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 全綠。

README.md

@@ -6,7 +6,7 @@ teai 是 Gitea 的命令列（CLI）輔助工具，補足官方 `tea` CLI 缺少
 
 - **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置
 - **目標站點：** `https://gitea.alterminal.com`
-- **狀態：** 專案初始化中，功能尚未開始開發；本文的指令集為設計藍圖
+- **狀態：** 基礎建設（#5：internal/gitea）與工作流命令（#6：whoami/orgs/members/mine/pulls/next）已實作；stalled/xrefs（#7）與日常操作命令（#8）進行中
 
 ## 安裝與建置
 
@@ -184,6 +184,15 @@ teai whoami               # 目前帳號（讀 tea 組態）
 | `mine` | `teai mine` | 相同 |
 | （底線函式） | `internal/` 套件 | 不設 CLI 命令；`xrefs` 為其邏輯的公開化 |
 
+已知輸出差異（刻意保留，機器可讀優先）：
+
+- **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令
+  （`mine`／`pulls`）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確，
+  交叉驗證時以此差異為準。`next` 兩者語義相同（無工作 → `null`／「沒有未完成的工作」）。
+- **全域選項位置**：teai 的全域選項（`--output` 等）可出現在命令之前或之後，
+  且可與命令旗標交錯（`teai members --has-work --output table`）；
+  gitea.py 的旗標剖析較寬鬆，兩者命令列介面以此行為對齊。
+
 遷移策略：
 
 1. 以 gitea.py 為行為基準：同帳號同時跑兩者，輸出應一致（交叉驗證）。

internal/cli/cli.go

@@ -1,14 +1,24 @@
-// 套件 cli 提供 teai 的命令列架構：引數剖析、子命令分派與輸出。
+// 套件 cli 提供 teai 的命令列架構：全域選項剖析、子命令分派與輸出。
 //
 // 設計目標是讓之後新增子命令時只需註冊一個 command 結構，
 // 不需要改動分派邏輯；也讓核心功能可以被測試（Run 接受 io.Writer）。
+//
+// 結束碼（見 README「輸出與結束碼」）：
+//
+//	0 成功（含「沒有工作」→ null／[]）
+//	2 用法錯誤（未知命令／參數）
+//	3 API 錯誤（連線失敗、401、403、5xx）
 package cli
 
 import (
-	"flag"
+	"errors"
 	"fmt"
 	"io"
 	"sort"
+	"strings"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
 )
 
 // Version 是目前開發中的版本號。採用語意化版本；正式發佈前以 0 開頭。
@@ -17,13 +27,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,12 +53,37 @@ 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 是已註冊的子命令表。新增功能時在這裡註冊即可。
@@ -50,57 +97,200 @@ var commands = map[string]*command{
 
 // Run 剖析引數並分派到對應子命令，回傳行程結束碼。
 //
-// 無引數或要求說明（-h/--help）時印出用法；未知子命令回 ExitUsage。
+// 引數結構：teai [全域選項] <命令> [命令參數]。全域選項可出現在命令
+// 之前或之後（README 範例：teai next --output table）；無引數或要求說明
+// （-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 := extractGlobals(&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 strings.HasPrefix(name, "-") {
+			fmt.Fprintf(stderr, "teai: unknown global option %q\n\n", name)
+			printUsage(stderr)
+			return int(ExitUsage)
+		}
 		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,
