---
name: wiki-update
description: >-
agent_created: true
  Use when docs/20-prd or docs/30-system-design markdown files are created or
  modified and need to be synced to the wiki/ directory. Triggered by user
  command or wiki-queue hook suggestion at session stop. Supports full and
  incremental sync modes.
---

# Wiki Update

将 `{PRD_DIR}/` 和 `{DESIGN_DIR}/` 下的 Markdown 文档同步到 `{WIKI_DIR}/` 目录，保持目录结构一致。

## 路径配置加载

在开始执行之前，先确定源目录和目标目录：

1. 检查项目根目录是否存在 `.adspecs/paths.json`
2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
3. 如果不存在或配置键缺失，使用下方表格中的默认值

| 配置键       | 默认值                  | 用途                  |
| ------------ | ----------------------- | --------------------- |
| `prd_dir`    | `docs/20-prd`           | PRD 文档源目录        |
| `design_dir` | `docs/30-system-design` | 系统设计文档源目录    |
| `wiki_dir`   | `wiki`                  | Wiki 文档输出目标目录 |

将解析后的路径分别记为 `PRD_DIR`、`DESIGN_DIR` 和 `WIKI_DIR`，后续步骤中引用这些变量而非硬编码路径。

## When to Use

- 用户执行 `/wiki-update`
- 会话结束时 hook 提示 `[wiki-update] Run: /wiki-update --mode=incremental --flush`
- 需要更新项目 wiki 文档时

## 参数

| 参数      | 值             | 说明                        |
| --------- | -------------- | --------------------------- |
| `--mode`  | `full`（默认） | 全量扫描并同步所有 .md 文件 |
| `--mode`  | `incremental`  | 仅同步队列中的变更文件      |
| `--flush` | 无值           | 增量同步后清空队列文件      |

**示例调用：**

- `/wiki-update` — 全量同步
- `/wiki-update --mode=incremental --flush` — 增量同步并清空队列

## 目录映射

```
{PRD_DIR}/{子路径}           → {WIKI_DIR}/20-prd/{子路径}
{DESIGN_DIR}/{子路径} → {WIKI_DIR}/30-system-design/{子路径}
```

**完整结构示例：**

```
{WIKI_DIR}/
├── 20-prd/
│   └── crm/
│       ├── customer-master-data/
│       │   └── M03-01_客户主数据需求规格说明书.md
│       ├── fo-order/
│       │   └── M08-01_履约单需求规格说明书.md
│       ├── product-master-data/
│       │   └── M01-01_产品主数据需求规格说明书.md
│       ├── sales-forecast/
│       │   └── M06-01_销售预测需求规格说明书.md
│       └── one-time-contract/
│           └── M07-02_单次合同需求规格说明书.md
└── 30-system-design/
    └── crm/
        ├── M01-01-产品主数据_system-design.md
        ├── M01-01-产品主数据_tasks.md
        ├── M03-01-客户主数据_system-design.md
        └── ...（所有 .md 文件）
```

## 文件过滤规则

| 文件类型          | 是否同步 | 原因                       |
| ----------------- | -------- | -------------------------- |
| `*.md`            | ✅ 同步  | Wiki 文档内容              |
| `*.html`          | ❌ 跳过  | HTML 原型，非 wiki 格式    |
| `*.sql`           | ❌ 跳过  | 数据库 schema，非文档      |
| `*.xlsx`          | ❌ 跳过  | Excel 附件                 |
| `checklists/*.md` | ✅ 同步  | checklist 也是文档的一部分 |

## 执行步骤

### Full 模式（全量同步）

```
┌─────────────────────────────────────┐
│ 1. 扫描源目录                         │
│    Glob: {PRD_DIR}/**/*.md          │
│    Glob: {DESIGN_DIR}/**/*.md       │
│                                     │
│ 2. 对每个 .md 文件:                   │
│    ├─ Read 源文件内容                  │
│    ├─ 计算 wiki 目标路径               │
│    └─ Write 到 {WIKI_DIR}/ 对应路径   │
│                                     │
│ 3. 输出同步报告                        │
│    - 新增文件数                        │
│    - 更新文件数                        │
│    - 总文件数                          │
└─────────────────────────────────────┘
```

**步骤 1 — 扫描源目录：**

使用 Glob 工具扫描两个源目录下所有 `.md` 文件：

