127 lines
4.7 KiB
Markdown
127 lines
4.7 KiB
Markdown
# 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。
|
||
|
||
预期：
|
||
|
||
```text
|
||
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），所以光替换文件无法跳过拦截。
|
||
|
||
快速修复（脚本本身已是新版，只差版本号）：
|
||
|
||
```bash
|
||
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
|
||
|
||
```text
|
||
POST /openapi/wiki/v1/create_media
|
||
```
|
||
|
||
请求核心字段：
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```text
|
||
POST /openapi/wiki/v1/add_knowledge
|
||
```
|
||
|
||
核心字段：
|
||
|
||
```json
|
||
{
|
||
"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 调用，原请求不发送。此前遇到过。
|
||
|
||
处理方式（不必整包替换）：
|
||
|
||
1. 按 stderr 提示下载新版 zip（如 `https://app-dl.ima.qq.com/skills/ima-skills-1.1.8.zip`）并解压；
|
||
2. 对比新旧 `ima_api.cjs` 的 md5——zip 内核心脚本常与本地一致，只是 `meta.json` 的 `version` 未同步（zip 内仍写 1.1.7）；
|
||
3. 若 `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`。
|