1. QTextBrowser 高亮与滚动错位：问题到底出在哪
如果你在用 QT 做读卡器、芯片测试工具，大概率会遇到这个场景：把一串 APDU 命令写进脚本文件，用 QTextBrowser 加载展示，然后开一个 ReadCardThread 线程按行执行，执行到哪行就把哪行标绿，同时让视图自动往下滚。听起来很顺，但真正跑起来你会发现——高亮的那一行和自动滚动停下来的位置，总是差一行。你点“开始测试”，第一行命令在执行，绿色却标在第二行；或者绿色标对了，视图却已经滚过头了。
这个问题的核心检索词就是 QT、QTextBrowser、加载脚本、脚本执行、动态展示。它适合谁？适合正在用 QT 写上位机、测试工具、自动化脚本执行器的开发者，尤其是那些已经跑通了文件读取和线程执行，但卡在“高亮和滚动不同步”这一步的人。我试过把 Codex 的 Base URL 改到 TaoToken，让它帮我逐行对照SetLineColor里findBlockByNumber(lineNum)和moveCursor(QTextCursor::Down)的调用顺序，才把问题拆清楚。
先说结论：错位通常不是单一原因，而是三个因素叠加——block 索引的基准不一致、moveCursor的副作用被忽略、以及repaint的时机和 ExtraSelection 的应用顺序。下面我会按“先配通 Codex 对照排查，再给可复制的修复配置，最后验证和排障”的顺序讲，你可以直接跟着做。
2. 前置：把 Codex 的 Base URL 改到 TaoToken
要让 Codex 帮你对照 QT 代码里的调用顺序，得先让它能稳定跑起来。我用的方式是走 TaoToken 的 API 接入，把 Codex 的 Base URL 指过去。这里注意两个细节：Base URL 填https://taotoken.net/api，不带/v1，也不加任何 UTM 参数；Key 在控制台创建。
先打开官网创建 Key：
https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=进去之后进控制台，路径是 console，创建 API Key 的页面在 api-keys。如果你后面要长期用 Codex 做编码和 Agent 任务，可以看 coding-plan；如果只是想先验证模型对话，用模型对话页面就行。接入文档在 doc，ClaudeCodeAnthropic 相关说明也有单独入口。
创建完 Key，把 Codex 的配置改成这样：
# Codex 配置片段 base_url = "https://taotoken.net/api" api_key = "sk-你的Key" model = "gpt-5-codex"注意base_url后面不要补/v1，很多错位排查失败就是因为多写了路径，导致请求 404 或者被重定向到错误端点。改完之后，你可以让 Codex 直接读你的ReadCardThread.cpp和SetLineColor函数，让它逐行分析findBlockByNumber和moveCursor的调用顺序。
3. 可复制配置：修复高亮与滚动错位的完整代码
3.1 先理解 block 索引和 lineNum 的基准差异
你的线程里emit runScriptLine(i)是从 0 开始递增的，i对应的是baList里的行号。而SetLineColor(int lineNum)里，你用findBlockByNumber(lineNum)去取 block。问题在于：QTextDocument的 block 数量和你按readLine()读出来的行数，在遇到空行、\r\n、文件末尾无换行符时，可能不一致。blockCount()返回的是文本块数量，回车符才算一个 block，如果脚本最后一行没有换行，最后一行可能不会被算成独立 block。
更关键的是moveCursor(QTextCursor::Down)这一句。它移动的是 QTextBrowser 自己的光标，而不是 ExtraSelection 里那个临时 cursor。你每次SetLineColor都调一次moveCursor(Down)，相当于每执行一行，视图光标就往下走一行。但你的高亮是基于lineNum直接定位 block 的，两者基准不同步，自然差一行。
3.2 修复版 SetLineColor：用 block 定位，不用 moveCursor 滚动
把滚动交给verticalScrollBar或者ensureCursorVisible，不要用moveCursor(Down)来兼职滚动。下面是可复制的修复版：
void ICTestTools::SetLineColor(int lineNum) { if (lineNum < 0 || lineNum >= extraSelections.size()) return; // 1. 上一行重置为黑色 if (lineNum > 0) { extraSelections[lineNum - 1].format.setForeground(Qt::black); } // 2. 当前行标绿，用 block 定位 QTextBlock block = loginDoc->findBlockByNumber(lineNum); if (!block.isValid()) return; QTextCursor cursor(block); cursor.select(QTextCursor::LineUnderCursor); extraSelections[lineNum].cursor = cursor; extraSelections[lineNum].format.setForeground(Qt::green); // 3. 应用 ExtraSelection ui.scriptTxt->setExtraSelections(extraSelections); // 4. 滚动：让当前 block 可见，而不是 moveCursor(Down) QTextCursor visibleCursor(block); ui.scriptTxt->setTextCursor(visibleCursor); ui.scriptTxt->ensureCursorVisible(); // 5. 重绘 ui.scriptTxt->repaint(); }这里的关键改动是：去掉moveCursor(QTextCursor::Down)，改用setTextCursor(block)加ensureCursorVisible()。ensureCursorVisible会保证当前 block 在可视区域内，但不会像Down那样每次强制下移一行，从而避免累积偏移。
3.3 线程侧：把行号和 block 对齐
线程里loadScript用readLine()逐行读，建议同时记录每行对应的 block 索引，或者在主线程初始化时用blockCount()重新校准。一个稳妥做法是：在on_startRunScript_clicked里，先按blockCount()重建extraSelections，而不是按lineCount。因为lineCount是你自己数的，blockCount()才是 QTextDocument 的真实块数。
void ICTestTools::on_startRunScript_clicked() { ui.scriptTxt->moveCursor(QTextCursor::Start); loginDoc = ui.scriptTxt->document(); loginDocNum = loginDoc->blockCount(); extraSelections.clear(); for (int i = 0; i < loginDocNum; i++) { QTextEdit::ExtraSelection sel; sel.cursor = QTextCursor(loginDoc->findBlockByNumber(i)); sel.cursor.select(QTextCursor::LineUnderCursor); sel.format.setForeground(Qt::black); extraSelections.append(sel); } ui.scriptTxt->setExtraSelections(extraSelections); ui.scriptTxt->repaint(); readCardThread.startThread(); }这样extraSelections的长度就和blockCount()一致，SetLineColor里的lineNum只要不超过blockCount()，就不会越界，也不会因为空行导致错位。
4. 验证请求：跑一遍看高亮和滚动是否同步
配置改完后，用一段带空行和注释的脚本验证。比如：
00 A4 04 00 07 A0 00 00 00 03 00 00 00 A4 00 00 02 3F 00 00 B0 00 00 10 00 B0 00 10 10注意第二行后面有空行，第三行是注释。跑起来后观察：第一行执行时绿色是否在第一行，视图是否只滚到第一行可见；第二行执行时绿色是否在第二行，视图是否跟着走；空行和注释行是否被跳过或正确标色。
如果你用 Codex 对照排查，可以把这段脚本和修复后的SetLineColor一起丢给它，让它检查findBlockByNumber的返回值是否和lineNum一一对应。Codex 在 TaoToken 上跑的时候，你可以直接问：“moveCursor(QTextCursor::Down)和ensureCursorVisible在这个场景下的副作用差异是什么？”它会给你逐行分析。
验证成功的标志是：绿色高亮始终落在正在执行的那一行，视图滚动不超前也不滞后，停止线程后高亮停在最后执行的行，不会多走一行。
5. 本篇常见错排查
5.1 高亮总是差一行
最常见的原因是moveCursor(QTextCursor::Down)在SetLineColor里被调用，导致视图光标每次都比高亮多走一行。去掉它，改用ensureCursorVisible。
5.2 最后一行高亮不到
检查脚本文件最后是否有换行符。如果没有，readLine()读出的行数和blockCount()可能差 1。可以在loadScript里补一个换行，或者在主线程用blockCount()重建extraSelections。
5.3 滚动条乱跳
不要用verticalScrollBar()->setValue(bar->value() + num)手动累加，因为每次setExtraSelections和repaint都可能改变滚动位置。用ensureCursorVisible让 QT 自己算。
5.4 高亮颜色不刷新
repaint()是同步重绘，但在某些平台上需要配合viewport()->update()。如果绿色不显示，试试ui.scriptTxt->viewport()->update()。
5.5 线程信号和主线程不同步
runScriptLine是跨线程信号，默认队列连接。如果SetLineColor执行太慢，信号会堆积。可以在SetLineColor开头加QCoreApplication::processEvents()，但更推荐把Sleep(200)调大一点，或者用QMetaObject::invokeMethod确保在主线程执行。
6. 接入与排障入口
如果你在配 Codex 对照排查时遇到接入问题，比如 Base URL 填错、Key 无效、请求超时，可以直接走 API Keys 和接入文档：
API Keys: https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 接入文档: https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite如果你只是想先验证模型能不能正确分析 QT 代码，用模型对话页面：
模型对话: https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite如果你后面要长期用 Codex 做编码和 Agent 任务，比如让它持续帮你改ReadCardThread和SetLineColor，可以看 Coding Plan：
Coding Plan: https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite控制台入口：
Console: https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewriteClaudeCodeAnthropic 相关：
ClaudeCodeAnthropic: https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite最后说一个我踩过的坑：findBlockByNumber在文档被修改后会失效，所以不要在SetLineColor里动态改文本。如果你需要在执行过程中插入日志，用单独的 QTextEdit 或者 QPlainTextEdit，不要动scriptTxt的 document。这样高亮和滚动才能一直同步。
