agent/.opencode/README.md

# OpenCode Agents 配置

本目录包含为 [OpenCode](https://opencode.ai) 配置的专业 AI 代理。

## 📁 目录结构

```
.opencode/
└── agents/
    ├── team.md           # 项目经理与团队协调者（主 Agent）
    ├── planning.md       # 技术架构与规划专家
    ├── frontend.md       # 前端架构与 UI/UX 专家
    ├── umi-pro.md        # UmiJS + ProComponents 专家
    ├── code-spec.md      # 代码规范与质量专家
    └── qa-tester.md      # 质量保证测试专家
```

## 🎯 主 Agent（Primary）

### Team Coordinator (`team`)

**角色**: 项目经理和团队协调者  
**模式**: Primary（主代理）  
**权限**: 完全访问  
**职责**:

- 理解和 clarify 用户需求
- 拆分任务为合理的子任务
- 协调所有子 Agent 按正确顺序工作
- 管理开发流程和进度
- 在关键检查点停止并征求用户意见
- **唯一有权开始和结束会话的 Agent**

**使用方式**: 这是默认的主 Agent，直接与用户对话，无需特殊调用。

---

## 🤖 子 Agent（Subagents）

所有子 Agent 只能被主 Agent (`team`) 调用，通过 `@agent-name` 方式。子 Agent 完成任务后必须将结果交回主 Agent，不能自行结束会话或调用其他 Agent。

### 1. Planning Agent (`@planning`)

**角色**: 技术架构师和规划专家  
**模式**: Subagent（子代理）  
**权限**: 只读（不可编辑代码）  
**用途**:

- 深度分析用户需求和代码库
- 生成详细的实施计划和技术方案
- API 契约驱动开发规划
- 技术选型建议

**调用方式**:

```
@planning 分析这个需求并给出详细的实施计划
```

---

### 2. Frontend Expert (`@frontend`)

**角色**: 前端架构师和 UI/UX 专家  
**模式**: Subagent（子代理）  
**权限**: 完全访问（可编辑代码）  
**用途**:

- 高端 UI/UX 实现
- Ant Design & ProComponents 开发
- Design Tokens 样式化
- 前端性能优化

**调用方式**:

```
@frontend 实现一个符合 Ant Design 规范的产品列表页面
```

---

### 3. Umi Pro Agent (`@umi-pro`)

**角色**: UmiJS 和 ProComponents 专家  
**模式**: Subagent（子代理）  
**权限**: 完全访问（可编辑代码）  
**用途**:

- 快速 ProComponents 实施
- UmiJS 框架约定和最佳实践
- Mock 数据和服务层开发
- 国际化实现

**调用方式**:

```
@umi-pro 创建一个包含搜索功能的商品管理表格
```

---

### 4. Code Spec Expert (`@code-spec`)

**角色**: 代码规范和质量专家  
**模式**: Subagent（子代理）  
**权限**: 完全访问（可编辑代码）  
**用途**:

- 执行 Ant Design 和 ProComponents 最佳实践
- 代码审查和重构
- 安全审计（XSS、认证、财务计算）
- 类型安全检查

**调用方式**:

```
@code-spec 审查这个组件是否符合 Ant Design 规范
```

---

### 5. QA Tester (`@qa-tester`)

**角色**: 质量保证和测试专家  
**模式**: Subagent（子代理）  
**权限**: 有限（仅 bash，不可编辑代码）  
**用途**:

- 功能测试和验证
- i18n 国际化检查
- UI/UX 质量审计
- 运行时错误检测

**调用方式**:

```
@qa-tester 测试产品列表页面的所有功能
```

---

## 🎯 核心设计理念

所有代理都遵循以下核心原则：

### 1. "Separated Card" 设计模式

- **< 4 个搜索字段**: 使用 `ProTable` 内置 `search`
- **>= 4 个搜索字段**: 使用独立 `QueryFilter` 组件

### 2. 强制样式 Tokens

```typescript
{
  background: token.colorBgContainer,    // 白色背景
  padding: token.paddingLG,              // 24px
  borderRadius: token.borderRadius,      // 6px
  marginBottom: token.marginLG,          // 24px
  // 无 boxShadow - 扁平化设计
}
```

### 3. 零 CSS 文件政策

所有样式必须通过 Ant Design Design Tokens 内联实现。

### 4. ProComponents 优先

- 列表 → `ProTable`
- 表单 → `ProForm` / `QueryFilter` / `ModalForm`
- 布局 → `ProLayout` / `PageContainer`

### 5. 严格 TypeScript

无 `any` 类型，所有接口定义在 `data.d.ts`。

### 6. 强制国际化

所有用户可见字符串必须使用 `intl.formatMessage` 并包含 `defaultMessage`。

---

## 📋 使用示例

### 典型开发流程

1. **规划阶段**:

   ```
   @planning 我需要创建一个文章管理系统，包含列表、编辑和删除功能
   ```

2. **实施阶段**:

   ```
   @umi-pro 根据计划实现服务层和 Mock 数据
   @frontend 实现文章列表页面的 UI
   ```

3. **审查阶段**:

   ```
   @code-spec 审查新创建的文章管理代码
   ```

4. **测试阶段**:
   ```
   @qa-tester 测试文章管理的所有功能并验证 i18n
   ```

---

## 🔧 配置说明

### Markdown 格式

每个代理使用 Markdown 文件定义，包含 YAML frontmatter：

```markdown
---
description: 代理描述
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
  write: true
  edit: true
  bash: true
---

# 代理提示内容

...
```

### JSON 格式

同时提供了 `opencode.json` 配置文件，可以在项目根目录使用。

---

## 📚 相关文档

- [OpenCode 官方文档](https://opencode.ai/docs/zh-cn/agents/)
- [Ant Design 官方文档](https://ant.design/)
- [ProComponents 官方文档](https://procomponents.ant.design/)
- [UmiJS 官方文档](https://umijs.org/)

---

## 🚀 版本信息

- **创建时间**: 2026-02-14
- **OpenCode 版本**: 最新
- **模型**: Claude Sonnet 4 (anthropic/claude-sonnet-4-20250514)

---

**维护者**: Antigravity Team