Agency Agents 技术分析报告

项目：agency-agents

1. 项目概述

Agency Agents 是一个专注于 AI 编码助手的 多角色 Agent 资产库，包含 144+ 个专业化 Agent 定义，以 Markdown+YAML frontmatter 格式存储。

1.1 核心定位

1.2 Agent 领域分布

academic/          学术研究 (5 agents)
design/           UI/UX 与视觉设计 (8 agents)
engineering/      软件工程 (32 agents)
finance/          金融分析
game-development/ 游戏开发
marketing/        市场营销
paid-media/       付费广告 (8 agents)
product/          产品管理 (6 agents)
project-management/ 项目管理 (7 agents)
sales/            销售 (9 agents)
spatial-computing/ AR/VR 空间计算 (7 agents)
specialized/      专业化领域 (43 agents)
strategy/         战略规划
support/          客户支持
testing/          QA 与测试

2. 架构设计

2.1 架构模式

本项目采用 Specialist Multi-Agent Orchestration Pattern（专家多智能体编排模式），核心设计理念：

每个 Agent 都是"专业化的、有人格驱动的、聚焦交付的、可用于生产环境的"

拒绝通用型设计，采用专家型角色分工。

2.2 核心架构分层

┌─────────────────────────────────────────────┐
│         Source Layer (Markdown)              │
│   144+ agents across 15 directories          │
└─────────────────┬───────────────────────────┘
                  │ convert.sh
                  ▼
┌─────────────────────────────────────────────┐
│       Transform Layer (9 format converters)  │
│  antigravity / gemini-cli / opencode        │
│  cursor / aider / windsurf / kimi / qwen    │
│  openclaw / claude-code / github-copilot   │
└─────────────────┬───────────────────────────┘
                  │ install.sh
                  ▼
┌─────────────────────────────────────────────┐
│      Integration Layer (11 tool targets)    │
│  ~/.claude/agents/ ~/.gemini/ ~/.cursor/... │
└─────────────────────────────────────────────┘

2.3 核心模块职责

2.4 组件通信模式

Agent 间通信

• • 主要方式：顺序委托 + 手动复制粘贴交接（显式）
• • 增强方式：MCP Memory 工具（remember, recall, rollback, search）

脚本到文件系统通信

set -euo pipefail  # 严格错误处理

• • 进度条通过 progress_bar() 函数
• • 颜色编码状态输出：info(), warn(), error(), header()

3. 技术选型

3.1 技术栈总览

3.2 Agent 技术栈覆盖

前端框架：

• • React, Vue, Angular, Svelte
• • Next.js, Nuxt.js, Remix
• • Tailwind CSS, styled-components

后端框架：

• • Express.js, FastAPI, Flask
• • Django, Laravel, Spring Boot
• • NestJS, Gin, Echo

移动开发：

• • SwiftUI, UIKit (iOS)
• • Jetpack Compose (Android)
• • React Native, Flutter

游戏开发：

• • Unity (C#), Unreal Engine (C++)
• • Godot (GDScript), Roblox Studio (Lua)

数据库：

PostgreSQL / MySQL / MongoDB / Redis
Elasticsearch / SQLite / DynamoDB
Pinecone / Weaviate / Chroma / FAISS (向量数据库)
Snowflake / BigQuery / Redshift (数据仓库)

云平台：

• • AWS (EC2, Lambda, S3, RDS, ECS, EKS)
• • GCP (BigQuery, Cloud Run, GKE)
• • Azure (Functions, Cosmos DB, Synapse)
• • Vercel, Netlify, DigitalOcean

3.3 工具链

4. 功能模块

4.1 Agent 文件格式

每个 Agent 以 Markdown 文件存储，结构如下：

---
name:AgentName
description:One-linedescription
color:green或#hexcode
emoji:?
vibe:One-linepersonalityhook
services:# optional
-name:ServiceName
url:https://service-url.com
tier:free|freemium|paid
---

# Agent 内容 sections

标准 Sections：

• • Your Identity & Memory - 角色与背景
• • Your Core Mission - 核心职责
• • Critical Rules You Must Follow - 关键约束
• • Your Technical Deliverables - 技术交付物
• • Your Workflow Process - 工作流程
• • Your Communication Style - 沟通风格
• • Learning & Memory - 模式识别
• • Your Success Metrics - 成功指标
• • Advanced Capabilities - 专业技巧

4.2 转换工具支持

convert.sh 支持 9 种工具格式转换：

4.3 设计模式

Pattern 1: Frontmatter Pattern

---
name:SeniorDeveloper
description:Premiumimplementationspecialist...
color:green
emoji:?
vibe:Premiumfull-stackcraftsperson...
---

Pattern 2: SOUL/AGENTS Split (OpenClaw)

按 header 关键词分类：

• • SOUL keywords: identity, learning.*memory, communication, style, critical.rule, rules.you.must.follow
• • 其余内容 → AGENTS.md

Pattern 3: Provider Aggregator

单一转换器通过 case 语句处理多工具：

case"$tool"in
  antigravity) convert_antigravity "$file" ;;
  gemini-cli)  convert_gemini_cli  "$file" ;;
  opencode)    convert_opencode    "$file" ;;
  ...
esac

Pattern 4: 状态管理模式

5. 部署方案

5.1 部署模式

模式 1：本地安装（直接复制）

