@adamchanadam/agent-handoff-kit 0.1.2 → 0.1.3
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 +23 -9
- package/bin/agent-handoff-kit.mjs +101 -19
- package/package.json +1 -1
- package/runtime-core/PROJECT_INDEX.md +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.1.
|
|
3
|
+
狀態:`v0.1.3` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
|
|
4
4
|
|
|
5
5
|
Agent Handoff Kit 是一套給 AI 專案使用的交接工具。它會在你的專案中放入一組固定文件,讓 AI 在下一次工作時知道:目前做到哪裡、哪些資料要先讀、哪些檔案不可亂動、收工時要留下甚麼。
|
|
6
6
|
|
|
@@ -65,8 +65,7 @@ yes
|
|
|
65
65
|
你可以貼上類似以下文字:
|
|
66
66
|
|
|
67
67
|
```text
|
|
68
|
-
Work in <你的專案資料夾>.
|
|
69
|
-
Read AGENTS.md first. Tell me what you understand before changing files.
|
|
68
|
+
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
70
69
|
```
|
|
71
70
|
|
|
72
71
|
接著再寫你的任務,例如:
|
|
@@ -93,6 +92,16 @@ npx @adamchanadam/agent-handoff-kit doctor
|
|
|
93
92
|
|
|
94
93
|
這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
|
|
95
94
|
|
|
95
|
+
## 版本提示
|
|
96
|
+
|
|
97
|
+
CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
98
|
+
|
|
99
|
+
若你不想檢查更新,可設定:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
103
|
+
```
|
|
104
|
+
|
|
96
105
|
## 會安裝甚麼
|
|
97
106
|
|
|
98
107
|
安裝工具會在你的專案中建立以下文件:
|
|
@@ -127,14 +136,19 @@ dev/rules/*.md
|
|
|
127
136
|
|
|
128
137
|
## 日常使用方式
|
|
129
138
|
|
|
130
|
-
每次開始新的 AI
|
|
139
|
+
每次開始新的 AI 工作階段,有兩種做法:
|
|
140
|
+
|
|
141
|
+
1. 最佳:貼上上一輪收工產生的開工文字。那段文字內容最完整、最準確。
|
|
142
|
+
2. 沒有那段文字時,貼上這一句就夠:
|
|
131
143
|
|
|
132
144
|
```text
|
|
133
|
-
Work in <你的專案資料夾>.
|
|
134
|
-
Read AGENTS.md, dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md, dev/PROJECT_INDEX.md, and dev/RULE_PACKS.md.
|
|
135
|
-
Tell me the current objective, pending work, risks, and your recommended next action before changing files.
|
|
145
|
+
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
136
146
|
```
|
|
137
147
|
|
|
148
|
+
你不需要在提示內逐一列出檔案。`AGENTS.md` 本身已包含開工讀序,AI 讀它就會自行讀入交接、紀錄與索引。
|
|
149
|
+
|
|
150
|
+
備用(只在你的 AI 工具沒有依 `AGENTS.md` 讀時才需要):在上面那句後面加一句 `Also read dev/SESSION_HANDOFF.md and dev/SESSION_LOG.md.`。
|
|
151
|
+
|
|
138
152
|
然後直接描述任務。
|
|
139
153
|
|
|
140
154
|
對簡單任務,可以這樣寫:
|
|
@@ -228,8 +242,8 @@ npm package 只包含安裝所需內容:
|
|
|
228
242
|
|
|
229
243
|
## 目前限制
|
|
230
244
|
|
|
231
|
-
- `v0.1.
|
|
232
|
-
-
|
|
245
|
+
- `v0.1.3` 是 GitHub 與 npm 同步發佈版本。
|
|
246
|
+
- 這是早期可用版本,尚未宣稱完整穩定。
|
|
233
247
|
- 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
|
|
234
248
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
235
249
|
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|
|
@@ -132,8 +132,7 @@ const requiredAnchors = [
|
|
|
132
132
|
target: "dev/PROJECT_INDEX.md",
|
|
133
133
|
label: "template version metadata",
|
|
134
134
|
snippets: [
|
|
135
|
-
"Agent Handoff Kit template version"
|
|
136
|
-
"0.1.2"
|
|
135
|
+
"Agent Handoff Kit template version"
|
|
137
136
|
]
|
|
138
137
|
},
|
|
139
138
|
{
|
|
@@ -259,6 +258,7 @@ main().catch((error) => {
|
|
|
259
258
|
|
|
260
259
|
async function main() {
|
|
261
260
|
const version = await readPackageVersion();
|
|
261
|
+
await maybePrintUpdateNotice(version);
|
|
262
262
|
const { command, options } = parseArgs(process.argv.slice(2));
|
|
263
263
|
if (!command || options.help) {
|
|
264
264
|
printHelp(version);
|
|
@@ -343,12 +343,12 @@ async function runInstall(command, root, options, version) {
|
|
|
343
343
|
}
|
|
344
344
|
|
|
345
345
|
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
346
|
-
console.log(`\
|
|
347
|
-
console.log(
|
|
348
|
-
console.log(
|
|
349
|
-
console.log(
|
|
350
|
-
if (merged.length > 0) console.log(
|
|
351
|
-
console.log(
|
|
346
|
+
console.log(`\n✅ created: ${created.length}`);
|
|
347
|
+
console.log(`🔀 merged: ${merged.length}`);
|
|
348
|
+
console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
|
|
349
|
+
console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
|
|
350
|
+
if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
|
|
351
|
+
console.log(`📄 migration report: ${path.relative(root, report)}`);
|
|
352
352
|
printInstallNextSteps(root, conflicts.length);
|
|
353
353
|
if (conflicts.length > 0) process.exitCode = 1;
|
|
354
354
|
}
|
|
@@ -632,6 +632,89 @@ async function readPackageVersion() {
|
|
|
632
632
|
}
|
|
633
633
|
}
|
|
634
634
|
|
|
635
|
+
async function maybePrintUpdateNotice(currentVersion) {
|
|
636
|
+
if (shouldSkipUpdateCheck()) return;
|
|
637
|
+
if (!isStableSemver(currentVersion)) return;
|
|
638
|
+
|
|
639
|
+
const latestVersion = await fetchLatestVersion();
|
|
640
|
+
if (!latestVersion || !isStableSemver(latestVersion)) return;
|
|
641
|
+
if (compareSemver(latestVersion, currentVersion) <= 0) return;
|
|
642
|
+
|
|
643
|
+
printUpdateNotice(currentVersion, latestVersion);
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
function shouldSkipUpdateCheck() {
|
|
647
|
+
if (process.env.AGENT_HANDOFF_KIT_NO_UPDATE_CHECK === "1") return true;
|
|
648
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_CHECK_FORCE === "1") return false;
|
|
649
|
+
if (process.env.CI) return true;
|
|
650
|
+
if ((process.env.npm_lifecycle_event ?? "").startsWith("qa:")) return true;
|
|
651
|
+
return false;
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
async function fetchLatestVersion() {
|
|
655
|
+
if (process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST) {
|
|
656
|
+
return process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST;
|
|
657
|
+
}
|
|
658
|
+
const url = process.env.AGENT_HANDOFF_KIT_UPDATE_REGISTRY_URL
|
|
659
|
+
?? "https://registry.npmjs.org/@adamchanadam%2Fagent-handoff-kit/latest";
|
|
660
|
+
const timeoutMs = Number.parseInt(process.env.AGENT_HANDOFF_KIT_UPDATE_TIMEOUT_MS ?? "1200", 10);
|
|
661
|
+
const controller = new AbortController();
|
|
662
|
+
const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 1200);
|
|
663
|
+
try {
|
|
664
|
+
const response = await fetch(url, {
|
|
665
|
+
headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
|
|
666
|
+
signal: controller.signal
|
|
667
|
+
});
|
|
668
|
+
if (!response.ok) return null;
|
|
669
|
+
const data = await response.json();
|
|
670
|
+
return typeof data.version === "string" ? data.version : null;
|
|
671
|
+
} catch {
|
|
672
|
+
return null;
|
|
673
|
+
} finally {
|
|
674
|
+
clearTimeout(timer);
|
|
675
|
+
}
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
function isStableSemver(version) {
|
|
679
|
+
return /^\d+\.\d+\.\d+$/.test(version);
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
function compareSemver(left, right) {
|
|
683
|
+
const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
|
|
684
|
+
const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
|
|
685
|
+
for (let i = 0; i < 3; i += 1) {
|
|
686
|
+
if (leftParts[i] > rightParts[i]) return 1;
|
|
687
|
+
if (leftParts[i] < rightParts[i]) return -1;
|
|
688
|
+
}
|
|
689
|
+
return 0;
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
function printUpdateNotice(currentVersion, latestVersion) {
|
|
693
|
+
const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
|
|
694
|
+
const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
|
|
695
|
+
const lines = [
|
|
696
|
+
`✨ Update available! ${currentVersion} -> ${latestVersion}`,
|
|
697
|
+
`Run ${command} to use the latest version.`,
|
|
698
|
+
"",
|
|
699
|
+
"For global installs:",
|
|
700
|
+
"npm install -g @adamchanadam/agent-handoff-kit",
|
|
701
|
+
"",
|
|
702
|
+
"See full release notes:",
|
|
703
|
+
releaseUrl
|
|
704
|
+
];
|
|
705
|
+
const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
|
|
706
|
+
console.log(`╭${"─".repeat(width)}╮`);
|
|
707
|
+
for (const line of lines) {
|
|
708
|
+
console.log(`│ ${line}${" ".repeat(width - visibleLength(line) - 1)}│`);
|
|
709
|
+
}
|
|
710
|
+
console.log(`╰${"─".repeat(width)}╯`);
|
|
711
|
+
console.log("");
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
function visibleLength(text) {
|
|
715
|
+
return [...text].length;
|
|
716
|
+
}
|
|
717
|
+
|
|
635
718
|
function printCard(version, status, eyes) {
|
|
636
719
|
console.log(` /\\_/\\ Agent Handoff Kit v${version}`);
|
|
637
720
|
console.log(` ( ${eyes} ) ${status}`);
|
|
@@ -642,25 +725,24 @@ function printCard(version, status, eyes) {
|
|
|
642
725
|
function printInstallNextSteps(root, conflictCount) {
|
|
643
726
|
console.log("");
|
|
644
727
|
console.log("============================================================");
|
|
645
|
-
console.log("安裝完成:下一步請在 AI 對話中操作");
|
|
728
|
+
console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
|
|
646
729
|
console.log("============================================================");
|
|
647
730
|
if (conflictCount > 0) {
|
|
648
|
-
console.log("狀態:有檔案需要你先處理,詳情見 migration report。");
|
|
649
|
-
console.log("請不要忽略 conflict,也不要直接覆寫既有檔案。");
|
|
731
|
+
console.log("⚠️ 狀態:有檔案需要你先處理,詳情見 migration report。");
|
|
732
|
+
console.log("⚠️ 請不要忽略 conflict,也不要直接覆寫既有檔案。");
|
|
650
733
|
console.log("");
|
|
651
734
|
}
|
|
652
|
-
console.log("請注意:下面文字不是 Terminal 指令。");
|
|
653
|
-
console.log("請打開你要使用的 AI
|
|
735
|
+
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
736
|
+
console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
|
|
654
737
|
console.log("------------------------------------------------------------");
|
|
655
|
-
console.log(`Work in ${root}.`);
|
|
656
|
-
console.log("Read AGENTS.md first. Tell me what you understand before changing files.");
|
|
738
|
+
console.log(`Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
|
|
657
739
|
console.log("------------------------------------------------------------");
|
|
658
740
|
console.log("");
|
|
659
|
-
console.log("然後直接描述你的任務,例如:");
|
|
660
|
-
console.log("整理這個專案,先告訴我你讀到的目前狀態與下一步。");
|
|
741
|
+
console.log("🚀 然後直接描述你的任務,例如:");
|
|
742
|
+
console.log(" 整理這個專案,先告訴我你讀到的目前狀態與下一步。");
|
|
661
743
|
console.log("");
|
|
662
|
-
console.log("如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
663
|
-
console.log("npx @adamchanadam/agent-handoff-kit doctor");
|
|
744
|
+
console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
|
|
745
|
+
console.log(" npx @adamchanadam/agent-handoff-kit doctor");
|
|
664
746
|
console.log("============================================================");
|
|
665
747
|
}
|
|
666
748
|
|
package/package.json
CHANGED
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.1.
|
|
9
|
+
| Agent Handoff Kit template version | 0.1.3 | package prototype |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|