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：

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：

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. 上下文管理约束

主 agent 可以读取项目源文件，但必须为后续 Task 结果预留上下文空间。

判断原则：主 agent 读取的源文件量 + 后续所有 Task 返回的摘要量，不能超出上下文预算。文档越多，Task 结果越多，主 agent 自身读取源文件的空间越小。

实践规则：

• 修改少量已有文档时，直接读取相关源文件没有问题
• 首次生成时，先通过目录结构（ls/Glob）评估项目规模，再决定结构规划方式：
  • 小项目（源文件少、预计文档 ≤ 5 篇）：主 agent 可直接读取源文件并规划结构
  • 大项目（源文件多、预计文档 > 5 篇）：将结构规划委派给 Task（见”关键流程”）

6. Task 分发约束

Task 类型：

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

分发规则：

• 文档数量 ≤ 5 时并行执行，> 5 时分批（每批 ≤ 5 个），前一批完成后再启动下一批
• 内容生成前先执行媒体资源扫描：Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}（排除 .aigne/ 和 node_modules/），将结果作为 mediaFiles 传递给每个 Task
• 所有 Task 返回的摘要必须简短（≤ 10 行），避免返回文件内容

7. 完成约束

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

统一入口

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

用户意图

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

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

# 用户意图

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

## 使用场景
- [场景 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（结构确认后、内容生成前）

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

并行生成文档内容

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

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

参数：
- 文档路径：{docPath}
- workspace：{WORKSPACE_PATH}
- 可链接文档列表：{LINKABLE_DOCS}
- mediaFiles：{MEDIA_FILES}
- 用户意图摘要：{INTENT_SUMMARY}

关键工具说明：
- 使用 Skill 工具调用 /doc-smith-images 生成图片（步骤 5.5）
- 使用 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}

模板变量说明：

• {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 句话摘要

AI 巡检

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

自动提交

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

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   # 发布用