doc-smith-create

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）
• 确认后若有变更需再次确认