第 7 章 专家解剖：一个带 UI 的 SubAgent 插件

专家中心是 WorkBuddy 最像应用商店的地方：满列专家排成列表（产品模板自述 100 余位），每人有头像、职业标签、一句简介，点进去还能看到三个快捷问题按钮。选一位「资讯速递专家」，对话框里的助手立刻换了人格、换了能力、换了说话方式。

这一章做一次完整解剖。解剖对象是本机安装的一位真实专家——「数字生命卡兹克」（AI 资讯速递）。我们会把它拆到文件级，看清「一位专家」在磁盘上的完整形态，然后观察它在运行时如何接管对话。结论先给：专家就是一个插件包，头像、开场白、快捷按钮全部是插件清单里的字段；对话开始时，专家的人设提示词注入主线程，替代通用助手人格。

读完本章，你应能说出专家插件的四件套结构、UI 元素与清单字段的对应关系，理解专家与专家团的区别，并知道装一位专家前该检查什么。

7.1 解剖台：一位专家的完整文件清单

在专家市场目录下，每位专家一个文件夹。卡兹克专家的全部家当是四个文件：

aihot/
├── .codebuddy-plugin/plugin.json   ← 插件清单（manifest）
├── agents/aihot.md                ← 人设提示词（核心）
├── skills/aihot/SKILL.md          ← 配套技能（干活方法）
└── avatars/expert.png             ← 头像

先看清单。plugin.json 里除了名称、版本、作者，有一组专家特有字段（节选自本机文件）：

{
  "name": "aihot",
  "agents": ["./agents/aihot.md"],
  "skills": ["./skills/aihot"],
  "expertType": "agent",
  "displayName": { "zh": "数字生命卡兹克", "en": "Kazik" },
  "profession": { "zh": "资讯速递专家", "en": "AI News Briefing Expert" },
  "defaultInitPrompt": { "zh": "今天 AI 圈有什么新动态？" },
  "quickPrompts": [
    { "zh": "今天 AI 圈有什么新动态？" },
    { "zh": "看一下最新的 AI 日报" },
    { "zh": "OpenAI 最近发布了什么？" }
  ],
  "avatar": "avatars/expert.png"
}

对照你在界面上看到的：头像 = avatar 字段指到的图片；职业标签 = profession；进入对话时预填的那句问话 = defaultInitPrompt；对话框上方的三个快捷按钮 = quickPrompts 数组。专家中心的每一格 UI，都能在这份清单里找到字段级对应。这就是「UI 按钮 → 本地文件」翻译法最完整的一个样本。

注意 expertType: "agent"——它声明这位专家是「单 Agent 型」。还存在另一种类型：Team 型（专家团），稍后讲。

图 7-1：专家四件套与 UI 字段映射。

7.2 人设提示词：专家的大脑

agents/aihot.md 是专家的本体，一份完整的系统提示词。结构分两段。开头是 frontmatter（YAML 元数据）：

---
name: aihot
description: AI 资讯速递专家，实时查询每天精选的 AI 动态。当用户提到 AI 资讯、AI 日报、AI 热点……时激活。
maxTurns: 30
---

description 不只是介绍——它写明了激活条件，什么话题会唤起这位专家；maxTurns: 30 限制这位专家单次对话最多转三十圈，防止失控。正文则是给模型的完整人设与工作规则：你是谁、核心能力五项、输出规范（默认生成 HTML 简报，给出配色、布局、分区要求；备选 Markdown 格式的规则）。

最有分量的是中间那段「技能调用声明」，原文风格是：收到 AI 资讯问题时必须调用配套技能获取实时数据，不得凭训练数据猜测当前动态。一份禁令加一份路由表（用户意图 → 技能里的哪个工作流）。这类强制条款的效果，马上会在运行时观测里看到。

7.3 运行时：接管是如何发生的

