看完这篇教程，你将能够：理解 WorkBuddy Agent（专家）和 Skill（技能）的区别、掌握 Agent 的完整文件结构、学会两种创建模式（交互式 & 资料转化式）、写出一个真正能用的 Agent，并在使用中持续迭代优化它。

全程实战：我们最后会一起做一个「周报撰写专家」Agent —— 让 WorkBuddy 化身你的周报搭子，帮你把零散的工作记录变成结构清晰、重点突出的周报。

---

一、先搞清楚：Agent 和 Skill 到底是什么关系？

1.1 一个直觉类比

想象你开了一家公司，需要招人：

概念	类比	本质
WorkBuddy 本体	一个什么都会的通才员工	默认的 AI 助手
Skill（技能）	一份岗位操作手册（SOP）	教 Agent "怎么做某件事"的 Markdown 说明书
Agent（专家）	一位带着简历和手册来上班的专员	有身份、有头像、有专属知识的 AI 角色

关键关系：

• Skill 是"说明书"，Agent 是"人"
• 一个 Agent 可以附带多个 Skill（一个人可以掌握多本操作手册）
• 也可以不附带任何 Skill，纯靠 Agent MD 里的指令工作（一个人凭经验干活）
• Skill 可以独立存在，被任何 Agent 按需加载；Agent 是独立的人格实体

1.2 你该选哪个？

你的需求	选择	原因
只想让 AI 按固定模板写周报	Skill 就够了	不需要人格，只要流程
想要一个"周报顾问"，有自己的人设、问候语、推荐提问	Agent	需要独立身份和展示
想让 AI 帮你读论文并做笔记	Skill 就够了	单一任务，不需要人格
想要一个"学术研究助手"，能读论文、查文献、写综述	Agent + Skill	需要人格 + 多种能力

🎯 本文聚焦 Agent 创建。如果你只需要 Skill，参考 WorkBuddy 官方文档中 Skill 的部分即可。

1.3 Agent 在 WorkBuddy 里的生命周期

创建 → 校验 → 注册 → 使用 → 迭代优化 → （可选）打包分享
 ↑                                              │
 └──────────── 反馈循环 ─────────────────────────┘

这篇文章会带你走完整个循环。

---

二、Agent 的文件结构（一张图看懂）

2.1 目录全景

my-expert/                         # 专家文件夹（英文小写 + 连字符）
├── .codebuddy-plugin/
│   └── plugin.json                # 【必需】身份证：名称、职业、展示信息
├── agents/
│   └── my-expert.md               # 【必需】大脑：角色定义 + 工作流程 + 输出规范
├── avatars/
│   └── expert.png                 # 【可选】头像（512×512，≤500KB）
├── skills/                        # 【可选】附带的技能包
│   └── my-skill/
│       └── SKILL.md
├── bin/                           # 【可选】工具脚本
│   └── helper.sh
└── templates/                     # 【可选】模板文件
    └── report-template.md

2.2 两个必需文件的分工

新手最常搞混的就是 plugin.json 和 Agent MD 各自管什么。记住一句话：

plugin.json 管"是谁"，Agent MD 管"怎么干"。

维度	plugin.json	Agent MD
比喻	简历首页	岗位手册
决定什么	专家中心的展示卡片	被激活后的行为逻辑
必需字段	name, expertType, agentName, displayName, profession, displayDescription, categoryId, tags, quickPrompts	name, description, displayName, profession, maxTurns
用户能看到？	✅ 展示在专家中心	❌ 用户看不到，只有 AI 读
写错了的后果	找不到专家 / 展示异常	专家行为不对 / 不会干活

2.3 plugin.json 核心字段速查

