root
5eb390e3ed
- 复制 reader-digest-flow skill 到 skills/ 目录（含 SKILL.md + references/） - README 新增 Agent Skill 章节说明供 Agent 使用的工作流
81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
# IMA Upload API Reference
|
|
|
|
Full API flow for uploading markdown articles to the IMA `daily` knowledge base. Used in Phase 7 of the reader-digest-flow.
|
|
|
|
## Credentials
|
|
|
|
```
|
|
IMA_OPENAPI_CLIENTID - from reader .env or user-provided
|
|
IMA_OPENAPI_APIKEY - from reader .env or user-provided
|
|
IMA_DAILY_KNOWLEDGE_BASE_ID - daily KB UUID
|
|
```
|
|
|
|
The `ima-skill` v1.1.7+ ships with `ima_api.cjs` for credential loading.
|
|
Legacy auth header: `ima-openapi-ctx: skill_version=1.1.7`.
|
|
|
|
Do NOT export the full API key in shell commands — use `execute_code` with `subprocess.run` and Python string variables.
|
|
|
|
## Flow (3 steps)
|
|
|
|
### 1. create_media
|
|
|
|
```
|
|
POST https://ima.qq.com/openapi/wiki/v1/create_media
|
|
Headers: ima-openapi-clientid, ima-openapi-apikey, Content-Type: application/json
|
|
Body: { file_name, file_size, content_type, knowledge_base_id, file_ext }
|
|
Returns: { code: 0, data: { media_id, cos_credential: { secret_id, secret_key, token, bucket_name, region, cos_key, start_time, expired_time } } }
|
|
```
|
|
|
|
`file_ext` is without the dot (e.g. `md` not `.md`).
|
|
`file_name` must be the user-facing article title + `.md`.
|
|
`content_type` for markdown is `text/markdown`; media_type=7.
|
|
|
|
### 2. COS upload
|
|
|
|
Use `cos-upload.cjs` from `ima-skill/knowledge-base/scripts/`:
|
|
|
|
```
|
|
node <skill_dir>/knowledge-base/scripts/cos-upload.cjs \
|
|
--file <local_md_file> \
|
|
--secret-id <from create_media> \
|
|
--secret-key <from create_media> \
|
|
--token <from create_media> \
|
|
--bucket <bucket_name> \
|
|
--region <region> \
|
|
--cos-key <cos_key> \
|
|
--content-type text/markdown \
|
|
--start-time <start_time> \
|
|
--expired-time <expired_time>
|
|
```
|
|
|
|
⚠️ Must use Python `subprocess.run(args=[...])` to avoid shell parameter mangling.
|
|
⚠️ Always capture `returncode` and `stderr` — COS may return exit 0 on HTTP 500.
|
|
|
|
### 3. add_knowledge
|
|
|
|
```
|
|
POST https://ima.qq.com/openapi/wiki/v1/add_knowledge
|
|
Headers: same as create_media
|
|
Body: { media_type: 7, media_id, title: "<file_name>", knowledge_base_id, file_info: { cos_key, file_size, file_name } }
|
|
```
|
|
|
|
`media_type=7` for markdown. `title` MUST equal `file_name`.
|
|
|
|
## Article Markdown reformatting (before upload)
|
|
|
|
Generated summaries from `reader` have `Source:` and `Category:` header lines.
|
|
Before uploading, reformat to IMA style:
|
|
|
|
```
|
|
原文链接：<original article URL>
|
|
|
|
## 核心结论
|
|
...
|
|
|
|
## 主要论点
|
|
...
|
|
```
|
|
|
|
Remove `Source:`, `Category:` lines. Keep `原文链接:` at top with the URL on the next line.
|
|
Break long prose (>200 chars per paragraph) into shorter paragraphs for IMA readability.
|