### Start DocSmith

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Run the 'aigne doc' command in your project root to start the interactive documentation generation process. This command automatically installs DocSmith on first execution.

```bash
cd my-project
aigne doc
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Install all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Aigne CLI

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Install the Aigne CLI globally using npm. This command is required before you can start using DocSmith.

```bash
npm install -g @aigne/cli
```

--------------------------------

### Config.yaml Example (Standalone Mode)

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Shows the configuration file content for standalone mode, with an empty sources array to be populated later in the dialogue.

```yaml
mode: standalone
sources: []
```

--------------------------------

### Config.yaml Example (Project Mode)

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Illustrates the configuration file content for project-internal mode, specifying the 'project' mode and 'local-path' source type with git information.

```yaml
mode: project
sources:
  - type: local-path
    path: "../../"                           # 相对路径（用于 AFS 挂载）
    url: "git@github.com:user/project.git"   # 远程仓库 URL（origin）
    branch: "main"                           # 当前分支
    commit: "a1b2c3d"                        # 当前 commit hash（短格式）
```

--------------------------------

### Example Summary of Changes

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

Use 1-3 sentences to describe the scope and focus of the changes. Avoid expanding the scope if no position anchor is provided.

```text
本次为全局语义调整 + 局部重写：统一术语，补充快速开始章节
```

--------------------------------

### Error Message: Git Not Installed

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Displays an error message indicating that Git is not installed and provides a link to the official Git download page.

```text
错误: 未检测到 Git

DocSmith 需要 Git 来管理数据源。
请先安装 Git: https://git-scm.com/downloads
```

--------------------------------

### Example Acceptance Criteria

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

A checklist for verifying the correctness of changes. Each item should be checked off, and any unmet criteria must be explained.

```text
- [ ] 全局术语统一：API、Blocklet、Workspace 一致
- [ ] 快速开始章节已补充环境要求
- [ ] 文档无重复段落、无矛盾
- [ ] 所有链接有效
- [ ] 代码块都有语言标识符
```

--------------------------------

### Configure Multiple Data Sources

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Example configuration file for setting up multiple data sources for Aigne Doc Smith, including local paths and Git repositories.

```yaml
# config.yaml
sources:
  - name: "main"
    type: local-path
    path: "../my-project"

  - name: "other-repo"
    type: git-clone
    url: "https://github.com/example/repo.git"
    branch: "main"
```

--------------------------------

### Example Global Semantic Changes

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

Examples of cross-document term, style, and naming consistency modifications. These should be executed before local rewrites and avoid excessive changes.

```text
1. 术语统一:"API" → "API 接口"、"blocklet" → "Blocklet"
2. 风格调整:删除第一人称，保持中立第三人称
3. 格式规范:代码块统一添加语言标识符
```

--------------------------------

### Create New Skill with Skill Creator

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/CLAUDE.md

Use the skill-creator command to get guidance and create a new Skill. Follow the instructions provided by skill-creator for folder structure and content.

```bash
# 1. 使用 skill-creator 获取指导
/skill-creator

# 2. 按照 skill-creator 的指导创建 Skill 文件夹和内容
```

--------------------------------

### Example Additional Data/References

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

Examples of adding or correcting reference information to provide more accurate context. This includes term table updates or referencing external documents.

```text
1. 术语表更新: `Workspace` → 独立的文档工作空间
2. 参考文档: /path/to/api-v2.md
```

--------------------------------

### Execution Order for Changeset Files

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

The recommended sequence for processing Changeset files, starting from finding the file to outputting a summary aligned with acceptance criteria.

```text
1. 找到 changeset 文件 → 提取用户信息中的文件信息，使用 pattern 搜索 changeset 文件
1. 读取 changeset 文件 → 建立全局约束
2. 扫描文档 → 定位所有 PATCH
3. 执行 PATCH → 确定性变更
4. 应用全局语义修改 → 遍历所有文档
5. 执行局部结构重写 → 利用 Additional Data
6. 一致性检查 → 术语、风格、结构
7. 输出摘要 → 对齐 Acceptance Criteria
```

--------------------------------

### Example Clarifications/Corrections

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

Examples of understanding corrections for initial goals, scope, constraints, or audience. These have the highest priority and may require re-evaluating the entire document.

```text
1. 受众修正:从技术开发者改为产品经理
2. 输出澄清:"全自动"指 patch 自动合并，非跳过人工审核
3. 语气调整:从营销宣传改为朴实技术说明
```

--------------------------------

### Doc-Smith Workflow Diagram

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Illustrates the startup and initialization process of the Doc-Smith agent, including workspace detection and configuration loading.

```text
doc-smith 启动
  ↓