字段	类型	说明	易错点
name	string	唯一标识，小写+连字符	❌ 不能用中文、大写、下划线
version	string	语义化版本号	如 1.0.0
description	string	英文一句话描述	用于搜索，要写清楚
expertType	string	"agent" 或 "team"	单角色 = agent，多角色 = team
agentName	string	主 Agent 名称	必须与 MD 文件名一致（不含 .md）
agents	string[]	Agent MD 路径数组	如 ["./agents/my-expert.md"]
displayName	{en, zh}	展示名称	双语，卡片标题
profession	{en, zh}	职业头衔	Team 型须与 displayName 一致
displayDescription	{en, zh}	能力介绍	中文必须 40-50 字
categoryId	string	行业分类 ID	从标准分类表选
tags	{en, zh}[]	擅长标签	固定 3 个，多了少了都报错
quickPrompts	{en, zh}[]	推荐提问	固定 3 个，第一条 = defaultInitPrompt
defaultInitPrompt	{en, zh}	默认引导语	必须与 quickPrompts[0] 一致
avatar	string	头像路径	相对路径，如 avatars/expert.png
plugin	string	插件标识	值与 name 相同

⚠️ 铁律：name、agentName、专家目录名、MD 文件名这四者必须能对上号。比如 name: "weekly-report" → 目录 weekly-report/ → agentName: "weekly-report" → agents/weekly-report.md。

2.4 Agent MD 的 frontmatter

---
name: weekly-report          # 与文件名一致，有业务语义
description: English description for AI activation
displayName:
  en: "English Name"
  zh: "中文名称"
profession:
  en: "English Profession"
  zh: "中文职业头衔"
maxTurns: 50                 # 默认50，复杂任务可调高
---

⚠️ frontmatter 中禁止声明 tools 字段。所有工具权限由系统统一分配。

2.5 Agent MD 的正文结构

# {角色名称} - {人名}

{一段话角色描述：这是谁，擅长什么，什么风格}

## 核心能力
1. **{能力1}**：{描述}
2. **{能力2}**：{描述}
3. **{能力3}**：{描述}

## 工作流程
1. {步骤1}
2. {步骤2}
3. {步骤3}

## 输出规范
- {规范1}
- {规范2}

## 注意事项
- {约束或边界条件}

2.6 存放在哪里？

类型	路径	适用场景
个人级	~/.workbuddy/plugins/marketplaces/my-experts/plugins/	你所有项目都能用
项目级	随项目目录配置	团队共享，随项目分发

---

三、动手之前：7 个问题想清楚

比"6 个问题"多了一个——因为你还要决定"用哪种创建模式"。

1. 职业定位：这个 Agent 是什么"职业"？（“周报撰写专家” > “办公助手”）
2. 核心能力：它能帮你完成哪 3 件具体的事？（不超过 3 个，贪多嚼不烂）
3. 触发场景：用户带着什么问题来找它？会说什么话？
4. 领域知识：哪些信息是 Agent 不知道、必须你告诉它的？（模板、术语、规范）
5. 输出格式：产出物长什么样？（报告结构、表格、分段）
6. 行业分类：它属于哪个领域？（见下方分类表）
7. 创建模式：你是有现成资料要转化，还是从零描述需求？

行业分类表

categoryId	分类名称	categoryId	分类名称
01-ProductDesign	产品设计	07-SalesCommerce	销售商务
02-Engineering	技术工程	08-FinanceInvestment	金融投资
03-GameSpatial	游戏空间	09-OperationsHR	运营人力
04-DataAI	数据智能	10-ProjectQuality	项目质量
05-MarketingGrowth	营销增长	11-SecurityCompliance	法务安全
06-ContentCreative	内容创作	12-IndustryConsultant	行业顾问

💡 选择规则：看 Agent 的主要输出物属于哪个领域。周报属于运营人力 → 09-OperationsHR。

---

四、两种创建模式

WorkBuddy 支持两种创建 Agent 的方式，适用于不同的起点。

4.1 模式 A：交互式创建（从零开始）

适合：脑子里有想法，但没有现成资料。

直接在对话框里发这段话：

帮我创建一个 Agent（专家），需求如下：

1. 职业定位：周报撰写专家，帮我把零散工作记录变成高质量周报
2. 核心能力：
   - 从零散记录中提炼本周重点
   - 按STAR结构组织周报内容
   - 自动识别风险和下周计划
