Cherry Studio 中 Pi 的非交互 JSON 模式调用:code-mate-pi Skill 实战指南

发布时间:2026/11/19 3:30:40

Cherry Studio 中 Pi 的非交互 JSON 模式调用:code-mate-pi Skill 实战指南 人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载本指南围绕 Cherry Studio 仓库内置的 code-mate-pi/SKILL.md 展开讲解如何以无头headless方式调用 Pi 编码代理完成仓库内的有界分析与实现任务。读完本文你将掌握pi --mode json --no-session的完整调用协议、JSONL 事件流解析要点、工具白名单的最小化授权策略以及 Cherry Studio 主进程中该 Skill 背后的安装同步与运行时代码支撑。一、code-mate-pi 是什么一份写给 Agent 的操作手册resources/code-cli-skills/目录下按 CLI 工具分类存放了一批 SKILL 文件code-mate-claude-code、code-mate-codex、code-mate-pi等它们是 Cherry Studio 为外部编码 CLI 准备的内置技能builtin skill。每一份SKILL.md都以 YAML frontmatter 声明name与description正文则用 Markdown 精确描述该 CLI 应如何被安全、正确地调用。code-mate-pi的 frontmatter 明确声明了它的适用场景--- name: code-mate-pi description: Runs Pi non-interactively and parses its JSON event stream for repository tasks. Use when the user asks to delegate a bounded analysis or implementation task to Pi. ---翻译过来即当用户希望把一个有边界的分析或实现任务委托给 Pi 时以非交互方式运行 Pi并解析其 JSON 事件流。它并不是一篇泛泛的 Pi 功能简介而是一份可执行的调用协议全文仅围绕如何正确启动、如何解析输出、如何约束权限三个问题展开具有很高的实战可复制性。二、运行前置条件工作目录、超时与可用性探测SKILL.md 给出的第一步是两项强制性前置检查把 Bash 工作目录切换到用户指定的确切项目目录并设置一个有限超时通常为 10 分钟。这保证了 Pi 的所有相对路径解析、文件工具与 Bash 工具都落在正确的仓库上下文中同时避免无界任务挂死整个委托流程。用command -v pi探测可用性。若命令不存在应立即停止并提示用户在 Code Mate 中安装 Pi而不是自行尝试修补环境或绕过检查。command -v走当前 shell 的 PATH 查找能同时覆盖系统安装与 Cherry Studio 托管安装两种来源。在 Cherry Studio 源码中Pi 的安装事实由 src/shared/data/presets/codeCliTools.ts 统一登记可执行名为pinpm 包名为earendil-works/pi-coding-agent安装方式为npm对应的 Skill 目录正是code-mate-pi其命名空间由defineCodeCliTool统一生成为code-cli:pi。这份 preset 同时被主进程与渲染进程共享是安装什么、同步哪份 Skill的唯一事实来源。三、核心命令pi --mode json --no-sessionSKILL.md 规定的标准调用方式是一次无会话sessionless的单次任务pi --mode json --no-session prompt两个关键参数缺一不可参数作用--mode json让 Pi 以 JSON 模式运行stdout 输出 JSONL每行一个 JSON 事件便于程序化逐行解析--no-session明确要求不进入交互式会话一次性完成当前任务后即退出3.1 prompt 必须作为单个带引号参数传递SKILL.md 特别强调 Pass the prompt as one quoted argument——prompt 必须整体作为单个参数传入。这既是 shell 层面的正确性要求防止含空格、引号、$()、反引号的 prompt 被拆分或触发命令替换也是事件流语义的要求Pi 将整个字符串视为一次完整任务的指令而非多段对话。3.2 解析 stdout 为 JSONL并检查错误事件这是整个 Skill 最核心的工程要点Parse stdout as JSONL and inspect error events; Pi can report model or tool failure in the event stream, so process exit alone is insufficient.即不能只依赖进程退出码判断成败。Pi 可能以 0 退出码正常结束但事件流中已经上报了模型失败或工具失败tool failure。因此调用方必须把 stdout 逐行按 JSON 解析主动检查其中是否包含 error 类事件只有退出码为 0且事件流无错误事件才算成功。这与 Cherry Studio 主进程对 Pi 的处理哲学完全一致。在 src/main/ai/runtime/pi/PiRuntimeConnection.ts 中Pi 的所有底层事件tool_execution_start、turn_end、agent_end、compaction_end等都经过AsyncEventQueue转成AgentRuntimeEvent事件流其中turn_end的stopReason error或length会被转换为显式错误事件finishPromptRunagent_end携带的错误信息也会被提取为lastAgentError。也就是说Cherry Studio 自己集成 Pi 时同样遵守事件流是唯一权威、退出码不够用的原则。3.3 禁止交互式启动SKILL.md 明确要求 Never start interactive Pi or/login。交互式 REPL 会阻塞等待用户输入破坏无头自动化的确定性/login是登录流程同样属于交互式命令被一并禁止。任何需要登录的配置都应在 Code Mate 中由用户预先完成见下一节。四、认证与权限最小授权、绝不触碰凭据4.1 配置缺失时停止并让用户介入If Pi reports missing login, model, provider, or API configuration, stop and ask the user to configure Pi in Code Mate.当事件流中出现缺登录、缺模型、缺 provider 或缺 API 配置的报错时调用方应立即停止把配置问题交还给用户在 Code Mate 中处理而不是自行猜测、反复重试或尝试注入配置。同时有一条红线级约束Never request, read, print, or copy credentials.绝不请求、读取、打印或复制任何凭据。这与 Cherry Studio 主进程的凭据处理原则同源在PiRuntimeConnection中Cherry 通过pi.AuthStorage.inMemory()与pi.ModelRegistry.inMemory()以内存方式持有运行时注入的 API KeyPiRuntimeConnection.ts源码注释明确说明 Cherry owns the credential model registry: in-memory only, never pis global auth.json/models.json——真实密钥只作为运行时覆盖存在绝不落盘到 Pi 的全局配置文件连接关闭时随unregisterApiProvider一并清理。4.2 Pi 没有工具审批提示授权边界必须由调用方收紧SKILL.md 指出Pi has no tool-approval prompt and normally exposes read, write, edit, and Bash tools.Pi 原生没有工具级审批tool-approval提示默认会暴露read、write、edit、Bash等工具。这意味着在无头模式下模型可以自行决定调用写操作与 shell 命令因此授权边界必须由调用方在命令行层显式施加——这正是--tools参数存在的意义。SKILL.md 给出的策略是For analysis, append--tools read,grep,find,ls. Include write, edit, or Bash only when the user explicitly requested workspace changes, and keep the tool list and working directory as narrow as possible.即纯分析类任务附加--tools read,grep,find,ls只开放只读能力需要修改仓库的任务仅当用户明确要求工作区变更时才追加write、edit或 Bash总体原则工具列表与工作目录都要保持尽可能窄as narrow as possible。值得注意的是SKILL.md 列举的只读白名单read、grep、find、ls与 Cherry Studio 内部对 Pi 内置工具的分类相互印证。在 src/shared/ai/piBuiltinTools.ts 中Pi 的原生内置工具被登记为readfile 类、permissionClassread、auto 审批、bashshell 类、prompt 审批、editfile 类、edit 类、writefile 类、edit 类另有tool_search、tool_describe、tool_call、tool_exec四个检索/执行辅助工具。其中只有read属于只读自动放行类别bash、edit、write均属会产生副作用或修改状态的类别——与 Skill 中只读任务默认只开 read/grep/find/ls、写工具按需追加的建议完全对齐。更进一步Cherry Studio 在 SDK 集成侧把同样的授权哲学落到了 src/main/ai/runtime/pi/approvalExtension.tsPi 暴露单一的tool_call钩子可在执行前拦截调用并原地改写event.input该扩展按顺序执行 disabledTools 硬屏蔽 → 用户数据 SQLite 保护 → 全局安装拦截 → rtk 命令改写 → 审批分发权限模式permission mode与禁用工具集都在运行时强制生效。命令行无头调用靠--tools白名单SDK 集成靠审批扩展两者殊途同归。五、完整实操一次只读诊断任务的标准流程将以上规则组合起来一次标准的只读诊断任务应遵循以下流程# 1. 切换到目标仓库目录设置有限超时如 10 分钟 cd /path/to/target/repo # 2. 确认 pi 可用缺失则停止并提示用户在 Code Mate 安装 command -v pi # 3. 以只读工具白名单运行单次无会话任务 pi --mode json --no-session --tools read,grep,find,ls \ 诊断 src/main/services/codeCli 目录下的代码结构输出关键类与职责清单输出解析规则SKILL.md 的收尾建议逐行解析 stdout将每一行作为独立 JSON 事件处理先检查是否存在 error 事件模型失败、工具失败、配置缺失等仅当没有任何错误事件时才采信最后一条 JSONL 消息final JSONL message作为任务结论。如果事件流中出现缺登录/模型/API 配置类错误则停止并把配置工作交还给用户在 Code Mate 中完成如果用户明确要求修改工作区才在--tools中追加write,edit,bash且工作目录与工具范围保持最小。六、源码级支撑这份 Skill 在 Cherry Studio 中如何落地6.1 Skill 的安装与同步链路code-mate-pi/SKILL.md不是孤立文档它经由 src/main/services/codeCli/CodeCliService.ts 的installCliSkill方法同步进 Cherry Studio 的技能库private async installCliSkill(preset: CodeCliToolPreset): Promisevoid { const sourcePath path.join( toAsarUnpackedPath(application.getPath(feature.code_cli.skills.builtin)), preset.skillFolderName ) await skillService.syncBuiltinSkill(preset.skillFolderName, sourcePath, app.getVersion(), preset.skillNamespace) }链路为二进制可用 → 按 preset 定位内置 Skill 目录 → 调用SkillService.syncBuiltinSkill同步到技能库。当 Pi 被卸载removeCli或快照显示其不可用时reconcileCliSkill对应的内置 Skill 会按code-cli:pi命名空间通过uninstallBuiltinSkill移除。也就是说Skill 的存在与否与 CLI 的安装状态自动对齐用户在 Code Mate 中安装/卸载 Pi 时无需手动管理这份 Skill应用启动时onAllReady还会执行一次全量reconcileCliSkills兜底。6.2 技能库的存储与镜像机制在 src/main/ai/skills/SkillService.ts 中可以看到技能的存储模型技能存放在{dataPath}/Skills/{folderName}/应用自有规范库同时镜像到CLAUDE_CONFIG_DIR/skills供 Claude Agent SDK 发现库的元数据存于agent_global_skill表按 Agent 的启用状态存于agent_skill关联表。内置技能builtin安装后会对所有 Agent 默认启用enableForAllAgents并且由于属于内置来源镜像采用复制而非符号链接并做内容哈希校验linkMirror防止旁路写入篡改加载到其他 Agent 的指令。code-mate-pi正是这样一个受版本号与哈希双重托管的 builtin skill。6.3 Pi 运行时的无头化设计虽然code-mate-piSkill 面向命令行直接调用但 Cherry Studio 内部对 Pi 的 SDK 集成PiRuntimeConnection同样遵循事件流驱动、无审批弹窗、内存态凭据的三原则事件流即真相Pi 会话的所有事件通过订阅回调进入AsyncEventQueue模型失败stopReason error、输出截断stopReason length、工具失败都会被转成显式 error 事件而不是仅依赖 Promise 成败无原生审批模式源码注释明确指出 pi has no native permission modes; the approval extension enforces them即权限模式与工具禁用集由 Cherry 的审批扩展在工具触发时强制执行工作区受信、凭据永不入盘用户手选的工作区被标记为projectTrusted: true不再弹是否信任该项目的提示凭据通过AuthStorage.inMemory()注入连接关闭时清理。这些实现与 SKILL.md 中检查事件流错误、禁止凭据读写、无 tool-approval 提示故需显式收紧工具的规则互为印证。七、安全边界与常见错误排查场景正确做法事件流出现模型失败/工具失败事件即使退出码为 0 也判定失败不要把最后一条消息当结论出现缺登录/模型/API 配置停止交由用户在 Code Mate 配置绝不代填凭据纯分析任务只开--tools read,grep,find,ls不追加写工具用户明确要求修改工作区才追加write、edit、Bash且工作目录与工具范围保持最小进程挂起风险始终设置有限超时默认 10 分钟并禁止交互式启动与/login八、总结resources/code-cli-skills/code-mate-pi/SKILL.md 用极简篇幅定义了一套可复用的 Pi 无头调用协议有限超时 可用性探测 →pi --mode json --no-session单次任务 → JSONL 事件流解析以错误事件而非退出码为准→ 最小工具白名单 → 凭据零接触。在 Cherry Studio 中这份 Skill 由CodeCliService随 Pi 的安装状态自动同步进技能库其安全与授权原则又与PiRuntimeConnection的审批扩展、内存态凭据注入等实现深度呼应。无论是直接在终端复用这套命令完成仓库诊断还是理解 Cherry Studio 的 Code Mate 集成机制本文给出的命令、解析规则与源码路径都可作为直接参考。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio 集成 OpenClaw以 Code Mate Skill 驱动本地 Agent 的非交互式调用指南Cherry Studio 集成 OpenClaw以 Code Mate Skill 驱动本地 Agent 的非交互式调用指南 导读 resources/co人工智能大模型AI 应用交互助手本地部署Cherry Studio Code Mate用内置 Skill 非交互式运行 Qoder CN CLIqoderclicnCherry Studio Code Mate用内置 Skill 非交互式运行 Qoder CN CLIqoderclicn 本文基于 Cherry StAI 应用大模型桌面应用本地部署RAGCherry Studio Code Mate 之 Pi 技能非交互运行 Pi 编码代理并解析 JSONL 事件流Cherry Studio Code Mate 之 Pi 技能非交互运行 Pi 编码代理并解析 JSONL 事件流 在 Cherry Studio 的 CodAI 应用大模型桌面应用本地部署RAG上一篇RecurrentGemma大揭秘Google DeepMind开源语言模型如何用Griffin架构实现极速长文本推理下一篇SpringSide4邮件服务集成MailService在企业应用中的完整实现创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/19 3:30:40

