企业官网建设流程全解析

QTextBrowser 更新最后一行，难点从来不在写入新文本，而在 QTextCursor 没对准时新内容会落到旧位置。TaoToken 在这里只负责通道：打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建一把 API Key，把 Codex 的 Base URL 填成 https://taotoken.net/api，之后同一个 update_row 问题，文本模式和 HTML 模式都能反复让 Codex 帮你核对光标落点，不必在多个厂商的 Key 之间来回切换。

很多人第一次写这个功能，脑子里想的是「把最后一行替换掉」，手上写的却是「往末尾追加一段」。跑起来看着像是对的，日志刷到第二十条就开始乱：新内容出现在旧内容上面，HTML 模式下还残留半截闭合标签。Qt 没有给你一个 replaceLine 之类的方法，你能用的只有光标：选中、删除、退回正确位置、再写入。这四个动作里，删除和写入都好理解，最容易翻车的是「退回哪里」。文本模式要退回行首，HTML 模式要退回文档末尾，两个方向刚好相反，写反了就会出现那种「删的是这一行、插的是另一行」的现象。

1. QTextBrowser 为什么必须靠 QTextCursor 才能更新一行

1.1 没有 update 接口，只有「删了再写」

QTextBrowser 继承自 QTextEdit，定位是只读展示控件。它提供了 setPlainText、setHtml、append、insertPlainText、insertHtml，但没有任何一个方法叫「替换第 N 行」。原因也很直白：控件内部维护的是 QTextDocument，文档由若干 block 组成，控件层面暴露的是「整篇设置」和「在光标处插入」这两类操作，行级的定位工作被下放给了 QTextCursor。

所以更新一行的通用套路是固定的：用 textCursor() 拿到当前光标，用 select() 把目标范围选出来，removeSelectedText() 把这段内容抹掉，再把光标挪到正确的落点，最后用 insertPlainText 或者 append 把新内容写进去。整条链路上只要有一环落点不对，结果就不对，而且不一定报错——它只是安静地把内容插错地方，这种 bug 比抛异常难查得多。

1.2 文本模式和 HTML 模式是两套语义

文本模式操作的是「行」，用的是 LineUnderCursor，配套方法是 insertPlainText。HTML 模式操作的是「块」，用的是 BlockUnderCursor，配套方法是 append。这两个词的区别不是命名习惯，而是文档结构决定的。

在 QTextDocument 里，block 是段落级单位。你 append 一段带<p>的 HTML，它就变成一个独立 block。如果此时用 LineUnderCursor 去选，遇到一个被自动换行拆成三行的长段落时，选中的只是其中一行，删掉之后段落里会留下一个空洞，视觉上就是「这一行缺了一块」。

1.3 光标错位后的三种典型症状

第一种，新内容插在旧行上方。这通常是删除后没有 moveCursor(StartOfLine)，光标停在选择区的起始位置，而选择方向恰好是从后往前，于是插入点落在了上一行末尾。

第二种，HTML 模式删完只剩半行。这多半是用了 LineUnderCursor 去处理富文本段落，标签被切开，浏览器再渲染时就把后面的闭合标签吞掉了。

第三种，连续更新时顺序倒过来。这种最隐蔽：第一次更新正常，第二次的内容跑到第一次前面。原因是 append 之后光标没有 moveCursor(End)，后面基于光标位置的选择又选中了旧块。下面两个章节会分别把这两套写法拆开。

2. 在 ~/.codex/config.toml 里把 Codex 的模型通道切到 TaoToken

2.1 先去模型广场确认 Key 和模型 ID

打开 TaoToken 完成注册登录，在控制台里创建一把 API Key，后面统一用占位符 YOUR_API_KEY 表示。同时到模型广场看一眼当前可用的模型 ID，把那个字符串原样记下来——不要凭印象写，也不要抄别人博客里的旧名字，模型列表是会变的，以页面上当时的展示为准。

Key 拿到之后先别急着改配置，可以先在模型对话页里发一条测试消息，确认这把 Key 是通的。这一步花不了两分钟，但能把「Key 本身有问题」和「配置文件写错了」这两类故障提前分开，省掉后面一大堆来回猜测。

2.2 config.toml 的 model_provider 和 base_url 怎么填

Codex 的全局配置在 ~/.codex/config.toml。要换供应商，核心是两件事：指定走哪个 provider，以及这个 provider 的 base_url 指向哪里。注意 base_url 末尾不要带 /v1，这里填的是接入地址本身。

model = "YOUR_MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

配置里的 env_key 是「环境变量名」，不是 Key 本身。所以还需要在 shell 里把它导出：

export TAOTOKEN_API_KEY=YOUR_API_KEY

