用途
oa-dispatch 用于通过 oneagent（oa）把范围明确的编码任务派发给另一个 AI 模型或后端执行。适合并行处理工作、利用特定模型的长处，或在继续其它工作的同时把一项定义清晰的编辑任务外包出去。
何时派发
派发最适合目标明确、自成一体且指令清楚的任务：
- 编辑指定文件或函数
- 为某个模块生成测试套件
- 按某种模式重构一段代码
- 针对特定关注点（安全、性能等）审查文件
不要派发含糊或开放式任务。接收任务的智能体无法访问你的对话上下文，因此提示词必须自包含。
基本命令
应始终把提示词通过管道传给 oa，而不是作为参数传入，以避免提示词内容出现在进程列表（ps aux）中：
echo "<prompt>" | oa -b <backend> -m <model> --thinking <level>
所有标志均为可选。--thinking 控制推理强度，支持级别因后端而异（例如 low、medium、high）。省略则使用后端的默认值。
用于带流式可见性的后台执行：
echo "Edit path/to/file.go: <specific instructions>" | oa -b claude --jsonl
多行提示词可使用 heredoc：
cat <<'EOF' | oa -b codex --jsonl Edit internal/auth/handler.go: add rate limiting to the Login function. Use x/time/rate with a limit of 5 requests per second per IP. Do not modify any other functions. Do not ask for confirmation, just make the edits. Run go test ./internal/auth/... when done. EOF
构造有效提示词
提示词必须包含智能体所需的一切。始终包含：
- 要编辑或读取的文件路径
- 要做什么——对改动要具体
- 约束——不要改什么、要遵循的模式、要通过的测试
好的提示词：
Edit internal/auth/handler.go: Add rate limiting to the Login function. Use x/time/rate with a limit of 5 requests per second per IP. Do not modify any other functions. Do not ask for confirmation, just make the edits. Run go test ./internal/auth/... when done.
差的提示词：
Add rate limiting to the auth system
始终加入 "Do not ask for confirmation, just make the edits" 或类似语句。没有这句时，某些后端可能会做计划或头脑风暴，而不是直接做修改，尤其是当它们带有鼓励 "先计划" 工作流的技能或设置时。
可用后端与模型
内置后端：
- claude，命令 oa -b claude，支持 --thinking，适合默认、通用任务
- codex，命令 oa -b codex，支持 --thinking，适合沙箱化执行
- opencode，命令 oa -b opencode，不支持 --thinking，适合 OpenCode 支持的模型
- pi，命令 oa -b pi，支持 --thinking，通过 Pi 提供广泛模型选择
- gemini，命令 oa -b gemini，不支持 --thinking，适合 Gemini CLI 模型
指定特定模型或推理级别：
echo "prompt" | oa -b pi -m openai-codex/gpt-5.4 echo "prompt" | oa -b claude -m sonnet --thinking high echo "prompt" | oa -b codex --thinking high
运行 oa list 查看所有已配置后端。
后台运行
把派发作为后台任务运行，以便继续工作：
Background with JSONL streaming (can inspect progress)
echo "Edit file.go: add error handling to ProcessOrder" | oa -b codex --jsonl &
Or with a specific model via Pi
echo "Edit file.go: add error handling to ProcessOrder" | oa -b pi -m openai-codex/gpt-5.4 --jsonl &
任务完成后验证改动：
git diff path/to/file.go
超时：派发任务可能需要 30 秒到 30 分钟不等，取决于复杂度。在 shell 工具中运行 oa 时，应设置至少 10 分钟（600000ms）的超时。默认的 2 分钟超时会过早终止大多数非平凡任务。
并行规则：只要任务编辑的是不同文件，就可以并行派发多个任务。如果多个任务涉及同一个文件，应顺序运行——否则后一个任务可能覆盖或与前一个任务冲突。
使用线程处理多步骤任务
当任务需要后续工作时，使用线程来携带上下文：
First pass with Claude
echo "Refactor internal/auth/handler.go to extract middleware" | oa -b claude -t refactor-auth
Follow-up on the same thread, different backend
echo "Now add tests for the extracted middleware" | oa -b codex -t refactor-auth
线程是可移植的——可在线程中途切换后端，上下文会自动延续。
输出模式
- （默认）纯文本结果，适合快速一次性任务
- --json，带 result/session 的规范化 JSON，适合解析最终结果
- --jsonl，流式 JSONL 事件，适合实时监控进度
验证结果
继续之前始终验证派发的工作：
- 检查 diff：用 git diff 查看改了什么
- 运行测试：go test ./... 或等价命令
- 阅读输出：检查错误或意外改动
如果结果不对，可以自行修复，或派发一个带有更具体指令的后续任务。
多智能体脚本
复杂派发模式可使用随附脚本：
- scripts/converse.sh —— 两个智能体在共享线程上轮流讨论一个问题，然后把发现综合成行动计划。
bash scripts/converse.sh -a claude -b codex -t 3 "the service crashes after 5 minutes under load"
- scripts/multi-review.sh —— 向不同智能体（安全 + 性能）并行派发代码审查，然后合并成一份摘要。
bash scripts/multi-review.sh
两个脚本都使用线程、管道和钩子——这些原语同样可用于任何自定义工作流。
注意事项
- 被派发的智能体在你的工作目录中运行，但无法访问你的对话历史。每个提示词都必须自包含。
- 如果某个后端 CLI 未安装或未登录，oa 会返回错误。先用 oa list 检查。
- --thread 与 --session 互斥。跨后端连续性用线程，单后端恢复用会话。
- 包含完整文件内容的大型提示词可能触及某些模型的 token 上限。应让智能体指向文件路径，而不是粘贴内容。