Soia Pkm Bootstrap Vault Ima

soia-pkm-bootstrap-vault-ima

把已有本地 Markdown vault 接入腾讯 ima（ima.qq.com）作为云端消费端。同步方向是 vault → ima；本地 Markdown、frontmatter、目录和 Git（若启用）是唯一真身，ima 中的内容不反向覆盖 vault。

客户可读说明

这个技能可以做什么

本 skill 不负责从零创建 vault，也不编造 ima 客户端的按钮名称、菜单路径或未公开 API。ima 具体 UI 操作未经本次实测，首次执行时必须以客户端实际界面为准并校正本文档。

客户如何使用

1. 提供已有 vault 路径、希望同步的相对目录、目标 ima 知识库和一篇用于验证的文章标题。
2. 安装并登录 ima 客户端。
3. 先确定不能是 vault 根或整个 20 区的目录 allowlist，并完成敏感级别预检，再在 ima 官方 Skills 中配置本地文件夹监控。
4. 首次同步只选一篇或一个小目录，确认层级、标题和正文后再扩大范围。
5. 在 ima 搜索验证文章；任何冲突都以本地 Markdown 为准，不从 ima 反向写回。

依赖与安装

安装本 skill（hard dependency 会同时要求 base）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-bootstrap-vault-ima -y

配置约定：

~/.config/soia-skills/soia-pkm-bootstrap-vault-ima/config.yml
SOIA_PKM_BOOTSTRAP_VAULT_IMA_CONFIG_FILE=<custom-config-path>

官方入口：

• ima 官网与客户端下载入口：https://ima.qq.com/
• ima 的 Skills、本地文件夹监控和知识库界面会随客户端版本变化；未实测部分标注为“以 ima 客户端实际界面为准，首次执行时校正本文档”。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

日志与完成回执

回执至少包含：客户端登录检查、目标知识库和本地 allowlist（只写相对目录）、首次同步范围、成功/跳过/失败数量、检索验证结果和仍需用户手动校正的 UI 步骤。不得打印账号、token、私有文件内容或本机绝对路径。

接入流程

1. 安装客户端并登录

打开 ima 官方入口，安装电脑端客户端并登录。官网当前提供“打开电脑版”和客户端下载入口；具体安装提示以官方页面和本机系统为准。

2. 创建知识库并制定目录映射

在 ima 客户端创建一个用于消费 vault 内容的知识库。具体创建动作和字段名称未经实测，以 ima 客户端实际界面为准，首次执行时校正本文档。

只允许用户明确选择、并能持续保证不混入敏感笔记的子目录 allowlist。整个 vault、整个 20_资料库/ 或历史导入树都不是合法同步源：

路径允许不等于内容允许。先运行 fail-closed 预检；它只输出相对路径、计数与风险代码，不输出命中值：

python3 scripts/preflight_sync.py --vault <vault-path> \
  --path-prefix '20_资料库/<精选分类>/<明确云端范围>'

缺少/非法 sensitivity、值为 private/restricted、疑似凭据/私有绝对路径、symlink 或无法分类的附件都会使 ready=false。版权和业务授权仍需人工复核。没有明确范围或无法保证未来新增文件遵守同一规则时暂停，不要开启监控。

映射记录至少包含：

本地 vault/<相对目录>  →  ima/<知识库>/<对应目录>
同步方向：vault → ima
排除：.obsidian/、.git/、.env、私密目录、未确认的日志/草稿

3. 配置 ima 官方 Skills 的本地文件夹监控

在 ima 的官方 Skills 能力中选择本地文件夹监控/知识库导入类能力，将上一步的本地 allowlist 目录映射到目标知识库。具体 Skill 名称、授权提示、监控开关、知识库选择和目录映射 UI 未经实测，必须以 ima 客户端实际界面为准，首次执行时校正本文档；不要根据本 skill 猜测按钮或菜单路径。

首次配置硬门：

1. 运行预检并输出相对目录 allowlist、文件数、敏感级别分布与拒绝项；必须 ready=true，报告不得含正文或秘密值。
2. 只选择一个已通过预检的测试子目录，不选择 20_资料库/ 根目录。
3. 先导入一篇 sensitivity: public 的 Markdown，再观察 ima 是否保留标题、正文、相对层级和可检索文本。
4. 确认监控范围、目标知识库和同步方向后，才扩大到完整 allowlist；扩大时重新预检。
5. 若官方 Skills 在当前客户端不可用，记录版本和缺失能力并停止自动同步；不要擅自改用第三方 watcher 或自建反向同步。

4. 验证检索

选择一篇本地 vault 文章，记录其标题和一个不敏感的独特短语。等待首次导入/索引完成后，在 ima 目标知识库中检索标题或短语，核对命中内容与本地 Markdown 一致。若未命中，按“监控范围 → 目标知识库 → 索引等待 → 文件格式/权限”的顺序排查，并把未实测的 UI 差异写入回执。

5. 边界与冲突处理

• 本地 Markdown vault 是唯一真身；ima 只是云端消费端。
• 只允许 vault → ima 的同步约定；本 skill 不做 ima → vault 反向同步。
• ima 中的摘要、标签、重排或 AI 生成内容不能自动覆盖本地正文。
• 变更同步范围前先暂停监控并复核排除清单，尤其是 .env、私密目录、会话日志和未发布草稿。
• 目录监控开启后，新增笔记也会进入云端范围；该目录的最近 AGENTS.md 必须明确只允许 public/internal，否则不启用持续监控。

完成后回执

执行完输出：

1. 客户端登录和目标知识库状态。
2. 本地相对目录到 ima 知识库的映射及排除项。
3. 官方 Skills 监控配置是否完成；未实测 UI 步骤逐项标注。
4. 一篇文章在 ima 中的检索验证结果。
5. 残余风险：索引延迟、权限、版本差异和未执行的反向同步；没有则写“无”。