IMA 技能使用示例

场景1：搜索并阅读笔记

用户请求: "帮我找一下关于项目进度的笔记"

技能执行流程:

1. 调用 search_note_book 接口搜索关键词"项目进度"
2. 从搜索结果中获取笔记的 docid
3. 调用 get_doc_content 接口获取笔记内容
4. 向用户展示笔记标题和摘要（不展示完整内容以保护隐私）

场景2：浏览笔记本

用户请求: "我想看看我的工作笔记有哪些"

技能执行流程:

1. 调用 list_note_folder_by_cursor 接口获取笔记本列表
2. 用户选择特定笔记本后，调用 list_note_by_folder_id 接口获取该笔记本中的笔记列表
3. 向用户展示笔记本名称和笔记标题列表

场景3：创建新笔记

用户请求: "帮我记录一下今天的会议内容"

技能执行流程:

1. 获取用户提供的会议内容
2. 调用 import_doc 接口创建新笔记
3. 返回新笔记的ID给用户

场景4：追加内容到现有笔记

用户请求: "在昨天的会议记录后面加上新的讨论点"

技能执行流程:

1. 先搜索找到"昨天的会议记录"笔记
2. 获取该笔记的 docid
3. 调用 append_doc 接口追加新内容
4. 确认追加成功

环境变量配置示例

在 Windows PowerShell 中配置环境变量：

# 设置环境变量（当前会话）
$env:IMA_OPENAPI_CLIENTID = "your_client_id"
$env:IMA_OPENAPI_APIKEY = "your_api_key"

# 永久设置环境变量（需要管理员权限）
[System.Environment]::SetEnvironmentVariable("IMA_OPENAPI_CLIENTID", "your_client_id", "User")
[System.Environment]::SetEnvironmentVariable("IMA_OPENAPI_APIKEY", "your_api_key", "User")

在 Windows 命令提示符中：

setx IMA_OPENAPI_CLIENTID "your_client_id"
setx IMA_OPENAPI_APIKEY "your_api_key"

技能触发关键词

当用户输入包含以下关键词时，IMA技能会自动触发：

• "笔记"、"备忘录"、"记事"、"记录"
• "知识库"、"文档"、"资料"
• "查找笔记"、"搜索笔记"、"查看笔记"
• "创建笔记"、"新建笔记"、"记录一下"
• "追加内容"、"添加内容"、"补充笔记"

隐私保护原则

1. 公开场合不展示完整内容：在群聊等公开场景中，只展示笔记标题和摘要
2. 用户确认后才展示内容：需要用户明确确认后才展示笔记完整内容
3. 敏感信息处理：如果笔记包含敏感信息，提醒用户注意隐私保护
4. 操作确认：重要操作（如删除、修改）需要用户二次确认

错误处理示例

场景：API 调用失败

用户请求: "搜索一下项目文档"

技能执行流程:

1. 尝试调用 search_note_book 接口
2. 如果返回错误码 100002（权限不足）：
   • 提示用户："需要配置 IMA API 凭证，请访问 https://ima.qq.com/agent-interface 获取 Client ID 和 Api Key"
   • 提供环境变量配置方法
3. 如果返回错误码 100007（频率限制）：
   • 提示用户："操作过于频繁，请稍后再试"
4. 如果返回其他错误码：
   • 提示用户："操作失败，错误码：[错误码]，请稍后重试"

场景：内容超长

用户请求: "创建一篇很长的笔记"

技能执行流程:

1. 调用 import_doc 接口
2. 如果返回错误码 100009（内容超长）：
   • 提示用户："内容过长，建议拆分写入"
   • 询问用户是否要拆分内容
3. 如果用户同意拆分：
   • 将内容按段落拆分
   • 创建多篇笔记或使用 append_doc 接口分批写入