1. QTextDocument 富文本编辑器里加 AI 排版卡在哪一步QTextDocument 是 Qt 里处理富文本的核心类能存段落、表格、图片还能直接导出 HTML、Markdown 和 PDF。如果你正在做 Qt 桌面端富文本编辑器想给文档加一个「AI 辅助排版」或「一键摘要」按钮大概率会卡在同一个地方文档模型、光标编辑、布局渲染这三块本身不难难的是 AI 能力怎么接进来。我见过不少项目是这么干的在 QTextEdit 旁边放一个输入框用户点「AI 排版」后代码里硬编码一个模型地址和 Key然后拼一段 prompt 发出去。跑通一次没问题但一旦要换模型、加摘要、加多语言润色Key 就散落在三四个文件里改一次要重新编译。更麻烦的是团队里不同人用的模型不一样有人用这个有人用那个最后代码里全是 if-else。这篇要解决的就是这个链路问题。核心思路是QTextDocument 负责文档结构和渲染QTextCursor 负责把 AI 返回的内容插到正确位置而所有 AI 调用统一走 TaoToken 的 Key 和 API 通道。这样你只需要维护一份配置模型切换、摘要、排版润色都从同一个入口走。适合谁看有 Qt/C 基础、正在做桌面端富文本编辑器、想把 AI 能力接进文档流的开发者。不需要你之前接过任何大模型 API跟着配置走就行。下面按「文档模型 → 光标编辑 → 布局渲染 → 接入 AI → 验证 → 排障」的顺序展开每一段都有可复制的代码。重点放在第 3 节的配置和第 4 节的验证这两块是能不能跑起来的关键。2. 用 TaoToken 统一 Key 打通 Qt 富文本的 AI 调用入口先说清楚 TaoToken 在这个链路里扮演什么角色。你可以把它理解成一个统一的 API 网关不管底层是哪个模型你拿到的都是一套 Base URL Key Model ID 的组合。对 Qt 项目来说这意味着你不需要在代码里区分「这个模型用这个地址、那个模型用那个地址」只需要在配置里改 Model ID。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 用。Key 在控制台的 API Keys 页面生成生成后复制出来后面配置里会用到。为什么要在 QTextDocument 场景里强调统一 Key因为富文本编辑器的 AI 需求是碎片化的用户可能选中一段文字要「润色」可能整篇文档要「摘要」可能插入表格后要「生成表头」。如果每个功能都单独配一套 Key维护成本会指数级上升。统一入口之后你只需要在文档级别维护一个配置对象所有 AI 操作都从它取参数。具体到 Qt 代码里我建议把配置抽成一个单独的类比如AiConfig里面存 Base URL、Key、Model ID 三个字段。QTextDocument 本身不直接持有网络请求而是通过一个AiService类来调用。这样文档模型和 AI 调用解耦测试的时候也好替换。还有一个实际收益QTextDocument 支持contentsChanged信号你可以在文档内容变化时触发自动摘要或格式建议。如果 AI 调用是统一的这个信号处理函数里只需要调一次AiService::summarize()不用关心底层模型。这就是「统一 Key 打通链路」的真正含义——不是省几行代码而是让文档事件和 AI 能力之间没有中间层。3. 可复制的 QTextDocument 初始化与 AI 配置片段这一节给两份配置一份是 QTextDocument 的初始化与 QTextCursor 插入片段一份是 AI 调用的 JSON 配置。两份都按实际项目路径写你直接改路径就能用。先看文档初始化。假设你的项目结构是src/editor/document.cpp头文件在include/editor/document.h。初始化代码// src/editor/document.cpp #include editor/document.h #include QTextDocument #include QTextCursor #include QTextCharFormat #include QTextBlockFormat void EditorDocument::initDocument() { m_doc new QTextDocument(this); m_doc-setDefaultFont(QFont(Microsoft YaHei, 11)); m_doc-setDocumentMargin(16); m_doc-setUndoRedoEnabled(true); // 连接内容变化信号用于触发 AI 摘要 connect(m_doc, QTextDocument::contentsChanged, this, EditorDocument::onContentsChanged); } void EditorDocument::insertAiResult(const QString text, int position) { QTextCursor cursor(m_doc); cursor.setPosition(position); QTextCharFormat fmt; fmt.setForeground(QColor(#1a73e8)); fmt.setFontWeight(QFont::Normal); QTextBlockFormat blockFmt; blockFmt.setLeftMargin(12); blockFmt.setBackground(QBrush(QColor(#f5f8ff))); cursor.insertBlock(blockFmt); cursor.insertText(text, fmt); }这段代码里insertAiResult就是 AI 返回内容落地的位置。注意cursor.insertBlock(blockFmt)会新起一个段落这样 AI 生成的内容和原文有视觉区分。position参数可以从当前光标位置取也可以从选区末尾取。再看 AI 配置。建议放在config/ai_config.json用 QJsonDocument 读取{ base_url: https://taotoken.net/api, api_key: sk-你的Key从控制台复制, model_id: claude-sonnet-4-20250514, timeout_ms: 30000, max_tokens: 2048 }读取代码// src/ai/ai_config.cpp #include QFile #include QJsonDocument #include QJsonObject bool AiConfig::load(const QString path) { QFile file(path); if (!file.open(QIODevice::ReadOnly)) { qWarning() 无法打开配置文件: path; return false; } QJsonDocument doc QJsonDocument::fromJson(file.readAll()); QJsonObject obj doc.object(); m_baseUrl obj[base_url].toString(); m_apiKey obj[api_key].toString(); m_modelId obj[model_id].toString(); m_timeout obj[timeout_ms].toInt(30000); return !m_baseUrl.isEmpty() !m_apiKey.isEmpty() !m_modelId.isEmpty(); }三件套齐了Base URL 是https://taotoken.net/apiKey 从控制台拿Model ID 按你实际用的填。如果你用 Claude Code 做辅助开发配置方式类似但走的是 Anthropic 兼容通道Base URL 和 Key 的填法在接入文档里有说明。请求部分用 QNetworkAccessManager拼一个标准的 chat completions 请求void AiService::requestSummary(const QString plainText) { QNetworkRequest req(QUrl(m_config.baseUrl() /v1/chat/completions)); req.setHeader(QNetworkRequest::ContentTypeHeader, application/json); req.setRawHeader(Authorization, Bearer m_config.apiKey().toUtf8()); QJsonObject body; body[model] m_config.modelId(); body[max_tokens] m_config.maxTokens(); QJsonArray messages; QJsonObject sysMsg; sysMsg[role] system; sysMsg[content] 你是文档排版助手只输出摘要正文不要解释。; messages.append(sysMsg); QJsonObject userMsg; userMsg[role] user; userMsg[content] 请为以下文档生成 100 字以内摘要\n plainText; messages.append(userMsg); body[messages] messages; QNetworkReply *reply m_nam-post(req, QJsonDocument(body).toJson()); connect(reply, QNetworkReply::finished, this, [this, reply]() { onSummaryReply(reply); }); }这里的关键是Authorization头用 Bearer 格式Base URL 后面拼/v1/chat/completions。如果你的项目里用的是 Codex 的auth.json风格配置字段名可能不同但 Base URL 和 Key 的对应关系是一样的。4. 编译运行后验证富文本渲染与接口调用配置写完之后怎么确认真的跑通了分两步验证先验证 QTextDocument 渲染再验证 AI 接口调用。第一步渲染验证。在main.cpp里加一段最小测试#include QApplication #include QTextEdit #include editor/document.h int main(int argc, char *argv[]) { QApplication app(argc, argv); QTextEdit editor; EditorDocument doc; doc.initDocument(); doc.insertAiResult(这是 AI 生成的摘要内容用于验证渲染。, 0); editor.setDocument(doc.document()); editor.resize(800, 600); editor.show(); return app.exec(); }编译运行后你应该看到窗口里有一段带浅蓝背景、左边距 12px 的文字。如果背景没出来检查QTextBlockFormat::setBackground是否在insertBlock之前调用如果字体不对检查setDefaultFont是否在文档创建后立即调用。第二步接口验证。在AiService里加一个测试方法直接发一个最短请求void AiService::testConnection() { QNetworkRequest req(QUrl(m_config.baseUrl() /v1/chat/completions)); req.setHeader(QNetworkRequest::ContentTypeHeader, application/json); req.setRawHeader(Authorization, Bearer m_config.apiKey().toUtf8()); QJsonObject body; body[model] m_config.modelId(); body[max_tokens] 16; QJsonArray messages; QJsonObject msg; msg[role] user; msg[content] 回复 OK 两个字母即可; messages.append(msg); body[messages] messages; QNetworkReply *reply m_nam-post(req, QJsonDocument(body).toJson()); connect(reply, QNetworkReply::finished, this, [reply]() { if (reply-error() QNetworkReply::NoError) { QJsonDocument resp QJsonDocument::fromJson(reply-readAll()); QString content resp.object()[choices] .toArray()[0].toObject()[message] .toObject()[content].toString(); qDebug() 接口返回: content; } else { qDebug() 请求失败: reply-errorString(); } reply-deleteLater(); }); }运行后看控制台输出。如果打印出「接口返回: OK」说明 Base URL、Key、Model ID 三件套都对。如果报 401往下看第 5 节。验证通过后把testConnection的调用去掉换成正式的requestSummary。这时候你在编辑器里选中一段文字点「AI 摘要」应该能看到摘要内容以新段落形式插入到文档末尾。整个链路就通了QTextDocument 管结构QTextCursor 管插入TaoToken 管调用。5. 本篇常见报错排查401、local proxy failed、reading choices这一节列几个实际会撞到的报错每个都给排查路径。401 Unauthorized。最常见的原因是 Key 没带对。检查三处Authorization头是不是Bearer开头注意 Bearer 后面有一个空格Key 是不是从控制台完整复制有些编辑器会截断长字符串Base URL 是不是https://taotoken.net/api不要多写或少写斜杠。如果 Key 里包含特殊字符确认在 JSON 里没有被转义。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或端口不对。Qt 的 QNetworkAccessManager 默认会读系统代理设置。如果你不需要代理在main.cpp里加QNetworkProxy::setApplicationProxy(QNetworkProxy::NoProxy);。如果你确实需要走代理确认代理地址和端口和实际运行的一致。注意不要用任何不合规的网络工具这里说的代理仅指企业内网正常的 HTTP 代理。reading choices 报错。这个一般是你解析返回 JSON 时choices数组为空或结构不对。先打印完整返回内容qDebug() reply-readAll();。常见原因是请求体里messages格式不对比如 role 写成了user但 content 是数组而不是字符串。另一个原因是max_tokens设得太小模型还没输出就被截断。把max_tokens调到 256 以上再试。OAuth 相关报错。如果你用的是 Claude Code 或类似工具可能会遇到 OAuth token 过期。这种情况不是 TaoToken 的 Key 问题而是工具本身的登录态失效。重新走一遍工具的登录流程或者改用 API Key 方式接入。在 Qt 项目里建议统一用 API Key不要混用 OAuth。编译期报错QTextDocument 未定义。检查.pro文件里有没有加QT guiQTextDocument 在 QtGui 模块里。如果用 CMake确认find_package(Qt6 COMPONENTS Gui)和target_link_libraries(your_target PRIVATE Qt6::Gui)都写了。渲染出来是乱码。QTextDocument 默认按 UTF-8 处理但如果你从文件读内容确认用QString::fromUtf8()转换。如果是从网络返回的 JSON 里取字符串QJsonDocument 已经处理了编码直接用toString()就行。排查顺序建议先看 HTTP 状态码再看返回体最后看本地配置。大部分问题出在 Key 和 Base URL 的拼接上把这两个打印出来对比一下往往一眼就能看出问题。6. 把 AI 能力接进文档流之后下一步做什么链路通了之后你可以把 AI 调用挂到更多文档事件上。比如QTextDocument::contentsChange信号里当用户连续输入超过 200 字时自动触发一次摘要建议或者当用户插入表格后自动请求生成表头文案。这些都不需要改底层配置只需要在AiService里加方法。如果你打算长期在 Qt 项目里做 AI 辅助编辑建议把 Coding Plan 用起来它适合需要持续调用、多模型切换的场景。模型对话页面可以用来快速验证 prompt 效果不用每次都编译 Qt 程序。接入文档里有完整的参数说明和错误码对照遇到不确定的字段先去那里查。最后给一个实用技巧在AiConfig里加一个enabled字段默认 false。这样在 CI 环境或没有配置 Key 的机器上AI 功能自动降级为普通编辑器不会因为网络请求失败导致整个程序卡住。这个开关在团队协作时特别有用不是每个人都需要配 Key。