Sails 应用内省指南:深入解析 `sails.getActions()` 方法

Sails 应用内省指南:深入解析 sails.getActions() 方法 【免费下载链接】sails Realtime MVC Framework for Node.js 项目地址: https://gitcode.com/gh_mirrors/sa/sails 导读 sails.getActions() 是 Sails(Realtime MVC Framework for Node.js…

2026/11/11 2:59:05

ZooKeeper客户端编程实战:从数据模型到分布式锁的避坑指南

分布式系统里,协调这件事听起来很虚,但落到代码上往往就是几个具体问题:多个进程怎么选出一个主节点、配置改了怎么让所有机器同时生效、某个节点挂了怎么让其他人立刻知道。ZooKeeper 就是为解决这类问题而生的。它对外暴露的接口非常朴素—…

2026/11/11 6:26:27

miniblink49 网页打印与 PDF 导出实战:从参数配置到故障排查

miniblink49 网页打印与 PDF 导出实战:从参数配置到故障排查 【免费下载链接】miniblink49 a lighter, faster browser kernel of blink to integrate HTML UI in your app. 一个小巧、轻量的浏览器内核,用来取代wke和libcef 项目地址: https://gitcod…

2026/11/19 3:30:33

职高让考电工证吗现在 怎么在哪考电工证不被坑

