Merge pull request 'docs+test：空清單輸出判決定案（維持 []／null，補 stalled 空輸出測試）（#37）' (#39 ) from fix/issue37-empty-output-docs into main

docs+test：空輸出判決 #37——維持 []／null、補 stalled 空輸出測試
Merge pull request 'internal/workflow：directLastActivity 排除跨 issue 引用事件（#34）' (#36 ) from fix/issue34-direct-last-activity into main
2026-09-12 23:56:52 +08:00 · 2026-09-12 23:43:29 +08:00 · 2026-09-12 15:24:23 +08:00 · 2026-09-12 15:21:21 +08:00 · 2026-09-12 15:10:31 +08:00 · 2026-09-11 11:32:53 +08:00
37 changed files with 8941 additions and 250 deletions
@@ -1,21 +1,57 @@
 # 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）、日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）與管理者巡邏命令（#7：stalled/xrefs）已實作
+- **範圍（#3）：** 不避開 tea 已有的功能；單一工具涵蓋完整操作

 ## 安裝與建置

-需要 Go 1.26 以上。
+### 需求
+
+- **Go 1.26 以上**（`go version` 確認；本倉庫僅用標準庫，離線可建置）
+- **git**
+- Gitea 帳號的 **API token**（設定階段使用；在 Gitea「設定 → 應用程式」產生）
+
+### 從原始碼建置

 ```sh
+git clone https://gitea.alterminal.com/alterminal/teai.git
+cd teai
 go build -o teai ./cmd/teai
+install -Dm755 teai ~/.local/bin/teai   # 或複製到任何 PATH 內目錄
+teai version                             # 驗證：teai version 0.1.0-dev
 ```

+也可以直接裝進 `GOBIN`（預設 `~/go/bin`；該目錄已在 PATH 時最省事）：
+
+```sh
+go install ./cmd/teai
+```
+
+> **注意：** `go install gitea.alterminal.com/alterminal/teai/cmd/teai@latest` 目前**不可用**——
+> module 尚未發佈任何 tag，`@latest` 會解析到任意中繼 commit（且 #21 修復前 main 建置失敗）。
+> 請在 clone 目錄內以版本控制的方式建置；發佈 tag 後再提供 `teai@<version>` 安裝路徑。
+
+### 登入設定（首次使用）
+
+teai 與 `tea` 共用同一份組態檔；若 `tea whoami` 已可正常輸出，可跳過本節。
+
+```sh
+teai login add --url https://gitea.alterminal.com
+# 未給 --token 時自 stdin 讀一行：貼上 token 後按 Enter（不會進 shell 歷史）
+teai whoami    # 驗證：應輸出 {"username":"<你的帳號>"}
+```
+
+- token 驗證失敗（HTTP 401）不會寫入組態，結束碼 3。
+- 組態檔：`--config`／`TEA_CONFIG` 指定，預設 `~/.config/tea/config.yml`；teai 採行級編輯，
+  不會改壞 tea 也在使用的欄位，檔案權限 `0600`。
+- 多站台以 `--name` 區分、`teai login default <名稱>` 切換預設；詳見下方 [`teai login`](#teai-login--管理登入) 一節。
+
 ## 指令設計

 > 工作流規則的唯一來源是 [`alterminal/agents`](https://gitea.alterminal.com/alterminal/agents) 的 `AGENTS.md`；
@@ -23,12 +59,45 @@ 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                          # 跨倉庫 open 里程碑總覽（gitea.py milestones 對應；期限近者在前）
+teai milestones --repo <owner>/<repo>    # 同 milestones list（單倉庫，維持既有語義）
+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 +117,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 +156,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
@@ -120,6 +209,47 @@ 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 milestones` — 跨倉庫里程碑總覽
+
+```sh
+teai milestones              # 各倉庫 open 里程碑概況（跨所屬組織；期限近者在前）
+teai milestones --output table
+```
+
+管理者巡邏用（`gitea.py milestones` 對應，agents AGENTS.md 10.1）。帶 `--repo` 時
+維持現行單倉庫 `list` 語義（`teai milestones --repo a/b` ＝ `teai milestones list --repo a/b`）。
+
+每筆欄位（鍵集鍵序與 `gitea.py` 全等，實測位元組一致）：
+
+```json
+{
+  "repo": "alterminal/test",
+  "id": 6,
+  "title": "xcheck31-ms-overdue",
+  "url": "https://gitea.alterminal.com/alterminal/test/milestone/6",
+  "open_issues": 2,
+  "closed_issues": 0,
+  "due_on": "2026-09-08T08:00:00+08:00",
+  "due_hours": 61.3,
+  "overdue": true,
+  "unassigned": [
+    {
+      "type": "issue",
+      "number": 14,
+      "title": "…",
+      "url": "https://gitea.alterminal.com/alterminal/test/issues/14"
+    }
+  ],
+  "updated_at": "2026-09-10T21:17:37+08:00"
+}
+```
+
+- **排序**：`due_on` 近者在前；無期限者最後（`gitea.py` 的 `(due_on is None, due_on)` 鍵）。
+- **`overdue`／`due_hours`**：期限已過為 `true`（`due_hours` 正數）；無期限 → `null`。
+- **`unassigned`**：該里程碑 open 條目（issue 與 PR）中無 assignee 者的摘要；PR 條目另帶 `author`。
+- **`updated_at`**：里程碑本身與其 open 條目 `updated_at` 的最大值（判斷活躍度用）。
+- 空輸出 → `[]`（`gitea.py` 無輸出；依 #26 慣例差異）。
+
 ### `teai members [--has-work]`

 ```sh
@@ -169,7 +299,7 @@ teai whoami               # 目前帳號（讀 tea 組態）

 | 碼 | 意義 |
 | --- | --- |
-| 0 | 成功（含「沒有工作」→ 輸出 `null`／`[]`） |
+| 0 | 成功（含「沒有結果」→ 清單類命令輸出 `[]`、`next` 輸出 `null`；#37 判決） |
 | 2 | 用法錯誤（未知命令／參數） |
 | 3 | API 錯誤（連線失敗、401、403、5xx） |

@@ -179,11 +309,31 @@ teai whoami               # 目前帳號（讀 tea 組態）
 | --- | --- | --- |
 | `next` | `teai next` | 相同：author-PR → reviewer-PR → issue，最久未更新優先 |
 | `stalled [--hours N]` | `teai stalled [--hours N]` | 相同，含 xref 父子追蹤與冷卻 |
+| `milestones` | `teai milestones` | 相同：跨倉庫 open 里程碑總覽，期限近者在前（#31） |
 | `members [--has-work]` | `teai members [--has-work]` | 相同 |
 | `pulls`／`pulls --mine`／`pulls --reviewer` | `teai pulls [--mine\|--reviewer]` | 相同 |
 | `mine` | `teai mine` | 相同 |
 | （底線函式） | `internal/` 套件 | 不設 CLI 命令；`xrefs` 為其邏輯的公開化 |

+已知輸出差異（刻意保留，機器可讀優先）：
+
+- **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令
+  （`mine`／`pulls`／`stalled`／`milestones` 總覽）空清單一律輸出 `[]`（exit 0）。對 JSON
+  消費者來說 `[]` 比「無輸出」更明確（可區分「沒有結果」與「查詢失敗無輸出」），交叉驗證時
+  以此差異為準。`next` 兩者語義相同：無工作時 teai 輸出 `null`（exit 0）、`gitea.py` 印
+  「沒有未完成的工作」。**判決 #37：維持 teai 現行 JSON 一致性（方向 2）**——消費端
+  （agents 倉庫巡邏提示與觸發腳本）應以「輸出 `[]`／`null` 且 exit 0」為「沒有」判據，
+  不得以「無輸出」判斷；`members [--has-work]` 維持逐行帳號、空時無輸出（兩者一致，不受影響）。
+- **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件
+  （`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位
+  （`mine`：repo／number／title／url；`pulls`：number／title／state／author／
+  head／base／updated_at…依命令定義）。交叉驗證比對**項目集合**（列出哪些
+  issue／PR）與判定語義，不逐欄位比對；`next`／`stalled`／`milestones` 總覽
+  兩者為策展欄位且鍵集鍵序全等，可逐欄位比對（#31 實測位元組一致）。判定 #26（維持摘要、文件化差異）。
+- **全域選項位置**：teai 的全域選項（`--output` 等）可出現在命令之前或之後，
+  且可與命令旗標交錯（`teai members --has-work --output table`）；
+  gitea.py 的旗標剖析較寬鬆，兩者命令列介面以此行為對齊。
+
 遷移策略：

 1. 以 gitea.py 為行為基準：同帳號同時跑兩者，輸出應一致（交叉驗證）。
@@ -132,8 +132,8 @@ func (s *apiSource) MyOrganizations() ([]string, error) {
 	return names, nil
 }

-func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repository, error) {
-	var repos []workflow.Repository
+func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+	var repos []workflow.Repo
 	if err := s.listAll("orgs/"+org+"/repos", nil, &repos); err != nil {
 		return nil, err
 	}
@@ -157,7 +157,7 @@ func (s *apiSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error
 	return pulls, nil
 }

-func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Comment, error) {
+func (s *apiSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
 	var comments []workflow.Comment
 	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/comments", owner, repo, number), nil, &comments); err != nil {
 		return nil, err
@@ -165,7 +165,15 @@ func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Co
 	return comments, nil
 }

-func (s *apiSource) TryGetIssue(owner, repo string, number int) (workflow.Issue, bool, error) {
+func (s *apiSource) IssueTimeline(owner, repo string, number int64) ([]workflow.TimelineEvent, error) {
+	var events []workflow.TimelineEvent
+	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/timeline", owner, repo, number), nil, &events); err != nil {
+		return nil, err
+	}
+	return events, nil
+}
+
+func (s *apiSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
 	var issue workflow.Issue
 	body, code, err := s.get(fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, number), nil)
 	if err != nil {
@@ -1,14 +1,25 @@
-// 套件 cli 提供 teai 的命令列架構：引數剖析、子命令分派與輸出。
+// 套件 cli 提供 teai 的命令列架構：全域選項剖析、子命令分派與輸出。
 //
 // 設計目標是讓之後新增子命令時只需註冊一個 command 結構，
 // 不需要改動分派邏輯；也讓核心功能可以被測試（Run 接受 io.Writer）。
+//
+// 結束碼（見 README「輸出與結束碼」）：
+//
+//	0 成功（含「沒有工作」→ null／[]）
+//	2 用法錯誤（未知命令／參數）
+//	3 API 錯誤（連線失敗、401、403、5xx）
 package cli

 import (
+	"errors"
 	"flag"
 	"fmt"
 	"io"
 	"sort"
+	"strings"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
 )

 // Version 是目前開發中的版本號。採用語意化版本；正式發佈前以 0 開頭。
@@ -17,13 +28,25 @@ var Version = "0.1.0-dev"
 // ExitCode 是 Run 回傳的行程結束碼。
 type ExitCode int

-// 常見的結束碼定義。0 表示成功，其餘對應常見的命令列錯誤情境。
+// 結束碼定義，對應 README「輸出與結束碼」表格。
 const (
-	ExitOK       ExitCode = iota // 成功
-	ExitUsage                    // 引數或子命令錯誤
-	ExitInternal                 // 內部錯誤（不該發生）
+	ExitOK    ExitCode = 0 // 成功
+	ExitUsage ExitCode = 2 // 用法錯誤（未知命令／參數）
+	ExitAPI   ExitCode = 3 // API 錯誤（連線失敗、401、403、5xx）
+
+	// ExitInternal 僅供「不該發生」的內部錯誤；不在 README 保證範圍。
+	ExitInternal ExitCode = 1
 )

+// ErrUsage 表示命令用法錯誤（缺參數、參數格式不對），對應 ExitUsage。
+type ErrUsage struct {
+	// Msg 是給使用者看的說明。
+	Msg string
+}
+
+// Error 實作 error 介面。
+func (e *ErrUsage) Error() string { return e.Msg }
+
 // command 定義一個子命令：名稱、一行說明與實作。
 type command struct {
 	name  string
@@ -31,16 +54,46 @@ type command struct {
 	run   func(env *Env, args []string) error
 }

-// Env 聚集一次執行所需的輸出目標，便於測試時替換。
+// Globals 是一次執行的全域選項（README「全域介面」）。
+type Globals struct {
+	// URL 是 Gitea 站點網址。
+	URL string
+	// Token 來自 --token 旗標；空字串表示未提供（依序退回環境變數與 tea 組態）。
+	Token string
+	// ConfigPath 是 tea 組態路徑（--config，等同 TEA_CONFIG）。
+	ConfigPath string
+	// Output 是輸出格式。
+	Output gitea.Format
+	// Timeout 是 HTTP 逾時。
+	Timeout time.Duration
+}
+
+// defaultGlobals 回傳預設全域選項。
+func defaultGlobals() Globals {
+	return Globals{
+		URL:     "https://gitea.alterminal.com",
+		Output:  gitea.FormatJSON,
+		Timeout: gitea.DefaultTimeout,
+	}
+}
+
+// Env 聚集一次執行所需的輸出目標與全域選項，便於測試時替換。
 type Env struct {
 	// Out 是一般輸出（命令結果）。
 	Out io.Writer
 	// Err 是診斷輸出（錯誤、警告）。
 	Err io.Writer
+	// Globals 是剖析後的全域選項。
+	Globals Globals
 }

 // commands 是已註冊的子命令表。新增功能時在這裡註冊即可。
 var commands = map[string]*command{
+	"login": {
+		name:  "login",
+		usage: "管理登入（list/add/default/remove）",
+		run:   runLogin,
+	},
 	"version": {
 		name:  "version",
 		usage: "顯示版本資訊",
@@ -50,57 +103,355 @@ var commands = map[string]*command{

 // Run 剖析引數並分派到對應子命令，回傳行程結束碼。
 //
-// 無引數或要求說明（-h/--help）時印出用法；未知子命令回 ExitUsage。
+// 引數結構：teai [全域選項] <命令> [命令參數]。全域選項須在命令之前；
+// 無引數或要求說明（-h/--help）時印出用法；未知命令或無效選項回 ExitUsage。
 func Run(stdout, stderr io.Writer, args []string) int {
-	env := &Env{Out: stdout, Err: stderr}
+	env := &Env{Out: stdout, Err: stderr, Globals: defaultGlobals()}

 	if len(args) == 0 {
 		printUsage(env.Out)
 		return int(ExitOK)
 	}

-	switch args[0] {
+	rest, err := parseGlobals(&env.Globals, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "teai: %v\n\n", err)
+		printUsage(stderr)
+		return int(ExitUsage)
+	}
+	if len(rest) == 0 {
+		printUsage(env.Out)
+		return int(ExitOK)
+	}
+
+	switch rest[0] {
 	case "-h", "--help", "help":
 		printUsage(env.Out)
 		return int(ExitOK)
 	case "-v", "--version", "version":
-		return dispatch(env, "version", args[1:])
+		return dispatch(env, "version", rest[1:])
 	default:
-		name := args[0]
+		name := rest[0]
 		if _, ok := commands[name]; !ok {
 			fmt.Fprintf(stderr, "teai: unknown command %q\n\n", name)
 			printUsage(stderr)
 			return int(ExitUsage)
 		}
-		return dispatch(env, name, args[1:])
+		return dispatch(env, name, rest[1:])
 	}
 }

+// globalFlags 列出全域選項的長名稱與是否需要值。
+var globalFlags = map[string]bool{
+	"--url":     true,
+	"--token":   true,
+	"--config":  true,
+	"--output":  true,
+	"--timeout": true,
+}
+
+// reservedFlags 回傳 dispatch 不得搶走的旗標名稱（含 -- 前綴）：這些
+// 旗標屬於目前命令（或其子命令），即使與全域選項同名也必須原樣留給
+// 命令剖析。目前唯一與全域同名的是 login add 的 --url／--token
+// （README「teai login add --url … --token …」）。其餘命令的旗標
+// （--repo、--has-work、--mine……）本來就不在 globalFlags 內，不受影響。
+func reservedFlags(name string) map[string]bool {
+	reserved := make(map[string]bool)
+	for _, f := range commandReservedFlags[name] {
+		reserved[f] = true
+	}
+	return reserved
+}
+
+// commandReservedFlags 登記每個命令「與全域選項同名」的自有旗標。
+// 命令旗標優先留給命令；新命令有同姓旗標時在這裡登記（#18）。
+var commandReservedFlags = map[string][]string{
+	"login": {"--url", "--token"},
+}
+
+// extractGlobals 從 args 中「抽取」全域選項（可出現在命令之後、與命令
+// 旗標交錯），其餘引數依原順序保留給子命令剖析。未知的選項一律留給
+// 子命令處理（可能是命令旗標，如 --has-work），不在這裡報錯。
+// reserved 是目前命令保留的旗標名稱（含 -- 前綴，見 reservedFlags）：
+// 列於其中的選項即使與全域同名也原樣留給命令，命令旗標優先（#18）。
+func extractGlobals(g *Globals, args []string, reserved map[string]bool) ([]string, error) {
+	rest := make([]string, 0, len(args))
+	applyGlobal := func(name, value string) error {
+		switch name {
+		case "--url":
+			if strings.TrimSpace(value) == "" {
+				return &ErrUsage{Msg: "--url must not be empty"}
+			}
+			g.URL = value
+		case "--token":
+			g.Token = value
+		case "--config":
+			if strings.TrimSpace(value) == "" {
+				return &ErrUsage{Msg: "--config must not be empty"}
+			}
+			g.ConfigPath = value
+		case "--output":
+			f, err := gitea.ParseFormat(value)
+			if err != nil {
+				return &ErrUsage{Msg: err.Error()}
+			}
+			g.Output = f
+		case "--timeout":
+			d, err := time.ParseDuration(value)
+			if err != nil || d <= 0 {
+				return &ErrUsage{Msg: fmt.Sprintf("invalid --timeout %q (want e.g. 30s)", value)}
+			}
+			g.Timeout = d
+		}
+		return nil
+	}
+	i := 0
+	for i < len(args) {
+		arg := args[i]
+		if arg == "--" {
+			rest = append(rest, args[i+1:]...)
+			return rest, nil
+		}
+		if !strings.HasPrefix(arg, "--") {
+			rest = append(rest, arg)
+			i++
+			continue
+		}
+		name, inline, hasInline := strings.Cut(arg, "=")
+		if reserved[name] {
+			// 命令保留旗標：即使與全域選項同名也留給命令剖析（#18）。
+			rest = append(rest, arg)
+			if !hasInline && i+1 < len(args) {
+				// 旗標值跟在下一個引數；一併保留，不當成全域值。
+				rest = append(rest, args[i+1])
+				i++
+			}
+			i++
+			continue
+		}
+		_, ok := globalFlags[name]
+		if !ok {
+			// 不是全域選項：留給子命令（可能是 --has-work 這類命令旗標）。
+			rest = append(rest, arg)
+			i++
+			continue
+		}
+		var value string
+		if hasInline {
+			value = inline
+		} else {
+			if i+1 >= len(args) {
+				return nil, &ErrUsage{Msg: fmt.Sprintf("global option %q requires a value", name)}
+			}
+			i++
+			value = args[i]
+		}
+		if err := applyGlobal(name, value); err != nil {
+			return nil, err
+		}
+		i++
+	}
+	return rest, nil
+}
+
+// parseGlobals 從 args 前端取走全域選項，回傳剩餘引數（命令與其參數）。
+// 遇到第一個非選項引數即停；不認得的選項或缺少值都回 ErrUsage。
+func parseGlobals(g *Globals, args []string) ([]string, error) {
+	i := 0
+	for i < len(args) {
+		arg := args[i]
+		if arg == "--" {
+			return args[i+1:], nil
+		}
+		if !strings.HasPrefix(arg, "-") || arg == "-" {
+			return args[i:], nil
+		}
+		name, inline, hasInline := strings.Cut(arg, "=")
+		// -h/--help/-v/--version 不是全域選項；交回 Run 的分派處理。
+		switch name {
+		case "-h", "--help", "-v", "--version":
+			return args[i:], nil
+		}
+		need, ok := globalFlags[name]
+		if !ok {
+			return nil, &ErrUsage{Msg: fmt.Sprintf("unknown global option %q", name)}
+		}
+		var value string
+		if hasInline {
+			value = inline
+		} else {
+			if !need {
+				// 目前所有全域選項都需要值；保留機制給未來的布林選項。
+				value = ""
+			}
+			if i+1 >= len(args) {
+				return nil, &ErrUsage{Msg: fmt.Sprintf("global option %q requires a value", name)}
+			}
+			i++
+			value = args[i]
+		}
+		switch name {
+		case "--url":
+			if strings.TrimSpace(value) == "" {
+				return nil, &ErrUsage{Msg: "--url must not be empty"}
+			}
+			g.URL = value
+		case "--token":
+			g.Token = value
+		case "--config":
+			if strings.TrimSpace(value) == "" {
+				return nil, &ErrUsage{Msg: "--config must not be empty"}
+			}
+			g.ConfigPath = value
+		case "--output":
+			f, err := gitea.ParseFormat(value)
+			if err != nil {
+				return nil, &ErrUsage{Msg: err.Error()}
+			}
+			g.Output = f
+		case "--timeout":
+			d, err := time.ParseDuration(value)
+			if err != nil || d <= 0 {
+				return nil, &ErrUsage{Msg: fmt.Sprintf("invalid --timeout %q (want e.g. 30s)", value)}
+			}
+			g.Timeout = d
+		}
+		i++
+	}
+	return nil, nil
+}
+
 // dispatch 執行已註冊的子命令，把錯誤轉成結束碼並輸出。
+// 旗標剖析交由各命令自行處理（不同命令有不同旗標，如 pulls --mine）；
+// 全域選項允許出現在命令之後（README 範例：teai next --output table），
+// dispatch 先從 args 剝離全域選項併入 Globals，其餘（含命令自己的旗標，
+// 如 --has-work）原樣交給命令，不會誤判為未知全域選項。與全域選項
+// 同名的命令旗標（登記於 commandReservedFlags）優先留給命令（#18）。
 func dispatch(env *Env, name string, args []string) int {
 	cmd := commands[name]
-	fs := flag.NewFlagSet("teai "+name, flag.ContinueOnError)
-	fs.SetOutput(env.Err)
-	if err := fs.Parse(args); err != nil {
+	g := env.Globals
+	rest, err := extractGlobals(&g, args, reservedFlags(name))
+	if err != nil {
+		fmt.Fprintf(env.Err, "teai: %v\n\n", err)
+		printUsage(env.Err)
 		return int(ExitUsage)
 	}
-	if err := cmd.run(env, fs.Args()); err != nil {
+	env.Globals = g
+	if err := cmd.run(env, rest); err != nil {
 		fmt.Fprintf(env.Err, "teai %s: %v\n", name, err)
-		return int(ExitInternal)
+		return int(exitCodeFor(err))
 	}
 	return int(ExitOK)
 }

-// runVersion 輸出版本資訊。
+// errHelp 表示使用者要求該命令的說明（-h/--help）；FlagSet 已自行印出
+// 用法，靜默成功結束即可。
+var errHelp = errors.New("help requested")
+
+// parseFlags 剖析命令旗標，允許旗標與位置參數交錯（#25）：Go 標準
+// flag 在遇到第一個非旗標參數後即停止剖析，其後的旗標會被當成位置
+// 參數。做法：先掃描 args 把「旗標（含其值）」與「位置參數」分離成
+// 兩串，再以旗標串呼叫 fs.Parse，最後以第二次 Parse 把位置參數設回
+// fs.Args（Parse 遇到 "--" 即停止並收下其餘引數，第一次剖析已設好
+// 的旗標值不受影響）。
+// -h/--help 回 errHelp（由 exitCodeFor 視為成功），其他剖析錯誤回 ErrUsage。
+func parseFlags(fs *flag.FlagSet, args []string) error {
+	var flags, positional []string
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--" {
+			// "--" 之後全部是位置參數（不再剖析旗標；同標準 flag）。
+			positional = append(positional, args[i+1:]...)
+			break
+		}
+		if len(arg) < 2 || arg[0] != '-' {
+			positional = append(positional, arg)
+			continue
+		}
+		flags = append(flags, arg)
+		// 判斷旗標是否需要「下一個引數」當值（布林旗標與 inline
+		// 形式 --name=value 不需要）。未知或格式錯誤的旗標不消費
+		// 下一個引數，交給 fs.Parse 產生標準錯誤訊息。
+		numMinuses := 1
+		if arg[1] == '-' {
+			numMinuses = 2
+		}
+		name := arg[numMinuses:]
+		if name == "" || name[0] == '-' || name[0] == '=' {
+			continue // ---x／--=…：bad flag syntax，由 fs.Parse 報錯
+		}
+		flagName, _, hasInline := strings.Cut(name, "=")
+		if !hasInline {
+			if fl := fs.Lookup(flagName); fl != nil && !isBoolFlag(fl) && i+1 < len(args) {
+				i++
+				flags = append(flags, args[i])
+			}
+		}
+	}
+	if err := fs.Parse(flags); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return errHelp
+		}
+		return &ErrUsage{Msg: err.Error()}
+	}
+	if len(positional) > 0 {
+		if err := fs.Parse(append([]string{"--"}, positional...)); err != nil {
+			if errors.Is(err, flag.ErrHelp) {
+				return errHelp
+			}
+			return &ErrUsage{Msg: err.Error()}
+		}
+	}
+	return nil
+}
+
+// isBoolFlag 回傳旗標是否為布林型（不需要值；同 flag 包內部判斷）。
+func isBoolFlag(fl *flag.Flag) bool {
+	bf, ok := fl.Value.(interface{ IsBoolFlag() bool })
+	return ok && bf.IsBoolFlag()
+}
+
+// exitCodeFor 把命令錯誤映射到結束碼：用法錯誤 → 2，API 錯誤 → 3，
+// 其他（內部）→ 1。errHelp（命令的 -h/--help）視為成功（#25：
+// 與 parseFlags 註解宣稱一致，FlagSet 已印出用法說明）。
+func exitCodeFor(err error) ExitCode {
+	if err == nil {
+		return ExitOK
+	}
+	if err == errHelp {
+		return ExitOK
+	}
+	var usage *ErrUsage
+	if errors.As(err, &usage) {
+		return ExitUsage
+	}
+	var api *gitea.ErrAPI
+	if errors.As(err, &api) {
+		return ExitAPI
+	}
+	return ExitInternal
+}
+
+// runVersion 輸出版本資訊；不接受任何參數。
 func runVersion(env *Env, args []string) error {
+	if len(args) > 0 {
+		return &ErrUsage{Msg: "version 不接受參數"}
+	}
 	fmt.Fprintf(env.Out, "teai version %s\n", Version)
 	return nil
 }

-// printUsage 印出用法與已註冊的子命令清單（依名稱排序）。
+// printUsage 印出用法、全域選項與已註冊的子命令清單（依名稱排序）。
 func printUsage(w io.Writer) {
 	fmt.Fprintf(w, "teai — Gitea CLI 輔助工具（tea + AI）\n\n")
-	fmt.Fprintf(w, "用法：\n  teai [命令] [參數]\n\n命令：\n")
+	fmt.Fprintf(w, "用法：\n  teai [全域選項] <命令> [參數]\n\n")
+	fmt.Fprintf(w, "全域選項：\n")
+	fmt.Fprintf(w, "  --url <URL>        Gitea 站點（預設 https://gitea.alterminal.com）\n")
+	fmt.Fprintf(w, "  --token <TOKEN>    API token；未給則依序嘗試 TEAI_TOKEN、tea 登入組態\n")
+	fmt.Fprintf(w, "  --config <path>    tea 組態檔路徑，等同 TEA_CONFIG\n")
+	fmt.Fprintf(w, "  --output <format>  輸出格式 json|table（預設 json）\n")
+	fmt.Fprintf(w, "  --timeout <dur>    HTTP 逾時（預設 30s）\n\n")
+	fmt.Fprintf(w, "命令：\n")
 	names := make([]string, 0, len(commands))
 	for name := range commands {
 		names = append(names, name)
@@ -51,8 +51,10 @@ func TestRunVersion(t *testing.T) {

 func TestRunUnknownCommand(t *testing.T) {
 	_, stderr, code := run("no-such-command")
-	if code != int(ExitUsage) {
-		t.Errorf("未知命令應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	// 直接對照 README「輸出與結束碼」的數值（用法錯誤＝2），
+	// 不以常數互比，避免常數與規格再次脫鉤（#10）。
+	if code != 2 {
+		t.Errorf("未知命令應回 2（README 用法錯誤），得到 %d", code)
 	}
 	if !strings.Contains(stderr, "unknown command") {
 		t.Errorf("未知命令應在 stderr 說明，得到：%q", stderr)
@@ -0,0 +1,893 @@
+// dailyops_commands.go — 日常操作命令的 CLI 接線（#8）：issues、pulls、
+// labels、milestones、releases、repos、api（tea 對等指令）。
+//
+// 規則：
+//   - 寫入類命令（create／close／comment／merge…）一律要求 --yes，
+//     未帶 --yes 時不產生任何遠端變更（exit 2，用法錯誤）。
+//   - `teai pulls` 相容 #6 的工作流用法（無子命令＝工作流清單 --mine/--reviewer）；
+//     有子命令（list/create/view/merge/comment）時走日常操作。
+//   - 輸出走 internal/gitea 的 Printer（--output json|table）。
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gitea.alterminal.com/alterminal/teai/internal/dailyops"
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+func init() {
+	register := func(c *command) { commands[c.name] = c }
+	register(&command{name: "issues", usage: "issues 管理（list/view/create/close/comment）", run: runIssues})
+	register(&command{name: "pulls", usage: "PR 管理（list/view/create/merge/comment；無子命令＝工作流清單）", run: runPullsDaily})
+	register(&command{name: "labels", usage: "標籤管理（list/create）", run: runLabels})
+	register(&command{name: "milestones", usage: "里程碑（跨倉庫總覽；list/create 管理單倉庫）", run: runMilestones})
+	register(&command{name: "releases", usage: "發佈清單（list）", run: runReleases})
+	register(&command{name: "repos", usage: "倉庫查詢（list）", run: runRepos})
+	register(&command{name: "api", usage: "任意 API 呼叫（--method/--data；寫入動詞需 --yes）", run: runAPIDirect})
+}
+
+// requireYes 檢查寫入閘門：未帶 --yes 回 ErrUsage（exit 2），不觸發任何請求。
+func requireYes(yes bool, what string) error {
+	if !yes {
+		return &ErrUsage{Msg: what + " 是寫入操作，需 --yes 明確確認（未確認，未產生任何遠端變更）"}
+	}
+	return nil
+}
+
+// splitRepoFlag 把 --repo owner/repo 拆成兩段；空值回 ("", "", nil)。
+func splitRepoFlag(v string) (string, string, error) {
+	if v == "" {
+		return "", "", nil
+	}
+	parts := strings.SplitN(v, "/", 2)
+	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", &ErrUsage{Msg: errNoRepoFlag.Error()}
+	}
+	return parts[0], parts[1], nil
+}
+
+// newOpsClient 依全域選項建立 dailyops 用戶端。
+func newOpsClient(env *Env) (*dailyops.Ops, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &dailyops.Ops{Client: client}, nil
+}
+
+// parseNumber 把位置參數解析為 issue／PR 編號。
+func parseNumber(s string) (int64, error) {
+	n, err := strconv.ParseInt(s, 10, 64)
+	if err != nil || n <= 0 {
+		return 0, &ErrUsage{Msg: fmt.Sprintf("無效的編號 %q", s)}
+	}
+	return n, nil
+}
+
+// joinOrEmpty 把清單型欄位格式化為逗號分隔（table 用）。
+func joinOrEmpty(v any) string {
+	switch x := v.(type) {
+	case string:
+		return x
+	case []string:
+		return strings.Join(x, ",")
+	default:
+		return fmt.Sprint(x)
+	}
+}
+
+// issueRowsFields 是 issues 清單的欄位定義（與值順序對應）。
+func issueListFields() []gitea.Field {
+	return []gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"},
+		{Name: "author"}, {Name: "assignees", ValueFmt: joinOrEmpty}, {Name: "updated_at"},
+	}
+}
+
+// ---- issues ----
+
+// runIssues：teai issues [list|view|create|close|comment] …
+func runIssues(env *Env, args []string) error {
+	if len(args) == 0 {
+		return &ErrUsage{Msg: "issues 需要子命令：list | view | create | close | comment"}
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runIssuesList(env, rest)
+	case "view":
+		return runIssuesView(env, rest)
+	case "create":
+		return runIssuesCreate(env, rest)
+	case "close":
+		return runIssuesClose(env, rest)
+	case "comment":
+		return runComment(env, rest, false)
+	default:
+		return &ErrUsage{Msg: fmt.Sprintf("issues 未知子命令 %q（可用：list | view | create | close | comment）", sub)}
+	}
+}
+
+// runIssuesList：teai issues list --repo owner/repo [--state open|closed|all]
+func runIssuesList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai issues list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	state := fs.String("state", "open", "狀態：open|closed|all")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "issues list 不接受位置參數"}
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "issues list 需要 --repo owner/repo"}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	issues, err := ops.ListIssues(context.Background(), owner, name, *state)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(issues))
+	for i := range issues {
+		it := &issues[i]
+		rows = append(rows, gitea.Values{
+			it.Number, it.Title, it.State, it.Author(),
+			it.AssigneeNames(), it.UpdatedAt,
+		})
+	}
+	return p.PrintList(issueListFields(), rows)
+}
+
+// runIssuesView：teai issues view --repo owner/repo <number> [--comments]
+func runIssuesView(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai issues view", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	withComments := fs.Bool("comments", false, "連留言一起輸出")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "issues view 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "issues view 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	it, err := ops.GetIssue(context.Background(), owner, name, num)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	fields := []gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"},
+		{Name: "author"}, {Name: "assignees", ValueFmt: joinOrEmpty},
+		{Name: "labels", ValueFmt: joinOrEmpty}, {Name: "body"},
+		{Name: "url"}, {Name: "updated_at"},
+	}
+	row := gitea.Values{
+		it.Number, it.Title, it.State, it.Author(),
+		it.AssigneeNames(), it.LabelNames(), it.Body,
+		it.HTMLURL, it.UpdatedAt,
+	}
+	if err := p.PrintOne(fields, row); err != nil {
+		return err
+	}
+	if !*withComments {
+		return nil
+	}
+	return printComments(env, ops, owner, name, num)
+}
+
+// printComments 輸出 issue／PR 的留言清單（view --comments 共用）。
+func printComments(env *Env, ops *dailyops.Ops, owner, repo string, number int64) error {
+	comments, err := ops.ListComments(context.Background(), owner, repo, number)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(comments))
+	for i := range comments {
+		c := &comments[i]
+		rows = append(rows, gitea.Values{c.Author(), c.CreatedAt, c.Body})
+	}
+	return p.PrintList([]gitea.Field{
+		{Name: "author"}, {Name: "created_at"}, {Name: "body"},
+	}, rows)
+}
+
+// runIssuesCreate：teai issues create --repo owner/repo --title … [--body …] [--assignees a,b] --yes
+func runIssuesCreate(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai issues create", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	title := fs.String("title", "", "標題（必填）")
+	body := fs.String("body", "", "內文")
+	assignees := fs.String("assignees", "", "assignees（逗號分隔，可選）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "issues create 需要 --repo owner/repo"}
+	}
+	if strings.TrimSpace(*title) == "" {
+		return &ErrUsage{Msg: "issues create 需要 --title"}
+	}
+	if err := requireYes(*yes, "issues create"); err != nil {
+		return err
+	}
+	var assigneeList []string
+	if strings.TrimSpace(*assignees) != "" {
+		for _, a := range strings.Split(*assignees, ",") {
+			if a = strings.TrimSpace(a); a != "" {
+				assigneeList = append(assigneeList, a)
+			}
+		}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	issue, err := ops.CreateIssue(context.Background(), owner, name, *title, *body, assigneeList)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "url"},
+	}, gitea.Values{issue.Number, issue.Title, issue.HTMLURL})
+}
+
+// runIssuesClose：teai issues close --repo owner/repo <number> --yes
+func runIssuesClose(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai issues close", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "issues close 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "issues close 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	if err := requireYes(*yes, "issues close"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	issue, err := ops.SetIssueState(context.Background(), owner, name, num, "closed")
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"}, {Name: "url"},
+	}, gitea.Values{issue.Number, issue.Title, issue.State, issue.HTMLURL})
+}
+
+// runComment：teai issues comment / teai pulls comment 共用。
+func runComment(env *Env, args []string, isPR bool) error {
+	name := "issues comment"
+	if isPR {
+		name = "pulls comment"
+	}
+	fs := flag.NewFlagSet("teai "+name, flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	body := fs.String("body", "", "留言內容（必填）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, rname, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: name + " 需要 --repo owner/repo"}
+	}
+	if strings.TrimSpace(*body) == "" {
+		return &ErrUsage{Msg: name + " 需要 --body"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: name + " 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	if err := requireYes(*yes, name); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	comment, err := ops.AddComment(context.Background(), owner, rname, num, *body)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "author"}, {Name: "created_at"}, {Name: "body"},
+	}, gitea.Values{comment.Author(), comment.CreatedAt, comment.Body})
+}
+
+// ---- pulls ----
+
+// runPullsDaily：teai pulls [list|view|create|merge|comment] …；
+// 無子命令時沿用 #6 的工作流清單（teai pulls [--mine|--reviewer] [--repo]）。
+func runPullsDaily(env *Env, args []string) error {
+	if len(args) == 0 || strings.HasPrefix(args[0], "-") {
+		// 相容 #6：teai pulls / teai pulls --mine …（工作流清單）。
+		return runPulls(env, args)
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runPullsList(env, rest)
+	case "view":
+		return runPullsView(env, rest)
+	case "create":
+		return runPullsCreate(env, rest)
+	case "merge":
+		return runPullsMerge(env, rest)
+	case "comment":
+		return runComment(env, rest, true)
+	default:
+		return &ErrUsage{Msg: fmt.Sprintf("pulls 未知子命令 %q（可用：list | view | create | merge | comment；或無子命令＝工作流清單）", sub)}
+	}
+}
+
+// runPullsList：teai pulls list --repo owner/repo [--state open|closed|all]
+func runPullsList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	state := fs.String("state", "open", "狀態：open|closed|all")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls list 需要 --repo owner/repo"}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	pulls, err := ops.ListPulls(context.Background(), owner, name, *state)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(pulls))
+	for i := range pulls {
+		pr := &pulls[i]
+		rows = append(rows, gitea.Values{
+			pr.Number, pr.Title, pr.State, pr.Author(),
+			pr.HeadRef(), pr.BaseRef(), pr.UpdatedAt,
+		})
+	}
+	return p.PrintList([]gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"},
+		{Name: "author"}, {Name: "head"}, {Name: "base"}, {Name: "updated_at"},
+	}, rows)
+}
+
+// runPullsView：teai pulls view --repo owner/repo <number> [--comments]
+func runPullsView(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls view", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	withComments := fs.Bool("comments", false, "連留言一起輸出")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls view 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "pulls view 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	pr, err := ops.GetPull(context.Background(), owner, name, num)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	fields := []gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "state"},
+		{Name: "author"}, {Name: "head"}, {Name: "base"}, {Name: "body"},
+		{Name: "url"}, {Name: "updated_at"},
+	}
+	row := gitea.Values{
+		pr.Number, pr.Title, pr.State, pr.Author(),
+		pr.HeadRef(), pr.BaseRef(), pr.Body, pr.HTMLURL, pr.UpdatedAt,
+	}
+	if err := p.PrintOne(fields, row); err != nil {
+		return err
+	}
+	if !*withComments {
+		return nil
+	}
+	return printComments(env, ops, owner, name, num)
+}
+
+// runPullsCreate：teai pulls create --repo owner/repo --head <branch> --base <branch> --title … [--body …] --yes
+func runPullsCreate(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls create", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	head := fs.String("head", "", "來源分支（必填）")
+	base := fs.String("base", "main", "目標分支（預設 main）")
+	title := fs.String("title", "", "標題（必填）")
+	body := fs.String("body", "", "說明")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls create 需要 --repo owner/repo"}
+	}
+	if *head == "" || *title == "" {
+		return &ErrUsage{Msg: "pulls create 需要 --head 與 --title"}
+	}
+	if err := requireYes(*yes, "pulls create"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	pr, err := ops.CreatePull(context.Background(), owner, name, *title, *body, *head, *base)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "title"}, {Name: "url"},
+	}, gitea.Values{pr.Number, pr.Title, pr.HTMLURL})
+}
+
+// runPullsMerge：teai pulls merge --repo owner/repo <number> [--style merge|rebase|squash] --yes
+func runPullsMerge(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls merge", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	style := fs.String("style", "merge", "合併方式：merge|rebase|rebase-merge|squash")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "pulls merge 需要 --repo owner/repo"}
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "pulls merge 需要恰好一個編號"}
+	}
+	num, err := parseNumber(fs.Arg(0))
+	if err != nil {
+		return err
+	}
+	switch *style {
+	case "merge", "rebase", "rebase-merge", "squash":
+	default:
+		return &ErrUsage{Msg: "pulls merge 的 --style 需為 merge|rebase|rebase-merge|squash"}
+	}
+	if err := requireYes(*yes, "pulls merge"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	if err := ops.MergePull(context.Background(), owner, name, num, *style); err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "number"}, {Name: "state"},
+	}, gitea.Values{num, "merged"})
+}
+
+// ---- labels ----
+
+// runLabels：teai labels list --repo owner/repo｜teai labels create … --yes
+func runLabels(env *Env, args []string) error {
+	if len(args) == 0 {
+		return &ErrUsage{Msg: "labels 需要子命令：list | create"}
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runLabelsList(env, rest)
+	case "create":
+		return runLabelsCreate(env, rest)
+	default:
+		return &ErrUsage{Msg: fmt.Sprintf("labels 未知子命令 %q（可用：list | create）", sub)}
+	}
+}
+
+// runLabelsList：teai labels list --repo owner/repo
+func runLabelsList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai labels list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "labels list 需要 --repo owner/repo"}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	labels, err := ops.ListLabels(context.Background(), owner, name)
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(labels))
+	for _, l := range labels {
+		rows = append(rows, gitea.Values{l.Name, l.Color, l.Description})
+	}
+	return printer(env).PrintList([]gitea.Field{
+		{Name: "name"}, {Name: "color"}, {Name: "description"},
+	}, rows)
+}
+
+// runLabelsCreate：teai labels create --repo owner/repo --name … [--color …] [--description …] --yes
+func runLabelsCreate(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai labels create", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	labelName := fs.String("name", "", "標籤名（必填）")
+	color := fs.String("color", "#ffffff", "顏色（#RRGGBB，預設 #ffffff）")
+	desc := fs.String("description", "", "說明")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "labels create 需要 --repo owner/repo"}
+	}
+	if *labelName == "" {
+		return &ErrUsage{Msg: "labels create 需要 --name"}
+	}
+	if err := requireYes(*yes, "labels create"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	label, err := ops.CreateLabel(context.Background(), owner, name, *labelName, *color, *desc)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "name"}, {Name: "color"}, {Name: "description"},
+	}, gitea.Values{label.Name, label.Color, label.Description})
+}
+
+// ---- milestones ----
+
+// runMilestones：teai milestones [list|create] …；不帶子命令時輸出
+// 跨倉庫里程碑總覽（#31，對應 gitea.py milestones）。帶 --repo 直接
+// 跟在 milestones 之後時維持現行單倉庫 list 語義。
+func runMilestones(env *Env, args []string) error {
+	if len(args) == 0 {
+		return runMilestonesOverview(env)
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runMilestonesList(env, rest)
+	case "create":
+		return runMilestonesCreate(env, rest)
+	default:
+		if !strings.HasPrefix(sub, "-") {
+			return &ErrUsage{Msg: fmt.Sprintf("milestones 未知子命令 %q（可用：list | create；或不帶參數輸出跨倉庫總覽）", sub)}
+		}
+		// milestones 之後直接跟旗標（非子命令）：帶 --repo → 整串轉發，
+		// 維持現行單倉庫 list 語義（--state 等旗標一併生效）；否則為
+		// 跨倉庫總覽（總覽不接受任何命令旗標，空 FlagSet 讓未知旗標
+		// 報用法錯誤）。
+		hasRepo := false
+		for _, a := range args {
+			if a == "--repo" || strings.HasPrefix(a, "--repo=") {
+				hasRepo = true
+				break
+			}
+		}
+		if hasRepo {
+			return runMilestonesList(env, args)
+		}
+		fs := flag.NewFlagSet("teai milestones", flag.ContinueOnError)
+		fs.SetOutput(env.Err)
+		if err := parseFlags(fs, args); err != nil {
+			return err
+		}
+		if fs.NArg() != 0 {
+			return &ErrUsage{Msg: "milestones 不接受位置參數（子命令：list | create）"}
+		}
+		return runMilestonesOverview(env)
+	}
+}
+
+// runMilestonesList：teai milestones list --repo owner/repo [--state open|closed|all]
+func runMilestonesList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai milestones list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	state := fs.String("state", "open", "狀態：open|closed|all")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "milestones list 需要 --repo owner/repo"}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	ms, err := ops.ListMilestones(context.Background(), owner, name, *state)
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(ms))
+	for _, m := range ms {
+		rows = append(rows, gitea.Values{m.Title, m.State, m.Description, m.DueOn})
+	}
+	return printer(env).PrintList([]gitea.Field{
+		{Name: "title"}, {Name: "state"}, {Name: "description"}, {Name: "due_on"},
+	}, rows)
+}
+
+// runMilestonesCreate：teai milestones create --repo owner/repo --title … [--description …] [--due …] --yes
+func runMilestonesCreate(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai milestones create", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	title := fs.String("title", "", "標題（必填）")
+	desc := fs.String("description", "", "說明")
+	due := fs.String("due", "", "截止日（RFC3339，可選）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "milestones create 需要 --repo owner/repo"}
+	}
+	if *title == "" {
+		return &ErrUsage{Msg: "milestones create 需要 --title"}
+	}
+	if err := requireYes(*yes, "milestones create"); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	m, err := ops.CreateMilestone(context.Background(), owner, name, *title, *desc, *due)
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne([]gitea.Field{
+		{Name: "id"}, {Name: "title"}, {Name: "state"}, {Name: "due_on"},
+	}, gitea.Values{m.ID, m.Title, m.State, m.DueOn})
+}
+
+// ---- releases / repos / api ----
+
+// runReleases：teai releases list --repo owner/repo
+func runReleases(env *Env, args []string) error {
+	if len(args) == 0 || args[0] != "list" {
+		return &ErrUsage{Msg: "releases 目前支援子命令：list"}
+	}
+	fs := flag.NewFlagSet("teai releases list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	repo := fs.String("repo", "", "倉庫（owner/repo，必填）")
+	if err := parseFlags(fs, args[1:]); err != nil {
+		return err
+	}
+	owner, name, err := splitRepoFlag(*repo)
+	if err != nil {
+		return err
+	}
+	if owner == "" {
+		return &ErrUsage{Msg: "releases list 需要 --repo owner/repo"}
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	releases, err := ops.ListReleases(context.Background(), owner, name)
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(releases))
+	for _, r := range releases {
+		rows = append(rows, gitea.Values{r.TagName, r.Name, r.Draft, r.Prerelease, r.PublishedAt})
+	}
+	return printer(env).PrintList([]gitea.Field{
+		{Name: "tag_name"}, {Name: "name"}, {Name: "draft"}, {Name: "prerelease"}, {Name: "published_at"},
+	}, rows)
+}
+
+// runRepos：teai repos list [--org <org>]（未指定 --org 則列自己可存的倉庫）
+func runRepos(env *Env, args []string) error {
+	if len(args) == 0 || args[0] != "list" {
+		return &ErrUsage{Msg: "repos 目前支援子命令：list"}
+	}
+	fs := flag.NewFlagSet("teai repos list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	org := fs.String("org", "", "組織（未指定則列自己可存取的倉庫）")
+	if err := parseFlags(fs, args[1:]); err != nil {
+		return err
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	var repos []dailyops.Repo
+	if *org != "" {
+		repos, err = ops.ListOrgRepos(context.Background(), *org)
+	} else {
+		repos, err = ops.ListMyRepos(context.Background())
+	}
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(repos))
+	for _, r := range repos {
+		rows = append(rows, gitea.Values{r.FullName, r.Private, r.Empty, r.UpdatedAt, r.HTMLURL})
+	}
+	return printer(env).PrintList([]gitea.Field{
+		{Name: "full_name"}, {Name: "private"}, {Name: "empty"}, {Name: "updated_at"}, {Name: "url"},
+	}, rows)
+}
+
+// runAPIDirect：teai api <path> [--method GET|POST|…] [--data <json>] [--yes]
+func runAPIDirect(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai api", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	method := fs.String("method", "GET", "HTTP 動詞（GET 預設；非 GET 需 --yes）")
+	data := fs.String("data", "", "請求 body（JSON 字串，可選）")
+	yes := fs.Bool("yes", false, "確認寫入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "api 需要恰好一個 path（相對 api/v1，以 / 開頭）"}
+	}
+	path := fs.Arg(0)
+	// path 內含查詢字串（如 /repos/x?state=closed）時剝離到 rawQuery，
+	// 不可併進 URL path（會 404）。
+	rawQuery := ""
+	if q := strings.IndexByte(path, '?'); q >= 0 {
+		rawQuery = path[q+1:]
+		path = path[:q]
+	}
+	if path == "" || path[0] != '/' {
+		return &ErrUsage{Msg: "api path 必須以 / 開頭（相對 api/v1）"}
+	}
+	upper := strings.ToUpper(strings.TrimSpace(*method))
+	if upper == "" {
+		upper = "GET"
+	}
+	switch upper {
+	case "GET", "HEAD", "OPTIONS":
+	default:
+		if err := requireYes(*yes, "api "+upper); err != nil {
+			return err
+		}
+	}
+	var payload []byte
+	if strings.TrimSpace(*data) != "" {
+		if !json.Valid([]byte(*data)) {
+			return &ErrUsage{Msg: "--data 必須是合法 JSON"}
+		}
+		payload = []byte(*data)
+	}
+	ops, err := newOpsClient(env)
+	if err != nil {
+		return err
+	}
+	resp, err := ops.CallAPIDirect(context.Background(), upper, path, rawQuery, payload)
+	if err != nil {
+		return err
+	}
+	// 原樣輸出（teai api 是逃生口，不做欄位挑選）。
+	_, err = env.Out.Write(resp)
+	if len(resp) > 0 && resp[len(resp)-1] != '\n' {
+		fmt.Fprintln(env.Out)
+	}
+	return err
+}
@@ -0,0 +1,338 @@
+// dailyops_commands_test.go — #8 的驗收測試：以 httptest 假伺服器驗證
+// issues/pulls/labels/milestones/releases/repos/api 的讀取行為，與
+// 寫入命令的 --yes 閘門（未帶 --yes 不得發出任何請求）。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// opsTestServer 建立假 Gitea API 伺服器與對應的執行輔助。
+func opsTestServer(t *testing.T, handler http.HandlerFunc) func(args ...string) (string, string, int) {
+	t.Helper()
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+	return func(args ...string) (string, string, int) {
+		full := append([]string{"--url", srv.URL}, args...)
+		return runCLI(full...) // 套件級輔助（見下）
+	}
+}
+
+// runCLI 是 cli_test.go `run` 的別名，避免與各測試內的區域變數 run 混淆。
+func runCLI(args ...string) (string, string, int) {
+	return run(args...)
+}
+
+// TestIssuesListReadsOpenIssuesOnly 驗證 issues list 帶 state=open 與
+// type=issues（排除 PR），輸出 JSON 陣列。
+func TestIssuesListReadsOpenIssuesOnly(t *testing.T) {
+	var gotQuery string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotQuery = r.URL.RawQuery
+		fmt.Fprint(w, `[{"number":8,"title":"日常操作","state":"open","user":{"login":"ceo"},"assignees":[{"login":"alex"}],"updated_at":"2026-09-10T08:13:00Z"}]`)
+	})
+	stdout, _, code := run("issues", "list", "--repo", "alterminal/teai")
+	if code != 0 {
+		t.Fatalf("issues list 應回 0，得到 %d", code)
+	}
+	if !strings.Contains(gotQuery, "state=open") || !strings.Contains(gotQuery, "type=issues") {
+		t.Errorf("查詢參數應含 state=open 與 type=issues，得到 %q", gotQuery)
+	}
+	if !strings.Contains(stdout, `"number":8`) || !strings.Contains(stdout, `"author":"ceo"`) {
+		t.Errorf("輸出應含 number 與 author 欄位，得到：%s", stdout)
+	}
+}
+
+// TestIssuesListRequiresRepo 驗證 --repo 必填。
+func TestIssuesListRequiresRepo(t *testing.T) {
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		t.Errorf("不應發出任何請求")
+	})
+	_, stderr, code := run("issues", "list")
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 {
+		t.Errorf("缺 --repo 應回 2（README 用法錯誤），得到 %d", code)
+	}
+	if !strings.Contains(stderr, "--repo") {
+		t.Errorf("錯誤訊息應提及 --repo，得到：%s", stderr)
+	}
+}
+
+// TestIssuesViewWithComments 驗證 view --comments 連留言輸出。
+func TestIssuesViewWithComments(t *testing.T) {
+	var paths []string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		paths = append(paths, r.URL.Path)
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/issues/8"):
+			fmt.Fprint(w, `{"number":8,"title":"日常操作","state":"open","user":{"login":"ceo"},"body":"內文","html_url":"https://x/8","labels":[],"updated_at":"t"}`)
+		case strings.HasSuffix(r.URL.Path, "/comments"):
+			fmt.Fprint(w, `[{"body":"開始處理","created_at":"t1","user":{"login":"alex"}}]`)
+		default:
+			fmt.Fprint(w, `[]`)
+		}
+	})
+	stdout, _, code := run("issues", "view", "--repo", "alterminal/teai", "--comments", "8")
+	if code != 0 {
+		t.Fatalf("view --comments 應回 0，得到 %d", code)
+	}
+	if len(paths) != 2 || !strings.HasSuffix(paths[1], "/issues/8/comments") {
+		t.Errorf("應依序呼叫 issue 與 comments 端點，得到 %v", paths)
+	}
+	if !strings.Contains(stdout, `"body":"開始處理"`) {
+		t.Errorf("輸出應含留言內容，得到：%s", stdout)
+	}
+}
+
+// TestWriteCommandsRequireYes 驗證所有寫入命令未帶 --yes 時：
+// 回 ExitUsage 且不發出任何 HTTP 請求（issue 驗收條件）。
+func TestWriteCommandsRequireYes(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+	}{
+		{"issues create", []string{"issues", "create", "--repo", "a/b", "--title", "t"}},
+		{"issues close", []string{"issues", "close", "--repo", "a/b", "1"}},
+		{"issues comment", []string{"issues", "comment", "--repo", "a/b", "--body", "x", "1"}},
+		{"pulls create", []string{"pulls", "create", "--repo", "a/b", "--head", "h", "--title", "t"}},
+		{"pulls merge", []string{"pulls", "merge", "--repo", "a/b", "1"}},
+		{"pulls comment", []string{"pulls", "comment", "--repo", "a/b", "--body", "x", "1"}},
+		{"labels create", []string{"labels", "create", "--repo", "a/b", "--name", "n"}},
+		{"milestones create", []string{"milestones", "create", "--repo", "a/b", "--title", "t"}},
+		{"api POST", []string{"api", "--method", "POST", "/repos/a/b/issues"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+				t.Errorf("%s：未帶 --yes 不得發出請求（%s %s）", tc.name, r.Method, r.URL.Path)
+			})
+			_, stderr, code := run(tc.args...)
+			// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+			if code != 2 {
+				t.Errorf("%s 未帶 --yes 應回 2（README 用法錯誤），得到 %d", tc.name, code)
+			}
+			if !strings.Contains(stderr, "--yes") {
+				t.Errorf("%s 錯誤訊息應提及 --yes，得到：%s", tc.name, stderr)
+			}
+		})
+	}
+}
+
+// TestIssuesCreateWithYes 驗證帶 --yes 時 POST 正確 payload。
+func TestIssuesCreateWithYes(t *testing.T) {
+	var gotMethod, gotPath, gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod, gotPath = r.Method, r.URL.Path
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotBody = string(buf[:n])
+		fmt.Fprint(w, `{"number":15,"title":"新 issue","html_url":"https://x/15"}`)
+	})
+	stdout, _, code := run("issues", "create", "--repo", "alterminal/teai", "--title", "新 issue", "--body", "說明", "--assignees", "alex,ceo", "--yes")
+	if code != 0 {
+		t.Fatalf("create --yes 應回 0，得到 %d", code)
+	}
+	if gotMethod != "POST" || !strings.HasSuffix(gotPath, "/repos/alterminal/teai/issues") {
+		t.Errorf("應 POST /repos/alterminal/teai/issues，得到 %s %s", gotMethod, gotPath)
+	}
+	if !strings.Contains(gotBody, `"assignees":["alex","ceo"]`) {
+		t.Errorf("body 應含 assignees，得到：%s", gotBody)
+	}
+	if !strings.Contains(stdout, `"number":15`) {
+		t.Errorf("輸出應含新 issue 編號，得到：%s", stdout)
+	}
+}
+
+// TestPullsListAndSubcommands 驗證 pulls list 與 pulls（無子命令）可並存。
+func TestPullsListAndSubcommands(t *testing.T) {
+	var gotPath string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		fmt.Fprint(w, `[{"number":13,"title":"PR","state":"open","user":{"login":"alex"},"head":{"ref":"feat"},"base":{"ref":"main"},"updated_at":"t"}]`)
+	})
+	stdout, _, code := run("pulls", "list", "--repo", "alterminal/teai")
+	if code != 0 {
+		t.Fatalf("pulls list 應回 0，得到 %d", code)
+	}
+	if !strings.HasSuffix(gotPath, "/repos/alterminal/teai/pulls") {
+		t.Errorf("應呼叫 /repos/alterminal/teai/pulls，得到 %s", gotPath)
+	}
+	if !strings.Contains(stdout, `"head":"feat"`) || !strings.Contains(stdout, `"base":"main"`) {
+		t.Errorf("輸出應含 head/base 欄位，得到：%s", stdout)
+	}
+}
+
+// TestLabelsMilestonesReleasesList 驗證三個清單命令打對端點並輸出。
+func TestLabelsMilestonesReleasesList(t *testing.T) {
+	cases := []struct {
+		args    []string
+		path    string
+		resp    string
+		wantOut string
+	}{
+		{
+			args:    []string{"labels", "list", "--repo", "a/b"},
+			path:    "/api/v1/repos/a/b/labels",
+			resp:    `[{"name":"enhancement","color":"#84b6eb","description":""}]`,
+			wantOut: `"name":"enhancement"`,
+		},
+		{
+			args:    []string{"milestones", "list", "--repo", "a/b"},
+			path:    "/api/v1/repos/a/b/milestones",
+			resp:    `[{"title":"v1","state":"open","description":"","due_on":""}]`,
+			wantOut: `"title":"v1"`,
+		},
+		{
+			args:    []string{"releases", "list", "--repo", "a/b"},
+			path:    "/api/v1/repos/a/b/releases",
+			resp:    `[{"tag_name":"v1.0.0","name":"首個發佈","draft":false,"prerelease":false,"published_at":"t"}]`,
+			wantOut: `"tag_name":"v1.0.0"`,
+		},
+		{
+			args:    []string{"repos", "list", "--org", "alterminal"},
+			path:    "/api/v1/orgs/alterminal/repos",
+			resp:    `[{"full_name":"alterminal/teai","private":false,"empty":false,"updated_at":"t","html_url":"u"}]`,
+			wantOut: `"full_name":"alterminal/teai"`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
+			var gotPath string
+			run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+				gotPath = r.URL.Path
+				fmt.Fprint(w, tc.resp)
+			})
+			stdout, _, code := run(tc.args...)
+			if code != 0 {
+				t.Fatalf("%v 應回 0，得到 %d", tc.args, code)
+			}
+			if gotPath != tc.path {
+				t.Errorf("應呼叫 %s，得到 %s", tc.path, gotPath)
+			}
+			if !strings.Contains(stdout, tc.wantOut) {
+				t.Errorf("輸出應含 %s，得到：%s", tc.wantOut, stdout)
+			}
+		})
+	}
+}
+
+// TestStateAllSendsExplicitParam 是 #33 的回歸測試：issues／milestones
+// 端點省略 state 時 API 預設 open，closed 項目會漏列，因此 --state all
+// 必須明確帶 state=all；pulls 端點雖省略時也回全部，同樣明確帶上。
+func TestStateAllSendsExplicitParam(t *testing.T) {
+	cases := []struct {
+		args    []string
+		resp    string
+		wantOut string
+	}{
+		{
+			args:    []string{"issues", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"number":30,"title":"open","state":"open","user":{"login":"ceo"},"updated_at":"t"},{"number":12,"title":"closed","state":"closed","user":{"login":"ceo"},"updated_at":"t"}]`,
+			wantOut: `"title":"closed"`,
+		},
+		{
+			args:    []string{"pulls", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"number":5,"title":"open PR","state":"open","user":{"login":"ceo"},"head":{"ref":"f"},"base":{"ref":"main"},"updated_at":"t"},{"number":2,"title":"closed PR","state":"closed","user":{"login":"ceo"},"head":{"ref":"f2"},"base":{"ref":"main"},"updated_at":"t"}]`,
+			wantOut: `"title":"closed PR"`,
+		},
+		{
+			args:    []string{"milestones", "list", "--repo", "a/b", "--state", "all"},
+			resp:    `[{"title":"v2","state":"open","description":"","due_on":""},{"title":"v1","state":"closed","description":"","due_on":""}]`,
+			wantOut: `"title":"v1"`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
+			var gotQuery string
+			run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+				gotQuery = r.URL.RawQuery
+				fmt.Fprint(w, tc.resp)
+			})
+			stdout, _, code := run(tc.args...)
+			if code != 0 {
+				t.Fatalf("%v 應回 0，得到 %d", tc.args, code)
+			}
+			if !strings.Contains(gotQuery, "state=all") {
+				t.Errorf("%v 應明確帶 state=all（省略時 issues／milestones 端點預設 open），得到查詢 %q", tc.args, gotQuery)
+			}
+			if !strings.Contains(stdout, tc.wantOut) {
+				t.Errorf("%v 輸出應含 closed 項目 %s，得到：%s", tc.args, tc.wantOut, stdout)
+			}
+		})
+	}
+}
+
+// TestAPIDirectPassthrough 驗證 teai api 原樣輸出、GET 免 --yes、
+// POST 未帶 --yes 被擋。
+func TestAPIDirectPassthrough(t *testing.T) {
+	var gotMethod string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod = r.Method
+		fmt.Fprint(w, `{"version":"1.27.0"}`)
+	})
+	stdout, _, code := run("api", "/version")
+	if code != 0 || gotMethod != "GET" {
+		t.Fatalf("GET /version 應回 0，得到 %d (%s)", code, gotMethod)
+	}
+	if strings.TrimSpace(stdout) != `{"version":"1.27.0"}` {
+		t.Errorf("api 應原樣輸出，得到：%s", stdout)
+	}
+
+	_, stderr, code := run("api", "--method", "POST", "/version")
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 || !strings.Contains(stderr, "--yes") {
+		t.Errorf("POST 未帶 --yes 應回 2 並提及 --yes，得到 %d：%s", code, stderr)
+	}
+}
+
+// TestAPIDirectQueryInPath 驗證 path 內含 ?query 時查詢字串正確傳遞。
+func TestAPIDirectQueryInPath(t *testing.T) {
+	var gotQuery, gotPath string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotPath, gotQuery = r.URL.Path, r.URL.RawQuery
+		fmt.Fprint(w, `[]`)
+	})
+	_, _, code := run("api", "/repos/a/b/issues?state=closed&limit=10")
+	if code != 0 {
+		t.Fatalf("api 帶查詢字串應回 0，得到 %d", code)
+	}
+	if gotPath != "/api/v1/repos/a/b/issues" || gotQuery != "state=closed&limit=10" {
+		t.Errorf("應剝離查詢字串，得到 path=%s query=%s", gotPath, gotQuery)
+	}
+}
+
+// TestIssuesCommentPostsBody 驗證 comment --yes 送出 body。
+func TestIssuesCommentPostsBody(t *testing.T) {
+	var gotPath, gotBody string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		buf := make([]byte, 512)
+		n, _ := r.Body.Read(buf)
+		gotPath, gotBody = r.URL.Path, string(buf[:n])
+		fmt.Fprint(w, `{"body":"留言","created_at":"t","user":{"login":"alex"}}`)
+	})
+	_, _, code := run("issues", "comment", "--repo", "alterminal/teai", "--body", "留言", "--yes", "8")
+	if code != 0 {
+		t.Fatalf("comment --yes 應回 0，得到 %d", code)
+	}
+	if !strings.HasSuffix(gotPath, "/issues/8/comments") || !strings.Contains(gotBody, `"body":"留言"`) {
+		t.Errorf("應 POST comments 端點帶 body，得到 %s %s", gotPath, gotBody)
+	}
+}
+
+// TestExtractGlobalsAllowsCommandFlags 驗證命令旗標與全域選項可交錯。
+func TestExtractGlobalsAllowsCommandFlags(t *testing.T) {
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"login":"alex"}`)
+	})
+	stdout, _, code := run("whoami", "--output", "table")
+	if code != 0 {
+		t.Fatalf("whoami --output table 應回 0，得到 %d", code)
+	}
+	if !strings.Contains(stdout, "alex") {
+		t.Errorf("table 輸出應含 alex，得到：%s", stdout)
+	}
+}
@@ -0,0 +1,224 @@
+// exitcode_test.go 驗證結束碼映射：用法錯誤 → 2、API 錯誤 → 3、其他 → 1，
+// 以及全域選項剖析（README「輸出與結束碼」「全域介面」）。
+package cli
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+func TestExitCodeMapping(t *testing.T) {
+	// want 直接寫 README「輸出與結束碼」的數值（0／2／3；內部錯誤 1），
+	// 不以常數互比，避免常數與規格再次脫鉤（#10）。
+	cases := []struct {
+		name string
+		err  error
+		want int
+	}{
+		{"usage error", &ErrUsage{Msg: "bad flag"}, 2},
+		{"api error 401", &gitea.ErrAPI{StatusCode: 401, Op: "GET /api/v1/user"}, 3},
+		{"api error transport", &gitea.ErrAPI{Op: "GET /api/v1/user", Err: errString("dial tcp")}, 3},
+		{"wrapped api error", wrapped(&gitea.ErrAPI{StatusCode: 500}), 3},
+		{"other error", errString("boom"), 1},
+		{"nil maps to OK", nil, 0},
+	}
+	for _, tc := range cases {
+		if got := int(exitCodeFor(tc.err)); got != tc.want {
+			t.Errorf("%s: exitCodeFor = %d, want %d", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestRunExitCodes(t *testing.T) {
+	t.Run("unknown command exits 2", func(t *testing.T) {
+		_, _, code := run("no-such")
+		if code != 2 {
+			t.Fatalf("code = %d, want 2", code)
+		}
+	})
+	t.Run("unknown global option exits 2", func(t *testing.T) {
+		_, _, code := run("--wat", "version")
+		if code != 2 {
+			t.Fatalf("code = %d, want 2", code)
+		}
+	})
+	t.Run("missing option value exits 2", func(t *testing.T) {
+		_, _, code := run("--output")
+		if code != 2 {
+			t.Fatalf("code = %d, want 2", code)
+		}
+	})
+	t.Run("invalid output value exits 2", func(t *testing.T) {
+		_, _, code := run("--output=yaml", "version")
+		if code != 2 {
+			t.Fatalf("code = %d, want 2", code)
+		}
+	})
+	t.Run("invalid timeout exits 2", func(t *testing.T) {
+		_, _, code := run("--timeout=soon", "version")
+		if code != 2 {
+			t.Fatalf("code = %d, want 2", code)
+		}
+	})
+	t.Run("version still works with globals", func(t *testing.T) {
+		stdout, _, code := run("--output=table", "--timeout=10s", "version")
+		if code != 0 || !strings.Contains(stdout, "teai version ") {
+			t.Fatalf("code = %d stdout = %q", code, stdout)
+		}
+	})
+}
+
+func TestExtractGlobals(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"--url", "https://example.com",
+		"--token=tok",
+		"--config", "/tmp/c.yml",
+		"--output", "table",
+		"--timeout", "45s",
+		"next",
+	}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rest) != 1 || rest[0] != "next" {
+		t.Fatalf("rest = %v, want [next]", rest)
+	}
+	if g.URL != "https://example.com" || g.Token != "tok" || g.ConfigPath != "/tmp/c.yml" {
+		t.Fatalf("globals = %+v", g)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+	if g.Timeout.String() != "45s" {
+		t.Fatalf("timeout = %s", g.Timeout)
+	}
+}
+
+func TestExtractGlobalsAfterCommand(t *testing.T) {
+	// 全域選項出現在命令之後也應抽出（README：teai next --output table）。
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{"version", "--output", "table"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rest) != 1 || rest[0] != "version" {
+		t.Fatalf("rest = %v, want [version]", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
+func TestExtractGlobalsKeepsCommandFlags(t *testing.T) {
+	// 非全域選項屬於子命令：原樣依序交回，不能攔成 ErrUsage。
+	cases := [][]string{
+		{"members", "--has-work"},
+		{"pulls", "--mine"},
+		{"pulls", "--reviewer"},
+		{"pulls", "--repo", "alterminal/teai"},
+		{"members", "--has-work", "--output", "table"},
+		{"pulls", "--mine", "--repo", "alterminal/teai", "--output", "table"},
+	}
+	for _, args := range cases {
+		g := defaultGlobals()
+		rest, err := extractGlobals(&g, args, nil)
+		if err != nil {
+			t.Fatalf("extractGlobals(%v) 不應報錯：%v", args, err)
+		}
+		want := args
+		if strings.HasSuffix(strings.Join(args, " "), "--output table") {
+			want = args[:len(args)-2]
+		}
+		if len(rest) != len(want) {
+			t.Fatalf("extractGlobals(%v) rest = %v, want %v", args, rest, want)
+		}
+		for i := range want {
+			if rest[i] != want[i] {
+				t.Fatalf("extractGlobals(%v) rest = %v, want %v", args, rest, want)
+			}
+		}
+	}
+}
+
+func TestExtractGlobalsDoubleDashStops(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{"--output", "table", "--", "--url", "x"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// -- 之後全部交回，--url 不再視為全域選項。
+	if len(rest) != 2 || rest[0] != "--url" || rest[1] != "x" {
+		t.Fatalf("rest = %v", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
+// TestExtractGlobalsReservedFlags 驗證 #18：與全域同名的命令旗標
+// （登記於 commandReservedFlags）必須留給命令，其餘全域選項照常抽取。
+func TestExtractGlobalsReservedFlags(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"add",
+		"--url", "https://srv.example.com", // login add 自有旗標：保留
+		"--token=tok", // 同上（inline 形式）：保留
+		"--name", "test-site",
+		"--output", "table", // 非保留：仍是全域
+	}, reservedFlags("login"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"add", "--url", "https://srv.example.com", "--token=tok", "--name", "test-site"}
+	if len(rest) != len(want) {
+		t.Fatalf("rest = %v, want %v", rest, want)
+	}
+	for i := range want {
+		if rest[i] != want[i] {
+			t.Fatalf("rest = %v, want %v", rest, want)
+		}
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+	if g.URL != defaultGlobals().URL || g.Token != "" {
+		t.Fatalf("reserved flags must not leak into globals: %+v", g)
+	}
+}
+
+// TestExtractGlobalsNonReservedCommand 驗證 #13 行為不回歸：未登記保留
+// 旗標的命令（如 next/members/pulls），命令後的全域選項照常抽取、
+// 命令自己的旗標（--has-work 等）原樣保留。
+func TestExtractGlobalsNonReservedCommand(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"members", "--has-work", "--output", "table",
+	}, reservedFlags("members"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rest) != 2 || rest[0] != "members" || rest[1] != "--has-work" {
+		t.Fatalf("rest = %v, want [members --has-work]", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
+// errString 把字串轉成 error（測試輔助）。
+type errStr string
+
+func (e errStr) Error() string { return string(e) }
+
+func errString(s string) error { return errStr(s) }
+
+// wrapped 包一層 error（測試 errors.As 穿透）。
+type wrappedErr struct{ inner error }
+
+func (w wrappedErr) Error() string { return "wrapped: " + w.inner.Error() }
+func (w wrappedErr) Unwrap() error { return w.inner }
+
+func wrapped(inner error) error { return wrappedErr{inner} }
@@ -0,0 +1,160 @@
+// interleaved_flags_test.go — #25 的回歸測試：命令旗標放在位置參數
+// （path／編號／名稱）之後也必須被剖析，不得被當成位置參數。
+// 涵蓋 parseFlags 走的命令（issues/pulls view、api、stalled）與
+// 原本直接 fs.Parse 的命令（login default/remove、members）。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+)
+
+// TestAPIFlagsAfterPath 驗證 #25 重現步驟一：teai api <path> --method POST
+// --data '{}' --yes 的旗標在 path 之後仍被剖析（POST 送達伺服器而非 exit 2）。
+func TestAPIFlagsAfterPath(t *testing.T) {
+	var gotMethod string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod = r.Method
+		fmt.Fprint(w, `{}`)
+	})
+	_, _, code := run("api", "/version", "--method", "POST", "--data", `{}`, "--yes")
+	if code != 0 {
+		t.Fatalf("api 旗標在 path 之後應回 0（#25），得到 %d", code)
+	}
+	if gotMethod != "POST" {
+		t.Fatalf("應送出 POST，得到 %s", gotMethod)
+	}
+}
+
+// TestIssuesViewCommentsFlagAfterNumber 驗證 #25 重現步驟二：
+// teai issues view --repo owner/repo <編號> --comments 的 --comments
+// 在編號之後仍生效（有打 /comments 端點）。
+func TestIssuesViewCommentsFlagAfterNumber(t *testing.T) {
+	var commentsHit bool
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/comments"):
+			commentsHit = true
+			fmt.Fprint(w, `[]`)
+		case strings.HasSuffix(r.URL.Path, "/issues/8"):
+			fmt.Fprint(w, `{"number":8,"title":"t","state":"open","user":{"login":"ceo"},"body":"","html_url":"u","labels":[],"updated_at":"t"}`)
+		default:
+			fmt.Fprint(w, `[]`)
+		}
+	})
+	stdout, _, code := run("issues", "view", "--repo", "alterminal/teai", "8", "--comments")
+	if code != 0 {
+		t.Fatalf("issues view 編號在前旗標在後應回 0（#25），得到 %d", code)
+	}
+	if !commentsHit {
+		t.Fatalf("--comments 在編號之後應觸發 /comments 請求；輸出：%s", stdout)
+	}
+}
+
+// TestPullsViewCommentsFlagAfterNumber 同上，驗證 pulls view。
+func TestPullsViewCommentsFlagAfterNumber(t *testing.T) {
+	var commentsHit bool
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/comments"):
+			commentsHit = true
+			fmt.Fprint(w, `[]`)
+		case strings.HasSuffix(r.URL.Path, "/pulls/13"):
+			fmt.Fprint(w, `{"number":13,"title":"t","state":"open","user":{"login":"ceo"},"body":"","html_url":"u","labels":[],"updated_at":"t"}`)
+		default:
+			fmt.Fprint(w, `[]`)
+		}
+	})
+	_, _, code := run("pulls", "view", "--repo", "alterminal/teai", "13", "--comments")
+	if code != 0 {
+		t.Fatalf("pulls view 編號在前旗標在後應回 0（#25），得到 %d", code)
+	}
+	if !commentsHit {
+		t.Fatal("--comments 在編號之後應觸發 /comments 請求")
+	}
+}
+
+// TestStalledHoursFlagAfterPositional 驗證 stalled 即使混入位置參數
+// 也不誤剖析：--hours 在位置參數後仍被剖析，而 stalled 本身不接受
+// 位置參數 → 應回 2（用法錯誤）而非誤把 --hours 當位置參數。
+func TestStalledHoursFlagAfterPositional(t *testing.T) {
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `[]`)
+	})
+	_, stderr, code := run("stalled", "9", "--hours", "3")
+	if code != 2 {
+		t.Fatalf("stalled 帶位置參數應回 2，得到 %d", code)
+	}
+	if !strings.Contains(stderr, "位置參數") {
+		t.Fatalf("錯誤訊息應提及位置參數，得到：%s", stderr)
+	}
+	// 對照組：--hours 值非法（剖析層錯誤）應回 2，而非把旗標當位置參數。
+	_, stderr, code = run("stalled", "--hours", "abc")
+	if code != 2 || !strings.Contains(stderr, "invalid value") {
+		t.Fatalf("stalled --hours abc 應回 2 且提及 invalid value，得到 %d：%s", code, stderr)
+	}
+	// 交錯但無多餘位置參數：--hours 值不會被誤收。
+	_, stderr, code = run("stalled", "--hours")
+	if code != 2 || !strings.Contains(stderr, "flag needs an argument") {
+		t.Fatalf("stalled --hours 缺值應回 2 且提及 flag needs an argument，得到 %d：%s", code, stderr)
+	}
+}
+
+// TestLoginDefaultNameOnly 驗證 login default <名稱>：位置參數在旗標
+// 之後（--config 在前）仍正確收取一個名稱。
+func TestLoginDefaultNameOnly(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	prefix, _ := loginTestEnv(t, cfg)
+	stdout, _, code := run(append(prefix, "login", "default", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("login default b 應回 0 並輸出 b：code=%d out=%s", code, stdout)
+	}
+	// 多給一個位置參數仍應報用法錯誤（不受交錯支援影響）。
+	_, stderr, code := run(append(prefix, "login", "default", "b", "c")...)
+	if code != 2 || !strings.Contains(stderr, "exactly one") {
+		t.Fatalf("兩個名稱應回 2，得到 %d：%s", code, stderr)
+	}
+}
+
+// TestMemberHelpExitZero 驗證命令的 -h 結束碼為 0（#25 順帶修正：
+// errHelp 視為成功）。
+func TestMemberHelpExitZero(t *testing.T) {
+	_, _, code := run("members", "-h")
+	if code != 0 {
+		t.Fatalf("members -h 應回 0，得到 %d", code)
+	}
+}
+
+// TestLoginRemoveFlagInterleaved 驗證 login remove <名稱> --yes：
+// --yes 在名稱之後仍視為旗標（未帶時走確認流程會讀 stdin）。
+func TestLoginRemoveFlagInterleaved(t *testing.T) {
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+`)
+	old := loginStdin
+	loginStdin = strings.NewReader("y\n") // 若 --yes 失效會讀到這行
+	defer func() { loginStdin = old }()
+	_, _, code := run(append(prefix, "login", "remove", "a", "--yes")...)
+	if code != 0 {
+		t.Fatalf("login remove a --yes 應回 0，得到 %d", code)
+	}
+	data, _ := os.ReadFile(configPath)
+	if strings.Contains(string(data), "token: ta") {
+		t.Fatalf("--yes 在名稱之後應生效（直接刪除）：\n%s", data)
+	}
+}
@@ -0,0 +1,365 @@
+// login.go — teai login 指令：管理 tea 相容的登入組態。
+//
+// teai 與 tea 共用同一份組態檔（README 設計原則 5），login 的職責是：
+// 以 token 向站點驗證（GET /user），成功後才寫入組態並記下帳號。
+// token 只走記憶體與組態檔，不進輸出、日誌或錯誤訊息。
+//
+// 子命令：list／add／default／remove。
+package cli
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// loginStdin 是讀 token 與確認的輸入（測試可替換）。
+var loginStdin io.Reader = os.Stdin
+
+// loginConfigPath 回傳組態檔路徑：--config／TEA_CONFIG 優先，其次
+// ~/.config/tea/config.yml。找不到可用路徑回空字串。
+func loginConfigPath(g Globals) string {
+	if p := strings.TrimSpace(g.ConfigPath); p != "" {
+		return expandHome(p)
+	}
+	if p := os.Getenv("TEA_CONFIG"); strings.TrimSpace(p) != "" {
+		return expandHome(strings.TrimSpace(p))
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".config", "tea", "config.yml")
+}
+
+// expandHome 展開路徑開頭的 ~。
+func expandHome(p string) string {
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			return filepath.Join(home, strings.TrimPrefix(p, "~"))
+		}
+	}
+	return p
+}
+
+// runLogin 是 teai login 的進入點：分派子命令。
+func runLogin(env *Env, args []string) error {
+	if len(args) == 0 {
+		return &ErrUsage{Msg: "login requires a subcommand: list, add, default, remove"}
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runLoginList(env, rest)
+	case "add":
+		return runLoginAdd(env, rest)
+	case "default":
+		return runLoginDefault(env, rest)
+	case "remove":
+		return runLoginRemove(env, rest)
+	default:
+		return &ErrUsage{Msg: fmt.Sprintf("unknown login subcommand %q (want list, add, default, remove)", sub)}
+	}
+}
+
+// loginFields 是輸出欄位（不含 token）。
+var loginFields = []gitea.Field{
+	{Name: "name"},
+	{Name: "url"},
+	{Name: "user"},
+	{Name: "default"},
+}
+
+// printLoginList 依格式輸出登入清單。
+func printLoginList(env *Env, logins []gitea.LoginEntry) error {
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	rows := make([]gitea.Values, 0, len(logins))
+	for _, l := range logins {
+		rows = append(rows, gitea.Values{l.Name, l.URL, l.User, l.Default})
+	}
+	return p.PrintList(loginFields, rows)
+}
+
+// runLoginList 列出組態中的登入（一律不含 token）。
+func runLoginList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() > 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("unexpected argument %q", fs.Arg(0))}
+	}
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	logins, err := gitea.ListLoginsFile(path)
+	if err != nil {
+		return fmt.Errorf("read config %s: %w", path, err)
+	}
+	return printLoginList(env, logins)
+}
+
+// runLoginAdd 新增或更新登入：先驗證 token（GET /user），成功才寫入。
+//
+// token 來源：--token 旗標，或 stdin（預設未給旗標時讀一行，
+// 避免 token 進 shell 歷史）。
+func runLoginAdd(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login add", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	urlFlag := fs.String("url", env.Globals.URL, "Gitea 站點網址")
+	nameFlag := fs.String("name", "", "登入名稱（省略時取 URL 主機）")
+	tokenFlag := fs.String("token", "", "API token（省略時自 stdin 讀一行）")
+	defaultFlag := fs.Bool("default", true, "設為預設登入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() > 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("unexpected argument %q", fs.Arg(0))}
+	}
+	siteURL := strings.TrimSuffix(strings.TrimSpace(*urlFlag), "/")
+	if siteURL == "" {
+		return &ErrUsage{Msg: "--url must not be empty"}
+	}
+
+	token := strings.TrimSpace(*tokenFlag)
+	if token == "" {
+		t, err := readLineFrom(loginStdin)
+		if err != nil {
+			return fmt.Errorf("read token from stdin: %w", err)
+		}
+		token = t
+	}
+	if token == "" {
+		return &ErrUsage{Msg: "token must not be empty"}
+	}
+
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	data, err := os.ReadFile(path)
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("read config %s: %w", path, err)
+	}
+
+	name := strings.TrimSpace(*nameFlag)
+	if name == "" {
+		// 未指定名稱：同站（主機相同）已有登入就就地更新，避免重複項目。
+		if existing, ok := findLoginByHost(data, siteURL); ok {
+			name = existing.Name
+		} else {
+			name = defaultLoginName(siteURL)
+		}
+	}
+
+	// 先驗證再寫入：token 無效時不動組態檔。
+	user, err := verifyToken(env, siteURL, token)
+	if err != nil {
+		return err
+	}
+	out, final, err := gitea.UpsertLogin(data, gitea.LoginEntry{
+		Name:    name,
+		URL:     siteURL,
+		Token:   token,
+		Default: *defaultFlag,
+		User:    user,
+	}, *defaultFlag)
+	if err != nil {
+		return err
+	}
+	if err := gitea.SaveTeaConfigFile(path, out); err != nil {
+		return err
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{final.Name, final.URL, final.User, final.Default})
+}
+
+// readLineFrom 讀一行並去除頭尾空白；EOF 且無內容回空字串。
+func readLineFrom(r io.Reader) (string, error) {
+	line, err := bufio.NewReader(r).ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}
+
+// verifyToken 以 token 呼叫 GET /user，回傳帳號名稱。
+// 401 特別標明是 token 遭拒，其餘依 *gitea.ErrAPI 對應結束碼 3。
+func verifyToken(env *Env, siteURL, token string) (string, error) {
+	c, err := gitea.New(siteURL, token, env.Globals.Timeout)
+	if err != nil {
+		return "", &ErrUsage{Msg: err.Error()}
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), env.Globals.Timeout)
+	defer cancel()
+	var out struct {
+		Login string `json:"login"`
+	}
+	if err := c.GetJSON(ctx, "/user", &out); err != nil {
+		var api *gitea.ErrAPI
+		if errors.As(err, &api) && api.StatusCode == 401 {
+			// 包 %w 保留 *ErrAPI：結束碼對應 3（API 錯誤）。
+			return "", fmt.Errorf("token rejected by %s: %w", siteURL, api)
+		}
+		return "", err
+	}
+	if out.Login == "" {
+		return "", fmt.Errorf("empty account name returned by %s", siteURL)
+	}
+	return out.Login, nil
+}
+
+// runLoginDefault 設定預設登入。
+func runLoginDefault(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login default", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "login default requires exactly one login name"}
+	}
+	name := fs.Arg(0)
+	data, err := readLoginConfig(env, "login default")
+	if err != nil {
+		return err
+	}
+	entry, found := findLogin(data, name)
+	if !found {
+		return fmt.Errorf("gitea: login %q not found", name)
+	}
+	out, err := gitea.SetDefaultLogin(data, name)
+	if err != nil {
+		return err
+	}
+	if err := saveLoginConfig(env, out); err != nil {
+		return err
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{entry.Name, entry.URL, entry.User, true})
+}
+
+// runLoginRemove 移除登入；未加 --yes 時先確認。
+func runLoginRemove(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login remove", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	yesFlag := fs.Bool("yes", false, "跳過確認")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "login remove requires exactly one login name"}
+	}
+	name := fs.Arg(0)
+	data, err := readLoginConfig(env, "login remove")
+	if err != nil {
+		return err
+	}
+	entry, found := findLogin(data, name)
+	if !found {
+		return fmt.Errorf("gitea: login %q not found", name)
+	}
+	if !*yesFlag {
+		confirmed, err := confirmRemove(env, entry)
+		if err != nil {
+			return err
+		}
+		if !confirmed {
+			fmt.Fprintln(env.Out, "cancelled")
+			return nil
+		}
+	}
+	out, promoted, err := gitea.RemoveLogin(data, name)
+	if err != nil {
+		return err
+	}
+	if err := saveLoginConfig(env, out); err != nil {
+		return err
+	}
+	if promoted != "" {
+		fmt.Fprintf(env.Err, "default login is now %q\n", promoted)
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{entry.Name, entry.URL, entry.User, false})
+}
+
+// confirmRemove 印出待移除項目（不含 token）並讀 y/yes 確認；
+// 其他輸入（含 EOF）一律視為取消。
+func confirmRemove(env *Env, entry gitea.LoginEntry) (bool, error) {
+	fmt.Fprintf(env.Err, "remove login %q (url %s, user %s)? [y/N] ", entry.Name, entry.URL, entry.User)
+	line, err := readLineFrom(loginStdin)
+	if err != nil {
+		return false, fmt.Errorf("read confirmation: %w", err)
+	}
+	switch strings.ToLower(line) {
+	case "y", "yes":
+		return true, nil
+	default:
+		return false, nil
+	}
+}
+
+// readLoginConfig 讀組態檔內容；路徑無法判定或讀取失敗時回錯。
+func readLoginConfig(env *Env, op string) ([]byte, error) {
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return nil, fmt.Errorf("cannot determine config path")
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("%s: read config %s: %w", op, path, err)
+	}
+	return data, nil
+}
+
+// saveLoginConfig 原子寫回組態檔。
+func saveLoginConfig(env *Env, data []byte) error {
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	return gitea.SaveTeaConfigFile(path, data)
+}
+
+// findLoginByHost 在組態內容中找 URL 主機與 siteURL 相同的登入。
+func findLoginByHost(data []byte, siteURL string) (gitea.LoginEntry, bool) {
+	for _, l := range gitea.ListLogins(data) {
+		if gitea.HostOf(l.URL) == gitea.HostOf(siteURL) {
+			return l, true
+		}
+	}
+	return gitea.LoginEntry{}, false
+}
+
+// findLogin 在組態內容中找指定名稱的登入。
+func findLogin(data []byte, name string) (gitea.LoginEntry, bool) {
+	for _, l := range gitea.ListLogins(data) {
+		if l.Name == name {
+			return l, true
+		}
+	}
+	return gitea.LoginEntry{}, false
+}
+
+// defaultLoginName 以 URL 主機作為登入名稱（同 tea 的習慣）。
+func defaultLoginName(rawURL string) string {
+	s := rawURL
+	if !strings.Contains(s, "://") {
+		s = "https://" + s
+	}
+	if u, err := url.Parse(s); err == nil && u.Host != "" {
+		return u.Host
+	}
+	return rawURL
+}
@@ -0,0 +1,292 @@
+// login_test.go 驗證 login 指令：list/add/default/remove 的輸出、
+// 驗證流程（先 GET /user 再寫入）、401 不寫檔、token 不外洩。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// loginTestEnv 建立測試環境：臨時組態檔路徑 + 可替換的 stdin。
+func loginTestEnv(t *testing.T, configContent string) (args []string, configPath string) {
+	t.Helper()
+	dir := t.TempDir()
+	configPath = filepath.Join(dir, "config.yml")
+	if configContent != "" {
+		if err := os.WriteFile(configPath, []byte(configContent), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("TEA_CONFIG", configPath)
+	return []string{"--config", configPath}, configPath
+}
+
+// newAPIServer 建立假的 Gitea API：/user 檢查 Authorization。
+func newAPIServer(t *testing.T, wantToken string, status int) (*httptest.Server, *atomic.Value) {
+	t.Helper()
+	var gotAuth atomic.Value
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth.Store(r.Header.Get("Authorization"))
+		if r.URL.Path != "/api/v1/user" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		if status != 0 {
+			w.WriteHeader(status)
+			return
+		}
+		fmt.Fprint(w, `{"login":"ceo"}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv, &gotAuth
+}
+
+func TestLoginListJSONNoToken(t *testing.T) {
+	prefix, _ := loginTestEnv(t, `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: super-secret
+      default: true
+      user: ceo
+`)
+	stdout, _, code := run(append(prefix, "login", "list")...)
+	if code != 0 {
+		t.Fatalf("code = %d", code)
+	}
+	if !strings.Contains(stdout, `"name":"alterminal"`) || !strings.Contains(stdout, `"user":"ceo"`) {
+		t.Fatalf("unexpected output: %s", stdout)
+	}
+	if strings.Contains(stdout, "super-secret") || strings.Contains(stdout, "token") {
+		t.Fatalf("token leaked: %s", stdout)
+	}
+}
+
+func TestLoginListEmpty(t *testing.T) {
+	prefix, path := loginTestEnv(t, "")
+	if _, err := os.Stat(path); err == nil {
+		t.Fatal("precondition: config should not exist")
+	}
+	stdout, _, code := run(append(prefix, "login", "list")...)
+	if code != 0 {
+		t.Fatalf("code = %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("want [], got %q", stdout)
+	}
+}
+
+func TestLoginAddVerifiesThenWrites(t *testing.T) {
+	srv, gotAuth := newAPIServer(t, "tok-xyz", 0)
+	prefix, configPath := loginTestEnv(t, "")
+	stdout, _, code := run(append(prefix,
+		"--url", srv.URL, "login", "add", "--name", "test-site", "--token", "tok-xyz")...)
+	if code != 0 {
+		t.Fatalf("code = %d, stdout = %s", code, stdout)
+	}
+	if got := gotAuth.Load(); got != "token tok-xyz" {
+		t.Fatalf("server saw Authorization %v", got)
+	}
+	if !strings.Contains(stdout, `"name":"test-site"`) || !strings.Contains(stdout, `"user":"ceo"`) {
+		t.Fatalf("unexpected output: %s", stdout)
+	}
+	if strings.Contains(stdout, "tok-xyz") {
+		t.Fatalf("token leaked: %s", stdout)
+	}
+	// 寫入的組態可被解析，且欄位齊全。
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := gitea.ListLogins(data)
+	if len(logins) != 1 {
+		t.Fatalf("want 1 login, got %d:\n%s", len(logins), data)
+	}
+	l := logins[0]
+	if l.Name != "test-site" || l.URL != srv.URL || l.Token != "tok-xyz" || !l.Default || l.User != "ceo" {
+		t.Fatalf("entry mismatch: %+v", l)
+	}
+	info, _ := os.Stat(configPath)
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("perm = %v", info.Mode().Perm())
+	}
+}
+
+func TestLoginAddTokenFromStdin(t *testing.T) {
+	srv, _ := newAPIServer(t, "stdin-tok", 0)
+	prefix, configPath := loginTestEnv(t, "")
+	old := loginStdin
+	loginStdin = strings.NewReader("stdin-tok\n")
+	defer func() { loginStdin = old }()
+	stdout, _, code := run(append(prefix, "--url", srv.URL, "login", "add")...)
+	if code != 0 {
+		t.Fatalf("code = %d, stdout = %s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Token != "stdin-tok" {
+		t.Fatalf("stdin token not saved:\n%s", data)
+	}
+}
+
+func TestLoginAddRejected401NoWrite(t *testing.T) {
+	srv, _ := newAPIServer(t, "", http.StatusUnauthorized)
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: keep
+      url: https://keep.example.com
+      token: keep-tok
+      default: true
+`)
+	_, stderr, code := run(append(prefix,
+		"--url", srv.URL, "login", "add", "--token", "bad-tok")...)
+	// 401 是 API 錯誤；對照 README「輸出與結束碼」＝3（#10）。
+	if code != 3 {
+		t.Fatalf("401 should exit 3 (README api error), got %d (stderr %s)", code, stderr)
+	}
+	if !strings.Contains(stderr, "401") {
+		t.Fatalf("stderr should mention 401: %s", stderr)
+	}
+	// 組態不受影響。
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Token != "keep-tok" {
+		t.Fatalf("config must be untouched:\n%s", data)
+	}
+}
+
+func TestLoginAddUpdatesExistingInPlace(t *testing.T) {
+	srv, _ := newAPIServer(t, "new-tok", 0)
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: alterminal
+      url: `+srv.URL+`
+      token: old-tok
+      default: true
+      user: someone-else
+      ssh_key: "keep-me"
+preferences:
+    editor: false
+`)
+	stdout, _, code := run(append(prefix, "--url", srv.URL, "login", "add", "--token", "new-tok")...)
+	if code != 0 {
+		t.Fatalf("code = %d, out = %s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	s := string(data)
+	// 未給 --name：同站既有項目（name: alterminal）就地更新，不新增重複項目。
+	if strings.Contains(stdout, `"name":"127.0.0.1:`) {
+		t.Fatalf("should reuse existing entry name, got %s", stdout)
+	}
+	if !strings.Contains(s, "- name: alterminal") {
+		t.Fatalf("existing entry name lost:\n%s", s)
+	}
+	if strings.Contains(s, "old-tok") || !strings.Contains(s, "token: new-tok") {
+		t.Fatalf("token not replaced:\n%s", s)
+	}
+	if !strings.Contains(s, `ssh_key: "keep-me"`) || !strings.Contains(s, "editor: false") {
+		t.Fatalf("unrelated content lost:\n%s", s)
+	}
+	if !strings.Contains(s, "user: ceo") {
+		t.Fatalf("user not refreshed:\n%s", s)
+	}
+}
+
+func TestLoginDefaultAndRemove(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	prefix, configPath := loginTestEnv(t, cfg)
+	stdout, _, code := run(append(prefix, "login", "default", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("default failed: code=%d out=%s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); !l[1].Default || l[0].Default {
+		t.Fatalf("default not switched:\n%s", data)
+	}
+
+	// remove --yes：移除預設者 b，a 遞補。
+	stdout, _, code = run(append(prefix, "login", "remove", "--yes", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("remove failed: code=%d out=%s", code, stdout)
+	}
+	data, _ = os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Name != "a" || !l[0].Default {
+		t.Fatalf("promote failed:\n%s", data)
+	}
+}
+
+func TestLoginRemoveAsksConfirmation(t *testing.T) {
+	prefix, _ := loginTestEnv(t, `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+`)
+	old := loginStdin
+	loginStdin = strings.NewReader("n\n")
+	defer func() { loginStdin = old }()
+	_, _, code := run(append(prefix, "login", "remove", "a")...)
+	if code != 0 {
+		t.Fatalf("cancel should still exit 0, got %d", code)
+	}
+	// 取消：檔案不變（token 仍在）。
+	data, _ := os.ReadFile(filepath.Dir(prefix[1]) + "/config.yml")
+	if !strings.Contains(string(data), "token: ta") {
+		t.Fatalf("cancelled remove must not write:\n%s", data)
+	}
+}
+
+func TestLoginUnknownSubcommandUsage(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "")
+	_, stderr, code := run(append(prefix, "login", "bogus")...)
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 {
+		t.Fatalf("want exit 2 (README usage), got %d", code)
+	}
+	if !strings.Contains(stderr, "unknown login subcommand") {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginNoSubcommandUsage(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "")
+	_, stderr, code := run(append(prefix, "login")...)
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 {
+		t.Fatalf("want exit 2 (README usage), got %d", code)
+	}
+	if !strings.Contains(stderr, "subcommand") {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginRemoveNotFound(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "logins: []\n")
+	_, stderr, code := run(append(prefix, "login", "remove", "--yes", "ghost")...)
+	// ExitInternal 不在 README 保證範圍；此處固定為 1（內部錯誤，#10）。
+	if code != 1 {
+		t.Fatalf("want exit 1 (internal), got %d", code)
+	}
+	if !strings.Contains(stderr, `login "ghost" not found`) {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginRegisteredInUsage(t *testing.T) {
+	stdout, _, code := run()
+	if code != 0 || !strings.Contains(stdout, "login") {
+		t.Fatalf("usage should list login: %s", stdout)
+	}
+}
@@ -0,0 +1,97 @@
+// milestones_commands.go — 跨倉庫里程碑總覽命令的 CLI 接線（#31）：
+// teai milestones（不帶 --repo）。
+//
+// 核心邏輯在 internal/workflow（MilestoneOverview），本檔只做旗標
+// 剖析、資料源接線與輸出格式化（與 stalled_commands.go 同模式）。
+// 輸出與 gitea.py milestones 位元組相容（MilestoneEntry 自訂
+// MarshalJSON；縮排 2、停用 HTML 轉義、空清單輸出 []，見 #26 慣例）。
+package cli
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// newMilestoneSourceFunc 建立總覽的資料源；宣告為變數讓接線層測試
+// 可注入假資料源（與 newStalledSourceFunc 同模式）。
+var newMilestoneSourceFunc = newMilestoneSource
+
+// newMilestoneSource 依全域選項建立 workflow.MilestoneSource（API 實作）。
+func newMilestoneSource(env *Env) (workflow.MilestoneSource, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &workflow.APIClient{Client: client}, nil
+}
+
+// milestonesNowFunc 回傳總覽的基準時刻；宣告為變數讓測試可固定時刻。
+var milestonesNowFunc = time.Now
+
+// milestoneEntryRow 把 MilestoneEntry 轉成 table 列（unassigned 僅 JSON
+// 模式輸出完整摘要；table 給人工抽查用，取計數）。
+func milestoneEntryRow(e workflow.MilestoneEntry) gitea.Values {
+	dueOn := ""
+	if e.DueOn != nil {
+		dueOn = *e.DueOn
+	}
+	dueHours := ""
+	if e.DueHours != nil {
+		dueHours = fmt.Sprintf("%.1f", *e.DueHours)
+	}
+	updatedAt := ""
+	if e.UpdatedAt != nil {
+		updatedAt = *e.UpdatedAt
+	}
+	id := ""
+	if e.ID != nil {
+		id = fmt.Sprintf("%d", *e.ID)
+	}
+	return gitea.Values{
+		e.Repo, id, e.Title, e.URL,
+		e.OpenIssues, e.ClosedIssues, dueOn, dueHours,
+		e.Overdue, len(e.Unassigned), updatedAt,
+	}
+}
+
+// runMilestonesOverview：teai milestones（跨倉庫總覽）。
+// JSON 輸出與 gitea.py milestones 位元組相容；空清單輸出 []（#26 慣例：
+// gitea.py 對空清單不輸出，teai 輸出 [] 供 JSON 消費者明確判斷）。
+func runMilestonesOverview(env *Env) error {
+	src, err := newMilestoneSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	entries, err := workflow.MilestoneOverview(src, env.Globals.URL, milestonesNowFunc())
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	if p.Format == gitea.FormatTable {
+		rows := make([]gitea.Values, 0, len(entries))
+		for i := range entries {
+			rows = append(rows, milestoneEntryRow(entries[i]))
+		}
+		return p.PrintList([]gitea.Field{
+			{Name: "repo"}, {Name: "id"}, {Name: "title"}, {Name: "url"},
+			{Name: "open_issues"}, {Name: "closed_issues"}, {Name: "due_on"},
+			{Name: "due_hours"}, {Name: "overdue"}, {Name: "unassigned"}, {Name: "updated_at"},
+		}, rows)
+	}
+	if len(entries) == 0 {
+		_, err := fmt.Fprintln(env.Out, "[]")
+		return err
+	}
+	return printJSON(env.Out, entries)
+}
@@ -0,0 +1,188 @@
+// milestones_commands_test.go — 跨倉庫里程碑總覽的 CLI 接線層測試（#31）：
+// 注入假 MilestoneSource，驗證 Run→dispatch→輸出完整路徑，不走網路
+// （與 stalled_commands_test.go 同模式）。
+package cli
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// stubMilestoneSource 以記憶體資料實作 workflow.MilestoneSource。
+type stubMilestoneSource struct {
+	orgs       []string
+	repos      map[string][]workflow.Repo
+	milestones map[string][]workflow.Milestone
+	openIssues map[string][]workflow.Issue // key: owner/repo?milestone=<title>
+}
+
+func (s *stubMilestoneSource) MyOrganizations() ([]string, error) { return s.orgs, nil }
+func (s *stubMilestoneSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+	return s.repos[org], nil
+}
+func (s *stubMilestoneSource) OpenMilestones(owner, repo string) ([]workflow.Milestone, error) {
+	return s.milestones[owner+"/"+repo], nil
+}
+func (s *stubMilestoneSource) MilestoneOpenIssues(owner, repo, title string) ([]workflow.Issue, error) {
+	return s.openIssues[owner+"/"+repo+"?milestone="+title], nil
+}
+
+// newStubMilestoneEnv 注入假資料源並固定時刻。
+func newStubMilestoneEnv(t *testing.T, src *stubMilestoneSource, frozen time.Time) {
+	t.Helper()
+	origSrc, origNow := newMilestoneSourceFunc, milestonesNowFunc
+	newMilestoneSourceFunc = func(env *Env) (workflow.MilestoneSource, error) { return src, nil }
+	milestonesNowFunc = func() time.Time { return frozen }
+	t.Cleanup(func() {
+		newMilestoneSourceFunc, milestonesNowFunc = origSrc, origNow
+	})
+}
+
+// stubPullIssue 以 JSON 建構帶 pull_request 標記的條目（pullMarker 未匯出，
+// 測試從套件外以 API 回應的形狀建構，走 Issue.UnmarshalJSON 同一路徑）。
+func stubPullIssue(t *testing.T) workflow.Issue {
+	t.Helper()
+	var issue workflow.Issue
+	err := json.Unmarshal([]byte(`{
+		"number": 32, "title": "文件", "state": "open",
+		"updated_at": "2026-09-08T00:00:00Z",
+		"html_url": "https://gitea.alterminal.com/alterminal/agents/pulls/32",
+		"user": {"username": "alex"},
+		"pull_request": {}
+	}`), &issue)
+	if err != nil {
+		t.Fatalf("建構 stub PR 條目失敗：%v", err)
+	}
+	return issue
+}
+
+// idPtr／msPtr 是測試用指標 helper（workflow 套件內同名函式未匯出）。
+func idPtr(i int64) *int64   { return &i }
+func msPtr(s string) *string { return &s }
+
+// newStubMilestoneData 建構總覽情境：兩倉庫各一里程碑、一個未分派 PR。
+func newStubMilestoneData(t *testing.T) *stubMilestoneSource {
+	due := "2026-09-09T00:00:00Z"
+	return &stubMilestoneSource{
+		orgs: []string{"alterminal"},
+		repos: map[string][]workflow.Repo{"alterminal": {
+			{Name: "agents"}, {Name: "teai"},
+		}},
+		milestones: map[string][]workflow.Milestone{
+			"alterminal/agents": {
+				{ID: idPtr(7), Title: "MVP", State: "open",
+					DueOn: &due, UpdatedAt: "2026-09-01T00:00:00Z",
+					OpenIssues: 1, ClosedIssues: 0},
+			},
+			"alterminal/teai": {
+				{ID: idPtr(3), Title: "CLI", State: "open",
+					DueOn: msPtr("2026-09-12T00:00:00Z"), UpdatedAt: "2026-09-05T00:00:00Z",
+					OpenIssues: 1, ClosedIssues: 2},
+			},
+		},
+		openIssues: map[string][]workflow.Issue{
+			"alterminal/agents?milestone=MVP": {stubPullIssue(t)},
+		},
+	}
+}
+
+// TestWiringMilestonesOverview 驗證 teai milestones 輸出跨倉庫總覽
+// （JSON 縮排 2、鍵序與欄位齊 gitea.py）。
+func TestWiringMilestonesOverview(t *testing.T) {
+	newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("milestones")
+	if code != 0 {
+		t.Fatalf("milestones 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	for _, want := range []string{
+		`"repo": "alterminal/agents"`,
+		`"title": "MVP"`,
+		`"overdue": true`,
+		`"type": "pull"`,
+		`"author": "alex"`,
+	} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("milestones 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+	// 排序：agents MVP（09-09）在 teai CLI（09-12）前。
+	if strings.Index(stdout, `"title": "MVP"`) > strings.Index(stdout, `"title": "CLI"`) {
+		t.Fatalf("期限近者應在前：\n%s", stdout)
+	}
+}
+
+// TestWiringMilestonesEmpty 驗證無里程碑 → []（#26 慣例）。
+func TestWiringMilestonesEmpty(t *testing.T) {
+	newStubMilestoneEnv(t, &stubMilestoneSource{
+		orgs:       []string{"alterminal"},
+		repos:      map[string][]workflow.Repo{"alterminal": {{Name: "agents"}}},
+		milestones: map[string][]workflow.Milestone{},
+		openIssues: map[string][]workflow.Issue{},
+	}, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("milestones")
+	if code != 0 {
+		t.Fatalf("milestones 空清單應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無里程碑應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringMilestonesTable 驗證 table 輸出（人工抽查用）。
+func TestWiringMilestonesTable(t *testing.T) {
+	newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("milestones", "--output", "table")
+	if code != 0 {
+		t.Fatalf("milestones --output table 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{"repo", "overdue", "MVP", "alterminal/agents"} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("table 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringMilestonesRepoFlagCompat 驗證 teai milestones --repo a/b
+// 維持現行單倉庫 list 語義（#31：帶 --repo 時不變）。
+func TestWiringMilestonesRepoFlagCompat(t *testing.T) {
+	var gotPath, gotQuery string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath, gotQuery = r.URL.Path, r.URL.RawQuery
+		w.Write([]byte(`[{"title":"v1","state":"open","description":"","due_on":""}]`))
+	}))
+	t.Cleanup(srv.Close)
+	stdout, _, code := run("--url", srv.URL, "milestones", "--repo", "a/b")
+	if code != 0 {
+		t.Fatalf("milestones --repo a/b 應回 0，得到 %d", code)
+	}
+	if gotPath != "/api/v1/repos/a/b/milestones" {
+		t.Fatalf("應呼叫 /repos/a/b/milestones，得到 %s", gotPath)
+	}
+	if !strings.Contains(gotQuery, "state=open") {
+		t.Fatalf("查詢應含 state=open，得到 %q", gotQuery)
+	}
+	if !strings.Contains(stdout, `"title":"v1"`) {
+		t.Fatalf("輸出應含 title v1，得到：%s", stdout)
+	}
+}
+
+// TestWiringMilestonesUsage 驗證未知子命令與位置參數 → exit 2。
+func TestWiringMilestonesUsage(t *testing.T) {
+	newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	if _, _, code := run("milestones", "bogus"); code != int(ExitUsage) {
+		t.Fatalf("milestones bogus 應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("milestones", "extra", "arg"); code != int(ExitUsage) {
+		t.Fatalf("milestones 位置參數應回 ExitUsage，得到 %d", code)
+	}
+	// milestones list 仍照舊要求 --repo。
+	if _, _, code := run("milestones", "list"); code != int(ExitUsage) {
+		t.Fatalf("milestones list 缺 --repo 應回 ExitUsage，得到 %d", code)
+	}
+}
@@ -0,0 +1,170 @@
+// stalled_commands.go — 管理者巡邏命令的 CLI 接線（#7）：
+// stalled [--hours N] 與 xrefs <owner>/<repo> <number>。
+//
+// 核心邏輯在 internal/workflow（ScanStalled／ResolveIssueXrefs），
+// 本檔只做旗標剖析、資料源接線與輸出格式化。輸出走得體架構的
+// Printer（--output json|table）；錯誤經 cli.exitCodeFor 映射結束碼
+// （用法 2／API 3）。token 解析選序見 internal/gitea/auth.go。
+package cli
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"strconv"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+func init() {
+	commands["stalled"] = &command{
+		name:  "stalled",
+		usage: "停滯的 open issues／PR（管理者巡邏；--hours N 門檻，預設 4）",
+		run:   runStalled,
+	}
+	commands["xrefs"] = &command{
+		name:  "xrefs",
+		usage: "解析 issue／PR 內文與留言中的 #N／repo#N／owner/repo#N 引用",
+		run:   runXrefs,
+	}
+}
+
+// newStalledSourceFunc 建立 stalled／xrefs 的資料源；宣告為變數讓
+// 接線層測試可注入假資料源（不走網路），與 newScannerFunc 同模式。
+var newStalledSourceFunc = newStalledSource
+
+// newStalledSource 依全域選項建立 workflow.StalledSource（API 實作）。
+func newStalledSource(env *Env) (workflow.StalledSource, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &workflow.APIClient{Client: client}, nil
+}
+
+// stalledFields 是 stalled 的 table 欄位（JSON 模式輸出完整 Item，
+// 欄位序與 gitea.py 一致，見 workflow.Item.MarshalJSON）。
+func stalledFields() []gitea.Field {
+	return []gitea.Field{
+		{Name: "type"}, {Name: "repo"}, {Name: "number"}, {Name: "title"},
+		{Name: "last_comment_by"}, {Name: "last_activity_at"},
+		{Name: "stalled_hours"}, {Name: "reason"},
+	}
+}
+
+// stalledRow 把 Item 轉成 table 列（assignees／reviewers／child_activity
+// 僅 JSON 模式輸出；table 給人工抽查用，取共同欄位）。
+// stalled_hours 定點一位小數（fmt.Sprint(9.0) 會印 "9"，與 JSON 的 9.0 不一致）。
+func stalledRow(item workflow.Item) gitea.Values {
+	return gitea.Values{
+		item.Type, item.Repo, item.Number, item.Title,
+		item.LastCommentBy, workflow.FormatMoment(item.LastActivityAt),
+		strconv.FormatFloat(item.StalledHours, 'f', 1, 64), item.Reason,
+	}
+}
+
+// runStalled：teai stalled [--hours N]。
+// 預設門檻 4 小時；--hours 需為正數（同 gitea.py _parse_hours）。
+// JSON 輸出與 gitea.py stalled 位元組相容（workflow.Item 自訂 MarshalJSON；
+// 這裡輸出前停用 HTML 轉義並縮排 2，對應 Python json.dumps(indent=2)）。
+func runStalled(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai stalled", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	hours := fs.Float64("hours", workflow.StalledDefaultHours, "停滯門檻（小時，正數）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "stalled 不接受位置參數"}
+	}
+	if *hours <= 0 {
+		return &ErrUsage{Msg: "--hours 需為正數（小時），例如 --hours 4"}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	items, err := workflow.RunStalled(src, *hours, nowFunc())
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	if p.Format == gitea.FormatTable {
+		rows := make([]gitea.Values, 0, len(items))
+		for _, item := range items {
+			rows = append(rows, stalledRow(item))
+		}
+		return p.PrintList(stalledFields(), rows)
+	}
+	// JSON：空清單輸出 []（README：無停滯項目 → 空陣列）；有項目時
+	// 縮排 2 且停用 HTML 轉義，與 gitea.py 的 _dump 位元組相容。
+	if len(items) == 0 {
+		_, err := fmt.Fprintln(env.Out, "[]")
+		return err
+	}
+	return printJSON(env.Out, items)
+}
+
+// runXrefs：teai xrefs <owner>/<repo> <number>。
+// 編號不存在 → API 錯誤（結束碼 3）；無引用 → []。
+func runXrefs(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai xrefs", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 2 {
+		return &ErrUsage{Msg: "xrefs 需要 <owner>/<repo> <number> 兩個參數"}
+	}
+	owner, name, err := splitRepoFlag(args[0])
+	if err != nil {
+		return err
+	}
+	number, err := strconv.ParseInt(args[1], 10, 64)
+	if err != nil || number <= 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("編號需為正整數，得到 %q", args[1])}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	hits, err := workflow.ResolveIssueXrefs(src, owner, name, number)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(hits))
+	for _, h := range hits {
+		rows = append(rows, gitea.Values{h.Owner, h.Repo, h.Number, h.Source})
+	}
+	return p.PrintList(
+		[]gitea.Field{
+			{Name: "owner"}, {Name: "repo"}, {Name: "number"}, {Name: "source"},
+		},
+		rows,
+	)
+}
+
+// nowFunc 回傳目前時刻；宣告為變數讓測試可固定時刻（stalled 判定用）。
+var nowFunc = time.Now
+
+// printJSON 以縮排 2、停用 HTML 轉義輸出 JSON（與 gitea.py 的
+// json.dumps(ensure_ascii=False, indent=2) 位元組相容；HTML 轉義會把
+// <、>、& 變 \u003c 等，破壞相容性）。
+func printJSON(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	return enc.Encode(v)
+}
@@ -0,0 +1,248 @@
+// stalled_commands_test.go — stalled／xrefs CLI 接線層測試（#7）：
+// 注入假 StalledSource，驗證 Run→dispatch→flagset 完整路徑，
+// 不走網路（與 workflow_commands_test.go 同模式）。
+package cli
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// stubStalledSource 以記憶體資料實作 workflow.StalledSource。
+type stubStalledSource struct {
+	username string
+	orgs     []string
+	repos    map[string][]workflow.Repo
+	issues   map[string]map[int64]workflow.Issue
+	comments map[string][]workflow.Comment
+	getErr   error
+}
+
+func (s *stubStalledSource) CurrentUser() (string, error) { return s.username, nil }
+func (s *stubStalledSource) MyOrganizations() ([]string, error) {
+	return s.orgs, nil
+}
+func (s *stubStalledSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+	return s.repos[org], nil
+}
+func (s *stubStalledSource) OpenIssues(owner, repo string) ([]workflow.Issue, error) {
+	var out []workflow.Issue
+	for _, i := range s.issues[owner+"/"+repo] {
+		out = append(out, i)
+	}
+	return out, nil
+}
+func (s *stubStalledSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error) {
+	return nil, nil
+}
+func (s *stubStalledSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
+	return s.comments[owner+"/"+repo+"/"+itoa(number)], nil
+}
+func (s *stubStalledSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
+	i, ok := s.issues[owner+"/"+repo][number]
+	return i, ok, nil
+}
+func (s *stubStalledSource) IssueTimeline(owner, repo string, number int64) ([]workflow.TimelineEvent, error) {
+	return nil, nil
+}
+func (s *stubStalledSource) GetIssue(owner, repo string, number int64) (workflow.Issue, error) {
+	if s.getErr != nil {
+		return workflow.Issue{}, s.getErr
+	}
+	i, ok := s.issues[owner+"/"+repo][number]
+	if !ok {
+		return workflow.Issue{}, &gitea.ErrAPI{Op: "GET /repos/" + owner + "/" + repo + "/issues/" + itoa(number), StatusCode: 404}
+	}
+	return i, nil
+}
+
+func itoa(n int64) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+// newStubStalledEnv 注入假資料源並固定時刻。
+func newStubStalledEnv(t *testing.T, src *stubStalledSource, frozen time.Time) {
+	t.Helper()
+	origSrc, origNow := newStalledSourceFunc, nowFunc
+	newStalledSourceFunc = func(env *Env) (workflow.StalledSource, error) { return src, nil }
+	nowFunc = func() time.Time { return frozen }
+	t.Cleanup(func() { newStalledSourceFunc, nowFunc = origSrc, origNow })
+}
+
+// isoAt 把相對分鐘轉成 ISO8601 字串（假資料用；錨點同 workflow 測試）。
+func isoAt(minutes int) string {
+	return workflow.FormatMoment(time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC).Add(time.Duration(minutes) * time.Minute))
+}
+
+// newStubStalledData 建構 stalled 情境：agents#1 停滯 10 小時（no-assignee）。
+func newStubStalledData() *stubStalledSource {
+	return &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {{Name: "agents"}}},
+		issues: map[string]map[int64]workflow.Issue{
+			"alterminal/agents": {
+				1: {Number: 1, Title: "停滯項", State: "open",
+					CreatedAt: isoAt(-600), UpdatedAt: isoAt(-600),
+					Repository: &workflow.Repository{FullName: "alterminal/agents"}},
+			},
+		},
+		comments: map[string][]workflow.Comment{},
+	}
+}
+
+// TestWiringStalled 驗證 stalled 基本路徑：JSON 輸出含停滯欄位。
+func TestWiringStalled(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled")
+	if code != 0 {
+		t.Fatalf("stalled 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	for _, want := range []string{`"type": "issue"`, `"reason": "no-assignee"`, `"stalled_hours": 10.0`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("stalled 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringStalledEmpty 驗證 stalled 無任何條目時輸出 []、exit 0（#37）。
+func TestWiringStalledEmpty(t *testing.T) {
+	newStubStalledEnv(t, &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {}},
+		issues:   map[string]map[int64]workflow.Issue{},
+		comments: map[string][]workflow.Comment{},
+	}, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled")
+	if code != 0 {
+		t.Fatalf("stalled 空情境應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("stalled 無條目應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringStalledHoursFlag 驗證 --hours 覆寫門檻與非正數被攔。
+func TestWiringStalledHoursFlag(t *testing.T) {
+	freeze := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	newStubStalledEnv(t, newStubStalledData(), freeze)
+	// 門檻 20h → 10h 停滯未過門檻 → 空陣列。
+	stdout, _, code := run("stalled", "--hours", "20")
+	if code != 0 {
+		t.Fatalf("stalled --hours 20 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無停滯項應輸出 []，得到 %q", stdout)
+	}
+	// 非正數 → exit 2。
+	_, stderr, code := run("stalled", "--hours", "-1")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled --hours -1 應回 ExitUsage(%d)，得到 %d（stderr=%q）", int(ExitUsage), code, stderr)
+	}
+	// 位置參數 → exit 2。
+	_, _, code = run("stalled", "extra")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled extra 應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	}
+}
+
+// TestWiringStalledTable 驗證 table 輸出（README 範例）。
+func TestWiringStalledTable(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled", "--output", "table")
+	if code != 0 {
+		t.Fatalf("stalled --output table 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{"reason", "no-assignee", "停滯項"} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("table 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefs 驗證 xrefs 解析輸出（含 body／comment 出處）。
+func TestWiringXrefs(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "父項", State: "open",
+		Body:       "子項：agents#2",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.issues["alterminal/agents"][2] = workflow.Issue{
+		Number: 2, Title: "子項", State: "open",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.comments["alterminal/agents/1"] = []workflow.Comment{
+		{Body: "看 agents#2", User: &workflow.User{UserName: "alex"}},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	// Printer JSON 為單行緊湊格式（無縮排）；命令清單類輸出一律如此。
+	for _, want := range []string{`"repo":"agents"`, `"number":2`, `"source":"body"`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("xrefs 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefsEmpty 驗證無引用 → []。
+func TestWiringXrefsEmpty(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "無引用", State: "open",
+		Body:       "沒有任何引用",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無引用應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringXrefsUsage 驗證參數不足／格式錯誤 → exit 2。
+func TestWiringXrefsUsage(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	if _, _, code := run("xrefs"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 無參數應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 缺編號應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "not-a-repo", "1"); code != int(ExitUsage) {
+		t.Fatalf("xrefs repo 格式錯誤應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents", "abc"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 編號非數字應回 ExitUsage，得到 %d", code)
+	}
+}
+
+// TestWiringXrefsNotFound 驗證 404 → exit 3（API 錯誤）。
+func TestWiringXrefsNotFound(t *testing.T) {
+	src := newStubStalledData()
+	src.getErr = &gitea.ErrAPI{Op: "GET /repos/alterminal/agents/issues/99", StatusCode: 404}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	_, stderr, code := run("xrefs", "alterminal/agents", "99")
+	if code != int(ExitAPI) {
+		t.Fatalf("xrefs 404 應回 ExitAPI(%d)，得到 %d（stderr=%q）", int(ExitAPI), code, stderr)
+	}
+}
@@ -0,0 +1,248 @@
+// workflow_commands.go — gitea.py 工作流命令的 CLI 接線（#6）：
+// whoami、orgs、members [--has-work]、mine、pulls [--mine|--reviewer] [--repo]、next。
+//
+// 輸出走 internal/gitea 的 Printer（--output json|table）；錯誤經 cli.exitCodeFor
+// 映射結束碼（用法 2／API 3）。token 解析選序見 internal/gitea/auth.go。
+package cli
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"strings"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+func init() {
+	register := func(c *command) {
+		commands[c.name] = c
+	}
+	register(&command{name: "whoami", usage: "目前帳號", run: runWhoami})
+	register(&command{name: "orgs", usage: "我所屬的組織", run: runOrgs})
+	register(&command{name: "members", usage: "Agents 團隊成員；--has-work 只列有未完成工作者", run: runMembers})
+	register(&command{name: "mine", usage: "分派給我、待跟進的 issues", run: runMine})
+	// pulls 由 dailyops_commands.go 註冊（#8）：無子命令時走本檔的 runPulls
+	// 工作流清單，有子命令（list/view/create/merge/comment）走日常操作。
+	register(&command{name: "next", usage: "下一件該做的事", run: runNext})
+}
+
+// errNoRepoFlag 是 --repo 值格式錯誤。
+var errNoRepoFlag = errors.New("--repo 需為 owner/repo 形式")
+
+// newScannerFunc 建立工作流 Scanner；正式環境用 API client。
+// 宣告為變數讓接線層測試可注入假 client（不走網路），
+// 彌補 workflow 套件單元測試覆蓋不到 CLI 分派路徑的缺口。
+var newScannerFunc = newWorkflowClient
+
+// newWorkflowClient 依全域選項建立 workflow 所需的 API client。
+func newWorkflowClient(env *Env) (*workflow.Scanner, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &workflow.Scanner{Client: &workflow.APIClient{Client: client}}, nil
+}
+
+// printer 依全域選項建立輸出器。
+func printer(env *Env) gitea.Printer {
+	return gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+}
+
+// runWhoami：teai whoami。
+func runWhoami(env *Env, args []string) error {
+	if len(args) != 0 {
+		return &ErrUsage{Msg: "whoami 不接受參數"}
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	name, err := s.Whoami()
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintOne(
+		[]gitea.Field{{Name: "username"}},
+		gitea.Values{name},
+	)
+}
+
+// runOrgs：teai orgs。
+func runOrgs(env *Env, args []string) error {
+	if len(args) != 0 {
+		return &ErrUsage{Msg: "orgs 不接受參數"}
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	orgs, err := s.Orgs()
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(orgs))
+	for _, o := range orgs {
+		rows = append(rows, gitea.Values{o})
+	}
+	return printer(env).PrintList(
+		[]gitea.Field{{Name: "username"}},
+		rows,
+	)
+}
+
+// runMembers：teai members [--has-work]。輸出每行一個帳號（同 gitea.py）。
+func runMembers(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai members", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	hasWork := fs.Bool("has-work", false, "只列出有未完成工作的成員")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "members 不接受位置參數"}
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	names, err := s.Members(*hasWork)
+	if err != nil {
+		return err
+	}
+	// gitea.py members 每行輸出一個帳號（非 JSON）；保持一致以便交叉驗證。
+	for _, name := range names {
+		fmt.Fprintln(env.Out, name)
+	}
+	return nil
+}
+
+// runMine：teai mine。
+func runMine(env *Env, args []string) error {
+	if len(args) != 0 {
+		return &ErrUsage{Msg: "mine 不接受參數"}
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	issues, err := s.Mine()
+	if err != nil {
+		return err
+	}
+	return printer(env).PrintList(
+		[]gitea.Field{
+			{Name: "repo"}, {Name: "number"}, {Name: "title"}, {Name: "url"},
+		},
+		issueRows(issues),
+	)
+}
+
+// runPulls：teai pulls [--mine|--reviewer] [--repo owner/repo]。
+func runPulls(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai pulls", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	mine := fs.Bool("mine", false, "限定作者是目前帳號")
+	reviewer := fs.Bool("reviewer", false, "限定自己是 requested reviewer")
+	repo := fs.String("repo", "", "限定單一倉庫（owner/repo）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "pulls 不接受位置參數"}
+	}
+	if *mine && *reviewer {
+		return &ErrUsage{Msg: "--mine 與 --reviewer 不能併用"}
+	}
+	var owner, name string
+	if *repo != "" {
+		parts := strings.SplitN(*repo, "/", 2)
+		if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+			return &ErrUsage{Msg: errNoRepoFlag.Error()}
+		}
+		owner, name = parts[0], parts[1]
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	items, err := s.Pulls(*mine, *reviewer)
+	if err != nil {
+		return err
+	}
+	rows := make([]gitea.Values, 0, len(items))
+	for _, item := range items {
+		if *repo != "" && (item.Owner != owner || item.Repo != name) {
+			continue
+		}
+		rows = append(rows, gitea.Values{
+			item.Owner + "/" + item.Repo,
+			item.Pull.Number,
+			item.Pull.Title,
+			item.Pull.WebURL(),
+		})
+	}
+	return printer(env).PrintList(
+		[]gitea.Field{
+			{Name: "repo"}, {Name: "number"}, {Name: "title"}, {Name: "url"},
+		},
+		rows,
+	)
+}
+
+// runNext：teai next。無工作輸出 null（exit 0）。
+func runNext(env *Env, args []string) error {
+	if len(args) != 0 {
+		return &ErrUsage{Msg: "next 不接受參數"}
+	}
+	s, err := newScannerFunc(env)
+	if err != nil {
+		return err
+	}
+	work, err := s.Next()
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	if work == nil {
+		return p.PrintNull()
+	}
+	// gitea.py 的 _work_dict：role 僅 pull 帶（issue 不輸出 role 欄位）。
+	fields := []gitea.Field{
+		{Name: "type"}, {Name: "role"}, {Name: "repo"},
+		{Name: "number"}, {Name: "title"}, {Name: "url"},
+	}
+	row := gitea.Values{work.Type, work.Role, work.Repo, work.Number, work.Title, work.URL}
+	if work.Role == "" {
+		fields = []gitea.Field{
+			{Name: "type"}, {Name: "repo"},
+			{Name: "number"}, {Name: "title"}, {Name: "url"},
+		}
+		row = gitea.Values{work.Type, work.Repo, work.Number, work.Title, work.URL}
+	}
+	return p.PrintOne(fields, row)
+}
+
+// issueRows 把 issues 轉成輸出列（repo 欄位由掃描脈絡補齊）。
+func issueRows(issues []workflow.Issue) []gitea.Values {
+	rows := make([]gitea.Values, 0, len(issues))
+	for i := range issues {
+		issue := &issues[i]
+		rows = append(rows, gitea.Values{
+			issue.FullName(),
+			issue.Num(),
+			issue.Title,
+			issue.WebURL(),
+		})
+	}
+	return rows
+}
@@ -0,0 +1,233 @@
+// workflow_commands_test.go — CLI 接線層測試：驗證 Run→dispatch→命令 flagset
+// 的完整路徑。ceo 於 PR #13 審核指出帶旗標命令（members --has-work、
+// pulls --mine/--reviewer）在 CLI 層全部 exit 2，workflow 單元測試覆蓋不到
+// 這條路徑——本檔以注入假 client 的方式補上，不走網路。
+package cli
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// stubClient 以記憶體資料實作 workflow.Client（最小集，僅供接線測試）。
+type stubClient struct {
+	currentUser string
+	orgs        []workflow.Org
+	teams       map[string][]workflow.Team
+	members     map[int64][]string
+	repos       map[string][]workflow.Repo
+	issues      map[string][]workflow.Issue
+	pulls       map[string][]workflow.PullRequest
+	comments    map[string][]workflow.Comment
+}
+
+func (c *stubClient) CurrentUser() (string, error) { return c.currentUser, nil }
+func (c *stubClient) ListOrgs() ([]string, error) {
+	out := make([]string, 0, len(c.orgs))
+	for _, o := range c.orgs {
+		out = append(out, o.Account())
+	}
+	return out, nil
+}
+func (c *stubClient) ListTeams(org string) ([]workflow.Team, error) {
+	return c.teams[org], nil
+}
+func (c *stubClient) ListTeamMembers(teamID int64) ([]string, error) {
+	return c.members[teamID], nil
+}
+func (c *stubClient) ListOrgRepos(org string) ([]workflow.Repo, error) {
+	return c.repos[org], nil
+}
+func (c *stubClient) ListIssues(owner, repo string) ([]workflow.Issue, error) {
+	return c.issues[owner+"/"+repo], nil
+}
+func (c *stubClient) ListPulls(owner, repo string) ([]workflow.PullRequest, error) {
+	return c.pulls[owner+"/"+repo], nil
+}
+func (c *stubClient) ListComments(owner, repo string, number int64) ([]workflow.Comment, error) {
+	return c.comments[owner+"/"+repo], nil
+}
+
+// newStubEnv 注入假 client，回傳還原函式（測試結束時呼叫）。
+func newStubEnv(t *testing.T, c *stubClient) {
+	t.Helper()
+	orig := newScannerFunc
+	newScannerFunc = func(env *Env) (*workflow.Scanner, error) {
+		return &workflow.Scanner{Client: c}, nil
+	}
+	t.Cleanup(func() { newScannerFunc = orig })
+}
+
+// newStubData 建構標準情境：alterminal 組織、Agents 團隊、teai 倉庫。
+func newStubData() *stubClient {
+	return &stubClient{
+		currentUser: "alex",
+		orgs:        []workflow.Org{{UserName: "alterminal"}},
+		teams:       map[string][]workflow.Team{"alterminal": {{ID: 1, Name: "Agents"}}},
+		members:     map[int64][]string{1: {"alex", "max", "queena"}},
+		repos:       map[string][]workflow.Repo{"alterminal": {{Name: "teai"}}},
+		issues:      map[string][]workflow.Issue{},
+		pulls:       map[string][]workflow.PullRequest{},
+		comments:    map[string][]workflow.Comment{},
+	}
+}
+
+// TestWiringMembersHasWork 驗證 members --has-work 不再被攔成 exit 2。
+func TestWiringMembersHasWork(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("members", "--has-work")
+	if code != 0 {
+		t.Fatalf("members --has-work 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	// 無未完成工作 → 空輸出（每行一個帳號，無帳號即無輸出）。
+	if strings.TrimSpace(stdout) != "" {
+		t.Fatalf("無工作時 members --has-work 應無輸出，得到 %q", stdout)
+	}
+}
+
+// TestWiringPullsMine 驗證 pulls --mine 不再被攔成 exit 2。
+func TestWiringPullsMine(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("pulls", "--mine")
+	if code != 0 {
+		t.Fatalf("pulls --mine 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("pulls --mine 空清單應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringPullsReviewer 驗證 pulls --reviewer 不再被攔成 exit 2。
+func TestWiringPullsReviewer(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("pulls", "--reviewer")
+	if code != 0 {
+		t.Fatalf("pulls --reviewer 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("pulls --reviewer 空清單應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringPullsRepoFilter 驗證 --repo 旗標可解析且值可帶斜線。
+func TestWiringPullsRepoFilter(t *testing.T) {
+	newStubEnv(t, newStubData())
+	_, _, code := run("pulls", "--repo", "alterminal/teai")
+	if code != 0 {
+		t.Fatalf("pulls --repo alterminal/teai 應回 0，得到 %d", code)
+	}
+	// --repo 值格式錯誤 → exit 2。
+	_, _, code = run("pulls", "--repo", "not-a-repo")
+	if code != int(ExitUsage) {
+		t.Fatalf("pulls --repo not-a-repo 應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	}
+}
+
+// TestWiringGlobalAfterCommandFlag 驗證命令旗標與全域選項交錯出現。
+func TestWiringGlobalAfterCommandFlag(t *testing.T) {
+	newStubEnv(t, newStubData())
+	// members --has-work --output table：命令旗標在前、全域選項在後。
+	stdout, _, code := run("members", "--has-work", "--output", "table")
+	if code != 0 {
+		t.Fatalf("members --has-work --output table 應回 0，得到 %d", code)
+	}
+	if strings.Contains(stdout, "--has-work") {
+		t.Fatalf("全域剖析不應把 --has-work 當成全域選項處理：%q", stdout)
+	}
+}
+
+// TestWiringMembersAll 驗證 members 不帶旗標仍正常（回歸保護）。
+func TestWiringMembersAll(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("members")
+	if code != 0 {
+		t.Fatalf("members 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{"alex", "max", "queena"} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("members 輸出應含 %q，得到 %q", want, stdout)
+		}
+	}
+}
+
+// TestWiringMine 驗證 mine 空清單輸出 []（與 gitea.py 空輸出的差異見 README）。
+func TestWiringMine(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("mine")
+	if code != 0 {
+		t.Fatalf("mine 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("mine 空清單應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringNextNull 驗證 next 無工作輸出 null、exit 0。
+func TestWiringNextNull(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("next")
+	if code != 0 {
+		t.Fatalf("next 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "null" {
+		t.Fatalf("next 無工作應輸出 null，得到 %q", stdout)
+	}
+}
+
+// TestWiringNextTable 驗證 teai next --output table（README 範例）。
+func TestWiringNextTable(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("next", "--output", "table")
+	if code != 0 {
+		t.Fatalf("next --output table 應回 0，得到 %d", code)
+	}
+	if !strings.Contains(stdout, "(none)") {
+		t.Fatalf("next --output table 無工作應輸出 (none)，得到 %q", stdout)
+	}
+}
+
+// TestWiringNextWithPull 驗證有工作時 next 輸出 JSON 物件（role=author）。
+func TestWiringNextWithPull(t *testing.T) {
+	c := newStubData()
+	c.pulls["alterminal/teai"] = []workflow.PullRequest{{
+		Number: 13,
+		Title:  "gitea.py 工作流命令 Go 化",
+		User:   &workflow.User{UserName: "alex"},
+	}}
+	c.comments["alterminal/teai"] = []workflow.Comment{
+		{CreatedAt: "2026-09-10T00:44:00Z", User: &workflow.User{UserName: "ceo"}},
+	}
+	newStubEnv(t, c)
+	stdout, _, code := run("next")
+	if code != 0 {
+		t.Fatalf("next 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{`"type":"pull"`, `"role":"author"`, `"number":13`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("next 輸出應含 %q，得到 %q", want, stdout)
+		}
+	}
+}
+
+// TestWiringWhoamiOrgs 驗證 whoami／orgs 的接線輸出。
+func TestWiringWhoamiOrgs(t *testing.T) {
+	newStubEnv(t, newStubData())
+	stdout, _, code := run("whoami")
+	if code != 0 || !strings.Contains(stdout, "alex") {
+		t.Fatalf("whoami code=%d stdout=%q", code, stdout)
+	}
+	stdout, _, code = run("orgs")
+	if code != 0 || !strings.Contains(stdout, "alterminal") {
+		t.Fatalf("orgs code=%d stdout=%q", code, stdout)
+	}
+}
+
+// TestWiringVersionRejectsArgs 驗證 version 不接受參數（新剖析語義下仍 exit 2）。
+func TestWiringVersionRejectsArgs(t *testing.T) {
+	_, _, code := run("version", "--wat")
+	if code != int(ExitUsage) {
+		t.Fatalf("version --wat 應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	}
+}
@@ -0,0 +1,384 @@
+// Package dailyops 實作 tea 對等的日常操作（#8）：issues、pulls、labels、
+// milestones、releases、repos 的讀寫，直接以 Gitea API 為準。
+//
+// 讀寫行為對照 Gitea 1.27 API（issues 端點帶 type=issues 排除 PR，
+// 見 gitea.py 的注意事項）；寫入的「--yes 閘門」在 CLI 層（見
+// dailyops_commands.go），本套件只負責 API 呼叫。
+package dailyops
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// User 是 API 回應中的使用者精簡欄位。
+type User struct {
+	UserName string `json:"login"`
+}
+
+// Name 回傳帳號名。
+func (u *User) Name() string {
+	if u == nil {
+		return ""
+	}
+	return u.UserName
+}
+
+// Issue 是 Gitea issue／PR 共用端點的精簡欄位（PR 亦走 issues 端點）。
+type Issue struct {
+	Number    int64    `json:"number"`
+	Title     string   `json:"title"`
+	State     string   `json:"state"`
+	Body      string   `json:"body"`
+	HTMLURL   string   `json:"html_url"`
+	UpdatedAt string   `json:"updated_at"`
+	User      *User    `json:"user"`
+	Assignees []*User  `json:"assignees"`
+	Labels    []Label  `json:"labels"`
+	Assignee  []string `json:"-"` // 輸出用：帳號清單（由 Assignees 導出）
+}
+
+// Author 回傳建立者帳號。
+func (i *Issue) Author() string { return i.User.Name() }
+
+// AssigneeNames 回傳 assignees 帳號清單（輸出用）。
+func (i *Issue) AssigneeNames() []string {
+	names := make([]string, 0, len(i.Assignees))
+	for _, a := range i.Assignees {
+		if n := a.Name(); n != "" {
+			names = append(names, n)
+		}
+	}
+	return names
+}
+
+// LabelNames 回傳標籤名稱清單（輸出用）。
+func (i *Issue) LabelNames() []string {
+	names := make([]string, 0, len(i.Labels))
+	for _, l := range i.Labels {
+		names = append(names, l.Name)
+	}
+	return names
+}
+
+// Label 是倉庫標籤。
+type Label struct {
+	ID          int64  `json:"id"`
+	Name        string `json:"name"`
+	Color       string `json:"color"`
+	Description string `json:"description"`
+}
+
+// Milestone 是倉庫里程碑。
+type Milestone struct {
+	ID          int64  `json:"id"`
+	Title       string `json:"title"`
+	Description string `json:"description"`
+	State       string `json:"state"`
+	DueOn       string `json:"due_on"`
+}
+
+// Release 是倉庫發佈。
+type Release struct {
+	TagName     string `json:"tag_name"`
+	Name        string `json:"name"`
+	Draft       bool   `json:"draft"`
+	Prerelease  bool   `json:"prerelease"`
+	CreatedAt   string `json:"created_at"`
+	PublishedAt string `json:"published_at"`
+	HTMLURL     string `json:"html_url"`
+}
+
+// Comment 是 issue／PR 留言。
+type Comment struct {
+	Body      string `json:"body"`
+	CreatedAt string `json:"created_at"`
+	User      *User  `json:"user"`
+}
+
+// Author 回串留言者帳號。
+func (c *Comment) Author() string { return c.User.Name() }
+
+// Pull 是 pull request 的精簡欄位。
+type Pull struct {
+	Number    int64    `json:"number"`
+	Title     string   `json:"title"`
+	State     string   `json:"state"`
+	Body      string   `json:"body"`
+	HTMLURL   string   `json:"html_url"`
+	UpdatedAt string   `json:"updated_at"`
+	User      *User    `json:"user"`
+	Head      *pullRef `json:"head"`
+	Base      *pullRef `json:"base"`
+}
+
+// pullRef 是 PR 的 head／base 參照。
+type pullRef struct {
+	Ref  string `json:"ref"`
+	Repo *struct {
+		FullName string `json:"full_name"`
+	} `json:"repo"`
+}
+
+// HeadRef 回傳 head 分支名（輸出用）。
+func (p *Pull) HeadRef() string {
+	if p.Head == nil {
+		return ""
+	}
+	return p.Head.Ref
+}
+
+// BaseRef 回傳 base 分支名（輸出用）。
+func (p *Pull) BaseRef() string {
+	if p.Base == nil {
+		return ""
+	}
+	return p.Base.Ref
+}
+
+// Author 回傳 PR 作者帳號。
+func (p *Pull) Author() string { return p.User.Name() }
+
+// Repo 是倉庫的精簡欄位。
+type Repo struct {
+	FullName    string `json:"full_name"`
+	Description string `json:"description"`
+	Private     bool   `json:"private"`
+	Empty       bool   `json:"empty"`
+	UpdatedAt   string `json:"updated_at"`
+	HTMLURL     string `json:"html_url"`
+}
+
+// Ops 聚合日常操作的 API 呼叫。
+type Ops struct {
+	// Client 是 Gitea API 用戶端（internal/gitea）。
+	Client *gitea.Client
+}
+
+// repoPath 組出 /repos/{owner}/{repo} 前綴；owner／repo 皆做路徑跳脫。
+func repoPath(owner, repo string) string {
+	return "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo)
+}
+
+// ListIssues 列出倉庫 issues。state：open｜closed｜all（預設 open）；
+// type=issues 排除 PR（Gitea 的 issues 端點會連 PR 一起回）。
+func (o *Ops) ListIssues(ctx context.Context, owner, repo, state string) ([]Issue, error) {
+	if state == "" {
+		state = "open"
+	}
+	// state 一律明確傳給 API：issues／milestones 端點省略 state 時預設
+	// open（#33），closed 項目會漏列；all 也不能省略。
+	extra := url.Values{}
+	extra.Set("state", state)
+	// type=issues：排除 PR（PR 在此端點帶 pull_request 欄位）。
+	extra.Set("type", "issues")
+	var issues []Issue
+	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/issues", gitea.ListOptions{Extra: extra}, &issues); err != nil {
+		return nil, err
+	}
+	return issues, nil
+}
+
+// CreateIssue 建立 issue；assignees 可為空。
+func (o *Ops) CreateIssue(ctx context.Context, owner, repo, title, body string, assignees []string) (*Issue, error) {
+	payload := map[string]any{
+		"title": title,
+		"body":  body,
+	}
+	if len(assignees) > 0 {
+		payload["assignees"] = assignees
+	}
+	var issue Issue
+	if err := o.Client.DoJSON(ctx, "POST", repoPath(owner, repo)+"/issues", "", payload, &issue); err != nil {
+		return nil, err
+	}
+	return &issue, nil
+}
+
+// GetIssue 取得單一 issue（含 PR，但此處供 issues view 用）。
+func (o *Ops) GetIssue(ctx context.Context, owner, repo string, number int64) (*Issue, error) {
+	var issue Issue
+	path := repoPath(owner, repo) + "/issues/" + strconv.FormatInt(number, 10)
+	if err := o.Client.GetJSON(ctx, path, &issue); err != nil {
+		return nil, err
+	}
+	return &issue, nil
+}
+
+// SetIssueState 變更 issue 狀態（open｜closed）。
+func (o *Ops) SetIssueState(ctx context.Context, owner, repo string, number int64, state string) (*Issue, error) {
+	payload := map[string]any{"state": state}
+	var issue Issue
+	path := repoPath(owner, repo) + "/issues/" + strconv.FormatInt(number, 10)
+	if err := o.Client.DoJSON(ctx, "PATCH", path, "", payload, &issue); err != nil {
+		return nil, err
+	}
+	return &issue, nil
+}
+
+// ListComments 列出 issue／PR 的留言（PR 亦走 issues 端點）。
+func (o *Ops) ListComments(ctx context.Context, owner, repo string, number int64) ([]Comment, error) {
+	var comments []Comment
+	path := repoPath(owner, repo) + "/issues/" + strconv.FormatInt(number, 10) + "/comments"
+	if err := o.Client.ListAll(ctx, path, gitea.ListOptions{}, &comments); err != nil {
+		return nil, err
+	}
+	return comments, nil
+}
+
+// AddComment 對 issue／PR 留言。
+func (o *Ops) AddComment(ctx context.Context, owner, repo string, number int64, body string) (*Comment, error) {
+	payload := map[string]any{"body": body}
+	var comment Comment
+	path := repoPath(owner, repo) + "/issues/" + strconv.FormatInt(number, 10) + "/comments"
+	if err := o.Client.DoJSON(ctx, "POST", path, "", payload, &comment); err != nil {
+		return nil, err
+	}
+	return &comment, nil
+}
+
+// ListPulls 列出倉庫 PR；state 預設 open。
+func (o *Ops) ListPulls(ctx context.Context, owner, repo, state string) ([]Pull, error) {
+	if state == "" {
+		state = "open"
+	}
+	// state 一律明確傳給 API：pulls 端點省略 state 時雖回全部，仍明確
+	// 帶上，避免依賴端點預設值（#33）。
+	extra := url.Values{}
+	extra.Set("state", state)
+	var pulls []Pull
+	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/pulls", gitea.ListOptions{Extra: extra}, &pulls); err != nil {
+		return nil, err
+	}
+	return pulls, nil
+}
+
+// GetPull 取得單一 PR。
+func (o *Ops) GetPull(ctx context.Context, owner, repo string, number int64) (*Pull, error) {
+	var pull Pull
+	path := repoPath(owner, repo) + "/pulls/" + strconv.FormatInt(number, 10)
+	if err := o.Client.GetJSON(ctx, path, &pull); err != nil {
+		return nil, err
+	}
+	return &pull, nil
+}
+
+// CreatePull 建立 PR。
+func (o *Ops) CreatePull(ctx context.Context, owner, repo, title, body, head, base string) (*Pull, error) {
+	payload := map[string]any{
+		"title": title,
+		"body":  body,
+		"head":  head,
+		"base":  base,
+	}
+	var pull Pull
+	if err := o.Client.DoJSON(ctx, "POST", repoPath(owner, repo)+"/pulls", "", payload, &pull); err != nil {
+		return nil, err
+	}
+	return &pull, nil
+}
+
+// MergePull 合併 PR。style：merge｜rebase｜rebase-merge｜squash（預設 merge）。
+func (o *Ops) MergePull(ctx context.Context, owner, repo string, number int64, style string) error {
+	if style == "" {
+		style = "merge"
+	}
+	payload := map[string]any{"Do": style}
+	path := repoPath(owner, repo) + "/pulls/" + strconv.FormatInt(number, 10) + "/merge"
+	return o.Client.DoJSON(ctx, "POST", path, "", payload, nil)
+}
+
+// ListLabels 列出倉庫標籤。
+func (o *Ops) ListLabels(ctx context.Context, owner, repo string) ([]Label, error) {
+	var labels []Label
+	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/labels", gitea.ListOptions{}, &labels); err != nil {
+		return nil, err
+	}
+	return labels, nil
+}
+
+// CreateLabel 建立標籤；color 格式如 #ffffff。
+func (o *Ops) CreateLabel(ctx context.Context, owner, repo, name, color, description string) (*Label, error) {
+	payload := map[string]any{
+		"name":        name,
+		"color":       color,
+		"description": description,
+	}
+	var label Label
+	if err := o.Client.DoJSON(ctx, "POST", repoPath(owner, repo)+"/labels", "", payload, &label); err != nil {
+		return nil, err
+	}
+	return &label, nil
+}
+
+// ListMilestones 列出倉庫里程碑；state 預設 open（可用 all）。
+func (o *Ops) ListMilestones(ctx context.Context, owner, repo, state string) ([]Milestone, error) {
+	if state == "" {
+		state = "open"
+	}
+	// state 一律明確傳給 API：milestones 端點省略 state 時預設 open
+	// （#33），closed 項目會漏列。
+	extra := url.Values{}
+	extra.Set("state", state)
+	var ms []Milestone
+	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/milestones", gitea.ListOptions{Extra: extra}, &ms); err != nil {
+		return nil, err
+	}
+	return ms, nil
+}
+
+// CreateMilestone 建立里程碑；dueOn 可空（RFC3339）。
+func (o *Ops) CreateMilestone(ctx context.Context, owner, repo, title, description, dueOn string) (*Milestone, error) {
+	payload := map[string]any{
+		"title":       title,
+		"description": description,
+	}
+	if dueOn != "" {
+		payload["due_on"] = dueOn
+	}
+	var m Milestone
+	if err := o.Client.DoJSON(ctx, "POST", repoPath(owner, repo)+"/milestones", "", payload, &m); err != nil {
+		return nil, err
+	}
+	return &m, nil
+}
+
+// ListReleases 列出倉庫發佈。
+func (o *Ops) ListReleases(ctx context.Context, owner, repo string) ([]Release, error) {
+	var releases []Release
+	if err := o.Client.ListAll(ctx, repoPath(owner, repo)+"/releases", gitea.ListOptions{}, &releases); err != nil {
+		return nil, err
+	}
+	return releases, nil
+}
+
+// ListMyRepos 列出自己可存取的倉庫。
+func (o *Ops) ListMyRepos(ctx context.Context) ([]Repo, error) {
+	var repos []Repo
+	if err := o.Client.ListAll(ctx, "/user/repos", gitea.ListOptions{}, &repos); err != nil {
+		return nil, err
+	}
+	return repos, nil
+}
+
+// ListOrgRepos 列出組織倉庫。
+func (o *Ops) ListOrgRepos(ctx context.Context, org string) ([]Repo, error) {
+	var repos []Repo
+	if err := o.Client.ListAll(ctx, "/orgs/"+url.PathEscape(org)+"/repos", gitea.ListOptions{}, &repos); err != nil {
+		return nil, err
+	}
+	return repos, nil
+}
+
+// CallAPIDirect 是 teai api 的原樣傳遞：以指定動詞呼叫 path（相對 /api/v1），
+// data 為原樣 JSON（可為 nil）。回傳原始回應位元組。
+func (o *Ops) CallAPIDirect(ctx context.Context, method, path, rawQuery string, data []byte) ([]byte, error) {
+	if path == "" || path[0] != '/' {
+		return nil, fmt.Errorf("api path 必須以 / 開頭（相對 api/v1）")
+	}
+	return o.Client.DoRaw(ctx, method, path, rawQuery, data)
+}
@@ -0,0 +1,268 @@
+// auth.go — 認證來源的解析與選序。
+//
+// 選序（README「全域介面」）：--token 旗標 → TEAI_TOKEN 環境變數 →
+// tea 登入組態（TEA_CONFIG 指定的路徑，或 ~/.config/tea/config.yml）。
+// token 一律只在記憶體傳遞，不寫入輸出、日誌或錯誤訊息。
+package gitea
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// TokenSource 標記 token 的來源，供測試與診斷（不含 token 本身）。
+type TokenSource int
+
+const (
+	// SourceNone 表示沒有任何可用 token（匿名存取）。
+	SourceNone TokenSource = iota
+	// SourceFlag 是 --token 旗標。
+	SourceFlag
+	// SourceEnv 是 TEAI_TOKEN 環境變數。
+	SourceEnv
+	// SourceTeaConfig 是 tea 登入組態。
+	SourceTeaConfig
+)
+
+// String 回傳來源名稱（診斷用）。
+func (s TokenSource) String() string {
+	switch s {
+	case SourceFlag:
+		return "flag"
+	case SourceEnv:
+		return "env"
+	case SourceTeaConfig:
+		return "tea-config"
+	default:
+		return "none"
+	}
+}
+
+// EnvLookup 是環境變數查詢介面（測試可替換）。
+type EnvLookup func(key string) (string, bool)
+
+// ReadFileFunc 是檔案讀取介面（測試可替換）。
+type ReadFileFunc func(path string) ([]byte, error)
+
+// osEnv / osReadFile 是正式環境的預設實作。
+func osEnv(key string) (string, bool) {
+	v, ok := os.LookupEnv(key)
+	return v, ok
+}
+
+func osReadFile(path string) ([]byte, error) {
+	// 假設路徑已被 ExpandConfigPath 展開為絕對路徑。
+	return os.ReadFile(path)
+}
+
+// AuthOptions 聚合認證解析所需的輸入。
+type AuthOptions struct {
+	// FlagToken 是 --token 旗標值；空字串表示未提供。
+	FlagToken string
+	// SiteURL 是目標站點（用來比對 tea 組態中的 login url）。
+	SiteURL string
+	// Env 是環境變數查詢；nil 時用 os.LookupEnv。
+	Env EnvLookup
+	// ConfigPath 是 tea 組態的明確路徑（TEA_CONFIG 或 --config）。
+	// 空字串表示用預設 ~/.config/tea/config.yml。
+	ConfigPath string
+	// Home 是使用者家目錄（展開 ~ 用）；空字串表示不展開。
+	Home string
+	// ReadFile 是檔案讀取函式；nil 時用 os.ReadFile。
+	ReadFile ReadFileFunc
+}
+
+// ResolveToken 依選序解析 token：flag → env(TEAI_TOKEN) → tea 組態。
+//
+// 找不到任何 token 時回傳 ("", SourceNone, nil)——查詢公開端點不需要
+// token，是否為錯由呼叫端依情境決定。組態檔存在但解析失敗（格式錯誤）
+// 時回傳錯誤，因為這通常代表組態被改壞了，靜默降級為匿名會更難查。
+func ResolveToken(opts AuthOptions) (string, TokenSource, error) {
+	if t := strings.TrimSpace(opts.FlagToken); t != "" {
+		return t, SourceFlag, nil
+	}
+	env := opts.Env
+	if env == nil {
+		env = osEnv
+	}
+	if t, ok := env("TEAI_TOKEN"); ok && strings.TrimSpace(t) != "" {
+		return strings.TrimSpace(t), SourceEnv, nil
+	}
+	path := opts.ConfigPath
+	if path == "" {
+		// --config 未給時，先看 TEA_CONFIG 環境變數。
+		if p, ok := env("TEA_CONFIG"); ok && strings.TrimSpace(p) != "" {
+			path = strings.TrimSpace(p)
+		}
+	}
+	if path == "" {
+		home := opts.Home
+		if home == "" {
+			h, err := os.UserHomeDir()
+			if err != nil {
+				return "", SourceNone, nil
+			}
+			home = h
+		}
+		if home == "" {
+			return "", SourceNone, nil
+		}
+		path = filepath.Join(home, ".config", "tea", "config.yml")
+	}
+	if path == "" {
+		return "", SourceNone, nil
+	}
+	readFile := opts.ReadFile
+	if readFile == nil {
+		readFile = osReadFile
+	}
+	data, err := readFile(path)
+	if err != nil {
+		// 組態不存在或讀不到：視為沒有這個來源，不是錯誤。
+		return "", SourceNone, nil
+	}
+	login, err := parseTeaConfig(data, opts.SiteURL)
+	if err != nil {
+		return "", SourceNone, fmt.Errorf("gitea: parse tea config %s: %w", path, err)
+	}
+	if login.Token == "" {
+		return "", SourceNone, nil
+	}
+	return login.Token, SourceTeaConfig, nil
+}
+
+// teaLogin 是 tea 組態中一筆登入資料（只取 teai 需要的欄位）。
+type teaLogin struct {
+	Name    string
+	URL     string
+	Token   string
+	Default bool
+}
+
+// parseTeaConfig 從 tea 的 config.yml 內容挑出最匹配 siteURL 的登入：
+// url 主機相同者優先，其中 default: true 最優，否則取第一筆；
+// 都不相同時退而取 default: true，再退第一筆。
+//
+// 僅解析 tea 實際寫出的 YAML 子集：頂層 `logins:` 清單，項目為
+// `key: value` 的平面映射。不處理錨點、多文件、巢狀清單——tea 不會寫出
+// 這些，遇到也不該默默誤讀。
+func parseTeaConfig(data []byte, siteURL string) (teaLogin, error) {
+	var logins []teaLogin
+	inLogins := false
+	cur := -1 // 目前項目在 logins 的索引；-1 表示尚未開始任何項目
+	for lineNo, raw := range strings.Split(string(data), "\n") {
+		line := strings.TrimRight(raw, "\r")
+		// 忽略註解行（行的第一個非空白字元是 #）。
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		indent := len(line) - len(strings.TrimLeft(line, " "))
+		if indent == 0 {
+			inLogins = strings.HasPrefix(trimmed, "logins:")
+			cur = -1
+			continue
+		}
+		if !inLogins {
+			continue
+		}
+		if strings.HasPrefix(trimmed, "- ") || trimmed == "-" {
+			// 新的清單項目；`- name: x` 形式同行帶鍵值。
+			logins = append(logins, teaLogin{})
+			cur = len(logins) - 1
+			rest := strings.TrimSpace(strings.TrimPrefix(trimmed, "-"))
+			if rest != "" {
+				if err := applyLoginField(&logins[cur], rest, lineNo+1); err != nil {
+					return teaLogin{}, err
+				}
+			}
+			continue
+		}
+		if cur < 0 {
+			// logins: 底下卻不是清單項目——不是預期的結構。
+			return teaLogin{}, fmt.Errorf("line %d: expected list item under logins:", lineNo+1)
+		}
+		if err := applyLoginField(&logins[cur], trimmed, lineNo+1); err != nil {
+			return teaLogin{}, err
+		}
+	}
+	if len(logins) == 0 {
+		return teaLogin{}, nil
+	}
+	wantHost := hostOf(siteURL)
+	// 第一輪：主機相符者，default 優先，否則第一筆。
+	var fallback = -1   // 主機相符的非 default
+	var anyDefault = -1 // 全域 default
+	for i, l := range logins {
+		if wantHost != "" && hostOf(l.URL) == wantHost {
+			if l.Default {
+				return l, nil
+			}
+			if fallback < 0 {
+				fallback = i
+			}
+		}
+		if l.Default && anyDefault < 0 {
+			anyDefault = i
+		}
+	}
+	if fallback >= 0 {
+		return logins[fallback], nil
+	}
+	if anyDefault >= 0 {
+		return logins[anyDefault], nil
+	}
+	return logins[0], nil
+}
+
+// applyLoginField 把 `key: value` 套用到 login；value 的引號會剝除。
+func applyLoginField(l *teaLogin, kv string, lineNo int) error {
+	key, value, ok := strings.Cut(kv, ":")
+	if !ok {
+		return fmt.Errorf("line %d: expected key: value, got %q", lineNo, kv)
+	}
+	key = strings.TrimSpace(key)
+	value = strings.TrimSpace(value)
+	value = unquoteYAML(value)
+	switch key {
+	case "name":
+		l.Name = value
+	case "url":
+		l.URL = value
+	case "token":
+		l.Token = value
+	case "default":
+		l.Default = value == "true"
+	}
+	return nil
+}
+
+// unquoteYAML 剝除 YAML 的單／雙引號。
+func unquoteYAML(s string) string {
+	if len(s) >= 2 {
+		if (s[0] == '"' && s[len(s)-1] == '"') || (s[0] == '\'' && s[len(s)-1] == '\'') {
+			return s[1 : len(s)-1]
+		}
+	}
+	return s
+}
+
+// hostOf 取 URL 的主機部分（連埠）；解析失敗回空字串。
+func hostOf(rawURL string) string {
+	s := strings.TrimSpace(rawURL)
+	if s == "" {
+		return ""
+	}
+	// 補配置讓 url.Parse 能取 Host。
+	if !strings.Contains(s, "://") {
+		s = "https://" + s
+	}
+	u, err := url.Parse(s)
+	if err != nil {
+		return ""
+	}
+	return strings.ToLower(u.Host)
+}
@@ -0,0 +1,181 @@
+// auth_test.go 驗證認證來源選序（--token → TEAI_TOKEN → tea 組態）
+// 與 tea 組態解析。
+package gitea
+
+import (
+	"errors"
+	"testing"
+)
+
+// fakeEnv 依 map 回傳環境變數。
+func fakeEnv(m map[string]string) EnvLookup {
+	return func(key string) (string, bool) {
+		v, ok := m[key]
+		return v, ok
+	}
+}
+
+// fakeReadFile 依 map 回傳檔案內容；不存在時回 os.ErrNotExist 類錯誤。
+func fakeReadFile(m map[string]string) ReadFileFunc {
+	return func(path string) ([]byte, error) {
+		if data, ok := m[path]; ok {
+			return []byte(data), nil
+		}
+		return nil, errors.New("file does not exist")
+	}
+}
+
+const sampleTeaConfig = `logins:
+    - name: other.example.com
+      url: https://other.example.com
+      token: other-token
+      default: false
+    - name: gitea.alterminal.com
+      url: https://gitea.alterminal.com
+      token: site-token
+      default: true
+preferences:
+    editor: false
+`
+
+func TestResolveTokenOrdering(t *testing.T) {
+	base := AuthOptions{
+		SiteURL: "https://gitea.alterminal.com",
+		Env:     fakeEnv(nil),
+		ReadFile: fakeReadFile(map[string]string{
+			"/cfg/config.yml": sampleTeaConfig,
+		}),
+		ConfigPath: "/cfg/config.yml",
+	}
+
+	t.Run("flag wins over env and config", func(t *testing.T) {
+		opts := base
+		opts.FlagToken = "flag-token"
+		opts.Env = fakeEnv(map[string]string{"TEAI_TOKEN": "env-token"})
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "flag-token" || src != SourceFlag {
+			t.Fatalf("want flag-token/flag, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("env wins over config", func(t *testing.T) {
+		opts := base
+		opts.Env = fakeEnv(map[string]string{"TEAI_TOKEN": "env-token"})
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "env-token" || src != SourceEnv {
+			t.Fatalf("want env-token/env, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("tea config used when flag and env absent", func(t *testing.T) {
+		opts := base
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "site-token" || src != SourceTeaConfig {
+			t.Fatalf("want site-token/tea-config, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("none when all sources absent", func(t *testing.T) {
+		opts := base
+		opts.ConfigPath = "/cfg/missing.yml"
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "" || src != SourceNone {
+			t.Fatalf("want \"\"/none, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("blank env var is skipped", func(t *testing.T) {
+		opts := base
+		opts.Env = fakeEnv(map[string]string{"TEAI_TOKEN": "   "})
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "site-token" || src != SourceTeaConfig {
+			t.Fatalf("want site-token/tea-config, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("blank flag is skipped", func(t *testing.T) {
+		opts := base
+		opts.FlagToken = "  "
+		opts.Env = fakeEnv(map[string]string{"TEAI_TOKEN": "env-token"})
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "env-token" || src != SourceEnv {
+			t.Fatalf("want env-token/env, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("TEA_CONFIG points config path", func(t *testing.T) {
+		opts := base
+		opts.ConfigPath = "" // 不用 --config，改用 TEA_CONFIG
+		opts.Env = fakeEnv(map[string]string{
+			"TEA_CONFIG": "/cfg/config.yml",
+		})
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "site-token" || src != SourceTeaConfig {
+			t.Fatalf("want site-token/tea-config via TEA_CONFIG, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+
+	t.Run("explicit --config beats TEA_CONFIG", func(t *testing.T) {
+		opts := base // ConfigPath = /cfg/config.yml（有 site-token）
+		opts.Env = fakeEnv(map[string]string{
+			"TEA_CONFIG": "/cfg/other.yml",
+		})
+		read := fakeReadFile(map[string]string{
+			"/cfg/config.yml": sampleTeaConfig,
+			"/cfg/other.yml":  "logins:\n    - name: x\n      url: https://gitea.alterminal.com\n      token: other\n      default: true\n",
+		})
+		opts.ReadFile = read
+		tok, src, err := ResolveToken(opts)
+		if err != nil || tok != "site-token" || src != SourceTeaConfig {
+			t.Fatalf("want site-token from explicit config, got %q/%v (err %v)", tok, src, err)
+		}
+	})
+}
+
+func TestParseTeaConfigPicksMatchingLogin(t *testing.T) {
+	t.Run("host match preferred over default", func(t *testing.T) {
+		cfg := `logins:
+    - name: other
+      url: https://other.example.com
+      token: wrong-token
+      default: true
+    - name: target
+      url: https://gitea.alterminal.com
+      token: right-token
+      default: false
+`
+		login, err := parseTeaConfig([]byte(cfg), "https://gitea.alterminal.com")
+		if err != nil {
+			t.Fatalf("parse error: %v", err)
+		}
+		if login.Token != "right-token" {
+			t.Fatalf("host-matched login should win, got token %q", login.Token)
+		}
+	})
+
+	t.Run("quoted token unquoted", func(t *testing.T) {
+		cfg := "logins:\n    - name: t\n      url: https://gitea.alterminal.com\n      token: \"quoted-token\"\n      default: true\n"
+		login, err := parseTeaConfig([]byte(cfg), "https://gitea.alterminal.com")
+		if err != nil {
+			t.Fatalf("parse error: %v", err)
+		}
+		if login.Token != "quoted-token" {
+			t.Fatalf("want quoted-token (unquoted), got %q", login.Token)
+		}
+	})
+
+	t.Run("malformed login entry errors", func(t *testing.T) {
+		cfg := "logins:\n    - name: t\n      url: https://gitea.alterminal.com\n      oops\n"
+		if _, err := parseTeaConfig([]byte(cfg), ""); err == nil {
+			t.Fatal("malformed line should error")
+		}
+	})
+
+	t.Run("no logins yields empty", func(t *testing.T) {
+		cfg := "preferences:\n    editor: false\n"
+		login, err := parseTeaConfig([]byte(cfg), "")
+		if err != nil || login.Token != "" {
+			t.Fatalf("want empty login, got %+v (err %v)", login, err)
+		}
+	})
+}
@@ -0,0 +1,228 @@
+// 套件 gitea 提供存取 Gitea API 的 HTTP 用戶端基礎：
+// 認證、分頁、逾時與錯誤映射。
+//
+// 僅使用標準庫（net/http 等），離線可建置。token 由呼叫端注入，
+// 本套件不負責認證來源的解析（見 auth.go），也不會把 token 寫進
+// 任何輸出或錯誤訊息。
+package gitea
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// ErrAPI 表示與 Gitea API 溝通失敗（連線、認證、權限或伺服器錯誤）。
+// 行為上對應結束碼 3（API 錯誤）。
+type ErrAPI struct {
+	// StatusCode 是 HTTP 回應狀態碼；0 表示請求未完成（連線失敗等）。
+	StatusCode int
+	// Op 是失敗的步驟描述（如 "GET /api/v1/user"），僅供診斷。
+	Op string
+	// Err 是底層錯誤。
+	Err error
+}
+
+// Error 實作 error 介面；不包含 token 或完整回應內容。
+func (e *ErrAPI) Error() string {
+	if e.StatusCode == 0 {
+		return fmt.Sprintf("gitea: %s: %v", e.Op, e.Err)
+	}
+	return fmt.Sprintf("gitea: %s: HTTP %d", e.Op, e.StatusCode)
+}
+
+// Unwrap 支援 errors.Is / errors.As。
+func (e *ErrAPI) Unwrap() error { return e.Err }
+
+// Client 是 Gitea API 的最小用戶端。零值不可用，請用 New。
+type Client struct {
+	// baseURL 是 API 根（如 https://gitea.alterminal.com/api/v1），
+	// 不帶尾斜線。
+	baseURL *url.URL
+	// token 是 API token；空字串表示匿名存取（公開端點）。
+	token string
+	// hc 是底層 HTTP 用戶端（帶逾時）。
+	hc *http.Client
+}
+
+// DefaultTimeout 是未指定逾時時的預設值。
+const DefaultTimeout = 30 * time.Second
+
+// New 建立用戶端。baseURL 為站點網址（如 https://gitea.alterminal.com），
+// 函式內部自行補上 /api/v1 路徑。timeout <= 0 時採 DefaultTimeout。
+func New(baseURL, token string, timeout time.Duration) (*Client, error) {
+	u, err := url.Parse(strings.TrimSuffix(baseURL, "/"))
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return nil, fmt.Errorf("gitea: invalid base URL %q", baseURL)
+	}
+	u = u.JoinPath("api", "v1")
+	if timeout <= 0 {
+		timeout = DefaultTimeout
+	}
+	return &Client{
+		baseURL: u,
+		token:   token,
+		hc:      &http.Client{Timeout: timeout},
+	}, nil
+}
+
+// MaxLimit 是 Gitea 清單端點單次回傳上限（服務端硬上限 50）。
+const MaxLimit = 50
+
+// getJSON 對 path（相對 baseURL，以 / 開頭）發 GET，把 JSON 回應解到 out。
+// 失敗時回傳 *ErrAPI。rawQuery 為組好的查詢字串（見 ListOptions.query）。
+func (c *Client) getJSON(ctx context.Context, path, rawQuery string, out any) error {
+	_, err := c.do(ctx, http.MethodGet, path, rawQuery, "", nil, out)
+	return err
+}
+
+// DoJSON 對 path 發 method 請求（POST/PATCH/PUT/DELETE…），body 為可 JSON
+// 化的值（nil 表示不帶 body），2xx 時把回應解到 out（out 非 nil 且回應
+// 有內容時）。供寫入類操作（issues create、pulls merge…）使用。
+func (c *Client) DoJSON(ctx context.Context, method, path, rawQuery string, body any, out any) error {
+	var payload []byte
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return fmt.Errorf("gitea: marshal request body: %w", err)
+		}
+		payload = b
+	}
+	_, err := c.do(ctx, method, path, rawQuery, "application/json", payload, out)
+	return err
+}
+
+// DoRaw 以原樣 body 送出請求並回傳原始回應內容（teai api 用）。
+// 非 2xx 回 *ErrAPI。
+func (c *Client) DoRaw(ctx context.Context, method, path, rawQuery string, body []byte) ([]byte, error) {
+	contentType := ""
+	if body != nil {
+		contentType = "application/json"
+	}
+	return c.do(ctx, method, path, rawQuery, contentType, body, nil)
+}
+
+// do 是所有請求的共同核心：組 URL、帶認證表頭、送出、檢查狀態碼、
+// 解析回應。2xx 時回傳原始回應位元組；out 非 nil 時另解到 out。
+// 錯誤訊息不含 token 或回應內容。
+func (c *Client) do(ctx context.Context, method, path, rawQuery, contentType string, payload []byte, out any) ([]byte, error) {
+	u := *c.baseURL
+	u.Path += path
+	u.RawQuery = rawQuery
+	op := method + " " + u.Path
+
+	var body io.Reader
+	if payload != nil {
+		body = bytes.NewReader(payload)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u.String(), body)
+	if err != nil {
+		return nil, &ErrAPI{Op: op, Err: err}
+	}
+	req.Header.Set("Accept", "application/json")
+	if payload != nil && contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	if c.token != "" {
+		req.Header.Set("Authorization", "token "+c.token)
+	}
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return nil, &ErrAPI{Op: op, Err: err}
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		// 把內容讀掉再丟棄，讓連線可重用；錯誤訊息不含回應內容。
+		_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
+		return nil, &ErrAPI{Op: op, StatusCode: resp.StatusCode}
+	}
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, &ErrAPI{Op: op, Err: err}
+	}
+	if out != nil && len(data) > 0 {
+		if err := json.Unmarshal(data, out); err != nil {
+			return nil, &ErrAPI{Op: op, Err: fmt.Errorf("decode response: %w", err)}
+		}
+	}
+	return data, nil
+}
+
+// GetJSON 是 getJSON 的公開介面，供非清單端點（如 /user）使用。
+func (c *Client) GetJSON(ctx context.Context, path string, out any) error {
+	return c.getJSON(ctx, path, "", out)
+}
+
+// ListOptions 描述清單端點的分頁參數。
+type ListOptions struct {
+	// Limit 是單頁筆數；<= 0 或 > MaxLimit 時設為 MaxLimit。
+	Limit int
+	// Page 是頁碼（1 起）；僅供單頁抓取，ListAll 一律從第 1 頁開始。
+	Page int
+	// Extra 是額外查詢參數（如 state、type）。
+	Extra url.Values
+}
+
+// query 把分頁參數組成查詢字串。
+func (o ListOptions) query() string {
+	q := url.Values{}
+	limit := o.Limit
+	if limit <= 0 || limit > MaxLimit {
+		limit = MaxLimit
+	}
+	q.Set("limit", strconv.Itoa(limit))
+	if o.Page > 1 {
+		q.Set("page", strconv.Itoa(o.Page))
+	}
+	for k, vs := range o.Extra {
+		for _, v := range vs {
+			q.Set(k, v)
+		}
+	}
+	return q.Encode()
+}
+
+// ListAll 逐頁抓取清單端點直到抓完，把結果存進 out（指向 slice 的指標，
+// 初始須為空 slice）。每頁固定使用 limit=MaxLimit（Gitea 上限 50）；
+// opts.Extra 照常帶入。頁數在服務端回傳未滿頁或空頁時結束。
+func (c *Client) ListAll(ctx context.Context, path string, opts ListOptions, out any) error {
+	rv := reflect.ValueOf(out)
+	if rv.Kind() != reflect.Pointer || rv.IsNil() {
+		return fmt.Errorf("gitea: ListAll: out must be non-nil pointer to slice")
+	}
+	sv := rv.Elem()
+	if sv.Kind() != reflect.Slice {
+		return fmt.Errorf("gitea: ListAll: out must be non-nil pointer to slice")
+	}
+	if sv.Len() != 0 {
+		return fmt.Errorf("gitea: ListAll: out slice must be empty")
+	}
+	for page := 1; ; page++ {
+		opts := opts
+		opts.Limit = MaxLimit
+		opts.Page = page
+		pageOut := reflect.MakeSlice(sv.Type(), 0, MaxLimit)
+		pp := reflect.New(sv.Type())
+		pp.Elem().Set(pageOut)
+		if err := c.getJSON(ctx, path, opts.query(), pp.Interface()); err != nil {
+			return err
+		}
+		got := pp.Elem()
+		n := got.Len()
+		if n == 0 {
+			return nil
+		}
+		sv.Set(reflect.AppendSlice(sv, got))
+		if n < MaxLimit {
+			return nil
+		}
+	}
+}
@@ -0,0 +1,195 @@
+// client_test.go 用 httptest 伺服器驗證用戶端行為：分頁（limit=50）、
+// 認證表頭、逾時與錯誤映射（連線失敗、401、5xx → *ErrAPI）。
+package gitea
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// newTestClient 對 srv 建立用戶端。
+func newTestClient(srvURL, token string, timeout time.Duration) (*Client, error) {
+	return New(srvURL, token, timeout)
+}
+
+func TestNewRejectsInvalidBaseURL(t *testing.T) {
+	for _, bad := range []string{"", "not a url", "http://"} {
+		if _, err := New(bad, "", 0); err == nil {
+			t.Errorf("New(%q) should fail", bad)
+		}
+	}
+}
+
+func TestClientSendsTokenHeader(t *testing.T) {
+	var gotAuth atomic.Value
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth.Store(r.Header.Get("Authorization"))
+		fmt.Fprint(w, `{"login":"max"}`)
+	}))
+	defer srv.Close()
+
+	c, err := newTestClient(srv.URL, "secret-token", time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out map[string]any
+	if err := c.GetJSON(context.Background(), "/user", &out); err != nil {
+		t.Fatal(err)
+	}
+	if got := gotAuth.Load(); got != "token secret-token" {
+		t.Fatalf("Authorization header = %v, want token secret-token", got)
+	}
+}
+
+func TestErrAPIMessageHasNoToken(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer srv.Close()
+
+	c, err := newTestClient(srv.URL, "secret-token", time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = c.GetJSON(context.Background(), "/user", nil)
+	var apiErr *ErrAPI
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("want *ErrAPI, got %v", err)
+	}
+	if apiErr.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("status = %d, want 401", apiErr.StatusCode)
+	}
+	if got := apiErr.Error(); got == "" || contains(got, "secret-token") {
+		t.Fatalf("error message must not leak token, got %q", got)
+	}
+}
+
+func TestListAllPaginatesWithLimitFifty(t *testing.T) {
+	var calls int32
+	var limits []int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		limit := int32(0)
+		fmt.Sscanf(r.URL.Query().Get("limit"), "%d", &limit)
+		limits = append(limits, limit)
+		page := 1
+		fmt.Sscanf(r.URL.Query().Get("page"), "%d", &page)
+		// 第 1、2 頁各滿 50 筆，第 3 頁 10 筆後結束。
+		total := 110
+		start := (page - 1) * 50
+		end := start + 50
+		if end > total {
+			end = total
+		}
+		w.Header().Set("Content-Type", "application/json")
+		if start >= total {
+			fmt.Fprint(w, "[]")
+			return
+		}
+		items := make([]int, 0, end-start)
+		for i := start; i < end; i++ {
+			items = append(items, i)
+		}
+		_ = json.NewEncoder(w).Encode(items)
+	}))
+	defer srv.Close()
+
+	c, err := newTestClient(srv.URL, "", time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got []int
+	if err := c.ListAll(context.Background(), "/things", ListOptions{}, &got); err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 110 {
+		t.Fatalf("want 110 items, got %d", len(got))
+	}
+	for i, v := range got {
+		if v != i {
+			t.Fatalf("item %d = %d, want %d", i, v, i)
+		}
+	}
+	if n := atomic.LoadInt32(&calls); n != 3 {
+		t.Fatalf("want 3 page requests, got %d", n)
+	}
+	for i, l := range limits {
+		if l != 50 {
+			t.Fatalf("page %d limit = %d, want 50", i+1, l)
+		}
+	}
+}
+
+func TestListAllRejectsBadOut(t *testing.T) {
+	c, err := newTestClient("https://gitea.alterminal.com", "", time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var notSlice int
+	if err := c.ListAll(context.Background(), "/x", ListOptions{}, &notSlice); err == nil {
+		t.Fatal("non-slice out should error")
+	}
+	preloaded := []int{1}
+	if err := c.ListAll(context.Background(), "/x", ListOptions{}, &preloaded); err == nil {
+		t.Fatal("non-empty out should error")
+	}
+}
+
+func TestClientTimeoutSurfacesAsErrAPI(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(200 * time.Millisecond)
+		fmt.Fprint(w, `{}`)
+	}))
+	defer srv.Close()
+
+	c, err := newTestClient(srv.URL, "", 50*time.Millisecond)
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = c.GetJSON(context.Background(), "/user", nil)
+	var apiErr *ErrAPI
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("timeout should surface as *ErrAPI, got %v", err)
+	}
+	if apiErr.StatusCode != 0 {
+		t.Fatalf(" StatusCode should be 0 for transport error, got %d", apiErr.StatusCode)
+	}
+}
+
+func TestClientServerFiveHundred(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	c, err := newTestClient(srv.URL, "", time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = c.GetJSON(context.Background(), "/user", nil)
+	var apiErr *ErrAPI
+	if !errors.As(err, &apiErr) || apiErr.StatusCode != 500 {
+		t.Fatalf("want *ErrAPI with 500, got %v", err)
+	}
+}
+
+// contains 是簡單子字串檢查（避免只為此引入 strings 到測試以外的地方）。
+func contains(s, sub string) bool {
+	return len(s) >= len(sub) && (s == sub || len(sub) == 0 || indexOf(s, sub) >= 0)
+}
+
+func indexOf(s, sub string) int {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return i
+		}
+	}
+	return -1
+}
@@ -0,0 +1,421 @@
+// config.go — tea 相容登入組態的讀取與行級編輯。
+//
+// teai 與 tea 共用同一份組態檔（README 設計原則 5），因此寫入採「行級編輯」：
+// 只修改目標登入項目的所屬行，其餘內容（未知欄位、註解、preferences 區段、
+// 空行與縮排）逐字保留，避免改壞 tea 也在使用的檔案。新增項目依 tea 實際
+// 寫出的欄位順序輸出，讓檔案外觀與 tea 一致。
+//
+// token 值只會進出這個套件的資料結構與組態檔本身，永遠不出現在錯誤訊息。
+package gitea
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// LoginEntry 是組態檔中的一筆登入資料（編輯用，含 tea 的 user 欄位）。
+type LoginEntry struct {
+	Name    string
+	URL     string
+	Token   string
+	Default bool
+	User    string
+}
+
+// loginItemSpan 標記 logins 清單中一個項目在檔案中的行範圍 [start, end)。
+type loginItemSpan struct {
+	name  string
+	start int
+	end   int
+}
+
+// configDoc 是解析後的組態檔：原始行與 logins 項目的位置資訊。
+type configDoc struct {
+	lines        []string
+	items        []loginItemSpan
+	loginsHeader int    // 「logins:」所在行；-1 表示沒有
+	itemIndent   string // 項目行的縮排（取第一個項目）；預設四格空白
+}
+
+// parseConfigDoc 掃描組態內容，定位 logins 清單與各項目的行範圍。
+// 只認識 tea 實際寫出的格式：頂層 `logins:` 加縮排的 `- key: value` 項目；
+// 其餘行原樣保留在 lines 中。
+func parseConfigDoc(data []byte) configDoc {
+	doc := configDoc{lines: splitLines(data), loginsHeader: -1, itemIndent: "    "}
+	inLogins := false
+	cur := -1
+	for i, raw := range doc.lines {
+		line := raw
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		indent := line[:len(line)-len(strings.TrimLeft(line, " "))]
+		if indent == "" {
+			if inLogins && doc.loginsHeader >= 0 {
+				// 離開 logins 區段；listEnd 由最後一個項目的 end 決定，這裡不用記。
+			}
+			inLogins = strings.HasPrefix(trimmed, "logins:")
+			if inLogins && doc.loginsHeader < 0 {
+				doc.loginsHeader = i
+			}
+			cur = -1
+			continue
+		}
+		if !inLogins {
+			continue
+		}
+		if strings.HasPrefix(trimmed, "- ") || trimmed == "-" {
+			if cur >= 0 {
+				doc.items[cur].end = i
+			}
+			doc.items = append(doc.items, loginItemSpan{start: i, end: i + 1})
+			cur = len(doc.items) - 1
+			if len(doc.items) == 1 {
+				doc.itemIndent = indent
+			}
+			if rest := strings.TrimSpace(strings.TrimPrefix(trimmed, "-")); rest != "" {
+				if key, value, ok := strings.Cut(rest, ":"); ok && strings.TrimSpace(key) == "name" {
+					doc.items[cur].name = unquoteYAML(strings.TrimSpace(value))
+				}
+			}
+			continue
+		}
+		if cur >= 0 {
+			doc.items[cur].end = i + 1
+		}
+	}
+	return doc
+}
+
+// findItem 依名稱找項目；找不到回 -1。
+func (d configDoc) findItem(name string) int {
+	for i, it := range d.items {
+		if it.name == name {
+			return i
+		}
+	}
+	return -1
+}
+
+// fieldIndent 回傳項目內屬性行的縮排（項目縮排 + 兩格，tea 的格式）。
+func (d configDoc) fieldIndent() string {
+	return d.itemIndent + "  "
+}
+
+// entryAt 取某個項目的完整欄位值。
+func (d configDoc) entryAt(it loginItemSpan) LoginEntry {
+	var e LoginEntry
+	apply := func(kv string) {
+		key, value, ok := strings.Cut(kv, ":")
+		if !ok {
+			return
+		}
+		key = strings.TrimSpace(key)
+		value = unquoteYAML(strings.TrimSpace(value))
+		switch key {
+		case "name":
+			e.Name = value
+		case "url":
+			e.URL = value
+		case "token":
+			e.Token = value
+		case "default":
+			e.Default = value == "true"
+		case "user":
+			e.User = value
+		}
+	}
+	first := strings.TrimSpace(d.lines[it.start])
+	if rest := strings.TrimSpace(strings.TrimPrefix(first, "-")); rest != "" {
+		apply(rest)
+	}
+	for i := it.start + 1; i < it.end; i++ {
+		if kv := strings.TrimSpace(d.lines[i]); kv != "" && !strings.HasPrefix(kv, "#") {
+			apply(kv)
+		}
+	}
+	return e
+}
+
+// ListLogins 回傳組態內容中的所有登入（依檔案順序）。
+func ListLogins(data []byte) []LoginEntry {
+	doc := parseConfigDoc(data)
+	out := make([]LoginEntry, 0, len(doc.items))
+	for _, it := range doc.items {
+		out = append(out, doc.entryAt(it))
+	}
+	return out
+}
+
+// ListLoginsFile 讀取組態檔並列出登入；檔案不存在視為空清單（非錯誤）。
+func ListLoginsFile(path string) ([]LoginEntry, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return ListLogins(data), nil
+}
+
+// UpsertLogin 新增或更新名為 e.Name 的登入。
+//
+// 已存在則就地更新 url/token/user/default（保留其他欄位與行）；不存在則
+// 依 tea 的欄位順序插入新項目。makeDefault 為 true 時將其設為預設並取消
+// 其他登入的預設旗標；新增後若成為唯一登入也自動成為預設。
+// 回傳新內容與最終生效的項目值。
+func UpsertLogin(data []byte, e LoginEntry, makeDefault bool) ([]byte, LoginEntry, error) {
+	if strings.TrimSpace(e.Name) == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login name must not be empty")
+	}
+	if strings.TrimSpace(e.URL) == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login url must not be empty")
+	}
+	if e.Token == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login token must not be empty")
+	}
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(e.Name)
+	if idx >= 0 {
+		existing := doc.entryAt(doc.items[idx])
+		wantDefault := existing.Default || makeDefault
+		it := doc.items[idx]
+		lines := doc.lines
+		// 就地替換各欄位；缺少的欄位補在項目結尾。
+		for _, kv := range []struct{ key, value string }{
+			{"name", yamlScalar(e.Name)},
+			{"url", yamlScalar(e.URL)},
+			{"token", yamlScalar(e.Token)},
+			{"user", yamlScalar(e.User)},
+			{"default", strconv.FormatBool(wantDefault)},
+		} {
+			lines = setFieldInItem(lines, it, kv.key, kv.value, doc.fieldIndent())
+		}
+		out := joinLines(lines)
+		if wantDefault {
+			var err error
+			out, err = SetDefaultLogin(out, e.Name)
+			if err != nil {
+				return nil, LoginEntry{}, err
+			}
+		}
+		final := existing
+		final.URL, final.Token, final.User = e.URL, e.Token, e.User
+		final.Default = wantDefault
+		return out, final, nil
+	}
+
+	// 新增項目。
+	wantDefault := makeDefault || len(doc.items) == 0
+	block := newLoginBlock(doc.itemIndent, e.Name, e.URL, e.Token, wantDefault, e.User)
+	var lines []string
+	var insertAt int
+	if doc.loginsHeader < 0 {
+		if len(doc.lines) == 0 {
+			lines = []string{"logins:"}
+		} else {
+			lines = append(slices.Clone(doc.lines), "", "logins:")
+		}
+		insertAt = len(lines)
+	} else {
+		lines = slices.Clone(doc.lines)
+		// 「logins: []」是空清單的串流寫法，直接接項目會變無效 YAML；改回區段寫法。
+		if len(doc.items) == 0 && strings.TrimSpace(lines[doc.loginsHeader]) == "logins: []" {
+			lines[doc.loginsHeader] = "logins:"
+		}
+		if len(doc.items) > 0 {
+			insertAt = doc.items[len(doc.items)-1].end
+		} else {
+			insertAt = doc.loginsHeader + 1
+		}
+	}
+	out := append(slices.Clone(lines[:insertAt]), block...)
+	out = append(out, lines[insertAt:]...)
+	data2 := joinLines(out)
+	if wantDefault {
+		var err error
+		data2, err = SetDefaultLogin(data2, e.Name)
+		if err != nil {
+			return nil, LoginEntry{}, err
+		}
+	}
+	return data2, LoginEntry{
+		Name:    e.Name,
+		URL:     e.URL,
+		Token:   e.Token,
+		Default: wantDefault,
+		User:    e.User,
+	}, nil
+}
+
+// SetDefaultLogin 把名為 name 的登入設為預設，其餘一律取消預設。
+func SetDefaultLogin(data []byte, name string) ([]byte, error) {
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(name)
+	if idx < 0 {
+		return nil, fmt.Errorf("gitea: login %q not found", name)
+	}
+	lines := doc.lines
+	// 反序處理：前面的插入不影響後面已算好的行範圍，這裡的反序則保證
+	// 後方項目的插入/修改不會推移前方項目的範圍。
+	for i := len(doc.items) - 1; i >= 0; i-- {
+		want := "false"
+		if i == idx {
+			want = "true"
+		}
+		lines = setFieldInItem(lines, doc.items[i], "default", want, doc.fieldIndent())
+	}
+	return joinLines(lines), nil
+}
+
+// RemoveLogin 移除名為 name 的登入。若被移除者是預設且還有其他登入，
+// 剩下的第一筆自動遞補為預設。回傳新內容與遞補後的預設名稱（無則空字串）。
+func RemoveLogin(data []byte, name string) ([]byte, string, error) {
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(name)
+	if idx < 0 {
+		return nil, "", fmt.Errorf("gitea: login %q not found", name)
+	}
+	removed := doc.entryAt(doc.items[idx])
+	it := doc.items[idx]
+	lines := slices.Delete(slices.Clone(doc.lines), it.start, it.end)
+	out := joinLines(lines)
+	promoted := ""
+	if removed.Default {
+		rest := ListLogins(out)
+		if len(rest) > 0 {
+			promoted = rest[0].Name
+			var err error
+			out, err = SetDefaultLogin(out, promoted)
+			if err != nil {
+				return nil, "", err
+			}
+		}
+	}
+	return out, promoted, nil
+}
+
+// setFieldInItem 把項目內 key 的值換成 value，保留該行的原始縮排；
+// key 不存在時以 fieldIndent 插在項目結尾。回傳新的行切片。
+func setFieldInItem(lines []string, it loginItemSpan, key, value, fieldIndent string) []string {
+	first := lines[it.start]
+	trimmed := strings.TrimSpace(first)
+	if rest := strings.TrimSpace(strings.TrimPrefix(trimmed, "-")); rest != "" {
+		if k, _, ok := strings.Cut(rest, ":"); ok && strings.TrimSpace(k) == key {
+			prefix := first[:strings.Index(first, "-")] + "- "
+			lines[it.start] = prefix + key + ": " + value
+			return lines
+		}
+	}
+	for i := it.start + 1; i < it.end; i++ {
+		t := strings.TrimSpace(lines[i])
+		if k, _, ok := strings.Cut(t, ":"); ok && strings.TrimSpace(k) == key {
+			indent := lines[i][:len(lines[i])-len(strings.TrimLeft(lines[i], " "))]
+			lines[i] = indent + key + ": " + value
+			return lines
+		}
+	}
+	out := append(slices.Clone(lines[:it.end]), fieldIndent+key+": "+value)
+	return append(out, lines[it.end:]...)
+}
+
+// newLoginBlock 產生 tea 格式的新登入項目（欄位順序與 tea 實際寫出的一致）。
+func newLoginBlock(itemIndent, name, url, token string, isDefault bool, user string) []string {
+	f := itemIndent + "  "
+	return []string{
+		itemIndent + "- name: " + yamlScalar(name),
+		f + "url: " + yamlScalar(url),
+		f + "token: " + yamlScalar(token),
+		f + "default: " + strconv.FormatBool(isDefault),
+		f + `ssh_host: ""`,
+		f + `ssh_key: ""`,
+		f + "insecure: false",
+		f + `ssh_certificate_principal: ""`,
+		f + "ssh_agent: false",
+		f + `ssh_key_agent_pub: ""`,
+		f + "version_check: false",
+		f + "user: " + yamlScalar(user),
+		f + "created: 0",
+	}
+}
+
+// plainScalar 是可以不加引號直接寫出的 YAML 純量。
+var plainScalar = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:/~+=@-]*$`)
+
+// yamlScalar 把值寫成 YAML 純量：安全字元集直接輸出，其餘加雙引號。
+func yamlScalar(s string) string {
+	if plainScalar.MatchString(s) {
+		return s
+	}
+	return strconv.Quote(s)
+}
+
+// HostOf 取 URL 的主機部分（連埠，小寫）；解析失敗回空字串。
+// 供比對「同一站點」的登入時使用。
+func HostOf(rawURL string) string { return hostOf(rawURL) }
+
+// splitLines 把內容拆成行（去掉行尾換行與 CR）。
+func splitLines(data []byte) []string {
+	if len(data) == 0 {
+		return nil
+	}
+	s := strings.TrimSuffix(string(data), "\n")
+	if s == "" {
+		return []string{""}
+	}
+	return strings.Split(s, "\n")
+}
+
+// joinLines 把行組回內容，保證以單一換行結尾。
+func joinLines(lines []string) []byte {
+	if len(lines) == 0 {
+		return nil
+	}
+	s := strings.Join(lines, "\n")
+	if !strings.HasSuffix(s, "\n") {
+		s += "\n"
+	}
+	return []byte(s)
+}
+
+// SaveTeaConfigFile 把組態內容原子寫入 path：先寫同目錄暫存檔（0600），
+// 再 rename 取代，避免半寫入狀態。必要時建立上層目錄（0700）。
+func SaveTeaConfigFile(path string, data []byte) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return fmt.Errorf("gitea: create config dir: %w", err)
+	}
+	tmp, err := os.CreateTemp(dir, ".config-*.yml")
+	if err != nil {
+		return fmt.Errorf("gitea: create temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer func() {
+		if tmpName != "" {
+			_ = os.Remove(tmpName)
+		}
+	}()
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return fmt.Errorf("gitea: write temp file: %w", err)
+	}
+	if err := tmp.Chmod(0o600); err != nil {
+		tmp.Close()
+		return fmt.Errorf("gitea: chmod temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("gitea: close temp file: %w", err)
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		return fmt.Errorf("gitea: rename config: %w", err)
+	}
+	tmpName = "" // 已改名成功，不必清理。
+	return nil
+}
@@ -0,0 +1,263 @@
+// config_test.go 驗證 tea 相容組態的行級編輯：新增、更新、設預設、
+// 移除，以及「未知欄位與其他區段逐字保留」的關鍵性質。
+package gitea
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// realWorldTeaConfig 是 tea 實際寫出的組態（含 ssh_* 等未知欄位與 preferences）。
+const realWorldTeaConfig = `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: tok-1
+      default: true
+      ssh_host: ""
+      ssh_key: ""
+      insecure: false
+      ssh_certificate_principal: ""
+      ssh_agent: false
+      ssh_key_agent_pub: ""
+      version_check: false
+      user: ceo
+      created: 0
+preferences:
+    editor: false
+    flag_defaults:
+        remote: ""
+`
+
+func TestListLoginsParsesAllEntries(t *testing.T) {
+	logins := ListLogins([]byte(realWorldTeaConfig))
+	if len(logins) != 1 {
+		t.Fatalf("want 1 login, got %d", len(logins))
+	}
+	l := logins[0]
+	if l.Name != "alterminal" || l.URL != "https://gitea.alterminal.com" || l.Token != "tok-1" || !l.Default || l.User != "ceo" {
+		t.Fatalf("unexpected entry: %+v", l)
+	}
+}
+
+func TestUpsertLoginUpdatesExistingPreservesRest(t *testing.T) {
+	out, final, err := UpsertLogin([]byte(realWorldTeaConfig), LoginEntry{
+		Name: "alterminal", URL: "https://gitea.alterminal.com", Token: "tok-2", User: "ceo",
+	}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(out)
+	// 更新 token、保留其他欄位。
+	if !strings.Contains(s, "token: tok-2") || strings.Contains(s, "tok-1") {
+		t.Fatalf("token not updated:\n%s", s)
+	}
+	for _, want := range []string{
+		"ssh_host: \"\"", "insecure: false", "ssh_key_agent_pub: \"\"",
+		"user: ceo", "created: 0", "default: true",
+		"preferences:", "editor: false", "flag_defaults:", `remote: ""`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Fatalf("missing %q after edit:\n%s", want, s)
+		}
+	}
+	if final.Default != true {
+		t.Fatalf("existing default should stay default, got %+v", final)
+	}
+	// 編輯後仍可解析出正確值。
+	logins := ListLogins(out)
+	if len(logins) != 1 || logins[0].Token != "tok-2" || !logins[0].Default {
+		t.Fatalf("reparse mismatch: %+v", logins)
+	}
+}
+
+func TestUpsertLoginAppendsNewAndMakesDefault(t *testing.T) {
+	out, final, err := UpsertLogin([]byte(realWorldTeaConfig), LoginEntry{
+		Name: "second", URL: "https://git.example.com", Token: "tok-b", User: "bob",
+	}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 2 {
+		t.Fatalf("want 2 logins, got %d:\n%s", len(logins), out)
+	}
+	if logins[0].Default || !logins[1].Default {
+		t.Fatalf("only the new login should be default: %+v", logins)
+	}
+	if logins[1].Name != "second" || logins[1].Token != "tok-b" || logins[1].User != "bob" {
+		t.Fatalf("new entry mismatch: %+v", logins[1])
+	}
+	if !final.Default {
+		t.Fatalf("final should be default: %+v", final)
+	}
+	// tea 的欄位順序仍在。
+	s := string(out)
+	if !strings.Contains(s, "    - name: second\n") {
+		t.Fatalf("new item not appended in tea style:\n%s", s)
+	}
+}
+
+func TestUpsertLoginFirstEverLoginCreatesSection(t *testing.T) {
+	out, final, err := UpsertLogin(nil, LoginEntry{
+		Name: "only", URL: "https://gitea.alterminal.com", Token: "tok", User: "ceo",
+	}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 1 || !logins[0].Default || logins[0].Token != "tok" {
+		t.Fatalf("first login should auto-default: %s", out)
+	}
+	if !final.Default {
+		t.Fatalf("final should be default: %+v", final)
+	}
+	if !strings.HasPrefix(string(out), "logins:\n") {
+		t.Fatalf("section not created:\n%s", out)
+	}
+}
+
+func TestUpsertLoginRejectsBadInput(t *testing.T) {
+	cases := []LoginEntry{
+		{Name: "", URL: "https://x", Token: "t"},
+		{Name: "n", URL: "  ", Token: "t"},
+		{Name: "n", URL: "https://x", Token: ""},
+	}
+	for _, e := range cases {
+		if _, _, err := UpsertLogin(nil, e, true); err == nil {
+			t.Errorf("UpsertLogin(%+v) should fail", e)
+		}
+	}
+}
+
+func TestSetDefaultLoginSwitchesFlag(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	out, err := SetDefaultLogin([]byte(cfg), "b")
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if logins[0].Default || !logins[1].Default {
+		t.Fatalf("default flag not switched:\n%s", out)
+	}
+	// b 之後的內容（如有）不受影響。
+	if !strings.Contains(string(out), "token: ta") || !strings.Contains(string(out), "token: tb") {
+		t.Fatalf("tokens lost:\n%s", out)
+	}
+}
+
+func TestSetDefaultLoginUnknownNameErrors(t *testing.T) {
+	if _, err := SetDefaultLogin([]byte(realWorldTeaConfig), "nope"); err == nil {
+		t.Fatal("unknown name should error")
+	}
+}
+
+func TestRemoveLoginPromotesNextDefault(t *testing.T) {
+	// 第二個登入放在 logins 區段內（preferences 之前）。
+	cfg := `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: tok-1
+      default: true
+      user: ceo
+    - name: backup
+      url: https://backup.example.com
+      token: tb
+      default: false
+preferences:
+    editor: false
+`
+	out, promoted, err := RemoveLogin([]byte(cfg), "alterminal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if promoted != "backup" {
+		t.Fatalf("promoted = %q, want backup:\n%s", promoted, out)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 1 || logins[0].Name != "backup" || !logins[0].Default {
+		t.Fatalf("remaining login mismatch: %+v", logins)
+	}
+	if strings.Contains(string(out), "tok-1") || strings.Contains(string(out), "name: alterminal") {
+		t.Fatalf("login not fully removed:\n%s", out)
+	}
+}
+
+func TestRemoveLoginLastOne(t *testing.T) {
+	out, promoted, err := RemoveLogin([]byte(realWorldTeaConfig), "alterminal")
+	if err != nil || promoted != "" {
+		t.Fatalf("want clean removal, promoted=%q err=%v", promoted, err)
+	}
+	if strings.Contains(string(out), "alterminal") {
+		t.Fatalf("login not removed:\n%s", out)
+	}
+	if !strings.Contains(string(out), "preferences:") {
+		t.Fatalf("preferences section lost:\n%s", out)
+	}
+}
+
+func TestSaveTeaConfigFileAtomicAndMode(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tea", "config.yml")
+	if err := SaveTeaConfigFile(path, []byte("logins: []\n")); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("perm = %v, want 0600", info.Mode().Perm())
+	}
+	// 再寫一次（覆蓋既有檔），不留暫存殘檔。
+	if err := SaveTeaConfigFile(path, []byte("logins: []\n# v2\n")); err != nil {
+		t.Fatal(err)
+	}
+	entries, _ := os.ReadDir(filepath.Dir(path))
+	if len(entries) != 1 {
+		for _, e := range entries {
+			t.Logf("leftover: %s", e.Name())
+		}
+		t.Fatalf("want exactly 1 file, got %d", len(entries))
+	}
+	data, _ := os.ReadFile(path)
+	if !bytes.Contains(data, []byte("# v2")) {
+		t.Fatalf("overwrite failed: %s", data)
+	}
+}
+
+func TestSplitJoinLinesRoundTrip(t *testing.T) {
+	original := "a\nb\n"
+	got := string(joinLines(splitLines([]byte(original))))
+	if got != original {
+		t.Fatalf("round trip: %q", got)
+	}
+	if joinLines(splitLines(nil)) != nil {
+		t.Fatal("nil input should stay nil")
+	}
+}
+
+func TestYamlScalarQuoting(t *testing.T) {
+	cases := map[string]string{
+		"https://gitea.alterminal.com": "https://gitea.alterminal.com", // 含 : 與 / 的純量在 YAML 合法，不必引號
+		"tok-abc_123":                  "tok-abc_123",
+		"has space":                    `"has space"`,
+		"ceo":                          "ceo",
+	}
+	for in, want := range cases {
+		if got := yamlScalar(in); got != want {
+			t.Errorf("yamlScalar(%q) = %s, want %s", in, got, want)
+		}
+	}
+}
@@ -0,0 +1,228 @@
+// output.go — 共用輸出：JSON（預設）與 table（人工抽查）。
+//
+// 命令把結果包成 Values（欄位順序即輸出順序），再由 output 依格式輸出。
+// 這個設計讓同一份結果可以同時餵 JSON 與 table，不需要各自重組。
+package gitea
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// Values 是一組已排序的欄位值（依 Field 順序）。
+type Values []any
+
+// Format 是輸出格式。
+type Format int
+
+const (
+	// FormatJSON 輸出 JSON（預設）。
+	FormatJSON Format = iota
+	// FormatTable 輸出對齊的文字表格。
+	FormatTable
+)
+
+// ParseFormat 解析 --output 的值；不認得的值回傳錯誤。
+func ParseFormat(s string) (Format, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "", "json":
+		return FormatJSON, nil
+	case "table":
+		return FormatTable, nil
+	default:
+		return FormatJSON, fmt.Errorf("invalid output format %q (want json or table)", s)
+	}
+}
+
+// Field 描述 table 輸出的一欄。
+type Field struct {
+	// Name 是欄位名（JSON 鍵與 table 表頭）。
+	Name string
+	// ValueFmt 是值的格式化函式；nil 時用預設（fmt.Sprint + JSON 引號字串）。
+	ValueFmt func(v any) string
+}
+
+// Printer 依格式輸出結果。
+type Printer struct {
+	// Format 是輸出格式。
+	Format Format
+	// Out 是輸出目標。
+	Out io.Writer
+}
+
+// PrintList 輸出清單。fields 定義欄位；rows 是每一列的欄位值。
+// JSON 模式輸出物件陣列；table 模式輸出對齊表格。
+func (p Printer) PrintList(fields []Field, rows []Values) error {
+	if p.Format == FormatTable {
+		return p.printTable(fields, rows)
+	}
+	w := p.Out
+	if len(rows) == 0 {
+		_, err := fmt.Fprintln(w, "[]")
+		return err
+	}
+	if _, err := fmt.Fprint(w, "["); err != nil {
+		return err
+	}
+	for i, row := range rows {
+		if i > 0 {
+			if _, err := fmt.Fprint(w, ","); err != nil {
+				return err
+			}
+		}
+		b, err := json.Marshal(mapOf(fields, row))
+		if err != nil {
+			return err
+		}
+		if _, err := w.Write(b); err != nil {
+			return err
+		}
+	}
+	_, err := fmt.Fprintln(w, "]")
+	return err
+}
+
+// PrintOne 輸出單一結果（物件）；v 已是可 JSON 化的值。
+// table 模式輸出 key: value 行。
+func (p Printer) PrintOne(fields []Field, row Values) error {
+	if p.Format == FormatTable {
+		return p.printTable(fields, []Values{row})
+	}
+	b, err := json.Marshal(mapOf(fields, row))
+	if err != nil {
+		return err
+	}
+	_, err = fmt.Fprintln(p.Out, string(b))
+	return err
+}
+
+// PrintNull 輸出「沒有結果」的 JSON null（table 模式輸出提示行）。
+func (p Printer) PrintNull() error {
+	if p.Format == FormatTable {
+		_, err := fmt.Fprintln(p.Out, "(none)")
+		return err
+	}
+	_, err := fmt.Fprintln(p.Out, "null")
+	return err
+}
+
+// printTable 印出對齊表格：表頭、分隔線、資料列。
+func (p Printer) printTable(fields []Field, rows []Values) error {
+	headers := make([]string, len(fields))
+	cells := make([][]string, len(rows))
+	for i, f := range fields {
+		headers[i] = f.Name
+	}
+	for r, row := range rows {
+		cells[r] = make([]string, len(fields))
+		for i := range fields {
+			cells[r][i] = formatValue(fields[i], row[i])
+		}
+	}
+	widths := make([]int, len(fields))
+	for i, h := range headers {
+		widths[i] = runeLen(h)
+	}
+	for _, row := range cells {
+		for i, c := range row {
+			if l := runeLen(c); l > widths[i] {
+				widths[i] = l
+			}
+		}
+	}
+	var b strings.Builder
+	for i, h := range headers {
+		fmt.Fprintf(&b, "%-*s", widths[i], h)
+		if i < len(headers)-1 {
+			b.WriteString("  ")
+		}
+	}
+	b.WriteString("\n")
+	for i := range fields {
+		fmt.Fprintf(&b, "%s", strings.Repeat("─", widths[i]))
+		if i < len(fields)-1 {
+			b.WriteString("  ")
+		}
+	}
+	b.WriteString("\n")
+	for _, row := range cells {
+		for i, c := range row {
+			fmt.Fprintf(&b, "%-*s", widths[i], c)
+			if i < len(fields)-1 {
+				b.WriteString("  ")
+				_ = i
+			}
+		}
+		b.WriteString("\n")
+	}
+	_, err := fmt.Fprint(p.Out, b.String())
+	return err
+}
+
+// mapOf 把欄位與值組成 JSON 物件用的 map（保留欄位順序由 encoding/json
+// 處理：map 會排序鍵，因此改用自組 slice 結構以保順序——見 marshalObject）。
+func mapOf(fields []Field, row Values) any {
+	if len(row) != len(fields) {
+		return nil
+	}
+	return orderedObject{fields, row}
+}
+
+// orderedObject 以欄位順序輸出 JSON 物件（避免 map 排序破壞欄位序）。
+type orderedObject struct {
+	fields []Field
+	row    Values
+}
+
+// MarshalJSON 按欄位順序輸出。
+func (o orderedObject) MarshalJSON() ([]byte, error) {
+	var b strings.Builder
+	b.WriteByte('{')
+	for i, f := range o.fields {
+		if i > 0 {
+			b.WriteByte(',')
+		}
+		k, err := json.Marshal(f.Name)
+		if err != nil {
+			return nil, err
+		}
+		b.Write(k)
+		b.WriteByte(':')
+		v, err := json.Marshal(o.row[i])
+		if err != nil {
+			return nil, err
+		}
+		b.Write(v)
+	}
+	b.WriteByte('}')
+	return []byte(b.String()), nil
+}
+
+// formatValue 把欄位值格式化為 table 用字串；nil → 空字串。
+func formatValue(f Field, v any) string {
+	if v == nil {
+		return ""
+	}
+	if f.ValueFmt != nil {
+		return f.ValueFmt(v)
+	}
+	switch x := v.(type) {
+	case string:
+		return x
+	case fmt.Stringer:
+		return x.String()
+	default:
+		return fmt.Sprint(x)
+	}
+}
+
+// runeLen 回傳字串的 rune 數（表格寬度用，CJK 後續可再調）。
+func runeLen(s string) int {
+	n := 0
+	for range s {
+		n++
+	}
+	return n
+}
@@ -0,0 +1,88 @@
+// output_test.go 驗證共用輸出：JSON 物件順序、空清單、table 對齊與
+// 格式解析。
+package gitea
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+var demoFields = []Field{
+	{Name: "type"},
+	{Name: "number"},
+}
+
+func TestPrintListJSON(t *testing.T) {
+	var b bytes.Buffer
+	p := Printer{Format: FormatJSON, Out: &b}
+	err := p.PrintList(demoFields, []Values{{"issue", 5}, {"pull", 7}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got []map[string]any
+	if err := json.Unmarshal(b.Bytes(), &got); err != nil {
+		t.Fatalf("invalid JSON %q: %v", b.String(), err)
+	}
+	if len(got) != 2 || got[0]["type"] != "issue" || got[1]["number"] != float64(7) {
+		t.Fatalf("unexpected payload: %v", got)
+	}
+}
+
+func TestPrintListEmptyJSONArray(t *testing.T) {
+	var b bytes.Buffer
+	p := Printer{Format: FormatJSON, Out: &b}
+	if err := p.PrintList(demoFields, nil); err != nil {
+		t.Fatal(err)
+	}
+	if strings.TrimSpace(b.String()) != "[]" {
+		t.Fatalf("want [], got %q", b.String())
+	}
+}
+
+func TestPrintNull(t *testing.T) {
+	var b bytes.Buffer
+	p := Printer{Format: FormatJSON, Out: &b}
+	if err := p.PrintNull(); err != nil {
+		t.Fatal(err)
+	}
+	if strings.TrimSpace(b.String()) != "null" {
+		t.Fatalf("want null, got %q", b.String())
+	}
+}
+
+func TestPrintTable(t *testing.T) {
+	var b bytes.Buffer
+	p := Printer{Format: FormatTable, Out: &b}
+	if err := p.PrintList(demoFields, []Values{{"issue", 5}}); err != nil {
+		t.Fatal(err)
+	}
+	out := b.String()
+	for _, want := range []string{"type", "number", "issue", "5"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("table missing %q:\n%s", want, out)
+		}
+	}
+	if !strings.Contains(out, "─") {
+		t.Fatalf("table should have separator:\n%s", out)
+	}
+}
+
+func TestParseFormat(t *testing.T) {
+	for in, want := range map[string]Format{
+		"":        FormatJSON,
+		"json":    FormatJSON,
+		"JSON":    FormatJSON,
+		"table":   FormatTable,
+		" Table ": FormatTable,
+	} {
+		got, err := ParseFormat(in)
+		if err != nil || got != want {
+			t.Errorf("ParseFormat(%q) = %v, %v; want %v", in, got, err, want)
+		}
+	}
+	if _, err := ParseFormat("yaml"); err == nil {
+		t.Error("yaml should be rejected")
+	}
+}
@@ -0,0 +1,224 @@
+// giteaapi.go — 以 internal/gitea 的 HTTP 用戶端實作 workflow.Client。
+//
+// 端點與查詢參數對照 gitea.py：清單一律帶 limit 分頁（ListAll 固定 50）；
+// issues 端點帶 type=issues（排除 PR）與 state=open；pulls 帶 state=open。
+package workflow
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"strconv"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// errNoUsername 表示 /user 回應中找不到帳號名（伺服端回應異常）。
+var errNoUsername = errors.New("gitea: GET /user: response has no username")
+
+// APIClient 是 Client 介面的 HTTP 實作，包裝 internal/gitea.Client。
+type APIClient struct {
+	Client *gitea.Client
+}
+
+// 確認 APIClient 實作 Client 介面（編譯期檢查）。
+var _ Client = (*APIClient)(nil)
+
+func (a *APIClient) CurrentUser() (string, error) {
+	var u User
+	if err := a.Client.GetJSON(context.Background(), "/user", &u); err != nil {
+		return "", err
+	}
+	name := u.Name()
+	if name == "" {
+		return "", errNoUsername
+	}
+	return name, nil
+}
+
+func (a *APIClient) ListOrgs() ([]string, error) {
+	var orgs []Org
+	if err := a.Client.ListAll(context.Background(), "/user/orgs", gitea.ListOptions{}, &orgs); err != nil {
+		return nil, err
+	}
+	names := make([]string, 0, len(orgs))
+	for _, o := range orgs {
+		if n := o.Account(); n != "" {
+			names = append(names, n)
+		}
+	}
+	return names, nil
+}
+
+func (a *APIClient) ListTeams(org string) ([]Team, error) {
+	var teams []Team
+	path := "/orgs/" + url.PathEscape(org) + "/teams"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &teams); err != nil {
+		return nil, err
+	}
+	return teams, nil
+}
+
+func (a *APIClient) ListTeamMembers(teamID int64) ([]string, error) {
+	var users []User
+	path := "/teams/" + strconv.FormatInt(teamID, 10) + "/members"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &users); err != nil {
+		return nil, err
+	}
+	names := make([]string, 0, len(users))
+	for i := range users {
+		if n := users[i].Name(); n != "" {
+			names = append(names, n)
+		}
+	}
+	return names, nil
+}
+
+func (a *APIClient) ListOrgRepos(org string) ([]Repo, error) {
+	var repos []Repo
+	path := "/orgs/" + url.PathEscape(org) + "/repos"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &repos); err != nil {
+		return nil, err
+	}
+	return repos, nil
+}
+
+func (a *APIClient) ListIssues(owner, repo string) ([]Issue, error) {
+	var issues []Issue
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/issues"
+	opts := gitea.ListOptions{Extra: url.Values{
+		"type":  {"issues"},
+		"state": {"open"},
+	}}
+	if err := a.Client.ListAll(context.Background(), path, opts, &issues); err != nil {
+		return nil, err
+	}
+	// /issues 也會回傳 PR（帶 pull_request 欄位）；一律排除。
+	out := make([]Issue, 0, len(issues))
+	for i := range issues {
+		if issues[i].PullRequest == nil {
+			out = append(out, issues[i])
+		}
+	}
+	return out, nil
+}
+
+func (a *APIClient) ListPulls(owner, repo string) ([]PullRequest, error) {
+	var pulls []PullRequest
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/pulls"
+	opts := gitea.ListOptions{Extra: url.Values{"state": {"open"}}}
+	if err := a.Client.ListAll(context.Background(), path, opts, &pulls); err != nil {
+		return nil, err
+	}
+	return pulls, nil
+}
+
+func (a *APIClient) ListComments(owner, repo string, number int64) ([]Comment, error) {
+	var comments []Comment
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10) + "/comments"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &comments); err != nil {
+		return nil, err
+	}
+	return comments, nil
+}
+
+// ── StalledSource 面向（#7 CLI 接線）────────────────────────────────────
+// APIClient 在 Client 之外同時實作 StalledSource（Source + CurrentUser +
+// GetIssue），讓 stalled／xrefs 命令與既有命令共用同一個 HTTP 用戶端。
+// 清單類方法直接委派 Client 同名操作，語義一致（type=issues、state=open）。
+
+// GetIssue 單一 issue 查詢（PR 亦經此端點，帶 pull_request 標記）；
+// 失敗（含 404）回 *gitea.ErrAPI，由 CLI 映射結束碼 3。
+func (a *APIClient) GetIssue(owner, repo string, number int64) (Issue, error) {
+	var issue Issue
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10)
+	if err := a.Client.GetJSON(context.Background(), path, &issue); err != nil {
+		return Issue{}, err
+	}
+	return issue, nil
+}
+
+// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)，
+// 供 stalled 父追蹤項掃描靜默略過不存在的子項（Source 介面契約）。
+func (a *APIClient) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
+	issue, err := a.GetIssue(owner, repo, number)
+	if err != nil {
+		return Issue{}, false, nil
+	}
+	return issue, true, nil
+}
+
+// IssueTimeline 回傳 issue 的 timeline 事件（Source 面向；對應 gitea.py
+// _direct_last_activity 拉取的 repos/{o}/{r}/issues/{n}/timeline）。
+// 分頁由 ListAll 處理（與 gitea.py api_get_list 的 limit=50 逐頁一致）。
+func (a *APIClient) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	var events []TimelineEvent
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10) + "/timeline"
+	if err := a.Client.ListAll(context.Background(), path, gitea.ListOptions{}, &events); err != nil {
+		return nil, err
+	}
+	return events, nil
+}
+
+// MyOrganizations 委派 ListOrgs（Source 面向）。
+func (a *APIClient) MyOrganizations() ([]string, error) { return a.ListOrgs() }
+
+// OrganizationRepositories 委派 ListOrgRepos（Source 面向）。
+func (a *APIClient) OrganizationRepositories(org string) ([]Repo, error) {
+	return a.ListOrgRepos(org)
+}
+
+// OpenIssues 委派 ListIssues（Source 面向；已排除 PR）。
+func (a *APIClient) OpenIssues(owner, repo string) ([]Issue, error) {
+	return a.ListIssues(owner, repo)
+}
+
+// OpenPulls 委派 ListPulls（Source 面向）。
+func (a *APIClient) OpenPulls(owner, repo string) ([]PullRequest, error) {
+	return a.ListPulls(owner, repo)
+}
+
+// IssueComments 委派 ListComments（Source 面向）。
+func (a *APIClient) IssueComments(owner, repo string, number int64) ([]Comment, error) {
+	return a.ListComments(owner, repo, number)
+}
+
+// ── MilestoneSource 面向（#31 跨倉庫里程碑總覽）────────────────────────
+// APIClient 在 StalledSource 之外另實作 MilestoneSource，讓 milestones
+// 總覽命令與既有命令共用同一個 HTTP 用戶端；查詢參數對照 gitea.py 的
+// list_open_milestones_for_repository／_milestone_open_issues。
+
+// OpenMilestones 回傳倉庫的 open 里程碑（GET /repos/{o}/{r}/milestones?state=open）。
+func (a *APIClient) OpenMilestones(owner, repo string) ([]Milestone, error) {
+	var ms []Milestone
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/milestones"
+	opts := gitea.ListOptions{Extra: url.Values{"state": {"open"}}}
+	if err := a.Client.ListAll(context.Background(), path, opts, &ms); err != nil {
+		return nil, err
+	}
+	return ms, nil
+}
+
+// MilestoneOpenIssues 回傳掛在指定里程碑（依名稱過濾，Gitea 以
+// milestones=<title> 查詢）的 open 條目。刻意**不**帶 type=issues——
+// PR 亦屬里程碑條目，保留兩者供覆蓋檢查（同 gitea.py
+// _milestone_open_issues；PR 帶 pull_request 標記由 workflow 判別）。
+func (a *APIClient) MilestoneOpenIssues(owner, repo, milestoneTitle string) ([]Issue, error) {
+	var issues []Issue
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/issues"
+	opts := gitea.ListOptions{Extra: url.Values{
+		"state":      {"open"},
+		"milestones": {milestoneTitle},
+	}}
+	if err := a.Client.ListAll(context.Background(), path, opts, &issues); err != nil {
+		return nil, err
+	}
+	return issues, nil
+}
+
+// 編譯期確認 APIClient 同時實作 Client、StalledSource 與 MilestoneSource。
+var _ StalledSource = (*APIClient)(nil)
+var _ MilestoneSource = (*APIClient)(nil)
@@ -0,0 +1,137 @@
+package workflow
+
+import "sort"
+
+// sortComments 依 created_at 字典序穩定排序（ISO8601 字串字典序與時間序一致），
+// 對應 gitea.py 各處的 comments.sort(key=created_at)。
+func sortComments(comments []Comment) []Comment {
+	out := append([]Comment(nil), comments...)
+	sort.SliceStable(out, func(a, b int) bool { return out[a].CreatedAt < out[b].CreatedAt })
+	return out
+}
+
+// LastComment 回傳依 created_at 排序後的最後一則留言；沒有留言回 nil。
+func LastComment(comments []Comment) *Comment {
+	ordered := sortComments(comments)
+	if len(ordered) == 0 {
+		return nil
+	}
+	return &ordered[len(ordered)-1]
+}
+
+// lastCommentAuthor 回傳最後一則留言的作者；無留言或作者未知回空字串。
+func lastCommentAuthor(comments []Comment) string {
+	if last := LastComment(comments); last != nil {
+		return last.Author()
+	}
+	return ""
+}
+
+func containsString(items []string, target string) bool {
+	for _, item := range items {
+		if item == target {
+			return true
+		}
+	}
+	return false
+}
+
+// NeedsAuthorFollowup 判定 PR 是否需要發起者跟進：有留言、且最後一則留言
+// 不是 PR 作者（gitea.py 的 _pr_needs_author_followup）。
+// 無留言或作者未知 → false（尚無留言的 PR 不列入跟進清單）。
+func NeedsAuthorFollowup(pr *PullRequest, comments []Comment) bool {
+	author := pr.Author()
+	if author == "" {
+		return false
+	}
+	last := lastCommentAuthor(comments)
+	return last != "" && last != author
+}
+
+// NeedsReviewerFollowup 判定使用者是否需要審核此 PR：被指定為審核者、
+// 不是作者、最後一則留言不是自己（含尚無留言）
+// （gitea.py 的 _pr_needs_reviewer_followup）。
+func NeedsReviewerFollowup(pr *PullRequest, comments []Comment, username string) bool {
+	if username == "" {
+		return false
+	}
+	if pr.Author() == username {
+		return false
+	}
+	if !containsString(ReviewerNames(pr), username) {
+		return false
+	}
+	return lastCommentAuthor(comments) != username
+}
+
+// ReviewerNames 回傳 PR 的 requested reviewers（去重、排序）。
+func ReviewerNames(pr *PullRequest) []string {
+	seen := map[string]bool{}
+	names := make([]string, 0, len(pr.RequestedReviewers))
+	for i := range pr.RequestedReviewers {
+		name := pr.RequestedReviewers[i].Name()
+		if name != "" && !seen[name] {
+			seen[name] = true
+			names = append(names, name)
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+// AssigneeNames 回傳 issue 的全部 assignees（assignee 欄位＋assignees 陣列，
+// 去重、排序），對應 gitea.py 的 _assignee_usernames。
+func AssigneeNames(issue *Issue) []string {
+	seen := map[string]bool{}
+	add := func(u *User) {
+		if u == nil {
+			return
+		}
+		if name := u.Name(); name != "" && !seen[name] {
+			seen[name] = true
+		}
+	}
+	add(issue.Assignee)
+	for i := range issue.Assignees {
+		add(&issue.Assignees[i])
+	}
+	names := make([]string, 0, len(seen))
+	for name := range seen {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// AssigneeOverlaps 判定 issue 是否分派給 members 中至少一人
+// （members 為空 → false，同 gitea.py filter_issues_by_assignee 的空成員集行為）。
+func AssigneeOverlaps(issue *Issue, members []string) bool {
+	if len(members) == 0 {
+		return false
+	}
+	assignees := AssigneeNames(issue)
+	for _, member := range members {
+		if member != "" && containsString(assignees, member) {
+			return true
+		}
+	}
+	return false
+}
+
+// LastCommentNotByAssignee 判定 issue 的最後一則留言是否不是任何 assignee
+// 留的（無留言 → true，視為需要處理）。
+// 注意：判定對象是該 issue 的**全部** assignees，不只是 members 中的成員
+// （gitea.py _last_comment_is_from_assignee 的語義）。
+func LastCommentNotByAssignee(issue *Issue, comments []Comment) bool {
+	last := lastCommentAuthor(comments)
+	if last == "" {
+		return true
+	}
+	return !containsString(AssigneeNames(issue), last)
+}
+
+// IssueNeedsWork 組合判定：分派給 members 中至少一人，且最後一則留言
+// 不是 assignee（gitea.py filter_issues_by_assignee 保留的項目）。
+func IssueNeedsWork(issue *Issue, comments []Comment, members []string) bool {
+	return AssigneeOverlaps(issue, members) && LastCommentNotByAssignee(issue, comments)
+}
@@ -0,0 +1,145 @@
+// judge_test.go — 驗證工作流判定語義（對照 gitea.py）：
+// 最後留言判定、作者／審核者跟進條件、assignee 交集與排序。
+package workflow
+
+import (
+	"reflect"
+	"testing"
+)
+
+// mkUser 構造 User。
+func mkUser(name string) *User { return &User{UserName: name} }
+
+func TestUserNameFallback(t *testing.T) {
+	if got := (&User{UserName: "a", Login: "b"}).Name(); got != "a" {
+		t.Errorf("username 優先，得到 %q", got)
+	}
+	if got := (&User{Login: "b"}).Name(); got != "b" {
+		t.Errorf("login 回退，得到 %q", got)
+	}
+	if got := mkUser("").Name(); got != "" {
+		t.Errorf("空帳號，得到 %q", got)
+	}
+}
+
+func TestLastComment(t *testing.T) {
+	comments := []Comment{
+		{CreatedAt: "2026-09-09T01:00:00Z", User: mkUser("alex")},
+		{CreatedAt: "2026-09-09T03:00:00Z", User: mkUser("max")},
+		{CreatedAt: "2026-09-09T02:00:00Z", User: mkUser("ceo")},
+	}
+	last := LastComment(comments)
+	if last == nil || last.Author() != "max" {
+		t.Errorf("應依 created_at 排序取最後（03:00 max），得到 %+v", last)
+	}
+	if LastComment(nil) != nil {
+		t.Errorf("無留言應回 nil")
+	}
+}
+
+func TestNeedsAuthorFollowup(t *testing.T) {
+	pr := &PullRequest{User: mkUser("alex")}
+	cases := []struct {
+		name     string
+		comments []Comment
+		want     bool
+	}{
+		{"無留言", nil, false},
+		{"最後留言是作者", []Comment{{CreatedAt: "a", User: mkUser("alex")}}, false},
+		{"最後留言是他人", []Comment{
+			{CreatedAt: "a", User: mkUser("alex")},
+			{CreatedAt: "b", User: mkUser("ceo")},
+		}, true},
+		{"留言者未知", []Comment{{CreatedAt: "a"}}, false},
+	}
+	for _, c := range cases {
+		if got := NeedsAuthorFollowup(pr, c.comments); got != c.want {
+			t.Errorf("%s：得到 %v，want %v", c.name, got, c.want)
+		}
+	}
+}
+
+func TestNeedsReviewerFollowup(t *testing.T) {
+	pr := &PullRequest{
+		User:               mkUser("max"),
+		RequestedReviewers: []User{*mkUser("alex"), *mkUser("queena")},
+	}
+	comments := []Comment{{CreatedAt: "a", User: mkUser("max")}}
+	if !NeedsReviewerFollowup(pr, comments, "alex") {
+		t.Errorf("審核者且最後留言非自己 → 應需跟進")
+	}
+	if NeedsReviewerFollowup(pr, comments, "max") {
+		t.Errorf("作者本人 → 不應列入審核清單")
+	}
+	if NeedsReviewerFollowup(pr, []Comment{{CreatedAt: "a", User: mkUser("alex")}}, "alex") {
+		t.Errorf("最後留言是自己 → 不應需跟進")
+	}
+	if NeedsReviewerFollowup(pr, comments, "ceo") {
+		t.Errorf("非審核者 → 不應需跟進")
+	}
+	// 尚無留言的 PR：審核者仍應被列入（含尚無留言）。
+	if !NeedsReviewerFollowup(pr, nil, "queena") {
+		t.Errorf("尚無留言 → 審核者應需跟進")
+	}
+}
+
+func TestAssigneeNames(t *testing.T) {
+	issue := &Issue{
+		Assignee:  mkUser("alex"),
+		Assignees: []User{*mkUser("alex"), *mkUser("max")},
+	}
+	if got := AssigneeNames(issue); !reflect.DeepEqual(got, []string{"alex", "max"}) {
+		t.Errorf("assignee 應去重排序，得到 %v", got)
+	}
+}
+
+func TestAssigneeOverlapsEmptyMembers(t *testing.T) {
+	issue := &Issue{Assignee: mkUser("alex")}
+	if AssigneeOverlaps(issue, nil) {
+		t.Errorf("成員集為空 → 不應列入（同 gitea.py filter_issues_by_assignee）")
+	}
+}
+
+func TestLastCommentNotByAssignee(t *testing.T) {
+	issue := &Issue{Assignee: mkUser("alex")}
+	if !LastCommentNotByAssignee(issue, nil) {
+		t.Errorf("無留言 → 應視為需要處理")
+	}
+	if LastCommentNotByAssignee(issue, []Comment{{CreatedAt: "a", User: mkUser("alex")}}) {
+		t.Errorf("最後留言來自 assignee → 不應列入")
+	}
+	if !LastCommentNotByAssignee(issue, []Comment{{CreatedAt: "a", User: mkUser("ceo")}}) {
+		t.Errorf("最後留言來自他人 → 應列入")
+	}
+}
+
+func TestUpdatedKeyFallbackChain(t *testing.T) {
+	i := &Issue{UpdatedAt: "", Updated: "u", CreatedAt: "c"}
+	if got := i.updatedKey(); got != "u" {
+		t.Errorf("updated 回退鏈，得到 %q", got)
+	}
+	if got := (&Issue{}).updatedKey(); got != "9999" {
+		t.Errorf("全缺 → 9999，得到 %q", got)
+	}
+}
+
+func TestFullNameFallbacks(t *testing.T) {
+	pr := &PullRequest{
+		HTMLURL: "https://gitea.alterminal.com/alterminal/teai/pulls/2",
+		Base:    &PRRef{Repo: &Repository{FullName: "alterminal/teai"}},
+	}
+	if got := pr.FullName(); got != "alterminal/teai" {
+		t.Errorf("base.repo 優先，得到 %q", got)
+	}
+	pr2 := &PullRequest{HTMLURL: "https://gitea.alterminal.com/alterminal/teai/pulls/2"}
+	if got := pr2.FullName(); got != "alterminal/teai" {
+		t.Errorf("html_url 回退，得到 %q", got)
+	}
+	i := &Issue{Repository: &Repository{FullName: "alterminal/agents"}}
+	if got := i.FullName(); got != "alterminal/agents" {
+		t.Errorf("repository 欄位，得到 %q", got)
+	}
+	if got := (&Issue{}).FullName(); got != "" {
+		t.Errorf("全缺 → 空，得到 %q", got)
+	}
+}
@@ -0,0 +1,256 @@
+// milestones.go — 跨倉庫里程碑總覽（teai #31；gitea.py milestones 的對應實作）。
+//
+// 各倉庫 open milestone 概況（管理者巡邏用，agents AGENTS.md 10.1）：期限近者
+// 在前的排序、逾期判定、未分派條目摘要與活躍度（updated_at 取里程碑本身與
+// 其 open 條位的最大值）。判定與輸出規則以 AGENTS.md 為單一來源，行為基準是
+// gitea.py 的 list_milestone_overview，本檔只實作、不改義。
+package workflow
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Milestone 是里程碑物件（僅取總覽會用到的欄位）。
+// ID 與 DueOn 用指標：Gitea 回 null／缺漏時輸出 null
+// （對應 gitea.py milestone.get("id")／get("due_on") 的 None 語義）。
+type Milestone struct {
+	ID           *int64  `json:"id"`
+	Title        string  `json:"title"`
+	State        string  `json:"state"`
+	DueOn        *string `json:"due_on"`
+	UpdatedAt    string  `json:"updated_at"`
+	OpenIssues   int64   `json:"open_issues"`
+	ClosedIssues int64   `json:"closed_issues"`
+}
+
+// MilestoneSource 是跨倉庫里程碑總覽需要的資料源（CLI 層以 API 實作；
+// 測試注入假資料，與 Source／StalledSource 同模式）。
+type MilestoneSource interface {
+	// MyOrganizations 回傳目前帳號所屬組織清單。
+	MyOrganizations() ([]string, error)
+	// OrganizationRepositories 回傳組織的倉庫清單。
+	OrganizationRepositories(org string) ([]Repo, error)
+	// OpenMilestones 回傳倉庫的 open 里程碑。
+	OpenMilestones(owner, repo string) ([]Milestone, error)
+	// MilestoneOpenIssues 回傳掛在指定里程碑（依名稱過濾）的 open
+	// issue 與 PR。刻意不設 type 過濾——兩者都保留供覆蓋檢查
+	//（同 gitea.py _milestone_open_issues 的查詢參數；PR 帶
+	// pull_request 標記，由本套件判別）。
+	MilestoneOpenIssues(owner, repo, milestoneTitle string) ([]Issue, error)
+}
+
+// UnassignedEntry 是里程碑 open 條目中未分派者的摘要。
+type UnassignedEntry struct {
+	Type   string
+	Number int64
+	Title  string
+	URL    string
+	// Author 僅 pull 條目輸出（且作者已知時；對應 gitea.py 只在
+	// _pr_author_username 非空時放 author 鍵）。
+	Author string
+}
+
+// MarshalJSON 輸出鍵集與鍵序與 gitea.py 一致的物件。
+func (u UnassignedEntry) MarshalJSON() ([]byte, error) {
+	var b strings.Builder
+	b.WriteString(`{"type":`)
+	writeJSON(&b, u.Type)
+	b.WriteString(`,"number":`)
+	fmt.Fprintf(&b, "%d", u.Number)
+	b.WriteString(`,"title":`)
+	writeJSON(&b, u.Title)
+	b.WriteString(`,"url":`)
+	writeJSON(&b, u.URL)
+	if u.Author != "" {
+		b.WriteString(`,"author":`)
+		writeJSON(&b, u.Author)
+	}
+	b.WriteString(`}`)
+	return []byte(b.String()), nil
+}
+
+// MilestoneEntry 是總覽的單筆輸出（欄位對應 gitea.py list_milestone_overview
+// 的 dict 鍵序：repo、id、title、url、open_issues、closed_issues、due_on、
+// due_hours、overdue、unassigned、updated_at）。
+type MilestoneEntry struct {
+	Repo         string
+	ID           *int64
+	Title        string
+	URL          string
+	OpenIssues   int64
+	ClosedIssues int64
+	DueOn        *string
+	DueHours     *float64
+	Overdue      bool
+	Unassigned   []UnassignedEntry
+	UpdatedAt    *string
+}
+
+// MarshalJSON 輸出鍵集與鍵序與 gitea.py 完全一致的物件
+// （與 Item／stalled 的做法相同：手寫鍵序，null／浮點格式對齊 Python）。
+func (e MilestoneEntry) MarshalJSON() ([]byte, error) {
+	var b strings.Builder
+	b.WriteString(`{"repo":`)
+	writeJSON(&b, e.Repo)
+	b.WriteString(`,"id":`)
+	if e.ID != nil {
+		fmt.Fprintf(&b, "%d", *e.ID)
+	} else {
+		b.WriteString("null")
+	}
+	b.WriteString(`,"title":`)
+	writeJSON(&b, e.Title)
+	b.WriteString(`,"url":`)
+	writeJSON(&b, e.URL)
+	b.WriteString(`,"open_issues":`)
+	fmt.Fprintf(&b, "%d", e.OpenIssues)
+	b.WriteString(`,"closed_issues":`)
+	fmt.Fprintf(&b, "%d", e.ClosedIssues)
+	b.WriteString(`,"due_on":`)
+	writeJSON(&b, e.DueOn)
+	b.WriteString(`,"due_hours":`)
+	if e.DueHours != nil {
+		// Python round(x, 1) 的 json 輸出是 48.0／10.4（定點一位小數）。
+		b.WriteString(strconv.FormatFloat(round1(*e.DueHours), 'f', 1, 64))
+	} else {
+		b.WriteString("null")
+	}
+	b.WriteString(`,"overdue":`)
+	b.WriteString(strconv.FormatBool(e.Overdue))
+	b.WriteString(`,"unassigned":`)
+	writeJSON(&b, e.Unassigned)
+	b.WriteString(`,"updated_at":`)
+	writeJSON(&b, e.UpdatedAt)
+	b.WriteString(`}`)
+	return []byte(b.String()), nil
+}
+
+// MilestoneOverview 收集跨組織各倉庫的 open 里程碑概況，依（due_on，
+// 無則視為最遠）由近到遠排序（穩定排序：同 due_on 者保持掃描順序，
+// 對應 Python list.sort 的穩定性）。webBase 是站點網址前綴
+// （scheme://host），空字串時 url 欄位輸出 ""（同 gitea.py 在
+// GITEA_WEB_DOMAIN 缺漏時的行為）。
+func MilestoneOverview(src MilestoneSource, webBase string, now time.Time) ([]MilestoneEntry, error) {
+	orgs, err := src.MyOrganizations()
+	if err != nil {
+		return nil, err
+	}
+	out := []MilestoneEntry{}
+	for _, org := range orgs {
+		repos, err := src.OrganizationRepositories(org)
+		if err != nil {
+			return nil, err
+		}
+		for _, repo := range repos {
+			if repo.Name == "" || repo.Empty {
+				continue
+			}
+			ms, err := src.OpenMilestones(org, repo.Name)
+			if err != nil {
+				return nil, err
+			}
+			for i := range ms {
+				entry, err := milestoneEntry(src, org, repo.Name, &ms[i], webBase, now)
+				if err != nil {
+					return nil, err
+				}
+				out = append(out, entry)
+			}
+		}
+	}
+	// gitea.py 的排序鍵：(due_on is None, due_on or "")——有期限者在前、
+	// 期限近者在前；無期限者在後。
+	sort.SliceStable(out, func(a, bb int) bool {
+		x, y := out[a].DueOn, out[bb].DueOn
+		if (x == nil) != (y == nil) {
+			return y == nil
+		}
+		if x != nil {
+			return *x < *y
+		}
+		return false
+	})
+	return out, nil
+}
+
+// milestoneEntry 計算單一里程碑的總覽欄位（對應 gitea.py 迴圈體）。
+func milestoneEntry(src MilestoneSource, org, repo string, m *Milestone, webBase string, now time.Time) (MilestoneEntry, error) {
+	// due_hours／overdue：due_on 缺漏或無法解析 → null／false。
+	// Python 以未捨入值判定 overdue（round 只作用於輸出），
+	// 邊界（如 0.04 小時 → overdue=true、due_hours=0.0）保持一致。
+	var dueHours *float64
+	overdue := false
+	if m.DueOn != nil {
+		if due, ok := parseMoment(*m.DueOn); ok {
+			raw := now.Sub(due).Hours()
+			dueHours = &raw
+			overdue = raw > 0
+		}
+	}
+	openEntries, err := src.MilestoneOpenIssues(org, repo, m.Title)
+	if err != nil {
+		return MilestoneEntry{}, err
+	}
+	// 未分派條目摘要（assignees 為空者）；updated_at 取里程碑本身與
+	// 各 open 條目 updated_at 的最大值（供巡邏判斷活躍度）。
+	unassigned := []UnassignedEntry{}
+	moments := []time.Time{}
+	if updated, ok := parseMoment(m.UpdatedAt); ok {
+		moments = append(moments, updated)
+	}
+	for i := range openEntries {
+		entry := &openEntries[i]
+		if updated, ok := parseMoment(entry.UpdatedAt); ok {
+			moments = append(moments, updated)
+		}
+		if len(AssigneeNames(entry)) > 0 {
+			continue
+		}
+		summary := UnassignedEntry{
+			Type:   "issue",
+			Number: entry.issueNumber(),
+			Title:  entry.Title,
+			URL:    entry.WebURL(),
+		}
+		if entry.PullRequest != nil {
+			summary.Type = "pull"
+			if author := entry.User.Name(); author != "" {
+				summary.Author = author
+			}
+		}
+		unassigned = append(unassigned, summary)
+	}
+	var updatedAt *string
+	if len(moments) > 0 {
+		s := FormatMoment(maxTime(moments))
+		updatedAt = &s
+	}
+	return MilestoneEntry{
+		Repo:         org + "/" + repo,
+		ID:           m.ID,
+		Title:        m.Title,
+		URL:          milestoneURL(webBase, org, repo, m.ID),
+		OpenIssues:   m.OpenIssues,
+		ClosedIssues: m.ClosedIssues,
+		DueOn:        m.DueOn,
+		DueHours:     dueHours,
+		Overdue:      overdue,
+		Unassigned:   unassigned,
+		UpdatedAt:    updatedAt,
+	}, nil
+}
+
+// milestoneURL 組里程碑網頁網址；webBase 空或 id 缺漏回 ""
+// （對應 gitea.py _milestone_url 的兩個空值條件。Python 原版不做
+// URL 跳脫——一般組織／倉庫名皆為安全字元，這裡保持一致以求位元組相容）。
+func milestoneURL(webBase, org, repo string, id *int64) string {
+	if webBase == "" || id == nil {
+		return ""
+	}
+	return strings.TrimRight(webBase, "/") + "/" + org + "/" + repo +
+		"/milestone/" + strconv.FormatInt(*id, 10)
+}
@@ -0,0 +1,262 @@
+// milestones_test.go — MilestoneOverview 的單元測試（#31）。
+//
+// 資料源注入假實作（離線可測）；鍵序、null 表示、排序與 overdue
+// 判定對照 gitea.py list_milestone_overview 的 Python 語義。
+package workflow
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeMilestoneSource 以記憶體資料實作 MilestoneSource。
+type fakeMilestoneSource struct {
+	orgs       []string
+	repos      map[string][]Repo
+	milestones map[string][]Milestone
+	openIssues map[string][]Issue // key: owner/repo?milestone=<title>
+}
+
+func (f *fakeMilestoneSource) MyOrganizations() ([]string, error) { return f.orgs, nil }
+func (f *fakeMilestoneSource) OrganizationRepositories(org string) ([]Repo, error) {
+	return f.repos[org], nil
+}
+func (f *fakeMilestoneSource) OpenMilestones(owner, repo string) ([]Milestone, error) {
+	return f.milestones[owner+"/"+repo], nil
+}
+func (f *fakeMilestoneSource) MilestoneOpenIssues(owner, repo, title string) ([]Issue, error) {
+	return f.openIssues[owner+"/"+repo+"?milestone="+title], nil
+}
+
+func msPtr(s string) *string { return &s }
+func idPtr(i int64) *int64   { return &i }
+
+// newMilestoneFixture 建構情境：alterminal 兩倉庫、三里程碑
+// （teai 有期限將至、agents 有逾期與無期限）。
+func newMilestoneFixture() *fakeMilestoneSource {
+	return &fakeMilestoneSource{
+		orgs: []string{"alterminal"},
+		repos: map[string][]Repo{"alterminal": {
+			{Name: "agents", HasPullRequests: boolPtr(true)},
+			{Name: "teai", HasPullRequests: boolPtr(true)},
+			{Name: "empty-repo", Empty: true}, // 空倉庫應跳過
+		}},
+		milestones: map[string][]Milestone{
+			"alterminal/agents": {
+				{ID: idPtr(7), Title: "MVP", State: "open",
+					DueOn: msPtr("2026-09-09T00:00:00Z"), UpdatedAt: "2026-09-01T00:00:00Z",
+					OpenIssues: 3, ClosedIssues: 1},
+				{ID: idPtr(8), Title: "v1", State: "open",
+					DueOn: nil, UpdatedAt: "2026-09-02T00:00:00Z",
+					OpenIssues: 1, ClosedIssues: 0},
+			},
+			"alterminal/teai": {
+				{ID: idPtr(3), Title: "CLI", State: "open",
+					DueOn: msPtr("2026-09-12T00:00:00Z"), UpdatedAt: "2026-09-05T00:00:00Z",
+					OpenIssues: 2, ClosedIssues: 5},
+			},
+		},
+		openIssues: map[string][]Issue{
+			// agents MVP：一個未分派 issue、一個未分派 PR、一個已分派 issue。
+			"alterminal/agents?milestone=MVP": {
+				{Number: 31, Title: "總覽命令", State: "open",
+					UpdatedAt:  "2026-09-10T01:00:00Z",
+					Repository: &Repository{FullName: "alterminal/agents"},
+					HTMLURL:    "https://gitea.alterminal.com/alterminal/agents/issues/31"},
+				{Number: 32, Title: "文件", State: "open",
+					UpdatedAt:   "2026-09-08T00:00:00Z",
+					Repository:  &Repository{FullName: "alterminal/agents"},
+					HTMLURL:     "https://gitea.alterminal.com/alterminal/agents/pulls/32",
+					PullRequest: &pullMarker{}, User: &User{UserName: "alex"}},
+				{Number: 33, Title: "已分派", State: "open",
+					UpdatedAt:  "2026-09-07T00:00:00Z",
+					Repository: &Repository{FullName: "alterminal/agents"},
+					HTMLURL:    "https://gitea.alterminal.com/alterminal/agents/issues/33",
+					Assignee:   &User{UserName: "queena"}},
+			},
+			// agents v1（無期限）：條目比里程碑本身新 → updated_at 取條目。
+			"alterminal/agents?milestone=v1": {
+				{Number: 40, Title: "無人理", State: "open",
+					UpdatedAt:  "2026-09-09T23:30:00Z",
+					Repository: &Repository{FullName: "alterminal/agents"},
+					HTMLURL:    "https://gitea.alterminal.com/alterminal/agents/issues/40"},
+			},
+		},
+	}
+}
+
+// TestMilestoneOverviewSortAndOverdue 驗證排序（期限近者在前、無期限在後）
+// 與 overdue／due_hours 計算。
+func TestMilestoneOverviewSortAndOverdue(t *testing.T) {
+	now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	entries, err := MilestoneOverview(newMilestoneFixture(), "https://gitea.alterminal.com", now)
+	if err != nil {
+		t.Fatalf("MilestoneOverview: %v", err)
+	}
+	if len(entries) != 3 {
+		t.Fatalf("應有 3 筆（空倉庫跳過），得到 %d", len(entries))
+	}
+	// 排序：MVP（2026-09-09，已過期）→ CLI（2026-09-12）→ v1（無期限）。
+	wantOrder := []string{"alterminal/agents#MVP", "alterminal/teai#CLI", "alterminal/agents#v1"}
+	for i, want := range wantOrder {
+		got := entries[i].Repo + "#" + entries[i].Title
+		if got != want {
+			t.Errorf("第 %d 筆應為 %s，得到 %s", i, want, got)
+		}
+	}
+	// MVP：due 2026-09-09T00:00Z、now 09-10T08:00Z → 32 小時、逾期。
+	if !entries[0].Overdue {
+		t.Errorf("MVP 應逾期")
+	}
+	if entries[0].DueHours == nil || *entries[0].DueHours != 32.0 {
+		t.Errorf("MVP due_hours 應 32.0，得到 %v", entries[0].DueHours)
+	}
+	// CLI：未到期。
+	if entries[1].Overdue {
+		t.Errorf("CLI 不應逾期")
+	}
+	// v1：無期限 → null。
+	if entries[2].DueOn != nil || entries[2].DueHours != nil || entries[2].Overdue {
+		t.Errorf("v1 無期限應為 null/false，得到 %+v", entries[2])
+	}
+}
+
+// TestMilestoneOverviewUnassigned 驗證未分派條目摘要（issue 無 author、
+// pull 帶 author）與 updated_at 取最大值。
+func TestMilestoneOverviewUnassigned(t *testing.T) {
+	now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	entries, err := MilestoneOverview(newMilestoneFixture(), "https://gitea.alterminal.com", now)
+	if err != nil {
+		t.Fatalf("MilestoneOverview: %v", err)
+	}
+	var mvp *MilestoneEntry
+	for i := range entries {
+		if entries[i].Title == "MVP" {
+			mvp = &entries[i]
+		}
+	}
+	if mvp == nil {
+		t.Fatalf("找不到 MVP")
+	}
+	// 未分派：#31（issue）、#32（PR, author=alex）；#33 已分派不列。
+	if len(mvp.Unassigned) != 2 {
+		t.Fatalf("MVP 應有 2 筆未分派，得到 %d：%+v", len(mvp.Unassigned), mvp.Unassigned)
+	}
+	if mvp.Unassigned[0].Type != "issue" || mvp.Unassigned[0].Number != 31 {
+		t.Errorf("第一筆未分派應為 issue #31，得到 %+v", mvp.Unassigned[0])
+	}
+	if mvp.Unassigned[1].Type != "pull" || mvp.Unassigned[1].Number != 32 || mvp.Unassigned[1].Author != "alex" {
+		t.Errorf("第二筆未分派應為 pull #32（author=alex），得到 %+v", mvp.Unassigned[1])
+	}
+	// updated_at：max(里程碑 09-01, #31 09-10T01:00Z) → 後者。
+	if mvp.UpdatedAt == nil || *mvp.UpdatedAt != "2026-09-10T01:00:00+00:00" {
+		t.Errorf("MVP updated_at 應取條目最大值 2026-09-10T01:00:00+00:00，得到 %v", mvp.UpdatedAt)
+	}
+	// url 組法。
+	if mvp.URL != "https://gitea.alterminal.com/alterminal/agents/milestone/7" {
+		t.Errorf("MVP url 應為 milestone/7，得到 %s", mvp.URL)
+	}
+}
+
+// TestMilestoneOverviewJSONKeys 驗證 JSON 鍵集與鍵序與 gitea.py 一致，
+// 以及 null／陣列空表示（unassigned 空 → []）。
+func TestMilestoneOverviewJSONKeys(t *testing.T) {
+	now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	entries, err := MilestoneOverview(newMilestoneFixture(), "", now)
+	if err != nil {
+		t.Fatalf("MilestoneOverview: %v", err)
+	}
+	// v1：無期限、無未分派條目 → due_on/due_hours/updated_at 的 null 表示、
+	// unassigned=[]、webBase 空 → url=""。
+	var v1 *MilestoneEntry
+	for i := range entries {
+		if entries[i].Title == "v1" {
+			v1 = &entries[i]
+		}
+	}
+	if v1 == nil {
+		t.Fatalf("找不到 v1")
+	}
+	// 手寫期望 JSON（縮排 2、鍵序照 gitea.py dict 實字序）。
+	b, err := json.Marshal(v1)
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	// 以逐鍵比對為準（MarshalIndent 因自訂 MarshalJSON 不縮排內層）。
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(b, &obj); err != nil {
+		t.Fatalf("Unmarshal: %v", err)
+	}
+	wantKeys := []string{"repo", "id", "title", "url", "open_issues", "closed_issues",
+		"due_on", "due_hours", "overdue", "unassigned", "updated_at"}
+	// 鍵序：json.Unmarshal 到 map 會失序；改檢查原始字串的鍵出現順序。
+	pos := -1
+	for _, k := range wantKeys {
+		i := strings.Index(string(b), `"`+k+`":`)
+		if i < 0 {
+			t.Fatalf("輸出缺少鍵 %q：%s", k, b)
+		}
+		if i < pos {
+			t.Fatalf("鍵 %q 順序錯誤：%s", k, b)
+		}
+		pos = i
+	}
+	for _, kv := range []struct {
+		key  string
+		want string
+	}{
+		{"repo", `"alterminal/agents"`},
+		{"due_on", `null`},
+		{"due_hours", `null`},
+		{"overdue", `false`},
+		{"url", `""`},
+	} {
+		if got := string(obj[kv.key]); got != kv.want {
+			t.Errorf("%s 應為 %s，得到 %s", kv.key, kv.want, got)
+		}
+	}
+	if !strings.Contains(string(b), `"number":40`) {
+		t.Errorf("未分派條目應含 number 40：%s", b)
+	}
+	// pull 條目的 author 鍵：有作者才輸出（無則不該出現 "author"）。
+	if strings.Contains(string(obj["unassigned"]), `"author"`) {
+		t.Errorf("issue 條目不應有 author 鍵：%s", obj["unassigned"])
+	}
+}
+
+// TestMilestoneOverviewDueHoursRounding 驗證 due_hours 捨入到一位小數，
+// 且 overdue 以未捨入值判定（0.04h → 0.0 但 overdue=true）。
+func TestMilestoneOverviewDueHoursRounding(t *testing.T) {
+	src := &fakeMilestoneSource{
+		orgs:  []string{"alterminal"},
+		repos: map[string][]Repo{"alterminal": {{Name: "r"}}},
+		milestones: map[string][]Milestone{
+			"alterminal/r": {
+				{ID: idPtr(1), Title: "edge", State: "open",
+					DueOn: msPtr("2026-09-10T07:57:36Z"), UpdatedAt: "2026-09-10T07:00:00Z"},
+			},
+		},
+		openIssues: map[string][]Issue{},
+	}
+	now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	entries, err := MilestoneOverview(src, "", now)
+	if err != nil {
+		t.Fatalf("MilestoneOverview: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("應有 1 筆，得到 %d", len(entries))
+	}
+	// 144 秒 = 0.04 小時 → round1 → 0.0；未捨入 > 0 → overdue=true。
+	b, err := json.Marshal(entries[0])
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	if !strings.Contains(string(b), `"due_hours":0.0`) {
+		t.Errorf("due_hours 應捨入為 0.0：%s", b)
+	}
+	if !strings.Contains(string(b), `"overdue":true`) {
+		t.Errorf("overdue 應以未捨入值判定為 true：%s", b)
+	}
+}
@@ -0,0 +1,115 @@
+package workflow
+
+import (
+	"errors"
+	"sort"
+)
+
+// errIncompatibleFlags 對應 gitea.py 的「--mine 與 --reviewer 不能併用」。
+var errIncompatibleFlags = errors.New("--mine 與 --reviewer 不能併用")
+
+// Work 是 next 命令的輸出物件：Type 為 "pull" 或 "issue"；Role 僅 pull 帶
+// （"author" 或 "reviewer"），對應 gitea.py 的 _work_dict。
+type Work struct {
+	Type   string `json:"type"`
+	Role   string `json:"role,omitempty"`
+	Repo   string `json:"repo"`
+	Number int64  `json:"number"`
+	Title  string `json:"title"`
+	URL    string `json:"url"`
+}
+
+// issueNumber 回傳 issue 編號：number 缺漏時回退 index（gitea.py 語義）。
+func (i *Issue) issueNumber() int64 {
+	if i.Number != 0 {
+		return i.Number
+	}
+	return i.Index
+}
+
+// Num 是 issueNumber 的公開介面（CLI 輸出用）。
+func (i *Issue) Num() int64 { return i.issueNumber() }
+
+// Next 回傳下一件未完成工作：先自己發起的待跟進 PR（role=author），再待審核
+// 的 PR（role=reviewer，含尚無留言），再分派給自己的 open issue。各層皆以
+// 「最久未更新優先」排序後取第一件（gitea.py 的 find_next_work）。
+// 沒有任何工作時回傳 nil。
+func (s *Scanner) Next() (*Work, error) {
+	username, err := s.Whoami()
+	if err != nil {
+		return nil, err
+	}
+	_ = username
+
+	// 第一層：自己發起、最後一則留言不是自己的 open PR。
+	minePulls, err := s.Pulls(true, false)
+	if err != nil {
+		return nil, err
+	}
+	if len(minePulls) > 0 {
+		sorted := sortPullItemsByUpdated(minePulls)
+		return workFromPull(sorted[0], "author"), nil
+	}
+
+	// 第二層：自己是審核者、最後一則留言不是自己的 open PR。
+	reviewerPulls, err := s.Pulls(false, true)
+	if err != nil {
+		return nil, err
+	}
+	if len(reviewerPulls) > 0 {
+		sorted := sortPullItemsByUpdated(reviewerPulls)
+		return workFromPull(sorted[0], "reviewer"), nil
+	}
+
+	// 第三層：分派給自己、最後一則留言不是 assignee 的 open issue。
+	issues, err := s.Mine()
+	if err != nil {
+		return nil, err
+	}
+	if len(issues) > 0 {
+		sorted := sortIssuesByUpdated(issues)
+		return workFromIssue(&sorted[0]), nil
+	}
+	return nil, nil
+}
+
+// sortPullItemsByUpdated 依 updatedKey 升冪（最久未更新在前）穩定排序。
+func sortPullItemsByUpdated(items []PullItem) []PullItem {
+	out := append([]PullItem(nil), items...)
+	sort.SliceStable(out, func(a, b int) bool {
+		return out[a].Pull.updatedKey() < out[b].Pull.updatedKey()
+	})
+	return out
+}
+
+// sortIssuesByUpdated 依 updatedKey 升冪（最久未更新在前）穩定排序。
+func sortIssuesByUpdated(items []Issue) []Issue {
+	out := append([]Issue(nil), items...)
+	sort.SliceStable(out, func(a, b int) bool {
+		return out[a].updatedKey() < out[b].updatedKey()
+	})
+	return out
+}
+
+// workFromPull 由 PR 組出 Work 物件。
+func workFromPull(item PullItem, role string) *Work {
+	return &Work{
+		Type:   "pull",
+		Role:   role,
+		Repo:   item.Owner + "/" + item.Repo,
+		Number: item.Pull.Number,
+		Title:  item.Pull.Title,
+		URL:    item.Pull.WebURL(),
+	}
+}
+
+// workFromIssue 由 issue 組出 Work 物件。
+func workFromIssue(issue *Issue) *Work {
+	return &Work{
+		Type:   "issue",
+		Repo:   issue.FullName(),
+		Number: issue.issueNumber(),
+		Title:  issue.Title,
+		URL:    issue.WebURL(),
+	}
+}
@@ -0,0 +1,361 @@
+// Package workflow 實作 AGENTS.md 工作流判定：跟進、審核、next 拾取與排序。
+//
+// 行為基準是 alterminal/agents 的 scripts/lib/gitea.py；判定規則以 AGENTS.md
+// 為唯一來源，本套件只實作、不改義。API 存取以 Client 介面抽象，HTTP 實作
+// 由 internal/gitea（#5 基礎建設）提供；測試以假 client 注入。
+package workflow
+
+import (
+	"sort"
+)
+
+// AgentsTeamName 是工作流團隊的名稱（AGENTS.md：調度成員由 Agents 團隊決定）。
+const AgentsTeamName = "Agents"
+
+// Client 抽象 teai 需要的 Gitea API 讀取操作（僅唯讀）。
+// #5 的 internal/gitea HTTP 用戶端實作此介面；workflow 不依賴 HTTP 細節。
+type Client interface {
+	// CurrentUser 回傳目前帳號名（GET /user）。
+	CurrentUser() (string, error)
+	// ListOrgs 回傳帳號所屬組織名（GET /user/orgs，分頁）。
+	ListOrgs() ([]string, error)
+	// ListTeams 回傳組織的團隊清單（GET /orgs/{org}/teams，分頁）。
+	ListTeams(org string) ([]Team, error)
+	// ListTeamMembers 回傳團隊成員帳號（GET /teams/{id}/members，分頁）。
+	ListTeamMembers(teamID int64) ([]string, error)
+	// ListOrgRepos 回傳組織的倉庫物件（GET /orgs/{org}/repos，分頁）。
+	ListOrgRepos(org string) ([]Repo, error)
+	// ListIssues 回傳倉庫的 open issues（GET /repos/{owner}/{repo}/issues?state=open&type=issues，
+	// 分頁；已排除帶 pull_request 標記的 PR）。assignee／留言過濾由 workflow 層負責。
+	ListIssues(owner, repo string) ([]Issue, error)
+	// ListPulls 回傳倉庫的 open PR（GET /repos/{owner}/{repo}/pulls?state=open，分頁）。
+	ListPulls(owner, repo string) ([]PullRequest, error)
+	// ListComments 回傳 issue／PR 的留言（GET /repos/{owner}/{repo}/issues/{n}/comments，分頁）。
+	ListComments(owner, repo string, number int64) ([]Comment, error)
+}
+
+// RepoPulls 是單一倉庫的 open PR 清單（掃描的中間產物）。
+type RepoPulls struct {
+	Owner string
+	Repo  string
+	Pulls []PullRequest
+}
+
+// PullItem 是跟進清單中的 PR，附掃描時的所屬倉庫（owner/repo），
+// 供輸出時補齊 gitea.py 工作物件的 repo 欄位。
+type PullItem struct {
+	Owner string
+	Repo  string
+	Pull  PullRequest
+}
+
+// Scanner 在 Client 之上組合出各命令的資料（whoami/orgs/members/mine/pulls/next）。
+type Scanner struct {
+	Client Client
+}
+
+// Whoami 回傳目前帳號。
+func (s *Scanner) Whoami() (string, error) {
+	return s.Client.CurrentUser()
+}
+
+// Orgs 回傳目前帳號所屬的組織（去重、排序）。
+func (s *Scanner) Orgs() ([]string, error) {
+	names, err := s.Client.ListOrgs()
+	if err != nil {
+		return nil, err
+	}
+	seen := map[string]bool{}
+	out := []string{}
+	for _, n := range names {
+		if n != "" && !seen[n] {
+			seen[n] = true
+			out = append(out, n)
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// agentsTeamID 找出組織內名為 Agents 的團隊 ID；沒有回 (0,false)。
+func (s *Scanner) agentsTeamID(org string) (int64, bool, error) {
+	teams, err := s.Client.ListTeams(org)
+	if err != nil {
+		return 0, false, err
+	}
+	for _, team := range teams {
+		if team.Name == AgentsTeamName {
+			return team.ID, true, nil
+		}
+	}
+	return 0, false, nil
+}
+
+// Members 回傳跨組織 Agents 團隊成員（去重、排序）。
+// hasWork 為 true 時只保留有未完成工作者（判定同 Next 的拾取規則）。
+func (s *Scanner) Members(hasWork bool) ([]string, error) {
+	orgs, err := s.Orgs()
+	if err != nil {
+		return nil, err
+	}
+	seen := map[string]bool{}
+	names := []string{}
+	for _, org := range orgs {
+		teamID, ok, err := s.agentsTeamID(org)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			continue
+		}
+		members, err := s.Client.ListTeamMembers(teamID)
+		if err != nil {
+			return nil, err
+		}
+		for _, m := range members {
+			if m != "" && !seen[m] {
+				seen[m] = true
+				names = append(names, m)
+			}
+		}
+	}
+	sort.Strings(names)
+	if !hasWork {
+		return names, nil
+	}
+	busy, err := s.usernamesWithUnfinishedWork(names)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]string, 0, len(names))
+	for _, name := range names {
+		if busy[name] {
+			out = append(out, name)
+		}
+	}
+	return out, nil
+}
+
+// iterOrgRepos 產出 (org, repoName)；空倉庫跳過（沒有內容可掃）。
+func (s *Scanner) iterOrgRepos() ([][2]string, error) {
+	orgs, err := s.Orgs()
+	if err != nil {
+		return nil, err
+	}
+	out := [][2]string{}
+	for _, org := range orgs {
+		repos, err := s.Client.ListOrgRepos(org)
+		if err != nil {
+			return nil, err
+		}
+		for _, repo := range repos {
+			if repo.Name == "" || repo.Empty {
+				continue
+			}
+			out = append(out, [2]string{org, repo.Name})
+		}
+	}
+	return out, nil
+}
+
+// iterOpenPulls 跨倉庫收集 open PR（附所屬 owner/repo）。
+// 對應 gitea.py 的 _iter_open_pulls：空倉庫、明確停用 PR 的倉庫跳過。
+func (s *Scanner) iterOpenPulls() ([]RepoPulls, error) {
+	orgs, err := s.Orgs()
+	if err != nil {
+		return nil, err
+	}
+	out := []RepoPulls{}
+	for _, org := range orgs {
+		repos, err := s.Client.ListOrgRepos(org)
+		if err != nil {
+			return nil, err
+		}
+		for _, repo := range repos {
+			if repo.Name == "" || repo.Empty {
+				continue
+			}
+			if repo.HasPullRequests != nil && !*repo.HasPullRequests {
+				continue
+			}
+			pulls, err := s.Client.ListPulls(org, repo.Name)
+			if err != nil {
+				return nil, err
+			}
+			if len(pulls) == 0 {
+				continue
+			}
+			out = append(out, RepoPulls{Owner: org, Repo: repo.Name, Pulls: pulls})
+		}
+	}
+	return out, nil
+}
+
+// orgIssue 是掃描到的 issue，附所屬 owner/repo。
+type orgIssue struct {
+	Owner string
+	Repo  string
+	Issue Issue
+}
+
+// commentsFor 取回 issue／PR 的留言；number 缺漏（0）時直接視為無留言，
+// 不打 API（gitea.py 在 number 為 None 時跳過留言檢查的語義——
+// 避免拿 0 去 issues/0/comments 觸發 404 中斷整個掃描）。
+func (s *Scanner) commentsFor(owner, repo string, number int64) ([]Comment, error) {
+	if number <= 0 {
+		return nil, nil
+	}
+	return s.Client.ListComments(owner, repo, number)
+}
+
+// collectMemberIssues 跨組織收集分派給 members（至少一人）且最後一則留言
+// 不是 assignee 的 open issues（gitea.py 的 for_all_organizations）。
+func (s *Scanner) collectMemberIssues(members []string) ([]orgIssue, error) {
+	pairs, err := s.iterOrgRepos()
+	if err != nil {
+		return nil, err
+	}
+	out := []orgIssue{}
+	for _, pair := range pairs {
+		owner, repo := pair[0], pair[1]
+		issues, err := s.Client.ListIssues(owner, repo)
+		if err != nil {
+			return nil, err
+		}
+		for i := range issues {
+			issue := &issues[i]
+			if !AssigneeOverlaps(issue, members) {
+				continue
+			}
+			comments, err := s.commentsFor(owner, repo, issue.issueNumber())
+			if err != nil {
+				return nil, err
+			}
+			if !LastCommentNotByAssignee(issue, comments) {
+				continue
+			}
+			out = append(out, orgIssue{Owner: owner, Repo: repo, Issue: *issue})
+		}
+	}
+	return out, nil
+}
+
+// Mine 回傳分派給目前帳號、且最後一則留言不是 assignee 的 open issues
+// （跨所屬組織；gitea.py 的 list_my_followup_issues）。
+func (s *Scanner) Mine() ([]Issue, error) {
+	username, err := s.Whoami()
+	if err != nil {
+		return nil, err
+	}
+	found, err := s.collectMemberIssues([]string{username})
+	if err != nil {
+		return nil, err
+	}
+	out := make([]Issue, 0, len(found))
+	for _, item := range found {
+		out = append(out, item.Issue)
+	}
+	return out, nil
+}
+
+// Pulls 回傳跟進清單（跨倉庫；gitea.py 的 list_followup_pulls 系列）：
+//   - 預設：「有留言且最後一則不是作者」的 open PR。
+//   - mine=true：再限定作者是目前帳號（list_my_followup_pulls）。
+//   - reviewer=true：改為「自己是 requested reviewer、不是作者、最後一則
+//     留言不是自己（含尚無留言）」（list_my_reviewer_pulls）。
+//
+// mine 與 reviewer 不可併用。
+func (s *Scanner) Pulls(mine, reviewer bool) ([]PullItem, error) {
+	if mine && reviewer {
+		return nil, errIncompatibleFlags
+	}
+	username := ""
+	if mine || reviewer {
+		var err error
+		username, err = s.Whoami()
+		if err != nil {
+			return nil, err
+		}
+	}
+	repoPulls, err := s.iterOpenPulls()
+	if err != nil {
+		return nil, err
+	}
+	found := []PullItem{}
+	for _, rp := range repoPulls {
+		for i := range rp.Pulls {
+			pr := &rp.Pulls[i]
+			comments, err := s.commentsFor(rp.Owner, rp.Repo, pr.Number)
+			if err != nil {
+				return nil, err
+			}
+			var match bool
+			switch {
+			case reviewer:
+				match = NeedsReviewerFollowup(pr, comments, username)
+			case mine:
+				match = NeedsAuthorFollowup(pr, comments) && pr.Author() == username
+			default:
+				match = NeedsAuthorFollowup(pr, comments)
+			}
+			if match {
+				found = append(found, PullItem{Owner: rp.Owner, Repo: rp.Repo, Pull: *pr})
+			}
+		}
+	}
+	return found, nil
+}
+
+// usernamesWithUnfinishedWork 從待跟進 issue／PR 清單收集有未完成工作的
+// 成員帳號（gitea.py 的 _usernames_with_unfinished_work；判定同 Next）。
+func (s *Scanner) usernamesWithUnfinishedWork(members []string) (map[string]bool, error) {
+	memberSet := map[string]bool{}
+	for _, m := range members {
+		if m != "" {
+			memberSet[m] = true
+		}
+	}
+	busy := map[string]bool{}
+	if len(memberSet) == 0 {
+		return busy, nil
+	}
+
+	// issues：分派給任一成員、最後留言不是 assignee。
+	issues, err := s.collectMemberIssues(members)
+	if err != nil {
+		return nil, err
+	}
+	for _, item := range issues {
+		for _, name := range AssigneeNames(&item.Issue) {
+			if memberSet[name] {
+				busy[name] = true
+			}
+		}
+	}
+
+	// PR：作者待跟進／審核者待審。
+	repoPulls, err := s.iterOpenPulls()
+	if err != nil {
+		return nil, err
+	}
+	for _, rp := range repoPulls {
+		for i := range rp.Pulls {
+			pr := &rp.Pulls[i]
+			comments, err := s.commentsFor(rp.Owner, rp.Repo, pr.Number)
+			if err != nil {
+				return nil, err
+			}
+			if NeedsAuthorFollowup(pr, comments) {
+				if author := pr.Author(); memberSet[author] {
+					busy[author] = true
+				}
+			}
+			for _, reviewer := range ReviewerNames(pr) {
+				if memberSet[reviewer] && NeedsReviewerFollowup(pr, comments, reviewer) {
+					busy[reviewer] = true
+				}
+			}
+		}
+	}
+	return busy, nil
+}
@@ -0,0 +1,261 @@
+// scan_test.go — 以假 client 驗證 Scanner 的命令層語義（對照 gitea.py）：
+// next 三層拾取與「最久未更新優先」、mine/pulls 過濾、members --has-work。
+package workflow
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"testing"
+)
+
+// fakeClient 以記憶體資料實作 Client。
+type fakeClient struct {
+	currentUser string
+	orgs        []Org
+	teams       map[string][]Team        // org → teams
+	teamMembers map[int64][]string       // teamID → 帳號
+	repos       map[string][]Repo        // org → repos
+	issues      map[string][]Issue       // "owner/repo" → issues（open，不含 PR）
+	pulls       map[string][]PullRequest // "owner/repo" → open PR
+	comments    map[string][]Comment     // "owner/repo#number" → 留言
+	failOn      map[string]error         // 端點 → 錯誤（測失敗傳播）
+}
+
+func (f *fakeClient) CurrentUser() (string, error) {
+	if err := f.failOn["user"]; err != nil {
+		return "", err
+	}
+	return f.currentUser, nil
+}
+
+func (f *fakeClient) ListOrgs() ([]string, error) {
+	if err := f.failOn["orgs"]; err != nil {
+		return nil, err
+	}
+	out := make([]string, 0, len(f.orgs))
+	for _, o := range f.orgs {
+		out = append(out, o.Account())
+	}
+	return out, nil
+}
+
+func (f *fakeClient) ListTeams(org string) ([]Team, error) {
+	if err := f.failOn["teams"]; err != nil {
+		return nil, err
+	}
+	return f.teams[org], nil
+}
+
+func (f *fakeClient) ListTeamMembers(teamID int64) ([]string, error) {
+	if err := f.failOn["members"]; err != nil {
+		return nil, err
+	}
+	return f.teamMembers[teamID], nil
+}
+
+func (f *fakeClient) ListOrgRepos(org string) ([]Repo, error) {
+	if err := f.failOn["repos"]; err != nil {
+		return nil, err
+	}
+	return f.repos[org], nil
+}
+
+func (f *fakeClient) ListIssues(owner, repo string) ([]Issue, error) {
+	if err := f.failOn["issues"]; err != nil {
+		return nil, err
+	}
+	return f.issues[owner+"/"+repo], nil
+}
+
+func (f *fakeClient) ListPulls(owner, repo string) ([]PullRequest, error) {
+	if err := f.failOn["pulls"]; err != nil {
+		return nil, err
+	}
+	return f.pulls[owner+"/"+repo], nil
+}
+
+func (f *fakeClient) ListComments(owner, repo string, number int64) ([]Comment, error) {
+	if err := f.failOn["comments"]; err != nil {
+		return nil, err
+	}
+	return f.comments[fmt.Sprintf("%s/%s#%d", owner, repo, number)], nil
+}
+
+// newTestScanner 構造測試情境：一個組織、一個 Agents 團隊、兩個倉庫。
+func newTestScanner() (*Scanner, *fakeClient) {
+	fc := &fakeClient{
+		currentUser: "alex",
+		orgs:        []Org{{UserName: "alterminal"}},
+		teams:       map[string][]Team{"alterminal": {{ID: 1, Name: "Agents"}}},
+		teamMembers: map[int64][]string{1: {"alex", "max", "queena"}},
+		repos:       map[string][]Repo{"alterminal": {{Name: "teai"}, {Name: "agents"}}},
+		issues:      map[string][]Issue{},
+		pulls:       map[string][]PullRequest{},
+		comments:    map[string][]Comment{},
+		failOn:      map[string]error{},
+	}
+	return &Scanner{Client: fc}, fc
+}
+
+func TestNextLayerPriority(t *testing.T) {
+	s, fc := newTestScanner()
+	// 三層各有工作：author PR、reviewer PR、issue。
+	fc.pulls["alterminal/teai"] = []PullRequest{
+		{
+			Number: 10, Title: "我的 PR", UpdatedAt: "2026-09-09T00:00:00Z",
+			User: mkUser("alex"),
+		},
+		{
+			Number: 11, Title: "待我審核的 PR", UpdatedAt: "2026-09-09T01:00:00Z",
+			User:               mkUser("max"),
+			RequestedReviewers: []User{*mkUser("alex")},
+		},
+	}
+	// author PR #10 有他人留言 → 需跟進。
+	fc.comments["alterminal/teai#10"] = []Comment{
+		{CreatedAt: "2026-09-09T00:10:00Z", User: mkUser("ceo")},
+	}
+	// reviewer PR #11 尚無留言 → 審核者仍應被列入。
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 30, Title: "分派給 alex", UpdatedAt: "2026-09-08T00:00:00Z", Assignees: []User{*mkUser("alex")}},
+	}
+	work, err := s.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if work.Type != "pull" || work.Role != "author" || work.Number != 10 {
+		t.Errorf("第一層應選 author PR #10，得到 %+v", work)
+	}
+}
+
+func TestNextLayerFallbackToReviewer(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.pulls["alterminal/teai"] = []PullRequest{
+		{
+			Number: 11, Title: "待審核", UpdatedAt: "2026-09-09T01:00:00Z",
+			User:               mkUser("max"),
+			RequestedReviewers: []User{*mkUser("alex")},
+		},
+	}
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 30, Title: "分派給 alex", UpdatedAt: "2026-09-08T00:00:00Z", Assignees: []User{*mkUser("alex")}},
+	}
+	work, err := s.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if work.Type != "pull" || work.Role != "reviewer" || work.Number != 11 {
+		t.Errorf("第二層應選 reviewer PR #11，得到 %+v", work)
+	}
+}
+
+func TestNextLayerFallbackToIssue(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 30, Title: "分派給 alex", UpdatedAt: "2026-09-08T00:00:00Z", Assignees: []User{*mkUser("alex")}},
+	}
+	work, err := s.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if work.Type != "issue" || work.Number != 30 {
+		t.Errorf("第三層應選 issue #30，得到 %+v", work)
+	}
+}
+
+func TestNextNone(t *testing.T) {
+	s, _ := newTestScanner()
+	work, err := s.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if work != nil {
+		t.Errorf("無工作應回 nil，得到 %+v", work)
+	}
+}
+
+func TestNextOldestFirst(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 31, Title: "較新", UpdatedAt: "2026-09-09T00:00:00Z", Assignees: []User{*mkUser("alex")}},
+		{Number: 30, Title: "較舊", UpdatedAt: "2026-09-08T00:00:00Z", Assignees: []User{*mkUser("alex")}},
+	}
+	work, err := s.Next()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if work.Number != 30 {
+		t.Errorf("應選最久未更新的 #30，得到 %+v", work)
+	}
+}
+
+func TestMineSkipsLastCommentByAssignee(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 30, Title: "已在處理", UpdatedAt: "a", Assignees: []User{*mkUser("alex")}},
+	}
+	fc.comments["alterminal/agents#30"] = []Comment{
+		{CreatedAt: "b", User: mkUser("alex")},
+	}
+	issues, err := s.Mine()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(issues) != 0 {
+		t.Errorf("最後留言來自 assignee → 應略過，得到 %d 件", len(issues))
+	}
+}
+
+func TestPullsMineReviewersExclusive(t *testing.T) {
+	s, _ := newTestScanner()
+	if _, err := s.Pulls(true, true); !errors.Is(err, errIncompatibleFlags) {
+		t.Errorf("--mine 與 --reviewer 併用應回 errIncompatibleFlags，得到 %v", err)
+	}
+}
+
+func TestMembersHasWork(t *testing.T) {
+	s, fc := newTestScanner()
+	// alex 有待審核 PR；max 無任何工作；queena 有分派 issue。
+	fc.pulls["alterminal/teai"] = []PullRequest{
+		{
+			Number: 11, UpdatedAt: "a", User: mkUser("max"),
+			RequestedReviewers: []User{*mkUser("alex")},
+		},
+	}
+	fc.issues["alterminal/agents"] = []Issue{
+		{Number: 30, UpdatedAt: "b", Assignees: []User{*mkUser("queena")}},
+	}
+	got, err := s.Members(true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got, []string{"alex", "queena"}) {
+		t.Errorf("應只有 alex 與 queena 有工作，得到 %v", got)
+	}
+}
+
+func TestErrorPropagation(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.failOn["orgs"] = errors.New("boom")
+	if _, err := s.Next(); err == nil {
+		t.Errorf("API 錯誤應向上傳播，不應吞掉")
+	}
+}
+
+func TestPullsDefault(t *testing.T) {
+	s, fc := newTestScanner()
+	fc.pulls["alterminal/teai"] = []PullRequest{
+		{Number: 10, UpdatedAt: "a", User: mkUser("alex")},
+	}
+	fc.comments["alterminal/teai#10"] = []Comment{
+		{CreatedAt: "b", User: mkUser("ceo")},
+	}
+	items, err := s.Pulls(false, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(items) != 1 || items[0].Repo != "teai" {
+		t.Errorf("應列出待跟進 PR，得到 %+v", items)
+	}
+}
@@ -0,0 +1,334 @@
+// stalled_entry_test.go — RunStalled／ResolveIssueXrefs 高階入口的單元測試
+// （#7 CLI 接線；資料源注入假實作，離線可測）。
+package workflow
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeStalledSource 包 fakeSource 補上 StalledSource 面向。
+type fakeStalledSource struct {
+	*fakeSource
+	username string
+	// getIssueErr 模擬 GetIssue 失敗（xrefs 的 404 路徑）。
+	getIssueErr error
+	// timeline[owner/repo/number]：issue timeline 事件（無則回空清單，
+	// 模擬 API 成功但無事件；timelineErr 模擬拉取失敗）。
+	timeline    map[string][]TimelineEvent
+	timelineErr map[string]error
+}
+
+func (f *fakeStalledSource) CurrentUser() (string, error) { return f.username, nil }
+
+func (f *fakeStalledSource) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	key := fmt.Sprintf("%s/%s/%d", owner, repo, number)
+	if err := f.timelineErr[key]; err != nil {
+		return nil, err
+	}
+	return f.timeline[key], nil
+}
+
+func (f *fakeStalledSource) GetIssue(owner, repo string, number int64) (Issue, error) {
+	if f.getIssueErr != nil {
+		return Issue{}, f.getIssueErr
+	}
+	i, ok := f.issues[owner+"/"+repo][number]
+	if !ok {
+		return Issue{}, &notFoundError{}
+	}
+	return i, nil
+}
+
+type notFoundError struct{}
+
+func (e *notFoundError) Error() string { return "404" }
+
+// newStalledFixture 建構掃描情境：alterminal 組織兩個倉庫，
+// agents#1 是父追蹤項（引用 teai#2），teai#2 有較新留言。
+func newStalledFixture() *fakeStalledSource {
+	return &fakeStalledSource{
+		fakeSource: &fakeSource{
+			orgs: []string{"alterminal"},
+			repos: map[string][]Repo{"alterminal": {
+				{Name: "agents", HasPullRequests: boolPtr(true)},
+				{Name: "teai", HasPullRequests: boolPtr(true)},
+			}},
+			issues: map[string]map[int64]Issue{
+				"alterminal/agents": {
+					1: {Number: 1, Title: "父追蹤項", State: "open",
+						Body: "子項：teai#2", CreatedAt: iso(-600), UpdatedAt: iso(-600),
+						Repository: &Repository{FullName: "alterminal/agents"}},
+				},
+				"alterminal/teai": {
+					2: {Number: 2, Title: "子項", State: "open",
+						CreatedAt: iso(-500), UpdatedAt: iso(-90),
+						Repository: &Repository{FullName: "alterminal/teai"}},
+				},
+			},
+			pulls: map[string][]PullRequest{},
+			comments: map[string][]Comment{
+				"alterminal/teai/2": {
+					{CreatedAt: iso(-90), User: &User{UserName: "alex"}, Body: "推進中"},
+				},
+			},
+		},
+		username: "ceo",
+	}
+}
+
+// TestRunStalledParentTracking 驗證 RunStalled：父追蹤項把子項活動
+// 計入 last_activity（reason=parent-tracking），且門檻預設與覆寫皆可。
+func TestRunStalledParentTracking(t *testing.T) {
+	src := newStalledFixture()
+	// 預設 4 小時門檻：子項 90 分鐘前有活動 → 父項 last_activity 同步，
+	// 未過門檻，清單為空。
+	items, err := RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("預設門檻下不應有停滯項，得到 %d 筆", len(items))
+	}
+	// 門檻降到 1 小時：父追蹤項 last_activity 取子項活動（-90m）→
+	// 停滯 1.5h 列入（reason=parent-tracking、附 child_activity）；
+	// 子項 teai#2 本身也停滯 1.5h（no-assignee）。
+	items, err = RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 2 {
+		t.Fatalf("應有兩筆（父追蹤項＋子項），得到 %d：%+v", len(items), items)
+	}
+	var parent *Item
+	for i := range items {
+		if items[i].Number == 1 {
+			parent = &items[i]
+		}
+	}
+	if parent == nil {
+		t.Fatalf("找不到 agents#1：%+v", items)
+	}
+	if parent.Reason != "parent-tracking" || parent.Repo != "alterminal/agents" {
+		t.Fatalf("agents#1 應為 parent-tracking，得到 %s（%s）", parent.Reason, parent.Repo)
+	}
+	if len(parent.ChildActivity) == 0 {
+		t.Fatalf("parent-tracking 應附 child_activity")
+	}
+	if parent.StalledHours != 1.5 {
+		t.Fatalf("last_activity 應取子項活動（-90m → 1.5h），得到 %.1f", parent.StalledHours)
+	}
+}
+
+// TestRunStalledNudgeCooldown 驗證催促冷卻：最後留言出自目前帳號
+// 且在 24 小時內 → 不列入；冷卻過後再出現。
+func TestRunStalledNudgeCooldown(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "") // 移除子項引用
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-2), User: &User{UserName: "ceo"}},
+	}
+	findOne := func(items []Item) bool {
+		for _, it := range items {
+			if it.Repo == "alterminal/agents" && it.Number == 1 {
+				return true
+			}
+		}
+		return false
+	}
+	items, err := RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if findOne(items) {
+		t.Fatalf("催促冷卻期內（2 小時前留言）agents#1 不應列入，得到 %+v", items)
+	}
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-30 * 60), User: &User{UserName: "ceo"}},
+	}
+	items, err = RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if !findOne(items) {
+		t.Fatalf("冷卻（24h）過後 agents#1 應再出現，得到 %+v", items)
+	}
+}
+
+// TestResolveIssueXrefs 驗證 xrefs 入口：內文與留言的引用解析、
+// 去重、出處標記與單段 repo 的存在性邊界。
+func TestResolveIssueXrefs(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "看 teai#2 與 #7，另見 alterminal/teai#2")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "teai#2 已處理", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+		{Body: "nope#9 不存在", User: &User{UserName: "max"}, CreatedAt: iso(-5)},
+	}
+	// fixture 的組織倉庫只有 agents → teai#2 單段不解析（repo 不在
+	// alterminal 組織清單）；補上 teai 倉庫讓單段解析成立。
+	src.repos["alterminal"] = []Repo{
+		{Name: "agents", HasPullRequests: boolPtr(true)},
+		{Name: "teai", HasPullRequests: boolPtr(true)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	want := []XrefHit{
+		{Owner: "alterminal", Repo: "teai", Number: 2, Source: "body"},
+		{Owner: "alterminal", Repo: "agents", Number: 7, Source: "body"},
+	}
+	if len(hits) != len(want) {
+		t.Fatalf("應解析出 %d 筆（留言重複的 teai#2 去重、nope#9 略過），得到 %d：%+v",
+			len(want), len(hits), hits)
+	}
+	for i := range want {
+		if hits[i] != want[i] {
+			t.Fatalf("hits[%d] = %+v, want %+v", i, hits[i], want[i])
+		}
+	}
+}
+
+// TestResolveIssueXrefsCommentSource 驗證出處：僅出現在留言的引用
+// 標記為 comment。
+func TestResolveIssueXrefsCommentSource(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "內文無引用")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "追蹤 #9", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 1 || hits[0].Source != "comment" || hits[0].Number != 9 {
+		t.Fatalf("應輸出一筆 source=comment 的 #9，得到 %+v", hits)
+	}
+}
+
+// TestResolveIssueXrefsGetError 驗證 GetIssue 失敗（如 404）層層回傳，
+// 由 CLI 映射結束碼。
+func TestResolveIssueXrefsGetError(t *testing.T) {
+	src := newStalledFixture()
+	src.getIssueErr = &notFoundError{}
+	if _, err := ResolveIssueXrefs(src, "alterminal", "agents", 1); err == nil {
+		t.Fatalf("GetIssue 失敗應回傳錯誤")
+	}
+}
+
+func boolPtr(b bool) *bool { return &b }
+
+// setIssueBody 修改 map 內 issue 的內文（map 元素不可定址，需整體重塞）。
+func setIssueBody(src *fakeStalledSource, owner, repo string, number int64, body string) {
+	key := owner + "/" + repo
+	issue := src.issues[key][number]
+	issue.Body = body
+	src.issues[key][number] = issue
+}
+
+// TestResolveIssueXrefsEmptyBody 驗證無引用時輸出空（CLI 印 []）。
+func TestResolveIssueXrefsEmptyBody(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, strings.Repeat("無引用內文", 3))
+	delete(src.comments, "alterminal/agents/1")
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("無引用應輸出空清單，得到 %+v", hits)
+	}
+	_ = time.Now // time 僅供 iso/at 使用；保留 import。
+}
+
+// TestRunStalledChildXrefRefresh 回歸測試（agents #38、teai #34）：
+// 子項 updated_at 被跨 issue 引用（comment_ref）刷新時，子項有效活動
+// 應經 directLastActivity 排除引用事件後採計，父追蹤項的停滯時鐘
+// 不被虛假刷新。
+func TestRunStalledChildXrefRefresh(t *testing.T) {
+	src := newStalledFixture()
+	// 子項 teai#2：直接活動為 created(-500) 與留言(-90)，
+	// updated_at 卻是 -10（他處留言提及刷新）。
+	issue := src.issues["alterminal/teai"][2]
+	issue.UpdatedAt = iso(-10)
+	src.issues["alterminal/teai"][2] = issue
+	// timeline：-10 的刷新是 comment_ref（引用事件，排除），
+	// -90 有直接事件（label）可對應 → 有效活動 -90。
+	src.timeline = map[string][]TimelineEvent{
+		"alterminal/teai/2": {
+			{Type: "label", CreatedAt: iso(-90)},
+			{Type: "comment_ref", CreatedAt: iso(-10)},
+		},
+	}
+	// 門檻 1 小時：父項 last_activity 取子項有效活動 -90 → 停滯 1.5h 列入；
+	// 若誤採被刷新的 -10，父項與子項都不會列入。
+	items, err := RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 2 {
+		t.Fatalf("應有兩筆（父追蹤項＋子項），得到 %d：%+v", len(items), items)
+	}
+	var parent *Item
+	for i := range items {
+		if items[i].Repo == "alterminal/agents" && items[i].Number == 1 {
+			parent = &items[i]
+		}
+	}
+	if parent == nil {
+		t.Fatalf("找不到 agents#1：%+v", items)
+	}
+	if parent.Reason != "parent-tracking" {
+		t.Fatalf("agents#1 應為 parent-tracking，得到 %s", parent.Reason)
+	}
+	if parent.StalledHours != 1.5 {
+		t.Fatalf("父項停滯應以子項有效活動（-90m → 1.5h）計，得到 %.1f", parent.StalledHours)
+	}
+}
+
+// TestRunStalledTimelineAllXrefFallback 回歸測試（agents #40、teai #34）：
+// issue 自身 updated_at 晚於全部已知直接活動、且 timeline 全為引用事件時，
+// 回退已知直接活動的最晚時刻（不高估活動、不低估停滯）；
+// timeline 拉取失敗則保守沿用 updated_at。
+func TestRunStalledTimelineAllXrefFallback(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "") // 移除父項引用，teai#2 獨立判定
+	delete(src.comments, "alterminal/teai/2")
+	// agents#1 給一則近期留言，避免本身停滯（10h）干擾本測試的斷言。
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-10), User: &User{UserName: "alex"}},
+	}
+	// teai#2：僅有 created(-500) 此一已知直接活動，
+	// updated_at -10 完全由他處提及刷新。
+	issue := src.issues["alterminal/teai"][2]
+	issue.UpdatedAt = iso(-10)
+	src.issues["alterminal/teai"][2] = issue
+	// 情境一：timeline 全為引用事件 → 回退 knownMax（created -500）
+	// → 停滯 8.3h，超過預設門檻 4h，列入。
+	src.timeline = map[string][]TimelineEvent{
+		"alterminal/teai/2": {{Type: "issue_ref", CreatedAt: iso(-10)}},
+	}
+	items, err := RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 1 || items[0].Number != 2 {
+		t.Fatalf("全引用事件應回退直接活動 → teai#2 停滯 8.3h 列入，得到 %+v", items)
+	}
+	if items[0].StalledHours != 8.3 {
+		t.Fatalf("回退 created(-500) → 停滯應 8.3h，得到 %.1f", items[0].StalledHours)
+	}
+	// 情境二：timeline 拉取失敗 → 保守沿用 updated_at(-10) → 0.2h 未達門檻，不列入。
+	src.timeline = nil
+	src.timelineErr = map[string]error{"alterminal/teai/2": errors.New("boom")}
+	items, err = RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("timeline 失敗應保守沿用 updated_at → 不列入，得到 %+v", items)
+	}
+}
@@ -0,0 +1,242 @@
+package workflow
+
+import (
+	"encoding/json"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// User 是 Gitea API 的使用者物件（僅取工作流判斷會用到的欄位）。
+type User struct {
+	UserName string `json:"username"`
+	Login    string `json:"login"`
+}
+
+// Name 回傳帳號名：先 username，缺漏時回退 login
+// （對應 gitea.py 的「username or login」取值順序）。
+func (u *User) Name() string {
+	if u == nil {
+		return ""
+	}
+	if u.UserName != "" {
+		return u.UserName
+	}
+	return u.Login
+}
+
+// Org 是帳號所屬的組織物件。
+type Org struct {
+	UserName string `json:"username"`
+	Name     string `json:"name"`
+}
+
+// Account 回傳組織名：先 username，缺漏時回退 name
+// （對應 gitea.py 的取值順序）。
+func (o Org) Account() string {
+	if o.UserName != "" {
+		return o.UserName
+	}
+	return o.Name
+}
+
+// Team 是組織內的團隊物件。
+type Team struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
+}
+
+// Repo 是組織倉庫清單中的倉庫物件。Empty 與 HasPullRequests
+// 對應 gitea.py _iter_open_pulls 的跳過條件：空倉庫、明確停用 PR
+// （has_pull_requests 為 false）者不列入 PR 掃描。
+type Repo struct {
+	Name            string `json:"name"`
+	Empty           bool   `json:"empty"`
+	HasPullRequests *bool  `json:"has_pull_requests"`
+}
+
+// Repository 是 issue／PR 物件內嵌的所屬倉庫資訊。
+type Repository struct {
+	FullName string `json:"full_name"`
+}
+
+// PRRef 是 PR 的 base/head 端點，含所屬倉庫。
+type PRRef struct {
+	Repo *Repository `json:"repo"`
+}
+
+// Comment 是 issue／PR 的討論留言（PR 的留言也走 issues comments 端點）。
+type Comment struct {
+	Body      string `json:"body"`
+	CreatedAt string `json:"created_at"`
+	User      *User  `json:"user"`
+}
+
+// Author 回傳留言者帳號；空字串表示未知。
+func (c *Comment) Author() string { return c.User.Name() }
+
+// pullMarker 標記 /issues 端點回傳的物件其實是 PR
+// （Gitea 只會在 PR 上附帶 pull_request 欄位；issue 沒有此欄位）。
+type pullMarker struct{}
+
+// Issue 是 issue 物件。/issues 端點也會以此形狀回傳 PR（帶非 nil 的
+// PullRequest 標記），判斷時一律排除（同 gitea.py list_issues_for_repository）。
+type Issue struct {
+	Number      int64       `json:"number"`
+	Index       int64       `json:"index"`
+	Title       string      `json:"title"`
+	State       string      `json:"state"`
+	Body        string      `json:"body"`
+	ClosedAt    string      `json:"closed_at"`
+	HTMLURL     string      `json:"html_url"`
+	URL         string      `json:"url"`
+	UpdatedAt   string      `json:"updated_at"`
+	Updated     string      `json:"updated"`
+	CreatedAt   string      `json:"created_at"`
+	Created     string      `json:"created"`
+	User        *User       `json:"user"`
+	Assignee    *User       `json:"assignee"`
+	Assignees   []User      `json:"assignees"`
+	PullRequest *pullMarker `json:"pull_request"`
+	Repository  *Repository `json:"repository"`
+
+	// Raw 是本次回應的完整原始 JSON。清單類命令（mine／pulls）必須原樣輸出
+	// （gitea.py 直接傾印 API 原始物件），作為交叉驗證一致的基礎。
+	Raw json.RawMessage `json:"-"`
+}
+
+// UnmarshalJSON 解碼各判斷欄位，並保留原始 JSON 供原樣輸出。
+func (i *Issue) UnmarshalJSON(data []byte) error {
+	type issueAlias Issue
+	var a issueAlias
+	if err := json.Unmarshal(data, &a); err != nil {
+		return err
+	}
+	*i = Issue(a)
+	i.Raw = append(json.RawMessage(nil), data...)
+	return nil
+}
+
+// updatedKey 對應 gitea.py 的 _updated_at 回退鏈
+// （updated_at → updated → created_at → created → "9999"），
+// 供「最久未更新優先」排序；ISO8601 字串字典序與時間序一致。
+func (i *Issue) updatedKey() string {
+	for _, v := range []string{i.UpdatedAt, i.Updated, i.CreatedAt, i.Created} {
+		if v != "" {
+			return v
+		}
+	}
+	return "9999"
+}
+
+// WebURL 回傳網頁網址：先 html_url，缺漏時回退 API url。
+func (i *Issue) WebURL() string {
+	if i.HTMLURL != "" {
+		return i.HTMLURL
+	}
+	return i.URL
+}
+
+// PullRequest 是 pull request 物件（僅取判斷所需欄位）。
+type PullRequest struct {
+	Number             int64       `json:"number"`
+	Title              string      `json:"title"`
+	HTMLURL            string      `json:"html_url"`
+	URL                string      `json:"url"`
+	UpdatedAt          string      `json:"updated_at"`
+	Updated            string      `json:"updated"`
+	CreatedAt          string      `json:"created_at"`
+	Created            string      `json:"created"`
+	User               *User       `json:"user"`
+	RequestedReviewers []User      `json:"requested_reviewers"`
+	Base               *PRRef      `json:"base"`
+	Head               *PRRef      `json:"head"`
+	Repository         *Repository `json:"repository"`
+
+	// Raw 意義同 Issue.Raw。
+	Raw json.RawMessage `json:"-"`
+}
+
+// UnmarshalJSON 解碼各判斷欄位，並保留原始 JSON 供原樣輸出。
+func (p *PullRequest) UnmarshalJSON(data []byte) error {
+	type pullAlias PullRequest
+	var a pullAlias
+	if err := json.Unmarshal(data, &a); err != nil {
+		return err
+	}
+	*p = PullRequest(a)
+	p.Raw = append(json.RawMessage(nil), data...)
+	return nil
+}
+
+// updatedKey 意義同 Issue.updatedKey。
+func (p *PullRequest) updatedKey() string {
+	for _, v := range []string{p.UpdatedAt, p.Updated, p.CreatedAt, p.Created} {
+		if v != "" {
+			return v
+		}
+	}
+	return "9999"
+}
+
+// Author 回傳 PR 發起者帳號（user 欄位）。
+func (p *PullRequest) Author() string { return p.User.Name() }
+
+// WebURL 回傳網頁網址：先 html_url，缺漏時回退 API url。
+func (p *PullRequest) WebURL() string {
+	if p.HTMLURL != "" {
+		return p.HTMLURL
+	}
+	return p.URL
+}
+
+// htmlURLRepoRe 從網頁網址推回 "owner/repo"
+// （gitea.py _full_name_of 的 html_url regex 回退）。
+var htmlURLRepoRe = regexp.MustCompile(`/([^/]+/[^/]+)/(?:issues|pulls)/[0-9]+`)
+
+func repoFullNameFromURL(webURL string) string {
+	if m := htmlURLRepoRe.FindStringSubmatch(webURL); m != nil {
+		return m[1]
+	}
+	return ""
+}
+
+// FullName 從 issue 物件推回 "owner/repo"：先 repository 欄位，再以網頁網址回退。
+func (i *Issue) FullName() string {
+	if i.Repository != nil && i.Repository.FullName != "" {
+		return i.Repository.FullName
+	}
+	return repoFullNameFromURL(i.WebURL())
+}
+
+// FullName 從 PR 物件推回 "owner/repo"：repository → base.repo → head.repo →
+// 網頁網址回退（Gitea 的 /pulls 回應通常沒有 repository 欄位）。
+func (p *PullRequest) FullName() string {
+	if p.Repository != nil && p.Repository.FullName != "" {
+		return p.Repository.FullName
+	}
+	for _, ref := range []*PRRef{p.Base, p.Head} {
+		if ref != nil && ref.Repo != nil && ref.Repo.FullName != "" {
+			return ref.Repo.FullName
+		}
+	}
+	return repoFullNameFromURL(p.WebURL())
+}
+
+// parseMoment 對應 gitea.py 的 _parse_iso8601：剖析 ISO8601 字串（Z 後綴、
+// 小數秒、時區偏移皆可；無時區視為 UTC），失敗回 (零值, false)。
+// 保留原時區偏移、不轉 UTC——Python datetime.isoformat() 會原樣輸出
+// 「+08:00」這類偏移，轉了 UTC 輸出就變 +00:00，與基準位元組不相容。
+// stalled 掃描的時刻判斷（last_activity、催促冷卻）都以這裡的語義為準。
+func parseMoment(value string) (time.Time, bool) {
+	text := strings.TrimSpace(value)
+	if text == "" {
+		return time.Time{}, false
+	}
+	for _, layout := range []string{time.RFC3339Nano, time.RFC3339, "2006-01-02T15:04:05", "2006-01-02"} {
+		if t, err := time.Parse(layout, text); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
@@ -30,6 +30,11 @@ const (
 	NudgeCooldownHours = 24.0
 )

+// xrefTimelineTypes 對應 gitea.py 的 XREF_TIMELINE_TYPES：他處留言／issue
+// 提及本編號時產生的 timeline 引用事件。這類事件會刷新 updated_at，但不是
+// 本 issue 的直接活動，directLastActivity 會予以排除（agents issue #34）。
+var xrefTimelineTypes = map[string]bool{"comment_ref": true, "issue_ref": true}
+
 // xrefPattern 對應 gitea.py 的 XREF_PATTERN：#N、repo#N、owner/repo#N。
 //
 // 前面不得是文數字／底線／斜線（避免切進 alterminal/bear#47 的後半段）；
@@ -37,85 +42,11 @@ const (
 // Go 的 regexp 不支援 lookbehind，改在掃描時檢查前一字元。
 var xrefPattern = regexp.MustCompile(`([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?)?#(\d+)`)

-// User 是 Gitea user 物件的精簡投影。
-type User struct {
-	Username string `json:"username"`
-}
-
-// Comment 是 issue／PR 留言的精簡投影。
-type Comment struct {
-	User      User      `json:"user"`
-	Body      string    `json:"body"`
-	CreatedAt time.Time `json:"created_at"`
-}
-
-// Author 回傳留言作者帳號；空字串表示無法判定。
-func (c Comment) Author() string { return c.User.Username }
-
-// Issue 是 issue 的精簡投影（Gitea /repos/{owner}/{repo}/issues，不含 PR）。
-type Issue struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Body      string     `json:"body"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL        string    `json:"html_url"`
-	Assignees  []User    `json:"assignees"`
-	Repository Reference `json:"repository"`
-	// PullRequest 非 nil 表示這其實是 PR（Gitea 的 /issues API 兩者都回）。
-	PullRequest any `json:"pull_request,omitempty"`
-}
-
-// Reference 是 repository 物件的精簡投影（issue 物件帶 full_name）。
-type Reference struct {
-	FullName string `json:"full_name"`
-}
-
-// Ref 是 PR base/head 的精簡投影（PR 物件沒有 repository 欄位，改讀 base/head.repo）。
-type Ref struct {
-	Repo Reference `json:"repo"`
-}
-
-// PullRequest 是 /repos/{owner}/{repo}/pulls 物件的精簡投影。
-type PullRequest struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL                string `json:"html_url"`
-	Base               Ref    `json:"base"`
-	Head               Ref    `json:"head"`
-	RequestedReviewers []User `json:"requested_reviewers"`
-}
-
-// FullName 回傳 "owner/repo"；PR 沒有 repository 欄位，改讀 base（再退 head）。
-func (p PullRequest) FullName() string {
-	if p.Base.Repo.FullName != "" {
-		return p.Base.Repo.FullName
-	}
-	return p.Head.Repo.FullName
-}
-
-// Repository 是 /orgs/{org}/repos 物件的精簡投影。
-type Repository struct {
-	Name            string `json:"name"`
-	Empty           bool   `json:"empty"`
-	HasPullRequests *bool  `json:"has_pull_requests"`
-}
-
 // Item 是 stalled 掃描的單筆輸出（欄位對應 gitea.py 的 find_stalled_work）。
 type Item struct {
 	Type           string
 	Repo           string
-	Number         int
+	Number         int64
 	Title          string
 	URL            string
 	Assignees      []string
@@ -195,7 +126,7 @@ func writeJSON(b *strings.Builder, v any) {
 // Child 是父追蹤項的子項活動摘要。
 type Child struct {
 	Repo   string `json:"repo"`
-	Number int    `json:"number"`
+	Number int64  `json:"number"`
 	Title  string `json:"title"`
 	State  string `json:"state"`
 	// LastActivityAt 用指標：子項無可解析時刻時 Python 輸出 null（不是 ""）。
@@ -206,7 +137,7 @@ type Child struct {
 type XrefTarget struct {
 	Owner  string
 	Repo   string
-	Number int
+	Number int64
 }

 // Source 是 stalled 掃描需要的資料源（CLI 層以 API 實作；測試注入假資料）。
@@ -214,15 +145,18 @@ type Source interface {
 	// MyOrganizations 回傳目前帳號所屬組織清單。
 	MyOrganizations() ([]string, error)
 	// OrganizationRepositories 回傳組織的倉庫清單。
-	OrganizationRepositories(org string) ([]Repository, error)
+	OrganizationRepositories(org string) ([]Repo, error)
 	// OpenIssues 回傳倉庫的 open issues（Gitea 會混入 PR，由掃描端過濾）。
 	OpenIssues(owner, repo string) ([]Issue, error)
 	// OpenPulls 回傳倉庫的 open pull requests。
 	OpenPulls(owner, repo string) ([]PullRequest, error)
 	// IssueComments 回傳 issue／PR 的留言。
-	IssueComments(owner, repo string, number int) ([]Comment, error)
+	IssueComments(owner, repo string, number int64) ([]Comment, error)
 	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
-	TryGetIssue(owner, repo string, number int) (Issue, bool, error)
+	TryGetIssue(owner, repo string, number int64) (Issue, bool, error)
+	// IssueTimeline 回傳 issue 的 timeline 事件（GET /repos/{o}/{r}/issues/{n}/timeline，
+	// 分頁）。directLastActivity 用來排除跨 issue 引用事件（agents issue #34）。
+	IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error)
 }

 // iterXrefs 產出文字中的 (prefix, number) 配對（對應 _iter_issue_xrefs）。
@@ -278,7 +212,7 @@ func ResolveXrefTargets(org, repo string, texts []string, myOrgs map[string]bool
 	for _, text := range texts {
 		for _, pair := range iterXrefs(text) {
 			prefix, numberStr := pair[0], pair[1]
-			var number int
+			var number int64
 			if _, err := fmt.Sscanf(numberStr, "%d", &number); err != nil || number <= 0 {
 				continue
 			}
@@ -334,26 +268,39 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 		if gerr != nil || !ok {
 			continue
 		}
-		if t.Owner == org && t.Repo == repo && child.Number == parent.Number {
+		if t.Owner == org && t.Repo == repo && child.issueNumber() == parent.issueNumber() {
 			continue // 自我引用
 		}
-		if !parent.CreatedAt.IsZero() && !child.CreatedAt.IsZero() && !child.CreatedAt.After(parent.CreatedAt) {
+		parentCreated, pcOK := parseMoment(parent.CreatedAt)
+		childCreated, ccOK := parseMoment(child.CreatedAt)
+		if pcOK && ccOK && !childCreated.After(parentCreated) {
 			continue // 上行引用（父項回指更早或同時的 issue）；時間未知則不排除
 		}
+		// 子項的直接活動：created_at、state 變更（closed_at）、留言（agents #32）。
+		// 原始 updated_at 不放入已知活動，另經 directLastActivity 核對後採計
+		//（與 considerIssue／considerPull 對本 issue 自身的處理同構）。
 		var ms []time.Time
-		if !child.UpdatedAt.IsZero() {
-			ms = append(ms, child.UpdatedAt)
+		if m, ok := parseMoment(child.CreatedAt); ok {
+			ms = append(ms, m)
 		}
-		if child.ClosedAt != nil && !child.ClosedAt.IsZero() {
-			ms = append(ms, *child.ClosedAt)
+		if m, ok := parseMoment(child.ClosedAt); ok {
+			ms = append(ms, m)
 		}
 		if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
 			for _, c := range cs {
-				if !c.CreatedAt.IsZero() {
-					ms = append(ms, c.CreatedAt)
+				if m, ok := parseMoment(c.CreatedAt); ok {
+					ms = append(ms, m)
 				}
 			}
 		}
+		if childUpdated, ok := parseMoment(child.UpdatedAt); ok {
+			// 子項 updated_at 可能被 comment_ref／issue_ref 引用事件刷新
+			//（agents #38）：走與本 issue 自身相同的 directLastActivity 排除
+			// 邏輯（同源判定，不漂移）；timeline 失敗時保守沿用 updated_at。
+			if d, ok := directLastActivity(src, t.Owner, t.Repo, t.Number, childUpdated, true, ms); ok {
+				ms = append(ms, d)
+			}
+		}
 		var last *string
 		if len(ms) > 0 {
 			latest := maxTime(ms)
@@ -374,6 +321,71 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 	return moments, children
 }

+// TimelineEvent 是 issue timeline 的單一事件（僅取判斷所需欄位；
+// 對應 gitea.py _direct_last_activity 讀取的 timeline 物件）。
+type TimelineEvent struct {
+	Type      string `json:"type"`
+	CreatedAt string `json:"created_at"`
+}
+
+// directLastActivity 排除跨 issue 引用事件後，本 issue 的最後直接活動時刻
+// （對應 gitea.py 的 _direct_last_activity；agents issues #34/#38/#40）。
+//
+// 他處留言／issue 提及本編號（comment_ref／issue_ref）也會刷新 updated_at，
+// 直接採用會虛假刷新停滯時鐘（false negative）並低估 stalled_hours。
+// updated_at 不晚於已知直接活動（留言、created_at、#32 納入的子項活動）時，
+// updated_at 本身可信，不必多打一次 timeline API；只有 updated_at 晚於全部
+// 已知活動時才拉 timeline 核對：排除引用類事件後取最晚事件時刻；若最晚的
+// 都是引用事件（本 issue 無直接活動可對應 updated_at），則回退已知直接活動
+// 的最晚時刻（agents #40）。timeline 拉取失敗時沿用 updated_at（不中斷掃描、
+// 寧可少報不誤報缺失活動）。
+func directLastActivity(src Source, org, repo string, number int64, updatedAt time.Time, hasUpdated bool, known []time.Time) (time.Time, bool) {
+	if !hasUpdated {
+		return time.Time{}, false
+	}
+	var knownMax *time.Time
+	for i := range known {
+		if known[i].IsZero() {
+			continue
+		}
+		if knownMax == nil || known[i].After(*knownMax) {
+			m := known[i]
+			knownMax = &m
+		}
+	}
+	if knownMax == nil || !updatedAt.After(*knownMax) {
+		return updatedAt, true
+	}
+	timeline, err := src.IssueTimeline(org, repo, number)
+	if err != nil {
+		return updatedAt, true
+	}
+	var moments []time.Time
+	for _, e := range timeline {
+		if xrefTimelineTypes[e.Type] {
+			continue
+		}
+		if m, ok := parseMoment(e.CreatedAt); ok {
+			moments = append(moments, m)
+		}
+	}
+	if len(moments) == 0 {
+		// timeline 全為引用事件：updated_at 完全由他處提及刷新，本 issue 沒有
+		// 可對應的直接活動。回退已知直接活動的最晚時刻，避免把被刷新的
+		// updated_at 當活動、低估停滯時數（agents #40）；連已知活動都沒有時才
+		// 保守沿用 updated_at（不中斷掃描、寧可少報不誤報缺失活動）。
+		if knownMax != nil {
+			return *knownMax, true
+		}
+		return updatedAt, true
+	}
+	latest := maxTime(moments)
+	if latest.Before(updatedAt) {
+		return latest, true
+	}
+	return updatedAt, true
+}
+
 func maxTime(ts []time.Time) time.Time {
 	best := ts[0]
 	for _, t := range ts[1:] {
@@ -384,20 +396,6 @@ func maxTime(ts []time.Time) time.Time {
 	return best
 }

-func usernames(users []User) []string {
-	var out []string
-	seen := map[string]bool{}
-	for _, u := range users {
-		if u.Username == "" || seen[u.Username] {
-			continue
-		}
-		seen[u.Username] = true
-		out = append(out, u.Username)
-	}
-	sort.Strings(out)
-	return out
-}
-
 // ScanStalled 掃描跨組織的停滯 open issues／PR（對應 find_stalled_work）。
 //
 // 判定：最後活動（留言時間與本身 updated_at 取較晚者，父追蹤項再加計
@@ -468,7 +466,7 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 				if err != nil {
 					continue
 				}
-				if item, ok := considerPull(pr, comments, username, threshold, now); ok {
+				if item, ok := considerPull(src, org, r.Name, pr, comments, username, threshold, now); ok {
 					items = append(items, item)
 				}
 			}
@@ -483,15 +481,28 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 // considerIssue 對單一 issue 套用停滯判定（對應 _consider 的 issue 分支）。
 func considerIssue(src Source, org, repo string, issue Issue, comments []Comment, username string, threshold float64, now time.Time, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (Item, bool) {
 	childMoments, children := childActivity(src, org, repo, issue, comments, myOrgs, orgRepos)
-	assignees := usernames(issue.Assignees)
-	moments := []time.Time{issue.UpdatedAt, issue.CreatedAt}
+	assignees := AssigneeNames(&issue)
+	// 已知直接活動：留言、created_at、#32 納入的子項活動。
+	var known []time.Time
+	if m, ok := parseMoment(issue.CreatedAt); ok {
+		known = append(known, m)
+	}
 	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
-			moments = append(moments, c.CreatedAt)
+		if m, ok := parseMoment(c.CreatedAt); ok {
+			known = append(known, m)
 		}
 	}
-	moments = append(moments, childMoments...)
-	moments = nonZero(moments)
+	known = append(known, childMoments...)
+	// 跨 issue 引用（comment_ref／issue_ref）也會刷新 updated_at（agents #34）：
+	// updated_at 晚於全部已知直接活動時，先排除引用事件核對後才採用，
+	// 避免停滯時鐘被虛假刷新或低估 stalled_hours。
+	var moments []time.Time
+	if m, ok := parseMoment(issue.UpdatedAt); ok {
+		if d, ok2 := directLastActivity(src, org, repo, issue.issueNumber(), m, ok, known); ok2 {
+			moments = append(moments, d)
+		}
+	}
+	moments = append(moments, known...)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -500,16 +511,21 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 	if stalled < threshold {
 		return Item{}, false
 	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
+	last := LastComment(comments)
+	lastCommentBy := ""
+	if last != nil {
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
 			return Item{}, false
 		}
+	}
 	reason := "waiting-outside"
 	switch {
 	case len(assignees) == 0:
 		reason = "no-assignee"
-	case lastCommentBy != "" && containsStr(assignees, lastCommentBy):
+	case lastCommentBy != "" && containsString(assignees, lastCommentBy):
 		reason = "assignee-idle"
 	case lastCommentBy == "":
 		reason = "no-commenter"
@@ -518,8 +534,8 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 		reason = "parent-tracking"
 	}
 	item := Item{
-		Type: "issue", Repo: issue.Repository.FullName, Number: issue.Number,
-		Title: issue.Title, URL: issue.URL,
+		Type: "issue", Repo: issue.FullName(), Number: issue.issueNumber(),
+		Title: issue.Title, URL: issue.WebURL(),
 		Assignees:     assignees,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -531,16 +547,28 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 }

 // considerPull 對單一 PR 套用停滯判定（對應 _consider 的 pull 分支）。
-func considerPull(pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
-	reviewers := usernames(pr.RequestedReviewers)
-	author := pr.Author.Username
-	moments := []time.Time{pr.UpdatedAt, pr.CreatedAt}
+func considerPull(src Source, org, repo string, pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
+	reviewers := ReviewerNames(&pr)
+	author := pr.Author()
+	// 已知直接活動：留言、created_at。
+	var known []time.Time
+	if m, ok := parseMoment(pr.CreatedAt); ok {
+		known = append(known, m)
+	}
 	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
-			moments = append(moments, c.CreatedAt)
+		if m, ok := parseMoment(c.CreatedAt); ok {
+			known = append(known, m)
 		}
 	}
-	moments = nonZero(moments)
+	// 跨 issue 引用也會刷新 PR 的 updated_at（agents #34）：與 issue 同一道
+	// directLastActivity 排除邏輯（同源判定，不漂移）。
+	var moments []time.Time
+	if m, ok := parseMoment(pr.UpdatedAt); ok {
+		if d, ok2 := directLastActivity(src, org, repo, pr.Number, m, ok, known); ok2 {
+			moments = append(moments, d)
+		}
+	}
+	moments = append(moments, known...)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -549,23 +577,28 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	if stalled < threshold {
 		return Item{}, false
 	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
+	last := LastComment(comments)
+	lastCommentBy := ""
+	if last != nil {
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
 			return Item{}, false
 		}
+	}
 	reason := "no-commenter"
 	switch {
 	case len(reviewers) == 0:
 		reason = "no-reviewer"
 	case lastCommentBy == author:
 		reason = "author-idle"
-	case lastCommentBy != "" && containsStr(reviewers, lastCommentBy):
+	case lastCommentBy != "" && containsString(reviewers, lastCommentBy):
 		reason = "reviewer-idle"
 	}
 	item := Item{
 		Type: "pull", Repo: pr.FullName(), Number: pr.Number,
-		Title: pr.Title, URL: pr.URL,
+		Title: pr.Title, URL: pr.WebURL(),
 		Author: author, Reviewers: reviewers,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -573,19 +606,6 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	return item, true
 }

-// lastComment 回傳最後一則留言（created_at 最新者）的時間與作者。
-func lastComment(comments []Comment) (time.Time, string) {
-	var best time.Time
-	by := ""
-	for _, c := range comments {
-		if c.CreatedAt.After(best) {
-			best = c.CreatedAt
-			by = c.Author()
-		}
-	}
-	return best, by
-}
-
 func anyOpen(children []Child) bool {
 	for _, c := range children {
 		if c.State == "open" {
@@ -595,25 +615,6 @@ func anyOpen(children []Child) bool {
 	return false
 }

-func containsStr(list []string, s string) bool {
-	for _, x := range list {
-		if x == s {
-			return true
-		}
-	}
-	return false
-}
-
-func nonZero(ts []time.Time) []time.Time {
-	out := make([]time.Time, 0, len(ts))
-	for _, t := range ts {
-		if !t.IsZero() {
-			out = append(out, t)
-		}
-	}
-	return out
-}
-
 // round1 舍入到小數一位（對應 Python round(x, 1)）。
 // 經 strconv 的十進位正確舍入（半偶數），與 Python 的浮點 round 行為一致，
 // 避免 (x*10+0.5) 截斷在 .x5 邊界產生偏差。
@@ -624,3 +625,111 @@ func round1(v float64) float64 {
 	}
 	return r
 }
+
+// ── CLI 接線用的高階入口（#7：teai stalled／teai xrefs）─────────────────
+
+// StalledSource 是 stalled／xrefs 命令需要的完整資料源：
+// Source（掃描用讀取）加上目前帳號與單一 issue 查詢。
+// APIClient（giteaapi.go）實作此介面；測試以假資料源注入。
+type StalledSource interface {
+	Source
+	// CurrentUser 回傳目前帳號名（催促冷卻判定用）。
+	CurrentUser() (string, error)
+	// GetIssue 嚴格版單一 issue／PR 查詢；失敗回錯誤（xrefs 命令用，
+	// 404 應回 ErrAPI 由 CLI 映射結束碼 3）。
+	GetIssue(owner, repo string, number int64) (Issue, error)
+}
+
+// RunStalled 是 teai stalled 的核心：解析目前帳號後跑 ScanStalled。
+// hours <= 0 時採 StalledDefaultHours（對應 gitea.py stalled [--hours N]
+// 的預設 4 小時）；旗標層已先攔下非正數，這裡是防禦。
+func RunStalled(src StalledSource, hours float64, now time.Time) ([]Item, error) {
+	if hours <= 0 {
+		hours = StalledDefaultHours
+	}
+	username, err := src.CurrentUser()
+	if err != nil {
+		return nil, err
+	}
+	return ScanStalled(src, username, hours, now)
+}
+
+// XrefHit 是 teai xrefs 的單筆輸出：解析後的目標加上出處
+// （README 規格："body"＝內文、"comment"＝留言）。
+type XrefHit struct {
+	Owner  string `json:"owner"`
+	Repo   string `json:"repo"`
+	Number int64  `json:"number"`
+	Source string `json:"source"`
+}
+
+// ResolveIssueXrefs 是 teai xrefs 的核心：取回單一 issue／PR 的內文與
+// 全部留言，解析其中的 #N、repo#N、owner/repo#N 引用（規則同
+// ResolveXrefTargets：單段 repo 僅在父項所屬組織有該倉庫時解析、
+// owner/repo#N 僅在 owner 為所屬組織時解析），去重並保留出現順序，
+// 每筆附首次出現的出處（內文先於留言）。stalled 的父追蹤項判定
+// 內部用同一套解析，不重複實作。
+func ResolveIssueXrefs(src StalledSource, owner, repo string, number int64) ([]XrefHit, error) {
+	issue, err := src.GetIssue(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	comments, err := src.IssueComments(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	orgs, err := src.MyOrganizations()
+	if err != nil {
+		return nil, err
+	}
+	myOrgs := make(map[string]bool, len(orgs))
+	for _, o := range orgs {
+		myOrgs[o] = true
+	}
+	// 組織倉庫清單跨呼叫快取，避免逐則留言重打 API。
+	orgRepoCache := map[string][]string{}
+	orgRepos := func(org string) ([]string, error) {
+		if names, ok := orgRepoCache[org]; ok {
+			return names, nil
+		}
+		repos, err := src.OrganizationRepositories(org)
+		if err != nil {
+			return nil, err
+		}
+		names := make([]string, 0, len(repos))
+		for _, r := range repos {
+			if r.Name != "" {
+				names = append(names, r.Name)
+			}
+		}
+		orgRepoCache[org] = names
+		return names, nil
+	}
+	type sourceText struct {
+		text   string
+		source string
+	}
+	texts := []sourceText{{issue.Body, "body"}}
+	for _, c := range comments {
+		texts = append(texts, sourceText{c.Body, "comment"})
+	}
+	var hits []XrefHit
+	seen := map[XrefTarget]bool{}
+	for _, t := range texts {
+		targets, err := ResolveXrefTargets(owner, repo, []string{t.text}, myOrgs, orgRepos)
+		if err != nil {
+			return nil, err
+		}
+		for _, target := range targets {
+			if seen[target] {
+				continue
+			}
+			seen[target] = true
+			hits = append(hits, XrefHit{
+				Owner: target.Owner, Repo: target.Repo,
+				Number: target.Number, Source: t.source,
+			})
+		}
+	}
+	return hits, nil
+}
@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -21,18 +22,20 @@ func at(minutes int) time.Time {
 // fakeSource 是注入假資料的 Source。
 type fakeSource struct {
 	orgs  []string
-	repos map[string][]Repository
+	repos map[string][]Repo
 	// issues[owner/repo][number]
-	issues map[string]map[int]Issue
+	issues map[string]map[int64]Issue
 	// pulls[owner/repo]
 	pulls map[string][]PullRequest
 	// comments[owner/repo/number]
 	comments map[string][]Comment
+	// timelines[owner/repo/number]：issue timeline 事件（nil → 空 timeline）。
+	timelines map[string][]TimelineEvent
 }

 func (f *fakeSource) MyOrganizations() ([]string, error) { return f.orgs, nil }

-func (f *fakeSource) OrganizationRepositories(org string) ([]Repository, error) {
+func (f *fakeSource) OrganizationRepositories(org string) ([]Repo, error) {
 	return f.repos[org], nil
 }

@@ -41,6 +44,8 @@ func (f *fakeSource) OpenIssues(owner, repo string) ([]Issue, error) {
 	for _, i := range f.issues[owner+"/"+repo] {
 		out = append(out, i)
 	}
+	// 對齊真實 API：issues 依 id（=number）遞增回傳，消除 map 迭代隨機性。
+	sort.Slice(out, func(a, b int) bool { return out[a].Number < out[b].Number })
 	return out, nil
 }

@@ -48,11 +53,15 @@ func (f *fakeSource) OpenPulls(owner, repo string) ([]PullRequest, error) {
 	return f.pulls[owner+"/"+repo], nil
 }

-func (f *fakeSource) IssueComments(owner, repo string, number int) ([]Comment, error) {
+func (f *fakeSource) IssueComments(owner, repo string, number int64) ([]Comment, error) {
 	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
 }

-func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, error) {
+func (f *fakeSource) IssueTimeline(owner, repo string, number int64) ([]TimelineEvent, error) {
+	return f.timelines[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
+}
+
+func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
 	i, ok := f.issues[owner+"/"+repo][number]
 	if !ok {
 		return Issue{}, false, nil
@@ -60,11 +69,14 @@ func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, e
 	return i, true, nil
 }

-func repoWith(name string, hasPR bool) []Repository {
+func repoWith(name string, hasPR bool) []Repo {
 	h := hasPR
-	return []Repository{{Name: name, HasPullRequests: &h}}
+	return []Repo{{Name: name, HasPullRequests: &h}}
 }

+// iso 把相對分鐘轉成 parseMoment 可剖析的 ISO8601 字串（假資料用）。
+func iso(minutes int) string { return FormatMoment(at(minutes)) }
+
 func mustResolve(t *testing.T, org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) []XrefTarget {
 	t.Helper()
 	targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
@@ -157,21 +169,21 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs: []string{"alterminal"},
-		repos: map[string][]Repository{
+		repos: map[string][]Repo{
 			"alterminal": repoWith("agents", true),
 		},
-		issues: map[string]map[int]Issue{
+		issues: map[string]map[int64]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/agents"}, URL: "u1"},
-				2: {Number: 2, Title: "分派者自己最後留言", State: "open", Author: User{"ceo"}, CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u2"},
-				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u3"},
-				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u4"},
-				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: at(-30), UpdatedAt: at(-30), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u5"},
+				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/agents"}, URL: "u1"},
+				2: {Number: 2, Title: "分派者自己最後留言", State: "open", User: &User{UserName: "ceo"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u2"},
+				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u3"},
+				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u4"},
+				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: iso(-30), UpdatedAt: iso(-30), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u5"},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/agents/2": {{User: User{"ceo"}, CreatedAt: at(-300)}},
-			"alterminal/agents/4": {{User: User{"dan"}, CreatedAt: at(-300)}},
+			"alterminal/agents/2": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}},
+			"alterminal/agents/4": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -182,11 +194,11 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	if len(got) != 4 {
 		t.Fatalf("應 4 筆，got %d：%v", len(got), got)
 	}
-	byNumber := map[int]Item{}
+	byNumber := map[int64]Item{}
 	for _, it := range got {
 		byNumber[it.Number] = it
 	}
-	for n, wantReason := range map[int]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
+	for n, wantReason := range map[int64]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
 		if byNumber[n].Reason != wantReason {
 			t.Errorf("issue %d reason = %q, want %q", n, byNumber[n].Reason, wantReason)
 		}
@@ -204,15 +216,15 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("agents", true)},
-		issues: map[string]map[int]Issue{
+		repos: map[string][]Repo{"alterminal": repoWith("agents", true)},
+		issues: map[string]map[int64]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/agents"}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/agents"}},
 			},
 		},
 		comments: map[string][]Comment{
 			// admin（掃描者）10 小時前催促過 → 冷卻中，不列入。
-			"alterminal/agents/1": {{User: User{"admin"}, CreatedAt: at(-600)}},
+			"alterminal/agents/1": {{User: &User{UserName: "admin"}, CreatedAt: iso(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -223,7 +235,7 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 		t.Fatalf("催促冷卻中的項目不應列入，got %v", got)
 	}
 	// 冷卻過了（25 小時前催促）→ 重新列入。
-	src.comments["alterminal/agents/1"] = []Comment{{User: User{"admin"}, CreatedAt: at(-1500)}}
+	src.comments["alterminal/agents/1"] = []Comment{{User: &User{UserName: "admin"}, CreatedAt: iso(-1500)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -240,15 +252,15 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 應以 parent-tracking 列入並附子項摘要；子項本身則是 assignee-idle。
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: at(-700), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				7: {Number: 7, Title: "子", State: "open", CreatedAt: at(-650), UpdatedAt: at(-300), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/teai"}},
+				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: iso(-700), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+				7: {Number: 7, Title: "子", State: "open", CreatedAt: iso(-650), UpdatedAt: iso(-300), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/teai"}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/7": {{User: User{"max"}, CreatedAt: at(-300)}},
+			"alterminal/teai/7": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -286,9 +298,9 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 子項 1 小時前恢復活動 → 父項 last_activity 跟著更新，未達門檻不列入；
 	// 子項本身也不停滯。整份輸出應為空。
 	child := src.issues["alterminal/teai"][7]
-	child.UpdatedAt = at(-60)
+	child.UpdatedAt = iso(-60)
 	src.issues["alterminal/teai"][7] = child
-	src.comments["alterminal/teai/7"] = []Comment{{User: User{"max"}, CreatedAt: at(-60)}}
+	src.comments["alterminal/teai/7"] = []Comment{{User: &User{UserName: "max"}, CreatedAt: iso(-60)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -303,14 +315,21 @@ func TestScanStalledParentTrackingNotChild(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: at(-700), UpdatedAt: at(-600), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				39: {Number: 39, State: "open", CreatedAt: at(-2000), UpdatedAt: at(-60), Repository: Reference{"alterminal/teai"}},
+				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: iso(-700), UpdatedAt: iso(-600), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+				39: {Number: 39, State: "open", CreatedAt: iso(-2000), UpdatedAt: iso(-60), Repository: &Repository{FullName: "alterminal/teai"}},
 			},
 		},
 	}
+	// timeline：#47 的 updated_at 對應直接事件（assignees）、#39 對應 label
+	//（agents #34 後 updated_at 需經 timeline 核對才採計；直接事件可對應 → 採用）。
+	// 必須在 ScanStalled 之前設定——掃描當下讀不到的事後修改無效。
+	src.timelines = map[string][]TimelineEvent{
+		"alterminal/teai/47": {{Type: "assignees", CreatedAt: iso(-600)}},
+		"alterminal/teai/39": {{Type: "label", CreatedAt: iso(-60)}},
+	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -345,30 +364,30 @@ func TestScanStalledPullReasons(t *testing.T) {
 	h := true
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
+		repos: map[string][]Repo{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
 		pulls: map[string][]PullRequest{
 			"alterminal/teai": {
-				{Number: 10, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)},
-				{Number: 11, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 12, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 13, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
+				{Number: 10, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)},
+				{Number: 11, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 12, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 13, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/11": {{User: User{"max"}, CreatedAt: at(-300)}}, // author-idle
-			"alterminal/teai/12": {{User: User{"ceo"}, CreatedAt: at(-300)}}, // reviewer-idle
-			"alterminal/teai/13": {{User: User{"dan"}, CreatedAt: at(-300)}}, // no-commenter（外部留言）
+			"alterminal/teai/11": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}}, // author-idle
+			"alterminal/teai/12": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}}, // reviewer-idle
+			"alterminal/teai/13": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}}, // no-commenter（外部留言）
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
 	}
-	byNumber := map[int]Item{}
+	byNumber := map[int64]Item{}
 	for _, it := range got {
 		byNumber[it.Number] = it
 	}
-	for n, wantReason := range map[int]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
+	for n, wantReason := range map[int64]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
 		item, ok := byNumber[n]
 		if !ok {
 			t.Fatalf("PR %d 應列入，got %v", n, got)
@@ -391,15 +410,15 @@ func TestScanStalledNoPullsFlag(t *testing.T) {
 	h := false
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
-		issues: map[string]map[int]Issue{
+		repos: map[string][]Repo{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
+		issues: map[string]map[int64]Issue{
 			"alterminal/docs": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/docs"}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/docs"}},
 			},
 		},
 		pulls: map[string][]PullRequest{
 			// 即使假資料有 PR，flag 關閉也不應掃。
-			"alterminal/docs": {{Number: 2, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)}},
+			"alterminal/docs": {{Number: 2, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -416,10 +435,10 @@ func TestScanStalledSkipsPRsInIssues(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
+		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
 			"alterminal/teai": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/teai"}, PullRequest: struct{}{}},
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/teai"}, PullRequest: &pullMarker{}},
 			},
 		},
 	}
@@ -480,7 +499,7 @@ func TestPullJSON(t *testing.T) {
 // TestScanStalledEmpty 無停滯項目 → 空輸出（CLI 層輸出 []）。
 func TestScanStalledEmpty(t *testing.T) {
 	now := at(0)
-	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repository{"alterminal": repoWith("teai", true)}}
+	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repo{"alterminal": repoWith("teai", true)}}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -501,17 +520,20 @@ func TestScanStalledOrgError(t *testing.T) {
 type errSource struct{}

 func (errSource) MyOrganizations() ([]string, error) { return nil, errors.New("boom") }
-func (e errSource) OrganizationRepositories(string) ([]Repository, error) {
+func (e errSource) OrganizationRepositories(string) ([]Repo, error) {
 	return nil, errors.New("boom")
 }
 func (e errSource) OpenIssues(string, string) ([]Issue, error)      { return nil, errors.New("boom") }
 func (e errSource) OpenPulls(string, string) ([]PullRequest, error) { return nil, errors.New("boom") }
-func (e errSource) IssueComments(string, string, int) ([]Comment, error) {
+func (e errSource) IssueComments(string, string, int64) ([]Comment, error) {
 	return nil, errors.New("boom")
 }
-func (e errSource) TryGetIssue(string, string, int) (Issue, bool, error) {
+func (e errSource) TryGetIssue(string, string, int64) (Issue, bool, error) {
 	return Issue{}, false, errors.New("boom")
 }
+func (e errSource) IssueTimeline(string, string, int64) ([]TimelineEvent, error) {
+	return nil, errors.New("boom")
+}

 // TestRound1 round1 十進位舍入到一位小數（與 Python round(x,1) 半偶數一致）。
 func TestRound1(t *testing.T) {
Author	SHA1	Message	Date
ceo	36a50b95ed	Merge pull request 'docs+test：空清單輸出判決定案（維持 []／null，補 stalled 空輸出測試）（#37）' (#39 ) from fix/issue37-empty-output-docs into main	2026-09-12 23:56:52 +08:00
chenyunda218	9e699f3b4e	docs+test：空輸出判決 #37——維持 []／null、補 stalled 空輸出測試	2026-09-12 23:43:29 +08:00
queena	d689107eea	Merge pull request 'internal/workflow：directLastActivity 排除跨 issue 引用事件（#34）' (#36 ) from fix/issue34-direct-last-activity into main	2026-09-12 15:24:23 +08:00
ceo	027ed1ade9	workflow_test：fakeSource.OpenIssues 依 number 排序，消除 map 迭代隨機性審核意見（PR #36）：issue 1 與 issue 3 在新邏輯下同為 10h， sort.SliceStable 平手時順序取決於 map 迭代隨機順序， TestScanStalledIssueReasons 的 got[0].Number != 1 斷言不穩定。採建議修法 1：fakeSource.OpenIssues 回傳前依 number 遞增排序，對齊真實 Gitea API（issues 依 id 遞增）行為。實作未動。 go build / go vet / go test ./... 全綠； TestScanStalledIssueReasons -count=50 重跑全綠。	2026-09-12 15:21:21 +08:00
ceo	e4212b9c90	internal/workflow：directLastActivity 排除跨 issue 引用事件（#34）同步 agents #34/#38/#40 三個停滯判定修補到 Go 端： - Source 介面新增 IssueTimeline（GET /repos/{o}/{r}/issues/{n}/timeline，分頁）， giteaapi.go 與 cmd/xcheck 同步實作 - 新增 directLastActivity：updated_at 晚於全部已知直接活動時拉 timeline 核對，排除 comment_ref／issue_ref 引用事件後取最晚；全為引用事件回退已知直接活動最晚時刻（agents #40）；timeline 失敗保守沿用 updated_at - considerIssue／considerPull 對自身 updated_at、childActivity 對子項 updated_at （含子項 created_at 入已知活動）套用同一排除邏輯（agents #38） - 回歸測試：子項 updated_at 被引用刷新（TestRunStalledChildXrefRefresh）、 timeline 全引用事件回退與拉取失敗保守路徑（TestRunStalledTimelineAllXrefFallback） - 修正 workflow_test.go：timelines 須在 ScanStalled 呼叫前設定驗證：go build／vet／test 全綠；xcheck 對真實 API 掃描， stalled 輸出與 gitea.py（agents @ 78769ec）位元組一致（5833 bytes）。	2026-09-12 15:10:31 +08:00
queena	a2baf55fce	Merge pull request 'dailyops：list 命令 --state all 明確帶 state=all（#33）' (#35 ) from fix/issue33-state-all into main	2026-09-11 11:32:53 +08:00
chenyunda218	1f6806ff99	dailyops：list 命令 --state all 明確帶 state=all（#33） issues／milestones 端點省略 state 時 API 預設 open，closed 項目漏列； pulls 端點省略時雖回全部，仍明確帶上避免依賴端點預設。三處同修並補回歸測試（TestStateAllSendsExplicitParam）。	2026-09-11 11:29:00 +08:00
ceo	87d00ae440	Merge pull request 'milestones：跨倉庫里程碑總覽命令（#31）' (#32 ) from feat/issue31-milestones-overview into main	2026-09-10 21:26:39 +08:00
chenyunda218	744e7ad809	milestones：新增跨倉庫里程碑總覽命令（#31） - teai milestones（不帶 --repo）輸出跨所屬組織各倉庫 open 里程碑概況，對應 gitea.py milestones（管理者巡邏，agents AGENTS.md 10.1）：欄位 repo/id/title/url/open_issues/closed_issues/due_on/due_hours/ overdue/unassigned/updated_at，排序期限近者在前、無期限最後。 - internal/workflow.MilestoneOverview：判定核心（Source 注入、離線可測）； MilestoneEntry 自訂 MarshalJSON，鍵集鍵序與 gitea.py 全等（null 表示、due_hours 定點一位、unassigned PR 條目帶 author）。 - internal/workflow.APIClient 增 OpenMilestones／MilestoneOpenIssues （issues 端點刻意不帶 type=issues，PR 條目保留供覆蓋檢查，同 gitea.py）。 - milestones --repo a/b 維持現行單倉庫 list 語義不變。 - 空清單輸出 []（gitea.py 無輸出；#26 慣例差異，README 已文件化）。 - 交叉驗證：同帳號同時跑 gitea.py milestones 與 teai milestones，含逾期／未到期／無期限里程碑與未分派 issue／PR 條目，輸出位元組全等。	2026-09-10 21:20:19 +08:00
chenyunda218	fd3b8cbd6b	Merge pull request 'docs：已知輸出差異補 mine／pulls 欄位集差異（#26）' (#27 ) from docs/issue26-output-fieldset-diff into main Reviewed-on: #27	2026-09-10 18:51:29 +08:00
queena	3a587f60ad	Merge pull request 'internal/cli：允許命令旗標與位置參數交錯（#25）' (#28 ) from fix/issue25-interleaved-flags into main	2026-09-10 15:38:37 +08:00
alex	3ed20b6aba	internal/cli：允許命令旗標與位置參數交錯（#25） parseFlags 改為先分離旗標與位置參數、再剖析旗標串、最後以第二次 Parse 把位置參數設回 fs.Args；Go 標準 flag 遇位置參數即停止的問題不再影響「位置參數在前、旗標在後」的用法（teai api --method、 issues/pulls view --comments 等照 README 範例可用了）。 - login.go／workflow_commands.go 直接呼叫 fs.Parse 的六處改走 parseFlags，行為一致（login default/remove 的名稱也可與旗標交錯）。 - errHelp（命令 -h/--help）在 exitCodeFor 視為成功，與其既有註解宣稱一致；命令層 -h 結束碼由 1/2 修正為 0。 - 新增 interleaved_flags_test.go 回歸測試：api／issues view／ pulls view／stalled／login default／login remove 的交錯組合。	2026-09-10 15:35:16 +08:00
ceo	3d555e38d9	docs：已知輸出差異補 mine／pulls 欄位集差異（#26） gitea.py 的 mine／pulls 輸出完整 API 物件是 _dump 直接傾倒的副作用，欄位集隨 Gitea 版本浮動；teai 維持策展摘要欄位（機器可讀優先），交叉驗證比對項目集合與判定語義，不逐欄位比對。判定 #26。	2026-09-10 15:24:09 +08:00
alex	ffae335e62	Merge pull request 'internal/cli：stalled 與 xrefs 命令接線，完成 #7 CLI 層（堆疊於 #23）' (#24 ) from feat/issue7-cli-stalled-xrefs into main	2026-09-10 12:30:10 +08:00
ceo	ab94cdce9f	internal/cli：stalled 與 xrefs 命令接線，完成 #7 CLI 層（堆疊於 #23） - workflow 新增 StalledSource 介面（Source＋CurrentUser＋GetIssue）與高階入口 RunStalled／ResolveIssueXrefs（xrefs 輸出附 source 出處） - APIClient 補上 StalledSource 面向（GetIssue／TryGetIssue 等） - CLI 新增 teai stalled [--hours N]（JSON 與 gitea.py 位元組相容：停用 HTML 轉義、縮排 2）與 teai xrefs <owner>/<repo> <number> （404 → exit 3）；table 模式 stalled_hours 定點一位小數 - 接線層與 workflow 層單元測試（注入假資料源、固定時刻） - README 狀態行更新驗證：go build／vet／test 全綠；對真實 API 並行掃描，stalled 輸出與 gitea.py 位元組一致（2169 bytes）；xrefs 邊界案例（PR#50／ issue#49 略過、CJK 緊鄰、跨倉庫 owner/repo#N）與 Python 版一致。	2026-09-10 12:20:39 +08:00
chenyunda218	32c3b30934	Merge pull request 'internal/workflow：統一型別宣告，修復 main 編譯失敗（#21）' (#23 ) from fix/issue21-workflow-types into main Reviewed-on: #23	2026-09-10 11:45:39 +08:00
ceo	5f323a685e	合併 main（47056dd）保持 #23 分支最新	2026-09-10 11:41:49 +08:00
ceo	4582dfaa4e	internal/workflow：統一型別宣告，修復 #12 合併後 main 編譯失敗（#21） #12 的 workflow.go 與 #13 的 types.go 各自宣告 User／Comment／Issue／ PullRequest／Repository，文字合併無衝突但語意衝突，main 自 `a8c1f3e` 起 go build 失敗。統一採 #13 的字串模型（types.go 為唯一型別來源）： - Issue／Comment 補 State／Body／ClosedAt 欄位，新增 parseMoment （對應 gitea.py _parse_iso8601；保留原時區偏移，輸出與 Python isoformat 位元組一致） - workflow.go 移除重複宣告，stalled／xref 邏輯改用該模型與 judge.go 既有輔助（AssigneeNames／ReviewerNames／LastComment／containsString） - Source 介面 number 改 int64（與 types.go 對齊），cmd/xcheck 同步 - workflow_test.go 測試資料改新型別模型（字串時刻、指標欄位）驗證： - go build／go vet／go test ./... 全綠（#6 與 #7 案例皆未回歸） - xcheck 對真實 API 並行掃描，stalled 輸出與 gitea.py 位元組一致（含 bear-cli#9 父追蹤項子項摘要、+08:00 時區偏移） - xref 邊界案例（nope#9／PR#50 略過、bear-cli#9 內嵌解析）與 Python 一致	2026-09-10 11:32:40 +08:00
alex	47056dda43	Merge pull request 'docs：README 補上完整安裝指南（#15）' (#22 ) from docs/issue15-install-guide into main	2026-09-10 11:26:25 +08:00
ceo	9948357f52	docs：README 補上完整安裝指南（#15）	2026-09-10 10:48:12 +08:00
alex	0b0c3cefcb	Merge pull request 'internal/cli：命令保留旗標機制，修正 login add 旗標被全域剖析搶走（#18）' (#20 ) from fix/issue18-reserved-flags into main	2026-09-10 10:37:20 +08:00
queena	a8c1f3e018	Merge pull request 'internal/workflow：xref 解析與 stalled 掃描核心邏輯（#7）' (#12 ) from feat/issue7-stalled-xrefs into main	2026-09-10 10:35:35 +08:00
max	0ed6f262c8	合併 main（4a34def）並把 exitcode_test.go 四處 extractGlobals 呼叫補上第三參數 nil（#20）	2026-09-10 10:32:53 +08:00
max	fb2990dc04	Merge remote-tracking branch 'origin/main' into fix/issue18-reserved-flags	2026-09-10 10:32:19 +08:00
ceo	4a34def1f5	Merge pull request 'gitea.py 工作流命令 Go 化：whoami/orgs/members/pulls/mine/next（#6）' (#13 ) from feature/issue6-workflow-commands into main	2026-09-10 10:24:21 +08:00
ceo	15c2d35935	合併 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 無關）。	2026-09-10 10:22:42 +08:00
max	c4fb641094	internal/cli：命令保留旗標機制，login add 的 --url/--token 不再被全域剖析搶走（#18）	2026-09-10 10:22:39 +08:00
queena	f7d63d6e8f	Merge pull request '測試改斷言具體結束碼數值，對照 README 規格（#10）' (#19 ) from fix/issue10-exitcode-tests into main	2026-09-10 10:20:23 +08:00
chenyunda218	f481377b9a	測試改斷言具體結束碼數值，對照 README 規格（#10） cli_test、dailyops_commands_test、login_test、exitcode_test 原以 int(ExitUsage)/int(ExitAPI)/int(ExitInternal) 常數互比，常數若再與 README 脫鉤測試仍會綠。改為直接斷言 0/2/3（內部錯誤 1）。常數本體已隨 #5（6951817）改為明確數值，未知命令實測回 2。	2026-09-10 10:12:35 +08:00
ceo	c5d5c37eae	Merge pull request '日常操作命令：issues/pulls/labels/milestones/releases/repos/api（#8）' (#16 ) from feature/issue8-dailyops into main	2026-09-10 09:54:23 +08:00
alex	a2be70ea7d	Merge pull request '實現 login 指令（#14）：tea 相容組態管理' (#17 ) from feature/issue14-login into main	2026-09-10 09:48:43 +08:00
chenyunda218	927855d3ca	cli：修正帶旗標命令被全域剖析攔下的阻斷問題（#13 審核） - parseGlobals 改為抽取式 extractGlobals：只取走已知全域選項，非全域選項（--has-work／--mine／--reviewer／--repo）原樣交回子命令 flagset，任何順序（含與全域選項交錯）皆可解析；-- 之後停止抽取。 - runVersion 補參數檢查：version --wat 仍回 exit 2。 - workflow：commentsFor 對 number<=0 視為無留言，不打 API（對齊 gitea.py 在 number 缺漏時跳過留言檢查，避免 issues/0/comments 404 中斷掃描）。 - 新增 internal/cli/workflow_commands_test.go：以注入假 client 的接線層測試補上 workflow 單元測試覆蓋不到的分派路徑（members --has-work、 pulls --mine/--reviewer/--repo、全域選項交錯、next null/table）。 - README：註明與 gitea.py 的已知輸出差異（空清單 [] vs 無輸出；全域選項可出現在命令前後）。實機交叉驗證（alex）：members --has-work、pulls --mine/--reviewer、 pulls --repo、next、mine 兩者輸出一致；go vet／test 全綠。	2026-09-10 09:41:53 +08:00
ceo	f8fc16ae49	實現 login 指令（#14）：tea 相容組態管理 - internal/gitea/config.go：tea 組態的行級編輯引擎（新增／更新／設預設／移除），未知欄位與 preferences 區段逐字保留；原子寫入（暫存檔 + rename，0600）。 - internal/cli/login.go：teai login list/add/default/remove。add 先以 token 呼叫 GET /user 驗證，成功才寫入並記下帳號；未給 --token 時自 stdin 讀一行；401 結束碼 3。未給 --name 時同站既有項目就地更新。 - 輸出欄位 name/url/user/default，永不輸出 token。 - 測試：編輯引擎 12 項、指令層 11 項（httptest 假 API），並以真 tea 驗證 teai 寫出的組態可互通（tea whoami 讀出同帳號）。 Closes #14	2026-09-10 09:32:53 +08:00
alex	c311f02e0f	合併 main（#4 藍圖修訂）並整合 README：日常操作段落以 #8 實作內容為準	2026-09-10 09:20:44 +08:00
alex	7badd9e46d	internal/dailyops + cli：日常操作命令 issues/pulls/labels/milestones/releases/repos/api（#8） - internal/gitea：用戶端支援寫入動詞（DoJSON/DoRaw，共用 do 核心） - internal/dailyops：七組日常操作的 API 層（issues/pulls/labels/milestones/releases/repos/api） - internal/cli：子命令接線；寫入類一律 --yes 閘門（未確認不發請求、exit 2） - teai pulls 相容 #6 工作流用法（無子命令）；有子命令走日常操作 - 修正 dispatch：命令旗標（如 --has-work、--comments）不再被誤判為未知全域選項 - teai api 支援 path 內含查詢字串 - 單元測試（httptest 假伺服器）＋真實站點交叉驗證（讀取命令輸出對照 Gitea API；寫入回路 create→comment→close 於 alex/.profile 驗證後清理）	2026-09-10 09:19:03 +08:00
chenyunda218	a7952c6834	Merge pull request '藍圖修訂：不再避開 tea 已有的功能（#3）' (#4 ) from docs/issue3-tea-parity into main Reviewed-on: #4	2026-09-10 08:54:33 +08:00
chenyunda218	5583a00bb5	internal/workflow + cli：gitea.py 工作流命令 Go 化（#6） - internal/workflow：Client 介面＋判定語義（最後留言、作者/審核者跟進、 assignee 交集、最久未更新優先），含假 client 單元測試 - internal/workflow/giteaapi.go：以 internal/gitea（#5）實作 Client - internal/cli：註冊 whoami/orgs/members/mine/pulls/next；全域選項允許出現在命令之後；結束碼 0/2/3 - 與 gitea.py 交叉驗證：next/mine/pulls/members(--has-work) 拾取一致 - 依 #5 分支 feature/issue5-gitea-client 為基底	2026-09-10 08:39:35 +08:00
ceo	afdead46e2	Merge pull request 'internal/gitea：API 用戶端、認證與輸出基礎（#5）' (#11 ) from feature/issue5-gitea-client into main	2026-09-10 08:39:02 +08:00
max	6951817313	internal/gitea：API 用戶端、認證與輸出基礎（#5） - internal/gitea：僅標準庫的 HTTP 用戶端；ListAll 以 limit=50 逐頁抓滿 - 認證選序 --token → TEAI_TOKEN → tea 組態（--config/TEA_CONFIG/預設路徑）； token 不入輸出、日誌與錯誤訊息 - 共用輸出 --output json\|table（預設 json）、--timeout（預設 30s） - CLI 結束碼 0/2/3：用法錯誤 → 2、API 錯誤（*gitea.ErrAPI）→ 3 - 單元測試：認證選序、tea 組態解析、分頁、逾時／401／5xx 錯誤映射、輸出實作 issue #5	2026-09-10 08:20:08 +08:00
ceo	9e46d233fb	藍圖修訂：不再避開 tea 已有的功能（#3） - 原則一改為「功能自主完整」：teai 自行實作完整功能集，不因 tea 已有而略過 - 新增「日常操作（tea 對等指令）」指令表：issues/pulls/labels/milestones/releases/repos/api - README 頂部與狀態區補範圍說明（#3）	2026-09-10 08:13:10 +08:00