# Agent Workflow Setup：多智能体协作开发工作流的最佳实践

> Agent Workflow Setup是一个可移植的多智能体开发工作流框架，支持Codex和Claude Code双引擎，通过定义标准化角色、共享记忆和严格的质量门禁，实现AI辅助软件开发的标准化和可控化。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-14T16:46:12.000Z
- 最近活动: 2026-06-14T16:53:46.753Z
- 热度: 163.9
- 关键词: AI agent, multi-agent, Codex, Claude Code, workflow, development process, quality gates, audit, GitHub Copilot, software engineering
- 页面链接: https://www.zingnex.cn/forum/thread/agent-workflow-setup
- Canonical: https://www.zingnex.cn/forum/thread/agent-workflow-setup
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: Niko4417
- **来源平台**: GitHub
- **原始标题**: Agent-Workflow-Setup
- **原始链接**: https://github.com/Niko4417/Agent-Workflow-Setup
- **发布时间**: 2026年6月14日

## 背景：AI辅助开发的挑战

随着GitHub Copilot、Claude Code、Codex等AI编程助手的普及，开发者开始探索如何让AI更深入地参与软件开发流程。然而，在实际应用中面临诸多挑战：

1. **缺乏标准化**：不同开发者使用AI的方式各异，难以保证输出质量的一致性
2. **上下文管理困难**：AI助手难以在多次会话间保持上下文连续性
3. **质量门禁缺失**：AI生成的代码缺乏系统性的审查机制
4. **多智能体协调复杂**：当多个AI角色协作时，任务分配和沟通变得混乱

Agent Workflow Setup正是为解决这些问题而设计的系统化方案。

## 项目概述

Agent Workflow Setup是一个可移植的多智能体开发工作流框架，专为Keiko代码库设计（但可适配其他项目）。它支持双引擎架构：

- **主引擎**: GitHub Copilot + Codex
- **备用引擎**: Claude Code

通过符号链接（symlink）安装到目标代码库，保持目标仓库的git历史干净，同时实现工作流的版本控制和团队协作。

### 核心理念

1. **单一协调者（Orchestrator）**：人类只与一个主导智能体交互，由它负责规划、委派和报告
2. **标准化角色**：16个预定义的规范角色，根据任务规模灵活组合
3. **神圣的主分支（dev）**：所有issue都以PR形式提交，只有issue合并到epic分支是自动的，合并到dev需要人工审查
4. **分层质量门禁**：从本地钩子到审计门的多层防护

## 架构与组件

### 目录结构

```
docs/                    # 文档
  workflow-contract.md   # 工作流契约（规则）
  workflow-blueprint.md  # 架构设计文档
  example-workflow.md    # 示例工作流

.agents/                 # 智能体配置
  roles.yaml             # 角色定义
  aliases.yaml           # 别名配置
  memory/<role>/         # 各角色的共享记忆

codex/                   # Codex引擎配置（主引擎）
  config.toml            # 主配置
  RUNBOOK.md             # 运行手册
  agents/*.toml          # 智能体配置
  playbooks/             # 剧本
  hooks/                 # Git钩子

claude/                  # Claude引擎配置（备用）
  settings.json          # 设置
  agents/*.md            # 智能体定义
  teams/                 # 团队配置
  skills/<name>/SKILL.md # 技能定义

scripts/                 # 工具脚本
  install.sh             # 安装脚本
  verify.sh              # 本地CI镜像
  keiko-watch            # 实时监控
  consolidate-memory     # 记忆预算检查

templates/               # 模板
  target-side gate snippets  # husky / lint-staged / PR证据模板
```

### 关键概念

**角色（Roles）**

工作流定义了16个规范角色，存储在 `.agents/roles.yaml` 中。角色根据任务规模灵活组合：

- **小型任务**：单个角色独立完成
- **中型任务**：3-5个角色协作
- **史诗级任务（Epic）**：完整角色集群

两个引擎共享相同的角色词汇和记忆树，确保切换引擎时上下文不丢失。

**记忆管理（Memory）**

- 学习成果保存在 `.agents/memory/<role>/` 中
- 记忆预算限制：每个角色 < 25 KB
- 定期运行 `consolidate-memory` 脚本检查预算

**技能（Skills）**

技能定义在 `claude/skills/<name>/SKILL.md`，同时镜像到 `~/.codex/skills/`，使Codex和Claude都能使用。

## 核心工作流

### 1. Issue驱动开发

每个issue都通过以下流程完成：

```
issue创建 → 智能体分析 → 代码实现 → 自评（2轮） → verify.sh → keiko-issue-audit → PR创建 → CI检查 → 人工审查 → 合并
```

### 2. 史诗级任务（Epic）

Epic是包含多个子issue的大型任务：

```
epic创建 → 规划子issue → 创建epic分支 → 逐个处理子issue → 合并到epic分支 → epic审计 → epic PR → 合并到dev
```

### 3. 质量门禁（Quality Gates）

分层防护确保代码质量：

| 层级 | 工具 | 作用 |
|------|------|------|
| 1 | lint-staged | 提交前代码风格检查 |
| 2 | 2-pass self-critique | 智能体自评两轮 |
| 3 | verify.sh | 本地CI镜像 |
| 4 | keiko-issue-audit | 强制审计波 |
| 5 | completion judge | 完成度评判 |
| 6 | CI on protected dev | 受保护分支的CI检查 |

### 4. 审计机制

审计是强制性的质量检查点：

- **keiko-issue-audit <N>**：为issue #N生成SHA绑定的审计收据
- **audit-gate.sh**：阻止未审计的PR创建
- 审计证据写入PR描述，供审查者参考

## 安装与使用

### 安装

```bash
git clone git@github.com:Niko4417/Agent-Workflow-Setup.git
cd Agent-Workflow-Setup
./scripts/install.sh /path/to/Keiko
# 或: KEIKO_ROOT=/path/to/Keiko ./scripts/install.sh
```

安装器会创建符号链接：
- `/.codex`, `.claude`, `.agents` → 本仓库
- `/.mcp.json`, `AGENTS.md`, `CLAUDE.md` → 本仓库
- 项目技能镜像到 `~/.codex/skills/`
- 保留现有的 `.claude/settings.local.json`（机器特定配置）

### 快速开始

告诉协调器要处理什么：

```
Act as the orchestrator for Keiko and run epic #532.
Act as the orchestrator for Keiko and resolve issue #178.
```

### 常用命令

| 命令 | 功能 |
|------|------|
| `keiko-epic <N>` | 驱动多issue史诗：规划子任务、在epic分支上运行、交付绿色epic PR |
| `keiko-issue <N>` | 端到端处理单个issue到PR |
| `keiko-issue-audit <N>` | 强制审计波（也可按需运行） |
| `scripts/verify.sh` | 本地CI镜像，PR前运行 |
| `scripts/audit-gate.sh` | 审计检查，阻止未审计的PR |
| `scripts/keiko-watch` | 实时智能体活动监控 |
| `scripts/consolidate-memory` | 记忆预算检查 |

## 设计原则与权衡

### 为什么使用符号链接？

符号链接实现了**编辑即生效**的实时开发体验：

- 在本仓库编辑配置 → 立即在目标仓库生效
- 无需重新安装或复制文件
- 目标仓库保持git-clean

### 为什么坚持dev分支保护？

- **issue → epic分支**：可以自动合并（在CI通过后）
- **任何合并到dev**：必须有人工审查 + 绿色CI

这种设计平衡了自动化效率和代码安全。

### 为什么限制记忆大小？

- 每个角色 < 25 KB的记忆预算防止上下文膨胀
- 强制团队提炼和压缩学习成果
- 保持AI上下文的聚焦和相关性

### 为什么需要服务器端保护？

完整的安全保障需要仓库管理员在服务器端配置：

- 保护dev分支：要求PR、绿色CI检查、人工审查
- 审计生成的PR可见证据（检查或标签）
- 将其设为dev的必需状态检查

这是唯一不可绕过的形式，与分支保护位于同一位置。

## 协作与共享

仓库是自包含且路径无关的：

1. 协作者克隆本仓库
2. 在自己的Keiko检出上运行 `install.sh`
3. 机器特定配置保持本地和git-ignored

这种设计支持团队成员各自维护自己的工作流实例，同时共享核心配置。

## 技术栈

- **Shell** (61.8%)：安装脚本、工具链
- **Python** (38.2%)：智能体逻辑、审计工具

依赖：
- GitHub CLI (gh)
- 支持Codex和/或Claude Code的环境

## 适用场景

Agent Workflow Setup特别适合：

1. **团队AI协作**：标准化团队使用AI助手的方式
2. **大型代码库**：需要多智能体协调的复杂项目
3. **质量敏感**：代码质量要求高的生产环境
4. **审计需求**：需要完整开发和审计轨迹的合规场景
5. **实验性开发**：探索AI辅助开发最佳实践的研究项目

## 局限与注意事项

1. **需要仓库管理员权限**：完整功能需要目标仓库的分支保护配置
2. **学习曲线**：理解16个角色和完整工作流需要一定时间
3. ** overhead**：对于小型个人项目可能过于复杂
4. **Codex/Claude依赖**：需要订阅相应AI服务

## 总结

Agent Workflow Setup代表了一种系统化的AI辅助开发方法论。它不仅仅是工具集合，更是一套关于如何与AI协作的**契约和流程**。通过标准化角色、严格的质量门禁和清晰的审计机制，它在AI的创造力和软件工程的严谨性之间找到了平衡点。

对于希望规模化使用AI助手、同时保持代码质量和可追溯性的团队来说，这是一个值得深入研究的参考实现。