muse-agent-example/docs/2026-07-16-批9c-收官与优化方案.md

批9c 收官状态 + 下一步优化方案（2026-07-16 晚，compact 恢复锚点）

本文档＝compact 后接续工作的详细锚点。概览见 README §九「批9c」条目；本文档给可执行细节。 任务完成后按仓库约定蒸馏进 README §九 并删本文档。

进展快照（2026-07-17 凌晨，最新——compact 恢复优先读这节）

• item4 额度系统：✅ 已实现+主代理亲验+已提交 9a513e7（chat_governed 统一治理，五书降级链上收，账本 example_llm_quota）。
• 范式卡去重（回溯聚类）：recluster 子命令已实现+亲验（连接三段/贪心最近母卡/软删可逆/dry-run 门控）。combat 已放量：886→770（并 116，缩减 13%），完整性/可逆性/质量四项亲验通过（116 输家软删+116 嵌入软删+83 母卡带回溯审计，被并卡全文留档可回滚）。其余四型（emotion/craft/scene_pattern/trope）后台放量中（/tmp/muse-recluster-rest.log，任务 bl8fwgyjc，受额度系统自动跨窗，约 5550 次判定、跑几小时）。真实归并率 ~13%（非预想 50%，创始人已知情拍板"全量 0.75"）。cards() 前向修复（SIM_MERGE 0.85→0.80、0.75+ 均送判定）已随附。
• 升格卡改造：4 决定已拍（①里程碑=结构化对象 章/台阶/周期 ②补齐=五型全补 ③character 一起改 ④存量迁移=人工精确化；+主代理定 演变概括独立字段），记入 docs/2026-07-16-升格卡改造设计.md §十。fable5 已实现前向代码+主代理亲验：6 个 schema yaml（演变历程 [detection,extraction]/演变概括·前身·后继 true/character 成长弧线回归"未来计划"）、parse_upgrade.py（里程碑对象合并去重按真实章号+撤销靠 _win 键+当前态干净纪律+语义判重默认关）、迁移脚本 migrate_upgrade_windows.py（确认只读零写库）、read-context/detect SKILL.md 补说明。
• 进度（截 2026-07-17 06:00）：范式卡去重 ✅ 五型全放量完成 7045→6327（并 718 / ~10%） 已提交 9c87f0d（五型均自洽可逆）；升格卡前向代码 ✅ 已提交 1786035、seed 已重跑灌合同（6 型合同均含演变历程，亲验）、type 键兼容已核 OK。
• 独立审查（opus 对抗复核，2026-07-17）：无阻断问题（软删/可逆/连接三段/额度不绕过/契约 全部独立复核成立）；揪出并修复 2 真 bug（提交 46704ee）——① recluster _absorb 用输家书名覆写实例跨书归属（已污染 30 条/14 母卡，已从回溯归并审计确定性还原、复验 0 残留）；② 迁移章号正则裸"N章"误抓"隔3章"数量词（迁移未真跑、无数据影响，已修+11 用例验证）。步骤3 语义判重启用前需处理：semantic_dedup 在持窗级 DB 连接期发 embed+M3（非三段式，靠 keepalives），开启前改三段或确认无碍。轻微项（_win 键入 payload 噪声、里程碑按台阶去重边界）已记、暂缓。
• 剩余待创始人 go 的两步动真格：① 真迁移落库（人工精确化＝无内嵌章号的 6616 条再抽原文定章，563 卡待迁、25 条待人工；先 dry-run 给样例再落）；② 开语义判重（需先把升格卡 embed 落库）。另注：部分老升格卡过度抽取（如李锋 #893 有 527 条成长条目），迁移只精确化章号、不清流水堆，真正干净需重抽（更贵、另议）。

一、批9c 已真收官（五书全量重审）

• 五书 b9-full-v2 审核库内校验 ALLOK：星环 1525 / 机动 780 / 机战 2336 / 超神 1441 / 深空 963，全书全覆盖。
• 审核统计：pass 1677（23.8%）/ revise 4358 / reject 1010 / blocked 0，均分 3.16，降级卡 30（全星环，敏感批用备用模型评分、已打标记；纯 M3 评分 7015）。
• 三份样张：docs/2026-07-16-批9终态样张-{范式五书,升格机动,升格深空}.md（前两已提交；升格深空为本轮新出，untracked）。
• 额度：旧 grep 次数口径（8965）作废；服务端实花 $122.93（累计=今日；授权上限 $2100）。

二、本轮踩坑与修复（勿回退）

