doc-smith-create

DocSmith ドキュメント生成

ワークスペースのデータソースから構造化ドキュメントを生成・更新します。すべての出力は .aigne/doc-smith/ ワークスペース内に作成されます。

制約

以下の制約は、すべての操作で必ず守る必要があります。

1. ワークスペースの制約

• すべての操作の前に、ワークスペースが存在し、有効である必要があります（config.yaml + sources）
• ワークスペースは独立した git リポジトリを持ち、すべての git 操作は .aigne/doc-smith/ 内で実行します
• ワークスペースが存在しない場合は、以下の手順で初期化します：
  1. mkdir -p .aigne/doc-smith/{intent,planning,docs,assets,cache}
  2. cd .aigne/doc-smith && git init
  3. config.yaml を作成します（スキーマは以下を参照）
  4. 初期 commit を作成します

config.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 の確認ルール：ワークスペースの初期化時に、ユーザーが言語を明示的に指定していない場合は、AskUserQuestion を使って出力言語（例：zh、en、ja）を必ず確認し、デフォルト値を書き込んではなりません。

2. 構造の制約

• document-structure.yaml は以下のスキーマに準拠する必要があります
• 構造の変更後は、/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 スキーマ：

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）を使用します。実行ログはメインエージェントのコンテキストに戻りません。メインエージェントはシグナルファイル（.status）で結果を取得します。

運用ルール：

• メインエージェントはプロジェクトのソースファイルを自由に読み取ることができ、Task の戻り値によるコンテキスト予算の制限を受けません
• 初回生成時は、まずディレクトリ構造（ls/Glob）でプロジェクトの規模を評価してから、構造計画の方法を決定します：
  • 小規模プロジェクト（ソースファイルが少なく、予想されるドキュメント数が 5 件以下）：メインエージェントがソースファイルを直接読み取り、構造を計画できます
  • 大規模プロジェクト（ソースファイルが多く、予想されるドキュメント数が 5 件超）：構造計画を Task に委任します（「主要なフロー」を参照）

6. Task 分配の制約

Task の種類：

• 構造計画 Task（必要に応じて）：プロジェクトが大規模な場合、ソースファイルを分析して document-structure.yaml の草案を作成するよう Task に委任します
• コンテンツ生成 Task：「ドキュメントコンテンツの並列生成」の prompt テンプレートに従って分配し、ドキュメントごとに 1 つの Task を実行します

分配ルール：

• すべてのコンテンツ生成 Task は run_in_background: true を必ず使用し、実行ログがメインエージェントのコンテキストに戻らないようにします
• ドキュメント数が 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 ✓）
• メインエージェントは .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 で確認します。

# 用户意图

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

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

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

構造計画の原則

• 計画はユーザーの意図に基づき、明確に必要なドキュメントのみを計画します
• ネストよりフラットな構造を優先し、迷った場合はよりシンプルな構造を選択します
• 分割条件：4 つ以上の章、内容が独立している、重複がない、単独で参照できる
• 分割しない条件：内容が薄い、順序に沿った手順、重複がある
• 構造計画後、AskUserQuestion で確認します。ドキュメントの総数、階層、各ドキュメントのタイトルと説明を提示します

コンテンツ構成の原則

• ナビゲーションリンクは生成済みのドキュメント（path 形式）のみにリンクし、作業ディレクトリ内のファイルにはリンクしません
• ドキュメントの冒頭：前提条件、親トピック
• ドキュメントの末尾：関連トピック、次のステップ、子ドキュメント
• 子ドキュメントがある概要ドキュメント：簡潔に記述します（150～300 行）。各子トピックは 2～4 段落とし、誘導リンクを付けます
• 子ドキュメントがない詳細ドキュメント：詳しく記述します（300～500 行）。内容を完全に展開します

主要なフロー

構造計画

メインエージェントは user-intent.md を生成してユーザーの確認を得た後、プロジェクトの規模に応じて構造計画の方法を選択します：

• 小規模プロジェクト：メインエージェントがソースファイルを直接読み取り、分析後に document-structure.yaml を生成します
• 大規模プロジェクト：ソースファイルを分析して document-structure.yaml の草案を作成するよう Task に委任します。Task はファイルパスと構造の要約（10 行以下）を返します

生成後、AskUserQuestion でユーザーに確認します。ドキュメントの総数、階層、各ドキュメントのタイトルと説明を提示します。

nav.js の生成（構造確認後、コンテンツ生成前）

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

画像バックエンドの事前検出

コンテンツ生成 Task を分配する前に、メインエージェントが画像バックエンドの検出を 1 回実行し、利用可能なバックエンドを特定します。バックグラウンド 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 の場合は、依存関係がインストールされていることも確認します：

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 文件数量：

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

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

收集结果

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

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

失败处理

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

AI 巡检

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

自动提交

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 完成信号文件