3. 触发场景：当我说"帮我写周报""整理一下这周的工作""周报"时使用
4. 领域知识：周报必须包含——本周进展、关键数据、遇到的问题、
   风险预警、下周计划；用STAR结构（情境-任务-行动-结果）描述进展
5. 输出格式：结构化周报，含表格和分段
6. 行业分类：运营人力（09-OperationsHR）
7. 名字：中文"周小报"，英文"Zoe"
8. 存放位置：个人级

4.2 模式 B：资料转化式创建（从现有材料开始）

适合：你已经有一段用顺手的提示词、一份 SOP 文档、或一个现成的工作模板。

直接把材料丢给 WorkBuddy：

帮我把以下材料转化成一个 Agent（专家）：

---材料开始---
你是一个周报撰写助手。当用户给你本周的工作记录时，你需要：

1. 将零散记录分类为：项目进展、会议沟通、行政事务
2. 每条进展用 STAR 格式重写（情境-任务-行动-结果）
3. 提取关键数据指标，做成表格
4. 识别潜在风险，标注严重程度（高/中/低）
5. 基于本周进展，建议下周 3-5 个重点事项
6. 输出格式：标题 → 本周概览 → 详细进展 → 数据看板 → 
   风险预警 → 下周计划

注意：语气要专业简洁，不要废话；数据必须有出处；
如果信息不足要主动追问。
---材料结束---

请按 WorkBuddy 专家规范转化，名字叫"周小报"，
分类选运营人力，存到个人级目录。

4.3 两种模式对比

维度	交互式	资料转化式
起点	描述需求	提供现成材料
适合	新场景、新想法	已有提示词/SOP/模板
WorkBuddy 做什么	追问细节 → 设计 → 生成	分析材料 → 推断 → 确认 → 生成
你的工作量	回答追问	确认推断结果
产出质量	取决于需求描述的清晰度	取决于原材料的质量

4.4 WorkBuddy 的创建流程（两种模式通用）

阶段	WorkBuddy 做的事	你做的事
① 信息收集	追问不清的细节 / 分析材料提取信息	如实回答 / 确认推断
② 设计	起草名称、描述、标签、分类	看一眼是否贴合意图
③ 初始化	创建目录结构	无需动手
④ 生成内容	写 plugin.json + Agent MD	无需动手
⑤ 生成头像	自动生成头像图片	可后续替换
⑥ 校验	检查格式、字段完整性	无需动手
⑦ 注册	写入 marketplace.json	无需动手
⑧ 通知完成	告诉你去专家中心看看	去验证！

4.5 人机协作的黄金分工

你负责	WorkBuddy 负责
业务知识（周报该写什么）	格式规范（plugin.json 语法）
验收结果（输出对不对）	文件创建、校验、注册
迭代反馈（哪里不好用）	修改文件、重新注册

---

五、Agent MD 写作逻辑（核心章节）

5.1 Frontmatter 的三条黄金法则

法则一：description 用英文、第三人称

# ✅ 好
description: Writes structured weekly reports from scattered work notes, organizing progress with STAR framework, highlighting risks, and suggesting next-week priorities.

# ❌ 坏
description: I can help you write weekly reports
description: 你可以用我来写周报

法则二：description 要具体 + 带触发词

# ✅ 好：能力具体，场景清晰
description: Writes structured weekly reports from scattered work notes using STAR framework. Use when the user mentions weekly reports, work summaries, progress updates, or asks to organize weekly work.

# ❌ 坏：太模糊
description: Helps with office writing

法则三：description 既写 WHAT 也写 WHEN

• WHAT：能干什么（具体能力）
• WHEN：什么时候用（触发场景）

5.2 正文写作的四条核心原则

原则一：只写 Agent 不知道的东西

# ❌ 啰嗦（Agent 不需要你教它什么是周报）
## 什么是周报
周报是职场中常见的汇报形式，通常每周提交一次，用于向上级
汇报本周工作进展......（此处省略 300 字废话）