1. 死锁解开：原重审 wrapper 与深空残渣清洗钩子的 pgrep -f 交叉/自匹配互锁 → 杀钩子手动跑 /tmp/muse-clean-debris.py 8 + 会话接管深空重审。教训：解死锁最小动作优先（曾多叠一个接管控制器、把正常在审的深空打断，纯属过度设计）。
2. review_cards.py 修 3 处（.claude/skills/review-cards/scripts/review_cards.py，工作树已改未提交）：
   • 敏感降级链 DEGRADE_CHAIN=["MiniMax-M3","MiniMax-M2.7","deepseek-v4-flash","glm-5.2"] + chat_degrade_review()；全链失败标 blocked 不崩。
   • 分片 --shard i/N（id%N==i），多进程并发各自独立事务。
   • 连接拆「读/算/写」三段：LLM 阶段不持 DB 连接、写库用全新短连接（治 Tailscale 长事务空转超时，实测星环/机动崩因）；+ reviews 条目 isinstance(r,dict) 守卫（防模型把条目返成 list 崩）。
3. 物理删除 work5/9（机战/超神「源修复前重复导入」旧本，共 8596 行：章 4296+块 4296+参考档案 2+作品 2）：创始人 2026-07-16 明确授权覆盖「删除=软删、不物理删」红线，仅此两废本；SQL=/tmp/muse-b9c-purge-w59.sql；删后作品表 8 本 8 活、好本 work10/11 无损。其余表仍守软删红线。

三、下一步工作（创始人已确认，compact 后继续）

item 4：额度系统改造（✅ 已上线·主代理亲验）

状态（2026-07-16 夜收口）：compact 后重做完成并主代理亲自验证上线——

• 代码：llm.py 加 chat_governed 统一治理入口 + 计价/窗口/账本读写；四调用方（parse_llm/parse_outline/parse_ingest/review_cards）自建降级链上收复用；新建 db/ddl/95-example额度账本.sql（表 example_llm_quota 已 apply）+ 离线单测 test_quota.py。
• 亲验：① 9 条离线单测主代理亲跑全过（窗口/计价/六路由）；② review_cards 三处红线修复完好未回退；③ 全模块导入无悬空引用；④ 真调用对账端到端闭合——首个真调用我算 11.04 配额单位、服务端 total_used 实扣 +11（异步延迟十几秒落账），匹配；账本两笔原子累加正确（0.00018516/2 笔）；⑤ 校准噪音已 DELETE，账本清零、额度从零起（当前窗 2026-07-16T20）。
• 已知：New-API /api/usage/token/ 聚合口径异步滞后且高频轮询会限流返非 JSON（与计价正确性无关，勿据此判错）。
• 下方 spec 为实现依据，保留备查。

全局改 llm skill（只改 .claude/skills/llm/scripts/llm.py + 新建 example_llm_quota 库表 DDL 落 db/ddl/）：

• 以钱为主。每次调用：cost_usd = model_ratio × ((prompt_tokens - cached_tokens) + cached_tokens×cache_ratio + completion_tokens×completion_ratio) / 500000（New-API 口径，$1=500000 配额单位）。费率从 GET http://100.64.0.8:3000/api/pricing 取，硬编码兜底：M3=0.15/4/0.2、M2.7=0.15/4/0.2、glm-5.2=0.5634/3.5/0.25、deepseek-v4-flash=0.07/2/0.0714（model_ratio/completion_ratio/cache_ratio）。
• 时间窗：按钟点 floor 到 00/05/10/15/20（每天 5 窗，末窗 20–24=4h），每窗独立、跨窗清零。用 datetime.now()（普通 python 可用）。
• 共享账本 example_llm_quota（窗口键、MiniMax花费usd、总调用数、更新时间），原子累加（INSERT ... ON CONFLICT DO NOTHING 建行 + UPDATE ... RETURNING），多进程/shard 共用一本账。
• 全局统一路由（敏感降级 + 预算降级并成一条），每调用前：① 本窗总调用 ≥4000 → 自动 sleep 到下一窗边界续跑（创始人选，非硬停退出）；② 要 MiniMax(M3/M2.7) 且本窗 MiniMax 花费 ≥10 → 切 glm-5.2 → 调用失败(不可用) → 切 deepseek-v4-flash（glm/deepseek 无 上限、但可能失败）；③ 撞 SensitiveError 沿链降级。成功后原子累加（花费仅 MiniMax 计、次数全计）。
• review_cards.py 里自建的 chat_degrade_review 改为复用 llm skill 统一路由（避免两套降级）。
• 坑：sleep 到下一窗时不持 DB 连接（Tailscale）；费率拉取失败用兜底值。
• 验证：离线单测（窗口边界/成本公式/路由选择，假 usage）+ 1–2 次真调用对账（snapshot /api/usage/token 的 total_used 增量 ÷500000 vs 算出的 cost，±5%）。
• 额度清零 = 新表从零起（当前 20–24 窗从 0 算）。

卡质量优化（方案已确认，等 item 4 上线后实施；都要烧 M3、受新 $10/5h 窗管控）

