pzhang_zywl
2b5d901cfe
CI / test (push) Successful in 18s
创建 zeekrAI 组织并将 document_analyzer 转移至其下。 更新所有文件中的 repo 路径和 git remote。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
208 lines
6.3 KiB
Markdown
208 lines
6.3 KiB
Markdown
# 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 服务 | `https://git.zywl.me` | SQLite 数据库，Actions 已启用 |
|
||
| Actions Runner | `C:\Users\peterz\tools\act_runner\` | Shell 模式，v0.2.11 |
|
||
| 仓库 | `zeekrAI/document_analyzer` | 22+ 文件，CI/CD 已配置 |
|
||
| API Token | 用户自行生成 | Settings → Applications → Generate Token |
|
||
|
||
## 环境搭建
|
||
|
||
### 1. Gitea 管理
|
||
|
||
启动 Gitea:
|
||
|
||
```bash
|
||
# 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 &
|
||
```
|
||
|
||
访问 `https://git.zywl.me` 即可使用。
|
||
|
||
### 2. 创建 Gitea API Token
|
||
|
||
1. 登录 Gitea → 右上角头像 → Settings → Applications
|
||
2. 或在浏览器直接打开: `https://git.zywl.me/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 环境变量
|
||
|
||
```bash
|
||
export GITEA_API_TOKEN="你的token"
|
||
export GITEA_URL="https://git.zywl.me"
|
||
export GITEA_REPO="zeekrAI/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 使用指南
|
||
|
||
### 前置：配置环境变量（一次性）
|
||
|
||
每次启动 Agent 前需要设置 Gitea API Token：
|
||
|
||
**Windows (双击启动):** 使用项目自带的 `scripts/start_dev_agent.bat`（见下方）
|
||
|
||
**Bash/WSL/Git Bash:**
|
||
```bash
|
||
export GITEA_API_TOKEN="59117246ec418d5d87042de073b0d4197d8054bf"
|
||
export GITEA_URL="https://git.zywl.me"
|
||
export GITEA_REPO="zeekrAI/document_analyzer"
|
||
```
|
||
|
||
### 方式 A: 单次任务模式
|
||
|
||
直接在命令行带上 Prompt 执行一次性任务：
|
||
|
||
```bash
|
||
cd /c/Users/peterz/projects/document_analyzer
|
||
|
||
claude -p --agent agents/DEV_AGENT.md \
|
||
"检查 Gitea 有没有新的 agent-task 或 ci-failure 工单，有就领取并修复。"
|
||
```
|
||
|
||
`-p` 表示非交互模式，执行完退出。适合手动触发或脚本调用。
|
||
|
||
### 方式 B: 持续轮询模式（推荐）
|
||
|
||
```bash
|
||
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: 交互模式
|
||
|
||
```bash
|
||
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 检查 https://git.zywl.me/zeekrAI/document_analyzer/issues 有没有待处理工单
|
||
|
||
### 方式 D: 任何其他 Agent
|
||
|
||
任何支持终端命令的 AI Agent 都可以通过 `agent_poller.py` 与 Gitea 交互:
|
||
|
||
```bash
|
||
# 列出待处理 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. 查看: `https://git.zywl.me/zeekrAI/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 https://git.zywl.me/api/v1/version`
|
||
- 确认 Token 权限包含 `write:issue` 和 `write:repository`
|