一、优秀 Subagent 文档的固定通用结构
下面这 8 块是必备模块
1. 标题
- 格式：
# 子智能体英文名（中文名称） - 作用：清晰标识这个子智能体是谁
2. Role（角色）
- 一句话说明：这个 Subagent 是干嘛的
- 核心价值：它在整个流程里承担什么职责、解决什么问题
- 边界：它不负责什么（避免越界）
3. Inputs（输入）
- 列出所有传入的参数
- 写明：参数名、类型、含义、路径/格式
- 示例：
winner: "A"或"B"、transcript_path: 执行记录路径
4. Process（执行流程）
- 用 Step 1 → Step N 分步写
- 每一步只写具体动作，不抽象
- 顺序就是实际执行顺序
- 强调：先读什么 → 再处理什么 → 最后输出什么
5. 核心规则/判定标准（可选但强烈推荐）
-
如果是打分、判断、分析类 Agent：必须写明确规则
- 什么时候 PASS
- 什么时候 FAIL
- 证据怎么取
- 模糊情况怎么处理
6. Output Format（输出格式）
- 必须给 完整 JSON 示例
- 结构严格、字段固定
- 示例里用占位符，方便直接复制
7. Field Descriptions（字段说明）
- 解释 JSON 里每个字段的含义
- 类型：bool / string / array / number
- 什么时候有值、什么时候为空
8. Guidelines（执行准则）
-
客观、具体、可落地
-
告诉调用方/模型：
- 必须做什么
- 绝对不能做什么
- 怎么保证一致性
- 优先级/判断逻辑
二、写作黄金原则（照着写就不会错）
- 全程面向“执行”
不写虚话，只写：读什么 → 做什么 → 输出什么。
- 步骤必须线性、无歧义
Step 1、2、3… 是人/模型都能一步步跟着跑的。
- 输入输出必须严格结构化
路径、参数名、JSON 结构一字不差。
- 判断规则必须可量化
比如：
- 有证据 → PASS
- 无证据 → FAIL
- 表面满足≠实质完成
- 语言统一、工程化
用：transcript、outputs、assertion、expectation、evidence、verdict 这类标准词。
三、直接套用：Subagent 文档通用模板
你把下面内容复制，填空就能写出专业文档：
# XXX Agent（XXX 子智能体）
## Role
【填写：该子智能体的核心定位、在流程中的作用、解决什么问题】
## Inputs
- **param1**: 【含义】
- **param2**: 【含义】
- **file_path1**: 【文件路径含义】
- **output_path**: 【结果保存路径】
## Process
### Step 1: 读取输入数据
1. 读取 XXX 文件
2. 提取 XXX 信息
3. 检查是否存在异常
### Step 2: 处理/分析/执行逻辑
1. 【具体动作】
2. 【具体动作】
3. 【对比/提取/验证…】
### Step 3: 生成结果
1. 汇总信息
2. 按格式构造输出
3. 保存到 output_path
## 判定规则（如适用）
- **PASS 条件**:
1. ...
2. ...
- **FAIL 条件**:
1. ...
2. ...
## Output Format
```json
{
"field1": "value",
"field2": [],
"summary": {}
}
Field Descriptions
- field1: 【含义】
- field2: 【含义】
Guidelines
- 必须基于证据，不主观推测
- 步骤必须完整执行
- 输出必须严格按格式
- ...
---
# 四、你只要告诉我 3 个信息，我可以**直接帮你写完**
1. 你的 Subagent 叫什么？
2. 它要**做什么事**（打分/分析/执行/抽取/对比…）？
3. 输入是哪些文件/参数？
我可以直接给你生成**和上面两份完全同风格、可直接上线使用**的 MD 文档。
