fable-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Research

Resolve external facts that can change the implementation, using current primary evidence instead of model memory.

依据当前的一手证据而非模型记忆，核实可能改变实现的外部事实。

Mission

使命

Research is not link collection. The output must be a decision-ready statement tied to the exact version, environment, or contract the repository will use.

研究不是链接收集。输出必须是一份可直接用于决策的陈述，并对应仓库将要使用的准确版本、环境或契约。

Activate When

适用场景

SDK/API signatures, limits, defaults, lifecycle semantics, or compatibility may have changed;
a design depends on current cloud/provider behavior;
the repository pins a version that may differ from current docs;
multiple official sources appear to disagree;
an error may come from a documented breaking change or deprecation;
a standard/RFC/security requirement must be interpreted precisely.

SDK/API 签名、限制、默认值、生命周期语义或兼容性可能已经发生变化；
设计依赖当前的云服务/提供商行为；
仓库固定的版本可能与当前文档不同；
多个官方来源似乎存在分歧；
错误可能源于文档中记录的破坏性变更或弃用；
需要精确解释某项标准/RFC/安全要求。

Do Not Activate When

不适用场景

the fact is repository-local (
```
fable-discover
```
);
the implementation is already grounded and only needs execution (
```
fable-execute
```
/
```
fable-tdd
```
);
the task is general brainstorming where no external claim changes the decision.

事实仅存在于仓库本地（
```
fable-discover
```
）；
实现已有充分依据，仅需执行（
```
fable-execute
```
/
```
fable-tdd
```
）；
任务属于一般性头脑风暴，没有任何外部事实主张会影响决策。

Research Classification

研究分类

Classify the question first.

Question type	Best primary evidence	Extra risk
API signature	versioned official docs + source/types	docs may show latest, repo pins older
Runtime behavior	official docs + upstream implementation/tests	marketing docs may omit edge behavior
Compatibility	release notes/changelog + version matrix	transitive dependency constraints
Standard/protocol	normative spec/RFC	examples may be non-normative
Cloud/product limit	current vendor docs	region/tier/account differences
Security guidance	official security docs/advisories	stale blog summaries
Deprecation/migration	migration guide + release notes	old and new APIs coexist

首先对问题进行分类。

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

Protocol

协议

Stage 1 — Turn the task into answerable claims

阶段 1 — 将任务转化为可回答的事实主张

Break a broad request into the smallest external claims that can affect design.

Bad: "Research the new SDK."

Good:

Does version 4.2 expose streaming tool-call deltas?
Which parameter enables them?
Is the callback ordered?
What minimum runtime version is required?

将宽泛的请求拆分为可能影响设计的最小外部事实主张。

坏示例：“调研新版 SDK。”

好示例：

4.2 版本是否提供流式 tool-call 增量？
哪个参数可以启用它们？
callback 是否按顺序执行？
所需的最低运行时版本是什么？

Stage 2 — Bind to repository reality

阶段 2 — 与仓库实际情况绑定

Before accepting current docs as applicable, record:

package/version actually used;
runtime/language version;
relevant feature flags/tier/region if applicable;
whether the repository uses generated types or a wrapper that changes the public contract.

在接受当前文档作为适用依据之前，需记录：

实际使用的 package/版本；
运行时/语言版本；
相关 feature flag/套餐/地区（如适用）；
仓库是否使用生成的类型，或使用会改变公开契约的 wrapper。

Stage 3 — Use a source hierarchy

阶段 3 — 使用来源层级

Prefer, in order when available:

normative specification or official versioned reference;
official upstream source/types/tests;
official release notes/migration guides/advisories;
vendor examples authored for the relevant version;
secondary sources only as leads.

Never use an unsourced search snippet as final evidence.

如有以下来源，按此顺序优先使用：

规范性规范或官方版本化参考；
官方上游源代码/类型/测试；
官方发行说明/迁移指南/安全公告；
由厂商为相关版本编写的示例；
二手来源仅可作为线索。

绝不将无来源的搜索摘要作为最终证据。

Stage 4 — Reconcile version and source conflicts

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

If latest docs disagree with the pinned package:

inspect versioned docs/release notes/source for the pinned version;
state the delta explicitly;
do not silently recommend latest syntax to an older lockfile.

If two official sources disagree, prefer the one closest to executable truth for the exact version, and report the conflict.

如果最新文档与仓库固定的 package 存在分歧：

检查针对所固定版本的版本化文档/发行说明/源代码；
明确说明差异；
不要在未加说明的情况下，向较旧的 lockfile 推荐最新语法。

如果两个官方来源存在分歧，优先采用最接近特定版本可执行事实的来源，并报告冲突。

Stage 5 — Separate fact from interpretation

阶段 5 — 区分事实与解释

Record:

Fact: what the source establishes;
Applicability: why it applies to this repo/version;
Interpretation: what it means for the design;
Confidence: measured / strongly supported / unresolved.

记录：

事实：来源确立了什么；
适用性：为什么它适用于此仓库/版本；
解释：这对设计意味着什么；
置信度：已衡量 / 有充分依据 / 尚未解决。

