---
name: wiki-synchelper
description: Wiki同步助手（Wiki SyncHelper）——用于"项目实现内容"与"开发Wiki文档"之间的双向同步。服务对象为AI开发流程，确保AI可基于Wiki快速理解项目现状并按规范继续开发。触发场景：(1) 用户要求扫描/比对/同步/报告项目与Wiki的差异；(2) 代码实现已更新但Wiki文档未跟进；(3) Wiki文档需要反向修正代码结构；(4) 用户说"同步Wiki"、"更新文档"、"Wiki和代码不一致"、"wiki-synchelper"、"扫描文档差异"，或调用 init/scan/diff/sync/report 命令。本技能完全通用，不含任何项目特定路径，通过 wiki-sync.yaml 适配各项目。
---

# Wiki同步助手（wiki-synchelper）

## 设计原则

**技能本身完全通用**，不包含任何项目特定路径或映射。所有项目配置存储于项目根目录的 `wiki-sync.yaml`。多项目复用只需每个项目维护自己的配置文件。

**约定**：Wiki 文档根目录默认为 `repowiki/`（`init` 命令自动识别此目录）。

两个同步方向：
- **方向A（项目→Wiki）**：代码变更后，更新 Wiki 反映最新实现
- **方向B（Wiki→项目）**：Wiki 规范更新后，生成代码合规性检查待办清单

---

## 配置文件发现顺序

执行任何命令前，按以下顺序查找配置（找到即停止）：

1. 命令行参数：`--config <path>`
2. 当前工作目录：`./wiki-sync.yaml`
3. 项目根目录（向上查找含 `.git` 的目录）：`<git-root>/wiki-sync.yaml`
4. `.claude/` 目录：`.claude/wiki-sync.yaml`

未找到时：提示运行 `init` 命令生成配置，然后中止。

---

## 命令接口

### `init` — 初始化配置

**功能**：扫描项目结构，自动生成 `wiki-sync.yaml` 配置模板。

**执行步骤**：
1. 检测项目根目录（寻找 `.git`）
2. 自动发现 Wiki 目录（优先查找 `repowiki/`，其次 `wiki/`、`docs/`）
3. 列出发现的目录，**询问用户确认 source_paths 和 wiki_root**
4. 生成 `wiki-sync.yaml`（`write_enabled: false`，只读模式）

---

### `scan` — 扫描

**功能**：只读扫描，枚举项目模块与 Wiki 文档的对应关系，不修改任何文件。

**输出示例**：
```
[SCAN] 扫描结果
  配置：<git-root>/wiki-sync.yaml
  项目模块数：12 | Wiki文档数：10 | 已覆盖：9
  未覆盖（项目有/Wiki无）：2 → [ModuleA, ModuleB]
  孤立Wiki（项目已删除/未映射）：1 → [repowiki/zh/content/OldSystem.md]
```

**执行步骤**：
1. 读取并验证配置（路径不存在则中止报错）
2. 遍历 `source_paths`，按 `ignore.source` 过滤，建立模块列表
3. 遍历 `wiki_root`，按 `ignore.wiki` 过滤，建立文档列表
4. 按 `mappings` 做交叉比对，输出覆盖状态表

---

### `diff` — 比对

**功能**：对已匹配的模块/文档对，检测内容差异（只读）。

**参数**：`--target <模块名>` 限定单个模块；`--dir A|B|both`（默认 both）

**输出示例**：
```
[DIFF] ModuleA/SkillSystem ↔ repowiki/zh/content/.../技能系统.md
  ▸ [新增] 枚举值 SkillPhase.Cast（Wiki未记录）
  ▸ [重命名] SkillCooldown → CooldownTick（代码已更新，Wiki未跟进）
  ▸ [孤立] Wiki描述的 SkillPrecast() 在代码中已删除
  建议：sync --dir A --target ModuleA/SkillSystem
```

**执行步骤**：
1. 执行 `scan`，获取已匹配对
2. 对每对：读取代码结构（类名、公共方法、枚举）+ 读取 Wiki 内容
3. 对比并标记差异类型：`新增` / `删除` / `重命名` / `语义变更`

---

### `sync` — 同步

