@adamchanadam/agent-handoff-kit 0.3.13 → 0.3.14
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 +14 -28
- package/bin/prompt-mirror-core.mjs +110 -0
- package/docs/whatsnew/v0.3.14.md +29 -0
- package/package.json +6 -5
- package/packs/safety.md +11 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.14`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -261,7 +261,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
261
261
|
|
|
262
262
|
## 目前限制
|
|
263
263
|
|
|
264
|
-
- 目前版本為 `v0.3.
|
|
264
|
+
- 目前版本為 `v0.3.14`。
|
|
265
265
|
- 這是早期可用版本,仍在持續完善中。
|
|
266
266
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
267
267
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -2,9 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
import { createInterface } from "node:readline/promises";
|
|
4
4
|
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
-
import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
-
import path from "node:path";
|
|
7
|
-
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { fileURLToPath } from "node:url";
|
|
8
|
+
import { assessPromptMirrorTexts } from "./prompt-mirror-core.mjs";
|
|
8
9
|
|
|
9
10
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
11
|
const packageRoot = path.resolve(__dirname, "..");
|
|
@@ -918,7 +919,7 @@ async function hydrateInitialOpeningPrompt(root, created) {
|
|
|
918
919
|
}
|
|
919
920
|
}
|
|
920
921
|
|
|
921
|
-
async function checkPromptMirror(root) {
|
|
922
|
+
async function checkPromptMirror(root) {
|
|
922
923
|
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
923
924
|
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
924
925
|
let handoffText = "";
|
|
@@ -933,29 +934,14 @@ async function checkPromptMirror(root) {
|
|
|
933
934
|
} catch {
|
|
934
935
|
return [{ target: "START_NEXT_SESSION_PROMPT.txt", label: "matches handoff opening message", ok: false, reason: "prompt copy unreadable" }];
|
|
935
936
|
}
|
|
936
|
-
const
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
}
|
|
943
|
-
|
|
944
|
-
function extractOpeningMessage(text) {
|
|
945
|
-
const marker = "📋 Next session: copy and paste the whole block below";
|
|
946
|
-
const markerIndex = text.indexOf(marker);
|
|
947
|
-
if (markerIndex < 0) return null;
|
|
948
|
-
const fenceStart = text.indexOf("```text", markerIndex);
|
|
949
|
-
if (fenceStart < 0) return null;
|
|
950
|
-
const contentStart = text.indexOf("\n", fenceStart);
|
|
951
|
-
const fenceEnd = text.indexOf("```", contentStart + 1);
|
|
952
|
-
if (contentStart < 0 || fenceEnd < 0) return null;
|
|
953
|
-
return text.slice(contentStart + 1, fenceEnd).trim();
|
|
954
|
-
}
|
|
955
|
-
|
|
956
|
-
function normalizePrompt(text) {
|
|
957
|
-
return text.replace(/\r\n/g, "\n").trim();
|
|
958
|
-
}
|
|
937
|
+
const mirror = assessPromptMirrorTexts(handoffText, promptText);
|
|
938
|
+
return [{
|
|
939
|
+
target: "START_NEXT_SESSION_PROMPT.txt",
|
|
940
|
+
label: "matches handoff opening message",
|
|
941
|
+
ok: mirror.ok,
|
|
942
|
+
reason: mirror.ok ? "" : mirror.reason
|
|
943
|
+
}];
|
|
944
|
+
}
|
|
959
945
|
|
|
960
946
|
function assessHandoffLifecycleConsistency(text) {
|
|
961
947
|
const fieldValue = fieldValueAfterMarker(text, "lifecycle-conflicts-resolved");
|
|
@@ -1322,7 +1308,7 @@ function mergeHandoffLifecycleField(targetText) {
|
|
|
1322
1308
|
const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
|
|
1323
1309
|
if (!targetText.includes(openingMarker)) return null;
|
|
1324
1310
|
|
|
1325
|
-
const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified:
|
|
1311
|
+
const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: Reclassified at upgrade: field added by v0.3.6+ migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
|
|
1326
1312
|
let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
|
|
1327
1313
|
|
|
1328
1314
|
if (!merged.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
+
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
+
const copyMarker = "📋 Next session: copy and paste the whole block below";
|
|
7
|
+
|
|
8
|
+
export function assessPromptMirrorRoot(root) {
|
|
9
|
+
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
10
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
11
|
+
let handoffText = "";
|
|
12
|
+
let promptText = "";
|
|
13
|
+
|
|
14
|
+
try {
|
|
15
|
+
handoffText = readFileSync(handoffPath, "utf8");
|
|
16
|
+
} catch {
|
|
17
|
+
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
try {
|
|
21
|
+
promptText = readFileSync(promptPath, "utf8");
|
|
22
|
+
} catch {
|
|
23
|
+
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
return assessPromptMirrorTexts(handoffText, promptText);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function assessPromptMirrorTexts(handoffText, promptText) {
|
|
30
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
31
|
+
if (openingMessage == null) {
|
|
32
|
+
return {
|
|
33
|
+
status: "missing",
|
|
34
|
+
ok: false,
|
|
35
|
+
reason: "handoff opening message missing"
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
if (openingMessage === promptText) {
|
|
40
|
+
return {
|
|
41
|
+
status: "match",
|
|
42
|
+
ok: true,
|
|
43
|
+
reason: "",
|
|
44
|
+
openingMessage,
|
|
45
|
+
firstDiff: null
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const normalizedOpening = normalizePrompt(openingMessage);
|
|
50
|
+
const normalizedPrompt = normalizePrompt(promptText);
|
|
51
|
+
if (normalizedOpening === normalizedPrompt) {
|
|
52
|
+
return {
|
|
53
|
+
status: "newline-only",
|
|
54
|
+
ok: true,
|
|
55
|
+
reason: "only newline style or final newline differs",
|
|
56
|
+
openingMessage,
|
|
57
|
+
firstDiff: null
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return {
|
|
62
|
+
status: "mismatch",
|
|
63
|
+
ok: false,
|
|
64
|
+
reason: "convenience copy differs from dev/SESSION_HANDOFF.md",
|
|
65
|
+
openingMessage,
|
|
66
|
+
firstDiff: firstDiff(normalizedOpening, normalizedPrompt)
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function extractOpeningMessage(text) {
|
|
71
|
+
const sectionStart = findOpeningSectionStart(text);
|
|
72
|
+
if (sectionStart < 0) return null;
|
|
73
|
+
|
|
74
|
+
const sectionText = text.slice(sectionStart);
|
|
75
|
+
const markerIndex = sectionText.indexOf(copyMarker);
|
|
76
|
+
if (markerIndex < 0) return null;
|
|
77
|
+
|
|
78
|
+
const afterMarker = sectionText.slice(markerIndex + copyMarker.length);
|
|
79
|
+
const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
|
|
80
|
+
if (!fenceMatch) return null;
|
|
81
|
+
return fenceMatch[1];
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function normalizePrompt(text) {
|
|
85
|
+
return text.replace(/\r\n?/g, "\n").replace(/\n+$/g, "");
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function findOpeningSectionStart(text) {
|
|
89
|
+
const markerIndex = text.indexOf(openingSectionMarker);
|
|
90
|
+
if (markerIndex >= 0) return markerIndex;
|
|
91
|
+
|
|
92
|
+
const headingMatch = openingHeadingPattern.exec(text);
|
|
93
|
+
return headingMatch ? headingMatch.index : -1;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function firstDiff(left, right) {
|
|
97
|
+
const leftLines = left.split("\n");
|
|
98
|
+
const rightLines = right.split("\n");
|
|
99
|
+
const count = Math.max(leftLines.length, rightLines.length);
|
|
100
|
+
for (let index = 0; index < count; index += 1) {
|
|
101
|
+
if ((leftLines[index] ?? "") !== (rightLines[index] ?? "")) {
|
|
102
|
+
return {
|
|
103
|
+
line: index + 1,
|
|
104
|
+
handoff: leftLines[index] ?? "",
|
|
105
|
+
prompt: rightLines[index] ?? ""
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# v0.3.14
|
|
2
|
+
|
|
3
|
+
## 本版新加了甚麼
|
|
4
|
+
|
|
5
|
+
本版修正舊版項目跨版本升級時的交接狀態誤判。部分由很早期版本升級的項目,`upgrade` 會補入新的 lifecycle 欄位;舊工具曾把欄位填成 `TBD`,然後同一次升級後自動 `doctor` 又把這個 `TBD` 判定為失敗。
|
|
6
|
+
|
|
7
|
+
現在升級工具會把這類欄位明確標記為「由升級重新分類,下一次 closeout 再核對」,避免工具自己寫入一個會被自己拒絕的值。
|
|
8
|
+
|
|
9
|
+
同時,本版把 rules / packs 路由與可重用程序入庫範圍加入發佈前全面檢,確認自然語言任務能導向相應 pack,而不是隨意新建治理文件或只寫在 handoff / log。
|
|
10
|
+
|
|
11
|
+
另外,本版把 `START_NEXT_SESSION_PROMPT.txt` 與 handoff opening message 的比對方法收斂到固定檢查器。檢查器會先錨定真正的下一次開工訊息,再正規化 CRLF / LF 換行符,避免只因換行風格不同就誤報內容不一致。
|
|
12
|
+
|
|
13
|
+
## 對你已有檔案的影響
|
|
14
|
+
|
|
15
|
+
既有項目不用重裝。若你是由舊版 Kit 升級,工具可能會在 `dev/SESSION_HANDOFF.md` 補入 lifecycle consistency 欄位;這是為了讓下一次 closeout 能核對「已完成的事是否仍被帶成未解待辦」。
|
|
16
|
+
|
|
17
|
+
工具仍會保留既有交接內容,不會用新版模板覆寫你的工作紀錄。若 `doctor` 指出其他真實缺失,仍應把完整輸出交給 AI 非破壞性修補。
|
|
18
|
+
|
|
19
|
+
若只出現 prompt convenience copy 的換行符差異,這不是內容損壞;正常 `doctor` 不會因此阻擋你繼續工作。
|
|
20
|
+
|
|
21
|
+
## 建議下一步
|
|
22
|
+
|
|
23
|
+
已安裝舊版的項目可先預演:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
如果預演沒有 conflict,再執行正式升級。升級後若自動 `doctor` 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.14",
|
|
4
4
|
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -18,10 +18,11 @@
|
|
|
18
18
|
"doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
|
|
19
19
|
"dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
|
|
20
20
|
"qa:prototype": "node scripts/check-public-prototype.mjs",
|
|
21
|
-
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
-
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
-
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
-
"qa:
|
|
21
|
+
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
+
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
+
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
+
"qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
|
|
25
|
+
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
25
26
|
},
|
|
26
27
|
"engines": {
|
|
27
28
|
"node": ">=18"
|
package/packs/safety.md
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
1
1
|
# Safety Pack
|
|
2
2
|
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
-
|
|
7
|
-
##
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
|
|
10
|
+
- A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, or public release state.
|
|
11
|
+
- Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
|
|
12
|
+
|
|
13
|
+
## Rules
|
|
8
14
|
|
|
9
15
|
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
10
16
|
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|