```
Glob("{PRD_DIR}/**/*.md")
Glob("{DESIGN_DIR}/**/*.md")
```

**步骤 2 — 逐文件同步：**

对每个扫描到的文件：

1. 用 `Read` 读取完整内容
2. 计算目标路径：将源目录前缀替换为 `{WIKI_DIR}/`
   - `{PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md` → `{WIKI_DIR}/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md`
   - `{DESIGN_DIR}/crm/M06-01-销售预测_system-design.md` → `{WIKI_DIR}/30-system-design/crm/M06-01-销售预测_system-design.md`
3. 用 `Write` 写入 wiki 目标路径（自动创建目录）

**步骤 3 — 输出报告：**

```
═══ [wiki-update] 全量同步完成 ═══════════
  新增: 12 个文件
  更新: 5 个文件
  总计: 17 个文件
═══════════════════════════════════════════
```

### Incremental 模式（增量同步）

```
┌─────────────────────────────────────┐
│ 1. 读取队列文件                        │
│    .claude/.wiki-update-queue       │
│                                     │
│ 2. 过滤: 仅保留 {PRD_DIR}/ 或        │
│    {DESIGN_DIR}/ 下的 .md            │
│                                     │
│ 3. 对每个文件:                        │
│    ├─ 检查源文件是否存在               │
│    ├─ Read + Write 到 wiki 路径       │
│    └─ 记录同步状态                     │
│                                     │
│ 4. 若指定 --flush:                    │
│    └─ 清空 .wiki-update-queue        │
│                                     │
│ 5. 输出同步报告                        │
└─────────────────────────────────────┘
```

**步骤 1 — 读取队列：**

读取 `.claude/.wiki-update-queue`，每行一个文件路径。

**步骤 2 — 过滤文件：**

仅保留同时满足以下条件的文件：

- 路径包含 `{PRD_DIR}/` 或 `{DESIGN_DIR}/`
- 以 `.md` 结尾

**步骤 3 — 同步文件：**

同 full 模式的步骤 2，但仅处理过滤后的文件列表。

**步骤 4 — 清空队列（--flush）：**

仅移除已处理的 wiki 相关条目，保留其他路径（如 `.java`、`.ts` 等非 wiki 文件路径）：

1. 重新读取 `.claude/.wiki-update-queue`
2. 过滤掉已同步的文件路径（即匹配 `{PRD_DIR}/` 或 `{DESIGN_DIR}/` 且以 `.md` 结尾的行）
3. 将剩余行写回队列文件；若无剩余行，写入空字符串

**步骤 5 — 输出报告：**

```
═══ [wiki-update] 增量同步完成 ═══════════
  同步: 3 个文件
  跳过: 1 个文件（非 wiki 目录）
  队列已清空 ✓
═══════════════════════════════════════════
```

## 路径计算逻辑

源路径到 wiki 路径的转换规则：

```
输入: {PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md
      └─ 替换源目录前缀为 {WIKI_DIR}/

输出: {WIKI_DIR}/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md
```

代码逻辑（伪代码）：

```
wikiPath = sourcePath
  .replace(/^\{PRD_DIR\}\//, '{WIKI_DIR}/20-prd/')
  .replace(/^\{DESIGN_DIR\}\//, '{WIKI_DIR}/30-system-design/')
```

## 错误处理

| 情况                   | 处理方式                                  |
| ---------------------- | ----------------------------------------- |
| 源文件不存在（已删除） | 跳过，输出 `[跳过] 文件不存在: {path}`    |
| 队列为空               | 输出 `队列为空，无需同步`，直接结束       |
| wiki 目录不存在        | 自动创建                                  |
| 队列文件不存在         | 输出 `队列文件不存在`，提示使用 full 模式 |

## Common Mistakes

| 错误                               | 正确做法                                       |
| ---------------------------------- | ---------------------------------------------- |
| 同步 .sql 或 .html 文件            | 仅同步 .md 文件                                |
| 修改 wiki 目录结构（如扁平化）     | 严格保持与 docs 相同的目录层级                 |
| 增量模式忘记清空队列               | 指定 `--flush` 时务必清空 `.wiki-update-queue` |
| 将 `docs/300-specs/` 等同步到 wiki | 仅同步 `20-prd` 和 `30-system-design`          |
| 使用文件复制命令                   | 使用 Read + Write 确保跨平台兼容               |