---
name: auto
version: "2.2.0"
category: auto
description: "当需要编排复杂目标时使用：拆解为可执行子任务、并行调度、汇总结果。不要用于单一技能任务（用 easy）或已知技能名时（用 expert）。Use when you need orchestration of complex goals: decompose into executable sub-tasks, dispatch in parallel, and aggregate results. Do NOT use for single-skill tasks (use easy) or when skill name is already known (use expert)."
triggers:
  zh: ["auto", "编排", "复合", "全面", "完整实现", "整套", "端到端"]
  en: ["auto", "orchestrate", "full implementation", "end to end", "complete"]
---

# 自动编排 / Auto Orchestration

## Changelog / 版本履历

| 日期 | 版本 | 变更摘要 |
|------|------|---------|
| 2026-06-25 | 2.2.0 | **Agent Architecture Integration**: Updated to reference new agent profiles (orchestrator) instead of hardcoded models, added agent architecture documentation |
| 2026-06-18 | 2.1.0 | **meta-skill.yaml 集成**: 双配置源 (skill-map.yaml + meta-skill.yaml)，新增「Task Creation / 任务创建」章节，调度算法引入 meta-skill dispatch 建议，Dispatch Reference 中文优先增强 |
| 2026-06-17 | 2.0.1 | Task 8 规范化：修复 YAML 分隔符、描述格式、添加 Core Concept 章节、内容分隔符替换 |
| 2026-06-16 | 2.0.0 | **Executable dispatch**: concrete task()/skill() orchestration, skill-map.yaml integration, batch execution engine, result aggregation |
| 2026-06-16 | 1.0.0 | 初始版本：概念设计（不可执行） |

## Core Concept / 核心概念

### 🇨🇳
一句话说清：输入什么 → 做什么 → 输出什么。明确 **不做什么**。

**输入**: 复合目标描述 | **输出**: 自动执行报告（汇总所有子任务结果） | **不负责**: 直接执行具体任务逻辑、替代 easy 做意图路由、替代 expert 做参数透传

### 🇺🇸
One line: Input → Process → Output. Explicitly state what is **NOT done**.

**Input**: Complex goal description | **Process**: Read skill-map.yaml → Analyze → Decompose → Dispatch → Aggregate | **Output**: Auto Execution Report | **NOT responsible for**: Direct task execution, replacing easy for intent routing, replacing expert for parameter passthrough

***

## Agent Architecture Integration / 代理架构集成

The Auto skill integrates with the new agent architecture through **agent profiles** defined in `opespro-opencode-ai.json` and referenced in `meta-skill.yaml`. 

- **Agent Profile**: `orchestrator` (maps to `livedata/deepseek-v4-pro`)
- **Role**: Task orchestration and complex goal decomposition
- **Usage**: Auto uses this profile when executing orchestration tasks via `task(category="deep", load_skills=["auto"], ...)`

This integration ensures Auto leverages the appropriate model capabilities while maintaining backward compatibility with existing workflows.

***

## How Auto Actually Works / 实际执行模型

### 关键理解：Auto 不是一个独立程序，它是一个编排协议

当你调用 `/auto` 时，发生的实际流程：

```
1. Auto SKILL.md 被加载到主 AI (Sisyphus) 的上下文中
2. Sisyphus 按照本 SKILL.md 的编排协议执行：
   a. 读取 skill-map.yaml → 获取完整技能地图和编排模式
   b. 读取 meta-skill.yaml → 获取调度配置和 agent_profile 建议
   c. 分析目标 → 提取 domain 和约束
   d. 拆解为子任务 → 映射到具体 skill
   e. 用 task() 启动子 agent（category/load_skills 优先来自 meta-skill）
   f. 收集 background_output() 结果
   g. 汇总为最终报告
```

**Auto 不直接写代码，但它用 `task()` 指令子 agent 去写。**
- Auto = 总指挥（分析、拆解、调度、汇总）
- 子 Agent = 工人（加载 skill，执行具体任务）
- `skill-map.yaml` = 资源清单（Auto 知道有哪些工人可用）

***

## Position / 定位

