@adamchanadam/agent-handoff-kit 0.3.9 → 0.3.11
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 +35 -26
- package/bin/agent-handoff-kit.mjs +267 -170
- package/docs/whatsnew/v0.3.1.md +5 -5
- package/docs/whatsnew/v0.3.10.md +19 -0
- package/docs/whatsnew/v0.3.11.md +19 -0
- package/docs/whatsnew/v0.3.2.md +5 -5
- package/docs/whatsnew/v0.3.3.md +5 -5
- package/docs/whatsnew/v0.3.4.md +2 -2
- package/package.json +1 -1
- package/packs/integrations.md +7 -7
- package/packs/onboarding.md +125 -121
- package/packs/safety.md +1 -1
- package/packs/writing.md +2 -0
- package/runtime-core/AGENTS.core.md +15 -15
- package/runtime-core/CLAUDE.md +8 -8
- package/runtime-core/GEMINI.md +7 -3
- package/runtime-core/PROJECT_INDEX.md +4 -4
- package/runtime-core/RULE_PACKS.md +3 -3
|
@@ -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("🩺
|
|
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("⚠️
|
|
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:
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
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: "
|
|
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");
|
|
@@ -1172,6 +1196,17 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1172
1196
|
};
|
|
1173
1197
|
}
|
|
1174
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
|
+
}
|
|
1175
1210
|
// v0.3.6+: SESSION_HANDOFF.md gains a non-destructive lifecycle consistency
|
|
1176
1211
|
// field. Existing handoff content stays intact; only the missing field and
|
|
1177
1212
|
// rule note are inserted around stable ack markers.
|
|
@@ -1187,12 +1222,51 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1187
1222
|
mergedText: mergedHandoff
|
|
1188
1223
|
};
|
|
1189
1224
|
}
|
|
1190
|
-
if (
|
|
1191
|
-
|
|
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
|
+
}
|
|
1192
1237
|
}
|
|
1193
1238
|
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
1194
1239
|
}
|
|
1195
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
|
+
|
|
1196
1270
|
function mergeHandoffLifecycleField(targetText) {
|
|
1197
1271
|
const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
|
|
1198
1272
|
if (!targetText.includes(openingMarker)) return null;
|
|
@@ -1342,24 +1416,24 @@ async function assessLastCloseout(root) {
|
|
|
1342
1416
|
return { date };
|
|
1343
1417
|
}
|
|
1344
1418
|
|
|
1345
|
-
function printLastCloseout(result) {
|
|
1346
|
-
if (!result.date) {
|
|
1347
|
-
console.log(" 📅
|
|
1348
|
-
return;
|
|
1349
|
-
}
|
|
1419
|
+
function printLastCloseout(result) {
|
|
1420
|
+
if (!result.date) {
|
|
1421
|
+
console.log(" 📅 上次收工:尚未收工過。第一次完成任務後,可以在 AI 對話輸入「收工」。");
|
|
1422
|
+
return;
|
|
1423
|
+
}
|
|
1350
1424
|
const today = new Date();
|
|
1351
1425
|
const closeout = new Date(result.date);
|
|
1352
1426
|
const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
|
|
1353
|
-
if (daysDiff < 0) {
|
|
1354
|
-
console.log(` 📅
|
|
1355
|
-
} else if (daysDiff === 0) {
|
|
1356
|
-
console.log(` 📅
|
|
1357
|
-
} else if (daysDiff <= 30) {
|
|
1358
|
-
console.log(` 📅
|
|
1359
|
-
} else {
|
|
1360
|
-
console.log(` 📅
|
|
1361
|
-
}
|
|
1362
|
-
}
|
|
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
|
+
}
|
|
1363
1437
|
|
|
1364
1438
|
// R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
|
|
1365
1439
|
// dev/governance_migrations/ which records the first install date. Read-only; doctor
|
|
@@ -1622,24 +1696,36 @@ async function detectMode(root) {
|
|
|
1622
1696
|
}
|
|
1623
1697
|
|
|
1624
1698
|
function printPlan(command, root, mode, plan, version, isDryRun = false) {
|
|
1625
|
-
printCard(version, "continuity ready", "o.o");
|
|
1626
|
-
console.log(`command: ${command}`);
|
|
1627
|
-
console.log(`current directory: ${process.cwd()}`);
|
|
1628
|
-
console.log(`selected root: ${root}`);
|
|
1629
|
-
console.log(`mode: ${mode}`);
|
|
1630
|
-
console.log("");
|
|
1631
|
-
const planIntro = isDryRun
|
|
1632
|
-
? "📋 計劃預覽:以下未執行。create 新增缺少檔案;merge 在備份後合併;skip 保留既有檔案;conflict 代表工具停手等你確認。"
|
|
1633
|
-
: "📋 即將執行:以下是本次寫入計劃。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);
|
|
1634
1706
|
console.log(planIntro);
|
|
1635
|
-
console.log("");
|
|
1707
|
+
console.log("");
|
|
1636
1708
|
for (const action of ["create", "merge", "skip", "conflict"]) {
|
|
1637
1709
|
const items = plan.filter((item) => item.action === action);
|
|
1638
1710
|
console.log(`${action}: ${items.length}`);
|
|
1639
1711
|
for (const item of items) console.log(` ${item.targetRel}${item.reason ? ` - ${item.reason}` : ""}`);
|
|
1640
1712
|
}
|
|
1641
|
-
console.log(`\nbackup: ${plan.filter((item) => item.action === "merge").length}`);
|
|
1642
|
-
}
|
|
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
|
+
}
|
|
1643
1729
|
|
|
1644
1730
|
// R-026 CLI Output Contract: install/upgrade 完成必含四項(版本/模式/剛完成/下一步)。
|
|
1645
1731
|
function printInstallSummary(version, command, mode, root, counts) {
|
|
@@ -1653,36 +1739,48 @@ function printInstallSummary(version, command, mode, root, counts) {
|
|
|
1653
1739
|
console.log(`📦 版本:v${version}`);
|
|
1654
1740
|
console.log(`🛠️ 模式:${mode}`);
|
|
1655
1741
|
console.log(`🔎 剛完成:${command} 命令;create ${counts.created} / merge ${counts.merged} / skip ${counts.skipped} / conflict ${counts.conflicts}。`);
|
|
1656
|
-
if (counts.conflicts > 0) {
|
|
1742
|
+
if (counts.conflicts > 0) {
|
|
1657
1743
|
console.log("🚀 下一步:把 migration report 或這段輸出貼給 AI,請它判斷衝突檔案怎樣處理;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1658
|
-
} else if (command === "upgrade") {
|
|
1659
|
-
console.log("🚀
|
|
1660
|
-
} else {
|
|
1661
|
-
console.log("🚀
|
|
1662
|
-
}
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
1666
|
-
|
|
1667
|
-
|
|
1668
|
-
|
|
1669
|
-
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
1673
|
-
|
|
1674
|
-
|
|
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,叫它幫你判斷要保留、合併,還是手動修改。");
|
|
1675
1773
|
}
|
|
1676
1774
|
|
|
1677
|
-
async function confirmWrite() {
|
|
1678
|
-
const rl = createInterface({ input, output });
|
|
1679
|
-
try {
|
|
1680
|
-
const answer = await rl.question("
|
|
1681
|
-
return answer.trim().toLowerCase() === "yes";
|
|
1682
|
-
} finally {
|
|
1683
|
-
rl.close();
|
|
1684
|
-
}
|
|
1685
|
-
}
|
|
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
|
+
}
|
|
1686
1784
|
|
|
1687
1785
|
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
|
|
1688
1786
|
const reportPath = path.join(migrationDir, "migration-report.md");
|
|
@@ -1833,62 +1931,61 @@ function printCard(version, status, eyes) {
|
|
|
1833
1931
|
console.log("");
|
|
1834
1932
|
}
|
|
1835
1933
|
|
|
1836
|
-
function printInstallNextSteps(root, conflictCount) {
|
|
1837
|
-
console.log("");
|
|
1838
|
-
console.log("============================================================");
|
|
1839
|
-
|
|
1840
|
-
|
|
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("============================================================");
|
|
1841
1943
|
if (conflictCount > 0) {
|
|
1842
1944
|
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
1843
1945
|
console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1844
|
-
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1845
|
-
console.log("");
|
|
1846
|
-
}
|
|
1847
|
-
|
|
1848
|
-
|
|
1849
|
-
|
|
1850
|
-
|
|
1851
|
-
|
|
1852
|
-
|
|
1853
|
-
|
|
1854
|
-
|
|
1855
|
-
|
|
1856
|
-
|
|
1857
|
-
console.log("
|
|
1858
|
-
console.log("");
|
|
1859
|
-
console.log("
|
|
1860
|
-
console.log("
|
|
1861
|
-
console.log("
|
|
1862
|
-
console.log(
|
|
1863
|
-
console.log(
|
|
1864
|
-
console.log("------------------------------------------------------------");
|
|
1865
|
-
console.log("");
|
|
1866
|
-
console.log("🚀 AI 會主動引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),");
|
|
1867
|
-
console.log(" 一步一步帶你做第一個任務(由新手引導包主動接管)。");
|
|
1868
|
-
console.log("");
|
|
1869
|
-
console.log("💡 之後你熟悉流程後,可改用更直接的開工句:");
|
|
1870
|
-
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("------------------------------------------------------------");
|
|
1871
1966
|
console.log("");
|
|
1872
|
-
console.log("
|
|
1873
|
-
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
1967
|
+
console.log("🚀 AI 會先確認這個資料夾,然後帶你選擇第一個任務情景:建構系統 / 工具 / 平台 / 網站或應用、研究報告、知識庫整理、學寫代碼,或其他。");
|
|
1874
1968
|
console.log("============================================================");
|
|
1875
1969
|
}
|
|
1876
1970
|
|
|
1877
1971
|
// R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
|
|
1878
1972
|
// (`printInstallNextSteps`) because the user is not first-time; pushing them through
|
|
1879
1973
|
// the onboarding canonical phrase resets context they already have.
|
|
1880
|
-
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1881
|
-
console.log("");
|
|
1882
|
-
console.log("============================================================");
|
|
1974
|
+
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1975
|
+
console.log("");
|
|
1976
|
+
console.log("============================================================");
|
|
1977
|
+
if (conflictCount > 0) {
|
|
1978
|
+
console.log("⚠️ 升級未完成:有檔案需要人工確認");
|
|
1979
|
+
console.log("============================================================");
|
|
1980
|
+
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
1981
|
+
console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1982
|
+
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1983
|
+
console.log("============================================================");
|
|
1984
|
+
return;
|
|
1985
|
+
}
|
|
1883
1986
|
console.log("✅ 升級完成:Kit 檔案已更新到最新版本");
|
|
1884
|
-
console.log("============================================================");
|
|
1885
|
-
|
|
1886
|
-
console.log("⚠️ 狀態:有既有檔案需要人工確認,詳情見 migration report。");
|
|
1887
|
-
console.log("⚠️ 這不是檔案壞掉;工具已停手,沒有覆寫 conflict 檔案。");
|
|
1888
|
-
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1889
|
-
console.log("");
|
|
1890
|
-
}
|
|
1891
|
-
// R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
|
|
1987
|
+
console.log("============================================================");
|
|
1988
|
+
// R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
|
|
1892
1989
|
// version (and any intermediate versions the user skipped).
|
|
1893
1990
|
// R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
|
|
1894
1991
|
// inject mutated PROJECT_INDEX), so the range narrative reflects actual user
|
|
@@ -1901,7 +1998,7 @@ async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRoo
|
|
|
1901
1998
|
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.`);
|
|
1902
1999
|
console.log("------------------------------------------------------------");
|
|
1903
2000
|
console.log("");
|
|
1904
|
-
console.log("🩺
|
|
2001
|
+
console.log("🩺 升級驗收會在下方自動執行 doctor;若全綠即升級完成。");
|
|
1905
2002
|
console.log("============================================================");
|
|
1906
2003
|
}
|
|
1907
2004
|
|
|
@@ -2016,14 +2113,13 @@ function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok
|
|
|
2016
2113
|
if (health.handoffLifecycle?.ok) {
|
|
2017
2114
|
console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
|
|
2018
2115
|
console.log("");
|
|
2019
|
-
console.log("🚀
|
|
2020
|
-
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2116
|
+
console.log("🚀 下一步:回到原本的 AI 對話或開工句即可;如果剛完成任務,記得在 AI 對話輸入「收工」保存交接。");
|
|
2021
2117
|
console.log("");
|
|
2022
2118
|
return;
|
|
2023
2119
|
}
|
|
2024
2120
|
console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
|
|
2025
2121
|
console.log("");
|
|
2026
|
-
console.log("🚀
|
|
2122
|
+
console.log("🚀 下一步:先執行 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
|
|
2027
2123
|
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2028
2124
|
console.log("");
|
|
2029
2125
|
}
|
|
@@ -2051,24 +2147,24 @@ Usage:
|
|
|
2051
2147
|
agent-handoff-kit upgrade [--dry-run] [--yes] [--root <path>]
|
|
2052
2148
|
agent-handoff-kit doctor [--root <path>]
|
|
2053
2149
|
|
|
2054
|
-
Commands:
|
|
2055
|
-
init Plan or install missing core files and rule packs.
|
|
2056
|
-
upgrade Preserve existing files; merge safe core updates or report conflicts.
|
|
2057
|
-
doctor Check required installed files.
|
|
2058
|
-
|
|
2059
|
-
中文速讀:
|
|
2060
|
-
✅ init 第一次安裝 Kit 文件。
|
|
2061
|
-
🔄 upgrade 升級既有 Kit 文件;先用 --dry-run 預演。
|
|
2062
|
-
🩺 doctor 檢查必要文件與交接結構是否完整。
|
|
2063
|
-
|
|
2064
|
-
After install:
|
|
2065
|
-
Do not type the shown "Work in ..." message into Terminal.
|
|
2066
|
-
Open your AI tool, start a new chat, and paste it there.
|
|
2067
|
-
The default post-install prompt triggers the onboarding pack — AI
|
|
2068
|
-
will guide you through scenario selection (coding / research / knowledge /
|
|
2069
|
-
learning / other / integrations governance) and walk you through your first task.
|
|
2150
|
+
Commands:
|
|
2151
|
+
init Plan or install missing core files and rule packs.
|
|
2152
|
+
upgrade Preserve existing files; merge safe core updates or report conflicts.
|
|
2153
|
+
doctor Check required installed files.
|
|
2070
2154
|
|
|
2071
|
-
|
|
2155
|
+
中文速讀:
|
|
2156
|
+
✅ 第一次用:先在項目資料夾執行 init。
|
|
2157
|
+
🔄 已裝過:先用 upgrade --dry-run 預演,再決定是否正式升級。
|
|
2158
|
+
🩺 不確定狀態:用 doctor 檢查;doctor 只檢查,不會改檔。
|
|
2159
|
+
|
|
2160
|
+
安裝之後:
|
|
2161
|
+
不要把顯示出來的 "Work in ..." 文字輸入終端機。
|
|
2162
|
+
請打開 Claude Code / Claude Cowork / OpenAI Codex / Google Antigravity,
|
|
2163
|
+
或任何能讀寫此資料夾的 AI 工具,新增對話後貼上那句起步句。
|
|
2164
|
+
這句會啟動新手引導;AI 會先帶你選擇情境,
|
|
2165
|
+
再一步一步整理第一個任務。
|
|
2166
|
+
|
|
2167
|
+
終端機範例:
|
|
2072
2168
|
npx --yes @adamchanadam/agent-handoff-kit@latest init
|
|
2073
2169
|
npx --yes @adamchanadam/agent-handoff-kit@latest doctor
|
|
2074
2170
|
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
@@ -2076,12 +2172,13 @@ Terminal 範例:
|
|
|
2076
2172
|
以上才是建議的 npx 用戶路徑。裸寫不帶 --yes / @latest 的 npx doctor
|
|
2077
2173
|
不是本工具的建議用戶路徑,容易先出現 npm 自己的安裝提示。
|
|
2078
2174
|
|
|
2079
|
-
|
|
2080
|
-
|
|
2081
|
-
|
|
2082
|
-
|
|
2175
|
+
即使資料夾已有 AGENTS.md 或 dev/,電腦也未必已經有可直接執行的工具;
|
|
2176
|
+
npx --yes 只是先取得工具,然後才執行你指定的 init / doctor / upgrade。
|
|
2177
|
+
|
|
2178
|
+
放在 package 名稱前的 --yes 只讓 npm 先取得執行工具,避免額外出現
|
|
2179
|
+
"Need to install" 提示。真正會建立項目文件的是 init;doctor 只檢查。
|
|
2083
2180
|
`);
|
|
2084
2181
|
console.log(`📦 版本:v${version}`);
|
|
2085
2182
|
console.log(`🛠️ 模式:help ready`);
|
|
2086
|
-
console.log(`🚀
|
|
2183
|
+
console.log(`🚀 下一步:新項目先執行 init;舊項目先執行 upgrade --dry-run;只想檢查才執行 doctor。`);
|
|
2087
2184
|
}
|
package/docs/whatsnew/v0.3.1.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# v0.3.1
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 本版新加了甚麼
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
改善升級流程的提示文字。完成升級、再次執行 `upgrade`、或沒有任何檔案需要更新時,工具會顯示不同提示,避免把「已經是最新版本」誤說成「安裝完成」。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
本版只調整工具輸出文字,不會改動既有項目內容,也不會改變已安裝的 Kit 文件結構。
|
|
10
10
|
|
|
11
11
|
## 建議下一步
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
執行 `doctor` 檢查項目健康即可。
|