SuperAPI AI 工具集

cherry-tool-guide

通用与其它

查看项目

更新于 10-27 09:37

技能介绍

该指南是 Cherry Studio 注入到会话中的工具路由文档,用于说明如何正确调用由四个 MCP 服务器提供的一组首方工具:mcp__cherry-tools__、mcp__agent-memory__、mcp__skills__* 与 mcp__mcp-manager__*。这些工具作用于正在运行的 Cherry Studio 应用,能够触及用户的知识库、IM 渠道、定时计划、受管 CLI、技能库与 MCP 服务器注册表,并且这些变更边界只有 Cherry 自身能够正确处理;普通 shell 与文件工具无法正确触达。同时,具备 shell 能力的通用智能体会附带用于本地执行的运行时。

从用途看,该文件本身是路由器,只包含全局规则和“意图 → 工具 → 参考文档”的对照表。每个参考文档负责对应领域的前置条件、调用顺序、条件可用性、输出解读、恢复方式与示例。使用前应先阅读任务所需的那一份参考文档(以及它交叉引用的文档),不能仅凭本页操作。

全局规则包括:首先检查工具是否可用,部分工具为条件可用,若不在当前会话的工具列表中,应如实说明能力不可用并停止,不得假装成功或编造结果。不得绕过 Cherry 的变更边界:知识库、IM 渠道、定时计划、受管 CLI、技能与已注册 MCP 服务器只能通过这些工具变更,不应使用 npm install、git clone、crontab 或手动编辑配置文件等方式完成,因为这些工具会执行注册、作用域、审批、同步等簿记工作,而原始 shell 命令会跳过这些步骤;shell 可用于检查,例如用 command -v 探测 PATH,但不可用于执行被托管的变更。需要遵守审批:kb_manage、cli_install、session_create、session_send、install_skill、install_mcp_server 受会话审批模式约束,只有在用户意图明确后才可调用,若审批被拒绝应停止并报告,不得通过其他途径重试相同效果。即使某些效果自动批准(如记忆写入、计划变更、通知、智能体/渠道配置),仍应由用户请求或为完成已批准任务所必需,不能仅因可用就调用。

路由表按用户意图给出调用路径:查询当前/在线事实、新闻、文档时走 web_search → web_fetch;浏览器交互(点击、表单、截图)在启用 Browser 时使用自动化 REPL 并加载 cherry-browser;原生桌面应用操作在启用 Computer Use 时使用自动化 REPL 并加载 cherry-computer;基于用户文档回答时使用 kb_list → kb_search → kb_read;新增/删除/重建知识库索引使用 kb_manage(需先解析 ID,需审批);读取或转换本地文档使用 to_markdown,再按需读取返回的临时 Markdown 路径;回忆过去的事实、纠正或偏好时先搜索记忆;保存长期知识还是单次事件时区分 update 与 append;安排重复或未来任务使用 cron(仅 Cherry 调度);主动向用户发消息或发送文件使用 notify(需配置收件人);检查/连接/修复 IM 渠道、重命名智能体使用 config;查找、创建、发消息或检查 Agent 会话使用 session_list / session_search / session_create / session_send / session_deliveries;生成图像使用 generate_image(需绘画模型);声明最终交付文件使用 report_artifacts;运行 JS/TS 或 Python、调用一次性包、搜索本地代码/文件时,按任务生命周期选用附带的 bun、uv/uvx 或 rg;查找/安装命令行工具时依次执行 command -v 检查 → cli_list → cli_search → cli_install(需审批);查找/安装新能力技能时使用 search_skills → install_skill(需审批);注册用户提供的新 MCP 服务器时使用 install_mcp_server(需审批,且不得自创配置)。

工具不可用时需要区分两种情况:一是工具不在当前列表中,表示该能力在本会话不可用(例如作用域内没有知识库,或 shell-less 智能体禁用了 CLI 管理),应说明缺少什么以及用户可以做什么,不要用 shell/文件工具绕过;二是工具已列出但报告缺少依赖(例如没有绘画模型时的 generate_image),它会保持列出并返回提示,应转述提示并引导用户检查配置,不要盲目重试或伪造成功。遇到任何工具错误(无效 ID、不支持的渠道/文件、无效 recipe)时,应阅读消息并修正调用,不要用相同参数静默重试;审批被拒时停止并报告,绝不通过其他途径重试变更。

该指南不覆盖:SDK 原生的 Read/Edit/Bash 与编排工具;调用第三方(用户配置)MCP 服务器的工具(只涉及注册,见 mcp.md);AI-SDK 聊天路径的 read_file 附件读取器;以及属于 Cherry Assistant 的 mcp__assistant__* 导航/诊断工具。