@adamchanadam/agent-handoff-kit 0.3.29 → 0.3.31
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 +95 -237
- package/bin/agent-handoff-kit.mjs +1651 -1634
- package/package.json +19 -29
- package/packs/agent-governance.md +2 -0
- package/packs/safety.md +13 -12
- package/packs/writing.md +2 -0
- package/runtime-core/AGENTS.core.md +96 -92
package/README.md
CHANGED
|
@@ -1,129 +1,71 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.31`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
|
|
7
|
+
</p>
|
|
6
8
|
|
|
7
9
|
Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
8
10
|
|
|
9
11
|
它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
>
|
|
13
|
-
> 最簡單做法:在你要安裝或升級的資料夾打開能讀寫本機資料夾的 AI agent,貼上:
|
|
14
|
-
>
|
|
15
|
-
> ```text
|
|
16
|
-
> 請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
|
|
17
|
-
> ```
|
|
18
|
-
>
|
|
19
|
-
> AI 會先顯示目前資料夾並請你確認;未確認前不應安裝或升級。
|
|
20
|
-
>
|
|
21
|
-
> 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
|
|
22
|
-
>
|
|
23
|
-
> ```text
|
|
24
|
-
> Start Agent Handoff
|
|
25
|
-
> ```
|
|
26
|
-
>
|
|
27
|
-
> 中文可說「開工」。
|
|
28
|
-
>
|
|
29
|
-
> 只有當 AI 還未指向你的專案資料夾時,才使用帶路徑啟動句:
|
|
30
|
-
>
|
|
31
|
-
> ```text
|
|
32
|
-
> Work in <你的資料夾>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.
|
|
33
|
-
> ```
|
|
34
|
-
>
|
|
35
|
-
> AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
|
|
36
|
-
|
|
37
|
-
想先看非技術版介紹,可打開 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) —— 三個日常情境的完整流程示範。若想讓 AI 代你判斷安裝或升級,給 AI 讀 [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html)。本 README 則保留安裝、日常使用與限制。
|
|
38
|
-
|
|
39
|
-
## 它解決甚麼問題
|
|
13
|
+
📌 使用時,你只需要說明目的;確認資料夾、判斷安裝或升級、執行指令和檢查結果,交給能讀寫本機資料夾的 AI 處理。
|
|
40
14
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
44
|
-
|---|---|
|
|
45
|
-
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
46
|
-
| 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
47
|
-
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
|
|
48
|
-
| AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
49
|
-
|
|
50
|
-
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
51
|
-
|
|
52
|
-
## 三步上手
|
|
53
|
-
|
|
54
|
-

|
|
55
|
-
|
|
56
|
-
這張圖是給第一次使用的人看的流程摘要:先在目標資料夾讓 AI 讀安裝指令頁,或手動執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init`;安裝完成後,在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」。AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
|
|
15
|
+
## 🚀 三步上手
|
|
57
16
|
|
|
58
|
-
|
|
17
|
+
第一次用,不需要先讀完整 README,也不需要研究終端機指令。只做三件事:
|
|
59
18
|
|
|
60
|
-
Agent Handoff Kit
|
|
61
|
-
|
|
62
|
-
它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
|
|
19
|
+
1. 在你想使用 Agent Handoff Kit 的資料夾打開 AI,貼上這句話:
|
|
63
20
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
```text
|
|
69
|
-
請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
AI 應先顯示目前資料夾的絕對路徑,問你是否就是要安裝或升級的資料夾;確認後才判斷要執行 `init`、`upgrade --dry-run`、`upgrade` 或停在衝突狀態。
|
|
73
|
-
|
|
74
|
-
如你想手動安裝,才用下面的終端機指令。
|
|
75
|
-
|
|
76
|
-
在你的專案資料夾打開終端機,執行:
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
npx --yes @adamchanadam/agent-handoff-kit@latest init
|
|
80
|
-
```
|
|
21
|
+
```text
|
|
22
|
+
請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
|
|
23
|
+
```
|
|
81
24
|
|
|
82
|
-
|
|
25
|
+
你也可以先打開 [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html) 看看 AI 會照甚麼步驟處理。
|
|
83
26
|
|
|
84
|
-
|
|
27
|
+
2. 安裝完成後,對 AI 說 `Start Agent Handoff` 或「開工」。
|
|
28
|
+
3. 完成本輪工作後,對 AI 說「收工」。
|
|
85
29
|
|
|
86
|
-
|
|
30
|
+
🔎 你不用判斷安裝、升級、檢查或檔案結構。AI 會先說明它看到的資料夾、風險與下一步;需要你確認時才停下來。
|
|
87
31
|
|
|
88
|
-
|
|
32
|
+
已裝過舊版,或資料夾裡已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,也用同一句交給 AI 判斷。AI 會先檢查,不會靜默覆寫。
|
|
89
33
|
|
|
90
|
-
|
|
34
|
+
想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)。想看完整操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)。想了解它在本機 Agentic AI 工作系統中的位置,可看 [`local-agentic-ai-workflow-case-study.html`](https://adamchanadam.github.io/agent-handoff-kit/local-agentic-ai-workflow-case-study.html)。
|
|
91
35
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
如果你不用 AI 代判斷安裝或升級,才直接使用下表指令。
|
|
95
|
-
|
|
96
|
-
| 你現在的狀態 | 手動指令 |
|
|
97
|
-
|---|---|
|
|
98
|
-
| 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
|
|
99
|
-
| 已安裝舊版,或已有 AI 記憶文件 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade` |
|
|
100
|
-
| 不確定是否安裝完整,或升級後想檢查 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
|
|
36
|
+
## 🧭 這個 repo 怎樣讀
|
|
101
37
|
|
|
102
|
-
|
|
38
|
+
如果你只是想使用 Agent Handoff Kit,只需要看四個入口:
|
|
103
39
|
|
|
104
|
-
|
|
40
|
+
| 入口 | 用途 |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `README.md` | 正式用途、安裝路徑、限制與安全邊界。 |
|
|
43
|
+
| [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) | 非技術版 60 秒入門與宣傳動畫。 |
|
|
44
|
+
| [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) | 三個實操情景,示範開工、工作、收工。 |
|
|
45
|
+
| [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html) | 給 AI 讀的安裝與升級指令頁。 |
|
|
105
46
|
|
|
106
|
-
|
|
47
|
+
這個公開 repo 是用戶流通版,保留使用、安裝、入門、GitHub Pages 與 npm 執行所需內容;內部 release QA、升級夾具和候選審核材料留在開發真源,不放入公開流通版。
|
|
107
48
|
|
|
108
|
-
|
|
109
|
-
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
110
|
-
```
|
|
49
|
+
## 🔎 它解決甚麼問題
|
|
111
50
|
|
|
112
|
-
|
|
51
|
+
用 AI 做長期項目,常見四個問題:
|
|
113
52
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
53
|
+
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
54
|
+
|---|---|
|
|
55
|
+
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
56
|
+
| 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
57
|
+
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
|
|
58
|
+
| AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
117
59
|
|
|
118
|
-
|
|
60
|
+
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
119
61
|
|
|
120
|
-
|
|
62
|
+
## 🧰 適用工具
|
|
121
63
|
|
|
122
|
-
|
|
64
|
+
Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity,或其他具備本機工作區讀寫能力的工具。
|
|
123
65
|
|
|
124
|
-
|
|
66
|
+
它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
|
|
125
67
|
|
|
126
|
-
|
|
68
|
+
## 🟢 開工
|
|
127
69
|
|
|
128
70
|
打開能讀寫本機專案資料夾的 AI agent。
|
|
129
71
|
|
|
@@ -147,7 +89,7 @@ Work in <你的專案資料夾>. Read AGENTS.md first, then Start Agent Handoff.
|
|
|
147
89
|
|
|
148
90
|
然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
|
|
149
91
|
|
|
150
|
-
|
|
92
|
+
## 💾 收工
|
|
151
93
|
|
|
152
94
|
本輪工作完成、準備結束時,只需輸入:
|
|
153
95
|
|
|
@@ -173,144 +115,69 @@ START_NEXT_SESSION_PROMPT.txt
|
|
|
173
115
|
|
|
174
116
|
這個檔案保存下一次真正要讀的開工內容。你下次仍只需說 `Start Agent Handoff` 或「開工」;若 AI 尚未指向專案資料夾,才使用帶路徑啟動句。真正的權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的「下次開工提示」段。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重新產生副本。
|
|
175
117
|
|
|
176
|
-
##
|
|
118
|
+
## 🩺 不確定狀態時
|
|
177
119
|
|
|
178
|
-
|
|
120
|
+
如你不確定目前資料夾是否安裝完整、是否需要升級,或剛升級後想確認狀態,直接叫 AI:
|
|
179
121
|
|
|
180
|
-
```
|
|
181
|
-
|
|
122
|
+
```text
|
|
123
|
+
請讀取頁頂的安裝頁,幫我檢查這個資料夾的 Agent Handoff Kit 狀態。
|
|
182
124
|
```
|
|
183
125
|
|
|
184
|
-
|
|
126
|
+
AI 會處理檢查,不會把「檢查通過」誤當成已理解你的專案。真正開始工作前,仍要對 AI 說 `Start Agent Handoff` 或「開工」。
|
|
127
|
+
|
|
128
|
+
## 🗂️ AI 會替你維護甚麼
|
|
185
129
|
|
|
186
|
-
|
|
130
|
+
安裝後,Agent Handoff Kit 會在你的專案中放入一組交接文件。你不需要逐一閱讀,也不需要手動維護。
|
|
187
131
|
|
|
188
|
-
|
|
132
|
+
- **開工入口**:讓不同 AI 工具找到同一套開工方式,例如 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 和 `START_NEXT_SESSION_PROMPT.txt`。
|
|
133
|
+
- **目前狀態**:保存做到哪裡、下一步、風險和檢查結果,例如 `dev/SESSION_HANDOFF.md`。
|
|
134
|
+
- **追溯紀錄**:保存近期做過的事;長期使用後,AI 會自動整理,避免紀錄無止境膨脹。
|
|
135
|
+
- **項目索引與決策**:記錄重要文件、外部來源、同步責任和長期決策,方便你日後問「之前為何這樣做」。
|
|
136
|
+
- **工作規則**:AI 會按你的任務自己載入需要的規則;你不用記規則名稱。
|
|
189
137
|
|
|
190
|
-
|
|
138
|
+
## 🧭 AI 工作規則怎樣運作
|
|
139
|
+
|
|
140
|
+
你不需要記住任何規則檔名。Agent Handoff Kit 會讓 AI 先判斷你現在要做甚麼,再只載入需要的工作規則。
|
|
141
|
+
|
|
142
|
+
| 你要做的事 | AI 會套用的規則 |
|
|
143
|
+
|---|---|
|
|
144
|
+
| 寫程式 / 修錯誤 | 先讀項目索引、相關檔案,再改動和測試。 |
|
|
145
|
+
| 寫文章 / README / 社交帖文 | 先確認讀者、目的、語氣和發布位置。 |
|
|
146
|
+
| 查資料 / 比較工具 | 分清已驗證事實、來源摘要和 AI 推論。 |
|
|
147
|
+
| 刪檔 / Git / 發佈 / npm | 高風險操作必須先說明影響,並等你確認。 |
|
|
148
|
+
| Notion / Google Drive 等外部工具 | 先確認是否已連接;機密不寫入項目文件。 |
|
|
149
|
+
|
|
150
|
+
你只要用日常話說目的,例如「幫我改 README」、「幫我查這個工具是否適合」、「把這份文件接入 Agent Handoff Kit」。AI 會自己判斷要用哪些規則。
|
|
151
|
+
|
|
152
|
+
想加入自己的長期規則,也不用手改規則檔。你可以直接說:
|
|
191
153
|
|
|
192
154
|
```text
|
|
193
|
-
|
|
194
|
-
CLAUDE.md
|
|
195
|
-
GEMINI.md
|
|
196
|
-
START_NEXT_SESSION_PROMPT.txt
|
|
197
|
-
dev/SESSION_HANDOFF.md
|
|
198
|
-
dev/SESSION_LOG.md
|
|
199
|
-
dev/PROJECT_INDEX.md
|
|
200
|
-
dev/PROJECT_DECISIONS.md
|
|
201
|
-
dev/DOC_SYNC_REGISTRY.md
|
|
202
|
-
dev/RULE_PACKS.md
|
|
203
|
-
dev/rules/*.md
|
|
155
|
+
以後寫公開中文文件時,請用繁體中文書面語,避免半中半英。請把這條規則接入 Agent Handoff Kit。
|
|
204
156
|
```
|
|
205
157
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
|
213
|
-
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。每次收工會先做維護觸發檢查;長期使用後,命中條件時舊條目會整理入封存資料夾,主檔保持簡短。日常使用不需要打開本檔,做審計或追溯時才看。 |
|
|
214
|
-
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
215
|
-
| `dev/PROJECT_DECISIONS.md` | 保存項目的長期演進、決策、架構取捨與學習觀察。AI 在每次收工時檢查是否需要維護,重大決策可即時寫入;日常開工不需要讀。當你問「之前為何這樣做」時,AI 會自己從這裡找答案。 |
|
|
216
|
-
| `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
|
|
217
|
-
| `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
|
|
218
|
-
| `dev/rules/*.md` | 按任務載入的工作規則,共十份:安全、寫代碼、寫作、研究、AI 治理、發佈、知識整理、溝通、新手引導、外部工具治理。 |
|
|
219
|
-
|
|
220
|
-
你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
|
|
221
|
-
|
|
222
|
-
## SESSION_LOG 的自動整理機制
|
|
223
|
-
|
|
224
|
-
長期使用後,`dev/SESSION_LOG.md` 不會無止境膨脹。每次你講「收工」,AI 會先做一次很短的維護觸發檢查;命中條件時才完整整理:
|
|
225
|
-
|
|
226
|
-
- 最新三條對話紀錄保留完整內容,作為意外時的後備。
|
|
227
|
-
- 之後的條目,如核心內容已被交接文件吸收,會在需要整理時縮成一行短索引(日期 + 標題 + 對應資料來源)。
|
|
228
|
-
- 累積到第十一條開始,會封存到 `dev/SESSION_LOG_archive/` 資料夾;主檔末尾留一份封存索引,方便日後追溯。
|
|
229
|
-
- 即使沒有明顯觸發,AI 也會每十次收工做一次完整維護兜底,避免長期使用後慢慢漏記。
|
|
230
|
-
|
|
231
|
-
接力責任由 `dev/SESSION_HANDOFF.md` 承擔;`dev/SESSION_LOG.md` 主要用來日後追溯。**新對話開工不需要讀完整紀錄**,只需要讀 `AGENTS.md`、`dev/SESSION_HANDOFF.md` 和索引文件,就足夠接力。
|
|
232
|
-
|
|
233
|
-
所以你的電腦中的 `dev/` 資料夾不會被對話紀錄不停撐大,也不需要你手動清理。如主檔意外膨脹,`doctor` 會在輸出顯示提醒,請 AI 下次收工時整理;這只是提醒,不會令 `doctor` 失敗,也不阻擋安裝。
|
|
234
|
-
|
|
235
|
-
## 項目決策日誌
|
|
236
|
-
|
|
237
|
-
`dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察。AI 每次收工都會檢查是否需要維護;遇到重大決策、方向轉變、架構取捨或重複出現的模式時才寫入,並且每十次收工做一次完整兜底。日常開工不需要讀本檔;當你問「之前為何這樣做」時,AI 會自己從這裡找答案。
|
|
238
|
-
|
|
239
|
-
短期單一任務的項目,本檔幾乎保持空白,你不需要維護。長期持續演進的項目,AI 會自動累積以下四類紀錄:
|
|
240
|
-
|
|
241
|
-
- **長期演進** —— 任務需求隨時間的變化
|
|
242
|
-
- **決策封存** —— 累積決策的歷史紀錄
|
|
243
|
-
- **架構取捨** —— 主要設計選擇與原因
|
|
244
|
-
- **學習觀察** —— 多次對話累積的觀察與心得
|
|
245
|
-
|
|
246
|
-
當交接文件中的決策清單累積到三十條以上,AI 會自動把較舊的條目搬入本檔,保持交接文件簡潔。
|
|
247
|
-
|
|
248
|
-
新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
|
|
249
|
-
|
|
250
|
-
## 把重要文件接入 Agent Handoff Kit
|
|
251
|
-
|
|
252
|
-
長期項目常會產生新文件,例如 stock list、production guide、runbook、workflow、checklist、研究真源或操作清單。文件本身做完,不代表下一個 AI 一定知道它存在,也不代表 AI 知道何時要讀、何時要更新、是否有另一份舊版真源。
|
|
253
|
-
|
|
254
|
-
常見有兩種用法。
|
|
255
|
-
|
|
256
|
-
第一種是指定一份文件,讓 AI 審核這份文件是否已接入治理層:
|
|
257
|
-
|
|
258
|
-
```text
|
|
259
|
-
把 docs/production-guide.md 接入 Agent Handoff Kit
|
|
260
|
-
治理打通 docs/production-guide.md
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
英文也可以說:
|
|
264
|
-
|
|
265
|
-
```text
|
|
266
|
-
bridge governance for docs/production-guide.md
|
|
267
|
-
connect this document to governance
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
AI 會檢查這份文件是否已接入項目記憶:文件本身是否講清楚用途與更新時機、`dev/PROJECT_INDEX.md` 是否登記它、`dev/DOC_SYNC_REGISTRY.md` 是否記下同類變更要同步哪裡、相關 workflow 是否會提醒更新它,以及 handoff / log 是否各自放在正確角色。
|
|
271
|
-
|
|
272
|
-
第二種是不指定單一文件,先掃描整個 repo 有沒有疑似未接合的重要文件:
|
|
273
|
-
|
|
274
|
-
```text
|
|
275
|
-
掃描未接入 Agent Handoff Kit 的重要文件
|
|
276
|
-
掃描 repo 有沒有未接合文件
|
|
277
|
-
scan for unbridged governance documents
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
這個掃描只列出候選與缺口,不會一邊掃描一邊自動修改。若你同意其中某個建議,可以再叫 AI 按建議補丁更新索引、同步登記或相關流程。若涉及刪除、改名、合併真源,AI 只會列出合併、引用或退役建議,等你明確確認。
|
|
281
|
-
|
|
282
|
-
這裡的「接入 Agent Handoff Kit」只指文件接合:避免重要文件變成下一個 AI 不知道要讀、不知道要更新的孤兒文件。若你想保存一條長期有效的做法,例如「以後都用這個 API 調用方式」、「把今次錯誤變成日後機制」、「這條工具使用方法要跨 session 生效」,請直接說「把這件事轉成長期機制」或「寫入長期治理」。AI 應把這類內容分流到規則包、項目索引、同步登記、決策紀錄或驗收檢查;不應只寫入 `dev/SESSION_LOG.md`、`dev/SESSION_HANDOFF.md` 或 `START_NEXT_SESSION_PROMPT.txt`。
|
|
283
|
-
|
|
284
|
-
## 外部工具治理
|
|
285
|
-
|
|
286
|
-
如你的項目涉及外部工具(例如 Notion、Google Drive、Slack、Linear、GitHub 等),Agent Handoff Kit 提供跨對話的治理紀律,確保 AI 在不同對話之間能穩定使用這些工具。
|
|
287
|
-
|
|
288
|
-
**登記表**:`dev/PROJECT_INDEX.md` 內設有「已裝外部工具」段,記錄項目已連接哪些外部工具。AI 在新對話開工時會自動讀取,了解能直接讀寫哪些資料來源。
|
|
289
|
-
|
|
290
|
-
**機密分離原則**:API key、token、密碼等任何敏感資料**永不寫入** `dev/` 內任何檔案。這類機密由你的 AI 工具或系統安全儲存管理,與本工具完全分離。`doctor` 會自動掃描,若發現任何疑似敏感資料寫入,會立即報錯。
|
|
291
|
-
|
|
292
|
-
**已裝才用**:如你已透過 Claude Desktop 等工具連接好外部服務,AI 會直接使用對應功能讀寫資料。如未連接,AI 會改為產生需要你手動同步的內容,並提示你下一步。
|
|
293
|
-
|
|
294
|
-
**失靈不亂修**:如外部工具中途認證失效,AI 會立即說明,不會嘗試自動修復;同時將狀況記錄入交接文件,方便你或下一個對話判斷處理。
|
|
295
|
-
|
|
296
|
-
## 工作模式
|
|
297
|
-
|
|
298
|
-
你不需要記規則名稱,只要描述任務。AI 會按任務切換工作模式。
|
|
299
|
-
|
|
300
|
-
| 你的任務 | AI 應使用的工作規則 |
|
|
158
|
+
AI 應先判斷這條規則應放在哪裡:是一次性備忘、下次交接、項目索引,還是長期工作規則。它不應把所有東西都塞進同一個檔案。
|
|
159
|
+
|
|
160
|
+
## 💬 你可以怎樣叫 AI
|
|
161
|
+
|
|
162
|
+
你只要用自然語言講目的,AI 會自己判斷要讀哪些交接文件、規則或索引。
|
|
163
|
+
|
|
164
|
+
| 你想做的事 | 可以這樣說 |
|
|
301
165
|
|---|---|
|
|
302
|
-
|
|
|
303
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
307
|
-
|
|
|
308
|
-
|
|
|
309
|
-
|
|
166
|
+
| 接上上次工作 | `Start Agent Handoff` 或「開工」 |
|
|
167
|
+
| 結束本輪工作 | 「收工」 |
|
|
168
|
+
| 讓新文件不變成孤兒 | 「把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。」 |
|
|
169
|
+
| 掃描可能被遺漏的重要文件 | 「掃描未接入 Agent Handoff Kit 的重要文件。」 |
|
|
170
|
+
| 把錯誤經驗保存成日後機制 | 「把今次錯誤變成日後機制,寫入長期治理。」 |
|
|
171
|
+
| 讓 API / 工具用法之後都生效 | 「以後都用這個 API 調用方式,跨 session 生效。」 |
|
|
172
|
+
| 使用外部工具,例如 Notion、Google Drive、GitHub | 「這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。」 |
|
|
173
|
+
|
|
174
|
+
這個掃描只列出候選與缺口,不會自動修改;是否接入、合併或退役由你確認。
|
|
175
|
+
|
|
176
|
+
長期機制不應只寫入 `dev/SESSION_LOG.md`,也不只留在 session log 或 handoff;AI 應放入合適的長期治理位置。
|
|
310
177
|
|
|
311
|
-
|
|
178
|
+
如涉及刪除、改名、合併真源、發佈、上傳或權限變更,AI 應先說明影響並等你確認。
|
|
312
179
|
|
|
313
|
-
## 安全護欄
|
|
180
|
+
## 🛡️ 安全護欄
|
|
314
181
|
|
|
315
182
|
就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
|
|
316
183
|
|
|
@@ -320,29 +187,20 @@ scan for unbridged governance documents
|
|
|
320
187
|
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
321
188
|
- 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
|
|
322
189
|
|
|
323
|
-
##
|
|
324
|
-
|
|
325
|
-
安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
326
|
-
|
|
327
|
-
若你不想檢查更新,可設定環境變數:
|
|
328
|
-
|
|
329
|
-
```bash
|
|
330
|
-
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
## 配合 Adam-AI-Instructions 使用
|
|
190
|
+
## 🔗 可選配合:Adam-AI-Instructions
|
|
334
191
|
|
|
335
192
|
Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions) 配合使用。兩者分工互補,不重疊:
|
|
336
193
|
|
|
337
194
|
- **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
|
|
338
195
|
- **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
|
|
339
196
|
|
|
340
|
-
|
|
197
|
+
這是可選配合,不影響 Agent Handoff Kit 的安裝和日常使用。想使用時,到該倉庫選擇適合你 AI 工具的版本,貼入 AI 工具設定即可。
|
|
341
198
|
|
|
342
|
-
## 目前限制
|
|
199
|
+
## ⚠️ 目前限制
|
|
343
200
|
|
|
344
|
-
- 目前版本為 `v0.3.
|
|
201
|
+
- 目前版本為 `v0.3.31`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
345
202
|
- 這是早期可用版本,仍在持續完善中。
|
|
346
203
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
347
204
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
348
|
-
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
205
|
+
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
206
|
+
|