# Agency Agents 中文版 源码深度分析文档

> 项目：`jnMetaCode/agency-agents-zh` (⭐ 14.5k)  
> 上游英文版：`msitarzewski/agency-agents`  
> 分析日期：2026-06-11  
> 项目版本：v1.2.1 (commit baseline: 783f6a7@upstream)

---

## 目录

1. [项目整体架构](#1-项目整体架构)
2. [智能体角色定义格式](#2-智能体角色定义格式)
3. [Agent 角色按部门/工具分布统计](#3-agent-角色按部门工具分布统计)
4. [安装到 AI 工具的方法](#4-安装到-ai-工具的方法)
5. [与 Agency Orchestrator 的关系](#5-与-agency-orchestrator-的关系)
6. [工作原理思维导图](#6-工作原理思维导图)

---

## 1. 项目整体架构

### 1.1 目录结构

```
agency-agents-zh/
├── README.md                         # 主文档（中文简体）
├── README.zh-TW.md                   # 繁体中文版
├── AGENT-LIST.md                     # 215 个智能体完整清单（含来源标记）
├── CATALOG.md                        # 智能体速查表（中文名→文件路径）
├── UPSTREAM.md                       # 上游版本追踪（同步状态记录）
├── CONTRIBUTING.md                   # 贡献指南（含智能体格式规范）
├── LICENSE                           # MIT 许可证
├── package.json                      # npm 元数据（描述、文件列表）
│
├── .github/                          # GitHub 模板与 CI
│   ├── workflows/
│   │   ├── ci.yml                    # 持续集成
│   │   ├── lint-agents.yml           # 智能体格式检查
│   │   └── sync-to-gitee.yml         # 同步到 Gitee 镜像
│   └── ISSUE_TEMPLATE/               # Issue/PR 模板
│
├── academic/                         # 📖 学术部 (6 个智能体)
├── design/                           # 🎨 设计部 (8 个)
├── engineering/                      # 🛠️ 工程部 (35 个)
├── finance/                          # 🏦 金融部 (8 个)
├── game-development/                 # 🎮 游戏开发部 (20 个)
│   ├── blender/
│   ├── godot/
│   ├── roblox-studio/
│   ├── unity/
│   └── unreal-engine/
├── hr/                               # 👔 人力资源部 (2 个) — 中国市场原创
├── legal/                            # ⚖️ 法务部 (2 个) — 中国市场原创
├── marketing/                        # 📢 营销部 (36 个)
├── paid-media/                       # 💰 付费媒体部 (7 个)
├── product/                          # 📦 产品部 (5 个)
├── project-management/               # 📋 项目管理部 (6 个)
├── sales/                            # 💼 销售部 (8 个)
├── spatial-computing/                # 🥽 空间计算部 (6 个)
├── specialized/                      # 🔬 专项部 (46 个)
├── strategy/                         # 🧠 NEXUS 策略框架
│   ├── EXECUTIVE-BRIEF.md            #   高管简报
│   ├── QUICKSTART.md                 #   快速上手指南
│   ├── nexus-strategy.md             #   完整运营纲领
│   ├── playbooks/                    #   阶段手册 (7 个阶段)
│   ├── coordination/                 #   协作模板
│   └── runbooks/                     #   场景操作手册
├── supply-chain/                     # 📦 供应链部 (4 个) — 中国市场原创
├── support/                          # 🛎️ 支持部 (7 个)
├── testing/                          # 🧪 测试部 (9 个)
│
├── integrations/                     # 🔌 工具适配输出目录（由 convert.sh 生成）
│   ├── aider/                        #   CONVENTIONS.md
│   ├── antigravity/                  #   SKILL.md 文件
│   ├── claude-code/                  #   原生 .md（直接复制）
│   ├── cursor/                       #   .mdc 规则文件
│   ├── gemini-cli/                   #   扩展 + SKILL.md
│   ├── github-copilot/               #   原生 .md（直接复制）
│   ├── mcp-memory/                   #   MCP 记忆服务器配置
│   ├── openclaw/                     #   SOUL.md + AGENTS.md + IDENTITY.md
│   ├── opencode/                     #   .md agent 文件
│   ├── trae/                         #   .md 规则文件
│   └── windsurf/                     #   .windsurfrules
│
├── examples/                         # 多智能体协作示例
│   ├── nexus-spatial-discovery.md    #  8 个智能体并行工作
│   ├── workflow-startup-mvp.md       #  Startup MVP 工作流
│   └── workflow-xiaohongshu-launch.md # 小红书发布工作流
│
├── scripts/                          # 运维脚本
│   ├── install.sh                    #   一键安装到各工具
│   ├── convert.sh                    #   转换格式生成集成文件
│   ├── install.ps1                   #   Windows PowerShell 安装脚本
│   ├── convert.ps1                   #   Windows 格式转换
│   ├── lint-agents.sh                #   智能体格式校验
│   └── sync-tw.sh                    #   繁体中文同步
│
└── assets/                           # 静态资源（赞助商图片等）
```

### 1.2 文件组织原则

| 原则 | 说明 |
|------|------|
| **按部门分目录** | 每个一级目录对应一个业务部门，目录名为英文 slug |
| **每个智能体一个文件** | 一个 `.md` 文件定义一个智能体角色，文件名格式：`{部门}-{角色名-snake-case}.md` |
| **YAML Frontmatter 元数据** | 每个 .md 文件头部包含 `name`、`description`、`emoji`、`color` 等字段 |
| **目录即分类** | 目录名（如 `engineering`）同时也是 CATALOG.md 中的分类 ID |
| **统一命名规范** | 文件名前缀匹配部门名（如 `engineering-*`），便于脚本自动化处理 |
| **CI 自动校验** | GitHub Actions 通过 `lint-agents.sh` 检查 frontmatter 格式完整性 |
| **双源并存** | 165 个翻译自上游 + 50 个中国市场原创，AGENT-LIST.md 的"来源"列标记区分 |

### 1.3 核心元数据文件关系

```
UPSTREAM.md ──→ 记录上游版本基线（commit 783f6a7, 184 agents）
      │
      ├──→ CATALOG.md ──→ 中文名 → 文件路径的快速查找表（用户查阅用）
      │
      └──→ AGENT-LIST.md ──→ 全量统计清单（自动生成，含部门统计、来源统计）
                                ├── 按部门统计：17 个部门 215 个智能体
                                └── 按来源统计：165 翻译 + 50 原创
```

---

## 2. 智能体角色定义格式

### 2.1 Frontmatter 字段结构（YAML 头部）

每个 `.md` 文件以 YAML frontmatter 开头，包含以下必须字段：

```yaml
---
name: 安全工程师              # 中文名称（必须）
description: 专业应用安全工程师...  # 一句话描述（必须）
emoji: 🔒                     # 表情符号（可选，部分智能体有）
color: red                    # 颜色标记（必须，用于工具 UI 区分）
---
```

**color 支持的取值**：`cyan`, `blue`, `green`, `red`, `purple`, `orange`, `teal`, `indigo`, `pink`, `gold`, `amber`, `neon-green` 及 Hex 颜色码（如 `"#FF2442"`）。

### 2.2 正文结构模板

```markdown
# {智能体名称}

你是**{智能体名称}**，[一句话定位和风格描述]。

## 你的身份与思维模式（身份与记忆）
- **角色**：具体角色定位
- **性格/个性**：性格特点描述
- **理念/记忆**：核心价值观或记住什么
- **经验**：擅长领域和背景故事

## 你的核心使命
### {子领域1}
- 具体职责条目
- ...

### {子领域2}
- ...

## 你必须遵守的关键规则
### {规则分类}
1. **规则条目** — 详细说明
2. ...
- 硬性规则（如"每个发现必须包含严重性评级"）

## 你的技术交付物
### {交付物类型1}
```{代码语言}
# 模板或示例代码
```

### {交付物类型2}
```{代码语言}
# 更多模板
```

## 你的工作流程
### 阶段一：{阶段名称}
1. 步骤1
2. 步骤2
...

### 阶段二：{阶段名称}
...

## 你的沟通风格
- **风格1**："示例对话"
- **风格2**："示例对话"

## 成功指标（可选）
- 可量化的 KPI
- ...

## 高级能力（可选）
### {能力领域}
- ...
```

### 2.3 各字段出现频率与典型内容

| 章节 | 出现率 | 典型内容 |
|------|--------|----------|
| `# 智能体名称` | 100% | Markdown H1 标题 |
| `你的身份与思维模式` | ~90% | 角色、性格、理念、经验 |
| `核心使命` | ~100% | 按子领域分条列出职责 |
| `关键规则` | ~80% | 硬性约束、红线、最佳实践 |
| `技术交付物` | ~85% | 代码模板、Markdown 模板、YAML 配置 |
| `工作流程` | ~95% | 分阶段的步骤化流程 |
| `沟通风格` | ~70% | 对话示例、语气说明 |
| `成功指标` | ~40% | 量化 KPI（营销/产品类常见） |
| `高级能力` | ~30% | 进阶技能（工程师类常见） |

### 2.4 实际示例对比

**工程类（安全工程师）**：强调技术深度、交付物包含代码示例、CI/CD YAML、威胁模型文档模板。文件约 303 行，15.8 KB。

**营销类（小红书运营专家）**：强调运营策略、交付物包含内容模板和投放排期表。文件约 139 行，5.5 KB。less is more 的结构风格。

---

## 3. Agent 角色按部门/工具分布统计

### 3.1 按部门统计（共 17 个部门，215 个智能体）

| # | 部门 | 英文分类 | 数量 | 占比 | 说明 |
|---|------|---------|:----:|:----:|------|
| 1 | 🔬 专项部 | `specialized` | **46** | 21.4% | 最多样化的部门，覆盖从区块链审计到高考志愿填报 |
| 2 | 📢 营销部 | `marketing` | **36** | 16.7% | 含国内平台(18) + 出海营销(6) + 通用(12) |
| 3 | 🛠️ 工程部 | `engineering` | **35** | 16.3% | 涵盖前端、后端、嵌入式、IoT、微信小程序等 |
| 4 | 🎮 游戏开发部 | `game-development` | **20** | 9.3% | Unity/Unreal/Godot/Blender/Roblox 全引擎覆盖 |
| 5 | 🧪 测试部 | `testing` | **9** | 4.2% | |
| 6 | 🎨 设计部 | `design` | **8** | 3.7% | |
| 7 | 💼 销售部 | `sales` | **8** | 3.7% | |
| 8 | 🏦 金融部 | `finance` | **8** | 3.7% | |
| 9 | 💰 付费媒体部 | `paid-media` | **7** | 3.3% | |
| 10 | 🛎️ 支持部 | `support` | **7** | 3.3% | |
| 11 | 📋 项目管理部 | `project-management` | **6** | 2.8% | |
| 12 | 🥽 空间计算部 | `spatial-computing` | **6** | 2.8% | |
| 13 | 📖 学术部 | `academic` | **6** | 2.8% | |
| 14 | 📦 产品部 | `product` | **5** | 2.3% | |
| 15 | 📦 供应链部 | `supply-chain` | **4** | 1.9% | 中国市场原创 |
| 16 | 👔 人力资源部 | `hr` | **2** | 0.9% | 中国市场原创 |
| 17 | ⚖️ 法务部 | `legal` | **2** | 0.9% | 中国市场原创 |
| | **总计** | | **215** | **100%** | |

### 3.2 按来源统计

| 来源 | 数量 | 占比 |
|------|:----:|:----:|
| 🌏 翻译自上游英文版 | **165** | 76.7% |
| 🇨🇳 中国市场原创 | **50** | 23.3% |
| **总计** | **215** | **100%** |

**50 个中国市场原创智能体的核心分布**：

| 领域 | 数量 | 代表智能体 |
|------|:----:|------------|
| 中国社交媒体平台运营 | ~18 | 小红书、抖音、微信、B站、快手、微博、知乎运营 |
| 中国市场工程专项 | ~8 | 微信小程序、飞书集成、钉钉集成、Qt 上位机、机械设计 |
| 政务 & 教育 | ~5 | 政务数字化售前、高考志愿填报、留学规划、养殖档案核对 |
| 医疗 & 合规 | ~3 | 医疗营销合规、AI 治理政策、企业风险评估 |
| 供应链 & 金融中国版 | ~6 | 库存预测、供应商评估、发票管理、金融风控 |
| 人力资源 & 法务 | ~4 | 招聘专家、绩效管理、合同审查、制度文件撰写 |
| 其他 | ~6 | 提示词工程师、播客策略师、知识付费策划师、会议效率专家等 |

### 3.3 按支持工具分布

以下 17 种 AI 编程工具均通过 `scripts/install.sh` 支持安装：

| # | 工具名称 | 安装方式 | 文件格式 | 安装目录 |
|---|---------|---------|---------|---------|
| 1 | **Claude Code** | 直接复制 | `.md` (原生) | `~/.claude/agents/` |
| 2 | **GitHub Copilot** | 直接复制 | `.md` (原生) | `~/.github/agents/`, `~/.copilot/agents/` |
| 3 | **OpenClaw** | convert + install | `SOUL.md` + `AGENTS.md` + `IDENTITY.md` | `~/.openclaw/agency-agents/` |
| 4 | **Cursor** | convert + install (项目级) | `.mdc` 规则文件 | `.cursor/rules/` |
| 5 | **Trae** | convert + install (项目级) | `.md` 规则文件 | `.trae/rules/` |
| 6 | **Aider** | convert + install (项目级) | `CONVENTIONS.md` 单文件 | 项目根目录 |
| 7 | **Windsurf** | convert + install (项目级) | `.windsurfrules` 单文件 | 项目根目录 |
| 8 | **OpenCode** | convert + install (项目级) | `.md` 文件 | `.opencode/agents/` |
| 9 | **Antigravity** | convert + install | `SKILL.md` | `~/.gemini/antigravity/skills/` |
| 10 | **Gemini CLI** | convert + install | 扩展 + `SKILL.md` | `~/.gemini/extensions/agency-agents/` |
| 11 | **Qwen Code** | convert + install (项目级) | `.md` 文件 | `.qwen/agents/` |
| 12 | **Codex CLI** | convert + install (项目级) | `.toml` 文件 | `.codex/agents/` |
| 13 | **DeerFlow 2.0** | convert + install | `SKILL.md` | `./skills/custom/` |
| 14 | **WorkBuddy** | convert + install | `SKILL.md` | `~/.workbuddy/skills/` |
| 15 | **Hermes Agent** | convert + install | `SKILL.md` | `~/.hermes/skills/` |
| 16 | **Kiro (Amazon)** | convert + install | `.md` (带 frontmatter) | `~/.kiro/agents/` |
| 17 | **Qoder** | convert + install (项目级) | `.md` 文件 | `.qoder/agents/` |

**安装模式分类**：
- **原生无转换**：Claude Code、GitHub Copilot（直接复制 `.md` 文件即可）
- **需先 convert 后 install**：OpenClaw、Cursor、Trae、Aider、Windsurf、Gemini CLI 等（需生成专属格式）
- **项目级安装**：Cursor、Trae、Aider、Windsurf、OpenCode、Codex CLI、Qoder（需在目标项目根目录执行）
- **全局安装**：Claude Code、Copilot、OpenClaw、Hermes、Kiro、WorkBuddy（安装到家目录）

---

## 4. 安装到 AI 工具的方法

### 4.1 一键安装（推荐）

```bash
# 1. 下载项目
git clone https://github.com/jnMetaCode/agency-agents-zh.git
cd agency-agents-zh

# 2. 自动检测并安装到所有已安装的工具
./scripts/install.sh

# 3. 或指定单个工具安装
./scripts/install.sh --tool claude-code    # Claude Code
./scripts/install.sh --tool copilot        # GitHub Copilot
./scripts/install.sh --tool cursor         # Cursor（需在项目根目录执行）
./scripts/install.sh --tool hermes         # Hermes Agent
```

### 4.2 各工具详细安装步骤

#### Claude Code
```bash
./scripts/install.sh --tool claude-code
# 复制到 ~/.claude/agents/
# 使用方式：在对话中直接说 "激活前端开发者"
```

#### GitHub Copilot
```bash
./scripts/install.sh --tool copilot
# 复制到 ~/.github/agents/ 和 ~/.copilot/agents/
```

#### Hermes Agent
```bash
# 先转换格式（生成 SKILL.md 文件到 integrations/hermes/）
./scripts/convert.sh --tool hermes

# 然后安装（复制到 ~/.hermes/skills/）
./scripts/install.sh --tool hermes

# 可选：只安装特定部门的技能（避免 Discord 斜杠命令超限）
./scripts/install.sh --tool hermes --category marketing
./scripts/install.sh --tool hermes --category engineering
```

#### Cursor
```bash
# 先转换
./scripts/convert.sh --tool cursor

# 然后在你的项目根目录安装
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool cursor
# 会在 .cursor/rules/ 生成 *.mdc 文件
# 需在 Cursor 设置中手动启用规则
```

#### Aider
```bash
./scripts/convert.sh --tool aider
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool aider
# 生成 CONVENTIONS.md 到项目根目录
```

#### Codex CLI
```bash
./scripts/convert.sh --tool codex
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool codex
# 生成 .codex/agents/*.toml 文件
```

### 4.3 直接手动复制

```bash
# 最简单的用法：直接复制需要的部门
cp marketing/*.md ~/.claude/agents/
cp engineering/*.md ~/.claude/agents/
```

### 4.4 安装流程示意图

```
原始 source .md 文件
        │
        ├──→ Claude Code / Copilot ──→ 直接复制（原生格式）
        │
        └──→ convert.sh ──→ integrations/<tool>/
                │
                ├──→ openclaw/       SOUL.md + AGENTS.md + IDENTITY.md
                ├──→ cursor/         *.mdc 规则文件
                ├──→ gemini-cli/     扩展 JSON + skills/
                ├──→ hermes/         SKILL.md (按分类组织)
                ├──→ codex/          *.toml
                ├──→ aider/          CONVENTIONS.md 单文件
                ├──→ windsurf/       .windsurfrules 单文件
                └──→ ...             (其他工具)
                        │
                        └──→ install.sh ──→ 复制到目标工具的配置目录
```

---

## 5. 与 Agency Orchestrator 的关系

### 5.1 两个项目的定位

| 项目 | 仓库 | 职责 | 关系 |
|------|------|------|------|
| **agency-agents-zh** | `jnMetaCode/agency-agents-zh` | **角色库**：定义 215 个 AI 专家的人设、流程和交付物 | 提供"专家定义" |
| **Agency Orchestrator** | `jnMetaCode/agency-orchestrator` | **编排引擎**：DAG 工作流管理器，让多个 Agent 自动协作 | 提供"团队协作" |

> **一句话概括**：角色库提供"做什么"的定义，Orchestrator 提供"怎么协作"的执行引擎。

### 5.2 Agency Orchestrator 的核心能力

```bash
npm install -g agency-orchestrator
ao compose "帮我写一篇关于 AI Agent 的深度分析文章" --run
```

输出示例：
```
🎭 自动选角 → 叙事学家 + 心理学家 + 内容创作者 + 叙事设计师
📊 自动编排 → DAG 工作流，检测依赖，并行执行
✅ 自动交付 → 几分钟后拿到完整成果
```

| 能力 | 说明 |
|------|------|
| 🎯 **零代码编排** | 纯自然语言或 YAML 描述需求 |
| ⚡ **DAG 并行执行** | 自动检测依赖，无依赖步骤并行跑 |
| 🔄 **断点续跑** | 失败步骤可单独重跑，不用从头来 |
| 🆓 **6 种免费 LLM** | Claude Code / Gemini CLI / Copilot / Codex / OpenClaw / Ollama |
| 💰 **3 种 API 接入** | DeepSeek / Claude API / OpenAI |
| 📋 **32 个现成模板** | 开发、营销、数据分析等场景开箱即用 |

### 5.3 协作流程示意

```
用户输入: "帮我做一个 SaaS MVP"
         │
         ▼
┌─────────────────────────────────────┐
│   Agency Orchestrator（编排引擎）    │
│                                     │
│   1. 解析需求 → 自动选角            │
│   2. 构建 DAG 工作流                │
│   3. 调度执行 → 断点续跑            │
│   4. 汇总交付 → 输出完整方案        │
└─────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│   agency-agents-zh（角色库）        │
│                                     │
│   Sprint 排序师  ← 拆解需求         │
│   UX 研究员     ← 用户调研          │
│   ┌──────────────────────┐          │
│   │ DAG 并行依赖检测     │          │
│   │ 无依赖 → 并行执行    │          │
│   │ 有依赖 → 串行等待    │          │
│   └──────────────────────┘          │
│   后端架构师    ← API 设计          │
│   前端开发者    ← UI 实现 (可并行)  │
│   增长黑客      ← 增长策略 (可并行) │
│   现实检验者    ← 质量门禁           │
└─────────────────────────────────────┘
         │
         ▼
   完整方案交付
```

### 5.4 NEXUS 策略框架

除了 Orchestrator 工具，项目自带的 `strategy/` 目录提供了官方的手动编排方案：

```
strategy/
├── EXECUTIVE-BRIEF.md         # 高管简报（战略总览）
├── QUICKSTART.md              # 5 分钟激活指南
├── nexus-strategy.md          # 完整运营纲领（800+ 行）
├── playbooks/                 # 7 个阶段手册
│   ├── phase-0-discovery.md   # 情报与发现
│   ├── phase-1-strategy.md    # 策略与架构
│   ├── phase-2-foundation.md  # 基础与脚手架
│   ├── phase-3-build.md       # 构建与迭代
│   ├── phase-4-hardening.md   # 质量与加固
│   ├── phase-5-launch.md      # 上线与增长
│   └── phase-6-operate.md     # 运营与演进
├── coordination/
│   ├── agent-activation-prompts.md  # 即用智能体提示词
│   └── handoff-templates.md        # 标准化交接格式
└── runbooks/                  # 4 个场景操作手册
    ├── scenario-startup-mvp.md        # 创业 MVP
    ├── scenario-enterprise-feature.md # 企业功能
    ├── scenario-marketing-campaign.md # 营销活动
    └── scenario-incident-response.md  # 事故响应
```

**NEXUS 三种部署模式**：

| 模式 | 智能体数量 | 周期 | 适用场景 |
|------|:----------:|:----:|----------|
| **NEXUS-Full** | 全部 | 12-24 周 | 完整产品生命周期 |
| **NEXUS-Sprint** | 15-25 | 2-6 周 | 功能或 MVP 构建 |
| **NEXUS-Micro** | 5-10 | 1-5 天 | 定向任务执行 |

### 5.5 两者的协同关系总结

```
              ┌──────────────────┐
              │   你的需求/任务   │
              └────────┬─────────┘
                       │
          ┌────────────┴────────────┐
          │                         │
          ▼                         ▼
┌──────────────────┐      ┌──────────────────────┐
│ 手动模式          │      │ 自动化模式            │
│ NEXUS 策略框架    │      │ Agency Orchestrator   │
│                  │      │                      │
│ 1. 阅读 QUICKSTART│      │ 1. ao compose "..."   │
│ 2. 选 playbook/   │      │ 2. 自动选角 + 编排    │
│ 3. 手动激活 Agent │      │ 3. DAG 并行执行       │
│ 4. 用 handoff 交接│      │ 4. 断点续跑           │
└────────┬─────────┘      └──────────┬───────────┘
         │                           │
         └──────────┬────────────────┘
                    │
                    ▼
       ┌────────────────────────┐
       │ agency-agents-zh 角色库 │
       │ 215 个专家定义文件      │
       └────────────────────────┘
                    │
                    ▼
          ┌──────────────────┐
          │    AI 工具执行    │
          │ Claude/Cursor/.. │
          └──────────────────┘
                    │
                    ▼
          ┌──────────────────┐
          │   完整交付成果    │
          └──────────────────┘
```

---

## 6. 工作原理思维导图

```
agency-agents-zh 工作原理
│
├── 1️⃣ 定义层：专家角色定义
│   ├── 每个 .md = 一个AI专家
│   │   ├── YAML Frontmatter (name, description, emoji, color)
│   │   ├── 身份与思维模式 (角色, 性格, 理念, 经验)
│   │   ├── 核心使命 (职责, 子领域)
│   │   ├── 关键规则 (红线, 约束)
│   │   ├── 技术交付物 (代码模板, 文档模板)
│   │   ├── 工作流程 (分阶段步骤)
│   │   ├── 沟通风格 (语气, 示例)
│   │   └── 成功指标 (KPI, 可量化)
│   │
│   └── 按部门分类组织
│       ├── engineering/ (35个) ───→ 技术实现专家
│       ├── marketing/ (36个)  ───→ 营销运营专家
│       ├── specialized/ (46个)───→ 垂直领域专家
│       └── ... (17个部门总计215个)
│
├── 2️⃣ 适配层：工具适配与安装
│   ├── 原生格式工具 (免转换)
│   │   ├── Claude Code ────→ 直接复制 .md → ~/.claude/agents/
│   │   └── GitHub Copilot ──→ 直接复制 .md → ~/.github/agents/
│   │
│   ├── 需转换格式的工具
│   │   ├── convert.sh 读取 .md → 解析 frontmatter + 正文
│   │   ├── 按工具模板生成目标格式
│   │   │   ├── Cursor       → *.mdc 规则文件 (YAML + markdown)
│   │   │   ├── OpenClaw     → SOUL.md + AGENTS.md + IDENTITY.md (三文件拆分)
│   │   │   ├── Hermes       → SKILL.md (两级目录: category/slug/)
│   │   │   ├── Codex CLI    → *.toml (结构化配置)
│   │   │   ├── Aider        → CONVENTIONS.md 单文件合并
│   │   │   ├── Windsurf     → .windsurfrules 单文件合并
│   │   │   └── Gemini CLI   → gemini-extension.json + SKILL.md 目录
│   │   └── install.sh 复制到目标路径
│   │
│   └── 安装模式
│       ├── 全局安装 (home目录) → Claude/Copilot/OpenClaw/Hermes/Kiro
│       └── 项目级安装 (工作目录) → Cursor/Trae/Aider/Windsurf/Codex
│
├── 3️⃣ 使用层：人机交互方式
│   ├── 单智能体模式
│   │   └── "激活前端开发者，帮我构建一个 React 组件"
│   │
│   ├── 手动编排模式 (NEXUS 框架)
│   │   ├── 选场景 → 找对应 runbook/playbook
│   │   ├── 按阶段激活智能体 (串行/并行)
│   │   ├── 用交接模板 (handoff) 传递上下文
│   │   └── 现实检验者做质量门禁 (evidence-based)
│   │
│   └── 自动编排模式 (Agency Orchestrator)
│       ├── npm install -g agency-orchestrator
│       ├── ao compose "一句话需求" → 自动选角
│       ├── DAG 依赖分析 → 并行/串行调度
│       ├── 逐步骤执行 (调用 LLM + 角色定义)
│       └── 断点续跑 + 汇总交付
│
├── 4️⃣ 协作层：多智能体协作机制
│   ├── 角色组合模式
│   │   ├── 开发流水线: 产品经理 → 架构师 → 开发者 → 测试 → 运维
│   │   ├── 内容流水线: 策略师 → 创作者 → 设计师 → 发布
│   │   └── 营销流水线: 研究员 → 策略师 → 运营 → 分析师
│   │
│   ├── DAG 执行模型
│   │   ├── 无依赖 → 并行 (多个部门同时工作)
│   │   ├── 有依赖 → 串行 (下游等上游输出)
│   │   └── 质量门禁 → 满足标准才能继续
│   │
│   └── 上下文传递
│       ├── 标准化交接模板 (handoff-templates.md)
│       ├── MCP 记忆服务器 (integrations/mcp-memory/)
│       └── 共享图谱 (identity-graph)
│
└── 5️⃣ 维护层：持续更新
    ├── 上游同步 (UPSTREAM.md)
    │   ├── 跟踪 msitarzewski/agency-agents @ main
    │   ├── 目前 184/184 翻译覆盖 100%
    │   └── 路径差异映射表
    │
    ├── CI 自动化
    │   ├── lint-agents.yml → frontmatter 格式校验
    │   ├── sync-to-gitee.yml → 国内镜像同步
    │   └── ci.yml → 综合检查
    │
    └── 社区贡献 (CONTRIBUTING.md)
        ├── 翻译上游新增 agent
        ├── 创建中国市场原创 agent
        └── 改进已有内容
```

---

## 附录 A：关键文件清单

| 文件/目录 | 说明 | 推荐阅读顺序 |
|-----------|------|-------------|
| `README.md` | 项目主文档，包含快速开始、安装方法、全部智能体阵容列表 | 1 |
| `AGENT-LIST.md` | 215 个智能体完整清单，含来源标记和部门统计汇总 | 2 |
| `CATALOG.md` | 速查表（中文名 → 文件路径） | 3 |
| `UPSTREAM.md` | 上游版本追踪和翻译覆盖率 | 4 |
| `CONTRIBUTING.md` | 贡献指南 + 智能体文件格式规范 | 5 |
| `integrations/README.md` | 各工具集成说明 | 6 |
| `strategy/EXECUTIVE-BRIEF.md` | NEXUS 多智能体协作策略概览 | 7 |
| `engineering/engineering-security-engineer.md` | 最佳角色定义示例（303 行完整版） | 8 |
| `marketing/marketing-xiaohongshu-operator.md` | 中国市场原创角色示例（139 行） | 9 |

## 附录 B：统计数字汇总

| 指标 | 数值 |
|------|:----:|
| 总智能体数 | **215** |
| 部门数 | **17**（含 strategy 运营文档为 18） |
| 翻译自上游 | **165** |
| 中国市场原创 | **50** |
| 支持 AI 工具 | **17** 种 |
| 项目版本 | **v1.2.1** |
| 许可证 | **MIT** |
| 上游 commit | 783f6a7 (2026-04-12) |
| 上游智能体数 | 184 |
| 翻译覆盖率 | **100%** |
| 安装脚本行数 | install.sh: 587 行 / convert.sh: 734 行 |
| NEXUS 阶段数 | 7 个 (Phase 0-6) |
| NEXUS 场景手册 | 4 个 |
| 集成示例 | 5 个 |
| 最大部门 | 专项部 (46 个，21.4%) |
| 最小部门 | 人力资源部 & 法务部 (各 2 个) |