Merge pull request 'docs：已知輸出差異補 mine／pulls 欄位集差異（#26）' (#27) from docs/issue26-output-fieldset-diff into main

Reviewed-on: #27

README.md

@@ -6,17 +6,52 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
 
 - **語言：** Go（與 Gitea 本體一致），僅用標準庫，離線可建置
 - **目標站點：** `https://gitea.alterminal.com`
-- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）與日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）已實作；stalled/xrefs（#7）進行中
+- **狀態：** 基礎建設（#5：internal/gitea）、工作流命令（#6：whoami/orgs/members/mine/pulls/next）、日常操作命令（#8：issues/pulls/labels/milestones/releases/repos/api）與管理者巡邏命令（#7：stalled/xrefs）已實作
 - **範圍（#3）：** 不避開 tea 已有的功能；單一工具涵蓋完整操作
 
 ## 安裝與建置
 
-需要 Go 1.26 以上。
+### 需求
+
+- **Go 1.26 以上**（`go version` 確認；本倉庫僅用標準庫，離線可建置）
+- **git**
+- Gitea 帳號的 **API token**（設定階段使用；在 Gitea「設定 → 應用程式」產生）
+
+### 從原始碼建置
 
 ```sh
+git clone https://gitea.alterminal.com/alterminal/teai.git
+cd teai
 go build -o teai ./cmd/teai
+install -Dm755 teai ~/.local/bin/teai   # 或複製到任何 PATH 內目錄
+teai version                             # 驗證：teai version 0.1.0-dev
 ```
 
+也可以直接裝進 `GOBIN`（預設 `~/go/bin`；該目錄已在 PATH 時最省事）：
+
+```sh
+go install ./cmd/teai
+```
+
+> **注意：** `go install gitea.alterminal.com/alterminal/teai/cmd/teai@latest` 目前**不可用**——
+> module 尚未發佈任何 tag，`@latest` 會解析到任意中繼 commit（且 #21 修復前 main 建置失敗）。
+> 請在 clone 目錄內以版本控制的方式建置；發佈 tag 後再提供 `teai@<version>` 安裝路徑。
+
+### 登入設定（首次使用）
+
+teai 與 `tea` 共用同一份組態檔；若 `tea whoami` 已可正常輸出，可跳過本節。
+
+```sh
+teai login add --url https://gitea.alterminal.com
+# 未給 --token 時自 stdin 讀一行：貼上 token 後按 Enter（不會進 shell 歷史）
+teai whoami    # 驗證：應輸出 {"username":"<你的帳號>"}
+```
+
+- token 驗證失敗（HTTP 401）不會寫入組態，結束碼 3。
+- 組態檔：`--config`／`TEA_CONFIG` 指定，預設 `~/.config/tea/config.yml`；teai 採行級編輯，
+  不會改壞 tea 也在使用的欄位，檔案權限 `0600`。
+- 多站台以 `--name` 區分、`teai login default <名稱>` 切換預設；詳見下方 [`teai login`](#teai-login--管理登入) 一節。
+
 ## 指令設計
 
 > 工作流規則的唯一來源是 [`alterminal/agents`](https://gitea.alterminal.com/alterminal/agents) 的 `AGENTS.md`；
@@ -80,6 +115,7 @@ teai [全域選項] <命令> [參數]
 
 | 命令 | 對應 gitea.py | 說明 |
 | --- | --- | --- |
+| `teai login list\|add\|default\|remove` | — | 管理 tea 相容登入組態（見下） |
 | `teai whoami` | `get_current_username` | 目前帳號 |
 | `teai orgs` | `for_all_organizations` | 我所屬的組織 |
 | `teai members [--has-work]` | `members [--has-work]` | Agents 團隊成員；`--has-work` 只列有未完成工作者 |
@@ -118,6 +154,25 @@ teai next --output table  # 人類可讀
 }
 ```
 
+### `teai login` — 管理登入
+
+teai 與 tea 共用同一份組態檔（`--config`／`TEA_CONFIG`，預設 `~/.config/tea/config.yml`）。
+寫入採行級編輯：只動目標項目的行，未知欄位（`ssh_*` 等）與 `preferences` 區段逐字保留，
+不改壞 tea 也在使用的檔案；檔案權限 `0600`、暫存檔原子替換。
+
+```sh
+teai login list                      # 列出登入（一律不含 token）
+teai login add [--url <URL>] [--name <名稱>] [--default=false] [--token <TOKEN>]
+                                     # 先以 token 呼叫 GET /user 驗證，成功才寫入（並記下帳號）
+teai login default <名稱>            # 設定預設登入
+teai login remove <名稱> [--yes]     # 移除登入；移除預設者時其餘第一筆自動遞補
+```
+
+- `login add` 未給 `--token` 時自 stdin 讀一行，避免 token 進 shell 歷史；token 驗證失敗（401）
+  不寫入，結束碼 3。
+- 未給 `--name` 時：同站（URL 主機相同）已有登入 → 就地更新該項目；否則以 URL 主機為名稱。
+- 輸出 JSON（`--output table` 供人工查看），欄位 `name`／`url`／`user`／`default`，**永不輸出 token**。
+
 ### `teai stalled [--hours N]` — 管理者巡邏
 
 ```sh
@@ -216,6 +271,21 @@ teai whoami               # 目前帳號（讀 tea 組態）
 | `mine` | `teai mine` | 相同 |
 | （底線函式） | `internal/` 套件 | 不設 CLI 命令；`xrefs` 為其邏輯的公開化 |
 
+已知輸出差異（刻意保留，機器可讀優先）：
+
+- **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令
+  （`mine`／`pulls`）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確，
+  交叉驗證時以此差異為準。`next` 兩者語義相同（無工作 → `null`／「沒有未完成的工作」）。
+- **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件
+  （`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位
+  （`mine`：repo／number／title／url；`pulls`：number／title／state／author／
+  head／base／updated_at…依命令定義）。交叉驗證比對**項目集合**（列出哪些
+  issue／PR）與判定語義，不逐欄位比對；`next`／`stalled` 兩者為策展欄位且
+  鍵集鍵序全等，可逐欄位比對。判定 #26（維持摘要、文件化差異）。
+- **全域選項位置**：teai 的全域選項（`--output` 等）可出現在命令之前或之後，
+  且可與命令旗標交錯（`teai members --has-work --output table`）；
+  gitea.py 的旗標剖析較寬鬆，兩者命令列介面以此行為對齊。
+
 遷移策略：
 
 1. 以 gitea.py 為行為基準：同帳號同時跑兩者，輸出應一致（交叉驗證）。

cmd/xcheck/main.go

@@ -0,0 +1,294 @@
+// 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.Repo, error) {
+	var repos []workflow.Repo
+	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 int64) ([]workflow.Comment, error) {
+	var comments []workflow.Comment
+	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/comments", owner, repo, number), nil, &comments); err != nil {
+		return nil, err
+	}
+	return comments, nil
+}
+
+func (s *apiSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
+	var issue workflow.Issue
+	body, code, err := s.get(fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, number), nil)
+	if err != nil {
+		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

@@ -89,6 +89,11 @@ type Env struct {
 
 // commands 是已註冊的子命令表。新增功能時在這裡註冊即可。
 var commands = map[string]*command{
+	"login": {
+		name:  "login",
+		usage: "管理登入（list/add/default/remove）",
+		run:   runLogin,
+	},
 	"version": {
 		name:  "version",
 		usage: "顯示版本資訊",
@@ -145,10 +150,31 @@ var globalFlags = map[string]bool{
 	"--timeout": true,
 }
 
+// reservedFlags 回傳 dispatch 不得搶走的旗標名稱（含 -- 前綴）：這些
+// 旗標屬於目前命令（或其子命令），即使與全域選項同名也必須原樣留給
+// 命令剖析。目前唯一與全域同名的是 login add 的 --url／--token
+// （README「teai login add --url … --token …」）。其餘命令的旗標
+// （--repo、--has-work、--mine……）本來就不在 globalFlags 內，不受影響。
+func reservedFlags(name string) map[string]bool {
+	reserved := make(map[string]bool)
+	for _, f := range commandReservedFlags[name] {
+		reserved[f] = true
+	}
+	return reserved
+}
+
+// commandReservedFlags 登記每個命令「與全域選項同名」的自有旗標。
+// 命令旗標優先留給命令；新命令有同姓旗標時在這裡登記（#18）。
+var commandReservedFlags = map[string][]string{
+	"login": {"--url", "--token"},
+}
+
 // extractGlobals 從 args 中「抽取」全域選項（可出現在命令之後、與命令
 // 旗標交錯），其餘引數依原順序保留給子命令剖析。未知的選項一律留給
 // 子命令處理（可能是命令旗標，如 --has-work），不在這裡報錯。
-func extractGlobals(g *Globals, args []string) ([]string, error) {
+// reserved 是目前命令保留的旗標名稱（含 -- 前綴，見 reservedFlags）：
+// 列於其中的選項即使與全域同名也原樣留給命令，命令旗標優先（#18）。
+func extractGlobals(g *Globals, args []string, reserved map[string]bool) ([]string, error) {
 	rest := make([]string, 0, len(args))
 	applyGlobal := func(name, value string) error {
 		switch name {
@@ -192,6 +218,17 @@ func extractGlobals(g *Globals, args []string) ([]string, error) {
 			continue
 		}
 		name, inline, hasInline := strings.Cut(arg, "=")
+		if reserved[name] {
+			// 命令保留旗標：即使與全域選項同名也留給命令剖析（#18）。
+			rest = append(rest, arg)
+			if !hasInline && i+1 < len(args) {
+				// 旗標值跟在下一個引數；一併保留，不當成全域值。
+				rest = append(rest, args[i+1])
+				i++
+			}
+			i++
+			continue
+		}
 		_, ok := globalFlags[name]
 		if !ok {
 			// 不是全域選項：留給子命令（可能是 --has-work 這類命令旗標）。
@@ -288,11 +325,12 @@ func parseGlobals(g *Globals, args []string) ([]string, error) {
 // 旗標剖析交由各命令自行處理（不同命令有不同旗標，如 pulls --mine）；
 // 全域選項允許出現在命令之後（README 範例：teai next --output table），
 // dispatch 先從 args 剝離全域選項併入 Globals，其餘（含命令自己的旗標，
-// 如 --has-work）原樣交給命令，不會誤判為未知全域選項。
+// 如 --has-work）原樣交給命令，不會誤判為未知全域選項。與全域選項
+// 同名的命令旗標（登記於 commandReservedFlags）優先留給命令（#18）。
 func dispatch(env *Env, name string, args []string) int {
 	cmd := commands[name]
 	g := env.Globals
-	rest, err := extractGlobals(&g, args)
+	rest, err := extractGlobals(&g, args, reservedFlags(name))
 	if err != nil {
 		fmt.Fprintf(env.Err, "teai: %v\n\n", err)
 		printUsage(env.Err)
@@ -310,24 +348,79 @@ func dispatch(env *Env, name string, args []string) int {
 // 用法，靜默成功結束即可。
 var errHelp = errors.New("help requested")
 
-// parseFlags 剖析命令旗標：-h/--help 回 errHelp（由 exitCodeFor 視為成功），
+// parseFlags 剖析命令旗標，允許旗標與位置參數交錯（#25）：Go 標準
-// 其他剖析錯誤回 ErrUsage。
+// flag 在遇到第一個非旗標參數後即停止剖析，其後的旗標會被當成位置
+// 參數。做法：先掃描 args 把「旗標（含其值）」與「位置參數」分離成
+// 兩串，再以旗標串呼叫 fs.Parse，最後以第二次 Parse 把位置參數設回
+// fs.Args（Parse 遇到 "--" 即停止並收下其餘引數，第一次剖析已設好
+// 的旗標值不受影響）。
+// -h/--help 回 errHelp（由 exitCodeFor 視為成功），其他剖析錯誤回 ErrUsage。
 func parseFlags(fs *flag.FlagSet, args []string) error {
-	if err := fs.Parse(args); err != nil {
+	var flags, positional []string
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if arg == "--" {
+			// "--" 之後全部是位置參數（不再剖析旗標；同標準 flag）。
+			positional = append(positional, args[i+1:]...)
+			break
+		}
+		if len(arg) < 2 || arg[0] != '-' {
+			positional = append(positional, arg)
+			continue
+		}
+		flags = append(flags, arg)
+		// 判斷旗標是否需要「下一個引數」當值（布林旗標與 inline
+		// 形式 --name=value 不需要）。未知或格式錯誤的旗標不消費
+		// 下一個引數，交給 fs.Parse 產生標準錯誤訊息。
+		numMinuses := 1
+		if arg[1] == '-' {
+			numMinuses = 2
+		}
+		name := arg[numMinuses:]
+		if name == "" || name[0] == '-' || name[0] == '=' {
+			continue // ---x／--=…：bad flag syntax，由 fs.Parse 報錯
+		}
+		flagName, _, hasInline := strings.Cut(name, "=")
+		if !hasInline {
+			if fl := fs.Lookup(flagName); fl != nil && !isBoolFlag(fl) && i+1 < len(args) {
+				i++
+				flags = append(flags, args[i])
+			}
+		}
+	}
+	if err := fs.Parse(flags); err != nil {
 		if errors.Is(err, flag.ErrHelp) {
 			return errHelp
 		}
 		return &ErrUsage{Msg: err.Error()}
 	}
+	if len(positional) > 0 {
+		if err := fs.Parse(append([]string{"--"}, positional...)); err != nil {
+			if errors.Is(err, flag.ErrHelp) {
+				return errHelp
+			}
+			return &ErrUsage{Msg: err.Error()}
+		}
+	}
 	return nil
 }
 
+// isBoolFlag 回傳旗標是否為布林型（不需要值；同 flag 包內部判斷）。
+func isBoolFlag(fl *flag.Flag) bool {
+	bf, ok := fl.Value.(interface{ IsBoolFlag() bool })
+	return ok && bf.IsBoolFlag()
+}
+
 // exitCodeFor 把命令錯誤映射到結束碼：用法錯誤 → 2，API 錯誤 → 3，
-// 其他（內部）→ 1。
+// 其他（內部）→ 1。errHelp（命令的 -h/--help）視為成功（#25：
+// 與 parseFlags 註解宣稱一致，FlagSet 已印出用法說明）。
 func exitCodeFor(err error) ExitCode {
 	if err == nil {
 		return ExitOK
 	}
+	if err == errHelp {
+		return ExitOK
+	}
 	var usage *ErrUsage
 	if errors.As(err, &usage) {
 		return ExitUsage
@@ -339,8 +432,11 @@ func exitCodeFor(err error) ExitCode {
 	return ExitInternal
 }
 
-// runVersion 輸出版本資訊。
+// 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
 }

internal/cli/cli_test.go

@@ -51,8 +51,10 @@ func TestRunVersion(t *testing.T) {
 
 func TestRunUnknownCommand(t *testing.T) {
 	_, stderr, code := run("no-such-command")
-	if code != int(ExitUsage) {
+	// 直接對照 README「輸出與結束碼」的數值（用法錯誤＝2），
-		t.Errorf("未知命令應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	// 不以常數互比，避免常數與規格再次脫鉤（#10）。
+	if code != 2 {
+		t.Errorf("未知命令應回 2（README 用法錯誤），得到 %d", code)
 	}
 	if !strings.Contains(stderr, "unknown command") {
 		t.Errorf("未知命令應在 stderr 說明，得到：%q", stderr)

internal/cli/dailyops_commands_test.go

@@ -53,8 +53,9 @@ func TestIssuesListRequiresRepo(t *testing.T) {
 		t.Errorf("不應發出任何請求")
 	})
 	_, stderr, code := run("issues", "list")
-	if code != int(ExitUsage) {
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
-		t.Errorf("缺 --repo 應回 ExitUsage，得到 %d", code)
+	if code != 2 {
+		t.Errorf("缺 --repo 應回 2（README 用法錯誤），得到 %d", code)
 	}
 	if !strings.Contains(stderr, "--repo") {
 		t.Errorf("錯誤訊息應提及 --repo，得到：%s", stderr)
@@ -110,8 +111,9 @@ func TestWriteCommandsRequireYes(t *testing.T) {
 				t.Errorf("%s：未帶 --yes 不得發出請求（%s %s）", tc.name, r.Method, r.URL.Path)
 			})
 			_, stderr, code := run(tc.args...)
-			if code != int(ExitUsage) {
+			// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
-				t.Errorf("%s 未帶 --yes 應回 ExitUsage(2)，得到 %d", tc.name, code)
+			if code != 2 {
+				t.Errorf("%s 未帶 --yes 應回 2（README 用法錯誤），得到 %d", tc.name, code)
 			}
 			if !strings.Contains(stderr, "--yes") {
 				t.Errorf("%s 錯誤訊息應提及 --yes，得到：%s", tc.name, stderr)
@@ -235,7 +237,8 @@ func TestAPIDirectPassthrough(t *testing.T) {
 	}
 
 	_, stderr, code := run("api", "--method", "POST", "/version")
-	if code != int(ExitUsage) || !strings.Contains(stderr, "--yes") {
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 || !strings.Contains(stderr, "--yes") {
 		t.Errorf("POST 未帶 --yes 應回 2 並提及 --yes，得到 %d：%s", code, stderr)
 	}
 }

internal/cli/exitcode_test.go

@@ -10,20 +10,22 @@ import (
 )
 
 func TestExitCodeMapping(t *testing.T) {
+	// want 直接寫 README「輸出與結束碼」的數值（0／2／3；內部錯誤 1），
+	// 不以常數互比，避免常數與規格再次脫鉤（#10）。
 	cases := []struct {
 		name string
 		err  error
-		want ExitCode
+		want int
 	}{
-		{"usage error", &ErrUsage{Msg: "bad flag"}, ExitUsage},
+		{"usage error", &ErrUsage{Msg: "bad flag"}, 2},
-		{"api error 401", &gitea.ErrAPI{StatusCode: 401, Op: "GET /api/v1/user"}, ExitAPI},
+		{"api error 401", &gitea.ErrAPI{StatusCode: 401, Op: "GET /api/v1/user"}, 3},
-		{"api error transport", &gitea.ErrAPI{Op: "GET /api/v1/user", Err: errString("dial tcp")}, ExitAPI},
+		{"api error transport", &gitea.ErrAPI{Op: "GET /api/v1/user", Err: errString("dial tcp")}, 3},
-		{"wrapped api error", wrapped(&gitea.ErrAPI{StatusCode: 500}), ExitAPI},
+		{"wrapped api error", wrapped(&gitea.ErrAPI{StatusCode: 500}), 3},
-		{"other error", errString("boom"), ExitInternal},
+		{"other error", errString("boom"), 1},
-		{"nil maps to OK", nil, ExitOK},
+		{"nil maps to OK", nil, 0},
 	}
 	for _, tc := range cases {
-		if got := exitCodeFor(tc.err); got != tc.want {
+		if got := int(exitCodeFor(tc.err)); got != tc.want {
 			t.Errorf("%s: exitCodeFor = %d, want %d", tc.name, got, tc.want)
 		}
 	}
@@ -68,16 +70,16 @@ func TestRunExitCodes(t *testing.T) {
 	})
 }
 
-func TestParseGlobals(t *testing.T) {
+func TestExtractGlobals(t *testing.T) {
 	g := defaultGlobals()
-	rest, err := parseGlobals(&g, []string{
+	rest, err := extractGlobals(&g, []string{
 		"--url", "https://example.com",
 		"--token=tok",
 		"--config", "/tmp/c.yml",
 		"--output", "table",
 		"--timeout", "45s",
 		"next",
-	})
+	}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -95,16 +97,115 @@ func TestParseGlobals(t *testing.T) {
 	}
 }
 
-func TestParseGlobalsStopsAtCommand(t *testing.T) {
+func TestExtractGlobalsAfterCommand(t *testing.T) {
+	// 全域選項出現在命令之後也應抽出（README：teai next --output table）。
 	g := defaultGlobals()
-	rest, err := parseGlobals(&g, []string{"version", "--output", "table"})
+	rest, err := extractGlobals(&g, []string{"version", "--output", "table"}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
-	// 命令之後的選項屬於命令，不屬於全域。
+	if len(rest) != 1 || rest[0] != "version" {
-	if len(rest) != 3 || rest[0] != "version" {
+		t.Fatalf("rest = %v, want [version]", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
+func TestExtractGlobalsKeepsCommandFlags(t *testing.T) {
+	// 非全域選項屬於子命令：原樣依序交回，不能攔成 ErrUsage。
+	cases := [][]string{
+		{"members", "--has-work"},
+		{"pulls", "--mine"},
+		{"pulls", "--reviewer"},
+		{"pulls", "--repo", "alterminal/teai"},
+		{"members", "--has-work", "--output", "table"},
+		{"pulls", "--mine", "--repo", "alterminal/teai", "--output", "table"},
+	}
+	for _, args := range cases {
+		g := defaultGlobals()
+		rest, err := extractGlobals(&g, args, nil)
+		if err != nil {
+			t.Fatalf("extractGlobals(%v) 不應報錯：%v", args, err)
+		}
+		want := args
+		if strings.HasSuffix(strings.Join(args, " "), "--output table") {
+			want = args[:len(args)-2]
+		}
+		if len(rest) != len(want) {
+			t.Fatalf("extractGlobals(%v) rest = %v, want %v", args, rest, want)
+		}
+		for i := range want {
+			if rest[i] != want[i] {
+				t.Fatalf("extractGlobals(%v) rest = %v, want %v", args, rest, want)
+			}
+		}
+	}
+}
+
+func TestExtractGlobalsDoubleDashStops(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{"--output", "table", "--", "--url", "x"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// -- 之後全部交回，--url 不再視為全域選項。
+	if len(rest) != 2 || rest[0] != "--url" || rest[1] != "x" {
 		t.Fatalf("rest = %v", rest)
 	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
+// TestExtractGlobalsReservedFlags 驗證 #18：與全域同名的命令旗標
+// （登記於 commandReservedFlags）必須留給命令，其餘全域選項照常抽取。
+func TestExtractGlobalsReservedFlags(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"add",
+		"--url", "https://srv.example.com", // login add 自有旗標：保留
+		"--token=tok", // 同上（inline 形式）：保留
+		"--name", "test-site",
+		"--output", "table", // 非保留：仍是全域
+	}, reservedFlags("login"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"add", "--url", "https://srv.example.com", "--token=tok", "--name", "test-site"}
+	if len(rest) != len(want) {
+		t.Fatalf("rest = %v, want %v", rest, want)
+	}
+	for i := range want {
+		if rest[i] != want[i] {
+			t.Fatalf("rest = %v, want %v", rest, want)
+		}
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+	if g.URL != defaultGlobals().URL || g.Token != "" {
+		t.Fatalf("reserved flags must not leak into globals: %+v", g)
+	}
+}
+
+// TestExtractGlobalsNonReservedCommand 驗證 #13 行為不回歸：未登記保留
+// 旗標的命令（如 next/members/pulls），命令後的全域選項照常抽取、
+// 命令自己的旗標（--has-work 等）原樣保留。
+func TestExtractGlobalsNonReservedCommand(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"members", "--has-work", "--output", "table",
+	}, reservedFlags("members"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rest) != 2 || rest[0] != "members" || rest[1] != "--has-work" {
+		t.Fatalf("rest = %v, want [members --has-work]", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
 }
 
 // errString 把字串轉成 error（測試輔助）。

internal/cli/interleaved_flags_test.go

@@ -0,0 +1,160 @@
+// interleaved_flags_test.go — #25 的回歸測試：命令旗標放在位置參數
+// （path／編號／名稱）之後也必須被剖析，不得被當成位置參數。
+// 涵蓋 parseFlags 走的命令（issues/pulls view、api、stalled）與
+// 原本直接 fs.Parse 的命令（login default/remove、members）。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+)
+
+// TestAPIFlagsAfterPath 驗證 #25 重現步驟一：teai api <path> --method POST
+// --data '{}' --yes 的旗標在 path 之後仍被剖析（POST 送達伺服器而非 exit 2）。
+func TestAPIFlagsAfterPath(t *testing.T) {
+	var gotMethod string
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		gotMethod = r.Method
+		fmt.Fprint(w, `{}`)
+	})
+	_, _, code := run("api", "/version", "--method", "POST", "--data", `{}`, "--yes")
+	if code != 0 {
+		t.Fatalf("api 旗標在 path 之後應回 0（#25），得到 %d", code)
+	}
+	if gotMethod != "POST" {
+		t.Fatalf("應送出 POST，得到 %s", gotMethod)
+	}
+}
+
+// TestIssuesViewCommentsFlagAfterNumber 驗證 #25 重現步驟二：
+// teai issues view --repo owner/repo <編號> --comments 的 --comments
+// 在編號之後仍生效（有打 /comments 端點）。
+func TestIssuesViewCommentsFlagAfterNumber(t *testing.T) {
+	var commentsHit bool
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/comments"):
+			commentsHit = true
+			fmt.Fprint(w, `[]`)
+		case strings.HasSuffix(r.URL.Path, "/issues/8"):
+			fmt.Fprint(w, `{"number":8,"title":"t","state":"open","user":{"login":"ceo"},"body":"","html_url":"u","labels":[],"updated_at":"t"}`)
+		default:
+			fmt.Fprint(w, `[]`)
+		}
+	})
+	stdout, _, code := run("issues", "view", "--repo", "alterminal/teai", "8", "--comments")
+	if code != 0 {
+		t.Fatalf("issues view 編號在前旗標在後應回 0（#25），得到 %d", code)
+	}
+	if !commentsHit {
+		t.Fatalf("--comments 在編號之後應觸發 /comments 請求；輸出：%s", stdout)
+	}
+}
+
+// TestPullsViewCommentsFlagAfterNumber 同上，驗證 pulls view。
+func TestPullsViewCommentsFlagAfterNumber(t *testing.T) {
+	var commentsHit bool
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/comments"):
+			commentsHit = true
+			fmt.Fprint(w, `[]`)
+		case strings.HasSuffix(r.URL.Path, "/pulls/13"):
+			fmt.Fprint(w, `{"number":13,"title":"t","state":"open","user":{"login":"ceo"},"body":"","html_url":"u","labels":[],"updated_at":"t"}`)
+		default:
+			fmt.Fprint(w, `[]`)
+		}
+	})
+	_, _, code := run("pulls", "view", "--repo", "alterminal/teai", "13", "--comments")
+	if code != 0 {
+		t.Fatalf("pulls view 編號在前旗標在後應回 0（#25），得到 %d", code)
+	}
+	if !commentsHit {
+		t.Fatal("--comments 在編號之後應觸發 /comments 請求")
+	}
+}
+
+// TestStalledHoursFlagAfterPositional 驗證 stalled 即使混入位置參數
+// 也不誤剖析：--hours 在位置參數後仍被剖析，而 stalled 本身不接受
+// 位置參數 → 應回 2（用法錯誤）而非誤把 --hours 當位置參數。
+func TestStalledHoursFlagAfterPositional(t *testing.T) {
+	run := opsTestServer(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `[]`)
+	})
+	_, stderr, code := run("stalled", "9", "--hours", "3")
+	if code != 2 {
+		t.Fatalf("stalled 帶位置參數應回 2，得到 %d", code)
+	}
+	if !strings.Contains(stderr, "位置參數") {
+		t.Fatalf("錯誤訊息應提及位置參數，得到：%s", stderr)
+	}
+	// 對照組：--hours 值非法（剖析層錯誤）應回 2，而非把旗標當位置參數。
+	_, stderr, code = run("stalled", "--hours", "abc")
+	if code != 2 || !strings.Contains(stderr, "invalid value") {
+		t.Fatalf("stalled --hours abc 應回 2 且提及 invalid value，得到 %d：%s", code, stderr)
+	}
+	// 交錯但無多餘位置參數：--hours 值不會被誤收。
+	_, stderr, code = run("stalled", "--hours")
+	if code != 2 || !strings.Contains(stderr, "flag needs an argument") {
+		t.Fatalf("stalled --hours 缺值應回 2 且提及 flag needs an argument，得到 %d：%s", code, stderr)
+	}
+}
+
+// TestLoginDefaultNameOnly 驗證 login default <名稱>：位置參數在旗標
+// 之後（--config 在前）仍正確收取一個名稱。
+func TestLoginDefaultNameOnly(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	prefix, _ := loginTestEnv(t, cfg)
+	stdout, _, code := run(append(prefix, "login", "default", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("login default b 應回 0 並輸出 b：code=%d out=%s", code, stdout)
+	}
+	// 多給一個位置參數仍應報用法錯誤（不受交錯支援影響）。
+	_, stderr, code := run(append(prefix, "login", "default", "b", "c")...)
+	if code != 2 || !strings.Contains(stderr, "exactly one") {
+		t.Fatalf("兩個名稱應回 2，得到 %d：%s", code, stderr)
+	}
+}
+
+// TestMemberHelpExitZero 驗證命令的 -h 結束碼為 0（#25 順帶修正：
+// errHelp 視為成功）。
+func TestMemberHelpExitZero(t *testing.T) {
+	_, _, code := run("members", "-h")
+	if code != 0 {
+		t.Fatalf("members -h 應回 0，得到 %d", code)
+	}
+}
+
+// TestLoginRemoveFlagInterleaved 驗證 login remove <名稱> --yes：
+// --yes 在名稱之後仍視為旗標（未帶時走確認流程會讀 stdin）。
+func TestLoginRemoveFlagInterleaved(t *testing.T) {
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+`)
+	old := loginStdin
+	loginStdin = strings.NewReader("y\n") // 若 --yes 失效會讀到這行
+	defer func() { loginStdin = old }()
+	_, _, code := run(append(prefix, "login", "remove", "a", "--yes")...)
+	if code != 0 {
+		t.Fatalf("login remove a --yes 應回 0，得到 %d", code)
+	}
+	data, _ := os.ReadFile(configPath)
+	if strings.Contains(string(data), "token: ta") {
+		t.Fatalf("--yes 在名稱之後應生效（直接刪除）：\n%s", data)
+	}
+}

