# agency-agents-zh 拆解报告 — 可复用的AI角色设计模式

> 工具：`jnMetaCode/agency-agents-zh`（14.5k⭐）| 上游：`msitarzewski/agency-agents`
> 拆解时间：2026-06-11
> 核心理念：学角色设计思路和编排方式，不直接套用角色定义

---

## 一、一句话核心

一个**纯文档驱动的AI专家角色库**——每个角色是一个 `.md` 文件，定义了这个专家怎么思考、怎么工作、怎么交付。配合Agency Orchestrator可以像真实团队一样协作。

**和普通提示词的区别：**
- 普通提示词：告诉AI"你是一个专家"
- 这个角色库：定义了专家**怎么思考、按什么流程工作、交付什么成果**

---

## 二、技术亮点清单（可复用的技术模式）

### 🔑 模式1：Frontmatter元数据驱动（最有价值）

每个角色 `.md` 文件开头有一段YAML frontmatter：

```yaml
---
id: security-engineer          # 唯一ID
slug: security-engineer        # URL友好名称
name: 安全工程师               # 显示名称
department: engineering        # 所属部门
skills: [安全审计, 渗透测试, DevSecOps]  # 技能标签
tools: [claude, cursor]        # 兼容的工具
model_recommendation: claude-sonnet-4  # 推荐模型
---
```

**可复用度：⭐⭐⭐⭐⭐ — 我们的技能包也是Frontmatter驱动，可以直接借鉴字段设计**

**对我们Hermes技能包的启发：**
- 我们现有技能包的 `frontmatter` 只有 `name/description/tags/trigger`
- 可以加 `department`（技能归属）和 `model_recommendation`（推荐模型）
- 这样不同模型可以根据标签自动分配到合适的技能

### 🔑 模式2：角色正文结构化模板

每个角色的正文都按固定模板写，不是自由发挥：

```markdown
# {角色名}

## 角色定义
一句话说清这个角色是谁、解决什么问题

## 关键规则
- 核心约束（3-5条）
- 必须遵守的原则
- 不允许做的事

## 工作流程
```mermaid
graph TD
  A[接收任务] --> B[分析需求]
  B --> C[规划方案]
  C --> D[执行交付]
  D --> E[质量审查]
  E --> F[提交成果]
```

## 交付物
- 清单式列出产出物

## 知识边界
- 这个角色不做什么
- 什么情况下需要求助其他角色
```

**可复用度：⭐⭐⭐⭐ — 我们写新技能包时可以用这个模板**

### 🔑 模式3：通用格式 + 多工具转换器（convert.sh）

角色用**通用格式**写一次，通过 `convert.sh`（734行）自动转为各工具专属格式：
```
通用的 .md 文件
      │
      ├── convert.sh --tool hermes → SKILL.md  
      ├── convert.sh --tool claude → CLAUDE.md
      ├── convert.sh --tool cursor → .cursorrules
      ├── convert.sh --tool copilot → copilot-instructions.md
      └── convert.sh --tool codex → 自定义格式
```

**可复用度：⭐⭐⭐ — 我们只有Hermes一个工具，暂时不需要多工具转换**

### 🔑 模式4：NEXUS手动编排 → Orchestrator自动编排 双路径

**NEXUS框架（手动）：**
在角色文件末尾用 `#nexus` 区域写明协作关系：
```
#nexus
- input_from: [market-analyst, user-researcher]
- output_to: [content-creator, visual-designer]
- parallel_with: [qa-engineer]
```

**Orchestrator（自动）：**
Agency Orchestrator（npm包）读取角色定义，自动构建DAG：
```
一句话需求 → 自动选角 → DAG工作流 → 并行执行 → 交付成果
     ↓
  架构师 + 前端 + 后端 + 测试 同时协作
```

**可复用度：⭐⭐⭐ — 我们的delegate_task已经能做DAG编排，但暂不支持断点续跑**

### 🔑 模式5：50个中国原创角色的垂直领域深耕

翻译了165个英文角色后，又**原创了50个中国市场专用角色**：

| 领域 | 角色示例 |
|------|---------|
| 内容平台 | 小红书运营、抖音投流、B站UP主 |
| 企业工具 | 飞书管理员、钉钉集成专家 |
| 跨境电商 | Temu运营、Shein合规 |
| 政府业务 | 政务ToG专家、招投标专家 |
| 工业 | Qt上位机开发、机械设计 |
| 农业 | 畜禽养殖档案核对 |

---

## 三、局限性和必改部分（不能照搬）

| 环节 | 问题 | 原因 |
|------|------|------|
| 角色定义太泛 | 215个角色中很多定位重叠 | 上游是"尽可能覆盖"，我们需要的是"精准够用" |
| 英文角色水土不服 | 165个翻译角色有些不符合中国语境 | 出法律/合同类建议会有偏差 |
| 没有版本管理 | 角色更新没有变更记录 | 改了不知道改了什么 |
| 缺乏测试 | 角色质量靠人工评审 | 有些角色的工作流程逻辑不闭环 |

---

## 四、可以借鉴到Hermes技能库的点

1. **技能包模板升级** — 借鉴它的frontmatter字段和正文结构模板
2. **部门/技能标签体系** — 把现有的技能包打上部门和技能标签，方便检索
3. **50个中国原创角色** — 小红书运营/抖音投流/B站UP主这些可以直接参考它的定义思路
4. **convert.sh思想** — 如果以后要支持Codex/Cursor，可以写一个类似的格式转换器

---

## 五、角色库目录结构（参考用）

```
215个 .md 文件
├── academic/       (6个)    — 学术/研究
├── design/         (8个)    — 设计
├── engineering/    (38个)   — 工程开发（最大部门）
├── finance/        (7个)    — 金融
├── game-development/(3个)   — 游戏开发
├── hr/             (3个)    — 人力资源
├── legal/          (4个)    — 法律
├── marketing/      (18个)   — 营销
├── paid-media/     (6个)    — 广告投放
├── product/        (9个)    — 产品
├── project-management/(4个)— 项目管理
├── sales/          (4个)    — 销售
├── spatial-computing/(2个) — 空间计算/VR
├── specialized/    (5个)    — 专业领域
├── strategy/       (4个)    — 战略
├── supply-chain/   (3个)    — 供应链
├── support/        (2个)    — 客服支持
└── testing/        (4个)    — 测试
```

> **完整的215个角色清单：** `kb.hunanningyuan.cloud/ant-queen/agency-agents-zh/AGENT-LIST.md`