+}
+
+// extractGlobals 從 args 中抽出全域選項（可出現在命令之前或之後），
+// 回傳其餘引數（命令與其參數，順序保留）。
+//
+// 採「抽取式」剖析：只取走已知的全域選項；任何其他引數——位置參數或
+// 子命令自己的旗標（如 members 的 --has-work、pulls 的 --mine／--reviewer／
+// --repo）——原樣依序交回，由子命令的 flagset 解析。因此
+//
+//	teai members --has-work --output table
+//	teai pulls --mine --repo alterminal/teai
+//	teai next --output table
+//
+// 都能正確分派（全域與命令旗標可交錯出現）。
+//
+// 停止條件：遇到 --（剝除它，其後全部交回，不再抽取）或
+// -h/--help/-v/--version（不是全域選項，交回 Run 的分派處理）。
+// 全域選項缺少值或值無效時回 ErrUsage。
+func extractGlobals(g *Globals, args []string) ([]string, error) {
+	rest := make([]string, 0, len(args))
+	i := 0
+	for i < len(args) {
+		arg := args[i]
+		if arg == "--" {
+			rest = append(rest, args[i+1:]...)
+			return rest, nil
+		}
+		if arg == "-" || !strings.HasPrefix(arg, "-") {
+			rest = append(rest, arg)
+			i++
+			continue
+		}
+		name, inline, hasInline := strings.Cut(arg, "=")
+		switch name {
+		case "-h", "--help", "-v", "--version":
+			rest = append(rest, args[i:]...)
+			return rest, nil
+		}
+		if _, ok := globalFlags[name]; !ok {
+			// 非全域選項：屬於子命令，原樣交回（順序保留）。
+			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(g, name, value); err != nil {
+			return nil, err
+		}
+		i++
+	}
+	return rest, nil
+}
+
+// applyGlobal 套用單一全域選項的值；值無效時回 ErrUsage。
+func applyGlobal(g *Globals, 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
+}
+
 // dispatch 執行已註冊的子命令，把錯誤轉成結束碼並輸出。
+// 全域選項已在 Run 的 extractGlobals 抽取完畢（允許出現在命令之後，
+// README 範例：teai next --output table）；這裡把剩餘引數直接交給
+// 命令的 flagset 解析。
 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 {
-		return int(ExitUsage)
-	}
-	if err := cmd.run(env, fs.Args()); err != nil {
+	if err := cmd.run(env, args); err != nil {
 		fmt.Fprintf(env.Err, "teai %s: %v\n", name, err)
-		return int(ExitInternal)
+		return int(exitCodeFor(err))
 	}
 	return int(ExitOK)
 }
 
+// exitCodeFor 把命令錯誤映射到結束碼：用法錯誤 → 2，API 錯誤 → 3，
+// 其他（內部）→ 1。
+func exitCodeFor(err error) ExitCode {
+	if err == nil {
+		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)
@@ -109,6 +299,6 @@ func printUsage(w io.Writer) {
 	for _, name := range names {
 		fmt.Fprintf(w, "  %-10s %s\n", name, commands[name].usage)
 	}
-	fmt.Fprintf(w, "\n說明：\n  -h, --help    顯示說明\n  -v, --version 顯示版本\n")
+	fmt.Fprintf(w, "\n說明：\n  -h, --help    顯示說明\n  -v, --version  顯示版本\n")
 	fmt.Fprintf(w, "\n更多資訊：https://gitea.alterminal.com/alterminal/teai\n")
 }

internal/cli/exitcode_test.go

@@ -0,0 +1,172 @@
+// 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) {
+	cases := []struct {
+		name string
+		err  error
+		want ExitCode
+	}{
+		{"usage error", &ErrUsage{Msg: "bad flag"}, ExitUsage},
+		{"api error 401", &gitea.ErrAPI{StatusCode: 401, Op: "GET /api/v1/user"}, ExitAPI},
+		{"api error transport", &gitea.ErrAPI{Op: "GET /api/v1/user", Err: errString("dial tcp")}, ExitAPI},
+		{"wrapped api error", wrapped(&gitea.ErrAPI{StatusCode: 500}), ExitAPI},
+		{"other error", errString("boom"), ExitInternal},
+		{"nil maps to OK", nil, ExitOK},
+	}
+	for _, tc := range cases {
+		if got := 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",
+	})
+	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"})
+	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)
+		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"})
+	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)
+	}
+}
+
+// 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} }

internal/cli/workflow_commands.go

@@ -0,0 +1,247 @@
+// 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})
+	register(&command{name: "pulls", usage: "跨倉庫 PR 跟進清單（--mine／--reviewer／--repo）", run: runPulls})
+	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 := fs.Parse(args); err != nil {
+		return &ErrUsage{Msg: err.Error()}
+	}
+	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 := fs.Parse(args); err != nil {
+		return &ErrUsage{Msg: err.Error()}
+	}
+	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
+}

internal/cli/workflow_commands_test.go

@@ -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)
+	}
+}

internal/gitea/auth.go

@@ -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)
+}

internal/gitea/auth_test.go

@@ -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)
+		}
+	})
+}

internal/gitea/client.go

@@ -0,0 +1,183 @@
+// 套件 gitea 提供存取 Gitea API 的 HTTP 用戶端基礎：
+// 認證、分頁、逾時與錯誤映射。
+//
+// 僅使用標準庫（net/http 等），離線可建置。token 由呼叫端注入，
+// 本套件不負責認證來源的解析（見 auth.go），也不會把 token 寫進
+// 任何輸出或錯誤訊息。
+package gitea
+
+import (
+	"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 {
+	u := *c.baseURL
+	u.Path += path
+	u.RawQuery = rawQuery
+	op := "GET " + u.Path
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
+	if err != nil {
+		return &ErrAPI{Op: op, Err: err}
+	}
+	req.Header.Set("Accept", "application/json")
+	if c.token != "" {
+		req.Header.Set("Authorization", "token "+c.token)
+	}
+	resp, err := c.hc.Do(req)
+	if err != nil {
+		return &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 &ErrAPI{Op: op, StatusCode: resp.StatusCode}
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return &ErrAPI{Op: op, Err: fmt.Errorf("decode response: %w", err)}
+	}
+	return 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
+		}
+	}
+}

internal/gitea/client_test.go

@@ -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
+}

internal/gitea/output.go

@@ -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
+}

internal/gitea/output_test.go

@@ -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")
+	}
+}

internal/workflow/giteaapi.go

@@ -0,0 +1,124 @@
+// 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
+}

internal/workflow/judge.go

@@ -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)
+}

internal/workflow/judge_test.go

@@ -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)
+	}
+}

internal/workflow/next.go

@@ -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(),
+	}
+}

internal/workflow/scan.go

@@ -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
+}

internal/workflow/scan_test.go

@@ -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)
+	}
+}

internal/workflow/types.go

@@ -0,0 +1,218 @@
+package workflow
+
+import (
+	"encoding/json"
+	"regexp"
+)
+
+// 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 {
+	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"`
+	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())
+}