mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
6428febdf6
- Introduced a new agent: universal-executor, designed for versatile task execution across various domains with a systematic approach. - Added comprehensive documentation for Codex subagents, detailing core architecture, API usage, lifecycle management, and output templates. - Created a new markdown file for Codex subagent usage guidelines, emphasizing parallel processing and structured deliverables. - Updated codex_prompt.md to clarify the deprecation of custom prompts in favor of skills for reusable instructions.
86 lines
3.1 KiB
Markdown
86 lines
3.1 KiB
Markdown
# Codex Subagent 使用规范（说明文档）
|
||
|
||
## 1. Subagent 是什么
|
||
|
||
Subagent 是由主 agent（当前对话）临时创建的“并行工作单元”，用于把任务拆分后并行推进；每个 subagent 有独立会话上下文，通过 `agent_id` 标识。
|
||
|
||
## 2. 核心特性
|
||
|
||
- **并行处理**：可同时创建多个 subagent，分别负责调研、方案、测试、实现建议等子任务。
|
||
- **结构化交付**：适合要求 subagent 按固定模板输出（如 `Summary/Findings/Proposed changes/Tests/Open questions`），便于主 agent 汇总合并。
|
||
- **迭代追问**：subagent 首次回包后，主 agent 可继续补充信息、纠偏或扩展任务。
|
||
- **Open questions 工作流**：subagent 可先只提澄清问题；待主 agent 回答后再输出方案与测试建议。
|
||
|
||
## 3. 生命周期与 API 约定
|
||
|
||
### 3.1 创建 subagent
|
||
|
||
- 调用：`functions.spawn_agent({ agent_type?, message })`
|
||
- 返回：`agent_id`
|
||
|
||
建议在 `message` 中明确：
|
||
|
||
- `Goal`：一句话目标
|
||
- `Scope`：可做/不可做（目录、文件类型、是否允许引入依赖、是否允许跑命令）
|
||
- `Context`：最小必要上下文（关键路径、现状摘要、约束）
|
||
- `Deliverables`：强制输出格式
|
||
- `Quality bar`：验收标准
|
||
|
||
### 3.2 获取结果（关键点）
|
||
|
||
- 调用：`functions.wait({ ids, timeout_ms? })`
|
||
- 结果：出现在 `status[agent_id].completed`（subagent 回包内容）
|
||
- 超时：`timed_out=true` 不等于失败，可继续 `wait` 或 `send_input` 催促收敛
|
||
|
||
> 注意：`close_agent` 不是“返回结果”的前置条件；拿结果靠 `wait`。
|
||
|
||
### 3.3 继续追问/纠偏
|
||
|
||
- 调用：`functions.send_input({ id, message, interrupt? })`
|
||
- `interrupt=true`：用于立刻打断并纠偏（慎用，优先用普通追问）
|
||
|
||
### 3.4 结束回收
|
||
|
||
- 调用：`functions.close_agent({ id })`
|
||
- 一旦关闭：该 subagent **不可恢复**；只能重新 `spawn_agent` 新的，并粘贴旧输出/上下文续做
|
||
|
||
## 4. 输出模板（推荐）
|
||
|
||
要求 subagent 统一用以下结构回包，便于合并：
|
||
|
||
```text
|
||
Summary:
|
||
- ...
|
||
|
||
Findings:
|
||
- ...
|
||
|
||
Proposed changes:
|
||
- 文件/模块：
|
||
- 变更点：
|
||
- 风险点：
|
||
|
||
Tests:
|
||
- 需要新增/更新的用例：
|
||
- 需要运行的测试命令（如适用）：
|
||
|
||
Open questions:
|
||
1. ...
|
||
2. ...
|
||
```
|
||
|
||
## 5. 并行拆分建议（高收益模式）
|
||
|
||
- **Worker A（调研）**：定位入口、调用链、相似实现；交付“文件+符号+证据点”，不写方案。
|
||
- **Worker B（方案）**：最小改动实现路径、兼容性与风险；交付“变更点清单”。
|
||
- **Worker C（测试）**：测试策略、边界条件、Mock 点；交付“用例列表+覆盖点”。
|
||
|
||
原则：尽量按“模块/文件域”拆分，避免多个 subagent 同时建议修改同一文件导致冲突。
|
||
|
||
## 6. 常见坑与约定
|
||
|
||
- **不 close 也能拿结果**：`wait` 才是取结果的入口；`close_agent` 只是收尾清理。
|
||
- **关闭不可逆**：想续聊就不要提前 close；若已 close，只能新建并补发上下文。
|
||
- **范围控制**：subagent 只做分配的子任务，超出范围必须在 `Open questions` 里请求确认。
|
||
|