refactor: simplify reader digest skill
This commit is contained in:
zhuyongxin
@@ -1,80 +1,91 @@
|
||||
# IMA Upload API Reference
|
||||
# IMA Markdown 上传 API
|
||||
|
||||
Full API flow for uploading markdown articles to the IMA `daily` knowledge base. Used in Phase 7 of the reader-digest-flow.
|
||||
用于将用户选中的单篇 Markdown 知识笔记上传到 `daily` knowledge base。
|
||||
|
||||
## 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
|
||||
- `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
|
||||
```
|
||||
|
||||
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`.
|
||||
## 2. Create Media
|
||||
|
||||
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 } } }
|
||||
```text
|
||||
POST /openapi/wiki/v1/create_media
|
||||
```
|
||||
|
||||
`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>
|
||||
```json
|
||||
{
|
||||
"file_name": "<完整文章标题>.md",
|
||||
"file_size": 0,
|
||||
"content_type": "text/markdown",
|
||||
"knowledge_base_id": "<daily-kb-id>",
|
||||
"file_ext": "md"
|
||||
}
|
||||
```
|
||||
|
||||
⚠️ Must use Python `subprocess.run(args=[...])` to avoid shell parameter mangling.
|
||||
⚠️ Always capture `returncode` and `stderr` — COS may return exit 0 on HTTP 500.
|
||||
保存返回的 `media_id` 和 `cos_credential`。COS 临时凭证只在进程内传递，不打印到聊天或日志。
|
||||
|
||||
### 3. add_knowledge
|
||||
## 3. COS Upload
|
||||
|
||||
```
|
||||
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 } }
|
||||
使用 IMA Skill 提供的 `cos-upload.cjs`，通过参数数组调用并检查：
|
||||
|
||||
- 进程 `returncode`；
|
||||
- `stderr`；
|
||||
- HTTP 上传结果。
|
||||
|
||||
不要拼接包含凭证的 Shell 字符串，也不要把多条 JSON 响应重定向到同一个文件。
|
||||
|
||||
## 4. Add Knowledge
|
||||
|
||||
```text
|
||||
POST /openapi/wiki/v1/add_knowledge
|
||||
```
|
||||
|
||||
`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>
|
||||
|
||||
## 核心结论
|
||||
...
|
||||
|
||||
## 主要论点
|
||||
...
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
## 5. 验证
|
||||
|
||||
上传成功不能只依据本地命令退出码。验证目标 knowledge base 中存在对应标题或返回对象，并向用户报告最终结果。
|
||||
|
||||
失败时明确报告发生在 Preflight、Create Media、COS Upload 或 Add Knowledge 的哪一步，不改用 URL 导入或 Notes 类型绕过错误。
|
||||
|
||||
Reference in New Issue
Block a user