internal/cli/login.go

@@ -0,0 +1,365 @@
+// login.go — teai login 指令：管理 tea 相容的登入組態。
+//
+// teai 與 tea 共用同一份組態檔（README 設計原則 5），login 的職責是：
+// 以 token 向站點驗證（GET /user），成功後才寫入組態並記下帳號。
+// token 只走記憶體與組態檔，不進輸出、日誌或錯誤訊息。
+//
+// 子命令：list／add／default／remove。
+package cli
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// loginStdin 是讀 token 與確認的輸入（測試可替換）。
+var loginStdin io.Reader = os.Stdin
+
+// loginConfigPath 回傳組態檔路徑：--config／TEA_CONFIG 優先，其次
+// ~/.config/tea/config.yml。找不到可用路徑回空字串。
+func loginConfigPath(g Globals) string {
+	if p := strings.TrimSpace(g.ConfigPath); p != "" {
+		return expandHome(p)
+	}
+	if p := os.Getenv("TEA_CONFIG"); strings.TrimSpace(p) != "" {
+		return expandHome(strings.TrimSpace(p))
+	}
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".config", "tea", "config.yml")
+}
+
+// expandHome 展開路徑開頭的 ~。
+func expandHome(p string) string {
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			return filepath.Join(home, strings.TrimPrefix(p, "~"))
+		}
+	}
+	return p
+}
+
+// runLogin 是 teai login 的進入點：分派子命令。
+func runLogin(env *Env, args []string) error {
+	if len(args) == 0 {
+		return &ErrUsage{Msg: "login requires a subcommand: list, add, default, remove"}
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "list":
+		return runLoginList(env, rest)
+	case "add":
+		return runLoginAdd(env, rest)
+	case "default":
+		return runLoginDefault(env, rest)
+	case "remove":
+		return runLoginRemove(env, rest)
+	default:
+		return &ErrUsage{Msg: fmt.Sprintf("unknown login subcommand %q (want list, add, default, remove)", sub)}
+	}
+}
+
+// loginFields 是輸出欄位（不含 token）。
+var loginFields = []gitea.Field{
+	{Name: "name"},
+	{Name: "url"},
+	{Name: "user"},
+	{Name: "default"},
+}
+
+// printLoginList 依格式輸出登入清單。
+func printLoginList(env *Env, logins []gitea.LoginEntry) error {
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	rows := make([]gitea.Values, 0, len(logins))
+	for _, l := range logins {
+		rows = append(rows, gitea.Values{l.Name, l.URL, l.User, l.Default})
+	}
+	return p.PrintList(loginFields, rows)
+}
+
+// runLoginList 列出組態中的登入（一律不含 token）。
+func runLoginList(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login list", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() > 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("unexpected argument %q", fs.Arg(0))}
+	}
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	logins, err := gitea.ListLoginsFile(path)
+	if err != nil {
+		return fmt.Errorf("read config %s: %w", path, err)
+	}
+	return printLoginList(env, logins)
+}
+
+// runLoginAdd 新增或更新登入：先驗證 token（GET /user），成功才寫入。
+//
+// token 來源：--token 旗標，或 stdin（預設未給旗標時讀一行，
+// 避免 token 進 shell 歷史）。
+func runLoginAdd(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login add", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	urlFlag := fs.String("url", env.Globals.URL, "Gitea 站點網址")
+	nameFlag := fs.String("name", "", "登入名稱（省略時取 URL 主機）")
+	tokenFlag := fs.String("token", "", "API token（省略時自 stdin 讀一行）")
+	defaultFlag := fs.Bool("default", true, "設為預設登入")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() > 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("unexpected argument %q", fs.Arg(0))}
+	}
+	siteURL := strings.TrimSuffix(strings.TrimSpace(*urlFlag), "/")
+	if siteURL == "" {
+		return &ErrUsage{Msg: "--url must not be empty"}
+	}
+
+	token := strings.TrimSpace(*tokenFlag)
+	if token == "" {
+		t, err := readLineFrom(loginStdin)
+		if err != nil {
+			return fmt.Errorf("read token from stdin: %w", err)
+		}
+		token = t
+	}
+	if token == "" {
+		return &ErrUsage{Msg: "token must not be empty"}
+	}
+
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	data, err := os.ReadFile(path)
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("read config %s: %w", path, err)
+	}
+
+	name := strings.TrimSpace(*nameFlag)
+	if name == "" {
+		// 未指定名稱：同站（主機相同）已有登入就就地更新，避免重複項目。
+		if existing, ok := findLoginByHost(data, siteURL); ok {
+			name = existing.Name
+		} else {
+			name = defaultLoginName(siteURL)
+		}
+	}
+
+	// 先驗證再寫入：token 無效時不動組態檔。
+	user, err := verifyToken(env, siteURL, token)
+	if err != nil {
+		return err
+	}
+	out, final, err := gitea.UpsertLogin(data, gitea.LoginEntry{
+		Name:    name,
+		URL:     siteURL,
+		Token:   token,
+		Default: *defaultFlag,
+		User:    user,
+	}, *defaultFlag)
+	if err != nil {
+		return err
+	}
+	if err := gitea.SaveTeaConfigFile(path, out); err != nil {
+		return err
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{final.Name, final.URL, final.User, final.Default})
+}
+
+// readLineFrom 讀一行並去除頭尾空白；EOF 且無內容回空字串。
+func readLineFrom(r io.Reader) (string, error) {
+	line, err := bufio.NewReader(r).ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}
+
+// verifyToken 以 token 呼叫 GET /user，回傳帳號名稱。
+// 401 特別標明是 token 遭拒，其餘依 *gitea.ErrAPI 對應結束碼 3。
+func verifyToken(env *Env, siteURL, token string) (string, error) {
+	c, err := gitea.New(siteURL, token, env.Globals.Timeout)
+	if err != nil {
+		return "", &ErrUsage{Msg: err.Error()}
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), env.Globals.Timeout)
+	defer cancel()
+	var out struct {
+		Login string `json:"login"`
+	}
+	if err := c.GetJSON(ctx, "/user", &out); err != nil {
+		var api *gitea.ErrAPI
+		if errors.As(err, &api) && api.StatusCode == 401 {
+			// 包 %w 保留 *ErrAPI：結束碼對應 3（API 錯誤）。
+			return "", fmt.Errorf("token rejected by %s: %w", siteURL, api)
+		}
+		return "", err
+	}
+	if out.Login == "" {
+		return "", fmt.Errorf("empty account name returned by %s", siteURL)
+	}
+	return out.Login, nil
+}
+
+// runLoginDefault 設定預設登入。
+func runLoginDefault(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login default", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "login default requires exactly one login name"}
+	}
+	name := fs.Arg(0)
+	data, err := readLoginConfig(env, "login default")
+	if err != nil {
+		return err
+	}
+	entry, found := findLogin(data, name)
+	if !found {
+		return fmt.Errorf("gitea: login %q not found", name)
+	}
+	out, err := gitea.SetDefaultLogin(data, name)
+	if err != nil {
+		return err
+	}
+	if err := saveLoginConfig(env, out); err != nil {
+		return err
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{entry.Name, entry.URL, entry.User, true})
+}
+
+// runLoginRemove 移除登入；未加 --yes 時先確認。
+func runLoginRemove(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai login remove", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	yesFlag := fs.Bool("yes", false, "跳過確認")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 1 {
+		return &ErrUsage{Msg: "login remove requires exactly one login name"}
+	}
+	name := fs.Arg(0)
+	data, err := readLoginConfig(env, "login remove")
+	if err != nil {
+		return err
+	}
+	entry, found := findLogin(data, name)
+	if !found {
+		return fmt.Errorf("gitea: login %q not found", name)
+	}
+	if !*yesFlag {
+		confirmed, err := confirmRemove(env, entry)
+		if err != nil {
+			return err
+		}
+		if !confirmed {
+			fmt.Fprintln(env.Out, "cancelled")
+			return nil
+		}
+	}
+	out, promoted, err := gitea.RemoveLogin(data, name)
+	if err != nil {
+		return err
+	}
+	if err := saveLoginConfig(env, out); err != nil {
+		return err
+	}
+	if promoted != "" {
+		fmt.Fprintf(env.Err, "default login is now %q\n", promoted)
+	}
+	p := gitea.Printer{Format: env.Globals.Output, Out: env.Out}
+	return p.PrintOne(loginFields, gitea.Values{entry.Name, entry.URL, entry.User, false})
+}
+
+// confirmRemove 印出待移除項目（不含 token）並讀 y/yes 確認；
+// 其他輸入（含 EOF）一律視為取消。
+func confirmRemove(env *Env, entry gitea.LoginEntry) (bool, error) {
+	fmt.Fprintf(env.Err, "remove login %q (url %s, user %s)? [y/N] ", entry.Name, entry.URL, entry.User)
+	line, err := readLineFrom(loginStdin)
+	if err != nil {
+		return false, fmt.Errorf("read confirmation: %w", err)
+	}
+	switch strings.ToLower(line) {
+	case "y", "yes":
+		return true, nil
+	default:
+		return false, nil
+	}
+}
+
+// readLoginConfig 讀組態檔內容；路徑無法判定或讀取失敗時回錯。
+func readLoginConfig(env *Env, op string) ([]byte, error) {
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return nil, fmt.Errorf("cannot determine config path")
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("%s: read config %s: %w", op, path, err)
+	}
+	return data, nil
+}
+
+// saveLoginConfig 原子寫回組態檔。
+func saveLoginConfig(env *Env, data []byte) error {
+	path := loginConfigPath(env.Globals)
+	if path == "" {
+		return fmt.Errorf("cannot determine config path")
+	}
+	return gitea.SaveTeaConfigFile(path, data)
+}
+
+// findLoginByHost 在組態內容中找 URL 主機與 siteURL 相同的登入。
+func findLoginByHost(data []byte, siteURL string) (gitea.LoginEntry, bool) {
+	for _, l := range gitea.ListLogins(data) {
+		if gitea.HostOf(l.URL) == gitea.HostOf(siteURL) {
+			return l, true
+		}
+	}
+	return gitea.LoginEntry{}, false
+}
+
+// findLogin 在組態內容中找指定名稱的登入。
+func findLogin(data []byte, name string) (gitea.LoginEntry, bool) {
+	for _, l := range gitea.ListLogins(data) {
+		if l.Name == name {
+			return l, true
+		}
+	}
+	return gitea.LoginEntry{}, false
+}
+
+// defaultLoginName 以 URL 主機作為登入名稱（同 tea 的習慣）。
+func defaultLoginName(rawURL string) string {
+	s := rawURL
+	if !strings.Contains(s, "://") {
+		s = "https://" + s
+	}
+	if u, err := url.Parse(s); err == nil && u.Host != "" {
+		return u.Host
+	}
+	return rawURL
+}

