research-with-sources

研究——收集来源并撰写初步发现

此技能提供流程指导。平台的 /open-knowledge 技能（读取／写入／预览／链接／依据规则）仍适用于所有 Markdown 操作——本流程是在其基础上补充的。

围绕某个主题开展以证据为依据的研究，并在 research/ 下撰写一篇初步研究文章。文章为初步内容，而非权威定稿：研究文章记录某一时点的发现、权衡和未决问题。只有当决策趋于明确时，才通过 /consolidate-notes 技能将其提升为权威文章。

内容目录是已解析的 content.dir——如果你还不知道该目录，请使用 config({ key: 'content.dir' }) 读取。以下路径均相对于该目录。

三种路径

• 路径 A——研究文章（默认）： 一篇持久的初步文章，带有 status: draft，并在 frontmatter 中以内联 sources: 列表指向通过摄取流程保存的原始来源。除非用户明确选择不创建文章，否则默认采用此路径。
• 路径 B——直接回答： 仅在对话中提供研究发现。需要用户明确提出请求（例如“直接告诉我”“不需要文档”“快速回答”）。
• 路径 C——更新现有研究： 对现有研究文章进行有针对性的补充／更正。用户提及现有研究文档，或表示“更新／刷新／扩展”时采用此路径。

路径 A 为默认路径，因为初步文章会随着时间不断积累；口头回答则不会。

兼容旧格式读取： 现有文章可能使用 status: provisional，并在 sources: 下使用字符串路径。将其视为草稿研究文章和来源资源。不要批量重写；新建内容使用以下 OKF 格式。

自主模式

模式	行为	进入方式
监督模式（默认）	在范围界定关卡处暂停，等待用户确认研究标准。交互式处理覆盖范围决策。	用户主导会话时默认采用。
无交互模式	提出研究标准后自动确认。自动选择路由决策。跳过交互式提示。其他所有关卡（扫描、分析、验证、依据）仍须执行。	用户明确表示“别等我”“直接继续”“以无交互模式运行”——或处于非交互式容器环境时。

在无交互模式下，提出研究标准后立即继续。提出标准后，将范围界定任务标记为已完成。

---

强制执行顺序

硬性关卡——不得跳过。 如果你发现自己准备在完成步骤 0–2 之前运行 WebFetch 或 WebSearch，请停下——你跳过了关卡。

1. 步骤 0：创建工作流检查点任务——始终作为第一个操作。
2. 步骤 1：扫描现有内容并确定路径——扫描内容目录中的既有工作；分类评估覆盖情况；在开始新研究前提供选项。
3. 步骤 2：协作确定研究范围——提出研究标准。在监督模式下，停止并等待用户确认后，再进行任何外部获取。
4. 步骤 3：通过摄取流程保存原始来源——先保存，再分析。
5. 步骤 4：阅读并分析——默认使用第三方／外部来源；仅当用户明确要求时，才使用第一方代码库。
6. 步骤 5：撰写研究文章——仅适用于路径 A。
7. 步骤 6：积极添加链接，并将有价值的问答归档回内容库。
8. 步骤 7：验证——检查 frontmatter、失效链接和来源对应关系。
9. 步骤 8：总结并提出后续方向。

路径 B 快捷方式： 如果用户在步骤 2 明确要求直接回答，则跳过步骤 5 和 7。仍须执行步骤 0、1、3、4、6、8（即使输出形式是对话，也不得放松证据要求）。

---

报告默认框架：外部／第三方来源

研究文章默认采用外部框架——研究第三方主题、技术、概念、公开代码仓库、论文和官方文档。除非用户明确要求，否则不要将用户自己的代码库分析混入研究文章。 混入这类内容会使研究结果从事实综合偏向针对组织的观点形成，从而降低事实保真度。

• 默认： 外部来源（网络、开源代码仓库、论文、官方 API）。
• 例外： 如果用户要求“研究我们的 X 与 Y 相比如何”或“纳入我们的代码库”，则将其纳入——但要在文章中明确区分第一方观察与第三方研究结果，以便读者区分可从外部验证的事实和针对特定组织的观点。

---

边做边持久化——文章就是检查点

