Merge pull request '藍圖修訂：不再避開 tea 已有的功能（#3）' (#4) from docs/issue3-tea-parity into main

Reviewed-on: #4

README.md

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

cmd/xcheck/main.go

@@ -1,294 +0,0 @@
-// cmd/xcheck 是 #7 的交叉驗證工具（不屬於 teai 本體，PR 內附驗證說明）。
-//
-// 以真實 Gitea API 資料源實作 workflow.Source，跑 Go 版 ScanStalled，
-// 再與 gitea.py stalled（行為基準）的 JSON 輸出逐欄位比對。
-// 建立限制：與 teai 本體一致，僅標準庫。
-package main
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"strings"
-	"time"
-
-	"gitea.alterminal.com/alterminal/teai/internal/workflow"
-)
-
-// apiSource 以 Gitea API 實作 workflow.Source。
-type apiSource struct {
-	base  string
-	token string
-	hc    *http.Client
-}
-
-func (s *apiSource) get(path string, params map[string]string) ([]byte, int, error) {
-	u := s.base + path
-	if len(params) > 0 {
-		q := url.Values{}
-		for k, v := range params {
-			q.Set(k, v)
-		}
-		u += "?" + q.Encode()
-	}
-	req, err := http.NewRequest("GET", u, nil)
-	if err != nil {
-		return nil, 0, err
-	}
-	req.Header.Set("Accept", "application/json")
-	req.Header.Set("Authorization", "token "+s.token)
-	resp, err := s.hc.Do(req)
-	if err != nil {
-		return nil, 0, err
-	}
-	defer resp.Body.Close()
-	body, err := io.ReadAll(resp.Body)
-	return body, resp.StatusCode, err
-}
-
-func (s *apiSource) getJSON(path string, params map[string]string, out any) error {
-	body, code, err := s.get(path, params)
-	if err != nil {
-		return err
-	}
-	if code != 200 {
-		return fmt.Errorf("GET %s: HTTP %d", path, code)
-	}
-	return json.Unmarshal(body, out)
-}
-
-// listAll 分頁拉取清單類 API（Gitea 上限 50/頁）。
-func (s *apiSource) listAll(path string, params map[string]string, out any) error {
-	var items []json.RawMessage
-	page := 1
-	for {
-		q := map[string]string{"page": fmt.Sprint(page), "limit": "50"}
-		for k, v := range params {
-			q[k] = v
-		}
-		var chunk json.RawMessage
-		if err := s.getJSON(path, q, &chunk); err != nil {
-			return err
-		}
-		var arr []json.RawMessage
-		if err := json.Unmarshal(chunk, &arr); err != nil {
-			return fmt.Errorf("GET %s: 回傳非陣列", path)
-		}
-		items = append(items, arr...)
-		if len(arr) < 50 {
-			break
-		}
-		page++
-	}
-	var b strings.Builder
-	b.WriteByte('[')
-	for i, item := range items {
-		if i > 0 {
-			b.WriteByte(',')
-		}
-		b.Write(item)
-	}
-	b.WriteByte(']')
-	return json.Unmarshal([]byte(b.String()), out)
-}
-
-// CurrentUser 以 token 呼叫 /user 取實際帳號，與 gitea.py 的
-// get_current_username() 同源（token 決定帳號，不接受環境變數覆寫，
-// 失敗即報錯退出，不靜默退回預設值）。
-func (s *apiSource) CurrentUser() (string, error) {
-	var user struct {
-		Username string `json:"username"`
-		Login    string `json:"login"`
-	}
-	if err := s.getJSON("user", nil, &user); err != nil {
-		return "", err
-	}
-	if user.Username != "" {
-		return user.Username, nil
-	}
-	if user.Login != "" {
-		return user.Login, nil
-	}
-	return "", fmt.Errorf("無法從 Gitea API /user 取得目前帳號")
-}
-
-func (s *apiSource) MyOrganizations() ([]string, error) {
-	var orgs []struct {
-		Username string `json:"username"`
-	}
-	if err := s.listAll("user/orgs", nil, &orgs); err != nil {
-		return nil, err
-	}
-	names := make([]string, 0, len(orgs))
-	for _, o := range orgs {
-		if o.Username != "" {
-			names = append(names, o.Username)
-		}
-	}
-	return names, nil
-}
-
-func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repository, error) {
-	var repos []workflow.Repository
-	if err := s.listAll("orgs/"+org+"/repos", nil, &repos); err != nil {
-		return nil, err
-	}
-	return repos, nil
-}
-
-func (s *apiSource) OpenIssues(owner, repo string) ([]workflow.Issue, error) {
-	var issues []workflow.Issue
-	// 與 gitea.py 一致：type=issues 排除 PR；state=open。
-	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues", owner, repo), map[string]string{"type": "issues", "state": "open"}, &issues); err != nil {
-		return nil, err
-	}
-	return issues, nil
-}
-
-func (s *apiSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error) {
-	var pulls []workflow.PullRequest
-	if err := s.listAll(fmt.Sprintf("repos/%s/%s/pulls", owner, repo), map[string]string{"state": "open"}, &pulls); err != nil {
-		return nil, err
-	}
-	return pulls, nil
-}
-
-func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Comment, error) {
-	var comments []workflow.Comment
-	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/comments", owner, repo, number), nil, &comments); err != nil {
-		return nil, err
-	}
-	return comments, nil
-}
-
-func (s *apiSource) TryGetIssue(owner, repo string, number int) (workflow.Issue, bool, error) {
-	var issue workflow.Issue
-	body, code, err := s.get(fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, number), nil)
-	if err != nil {
-		return workflow.Issue{}, false, nil
-	}
-	if code != 200 {
-		return workflow.Issue{}, false, nil
-	}
-	if err := json.Unmarshal(body, &issue); err != nil {
-		return workflow.Issue{}, false, nil
-	}
-	return issue, true, nil
-}
-
-// loadEnv 讀 agents 倉庫的 .env（ACCESS_TOKEN、GITEA_API_DOMAIN）。
-func loadEnv(path string) {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return
-	}
-	for _, line := range strings.Split(string(data), "\n") {
-		line = strings.TrimSpace(line)
-		if line == "" || strings.HasPrefix(line, "#") {
-			continue
-		}
-		k, v, ok := strings.Cut(line, "=")
-		if !ok {
-			continue
-		}
-		k = strings.TrimSpace(k)
-		v = strings.Trim(strings.TrimSpace(v), "'\"")
-		if os.Getenv(k) == "" {
-			os.Setenv(k, v)
-		}
-	}
-}
-
-func main() {
-	// --xrefs 模式：從 stdin 讀文字，輸出解析後的引用目標（與 gitea.py
-	// _resolve_xref_targets 對照用）。組織與倉庫清單來自真實 API。
-	if len(os.Args) > 1 && os.Args[1] == "--xrefs" {
-		xrefsMain()
-		return
-	}
-	loadEnv(os.Getenv("HOME") + "/agents/.env")
-	domain := os.Getenv("GITEA_API_DOMAIN")
-	token := os.Getenv("ACCESS_TOKEN")
-	if domain == "" || token == "" {
-		fmt.Fprintln(os.Stderr, "缺少 GITEA_API_DOMAIN／ACCESS_TOKEN")
-		os.Exit(1)
-	}
-	src := &apiSource{
-		base:  "https://" + domain + "/api/v1/",
-		token: token,
-		hc:    &http.Client{Timeout: 30 * time.Second},
-	}
-	username, err := src.CurrentUser()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "CurrentUser:", err)
-		os.Exit(1)
-	}
-	hours := 4.0
-	items, scanErr := workflow.ScanStalled(src, username, hours, time.Now())
-	if scanErr != nil {
-		fmt.Fprintln(os.Stderr, "ScanStalled:", scanErr)
-		os.Exit(1)
-	}
-	// json.Marshal* 會把 <、>、& 轉義成 \u003c 等（含自訂 MarshalJSON 的輸出），
-	// 與 gitea.py（ensure_ascii=False）位元組不相容；必須停用 HTML 轉義。
-	var buf bytes.Buffer
-	enc := json.NewEncoder(&buf)
-	enc.SetEscapeHTML(false)
-	enc.SetIndent("", "  ")
-	if err := enc.Encode(items); err != nil {
-		fmt.Fprintln(os.Stderr, "Encode:", err)
-		os.Exit(1)
-	}
-	fmt.Print(buf.String())
-}
-
-// xrefsMain 對 stdin 的每行文字解析引用目標並輸出 JSON。
-func xrefsMain() {
-	loadEnv(os.Getenv("HOME") + "/agents/.env")
-	domain := os.Getenv("GITEA_API_DOMAIN")
-	token := os.Getenv("ACCESS_TOKEN")
-	if domain == "" || token == "" {
-		fmt.Fprintln(os.Stderr, "缺少 GITEA_API_DOMAIN／ACCESS_TOKEN")
-		os.Exit(1)
-	}
-	src := &apiSource{
-		base:  "https://" + domain + "/api/v1/",
-		token: token,
-		hc:    &http.Client{Timeout: 30 * time.Second},
-	}
-	orgs, err := src.MyOrganizations()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "MyOrganizations:", err)
-		os.Exit(1)
-	}
-	myOrgs := map[string]bool{}
-	for _, o := range orgs {
-		myOrgs[o] = true
-	}
-	data, _ := io.ReadAll(os.Stdin)
-	repos, _ := src.OrganizationRepositories("alterminal")
-	names := make([]string, 0, len(repos))
-	for _, r := range repos {
-		names = append(names, r.Name)
-	}
-	targets, err := workflow.ResolveXrefTargets("alterminal", "agents", []string{string(data)}, myOrgs, func(string) ([]string, error) {
-		return names, nil
-	})
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "ResolveXrefTargets:", err)
-		os.Exit(1)
-	}
-	var buf bytes.Buffer
-	enc := json.NewEncoder(&buf)
-	enc.SetEscapeHTML(false)
-	enc.SetIndent("", "  ")
-	if err := enc.Encode(targets); err != nil {
-		fmt.Fprintln(os.Stderr, "Encode:", err)
-		os.Exit(1)
-	}
-	fmt.Print(buf.String())
-}

