aif-docs

文档 — 项目文档生成器

按照“README 作为首页 + 详细文档目录”的结构生成、维护并改进项目文档。

核心原则

1. README 是首页，不是手册。 约 80–120 行。用于留下第一印象、介绍安装方式和快速示例，并提供详细信息的链接。
2. 详细内容放在解析后的文档目录中（paths.docs，默认值：docs/）。每个文件都应自成一体——一篇文档只讲一个主题。用户只需阅读单个文档文件，就能全面了解该主题。
3. 避免重复。 如果信息已放在解析后的文档目录中，README 应链接到该信息，而不是重复内容。例外：安装命令可以同时出现在两处（用户希望在 README 中找到它）。
4. 导航。 解析后的文档目录中的每个文档文件都应在首行添加导航链接，并按照文档目录表中的顺序排列：[← Previous Page](prev.md) · [Back to README](<docs-to-readme-link>) · [Next Page →](next.md)。第一页不包含上一页链接；最后一页不包含下一页链接。每页末尾都应添加“另请参阅”部分，链接到 2–3 篇相关文档。
5. 交叉链接使用相对路径。 从 README 链接时，使用解析后的文档目录路径（例如，默认情况下为 docs/workflow.md）。在同一目录中的文档页面之间链接时，使用 workflow.md。
6. 便于浏览。 使用表格、项目符号列表和代码块。避免长段落。用户通常会浏览，而不是逐字阅读。

工作流

步骤 0：加载配置和项目上下文

首先： 如果 .ai-factory/config.yaml 存在，请读取它以确定：

• 路径： paths.description、paths.architecture 和 paths.docs
• 语言： 用于提示词的 language.ui，以及用于生成文档的 language.artifacts

如果 config.yaml 不存在，请使用默认值：

• DESCRIPTION.md：.ai-factory/DESCRIPTION.md
• ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
• 文档目录：docs/
• 语言：en（英语）

注意： README.md 仍是项目根目录中的落地页。详细文档写入解析出的 paths.docs 目录（默认为 docs/）。

然后： 如果 .ai-factory/DESCRIPTION.md 存在，请读取它（使用配置中的路径）以了解：

• 技术栈（语言、框架、数据库）
• 项目用途和架构
• 主要功能和约定

同时，如果 .ai-factory/ARCHITECTURE.md 存在，也请读取它（使用配置中的路径），以便让文档符合项目的结构和边界。

探索代码库：

• 阅读 package.json、composer.json、requirements.txt、go.mod、Cargo.toml 等文件
• 扫描 src/ 结构以了解架构
• 查找现有文档、注释、API 端点、命令行命令
• 检查现有的 README.md 和解析出的文档目录

读取 .ai-factory/skill-context/aif-docs/SKILL.md——如果该文件存在，则必须读取。

此文件包含 /aif-evolve 根据补丁、代码库约定和技术栈分析积累的项目专属规则。这些规则专为当前项目定制。

如何应用 skill-context 规则：

• 将其视为对本技能通用指令的项目级覆盖规则
• 当 skill-context 规则与此 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准（更具体的上下文优先——遵循与嵌套 CLAUDE.md 文件相同的原则）
• 如果没有冲突，则同时应用两者：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则似乎与本技能的默认规则相矛盾，也不要忽略它们——这些规则的存在是因为项目经验表明默认规则不够完善
• 重要： skill-context 规则适用于本技能的所有输出，包括 README.md、文档页面及其模板。此 SKILL.md 中的模板只是基础结构。如果 skill-context 规则要求“文档必须包含 X”或“README 必须包含 Y 章节”，则必须相应扩展模板。生成的文档若违反 skill-context 规则，即属于错误。

**强制要求：**生成任何输出产物后，都要依据所有 skill-context 规则进行检查。如有违反，必须先修正，再呈现给用户。

扫描项目根目录中零散的 Markdown 文件：

使用 Glob 查找项目根目录中的所有 *.md 文件（排除 node_modules/、.ai-factory/ 和 Agent 目录）：

CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, etc.

记录每个文件、其大小及内容简述。此列表将在步骤 1.1 中使用。

步骤 0.1：解析标志

--web  → Generate HTML version of documentation

步骤 1：确定当前状态

检查现有文档：

