From 9e699f3b4ee3ba5efffdf19044c924e2f80dcf39 Mon Sep 17 00:00:00 2001
From: chenyunda218 <chenyunda218@gmail.com>
Date: Sat, 12 Sep 2026 23:43:29 +0800
Subject: [PATCH] =?UTF-8?q?docs+test=EF=BC=9A=E7=A9=BA=E8=BC=B8=E5=87=BA?=
 =?UTF-8?q?=E5=88=A4=E6=B1=BA=20#37=E2=80=94=E2=80=94=E7=B6=AD=E6=8C=81=20?=
 =?UTF-8?q?[]=EF=BC=8Fnull=E3=80=81=E8=A3=9C=20stalled=20=E7=A9=BA?=
 =?UTF-8?q?=E8=BC=B8=E5=87=BA=E6=B8=AC=E8=A9=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                             | 10 +++++++---
 internal/cli/stalled_commands_test.go | 18 ++++++++++++++++++
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d046430..d49457f 100644
--- a/README.md
+++ b/README.md
@@ -299,7 +299,7 @@ teai whoami               # 目前帳號（讀 tea 組態）
 
 | 碼 | 意義 |
 | --- | --- |
-| 0 | 成功（含「沒有工作」→ 輸出 `null`／`[]`） |
+| 0 | 成功（含「沒有結果」→ 清單類命令輸出 `[]`、`next` 輸出 `null`；#37 判決） |
 | 2 | 用法錯誤（未知命令／參數） |
 | 3 | API 錯誤（連線失敗、401、403、5xx） |
 
@@ -318,8 +318,12 @@ teai whoami               # 目前帳號（讀 tea 組態）
 已知輸出差異（刻意保留，機器可讀優先）：
 
 - **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令
-  （`mine`／`pulls`／`milestones` 總覽）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確，
-  交叉驗證時以此差異為準。`next` 兩者語義相同（無工作 → `null`／「沒有未完成的工作」）。
+  （`mine`／`pulls`／`stalled`／`milestones` 總覽）空清單一律輸出 `[]`（exit 0）。對 JSON
+  消費者來說 `[]` 比「無輸出」更明確（可區分「沒有結果」與「查詢失敗無輸出」），交叉驗證時
+  以此差異為準。`next` 兩者語義相同：無工作時 teai 輸出 `null`（exit 0）、`gitea.py` 印
+  「沒有未完成的工作」。**判決 #37：維持 teai 現行 JSON 一致性（方向 2）**——消費端
+  （agents 倉庫巡邏提示與觸發腳本）應以「輸出 `[]`／`null` 且 exit 0」為「沒有」判據，
+  不得以「無輸出」判斷；`members [--has-work]` 維持逐行帳號、空時無輸出（兩者一致，不受影響）。
 - **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件
   （`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位
   （`mine`：repo／number／title／url；`pulls`：number／title／state／author／
diff --git a/internal/cli/stalled_commands_test.go b/internal/cli/stalled_commands_test.go
index 8e1d241..8c1e565 100644
--- a/internal/cli/stalled_commands_test.go
+++ b/internal/cli/stalled_commands_test.go
@@ -117,6 +117,24 @@ func TestWiringStalled(t *testing.T) {
 	}
 }
 
+// TestWiringStalledEmpty 驗證 stalled 無任何條目時輸出 []、exit 0（#37）。
+func TestWiringStalledEmpty(t *testing.T) {
+	newStubStalledEnv(t, &stubStalledSource{
+		username: "ceo",
+		orgs:     []string{"alterminal"},
+		repos:    map[string][]workflow.Repo{"alterminal": {}},
+		issues:   map[string]map[int64]workflow.Issue{},
+		comments: map[string][]workflow.Comment{},
+	}, 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)
+	}
+	if strings.TrimSpace(stdout) != "[]" {
+		t.Fatalf("stalled 無條目應輸出 []，得到 %q", stdout)
+	}
+}
+
 // TestWiringStalledHoursFlag 驗證 --hours 覆寫門檻與非正數被攔。
 func TestWiringStalledHoursFlag(t *testing.T) {
 	freeze := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)
-- 
2.54.0