doc-smith-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DocSmith 文档生成

DocSmith Documentation Generation

从工作区数据源生成和更新结构化文档。所有输出创建在

.aigne/doc-smith/

workspace 中。

Generate and update structured documentation from workspace data sources. All outputs are created in the

.aigne/doc-smith/

workspace.

约束

Constraints

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

The following constraints must be satisfied in all operations.

1. Workspace 约束

1. Workspace Constraints

所有操作前 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），不得默认写入。

The workspace must exist and be valid (config.yaml + sources) before any operation
The workspace has an independent git repository, and all git operations are performed under
```
.aigne/doc-smith/
```
If the workspace does not exist, initialize it following this process:
1. ```
mkdir -p .aigne/doc-smith/{intent,planning,docs,assets,cache}
```
2. ```
cd .aigne/doc-smith && git init
```
3. Create config.yaml (schema see below)
4. Initial commit

config.yaml schema：

yaml

workspaceVersion: "1.0"
createdAt: "2025-01-13T10:00:00Z"  # ISO 8601
projectName: "my-project"
projectDesc: "Project description"
locale: "zh"                        # Output language code, must confirm with user during initialization
projectLogo: ""
translateLanguages: []
sources:
  - type: local-path
    path: "../../"                  # Relative to workspace
    url: ""                         # Optional: git remote URL
    branch: ""                      # Optional: current branch
    commit: ""                      # Optional: current commit

Locale Confirmation Rule: When initializing the workspace, if the user does not explicitly specify the language, must use AskUserQuestion to confirm the output language (e.g., zh, en, ja), and must not write a default value.

2. 结构约束

2. Structure Constraints

```
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"]

```
document-structure.yaml
```
must comply with the schema below
After structure changes, must pass
```
/doc-smith-check --structure
```

After structure changes, must rebuild 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: "Project Name"
  description: "Project Overview"
documents:
  - title: "Document Title"
    description: "Brief Summary"
    path: "/filename"               # Must start with /
    sourcePaths: ["src/main.py"]    # Source file path (no workspace: prefix)
    icon: "lucide:book-open"        # Required only for top-level documents
    children:                       # Optional: nested documents
      - title: "Sub-document"
        description: "Detailed Information"
        path: "/section/nested"
        sourcePaths: ["src/utils.py"]

3. 内容约束

3. Content Constraints

每篇文档必须有
```
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 自动转换为相对路径）

Each document must have
```
docs/{path}/.meta.yaml
```
(kind: doc, source, default)
HTML must be generated in
```
dist/{lang}/docs/{path}.html
```
No
```
.md
```
files shall remain in the
```
docs/
```
directory (delete after build)
All internal links use the document path format (e.g.,
```
/overview/doc-gen
```
), build.mjs automatically converts to relative HTML paths
Resource references use the absolute path format
```
/assets/xxx
```
(build.mjs automatically converts to relative paths)

4. 人类确认约束

4. Human Confirmation Constraints

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

After inferring user intent, must confirm with the user (using AskUserQuestion)
After planning the document structure, must confirm with the user (using AskUserQuestion)
If there are changes after confirmation, re-confirmation is required

5. 上下文管理约束

5. Context Management Constraints

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

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

实践规则：

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

The main agent can read project source files, but must reserve context space for subsequent Task results.

Judgment Principle: The amount of source files read by the main agent + the total summary volume returned by all subsequent Tasks must not exceed the context budget. The more documents there are, the more Task results there will be, and the smaller the space for the main agent to read source files itself.

Practical Rules:

When modifying a small number of existing documents, directly reading the relevant source files is acceptable
For initial generation: first evaluate the project scale through directory structure (
```
ls
```
/
```
Glob
```
), then decide the structure planning method:
- Small projects (few source files, expected documents ≤5): The main agent can directly read source files and plan the structure
- Large projects (many source files, expected documents >5): Delegate structure planning to a Task (see "Key Processes")

6. Task 分发约束

6. Task Distribution Constraints

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 行），避免返回文件内容

Task Types:

Structure Planning Task (on-demand): When the project is large, delegate a Task to analyze source files and generate a draft of
```
document-structure.yaml
```
Content Generation Task: Distribute according to the prompt template in "Parallel Generation of Document Content", one Task per document

Distribution Rules:

Execute in parallel when the number of documents ≤5; batch execution when >5 (≤5 per batch), start the next batch only after the previous one is completed
Perform media resource scanning before content generation:
```
Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}
```
(exclude .aigne/ and node_modules/), pass the result as mediaFiles to each Task
All summaries returned by Tasks must be brief (≤10 lines), avoid returning file content

7. 完成约束

7. Completion Constraints

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

Pass
```
/doc-smith-check --structure
```
Pass
```
/doc-smith-check --content
```
The
```
dist/
```
directory contains HTML for all documents
```
nav.js
```
contains all document entries
Automatic git commit (under
```
.aigne/doc-smith/
```
directory)

统一入口

Unified Entry

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

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

Scenario	Judgment Condition	Action
Initial Generation	`docs/` does not exist or user explicitly requests	Full process: Intent → Structure → Generation
Modify Existing Documents	`docs/` already exists	The AI understands the modification request, makes direct modifications, and only needs to satisfy the constraints

No changeset/PATCH mechanism is required for modification scenarios. Users describe modification requirements in natural language, and the AI executes them while satisfying constraints.

用户意图

User Intent

文件：

.aigne/doc-smith/intent/user-intent.md

基于项目 README 和目录结构（

ls

Glob

）推断目标用户、使用场景、文档侧重点。生成后用 AskUserQuestion 确认。

markdown

undefined

File:

.aigne/doc-smith/intent/user-intent.md

Infer target users, usage scenarios, and document focus based on the project README and directory structure (

ls

Glob

). Confirm with AskUserQuestion after generation.

markdown

undefined

用户意图

User Intent

目标用户

Target Users

[主要受众是谁]

[Who are the main audiences]

使用场景

Usage Scenarios

[场景 1]
[场景 2]

[Scenario 1]
[Scenario 2]

文档侧重点

Document Focus

本文档采用**[文档类型]**的形式：

[侧重点 1]
[侧重点 2]

undefined

This document adopts the form of [Document Type]:

[Focus 1]
[Focus 2]

undefined

结构规划原则

Structure Planning Principles

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

Planning must be based on user intent, only plan documents that are clearly needed
Flat structure is better than nested; choose a simpler structure when in doubt
Split conditions: 4+ chapters, independent content, no duplication, can be accessed independently
Do not split: thin content, sequential steps, duplication exists
After structure planning, confirm with the user using AskUserQuestion, showing the total number of documents, hierarchy, and the title and description of each document

内容组织原则

Content Organization Principles

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

Navigation links can only link to generated documents (using path format), not to working directory files
Document opening: prerequisites, parent topic
Document ending: related topics, next steps, sub-documents
Overview documents with sub-documents: concise (150-300 words), 2-4 paragraphs per sub-topic + guiding links
Detailed documents without sub-documents: detailed (300-500 words), fully expanded

关键流程

Key Processes

结构规划

Structure Planning

主 agent 生成

user-intent.md

并经用户确认后，根据项目规模选择结构规划方式：

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

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

After the main agent generates

user-intent.md

and confirms it with the user, select the structure planning method based on project scale:

Small Projects: The main agent directly reads source files, analyzes them, and generates
```
document-structure.yaml
```
Large Projects: Delegate a Task to analyze source files and generate a draft of
```
document-structure.yaml
```
, the Task returns the file path + structure summary (≤10 lines)

After generation, confirm with the user using AskUserQuestion, showing the total number of documents, hierarchy, and the title and description of each document.

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

Generate nav.js (After Structure Confirmation, Before Content Generation)

bash

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

bash

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

并行生成文档内容

Parallel Generation of Document Content

每篇文档使用单独的 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 句话摘要

Each document is generated using a separate Task tool (≤5 in parallel, batch when >5). Must use the following template to construct the Task prompt, do not summarize the content of content.md on your own:

You are a documentation content generation agent. Please first use the Read tool to read {CONTENT_MD_PATH} as your complete workflow, then strictly follow the steps outlined in it.

Parameters:
- Document Path: {docPath}
- Workspace: {WORKSPACE_PATH}
- Linkable Documents List: {LINKABLE_DOCS}
- mediaFiles: {MEDIA_FILES}
- User Intent Summary: {INTENT_SUMMARY}

Key Tool Instructions:
- Use the Skill tool to call /doc-smith-images to generate images (Step 5.5)
- Use the Skill tool to call /doc-smith-check to validate documents (Step 7)

Completion Checklist (must confirm each item before returning the summary):
□ Step 5 Image Usage: Image references have been added to the document as needed
□ Step 5.5 Image Generation: All /assets/{key}/images/ references have been scanned and processed
□ Step 6.5 HTML Build: build.mjs --doc has been executed and HTML generation confirmed
□ Step 7 Validation: /doc-smith-check --content --path {docPath} has been called

Template Variable Explanation:

```
{CONTENT_MD_PATH}
```
: Absolute path of
```
references/content.md
```
```
{WORKSPACE_PATH}
```
: Absolute path of
```
.aigne/doc-smith
```
```
{docPath}
```
: Document path, e.g.,
```
/overview
```
```
{LINKABLE_DOCS}
```
: List of all document paths (extracted from document-structure.yaml)
```
{MEDIA_FILES}
```
: Media resource scanning results
```
{INTENT_SUMMARY}
```
: 2-3 sentence summary of user-intent.md

AI 巡检

AI Inspection

构建完成后，读取

dist/

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

After build completion, read the generated HTML files in

dist/

(spot-check 1-2 pages per language), check if the output meets expectations. If there are issues, directly modify the HTML files to fix them.

自动提交

Automatic Commit

bash

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

bash

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

完成提示

Completion Prompt

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

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

After all documents are generated and validated, display the generation summary to the user and prompt:

Documentation generation is complete. You can use
/doc-smith-publish
to publish the documentation for online preview.

Workspace 目录结构

Workspace Directory Structure

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

.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                  # Optional
└── cache/translation-cache.yaml   # For publishing