docs: propose analysis planning architecture

[Wzh20040721]

目的

这是一个仅包含文档的 RFC，用于在开始生产代码改造前征求维护者意见。

当前分析方法选择分散在 Skill 检索、Prompt、LLM 判断、分析注册表和图表规则中。本提案建议增加统一、结构化且可验证的 AnalysisPlan，让 LLM 负责语义理解与有限候选生成，让确定性代码负责数据适用性、参数、置信度和澄清边界。

这份 RFC 提议什么

• 引入 AnalysisIntent、DataContext、AnalysisCapability、AnalysisPlan、AnalysisResult 和 PresentationPlan 契约。
• 扩展分析与可视化注册表，使其描述输入类型、前置条件、禁用条件、诊断和输出契约，而不只描述执行入口。
• 统一 execute / clarify / blocked / fallback 决策和 reason codes。
• 保持现有 Skill、run_analysis、select_charts 和 generate_chart 公共入口兼容。
• 不提交独立的运行时影子 Planner PR；维护者认可方向后，先在贡献者本地完成离线影子对照并记录结果，达到门槛后才提交生产代码 PR。

为什么这样做

• 在执行前发现方法与字段类型、样本量或数据质量不兼容的问题。
• 让“为什么选择这个方法和呈现方式”可解释、可测试、可审计。
• 统一低置信度时的澄清行为，减少 LLM 直接猜测。
• 让呈现形式由业务问题、数据形状、分析结果和受众共同决定。
• 减少 Prompt、Skill、命令和注册表之间的重复规则与维护漂移。
• 先提供本地基线和对照证据，不让上游或真实用户承担实验性双 Planner 风险。

本 PR 的实际变更

• 仅新增 docs/15-analysis-planning-architecture-rfc.md。
• 没有修改生产代码、测试、工具 Schema、模型调用或运行行为。
• 没有开始实现 Planner。

希望维护者确认

1. 是否认可统一 AnalysisPlan 和能力注册表作为后续演进方向？
2. 是否接受在贡献者本地完成离线影子评测，并随未来代码 PR 附上结果摘要，而不先合并运行时影子路径？
3. 如果方向可行，希望后续代码使用一个完整 PR，还是按数据契约、能力注册表、Planner 和 Presentation Planner 拆分提交？

如果方向或范围不符合项目路线，欢迎直接指出；在得到确认前不会开始生产代码改造。

验证

• git diff --check upstream/main...HEAD
• Git diff 仅包含一份 RFC 文档
• 文档无占位符，Mermaid/代码围栏闭合，引用的当前代码路径均存在

[Zafer-Liu]

感谢这份高质量的 RFC，方向我完全认可。以下是维护者意见：

✅ 方向认可

• 认可引入统一 AnalysisPlan + 能力注册表作为分析决策真相源；
• 认可「LLM 负责语义理解、确定性代码负责验证」的边界划分；
• 认可本地离线影子评测 + 门槛的方式，不先合并运行时影子路径。

📝 修改意见（请修订后重新提交，我会审查并合并）

1. 命名统一：正文混用了 select_chart（工具名，单数）与 select_charts（函数名，复数），请统一并注明两者区别，避免后续实现混淆。
2. Skill 硬约束去重策略：2.7 与 8.1 之间需要明确——能力注册表接管硬约束后，Skill 中重复的硬约束如何迁移/弃用，避免形成新的漂移点。
3. 评测集审题：冻结评测集建议由维护者抽审（或提供部分维护者用例），避免「自己出题自己考」的偏差。
4. reason_codes 枚举：既然强调稳定 reason_codes 便于测试，建议在 RFC 阶段先列出初版枚举。
5. 拆分范围：建议 Analysis 侧（契约 + 能力元数据 + validator）先行，Presentation Planner 拆到后续独立 PR——chart_selector 刚经 PR fix: improve chart recommendation confidence #51 改造，短期内再动会叠加风险。

方向没问题，按上述意见修订后重新提交即可。

[Wzh20040721]

已按五项意见完成 RFC 修订，commit：3b87759。

1. 命名边界：第 2.8 节明确 select_chart 是 Agent 对外工具名，select_charts(...) 是 LLM/chart_selector.py 内部多候选函数，_tool_select_chart(...) 是现有适配层；第 8.3 节明确首期保持三者名称和调用关系不变。
2. Skill 硬约束迁移：第 8.1–8.2 节划分 Registry、Skill、Prompt 和分析模块的规则所有权，规定 Registry/Validator 为硬约束唯一真相源；增加盘点、双轨一致性测试、禁止 Skill 放宽、删除重复约束和持续漂移检测。
3. 冻结评测集抽审：第 9.2 节加入 canonical JSONL 版本与 SHA-256、冻结后变更重跑，以及两种治理方案：维护者分层抽审至少 20% 且不少于 20 例，或提供不少于 20 个隐藏/保留案例；同时规定防逐例硬编码和不泄漏隐藏数据。请确认更适合采用哪一种；如果暂时无法提供隐藏案例，是否接受分层抽审方案。
4. 稳定 reason_codes：第 7 节定义 analysis-reason-codes/v1 初版枚举，覆盖目标/显式指定、字段类型、样本量、数据质量、方法假设、语义低置信度、意图歧义、低候选分差、缺字段、非法参数、缺依赖、无合法候选和描述性降级；同时规定同 major 只追加、破坏性变化升 major、未知值保留和动态值进入 validation_errors。
5. 首期范围：第 3、4、10、12 节将首期收缩为 Analysis 契约、能力元数据、Candidate Planner、Validator、统一决策、AnalysisResult、兼容适配和本地离线评测。首期实线主链终止于 AnalysisResult；Presentation Planner、Visualization Registry、chart_selector 重构及报告/看板呈现决策移至后续独立 RFC/PR。AnalysisResult 后仍兼容交接给现有呈现链，不删除现有功能。

第 9.4 节给出了待确认的建议门槛；当前没有基线，因此 RFC 没有声称或伪造提升结果。本 PR 仍只修改 RFC 文档，不含生产代码。

请重新审查，并确认评测抽审方式、建议门槛，以及是否允许在 PR 合并后（或明确许可后）开始本地 Analysis 侧实现与评测。

[Zafer-Liu]

RFC 方向认可，但请调整提交方式。

提交方式调整（关键）

不接受纯文档单文件 RFC PR。请在本地完成 Analysis 侧代码实现——数据契约、能力元数据、Candidate Planner、确定性 Validator、统一决策、AnalysisResult、兼容适配与本地离线评测——然后连同这份 RFC 文档一起提交为一个完整 PR，再请求审查。本 PR（纯文档）请保持或关闭。