From 3af9fa58e73959fce76bddf8867bf1bd731308f2 Mon Sep 17 00:00:00 2001 From: bojunC <316231662@qq.com> Date: Thu, 19 Mar 2026 17:34:56 +0800 Subject: [PATCH] =?UTF-8?q?feat(scheduler):=20=E4=BF=AE=E6=94=B9=E5=AE=9A?= =?UTF-8?q?=E6=97=B6=E4=BB=BB=E5=8A=A1=E4=B8=BA=E5=AD=90Agent=E6=A8=A1?= =?UTF-8?q?=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 使用 Agent 工具启动独立子Agent处理任务 - 子Agent完成后自动退出，等待下次触发 - 提高系统稳定性和资源管理 - 添加实施计划和模块文档 --- .claude/commands/gitea/start-scheduler.md | 70 +++++++-- .claude/commands/gitea/stop-scheduler.md | 3 +- docs/modules/subagent-scheduler.md | 170 +++++++++++++++++++++ docs/plan/2026-03-19_subagent-scheduler.md | 138 +++++++++++++++++ 4 files changed, 365 insertions(+), 16 deletions(-) create mode 100644 docs/modules/subagent-scheduler.md create mode 100644 docs/plan/2026-03-19_subagent-scheduler.md diff --git a/.claude/commands/gitea/start-scheduler.md b/.claude/commands/gitea/start-scheduler.md index 087e896..41cf054 100644 --- a/.claude/commands/gitea/start-scheduler.md +++ b/.claude/commands/gitea/start-scheduler.md @@ -29,15 +29,30 @@ description: 启动定时任务（Issue 处理和 PR 审核） 3. 按优先级排序 4. 依据 API-QUICK-REFERENCE.md 文档检查依赖是否满足 5. 选择优先级最高的未阻塞 Issue -6. 启动 Agent 处理该 Issue +6. 检查是否有正在运行的子Agent +7. 如果没有，使用 Agent 工具启动子Agent处理该 Issue +8. 子Agent完成后自动退出 +9. 等待下次定时任务 ``` -**Agent 工作流程**： -``` -1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 文档中的 Issue 操作指南获取 Issue 详情 +**使用 Agent 工具启动子Agent**： +```javascript +Agent({ + subagent_type: "general-purpose", + description: `处理 Issue #{number}`, + prompt: `你是一个 Code Agent，负责处理 Gitea Issue #{number}。 + +环境变量（已配置）： +- GITEA_URL: ${process.env.GITEA_URL} +- GITEA_TOKEN: ${process.env.GITEA_TOKEN} +- GITEA_OWNER: ${process.env.GITEA_OWNER} +- GITEA_REPO: ${process.env.GITEA_REPO} + +工作流程： +1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 文档中的 Issue 操作指南获取 Issue #{number} 详情 2. 解析 Issue 描述，提取需求 3. 依据 API-QUICK-REFERENCE.md 文档检查依赖 Issue 是否已完成 -4. 如果依赖未满足，跳过该 Issue +4. 如果依赖未满足，报告并退出 5. 创建特性分支: feature/issue-{number} 6. 分析需要实现的功能 7. 读取现有代码结构 @@ -59,6 +74,10 @@ description: 启动定时任务（Issue 处理和 PR 审核） - 描述: 关联 Issue，说明实现内容 - 标签: 继承 Issue 的标签 13. 依据 API-QUICK-REFERENCE.md 文档中的 Issue 评论操作指南在 Issue 中添加评论，说明已创建 PR + +完成后报告处理结果（成功/失败/跳过）并退出。`, + run_in_background: false // 前台运行，完成后继续主流程 +}) ``` ### 第三步：创建 PR Agent 定时任务 @@ -70,12 +89,27 @@ description: 启动定时任务（Issue 处理和 PR 审核） 每 N 分钟执行一次： 1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 文档中的 Pull Request 操作指南获取所有打开的 Pull Requests 2. 过滤出未审核的 -3. 对每个 PR 启动 Agent 审核 +3. 对每个 PR 使用 Agent 工具启动子Agent审核 +4. 子Agent完成后自动退出 +5. 等待下次定时任务 ``` -**Agent 审核流程**： -``` -1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 文档中的 Pull Request 操作指南获取 PR 详情 +**使用 Agent 工具启动子Agent**： +```javascript +Agent({ + subagent_type: "general-purpose", + description: `审核 PR #{number}`, + prompt: `你是一个 PR Agent，负责审核 Gitea PR #{number}。 + +环境变量（已配置）： +- GITEA_URL: ${process.env.GITEA_URL} +- GITEA_TOKEN: ${process.env.GITEA_TOKEN} +- GITEA_OWNER: ${process.env.GITEA_OWNER} +- GITEA_REPO: ${process.env.GITEA_REPO} +- AUTO_MERGE: ${process.env.AUTO_MERGE || false} + +工作流程： +1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 文档中的 Pull Request 操作指南获取 PR #{number} 详情 - 代码变更 - 关联的 Issue - 提交历史 @@ -104,10 +138,14 @@ description: 启动定时任务（Issue 处理和 PR 审核） - 批准（APPROVE） - 根据 AUTO_MERGE 配置决定是否自动合并 -6. 如果需要修改 - - 启动修复 Agent +6. 如果需要修改且 AUTO_MERGE=true + - 使用 Agent 工具启动修复子Agent - 修复问题 - 推送修复 + +完成后报告审核结果（通过/需修改/拒绝）并退出。`, + run_in_background: false // 前台运行，完成后继续主流程 +}) ``` ### 第四步：显示任务状态 @@ -198,10 +236,12 @@ Agent 将自动： 1. **会话限制**: 定时任务仅在当前会话有效，会话结束后需要重新启动 2. **自动过期**: 定时任务最多运行 3 天，之后会自动删除 -3. **并发控制**: 同一时间只处理一个 Issue，避免冲突 -4. **依赖检查**: 会自动跳过依赖未满足的 Issues -5. **错误重试**: 如果 Agent 执行失败，会在下次定时任务时重试 -6. **手动干预**: 可以随时使用 `/gitea-process-issue` 手动处理特定 Issue +3. **子Agent模式**: 每次定时触发时启动独立的子Agent，完成后自动退出 +4. **并发控制**: 同一时间只运行一个子Agent，避免冲突 +5. **依赖检查**: 会自动跳过依赖未满足的 Issues +6. **错误重试**: 如果子Agent执行失败，会在下次定时任务时重试 +7. **资源管理**: 子Agent完成后自动释放资源，不影响主进程 +8. **手动干预**: 可以随时使用 `/gitea-process-issue` 手动处理特定 Issue ## 工作流示例 diff --git a/.claude/commands/gitea/stop-scheduler.md b/.claude/commands/gitea/stop-scheduler.md index bf7a3e7..2d71812 100644 --- a/.claude/commands/gitea/stop-scheduler.md +++ b/.claude/commands/gitea/stop-scheduler.md @@ -45,8 +45,9 @@ description: 停止所有定时任务 ## 注意事项 1. **不可恢复**: 停止后无法恢复，需要重新创建定时任务 -2. **正在进行**: 如果有 Agent 正在工作，它不会立即停止，而是完成当前任务 +2. **正在运行的子Agent**: 如果有子Agent正在工作，它不会立即停止，而是完成当前任务后自动退出 3. **清理**: 停止任务不会删除已创建的代码或 PRs +4. **子Agent模式**: 定时任务使用子Agent模式运行，停止定时任务不影响已启动的子Agent ## 相关命令 diff --git a/docs/modules/subagent-scheduler.md b/docs/modules/subagent-scheduler.md new file mode 100644 index 0000000..07506c5 --- /dev/null +++ b/docs/modules/subagent-scheduler.md @@ -0,0 +1,170 @@ +# 子Agent模式定时任务 + +## 概述 + +定时任务系统已从主进程执行模式改为子Agent执行模式。每次定时任务触发时，会启动一个独立的子Agent来处理任务，完成后子Agent自动退出，主进程等待下一次触发。 + +## 架构 + +### 主进程职责 +- 维护定时任务调度（使用 CronCreate） +- 在每次触发时扫描待处理的 Issues/PRs +- 使用 Agent 工具启动子Agent +- 等待子Agent完成 +- 不执行具体的业务逻辑 + +### 子Agent职责 +- 接收具体的任务（处理 Issue 或审核 PR） +- 拥有独立的上下文和执行环境 +- 完成任务后报告结果 +- 自动退出 + +## 工作流程 + +### Code Agent 流程 + +```mermaid +graph TD + A[定时触发] --> B[扫描未处理的 Issues] + B --> C[过滤和排序] + C --> D{是否有未处理 Issue?} + D -->|是| E[启动子Agent] + D -->|否| F[等待下次触发] + E --> G[子Agent处理 Issue] + G --> H[创建分支和代码] + H --> I[运行测试] + I --> J[提交代码和创建 PR] + J --> K[报告结果并退出] + K --> F +``` + +### PR Agent 流程 + +```mermaid +graph TD + A[定时触发] --> B[扫描未审核的 PRs] + B --> C{是否有未审核 PR?} + C -->|是| D[启动子Agent] + C -->|否| E[等待下次触发] + D --> F[子Agent审核 PR] + F --> G[代码质量检查] + G --> H[测试检查] + H --> I[安全检查] + I --> J{审核通过?} + J -->|是| K[批准 PR] + J -->|否| L[请求修改] + K --> M[报告结果并退出] + L --> M + M --> E +``` + +## 技术实现 + +### 使用 Agent 工具 + +```javascript +// Code Agent +Agent({ + subagent_type: "general-purpose", + description: `处理 Issue #{number}`, + prompt: `完整的工作流程说明...`, + run_in_background: false // 前台运行 +}) + +// PR Agent +Agent({ + subagent_type: "general-purpose", + description: `审核 PR #{number}`, + prompt: `完整的审核流程说明...`, + run_in_background: false // 前台运行 +}) +``` + +### 并发控制 + +- 定时任务检查是否有正在运行的子Agent +- 如果有，跳过本次触发 +- 如果没有，启动新的子Agent + +## 优势 + +### 1. 隔离性 +- 每个子Agent有独立的上下文 +- 子Agent的错误不影响主进程 +- 任务之间相互独立 + +### 2. 稳定性 +- 子Agent崩溃不影响定时任务继续运行 +- 资源泄漏被限制在子Agent内 +- 主进程保持轻量 + +### 3. 可观察性 +- 每个子Agent的任务清晰可追踪 +- 独立的日志和状态 +- 更容易调试问题 + +### 4. 资源管理 +- 子Agent完成后自动释放资源 +- 避免长时间运行导致的内存问题 +- 更好的系统资源利用率 + +## 配置 + +### 环境变量 + +```bash +# Gitea 配置 +GITEA_URL=http://your-gitea-url +GITEA_TOKEN=your-api-token +GITEA_OWNER=your-username +GITEA_REPO=your-repo-name + +# 定时间隔（分钟） +CODE_AGENT_INTERVAL=5 # Code Agent 触发间隔 +PR_AGENT_INTERVAL=10 # PR Agent 触发间隔 + +# 审核配置 +AUTO_MERGE=false # 是否自动合并审核通过的 PR +``` + +### 定时间隔建议 + +根据项目规模调整： +- **小型项目** (< 10 个 Issues): 3-5 分钟 +- **中型项目** (10-50 个 Issues): 5-10 分钟 +- **大型项目** (> 50 个 Issues): 10-15 分钟 + +## 使用方式 + +### 启动定时任务 +```bash +/gitea:start-scheduler +``` + +### 停止定时任务 +```bash +/gitea:stop-scheduler +``` + +### 查看状态 +```bash +/gitea:status +``` + +## 注意事项 + +1. **会话限制**: 定时任务仅在当前会话有效 +2. **自动过期**: 定时任务最多运行 3 天 +3. **并发控制**: 同一时间只运行一个子Agent +4. **错误重试**: 子Agent失败后会在下次触发时重试 +5. **资源管理**: 子Agent完成后自动释放资源 + +## 相关文件 + +- `.claude/commands/gitea/start-scheduler.md` - 启动定时任务 +- `.claude/commands/gitea/stop-scheduler.md` - 停止定时任务 +- `docs/plan/2026-03-19_subagent-scheduler.md` - 实施计划 + +## 更新历史 + +- 2026-03-19: 从主进程模式迁移到子Agent模式 diff --git a/docs/plan/2026-03-19_subagent-scheduler.md b/docs/plan/2026-03-19_subagent-scheduler.md new file mode 100644 index 0000000..a16498f --- /dev/null +++ b/docs/plan/2026-03-19_subagent-scheduler.md @@ -0,0 +1,138 @@ +# 修改定时任务为子Agent模式 + +## 目标 + +将定时任务从主进程执行改为子Agent执行模式，实现： +1. 启动定时任务时，启动一个子Agent +2. 子Agent完成任务后自动退出 +3. 主进程等待下一个定时任务触发 + +## 背景 + +当前实现： +- 使用 CronCreate 创建定时任务 +- 定时任务在主进程中直接执行Agent逻辑 +- 可能存在长时间运行导致的问题 + +目标实现： +- 定时任务触发时，使用Agent工具启动子Agent +- 子Agent独立运行，有自己的上下文 +- 子Agent完成后自动退出，不影响主进程 + +## 实施步骤 + +### 1. 修改 start-scheduler.md + +**当前逻辑**： +``` +每 N 分钟执行一次： +1. 获取所有打开的 Issues +2. 过滤出未处理的 +3. 选择优先级最高的Issue +4. 在主进程中处理该Issue +``` + +**修改后逻辑**： +``` +每 N 分钟执行一次： +1. 获取所有打开的 Issues +2. 过滤出未处理的 +3. 选择优先级最高的Issue +4. 使用 Agent 工具启动子Agent处理该Issue +5. 子Agent完成后自动退出 +6. 等待下次定时任务 +``` + +### 2. 使用 Agent 工具 + +使用 Agent 工具启动子Agent： +```typescript +Agent({ + subagent_type: "general-purpose", + description: "处理 Issue #{number}", + prompt: "处理 Gitea Issue #{number} 的完整流程...", + run_in_background: false // 前台运行，完成后继续 +}) +``` + +### 3. 修改内容 + +#### start-scheduler.md 的修改点 + +1. **Code Agent 定时任务逻辑**（第24-33行） + - 将"启动 Agent 处理该 Issue"改为使用 Agent 工具 + +2. **Agent 工作流程**（第35-62行） + - 将详细工作流程移到子Agent的prompt中 + +3. **PR Agent 定时任务逻辑**（第68-74行） + - 将"启动 Agent 审核"改为使用 Agent 工具 + +4. **Agent 审核流程**（第76-111行） + - 将详细工作流程移到子Agent的prompt中 + +### 4. 优势 + +1. **隔离性**：子Agent有独立的上下文，不会干扰主进程 +2. **稳定性**：子Agent崩溃不影响定时任务继续运行 +3. **可观察性**：每个子Agent的任务清晰可追踪 +4. **资源管理**：子Agent完成后自动释放资源 + +### 5. 实施细节 + +#### Code Agent Prompt 模板 +``` +你是一个 Code Agent，负责处理 Gitea Issue #{number}。 + +工作流程： +1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 获取 Issue 详情 +2. 解析需求，检查依赖 +3. 创建分支 feature/issue-{number} +4. 实现功能，编写测试 +5. 运行测试，确保通过 +6. 提交代码，创建 PR +7. 在 Issue 中添加评论说明 + +完成后报告结果并退出。 +``` + +#### PR Agent Prompt 模板 +``` +你是一个 PR Agent，负责审核 Gitea PR #{number}。 + +工作流程： +1. 依据 .claude/commands/gitea/API-QUICK-REFERENCE.md 获取 PR 详情 +2. 代码质量检查 +3. 测试检查 +4. 安全检查 +5. 创建审核评论，决定是否批准 +6. 如需修改，启动修复Agent + +完成后报告结果并退出。 +``` + +## 风险与缓解 + +1. **风险**：子Agent启动开销 + - **缓解**：定时任务间隔已考虑此开销 + +2. **风险**：子Agent失败无法重试 + - **缓解**：下次定时任务会再次尝试 + +3. **风险**：并发控制需要确保 + - **缓解**：在启动子Agent前检查是否有正在运行的任务 + +## 测试计划 + +1. 启动定时任务 +2. 创建测试Issue +3. 观察子Agent启动和处理 +4. 验证子Agent自动退出 +5. 确认定时任务继续运行 + +## 预期结果 + +- 定时任务启动后，主进程保持轻量 +- 子Agent按需启动，完成任务后自动退出 +- 系统资源得到更好的管理 +- 错误隔离，提高系统稳定性