GeeLee

要解决的工程问题

Agent 直接调用 IMA OpenAPI 时面临几个棘手问题。首先是编码处理：笔记写入时若混入非 UTF-8 字符，会导致不可逆的乱码；而 PowerShell 5.1 更会静默将请求体从 UTF-8 转为系统 ANSI 编码，即使设置了正确的 Content-Type 也无法避免。其次是意图路由：用户说「把知识库里的笔记记下来」时，Agent 需要判断这是读取知识库条目还是操作笔记内容，两者调用完全不同的 API。第三是跨模块任务：当操作同时涉及笔记与知识库时（如将 KB 原文写入笔记），只读取单个子模块的文档会导致流程中断。

核心机制与实现

GeeLee 通过三个层面解决上述问题。意图路由层：内置模块决策表，将用户请求映射到 notes 或 knowledge-base 模块，并针对易混淆场景（如「添加到笔记」未指定具体笔记）强制要求确认。跨模块协调层：定义了清晰的读取顺序——先读 knowledge-base/SKILL.md 再读 notes/SKILL.md，确保在 KB 搜索后能正确调用 Notes API 创建或追加内容。强制校验层：在笔记写入前对所有字符串字段执行 UTF-8 校验，上传文件时保持二进制原样，并在 PowerShell 环境中检测版本后强制使用 UTF-8 字节数组发送请求。

API 调用统一封装到 ima_api.cjs 脚本，采用 HTTP POST + JSON Body 模式。错误处理分为两层：脚本执行错误（凭证缺失、参数非法，退出码 -100）直接从 stderr 读取 msg 展示给用户；后端业务错误（响应 JSON 中 code 非 0）则提取 msg 字段反馈。这种设计让 Agent 能准确区分「本地配置问题」与「服务端业务异常」。

使用边界与注意事项

该技能不支持视频文件、Bilibili/YouTube URL 或 file:// 协议，遇到此类请求应明确告知用户改用 IMA 桌面客户端。凭证配置是硬性要求，需通过 ~/.config/ima/client_id 与 ~/.config/ima/api_key 文件或环境变量提供，缺失时脚本会以 -100 退出。PowerShell 5.1 用户必须接受「所有 API 调用需显式转为 UTF-8 字节数组」这一约束，否则中文内容必然乱码。