Document Indexers

A document Indexer helps the Agent interpret one family of captured documents — design reviews, runbooks, API specifications, product requirements — and turn them into articles organized around reader questions rather than around the source files. This page covers what to put in one, following the shipped context-markdown-indexer. Notes and session summaries have their own interpreters but can support the same reader topics.

flowchart LR
  outline["Titles, opening excerpts,<br/>H2/H3 outlines"] --> group["Group by reader task<br/>and existing topics"]
  group -->|"report confirmed"| read["Read the passages<br/>each article needs"]
  read --> art["Articles with<br/>regional references"]

Start from captured sources

The Indexer works on authorized captured Markdown and its source identity. Capture proves which bytes are available, not what they mean; titles, headings and file names are navigation aids, not proof that the body has been read.

It must not fetch new documents, follow external links or widen source authorization on its own. Missing material is requested through the current workflow, and an unavailable source is kept distinct from an irrelevant one.

Planning from outlines

For each document the CLI supplies its title, a bounded introduction and the complete H2/H3 outline, plus existing article titles, descriptions and references. The Agent reads more — a section or the whole document — only where the reader question, grouping or authority is unclear. Full reading of every document is not required before a plan can be submitted.

Guide the grouping:

• Reuse an existing article, including a topic first discovered from code, when it answers the same question for the same audience.
• Let business definitions in documents correct a mechanical code-topic name, rather than forcing a document under a code directory.
• Split distinct reader tasks or lifecycles; combine sources that answer the same task. A broad shared label such as "operations" does not make all its procedures one summary.
• Neither file count nor heading count decides article count. One document may support several articles, and several documents one article.

Age, archive location and polished language prove neither authority nor irrelevance; compare substance, audience and applicability. The first plan is shown in the work-start report and waits for your feedback before bulk writing, also in managed mode.

Writing and repairs

Before writing, the Agent reads the actual passages each article needs, and keeps authoritative rules, examples, decisions and proposals distinct — a suggestion in a meeting summary is not implemented behavior. Each section cites at most three real source regions; the CLI handles digests and safety, the Agent judges whether the evidence supports the explanation. A local failure is repaired at the reported section, and finished tasks can be submitted without waiting for the rest of a batch.

Revisions keep stable article and section identities and preserve useful steps, examples, images and limitations. Do not inflate page counts, write one page per heading or turn missing evidence into speculative prose.

Images, tables and diagrams

Authorized images in a document arrive as registered visual resources. The Agent reads only those, prefers structured whiteboard or table data when available, and converts a clear flow, sequence, state or relationship diagram to Mermaid, or a table to Markdown, only when every label, value and footnote survives. Screenshots, photos and designs where the appearance is the information are kept as originals, and so is anything it cannot read reliably. It never guesses relationships or numbers. A document Indexer can add guidance for diagrams typical of its family.

Example outline

A minimal Indexer for design-review documents:

design-review-indexer/
  SKILL.md
  references/
    writing.md     # decision record and architecture guide outlines
  tests/fixtures/
    reviews/       # three anonymous design reviews, one superseded

---
name: design-review-indexer
description: Interpret design-review documents and write decision records and architecture guides. Use when selected for a Context planning or writing task on such documents.
---

# Design Review Indexer

During planning, use the title, "Context", "Decision" and "Alternatives"
headings to group reviews by the system they change. A superseded review
still explains history; link it from the current decision instead of
dropping it.

During writing, read [writing guidance](references/writing.md). State the
decision, its rationale and limits; mark open questions as open. A proposal
without a recorded decision is not adopted behavior.

Testing

Cover the document forms the Skill claims to support: an ordinary one-to-one article, a synthesis from several documents, reuse of an existing topic, a section repair, source line changes, links and images, and missing material. Check both fidelity to the source and the final page, keep examples anonymous and verify packaged links. Drafts and scheduling details stay temporary; clearing .tmp simply starts fresh production from formal knowledge and available sources.

See Creating an Indexer for the creation flow, Code Indexers for the code counterpart and Providers and Customization for combining Skills.

文档类 Indexer

文档 Indexer 帮助 Agent 解读某一类已采集的文档——设计评审、运维手册、API 规范、产品需求——并把它们转化为围绕读者问题而非来源文件组织的文章。本页参照自带的 context-markdown-indexer，介绍其中应包含的内容。笔记和会话摘要有各自的解读器，但可以支撑相同的读者主题。

