IMA Markdown 上传 API

用于将用户选中的单篇 Markdown 知识笔记上传到 daily knowledge base。

凭证

IMA_OPENAPI_CLIENTID
IMA_OPENAPI_APIKEY
IMA_DAILY_KNOWLEDGE_BASE_ID
IMA_DAILY_KNOWLEDGE_BASE_NAME

凭证定位和恢复见 ima-credential-chain.md。不要在终端输出完整密钥。

上传前检查

文件名为 <完整文章标题>.md；
title 为完整文章标题，不带 .md；
Markdown 符合 ima-format-quickref.md；
内容可追溯到当前 Run Artifact；
用户已经明确选择该文章；
目标知识库已经解析并验证。

1. Preflight

调用 IMA Skill 的 preflight-check.cjs 检查文件类型、扩展名、大小和 MIME。

预期：

file_ext=md
content_type=text/markdown
media_type=7

⚠️ IMA skill 版本拦截（-200）

ima_api.cjs 每天首次调用会检查更新，若检测到新版（如 1.1.8 > 当前 1.1.7）会以 code=-200 拦截原请求。注意：官方 zip 包内的 meta.json 可能没同步版本号（下载 1.1.8 zip 后 meta 仍写 1.1.7），所以光替换文件无法跳过拦截。

快速修复（脚本本身已是新版，只差版本号）：

cd /root/.hermes/skills/openclaw-imports/ima-skill && python3 -c "
import json
m = json.load(open('meta.json')); m['version'] = '1.1.8'
json.dump(m, open('meta.json','w'), ensure_ascii=False, indent=2)
"

先用 diff -rq 对比 zip 与安装目录：若只有 .DS_Store/meta 差异，说明代码已是最新，直接改 meta.json 版本号即可；若脚本有实质差异才需要整体替换。

2. Create Media

POST /openapi/wiki/v1/create_media

请求核心字段：

{
  "file_name": "<完整文章标题>.md",
  "file_size": 0,
  "content_type": "text/markdown",
  "knowledge_base_id": "<daily-kb-id>",
  "file_ext": "md"
}

保存返回的 media_id 和 cos_credential。COS 临时凭证只在进程内传递，不打印到聊天或日志。

3. COS Upload

使用 IMA Skill 提供的 cos-upload.cjs，通过参数数组调用并检查：

进程 returncode；
stderr；
HTTP 上传结果。

不要拼接包含凭证的 Shell 字符串，也不要把多条 JSON 响应重定向到同一个文件。

4. Add Knowledge

POST /openapi/wiki/v1/add_knowledge

核心字段：

{
  "media_type": 7,
  "media_id": "<media-id>",
  "title": "<完整文章标题>",
  "knowledge_base_id": "<daily-kb-id>",
  "file_info": {
    "cos_key": "<cos-key>",
    "file_size": 0,
    "file_name": "<完整文章标题>.md"
  }
}

5. 验证

上传成功不能只依据本地命令退出码。验证目标 knowledge base 中存在对应标题或返回对象，并向用户报告最终结果。

失败时明确报告发生在 Preflight、Create Media、COS Upload 或 Add Knowledge 的哪一步，不改用 URL 导入或 Notes 类型绕过错误。

6. 已知坑：IMA skill 版本拦截（-200）

ima_api.cjs 每天首次调用会检查远端版本，若发现新版本（如 1.1.8 > 1.1.7）会以 exit=1 + stderr {"code":-200} 拦截所有 API 调用，原请求不发送。此前遇到过。

处理方式（不必整包替换）：

按 stderr 提示下载新版 zip（如 https://app-dl.ima.qq.com/skills/ima-skills-1.1.8.zip）并解压；
对比新旧 ima_api.cjs 的 md5——zip 内核心脚本常与本地一致，只是 meta.json 的 version 未同步（zip 内仍写 1.1.7）；
若 ima_api.cjs 一致，只需把本地 meta.json 的 version 改为远端版本号即可跳过拦截，无需替换文件。

调用成功后再执行本文件前面的上传流程。

6. 版本拦截与批量上传实测（2026-07-31）

-200 skill 更新拦截：ima_api.cjs 每天首次调用检查版本，发现新版时以 code -200 退出并提示更新。下载 zip 后先对比 ima_api.cjs 的 md5——实测 zip 内脚本与已装版本完全一致，只是 meta.json 版本号未同步。此时只需把 ~/.hermes/skills/openclaw-imports/ima-skill/meta.json 的 version 改为最新版即可跳过拦截，无需替换任何脚本。
Python 脚本编排上传比 bash 可靠：bash 拼接含中文文件名/凭证的 curl 易出错。用 subprocess 参数数组依次调 preflight-check.cjs → ima_api.cjs check_repeated_names → create_media → cos-upload.cjs（--secret-id/--secret-key/--token 走参数数组，不打印）→ add_knowledge，每步解析返回 JSON，失败即停。
批量上传：4 篇逐个跑同一脚本即可；同名文件先 check_repeated_names 确认无重复。
凭证从 IMA_OPENAPI_CLIENTID / IMA_OPENAPI_APIKEY 环境变量读取（ima_api.cjs 自动加载），KB ID 用 IMA_DAILY_KNOWLEDGE_BASE_ID。

4.7 KiB Raw Permalink Blame History Unescape Escape