```
用户输入复杂目标 / User inputs complex goal
        │
        ▼
    auto (L0 - 编排层 / Orchestration)
        │
        ├── 1. Read skill-map.yaml + meta-skill.yaml ──→ 获取所有可用技能 + 调度配置
        │
        ├── 2. Analyze 分析目标 ──→ 提取 domain + constraints
        │
        ├── 3. Decompose 拆解 ──→ [子任务1, 子任务2, ...]
        │
        ├── 4. Dispatch 调度 ──→ task(category="[来自 meta-skill]", load_skills=["[来自 meta-skill]"], ...)
        │                    └── 无依赖的子任务并行启动
        │                    └── 有依赖的子任务按序执行
        │
        └── 5. Aggregate 汇总 ← background_output(task_id="bg_...")
        │
        ▼
    Auto Execution Report / 自动执行报告
```

### 与 easy / expert 的关系

| 模式 | 适用场景 | 调度方式 |
|------|---------|---------|
| **easy** | 单一需求，不知技能名 | AI 分析关键词 → 加载对应 skill → 执行 |
| **auto** | 复合需求，多技能协作 | 读取 skill-map.yaml → task() 批量调度 → 汇总 |
| **expert** | 精确控制，已知技能名 | 直接加载指定 skill → 执行 |

***

## Configuration / 配置

> Auto 启动时自动读取以下配置文件。

| 配置文件 | 用途 | 必填 |
|---------|------|------|
| `config/skill-map.yaml` | 完整技能能力映射表（输入/输出/依赖/调度方式） | ✅ |
| `../meta-skill.yaml` | 技能协议注册表（元数据、触发词、dispatch 建议、agent_profile） | ✅ |

**配置读取规则**：
1. Auto 被调用时，首先读取 `config/skill-map.yaml` 和 `../meta-skill.yaml`
2. 缺失任一配置 → 🔴 CRITICAL → 终止，提示创建缺失文件
3. 每次调用都重新读取（支持热更新）
4. `skill-map.yaml` 提供 **编排模式**（patterns），`meta-skill.yaml` 提供 **调度配置**（dispatch）— 两者互补

***

## Workflow / 工作流程

### Step 0: Load Skill Map (前置)

**读取 `config/skill-map.yaml` 和 `../meta-skill.yaml`**，加载所有可用技能的能力映射和调度配置。

两个配置文件的定位：
- `skill-map.yaml` → **编排模式**（patterns）：定义常见任务的串行/并行执行顺序，是 Auto 拆解目标的参考蓝图
- `meta-skill.yaml` → **调度配置**（dispatch）：定义每个技能的 `category`、`load_skills`、触发词，是 Auto 生成 `task()` 调用的参数来源

出错处理：
- 文件不存在 → 🔴 CRITICAL → 终止：「Auto 需要 skill-map.yaml 和 meta-skill.yaml 才能工作。请确保两个文件都存在。」
- `meta-skill.yaml` 中某技能的 `dispatch` 字段缺失 → 🟡 WARN → 跳过该技能，继续编排其他技能

### Step 1: Analyze / 分析 — 理解目标

解析用户输入，提取：
- **目标类型**: 实现/检查/修复/审计/分析/迁移/重构
- **涉及领域**: quality/workflow/tools/expert/java/frontend/database/api
- **约束条件**: 文件范围、不能修改的生产代码、时间限制
- **期望输出**: 代码实现/报告/方案/修复

**输出格式** (JSON):
```json
{
  "goal": "完整实现用户登录模块，含安全审计",
  "domains": ["api", "java", "database", "frontend", "quality"],
  "constraints": ["API 用 Spring Boot", "前端用 Vue 2 + Element UI"],
  "expectedOutput": "完整代码 + 安全审计报告"
}
```

### Step 2: Decompose / 拆解 — 生成子任务

对照 `skill-map.yaml`，将目标拆解为原子子任务。每个子任务映射到一个具体 skill。

**拆解规则**：
1. 每个子任务 = 一个 `task()` 调用，加载一个 skill
2. 参考 `skill-map.yaml` 中的 `patterns` 找到匹配的任务模式
3. 参考 `meta-skill.yaml` 中对应技能的 `dispatch` 字段获取 `category` 和 `load_skills` 建议
4. 标注依赖关系 (`dependsOn`)
5. 标注是否可以并行执行 (`parallel: true`)