加载 index.mjs（使用 top-level await）
  ↓
检测当前目录状态
  ↓
├─ config.yaml 已存在 → 读取配置，生成 AFS modules
├─ 是 git 仓库（无 config.yaml）→ 执行项目内初始化，生成 AFS modules
├─ 是空目录或非 git 目录 → 执行独立初始化，生成 AFS modules
└─ 其他情况 → 报错退出
  ↓
导出配置对象（含动态生成的 AFS modules）
  ↓
进入文档生成对话模式
```

--------------------------------

### DocSmith Initialization Logic Flow

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/ai/intent/sources-improve.md

This flowchart illustrates the automatic detection and initialization process for DocSmith. It outlines the steps taken based on whether the current directory is a git repository, determining the startup path and subsequent actions.

```text
docsmith init
  ↓
检测当前目录
  ↓
├─ 是 git 仓库 → 项目内启动
│   ├─ 创建 .docsmith/ 子目录
│   ├─ git init（独立仓库）
│   ├─ 添加为 submodule
│   └─ 配置 local-path: "../"
│
└─ 非 git 仓库 → 独立启动
    ├─ 在当前目录初始化
    ├─ git init
    ├─ 询问数据源 URL
    └─ 配置 git-clone

```

--------------------------------

### Initialize Aigne Doc Smith Workspace

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Create a new workspace and initialize Aigne Doc Smith for documentation generation.

```bash
mkdir my-docs
cd my-docs
aigne doc
```

--------------------------------

### Doc-smith Main Workflow

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith-docs-detail/ai/intent.md

Illustrates the main workflow of the doc-smith system, highlighting the step where doc-smith-docs-detail is called in batch to generate individual document content.

```text
doc-smith 主流程:
1. Workspace 检测与初始化
2. 分析数据源
3. 推断用户意图
4. 规划文档结构 → 生成 document-structure.yaml
5. 确认文档结构
6. [批量调用 doc-smith-docs-detail] 生成各文档内容
   ├─ 调用 agent(path: "/overview")
   ├─ 调用 agent(path: "/api/auth")
   └─ 调用 agent(path: "/guides/install")
7. 生成 AFS 图片
8. 最终校验与提交
```

--------------------------------

### Example Structural Rewrite Request

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/changeset-guide.md

Requests for rewriting or refactoring specific sections/paragraphs or adjusting document structure. Specify the target, issue, and rewrite goal. Prioritize PATCH operations first.

```text
Target: overview.md, Introduction 章节
Issue: 缺少项目背景
Rewrite Goal: 补充项目定位、核心价值、适用场景
```

--------------------------------

### Project-Internal Initialization Structure

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Defines the directory structure created during project-internal initialization, including configuration, intent, planning, and docs directories.

```tree
.aigne/
└── doc-smith/
    ├── .git/                # 独立 git 仓库
    ├── .gitignore           # 忽略 sources/ 目录
    ├── config.yaml          # 工作空间配置
    ├── intent/              # 意图文件目录
    ├── planning/            # 规划文件目录
    └── docs/                # 生成的文档目录
```

--------------------------------

### Data Source Check Flowchart

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Visualizes the process for checking data sources configured in `config.yaml`, including handling cases where sources are empty or directories are missing.

```text
读取 config.yaml 中的 sources 配置
  ↓
├─ sources 为空或不存在 → 询问用户提供仓库 URL（5.2）
└─ sources 存在 → 检查 /sources/ 目录
    ├─ 目录存在 → 跳过，继续后续流程
    └─ 目录不存在 → 执行恢复流程（5.3）
```

--------------------------------

### 扫描 PATCH 标记

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/patch-guide.md

使用 Grep 命令查找文档目录下的所有 PATCH 标记。

```bash
pattern: ":::\s*PATCH"
path: docs/
output_mode: files_with_matches
```

--------------------------------

### Find Media Files

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/document-content-guide.md

Use this command to locate all media files (images, videos) within the workspace. Record all results for reference.

```bash
find . -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.svg" -o -name "*.mp4" -o -name "*.webp" \)
```

--------------------------------

### Standalone Initialization Structure

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Defines the directory structure created during standalone initialization, including a sources directory for future additions.

```tree
./                           # 当前目录
├── .git/
├── .gitignore               # 包含 sources/
├── config.yaml              # 工作空间配置
├── sources/                 # 源仓库目录（后续添加）
├── intent/
├── planning/
└── docs/
```

--------------------------------

### Doc-Smith File Structure

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills-entry/doc-smith/ai/intent.md

Outlines the file structure for the Doc-Smith agent, including the main entry point, utility functions, prompt file, and AI intent directory.

```tree
skills-entry/doc-smith/
├── index.mjs            # 主入口（含初始化逻辑和配置导出）
├── utils.mjs            # 共享工具函数
├── prompt.md            # agent 指令文件
└── ai/
    └── intent/
        └── doc-smith.md # 本文档
