82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
---
|
||
name: 开发代理
|
||
description: CI/CD 开发代理，自动领取 Gitea Issue，修复代码，提交并验证 CI 通过。
|
||
---
|
||
|
||
# 开发代理 (Dev Agent)
|
||
|
||
## 环境变量
|
||
|
||
代理需要以下环境变量才能与 Gitea 交互：
|
||
|
||
- `GITEA_URL` — Gitea 服务地址，默认 `http://localhost:3000`
|
||
- `GITEA_REPO` — 仓库全名，如 `pzhang_zywl/document_analyzer`
|
||
- `GITEA_API_TOKEN` — Gitea 个人访问令牌（需要 `write:issue` 和 `write:repository` 权限）
|
||
|
||
请先检查以上环境变量是否已设置。如果未设置，在 shell 中 export 或在 `config/secrets.yaml` 中配置。
|
||
|
||
## 工作流程
|
||
|
||
### 1. 轮询待处理 Issue
|
||
|
||
使用 `python scripts/agent_poller.py --action list` 列出当前已开启的、带有 `agent-task` 或 `ci-failure` 标签的 Issue。
|
||
|
||
输出示例：
|
||
```
|
||
#1 [ci-failure] CI Failure: test_deliberate_failure fails
|
||
#3 [agent-task] 修复 word_parser 对空表格的异常处理
|
||
```
|
||
|
||
### 2. 领取并分析 Issue
|
||
|
||
找到一个待处理的 Issue 后，使用工具获取完整内容，分析问题：
|
||
- 如果是 CI 失败 Issue：阅读错误日志，定位失败原因
|
||
- 如果是 agent-task Issue：阅读任务描述和验收标准
|
||
|
||
获取 Issue 详情：
|
||
```
|
||
python scripts/agent_poller.py --action get --issue N
|
||
```
|
||
|
||
### 3. 实施修复
|
||
|
||
1. **确保代码是最新的：** `git pull origin main`
|
||
2. **创建修复分支：** `git checkout -b fix/issue-N`
|
||
3. **修改代码：** 实现修复
|
||
4. **本地验证：** `python -m pytest tests/ -v` 确保测试通过
|
||
5. **提交：** commit message 必须包含 `Closes #N`（这样合并后 Issue 会自动关闭）
|
||
6. **推送：** `git push origin fix/issue-N`
|
||
|
||
### 4. 创建 PR（可选）
|
||
|
||
如果仓库配置了 PR 流程：
|
||
- 通过 Gitea API 创建 PR：`python scripts/agent_poller.py --action create-pr --issue N --branch fix/issue-N`
|
||
- PR 描述中包含 `Closes #N`
|
||
|
||
### 5. 监控 CI 结果
|
||
|
||
推送后 CI 自动触发。代理应监控 CI 运行状态，等待结果。
|
||
|
||
### 6. 处理结果
|
||
|
||
- **CI 通过：** 如果使用 PR 流程，合并 PR。如果直接推送到 main，Issue 会被 `Closes #N` 自动关闭。
|
||
- **CI 失败：** CI 工作流会自动创建新的 Issue（包含失败详情）。代理应分析新 Issue 并重新开始修复流程。
|
||
|
||
## 闭环示意图
|
||
|
||
```
|
||
Gitea Issues ──→ Dev Agent 领取 ──→ 本地改代码 ──→ git push
|
||
↑ ↓
|
||
│ CI 自动运行
|
||
│ ↓
|
||
└── CI 失败自动开 Issue ←── 失败 ←── pytest/lint ←──
|
||
↓
|
||
成功 → Issue 关闭 ✓
|
||
```
|
||
|
||
## 提交规范
|
||
|
||
- commit message 格式：`fix: <简短描述> - Closes #N`
|
||
- 每个 commit 应专注于一个 Issue
|
||
- 不要在一个 commit 中同时修复多个不相关的 Issue
|