PROJECT-MAP：token_proxy 工程地图¶
接任务先查第 1 节路由表；问现状去
docs/HANDOFF.md；问步骤去docs/SOP.md或各主题目录 SOP。 本文件只描述工程身份与结构（静态），不写当前状态（HANDOFF），不写操作步骤（SOP / RUNBOOK）。 修订纪律：定点修订，只改受影响行；仅在新增/退役子项目或拓扑变化时动，不借机整体重写。
1. 任务路由表¶
| 任务 / 症状 | 工程 / 组件 | 先读 | 入口命令 |
|---|---|---|---|
| 加/改上游路由、计价、白名单 | 代理本体 | docs/SOP.md 十、十七节 |
改 config.yaml → systemctl --user restart token-proxy |
| 代理起不来 / 8788 被占 | 代理本体 | docs/SOP.md 十三节 |
systemctl --user status token-proxy |
| 改全局规则 / Hook 行为 | Hook 脚本集（7 个） | hook-restore-20260923/SOP.md 第 6 章、hook-skill-desc-20261002/SOP.md |
改脚本与 hooks.json 均即时生效（10-07 实测，旧「须重启 Trae」已证伪） |
| Hook 提醒静默失效 | Hook 脚本集（7 个） | posttooluse-guard/README.md、docs/SOP.md 四十六节 |
核对 ~/.trae-cn/hooks.json 的 7 条脚本路径 |
日度成本审查（/cost） |
cost_audit + skill | daily-cost-review-20260923/SOP.md |
./venv/bin/python cost_audit/daily_review.py |
| 用量 / 成本 / 步轮统计 | cost_audit | docs/BASELINE.md 第 3 节 |
./venv/bin/python cost_audit/analyze_usage.py |
| 按天 / 按上游聚合，含三段成本 | cost_audit | cost_audit/agg.py（docstring） |
python3 cost_audit/agg.py [--by day\|route] [--since D] [--until D] [--route ds\|all] |
| 效率收益对照 / 规则遵守率 | cost_audit | rule-compliance-20261006/SOP.md |
python3 cost_audit/rule_compliance.py [--by week] [--cut <日期>] |
| 合并机会 / 未合并块统计 | cost_audit + merge-guard | merge-coverage-all-20261006/SOP.md |
python3 cost_audit/step_profile.py [--top N | --conv ID] |
| 工具执行耗时 / 工具变慢 | tool-timing-hook | tool-timing-20261007/RUNBOOK.md |
日志 logs/tool_timing.jsonl；自测 python3 tool-timing-20261007/verify_tool_timing.py |
| 上游生成耗时 / 首 token 慢 | 代理本体 | upstream-timing-20261007/RUNBOOK.md |
logs/usage.jsonl 的 ttfb_ms / first_chunk_ms / total_ms；验证 python3 upstream-timing-20261007/verify_upstream_timing.py |
| 收尾四项取数（时间墙/步数/合并/费用） | cost_audit | wrapup-ask-guard-20261007/SOP.md |
python3 cost_audit/wrapup.py |
| 变更脚手架：建主题目录 / 备份 / 台账 | docgen | docgen/backup_ledger.py（docstring） |
python3 docgen/backup_ledger.py <主题目录> --backup <文件>...（幂等、保层次） |
| 建 HANDOFF 骨架 | docgen | docgen/handoff_skeleton.py（docstring） |
python3 docgen/handoff_skeleton.py [--write]，再跑 cost_audit/handoff_precheck.py |
| 缓存整段失效 / 未命中排查 | cost_audit | cost_audit/analyze_prefix_fail.py（docstring） |
见该脚本用法说明 |
| 会话成本归因 / 单会话深挖 | cost-deep-review | .trae/skills/cost-deep-review/SKILL.md |
session_deep_dive.py --date / --conv |
| 开机自启 / 每日 00:00 报表 | autostart | autostart/SOP.md |
autostart/install-autostart.sh |
| 网卡静态 IP | net_static_ip | net_static_ip/SOP_静态IP.md |
net_static_ip/set_static_ip.sh |
思考档位（reasoning_effort） |
代理本体 + stage-thinking | stage-thinking-20260930/SOP.md、RUNBOOK.md |
改 config.yaml + proxy.py |
小米 / MiMo 链路（路由 mi） |
代理本体 | mi-model-20260924/SOP.md |
见路由表 config.yaml |
| 答复缺四列表 / 要你拍板行 | 代理本体（reply_check） |
reply-nudge-20261012/SOP.md |
改 config.yaml 的 reply_check.enabled → systemctl --user restart token-proxy |
| 交接文档 / 项目地图维护 | docs | 本文件 + docs/HANDOFF.md |
按 writing-handoff 约定 |
2. 分层依赖¶
[物理层] 主机 192.168.31.250 (rain) + systemd 用户服务 token-proxy（linger 已开）
[服务层] proxy.py @ 0.0.0.0:8788 ──读── config.yaml / secret.yaml（routes + pricing + 白名单）
[兼容层] ds→DeepSeek / glm→智谱 / mi→api.xiaomimimo.com/v1（加新上游只改配置、不改代码）
[入口层] Trae 客户端 → http://192.168.31.250:8788/<route>
[数据层] logs/usage.jsonl · balance_history.jsonl · req_shape.jsonl · guard_events.jsonl · tool_timing.jsonl → cost_audit/*.py → reports/*.md · *.xlsx
[旁路] Hook 脚本 7 个 ← ~/.trae-cn/hooks.json（SessionStart ×1 / PreToolUse ×6 / PostToolUse ×2）
装载来源（链路外）：venv/（openpyxl 等依赖）、~/.trae-cn/user_rules/*.md（5 个规则）、
~/.trae-cn/commands/cost.md、~/.trae-cn/commands/subagent-mode.md、~/.trae-cn/agents/ctx-scout.md、~/.trae-cn/agents/web-scout.md、~/.trae-cn/hooks.json。
3. 子项目卡片¶
活工程¶
- 代理本体（工程根）｜定位：计量代理服务 ｜ 关键产物：
proxy.py、config.yaml、run.sh｜ 上下游：上游 ds/glm/mi ↔ Trae 客户端 ｜ 文档docs/SOP.md - sessionstart-hook/｜定位：SessionStart 注入中文指令 + HANDOFF ｜ 产物：
session-start-inject.py｜ 上下游：读docs/HANDOFF.md - docs-read-hook/｜定位：Read
docs/*.md前注入上下文成本约束 ｜ 产物：docs-read-guard.py - posttooluse-guard/｜定位：写规则 / 命令 / hooks / SKILL 描述后分档提醒 ｜ 产物：
skill-edit-guard.py、README.md - glob-grep-guard/｜定位：Glob/Grep 使用无目录限定的
**通配前，注入检索约束提醒（只提醒、不阻断）｜ 产物：glob-grep-guard.py - tool-timing-hook/｜定位：工具执行埋点（Pre 记开始 / Post 算时长，落
logs/tool_timing.jsonl，异常静默、不注入上下文）｜ 产物：tool-timing.py、state/｜ 文档tool-timing-20261007/SOP.md、RUNBOOK.md - merge-guard/｜定位：PreToolUse 检测「本可合并却逐步来」的高置信序列（连续只读 / 同文件重复读改 / 连续删除），高置信判据强制拦截 + 指纹放行；另含判据 J「禁止提问窗」｜ 产物：
merge-guard.py｜ 文档merge-coverage-all-20261006/SOP.md、merge-guard-enforce-20261006/SOP.md - cost_audit/｜定位：只读成本与用量分析脚本集 ｜ 产物：
daily_review.py、analyze_usage.py、analyze_prefix_fail.py、selfcheck.py、verify_thinking.py、step_profile.py、rule_compliance.py、wrapup.py（收尾四项取数） ｜ 上下游：读logs/*.jsonl - .trae/skills/cost-deep-review/｜定位：
/cost深挖技能（三阶段 + 归因/取证）｜ 产物：SKILL.md、scripts/session_deep_dive.py - autostart/｜定位：开机自启 + 每日 00:00 报表任务 ｜ 产物：
install-autostart.sh｜ 文档autostart/SOP.md - net_static_ip/｜定位：网卡静态 IP 固化 ｜ 产物：
set_static_ip.sh｜ 文档net_static_ip/SOP_静态IP.md
服务档案¶
- 暂无独立服务档案目录（服务行为与端口见
docs/BASELINE.md第 1 节）。
数据源（不可再生）¶
- logs/｜
usage.jsonl（记账）、balance_history.jsonl（余额）、req_shape.jsonl（请求结构指纹）、guard_events.jsonl（守卫拦截事件）、tool_timing.jsonl（工具执行时长）—— 绝不可删
留档（变更档案目录；目录不删，仅追加）¶
| 目录 | 变更主题 |
|---|---|
handoff-bootstrap-20260923/ |
HANDOFF 机制空档补齐（未命中提示 + 首份快照） |
md-inventory-20260923/ |
md 文件清单生成 + backup 清理 |
hook-restore-20260923/ |
误删 Hook 守卫脚本的恢复（第 6 章为守卫离线回归用例表） |
turn-seq-fix-20260923/ |
轮次口径 turn_seq 修复 |
daily-cost-review-20260923/ |
日度成本审查（daily_review.py + /cost）上线 |
output-cost-20260923/ |
执行效率规则落地（含规则写入源与提问对照卡） |
mi-model-20260924/ |
小米 / MiMo 链路接入 |
cost-auto-trigger-20260925/ |
/cost 自动触发（无 SOP，仅 backup） |
stage-thinking-20260930/ |
会话阶段思考档位（含 RUNBOOK） |
hook-skill-desc-20261002/ |
Hook 守卫命中面收窄（skill description） |
project-map-20261002/ |
本文件建立（备份台账） |
ctx-warn-20261002/ |
Hook 新增会话规模提醒（步数 + 上下文） |
backlog-20261002/ |
优化点总账挂账项落地（#9 深挖批量化 / #19 Glob+Grep 守卫）+ 三个残留 backup 清理 |
subagent-20261002/ |
用户级 Subagent ctx-scout 上线 + 积分门控一键切换（/subagent-mode） |
web-scout-20261002/ |
用户级 Subagent web-scout 上线（浏览器/网页取证专用，只读，仅挂 Exec；与 ctx-scout 分离） |
merge-coverage-all-20261006/ |
动作类型全覆盖的强制合并（规则矩阵 12 类 + step_profile 全集分列 + merge-guard Hook） |
ctx-attribution-20261006/ |
上下文成本归因结案（大 miss 归因表落 docs/BASELINE.md §2.1；HANDOFF 因超 10 KB 整体重写） |
merge-guard-enforce-20261006/ |
merge-guard 升级为强制拦截（判据 A/B/D/E/F/I，JSON deny + 指纹放行；C 仅提醒） |
glob-grep-enforce-20261007/ |
glob-grep-guard 升级为强制拦截（判据 G：LS 过浅目录；H：** 通配；hooks.json 新增 LS matcher） |
wrapup-ask-guard-20261007/ |
收尾固定五项（wrapup.py）+ 判据 J「禁止提问窗」+ guard 事件落盘 + miss 阈值 5000→20000 |
task-side-efficiency-20261007/ |
效率体系：系统侧 vs agent 侧（专项待处理，含部署器基线数字） |
efficiency-sides-20261007/ |
时间侧全景画像（总墙钟 → 活跃 / 离开、按工具分组；profile_time_sides.py） |
tool-timing-20261007/ |
工具执行埋点（tool-timing Hook）上线：Pre/Post 配对量工具执行时长 |
upstream-timing-20261007/ |
上游生成侧埋点：proxy.py 落 ttfb_ms / first_chunk_ms / total_ms |
backlog-review-20261007/ |
过账结构治理：第一节拆 1.1 待办型 / 1.2 判据型，_backlog_count 改口径（挂账 21 → 6） |
merge-guard-i-20261007/ |
判据 I 补 separated（修「同一步并行批被误拦」）；总账关闭 #35、新增待标定 #40 |
backlog-prune-20261002/ |
优化总账分区治理与过账收敛 |
backlog-review-20261002/ |
把优化总账的过账变成有触发点的动作 |
handoff-capacity-20261002/ |
HANDOFF 容量机制修正（护栏解耦 + 技能归因纠错） |
handoff-read-guard-20261002/ |
SessionStart 注入「HANDOFF 读取守卫」 |
prompt-hint-20261002/ |
代理层注入固定「推理约束」提示（prompt_hint） |
selfcheck-abc-loop-20261002/ |
补 A/B/C 收尾自查的跨轮样本闭环 |
selfcheck-d-20261002/ |
收尾自查新增 D 组「工具与子智能体」 |
selfcheck-d-loop-20261002/ |
补齐 D 组自我迭代闭环 |
selfcheck-detail-20261002/ |
给收尾自查补「执行阶段详情」 |
shape-toolname-20261002/ |
给 logs/req_shape.jsonl 补记工具名（总账 #21） |
step-profile-20261002/ |
会话步序列画像工具（step_profile.py） |
efficiency-trigger-20261003/ |
探目录口径固化（从 MB 台账提升为可触发项） |
rule-ambiguity-20261003/ |
全局规则新增「歧义先问（硬门禁）」 |
conclusion-fix-20261006/ |
效率与成本「结论修正」（贴图归因 + 切换成本倍数） |
merge-coverage-20261006/ |
可并组识别口径扩为全覆盖 |
merge-scenarios-20261006/ |
碎步合并措施补强 —— 可并组分列 + 改-验批量化 |
merge-toolsseq-20261006/ |
强制合并优先 + 采集 tools 名字序列 |
rule-ambiguity-removal-20261006/ |
删除「歧义先问（硬门禁）」机制 |
rule-compliance-20261006/ |
规则遵守率代理对照（效率收益对照组的补齐） |
rule-selfcheck-20261006/ |
自评类条款改为「无异常一句话，有异常才展开」 |
batch-interface-20261007/ |
新增判据 L（批量接口提醒）+ BASELINE 记「逐条 vs 批量入参」 |
cache-ttl-20261007/ |
缓存 TTL「空闲即失效」降级【存疑】（9.3 h 空档反例） |
compress-point-20261007/ |
「不切会话路线」手动压缩点模型沉淀进 BASELINE §2.1；2026-10-08 落地到 Hook（300 K） |
cost-command-20261007/ |
/cost 命令正文口径对齐 BASELINE §2.1 |
guards-strengthen-20261007/ |
守卫补强三件（G/H 真机验证 · webfetch-guard 落盘 · 新增判据 K） |
handoff-rewrite-20261007/ |
HANDOFF 整体重写 |
ledger-gap-20261007/ |
台账缺口补齐（HANDOFF / BASELINE / 总账） |
ledger-sync-20261007/ |
台账同步（耗时埋点样本 + 守卫误报率回填） |
merge-guard-allowfp-20261007/ |
修复 merge-guard 的 allow_fp 漏记 |
tools-norm-verify-20261007/ |
核实「proxy 侧规范化 tools 顺序」措施的实际效果 |
tools-order-20261007/ |
proxy 侧规范化 tools 顺序（消除轮首冷启动） |
turnkey-pitfall-20261007/ |
turn_key 复用陷阱入库（稳定层 + MB） |
wrapup-miss-threshold-20261007/ |
修正 wrapup.py 的 miss 阈值注释残留 |
wrapup-short-order-20261007/ |
补 SHORT_ORDER 缺失的「改跑」 |
wrapup-tools-jitter-20261007/ |
收紧 wrapup.py 的「tools 顺序抖动」判据 |
wrapup-turn-span-20261007/ |
修 wrapup.py 的「时间墙」口径（turn_key 复用导致失真） |
batch-workflow-20261008/ |
批量项工作流固化（先敲定、再一次做完） |
cache-probe-20261008/ |
proxy 侧空闲后探测前缀缓存（cache_probe） |
handoff-frontload-20261008/ |
HANDOFF「写入前置流程」（消除「先写后压」） |
permission-grant-20261008/ |
Trae 权限全开（global.json 写白名单 + 命令白名单 19→56） |
rule-acceptance-20261008/ |
条款验收方补强（Hook 存活自检 / script-safety-guard / sched-guard / shadow-check-guard） |
rule-slim-20261008/ |
常驻规则减重两批（42 340 → 29 782 B）+ 修订史迁出 |
state-persist-20261008/ |
proxy 内存态落盘（thinking_stages + 探测快照） |
wrapup-cost-20261008/ |
修正 wrapup.py 的费用口径（逐条按 pricing / 跳空 conv_key） |
thinking-default-low-20261011/ |
思考默认档由 off 改为 low（三档：off / low / high） |
efficiency-iteration-20261011/ |
merge-guard 判据 S + 优化关键词提档（8 词） |
backup-hygiene-20261011/ |
备份清理评估（backup_ledger.py --prune，双 3 天）+ merge-guard 判据 W 收尾软提醒 |
wrapup-deep-analysis-20261011/ |
「大轮次默认深挖」阈值（时间墙 ≥5 min 或 费用 ≥0.4 元）入规则 §收尾自查 |
prompt-hint-cn-20261011/ |
强制中文思考（thinking.prompt_hint 重新启用）+ 前缀失效口径修正（增删 skill 才整段重建） |
prefix-guard-20261011/ |
merge-guard 判据 X（system prompt 改动 → 建议开新会话）+ 默认档改 high + 重启非红线 |
cacheprobe-expired-20261011/ |
cache_probe 快照过期即判无缓存（修超长空闲盲区）+ 修复 token-proxy systemd failed（端口 8788 被手动进程占） |
remote-exec-20261011/ |
Agent 远端操作入口固化（共享库 remote_exec.py + merge-guard 判据 Y / Z）+ 跨项目落盘口径 |
hook-deny-tune-20261012/ |
收窄两处强制拦截面：sched-guard 动词表移出只读查询、webfetch-guard 由按次数改为 120 秒连续窗口 |
reply-nudge-20261012/ |
代理侧答复形状检查（reply_check）：轮首回看上一轮答复，缺四列表或拍板行即注入提醒 |
上表由脚本按「目录名后缀日期」补录（2026-10-08），原 26 行逐字未动；目录不删，仅追加。
项目外强相关路径¶
~/.trae-cn/hooks.json、~/.trae-cn/user_rules/*.md、~/.trae-cn/commands/cost.md、~/.trae-cn/agents/*.md- 使用本代理记录用量的下游项目：
~/Documents/k8s_ins/、~/Documents/kvm/等
4. 工程命名与文档约定¶
- 主题目录：
<主题>-<YYYYMMDD>，内含SOP.md与backup/；常驻工程目录用语义名（autostart/、net_static_ip/、cost_audit/） - docs 三件套：
HANDOFF.md（动态快照，SessionStart 注入，≤10 KB）/BASELINE.md（稳定层）/PROJECT-MAP.md（本文件，静态结构） - 信息边界：地图 = 身份与结构；HANDOFF = 现状与待办；SOP / RUNBOOK = 步骤与过程。三者不重复维护
- backup 台账：每主题目录下
backup/README.md逐条登记（备份文件 / 原路径 / 时间 / 原因 / 回滚内容 / 可删时机） - 工程形态：复杂变更（多主机、多模块、需回滚编排）用 Python 工程（apply / verify 分离）；极简变更才用 shell（首行
set -euo pipefail） - 退役纪律：工程退役或被取代时不删目录，改身份标签并移入留档分组
来源：
/home/rain/Documents/services/token_proxy/docs/PROJECT-MAP.md｜ 最后更新：2026-10-12 13:46（由build/sync.py同步，请勿在站点侧修改）