边做边持久化——防崩溃检查点规则。 此流程导致的代价最高的单一失败，是已完成的研究因会话中途触发速率限制或崩溃而丢失——分析内容留在上下文中，从未写入，随着会话结束而被丢弃。用户付出的代价白白浪费了。知识库就是检查点；两条规则可确保每一步都能抵御崩溃：

• 获取每个来源后立即摄取（步骤 3），一次一个——不要先获取所有来源，再集中批量摄取。已摄取的来源在崩溃后仍会保留；已获取但未写入的来源则不会。
• 尽早创建文章骨架，并在阅读时按章节逐步填充（步骤 4-5），不要等到最后一次性写完。 分析完每个来源后，在继续处理下一个来源之前，先用 edit 将研究结果写入文章。若在阅读八个来源中的五个后崩溃，知识库中仍会安全保留五个章节；恢复时只需读回未完成的文章，而不必重新执行整个检索流程。

只存在于上下文中的结构化笔记并未持久化。如果某项发现值得保留，就应将其写入已摄取的来源或文章中，而不是只留在上下文里。

---

步骤 0：创建工作流检查点任务

始终作为第一个操作。 在进行任何读取、扫描或获取之前，创建任务。这些任务会在上下文压缩后继续保留，让遗漏的步骤立即显现，并向用户展示进度。

通过宿主的任务系统创建这些任务（在 Claude 中使用 TaskCreate；其他环境使用等效工具）：

TaskCreate: "Research: Scan existing coverage + route"        → start as in_progress
TaskCreate: "Research: Collaborative scoping — rubric gate"   → pending, blocked by #1
TaskCreate: "Research: Capture sources via ingest"            → pending, blocked by #2
TaskCreate: "Research: Read + analyze"                        → pending, blocked by #3
TaskCreate: "Research: Write the research article"            → pending, blocked by #4
TaskCreate: "Research: Link aggressively + file Q&A back"     → pending, blocked by #5
TaskCreate: "Research: Validate (frontmatter + dead-links)"   → pending, blocked by #6
TaskCreate: "Research: Recap + follow-up directions"          → pending, blocked by #7

使用宿主的阻塞关系来强制执行顺序。完成每个步骤后，将对应任务标记为 completed，并将下一个任务标记为 in_progress。

路径 B 变体： 如果范围界定后确定走路径 B（直接回答），则移除任务 #5 和 #7——它们不适用。

路径 C 变体： 如果步骤 1 判定走路径 C（更新现有内容），则移除任务 #3 和 #5（通常无需摄取，也不会创建新文章），并将任务 #4 重命名为“研究：阅读现有文章并比对差异”。

设置任务的原因：观察到的失败模式是 Agent 跳过扫描和范围界定，直接调用 WebFetch。任务能让用户在会话进行时立即发现被跳过的关卡。

---

步骤 1：扫描现有内容并确定路径

必须执行的第一个研究步骤。 在获取任何外部内容之前，先扫描知识库中已有的内容。

阶段 1：检查现有知识

如果用户明确提及一篇现有研究文章（说出文章名称、提供链接，或说“更新／刷新／扩展”）： → 跳过扫描，直接进入 路径 C。

否则，始终先扫描：

1. exec("grep -rln <topic-keyword> <content-dir>") — 返回匹配文件，并附带 frontmatter 信息，让你无需逐一打开文件即可判断相关性。
2. exec("ls -A <content-dir>") — 展示文件夹布局，以及每个子目录中最近更新的文档。
3. 对 最有希望的 1-3 个候选文件，执行 exec("cat <path>") — 返回完整文档、frontmatter、反向链接，以及 shadow-repo 最近的活动。

分类：

覆盖情况	含义	转至
已完全覆盖	现有文章以证据直接回答了问题	呈现发现；提供详细说明、验证、扩展或明确撰写新报告的选项
部分覆盖	存在相关研究；具体问题是自然的延伸	提供选项：（1）通过路径 C 扩展现有内容，（2）通过路径 A 撰写新文章
未覆盖	没有实质性重叠	进入路径 A（默认）或路径 B

阶段 2：提供路径选项（监督模式）