两只 fable5 诊断共同结论：病根＝判重坏了（当初为省钱关了语义判重）+ 抽取过量产碎片；两类卡头号修复都是开启嵌入语义判重。

范式卡（pass 率 23.8%；判据没冤枉卡=已校准 opus 金标准、卡真普通，但一大块好卡被「同功 family」机械压分打进 revise＝判重漏检+抽取过量所致，非判据太严。硬证：81.5% 卡有 ≥0.75 近邻、0.75–0.85 段 5123 张全漏走且 64% 是 revise）：

• P0 生产期跨窗跨书聚类去重（最大杠杆）：出卡入库前对全库同型卡聚类归并，一家族留一张母卡累积多实例；SIM_MERGE 0.85→0.80、0.75–0.85 段强制走 merge_judge（现只标记）。改 parse_ingest.py（SIM_MERGE≈L44、cards() L445–471）。预期 7045→~3000–4000 唯一卡，pass 率诚实抬升。
• P1 抽取提干货（改 parse_llm.py scaffold_prompt/window_cards_prompt）：换书测试设硬前置 checklist；combat 只抽战术原理、禁单场战斗走位、强制打题材标签（=combat 打标签落地）；craft 四件套（原理/失败模式/异质化/迁移用例）缺项不出卡；拆掉空批 nudge 逼卡效应（允许型-批真诚 0 卡）。
• P2 控出卡密度（平庸窗允许 0 卡）；P3 判据不松（cal-002 红线），只把 3.33–3.49 贴线的 759 张 fable/opus 批量复审捞回（运营动作）。

升格卡（作品面，成长线丢失；根因＝只有 character 有成长字段、机甲/武器/力量体系无成长字段→进阶被覆写抹平或塞错字段；主线被拆 30+ 张碎卡跨人物/物品/力量体系 3 型、无链接；判重纯字符串、语义判重关了）：

• P0 补骨架+记里程碑（改 meta/schemas/item.yaml、power_system.yaml→seed_schemas.py 重跑入库；改 parse_upgrade.py APPEND_FIELDS(L47)、observe/update prompt）：给 item/power_system 加「演变历程」数组字段；提示词记进化台阶 + 登场→高光→退场→结局生命周期，别覆写抹平。
• P1 串链+语义判重：加「前身/后继」链接字段串进化链；判重接 embed skill（≥0.78 召回 + M3 终判）治改名/跨型漏并。
• P2 清墓碑卡（深空 475 张 deleted=TRUE 回滚残留，物删需创始人授权）；导出层 parse_export.py 按进化链聚合呈现。

创始人两点细化（必须遵守）：

1. 历史/里程碑数组用「绝对章号」索引，绝不用 [窗N]——窗口是运行时定义、会变、非卡属性；现有卡里的 [窗N] 要清成章号。
2. 卡做「渐进式披露」：现状层（实体当前态+概括，写作 agent 续写默认只读）+ 完整历史层（全里程碑，仅一致性检查/detector 读全）；关键卡上万字。落法＝接现有 read-context 的 aiContext 按用途裁剪——把「完整历史」字段标「仅 detection 用途可见、续写不给」（不是新机制，是字段可见性按用途/scenario 分层，与四层上下文/三级裁剪一脉相承）。schema 字段加用途可见性标注、抽取产出分层、read-context 按用途裁剪。

combat 210 卡题材绑定 = 打标签（创始人拍板，纳入范式卡 P1 一起做）

四、遗留项

• 原有：B3 检索验证、B5 确认门、嵌入批量补算——延后。
• 本轮新增：降级卡 30（星环，如要纯 M3 可单独重审这 30 张）；深空摘要重刷 20 条失败尾巴（可重跑补）；卡格萨莫同名升格卡对 1 处（体检唯一黄线，可定点消歧）；框架改动待提交（review_cards.py 3 修复 + item4 llm.py/DDL + 本 doc + README§九——创始人问过「要不要提交」未明确答，恢复后确认再提交）。

五、红线/环境（勿违反）

• review_cards.py 三处修复勿回退；深空清洗→重审串行（禁并发整行写回）；新额度规则(item4)。
• 双轨：创作内容不 commit（确认=commit 只创始人指令触发）；框架/文档正常提交推送。
• 汇报纪律：第一句先说创始人要做什么，白话不黑话（内部代号/英文行话不裸用当场展开）。
• Python=.venv/bin/python；DB 通道=db skill（DSN 锁脚本内，只连 muse-example）；New-API base=http://100.64.0.8:3000、token 在 llm.py 头。
• 书：星环=work3 / 机动=4 / 深空=8 / 机战=10 / 超神=11（work5 机战旧本、work9 超神旧本已物删）。
• 两只 fable5 诊断全文在本 session 对话（升格卡+范式卡），关键点已蒸馏进本文档第三节。