Files
teai/internal/workflow/workflow.go
T
ceo a86803d336 internal/workflow:xref 解析與 stalled 掃描核心邏輯(#7)
完整移植 gitea.py 的 _resolve_xref_targets 與 find_stalled_work:
- xref:#N/repo#N/owner/repo#N;單段 repo 僅在存在於組織時解析
  (PR#50、issue#49 這類寫法自動略過);owner 需為所屬組織。
  Go regexp 無 lookbehind,掃描時檢查前一字元等價實作。
- stalled:reason 分類(issue:no-assignee/assignee-idle/no-commenter/
  waiting-outside/parent-tracking;PR:no-reviewer/author-idle/
  reviewer-idle/no-commenter)、24h 催促冷卻、父追蹤項把子項活動
  (留言、state 變更、PR 合併)計入 last_activity、上行引用不採計。
- 資料以 Source 介面注入:邏輯離線可測,CLI 接線待 #5 基礎建設。
- 輸出 JSON 與 gitea.py 位元組相容(鍵序、assignees/author 欄位、
  isoformat 時刻、round(x,1) 半偶數舍入)。
- cmd/xcheck:交叉驗證工具(--xrefs 與停滯掃描模式),已對真實 API
  與 gitea.py 並行比對,輸出一致。

go build/vet/test 全綠;單元測試覆蓋 xref 邊界與 stalled 判定。
2026-09-10 08:36:31 +08:00

602 lines
18 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 套件 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 (
"encoding/json"
"fmt"
"regexp"
"sort"
"strconv"
"strings"
"time"
)
// 常數與 gitea.py 保持一致(STALLED_DEFAULT_HOURS、NUDGE_COOLDOWN_HOURS)。
const (
// StalledDefaultHours 是 stalled 掃描的預設門檻(小時)。
StalledDefaultHours = 4.0
// NudgeCooldownHours 是「最後留言出自目前帳號」項目的催促冷卻(小時)。
NudgeCooldownHours = 24.0
)
// xrefPattern 對應 gitea.py 的 XREF_PATTERN:#N、repo#N、owner/repo#N。
//
// 前面不得是文數字/底線/斜線(避免切進 alterminal/bear#47 的後半段);
// owner/repo 兩段之間必須有斜線(避免把 bear-cli#10 誤判成 cli#10)。
// Go 的 regexp 不支援 lookbehind,改在掃描時檢查前一字元。
var xrefPattern = regexp.MustCompile(`([A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?)?#(\d+)`)
// User 是 Gitea user 物件的精簡投影。
type User struct {
Username string `json:"username"`
}
// Comment 是 issue/PR 留言的精簡投影。
type Comment struct {
User User `json:"user"`
Body string `json:"body"`
CreatedAt time.Time `json:"created_at"`
}
// Author 回傳留言作者帳號;空字串表示無法判定。
func (c Comment) Author() string { return c.User.Username }
// Issue 是 issue 的精簡投影(Gitea /repos/{owner}/{repo}/issues,不含 PR)。
type Issue struct {
Number int `json:"number"`
Title string `json:"title"`
State string `json:"state"`
Body string `json:"body"`
Author User `json:"user"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ClosedAt *time.Time `json:"closed_at,omitempty"`
// URL 對應 API 的 html_url。
URL string `json:"html_url"`
Assignees []User `json:"assignees"`
Repository Reference `json:"repository"`
// PullRequest 非 nil 表示這其實是 PR(Gitea 的 /issues API 兩者都回)。
PullRequest any `json:"pull_request,omitempty"`
}
// Reference 是 repository 物件的精簡投影(issue 物件帶 full_name)。
type Reference struct {
FullName string `json:"full_name"`
}
// Ref 是 PR base/head 的精簡投影(PR 物件沒有 repository 欄位,改讀 base/head.repo)。
type Ref struct {
Repo Reference `json:"repo"`
}
// PullRequest 是 /repos/{owner}/{repo}/pulls 物件的精簡投影。
type PullRequest struct {
Number int `json:"number"`
Title string `json:"title"`
State string `json:"state"`
Author User `json:"user"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ClosedAt *time.Time `json:"closed_at,omitempty"`
// URL 對應 API 的 html_url。
URL string `json:"html_url"`
Base Ref `json:"base"`
Head Ref `json:"head"`
RequestedReviewers []User `json:"requested_reviewers"`
}
// FullName 回傳 "owner/repo";PR 沒有 repository 欄位,改讀 base(再退 head)。
func (p PullRequest) FullName() string {
if p.Base.Repo.FullName != "" {
return p.Base.Repo.FullName
}
return p.Head.Repo.FullName
}
// Repository 是 /orgs/{org}/repos 物件的精簡投影。
type Repository struct {
Name string `json:"name"`
Empty bool `json:"empty"`
HasPullRequests *bool `json:"has_pull_requests"`
}
// Item 是 stalled 掃描的單筆輸出(欄位對應 gitea.py 的 find_stalled_work)。
type Item struct {
Type string
Repo string
Number int
Title string
URL string
Assignees []string
Author string
Reviewers []string
LastCommentBy string
LastActivityAt time.Time
StalledHours float64
Reason string
ChildActivity []Child
}
// MarshalJSON 輸出鍵集與鍵序與 gitea.py 完全一致的物件:
// issue 帶 assignees;pull 帶 author 與 reviewers;
// child_activity 僅在有子項摘要時輸出。
func (i Item) MarshalJSON() ([]byte, error) {
var b strings.Builder
b.WriteString(`{"type":`)
writeJSON(&b, i.Type)
b.WriteString(`,"repo":`)
writeJSON(&b, i.Repo)
b.WriteString(`,"number":`)
fmt.Fprintf(&b, "%d", i.Number)
b.WriteString(`,"title":`)
writeJSON(&b, i.Title)
b.WriteString(`,"url":`)
writeJSON(&b, i.URL)
if i.Type == "pull" {
b.WriteString(`,"author":`)
writeJSON(&b, i.Author)
b.WriteString(`,"reviewers":`)
writeJSON(&b, i.Reviewers)
} else {
b.WriteString(`,"assignees":`)
writeJSON(&b, i.Assignees)
}
b.WriteString(`,"last_comment_by":`)
writeJSON(&b, i.LastCommentBy)
b.WriteString(`,"last_activity_at":`)
writeJSON(&b, FormatMoment(i.LastActivityAt))
b.WriteString(`,"stalled_hours":`)
fmt.Fprintf(&b, "%g", i.StalledHours)
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")
}
func writeJSON(b *strings.Builder, v any) {
enc, err := json.Marshal(v)
if err != nil {
return
}
b.Write(enc)
}
// Child 是父追蹤項的子項活動摘要。
type Child struct {
Repo string `json:"repo"`
Number int `json:"number"`
Title string `json:"title"`
State string `json:"state"`
LastActivityAt string `json:"last_activity_at"`
}
// XrefTarget 是解析後的引用目標(owner、repo、number)。
type XrefTarget struct {
Owner string
Repo string
Number int
}
// Source 是 stalled 掃描需要的資料源(CLI 層以 API 實作;測試注入假資料)。
type Source interface {
// MyOrganizations 回傳目前帳號所屬組織清單。
MyOrganizations() ([]string, error)
// OrganizationRepositories 回傳組織的倉庫清單。
OrganizationRepositories(org string) ([]Repository, error)
// OpenIssues 回傳倉庫的 open issues(Gitea 會混入 PR,由掃描端過濾)。
OpenIssues(owner, repo string) ([]Issue, error)
// OpenPulls 回傳倉庫的 open pull requests。
OpenPulls(owner, repo string) ([]PullRequest, error)
// IssueComments 回傳 issue/PR 的留言。
IssueComments(owner, repo string, number int) ([]Comment, error)
// TryGetIssue 寬容版單一 issue 查詢:失敗(含 404)回 (零值, false, nil)。
TryGetIssue(owner, repo string, number int) (Issue, bool, error)
}
// iterXrefs 產出文字中的 (prefix, number) 配對(對應 _iter_issue_xrefs)。
// 前一字元是文數字/底線/斜線者略過(Python lookbehind 的等價實作)。
func iterXrefs(text string) [][2]string {
var out [][2]string
for _, m := range xrefPattern.FindAllStringIndex(text, -1) {
start := m[0]
if start > 0 {
prev := rune(text[start-1])
if isWordChar(prev) || prev == '/' {
continue
}
}
match := text[m[0]:m[1]]
i := strings.IndexByte(match, '#')
prefix := match[:i]
number := match[i+1:]
out = append(out, [2]string{prefix, number})
}
return out
}
func isWordChar(r rune) bool {
return r == '_' || isAlnum(r)
}
func isAlnum(r rune) bool {
return (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9')
}
// ResolveXrefTargets 把內文/留言中的引用解析成目標清單(對應 _resolve_xref_targets)。
//
// 單段 #N 指向父項所在倉庫;單段 repo#N 需 repo 存在於父項所屬組織
// (「PR#50」這類寫法因 repo 不存在而自動略過);owner/repo#N 需 owner
// 為目前帳號所屬組織(跨倉庫子項,如 bear-cli#9 → bear#35 的同組織判定)。
// 去重、保留出現順序。
func ResolveXrefTargets(org, repo string, texts []string, myOrgs map[string]bool, orgRepos func(org string) ([]string, error)) ([]XrefTarget, error) {
var resolved []XrefTarget
seen := map[XrefTarget]bool{}
var orgRepoSet map[string]bool
for _, text := range texts {
for _, pair := range iterXrefs(text) {
prefix, numberStr := pair[0], pair[1]
var number int
if _, err := fmt.Sscanf(numberStr, "%d", &number); err != nil || number <= 0 {
continue
}
var target XrefTarget
switch {
case strings.Contains(prefix, "/"):
parts := strings.SplitN(prefix, "/", 2)
owner, name := parts[0], parts[1]
if owner != "" && name != "" && myOrgs[owner] {
target = XrefTarget{owner, name, number}
}
case prefix != "":
if orgRepoSet == nil {
names, err := orgRepos(org)
if err != nil {
return nil, err
}
orgRepoSet = map[string]bool{}
for _, n := range names {
orgRepoSet[n] = true
}
}
if orgRepoSet[prefix] {
target = XrefTarget{org, prefix, number}
}
default:
target = XrefTarget{org, repo, number}
}
if target != (XrefTarget{}) && !seen[target] {
seen[target] = true
resolved = append(resolved, target)
}
}
}
return resolved, nil
}
// childActivity 計算父追蹤項的子項活動(對應 _child_activity)。
//
// 只採計向下引用:子項建立時間需晚於父項(父項內文回指更早的規劃 issue
// 是上行引用,不採計)。資料源失敗(含編號不存在)靜默略過,不影響掃描。
func childActivity(src Source, org, repo string, parent Issue, comments []Comment, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (moments []time.Time, children []Child) {
texts := []string{parent.Body}
for _, c := range comments {
texts = append(texts, c.Body)
}
targets, err := ResolveXrefTargets(org, repo, texts, myOrgs, orgRepos)
if err != nil {
return nil, nil
}
for _, t := range targets {
child, ok, gerr := src.TryGetIssue(t.Owner, t.Repo, t.Number)
if gerr != nil || !ok {
continue
}
if t.Owner == org && t.Repo == repo && child.Number == parent.Number {
continue // 自我引用
}
if !parent.CreatedAt.IsZero() && !child.CreatedAt.IsZero() && !child.CreatedAt.After(parent.CreatedAt) {
continue // 上行引用(父項回指更早或同時的 issue);時間未知則不排除
}
var ms []time.Time
if !child.UpdatedAt.IsZero() {
ms = append(ms, child.UpdatedAt)
}
if child.ClosedAt != nil && !child.ClosedAt.IsZero() {
ms = append(ms, *child.ClosedAt)
}
if cs, cerr := src.IssueComments(t.Owner, t.Repo, t.Number); cerr == nil {
for _, c := range cs {
if !c.CreatedAt.IsZero() {
ms = append(ms, c.CreatedAt)
}
}
}
var last string
if len(ms) > 0 {
latest := maxTime(ms)
moments = append(moments, latest)
last = latest.Format(time.RFC3339)
}
children = append(children, Child{
Repo: t.Owner + "/" + t.Repo,
Number: child.Number,
Title: child.Title,
State: child.State,
LastActivityAt: last,
})
}
return moments, children
}
func maxTime(ts []time.Time) time.Time {
best := ts[0]
for _, t := range ts[1:] {
if t.After(best) {
best = t
}
}
return best
}
func usernames(users []User) []string {
var out []string
seen := map[string]bool{}
for _, u := range users {
if u.Username == "" || seen[u.Username] {
continue
}
seen[u.Username] = true
out = append(out, u.Username)
}
sort.Strings(out)
return out
}
// ScanStalled 掃描跨組織的停滯 open issues/PR(對應 find_stalled_work)。
//
// 判定:最後活動(留言時間與本身 updated_at 取較晚者,父追蹤項再加計
// 子項活動)距今超過 threshold 小時。刻意包含拾取死角形態:最後一則留言
// 出自 assignee/PR 作者本人且超過時限——工作休眠、無人催促。最後留言
// 出自目前帳號(username)的項目在冷卻期間不列入(已催促過);冷卻後
// 仍停滯會再出現。輸出依停滯時間由長到短排序。
func ScanStalled(src Source, username string, threshold float64, now time.Time) ([]Item, error) {
orgs, err := src.MyOrganizations()
if err != nil {
return nil, err
}
myOrgs := make(map[string]bool, len(orgs))
for _, o := range orgs {
myOrgs[o] = true
}
orgRepos := func(org string) ([]string, error) {
repos, err := src.OrganizationRepositories(org)
if err != nil {
return nil, err
}
names := make([]string, 0, len(repos))
for _, r := range repos {
if r.Name != "" {
names = append(names, r.Name)
}
}
return names, nil
}
var items []Item
for _, org := range orgs {
repos, err := src.OrganizationRepositories(org)
if err != nil {
continue
}
for _, r := range repos {
if r.Name == "" || r.Empty {
continue
}
// 停用 PR 的倉庫沒有 PR 可掃;issues 照常(gitea.py _iter_open_issues 不檢查此欄位)。
scanPulls := r.HasPullRequests == nil || *r.HasPullRequests
issues, err := src.OpenIssues(org, r.Name)
if err != nil {
continue
}
for _, issue := range issues {
if issue.PullRequest != nil {
continue
}
comments, err := src.IssueComments(org, r.Name, issue.Number)
if err != nil {
continue
}
item, ok := considerIssue(src, org, r.Name, issue, comments, username, threshold, now, myOrgs, orgRepos)
if ok {
items = append(items, item)
}
}
if !scanPulls {
continue
}
pulls, err := src.OpenPulls(org, r.Name)
if err != nil {
continue
}
for _, pr := range pulls {
comments, err := src.IssueComments(org, r.Name, pr.Number)
if err != nil {
continue
}
if item, ok := considerPull(pr, comments, username, threshold, now); ok {
items = append(items, item)
}
}
}
}
sort.SliceStable(items, func(i, j int) bool {
return items[i].StalledHours > items[j].StalledHours
})
return items, nil
}
// considerIssue 對單一 issue 套用停滯判定(對應 _consider 的 issue 分支)。
func considerIssue(src Source, org, repo string, issue Issue, comments []Comment, username string, threshold float64, now time.Time, myOrgs map[string]bool, orgRepos func(string) ([]string, error)) (Item, bool) {
childMoments, children := childActivity(src, org, repo, issue, comments, myOrgs, orgRepos)
assignees := usernames(issue.Assignees)
moments := []time.Time{issue.UpdatedAt, issue.CreatedAt}
for _, c := range comments {
if !c.CreatedAt.IsZero() {
moments = append(moments, c.CreatedAt)
}
}
moments = append(moments, childMoments...)
moments = nonZero(moments)
if len(moments) == 0 {
return Item{}, false
}
lastActivity := maxTime(moments)
stalled := now.Sub(lastActivity).Hours()
if stalled < threshold {
return Item{}, false
}
lastCommentAt, lastCommentBy := lastComment(comments)
if lastCommentBy == username && !lastCommentAt.IsZero() &&
now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
return Item{}, false
}
reason := "waiting-outside"
switch {
case len(assignees) == 0:
reason = "no-assignee"
case lastCommentBy != "" && containsStr(assignees, lastCommentBy):
reason = "assignee-idle"
case lastCommentBy == "":
reason = "no-commenter"
}
if len(children) > 0 && anyOpen(children) {
reason = "parent-tracking"
}
item := Item{
Type: "issue", Repo: issue.Repository.FullName, Number: issue.Number,
Title: issue.Title, URL: issue.URL,
Assignees: assignees,
LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
StalledHours: round1(stalled), Reason: reason,
}
if len(children) > 0 {
item.ChildActivity = children
}
return item, true
}
// considerPull 對單一 PR 套用停滯判定(對應 _consider 的 pull 分支)。
func considerPull(pr PullRequest, comments []Comment, username string, threshold float64, now time.Time) (Item, bool) {
reviewers := usernames(pr.RequestedReviewers)
author := pr.Author.Username
moments := []time.Time{pr.UpdatedAt, pr.CreatedAt}
for _, c := range comments {
if !c.CreatedAt.IsZero() {
moments = append(moments, c.CreatedAt)
}
}
moments = nonZero(moments)
if len(moments) == 0 {
return Item{}, false
}
lastActivity := maxTime(moments)
stalled := now.Sub(lastActivity).Hours()
if stalled < threshold {
return Item{}, false
}
lastCommentAt, lastCommentBy := lastComment(comments)
if lastCommentBy == username && !lastCommentAt.IsZero() &&
now.Sub(lastCommentAt).Hours() < NudgeCooldownHours {
return Item{}, false
}
reason := "no-commenter"
switch {
case len(reviewers) == 0:
reason = "no-reviewer"
case lastCommentBy == author:
reason = "author-idle"
case lastCommentBy != "" && containsStr(reviewers, lastCommentBy):
reason = "reviewer-idle"
}
item := Item{
Type: "pull", Repo: pr.FullName(), Number: pr.Number,
Title: pr.Title, URL: pr.URL,
Author: author, Reviewers: reviewers,
LastCommentBy: lastCommentBy, LastActivityAt: lastActivity,
StalledHours: round1(stalled), Reason: reason,
}
return item, true
}
// lastComment 回傳最後一則留言(created_at 最新者)的時間與作者。
func lastComment(comments []Comment) (time.Time, string) {
var best time.Time
by := ""
for _, c := range comments {
if c.CreatedAt.After(best) {
best = c.CreatedAt
by = c.Author()
}
}
return best, by
}
func anyOpen(children []Child) bool {
for _, c := range children {
if c.State == "open" {
return true
}
}
return false
}
func containsStr(list []string, s string) bool {
for _, x := range list {
if x == s {
return true
}
}
return false
}
func nonZero(ts []time.Time) []time.Time {
out := make([]time.Time, 0, len(ts))
for _, t := range ts {
if !t.IsZero() {
out = append(out, t)
}
}
return out
}
// round1 舍入到小數一位(對應 Python round(x, 1))。
// 經 strconv 的十進位正確舍入(半偶數),與 Python 的浮點 round 行為一致,
// 避免 (x*10+0.5) 截斷在 .x5 邊界產生偏差。
func round1(v float64) float64 {
r, err := strconv.ParseFloat(strconv.FormatFloat(v, 'f', 1, 64), 64)
if err != nil {
return v
}
return r
}