核心用法
IMA Note 是腾讯 IMA 知识库服务的官方 OpenAPI 技能，提供完整的个人笔记管理能力，涵盖读取（搜索、列表、获取内容）和写入（新建、追加）两大场景。
核心能力：
- 智能检索：支持标题检索（
search_type: 0）和全文检索（search_type: 1），可按更新时间、创建时间、标题等排序 - 笔记本管理：浏览笔记本列表（
list_note_folder_by_cursor），区分用户自建、全部笔记、未分类三种类型 - 笔记读写：新建笔记（
import_doc）支持指定笔记本，追加内容（append_doc）实现增量更新 - 隐私保护：群聊场景仅展示标题和摘要，正文内容严格保密
典型工作流：
1. 查找并阅读：先 search_note_book 获取 docid，再用 get_doc_content 读取纯文本正文
2. 浏览笔记本：先拉 list_note_folder_by_cursor 获取 folder_id，再拉 list_note_by_folder_id 查看笔记列表
3. 新建笔记：调用 import_doc 传入 Markdown 格式内容，返回 doc_id 供后续追加使用
技术细节：
- 统一采用 HTTP POST + JSON Body，Base URL 为
https://ima.qq.com/openapi/note/v1 - 认证方式为 Header 传递
ima-openapi-clientid和ima-openapi-apikey - 内容格式：
content_format: 1（Markdown）用于写入，target_content_format: 0（纯文本）用于读取 - 分页机制：笔记本和笔记列表采用游标分页，搜索采用偏移量分页
- 编码要求：所有内容必须 UTF-8 编码，提供 Python/Node.js/Unix/PowerShell 多平台转码方案
显著优点
1. 官方权威：腾讯 IMA 官方 OpenAPI，数据安全性和服务稳定性有保障
2. 功能完整：覆盖笔记全生命周期，从创建、搜索、阅读到更新一站式解决
3. 隐私合规：内置群聊隐私规则，自动隐藏笔记正文，降低敏感信息泄露风险
4. 格式友好：原生支持 Markdown 写入，符合开发者和技术用户习惯
5. 错误码详尽：15+ 个细分错误码，覆盖鉴权、限频、容量、版本冲突等场景，便于精准排查
潜在缺点与局限性
1. 格式限制：读取时 Markdown 格式不支持（target_content_format: 0），仅能获取纯文本，格式信息丢失
2. 容量上限：单篇笔记有大小限制（错误码 100009），超大内容需手动拆分多次追加
3. 凭证依赖：必须配置 IMA_OPENAPI_CLIENTID 和 IMA_OPENAPI_APIKEY，且存在过期风险（错误码 110037）
4. 限频约束：apiKey 有最大限频（错误码 20002），高频场景需做速率控制
5. 平台差异：Windows PowerShell 5.1 存在 UTF-8 编码陷阱，需额外处理字节数组转换
适合人群
- 知识管理用户：需要结构化存储和检索个人笔记、备忘录、会议纪要
- 效率工具爱好者：希望通过 API 自动化笔记工作流，如定时备份、内容聚合
- 团队协作场景：在受控环境下分享笔记标题和摘要，保护核心内容隐私
- 开发者/技术用户：熟悉 curl、JSON、环境变量配置，能处理编码转换和错误码
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| **凭证泄露** | Client ID 和 API Key 泄露可能导致笔记数据被非法访问 | 避免硬编码，使用环境变量；定期轮换 API Key |
| **编码错误** | 非 UTF-8 内容传入 API 导致乱码或失败 | 严格按文档执行编码预检，使用推荐的 Python/Node.js 转码方案 |
| **数据覆盖** | `append_doc` 误操作可能污染已有笔记 | 追加前确认 `doc_id`，关键笔记先备份 |
| **限频中断** | 高频调用触发 `20002` 错误 | 实施指数退避重试，或联系 IMA 提升额度 |
| **隐私误曝** | 开发时未遵守"群聊只展示标题摘要"规则 | 代码审查时重点检查内容展示逻辑，默认隐藏正文 |