State A: No README.md                        → Full generation (README + docs dir)
State B: README.md exists, no docs dir      → Analyze README, propose split into docs dir
State C: README.md + docs dir exist         → Depends on flags (see below)

带有 --web 标志的状态 C——询问用户：

Documentation already exists (README.md + resolved docs directory).

AskUserQuestion: What would you like to do?

Options:
1. Generate HTML only — build site from current docs as-is
2. Audit & improve first — check for issues, then generate HTML
3. Audit only — check for issues without generating HTML

根据选择：

• 仅生成 HTML → 跳过步骤 1.1、步骤 2 和步骤 4——直接进入步骤 3（生成 HTML），然后结束
• 先审查并改进 → 执行步骤 1.1 → 步骤 2（状态 C）→ 步骤 3 → 步骤 4 → 步骤 4.1
• 仅审查 → 执行步骤 1.1 → 步骤 2（状态 C）→ 步骤 4 → 步骤 4.1（跳过步骤 3）

不带 --web 标志的状态 C → 按常规执行步骤 2（状态 C）。

步骤 1.1：检查零散的 Markdown 文件

如果在项目根目录中发现了零散的 .md 文件（见步骤 0），建议将它们整合到已确定的文档目录中。

应移至已确定的文档目录的常见文件：

根目录文件	文档目录中的目标位置	合并还是移动？
CONTRIBUTING.md	<resolved docs dir>/contributing.md	移动
ARCHITECTURE.md	<resolved docs dir>/architecture.md	移动
DEPLOYMENT.md	<resolved docs dir>/deployment.md	移动
SETUP.md	<resolved docs dir>/getting-started.md	合并（追加到现有内容）
DEVELOPMENT.md	<resolved docs dir>/getting-started.md 或 <resolved docs dir>/contributing.md	合并
API.md	<resolved docs dir>/api.md	移动
TESTING.md	<resolved docs dir>/testing.md	移动
SECURITY.md	<resolved docs dir>/security.md	移动

保留在根目录中的文件（标准惯例）：

• README.md — 始终保留
• CHANGELOG.md — 标准的根目录文件，保持原样
• LICENSE / LICENSE.md — 标准的根目录文件，保持原样
• CODE_OF_CONDUCT.md — 标准的根目录文件，保持原样

如果发现了零散文件，请询问用户：

Found [N] markdown files in the project root:

  CONTRIBUTING.md (45 lines) — contribution guidelines
  ARCHITECTURE.md (120 lines) — system architecture overview
  DEPLOYMENT.md (80 lines) — deployment instructions
  SETUP.md (30 lines) — setup guide (overlaps with getting-started)

Suggested actions:
  → Move CONTRIBUTING.md → <resolved docs dir>/contributing.md
  → Move ARCHITECTURE.md → <resolved docs dir>/architecture.md
  → Move DEPLOYMENT.md → <resolved docs dir>/deployment.md
  → Merge SETUP.md into <resolved docs dir>/getting-started.md

AskUserQuestion: Would you like to apply the consolidation?

Options:
1. Apply all suggestions
2. Let me pick which ones
3. Skip — keep files where they are

根据用户的选择：

• 全部应用建议 → 移动/合并所有列出的文件，然后继续步骤 2
• 让我选择具体文件 → 逐个列出文件并征求批准，应用用户选择的文件
• 跳过 → 保留文件原位，然后继续步骤 2

移动/合并时：

1. 在已确定的文档目录中创建目标文件，添加上一页/下一页导航标题（遵循文档表格中的顺序）和“另请参阅”页脚
2. 如果合并到现有文档中，则在新的章节标题下追加内容，避免重复已有信息
3. 暂时不要删除原文件 — 保留这些文件，直到审核步骤确认所有内容均已就位
4. 使用相对于 README 的正确路径，将新文档页面添加到 README 的文档表格中
5. 更新其他文件中指向旧根目录文件的链接
6. 记录已移动/合并的文件，以便在步骤 4.1 中使用此列表

**重要：**切勿强行移动文件。务必先展示计划并征得用户批准。

步骤 2（状态 A）：从头生成

如果不存在 README.md，则生成完整的文档集。

2.1：分析项目并确定文档主题

探索代码库并确定文档主题：

Always include:
- getting-started.md    (installation, setup, quick start)