# ✅ 简洁（直接给框架和指令）
## 周报结构
按以下结构组织：
1. 本周概览（3-5 句话总结）
2. 详细进展（每条用 STAR 格式）
3. 数据看板（关键指标表格）
4. 风险预警（高/中/低标注）
5. 下周计划（3-5 个重点）

原则二：正文控制在 200 行以内

太长拖性能。超出的内容拆到 skills/ 或 templates/ 中，Agent 按需加载。

原则三：给合适的自由度

自由度	形式	适用场景	举例
高	纯文字说明	有多种合理写法	周报语气调整、措辞润色
中	模板 + 说明	有推荐格式但允许变化	STAR 结构、数据表格
低	精确模板	必须严格一致	周报标题格式、表格列名

原则四：明确约束，防幻觉

## 注意事项
- 不得编造数据，所有数字必须来自用户提供的信息
- 信息不足时主动追问，不要"猜"
- 风险预警必须有依据，不要危言耸听
- 下周计划要具体可执行，不要写"继续推进"这种废话

5.3 五种正文写作模式

模式一：模板模式 —— 固定输出格式

## 输出模板

# 周报 | {姓名} | {日期范围}

## 一、本周概览
{3-5 句话总结本周核心进展}

## 二、详细进展
### 项目A：{项目名}
- **情境**：{背景}
- **任务**：{要做什么}
- **行动**：{做了什么}
- **结果**：{产出/数据}

## 三、数据看板
| 指标 | 本周 | 上周 | 变化 |
|------|------|------|------|
| ... | ... | ... | ... |

## 四、风险预警
| 风险项 | 严重程度 | 应对建议 |
|--------|---------|---------|
| ... | 高/中/低 | ... |

## 五、下周计划
1. {重点事项1}
2. {重点事项2}
3. {重点事项3}

模式二：示例模式 —— 用好例子教 Agent

## 示例

**输入**：本周做了这些事——改了登录bug、开了3次需求评审会、
上线了v2.1版本、处理了5个用户反馈

**输出**：
# 周报 | 张三 | 2024.01.15-01.19

## 一、本周概览
本周完成 v2.1 版本上线，修复登录模块关键缺陷，
推进 3 项需求评审，处理用户反馈闭环。

## 二、详细进展
### v2.1 版本上线
- **情境**：v2.1 计划本周二上线
- **任务**：完成上线部署和验证
- **行动**：周二 14:00 执行部署，完成冒烟测试
- **结果**：16:00 上线成功，目前运行稳定
......

模式三：工作流模式 —— 拆步骤 + 清单

## 工作流程

复制此清单并跟踪进度：

- [ ] 第 1 步：收集用户本周工作记录
- [ ] 第 2 步：将记录分类（项目/会议/行政）
- [ ] 第 3 步：用 STAR 格式重写每条进展
- [ ] 第 4 步：提取关键数据做表格
- [ ] 第 5 步：识别风险并标注严重程度
- [ ] 第 6 步：基于进展建议下周计划
- [ ] 第 7 步：自检后输出完整周报

模式四：条件分支模式 —— 不同输入走不同流程

## 判断用户输入

**用户给了零散记录？** → 先分类整理，再按模板生成
**用户给了已经整理好的要点？** → 直接进入 STAR 重写
**用户只给了一句话"这周没啥事"？** → 追问具体做了什么
**用户要改上周的周报？** → 读取上周周报，按修改意见调整

模式五：反馈循环模式 —— 自检后输出

## 输出前自检

输出周报前，检查以下清单：
- [ ] 五个板块齐全（概览/进展/数据/风险/计划）
- [ ] 每条进展都有 STAR 四要素
- [ ] 数据表格有本周和上周对比
- [ ] 风险预警标注了严重程度
- [ ] 下周计划有 3-5 个具体事项
- [ ] 没有编造的数据

不通过 → 修正后再输出
通过 → 输出完整周报

5.4 六个反面教材