Stage 6 — Stop when the decision is grounded

阶段 6 — 在决策有依据时停止

Do not continue reading once all load-bearing external claims are resolved and the next action is safe.

一旦所有关键外部事实主张均已解决且下一步行动安全，就停止继续阅读。

Decision Rules

决策规则

If a fact could have changed since model training, verify it rather than recall it.
If docs are unversioned and the repo pins an older version, inspect source/types/changelog for that exact version.
If an official quickstart conflicts with a normative reference, do not flatten the disagreement; determine which governs the target behavior.
If behavior depends on account/tier/region, label that dependency and avoid universal claims.
If no primary source is available, report the evidence gap and use upstream code/types/tests as the next-best source; never invent missing parameters.
If the answer changes architecture, hand off to
```
fable-plan
```
; if it simply confirms a bounded implementation contract, hand off to
```
fable-tdd
```
or
```
fable-execute
```
.

如果某项事实在模型训练后可能已经发生变化，应予以核实，而不是凭记忆作答。
如果文档未版本化且仓库固定了较旧版本，则检查该准确版本的源代码/类型/变更日志。
如果官方快速入门与规范性参考冲突，不要抹平分歧；应确定哪一方对目标行为具有约束力。
如果行为取决于账户/套餐/地区，应标明这种依赖关系，避免作出普遍性结论。
如果没有一手来源，应报告证据缺口，并使用上游代码/类型/测试作为次优来源；绝不臆造缺失的参数。
如果答案会改变架构，则移交至
```
fable-plan
```
；如果只是确认了边界明确的实现契约，则移交至
```
fable-tdd
```
或
```
fable-execute
```
。

Invariants

不变量

Every load-bearing external claim has a source.
Source applicability includes version/context, not just URL authority.
Quotes/signatures are kept short and exact; conclusions are written in the agent's own words.
Secondary sources do not override accessible primary sources.
Conflicting evidence remains visible until resolved.

每个关键外部事实主张都有来源。
来源的适用性必须包含版本/上下文，而不能仅依据 URL 的权威性。
引文/签名应保持简短且准确；结论应以 Agent 自己的措辞表述。
二手来源不得凌驾于可获取的一手来源之上。
冲突证据在得到解决前必须保持可见。

Failure Taxonomy

失败分类

Freshness failure

时效性失败

The source is official but stale/deprecated. Find versioned/current material and release history.

来源虽然官方，但已过时或被弃用。查找版本化/当前资料和发布历史。

Version mismatch

版本不匹配

The repo and docs describe different versions. Reconcile against the lockfile/package metadata.

仓库与文档描述的是不同版本。根据 lockfile/package 元数据进行调和。

Authority mismatch

权威性不匹配

A blog/example contradicts normative docs or upstream source. Demote the weaker source.

博客/示例与规范性文档/上游源代码相矛盾。降低较弱来源的优先级。

Context mismatch

上下文不匹配

The claim differs by region, tier, runtime, platform, or feature flag. Scope the conclusion.

事实主张因地区、套餐、运行时、平台或 feature flag 而异。应限定结论的适用范围。

Interpretation ambiguity

解释歧义

The source is clear but its implication for the repository is not. Hand the unresolved design question to

fable-plan

rather than pretending the research answered it.

来源本身清晰，但其对仓库的影响并不明确。将尚未解决的设计问题移交至

fable-plan

，不要假装研究已经回答了该问题。

Anti-Patterns

反模式

asking a search engine for a signature and copying the snippet;
citing the latest docs without checking the pinned version;
collecting many links without a decision-ready conclusion;
using model memory because the API "probably hasn't changed";
quoting a source without saying why it applies;
hiding official-source disagreement;
continuing research after every load-bearing claim is resolved.

向搜索引擎询问签名并直接复制搜索摘要；
引用最新文档，却不核对仓库固定的版本；
收集大量链接，却未给出可直接用于决策的结论；
因为 API“可能没有变化”而依赖模型记忆；
引用来源，却不说明其为何适用；
掩盖官方来源之间的分歧；
在所有关键事实主张均已解决后仍继续研究。

Research Packet / Handoff

研究资料包 / 移交

text

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

text

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

Completion Criteria

完成标准

Research is complete when:

the exact external claim is answered for the repository's actual context;
evidence is primary or the absence of primary evidence is explicit;
version conflicts are reconciled;
the implementation/design implication is stated without overclaiming;
no load-bearing parameter or semantic remains ambiguous.

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

已针对仓库的实际上下文回答确切的外部事实主张；
证据来自一手来源，或已明确说明不存在一手证据；
版本冲突已得到调和；
已在不过度推断的前提下说明对实现/设计的影响；
不存在任何关键参数或语义歧义。

Progressive Resources

渐进式资源

Deep guide:

references/source-reconciliation-playbook.md

Existing hierarchy:
```
references/primary-source-hierarchy.md
```
Example:
```
examples/research-api-specs.md
```

深度指南：

references/source-reconciliation-playbook.md

现有来源层级：
```
references/primary-source-hierarchy.md
```
示例：
```
examples/research-api-specs.md
```