人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载导读本文是 Cherry Studio 中新增 Agent 运行时agent runtime的实操清单。Cherry Studio 的 Agent 会话体系围绕claude-code、pi、dsh三个内置运行时构建宿主服务AgentSessionRuntimeService按agent.type分发、渲染层按能力描述符驱动因此接入一个新的运行时只需一个共享层描述符条目加一个主进程驱动包无需改动宿主与渲染层的任何分支逻辑。读完本文你将掌握能力描述符各字段的语义、驱动包五个组成部分的契约、设计规则与验证命令能够独立为 Cherry Studio 新增一个与既有运行时同等完整的 Agent 运行时。前置阅读本文是操作清单operational checklist关于宿主/驱动架构本身turn 生命周期、resume token、follow-up 队列请先阅读 Agent Session Runtime。为什么新增运行时如此轻量类型无关的宿主 描述符驱动的 UICherry Studio 的 Agent 运行时架构刻意做了两层解耦宿主Host是类型无关的AgentSessionRuntimeService只通过runtimeDriverRegistry按agent.type分发从不针对某个具体运行时写分支代码。注册中心 registry.ts 以Mapstring, AiRuntimeDriver保存驱动通过getAgentSessionDriver(type)依据capabilities.includes(agent-session) connect in driver判定是否为 Agent 会话驱动。渲染层 UI 是描述符驱动的渲染层读取AGENT_RUNTIME_CAPABILITIES[agent.type]运行时选择器、权限模式选项、编辑弹窗是否显示模型分层/Soul/MCP/技能、创建弹窗默认值、内置斜杠命令、模型选择器过滤、transport 标签、内置工具目录全部由这一份描述符推导渲染层同样不针对具体运行时分支。因此新增一个运行时的全部工作收敛为一个共享层描述符条目 一个主进程驱动包。编译器和测试替你兜底的注册点多数注册点在遗漏时会直接失败并报错清单如下注册点强制手段AGENT_RUNTIME_CAPABILITIES条目satisfies RecordAgentType, AgentRuntimeCapabilities——缺少 key 时产生编译错误registerDrivers.ts中的驱动注册registerDrivers.test.ts——每个AgentType必须能解析到已注册的 agent-session 驱动描述符结构不变量agentRuntimeCapabilities.test.tsi18n key 存在且所有语言已翻译PR CI 中的pnpm lint其中唯一没有任何机制强制的是本文底部“设计规则”一节——请务必逐条阅读。以 registerDrivers.test.ts 为例测试会枚举Object.keys(AGENT_RUNTIME_CAPABILITIES)中的每个AgentType断言runtimeDriverRegistry.getAgentSessionDriver(type)均已注册——注释明确指出这是为了守卫描述符↔注册表配对一次合并若丢失了驱动注册如 pi 曾在 barrel 重构中遇到的会在该测试失败而不是等到会话打开时才暴露。Step 1 — 共享层Shared Layer1.1 扩展类型向AGENT_TYPES添加字面量在src/shared/data/api/schemas/agents.ts中AGENT_TYPES是唯一的字面量来源export const AGENT_TYPES [claude-code, pi, dsh] as constAgentTypeSchema与AgentType都由该元组派生src/shared/data/types/agent.ts仅做类型再导出。新增运行时只需把新的字面量追加进该元组。1.2 添加能力描述符在src/shared/ai/agentRuntimeCapabilities.ts中添加条目。这是驱动一切通用渲染行为的单一入口接口定义节选关键字段如下export interface AgentRuntimeCapabilities { /** 运行时选择器选项的 i18n key。 */ labelKey: string labelFallback: string permissionModes: readonly AgentPermissionMode[] /** plan/small 模型分层字段。 */ modelTiers: boolean /** 心跳编排。 */ heartbeat: boolean knowledgeBases: boolean mcp: boolean skills: boolean /** 运行时内置工具是否走 Claude 工具注册表管线当前仅 claude-code 为 true。 */ claudeRegistryTools: boolean slashCommands: readonly SlashCommand[] createDefaults: { permissionMode: AgentPermissionMode } /** 在基础 agent 友好过滤之上的额外限制null 无。provider 对孤儿模型为 undefined。 */ isModelCompatible: ((provider: Provider | undefined, model: Model) boolean) | null /** 由运行时流适配器打标的 providerMetadata.cherry.transport 标签。 */ transport: string /** 编辑弹窗目录行。 */ builtinTools: () readonly { id: string labelKey: string descriptionKey: string labelFallback?: string descriptionFallback?: string category: string }[] }书写描述符时需注意以下语义permissionModes——只列出该运行时真正支持的权限模式。例如pi没有 plan 模式因此其permissionModes是ALL_PERMISSION_MODES.filter((mode) mode ! plan)dsh没有模型侧的自动批准分类器因此过滤掉auto见 agentRuntimeCapabilities.ts 中ALL_PERMISSION_MODES [default, plan, acceptEdits, auto, bypassPermissions]。createDefaults.permissionMode——从该运行时真实的信任根与批准策略中选择见底部权限规则。isModelCompatible(provider, model)——provider对孤儿模型provider 被删除或尚未加载为undefined必须显式决定 fail-open 还是 fail-closed 并用注释说明理由。需要 provider 端点配置才能驱动模型的运行时必须 fail-closed。当前三个运行时的实现即为此规则的注脚pi、dsh都要求!!provider且拒绝托管 CherryAI 免费配额默认模型isManagedCherryAiDefaultModel而claude-code通过本地 API Gateway 触达非原生 provider因此其选择器复用网关模型目录的路由规则isGatewayRoutableModel(model)。这些行为都有对应测试锚定见 agentRuntimeCapabilities.test.ts。transport——一个唯一标签由你的流适配器在每个工具部件tool part上打标providerMetadata.cherry.transport渲染层据此把工具部件路由到对应的卡片渲染器。现有取值claude-agent、pi-agent、dsh-agent。builtinTools()——编辑弹窗目录。若运行时自带工具集应在一个共享模块中定义描述符参照src/shared/ai/piBuiltinTools.ts、src/shared/ai/dshBuiltinTools.ts的模式携带 name、category和批准默认值其余一切从该单一来源派生。1.3 添加 i18n key为运行时选项标签labelKey以及每个内置工具的agent.tools.builtin.id.*条目添加 i18n 键。流程为先在src/renderer/i18n/locales/en-us.json与zh-cn.json中添加规范的英文与中文基准值运行pnpm i18n:sync同步再手工或用翻译工具补齐其余语言当前仓库共 13 个语言文件de-de、el-gr、en-us、es-es、fr-fr、ja-jp、pt-pt、ro-ro、ru-ru、tr-tr、vi-vn、zh-cn、zh-tw最后以pnpm lint收尾。Step 2 — 主进程驱动包创建src/main/ai/runtime/name/目录实现 types.ts 中的契约。参考实现是claudeCode/、pi/、dsh/三个既有目录。驱动包共五个组成部分2.1 DriverAgentSessionRuntimeDriver必需成员typeAgentType字面量与capabilities: [agent-session]validateSession(session)——会话无法被服务时抛出异常缺少工作区、agent、模型或 provider 不可用。必须无副作用它会在每次分发时运行因此不得消耗 API-key 轮换、打开连接或写入状态listAvailableTools(mcpIds)——供批准 UI 使用的工具目录connect(input)——构建AgentRuntimeConnection可选prewarmSession/closeSessionWarm/onSessionIdle用于能从空闲预热获益的运行时参见 Claude 驱动。既有驱动的注册方式见 registerDrivers.tsregisterRuntimeDrivers()在AgentSessionRuntimeService.onInit生命周期边界被调用注册三个驱动。注意其中 Claude 驱动使用LazyClaudeCodeRuntimeDriver包装器做惰性加载loadImplementation()缓存createClaudeCodeRuntimeDriver()的 promise避免在会话打开前就拉入重量级 SDK。2.2 ConnectionAgentRuntimeConnection必需成员events——AsyncIterableAgentRuntimeEvent。最小可行事件映射见 types.ts 的联合类型chunk——流式内容turn-complete——结算宿主回合宿主在该事件上关闭 UI 回合——从不发出该事件的运行时会永久卡住回合resume-token——运行时每当获得恢复句柄时发出error——失败。可选事件还包括tool-approval-request、usage、steer-boundary/steer-undelivered、compaction-start/compaction-complete/compaction-error、api-retry、context-usage、supported-commands、background-tasks、background-work-state、autonomous-turn-state等。send(input)——投递用户消息input.systemReminder标记 steer需用wrapSteerReminder(...)包裹。reconcile(input)——重新推导期望的连接状态。并发调用按连接串行化在返回rebuild前先热应用安全的策略事实活跃回合期间冻结权限模式变更当一次收紧无法被实时应用时返回failed让宿主 fail-closed。AgentRuntimeReconcileResult的五档语义为current/patched/rebuild/invalid/failed见 types.ts。close()。可选成员省略时宿主提供回退redirect(input)——原生回合中转向steer不实现时宿主把 follow-up 排队为下一回合。若实现必须在 steer 注入时发出steer-boundary对回合结束前未注入的 steer 发出steer-undeliveredgetContextUsage()——实时上下文窗口统计省略时 UI 只是没有用量表compaction-start/compaction-complete/compaction-error事件——当运行时自行压缩历史时使用。2.3 系统提示词适配器System Prompt Adapter调用运行时中立的buildAgentRuntimePrompt()agentPrompt.ts把其{ base, append }结果映射为 SDK 原生提示词表示。传入已解析的通道状态与能力门控的引用指南citations guidance到公共 materializer。不要把以下职责复制进驱动指令优先级、内置 Agent 的回退/供给loadBuiltinAgentDefinition/provisionBuiltinAgent、提示词变量解析replacePromptVariables、通道安全、产物上报REPORT_ARTIFACTS_PROMPT、语言指南getLanguageInstruction。适配器只保留原生机制SDK 基础提示词、cwd/项目上下文载体、工具片段、技能传输以及 base/append 的表示。公共策略统一放在 materializer 中并用测试确认每个驱动都携带它。详细所有权划分见 Agent Session Runtime 的 System prompt ownership 一节。buildAgentRuntimePrompt()的append段落依次拼接指令优先级提示、产物上报提示、Agent System Prompt 区块、工作区指令、上下文部件、自定义 base 上下文、引用指南、语言指令——稳定前缀在前以利 prompt-cache 共享语言指令保持在最后以便 persona/工作区指令优先。2.4 流适配器Stream Adapter把运行时原生事件转换为UIMessageChunk。transport 常量必须从描述符导入单一来源绝不重新声明字符串。参考实现claudeCode/streamAdapter.ts、pi/piStreamAdapter.ts、dsh/dshStreamAdapter.ts。2.5 注册驱动与路径键在 registerDrivers.ts 中注册驱动由AgentSessionRuntimeService.onInit调用。不要创建有副作用的register.ts模块——未导入的副作用模块正是 pi 的注册在一次合并中悄然丢失的原因该事故由 registerDrivers.test.ts 的配对测试兜住。若运行时需要磁盘状态配置目录、会话文件在路径注册表src/main/core/paths/中添加feature.agents.name.*键而不是临时拼路径。Step 3 — 渲染层通常什么都不用改。选择器选项、编辑/创建弹窗、斜杠命令、模型过滤、transport 路由全部从描述符推导。已知例外仅在需要时处理定制工具卡片渲染——src/renderer/components/chat/messages/tools/按 transport 标签键控卡片渲染器新运行时的工具部件在添加专属卡片前会以通用卡片渲染。设计规则从 pi 集成中习得这些是没有机制强制的选择但违反它们会引入难以排查的策略漏洞Cherry 提示词策略是运行时中立的。每个驱动必须消费buildAgentRuntimePrompt()而不是自行组装 Cherry 策略。运行时可以提供原生的工作区/上下文机制但不得省略或另起炉灶地复刻指令权威、内置 Agent 解析、通道安全、引用/产物指南、响应语言。公共策略加在 materializer 中并测试每个驱动都携带它。运行时原生工具身份。各处保留运行时自己的工具名与大小写目录 id、disabledTools写回、批准查找。改名成其他运行时的约定会破坏策略查找。批准默认值随工具描述符存放。一张表携带 name category approval用?? auto回退的旁路查找意味着新加的工具会静默变成自动批准fail-open。凭据绝不进入运行时配置。若运行时持久化或插值其配置env 展开、$VAR语法写入占位符并在运行时通过 SDK 的 auth API 注入真实密钥。密钥按连接轮换而非按校验轮换。按信任类进行 fail-closed 资源发现。在 Cherry 具备显式信任流程之前不要让运行时自动导入用户全局资源或工作区可执行/代码资源扩展、技能、提示词文件。用户手工挑选工作区即已背书的文本资源如AGENTS.md/CLAUDE.md等上下文文件可以加载——pi 就是这么做的与 claude 驱动的project来源对齐。分界线画在信任类上而不是全部工作区资源整体放宽运行时的no*标志正是需要防范的回归。具体执行模式见 Agent Session Runtime 的 pi driver resource boundary 一节。权限姿态匹配信任根。claude-code默认auto由其 SDK 代理工具执行进程内运行时仅在自动写入被限制在用户选定的规范根目录内时才默认acceptEditsshell、外部路径、第三方工具、符号链接逃逸、Cherry 要求批准的变更必须保持门控。Resume token 对宿主不透明但对你不透明。持久化一个稳定的运行时 id 作为恢复句柄并在打开时于 Cherry 拥有的会话目录下解析它绝不持久化绝对路径——因为 DB 存储的路径会把该目录永久钉死。使用句柄定位会话文件前先校验它。验证改动完成后依次执行pnpm test——包含注册表配对测试与描述符不变量测试pnpm lint——格式、类型检查与 i18n 检查pnpm build:check——针对这种跨进程的宽泛改动手动冒烟创建新类型的 agent选择器显示标签→ 打开会话 → 运行一个带变更工具的回合批准提示出现→ 发送回合中 follow-up按你的redirect支持触发 steer 或排队→ 重启应用并恢复会话。小结新增一个 Agent 运行时在 Cherry Studio 中是一条清晰、被测试守护的路径共享层扩展AGENT_TYPES元组并补一份AGENT_RUNTIME_CAPABILITIES描述符主进程侧按 types.ts 契约实现驱动、连接、提示词适配器与流适配器并在 registerDrivers.ts 注册最后补齐 i18n 并遵守七条设计规则。宿主与渲染层无需任何改动——这正是描述符驱动架构的收益所在。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio 添加 Agent 运行时Runtime完整指南能力描述符 主进程 Driver 的实操清单Cherry Studio 添加 Agent 运行时Runtime完整指南能力描述符 主进程 Driver 的实操清单 本篇指南系统讲解在 CherrAI 应用大模型桌面应用本地部署RAGCherry Studio Agent 自主能力实战cron 定时调度、notify 主动通知与 config 渠道配置Cherry Studio Agent 自主能力实战cron 定时调度、notify 主动通知与 config 渠道配置 本指南讲解 Cherry Studi人工智能大模型AI 应用交互助手本地部署Cherry Studio 的 Cherry Tool Guide内置工具路由、捆绑运行时与 Agent 能力边界全解Cherry Studio 的 Cherry Tool Guide内置工具路由、捆绑运行时与 Agent 能力边界全解 Cherry Studio 面向具备人工智能大模型AI 应用交互助手本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考