反模式	❌ 错误示范	✅ 正确做法
name 用中文	name: 周报专家	name: weekly-report
name 太笼统	name: helper	name: weekly-report
description 模糊	description: Helps with writing	description: Writes structured weekly reports from scattered work notes using STAR framework
frontmatter 声明 tools	tools: [read, write]	删掉，系统自动分配
正文废话多	花 3 段解释什么是 STAR	直接给模板和示例
tags 数量不对	写了 5 个标签	固定 3 个

---

六、实战：写一个「周报撰写专家」Agent

6.1 需求确认

让 WorkBuddy 化身周报搭子 → 把零散工作记录变成结构化周报 → 含 STAR 进展、数据看板、风险预警、下周计划。

6.2 目录结构

weekly-report/
├── .codebuddy-plugin/
│   └── plugin.json              # 身份证
├── agents/
│   └── weekly-report.md         # 大脑
└── avatars/
    └── expert.png               # 头像

6.3 完整的 plugin.json

{
  "name": "weekly-report",
  "version": "1.0.0",
  "description": "Transforms scattered work notes into structured weekly reports with STAR framework, data dashboards, risk alerts, and next-week plans.",

  "agents": ["./agents/weekly-report.md"],

  "expertType": "agent",
  "agentName": "weekly-report",

  "displayName": {
    "en": "Zoe - Weekly Report Expert",
    "zh": "周小报 - 周报撰写专家"
  },
  "profession": {
    "en": "Weekly Report Writer",
    "zh": "周报撰写专家"
  },
  "displayDescription": {
    "en": "Transforms scattered work notes into structured weekly reports with STAR framework, data dashboards, and risk alerts.",
    "zh": "帮你把零散工作记录变成结构清晰的周报，含STAR进展、数据看板和风险预警。"
  },
  "avatar": "avatars/expert.png",
  "categoryId": "09-OperationsHR",
  "defaultInitPrompt": {
    "zh": "帮我写本周周报",
    "en": "Help me write this week's report"
  },
  "plugin": "weekly-report",
  "tags": [
    { "en": "Weekly Report", "zh": "周报撰写" },
    { "en": "Work Summary", "zh": "工作总结" },
    { "en": "Progress Tracking", "zh": "进展追踪" }
  ],
  "quickPrompts": [
    { "en": "Help me write this week's report", "zh": "帮我写本周周报" },
    { "en": "Organize my work notes into a report", "zh": "整理我的工作记录成周报" },
    { "en": "Improve last week's report", "zh": "优化上周的周报" }
  ]
}

6.4 完整的 Agent MD

---
name: weekly-report
description: Transforms scattered work notes into structured weekly reports using STAR framework. Use when the user mentions weekly reports, work summaries, progress updates, or asks to organize weekly work.
displayName:
  en: "Zoe - Weekly Report Expert"
  zh: "周小报 - 周报撰写专家"
profession:
  en: "Weekly Report Writer"
  zh: "周报撰写专家"
maxTurns: 50
---

# 周报撰写专家 - 周小报

你是周小报，一位有 5 年经验的职场周报顾问。你擅长从杂乱的工作记录中
提炼重点，用 STAR 结构让进展描述清晰有力，让领导一眼看到价值。
你的风格是：简洁、专业、数据说话、不废话。

## 核心能力

1. **记录整理**：将零散的工作记录分类为项目进展、会议沟通、行政事务
2. **STAR 重写**：用"情境-任务-行动-结果"格式重写每条进展，让描述更有说服力
3. **数据提炼**：从记录中提取关键数据指标，制作对比看板
4. **风险识别**：识别潜在风险，标注严重程度并给出应对建议
5. **计划建议**：基于本周进展，建议下周 3-5 个重点事项

## 工作流程

复制此清单并跟踪进度：

- [ ] 第 1 步：收集用户本周工作记录
- [ ] 第 2 步：将记录分类整理
- [ ] 第 3 步：用 STAR 格式重写进展
- [ ] 第 4 步：提取数据制作看板
- [ ] 第 5 步：识别风险并标注
- [ ] 第 6 步：建议下周计划
- [ ] 第 7 步：自检后输出完整周报

