多个智能体协作时的麻烦，往往不是模型能力不够，而是角色边界没定就开始跑：两个智能体抢同一件事，或者一个在等另一个永远不会给出的结果。比较稳的顺序是先拆出能独立交付的子任务，把每个智能体的输入、输出、停止条件写进配置，再用两个智能体跑一次真实交接，最后看运行记录里有没有重复劳动和空转。Agensh 的具体字段名以你本地版本为准，下面给的是通用骨架，替换成自己的模型、工具和路径即可。
面对“拆几份、每个智能体管什么”的问题，判断依据是子任务能否只靠自己的输入产出可检查的结果。动作上：先拆任务并画出依赖顺序，再把角色边界落到输入、输出、停止条件三个字段，用两个智能体跑一次交接。验证方式是看运行记录里的发起方、接手方、交接次数和产出重复条目。风险边界在于：拆分过细会制造等待，停止条件写成“直到满意”则无法判定；涉及真实写操作的任务建议先只读跑通再放开。
把一次任务拆成几个能独立交付的子任务
拆分的判据只有一条：这个子任务能不能只靠自己的输入完成，并交出一份别人能检查的产物。如果两个子任务必须共享同一份中间结果、并且交替修改它，说明拆得太细，先合并成一个。反过来，如果某个子任务的产物需要另一方的结论才能开始，那就是有效依赖，按先后顺序排好即可，不要试图让两个智能体并行啃同一段。
以一个“整理接口变更说明”的任务为例，可以拆成三个子任务：
- 收集变更点（输入：代码差异或提交记录；输出：变更点清单）。这一层内部还可以继续并列为“接口签名变更”和“配置项变更”两个互不依赖的子任务。
- 撰写说明（输入：变更点清单；输出：说明草稿）。依赖收集变更点，必须等清单齐备才能开始。
- 校对补充（输入：说明草稿；输出：问题列表或修订稿）。依赖撰写说明。
依赖关系是“收集 → 撰写 → 校对”的串行链，只有收集环节内部可以并行。拆到这个程度，每个子任务都能独立交付，运行中不会出现两个智能体同时改同一段文字的情况。
给每个智能体写清输入、输出和停止条件
角色边界如果不落到字段上，写在提示词里也只是一句愿望。通用的角色描述骨架大致包含五块：这个角色负责什么、不负责什么、输入从哪来、输出长什么样、什么情况下停。下面是 YAML 风格的通用写法，字段名与嵌套方式按 Agensh 实际配置调整，不必照抄：
role: collector # 角色标识，handoff 时用来指定接手方
scope:
does: 把代码变更整理成变更点清单
does_not: 不写文案、不改代码、不判断发布节奏
input:
source: change_diff # 替换为你自己的输入通道：文件、工具输出或上游产物
format: 每行一条变更记录
output:
field: change_points
schema: 每条含 文件路径、变更类型、影响范围
stop_when:
- change_points 非空，且每条字段齐全
- 或达到 max_turns 上限后交回当前结果
handoff_to: writer # 交给下游角色，没有下游就留空停止条件是整份配置里最容易写坏的地方。“直到满意为止”“尽可能完整”这类描述在运行时无法判定，智能体会一直追加内容或反复自我检查。可判定的写法只有两类：一是产物满足某个可校验的结构条件，比如字段齐全、条数大于零、能通过一次格式检查；二是轮次或时间上限，到点就交出当前结果并标记未完成。两类建议同时写，前者管质量，后者管兜底。
用两个智能体跑通一次任务交接
不要一上来就铺五六个角色。先用两个智能体跑一次真实交接，确认“上游产出被下游正确接住”这条链路是通的，再往两边加人。下面是双智能体的最小配置骨架，除角色描述外，其余值都要换成你自己的模型、工具和路径：
agents:
- name: collector
model: your-model-name # 换成你实际可用的模型标识
tools: [read_diff] # 换成你自己的只读工具
role_file: ./roles/collector.yaml
- name: writer
model: your-model-name
tools: [write_doc]
role_file: ./roles/writer.yaml
flow:
- from: collector
to: writer
payload: change_points # 交接时传的字段，必须和上游 output.field 一致
on_empty: abort # 上游产物为空时不进入下游，避免空转
run:
max_turns: 6
trace: ./run-01.log调用命令按本机安装的 CLI 为准，下列写法只表示参数顺序，命令名与选项需要按实际版本替换：
# 占位示例：命令名、选项名以本机 agensh `--help` 输出为准
agensh run `--config` ./agents.two.yaml `--task` ./task.md `--trace` ./run-01.log跑完先别改配置，直接看 run-01.log 里有没有发生交接：如果 writer 从未被调用，通常是 payload 字段名和上游 output.field 对不上；如果 writer 被调用但输入为空，检查上游停止条件是不是在产物为空时就判了完成。
在运行记录里确认有没有重复劳动或空转
分工是否有效，不用凭感觉判断，把问题变成日志里能看到的四个字段就够：
- 谁发起：每条产物的来源角色。同一类产物出现两个不同来源，基本就是职责重叠。
- 谁接手：下一次交接的接收角色。如果某角色连续多轮没有被接手，说明它在空转或在做无人消费的活。
- 耗时：每个角色的起止时间。某角色耗时远高于其他角色，通常意味着它的停止条件不可判定，或者它承担了超出职责范围的工作。
- 产出重复度：把同类产物的条目做一次人工或规则比对，看两条记录是否描述同一件事。
判定标准可以保守一些：同一轮内出现两个角色产出内容高度重合的条目，就视为职责重叠，回到角色描述里划清 does / does_not；某角色连续两轮产出没有被下游引用，视为空转，检查它是否应该被合并或删除；交接次数明显多于子任务数量，说明拆分过细，存在无意义的来回传递。
改一版角色描述再跑，对比两次结果
调整时一次只改角色描述，任务、模型、工具保持不变，否则对比没有意义。改完用同样的命令再跑一次，输出到 run-02.log。对比时只看两项指标：
- 交接次数：两次运行的交接条数。次数下降且任务仍能完成，说明角色边界更清晰；次数下降但任务没跑完，说明边界划得太粗，把必要的依赖也切掉了。
- 重复产出条目：两次运行中同类产物的重合条目数。这一项减少，才说明职责重叠真的被消除了。
两项一升一降时不要急着下结论，先回到日志确认具体是哪一条产物重复、哪一次交接多余。通常调整两三轮就能收敛到稳定分工；如果反复修改仍出现重复劳动，多半是任务本身拆得不对，应该回到第一步重新划分独立子任务，而不是继续在角色描述上打磨措辞。