From 03a3d9ae5e7c7ed89dd7188c797fa7936432e5ca Mon Sep 17 00:00:00 2001 From: claude_dev Date: Wed, 1 Jul 2026 20:32:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(v0.5):=20=E6=B7=BB=E5=8A=A0=20Gitea=20?= =?UTF-8?q?=E5=8D=8F=E4=BD=9C=E6=B5=81=E7=A8=8B=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加 Issue 结构（工作清单模式） - 添加 6 步工作流程 - 添加 Comment 标记约定 - 添加流程图 - 添加偏差处理机制 - 简化感知机制：Sub 完成标记 → Main 主动读取 Gitea --- ...n-v0.5-dynamic-orchestration-integrated.md | 274 +++++++++++++++++- 1 file changed, 272 insertions(+), 2 deletions(-) diff --git a/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md b/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md index 4303b3b..beb0c7b 100644 --- a/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md +++ b/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md @@ -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 重新验收。 ---