@adamchanadam/agent-handoff-kit 0.3.8 → 0.3.10

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.
@@ -193,7 +193,7 @@ const requiredAnchors = [
193
193
  "明確 onboarding signal keywords",
194
194
  "5-step walk-through pattern",
195
195
  "Application Scenario Library",
196
- "Scenario A. 寫 / 改代碼項目",
196
+ "Scenario A. 建構系統 / 工具 / 平台 / 網站或應用",
197
197
  "Scenario B. 整理研究資料",
198
198
  "Scenario C. 整理電腦檔案",
199
199
  "Scenario D. 學寫代碼",
@@ -525,13 +525,13 @@ async function runInstall(command, root, options, version) {
525
525
  }
526
526
 
527
527
  printPlan(command, root, mode, plan, version, options.dryRun);
528
-
529
- if (options.dryRun) {
530
- console.log("\ndry-run: no files written");
531
- printDryRunExplanation(plan);
532
- if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
533
- return;
534
- }
528
+
529
+ if (options.dryRun) {
530
+ console.log("\ndry-run: no files written");
531
+ printDryRunExplanation(command, mode, plan);
532
+ if (plan.some((item) => item.action === "conflict")) process.exitCode = 1;
533
+ return;
534
+ }
535
535
 
536
536
  if (!options.yes) {
537
537
  const ok = await confirmWrite();
@@ -548,12 +548,14 @@ async function runInstall(command, root, options, version) {
548
548
  const migrationDir = path.join(root, "dev/governance_migrations", stamp);
549
549
  const backupDir = path.join(migrationDir, "backup");
550
550
 
551
- for (const item of plan) {
552
- if (item.action !== "create") continue;
553
- await mkdir(path.dirname(item.targetAbs), { recursive: true });
554
- await copyFile(item.sourceAbs, item.targetAbs);
555
- created.push(item.targetRel);
556
- }
551
+ for (const item of plan) {
552
+ if (item.action !== "create") continue;
553
+ await mkdir(path.dirname(item.targetAbs), { recursive: true });
554
+ await copyFile(item.sourceAbs, item.targetAbs);
555
+ created.push(item.targetRel);
556
+ }
557
+
558
+ await hydrateInitialOpeningPrompt(root, created);
557
559
 
558
560
  for (const item of plan) {
559
561
  if (item.action !== "merge") continue;
@@ -630,23 +632,23 @@ async function runInstall(command, root, options, version) {
630
632
  // R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
631
633
  // R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
632
634
  // actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
633
- if (command === "upgrade") {
634
- await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
635
- } else {
636
- printInstallNextSteps(root, conflicts.length);
637
- }
635
+ if (command === "upgrade") {
636
+ await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
637
+ } else {
638
+ printInstallNextSteps(root, conflicts.length, mode, skippedCount);
639
+ }
638
640
 
639
641
  // R-024 upgrade.done self-check: after substantive upgrade writes, run doctor automatically.
640
642
  // The user must see whether the merged state actually reaches a clean health state.
641
643
  if (command === "upgrade" && conflicts.length === 0) {
642
644
  console.log("");
643
645
  console.log("------------------------------------------------------------");
644
- console.log("🩺 upgrade self-check: running doctor against the upgraded root");
646
+ console.log("🩺 升級後自動檢查:正在檢查升級後的資料夾");
645
647
  console.log("------------------------------------------------------------");
646
- const doctorStatus = await runDoctor(root, version, { silentCard: true });
648
+ const doctorStatus = await runDoctor(root, version, { silentCard: true, context: "upgrade-self-check" });
647
649
  if (doctorStatus !== "passed") {
648
650
  console.log("");
649
- console.log("⚠️ upgrade self-check did not pass; see doctor output above.");
651
+ console.log("⚠️ 升級後自動檢查未通過;請看上方檢查輸出。");
650
652
  console.log("📋 下一步:把上面 doctor 輸出貼給 AI,請它先按提示修補後再宣稱 upgrade 完成。");
651
653
  process.exitCode = 1;
652
654
  } else {
@@ -672,15 +674,17 @@ async function runDoctor(root, version, options = {}) {
672
674
  console.log(`${row.ok ? "ok" : "missing"} ${row.target}`);
673
675
  }
674
676
 
675
- if (missing.length > 0) {
676
- printDoctorSummary(version, root, "needs-fix", {
677
- checked: rows.length,
678
- failedKind: "missing files",
679
- failedCount: missing.length,
680
- nextStep: "先確認你是否在正確專案資料夾;如是,執行 init 或 upgrade 補回缺少檔案。"
681
- });
682
- process.exitCode = 1;
683
- return "failed";
677
+ if (missing.length > 0) {
678
+ printDoctorSummary(version, root, "needs-fix", {
679
+ checked: rows.length,
680
+ failedKind: "missing files",
681
+ failedCount: missing.length,
682
+ nextStep: missing.length === rows.length
683
+ ? "這個資料夾未安裝 Kit。若這就是你的項目資料夾,請執行:npx --yes @adamchanadam/agent-handoff-kit@latest init"
684
+ : "這個資料夾只裝了一部分 Kit 檔案。請先確認路徑;如路徑正確,執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run"
685
+ });
686
+ process.exitCode = 1;
687
+ return "failed";
684
688
  }
685
689
 
686
690
  const anchorRows = await checkRequiredAnchors(root);
@@ -691,12 +695,12 @@ async function runDoctor(root, version, options = {}) {
691
695
  }
692
696
 
693
697
  if (anchorFailures.length > 0) {
694
- printDoctorSummary(version, root, "needs-fix", {
695
- checked: rows.length + anchorRows.length,
696
- failedKind: "anchor checks",
697
- failedCount: anchorFailures.length,
698
- nextStep: "執行 upgrade --dry-run 查看可否安全補齊;不要手動覆寫既有檔案。"
699
- });
698
+ printDoctorSummary(version, root, "needs-fix", {
699
+ checked: rows.length + anchorRows.length,
700
+ failedKind: "anchor checks",
701
+ failedCount: anchorFailures.length,
702
+ nextStep: "有入口檔存在,但缺少 Kit 需要的橋接段落。請執行:npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run;不要手動覆寫既有檔案。"
703
+ });
700
704
  process.exitCode = 1;
701
705
  return "failed";
702
706
  }
@@ -768,9 +772,10 @@ async function runDoctor(root, version, options = {}) {
768
772
  printVersionAlignment(versionAlignment);
769
773
  const versionNextStep = getVersionAlignmentNextStep(versionAlignment);
770
774
  const lastCloseout = await assessLastCloseout(root);
771
- printLastCloseout(lastCloseout);
772
- const projectAge = await assessProjectAge(root);
773
- printProjectAge(projectAge);
775
+ printLastCloseout(lastCloseout);
776
+ const projectAge = await assessProjectAge(root);
777
+ printProjectAge(projectAge);
778
+ const onboardingNextStep = options.context === "upgrade-self-check" ? null : getFirstUseNextStep(root, lastCloseout);
774
779
 
775
780
  const overallHealthy = credentialResult.ok;
776
781
  printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
@@ -780,11 +785,16 @@ async function runDoctor(root, version, options = {}) {
780
785
  nextStep: !credentialResult.ok
781
786
  ? "立即從相關檔案 redact credential value + rotate 已泄露 token;credential 應該由 AI 工具自身 secure storage 管理,永不寫入 dev/* 任何檔。"
782
787
  : disciplineResult.ok
783
- ? versionNextStep ?? "繼續日常使用即可。如有新版本發佈,啟動本工具時會自動顯示升級通知。"
788
+ ? versionNextStep ?? onboardingNextStep ?? "檢查已通過。繼續使用你原本的 AI 開工方式;如剛完成一個任務,記得在 AI 對話輸入「收工」保存交接。"
784
789
  : "繼續使用;下次 closeout 時 AI 應自動執行 SESSION_LOG N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
785
790
  });
786
- return overallHealthy ? "passed" : "failed";
787
- }
791
+ return overallHealthy ? "passed" : "failed";
792
+ }
793
+
794
+ function getFirstUseNextStep(root, lastCloseout) {
795
+ if (lastCloseout.date) return null;
796
+ return `檢查已通過。下一步不要再留在終端機;打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,或任何能讀寫此資料夾的 AI 工具,貼上:Work in ${root}. I just installed agent-handoff-kit. Help me get started.`;
797
+ }
788
798
 
789
799
  // R-030 v0.3.0+: Credential leak prevention sweep. Scans dev/PROJECT_INDEX.md,
790
800
  // dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md for common credential prefix patterns.
@@ -847,6 +857,20 @@ function printDoctorSummary(version, root, mode, details) {
847
857
  console.log(`🔎 剛完成:檢查 ${details.checked} 項;${mode === "healthy" ? "全部通過" : `${details.failedCount} 項未通過(${details.failedKind})`}。`);
848
858
  console.log(`🚀 下一步:${details.nextStep}`);
849
859
  }
860
+
861
+ async function hydrateInitialOpeningPrompt(root, created) {
862
+ if (!created.includes("dev/SESSION_HANDOFF.md") && !created.includes("START_NEXT_SESSION_PROMPT.txt")) return;
863
+ for (const rel of ["dev/SESSION_HANDOFF.md", "START_NEXT_SESSION_PROMPT.txt"]) {
864
+ const filePath = path.join(root, rel);
865
+ try {
866
+ const text = await readFile(filePath, "utf8");
867
+ if (!text.includes("<absolute project root>")) continue;
868
+ await writeFile(filePath, text.replaceAll("<absolute project root>", root), "utf8");
869
+ } catch {
870
+ // Leave template untouched; doctor will surface prompt mirror problems if any.
871
+ }
872
+ }
873
+ }
850
874
 
851
875
  async function checkPromptMirror(root) {
852
876
  const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
@@ -889,6 +913,9 @@ function normalizePrompt(text) {
889
913
 
890
914
  function assessHandoffLifecycleConsistency(text) {
891
915
  const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
916
+ if (isAffirmativeLifecycleFieldValue(fieldValue)) {
917
+ return { ok: true, reason: "" };
918
+ }
892
919
  if (isUnresolvedLifecycleFieldValue(fieldValue)) {
893
920
  return { ok: false, reason: "lifecycle field is explicitly unresolved" };
894
921
  }
@@ -898,6 +925,11 @@ function assessHandoffLifecycleConsistency(text) {
898
925
  return { ok: true, reason: "" };
899
926
  }
900
927
 
928
+ function isAffirmativeLifecycleFieldValue(value) {
929
+ const trimmed = (value || "").trim();
930
+ return /^(yes|resolved|confirmed|complete|completed|ok|passed|all clear)\b|^(是|已|完成|已完成|已解決|已核對|已確認|通過)\b/i.test(trimmed);
931
+ }
932
+
901
933
  function isUnresolvedLifecycleFieldValue(value) {
902
934
  return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
903
935
  }
@@ -1164,6 +1196,17 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1164
1196
  };
1165
1197
  }
1166
1198
  }
1199
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario A. 建構系統 / 工具 / 平台 / 網站或應用")) {
1200
+ const mergedOnboarding = mergeOnboardingScenarioALabel(targetText);
1201
+ if (mergedOnboarding !== targetText) {
1202
+ return {
1203
+ ...base,
1204
+ action: "merge",
1205
+ reason: "update onboarding Scenario A wording from narrow coding label to broader system/tool/platform/app label",
1206
+ mergedText: mergedOnboarding
1207
+ };
1208
+ }
1209
+ }
1167
1210
  // v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
1168
1211
  // field. Existing handoff content stays intact; only the missing field and
1169
1212
  // rule note are inserted around stable ack markers.
@@ -1179,12 +1222,51 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1179
1222
  mergedText: mergedHandoff
1180
1223
  };
1181
1224
  }
1182
- if ((targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") && !targetText.includes("AGENTS.md")) {
1183
- return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1225
+ if (targetRel === "CLAUDE.md" || targetRel === "GEMINI.md") {
1226
+ if (!targetText.includes("AGENTS.md")) {
1227
+ return { ...base, action: "conflict", reason: "existing bridge does not route to AGENTS.md" };
1228
+ }
1229
+ if (looksLikeExpandedKitBridge(targetRel, targetText)) {
1230
+ return {
1231
+ ...base,
1232
+ action: "merge",
1233
+ reason: `${targetRel} appears to be an expanded Kit bridge; restore short bridge so AGENTS.md remains the single source of truth`,
1234
+ mergedText: sourceText
1235
+ };
1236
+ }
1184
1237
  }
1185
1238
  return { ...base, action: "skip", reason: "preserve existing file" };
1186
1239
  }
1187
1240
 
1241
+ function looksLikeExpandedKitBridge(targetRel, text) {
1242
+ if (text.includes("This file is a bridge only")) return false;
1243
+ if (targetRel === "CLAUDE.md") {
1244
+ return (text.includes("This file provides guidance to Claude Code") && text.includes("## Session Startup"))
1245
+ || text.includes("## Architecture")
1246
+ || text.includes("## CLI Commands")
1247
+ || text.includes("Every non-trivial task follows");
1248
+ }
1249
+ if (targetRel === "GEMINI.md") {
1250
+ return text.includes("## Architecture")
1251
+ || text.includes("## CLI Commands")
1252
+ || text.includes("Every non-trivial task follows");
1253
+ }
1254
+ return false;
1255
+ }
1256
+
1257
+ function mergeOnboardingScenarioALabel(targetText) {
1258
+ let merged = targetText;
1259
+ merged = merged.replace(
1260
+ /\*\*A\. 寫 \/ 改代碼項目\*\* —— 你有一個(?: project 的 codebase|程式項目)想長期維護/g,
1261
+ "**A. 建構系統 / 工具 / 平台 / 網站或應用** —— 你想由 AI 協助建立或長期維護一個可運作的項目"
1262
+ );
1263
+ merged = merged.replace(
1264
+ /### Scenario A\. 寫 \/ 改代碼項目/g,
1265
+ "### Scenario A. 建構系統 / 工具 / 平台 / 網站或應用"
1266
+ );
1267
+ return merged;
1268
+ }
1269
+
1188
1270
  function mergeHandoffLifecycleField(targetText) {
1189
1271
  const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
1190
1272
  if (!targetText.includes(openingMarker)) return null;
@@ -1334,24 +1416,24 @@ async function assessLastCloseout(root) {
1334
1416
  return { date };
1335
1417
  }
1336
1418
 
1337
- function printLastCloseout(result) {
1338
- if (!result.date) {
1339
- console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
1340
- return;
1341
- }
1419
+ function printLastCloseout(result) {
1420
+ if (!result.date) {
1421
+ console.log(" 📅 上次收工:尚未收工過。第一次完成任務後,可以在 AI 對話輸入「收工」。");
1422
+ return;
1423
+ }
1342
1424
  const today = new Date();
1343
1425
  const closeout = new Date(result.date);
1344
1426
  const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
1345
- if (daysDiff < 0) {
1346
- console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
1347
- } else if (daysDiff === 0) {
1348
- console.log(` 📅 上次 closeout:今日(${result.date})`);
1349
- } else if (daysDiff <= 30) {
1350
- console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
1351
- } else {
1352
- console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
1353
- }
1354
- }
1427
+ if (daysDiff < 0) {
1428
+ console.log(` 📅 上次收工:${result.date}(日期超前?檢查系統時鐘)`);
1429
+ } else if (daysDiff === 0) {
1430
+ console.log(` 📅 上次收工:今日(${result.date})`);
1431
+ } else if (daysDiff <= 30) {
1432
+ console.log(` 📅 上次收工:${daysDiff} 日前(${result.date})`);
1433
+ } else {
1434
+ console.log(` 📅 上次收工:${daysDiff} 日前(${result.date})— 建議輸入「收工」整理進度`);
1435
+ }
1436
+ }
1355
1437
 
1356
1438
  // R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
1357
1439
  // dev/governance_migrations/ which records the first install date. Read-only; doctor
@@ -1614,24 +1696,36 @@ async function detectMode(root) {
1614
1696
  }
1615
1697
 
1616
1698
  function printPlan(command, root, mode, plan, version, isDryRun = false) {
1617
- printCard(version, "continuity ready", "o.o");
1618
- console.log(`command: ${command}`);
1619
- console.log(`current directory: ${process.cwd()}`);
1620
- console.log(`selected root: ${root}`);
1621
- console.log(`mode: ${mode}`);
1622
- console.log("");
1623
- const planIntro = isDryRun
1624
- ? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
1625
- : "📋 即將執行:以下是本次寫入計劃。create 新增缺少檔案;merge 會先備份再合併;skip 保留既有檔案;conflict 代表工具停手等你確認。";
1699
+ printCard(version, "continuity ready", "o.o");
1700
+ console.log(`command: ${command}`);
1701
+ console.log(`current directory: ${process.cwd()}`);
1702
+ console.log(`selected root: ${root}`);
1703
+ console.log(`mode: ${mode}`);
1704
+ console.log("");
1705
+ const planIntro = planIntroFor(command, mode, isDryRun);
1626
1706
  console.log(planIntro);
1627
- console.log("");
1707
+ console.log("");
1628
1708
  for (const action of ["create", "merge", "skip", "conflict"]) {
1629
1709
  const items = plan.filter((item) => item.action === action);
1630
1710
  console.log(`${action}: ${items.length}`);
1631
1711
  for (const item of items) console.log(` ${item.targetRel}${item.reason ? ` - ${item.reason}` : ""}`);
1632
1712
  }
1633
- console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
1634
- }
1713
+ console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
1714
+ }
1715
+
1716
+ function planIntroFor(command, mode, isDryRun) {
1717
+ const prefix = isDryRun ? "📋 預演結果:這次不會寫入檔案。" : "📋 寫入前確認:工具準備這樣處理目前資料夾。";
1718
+ if (command === "init" && mode === "first-install") {
1719
+ return `${prefix} 目前資料夾未見 Kit 檔案;工具會建立交接文件、AI 入口檔與工作規則。沒有既有檔案會被覆寫。`;
1720
+ }
1721
+ if (command === "init" && mode === "partial") {
1722
+ return `${prefix} 目前資料夾已有部分 AI 或 Kit 檔案;工具會補齊缺少檔案,保留既有檔案。安裝後可能仍要用 upgrade 補入口連接。`;
1723
+ }
1724
+ if (command === "upgrade") {
1725
+ return `${prefix} 工具會檢查既有 Kit 檔案;能安全合併才合併,不能判斷時會停手並列為 conflict。`;
1726
+ }
1727
+ return `${prefix} create 代表建立缺少檔案;merge 代表先備份再合併;skip 代表保留既有檔案;conflict 代表工具停手等你判斷。`;
1728
+ }
1635
1729
 
1636
1730
  // R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
1637
1731
  function printInstallSummary(version, command, mode, root, counts) {
@@ -1645,36 +1739,48 @@ function printInstallSummary(version, command, mode, root, counts) {
1645
1739
  console.log(`📦 版本:v${version}`);
1646
1740
  console.log(`🛠️ 模式:${mode}`);
1647
1741
  console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
1648
- if (counts.conflicts > 0) {
1742
+ if (counts.conflicts > 0) {
1649
1743
  console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
1650
- } else if (command === "upgrade") {
1651
- console.log("🚀 下一步:留意下方 upgrade self-check(自動跑 doctor);若全綠即升級完成。");
1652
- } else {
1653
- console.log("🚀 下一步:開新 AI 對話,按下方提示貼入 Work in <root> 一句後描述任務。");
1654
- }
1655
- }
1656
-
1657
- function printDryRunExplanation(plan) {
1658
- const conflicts = plan.filter((item) => item.action === "conflict");
1659
- console.log("✅ 這次沒有改動任何檔案。");
1660
- if (conflicts.length === 0) {
1661
- console.log("✅ 沒有發現 conflict。你仍應先看清楚 create / merge / skip 清單,再決定是否執行正式 upgrade。");
1662
- return;
1663
- }
1664
- console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
1665
- console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
1666
- console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
1744
+ } else if (command === "upgrade") {
1745
+ console.log("🚀 下一步:留意下方升級後自動檢查;若全綠即升級完成。");
1746
+ } else if (mode === "partial" || counts.skipped > 0) {
1747
+ console.log("🚀 下一步:先看下方提示。若你原本已有 AGENTS.md 或其他 AI 規則,請先執行 upgrade --dry-run 補入口連接,再執行 doctor。");
1748
+ } else {
1749
+ console.log("🚀 下一步:不用再留在終端機。打開 AI 工具,貼下方起步句。");
1750
+ }
1751
+ }
1752
+
1753
+ function printDryRunExplanation(command, mode, plan) {
1754
+ const conflicts = plan.filter((item) => item.action === "conflict");
1755
+ console.log("✅ 這次沒有改動任何檔案。");
1756
+ if (conflicts.length === 0) {
1757
+ if (command === "init") {
1758
+ console.log("✅ 沒有發現 conflict。若這是你要安裝 Kit 的資料夾,下一步執行:");
1759
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest init");
1760
+ return;
1761
+ }
1762
+ if (mode === "upgrade-existing") {
1763
+ console.log("✅ 沒有發現 conflict。若你想正式套用以上升級計劃,下一步執行:");
1764
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade");
1765
+ return;
1766
+ }
1767
+ console.log("✅ 沒有發現 conflict。請按你剛才預演的命令去掉 --dry-run 後正式執行。");
1768
+ return;
1769
+ }
1770
+ console.log(`⚠️ 需要人工確認:有 ${conflicts.length} 個既有檔案,工具不能安全判斷怎樣合併。`);
1771
+ console.log("⚠️ 這不是檔案壞掉,也沒有覆寫你的檔案。");
1772
+ console.log("📋 下一步:把這段輸出貼給 AI,叫它幫你判斷要保留、合併,還是手動修改。");
1667
1773
  }
1668
1774
 
1669
- async function confirmWrite() {
1670
- const rl = createInterface({ input, output });
1671
- try {
1672
- const answer = await rl.question("Write missing Agent Handoff Kit files? Type yes to continue: ");
1673
- return answer.trim().toLowerCase() === "yes";
1674
- } finally {
1675
- rl.close();
1676
- }
1677
- }
1775
+ async function confirmWrite() {
1776
+ const rl = createInterface({ input, output });
1777
+ try {
1778
+ const answer = await rl.question("要按上面計劃寫入 / 合併 Kit 檔案嗎?輸入 yes 繼續:");
1779
+ return answer.trim().toLowerCase() === "yes";
1780
+ } finally {
1781
+ rl.close();
1782
+ }
1783
+ }
1678
1784
 
1679
1785
  async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
1680
1786
  const reportPath = path.join(migrationDir, "migration-report.md");
@@ -1825,44 +1931,40 @@ function printCard(version, status, eyes) {
1825
1931
  console.log("");
1826
1932
  }
1827
1933
 
1828
- function printInstallNextSteps(root, conflictCount) {
1829
- console.log("");
1830
- console.log("============================================================");
1831
- console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
1832
- console.log("============================================================");
1934
+ function printInstallNextSteps(root, conflictCount, mode = "first-install", skippedCount = 0) {
1935
+ console.log("");
1936
+ console.log("============================================================");
1937
+ if (mode === "partial" || skippedCount > 0) {
1938
+ console.log("⚠️ 已補齊缺少檔案,但仍要檢查入口連接");
1939
+ } else {
1940
+ console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
1941
+ }
1942
+ console.log("============================================================");
1833
1943
  if (conflictCount > 0) {
1834
1944
  console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
1835
1945
  console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
1836
- console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1837
- console.log("");
1838
- }
1839
- // R-031.2 v0.3.2+: first-install checklist. It answers the user's first
1840
- // question: "is this installed and what do I do next?"
1841
- console.log("📋 如何確認安裝完成:");
1842
- console.log("");
1843
- console.log(" 1. 在 Terminal 執行 npx --yes @adamchanadam/agent-handoff-kit@latest doctor,應該見到「status: passed」");
1844
- console.log(" 2. 你的 dev/ 資料夾應該有規則、交接與工作紀錄等檔案");
1845
- console.log(" 3. 在你使用的 AI 工具(Claude Code / Codex / Gemini)開新對話,貼下面起步句");
1846
- console.log("");
1847
- console.log("⚠️ 注意:Agent Handoff Kit 是放在項目資料夾內的一組交接檔案。");
1848
- console.log(" 它沒有圖形介面,不會啟動伺服器,也不會自動替你做事;你需要在 AI 對話中使用它。");
1849
- console.log(" `npx --yes ...` 只是讓 npm 取得執行工具;不代表 doctor 會安裝或修改項目文件。");
1850
- console.log("");
1851
- console.log("------------------------------------------------------------");
1852
- console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
1853
- console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
1854
- console.log("------------------------------------------------------------");
1855
- console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
1856
- console.log("------------------------------------------------------------");
1857
- console.log("");
1858
- console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
1859
- console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
1860
- console.log("");
1861
- console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
1862
- console.log(` Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
1946
+ console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
1947
+ console.log("");
1948
+ }
1949
+ if (mode === "partial" || skippedCount > 0) {
1950
+ console.log("你原本已有部分 AI 記憶檔,工具已保留它們,沒有覆寫。");
1951
+ console.log("下一步先不要開始新任務;請在終端機執行以下預演,讓工具檢查能否安全補入口連接:");
1952
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run");
1953
+ console.log("");
1954
+ console.log("如預演顯示沒有 conflict,再執行:");
1955
+ console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest upgrade");
1956
+ console.log("============================================================");
1957
+ return;
1958
+ }
1959
+ console.log("------------------------------------------------------------");
1960
+ console.log("⚠️ 下面這句不是終端機指令。");
1961
+ console.log("📋 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,");
1962
+ console.log(" 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上:");
1963
+ console.log("------------------------------------------------------------");
1964
+ console.log(`Work in ${root}. I just installed agent-handoff-kit. Help me get started.`);
1965
+ console.log("------------------------------------------------------------");
1863
1966
  console.log("");
1864
- console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
1865
- console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
1967
+ console.log("🚀 AI 會先確認這個資料夾,然後帶你選擇第一個任務情景:建構系統 / 工具 / 平台 / 網站或應用、研究報告、知識庫整理、學寫代碼,或其他。");
1866
1968
  console.log("============================================================");
1867
1969
  }
1868
1970
 
@@ -1893,7 +1995,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
1893
1995
  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.`);
1894
1996
  console.log("------------------------------------------------------------");
1895
1997
  console.log("");
1896
- console.log("🩺 升級驗收會在下方自動跑 doctor;若全綠即升級完成。");
1998
+ console.log("🩺 升級驗收會在下方自動執行 doctor;若全綠即升級完成。");
1897
1999
  console.log("============================================================");
1898
2000
  }
1899
2001
 
@@ -2008,14 +2110,13 @@ function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok
2008
2110
  if (health.handoffLifecycle?.ok) {
2009
2111
  console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
2010
2112
  console.log("");
2011
- console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
2012
- console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2113
+ console.log("🚀 下一步:回到原本的 AI 對話或開工句即可;如果剛完成任務,記得在 AI 對話輸入「收工」保存交接。");
2013
2114
  console.log("");
2014
2115
  return;
2015
2116
  }
2016
2117
  console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
2017
2118
  console.log("");
2018
- console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2119
+ console.log("🚀 下一步:先執行 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
2019
2120
  console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
2020
2121
  console.log("");
2021
2122
  }
@@ -2043,24 +2144,24 @@ Usage:
2043
2144
  agent-handoff-kit upgrade [--dry-run] [--yes] [--root <path>]
2044
2145
  agent-handoff-kit doctor [--root <path>]
2045
2146
 
2046
- Commands:
2047
- init Plan or install missing core files and rule packs.
2048
- upgrade Preserve existing files; merge safe core updates or report conflicts.
2049
- doctor Check required installed files.
2050
-
2051
- 中文速讀:
2052
- ✅ init 第一次安裝 Kit 文件。
2053
- 🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
2054
- 🩺 doctor 檢查必要文件與交接結構是否完整。
2055
-
2056
- After install:
2057
- Do not type the shown "Work in ..." message into Terminal.
2058
- Open your AI tool, start a new chat, and paste it there.
2059
- The default post-install prompt triggers the onboarding pack — AI
2060
- will guide you through scenario selection (coding / research / knowledge /
2061
- learning / other / integrations governance) and walk you through your first task.
2147
+ Commands:
2148
+ init Plan or install missing core files and rule packs.
2149
+ upgrade Preserve existing files; merge safe core updates or report conflicts.
2150
+ doctor Check required installed files.
2062
2151
 
2063
- Terminal 範例:
2152
+ 中文速讀:
2153
+ ✅ 第一次用:先在項目資料夾執行 init。
2154
+ 🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
2155
+ 🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
2156
+
2157
+ 安裝之後:
2158
+ 不要把顯示出來的 "Work in ..." 文字輸入終端機。
2159
+ 請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,
2160
+ 或任何能讀寫此資料夾的 AI 工具,新增對話後貼上那句起步句。
2161
+ 這句會啟動新手引導;AI 會先帶你選擇情境,
2162
+ 再一步一步整理第一個任務。
2163
+
2164
+ 終端機範例:
2064
2165
  npx --yes @adamchanadam/agent-handoff-kit@latest init
2065
2166
  npx --yes @adamchanadam/agent-handoff-kit@latest doctor
2066
2167
  npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
@@ -2068,12 +2169,13 @@ Terminal 範例:
2068
2169
  以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
2069
2170
  不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
2070
2171
 
2071
- 放在 package 名稱前的 --yes 只讓 npm 取得執行工具,避免額外出現
2072
- "Need to install" 提示。這不會令 doctor 安裝或修改項目文件;
2073
- doctor 只檢查目前的 Kit 文件。即使資料夾已有 AGENTS.md 或 dev/,
2074
- npx 仍可能只是先取得 npm 執行工具。
2172
+ 即使資料夾已有 AGENTS.md 或 dev/,電腦也未必已經有可直接執行的工具;
2173
+ npx --yes 只是先取得工具,然後才執行你指定的 init / doctor / upgrade。
2174
+
2175
+ 放在 package 名稱前的 --yes 只讓 npm 先取得執行工具,避免額外出現
2176
+ "Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
2075
2177
  `);
2076
2178
  console.log(`📦 版本:v${version}`);
2077
2179
  console.log(`🛠️ 模式:help ready`);
2078
- console.log(`🚀 下一步:第一次使用先跑 npx --yes ... init;既有專案升級用 npx --yes ... upgrade --dry-run;要檢查現狀用 npx --yes ... doctor。`);
2180
+ console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
2079
2181
  }
@@ -0,0 +1,19 @@
1
+ # v0.3.10
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 改善第一次安裝後的實際使用流程。終端機完成安裝後,提示會更清楚地把「終端機動作」與「AI 對話下一步」分開;新手引導會用 5 步幫用戶選情境、問背景、收斂第一個小任務,再等用戶確認後才開始正式工作。
6
+
7
+ ## 對你已有檔案的影響
8
+
9
+ 本版會保留既有項目內容。升級時若發現 `CLAUDE.md` 被 AI 改成一份很長的規則文件,工具會把它恢復為短橋接檔,避免 Claude Code 把橋接檔當成第二套規則來源。`GEMINI.md` 也同步說明 Antigravity CLI 與 Gemini CLI 遷移期的入口關係。
10
+
11
+ ## 建議下一步
12
+
13
+ 升級前可先預演:
14
+
15
+ ```bash
16
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
17
+ ```
18
+
19
+ 確認沒有衝突後再升級。升級完成後,如你是第一次使用這個項目,請把工具顯示的完整起步句貼到 AI 對話,而不是留在終端機繼續操作;舊項目升級用戶則照原本開工方式繼續即可。
@@ -0,0 +1,19 @@
1
+ # v0.3.9
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 修正交接狀態檢查的一個誤判:如果 handoff 已明確寫出「已解決」,但同一句同時提到仍有下一步要做,`doctor` 不應把它當成未完成。
6
+
7
+ ## 對你已有檔案的影響
8
+
9
+ 本版不會覆寫你的 handoff 內容。它只令 `doctor` 更準確:真正未收口的交接仍會被指出;已明確收口但保留後續待辦的文字,不應再被誤殺。
10
+
11
+ ## 建議下一步
12
+
13
+ 升級後照常執行:
14
+
15
+ ```bash
16
+ npx --yes @adamchanadam/agent-handoff-kit@latest doctor
17
+ ```
18
+
19
+ 如果 `doctor` 通過,就可以繼續日常使用。如果它指出 handoff 需要修補,請把輸出貼給 AI,先修交接狀態,不要重裝覆蓋項目文件。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.8",
3
+ "version": "0.3.10",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {