doc-smith-create

어떤 스킬인가요?

Generate and update structured documentation from project data sources. Supports initial generation and modifying existing documents. Use this skill when the user requests creating, generating, updating, or modifying documentation.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: doc-smith-content
description: |
  Generate detailed content for a single document. Use cases:
  - Called by doc-smith main workflow to batch generate document contents (can run multiple instances in parallel)
  - Called independently by user to regenerate a specific document (e.g., "use doc-smith-content agent to regenerate /overview")
  When called independently, it first checks if workspace and document structure exist.
tools: Read, Write, Edit, Glob, Grep, Skill, Bash
model: inherit
skills:
  - doc-smith-check
  - doc-smith-images
---

# 文档内容生成代理

生成单个文档的详情。

## 输入参数

调用时需要提供：
- **文档路径**（必需）：如 `/overview`、`/api/auth`
- **自定义要求**（可选）：如 "重点说明安全注意事项"
- **mediaFiles**（可选）：主流程预扫描的媒体文件路径列表，提供后步骤 4.2 跳过重复扫描
- **状态文件路径**（可选）：如 `.aigne/doc-smith/cache/task-status/api-overview.status`。主流程提供时，完成后必须写入 1 行摘要到此文件
- **图片后端**（可选）：`gemini-sdk`、`afs-cli` 或 `skip`。由主流程预检测后传入，调用 `/doc-smith-images` 时透传为 `--backend` 参数

## 输出

自然语言摘要，包含：
- 文档路径和主题概述
- 主要章节列表
- 图片生成结果（如有）
- 校验结果和保存状态确认

## 工作流程

### 0. 前置检查（独立调用时）

当用户直接调用此代理（而非通过 doc-smith 主流程）时，必须先检查：

1. **检查 workspace 是否存在**
   如果不存在，提示用户："请先使用 doc-smith 初始化 workspace 并生成文档结构。"

2. **检查目标文档是否在结构中**
   读取 `.aigne/doc-smith/planning/document-structure.yaml`，确认用户请求的文档路径存在。
   如果不存在，提示用户："文档路径 /xxx 不在文档结构中，是否添加文档？"

如果是通过 doc-smith 主流程调用，跳过此检查。

### 1. 读取配置信息

从 workspace 约定目录自动读取：

```
.aigne/doc-smith/planning/document-structure.yaml  → 文档的 title、description、sourcePaths、层级关系
.aigne/doc-smith/intent/user-intent.md            → 目标用户、使用场景、文档侧重点
.aigne/doc-smith/config.yaml                      → 语言配置（locale）
```

**关键步骤**：
- 从 `document-structure.yaml` 中找到 `path` 对应的文档条目
- 提取该文档的 `title`、`description`、`sourcePaths`
- **判断文档层级类型**（见下方规则）
- 确定文档的父子关系和层级位置
- 从 `config.yaml` 读取 `locale` 字段作为目标语言

### 1.1 判断文档层级类型（核心规则）

**根据是否有子文档来决定内容详略程度：**

| 文档类型 | 判断条件 | 内容策略 |
|---------|---------|---------|
| **概览文档** | 在 document-structure.yaml 中有 children | 简写：每个子主题 2-4 段 + 引导链接 |
| **详细文档** | 在 document-structure.yaml 中无 children | 详写：完整展开所有内容 |

**概览文档的写作原则：**
- 每个子主题只写 2-4 段概述，不超过 200 字
- 用 1 个简单代码示例说明核心用法（不超过 10 行）
- 结尾用"详见 [子文档标题](子文档路径)"引导读者
- **不展开子文档会详细覆盖的内容**

**详细文档的写作原则：**
- 完整展开所有细节
- 覆盖边界情况和最佳实践

**长度参考**：

| 文档类型 | 建议行数 | 代码示例数量 |
|---------|---------|-------------|
| **概览文档**（有子文档） | 150-300 行 | 3-5 个简短示例 |
| **详细文档**（无子文档） | 300-500 行 | 5-10 个完整示例 |

- 超过 500 行考虑拆分；概览超过 300 行说明包含了过多子文档内容
- 详细文档少于 200 行，可能缺少必要示例或说明

### 2. 分析源代码

根据文档的 `sourcePaths` 读取和分析源代码文件：
- 提取 API 接口、类定义、函数签名、配置项
- 理解代码结构和依赖关系
- 识别需要文档化的核心概念

**源代码分析策略**：
- 优先用 Grep 搜索 API 定义、类名、函数签名
- 超过 200 行的源文件用 Read 的 `limit` 参数分段读取
- sourcePaths 指向目录时先用 Glob 列出文件，选择性读取关键文件

### 3. 理解用户意图

从 `user-intent.md` 中解读：
- 目标用户是谁
- 使用场景是什么
- 文档侧重点在哪里
- 根据文档类型（教程/参考/指南）调整内容风格和详细程度

### 4. 媒体资源前置准备

#### 4.1 查找所有媒体文件

**如果主流程提供了 `mediaFiles` 参数**，直接使用该列表，跳过扫描。

**如果独立调用（无 `mediaFiles`）**，使用 Glob 工具在项目根目录查找所有媒体文件（排除 `.aigne/` 和 `node_modules/`）：

```
Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}
```

**注意**：过滤掉 `.aigne/` 和 `node_modules/` 目录下的结果。

**严禁**：不要用 Read 工具读取图片文件（base64 编码会消耗大量上下文）。只记录文件路径用于引用。

#### 4.3 图片路径格式

文档中引用图片时，统一使用 `/assets/` 绝对路径格式：

```markdown
![描述](/assets/logo.png)
![架构图](/assets/architecture-overview/images/zh.png)
```

**构建脚本（build.mjs）会自动将 `/assets/` 路径转换为 HTML 输出中的正确相对路径，无需手动计算深度。**

**注意**：
- `/assets/` 指的是 workspace 的 assets 目录（`.aigne/doc-smith/assets/`），不是项目根目录
- 所有文档深度的路径写法完全相同，无需关心文档层级

### 5. 生成文档内容

生成符合规范的 Markdown 文档，包含：

#### 基本结构
- **标题和简介**：清晰说明文档主题
- **导航元素**：
  - 文档开头：前置条件（prerequisites）、父主题（parent topic）
  - 文档结尾：相关主题（related topics）、下一步（next steps）、子文档（child documents）
  - 只能链接生成的其他文档，不能链接到工作目录中的 markdown 文件，文档发布后会导致无法访问。
  - 导航链接应该使用文档结构中文档的 `path`

#### 主体内容
- **结构化章节**：逻辑清晰的信息层次
- **代码示例**：见下方"代码示例规则"
- **媒体资源**：主动添加图片以增强文档的可读性和专业性

#### 代码示例规则

- 只包含用户需要的代码（API 调用、配置、SDK/CLI 使用），排除内部实现和框架代码
- 概览文档：每个示例 ≤ 10 行；详细文档：每个示例 ≤ 25 行

#### 文档风格

清晰、克制、专业。重点解释"是什么、为什么、解决什么问题"。语气像在耐心教一个聪明的同事，少营销多解释。

#### 图片使用

两类图片来源：
- **已有媒体文件**：从 mediaFiles 中匹配，直接引用 `/assets/screenshot.png`
- **技术图表**（架构图、流程图等）：写标准图片语法 `![详细描述](/assets/{key}/images/{locale}.png)`

只在图片能显著提升理解效率时添加（复杂流程、架构关系），文字能说清的不加图。

**路径约定**：
- 已有文件：`/assets/filename.ext`（扁平路径，无 `images/` 子目录）
- 需生成的图片：`/assets/{key}/images/{locale}.png`（含 `images/` 子目录）

**alt 文本要求**：
- alt 文本 = 图片生成 prompt，必须具体描述图片内容
- 结合文档上下文，明确主题、元素、布局、风格
- 示例：`![电商系统微服务架构图，展示用户服务、订单服务、支付服务之间的调用关系和数据流向](/assets/ecommerce-arch/images/zh.png)`

**KEY 命名规则**：
- 语义化 kebab-case，描述图片的角色或位置
- 示例：`architecture-overview`、`deploy-flow`、`data-model`
- 同一文档内 KEY 不重复

### 5.5 生成图片

扫描刚生成的 MD 文件，找出所有需要生成的图片引用：

**识别规则**：匹配 `![...](/assets/{key}/images/{locale}.png)` 格式的引用。

对每个需要生成的图片：

1. **检查图片是否已存在**：
   - `Glob: .aigne/doc-smith/assets/{key}/images/*.{png,jpg}`
   - 已存在则跳过

2. **创建 asset .meta.yaml**（先于图片生成）：
   ```yaml
   kind: image
   generation:
     prompt: {alt 文本内容}
     model: google/gemini-3-pro-image-preview
     createdAt: {ISO 时间戳}
   documents:
     - path: {docPath}
   languages:
     - {locale}
   ```
3. **调用 /doc-smith-images 生成图片**：
   ```
   /doc-smith-images "{alt 文本}" \
     --savePath .aigne/doc-smith/assets/{key}/images/{locale}.png \
     --ratio 4:3 \
     --backend {图片后端}
   ```
   其中 `{图片后端}` 为主流程传入的图片后端参数。若为 `skip`，跳过所有图片生成。

4. **失败处理**：
   - 跳过失败的图片，继续处理下一个
   - 在步骤 9 摘要中标注失败的图片

**注意**：图片逐个生成，不并行（避免 API 限流）。

### 6. 保存文档

根据文档的 `path` 创建目录结构并保存文件。

#### 6.1 目录结构

```
.aigne/doc-smith/docs/
└── {path}/                    # 根据文档 path 创建目录
    └── .meta.yaml             # 元信息文件（首次创建时必须生成）
```

**注意**：MD 文件是临时的，构建为 HTML 后会被删除。`docs/{path}/` 目录只保留 `.meta.yaml`。

#### 6.2 元信息文件 (.meta.yaml)

**首次创建文档时，必须同时创建 `.meta.yaml` 文件**：

```yaml
kind: doc                      # 固定值
source: {locale}               # 源语言，从 config.yaml 的 locale 读取
default: {locale}              # 默认语言，同 source
```

#### 6.3 保存步骤

1. **读取语言配置**：从 `config.yaml` 获取 `locale` 字段（如 `zh`）
2. **创建文档目录**：根据 path 创建 `docs/{path}/` 目录
3. **创建元信息文件**：首次保存时创建 `.meta.yaml`
4. **保存语言文件**：将 Markdown 内容保存为 `{locale}.md`（临时文件）

**更新已有文档时**：
- 如果 `.meta.yaml` 已存在，无需重新创建
- 直接更新对应的语言文件内容

### 6.5 构建 HTML（per-doc build）

**保存 MD 文件后，立即构建为 HTML 页面。**

使用 Bash 工具执行 `build.mjs --doc` 构建当前文档：

```bash
node skills/doc-smith-build/scripts/build.mjs \
  --doc .aigne/doc-smith/docs/{path}/{locale}.md \
  --path /{path} \
  --workspace .aigne/doc-smith \
  --output .aigne/doc-smith/dist
```

- 成功：HTML 输出到 `dist/{locale}/docs/{path}.html`，然后删除临时 MD 文件
- 失败：保留 MD 文件不删除，在摘要中标注失败
- 依赖缺失：先执行 `cd skills/doc-smith-build/scripts && npm install` 再重试

### 7. 校验内容

使用 Skill 工具调用 `doc-smith-check` 校验**本次生成的文档**（使用 `--path` 指定文档路径）：

```
Skill: doc-smith-check --content --path /api/overview
```

校验内容（检查 HTML 文件）：
- HTML 文件存在性（`dist/{lang}/docs/{path}.html`）
- .meta.yaml 完整性
- nav.js 存在性
- 内部链接有效性
- 图片路径正确性

**注意**：使用 `--path` 参数只检查本次生成的文档，避免检查整个目录。

### 8. 验证保存结果

**在结束前必须执行以下检查：**

1. **验证 HTML 文件**：检查 `dist/{locale}/docs/{path}.html` 是否已生成
2. **验证元信息文件**：检查 `docs/{path}/.meta.yaml` 是否存在且内容正确
3. **验证无 MD 残留**：检查 `docs/{path}/` 目录中不存在 `{locale}.md` 文件
4. **如果 HTML 缺失**：重新执行步骤 6（保存 MD）和 6.5（构建 HTML）

### 8.5 检查翻译过期（更新已有文档时）

**仅在更新已有文档时执行**（即 `.meta.yaml` 已存在且包含 `translations` 字段）：

1. 读取 `docs/{path}/.meta.yaml`
2. 检查是否存在 `translations` 字段
3. 如果存在，记录已有的翻译语言列表（如 `en`、`ja`），在步骤 9 的摘要中提醒

### 9. 写入状态文件 & 返回摘要

#### 9.1 写入状态文件

**如果提供了 `状态文件路径` 参数**，使用 Write 工具将 1 行摘要写入该路径：

```
{docPath}: 成功 | HTML ✓ | .meta.yaml ✓ | MD 已清理 | images: 3 ok, 1 failed(deploy-flow) | 翻译过期: en, ja
```

**失败时**也必须写入，内容以"失败"开头：
```
{docPath}: 失败 | 原因: build.mjs 执行报错
```

**写入状态文件是 Task 的最后一个动作。**

#### 9.2 返回文本摘要

返回与状态文件相同的 1 行摘要。（后台模式下此返回值不进入主 agent 上下文，但独立调用时仍有用。）

## 职责边界

**必须执行**：
- ✅ 读取 workspace 约定目录中的配置信息
- ✅ 分析源代码并生成文档内容
- ✅ 创建文档目录和元信息文件
- ✅ 保存 MD 文件（临时）并构建为 HTML（`build.mjs --doc`）
- ✅ 构建成功后删除临时 MD 文件
- ✅ 调用 `/doc-smith-check --content --path <文档路径>` 校验 HTML
- ✅ 更新已有文档时检查翻译过期并提醒
- ✅ 返回摘要信息
- ✅ 如果提供了状态文件路径，在所有步骤完成后写入 1 行状态摘要

**不应执行**：
- ❌ 不创建或修改 document-structure.yaml
- ❌ 不进行 Git 操作
- ❌ 不生成空洞的占位内容
- ❌ 不偏离用户意图
- ❌ 不调用 `build.mjs --nav`（由 doc-smith-create 负责）
- ❌ 不使用 Read 工具读取图片/视频等二进制文件

## 成功标准

1. **完整性**：包含必需章节、导航链接完整
2. **准确性**：与源代码一致、技术细节正确
3. **可读性**：结构清晰、语言流畅、示例恰当
4. **一致性**：风格符合用户意图、格式遵循 doc-smith 规范
5. **构建成功**：`build.mjs --doc` 成功生成 HTML 文件
6. **校验通过**：`/doc-smith-check --content --path <文档路径>` 校验无错误
7. **保存验证**：`.meta.yaml` 存在、HTML 已生成、MD 已清理
8. **长度适当**：符合步骤 1.1 中的长度参考标准

---
name: doc-smith-create
description: "Generate and update structured documentation from project data sources. Supports initial generation and modifying existing documents. Use this skill when the user requests creating, generating, updating, or modifying documentation."
---

# DocSmith 文档生成

从工作区数据源生成和更新结构化文档。所有输出创建在 `.aigne/doc-smith/` workspace 中。

## 约束

以下约束在任何操作中都必须满足。

### 1. Workspace 约束

- 所有操作前 workspace 必须存在且有效（config.yaml + sources）
- workspace 有独立 git 仓库，所有 git 操作在 `.aigne/doc-smith/` 下执行
- workspace 不存在时按以下流程初始化：
  1. `mkdir -p .aigne/doc-smith/{intent,planning,docs,assets,cache}`
  2. `cd .aigne/doc-smith && git init`
  3. 创建 config.yaml（schema 见下方）
  4. 初始 commit

**config.yaml schema**：

