@adamchanadam/agent-handoff-kit 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,303 +1,246 @@
1
- # Agent Handoff Kit
2
-
3
- 狀態:`v0.3.0` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
4
-
5
- ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
-
7
- Agent Handoff Kit 是 **AI Session 之間的接力棒**。
8
-
9
- 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
-
11
- > 🚀 **第一次用?你不需要先讀本 README 或任何文檔。**
12
- >
13
- > 安裝完成後,在 AI 對話中講一句:
14
- >
15
- > ```
16
- > Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
17
- > ```
18
- >
19
- > AI 會自動引導你選擇情景(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
20
-
21
- 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想睇實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情景(整理電腦下載目錄、開咖啡店市場調查)嘅七步流程完整示範。README 則保留安裝、日常使用與限制。
22
-
23
- ## 它解決甚麼問題
24
-
25
- 用 AI 做長期項目,常見四個問題:
26
-
27
- | 問題 | Agent Handoff Kit 怎樣處理 |
28
- |---|---|
29
- | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
30
- | 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
31
- | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
32
- | AI 可能亂改、亂刪或誤發佈 | 內置 safety 工作模式;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
33
-
34
- 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
35
-
36
- ## 三步上手
37
-
38
- ### 一、安裝
39
-
40
- 在你的專案資料夾打開 Terminal,執行:
41
-
42
- ```bash
43
- npx @adamchanadam/agent-handoff-kit init
44
- ```
45
-
46
- 出現確認問題時,輸入 `yes`。
47
-
48
- 安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
49
-
50
- ### 二、開工
51
-
52
- 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
53
-
54
- **第一次用(新手引導 trigger)**:
55
-
56
- ```text
57
- Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
58
- ```
59
-
60
- AI 會自動載入 onboarding pack,引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。
61
-
62
- **之後 session(你已熟悉 v2 之後)可用更直接 prompt**:
63
-
64
- ```text
65
- Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
66
- ```
67
-
68
- 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
69
-
70
- ### 三、收工
71
-
72
- 工作完成想結束時,只需輸入:
73
-
74
- ```text
75
- 收工
76
- ```
77
-
78
- 也可以輸入:
79
-
80
- ```text
81
- wrap up
82
- handoff
83
- ```
84
-
85
- AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
86
-
87
- ```text
88
- START_NEXT_SESSION_PROMPT.txt
89
- ```
90
-
91
- 這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
92
-
93
- ## 檢查是否安裝完整
94
-
95
- 如要檢查安裝是否完整,可在 Terminal 執行:
96
-
97
- ```bash
98
- npx @adamchanadam/agent-handoff-kit doctor
99
- ```
100
-
101
- 看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
102
-
103
- 這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
104
-
105
- ## 會安裝甚麼
106
-
107
- 安裝工具會在你的專案中建立:
108
-
109
- ```text
110
- AGENTS.md
111
- CLAUDE.md
112
- GEMINI.md
113
- START_NEXT_SESSION_PROMPT.txt
114
- dev/SESSION_HANDOFF.md
115
- dev/SESSION_LOG.md
116
- dev/PROJECT_INDEX.md
117
- dev/PROJECT_DECISIONS.md
118
- dev/DOC_SYNC_REGISTRY.md
119
- dev/RULE_PACKS.md
120
- dev/rules/*.md
121
- ```
122
-
123
- | 文件 | 用途 |
124
- |---|---|
125
- | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
126
- | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
127
- | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
128
- | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
129
- | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
130
- | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。主檔長期保持短小;N=11+ 嘅舊條目自動 archive 至 `dev/SESSION_LOG_archive/`,trace-back 用。接力靠 `SESSION_HANDOFF.md`,本檔屬冷資料層。 |
131
- | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
132
- | `dev/PROJECT_DECISIONS.md` | 保存項目嘅長期演進、決策、架構取捨、學習觀察。屬 warm 資料層 —— AI 開工**不需要讀**本檔;遇到「之前點解咁做」嘅問題時 AI 自己嚟搵。短期單一 task 項目本檔保持近空;長期項目 AI 喺收工時自動 maintain。 |
133
- | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
134
- | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
135
- | `dev/rules/*.md` | 按任務載入的細分工作規則。含 10 個 pack:safety / coding / writing / research / agent-governance / release / knowledge / communication / onboarding(v0.2.0 新加,新手第一次用時 AI 主動載入做 walk-through)/ **integrations**(v0.3.0 新加,外部工具治理 — Connectors / MCPs / Plugins / Skills 跨 session resilience + 機密分離原則)。 |
136
-
137
- 你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
138
-
139
- ## SESSION_LOG 嘅自動整理機制
140
-
141
- 長期使用後,`dev/SESSION_LOG.md` 唔會無止境膨脹。每次你講「收工」,AI 會自動執行 N 規則整理(N 代表 session 嘅 entry 數,N=1 為最新):
142
-
143
- - **N=1–3**:最新三條 session 條目保留完整內容(safety buffer,萬一交接出錯仍有 fallback)。
144
- - **N=4–10**:核心內容已被 `dev/SESSION_HANDOFF.md` 等真源吸收嘅條目,自動降為短索引(日期 + 標題 + 真源 anchor)。
145
- - **N=11+**:自動 archive 入 `dev/SESSION_LOG_archive/archive_<批次>_<日期區間>.md`;主檔末尾留一份 archive index 做 trace-back 入口。
146
-
147
- 接力責任由 `dev/SESSION_HANDOFF.md` 對賬式更新承擔;`dev/SESSION_LOG.md` 屬 trace-back / 審計用嘅冷資料層。**新 AI session 開工唔需要讀完整 LOG**,只需要讀 `AGENTS.md` + `dev/SESSION_HANDOFF.md` + 索引文件就足夠接力。
148
-
149
- 所以你部電腦嘅 `dev/` 資料夾唔會被 session log 不停撐大,亦唔需要你手動清理。如果主檔意外膨脹(11 條以上未 archive,或單檔超過 1500 行),`doctor` 會喺輸出顯示一個 warning 提醒 AI 下次收工執行整理;但呢個只屬提醒,唔會令 `doctor` 失敗、亦唔阻擋安裝。
150
-
151
- ## 項目決策日誌
152
-
153
- `dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察 narrative。屬 warm 資料層 —— AI 開工**不需要讀**本檔;當你問「之前為何這樣做」時,AI 自己會從這裡找答案。
154
-
155
- - 短期 single-task 項目:本檔保持近空,你不需要 maintain
156
- - 長期持續演進項目:AI 會在每次收工時自動 maintain
157
- - HANDOFF 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 條時,AI 自動 split 舊條目至此
158
- - 觀察到任務需求演進、架構取捨、累積學習 pattern 時,AI 主動 append entry
159
-
160
- 本檔含 4 個固定 H2 section:
161
-
162
- - **Evolution Timeline** —— 任務需求嘅長期演進
163
- - **Decisions Archive** —— 累積決策嘅冷封存
164
- - **Architecture Choices** —— 主要架構取捨同 rationale
165
- - **Insights & Learnings** —— 多 session 累積嘅學習觀察
166
-
167
- 本檔同 SESSION_LOG 嘅 archive 機制屬同一套 hot / warm / cold 分層紀律 —— 你部電腦嘅 `dev/` 資料夾長期使用都唔會被無關 narrative 撐大,亦唔需要你手動清理。新手用戶完全唔需要打開本檔,亦唔需要記任何 schema —— 一切由 AI 自律執行。
168
-
169
- ## 外部工具治理
170
-
171
- 當你項目涉及外部工具(Notion、Google Drive、Dropbox、Slack、Linear、GitHub、HubSpot 等),Kit 提供完整跨 session 治理紀律 —— 但 **不教你點 install**(安裝行為由 Anthropic 官方文檔 + 各工具自身 setup guide 負責,屬中階用戶責任)。Kit 專注「**已裝好之後,點樣治理跨 session 穩定可用**」。
172
-
173
- ### Installed Integrations 登記表
174
-
175
- `dev/PROJECT_INDEX.md` 內 `## Installed Integrations` section 係項目嘅外部工具能力 registry,4 個 subsection:
176
-
177
- - **Connectors**(Anthropic 官方 vetted)—— 譬如 Notion / Drive / Slack 經 Claude Desktop Settings → Extensions 一鍵安裝
178
- - **MCPs**(community / custom)—— 用戶自建或第三方 MCP server
179
- - **Plugins**(Claude Code plugin bundle)—— 經 `/plugin` command 安裝嘅 bundle
180
- - **Skills**(SKILL.md instruction set)—— 由 plugin 攜帶或直接安裝
181
-
182
- 加 `### Source-of-truth Architecture` sub-table 描述多層持久化分工 —— 譬如「Notion DB Index 記真源 metadata、本機 `reference/` 儲真源檔、Drive folder 做持久化參考檔 mirror、本機 `output/` 做 AI working draft」。
183
-
184
- ### 機密分離原則
185
-
186
- **API key / OAuth token / 任何 credential value 永不寫入 `dev/*` 任何檔**。Credential 由 AI 工具自身 secure storage(OS Keychain / Credential Manager / AI tool config)管理,與 Kit 完全分離。Kit 嘅 doctor 對 `dev/PROJECT_INDEX.md` + `dev/SESSION_HANDOFF.md` + `dev/SESSION_LOG.md` 強制 grep 14 種 credential prefix patterns,命中即 `status: failed`。
187
-
188
- ### Connector-first default
189
-
190
- 新手第一次貼起步句進入 onboarding 後,AI 主動引問:「你已裝邊啲 Connector / MCP / Plugin / Skill 我可以用?」用戶 declare 後 AI 寫入 Installed Integrations registry,之後每次新 session 開工自動 verify availability + 跨 session leverage。當 declared Connector functional,AI 用直接 MCP tool call(譬如 `mcp__notion__*` 讀寫 Notion DB);unavailable 才 fallback paste packet。
191
-
192
- ### 跨 session 治理 lifecycle 6 階段
193
-
194
- 1. **First-contact declaration**(onboarding 階段,AI 主動引問)
195
- 2. **Initial recording**(寫入 PROJECT_INDEX `## Installed Integrations`)
196
- 3. **Cross-session handoff**(SESSION_HANDOFF `## Durable Anchors` 強制要求新 AI 讀本 section)
197
- 4. **Startup availability probe**(新 AI 開工自動 verify 每個 declared Integration)
198
- 5. **Mid-session drift handling**(auth 失靈即 surface,唔自動 fix,紀錄入 PROJECT_INDEX + SESSION_LOG)
199
- 6. **Multi-tool 環境 cross-tool 一致性**(PROJECT_INDEX declaration 屬 project-level,唔 lock 一個 AI tool)
200
-
201
- 詳細紀律見 `dev/rules/integrations.md`(新 session 涉外部工具時 AI 自動 load)。
202
-
203
- ## 工作模式
204
-
205
- 你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
206
-
207
- | 你的任務 | AI 應使用的工作規則 |
208
- |---|---|
209
- | 寫或改代碼、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
210
- | 查資料、比較來源、整理證據 | `research` |
211
- | 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
212
- | 整理 Notion、Google Drive 或知識庫 | `knowledge` |
213
- | 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
214
- | 改規則、改流程、整理交接 | `agent-governance`;先找既有真源,不盲目新增規則 |
215
-
216
- 原則是只讀當前任務需要的規則,不是每次讀全部文件。
217
-
218
- ## 安全護欄
219
-
220
- 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
221
-
222
- - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
223
- - 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
224
- - 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
225
- - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
226
- - 發佈需明確批准:tag、GitHub Release、npm publish、部署或上傳都不能因「準備好了」而自動執行。
227
-
228
- ## 已安裝舊版,或已有 AI 記憶文件?
229
-
230
- 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,先用最新版 CLI dry-run 預演會發生甚麼:
231
-
232
- ```bash
233
- npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
234
- ```
235
-
236
- 確認沒有問題後,再執行:
237
-
238
- ```bash
239
- npx @adamchanadam/agent-handoff-kit@latest upgrade
240
- ```
241
-
242
- `@latest` 代表使用 npm 上最新的 Agent Handoff Kit CLI。`upgrade` 則負責把專案內已安裝的 Kit 文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會報 conflict,不會靜默覆寫。
243
-
244
- 看到 `conflict` 不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把 dry-run 輸出貼給 AI,請它幫你判斷要保留、合併,還是手動修改。
245
-
246
- ## 版本提示
247
-
248
- CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
249
-
250
- 若你不想檢查更新,可設定:
251
-
252
- ```bash
253
- AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
254
- ```
255
-
256
- ## 語言使用
257
-
258
- 安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
259
-
260
- 你的交接筆記、任務說明和文件內容可以使用中文或其他語言。需要機器檢查的結構,會由模板內的 `ack:section:*` 與 `ack:field:*` 標記承擔。
261
-
262
- ## 原始碼倉庫驗收
263
-
264
- 以下指令供維護者檢查原始碼倉庫,不是一般用戶日常必須執行的步驟:
265
-
266
- ```bash
267
- npm run qa:prototype
268
- npm run qa:packs
269
- npm run qa:upgrade
270
- npm run qa:release
271
- ```
272
-
273
- 這些檢查涵蓋安裝、`doctor`、套件預演、過時字串、公開輸出污染標記、工作規則路由、升級安全,以及從安裝到收工再到下一次開工的流程模擬。
274
-
275
- ## 套件邊界
276
-
277
- npm package 只包含安裝所需內容:
278
-
279
- - `bin/`
280
- - `runtime-core/`
281
- - `packs/`
282
- - `README.md`
283
- - `LICENSE`
284
- - `package.json`
285
-
286
- GitHub Pages 上的兩個 onboarding 頁 —— [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)(60 秒入門)與 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)(實操指南)—— 由原始碼倉庫根目錄發佈;兩個 HTML 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
287
-
288
- ## 配合 Adam-AI-Instructions 使用
289
-
290
- Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions)(Meta Instruction for AI)配合使用效果最好。兩者分工互補,不重疊:
291
-
292
- - **Adam-AI-Instructions** 負責 AI 喺**單一對話**內嘅做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該點答你」嘅持久基準。
293
- - **Agent Handoff Kit** 負責 AI 喺**對話之間**嘅接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 對話之間點記憶你個項目」嘅持久基準。
294
-
295
- 到該 repo 嘅「**五、Prompt 索引**」揀啱你 AI 工具嘅 prompt(Claude Cowork / Claude Code / OpenAI Codex / ChatGPT 等),複製對應子目錄嘅 `prompt.md` 全文,貼入 AI 工具嘅 system prompt、personal preferences 或 project instructions(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再喺項目資料夾跑 `npx @adamchanadam/agent-handoff-kit init` 安裝呢套 Kit。兩者配合就能涵蓋「單次對話質素」+「跨對話接力」兩個維度。
296
-
297
- ## 目前限制
298
-
299
- - `v0.3.0` 是 GitHub 與 npm 同步發佈版本。
300
- - 這是早期可用版本,尚未宣稱完整穩定。
301
- - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
302
- - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
303
- - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
1
+ # Agent Handoff Kit
2
+
3
+ 狀態:`v0.3.2` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
4
+
5
+ ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
+
7
+ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
8
+
9
+ 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
+
11
+ > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
+ >
13
+ > 安裝完成後,在 AI 對話中講一句:
14
+ >
15
+ > ```
16
+ > Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
17
+ > ```
18
+ >
19
+ > AI 會自動引導你選擇使用情境(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
20
+
21
+ 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情境(整理電腦下載目錄、開咖啡店市場調查)的完整流程示範。本 README 則保留安裝、日常使用與限制。
22
+
23
+ ## 它解決甚麼問題
24
+
25
+ 用 AI 做長期項目,常見四個問題:
26
+
27
+ | 問題 | Agent Handoff Kit 怎樣處理 |
28
+ |---|---|
29
+ | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
30
+ | 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
31
+ | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
32
+ | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
33
+
34
+ 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
35
+
36
+ ## 三步上手
37
+
38
+ ### 一、安裝
39
+
40
+ 在你的專案資料夾打開 Terminal,執行:
41
+
42
+ ```bash
43
+ npx @adamchanadam/agent-handoff-kit init
44
+ ```
45
+
46
+ 出現確認問題時,輸入 `yes`。
47
+
48
+ 安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
49
+
50
+ ### 二、開工
51
+
52
+ 打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
53
+
54
+ **第一次用(新手引導句)**:
55
+
56
+ ```text
57
+ Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
58
+ ```
59
+
60
+ AI 會自動載入新手引導,帶你選擇使用情境(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。
61
+
62
+ **之後熟悉 Handoff Kit 後,可改用更直接的開工句**:
63
+
64
+ ```text
65
+ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
66
+ ```
67
+
68
+ 然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
69
+
70
+ ### 三、收工
71
+
72
+ 工作完成想結束時,只需輸入:
73
+
74
+ ```text
75
+ 收工
76
+ ```
77
+
78
+ 也可以輸入:
79
+
80
+ ```text
81
+ wrap up
82
+ handoff
83
+ ```
84
+
85
+ AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字明確標示出來,方便完整複製。安裝後也會有一個更直覺的副本檔:
86
+
87
+ ```text
88
+ START_NEXT_SESSION_PROMPT.txt
89
+ ```
90
+
91
+ 這個檔案只是方便你複製下次開工提示;真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
92
+
93
+ ## 檢查是否安裝完整
94
+
95
+ 如要檢查安裝是否完整,可在 Terminal 執行:
96
+
97
+ ```bash
98
+ npx @adamchanadam/agent-handoff-kit doctor
99
+ ```
100
+
101
+ 看到 `status: passed`,代表必要文件、基本結構與下次開工提示副本的一致性都通過檢查。
102
+
103
+ 這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
104
+
105
+ ## 會安裝甚麼
106
+
107
+ 安裝工具會在你的專案中建立:
108
+
109
+ ```text
110
+ AGENTS.md
111
+ CLAUDE.md
112
+ GEMINI.md
113
+ START_NEXT_SESSION_PROMPT.txt
114
+ dev/SESSION_HANDOFF.md
115
+ dev/SESSION_LOG.md
116
+ dev/PROJECT_INDEX.md
117
+ dev/PROJECT_DECISIONS.md
118
+ dev/DOC_SYNC_REGISTRY.md
119
+ dev/RULE_PACKS.md
120
+ dev/rules/*.md
121
+ ```
122
+
123
+ | 文件 | 用途 |
124
+ |---|---|
125
+ | `AGENTS.md` | AI 開工時最先讀的入口文件。 |
126
+ | `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
127
+ | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
128
+ | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由交接文件自動產生。 |
129
+ | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
130
+ | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。長期使用後舊條目會自動整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
131
+ | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
132
+ | `dev/PROJECT_DECISIONS.md` | 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時自動維護,日常開工不需要讀。當你問「之前為何這樣做」時,AI 會自己從這裡找答案。 |
133
+ | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
134
+ | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
135
+ | `dev/rules/*.md` | 按任務載入的工作規則,共十份:安全、寫代碼、寫作、研究、AI 治理、發佈、知識整理、溝通、新手引導、外部工具治理。 |
136
+
137
+ 你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
138
+
139
+ ## SESSION_LOG 的自動整理機制
140
+
141
+ 長期使用後,`dev/SESSION_LOG.md` 不會無止境膨脹。每次你講「收工」,AI 會自動整理:
142
+
143
+ - 最新三條對話紀錄保留完整內容,作為意外時的後備。
144
+ - 之後的條目,如核心內容已被交接文件吸收,會自動縮成一行短索引(日期 + 標題 + 對應資料來源)。
145
+ - 累積到第十一條開始,會自動封存到 `dev/SESSION_LOG_archive/` 資料夾;主檔末尾留一份封存索引,方便日後追溯。
146
+
147
+ 接力責任由 `dev/SESSION_HANDOFF.md` 承擔;`dev/SESSION_LOG.md` 屬審計與追溯用的舊資料。**新對話開工不需要讀完整紀錄**,只需要讀 `AGENTS.md` 加 `dev/SESSION_HANDOFF.md` 加索引文件就足夠接力。
148
+
149
+ 所以你的電腦中的 `dev/` 資料夾不會被對話紀錄不停撐大,也不需要你手動清理。如主檔意外膨脹,`doctor` 會在輸出顯示提醒,請 AI 下次收工時整理;這只是提醒,不會令 `doctor` 失敗,也不阻擋安裝。
150
+
151
+ ## 項目決策日誌
152
+
153
+ `dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時自動維護,日常開工不需要讀本檔;當你問「之前為何這樣做」時,AI 會自己從這裡找答案。
154
+
155
+ 短期單一任務的項目,本檔幾乎保持空白,你不需要維護。長期持續演進的項目,AI 會自動累積以下四類紀錄:
156
+
157
+ - **長期演進** —— 任務需求隨時間的變化
158
+ - **決策封存** —— 累積決策的歷史紀錄
159
+ - **架構取捨** —— 主要設計選擇與原因
160
+ - **學習觀察** —— 多次對話累積的觀察與心得
161
+
162
+ 當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
163
+
164
+ 新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
165
+
166
+ ## 外部工具治理
167
+
168
+ 如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
169
+
170
+ **登記表**:`dev/PROJECT_INDEX.md` 內設有「已裝外部工具」段,記錄項目已連接哪些外部工具。AI 在新對話開工時會自動讀取,了解能直接讀寫哪些資料來源。
171
+
172
+ **機密分離原則**:API key、token、密碼等任何敏感資料**永不寫入** `dev/` 內任何檔案。這類機密由你的 AI 工具本身的安全儲存(系統 Keychain、Credential Manager 等)管理,與本工具完全分離。`doctor` 會自動掃描,若發現任何疑似敏感資料寫入,會立即報錯。
173
+
174
+ **已裝才用**:如你已透過 Claude Desktop 等工具連接好外部服務,AI 會直接使用對應功能讀寫資料。如未連接,AI 會改為產生需要你手動同步的內容,並提示你下一步。
175
+
176
+ **失靈不亂修**:如外部工具中途認證失效,AI 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
177
+
178
+ ## 工作模式
179
+
180
+ 你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
181
+
182
+ | 你的任務 | AI 應使用的工作規則 |
183
+ |---|---|
184
+ | 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
185
+ | 查資料、比較來源、整理證據 | 研究規則 |
186
+ | 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
187
+ | 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
188
+ | 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
189
+ | 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
190
+
191
+ 原則是只讀當前任務需要的規則,不是每次讀全部文件。
192
+
193
+ ## 安全護欄
194
+
195
+ 就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
196
+
197
+ - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
198
+ - 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
199
+ - 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
200
+ - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
201
+ - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
202
+
203
+ ## 已安裝舊版,或已有 AI 記憶文件?
204
+
205
+ 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,可先用最新版安裝工具預演會發生甚麼:
206
+
207
+ ```bash
208
+ npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
209
+ ```
210
+
211
+ 確認沒有問題後,再執行:
212
+
213
+ ```bash
214
+ npx @adamchanadam/agent-handoff-kit@latest upgrade
215
+ ```
216
+
217
+ `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 則負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
218
+
219
+ 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
220
+
221
+ ## 版本提示
222
+
223
+ 安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
224
+
225
+ 若你不想檢查更新,可設定環境變數:
226
+
227
+ ```bash
228
+ AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
229
+ ```
230
+
231
+ ## 配合 Adam-AI-Instructions 使用
232
+
233
+ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用效果最好。兩者分工互補,不重疊:
234
+
235
+ - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
236
+ - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
237
+
238
+ 到該 repo 的「五、Prompt 索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具的設定區(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再在項目資料夾執行 `npx @adamchanadam/agent-handoff-kit init` 安裝本工具。兩者配合就能涵蓋「單次對話質素」加「跨對話接力」兩個維度。
239
+
240
+ ## 目前限制
241
+
242
+ - `v0.3.0` 是 GitHub 與 npm 同步發佈版本。
243
+ - 這是早期可用版本,仍在持續完善中。
244
+ - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
245
+ - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
246
+ - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -2,7 +2,7 @@
2
2
 
3
3
  import { createInterface } from "node:readline/promises";
4
4
  import { stdin as input, stdout as output } from "node:process";
5
- import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
5
+ import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
6
6
  import path from "node:path";
7
7
  import { fileURLToPath } from "node:url";
8
8
 
@@ -437,6 +437,36 @@ function parseArgs(args) {
437
437
  async function runInstall(command, root, options, version) {
438
438
  const mode = await detectMode(root);
439
439
  const plan = await buildPlan(root, command);
440
+
441
+ // R-031 v0.3.1+: plan-time upgrade no-op detection. When upgrade has zero
442
+ // create/merge/conflict actions (skip-only), skip the full plan listing +
443
+ // confirmWrite + ceremony. The plan listing in this scenario is pure noise —
444
+ // user is already at latest and just verifying status.
445
+ const planCreateCount = plan.filter((item) => item.action === "create").length;
446
+ const planMergeCount = plan.filter((item) => item.action === "merge").length;
447
+ const planConflictCount = plan.filter((item) => item.action === "conflict").length;
448
+ const planSkipCount = plan.filter((item) => item.action === "skip").length;
449
+ const isUpgradeNoopAtPlanTime = command === "upgrade"
450
+ && planCreateCount === 0
451
+ && planMergeCount === 0
452
+ && planConflictCount === 0;
453
+
454
+ if (isUpgradeNoopAtPlanTime) {
455
+ printCard(version, "continuity ready", "o.o");
456
+ console.log(`command: ${command}`);
457
+ console.log(`current directory: ${process.cwd()}`);
458
+ console.log(`selected root: ${root}`);
459
+ console.log(`mode: ${mode}`);
460
+ console.log("");
461
+ console.log(`📋 計劃預覽:create 0 / merge 0 / skip ${planSkipCount} / conflict 0 — 沒有檔案需要建立或合併。`);
462
+ if (options.dryRun) {
463
+ console.log("");
464
+ console.log("dry-run: no files written");
465
+ }
466
+ printUpgradeNoopShortCircuit(version);
467
+ return;
468
+ }
469
+
440
470
  printPlan(command, root, mode, plan, version);
441
471
 
442
472
  if (options.dryRun) {
@@ -468,6 +498,29 @@ async function runInstall(command, root, options, version) {
468
498
  created.push(item.targetRel);
469
499
  }
470
500
 
501
+ // R-031.2 v0.3.2+: For freshly-created PROJECT_INDEX (fresh install), inject the
502
+ // current CLI version into the template version metadata row. Template ships with
503
+ // a hardcoded historical version (0.1.7) which is preserved by R-016 during upgrades
504
+ // but should NOT confuse a fresh installer about which version they just installed.
505
+ // Only triggers when PROJECT_INDEX was just created (not preserved/merged).
506
+ if (created.includes("dev/PROJECT_INDEX.md")) {
507
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
508
+ try {
509
+ const text = await readFile(indexPath, "utf8");
510
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
511
+ if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
512
+ const updated = text.replace(
513
+ /\| Agent Handoff Kit template version \| [\d.]+ \|/,
514
+ `| Agent Handoff Kit template version | ${version} |`
515
+ );
516
+ await writeFile(indexPath, updated, "utf8");
517
+ }
518
+ } catch {
519
+ // ignore — fresh install will still pass doctor because the anchor (R-016) only
520
+ // checks for the row's existence, not a specific version.
521
+ }
522
+ }
523
+
471
524
  for (const item of plan) {
472
525
  if (item.action !== "merge") continue;
473
526
  const backupPath = path.join(backupDir, item.targetRel);
@@ -477,8 +530,22 @@ async function runInstall(command, root, options, version) {
477
530
  merged.push(item.targetRel);
478
531
  }
479
532
 
480
- const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
481
533
  const skippedCount = plan.filter((item) => item.action === "skip").length;
534
+
535
+ // R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
536
+ // migration report, self-check doctor, install banner, onboarding canonical phrase.
537
+ // Prevents misleading "安裝完成" framing when user is just verifying they are latest.
538
+ const isUpgradeNoop = command === "upgrade"
539
+ && created.length === 0
540
+ && merged.length === 0
541
+ && conflicts.length === 0;
542
+
543
+ if (isUpgradeNoop) {
544
+ printUpgradeNoopShortCircuit(version);
545
+ return;
546
+ }
547
+
548
+ const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
482
549
  printInstallSummary(version, command, mode, root, {
483
550
  created: created.length,
484
551
  merged: merged.length,
@@ -487,9 +554,18 @@ async function runInstall(command, root, options, version) {
487
554
  backupRel: merged.length > 0 ? path.relative(root, backupDir) : null,
488
555
  reportRel: path.relative(root, report)
489
556
  });
490
- printInstallNextSteps(root, conflicts.length);
491
557
 
492
- // R-024 upgrade.done self-check: after upgrade writes, run doctor automatically.
558
+ // R-031 v0.3.1+: install vs upgrade narrative split. Upgrade substantive uses
559
+ // "升級完成" framing (not "安裝完成") and offers optional review prompt instead of
560
+ // pushing first-time onboarding canonical phrase.
561
+ // R-031.2 v0.3.2+: printUpgradeNextSteps now async (awaits inline whatsnew print).
562
+ if (command === "upgrade") {
563
+ await printUpgradeNextSteps(root, conflicts.length, version);
564
+ } else {
565
+ printInstallNextSteps(root, conflicts.length);
566
+ }
567
+
568
+ // R-024 upgrade.done self-check: after substantive upgrade writes, run doctor automatically.
493
569
  // The user must see whether the merged state actually reaches a clean health state.
494
570
  if (command === "upgrade" && conflicts.length === 0) {
495
571
  console.log("");
@@ -609,6 +685,18 @@ async function runDoctor(root, version, options = {}) {
609
685
  }
610
686
  }
611
687
 
688
+ // R-031.2 v0.3.2+: 項目狀態速覽 —— 三向 version 對比 + 距上次 closeout 幾耐 +
689
+ // 項目首次安裝距今幾耐。從用戶跑 doctor 嗰刻嘅 mental state 出發(confirm health /
690
+ // suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
691
+ console.log("");
692
+ console.log("項目狀態速覽:");
693
+ const versionAlignment = await assessVersionAlignment(root, version);
694
+ printVersionAlignment(versionAlignment);
695
+ const lastCloseout = await assessLastCloseout(root);
696
+ printLastCloseout(lastCloseout);
697
+ const projectAge = await assessProjectAge(root);
698
+ printProjectAge(projectAge);
699
+
612
700
  const overallHealthy = credentialResult.ok;
613
701
  printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
614
702
  checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
@@ -617,7 +705,7 @@ async function runDoctor(root, version, options = {}) {
617
705
  nextStep: !credentialResult.ok
618
706
  ? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
619
707
  : disciplineResult.ok
620
- ? "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
708
+ ? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
621
709
  : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
622
710
  });
623
711
  return overallHealthy ? "passed" : "failed";
@@ -937,6 +1025,137 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
937
1025
  return { ...base, action: "skip", reason: "preserve existing file" };
938
1026
  }
939
1027
 
1028
+ // R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
1029
+ // Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
1030
+ // and npm latest. Surfaces drift awareness because previous design relied on startup
1031
+ // maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
1032
+ // equals npm latest, so the notice never triggers, leaving user root drift invisible).
1033
+ async function assessVersionAlignment(root, cliVersion) {
1034
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1035
+ let rootVersion = null;
1036
+ try {
1037
+ const text = await readFile(indexPath, "utf8");
1038
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1039
+ if (m) rootVersion = m[1];
1040
+ } catch {
1041
+ // file missing or unreadable; rootVersion stays null
1042
+ }
1043
+
1044
+ let npmLatest = null;
1045
+ try {
1046
+ npmLatest = await fetchLatestVersion();
1047
+ } catch {
1048
+ // network failure; npmLatest stays null
1049
+ }
1050
+
1051
+ return { cliVersion, rootVersion, npmLatest };
1052
+ }
1053
+
1054
+ function printVersionAlignment(result) {
1055
+ const { cliVersion, rootVersion, npmLatest } = result;
1056
+ if (rootVersion === null) {
1057
+ console.log(` 📦 版本:CLI v${cliVersion} / root metadata 缺失(曾經手動編輯?)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
1058
+ return;
1059
+ }
1060
+ if (npmLatest === null) {
1061
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
1062
+ return;
1063
+ }
1064
+ const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
1065
+ if (aligned) {
1066
+ console.log(` 📦 版本:CLI / root / npm latest 三向對齊 v${cliVersion} ✅`);
1067
+ return;
1068
+ }
1069
+ console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest v${npmLatest}`);
1070
+ if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
1071
+ console.log(` npm 有新版(v${npmLatest});可執行:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1072
+ } else if (cliVersion !== rootVersion) {
1073
+ console.log(` 你 root template metadata 同 CLI 唔對齊;兩個版本仍相容 doctor 仍 PASS;如想對齊:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
1074
+ }
1075
+ }
1076
+
1077
+ // R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
1078
+ // line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
1079
+ // HANDOFF missing or unparseable.
1080
+ async function assessLastCloseout(root) {
1081
+ const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
1082
+ let date = null;
1083
+ try {
1084
+ const text = await readFile(handoffPath, "utf8");
1085
+ const m = text.match(/Last Updated:\s*(\d{4}-\d{2}-\d{2})/);
1086
+ if (m) date = m[1];
1087
+ } catch {
1088
+ // ignore
1089
+ }
1090
+
1091
+ if (!date) {
1092
+ const logPath = path.join(root, "dev/SESSION_LOG.md");
1093
+ try {
1094
+ const text = await readFile(logPath, "utf8");
1095
+ const m = text.match(/^## (\d{4}-\d{2}-\d{2})/m);
1096
+ if (m) date = m[1];
1097
+ } catch {
1098
+ // ignore
1099
+ }
1100
+ }
1101
+
1102
+ return { date };
1103
+ }
1104
+
1105
+ function printLastCloseout(result) {
1106
+ if (!result.date) {
1107
+ console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
1108
+ return;
1109
+ }
1110
+ const today = new Date();
1111
+ const closeout = new Date(result.date);
1112
+ const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
1113
+ if (daysDiff < 0) {
1114
+ console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
1115
+ } else if (daysDiff === 0) {
1116
+ console.log(` 📅 上次 closeout:今日(${result.date})`);
1117
+ } else if (daysDiff <= 30) {
1118
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
1119
+ } else {
1120
+ console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
1121
+ }
1122
+ }
1123
+
1124
+ // R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
1125
+ // dev/governance_migrations/ which records the first install date. Read-only; doctor
1126
+ // remains side-effect-free (no new write logic).
1127
+ async function assessProjectAge(root) {
1128
+ const migrationsDir = path.join(root, "dev/governance_migrations");
1129
+ try {
1130
+ const entries = await readdir(migrationsDir);
1131
+ const timestamps = entries.filter((name) => /^\d{8}T\d{6}Z$/.test(name)).sort();
1132
+ if (timestamps.length === 0) return { firstInstall: null };
1133
+ const oldest = timestamps[0];
1134
+ // Format: 20260423T112233Z → 2026-04-23
1135
+ const year = oldest.slice(0, 4);
1136
+ const month = oldest.slice(4, 6);
1137
+ const day = oldest.slice(6, 8);
1138
+ return { firstInstall: `${year}-${month}-${day}` };
1139
+ } catch {
1140
+ return { firstInstall: null };
1141
+ }
1142
+ }
1143
+
1144
+ function printProjectAge(result) {
1145
+ if (!result.firstInstall) {
1146
+ console.log(" 🌱 項目首次安裝距今:未知(dev/governance_migrations/ 未有 timestamp)");
1147
+ return;
1148
+ }
1149
+ const today = new Date();
1150
+ const firstInstall = new Date(result.firstInstall);
1151
+ const daysDiff = Math.floor((today - firstInstall) / (1000 * 60 * 60 * 24));
1152
+ if (daysDiff === 0) {
1153
+ console.log(` 🌱 項目首次安裝距今:今日(${result.firstInstall})`);
1154
+ } else {
1155
+ console.log(` 🌱 項目首次安裝距今:${daysDiff} 日(自 ${result.firstInstall})`);
1156
+ }
1157
+ }
1158
+
940
1159
  // R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
941
1160
  // Returns { ok, warnings } where:
942
1161
  // - ok: true if no warnings triggered
@@ -1371,6 +1590,19 @@ function printInstallNextSteps(root, conflictCount) {
1371
1590
  console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1372
1591
  console.log("");
1373
1592
  }
1593
+ // R-031.2 v0.3.2+: 「點 confirm 你裝啱咗」mini-checklist,直接答用戶第一次安裝後嘅
1594
+ // anxiety「我裝啱咗嗎」。三個具體 verify step + 一句講清本工具係 background harness
1595
+ // (冇 GUI、冇 server、需要連住 AI tool 先見到實際 value)。
1596
+ console.log("📋 點 confirm 你裝啱咗:");
1597
+ console.log("");
1598
+ console.log(" 1. 跑 npx @adamchanadam/agent-handoff-kit doctor 應該見到「status: passed」");
1599
+ console.log(" 2. 你 dev/ folder 應該有起碼 14 個檔(rules / SESSION_HANDOFF / SESSION_LOG 等)");
1600
+ console.log(" 3. 喺你 AI tool(Claude Code / Codex / Gemini)開新對話,貼下面起步句先見到實際 value");
1601
+ console.log("");
1602
+ console.log("⚠️ 注意:Agent Handoff Kit 只係 background harness —— 喺你 project folder 入面嘅幾類檔案。");
1603
+ console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
1604
+ console.log("");
1605
+ console.log("------------------------------------------------------------");
1374
1606
  console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1375
1607
  console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1376
1608
  console.log("------------------------------------------------------------");
@@ -1388,6 +1620,121 @@ function printInstallNextSteps(root, conflictCount) {
1388
1620
  console.log("============================================================");
1389
1621
  }
1390
1622
 
1623
+ // R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
1624
+ // (`printInstallNextSteps`) because the user is not first-time; pushing them through
1625
+ // the onboarding canonical phrase resets context they already have.
1626
+ async function printUpgradeNextSteps(root, conflictCount, version) {
1627
+ console.log("");
1628
+ console.log("============================================================");
1629
+ console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
1630
+ console.log("============================================================");
1631
+ if (conflictCount > 0) {
1632
+ console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
1633
+ console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
1634
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1635
+ console.log("");
1636
+ }
1637
+ // R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
1638
+ // version (and any intermediate versions the user skipped), without requiring the
1639
+ // user to ask AI separately. Treats user as collaborator who deserves to know what's
1640
+ // shipped, not reactive recipient who must opt-in to discovery.
1641
+ await printWhatsnew(root, version);
1642
+ console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
1643
+ console.log("");
1644
+ console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
1645
+ console.log("------------------------------------------------------------");
1646
+ console.log(`Work in ${root}. I just upgraded agent-handoff-kit. Brief me on what changed in this version and what I should pay attention to.`);
1647
+ console.log("------------------------------------------------------------");
1648
+ console.log("");
1649
+ console.log("🩺 升級驗收會在下方自動跑 doctor;若全綠即升級完成。");
1650
+ console.log("============================================================");
1651
+ }
1652
+
1653
+ // R-031.2 v0.3.2+: Print whatsnew summaries for the version range crossed by this
1654
+ // upgrade. fromVersion = user root template metadata version (the state before
1655
+ // upgrade; R-016 preserves this row so it still reflects the prior state after
1656
+ // upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
1657
+ // inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
1658
+ async function printWhatsnew(root, toVersion) {
1659
+ const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
1660
+ let fromVersion = null;
1661
+ try {
1662
+ const text = await readFile(indexPath, "utf8");
1663
+ const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
1664
+ if (m) fromVersion = m[1];
1665
+ } catch {
1666
+ return;
1667
+ }
1668
+ if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
1669
+ return;
1670
+ }
1671
+
1672
+ const whatsnewDir = path.join(packageRoot, "docs/whatsnew");
1673
+ let entries = [];
1674
+ try {
1675
+ entries = await readdir(whatsnewDir);
1676
+ } catch {
1677
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${toVersion}`);
1678
+ console.log("");
1679
+ return;
1680
+ }
1681
+
1682
+ const relevant = entries
1683
+ .filter((name) => /^v\d+\.\d+\.\d+\.md$/.test(name))
1684
+ .map((name) => name.replace(/^v/, "").replace(/\.md$/, ""))
1685
+ .filter((v) => compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0)
1686
+ .sort((a, b) => compareSemver(a, b));
1687
+
1688
+ if (relevant.length === 0) {
1689
+ console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
1690
+ console.log(` (v${fromVersion} → v${toVersion} 跨版本嘅完整變更見 GitHub Release 全列表)`);
1691
+ console.log("");
1692
+ return;
1693
+ }
1694
+
1695
+ console.log(`📰 本次升級(v${fromVersion} → v${toVersion})涵蓋 ${relevant.length} 個版本嘅 release notes:`);
1696
+ console.log("");
1697
+
1698
+ const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
1699
+ const elidedCount = relevant.length > 3 ? relevant.length - 2 : 0;
1700
+
1701
+ for (let i = 0; i < toShow.length; i += 1) {
1702
+ const v = toShow[i];
1703
+ const filePath = path.join(whatsnewDir, `v${v}.md`);
1704
+ try {
1705
+ const content = await readFile(filePath, "utf8");
1706
+ console.log(content.trimEnd());
1707
+ console.log("");
1708
+ if (i === 0 && elidedCount > 0) {
1709
+ console.log(` ⋯ 中間 ${elidedCount} 個版本嘅 release notes 略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
1710
+ console.log("");
1711
+ }
1712
+ } catch {
1713
+ console.log(`(v${v} release notes 檔缺失,見 https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${v})`);
1714
+ console.log("");
1715
+ }
1716
+ }
1717
+ console.log("------------------------------------------------------------");
1718
+ console.log("");
1719
+ }
1720
+
1721
+ // R-031 v0.3.1+: Upgrade no-op short-circuit. When the user runs upgrade on a root
1722
+ // already at latest version (skip all / create 0 / merge 0 / conflict 0), print a
1723
+ // short factual message and return. Saves disk (no migration report) + reduces noise
1724
+ // (no self-check doctor) + avoids misleading "安裝完成" framing for an idempotent
1725
+ // operation where nothing changed.
1726
+ function printUpgradeNoopShortCircuit(version) {
1727
+ console.log("");
1728
+ console.log(`📦 版本:v${version}`);
1729
+ console.log("🛠️ 模式:upgrade-existing");
1730
+ console.log("🔎 剛做咗:檢查所有管治架構檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
1731
+ console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
1732
+ console.log("");
1733
+ console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
1734
+ console.log(" npx @adamchanadam/agent-handoff-kit doctor");
1735
+ console.log("");
1736
+ }
1737
+
1391
1738
  function listOrNone(items) {
1392
1739
  if (items.length === 0) return ["- none"];
1393
1740
  return items.map((item) => `- ${item}`);
@@ -0,0 +1,13 @@
1
+ # v0.3.1
2
+
3
+ ## 本版新加咗咩
4
+
5
+ CLI 升級流程嘅 messaging 改進 —— 你升完或者第二次跑 upgrade 嗰陣會見到唔同 output。第二次跑 upgrade(零改動)會直接短訊「你已係最新版本」,唔再印「安裝完成」+ 新手起步句嘅完整 ceremony。
6
+
7
+ ## 對你已有檔案嘅影響
8
+
9
+ 完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
10
+
11
+ ## 建議下一步
12
+
13
+ 跑 doctor confirm 健康即可。
@@ -0,0 +1,13 @@
1
+ # v0.3.2
2
+
3
+ ## 本版新加咗咩
4
+
5
+ Doctor 同 init 命令加入「項目狀態速覽」+「點 confirm 你裝啱咗」。Doctor 跑完會印你嘅版本對齊狀況(CLI / root template / npm latest 三向比較)、上次 closeout 距今幾耐、項目首次安裝距今幾耐。Init 完會印 mini-checklist 答「我裝啱咗嗎」嘅 anxiety,並講清本工具係 background harness(需要連住 AI tool 先見到實際 value)。Upgrade 完會直接 inline print 本版同跨版本嘅 whatsnew 摘要(即你而家睇緊呢段),唔等你 ask AI。
6
+
7
+ ## 對你已有檔案嘅影響
8
+
9
+ 完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
10
+
11
+ ## 建議下一步
12
+
13
+ 跑 doctor confirm 健康,順便試吓本版新加嘅「項目狀態速覽」。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -10,6 +10,7 @@
10
10
  "bin/",
11
11
  "runtime-core/",
12
12
  "packs/",
13
+ "docs/whatsnew/",
13
14
  "README.md",
14
15
  "LICENSE"
15
16
  ],