专家套件（Plugin）

本文说明 百度搭子 套件（Plugin）的结构、编写方式、测试方法和安全要求，供开发者参考。

套件是面向垂直场景的能力包：它通过入口智能体(Agent)定义场景角色和标准流程，用多个技能(Skill)承载具体能力，并可声明依赖的连接应用（Connector）。

适用对象

• 想为 百度搭子 专家套件的开发者
• 需要组合多个技能、定义统一标准流程或安全边界的开发者
• 需要引用连接应用或接入外部服务的开发者
• 需要调整入口智能体、技能清单或测试用例的开发者

最小结构

最小结构如下：

1customer-support-expert/
2├── .claude-plugin/
3│   └── plugin.json
4└── agents/
5    └── customer-support-expert.md

如果套件包含技能，推荐结构如下：

1customer-support-expert/
2├── .claude-plugin/
3│   └── plugin.json
4├── agents/
5│   └── customer-support-expert.md
6├── skills/
7│   ├── ticket-triage/
8│   │   ├── SKILL.md
9│   │   └── tests/
10│   │       └── cases.json
11│   └── reply-draft/
12│       ├── SKILL.md
13│       └── tests/
14│           └── cases.json
15└── README.md

可选目录如下：

• skills/：存放套件内技能
• 技能下的 scripts/：存放确定性脚本，例如数据校验、格式转换、接口调用
• 技能下的 references/：存放静态参考资料，例如长文档、接口说明、业务规则
• 技能下的 assets/：存放图标、模板和其他静态资源
• README.md：面向开发者和评审人员说明套件的目标、依赖和验证方式

命名规则：

• 套件目录名和 plugin.json.name 使用小写 kebab-case，并保持一致
• 技能目录名、SKILL.md 的 name 与 agents[].skills 声明保持一致
• 入口智能体文件名建议与套件名称一致
• 机器标识不使用空格、中文或下划线

编写 plugin.json

plugin.json 是套件的核心配置文件，它同时承担“入口声明”和“能力清单”两种作用。

先写 name 和 description

• name 建议用 kebab-case，例如 customer-support-expert，并与文件夹名保持一致。
• description 决定开发者和平台能否正确理解这个套件的适用场景与边界。

推荐公式：

1[面向谁、解决什么场景] + [串联哪些工作] + [帮助用户得到什么结果]。

写法原则：

• 聚焦一个垂直场景，不写“万能助手”“处理所有任务”等泛化描述
• 写清服务对象、核心能力和边界
• 使用面向用户的业务语言，不用内部实现术语

示例：

1{
2  "description": "面向客服场景，串联工单理解、问题分级和回复草拟，帮助客服人员提升处理效率与回复一致性。"
3}

配置清单示例

1{
2  "name": "customer-support-expert",
3  "displayName": "客服专家",
4  "version": "1.0.0",
5  "description": "面向客服场景，串联工单理解、问题分级和回复草拟，帮助客服人员提升处理效率与回复一致性。",
6  "author": {
7    "name": "DuMate"
8  },
9  "license": "UNLICENSED",
10  "keywords": ["customer-support", "ticket", "reply"],
11  "defaultEnabled": true,
12  "entry": "customer-support-expert",
13  "agents": [
14    {
15      "name": "customer-support-expert",
16      "displayName": "客服专家",
17      "description": "辅助客服人员理解工单、草拟回复并识别升级风险。",
18      "mode": "primary",
19      "prompt": "./agents/customer-support-expert.md",
20      "skills": ["ticket-triage", "reply-draft"],
21      "mcpServers": [],
22      "connectors": []
23    }
24  ],
25  "skills": "./skills/"
26}

字段说明：

说明：entry 必须能在 agents[].name 中找到；每个 prompt 和技能路径必须真实存在。不要在 plugin.json 中写入访问令牌、浏览器登录信息、接口密钥、密码或本地凭证路径，也不要依赖 tools 或 permission 字段实施安全控制。

编写入口智能体文件