```yaml
workspaceVersion: "1.0"
createdAt: "2025-01-13T10:00:00Z"  # ISO 8601
projectName: "my-project"
projectDesc: "项目描述"
locale: "zh"                        # 输出语言代码，初始化时必须向用户确认
projectLogo: ""
translateLanguages: []
sources:
  - type: local-path
    path: "../../"                  # 相对于 workspace
    url: ""                         # 可选: git remote URL
    branch: ""                      # 可选: 当前分支
    commit: ""                      # 可选: 当前 commit
```

**locale 确认规则**：初始化 workspace 时，若用户未明确指定语言，必须用 AskUserQuestion 确认输出语言（如 zh、en、ja），不得默认写入。

### 2. 结构约束

- `document-structure.yaml` 必须符合下方 schema
- 结构变更后必须通过 `/doc-smith-check --structure`
- 结构变更后必须重建 nav.js：`node skills/doc-smith-build/scripts/build.mjs --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist`

**document-structure.yaml schema**：

```yaml
project:
  title: "项目名称"
  description: "项目概述"
documents:
  - title: "文档标题"
    description: "简要摘要"
    path: "/filename"               # 必须以 / 开头
    sourcePaths: ["src/main.py"]    # 源文件路径（无 workspace: 前缀）
    icon: "lucide:book-open"        # 仅顶层文档必需
    children:                       # 可选：嵌套文档
      - title: "子文档"
        description: "详细信息"
        path: "/section/nested"
        sourcePaths: ["src/utils.py"]
```

### 3. 内容约束

- 每篇文档必须有 `docs/{path}/.meta.yaml`（kind: doc, source, default）
- HTML 必须生成在 `dist/{lang}/docs/{path}.html`
- `docs/` 目录中不得残留 `.md` 文件（构建后删除）
- 所有内部链接使用文档 path 格式（如 `/overview/doc-gen`），build.mjs 自动转换为相对 HTML 路径
- 资源引用使用 `/assets/xxx` 绝对路径格式（build.mjs 自动转换为相对路径）

### 4. 人类确认约束

- 用户意图推断后必须经用户确认（使用 AskUserQuestion）
- 文档结构规划后必须经用户确认（使用 AskUserQuestion）
- 确认后若有变更需再次确认

### 5. 上下文管理约束

Task 使用后台执行模式（`run_in_background: true`），执行日志不会回流到主 agent 上下文。主 agent 通过信号文件（`.status`）获取结果。

**实践规则**：
- 主 agent 可自由读取项目源文件，不再受 Task 返回值的上下文预算限制
- 首次生成时，先通过目录结构（`ls`/`Glob`）评估项目规模，再决定结构规划方式：
  - 小项目（源文件少、预计文档 ≤ 5 篇）：主 agent 可直接读取源文件并规划结构
  - 大项目（源文件多、预计文档 > 5 篇）：将结构规划委派给 Task（见"关键流程"）

### 6. Task 分发约束

Task 类型：
- **结构规划** Task（按需）：当项目较大时，委派 Task 分析源文件生成 `document-structure.yaml` 草稿
- **内容生成** Task：按"并行生成文档内容"中的 prompt 模板分发，每篇文档一个 Task

分发规则：
- **所有内容生成 Task 必须使用 `run_in_background: true`**，避免执行日志回流到主 agent 上下文
- 文档数量 ≤ 5 时并行执行，> 5 时分批（每批 ≤ 5 个），前一批完成后再启动下一批
- 内容生成前先执行媒体资源扫描：`Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}`（排除 .aigne/ 和 node_modules/），将结果作为 mediaFiles 传递给每个 Task

信号文件机制：
- 每个 Task 完成时在 `.aigne/doc-smith/cache/task-status/` 写入 `{slug}.status` 文件
- slug 规则：docPath 去除 `/` 前缀后以 `-` 替换 `/`（如 `/api/overview` → `api-overview`）
- 状态文件内容为 1 行摘要（如 `/overview: 成功 | HTML ✓ | .meta.yaml ✓`）
- 主 agent 通过轮询 `.status` 文件判断 Task 是否完成（见"批次执行流程"）

### 7. 完成约束

