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:

```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 &
```

访问 `$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：

```bash
# 设置要使用的账号
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:**
```bash
# 设置要使用的 Gitea 账号（从 ~/.gitea/config.yaml 读取配置）
export GITEA_USER=pzhangzywl
```

### 方式 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 检查 `$GITEA_URL/$GITEA_REPO/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. 查看: `$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`