### 第 1 步：收集记录

询问用户：
- 本周做了哪些事？（可以随便列，不需要整理）
- 有没有关键数据？（如用户量、销售额、完成率）
- 有没有遇到问题或风险？
- 需要特别强调什么？

如果用户只给了一句话，主动追问以上 4 个问题。

### 第 2 步：分类整理

将用户给的记录分为三类：
- **项目进展**：有明确产出的工作
- **会议沟通**：讨论、评审、协调类
- **行政事务**：流程性、支持性工作

### 第 3 步：STAR 重写

对每条项目进展，用以下格式重写：
- **情境**：什么背景？为什么做这件事？
- **任务**：具体要做什么？
- **行动**：怎么做的？用了什么方法？
- **结果**：产出是什么？有没有数据？

> 如果信息不足以填满 STAR，标注"待补充"并提示用户。

### 第 4 步：数据看板

提取记录中的关键数据，制作表格：

| 指标 | 本周 | 上周 | 变化 | 备注 |
|------|------|------|------|------|

> 如果用户没有提供上周数据，"变化"列标注"待补充"。

### 第 5 步：风险预警

从记录中识别潜在风险，按严重程度分类：
- 🔴 **高风险**：可能影响项目交付或关键指标
- 🟡 **中风险**：需要关注但不紧急
- 🟢 **低风险**：记录备查即可

每个风险给出一句应对建议。

### 第 6 步：下周计划

基于本周进展，建议 3-5 个下周重点事项：
- 要具体可执行（不要"继续推进XX"）
- 要有关联性（基于本周的进展和风险）
- 要有优先级排序

### 第 7 步：自检

输出前检查：
- [ ] 五个板块齐全（概览/进展/数据/风险/计划）
- [ ] 每条进展有 STAR 四要素
- [ ] 数据表格完整
- [ ] 风险标注了严重程度
- [ ] 下周计划 3-5 个具体事项
- [ ] 没有编造的数据

自检通过 → 输出完整周报。

## 输出模板

# 周报 | {姓名} | {日期范围}

## 一、本周概览
{3-5 句话总结核心进展}

## 二、详细进展
### {项目名}
- **情境**：{背景}
- **任务**：{目标}
- **行动**：{做法}
- **结果**：{产出/数据}

### {项目名}
......

## 三、数据看板
| 指标 | 本周 | 上周 | 变化 | 备注 |
|------|------|------|------|------|
| ... | ... | ... | ... | ... |

## 四、风险预警
| 风险项 | 级别 | 应对建议 |
|--------|------|---------|
| ... | 🔴/🟡/🟢 | ... |

## 五、下周计划
1. {重点事项1}（优先级：高）
2. {重点事项2}（优先级：中）
3. {重点事项3}（优先级：中）

## 注意事项

- 不得编造数据，所有数字必须来自用户提供的信息
- 信息不足时主动追问，不要"猜"
- 风险预警必须有依据，不要危言耸听
- 下周计划要具体可执行，不要写"继续推进"这种废话
- 语气专业简洁，像一个靠谱的同事帮你整理
- 如果用户给了上周周报，做对比分析

6.5 这个 Agent 好在哪里？

• ✅ description 包含 WHAT（把零散记录变成结构化周报）和 WHEN（用户提到周报、工作总结时）
• ✅ displayDescription 中文 44 字，在 40-50 字范围内
• ✅ tags 固定 3 个，quickPrompts 固定 3 个
• ✅ defaultInitPrompt 与 quickPrompts[0] 一致
• ✅ 工作流有 7 步清单 + 自检反馈循环
• ✅ 输出模板给中等自由度（结构固定、措辞自由）
• ✅ 明确约束"不得编造数据"“信息不足要追问”，防幻觉
• ✅ name、agentName、目录名、MD 文件名完全一致

---

七、如何安装和注册 Agent

方式一：让 WorkBuddy 全程代办（推荐）

在对话框里说：

帮我创建一个 Agent，需求如下：
[把第三节的需求描述发过去]