想让它长期生效，就把这一行写进 ~/.zshrc 或 ~/.bashrc，重新开一个终端再跑 Codex。有一点要特别提醒：Codex 用的是自己的 provider 体系，不要把 Claude Code 那套 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 变量塞到 Codex 这边来，两套变量互不认识，混着填只会得到一个「找不到凭证」的报错。

2.3 先验证通道，再让它碰你的业务代码

配置改完之后，先拿一个和项目无关的问题试水，比如让 Codex 解释一段 QTextCursor 的选择逻辑，看它能否正常返回。确认能返回之后再做下一步。

注意：Codex 不能连上你本地的 Python 环境、PyQt 运行时或者任何生产机器去执行代码。它只能生成、解释、对照代码；跑脚本、看 traceback、截图结果这些动作必须由你在本地完成，然后把输出贴回对话让它继续分析。

3. 文本模式：LineUnderCursor 选中、删除、再 insertPlainText

3.1 文本版 update_row 的完整写法

先把最小可用版本写出来，再考虑边界情况。下面这段是文本模式下的更新逻辑，PyQt5 和 PySide2 的写法基本一致，只需要改导入路径。

from PyQt5 import QtGui, QtWidgets class LogView(QtWidgets.QWidget): def __init__(self): super().__init__() self.textBrowser = QtWidgets.QTextBrowser(self) def update_row_text(self, msg: str) -> None: browser = self.textBrowser cursor = browser.textCursor() # 1. 选中光标所在的那一行 cursor.select(QtGui.QTextCursor.LineUnderCursor) # 2. 抹掉这一行的内容 cursor.removeSelectedText() # 3. 把插入点退回行首 browser.moveCursor(QtGui.QTextCursor.StartOfLine, QtGui.QTextCursor.MoveAnchor) # 4. 写入新内容 browser.insertPlainText(msg) # 5. 顺手把光标推到末尾，方便下一次操作 browser.moveCursor(QtGui.QTextCursor.End)

顺序是有讲究的。第 1 步和第 2 步负责「清空位置」，第 3 步负责「对准落点」，第 4 步才写内容。如果跳过第 3 步，插入点会停在选择区的起始端，一旦你这次的选择范围覆盖了整行，插入点往往跑到上一行的末尾，于是新消息显示在旧消息上面。很多「更新变成了往上插一行」的反馈，根源就在这。

3.2 多行消息和空行的处理

insertPlainText 是能插入换行的，传进去的\n会被当成块分隔符。所以如果 msg 本身是多行文本，更新完之后文档里会多出几个 block，下一次再调 update_row_text，select(LineUnderCursor) 只会命中其中一行，剩下的残留就会被留在原地。这类问题的表现是「更新几次之后日志越来越长，旧的半截内容还在」。

比较稳妥的做法是在写入前把消息规范化：要么把多行压成单行，要么明确按行拆成多条记录调用多次。再配合一个简单判断，只有当前 block 就是最后一个 block 时才走「替换」逻辑，否则直接 append：

def is_last_block(self) -> bool: doc = self.textBrowser.document() return self.textBrowser.textCursor().blockNumber() == doc.blockCount() - 1

3.3 把这个报错贴给 Codex，让它对着 traceback 改

光说「我的光标位置不对」这种描述，Codex 只能猜。有效的做法是把上下文、复现步骤、实际输出和期望输出一起给它。可以照着下面这个结构提问：

环境：Python 3.11 + PyQt5，QTextBrowser 作为日志窗，只保留最后一行。 目标：每次来新消息时替换最后一行，而不是往后面追加。 现状：连续调用两次之后，第二条消息显示在第一条上面。 相关代码：（粘贴 update_row_text 全文） 实际输出：（粘贴 QTextBrowser 里两行文本的实际顺序） 日志：（粘贴 traceback，没有就写"无异常"）

拿到这种输入之后，它通常能直接指出「removeSelectedText 之后缺少 StartOfLine 归位」或者「moveCursor 用错了 MoveMode」。你在本地跑一遍改后的版本，把新的输出再贴回去，比一次问一大段模糊描述要快得多。

4. HTML 模式：BlockUnderCursor 删块后 append 必须回 End

4.1 HTML 版 update_row 的写法

HTML 模式下换成了块级选择加 append，多出来的关键一步是「先把光标挪到末尾再删」。原文的写法是在 append 之后再 moveCursor(End)，但如果你希望「更新的永远是最后一行」，那在删除之前就该先归位一次，否则删掉的可能是历史某一块，而新内容加在文档末尾，两边对不上。

