# IMA 知识库与笔记 SOP

## 适用场景
用户需要操作 IMA 知识库/笔记（搜索笔记、创建笔记、上传文件到知识库、搜索知识库等）

## 前置条件
- Node.js >= 18 (已装 v24.15.0)
- 凭证: ~/.config/ima/client_id 和 ~/.config/ima/api_key (已配)
- 技能包: ../memory/ima-skill/
- API入口: ../memory/ima-skill/ima_api.cjs

## API调用
```python
import subprocess, json
from pathlib import Path
SKILL = Path(os.getcwd()) / 'memory' / 'ima-skill'
def call_ima(api_path, params=None):
    opts = {"clientId": Path.home()/'.config'/'ima'/'client_id'|read, "apiKey": Path.home()/'.config'/'ima'/'api_key'|read}
    r = subprocess.run(['node', str(SKILL/'ima_api.cjs'), api_path, json.dumps(params or {}), json.dumps(opts)],
                       capture_output=True, text=True, timeout=30, cwd=str(SKILL))
    if r.returncode != 0: raise RuntimeError(json.loads(r.stderr)['msg'])
    return json.loads(r.stdout)
```

## 笔记操作
| 功能 | api_path | 关键参数 |
|------|----------|----------|
| 搜索笔记 | notes/search_docs | keyword, limit |
| 浏览笔记本 | notes/list_notebooks | (无) |
| 获取笔记 | notes/get_doc_content | doc_id |
| 创建笔记 | notes/import_doc | content, title, notebook_id |
| 追加内容 | notes/append_doc | doc_id, content |

## 知识库操作
API base path: `openapi/wiki/v1`（传入 ima_api.cjs 时拼接完整路径）

| 功能 | api_path | 关键参数 |
|------|----------|----------|
| 查看所有知识库（我的列表） | openapi/wiki/v1/search_knowledge_base | query: ""（空字符串返回全部）, cursor, limit(1~20) |
| 按名称搜索知识库 | openapi/wiki/v1/search_knowledge_base | query, cursor, limit(1~20) |
| 浏览知识库内容列表 | openapi/wiki/v1/get_knowledge_list | knowledge_base_id, cursor, limit(1~50), 可选folder_id |
| 获取知识库信息 | openapi/wiki/v1/get_knowledge_base | ids(1-20个) |
| 搜索知识库内文件 | openapi/wiki/v1/search_knowledge | query, knowledge_base_id, cursor |
| 上传文件 | openapi/wiki/v1/check_repeated_names → create_media → COS上传 → add_knowledge | 三步流程，详见ima-skill/knowledge-base/SKILL.md |
| 添加网页/微信文章 | openapi/wiki/v1/import_urls | urls(1-10个), knowledge_base_id, 可选folder_id |
| 添加笔记到知识库 | openapi/wiki/v1/add_knowledge | media_type=11, note_info.content_id=<note_id> |
| 获取可添加的知识库列表 | openapi/wiki/v1/get_addable_knowledge_base_list | cursor, limit(1~50) |

## 注意
- 全部UTF-8编码
- 文件上传title必须等于原始文件名(含后缀)
- 不支持视频/B站/YouTube/file://链接