---
date: 2026-05-15
kind: learning
scope: scripts/ops/gitea
---

# `gitea` CLI 子命令顺序：`<verb> <num>` 不是 `<num> <verb>`

## 现象

试图给 PR #369 加评论，连发 2 次 fail 才发现 syntax 错：

```bash
# ❌ 错（看起来"自然"但 CLI 不支持）
scripts/ops/gitea pr 369 comment --body "..."
scripts/ops/gitea issue 369 comment --body "..."

# ✅ 对
scripts/ops/gitea issue comment 369 --body "..."
```

## 为什么容易踩

1. **shorthand 误导**：`gitea issue 369`（无 verb）能直接打印 issue——argparse 把单独的 num 当成 `get` 子命令的缩写。这让人误以为"verb 挂在 num 后面"。
2. **错误回显被 heredoc 掩盖**：`gitea pr 369 comment --body "$(cat <<EOF ... EOF)"` 执行失败时，argparse 的 `error: unrecognized arguments` 在 stderr 一闪而过，stdout 把 heredoc body 整段回显出来，**看上去像 dry-run 成功**。`2>&1 | tail -5` 没救到——因为 body 把 error 行挤出 tail 窗口。
3. `gitea pr` **根本没有 `comment` 子命令**（PR 在 Gitea API 里走 issue endpoint）；`gitea issue comment <num>` 才是。

## 如何避免

- **post 类操作必须 post-verify**：发完立刻 `curl /issues/<n>/comments | jq '.[-1].id'` 或 `gitea issue get <n>` 看最后一条是否是自己刚发的。silent success 不能信。
- **新 CLI 用户先 `--help`**：`scripts/ops/gitea <topic> --help` 一行确认 verb 列表 + 参数顺序，比"凭直觉拼"快。
- **写 CLI 时考虑**：是否把 `<num>` 放 verb 前面更符合用户直觉（`gitea issue 369 comment --body`）？或者至少在 verb 未识别时 print 一行"Did you mean `gitea issue comment 369`?"hint。

## Refs

- 项目 CLI 设计规范：`docs/standards/15-cli-design-spec.md`
- 当前 CLI 源码：`scripts/ops/gitea`（topic → verb → positional 三层）