# agentTeams

**Repository Path**: strivingboy/agent-teams

## Basic Information

- **Project Name**: agentTeams
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent-Team — Claude Code / Codex / OpenCode SubAgent 团队模板

一套可复制到任意项目根目录直接使用的智能体团队配置，当前提供 Claude Code、Codex 与 OpenCode 三个平台版本。

## 核心理念

- **通用级别**：不假设技术栈，约定从目标项目真实代码动态提取
- **开箱即用**：复制即部署，首次运行自动生成项目地图
- **安全优先**：数据库 MCP 默认只读；Claude Code/Codex 使用 Hook，OpenCode 使用 fail-closed 执行前插件
- **最小文档模型**：两级项目记忆 + 按需单任务卡 + 必要证据 + 自动日志
- **标准流程可追溯**：稳定 Task ID 串联任务、产物、Finding、验收与 Agent/Skill/MCP 审计
- **契约防回归**：后端原接口路径、前端原页面入口默认保留，code-reviewer 将路径兼容作为硬质量门
- **清晰长期记忆**：`project-map.md` 只保存项目骨架和领域索引，领域 Agent 按需维护自己的稳定约定，标准流程的单次任务信息留在唯一任务卡
- **规范 Agent 交接**：所有 SubAgent 使用统一结构化 Envelope 返回状态、产物、验收、验证、记忆动作和剩余风险
- **需求确认门禁**：关键目标、范围、契约或验收存在歧义时先向用户确认，确认前只读分析且不得修改项目文件
- **小任务快速直做**：风险 0～2 的单模块小 Bug 由主对话读取必要约定、直接实现、分级 Review 和验证，不创建任务卡、不调用任何 SubAgent

## 当前版本：v1.3

### OpenCode 版

```bash
bash v1.3/.OpenCode/deploy.sh --target /path/to/target-project --dry-run
bash v1.3/.OpenCode/deploy.sh --target /path/to/target-project
```

```powershell
.\v1.3\.OpenCode\deploy.ps1 -Target "C:\path\to\target-project" -DryRun
.\v1.3\.OpenCode\deploy.ps1 -Target "C:\path\to\target-project"
```

OpenCode 版使用 OpenCode 原生项目级目录：`.opencode/agents/*.md` 提供七个叶子 Agent，`.opencode/commands/dev.md` 提供主 Agent `/dev` 命令，`.opencode/skills/` 与 `.opencode/spec/` 承载共享 Skill 和规范，根级 `opencode.json` 注册项目配置。模板继承当前模型配置，不硬编码 Provider/Model；不会覆盖 `AGENTS.md`，已有 `opencode.json` 时要求人工合并。

部署完成后，目标项目目录应类似：

```text
target-project/
├── .opencode/            # OpenCode 原生配置入口
│   ├── agents/           # 7 个 OpenCode 叶子 Agent 定义（*.md）
│   ├── commands/         # OpenCode 主 Agent /dev 命令
│   ├── skills/           # 15 个共享 Skill 工作流与规则
│   ├── spec/SPEC.md      # 参考文档规范
│   └── plugins/          # fail-closed 执行前安全插件
├── opencode.json         # OpenCode 项目级配置，不硬编码 Provider/Model
├── docs/                 # 运行后生成 docs/subagent-reference/
└── <你的项目代码>
```

注意：OpenCode 版是项目级配置，需要把 `.opencode/` 和 `opencode.json` 放到目标项目根目录，不是把整个 `v1.3/.OpenCode/` 目录作为子目录放进去。

#### OpenCode SubAgent 模型配置

模板默认不硬编码模型，所有 SubAgent 继承主 Agent 的模型。如需为不同 SubAgent 指定不同模型，打开 `.opencode/agents/<agent>.md`，取消注释并填写 `model` 字段：

```yaml
---
mode: subagent
model: codex/gpt-5.5               # provider_id/model_id
permission:
  ...
---
```

**如何找到 Provider ID 和 Model ID？**

1. 查看你的 `opencode.json`（全局：`~/.config/opencode/opencode.json`，项目级：项目根目录 `opencode.json`）
2. `provider` 块的**键名**即为 Provider ID（如 `codex`、`deepseek`、`minimax`）
3. 对应 `provider.<provider>.models` 块的**键名**即为 Model ID（如 `gpt-5.5`、`deepseek-v4-pro`）
4. 格式：`<provider_id>/<model_id>`

示例：假设 `opencode.json` 中有以下配置：

```json
{
  "provider": {
    "deepseek": {
      "models": {
        "deepseek-v4-flash": { ... },
        "deepseek-v4-pro": { ... }
      }
    }
  }
}
```

则 planner 使用快速模型：`model: deepseek/deepseek-v4-flash`，backend 使用强编码模型：`model: deepseek/deepseek-v4-pro`。

