zhuozhuocrayon iwiki-sync — AI 工作区与 iWiki 双向同步
目标：让 knowledge/ 与 iWiki 个人空间保持可持续、可回溯、可增量的双向同步。
MCP Server：user-iWiki
0x00 前置约束
- 同步范围默认从
knowledge/<project>/开始，不直接同步整个仓库。 INDEX.md默认不同步（仅同步 issue 实体文档）。- 所有路径使用工作区根目录相对路径。
- 同步前必须先读取
.iwiki-sync.json。 - 调用任何 iWiki MCP 工具前，必须先读取对应工具 schema（
mcps/user-iWiki/tools/*.json）。
0x01 映射文件规范
位置：工作区根目录 .iwiki-sync.json（应被 .gitignore 忽略）。
建议结构：
{
"space_id": 136740934,
"homepage_id": 135057649,
"root_title": "AI 工作区",
"sync_policy": {
"index_sync": false,
"conflict_mode": "manual",
"deletion_mode": "tombstone"
},
"mappings": {
"knowledge/bkmonitor/issues/2026-03-03-apm-shared-datasource/README.md": {
"docid": 4018554751,
"type": "MD",
"iwiki_title": "需求",
"last_local_updated": "2026-03-03",
"last_sync_at": "2026-03-08T12:30:00Z",
"status": "active"
}
}
}
字段说明：
space_id/homepage_id: iWiki 定位信息。root_title: iWiki 顶层目录名，固定为AI 工作区。sync_policy.conflict_mode:manual | local_wins | remote_wins。sync_policy.deletion_mode: 推荐tombstone（标记删除，不做远端删除）。mappings[*].status:active | tombstone。
0x02 命名与目录映射
目录骨架固定为：AI 工作区 → <project> → <category>。
命名规则：
- issue 文件夹：
{date}-{frontmatter.title}。 README.md→需求。PLAN.md→实施方案。PROGRESS.md→进展。INDEX.md：默认不同步。
示例：
- 本地
knowledge/bkmonitor/issues/2026-03-03-apm-shared-datasource/ - iWiki 标题
2026-03-03-APM 支持跨应用共享数据源
0x03 上传流程（本地 -> iWiki）
- 读取
.iwiki-sync.json，确认space_id、homepage_id与root_title。 - 扫描本地目录，过滤掉
INDEX.md。 - 对每个条目按映射判断：
- 无映射：新增（
createDocument）。 - 有映射：更新（
saveDocument）。
- 无映射：新增（
- 新增时先确保父目录存在，再创建子目录/文件。
- 每次创建或更新后立即回写
.iwiki-sync.json。
新增操作规范：
- FOLDER：
contenttype="FOLDER"，body传" "。 - MD：
contenttype="MD"，body传完整 Markdown。
更新操作规范：
- 使用
saveDocument(docid, title, body)。 - 即使只改标题，也传非空
body。
0x04 下载流程（iWiki -> 本地）
- 根据
.iwiki-sync.json取目标docid。 - 调用
getDocument获取远端正文。 - 写回本地对应路径（不存在则创建）。
- 更新映射项中的
last_sync_at与状态字段。
适用场景：
- 用户在 iWiki 手动修正文档后，需要回写本地。
- 本地文件丢失，需要从 iWiki 恢复。
0x05 冲突与删除策略
a. 冲突识别
当“本地 updated 晚于 last_sync_at”且“远端也发生变更”时，判定为冲突。
b. 冲突处理
manual（默认）：停止自动覆盖，提示用户选择来源。local_wins：本地覆盖远端。remote_wins：远端覆盖本地。
c. 删除处理
由于无 deleteDocument API，不执行物理删除：
- 本地删除时，将映射状态改为
tombstone。 - 可选：远端文档重命名为
[已归档] <title>，用于人工清理。
0x06 API 实战约束（已验证）
createDocument与saveDocument在当前环境下都应传非空body。- FOLDER 也要传
body: " "。 - 长文档直接内联调用容易 JSON 截断，建议分批或使用 Task 子任务执行。
- 无
deleteDocument，删除需走 tombstone/归档策略。
0x07 日常巡检清单
每次同步后执行：
- 抽样检查 iWiki 目录层级是否符合命名规范。
- 对比同步文件数与
mappings活跃条目数。 - 检查是否存在“本地有文件但无 mapping”的漏同步项。
- 检查是否存在“mapping 有 docid 但远端不可读”的失效项。
- 记录本次同步摘要（新增/更新/冲突/tombstone 数）。
0x08 输出模板（给用户）
同步任务结束后按以下结构汇报：
- 同步方向：本地 -> iWiki / iWiki -> 本地 / 双向
- 处理结果：新增 N、更新 N、冲突 N、tombstone N
- 失败项：列出路径 + 原因 + 建议重试动作
- 映射状态：
.iwiki-sync.json是否已更新 - 后续建议：是否需要执行一次全量巡检