1. 为什么自动补全和进度通知总有一个是坏的先说一个我踩过的坑。去年给团队做一个代码审查助手前端接的是 OpenAI 兼容的 Completions 接口后端跑一个批量扫描任务。功能上线第一天就收到反馈补全框里输入py能弹出python但任务跑起来之后界面一直转圈用户不知道是死是活。我去查日志发现补全请求走的是/v1/completions任务进度走的是另一套 WebSocket 通道两边用的 Key 和 Base URL 还不一样一个配在环境变量里一个硬编码在配置文件里。结果就是补全正常、通知全丢。这件事让我意识到Completions 和通知机制其实是两套独立的交互模型。Completions 是典型的请求-响应客户端发一个带prompt或messages的请求服务端返回补全文本一问一答结束就结束。通知机制是单向推送服务端在处理长任务的过程中主动往客户端发进度、日志、状态变更客户端不需要为每条通知回一个响应。把这两套东西接在同一个通道上才能让 AI 编程工具既有输入提示又有实时反馈。这篇就围绕这个场景展开。我会用 TaoToken 作为统一的 Key 和 API 通道把 Completions 请求、进度上报、状态通知三类交互串起来。TaoToken 在这里的角色是提供一个 OpenAI 兼容的 Base URL 和统一的 Key让补全请求和通知回调走同一个入口不用在多个服务之间来回切换配置。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 后面所有配置都基于这两个地址。适合谁看正在给 IDE 插件、代码助手、Agent 工具接补全和进度反馈的开发者已经能跑通单次补全请求但长任务状态同步一直做不干净的团队以及想搞清楚 Completions 和通知机制边界的人。读完之后你应该能拿到一套可复制的 endpoint 配置、一段能跑的 curl 验证命令以及一份常见报错对照表。核心检索词先摆出来Completions 是补全请求的接口形态通知机制是服务端主动推送进度和状态的通道自动补全是用户在输入时触发的建议请求进度上报是长任务执行中的百分比回传状态通知是任务开始、完成、失败等生命周期事件的推送。这五个词贯穿全文后面每个章节都会落到具体配置上。2. TaoToken 前置统一 Key 与 Base URL 的接入点在动手写配置之前先把 TaoToken 这一层说清楚。很多人第一次接的时候会问我已经有补全接口了为什么还要套一层答案在于通道统一。补全请求和通知回调如果走不同的域名、不同的 Key排查问题时要同时看两套日志任何一个环节的鉴权失败都会让整条链路断掉。TaoToken 提供的是一个 OpenAI 兼容的入口补全请求发到https://taotoken.net/api/v1/completions通知相关的状态查询和回调也走同一个 Base URLKey 只用配一份。2.1 拿到 Key 和确认 Base URL第一步是拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key。建议按用途分开建一个给补全请求用一个给后台任务用方便后面做额度隔离和问题定位。创建完复制出来形如sk-开头的一串字符只显示一次丢了就重新建。Base URL 固定为https://taotoken.net/api注意这里不带 UTM 参数配置里写干净地址就行。补全的完整 endpoint 是https://taotoken.net/api/v1/completions对话式补全走https://taotoken.net/api/v1/chat/completions。这两个是后面 curl 验证要用的。2.2 环境变量与配置文件的位置我习惯把 Key 放在环境变量里不写进代码。Linux 和 macOS 下在~/.zshrc或~/.bashrc追加export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它的配置文件通常在~/.claude/settings.json或项目根目录的.claude/settings.json。里面要写全三件套Base URL、Key、Model ID。Model ID 按你实际用的模型填比如claude-sonnet-4-5或gpt-4o具体以控制台模型列表为准。配置片段长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意ANTHROPIC_BASE_URL这里填的是https://taotoken.net/api不要自己加/v1工具内部会拼。这一点很多人搞错加了/v1之后请求变成/v1/v1/messages直接 404。2.3 为什么通知机制也要走同一个通道通知机制本身是服务端到客户端的单向消息看起来和 Key 没关系。但实际工程里通知的触发往往依赖一次补全请求或任务提交。比如你发一个批量处理请求服务端返回一个task_id后续的进度通知都围绕这个task_id展开。如果提交请求走 A 通道、进度查询走 B 通道task_id的归属就对不上。统一到 TaoToken 之后提交和查询用同一个 Key服务端能正确关联任务和调用方。另外TaoToken 的 Coding Plan 适合长期跑编码和 Agent 任务的场景如果你的通知机制是给这类长任务做状态同步可以了解一下 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 里面有各语言的示例遇到字段对不上时先翻文档。3. 可复制配置Completions 请求与通知回调的完整片段这一章给可直接复制的配置。分三块补全请求的 JSON 体、通知回调的注册配置、以及一个把两者串起来的 settings 片段。路径和字段名都按实际能跑通的写你复制过去改 Key 就能用。3.1 Completions 请求体先看最基础的补全请求。用 curl 发一个curl https://taotoken.net/api/v1/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, prompt: def quick_sort(arr):\n , max_tokens: 128, temperature: 0.2, stream: false }字段说明model填控制台里可用的模型 IDprompt是补全的上下文代码补全场景通常把光标前的代码贴进来max_tokens控制返回长度补全场景别设太大128 到 256 够用temperature补全建议调低0.1 到 0.3 之间太高会给出离谱建议stream设 false 时一次性返回设 true 时逐 token 推送后者适合做打字机效果。对话式补全走另一个 endpointcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [ {role: system, content: 你是一个代码补全助手只返回补全的代码不要解释。}, {role: user, content: 补全这个函数def parse_json(s):} ], max_tokens: 256, temperature: 0.2 }3.2 通知回调的注册配置通知机制的核心是客户端先注册一个回调地址或令牌服务端在处理过程中往这个地址推送。以本地开发为例假设你的回调服务跑在http://localhost:8787/notify注册配置写成 JSON{ callback_url: http://localhost:8787/notify, events: [progress, status, log], progress_token: task-20250101-001, min_log_level: info }events里声明你关心哪几类通知progress是进度百分比status是任务生命周期log是服务端日志。progress_token是这次任务的唯一标识服务端推送时会带回来客户端据此判断是哪条任务。min_log_level控制日志等级设成info时debug级别的日志不会推过来避免刷屏。如果你用的是 Claude Code 或 Cline 这类工具它们的 MCP 配置里也有类似结构。以 Cline 的 MCP 配置为例在cline_mcp_settings.json里加{ mcpServers: { taotoken-notify: { command: node, args: [/path/to/notify-server.js], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL: gpt-4o } } } }这里同样要写全三件套Base URL、Key、Model ID。少任何一个MCP 服务启动时就会报鉴权失败或模型找不到。3.3 把补全和通知串起来的 settings 片段下面是一个完整的 settings 片段把补全请求和通知回调放在同一个配置里。以 VS Code 插件为例路径是项目根目录的.vscode/settings.json{ taotoken.baseUrl: https://taotoken.net/api, taotoken.apiKey: sk-你的Key, taotoken.completionModel: gpt-4o, taotoken.completionMaxTokens: 256, taotoken.completionTemperature: 0.2, taotoken.notify.enabled: true, taotoken.notify.callbackUrl: http://localhost:8787/notify, taotoken.notify.events: [progress, status], taotoken.notify.progressTokenPrefix: vscode-task- }completionModel和notify两块共用同一个baseUrl和apiKey这是统一通道的关键。progressTokenPrefix给每个任务加前缀避免多个窗口的任务 ID 撞车。3.4 通知回调服务的最小实现回调服务收到推送后要做什么最小实现是解析 JSON按event字段分流。用 Node.js 写一个// notify-server.js const http require(http); const server http.createServer((req, res) { if (req.method ! POST || req.url ! /notify) { res.writeHead(404); return res.end(); } let body ; req.on(data, chunk { body chunk; }); req.on(end, () { const msg JSON.parse(body); switch (msg.event) { case progress: console.log([进度] ${msg.progress}/${msg.total} ${msg.message || }); break; case status: console.log([状态] ${msg.status} task${msg.progress_token}); break; case log: console.log([日志] ${msg.level} ${msg.data}); break; default: console.log([未知事件], msg); } res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ ok: true })); }); }); server.listen(8787, () { console.log(通知回调服务已启动: http://localhost:8787/notify); });跑起来node notify-server.js。这个服务只做打印真实项目里可以在这里更新前端状态、写数据库、触发下一步动作。4. 验证请求用 curl 跑通补全与通知链路配置写完不算完得验证。这一章给具体的验证动作从补全响应到通知回调一步步确认链路是通的。4.1 验证补全响应先确认补全接口能返回。用第 3 章的 curl 命令把$TAOTOKEN_API_KEY换成实际 Key。正常返回长这样{ id: cmpl-xxx, object: text_completion, created: 1735689600, model: gpt-4o, choices: [ { text: if len(arr) 1:\n return arr\n pivot arr[len(arr) // 2]\n left [x for x in arr if x pivot]\n mid [x for x in arr if x pivot]\n right [x for x in arr if x pivot]\n return quick_sort(left) mid quick_sort(right), index: 0, finish_reason: stop } ], usage: { prompt_tokens: 12, completion_tokens: 68, total_tokens: 80 } }重点看choices[0].text有没有内容finish_reason是不是stop。如果是length说明max_tokens设小了补全被截断。如果choices是空数组检查prompt是不是空字符串。对话式补全的返回结构不同内容在choices[0].message.content里{ choices: [ { message: { role: assistant, content: def parse_json(s):\n import json\n try:\n return json.loads(s)\n except json.JSONDecodeError:\n return None }, finish_reason: stop } ] }4.2 验证通知回调补全通了之后验证通知。先启动第 3.4 节的回调服务确认监听在 8787。然后手动往回调地址发一条模拟通知确认服务能收到curl -X POST http://localhost:8787/notify \ -H Content-Type: application/json \ -d { event: progress, progress_token: task-20250101-001, progress: 30, total: 100, message: 正在处理第 30/100 条 }回调服务终端应该打印[进度] 30/100 正在处理第 30/100 条。这一步确认回调服务本身没问题。接着验证真实任务的通知。发一个带progress_token的补全请求服务端在处理过程中会往回调地址推通知。请求体里加_meta字段curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 生成一个快速排序函数}], max_tokens: 256, _meta: { progress_token: task-20250101-001, callback_url: http://localhost:8787/notify } }如果服务端支持进度推送回调服务会陆续打印进度。注意不是所有模型和接口都支持_meta进度推送具体以接入文档为准。如果不支持进度上报需要你在自己的任务编排层实现把任务拆成多个子请求每完成一个子请求就手动往回调地址发一条进度。4.3 验证状态通知状态通知覆盖任务的生命周期started、running、completed、failed。手动模拟一条完成通知curl -X POST http://localhost:8787/notify \ -H Content-Type: application/json \ -d { event: status, progress_token: task-20250101-001, status: completed, message: 任务完成共处理 100 条 }回调服务打印[状态] completed tasktask-20250101-001。真实场景里状态通知由任务编排层在任务开始和结束时发出客户端收到completed后关闭进度条收到failed后展示错误信息。4.4 端到端串起来把上面三步串成一个脚本验证完整链路#!/bin/bash # e2e-test.sh set -e echo 1. 启动回调服务 node notify-server.js NOTIFY_PID$! sleep 1 echo 2. 发补全请求 curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 写一个二分查找}], max_tokens: 128 } | head -c 200 echo echo 3. 模拟进度通知 curl -s -X POST http://localhost:8787/notify \ -H Content-Type: application/json \ -d {event:progress,progress_token:e2e-001,progress:50,total:100} echo echo 4. 模拟完成通知 curl -s -X POST http://localhost:8787/notify \ -H Content-Type: application/json \ -d {event:status,progress_token:e2e-001,status:completed} echo echo 5. 清理 kill $NOTIFY_PID跑bash e2e-test.sh看到补全返回内容、进度打印、完成打印链路就通了。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一章对照真实报错。下面每一条都是我在接 TaoToken 和通知机制时实际遇到过的按报错信息、原因、解决三步写。5.1 401 Unauthorized报错长这样{ error: { message: Invalid API key provided, type: invalid_request_error, code: invalid_api_key } }原因有三种。第一Key 复制时带了空格或换行Authorization头里多了空白字符。第二Key 已经失效或被删除去 https://taotoken.net/api-keys 确认状态。第三环境变量没生效echo $TAOTOKEN_API_KEY输出为空。解决重新复制 Key确保Authorization: Bearer sk-xxx中间只有一个空格。环境变量在~/.zshrc里加完之后执行source ~/.zshrc或者新开一个终端。如果用的是 Claude Code检查settings.json里ANTHROPIC_API_KEY字段有没有写对注意不要写成ANTHROPIC_AUTH_TOKEN字段名错了也会 401。5.2 local proxy failed报错长这样Error: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这个报错说明你的工具配置里指向了一个本地代理端口但那个端口没有服务在跑。常见于之前配过代理工具后来关掉了但配置没清。解决检查环境变量HTTP_PROXY、HTTPS_PROXY、ALL_PROXY有的话清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后检查工具的配置文件里有没有proxy字段删掉或改成直连。TaoToken 的 Base URL 是https://taotoken.net/api直连即可不需要额外代理。5.3 reading choices 相关报错报错长这样TypeError: Cannot read properties of undefined (reading choices)或者KeyError: choices原因是你按补全接口的返回结构去解析对话接口的响应或者反过来。/v1/completions返回的顶层字段是choices[0].text/v1/chat/completions返回的是choices[0].message.content。用错了 endpoint 或者解析路径写错就会读到 undefined。解决先确认你调的是哪个 endpoint。补全用https://taotoken.net/api/v1/completions对话用https://taotoken.net/api/v1/chat/completions。解析时加防御const data await response.json(); if (!data.choices || data.choices.length 0) { console.error(返回结构异常:, JSON.stringify(data)); return; } const text data.choices[0].text || data.choices[0].message?.content || ;另外如果返回体里出现error字段说明请求本身失败了先处理错误再读choices。5.4 OAuth 相关报错报错长这样Error: OAuth token expired, please re-authenticate或者invalid_grant: refresh token is invalid这类报错出现在用 OAuth 方式登录的工具里比如某些 Claude Code 版本。OAuth token 有有效期过期后需要重新授权。但如果你用的是 API Key 方式接入 TaoToken不应该出现 OAuth 报错。出现的话说明工具还在走旧的 OAuth 通道没切到 API Key。解决在工具设置里找到认证方式从 OAuth 切换成 API Key填入sk-开头的 KeyBase URL 填https://taotoken.net/api。Claude Code 的话检查settings.json里是不是同时存在 OAuth 相关字段和 API Key 字段把 OAuth 字段删掉只留ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL三件套。5.5 进度通知收不到报错不一定有但现象是回调服务一直没打印。排查顺序第一确认回调地址可达。在服务端所在机器上curl http://localhost:8787/notify如果连不上说明回调服务没启动或端口被占。第二确认progress_token唯一。两个任务用了同一个 token服务端推送时客户端分不清是哪条任务可能覆盖或丢弃。用 UUID 或自增计数器生成。第三确认progress单调递增。协议规定进度值只能增不能减重试时把计数器重置成 0 会导致后续较小值被忽略。重试时要么继续递增要么发一条全新的任务。第四确认日志等级。min_log_level设成warning时info和debug级别的日志不会推送。调试时临时设成debug。5.6 补全建议为空现象是补全请求返回 200但choices[0].text是空字符串。原因通常是prompt太短或太模糊模型没有足够上下文生成建议。解决把光标前的更多代码贴进prompt至少包含函数签名和几行上下文。另外temperature设成 0 时模型可能返回空调到 0.2 左右。如果还是空检查max_tokens是不是设成了 0 或负数。6. 把补全和通知接进你的工具链到这里Completions 请求、进度上报、状态通知三条链路都跑通了。回到开头那个问题补全正常但通知全丢根因是通道不统一。用 TaoToken 把 Base URL 和 Key 统一之后补全请求和通知回调走同一个入口progress_token能正确关联排查问题时只看一份日志。如果你要长期跑编码任务或 Agent建议了解一下 Coding Plan地址是 https://taotoken.net/coding-plan 适合需要稳定额度和长任务支持的场景。补全和通知的接入细节在文档里都有遇到字段对不上时先翻 https://taotoken.net/doc 。想快速验证模型返回效果可以直接用模型对话页面 https://taotoken.net/chat 试几条 prompt确认模型 ID 和返回格式没问题再写进配置。最后给一个实用技巧把progress_token的生成逻辑封装成一个函数每次任务开始时调用返回带前缀的唯一 ID。这样多个窗口、多个任务并发时不会串台。通知回调服务里加一个内存 Map按progress_token存最新进度前端轮询这个 Map 就能拿到实时状态不用每条通知都推给前端。这套组合我在几个项目里用过长任务的体验提升很明显用户不再问“是不是卡死了”。