也可在命令行运行 `opencode models` 查看当前可用模型列表，或访问 [models.dev](https://models.dev) 查看内置 Provider 和 Model 名称。

### Codex 版（推荐给 Codex 使用）

```bash
cp -r v1.3/.Codex/.agents /path/to/target-project/
cp -r v1.3/.Codex/.codex /path/to/target-project/
```

或使用脚本：

```bash
./v1.3/.Codex/deploy.sh --target /path/to/target-project
```

Windows PowerShell：

```powershell
.\v1.3\.Codex\deploy.ps1 -Target "C:\path\to\target-project"
```

Codex 主对话模型由 `.codex/config.toml` 指定为 `gpt-5.5`；7 个原生 SubAgent 在各自 TOML 中明确使用 `gpt-5.4`。

复制或脚本部署完成后，目标项目目录应类似：

```text
target-project/
├── .agents/              # 共享能力目录，不是 Codex subAgent
│   ├── skills/           # 15 个共享 Skill 工作流与规则
│   ├── commands/         # /dev
│   └── spec/SPEC.md      # 参考文档规范
├── .codex/               # Codex 原生配置与 subAgent
│   ├── agents/           # 7 个 Codex subAgent 定义（*.toml）
│   ├── hooks/scripts/    # 8 个 Hook 脚本
│   ├── hooks.json        # Hook 注册
│   └── config.toml       # Codex 模型与运行配置
├── docs/                 # 运行后生成 docs/subagent-reference/
└── <你的项目代码>
```

注意：Codex 版需要把 `v1.3/.Codex/.agents` 和 `v1.3/.Codex/.codex` 都放到目标项目根目录，不是把整个 `v1.3/.Codex/` 目录作为子目录放进去。其中 `.agents/` 只承载 Skill、命令和规范，真正的 Codex subAgent 位于 `.codex/agents/`。

### Claude Code 版

```bash
cp -r v1.3/.claude/ /path/to/target-project/
# 目标项目 .gitignore 追加:
#   docs/subagent-reference/
```

然后在 Claude Code 中输入 `/dev <需求>` 即可。

复制完成后，目标项目目录应类似：

```text
target-project/
├── .claude/              # Claude Code 模板入口
│   ├── agents/           # 7 个 Agent
│   ├── skills/           # 21 个 Skill
│   ├── commands/         # /dev
│   ├── hooks/scripts/    # 8 个 Hook 脚本
│   ├── spec/SPEC.md      # 参考文档规范
│   └── settings.json     # Hook 注册与环境变量
├── docs/                 # 运行后生成 docs/subagent-reference/
└── <你的项目代码>
```

注意：Claude Code 版需要把 `v1.3/.claude/` 复制为目标项目根目录下的 `.claude/`。建议目标项目 `.gitignore` 忽略运行时产物 `docs/subagent-reference/`。

## 组成

### Agent（7 个，全叶子节点）

| Agent | 职责 |
|-------|------|
| planner | 风险评估、技术方案、任务拆解和验收标准 |
| backend | Spring Boot 后端开发 |
| frontend | Vue 3 前端开发 |
| database | 数据库审查与变更 |
| code-reviewer | 非 direct 运行时变更的唯一生产级质量门，负责完整影响面审查、结构化 Finding 与增量复查 |
| tester | 按验收标准执行验证并提供必要证据 |
| doc-syncer | 项目记忆更新、变更信号校验和任务卡只读检查 |

编排逻辑由 `skills/dev/SKILL.md` 负责，`/dev` 加载后主对话即 Orchestrator。满足 direct 准入条件的小任务不会启动 SubAgent；标准流程中 `agent-nesting-guard` 会硬阻断子 Agent 内再次调度 Agent 和同类 Agent 重复派发。

### Skill（15 个）

| 领域 | Skill |
|------|-------|
| 编排 | dev（含质量门闭环） |
| 需求与流程 | prd-analysis, task-breakdown |
| 后端 | springboot-patterns |
| 前端 | vue-patterns |
| 数据库 | sql-review（含 DDL 迁移安全性审查）, mysql-index-strategy |
| 质量 | code-quality, coding-standards |
| 测试 | test-coverage |
| 项目管理 | project-map, context-compression, progress-tracker |
| 浏览器自动化 | chrome-cdp-bridge |
| 文档可视化 | md-to-visual-html |

### Hook

Claude Code 版与 Codex 版均包含 8 个 hook 脚本：agent-logger、agent-nesting-guard、branch-guard、env-guard、mcp-sql-guard、post-edit-lint、skill-candidate-detector、health-check。Claude Code 版通过 `.claude/settings.json` 注册；Codex 版通过 `.codex/hooks.json` 注册，脚本路径为 `.codex/hooks/scripts/`。

### 安全机制

数据库 MCP 默认只允许 SELECT/SHOW/DESCRIBE/EXPLAIN。Claude Code 版与 Codex 版均由 `mcp-sql-guard.js` 硬拦截非只读 SQL；未获用户明确授权时只能输出脚本与风险说明。

### 质量门闭环

风险 0～2 且满足 direct 准入条件时：主对话读取相关 `project-map.md` 切片、已存在领域记忆或等价源码约定 → 直接实现 → 检查完整 diff → 按风险执行粗略/针对性 Review → 执行针对性验证 → 返回结果，全程不创建任务卡或调用 SubAgent。

其他运行时变更继续执行：主对话或开发 Agent 产出 → code-reviewer 生产级质量门 → 定向修复 → 增量复查 → 按风险调用 tester。审查至少覆盖功能回归、契约兼容、安全隐私、数据事务、并发幂等、可靠性、性能容量、可运维性、发布回滚和验证证据。

数据库、安全、接口/路由兼容、跨模块、公共组件、共享配置、依赖、部署、并发冲突或无法可靠验证时禁止使用 direct，必须升级标准流程。

生产就绪判定要求所有适用维度均已核查、必需 AC 有真实证据、发布顺序与回滚方案可执行，并且没有未关闭 blocker/major。安全、数据、迁移、回滚或关键路径缺少必要证据时，质量门必须失败或保持 unknown。

### 目录结构

```
v1.3/
├── AGENTS.md              # Codex 版部署说明
├── CLAUDE.md              # 模板架构说明
├── UPGRADE.md             # 升级说明
├── .Codex/                # Codex 可独立部署包
│   ├── .agents/
│   │   ├── skills/        # 21 个共享 Skill
│   │   ├── commands/      # /dev
│   │   └── spec/SPEC.md   # 参考文档规范
│   ├── .codex/
│   │   ├── agents/        # 7 个 Codex 原生 subagent（*.toml）
│   │   ├── hooks/scripts/ # 8 个 Codex Hook 脚本
│   │   ├── hooks.json     # Codex hook 注册
│   │   └── config.toml    # Codex 主对话配置，model = "gpt-5.5"
│   ├── deploy.ps1
│   └── deploy.sh
├── .OpenCode/             # OpenCode 可独立部署包
│   ├── .opencode/
│   │   ├── agents/        # 7 个 OpenCode 叶子 Agent（*.md）
│   │   ├── commands/      # 主 Agent /dev
│   │   ├── skills/        # 21 个共享 Skill
│   │   ├── spec/SPEC.md   # 参考文档规范
│   │   └── plugins/       # fail-closed 执行前安全插件
│   ├── opencode.json      # 不硬编码 Provider/Model
│   ├── deploy.ps1
│   └── deploy.sh
├── .claude/               # Claude Code 可独立部署包
│   ├── agents/            # 7 个 Agent
│   ├── skills/            # 21 个 Skill
│   ├── commands/          # /dev
│   ├── hooks/scripts/     # 8 个 Node.js Hook 脚本
│   ├── spec/SPEC.md       # 参考文档规范
│   └── settings.json      # Hook 注册 + 环境变量
└── docs/                  # 空占位（运行时产物在目标项目生成）
```

### 运行时产物（目标项目 `docs/subagent-reference/` 下）

| 路径 | 用途 |
|------|------|
| `project-map.md` | 跨任务项目记忆、关键入口与变更信号 |
| `领域记忆/后端约定.md` | backend 首次需要时生成并独占维护的后端稳定约定 |
| `领域记忆/前端约定.md` | frontend 首次需要时生成并独占维护的前端稳定约定 |
| `领域记忆/数据库约定.md` | database 首次需要时生成并独占维护的数据库稳定约定 |
| `领域记忆/测试约定.md` | tester 首次需要时生成并独占维护的测试稳定约定 |
| `任务/TASK-{日期}-{短码}-{中文短名}.md` | 单任务唯一人工对齐入口，内嵌状态、AC、产物和 Finding |
| `证据/` | 仅保存必须独立执行或证明的 SQL、测试报告、请求样例等 |
| `log/agent-calls.jsonl` | Agent 与 Skill 调用审计 |
| `log/mcp-calls.jsonl` | MCP 安全审计 |
| `log/lint-issues.jsonl` | 编辑后质量检查日志 |

标准流程默认只维护一张任务卡；direct 的任务对齐和交付记录只保留在当前主对话最终回复中。四份领域记忆不会在初始化时一次性创建，而是在对应 Agent 首次参与时按需生成；direct 遇到已有领域记忆时必须读取，缺失时只从相关源码、配置或邻近实现提取最小约定，不为空建记忆文件。增量上下文包由主对话从任务卡和相关领域记忆动态提取，只传递当前 SubAgent 必需的信息，不默认生成独立文档。

SubAgent 返回统一包含 `task_id`、`subtask_id`、`agent`、`status`、`summary`、`artifacts`、`validation`、`acceptance_updates`、`memory_updates`、`findings`、`risks` 和 `next_actions`；各角色只在公共 Envelope 后追加自己的结构化扩展字段，不能修改公共字段的结构或枚举。