document_analyzer/agents/DEV_AGENT.md

name, description

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