合併 main（#16/#17）並解 cli.go 衝突
衝突原因：#13（本分支 927855d）與 #16（main 7badd9e）各自實作了 同一問題（帶旗標命令被全域剖析攔下）的抽取式修正。採 main 現行 架構（dispatch 內 extractGlobals）為準，並保留本分支的： - runVersion 參數檢查（version 不接受參數，TestWiringVersionRejectsArgs） - workflow 命令與接線層測試（workflow_commands_test.go） go build／vet／gofmt 綠；單元測試僅餘 main 既有回歸 （3 個 login 測試，#16 合併後即失敗，與本 PR 無關）。
This commit is contained in:
@@ -1,12 +1,13 @@
|
||||
# teai
|
||||
|
||||
teai 是 Gitea 的命令列（CLI）輔助工具，補足官方 `tea` CLI 缺少的功能。
|
||||
teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式操作 Gitea。
|
||||
名稱取「**te**a + **AI**」：這套工具主要為了讓 AI agent 能以更完整、更可靠的
|
||||
方式操作 Gitea（查詢、回覆、審核、自動化……）。
|
||||
|
||||
- **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置
|
||||
- **目標站點：** `https://gitea.alterminal.com`
|
||||
- **狀態：** 基礎建設（#5：internal/gitea）與工作流命令（#6：whoami/orgs/members/mine/pulls/next）已實作；stalled/xrefs（#7）與日常操作命令（#8）進行中
|
||||
- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）與日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）已實作；stalled/xrefs（#7）進行中
|
||||
- **範圍（#3）：** 不避開 tea 已有的功能；單一工具涵蓋完整操作
|
||||
|
||||
## 安裝與建置
|
||||
|
||||
@@ -23,12 +24,43 @@ go build -o teai ./cmd/teai
|
||||
|
||||
### 設計原則
|
||||
|
||||
1. **與 tea 互補，不重複**：`tea` 已有的功能（clone、issues、pulls、labels、milestones、release、api……）一律用 `tea`。teai 只做 tea 做不到的事：跨倉庫／跨組織聚合、工作流判定（跟進／審核／停滯）、機器可讀輸出。
|
||||
1. **功能自主完整（#3）**：teai 自行實作完整的功能集，**不**以「tea 已有」為由略過（tea 本身存在諸多問題，見 #3）。除了 gitea.py 工作流（跨倉庫／跨組織聚合、工作流判定、機器可讀輸出），也涵蓋日常操作（issues／pulls／labels／milestones／release……），tea 只是相容參考與對照組。由單一二進位檔提供一致介面，避免多工具拼接。
|
||||
2. **規則單一來源**：「最後一則留言不是自己」等工作流判定規則以 `AGENTS.md` 為準，teai 只實作、不改義。規則要變更，先改 AGENTS.md，teai 跟著改。
|
||||
3. **機器可讀優先**：預設輸出 JSON；`--output table` 僅供人工抽查。
|
||||
4. **可直接替換原型**：`gitea.py` 的每個子命令在 teai 都有語義相同的對應命令，可交叉驗證、平滑遷移。
|
||||
5. **認證沿用 tea**：讀 `tea` 的登入組態（`TEA_CONFIG` 或 `~/.config/tea/config.yml`），不另建認證體系。
|
||||
6. **安全預設**：本期全部是查詢類（唯讀）；寫入類（留言、指派、審核者）不在本期範圍，未來加入時須明確 `--yes`。
|
||||
6. **安全預設**：查詢類唯讀；寫入類命令（#8 起）一律要求明確 `--yes`，未確認時不發出任何請求、不產生任何遠端變更。
|
||||
|
||||
### 日常操作（tea 對等指令；#3 不避開 tea 已有功能；#8 已實作）
|
||||
|
||||
issues／pulls／labels／milestones／releases／repos／api 的日常操作，自行實作、輸出一致 JSON、共用同一套認證與全域選項。介面語義以 `tea`／Gitea API 為相容參考。已實作：
|
||||
|
||||
```sh
|
||||
# issues
|
||||
teai issues list --repo <owner>/<repo> [--state open|closed|all]
|
||||
teai issues view --repo <owner>/<repo> <number> [--comments]
|
||||
teai issues create --repo <owner>/<repo> --title … [--body …] [--assignees a,b] --yes
|
||||
teai issues close --repo <owner>/<repo> --yes <number>
|
||||
teai issues comment --repo <owner>/<repo> --body … --yes <number>
|
||||
# pulls（無子命令仍是工作流清單：--mine／--reviewer／--repo）
|
||||
teai pulls list --repo <owner>/<repo> [--state open|closed|all]
|
||||
teai pulls view --repo <owner>/<repo> <number> [--comments]
|
||||
teai pulls create --repo <owner>/<repo> --head <branch> [--base main] --title … [--body …] --yes
|
||||
teai pulls merge --repo <owner>/<repo> [--style merge|rebase|rebase-merge|squash] --yes <number>
|
||||
teai pulls comment --repo <owner>/<repo> --body … --yes <number>
|
||||
# labels／milestones／releases／repos
|
||||
teai labels list --repo <owner>/<repo>
|
||||
teai labels create --repo <owner>/<repo> --name … [--color #RRGGBB] [--description …] --yes
|
||||
teai milestones list --repo <owner>/<repo> [--state open|closed|all]
|
||||
teai milestones create --repo <owner>/<repo> --title … [--description …] [--due RFC3339] --yes
|
||||
teai releases list --repo <owner>/<repo>
|
||||
teai repos list [--org <org>]
|
||||
# 任意 API 呼叫（逃生口）
|
||||
teai api <path> [--method GET|POST|PATCH|DELETE] [--data '<json>'] [--yes]
|
||||
```
|
||||
|
||||
> `--yes` 閘門：所有寫入類命令（create／close／comment／merge／labels create／milestones create／api 非 GET 動詞）未帶 `--yes` 時回 exit 2（用法錯誤），且不發出任何 HTTP 請求。
|
||||
> `teai api` 的 path 內含查詢字串（如 `/repos/a/b/issues?state=closed`）時會正確傳遞。
|
||||
|
||||
### 全域介面
|
||||
|
||||
@@ -48,6 +80,7 @@ teai [全域選項] <命令> [參數]
|
||||
|
||||
| 命令 | 對應 gitea.py | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `teai login list\|add\|default\|remove` | — | 管理 tea 相容登入組態（見下） |
|
||||
| `teai whoami` | `get_current_username` | 目前帳號 |
|
||||
| `teai orgs` | `for_all_organizations` | 我所屬的組織 |
|
||||
| `teai members [--has-work]` | `members [--has-work]` | Agents 團隊成員；`--has-work` 只列有未完成工作者 |
|
||||
@@ -86,6 +119,25 @@ teai next --output table # 人類可讀
|
||||
}
|
||||
```
|
||||
|
||||
### `teai login` — 管理登入
|
||||
|
||||
teai 與 tea 共用同一份組態檔（`--config`／`TEA_CONFIG`，預設 `~/.config/tea/config.yml`）。
|
||||
寫入採行級編輯：只動目標項目的行，未知欄位（`ssh_*` 等）與 `preferences` 區段逐字保留，
|
||||
不改壞 tea 也在使用的檔案；檔案權限 `0600`、暫存檔原子替換。
|
||||
|
||||
```sh
|
||||
teai login list # 列出登入（一律不含 token）
|
||||
teai login add [--url <URL>] [--name <名稱>] [--default=false] [--token <TOKEN>]
|
||||
# 先以 token 呼叫 GET /user 驗證，成功才寫入（並記下帳號）
|
||||
teai login default <名稱> # 設定預設登入
|
||||
teai login remove <名稱> [--yes] # 移除登入；移除預設者時其餘第一筆自動遞補
|
||||
```
|
||||
|
||||
- `login add` 未給 `--token` 時自 stdin 讀一行，避免 token 進 shell 歷史；token 驗證失敗（401）
|
||||
不寫入，結束碼 3。
|
||||
- 未給 `--name` 時：同站（URL 主機相同）已有登入 → 就地更新該項目；否則以 URL 主機為名稱。
|
||||
- 輸出 JSON（`--output table` 供人工查看），欄位 `name`／`url`／`user`／`default`，**永不輸出 token**。
|
||||
|
||||
### `teai stalled [--hours N]` — 管理者巡邏
|
||||
|
||||
```sh
|
||||
|
||||
Reference in New Issue
Block a user