fable-research

Fable 研究

使用当前的一手证据，而非模型记忆，核实可能影响实现的外部事实。

使命

研究不是收集链接。输出必须是一项可用于决策的陈述，并与仓库将使用的确切版本、环境或约定相关联。

适用情形

• SDK/API 签名、限制、默认值、生命周期语义或兼容性可能已发生变化；
• 设计依赖当前云服务商的行为；
• 仓库锁定的版本可能与当前文档中的版本不同；
• 多个官方来源似乎相互矛盾；
• 错误可能源于有文档记录的破坏性变更或弃用；
• 必须准确解读标准/RFC/安全要求。

不适用情形

• 事实仅与仓库本身有关（fable-discover）；
• 实现已有依据，只需执行（fable-execute/fable-tdd）；
• 任务是一般性头脑风暴，没有外部声明会影响决策。

研究分类

先对问题进行分类。

问题类型	最佳一手证据	额外风险
API 签名	带版本的官方文档 + 源码/类型	文档可能展示的是最新版本，而仓库锁定的是旧版本
运行时行为	官方文档 + 上游实现/测试	营销文档可能省略边缘行为
兼容性	发布说明/变更日志 + 版本矩阵	传递依赖约束
标准/协议	规范性规范/RFC	示例可能不具规范效力
云服务/产品限制	服务商当前文档	可能因区域/层级/账户而异
安全指导	官方安全文档/公告	博客摘要可能过时
弃用/迁移	迁移指南 + 发布说明	新旧 API 可能并存

流程

阶段 1 — 将任务转化为可回答的声明

把宽泛的请求拆分成可能影响设计的最小外部声明。

不好：“研究新 SDK。”

好：

• 4.2 版是否提供工具调用增量流？
• 哪个参数可启用该功能？
• 回调是否有序？
• 最低运行时版本要求是什么？

阶段 2 — 结合仓库实际情况

在采信当前文档适用于仓库之前，记录：

• 实际使用的软件包/版本；
• 运行时/语言版本；
• 相关功能标志/层级/区域（如适用）；
• 仓库使用的是生成的类型，还是会改变公共约定的封装层。

阶段 3 — 采用来源层级

在可用时，按以下顺序优先选择：

1. 规范性规范或官方版本化参考资料；
2. 官方上游源码/类型/测试；
3. 官方发布说明/迁移指南/公告；
4. 针对相关版本编写的服务商示例；
5. 次要来源仅可用作线索。

切勿将未经来源支持的搜索摘要作为最终证据。

阶段 4 — 调和版本和来源冲突

如果最新文档与锁定的软件包版本不一致：

• 检查锁定版本对应的版本化文档/发布说明/源码；
• 明确说明差异；
• 不要在旧版锁文件上悄然推荐最新语法。

如果两个官方来源互相矛盾，应优先采用最接近确切版本可执行事实的来源，并报告冲突。

阶段 5 — 区分事实与解读

记录：

• 事实：来源证实了什么；
• 适用性：它为何适用于此仓库/版本；
• 解读：这对设计意味着什么；
• 置信度：已验证 / 有充分依据 / 尚无定论。

阶段 6 — 决策有据后停止

一旦所有关键外部声明都已得到解决，且下一步操作安全，就不要继续查阅。

决策规则

• 如果某项事实可能在模型训练后发生变化，请核实，而不要凭记忆作答。
• 如果文档未标明版本，而代码仓库固定使用较旧版本，请检查该确切版本的源代码、类型定义或变更日志。
• 如果官方快速入门指南与规范性参考文档相冲突，不要掩盖分歧；应确定哪一方决定目标行为。
• 如果行为取决于账户、套餐或区域，请标明这一依赖关系，避免作出普遍性断言。
• 如果没有可用的一手来源，请说明证据缺口，并将上游代码、类型定义或测试作为次优来源；绝不要编造缺失的参数。
• 如果答案会改变架构，请交由 fable-plan 处理；如果只是确认范围明确的实现约定，请交由 fable-tdd 或 fable-execute 处理。

不变量

• 每项关键外部主张都有来源。
• 来源的适用性不仅取决于 URL 的权威性，还包括版本和上下文。
• 引文和签名应简短准确；结论应以 Agent 自己的措辞撰写。
• 在可访问一手来源时，二手来源不得凌驾于一手来源之上。
• 冲突证据应保持可见，直到得到解决。

失败分类

时效性问题

来源是官方的，但已过时或弃用。请查找有版本标记的当前资料和发布历史。

版本不匹配

代码仓库与文档描述的版本不同。请根据锁文件或软件包元数据进行协调。

权威性不匹配

博客或示例与规范性文档或上游源代码相矛盾。请降低较弱来源的权重。

上下文不匹配

主张因区域、套餐、运行时、平台或功能标志而异。请明确结论的适用范围。

解释存在歧义

来源内容明确，但其对代码仓库的影响不明确。请将未解决的设计问题交由 fable-plan 处理，而不要假装研究已经得出答案。

反模式

• 向搜索引擎查询签名并照抄摘要；
• 引用最新文档，却不检查固定使用的版本；
• 收集大量链接，却不给出可直接用于决策的结论；
• 因为 API“可能没变”就依赖模型记忆；
• 引用来源，却不说明其适用原因；
• 隐瞒官方来源之间的分歧；
• 在所有关键主张都已解决后仍继续研究。

研究资料包 / 交接

Question:
Repository version/context:
Source-backed facts:
- fact → primary source → applicability
Conflicts/version deltas:
Interpretation for implementation:
Confidence / unresolved:
Recommended next Skill:

完成标准

满足以下条件时，研究即告完成：

• 已针对代码仓库的实际上下文回答确切的外部主张；
• 证据来自一手来源，或已明确说明缺少一手证据；
• 版本冲突已协调解决；
• 已说明对实现或设计的影响，且没有夸大结论；
• 没有任何关键参数或语义仍存在歧义。

渐进式资源

• 深入指南：references/source-reconciliation-playbook.md
• 现有来源层级：references/primary-source-hierarchy.md
• 示例：examples/research-api-specs.md