| 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 规范更新后，生成代码合规性检查待办清单
配置文件发现顺序
执行任何命令前，按以下顺序查找配置（找到即停止）：
- 命令行参数：
--config <path>
- 当前工作目录：
./wiki-sync.yaml
- 项目根目录（向上查找含
.git 的目录）：<git-root>/wiki-sync.yaml
.claude/ 目录：.claude/wiki-sync.yaml
未找到时：提示运行 init 命令生成配置，然后中止。
命令接口
init — 初始化配置
功能：扫描项目结构，自动生成 wiki-sync.yaml 配置模板。
执行步骤：
- 检测项目根目录（寻找
.git）
- 自动发现 Wiki 目录（优先查找
repowiki/，其次 wiki/、docs/）
- 列出发现的目录，询问用户确认 source_paths 和 wiki_root
- 生成
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]
执行步骤：
- 读取并验证配置（路径不存在则中止报错）
- 遍历
source_paths，按 ignore.source 过滤，建立模块列表
- 遍历
wiki_root，按 ignore.wiki 过滤，建立文档列表
- 按
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
执行步骤：
- 执行
scan，获取已匹配对
- 对每对：读取代码结构（类名、公共方法、枚举）+ 读取 Wiki 内容
- 对比并标记差异类型：
新增 / 删除 / 重命名 / 语义变更
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 | 跳过冲突项，记录到报告 |
执行步骤：
- 检查
write_enabled，为 false 时拒绝并提示
- 执行
diff，获取差异列表
- 写入前备份目标文件
- 检测敏感信息 → 脱敏 → 写入
- 输出操作日志
report — 报告
功能：生成完整同步状态报告（Markdown），可输出到文件。
参数：--output <path>（默认输出到控制台）
输出内容：覆盖率统计、差异概览、建议操作清单
配置文件规范
文件名：wiki-sync.yaml（项目根目录，不提交到技能目录）
version: "1.0"
source_paths:
- path: "src"
label: "Source"
wiki_root: "repowiki"
mappings:
- source_pattern: "src/ModuleA/**"
wiki_path: "zh/content/ModuleA"
ignore:
source: ["**/*.meta", "**/bin/**", "**/obj/**"]
wiki: ["**/草稿/**", "**/Archive/**", "**/_*"]
conflict_strategy: ask
write_enabled: false
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
典型工作流
新项目首次使用：
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 文档格式错误 | 警告后跳过，继续处理其余 |
安全约束（强制）
- 默认只读：所有命令默认不修改任何文件
- 脱敏必须：敏感信息不得写入 Wiki
- 备份优先：写入前强制备份
- 方向B只读代码：不自动修改代码，只生成待办清单
- 错误即停：任一前置条件不满足，立即中止，不做部分写入
