@adamchanadam/agent-handoff-kit 0.2.3 → 0.3.1
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 +62 -85
- package/bin/agent-handoff-kit.mjs +1528 -1285
- package/package.json +1 -1
- package/packs/integrations.md +179 -0
- package/packs/knowledge.md +35 -31
- package/packs/onboarding.md +389 -298
- package/packs/safety.md +37 -29
- package/runtime-core/AGENTS.core.md +153 -144
- package/runtime-core/PROJECT_INDEX.md +136 -93
- package/runtime-core/RULE_PACKS.md +20 -19
- package/runtime-core/SESSION_HANDOFF.md +151 -150
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.
|
|
3
|
+
狀態:`v0.3.1` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -8,7 +8,7 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
|
8
8
|
|
|
9
9
|
它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
|
|
10
10
|
|
|
11
|
-
> 🚀 **第一次用?你不需要先讀本 README
|
|
11
|
+
> 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
|
|
12
12
|
>
|
|
13
13
|
> 安裝完成後,在 AI 對話中講一句:
|
|
14
14
|
>
|
|
@@ -16,9 +16,9 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
|
16
16
|
> Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
17
17
|
> ```
|
|
18
18
|
>
|
|
19
|
-
> AI
|
|
19
|
+
> AI 會自動引導你選擇使用情境(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
|
|
20
20
|
|
|
21
|
-
想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60
|
|
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
22
|
|
|
23
23
|
## 它解決甚麼問題
|
|
24
24
|
|
|
@@ -29,7 +29,7 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
|
29
29
|
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
30
30
|
| 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
31
31
|
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
|
|
32
|
-
| AI 可能亂改、亂刪或誤發佈 |
|
|
32
|
+
| AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
33
33
|
|
|
34
34
|
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
35
35
|
|
|
@@ -51,15 +51,15 @@ npx @adamchanadam/agent-handoff-kit init
|
|
|
51
51
|
|
|
52
52
|
打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
**第一次用(新手引導句)**:
|
|
55
55
|
|
|
56
56
|
```text
|
|
57
57
|
Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
AI
|
|
60
|
+
AI 會自動載入新手引導,帶你選擇使用情境(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),再一步一步陪你做第一個任務。
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
**之後熟悉 Handoff Kit 後,可改用更直接的開工句**:
|
|
63
63
|
|
|
64
64
|
```text
|
|
65
65
|
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
@@ -82,13 +82,13 @@ wrap up
|
|
|
82
82
|
handoff
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
AI
|
|
85
|
+
AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字明確標示出來,方便完整複製。安裝後也會有一個更直覺的副本檔:
|
|
86
86
|
|
|
87
87
|
```text
|
|
88
88
|
START_NEXT_SESSION_PROMPT.txt
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
|
|
91
|
+
這個檔案只是方便你複製下次開工提示;真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
|
|
92
92
|
|
|
93
93
|
## 檢查是否安裝完整
|
|
94
94
|
|
|
@@ -98,7 +98,7 @@ START_NEXT_SESSION_PROMPT.txt
|
|
|
98
98
|
npx @adamchanadam/agent-handoff-kit doctor
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
-
看到 `status: passed
|
|
101
|
+
看到 `status: passed`,代表必要文件、基本結構與下次開工提示副本的一致性都通過檢查。
|
|
102
102
|
|
|
103
103
|
這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
|
|
104
104
|
|
|
@@ -125,59 +125,68 @@ dev/rules/*.md
|
|
|
125
125
|
| `AGENTS.md` | AI 開工時最先讀的入口文件。 |
|
|
126
126
|
| `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
|
|
127
127
|
| `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
|
|
128
|
-
| `START_NEXT_SESSION_PROMPT.txt` |
|
|
128
|
+
| `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由交接文件自動產生。 |
|
|
129
129
|
| `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
|
|
130
|
-
| `dev/SESSION_LOG.md` |
|
|
130
|
+
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。長期使用後舊條目會自動整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
|
|
131
131
|
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
132
|
-
| `dev/PROJECT_DECISIONS.md` |
|
|
132
|
+
| `dev/PROJECT_DECISIONS.md` | 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時自動維護,日常開工不需要讀。當你問「之前為何這樣做」時,AI 會自己從這裡找答案。 |
|
|
133
133
|
| `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
|
|
134
134
|
| `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
|
|
135
|
-
| `dev/rules/*.md` |
|
|
135
|
+
| `dev/rules/*.md` | 按任務載入的工作規則,共十份:安全、寫代碼、寫作、研究、AI 治理、發佈、知識整理、溝通、新手引導、外部工具治理。 |
|
|
136
136
|
|
|
137
137
|
你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
|
|
138
138
|
|
|
139
|
-
## SESSION_LOG
|
|
139
|
+
## SESSION_LOG 的自動整理機制
|
|
140
140
|
|
|
141
|
-
長期使用後,`dev/SESSION_LOG.md`
|
|
141
|
+
長期使用後,`dev/SESSION_LOG.md` 不會無止境膨脹。每次你講「收工」,AI 會自動整理:
|
|
142
142
|
|
|
143
|
-
-
|
|
144
|
-
-
|
|
145
|
-
-
|
|
143
|
+
- 最新三條對話紀錄保留完整內容,作為意外時的後備。
|
|
144
|
+
- 之後的條目,如核心內容已被交接文件吸收,會自動縮成一行短索引(日期 + 標題 + 對應資料來源)。
|
|
145
|
+
- 累積到第十一條開始,會自動封存到 `dev/SESSION_LOG_archive/` 資料夾;主檔末尾留一份封存索引,方便日後追溯。
|
|
146
146
|
|
|
147
|
-
接力責任由 `dev/SESSION_HANDOFF.md`
|
|
147
|
+
接力責任由 `dev/SESSION_HANDOFF.md` 承擔;`dev/SESSION_LOG.md` 屬審計與追溯用的舊資料。**新對話開工不需要讀完整紀錄**,只需要讀 `AGENTS.md` 加 `dev/SESSION_HANDOFF.md` 加索引文件就足夠接力。
|
|
148
148
|
|
|
149
|
-
|
|
149
|
+
所以你的電腦中的 `dev/` 資料夾不會被對話紀錄不停撐大,也不需要你手動清理。如主檔意外膨脹,`doctor` 會在輸出顯示提醒,請 AI 下次收工時整理;這只是提醒,不會令 `doctor` 失敗,也不阻擋安裝。
|
|
150
150
|
|
|
151
151
|
## 項目決策日誌
|
|
152
152
|
|
|
153
|
-
`dev/PROJECT_DECISIONS.md`
|
|
153
|
+
`dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時自動維護,日常開工不需要讀本檔;當你問「之前為何這樣做」時,AI 會自己從這裡找答案。
|
|
154
154
|
|
|
155
|
-
|
|
156
|
-
- 長期持續演進項目:AI 會在每次收工時自動 maintain
|
|
157
|
-
- HANDOFF 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 條時,AI 自動 split 舊條目至此
|
|
158
|
-
- 觀察到任務需求演進、架構取捨、累積學習 pattern 時,AI 主動 append entry
|
|
155
|
+
短期單一任務的項目,本檔幾乎保持空白,你不需要維護。長期持續演進的項目,AI 會自動累積以下四類紀錄:
|
|
159
156
|
|
|
160
|
-
|
|
157
|
+
- **長期演進** —— 任務需求隨時間的變化
|
|
158
|
+
- **決策封存** —— 累積決策的歷史紀錄
|
|
159
|
+
- **架構取捨** —— 主要設計選擇與原因
|
|
160
|
+
- **學習觀察** —— 多次對話累積的觀察與心得
|
|
161
161
|
|
|
162
|
-
|
|
163
|
-
- **Decisions Archive** —— 累積決策嘅冷封存
|
|
164
|
-
- **Architecture Choices** —— 主要架構取捨同 rationale
|
|
165
|
-
- **Insights & Learnings** —— 多 session 累積嘅學習觀察
|
|
162
|
+
當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
|
|
166
163
|
|
|
167
|
-
|
|
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 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
|
|
168
177
|
|
|
169
178
|
## 工作模式
|
|
170
179
|
|
|
171
|
-
|
|
180
|
+
你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
|
|
172
181
|
|
|
173
182
|
| 你的任務 | AI 應使用的工作規則 |
|
|
174
183
|
|---|---|
|
|
175
|
-
| 寫或改代碼、檢查錯誤、執行測試 |
|
|
176
|
-
| 查資料、比較來源、整理證據 |
|
|
177
|
-
| 改 README、寫說明、整理文案 |
|
|
178
|
-
| 整理 Notion、Google Drive 或知識庫 |
|
|
179
|
-
| 準備發佈說明 |
|
|
180
|
-
| 改規則、改流程、整理交接 |
|
|
184
|
+
| 寫或改代碼、檢查錯誤、執行測試 | 寫代碼規則;涉及刪除、覆寫、Git、套件管理或外部服務時,再讀安全規則 |
|
|
185
|
+
| 查資料、比較來源、整理證據 | 研究規則 |
|
|
186
|
+
| 改 README、寫說明、整理文案 | 寫作規則,通常再加溝通規則 |
|
|
187
|
+
| 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
|
|
188
|
+
| 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
|
|
189
|
+
| 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
|
|
181
190
|
|
|
182
191
|
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
183
192
|
|
|
@@ -189,11 +198,11 @@ dev/rules/*.md
|
|
|
189
198
|
- 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
|
|
190
199
|
- 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
|
|
191
200
|
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
192
|
-
-
|
|
201
|
+
- 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
|
|
193
202
|
|
|
194
203
|
## 已安裝舊版,或已有 AI 記憶文件?
|
|
195
204
|
|
|
196
|
-
如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI
|
|
205
|
+
如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,可先用最新版安裝工具預演會發生甚麼:
|
|
197
206
|
|
|
198
207
|
```bash
|
|
199
208
|
npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
@@ -205,65 +214,33 @@ npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
|
205
214
|
npx @adamchanadam/agent-handoff-kit@latest upgrade
|
|
206
215
|
```
|
|
207
216
|
|
|
208
|
-
`@latest` 代表使用 npm
|
|
217
|
+
`@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 則負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
|
|
209
218
|
|
|
210
|
-
|
|
219
|
+
看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
|
|
211
220
|
|
|
212
221
|
## 版本提示
|
|
213
222
|
|
|
214
|
-
|
|
223
|
+
安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
215
224
|
|
|
216
|
-
|
|
225
|
+
若你不想檢查更新,可設定環境變數:
|
|
217
226
|
|
|
218
227
|
```bash
|
|
219
228
|
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
220
229
|
```
|
|
221
230
|
|
|
222
|
-
## 語言使用
|
|
223
|
-
|
|
224
|
-
安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
|
|
225
|
-
|
|
226
|
-
你的交接筆記、任務說明和文件內容可以使用中文或其他語言。需要機器檢查的結構,會由模板內的 `ack:section:*` 與 `ack:field:*` 標記承擔。
|
|
227
|
-
|
|
228
|
-
## 原始碼倉庫驗收
|
|
229
|
-
|
|
230
|
-
以下指令供維護者檢查原始碼倉庫,不是一般用戶日常必須執行的步驟:
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
npm run qa:prototype
|
|
234
|
-
npm run qa:packs
|
|
235
|
-
npm run qa:upgrade
|
|
236
|
-
npm run qa:release
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
這些檢查涵蓋安裝、`doctor`、套件預演、過時字串、公開輸出污染標記、工作規則路由、升級安全,以及從安裝到收工再到下一次開工的流程模擬。
|
|
240
|
-
|
|
241
|
-
## 套件邊界
|
|
242
|
-
|
|
243
|
-
npm package 只包含安裝所需內容:
|
|
244
|
-
|
|
245
|
-
- `bin/`
|
|
246
|
-
- `runtime-core/`
|
|
247
|
-
- `packs/`
|
|
248
|
-
- `README.md`
|
|
249
|
-
- `LICENSE`
|
|
250
|
-
- `package.json`
|
|
251
|
-
|
|
252
|
-
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/` 是原始碼倉庫資產,不會安裝到你的專案。
|
|
253
|
-
|
|
254
231
|
## 配合 Adam-AI-Instructions 使用
|
|
255
232
|
|
|
256
|
-
Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions)
|
|
233
|
+
Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用效果最好。兩者分工互補,不重疊:
|
|
257
234
|
|
|
258
|
-
- **Adam-AI-Instructions** 負責 AI
|
|
259
|
-
- **Agent Handoff Kit** 負責 AI
|
|
235
|
+
- **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
|
|
236
|
+
- **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
|
|
260
237
|
|
|
261
|
-
到該 repo
|
|
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` 安裝本工具。兩者配合就能涵蓋「單次對話質素」加「跨對話接力」兩個維度。
|
|
262
239
|
|
|
263
240
|
## 目前限制
|
|
264
241
|
|
|
265
|
-
- `v0.
|
|
266
|
-
-
|
|
267
|
-
-
|
|
242
|
+
- `v0.3.0` 是 GitHub 與 npm 同步發佈版本。
|
|
243
|
+
- 這是早期可用版本,仍在持續完善中。
|
|
244
|
+
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
268
245
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
269
246
|
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|