1. 从手动改 conref 到让 Planner 自己规划Oxygen 技术写作者的 Agentic 转型现场如果你每天的工作是在 Oxygen XML Editor 里打开一个几百个文件的 DITA 项目手动把conref一个个换成conkeyref那你大概已经体会过那种“改到第 37 个文件时开始怀疑人生”的感觉。Planner 聊天模式要解决的正是这类问题它不是帮你补全一句话而是先读懂整个userguide.ditamap的结构再生成一份多步骤计划然后委派子代理去执行。适合谁适合维护大规模 DITA 文档集、需要批量翻译、批量重构引用关系的技术写作者和文档工程师。但这里有个现实问题Planner 模式背后要调用大模型而 Oxygen AI Positron 默认走的是官方通道点数消耗快、模型选择受限。我在实际项目里更习惯用 TaoToken 统一 Key 把模型调用收口——一个 Key 覆盖多个模型Base URL 固定配置一次就能在 Oxygen 的 MCP 工具链里复用。下面我会把从拿 Key 到在 Oxygen 侧验证 Planner 会话是否真正调通的完整路径写清楚包括可复制的 JSON 配置、验证请求的命令以及几个我踩过的报错。先明确一个认知Planner 聊天模式的“代理化”不是魔法。它的工作逻辑是“先规划、后执行、可审核”。你给它一句“翻译当前文件夹下所有 .dita 文件”它会先扫描项目结构生成一份步骤清单比如识别文件列表 → 提取可翻译单元 → 调用翻译子代理 → 回写并保留标签结构。你批准后它才逐步执行每一步的工具调用和结果都会展示出来。这意味着你的 Key 和 Base URL 必须稳定否则规划到一半断了整个会话就废了。所以这篇内容的核心不是复述 Planner 有多强而是交付一条可复制的接入通道让你在 Oxygen 里真正把 Planner 会话跑起来并且能验证它是否生效。2. TaoToken 统一 Key 与 API 通道的前置准备Base URL、Key、Model ID 三件套在 Oxygen 里配置任何 AI 功能本质上都是填三个东西Base URL、API Key、Model ID。Planner 模式也不例外只是它多了一层 MCP 工具选择器的逻辑。我试过把这三件套先在一个独立环境里验证通过再填进 Oxygen这样排障时能快速定位是通道问题还是编辑器配置问题。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。Key 需要在控制台生成地址是https://taotoken.net/console生成后复制保存页面关闭后不再完整显示。模型对话调试入口在https://taotoken.net/models你可以先在那里发一条测试消息确认 Key 和模型 ID 能通再去配 Oxygen。Model ID 这块要特别注意Oxygen AI Positron 的 Planner 模式对模型能力有要求因为它要做多步骤规划和工具调用。如果你填了一个不支持 function calling 的模型Planner 会在生成计划阶段就报错典型表现是返回内容里没有结构化的步骤而是一段普通文本。我建议先用一个明确支持工具调用的模型 ID 做验证跑通后再按项目需求切换。三件套的对应关系可以这样记配置项值获取位置Base URLhttps://taotoken.net/api固定不加 UTMAPI Keysk-开头的一串控制台生成Model ID具体模型标识模型列表或文档这里有个容易混淆的点TaoToken 官网首页是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end但 API 调用只用https://taotoken.net/api不要把首页地址填进 Base URL否则会返回 404 或 HTML 内容Oxygen 解析时会报 JSON 解析失败。另外如果你用的是 Claude Code 或 Codex 这类命令行工具做辅助验证它们的配置文件格式不同。Claude Code 走的是 Anthropic 兼容通道Codex 走的是auth.json。但在 Oxygen 场景下你主要面对的是编辑器内的 MCP 配置所以下面我重点给 Oxygen 侧的 JSON 片段。3. 可复制配置Oxygen 侧 MCP 工具链与 Planner 会话的 JSON 片段Oxygen XML Editor 28.1 的 Planner 模式依赖 MCP 工具选择器来启用或禁用特定工具。你要做的第一件事是找到 AI Positron 的配置文件位置。在 Windows 上通常在%APPDATA%\Oxygen XML Editor 28.1\下macOS 在~/Library/Application Support/Oxygen XML Editor 28.1/。里面会有一个与 AI 相关的配置目录具体文件名随版本略有差异但结构一致。下面是一个可复制的 JSON 配置片段用于把模型调用指向 TaoToken 通道。注意路径和字段名要与你的实际文件一致不要直接覆盖整个文件而是合并到现有配置中{ ai: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, modelId: 你的模型ID, planner: { enabled: true, maxPlanningSteps: 12, requireApproval: true, toolsSelector: { enabledTools: [ file-system, dita-map-parser, conref-refactor, translation-agent ], disabledTools: [] } } } }这段配置里几个关键字段解释一下。provider填openai-compatible是因为 TaoToken 的 API 通道兼容 OpenAI 格式Oxygen 能直接识别。baseUrl就是前面说的https://taotoken.net/api不要加斜杠结尾也不要加任何查询参数。planner.enabled设为true才会在聊天模式里出现 Planner 选项。requireApproval建议保持true这样每一步执行前你都能审核避免子代理误改整个项目。toolsSelector是 Planner 模式的核心定制点。你可以根据任务类型启用或禁用工具。比如做翻译任务时启用translation-agent和file-system做引用重构时启用conref-refactor和dita-map-parser。禁用不需要的工具能减少子代理的无效调用也能降低点数消耗。如果你同时用 Cline 或 CC Switch 做辅助开发它们的 MCP 配置格式类似但字段名可能不同。Cline 的 MCP 配置通常在cline_mcp_settings.json里结构是mcpServers对象。CC Switch 则是在切换配置时写入不同的 Base URL 和 Key。无论哪种三件套的逻辑不变Base URL 指向https://taotoken.net/apiKey 用控制台生成的Model ID 填支持工具调用的。配置写完后重启 Oxygen让 AI Positron 重新加载。如果重启后 Planner 选项没出现先检查 JSON 是否有语法错误比如多余的逗号或引号不匹配。Oxygen 的日志里会记录配置加载失败的原因位置在Help Show Log里。4. 验证 Planner 会话调用与 XML/DITA 任务编排是否生效的具体检查动作配置填完不等于生效。你需要一套可执行的验证动作确认 Planner 真的在调用你配置的通道而不是回退到默认通道或静默失败。第一步在 Oxygen 里打开一个 DITA 项目确保有userguide.ditamap和若干.dita文件。然后打开 AI Positron 聊天面板切换到 Planner 模式。输入一条低风险指令比如“列出当前 ditamap 中所有 topic 文件的路径”。这条指令不涉及修改适合验证规划能力。第二步观察返回内容。如果 Planner 正常工作你会看到它先输出一份计划类似“步骤 1解析 userguide.ditamap步骤 2提取 topicref 的 href 属性步骤 3汇总路径列表”。然后出现批准按钮。如果它直接返回一段普通文本没有结构化步骤说明模型没有走工具调用通道大概率是 Model ID 不支持 function calling或者 Base URL 填错了。第三步用命令行做独立验证。在终端里执行一条 curl 请求确认 TaoToken 通道本身是通的curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: 你的模型ID, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }如果返回 JSON 里有choices字段且内容为 OK说明通道正常。如果返回 401说明 Key 无效或没带上。如果返回local proxy failed或连接超时说明网络层有问题但注意不要使用任何非正规网络手段检查你的 DNS 和防火墙设置即可。第四步验证 DITA 任务编排。在 Planner 里输入“在当前文件夹的所有 .dita 文件中查找 conref 并替换为 conkeyref”。批准计划后观察它是否逐个文件展示工具调用。每个文件处理完检查文件内容是否真的被修改以及修改后 DITA 结构是否完整。如果某个文件报错Planner 会展示错误信息你可以据此判断是文件权限问题还是引用格式问题。第五步检查点数消耗。在 TaoToken 控制台的用量页面确认刚才的 Planner 会话产生了调用记录。如果没有记录说明 Oxygen 根本没走你配置的通道需要回到配置文件排查。这套验证动作跑完你就能确定 Planner 会话是否真正生效。实测下来最容易出问题的环节是 Model ID 和 Base URL 的匹配其次是 JSON 配置的字段名拼写。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照在 Oxygen 里接 TaoToken 通道报错信息往往比较隐晦。下面是我遇到过的几类典型错误和对应的排查方向。401 Unauthorized。这是最常见的。原因通常是 Key 没填对或者 Key 前面多了空格或者 Key 已经失效。检查配置文件里的apiKey字段确认是sk-开头且没有换行。如果 Key 是从控制台复制的注意不要复制到多余的空格。另外如果你在 Oxygen 里同时配置了多个 provider确认 Planner 用的是你改的那个。local proxy failed。这个报错通常出现在 Oxygen 尝试连接 Base URL 但网络层不通的时候。先确认baseUrl是https://taotoken.net/api没有多余路径。然后在终端用 curl 测试同一地址如果 curl 也失败说明是本地网络环境问题检查 DNS 解析和防火墙规则。注意不要使用任何非正规网络工具保持环境干净。reading choices 报错。这个错误说明 Oxygen 收到了响应但响应结构里没有choices字段。常见原因是 Base URL 填成了首页地址返回的是 HTML 而不是 JSON。另一个原因是 Model ID 填错了服务端返回了错误信息而不是正常的 completion 结构。检查 Base URL 和 Model ID确保与文档一致。OAuth 相关报错。如果你在配置里误开了 OAuth 模式而 TaoToken 通道用的是 API Key 认证就会报 OAuth 错误。检查配置文件里是否有authType或oauth字段如果有改成apiKey或直接删除该字段。Oxygen 的某些版本会默认尝试 OAuth需要手动覆盖。Planner 计划生成后不执行。这通常是因为requireApproval设为true但你没有点批准按钮或者toolsSelector里禁用了执行所需的工具。检查enabledTools列表确保包含了file-system和对应的任务工具。子代理调用超时。大规模项目里Planner 可能同时调用多个子代理如果某个子代理响应慢整个会话会卡住。可以在配置里调小maxPlanningSteps或者分批执行任务比如先处理一个文件夹再处理下一个。排查时建议按顺序来先 curl 验证通道再检查 Oxygen 配置最后看 Planner 会话日志。这样能快速缩小范围。6. 把 Planner 会话接入长期编码与 Agent 工作流CTA 与后续路径Planner 聊天模式在 Oxygen 里的价值不只是单次批量操作。它真正的意义是把技术写作者的日常工作流从“手动编辑”推向“代理化协作”。你可以把常用的 DITA 重构任务、翻译任务、引用检查任务固化成 Planner 的指令模板配合toolsSelector的工具组合形成一套可复用的 Agent 工作流。如果你打算长期在 Oxygen 里跑 Planner 会话建议把 TaoToken 的 Key 管理纳入日常流程。控制台可以生成多个 Key按项目或按任务类型区分这样用量统计更清晰。模型对话入口适合做单次调试确认某个 Model ID 是否支持工具调用。接入文档里有完整的 API 参数说明配置新工具时可以参考。对于需要长期编码和 Agent 协作的场景Coding Plan 提供了更稳定的通道配置适合把 Oxygen 的 Planner 会话和其他开发工具统一到同一个 Key 下。API Keys 页面则是管理所有 Key 的入口生成、禁用、查看用量都在那里。最后给一个实用技巧在 Oxygen 里跑 Planner 之前先用 Git 把当前项目提交一次。这样即使子代理改错了文件你也能快速回滚。Planner 的审批机制虽然能拦截大部分误操作但批量替换类任务还是留个后手更稳妥。