跳转至

短上下文工程化第 2 期：Skill 规则单源化 + 规则预筛

分支文档快照 · 同步于 2026-09-09 · 来源：feat/evidence-projection @ 91a7d1c · 原路径：docs/project/current/PENDING-short-context-eng-phase2.md。正文描述的是该分支的方案或进展，合入与验收状态以当前看板为准。

状态：待执行 前置：PR #8（evidence-projection）合入 develop 关联 issue：待开（[sql-dis-opt] 短上下文工程化第 2 期） 目标分支：feat/IK?-short-context-eng-phase2（issue 编号回填）

一、背景

OpenCode 端到端测试（0730 载荷 replay）证明：投影单独做完峰值仍达 98K，超过 50K 限制。

阶段 投影前 投影后 50K 内能否跑完
baseline + table_ctx 54K 36K ✅
规则匹配 + 子技能加载 66K 53K ❌
全流程完成 卡死 98K ❌

投影已把脚本 stdout 从约 40K 压到约 6K，剩余瓶颈是：

  • sql-distributed/SKILL.md 本体 30K，一次性进入上下文
  • 六个 Skill 合计 75.6K，路由、验收、投影和安全规则大量重复
  • 步骤 7 默认同时加载 generation + dml + ddl
  • pending_rules_1.md 32K 全量读入
  • 单会话多轮工具调用持续累积

关键判断：仅把主文件拆成 SKILL.md + references/ 不会自动省 token；如果后续仍读取全部 references，输入总量不变。本期必须减少实际加载的正文，并用加载记录和 effective input 验证。

第 2 期目标：通过“规则单源化 + 条件加载 + 规则预筛”，把完整流程峰值压到 50K 以内。

二、实施阶段

阶段 0：前置（已完成）

  • ✅ PR #8（evidence-projection）落地
  • ✅ OpenCode replay 验证（产物在 .tmp/message-replay-0730/session.json）

阶段 1：Skill 规则单源化 + 条件加载

目标：真正减少进入会话的 Skill 正文，不创建会在正常路径中被重新全量读取的 references。

1.1 当前重复

  • 主 Skill 与 skill-analysis 重复描述 DML / DDL 路由
  • 主 Skill 与 optimization-review 重复描述四态验收
  • 投影消费、分片键缺失、索引作用域、高风险改写等规则在 3–5 处复述
  • generation、dml、ddl 含重复 CLI、依赖说明和父流程字段枚举

1.2 改造方案

  1. 主 Skill 实际删减
  2. 只保留：工作流状态转移、命令骨架、环境/超时/回滚等不可丢失的安全底线
  3. 删除：长 JSON 示例、字段枚举、重复 CLI、常见错误、子 Skill 已拥有的领域规则
  4. 目标：sql-distributed/SKILL.md ≤ 5K bytes
  5. 投影成为门禁的唯一事实源
  6. baseline_facts / table_ctx_facts / execute_facts 输出当前 case 的 blocked_decisions、claim_constraints、known_unknowns
  7. 补充紧凑字段：routing_hint.skills[]、max_status、recommended_action
  8. Skill 只保留“不得违反投影门禁”，不再复述所有分支条件
  9. 禁止步骤 7 默认三连加载 
     必加载：sql-distributed-optimization-generation
 routing_hint 含 dml → 加载 sql-distributed-dml-rewrite
 routing_hint 含 ddl → 加载 sql-distributed-ddl-index
 未选中的子 Skill 禁止加载
  10. 路由与验收分别只保留一个权威实现
  11. 路由优先使用投影 routing_hint；若保留 skill-analysis，压到 ≤1.5K，主 Skill 不再复述
  12. 默认验收使用主流程 + execute_facts；optimization-review 仅用于显式独立审查，不进入默认路径
  13. 子 Skill 只保留不可机械化的领域策略
  14. generation ≤ 8K：输出契约、生成阶段安全底线
  15. dml-rewrite ≤ 3.5K：结构改写启发式
  16. ddl-index ≤ 6K：索引列序、作用域和冗余判断
  17. 删除父流程 CLI、依赖表、投影字段枚举和重复硬规则

1.3 Token 收益

正常路径注入的 Skill 正文预计从约 67.7K bytes 降到最坏约 24K bytes：

main 5K + route 1.5K + generation 8K + dml 3.5K + ddl 6K

这是正文删除和条件加载产生的收益，不依赖 agent “不要读 references”的自律。

commit：refactor(sql-dis-opt): 规则单源化并按路由加载子技能

验收：

  • 主 Skill ≤ 5K bytes；六个 Skill 合计 ≤ 45K bytes
  • 步骤 7 禁止默认三连加载，未命中的 dml / ddl 无加载记录
  • main 与 review 的验收、main 与 skill-analysis 的路由不再双写
  • replay 生成阶段 effective input：both 路由 ≤ 55K，单路由 ≤ 50K
  • scripts/test_evidence_projection.py 仍通过