Include if relevant:
- architecture.md       (if project has clear architecture: services, modules, layers)
- api.md                (if project exposes API endpoints)
- configuration.md      (if project has config files, env vars, feature flags)
- deployment.md         (if Dockerfile, CI/CD, deploy scripts exist)
- contributing.md       (if open-source or team project)
- security.md           (if auth, permissions, or security patterns exist)
- testing.md            (if test suite exists)
- cli.md                (if project has CLI commands)

询问用户：

I've analyzed your project and suggest these documentation pages:

1. getting-started.md — Installation, setup, quick start
2. architecture.md — Project structure and patterns
3. api.md — API endpoints reference
4. configuration.md — Environment variables and config

AskUserQuestion: Would you like to generate these documentation pages?

Options:
1. Generate all of these
2. Let me pick which ones
3. Add more topics

根据用户的选择：

• 全部生成 → 在已确定的文档目录中生成 README.md 和所有列出的文档文件
• 让我选择 → 逐个列出主题供用户批准，仅生成获批的主题
• 添加更多主题 → 询问还需包含哪些主题，确认最终列表，然后生成

2.2：生成 README.md

结构（目标约 80–120 行）：

# Project Name

> One-line tagline describing the project.

Brief 2-3 sentence description of what this project does and why it exists.

## Quick Start