**功能**：根据差异执行实际写入，**需显式开启写入模式**。

**开启写入**：配置 `write_enabled: true` 或命令行传入 `--write`。

**同步方向**：
- `--dir A`：项目→Wiki（更新 Wiki 文档）
- `--dir B`：Wiki→项目（生成 `WIKI_SYNC_TODO.md`，**不自动改代码**）
- `--dir both`：双向，冲突按策略处理

**冲突策略**（`conflict_strategy`）：

| 值 | 行为 |
|----|------|
| `ask`（默认）| 每个冲突项暂停，等待用户决策 |
| `prefer_code` | 以代码为准，覆盖 Wiki |
| `prefer_wiki` | 以 Wiki 为准，生成代码修改建议 |
| `skip` | 跳过冲突项，记录到报告 |

**执行步骤**：
1. 检查 `write_enabled`，为 false 时拒绝并提示
2. 执行 `diff`，获取差异列表
3. 写入前备份目标文件
4. 检测敏感信息 → 脱敏 → 写入
5. 输出操作日志

---

### `report` — 报告

**功能**：生成完整同步状态报告（Markdown），可输出到文件。

**参数**：`--output <path>`（默认输出到控制台）

**输出内容**：覆盖率统计、差异概览、建议操作清单

---

## 配置文件规范

**文件名**：`wiki-sync.yaml`（项目根目录，不提交到技能目录）

```yaml
# wiki-sync.yaml — 项目特定配置，不属于技能本身
version: "1.0"

source_paths:
  - path: "src"          # 相对于项目根目录，按实际填写
    label: "Source"

wiki_root: "repowiki"    # Wiki 文档根目录，默认约定为 repowiki/

mappings:
  - source_pattern: "src/ModuleA/**"
    wiki_path: "zh/content/ModuleA"

ignore:
  source: ["**/*.meta", "**/bin/**", "**/obj/**"]
  wiki:   ["**/草稿/**", "**/Archive/**", "**/_*"]

conflict_strategy: ask   # ask | prefer_code | prefer_wiki | skip

write_enabled: false     # 必须显式改为 true 才允许写入

backup:
  enabled: true
  directory: ".wiki-sync-backups"

sensitive_patterns:
  - pattern: "(api[_-]?key|secret|password|token|pwd)\\s*[:=]\\s*\\S+"
    replacement: "<REDACTED>"

report:
  default_output: "wiki-sync-report.md"
  include_diff_detail: true
  include_suggestions: true
```

> 完整配置字段说明见 [references/config-reference.md](references/config-reference.md)

---

## 典型工作流

**新项目首次使用**：
```
init    → 扫描项目，生成 wiki-sync.yaml（需确认路径）
scan    → 验证配置，查看覆盖率
```

**代码更新后同步 Wiki**：
```
scan                        → 查看哪些模块缺少 Wiki
diff                        → 查看现有 Wiki 的过时内容
sync --dir A --write        → 更新 Wiki（需先将 write_enabled 改为 true）
report                      → 生成变更报告
```

**Wiki 规范更新后检查代码合规**：
```
diff --dir B                → 检查代码是否符合最新 Wiki 规范
report --output check.md   → 方向B输出 WIKI_SYNC_TODO.md，供开发者手动跟进
```

---

## 异常处理

| 异常 | 行为 |
|------|------|
| 配置文件不存在 | **中止**，提示运行 `init` |
| 路径不存在 | **中止**，列出缺失路径 |
| 无写入权限 | **中止** |
| `write_enabled: false` 时调用 sync | **拒绝**，提示修改配置或传入 `--write` |
| 两侧都有变更（冲突） | 按 `conflict_strategy` 处理 |
| 检测到敏感信息 | 脱敏后继续，日志标注位置 |
| Wiki 文档格式错误 | 警告后跳过，继续处理其余 |

---

## 安全约束（强制）

1. **默认只读**：所有命令默认不修改任何文件
2. **脱敏必须**：敏感信息不得写入 Wiki
3. **备份优先**：写入前强制备份
4. **方向B只读代码**：不自动修改代码，只生成待办清单
5. **错误即停**：任一前置条件不满足，立即中止，不做部分写入