# scripts/ops/

本目录是仓库的 ops 工具（Gitea 操作、备份清理、PR 整理等）集中地。

## 文件分类

| 类型 | 命名 | 例子 |
|---|---|---|
| **CLI 工具** | 无扩展名可执行 | `gitea` |
| **一次性 / 批处理脚本** | `*.py` / `*.sh` | `setup-gitea-labels.py`, `sweep-remote-stale.py`, `weekly-review.py` |
| **共享 library**（内部使用） | `_xxx_api.py` 下划线前缀 | `_gitea_api.py`, `_ai_review_common.sh` |
| **CI checker** | `check-*.sh` | `check-env-coverage.sh`, `check-migration-count.sh` |

## CLI 工具

### `gitea` — 本仓库 Gitea ops 的薄 CLI 出口

一句话：把 AI / 团队成员手写 `curl + python heredoc` 调 Gitea API 收敛到一行命令。

**调用方式**：

```bash
./scripts/ops/gitea --help                          # 入口帮助
./scripts/ops/gitea issue 331                       # 读 issue
./scripts/ops/gitea issue list --label Kind/Feature # 列 issue
./scripts/ops/gitea issue comment 331 --body "..."  # 加评论（--body - 读 stdin）
./scripts/ops/gitea pr 318                          # 读 PR
./scripts/ops/gitea label add 331 Owner/Chentao     # 加 label
./scripts/ops/gitea label remove 331 Status/待领取  # 移 label
```

**全局 flag**：`--json` / `--verbose -v` / `--no-color` / `--dry-run -n`（任意位置）

**与 `_gitea_api.py` 的关系**：CLI 是 `_gitea_api.py` library 的薄出口，业务原语（HTTP / token / 实体操作）都在 library 层。批处理脚本应该 `from _gitea_api import Api` 直接用，而不是 subprocess 调 CLI。

**鉴权**：`GITEA_API_TOKEN` 或 `GITEA_TOKEN` 环境变量（详见 CLAUDE.md "Gitea 平台配置"）。

**退出码 4 档**：`0` 成功 / `1` 用户错 / `2` 系统错（可重试）/ `3` 约定拦截（不重试）。

### 设计规范

新写 CLI 必读 [`docs/standards/15-cli-design-spec.md`](../../docs/standards/15-cli-design-spec.md) — 元规则 5 条 + 退出码语义 + JSON 错误结构 + 反模式清单。

---

## 共享 library

- [`_gitea_api.py`](./_gitea_api.py) — Gitea REST API client + token/repo 解析 + `paginate` / `ensure_label` / `find_issue_by_title`。**新脚本调 Gitea API 一律 `from _gitea_api import ...`，禁止重抄 Api class**（CLAUDE.md 硬规则）。

## 一次性脚本约定

- 顶部 docstring 必给：用途 / 模式一行一例 / Auth 要求 / 退出码 / 安全网
- dry-run 默认；破坏性操作必须 `--execute` 显式确认
- 批量 mutation 必须留 audit log 到 `testing/reports/<script-name>-<ts>.md`
- 复用 `_gitea_api.py` 等 library，不重写 HTTP / token 解析

参考范式：[`sweep-remote-stale.py`](./sweep-remote-stale.py)、[`weekly-retro-issue.py`](./weekly-retro-issue.py)、[`setup-gitea-labels.py`](./setup-gitea-labels.py)。

## 测试

CLI 工具的 L1 集成测试放在 [`testing/ops/`](../../testing/ops/)，命名 `<tool>.test.py`，直接 `python3 testing/ops/<tool>.test.py` 跑。