internal/cli/cli.go

@@ -1,14 +1,25 @@
-// 套件 cli 提供 teai 的命令列架構：引數剖析、子命令分派與輸出。
+// 套件 cli 提供 teai 的命令列架構：全域選項剖析、子命令分派與輸出。
 //
 // 設計目標是讓之後新增子命令時只需註冊一個 command 結構，
 // 不需要改動分派邏輯；也讓核心功能可以被測試（Run 接受 io.Writer）。
+//
+// 結束碼（見 README「輸出與結束碼」）：
+//
+//	0 成功（含「沒有工作」→ null／[]）
+//	2 用法錯誤（未知命令／參數）
+//	3 API 錯誤（連線失敗、401、403、5xx）
 package cli
 
 import (
+	"errors"
 	"flag"
 	"fmt"
 	"io"
 	"sort"
+	"strings"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
 )
 
 // Version 是目前開發中的版本號。採用語意化版本；正式發佈前以 0 開頭。
@@ -17,13 +28,25 @@ var Version = "0.1.0-dev"
 // ExitCode 是 Run 回傳的行程結束碼。
 type ExitCode int
 
-// 常見的結束碼定義。0 表示成功，其餘對應常見的命令列錯誤情境。
+// 結束碼定義，對應 README「輸出與結束碼」表格。
 const (
-	ExitOK       ExitCode = iota // 成功
-	ExitUsage                    // 引數或子命令錯誤
-	ExitInternal                 // 內部錯誤（不該發生）
+	ExitOK    ExitCode = 0 // 成功
+	ExitUsage ExitCode = 2 // 用法錯誤（未知命令／參數）
+	ExitAPI   ExitCode = 3 // API 錯誤（連線失敗、401、403、5xx）
+
+	// ExitInternal 僅供「不該發生」的內部錯誤；不在 README 保證範圍。
+	ExitInternal ExitCode = 1
 )
 
