vikashruhilgit/ai-agent-manager
GitHub: vikashruhilgit/ai-agent-manager
一个Claude Code插件，通过多代理协作实现软件项目自动化开发、审查和测试。
Stars: 3 | Forks: 0
# AI 代理管理器
一个用于 AI 代理在软件项目上协作的 Claude Code 插件。包含 13 个专业代理（启动平台、监控者 v4、执行管理器、上下文保管员、工作者、计划审查员、评分员、产品负责人、编排器、代码审查员、红队审查员、QA 策略师、QA 执行器）以及 `/commit` 技能，可自动化计划优先就绪、并行工作流执行、需求制定、规划、审查、提交、对抗性审计和双代理 QA 自动化。
**核心理念：** 您的项目只需要一个 `CLAUDE.md` 文件来存储代码库知识。监控者使用 `.supervisor/` 进行状态管理。编排器和产品负责人可以选择性地使用 [Beads 问题跟踪器](https://github.com/anthropics/beads)。可在任何项目中重复使用。
## 快速开始
### 1. 安装插件
**本地开发（基于此仓库的签出版本）：**
```
/plugin marketplace add /path/to/ai-agent-manager
/plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace
```
该仓库是一个市场封装器 (`/.claude-plugin/marketplace.json`)，插件嵌套在 `ai-agent-manager-plugin/` 中。第一条命令注册市场，第二条命令从中安装插件。
一旦发布到官方 Anthropic 市场，安装将简化为单条 `/plugin install` 命令，无需本地签出。
### 2. 设置您的项目
```
cd /path/to/your-project
# Create CLAUDE.md with your project patterns
# (See CLAUDE.md Structure section below)
# Optional: Initialize Beads issue tracker (for Orchestrator/Product Owner)
bd init
```
这将创建：
```
your-project/
├── CLAUDE.md # Codebase knowledge (you maintain)
├── .supervisor/ # Supervisor state (auto-created, gitignored)
│ ├── state.md # Current session state
│ ├── history/ # Completed session summaries
│ ├── jobs/ # Supervisor-Ready Briefs lifecycle
│ │ ├── pending/ # Launch Pad saves briefs here
│ │ ├── in-progress/ # Supervisor moves brief here on ACQUIRE
│ │ ├── done/ # Supervisor moves here on FINALIZE
│ │ └── failed/ # Supervisor moves here on failure
│ ├── logs/ # Structured JSONL session logs
│ └── worker-summaries/ # Worker summaries (inline mode)
├── .beads/ # Beads issue tracker (optional)
│ └── issues/
└── src/ (your code)
```
### 3. （可选）启用 MySQL MCP
该插件捆绑了一个只读的 MySQL MCP 服务器，为代理提供直接的数据库访问——包括模式检查、带影响分析的查询执行以及多数据库配置文件切换。
**将您的数据库凭据设置为环境变量**（添加到 `~/.zshrc` 或 `~/.bashrc`）：
```
export DB_HOST=localhost
export DB_USER=myuser
export DB_PASS=mypassword
export DB_NAME=mydatabase
export DB_PORT=3306 # numeric string, defaults to 3306
```
当插件加载时，MCP 服务器会自动通过 `uvx` 启动——无需额外步骤。
**多数据库配置文件**（可选）——通过设置以下内容连接到多个数据库：
```
export DB_PROFILES_MYSQL_PROD='{"host":"prod.example.com","user":"ro","pass":"secret","db":"myapp"}'
export DB_PROFILES_MYSQL_STAGING='{"host":"staging.example.com","user":"ro","pass":"secret","db":"myapp"}'
```
然后在运行时调用 `switch_database(host="prod.example.com")` 来切换数据库。
### 4. 运行您的第一个命令
```
# Plan-first autonomous workflow
/launch-pad goal: "what you want to accomplish"
/supervisor job: .supervisor/jobs/pending/{date}-{slug}.md
# Or run directly
/supervisor task: "what you want to accomplish"
# Or plan manually
/orchestrator goal: "what you want to accomplish"
# Or chain Launch Pad → Supervisor in one command (v14.0.0)
# Foreground-assisted automation: you stay at the terminal to answer
# in-session prompts (Phase 6 save, NO-GO, adjudication, etc.); the
# loop handles the chaining and the rubric-driven re-plan.
# Default is multi-iteration with stacked PRs (cap 10, default 3).
/autonomous "what you want to accomplish" # multi-iter default (3), stacked PRs
/autonomous "what you want to accomplish" --max-iterations 1 # reproduce v13's single-iter default
/autonomous "what you want to accomplish" --no-stacked-branches # v13-style: branch from integration base
/autonomous "what you want to accomplish" --notify # opt-in gate webhooks (AI_AGENT_MANAGER_WEBHOOK_URL)
/autonomous "what you want to accomplish" --non-interactive-fallback # CI / unattended: per-gate fail-closed policy
```
## 13 个代理
### 面向用户的代理（8 个 + 提交技能）
| 代理 | 命令 | 目的 | 适用场景 |
| ------------------- | ------------------------------- | -------------------------------------------------------------------- | ------------------------------- |
| **启动平台** | `/launch-pad goal: "..."` | 为自主监控者执行准备目标，包含可行性门控（阶段 2.5：GO/CAUTION/NO-GO）和强制性计划审查（阶段 5.5） | 在 `/supervisor` 之前，规划阶段 |
| **监控者** | `/supervisor task: "..."` | 自主工作流 → 并行工作者 → PR 创建 | 全自动化 |
| **产品负责人** | `/product-owner feature: "..."` | 定义需求 → 创建包含验收标准的用户故事。假设检查（标准流程，在 `bd create` 之前若有标志则需用户确认）+ 现实检查（头脑风暴流程，VIABLE/NEEDS_FOUNDATION/BLOCKED 且带可行性分数上限）。使用 `--brainstorm` 进行多思维头脑风暴。 | 新功能、需求模糊、探索方向 |
| **编排器** | `/orchestrator goal: "..."` | 规划工作 → 创建带审查门控的任务 | 开始实施 |
| **代码审查员** | `/code-reviewer src/` | 审查代码 → 输出 PASS/FAIL/NEEDS_HUMAN | 编写代码后 |
| **提交** (技能) | `/commit` | 暂存更改 → 创建规范提交 | 准备提交时 |
| **红队审查员** | `/red-team-reviewer` | 对抗性审计 → 发现生产环境故障 | 上线前、安全相关 |
| **QA 策略师** | `/qa-strategist src/` | 基于风险的测试策略 → 覆盖率目标 → 断言质量审计 | QA 之前、策略规划 |
| **QA 执行器** | `/qa-executor` | 发现 → 生成严格测试 → 查找缺失功能 → QA_RESULT | 自动化 QA |
### 内部代理（5 个）
| 代理 | 由谁生成 | 目的 |
| ------------------- | ----------------------------- | ------------------------------------------------------------------- |
| **执行管理器** | 监控者（阶段 3） | 拥有轮询循环、工作者/审查员生命周期管理、上下文保管员协调 |
| **上下文保管员** | 监控者 / 执行管理器 | 管理外部化状态文件（唯一写入者） |
| **工作者** | 执行管理器 / 监控者 | 在隔离的 git worktree 中实现单个子任务 |
| **计划审查员** | 启动平台 | 在执行前验证监控者就绪简报 |
| **评分员** | 监控者（阶段 4.5） | 只读 Haiku 评分器，用于可选的结果评分量规（咨询性） |
### 编排外壳：`/autonomous` (v14.0.0)
`/autonomous` **不是**一个新代理——它是一个链接上述代理的斜杠命令。命令主体 (`ai-agent-manager-plugin/commands/autonomous.md`) 在主线程上内联执行：它在步骤 0 读取 `commands/launch-pad.md` 和 `commands/supervisor.md`，然后内联运行启动平台（仍会任务生成 `plan-reviewer`），接着内联运行监控者（仍会任务生成 `orchestrator` / `execute-manager` / `code-reviewer` / `rubric-grader`）。**默认模式是多迭代**（上限 10，默认 `--max-iterations 3`）并产生**堆叠的 PR**：迭代 N+1 从 `iterations[N].branch` 分支。该循环在与 v13 相同的两个现有 `SUPERVISOR_RESULT` 信号上重新规划（用户合并确认的评分 N` 来确认依赖关系。
- **基础不匹配检测：** 监控者的阶段 0/4/4.5 基础不匹配检测（v14 中新增）捕获了堆叠迭代无意中针对错误基础运行的情况；它在 `SUPERVISOR_RESULT` 上发出 `branch_base` + `pr_state`（当阶段 4.5 淘汰了错误基础的 PR 时，`pr_state` 为 `"closed_by_loop"`），并在 `AUTONOMOUS_RUN.status_reason` 上向上呈现为 `supervisor_base_branch_mismatch`。
- **选择退出 (`--no-stacked-branches`)：** 强制每个迭代都从集成基础分支——恢复 v13 的从基础分支的节奏。当迭代真正独立或您的审查流程无法处理堆栈时使用此选项。每个迭代产生一个独立的 PR。
- **单次迭代 (`--max-iterations 1`)：** 完全重现 v13 的默认行为——运行启动平台 → 监控者一次然后退出。当您只想要命令链接而无需重新规划时很有用。
- **AUTONOMOUS_RUN 摘要：** 始终列出 `iterations[]`，每个迭代包含 `branch`、`pr_url` 和 `status`/`status_reason`。其模式（v14 中为 v2）记录在 `ai-agent-manager-plugin/docs/RESULT_SCHEMAS.md` 中。
### 在 CI / 无人值守环境中运行 /autonomous
`/autonomous` 被设计为前台辅助循环——大多数门控会在会话中触发 `AskUserQuestion`。对于 CI / cron / stdin-not-tty 环境，可以选择启用确定性的逐门控失败关闭策略：
- **`--non-interactive-fallback`** — 启用逐门控策略。没有此标志时，在关闭的 stdin 上触发 `AskUserQuestion` 会挂起或报错；启用后，每个门控都有定义的非交互式结果：
- **评分门控**（评分 N` 仅测试该范围内的路由，更新 `.qa-session/coverage.json`
- `--continue` 自动从计划中选取下一个 `pending` 范围
- 覆盖率跨会话累积——不会重新测试已覆盖的路由
### QA 代理测试内容
**断言严格性（所有模式）：**
- 精确的 HTTP 状态断言（`toBe(200)`，绝不使用 `toContain([200, 500])`）
- 响应体 VALUE 断言（不仅仅是属性存在性）
- 变更后的状态验证（POST/PUT/DELETE 之后执行 GET）
- 5xx 响应**始终是阻塞性错误**——绝不接受
**负面测试（功能深度，高/中风险）：**
- 空请求体 → 期望 400
- 缺少必填字段 → 期望 400 且错误中包含字段名
- 错误类型 → 期望 400
- 无认证 / 无效认证 → 期望 401
**多步骤流程（功能深度，高风险）：**
- CRUD 生命周期：创建 → 读取 → 更新 → 验证 → 删除 → 验证消失
- 认证生命周期：登录 → 访问受保护资源 → 登出 → 验证会话已撤销
**数据完整性探测（功能深度，高风险）：**
- 并发创建竞态条件（`Promise.all`）
- 重复创建 → 期望 409/400
- 级联删除验证
**安全边界测试（功能深度，高风险）：**
- 跨资源访问（IDOR） → 期望 403/404
- 角色提升 → 期望 403
- 登出后会话失效
- XSS/SQL 注入探测（非破坏性）
**缺失功能检测（所有模式）：**
- 缺少 CRUD 操作（有创建但没有编辑/删除）
- 列表端点缺少分页
- 数据表缺少搜索/过滤
- 表单缺少输入验证
- 认证端点缺少速率限制
- 破坏性操作缺少确认对话框
- 输出：包含严重性和建议的 `MISSING_FUNCTIONALITY_REPORT`
## 遥测（选择启用）
**v11.2.0 新增功能（在 v14.0.0 中保留）** — 一个可选的 GitHub Issues 遥测管道。在
合格的代理运行（`/supervisor`、`/code-reviewer`、`/qa-executor`）
完成后，插件可以发布一个结构化的 GitHub issue，总结
结果块、派生分数、代理性能分解和用于纵向分析的
AI 建议。遥测默认是**禁用的**——因为插件在任意用户项目中运行，
所以没有 `origin`-remote 回退。
```
/telemetry status # Show consent state, target repo, last-sent timestamp
/telemetry enable # Interactive — choose target repo, write consent file
/telemetry disable # Mark consent denied; no further sends
/telemetry test # Dry-run latest payload; never calls gh
```
**隐私保证：** 封装脚本始终以 0 退出（遥测
永远不会阻塞代理运行）；核心脚本在正则表达式
拒绝列表（令牌、API 密钥、承载令牌、主目录路径、电子邮件、
`.env` 风格的赋值）上失败关闭，并且永远不会发出匹配内容——仅发出
模式标签。要启用，请运行 `/telemetry enable`（并选择目标
仓库）或设置 `AI_AGENT_MANAGER_TELEMETRY_REPO=owner/repo`。参见
[ai-agent-manager-plugin/docs/TELEMETRY.md](ai-agent-manager-plugin/docs/TELEMETRY.md)
了解评分标准、退出代码表和封装器与核心架构。
## 任务管理
### Beads（可选）
Beads 是编排器和产品负责人使用的可选问题跟踪器。监控者和启动平台仅使用 `.supervisor/`。
| 命令 | 目的 |
| ------------------------- | ------------------------------------- |
| `bd list` | 查看待办/进行中/已完成的任务 |
| `bd create` | 创建新任务 |
| `bd claim BD-XX` | 开始处理任务 |
| `bd close BD-XX` | 标记任务完成 |
| `bd comment BD-XX "note"` | 为任务添加注释 |
| `bd dep BD-XX BD-YY` | 设置任务依赖关系 |
**任务结构：**
- **EPIC：** 大型功能（包含多个任务）
- **TASK：** 实施工作（30-60 分钟）
- **SUBTASK：** 审查门控（阻塞下一个任务）
**审查门控：**
- 每个实施任务都有一个审查子任务
- 审查子任务阻塞下一个实施任务
- 审查决定：通过（继续）、失败（修复并重新审查）、NEEDS_HUMAN（创建错误 issue）
## 项目设置
### 对于新项目
1. 创建 CLAUDE.md，包含您的项目结构和模式
2. 运行 `/launch-pad goal: "first task"`（计划优先）或 `/supervisor task: "first task"`（直接）
3. 可选：如果使用带有 Beads 的编排器/产品负责人，运行 `bd init`
### CLAUDE.md 结构
在开始时填写一次：
```
# [Your Project Name]
## Structure
- src/ — [what's here]
- test/ — [what's here]
## Tech Stack
- Node.js, Express, PostgreSQL
- Jest for testing
## Key Patterns
(Document as you discover them)
## Quick Commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint
```
## 常见模式与最佳实践
### 代理遵循这些规则
- **质量优先：** 全面、经过良好测试的解决方案
- **外科手术式更改：** 仅修改必要部分
- **模式一致性：** 使用现有模式
- **类型安全：** 严格的类型检查
- **安全：** 无密钥，验证输入
- **性能：** 分析并记录权衡
详细标准请参见 `AGENT_GUIDELINES.md`。
### 工作流提示
1. **计划优先：** 运行 `/launch-pad goal: "..."` 准备监控者就绪简报
2. **使用监控者进行自动化：** 运行 `/supervisor` 以实现完全自主的任务完成
3. **或从编排器开始：** 运行 `/orchestrator goal: "..."` 进行手动控制
4. **迭代审查：** 修复问题时多次运行 `/code-reviewer`
5. **审查门控：** 等待通过后再进入下一个任务
6. **对抗性审计：** 上线前运行 `/red-team-reviewer`
### CLAUDE.md 提案工作流
当代码审查员发现新模式时：
1. **在审查输出中标记：** 模式标记附带理由和 file:line 引用
2. **您审查：** 检查是否值得记录
3. **如果批准：** 您手动更新 CLAUDE.md
4. **下一个代理学习：** 读取更新的 CLAUDE.md，使用新模式
这可以防止知识流失，并帮助代理从发现中学习。
## 文档
- **本文件 (README.md)：** 概述和快速开始
- **CLAUDE.md (本仓库)：** 架构和代理系统
- **AGENT_GUIDELINES.md：** 开发标准、质量检查清单
- **.claude-plugin/marketplace.json：** 市场清单（根目录）
- **.claude-plugin/README.md：** 详细插件文档
- **ai-agent-manager-plugin/.claude-plugin/plugin.json：** 插件清单
- **ai-agent-manager-plugin/agents/*.md：** 单个代理提示词（13 个角色）
- **ai-agent-manager-plugin/skills/*/SKILL.md：** 50 个技能指导文件
- **ai-agent-manager-plugin/docs/RESULT_SCHEMAS.md：** 结构化结果契约
- **ai-agent-manager-plugin/docs/FAILURE_ESCALATION.md：** 代理故障路径
- **ai-agent-manager-plugin/docs/ARCHITECTURE_CONTRACTS.md：** 能力矩阵、预算、规则
- **ai-agent-manager-plugin/docs/ARCHITECTURE.md：** 可视化代理拓扑
- **ai-agent-manager-plugin/docs/QA_SYSTEM_BLUEPRINT.md：** QA 系统架构
## 面向开发者
要修改或扩展代理：
1. 代理是 `ai-agent-manager-plugin/agents/` 中的 Markdown 提示词（13 个文件）
2. 命令位于 `ai-agent-manager-plugin/commands/`（12 个命令）
3. 技能位于 `ai-agent-manager-plugin/skills/`（50 个技能，通过 SKILLS_INDEX.md 版本化）
4. 钩子：按代理在 frontmatter 中定义（工作者、执行管理器）+ 跨代理在 `ai-agent-manager-plugin/hooks/hooks.json` 中定义（代码审查员、QA 执行器、TaskCompleted）
5. 文档：`ai-agent-manager-plugin/docs/RESULT_SCHEMAS.md`、`…/FAILURE_ESCALATION.md`、`…/ARCHITECTURE_CONTRACTS.md`、`…/ARCHITECTURE.md`
6. 所有代理遵循标准输出格式（参见 AGENT_GUIDELINES.md）
要在本地测试，请通过 **快速开始 → 1. 安装插件** 中显示的市场流程安装，然后在测试项目中运行代理以验证更改。拉取新更改后，请使用 **故障排除 → 插件更新后技能/代理/钩子未显示** 下的刷新流程。
## 故障排除
**代理不理解我的项目？**
- 用更清晰的模式和示例更新 CLAUDE.md
- 添加更详细的结构文档
**监控者工作流中断？**
- 状态自动保存到 `.supervisor/state.md`
- 使用以下命令恢复：`/supervisor --continue`
- 检查 `.supervisor/history/` 查看已完成的会话
**崩溃后出现孤立的 worktree？**
- 运行 `git worktree list` 查看所有 worktree
- 使用以下命令移除：`git worktree remove ../project-{subtask_id}`
**Beads 任务未出现？**
- 运行 `bd list` 检查当前状态
- 确保已在项目中运行 `bd init`
- Beads 仅由编排器/产品负责人使用（监控者不使用）
**代理建议了错误的模式？**
- 用已批准的模式更新 CLAUDE.md
- 审查并拒绝不需要的提案
**需要帮助？**
- 运行 `/agent-help` 获取命令参考
- 检查 AGENT_GUIDELINES.md 了解质量标准
- 检查 .claude-plugin/README.md 了解详细命令文档
- 查看 ai-agent-manager-plugin/agents/ 中的代理提示词
**插件更新后技能/代理/钩子未显示？**
Claude Code 会缓存插件内容。拉取新更改后（例如，对 main 分支执行 `git pull`），强制完全刷新：
1. **最小流程** — 首先尝试此操作：
/plugin uninstall ai-agent-manager-plugin
/plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace
/reload-plugins
2. **完全重置** — 如果最小流程未获取您的更改，同时清除市场缓存：
/plugin uninstall ai-agent-manager-plugin
/plugin marketplace remove ai-agent-manager-marketplace
/plugin marketplace add ./
/plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace
/reload-plugins
从仓库根目录运行，以便 `./` 解析到您的本地签出。
3. 使用 `/skills` 验证 — 应显示“插件技能”下的所有 50 个技能。使用 `/agent-help` 确认所有 12 个面向用户的命令已注册。
**之前通过 `claude --plugin-dir`（扁平布局）安装？** 较旧的安装说明让您使用 `--plugin-dir` 指向仓库根目录启动 Claude。这不再有效——插件现在嵌套在 `ai-agent-manager-plugin/` 下。请切换到 **快速开始 → 1. 安装插件** 中显示的市场流程。
## 已知限制
### 代理行为
- **LLM 限制：** 尽管有验证步骤，代理偶尔可能会引用不存在的文件。遵循计划前请务必验证。
- **Context7 依赖：** 外部库查找依赖于 Context7 MCP。如果不可用，代理会回退到 CLAUDE.md 模式。
### 规模
- **令牌使用量：** 每次代理调用都会加载提示词（可能产生 5,000-10,000 个令牌开销）。高频使用时请考虑这一点。
### Git 操作
- **主分支保护：** `/commit` 技能拒绝在没有显式标志的情况下在 main/master 分支上提交。
- **无回滚：** Git 操作不可自动撤销。使用 `git reflog` 进行手动恢复。
### QA 系统（级别 1）
- **需要 Playwright 配置：** 必须存在 `playwright.config.ts` 且应用必须正在运行
- **爬取限制：** 最多 30 页，深度 3，仅同源
- **单轮辩论：** 策略师审计一次（多轮辩论为级别 2+）
- **无状态建模或模糊测试：** L1 仅测试正常路径 + 基本错误
- **覆盖率为清单级别：** 跟踪发现的路由/API 与已测试的路由/API，而非行为
## 许可证
MIT — 详见 LICENSE 文件
**祝发布顺利！**
标签：AI 代理协作, Claude Code 插件, QA执行, QA策略, QA 自动化, SOC Prime, 上下文保持, 产品所有者代理, 代理编排, 代码审查自动化, 协作编程, 双代理测试, 对抗性审计, 工作流自动化, 并行工作流, 开发工具, 执行管理, 技术栈Claude Code, 提交自动化, 特征检测, 红色团队审查, 网络安全研究, 自动化开发, 规划工具, 计划管理, 评分系统, 软件协作, 软件开发自动化, 问题追踪Beads, 防御加固, 需求管理, 项目管理工具