swarma — Agent 团队增长实验循环
何时使用此技能
当用户想要以下内容时，请使用 swarma：
- 运行增长实验（钩子、落地页、外联、定价、激活、留存）
- 构建 能学习并改进 的 Agent 团队（通过 A/B 测试，而非一次性执行）
- 获得针对特定受众/产品经过验证的有效战术手册
- 大规模测试想法（每周 50+ 个实验，而非 2-5 个）
- 用已记录、可分析、可搜索的实验数据替代“我们试过，没用”
触发短语：“测试什么有效”、“优化我的漏斗”、“找到最佳钩子”、“运行实验”、“A/B 测试”、“什么有效”、“构建战术手册”、“增长实验”、“提高转化率”
不要使用：当用户想要工作流自动化（使用 n8n/Make）、对话记忆（使用 honcho）或一次性 Agent 管道（使用 CrewAI/AutoGen）时。swarma 专用于随时间改进的实验循环。
快速参考
命令一览
| 命令 | 作用 | 何时使用 |
|---|---|---|
swarma init | 创建实例 + 启动团队 | 首次设置 |
swarma cycle <team> | 运行一个实验周期 | 测试、手动运行 |
swarma cycle <team> --topic "..." | 运行特定主题的周期 | 临时实验 |
swarma team create <name> --from-goal "..." | 根据目标生成团队 | 开始新的实验领域 |
swarma team show <name> | 检查团队配置 | 审查生成的内容 |
swarma team list | 显示所有团队 | 概览 |
swarma status | 成本、近期运行、实验 | 健康检查 |
swarma metric log <team> <agent> <value> | 记录外部指标 | 输入真实世界数据 |
swarma metric import <team> <csv> | 批量导入指标 | 批量数据摄入 |
swarma metric show <team> | 查看已记录的指标 | 审查性能 |
swarma serve --port 8282 | 启动 REST API | 外部集成 |
swarma serve --mcp | 启动 MCP 服务器 | Claude Code / Hermes 集成 |
swarma run | 启动调度引擎 | 持续运行 |
swarma expert list | 浏览推理透镜 | 探索专家框架 |
决策：选择哪个小队模板？
| 用户想改进... | 使用此小队 | AARRR 阶段 |
|---|---|---|
| 开头/钩子 | hook-lab | 获客 |
| 落地页文案 | landing-lab | 获客 |
| SEO 排名 | seo-engine | 获客 |
| 冷外联回复率 | cold-outbound | 获客 |
| 多渠道内容 | channel-mix | 获客 |
| 注册到价值激活 | activation-flow | 激活 |
| 定价与打包 | pricing-lab | 营收 |
| 流失与留存 | retention-squad | 留存 |
| 病毒传播与推荐 | referral-engine | 推荐 |
| 市场定位 | competitive-intel | -- |
| 短视频制作流水线 | faceless-factory | 获客 |
| 广告创意测试 | ad-creative-lab | 获客 |
| UGC 内容模拟 | ugc-factory | 获客 |
| 程序化 SEO | programmatic-seo | 获客 |
| 邮件订阅增长 | newsletter-engine | 留存 |
| 付费 + 自然流量循环 | acquisition-squad | 获客 |
| 社区驱动增长 | community-engine | 留存 |
| AI 电商优化 | agentic-storefront | 营收 |
决策：使用生成器还是模板？
| 情境 | 方法 |
|---|---|
| 用户有具体、明确的目标 | swarma team create --from-goal（让 AI 设计团队） |
| 目标匹配现有小队模板 | 复制模板，然后自定义 |
| 用户想广泛实验 | 从 hook-lab 开始（最通用） |
| 用户不知道从哪里开始 | 询问他们的漏斗瓶颈，然后选择 |
GROWS 循环（核心概念）
每个实验周期遵循五个步骤：
生成假说 运行实验 观察信号 评估裁决 积累战术手册
Generate Run Observe Weigh Stack
hypothesis --> experiment --> signal --> verdict --> playbook
^ |
└──────────────────────────────────────────────────┘
| 步骤 | 做什么 | 代码位置 |
|---|---|---|
| G — 生成 | Agent 读取 strategy.md，提出假说 | core/cycle.py |
| R — 运行 | Agent 激活假说执行，产生输出 | flow/executor.py |
| O — 观察 | 单独的廉价 LLM 对输出评分（1-10，强制小数） | core/agent.py |
| W — 评估 | 5 个周期后，比较平均值与基线。>20% = 保留/丢弃 | core/experiment.py |
| S — 积累 | 已验证的模式写入 strategy.md + 战术手册 | core/agent.py |
关键数字：
- 裁决阈值：改进 20% 保留，下降 20% 丢弃
- 默认
min_sample_size：裁决前 5 个周期 - 评分：1-10 分制，使用小数（如 7.3，非 7）
设置指南
平台：Claude Code / Claude Desktop
pip install swarma
swarma init
添加到 .mcp.json：
{
"mcpServers": {
"swarma": {
"command": "swarma",
"args": ["serve", "--mcp"],
"env": { "OPENROUTER_API_KEY": "sk-or-..." }
}
}
}
重要：OPENROUTER_API_KEY 必须放在 MCP env 块中。实例的 .env 不会被子进程继承。
平台：Hermes（通过终端）
Hermes 有终端访问权限——可以直接运行 swarma CLI 命令。无需 MCP。
pip install swarma
swarma init
然后告诉 Hermes："运行 swarma cycle hook-lab --topic 'AI agents are overhyped'"
Hermes 读取终端输出并执行结果。要获得结构化访问，添加 MCP：
# hermes config.yaml
mcp_servers:
swarma:
transport: stdio
command: swarma
args: ["serve", "--mcp"]
env:
OPENROUTER_API_KEY: "sk-or-..."
平台：OpenClaw
pip install swarma
swarma init
根据你的 OpenClaw 配置，配置为 MCP 工具或使用终端访问。
平台：CLI（独立使用）
pip install swarma
swarma init # 创建实例 + 启动团队
swarma cycle starter --topic "为什么创业公司会失败" # 运行一个周期
swarma status # 检查成本、运行、实验
从源码安装
git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
swarma init
环境设置
swarma init 后，添加你的 API 密钥：
echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env
在 openrouter.ai/keys 获取密钥。
可选（用于跨团队知识）：
# 仅在运行 3 个以上团队时需要
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env
上手流程
当用户想要设置 swarma 时，请遵循以下顺序。团队生成器是最快的路径——不要让用户手动配置智能体。
步骤 1：理解目标
询问：
- “你想改进什么？”（转化率、用户参与度、外联回复率、SEO 排名等）
- “你的受众是谁？”（B2B SaaS 用户、加密货币社区、企业买家等）
- “成功是什么样子？”（更多注册、更高 CTR、更好回复率等）
步骤 2：安装
pip install swarma
swarma init --yes
步骤 3：生成团队
这是关键步骤。使用团队生成器而不是手动挑选模板。
swarma team create growth-lab \
--from-goal "优化我们 B2B SaaS 的落地页转化" \
--context "开发者工具公司，500 免费用户，2% 转化到付费" \
--budget 30
生成器会：
- 设计团队（2-5 个具有特定角色的 Agent）
- 为每个角色选择合适的模型
- 编写 Agent 指令和实验模式
- 创建第一个实验假说并准备运行
审查生成的内容：
swarma team show growth-lab
步骤 4：运行第一个周期
swarma cycle growth-lab
预期输出：
Running cycle: growth-lab
flow: researcher -> copywriter -> judge
agents: ['researcher', 'copywriter', 'judge']
Cycle: growth-lab
Agent Model Cost Output Preview
researcher sonar-pro $0.000384 **Topic:** 52% of executives...
copywriter qwen3.5-plus-02-15 $0.000746 [A] We sent 4,382 cold emails...
judge mistral-nemo $0.000416 **Hook Variations:** A: "Did...
duration: 43.9s | total cost: $0.001546 | agents: 3
步骤 5：运行更多周期并审查
swarma cycle growth-lab # 运行另一个周期
swarma cycle growth-lab --topic "特定角度" # 带主题
swarma status # 检查进度
5 个周期后，实验引擎会发出第一个裁决。策略文件会自动演化。
日常使用
运行实验
# 单个周期
swarma cycle hook-lab
# 指定主题
swarma cycle hook-lab --topic "AI Agent 正在商品化"
# 持续运行（具有 cron 调度的团队会自动运行）
swarma run
# 持续运行并启用 API 服务器
swarma run --port 8282
输入真实指标
LLM 自我评估是一个起始代理。对于生产环境，请回传真实世界信号：
# 记录单个指标
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct
# 附加到特定实验
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3
# 添加注释
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "来自 linkedin 分析"
# 从 CSV 批量导入
swarma metric import hook-lab metrics.csv
# 查看已记录的指标
swarma metric show hook-lab
CSV 格式：agent,value,metric_name,note
copywriter,4.2,ctr_pct,第 1 周
copywriter,5.1,ctr_pct,第 2 周
researcher,7.8,relevance_score,
使用小队模板
# 将模板复制到你的实例
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
~/.swarma/instances/default/teams/hook-lab
# 或者，如果你克隆了仓库
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab
# 运行它
swarma cycle hook-lab --topic "为什么大部分创业公司会失败"
检查状态
swarma status
显示：所有团队、近期运行、成本（今天 + 本月）、待定计划、队列统计。
MCP 工具参考
通过 MCP 连接时，以下 16 个工具可用：
| 工具 | 描述 | 参数 |
|---|---|---|
swarma_health | 检查 swarma 是否在运行 | -- |
swarma_list_teams | 列出所有已配置的团队 | -- |
swarma_get_team | 获取团队详情（Agent、流程、调度） | team_id |
swarma_list_agents | 列出团队中的 Agent | team_id |
swarma_run_agent | 运行单个 Agent，可选上下文 | team_id, agent_id, context? |
swarma_run_cycle | 为团队运行完整周期 | team_id, topic? |
swarma_status | 实例状态（成本、运行、实验） | -- |
swarma_costs | 成本明细（今天、本月） | -- |
swarma_list_plans | 显示待定的实验计划 | team_id? |
swarma_approve_plan | 批准待定实验计划 | plan_id |
swarma_reject_plan | 拒绝待定计划 | plan_id, reason? |
swarma_get_outputs | 从 Agent 获取近期输出 | team_id?, agent_id?, limit? |
swarma_list_tools | 列出可用的 Agent 工具 | -- |
swarma_list_experts | 浏览专家推理透镜 | -- |
swarma_get_expert | 按 ID 获取专家详情 | expert_id |
swarma_generate_team | 根据目标生成新团队 | name, goal, context?, budget? |
常见 MCP 工作流
“最近发生了什么？”
swarma_status— 概览swarma_get_outputs— 近期 Agent 输出swarma_list_plans— 待定实验
“运行一个实验”
swarma_run_cycle带上 team_id 和可选主题swarma_get_outputs审查结果
“开始一个新的实验领域”
swarma_generate_team带上目标和上下文swarma_get_team审查生成的内容swarma_run_cycle启动它
“什么有效？”
swarma_get_outputs获取近期结果- 读取团队的
strategy.md获取已验证的模式
团队配置参考
一个团队就是一个文件夹。无需写代码。
teams/my-squad/
├── team.yaml # 目标、流程、调度、预算
├── program.md # 团队上下文和约束
└── agents/
├── researcher.yaml
├── writer.yaml
└── strategy.md # 预植入的增长知识（自动演化）
team.yaml
name: my-squad
goal: 找到有效的方法。
flow: "researcher -> writer" # 顺序
# flow: "researcher -> [writer, analyst]" # 并行
schedule: "0 8 * * 1-5" # 可选：工作日上午 8 点
budget: 30 # 可选：月预算（美元）
agent.yaml
id: writer
name: Writer
instructions: |
将研究转化为帖子。最多 200 字。
第一行就要有钩子。从业者语气。
model: qwen/qwen3.5-plus-02-15 # 可选：覆盖默认路由
metric:
name: content_quality
target: 8.0
experiment_config:
min_sample_size: 5
auto_propose: true
strategy.md（自动演化）
从种子知识开始，随着每个经过验证的实验而增长：
### 已验证的模式
**具体性胜出**
- 包含具体数字的钩子比模糊说法的收藏率高 2-3 倍
- “47% 的创业公司” > “大多数创业公司”
### 反模式（已丢弃）
- 通用励志开头：较基线下降 23%。丢弃。
### 待测试模式
- [ ] 第一人称忏悔 vs 第三人称案例研究
- [ ] 时间锚定（“2024 年...”）vs 永恒钩子
流程 DSL
# 顺序：a 运行，输出传递给 b
flow: "researcher -> writer"
# 并行：a 运行，然后 b 和 c 并发运行
flow: "researcher -> [writer, analyst]"
# 混合：
…
[译文截断]
专家推理透镜
swarma 附带了数十个专家框架（“透镜”），Agent 可以用它们来分析和生成更好的实验。swarma expert list 查看所有可用的透镜，swarma get_expert 查看详情。
每个透镜都带有：
- 领域（说服力、定价心理学、认知偏见等）
- 核心原理（关键概念）
- 透镜提示（Agent 用于自我引导的框架）
- 适用用例（何时使用该透镜）
示例：
| 透镜 ID | 领域 | 最佳用于 |
|---|---|---|
| objectivity | 说服力 | 需要客观性、高权威的论点 |
| social-proof | 说服力 | 社会证明对决策影响更大的情况 |
| optimism | 说服力 | 以希望为导向的叙述 |
| fairness | 说服力 | 围绕公平互惠的论点 |
| authority | 说服力 | 专家或权威意见的论据 |
| decoy | 定价心理学 | 三个选项，中间是诱饵 |
| … |
可以在 program.md 中为团队初始化透镜：
# 团队上下文
分析所有文案时应用 fairness、social-proof 和 objectivity 透镜。
扩展注意事项
当运行 1-2 个团队时
一切都通过 LLM 评估运行。成本约为每个周期 $0.001-$0.005。单个 team.yaml，策略文件手动编辑。简单场景不需要额外基础设施。
当运行 3-5 个团队时
考虑添加 Qdrant（MCP 向量数据库）进行跨团队模式匹配。设置 QMD：
docker run -p 8181:8181 qdrant/qdrant-mcp
工作原理：
- QMD 自动索引所有团队的
strategy.md文件 - 当 Agent 提出假说时，它会扫描跨团队模式
- “在 hook-lab 团队中，数字钩子胜出。把这个应用到 landing-lab。”
当运行 10+ 个团队或需要人机互动时
启用计划模式。在 team.yaml 中设置 review: human：
name: high-stakes
goal: 优化定价页面 — 有风险
flow: researcher -> copywriter
review: human
现在实验引擎启动但不会执行：
$ swarma cycle high-stakes
plan: high-stakes-03 (proposed 5 experiments)
approve with: swarma approve high-stakes-03
reject with: swarma reject high-stakes-03 --reason "too risky"
人机互动模式确保在有价值的场景中不会未经验证就投入精力。
成本管理
swarma status 显示今天和本月的累计成本。要设置预算：
# team.yaml
budget: 50 # 月预算 50 美元
当达到预算时，团队进入观察模式直至下个月。使用 --budget 标志覆盖：
swarma cycle hook-lab --budget 10 # 将此周期限制为 10 美元
故障排除
常见问题
| 问题 | 原因 | 修复 |
|---|---|---|
swarma 命令未找到 | pip 安装路径不在 PATH 中 | 运行 python -m swarma 或修复 PATH |
OPENROUTER_API_KEY 未设置 | 密钥缺失 | 检查 .env 文件或 MCP 配置中的 env 块 |
| 周期运行但无输出 | 模型返回空或不兼容 | 检查 Agent 的 model 字段，尝试 qwen/qwen3.5-plus-02-15 |
| 成本高于预期 | 模型选择或循环太过频繁 | 检查 budget 设置，考虑改用 qwen 或 mistral 模型 |
strategy.md 不更新 | 权限问题或裁决未触发 | 检查团队文件夹的写权限，确认 min_sample_size 为 5 |
| MCP 连接拒绝 | 端口冲突 | swarma serve --port 8282 使用不同端口 |
调试技巧
- 使用
swarma cycle <team> --verbose获取详细日志 - 检查
~/.swarma/instances/default/logs/目录中的日志 - 对于 MCP 问题，手动运行
swarma serve --mcp查看是否有错误被记录 - 对于指标问题，确认 CSV 格式正确：
agent,value,metric_name,note