document_analyzer/GITEA_CICD_SETUP.md

Gitea CI/CD 环境配置指南

架构总览

Gitea (localhost:3000)                    Dev Agent
  ├── Issues (任务管理)        ←→    agent_poller.py (轮询/领取)
  ├── Actions (CI/CD)          ←→    ci.yml (自动测试)
  └── Git (版本管理)           ←→    git push / git clone

闭环: Issue → Agent改代码 → Push → CI测试 → 失败自动开工单 → Agent再领

组件清单

组件	位置	说明
Gitea 服务	http://localhost:3000	SQLite 数据库，Actions 已启用
Actions Runner	C:\Users\peterz\tools\act_runner\	Shell 模式，v0.2.11
仓库	pzhang_zywl/document_analyzer	22+ 文件，CI/CD 已配置
API Token	用户自行生成	Settings → Applications → Generate Token

环境搭建

1. Gitea 管理

启动 Gitea:

# Gitea 服务
export GITEA_WORK_DIR=/c/Users/peterz/tools/gitea/data
cd /c/Users/peterz/tools/gitea
nohup ./gitea.exe web --config /c/Users/peterz/tools/gitea/data/app.ini > data/gitea.log 2>&1 &

# Gitea Runner
nohup /c/Users/peterz/tools/act_runner/act_runner.exe daemon > /c/Users/peterz/tools/act_runner/runner.log 2>&1 &

访问 http://localhost:3000 即可使用。

2. 创建 Gitea API Token

1. 登录 Gitea → 右上角头像 → Settings → Applications
2. 或在浏览器直接打开: http://localhost:3000/user/settings/applications
3. Manage Access Tokens → Generate Token
4. 权限勾选: write:issue write:repository write:user
5. 复制 token 备用

3. 配置 Actions Secrets

在仓库 Secrets 页面添加:

• Name: GITEA_TOKEN
• Value: 上一步生成的 API token

4. 配置 Dev Agent 环境变量

export GITEA_API_TOKEN="你的token"
export GITEA_URL="http://localhost:3000"
export GITEA_REPO="pzhang_zywl/document_analyzer"

CI/CD 工作流

ci.yml - 主流水线

触发条件: push 到 main / pull_request 到 main

git clone → pip install → pytest → 
  失败 → if: failure() → create_failure_issue.py → 自动创建 Issue
  成功 → 结束 (commit 中的 "Closes #N" 自动关闭对应 Issue)

关键文件

文件	作用
.gitea/workflows/ci.yml	CI 配置（含失败自动开 Issue 逻辑）
scripts/create_failure_issue.py	CI 失败时调用的 Issue 创建脚本
scripts/agent_poller.py	Dev Agent 使用的 Issue 轮询/操作工具
requirements.txt	项目依赖
tests/test_sample.py	测试文件
agents/DEV_AGENT.md	Dev Agent 系统指令
agents/AGENT.md	文档分析 Agent（原始功能）

设计决策

• 不使用 actions/checkout@v4: 国内无法访问 GitHub，改用 git clone 从本地 Gitea 拉取
• if: failure() 在 step 级别触发: 比跨 workflow 的 workflow_run 更可靠
• Token 通过环境变量传递: 避免 PowerShell 参数解析问题

Dev Agent 使用指南

方式 A: Claude Code Agent 模式

cd /c/Users/peterz/projects/document_analyzer
export GITEA_API_TOKEN="你的token"
export GITEA_URL="http://localhost:3000"
export GITEA_REPO="pzhang_zywl/document_analyzer"

# 启动 Dev Agent
claude --agent agents/DEV_AGENT.md

对 Agent 说: "检查 Gitea 有没有新的待处理工单，有就处理。"

方式 B: Claude Code 内作为子 Agent

在 Claude Code 对话中直接说:

用 DEV_AGENT.md 检查 http://localhost:3000/pzhang_zywl/document_analyzer/issues 有没有待处理工单

方式 C: 任何其他 Agent

任何支持终端命令的 AI Agent 都可以通过 agent_poller.py 与 Gitea 交互:

# 列出待处理 Issue
python scripts/agent_poller.py --action list

# 查看 Issue 详情
python scripts/agent_poller.py --action get --issue N

# 在 Issue 下评论
python scripts/agent_poller.py --action comment --issue N --body "正在处理..."

# 修复代码后创建 PR
git checkout -b fix/issue-N
# ... 修改代码 ...
python -m pytest tests/ -v
git commit -m "fix: <描述> - Closes #N"
git push origin fix/issue-N
python scripts/agent_poller.py --action create-pr --issue N --branch fix/issue-N

Agent 提交规范

规范	说明
分支命名	fix/issue-N 或 feature/issue-N-slug
Commit 格式	fix: <简短描述> - Closes #N
必须包含	Closes #N（合并后自动关闭 Issue）
一个 Issue 一个 commit	不混入无关改动

验证闭环

测试 CI 失败 → 自动开 Issue

1. 在 tests/test_sample.py 中添加故意失败的测试
2. Push → CI 变红 → 自动在 Gitea 创建 Issue（含失败详情）
3. 查看: http://localhost:3000/pzhang_zywl/document_analyzer/issues

测试修复 → CI 通过 → Issue 关闭

1. 修复刚才的失败测试
2. Commit 包含 Closes #N → Push → CI 绿
3. Issue 自动标记为 "closed"

常见问题

Q: CI 跑不起来？

• 确认 Runner 已启动: 访问 Actions 页面看 Runner 是否为 "idle"
• 查看 Runner 日志: tail -f /c/Users/peterz/tools/act_runner/runner.log
• 查看 CI 日志: Gitea Web UI → Actions → 点击具体 run

Q: Issue 没自动创建？

• 确认 GITEA_TOKEN secret 已在仓库设置中配置
• 确认 secret 名称与 ci.yml 中 ${{ secrets.xxx }} 一致

Q: Agent 连不上 Gitea API？

• 确认 GITEA_API_TOKEN 环境变量已设置
• 确认 Gitea 服务正在运行: curl http://localhost:3000/api/v1/version
• 确认 Token 权限包含 write:issue 和 write:repository