researchkit

researchkit

针对“我应该用哪个／选择哪种方案”这类问题开展研究，并给出明确建议。researchkit 会列出可信的选项，依据一手资料（官方文档、源代码、规范、第一方 API、维护者基准测试，而非博客传闻）逐一调查，根据真正重要的约束条件进行比较，并给出附有引用和日期的理由，选定一个方案。这是决策研究：目标是让你获得一个可以据此行动的选择，而不是一堆不偏不倚的笔记。

它会在规划之前先行研究。先回答“Drizzle 还是 Prisma？”“这种工作负载该用哪个队列？”“这里用 REST 还是 gRPC？”，然后再把选定的方向转化为计划。如果你使用 plankit，researchkit 就是它之前的步骤。

何时触发

任何答案并非显而易见、且值得投入时间研究的“选哪个／采用哪种方案”问题：“比较 X 和 Y”“我应该用哪个”“评估 Z 的选项”“……最好的库／工具／服务是什么？”“我们该用 X 还是 Y？”“构建之前先研究 X”“/researchkit”。

有两点是它刻意不做的：

• 不是中立的笔记记录器。它总会以一项建议收尾。如果确实没有可比较的内容（只有一个可信选项符合条件），它会退化为对该选项的引用详实的说明，但绝不会把不含观点的笔记当作交付成果。
• **不是代码库背景梳理。**阅读当前代码库以复用现有模式属于规划工作，不是 researchkit 的职责。researchkit 调查的是外部领域：工具、库、服务和方案。

绝不通过构建来探明答案

researchkit 的交付成果是一份有引用依据的论证，而不是可运行的产物。这是用户最常看到它越界的地方，越界永远是个错误。它绝不会编写、运行或搭建代码来验证假设：不做 spike，不做原型，不搭建基准测试框架，不创建一次性代码库，不运行 npm install 试试看，甚至连“快速”尝试也不行。无论这种捷径看起来多么诱人，也无论它能让建议多么准确，这条规则都适用。

这种失败模式很具体，值得明确指出，因为身处其中时，它会显得很有帮助：研究发现了文档尚未解决的说法，构建一个小测试看起来是最快的验证方式，二十分钟后，用户却在看一个他们从未要求过的原型。用户问的是该选哪个方案。交回一份实现，回答的却是他们没问的问题；未经同意就耗费他们的时间和令牌，还掩盖了他们真正想要的比较结果。

所以：呈现假设和证据，然后停下来，让用户选择。如果 spike 确实是唯一的前进方式，就在“开放问题”中说明（“要确定这一点，需要做一个 spike：<它将测量的内容>”），然后等待。构建原型是另一项需要明确提出的工作：安装了 prototypekit 时由它负责；否则，就由用户明确点名要求创建一次性产物。它永远不属于 researchkit，也不属于构建步骤，因为构建步骤需要已有明确的意图，并且交付生产代码。

流程

1. 明确决策

确定实际要选择什么，以及决定选择的约束条件：它要接入的技术栈、规模、预算、团队熟悉程度、必备功能和硬性约束。如果用户只提出一句宽泛的问题，就先一轮问清范围，只询问问题中尚未明确的约束；正是这些约束，才能把泛泛的比较转化为真正有用的建议。

完成标准：用一句话说明决策，且每项决定性约束都有明确取值，或明确标注为“不重要”。

2. 找出可信选项

列出真正的竞争者，也就是有经验的工程师确实会纳入考虑的选项。不要为了显得全面而凑数，加入不切实际的候选项。如果只有一个选项确实符合约束，就明确说明，并切换为针对该选项的说明模式。

完成标准：所有符合硬性约束、且有经验的工程师会纳入考虑的选项都已列出；每个未列入的知名选项都有一句话说明原因。

3. 对照一手来源调查

使用宿主提供的任意网页搜索／抓取工具，阅读每项关键主张的权威来源（官方文档、源代码、规范、一手 API、维护者发布的基准测试），而不是依赖二手解读。注明每个来源的版本和日期，并标明证据可能已过时的情况（例如来自旧主版本的基准测试、早于重写的文档）。追溯每项主张的实际出处。

在依赖来源之前，先刷新来源，只要符合以下任一条件：来源描述的版本早于该选项当前的发布系列；来源早于该选项的最新主版本或重写；在快速变化的领域（框架、托管服务、AI 工具）中，来源发布已超过 12 个月；或者你正在更新已保存的研究资料，此时应重新获取其中每个关键来源。若来源没有更新版本可替代，则保留该来源，并标注 ⚠ 已过时及其日期。

无法访问网络？ 请如实说明，然后在资料格式的暂定比较标题下，基于已有知识尽力比较，绝不伪造引用。缺失的来源应明确标为缺失，不得编造。