职高让考电工证吗现在 怎么在哪考电工证不被坑 你是不是正愁不知道去哪报名考电工证,担心被中介骗钱?现在很多人觉得职高毕业后就不用再考电工证了,但其实不然。特别是在特种作业操作证领域,电工证是必须的。职高让考电工证吗现在?这个问题,很多同学和…

2026/11/19 3:30:33

铜川考电工证好过嘛?学历不高怕报不上名?网上查询最新政策

铜川考电工证好过嘛?学历不高怕报不上名?网上查询最新政策 学历不高怕报不上名?网上查询最新政策,发现其实铜川考电工证门槛并不高,关键是要掌握正确信息和备考策略。现在电工证已经不再是“高学历专属”,只要符合基本条件,很多人都能顺利报考。尤其是…

2026/11/19 3:30:33

肥西高低压电工证怎么考?2026河南最新政策全知道

肥西高低压电工证怎么考?2026河南最新政策全知道 你缺一张肥西高低压电工证,就少了一把打开电工行业的钥匙。在河南,尤其是2026年新规落地后,特种作业证的门槛越来越高,企业对持证上岗的要求也越来越严格。如果你是应届工程类毕业生,正打算进入…

2026/11/19 3:25:33

邯郸电工证在哪里培训千万别踩坑实操考试心里没底怕挂科

邯郸电工证在哪里培训千万别踩坑实操考试心里没底怕挂科 实操考试心里没底怕挂科,这是很多准备考邯郸电工证的学员最真实的心理状态。别看现在电工证是刚需,但真正去培训、考试的时候,还是会因为培训质量、考试难度、流程不熟悉等问题,让自己多走弯路。特…

2026/11/18 21:12:58

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/18 21:55:23

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/19 0:04:42

深圳电工证培训考场模拟考试题库:郑州报考避坑指南

深圳电工证培训考场模拟考试题库:郑州报考避坑指南 证书过期了不知道怎么复审延期,很多人在遇到这个问题的时候才意识到特种作业证的重要性。其实,不管是电工证、焊工证还是高处作业证,这些证书不仅是上岗的“通行证”,更是法律对安全操作的硬性要求。尤…

2026/11/19 0:04:42

天津电工证查询入口多少钱能报上名

天津电工证查询入口多少钱能报上名 学历不高怕报不上名?别急,天津电工证查询入口其实没你想的那么难。今天咱们就来聊聊,怎么用最低的门槛、最少的钱,把电工证拿下来,还能查得到、用得上。 电工证到底值不值?先搞清楚它的作用…

2026/11/18 12:37:05

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/18 1:15:04

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