阶段 2：规则匹配预筛 + 来源 SQL 拆分

目标：把 pending_rules_1.md（32K）从“全量加载”改为“预筛 + 命中后加载”。

具体逻辑细节待定：本节只锁定方向与边界（拆分规则文件 + 预筛 + 命中后加载正文）。特征抽取字段、匹配算法、索引 schema、脚本拆分方式、漏命中/过召回兜底等均未定稿；实施前另开设计确认，不以本节示例为最终契约。

  1. 拆分规则文件（目录形态示意，可调整） 
     skills/rule-match/rules/
 ├── _index.json                ← 触发特征索引（字段/体量待定）
 ├── P-001.md
 ├── ...
 └── P-012.md
  2. 预筛能力（脚本名、接口、算法待定；下表仅为占位）
  3. 从原 SQL 提取可匹配特征
  4. 对照索引返回候选规则 ID
  5. 未命中时不得全量加载全部 pending 规则正文
  6. 更新 rule-match/SKILL.md
  7. 先预筛，再只读取命中条目
  8. 默认禁止加载全部 pending 规则正文

commit（题目可随最终设计微调）：

  • refactor(rule-match): 拆分 pending 规则为单条目文件
  • feat(rule-match): 新增规则特征预筛

验收（硬目标；具体 case 断言待逻辑定稿后补）：

  • 正常路径不默认全量加载全部 pending 规则正文
  • rule-match 阶段 token 明显下降（目标约 ≤3K，以定稿后实测为准）
  • 逻辑定稿后补齐：代表性正例/反例回归，覆盖漏命中与过召回策略

阶段 3：工作流集成

目标：把投影、条件加载和规则预筛串成可验证的短上下文路径。

  1. 主流程更新
  2. 步骤 5.5：预筛后只读命中规则（预筛实现待阶段 2 定稿）
  3. 步骤 6：读取 routing_hint，未选中的子 Skill 禁止加载
  4. 步骤 7：generation 必载，dml / ddl 条件加载
  5. 步骤 4/5/9/10：只消费 stdout facts 与当前 case 的门禁字段
  6. 新增 scripts/test_short_context_workflow.py
  7. 用 .tmp/token-sim-0730/ 离线跑完整工作流
  8. 断言每阶段 stdout 是投影
  9. 断言无全量规则库读取、无默认三连 Skill 加载
  10. 统计实际加载文件和累计字节，阻止“搬文件但总输入不变”

commit：feat(sql-dis-opt): 集成短上下文条件加载工作流

阶段 4：端到端验证

目标：在 OpenCode replay 模式下跑完整 0730 case，证明峰值进入 50K。

  1. 切到最新代码，注入 SQLOPT_REPLAY_DIR 短路
  2. opencode run 跑完整 10 步
  3. 导出 session，统计每轮 effective input
  4. 对比第 1 期（98K）和第 2 期目标（≤50K）

commit：test(sql-dis-opt): 验证第 2 期短上下文工作流

验收：

  • 单轮 effective input 峰值 ≤50K
  • 完整 10 步无中断
  • 加载记录符合 route：无未选中的 Skill / 规则条目
  • 测试数据入仓（.tmp/phase2-replay-0730/session.json）

非范围

  • 子技能合并、precheck 并入 execute 等执行语义重构
  • 依赖 /compact 才能跑完；本期先证明条件加载本身的收益
  • comparison_mode=full 正确性修复
  • 将创造性 SQL 改写下沉为脚本

三、风险

风险 缓解
删除重复正文时误删安全底线 建立“安全底线唯一归属”清单；回归 env/timeout/rollback/shard-key 场景
routing_hint 错选导致漏加载子 Skill 多信号或不确定时返回 both；为 dml/ddl/both 建 golden cases
预筛漏命中 / 过召回 逻辑定稿后补正反例回归；不确定时偏向少读正文而非全量加载
agent 无视 route 继续全量加载 主 Skill 明令禁止；测试解析 session 的 Skill/Read 记录
阶段 1 both 路由仍略高于 50K 阶段 2 规则预筛叠加后再做最终验收，不用 references 搬运兜底
全流程仍超 50K 阶段 4 失败后另议上下文隔离子任务或显式 compact，不在本期静默扩范围

七、执行顺序

  1. 人：开 Gitee issue
  2. 人：PR #8 合入 develop
  3. Claude：从 develop 创建 phase2 分支
  4. Claude：阶段 1（规则单源化 + 条件加载）→ commit
  5. Claude：阶段 2（规则预筛）→ commit
  6. Claude：阶段 3（工作流集成）→ commit
  7. Claude：阶段 4（端到端验证）→ commit + 测试数据
  8. 人：review PR → 合入 develop
  9. Claude：给 develop 打 tag short-context-eng-v1