agent.md 负责定义套件挂载后的工作方式。它是场景级行为规范，应写明角色、边界、整体标准流程和能力路由；具体接口参数、脚本细节和局部执行步骤放到对应技能中。

推荐结构：

1# 客服专家
2
3你是「客服专家」，服务对象是客服人员和运营人员，目标是辅助他们完成工单理解、回复草拟和升级风险识别。
4
5## 能力边界
6
7- 支持：工单摘要、问题分类、回复草拟、升级建议。
8- 不支持：直接发送回复、承诺赔付、修改用户账户数据。
9- 高风险：涉及退款、封禁、隐私数据或法律争议时，必须提醒人工核验；执行外部写操作前必须获得用户确认。
10
11## 工作原则
12
13- 先判断任务类型，再选择完成任务所需的最少技能。
14- 只基于用户提供或可验证的信息输出，不编造政策、来源和执行结果。
15- 信息不足时，只追问完成任务必需的信息。
16
17## 可用能力与调用时机
18
19- `ticket-triage`：需要识别工单类型、优先级和风险等级时使用。
20- `reply-draft`：需要基于已确认事实草拟用户回复时使用。
21
22## 标准流程
23
241. 确认用户目标、输入材料和期望输出。
252. 判断任务类型、信息完整性和风险等级。
263. 选择一个或最少组合的技能；有依赖时按顺序调用。
274. 核对事实、引用、风险和跨技能冲突。
285. 输出统一结果，不直接拼接多个技能的原始输出。
29
30## 安全红线
31
32- 不直接执行账号、订单或资金类写操作。
33- 不承诺超出政策范围的赔付或处理时效。
34- 不输出用户隐私、凭证或内部日志。

编写建议：

• 用祈使句，直接说明智能体要做什么
• 能并行的工作分开写；有依赖的工作明确先后顺序
• 高风险操作必须写清“展示完整内容并等待用户确认”
• 列出每个技能的调用时机，避免多个技能抢同一入口
• 不要把大量脚本参数、接口字段堆进 agent.md

写好降级策略

如果套件或其技能依赖连接应用或外部服务，就要提前写好降级逻辑。连接应用当前只是依赖声明，不会自动连接或完成配置，也不保证运行时可用。

常见的三种方式：

处理规则：

• 能替代就降级
• 只能部分完成就部分返回
• 有风险的写操作、发送、删除和鉴权失败就停止

给出例子

至少提供 1 个完整示例，建议覆盖主流程和边界情况。

1## 示例
2
3**用户**：帮我看看这张工单需要怎么回复：客户说已经三天无法登录，并要求退款。
4
5**DuMate**：
61. 工单类型：登录异常，包含退款诉求。
72. 风险等级：高。退款属于资金类动作，需人工核验订单、故障范围和退款政策。
83. 建议回复草稿：很抱歉影响您的使用。我们正在核查登录异常原因，并会在确认后第一时间同步处理进展。关于退款诉求，需要先核验订单和服务状态后由专员为您处理。
94. 下一步：如需实际发送回复或处理退款，先展示操作内容并等待确认。

编写 tests/cases.json

套件本身当前没有统一的 cases.json 格式规范。套件中的每个技能都应在 skills/<skill-name>/tests/cases.json 中验证两个问题：

1. 这个技能该不该触发
2. 触发后做得对不对

推荐结构如下：

1{
2  "skill": "ticket-triage",
3  "version": "1.0.0",
4  "test_cases": [
5    {
6      "id": "TC001",
7      "name": "标准输入",
8      "category": "happy_path",
9      "input": {
10        "user_message": "客户无法登录，帮我判断这个工单要怎么处理"
11      },
12      "expected": {
13        "trigger_skill": true,
14        "output_contains": ["工单类型", "风险等级"]
15      }
16    },
17    {
18      "id": "TC002",
19      "name": "负向场景",
20      "category": "negative",
21      "input": {
22        "user_message": "帮我写一份产品周报"
23      },
24      "expected": {
25        "trigger_skill": false
26      }
27    }
28  ]
29}

建议每个技能至少包含：

• happy_path（正常流程）
• negative（负向场景）

