会话阶段思考档位运行手册¶

1. 服务概览¶

token-proxy 是 Trae 自定义模型的本地计量转发代理，监听 0.0.0.0:8788，由 systemd 用户服务管理。当前阶段策略仅对 DeepSeek 请求启用：明确读取阶段使用 low，编码、命令执行、部署和未知阶段使用 high；同一会话阶段只升不降。代理异常会影响 Trae 经代理访问上游。

请求体规范化（2026-10-07 起）：转发前会把 tools 数组按函数名稳定排序。Trae 每轮会重排该数组（内容一字未改、仅顺序抖动），上游据此判定前缀失效 → 整段重建；排序后顺序恒定，可消除该轮首冷启动（实测约 4.34 元 / 25 天，占短间隔大 miss 的 58%）。语义等价、不改内容；变更档案见 tools-order-20261007/SOP.md。

2. 接入与凭据¶

客户端继续使用现有路由：/ds、/glm、/mi。Authorization 由客户端透传，凭据不写入本手册。MiMo 与 GLM 跳过本次阶段思考注入。

3. 日常速查¶

systemctl --user is-active token-proxy
python3 -c "import urllib.request,json;print(json.load(urllib.request.urlopen('http://127.0.0.1:8788/healthz', timeout=5)))"
journalctl --user -u token-proxy -n 30 --no-pager
tail -n 5 logs/proxy.log
tail -n 5 logs/usage.jsonl
systemctl --user restart token-proxy

预期服务为 active，healthz 返回 status=ok。重启会中断在途流式回答。

4. 日常操作¶

查看启动日志确认策略：

tail -n 30 logs/proxy.log

应看到 思考注入=默认 以及 阶段=collecting:low,coding:high,deploying:high,unknown:high。查看真实请求是否命中阶段策略：

python3 - <<'PY'
import json
for line in open('logs/usage.jsonl', encoding='utf-8'):
    try:
        row = json.loads(line)
    except json.JSONDecodeError:
        continue
    if row.get('thinking_stage'):
        print(row.get('ts'), row.get('route'), row.get('model'), row.get('thinking_stage'), row.get('thinking_effort'), row.get('status'))
PY

5. 配置管理¶

配置文件是 config.yaml，实现文件是 proxy.py。修改前必须按本次交付物的 backup/README.md 备份；修改后先运行离线检查，再重启服务。thinking.skip_models 中的 glm-5.3* 与 mimo-* 不注入思考参数。

6. 备份与恢复¶

本次备份位于 stage-thinking-20260930/backup/，台账与权限见 backup/README.md。恢复后执行：

cp -p stage-thinking-20260930/backup/proxy.py.bak.20260930-233007 proxy.py
cp -p stage-thinking-20260930/backup/config.yaml.bak.20260930-233007 config.yaml
python3 -m py_compile proxy.py
systemctl --user restart token-proxy
python3 -c "import urllib.request,json;print(json.load(urllib.request.urlopen('http://127.0.0.1:8788/healthz', timeout=5)))"

7. 监控与告警¶

重点查看 logs/proxy.log 的启动失败、上游 4xx/5xx、连接失败；重点查看 logs/usage.jsonl 的 status、thinking_stage、thinking_effort 与 usage.completion_tokens_details.reasoning_tokens。阶段策略的成本收益需至少积累 3 个同类任务后再评估，不能用单次请求下结论。

8. 故障处置¶

服务不 active¶

systemctl --user status token-proxy --no-pager --lines=20
journalctl --user -u token-proxy -n 40 --no-pager

若为配置或语法错误，恢复备份并重启；验证 healthz 返回 ok。

healthz 连接拒绝¶

刚重启后可能处于监听初始化窗口；再次执行 healthz。若服务仍 active 但持续拒绝，检查 proxy.log 和端口占用，不启动第二个 run.sh 实例；必要时回滚。

上游因 thinking 参数报错¶

检查 logs/proxy.log 与响应摘要。GLM/MiMo 应命中跳过名单；DeepSeek 4xx 且错误指向 thinking/reasoning 时，代理已有一次原始请求兜底。若真实任务失败或返工增加，立即按第 6 节恢复并重启。

9. 安全与权限¶

不读取、不打印、不提交 API key；备份权限为 600。不得删除 logs/usage.jsonl、logs/balance_history.jsonl 或 logs/req_shape.jsonl。

10. 容量与性能¶

阶段状态保存在代理进程内存中，重启后由后续请求上下文重新判断。日志持续增长时按既有日志轮转策略处理；本次未改变日志保留策略。

11. 附录¶

变更档案：SOP.md
备份台账：backup/README.md
实现入口：proxy.py

来源：/home/rain/Documents/services/token_proxy/stage-thinking-20260930/RUNBOOK.md ｜最后更新：2026-10-07 05:54（由 build/sync.py 同步，请勿在站点侧修改）