**输出格式** (JSON):
```json
{
  "tasks": [
    {
      "id": "1",
      "skill": "ba",
      "goal": "分析登录模块业务需求，输出功能规格和CRUD矩阵",
      "category": "deep",
      "load_skills": ["pdd-ba"],
      "dependsOn": [],
      "parallel": false
    },
    {
      "id": "2",
      "skill": "db-query",
      "goal": "基于BA分析结果设计用户表、会话表，输出Flyway DDL",
      "category": "deep",
      "load_skills": ["db-query"],
      "dependsOn": ["1"],
      "parallel": true
    },
    {
      "id": "3",
      "skill": "api-design",
      "goal": "设计登录/注册/登出 RESTful API，输出Controller和DTO",
      "category": "deep",
      "load_skills": ["api-design"],
      "dependsOn": ["1"],
      "parallel": true
    }
  ]
}
```

> 🔴 **中断条件**: 子任务数 > 10 → 展示拆解计划，等待用户确认后再执行。
> 🟡 **中断条件**: 子任务数 > 5 → 展示拆解计划（但不需要确认即可执行）。

### Step 3: Dispatch / 调度 — 并行执行子任务

这是 Auto 的核心——将拆解结果转换为实际的 `task()` 调用。

**调度算法**：

```
1. 找出所有 dependsOn 为空的子任务 → 第一波并行
2. 对每个子任务，从 meta-skill.yaml 查找 dispatch 配置：
   - 若 meta-skill.yaml 中有该技能的 dispatch 条目 → 使用其建议的 category 和 load_skills
   - 若 meta-skill.yaml 中无该技能 → 使用 skill-map.yaml 中的默认 dispatch 配置
3. 构建 task() 调用：
   task(
     category="[从 meta-skill.yaml dispatch.category 获取]",
     load_skills=[从 meta-skill.yaml dispatch.load_skills 获取],
     run_in_background=true,    ← 关键：后台运行，不阻塞
     description="[简短中文描述]",
     prompt="[完整的任务指令，包含 GOAL + CONTEXT + CONSTRAINTS]"
   )
4. 记录每个子任务返回的 bg_... ID
5. 第一波全部完成后，启动第二波（依赖已解决）
6. 重复直到所有子任务完成
```

> **meta-skill agent_profile 建议**：`meta-skill.yaml` 中每个技能的 `dispatch` 字段相当于该技能的 **agent_profile**——定义了该技能应该用哪个 `category`（deep/quick/visual-engineering）启动子 Agent，以及需要加载哪些 skills。Auto 在调度时直接读取这些建议，无需手动指定参数。

**每个子任务的 prompt 必须包含 6 个要素**：
```
1. TASK: 原子目标（一个 skill 一次调用能完成的事）
2. EXPECTED OUTCOME: 具体交付物 + 成功标准
3. REQUIRED TOOLS: 明确工具白名单
4. MUST DO: 必须完成的步骤
5. MUST NOT DO: 禁止的操作
6. CONTEXT: 文件路径、已有模式、上游任务的输出
```

***

## Task Creation / 任务创建

> 中文优先的 `task()` 调用参考。以下示例展示如何将拆解结果转换为具体的子 Agent 调度指令。

### 基础模板 / Basic Template

```typescript
// 标准 task() 调用 — 中文优先 / Standard task() invocation — Chinese-first
task(
  category="deep",
  load_skills=["skill-name"],
  run_in_background=true,
  description="简短中文任务描述",
  prompt="完整的任务指令（中文）..."
)
```

### 常见调用模式 / Common Invocation Patterns

> 详见: [task-patterns.md](references/task-patterns.md) - 包含 10 种常见场景的完整示例（代码审查、数据库设计、API 设计、后端实现、前端组件、安全审计、并行审计、需求分析管线、Bug 修复循环、完整模块实现）

### 关键参数说明 / Key Parameter Reference

| 参数 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `category` | `string` | 子 Agent 类别。来自 `meta-skill.yaml` 的 `dispatch.category` 建议 | `"deep"`, `"quick"`, `"visual-engineering"` |
| `load_skills` | `string[]` | 需加载的技能列表。来自 `meta-skill.yaml` 的 `dispatch.load_skills` 建议 | `["code-review"]`, `["db-query", "api-design"]` |
| `run_in_background` | `boolean` | 必须为 `true`（Auto 依赖后台并行调度） | `true` |
| `description` | `string` | 简短中文任务标签（用于日志和报告） | `"审查登录模块代码质量"` |
| `prompt` | `string` | 完整的任务指令（中文优先），必须包含 TASK + EXPECTED OUTCOME + MUST DO + MUST NOT DO + CONTEXT | 见上方示例 |

> **参数来源优先级**：`category` 和 `load_skills` 优先从 `meta-skill.yaml` 的 `dispatch` 字段获取。若 meta-skill.yaml 无该技能，回退使用 `skill-map.yaml` 的默认值。