- `/doc-smith-check --structure` 通过
- `/doc-smith-check --content` 通过
- `dist/` 目录包含所有文档的 HTML
- `nav.js` 包含所有文档条目
- 自动 git commit（在 `.aigne/doc-smith/` 目录下）

## 统一入口

| 场景 | 判断条件 | 行为 |
|------|---------|------|
| 首次生成 | `docs/` 不存在或用户明确要求 | 完整流程：意图 → 结构 → 生成 |
| 修改已有文档 | `docs/` 已存在 | AI 理解修改请求，直接修改，满足约束即可 |

修改场景不需要 changeset/PATCH 机制。用户用自然语言描述修改需求，AI 执行并满足约束。

## 用户意图

文件：`.aigne/doc-smith/intent/user-intent.md`

基于项目 README 和目录结构（`ls`/`Glob`）推断目标用户、使用场景、文档侧重点。生成后用 AskUserQuestion 确认。

```markdown
# 用户意图

## 目标用户
[主要受众是谁]

## 使用场景
- [场景 1]
- [场景 2]

## 文档侧重点
本文档采用**[文档类型]**的形式：
- [侧重点 1]
- [侧重点 2]
```

## 结构规划原则

- 规划必须依据用户意图，只规划明确需要的文档
- 扁平优于嵌套，有疑虑时选择更简单的结构
- 拆分条件：4+ 章节、内容独立、无重复、可独立查阅
- 不拆分：内容单薄、顺序步骤、存在重复
- 结构规划后用 AskUserQuestion 确认，展示文档总数、层次、每个文档的标题和描述

## 内容组织原则

- 导航链接只能链接已生成的文档（使用 path 格式），不链接工作目录文件
- 文档开头：前置条件、父主题
- 文档结尾：相关主题、下一步、子文档
- 有子文档的概览文档：简写（150-300 行），每个子主题 2-4 段 + 引导链接
- 无子文档的详细文档：详写（300-500 行），完整展开

## 关键流程

### 结构规划

主 agent 生成 `user-intent.md` 并经用户确认后，根据项目规模选择结构规划方式：

- **小项目**：主 agent 直接读取源文件，分析后生成 `document-structure.yaml`
- **大项目**：委派 Task 分析源文件并生成 `document-structure.yaml` 草稿，Task 返回文件路径 + 结构摘要（≤ 10 行）

生成后用 AskUserQuestion 向用户确认，展示文档总数、层次、每个文档的标题和描述。

### 生成 nav.js（结构确认后、内容生成前）

```bash
node skills/doc-smith-build/scripts/build.mjs \
  --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist
```

### 图片后端预检测

**在分发内容生成 Task 之前**，主 agent 执行一次图片后端检测，确定可用后端。后台 Task 无法与用户交互，因此必须在前台完成检测。

检测逻辑与 `doc-smith-images` 的「后端检测」部分相同：
1. 检查 `GEMINI_API_KEY` 是否已设置 → 选定 `gemini-sdk`
2. 否则检查 AFS CLI 是否可用 → 选定 `afs-cli`
3. 均不可用 → **必须使用 AskUserQuestion 让用户选择**（配置 API Key / 安装 AFS CLI / 跳过图片生成），禁止自动默认为 skip

检测结果记为 `{IMAGE_BACKEND}`（值为 `gemini-sdk`、`afs-cli` 或 `skip`），传入每个 Task 的 prompt 模板。只有用户明确选择跳过时才可设为 `skip`。

若 `{IMAGE_BACKEND}` 为 `gemini-sdk`，还需确保依赖已安装：
```bash
ls <skill-directory>/scripts/node_modules/@google/genai 2>/dev/null || (cd <skill-directory>/scripts && npm install)
```

### 并行生成文档内容

每篇文档使用单独的 Task tool 生成（≤ 5 篇并行，> 5 篇分批）。**必须使用 `run_in_background: true` 分发 Task**。必须使用以下模板构造 Task prompt，不得自行概括 content.md 内容：

