diff --git a/agents/DEV_AGENT.md b/agents/DEV_AGENT.md new file mode 100644 index 0000000..7f578a3 --- /dev/null +++ b/agents/DEV_AGENT.md @@ -0,0 +1,81 @@ +--- +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 diff --git a/scripts/agent_poller.py b/scripts/agent_poller.py new file mode 100644 index 0000000..055b143 --- /dev/null +++ b/scripts/agent_poller.py @@ -0,0 +1,118 @@ +"""Helper for dev agent to interact with Gitea issues. + +Usage: + python scripts/agent_poller.py --action list + python scripts/agent_poller.py --action get --issue 1 + python scripts/agent_poller.py --action comment --issue 1 --body "Working on this" + python scripts/agent_poller.py --action create-pr --issue 1 --branch fix/issue-1 +""" + +import argparse +import json +import os +import sys +import urllib.request +import urllib.error + +GITEA_URL = os.environ.get("GITEA_URL", "http://localhost:3000") +GITEA_REPO = os.environ.get("GITEA_REPO", "pzhang_zywl/document_analyzer") +GITEA_TOKEN = os.environ.get("GITEA_API_TOKEN", "") + +BASE = f"{GITEA_URL}/api/v1/repos/{GITEA_REPO}" +TARGET_LABELS = {"agent-task", "ci-failure"} + + +def _req(method, path, data=None): + url = f"{BASE}{path}" + payload = json.dumps(data).encode("utf-8") if data else None + req = urllib.request.Request(url, data=payload, method=method) + req.add_header("Authorization", f"token {GITEA_TOKEN}") + req.add_header("Content-Type", "application/json") + try: + with urllib.request.urlopen(req) as resp: + return json.loads(resp.read()) + except urllib.error.HTTPError as e: + body = e.read().decode() + print(f"API Error {e.code}: {body}", file=sys.stderr) + sys.exit(1) + + +def list_issues(): + issues = _req("GET", "/issues?state=open") + if not issues: + print("No open issues found.") + return [] + for i in issues: + labels = [l["name"] for l in i.get("labels", [])] + if TARGET_LABELS & set(labels): + print(f"#{i['number']} [{', '.join(labels)}] {i['title']}") + return issues + + +def get_issue(num): + i = _req("GET", f"/issues/{num}") + print(f"## #{i['number']}: {i['title']}") + print(f"State: {i['state']}") + labels = [l["name"] for l in i.get("labels", [])] + print(f"Labels: {', '.join(labels) if labels else 'none'}") + print() + print(i.get("body", "(no description)")) + return i + + +def comment_issue(num, body): + i = _req("POST", f"/issues/{num}/comments", {"body": body}) + print(f"Comment added to #{num}") + return i + + +def create_pr(issue_num, branch): + # Get issue title for PR description + issue = _req("GET", f"/issues/{issue_num}") + title = f"Fix #{issue_num}: {issue['title'].replace('CI Failure: ', '')}" + body = f"Closes #{issue_num}\n\n{issue.get('body', '')}\n\n🤖 Generated by dev agent" + pr = _req("POST", "/pulls", { + "title": title, + "head": branch, + "base": "main", + "body": body, + }) + print(f"PR created: {pr.get('html_url', pr.get('url', ''))}") + return pr + + +def main(): + parser = argparse.ArgumentParser(description="Dev agent Gitea helper") + parser.add_argument("--action", required=True, + choices=["list", "get", "comment", "create-pr"]) + parser.add_argument("--issue", type=int) + parser.add_argument("--branch") + parser.add_argument("--body") + args = parser.parse_args() + + if not GITEA_TOKEN: + print("Error: GITEA_API_TOKEN environment variable is not set.", file=sys.stderr) + print("Set it via: export GITEA_API_TOKEN=your-token", file=sys.stderr) + sys.exit(1) + + if args.action == "list": + list_issues() + elif args.action == "get": + if not args.issue: + print("--issue is required for 'get' action", file=sys.stderr) + sys.exit(1) + get_issue(args.issue) + elif args.action == "comment": + if not args.issue or not args.body: + print("--issue and --body are required for 'comment' action", file=sys.stderr) + sys.exit(1) + comment_issue(args.issue, args.body) + elif args.action == "create-pr": + if not args.issue or not args.branch: + print("--issue and --branch are required for 'create-pr' action", file=sys.stderr) + sys.exit(1) + create_pr(args.issue, args.branch) + + +if __name__ == "__main__": + main()