# Claude Code
cp engineering/*.md ~/.claude/agents/

# GitHub Copilot
cp engineering/*.md ~/.github/agents/

模式 2：自动化脚本安装

# 交互式安装（自动检测已安装工具）
./scripts/install.sh

# 指定工具安装
./scripts/install.sh --tool claude-code

# 批量并行安装
./scripts/install.sh --tool antigravity --tool cursor --parallel

模式 3：CI/CD 集成

# .github/workflows/lint-agents.yml
on:
pull_request:
paths:
-'**.md'
-'scripts/**'
jobs:
lint:
runs-on:ubuntu-latest
steps:
-uses:actions/checkout@v4
-run:./scripts/lint-agents.sh

5.2 工具安装矩阵

5.3 MCP Memory 集成

MCP Memory 提供跨会话持久化能力：

┌──────────────┐     ┌──────────────┐
│  MCP Server  │────▶│   Memory     │
│              │     │  (持久存储)  │
└──────────────┘     └──────────────┘
       │
       ▼
┌──────────────┐
│   Agent      │
│  remember/   │
│  recall/     │
│  rollback/   │
│  search      │
└──────────────┘

特点：

• • 无需修改 Agent 文件
• • 无 API 调用
• • 工具自动处理所有操作
• • 支持标签和跨会话连续性

6. 代码组织

6.1 目录结构

agency-agents/
├── .github/
│   └── workflows/
│       └── lint-agents.yml    # CI/CD 验证
├── academic/                  # 学术领域 agents
├── design/                    # 设计领域 agents
├── engineering/               # 工程领域 agents (32)
├── finance/                   # 金融领域
├── game-development/           # 游戏开发
├── integrations/               # 工具集成
│   ├── claude-code/
│   ├── cursor/
│   ├── mcp-memory/
│   ├── aider/
│   ├── windsurf/
│   └── ... (11 个工具)
├── examples/                   # 工作流示例
│   ├── nexus-spatial-discovery.md
│   ├── workflow-startup-mvp.md
│   └── workflow-with-memory.md
├── marketing/                  # 市场营销
├── paid-media/                 # 付费媒体
├── product/                   # 产品管理
├── project-management/         # 项目管理
├── sales/                     # 销售
├── specialized/                # 专业领域 (43)
├── spatial-computing/          # 空间计算
├── strategy/                  # 战略规划
├── support/                   # 客户支持
├── testing/                   # 测试
├── scripts/
│   ├── convert.sh             # 格式转换
│   ├── install.sh             # 安装脚本
│   └── lint-agents.sh         # 验证脚本
├── README.md
├── CONTRIBUTING.md
├── CONTRIBUTING_zh-CN.md
└── SECURITY.md

6.2 关键脚本

convert.sh (18KB)

• • 转换 Markdown Agent 为 9 种工具格式
• • 支持并行转换 (--parallel)
• • 进度条与颜色输出
• • 错误处理：set -euo pipefail

install.sh (24KB)

• • 交互式 TUI 安装
• • 自动检测已安装工具
• • 支持 checkbox 多选
• • Box-drawing 字符 UI

lint-agents.sh

• • 验证 YAML frontmatter
• • 检查必需字段：name, description, color
• • 建议 sections：Identity, Core Mission, Critical Rules
• • SOUL/AGENTS header 验证

7. 工作流示例

7.1 典型部署流程

# 1. 克隆仓库
git clone https://github.com/your-repo/agency-agents.git
cd agency-agents

# 2. 转换 agent 文件
./scripts/convert.sh

# 3. 安装到目标工具
./scripts/install.sh

# 4. 验证
./scripts/lint-agents.sh

7.2 多 Agent 协作示例

Nexus Spatial Discovery (8 个 Agent 并行)：

Opportunity Input
      │
      ├── Agent A: Product Manager
      ├── Agent B: Market Analyst
      ├── Agent C: Technical Architect
      ├── Agent D: Design Lead
      ├── Agent E: Financial Analyst
      ├── Agent F: Risk Advisor
      ├── Agent G: Marketing Strategist
      ├── Agent H: Legal/Compliance
      │
      ▼
  Synthesis Section (综合报告)

7.3 MCP Memory 工作流

# Agent 激活时
1. recall() → 获取项目上下文
2. remember() → 记录关键决策

# 关键节点
- session start: recall previous context
- decision point: remember key choice
- handoff: recall + remember for next agent
- failure: rollback to last known good state

8. 质量保证

8.1 Lint 规则

8.2 CI/CD 验证

name:LintAgents
on:
pull_request:
paths:
-'**.md'
-'scripts/lint-agents.sh'
jobs:
lint:
runs-on:ubuntu-latest
steps:
-uses:actions/checkout@v4
-run:./scripts/lint-agents.sh

9. 安全特性

9.1 脚本安全

• • set -euo pipefail：严格错误处理
• • 输入验证：工具检测函数 is_detected()
• • 临时文件清理：trap 'rm -f ...' EXIT

9.2 Agent 安全

• • 无 API 密钥存储
• • 无外部依赖（仅本地文件）
• • MCP Memory 隔离存储

10. 统计摘要

11. 扩展指南

11.1 添加新 Agent

1. 1. 创建 category/agent-name.md 文件
2. 2. 包含必需 frontmatter：name, description, color
3. 3. 实现所有建议 sections
4. 4. 运行 ./scripts/lint-agents.sh 验证

11.2 添加新工具支持

1. 1. 在 convert.sh 添加 convert_<tool>() 函数
2. 2. 在 install.sh 添加 detect_<tool>() 函数
3. 3. 创建 integrations/<tool>/ 目录
4. 4. 更新 README.md 文档

11.3 MCP Memory 集成

在 Agent 文件末尾添加：

## Memory Integration

-**Session start**: recall project context
-**Decision point**: remember key choices
-**Handoff**: use remember/recall for continuity
-**Failure**: rollback to last known good state

参考资源

• • README.md - 主文档
• • CONTRIBUTING.md - 贡献指南
• • integrations/README.md - 集成概述
• • scripts/convert.sh - 转换脚本源码
• • scripts/install.sh - 安装脚本源码
• • integrations/mcp-memory/README.md - 记忆集成