skill一键同步（workbuddy to ima） · IMA skill 同步器
把 WorkBuddy 本地 skill 目录,一键同步到 IMA 知识库。支持两态:
- 改后同步:IMA 已有同名文件夹 →
REPLACE精准覆盖同名文件,新文件ADD。 - 首次安装:IMA 无同名文件夹 → 推到知识库根目录(无 folder_id),真一键、零手动。
前置条件(硬要求)
- ima-mcp 连接器已连接(connected)。本 skill 依赖
mcp__ima-mcp__*工具。
- 用完按"按需连接"原则断开,避免 idle 长期授权。 - 已知目标知识库 id。默认 知新阁 =
7485675066647145(用户级,可改)。 - 本地 Python 隔离 venv 已装
cos-python-sdk-v5(不污染用户环境):
venv 路径为~/.workbuddy/binaries/python/envs/default(Windows:%USERPROFILE%\.workbuddy\binaries\python\envs\default\Scripts\python.exe)。
若未安装:用该 venv 的 python 执行python.exe -m pip install cos-python-sdk-v5。
核心约束(已查 ima-mcp schema 确认)
- IMA 没有"创建文件夹"的 API。
add_knowledge只接受已存在的folder_id;
create_media仅给文件用;无 create-folder 入口。因此: - 改后同步(文件夹已存在)= 真·一键
REPLACE✅ - 首次安装(无文件夹)= 只能落到知识库根目录,无法自动建文件夹 ⚠️
(这正是"推到根目录(真一键)"设计:牺牲归类换零手动;之后可在 IMA 手动拖进文件夹)
主流程
Step 0 · 收参数
local_skill_path:本地 skill 目录(默认 = 当前对话涉及的 skill;否则问用户)knowledge_base_id:默认7485675066647145(知新阁)folder_name:默认 =local_skill_path的目录名(如双通道职级名称)push_to_root_if_missing:默认true(首次安装落根目录)
Step 1 · 扫描本地
收集 local_skill_path 下所有 .md / .markdown(含 references/ 子目录),排除隐藏文件。
记录每个文件的:local_path、file_name(含相对路径,如 SKILL.md、references/双通道职级命名框架.md)、size(字节,stat -c%s)。
> 同步以本地文件名为 IMA 侧文件名(沿用本地名)。若某 skill 历史在 IMA 侧被手动改名,
> REPLACE 会因名不符而新建重复条目——见末尾"防错"。
Step 2 · 查 IMA 现状
get_knowledge_list(knowledge_base_id=..., limit=50)列根目录,找media_type=FOLDER且
title == folder_name的文件夹 → 得到folder_id(若有)。- 若命中文件夹:再
get_knowledge_list(knowledge_base_id=..., folder_id=..., limit=50)列出其内文件,
建ima_file_by_name(IMA 文件名 → media 信息)映射。
Step 3 · 分支
分支 A:命中文件夹(改后同步)
对每个本地文件:
- IMA 同名文件存在 → add_knowledge(..., folder_id, media_id, duplicate_name_strategy=REPLACE)
- IMA 无同名 → add_knowledge(..., folder_id, media_id)(默认 SAVE,即新增)
分支 B:未命中文件夹(首次安装)
对每个本地文件:add_knowledge(..., media_id) 不带 folder_id → 落知识库根目录。
> 输出醒目提示:「⚠️ 首次安装:已推到知识库根目录(IMA 无建文件夹 API)。如需归类,
> 可在 IMA 手动建文件夹『{folder_name}』并把文件移入;后续改后同步仍走 REPLACE。」
Step 4 · 上传字节(两分支共用)
对每个本地文件,按顺序:
1. create_media(content_type="text/markdown", file_name=本地文件名, file_size=字节数, knowledge_base_id=...)
→ 取返回:media_id、bucket、region、cos_key、临时 secretId/secretKey/token。
2. 把该文件信息追加进 manifest.json(供 upload_cos.py)。
3. 所有文件凭证拿齐后,一次性跑
references/upload_cos.py manifest.json
(用隔离 venv 的 python:Windows 为 %USERPROFILE%\.workbuddy\binaries\python\envs\default\Scripts\python.exe,
macOS/Linux 为 ~/.workbuddy/binaries/python/envs/default/bin/python)。
4. 上传成功(返回 ETag)后,执行 Step 3 的 add_knowledge。
> content_type 映射:.md/.markdown → text/markdown(其余扩展名见 ima 对照表,本 skill 只处理 md)。
Step 5 · 校验
- 分支 A:重列文件夹,比对
文件数+ 每个文件size与本地逐字节一致;确认无新增副本(文件名不变)。 - 分支 B:重列根目录,确认新增文件数 = 本地文件数、size 一致。
- 输出每文件结果表:
本地文件 | IMA 文件名 | 动作(REPLACE/ADD/ROOT-ADD) | 字节数 | 状态。
防错 / 注意事项
- 历史改名导致重复:若某 skill 之前手动在 IMA 改名(如
SKILL.md→双通道职级名称-SKILL.md),
本 skill 按本地名SKILL.md推送会新建重复条目。处理:先让用户手动删 IMA 旧条目,或用
ima_file_by_name做名称映射(在 Step 3 用旧 IMA 名匹配 REPLACE)。首次跑前主动提示用户核对。 - size 必须一致:
create_media.file_size与实际上传字节必须相等,否则服务端拒收。以stat -c%s为准。 - 连接器用后断开:ima-mcp 完成即断,遵循最小授权。
- 不碰无关库:只操作指定
knowledge_base_id,绝不遍历/修改其他知识库。 - 只处理 md:references 下非 md(如图片)不推;如需扩展再议。
触发即读(强制)
本 skill 触发时,先向用户声明:「IMA 无建文件夹 API;改后同步一键覆盖,首次安装落根目录。」
再按 Step 0 收参执行。