WorkBuddy 会自动完成：初始化目录 → 写文件 → 生成头像 → 校验 → 注册。完成后你去专家中心看看就行。

方式二：手动创建 + 让 WorkBuddy 注册

适合自己管理文件、或从同事那拷贝了现成的 Agent 文件夹。

第 1 步：创建目录

mkdir -p ~/.workbuddy/plugins/marketplaces/my-experts/plugins/weekly-report/.codebuddy-plugin
mkdir -p ~/.workbuddy/plugins/marketplaces/my-experts/plugins/weekly-report/agents
mkdir -p ~/.workbuddy/plugins/marketplaces/my-experts/plugins/weekly-report/avatars

第 2 步：放入文件

~/.workbuddy/.../weekly-report/
├── .codebuddy-plugin/plugin.json    ← 放这里
├── agents/weekly-report.md          ← 放这里
└── avatars/expert.png               ← 放这里

第 3 步：注册

在对话框里说：

帮我把 weekly-report 这个专家注册一下

第 4 步：验证

1. 打开 WorkBuddy 左侧「专家」入口
2. 在「我的专家」中找到「周小报」
3. 点击进入，测试发一句：帮我写本周周报
4. 看看是不是按你的模板输出 → 成功！

排错速查表

症状	可能原因	解决办法
专家中心找不到	目录结构不对	确认 .codebuddy-plugin/plugin.json 路径
找到了但点不开	agentName 与 MD 文件名不一致	确保 agentName = MD 文件名（不含 .md）
展示信息缺字段	tags/quickPrompts 数量不对	各固定 3 个
displayDescription 报错	中文字数不对	40-50 字
头像不显示	路径错或尺寸超标	512×512，≤500KB
Agent 不按模板输出	MD 指令太模糊	加模板、示例、自检清单

---

八、迭代优化：让你的 Agent 越用越好

Agent 不是"创建完就结束"的东西。像产品一样，它需要在使用中迭代。

8.1 迭代循环

使用 → 发现问题 → 修改 Agent MD → 重新注册 → 再使用

8.2 常见迭代场景

场景	怎么改	修改哪个文件
输出格式不对	加模板 / 加示例	Agent MD
总是编造数据	加约束 / 加自检	Agent MD
触发不了	改 description	Agent MD frontmatter
展示名称要改	改 displayName	plugin.json
想加新能力	加核心能力 + 工作流步骤	Agent MD
换头像	替换 avatars/ 下的图片	avatars/
想加技能包	新增 skills/ 目录	skills/ + plugin.json

8.3 怎么修改？

直接在对话框里说：

帮我修改 weekly-report 这个专家：
1. 周报里加一个"学习成长"板块
2. 下周计划改成按优先级 P0/P1/P2 标注
3. 把标签从"进展追踪"换成"效率提升"

WorkBuddy 会自动定位文件、修改内容、重新校验和注册。

8.4 ⚠️ 修改时的禁忌

以下字段绝对不能改（改了会导致 Agent 丢失）：

禁止修改的字段	原因
plugin.json 中的 name	唯一标识，改了等于删了重建
plugin.json 中的 agentName	与 MD 文件名绑定
专家目录名（如 weekly-report/）	改了注册信息对不上
agents/ 下的 MD 文件名	agentName = MD 文件名

如果确实要改名，需要删除旧 Agent、创建新的。

8.5 怎么判断该迭代还是该重建？

情况	建议
输出格式微调	迭代（改模板）
加一两个新能力	迭代（改 Agent MD）
核心定位变了（从周报变成月报）	迭代（改 MD + plugin.json 展示字段）
完全换了个场景（从周报变成财务分析）	重建（创建新 Agent）

---

九、进阶：从单角色 Agent 到多角色 Team

当你做好第一个 Agent 后，可能会遇到更复杂的需求——一个人搞不定了。

9.1 什么时候该用 Team 型？

判断标准	单角色 Agent	多角色 Team
任务复杂度	单一领域	跨领域协作
角色数量	一个人能搞定	需要多个专业角色
举例	周报撰写	投研报告（分析师+风控+策略师）

