Docs Management

VitePress 文档站点管理指南

概述

本技能负责"产品级对外文档站点"的完整生命周期管理：

• 初始化：从 templates/update-docs-template/ 复制骨架，根据主项目信息替换占位符
• 增量更新：读取 .docs-meta.json 的 lastSyncCommit，基于 git diff 识别受影响的文档章节
• 风格对齐：生成的文档风格与同级目录的 tauri-docs / tauri-cc-docs / knowledge-base-docs 保持一致（VitePress 1.6.3、纯中文、Hero+Features 首页、h2/h3 分层、表格密集）

与 doc-generation 的区别：doc-generation 生成的是本地 Markdown 文件（给开发者看的 API 参考，输出到 docs/ 作为内部笔记）；本技能管理的是VitePress 站点（面向用户的产品文档，输出到 ./website/ 或 ../xxx-docs/）。

核心规则

文档放置决策树

首次运行（无 .docs-meta.json）
├── 询问用户选择：
│   ├── [1] 同级独立仓库 → ../{project-slug}-docs     （默认 ★ 推荐）
│   ├── [2] 本项目内部    → ./website
│   └── [3] 自定义路径    → 用户输入
├── 读 {project}/package.json 和 src-tauri/tauri.conf.json 获取项目名/描述
├── 复制 templates/update-docs-template/ → 目标位置
├── 替换占位符（见下表）
├── 分析代码生成首版内容
└── 写 .docs-meta.json 到主项目根

后续运行（已有 .docs-meta.json）
├── 读取 lastSyncCommit
├── git diff --name-only {lastSyncCommit}..HEAD
├── 按文件路径 → 文档章节映射（见下表）
├── 聚合同章节变更
├── 展示影响范围给用户确认
├── 生成/更新受影响的 .md
├── 追加 updateHistory 到 .docs-meta.json
└── 提示用户 cd 到文档目录 commit

占位符替换表

初始化时从 templates/update-docs-template/ 复制后，全局替换以下占位符：

文件路径 → 文档章节映射

增量更新时用此表把主项目的代码变更路由到对应文档章节：

聚合规则：同一文档章节的多个源文件变更合并成一篇文档的一次更新，不按文件拆小节。

.docs-meta.json 结构

放在主项目根目录。完整结构：

{
  "version": "1.0.0",
  "docsProject": "tauri-docs",
  "docsLocation": "sibling",
  "docsPath": "../tauri-docs",
  "themeColor": "#0B6EF0",
  "lastSyncCommit": "a1c6cc8",
  "lastSyncTime": "2026-04-19T15:30:00Z",
  "coveredSections": ["guide", "api", "backend", "frontend"],
  "updateHistory": [
    {
      "commit": "a1c6cc8",
      "time": "2026-04-19T15:30:00Z",
      "type": "init",
      "affectedDocs": ["index.md", "guide/introduction.md", ...],
      "sourceChanges": []
    },
    {
      "commit": "b2d7ef1",
      "time": "2026-04-20T10:00:00Z",
      "type": "incremental",
      "affectedDocs": ["api/commands.md"],
      "sourceChanges": ["src-tauri/src/commands/user.rs"]
    }
  ]
}

字段含义：

执行流程

流程 A：首次初始化

1. 检测主项目根 .docs-meta.json 是否存在
   └─ 不存在 → 进入初始化