### Step 4: Wait & Collect / 等待与收集

**后台任务的生命周期**：

1. `task(run_in_background=true)` 返回 `bg_xxx` ID
2. 系统在后台运行子 agent
3. 子 agent 完成后，系统发送 `<system-reminder>` 通知
4. Sisyphus 在收到通知后调用 `background_output(task_id="bg_xxx")` 获取结果
5. 检查结果有效性：
   - ✅ 成功 → 记录输出，解除下游依赖
   - ❌ 失败 → 🟡 WARN → 记录失败原因，继续执行不依赖它的后续任务

**重要**：不要在子 agent 还在运行时 poll `background_output()`。等待 `<system-reminder>` 通知。

### Step 5: Aggregate / 汇总

所有子任务完成后（成功或失败），生成汇总报告：

```markdown
# Auto Execution Report / 自动执行报告

## Goal / 目标
完整实现用户登录模块，含安全审计

## Summary / 总览
- Total tasks: 7 | Success: 6 | Failed: 1
- Parallel waves: 3

## Task Results / 子任务结果

### ✅ Task 1: BA 需求分析 [ba]
- Status: Success
- Output: 功能规格书 + CRUD矩阵

### ❌ Task 4: 后端实现 [java-spring]
- Status: Failed
- Reason: 缺少依赖配置

## Final Output / 最终交付
- ✅ 功能规格书
- ✅ 数据库 DDL
- ❌ 后端 Service 实现（Task 4 失败，需手动处理）
```

***

## Dispatch Reference / 调度速查表

> 详见: [dispatch-reference.md](references/dispatch-reference.md) - 包含按任务目标选择 Skills 的映射表、按领域选择 Category 的映射表（来自 meta-skill.yaml dispatch 建议）
>
> 完整映射见 `config/skill-map.yaml`（编排模式）和 `../meta-skill.yaml`（dispatch 配置）。

***

## Iron Law / 核心铁律

### 🇨🇳
1. **只编排不写代码**: Auto 不直接调用 write/edit 工具修改业务代码。它用 `task()` 调度子 agent 去写。唯一的例外：Auto 可以写汇总报告文件。
2. **必须先读双配置源**: 每次被调用，第一步就是读取 `skill-map.yaml`（编排模式）和 `meta-skill.yaml`（dispatch 配置）。缺少任一文件则终止。
3. **拆解前确认**: 子任务数 > 5 时展示计划。> 10 时必须等用户确认。
4. **失败不阻塞**: 子任务失败 ≠ 整体失败。记录失败原因，继续执行不依赖它的后续任务。
5. **依赖保序**: 严格按 `dependsOn` 顺序执行，上游未完成不启动下游。
6. **并行最大化**: 无依赖的子任务必须并行启动（同时调用多个 `task(run_in_background=true)`）。
7. **Prompt 必须完整**: 每个子任务的 prompt 必须包含 TASK + EXPECTED OUTCOME + MUST DO + MUST NOT DO + CONTEXT。
8. **参数优先查 meta-skill**: `task()` 的 `category` 和 `load_skills` 参数优先从 `meta-skill.yaml` 的 `dispatch` 字段获取。

### 🇺🇸
1. **Orchestrate, don't code**: Auto never calls write/edit on business code. It uses task() to spawn sub-agents. Exception: final report writing.
2. **Read both config sources first**: Every invocation starts by reading `skill-map.yaml` (patterns) and `meta-skill.yaml` (dispatch). Abort if either is missing.
3. **Confirm before large decompositions**: Show plan when > 5 tasks, confirm when > 10.
4. **Failure is non-blocking**: Log failures, continue independent downstream tasks.
5. **Respect dependencies**: Strictly follow dependsOn order.
6. **Maximize parallelism**: Independent tasks MUST be launched in parallel.
7. **Complete prompts**: Every sub-task prompt MUST include TASK + EXPECTED OUTCOME + MUST DO + MUST NOT DO + CONTEXT.
8. **Check meta-skill first for dispatch params**: `category` and `load_skills` for `task()` calls are sourced from `meta-skill.yaml`'s `dispatch` field first.

***

## Rationalization Table / 合理化防御表

