docs：README 補上完整安裝指南（#15）

README.md

@@ -11,12 +11,47 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
 
 ## 安裝與建置
 
-需要 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`；

cmd/xcheck/main.go

@@ -132,8 +132,8 @@ func (s *apiSource) MyOrganizations() ([]string, error) {
 	return names, nil
 }
 
-func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repo, error) {
+func (s *apiSource) OrganizationRepositories(org string) ([]workflow.Repository, error) {
-	var repos []workflow.Repo
+	var repos []workflow.Repository
 	if err := s.listAll("orgs/"+org+"/repos", nil, &repos); err != nil {
 		return nil, err
 	}
@@ -157,7 +157,7 @@ func (s *apiSource) OpenPulls(owner, repo string) ([]workflow.PullRequest, error
 	return pulls, nil
 }
 
-func (s *apiSource) IssueComments(owner, repo string, number int64) ([]workflow.Comment, error) {
+func (s *apiSource) IssueComments(owner, repo string, number int) ([]workflow.Comment, error) {
 	var comments []workflow.Comment
 	if err := s.listAll(fmt.Sprintf("repos/%s/%s/issues/%d/comments", owner, repo, number), nil, &comments); err != nil {
 		return nil, err
@@ -165,7 +165,7 @@ func (s *apiSource) IssueComments(owner, repo string, number int64) ([]workflow.
 	return comments, nil
 }
 
-func (s *apiSource) TryGetIssue(owner, repo string, number int64) (workflow.Issue, bool, error) {
+func (s *apiSource) TryGetIssue(owner, repo string, number int) (workflow.Issue, bool, error) {
 	var issue workflow.Issue
 	body, code, err := s.get(fmt.Sprintf("repos/%s/%s/issues/%d", owner, repo, number), nil)
 	if err != nil {

internal/workflow/types.go

@@ -3,8 +3,6 @@ package workflow
 import (
 	"encoding/json"
 	"regexp"
-	"strings"
-	"time"
 )
 
 // User 是 Gitea API 的使用者物件（僅取工作流判斷會用到的欄位）。
@@ -67,7 +65,6 @@ 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"`
 }
@@ -85,9 +82,6 @@ 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"`
@@ -222,21 +216,3 @@ 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

