note-test1-limingzhi

ima-note

通过 IMA OpenAPI 管理用户个人笔记，支持读取（搜索、列表、获取内容）和写入（新建、追加）。

完整的数据结构和接口参数详见 references/API.md。

设置up 请打开 https://ima.qq.com/代理-interface 获取 命令行工具ent ID 和 应用 Key 存储凭证： mkdir -p ~/.config/ima echo "your_命令行工具ent_id" > ~/.config/ima/命令行工具ent_id echo "your_API_key" > ~/.config/ima/API_key

也可以通过环境变量配置（代理 会按优先级依次尝试：环境变量 → 配置文件）：

导出 IMA_OPENAPI_命令行工具ENTID="your_命令行工具ent_id" 导出 IMA_OPENAPI_APIKEY="your_API_key"

凭证预检

每次调用 API 前，先确认凭证可用。如果两个值都为空，停止操作并提示用户按 设置up 步骤配置。

IMA_命令行工具ENT_ID="${IMA_OPENAPI_命令行工具ENTID:-$(cat ~/.config/ima/命令行工具ent_id 2>/dev/null)}" IMA_API_KEY="${IMA_OPENAPI_APIKEY:-$(cat ~/.config/ima/API_key 2>/dev/null)}" if [ -z "$IMA_命令行工具ENT_ID" ] || [ -z "$IMA_API_KEY" ]; then echo "缺少 IMA 凭证，请按 设置up 步骤配置 命令行工具ent ID 和 应用 Key" exit 1 fi

API 调用模板

所有请求统一为 HTTP POST + JSON Body，Base URL 为 https://ima.qq.com/openAPI/note/v1。

定义辅助函数避免重复 header：

ima_API() { local 端点="$1" body="$2" curl -s -X POST "https://ima.qq.com/openAPI/note/v1/$端点" \ -H "ima-openAPI-命令行工具entid: $IMA_命令行工具ENT_ID" \ -H "ima-openAPI-APIkey: $IMA_API_KEY" \ -H "Content-Type: 应用/json" \ -d "$body" }

隐私规则： 笔记内容属于用户隐私，在群聊场景中只展示标题和摘要，禁止展示笔记正文。

接口决策表 用户意图 调用接口 关键参数 搜索/查找笔记 搜索_note_book 查询_信息（查询信息 对象）+ 启动(必填) + end(必填) 查看笔记本列表 列出_note_folder_by_cursor cursor(必填，首页传"0") + limit(必填) 浏览某笔记本里的笔记 列出_note_by_folder_id folder_id(必填) + cursor(必填，首次传"") + limit(必填) 读取笔记正文 获取_doc_content doc_id + tar获取_content_格式化(必填，推荐0纯文本) 新建一篇笔记 导入_doc content + content_格式化(必填，固定1) + 可选 folder_id 往已有笔记追加内容 应用end_doc doc_id + content + content_格式化(必填，固定1) 常用工作流 查找并阅读笔记

先搜索获取 docid，再用 获取_doc_content 读取正文：

# 1. 按标题搜索 ima_API "搜索_note_book" '{"搜索_type": 0, "查询_信息": {"title": "会议纪要"}, "启动": 0, "end": 20}' # 从返回的 docs[].doc.basic_信息.basic_信息.docid 中取目标笔记 ID

# 2. 读取正文（纯文本格式，Markdown 格式目前不支持） ima_API "获取_doc_content" '{"doc_id": "目标docid", "tar获取_content_格式化": 0}'

浏览笔记本里的笔记

先拉笔记本列表获取 folder_id，再拉该笔记本下的笔记：

# 1. 列出笔记本（首页 cursor 传 "0"） ima_API "列出_note_folder_by_cursor" '{"cursor": "0", "limit": 20}'

# 2. 拉取指定笔记本的笔记（首页 cursor 传 ""） ima_API "列出_note_by_folder_id" '{"folder_id": "user_列出_xxx", "cursor": "", "limit": 20}'

新建笔记 # 新建到默认位置 ima_API "导入_doc" '{"content_格式化": 1, "content": "# 标题\n\n正文内容"}'

# 新建到指定笔记本 ima_API "导入_doc" '{"content_格式化": 1, "content": "# 标题\n\n正文内容", "folder_id": "笔记本ID"}' # 返回 doc_id 和 doc_信息，后续可用于 应用end_doc

追加内容到已有笔记 ima_API "应用end_doc" '{"doc_id": "笔记ID", "content_格式化": 1, "content": "\n## 补充内容\n\n追加的文本"}'

按正文搜索 ima_API "搜索_note_book" '{"搜索_type": 1, "查询_信息": {"content": "项目排期"}, "启动": 0, "end": 20}'

核心响应字段

搜索结果（搜索edDoc）：笔记信息在 doc.basic_信息.basic_信息 下，关键字段：docid、title、summary、tags、folder_name、创建_time（Unix 毫秒）、modify_time。额外包含 highlight_信息（高亮匹配）和 分享_flag。

笔记本条目（NoteBookFolder）：信息在 folder.basic_信息.basic_信息 下，关键字段：folder_id、name、note_number、folder_type（0=用户自建，1=全部笔记根目录，2=未分类）。

笔记列表条目（NoteBook信息）：信息在 basic_信息.basic_信息 下，额外包含 knowledge_exist_信息（知识库状态）和 security_状态（安审状态）。

写入结果（导入_doc/应用end_doc）：返回 doc_id 和完整的 doc_信息（Doc信息 对象）。

完整字段定义见 references/API.md。

分页 游标分页 — 笔记本列表（列出_note_folder_by_cursor）：首次 cursor: "0"，后续用 next_cursor，is_end=true 时停止。支持 version/next_version 增量同步，need_更新 判断是否有变化。 游标分页 — 笔记列表（列出_note_by_folder_id）：首次 cursor: ""，后续用 next_cursor，is_end=true 时停止。同样支持 version 增量同步。 偏移量分页（搜索_note_book）：首次 启动: 0, end: 20，翻页时递增，查询_id 原样透传，is_end=true 时停止。 枚举值 content_格式化： 0=纯文本，1=Markdown，2=JSON。写入（导入_doc/应用end_doc）目前仅支持 1（Markdown）。读取（获取_doc_content）推荐 0（纯文本），Markdown 格式不支持。 搜索_type： 0=标题检索（默认），1=正文检索 排序_type： 0=更新时间（默认），1=创建时间，2=标题，3=大小（仅 搜索_note_book 使用） folder_type： 0=用户自建，1=全部笔记（根目录），2=未分类 注意事项 folder_id 不可为 "0"，根目录 ID 格式为 user_列出_{userid}（从 folder_type=1 的笔记本条目获取） 笔记内容有大小上限，超过时返回 100009，可拆分为多次 应用end_doc 写入 展示笔记列表时只展示标题、摘要和修改时间，不要主动展示正文 时间字段是 Unix 毫秒时间戳，展示时转为可读格式 新协议返回的数据是嵌套结构（如 doc.basic_信息.basic_信息.docid），注意按层级解析 错误处理 错误码 含义 建议处理 0 成功 — 100001 参数错误 检查请求参数格式和必填字段 100002 无效 QBID 检查凭证配置 100003 服务器内部错误 等待后重试 100004 size 不合法 / 空间不够 检查参数范围 100005 无权限 确认操作的是用户自己的笔记 100006 笔记已删除 告知用户该笔记不存在 100008 版本冲突 重新获取内容后再操作 100009 超过大小限制 拆分为多次 应用end_doc 写入 310001 笔记本不存在 检查 folder_id 是否正确 20004 应用key 鉴权失败 检查凭证配置是否正确