+// ErrUsage 表示命令用法錯誤（缺參數、參數格式不對），對應 ExitUsage。
+type ErrUsage struct {
+	// Msg 是給使用者看的說明。
+	Msg string
+}
+
+// Error 實作 error 介面。
+func (e *ErrUsage) Error() string { return e.Msg }
+
 // command 定義一個子命令：名稱、一行說明與實作。
 type command struct {
 	name  string
@@ -31,12 +54,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,32 +98,120 @@ var commands = map[string]*command{
 
 // Run 剖析引數並分派到對應子命令，回傳行程結束碼。
 //
-// 無引數或要求說明（-h/--help）時印出用法；未知子命令回 ExitUsage。
+// 引數結構：teai [全域選項] <命令> [命令參數]。全域選項須在命令之前；
+// 無引數或要求說明（-h/--help）時印出用法；未知命令或無效選項回 ExitUsage。
 func Run(stdout, stderr io.Writer, args []string) int {
-	env := &Env{Out: stdout, Err: stderr}
+	env := &Env{Out: stdout, Err: stderr, Globals: defaultGlobals()}
 
 	if len(args) == 0 {
 		printUsage(env.Out)
 		return int(ExitOK)
 	}
 
-	switch args[0] {
+	rest, err := parseGlobals(&env.Globals, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "teai: %v\n\n", err)
+		printUsage(stderr)
+		return int(ExitUsage)
+	}
+	if len(rest) == 0 {
+		printUsage(env.Out)
+		return int(ExitOK)
+	}
+
+	switch rest[0] {
 	case "-h", "--help", "help":
 		printUsage(env.Out)
 		return int(ExitOK)
 	case "-v", "--version", "version":
-		return dispatch(env, "version", args[1:])
+		return dispatch(env, "version", rest[1:])
 	default:
-		name := args[0]
+		name := rest[0]
 		if _, ok := commands[name]; !ok {
 			fmt.Fprintf(stderr, "teai: unknown command %q\n\n", name)
 			printUsage(stderr)
 			return int(ExitUsage)
 		}
-		return dispatch(env, name, args[1:])
+		return dispatch(env, name, rest[1:])
 	}
 }
 
+// globalFlags 列出全域選項的長名稱與是否需要值。
+var globalFlags = map[string]bool{
+	"--url":     true,
+	"--token":   true,
+	"--config":  true,
+	"--output":  true,
+	"--timeout": true,
+}
+
+// parseGlobals 從 args 前端取走全域選項，回傳剩餘引數（命令與其參數）。
+// 遇到第一個非選項引數即停；不認得的選項或缺少值都回 ErrUsage。
+func parseGlobals(g *Globals, args []string) ([]string, error) {
+	i := 0
+	for i < len(args) {
+		arg := args[i]
+		if arg == "--" {
+			return args[i+1:], nil
+		}
+		if !strings.HasPrefix(arg, "-") || arg == "-" {
+			return args[i:], nil
+		}
+		name, inline, hasInline := strings.Cut(arg, "=")
+		// -h/--help/-v/--version 不是全域選項；交回 Run 的分派處理。
+		switch name {
+		case "-h", "--help", "-v", "--version":
+			return args[i:], nil
+		}
+		need, ok := globalFlags[name]
+		if !ok {
+			return nil, &ErrUsage{Msg: fmt.Sprintf("unknown global option %q", name)}
+		}
+		var value string
+		if hasInline {
+			value = inline
+		} else {
+			if !need {
+				// 目前所有全域選項都需要值；保留機制給未來的布林選項。
+				value = ""
+			}
+			if i+1 >= len(args) {
+				return nil, &ErrUsage{Msg: fmt.Sprintf("global option %q requires a value", name)}
+			}
+			i++
+			value = args[i]
+		}
+		switch name {
+		case "--url":
+			if strings.TrimSpace(value) == "" {
+				return nil, &ErrUsage{Msg: "--url must not be empty"}
+			}
+			g.URL = value
+		case "--token":
+			g.Token = value
+		case "--config":
+			if strings.TrimSpace(value) == "" {
+				return nil, &ErrUsage{Msg: "--config must not be empty"}
+			}
+			g.ConfigPath = value
+		case "--output":
+			f, err := gitea.ParseFormat(value)
+			if err != nil {
+				return nil, &ErrUsage{Msg: err.Error()}
+			}
+			g.Output = f
+		case "--timeout":
+			d, err := time.ParseDuration(value)
+			if err != nil || d <= 0 {
+				return nil, &ErrUsage{Msg: fmt.Sprintf("invalid --timeout %q (want e.g. 30s)", value)}
+			}
+			g.Timeout = d
+		}
+		i++
+	}
+	return nil, nil
+}
+
 // dispatch 執行已註冊的子命令，把錯誤轉成結束碼並輸出。
 func dispatch(env *Env, name string, args []string) int {
 	cmd := commands[name]
@@ -86,21 +222,45 @@ func dispatch(env *Env, name string, args []string) int {
 	}
 	if err := cmd.run(env, fs.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 {
 	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 +269,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,123 @@
+// 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 TestParseGlobals(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := parseGlobals(&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 TestParseGlobalsStopsAtCommand(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := parseGlobals(&g, []string{"version", "--output", "table"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 命令之後的選項屬於命令，不屬於全域。
+	if len(rest) != 3 || rest[0] != "version" {
+		t.Fatalf("rest = %v", rest)
+	}
+}
+
+// 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/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/workflow.go

@@ -1,626 +0,0 @@
-// 套件 workflow 實作 gitea.py 工作流的核心判定邏輯（teai issue #7）。
-//
-// 行為基準是 alterminal/agents 的 scripts/lib/gitea.py：xref 解析
-// （#N、repo#N、owner/repo#N）與 stalled 停滯掃描（reason 分類、催促冷卻、
-// 父追蹤項把子項活動計入 last_activity）。判定規則以 AGENTS.md 為準，
-// 本套件只實作、不改義。
-//
-// 資料以 Source 介面注入：CLI 層負責拉取 API，測試用假資料源，
-// 邏輯本身離線可測（README 設計原則 4：可直接替換原型、交叉驗證）。
-package workflow
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"regexp"
-	"sort"
-	"strconv"
-	"strings"
-	"time"
-	"unicode"
-	"unicode/utf8"
-)
-
-// 常數與 gitea.py 保持一致（STALLED_DEFAULT_HOURS、NUDGE_COOLDOWN_HOURS）。
-const (
-	// StalledDefaultHours 是 stalled 掃描的預設門檻（小時）。
-	StalledDefaultHours = 4.0
-	// NudgeCooldownHours 是「最後留言出自目前帳號」項目的催促冷卻（小時）。
-	NudgeCooldownHours = 24.0
-)
-
-// xrefPattern 對應 gitea.py 的 XREF_PATTERN：#N、repo#N、owner/repo#N。
-//
-// 前面不得是文數字／底線／斜線（避免切進 alterminal/bear#47 的後半段）；
-// owner/repo 兩段之間必須有斜線（避免把 bear-cli#10 誤判成 cli#10）。
-// Go 的 regexp 不支援 lookbehind，改在掃描時檢查前一字元。
-var xrefPattern = regexp.MustCompile(`([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?)?#(\d+)`)
-
-// User 是 Gitea user 物件的精簡投影。
-type User struct {
-	Username string `json:"username"`
-}
-
-// Comment 是 issue／PR 留言的精簡投影。
-type Comment struct {
-	User      User      `json:"user"`
-	Body      string    `json:"body"`
-	CreatedAt time.Time `json:"created_at"`
-}
-
-// Author 回傳留言作者帳號；空字串表示無法判定。
-func (c Comment) Author() string { return c.User.Username }
-
-// Issue 是 issue 的精簡投影（Gitea /repos/{owner}/{repo}/issues，不含 PR）。
-type Issue struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Body      string     `json:"body"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL        string    `json:"html_url"`
-	Assignees  []User    `json:"assignees"`
-	Repository Reference `json:"repository"`
-	// PullRequest 非 nil 表示這其實是 PR（Gitea 的 /issues API 兩者都回）。
-	PullRequest any `json:"pull_request,omitempty"`
-}
-
-// Reference 是 repository 物件的精簡投影（issue 物件帶 full_name）。
-type Reference struct {
-	FullName string `json:"full_name"`
-}
-
-// Ref 是 PR base/head 的精簡投影（PR 物件沒有 repository 欄位，改讀 base/head.repo）。
-type Ref struct {
-	Repo Reference `json:"repo"`
-}
-
-// PullRequest 是 /repos/{owner}/{repo}/pulls 物件的精簡投影。
-type PullRequest struct {
-	Number    int        `json:"number"`
-	Title     string     `json:"title"`
-	State     string     `json:"state"`
-	Author    User       `json:"user"`
-	CreatedAt time.Time  `json:"created_at"`
-	UpdatedAt time.Time  `json:"updated_at"`
-	ClosedAt  *time.Time `json:"closed_at,omitempty"`
-	// URL 對應 API 的 html_url。
-	URL                string `json:"html_url"`
-	Base               Ref    `json:"base"`
-	Head               Ref    `json:"head"`
-	RequestedReviewers []User `json:"requested_reviewers"`
-}
-
-// FullName 回傳 "owner/repo"；PR 沒有 repository 欄位，改讀 base（再退 head）。
-func (p PullRequest) FullName() string {
-	if p.Base.Repo.FullName != "" {
-		return p.Base.Repo.FullName
-	}
-	return p.Head.Repo.FullName
-}
-
-// Repository 是 /orgs/{org}/repos 物件的精簡投影。
-type Repository struct {
-	Name            string `json:"name"`
-	Empty           bool   `json:"empty"`
-	HasPullRequests *bool  `json:"has_pull_requests"`
-}
-
-// Item 是 stalled 掃描的單筆輸出（欄位對應 gitea.py 的 find_stalled_work）。
-type Item struct {
-	Type           string
-	Repo           string
-	Number         int
-	Title          string
-	URL            string
-	Assignees      []string
-	Author         string
-	Reviewers      []string
-	LastCommentBy  string
-	LastActivityAt time.Time
-	StalledHours   float64
-	Reason         string
-	ChildActivity  []Child
-}
-
-// MarshalJSON 輸出鍵集與鍵序與 gitea.py 完全一致的物件：
-// issue 帶 assignees；pull 帶 author 與 reviewers；
-// child_activity 僅在有子項摘要時輸出。
-func (i Item) MarshalJSON() ([]byte, error) {
-	var b strings.Builder
-	b.WriteString(`{"type":`)
-	writeJSON(&b, i.Type)
-	b.WriteString(`,"repo":`)
-	writeJSON(&b, i.Repo)
-	b.WriteString(`,"number":`)
-	fmt.Fprintf(&b, "%d", i.Number)
-	b.WriteString(`,"title":`)
-	writeJSON(&b, i.Title)
-	b.WriteString(`,"url":`)
-	writeJSON(&b, i.URL)
-	if i.Type == "pull" {
-		b.WriteString(`,"author":`)
-		writeJSON(&b, i.Author)
-		b.WriteString(`,"reviewers":`)
-		writeJSON(&b, i.Reviewers)
-	} else {
-		b.WriteString(`,"assignees":`)
-		writeJSON(&b, i.Assignees)
-	}
-	b.WriteString(`,"last_comment_by":`)
-	writeJSON(&b, i.LastCommentBy)
-	b.WriteString(`,"last_activity_at":`)
-	writeJSON(&b, FormatMoment(i.LastActivityAt))
-	b.WriteString(`,"stalled_hours":`)
-	// Python round(x, 1) 的 json 輸出是 48.0／10.4（repr 帶 .0）；
-	// %g 會輸出 48，極大值還會變 1e+06，改定點一位小數。
-	b.WriteString(strconv.FormatFloat(i.StalledHours, 'f', 1, 64))
-	b.WriteString(`,"reason":`)
-	writeJSON(&b, i.Reason)
-	if len(i.ChildActivity) > 0 {
-		b.WriteString(`,"child_activity":`)
-		writeJSON(&b, i.ChildActivity)
-	}
-	b.WriteString(`}`)
-	return []byte(b.String()), nil
-}
-
-// FormatMoment 輸出與 Python datetime.isoformat() 一致的時刻字串
-// （UTC 以 +00:00 表示，不用 Z；秒以下省略）。
-func FormatMoment(t time.Time) string {
-	if t.Nanosecond() != 0 {
-		return t.Format("2006-01-02T15:04:05.999999999-07:00")
-	}
-	return t.Format("2006-01-02T15:04:05-07:00")
-}
-
-// writeJSON 以停用 HTML 轉義的編碼器輸出：Python json.dumps（ensure_ascii=False）
-// 不會把 <、>、& 轉成 \u003c 等逸出，json.Marshal 預設會，造成位元組不相容。
-// Encoder 會在結尾補換行， trim 掉。
-func writeJSON(b *strings.Builder, v any) {
-	var buf bytes.Buffer
-	enc := json.NewEncoder(&buf)
-	enc.SetEscapeHTML(false)
-	if err := enc.Encode(v); err != nil {
-		return
-	}
-	b.Write(bytes.TrimSuffix(buf.Bytes(), []byte{'\n'}))
-}
-
-// Child 是父追蹤項的子項活動摘要。
-type Child struct {
-	Repo   string `json:"repo"`
-	Number int    `json:"number"`
-	Title  string `json:"title"`
-	State  string `json:"state"`
-	// LastActivityAt 用指標：子項無可解析時刻時 Python 輸出 null（不是 ""）。
-	LastActivityAt *string `json:"last_activity_at"`
-}
-
-// XrefTarget 是解析後的引用目標（owner、repo、number）。
-type XrefTarget struct {
-	Owner  string
-	Repo   string
-	Number int
-}
-
-// Source 是 stalled 掃描需要的資料源（CLI 層以 API 實作；測試注入假資料）。
-type Source interface {
-	// MyOrganizations 回傳目前帳號所屬組織清單。
-	MyOrganizations() ([]string, error)
-	// OrganizationRepositories 回傳組織的倉庫清單。
-	OrganizationRepositories(org string) ([]Repository, error)
-	// OpenIssues 回傳倉庫的 open issues（Gitea 會混入 PR，由掃描端過濾）。
-	OpenIssues(owner, repo string) ([]Issue, error)
-	// OpenPulls 回傳倉庫的 open pull requests。
-	OpenPulls(owner, repo string) ([]PullRequest, error)
-	// IssueComments 回傳 issue／PR 的留言。
-	IssueComments(owner, repo string, number int) ([]Comment, error)
-	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
-	TryGetIssue(owner, repo string, number int) (Issue, bool, error)
-}
-
-// iterXrefs 產出文字中的 (prefix, number) 配對（對應 _iter_issue_xrefs）。
-//
-// Python 原版以 lookbehind (?<![\w/#]) 在匹配起點檢查前一「字元」，
-// 且 \w 採 Unicode（中日韓、全形數字都算）。Go regexp 不支援 lookbehind，
-// 改為掃描時檢查起點前一 rune：是文數字（Unicode）／底線／斜線／# 者略過，
-// 並從起點的下一個 rune 重試——與 Python finditer 的逐位置語義一致，
-// 否則「修復bear-cli#9」這種寫法會整段被丟棄（Python 只匹配後半 cli#9）。
-func iterXrefs(text string) [][2]string {
-	var out [][2]string
-	pos := 0
-	for pos <= len(text) {
-		m := xrefPattern.FindStringIndex(text[pos:])
-		if m == nil {
-			break
-		}
-		start, end := pos+m[0], pos+m[1]
-		if start > 0 {
-			prev, _ := utf8.DecodeLastRuneInString(text[:start])
-			if isWordChar(prev) || prev == '/' || prev == '#' {
-				_, size := utf8.DecodeRuneInString(text[start:])
-				pos = start + size
-				continue
-			}
-		}
-		match := text[start:end]
-		i := strings.IndexByte(match, '#')
-		prefix := match[:i]
-		number := match[i+1:]
-		out = append(out, [2]string{prefix, number})
-		pos = end
-	}
-	return out
-}
-
-// isWordChar 對應 Python \w（Unicode）：字母／數字／底線。
-// 前一版只認 ASCII，中文緊鄰 #N 時（「修復#12」）與 Python 行為分歧。
-func isWordChar(r rune) bool {
-	return r == '_' || unicode.IsLetter(r) || unicode.IsDigit(r)
-}
-
-// ResolveXrefTargets 把內文／留言中的引用解析成目標清單（對應 _resolve_xref_targets）。
-//
-// 單段 #N 指向父項所在倉庫；單段 repo#N 需 repo 存在於父項所屬組織
-// （「PR#50」這類寫法因 repo 不存在而自動略過）；owner/repo#N 需 owner
-// 為目前帳號所屬組織（跨倉庫子項，如 bear-cli#9 → bear#35 的同組織判定）。
-// 去重、保留出現順序。
-func ResolveXrefTargets(org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(org string) ([]string, error)) ([]XrefTarget, error) {
-	var resolved []XrefTarget
-	seen := map[XrefTarget]bool{}
-	var orgRepoSet map[string]bool
-	for _, text := range texts {
-		for _, pair := range iterXrefs(text) {
-			prefix, numberStr := pair[0], pair[1]
-			var number int
-			if _, err := fmt.Sscanf(numberStr, "%d", &number); err != nil || number <= 0 {
-				continue
-			}
-			var target XrefTarget
-			switch {
-			case strings.Contains(prefix, "/"):
-				parts := strings.SplitN(prefix, "/", 2)
-				owner, name := parts[0], parts[1]
-				if owner != "" && name != "" && myOrgs[owner] {
-					target = XrefTarget{owner, name, number}
-				}
-			case prefix != "":
-				if orgRepoSet == nil {
-					names, err := orgRepos(org)
-					if err != nil {
-						return nil, err
-					}
-					orgRepoSet = map[string]bool{}
-					for _, n := range names {
-						orgRepoSet[n] = true
-					}
-				}
-				if orgRepoSet[prefix] {
-					target = XrefTarget{org, prefix, number}
-				}
-			default:
-				target = XrefTarget{org, repo, number}
-			}
-			if target != (XrefTarget{}) && !seen[target] {
-				seen[target] = true
-				resolved = append(resolved, target)
-			}
-		}
-	}
-	return resolved, nil
-}
-
-// childActivity 計算父追蹤項的子項活動（對應 _child_activity）。
-//
-// 只採計向下引用：子項建立時間需晚於父項（父項內文回指更早的規劃 issue
-// 是上行引用，不採計）。資料源失敗（含編號不存在）靜默略過，不影響掃描。
-func childActivity(src Source, org, repo string, parent Issue, comments []Comment, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (moments []time.Time, children []Child) {
-	texts := []string{parent.Body}
-	for _, c := range comments {
-		texts = append(texts, c.Body)
-	}
-	targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
-	if err != nil {
-		return nil, nil
-	}
-	for _, t := range targets {
-		child, ok, gerr := src.TryGetIssue(t.Owner, t.Repo, t.Number)
-		if gerr != nil || !ok {
-			continue
-		}
-		if t.Owner == org && t.Repo == repo && child.Number == parent.Number {
-			continue // 自我引用
-		}
-		if !parent.CreatedAt.IsZero() && !child.CreatedAt.IsZero() && !child.CreatedAt.After(parent.CreatedAt) {
-			continue // 上行引用（父項回指更早或同時的 issue）；時間未知則不排除
-		}
-		var ms []time.Time
-		if !child.UpdatedAt.IsZero() {
-			ms = append(ms, child.UpdatedAt)
-		}
-		if child.ClosedAt != nil && !child.ClosedAt.IsZero() {
-			ms = append(ms, *child.ClosedAt)
-		}
-		if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
-			for _, c := range cs {
-				if !c.CreatedAt.IsZero() {
-					ms = append(ms, c.CreatedAt)
-				}
-			}
-		}
-		var last *string
-		if len(ms) > 0 {
-			latest := maxTime(ms)
-			moments = append(moments, latest)
-			// 與 Item 相同用 FormatMoment（Python isoformat：UTC 記 +00:00）；
-			// RFC3339 對 UTC 會輸出 Z，與基準不相容。
-			s := FormatMoment(latest)
-			last = &s
-		}
-		children = append(children, Child{
-			Repo:           t.Owner + "/" + t.Repo,
-			Number:         child.Number,
-			Title:          child.Title,
-			State:          child.State,
-			LastActivityAt: last,
-		})
-	}
-	return moments, children
-}
-
-func maxTime(ts []time.Time) time.Time {
-	best := ts[0]
-	for _, t := range ts[1:] {
-		if t.After(best) {
-			best = t
-		}
-	}
-	return best
-}
-
-func usernames(users []User) []string {
-	var out []string
-	seen := map[string]bool{}
-	for _, u := range users {
-		if u.Username == "" || seen[u.Username] {
-			continue
-		}
-		seen[u.Username] = true
-		out = append(out, u.Username)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// ScanStalled 掃描跨組織的停滯 open issues／PR（對應 find_stalled_work）。
-//
-// 判定：最後活動（留言時間與本身 updated_at 取較晚者，父追蹤項再加計
-// 子項活動）距今超過 threshold 小時。刻意包含拾取死角形態：最後一則留言
-// 出自 assignee／PR 作者本人且超過時限——工作休眠、無人催促。最後留言
-// 出自目前帳號（username）的項目在冷卻期間不列入（已催促過）；冷卻後
-// 仍停滯會再出現。輸出依停滯時間由長到短排序。
-func ScanStalled(src Source, username string, threshold float64, now time.Time) ([]Item, error) {
-	orgs, err := src.MyOrganizations()
-	if err != nil {
-		return nil, err
-	}
-	myOrgs := make(map[string]bool, len(orgs))
-	for _, o := range orgs {
-		myOrgs[o] = true
-	}
-	orgRepos := func(org string) ([]string, error) {
-		repos, err := src.OrganizationRepositories(org)
-		if err != nil {
-			return nil, err
-		}
-		names := make([]string, 0, len(repos))
-		for _, r := range repos {
-			if r.Name != "" {
-				names = append(names, r.Name)
-			}
-		}
-		return names, nil
-	}
-	var items []Item
-	for _, org := range orgs {
-		repos, err := src.OrganizationRepositories(org)
-		if err != nil {
-			continue
-		}
-		for _, r := range repos {
-			if r.Name == "" || r.Empty {
-				continue
-			}
-			// 停用 PR 的倉庫沒有 PR 可掃；issues 照常（gitea.py _iter_open_issues 不檢查此欄位）。
-			scanPulls := r.HasPullRequests == nil || *r.HasPullRequests
-			issues, err := src.OpenIssues(org, r.Name)
-			if err != nil {
-				continue
-			}
-			for _, issue := range issues {
-				if issue.PullRequest != nil {
-					continue
-				}
-				comments, err := src.IssueComments(org, r.Name, issue.Number)
-				if err != nil {
-					continue
-				}
-				item, ok := considerIssue(src, org, r.Name, issue, comments, username, threshold, now, myOrgs, orgRepos)
-				if ok {
-					items = append(items, item)
-				}
-			}
-			if !scanPulls {
-				continue
-			}
-			pulls, err := src.OpenPulls(org, r.Name)
-			if err != nil {
-				continue
-			}
-			for _, pr := range pulls {
-				comments, err := src.IssueComments(org, r.Name, pr.Number)
-				if err != nil {
-					continue
-				}
-				if item, ok := considerPull(pr, comments, username, threshold, now); ok {
-					items = append(items, item)
-				}
-			}
-		}
-	}
-	sort.SliceStable(items, func(i, j int) bool {
-		return items[i].StalledHours > items[j].StalledHours
-	})
-	return items, nil
-}
-
-// considerIssue 對單一 issue 套用停滯判定（對應 _consider 的 issue 分支）。
-func considerIssue(src Source, org, repo string, issue Issue, comments []Comment, username string, threshold float64, now time.Time, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (Item, bool) {
-	childMoments, children := childActivity(src, org, repo, issue, comments, myOrgs, orgRepos)
-	assignees := usernames(issue.Assignees)
-	moments := []time.Time{issue.UpdatedAt, issue.CreatedAt}
-	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
-			moments = append(moments, c.CreatedAt)
-		}
-	}
-	moments = append(moments, childMoments...)
-	moments = nonZero(moments)
-	if len(moments) == 0 {
-		return Item{}, false
-	}
-	lastActivity := maxTime(moments)
-	stalled := now.Sub(lastActivity).Hours()
-	if stalled < threshold {
-		return Item{}, false
-	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
-		return Item{}, false
-	}
-	reason := "waiting-outside"
-	switch {
-	case len(assignees) == 0:
-		reason = "no-assignee"
-	case lastCommentBy != "" && containsStr(assignees, lastCommentBy):
-		reason = "assignee-idle"
-	case lastCommentBy == "":
-		reason = "no-commenter"
-	}
-	if len(children) > 0 && anyOpen(children) {
-		reason = "parent-tracking"
-	}
-	item := Item{
-		Type: "issue", Repo: issue.Repository.FullName, Number: issue.Number,
-		Title: issue.Title, URL: issue.URL,
-		Assignees:     assignees,
-		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
-		StalledHours: round1(stalled), Reason: reason,
-	}
-	if len(children) > 0 {
-		item.ChildActivity = children
-	}
-	return item, true
-}
-
-// considerPull 對單一 PR 套用停滯判定（對應 _consider 的 pull 分支）。
-func considerPull(pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
-	reviewers := usernames(pr.RequestedReviewers)
-	author := pr.Author.Username
-	moments := []time.Time{pr.UpdatedAt, pr.CreatedAt}
-	for _, c := range comments {
-		if !c.CreatedAt.IsZero() {
-			moments = append(moments, c.CreatedAt)
-		}
-	}
-	moments = nonZero(moments)
-	if len(moments) == 0 {
-		return Item{}, false
-	}
-	lastActivity := maxTime(moments)
-	stalled := now.Sub(lastActivity).Hours()
-	if stalled < threshold {
-		return Item{}, false
-	}
-	lastCommentAt, lastCommentBy := lastComment(comments)
-	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
-		return Item{}, false
-	}
-	reason := "no-commenter"
-	switch {
-	case len(reviewers) == 0:
-		reason = "no-reviewer"
-	case lastCommentBy == author:
-		reason = "author-idle"
-	case lastCommentBy != "" && containsStr(reviewers, lastCommentBy):
-		reason = "reviewer-idle"
-	}
-	item := Item{
-		Type: "pull", Repo: pr.FullName(), Number: pr.Number,
-		Title: pr.Title, URL: pr.URL,
-		Author: author, Reviewers: reviewers,
-		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
-		StalledHours: round1(stalled), Reason: reason,
-	}
-	return item, true
-}
-
-// lastComment 回傳最後一則留言（created_at 最新者）的時間與作者。
-func lastComment(comments []Comment) (time.Time, string) {
-	var best time.Time
-	by := ""
-	for _, c := range comments {
-		if c.CreatedAt.After(best) {
-			best = c.CreatedAt
-			by = c.Author()
-		}
-	}
-	return best, by
-}
-
-func anyOpen(children []Child) bool {
-	for _, c := range children {
-		if c.State == "open" {
-			return true
-		}
-	}
-	return false
-}
-
-func containsStr(list []string, s string) bool {
-	for _, x := range list {
-		if x == s {
-			return true
-		}
-	}
-	return false
-}
-
-func nonZero(ts []time.Time) []time.Time {
-	out := make([]time.Time, 0, len(ts))
-	for _, t := range ts {
-		if !t.IsZero() {
-			out = append(out, t)
-		}
-	}
-	return out
-}
-
-// round1 舍入到小數一位（對應 Python round(x, 1)）。
-// 經 strconv 的十進位正確舍入（半偶數），與 Python 的浮點 round 行為一致，
-// 避免 (x*10+0.5) 截斷在 .x5 邊界產生偏差。
-func round1(v float64) float64 {
-	r, err := strconv.ParseFloat(strconv.FormatFloat(v, 'f', 1, 64), 64)
-	if err != nil {
-		return v
-	}
-	return r
-}

internal/workflow/workflow_test.go

@@ -1,532 +0,0 @@
-// workflow 套件的單元測試（teai issue #7 驗收：xref 邊界案例與 stalled 判定）。
-//
-// fakeSource 以假資料實作 Source 介面，邏輯離線可測；
-// 語義對照組是 alterminal/agents scripts/lib/gitea.py。
-package workflow
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-)
-
-func at(minutes int) time.Time {
-	return time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC).Add(time.Duration(minutes) * time.Minute)
-}
-
-// fakeSource 是注入假資料的 Source。
-type fakeSource struct {
-	orgs  []string
-	repos map[string][]Repository
-	// issues[owner/repo][number]
-	issues map[string]map[int]Issue
-	// pulls[owner/repo]
-	pulls map[string][]PullRequest
-	// comments[owner/repo/number]
-	comments map[string][]Comment
-}
-
-func (f *fakeSource) MyOrganizations() ([]string, error) { return f.orgs, nil }
-
-func (f *fakeSource) OrganizationRepositories(org string) ([]Repository, error) {
-	return f.repos[org], nil
-}
-
-func (f *fakeSource) OpenIssues(owner, repo string) ([]Issue, error) {
-	var out []Issue
-	for _, i := range f.issues[owner+"/"+repo] {
-		out = append(out, i)
-	}
-	return out, nil
-}
-
-func (f *fakeSource) OpenPulls(owner, repo string) ([]PullRequest, error) {
-	return f.pulls[owner+"/"+repo], nil
-}
-
-func (f *fakeSource) IssueComments(owner, repo string, number int) ([]Comment, error) {
-	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
-}
-
-func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, error) {
-	i, ok := f.issues[owner+"/"+repo][number]
-	if !ok {
-		return Issue{}, false, nil
-	}
-	return i, true, nil
-}
-
-func repoWith(name string, hasPR bool) []Repository {
-	h := hasPR
-	return []Repository{{Name: name, HasPullRequests: &h}}
-}
-
-func mustResolve(t *testing.T, org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) []XrefTarget {
-	t.Helper()
-	targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
-	if err != nil {
-		t.Fatalf("ResolveXrefTargets: %v", err)
-	}
-	return targets
-}
-
-// TestIterXrefsEdges 驗證 regex 邊界：lookbehind 等價實作與兩段式斜線限制。
-func TestIterXrefsEdges(t *testing.T) {
-	cases := []struct {
-		name string
-		text string
-		want [][2]string
-	}{
-		{"單段 #N", "父項：#3。", [][2]string{{"3"}, {"", "3"}}[1:]},
-		{"單段 repo#N 存在", "見 agents#10", [][2]string{{"agents", "10"}}},
-		{"PR#50 寫法不是 repo", "PR#50 與 issue#49", [][2]string{{"PR", "50"}, {"issue", "49"}}},
-		{"owner/repo#N", "alterminal/agents#32", [][2]string{{"alterminal/agents", "32"}}},
-		{"斜線後不切半段", "alterminal/bear#47 只應匹配整段", [][2]string{{"alterminal/bear", "47"}}},
-		{"連字號 repo 名", "bear-cli#9", [][2]string{{"bear-cli", "9"}}},
-		{"路徑後的 #N 不匹配", "see https://x/a/#frag not #5", [][2]string{{"", "5"}}},
-		// Python \w 是 Unicode：CJK 緊鄰 #N 時整體視為 \w，lookbehind 擋下。
-		{"CJK 緊鄰 #N 略過", "修復#12的問題，見 #5", [][2]string{{"", "5"}}},
-		{"CJK 緊鄰 repo#N 整段略過", "修復agents#12", nil},
-		{"CJK 緊鄰連字號 repo 匹配後半", "修復bear-cli#9 見 #5", [][2]string{{"cli", "9"}, {"", "5"}}},
-		{"連續井號", "##5", nil},
-		{"全形數字後 #N", "１２#5", nil},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			got := iterXrefs(tc.text)
-			if len(got) != len(tc.want) {
-				t.Fatalf("iterXrefs(%q) = %v, want %v", tc.text, got, tc.want)
-			}
-			for i := range got {
-				if got[i] != tc.want[i] {
-					t.Fatalf("iterXrefs(%q)[%d] = %v, want %v", tc.text, i, got[i], tc.want[i])
-				}
-			}
-		})
-	}
-}
-
-// TestResolveXrefTargets 驗證三種形態的解析與單段 repo 的存在性邊界（#7 驗收）。
-func TestResolveXrefTargets(t *testing.T) {
-	myOrgs := map[string]bool{"alterminal": true}
-	orgRepos := func(string) ([]string, error) { return []string{"agents", "teai", "bear-cli"}, nil }
-	texts := []string{"父項：#3，子項 teai#7，跨倉 alterminal/bear#35，不存在 nope#9，PR#50"}
-
-	got := mustResolve(t, "alterminal", "agents", texts, myOrgs, orgRepos)
-	want := []XrefTarget{
-		{Owner: "alterminal", Repo: "agents", Number: 3},
-		{Owner: "alterminal", Repo: "teai", Number: 7},
-		{Owner: "alterminal", Repo: "bear", Number: 35},
-	}
-	if len(got) != len(want) {
-		t.Fatalf("got %v, want %v", got, want)
-	}
-	for i := range want {
-		if got[i] != want[i] {
-			t.Fatalf("got[%d] %v, want %v", i, got[i], want[i])
-		}
-	}
-}
-
-// TestResolveXrefTargetsOwnerNotMyOrg owner/repo#N 的 owner 非所屬組織 → 不解析。
-func TestResolveXrefTargetsOwnerNotMyOrg(t *testing.T) {
-	myOrgs := map[string]bool{"alterminal": true}
-	orgRepos := func(string) ([]string, error) { return nil, nil }
-	got := mustResolve(t, "alterminal", "agents", []string{"other/repo#1"}, myOrgs, orgRepos)
-	if len(got) != 0 {
-		t.Fatalf("owner 非所屬組織應略過，got %v", got)
-	}
-}
-
-// TestResolveXrefTargetsDedup 同一目標重複出現只保留第一個。
-func TestResolveXrefTargetsDedup(t *testing.T) {
-	myOrgs := map[string]bool{"alterminal": true}
-	orgRepos := func(string) ([]string, error) { return []string{"teai"}, nil }
-	got := mustResolve(t, "alterminal", "agents", []string{"#7 又 teai#7"}, myOrgs, orgRepos)
-	if len(got) != 2 {
-		t.Fatalf("應兩筆（#7 同倉庫、teai#7 跨倉庫），got %v", got)
-	}
-}
-
-// TestScanStalledIssueReasons 驗證 issue 的 reason 分類與排序。
-func TestScanStalledIssueReasons(t *testing.T) {
-	now := at(0)
-	src := &fakeSource{
-		orgs: []string{"alterminal"},
-		repos: map[string][]Repository{
-			"alterminal": repoWith("agents", true),
-		},
-		issues: map[string]map[int]Issue{
-			"alterminal/agents": {
-				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/agents"}, URL: "u1"},
-				2: {Number: 2, Title: "分派者自己最後留言", State: "open", Author: User{"ceo"}, CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u2"},
-				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u3"},
-				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u4"},
-				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: at(-30), UpdatedAt: at(-30), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u5"},
-			},
-		},
-		comments: map[string][]Comment{
-			"alterminal/agents/2": {{User: User{"ceo"}, CreatedAt: at(-300)}},
-			"alterminal/agents/4": {{User: User{"dan"}, CreatedAt: at(-300)}},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	// 1: no-assignee（10h）、2: assignee-idle（5h）、3: no-commenter（5h）、4: waiting-outside（5h）、5: 不列入
-	if len(got) != 4 {
-		t.Fatalf("應 4 筆，got %d：%v", len(got), got)
-	}
-	byNumber := map[int]Item{}
-	for _, it := range got {
-		byNumber[it.Number] = it
-	}
-	for n, wantReason := range map[int]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
-		if byNumber[n].Reason != wantReason {
-			t.Errorf("issue %d reason = %q, want %q", n, byNumber[n].Reason, wantReason)
-		}
-	}
-	if got[0].Number != 1 || got[0].StalledHours != 10 {
-		t.Errorf("排序應由長到短，首筆 issue 1（10h），got %v", got[0])
-	}
-	if byNumber[2].LastCommentBy != "ceo" {
-		t.Errorf("issue 2 last_comment_by 應為 ceo，got %q", byNumber[2].LastCommentBy)
-	}
-}
-
-// TestScanStalledNudgeCooldown 最後留言出自掃描者本人 → 24 小時內冷卻不列入。
-func TestScanStalledNudgeCooldown(t *testing.T) {
-	now := at(0)
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("agents", true)},
-		issues: map[string]map[int]Issue{
-			"alterminal/agents": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/agents"}},
-			},
-		},
-		comments: map[string][]Comment{
-			// admin（掃描者）10 小時前催促過 → 冷卻中，不列入。
-			"alterminal/agents/1": {{User: User{"admin"}, CreatedAt: at(-600)}},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 0 {
-		t.Fatalf("催促冷卻中的項目不應列入，got %v", got)
-	}
-	// 冷卻過了（25 小時前催促）→ 重新列入。
-	src.comments["alterminal/agents/1"] = []Comment{{User: User{"admin"}, CreatedAt: at(-1500)}}
-	got, err = ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 1 || got[0].Reason != "waiting-outside" {
-		t.Fatalf("冷卻後應重新列入，got %v", got)
-	}
-}
-
-// TestScanStalledParentTracking 父追蹤項：子項活動計入 last_activity、reason 標記。
-func TestScanStalledParentTracking(t *testing.T) {
-	now := at(0)
-	// 父項與子項都 5 小時沒動：父項 last_activity 計入子項活動後同為 5h，
-	// 應以 parent-tracking 列入並附子項摘要；子項本身則是 assignee-idle。
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
-			"alterminal/teai": {
-				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: at(-700), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				7: {Number: 7, Title: "子", State: "open", CreatedAt: at(-650), UpdatedAt: at(-300), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/teai"}},
-			},
-		},
-		comments: map[string][]Comment{
-			"alterminal/teai/7": {{User: User{"max"}, CreatedAt: at(-300)}},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	var parent3, child7 *Item
-	for i := range got {
-		switch got[i].Number {
-		case 3:
-			parent3 = &got[i]
-		case 7:
-			child7 = &got[i]
-		}
-	}
-	if child7 == nil {
-		t.Fatalf("子項 7 應列入（5h 無活動），got %v", got)
-	}
-	if child7.Reason != "assignee-idle" {
-		t.Errorf("子項 7 reason = %q, want assignee-idle", child7.Reason)
-	}
-	if parent3 == nil {
-		t.Fatalf("父項 3 應列入，got %v", got)
-	}
-	if parent3.Reason != "parent-tracking" {
-		t.Errorf("父項 3 reason = %q, want parent-tracking", parent3.Reason)
-	}
-	if len(parent3.ChildActivity) != 1 || parent3.ChildActivity[0].Number != 7 {
-		t.Errorf("父項 3 應附子項摘要，got %v", parent3.ChildActivity)
-	}
-	if parent3.StalledHours != 5 {
-		t.Errorf("父項 3 stalled_hours = %v, want 5", parent3.StalledHours)
-	}
-
-	// 子項 1 小時前恢復活動 → 父項 last_activity 跟著更新，未達門檻不列入；
-	// 子項本身也不停滯。整份輸出應為空。
-	child := src.issues["alterminal/teai"][7]
-	child.UpdatedAt = at(-60)
-	src.issues["alterminal/teai"][7] = child
-	src.comments["alterminal/teai/7"] = []Comment{{User: User{"max"}, CreatedAt: at(-60)}}
-	got, err = ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 0 {
-		t.Fatalf("子項推進中 → 父項不應誤報停滯，got %v", got)
-	}
-}
-
-// TestScanStalledParentTrackingNotChild 上行引用：引用對象早於父項 → 非子項，不採計。
-func TestScanStalledParentTrackingNotChild(t *testing.T) {
-	now := at(0)
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
-			"alterminal/teai": {
-				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: at(-700), UpdatedAt: at(-600), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				39: {Number: 39, State: "open", CreatedAt: at(-2000), UpdatedAt: at(-60), Repository: Reference{"alterminal/teai"}},
-			},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	// #39 是上行引用，不採計 → 父項 47 停滯 10h（assignee-idle：ceo 分派、無留言）→ no-commenter。
-	var n47 *Item
-	for i := range got {
-		if got[i].Number == 47 {
-			n47 = &got[i]
-		}
-	}
-	if n47 == nil {
-		t.Fatalf("上行引用不採計 → 47 應停滯列入，got %v", got)
-	}
-	if n47.Reason != "no-commenter" {
-		t.Errorf("47 reason = %q, want no-commenter", n47.Reason)
-	}
-	if len(n47.ChildActivity) != 0 {
-		t.Errorf("上行引用不應產生子項摘要，got %v", n47.ChildActivity)
-	}
-	// #39 本身 updated 1 小時前 → 不列入。
-	for _, it := range got {
-		if it.Number == 39 {
-			t.Errorf("39 未達門檻不應列入：%v", it)
-		}
-	}
-}
-
-// TestScanStalledPullReasons 驗證 PR 的 reason 分類。
-func TestScanStalledPullReasons(t *testing.T) {
-	now := at(0)
-	h := true
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
-		pulls: map[string][]PullRequest{
-			"alterminal/teai": {
-				{Number: 10, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)},
-				{Number: 11, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 12, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 13, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-			},
-		},
-		comments: map[string][]Comment{
-			"alterminal/teai/11": {{User: User{"max"}, CreatedAt: at(-300)}}, // author-idle
-			"alterminal/teai/12": {{User: User{"ceo"}, CreatedAt: at(-300)}}, // reviewer-idle
-			"alterminal/teai/13": {{User: User{"dan"}, CreatedAt: at(-300)}}, // no-commenter（外部留言）
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	byNumber := map[int]Item{}
-	for _, it := range got {
-		byNumber[it.Number] = it
-	}
-	for n, wantReason := range map[int]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
-		item, ok := byNumber[n]
-		if !ok {
-			t.Fatalf("PR %d 應列入，got %v", n, got)
-		}
-		if item.Reason != wantReason {
-			t.Errorf("PR %d reason = %q, want %q", n, item.Reason, wantReason)
-		}
-	}
-	if len(got) != 4 {
-		t.Fatalf("應 4 筆，got %d", len(got))
-	}
-	if byNumber[10].Author != "max" {
-		t.Errorf("PR 10 author 應為 max，got %q", byNumber[10].Author)
-	}
-}
-
-// TestScanStalledNoPullsFlag 停用 PR 的倉庫仍掃 issues，只跳過 PR。
-func TestScanStalledNoPullsFlag(t *testing.T) {
-	now := at(0)
-	h := false
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
-		issues: map[string]map[int]Issue{
-			"alterminal/docs": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/docs"}},
-			},
-		},
-		pulls: map[string][]PullRequest{
-			// 即使假資料有 PR，flag 關閉也不應掃。
-			"alterminal/docs": {{Number: 2, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)}},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 1 || got[0].Number != 1 || got[0].Type != "issue" {
-		t.Fatalf("應只有 issue 1，got %v", got)
-	}
-}
-
-// TestScanStalledSkipsPRsInIssues 確認 /issues 混入的 PR 會被過濾。
-func TestScanStalledSkipsPRsInIssues(t *testing.T) {
-	now := at(0)
-	src := &fakeSource{
-		orgs:  []string{"alterminal"},
-		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int]Issue{
-			"alterminal/teai": {
-				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/teai"}, PullRequest: struct{}{}},
-			},
-		},
-	}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 0 {
-		t.Fatalf("/issues 混入的 PR 應過濾，got %v", got)
-	}
-}
-
-// TestItemJSON 與 gitea.py 的 JSON 位元組相容（鍵序、HTML 不轉義、48.0、null）。
-func TestItemJSON(t *testing.T) {
-	ts := at(-600)
-	activity := FormatMoment(ts)
-	item := Item{
-		Type: "issue", Repo: "alterminal/teai", Number: 7, Title: "R,D <v2> & 規劃", URL: "u",
-		Assignees: []string{"ceo"}, LastCommentBy: "max",
-		LastActivityAt: ts, StalledHours: 48, Reason: "assignee-idle",
-		ChildActivity: []Child{
-			{Repo: "alterminal/teai", Number: 3, Title: "父", State: "open", LastActivityAt: &activity},
-			{Repo: "alterminal/teai", Number: 4, Title: "無時刻", State: "open"},
-		},
-	}
-	// json.Marshal 會把 <、>、& 重新轉義，必須用停用 HTML 轉義的編碼器。
-	var buf bytes.Buffer
-	enc := json.NewEncoder(&buf)
-	enc.SetEscapeHTML(false)
-	if err := enc.Encode(item); err != nil {
-		t.Fatalf("Encode: %v", err)
-	}
-	got := strings.TrimSuffix(buf.String(), "\n")
-	want := `{"type":"issue","repo":"alterminal/teai","number":7,"title":"R,D <v2> & 規劃","url":"u","assignees":["ceo"],"last_comment_by":"max","last_activity_at":"2026-09-09T22:00:00+00:00","stalled_hours":48.0,"reason":"assignee-idle","child_activity":[{"repo":"alterminal/teai","number":3,"title":"父","state":"open","last_activity_at":"2026-09-09T22:00:00+00:00"},{"repo":"alterminal/teai","number":4,"title":"無時刻","state":"open","last_activity_at":null}]}`
-	if got != want {
-		t.Fatalf("JSON 位元組不相容:\n got %s\nwant %s", got, want)
-	}
-}
-
-// TestPullJSON：pull 的鍵序（author、reviewers）與非整數 stalled_hours。
-func TestPullJSON(t *testing.T) {
-	item := Item{
-		Type: "pull", Repo: "alterminal/teai", Number: 12, Title: "t", URL: "u",
-		Author: "ceo", Reviewers: []string{"queena"},
-		LastActivityAt: at(-600), StalledHours: 10.44, Reason: "reviewer-idle",
-	}
-	b, err := json.Marshal(item)
-	if err != nil {
-		t.Fatalf("Marshal: %v", err)
-	}
-	got := string(b)
-	want := `{"type":"pull","repo":"alterminal/teai","number":12,"title":"t","url":"u","author":"ceo","reviewers":["queena"],"last_comment_by":"","last_activity_at":"2026-09-09T22:00:00+00:00","stalled_hours":10.4,"reason":"reviewer-idle"}`
-	if got != want {
-		t.Fatalf("JSON 位元組不相容:\n got %s\nwant %s", got, want)
-	}
-}
-
-// TestScanStalledEmpty 無停滯項目 → 空輸出（CLI 層輸出 []）。
-func TestScanStalledEmpty(t *testing.T) {
-	now := at(0)
-	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repository{"alterminal": repoWith("teai", true)}}
-	got, err := ScanStalled(src, "admin", 4.0, now)
-	if err != nil {
-		t.Fatalf("ScanStalled: %v", err)
-	}
-	if len(got) != 0 {
-		t.Fatalf("應空，got %v", got)
-	}
-}
-
-// TestScanStalledOrgError 組織層錯誤應回傳（不靜默）。
-func TestScanStalledOrgError(t *testing.T) {
-	src := &errSource{}
-	if _, err := ScanStalled(src, "admin", 4.0, at(0)); err == nil {
-		t.Fatal("組織清單失敗應回傳錯誤")
-	}
-}
-
-type errSource struct{}
-
-func (errSource) MyOrganizations() ([]string, error) { return nil, errors.New("boom") }
-func (e errSource) OrganizationRepositories(string) ([]Repository, error) {
-	return nil, errors.New("boom")
-}
-func (e errSource) OpenIssues(string, string) ([]Issue, error)      { return nil, errors.New("boom") }
-func (e errSource) OpenPulls(string, string) ([]PullRequest, error) { return nil, errors.New("boom") }
-func (e errSource) IssueComments(string, string, int) ([]Comment, error) {
-	return nil, errors.New("boom")
-}
-func (e errSource) TryGetIssue(string, string, int) (Issue, bool, error) {
-	return Issue{}, false, errors.New("boom")
-}
-
-// TestRound1 round1 十進位舍入到一位小數（與 Python round(x,1) 半偶數一致）。
-func TestRound1(t *testing.T) {
-	cases := []struct {
-		in   float64
-		want float64
-	}{
-		{10.44, 10.4}, {10.46, 10.5}, {10.0, 10.0},
-		// 半偶數（與 Python round(x,1) 對二進位真值的行為一致）：
-		// 10.45、5.25、5.15 的二進位真值都略低於表值 → 舍到偶數位。
-		{10.45, 10.4}, {0.05, 0.1}, {5.25, 5.2}, {5.15, 5.2},
-	}
-	for _, tc := range cases {
-		if got := round1(tc.in); got != tc.want {
-			t.Errorf("round1(%v) = %v, want %v", tc.in, got, tc.want)
-		}
-	}
-}