@@ -37,11 +37,85 @@ const (
 // Go 的 regexp 不支援 lookbehind，改在掃描時檢查前一字元。
 var xrefPattern = regexp.MustCompile(`([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?)?#(\d+)`)
 
+// User 是 Gitea user 物件的精簡投影。
+type User struct {
+	Username string `json:"username"`
+}
+
+// Comment 是 issue／PR 留言的精簡投影。
+type Comment struct {
+	User      User      `json:"user"`
+	Body      string    `json:"body"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// Author 回傳留言作者帳號；空字串表示無法判定。
+func (c Comment) Author() string { return c.User.Username }
+
+// Issue 是 issue 的精簡投影（Gitea /repos/{owner}/{repo}/issues，不含 PR）。
+type Issue struct {
+	Number    int        `json:"number"`
+	Title     string     `json:"title"`
+	State     string     `json:"state"`
+	Body      string     `json:"body"`
+	Author    User       `json:"user"`
+	CreatedAt time.Time  `json:"created_at"`
+	UpdatedAt time.Time  `json:"updated_at"`
+	ClosedAt  *time.Time `json:"closed_at,omitempty"`
+	// URL 對應 API 的 html_url。
+	URL        string    `json:"html_url"`
+	Assignees  []User    `json:"assignees"`
+	Repository Reference `json:"repository"`
+	// PullRequest 非 nil 表示這其實是 PR（Gitea 的 /issues API 兩者都回）。
+	PullRequest any `json:"pull_request,omitempty"`
+}
+
+// Reference 是 repository 物件的精簡投影（issue 物件帶 full_name）。
+type Reference struct {
+	FullName string `json:"full_name"`
+}
+
+// Ref 是 PR base/head 的精簡投影（PR 物件沒有 repository 欄位，改讀 base/head.repo）。
+type Ref struct {
+	Repo Reference `json:"repo"`
+}
+
+// PullRequest 是 /repos/{owner}/{repo}/pulls 物件的精簡投影。
+type PullRequest struct {
+	Number    int        `json:"number"`
+	Title     string     `json:"title"`
+	State     string     `json:"state"`
+	Author    User       `json:"user"`
+	CreatedAt time.Time  `json:"created_at"`
+	UpdatedAt time.Time  `json:"updated_at"`
+	ClosedAt  *time.Time `json:"closed_at,omitempty"`
+	// URL 對應 API 的 html_url。
+	URL                string `json:"html_url"`
+	Base               Ref    `json:"base"`
+	Head               Ref    `json:"head"`
+	RequestedReviewers []User `json:"requested_reviewers"`
+}
+
+// FullName 回傳 "owner/repo"；PR 沒有 repository 欄位，改讀 base（再退 head）。
+func (p PullRequest) FullName() string {
+	if p.Base.Repo.FullName != "" {
+		return p.Base.Repo.FullName
+	}
+	return p.Head.Repo.FullName
+}
+
+// Repository 是 /orgs/{org}/repos 物件的精簡投影。
+type Repository struct {
+	Name            string `json:"name"`
+	Empty           bool   `json:"empty"`
+	HasPullRequests *bool  `json:"has_pull_requests"`
+}
+
 // Item 是 stalled 掃描的單筆輸出（欄位對應 gitea.py 的 find_stalled_work）。
 type Item struct {
 	Type           string
 	Repo           string
-	Number         int64
+	Number         int
 	Title          string
 	URL            string
 	Assignees      []string
@@ -121,7 +195,7 @@ func writeJSON(b *strings.Builder, v any) {
 // Child 是父追蹤項的子項活動摘要。
 type Child struct {
 	Repo   string `json:"repo"`
-	Number int64  `json:"number"`
+	Number int    `json:"number"`
 	Title  string `json:"title"`
 	State  string `json:"state"`
 	// LastActivityAt 用指標：子項無可解析時刻時 Python 輸出 null（不是 ""）。
@@ -132,7 +206,7 @@ type Child struct {
 type XrefTarget struct {
 	Owner  string
 	Repo   string
-	Number int64
+	Number int
 }
 
 // Source 是 stalled 掃描需要的資料源（CLI 層以 API 實作；測試注入假資料）。
@@ -140,15 +214,15 @@ type Source interface {
 	// MyOrganizations 回傳目前帳號所屬組織清單。
 	MyOrganizations() ([]string, error)
 	// OrganizationRepositories 回傳組織的倉庫清單。
-	OrganizationRepositories(org string) ([]Repo, error)
+	OrganizationRepositories(org string) ([]Repository, error)
 	// OpenIssues 回傳倉庫的 open issues（Gitea 會混入 PR，由掃描端過濾）。
 	OpenIssues(owner, repo string) ([]Issue, error)
 	// OpenPulls 回傳倉庫的 open pull requests。
 	OpenPulls(owner, repo string) ([]PullRequest, error)
 	// IssueComments 回傳 issue／PR 的留言。
-	IssueComments(owner, repo string, number int64) ([]Comment, error)
+	IssueComments(owner, repo string, number int) ([]Comment, error)
 	// TryGetIssue 寬容版單一 issue 查詢：失敗（含 404）回 (零值, false, nil)。
-	TryGetIssue(owner, repo string, number int64) (Issue, bool, error)
+	TryGetIssue(owner, repo string, number int) (Issue, bool, error)
 }
 
 // iterXrefs 產出文字中的 (prefix, number) 配對（對應 _iter_issue_xrefs）。
@@ -204,7 +278,7 @@ func ResolveXrefTargets(org, repo string, texts []string, myOrgs map[string]bool
 	for _, text := range texts {
 		for _, pair := range iterXrefs(text) {
 			prefix, numberStr := pair[0], pair[1]
-			var number int64
+			var number int
 			if _, err := fmt.Sscanf(numberStr, "%d", &number); err != nil || number <= 0 {
 				continue
 			}
@@ -260,25 +334,23 @@ func childActivity(src Source, org, repo string, parent Issue, comments []Commen
 		if gerr != nil || !ok {
 			continue
 		}
-		if t.Owner == org && t.Repo == repo && child.issueNumber() == parent.issueNumber() {
+		if t.Owner == org && t.Repo == repo && child.Number == parent.Number {
 			continue // 自我引用
 		}
-		parentCreated, pcOK := parseMoment(parent.CreatedAt)
+		if !parent.CreatedAt.IsZero() && !child.CreatedAt.IsZero() && !child.CreatedAt.After(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 {
+		if !child.UpdatedAt.IsZero() {
-			ms = append(ms, m)
+			ms = append(ms, child.UpdatedAt)
 		}
-		if m, ok := parseMoment(child.ClosedAt); ok {
+		if child.ClosedAt != nil && !child.ClosedAt.IsZero() {
-			ms = append(ms, m)
+			ms = append(ms, *child.ClosedAt)
 		}
 		if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
 			for _, c := range cs {
-				if m, ok := parseMoment(c.CreatedAt); ok {
+				if !c.CreatedAt.IsZero() {
-					ms = append(ms, m)
+					ms = append(ms, c.CreatedAt)
 				}
 			}
 		}
@@ -312,6 +384,20 @@ func maxTime(ts []time.Time) time.Time {
 	return best
 }
 
+func usernames(users []User) []string {
+	var out []string
+	seen := map[string]bool{}
+	for _, u := range users {
+		if u.Username == "" || seen[u.Username] {
+			continue
+		}
+		seen[u.Username] = true
+		out = append(out, u.Username)
+	}
+	sort.Strings(out)
+	return out
+}
+
 // ScanStalled 掃描跨組織的停滯 open issues／PR（對應 find_stalled_work）。
 //
 // 判定：最後活動（留言時間與本身 updated_at 取較晚者，父追蹤項再加計
@@ -397,20 +483,15 @@ func ScanStalled(src Source, username string, threshold float64, now time.Time)
 // considerIssue 對單一 issue 套用停滯判定（對應 _consider 的 issue 分支）。
 func considerIssue(src Source, org, repo string, issue Issue, comments []Comment, username string, threshold float64, now time.Time, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (Item, bool) {
 	childMoments, children := childActivity(src, org, repo, issue, comments, myOrgs, orgRepos)
-	assignees := AssigneeNames(&issue)
+	assignees := usernames(issue.Assignees)
-	var moments []time.Time
+	moments := []time.Time{issue.UpdatedAt, issue.CreatedAt}
-	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 {
+		if !c.CreatedAt.IsZero() {
-			moments = append(moments, m)
+			moments = append(moments, c.CreatedAt)
 		}
 	}
 	moments = append(moments, childMoments...)
+	moments = nonZero(moments)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -419,21 +500,16 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 	if stalled < threshold {
 		return Item{}, false
 	}
-	last := LastComment(comments)
+	lastCommentAt, lastCommentBy := lastComment(comments)
-	lastCommentBy := ""
+	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-	if last != nil {
+		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
-		lastCommentBy = last.Author()
+		return Item{}, false
-	}
-	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):
+	case lastCommentBy != "" && containsStr(assignees, lastCommentBy):
 		reason = "assignee-idle"
 	case lastCommentBy == "":
 		reason = "no-commenter"
@@ -442,8 +518,8 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 		reason = "parent-tracking"
 	}
 	item := Item{
-		Type: "issue", Repo: issue.FullName(), Number: issue.issueNumber(),
+		Type: "issue", Repo: issue.Repository.FullName, Number: issue.Number,
-		Title: issue.Title, URL: issue.WebURL(),
+		Title: issue.Title, URL: issue.URL,
 		Assignees:     assignees,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -456,20 +532,15 @@ func considerIssue(src Source, org, repo string, issue Issue, comments []Comment
 
 // considerPull 對單一 PR 套用停滯判定（對應 _consider 的 pull 分支）。
 func considerPull(pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
-	reviewers := ReviewerNames(&pr)
+	reviewers := usernames(pr.RequestedReviewers)
-	author := pr.Author()
+	author := pr.Author.Username
-	var moments []time.Time
+	moments := []time.Time{pr.UpdatedAt, pr.CreatedAt}
-	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 {
+		if !c.CreatedAt.IsZero() {
-			moments = append(moments, m)
+			moments = append(moments, c.CreatedAt)
 		}
 	}
+	moments = nonZero(moments)
 	if len(moments) == 0 {
 		return Item{}, false
 	}
@@ -478,15 +549,10 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	if stalled < threshold {
 		return Item{}, false
 	}
-	last := LastComment(comments)
+	lastCommentAt, lastCommentBy := lastComment(comments)
-	lastCommentBy := ""
+	if lastCommentBy == username && !lastCommentAt.IsZero() &&
-	if last != nil {
+		now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
-		lastCommentBy = last.Author()
+		return Item{}, false
-	}
-	if lastCommentBy == username {
-		if m, ok := parseMoment(last.CreatedAt); ok && now.Sub(m).Hours() < NudgeCooldownHours {
-			return Item{}, false
-		}
 	}
 	reason := "no-commenter"
 	switch {
@@ -494,12 +560,12 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 		reason = "no-reviewer"
 	case lastCommentBy == author:
 		reason = "author-idle"
-	case lastCommentBy != "" && containsString(reviewers, lastCommentBy):
+	case lastCommentBy != "" && containsStr(reviewers, lastCommentBy):
 		reason = "reviewer-idle"
 	}
 	item := Item{
 		Type: "pull", Repo: pr.FullName(), Number: pr.Number,
-		Title: pr.Title, URL: pr.WebURL(),
+		Title: pr.Title, URL: pr.URL,
 		Author: author, Reviewers: reviewers,
 		LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
 		StalledHours: round1(stalled), Reason: reason,
@@ -507,6 +573,19 @@ func considerPull(pr PullRequest, comments []Comment, username string, threshold
 	return item, true
 }
 
+// lastComment 回傳最後一則留言（created_at 最新者）的時間與作者。
+func lastComment(comments []Comment) (time.Time, string) {
+	var best time.Time
+	by := ""
+	for _, c := range comments {
+		if c.CreatedAt.After(best) {
+			best = c.CreatedAt
+			by = c.Author()
+		}
+	}
+	return best, by
+}
+
 func anyOpen(children []Child) bool {
 	for _, c := range children {
 		if c.State == "open" {
@@ -516,6 +595,25 @@ func anyOpen(children []Child) bool {
 	return false
 }
 
+func containsStr(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}
+
+func nonZero(ts []time.Time) []time.Time {
+	out := make([]time.Time, 0, len(ts))
+	for _, t := range ts {
+		if !t.IsZero() {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
 // round1 舍入到小數一位（對應 Python round(x, 1)）。
 // 經 strconv 的十進位正確舍入（半偶數），與 Python 的浮點 round 行為一致，
 // 避免 (x*10+0.5) 截斷在 .x5 邊界產生偏差。

internal/workflow/workflow_test.go

@@ -21,9 +21,9 @@ func at(minutes int) time.Time {
 // fakeSource 是注入假資料的 Source。
 type fakeSource struct {
 	orgs  []string
-	repos map[string][]Repo
+	repos map[string][]Repository
 	// issues[owner/repo][number]
-	issues map[string]map[int64]Issue
+	issues map[string]map[int]Issue
 	// pulls[owner/repo]
 	pulls map[string][]PullRequest
 	// comments[owner/repo/number]
@@ -32,7 +32,7 @@ type fakeSource struct {
 
 func (f *fakeSource) MyOrganizations() ([]string, error) { return f.orgs, nil }
 
-func (f *fakeSource) OrganizationRepositories(org string) ([]Repo, error) {
+func (f *fakeSource) OrganizationRepositories(org string) ([]Repository, error) {
 	return f.repos[org], nil
 }
 
@@ -48,11 +48,11 @@ 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) {
+func (f *fakeSource) IssueComments(owner, repo string, number int) ([]Comment, error) {
 	return f.comments[fmt.Sprintf("%s/%s/%d", owner, repo, number)], nil
 }
 
-func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool, error) {
+func (f *fakeSource) TryGetIssue(owner, repo string, number int) (Issue, bool, error) {
 	i, ok := f.issues[owner+"/"+repo][number]
 	if !ok {
 		return Issue{}, false, nil
@@ -60,14 +60,11 @@ func (f *fakeSource) TryGetIssue(owner, repo string, number int64) (Issue, bool,
 	return i, true, nil
 }
 
-func repoWith(name string, hasPR bool) []Repo {
+func repoWith(name string, hasPR bool) []Repository {
 	h := hasPR
-	return []Repo{{Name: name, HasPullRequests: &h}}
+	return []Repository{{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)
@@ -160,21 +157,21 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs: []string{"alterminal"},
-		repos: map[string][]Repo{
+		repos: map[string][]Repository{
 			"alterminal": repoWith("agents", true),
 		},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/agents"}, URL: "u1"},
+				1: {Number: 1, Title: "無分派者", State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"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"},
+				2: {Number: 2, Title: "分派者自己最後留言", State: "open", Author: User{"ceo"}, CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u2"},
-				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u3"},
+				3: {Number: 3, Title: "無留言", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u3"},
-				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-300), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u4"},
+				4: {Number: 4, Title: "等外部回應", State: "open", CreatedAt: at(-600), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u4"},
-				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: iso(-30), UpdatedAt: iso(-30), Assignees: []User{{UserName: "ceo"}}, Repository: &Repository{FullName: "alterminal/agents"}, URL: "u5"},
+				5: {Number: 5, Title: "太新不在門檻內", State: "open", CreatedAt: at(-30), UpdatedAt: at(-30), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/agents"}, URL: "u5"},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/agents/2": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}},
+			"alterminal/agents/2": {{User: User{"ceo"}, CreatedAt: at(-300)}},
-			"alterminal/agents/4": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}},
+			"alterminal/agents/4": {{User: User{"dan"}, CreatedAt: at(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -185,11 +182,11 @@ func TestScanStalledIssueReasons(t *testing.T) {
 	if len(got) != 4 {
 		t.Fatalf("應 4 筆，got %d：%v", len(got), got)
 	}
-	byNumber := map[int64]Item{}
+	byNumber := map[int]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"} {
+	for n, wantReason := range map[int]string{1: "no-assignee", 2: "assignee-idle", 3: "no-commenter", 4: "waiting-outside"} {
 		if byNumber[n].Reason != wantReason {
 			t.Errorf("issue %d reason = %q, want %q", n, byNumber[n].Reason, wantReason)
 		}
@@ -207,15 +204,15 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": repoWith("agents", true)},
+		repos: map[string][]Repository{"alterminal": repoWith("agents", true)},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]Issue{
 			"alterminal/agents": {
-				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/agents"}},
+				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/agents"}},
 			},
 		},
 		comments: map[string][]Comment{
 			// admin（掃描者）10 小時前催促過 → 冷卻中，不列入。
-			"alterminal/agents/1": {{User: &User{UserName: "admin"}, CreatedAt: iso(-600)}},
+			"alterminal/agents/1": {{User: User{"admin"}, CreatedAt: at(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -226,7 +223,7 @@ func TestScanStalledNudgeCooldown(t *testing.T) {
 		t.Fatalf("催促冷卻中的項目不應列入，got %v", got)
 	}
 	// 冷卻過了（25 小時前催促）→ 重新列入。
-	src.comments["alterminal/agents/1"] = []Comment{{User: &User{UserName: "admin"}, CreatedAt: iso(-1500)}}
+	src.comments["alterminal/agents/1"] = []Comment{{User: User{"admin"}, CreatedAt: at(-1500)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -243,15 +240,15 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 應以 parent-tracking 列入並附子項摘要；子項本身則是 assignee-idle。
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]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"}},
+				3: {Number: 3, Title: "父", State: "open", Body: "子項：#7", CreatedAt: at(-700), UpdatedAt: at(-300), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				7: {Number: 7, Title: "子", State: "open", CreatedAt: iso(-650), UpdatedAt: iso(-300), Assignees: []User{{UserName: "max"}}, Repository: &Repository{FullName: "alterminal/teai"}},
+				7: {Number: 7, Title: "子", State: "open", CreatedAt: at(-650), UpdatedAt: at(-300), Assignees: []User{{"max"}}, Repository: Reference{"alterminal/teai"}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/7": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}},
+			"alterminal/teai/7": {{User: User{"max"}, CreatedAt: at(-300)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -289,9 +286,9 @@ func TestScanStalledParentTracking(t *testing.T) {
 	// 子項 1 小時前恢復活動 → 父項 last_activity 跟著更新，未達門檻不列入；
 	// 子項本身也不停滯。整份輸出應為空。
 	child := src.issues["alterminal/teai"][7]
-	child.UpdatedAt = iso(-60)
+	child.UpdatedAt = at(-60)
 	src.issues["alterminal/teai"][7] = child
-	src.comments["alterminal/teai/7"] = []Comment{{User: &User{UserName: "max"}, CreatedAt: iso(-60)}}
+	src.comments["alterminal/teai/7"] = []Comment{{User: User{"max"}, CreatedAt: at(-60)}}
 	got, err = ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -306,11 +303,11 @@ func TestScanStalledParentTrackingNotChild(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]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"}},
+				47: {Number: 47, State: "open", Body: "規劃見 #39（更早）", CreatedAt: at(-700), UpdatedAt: at(-600), Assignees: []User{{"ceo"}}, Repository: Reference{"alterminal/teai"}},
-				39: {Number: 39, State: "open", CreatedAt: iso(-2000), UpdatedAt: iso(-60), Repository: &Repository{FullName: "alterminal/teai"}},
+				39: {Number: 39, State: "open", CreatedAt: at(-2000), UpdatedAt: at(-60), Repository: Reference{"alterminal/teai"}},
 			},
 		},
 	}
@@ -348,30 +345,30 @@ func TestScanStalledPullReasons(t *testing.T) {
 	h := true
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
+		repos: map[string][]Repository{"alterminal": {{Name: "teai", HasPullRequests: &h}}},
 		pulls: map[string][]PullRequest{
 			"alterminal/teai": {
-				{Number: 10, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)},
+				{Number: 10, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)},
-				{Number: 11, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 11, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 12, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 12, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
-				{Number: 13, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-300), RequestedReviewers: []User{{UserName: "ceo"}}},
+				{Number: 13, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-300), RequestedReviewers: []User{{"ceo"}}},
 			},
 		},
 		comments: map[string][]Comment{
-			"alterminal/teai/11": {{User: &User{UserName: "max"}, CreatedAt: iso(-300)}}, // author-idle
+			"alterminal/teai/11": {{User: User{"max"}, CreatedAt: at(-300)}}, // author-idle
-			"alterminal/teai/12": {{User: &User{UserName: "ceo"}, CreatedAt: iso(-300)}}, // reviewer-idle
+			"alterminal/teai/12": {{User: User{"ceo"}, CreatedAt: at(-300)}}, // reviewer-idle
-			"alterminal/teai/13": {{User: &User{UserName: "dan"}, CreatedAt: iso(-300)}}, // no-commenter（外部留言）
+			"alterminal/teai/13": {{User: User{"dan"}, CreatedAt: at(-300)}}, // no-commenter（外部留言）
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
 	}
-	byNumber := map[int64]Item{}
+	byNumber := map[int]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"} {
+	for n, wantReason := range map[int]string{10: "no-reviewer", 11: "author-idle", 12: "reviewer-idle", 13: "no-commenter"} {
 		item, ok := byNumber[n]
 		if !ok {
 			t.Fatalf("PR %d 應列入，got %v", n, got)
@@ -394,15 +391,15 @@ func TestScanStalledNoPullsFlag(t *testing.T) {
 	h := false
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
+		repos: map[string][]Repository{"alterminal": {{Name: "docs", HasPullRequests: &h}}},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]Issue{
 			"alterminal/docs": {
-				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/docs"}},
+				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/docs"}},
 			},
 		},
 		pulls: map[string][]PullRequest{
 			// 即使假資料有 PR，flag 關閉也不應掃。
-			"alterminal/docs": {{Number: 2, User: &User{UserName: "max"}, CreatedAt: iso(-600), UpdatedAt: iso(-600)}},
+			"alterminal/docs": {{Number: 2, State: "open", Author: User{"max"}, CreatedAt: at(-600), UpdatedAt: at(-600)}},
 		},
 	}
 	got, err := ScanStalled(src, "admin", 4.0, now)
@@ -419,10 +416,10 @@ func TestScanStalledSkipsPRsInIssues(t *testing.T) {
 	now := at(0)
 	src := &fakeSource{
 		orgs:  []string{"alterminal"},
-		repos: map[string][]Repo{"alterminal": repoWith("teai", true)},
+		repos: map[string][]Repository{"alterminal": repoWith("teai", true)},
-		issues: map[string]map[int64]Issue{
+		issues: map[string]map[int]Issue{
 			"alterminal/teai": {
-				1: {Number: 1, State: "open", CreatedAt: iso(-600), UpdatedAt: iso(-600), Repository: &Repository{FullName: "alterminal/teai"}, PullRequest: &pullMarker{}},
+				1: {Number: 1, State: "open", CreatedAt: at(-600), UpdatedAt: at(-600), Repository: Reference{"alterminal/teai"}, PullRequest: struct{}{}},
 			},
 		},
 	}
@@ -483,7 +480,7 @@ func TestPullJSON(t *testing.T) {
 // TestScanStalledEmpty 無停滯項目 → 空輸出（CLI 層輸出 []）。
 func TestScanStalledEmpty(t *testing.T) {
 	now := at(0)
-	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repo{"alterminal": repoWith("teai", true)}}
+	src := &fakeSource{orgs: []string{"alterminal"}, repos: map[string][]Repository{"alterminal": repoWith("teai", true)}}
 	got, err := ScanStalled(src, "admin", 4.0, now)
 	if err != nil {
 		t.Fatalf("ScanStalled: %v", err)
@@ -504,15 +501,15 @@ func TestScanStalledOrgError(t *testing.T) {
 type errSource struct{}
 
 func (errSource) MyOrganizations() ([]string, error) { return nil, errors.New("boom") }
-func (e errSource) OrganizationRepositories(string) ([]Repo, error) {
+func (e errSource) OrganizationRepositories(string) ([]Repository, error) {
 	return nil, errors.New("boom")
 }
 func (e errSource) OpenIssues(string, string) ([]Issue, error)      { return nil, errors.New("boom") }
 func (e errSource) OpenPulls(string, string) ([]PullRequest, error) { return nil, errors.New("boom") }
-func (e errSource) IssueComments(string, string, int64) ([]Comment, error) {
+func (e errSource) IssueComments(string, string, int) ([]Comment, error) {
 	return nil, errors.New("boom")
 }
-func (e errSource) TryGetIssue(string, string, int64) (Issue, bool, error) {
+func (e errSource) TryGetIssue(string, string, int) (Issue, bool, error) {
 	return Issue{}, false, errors.New("boom")
 }