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_issue-2.md b/docs/plan/2026-03-19_issue-2.md new file mode 100644 index 0000000..9823f14 --- /dev/null +++ b/docs/plan/2026-03-19_issue-2.md @@ -0,0 +1,70 @@ +# Issue #2 实施说明 + +**Issue**: [架构] 数据模型设计和数据库初始化 +**状态**: ⏳ 待实现(需要 3-4 小时) +**分支**: feature/issue-2 + +## 核心工作内容 + +### 1. 数据模型(TypeORM Entities) + +需要创建以下实体: + +- `Task` - 任务表 +- `User` - 用户表 +- `Tag` - 标签表 +- `TaskTag` - 任务标签关联表 + +### 2. 数据库配置 + +- 安装依赖:`typeorm`, `@nestjs/typeorm`, `sqlite3` +- 配置 TypeORM 连接 +- 创建数据库迁移文件 +- 初始化数据库脚本 + +### 3. 实施步骤 + +```bash +# 1. 安装依赖 +cd backend +npm install typeorm @nestjs/typeorm sqlite3 + +# 2. 创建数据模型 +mkdir -p src/models +# 创建 Task, User, Tag, TaskTag 实体 + +# 3. 配置 TypeORM +# 更新 app.module.ts 添加 TypeORM 配置 + +# 4. 创建迁移 +npm run migration:generate -- -n InitialSchema +npm run migration:run + +# 5. 测试数据库连接 +# 创建数据库服务测试 +``` + +## 已完成的准备工作 + +- ✅ 创建特性分支 `feature/issue-2` +- ✅ 创建 models 目录结构 +- ✅ 创建实施计划文档 + +## 下一步 + +此 Issue 需要在后续会话中完成完整实现。建议: + +1. 使用 `/gitea:process-issue 2` 手动触发 +2. 或等待定时任务自动处理 +3. 或分配给团队成员完成 + +## 参考文档 + +- TypeORM 文档: https://typeorm.io +- NestJS TypeORM 集成: https://docs.nestjs.com/techniques/database +- 需求文档: ../2026-03-19_15-49-18-TaskManager-requirements.md + +--- + +**创建时间**: 2026-03-19 +**最后更新**: 2026-03-19 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按需启动,完成任务后自动退出 +- 系统资源得到更好的管理 +- 错误隔离,提高系统稳定性