internal/cli/login_test.go

@@ -0,0 +1,292 @@
+// login_test.go 驗證 login 指令：list/add/default/remove 的輸出、
+// 驗證流程（先 GET /user 再寫入）、401 不寫檔、token 不外洩。
+package cli
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+)
+
+// loginTestEnv 建立測試環境：臨時組態檔路徑 + 可替換的 stdin。
+func loginTestEnv(t *testing.T, configContent string) (args []string, configPath string) {
+	t.Helper()
+	dir := t.TempDir()
+	configPath = filepath.Join(dir, "config.yml")
+	if configContent != "" {
+		if err := os.WriteFile(configPath, []byte(configContent), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("TEA_CONFIG", configPath)
+	return []string{"--config", configPath}, configPath
+}
+
+// newAPIServer 建立假的 Gitea API：/user 檢查 Authorization。
+func newAPIServer(t *testing.T, wantToken string, status int) (*httptest.Server, *atomic.Value) {
+	t.Helper()
+	var gotAuth atomic.Value
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth.Store(r.Header.Get("Authorization"))
+		if r.URL.Path != "/api/v1/user" {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		if status != 0 {
+			w.WriteHeader(status)
+			return
+		}
+		fmt.Fprint(w, `{"login":"ceo"}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv, &gotAuth
+}
+
+func TestLoginListJSONNoToken(t *testing.T) {
+	prefix, _ := loginTestEnv(t, `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: super-secret
+      default: true
+      user: ceo
+`)
+	stdout, _, code := run(append(prefix, "login", "list")...)
+	if code != 0 {
+		t.Fatalf("code = %d", code)
+	}
+	if !strings.Contains(stdout, `"name":"alterminal"`) || !strings.Contains(stdout, `"user":"ceo"`) {
+		t.Fatalf("unexpected output: %s", stdout)
+	}
+	if strings.Contains(stdout, "super-secret") || strings.Contains(stdout, "token") {
+		t.Fatalf("token leaked: %s", stdout)
+	}
+}
+
+func TestLoginListEmpty(t *testing.T) {
+	prefix, path := loginTestEnv(t, "")
+	if _, err := os.Stat(path); err == nil {
+		t.Fatal("precondition: config should not exist")
+	}
+	stdout, _, code := run(append(prefix, "login", "list")...)
+	if code != 0 {
+		t.Fatalf("code = %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("want [], got %q", stdout)
+	}
+}
+
+func TestLoginAddVerifiesThenWrites(t *testing.T) {
+	srv, gotAuth := newAPIServer(t, "tok-xyz", 0)
+	prefix, configPath := loginTestEnv(t, "")
+	stdout, _, code := run(append(prefix,
+		"--url", srv.URL, "login", "add", "--name", "test-site", "--token", "tok-xyz")...)
+	if code != 0 {
+		t.Fatalf("code = %d, stdout = %s", code, stdout)
+	}
+	if got := gotAuth.Load(); got != "token tok-xyz" {
+		t.Fatalf("server saw Authorization %v", got)
+	}
+	if !strings.Contains(stdout, `"name":"test-site"`) || !strings.Contains(stdout, `"user":"ceo"`) {
+		t.Fatalf("unexpected output: %s", stdout)
+	}
+	if strings.Contains(stdout, "tok-xyz") {
+		t.Fatalf("token leaked: %s", stdout)
+	}
+	// 寫入的組態可被解析，且欄位齊全。
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := gitea.ListLogins(data)
+	if len(logins) != 1 {
+		t.Fatalf("want 1 login, got %d:\n%s", len(logins), data)
+	}
+	l := logins[0]
+	if l.Name != "test-site" || l.URL != srv.URL || l.Token != "tok-xyz" || !l.Default || l.User != "ceo" {
+		t.Fatalf("entry mismatch: %+v", l)
+	}
+	info, _ := os.Stat(configPath)
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("perm = %v", info.Mode().Perm())
+	}
+}
+
+func TestLoginAddTokenFromStdin(t *testing.T) {
+	srv, _ := newAPIServer(t, "stdin-tok", 0)
+	prefix, configPath := loginTestEnv(t, "")
+	old := loginStdin
+	loginStdin = strings.NewReader("stdin-tok\n")
+	defer func() { loginStdin = old }()
+	stdout, _, code := run(append(prefix, "--url", srv.URL, "login", "add")...)
+	if code != 0 {
+		t.Fatalf("code = %d, stdout = %s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Token != "stdin-tok" {
+		t.Fatalf("stdin token not saved:\n%s", data)
+	}
+}
+
+func TestLoginAddRejected401NoWrite(t *testing.T) {
+	srv, _ := newAPIServer(t, "", http.StatusUnauthorized)
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: keep
+      url: https://keep.example.com
+      token: keep-tok
+      default: true
+`)
+	_, stderr, code := run(append(prefix,
+		"--url", srv.URL, "login", "add", "--token", "bad-tok")...)
+	// 401 是 API 錯誤；對照 README「輸出與結束碼」＝3（#10）。
+	if code != 3 {
+		t.Fatalf("401 should exit 3 (README api error), got %d (stderr %s)", code, stderr)
+	}
+	if !strings.Contains(stderr, "401") {
+		t.Fatalf("stderr should mention 401: %s", stderr)
+	}
+	// 組態不受影響。
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Token != "keep-tok" {
+		t.Fatalf("config must be untouched:\n%s", data)
+	}
+}
+
+func TestLoginAddUpdatesExistingInPlace(t *testing.T) {
+	srv, _ := newAPIServer(t, "new-tok", 0)
+	prefix, configPath := loginTestEnv(t, `logins:
+    - name: alterminal
+      url: `+srv.URL+`
+      token: old-tok
+      default: true
+      user: someone-else
+      ssh_key: "keep-me"
+preferences:
+    editor: false
+`)
+	stdout, _, code := run(append(prefix, "--url", srv.URL, "login", "add", "--token", "new-tok")...)
+	if code != 0 {
+		t.Fatalf("code = %d, out = %s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	s := string(data)
+	// 未給 --name：同站既有項目（name: alterminal）就地更新，不新增重複項目。
+	if strings.Contains(stdout, `"name":"127.0.0.1:`) {
+		t.Fatalf("should reuse existing entry name, got %s", stdout)
+	}
+	if !strings.Contains(s, "- name: alterminal") {
+		t.Fatalf("existing entry name lost:\n%s", s)
+	}
+	if strings.Contains(s, "old-tok") || !strings.Contains(s, "token: new-tok") {
+		t.Fatalf("token not replaced:\n%s", s)
+	}
+	if !strings.Contains(s, `ssh_key: "keep-me"`) || !strings.Contains(s, "editor: false") {
+		t.Fatalf("unrelated content lost:\n%s", s)
+	}
+	if !strings.Contains(s, "user: ceo") {
+		t.Fatalf("user not refreshed:\n%s", s)
+	}
+}
+
+func TestLoginDefaultAndRemove(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	prefix, configPath := loginTestEnv(t, cfg)
+	stdout, _, code := run(append(prefix, "login", "default", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("default failed: code=%d out=%s", code, stdout)
+	}
+	data, _ := os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); !l[1].Default || l[0].Default {
+		t.Fatalf("default not switched:\n%s", data)
+	}
+
+	// remove --yes：移除預設者 b，a 遞補。
+	stdout, _, code = run(append(prefix, "login", "remove", "--yes", "b")...)
+	if code != 0 || !strings.Contains(stdout, `"name":"b"`) {
+		t.Fatalf("remove failed: code=%d out=%s", code, stdout)
+	}
+	data, _ = os.ReadFile(configPath)
+	if l := gitea.ListLogins(data); len(l) != 1 || l[0].Name != "a" || !l[0].Default {
+		t.Fatalf("promote failed:\n%s", data)
+	}
+}
+
+func TestLoginRemoveAsksConfirmation(t *testing.T) {
+	prefix, _ := loginTestEnv(t, `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+`)
+	old := loginStdin
+	loginStdin = strings.NewReader("n\n")
+	defer func() { loginStdin = old }()
+	_, _, code := run(append(prefix, "login", "remove", "a")...)
+	if code != 0 {
+		t.Fatalf("cancel should still exit 0, got %d", code)
+	}
+	// 取消：檔案不變（token 仍在）。
+	data, _ := os.ReadFile(filepath.Dir(prefix[1]) + "/config.yml")
+	if !strings.Contains(string(data), "token: ta") {
+		t.Fatalf("cancelled remove must not write:\n%s", data)
+	}
+}
+
+func TestLoginUnknownSubcommandUsage(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "")
+	_, stderr, code := run(append(prefix, "login", "bogus")...)
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 {
+		t.Fatalf("want exit 2 (README usage), got %d", code)
+	}
+	if !strings.Contains(stderr, "unknown login subcommand") {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginNoSubcommandUsage(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "")
+	_, stderr, code := run(append(prefix, "login")...)
+	// 對照 README「輸出與結束碼」：用法錯誤＝2（#10）。
+	if code != 2 {
+		t.Fatalf("want exit 2 (README usage), got %d", code)
+	}
+	if !strings.Contains(stderr, "subcommand") {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginRemoveNotFound(t *testing.T) {
+	prefix, _ := loginTestEnv(t, "logins: []\n")
+	_, stderr, code := run(append(prefix, "login", "remove", "--yes", "ghost")...)
+	// ExitInternal 不在 README 保證範圍；此處固定為 1（內部錯誤，#10）。
+	if code != 1 {
+		t.Fatalf("want exit 1 (internal), got %d", code)
+	}
+	if !strings.Contains(stderr, `login "ghost" not found`) {
+		t.Fatalf("stderr: %s", stderr)
+	}
+}
+
+func TestLoginRegisteredInUsage(t *testing.T) {
+	stdout, _, code := run()
+	if code != 0 || !strings.Contains(stdout, "login") {
+		t.Fatalf("usage should list login: %s", stdout)
+	}
+}

internal/cli/stalled_commands.go

@@ -0,0 +1,170 @@
+// stalled_commands.go — 管理者巡邏命令的 CLI 接線（#7）：
+// stalled [--hours N] 與 xrefs <owner>/<repo> <number>。
+//
+// 核心邏輯在 internal/workflow（ScanStalled／ResolveIssueXrefs），
+// 本檔只做旗標剖析、資料源接線與輸出格式化。輸出走得體架構的
+// Printer（--output json|table）；錯誤經 cli.exitCodeFor 映射結束碼
+// （用法 2／API 3）。token 解析選序見 internal/gitea/auth.go。
+package cli
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"strconv"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+func init() {
+	commands["stalled"] = &command{
+		name:  "stalled",
+		usage: "停滯的 open issues／PR（管理者巡邏；--hours N 門檻，預設 4）",
+		run:   runStalled,
+	}
+	commands["xrefs"] = &command{
+		name:  "xrefs",
+		usage: "解析 issue／PR 內文與留言中的 #N／repo#N／owner/repo#N 引用",
+		run:   runXrefs,
+	}
+}
+
+// newStalledSourceFunc 建立 stalled／xrefs 的資料源；宣告為變數讓
+// 接線層測試可注入假資料源（不走網路），與 newScannerFunc 同模式。
+var newStalledSourceFunc = newStalledSource
+
+// newStalledSource 依全域選項建立 workflow.StalledSource（API 實作）。
+func newStalledSource(env *Env) (workflow.StalledSource, error) {
+	token, _, err := gitea.ResolveToken(gitea.AuthOptions{
+		FlagToken:  env.Globals.Token,
+		SiteURL:    env.Globals.URL,
+		ConfigPath: env.Globals.ConfigPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+	client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout)
+	if err != nil {
+		return nil, err
+	}
+	return &workflow.APIClient{Client: client}, nil
+}
+
+// stalledFields 是 stalled 的 table 欄位（JSON 模式輸出完整 Item，
+// 欄位序與 gitea.py 一致，見 workflow.Item.MarshalJSON）。
+func stalledFields() []gitea.Field {
+	return []gitea.Field{
+		{Name: "type"}, {Name: "repo"}, {Name: "number"}, {Name: "title"},
+		{Name: "last_comment_by"}, {Name: "last_activity_at"},
+		{Name: "stalled_hours"}, {Name: "reason"},
+	}
+}
+
+// stalledRow 把 Item 轉成 table 列（assignees／reviewers／child_activity
+// 僅 JSON 模式輸出；table 給人工抽查用，取共同欄位）。
+// stalled_hours 定點一位小數（fmt.Sprint(9.0) 會印 "9"，與 JSON 的 9.0 不一致）。
+func stalledRow(item workflow.Item) gitea.Values {
+	return gitea.Values{
+		item.Type, item.Repo, item.Number, item.Title,
+		item.LastCommentBy, workflow.FormatMoment(item.LastActivityAt),
+		strconv.FormatFloat(item.StalledHours, 'f', 1, 64), item.Reason,
+	}
+}
+
+// runStalled：teai stalled [--hours N]。
+// 預設門檻 4 小時；--hours 需為正數（同 gitea.py _parse_hours）。
+// JSON 輸出與 gitea.py stalled 位元組相容（workflow.Item 自訂 MarshalJSON；
+// 這裡輸出前停用 HTML 轉義並縮排 2，對應 Python json.dumps(indent=2)）。
+func runStalled(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai stalled", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	hours := fs.Float64("hours", workflow.StalledDefaultHours, "停滯門檻（小時，正數）")
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 0 {
+		return &ErrUsage{Msg: "stalled 不接受位置參數"}
+	}
+	if *hours <= 0 {
+		return &ErrUsage{Msg: "--hours 需為正數（小時），例如 --hours 4"}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	items, err := workflow.RunStalled(src, *hours, nowFunc())
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	if p.Format == gitea.FormatTable {
+		rows := make([]gitea.Values, 0, len(items))
+		for _, item := range items {
+			rows = append(rows, stalledRow(item))
+		}
+		return p.PrintList(stalledFields(), rows)
+	}
+	// JSON：空清單輸出 []（README：無停滯項目 → 空陣列）；有項目時
+	// 縮排 2 且停用 HTML 轉義，與 gitea.py 的 _dump 位元組相容。
+	if len(items) == 0 {
+		_, err := fmt.Fprintln(env.Out, "[]")
+		return err
+	}
+	return printJSON(env.Out, items)
+}
+
+// runXrefs：teai xrefs <owner>/<repo> <number>。
+// 編號不存在 → API 錯誤（結束碼 3）；無引用 → []。
+func runXrefs(env *Env, args []string) error {
+	fs := flag.NewFlagSet("teai xrefs", flag.ContinueOnError)
+	fs.SetOutput(env.Err)
+	if err := parseFlags(fs, args); err != nil {
+		return err
+	}
+	if fs.NArg() != 2 {
+		return &ErrUsage{Msg: "xrefs 需要 <owner>/<repo> <number> 兩個參數"}
+	}
+	owner, name, err := splitRepoFlag(args[0])
+	if err != nil {
+		return err
+	}
+	number, err := strconv.ParseInt(args[1], 10, 64)
+	if err != nil || number <= 0 {
+		return &ErrUsage{Msg: fmt.Sprintf("編號需為正整數，得到 %q", args[1])}
+	}
+	src, err := newStalledSourceFunc(env)
+	if err != nil {
+		return err
+	}
+	hits, err := workflow.ResolveIssueXrefs(src, owner, name, number)
+	if err != nil {
+		return err
+	}
+	p := printer(env)
+	rows := make([]gitea.Values, 0, len(hits))
+	for _, h := range hits {
+		rows = append(rows, gitea.Values{h.Owner, h.Repo, h.Number, h.Source})
+	}
+	return p.PrintList(
+		[]gitea.Field{
+			{Name: "owner"}, {Name: "repo"}, {Name: "number"}, {Name: "source"},
+		},
+		rows,
+	)
+}
+
+// nowFunc 回傳目前時刻；宣告為變數讓測試可固定時刻（stalled 判定用）。
+var nowFunc = time.Now
+
+// printJSON 以縮排 2、停用 HTML 轉義輸出 JSON（與 gitea.py 的
+// json.dumps(ensure_ascii=False, indent=2) 位元組相容；HTML 轉義會把
+// <、>、& 變 \u003c 等，破壞相容性）。
+func printJSON(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	return enc.Encode(v)
+}

internal/cli/stalled_commands_test.go

@@ -0,0 +1,227 @@
+// stalled_commands_test.go — stalled／xrefs CLI 接線層測試（#7）：
+// 注入假 StalledSource，驗證 Run→dispatch→flagset 完整路徑，
+// 不走網路（與 workflow_commands_test.go 同模式）。
+package cli
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.alterminal.com/alterminal/teai/internal/gitea"
+	"gitea.alterminal.com/alterminal/teai/internal/workflow"
+)
+
+// stubStalledSource 以記憶體資料實作 workflow.StalledSource。
+type stubStalledSource struct {
+	username string
+	orgs     []string
+	repos    map[string][]workflow.Repo
+	issues   map[string]map[int64]workflow.Issue
+	comments map[string][]workflow.Comment
+	getErr   error
+}
+
+func (s *stubStalledSource) CurrentUser() (string, error) { return s.username, nil }
+func (s *stubStalledSource) MyOrganizations() ([]string, error) {
+	return s.orgs, nil
+}
+func (s *stubStalledSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+	return s.repos[org], nil
+}
+func (s *stubStalledSource) OpenIssues(owner, repo string) ([]workflow.Issue, error) {
+	var out []workflow.Issue
+	for _, i := range s.issues[owner+"/"+repo] {
+		out = append(out, i)
+	}
+	return out, nil
+}
+func (s *stubStalledSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error) {
+	return nil, nil
+}
+func (s *stubStalledSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
+	return s.comments[owner+"/"+repo+"/"+itoa(number)], nil
+}
+func (s *stubStalledSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
+	i, ok := s.issues[owner+"/"+repo][number]
+	return i, ok, nil
+}
+func (s *stubStalledSource) GetIssue(owner, repo string, number int64) (workflow.Issue, error) {
+	if s.getErr != nil {
+		return workflow.Issue{}, s.getErr
+	}
+	i, ok := s.issues[owner+"/"+repo][number]
+	if !ok {
+		return workflow.Issue{}, &gitea.ErrAPI{Op: "GET /repos/" + owner + "/" + repo + "/issues/" + itoa(number), StatusCode: 404}
+	}
+	return i, nil
+}
+
+func itoa(n int64) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+// newStubStalledEnv 注入假資料源並固定時刻。
+func newStubStalledEnv(t *testing.T, src *stubStalledSource, frozen time.Time) {
+	t.Helper()
+	origSrc, origNow := newStalledSourceFunc, nowFunc
+	newStalledSourceFunc = func(env *Env) (workflow.StalledSource, error) { return src, nil }
+	nowFunc = func() time.Time { return frozen }
+	t.Cleanup(func() { newStalledSourceFunc, nowFunc = origSrc, origNow })
+}
+
+// isoAt 把相對分鐘轉成 ISO8601 字串（假資料用；錨點同 workflow 測試）。
+func isoAt(minutes int) string {
+	return workflow.FormatMoment(time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC).Add(time.Duration(minutes) * time.Minute))
+}
+
+// newStubStalledData 建構 stalled 情境：agents#1 停滯 10 小時（no-assignee）。
+func newStubStalledData() *stubStalledSource {
+	return &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {{Name: "agents"}}},
+		issues: map[string]map[int64]workflow.Issue{
+			"alterminal/agents": {
+				1: {Number: 1, Title: "停滯項", State: "open",
+					CreatedAt: isoAt(-600), UpdatedAt: isoAt(-600),
+					Repository: &workflow.Repository{FullName: "alterminal/agents"}},
+			},
+		},
+		comments: map[string][]workflow.Comment{},
+	}
+}
+
+// TestWiringStalled 驗證 stalled 基本路徑：JSON 輸出含停滯欄位。
+func TestWiringStalled(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled")
+	if code != 0 {
+		t.Fatalf("stalled 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	for _, want := range []string{`"type": "issue"`, `"reason": "no-assignee"`, `"stalled_hours": 10.0`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("stalled 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringStalledHoursFlag 驗證 --hours 覆寫門檻與非正數被攔。
+func TestWiringStalledHoursFlag(t *testing.T) {
+	freeze := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
+	newStubStalledEnv(t, newStubStalledData(), freeze)
+	// 門檻 20h → 10h 停滯未過門檻 → 空陣列。
+	stdout, _, code := run("stalled", "--hours", "20")
+	if code != 0 {
+		t.Fatalf("stalled --hours 20 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無停滯項應輸出 []，得到 %q", stdout)
+	}
+	// 非正數 → exit 2。
+	_, stderr, code := run("stalled", "--hours", "-1")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled --hours -1 應回 ExitUsage(%d)，得到 %d（stderr=%q）", int(ExitUsage), code, stderr)
+	}
+	// 位置參數 → exit 2。
+	_, _, code = run("stalled", "extra")
+	if code != int(ExitUsage) {
+		t.Fatalf("stalled extra 應回 ExitUsage(%d)，得到 %d", int(ExitUsage), code)
+	}
+}
+
+// TestWiringStalledTable 驗證 table 輸出（README 範例）。
+func TestWiringStalledTable(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("stalled", "--output", "table")
+	if code != 0 {
+		t.Fatalf("stalled --output table 應回 0，得到 %d", code)
+	}
+	for _, want := range []string{"reason", "no-assignee", "停滯項"} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("table 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefs 驗證 xrefs 解析輸出（含 body／comment 出處）。
+func TestWiringXrefs(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "父項", State: "open",
+		Body: "子項：agents#2",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.issues["alterminal/agents"][2] = workflow.Issue{
+		Number: 2, Title: "子項", State: "open",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	src.comments["alterminal/agents/1"] = []workflow.Comment{
+		{Body: "看 agents#2", User: &workflow.User{UserName: "alex"}},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d（stdout=%q）", code, stdout)
+	}
+	// Printer JSON 為單行緊湊格式（無縮排）；命令清單類輸出一律如此。
+	for _, want := range []string{`"repo":"agents"`, `"number":2`, `"source":"body"`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("xrefs 輸出應含 %q，得到：\n%s", want, stdout)
+		}
+	}
+}
+
+// TestWiringXrefsEmpty 驗證無引用 → []。
+func TestWiringXrefsEmpty(t *testing.T) {
+	src := newStubStalledData()
+	src.issues["alterminal/agents"][1] = workflow.Issue{
+		Number: 1, Title: "無引用", State: "open",
+		Body: "沒有任何引用",
+		Repository: &workflow.Repository{FullName: "alterminal/agents"},
+	}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	stdout, _, code := run("xrefs", "alterminal/agents", "1")
+	if code != 0 {
+		t.Fatalf("xrefs 應回 0，得到 %d", code)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("無引用應輸出 []，得到 %q", stdout)
+	}
+}
+
+// TestWiringXrefsUsage 驗證參數不足／格式錯誤 → exit 2。
+func TestWiringXrefsUsage(t *testing.T) {
+	newStubStalledEnv(t, newStubStalledData(), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	if _, _, code := run("xrefs"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 無參數應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 缺編號應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "not-a-repo", "1"); code != int(ExitUsage) {
+		t.Fatalf("xrefs repo 格式錯誤應回 ExitUsage，得到 %d", code)
+	}
+	if _, _, code := run("xrefs", "alterminal/agents", "abc"); code != int(ExitUsage) {
+		t.Fatalf("xrefs 編號非數字應回 ExitUsage，得到 %d", code)
+	}
+}
+
+// TestWiringXrefsNotFound 驗證 404 → exit 3（API 錯誤）。
+func TestWiringXrefsNotFound(t *testing.T) {
+	src := newStubStalledData()
+	src.getErr = &gitea.ErrAPI{Op: "GET /repos/alterminal/agents/issues/99", StatusCode: 404}
+	newStubStalledEnv(t, src, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC))
+	_, stderr, code := run("xrefs", "alterminal/agents", "99")
+	if code != int(ExitAPI) {
+		t.Fatalf("xrefs 404 應回 ExitAPI(%d)，得到 %d（stderr=%q）", int(ExitAPI), code, stderr)
+	}
+}

internal/cli/workflow_commands.go

@@ -31,6 +31,11 @@ func init() {
 // 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{
@@ -58,7 +63,7 @@ func runWhoami(env *Env, args []string) error {
 	if len(args) != 0 {
 		return &ErrUsage{Msg: "whoami 不接受參數"}
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}
@@ -77,7 +82,7 @@ func runOrgs(env *Env, args []string) error {
 	if len(args) != 0 {
 		return &ErrUsage{Msg: "orgs 不接受參數"}
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}
@@ -100,13 +105,13 @@ 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 {
+	if err := parseFlags(fs, args); err != nil {
-		return &ErrUsage{Msg: err.Error()}
+		return err
 	}
 	if fs.NArg() != 0 {
 		return &ErrUsage{Msg: "members 不接受位置參數"}
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}
@@ -126,7 +131,7 @@ func runMine(env *Env, args []string) error {
 	if len(args) != 0 {
 		return &ErrUsage{Msg: "mine 不接受參數"}
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}
@@ -149,8 +154,8 @@ func runPulls(env *Env, args []string) error {
 	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 {
+	if err := parseFlags(fs, args); err != nil {
-		return &ErrUsage{Msg: err.Error()}
+		return err
 	}
 	if fs.NArg() != 0 {
 		return &ErrUsage{Msg: "pulls 不接受位置參數"}
@@ -166,7 +171,7 @@ func runPulls(env *Env, args []string) error {
 		}
 		owner, name = parts[0], parts[1]
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}
@@ -199,7 +204,7 @@ func runNext(env *Env, args []string) error {
 	if len(args) != 0 {
 		return &ErrUsage{Msg: "next 不接受參數"}
 	}
-	s, err := newWorkflowClient(env)
+	s, err := newScannerFunc(env)
 	if err != nil {
 		return err
 	}

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/config.go

@@ -0,0 +1,421 @@
+// config.go — tea 相容登入組態的讀取與行級編輯。
+//
+// teai 與 tea 共用同一份組態檔（README 設計原則 5），因此寫入採「行級編輯」：
+// 只修改目標登入項目的所屬行，其餘內容（未知欄位、註解、preferences 區段、
+// 空行與縮排）逐字保留，避免改壞 tea 也在使用的檔案。新增項目依 tea 實際
+// 寫出的欄位順序輸出，讓檔案外觀與 tea 一致。
+//
+// token 值只會進出這個套件的資料結構與組態檔本身，永遠不出現在錯誤訊息。
+package gitea
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// LoginEntry 是組態檔中的一筆登入資料（編輯用，含 tea 的 user 欄位）。
+type LoginEntry struct {
+	Name    string
+	URL     string
+	Token   string
+	Default bool
+	User    string
+}
+
+// loginItemSpan 標記 logins 清單中一個項目在檔案中的行範圍 [start, end)。
+type loginItemSpan struct {
+	name  string
+	start int
+	end   int
+}
+
+// configDoc 是解析後的組態檔：原始行與 logins 項目的位置資訊。
+type configDoc struct {
+	lines        []string
+	items        []loginItemSpan
+	loginsHeader int    // 「logins:」所在行；-1 表示沒有
+	itemIndent   string // 項目行的縮排（取第一個項目）；預設四格空白
+}
+
+// parseConfigDoc 掃描組態內容，定位 logins 清單與各項目的行範圍。
+// 只認識 tea 實際寫出的格式：頂層 `logins:` 加縮排的 `- key: value` 項目；
+// 其餘行原樣保留在 lines 中。
+func parseConfigDoc(data []byte) configDoc {
+	doc := configDoc{lines: splitLines(data), loginsHeader: -1, itemIndent: "    "}
+	inLogins := false
+	cur := -1
+	for i, raw := range doc.lines {
+		line := raw
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		indent := line[:len(line)-len(strings.TrimLeft(line, " "))]
+		if indent == "" {
+			if inLogins && doc.loginsHeader >= 0 {
+				// 離開 logins 區段；listEnd 由最後一個項目的 end 決定，這裡不用記。
+			}
+			inLogins = strings.HasPrefix(trimmed, "logins:")
+			if inLogins && doc.loginsHeader < 0 {
+				doc.loginsHeader = i
+			}
+			cur = -1
+			continue
+		}
+		if !inLogins {
+			continue
+		}
+		if strings.HasPrefix(trimmed, "- ") || trimmed == "-" {
+			if cur >= 0 {
+				doc.items[cur].end = i
+			}
+			doc.items = append(doc.items, loginItemSpan{start: i, end: i + 1})
+			cur = len(doc.items) - 1
+			if len(doc.items) == 1 {
+				doc.itemIndent = indent
+			}
+			if rest := strings.TrimSpace(strings.TrimPrefix(trimmed, "-")); rest != "" {
+				if key, value, ok := strings.Cut(rest, ":"); ok && strings.TrimSpace(key) == "name" {
+					doc.items[cur].name = unquoteYAML(strings.TrimSpace(value))
+				}
+			}
+			continue
+		}
+		if cur >= 0 {
+			doc.items[cur].end = i + 1
+		}
+	}
+	return doc
+}
+
+// findItem 依名稱找項目；找不到回 -1。
+func (d configDoc) findItem(name string) int {
+	for i, it := range d.items {
+		if it.name == name {
+			return i
+		}
+	}
+	return -1
+}
+
+// fieldIndent 回傳項目內屬性行的縮排（項目縮排 + 兩格，tea 的格式）。
+func (d configDoc) fieldIndent() string {
+	return d.itemIndent + "  "
+}
+
+// entryAt 取某個項目的完整欄位值。
+func (d configDoc) entryAt(it loginItemSpan) LoginEntry {
+	var e LoginEntry
+	apply := func(kv string) {
+		key, value, ok := strings.Cut(kv, ":")
+		if !ok {
+			return
+		}
+		key = strings.TrimSpace(key)
+		value = unquoteYAML(strings.TrimSpace(value))
+		switch key {
+		case "name":
+			e.Name = value
+		case "url":
+			e.URL = value
+		case "token":
+			e.Token = value
+		case "default":
+			e.Default = value == "true"
+		case "user":
+			e.User = value
+		}
+	}
+	first := strings.TrimSpace(d.lines[it.start])
+	if rest := strings.TrimSpace(strings.TrimPrefix(first, "-")); rest != "" {
+		apply(rest)
+	}
+	for i := it.start + 1; i < it.end; i++ {
+		if kv := strings.TrimSpace(d.lines[i]); kv != "" && !strings.HasPrefix(kv, "#") {
+			apply(kv)
+		}
+	}
+	return e
+}
+
+// ListLogins 回傳組態內容中的所有登入（依檔案順序）。
+func ListLogins(data []byte) []LoginEntry {
+	doc := parseConfigDoc(data)
+	out := make([]LoginEntry, 0, len(doc.items))
+	for _, it := range doc.items {
+		out = append(out, doc.entryAt(it))
+	}
+	return out
+}
+
+// ListLoginsFile 讀取組態檔並列出登入；檔案不存在視為空清單（非錯誤）。
+func ListLoginsFile(path string) ([]LoginEntry, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return ListLogins(data), nil
+}
+
+// UpsertLogin 新增或更新名為 e.Name 的登入。
+//
+// 已存在則就地更新 url/token/user/default（保留其他欄位與行）；不存在則
+// 依 tea 的欄位順序插入新項目。makeDefault 為 true 時將其設為預設並取消
+// 其他登入的預設旗標；新增後若成為唯一登入也自動成為預設。
+// 回傳新內容與最終生效的項目值。
+func UpsertLogin(data []byte, e LoginEntry, makeDefault bool) ([]byte, LoginEntry, error) {
+	if strings.TrimSpace(e.Name) == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login name must not be empty")
+	}
+	if strings.TrimSpace(e.URL) == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login url must not be empty")
+	}
+	if e.Token == "" {
+		return nil, LoginEntry{}, fmt.Errorf("gitea: login token must not be empty")
+	}
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(e.Name)
+	if idx >= 0 {
+		existing := doc.entryAt(doc.items[idx])
+		wantDefault := existing.Default || makeDefault
+		it := doc.items[idx]
+		lines := doc.lines
+		// 就地替換各欄位；缺少的欄位補在項目結尾。
+		for _, kv := range []struct{ key, value string }{
+			{"name", yamlScalar(e.Name)},
+			{"url", yamlScalar(e.URL)},
+			{"token", yamlScalar(e.Token)},
+			{"user", yamlScalar(e.User)},
+			{"default", strconv.FormatBool(wantDefault)},
+		} {
+			lines = setFieldInItem(lines, it, kv.key, kv.value, doc.fieldIndent())
+		}
+		out := joinLines(lines)
+		if wantDefault {
+			var err error
+			out, err = SetDefaultLogin(out, e.Name)
+			if err != nil {
+				return nil, LoginEntry{}, err
+			}
+		}
+		final := existing
+		final.URL, final.Token, final.User = e.URL, e.Token, e.User
+		final.Default = wantDefault
+		return out, final, nil
+	}
+
+	// 新增項目。
+	wantDefault := makeDefault || len(doc.items) == 0
+	block := newLoginBlock(doc.itemIndent, e.Name, e.URL, e.Token, wantDefault, e.User)
+	var lines []string
+	var insertAt int
+	if doc.loginsHeader < 0 {
+		if len(doc.lines) == 0 {
+			lines = []string{"logins:"}
+		} else {
+			lines = append(slices.Clone(doc.lines), "", "logins:")
+		}
+		insertAt = len(lines)
+	} else {
+		lines = slices.Clone(doc.lines)
+		// 「logins: []」是空清單的串流寫法，直接接項目會變無效 YAML；改回區段寫法。
+		if len(doc.items) == 0 && strings.TrimSpace(lines[doc.loginsHeader]) == "logins: []" {
+			lines[doc.loginsHeader] = "logins:"
+		}
+		if len(doc.items) > 0 {
+			insertAt = doc.items[len(doc.items)-1].end
+		} else {
+			insertAt = doc.loginsHeader + 1
+		}
+	}
+	out := append(slices.Clone(lines[:insertAt]), block...)
+	out = append(out, lines[insertAt:]...)
+	data2 := joinLines(out)
+	if wantDefault {
+		var err error
+		data2, err = SetDefaultLogin(data2, e.Name)
+		if err != nil {
+			return nil, LoginEntry{}, err
+		}
+	}
+	return data2, LoginEntry{
+		Name:    e.Name,
+		URL:     e.URL,
+		Token:   e.Token,
+		Default: wantDefault,
+		User:    e.User,
+	}, nil
+}
+
+// SetDefaultLogin 把名為 name 的登入設為預設，其餘一律取消預設。
+func SetDefaultLogin(data []byte, name string) ([]byte, error) {
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(name)
+	if idx < 0 {
+		return nil, fmt.Errorf("gitea: login %q not found", name)
+	}
+	lines := doc.lines
+	// 反序處理：前面的插入不影響後面已算好的行範圍，這裡的反序則保證
+	// 後方項目的插入/修改不會推移前方項目的範圍。
+	for i := len(doc.items) - 1; i >= 0; i-- {
+		want := "false"
+		if i == idx {
+			want = "true"
+		}
+		lines = setFieldInItem(lines, doc.items[i], "default", want, doc.fieldIndent())
+	}
+	return joinLines(lines), nil
+}
+
+// RemoveLogin 移除名為 name 的登入。若被移除者是預設且還有其他登入，
+// 剩下的第一筆自動遞補為預設。回傳新內容與遞補後的預設名稱（無則空字串）。
+func RemoveLogin(data []byte, name string) ([]byte, string, error) {
+	doc := parseConfigDoc(data)
+	idx := doc.findItem(name)
+	if idx < 0 {
+		return nil, "", fmt.Errorf("gitea: login %q not found", name)
+	}
+	removed := doc.entryAt(doc.items[idx])
+	it := doc.items[idx]
+	lines := slices.Delete(slices.Clone(doc.lines), it.start, it.end)
+	out := joinLines(lines)
+	promoted := ""
+	if removed.Default {
+		rest := ListLogins(out)
+		if len(rest) > 0 {
+			promoted = rest[0].Name
+			var err error
+			out, err = SetDefaultLogin(out, promoted)
+			if err != nil {
+				return nil, "", err
+			}
+		}
+	}
+	return out, promoted, nil
+}
+
+// setFieldInItem 把項目內 key 的值換成 value，保留該行的原始縮排；
+// key 不存在時以 fieldIndent 插在項目結尾。回傳新的行切片。
+func setFieldInItem(lines []string, it loginItemSpan, key, value, fieldIndent string) []string {
+	first := lines[it.start]
+	trimmed := strings.TrimSpace(first)
+	if rest := strings.TrimSpace(strings.TrimPrefix(trimmed, "-")); rest != "" {
+		if k, _, ok := strings.Cut(rest, ":"); ok && strings.TrimSpace(k) == key {
+			prefix := first[:strings.Index(first, "-")] + "- "
+			lines[it.start] = prefix + key + ": " + value
+			return lines
+		}
+	}
+	for i := it.start + 1; i < it.end; i++ {
+		t := strings.TrimSpace(lines[i])
+		if k, _, ok := strings.Cut(t, ":"); ok && strings.TrimSpace(k) == key {
+			indent := lines[i][:len(lines[i])-len(strings.TrimLeft(lines[i], " "))]
+			lines[i] = indent + key + ": " + value
+			return lines
+		}
+	}
+	out := append(slices.Clone(lines[:it.end]), fieldIndent+key+": "+value)
+	return append(out, lines[it.end:]...)
+}
+
+// newLoginBlock 產生 tea 格式的新登入項目（欄位順序與 tea 實際寫出的一致）。
+func newLoginBlock(itemIndent, name, url, token string, isDefault bool, user string) []string {
+	f := itemIndent + "  "
+	return []string{
+		itemIndent + "- name: " + yamlScalar(name),
+		f + "url: " + yamlScalar(url),
+		f + "token: " + yamlScalar(token),
+		f + "default: " + strconv.FormatBool(isDefault),
+		f + `ssh_host: ""`,
+		f + `ssh_key: ""`,
+		f + "insecure: false",
+		f + `ssh_certificate_principal: ""`,
+		f + "ssh_agent: false",
+		f + `ssh_key_agent_pub: ""`,
+		f + "version_check: false",
+		f + "user: " + yamlScalar(user),
+		f + "created: 0",
+	}
+}
+
+// plainScalar 是可以不加引號直接寫出的 YAML 純量。
+var plainScalar = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:/~+=@-]*$`)
+
+// yamlScalar 把值寫成 YAML 純量：安全字元集直接輸出，其餘加雙引號。
+func yamlScalar(s string) string {
+	if plainScalar.MatchString(s) {
+		return s
+	}
+	return strconv.Quote(s)
+}
+
+// HostOf 取 URL 的主機部分（連埠，小寫）；解析失敗回空字串。
+// 供比對「同一站點」的登入時使用。
+func HostOf(rawURL string) string { return hostOf(rawURL) }
+
+// splitLines 把內容拆成行（去掉行尾換行與 CR）。
+func splitLines(data []byte) []string {
+	if len(data) == 0 {
+		return nil
+	}
+	s := strings.TrimSuffix(string(data), "\n")
+	if s == "" {
+		return []string{""}
+	}
+	return strings.Split(s, "\n")
+}
+
+// joinLines 把行組回內容，保證以單一換行結尾。
+func joinLines(lines []string) []byte {
+	if len(lines) == 0 {
+		return nil
+	}
+	s := strings.Join(lines, "\n")
+	if !strings.HasSuffix(s, "\n") {
+		s += "\n"
+	}
+	return []byte(s)
+}
+
+// SaveTeaConfigFile 把組態內容原子寫入 path：先寫同目錄暫存檔（0600），
+// 再 rename 取代，避免半寫入狀態。必要時建立上層目錄（0700）。
+func SaveTeaConfigFile(path string, data []byte) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return fmt.Errorf("gitea: create config dir: %w", err)
+	}
+	tmp, err := os.CreateTemp(dir, ".config-*.yml")
+	if err != nil {
+		return fmt.Errorf("gitea: create temp file: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer func() {
+		if tmpName != "" {
+			_ = os.Remove(tmpName)
+		}
+	}()
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return fmt.Errorf("gitea: write temp file: %w", err)
+	}
+	if err := tmp.Chmod(0o600); err != nil {
+		tmp.Close()
+		return fmt.Errorf("gitea: chmod temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("gitea: close temp file: %w", err)
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		return fmt.Errorf("gitea: rename config: %w", err)
+	}
+	tmpName = "" // 已改名成功，不必清理。
+	return nil
+}

internal/gitea/config_test.go

@@ -0,0 +1,263 @@
+// config_test.go 驗證 tea 相容組態的行級編輯：新增、更新、設預設、
+// 移除，以及「未知欄位與其他區段逐字保留」的關鍵性質。
+package gitea
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// realWorldTeaConfig 是 tea 實際寫出的組態（含 ssh_* 等未知欄位與 preferences）。
+const realWorldTeaConfig = `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: tok-1
+      default: true
+      ssh_host: ""
+      ssh_key: ""
+      insecure: false
+      ssh_certificate_principal: ""
+      ssh_agent: false
+      ssh_key_agent_pub: ""
+      version_check: false
+      user: ceo
+      created: 0
+preferences:
+    editor: false
+    flag_defaults:
+        remote: ""
+`
+
+func TestListLoginsParsesAllEntries(t *testing.T) {
+	logins := ListLogins([]byte(realWorldTeaConfig))
+	if len(logins) != 1 {
+		t.Fatalf("want 1 login, got %d", len(logins))
+	}
+	l := logins[0]
+	if l.Name != "alterminal" || l.URL != "https://gitea.alterminal.com" || l.Token != "tok-1" || !l.Default || l.User != "ceo" {
+		t.Fatalf("unexpected entry: %+v", l)
+	}
+}
+
+func TestUpsertLoginUpdatesExistingPreservesRest(t *testing.T) {
+	out, final, err := UpsertLogin([]byte(realWorldTeaConfig), LoginEntry{
+		Name: "alterminal", URL: "https://gitea.alterminal.com", Token: "tok-2", User: "ceo",
+	}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(out)
+	// 更新 token、保留其他欄位。
+	if !strings.Contains(s, "token: tok-2") || strings.Contains(s, "tok-1") {
+		t.Fatalf("token not updated:\n%s", s)
+	}
+	for _, want := range []string{
+		"ssh_host: \"\"", "insecure: false", "ssh_key_agent_pub: \"\"",
+		"user: ceo", "created: 0", "default: true",
+		"preferences:", "editor: false", "flag_defaults:", `remote: ""`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Fatalf("missing %q after edit:\n%s", want, s)
+		}
+	}
+	if final.Default != true {
+		t.Fatalf("existing default should stay default, got %+v", final)
+	}
+	// 編輯後仍可解析出正確值。
+	logins := ListLogins(out)
+	if len(logins) != 1 || logins[0].Token != "tok-2" || !logins[0].Default {
+		t.Fatalf("reparse mismatch: %+v", logins)
+	}
+}
+
+func TestUpsertLoginAppendsNewAndMakesDefault(t *testing.T) {
+	out, final, err := UpsertLogin([]byte(realWorldTeaConfig), LoginEntry{
+		Name: "second", URL: "https://git.example.com", Token: "tok-b", User: "bob",
+	}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 2 {
+		t.Fatalf("want 2 logins, got %d:\n%s", len(logins), out)
+	}
+	if logins[0].Default || !logins[1].Default {
+		t.Fatalf("only the new login should be default: %+v", logins)
+	}
+	if logins[1].Name != "second" || logins[1].Token != "tok-b" || logins[1].User != "bob" {
+		t.Fatalf("new entry mismatch: %+v", logins[1])
+	}
+	if !final.Default {
+		t.Fatalf("final should be default: %+v", final)
+	}
+	// tea 的欄位順序仍在。
+	s := string(out)
+	if !strings.Contains(s, "    - name: second\n") {
+		t.Fatalf("new item not appended in tea style:\n%s", s)
+	}
+}
+
+func TestUpsertLoginFirstEverLoginCreatesSection(t *testing.T) {
+	out, final, err := UpsertLogin(nil, LoginEntry{
+		Name: "only", URL: "https://gitea.alterminal.com", Token: "tok", User: "ceo",
+	}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 1 || !logins[0].Default || logins[0].Token != "tok" {
+		t.Fatalf("first login should auto-default: %s", out)
+	}
+	if !final.Default {
+		t.Fatalf("final should be default: %+v", final)
+	}
+	if !strings.HasPrefix(string(out), "logins:\n") {
+		t.Fatalf("section not created:\n%s", out)
+	}
+}
+
+func TestUpsertLoginRejectsBadInput(t *testing.T) {
+	cases := []LoginEntry{
+		{Name: "", URL: "https://x", Token: "t"},
+		{Name: "n", URL: "  ", Token: "t"},
+		{Name: "n", URL: "https://x", Token: ""},
+	}
+	for _, e := range cases {
+		if _, _, err := UpsertLogin(nil, e, true); err == nil {
+			t.Errorf("UpsertLogin(%+v) should fail", e)
+		}
+	}
+}
+
+func TestSetDefaultLoginSwitchesFlag(t *testing.T) {
+	cfg := `logins:
+    - name: a
+      url: https://a.example.com
+      token: ta
+      default: true
+    - name: b
+      url: https://b.example.com
+      token: tb
+      default: false
+`
+	out, err := SetDefaultLogin([]byte(cfg), "b")
+	if err != nil {
+		t.Fatal(err)
+	}
+	logins := ListLogins(out)
+	if logins[0].Default || !logins[1].Default {
+		t.Fatalf("default flag not switched:\n%s", out)
+	}
+	// b 之後的內容（如有）不受影響。
+	if !strings.Contains(string(out), "token: ta") || !strings.Contains(string(out), "token: tb") {
+		t.Fatalf("tokens lost:\n%s", out)
+	}
+}
+
+func TestSetDefaultLoginUnknownNameErrors(t *testing.T) {
+	if _, err := SetDefaultLogin([]byte(realWorldTeaConfig), "nope"); err == nil {
+		t.Fatal("unknown name should error")
+	}
+}
+
+func TestRemoveLoginPromotesNextDefault(t *testing.T) {
+	// 第二個登入放在 logins 區段內（preferences 之前）。
+	cfg := `logins:
+    - name: alterminal
+      url: https://gitea.alterminal.com
+      token: tok-1
+      default: true
+      user: ceo
+    - name: backup
+      url: https://backup.example.com
+      token: tb
+      default: false
+preferences:
+    editor: false
+`
+	out, promoted, err := RemoveLogin([]byte(cfg), "alterminal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if promoted != "backup" {
+		t.Fatalf("promoted = %q, want backup:\n%s", promoted, out)
+	}
+	logins := ListLogins(out)
+	if len(logins) != 1 || logins[0].Name != "backup" || !logins[0].Default {
+		t.Fatalf("remaining login mismatch: %+v", logins)
+	}
+	if strings.Contains(string(out), "tok-1") || strings.Contains(string(out), "name: alterminal") {
+		t.Fatalf("login not fully removed:\n%s", out)
+	}
+}
+
+func TestRemoveLoginLastOne(t *testing.T) {
+	out, promoted, err := RemoveLogin([]byte(realWorldTeaConfig), "alterminal")
+	if err != nil || promoted != "" {
+		t.Fatalf("want clean removal, promoted=%q err=%v", promoted, err)
+	}
+	if strings.Contains(string(out), "alterminal") {
+		t.Fatalf("login not removed:\n%s", out)
+	}
+	if !strings.Contains(string(out), "preferences:") {
+		t.Fatalf("preferences section lost:\n%s", out)
+	}
+}
+
+func TestSaveTeaConfigFileAtomicAndMode(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tea", "config.yml")
+	if err := SaveTeaConfigFile(path, []byte("logins: []\n")); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm() != 0o600 {
+		t.Fatalf("perm = %v, want 0600", info.Mode().Perm())
+	}
+	// 再寫一次（覆蓋既有檔），不留暫存殘檔。
+	if err := SaveTeaConfigFile(path, []byte("logins: []\n# v2\n")); err != nil {
+		t.Fatal(err)
+	}
+	entries, _ := os.ReadDir(filepath.Dir(path))
+	if len(entries) != 1 {
+		for _, e := range entries {
+			t.Logf("leftover: %s", e.Name())
+		}
+		t.Fatalf("want exactly 1 file, got %d", len(entries))
+	}
+	data, _ := os.ReadFile(path)
+	if !bytes.Contains(data, []byte("# v2")) {
+		t.Fatalf("overwrite failed: %s", data)
+	}
+}
+
+func TestSplitJoinLinesRoundTrip(t *testing.T) {
+	original := "a\nb\n"
+	got := string(joinLines(splitLines([]byte(original))))
+	if got != original {
+		t.Fatalf("round trip: %q", got)
+	}
+	if joinLines(splitLines(nil)) != nil {
+		t.Fatal("nil input should stay nil")
+	}
+}
+
+func TestYamlScalarQuoting(t *testing.T) {
+	cases := map[string]string{
+		"https://gitea.alterminal.com": "https://gitea.alterminal.com", // 含 : 與 / 的純量在 YAML 合法，不必引號
+		"tok-abc_123":                  "tok-abc_123",
+		"has space":                    `"has space"`,
+		"ceo":                          "ceo",
+	}
+	for in, want := range cases {
+		if got := yamlScalar(in); got != want {
+			t.Errorf("yamlScalar(%q) = %s, want %s", in, got, want)
+		}
+	}
+}

internal/workflow/giteaapi.go

@@ -122,3 +122,56 @@ func (a *APIClient) ListComments(owner, repo string, number int64) ([]Comment, e
 	}
 	return comments, nil
 }
+
+// ── StalledSource 面向（#7 CLI 接線）────────────────────────────────────
+// APIClient 在 Client 之外同時實作 StalledSource（Source + CurrentUser +
+// GetIssue），讓 stalled／xrefs 命令與既有命令共用同一個 HTTP 用戶端。
+// 清單類方法直接委派 Client 同名操作，語義一致（type=issues、state=open）。
+
+// GetIssue 單一 issue 查詢（PR 亦經此端點，帶 pull_request 標記）；
+// 失敗（含 404）回 *gitea.ErrAPI，由 CLI 映射結束碼 3。
+func (a *APIClient) GetIssue(owner, repo string, number int64) (Issue, error) {
+	var issue Issue
+	path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) +
+		"/issues/" + strconv.FormatInt(number, 10)
+	if err := a.Client.GetJSON(context.Background(), path, &issue); err != nil {
+		return Issue{}, err
+	}
+	return issue, nil
+}
+
+// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)，
+// 供 stalled 父追蹤項掃描靜默略過不存在的子項（Source 介面契約）。
+func (a *APIClient) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
+	issue, err := a.GetIssue(owner, repo, number)
+	if err != nil {
+		return Issue{}, false, nil
+	}
+	return issue, true, nil
+}
+
+// MyOrganizations 委派 ListOrgs（Source 面向）。
+func (a *APIClient) MyOrganizations() ([]string, error) { return a.ListOrgs() }
+
+// OrganizationRepositories 委派 ListOrgRepos（Source 面向）。
+func (a *APIClient) OrganizationRepositories(org string) ([]Repo, error) {
+	return a.ListOrgRepos(org)
+}
+
+// OpenIssues 委派 ListIssues（Source 面向；已排除 PR）。
+func (a *APIClient) OpenIssues(owner, repo string) ([]Issue, error) {
+	return a.ListIssues(owner, repo)
+}
+
+// OpenPulls 委派 ListPulls（Source 面向）。
+func (a *APIClient) OpenPulls(owner, repo string) ([]PullRequest, error) {
+	return a.ListPulls(owner, repo)
+}
+
+// IssueComments 委派 ListComments（Source 面向）。
+func (a *APIClient) IssueComments(owner, repo string, number int64) ([]Comment, error) {
+	return a.ListComments(owner, repo, number)
+}
+
+// 編譯期確認 APIClient 同時實作 Client 與 StalledSource。
+var _ StalledSource = (*APIClient)(nil)

internal/workflow/scan.go

@@ -198,6 +198,16 @@ type orgIssue struct {
 	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) {
@@ -217,7 +227,7 @@ func (s *Scanner) collectMemberIssues(members []string) ([]orgIssue, error) {
 			if !AssigneeOverlaps(issue, members) {
 				continue
 			}
-			comments, err := s.Client.ListComments(owner, repo, issue.issueNumber())
+			comments, err := s.commentsFor(owner, repo, issue.issueNumber())
 			if err != nil {
 				return nil, err
 			}
@@ -275,7 +285,7 @@ func (s *Scanner) Pulls(mine, reviewer bool) ([]PullItem, error) {
 	for _, rp := range repoPulls {
 		for i := range rp.Pulls {
 			pr := &rp.Pulls[i]
-			comments, err := s.Client.ListComments(rp.Owner, rp.Repo, pr.Number)
+			comments, err := s.commentsFor(rp.Owner, rp.Repo, pr.Number)
 			if err != nil {
 				return nil, err
 			}
@@ -331,7 +341,7 @@ func (s *Scanner) usernamesWithUnfinishedWork(members []string) (map[string]bool
 	for _, rp := range repoPulls {
 		for i := range rp.Pulls {
 			pr := &rp.Pulls[i]
-			comments, err := s.Client.ListComments(rp.Owner, rp.Repo, pr.Number)
+			comments, err := s.commentsFor(rp.Owner, rp.Repo, pr.Number)
 			if err != nil {
 				return nil, err
 			}

internal/workflow/stalled_entry_test.go

@@ -0,0 +1,231 @@
+// stalled_entry_test.go — RunStalled／ResolveIssueXrefs 高階入口的單元測試
+//（#7 CLI 接線；資料源注入假實作，離線可測）。
+package workflow
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeStalledSource 包 fakeSource 補上 StalledSource 面向。
+type fakeStalledSource struct {
+	*fakeSource
+	username string
+	// getIssueErr 模擬 GetIssue 失敗（xrefs 的 404 路徑）。
+	getIssueErr error
+}
+
+func (f *fakeStalledSource) CurrentUser() (string, error) { return f.username, nil }
+
+func (f *fakeStalledSource) GetIssue(owner, repo string, number int64) (Issue, error) {
+	if f.getIssueErr != nil {
+		return Issue{}, f.getIssueErr
+	}
+	i, ok := f.issues[owner+"/"+repo][number]
+	if !ok {
+		return Issue{}, &notFoundError{}
+	}
+	return i, nil
+}
+
+type notFoundError struct{}
+
+func (e *notFoundError) Error() string { return "404" }
+
+// newStalledFixture 建構掃描情境：alterminal 組織兩個倉庫，
+// agents#1 是父追蹤項（引用 teai#2），teai#2 有較新留言。
+func newStalledFixture() *fakeStalledSource {
+	return &fakeStalledSource{
+		fakeSource: &fakeSource{
+			orgs:  []string{"alterminal"},
+			repos: map[string][]Repo{"alterminal": {
+				{Name: "agents", HasPullRequests: boolPtr(true)},
+				{Name: "teai", HasPullRequests: boolPtr(true)},
+			}},
+			issues: map[string]map[int64]Issue{
+				"alterminal/agents": {
+					1: {Number: 1, Title: "父追蹤項", State: "open",
+						Body: "子項：teai#2", CreatedAt: iso(-600), UpdatedAt: iso(-600),
+						Repository: &Repository{FullName: "alterminal/agents"}},
+				},
+				"alterminal/teai": {
+					2: {Number: 2, Title: "子項", State: "open",
+						CreatedAt: iso(-500), UpdatedAt: iso(-90),
+						Repository: &Repository{FullName: "alterminal/teai"}},
+				},
+			},
+			pulls: map[string][]PullRequest{},
+			comments: map[string][]Comment{
+				"alterminal/teai/2": {
+					{CreatedAt: iso(-90), User: &User{UserName: "alex"}, Body: "推進中"},
+				},
+			},
+		},
+		username: "ceo",
+	}
+}
+
+// TestRunStalledParentTracking 驗證 RunStalled：父追蹤項把子項活動
+// 計入 last_activity（reason=parent-tracking），且門檻預設與覆寫皆可。
+func TestRunStalledParentTracking(t *testing.T) {
+	src := newStalledFixture()
+	// 預設 4 小時門檻：子項 90 分鐘前有活動 → 父項 last_activity 同步，
+	// 未過門檻，清單為空。
+	items, err := RunStalled(src, 0, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("預設門檻下不應有停滯項，得到 %d 筆", len(items))
+	}
+	// 門檻降到 1 小時：父追蹤項 last_activity 取子項活動（-90m）→
+	// 停滯 1.5h 列入（reason=parent-tracking、附 child_activity）；
+	// 子項 teai#2 本身也停滯 1.5h（no-assignee）。
+	items, err = RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if len(items) != 2 {
+		t.Fatalf("應有兩筆（父追蹤項＋子項），得到 %d：%+v", len(items), items)
+	}
+	var parent *Item
+	for i := range items {
+		if items[i].Number == 1 {
+			parent = &items[i]
+		}
+	}
+	if parent == nil {
+		t.Fatalf("找不到 agents#1：%+v", items)
+	}
+	if parent.Reason != "parent-tracking" || parent.Repo != "alterminal/agents" {
+		t.Fatalf("agents#1 應為 parent-tracking，得到 %s（%s）", parent.Reason, parent.Repo)
+	}
+	if len(parent.ChildActivity) == 0 {
+		t.Fatalf("parent-tracking 應附 child_activity")
+	}
+	if parent.StalledHours != 1.5 {
+		t.Fatalf("last_activity 應取子項活動（-90m → 1.5h），得到 %.1f", parent.StalledHours)
+	}
+}
+
+// TestRunStalledNudgeCooldown 驗證催促冷卻：最後留言出自目前帳號
+// 且在 24 小時內 → 不列入；冷卻過後再出現。
+func TestRunStalledNudgeCooldown(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "") // 移除子項引用
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-2), User: &User{UserName: "ceo"}},
+	}
+	findOne := func(items []Item) bool {
+		for _, it := range items {
+			if it.Repo == "alterminal/agents" && it.Number == 1 {
+				return true
+			}
+		}
+		return false
+	}
+	items, err := RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if findOne(items) {
+		t.Fatalf("催促冷卻期內（2 小時前留言）agents#1 不應列入，得到 %+v", items)
+	}
+	src.comments["alterminal/agents/1"] = []Comment{
+		{CreatedAt: iso(-30 * 60), User: &User{UserName: "ceo"}},
+	}
+	items, err = RunStalled(src, 1, at(0))
+	if err != nil {
+		t.Fatalf("RunStalled: %v", err)
+	}
+	if !findOne(items) {
+		t.Fatalf("冷卻（24h）過後 agents#1 應再出現，得到 %+v", items)
+	}
+}
+
+// TestResolveIssueXrefs 驗證 xrefs 入口：內文與留言的引用解析、
+// 去重、出處標記與單段 repo 的存在性邊界。
+func TestResolveIssueXrefs(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "看 teai#2 與 #7，另見 alterminal/teai#2")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "teai#2 已處理", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+		{Body: "nope#9 不存在", User: &User{UserName: "max"}, CreatedAt: iso(-5)},
+	}
+	// fixture 的組織倉庫只有 agents → teai#2 單段不解析（repo 不在
+	// alterminal 組織清單）；補上 teai 倉庫讓單段解析成立。
+	src.repos["alterminal"] = []Repo{
+		{Name: "agents", HasPullRequests: boolPtr(true)},
+		{Name: "teai", HasPullRequests: boolPtr(true)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	want := []XrefHit{
+		{Owner: "alterminal", Repo: "teai", Number: 2, Source: "body"},
+		{Owner: "alterminal", Repo: "agents", Number: 7, Source: "body"},
+	}
+	if len(hits) != len(want) {
+		t.Fatalf("應解析出 %d 筆（留言重複的 teai#2 去重、nope#9 略過），得到 %d：%+v",
+			len(want), len(hits), hits)
+	}
+	for i := range want {
+		if hits[i] != want[i] {
+			t.Fatalf("hits[%d] = %+v, want %+v", i, hits[i], want[i])
+		}
+	}
+}
+
+// TestResolveIssueXrefsCommentSource 驗證出處：僅出現在留言的引用
+// 標記為 comment。
+func TestResolveIssueXrefsCommentSource(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, "內文無引用")
+	src.comments["alterminal/agents/1"] = []Comment{
+		{Body: "追蹤 #9", User: &User{UserName: "alex"}, CreatedAt: iso(-10)},
+	}
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 1 || hits[0].Source != "comment" || hits[0].Number != 9 {
+		t.Fatalf("應輸出一筆 source=comment 的 #9，得到 %+v", hits)
+	}
+}
+
+// TestResolveIssueXrefsGetError 驗證 GetIssue 失敗（如 404）層層回傳，
+// 由 CLI 映射結束碼。
+func TestResolveIssueXrefsGetError(t *testing.T) {
+	src := newStalledFixture()
+	src.getIssueErr = &notFoundError{}
+	if _, err := ResolveIssueXrefs(src, "alterminal", "agents", 1); err == nil {
+		t.Fatalf("GetIssue 失敗應回傳錯誤")
+	}
+}
+
+func boolPtr(b bool) *bool { return &b }
+
+// setIssueBody 修改 map 內 issue 的內文（map 元素不可定址，需整體重塞）。
+func setIssueBody(src *fakeStalledSource, owner, repo string, number int64, body string) {
+	key := owner + "/" + repo
+	issue := src.issues[key][number]
+	issue.Body = body
+	src.issues[key][number] = issue
+}
+
+// TestResolveIssueXrefsEmptyBody 驗證無引用時輸出空（CLI 印 []）。
+func TestResolveIssueXrefsEmptyBody(t *testing.T) {
+	src := newStalledFixture()
+	setIssueBody(src, "alterminal", "agents", 1, strings.Repeat("無引用內文", 3))
+	delete(src.comments, "alterminal/agents/1")
+	hits, err := ResolveIssueXrefs(src, "alterminal", "agents", 1)
+	if err != nil {
+		t.Fatalf("ResolveIssueXrefs: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("無引用應輸出空清單，得到 %+v", hits)
+	}
+	_ = time.Now // time 僅供 iso/at 使用；保留 import。
+}

internal/workflow/types.go

@@ -3,6 +3,8 @@ package workflow
 import (
 	"encoding/json"
 	"regexp"
+	"strings"
+	"time"
 )
 
 // User 是 Gitea API 的使用者物件（僅取工作流判斷會用到的欄位）。
@@ -65,6 +67,7 @@ type PRRef struct {
 
 // Comment 是 issue／PR 的討論留言（PR 的留言也走 issues comments 端點）。
 type Comment struct {
+	Body      string `json:"body"`
 	CreatedAt string `json:"created_at"`
 	User      *User  `json:"user"`
 }
@@ -82,6 +85,9 @@ type Issue struct {
 	Number      int64       `json:"number"`
 	Index       int64       `json:"index"`
 	Title       string      `json:"title"`
+	State       string      `json:"state"`
+	Body        string      `json:"body"`
+	ClosedAt    string      `json:"closed_at"`
 	HTMLURL     string      `json:"html_url"`
 	URL         string      `json:"url"`
 	UpdatedAt   string      `json:"updated_at"`
@@ -216,3 +222,21 @@ func (p *PullRequest) FullName() string {
 	}
 	return repoFullNameFromURL(p.WebURL())
 }
+
+// parseMoment 對應 gitea.py 的 _parse_iso8601：剖析 ISO8601 字串（Z 後綴、
+// 小數秒、時區偏移皆可；無時區視為 UTC），失敗回 (零值, false)。
+// 保留原時區偏移、不轉 UTC——Python datetime.isoformat() 會原樣輸出
+// 「+08:00」這類偏移，轉了 UTC 輸出就變 +00:00，與基準位元組不相容。
+// stalled 掃描的時刻判斷（last_activity、催促冷卻）都以這裡的語義為準。
+func parseMoment(value string) (time.Time, bool) {
+	text := strings.TrimSpace(value)
+	if text == "" {
+		return time.Time{}, false
+	}
+	for _, layout := range []string{time.RFC3339Nano, time.RFC3339, "2006-01-02T15:04:05", "2006-01-02"} {
+		if t, err := time.Parse(layout, text); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}

internal/workflow/workflow.go

@@ -0,0 +1,636 @@
+// 套件 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+)`)
+
+// Item 是 stalled 掃描的單筆輸出（欄位對應 gitea.py 的 find_stalled_work）。
+type Item struct {
+	Type           string
+	Repo           string
+	Number         int64
+	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 int64  `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 int64
+}
+
+// Source 是 stalled 掃描需要的資料源（CLI 層以 API 實作；測試注入假資料）。
+type Source interface {
+	// MyOrganizations 回傳目前帳號所屬組織清單。
+	MyOrganizations() ([]string, error)
+	// OrganizationRepositories 回傳組織的倉庫清單。
+	OrganizationRepositories(org string) ([]Repo, error)
+	// OpenIssues 回傳倉庫的 open issues（Gitea 會混入 PR，由掃描端過濾）。
+	OpenIssues(owner, repo string) ([]Issue, error)
+	// OpenPulls 回傳倉庫的 open pull requests。
+	OpenPulls(owner, repo string) ([]PullRequest, error)
+	// IssueComments 回傳 issue／PR 的留言。
+	IssueComments(owner, repo string, number int64) ([]Comment, error)
+	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
+	TryGetIssue(owner, repo string, number int64) (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 int64
+			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.issueNumber() == parent.issueNumber() {
+			continue // 自我引用
+		}
+		parentCreated, pcOK := parseMoment(parent.CreatedAt)
+		childCreated, ccOK := parseMoment(child.CreatedAt)
+		if pcOK && ccOK && !childCreated.After(parentCreated) {
+			continue // 上行引用（父項回指更早或同時的 issue）；時間未知則不排除
+		}
+		var ms []time.Time
+		if m, ok := parseMoment(child.UpdatedAt); ok {
+			ms = append(ms, m)
+		}
+		if m, ok := parseMoment(child.ClosedAt); ok {
+			ms = append(ms, m)
+		}
+		if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
+			for _, c := range cs {
+				if m, ok := parseMoment(c.CreatedAt); ok {
+					ms = append(ms, m)
+				}
+			}
+		}
+		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
+}
+
+// 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 := AssigneeNames(&issue)
+	var moments []time.Time
+	if m, ok := parseMoment(issue.UpdatedAt); ok {
+		moments = append(moments, m)
+	}
+	if m, ok := parseMoment(issue.CreatedAt); ok {
+		moments = append(moments, m)
+	}
+	for _, c := range comments {
+		if m, ok := parseMoment(c.CreatedAt); ok {
+			moments = append(moments, m)
+		}
+	}
+	moments = append(moments, childMoments...)
+	if len(moments) == 0 {
+		return Item{}, false
+	}
+	lastActivity := maxTime(moments)
+	stalled := now.Sub(lastActivity).Hours()
+	if stalled < threshold {
+		return Item{}, false
+	}
+	last := LastComment(comments)
+	lastCommentBy := ""
+	if last != nil {
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
+			return Item{}, false
+		}
+	}
+	reason := "waiting-outside"
+	switch {
+	case len(assignees) == 0:
+		reason = "no-assignee"
+	case lastCommentBy != "" && containsString(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.FullName(), Number: issue.issueNumber(),
+		Title: issue.Title, URL: issue.WebURL(),
+		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 := ReviewerNames(&pr)
+	author := pr.Author()
+	var moments []time.Time
+	if m, ok := parseMoment(pr.UpdatedAt); ok {
+		moments = append(moments, m)
+	}
+	if m, ok := parseMoment(pr.CreatedAt); ok {
+		moments = append(moments, m)
+	}
+	for _, c := range comments {
+		if m, ok := parseMoment(c.CreatedAt); ok {
+			moments = append(moments, m)
+		}
+	}
+	if len(moments) == 0 {
+		return Item{}, false
+	}
+	lastActivity := maxTime(moments)
+	stalled := now.Sub(lastActivity).Hours()
+	if stalled < threshold {
+		return Item{}, false
+	}
+	last := LastComment(comments)
+	lastCommentBy := ""
+	if last != nil {
+		lastCommentBy = last.Author()
+	}
+	if lastCommentBy == username {
+		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
+			return Item{}, false
+		}
+	}
+	reason := "no-commenter"
+	switch {
+	case len(reviewers) == 0:
+		reason = "no-reviewer"
+	case lastCommentBy == author:
+		reason = "author-idle"
+	case lastCommentBy != "" && containsString(reviewers, lastCommentBy):
+		reason = "reviewer-idle"
+	}
+	item := Item{
+		Type: "pull", Repo: pr.FullName(), Number: pr.Number,
+		Title: pr.Title, URL: pr.WebURL(),
+		Author: author, Reviewers: reviewers,
+		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
+		StalledHours: round1(stalled), Reason: reason,
+	}
+	return item, true
+}
+
+func anyOpen(children []Child) bool {
+	for _, c := range children {
+		if c.State == "open" {
+			return true
+		}
+	}
+	return false
+}
+
+// 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
+}
+
+// ── CLI 接線用的高階入口（#7：teai stalled／teai xrefs）─────────────────
+
+// StalledSource 是 stalled／xrefs 命令需要的完整資料源：
+// Source（掃描用讀取）加上目前帳號與單一 issue 查詢。
+// APIClient（giteaapi.go）實作此介面；測試以假資料源注入。
+type StalledSource interface {
+	Source
+	// CurrentUser 回傳目前帳號名（催促冷卻判定用）。
+	CurrentUser() (string, error)
+	// GetIssue 嚴格版單一 issue／PR 查詢；失敗回錯誤（xrefs 命令用，
+	// 404 應回 ErrAPI 由 CLI 映射結束碼 3）。
+	GetIssue(owner, repo string, number int64) (Issue, error)
+}
+
+// RunStalled 是 teai stalled 的核心：解析目前帳號後跑 ScanStalled。
+// hours <= 0 時採 StalledDefaultHours（對應 gitea.py stalled [--hours N]
+// 的預設 4 小時）；旗標層已先攔下非正數，這裡是防禦。
+func RunStalled(src StalledSource, hours float64, now time.Time) ([]Item, error) {
+	if hours <= 0 {
+		hours = StalledDefaultHours
+	}
+	username, err := src.CurrentUser()
+	if err != nil {
+		return nil, err
+	}
+	return ScanStalled(src, username, hours, now)
+}
+
+// XrefHit 是 teai xrefs 的單筆輸出：解析後的目標加上出處
+// （README 規格："body"＝內文、"comment"＝留言）。
+type XrefHit struct {
+	Owner  string `json:"owner"`
+	Repo   string `json:"repo"`
+	Number int64  `json:"number"`
+	Source string `json:"source"`
+}
+
+// ResolveIssueXrefs 是 teai xrefs 的核心：取回單一 issue／PR 的內文與
+// 全部留言，解析其中的 #N、repo#N、owner/repo#N 引用（規則同
+// ResolveXrefTargets：單段 repo 僅在父項所屬組織有該倉庫時解析、
+// owner/repo#N 僅在 owner 為所屬組織時解析），去重並保留出現順序，
+// 每筆附首次出現的出處（內文先於留言）。stalled 的父追蹤項判定
+// 內部用同一套解析，不重複實作。
+func ResolveIssueXrefs(src StalledSource, owner, repo string, number int64) ([]XrefHit, error) {
+	issue, err := src.GetIssue(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	comments, err := src.IssueComments(owner, repo, number)
+	if err != nil {
+		return nil, err
+	}
+	orgs, err := src.MyOrganizations()
+	if err != nil {
+		return nil, err
+	}
+	myOrgs := make(map[string]bool, len(orgs))
+	for _, o := range orgs {
+		myOrgs[o] = true
+	}
+	// 組織倉庫清單跨呼叫快取，避免逐則留言重打 API。
+	orgRepoCache := map[string][]string{}
+	orgRepos := func(org string) ([]string, error) {
+		if names, ok := orgRepoCache[org]; ok {
+			return names, nil
+		}
+		repos, err := src.OrganizationRepositories(org)
+		if err != nil {
+			return nil, err
+		}
+		names := make([]string, 0, len(repos))
+		for _, r := range repos {
+			if r.Name != "" {
+				names = append(names, r.Name)
+			}
+		}
+		orgRepoCache[org] = names
+		return names, nil
+	}
+	type sourceText struct {
+		text   string
+		source string
+	}
+	texts := []sourceText{{issue.Body, "body"}}
+	for _, c := range comments {
+		texts = append(texts, sourceText{c.Body, "comment"})
+	}
+	var hits []XrefHit
+	seen := map[XrefTarget]bool{}
+	for _, t := range texts {
+		targets, err := ResolveXrefTargets(owner, repo, []string{t.text}, myOrgs, orgRepos)
+		if err != nil {
+			return nil, err
+		}
+		for _, target := range targets {
+			if seen[target] {
+				continue
+			}
+			seen[target] = true
+			hits = append(hits, XrefHit{
+				Owner: target.Owner, Repo: target.Repo,
+				Number: target.Number, Source: t.source,
+			})
+		}
+	}
+	return hits, nil
+}

internal/workflow/workflow_test.go

@@ -0,0 +1,535 @@
+// 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][]Repo
+	// issues[owner/repo][number]
+	issues map[string]map[int64]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) ([]Repo, 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 int64) ([]Comment, error) {
+	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
+}
+
+func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
+	i, ok := f.issues[owner+"/"+repo][number]
+	if !ok {
+		return Issue{}, false, nil
+	}
+	return i, true, nil
+}
+
+func repoWith(name string, hasPR bool) []Repo {
+	h := hasPR
+	return []Repo{{Name: name, HasPullRequests: &h}}
+}
+
+// iso 把相對分鐘轉成 parseMoment 可剖析的 ISO8601 字串（假資料用）。
+func iso(minutes int) string { return FormatMoment(at(minutes)) }
+
+func mustResolve(t *testing.T, org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) []XrefTarget {
+	t.Helper()
+	targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
+	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][]Repo{
+			"alterminal": repoWith("agents", true),
+		},
+		issues: map[string]map[int64]Issue{
+			"alterminal/agents": {
+				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/agents"}, URL: "u1"},
+				2: {Number: 2, Title: "分派者自己最後留言", State: "open", User: &User{UserName: "ceo"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u2"},
+				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u3"},
+				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u4"},
+				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: iso(-30), UpdatedAt: iso(-30), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u5"},
+			},
+		},
+		comments: map[string][]Comment{
+			"alterminal/agents/2": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}},
+			"alterminal/agents/4": {{User: &User{UserName: "dan"}, CreatedAt: iso(-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[int64]Item{}
+	for _, it := range got {
+		byNumber[it.Number] = it
+	}
+	for n, wantReason := range map[int64]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
+		if byNumber[n].Reason != wantReason {
+			t.Errorf("issue %d reason = %q, want %q", n, byNumber[n].Reason, wantReason)
+		}
+	}
+	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][]Repo{"alterminal": repoWith("agents", true)},
+		issues: map[string]map[int64]Issue{
+			"alterminal/agents": {
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/agents"}},
+			},
+		},
+		comments: map[string][]Comment{
+			// admin（掃描者）10 小時前催促過 → 冷卻中，不列入。
+			"alterminal/agents/1": {{User: &User{UserName: "admin"}, CreatedAt: iso(-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{UserName: "admin"}, CreatedAt: iso(-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][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
+			"alterminal/teai": {
+				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: iso(-700), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+				7: {Number: 7, Title: "子", State: "open", CreatedAt: iso(-650), UpdatedAt: iso(-300), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+			},
+		},
+		comments: map[string][]Comment{
+			"alterminal/teai/7": {{User: &User{UserName: "max"}, CreatedAt: iso(-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 = iso(-60)
+	src.issues["alterminal/teai"][7] = child
+	src.comments["alterminal/teai/7"] = []Comment{{User: &User{UserName: "max"}, CreatedAt: iso(-60)}}
+	got, err = ScanStalled(src, "admin", 4.0, now)
+	if err != nil {
+		t.Fatalf("ScanStalled: %v", err)
+	}
+	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][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
+			"alterminal/teai": {
+				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: iso(-700), UpdatedAt: iso(-600), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+				39: {Number: 39, State: "open", CreatedAt: iso(-2000), UpdatedAt: iso(-60), Repository: &Repository{FullName: "alterminal/teai"}},
+			},
+		},
+	}
+	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][]Repo{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
+		pulls: map[string][]PullRequest{
+			"alterminal/teai": {
+				{Number: 10, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)},
+				{Number: 11, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 12, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 13, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+			},
+		},
+		comments: map[string][]Comment{
+			"alterminal/teai/11": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}}, // author-idle
+			"alterminal/teai/12": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}}, // reviewer-idle
+			"alterminal/teai/13": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}}, // no-commenter（外部留言）
+		},
+	}
+	got, err := ScanStalled(src, "admin", 4.0, now)
+	if err != nil {
+		t.Fatalf("ScanStalled: %v", err)
+	}
+	byNumber := map[int64]Item{}
+	for _, it := range got {
+		byNumber[it.Number] = it
+	}
+	for n, wantReason := range map[int64]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
+		item, ok := byNumber[n]
+		if !ok {
+			t.Fatalf("PR %d 應列入，got %v", n, got)
+		}
+		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][]Repo{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
+		issues: map[string]map[int64]Issue{
+			"alterminal/docs": {
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/docs"}},
+			},
+		},
+		pulls: map[string][]PullRequest{
+			// 即使假資料有 PR，flag 關閉也不應掃。
+			"alterminal/docs": {{Number: 2, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-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][]Repo{"alterminal": repoWith("teai", true)},
+		issues: map[string]map[int64]Issue{
+			"alterminal/teai": {
+				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/teai"}, PullRequest: &pullMarker{}},
+			},
+		},
+	}
+	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][]Repo{"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) ([]Repo, error) {
+	return nil, errors.New("boom")
+}
+func (e errSource) OpenIssues(string, string) ([]Issue, error)      { return nil, errors.New("boom") }
+func (e errSource) OpenPulls(string, string) ([]PullRequest, error) { return nil, errors.New("boom") }
+func (e errSource) IssueComments(string, string, int64) ([]Comment, error) {
+	return nil, errors.New("boom")
+}
+func (e errSource) TryGetIssue(string, string, int64) (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)
+		}
+	}
+}