9.2 Team 型的核心概念

┌──────────────────────────────────────┐
│              主理人（Lead）            │
│  负责：接收需求 → 分配任务 → 汇总结果  │
├──────────┬───────────┬───────────────┤
│  团员 A   │  团员 B    │   团员 C      │
│  分析师   │  风控官    │  策略师       │
└──────────┴───────────┴───────────────┘

• 主理人：接收用户需求，按 SOP 调度各团员，汇总产出
• 团员：各自独立完成专业分析，结果回传给主理人
• 铁律：所有跨成员信息流必须经主理人中转，团员之间不直连

9.3 Team 型的文件结构

my-team/
├── .codebuddy-plugin/
│   └── plugin.json              # expertType: "team"
├── agents/
│   ├── my-team-team-lead.md     # 主理人（文件名必须带团队前缀）
│   ├── analyst.md               # 团员 A
│   └── risk-officer.md          # 团员 B
└── avatars/
    ├── my-team-team-lead.png
    ├── analyst.png
    └── risk-officer.png

Team 型更复杂，建议先做好单角色 Agent，再探索 Team。

---

十、发布前的验收清单

核心质量

• description 具体、包含触发词、英文第三人称
• description 同时包含 WHAT 和 WHEN
• displayDescription 中文 40-50 字
• Agent MD 正文 ≤ 200 行
• 全文术语统一
• 示例具体而非抽象

结构规范

• name 小写+连字符（如 weekly-report）
• agentName = MD 文件名（不含 .md）
• tags 固定 3 个
• quickPrompts 固定 3 个
• defaultInitPrompt = quickPrompts[0]
• categoryId 从标准分类表选择
• frontmatter 无 tools 字段
• 头像 512×512，≤500KB

内容质量

• 工作流有清晰步骤
• 输出有固定模板
• 有自检/反馈环节
• 有明确约束（防幻觉）
• 没有时效性信息

Team 型额外检查

• 主理人文件名带团队前缀（如 my-team-team-lead.md）
• profession 与 displayName 一致
• members 数组包含主理人（role=lead）
• teamInfo.memberAgents 不含主理人
• 主理人 MD 有成员能力清单和预设 Workflow

---

十一、总结

全流程回顾

想清楚（7 个问题）
   │
   ├── 交互式创建 ──┐
   │                ├──→ WorkBuddy 生成文件
   ├── 资料转化式 ──┘         │
   │                     校验 → 注册
   │                         │
   │                    专家中心可见
   │                         │
   │                      使用测试
   │                         │
   └── 迭代优化 ←── 发现问题 ←┘
         │
    （可选）打包分享

核心要点

1. Agent = 人格（plugin.json）+ 大脑（Agent MD），前者管展示，后者管行为
2. 两种创建模式：交互式（从零描述）和资料转化式（从现成材料）
3. Agent MD = frontmatter + 正文，frontmatter 管元数据，正文管"怎么干"
4. description 是灵魂：写得好不好决定了 Agent 能不能被正确触发
5. 迭代是常态：第一次写不好很正常，用起来再改
6. 四个名字必须对上：name = 目录名 = agentName = MD 文件名

从一个小场景开始

不要一上来就想做一个"万能助手"。从一个高频小痛点开始：

• 每周写周报很痛苦 → 做一个「周报撰写专家」
• 每月做数据报告很费时 → 做一个「数据报告专家」
• 每次写邮件都纠结措辞 → 做一个「商务邮件专家」

Agent 的本质，是把你的隐性经验显性化：你脑海里"周报就该这么写"的直觉，写成文字后，就变成了 WorkBuddy 永不遗忘、每次必执行的标准动作。

从一个高频小场景开始，创建你的第一个 Agent 吧。

⭐如果你想免费体验WorkBuddy企业版，或者需要安全可控地接入API、自由切换 全球200+大模型，可以注册魔芋AI免费体验Qoder并领取token大礼包：https://www.moyu.info/register?aff=uZut