芯耀
与非AI
255
上一篇讲完 skill 之后，留言里有人问：
"skill 我大概懂了。但 agent 编排这个词我看了很多文章，每个人讲得不一样，到底是个啥？我应该怎么开始？"
这个问题非常好。"Agent 编排"是这两年被讲烂了但 90% 的人没真正搞清楚的概念——大部分文章要么停在"画个 LangGraph 框图"的层次，要么扯一大堆"AI 协作未来"的虚的。
今天这篇我们不谈虚的。我们真的搭一条能跑、能用、能进生产的多 agent 工作流，从设计到实现到 debug，全过程。
我挑的实战题目是我自己每周都在用的：给一个开源仓库做一份"技术尽职调查报告"——你给我一个 GitHub URL，我给你一份能直接给老板看的评估报告（成熟度 / 代码质量 / 社区活跃度 / 维护风险 / 是否值得引入）。
一、先把"Agent 编排"这个词讲清楚
在动手之前，先把这个词的歧义剥开。我看到的写法至少有 5 种：
多步 prompt chain
-
- —— 一个 LLM、多个 prompt 串起来。其实就是 prompt engineering，谈不上"编排"
Tool calling loop
-
- —— 一个 LLM、多个工具来回调用。这是现代 agent 的标配，也不是"编排"
Sub-agent 分工
-
- —— 一个父 agent 把任务拆给多个子 agent 并行做。这才开始有点"编排"的意思
多 agent 协作（DAG / state machine）
-
- —— 多个 agent 按预定义的图执行，每个 agent 有自己的角色。这是真正的编排
Recursive Language Model (RLM)
- —— 一个 agent 调用一群"小 agent"做批量并行子任务。这是 2026 年最火的新范式
今天我们要做的工作流，会同时用到 3、4、5 三种。所以是一个完整意义上的"agent 编排"实战。
提醒一下口径：如果你之前接触的"agent 编排"只停在 1、2 层次，今天的内容会刷新你的认知。
二、需求分析：技术尽调报告长什么样？
跟上一篇 skill 一样，先把产品想清楚再动手。
我每次接到"评估这个开源库要不要引入"的请求时，本质上是要回答 5 个问题：
它真在解决我们的问题吗？
-
- ——读 README + 几个 issue 看主诉求
代码质量如何？
-
- ——抽 5-10 个核心文件 review
维护活跃度如何？
-
- ——commit 频率、issue 响应速度、PR 周转
社区生态如何？
-
- ——star 增长曲线、贡献者数、依赖方
风险点是什么？
- ——bus factor、license、security advisory、breaking changes
这 5 个问题的答案合起来就是一份可决策的报告。
每个问题的处理方式很不一样：
问题 1：需要理解能力（读 README、issue 摘要）→ 强模型
问题 2：需要代码理解（读源码做 review）→ 强模型 + 工具调用
问题 3：需要结构化数据查询（GitHub API）→ 弱模型 + 工具
问题 4：需要爬数据 + 简单分析 → 弱模型 + 工具
问题 5：需要综合判断（合成所有信息得出结论）→ 强模型
如果用一个 agent 串行做完，会出现两个问题：
慢 —— 一个仓库评估串行下来要 20-30 分钟
贵 —— 全程用强模型很烧钱
质量降级 —— 上下文越长，强模型在最后阶段的判断质量反而下降
所以我们要把它拆成多个角色明确、职责清晰的 sub-agent，让该并行的并行、该用弱模型的用弱模型、该做综合的用强模型。
三、架构设计：5 个 agent + 1 个 RLM batch
我画了张图（用文字版描述）：
┌──────────────────┐
│ Orchestrator │ ← 主 agent (Claude Opus / DS V4 Pro)
│ (planner + │
│ synthesizer) │
└────────┬─────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Recon Agent │ │ Code Review │ │ Health │
│ (扫 README/ │ │ Agent │ │ Metrics │
│ issues) │ │ (源码抽样) │ │ Agent │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ RLM Batch │ │
│ │ (10 个文件并行 │ │
│ │ review，每个 │ │
│ │ 独立 Flash 模型) │ │
│ └──────────┬─────────┘ │
│ │ │
└────────────────┼──────────────────┘
▼
┌──────────────────┐
│ Risk Analyst │ ← 综合所有上游输出
│ Agent │
└──────────────────┘
│
▼
┌──────────────────┐
│ Final Report │
│ (markdown) │
└──────────────────┘
设计要点：
1. Orchestrator 是"项目经理"，不是"工人"
Orchestrator 只做三件事：
拆任务——把"做尽调"拆成 5 个子任务，分发给对应 sub-agent
协调——并行的并行、串行的串行、传递必要上下文
综合——汇总所有 sub-agent 的输出，写最终报告
它不直接读代码、不直接爬数据、不直接做分析。这条边界守住，整个工作流才稳。
很多人写多 agent 系统的失败模式是：Orchestrator 越管越多，最后什么都自己做，sub-agent 变成了摆设。
2. Sub-agent 各司其职、隔离上下文
每个 sub-agent 都有自己的"上下文窗口"，拿到的输入只有它需要的部分，输出回 Orchestrator 时也是结构化摘要，不带原始爬虫垃圾数据。
这件事的工程意义巨大：
上下文小 = 模型表现好
-
- ——一个 200K token 的窗口，agent 在里面找信息的命中率，比 20K 的窗口低得多
隔离 = 可独立 debug
-
- ——某个 sub-agent 输出有问题，单独跑它就能定位
隔离 = 可独立优化
- ——某个 sub-agent 用弱模型够了，就用 Flash
3. RLM Batch 是"代码 review 农民工"
Code Review Agent 自己不读代码。它做的事是：
-
- 找出仓库里的"核心代码文件"（可能是 10 个）对每个文件，
fan-out 一个 V4 Flash 子模型
- 做独立 review收集所有 review 结果，汇总成一份代码质量报告
这就是 RLM (Recursive Language Model)——主 agent 调用一群"小 agent"做批量并行任务。在 DeepSeek-TUI 里这是个原生工具叫 rlm_query，在 Hermes Agent 里叫 parallel_subagents。
为什么 RLM 这么重要？因为：
10 个文件并行 review，比串行快 8-9 倍
-
- （不是 10 倍，因为有调度开销）
每个 review 用 Flash 模型，成本只有 Pro 的 1/30隔离的小窗口，每个文件的 review 质量比"塞 10 个文件让一个模型一起读"要高得多
4. Risk Analyst 拿到的是"压缩过的高密度信息"
最后做综合判断的 Risk Analyst 不需要看原始数据，只需要看上游 3 个 agent 输出的结构化摘要。这意味着它能用最贵的模型（Opus / V4 Pro）专心做"判断"这件事，不浪费 token 在"理解原始信息"上。
四、一步步实现：从零搭这个工作流
我在 DeepSeek-TUI 上演示。Hermes Agent / Claude Code 的逻辑一样，只是 API 名字不同。
Step 1：搭 skill 骨架
~/.deepseek/skills/repo-due-diligence/
├── SKILL.md
├── references/
│ ├── recon-prompt.md # Recon Agent 的系统提示
│ ├── code-review-prompt.md # Code Review Agent 的系统提示
│ ├── health-prompt.md # Health Metrics Agent 的系统提示
│ ├── risk-prompt.md # Risk Analyst 的系统提示
│ └── report-template.md # 最终报告模板
├── scripts/
│ ├── github_meta.py # 拿 GitHub 仓库元数据（star、PR、issue）
│ ├── pick_core_files.py # 启发式挑出"核心文件"
│ └── render_report.py # 把结构化输出渲染成 markdown
└── tests/
└── eval.md # 10 个真实仓库 + 期望输出
Step 2：SKILL.md（Orchestrator 的剧本）
这里贴一个简化版本（实际我用的版本约 220 行）：
---
name: repo-due-diligence
version: "0.4.0"
description: |
Generate a technical due-diligence report for a GitHub repository.
Use this skill whenever the user asks to: 评估这个仓库、做技术尽调、看看这个开源项目
值不值得用、analyze this repo、due diligence on github.com/...、给我一份评估报告.
Triggers when the user pastes a GitHub URL with words like "评估"/"尽调"/"评测"/
"review"/"analyze". Do NOT trigger for code generation tasks or PR reviews.
allowed-tools: Bash, Read, Write, fetch_webpage, github_repo, rlm_query, agent_spawn
---
# repo-due-diligence
针对一个 GitHub 仓库，生成可决策的技术尽调报告。
## 编排流程
### 阶段 1：信息采集（并行）
并行 spawn 三个 sub-agent：
1. **Recon Agent**
- 输入：仓库 URL
- 任务：读 README、最近 20 个 open issues、最近 20 个 closed issues
- 输出：一段 ≤ 500 字的「项目意图与现状」摘要 + 3-5 条值得关注的 issue
- 模型：DeepSeek V4 Flash（足够）
- prompt: references/recon-prompt.md
2. **Code Review Agent**
- 输入：仓库 URL
- 任务：用 `scripts/pick_core_files.py` 挑出 10 个核心文件，
**每个文件 fan-out 一个 RLM child** 独立 review
- 输出：一份「代码质量报告」，含 5 项打分（架构 / 命名 / 测试 / 文档 / 复杂度）+ 风险点
- 模型：Code Review Agent 本身用 V4 Pro，每个 child 用 V4 Flash
- prompt: references/code-review-prompt.md
3. **Health Metrics Agent**
- 输入：仓库 URL
- 任务：跑 `scripts/github_meta.py` 拿元数据，分析活跃度趋势
- 输出：「健康度报告」，含 commit 频率、PR 周转中位数、issue 响应中位数、
近 6 个月 star 增长率、bus factor 估算
- 模型：V4 Flash（纯结构化分析，弱模型够）
- prompt: references/health-prompt.md
### 阶段 2：综合判断（串行）
阶段 1 全部完成后，spawn:
4. **Risk Analyst Agent**
- 输入：上面三个 agent 的结构化输出
- 任务：识别 5 大类风险（技术债 / 维护风险 / 社区风险 / license / security）
- 输出：「风险评估报告」+ 一句话「是否推荐引入」结论
- 模型：DeepSeek V4 Pro（综合判断需要强推理）
- prompt: references/risk-prompt.md
### 阶段 3：渲染（脚本）
跑 `python scripts/render_report.py` 把上面四个 agent 的结构化输出
渲染成 references/report-template.md 模板的 markdown 报告。
输出到 `./due-diligence-{repo}-{date}.md`。
## 严格约束
- 必须按阶段执行，不能跳过任何 sub-agent
- Code Review Agent 必须使用 RLM batch，不能串行
- Risk Analyst 输出的「是否推荐引入」必须是 强烈推荐 / 推荐 / 谨慎 / 不推荐 之一
- 最终报告里每个数字都必须可追溯到上游 agent 的输出
注意几个关键点：
每个 sub-agent 的输入 / 输出 / 模型 / prompt 路径都明确写出来
-
- ——这就是 Orchestrator 的剧本
明确哪一步并行、哪一步串行明确哪个 agent 用强模型、哪个用弱模型最后的渲染交给脚本
- ——绝对不要让 LLM 拼字符串
Step 3：sub-agent 的系统提示
每个 sub-agent 的 prompt 都要满足三条：
角色边界明确
-
- —— "你是 X，只做 Y，不做 Z"
输出格式锁死
-
- —— 必须是 JSON 或固定模板
失败时怎么办
- —— 数据缺失时输出什么
举个 Code Review Agent 的 prompt 节选：
# Code Review Agent
你是一个**代码 review 专员**，只负责一件事：评估给定文件的代码质量。
## 你的工具
- `rlm_query`: fan-out 多个 V4 Flash 子模型并行处理。**这是你必须使用的工具**。
- `Read`: 读取 review 子模型的输出。
## 流程
1. 用户会传给你一个文件列表（10 个 path）
2. 调用 `rlm_query`，并发度 = 10，每个 child 的 prompt:
你是代码 review 子模型。读取下面的文件内容，按 5 个维度打分（1-5）：
- 架构清晰度命名质量测试覆盖（基于本文件可见信息）文档完整性复杂度控制
输出严格 JSON：{"file": "", "scores": {...}, "risks": [...], "highlights": [...]}
3. 收集 10 份 JSON
4. 综合输出一份汇总报告（也是 JSON）：
{ "overall_scores": { ... 5 维平均分 ... }, "key_risks": [ ... 跨文件汇总的 top 5 风险 ... ], "key_strengths": [ ... 跨文件汇总的 top 3 亮点 ... ], "per_file": [ ... 10 份子报告 ... ] }
## 严格禁止
- 不要直接 Read 文件（让 RLM children 去做）
- 不要做风险综合判断（那是 Risk Analyst 的活）
- 不要写自然语言报告（输出必须是 JSON）
注意每个 sub-agent 都被严格限定了"角色 + 工具 + 输出格式 + 边界"。这是多 agent 系统能稳定工作的核心。
Step 4：scripts 把"逻辑"从 LLM 里挤出来
scripts/pick_core_files.py：
#!/usr/bin/env python3
"""启发式挑出仓库里最值得 review 的核心文件。"""
import sys
from pathlib import Path
# 文件评分规则
def score_file(path: Path, repo_root: Path) -> int:
rel = path.relative_to(repo_root).as_posix()
score = 0
# 主要源码目录加分
if any(rel.startswith(p) for p in ["src/", "lib/", "internal/", "pkg/"]):
score += 50
# 入口文件加分
if path.name in ("main.py", "main.rs", "main.go", "index.ts", "index.js", "app.py", "lib.rs"):
score += 30
# 核心模块名加分
for kw in ("core", "engine", "kernel", "runtime", "scheduler", "orchestrator"):
if kw in rel.lower():
score += 20
# 测试文件减分（不是这次的 review 对象）
if"test"in rel.lower() or"spec"in rel.lower():
score -= 100
# 配置 / 构建文件减分
if path.suffix in (".yaml", ".yml", ".toml", ".json", ".lock"):
score -= 50
# 文档减分
if path.suffix in (".md", ".rst"):
score -= 80
# 文件大小评分（太小 / 太大都减分）
try:
size = path.stat().st_size
if500 <= size <= 30000: # 0.5KB - 30KB 是 sweet spot
score += 10
elif size < 200:
score -= 30
elif size > 100000:
score -= 20
except OSError:
return-1
return score
def main():
repo_root = Path(sys.argv[1])
candidates = []
for p in repo_root.rglob("*"):
ifnot p.is_file():
continue
if any(part.startswith(".") for part in p.parts): # skip dot dirs
continue
s = score_file(p, repo_root)
if s > 0:
candidates.append((s, str(p.relative_to(repo_root))))
candidates.sort(reverse=True)
for _, path in candidates[:10]:
print(path)
if __name__ == "__main__":
main()
为什么这个逻辑要写成脚本而不是让 LLM 做？
确定性：同样的仓库，永远挑同样的文件。LLM 每次都不一样
速度：脚本毫秒级完成。LLM 要几十秒
成本：脚本免费。LLM 要烧 token
可调试：脚本结果不对，改规则；LLM 结果不对，没法直观调试
这条原则在 agent 编排里特别重要：任何能用代码解决的事，都不要交给 LLM 做。
Step 5：触发与跑通
在 DeepSeek-TUI 里跑：
> 评估一下 https://github.com/Hmbown/DeepSeek-TUI 这个仓库
DeepSeek-TUI 触发 skill，执行 Orchestrator 剧本，整个过程大约：
阶段 1 并行启动：3 个 sub-agent 同时开跑Recon Agent：~ 90 秒，输出 README + issues 摘要Code Review Agent：~ 4 分钟（其中 RLM 10 个 child 并行，最慢的 child 决定总时长）Health Metrics Agent：~ 60 秒，纯结构化数据
阶段 2 串行：Risk Analyst 拿三份摘要做综合，~ 2 分钟
阶段 3 渲染：脚本 < 1 秒
总耗时约 7-8 分钟，总成本约 $0.6。
对比串行单 agent 方案（用 Opus 全程跑）：
- 时间：25-30 分钟成本：$4-5
性价比提升约 6-7 倍。
五、踩过的坑
坑 1：让 Orchestrator 知道太多上下文
第一版让 Orchestrator 全程持有所有 sub-agent 的原始输出。结果：
- Orchestrator 的上下文窗口很快被撑爆综合判断质量反而下降（信息过载）整体成本飙升（每次工具调用都带着完整上下文）
修复：sub-agent 的输出回到 Orchestrator 时必须先压缩成结构化摘要，原始数据存到磁盘临时文件，需要时才按 path 读取。
坑 2：Sub-agent 越界
第二版没把 Code Review Agent 的边界写死。它在跑的过程中"顺便"开始查 GitHub API、读 README——做了 Recon Agent 的活，导致：
- 任务重叠一致性差（同一个事实两个 agent 给出不同结论）Orchestrator 被一堆冗余信息淹没
修复：每个 sub-agent 的 prompt 末尾加一段"严格禁止"清单，列明它不能做什么。
坑 3：RLM child 的输出格式不一致
第三版的 RLM 10 个 child 各自输出 markdown，结果汇总时发现格式五花八门——有的有 emoji 有的没有、有的列表用 - 有的用 *、有的字段缺失。
修复：RLM child 的 prompt 强制要求输出 JSON给一个 JSON schema 让 child 严格遵守在 Code Review Agent 里加一个
校验步骤：如果某个 child 输出不合格，
重试一次（最多 2 次）
坑 4：Risk Analyst 把"分析"和"判断"混在一起
第四版的 Risk Analyst 输出是一大段散文式分析，最后藏一句结论。问题：
- 用户找结论要扒半天自动化下游消费（比如"如果不推荐就发邮件提醒"）做不了
修复：强制 Risk Analyst 输出两段式——先一段结构化判断（JSON），再一段自由文字解释。结构化部分必须包含 recommendation: 强烈推荐 | 推荐 | 谨慎 | 不推荐。
坑 5：失败处理没设计
跑这套工作流，约 15% 的运行会卡死。原因五花八门：
- GitHub API 限流某个文件读取超时RLM child 返回了不合法 JSON网络抖动
修复：每个 sub-agent 加 3 次重试 + 退避RLM child 失败的，忽略它，继续用其他 9 份做汇总
-
- （不要为 1 个 child 卡住整个流程）Orchestrator 必须能处理"sub-agent 部分失败"的情况，给出"评估完成度 80%"这种带置信度的结论在最终报告里
显式标注哪些数据缺失
六、放大思路：这套架构能套到多少其他场景
repo 尽调 只是一个具体例子。这套"orchestrator + 角色化 sub-agent + RLM batch + 综合判断" 的架构是个通用模式，至少可以套到这些场景：
1. 招聘简历筛选
- Recon Agent: 提取简历元数据（学校 / 公司 / 年限）Skill Match Agent: 用 RLM batch 对简历每个项目并行做技能 matchingCulture Fit Agent: 读自我介绍，分析价值观Synthesizer: 综合输出"是否进入下一轮 + 理由"
2. 客户 ticket 智能分诊
- Triage Agent: 看 subject 决定大类Detail Extractor: 用 RLM 并行抽取每条 ticket 的关键字段Routing Agent: 综合判断该转给哪个 team
3. 财报 / 论文摘要
- Section Extractor: 拆出每个章节RLM batch: 每个章节并行做摘要Synthesizer: 综合出整篇要点
4. 长视频 / 长会议总结
- Audio Splitter (脚本): 切成 10 分钟一段RLM batch: 每段并行做摘要Timeline Builder: 按时间线汇总成一份会议纪要
5. 大型代码库 onboarding
- Structure Agent: 扫清目录结构Module Reviewer (RLM): 并行 review 每个核心模块Architecture Synthesizer: 输出一份"新人入门架构图 + 重点文件指南"
只要你的任务能拆成"信息采集 + 并行处理 + 综合判断"三段，这套架构就能用。
七、什么时候不要用多 agent
多 agent 架构虽然强，但不是所有任务都该这么搞。
不要用多 agent 的场景
单步就能完成的任务
-
- —— 一个简单 prompt 就够了
需要严格上下文连贯的任务
-
- —— 比如长篇创作，sub-agent 互相不知道对方在写什么会出问题
实时性要求高的任务
-
- —— 多 agent 编排有协调开销，至少几秒到几分钟，不适合做实时响应
预算极敏感的任务
-
- —— 多 agent 的"协调成本"是真金白银的 token，简单任务这套架构反而更贵
你自己都没想清楚流程的任务
-
-
- —— 多 agent 编排要求你
先把流程拆清楚
- 。如果你自己都不知道该怎么做，让多个 agent 协作只会乱上加乱
-
决策树
任务能用一个 prompt 完成吗？
├── 能 → 一个 prompt 搞定
└── 不能 → 任务能分成清晰的步骤吗？
├── 不能 → 用单 agent + tool calling loop
└── 能 → 步骤之间能并行吗？
├── 不能 → 单 agent 多步执行
└── 能 → 是否有"批量同质子任务"？
├── 没有 → 单层 sub-agent 编排
└── 有 → 多 agent + RLM batch（今天讲的架构）
八、给你的实战建议
如果你看完想自己搭一套，我的建议：
第一周：
- 挑一个你每周做 3-5 次的任务（不要挑你不熟的）用纸笔画出来你自己做这件事的步骤标出哪些步骤能并行、哪些要串行标出哪些步骤需要"创造"（用强模型）、哪些需要"机械执行"（用弱模型 / 脚本）
第二周：
- 用 DeepSeek-TUI 或 Hermes Agent 实现 v0.1 版本——只用 2-3 个 sub-agent，不要一上来就堆 5 个跑通端到端，先不优化
第三周：
- 加 RLM batch（如果有批量子任务的话）加每个 sub-agent 的"严格禁止"边界加结构化输出 + 校验
第四周：
- 写 eval set（参考上一篇 skill 的方法）加失败处理（重试、降级、部分失败）加监控（每个 agent 的耗时 / 成本 / 成功率）
一个月之后，你就拥有了一套真正可以放进生产 的多 agent 工作流。
更重要的是，你掌握了一种"思考问题的方式"：把复杂任务拆成"角色 + 流程 + 数据流"，让 LLM 各司其职。这种思维一旦建立，你能套到的场景几乎是无限的。
写在最后
我的体会是：多 agent 编排的难度，80% 在产品设计，20% 在工程实现。
工程实现不难——DeepSeek-TUI / Hermes Agent / Claude Code 都提供了完整的 sub-agent 和 RLM API，你只要按文档调就行。
难的是产品设计：
- 任务该怎么拆？边界该划在哪？哪些用强模型？哪些用弱模型？哪些根本不该用 LLM？失败时怎么降级？
这些问题没有标准答案。只有你自己反复跑、反复改、反复踩坑，才能形成判断。
但一旦你形成了这种判断，你就拥有了在 AI 时代构建复杂系统的核心能力。这种能力不会过时——模型会换、工具会换、平台会换，但"如何用 agent 协作解决复杂问题"这种思维会越来越值钱。
