docs(v0.5): 添加 Gitea 协作流程设计
- 添加 Issue 结构（工作清单模式） - 添加 6 步工作流程 - 添加 Comment 标记约定 - 添加流程图 - 添加偏差处理机制 - 简化感知机制：Sub 完成标记 → Main 主动读取 Gitea
This commit is contained in:
@@ -514,9 +514,279 @@ export default async function (task) {
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 配置 Gitea 协作
|
||||
### 5.3 Gitea 协作流程
|
||||
|
||||
见 `docs/gitea-collaboration-guide.md`
|
||||
系统使用 Gitea Issue 作为协作中心，Main Agent 和 Sub Agents 在同一个 Issue 中协作。
|
||||
|
||||
#### 5.3.1 Issue 结构
|
||||
|
||||
**Issue 标题格式**：
|
||||
```
|
||||
[sanguo_moziplus_v3] 功能描述
|
||||
```
|
||||
|
||||
**Issue 正文结构**：
|
||||
```markdown
|
||||
## 项目信息
|
||||
- 项目: sanguo_moziplus_v3
|
||||
- 需求编号: D-N
|
||||
- 复杂度: 简单/中等/复杂
|
||||
|
||||
## 需求描述
|
||||
<!-- 用户需求概述 -->
|
||||
|
||||
## 执行清单
|
||||
|
||||
### 📋 Execute Sub Agent
|
||||
> **负责**: Execute Sub Agent
|
||||
> **状态**: 🔄 进行中
|
||||
|
||||
- [ ] 任务1...
|
||||
- [ ] 任务2...
|
||||
|
||||
**完成时标记**: `@main-agent ✅ EXECUTE_DONE`
|
||||
|
||||
### 📋 Review Sub Agent
|
||||
> **负责**: Review Sub Agent
|
||||
> **状态**: ⏳ 等待中
|
||||
|
||||
- [ ] 检查项1...
|
||||
- [ ] 检查项2...
|
||||
|
||||
**完成时标记**: `@main-agent ✅ REVIEW_DONE verdict=approved/rejected`
|
||||
|
||||
### 📋 Test Sub Agent
|
||||
> **负责**: Test Sub Agent
|
||||
> **状态**: ⏳ 等待中
|
||||
|
||||
- [ ] 测试项1...
|
||||
- [ ] 测试项2...
|
||||
|
||||
**完成时标记**: `@main-agent ✅ TEST_DONE result=passed/failed`
|
||||
|
||||
### 📋 Main Agent 验收
|
||||
> **负责**: Main Agent
|
||||
> **状态**: ⏳ 等待中
|
||||
|
||||
- [ ] 需求 → 设计 一致性
|
||||
- [ ] 设计 → 编码 一致性
|
||||
- [ ] 需求 → 编码 一致性
|
||||
|
||||
**完成时标记**: `@main-agent ✅ VERIFICATION_PASSED`
|
||||
|
||||
## 执行状态
|
||||
| 阶段 | 负责者 | 状态 | 更新时间 |
|
||||
|------|-------|------|---------|
|
||||
| Execute | Execute Sub Agent | 🔄 进行中 | - |
|
||||
| Review | Review Sub Agent | ⏳ 等待 | - |
|
||||
| Test | Test Sub Agent | ⏳ 等待 | - |
|
||||
| 验收 | Main Agent | ⏳ 等待 | - |
|
||||
```
|
||||
|
||||
#### 5.3.2 工作流程
|
||||
|
||||
**Step 1: Main Agent 创建 Issue**
|
||||
|
||||
Main Agent 接收需求后，创建 Issue 并制定工作清单。
|
||||
|
||||
**Step 2: Sub Agents 工作并更新**
|
||||
|
||||
Sub Agents 在工作过程中通过 Issue Comments 更新进度：
|
||||
|
||||
```markdown
|
||||
@main-agent 📝 **进度更新: Execute 阶段**
|
||||
|
||||
## 已完成
|
||||
- ✅ 1.1 数据库迁移
|
||||
- ✅ 1.2 核心逻辑实现
|
||||
|
||||
## 进行中
|
||||
- 🔄 1.3 API 接口实现
|
||||
|
||||
---
|
||||
**进度**: 66% (2/3 完成)
|
||||
```
|
||||
|
||||
**Step 3: Sub Agent 完成后发布标记**
|
||||
|
||||
Sub Agent 完成工作后，发布标准格式的完成标记：
|
||||
|
||||
```markdown
|
||||
@main-agent ✅ **EXECUTE_DONE**
|
||||
|
||||
## 完成总结
|
||||
|
||||
### 交付物
|
||||
1. `db/migrations/001_login_attempts.sql` - 数据库迁移
|
||||
2. `src/auth/login_checker.py` - 核心逻辑
|
||||
3. `src/api/routes/auth.py` - API 集成
|
||||
|
||||
### 测试状态
|
||||
- 本地运行: ✅ PASS
|
||||
- 覆盖率: 85%
|
||||
|
||||
---
|
||||
**执行者**: Execute Sub Agent
|
||||
**完成时间**: 2026-07-01 12:00
|
||||
```
|
||||
|
||||
**Step 4: Main Agent 读取 Gitea 并编排下一阶段**
|
||||
|
||||
Sub Agent 完成后，Main Agent 主动读取 Gitea 状态：
|
||||
|
||||
```javascript
|
||||
// Main Agent 感知 Sub Agent 完成并编排
|
||||
async function checkAndOrchestrate(issueNumber) {
|
||||
// 1. 读取 Issue Comments
|
||||
const comments = await gitea.getIssueComments(issueNumber)
|
||||
|
||||
// 2. 解析完成标记
|
||||
const executeDone = comments.some(c => c.body.includes('✅ EXECUTE_DONE'))
|
||||
const reviewDone = comments.some(c => c.body.includes('✅ REVIEW_DONE'))
|
||||
const testDone = comments.some(c => c.body.includes('✅ TEST_DONE'))
|
||||
|
||||
// 3. 根据状态编排下一阶段
|
||||
if (executeDone && !reviewDone) {
|
||||
// Execute 完成 → 启动 Review + Test 并行
|
||||
await notifyAgents(issueNumber, 'Review 和 Test 可以开始了')
|
||||
}
|
||||
|
||||
if (reviewDone && testDone) {
|
||||
// Review + Test 完成 → 启动验收
|
||||
await startVerification(issueNumber)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5: Main Agent 执行三向一致性检查**
|
||||
|
||||
Main Agent 在验收时执行一致性检查，并发布结果：
|
||||
|
||||
```markdown
|
||||
@main-agent ✅ **VERIFICATION_PASSED**
|
||||
|
||||
## 三向一致性检查
|
||||
|
||||
### 1️⃣ 需求 → 设计
|
||||
| 需求项 | 设计覆盖 | 状态 |
|
||||
|--------|---------|------|
|
||||
| IP 5次/5分钟 | login_attempts + 计数逻辑 | ✅ |
|
||||
| 用户名 3次 | login_attempts + 计数逻辑 | ✅ |
|
||||
| 锁定 30/15分钟 | locked_until 字段 | ✅ |
|
||||
|
||||
✅ **需求→设计: 通过**
|
||||
|
||||
### 2️⃣ 设计 → 编码
|
||||
| 设计 | 代码 | 状态 |
|
||||
|------|------|------|
|
||||
| 数据库表 | 001_login_attempts.sql | ✅ |
|
||||
| 检查逻辑 | login_checker.py | ✅ |
|
||||
|
||||
✅ **设计→编码: 通过**
|
||||
|
||||
### 3️⃣ 需求 → 编码
|
||||
| 需求 | 代码实现 | 状态 |
|
||||
|------|---------|------|
|
||||
| IP 5次/5分钟 | IP_MAX_ATTEMPTS=5, IP_WINDOW=300 | ✅ |
|
||||
| 锁定 30/15分钟 | IP_LOCK_DURATION=1800 | ✅ |
|
||||
|
||||
✅ **需求→编码: 通过**
|
||||
|
||||
## 最终结论
|
||||
✅ **三向一致性检查全部通过**
|
||||
**VERDICT**: ✅ APPROVED FOR MERGE
|
||||
|
||||
---
|
||||
**执行者**: Main Agent
|
||||
**完成时间**: 2026-07-01 13:00
|
||||
```
|
||||
|
||||
**Step 6: 关闭 Issue**
|
||||
|
||||
Main Agent 更新 Issue 状态：
|
||||
|
||||
```markdown
|
||||
## 最终状态: ✅ COMPLETED
|
||||
|
||||
### 完成链路
|
||||
1. ✅ Execute Sub Agent 完成 (12:00)
|
||||
2. ✅ Review Sub Agent 通过 (12:30)
|
||||
3. ✅ Test Sub Agent 通过 (12:45)
|
||||
4. ✅ Main Agent 验收通过 (13:00)
|
||||
|
||||
### 三向一致性
|
||||
- 需求 → 设计: ✅
|
||||
- 设计 → 编码: ✅
|
||||
- 需求 → 编码: ✅
|
||||
|
||||
---
|
||||
**状态**: Closed
|
||||
**标签**: completed, verified, D-1
|
||||
```
|
||||
|
||||
#### 5.3.3 Comment 标记约定
|
||||
|
||||
| Sub Agent | 完成标记格式 | 说明 |
|
||||
|-----------|-------------|------|
|
||||
| Execute | `@main-agent ✅ EXECUTE_DONE` | 包含交付物清单 |
|
||||
| Review | `@main-agent ✅ REVIEW_DONE verdict=approved` | 包含检查结果 |
|
||||
| Test | `@main-agent ✅ TEST_DONE result=passed coverage=85%` | 包含测试结果 |
|
||||
| Main | `@main-agent ✅ VERIFICATION_PASSED` | 包含三向检查结果 |
|
||||
|
||||
#### 5.3.4 流程图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Gitea 协作流程 │
|
||||
│ │
|
||||
│ Main Agent 创建 Issue #42 │
|
||||
│ ├─ 标题: [sanguo_moziplus_v3] 功能描述 │
|
||||
│ ├─ 工作清单: Execute / Review / Test / 验收 │
|
||||
│ └─ 状态表: 初始状态 │
|
||||
│ ↓ │
|
||||
│ Execute Sub Agent 工作... │
|
||||
│ └─ Comment: "@main-agent ✅ EXECUTE_DONE" │
|
||||
│ ↓ │
|
||||
│ Main Agent 读取 Gitea → 感知到 EXECUTE_DONE │
|
||||
│ └─ @review @test 请开始工作 │
|
||||
│ ↓ │
|
||||
│ Review + Test 并行工作... │
|
||||
│ ├─ Review: "@main-agent ✅ REVIEW_DONE verdict=approved" │
|
||||
│ └─ Test: "@main-agent ✅ TEST_DONE result=passed" │
|
||||
│ ↓ │
|
||||
│ Main Agent 读取 Gitea → 感知到 REVIEW_DONE + TEST_DONE │
|
||||
│ └─ 开始三向一致性检查 │
|
||||
│ ↓ │
|
||||
│ Main Agent Comment: "@main-agent ✅ VERIFICATION_PASSED" │
|
||||
│ ↓ │
|
||||
│ Main Agent 更新 Issue → Closed ✅ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 5.3.5 偏差处理
|
||||
|
||||
如果 Main Agent 在验收时发现偏差：
|
||||
|
||||
```markdown
|
||||
@main-agent ❌ **CONSISSYENCY_ISSUE**
|
||||
|
||||
## 发现偏差
|
||||
|
||||
### 问题: 需求 → 编码 偏差
|
||||
**需求**: "锁定期间即使密码正确也不允许登录"
|
||||
**代码**: login_checker.py:L45 中，锁定检查在密码验证之后执行
|
||||
|
||||
### 处理要求
|
||||
1. 将锁定检查移到密码验证之前
|
||||
2. 添加测试用例验证此场景
|
||||
3. 重新提交 review
|
||||
|
||||
---
|
||||
**标签**: needs-consistency-fix 🔴
|
||||
```
|
||||
|
||||
Sub Agent 修复后重新发布完成标记，Main Agent 重新验收。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user