flowchart LR
  outline["标题、开头摘录、<br/>H2/H3 大纲"] --> group["按读者任务<br/>和已有主题分组"]
  group -->|"报告已确认"| read["阅读每篇文章<br/>所需的段落"]
  read --> art["带有区域<br/>引用的文章"]

从已采集的来源开始

Indexer 处理的是已授权、已采集的 Markdown 及其来源标识。采集证明的是哪些字节可用，而不是它们的含义；标题、小标题和文件名只是导航辅助，不能证明正文已被阅读。

它不得自行抓取新文档、跟随外部链接或扩大来源授权。缺失的材料通过当前工作流申请，不可用的来源与无关的来源要区分开。

依据大纲规划

对每份文档，CLI 会提供标题、有限的引言和完整的 H2/H3 大纲，以及已有文章的标题、描述和引用。只有在读者问题、分组或权威性不明确时，Agent 才会进一步阅读——某一节或整份文档。提交计划之前并不要求全文阅读每份文档。

引导分组：

• 当某篇已有文章（包括最初从代码中发现的主题）为同一受众回答同一问题时，复用它。
• 让文档中的业务定义修正机械生成的代码主题名称，而不是把文档硬塞到代码目录下。
• 拆分不同的读者任务或生命周期；合并回答同一任务的来源。像“运维”这样宽泛的共用标签，并不意味着其下所有流程都要合并成一篇摘要。
• 文件数和标题数都不决定文章数。一份文档可以支撑多篇文章，多份文档也可以支撑一篇文章。

年代、归档位置和文字是否精炼，既不能证明权威性，也不能证明无关；要比较实质内容、受众和适用范围。第一版计划会展示在开工报告中，并在批量撰写之前等待你的反馈，全托管模式下也是如此。

撰写与修复

撰写之前，Agent 会阅读每篇文章所需的实际段落，并把权威规则、示例、决定和提议区分开——会议纪要中的一条建议并不是已实现的行为。每个小节最多引用三个真实的来源区域；CLI 负责摘要值和安全性，Agent 判断证据是否支撑讲解。局部失败在报告的小节处修复，已完成的任务可以直接提交，无需等待同一批次的其余任务。

修订会保持文章和小节的标识稳定，并保留有用的步骤、示例、图片和限制。不要虚增页数，不要每个标题写一页，也不要把缺失的证据变成推测性的文字。

图片、表格和图表

文档中已授权的图片会作为已登记的视觉资源提供。Agent 只读取这些资源，在可用时优先使用结构化的白板或表格数据；只有当每个标签、数值和脚注都能完整保留时，才会把清晰的流程图、时序图、状态图或关系图转换为 Mermaid，或把表格转换为 Markdown。截图、照片以及以外观本身为信息的设计稿会保留原件，无法可靠读取的内容也是如此。它绝不猜测关系或数字。文档 Indexer 可以针对其文档类别中常见的图表补充指引。

示例结构

一个针对设计评审文档的最小 Indexer：

design-review-indexer/
  SKILL.md
  references/
    writing.md     # decision record and architecture guide outlines
  tests/fixtures/
    reviews/       # three anonymous design reviews, one superseded

---
name: design-review-indexer
description: Interpret design-review documents and write decision records and architecture guides. Use when selected for a Context planning or writing task on such documents.
---

# Design Review Indexer

During planning, use the title, "Context", "Decision" and "Alternatives"
headings to group reviews by the system they change. A superseded review
still explains history; link it from the current decision instead of
dropping it.

During writing, read [writing guidance](references/writing.md). State the
decision, its rationale and limits; mark open questions as open. A proposal
without a recorded decision is not adopted behavior.

测试

覆盖该 Skill 声称支持的文档形式：普通的一对一文章、综合多份文档的文章、复用已有主题、小节修复、来源行变化、链接和图片，以及材料缺失。既要检查对来源的忠实度，也要检查最终页面；保持示例匿名，并验证打包后的链接。草稿和调度细节都是临时的；清空 .tmp 只会让新的生产从正式知识和可用来源重新开始。

创建流程参见创建 Indexer，代码方面的对应内容参见代码类 Indexer，组合 Skill 参见 Provider 与定制。