```

--------------------------------

### Agent Skill Entry Configuration (YAML)

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith-docs-detail/ai/intent.md

Shows the YAML configuration for registering the doc-smith-docs-detail agent skill, including its type, name, description, instructions path, and associated skills.

```yaml
# skills-entry/doc-smith-docs-detail/index.mjs
# 导出 JavaScript 配置对象
type: "@aigne/agent-library/agent-skill-manager"
name: generateDocumentDetail
description: 根据文档路径和用户要求生成文档详细内容

instructions: ../../skills/doc-smith-docs-detail/SKILL.md

skills:
  - url: ../../agents/save-document/index.mjs    # 保存文档工具

input_schema:
  type: object
  required:
    - path
  properties:
    path:
      type: string
      description: 文档路径，与 document-structure.yaml 中的 path 一致
    customRequirements:
      type: string
      description: 用户在对话中提出的额外要求（可选）

output_schema:
  type: object
  required:
    - success
  properties:
    success:
      type: boolean
    path:
      type: string
    summary:
      type: string
      description: 文档摘要（200-300字）
    sections:
      type: array
      items:
        type: string
      description: 主要章节列表
    imageSlots:
      type: array
      items:
        type: string
      description: 生成的 AFS image slots ID 列表
    validationResult:
      type: object
      description: checkContent 的校验结果
```

--------------------------------

### PATCH 标记格式：替换内容

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/patch-guide.md

使用此格式在文档中指定要替换的旧内容和新的替换内容。

```markdown
::: PATCH
# Original
旧内容

# Revised
新内容
:::
```

--------------------------------

### PATCH 标记格式：插入内容

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/patch-guide.md

用于在文档的特定位置插入新内容。支持在指定锚点后或前插入。

```markdown
::: PATCH
# Insert After: "## 章节标题"

新增的内容
:::
```

--------------------------------

### Prompt for Selecting Output Language

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Presents a user prompt for selecting the desired output language for documentation, offering a list of common languages and an option for custom input.

```text
请选择文档输出语言:
1. English (en)
2. 简体中文 (zh)
3. 繁體中文 (zh-TW)
4. 日本語 (ja)
5. 한국어 (ko)
6. Español (es)
7. Français (fr)
8. Deutsch (de)
9. Português (pt)
10. Русский (ru)
11. Italiano (it)
12. العربية (ar)
13. 其他 (请输入语言代码)
```

--------------------------------

### PATCH 标记格式：删除内容

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/patch-guide.md

用于从文档中删除指定的内容。

```markdown
::: PATCH
# Delete

要删除的内容
:::
```

--------------------------------

### Clone Git Repository Command

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Demonstrates the bash command used to clone a Git repository, specifying a branch, URL, and destination directory, and then retrieving the commit hash.

```bash
git clone -b <branch> <url> sources/<project-name>
cd /sources/<project-name>
git rev-parse HEAD  # 获取 commit hash
```

--------------------------------

### Doc-smith Skill Registration (YAML)

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith-docs-detail/ai/intent.md

Demonstrates how to register the doc-smith-docs-detail skill within the main doc-smith entry configuration.

```yaml
# skills-entry/doc-smith/index.yaml
skills:
  - url: ../doc-smith-docs-detail/index.mjs
  # ... 其他 skills
```

--------------------------------

### Config.yaml Schema for DocSmith Workspace

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Illustrates the schema for the `config.yaml` file, which defines workspace metadata, project information, documentation settings, and data source configurations.

```yaml
# Workspace metadata
workspaceVersion: "1.0"
createdAt: "2025-01-13T10:00:00Z"

# Project information
projectName: "my-project"
projectDesc: "项目描述"
locale: "zh"

# Documentation settings (for publish)
projectLogo: ""
translateLanguages: []

# 数据源配置（数组）
sources:
  # local-path 类型
  - name: "main"
    type: local-path
    path: "../../"              # 相对于 workspace 的路径

  # git-clone 类型
  - name: "aigne-framework"
    type: git-clone
    url: "https://github.com/ArcBlock/aigne-framework.git"
    branch: "main"                    # 分支名（用于恢复）
    commit: "a1b2c3d4e5f6789..."      # 完整的 commit hash
    clonedAt: "2025-01-13T10:00:00Z"  # 克隆/更新时间
