name	iwiki-sync
title	iwiki-sync — AI 工作区与 iWiki 双向同步
description	同步 AI 工作区文档到 iWiki、从 iWiki 回写本地、做日常增量对齐时使用。只要用户提到“同步到 iWiki”“从 iWiki 拉取”“双向更新”“补齐映射”“重传文档”“个人空间目录对齐”，都应立即使用本 Skill。

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 是否已更新
后续建议：是否需要执行一次全量巡检

Más de este repositorio

mismo repositorio

work-schedule

ZhuoZhuoCrayon/ai-workspace

需求排期录入工具——将工作事项同步到企业微信智能表格。当用户提到"加入排期"、"录入排期"、"更新排期表"、"需求排期"、"把 xxx 加到排期"等意图时触发。也适用于用户提供新周期 schema/key 要求配置新文档的场景。

2026-07-0625

knowledge-mgr

ZhuoZhuoCrayon/ai-workspace

管理工作区知识对象的检索与全生命周期操作，路径涉及 `knowledge/`，知识对象包括 issue（需求）、plan（方案 / 计划）、snippet（代码片段）、article（文章）和 troubleshooting（排障经验）。当用户询问事项进展、最近做了什么、周报 / 日报 / 总结素材，或者问题依赖历史结论、过往决策时，应优先使用本 skill。当用户要求将结论沉淀到知识对象体系，或者要求检索、创建、修改、归档、迁移知识对象时，应使用本 skill 执行相关操作。外部资料调研、纯代码实现 & 调试 & 测试等无需落地知识对象的行为不属于本 skill 场景。

2026-07-0225

doc-style

ZhuoZhuoCrayon/ai-workspace

结构化编写、重构、润色和验收 Markdown / MDC 文档。只要用户要创建、编辑、润色、改写、评审或整理任何 `.md` / `.mdc` 文件，或需要整理规则文档、普通说明文档、PR review 评论、GitHub 评论、零散草稿，就应使用这个 skill。

2026-06-2025

dev-env

ZhuoZhuoCrayon/ai-workspace

准备和修复 Go、Node.js、Python 本地开发环境。用于版本切换、工具链缺失、依赖环境异常、虚拟环境问题，以及编译、测试、检查命令中的环境类失败。典型信号：系统已装版本低于 `go.mod`、`.nvmrc`、`pyproject.toml` 要求，出现 `invalid go version`，找不到 `gvm`、`nvm`、`uv`，或 `uv sync` 报错。在判定环境不可用或跳过、假装跳过编译、测试前，必须先用本 skill 尝试切换或修复环境。

2026-06-1825

code-style

ZhuoZhuoCrayon/ai-workspace

统一通用代码风格与实现约束：按目标项目规范（AGENTS.md / CONTRIBUTING.md）与语言参考约束命名、格式、复杂度与错误处理。编写、修改、评审任意语言源码或迁移代码规则时使用，交付代码前据此确保改动符合项目与工作区风格。

2026-06-0825

git-workflow

ZhuoZhuoCrayon/ai-workspace

Git 提交规范。用户要求提交、commit、拆分提交、起草 commit message、整理待提交范围或处理暂存区时必须使用。用于区分工作区知识库提交与非工作区项目提交：默认按工作区规范，用户明确要求提交其他项目时遵循项目自身规范。

2026-06-0825

name	iwiki-sync
title	iwiki-sync — AI 工作区与 iWiki 双向同步
description	同步 AI 工作区文档到 iWiki、从 iWiki 回写本地、做日常增量对齐时使用。只要用户提到“同步到 iWiki”“从 iWiki 拉取”“双向更新”“补齐映射”“重传文档”“个人空间目录对齐”，都应立即使用本 Skill。

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 是否已更新
后续建议：是否需要执行一次全量巡检