| # | Trap / 陷阱 | Question / 请问自己 | Action / 应该怎么做 |
|---|-------------|------------------|------------------|
| 1 | "这个任务太简单了，不需要拆解，我自己做就行" | 手动做真的比拆解+并行调度更快吗？ | 即使是简单任务也拆解为 2-3 个原子子任务，并行执行 |
| 2 | "下游任务不等上游结果也可以开始" | 上游输出是否真的是下游的必需输入？ | 严格检查 `dependsOn` 关系，上游未完成绝不启动下游 |
| 3 | "子任务失败了应该还能凑合用" | 失败的结果是否真的能用于下游决策？ | 标记失败，记录原因，不传递不可靠的输出到下游 |
| 4 | "给子 agent 的 prompt 简单写写就行" | 模糊的 prompt 会导致什么后果？ | 每个 prompt 必须包含完整的 6 要素 |

***

## Red Flags / 三层防御

### Layer 1: Input / 输入
- **INPUT-01**: 用户目标模糊不可拆解 → 🟡 WARN → 要求澄清或降级为 easy
- **INPUT-02**: 目标涉及文件修改但未指定范围 → 🟡 WARN → 提示指定范围

### Layer 2: Execution / 执行
- **EXEC-01**: 子任务数 > 10 → 🔴 CRITICAL → 展示计划，等用户确认
- **EXEC-02**: 3 个连续子任务失败 → 🔴 CRITICAL → 中断，输出失败原因诊断
- **EXEC-03**: 检测到循环依赖 → 🔴 CRITICAL → 中断，修正拆解方案
- **EXEC-04**: skill-map.yaml 或 meta-skill.yaml 不存在 → 🔴 CRITICAL → 终止，提示创建缺失文件

### Layer 3: Output / 输出
- **OUTPUT-01**: 汇总报告缺少任一子任务结果 → 🟡 WARN → 标注「未完成」
- **OUTPUT-02**: 最终输出与原始目标不一致 → 🔴 CRITICAL → 重新分析

***

## Output / 输出规范

### 🇨🇳
最终输出为 Markdown 格式的 Auto Execution Report，包含：
1. 原始目标
2. 执行摘要（total/success/failed/waves）
3. 每个子任务的详细结果（status/output/session）
4. 最终交付物总结

### 🇺🇸
Final output is an Auto Execution Report in Markdown, containing:
1. Original goal
2. Execution summary (total/success/failed/waves)
3. Detailed results per sub-task (status/output/session)
4. Final deliverables summary

***

## Auto-Review / 自检清单

> 详见: [auto-review.md](references/auto-review.md) - 包含 8 项自检清单（子任务结果、依赖关系、目标覆盖、代码修改、报告格式、配置读取、prompt 完整性、dispatch 参数来源）

***

## §Orchestration Optimizations / 编排优化 (2026-06-24)

Add these improvements learned from V12 orchestration:

### 1. Same-File Sequential Dispatch
When multiple tasks modify the SAME file, run them SEQUENTIALLY not parallel to avoid Edit tool conflicts. Pattern:
```
if (tasks_all_modify_same_file) {
  dispatch_sequentially();
} else {
  dispatch_parallel();
}
```

### 2. Prompt Length Limit
Long prompts (>2000 chars) cause dispatch failures ("Expected 'function.name' to be a string"). Keep prompts concise: <1500 chars for quick tasks, <2500 for deep tasks.

### 3. Frontend Bug Fix Delegation
For CSS-only fixes (selector changes, style adjustments), prefer single comprehensive task over multiple micro-tasks. Example: combine "fix card overlap" + "fix drawer" + "fix breadcrumb" into ONE dispatch.

### 4. Visual-Engineering Category Preference
When the task involves HTML/CSS/visual changes, use `category="visual-engineering"` instead of `category="deep"`. The visual-engineering category uses the appropriate agent profile configured in opespro-opencode-ai.json for optimal CSS/HTML output.

### 5. Git Commit Strategy
Group related changes into single commits:
- Wave 1 tasks → single commit (e.g., "docs: update design docs")
- Wave 2 tasks → single commit (e.g., "feat: add HTML structure")
- Fix tasks → single commit (e.g., "fix: CSS and interaction bugs")
- Never commit mid-wave — commit only after all tasks in a wave complete.

### 6. Verification Budget
For minor CSS-only fixes, skip full verification cycle (read→greas→diagnostics). Pattern:
```
if (change_is_css_only && lines_modified < 20) {
  quick_grep_verify(); // 1 check, not full cycle
} else {
  full_verification_cycle(); // Phase 1-4
}
```