2. 交互收集项目信息（依次询问）:
   Q1: 文档放哪里？
       [1] 同级独立仓库 ../{slug}-docs   (推荐)
       [2] 本项目内部  ./website
       [3] 自定义路径  [用户输入]
   Q2: 项目对外名称？              (默认读 tauri.conf.json productName)
   Q3: 一句话描述？                (默认读 package.json description)
   Q4: 主题色？                     (默认 #0B6EF0)
   Q5: 站点 URL？                   (默认 https://example.com，可跳过)

3. 复制模板:
   cp -r templates/update-docs-template/* <目标路径>/
   cp templates/update-docs-template/.gitignore <目标路径>/
   cp templates/update-docs-template/.docs-meta.template.json <主项目根>/.docs-meta.json
   (注意：docs-meta 放主项目根，不是目标路径)

4. 替换占位符（见上方占位符表）:
   对 <目标路径> 下所有 .md / .ts / .css / .svg / .json 递归替换

5. 分析主项目生成初版内容:
   - 读 src-tauri/src/commands/*.rs 填充 api/commands.md 的索引表
   - 读 Cargo.toml / package.json 填充 guide/quickstart.md 的版本
   - 读 README.md 填充 guide/introduction.md 的核心特性

6. (仅 sibling) git 初始化:
   cd <目标路径>
   git init
   git add -A
   git commit -m "📝 docs: 初始化文档站点"
   (不推送，由用户手动)

7. 输出提示:
   ✅ 文档站点已初始化到 <目标路径>
   📋 元数据已写入 .docs-meta.json
   下一步：
     cd <目标路径>
     pnpm install
     pnpm dev       # http://localhost:5173

流程 B：增量更新

1. 读取 .docs-meta.json，确认 lastSyncCommit 和 docsPath

2. git diff --name-only <lastSyncCommit>..HEAD
   → 得到变更文件列表

3. 按"文件路径 → 文档章节映射"表路由:
   src-tauri/src/commands/user.rs → api/commands.md
   src-tauri/src/services/user.rs → backend/services.md
   ...

4. 聚合同章节变更，输出影响范围:
   ## 本次将更新的文档章节
   | 章节 | 受影响的源文件 |
   |------|---------------|
   | api/commands.md | src-tauri/src/commands/user.rs (+2 commands) |
   | backend/services.md | src-tauri/src/services/user.rs |

   确认更新吗？[y/N]

5. 用户确认后逐章节重写受影响段落:
   - 只改 <!-- 本章由 /update-docs ... --> 标记的段落
   - 手工添加的段落保留
   - 索引表（如 api/commands.md 的 Command 清单）整体重生成

6. 追加 updateHistory 到 .docs-meta.json:
   - lastSyncCommit = git rev-parse HEAD
   - lastSyncTime = now
   - 追加一条 updateHistory 记录

7. 输出提示:
   ✅ 已更新 N 篇文档
   下一步：
     cd <docsPath>
     git diff              # 查看变化
     git commit -am "..."  # 手动提交

流程 C：全量重建（/update-docs full）

与流程 B 类似，但：
- 不看 lastSyncCommit，所有章节重新基于当前代码生成
- updateHistory type = "full"
- 保留 docs/public/ 下用户添加的图片
- 保留用户手动新增的 .md 文件（不删除）

生成文档的写作风格（与 tauri-docs 一致）

实战示例：增量更新片段

场景：主项目新增了 commands/user.rs，含两个 Command list_users 和 create_user。

步骤 1 — diff 识别：

git diff --name-only a1c6cc8..HEAD
# src-tauri/src/commands/user.rs
# src-tauri/src/lib.rs  (generate_handler! 新增两项)

步骤 2 — 路由：

src-tauri/src/commands/user.rs → api/commands.md
src-tauri/src/lib.rs            → 跳过（仅注册表，不单独成章）

步骤 3 — 扫描 Command 签名：

// src-tauri/src/commands/user.rs
#[tauri::command]
pub fn list_users(state: State<'_, AppState>) -> Result<Vec<User>, CommandError> { ... }

#[tauri::command]
pub fn create_user(state: State<'_, AppState>, name: String, email: String) -> Result<User, CommandError> { ... }

步骤 4 — 更新 api/commands.md 索引表：

| Command | 模块 | 简述 |
|---------|------|------|
| `list_users` | user | 列出所有用户 |
| `create_user` | user | 创建新用户 |

步骤 5 — 为每个新 Command 生成一节：

### `list_users`

**签名**：`fn list_users(state: State<'_, AppState>) -> Result<Vec<User>, CommandError>`

**参数**：无（仅注入 AppState）

**返回**：`User[]`

**前端调用**：

\`\`\`typescript
import { userApi } from "@/lib/api";
const users = await userApi.list();
\`\`\`

步骤 6 — 更新 .docs-meta.json：

{
  "lastSyncCommit": "b2d7ef1",
  "lastSyncTime": "2026-04-20T10:00:00Z",
  "updateHistory": [
    ...,
    {
      "commit": "b2d7ef1",
      "time": "2026-04-20T10:00:00Z",
      "type": "incremental",
      "affectedDocs": ["api/commands.md"],
      "sourceChanges": ["src-tauri/src/commands/user.rs"]
    }
  ]
}

常见错误与最佳实践

相关技能

• add-skill — 技能维护流程（本技能本身遵循这些规范）
• project-navigator — 主项目结构导航（映射表的依据）
• doc-generation — 旧技能，生成本地 Markdown API 参考（与本技能互补不冲突）
• release-publish — 发版时可以顺便 /update-docs 更新文档