SOP：代理层注入固定「推理约束」提示（prompt_hint）¶
主题目录
prompt-hint-20261002/。变更对象proxy.py+config.yaml。
1. 背景¶
实测输出成本的大头是模型思考（13,984 步 reasoning_tokens 中位 517、占输出 ~60%）。社区针对推理模型的实践是"在系统提示里加推理约束以压低多余思考"，但 Trae 不提供直接编辑 Agent 系统提示的入口，故落到自建代理层实现。
2. 目标¶
- 代理把一段固定文本追加到请求的首条
system消息末尾； - 幂等（已在位不重复追加）、无
system时不动、多模态消息正确追加； - 可一键关闭（
config.yaml的thinking.prompt_hint置空）； - 不影响既有
thinking/reasoning_effort注入与转发链路。
3. 前置条件¶
工程根含 venv/；token-proxy 以 systemd 用户服务运行（8788）；离线验证用"假上游 + 临时端口"，不碰生产端口与生产 logs/。
4. 影响范围¶
| 项 | 说明 |
|---|---|
| 主机 | 仅 192.168.31.250，单机 |
| 需停服 | 是：重启会打断在途流式回答（数秒） |
| 请求体 | 仅改首条 system 的 content，不改消息条数结构；文本固定，故不破坏上游前缀缓存 |
| 关闭方式 | prompt_hint: "" + 重启，无需回滚代码 |
5. 分步操作¶
步骤 1：备份（高危前置）¶
cd /home/rain/Documents/services/token_proxy
ts=$(date +%Y%m%d-%H%M%S)
cp -p proxy.py "prompt-hint-20261002/backup/proxy.py.bak.$ts"
cp -p config.yaml "prompt-hint-20261002/backup/config.yaml.bak.$ts"
chmod 600 prompt-hint-20261002/backup/*.bak.*
台账见 backup/README.md。
步骤 2：配置固定文本（config.yaml）¶
在 thinking: 段加 prompt_hint: | 块（YAML 块标量，保留换行）。文本必须固定不变——随请求变化会使前缀失效。
步骤 3：实现注入（proxy.py）¶
- 新增
apply_prompt_hint(obj, hint)：定位首条role=system，str 内容直接追加、list 内容追加到末个text块；含hint in content幂等判断； parse_thinking_config()增加prompt_hint解析（非字符串告警忽略、空白视为关闭）；- 请求处理处在
json.dumps之前调用，结果记入meta["prompt_hint_applied"]； - 启动摘要
describe_thinking_config()增加推理约束=开。
坑：注入必须在序列化之前；build_shape_fingerprint 在注入之前执行，故 req_shape.jsonl 的 system 指纹不反映 hint（已知局限，见第 8 章）。
./venv/bin/python -m py_compile proxy.py # 预期退出码 0
步骤 4：离线验证¶
./venv/bin/python prompt-hint-20261002/verify_prompt_hint.py
A 纯函数 8 项 + B 假上游端到端 10 项；预期全 [通过]、退出码 0。
步骤 5：重启使配置生效（高危）¶
systemctl --user restart token-proxy
sleep 3 && systemctl --user is-active token-proxy
curl -s -m 3 http://127.0.0.1:8788/healthz
6. 验证¶
grep -a "代理启动" logs/proxy.log | tail -1 # 预期含「推理约束=开」
预期：最新启动行含 推理约束=开（生效前不含）。离线 B 段已证明上游收到的 system 含 hint 且只出现一次。
效果留待观察：用 usage.jsonl 的 reasoning_tokens 中位与"思考/输出"占比，与生效前对比（selfcheck.py/analyze_usage.py）。
7. 回滚¶
触发判据：/healthz 非 200 / 进程非 active / 任务返工明显增加 / 运行日志有 Traceback。
cd /home/rain/Documents/services/token_proxy
cp -p prompt-hint-20261002/backup/proxy.py.bak.20261002-190702 proxy.py
cp -p prompt-hint-20261002/backup/config.yaml.bak.20261002-190702 config.yaml
python3 -m py_compile proxy.py && systemctl --user restart token-proxy
curl -s -m 3 http://127.0.0.1:8788/healthz
更轻的关闭：只把 thinking.prompt_hint 置空后重启（保留代码）。备份位置与用途见 backup/README.md。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 文本随请求变化 → 前缀缓存失效、成本反升 | 文本固定在 config.yaml，不参与任何动态逻辑 |
| 过度压制思考、损伤分析/写作类任务 | 第 1 条已从"唯一目的是调工具"放宽为"决定下一步动作（含结论）"；可随时置空 |
| 多模态/异常消息结构 | apply_prompt_hint 对非 str/list、无 text 块、无 system 一律不改；离线 A4~A8 覆盖 |
| 上游对追加内容不适用 | 纯文本追加，不新增消息条数；无效也只是无效，不报错 |
req_shape 不体现 hint |
已记录为已知局限；验证走启动日志 + 离线 B 段 |
附录：交付物与不另出 RUNBOOK 的理由¶
| 文件 | 说明 |
|---|---|
proxy.py（改） |
新增 apply_prompt_hint()；parse_thinking_config() / describe_thinking_config() 扩展 |
config.yaml（改） |
thinking.prompt_hint 固定文本 |
prompt-hint-20261002/verify_prompt_hint.py |
离线验证（A 8 项 + B 10 项） |
prompt-hint-20261002/backup/ |
两份 .bak + README.md |
未新增可复用服务或入口命令，运行方式仍由 systemctl --user 管理（docs/BASELINE.md 第 1 节），故不另出 RUNBOOK。
9. 关闭记录（2026-10-06）¶
9.1 背景与依据¶
原「效果留待观察」（第 6 章）已出结论：降思考无收益，且反向存在一次全量前缀重建的代价，故关闭。
证据（数据源 logs/usage.jsonl + logs/req_shape.jsonl，区间 2026-09-20~2026-10-06，判据窗口取 10-02 19:08:41 生效时刻前后）：
| 证据 | 数值 |
|---|---|
| ds 路由按 prompt 规模分桶的思考 token 中位（应用前→应用后） | <60k 472→501；60-150k 858→724；150-300k 542→722；>300k 622→920 |
| 逐日「思考占输出」 | 62.1% → 63.7% → 68.3% → 71.0% → 68.1% → 70.2%（整体走高） |
| 开启那一刻的前缀重建 | 10-02 19:08:41 重启，19:08:54 首条请求 miss=235,072（hit 仅 4,224），而该步 head0/tools_hash 与前后完全一致 → 差异只能来自被追加的 227 字符 |
| 成本上界 | 227 字符 ≈110 tok × 6,703 请求 × ¥0.02/百万 ≈ ¥0.015，加上述重建 ¥0.24 = ¥0.26 / 6 天（0.26%） |
结论口径：否证「已见效」——分桶对比中大上下文桶思考反而上升；开启/关闭状态变化会产生一次全量重建。
（完整分析见 reports/daily-review-20261001-20261006.md §6.4；thinking.reasoning_effort 属【已决策】不动，本次不动它。）
9.2 变更内容¶
仅置空 config.yaml 的 thinking.prompt_hint，不改 proxy.py（注入代码保留，便于随时恢复）。
cd /home/rain/Documents/services/token_proxy
ts=$(date +%Y%m%d-%H%M%S) # 高危前置：备份
cp -p config.yaml "prompt-hint-20261002/backup/config.yaml.bak.$ts"
chmod 600 "prompt-hint-20261002/backup/config.yaml.bak.$ts"
# 编辑 config.yaml：prompt_hint: | ... → prompt_hint: ""
systemctl --user restart token-proxy # 高危：打断在途流式回答数秒
坑：prompt_hint 必须写成 ""（空字符串）而非删除该键——parse_thinking_config 对非字符串会告警并忽略；"" 为假值，
if hint: 分支直接跳过，等价于关闭且保留配置位。
9.3 验证（已执行）¶
cd /home/rain/Documents/services/token_proxy
./venv/bin/python -c "import yaml;print(repr(yaml.safe_load(open('config.yaml'))['thinking'].get('prompt_hint')))" # 预期 ''
./venv/bin/python -m py_compile proxy.py # 预期 rc=0
systemctl --user is-active token-proxy # 预期 active
curl -s -m 3 http://127.0.0.1:8788/healthz # 预期 {"status":"ok","routes":["ds","glm","mi"]}
grep -a "代理启动" logs/proxy.log | tail -1 # 预期**不含**「推理约束=开」；仍含 强度=high
实测结果：prompt_hint=''；apply_prompt_hint(obj,"") 返回 False 且 system 未被改写；py_compile rc=0；
服务 active、healthz 正常；启动摘要无「推理约束=开」、思考注入=默认={"type":"enabled"} | 强度=high 保留。
幂等：复跑只做状态确认——配置已是目标值（不再产生变更），服务状态与启动摘要一致。
9.4 回滚¶
cd /home/rain/Documents/services/token_proxy
cp -p prompt-hint-20261002/backup/config.yaml.bak.20261006-162909 config.yaml # 恢复到"注入开启"态
cp -p prompt-hint-20261002/backup/config.yaml.bak.20261002-190702 config.yaml # 或恢复到"注入原始文本"态
systemctl --user restart token-proxy && curl -s -m 3 http://127.0.0.1:8788/healthz
回滚触发判据：若出现「思考量异常暴涨 / 任务返工明显增加」等关闭带来的副作用，即回滚（预期不会：注入本就无收益）。
备份存放位置：prompt-hint-20261002/backup/，台账见其 README.md。
9.5 风险说明¶
| 风险 | 缓解 |
|---|---|
| 关闭瞬间 system 再次变化 → 一次全量前缀重建 | 一次性、可预期；新会话不受影响 |
| 目标未达（关闭后思考反而上升） | 已实测分桶中位无下降，属"去掉一个无效负担"，不改变思考档位 |
| 误改其它配置 | 只改 thinking.prompt_hint 一行；sha256sum 变更前后留痕（c42e5eb4… → 8e8dab2b…） |
来源：
/home/rain/Documents/services/token_proxy/prompt-hint-20261002/SOP.md｜ 最后更新：2026-10-06 16:30（由build/sync.py同步，请勿在站点侧修改）