第 5 章讲过专家模式模板里那个 {{ PluginAgentPrompt }} 插槽，现在看它运行时被填充后的样子。在声明环境中做了一次受控实验：选择卡兹克专家，发送「今天 AI 圈有什么新动态」。会话文件的首条用户消息结构如下（已脱敏缩略）：

今天 AI 圈有什么新动态？

专家的人设文件被系统提醒通道完整注入。接下来模型的行为链值得逐帧看：推理记录原话是「根据专家指令，我必须调用 aihot 技能获取实时数据，不能凭训练数据猜测」——人设里的强制条款直接改写了模型的行为决策；随后它先找到并阅读技能文件，按里面的命令模板调用数据接口，拿到返回后按人设里的输出规范生成了 HTML 简报。

一次专家对话 = 清单字段渲染 UI + 人设注入 + 技能执行。没有魔法，全是文件。

图 7-2：专家接管的运行时链路。

7.4 专家团：编排层的另一形态

专家中心里还有一类「专家团」：多位专家加一套协作流程。官方文档的定义对比很清楚——技能是能力，专家是能力加经验，专家团是多位专家加协作。落到本地形态：Team 型专家的插件里同样有清单与人设，但工作方式是团长拆解任务、分派成员、并行执行、整合交付（官方文档专家中心页描述其积分消耗约为普通对话的三到五倍，适合复杂任务）。

单机文件层面能看到的入口有两处：专家模式工具白名单里的 Defer(TeamCreate) 与 Defer(TeamDelete)（团队创建与解散的延迟加载工具），以及插件市场里的团队协作类插件。专家团的多轮协作过程发生在运行时编排层，本机未留存完整的团队会话样本——这部分标注为官方定义加文件入口证据，协作细节留作读者实验。

7.5 另一位样本：带规则的专家

本机另有一位已下载的视频生成专家，结构与卡兹克同构，但多出一个值得研究的目录：rules/。规则文件的元数据写着 alwaysApply: true，正文以系统提醒形式包裹一段场景声明（「用户已选择视频生成场景」），随后是严格的工作流约束——第一步必须用选择工具与用户确认画幅、帧率、时长，规格未确认前禁止执行任何后续步骤。

把它与卡兹克对照，能看出专家设计的两种配方：卡兹克把全部约束写进人设提示词（agents 文件），随对话注入一次；视频专家则把「人设」与「常驻规则」拆开——人设管身份与能力，规则管不可违反的流程纪律。后者更适合高风险、多步骤的专家（视频渲染失败成本高，所以规格确认被设计成硬门槛）。装专家时看它有没有 rules 目录、写了什么，等于提前读到这位专家的「脾气」。

两个样本也划出了专家市场的现实边界：市场里的内容由各路作者生产，格式统一但质量与安全水位不齐——这正是下一章插件供应链话题的入口。

7.6 实战：装专家前检查三件事

专家是第三方内容，装之前花两分钟做尽职调查。按侵入度查三样：

一查注入面。打开专家的 agents/*.md，通读人设：它要求模型必须做什么、禁止做什么？有没有要求访问外部地址、发送数据？这段文本将进入你后续每次与它的对话。

二查能力面。看清单里的 skills 与 mcps（如果有）：技能文件里有没有下载可执行内容、要求输入密钥的步骤？能力越强，越要确认来源可信。

三查来源。清单里的作者、版本、主页字段是否完整；市场里的发布者是否官方或可追溯。本机实测的专家样本来自个人作者，内容质量高，但这恰恰说明这个市场走的是社区生态模式——信任决策在你，机制只负责分发。

7.7 边界

本章边界：解剖样本为专家市场两位本机专家之一，样本量小，不声称覆盖全部专家形态（比如 Team 型专家的完整文件结构未取得样本）；「每一格 UI 对应清单字段」的映射基于 5.3.13 实测的字段集合；运行时证据来自单次受控会话，行为稳定性未做统计。

下一章从单个专家拉远到整个插件系统：市场怎么分发、插件怎么登记、规则怎么注入——以及为什么说插件是 Harness 供应链的入口。