@adamchanadam/agent-handoff-kit 0.3.7 → 0.3.9
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 +3 -3
- package/bin/agent-handoff-kit.mjs +67 -59
- package/docs/whatsnew/v0.3.8.md +19 -0
- package/docs/whatsnew/v0.3.9.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.9`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -248,8 +248,8 @@ Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates
|
|
|
248
248
|
|
|
249
249
|
## 目前限制
|
|
250
250
|
|
|
251
|
-
- 目前版本為 `v0.3.
|
|
251
|
+
- 目前版本為 `v0.3.9`。
|
|
252
252
|
- 這是早期可用版本,仍在持續完善中。
|
|
253
253
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
254
254
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
255
|
-
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
255
|
+
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
@@ -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,45 @@ function normalizePrompt(text) {
|
|
|
888
889
|
|
|
889
890
|
function assessHandoffLifecycleConsistency(text) {
|
|
890
891
|
const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
|
|
891
|
-
if (
|
|
892
|
+
if (isAffirmativeLifecycleFieldValue(fieldValue)) {
|
|
893
|
+
return { ok: true, reason: "" };
|
|
894
|
+
}
|
|
895
|
+
if (isUnresolvedLifecycleFieldValue(fieldValue)) {
|
|
892
896
|
return { ok: false, reason: "lifecycle field is explicitly unresolved" };
|
|
893
897
|
}
|
|
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
|
-
}
|
|
898
|
+
if (isPlaceholderLifecycleFieldValue(fieldValue) && hasSubstantiveHandoffState(text)) {
|
|
899
|
+
return { ok: false, reason: "lifecycle field is still placeholder after handoff content changed" };
|
|
910
900
|
}
|
|
911
|
-
|
|
912
901
|
return { ok: true, reason: "" };
|
|
913
902
|
}
|
|
914
903
|
|
|
915
|
-
function
|
|
916
|
-
const
|
|
917
|
-
|
|
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];
|
|
904
|
+
function isAffirmativeLifecycleFieldValue(value) {
|
|
905
|
+
const trimmed = (value || "").trim();
|
|
906
|
+
return /^(yes|resolved|confirmed|complete|completed|ok|passed|all clear)\b|^(是|已|完成|已完成|已解決|已核對|已確認|通過)\b/i.test(trimmed);
|
|
923
907
|
}
|
|
924
908
|
|
|
925
|
-
function
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
return
|
|
909
|
+
function isUnresolvedLifecycleFieldValue(value) {
|
|
910
|
+
return /\b(no|blocked|uncertain)\b|否|阻擋|不確定/i.test(value || "");
|
|
911
|
+
}
|
|
912
|
+
|
|
913
|
+
function isPlaceholderLifecycleFieldValue(value) {
|
|
914
|
+
return !value || /\b(TBD|todo|pending|unverified|unknown|needs-review)\b|待核對|待確認|未核對|未確認/i.test(value);
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
function hasSubstantiveHandoffState(text) {
|
|
918
|
+
const sections = [
|
|
919
|
+
extractSectionText(text, "completed-this-session", "Completed This Session"),
|
|
920
|
+
extractSectionText(text, "validation-qc", "Validation / QC")
|
|
921
|
+
].join("\n");
|
|
922
|
+
const body = sections.replace(/```[\s\S]*?```/g, "");
|
|
923
|
+
return body.split(/\r?\n/).some((line) => {
|
|
924
|
+
const trimmed = line.trim();
|
|
925
|
+
if (!trimmed || trimmed.startsWith("##") || trimmed.startsWith("<!--")) return false;
|
|
926
|
+
if (/^Record only work actually completed/i.test(trimmed)) return false;
|
|
927
|
+
if (/\bTBD\b|待定|待核對|未適用/i.test(trimmed)) return false;
|
|
928
|
+
const normalized = trimmed.replace(/^[\d.*\-)\s]+/, "").replace(/[`\s#|:\-*/()[\].,;,。;、]/g, "");
|
|
929
|
+
return normalized.length > 20;
|
|
930
|
+
});
|
|
940
931
|
}
|
|
941
932
|
|
|
942
933
|
function fieldValueAfterMarker(text, fieldId) {
|
|
@@ -2008,14 +1999,31 @@ async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
|
2008
1999
|
// short factual message and return. Saves disk (no migration report) + reduces noise
|
|
2009
2000
|
// (no self-check doctor) + avoids misleading "安裝完成" framing for an idempotent
|
|
2010
2001
|
// operation where nothing changed.
|
|
2011
|
-
function
|
|
2012
|
-
|
|
2013
|
-
|
|
2014
|
-
|
|
2002
|
+
async function assessUpgradeNoopHealth(root) {
|
|
2003
|
+
try {
|
|
2004
|
+
const handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
|
|
2005
|
+
return { handoffLifecycle: assessHandoffLifecycleConsistency(handoffText) };
|
|
2006
|
+
} catch {
|
|
2007
|
+
return { handoffLifecycle: { ok: false, reason: "dev/SESSION_HANDOFF.md unreadable" } };
|
|
2008
|
+
}
|
|
2009
|
+
}
|
|
2010
|
+
|
|
2011
|
+
function printUpgradeNoopShortCircuit(version, health = { handoffLifecycle: { ok: true } }) {
|
|
2012
|
+
console.log("");
|
|
2013
|
+
console.log(`📦 版本:v${version}`);
|
|
2014
|
+
console.log("🛠️ 模式:upgrade-existing");
|
|
2015
2015
|
console.log("🔎 剛完成:檢查所有 Kit 檔案的狀態(含 AGENTS.md、dev/SESSION_HANDOFF.md、dev/PROJECT_INDEX.md 等)。");
|
|
2016
|
-
|
|
2016
|
+
if (health.handoffLifecycle?.ok) {
|
|
2017
|
+
console.log("✅ 結果:你已經是最新版本,沒有檔案需要建立或合併;用戶填寫的內容全部保留現狀。");
|
|
2018
|
+
console.log("");
|
|
2019
|
+
console.log("🚀 下一步:繼續日常使用即可。如要檢查健康狀態,可執行:");
|
|
2020
|
+
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2021
|
+
console.log("");
|
|
2022
|
+
return;
|
|
2023
|
+
}
|
|
2024
|
+
console.log("⚠️ 結果:Kit 檔案已是最新版本,沒有檔案需要建立或合併;但交接狀態仍需 AI closeout 核對。");
|
|
2017
2025
|
console.log("");
|
|
2018
|
-
console.log("🚀
|
|
2026
|
+
console.log("🚀 下一步:先跑 doctor 取得待修項,再把輸出貼給 AI;不要重裝或覆寫用戶內容。");
|
|
2019
2027
|
console.log(" npx --yes @adamchanadam/agent-handoff-kit@latest doctor");
|
|
2020
2028
|
console.log("");
|
|
2021
2029
|
}
|
|
@@ -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 狀態核對,不要重裝或覆寫項目文件。
|
|
@@ -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,先修交接狀態,不要重裝覆蓋項目文件。
|