from PyQt5 import QtGui, QtWidgets class HtmlView(QtWidgets.QWidget): def __init__(self): super().__init__() self.textBrowser = QtWidgets.QTextBrowser(self) def update_row_html(self, msg: str) -> None: browser = self.textBrowser # 1. 光标先归位到文档末尾，保证操作对象是最后一块 browser.moveCursor(QtGui.QTextCursor.End) cursor = browser.textCursor() # 2. 选中当前所在的整个块 cursor.select(QtGui.QTextCursor.BlockUnderCursor) # 3. 删除该块内容 cursor.removeSelectedText() # 4. 追加新的 HTML 内容 browser.append(msg) # 5. 再次回到末尾，方便下一次调用 browser.moveCursor(QtGui.QTextCursor.End)

第 5 步看着像多余，其实是防错关键。append 内部会把内容加到文档尾部，但光标位置并不一定跟着走。如果调用完不归位，下一次进来时 textCursor() 还停在旧位置，第 2 步选中的就是老块，于是出现「删上面、加下面」的错位。

4.2 文本和 HTML 混用时容易忽略的三件事

第一件，setPlainText 和 setHtml 都会重置整个文档并把光标放到开头，一秒前还在末尾，调用之后就跑回第一行了。如果你用整篇重刷的方式做 UI 刷新，很容易出现滚动条跳回顶部、日志只剩最后一条的情况，这类问题跟光标逻辑无关，是刷新策略选错了。

第二件，纯文本和富文本的转义规则不一样。往 append 里塞内容时，&、<、>会被当作标签解析，得先做转义；反过来，用 insertPlainText 写入带标签的字符串，标签会被原样显示成文字。判断标准很简单：内容的来源是什么，就用对应的方法写入。

第三件，QTextBrowser 只能在 GUI 线程里更新。消息如果来自工作线程或网络回调，必须通过信号槽转发到主线程，否则表面上看是「偶尔丢一行」，实际是跨线程操作控件导致的未定义行为。这一点在自己写日志窗时特别容易踩。做完这些之后，把两套代码合并到一个文件里，让 Codex 检查一遍两种模式的调用时机是否互斥，通常能再挖出一两个隐藏分支。

5. 通道切完之后，怎么确认 Codex 给的是对的光标逻辑

5.1 先分清是通道问题还是代码问题

切换供应商后遇到报错，先判断它属于哪一类。凭证类错误通常表现为 401 或者「找不到 API key」，检查方向是环境变量名和 config.toml 里的 env_key 是否一致、有没有重新开终端。路径类错误表现为 404 或提示请求路径异常，八成是 base_url 后面多写了 /v1，把它去掉就行——填进工具的地址是 https://taotoken.net/api，末尾不带版本段。模型类错误会直接告诉你模型不存在，这时候回模型广场核对 ID 拼写，不要靠记忆去补。

代码类问题不会抛异常，它只体现在输出结果上。判断方法是：让 Codex 解释你贴过去的那段 update_row，看它描述的光标落点和你预期的是否一致。如果它说的落点和实际现象对不上，说明它缺上下文，把 QTextBrowser 里更新前后的实际内容一并贴给它。

5.2 对着现象逐条排查

更新后内容出现在上一行：检查删除之后有没有 moveCursor(StartOfLine)，以及插入前光标是不是还在原位置。

HTML 模式删完留下孤立标签：检查是否误用了 LineUnderCursor 处理富文本，改成 BlockUnderCursor 再试。

连续更新顺序颠倒：检查 append 之后有没有 moveCursor(End)，以及下一次进入时是否又从头选了旧块。

滚动位置频繁跳动：检查有没有在每次更新时调 setHtml 或 setPlainText 整篇重刷，改成块级局部更新即可。

5.3 去控制台对一下这次调用有没有记上

配置验证通过、代码也跑顺之后，建议回到控制台看一眼这几轮追问的用量记录，确认请求确实走的是新通道，而不是你以为切了、实际上还在读旧的环境变量。这次调用如果记上了，说明从 config.toml 到 Key 到模型 ID 这条链路是通的。

想快速确认模型 ID 和回复质量，可以去 TaoToken 模型对话 用同一把 Key 发一条消息；如果打算把这种「贴报错、要补丁」的用法长期跑下去，可以打开 Coding Plan 看看套餐够不够用。新的 Key 在 控制台 API Keys 里创建，环境变量的完整对照表在 Claude Code 接入文档，如果哪天要把同一套通道挪到 Claude Code 上用，那份文档可以直接照抄。

最后留一句实在的提醒：QTextBrowser 的光标逻辑，本质上是拿「位置」换「状态」，代码里每一个 moveCursor 都在改状态机，所以改动之后一定要连续调三次以上，单次正常不代表顺序正确。至于让 Codex 帮忙，它的价值在于对着你的 traceback 快速定位到哪一步落点错了，真正跑和看结果这一步，还是得在你本地完成。