Cherry Studio Shell 运行时与托管 CLI 完整指南bun/uv/rg 与 cli_list/cli_search/cli_install 实战【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 为具备 Shell 能力的通用 Agent 注入了两类本地执行能力随应用捆绑的 Shell 运行时bun、uv/uvx、rg以及通过mcp__cherry-tools__MCP 服务器暴露的托管 CLI 管理工具cli_list、cli_search、cli_install。前者用于执行本地、项目级或一次性任务后者在 Cherry 的隔离托管环境中安装可复用的 CLI。读完本文你将掌握按任务生命周期选择合适的执行机制、正确调用三个 CLI MCP 工具、以及安全通过审批门控的完整工作流。本文以 cli.md 为骨架并结合 cherryCliTools.ts、BinaryManager.ts 及其测试用例给出源码级佐证。需要强调的是本文只说明路由、时序与安全约束不替代会话中的实时工具 Schema——参数形状一律以 Agent 会话中暴露的 MCP 工具 Schema 为准。背景从全局路由表到 CLI 领域在 Cherry Studio 中第一方工具通过四个 MCP 服务器注入到会话mcp__cherry-tools__*、mcp__agent-memory__*、mcp__skills__*、mcp__mcp-manager__*而 CLI 相关能力属于其中的mcp__cherry-tools__服务器。领域路由定义在 SKILL.md 的全局路由表中用户意图路由参考文档运行 JS/TS 或 Python、调用一次性包、搜索本地代码/文件按任务生命周期使用捆绑的bun、uv/uvx、rgcli.md查找/安装命令行工具command -v检查 →mcp__cherry-tools__cli_list→mcp__cherry-tools__cli_search→mcp__cherry-tools__cli_install需审批cli.md从源码看这三个工具由CherryCliTools类实现注册在名为cherry-tools的 MCP 服务器上见 cherryBuiltinTools.ts工具全限定名分别为mcp__cherry-tools__cli_list、mcp__cherry-tools__cli_search、mcp__cherry-tools__cli_install常量定义见 cherryCliTools.ts。按生命周期选择执行机制核心原则是尽量使用生命周期最短的机制。下表完整给出官方推荐矩阵需求使用方式运行一个 JS/TS 文件bun file为已有 JS 项目安装依赖 / 添加项目依赖在项目 cwd 下执行bun install/bun add pkg运行一次性 JavaScript 包bun x tool注意仅捆绑了bun没有bunx垫片运行 Python 文件uv run python file带临时依赖运行 Pythonuv run --with pkg python file运行一次性 Python CLIuvx tool搜索本地文件或内容rg为后续任务保留 CLI、登录或持久化配置使用下面的托管 CLI 工作流可用运行时与 PATH 规则具备 Shell 能力的通用 Agent 会在执行 PATH 中获得bun、uv/uvx、rg。官方明确要求优先使用这三个命令而不是node/npm/npx/pip——后者不保证存在不要假设版本或来源Cherry 托管或系统可执行文件可能遮蔽捆绑的兜底版本若command -v无法解析这些预期命令应报告环境问题而不是假装命令已执行。从源码可印证“捆绑”的含义BinaryManager在启动时会把随应用分发的二进制解压到cherry.bin目录通过版本标记文件如.mise-version探测捆绑版本见 BinaryManager.ts。运行时查找顺序为mise shim → 捆绑二进制 → 用户登录 shell 的 PATH见 docs/references/binary-manager/README.md。而probeSystem使用原始登录 shell 环境做系统路径探测确保 Cherry 自己的目录不会被误判为系统可执行文件。依赖变更必须留在当前项目内以下操作因会在 Agent 会话之间泄漏状态而被禁止全局安装-g/--globaluv tool installpip install --user直接修改mise配置正确的替代方案是一次性工具用bun x/uvx需要持久化的工具走托管 CLI 工作流。此外注意边界不要用cli_install安装项目库也不要用临时运行器运行需要登录或复用的 CLI。条件可用性哪些会话能用 cli_*CLI 管理工具并非对每个角色都开放内置 Assistantbuilt-in Assistant不暴露cli_*工具对其他角色以实时工具列表为准——若这些工具缺失说明当前会话无法安装 CLI应当如实说明而不是绕过捆绑 Shell 运行时的上述指导仅在会话暴露 Shell 时适用。CherryCliTools的handles()只认cli_list/cli_search/cli_install三个名字见 cherryCliTools.ts若在 ListTools 中看不到它们调用同样会失败。审批门控cli_install 是受审批的变更mcp__cherry-tools__cli_install会改变持久化状态因此受审批门控只有在用户意图明确后才调用若审批被拒绝停止并报告——不要通过 Shell 重试同一效果。这与 SKILL.md 的全局审批规则一致受审批门控的工具还包括kb_manage、session_create、session_send、install_skill、install_mcp_server。而cli_list与cli_search是只读操作不触发审批。三个 MCP 工具的参数与实现细节CherryCliTools使用 Zod 严格模式定义输入 Schema.strict()额外字段会被拒绝并在每次调用时实时读取BinaryManager见 cherryCliTools.tscli_list参数无additionalProperties: false返回Cherry 当前托管的 CLI 清单getToolInventory()实时读取关键语义只报告 Cherry 托管的二进制不检查系统 PATH。所以一个工具被报告为“不可用”仍可能在 Agent Shell 中已解析——安装副本之前必须先检查。从 binary-manager README 可知清单是四维快照definition用户自定义定义、applicationapplied/broken/absent/conflict/unknown、availabilitymise/bundled/system/none、operation进行中的安装/移除状态。托管 CLI 状态枚举定义于 BinaryManager.tsready/not_installed/installing/removing/failed/unknown。cli_search参数query可执行文件名trim后 1–200 字符必填返回mise registry 中的匹配项结果包含cli_install可直接接受的精确name和tool字段关键语义永远不要猜测可执行名或 recipe若可信文档只给出生态系统的安装命令按以下规则直接翻译生态安装命令cli_install 的 tool 字段npm install -g scope/pkgnpm:scope/pkgpipx install pkgpipx:pkgcargo install pkgcargo:pkggo install moduleversiongo:moduleGitHub Releasesgithub:owner/repo这些翻译规则直接写在cli_search工具的官方 description 中见 cherryCliTools.ts。cli_install参数name与tool必填name放置在 PATH 上的精确可执行名1–100 字符tool精确的 mise tool recipe1–500 字符如npm:scope/package、pipx:package、github:owner/reporequestedVersion可选目标版本1–200 字符返回安装后的工具条目若最终状态不是ready则isError为true安装路由在源码中有清晰的优先级见 cherryCliTools.ts若清单中已存在同名且 recipe 相同的条目 → 按名称安装installByNamerequestedVersion会转为targetVersion若该名称是 Code CLI 预置如codex→ 走CodeCliService.installCli否则 → 作为新自定义工具持久化addCustomTooldefinition 先写入注册表再做后端安装安装后重新读取清单校验最终条目状态非ready返回工具错误。测试用例完整覆盖了这些分支见 cherryCliTools.test.ts同 recipe 走installByName、Code CLI 走CodeCliService、任意合法 mise 后端走addCustomTool、最终状态failed返回isError、同名不同 recipe 会被拒绝为内置工具。完整工作流安装前的四步检查官方要求在安装任何东西之前依次执行探测 Agent 的有效 PATHmcp__cherry-tools__cli_list只报告 Cherry 托管的二进制看不到系统 PATH所以先用command -v name做 Shell 检查只读检查是允许的再决定是否安装副本。注意该 PATH 同时包含 Cherry 托管/捆绑位置与用户 shell PATH不要把它当成纯系统探测。mcp__cherry-tools__cli_search从 registry 中查出精确的name/toolrecipe。绝不猜测可执行名或 recipe。mcp__cherry-tools__cli_install使用 search 返回的 recipe或从可信文档翻译出的 recipe安装。审批在这里发生。作为补充安装环境是隔离的BinaryManager构建独立的 mise 子进程环境不会把用户 shell 中的凭据泄漏给 mise 的安装过程代理与镜像等安装设置只影响隔离安装子进程不影响已安装 CLI 的执行环境见 docs/references/binary-manager/README.md 的“GitHub rate-limit opt-in”与“China mirrors”章节。不要绕过托管环境禁止用以下方式替代cli_install它们都会绕过 Cherry 的托管环境丢掉注册、作用域、审批与同步等簿记npm install -gpipx installcargo installbrew install手动下载关键论据cli_install接受同样的后端npm:、pipx:、cargo:、github:等所以通过 Shell 绕道不会获得任何额外能力只会失去 Cherry 的簿记。Shell 只适合做检查如command -v探测 PATH不适合执行托管变更。恢复策略无效 recipe / 名字错误→ 工具返回错误应重新运行cli_search修正 recipe不要盲目重试审批被拒绝→停止并报告不要通过 Shell 安装。这一点在测试中同样被验证addCustomTool抛出校验错误如Invalid tool specification: curl installer时错误消息原样返回给模型见 cherryCliTools.test.ts。实战示例为后续数据处理安装 jq假设用户说“我需要jq供后续数据处理任务使用。”标准流程如下运行command -v jq检查 Agent 的有效 PATH——若已存在直接使用无需安装若不存在运行mcp__cherry-tools__cli_list查看 Cherry 是否已托管jq运行mcp__cherry-tools__cli_search查询jq取得精确 recipe用该 recipe 调用mcp__cherry-tools__cli_install此处触发审批永远不要自己执行brew install jq或apt install jq。与固定预置工具的关联托管工具分为两类固定工具Fixed与自定义工具Custom。固定工具的 canonical mise recipe 由代码持有不写任何 Preference其预置定义在 binaryTools.ts包括uv、bun、fd、rg、rtk、lark-cligithub:larksuite/cli、gh、ntnnpm:ntn、BabelDOC Streampipx:babeldoc-stream等Code CLI 则单独维护在 codeCliTools 预置中。自定义工具是用户通过cli_install新增的每个定义{ name, tool, requestedVersion? }持久化在feature.binary.tools自定义注册表中——持久化的定义只代表用户添加过该工具不证明当前存在可执行文件。了解这一区分有助于理解cli_install的行为安装一个固定预置工具时走 canonical recipe 与版本升级逻辑安装自定义工具时才真正写入注册表并做后端安装。总结场景正确做法本地一次性执行 JS/TSbun file/bun x tool本地一次性执行 Pythonuv run python file/uv run --with pkg/uvx tool本地搜索rg需要登录、复用或持久化配置的 CLIcommand -v→cli_list→cli_search→cli_install审批工具不可用但会话无 Shell 或无 cli_* 工具如实报告不绕过这套“短生命周期优先 持久化走托管环境 审批门控”的机制既保证了 Agent 本地执行的灵活性又把跨会话状态泄漏和未经簿记的系统级变更挡在边界之外。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio Shell 运行时与托管 CLI 完整指南：bun/uv/rg 与 cli_list/cli_search/cli_install 实战
Cherry Studio Shell 运行时与托管 CLI 完整指南bun/uv/rg 与 cli_list/cli_search/cli_install 实战【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 为具备 Shell 能力的通用 Agent 注入了两类本地执行能力随应用捆绑的 Shell 运行时bun、uv/uvx、rg以及通过mcp__cherry-tools__MCP 服务器暴露的托管 CLI 管理工具cli_list、cli_search、cli_install。前者用于执行本地、项目级或一次性任务后者在 Cherry 的隔离托管环境中安装可复用的 CLI。读完本文你将掌握按任务生命周期选择合适的执行机制、正确调用三个 CLI MCP 工具、以及安全通过审批门控的完整工作流。本文以 cli.md 为骨架并结合 cherryCliTools.ts、BinaryManager.ts 及其测试用例给出源码级佐证。需要强调的是本文只说明路由、时序与安全约束不替代会话中的实时工具 Schema——参数形状一律以 Agent 会话中暴露的 MCP 工具 Schema 为准。背景从全局路由表到 CLI 领域在 Cherry Studio 中第一方工具通过四个 MCP 服务器注入到会话mcp__cherry-tools__*、mcp__agent-memory__*、mcp__skills__*、mcp__mcp-manager__*而 CLI 相关能力属于其中的mcp__cherry-tools__服务器。领域路由定义在 SKILL.md 的全局路由表中用户意图路由参考文档运行 JS/TS 或 Python、调用一次性包、搜索本地代码/文件按任务生命周期使用捆绑的bun、uv/uvx、rgcli.md查找/安装命令行工具command -v检查 →mcp__cherry-tools__cli_list→mcp__cherry-tools__cli_search→mcp__cherry-tools__cli_install需审批cli.md从源码看这三个工具由CherryCliTools类实现注册在名为cherry-tools的 MCP 服务器上见 cherryBuiltinTools.ts工具全限定名分别为mcp__cherry-tools__cli_list、mcp__cherry-tools__cli_search、mcp__cherry-tools__cli_install常量定义见 cherryCliTools.ts。按生命周期选择执行机制核心原则是尽量使用生命周期最短的机制。下表完整给出官方推荐矩阵需求使用方式运行一个 JS/TS 文件bun file为已有 JS 项目安装依赖 / 添加项目依赖在项目 cwd 下执行bun install/bun add pkg运行一次性 JavaScript 包bun x tool注意仅捆绑了bun没有bunx垫片运行 Python 文件uv run python file带临时依赖运行 Pythonuv run --with pkg python file运行一次性 Python CLIuvx tool搜索本地文件或内容rg为后续任务保留 CLI、登录或持久化配置使用下面的托管 CLI 工作流可用运行时与 PATH 规则具备 Shell 能力的通用 Agent 会在执行 PATH 中获得bun、uv/uvx、rg。官方明确要求优先使用这三个命令而不是node/npm/npx/pip——后者不保证存在不要假设版本或来源Cherry 托管或系统可执行文件可能遮蔽捆绑的兜底版本若command -v无法解析这些预期命令应报告环境问题而不是假装命令已执行。从源码可印证“捆绑”的含义BinaryManager在启动时会把随应用分发的二进制解压到cherry.bin目录通过版本标记文件如.mise-version探测捆绑版本见 BinaryManager.ts。运行时查找顺序为mise shim → 捆绑二进制 → 用户登录 shell 的 PATH见 docs/references/binary-manager/README.md。而probeSystem使用原始登录 shell 环境做系统路径探测确保 Cherry 自己的目录不会被误判为系统可执行文件。依赖变更必须留在当前项目内以下操作因会在 Agent 会话之间泄漏状态而被禁止全局安装-g/--globaluv tool installpip install --user直接修改mise配置正确的替代方案是一次性工具用bun x/uvx需要持久化的工具走托管 CLI 工作流。此外注意边界不要用cli_install安装项目库也不要用临时运行器运行需要登录或复用的 CLI。条件可用性哪些会话能用 cli_*CLI 管理工具并非对每个角色都开放内置 Assistantbuilt-in Assistant不暴露cli_*工具对其他角色以实时工具列表为准——若这些工具缺失说明当前会话无法安装 CLI应当如实说明而不是绕过捆绑 Shell 运行时的上述指导仅在会话暴露 Shell 时适用。CherryCliTools的handles()只认cli_list/cli_search/cli_install三个名字见 cherryCliTools.ts若在 ListTools 中看不到它们调用同样会失败。审批门控cli_install 是受审批的变更mcp__cherry-tools__cli_install会改变持久化状态因此受审批门控只有在用户意图明确后才调用若审批被拒绝停止并报告——不要通过 Shell 重试同一效果。这与 SKILL.md 的全局审批规则一致受审批门控的工具还包括kb_manage、session_create、session_send、install_skill、install_mcp_server。而cli_list与cli_search是只读操作不触发审批。三个 MCP 工具的参数与实现细节CherryCliTools使用 Zod 严格模式定义输入 Schema.strict()额外字段会被拒绝并在每次调用时实时读取BinaryManager见 cherryCliTools.tscli_list参数无additionalProperties: false返回Cherry 当前托管的 CLI 清单getToolInventory()实时读取关键语义只报告 Cherry 托管的二进制不检查系统 PATH。所以一个工具被报告为“不可用”仍可能在 Agent Shell 中已解析——安装副本之前必须先检查。从 binary-manager README 可知清单是四维快照definition用户自定义定义、applicationapplied/broken/absent/conflict/unknown、availabilitymise/bundled/system/none、operation进行中的安装/移除状态。托管 CLI 状态枚举定义于 BinaryManager.tsready/not_installed/installing/removing/failed/unknown。cli_search参数query可执行文件名trim后 1–200 字符必填返回mise registry 中的匹配项结果包含cli_install可直接接受的精确name和tool字段关键语义永远不要猜测可执行名或 recipe若可信文档只给出生态系统的安装命令按以下规则直接翻译生态安装命令cli_install 的 tool 字段npm install -g scope/pkgnpm:scope/pkgpipx install pkgpipx:pkgcargo install pkgcargo:pkggo install moduleversiongo:moduleGitHub Releasesgithub:owner/repo这些翻译规则直接写在cli_search工具的官方 description 中见 cherryCliTools.ts。cli_install参数name与tool必填name放置在 PATH 上的精确可执行名1–100 字符tool精确的 mise tool recipe1–500 字符如npm:scope/package、pipx:package、github:owner/reporequestedVersion可选目标版本1–200 字符返回安装后的工具条目若最终状态不是ready则isError为true安装路由在源码中有清晰的优先级见 cherryCliTools.ts若清单中已存在同名且 recipe 相同的条目 → 按名称安装installByNamerequestedVersion会转为targetVersion若该名称是 Code CLI 预置如codex→ 走CodeCliService.installCli否则 → 作为新自定义工具持久化addCustomTooldefinition 先写入注册表再做后端安装安装后重新读取清单校验最终条目状态非ready返回工具错误。测试用例完整覆盖了这些分支见 cherryCliTools.test.ts同 recipe 走installByName、Code CLI 走CodeCliService、任意合法 mise 后端走addCustomTool、最终状态failed返回isError、同名不同 recipe 会被拒绝为内置工具。完整工作流安装前的四步检查官方要求在安装任何东西之前依次执行探测 Agent 的有效 PATHmcp__cherry-tools__cli_list只报告 Cherry 托管的二进制看不到系统 PATH所以先用command -v name做 Shell 检查只读检查是允许的再决定是否安装副本。注意该 PATH 同时包含 Cherry 托管/捆绑位置与用户 shell PATH不要把它当成纯系统探测。mcp__cherry-tools__cli_search从 registry 中查出精确的name/toolrecipe。绝不猜测可执行名或 recipe。mcp__cherry-tools__cli_install使用 search 返回的 recipe或从可信文档翻译出的 recipe安装。审批在这里发生。作为补充安装环境是隔离的BinaryManager构建独立的 mise 子进程环境不会把用户 shell 中的凭据泄漏给 mise 的安装过程代理与镜像等安装设置只影响隔离安装子进程不影响已安装 CLI 的执行环境见 docs/references/binary-manager/README.md 的“GitHub rate-limit opt-in”与“China mirrors”章节。不要绕过托管环境禁止用以下方式替代cli_install它们都会绕过 Cherry 的托管环境丢掉注册、作用域、审批与同步等簿记npm install -gpipx installcargo installbrew install手动下载关键论据cli_install接受同样的后端npm:、pipx:、cargo:、github:等所以通过 Shell 绕道不会获得任何额外能力只会失去 Cherry 的簿记。Shell 只适合做检查如command -v探测 PATH不适合执行托管变更。恢复策略无效 recipe / 名字错误→ 工具返回错误应重新运行cli_search修正 recipe不要盲目重试审批被拒绝→停止并报告不要通过 Shell 安装。这一点在测试中同样被验证addCustomTool抛出校验错误如Invalid tool specification: curl installer时错误消息原样返回给模型见 cherryCliTools.test.ts。实战示例为后续数据处理安装 jq假设用户说“我需要jq供后续数据处理任务使用。”标准流程如下运行command -v jq检查 Agent 的有效 PATH——若已存在直接使用无需安装若不存在运行mcp__cherry-tools__cli_list查看 Cherry 是否已托管jq运行mcp__cherry-tools__cli_search查询jq取得精确 recipe用该 recipe 调用mcp__cherry-tools__cli_install此处触发审批永远不要自己执行brew install jq或apt install jq。与固定预置工具的关联托管工具分为两类固定工具Fixed与自定义工具Custom。固定工具的 canonical mise recipe 由代码持有不写任何 Preference其预置定义在 binaryTools.ts包括uv、bun、fd、rg、rtk、lark-cligithub:larksuite/cli、gh、ntnnpm:ntn、BabelDOC Streampipx:babeldoc-stream等Code CLI 则单独维护在 codeCliTools 预置中。自定义工具是用户通过cli_install新增的每个定义{ name, tool, requestedVersion? }持久化在feature.binary.tools自定义注册表中——持久化的定义只代表用户添加过该工具不证明当前存在可执行文件。了解这一区分有助于理解cli_install的行为安装一个固定预置工具时走 canonical recipe 与版本升级逻辑安装自定义工具时才真正写入注册表并做后端安装。总结场景正确做法本地一次性执行 JS/TSbun file/bun x tool本地一次性执行 Pythonuv run python file/uv run --with pkg/uvx tool本地搜索rg需要登录、复用或持久化配置的 CLIcommand -v→cli_list→cli_search→cli_install审批工具不可用但会话无 Shell 或无 cli_* 工具如实报告不绕过这套“短生命周期优先 持久化走托管环境 审批门控”的机制既保证了 Agent 本地执行的灵活性又把跨会话状态泄漏和未经簿记的系统级变更挡在边界之外。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考