腾讯ima官方API skill，用于管理个人笔记知识库，支持搜索、阅读、新建、追加笔记等完整笔记管理能力，需配置ClientID和ApiKey使用。
说明：
## ima-note 技能评估报告
### 核心用法
ima-note 是腾讯 IMA（Intelligent Management Assistant）官方推出的个人笔记服务 API skill，提供完整的笔记生命周期管理能力。该技能基于 RESTful API 设计，支持六大核心操作：搜索笔记（`search_note_book`）、浏览笔记本列表（`list_note_folder_by_cursor`）、获取笔记本内笔记（`list_note_by_folder_id`）、读取笔记正文（`get_doc_content`）、新建笔记（`import_doc`）和追加内容（`append_doc`）。所有接口统一采用 HTTP POST + JSON Body 格式，Base URL 为 `https://ima.qq.com/openapi/note/v1`，需通过 `ima-openapi-clientid` 和 `ima-openapi-apikey` 双 Header 鉴权。
**关键技术细节**：搜索支持标题检索（`search_type=0`）和正文检索（`search_type=1`），分页机制分为游标分页（笔记本/笔记列表）和偏移量分页（搜索）；写入操作强制使用 Markdown 格式（`content_format=1`），读取推荐纯文本（`0`）。数据返回为多层嵌套结构，需按 `docs[].doc.basic_info` 等路径解析。
### 显著优点
– **官方背书**：腾讯 ima 团队直接维护，API 稳定性与持续更新有保障
– **功能完备**：覆盖笔记 CRUD 全场景，支持笔记本层级管理
– **隐私设计内置**：文档明确约定群聊场景仅展示标题摘要，禁止暴露正文
– **多平台编码适配**：提供 Python/Node.js/Unix/Windows PowerShell 全套 UTF-8 编码转换方案
– **详尽错误码**：定义 12 类错误码及对应处理建议，降低调试成本
### 潜在缺点与局限性
– **凭证门槛**：必须前往 `https://ima.qq.com/agent-interface` 手动申请 Client ID 和 Api Key，流程不够自动化
– **格式限制**：写入仅支持 Markdown，读取不支持 Markdown 格式返回（`get_doc_content` 的 `target_content_format` 不支持 `1`）
– **大小限制**：单笔记存在内容上限（错误码 100009），大内容需手动拆分多次 `append_doc`
– **编码风险**：中文环境下若未正确处理 UTF-8，易导致乱码或 API 报错（尤其对 Windows PowerShell 5.1 需特殊处理）
– **限频约束**：`apiKey` 存在最大限频（错误码 20002），高并发场景需注意
### 适合人群
– 已使用腾讯 ima 作为主力笔记工具，希望通过自动化脚本/Agent 扩展工作流的知识工作者
– 需要将外部信息（网页、文档、对话记录）自动归档至个人知识库的开发者
– 企业团队基于 ima 构建内部知识管理系统的集成工程师
### 常规风险
– **凭证泄露风险**：Client ID 和 Api Key 为长期有效凭证，若硬编码在公共仓库或日志中泄露，可能导致笔记数据被非法访问
– **数据覆盖风险**：`append_doc` 无版本确认机制，并发写入可能导致内容覆盖（错误码 100008 版本冲突需手动处理）
– **权限边界风险**：错误码 100005 提示”无权限”，暗示可能存在共享笔记本场景，误操作他人笔记会导致权限错误
– **API 变更风险**：作为 OpenAPI v1 版本，未来接口字段或鉴权方式可能存在非兼容升级