```
你是文档内容生成代理。请先用 Read 工具读取 {CONTENT_MD_PATH} 作为你的完整工作流程，然后严格按照其中的步骤执行。

参数：
- 文档路径：{docPath}
- workspace：{WORKSPACE_PATH}
- 可链接文档列表：{LINKABLE_DOCS}
- mediaFiles：{MEDIA_FILES}
- 用户意图摘要：{INTENT_SUMMARY}
- 状态文件路径：{STATUS_FILE_PATH}
- 图片后端：{IMAGE_BACKEND}

关键工具说明：
- 使用 Skill 工具调用 /doc-smith-images 生成图片（步骤 5.5），必须传入 --backend {IMAGE_BACKEND}
- 使用 Skill 工具调用 /doc-smith-check 校验文档（步骤 7）

完成检查清单（必须在写入状态文件前逐项确认）：
□ 步骤 5 图片使用：文档中已按需添加图片引用
□ 步骤 5.5 图片生成：已扫描并处理所有 /assets/{key}/images/ 引用
□ 步骤 6.5 HTML 构建：已执行 build.mjs --doc 并确认 HTML 生成
□ 步骤 7 校验：已调用 /doc-smith-check --content --path {docPath}
□ 状态文件：已将 1 行摘要写入 {STATUS_FILE_PATH}
```

**模板变量说明**：
- `{CONTENT_MD_PATH}`：`references/content.md` 的绝对路径
- `{WORKSPACE_PATH}`：`.aigne/doc-smith` 的绝对路径
- `{docPath}`：文档路径，如 `/overview`
- `{LINKABLE_DOCS}`：所有文档路径列表（从 document-structure.yaml 提取）
- `{MEDIA_FILES}`：媒体资源扫描结果
- `{INTENT_SUMMARY}`：user-intent.md 的 2-3 句话摘要
- `{STATUS_FILE_PATH}`：`.aigne/doc-smith/cache/task-status/{slug}.status`
- `{IMAGE_BACKEND}`：图片后端检测结果（`gemini-sdk`、`afs-cli` 或 `skip`）

### 批次执行流程

#### 准备阶段

分发第一个 Task 前：
1. `rm -rf .aigne/doc-smith/cache/task-status && mkdir -p .aigne/doc-smith/cache/task-status`（重建目录，清空旧状态）

#### 分发阶段

每个 Task 使用 `run_in_background: true` 分发。批次内所有 Task 同时启动。

#### 等待阶段

每 15 秒检查 `.status` 文件数量：

```bash
find .aigne/doc-smith/cache/task-status -name '*.status' | wc -l
```

- 文件数 = 当前批次文档数 → 该批次完成
- 超时：单批最多等待 10 分钟，超时后报告缺失文档
- **不要读取后台 Task 的 output_file**（可能 300K+），只读 `.status` 文件

#### 收集结果

```bash
find .aigne/doc-smith/cache/task-status -name '*.status' -exec cat {} +
```

每个文件 1 行，所有文档摘要汇总后通常不超过 20 行。

#### 失败处理

- `.status` 内容以"失败"开头 → 记录失败原因，不阻塞后续批次
- 超时未产生 `.status` → 标记为超时，在最终报告中提示用户重试

### AI 巡检

构建完成后，读取 `dist/` 中生成的 HTML 文件（每种语言各抽查 1-2 个页面），检查输出是否符合预期。如有问题直接修改 HTML 文件修复。

### 自动提交

```bash
cd .aigne/doc-smith && git add . && git commit -m "docsmith: xxx"
```

### 完成提示

所有文档生成并校验通过后，向用户展示生成摘要，并提示：

> 文档已生成完毕，可使用 `/doc-smith-publish` 将文档发布到线上预览。

## Workspace 目录结构

```
.aigne/doc-smith/
├── config.yaml
├── intent/user-intent.md
├── planning/document-structure.yaml
├── docs/{path}/.meta.yaml
├── dist/
│   ├── index.html
│   ├── {lang}/docs/{path}.html
│   └── assets/nav.js, docsmith.css, theme.css
├── assets/{key}/.meta.yaml, images/{lang}.png
├── glossary.yaml                  # 可选
└── cache/
    ├── translation-cache.yaml     # 发布用
    └── task-status/{slug}.status  # Task 完成信号文件
```