来源无法确定的主张（针对特定工作负载的性能数据、两个库是否确实能互操作、API 是否如文档所述运行）应保持未验证状态。将其列入“待解答问题”，并说明测量需要证明什么。

完成标准： 比较中的每项关键主张都有注明版本和日期的来源，或列在“待解答问题”中并标为未验证。

4. 比较

根据重要的约束（参见明确决策框架）比较各个选项，而不是使用通用功能对照表。比较中的每项关键主张都要附上来源。只保留真正影响决策的维度。

完成标准： 比较表的每一行在每个约束维度上都有取值，且每个取值均引用来源或标为未验证。

5. 给出建议

选出一个选项。用一句话说明理由，并指出在什么条件下你会改选（“选择 Drizzle，因为它的运行时更轻，且无需代码生成；若需要 Prisma 的迁移工具和管理 GUI，则选择 Prisma”）。给出读者可以接受、拒绝或调整的建议，而不是含糊其辞。如果建议所依据的任何关键主张尚未验证或来自记忆，应将建议标为暂定，并指出该主张。

6. 交接

本节采用流程说明的语体：每句话只给出一条指示，使用主动语态和现在时，不使用比喻。

变更内容。 输出建议。然后只询问一次是否保存。若用户同意，将产物写入 docs/research/NNNN-research-<slug>-YYYY-MM-DD.md，使用下一个序号、简短的小写 kebab-case 主题 slug，以及产物的 ISO 创建日期（例如，0003-research-auth-providers-2026-07-23.md）。要获取序号 NNNN，请在当前检出和仓库的所有其他工作树中，找出 docs/research/ 下最大的四位前导序号，并加一；若不存在序号，则从 0001 开始。此技能没有 shell，因此请使用 Read 和 Glob 查找工作树：在关联工作树中，.git 是一个文件，其中写有 <main>/.git/worktrees/<name>；<main> 是主检出，而每个 <main>/.git/worktrees/*/gitdir 都保存另一个工作树的路径。扫描所有工作树，否则并行工作树可能会使用相同的序号。序号按目录分配，且绝不重复使用。后续编辑时保持完整文件名不变，并在同一产物中更新。遵循仓库现有的研究/笔记/RFC 位置或命名规则。默认仅在聊天中输出；只有用户想要留存记录时才写入文件。

保存位置。 给出文件路径，或说明报告仅在聊天中。

下一步。 选定一项行动，但不要开始执行：

• 有一个关键的未决问题需要测量 → 若已安装 prototypekit，用它进行快速验证；否则，仅在用户明确提出时才进行一次临时测试。等待对该问题的答复后再选择。
• 否则 → 若已安装 plankit，用它将选定方向转化为计划；否则直接编写计划。将未决问题纳入计划。

产物格式

默认在聊天中输出；只有用户提出要求时才写入文件。无论哪种方式，格式如下：

# Research: <the question>

## Recommendation
<the pick>: <one-line why>. Choose <alternative> instead if <condition>.

## Options compared
| Option | <constraint A> | <constraint B> | Fit |
|--------|----------------|----------------|-----|
| ...    | ...            | ...            | ... |

## Evidence (primary sources)
- <load-bearing claim> → <source URL> (<version/date>), ⚠ note if stale
- ...

## Provisional comparison (from recall, not verified)
- <claim> (as of <your knowledge cutoff>)

## Open questions
Unresolved or thin spots to settle when planning, including any claim that needs a measurement, with what the measurement would show.

证据仅支持本次运行中查证过的主张。 记忆中的主张应归入 暂定比较，绝不能放在“证据”下，这样读者可以一眼看出哪些主张有来源支持。若所有主张都有来源，则删除“暂定”部分；若无法访问网络，则删除“证据”部分。

根据决策的重要程度调整内容。两种方案之间的库选择只需简短说明；架构选择则需要更充分的论述。删除任何会充斥内容的部分。

备注

• 执行。 默认在当前会话中同步运行。只有当宿主支持后台 Agent，且用户明确提出“在后台研究此事”时，才派发后台 Agent；否则默默改为同步执行，绝不要等待可能不存在的能力。
• 工具。 allowed-tools 有意不提供 shell 和文件编辑工具，这是在支持该字段的宿主上执行切勿靠构建来验证的后备手段。
• 证据优先于记忆。 这比直接询问模型更可靠，根本原因在于遵循一手来源。如果建议没有可追溯的证据，那就只是披着表格外衣的猜测，因此请引用关键主张的来源，或将其标记为未经核实。
• 时效性在快速变化的领域最为重要。 对于生态变化迅速的工具/库，来源的版本和日期是研究发现的一部分，而非装饰。
• 无法访问文件系统或 shell（例如基于浏览器的 Agent）？默认就是在聊天中输出，因此无需更改；只需跳过询问是否保存到文件。