IMA 笔记与知识库助手

解决了什么问题

在 Agent 工作流中，笔记与知识库通常被割裂：笔记散落在个人工具里，知识库沉淀在团队系统中，Agent 很难在一次对话里同时完成「记下来」和「归档到知识库」。这个技能把 IMA 的笔记（notes）与知识库（knowledge-base）两套接口统一到同一个 Agent Skill 下，让模型可以按用户意图自动选择模块，完成搜索、读取、创建、追加、上传、关联等操作，而不是让用户在多个工具之间来回切换。

核心能力与工作流程

技能内部按用户意图做路由，核心判断规则是：操作对象是笔记的内容，还是知识库的条目。

• 目标是笔记内容（读、写、追加）：走 notes 模块，调用 import_doc 创建、append_doc 追加、搜索笔记获取 note_id
• 目标是知识库条目（上传文件、添加网页链接、把笔记关联到知识库）：走 knowledge-base 模块，走 create_media → COS → add_knowledge 流程
• 目标是获取知识库条目的原始内容（查看原文、分析、导出）：走 knowledge-base 模块，若原文是笔记类型，会自动跨到 notes 的 get_doc_content

对于容易混淆的场景，技能内置了决策表。例如「把这段内容添加到知识库 XX 里的笔记 YY」实际是往已有笔记追加，应走 notes 的 append_doc；而「把这篇笔记添加到知识库」才是把笔记关联到知识库，走 knowledge-base 的 add_knowledge，并使用 media_type=11。

跨模块任务是另一个关键设计。如果用户意图同时涉及笔记和知识库，技能要求先读取两个子模块的 SKILL.md 再按顺序执行，而不是只读一个就开始。例如「把知识库里的 XX 内容记到笔记」需要先 knowledge-base 搜索/读取，再 notes 创建/追加。

关键实现细节

凭证与调用。 所有 API 调用统一为 HTTP POST + JSON Body，仅发往 https://ima.qq.com。凭证从环境变量或 ~/.config/ima/client_id 与 ~/.config/ima/api_key 读取，仅作为 HTTP Header 发送，不写入日志或文件。

错误处理分两层。 第一层是脚本执行错误，进程非 0 退出，错误在 stderr：-100 表示程序错误（缺凭证、参数非法、网络错误等），-200 表示 skill 需要更新，原请求未发送；第二层是后端业务错误，进程正常退出，stdout 返回 JSON，code=0 成功，code≠0 直接展示 msg。

UTF-8 编码校验。 对 notes 模块的写入类 API（import_doc、append_doc），在构造请求前必须校验所有字符串字段为合法 UTF-8。无论内容来自用户输入、文件读取、WebFetch 抓取还是外部 API，都不能假设已是合法 UTF-8。文件内容作为笔记正文写入时要先转码，但上传文件到知识库时必须保持原始二进制不变。

PowerShell 5.1 兼容。 在 PowerShell 5.1 下，Invoke-RestMethod 会静默将请求 Body 从 UTF-8 转为系统 ANSI（中文 Windows 为 GBK），即使设置 charset=utf-8 也无效。技能要求在首次调用前检测版本，并在 5.1 环境下显式将 Body 转为 UTF-8 字节数组发送。

文件上传规则。 上传文件时 title 必须等于 file_name（含扩展名），不得重命名、缩短或翻译。不支持的视频文件、Bilibili/YouTube URL 和 file:// URL 直接拒绝，并引导用户使用 IMA 桌面客户端。

适用边界

这个技能适合在 Agent 工作流中统一管理 IMA 笔记与知识库，但不适合直接替代桌面客户端的全部功能。视频类媒体、外部平台链接不在支持范围内；跨模块任务需要按顺序读取两个子模块，不能跳步；在 PowerShell 5.1 环境中必须走 UTF-8 字节数组模式，否则中文内容会静默乱码。

使用时建议先通过 Credential Check 确认凭证已配置，再按模块决策表判断用户意图，最后按对应子模块的详细规则执行。