Compare commits
19 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 claude-code
|
eb6c427421 | ||
|
claude-code
|
c6eb269551 | ||
|
claude-code
|
bc02c2645b | ||
|
claude-code
|
ca10e1db30 | ||
|
claude-code
|
5f6995b892 | ||
|
claude-code
|
395d885ceb | ||
|
claude-code
|
a7ca29c180 | ||
|
claude-code
|
ba30c49876 | ||
|
claude-code
|
4eed944f68 | ||
|
claude-code
|
b6405b2a5c | ||
|
claude-code
|
521dda1b47 | ||
|
claude-code
|
90ed988d84 | ||
|
claude-code
|
d301810fb6 | ||
|
claude-code
|
e575786be3 | ||
|
claude-code
|
5d6c4b5d63 | ||
|
claude-code
|
45adc10a52 | ||
 claude-code
|
07cb5e4e55 | ||
|
claude-code
|
67f5f0fa5e | ||
|
claude-code
|
f3a41fba0e |
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "isep",
|
||||
"description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：54 支機械閘（71 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、40 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。",
|
||||
"version": "0.13.0",
|
||||
"description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：55 支機械閘（72 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、48 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。",
|
||||
"version": "0.14.0",
|
||||
"keywords": [
|
||||
"inkstone",
|
||||
"guardrails",
|
||||
|
||||
@@ -23,10 +23,24 @@
|
||||
|
||||
| | 數量 | 是什麼 |
|
||||
|---|---|---|
|
||||
| `hooks/` | 48 支 ＋ `hooks.json` | 全部機械閘（PreToolUse／Stop／SubagentStop／SessionStart／PostToolUse 共 59 條註冊；`ISEP#60` 移除 `claim-verify-police.sh`／`subagent-claim-worksheet.sh` 這對自造機制，改由 Gitea 原生三格承接見 `ISEP#59`） |
|
||||
| `hooks/` | 54 支 ＋ `hooks.json` | 全部機械閘（PreToolUse／Stop／SubagentStop／SessionStart／PostToolUse 共 69 條註冊，2026-08-28 在樹上實數；`ISEP#60` 移除 `claim-verify-police.sh`／`subagent-claim-worksheet.sh` 這對自造機制，改由 Gitea 原生三格承接見 `ISEP#59`） |
|
||||
| `hooks/` | 54 支 ＋ `hooks.json` | 全部機械閘（PreToolUse／Stop／SubagentStop／SessionStart／PostToolUse 共 71 條註冊。**一支一行的白話盤點在 `docs/hooks-inventory.md`，那裡才是這兩個數字的家**） |
|
||||
| `commands/` | 7 支 | `/wiki-recall` `/ship-check` `/cp-write` … |
|
||||
| `skills/` | 2 支 | |
|
||||
| `scripts/` | 23 支 | `ticket`／`github-arm.sh`／`gitea-bootstrap.sh` … |
|
||||
| `scripts/` | 38 支 | `ticket`／`github-arm.sh`／`gitea-bootstrap.sh` …（頂層檔案，不含 `lib/` 等子目錄） |
|
||||
|
||||
> 🔴 **這四個數字要用數的，不要用推的**（2026-08-28：上一版寫 48／59／23，
|
||||
> 而真實是 54／71／38——三個都錯，錯了不知道多久）。重數一次：
|
||||
>
|
||||
> ```sh
|
||||
> ls hooks/*.sh | wc -l # hooks
|
||||
> ls commands/*.md | wc -l ; ls -d skills/*/ | wc -l
|
||||
> find scripts -maxdepth 1 -type f | wc -l # scripts（頂層）
|
||||
> python3 -c "import json;h=json.load(open('hooks/hooks.json'));h=h.get('hooks',h);\
|
||||
> print(sum(len(m.get('hooks',[])) for ev in h.values() for m in ev))" # 註冊條數
|
||||
> ```
|
||||
>
|
||||
> **這是 leo 的驗收介面**——多報就是假綠（`docs/hooks-inventory.md` 開頭記著同一個病）。
|
||||
|
||||
**不放**：`.env`（金鑰，違 D36「金鑰只有一個家」）、`wiki/`、`docs/`、`_archive/`
|
||||
——那些是**知識**不是**環境**。
|
||||
|
||||
+144
@@ -208,6 +208,67 @@ bash hooks/tests/prod-write-guard.test.sh hooks/prod-write-guard.sh
|
||||
- 「卡點二」2 條任一紅 ⇒ 「談論它」又被當成「執行它」（同款第八次），
|
||||
或是剝了內文之後連真的部署都放行了
|
||||
|
||||
### A16 — 一次交貨 ＝ 一份清單（跨 repo 版本組合）：21 條
|
||||
```
|
||||
bash scripts/test-release-manifest.sh
|
||||
```
|
||||
**該看到**：`通過 21 條，失敗 0 條`。全程離線（`RELEASE_MANIFEST_FIXTURE`），
|
||||
**不打 Gitea、不建任何真的 release**；清單寫在 `mktemp` 的目錄，不碰 repo 裡的 `releases/`。
|
||||
|
||||
**它在守什麼**（`inkstone/ISEP#84`）：一次交貨常常同時動到好幾個 repo，
|
||||
而「這一版 ＝ 哪幾個 repo 的哪幾版」**沒有任何地方記著** ⇒ 退版只退了其中一個，
|
||||
剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。
|
||||
|
||||
**失敗**：
|
||||
- ⑨⑩ 紅 ⇒ 驗收 1 沒過：**版本號寫上去就算數**，沒有真的去 Gitea 抓過
|
||||
（「寫上去」跟「存在」是兩件事，而清單的用處完全建立在後者）
|
||||
- ⑱ 紅 ⇒ 驗收 3 沒過：**只退其中一個 repo 沒有被擋下來**，那正是票上那個病
|
||||
- ⑯⑰⑲ 任一紅 ⇒ 驗收 2 沒過：退版沒有吐出整份清單的每一格
|
||||
（包含「已經在目標版本、不必動」那幾格——列出來才證明沒有一格被漏掉）
|
||||
- ⑫ 紅 ⇒ 凍結過的清單還能再加東西，「凍結」兩個字就沒有意義了
|
||||
- ⑳㉑ 紅 ⇒ 驗收 4 沒過：leo 打開 `INDEX.md` 看不出「我現在手上是哪一版」
|
||||
|
||||
### A17 — 每次結案都留下估多久／花多久／差多少：23 條
|
||||
```
|
||||
bash scripts/test-milestone-account.sh
|
||||
```
|
||||
**該看到**：`通過 23 條，失敗 0 條`。全程離線（`MILESTONE_ACCOUNT_FIXTURE` ＝一份假的
|
||||
Gitea 回應表），時鐘用 `MILESTONE_ACCOUNT_NOW` 定住，帳本寫在 `mktemp` 目錄，
|
||||
**不打 Gitea、不關任何真的 milestone**。
|
||||
|
||||
**它在守什麼**（`inkstone/ISEP#85`，leo 2026-08-27 說那天「**拖時間**」）：
|
||||
拖了多久、比預計多拖多少、為什麼拖——**沒有任何數字**。偵測器早就有了
|
||||
（`mainline-idle-guard.sh`／`factory-idle-guard.sh`），**但沒有人把它算成帳**。
|
||||
|
||||
**失敗**：
|
||||
- ①②③④ 任一紅 ⇒ 驗收 1 沒過：三個數字不是自己算出來的
|
||||
- ⑤⑥ 紅 ⇒ 驗收 2 沒過：差超過 ±25% 卻能不挑代號就結案
|
||||
- ⑧ 紅 ⇒ 代號不再是封閉集合。**能統計的前提是分類有限**，這一格垮了統計就垮了
|
||||
- ⑨ 紅 ⇒ **挑一個時間軸撐不住的代號也能過**，等於「採信我自己說的」，
|
||||
而票上寫死證據一律從 Gitea 的時間軸取
|
||||
- ⑦ 紅 ⇒ **誤攔**：只差 -6% 也逼人挑代號。這比漏擋嚴重——每次結案都被念，
|
||||
人就學會繞過去
|
||||
- ⑭⑮⑯⑰ 任一紅 ⇒ 驗收 3 沒過：累積之後看不出哪一種原因最常發生
|
||||
- ⑱⑲ 紅 ⇒ 驗收 4 沒過：拿已經逾期的里程碑進去算不出數字
|
||||
|
||||
### A18 — 結案要記帳的那道閘：22 條
|
||||
```
|
||||
bash hooks/tests/milestone-account-guard.test.sh
|
||||
```
|
||||
**該看到**：`通過 22 條，失敗 0 條`。離線（帳本走 `MILESTONE_ACCOUNT_LEDGER`），
|
||||
純結構判斷、沒有語意判官，所以每次結果都一樣。
|
||||
|
||||
**失敗**：
|
||||
- **A 群任何一條紅 ⇒ 誤攔，這比漏擋嚴重。** ⑥⑦⑧⑪ 特別重要：
|
||||
`echo` 一段指令、`cat` 這支閘自己、commit 訊息裡提到、把指令寫進文件的 heredoc 內文
|
||||
——**四種都只是「談論它」，不是「執行它」**。這四格是本 repo 撞過很多次的同一個病
|
||||
（`strip_heredoc.py` 的檔頭記著兩次真跡）
|
||||
- ⑨⑩ 紅 ⇒ 走正門 `scripts/milestone-account close` 反而被自己的閘擋下，
|
||||
那道閘就等於封死了唯一的出路
|
||||
- ⑭⑮⑯⑰⑱ 任一紅 ⇒ 漏擋：換個寫法（`python urllib`、前面串一個無害指令、
|
||||
`--request` 長寫法、換一個 repo）就繞過去了
|
||||
- ⑲ 紅 ⇒ 訊息沒有點名目標，人看完不知道要對哪一個里程碑動手
|
||||
- ⑳㉑ 紅 ⇒ 「記過帳就放行」這個出路是假的，或者一記帳就把所有里程碑全開了
|
||||
### A16 — 「總管可以放行」那道門真的打得開：17 條
|
||||
```
|
||||
bash hooks/tests/gate-ok.test.sh
|
||||
@@ -268,6 +329,84 @@ bash hooks/tests/isep-presence-beacon.test.sh
|
||||
- ⑤⑦ 紅 ⇒ 舊複本遮蔽正門抓不到（`InkStoneCo/scripts/ticket` 那件）
|
||||
- ⑥ 紅 ⇒ **誤攔**：同步過的複本被念，人就學會忽略它
|
||||
- ⑪ 紅 ⇒ 內層迴圈變數撞名的回歸（同一個 `.claude` 下第二個殘骸會被靜靜跳過）
|
||||
### A19 — 下游做完時頂層跟著關：49 條
|
||||
```
|
||||
bash scripts/test-ticket-handoff-writeback.sh
|
||||
```
|
||||
**該看到**：`通過 49 條，失敗 0 條`。**全程離線**——`TICKET_HOST` 指到連不上的位址，
|
||||
會打 API 的兩段（`_writeback`／`cmd_subtask`）把 `api()` 換成錄音機跑，
|
||||
**不打真實 Gitea、不開票、不關票、不留任何測試票**。
|
||||
|
||||
**它在守什麼**（`inkstone/ISEP#92`）：
|
||||
「開在頂層的票，下游做完了卻沒人回來關⋯⋯頂層票會永遠掛著，**而 leo 是看頂層的**。」
|
||||
|
||||
四格對應票上的四條驗收條件：
|
||||
- ①②③ 純函式（`is_loose`／`writeback_plan`／`journey_label`）——**判準本身**，
|
||||
不必開真票就驗得動
|
||||
- ④⑤ `subtask`／`handoff` 的參數閘：該擋的擋、齊全的放得過
|
||||
- ⑦ **完工回寫的接線**（驗收第 2 條）：關掉一張下游票之後，它到底對頂層票做了什麼
|
||||
- ⑧ **雙向連結的接線**（驗收第 1 條）：兩張票互相看得到對方，不是靠人記得補
|
||||
|
||||
**失敗**：
|
||||
- ①「open ＋ 從來沒有下游 → 不撈」紅 ⇒ **誤攔**：`ticket loose` 會把每一張普通票
|
||||
都列出來，那張表就變成雜訊，人學會忽略它（本 repo 心法第 2 條）
|
||||
- ②「還有別的下游沒關 → 只記一筆」紅 ⇒ 母票會在下游還沒做完時被指派回總管，
|
||||
假綠
|
||||
- ⑦「沒有去關母票」變綠 ⇒ 回寫從「處理」滑成「自動關掉」。
|
||||
**默默關掉跟默默留著是同一個病的兩面**——關票要有交付物、要有人看過
|
||||
- ⑦「留言第一行有身份欄」紅 ⇒ 機器貼的留言看起來像某個人寫的，
|
||||
下一個讀票的人會去找那個人（`reply-identity-guard` 管的是同一件事）
|
||||
- ⑧「母子兩端都被貼」剩 1 ⇒ journey 只貼了一端，**聚類時撈得到一半**，
|
||||
比完全沒貼更危險
|
||||
- ⑤ 任何一條紅 ⇒ 誤攔，合規的交辦被擋掉等於這條路不能走
|
||||
|
||||
🔴 **這支測不到的那一格（要 leo 或總管接手）**：`labels.yaml` 的 `j/` 段
|
||||
**刻意是空的**——旅程怎麼切、叫什麼名字是方向題，不由工具代決。
|
||||
在有人往那裡加第一條旅程之前，`--journey` 只會擋、不會貼。
|
||||
機制驗過了，**資料還沒有**。
|
||||
|
||||
### A20 — 舊票每天有固定管道被撈出來：47 條
|
||||
```
|
||||
bash scripts/test-debt-worklist.sh
|
||||
```
|
||||
**該看到**：`通過 47 條，失敗 0 條`。**全程離線**：資料走 `ISEP_DEBT_FIXTURE`、
|
||||
時鐘走 `ISEP_DEBT_NOW`、狀態走 `ISEP_DEBT_STATE_DIR`、主線走 `ISEP_COUNTDOWN_STATE_DIR`
|
||||
——**不打 Gitea、不留測試票、不碰 `$HOME`**。
|
||||
|
||||
**它在守什麼**（`inkstone/ISEP#83`，leo 2026-08-27）：
|
||||
「現在每天都在追新的，所以**要用 Routine 去消化舊的**，可以有多個條件」。
|
||||
全 org 229 張 open 票，每天在動的只有掛在 open milestone 上的那 56 張；
|
||||
其餘的不是不重要，是**沒有任何機制會去拿它們**。
|
||||
|
||||
🔴 **兩條線各用各的判準，不是二選一**（leo 當場訂正總管的誤解）：
|
||||
掛 milestone ＝緊急線，用「距離目標的遠近」排；沒掛的＝還債線，用多條件排
|
||||
（事故／擋人／承諾／票齡／估工）——後者就是 `scripts/debt-worklist`。
|
||||
|
||||
**失敗**：
|
||||
- 「驗收 1」那組紅 ⇒ 清單沒有附「我查了哪些 repo」的證明。
|
||||
**沒有證明的清單分不出「今天真的沒有」與「查詢壞了」**，而後者會靜靜地零產出
|
||||
- 「驗收 2」紅 ⇒ 空清單默默結束。這是這支工具最貴的失效方式：
|
||||
它看起來跑完了，於是沒有人再去看那 180 張
|
||||
- 「驗收 3」紅 ⇒ 領走的票明天又冒出來，這份清單就會變成每天一樣的一坨，人就不看了
|
||||
- 「成包」兩條紅 ⇒ 互相指著／母子票被拆開領，做到一半才發現卡在另一張
|
||||
- **「單向引用不成包」紅 ⇒ 這是誤攔的那一面**：第一版用單向引用成包，
|
||||
結果 190 張裡 121 張黏成一包（大家都會順手引用 hub 票）＝**一包沒有人領得動**
|
||||
- 「接上主線」那組紅 ⇒ 還債線又自己養了一套「哪個是 active」的判斷。
|
||||
唯一答案在 `hooks/lib/mainline.py`（`inkstone/ISEP#82`），**兩份必然漂移**。
|
||||
特別看「沒標主線」那兩條：**沒有答案時要退回保守**（掛 open milestone 的一律不領），
|
||||
不准猜一條出來
|
||||
- 最後一組（SessionStart）紅 ⇒ 要嘛沒有人會被提醒去撈，
|
||||
要嘛那一段偷偷去打網路——**開 session 自動撈就是輪詢**，紅線擋著
|
||||
|
||||
**手動驗真實資料**（會打 Gitea，唯讀 GET）：
|
||||
```
|
||||
python3 scripts/debt-worklist list --top 5
|
||||
```
|
||||
**該看到**：15 個 repo 逐一列出 issue／PR 數，講得出**現在的主線是哪一條**
|
||||
（或誠實說沒標），扣除數字講得出來（掛 open milestone 的幾張、等 leo 的幾張、已領走的幾張），
|
||||
前幾名旁邊看得到「為什麼排這裡」的分項。
|
||||
**失敗**：前幾名一眼看不出為什麼在那裡 ⇒ 那些權重就是錯的，去改 `score()`，
|
||||
**不要改成「總管覺得」**——這份清單的價值就在於它不靠記憶。
|
||||
|
||||
### A5 — 開票前的搜尋是跨 repo 的
|
||||
```
|
||||
@@ -466,6 +605,9 @@ B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面
|
||||
| **A15 pr-verdict --dry-run** | 總管 | ✅（2026-08-28） |
|
||||
| **A14 回覆自己說出拖了多久** | 總管 | ✅ 20/20（2026-08-28，inkstone/ISEP#63） |
|
||||
| **A15 發通知不等於部署** | 總管 | ✅ 37/37（2026-08-28，inkstone/ISEP#63） |
|
||||
| **A16 跨 repo 版本清單** | 總管 | ✅ 21/21（2026-08-28，inkstone/ISEP#84） |
|
||||
| **A17 估多久／花多久／差多少** | 總管 | ✅ 23/23（2026-08-28，inkstone/ISEP#85） |
|
||||
| **A18 結案要記帳的閘** | 總管 | ✅ 22/22（2026-08-28，inkstone/ISEP#85） |
|
||||
| A5 搜尋跨 repo | 總管 | ✅ |
|
||||
| A6 標籤對齊＋冪等 | 總管 | ✅ 14 repo，第二次 0/0 |
|
||||
| **A9 人閘警察管路** | 總管 | ✅ 14/14（2026-08-26） |
|
||||
@@ -475,6 +617,8 @@ B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面
|
||||
| **A16 放行的門真的打得開** | 總管 | ✅ 17/17（2026-08-28，inkstone/ISEP#90） |
|
||||
| **A17 未推警察不誤攔雲端分支** | 總管 | ✅ 10/10（2026-08-28，inkstone/ISEP#90） |
|
||||
| **A18 信標會報雲端接線缺陷** | 總管 | ✅ 14/14（2026-08-28，inkstone/ISEP#90） |
|
||||
| **A19 下游做完頂層跟著關** | 總管 | ✅ 49/49（2026-08-28，inkstone/ISEP#92） |
|
||||
| **A20 舊票有固定管道被撈** | 總管 | ✅ 47/47（2026-08-28，inkstone/ISEP#83）＋真實 229 張唯讀實跑 |
|
||||
| A7 plugin 裝得起來 | 總管 | ✅ |
|
||||
| **A8 新 session 閘會觸發** | 總管 | 見本版 release note |
|
||||
| **B1–B5 雲端** | **leo** | 還沒跑（機器碰不到 Cloud environment） |
|
||||
|
||||
+13
-2
@@ -7,7 +7,8 @@
|
||||
|
||||
## 一句話結論
|
||||
|
||||
`hooks/` 底下有 **54 個 `.sh` 檔**，`hooks.json` 實際掛上 **71 條註冊**（同一支閘常被多種情境同時掛上）；
|
||||
`hooks/` 底下有 **55 個 `.sh` 檔**，`hooks.json` 實際掛上 **72 條註冊**（同一支閘常被多種情境同時掛上）；
|
||||
`hooks/` 底下有 **55 個 `.sh` 檔**，`hooks.json` 實際掛上 **72 條註冊**（同一支閘常被多種情境同時掛上）；
|
||||
其中 **3 支檔案存在但沒被掛上**（2 支是待人填的空範本、1 支是刻意留著沒開的止血帶，見下面「未生效」表）。
|
||||
下面按「你會在什麼時候撞到它」分組，一支一行。
|
||||
|
||||
@@ -52,6 +53,15 @@
|
||||
> 順手改掉一個過期的數字：描述欄長期寫「27 支腳本」，實數是 **34**
|
||||
> （`ls -p scripts | grep -v / | wc -l`）——**同一個病，只是換一欄。**
|
||||
|
||||
> 📌 **`inkstone/ISEP#85`（2026-08-28）進來一支**：`milestone-account-guard.sh`（A 組，PreToolUse／Bash）。
|
||||
> 53→**54** 支、68→**69** 條，兩個數字都是加完之後**在自己的樹上當場數出來的**
|
||||
> （指令同上），**不是拿上一版加一**——`system-dev/wiki/mistakes.md` 記著這條：
|
||||
> 那個數字是 leo 的驗收介面，多報就是假綠。
|
||||
> 順手修掉一個真的漂移：上一版「一句話結論」那一句**被貼了兩次**（同一行連續出現兩遍），
|
||||
> 而標頭寫 52、內文寫 53——**同一頁裡三個數字互相矛盾**，正是本頁自己警告過的那種病。
|
||||
> 另外描述欄的「38 支腳本」是把 `kbdb-live-exam/`／`lib/`／`patches/` 三個**目錄**也數進去了；
|
||||
> 用本頁寫死的那道指令（只數檔案）實數是 **39**。
|
||||
|
||||
---
|
||||
|
||||
## 怎麼讀這張表
|
||||
@@ -80,6 +90,7 @@
|
||||
| `release-tag-guard.sh` | AI 想打版本 tag，但 `plugin.json` 裡寫的版本號跟 tag 對不上就擋下——避免「這裡說 0.2.0、那裡說 0.1.0」各說各話。 | 🛑 擋 |
|
||||
| `ticket-api-bypass-guard.sh` | AI 想繞過 `scripts/ticket` 工具、直接打 API 新增 Gitea 東西（開新票／milestone／label／PR，會漏掉「新增前先搜過」這道檢查）就擋下——不管是隱式 POST（urllib 傳 data= 沒寫 method）還是小寫 `requests.post(...)`。 | 🛑 擋 |
|
||||
| `milestone-due-guard.sh` | AI 想開一個新的里程碑（milestone）卻沒填期限就擋下，**填 `9999-01-01` 一樣擋**——那是「沒有期限」穿了一件期限的衣服，盤點時每一格看起來都有值，其實一格都沒有。只管「建里程碑」這個動作，查詢／改別的欄位都放行。 | 🛑 擋 |
|
||||
| `milestone-account-guard.sh` | AI 想直接打 API 把某個里程碑改成「已關閉」，卻**還沒留下「估多久／花多久／差多少／為什麼差」**就擋下。跟上一列是同一條線的兩端：那支管**開**里程碑要有真的期限，這支管**關**的時候要留下帳。走正門 `scripts/milestone-account close` 就會自己算（數字取自 Gitea 的 `created_at`／`due_on`／`closed_at`，不用手填），差超過 ±25% 才要你從**七個固定代號**裡挑一個，而且那個代號要有 Gitea 時間軸撐得住——**不採信自述**。純讀取／建里程碑／改期限／只是談論它／走正門，全部放行；真要手動關就在指令裡加 `milestone-account-ok`（留痕）。 | 🛑 擋 |
|
||||
| `reply-identity-guard.sh` | 直接打 Gitea API 貼留言到票上時，內文第一行沒有 `【身份】`（`總管`／`subagent`／`leo`）就擋下——票上多條線並行時，看不出哪一則是誰寫的。純讀取、走 `scripts/ticket` 正門、指令裡加 `reply-identity-ok` 都放行。 | 🛑 擋 |
|
||||
| `comment-carries-task-guard.sh` | AI 要在票裡留一則「等某某上線才驗得了」這種**還沒做完的事**，卻沒有把它開成一張子票時，擋一次。留言沒人會回頭讀，票的 open／closed 撈一次就看得到。 | 🛑 擋（同一輪只擋一次） |
|
||||
| `search-is-not-proof-guard.sh` | AI 用知識庫的**搜尋**找到一筆東西，然後把那筆東西的原始編號直接貼進票裡或派工單裡，當成「某個功能壞了」的證據——而它從沒用正規的檢索路徑去查過那筆——擋一次。你關心的是：不會再有人拿錯的方法量出一個錯的結論，然後退回一張其實已經做完的票。 | 🛑 擋（同一輪只擋一次） |
|
||||
@@ -276,7 +287,7 @@ A1 缺人話、A2 表格有幽靈、C 全頁有幽靈。
|
||||
|
||||
**這次順便抓到的另一個落差**（🕐 **這一段是 2026-08-20 的快照，裡面每個數字都是那天的，不是現況**——
|
||||
留著是因為它是「兩份文件的數字不會自己跟上」這個病的第一個案例；現況數字看本頁標頭）：
|
||||
`.claude-plugin/plugin.json` 的說明文字寫「42 支機械閘（52 條註冊）」，
|
||||
`.claude-plugin/plugin.json` 的說明文字寫「55 支機械閘（52 條註冊）」，
|
||||
`README.md` 也寫「42 支 ＋ `hooks.json`」「共 52 條註冊」——但實測是 **43 支檔案、53 條註冊**。
|
||||
差 1 支、差 1 條，猜測是今天（2026-08-20）新增的 `leo21c-write-guard.sh`／`release-tag-guard.sh`／
|
||||
`ticket-api-bypass-guard.sh` 這批（檔頭日期都是今天）加了之後，兩份文件的數字沒有跟著更新。
|
||||
|
||||
@@ -49,6 +49,10 @@
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/milestone-due-guard.sh"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/milestone-account-guard.sh"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/reply-identity-guard.sh"
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
#!/usr/bin/env bash
|
||||
# 管什麼: 直接打 Gitea API 把一個里程碑改成 closed，卻沒有先記帳（估多久／花多久／
|
||||
# 差多少／為什麼差），就擋下來。
|
||||
# 為什麼: leo 2026-08-27 說那天「拖時間」，但拖了多久、比預計多拖多少、為什麼拖——
|
||||
# 一個數字都沒有。偵測器早就有了（mainline-idle-guard／factory-idle-guard），
|
||||
# **但沒有人把它算成帳**，所以事後只能說「這次比較慢」，下次還是一樣。
|
||||
# 誤觸時怎麼關: 走正門 `scripts/milestone-account close <owner/repo#編號>`
|
||||
# （它會自己算三個數字、自己去 Gitea 的時間軸取證據、然後幫你關）。
|
||||
# 真的有理由要繞過去 ⇒ 指令裡加 `milestone-account-ok`（留痕，commit 說明理由）。
|
||||
#
|
||||
# milestone-account-guard.sh — 結案要記帳（PreToolUse／Bash；inkstone/ISEP#85）
|
||||
#
|
||||
# ── 這支跟 milestone-due-guard.sh 是同一條線的兩端 ────────────────────
|
||||
# 那支管**開**里程碑要有真的期限（沒有期限就沒有「估多久」可言）。
|
||||
# 這支管**關**里程碑要留下那三個數字。少了任何一端，帳都算不出來。
|
||||
#
|
||||
# ── 判準：三件同時成立才擋，缺一放行 ──────────────────────────────
|
||||
# ① 指令位置真的有人在發網路請求（curl／wget／python／node／gh）
|
||||
# ——「講到它」跟「執行它」是兩件事，這是本 repo 已經證明過的判準
|
||||
# （release-tag-guard.sh 的 `git tag` 位置比對、strip_heredoc.py 的來由）。
|
||||
# ② URL 指名了**某一個**里程碑：`/repos/<owner>/<repo>/milestones/<數字>`
|
||||
# ——沒有數字的（建里程碑、列清單）不是本閘管的形狀。
|
||||
# ③ 有寫入動詞（PATCH／POST／.patch(／.post(）**而且**內容把 state 設成 closed。
|
||||
#
|
||||
# ⇒ 純 GET、建里程碑、改標題改期限、`cat` 這支腳本、把指令寫進文件（heredoc 內文
|
||||
# 先被 strip_heredoc.py 剝掉）、走正門 `scripts/milestone-account close`
|
||||
# ——全部放行，一條都不擋。
|
||||
#
|
||||
# ── 抽不出 owner/repo/編號就不擋 ────────────────────────────────────
|
||||
# fail-open on 解析失敗（不是 fail-open on 檢查結果）。理由同 release-tag-guard.sh：
|
||||
# 誤攔比漏擋更該修——**誤攔會懲罰謹慎**，而被誤攔幾次之後人就學會繞過這支閘。
|
||||
#
|
||||
# ── 已知的漏擋（寫出來，不假裝沒有）────────────────────────────────
|
||||
# `bash -c 'curl -X PATCH …'` 這種把真正的指令包進引號裡的寫法，本閘看不到。
|
||||
# 這是刻意的取捨：要接住它就得去猜引號裡的內容，而那條路的盡頭是關鍵字黑名單
|
||||
# （leo 2026-08-17 已證偽：當日 8 次誤攔、0 次正確攔截）。
|
||||
#
|
||||
# 迴歸測試：hooks/tests/milestone-account-guard.test.sh（離線，不打 Gitea）
|
||||
set -uo pipefail
|
||||
|
||||
HOOKDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
INPUT=$(cat 2>/dev/null || echo '{}')
|
||||
CMD=$(printf '%s' "$INPUT" | python3 -c '
|
||||
import json, sys
|
||||
try: print(json.load(sys.stdin).get("tool_input", {}).get("command", "") or "")
|
||||
except Exception: print("")
|
||||
' 2>/dev/null || printf '')
|
||||
[ -n "$CMD" ] || exit 0
|
||||
|
||||
# 明講的豁免（留痕）
|
||||
case "$CMD" in *milestone-account-ok*) exit 0 ;; esac
|
||||
|
||||
# heredoc 的內文是資料不是指令——先剝掉，理由見 hooks/lib/strip_heredoc.py 檔頭
|
||||
if [ -f "$HOOKDIR/lib/strip_heredoc.py" ]; then
|
||||
CMD=$(printf '%s' "$CMD" | python3 "$HOOKDIR/lib/strip_heredoc.py" 2>/dev/null || printf '%s' "$CMD")
|
||||
fi
|
||||
|
||||
# ① 指令位置真的有人在發請求
|
||||
printf '%s' "$CMD" | grep -qE '(^|[;&|(`]|&&|\|\|)[[:space:]]*(sudo[[:space:]]+)?(curl|wget|http|python3?|node|gh)[[:space:]]' || exit 0
|
||||
|
||||
# ② 指名某一個里程碑
|
||||
REF=$(printf '%s' "$CMD" | grep -oE '/repos/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/milestones/[0-9]+' | head -1 || printf '')
|
||||
[ -n "$REF" ] || exit 0
|
||||
|
||||
# ③ 寫入動詞 ＋ 把 state 設成 closed
|
||||
printf '%s' "$CMD" | grep -qiE -- '-X[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)|--request[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)|\.(patch|post)\(|method[[:space:]]*=[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)' || exit 0
|
||||
printf '%s' "$CMD" | grep -qiE 'state[^A-Za-z0-9]{1,8}closed' || exit 0
|
||||
|
||||
OWNER=$(printf '%s' "$REF" | cut -d/ -f3)
|
||||
REPO=$(printf '%s' "$REF" | cut -d/ -f4)
|
||||
NUM=$(printf '%s' "$REF" | cut -d/ -f6)
|
||||
TARGET="$OWNER/$REPO#$NUM"
|
||||
|
||||
# 已經記過帳的就放行——正門 `milestone-account close` 是**先記帳、再關**，
|
||||
# 所以「帳本裡有這一筆」就代表三個數字已經留下來了。
|
||||
LEDGER="${MILESTONE_ACCOUNT_LEDGER:-}"
|
||||
if [ -z "$LEDGER" ] && [ -x "$HOOKDIR/../scripts/milestone-account" ]; then
|
||||
LEDGER=$(python3 "$HOOKDIR/../scripts/milestone-account" ledger-path 2>/dev/null || printf '')
|
||||
fi
|
||||
if [ -n "$LEDGER" ] && [ -f "$LEDGER" ] && grep -qF "\"ref\": \"$TARGET\"" "$LEDGER" 2>/dev/null; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
cat >&2 <<MSG
|
||||
⏱️ 結案要記帳：**$TARGET 還沒有留下「估多久／花多久／差多少」。**
|
||||
|
||||
【inkstone/ISEP#85】leo 2026-08-27 說那天「**拖時間**」。
|
||||
但拖了多久、比預計多拖多少、為什麼拖——**沒有任何數字**。
|
||||
「偵測器早就有了，但沒有人把它算成帳」⇒ 每次事後只能說「這次比較慢」，下次還是一樣。
|
||||
|
||||
━━ 走正門，它會把該做的一次做完 ━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
先看時間軸怎麼說： scripts/milestone-account audit $TARGET
|
||||
結案（會自己算、自己關）：
|
||||
scripts/milestone-account close $TARGET [--reason <代號>]
|
||||
|
||||
三個數字**它自己算**（取自 Gitea 的 created_at／due_on／closed_at），不用你手填。
|
||||
差超過 ±25%（超時或提早都算）才需要 --reason，而且代號只能從那七個裡面挑：
|
||||
scripts/milestone-account codes
|
||||
代號要有**時間軸撐得住**——證據取自 Gitea，不採信任何人的自述。
|
||||
|
||||
━━ 為什麼不是「你自己 curl 一下就好」 ━━━━━━━━━━━━━━━━━━━━
|
||||
這一關掉，那個里程碑就再也算不出帳了（closed_at 之後沒有人會回頭補）。
|
||||
⇒ 這是**不可逆**的一步，所以閘長在這裡，不長在誰的記性上。
|
||||
|
||||
真的有理由要手動關 ⇒ 指令裡加 `milestone-account-ok`（留痕，commit 說明理由）。
|
||||
MSG
|
||||
exit 2
|
||||
@@ -144,6 +144,33 @@ if [ -f "$MISTAKES_FILE" ] && grep -q 'MISTAKE' "$MISTAKES_FILE" 2>/dev/null; th
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# ── push 6：還債線今天撈過了沒（inkstone/ISEP#83）──────────────────────────
|
||||
# 🔴 **這裡不打網路、不撈票**——只看狀態檔的日期，講一句話。
|
||||
# 要真的撈是人（或這個 session）自己跑那一行；SessionStart 只負責讓它被想起來。
|
||||
# 「每天都在追新的，所以要用 Routine 去消化舊的」（leo 2026-08-27）——
|
||||
# 沒有這一句，沒掛 milestone 的那 170 多張永遠不會被任何人拿起來。
|
||||
DEBT_STATE="${ISEP_DEBT_STATE_DIR:-$HOME/.claude/isep-debt}/claimed.json"
|
||||
DEBT_LINE=$(python3 - "$DEBT_STATE" <<'PY' 2>/dev/null || true
|
||||
import json, sys, datetime
|
||||
try:
|
||||
d = json.load(open(sys.argv[1]))
|
||||
except Exception:
|
||||
d = {}
|
||||
last = (d.get("last_run") or "")[:10]
|
||||
today = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d")
|
||||
n = len(d.get("claims") or {})
|
||||
if last == today:
|
||||
print(f"✅ 今天撈過了（手上領著 {n} 張）")
|
||||
else:
|
||||
print("🔴 今天還沒撈過還債清單" + (f"（手上還領著 {n} 張沒關）" if n else ""))
|
||||
PY
|
||||
)
|
||||
echo "────────────────────────────────────────────────"
|
||||
echo "🧾 還債線（inkstone/ISEP#83）：${DEBT_LINE:-🔴 今天還沒撈過還債清單}"
|
||||
echo " 撈一次 ＝ python3 ${CLAUDE_PLUGIN_ROOT:-.}/scripts/debt-worklist list"
|
||||
echo " 它排的是「沒掛 milestone 的舊票」——掛著的歸緊急線（milestone）管，兩條線不互搶。"
|
||||
echo ""
|
||||
|
||||
echo "────────────────────────────────────────────────"
|
||||
echo "以上是 index，不是內容——它只讓你知道「有這件事、去哪裡找」。"
|
||||
echo "要完整脈絡（decisions / mistakes / SDD）→ 執行 /wiki-recall"
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
#!/usr/bin/env bash
|
||||
# milestone-account-guard.sh 的迴歸測試（inkstone/ISEP#85）
|
||||
#
|
||||
# A 群「不該擋」——純讀取／建里程碑／改別的欄位／只是談論它／heredoc 內文／
|
||||
# 走正門 `milestone-account close`／已經記過帳／解析不出來
|
||||
# B 群「該擋」 ——真的用 curl／python 把某一個里程碑 PATCH 成 closed，而帳本裡沒有它
|
||||
# C 群「訊息承諾的出路真的走得通」——記過帳之後立刻不再擋；加了豁免字樣就放行
|
||||
#
|
||||
# 🔴 全程離線：帳本走 MILESTONE_ACCOUNT_LEDGER 指到 mktemp 的檔，不打 Gitea。
|
||||
# **誤攔比漏擋更該修**——A 群任何一條紅，就是這支閘在懲罰謹慎。
|
||||
set -u
|
||||
HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/milestone-account-guard.sh}"
|
||||
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
|
||||
LED="$TMP/ledger.jsonl"; : > "$LED"
|
||||
PASS=0; FAIL=0; N=0
|
||||
|
||||
fire() {
|
||||
want="$1"; desc="$2"; cmd="$3"
|
||||
N=$((N+1))
|
||||
payload=$(python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$cmd")
|
||||
out=$(printf '%s' "$payload" | MILESTONE_ACCOUNT_LEDGER="$LED" bash "$HOOK" 2>&1 >/dev/null); rc=$?
|
||||
if [ "$rc" -eq "$want" ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ %s —— 期望 exit=%s，實得 exit=%s\n' "$desc" "$want" "$rc"
|
||||
printf '%s\n' "$out" | sed -n '1,6p' | sed 's/^/ /'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
}
|
||||
|
||||
CLOSE='curl -s -X PATCH -H "Authorization: token X" -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12'
|
||||
|
||||
echo "── A 群：不該擋（誤攔比漏擋更該修）─────────────────────────"
|
||||
fire 0 "① 空指令" ""
|
||||
fire 0 "② 純 GET 撈里程碑" \
|
||||
'curl -s https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12'
|
||||
fire 0 "③ 列出所有里程碑" \
|
||||
'curl -s "https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones?state=open"'
|
||||
fire 0 "④ 建一個新里程碑（那是 milestone-due-guard 管的，不是這支）" \
|
||||
'curl -X POST -d {"title":"x","due_on":"2026-09-05T23:59:59Z"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones'
|
||||
fire 0 "⑤ PATCH 但只是改期限，沒有要關它" \
|
||||
'curl -X PATCH -d {"due_on":"2026-09-05T23:59:59Z"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12'
|
||||
fire 0 "⑥ 只是談論它（echo 在指令位置，curl 在字串裡）" \
|
||||
"echo '$CLOSE'"
|
||||
fire 0 "⑦ 讀這支閘自己的原始碼" 'cat hooks/milestone-account-guard.sh'
|
||||
fire 0 "⑧ commit 訊息裡出現「關掉 milestone」" \
|
||||
'git commit -m "關掉 milestone 12，state closed"'
|
||||
fire 0 "⑨ 走正門：scripts/milestone-account close" \
|
||||
'python3 scripts/milestone-account close inkstone/ISEP#12 --reason idle'
|
||||
fire 0 "⑩ 正門的 --dry-run" \
|
||||
'python3 scripts/milestone-account close inkstone/ISEP#12 --reason idle --dry-run'
|
||||
fire 0 "⑪ 把那段指令寫進文件（heredoc 內文是資料不是指令）" \
|
||||
"$(printf 'cat > docs/x.md <<%s\n%s\nEOD\n' "'EOD'" "$CLOSE")"
|
||||
fire 0 "⑫ 網址沒有里程碑編號（抽不出目標 ⇒ 不擋）" \
|
||||
'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones'
|
||||
fire 0 "⑬ 關的是一張票不是里程碑" \
|
||||
'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/issues/12'
|
||||
|
||||
echo "── B 群：該擋 ──────────────────────────────────────────────"
|
||||
fire 2 "⑭ curl PATCH state=closed，帳本裡沒有它" "$CLOSE"
|
||||
fire 2 "⑮ 換成 python urllib（method=\"PATCH\"）一樣擋" \
|
||||
'python3 -c "import urllib.request,json; urllib.request.urlopen(urllib.request.Request(\"https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12\", data=json.dumps({\"state\":\"closed\"}).encode(), method=\"PATCH\"))"'
|
||||
fire 2 "⑯ 前面串一個無害指令也擋（不是靠前綴判斷）" "ls && $CLOSE"
|
||||
fire 2 "⑰ --request PATCH 的長寫法" \
|
||||
'curl --request PATCH --data {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12'
|
||||
fire 2 "⑱ 別的 repo 的里程碑一樣管" \
|
||||
'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/arcrun-rag/milestones/47'
|
||||
|
||||
echo "── C 群：訊息承諾的出路真的走得通 ──────────────────────────"
|
||||
N=$((N+1))
|
||||
out=$(python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$CLOSE" \
|
||||
| MILESTONE_ACCOUNT_LEDGER="$LED" bash "$HOOK" 2>&1 >/dev/null)
|
||||
if printf '%s' "$out" | grep -q "scripts/milestone-account audit inkstone/ISEP#12"; then
|
||||
printf ' ✅ ⑲ 訊息直接給出可以照打的那一行（含正確的 owner/repo#編號）\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ⑲ 訊息沒有點名目標\n'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
|
||||
echo '{"ref": "inkstone/ISEP#12", "reason": "idle"}' >> "$LED"
|
||||
fire 0 "⑳ 記過帳之後立刻放行（正門是先記帳再關）" "$CLOSE"
|
||||
fire 2 "㉑ 但別的里程碑還是照擋（不是一記帳就全開）" \
|
||||
'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/13'
|
||||
fire 0 "㉒ 明講的豁免字樣（留痕）" "$CLOSE # milestone-account-ok"
|
||||
|
||||
echo
|
||||
echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）"
|
||||
[ "$FAIL" -eq 0 ]
|
||||
+20
@@ -101,6 +101,26 @@ labels:
|
||||
exclusive: true
|
||||
description: "雜務、整理、不改行為"
|
||||
|
||||
# ── 使用者旅程（正交，`j/` scope）──────────────────
|
||||
#
|
||||
# inkstone/ISEP#92：「這件事服務哪個使用者旅程，沒有記錄⋯⋯後面要把相關的票
|
||||
# 聚成一包時，只能靠人重新讀一遍每張票在講什麼。」
|
||||
#
|
||||
# `ticket subtask/handoff --journey <名>` 會把 `j/<名>` **同時貼在母子兩端**
|
||||
# （只貼一端就聚不起來）。標籤不存在時它會擋下來並指回本檔——
|
||||
# **「要求標籤在場」，不是「猜哪些名字合法」**。
|
||||
#
|
||||
# 🔴 這裡刻意是空的。旅程怎麼切、叫什麼名字，是方向題（四題公式第 4 題），
|
||||
# 不該由工具或 subagent 代決；隨手造名字會讓同一條旅程長出三個拼法。
|
||||
# 要新增一條就照這個形狀加一筆，然後跑 scripts/gitea-labels-sync.sh：
|
||||
#
|
||||
# - name: "j/收件匣"
|
||||
# color: "fbca04"
|
||||
# exclusive: false
|
||||
# description: "🧭 旅程：<一句話講這條旅程的頭和尾>"
|
||||
#
|
||||
# （票上明講「對不上就不貼，不硬湊」——沒有對應旅程的票就不要加 --journey。）
|
||||
|
||||
# ── 結構（正交）──────────────────────────────────
|
||||
- name: "hub"
|
||||
color: "0052cc"
|
||||
|
||||
Executable
+559
@@ -0,0 +1,559 @@
|
||||
#!/usr/bin/env python3
|
||||
"""debt-worklist — 還債線：每天固定撈一次「今天可以領什麼」，整包整包地領。
|
||||
|
||||
leo 2026-08-27（inkstone/ISEP#83 的來由，他當場訂正總管的誤解）：
|
||||
「這是兩件不同的事，你根本沒搞清楚，距離是在確定有個緊急事件要儘速達成時，
|
||||
現在每天都在追新的，所以**要用 Routine 去消化舊的**，可以有多個條件」
|
||||
|
||||
⇒ **兩條線，各用各的判準**，不是二選一：
|
||||
|
||||
緊急線 有事要趕 → 用「距離目標的遠近」排（＝掛在 open milestone 上的那些）
|
||||
還債線 每天消化舊的 → 用多條件排（事故／擋人／承諾／票齡／估工） ← 本工具
|
||||
|
||||
病根：全 org 229 張 open 票，每天在動的只有掛在 active milestone 上的那些。
|
||||
沒掛的不是不重要，是**沒有任何機制會去拿它們**。`worklist-guard.sh` 擋的是
|
||||
「這一輪已經領到的工作沒做完就收工」——它不會去把舊票撈出來。本工具補的是供給面。
|
||||
|
||||
三個動詞：
|
||||
|
||||
debt-worklist list 撈一次，排好序印出來（預設動作）
|
||||
debt-worklist claim <票...> 領走（今天領的，明天就不會再出現在清單上）
|
||||
debt-worklist forget <票...> 放回去（領錯了、或那條線改方向了）
|
||||
|
||||
票的寫法：`owner/repo#N`，例：`inkstone/InkStoneCo#44`
|
||||
|
||||
🔴 **不是輪詢。** 這支腳本自己不會醒——是人跑它、或 SessionStart 那一次順手跑。
|
||||
不准掛 Gitea Actions／webhook fan-out（CLAUDE.md 避免再被 flag 的硬規則，
|
||||
`issue-handle` 明寫「有事才讀」，換成 Gitea 也不放寬）。
|
||||
|
||||
離線可測：設 `ISEP_DEBT_FIXTURE=<json 檔>` 就完全不打網路（測試用）。
|
||||
狀態檔位置可用 `ISEP_DEBT_STATE_DIR` 改（測試用，預設 `~/.claude/isep-debt/`）。
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
from datetime import datetime, timezone
|
||||
|
||||
HOST = os.environ.get("TICKET_HOST") or "https://git.uncle6.me"
|
||||
ORG = os.environ.get("ISEP_DEBT_ORG") or "inkstone"
|
||||
|
||||
# ── 「現在的主線是哪一個」只有一份答案（inkstone/ISEP#82 → hooks/lib/mainline.py）──
|
||||
# 本工具排除的是**緊急線正在管的那些**。在 #82 之前，「哪個是 active」沒有指涉對象
|
||||
# （14 個 open milestone 同時亮著），所以第一版只能粗暴地「掛 open milestone 就排除」。
|
||||
# 現在有唯一答案了 ⇒ 接上去，**不要自己養第二套判斷**（兩份必然漂移）。
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks", "lib"))
|
||||
try:
|
||||
import mainline as ML
|
||||
except Exception: # 拿不到共用零件就退回舊行為（fail-open），不讓還債線整個癱掉
|
||||
ML = None
|
||||
|
||||
# 等 leo 的票不進「可領清單」——不是它們不重要，是**沒有人能替他領**：
|
||||
# Human／human/exec ＝ 要他親手批示或動手
|
||||
# s/stage ＝ 已經部到 stage，等他驗（session-start-recall 就是這樣定義的）
|
||||
# 這些的正確動作是「催」不是「領」，而催辦是 inkstone/ISEP#93 的事。本票是供給面。
|
||||
WAITING_LEO_LABELS = {"Human", "human/exec", "s/stage"}
|
||||
|
||||
# 已經有人在做／已經有 PR 的狀態：這是「答應過人家的」，債比沒開工的還硬。
|
||||
STARTED_LABELS = {"s/doing", "s/review"}
|
||||
|
||||
|
||||
def die(msg, code=2):
|
||||
print(msg, file=sys.stderr)
|
||||
sys.exit(code)
|
||||
|
||||
|
||||
# ── 連線（跟 scripts/ticket 同一套：先找帶憑證的 remote，再退環境變數）────────
|
||||
def token():
|
||||
root = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
|
||||
host = HOST.split("//")[-1].rstrip("/")
|
||||
try:
|
||||
out = subprocess.run(["git", "-C", root, "remote", "-v"],
|
||||
capture_output=True, text=True, timeout=20).stdout
|
||||
except Exception:
|
||||
out = ""
|
||||
for line in out.splitlines():
|
||||
if host in line:
|
||||
m = re.search(r"//[^:/]+:([^@]+)@", line)
|
||||
if m:
|
||||
return m.group(1)
|
||||
for env in ("GITEA_TOKEN_CLAUDE_CODE", "GITEA_TOKEN"):
|
||||
if os.environ.get(env):
|
||||
return os.environ[env]
|
||||
die(f"""🔴 拿不到 {host} 的 token
|
||||
|
||||
擇一：
|
||||
• 讓某個 remote 帶憑證（多數 repo 的 gitea/origin 本來就有）
|
||||
• 或設環境變數 GITEA_TOKEN_CLAUDE_CODE""")
|
||||
|
||||
|
||||
def api(path):
|
||||
url = f"{HOST}/api/v1{path}"
|
||||
req = urllib.request.Request(url, headers={"Authorization": f"token {token()}"})
|
||||
try:
|
||||
return json.load(urllib.request.urlopen(req, timeout=60))
|
||||
except urllib.error.HTTPError as e:
|
||||
die(f"🔴 Gitea {e.code}：{e.read().decode()[:300]}\n （path={path}）")
|
||||
except Exception as e:
|
||||
die(f"🔴 打不到 {HOST}：{e}\n （path={path}）")
|
||||
|
||||
|
||||
# ── 收集：全 org 每個 repo 的 open issue ＋ open PR ──────────────────────────
|
||||
def collect():
|
||||
"""回 (repos, items)。repos 是「我查了哪些」的證明，items 是原始票。
|
||||
|
||||
fixture 模式（測試用）：完全不打網路，資料從 json 檔讀。
|
||||
"""
|
||||
fx = os.environ.get("ISEP_DEBT_FIXTURE")
|
||||
if fx:
|
||||
with open(fx) as f:
|
||||
data = json.load(f)
|
||||
return data["repos"], data["items"]
|
||||
|
||||
repos, items = [], []
|
||||
for r in api(f"/orgs/{ORG}/repos?limit=100") or []:
|
||||
full = r["full_name"]
|
||||
if not r.get("has_issues", True):
|
||||
repos.append({"name": full, "issues": 0, "prs": 0, "skipped": "issues 關閉"})
|
||||
continue
|
||||
got, page = [], 1
|
||||
while True:
|
||||
q = urllib.parse.urlencode({"state": "open", "limit": 50, "page": page})
|
||||
batch = api(f"/repos/{full}/issues?{q}") or []
|
||||
got.extend(batch)
|
||||
if len(batch) < 50:
|
||||
break
|
||||
page += 1
|
||||
if page > 20: # 保險絲：不可能有一千張，有的話是我寫錯了
|
||||
break
|
||||
for it in got:
|
||||
it.setdefault("repository", {"full_name": full})
|
||||
n_pr = sum(1 for it in got if it.get("pull_request"))
|
||||
repos.append({"name": full, "issues": len(got) - n_pr, "prs": n_pr})
|
||||
items.extend(got)
|
||||
return repos, items
|
||||
|
||||
|
||||
# ── 工具 ───────────────────────────────────────────────────────────────────
|
||||
def ref_of(it):
|
||||
return f"{it['repository']['full_name']}#{it['number']}"
|
||||
|
||||
|
||||
def labels_of(it):
|
||||
return {l["name"] for l in (it.get("labels") or [])}
|
||||
|
||||
|
||||
def is_pr(it):
|
||||
return bool(it.get("pull_request"))
|
||||
|
||||
|
||||
def parse_ts(s):
|
||||
if not s:
|
||||
return None
|
||||
try:
|
||||
return datetime.fromisoformat(s.replace("Z", "+00:00"))
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def now():
|
||||
"""時鐘可以被定住——測試要能重現，不能今天跑綠明天跑紅。"""
|
||||
inj = os.environ.get("ISEP_DEBT_NOW")
|
||||
if inj:
|
||||
d = parse_ts(inj)
|
||||
if d:
|
||||
return d
|
||||
return datetime.now(timezone.utc)
|
||||
|
||||
|
||||
def days_since(s):
|
||||
d = parse_ts(s)
|
||||
if not d:
|
||||
return 0.0
|
||||
return max(0.0, (now() - d).total_seconds() / 86400)
|
||||
|
||||
|
||||
REF_RE = re.compile(r"(?:([\w.-]+)/([\w.-]+))?#(\d+)")
|
||||
|
||||
|
||||
def refs_in(it):
|
||||
"""從標題＋內文抓出它指到的別張票。裸 `#12` 算同 repo。
|
||||
|
||||
只認得出「文字上指了誰」——這是零成本的訊號（內文本來就在清單裡）。
|
||||
Gitea 原生的 dependencies 要一張票打一次 API，229 張＝229 次，不值得。
|
||||
"""
|
||||
owner, repo = it["repository"]["full_name"].split("/")
|
||||
out = set()
|
||||
text = f"{it.get('title') or ''}\n{it.get('body') or ''}"
|
||||
for o, r, n in REF_RE.findall(text):
|
||||
out.add(f"{o or owner}/{r or repo}#{n}")
|
||||
out.discard(ref_of(it))
|
||||
return out
|
||||
|
||||
|
||||
# ── 排序：多個條件，每一條都看得見自己貢獻了幾分 ─────────────────────────────
|
||||
#
|
||||
# leo 給的順序（票上原文）：出事的 → 擋住別人的 → 答應過人家的 → 放最久的 → 最快做完的。
|
||||
# 分數只是把這個順序寫成可重現的東西；**每一項都會印在票旁邊**，
|
||||
# 排出來覺得不對可以直接指著說「這一項給太多」，而不是猜它為什麼在第一名。
|
||||
def score(it, in_degree):
|
||||
lab = labels_of(it)
|
||||
parts = []
|
||||
|
||||
if "type/bug" in lab:
|
||||
parts.append(("事故", 40))
|
||||
if "p/high" in lab:
|
||||
parts.append(("高優先", 20))
|
||||
if "p/low" in lab:
|
||||
parts.append(("低優先", -12))
|
||||
|
||||
blocked = in_degree.get(ref_of(it), 0)
|
||||
if blocked:
|
||||
parts.append((f"擋住{blocked}張", min(12 * blocked, 36)))
|
||||
if is_pr(it):
|
||||
# 躺著沒結論的 PR 擋的是 merge 那條路（inkstone/ISEP#81 是它的另一半）
|
||||
parts.append(("PR躺著", 25))
|
||||
|
||||
started = lab & STARTED_LABELS
|
||||
if started:
|
||||
parts.append((f"已開工({'/'.join(sorted(started))})", 18))
|
||||
if it.get("assignees") or it.get("assignee"):
|
||||
parts.append(("有人接了", 12))
|
||||
|
||||
ms = it.get("milestone") or {}
|
||||
if ms and (ms.get("state") or "open") == "open" and ML is not None:
|
||||
due = ML.due_of(ms)
|
||||
if due and due < now():
|
||||
# 掛在**別條**（非主線）而且期限已經過去的 milestone ⇒ 這是承諾過的日期，
|
||||
# 而那個日期已經過了。它之所以還在這份清單上，正是因為沒有人在管那條線。
|
||||
parts.append((f"逾期{int((now() - due).total_seconds() // 86400)}天的承諾", 15))
|
||||
|
||||
age = days_since(it.get("updated_at"))
|
||||
if age >= 1:
|
||||
parts.append((f"擱置{int(age)}天", round(min(age * 0.6, 30), 1)))
|
||||
|
||||
body_len = len(it.get("body") or "")
|
||||
if "type/chore" in lab or body_len < 800:
|
||||
parts.append(("看起來小", 10))
|
||||
|
||||
total = round(sum(p[1] for p in parts), 1)
|
||||
return total, parts
|
||||
|
||||
|
||||
def pick(items, claimed):
|
||||
"""把原始票分成三堆：可領的／緊急線的／要 leo 動手的。並回統計。"""
|
||||
open_refs = {ref_of(it) for it in items}
|
||||
in_degree = {}
|
||||
for it in items:
|
||||
for target in refs_in(it):
|
||||
if target in open_refs:
|
||||
in_degree[target] = in_degree.get(target, 0) + 1
|
||||
|
||||
ml = ML.load() if ML is not None else None
|
||||
pool, stats = [], {"milestone": 0, "human": 0, "claimed": 0, "total": len(items),
|
||||
"other_ms": 0, "mainline": ml}
|
||||
for it in items:
|
||||
ref = ref_of(it)
|
||||
ms = it.get("milestone")
|
||||
if ms and (ms.get("state") or "open") == "open":
|
||||
if ml is None:
|
||||
# 現在沒有主線 ⇒ 分不出哪一條是緊急線在管的。退回保守做法：
|
||||
# 掛 open milestone 的一律不領（寧可少領，不要跟緊急線搶同一張）。
|
||||
stats["milestone"] += 1
|
||||
continue
|
||||
if ML.belongs(ref, ml, ms.get("title")):
|
||||
stats["milestone"] += 1 # 這張真的在主線上 ⇒ 緊急線在管，不重複領
|
||||
continue
|
||||
# 掛在**別條** milestone 上：那條線現在沒有人在推 ⇒ 它就是債
|
||||
stats["other_ms"] += 1
|
||||
if labels_of(it) & WAITING_LEO_LABELS:
|
||||
stats["human"] += 1 # 沒有人能替 leo 領（催辦是 ISEP#93）
|
||||
continue
|
||||
if ref in claimed:
|
||||
stats["claimed"] += 1 # 昨天領走的，今天不再出現
|
||||
continue
|
||||
s, parts = score(it, in_degree)
|
||||
pool.append({"ref": ref, "title": it.get("title") or "", "score": s,
|
||||
"why": parts, "labels": sorted(labels_of(it)),
|
||||
"pr": is_pr(it), "url": it.get("html_url"),
|
||||
"age": round(days_since(it.get("updated_at")), 1),
|
||||
"refs": sorted(refs_in(it) & open_refs)})
|
||||
pool.sort(key=lambda d: (-d["score"], d["ref"]))
|
||||
return pool, stats, in_degree
|
||||
|
||||
|
||||
# ── 成包：互相指著的必然同包（票上原文「相關的票要成包一起領，不要拆散」）──────
|
||||
#
|
||||
# 🔴 **只認強訊號，寧可少成包**。第一版用「單向文字引用」成包，結果是
|
||||
# **前 190 張裡有 121 張黏成一包**——因為大家都會順手引用 hub 票。
|
||||
# 一包 121 張＝沒有人領得動＝跟沒分包一樣。所以只認這兩種：
|
||||
# ① 互相指著（A 的內文提 B，且 B 的內文提 A）——單向不算
|
||||
# ② Gitea 原生相依（`ticket subtask` 建的母子票就是這個）
|
||||
# 代價：同一條使用者旅程但沒有互指、也沒建相依的兩張票不會成包。
|
||||
# 這是誠實的取捨——**寧可漏成包，不要成一包沒人領得動的**。
|
||||
BUNDLE_CAP = 8 # 一包最多印幾張；超過就說「還有幾張」
|
||||
DEPS_TOP_K = 25 # 只對前 K 名查原生相依（一張一次 API，不對全部查）
|
||||
|
||||
|
||||
def dep_edges(pool, enabled=True):
|
||||
"""回 [(a, b)…]：前 K 名的原生相依邊，只留兩端都在 pool 裡的。"""
|
||||
fx = os.environ.get("ISEP_DEBT_FIXTURE")
|
||||
if fx:
|
||||
with open(fx) as f:
|
||||
deps = (json.load(f).get("deps") or {})
|
||||
in_pool = {d["ref"] for d in pool}
|
||||
return [(a, b) for a, bs in deps.items() for b in bs
|
||||
if a in in_pool and b in in_pool]
|
||||
if not enabled:
|
||||
return []
|
||||
in_pool = {d["ref"] for d in pool}
|
||||
edges = []
|
||||
for d in pool[:DEPS_TOP_K]:
|
||||
owner, rest = d["ref"].split("/", 1)
|
||||
repo, num = rest.split("#")
|
||||
try:
|
||||
got = api(f"/repos/{owner}/{repo}/issues/{num}/dependencies") or []
|
||||
except SystemExit:
|
||||
continue
|
||||
for i in got:
|
||||
other = f"{i['repository']['full_name']}#{i['number']}"
|
||||
if other in in_pool:
|
||||
edges.append((d["ref"], other))
|
||||
return edges
|
||||
|
||||
|
||||
def mutual_edges(pool):
|
||||
idx = {d["ref"]: set(d["refs"]) for d in pool}
|
||||
out = []
|
||||
for ref, targets in idx.items():
|
||||
for t in targets:
|
||||
if t in idx and ref in idx[t] and ref < t:
|
||||
out.append((ref, t))
|
||||
return out
|
||||
|
||||
|
||||
def bundle(pool, edges):
|
||||
idx = {d["ref"]: d for d in pool}
|
||||
parent = {r: r for r in idx}
|
||||
|
||||
def find(x):
|
||||
while parent[x] != x:
|
||||
parent[x] = parent[parent[x]]
|
||||
x = parent[x]
|
||||
return x
|
||||
|
||||
def union(a, b):
|
||||
ra, rb = find(a), find(b)
|
||||
if ra != rb:
|
||||
parent[rb] = ra
|
||||
|
||||
for a, b in edges:
|
||||
if a in idx and b in idx:
|
||||
union(a, b)
|
||||
|
||||
groups = {}
|
||||
for d in pool:
|
||||
groups.setdefault(find(d["ref"]), []).append(d)
|
||||
out = []
|
||||
for members in groups.values():
|
||||
members.sort(key=lambda d: (-d["score"], d["ref"]))
|
||||
out.append({"lead": members[0], "members": members,
|
||||
"score": members[0]["score"]})
|
||||
out.sort(key=lambda b: (-b["score"], b["lead"]["ref"]))
|
||||
return out
|
||||
|
||||
|
||||
# ── 狀態：領走了什麼（明天的清單要看得出昨天領走的不見了）───────────────────
|
||||
def state_dir():
|
||||
d = os.environ.get("ISEP_DEBT_STATE_DIR") or os.path.expanduser("~/.claude/isep-debt")
|
||||
os.makedirs(d, exist_ok=True)
|
||||
return d
|
||||
|
||||
|
||||
def state_path():
|
||||
return os.path.join(state_dir(), "claimed.json")
|
||||
|
||||
|
||||
def load_state():
|
||||
try:
|
||||
with open(state_path()) as f:
|
||||
d = json.load(f)
|
||||
except Exception:
|
||||
d = {}
|
||||
d.setdefault("claims", {})
|
||||
d.setdefault("last_run", None)
|
||||
return d
|
||||
|
||||
|
||||
def save_state(d):
|
||||
with open(state_path(), "w") as f:
|
||||
json.dump(d, f, ensure_ascii=False, indent=1)
|
||||
|
||||
|
||||
# ── 印 ─────────────────────────────────────────────────────────────────────
|
||||
def print_proof(repos, stats):
|
||||
scanned = [r for r in repos if not r.get("skipped")]
|
||||
n_iss = sum(r["issues"] for r in scanned)
|
||||
n_pr = sum(r["prs"] for r in scanned)
|
||||
print(f"🔎 查過的 repo：{len(repos)} 個（{ORG} 全組織）"
|
||||
f" open issue {n_iss}、open PR {n_pr}")
|
||||
for r in sorted(repos, key=lambda x: -(x["issues"] + x["prs"])):
|
||||
mark = f"（跳過：{r['skipped']}）" if r.get("skipped") else ""
|
||||
print(f" · {r['name']} issue {r['issues']}／PR {r['prs']} {mark}")
|
||||
ml = stats.get("mainline")
|
||||
if ml:
|
||||
print(f"\n🎯 現在的主線：{ML.ref_of(ml)}「{ml.get('title')}」"
|
||||
f"（唯一答案來自 scripts/mainline，本工具不自己判）")
|
||||
print(f" 掛在**別條** milestone 上的 {stats['other_ms']} 張仍算債"
|
||||
"——那條線現在沒有人在推")
|
||||
else:
|
||||
print("\n🎯 現在沒有標主線（`scripts/mainline set …`）"
|
||||
"⇒ 分不出哪條是緊急線在管的，保守起見：掛 open milestone 的一律不領")
|
||||
print(f"\n 扣掉：掛在 open milestone 上的 {stats['milestone']} 張（那些歸緊急線管）"
|
||||
f"／等 leo 的 {stats['human']} 張"
|
||||
f"（Human・human/exec・s/stage——那些要催不是要領，見 inkstone/ISEP#93）"
|
||||
f"／已經領走的 {stats['claimed']} 張")
|
||||
|
||||
|
||||
def print_carry(state, items):
|
||||
"""昨天領走的，今天怎麼了——**這一段就是「看得出領走的不在清單上」**。"""
|
||||
claims = state.get("claims") or {}
|
||||
if not claims:
|
||||
return
|
||||
open_refs = {ref_of(it) for it in items}
|
||||
done = [r for r in claims if r not in open_refs]
|
||||
doing = [r for r in claims if r in open_refs]
|
||||
print(f"\n📦 之前領走的 {len(claims)} 張：已關 {len(done)}、還開著 {len(doing)}")
|
||||
for r in sorted(doing):
|
||||
c = claims[r]
|
||||
print(f" ◻ {r} （{c.get('at', '?')[:10]} 領的）{c.get('title', '')[:40]}")
|
||||
for r in sorted(done):
|
||||
print(f" ✅ {r} 已關")
|
||||
if doing:
|
||||
print(" 🔴 還開著的沒有回到可領清單裡——做完就關票，或 "
|
||||
"`debt-worklist forget <票>` 把它放回去。")
|
||||
|
||||
|
||||
def print_bundle(i, b, verbose):
|
||||
lead = b["lead"]
|
||||
kind = "PR" if lead["pr"] else "票"
|
||||
print(f"\n {i}. [{lead['score']}] {lead['ref']}（{kind}）")
|
||||
print(f" {lead['title'][:72]}")
|
||||
print(" 為什麼排這裡：" + "、".join(f"{n}{v:+g}" for n, v in lead["why"]))
|
||||
if lead["labels"]:
|
||||
print(f" 標籤：{lead['labels']}")
|
||||
others = b["members"][1:]
|
||||
if others:
|
||||
print(f" ↳ 同一包（互相指著／原生相依，要一起領）共 {len(b['members'])} 張：")
|
||||
shown = others if verbose else others[:BUNDLE_CAP]
|
||||
for m in shown:
|
||||
print(f" · [{m['score']}] {m['ref']} {m['title'][:56]}")
|
||||
if len(others) > len(shown):
|
||||
print(f" · …另外 {len(others) - len(shown)} 張（`--all` 看全部）")
|
||||
|
||||
|
||||
def cmd_list(argv):
|
||||
top = int(argv[argv.index("--top") + 1]) if "--top" in argv else 6
|
||||
verbose = "--all" in argv
|
||||
as_json = "--json" in argv
|
||||
|
||||
repos, items = collect()
|
||||
state = load_state()
|
||||
pool, stats, _ = pick(items, set(state.get("claims") or {}))
|
||||
edges = mutual_edges(pool) + dep_edges(pool, enabled="--no-deps" not in argv)
|
||||
bundles = bundle(pool, edges)
|
||||
|
||||
if as_json:
|
||||
print(json.dumps({
|
||||
"at": now().isoformat(), "repos": repos, "stats": stats,
|
||||
"claimed": sorted(state.get("claims") or {}),
|
||||
"bundles": [{"score": b["score"],
|
||||
"members": [{"ref": m["ref"], "score": m["score"],
|
||||
"title": m["title"], "why": m["why"]}
|
||||
for m in b["members"]]} for b in bundles],
|
||||
}, ensure_ascii=False, indent=1))
|
||||
else:
|
||||
print(f"🧾 還債清單 {now().strftime('%Y-%m-%d %H:%M UTC')}\n")
|
||||
print_proof(repos, stats)
|
||||
print_carry(state, items)
|
||||
print(f"\n── 今天可以領的：{len(pool)} 張，收斂成 {len(bundles)} 包 "
|
||||
f"────────────────────")
|
||||
if not pool:
|
||||
# 🔴 空清單要說話。默默結束＝人分不出「查過沒東西」跟「根本沒查」。
|
||||
print("\n ✅ **查詢跑過了，結果是零。**"
|
||||
f"\n {len(repos)} 個 repo 都掃過（見上面那份清單），"
|
||||
"沒有一張是「沒掛 milestone、沒等 leo、還沒被領走」的。"
|
||||
"\n 這代表舊債清乾淨了——不是查詢壞掉。")
|
||||
for i, b in enumerate(bundles[:len(bundles) if verbose else top], 1):
|
||||
print_bundle(i, b, verbose)
|
||||
if not verbose and len(bundles) > top:
|
||||
print(f"\n …另外 {len(bundles) - top} 包（`--top N` 或 `--all` 看更多）")
|
||||
if pool:
|
||||
first = " ".join(m["ref"] for m in bundles[0]["members"][:BUNDLE_CAP])
|
||||
print(f"""
|
||||
── 領走它 ──────────────────────────────────────────────────
|
||||
debt-worklist claim {first}
|
||||
|
||||
領走 ＝ 今天要做它。領了之後它就不會再出現在這份清單上，
|
||||
直到你把票關掉、或 `debt-worklist forget` 把它放回去。
|
||||
🔴 **整包一起領**：同一包是互相指著的，拆開做會做到一半發現卡在另一張。""")
|
||||
|
||||
state["last_run"] = now().isoformat()
|
||||
save_state(state)
|
||||
return 0
|
||||
|
||||
|
||||
def _titles(items):
|
||||
return {ref_of(it): (it.get("title") or "") for it in items}
|
||||
|
||||
|
||||
def cmd_claim(argv):
|
||||
refs = [a for a in argv if not a.startswith("-")]
|
||||
if not refs:
|
||||
die("用法：debt-worklist claim <owner/repo#N> [更多…]")
|
||||
for r in refs:
|
||||
if not re.match(r"^[\w.-]+/[\w.-]+#\d+$", r):
|
||||
die(f"🔴 票的寫法是 owner/repo#N，你給的是：{r}")
|
||||
_, items = collect()
|
||||
titles = _titles(items)
|
||||
unknown = [r for r in refs if r not in titles]
|
||||
if unknown:
|
||||
die("🔴 這幾張不在 open 清單裡（打錯了？已經關了？）：" + "、".join(unknown))
|
||||
state = load_state()
|
||||
for r in refs:
|
||||
state["claims"][r] = {"at": now().isoformat(), "title": titles[r]}
|
||||
save_state(state)
|
||||
print(f"📦 領走 {len(refs)} 張，明天的清單不會再出現它們：")
|
||||
for r in refs:
|
||||
print(f" · {r} {titles[r][:60]}")
|
||||
print("\n🔴 領了就是今天要做它。做完關票；改方向就 `debt-worklist forget`。")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_forget(argv):
|
||||
refs = [a for a in argv if not a.startswith("-")]
|
||||
if not refs:
|
||||
die("用法：debt-worklist forget <owner/repo#N> [更多…]")
|
||||
state = load_state()
|
||||
gone = [r for r in refs if state["claims"].pop(r, None) is not None]
|
||||
save_state(state)
|
||||
print(f"↩️ 放回清單 {len(gone)} 張：" + ("、".join(gone) or "（本來就沒領過）"))
|
||||
return 0
|
||||
|
||||
|
||||
CMDS = {"list": cmd_list, "claim": cmd_claim, "forget": cmd_forget}
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
sys.exit(cmd_list([]))
|
||||
if sys.argv[1] in ("-h", "--help", "help"):
|
||||
print(__doc__)
|
||||
sys.exit(0)
|
||||
if sys.argv[1] not in CMDS:
|
||||
print(__doc__)
|
||||
sys.exit(2)
|
||||
sys.exit(CMDS[sys.argv[1]](sys.argv[2:]))
|
||||
@@ -0,0 +1,634 @@
|
||||
#!/usr/bin/env python3
|
||||
"""milestone-account — 每次結案都留下「估多久／花多久／差多少／為什麼」（inkstone/ISEP#85）。
|
||||
|
||||
leo 的問題（票上原文）：「leo 2026-08-27 說今天『**拖時間**』。但拖了多久、
|
||||
比預計多拖多少、為什麼拖——**沒有任何數字**⋯⋯每次事後只能用『這次比較慢』
|
||||
這種話帶過，下次還是一樣。」
|
||||
|
||||
milestone-account codes 七個代號是哪七個（封閉集合）
|
||||
milestone-account list --org inkstone [--overdue] 現在每個里程碑的三個數字
|
||||
milestone-account audit inkstone/ISEP#12 從 Gitea 時間軸算證據
|
||||
milestone-account close inkstone/ISEP#12 --reason idle [--dry-run]
|
||||
milestone-account report 累計：哪一種原因最常發生
|
||||
milestone-account ledger-path 帳本檔在哪（給閘問的）
|
||||
|
||||
🔴 這支工具的三條，全部長在機器上（不是寫在規範裡靠人記得）：
|
||||
|
||||
① **三個數字自己算，不用手填**：期限與實際都取自 Gitea 的 `created_at`／
|
||||
`due_on`／`closed_at`。手填的數字沒有人會去對，等於沒有。
|
||||
② **差超過 25%（超時或提早都算）就一定要挑一個代號**，挑不出來不准結案。
|
||||
提早太多不是好消息，是**當初估太鬆**——所以兩個方向同一條線。
|
||||
③ **代號要有時間軸撐得住**：`audit` 先從 Gitea 的時間軸算出哪幾個訊號成立，
|
||||
`close` 只接受**訊號成立的那幾個代號**；一個都沒成立時，唯一合法的代號
|
||||
就是 `misestimate`（＝票上那句「以上都沒有，但還是差很多」）。
|
||||
⇒ **不採信我自己說的**，這是票上寫死的。
|
||||
|
||||
🔴 代號是**封閉集合**，這一點是刻意的——票上原文：「**能統計的前提是分類有限**」。
|
||||
真的歸不進去才提案加一個，而那要走 leo 核准（開票，不是自己加）。
|
||||
|
||||
離線測試：`scripts/test-milestone-account.sh`（走 `MILESTONE_ACCOUNT_FIXTURE`，不打網路）。
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
HOST = os.environ.get("MILESTONE_ACCOUNT_HOST", "https://git.uncle6.me")
|
||||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||||
ROOT = os.path.dirname(HERE)
|
||||
def _resolve_dir():
|
||||
"""帳本住哪裡。
|
||||
|
||||
🔴 **不能住在 plugin 目錄裡**：ISEP 是用 marketplace 裝的，
|
||||
`claude plugin update` 會把那個目錄整個換掉 ⇒ 累積幾個月的帳一次歸零，
|
||||
而這張票的全部價值就在「累積」。
|
||||
順序：環境變數 → 這個 session 的專案根底下的 `system-dev/`（總管的跨專案知識庫，
|
||||
帳本本來就屬於那一層）→ 這份原始碼所在 repo 的 `system-dev/` → `~/.claude/`。
|
||||
"""
|
||||
v = os.environ.get("MILESTONE_ACCOUNT_DIR")
|
||||
if v:
|
||||
return v
|
||||
for base in (os.environ.get("CLAUDE_PROJECT_DIR") or "", ROOT):
|
||||
if base and os.path.isdir(os.path.join(base, "system-dev")):
|
||||
return os.path.join(base, "system-dev", "estimates")
|
||||
return os.path.join(os.path.expanduser("~"), ".claude", "isep-estimates")
|
||||
|
||||
|
||||
DIR = _resolve_dir()
|
||||
LEDGER = os.path.join(DIR, "ledger.jsonl")
|
||||
FIXTURE = os.environ.get("MILESTONE_ACCOUNT_FIXTURE", "")
|
||||
DRY = False
|
||||
THRESHOLD = 25.0 # 差超過幾 % 就一定要挑代號（票上寫死「四分之一」）
|
||||
|
||||
# ── 封閉集合：七個代號，一個都不准多、不准少 ──────────────────────────────
|
||||
CODES = [
|
||||
("idle", "磨洋工", "小事拖成大事", "時間軸上有長長的空白"),
|
||||
("sidetrack", "分心跳線", "講到別的就跑去做", "期間出現不屬於這條線的動作"),
|
||||
("undispatched", "忘了派工", "該派沒派，票停著", "票很久沒有人被指派"),
|
||||
("cherry-pick", "偏科", "挑喜歡的做，難的擱著", "完成順序跟優先順序倒過來"),
|
||||
("waiting", "等答案", "問了就原地等，沒去做別的", "等待期間其他票零進度"),
|
||||
("scope-creep", "範圍變大", "一直塞新東西進來", "補收的次數、票數成長曲線"),
|
||||
("misestimate", "純粹估錯", "過程沒異常，就是估錯", "以上都沒有，但還是差很多"),
|
||||
]
|
||||
CODE_IDS = [c[0] for c in CODES]
|
||||
LABEL = {c[0]: c[1] for c in CODES}
|
||||
|
||||
|
||||
def die(msg, code=2):
|
||||
print(msg, file=sys.stderr)
|
||||
sys.exit(code)
|
||||
|
||||
|
||||
def token():
|
||||
root = os.environ.get("CLAUDE_PROJECT_DIR") or HERE
|
||||
host = HOST.split("//")[-1].rstrip("/")
|
||||
try:
|
||||
out = subprocess.run(["git", "-C", root, "remote", "-v"],
|
||||
capture_output=True, text=True, timeout=20).stdout
|
||||
except Exception:
|
||||
out = ""
|
||||
for line in out.splitlines():
|
||||
if host in line:
|
||||
m = re.search(r"//[^:/]+:([^@]+)@", line)
|
||||
if m:
|
||||
return m.group(1)
|
||||
for env in ("GITEA_TOKEN_CLAUDE_CODE", "GITEA_TOKEN"):
|
||||
if os.environ.get(env):
|
||||
return os.environ[env]
|
||||
return ""
|
||||
|
||||
|
||||
_FX = None
|
||||
|
||||
|
||||
def fx():
|
||||
global _FX
|
||||
if _FX is None:
|
||||
try:
|
||||
with open(FIXTURE) as f:
|
||||
_FX = json.load(f)
|
||||
except Exception:
|
||||
die("🔴 讀不到 MILESTONE_ACCOUNT_FIXTURE：%s" % FIXTURE)
|
||||
return _FX
|
||||
|
||||
|
||||
def api(path, payload=None, method=None):
|
||||
verb = method or ("POST" if payload is not None else "GET")
|
||||
if FIXTURE:
|
||||
if verb == "GET":
|
||||
return (fx().get("api") or {}).get(path)
|
||||
print(" [fixture] %s %s %s" % (verb, path, json.dumps(payload or {})))
|
||||
return {}
|
||||
if DRY and verb != "GET":
|
||||
print(" [dry-run] %s %s %s" % (verb, path, json.dumps(payload or {})))
|
||||
return {}
|
||||
tk = token()
|
||||
if not tk:
|
||||
die("🔴 拿不到 %s 的 token（remote 沒帶憑證，也沒有 GITEA_TOKEN_CLAUDE_CODE）" % HOST)
|
||||
data = json.dumps(payload).encode() if payload is not None else None
|
||||
req = urllib.request.Request(
|
||||
HOST + "/api/v1" + path, data=data, method=verb,
|
||||
headers={"Authorization": "token " + tk, "Content-Type": "application/json"})
|
||||
try:
|
||||
raw = urllib.request.urlopen(req, timeout=30).read()
|
||||
return json.loads(raw) if raw.strip() else {}
|
||||
except urllib.error.HTTPError as e:
|
||||
if e.code == 404:
|
||||
return None
|
||||
die("🔴 Gitea %d on %s %s：%s" % (e.code, verb, path, e.read().decode()[:200]))
|
||||
except Exception as e:
|
||||
die("🔴 連不上 %s：%s" % (HOST, e))
|
||||
|
||||
|
||||
# ── 時間 ─────────────────────────────────────────────────────────────────
|
||||
_TS = re.compile(r"^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})"
|
||||
r"(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?$")
|
||||
|
||||
|
||||
def ts(s):
|
||||
"""Gitea 的時間字串 → epoch 秒。認得 Z 與 +08:00 兩種尾巴；認不得回 None。"""
|
||||
if not s:
|
||||
return None
|
||||
m = _TS.match(str(s).strip())
|
||||
if not m:
|
||||
return None
|
||||
y, mo, d, h, mi, se, off = m.groups()
|
||||
t = time.mktime((int(y), int(mo), int(d), int(h), int(mi), int(se), 0, 1, 0)) \
|
||||
- time.timezone
|
||||
if off and off not in ("Z", "z"):
|
||||
sign = 1 if off[0] == "+" else -1
|
||||
off = off[1:].replace(":", "")
|
||||
t -= sign * (int(off[:2]) * 3600 + int(off[2:]) * 60)
|
||||
return t
|
||||
|
||||
|
||||
def now():
|
||||
v = os.environ.get("MILESTONE_ACCOUNT_NOW")
|
||||
return ts(v) if v else time.time()
|
||||
|
||||
|
||||
def days(sec):
|
||||
return sec / 86400.0
|
||||
|
||||
|
||||
def parse_ref(s):
|
||||
m = re.match(r"^([\w.-]+)/([\w.-]+)#(\d+)$", s.strip())
|
||||
if not m:
|
||||
die("🔴 寫法是 owner/repo#里程碑編號，你給的是：%s" % s)
|
||||
return m.group(1), m.group(2), int(m.group(3))
|
||||
|
||||
|
||||
# ── 三個數字 ─────────────────────────────────────────────────────────────
|
||||
def numbers(ms):
|
||||
"""回 (planned_days, actual_days, deviation_pct)。算不出來的格子回 None。"""
|
||||
c, due = ts(ms.get("created_at")), ts(ms.get("due_on"))
|
||||
end = ts(ms.get("closed_at")) or now()
|
||||
if c is None:
|
||||
return None, None, None
|
||||
actual = days(end - c)
|
||||
if due is None or due <= c:
|
||||
return None, actual, None
|
||||
planned = days(due - c)
|
||||
return planned, actual, (actual - planned) / planned * 100.0
|
||||
|
||||
|
||||
def fmt(v, unit=""):
|
||||
return "—" if v is None else ("%.1f%s" % (v, unit))
|
||||
|
||||
|
||||
def three_lines(ms, planned, actual, dev):
|
||||
return (" 當初訂的期限 %s天 （%s → %s）\n"
|
||||
" 實際花掉的 %s天 （到 %s）\n"
|
||||
" 差了 %s"
|
||||
% (fmt(planned), (ms.get("created_at") or "?")[:10],
|
||||
(ms.get("due_on") or "沒填期限")[:10],
|
||||
fmt(actual), (ms.get("closed_at") or "現在")[:10],
|
||||
"算不出來（期限沒填，或期限不晚於建立日）" if dev is None
|
||||
else "%+.0f%%%s" % (dev, " 🔴 超過 ±25%，要挑代號"
|
||||
if abs(dev) > THRESHOLD else "")))
|
||||
|
||||
|
||||
# ── 從 Gitea 時間軸取證據 ────────────────────────────────────────────────
|
||||
def fetch_issues(owner, repo):
|
||||
rows, page = [], 1
|
||||
while page <= 5:
|
||||
r = api("/repos/%s/%s/issues?state=all&type=issues&limit=50&page=%d"
|
||||
% (owner, repo, page))
|
||||
if not isinstance(r, list) or not r:
|
||||
break
|
||||
rows.extend(r)
|
||||
if len(r) < 50:
|
||||
break
|
||||
page += 1
|
||||
return rows
|
||||
|
||||
|
||||
def fetch_comments(owner, repo, since):
|
||||
q = "?limit=100"
|
||||
if since:
|
||||
q += "&since=" + urllib.parse.quote(since)
|
||||
r = api("/repos/%s/%s/issues/comments%s" % (owner, repo, q))
|
||||
return r if isinstance(r, list) else []
|
||||
|
||||
|
||||
def prio(issue):
|
||||
"""優先度：p/high=3、p/med=2、p/low=1、沒標=0。"""
|
||||
v = 0
|
||||
for l in issue.get("labels") or []:
|
||||
n = (l.get("name") or "").lower()
|
||||
if n in ("p/high", "p/urgent", "p0", "p1"):
|
||||
v = max(v, 3)
|
||||
elif n in ("p/med", "p/medium", "p2"):
|
||||
v = max(v, 2)
|
||||
elif n in ("p/low", "p3"):
|
||||
v = max(v, 1)
|
||||
return v
|
||||
|
||||
|
||||
def evidence(owner, repo, ms):
|
||||
"""把 Gitea 時間軸算成七個訊號。回 (signals, detail)。
|
||||
|
||||
🔴 這裡**一句話都不讀**：全部只看時間戳、指派欄位、標籤、票的歸屬。
|
||||
票上寫死「不採信我自己說的」，所以判準不能碰任何自然語言。
|
||||
"""
|
||||
start = ts(ms.get("created_at"))
|
||||
end = ts(ms.get("closed_at")) or now()
|
||||
span = max(end - start, 1.0)
|
||||
mid = ms.get("id")
|
||||
|
||||
issues = fetch_issues(owner, repo)
|
||||
if issues is None:
|
||||
issues = []
|
||||
mine = [i for i in issues if (i.get("milestone") or {}).get("id") == mid]
|
||||
others = [i for i in issues if (i.get("milestone") or {}).get("id") != mid]
|
||||
comments = fetch_comments(owner, repo, ms.get("created_at"))
|
||||
|
||||
mine_ids = set(i.get("number") for i in mine)
|
||||
|
||||
def cnum(c):
|
||||
u = c.get("issue_url") or c.get("html_url") or ""
|
||||
m = re.search(r"/(?:issues|pulls)/(\d+)", u)
|
||||
return int(m.group(1)) if m else c.get("issue_number")
|
||||
|
||||
ev_mine, ev_other = [], []
|
||||
for i in mine:
|
||||
for k in ("created_at", "closed_at"):
|
||||
t = ts(i.get(k))
|
||||
if t and start <= t <= end:
|
||||
ev_mine.append(t)
|
||||
for c in comments:
|
||||
t = ts(c.get("created_at"))
|
||||
if not t or not (start <= t <= end):
|
||||
continue
|
||||
(ev_mine if cnum(c) in mine_ids else ev_other).append(t)
|
||||
for i in others:
|
||||
t = ts(i.get("created_at"))
|
||||
if t and start <= t <= end:
|
||||
ev_other.append(t)
|
||||
|
||||
marks = sorted([start] + ev_mine + [end])
|
||||
gap, gap_at = 0.0, None
|
||||
for a, b in zip(marks, marks[1:]):
|
||||
if b - a > gap:
|
||||
gap, gap_at = b - a, a
|
||||
sig, det = {}, {}
|
||||
|
||||
# ① 磨洋工：時間軸上有長長的空白
|
||||
sig["idle"] = days(gap) >= 2.0 and gap / span >= 0.35
|
||||
det["idle"] = ("最長空白 %.1f 天（佔整段 %.0f%%），起點 %s"
|
||||
% (days(gap), gap / span * 100,
|
||||
time.strftime("%Y-%m-%d", time.gmtime(gap_at)) if gap_at else "?"))
|
||||
|
||||
# ② 分心跳線：期間出現不屬於這條線的動作
|
||||
tot = len(ev_mine) + len(ev_other)
|
||||
ratio = (len(ev_other) / tot) if tot else 0.0
|
||||
sig["sidetrack"] = len(ev_other) >= 5 and ratio >= 0.30
|
||||
det["sidetrack"] = ("這段期間 %d 個動作在這條線上、%d 個在別的票上（%.0f%%）"
|
||||
% (len(ev_mine), len(ev_other), ratio * 100))
|
||||
|
||||
# ③ 忘了派工：票很久沒有人被指派
|
||||
naked = [i for i in mine if not (i.get("assignees") or i.get("assignee"))
|
||||
and days(end - (ts(i.get("created_at")) or end)) >= days(span) * 0.5]
|
||||
sig["undispatched"] = len(naked) > 0
|
||||
det["undispatched"] = ("%d 張票整段期間沒有人被指派：%s"
|
||||
% (len(naked), ", ".join("#%s" % i.get("number")
|
||||
for i in naked[:6])) if naked
|
||||
else "每一張票都有人被指派過")
|
||||
|
||||
# ④ 偏科：完成順序跟優先順序倒過來
|
||||
inv = 0
|
||||
closed = [i for i in mine if ts(i.get("closed_at"))]
|
||||
openv = [i for i in mine if not ts(i.get("closed_at"))]
|
||||
for a in closed:
|
||||
for b in closed:
|
||||
if prio(a) < prio(b) and ts(a["closed_at"]) < ts(b["closed_at"]):
|
||||
inv += 1
|
||||
for a in closed:
|
||||
for b in openv:
|
||||
if prio(a) < prio(b):
|
||||
inv += 1
|
||||
sig["cherry-pick"] = inv >= 2
|
||||
det["cherry-pick"] = ("低優先先收掉、高優先還晾著的配對 %d 組" % inv)
|
||||
|
||||
# ⑤ 等答案：等待期間其他票零進度
|
||||
waitset = [i for i in mine
|
||||
if any((l.get("name") or "").lower() == "human"
|
||||
for l in (i.get("labels") or []))]
|
||||
wait_days = 0.0
|
||||
for i in waitset:
|
||||
s = ts(i.get("created_at")) or start
|
||||
e = ts(i.get("closed_at")) or end
|
||||
wait_days = max(wait_days, days(e - s))
|
||||
moved = sum(1 for i in mine
|
||||
if ts(i.get("closed_at")) and i not in waitset)
|
||||
sig["waiting"] = bool(waitset) and wait_days >= days(span) * 0.30 and moved == 0
|
||||
det["waiting"] = ("掛 Human 的票 %d 張、最長等 %.1f 天；期間其他票關掉 %d 張"
|
||||
% (len(waitset), wait_days, moved))
|
||||
|
||||
# ⑥ 範圍變大：補收的次數、票數成長曲線
|
||||
late = [i for i in mine
|
||||
if (ts(i.get("created_at")) or start) > start + span * 0.25]
|
||||
sig["scope-creep"] = len(late) >= 1 and len(mine) and len(late) / len(mine) >= 0.20
|
||||
det["scope-creep"] = ("開跑之後才補進來的票 %d／%d 張：%s"
|
||||
% (len(late), len(mine),
|
||||
", ".join("#%s" % i.get("number") for i in late[:6])))
|
||||
|
||||
# ⑦ 純粹估錯：以上都沒有
|
||||
sig["misestimate"] = not any(sig[c] for c in CODE_IDS if c != "misestimate")
|
||||
det["misestimate"] = ("上面六個訊號%s成立"
|
||||
% ("一個都沒有" if sig["misestimate"] else "有"))
|
||||
return sig, det
|
||||
|
||||
|
||||
def get_milestone(owner, repo, num):
|
||||
ms = api("/repos/%s/%s/milestones/%d" % (owner, repo, num))
|
||||
if not isinstance(ms, dict) or not ms.get("id"):
|
||||
die("🔴 抓不到里程碑 %s/%s#%d（編號對嗎？）" % (owner, repo, num))
|
||||
return ms
|
||||
|
||||
|
||||
# ── 指令 ─────────────────────────────────────────────────────────────────
|
||||
def cmd_codes(argv):
|
||||
print("七個代號（封閉集合，inkstone/ISEP#85）——「能統計的前提是分類有限」\n")
|
||||
for cid, label, plain, how in CODES:
|
||||
print(" %-13s %-8s %-22s 從哪看出來：%s" % (cid, label, plain, how))
|
||||
print("\n真的歸不進去 ⇒ 開一張票請 leo 核准加一個，**不要自己加**。")
|
||||
|
||||
|
||||
def _repos(argv):
|
||||
rs = [r for r in (argv[i + 1] for i, a in enumerate(argv)
|
||||
if a == "--repo" and i + 1 < len(argv))]
|
||||
if rs:
|
||||
return rs
|
||||
org = None
|
||||
for i, a in enumerate(argv):
|
||||
if a == "--org" and i + 1 < len(argv):
|
||||
org = argv[i + 1]
|
||||
if not org:
|
||||
die("用法：milestone-account list --org inkstone [--overdue] 或 --repo owner/repo")
|
||||
rows = api("/orgs/%s/repos?limit=100" % org)
|
||||
if not isinstance(rows, list):
|
||||
die("🔴 撈不到 %s 底下的 repo" % org)
|
||||
return [r["full_name"] for r in rows]
|
||||
|
||||
|
||||
def cmd_list(argv):
|
||||
overdue = "--overdue" in argv
|
||||
n = 0
|
||||
for full in _repos(argv):
|
||||
owner, repo = full.split("/", 1)
|
||||
mss = api("/repos/%s/%s/milestones?state=open&limit=50" % (owner, repo))
|
||||
if not isinstance(mss, list):
|
||||
continue
|
||||
for ms in mss:
|
||||
planned, actual, dev = numbers(ms)
|
||||
late = dev is not None and dev > 0
|
||||
if overdue and not late:
|
||||
continue
|
||||
n += 1
|
||||
print("%s %-34s %-30s 估 %s天／已 %s天／%s"
|
||||
% ("🔴" if (dev is not None and abs(dev) > THRESHOLD) else " ",
|
||||
"%s#%s" % (full, ms.get("id")), (ms.get("title") or "")[:28],
|
||||
fmt(planned), fmt(actual),
|
||||
"—" if dev is None else "%+.0f%%" % dev))
|
||||
print("\n共 %d 個%s里程碑。🔴 ＝ 差超過 ±25%%，結案時一定要挑一個代號。"
|
||||
% (n, "逾期的 " if overdue else "open "))
|
||||
print("挑代號之前先跑：milestone-account audit <owner/repo#編號>")
|
||||
|
||||
|
||||
def cmd_audit(argv):
|
||||
if not argv:
|
||||
die("用法：milestone-account audit <owner/repo#里程碑編號>")
|
||||
owner, repo, num = parse_ref(argv[0])
|
||||
ms = get_milestone(owner, repo, num)
|
||||
planned, actual, dev = numbers(ms)
|
||||
print("【%s/%s#%d】%s\n" % (owner, repo, num, ms.get("title") or ""))
|
||||
print(three_lines(ms, planned, actual, dev))
|
||||
sig, det = evidence(owner, repo, ms)
|
||||
print("\n【時間軸怎麼說】（全部取自 Gitea 的時間戳／欄位，一句話都沒讀）")
|
||||
for cid, label, _plain, _how in CODES:
|
||||
print(" %s %-13s %-8s %s" % ("🔴" if sig[cid] else " ", cid, label, det[cid]))
|
||||
ok = [c for c in CODE_IDS if sig[c]]
|
||||
print("\n可以挑的代號：%s" % " / ".join(ok))
|
||||
print("結案：milestone-account close %s/%s#%d --reason %s" % (owner, repo, num, ok[0]))
|
||||
|
||||
|
||||
def _ledger():
|
||||
rows = []
|
||||
try:
|
||||
with open(LEDGER) as f:
|
||||
for line in f:
|
||||
line = line.strip()
|
||||
if line:
|
||||
try:
|
||||
rows.append(json.loads(line))
|
||||
except Exception:
|
||||
pass
|
||||
except Exception:
|
||||
pass
|
||||
return rows
|
||||
|
||||
|
||||
def cmd_close(argv):
|
||||
if not argv:
|
||||
die("用法：milestone-account close <owner/repo#編號> [--reason 代號] [--dry-run]")
|
||||
owner, repo, num = parse_ref(argv[0])
|
||||
ref = "%s/%s#%d" % (owner, repo, num)
|
||||
reason = None
|
||||
for i, a in enumerate(argv):
|
||||
if a == "--reason" and i + 1 < len(argv):
|
||||
reason = argv[i + 1]
|
||||
|
||||
ms = get_milestone(owner, repo, num)
|
||||
planned, actual, dev = numbers(ms)
|
||||
print("【%s】%s\n" % (ref, ms.get("title") or ""))
|
||||
print(three_lines(ms, planned, actual, dev))
|
||||
|
||||
sig, det = evidence(owner, repo, ms)
|
||||
legal = [c for c in CODE_IDS if sig[c]]
|
||||
need = dev is None or abs(dev) > THRESHOLD
|
||||
|
||||
if need and not reason:
|
||||
die("\n🚫 **差 %s，超過 ±25%%——挑不出代號不准結案。**\n\n"
|
||||
"【inkstone/ISEP#85】「差超過四分之一（不管是超時還是提早太多，\n"
|
||||
" **提早太多代表當初估太鬆**）就要挑一個原因，而且**只能從固定的幾個裡面挑**，\n"
|
||||
" 不准用一段話帶過。」\n\n"
|
||||
"時間軸撐得住的代號：%s\n"
|
||||
"%s\n"
|
||||
" 再送一次：milestone-account close %s --reason %s\n"
|
||||
" 想看全部七個：milestone-account codes ／ 看證據：milestone-account audit %s"
|
||||
% ("算不出來（期限沒填）" if dev is None else "%+.0f%%" % dev,
|
||||
" / ".join(legal),
|
||||
"\n".join(" %-13s %s" % (c, det[c]) for c in legal), ref, legal[0], ref))
|
||||
|
||||
if reason:
|
||||
if reason not in CODE_IDS:
|
||||
die("\n🚫 `%s` 不是那七個代號之一。\n"
|
||||
" 【inkstone/ISEP#85】代號是**封閉集合**——「能統計的前提是分類有限」。\n"
|
||||
" 七個：%s\n"
|
||||
" 真的歸不進去 ⇒ 開票請 leo 核准加一個，不要自己造。"
|
||||
% (reason, " / ".join(CODE_IDS)))
|
||||
if reason not in legal:
|
||||
die("\n🚫 `%s`（%s）**時間軸撐不住**——不接受。\n\n"
|
||||
" 【inkstone/ISEP#85】「證據一律從 Gitea 的時間軸取"
|
||||
"（留言、指派、標籤、commit 都有時間戳），**不採信我自己說的**。」\n\n"
|
||||
" 這個代號的訊號：%s\n"
|
||||
" 撐得住的是：%s\n"
|
||||
" （訊號真的判錯了 ⇒ 那是 audit 的 bug，去修偵測器，"
|
||||
"不是在這裡繞過去——這條線的意義就是「可以統計、可以迭代」。）"
|
||||
% (reason, LABEL[reason], det[reason], " / ".join(legal)))
|
||||
|
||||
rec = {"ref": ref, "title": ms.get("title") or "",
|
||||
"created_at": ms.get("created_at"), "due_on": ms.get("due_on"),
|
||||
"closed_at": ms.get("closed_at") or time.strftime(
|
||||
"%Y-%m-%dT%H:%M:%SZ", time.gmtime(now())),
|
||||
"planned_days": None if planned is None else round(planned, 2),
|
||||
"actual_days": None if actual is None else round(actual, 2),
|
||||
"deviation_pct": None if dev is None else round(dev, 1),
|
||||
"over_threshold": bool(need),
|
||||
"reason": reason, "reason_label": LABEL.get(reason or "", ""),
|
||||
"signals": {c: bool(sig[c]) for c in CODE_IDS},
|
||||
"evidence": {c: det[c] for c in CODE_IDS},
|
||||
"recorded_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now()))}
|
||||
|
||||
if DRY:
|
||||
print("\n[dry-run] 會寫進 %s：" % LEDGER)
|
||||
print(json.dumps(rec, ensure_ascii=False, indent=2)[:900])
|
||||
print(" [dry-run] PATCH /repos/%s/%s/milestones/%d {\"state\": \"closed\"}"
|
||||
% (owner, repo, num))
|
||||
print("[dry-run] 一筆都沒有真的寫出去。")
|
||||
return
|
||||
|
||||
# 🔴 順序：**先記帳、再關**。反過來的話，關成功而記帳失敗，
|
||||
# 那個里程碑就永遠不會出現在統計裡——而那正是這張票要解的病。
|
||||
os.makedirs(DIR, exist_ok=True)
|
||||
with open(LEDGER, "a") as f:
|
||||
f.write(json.dumps(rec, ensure_ascii=False) + "\n")
|
||||
print("\n✅ 已記帳：%s 估 %s天／花 %s天／%s%s"
|
||||
% (ref, fmt(planned), fmt(actual),
|
||||
"—" if dev is None else "%+.0f%%" % dev,
|
||||
" 原因＝%s（%s）" % (reason, LABEL[reason]) if reason else ""))
|
||||
|
||||
if (ms.get("state") or "") != "closed":
|
||||
api("/repos/%s/%s/milestones/%d" % (owner, repo, num),
|
||||
{"state": "closed"}, method="PATCH")
|
||||
print("✅ 里程碑已關閉")
|
||||
else:
|
||||
print("ℹ️ 里程碑本來就是 closed，只補記帳")
|
||||
write_report()
|
||||
print("📊 累計統計已更新：%s" % os.path.join(DIR, "REPORT.md"))
|
||||
|
||||
|
||||
def write_report():
|
||||
rows = _ledger()
|
||||
cnt = {}
|
||||
for r in rows:
|
||||
if r.get("reason"):
|
||||
cnt[r["reason"]] = cnt.get(r["reason"], 0) + 1
|
||||
devs = [r["deviation_pct"] for r in rows if r.get("deviation_pct") is not None]
|
||||
lines = ["# 估多久／花多久／差多少——累計統計", "",
|
||||
"> 這份檔案由 `scripts/milestone-account` 自動重寫，**不要手改**。",
|
||||
"> 【inkstone/ISEP#85】「每次事後只能用『這次比較慢』這種話帶過，"
|
||||
"下次還是一樣。」", "",
|
||||
"- 累計結案 **%d** 個里程碑" % len(rows)]
|
||||
if devs:
|
||||
lines.append("\t- 平均偏差 **%+.0f%%**（正＝超時，負＝提早）"
|
||||
% (sum(devs) / len(devs)))
|
||||
lines.append("\t- 超過 ±25%% 的有 **%d** 個"
|
||||
% sum(1 for d in devs if abs(d) > THRESHOLD))
|
||||
lines.append("- 哪一種原因最常發生（這才是迭代的依據）")
|
||||
if not cnt:
|
||||
lines.append("\t- 目前還沒有任何被挑過的代號。")
|
||||
for cid, n in sorted(cnt.items(), key=lambda kv: -kv[1]):
|
||||
lines.append("\t- **%s（%s）** ×%d" % (LABEL.get(cid, cid), cid, n))
|
||||
lines.append("- 逐筆")
|
||||
for r in sorted(rows, key=lambda r: r.get("recorded_at") or "", reverse=True):
|
||||
lines.append("\t- `%s` %s" % (r["ref"], r.get("title", "")))
|
||||
lines.append("\t\t- 估 %s 天／花 %s 天／差 %s"
|
||||
% (r.get("planned_days"), r.get("actual_days"),
|
||||
"—" if r.get("deviation_pct") is None
|
||||
else "%+.0f%%" % r["deviation_pct"]))
|
||||
if r.get("reason"):
|
||||
lines.append("\t\t- 原因：**%s（%s）**" % (r.get("reason_label"), r["reason"]))
|
||||
lines.append("\t\t- 時間軸證據：%s"
|
||||
% (r.get("evidence") or {}).get(r["reason"], "—"))
|
||||
try:
|
||||
os.makedirs(DIR, exist_ok=True)
|
||||
with open(os.path.join(DIR, "REPORT.md"), "w") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
except Exception as e:
|
||||
die("🔴 寫不進 %s：%s" % (DIR, e))
|
||||
|
||||
|
||||
def cmd_report(argv):
|
||||
rows = _ledger()
|
||||
if not rows:
|
||||
print("（帳本還是空的：%s）" % LEDGER)
|
||||
print("關掉第一個里程碑就會有第一筆：milestone-account close <owner/repo#編號>")
|
||||
return
|
||||
cnt = {}
|
||||
for r in rows:
|
||||
if r.get("reason"):
|
||||
cnt[r["reason"]] = cnt.get(r["reason"], 0) + 1
|
||||
devs = [r["deviation_pct"] for r in rows if r.get("deviation_pct") is not None]
|
||||
print("累計結案 %d 個里程碑" % len(rows))
|
||||
if devs:
|
||||
print("平均偏差 %+.0f%%（正＝超時，負＝提早）；超過 ±25%% 的有 %d 個"
|
||||
% (sum(devs) / len(devs), sum(1 for d in devs if abs(d) > THRESHOLD)))
|
||||
print("\n哪一種原因最常發生：")
|
||||
if not cnt:
|
||||
print(" （還沒有任何被挑過的代號）")
|
||||
for cid, n in sorted(cnt.items(), key=lambda kv: -kv[1]):
|
||||
print(" %-13s %-8s ×%d %s" % (cid, LABEL.get(cid, cid), n, "█" * n))
|
||||
write_report()
|
||||
print("\n人看的版本：%s" % os.path.join(DIR, "REPORT.md"))
|
||||
|
||||
|
||||
def main():
|
||||
global DRY
|
||||
argv = sys.argv[1:]
|
||||
if "--dry-run" in argv:
|
||||
DRY = True
|
||||
argv = [a for a in argv if a != "--dry-run"]
|
||||
if not argv:
|
||||
print(__doc__)
|
||||
return
|
||||
cmd, rest = argv[0], argv[1:]
|
||||
table = {"codes": cmd_codes, "list": cmd_list, "audit": cmd_audit,
|
||||
"close": cmd_close, "report": cmd_report,
|
||||
# 給 hooks/milestone-account-guard.sh 問「帳本在哪」用的。
|
||||
# 讓「怎麼找到帳本」只有一份答案，閘不必自己再實作一次解析。
|
||||
"ledger-path": lambda a: print(LEDGER)}
|
||||
if cmd not in table:
|
||||
print(__doc__)
|
||||
die("🔴 沒有這個子指令：%s" % cmd)
|
||||
table[cmd](rest)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,410 @@
|
||||
#!/usr/bin/env python3
|
||||
"""release-manifest — 一次交貨 ＝ 一份清單（inkstone/ISEP#84）。
|
||||
|
||||
leo 的問題（票上原文）：「一次交貨常常同時動到好幾個 repo，但**沒有任何地方記著
|
||||
『這一版 ＝ 哪幾個 repo 的哪幾個版本』**⋯⋯要退版的時候，只退了其中一個 repo，
|
||||
剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。」
|
||||
|
||||
release-manifest freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.52 \
|
||||
--part inkstone/arcrun-collector@v0.18.36
|
||||
release-manifest current 我現在手上是哪一版、由什麼組成
|
||||
release-manifest list 全部清單，新的在上面
|
||||
release-manifest show R-2026.08.30
|
||||
release-manifest verify R-2026.08.30 清單上的版本號現在還抓得到嗎
|
||||
release-manifest diff R-2026.08.29 R-2026.08.30
|
||||
release-manifest rollback R-2026.08.29 退版：**整份一起退**
|
||||
|
||||
🔴 三條硬規則，全部長在這支工具裡（不是寫在文件裡靠人記得）：
|
||||
|
||||
① **freeze 之前每一個版本號都真的去 Gitea 抓一次**。抓不到就不給凍結——
|
||||
「寫上去」跟「存在」是兩件事，而清單的用處完全建立在後者。
|
||||
② **凍結了就不准再加東西**。同名清單已存在 ⇒ 拒絕覆寫，新的需求進下一份。
|
||||
③ **退版沒有「只退一個」這個選項**。`rollback` 一定吐出整份清單的每一格；
|
||||
指名單一 repo（`--only`）會被擋下，因為那正是票上那個病：
|
||||
**剩下的還停在新版 ⇒ 一組從來沒測過的組合。**
|
||||
|
||||
📌 跟 `release-tag-guard.sh` 是包含關係不是重複：那支管「打 tag 那一刻，
|
||||
單一 repo 內版本號三處一致」；這支管它上面那一層——**跨 repo 的組合**。
|
||||
|
||||
📌 單一 repo 的交貨不必特例：清單就退化成只有一格，規則一字不改。
|
||||
|
||||
離線測試：`scripts/test-release-manifest.sh`（走 `RELEASE_MANIFEST_FIXTURE`，不打網路）。
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
HOST = os.environ.get("RELEASE_MANIFEST_HOST", "https://git.uncle6.me")
|
||||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||||
def _resolve_dir():
|
||||
"""清單住哪裡。
|
||||
|
||||
🔴 **不能住在 plugin 目錄裡**：ISEP 是用 marketplace 裝的，
|
||||
`claude plugin update` 會把那個目錄整個換掉 ⇒ 所有出貨清單一次消失，
|
||||
而清單的用處全部發生在「以後要退版的那一天」。
|
||||
順序：環境變數 → 這個 session 的專案根（有 `system-dev/` ＝總管的工作區，
|
||||
跨 repo 的出貨清單本來就屬於那一層）→ 這份原始碼所在 repo → `~/.claude/`。
|
||||
"""
|
||||
v = os.environ.get("RELEASE_MANIFEST_DIR")
|
||||
if v:
|
||||
return v
|
||||
root = os.path.dirname(HERE)
|
||||
for base in (os.environ.get("CLAUDE_PROJECT_DIR") or "", root):
|
||||
if base and os.path.isdir(os.path.join(base, "system-dev")):
|
||||
return os.path.join(base, "releases")
|
||||
return os.path.join(os.path.expanduser("~"), ".claude", "isep-releases")
|
||||
|
||||
|
||||
DIR = _resolve_dir()
|
||||
FIXTURE = os.environ.get("RELEASE_MANIFEST_FIXTURE", "")
|
||||
DRY = False
|
||||
|
||||
NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
||||
PART_RE = re.compile(r"^([\w.-]+)/([\w.-]+)@(\S+)$")
|
||||
|
||||
|
||||
def die(msg, code=2):
|
||||
print(msg, file=sys.stderr)
|
||||
sys.exit(code)
|
||||
|
||||
|
||||
def token():
|
||||
root = os.environ.get("CLAUDE_PROJECT_DIR") or HERE
|
||||
host = HOST.split("//")[-1].rstrip("/")
|
||||
try:
|
||||
out = subprocess.run(["git", "-C", root, "remote", "-v"],
|
||||
capture_output=True, text=True, timeout=20).stdout
|
||||
except Exception:
|
||||
out = ""
|
||||
for line in out.splitlines():
|
||||
if host in line:
|
||||
m = re.search(r"//[^:/]+:([^@]+)@", line)
|
||||
if m:
|
||||
return m.group(1)
|
||||
for env in ("GITEA_TOKEN_CLAUDE_CODE", "GITEA_TOKEN"):
|
||||
if os.environ.get(env):
|
||||
return os.environ[env]
|
||||
return ""
|
||||
|
||||
|
||||
def _fixture():
|
||||
try:
|
||||
with open(FIXTURE) as f:
|
||||
return json.load(f)
|
||||
except Exception:
|
||||
die("🔴 讀不到 RELEASE_MANIFEST_FIXTURE：%s" % FIXTURE)
|
||||
|
||||
|
||||
def api(path):
|
||||
"""GET 一筆。回 dict／list，查不到回 None。fixture 模式完全不碰網路。"""
|
||||
if FIXTURE:
|
||||
return None
|
||||
tk = token()
|
||||
if not tk:
|
||||
die("🔴 拿不到 %s 的 token（remote 沒帶憑證，也沒有 GITEA_TOKEN_CLAUDE_CODE）" % HOST)
|
||||
try:
|
||||
req = urllib.request.Request(HOST + "/api/v1" + path,
|
||||
headers={"Authorization": "token " + tk})
|
||||
return json.load(urllib.request.urlopen(req, timeout=25))
|
||||
except urllib.error.HTTPError:
|
||||
return None
|
||||
except Exception as e:
|
||||
die("🔴 連不上 %s：%s" % (HOST, e))
|
||||
|
||||
|
||||
def resolve(owner, repo, ver):
|
||||
"""這個版本號**真的存在嗎**。存在回一段可以貼給人看的證據，不存在回 None。
|
||||
|
||||
先問 release，再問 tag：有些 repo 只打 tag 沒建 release，那也算存在
|
||||
（票上要的是「抓得到那個 release」＝抓得到那個版本，不是逼每個 repo 都建 release 頁）。
|
||||
"""
|
||||
if FIXTURE:
|
||||
fx = _fixture().get("versions") or {}
|
||||
return fx.get("%s/%s@%s" % (owner, repo, ver))
|
||||
r = api("/repos/%s/%s/releases/tags/%s" % (owner, repo, ver))
|
||||
if isinstance(r, dict) and r.get("tag_name"):
|
||||
return {"kind": "release", "url": r.get("html_url") or "",
|
||||
"commit": (r.get("target_commitish") or "")[:12]}
|
||||
t = api("/repos/%s/%s/tags/%s" % (owner, repo, ver))
|
||||
if isinstance(t, dict) and t.get("name"):
|
||||
return {"kind": "tag", "url": (t.get("commit") or {}).get("url") or "",
|
||||
"commit": ((t.get("commit") or {}).get("sha") or "")[:12]}
|
||||
return None
|
||||
|
||||
|
||||
# ── 清單的存取 ────────────────────────────────────────────────────────────
|
||||
def path_of(name):
|
||||
return os.path.join(DIR, name + ".json")
|
||||
|
||||
|
||||
def load(name):
|
||||
try:
|
||||
with open(path_of(name)) as f:
|
||||
return json.load(f)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def all_manifests():
|
||||
try:
|
||||
names = [f[:-5] for f in os.listdir(DIR) if f.endswith(".json")]
|
||||
except Exception:
|
||||
return []
|
||||
rows = [load(n) for n in names]
|
||||
rows = [m for m in rows if m]
|
||||
# 🔴 排序鍵不能只用時間戳：同一分鐘凍兩份清單就會並列，
|
||||
# 而並列之後「現在手上的是哪一份」會變成 os.listdir 的順序（等於隨機）。
|
||||
# seq 是 freeze 當下遞增的流水號 ⇒ 先後永遠有唯一解。
|
||||
rows.sort(key=lambda m: (m.get("seq", 0), m.get("frozen_at") or ""), reverse=True)
|
||||
return rows
|
||||
|
||||
|
||||
def parse_part(s):
|
||||
m = PART_RE.match(s.strip())
|
||||
if not m:
|
||||
die("🔴 寫法是 owner/repo@版本號，你給的是：%s" % s)
|
||||
return m.group(1), m.group(2), m.group(3)
|
||||
|
||||
|
||||
def opts(argv, name):
|
||||
return [argv[i + 1] for i, a in enumerate(argv) if a == name and i + 1 < len(argv)]
|
||||
|
||||
|
||||
def opt(argv, name, default=None):
|
||||
v = opts(argv, name)
|
||||
return v[0] if v else default
|
||||
|
||||
|
||||
# ── INDEX.md：leo 打開就看得懂「我現在手上是哪一版」 ──────────────────────
|
||||
def write_index():
|
||||
rows = all_manifests()
|
||||
lines = ["# 出貨清單（哪一版由哪幾個 repo 的哪幾版組成）", "",
|
||||
"> 這份檔案由 `scripts/release-manifest` 自動重寫，**不要手改**"
|
||||
"（手改的那一份會安靜地騙人）。", "",
|
||||
"- 每一列 ＝ 一次交貨。**最上面那一份就是現在手上的這一版。**"]
|
||||
if not rows:
|
||||
lines.append("\t- 目前還沒有任何凍結過的清單。")
|
||||
for i, m in enumerate(rows):
|
||||
head = "**%s**%s" % (m["name"], " ← 現在手上的這一版" if i == 0 else "")
|
||||
lines.append("\t- " + head)
|
||||
lines.append("\t\t- 凍結於 %s（UTC）" % m.get("frozen_at", "?"))
|
||||
if m.get("note"):
|
||||
lines.append("\t\t- 說明：%s" % m["note"])
|
||||
lines.append("\t\t- 由這些組成（沒有更動的 repo 不會出現在這裡）")
|
||||
for p in m.get("parts", []):
|
||||
ev = p.get("verified") or {}
|
||||
lines.append("\t\t\t- `%s` @ **%s** （凍結當下驗過：%s %s）"
|
||||
% (p["repo"], p["version"], ev.get("kind", "?"),
|
||||
ev.get("commit", "")))
|
||||
lines.append("\t\t- 要退回這一版：`scripts/release-manifest rollback %s`" % m["name"])
|
||||
lines.append("")
|
||||
lines.append("- 為什麼要有這份東西（`inkstone/ISEP#84`）")
|
||||
lines.append("\t- 退版只退了其中一個 repo，剩下的還停在新版"
|
||||
" ⇒ **變成一組從來沒測過的組合**。")
|
||||
lines.append("\t- 所以送測、放行、出貨、退版**全部以一份清單為單位**，"
|
||||
"不以單一 repo 為單位。")
|
||||
try:
|
||||
os.makedirs(DIR, exist_ok=True)
|
||||
with open(os.path.join(DIR, "INDEX.md"), "w") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
except Exception as e:
|
||||
die("🔴 寫不進 %s：%s" % (DIR, e))
|
||||
|
||||
|
||||
# ── freeze ───────────────────────────────────────────────────────────────
|
||||
def cmd_freeze(argv):
|
||||
if not argv:
|
||||
die("用法：release-manifest freeze <清單名> --part owner/repo@版本 [--part …] "
|
||||
"[--note 說明] [--dry-run]")
|
||||
name = argv[0]
|
||||
if not NAME_RE.match(name):
|
||||
die("🔴 清單名只准英數與 . _ -（例：R-2026.08.30），你給的是：%s" % name)
|
||||
raw = opts(argv[1:], "--part")
|
||||
if not raw:
|
||||
die("🚫 一份清單至少要有一格 --part owner/repo@版本號。\n"
|
||||
" （單一 repo 的交貨也要開清單——它只是退化成一格，規則不變。）")
|
||||
|
||||
if load(name) is not None:
|
||||
die("🚫 %s 已經凍結過了，不准再加東西。\n"
|
||||
" 【inkstone/ISEP#84】「清單一旦凍結就不再加東西，**新的需求進下一版**。」\n"
|
||||
" 要出新的組合 ⇒ 換一個清單名重新 freeze（舊的留著，退版時要用）。" % name)
|
||||
|
||||
seen, parts = set(), []
|
||||
for s in raw:
|
||||
owner, repo, ver = parse_part(s)
|
||||
full = "%s/%s" % (owner, repo)
|
||||
if full in seen:
|
||||
die("🔴 同一個 repo 在清單裡出現兩次：%s" % full)
|
||||
seen.add(full)
|
||||
ev = resolve(owner, repo, ver)
|
||||
if not ev:
|
||||
die("🚫 %s@%s **在 Gitea 上抓不到**——不給凍結。\n"
|
||||
" 【inkstone/ISEP#84 驗收 1】「清單上的版本號**真的存在**"
|
||||
"（不是寫上去而已，要抓得到那個 release）」。\n"
|
||||
" 先把那個 repo 的版本打出來（tag／release），再回來 freeze。"
|
||||
% (full, ver))
|
||||
parts.append({"repo": full, "version": ver, "verified": ev})
|
||||
|
||||
nxt = max([m.get("seq", 0) for m in all_manifests()] or [0]) + 1
|
||||
man = {"name": name, "seq": nxt,
|
||||
"frozen_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
|
||||
"note": opt(argv[1:], "--note", "") or "",
|
||||
"parts": parts}
|
||||
|
||||
if DRY:
|
||||
print("[dry-run] 會寫進 %s" % path_of(name))
|
||||
print(json.dumps(man, ensure_ascii=False, indent=2))
|
||||
print("[dry-run] 一個檔都沒有真的寫出去。")
|
||||
return
|
||||
os.makedirs(DIR, exist_ok=True)
|
||||
with open(path_of(name), "w") as f:
|
||||
json.dump(man, f, ensure_ascii=False, indent=2)
|
||||
write_index()
|
||||
print("✅ 清單 %s 已凍結（%d 個 repo，每一格都驗過真的抓得到）" % (name, len(parts)))
|
||||
for p in parts:
|
||||
print(" %-34s %s" % (p["repo"], p["version"]))
|
||||
print("\n📌 從現在起：送測／放行／出貨／退版都以 %s 為單位，不以單一 repo 為單位。" % name)
|
||||
print(" 人看的版本：%s" % os.path.join(DIR, "INDEX.md"))
|
||||
|
||||
|
||||
# ── verify / show / list / current / diff ────────────────────────────────
|
||||
def cmd_verify(argv):
|
||||
if not argv:
|
||||
die("用法：release-manifest verify <清單名>")
|
||||
man = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0])
|
||||
bad = 0
|
||||
for p in man["parts"]:
|
||||
owner, repo = p["repo"].split("/", 1)
|
||||
ev = resolve(owner, repo, p["version"])
|
||||
print("%s %-34s %s" % ("✅" if ev else "❌", p["repo"], p["version"]))
|
||||
if not ev:
|
||||
bad += 1
|
||||
if bad:
|
||||
die("\n🔴 %d 格抓不到了——這份清單現在**退不回去**，"
|
||||
"要嘛版本被刪了，要嘛當初就沒真的存在。" % bad)
|
||||
print("\n✅ %s 全部 %d 格都還抓得到，可以拿它退版。" % (man["name"], len(man["parts"])))
|
||||
|
||||
|
||||
def cmd_show(argv):
|
||||
if not argv:
|
||||
die("用法：release-manifest show <清單名>")
|
||||
man = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0])
|
||||
print(json.dumps(man, ensure_ascii=False, indent=2))
|
||||
|
||||
|
||||
def cmd_list(argv):
|
||||
rows = all_manifests()
|
||||
if not rows:
|
||||
print("（還沒有任何凍結過的清單。第一份用 release-manifest freeze 開。）")
|
||||
return
|
||||
for i, m in enumerate(rows):
|
||||
print("%s %-18s %s %d 個 repo：%s"
|
||||
% ("👉" if i == 0 else " ", m["name"], m.get("frozen_at", "?"),
|
||||
len(m.get("parts", [])),
|
||||
" + ".join("%s@%s" % (p["repo"].split("/")[-1], p["version"])
|
||||
for p in m.get("parts", []))))
|
||||
print("\n👉 ＝ 現在手上的這一版。人看的版本：%s" % os.path.join(DIR, "INDEX.md"))
|
||||
|
||||
|
||||
def cmd_current(argv):
|
||||
rows = all_manifests()
|
||||
if not rows:
|
||||
die("🔴 一份清單都沒有——「我現在手上是哪一版」目前沒有人答得出來。", 1)
|
||||
m = rows[0]
|
||||
print("現在手上的這一版：%s（凍結於 %s）" % (m["name"], m.get("frozen_at", "?")))
|
||||
for p in m["parts"]:
|
||||
print(" %-34s %s" % (p["repo"], p["version"]))
|
||||
|
||||
|
||||
def cmd_diff(argv):
|
||||
if len(argv) < 2:
|
||||
die("用法：release-manifest diff <舊清單> <新清單>")
|
||||
a = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0])
|
||||
b = load(argv[1]) or die("🔴 沒有這份清單：%s" % argv[1])
|
||||
va = {p["repo"]: p["version"] for p in a["parts"]}
|
||||
vb = {p["repo"]: p["version"] for p in b["parts"]}
|
||||
for repo in sorted(set(va) | set(vb)):
|
||||
x, y = va.get(repo), vb.get(repo)
|
||||
if x == y:
|
||||
print(" = %-34s %s" % (repo, x))
|
||||
elif x is None:
|
||||
print(" + %-34s %s（新進來的）" % (repo, y))
|
||||
elif y is None:
|
||||
print(" - %-34s %s（新清單裡沒有了）" % (repo, x))
|
||||
else:
|
||||
print(" ~ %-34s %s → %s" % (repo, x, y))
|
||||
|
||||
|
||||
# ── rollback：整份一起退，沒有「只退一個」這個選項 ────────────────────────
|
||||
def cmd_rollback(argv):
|
||||
if not argv:
|
||||
die("用法：release-manifest rollback <清單名> [--dry-run]")
|
||||
name = argv[0]
|
||||
man = load(name) or die("🔴 沒有這份清單：%s" % name)
|
||||
|
||||
only = opts(argv[1:], "--only")
|
||||
if only:
|
||||
die("🚫 **退版沒有「只退一個」這個選項。**（你指名了：%s）\n\n"
|
||||
" 【inkstone/ISEP#84】「要退版的時候，只退了其中一個 repo，\n"
|
||||
" 剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。」\n\n"
|
||||
" %s 這一版由 %d 個 repo 組成：\n%s\n"
|
||||
" ⇒ 拿掉 --only，整份一起退：release-manifest rollback %s\n"
|
||||
" ⇒ 真的只有一個 repo 要動 ⇒ 那就 freeze 一份**新的**清單，"
|
||||
"把不動的那幾格照抄過去。"
|
||||
% (", ".join(only), name, len(man["parts"]),
|
||||
"\n".join(" %s @ %s" % (p["repo"], p["version"])
|
||||
for p in man["parts"]), name))
|
||||
|
||||
cur = all_manifests()
|
||||
curv = {p["repo"]: p["version"] for p in cur[0]["parts"]} if cur else {}
|
||||
curname = cur[0]["name"] if cur else "（沒有）"
|
||||
|
||||
print("退版目標：%s（現在手上的是 %s）\n" % (name, curname))
|
||||
moves, stays = [], []
|
||||
for p in man["parts"]:
|
||||
(stays if curv.get(p["repo"]) == p["version"] else moves).append(p)
|
||||
|
||||
print("【要動的】")
|
||||
if not moves:
|
||||
print(" （沒有——現在手上的組合已經等於這份清單）")
|
||||
for p in moves:
|
||||
owner_repo = p["repo"]
|
||||
print(" %-34s %s → %s" % (owner_repo, curv.get(owner_repo, "?"), p["version"]))
|
||||
print(" git -C <%s 的工作目錄> fetch --tags && "
|
||||
"git -C <同上> checkout %s" % (owner_repo.split("/")[-1], p["version"]))
|
||||
if stays:
|
||||
print("\n【已經在目標版本、不必動】（列出來是為了讓你確認**沒有一格被漏掉**）")
|
||||
for p in stays:
|
||||
print(" %-34s %s" % (p["repo"], p["version"]))
|
||||
|
||||
print("\n🔴 這 %d 格是一組，要嘛全部到位，要嘛就不算退版完成。"
|
||||
% len(man["parts"]))
|
||||
print(" 退完跑一次複驗：release-manifest verify %s" % name)
|
||||
|
||||
|
||||
def main():
|
||||
global DRY
|
||||
argv = sys.argv[1:]
|
||||
if "--dry-run" in argv:
|
||||
DRY = True
|
||||
argv = [a for a in argv if a != "--dry-run"]
|
||||
if not argv:
|
||||
print(__doc__)
|
||||
return
|
||||
cmd, rest = argv[0], argv[1:]
|
||||
table = {"freeze": cmd_freeze, "verify": cmd_verify, "show": cmd_show,
|
||||
"list": cmd_list, "current": cmd_current, "diff": cmd_diff,
|
||||
"rollback": cmd_rollback}
|
||||
if cmd not in table:
|
||||
print(__doc__)
|
||||
die("🔴 沒有這個子指令：%s" % cmd)
|
||||
table[cmd](rest)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Executable
+222
@@ -0,0 +1,222 @@
|
||||
#!/bin/bash
|
||||
# 還債清單（scripts/debt-worklist）的測試——inkstone/ISEP#83 的四條驗收條件，一條一組。
|
||||
#
|
||||
# 全程離線：資料走 ISEP_DEBT_FIXTURE、時鐘走 ISEP_DEBT_NOW、狀態走 ISEP_DEBT_STATE_DIR。
|
||||
# **不打 Gitea、不留任何測試票、不碰 $HOME**。
|
||||
#
|
||||
# 為什麼要能離線測：這支工具的判斷（誰排前面、誰算緊急線、領走的還在不在）
|
||||
# 全都是純函式，只有「撈」那一步要網路。把撈的那一步換掉，其餘每一條都測得動——
|
||||
# 否則就只剩「今天跑起來看起來對」，那不是測試（本 repo 心法：跑過 ≠ 驗過）。
|
||||
cd "$(dirname "$0")/.." || exit 1
|
||||
W=scripts/debt-worklist
|
||||
PASS=0; FAIL=0
|
||||
T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
|
||||
NOW=2026-08-28T00:00:00Z
|
||||
|
||||
ok(){ # $1=條件 $2=說明
|
||||
if eval "$1"; then PASS=$((PASS+1)); printf ' ✅ %s\n' "$2"
|
||||
else FAIL=$((FAIL+1)); printf ' ❌ %s\n 判準：%s\n' "$2" "$1"; fi
|
||||
}
|
||||
|
||||
run(){ # 跑 list（或任何子命令），輸出留在 $OUT，離開碼留在 $RC
|
||||
# 🔴 ISEP_COUNTDOWN_STATE_DIR 也要指到暫存目錄：主線（hooks/lib/mainline.py）住在那裡，
|
||||
# 不隔離的話這支測試的結果會取決於「這台機器現在標了哪條主線」——那就不是測試了。
|
||||
OUT=$(ISEP_DEBT_FIXTURE="$FX" ISEP_DEBT_STATE_DIR="$T/state" ISEP_DEBT_NOW="$NOW" \
|
||||
ISEP_COUNTDOWN_STATE_DIR="$ML_DIR" python3 "$W" "$@" 2>&1); RC=$?
|
||||
}
|
||||
|
||||
ML_DIR="$T/mainline"; mkdir -p "$ML_DIR"
|
||||
set_mainline(){ # $1=主線 milestone 標題（空＝沒有主線）
|
||||
if [ -z "$1" ]; then rm -f "$ML_DIR/mainline.json"; return; fi
|
||||
python3 - "$ML_DIR/mainline.json" "$1" <<'PY'
|
||||
import json, sys
|
||||
path, title = sys.argv[1], sys.argv[2]
|
||||
json.dump({"ref": "inkstone/A#1", "owner": "inkstone", "repo": "A", "id": 1,
|
||||
"title": title, "members": [], "due_on": ""}, open(path, "w"))
|
||||
PY
|
||||
}
|
||||
|
||||
# ── 造資料：一份長得像 Gitea 回應的 fixture ─────────────────────────────────
|
||||
mkfx(){ FX="$T/$1.json"; python3 - "$FX" "$1" <<'PY'
|
||||
import json, sys
|
||||
path, which = sys.argv[1], sys.argv[2]
|
||||
|
||||
def it(repo, n, title, labels=(), ms=None, ms_state="open", assignees=(),
|
||||
updated="2026-08-01T00:00:00Z", body="", pr=False):
|
||||
d = {"number": n, "title": title, "body": body, "updated_at": updated,
|
||||
"created_at": "2026-07-01T00:00:00Z", "state": "open",
|
||||
"labels": [{"name": l} for l in labels],
|
||||
"assignees": [{"login": a} for a in assignees] or None,
|
||||
"repository": {"full_name": repo},
|
||||
"html_url": f"https://git.uncle6.me/{repo}/issues/{n}"}
|
||||
if ms:
|
||||
d["milestone"] = {"title": ms, "state": ms_state}
|
||||
if ms == "上個 sprint":
|
||||
d["milestone"]["due_on"] = "2026-08-10T23:59:59Z" # 已經過了 18 天
|
||||
if pr:
|
||||
d["pull_request"] = {"merged": False}
|
||||
return d
|
||||
|
||||
repos = [{"name": "inkstone/A", "issues": 0, "prs": 0},
|
||||
{"name": "inkstone/B", "issues": 0, "prs": 0}]
|
||||
deps, items = {}, []
|
||||
|
||||
if which == "full":
|
||||
items = [
|
||||
# 事故＋擋住別人的 → 該排第一
|
||||
it("inkstone/A", 1, "壞掉了", ["type/bug"], updated="2026-08-20T00:00:00Z",
|
||||
body="x" * 2000),
|
||||
it("inkstone/A", 2, "我等 A#1", updated="2026-08-27T00:00:00Z",
|
||||
body="被 inkstone/A#1 擋住" + "y" * 2000),
|
||||
it("inkstone/B", 9, "我也等 A#1", updated="2026-08-27T00:00:00Z",
|
||||
body="要先解 inkstone/A#1" + "y" * 2000),
|
||||
# 掛在 open milestone 上＝緊急線在管，不該出現
|
||||
it("inkstone/A", 3, "緊急線的票", ["p/high", "type/bug"], ms="這週出貨"),
|
||||
# 掛在**別條**（非主線）milestone 上，而且期限已經過了
|
||||
it("inkstone/A", 8, "別條線的票", ms="上個 sprint", body="q" * 2000),
|
||||
# milestone 已關但票還開著＝孤兒，該出現
|
||||
it("inkstone/A", 4, "孤兒票", ms="上週", ms_state="closed", body="z" * 2000),
|
||||
# 等 leo 的三種，都不該出現在可領清單
|
||||
it("inkstone/A", 5, "等 leo 批", ["Human", "p/high", "type/bug"]),
|
||||
it("inkstone/A", 6, "等 leo 動手", ["human/exec"]),
|
||||
it("inkstone/A", 7, "等 leo 驗", ["s/stage", "p/high"]),
|
||||
# 放很久沒人動 vs 昨天才動過：同條件下前者要排前面
|
||||
it("inkstone/B", 10, "放了很久", updated="2026-06-01T00:00:00Z", body="w" * 2000),
|
||||
it("inkstone/B", 11, "昨天才動過", updated="2026-08-27T00:00:00Z", body="w" * 2000),
|
||||
# 躺著的 PR 也是債
|
||||
it("inkstone/B", 12, "躺著的 PR", pr=True, updated="2026-08-10T00:00:00Z",
|
||||
body="v" * 2000),
|
||||
# p/low：往後排
|
||||
it("inkstone/B", 13, "晚點沒關係", ["p/low"], body="u" * 2000),
|
||||
# 互相指著＝必然同包
|
||||
it("inkstone/B", 20, "雙胞胎甲", body="跟 inkstone/B#21 是同一件事" + "t" * 2000,
|
||||
updated="2026-08-05T00:00:00Z"),
|
||||
it("inkstone/B", 21, "雙胞胎乙", body="見 inkstone/B#20" + "t" * 2000,
|
||||
updated="2026-08-05T00:00:00Z"),
|
||||
# 母票／子票：只有原生相依看得出來（內文沒有互指）
|
||||
it("inkstone/B", 30, "母票", body="s" * 2000, updated="2026-08-05T00:00:00Z"),
|
||||
it("inkstone/B", 31, "子票", body="s" * 2000, updated="2026-08-05T00:00:00Z"),
|
||||
]
|
||||
deps = {"inkstone/B#30": ["inkstone/B#31"]}
|
||||
|
||||
elif which == "empty":
|
||||
items = [it("inkstone/A", 3, "緊急線的票", ["p/high"], ms="這週出貨"),
|
||||
it("inkstone/A", 5, "等 leo 批", ["Human"])]
|
||||
|
||||
elif which == "onedone":
|
||||
# 「昨天領走的今天關掉了」——它從 open 清單消失
|
||||
items = [it("inkstone/A", 2, "我等 A#1", body="y" * 2000)]
|
||||
|
||||
json.dump({"repos": repos, "items": items, "deps": deps}, open(path, "w"))
|
||||
PY
|
||||
}
|
||||
|
||||
mkfx full; FULL="$T/full.json"
|
||||
mkfx empty
|
||||
mkfx onedone
|
||||
|
||||
echo "── 驗收 1：跑一次要吐出排好序的清單＋「我查了哪些 repo」的證明 ──"
|
||||
FX="$FULL"; run list --top 20
|
||||
ok '[ "$RC" = 0 ]' '離開碼 0'
|
||||
ok 'grep -q "查過的 repo：2 個" <<<"$OUT"' '證明段落列出查過的 repo 數'
|
||||
ok 'grep -q "inkstone/A" <<<"$OUT" && grep -q "inkstone/B" <<<"$OUT"' '每個 repo 都列名（不是只給總數）'
|
||||
ok 'grep -q "1\. \[.*\] inkstone/A#1" <<<"$OUT"' '事故＋擋住兩張 ⇒ 排第一名'
|
||||
ok 'grep -q "事故+40" <<<"$OUT"' '每張票旁邊看得到「為什麼排這裡」的分項'
|
||||
ok 'grep -q "擋住2張" <<<"$OUT"' '「擋住別人的」算得出來（兩張指著 A#1）'
|
||||
|
||||
echo "── 驗收 1b：排序的五個條件真的有作用 ──"
|
||||
pos(){ grep -n "$1" <<<"$OUT" | head -1 | cut -d: -f1; }
|
||||
ok '[ "$(pos "inkstone/B#10")" -lt "$(pos "inkstone/B#11")" ]' '放最久的排在昨天才動過的前面'
|
||||
ok '[ "$(pos "inkstone/B#12")" -lt "$(pos "inkstone/B#13")" ]' '躺著的 PR 排在 p/low 前面'
|
||||
ok 'grep -q "PR躺著+25" <<<"$OUT"' 'PR 被認出來（不是只算 issue）'
|
||||
ok '! grep -q "inkstone/A#3" <<<"$OUT"' '掛 open milestone 的不進清單（那歸緊急線）'
|
||||
ok 'grep -q "inkstone/A#4" <<<"$OUT"' 'milestone 已關但票還開著 ⇒ 是債，要進清單'
|
||||
ok '! grep -q "inkstone/A#5" <<<"$OUT" && ! grep -q "inkstone/A#6" <<<"$OUT"' \
|
||||
'Human／human-exec 不進可領清單（沒有人能替 leo 領）'
|
||||
ok '! grep -q "inkstone/A#7" <<<"$OUT"' 's/stage＝等 leo 驗，要催不是要領'
|
||||
ok 'grep -q "等 leo 的 3 張" <<<"$OUT"' '被扣掉的有講數字，不是靜靜消失'
|
||||
|
||||
echo "── 驗收 1c：成包——相關的要一起領，但不准黏成一坨 ──"
|
||||
ok 'grep -A6 "inkstone/B#20（票）" <<<"$OUT" | grep -q "inkstone/B#21"' '互相指著的成同一包'
|
||||
ok 'grep -A6 "inkstone/B#30（票）" <<<"$OUT" | grep -q "inkstone/B#31"' '原生相依（母票→子票）成同一包'
|
||||
ok '! (grep -A6 "inkstone/A#1（票）" <<<"$OUT" | grep -q "同一包")' \
|
||||
'單向引用不成包（A#2、B#9 都指著 A#1，但 A#1 沒指回來 ⇒ 不能黏成一坨）'
|
||||
|
||||
echo "── 接上「現在的主線是哪一個」（inkstone/ISEP#82 的唯一答案）──"
|
||||
set_mainline ""; FX="$FULL"; run list --top 20
|
||||
ok 'grep -q "現在沒有標主線" <<<"$OUT"' '沒標主線 ⇒ 照實說，不編一條出來'
|
||||
ok '! grep -q "inkstone/A#3" <<<"$OUT" && ! grep -q "inkstone/A#8" <<<"$OUT"' \
|
||||
'沒標主線 ⇒ 保守：掛 open milestone 的一律不領（不跟緊急線搶同一張）'
|
||||
set_mainline "這週出貨"; run list --top 20
|
||||
ok 'grep -q "現在的主線" <<<"$OUT" && grep -q "這週出貨" <<<"$OUT"' \
|
||||
'標了主線 ⇒ 清單上講得出用的是哪一條（判斷來自 scripts/mainline，不是自己算的）'
|
||||
ok '! grep -q "inkstone/A#3" <<<"$OUT"' '在主線上的票仍然不領（那是緊急線在管的）'
|
||||
ok 'grep -q "inkstone/A#8" <<<"$OUT"' '掛在別條 milestone 的是債（那條線現在沒人推）'
|
||||
ok 'grep -q "逾期17天的承諾+15" <<<"$OUT"' '別條 milestone 已逾期 ⇒ 算「答應過人家的」加分'
|
||||
ok 'grep -q "別條\*\* milestone 上的 1 張仍算債" <<<"$OUT"' '被改判成債的有幾張，講出來'
|
||||
set_mainline "" # 收回去，後面幾組回到「沒有主線」的世界
|
||||
|
||||
echo "── 驗收 2：清單是空的要說話，不能默默結束 ──"
|
||||
FX="$T/empty.json"; run list
|
||||
ok '[ "$RC" = 0 ]' '離開碼 0（沒東西可領不是錯誤）'
|
||||
ok 'grep -q "查詢跑過了，結果是零" <<<"$OUT"' '明講「查過了，結果是零」'
|
||||
ok 'grep -q "查過的 repo：2 個" <<<"$OUT"' '空清單一樣附查詢證明（分得出「沒東西」與「沒查」）'
|
||||
|
||||
echo "── 驗收 3：今天領走的，明天不在清單上 ──"
|
||||
rm -rf "$T/state"; FX="$FULL"
|
||||
run claim inkstone/B#20 inkstone/B#21
|
||||
ok '[ "$RC" = 0 ]' '領走兩張成功'
|
||||
run list --top 20
|
||||
PICK=$(sed -n '/今天可以領的/,$p' <<<"$OUT")
|
||||
ok '! grep -q "inkstone/B#21" <<<"$PICK"' '領走的不再出現在可領清單（只看清單那一段）'
|
||||
ok 'grep -q "之前領走的 2 張" <<<"$OUT"' '第二天看得到「之前領走的」那一段'
|
||||
ok 'grep -q "還開著 2" <<<"$OUT"' '還開著的照實說（沒關就是還沒做完）'
|
||||
ok 'grep -q "已經領走的 2 張" <<<"$OUT"' '扣除數字對得上'
|
||||
|
||||
echo "── 驗收 3b：領走的票關掉之後，狀態要跟著變 ──"
|
||||
FX="$T/onedone.json"; run list
|
||||
ok 'grep -q "已關 2" <<<"$OUT"' '票已經不在 open 清單 ⇒ 認定它做完了'
|
||||
|
||||
echo "── 驗收 3c：放回去 ──"
|
||||
FX="$FULL"; run forget inkstone/B#20 inkstone/B#21
|
||||
ok '[ "$RC" = 0 ]' 'forget 成功'
|
||||
run list --top 20
|
||||
ok 'grep -q "inkstone/B#20" <<<"$OUT"' '放回去之後又回到可領清單'
|
||||
|
||||
echo "── 誤用：擋得住，而且說得出怎麼改 ──"
|
||||
run claim B#20
|
||||
ok '[ "$RC" = 2 ] && grep -q "owner/repo#N" <<<"$OUT"' '票號寫錯 ⇒ 擋下並示範正確寫法'
|
||||
run claim inkstone/B#999
|
||||
ok '[ "$RC" = 2 ]' '領一張不存在／已關的票 ⇒ 擋下'
|
||||
run claim
|
||||
ok '[ "$RC" = 2 ] && grep -q "用法" <<<"$OUT"' '沒給票號 ⇒ 印用法'
|
||||
|
||||
echo "── 機器可讀（要接進別的東西時不用 parse 中文）──"
|
||||
run list --json
|
||||
ok 'python3 -c "import json,sys;d=json.load(sys.stdin);sys.exit(0 if d[\"bundles\"] and d[\"repos\"] else 1)" <<<"$OUT"' \
|
||||
'--json 吐得出合法 JSON，且有 bundles／repos'
|
||||
|
||||
echo "── 紅線：這支腳本自己不會醒（不准做成輪詢／fan-out）──"
|
||||
ok '! grep -nE "time\\.sleep|crontab|sched|urlopen.*hooks" '"$W" \
|
||||
'原始碼裡沒有等待／排程／裝 webhook 的動作（只有註解在談紅線，那不算）'
|
||||
|
||||
echo "── SessionStart 那一句：不用有人記得下指令，也不准偷偷打網路 ──"
|
||||
# 把 session-start-recall.sh 裡「還債線」那一段切出來單獨跑（其餘段落會打雲端，這裡不要）。
|
||||
FRAG="$T/frag.sh"
|
||||
sed -n '/push 6：還債線/,/^echo ""$/p' hooks/session-start-recall.sh > "$FRAG"
|
||||
ok '[ -s "$FRAG" ]' 'session-start-recall.sh 裡真的有那一段（被刪掉就會紅）'
|
||||
rm -rf "$T/nudge"; mkdir -p "$T/nudge"
|
||||
OUT=$(set -euo pipefail; ISEP_DEBT_STATE_DIR="$T/nudge" bash "$FRAG" 2>&1); RC=$?
|
||||
ok '[ "$RC" = 0 ]' '沒有狀態檔也跑得過（第一次開 session）'
|
||||
ok 'grep -q "今天還沒撈過" <<<"$OUT"' '今天沒撈過 ⇒ 開 session 就會說'
|
||||
ok 'grep -q "debt-worklist list" <<<"$OUT"' '順手把要跑的那一行給出來'
|
||||
printf '{"claims":{"a/b#1":{}},"last_run":"%sT00:00:00Z"}' "$(date -u +%Y-%m-%d)" > "$T/nudge/claimed.json"
|
||||
OUT=$(ISEP_DEBT_STATE_DIR="$T/nudge" bash "$FRAG" 2>&1)
|
||||
ok 'grep -q "今天撈過了" <<<"$OUT"' '今天撈過了 ⇒ 不再重複催'
|
||||
ok 'grep -q "手上領著 1 張" <<<"$OUT"' '手上還領著幾張講出來'
|
||||
ok '! grep -qE "curl|urlopen|http" <<<"$(cat "$FRAG")"' \
|
||||
'SessionStart 那一段完全不打網路（撈是人決定的動作，不是開機自動去撈）'
|
||||
|
||||
echo
|
||||
echo "通過 $PASS 條，失敗 $FAIL 條"
|
||||
[ "$FAIL" = 0 ]
|
||||
@@ -0,0 +1,155 @@
|
||||
#!/usr/bin/env bash
|
||||
# scripts/milestone-account 的迴歸測試（inkstone/ISEP#85）
|
||||
#
|
||||
# 驗收 1：關掉一個 milestone → 三個數字要自己算出來，不用手填
|
||||
# 驗收 2：差超過 25% → 要逼我挑一個代號，挑不出來不准結案
|
||||
# 驗收 3：累積幾次之後 → 看得出哪一種原因最常發生
|
||||
# 驗收 4：拿已經逾期的 milestone 進去算 → 要算得出數字
|
||||
#
|
||||
# 🔴 全程離線（MILESTONE_ACCOUNT_FIXTURE ＝一份假的 Gitea 回應表），
|
||||
# 時鐘用 MILESTONE_ACCOUNT_NOW 定住，帳本寫在 mktemp 目錄。
|
||||
# **不打 Gitea、不關任何真的 milestone、不碰 repo 裡的 system-dev/estimates/。**
|
||||
set -u
|
||||
TOOL="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/milestone-account}"
|
||||
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
|
||||
PASS=0; FAIL=0; N=0
|
||||
NOW="2026-08-28T00:00:00Z"
|
||||
FX="$TMP/fx.json"
|
||||
|
||||
python3 - "$FX" <<'PY'
|
||||
import json, sys, urllib.parse
|
||||
api = {}
|
||||
|
||||
def iso(d, h=0):
|
||||
return "2026-08-%02dT%02d:00:00Z" % (d, h)
|
||||
|
||||
def issue(n, created, closed=None, assignee=True, labels=(), ms=None):
|
||||
return {"number": n, "created_at": created, "closed_at": closed,
|
||||
"updated_at": closed or created,
|
||||
"assignees": [{"login": "cc"}] if assignee else [],
|
||||
"labels": [{"name": l} for l in labels],
|
||||
"milestone": ({"id": ms} if ms else None)}
|
||||
|
||||
def comment(n, at):
|
||||
return {"issue_url": "https://x/api/v1/repos/o/r/issues/%d" % n, "created_at": at}
|
||||
|
||||
def repo(full, mid, title, created, due, closed, issues, comments, open_ms=True):
|
||||
o, r = full.split("/")
|
||||
ms = {"id": mid, "title": title, "created_at": created, "due_on": due,
|
||||
"closed_at": closed, "state": "open" if closed is None else "closed"}
|
||||
api["/repos/%s/%s/milestones/%d" % (o, r, mid)] = ms
|
||||
api["/repos/%s/%s/issues?state=all&type=issues&limit=50&page=1" % (o, r)] = issues
|
||||
api["/repos/%s/%s/issues/comments?limit=100&since=%s"
|
||||
% (o, r, urllib.parse.quote(created))] = comments
|
||||
api["/repos/%s/%s/milestones?state=open&limit=50" % (o, r)] = [ms] if open_ms else []
|
||||
|
||||
# ① A#12 磨洋工：08-02 收掉一張之後，時間軸整整空了 24 天
|
||||
repo("inkstone/A", 12, "sprint-磨洋工", iso(1), "2026-08-08T23:59:59Z", None,
|
||||
[issue(1, iso(1, 1), iso(2), ms=12), issue(2, iso(1, 2), ms=12),
|
||||
issue(3, iso(1, 3), ms=12), issue(9, iso(10), ms=None)],
|
||||
[comment(1, iso(26))])
|
||||
|
||||
# ② B#13 準時收掉：偏差只有 -6%，不必挑代號
|
||||
repo("inkstone/B", 13, "sprint-準時", iso(20), "2026-08-27T23:59:59Z",
|
||||
"2026-08-27T12:00:00Z",
|
||||
[issue(1, iso(20, 1), iso(25), ms=13), issue(2, iso(20, 2), iso(26), ms=13)],
|
||||
[comment(1, iso(22)), comment(2, iso(24))], open_ms=False)
|
||||
|
||||
# ③ C#14 過程沒異常、就是估錯：每兩天都有動作，其他六個訊號全不成立
|
||||
repo("inkstone/C", 14, "sprint-估錯", iso(1), "2026-08-10T23:59:59Z",
|
||||
"2026-08-25T00:00:00Z",
|
||||
[issue(1, iso(1, 1), iso(24), ms=14), issue(2, iso(1, 2), iso(23), ms=14)],
|
||||
[comment(1, iso(d)) for d in range(3, 25, 2)], open_ms=False)
|
||||
|
||||
# ④ D#15 範圍變大：開跑之後又補進來三張票
|
||||
repo("inkstone/D", 15, "sprint-範圍變大", iso(1), "2026-08-10T23:59:59Z",
|
||||
"2026-08-25T00:00:00Z",
|
||||
[issue(1, iso(1, 1), iso(24), ms=15), issue(2, iso(1, 2), iso(23), ms=15),
|
||||
issue(3, iso(15), ms=15), issue(4, iso(15, 1), ms=15),
|
||||
issue(5, iso(15, 2), ms=15)],
|
||||
[comment(1, iso(d)) for d in range(3, 25, 2)], open_ms=False)
|
||||
|
||||
api["/orgs/inkstone/repos?limit=100"] = [
|
||||
{"full_name": "inkstone/%s" % x} for x in "ABCD"]
|
||||
json.dump({"api": api}, open(sys.argv[1], "w"), ensure_ascii=False)
|
||||
PY
|
||||
|
||||
run() { MILESTONE_ACCOUNT_FIXTURE="$FX" MILESTONE_ACCOUNT_DIR="$TMP/led" \
|
||||
MILESTONE_ACCOUNT_NOW="$NOW" python3 "$TOOL" "$@" 2>&1; }
|
||||
|
||||
t() {
|
||||
want="$1"; desc="$2"; must="$3"; shift 4
|
||||
N=$((N+1)); out=$(run "$@"); rc=$?
|
||||
ok=1; [ "$rc" -eq "$want" ] || ok=0
|
||||
if [ -n "$must" ] && ! printf '%s' "$out" | grep -qF "$must"; then ok=0; fi
|
||||
if [ "$ok" -eq 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ %s —— 期望 exit=%s%s，實得 exit=%s\n' "$desc" "$want" \
|
||||
"${must:+ 且輸出含「$must」}" "$rc"
|
||||
printf '%s\n' "$out" | sed -n '1,12p' | sed 's/^/ /'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
}
|
||||
|
||||
echo "── 驗收 1：三個數字自己算出來 ─────────────────────────────"
|
||||
t 0 "① audit 印出「當初訂的期限」" "當初訂的期限" -- audit inkstone/A#12
|
||||
t 0 "② audit 印出「實際花掉的」" "實際花掉的" -- audit inkstone/A#12
|
||||
t 0 "③ 偏差算得出來（A#12 逾期 +238%）" "+238%" -- audit inkstone/A#12
|
||||
t 0 "④ 期限是 08-08、實際算到今天 08-28 ⇒ 27 天" "27.0天" -- audit inkstone/A#12
|
||||
|
||||
echo "── 驗收 2：差超過 25% 逼你挑代號 ──────────────────────────"
|
||||
t 2 "⑤ A#12 差 +237% 卻沒給 --reason ⇒ 不准結案" "挑不出代號不准結案" -- \
|
||||
close inkstone/A#12
|
||||
t 2 "⑥ 承上：訊息要直接列出撐得住的代號" "時間軸撐得住的代號：idle" -- close inkstone/A#12
|
||||
t 0 "⑦ B#13 只差 -6% ⇒ 不必挑代號，直接結得掉" "已記帳" -- close inkstone/B#13
|
||||
t 2 "⑧ 造一個不存在的代號 ⇒ 擋（封閉集合）" "不是那七個代號之一" -- \
|
||||
close inkstone/A#12 --reason 拖延症
|
||||
t 2 "⑨ 挑一個時間軸撐不住的代號 ⇒ 擋（不採信我自己說的）" "時間軸撐不住" -- \
|
||||
close inkstone/C#14 --reason idle
|
||||
t 0 "⑩ C#14 六個訊號都不成立 ⇒ 唯一合法的是 misestimate" "misestimate" -- \
|
||||
audit inkstone/C#14
|
||||
t 0 "⑪ 承上：--reason misestimate 收得掉" "原因＝misestimate" -- \
|
||||
close inkstone/C#14 --reason misestimate
|
||||
t 0 "⑫ A#12 挑 idle（時間軸真的有 24 天空白）⇒ 收得掉" "原因＝idle" -- \
|
||||
close inkstone/A#12 --reason idle
|
||||
t 0 "⑬ D#15 開跑後補三張票 ⇒ scope-creep 撐得住" "原因＝scope-creep" -- \
|
||||
close inkstone/D#15 --reason scope-creep
|
||||
|
||||
echo "── 驗收 3：看得出哪一種原因最常發生 ───────────────────────"
|
||||
t 0 "⑭ report 數得出每個代號各幾次" "磨洋工" -- report
|
||||
t 0 "⑮ report 算得出累計結案幾個" "累計結案 4 個里程碑" -- report
|
||||
N=$((N+1))
|
||||
if grep -q "哪一種原因最常發生" "$TMP/led/REPORT.md" 2>/dev/null \
|
||||
&& grep -q "時間軸證據" "$TMP/led/REPORT.md"; then
|
||||
printf ' ✅ ⑯ REPORT.md 寫出來了，而且每一筆都帶時間軸證據\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ⑯ REPORT.md 內容不對\n'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
N=$((N+1))
|
||||
if [ "$(wc -l < "$TMP/led/ledger.jsonl")" = "4" ]; then
|
||||
printf ' ✅ ⑰ 帳本剛好四筆（沒有被擋下的那幾次也記進去）\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ⑰ 帳本筆數不對：%s\n' "$(wc -l < "$TMP/led/ledger.jsonl" 2>/dev/null)"
|
||||
FAIL=$((FAIL+1))
|
||||
fi
|
||||
|
||||
echo "── 驗收 4：拿已經逾期的里程碑進去算 ───────────────────────"
|
||||
t 0 "⑱ list --overdue 撈得到逾期的那一個，而且帶數字" "inkstone/A#12" -- \
|
||||
list --org inkstone --overdue
|
||||
t 0 "⑲ 承上：逾期的要被標成「差超過 ±25%」那一類" "🔴" -- \
|
||||
list --org inkstone --overdue
|
||||
|
||||
echo "── 其他 ───────────────────────────────────────────────────"
|
||||
t 0 "⑳ codes 印得出七個代號，一個不多一個不少" "misestimate" -- codes
|
||||
N=$((N+1))
|
||||
if [ "$(run codes | grep -cE '^ [a-z-]+ ')" = "7" ]; then
|
||||
printf ' ✅ ㉑ 真的是七個（封閉集合）\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ㉑ 代號數量不是 7：%s\n' "$(run codes | grep -cE '^ [a-z-]+ ')"; FAIL=$((FAIL+1))
|
||||
fi
|
||||
t 0 "㉒ --dry-run 印出要打的那通 API 但不送出" "一筆都沒有真的寫出去" -- \
|
||||
close inkstone/A#12 --reason idle --dry-run
|
||||
t 2 "㉓ 里程碑編號寫錯 ⇒ 講清楚寫法" "寫法是 owner/repo#里程碑編號" -- audit ISEP-12
|
||||
|
||||
echo
|
||||
echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）"
|
||||
[ "$FAIL" -eq 0 ]
|
||||
@@ -0,0 +1,98 @@
|
||||
#!/usr/bin/env bash
|
||||
# scripts/release-manifest 的迴歸測試（inkstone/ISEP#84）
|
||||
#
|
||||
# 兩個方向都要有證據：
|
||||
# A 群「該擋」——版本號在 Gitea 抓不到／清單已凍結還想加東西／退版只退一個
|
||||
# B 群「該過」——版本號真的存在就凍結得起來、退版吐出整份、diff 看得出差在哪
|
||||
# C 群「leo 打開看得懂」——INDEX.md 真的被重寫，而且第一份標著「現在手上的這一版」
|
||||
#
|
||||
# 🔴 全程離線（RELEASE_MANIFEST_FIXTURE），不打 Gitea、不建任何真的 release。
|
||||
# 清單寫在 mktemp 的目錄（RELEASE_MANIFEST_DIR），不碰 repo 裡的 releases/。
|
||||
set -u
|
||||
TOOL="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/release-manifest}"
|
||||
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
|
||||
PASS=0; FAIL=0; N=0
|
||||
|
||||
FX="$TMP/fx.json"
|
||||
cat > "$FX" <<'JSON'
|
||||
{"versions": {
|
||||
"inkstone/Arcrun@v1.4.52": {"kind":"release","url":"u1","commit":"aaaaaaaaaaaa"},
|
||||
"inkstone/Arcrun@v1.4.51": {"kind":"release","url":"u2","commit":"bbbbbbbbbbbb"},
|
||||
"inkstone/arcrun-collector@v0.18.36": {"kind":"tag","url":"u3","commit":"cccccccccccc"},
|
||||
"inkstone/arcrun-collector@v0.18.35": {"kind":"tag","url":"u4","commit":"dddddddddddd"}
|
||||
}}
|
||||
JSON
|
||||
|
||||
run() { RELEASE_MANIFEST_FIXTURE="$FX" RELEASE_MANIFEST_DIR="$TMP/rel" python3 "$TOOL" "$@" 2>&1; }
|
||||
|
||||
# t <期望 exit> <說明> <必須出現的字串（可空）> -- <參數…>
|
||||
t() {
|
||||
want="$1"; desc="$2"; must="$3"; shift 4
|
||||
N=$((N+1))
|
||||
out=$(run "$@"); rc=$?
|
||||
ok=1
|
||||
[ "$rc" -eq "$want" ] || ok=0
|
||||
if [ -n "$must" ] && ! printf '%s' "$out" | grep -qF "$must"; then ok=0; fi
|
||||
if [ "$ok" -eq 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ %s —— 期望 exit=%s%s，實得 exit=%s\n' "$desc" "$want" \
|
||||
"${must:+ 且輸出含「$must」}" "$rc"
|
||||
printf '%s\n' "$out" | sed -n '1,8p' | sed 's/^/ /'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
}
|
||||
|
||||
echo "── B 群：該過 ──────────────────────────────────────────────"
|
||||
t 0 "① 兩個 repo 的版本都真的存在 ⇒ 凍結得起來" "已凍結（2 個 repo" -- \
|
||||
freeze R-2026.08.29 --part inkstone/Arcrun@v1.4.51 --part inkstone/arcrun-collector@v0.18.35
|
||||
t 0 "② 單一 repo 的交貨不必特例（清單退化成一格）" "已凍結（1 個 repo" -- \
|
||||
freeze R-single --part inkstone/Arcrun@v1.4.51
|
||||
t 0 "③ 再凍一份新的（這才是「新的需求進下一版」）" "已凍結（2 個 repo" -- \
|
||||
freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.52 --part inkstone/arcrun-collector@v0.18.36
|
||||
t 0 "④ current 答得出「我現在手上是哪一版」" "R-2026.08.30" -- current
|
||||
t 0 "⑤ verify：每一格都還抓得到" "全部 2 格都還抓得到" -- verify R-2026.08.30
|
||||
t 0 "⑥ diff 看得出兩份差在哪一格" "v1.4.51 → v1.4.52" -- diff R-2026.08.29 R-2026.08.30
|
||||
t 0 "⑦ --dry-run 不寫檔" "一個檔都沒有真的寫出去" -- \
|
||||
freeze R-dryrun --part inkstone/Arcrun@v1.4.52 --dry-run
|
||||
t 2 "⑧ 承上：--dry-run 那份真的沒被寫出去" "沒有這份清單" -- show R-dryrun
|
||||
|
||||
echo "── A 群：該擋 ──────────────────────────────────────────────"
|
||||
t 2 "⑨ 版本號在 Gitea 抓不到 ⇒ 不給凍結（驗收 1）" "在 Gitea 上抓不到" -- \
|
||||
freeze R-bad --part inkstone/Arcrun@v9.9.9
|
||||
t 2 "⑩ 承上：整份都不寫（不會留下半份清單）" "沒有這份清單" -- show R-bad
|
||||
t 2 "⑪ 一格都不給 ⇒ 擋" "至少要有一格" -- freeze R-empty
|
||||
t 2 "⑫ 同名清單已凍結 ⇒ 不准再加東西" "新的需求進下一版" -- \
|
||||
freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.51
|
||||
t 2 "⑬ 同一個 repo 出現兩次 ⇒ 擋" "出現兩次" -- \
|
||||
freeze R-dup --part inkstone/Arcrun@v1.4.51 --part inkstone/Arcrun@v1.4.52
|
||||
t 2 "⑭ 清單名亂寫 ⇒ 擋" "清單名只准" -- freeze "R 2026/08" --part inkstone/Arcrun@v1.4.51
|
||||
t 2 "⑮ part 寫法不對 ⇒ 擋" "寫法是 owner/repo@版本號" -- \
|
||||
freeze R-x --part Arcrun-v1.4.52
|
||||
|
||||
echo "── 驗收 2／3：退版 ─────────────────────────────────────────"
|
||||
t 0 "⑯ 退版吐出整份清單的每一格（驗收 2）" "這 2 格是一組" -- rollback R-2026.08.29
|
||||
t 0 "⑰ 承上：兩個 repo 都被列進「要動的」" "arcrun-collector" -- rollback R-2026.08.29
|
||||
t 2 "⑱ 試著只退其中一個 ⇒ 被擋下來（驗收 3）" "沒有「只退一個」這個選項" -- \
|
||||
rollback R-2026.08.29 --only inkstone/Arcrun
|
||||
t 0 "⑲ 已經在目標版本的那幾格也要列出來（沒有一格被漏掉）" "不必動" -- \
|
||||
rollback R-2026.08.30
|
||||
|
||||
echo "── 驗收 4：leo 打開那份清單看得懂 ──────────────────────────"
|
||||
N=$((N+1))
|
||||
IDX="$TMP/rel/INDEX.md"
|
||||
if [ -f "$IDX" ] && grep -q "現在手上的這一版" "$IDX" \
|
||||
&& grep -q "R-2026.08.30" "$IDX" && grep -q "從來沒測過的組合" "$IDX"; then
|
||||
printf ' ✅ ⑳ INDEX.md 被重寫，標出「現在手上的這一版」與為什麼要有它\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ⑳ INDEX.md 內容不對\n'; sed -n '1,20p' "$IDX" 2>/dev/null | sed 's/^/ /'
|
||||
FAIL=$((FAIL+1))
|
||||
fi
|
||||
N=$((N+1))
|
||||
if head -20 "$IDX" 2>/dev/null | grep -A2 "R-2026.08.30" | grep -q "現在手上的這一版"; then
|
||||
printf ' ✅ ㉑ 最新那一份（不是最舊那份）才被標成「現在手上的」\n'; PASS=$((PASS+1))
|
||||
else
|
||||
printf ' ❌ ㉑ 標錯了哪一份是現在手上的\n'; FAIL=$((FAIL+1))
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）"
|
||||
[ "$FAIL" -eq 0 ]
|
||||
Executable
+274
@@ -0,0 +1,274 @@
|
||||
#!/bin/bash
|
||||
# 「下游做完時頂層跟著關」的測試（inkstone/ISEP#92）
|
||||
#
|
||||
# 這支測三件事：
|
||||
# ① 判準本身（純函式 is_loose／writeback_plan／journey_label）
|
||||
# —— 這三支不打網路，所以「撈得對不對」「回寫該做什麼」測得動，
|
||||
# 不必真的開票、關票來驗。
|
||||
# ② `subtask`／`handoff` 的參數閘：該擋的擋、齊全的放得過
|
||||
# ③ `loose` 這個動詞真的接得上（走到網路那一層才炸）
|
||||
#
|
||||
# 怎麼在「不真的動任何票」的前提下分辨擋／放行（沿用 test-ticket-where-seen-guard.sh）：
|
||||
# TICKET_HOST 指到一個連不上的位址（127.0.0.1:9）
|
||||
# 離開碼 2 ＝ 閘擋下（die）
|
||||
# 離開碼 1 ＝ 閘全部放行，走到網路那一層才炸（Connection refused）
|
||||
# 全程離線、不打真實 Gitea、不產生任何票、不關任何票。
|
||||
cd "$(dirname "$0")/.." || exit 1
|
||||
T=scripts/ticket
|
||||
TMP=$(mktemp -d)
|
||||
trap 'rm -rf "$TMP"' EXIT
|
||||
PASS=0; FAIL=0
|
||||
|
||||
cat > "$TMP/body.md" <<'MD'
|
||||
## 目標
|
||||
測試用內文。
|
||||
|
||||
## 驗收條件
|
||||
離開碼 2 ＝ 被擋；離開碼 1 ＝ 放行（走到網路才炸）。
|
||||
|
||||
## deliverable 類型
|
||||
code
|
||||
MD
|
||||
BAD_BODY="$TMP/bad.md"; echo "沒有模板欄位" > "$BAD_BODY"
|
||||
TITLE="身為看頂層票的人，我要下游做完時頂層跟著關，我才不會看到一堆早就做完的票"
|
||||
|
||||
# ── 純函式探針：把 scripts/ticket 當模組載進來問 ────────────────────────
|
||||
probe() { # probe <python 片段> → 印出結果
|
||||
python3 - "$1" <<'PY'
|
||||
import sys, importlib.util as u
|
||||
from importlib.machinery import SourceFileLoader as L
|
||||
spec = u.spec_from_loader("t", L("t", "scripts/ticket"))
|
||||
m = u.module_from_spec(spec); spec.loader.exec_module(m)
|
||||
print(eval(sys.argv[1], {"m": m}))
|
||||
PY
|
||||
}
|
||||
|
||||
p() { # p <說明> <want> <python 片段>
|
||||
got=$(probe "$3" 2>&1)
|
||||
if [ "$got" = "$2" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf 'want=%s got=%s %s\n' "$2" "$got" "$1"
|
||||
}
|
||||
|
||||
O='{"state":"open"}'; C='{"state":"closed"}'
|
||||
|
||||
echo "── ① is_loose：「下游都關了、自己還開著」是機械事實 ──"
|
||||
p "★ open ＋ 下游全關 → 撈得到（票上驗收第 3 條）" "True" "m.is_loose('open',[$C,$C])"
|
||||
p "open ＋ 還有一張下游開著 → 不撈（它還在跑）" "False" "m.is_loose('open',[$C,$O])"
|
||||
p "open ＋ 從來沒有下游 → 不撈（它根本不是頂層票）" "False" "m.is_loose('open',[])"
|
||||
p "closed ＋ 下游全關 → 不撈（自己都關了）" "False" "m.is_loose('closed',[$C,$C])"
|
||||
p "open ＋ 下游全開 → 不撈" "False" "m.is_loose('open',[$O,$O])"
|
||||
|
||||
echo
|
||||
echo "── ② writeback_plan：下游關掉之後，頂層票該被怎麼處理 ──"
|
||||
p "★ 最後一張下游關掉 → handback（指派回總管＋s/review，不默默留著）" \
|
||||
"('handback', [])" "m.writeback_plan('open',[$C,$C])"
|
||||
p "還有別的下游沒關 → 只記一筆，別假裝它可以收了" \
|
||||
"('note', [{'state': 'open'}])" "m.writeback_plan('open',[$C,$O])"
|
||||
p "頂層票自己已經關了 → skip" \
|
||||
"('skip', [])" "m.writeback_plan('closed',[$C,$C])"
|
||||
p "頂層票已關但還有 open 下游 → 一樣 skip（不去吵已關的票）" \
|
||||
"('skip', [{'state': 'open'}])" "m.writeback_plan('closed',[$O])"
|
||||
p "防禦：頂層票沒有任何下游（實務上到不了這裡）→ 不會炸" \
|
||||
"('handback', [])" "m.writeback_plan('open',[])"
|
||||
|
||||
echo
|
||||
echo "── ③ journey_label：只加前綴，不猜名字合不合法 ──"
|
||||
p "收件匣 → j/收件匣" "j/收件匣" "m.journey_label('收件匣')"
|
||||
p "已經帶前綴 → 不重複加" "j/收件匣" "m.journey_label('j/收件匣')"
|
||||
p "前後空白 → 修掉" "j/收件匣" "m.journey_label(' 收件匣 ')"
|
||||
|
||||
echo
|
||||
echo "── ④ subtask／handoff 的參數閘（該擋）──"
|
||||
run() { # run <want_rc> <說明> <verb> [參數...]
|
||||
want=$1; what=$2; verb=$3; shift 3
|
||||
out=$(TICKET_HOST=http://127.0.0.1:9 GITEA_TOKEN=x \
|
||||
python3 "$T" "$verb" inkstone/ISEP#92 "$@" 2>&1)
|
||||
got=$?
|
||||
LAST_OUT="$out"
|
||||
if [ "$got" = "$want" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf 'want=%s got=%s %s\n' "$want" "$got" "$what"
|
||||
}
|
||||
has() { if printf '%s' "$LAST_OUT" | grep -q "$1"; then PASS=$((PASS+1)); printf ' ✅ '
|
||||
else FAIL=$((FAIL+1)); printf ' ❌ '; fi; printf '訊息裡有「%s」 %s\n' "$1" "$2"; }
|
||||
|
||||
run 2 "缺 --title" subtask -F "$TMP/body.md"
|
||||
run 2 "缺 -F" subtask --title "$TITLE"
|
||||
run 2 "標題不是 User Story" subtask --title "整理一下票" -F "$TMP/body.md"
|
||||
run 2 "內文缺模板欄位" subtask --title "$TITLE" -F "$BAD_BODY"
|
||||
run 2 "指派了人卻沒寫 --next" subtask --title "$TITLE" -F "$TMP/body.md" --assign someone
|
||||
run 2 "--journey 給了空字串（對不上就不要加這個參數）" \
|
||||
subtask --title "$TITLE" -F "$TMP/body.md" --journey ""
|
||||
has "不硬湊" "空 journey 的訊息講的是「不硬湊」，不是叫人隨便填一個"
|
||||
|
||||
echo
|
||||
echo "── ⑤ 齊全就放得過（誤攔比漏擋更該修）──"
|
||||
run 1 "subtask 齊全 → 走到網路才炸" subtask --title "$TITLE" -F "$TMP/body.md"
|
||||
run 1 "★ handoff 是同一個動作的別名，一樣放得過" handoff --title "$TITLE" -F "$TMP/body.md" --to arcrun-rag
|
||||
run 1 "帶 --journey 一樣放得過" subtask --title "$TITLE" -F "$TMP/body.md" --journey 收件匣
|
||||
run 1 "--assign 有配 --next → 放行" subtask --title "$TITLE" -F "$TMP/body.md" --assign someone --next "先看一眼"
|
||||
|
||||
echo
|
||||
echo "── ⑥ loose 這個動詞接得上 ──"
|
||||
out=$(TICKET_HOST=http://127.0.0.1:9 GITEA_TOKEN=x python3 "$T" loose 2>&1); got=$?
|
||||
if [ "$got" = 1 ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf 'want=1 got=%s loose 走到網路那一層才炸（動詞有註冊、參數不擋）\n' "$got"
|
||||
|
||||
out=$(python3 "$T" 2>&1)
|
||||
if printf '%s' "$out" | grep -q "ticket loose"; then PASS=$((PASS+1)); printf ' ✅ '
|
||||
else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf '不帶參數的說明裡列得出 loose（撈不到的東西等於不存在）\n'
|
||||
|
||||
echo
|
||||
echo "── ⑦ 完工回寫的接線（票上驗收第 2 條）──"
|
||||
echo " 把 api() 換成錄音機跑一次 _writeback，驗它到底打了哪些端點、送了什麼。"
|
||||
echo " 不打網路、不動任何真票；/blocks 的回應形狀取自 2026-08-28 實查 inkstone/ISEP#75。"
|
||||
w() { # w <說明> <want> <python 片段（用 rec 這個錄音清單）>
|
||||
got=$(python3 - "$3" <<'PY' 2>&1
|
||||
import sys, json, importlib.util as u
|
||||
from importlib.machinery import SourceFileLoader as L
|
||||
spec = u.spec_from_loader("t", L("t", "scripts/ticket"))
|
||||
m = u.module_from_spec(spec); spec.loader.exec_module(m)
|
||||
|
||||
SCEN = json.loads(__import__("os").environ["SCEN"])
|
||||
rec = []
|
||||
def fake_api(path, payload=None, method=None):
|
||||
rec.append((method or ("POST" if payload is not None else "GET"), path, payload))
|
||||
if path.endswith("/blocks"):
|
||||
return SCEN["blocks"]
|
||||
if path.endswith("/dependencies"):
|
||||
return SCEN["deps"]
|
||||
if "/labels" in path and (method or "GET") == "GET":
|
||||
return [{"name": n, "id": i} for i, n in enumerate(SCEN.get("labels", []), 1)]
|
||||
return {}
|
||||
m.api = fake_api
|
||||
# _writeback 會把進度印出來——那是給人看的，不是這支測試的判準。
|
||||
# 判準是**它打了哪些端點、送了什麼**（rec），所以把它的輸出吞掉。
|
||||
import contextlib, io
|
||||
buf = io.StringIO()
|
||||
with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
|
||||
m._writeback("inkstone", "arcrun-rag", 143, "https://example/pr/1")
|
||||
print(eval(sys.argv[1], {"rec": rec, "m": m}))
|
||||
PY
|
||||
)
|
||||
if [ "$got" = "$2" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf 'want=%s got=%s %s\n' "$2" "$got" "$1"
|
||||
}
|
||||
|
||||
PARENT='{"number":136,"state":"open","title":"頂層票","labels":[{"name":"s/doing"},{"name":"p/high"}],"repository":{"full_name":"inkstone/arcrun-rag"}}'
|
||||
LBL='["s/todo","s/doing","s/review","p/high"]'
|
||||
|
||||
# 情境 A：這是最後一張下游 → 母票要被指派回總管＋改 s/review
|
||||
export SCEN="{\"blocks\":[$PARENT],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}}],\"labels\":$LBL}"
|
||||
w "★ 有去問子票的 /blocks（誰在等我）" "True" \
|
||||
"any(p.endswith('/issues/143/blocks') for _,p,_ in rec)"
|
||||
w "★ 有在母票的時間軸貼回寫留言" "True" \
|
||||
"any(mm=='POST' and p=='/repos/inkstone/arcrun-rag/issues/136/comments' for mm,p,_ in rec)"
|
||||
w "★ 留言裡點名了剛關掉的那張下游票" "True" \
|
||||
"any('arcrun-rag#143' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))"
|
||||
w "★ 留言裡有交付物連結（不是空口說做完了）" "True" \
|
||||
"any('https://example/pr/1' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))"
|
||||
w "★ 留言第一行有身份欄（機器貼的留言一樣要標）" "True" \
|
||||
"all((pl or {}).get('body','').startswith('【身份】') for _,p,pl in rec if p.endswith('/136/comments'))"
|
||||
w "★ 母票被指派回總管（欄位，不是一句話）" "['claude-code']" \
|
||||
"[(pl or {}).get('assignees') for mm,p,pl in rec if mm=='PATCH' and p=='/repos/inkstone/arcrun-rag/issues/136'][0]"
|
||||
w "★ 母票的 s/* 換成 s/review，而非 s/* 的標籤留著" "True" \
|
||||
"[sorted(pl['labels'])==sorted([3,4]) for mm,p,pl in rec if mm=='PUT' and p.endswith('/136/labels')][0]"
|
||||
w "沒有去關母票（關票要有人驗——默默關掉跟默默留著是同一個病）" "False" \
|
||||
"any((pl or {}).get('state')=='closed' for _,_,pl in rec)"
|
||||
|
||||
# 情境 B：母票還有別的下游沒關 → 只記一筆，不准指派、不准改 tag
|
||||
export SCEN="{\"blocks\":[$PARENT],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}},{\"state\":\"open\",\"number\":150,\"title\":\"還沒做的\",\"repository\":{\"full_name\":\"inkstone/Arcrun\"}}],\"labels\":$LBL}"
|
||||
w "還有下游沒關 → 只貼留言，不指派" "False" "any(mm=='PATCH' for mm,_,_ in rec)"
|
||||
w "還有下游沒關 → 不改 tag" "False" "any(mm=='PUT' for mm,_,_ in rec)"
|
||||
w "留言裡把還沒關的那張列出來（跨 repo 也要列全稱）" "True" \
|
||||
"any('inkstone/Arcrun#150' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))"
|
||||
|
||||
# 情境 C：母票自己已經關了 → 完全不動它
|
||||
PARENT_CLOSED='{"number":136,"state":"closed","title":"頂層票","labels":[],"repository":{"full_name":"inkstone/arcrun-rag"}}'
|
||||
export SCEN="{\"blocks\":[$PARENT_CLOSED],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}}],\"labels\":$LBL}"
|
||||
w "母票已關 → 一則留言都不貼（不去吵已關的票）" "False" \
|
||||
"any(p.endswith('/136/comments') for _,p,_ in rec)"
|
||||
|
||||
# 情境 D：這張票沒有任何頂層票在等它 → 不要吵
|
||||
export SCEN="{\"blocks\":[],\"deps\":[],\"labels\":$LBL}"
|
||||
w "沒有頂層票在等它 → 只問一次 /blocks 就收工" "1" "len(rec)"
|
||||
unset SCEN
|
||||
|
||||
echo
|
||||
echo "── ⑧ 雙向連結的接線（票上驗收第 1 條）──"
|
||||
echo " 同樣用錄音機跑一次 subtask：驗「兩張票互相看得到對方」不是靠人記得補。"
|
||||
b() { # b <說明> <want> <python 片段> [額外 argv...]
|
||||
what=$1; want=$2; frag=$3; shift 3
|
||||
got=$(ARGS_JSON=$(printf '%s\n' "$@" | python3 -c "import sys,json;print(json.dumps([l.rstrip('\n') for l in sys.stdin if l.strip()!='']))") \
|
||||
python3 - "$frag" <<'PY' 2>&1
|
||||
import sys, os, json, contextlib, io, importlib.util as u
|
||||
from importlib.machinery import SourceFileLoader as L
|
||||
spec = u.spec_from_loader("t", L("t", "scripts/ticket"))
|
||||
m = u.module_from_spec(spec); spec.loader.exec_module(m)
|
||||
|
||||
rec = []
|
||||
def fake_api(path, payload=None, method=None):
|
||||
rec.append((method or ("POST" if payload is not None else "GET"), path, payload))
|
||||
if path.endswith("/labels?limit=100"):
|
||||
return [{"name": n, "id": i} for i, n in
|
||||
enumerate(["s/todo", "s/review", "p/high", "j/收件匣"], 1)]
|
||||
if path.endswith("/dependencies"):
|
||||
return [{"state": "open", "number": 900, "title": "子票",
|
||||
"repository": {"full_name": "inkstone/arcrun-rag"}}]
|
||||
if path == "/repos/inkstone/ISEP/issues":
|
||||
return {"number": 900, "html_url": "https://git.uncle6.me/inkstone/ISEP/issues/900"}
|
||||
if path == "/repos/inkstone/arcrun-rag/issues":
|
||||
return {"number": 900, "html_url": "https://git.uncle6.me/inkstone/arcrun-rag/issues/900"}
|
||||
if path == "/repos/inkstone/ISEP/issues/92":
|
||||
return {"number": 92, "labels": [{"name": "p/high"}]}
|
||||
return {}
|
||||
m.api = fake_api
|
||||
argv = ["inkstone/ISEP#92"] + json.loads(os.environ["ARGS_JSON"])
|
||||
buf = io.StringIO()
|
||||
blocked = False
|
||||
with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
|
||||
try:
|
||||
m.cmd_subtask(argv)
|
||||
except SystemExit:
|
||||
blocked = True # 被閘擋下也是一種結果，不該讓整支測試靜靜掛掉
|
||||
print(eval(sys.argv[1], {"rec": rec, "m": m, "blocked": blocked, "buf": buf.getvalue()}))
|
||||
PY
|
||||
)
|
||||
if [ "$got" = "$want" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi
|
||||
printf 'want=%s got=%s %s\n' "$want" "$got" "$what"
|
||||
}
|
||||
|
||||
A_BASE=(--title "$TITLE" -F "$TMP/body.md" --to arcrun-rag)
|
||||
|
||||
b "★ 子票內文寫著它的頂層票是誰（下游看得到上游）" "True" \
|
||||
"any('Parent: inkstone/ISEP#92' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/arcrun-rag/issues')" \
|
||||
"${A_BASE[@]}"
|
||||
b "★ 有掛上 Gitea 原生相依（不是只寫在內文裡）" "True" \
|
||||
"any(mm=='POST' and p=='/repos/inkstone/ISEP/issues/92/dependencies' for mm,p,pl in rec)" \
|
||||
"${A_BASE[@]}"
|
||||
b "★ 頂層票的時間軸上有一則指向下游的留言（上游看得到下游）" "True" \
|
||||
"any('inkstone/arcrun-rag#900' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \
|
||||
"${A_BASE[@]}"
|
||||
b "★ 那則留言明講「不會因為轉出去就自動關」（第 2 條的預告）" "True" \
|
||||
"any('不會因為轉出去就自動關' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \
|
||||
"${A_BASE[@]}"
|
||||
b "沒給 --journey → 留言裡誠實寫「沒有貼」（不硬湊，也不假裝有）" "True" \
|
||||
"any('沒有貼' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \
|
||||
"${A_BASE[@]}"
|
||||
b "沒給 --journey → 不去動任何一端的標籤軸（只設子票的 s/*）" "1" \
|
||||
"len([1 for mm,p,pl in rec if mm=='PUT' and p.endswith('/labels')])" \
|
||||
"${A_BASE[@]}"
|
||||
b "★ 給了 --journey → 母子兩端都被貼（只貼一端就聚不起來）" "2" \
|
||||
"len([1 for mm,p,pl in rec if mm=='PUT' and p.endswith('/labels') and 4 in pl['labels']])" \
|
||||
"${A_BASE[@]}" --journey 收件匣
|
||||
b "★ 貼在頂層票上時保留它原本的標籤（不是整組蓋掉）" "True" \
|
||||
"any(mm=='PUT' and p=='/repos/inkstone/ISEP/issues/92/labels' and sorted(pl['labels'])==[3,4] for mm,p,pl in rec)" \
|
||||
"${A_BASE[@]}" --journey 收件匣
|
||||
b "labels.yaml 沒有的旅程名 → 擋下來（要求標籤在場，不是猜名字合不合法）" "True" \
|
||||
"blocked" "${A_BASE[@]}" --journey 沒這條旅程
|
||||
b "擋下來時直接指回 labels.yaml（不叫人自己猜怎麼修）" "True" \
|
||||
"'labels.yaml' in buf" "${A_BASE[@]}" --journey 沒這條旅程
|
||||
|
||||
echo
|
||||
echo "通過 $PASS 條，失敗 $FAIL 條"
|
||||
[ "$FAIL" = 0 ] || exit 1
|
||||
+295
-6
@@ -21,8 +21,10 @@ leo 2026-08-16 三句話，本工具就是它們的機械化：
|
||||
三個 Gitea 原生欄位（leo 2026-08-27「這些全部都要」，缺一個就會掉棒）：
|
||||
|
||||
ticket subtask <母票> --title <US> -F <檔> 討論串裡的一件事 → 看得見的子票＋相依
|
||||
ticket handoff <頂層票> --to <repo> … 同一個動作，換個名字：頂層 → 下游 repo
|
||||
ticket handback <票> --to <誰> --next <一句> 收工＝指派＋改 tag＋寫下一步，一個動作
|
||||
ticket mine [--user <誰>] 撈一次：棒子在誰手上、每根下一步是什麼
|
||||
ticket loose 撈一次：下游都關了、自己還開著的頂層票
|
||||
|
||||
票的寫法：`owner/repo#N`，例：`inkstone/InkStoneCo#44`
|
||||
"""
|
||||
@@ -452,10 +454,87 @@ def cmd_close(argv):
|
||||
|
||||
if deliv:
|
||||
api(f"/repos/{owner}/{repo}/issues/{num}/comments",
|
||||
{"body": f"{os.environ.get('ISEP_IDENTITY') or f'【身份】總管／{owner}/{repo}／-'}\n\n✅ 結案。交付物：{deliv}"})
|
||||
{"body": f"{_identity(owner, repo)}\n\n✅ 結案。交付物：{deliv}"})
|
||||
api(f"/repos/{owner}/{repo}/issues/{num}", {"state": "closed"}, method="PATCH")
|
||||
print(f"✅ {owner}/{repo}#{num} 已關（交付物：{deliv or ('PR' if has_pr else '票上回報')}）")
|
||||
|
||||
# ── 完工回寫（inkstone/ISEP#92 最痛的那一格）─────────────────────────
|
||||
# 關掉一張下游票之後，**同一個動作**回頭處理它的頂層票。
|
||||
# 不做這件事的後果票上寫得很清楚：「頂層票會永遠掛著，而 leo 是看頂層的」。
|
||||
_writeback(owner, repo, num, deliv or ("PR" if has_pr else "票上回報"))
|
||||
|
||||
|
||||
def _writeback(owner, repo, num, deliv):
|
||||
"""子票關掉 → 回頭處理每一張在等它的頂層票。
|
||||
|
||||
🔴 失敗要吵。回寫悄悄失敗 ＝ 這格等於沒做，而沒有人會發現
|
||||
（那正是本票在治的病）。所以任何一張處理失敗就非零離開。
|
||||
"""
|
||||
child = f"{owner}/{repo}#{num}"
|
||||
try:
|
||||
parents = _blocks(owner, repo, num)
|
||||
except SystemExit:
|
||||
print(f"\n⚠️ 撈不到 {child} 的頂層票（/blocks 讀失敗）——"
|
||||
f"回寫這一格**沒有做**，請手動確認或跑 `ticket loose`", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
if not parents:
|
||||
print("\n📌 這張票沒有任何頂層票在等它（沒有相依邊）⇒ 不需要回寫。")
|
||||
return
|
||||
|
||||
print(f"\n🔗 有 {len(parents)} 張頂層票在等這張票，逐一回寫：")
|
||||
failed = []
|
||||
for pt in parents:
|
||||
pfull = pt["repository"]["full_name"]
|
||||
po, pr = pfull.split("/")
|
||||
pn = pt["number"]
|
||||
try:
|
||||
pdeps = _deps(po, pr, pn)
|
||||
action, open_left = writeback_plan(pt.get("state"), pdeps)
|
||||
|
||||
if action == "skip":
|
||||
print(f" · {pfull}#{pn} 已經是 closed ⇒ 不動")
|
||||
continue
|
||||
|
||||
lines = [_identity(po, pr), "",
|
||||
f"⬇️ **下游完工回寫**：`{child}` 已關（交付物：{deliv}）"]
|
||||
if open_left:
|
||||
lines += ["", f"這張票還在等 {len(open_left)} 張下游（都關了才輪到它）："]
|
||||
lines += [f"- ◻ {i['repository']['full_name']}#{i['number']} {i['title'][:60]}"
|
||||
for i in open_left]
|
||||
lines += ["", "⇒ 本票維持原狀，不要當成可以收了。"]
|
||||
else:
|
||||
lines += ["", "**這是最後一張下游——本票的下游已經全部關閉。**", "",
|
||||
f"{BATON_MARK} → `{HANDBACK_TO}`", "",
|
||||
"**下一步**：驗一次頂層要的東西真的到齊了，到齊就 "
|
||||
f"`ticket close {pfull}#{pn} --deliverable <URL>`；"
|
||||
"沒到齊就開下一張下游票，不要把它留在原地。", "",
|
||||
"（本則由 `ticket close` 的完工回寫自動貼上，"
|
||||
"機制見 `inkstone/ISEP#92`）"]
|
||||
api(f"/repos/{po}/{pr}/issues/{pn}/comments", {"body": "\n".join(lines)})
|
||||
|
||||
if action == "handback":
|
||||
# 指派 ＋ 改 tag：**欄位**才撈得到，留言撈不到。
|
||||
# 08-26 那次掉棒就是話有說、欄位沒動，棒子躺在地上 14 小時。
|
||||
api(f"/repos/{po}/{pr}/issues/{pn}",
|
||||
{"assignees": [HANDBACK_TO]}, method="PATCH")
|
||||
cur = [l["name"] for l in (pt.get("labels") or [])]
|
||||
keep = [n for n in cur if not n.startswith("s/")] + ["s/review"]
|
||||
_set_labels(po, pr, pn, keep)
|
||||
print(f" · {pfull}#{pn} 下游全關 ⇒ 已指派 {HANDBACK_TO}＋s/review（等人驗）")
|
||||
else:
|
||||
print(f" · {pfull}#{pn} 還有 {len(open_left)} 張下游沒關 ⇒ 只記一筆")
|
||||
except SystemExit:
|
||||
failed.append(f"{pfull}#{pn}")
|
||||
except Exception as e:
|
||||
failed.append(f"{pfull}#{pn}（{e}）")
|
||||
|
||||
if failed:
|
||||
print(f"\n⚠️ 這幾張頂層票**沒有回寫成功**：{'、'.join(failed)}\n"
|
||||
f" 回寫失敗要吵——悄悄失敗等於這格沒做。手動補，或稍後跑 `ticket loose` 對帳。",
|
||||
file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
|
||||
# ── decide ───────────────────────────────────────────────────────────────
|
||||
@@ -526,6 +605,10 @@ def cmd_decide(argv):
|
||||
|
||||
BATON_MARK = "🏃 **棒子交回**"
|
||||
|
||||
# 棒子的預設終點：總管。**這是 Gitea 的 assignee 欄位，不是一句話**——
|
||||
# 撈「指派給你的」一頁就看得到，撈留言看不到。
|
||||
HANDBACK_TO = os.environ.get("ISEP_HANDBACK_TO") or "claude-code"
|
||||
|
||||
|
||||
def _labels_of(owner, repo):
|
||||
return {l["name"]: l["id"] for l in api(f"/repos/{owner}/{repo}/labels?limit=100")}
|
||||
@@ -545,6 +628,97 @@ def _deps(owner, repo, num):
|
||||
return api(f"/repos/{owner}/{repo}/issues/{num}/dependencies") or []
|
||||
|
||||
|
||||
def _blocks(owner, repo, num):
|
||||
"""反方向：**誰把這張票當相依**——也就是這張票的頂層票（可能不只一張、可能跨 repo）。
|
||||
|
||||
Gitea 原生兩個端點是同一條邊的兩端，方向不可混淆：
|
||||
/issues/<N>/dependencies 這張票在等誰 → 它的下游
|
||||
/issues/<N>/blocks 誰在等這張票 → 它的頂層
|
||||
`subtask` POST 的是**母票的 dependencies**，所以子票這端看到的是 `blocks`。
|
||||
"""
|
||||
return api(f"/repos/{owner}/{repo}/issues/{num}/blocks") or []
|
||||
|
||||
|
||||
def _identity(owner, repo):
|
||||
"""票上的每一則留言第一行要表明身份（規約見 docs/governance/dispatch-and-reply-format.md §3）。
|
||||
|
||||
機器自動貼的留言同樣要標——不標的話，回寫留言看起來像某個人寫的，
|
||||
而下一個讀票的人會去找那個人。
|
||||
"""
|
||||
return os.environ.get("ISEP_IDENTITY") or f"【身份】總管／{owner}/{repo}／-"
|
||||
|
||||
|
||||
# ══════════════════════════════════════════════════════════════════════════
|
||||
# inkstone/ISEP#92 — 「下游做完時頂層跟著關」的三格
|
||||
#
|
||||
# 票上的原話：「開在頂層的票，下游做完了卻沒人回來關⋯⋯頂層票會永遠掛著，
|
||||
# 而 leo 是看頂層的。」
|
||||
#
|
||||
# 缺的三格，各由下面一段承接：
|
||||
# ① 雙向連結的強制 → cmd_subtask 一個動作同時掛相依 ＋ 在母票留下指回來的留言
|
||||
# ② journey 標籤 → journey_label()（對不上就不貼，不硬湊）
|
||||
# ③ 完工回寫 → writeback_plan() ＋ cmd_close 關完子票立刻回頭處理母票
|
||||
# ④ 撈得出來 → is_loose() ＋ cmd_loose（③ 走側門漏掉的，這張網補回來）
|
||||
#
|
||||
# 🔴 這四格的判準**全部是機械事實**（相依邊在不在、state 是什麼），
|
||||
# 沒有一格在猜文字。leo 2026-08-17 已證偽關鍵字黑名單那條路
|
||||
# （8 次誤攔、0 次正確攔截）。
|
||||
# ══════════════════════════════════════════════════════════════════════════
|
||||
|
||||
JOURNEY_PREFIX = "j/"
|
||||
|
||||
|
||||
def journey_label(name):
|
||||
"""`--journey 收件匣` → `j/收件匣`。只加前綴，不做語意判斷。
|
||||
|
||||
標籤存不存在由 `_set_labels` 去問 Gitea（不存在就擋，並指回 labels.yaml）——
|
||||
**「要求某個東西在場」，不是「猜哪些名字合法」**。
|
||||
⇒ 新的一條旅程要先加進 labels.yaml 再 sync，這是刻意的：
|
||||
journey 是**跨票聚類的軸**，隨手造名字會讓同一條旅程長出三個拼法。
|
||||
"""
|
||||
n = (name or "").strip()
|
||||
if not n:
|
||||
die("🚫 --journey 後面要接旅程名（例：--journey 收件匣）。\n"
|
||||
" 對不上任何旅程就**不要加這個參數**——票上明講不硬湊。")
|
||||
return n if n.startswith(JOURNEY_PREFIX) else JOURNEY_PREFIX + n
|
||||
|
||||
|
||||
def is_loose(state, deps):
|
||||
"""這張票是不是「下游都關了、自己還開著」的頂層票。
|
||||
|
||||
純函式（不打網路）⇒ 判準本身測得動，不必開真的票來驗。
|
||||
|
||||
三個條件缺一不可：
|
||||
· 自己還 open 關掉的票不用管
|
||||
· 曾經有下游 沒有相依邊 ⇒ 它根本不是頂層票，不要拿它來吵
|
||||
· 沒有任何 open 下游 有一張還開著就還在跑，不是掉在地上
|
||||
"""
|
||||
if state != "open":
|
||||
return False
|
||||
if not deps:
|
||||
return False
|
||||
return not any(d.get("state") == "open" for d in deps)
|
||||
|
||||
|
||||
def writeback_plan(parent_state, parent_deps):
|
||||
"""下游關掉之後，它的頂層票該被怎麼處理。**只回計畫，不做副作用**⇒ 離線測得動。
|
||||
|
||||
回 (動作, 還開著的下游)：
|
||||
"skip" 頂層票自己已經關了 ⇒ 沒事
|
||||
"note" 還有別的下游沒關 ⇒ 只在頂層票記一筆，別假裝它可以收了
|
||||
"handback" 下游全關了 ⇒ 這張票現在**只等人驗**：
|
||||
指派回總管 ＋ s/review，讓它出現在「指派給你的」
|
||||
|
||||
🔴 為什麼不自動關母票：關票要有交付物、要有人看過（`ticket close` 的既有閘）。
|
||||
票上要的是「不能默默留著」，不是「自動消失」——
|
||||
默默關掉跟默默留著是同一個病的兩面。
|
||||
"""
|
||||
open_left = [d for d in (parent_deps or []) if d.get("state") == "open"]
|
||||
if parent_state != "open":
|
||||
return "skip", open_left
|
||||
return ("note" if open_left else "handback"), open_left
|
||||
|
||||
|
||||
# ── subtask ──────────────────────────────────────────────────────────────
|
||||
def cmd_subtask(argv):
|
||||
"""把「討論串裡的一件事」長成看得見的子票，並掛成母票的 Gitea 原生相依。
|
||||
@@ -565,7 +739,9 @@ def cmd_subtask(argv):
|
||||
if len(argv) < 1:
|
||||
die("用法：ticket subtask <母票 owner/repo#N> --title \"<User Story>\" -F <內文檔>\n"
|
||||
" [--repo <收件 repo，預設跟母票同一個>] [--label <s/xxx，預設 s/todo>]\n"
|
||||
" [--assign <誰做> --next \"<他第一件事要做什麼>\"] ← 指派了就一定要寫下一步")
|
||||
" [--journey <旅程名>] ← 這件事服務哪條使用者旅程（對不上就不要加）\n"
|
||||
" [--assign <誰做> --next \"<他第一件事要做什麼>\"] ← 指派了就一定要寫下一步\n"
|
||||
"\n（`ticket handoff` 是同一個動作的別名：頂層票 → 下游 repo）")
|
||||
powner, prepo, pnum = parse_ref(argv[0])
|
||||
|
||||
def opt(name, default=None):
|
||||
@@ -585,10 +761,13 @@ def cmd_subtask(argv):
|
||||
" leo 2026-08-27：『每個事情沒有歷史記錄才是大問題』，\n"
|
||||
" 而沒寫驗收條件的票，關掉之後就沒有歷史，只剩一個關字）")
|
||||
|
||||
repo = opt("--repo", prepo)
|
||||
# `--to <repo>` 是 `ticket handoff` 那個名字底下比較自然的講法，同一個東西。
|
||||
# （handback 的 `--to` 是「交給誰」，subtask 沒有那個參數，不會撞。）
|
||||
repo = opt("--repo", opt("--to", prepo))
|
||||
label = opt("--label", "s/todo")
|
||||
assign = opt("--assign")
|
||||
nxt = opt("--next")
|
||||
jlabel = journey_label(opt("--journey")) if "--journey" in argv else None
|
||||
if assign and not nxt:
|
||||
die("🚫 指派了人卻沒寫 --next。\n"
|
||||
" **有人被指到這張票，他撈到它的第一件事就是問「所以我要做什麼」**——\n"
|
||||
@@ -597,7 +776,8 @@ def cmd_subtask(argv):
|
||||
|
||||
body = (f"Parent: {powner}/{prepo}#{pnum}\n"
|
||||
f"> 這張票是從母票的討論串裡長出來的一件事。\n"
|
||||
f"> **它沒關，母票關不掉**（Gitea 原生相依，實測 412 硬擋）。\n\n") + body
|
||||
f"> **它沒關，母票關不掉**（Gitea 原生相依，實測 412 硬擋）。\n"
|
||||
f"> **它關掉時，母票會收到一則回寫**（`ticket close` 自動做，見 `inkstone/ISEP#92`）。\n\n") + body
|
||||
|
||||
d = api(f"/repos/{ORG}/{repo}/issues", {"title": title, "body": body})
|
||||
cnum = d["number"]
|
||||
@@ -619,6 +799,38 @@ def cmd_subtask(argv):
|
||||
deps = _deps(powner, prepo, pnum)
|
||||
openn = [i for i in deps if i["state"] == "open"]
|
||||
print(f" 相依：已掛上 {powner}/{prepo}#{pnum}（它存在、且擋著母票）")
|
||||
|
||||
# 🔴 雙向連結：相依邊只長在 Gitea 的側欄，**母票的時間軸上什麼都沒有**。
|
||||
# 票上的原話：「頂層票寫了『轉去某個 repo』，但那邊的票沒有指回來，
|
||||
# 從下游那張票看不出它從哪來，脈絡就斷了。」
|
||||
# ⇒ 兩端各留一個看得見的指標：子票內文的 `Parent:`（上面），母票時間軸的這一則。
|
||||
# 跨 repo 時尤其重要——側欄的相依很容易被當成同 repo 的東西。
|
||||
plines = [_identity(powner, prepo), "",
|
||||
f"➡️ **已轉往下游**：`{ORG}/{repo}#{cnum}` {title}", "",
|
||||
f"{d['html_url']}", "",
|
||||
f"- 收件 repo：`{ORG}/{repo}` tag：`{label}`"
|
||||
+ (f" 旅程：`{jlabel}`" if jlabel else "")
|
||||
+ (f" 指派：`{assign}`" if assign else " （還沒指派，留在票池等人領）")]
|
||||
if jlabel is None:
|
||||
plines += ["- 旅程：**沒有貼**（開票時判定對不上任何一條，不硬湊）"]
|
||||
plines += ["",
|
||||
"**這張頂層票不會因為轉出去就自動關**——下游那張關掉時，"
|
||||
"`ticket close` 會回頭在這裡貼一則回寫；"
|
||||
"全部下游關完，這張票會被指派回總管等驗。（機制：`inkstone/ISEP#92`）"]
|
||||
api(f"/repos/{powner}/{prepo}/issues/{pnum}/comments", {"body": "\n".join(plines)})
|
||||
print(f" 回指：已在母票 {powner}/{prepo}#{pnum} 的時間軸貼上指向子票的留言")
|
||||
|
||||
# journey 標籤：兩端都貼，聚類才聚得起來（只貼一端＝撈不到另一端）
|
||||
if jlabel:
|
||||
_set_labels(ORG, repo, cnum, [label, jlabel])
|
||||
pcur = [l["name"] for l in (api(f"/repos/{powner}/{prepo}/issues/{pnum}")
|
||||
.get("labels") or [])]
|
||||
if jlabel not in pcur:
|
||||
_set_labels(powner, prepo, pnum, pcur + [jlabel])
|
||||
print(f" 旅程：`{jlabel}`（母子兩端都貼——只貼一端就聚不起來）")
|
||||
else:
|
||||
print(" 旅程：沒有貼（沒給 --journey）。對得上就補一次："
|
||||
f"`ticket subtask … --journey <旅程名>`；對不上就不要硬湊。")
|
||||
print(f"\n📌 母票 {powner}/{prepo}#{pnum} 目前有 {len(openn)} 張未關的相依：")
|
||||
for i in deps:
|
||||
mark = "◻" if i["state"] == "open" else "☑"
|
||||
@@ -747,9 +959,86 @@ def _last_next(owner, repo, num):
|
||||
return None
|
||||
|
||||
|
||||
# ── loose ────────────────────────────────────────────────────────────────
|
||||
def cmd_loose(argv):
|
||||
"""撈一次：**下游都關了、自己還開著**的頂層票。
|
||||
|
||||
票上的驗收條件第 3、4 條（`inkstone/ISEP#92`）：
|
||||
「撈一次『已經沒有 open 下游票、但自己還開著的頂層票』→ 要撈得出來（現在撈不出來）」
|
||||
「拿現有的頂層票跑一次 → 要能指出哪幾張是這種情況」
|
||||
|
||||
這是 `ticket close` 自動回寫的**補網**：回寫只在走正門（`ticket close`）時發生，
|
||||
而關票的側門（直接 PATCH `state=closed`）是刻意放行的
|
||||
（見 `hooks/ticket-api-bypass-guard.sh`：「帶了 ID 的子路徑」一律放行）。
|
||||
⇒ 側門漏掉的，由這張網撈回來。**不是輪詢**——掛在開場／收工對帳跑一次。
|
||||
"""
|
||||
def opt(name, default=None):
|
||||
return argv[argv.index(name) + 1] if name in argv else default
|
||||
|
||||
org = opt("--org", ORG)
|
||||
only = opt("--repo")
|
||||
|
||||
print(f"🔎 掃 `{org}` 的 open 票，找「下游都關了、自己還開著」的頂層票"
|
||||
+ (f"（只看 {only}）" if only else "") + " …")
|
||||
|
||||
items, page = [], 1
|
||||
while page <= 12:
|
||||
q = urllib.parse.urlencode({"state": "open", "type": "issues",
|
||||
"limit": 50, "page": page, "owner": org})
|
||||
got = api(f"/repos/issues/search?{q}") or []
|
||||
if not got:
|
||||
break
|
||||
items += got
|
||||
page += 1
|
||||
if only:
|
||||
items = [i for i in items if i["repository"]["full_name"].split("/")[-1] == only]
|
||||
print(f" open 票 {len(items)} 張，逐張問它的下游 …")
|
||||
|
||||
def probe(it):
|
||||
full = it["repository"]["full_name"]
|
||||
o, r = full.split("/")
|
||||
try:
|
||||
deps = _deps(o, r, it["number"])
|
||||
except SystemExit:
|
||||
return None # 讀不到 ≠ 沒有下游；寧可漏報也不要編一筆出來
|
||||
except Exception:
|
||||
return None
|
||||
return (full, it, deps)
|
||||
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
with ThreadPoolExecutor(max_workers=12) as ex:
|
||||
probed = [x for x in ex.map(probe, items) if x]
|
||||
|
||||
parents = [x for x in probed if x[2]]
|
||||
loose = [x for x in parents if is_loose("open", x[2])]
|
||||
|
||||
print(f"\n 有下游相依的頂層票：{len(parents)} 張")
|
||||
print(f" 其中「下游都關了、自己還開著」：**{len(loose)} 張**\n")
|
||||
|
||||
if not loose:
|
||||
print("✅ 一張都沒有——每張頂層票都還有下游在跑，或已經跟著關了。")
|
||||
for full, it, deps in loose:
|
||||
n = it["number"]
|
||||
st = [l["name"] for l in it.get("labels") or []]
|
||||
who = [a["login"] for a in (it.get("assignees") or [])] or ["（沒有人）"]
|
||||
print(f" ● {full}#{n} {st} 指派：{'、'.join(who)}")
|
||||
print(f" {it['title'][:64]}")
|
||||
for d in deps:
|
||||
print(f" ☑ {d['repository']['full_name']}#{d['number']}"
|
||||
f" {d['title'][:52]}")
|
||||
print(f" → 驗過就關：ticket close {full}#{n} --deliverable <URL>")
|
||||
print(f" 還缺東西：ticket subtask {full}#{n} --title \"<US>\" -F <檔>")
|
||||
print()
|
||||
|
||||
print("📌 這張表撈的是**機械事實**（相依邊的 state），不是猜文字。")
|
||||
print(" 走 `ticket close` 關下游時會自動回寫、這張表就不會長；")
|
||||
print(" 會長出來的都是走側門關掉的那些。")
|
||||
return loose
|
||||
|
||||
|
||||
CMDS = {"where": cmd_where, "say": cmd_say, "new": cmd_new, "close": cmd_close,
|
||||
"decide": cmd_decide, "subtask": cmd_subtask, "handback": cmd_handback,
|
||||
"mine": cmd_mine}
|
||||
"decide": cmd_decide, "subtask": cmd_subtask, "handoff": cmd_subtask,
|
||||
"handback": cmd_handback, "mine": cmd_mine, "loose": cmd_loose}
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2 or sys.argv[1] not in CMDS:
|
||||
|
||||
Reference in New Issue
Block a user