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 服务	${GITEA_URL}（见 ~/.gitea/config.yaml）	SQLite 数据库，Actions 已启用
仓库	${GITEA_REPO}（见 ~/.gitea/config.yaml）	CI/CD 已配置
API Token	用户自行生成	配置在 ~/.gitea/config.yaml

环境搭建

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 &

访问 $GITEA_URL（在 ~/.gitea/config.yaml 中配置）即可使用。

2. 创建 Gitea API Token

1. 登录 Gitea → 右上角头像 → Settings → Applications
2. 或在浏览器直接打开: $GITEA_URL/user/settings/applications
3. Manage Access Tokens → Generate Token
4. 权限勾选: write:issue write:repository write:user
5. 复制 token，配置到 ~/.gitea/config.yaml 对应 profile

3. 配置 Actions Secrets

在仓库 Secrets 页面添加:

• Name: GITEA_TOKEN
• Value: token

4. 配置本地 Gitea 连接

编辑 ~/.gitea/config.yaml，配置你的 Gitea profile：

# 设置要使用的账号
export GITEA_USER=pzhangzywl

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 使用指南

前置：配置环境变量（一次性）

每次启动 Agent 前需要设置 Gitea API Token：

Windows (双击启动): 使用项目自带的 scripts/start_dev_agent.bat（见下方）

Bash/WSL/Git Bash:

# 设置要使用的 Gitea 账号（从 ~/.gitea/config.yaml 读取配置）
export GITEA_USER=pzhangzywl

方式 A: 单次任务模式

直接在命令行带上 Prompt 执行一次性任务：

cd /c/Users/peterz/projects/document_analyzer

claude -p --agent agents/DEV_AGENT.md \
  "检查 Gitea 有没有新的 agent-task 或 ci-failure 工单，有就领取并修复。"

-p 表示非交互模式，执行完退出。适合手动触发或脚本调用。

方式 B: 持续轮询模式（推荐）

cd /c/Users/peterz/projects/document_analyzer

claude -p --agent agents/DEV_AGENT.md \
  "用 loop 模式每 10 分钟检查一次 Gitea Issues，发现 agent-task 或 ci-failure 就处理。"

Agent 会持续运行，每隔 10 分钟检查一次，有工单就干活。

方式 C: 交互模式

cd /c/Users/peterz/projects/document_analyzer
claude --agent agents/DEV_AGENT.md

进入交互会话后，对 Agent 说："检查 Gitea Issues 并处理。"

方式 B: Claude Code 内作为子 Agent

在 Claude Code 对话中直接说:

用 DEV_AGENT.md 检查 $GITEA_URL/$GITEA_REPO/issues 有没有待处理工单

方式 D: 任何其他 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. 查看: $GITEA_URL/$GITEA_REPO/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 $GITEA_URL/api/v1/version
• 确认 Token 权限包含 write:issue 和 write:repository