\`\`\`bash
# Installation steps (1-3 commands)
\`\`\`

## Key Features

- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description

## Example

\`\`\`
# Show a real usage example — this is where users decide "I want this"
\`\`\`

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](<readme-to-docs-dir>/getting-started.md) | Installation, setup, first steps |
| [Architecture](<readme-to-docs-dir>/architecture.md) | Project structure and patterns |
| [API Reference](<readme-to-docs-dir>/api.md) | Endpoints, request/response formats |
| [Configuration](<readme-to-docs-dir>/configuration.md) | Environment variables, config files |

## License

MIT (or whatever is in the project)

README 的关键规则：

• 如果项目有 Logo/徽章行，则将其放在顶部
• 将标语写成引用块
• 快速入门部分使用真实的安装命令（根据包管理器判断）
• 关键功能使用项目符号列表（3–6 项，便于快速浏览）
• 提供展示“惊艳效果”的真实用法示例
• 添加包含指向已确定文档目录的链接的文档表格
• 在底部注明许可证
• 不要写冗长描述、完整 API 参考或配置详情

2.3：在解析后的 docs 目录中生成文档文件

为每个已批准的主题创建一个文档文件：

[← Previous Topic](previous-topic.md) · [Back to README](<docs-to-readme-link>) · [Next Topic →](next-topic.md)

# Topic Title

Content organized by subtopic with headers, code examples, and tables.
Keep each section self-contained.

## See Also

- [Related Topic 1](related-topic.md) — brief description
- [Related Topic 2](other-topic.md) — brief description

导航链接顺序遵循 README.md 中的 Documentation 表（从上到下）。第一个文档页面省略“← Previous”链接；最后一个页面省略“Next →”链接。使用从解析后的 docs 目录返回 README.md 的正确相对链接。默认 docs/ 布局示例：

getting-started.md:  [Back to README](../README.md) · [Architecture →](architecture.md)
architecture.md:     [← Getting Started](getting-started.md) · [Back to README](../README.md) · [API Reference →](api.md)
api.md:              [← Architecture](architecture.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
configuration.md:    [← API Reference](api.md) · [Back to README](../README.md)

各主题的内容指南：

getting-started.md：

• 前置条件（运行时版本、所需工具）
• 分步安装说明
• 首次运行／快速入门
• 验证是否正常工作（预期输出）
• 后续步骤链接

architecture.md：

• 高层概述（如有帮助，可添加图表）
• 目录结构及说明
• 关键模式（命名、导入、错误处理）
• 数据流

api.md：

• 基础 URL／配置
• 身份验证
• 按资源分组的端点
• 请求／响应示例
• 错误代码

configuration.md：

• 所有环境变量及其说明和默认值
• 配置文件及其用途
• 功能标志

deployment.md：

• 构建步骤
• 环境设置
• CI/CD 流水线说明
• 监控／运行状况检查

步骤 2（状态 B）：将现有 README 拆分到解析后的 docs 目录中

当 README.md 存在但篇幅较长（150 行以上），且尚未有解析后的 docs 目录时。

2.1：分析 README 结构

阅读 README.md 并确定：

• 哪些部分应保留（着陆页内容）
• 哪些部分应移至解析后的 docs 目录（详细内容）

保留在 README 中：

• 标题、标语、徽章
• “为什么？”／主要功能项目列表
• 快速安装（1-3 条命令）
• 简短示例
• 文档链接表
• 外部链接、许可证

移至解析后的 docs 目录：

• 详细设置说明 → getting-started.md
• 架构／项目结构 → architecture.md
• 完整 API 参考 → api.md
• 配置详情 → configuration.md
• 贡献指南 → contributing.md
• 任何篇幅超过约 30 行且涉及单个主题的部分

2.2：向用户提出变更方案

Your README.md is [N] lines. I suggest splitting it:

README.md (~100 lines) — keep as landing page:
  ✓ Title + tagline
  ✓ Key features
  ✓ Quick install
  ✓ Example
  ✓ Documentation links table

Move to docs dir:
  → "Installation" section → <resolved docs dir>/getting-started.md
  → "Configuration" section → <resolved docs dir>/configuration.md
  → "API Reference" section → <resolved docs dir>/api.md
  → "Architecture" section → <resolved docs dir>/architecture.md

Proceed?

2.3：执行拆分

1. 创建解析后的 docs 目录
2. 使用 README 中的内容为每个主题创建文档文件，并添加上一页／下一页导航标题（遵循 Documentation 表顺序）和“另请参阅”页脚
3. 将 README 重写为包含 Documentation 链接表的着陆页
4. 确认没有内容丢失——旧 README 中的每个部分都必须保留在某处

步骤 2（状态 C）：改进现有文档

当 README.md 和解析后的 docs 目录都存在时。

2.1：审核当前文档

检查以下内容：

• README 篇幅——它是否仍是着陆页（少于 150 行）？
• 缺失主题——项目是否有未记录的方面？
• 过时内容——文档是否引用了已不存在的文件／API？
• 导航——所有文档是否都包含上一页／下一页标题链接和“另请参阅”？
• 失效链接——确认所有内部链接均指向现有文件／锚点
• 一致性——所有文档的格式风格是否相同
• 标准合规性——现有文档是否符合当前技能标准？（参见 2.1.1）

2.1.1：标准合规性检查

根据当前核心原则检查现有文档是否存在缺漏（缺少导航、缺少“另请参阅”、格式过时）。如需查看完整合规性表和自动修复规则 → 阅读 references/REVIEW-CHECKLISTS.md（标准合规性部分）。

发现缺漏时，在审核报告中与内容问题一并列出（步骤 2.2）。将其视为常规改进——展示计划并在应用前征得用户批准。

2.2：提出改进建议

Documentation audit results:

✅ README is lean (105 lines)
⚠️  Docs pages in the resolved docs directory are missing prev/next navigation — will add
⚠️  <resolved docs dir>/api.md is missing — project has 12 API endpoints
⚠️  <resolved docs dir>/configuration.md references old env var DB_HOST (now DATABASE_URL)
❌ <resolved docs dir>/getting-started.md links to setup.md which doesn't exist

Proposed fixes:
1. Add prev/next navigation to all doc pages in the resolved docs directory
2. Create <resolved docs dir>/api.md with endpoint reference
3. Update DATABASE_URL in <resolved docs dir>/configuration.md
4. Fix broken link in <resolved docs dir>/getting-started.md

Apply fixes?

步骤 3：生成 HTML 版本（--web 标志）

传入 --web 标志时，根据 Markdown 文档生成静态 HTML 网站。

3.1：创建 docs-html/ 目录

mkdir -p docs-html

3.2：生成 HTML 文件

为每个 Markdown 文件（README.md + <resolved docs dir>/*.md）生成 HTML 版本：

读取 HTML 模板 templates/html-template.html，并将其用于每个页面。 自定义：{page_title}、{project_name}、{nav_links}、{content}。

3.3：将 Markdown 转换为 HTML

对于每个文档文件：解析 Markdown → 转换为 HTML 元素 → 将 .md 链接修正为 .html → 生成导航栏 → 写入 docs-html/。

文件映射：README.md → index.html，<resolved docs dir>/*.md → *.html。

3.4：输出结果

显示生成文件的目录树，并提示运行 open docs-html/index.html。

步骤 4：文档审查

任何内容变更后都必须执行此步骤（生成、拆分、改进、文件合并）。请勿跳过此步骤。

仅当选择了“仅生成 HTML”时，跳过此步骤——未修改任何内容，无需审查。

阅读每个生成或修改的文件，并根据 references/REVIEW-CHECKLISTS.md 中的两份检查清单进行评估。两份检查清单：技术准确性和可读性与完整性。

在向用户呈现结果前修复发现的所有问题。以简洁表格显示每项的 ✅/❌/⚠️ 状态。

步骤 4.1：清理已移动的文件

仅当步骤 1.1 中有文件从根目录移入 docs/ 时才执行。

审查确认所有内容都已正确放置在 docs/ 中后，询问是否删除原始根目录文件：

The following root files have been incorporated into docs/:

  CONTRIBUTING.md → now in docs/contributing.md
  ARCHITECTURE.md → now in docs/architecture.md
  DEPLOYMENT.md → now in docs/deployment.md
  SETUP.md → merged into docs/getting-started.md

AskUserQuestion: These originals are no longer needed. Delete them?

Options:
1. Yes, delete all originals
2. Let me pick which ones to delete
3. No, keep them (I'll clean up later)

根据用户选择：

• 是，全部删除 → 删除所有列出的原文件（见下文“删除时”）
• 让我选择 → 逐个列出文件，仅删除获准删除的文件
• 否，保留 → 原样保留文件，继续执行步骤 5

删除时：

1. 再次确认目标 docs/ 文件包含原文件的所有内容
2. 删除根目录文件
3. 运行 git status 显示已删除的文件——用户可根据需要运行 git checkout 恢复

请勿自动删除。 始终先征求用户同意。用户可能想暂时保留原文件以供参考或比较差异。

步骤 5：更新 AGENTS.md

任何文档变更后，更新 AGENTS.md 中的 Documentation 部分（如果该文件存在）。

读取 AGENTS.md 并找到 ## Documentation 部分。更新该部分，以反映所有文档文件的当前状态：

## Documentation
| Document | Path | Description |
|----------|------|-------------|
| README | README.md | Project landing page |
| Getting Started | `<resolved docs dir>/getting-started.md` | Installation, setup, first steps |
| Architecture | `<resolved docs dir>/architecture.md` | Project structure and patterns |
| API Reference | `<resolved docs dir>/api.md` | Endpoints, request/response formats |
| Configuration | `<resolved docs dir>/configuration.md` | Environment variables, config files |

规则：

• 首先列出 README.md，然后按照 README Documentation 表中的相同顺序列出已解析文档目录中的所有文档文件
• 如果步骤 1.1 中有文件从根目录移入或合并，应反映其新位置
• 如果创建了新的文档页面，应将其添加进来
• 如果移除了文档页面，应将其删除
• 描述应简洁（少于 10 个单词）
• 如果 AGENTS.md 不存在，则静默跳过此步骤

上下文清理

如有需要，建议用户释放上下文空间：/clear（完全重置）或 /compact（压缩历史记录）。

产物归属

• 主要归属：README.md、<resolved docs dir>/* 和 AGENTS.md 中的 Documentation 部分。
• 配置用途：config.yaml 用于解析 paths.description、paths.architecture、paths.docs、language.ui 和 language.artifacts。
• 只读上下文：.ai-factory/DESCRIPTION.md、.ai-factory/ARCHITECTURE.md、路线图/规则/研究产物，除非用户明确要求进行更广泛的编辑。

重要规则

1. 修改现有文档前务必先征求同意——先展示计划
2. 绝不删除内容，除非将其移至其他位置
3. 识别项目的真实信息——不要臆造功能，应读取 package.json/配置文件
4. 使用项目所用语言——如果项目 README 使用俄语，就用俄语编写文档
5. 保留现有徽章/标志——重组时不要移除
6. 如果生成 HTML，则添加到 .gitignore：将 docs-html/ 添加到 .gitignore
7. 归属边界——此命令负责文档产物（README.md、<resolved docs dir>/* 和 AGENTS.md 中的 Documentation 部分），不负责根据配置解析出的路线图、RULES.md 或研究产物