From 2c851186d876e393ed744bfd5f1432161c1d36b2 Mon Sep 17 00:00:00 2001 From: ceo Date: Thu, 10 Sep 2026 08:02:16 +0800 Subject: [PATCH] =?UTF-8?q?README=EF=BC=9A=E5=8A=A0=E5=85=A5=E6=8C=87?= =?UTF-8?q?=E4=BB=A4=E9=9B=86=E8=A8=AD=E8=A8=88=EF=BC=88gitea.py=20?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E6=B5=81=E7=9A=84=20Go=20=E5=8C=96=E8=97=8D?= =?UTF-8?q?=E5=9C=96=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 179 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 398716f..2a9a264 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ teai 是 Gitea 的命令列（CLI）輔助工具，補足官方 `tea` CLI 缺少 名稱取「**te**a + **AI**」：這套工具主要為了讓 AI agent 能以更完整、更可靠的 方式操作 Gitea（查詢、回覆、審核、自動化……）。 -- **語言：** Go（與 Gitea 本體一致） +- **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置 - **目標站點：** `https://gitea.alterminal.com` -- **狀態：** 專案初始化中，功能尚未開始開發 +- **狀態：** 專案初始化中，功能尚未開始開發；本文的指令集為設計藍圖 ## 安裝與建置 @@ -16,15 +16,186 @@ teai 是 Gitea 的命令列（CLI）輔助工具，補足官方 `tea` CLI 缺少 go build -o teai ./cmd/teai ``` -## 使用方式 +## 指令設計 + +> 工作流規則的唯一來源是 [`alterminal/agents`](https://gitea.alterminal.com/alterminal/agents) 的 `AGENTS.md`； +> 現行原型為 `agents/scripts/lib/gitea.py`（Python）。teai 的指令集以它為行為基準，用 Go 重寫並納入本 CLI。 + +### 設計原則 + +1. **與 tea 互補，不重複**：`tea` 已有的功能（clone、issues、pulls、labels、milestones、release、api……）一律用 `tea`。teai 只做 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`。 + +### 全域介面 ```sh -# 目前僅提供骨架 -./teai # 顯示說明 -./teai version # 顯示版本資訊 +teai [全域選項] <命令> [參數] ``` -離線環境可直接建置：本專案目前僅使用 Go 標準庫，沒有外部相依。 +| 選項 | 說明 | +| --- | --- | +| `--url ` | Gitea 站點，預設 `https://gitea.alterminal.com` | +| `--token ` | API token；未給則依序嘗試 `TEAI_TOKEN` 環境變數、tea 登入組態 | +| `--config ` | tea 組態檔路徑，等同 `TEA_CONFIG` | +| `--output json\|table` | 輸出格式，預設 `json` | +| `--timeout ` | HTTP 請求逾時，預設 `30s` | + +### 指令總覽 + +| 命令 | 對應 gitea.py | 說明 | +| --- | --- | --- | +| `teai whoami` | `get_current_username` | 目前帳號 | +| `teai orgs` | `for_all_organizations` | 我所屬的組織 | +| `teai members [--has-work]` | `members [--has-work]` | Agents 團隊成員；`--has-work` 只列有未完成工作者 | +| `teai mine` | `mine` | 分派給我、待跟進的 issues | +| `teai pulls [--mine\|--reviewer] [--repo /]` | `pulls` 系列 | 跨倉庫 PR 跟進清單 | +| `teai next` | `next` | 下一件該做的事 | +| `teai stalled [--hours N]` | `stalled` | 全組織停滯項目掃描（管理者巡邏） | +| `teai xrefs / ` | （內部函式公開化） | 解析內文／留言中的 issue／PR 引用 | +| `teai version` | — | 版本資訊（骨架已實作） | + +> `gitea.py` 的底線函式（`_pr_needs_author_followup`、`_resolve_xref_targets` 等）是內部實作，teai 將其放在 `internal/` 套件，不另設 CLI 命令。 + +### `teai next` — 下一件該做的事 + +```sh +teai next # JSON；沒有工作 → 輸出 null，exit 0 +teai next --output table # 人類可讀 +``` + +拾取規則（與 AGENTS.md／gitea.py 完全一致，最久未更新者優先）： + +1. 自己發起、最後一則留言不是自己的 open PR（role=author） +2. 自己被指定為審核者、最後一則留言不是自己的 open PR（role=reviewer，含尚無留言） +3. 分派給自己、最後一則留言不是自己的 open issue + +輸出（與 `find_next_work()` 同欄位）： + +```json +{ + "type": "pull", + "role": "author", + "repo": "alterminal/teai", + "number": 2, + "title": "初始化專案：Go 骨架與 CLI 進入點", + "url": "https://gitea.alterminal.com/alterminal/teai/pulls/2" +} +``` + +### `teai stalled [--hours N]` — 管理者巡邏 + +```sh +teai stalled # 預設 4 小時門檻 +teai stalled --hours 6 +teai stalled --hours 48 --output table +``` + +- **判定**：open issue／PR 的最後活動距今超過 N 小時（預設 4）。 +- **父追蹤項**（內文／留言有 `#N` 子項引用）：子項的留言、state 變更與 PR 合併時間一併計入 last_activity；仍有 open 子項時 `reason=parent-tracking` 並附 `child_activity`。 +- **冷卻**：最後留言出自 `ceo` 的項目 24 小時內不再列入（已催促過），冷卻後仍停滯會再出現。 +- **輸出**：JSON 陣列，停滯由長到短；無停滯項目 → 空陣列 `[]`。 + +每筆欄位： + +```json +{ + "type": "issue", + "repo": "alterminal/agents", + "number": 30, + "title": "…", + "assignees": ["alex"], + "last_comment_by": "alex", + "last_activity_at": "2026-09-09T22:00:00+08:00", + "stalled_hours": 10.5, + "reason": "assignee-idle" +} +``` + +PR 改帶 `author` 與 `reviewers` 欄位。`reason` 取值： + +- issue：`no-assignee`、`assignee-idle`、`no-commenter`、`waiting-outside`、`parent-tracking` +- PR：`no-reviewer`、`author-idle`、`reviewer-idle`、`no-commenter` + +### `teai members [--has-work]` + +```sh +teai members # Agents 團隊全體成員（去重、排序） +teai members --has-work # 只列有未完成工作的成員（判定同 next） +``` + +### `teai pulls [filters]` + +```sh +teai pulls # 有留言且最後一則不是作者的 open PR（跨倉庫） +teai pulls --mine # 再限定：作者是我（我該跟進的 PR） +teai pulls --reviewer # 我是 requested reviewer、最後留言不是自己（含尚無留言） +teai pulls --repo alterminal/teai # 限定單一倉庫 +``` + +`--mine` 與 `--reviewer` 不可併用。 + +### `teai mine` + +```sh +teai mine # 分派給我、最後一則留言不是自己的 open issues（跨所屬組織） +``` + +### `teai orgs` / `teai whoami` + +```sh +teai orgs # 我所屬的組織 +teai whoami # 目前帳號（讀 tea 組態） +``` + +### `teai xrefs / ` — 引用解析 + +解析該 issue／PR 內文與全部留言中的 `#N`、`repo#N`、`owner/repo#N` 引用，輸出解析後的目標清單（去重）： + +```json +[ + { "owner": "alterminal", "repo": "agents", "number": 32, "source": "body" } +] +``` + +`stalled` 的父追蹤項判定內部呼叫同一套邏輯，不重複實作。 + +### 輸出與結束碼 + +所有命令支援 `--output json|table`，預設 JSON。結束碼： + +| 碼 | 意義 | +| --- | --- | +| 0 | 成功（含「沒有工作」→ 輸出 `null`／`[]`） | +| 2 | 用法錯誤（未知命令／參數） | +| 3 | API 錯誤（連線失敗、401、403、5xx） | + +### 與 gitea.py 的對應與遷移 + +| gitea.py 子命令 | teai 對應 | 語義 | +| --- | --- | --- | +| `next` | `teai next` | 相同：author-PR → reviewer-PR → issue，最久未更新優先 | +| `stalled [--hours N]` | `teai stalled [--hours N]` | 相同，含 xref 父子追蹤與冷卻 | +| `members [--has-work]` | `teai members [--has-work]` | 相同 | +| `pulls`／`pulls --mine`／`pulls --reviewer` | `teai pulls [--mine\|--reviewer]` | 相同 | +| `mine` | `teai mine` | 相同 | +| （底線函式） | `internal/` 套件 | 不設 CLI 命令；`xrefs` 為其邏輯的公開化 | + +遷移策略： + +1. 以 gitea.py 為行為基準：同帳號同時跑兩者，輸出應一致（交叉驗證）。 +2. gitea.py 保留不刪；待 AGENTS.md 改引用 teai 時才停用對應腳本。 +3. 實作順序：`whoami`／`orgs`／`members`（讀取類）→ `pulls`／`mine`／`next`（判定類）→ `stalled`（最複雜，含 xref）。 + +### 安全設計 + +- 本期命令全部唯讀；寫入類命令未來加入時須 `--yes` 明確確認。 +- token 不入輸出、不入日誌；建議用 `TEAI_TOKEN` 或 tea 組態，避免出現在命令列。 +- 清單類 API 一律帶 `limit`（Gitea 預設上限 50），避免漏抓。 +- 「有無實際產出」的判斷一律對照遠端實況（API 回傳），不信任回報文字。 ## 開發 @@ -40,7 +211,7 @@ go vet ./... # 靜態檢查 | --- | --- | | `cmd/teai/` | 程式進入點（`main`） | | `internal/cli/` | 命令列架構（flag 剖析、子命令分派、輸出） | -| `internal/` 其他子套件 | 之後依功能新增（如 `internal/gitea`、`internal/cmds/`） | +| `internal/` 其他子套件 | 依功能新增（如 `internal/gitea`、`internal/workflow`） | ### 慣例