feat: teai role
This commit is contained in:
ydc3148
@@ -6,7 +6,7 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
|
||||
|
||||
- **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置
|
||||
- **目標站點：** `https://gitea.alterminal.com`
|
||||
- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）、日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）與管理者巡邏命令（#7：stalled/xrefs）已實作
|
||||
- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/role/orgs/members/mine/pulls/next）、日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）與管理者巡邏命令（#7：stalled/xrefs）已實作
|
||||
- **範圍（#3）：** 不避開 tea 已有的功能；單一工具涵蓋完整操作
|
||||
|
||||
## 安裝與建置
|
||||
@@ -59,8 +59,6 @@ clone 建置時 Go 會把 VCS 狀態寫進 build info：位於 tag 上顯示該
|
||||
|
||||
### 登入設定（首次使用）
|
||||
|
||||
teai 與 `tea` 共用同一份組態檔；若 `tea whoami` 已可正常輸出，可跳過本節。
|
||||
|
||||
```sh
|
||||
teai login add --url https://gitea.alterminal.com
|
||||
# 未給 --token 時自 stdin 讀一行：貼上 token 後按 Enter（不會進 shell 歷史）
|
||||
@@ -68,8 +66,7 @@ teai whoami # 驗證：應輸出 {"username":"<你的帳號>"}
|
||||
```
|
||||
|
||||
- token 驗證失敗（HTTP 401）不會寫入組態，結束碼 3。
|
||||
- 組態檔：`--config`／`TEA_CONFIG` 指定，預設 `~/.config/tea/config.yml`；teai 採行級編輯，
|
||||
不會改壞 tea 也在使用的欄位，檔案權限 `0600`。
|
||||
- 組態檔：`--config`／`TEAI_CONFIG` 指定，預設 `~/.config/teai/config.yml`；檔案權限 `0600`。
|
||||
- 多站台以 `--name` 區分、`teai login default <名稱>` 切換預設；詳見下方 [`teai login`](#teai-login--管理登入) 一節。
|
||||
|
||||
## 指令設計
|
||||
@@ -83,7 +80,7 @@ teai whoami # 驗證：應輸出 {"username":"<你的帳號>"}
|
||||
2. **規則單一來源**：「最後一則留言不是自己」等工作流判定規則以 `AGENTS.md` 為準，teai 只實作、不改義。規則要變更，先改 AGENTS.md，teai 跟著改。
|
||||
3. **機器可讀優先**：預設輸出 JSON；`--output table` 僅供人工抽查。
|
||||
4. **可直接替換原型**：`gitea.py` 的每個子命令在 teai 都有語義相同的對應命令，可交叉驗證、平滑遷移。
|
||||
5. **認證沿用 tea**：讀 `tea` 的登入組態（`TEA_CONFIG` 或 `~/.config/tea/config.yml`），不另建認證體系。
|
||||
5. **自主認證組態**：登入資料寫在 teai 自己的組態（`TEAI_CONFIG` 或 `~/.config/teai/config.yml`），不依賴 tea。
|
||||
6. **安全預設**：查詢類唯讀；寫入類命令（#8 起）一律要求明確 `--yes`，未確認時不發出任何請求、不產生任何遠端變更。
|
||||
|
||||
### 日常操作（tea 對等指令；#3 不避開 tea 已有功能；#8 已實作）
|
||||
@@ -138,8 +135,8 @@ teai [全域選項] <命令> [參數]
|
||||
| 選項 | 說明 |
|
||||
| --- | --- |
|
||||
| `--url <URL>` | Gitea 站點，預設 `https://gitea.alterminal.com` |
|
||||
| `--token <TOKEN>` | API token；未給則依序嘗試 `TEAI_TOKEN` 環境變數、tea 登入組態 |
|
||||
| `--config <path>` | tea 組態檔路徑，等同 `TEA_CONFIG` |
|
||||
| `--token <TOKEN>` | API token；未給則依序嘗試 `TEAI_TOKEN` 環境變數、teai 登入組態 |
|
||||
| `--config <path>` | teai 組態檔路徑，等同 `TEAI_CONFIG` |
|
||||
| `--output json\|table` | 輸出格式，預設 `json` |
|
||||
| `--timeout <dur>` | HTTP 請求逾時，預設 `30s` |
|
||||
|
||||
@@ -147,8 +144,9 @@ teai [全域選項] <命令> [參數]
|
||||
|
||||
| 命令 | 對應 gitea.py | 說明 |
|
||||
| --- | --- | --- |
|
||||
| `teai login list\|add\|default\|remove` | — | 管理 tea 相容登入組態（見下） |
|
||||
| `teai login list\|add\|default\|remove` | — | 管理登入組態（見下） |
|
||||
| `teai whoami` | `get_current_username` | 目前帳號 |
|
||||
| `teai role` | — | 目前角色（Supervisor 團隊→supervisor，Agents 團隊→worker） |
|
||||
| `teai orgs` | `for_all_organizations` | 我所屬的組織 |
|
||||
| `teai organizations list\|create\|delete` | — | 組織管理（tea 對等日常操作；`orgs` 是工作流精簡版） |
|
||||
| `teai members [--has-work]` | `members [--has-work]` | Agents 團隊成員；`--has-work` 只列有未完成工作者 |
|
||||
@@ -189,9 +187,8 @@ teai next --output table # 人類可讀
|
||||
|
||||
### `teai login` — 管理登入
|
||||
|
||||
teai 與 tea 共用同一份組態檔（`--config`／`TEA_CONFIG`，預設 `~/.config/tea/config.yml`）。
|
||||
寫入採行級編輯：只動目標項目的行，未知欄位（`ssh_*` 等）與 `preferences` 區段逐字保留，
|
||||
不改壞 tea 也在使用的檔案；檔案權限 `0600`、暫存檔原子替換。
|
||||
登入組態由 teai 自行管理（`--config`／`TEAI_CONFIG`，預設 `~/.config/teai/config.yml`）。
|
||||
寫入採行級編輯：只動目標項目的行，未知欄位與註解逐字保留；檔案權限 `0600`、暫存檔原子替換。
|
||||
|
||||
```sh
|
||||
teai login list # 列出登入（一律不含 token）
|
||||
@@ -305,13 +302,21 @@ teai pulls --repo alterminal/teai # 限定單一倉庫
|
||||
teai mine # 分派給我、最後一則留言不是自己的 open issues（跨所屬組織）
|
||||
```
|
||||
|
||||
### `teai orgs` / `teai whoami`
|
||||
### `teai orgs` / `teai whoami` / `teai role`
|
||||
|
||||
```sh
|
||||
teai orgs # 我所屬的組織
|
||||
teai whoami # 目前帳號（讀 tea 組態）
|
||||
teai whoami # 目前帳號
|
||||
teai role # 目前角色
|
||||
```
|
||||
|
||||
角色由所屬組織的團隊決定：
|
||||
|
||||
- 在 **Supervisor** 團隊 → `{"role":"supervisor"}`
|
||||
- 在 **Agents** 團隊 → `{"role":"worker"}`
|
||||
- 同時屬於兩者時以 supervisor 為準
|
||||
- 兩者都不屬於 → 輸出 `null`，exit 0
|
||||
|
||||
### `teai xrefs <owner>/<repo> <number>` — 引用解析
|
||||
|
||||
解析該 issue／PR 內文與全部留言中的 `#N`、`repo#N`、`owner/repo#N` 引用，輸出解析後的目標清單（去重）：
|
||||
@@ -330,7 +335,7 @@ teai whoami # 目前帳號（讀 tea 組態）
|
||||
|
||||
| 碼 | 意義 |
|
||||
| --- | --- |
|
||||
| 0 | 成功（含「沒有結果」→ 清單類命令輸出 `[]`、`next` 輸出 `null`；#37 判決） |
|
||||
| 0 | 成功（含「沒有結果」→ 清單類命令輸出 `[]`、`next`／`role` 輸出 `null`；#37 判決） |
|
||||
| 2 | 用法錯誤（未知命令／參數） |
|
||||
| 3 | API 錯誤（連線失敗、401、403、5xx） |
|
||||
|
||||
@@ -355,6 +360,7 @@ teai whoami # 目前帳號（讀 tea 組態）
|
||||
「沒有未完成的工作」。**判決 #37：維持 teai 現行 JSON 一致性（方向 2）**——消費端
|
||||
（agents 倉庫巡邏提示與觸發腳本）應以「輸出 `[]`／`null` 且 exit 0」為「沒有」判據，
|
||||
不得以「無輸出」判斷；`members [--has-work]` 維持逐行帳號、空時無輸出（兩者一致，不受影響）。
|
||||
`teai role` 不在 Supervisor／Agents 時同樣輸出 `null`（exit 0）。
|
||||
- **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件
|
||||
（`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位
|
||||
（`mine`：repo／number／title／url；`pulls`：number／title／state／author／
|
||||
@@ -374,7 +380,7 @@ teai whoami # 目前帳號（讀 tea 組態）
|
||||
### 安全設計
|
||||
|
||||
- 本期命令全部唯讀；寫入類命令未來加入時須 `--yes` 明確確認。
|
||||
- token 不入輸出、不入日誌；建議用 `TEAI_TOKEN` 或 tea 組態，避免出現在命令列。
|
||||
- token 不入輸出、不入日誌；建議用 `TEAI_TOKEN` 或 teai 組態，避免出現在命令列。
|
||||
- 清單類 API 一律帶 `limit`（Gitea 預設上限 50），避免漏抓。
|
||||
- 「有無實際產出」的判斷一律對照遠端實況（API 回傳），不信任回報文字。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user