已完全覆盖：

“我们已有关于此主题的研究，见 <path>。主要发现如下：[2-4 项关键发现]。选项：（1）直接使用，（2）验证／刷新（文章日期为 [date]），（3）围绕 [specific dimension] 扩展，（4）如果这是不同的切入角度，则另辟新角度。”

让用户选择。如果现有研究已经回答了问题，不要开始新的研究。

部分覆盖：

“我们在 <path> 中有相关研究，涵盖 [scope]。你关于 [topic] 的问题尚未得到直接回答，但这是自然的延伸。选项：（1）通过路径 C 扩展现有内容，（2）通过路径 A 开始撰写新文章。我建议选择 [1 or 2]，因为 [reason]。”

未覆盖：

进入步骤 2（界定范围）。如果用户要求快速回答，应指出路径 B 可能适用，并在步骤 2 的范围界定交流中予以确认。

**无头模式：**自动选择——已完全覆盖 → 针对调用方要求的具体角度撰写新文章；部分覆盖 → 开始撰写新文章；未覆盖 → 路径 A。

扫描原则

• 不要跳过扫描。 即使只花 30 秒执行 grep + cat，也能避免重复研究，并让用户了解已有信息。
• 当主题在语义上连贯时，优先扩展（路径 C）——一篇全面的文章胜过两篇内容重叠的文章。
• 当切入角度、受众或核心问题有实质性差异时，优先撰写新文章（路径 A）。

---

步骤 2：协作界定范围（监督模式硬性停止关卡）

硬性关卡（监督模式）。 在用户确认评估标准之前，不要开始外部研究。提出评估标准后，停止并等待用户回复。只有之后才能将范围界定任务标记为已完成。

**无头模式下：**提出评估标准并继续。提出后将任务标记为已完成。

提出评估标准

向用户返回以下结构：

## Proposed research rubric

**Question:** [narrowed from the original topic — concrete, answerable, bounded]

**Dimensions to investigate:** [3-7 facets]
1. [Dimension 1]
2. [Dimension 2]
...

