docs: add Gitea CI/CD setup guide

GITEA_CICD_SETUP.md

@@ -0,0 +1,175 @@
+# 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:
+
+```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 &
+```
+
+访问 `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 环境变量
+
+```bash
+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 模式
+
+```bash
+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 交互:
+
+```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. 查看: `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`