如果涉及写操作，再补上：

• 用户确认后执行
• 用户拒绝时不执行

如果依赖外部工具或连接应用，再补上：

• 工具可用时的增强路径
• 工具或连接应用不可用时的降级路径

常用断言字段：

套件结构与挂载验证

除技能用例外，提交前还要验证：

1. .claude-plugin/plugin.json 存在且 JSON 格式正确
2. plugin.json.name 与目录名一致，entry 能在 agents[] 中找到
3. agents[].prompt 和 agents[].skills 指向的文件真实存在
4. 所有技能的 YAML 元数据 name 与目录和配置清单声明一致
5. 平台可正常扫描套件，并将套件内技能注册到技能列表
6. 套件未挂载时，套件内技能不出现在可用技能列表中；挂载后，入口 agent.md 生效且套件内技能可用
7. 多套件场景下，当前运行时仅为第一个挂载的套件注入入口 agent.md
8. 沙箱模式下，套件信息可通过启动信息正常传入和读取

工具接入与复杂流程

当套件只需要组织角色、标准流程和文本型技能时，尽量保持简单。

如果需要接入外部服务，应先将连接应用上架，再在 plugin.json 中声明引用；具体工具调用、确认和降级逻辑写在对应技能中。

什么时候写脚本

• 需要确定性输出
• 操作有副作用
• 处理顺序不能错
• 逻辑太长，模型容易写偏

什么时候保持自然语言

• 只要阅读、总结或草拟
• 只要轻量判断或场景路由
• 结果不依赖精确流程

组件分工

注意：不要依赖随套件打包的本地连接服务、.mcp.json 或子智能体作为发布必需能力。连接应用的标识和配置以平台上架及校验结果为准。

安全与合规

发布时，优先保证可验证、可回退、最小权限。

原则：

• 只处理完成任务必须的数据
• 不要暴露密码、访问令牌、浏览器登录信息、接口密钥、手机号、身份证号、邮箱等敏感信息
• 不把用户私有数据或本地凭证文件写入套件目录或发布包
• 向外部系统写入、发送、删除、发布、付费或执行不可逆操作时先确认
• 不要虚构来源、结果、授权状态或执行记录
• 涉及隐私、财务、医疗、法律、教育等内容时要更谨慎，并提示专业核验
• 所有需要持久化的配置和状态写入 $XDG_CONFIG_HOME

如果外部服务不可用，宁可明确说明，也不要编造结果。

如果需要外部授权，请使用平台提供的连接应用或标准凭证方案，不要在 plugin.json、agent.md、SKILL.md、示例、错误提示或日志中暴露密钥、凭证路径或其他敏感实现细节。

开发流程

建议顺序：

1. 先定义单一场景、目标用户和业务目标
2. 再明确支持范围、不支持范围和高风险操作
3. 再拆分技能，并定义每个技能的触发时机
4. 再写 plugin.json
5. 再补 agent.md
6. 再完成各技能的 SKILL.md 和 tests/cases.json
7. 最后补充连接应用依赖、降级策略、README.md 和验证记录

发布前检查清单

• 套件目录名、plugin.json.name 和入口智能体名称一致
• description 写清场景、服务对象和边界，没有“万能助手”等泛化描述
• entry 能在 agents[] 中找到，prompt 路径真实存在
• agent.md 有清晰的角色、能力边界、技能路由、标准流程和安全红线
• agents[].skills 只包含真实存在的套件内技能
• 每个技能的 name、目录名和配置清单声明一致
• 每个技能至少有一个正常流程（happy_path）用例和一个负向场景（negative）用例
• 涉及写操作时有确认流程，并覆盖拒绝时不执行
• 依赖连接应用或外部服务时写了降级策略
• 不依赖当前一期不支持的套件内置本地连接服务或子智能体
• JSON 和 Markdown 格式可解析，路径未越过套件根目录
• 套件挂载前后，入口提示词和套件内技能的可用状态符合预期
• 输出不会泄露敏感信息，发布包不包含凭证、隐私数据、缓存或临时文件