@adamchanadam/agent-handoff-kit 0.3.19 → 0.3.20

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,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:目前版本為 `v0.3.19`,已正式發佈。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.20`,已正式發佈。這是早期可用版本,仍在持續完善中。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
@@ -76,10 +76,28 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
76
76
  | 你現在的狀態 | 建議指令 |
77
77
  |---|---|
78
78
  | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
79
- | 不確定是否安裝完整 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
80
- | 已裝過舊版,想先看升級會改甚麼 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run` |
79
+ | 已安裝舊版,或已有 AI 記憶文件 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade` |
80
+ | 不確定是否安裝完整,或升級後想檢查 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
81
81
 
82
- 舊資料夾若原本已有 `AGENTS.md` 或其他 AI 記憶檔,`init` 會保留既有檔案。這時請先用 `upgrade --dry-run` 看清工具準備怎樣合併,不要手動覆寫。
82
+ ### 已安裝舊版,或已有 AI 記憶文件?
83
+
84
+ 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,不要重新 `init`,改用 `upgrade`。
85
+
86
+ 你可以先預演:
87
+
88
+ ```bash
89
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
90
+ ```
91
+
92
+ `dry-run` 只會預覽,不會完成升級,也不會寫入檔案。確認沒有問題後,才執行正式升級:
93
+
94
+ ```bash
95
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
96
+ ```
97
+
98
+ `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
99
+
100
+ 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
83
101
 
84
102
  即使目前資料夾已安裝舊版 Kit 文件,電腦也未必已經有可直接執行的 npm 工具。判斷點不是資料夾有沒有 `AGENTS.md` 或 `dev/`,而是你是否用上方 `npx --yes ... @latest` 路徑取得最新工具。裸寫不帶 `--yes` / `@latest` 的 `npx ... doctor` 不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
85
103
 
@@ -243,24 +261,6 @@ dev/rules/*.md
243
261
  - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
244
262
  - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
245
263
 
246
- ## 已安裝舊版,或已有 AI 記憶文件?
247
-
248
- 如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,可先用最新版安裝工具預演會發生甚麼:
249
-
250
- ```bash
251
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
252
- ```
253
-
254
- 確認沒有問題後,再執行:
255
-
256
- ```bash
257
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
258
- ```
259
-
260
- `@latest` 代表使用 npm 上最新版本的 Agent Handoff Kit。`upgrade` 負責把專案內已安裝的文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會回報衝突,不會靜默覆寫。
261
-
262
- 看到「衝突」不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把預演輸出貼給 AI,請它幫你判斷要保留、合併還是手動修改。
263
-
264
264
  ## 版本提示
265
265
 
266
266
  安裝工具執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與版本說明連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
@@ -282,7 +282,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
282
282
 
283
283
  ## 目前限制
284
284
 
285
- - 目前版本為 `v0.3.19`,npm registry `latest` 已對齊此版本。
285
+ - 目前版本為 `v0.3.20`,npm registry `latest` 已對齊此版本。
286
286
  - 這是早期可用版本,仍在持續完善中。
287
287
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
288
288
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -2148,10 +2148,10 @@ Commands:
2148
2148
  upgrade Preserve existing files; merge safe core updates or report conflicts.
2149
2149
  doctor Check required installed files.
2150
2150
 
2151
- 中文速讀:
2152
- ✅ 第一次用:先在項目資料夾執行 init。
2153
- 🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
2154
- 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2151
+ 中文速讀:
2152
+ ✅ 第一次用:先在項目資料夾執行 init。
2153
+ 🔄 已裝過:執行 upgrade;若想先預覽,才加 --dry-run。
2154
+ 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2155
2155
 
2156
2156
  安裝之後:
2157
2157
  不要把顯示出來的 Start Agent Handoff 或 "Work in ..." 文字輸入終端機。
@@ -2168,22 +2168,26 @@ Commands:
2168
2168
  會先確認是否指本工具交接。
2169
2169
 
2170
2170
  終端機範例:
2171
- npx --yes @adamchanadam/agent-handoff-kit@latest init
2172
- npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2173
- npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
2171
+ npx --yes @adamchanadam/agent-handoff-kit@latest init
2172
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade
2173
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2174
+
2175
+ 升級前如想先看會改甚麼,才用預演:
2176
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
2177
+ --dry-run 只預覽、不寫入;它不是正式升級完成。
2174
2178
 
2175
2179
  以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
2176
2180
  不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
2177
2181
 
2178
2182
  即使資料夾已有 AGENTS.md 或 dev/,電腦也未必已經有可直接執行的工具;
2179
- npx --yes 只是先取得工具,然後才執行你指定的 init / doctor / upgrade。
2183
+ npx --yes 只是先取得工具,然後才執行你指定的 init / upgrade / doctor。
2180
2184
 
2181
2185
  放在 package 名稱前的 --yes 只讓 npm 先取得執行工具,避免額外出現
2182
2186
  "Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
2183
2187
  `);
2184
2188
  console.log(`📦 版本:v${version}`);
2185
2189
  console.log(`🛠️ 模式:help ready`);
2186
- console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2190
+ console.log(`🚀 下一步:新項目先執行 init;舊項目執行 upgrade;只想檢查才執行 doctor。`);
2187
2191
  }
2188
2192
 
2189
2193
  function startupPathBootstrapPrompt(root) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.19",
3
+ "version": "0.3.20",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {