藍圖修訂:不再避開 tea 已有的功能(#3)

- 原則一改為「功能自主完整」:teai 自行實作完整功能集,不因 tea 已有而略過
- 新增「日常操作(tea 對等指令)」指令表:issues/pulls/labels/milestones/releases/repos/api
- README 頂部與狀態區補範圍說明(#3)
This commit is contained in:
ceo
2026-09-10 08:13:10 +08:00
parent 14edef066b
commit 9e46d233fb
+19 -2
View File
@@ -1,12 +1,13 @@
# teai # teai
teai 是 Gitea 的命令列(CLI)輔助工具,補足官方 `tea` CLI 缺少的功能。 teai 是 Gitea 的命令列(CLI)工具,以更完整、更可靠的方式操作 Gitea。
名稱取「**te**a + **AI**」:這套工具主要為了讓 AI agent 能以更完整、更可靠的 名稱取「**te**a + **AI**」:這套工具主要為了讓 AI agent 能以更完整、更可靠的
方式操作 Gitea(查詢、回覆、審核、自動化……)。 方式操作 Gitea(查詢、回覆、審核、自動化……)。
- **語言:** Go(與 Gitea 本體一致),僅用標準庫,離線可建置 - **語言:** Go(與 Gitea 本體一致),僅用標準庫,離線可建置
- **目標站點:** `https://gitea.alterminal.com` - **目標站點:** `https://gitea.alterminal.com`
- **狀態:** 專案初始化中,功能尚未開始開發;本文的指令集為設計藍圖 - **狀態:** 專案初始化中,功能尚未開始開發;本文的指令集為設計藍圖
- **範圍(#3):** 不避開 tea 已有的功能;單一工具涵蓋完整操作
## 安裝與建置 ## 安裝與建置
@@ -23,7 +24,7 @@ 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 跟著改。 2. **規則單一來源**:「最後一則留言不是自己」等工作流判定規則以 `AGENTS.md` 為準,teai 只實作、不改義。規則要變更,先改 AGENTS.md,teai 跟著改。
3. **機器可讀優先**:預設輸出 JSON;`--output table` 僅供人工抽查。 3. **機器可讀優先**:預設輸出 JSON;`--output table` 僅供人工抽查。
4. **可直接替換原型**:`gitea.py` 的每個子命令在 teai 都有語義相同的對應命令,可交叉驗證、平滑遷移。 4. **可直接替換原型**:`gitea.py` 的每個子命令在 teai 都有語義相同的對應命令,可交叉驗證、平滑遷移。
@@ -58,6 +59,22 @@ teai [全域選項] <命令> [參數]
| `teai xrefs <owner>/<repo> <number>` | (內部函式公開化) | 解析內文/留言中的 issue/PR 引用 | | `teai xrefs <owner>/<repo> <number>` | (內部函式公開化) | 解析內文/留言中的 issue/PR 引用 |
| `teai version` | — | 版本資訊(骨架已實作) | | `teai version` | — | 版本資訊(骨架已實作) |
### 日常操作(tea 對等指令;#3 不避開 tea 已有功能)
tea 已有的日常操作 teai 也會自行實作(一致的 JSON 輸出、同一套認證與全域選項),
不要求使用者回頭併用 `tea`。介面語義以 `tea`/Gitea API 為相容參考,僅列出主要子命令,
細節(旗標、欄位)在個別實作 issue 中定義:
| 命令 | 對應 tea | 說明 |
| --- | --- | --- |
| `teai issues [list\|create\|view\|close\|comment…]` | `tea issues` | issues 管理(含 `--comments`、`--assignees`) |
| `teai pulls [list\|create\|view\|merge\|comment…]` | `tea pulls` | PR 管理(含審核者、合併) |
| `teai labels` / `teai milestones` / `teai releases` | 同名 tea 指令 | 標籤、里程碑、發佈管理 |
| `teai repos` / `teai orgs` | `tea repos`/`tea orgs` | 倉庫與組織查詢 |
| `teai api <path>` | `tea api` | 任意 API 呼叫(逃生口,`--method`、`--data`) |
> 實作順序不變:先完成 gitea.py 工作流命令的 Go 化,再依 issue 逐項補齊日常操作。
> `gitea.py` 的底線函式(`_pr_needs_author_followup`、`_resolve_xref_targets` 等)是內部實作,teai 將其放在 `internal/` 套件,不另設 CLI 命令。 > `gitea.py` 的底線函式(`_pr_needs_author_followup`、`_resolve_xref_targets` 等)是內部實作,teai 將其放在 `internal/` 套件,不另設 CLI 命令。
### `teai next` — 下一件該做的事 ### `teai next` — 下一件該做的事