清单驱动Cherry Studio 内置 Cherry Assistant 的产品信息查询、导航与诊断机制解析【免费下载链接】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本指南围绕 Cherry Studio 内置 Agent Cherry Assistant 的cherry-assistant-guide技能即 skill-zh-cn-template.md展开讲解其以当前安装包清单为唯一事实来源的产品问答设计Agent 如何通过product_info读取随包生成的product-manifest.json、如何用navigate生成可点击导航入口、以及如何用diagnose排查运行问题。读完本文你将掌握这套清单驱动manifest-driven知识管线的完整调用链、回答约束与源码实现依据。一、为什么 Cherry Assistant 不背产品知识传统内置助手回答产品问题时往往依赖训练数据或手写 FAQ。这种方式在桌面应用迭代中会产生两个致命问题旧版本经验被当作当前事实、文档与代码不同步。cherry-assistant-guide的第一条原则即对此做了硬性约束不要凭训练数据、记忆或本文件中的旧描述回答 Cherry Studio 产品问题。每个独立的产品问题都先读取当前安装包信息。也就是说该技能文件本身刻意不包含任何具体的路由表、快捷键表、Provider 列表。这一点在测试中也有明确验证guide.test.ts 断言指南中不得包含## 路由表、## 常见问题、## 功能速查、## 快捷键、## 日志路径这类陈旧小节并且不得硬编码/app/、/settings/等应用路由见该文件第 50–57 行。凡是版本相关的产品事实一律在运行时从当前安装包读取。二、核心数据源随包生成的 product-manifest.json指南中反复出现的mcp__assistant__product_info({ source: manifest, ... })指向的是随当前构建生成并打包的product-manifest.json而不是手写版本知识。它的生成逻辑位于 generators/manifest.ts结构如下Section数据来源源码/配置文件内容说明packagepackage.json应用名、版本号、描述、主页routes.primarysidebar.ts 中的SIDEBAR_APPS定义主导航入口id 路由前缀routes.allrouteTree.gen.ts 的FileRoutesByFullPath全部路由含内部页、参数路由、兼容跳转commandsdefinitions.ts 的COMMAND_DEFINITIONS命令 ID、标题/分类 key、作用域、默认快捷键providersproviders.jsonProvider 注册表版本、数量、id 与名称localeslanguages.ts 的appLanguageOptions支持的语言value/label/flagagentsagentChannels.ts、jobs.ts、CodeCli枚举频道类型、定时任务触发类型、Code CLI 路由与工具features上下文设置、MCP 类型、知识库扩展名等共享常量上下文默认值/阈值、MCP server 类型、知识库支持的文件扩展名该清单是在构建时从当前源码注册表机械化生成的因此任何一次构建产出的清单都严格对应当前版本。生成入口脚本为 index.ts它会同时产出product-manifest.json、SKILL.md由模板拷贝而来、cherry-assistant/agent.json与cherry-support/agent.json四份运行时产物。三、product_info按 section 精确读取清单3.1 标准用法指南规定按问题类型直接读取对应 section路由 / 页面入口mcp__assistant__product_info({ source: manifest, section: routes }) 快捷键mcp__assistant__product_info({ source: manifest, section: commands }) Providermcp__assistant__product_info({ source: manifest, section: providers }) 语言mcp__assistant__product_info({ source: manifest, section: locales }) Agent / 频道 / 定时任务 / Code CLImcp__assistant__product_info({ source: manifest, section: agents })3.2 紧凑索引如果不知道应该查哪个 section先调用不带 section 的紧凑索引mcp__assistant__product_info({ source: manifest })索引只返回当前版本号和可用 section 名称用于引导下一步读取之后再按需读取相关 section。指南明确告诫只有一个问题确实横跨多个 section 时才使用section: all不要为省一次调用把整份清单放进上下文——这是出于上下文context window经济性的考虑。3.3 服务端实现细节服务端实现位于 assistant.ts。product_info工具的关键行为第 426–462 行source参数的枚举只有manifest传入其他值直接报Unknown product_info source读取 manifest 时会校验schemaVersion 1且package.version非空否则视为Product manifest schema is invalid第 399–405 行未传section时返回{ runtimeVersion, manifestVersion, sections }其中runtimeVersion来自app.getVersion()运行时实际版本manifestVersion来自清单内记录的版本——两个版本对照可发现包与清单是否一致传section: all时返回整份清单传具体 section 时只返回该 section 数据未知 section 报错。工具描述第 126–147 行要求只请求相关 section 以保持上下文精简与指南的节流原则一致。四、回答规则的硬约束指南给出了 5 条回答规则逐条约束 Agent 的事实边界只把返回清单中存在的内容表述为当前版本事实——清单里没有的就不能说有。routes.primary是主导航入口routes.all还可能包含内部页、参数路由或兼容跳转不能无条件推荐。providers只表示随包支持的 Provider用户实际配置或启用状态须另用mcp__assistant__diagnose的 Provider 诊断能力查询——即包支持与用户已启用是两个不同维度。默认快捷键来自当前包定义不代表用户没有自定义覆盖——UI 允许用户改快捷键包里的默认值只是出厂状态。清单未暴露的能力必须明确说当前包清单未提供该信息再按需查官方文档不得补写旧版本经验。这 5 条共同构成了 Agent 回答的证据链能引清单的引清单清单覆盖不到的就明说绝不脑补。五、navigate导航必须是同轮生成的可点击入口凡是涉及去哪里找、打开、配置或使用某个页面的问题包括我去哪里配置找不到入口这类含蓄问法指南要求先从当前包清单选择有效路径必须在同一轮调用mcp__assistant__navigate并把生成的可点击入口放在手动操作步骤之前不能等用户再次提醒。服务端实现进一步解释了两个关键语义不自动导航只生成入口navigate实际执行的是创建可点击入口日志输出Navigate link created: {path}第 491–497 行由渲染层把入口呈现给用户点击。因此指南强调只有导航工具成功后才能告诉用户点击生成的入口、工具未调用或失败时不得声称已经生成入口或已经打开页面。路径白名单校验navigate只允许product_info返回清单中、且以/settings、/app开头的路由第 409–424 行的getManifestNavigationRoutes再经 navigationPath.ts 的isAllowedNavigationPath做逐段匹配。该校验支持$与$param形式的参数占位符第 17–27 行同时拒绝包含?、#、\、.、..的路径从机制上杜绝了把 Agent 导向清单外路径的可能。navigate还支持通过query传入 URL 查询参数如{ id: anthropic }拼装完整路径。六、diagnose运行问题排查的只读探针用户报告运行错误、连接失败、配置异常时使用mcp__assistant__diagnose。该工具通过action参数选择诊断能力第 583–607 行action用途实现要点info应用版本/路径/系统信息返回 app 版本、userData/logs/temp 路径、Node/Electron/Chrome/V8 版本、平台架构与内存/CPUproviders已配置的 Provider 列表汇总 authType、endpoints、defaultChatEndpoint、是否配置 API Key、是否启用health测试 Provider 连通性对 API host 发 HEAD 请求401/403也视为可达结果按 Provider 缓存 30 秒HEALTH_CACHE_TTL 30_000见第 281 行logs读取最近日志取最新.log文件尾部默认 50 行、上限 500 行errors提取 ERROR/WARN 条目扫描最近最多 3 个日志文件上限 200 条mcp_status检查 MCP server 状态列出 server 的 id/name/type/isActive/command/baseUrlbaseUrl 会脱敏到 originread_source只读读取源码/目录见下方安全边界config读取用户设置语言、主题、代理脱敏、缩放、默认/快捷模型、托盘、自动更新等两个值得注意的安全设计逐次授权指南要求这些数据来自用户设备调用前保留逐次授权诊断动作不隐式越权。read_source 的安全边界第 1009–1090 行路径必须解析到 app 根目录或node_modules内先 realpath 解析符号链接防止 symlink 逃逸文件名匹配.env*除.env.example、.pem/.key/.p12/.pfx或credentials.json、id_rsa等密钥文件的直接拒绝isBlockedSourceFile第 35–41 行单文件超过 200KB 拒读防止 token 爆炸。这些行为有对应回归测试覆盖见 assistant.test.ts例如对product_info契约、read_source敏感文件黑名单的断言。七、信息优先级与冲突处理指南将信息来源的优先级固化为当前安装包清单当前版本具备什么、入口在哪里、默认值是什么。Cherry Studio 官方文档清单未覆盖的详细用法和版本变化。冲突时当前安装包清单优先于旧文档和模型记忆。同时明确清单不包含版本历史无法从官方资料核实时不得编造更新内容。配套的长期记忆文件 FACT.md 也声明产品知识一律通过cherry-assistant-guide技能查询当前包清单不要在这里重复产品事实否则会悄悄过时——这解释了整个知识架构为何是运行时读取而非静态沉淀。八、模板与产物如何维护这套技能cherry-assistant-guide采用模板即源、产物可校验的维护模式模板skill-zh-cn-template.md 是唯一需要编辑的源文件文件头注释明确本文件SKILL.md由模板生成不要直接编辑产物。生成运行pnpm build:builtin-knowledge见 index.ts将模板原样拷贝为 SKILL.md同时重新生成 manifest 与两个 agent 的agent.json。校验CI 中通过pnpm build:builtin-knowledge:check逐字节比对产物与期望内容不一致即失败退出第 55–70 行保证提交到仓库的产物永远与模板/源码同步。九、小结cherry-assistant-guide的核心设计可以概括为三句话版本事实来自随包清单导航入口来自同轮生成的受控跳转运行诊断来自带安全边界的只读探针。它通过构建时从源码机械化生成 manifest 运行时按需读取 测试锁定契约的组合让内置 Agent 在不引入陈旧知识的前提下始终能回答与当前安装包一致的产品问题。这套清单驱动模式也可作为其他桌面应用内置 AI 助手做产品知识治理的参考范式。【免费下载链接】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），仅供参考