ai-workspace: Skill for Claude Code

iwiki-sync — AI 工作区与 iWiki 双向同步

目标：让 knowledge/ 与 iWiki 个人空间保持可持续、可回溯、可增量的双向同步。

MCP Server：user-iWiki

0x00 前置约束

1. 同步范围默认从 knowledge/<project>/ 开始，不直接同步整个仓库。
2. INDEX.md 默认不同步（仅同步 issue 实体文档）。
3. 所有路径使用工作区根目录相对路径。
4. 同步前必须先读取 .iwiki-sync.json。
5. 调用任何 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）

1. 读取 .iwiki-sync.json，确认 space_id、homepage_id 与 root_title。
2. 扫描本地目录，过滤掉 INDEX.md。
3. 对每个条目按映射判断：
   • 无映射：新增（createDocument）。
   • 有映射：更新（saveDocument）。
4. 新增时先确保父目录存在，再创建子目录/文件。
5. 每次创建或更新后立即回写 .iwiki-sync.json。

新增操作规范：

• FOLDER：contenttype="FOLDER"，body 传 " "。
• MD：contenttype="MD"，body 传完整 Markdown。

更新操作规范：

• 使用 saveDocument(docid, title, body)。
• 即使只改标题，也传非空 body。

0x04 下载流程（iWiki -> 本地）

1. 根据 .iwiki-sync.json 取目标 docid。
2. 调用 getDocument 获取远端正文。
3. 写回本地对应路径（不存在则创建）。
4. 更新映射项中的 last_sync_at 与状态字段。