@adamchanadam/agent-handoff-kit 0.1.2 → 0.1.4
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 +71 -98
- package/bin/agent-handoff-kit.mjs +197 -20
- package/package.json +1 -1
- package/packs/agent-governance.md +2 -0
- package/runtime-core/AGENTS.core.md +5 -0
- package/runtime-core/PROJECT_INDEX.md +3 -2
- package/runtime-core/SESSION_HANDOFF.md +2 -0
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +14 -0
package/README.md
CHANGED
|
@@ -1,34 +1,31 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.1.
|
|
3
|
+
狀態:`v0.1.4` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
|
|
4
4
|
|
|
5
|
-
Agent Handoff Kit
|
|
5
|
+

|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
AI 很容易在新工作階段失去前文。它可能不知道上次改了甚麼、哪些文件才是最新、哪些資料只是參考、哪些操作需要先問你。
|
|
9
|
+
它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
想先看非技術版介紹,可打開 GitHub repo 內的 [`agent-handoff-kit-intro.html`](agent-handoff-kit-intro.html)。那一頁是新手 60 秒入門,README 則保留安裝、日常使用與限制。
|
|
14
12
|
|
|
15
|
-
##
|
|
13
|
+
## 它解決甚麼問題
|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
用 AI 做長期項目,常見四個問題:
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
17
|
+
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
18
|
+
|---|---|
|
|
19
|
+
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
20
|
+
| 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
21
|
+
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
|
|
22
|
+
| AI 可能亂改、亂刪或誤發佈 | 內置 safety 工作模式;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
26
25
|
|
|
27
|
-
|
|
28
|
-
- 不想在專案內新增任何交接文件。
|
|
29
|
-
- 需要已完全成熟的穩定版安裝工具。
|
|
26
|
+
## 三步上手
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
### 一、安裝
|
|
32
29
|
|
|
33
30
|
在你的專案資料夾打開 Terminal,執行:
|
|
34
31
|
|
|
@@ -36,51 +33,43 @@ Agent Handoff Kit 把這些事情寫進專案文件:開工先讀哪裡、任
|
|
|
36
33
|
npx @adamchanadam/agent-handoff-kit init
|
|
37
34
|
```
|
|
38
35
|
|
|
39
|
-
|
|
36
|
+
出現確認問題時,輸入 `yes`。
|
|
40
37
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
38
|
+
安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
|
|
39
|
+
|
|
40
|
+
### 二、開工
|
|
44
41
|
|
|
45
|
-
|
|
42
|
+
打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。沒有那段文字時,可貼這句:
|
|
46
43
|
|
|
47
44
|
```text
|
|
48
|
-
|
|
45
|
+
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
49
46
|
```
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
|
|
52
49
|
|
|
53
|
-
|
|
50
|
+
### 三、收工
|
|
54
51
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
正確做法是:
|
|
58
|
-
|
|
59
|
-
1. 打開你要使用的 AI 工具。
|
|
60
|
-
2. 新增一段對話。
|
|
61
|
-
3. 貼上安裝工具顯示的 `Work in ...` 文字。
|
|
62
|
-
4. 要求 AI 先讀 `AGENTS.md`,並在改檔前說明它讀到的目前狀態。
|
|
63
|
-
5. 然後直接描述你要完成的任務。
|
|
64
|
-
|
|
65
|
-
你可以貼上類似以下文字:
|
|
52
|
+
工作完成想結束時,只需輸入:
|
|
66
53
|
|
|
67
54
|
```text
|
|
68
|
-
|
|
69
|
-
Read AGENTS.md first. Tell me what you understand before changing files.
|
|
55
|
+
收工
|
|
70
56
|
```
|
|
71
57
|
|
|
72
|
-
|
|
58
|
+
也可以輸入:
|
|
73
59
|
|
|
74
60
|
```text
|
|
75
|
-
|
|
61
|
+
wrap up
|
|
62
|
+
handoff
|
|
76
63
|
```
|
|
77
64
|
|
|
78
|
-
|
|
65
|
+
AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
|
|
79
66
|
|
|
80
67
|
```text
|
|
81
|
-
|
|
68
|
+
START_NEXT_SESSION_PROMPT.txt
|
|
82
69
|
```
|
|
83
70
|
|
|
71
|
+
這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
|
|
72
|
+
|
|
84
73
|
## 檢查是否安裝完整
|
|
85
74
|
|
|
86
75
|
如要檢查安裝是否完整,可在 Terminal 執行:
|
|
@@ -89,18 +78,19 @@ Read AGENTS.md first. Tell me what you understand before changing files.
|
|
|
89
78
|
npx @adamchanadam/agent-handoff-kit doctor
|
|
90
79
|
```
|
|
91
80
|
|
|
92
|
-
看到 `status: passed
|
|
81
|
+
看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
|
|
93
82
|
|
|
94
83
|
這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
|
|
95
84
|
|
|
96
85
|
## 會安裝甚麼
|
|
97
86
|
|
|
98
|
-
|
|
87
|
+
安裝工具會在你的專案中建立:
|
|
99
88
|
|
|
100
89
|
```text
|
|
101
90
|
AGENTS.md
|
|
102
91
|
CLAUDE.md
|
|
103
92
|
GEMINI.md
|
|
93
|
+
START_NEXT_SESSION_PROMPT.txt
|
|
104
94
|
dev/SESSION_HANDOFF.md
|
|
105
95
|
dev/SESSION_LOG.md
|
|
106
96
|
dev/PROJECT_INDEX.md
|
|
@@ -109,13 +99,12 @@ dev/RULE_PACKS.md
|
|
|
109
99
|
dev/rules/*.md
|
|
110
100
|
```
|
|
111
101
|
|
|
112
|
-
每個文件的用途如下:
|
|
113
|
-
|
|
114
102
|
| 文件 | 用途 |
|
|
115
103
|
|---|---|
|
|
116
104
|
| `AGENTS.md` | AI 開工時最先讀的入口文件。 |
|
|
117
105
|
| `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
|
|
118
106
|
| `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
|
|
107
|
+
| `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
|
|
119
108
|
| `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
|
|
120
109
|
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。 |
|
|
121
110
|
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
@@ -125,75 +114,59 @@ dev/rules/*.md
|
|
|
125
114
|
|
|
126
115
|
你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
|
|
127
116
|
|
|
128
|
-
##
|
|
117
|
+
## 工作模式
|
|
129
118
|
|
|
130
|
-
|
|
119
|
+
你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
|
|
131
120
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
121
|
+
| 你的任務 | AI 應使用的工作規則 |
|
|
122
|
+
|---|---|
|
|
123
|
+
| 寫或改代碼、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
|
|
124
|
+
| 查資料、比較來源、整理證據 | `research` |
|
|
125
|
+
| 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
|
|
126
|
+
| 整理 Notion、Google Drive 或知識庫 | `knowledge` |
|
|
127
|
+
| 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
|
|
128
|
+
| 改規則、改流程、整理交接 | `agent-governance`;先找既有真源,不盲目新增規則 |
|
|
137
129
|
|
|
138
|
-
|
|
130
|
+
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
139
131
|
|
|
140
|
-
|
|
132
|
+
## 安全護欄
|
|
141
133
|
|
|
142
|
-
|
|
143
|
-
幫我檢查 README 是否清楚,先只提出問題,不要改檔。
|
|
144
|
-
```
|
|
134
|
+
就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
|
|
145
135
|
|
|
146
|
-
|
|
136
|
+
- 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
|
|
137
|
+
- 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
|
|
138
|
+
- 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
|
|
139
|
+
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
140
|
+
- 發佈需明確批准:tag、GitHub Release、npm publish、部署或上傳都不能因「準備好了」而自動執行。
|
|
147
141
|
|
|
148
|
-
|
|
149
|
-
請更新 README 的安裝後說明,完成後執行必要檢查,並告訴我改了甚麼。
|
|
150
|
-
```
|
|
142
|
+
## 已安裝舊版,或已有 AI 記憶文件?
|
|
151
143
|
|
|
152
|
-
|
|
144
|
+
如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,先用最新版 CLI dry-run 預演會發生甚麼:
|
|
153
145
|
|
|
154
|
-
```
|
|
155
|
-
|
|
146
|
+
```bash
|
|
147
|
+
npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
156
148
|
```
|
|
157
149
|
|
|
158
|
-
|
|
150
|
+
確認沒有問題後,再執行:
|
|
159
151
|
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
handoff
|
|
152
|
+
```bash
|
|
153
|
+
npx @adamchanadam/agent-handoff-kit@latest upgrade
|
|
163
154
|
```
|
|
164
155
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
## 工作規則怎樣運作
|
|
156
|
+
`@latest` 代表使用 npm 上最新的 Agent Handoff Kit CLI。`upgrade` 則負責把專案內已安裝的 Kit 文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會報 conflict,不會靜默覆寫。
|
|
168
157
|
|
|
169
|
-
|
|
158
|
+
看到 `conflict` 不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把 dry-run 輸出貼給 AI,請它幫你判斷要保留、合併,還是手動修改。
|
|
170
159
|
|
|
171
|
-
|
|
172
|
-
|---|---|
|
|
173
|
-
| 修改程式、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
|
|
174
|
-
| 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
|
|
175
|
-
| 查證資料、比較來源、整理證據 | `research` |
|
|
176
|
-
| 整理 Notion、Google Drive 或知識庫 | `knowledge` |
|
|
177
|
-
| 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
|
|
178
|
-
|
|
179
|
-
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
180
|
-
|
|
181
|
-
## 既有專案升級
|
|
182
|
-
|
|
183
|
-
若你的專案已經有 `AGENTS.md` 或其他 AI 記憶文件,請先預演,不要直接覆寫:
|
|
160
|
+
## 版本提示
|
|
184
161
|
|
|
185
|
-
|
|
186
|
-
npx @adamchanadam/agent-handoff-kit upgrade --dry-run
|
|
187
|
-
```
|
|
162
|
+
CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
188
163
|
|
|
189
|
-
|
|
164
|
+
若你不想檢查更新,可設定:
|
|
190
165
|
|
|
191
166
|
```bash
|
|
192
|
-
|
|
167
|
+
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
193
168
|
```
|
|
194
169
|
|
|
195
|
-
升級工具會保留既有檔案。能安全合併時才合併;不能安全合併時會報 conflict,不會靜默覆寫。
|
|
196
|
-
|
|
197
170
|
## 語言使用
|
|
198
171
|
|
|
199
172
|
安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
|
|
@@ -224,12 +197,12 @@ npm package 只包含安裝所需內容:
|
|
|
224
197
|
- `LICENSE`
|
|
225
198
|
- `package.json`
|
|
226
199
|
|
|
227
|
-
|
|
200
|
+
GitHub repo 內的新手介紹頁 `agent-handoff-kit-intro.html` 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
|
|
228
201
|
|
|
229
202
|
## 目前限制
|
|
230
203
|
|
|
231
|
-
- `v0.1.
|
|
232
|
-
-
|
|
204
|
+
- `v0.1.4` 是 GitHub 與 npm 同步發佈版本。
|
|
205
|
+
- 這是早期可用版本,尚未宣稱完整穩定。
|
|
233
206
|
- 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
|
|
234
207
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
235
208
|
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
@@ -13,6 +13,7 @@ const mappings = [
|
|
|
13
13
|
["runtime-core/AGENTS.core.md", "AGENTS.md"],
|
|
14
14
|
["runtime-core/CLAUDE.md", "CLAUDE.md"],
|
|
15
15
|
["runtime-core/GEMINI.md", "GEMINI.md"],
|
|
16
|
+
["runtime-core/START_NEXT_SESSION_PROMPT.txt", "START_NEXT_SESSION_PROMPT.txt"],
|
|
16
17
|
["runtime-core/SESSION_HANDOFF.md", "dev/SESSION_HANDOFF.md"],
|
|
17
18
|
["runtime-core/SESSION_LOG.md", "dev/SESSION_LOG.md"],
|
|
18
19
|
["runtime-core/PROJECT_INDEX.md", "dev/PROJECT_INDEX.md"],
|
|
@@ -63,7 +64,18 @@ const requiredAnchors = [
|
|
|
63
64
|
"handoff saved",
|
|
64
65
|
"📋 Next session: copy and paste the whole block below",
|
|
65
66
|
"State Reconciliation Check",
|
|
66
|
-
"Do not append a new state snapshot"
|
|
67
|
+
"Do not append a new state snapshot",
|
|
68
|
+
"START_NEXT_SESSION_PROMPT.txt"
|
|
69
|
+
]
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
target: "START_NEXT_SESSION_PROMPT.txt",
|
|
73
|
+
label: "next-session prompt convenience copy",
|
|
74
|
+
snippets: [
|
|
75
|
+
"Work in ",
|
|
76
|
+
"Read in order:",
|
|
77
|
+
"dev/PROJECT_INDEX.md",
|
|
78
|
+
"If this root does not match the expected project root"
|
|
67
79
|
]
|
|
68
80
|
},
|
|
69
81
|
{
|
|
@@ -132,8 +144,7 @@ const requiredAnchors = [
|
|
|
132
144
|
target: "dev/PROJECT_INDEX.md",
|
|
133
145
|
label: "template version metadata",
|
|
134
146
|
snippets: [
|
|
135
|
-
"Agent Handoff Kit template version"
|
|
136
|
-
"0.1.2"
|
|
147
|
+
"Agent Handoff Kit template version"
|
|
137
148
|
]
|
|
138
149
|
},
|
|
139
150
|
{
|
|
@@ -259,6 +270,7 @@ main().catch((error) => {
|
|
|
259
270
|
|
|
260
271
|
async function main() {
|
|
261
272
|
const version = await readPackageVersion();
|
|
273
|
+
await maybePrintUpdateNotice(version);
|
|
262
274
|
const { command, options } = parseArgs(process.argv.slice(2));
|
|
263
275
|
if (!command || options.help) {
|
|
264
276
|
printHelp(version);
|
|
@@ -307,6 +319,7 @@ async function runInstall(command, root, options, version) {
|
|
|
307
319
|
|
|
308
320
|
if (options.dryRun) {
|
|
309
321
|
console.log("\ndry-run: no files written");
|
|
322
|
+
printDryRunExplanation(plan);
|
|
310
323
|
if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
|
|
311
324
|
return;
|
|
312
325
|
}
|
|
@@ -343,12 +356,12 @@ async function runInstall(command, root, options, version) {
|
|
|
343
356
|
}
|
|
344
357
|
|
|
345
358
|
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
346
|
-
console.log(`\
|
|
347
|
-
console.log(
|
|
348
|
-
console.log(
|
|
349
|
-
console.log(
|
|
350
|
-
if (merged.length > 0) console.log(
|
|
351
|
-
console.log(
|
|
359
|
+
console.log(`\n✅ created: ${created.length}`);
|
|
360
|
+
console.log(`🔀 merged: ${merged.length}`);
|
|
361
|
+
console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
|
|
362
|
+
console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
|
|
363
|
+
if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
|
|
364
|
+
console.log(`📄 migration report: ${path.relative(root, report)}`);
|
|
352
365
|
printInstallNextSteps(root, conflicts.length);
|
|
353
366
|
if (conflicts.length > 0) process.exitCode = 1;
|
|
354
367
|
}
|
|
@@ -369,6 +382,8 @@ async function runDoctor(root, version) {
|
|
|
369
382
|
|
|
370
383
|
if (missing.length > 0) {
|
|
371
384
|
console.log(`\nstatus: failed (${missing.length} missing)`);
|
|
385
|
+
console.log("⚠️ 檢查未通過:有必要檔案不存在。");
|
|
386
|
+
console.log("下一步:先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。");
|
|
372
387
|
process.exitCode = 1;
|
|
373
388
|
return;
|
|
374
389
|
}
|
|
@@ -382,6 +397,8 @@ async function runDoctor(root, version) {
|
|
|
382
397
|
|
|
383
398
|
if (anchorFailures.length > 0) {
|
|
384
399
|
console.log(`\nstatus: failed (${anchorFailures.length} anchor checks failed)`);
|
|
400
|
+
console.log("⚠️ 檢查未通過:有檔案存在,但內容缺少必要段落。");
|
|
401
|
+
console.log("下一步:執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。");
|
|
385
402
|
process.exitCode = 1;
|
|
386
403
|
return;
|
|
387
404
|
}
|
|
@@ -398,11 +415,69 @@ async function runDoctor(root, version) {
|
|
|
398
415
|
|
|
399
416
|
if (schemaFailures.length > 0) {
|
|
400
417
|
console.log(`\nstatus: failed (${schemaFailures.length} schema checks failed)`);
|
|
418
|
+
console.log("⚠️ 檢查未通過:交接或索引文件結構不完整。");
|
|
419
|
+
console.log("下一步:把這段 doctor 輸出貼給 AI,請它先修交接結構,不要直接重裝覆蓋。");
|
|
420
|
+
process.exitCode = 1;
|
|
421
|
+
return;
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
const mirrorRows = await checkPromptMirror(root);
|
|
425
|
+
const mirrorFailures = mirrorRows.filter((row) => !row.ok);
|
|
426
|
+
console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
|
|
427
|
+
for (const row of mirrorRows) {
|
|
428
|
+
console.log(`${row.ok ? "ok" : "missing"} ${row.target} (${row.label})`);
|
|
429
|
+
if (!row.ok && row.reason) console.log(` reason: ${row.reason}`);
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
if (mirrorFailures.length > 0) {
|
|
433
|
+
console.log(`\nstatus: failed (${mirrorFailures.length} prompt mirror checks failed)`);
|
|
434
|
+
console.log("⚠️ 檢查未通過:下次開工提示副本與 handoff 真源不同。");
|
|
435
|
+
console.log("下一步:以 dev/SESSION_HANDOFF.md 的 Next Session Opening Message 為準,重生 START_NEXT_SESSION_PROMPT.txt。");
|
|
401
436
|
process.exitCode = 1;
|
|
402
437
|
return;
|
|
403
438
|
}
|
|
404
439
|
|
|
405
440
|
console.log("\nstatus: passed");
|
|
441
|
+
console.log("✅ 檢查通過:必要文件存在,基本結構完整,下次開工提示副本也與 handoff 一致。");
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
async function checkPromptMirror(root) {
|
|
445
|
+
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
446
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
447
|
+
let handoffText = "";
|
|
448
|
+
let promptText = "";
|
|
449
|
+
try {
|
|
450
|
+
handoffText = await readFile(handoffPath, "utf8");
|
|
451
|
+
} catch {
|
|
452
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff unreadable" }];
|
|
453
|
+
}
|
|
454
|
+
try {
|
|
455
|
+
promptText = await readFile(promptPath, "utf8");
|
|
456
|
+
} catch {
|
|
457
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "prompt copy unreadable" }];
|
|
458
|
+
}
|
|
459
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
460
|
+
if (!openingMessage) {
|
|
461
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "handoff opening message missing" }];
|
|
462
|
+
}
|
|
463
|
+
const ok = normalizePrompt(promptText) === normalizePrompt(openingMessage);
|
|
464
|
+
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok, reason: ok ? "" : "convenience copy differs from dev/SESSION_HANDOFF.md" }];
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
function extractOpeningMessage(text) {
|
|
468
|
+
const marker = "📋 Next session: copy and paste the whole block below";
|
|
469
|
+
const markerIndex = text.indexOf(marker);
|
|
470
|
+
if (markerIndex < 0) return null;
|
|
471
|
+
const fenceStart = text.indexOf("```text", markerIndex);
|
|
472
|
+
if (fenceStart < 0) return null;
|
|
473
|
+
const contentStart = text.indexOf("\n", fenceStart);
|
|
474
|
+
const fenceEnd = text.indexOf("```", contentStart + 1);
|
|
475
|
+
if (contentStart < 0 || fenceEnd < 0) return null;
|
|
476
|
+
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
function normalizePrompt(text) {
|
|
480
|
+
return text.replace(/\r\n/g, "\n").trim();
|
|
406
481
|
}
|
|
407
482
|
|
|
408
483
|
async function checkRequiredAnchors(root) {
|
|
@@ -566,6 +641,8 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
566
641
|
console.log(`selected root: ${root}`);
|
|
567
642
|
console.log(`mode: ${mode}`);
|
|
568
643
|
console.log("");
|
|
644
|
+
console.log("📋 人話解讀:下面只是計劃。create 會新增缺少檔案,merge 會在備份後安全合併,skip 會保留既有檔案,conflict 代表工具停手等你確認。");
|
|
645
|
+
console.log("");
|
|
569
646
|
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
570
647
|
const items = plan.filter((item) => item.action === action);
|
|
571
648
|
console.log(`${action}: ${items.length}`);
|
|
@@ -574,6 +651,18 @@ function printPlan(command, root, mode, plan, version) {
|
|
|
574
651
|
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
575
652
|
}
|
|
576
653
|
|
|
654
|
+
function printDryRunExplanation(plan) {
|
|
655
|
+
const conflicts = plan.filter((item) => item.action === "conflict");
|
|
656
|
+
console.log("✅ 這次沒有改動任何檔案。");
|
|
657
|
+
if (conflicts.length === 0) {
|
|
658
|
+
console.log("✅ 沒有發現 conflict。你仍應先看清楚 create / merge / skip 清單,再決定是否執行正式 upgrade。");
|
|
659
|
+
return;
|
|
660
|
+
}
|
|
661
|
+
console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
|
|
662
|
+
console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
|
|
663
|
+
console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
|
|
664
|
+
}
|
|
665
|
+
|
|
577
666
|
async function confirmWrite() {
|
|
578
667
|
const rl = createInterface({ input, output });
|
|
579
668
|
try {
|
|
@@ -632,6 +721,89 @@ async function readPackageVersion() {
|
|
|
632
721
|
}
|
|
633
722
|
}
|
|
634
723
|
|
|
724
|
+
async function maybePrintUpdateNotice(currentVersion) {
|
|
725
|
+
if (shouldSkipUpdateCheck()) return;
|
|
726
|
+
if (!isStableSemver(currentVersion)) return;
|
|
727
|
+
|
|
728
|
+
const latestVersion = await fetchLatestVersion();
|
|
729
|
+
if (!latestVersion || !isStableSemver(latestVersion)) return;
|
|
730
|
+
if (compareSemver(latestVersion, currentVersion) <= 0) return;
|
|
731
|
+
|
|
732
|
+
printUpdateNotice(currentVersion, latestVersion);
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
function shouldSkipUpdateCheck() {
|
|
736
|
+
if (process.env.AGENT_HANDOFF_KIT_NO_UPDATE_CHECK === "1") return true;
|
|
737
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_CHECK_FORCE === "1") return false;
|
|
738
|
+
if (process.env.CI) return true;
|
|
739
|
+
if ((process.env.npm_lifecycle_event ?? "").startsWith("qa:")) return true;
|
|
740
|
+
return false;
|
|
741
|
+
}
|
|
742
|
+
|
|
743
|
+
async function fetchLatestVersion() {
|
|
744
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST) {
|
|
745
|
+
return process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST;
|
|
746
|
+
}
|
|
747
|
+
const url = process.env.AGENT_HANDOFF_KIT_UPDATE_REGISTRY_URL
|
|
748
|
+
?? "https://registry.npmjs.org/@adamchanadam%2Fagent-handoff-kit/latest";
|
|
749
|
+
const timeoutMs = Number.parseInt(process.env.AGENT_HANDOFF_KIT_UPDATE_TIMEOUT_MS ?? "1200", 10);
|
|
750
|
+
const controller = new AbortController();
|
|
751
|
+
const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 1200);
|
|
752
|
+
try {
|
|
753
|
+
const response = await fetch(url, {
|
|
754
|
+
headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
|
|
755
|
+
signal: controller.signal
|
|
756
|
+
});
|
|
757
|
+
if (!response.ok) return null;
|
|
758
|
+
const data = await response.json();
|
|
759
|
+
return typeof data.version === "string" ? data.version : null;
|
|
760
|
+
} catch {
|
|
761
|
+
return null;
|
|
762
|
+
} finally {
|
|
763
|
+
clearTimeout(timer);
|
|
764
|
+
}
|
|
765
|
+
}
|
|
766
|
+
|
|
767
|
+
function isStableSemver(version) {
|
|
768
|
+
return /^\d+\.\d+\.\d+$/.test(version);
|
|
769
|
+
}
|
|
770
|
+
|
|
771
|
+
function compareSemver(left, right) {
|
|
772
|
+
const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
|
|
773
|
+
const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
|
|
774
|
+
for (let i = 0; i < 3; i += 1) {
|
|
775
|
+
if (leftParts[i] > rightParts[i]) return 1;
|
|
776
|
+
if (leftParts[i] < rightParts[i]) return -1;
|
|
777
|
+
}
|
|
778
|
+
return 0;
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
function printUpdateNotice(currentVersion, latestVersion) {
|
|
782
|
+
const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
|
|
783
|
+
const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
|
|
784
|
+
const lines = [
|
|
785
|
+
`✨ 有新版可用:${currentVersion} -> ${latestVersion}`,
|
|
786
|
+
`如要使用最新版,執行:${command}`,
|
|
787
|
+
"",
|
|
788
|
+
"如果你是全域安裝:",
|
|
789
|
+
"npm install -g @adamchanadam/agent-handoff-kit",
|
|
790
|
+
"",
|
|
791
|
+
"完整 release notes:",
|
|
792
|
+
releaseUrl
|
|
793
|
+
];
|
|
794
|
+
const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
|
|
795
|
+
console.log(`╭${"─".repeat(width)}╮`);
|
|
796
|
+
for (const line of lines) {
|
|
797
|
+
console.log(`│ ${line}${" ".repeat(width - visibleLength(line) - 1)}│`);
|
|
798
|
+
}
|
|
799
|
+
console.log(`╰${"─".repeat(width)}╯`);
|
|
800
|
+
console.log("");
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
function visibleLength(text) {
|
|
804
|
+
return [...text].length;
|
|
805
|
+
}
|
|
806
|
+
|
|
635
807
|
function printCard(version, status, eyes) {
|
|
636
808
|
console.log(` /\\_/\\ Agent Handoff Kit v${version}`);
|
|
637
809
|
console.log(` ( ${eyes} ) ${status}`);
|
|
@@ -642,25 +814,25 @@ function printCard(version, status, eyes) {
|
|
|
642
814
|
function printInstallNextSteps(root, conflictCount) {
|
|
643
815
|
console.log("");
|
|
644
816
|
console.log("============================================================");
|
|
645
|
-
console.log("安裝完成:下一步請在 AI 對話中操作");
|
|
817
|
+
console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
|
|
646
818
|
console.log("============================================================");
|
|
647
819
|
if (conflictCount > 0) {
|
|
648
|
-
console.log("
|
|
649
|
-
console.log("
|
|
820
|
+
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
821
|
+
console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
|
|
822
|
+
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
650
823
|
console.log("");
|
|
651
824
|
}
|
|
652
|
-
console.log("請注意:下面文字不是 Terminal 指令。");
|
|
653
|
-
console.log("請打開你要使用的 AI
|
|
825
|
+
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
826
|
+
console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
|
|
654
827
|
console.log("------------------------------------------------------------");
|
|
655
|
-
console.log(`Work in ${root}.`);
|
|
656
|
-
console.log("Read AGENTS.md first. Tell me what you understand before changing files.");
|
|
828
|
+
console.log(`Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
|
|
657
829
|
console.log("------------------------------------------------------------");
|
|
658
830
|
console.log("");
|
|
659
|
-
console.log("然後直接描述你的任務,例如:");
|
|
660
|
-
console.log("整理這個專案,先告訴我你讀到的目前狀態與下一步。");
|
|
831
|
+
console.log("🚀 然後直接描述你的任務,例如:");
|
|
832
|
+
console.log(" 整理這個專案,先告訴我你讀到的目前狀態與下一步。");
|
|
661
833
|
console.log("");
|
|
662
|
-
console.log("如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
663
|
-
console.log("npx @adamchanadam/agent-handoff-kit doctor");
|
|
834
|
+
console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
835
|
+
console.log(" npx @adamchanadam/agent-handoff-kit doctor");
|
|
664
836
|
console.log("============================================================");
|
|
665
837
|
}
|
|
666
838
|
|
|
@@ -692,6 +864,11 @@ Commands:
|
|
|
692
864
|
upgrade Preserve existing files; merge safe core updates or report conflicts.
|
|
693
865
|
doctor Check required installed files.
|
|
694
866
|
|
|
867
|
+
中文速讀:
|
|
868
|
+
✅ init 第一次安裝 Kit 文件。
|
|
869
|
+
🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
|
|
870
|
+
🩺 doctor 檢查必要文件與交接結構是否完整。
|
|
871
|
+
|
|
695
872
|
After install:
|
|
696
873
|
Do not type "Follow AGENTS.md" into Terminal.
|
|
697
874
|
Open your AI tool, start a new chat, paste the shown Work in ... message,
|
package/package.json
CHANGED
|
@@ -17,6 +17,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
17
17
|
4. Do not let development-only workspace rules enter public runtime.
|
|
18
18
|
5. Check complexity budget before adding default-core behavior.
|
|
19
19
|
6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, `dev/DOC_SYNC_REGISTRY.md`, or existing rule packs can carry the need without a new file.
|
|
20
|
+
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs its own handoff/log/index/registry persistence.
|
|
20
21
|
|
|
21
22
|
## Checks
|
|
22
23
|
|
|
@@ -24,6 +25,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
24
25
|
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
25
26
|
- Confirm old overlapping wording was retired or marked legacy.
|
|
26
27
|
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
28
|
+
- Before claiming completion, inspect the active root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`; do not assume child or demo workspaces cover the parent/root workspace.
|
|
27
29
|
|
|
28
30
|
## Closeout
|
|
29
31
|
|
|
@@ -44,6 +44,8 @@ Use this loop for every task:
|
|
|
44
44
|
4. QC: run available checks or state why they cannot run.
|
|
45
45
|
5. PERSIST: update handoff/log and any affected project index or sync registry.
|
|
46
46
|
|
|
47
|
+
External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence step for the active project root, and completion cannot be claimed until that root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md` have been inspected and updated or explicitly marked not applicable.
|
|
48
|
+
|
|
47
49
|
For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
|
|
48
50
|
|
|
49
51
|
## 3. Safety Boundaries
|
|
@@ -71,6 +73,7 @@ At full closeout:
|
|
|
71
73
|
7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
|
|
72
74
|
8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
|
|
73
75
|
9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
|
|
76
|
+
10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
|
|
74
77
|
|
|
75
78
|
Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
|
|
76
79
|
|
|
@@ -105,6 +108,8 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
|
|
|
105
108
|
|
|
106
109
|
After the task, persist durable facts into handoff/log/index/registry. Do not assume the next session remembers pack context unless it is recorded.
|
|
107
110
|
|
|
111
|
+
If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs Agent Handoff Kit persistence before the task is complete.
|
|
112
|
+
|
|
108
113
|
## Core Complexity Rule
|
|
109
114
|
|
|
110
115
|
New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
|
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.1.
|
|
9
|
+
| Agent Handoff Kit template version | 0.1.4 | package prototype |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -21,6 +21,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
21
21
|
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
22
|
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
23
|
| `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
|
|
24
|
+
| `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
|
|
24
25
|
| `src/` | application source | coding task |
|
|
25
26
|
| `tests/` | tests | coding/QC |
|
|
26
27
|
| `docs/` | user or product docs | doc/public behavior change |
|
|
@@ -79,7 +80,7 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
79
80
|
| UI behavior | TBD | build + visual/manual check |
|
|
80
81
|
| Data model | TBD | migration/checks |
|
|
81
82
|
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
82
|
-
| Closeout/startup contract | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current |
|
|
83
|
+
| Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
|
|
83
84
|
|
|
84
85
|
## External Services
|
|
85
86
|
|
|
@@ -128,6 +128,8 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
|
|
|
128
128
|
<!-- ack:section:next-session-opening-message -->
|
|
129
129
|
## Next Session Opening Message
|
|
130
130
|
|
|
131
|
+
This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
|
|
132
|
+
|
|
131
133
|
📋 Next session: copy and paste the whole block below
|
|
132
134
|
|
|
133
135
|
```text
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
Work in <absolute project root>.
|
|
2
|
+
|
|
3
|
+
Read in order:
|
|
4
|
+
1. AGENTS.md
|
|
5
|
+
2. dev/SESSION_HANDOFF.md
|
|
6
|
+
3. dev/SESSION_LOG.md
|
|
7
|
+
4. dev/PROJECT_INDEX.md
|
|
8
|
+
5. dev/RULE_PACKS.md
|
|
9
|
+
|
|
10
|
+
Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
|
|
11
|
+
|
|
12
|
+
If this root does not match the expected project root, stop and ask for confirmation.
|
|
13
|
+
|
|
14
|
+
After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
|