@adamchanadam/agent-handoff-kit 0.3.7 → 0.3.8
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 +2 -2
- package/bin/agent-handoff-kit.mjs +59 -59
- package/docs/whatsnew/v0.3.8.md +19 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.8`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -248,7 +248,7 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
|
|
|
248
248
|
|
|
249
249
|
## 目前限制
|
|
250
250
|
|
|
251
|
-
- 目前版本為 `v0.3.
|
|
251
|
+
- 目前版本為 `v0.3.8`。
|
|
252
252
|
- 這是早期可用版本,仍在持續完善中。
|
|
253
253
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
254
254
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -490,21 +490,22 @@ async function runInstall(command, root, options, version) {
|
|
|
490
490
|
&& planConflictCount === 0
|
|
491
491
|
&& !projectIndexVersionNeedsInject;
|
|
492
492
|
|
|
493
|
-
if (isUpgradeNoopAtPlanTime) {
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
console.log(`
|
|
497
|
-
console.log(`
|
|
498
|
-
console.log(`
|
|
493
|
+
if (isUpgradeNoopAtPlanTime) {
|
|
494
|
+
const noOpHealth = await assessUpgradeNoopHealth(root);
|
|
495
|
+
printCard(version, "continuity ready", "o.o");
|
|
496
|
+
console.log(`command: ${command}`);
|
|
497
|
+
console.log(`current directory: ${process.cwd()}`);
|
|
498
|
+
console.log(`selected root: ${root}`);
|
|
499
|
+
console.log(`mode: ${mode}`);
|
|
499
500
|
console.log("");
|
|
500
501
|
console.log(`📋 計劃預覽:create 0 / merge 0 / skip ${planSkipCount} / conflict 0 — 沒有檔案需要建立或合併。`);
|
|
501
502
|
if (options.dryRun) {
|
|
502
|
-
console.log("");
|
|
503
|
-
console.log("dry-run: no files written");
|
|
504
|
-
}
|
|
505
|
-
printUpgradeNoopShortCircuit(version);
|
|
506
|
-
return;
|
|
507
|
-
}
|
|
503
|
+
console.log("");
|
|
504
|
+
console.log("dry-run: no files written");
|
|
505
|
+
}
|
|
506
|
+
printUpgradeNoopShortCircuit(version, noOpHealth);
|
|
507
|
+
return;
|
|
508
|
+
}
|
|
508
509
|
|
|
509
510
|
// R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
|
|
510
511
|
// before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
|
|
@@ -888,55 +889,37 @@ function normalizePrompt(text) {
|
|
|
888
889
|
|
|
889
890
|
function assessHandoffLifecycleConsistency(text) {
|
|
890
891
|
const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
|
|
891
|
-
if (
|
|
892
|
+
if (isUnresolvedLifecycleFieldValue(fieldValue)) {
|
|
892
893
|
return { ok: false, reason: "lifecycle field is explicitly unresolved" };
|
|
893
894
|
}
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
extractSectionText(text, "completed-this-session", "Completed This Session"),
|
|
897
|
-
extractSectionText(text, "validation-qc", "Validation / QC")
|
|
898
|
-
].join("\n");
|
|
899
|
-
const targetText = [
|
|
900
|
-
extractSectionText(text, "next-priorities", "Next Priorities"),
|
|
901
|
-
extractSectionText(text, "risks-blockers", "Risks / Blockers"),
|
|
902
|
-
extractSectionText(text, "next-session-opening-message", "Next Session Opening Message")
|
|
903
|
-
].join("\n");
|
|
904
|
-
|
|
905
|
-
const topics = extractLifecycleTopics(evidenceText);
|
|
906
|
-
for (const topic of topics) {
|
|
907
|
-
if (hasUnresolvedCarryForward(targetText, topic)) {
|
|
908
|
-
return { ok: false, reason: `completed topic carried forward unresolved: ${topic}` };
|
|
909
|
-
}
|
|
895
|
+
if (isPlaceholderLifecycleFieldValue(fieldValue) && hasSubstantiveHandoffState(text)) {
|
|
896
|
+
return { ok: false, reason: "lifecycle field is still placeholder after handoff content changed" };
|
|
910
897
|
}
|
|
911
|
-
|
|
912
898
|
return { ok: true, reason: "" };
|
|
913
899
|
}
|
|
914
900
|
|
|
915
|
-
function
|
|
916
|
-
|
|
917
|
-
for (const match of text.matchAll(/`([^`\n]{2,80})`/g)) {
|
|
918
|
-
const topic = match[1].trim();
|
|
919
|
-
if (!topic || /^dev\/|^docs\/|\.md$|\.txt$|\.json$|^AGENTS\.md$/.test(topic)) continue;
|
|
920
|
-
topics.add(topic);
|
|
921
|
-
}
|
|
922
|
-
return [...topics];
|
|
901
|
+
function isUnresolvedLifecycleFieldValue(value) {
|
|
902
|
+
return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
|
|
923
903
|
}
|
|
924
904
|
|
|
925
|
-
function
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
905
|
+
function isPlaceholderLifecycleFieldValue(value) {
|
|
906
|
+
return !value || /\b(TBD|todo|pending|unverified|unknown|needs-review)\b|待核對|待確認|未核對|未確認/i.test(value);
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
function hasSubstantiveHandoffState(text) {
|
|
910
|
+
const sections = [
|
|
911
|
+
extractSectionText(text, "completed-this-session", "Completed This Session"),
|
|
912
|
+
extractSectionText(text, "validation-qc", "Validation / QC")
|
|
913
|
+
].join("\n");
|
|
914
|
+
const body = sections.replace(/```[\s\S]*?```/g, "");
|
|
915
|
+
return body.split(/\r?\n/).some((line) => {
|
|
916
|
+
const trimmed = line.trim();
|
|
917
|
+
if (!trimmed || trimmed.startsWith("##") || trimmed.startsWith("<!--")) return false;
|
|
918
|
+
if (/^Record only work actually completed/i.test(trimmed)) return false;
|
|
919
|
+
if (/\bTBD\b|待定|待核對|未適用/i.test(trimmed)) return false;
|
|
920
|
+
const normalized = trimmed.replace(/^[\d.*\-)\s]+/, "").replace(/[`\s#|:\-*/()[\].,;,。;、]/g, "");
|
|
921
|
+
return normalized.length > 20;
|
|
922
|
+
});
|
|
940
923
|
}
|
|
941
924
|
|
|
942
925
|
function fieldValueAfterMarker(text, fieldId) {
|
|
@@ -2008,14 +1991,31 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
2008
1991
|
// short factual message and return. Saves disk (no migration report) + reduces noise
|
|
2009
1992
|
// (no self-check doctor) + avoids misleading "安裝完成" framing for an idempotent
|
|
2010
1993
|
// operation where nothing changed.
|
|
2011
|
-
function
|
|
2012
|
-
|
|
2013
|
-
|
|
2014
|
-
|
|
1994
|
+
async function assessUpgradeNoopHealth(root) {
|
|
1995
|
+
try {
|
|
1996
|
+
const handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
|
|
1997
|
+
return { handoffLifecycle: assessHandoffLifecycleConsistency(handoffText) };
|
|
1998
|
+
} catch {
|
|
1999
|
+
return { handoffLifecycle: { ok: false, reason: "dev/SESSION_HANDOFF.md unreadable" } };
|
|
2000
|
+
}
|
|
2001
|
+
}
|
|
2002
|
+
|
|
2003
|
+
function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok: true } }) {
|
|
2004
|
+
console.log("");
|
|
2005
|
+
console.log(`📦 版本:v${version}`);
|
|
2006
|
+
console.log("🛠️ 模式:upgrade-existing");
|
|
2015
2007
|
console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
|
|
2016
|
-
|
|
2008
|
+
if (health.handoffLifecycle?.ok) {
|
|
2009
|
+
console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
|
|
2010
|
+
console.log("");
|
|
2011
|
+
console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
|
|
2012
|
+
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2013
|
+
console.log("");
|
|
2014
|
+
return;
|
|
2015
|
+
}
|
|
2016
|
+
console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
|
|
2017
2017
|
console.log("");
|
|
2018
|
-
console.log("🚀
|
|
2018
|
+
console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
|
|
2019
2019
|
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2020
2020
|
console.log("");
|
|
2021
2021
|
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# v0.3.8
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
修正舊項目升級時的狀態提示:如果 Kit 檔案已是最新版,但交接文件仍有待核對的 closeout 欄位,`upgrade` 不再說可以繼續日常使用,而會提示先請 AI 修正交接狀態。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案的影響
|
|
8
|
+
|
|
9
|
+
本版不會自動覆寫你的 handoff 內容,也不會替你假裝已完成 closeout。`doctor` 會繼續指出需要修的交接結構;`upgrade` 只負責把「檔案已最新」與「交接狀態仍需核對」分清楚。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
升級後如看到交接狀態提示,請執行:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest doctor
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
然後把輸出貼給 AI,請它先做 closeout 狀態核對,不要重裝或覆寫項目文件。
|