```

--------------------------------

### Code Quality Checks with Biome

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/README.md

Commands to check and automatically fix code quality issues using Biome.

```bash
# Check code
pnpm run lint

# Auto fix
pnpm run lint:fix
```

--------------------------------

### PATCH 应用摘要

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/patch-guide.md

展示 PATCH 操作执行后的输出摘要，包括修改的总数和具体文件及修改说明。

```markdown
✓ PATCH 应用：N 处精确修改
  - overview.md: 修正定位说明
  - quick-start.md: 新增环境要求章节
  - api.md: 删除过时说明
```

--------------------------------

### Modify Existing Skill with Skill Creator

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/CLAUDE.md

When modifying an existing Skill, consult skill-creator for updated guidance if necessary. Then, proceed with editing the Skill files.

```bash
# 1. 如需要，使用 skill-creator 获取更新指导
/skill-creator

# 2. 编辑 Skill 文件
```

--------------------------------

### Agent Output Format

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith-docs-detail/ai/intent.md

Defines the expected return format for the agent, which includes success status, document path, summary, sections, image slots, and validation results. It explicitly states that the full document content is not returned.

```javascript
{
  success: boolean,
  path: string,              // 文档路径，如 "/api/overview"
  summary: string,           // 文档摘要（200-300字）
  sections: string[],        // 主要章节列表
  imageSlots: string[],      // 生成的 AFS image slots ID 列表
  validationResult: object   // checkContent 的校验结果
}
```

--------------------------------

### Update Config.yaml with New Data Source

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/references/workspace-initialization.md

Shows the YAML structure for updating `config.yaml` after adding a new Git-cloned data source, including its name, type, URL, branch, commit hash, and timestamp.

```yaml
sources:
  - name: "<project-name>"
    type: git-clone
    url: "<url>"
    branch: "<branch>"
    commit: "<commit-hash>"
    clonedAt: "<current-timestamp>"
```

--------------------------------

### Function Agent Basic Structure (JavaScript)

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/CLAUDE.md

Defines the basic structure for a Function Agent, which is a pure JavaScript implementation not reliant on LLM capabilities. It includes the main async function and optional properties for description and input schema.

```javascript
// 基本结构
export default async function agentName(input, options) {
  const { prompts, context } = options;

  // 业务逻辑...

  return { success: true, data: result };
}

// 可选：描述和输入 schema
agentName.description = "Agent 功能描述";
agentName.input_schema = {
  type: "object",
  properties: {
    param1: { type: "string", description: "参数说明" }
  }
};
```

--------------------------------

### DocSmith Add Source CLI Commands

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/skills/doc-smith/ai/intent/sources-improve.md

These bash commands demonstrate how to add new data sources to a DocSmith workspace after initialization. They support adding both local paths and remote git repositories.

```bash
docsmith add-source https://github.com/ArcBlock/aigne-framework.git
```

```bash
docsmith add-source ../another-local-project --type local-path
```

--------------------------------

### Intent Document General Structure

Source: https://github.com/aigne-io/aigne-doc-smith/blob/main/CLAUDE.md

This markdown structure outlines the standard format for intent documents, which describe a feature's intent, constraints, and expected outcomes without including implementation details or pseudocode.

```markdown
# {功能名称} 功能意图

## 功能概述
[一句话概述功能是什么]

## 功能意图
[为什么需要这个功能，要解决什么问题，背景是什么]

## 工作流程
[在整体系统中的位置，与其他组件的交互时序，调用关系]

## 核心能力
[功能的主要能力点，列举 3-5 个关键能力]

## 输入输出
### 输入
- 必需输入：[必须提供的信息]
- 可选输入：[可选提供的信息]
- 自动获取：[从配置或上下文自动获取的信息]

### 输出
- 输出内容：[功能产生的结果]
- 输出格式：[结果的格式或结构]

## 约束条件
### 必须遵循的规范
[格式规范、标准、协议等]

### 职责边界
- 必须执行：[这个功能必须做的事]
- 不应执行：[这个功能不应该做的事]
- 协作方式：[与其他组件的协作关系]

## 预期结果
### 成功标准
[如何判断功能成功，具体的标准]

## 错误处理
### 常见错误
[可能遇到的错误场景]

### 处理策略
[如何处理这些错误]

## 实现方式
[实现的技术选型、架构设计、集成方式等说明]

---
**注意**：本文档描述功能意图，不包含具体实现细节。
```