**Candidate sources:** [3-8 initial guesses]
- [Source 1 — why it's relevant]
- [Source 2 — why it's relevant]
...

**Success criteria:** [2-3 concrete outcomes — "the article cites X authoritative sources", "open questions are marked explicitly", etc.]

**Output format:** Path A (article) | Path B (direct answer) | Path C (update `<existing-article>`)

范围界定原则

• 如果原始主题含糊不清（“研究 LLM Agent”），应在检索前缩小范围：“具体研究哪些 Agent？要辅助做出什么决策？时间跨度是多久？”
• 如果主题本身是一个 URL，则将该 URL 作为锚点，并扩展到 2-4 个相邻的权威来源。
• 明确这项研究要辅助做出的决策。缺少决策背景的研究容易漫无目的。
• 不要过度限定评估标准——用户可以调整。提出建议，而非强加要求。

---

第 3 步：通过 ingest 捕获原始来源

对于已确认的评分标准中每个相关 URL、论文或文档，请按照 ingest 流程操作——该流程位于平台的 /open-knowledge 技能中的 references/ingest-and-sources.md，而不是本资料包中。典型研究会提取 3-8 个来源。 太少 → 综合分析单薄。太多 → 你会在本次会话剩余时间里一直阅读。

• 不要跳过 ingest。 保留原始内容可以将采集与解读分开，并使研究可复现。没有保留来源的文章只是观点；保留了来源的文章则提供了一条他人可以追溯的路径。
• 如果你特别需要的来源获取失败，请停下来让用户粘贴内容——不要默默略过。写作时捏造缺失证据是最严重的失败模式。
• 如果获取结果明显是摘要而非原始字节（某些基于 LLM 的获取工具会这样），请注明这一点，并尝试使用原始内容替代方案（curl -sL <url>，或请用户粘贴）。

---

第 4 步：阅读 + 分析

仔细阅读每个已采集的来源。此外，还要加载：

• 该主题已有的权威文章——exec("cat <path>")（返回 frontmatter + 反向链接 + shadow-repo 活动）。
• 相邻主题的既有研究——同样使用 exec("cat <path>") 读取 OpenKnowledge markdown。
• 相关源代码——仅当用户要求进行一手分析时才读取。对 .ts / .js 等文件使用原生 Read；对范围内的 .md / .mdx 文件使用 exec。
• 项目背景——项目存放设计资料的位置。

记录结构化笔记：

• 关键论断及其证据——每项论断都需要有可指向的来源
• 不同选项之间的权衡
• 来源之间的矛盾——这些往往是文章中最有价值的部分
• 未知事项和待解决的问题——明确你所了解内容的边界
• 与当前具体决策的相关性

记笔记时就把内容写进文章，而不是之后再写（必须遵守——见上文的 边做边保存）。 开始阅读前，先创建文章骨架——frontmatter + 第 5 步的章节标题；然后每分析完一个来源，就立即用 edit 将其发现写入相关章节。“笔记”就是正在编写的文章的 Findings 章节；不要把笔记留在上下文中，等到第 5 步再一次性誊写。从这里到第 5 步之间的速率限制，不应导致你已经完成的分析丢失。到达第 5 步时，文章应已基本完成，第 5 步只需定稿和润色。

依据纪律

文章中的每项事实性论断都必须在文内注明来源。不要写没有来源支撑的推测。如果没有证据：(a) 再进行一次搜索并引用来源，(b) 在文内标注 (TODO: needs source)，或 (c) 不写这项论断。切勿捏造。

---

步骤 5：撰写研究文章（仅适用于路径 A）

如果你遵循了 边做边持久化，文章已经存在，并且已根据步骤 4 大体填写完成——此步骤是对其进行定稿（补全任何剩余部分、完善建议，并运行下方的结构和验证检查），而不是从空白文档开始撰写。如果文章不存在或内容很少，而你是在中断后恢复工作：先用 exec("cat <path>") 重新查看未完成的文章，再只补齐缺失部分——并注意，步骤 4 中尚未写入知识库的分析会在会话中断时丢失，因此只需重新推导实际缺失的内容。在此处从头创建文档，说明跳过了增量规则；这属于错误情况，而不是理想流程。

在内容目录中保存 Markdown 文档。路径约定：

• 如果项目采用了三层生命周期（external-sources/ → research/ → articles/），请保存到 research/<slug>.md。
• 如果项目已有 docs/reports/specs 布局，请沿用该布局。
• 对于大型主题，请使用子目录：research/<topic>/<subtopic>.md。

文件名：使用描述性强的 kebab-case（crdt-alternatives-for-editor.md、llm-wikis-and-knowledge-bases.md）。不要写日期——日期应放在 frontmatter 中。

Frontmatter

---
title: Descriptive title
description: One-line summary of the research question
type: research-note
status: draft
date: YYYY-MM-DD
tags:
  - research
  - provisional
  - <topic-tag>
sources:
  - resource: ../external-sources/<source-1>.md
  - resource: ../external-sources/<source-2>.md
---

结构

## Question

[What specific question does this research answer? Be precise.]

## Context

[Why does this matter? What decision does it inform? Who is the reader?]

## Findings

[Main findings organized by theme, option, or criterion. Every claim cites a source inline.]

### Theme / Option 1

- Pros — with evidence links
- Cons — with evidence links
- Evidence: [Source A](../external-sources/source-a.md), [Source B](../external-sources/source-b.md)

### Theme / Option 2

...

## Trade-offs

[What you gain vs. lose with each option. A comparison table often helps.]

## Open questions

[What you still don't know — candidates for further research, prototyping, or human-judgment decisions.]

## Tentative recommendation

[Your best guess, clearly marked as tentative. Explain the reasoning so a future reader can re-evaluate when new information arrives.]

## Further reading

[Links to the ingested sources + adjacent research + any canonical articles on the topic.]

语气

• 暂定，而非权威定论。 使用“暂定”“初步发现”“基于目前的理解”等表述。
• 不要写得像是权威定论——这会造成误导。确立权威结论是 /consolidate-notes 技能的职责，应在决策确定后进行。
• 明确说明不确定性。 研究是允许保留不确定性的层次。

---

步骤 6：积极添加链接 + 将有价值的问答归档

研究文章是探索入口。链接不足的研究会沦为无人发现的孤岛。

链接规范

• 每个指向其他文档的名词短语都应添加链接。使用标准 Markdown：[text](./relative/path.md)。
• 引用来源时，应在正文中直接添加链接，而不只是将其列入 frontmatter 的 sources: 列表：根据 [LLM Agents](../external-sources/llm-agents.md)... 比单独列出 sources: 更好。
• 交叉链接相关研究：如果相邻主题有自己的研究文档，请在“待解决问题”部分或正文中添加链接。读者沿着一条线索阅读时，也应能找到其他相关内容。
• 撰写完成后，更新 1-2 个密切相关的现有页面，添加指向本研究的链接（通常放在“延伸阅读”或“另请参阅”部分）。这样才能通过反向链接让更多人发现这项研究。
• 不要用反引号括住链接，也不要使用 HTML 锚点——这符合平台技能的链接规则。

将有价值的问答归档

如果用户在研究过程中提出了一个具体问题，并且得到了有来源支持、可引用的答案，请将其单独整理成一个简短页面，与研究文章放在一起，而不只是留在聊天记录中。带有来源依据答案的具体问题，是你能产出的知识中信号价值最高的内容。

• 简短文件名：what-does-X-mean.md、how-does-Y-work.md
• 使用相同的对象形状 sources: frontmatter
• 在本研究文档的“延伸阅读”部分链接该答案
• 如果答案过短，不值得单独建文件，就留在聊天记录中；不要拆分过度

---

步骤 7：验证

标记完成前，请运行以下检查清单：

• 文件已保存在内容目录下选定的路径中
• Frontmatter 包含 title、description、type: research-note、status: draft、date，以及对象形状的 sources: 列表
• exec("ls -A <dir>") 会列出带有 frontmatter 信息的新文件
• audit({ path: "<doc-path>.md" }) 检查通过（没有 lint 违规，也没有损坏的内部链接）——修复所有检查结果
• “发现”中的每项事实陈述都在正文中引用来源
• 步骤 3 中链接的源文件全部存在（源链接损坏意味着采集过程的某个环节出了问题）
• 至少有 1-2 个相邻文档现在链接到本研究（遵循步骤 6“撰写完成后，更新……”的规则）

步骤 8：回顾 + 后续方向

在对话中与用户完成闭环：

## Recap

- [Finding 1 — with source]
- [Finding 2 — with source]
- [Key trade-off / contradiction surfaced]
- [1-2 open questions that remain]

**Tentative recommendation:** [state it in one sentence]

**Follow-up research directions** (Path A candidates for later):
1. [Direction 1 — what would it investigate?]
2. [Direction 2 — what would it investigate?]
3. [Direction 3 — what would it investigate?]

后续方向应是外部来源调查，而不是对用户代码库采取行动（这些内容应写入规范，而非开展更多研究）。每个方向都应是一个独立主题，供日后进一步研究。

在无头模式下，将回顾内容写入研究文章的“延伸阅读”部分，而不是通过交互方式提问。

---

非目标

• 不要提升为规范文章。 这是 /consolidate-notes 技能的职责，应在决策真正确定后执行。过早将内容规范化会掩盖不确定性，误导未来的读者。
• 不要掩盖不确定性。 在研究阶段，“我们目前还不知道”是可以接受的表述。请明确说明。
• 不要跳过资料导入。 始终先收集原始来源，再进行分析。没有保留来源的文章只是观点。
• 不要跳过步骤 1 的扫描。 重复研究会浪费用户时间，也会错失拓展既有工作的机会。
• 在监督模式下，不要跳过范围界定关卡。 用户的评估标准会影响后续所有工作；如果文章范围有误，就无法轻易补救。
• 除非用户要求，否则不要将第一方代码库分析混入文章。 这样做会使结论从事实综合偏离为观点。
• 不要悄无声息地覆盖现有研究。 如果该主题之前研究过，请迭代（路径 C），或创建一个名称明确的后继文件（crdt-alternatives-2.md），并标记旧文件已被取代。