跳转至

Issue：分布式 SQL 优化工作流 stdout 投影，破解 50K 上下文墙

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

状态：已提交 Gitee（URL 待回填） 优先级：P0（阻塞分布式端到端自动化在 50K 上下文上限下跑通） 来源：0730 实测会话 gcsdb_0009 步骤 5.5 撞 token 上限 分支：feat/evidence-projection（实现已落地） 技术规格：docs/project/current/IK6EG0-tech-spec.md 离线回归：python3 scripts/test_evidence_projection.py 模拟产物：.tmp/token-sim-0730/

一、问题现象

0730 在 gcsdb_0009 案例跑到步骤 5.5（规则匹配）时，输入 token 数突破 50K，agent 无法继续读规则文件、整个流程卡死。

token 实测曲线（来源：会话导出 step-finish.tokens.input）：

阶段 累计 input tokens 单段增量
工作流启动（脚手架 + SKILL.md） 15,995 +16.0k
步骤 1–3 + 用户交互 25,126 +9k
baseline 脚本 stdout 入上下文 40,176 +15,050
table_ctx 脚本 stdout 入上下文 54,424 +12,574
读 rule-match SKILL 55,350 +926
再读 pending 规则（预估） ~66–69k 超 50K，撞墙

卡死点不在规则文件本身——而是 baseline 和 table_ctx 两个脚本把完整 JSON 全量打印到 stdout，OpenCode 把 stdout 自动注入对话上下文，每次 +12~15K，两次就把余量吃光。

二、根因

skills/sql-dis-opt/sql-distributed/scripts/_lib.py::output_json 同时干了两件事：

  1. 把完整数据写到磁盘（必须，后续步骤要拿全量做比较）
  2. 把同一份完整数据再打印一遍到 stdout（这进 agent 上下文）

问题在于第 2 步——stdout 是 agent 上下文的来源，但全量 JSON 里大部分字段对推进分析毫无帮助：

  • baseline：50 行业务结果数据（rows），列清单就够了
  • table_ctx：拼接的表 DDL/分区 dump 文本（27 KB），保留 distributed_context 摘要就够
  • execute：优化后的结果数据行（~60 KB），比较结论就够

agent 真正需要的只是「结论性事实」：耗时、行数、列名、分布式算子特征、结果一致性判定。原始数据只在「需要核对具体某行」时才有价值。

三、可行解决方向

磁盘全量、stdout 投影：脚本继续把完整证据落盘（不动），stdout 改为只打印结构化的事实投影（schema sqlopt-evidence/v1）。agent 默认消费投影推进分析、生成、验收；仅在投影显式标注证据缺口时才回退读磁盘全量。

设计原则：事实由脚本钉死、策略由 agent 发挥——投影必须是脚本机械映射的结构化字段，不得由 LLM 自由摘要（0730 试跑里出现过 has_full_shard_scan=false 被模型写成"全扫"的事实篡改）。

具体投影字段、回退触发条件、软门禁规则、实测收益、为何不采用 LLM 摘要 / /compact 等反方案对比，详见 PR 描述。

四、验收标准

  • 传 --output 时：磁盘全量、stdout 投影、投影含 evidence_ref
  • 不传 --output：stdout 仍走投影（agent 调用脚本的目的就是分析，原始 rows 对分析无价值；此为预期行为变更，PR 描述中需明确）
  • baseline 磁盘仍含完整 result.rows；execute 比较链路不回归
  • table_ctx stdout 保留 distributed_context 原样，砍掉 table_info 全文与 column_selectivity_text
  • execute stdout 砍掉 optimized_result.rows，新增 verdict / comparison_strength
  • 有 table_ctx_dir 时 tables_schema 含 indexes 列序（回归：scripts/test_evidence_projection.py）
  • SKILL 步骤 4/5/9/10 写明：策略依据 facts、缺证据走 evidence_ref 回读
  • 0730 同载荷重放：三阶段投影合计 << 50K（量化目标见 PR 描述实测）
  • 不引入联网安装 / 不改比较算法本体

五、非范围

以下不在本 issue 内，分别单开：

  • 规则预筛 / feature_index.json：rule-match 在投影之上再做一层预筛，进一步压低规则文件本身占用
  • 总控 SKILL.md 大幅瘦身：与投影解耦
  • comparison_mode=full 实为采样等价的正确性修复：投影只是暴露了 comparison_strength，算法本身的修订另议
  • pending_rules_1.md 文本修订：归 IK1CK3