@adamchanadam/agent-handoff-kit 0.3.67 → 0.4.1

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.
@@ -1,98 +1,100 @@
1
- import { createHash } from "node:crypto";
1
+ import { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
2
+ export { parseProjectIndexTemplateVersion, projectIndexTemplateVersionRow, materializeProjectIndexTemplateVersion, markdownVisibleLinesOutsideHiddenBlocks } from './progress/project-version.mjs';
3
+ import { createHash } from "node:crypto";
2
4
  import { lstat, readdir, readFile, realpath } from "node:fs/promises";
3
5
  import path from "node:path";
4
6
  import { installedFileContracts } from "./installed-file-contract.mjs";
5
7
  import { FORMAL_USER_RULES_ENTRY_ANCHOR, readFormalUserRules } from "./user-rules-router.mjs";
6
-
8
+
7
9
  export const UPGRADE_INVENTORY_SCHEMA = 1;
8
-
9
- const formalEntryTargets = Object.freeze([
10
- "AGENTS.md",
11
- "CLAUDE.md",
12
- "GEMINI.md",
13
- "START_NEXT_SESSION_PROMPT.txt"
14
- ]);
15
-
10
+
11
+ const formalEntryTargets = Object.freeze([
12
+ "AGENTS.md",
13
+ "CLAUDE.md",
14
+ "GEMINI.md",
15
+ "START_NEXT_SESSION_PROMPT.txt"
16
+ ]);
17
+
16
18
  const archiveDirectories = Object.freeze([
17
19
  { relative: "dev/SESSION_LOG_archive", classification: "session-log-archive" },
18
20
  { relative: "dev/session_log_archive", classification: "legacy-session-log-archive" }
19
21
  ]);
20
-
22
+
21
23
  /**
22
24
  * Builds a read-only, hash-bound description of the Kit data that an upgrade
23
25
  * can reach now. Ordinary workspace files, generic Markdown references, and
24
26
  * committed historical transaction receipts are not current upgrade authority.
25
27
  */
26
- export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
27
- if (!root) throw new Error("upgrade inventory requires a project root");
28
- const rootPath = path.resolve(root);
29
- const rootStats = await lstat(rootPath).catch((error) => {
30
- if (error?.code === "ENOENT") return null;
31
- throw error;
32
- });
33
- if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
34
- throw new Error("upgrade inventory root must be a real directory");
35
- }
36
- const realRoot = await realpath(rootPath);
28
+ export async function buildUpgradeInventory({ root, contracts = installedFileContracts } = {}) {
29
+ if (!root) throw new Error("upgrade inventory requires a project root");
30
+ const rootPath = path.resolve(root);
31
+ const rootStats = await lstat(rootPath).catch((error) => {
32
+ if (error?.code === "ENOENT") return null;
33
+ throw error;
34
+ });
35
+ if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) {
36
+ throw new Error("upgrade inventory root must be a real directory");
37
+ }
38
+ const realRoot = await realpath(rootPath);
37
39
  const entries = new Map();
38
40
  const blockers = [];
39
-
40
- const addBlocker = (relative, reason) => {
41
- const key = `${relative}\0${reason}`;
42
- if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
43
- };
44
-
41
+
42
+ const addBlocker = (relative, reason) => {
43
+ const key = `${relative}\0${reason}`;
44
+ if (!blockers.some((item) => `${item.path}\0${item.reason}` === key)) blockers.push({ path: relative, reason });
45
+ };
46
+
45
47
  async function addFile(relative, classification, reachability = null) {
46
- const normalized = normalizeProjectRelative(relative);
47
- if (!normalized) {
48
- addBlocker(String(relative), "reference escapes the selected project root");
49
- return null;
50
- }
51
- const absolute = path.resolve(rootPath, normalized);
52
- if (!isInside(rootPath, absolute)) {
53
- addBlocker(normalized, "reference escapes the selected project root");
54
- return null;
55
- }
56
- const stats = await lstat(absolute).catch((error) => {
57
- if (error?.code === "ENOENT") return null;
58
- throw error;
59
- });
60
- if (!stats) return null;
61
- if (stats.isSymbolicLink()) {
62
- addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
63
- return null;
64
- }
65
- if (!stats.isFile()) {
66
- addBlocker(normalized, "inventory source is not a regular file");
67
- return null;
68
- }
69
- const resolved = await realpath(absolute);
70
- if (!isInside(realRoot, resolved)) {
71
- addBlocker(normalized, "resolved inventory source is outside the selected project root");
72
- return null;
73
- }
74
-
75
- const buffer = await readFile(absolute);
76
- let entry = entries.get(normalized);
77
- if (!entry) {
78
- entry = {
79
- path: normalized,
80
- sha256: sha256(buffer),
81
- bytes: buffer.length,
82
- classifications: new Set(),
83
- reachability: new Map(),
84
- text: decodeUtf8(buffer)
85
- };
86
- entries.set(normalized, entry);
87
- }
88
- entry.classifications.add(classification);
89
- if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
48
+ const normalized = normalizeProjectRelative(relative);
49
+ if (!normalized) {
50
+ addBlocker(String(relative), "reference escapes the selected project root");
51
+ return null;
52
+ }
53
+ const absolute = path.resolve(rootPath, normalized);
54
+ if (!isInside(rootPath, absolute)) {
55
+ addBlocker(normalized, "reference escapes the selected project root");
56
+ return null;
57
+ }
58
+ const stats = await lstat(absolute).catch((error) => {
59
+ if (error?.code === "ENOENT") return null;
60
+ throw error;
61
+ });
62
+ if (!stats) return null;
63
+ if (stats.isSymbolicLink()) {
64
+ addBlocker(normalized, "symbolic links and junctions are not accepted as inventory sources");
65
+ return null;
66
+ }
67
+ if (!stats.isFile()) {
68
+ addBlocker(normalized, "inventory source is not a regular file");
69
+ return null;
70
+ }
71
+ const resolved = await realpath(absolute);
72
+ if (!isInside(realRoot, resolved)) {
73
+ addBlocker(normalized, "resolved inventory source is outside the selected project root");
74
+ return null;
75
+ }
76
+
77
+ const buffer = await readFile(absolute);
78
+ let entry = entries.get(normalized);
79
+ if (!entry) {
80
+ entry = {
81
+ path: normalized,
82
+ sha256: sha256(buffer),
83
+ bytes: buffer.length,
84
+ classifications: new Set(),
85
+ reachability: new Map(),
86
+ text: decodeUtf8(buffer)
87
+ };
88
+ entries.set(normalized, entry);
89
+ }
90
+ entry.classifications.add(classification);
91
+ if (reachability) entry.reachability.set(`${reachability.from}\0${reachability.via}`, reachability);
90
92
  return entry;
91
93
  }
92
-
93
- for (const contract of contracts) {
94
- const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
95
- await addFile(
94
+
95
+ for (const contract of contracts) {
96
+ const isFormalEntry = formalEntryTargets.includes(contract.targetRel);
97
+ await addFile(
96
98
  contract.targetRel,
97
99
  "managed-contract",
98
100
  isFormalEntry ? { from: "formal-entry", via: contract.targetRel } : { from: "managed-contract", via: contract.targetRel }
@@ -115,54 +117,54 @@ export async function buildUpgradeInventory({ root, contracts = installedFileCon
115
117
  addBlocker("dev/USER_RULES.md", `formal user-rules state is unsafe: ${String(error?.message ?? error)}`);
116
118
  }
117
119
  }
118
-
119
- const frozenEntries = [...entries.values()]
120
- .map((entry) => ({
121
- path: entry.path,
122
- sha256: entry.sha256,
123
- bytes: entry.bytes,
124
- classifications: [...entry.classifications].sort(),
125
- reachability: [...entry.reachability.values()]
126
- .sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
127
- }))
128
- .sort((left, right) => left.path.localeCompare(right.path));
129
- const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
130
- const digestInput = {
131
- schemaVersion: UPGRADE_INVENTORY_SCHEMA,
132
- entries: frozenEntries,
133
- blockers: sortedBlockers
134
- };
135
-
136
- return Object.freeze({
137
- schemaVersion: UPGRADE_INVENTORY_SCHEMA,
138
- status: sortedBlockers.length === 0 ? "ready" : "blocked",
139
- entries: frozenEntries,
140
- blockers: sortedBlockers,
141
- inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
142
- formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
143
- });
144
-
120
+
121
+ const frozenEntries = [...entries.values()]
122
+ .map((entry) => ({
123
+ path: entry.path,
124
+ sha256: entry.sha256,
125
+ bytes: entry.bytes,
126
+ classifications: [...entry.classifications].sort(),
127
+ reachability: [...entry.reachability.values()]
128
+ .sort((left, right) => `${left.from}\0${left.via}`.localeCompare(`${right.from}\0${right.via}`))
129
+ }))
130
+ .sort((left, right) => left.path.localeCompare(right.path));
131
+ const sortedBlockers = blockers.sort((left, right) => `${left.path}\0${left.reason}`.localeCompare(`${right.path}\0${right.reason}`));
132
+ const digestInput = {
133
+ schemaVersion: UPGRADE_INVENTORY_SCHEMA,
134
+ entries: frozenEntries,
135
+ blockers: sortedBlockers
136
+ };
137
+
138
+ return Object.freeze({
139
+ schemaVersion: UPGRADE_INVENTORY_SCHEMA,
140
+ status: sortedBlockers.length === 0 ? "ready" : "blocked",
141
+ entries: frozenEntries,
142
+ blockers: sortedBlockers,
143
+ inventorySha256: sha256(Buffer.from(`${JSON.stringify(digestInput)}\n`, "utf8")),
144
+ formalEntryTargets: formalEntryTargets.filter((target) => entries.has(target))
145
+ });
146
+
145
147
  async function addTree(relativeDirectory, classification) {
146
- const normalized = normalizeProjectRelative(relativeDirectory);
147
- if (!normalized) {
148
+ const normalized = normalizeProjectRelative(relativeDirectory);
149
+ if (!normalized) {
148
150
  addBlocker(String(relativeDirectory), "dynamic directory escapes the selected project root");
149
151
  return;
150
152
  }
151
153
  const absolute = path.resolve(rootPath, normalized);
152
154
  const stats = await lstat(absolute).catch((error) => {
153
155
  if (error?.code === "ENOENT") return null;
154
- throw error;
155
- });
156
- if (!stats) return;
157
- if (!stats.isDirectory() || stats.isSymbolicLink()) {
158
- addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
159
- return;
160
- }
161
- const resolved = await realpath(absolute);
162
- if (!isInside(realRoot, resolved)) {
163
- addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
164
- return;
165
- }
156
+ throw error;
157
+ });
158
+ if (!stats) return;
159
+ if (!stats.isDirectory() || stats.isSymbolicLink()) {
160
+ addBlocker(normalized, "dynamic inventory directory is not a safe real directory");
161
+ return;
162
+ }
163
+ const resolved = await realpath(absolute);
164
+ if (!isInside(realRoot, resolved)) {
165
+ addBlocker(normalized, "dynamic inventory directory resolves outside the selected project root");
166
+ return;
167
+ }
166
168
  for (const item of await readdir(absolute, { withFileTypes: true })) {
167
169
  const child = `${normalized}/${item.name}`;
168
170
  const childAbsolute = path.join(absolute, item.name);
@@ -193,171 +195,49 @@ export async function readProjectIndexTemplateVersion(root) {
193
195
  return parseProjectIndexTemplateVersion(bytes.toString("utf8"));
194
196
  }
195
197
 
196
- export function parseProjectIndexTemplateVersion(text) {
197
- return projectIndexTemplateVersionEvidence(text)?.version ?? null;
198
+ export function extractExplicitLocalReferences(text) {
199
+ const matches = new Map();
200
+ const add = (raw, via) => {
201
+ const normalized = normalizeReference(raw);
202
+ if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
203
+ };
204
+ for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
205
+ for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
206
+ for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
207
+ // Do not treat the dot before a filename extension as sentence punctuation.
208
+ // On Windows, the truncated `dev/USER_RULES` then aliases the real
209
+ // `dev/user_rules/` directory, making a valid formal router look unsafe.
210
+ for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
211
+ return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
198
212
  }
199
213
 
200
- export function projectIndexTemplateVersionRow(text) {
201
- return projectIndexTemplateVersionEvidence(text)?.row ?? null;
214
+ function normalizeReference(raw) {
215
+ const value = String(raw).trim().replace(/^<|>$/g, "");
216
+ if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
217
+ const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
218
+ if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
219
+ return normalizeProjectRelative(withoutFragment);
202
220
  }
203
221
 
204
- export function materializeProjectIndexTemplateVersion(text, version) {
205
- if (!isStableSemver(version)) return text;
206
- const evidence = projectIndexTemplateVersionEvidence(text);
207
- if (!evidence) return text;
208
- return String(text).slice(0, evidence.rowStart)
209
- + evidence.row.replace(`| ${evidence.version} |`, `| ${version} |`)
210
- + String(text).slice(evidence.rowEnd);
222
+ function normalizeProjectRelative(relative) {
223
+ const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
224
+ if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
225
+ return normalized;
211
226
  }
212
227
 
213
- function projectIndexTemplateVersionEvidence(text) {
214
- const value = String(text);
215
- const normalized = value.replace(/\r\n/g, "\n");
216
- const visibleLines = markdownVisibleLinesOutsideHiddenBlocks(value);
217
- const headings = [];
218
- for (const item of visibleLines) if (/^## [^\r\n]+$/u.test(item.text)) headings.push({ title: item.text.trim(), line: item.line, offset: item.normalizedStart });
219
- const stackHeadings = headings.filter((heading) => heading.title === "## Stack");
220
- if (stackHeadings.length !== 1) return null;
221
- const stack = stackHeadings[0];
222
- const nextHeading = headings.find((heading) => heading.line > stack.line);
223
- const stackStart = stack.offset + visibleLines.find((line) => line.line === stack.line)?.text.length + 1;
224
- const stackEnd = nextHeading ? nextHeading.offset : normalized.length;
225
- const stackLines = visibleLines.filter((line) => line.normalizedStart >= stackStart && line.normalizedStart < stackEnd);
226
- const candidateRows = [];
227
- const rowPattern = /^\| Agent Handoff Kit template version \| ([^|\n]+) \| [^|\n]+ \|$/u;
228
- for (const line of stackLines) {
229
- const match = rowPattern.exec(line.text);
230
- if (!match) continue;
231
- const version = match[1].trim();
232
- if (!isStableSemver(version)) return null;
233
- candidateRows.push({
234
- version,
235
- row: line.text,
236
- rowStart: line.start,
237
- rowEnd: line.end
238
- });
239
- }
240
- const versionLabelRows = stackLines.filter((line) => line.text.startsWith("| Agent Handoff Kit template version |"));
241
- if (versionLabelRows.length !== candidateRows.length || candidateRows.length !== 1) return null;
242
- const [row] = candidateRows;
243
- return { version: row.version, row: row.row, rowStart: row.rowStart, rowEnd: row.rowEnd };
228
+ function isInside(root, target) {
229
+ const relative = path.relative(path.resolve(root), path.resolve(target));
230
+ return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
244
231
  }
245
232
 
246
- export function markdownVisibleLinesOutsideHiddenBlocks(text) {
247
- const value = String(text);
248
- const normalized = value.replace(/\r\n/g, "\n");
249
- const lines = normalized.split("\n");
250
- const result = [];
251
- let offset = 0;
252
- let fence = null;
253
- let inComment = false;
254
- for (let index = 0; index < lines.length; index += 1) {
255
- const line = lines[index];
256
- if (inComment) {
257
- if (line.includes("-->")) inComment = false;
258
- offset += line.length + 1;
259
- continue;
260
- }
261
- const fenceMatch = /^\s{0,3}(`{3,}|~{3,})(?![`~])(.*)$/u.exec(line);
262
- const fenceRun = fenceMatch?.[1] ?? null;
263
- if (fence) {
264
- if (
265
- fenceRun
266
- && fenceRun[0] === fence.char
267
- && fenceRun.length >= fence.length
268
- && /^\s*$/u.test(fenceMatch?.[2] ?? "")
269
- ) {
270
- fence = null;
271
- }
272
- offset += line.length + 1;
273
- continue;
274
- }
275
- if (fenceRun) {
276
- fence = { char: fenceRun[0], length: fenceRun.length };
277
- offset += line.length + 1;
278
- continue;
279
- }
280
- const commentStart = line.indexOf("<!--");
281
- if (commentStart >= 0) {
282
- if (line.indexOf("-->", commentStart + 4) < 0) inComment = true;
283
- offset += line.length + 1;
284
- continue;
285
- }
286
- result.push({
287
- text: line,
288
- line: index,
289
- normalizedStart: offset,
290
- normalizedEnd: offset + line.length,
291
- start: originalOffsetForNormalizedOffset(value, offset),
292
- end: originalOffsetForNormalizedOffset(value, offset + line.length)
293
- });
294
- offset += line.length + 1;
233
+ function decodeUtf8(buffer) {
234
+ try {
235
+ return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
236
+ } catch {
237
+ return null;
295
238
  }
296
- return result;
297
239
  }
298
240
 
299
- function originalOffsetForNormalizedOffset(text, normalizedOffset) {
300
- let original = 0;
301
- let normalized = 0;
302
- while (original < text.length && normalized < normalizedOffset) {
303
- if (text[original] === "\r" && text[original + 1] === "\n") {
304
- original += 2;
305
- normalized += 1;
306
- } else {
307
- original += 1;
308
- normalized += 1;
309
- }
310
- }
311
- return original;
312
- }
313
-
314
- function isStableSemver(value) {
315
- return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.test(String(value));
241
+ function sha256(value) {
242
+ return createHash("sha256").update(value).digest("hex");
316
243
  }
317
-
318
- export function extractExplicitLocalReferences(text) {
319
- const matches = new Map();
320
- const add = (raw, via) => {
321
- const normalized = normalizeReference(raw);
322
- if (normalized) matches.set(`${normalized}\0${via}`, { path: normalized, via });
323
- };
324
- for (const match of String(text).matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+[^)]*)?\)/g)) add(match[1], "markdown-link");
325
- for (const match of String(text).matchAll(/`([^`\r\n]+)`/g)) add(match[1], "inline-code-path");
326
- for (const match of String(text).matchAll(/^\s*@([^\s]+)\s*$/gm)) add(match[1], "bridge-import");
327
- // Do not treat the dot before a filename extension as sentence punctuation.
328
- // On Windows, the truncated `dev/USER_RULES` then aliases the real
329
- // `dev/user_rules/` directory, making a valid formal router look unsafe.
330
- for (const match of String(text).matchAll(/(?:^|[\s("'`])((?:[\p{L}\p{N}_-]+[\\/])+[\p{L}\p{N}_. -]*[\p{L}\p{N}_.-])(?=$|[\s,;:,。!?)\]}>"'])/gu)) add(match[1], "plain-local-path");
331
- return [...matches.values()].sort((left, right) => `${left.path}\0${left.via}`.localeCompare(`${right.path}\0${right.via}`));
332
- }
333
-
334
- function normalizeReference(raw) {
335
- const value = String(raw).trim().replace(/^<|>$/g, "");
336
- if (!value || value.includes("://") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/")) return null;
337
- const withoutFragment = value.split(/[?#]/, 1)[0].replaceAll("\\", "/");
338
- if (!withoutFragment || withoutFragment.endsWith("/") || (!withoutFragment.includes("/") && !/\.[\p{L}\p{N}]+$/u.test(withoutFragment))) return null;
339
- return normalizeProjectRelative(withoutFragment);
340
- }
341
-
342
- function normalizeProjectRelative(relative) {
343
- const normalized = path.posix.normalize(String(relative).replaceAll("\\", "/").replace(/^\.\//, ""));
344
- if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
345
- return normalized;
346
- }
347
-
348
- function isInside(root, target) {
349
- const relative = path.relative(path.resolve(root), path.resolve(target));
350
- return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
351
- }
352
-
353
- function decodeUtf8(buffer) {
354
- try {
355
- return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
356
- } catch {
357
- return null;
358
- }
359
- }
360
-
361
- function sha256(value) {
362
- return createHash("sha256").update(value).digest("hex");
363
- }
@@ -0,0 +1,61 @@
1
+ # Agent Handoff Kit 常用指令
2
+
3
+ [English](#shortcuts)
4
+
5
+ 這份說明包含尚未發布的更新;正式下載可用的功能,以已發布版本為準。
6
+
7
+ 在專案的 AI 對話輸入指令,不是在終端機。Claude Code、Gemini CLI、Antigravity CLI 用 /;Codex 用 $,也可從 /skills 選取。 例如 Codex 用 `$handoff-kit-start`。
8
+
9
+ | 想做甚麼 | 指令 |
10
+ |---|---|
11
+ | 接回上次工作 | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#start) |
12
+ | 看專案全貌 | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#progress) |
13
+ | 準備結束這次對話 | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#close) |
14
+ | 第一次用,想有人帶路 | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#onboard) |
15
+ | 忘了用哪個指令 | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#help) |
16
+ | 讓下次 AI 找得到重要文件 | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#align) |
17
+ | 希望以後都照這樣做 | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#remember) |
18
+ | 交接功能出了問題 | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#check) |
19
+ | 想用最新正式版 | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html#update) |
20
+
21
+ 日常用開工、進度頁、收工;其他按需要用。每個指令的例子與注意事項都在[使用指南](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html),不用另外讀一套教學。
22
+
23
+ ### 安裝與選單
24
+
25
+ 安裝或升級時,指令入口會一併放好,只供目前專案使用,不安裝到電腦的共用設定。不用額外啟用。舊對話未顯示時,重新開啟專案對話;Gemini CLI 可用 `/commands reload`。Codex 選單有簡短中英文說明,例如「開工 / Start」。
26
+
27
+ 如果入口缺漏,把[安裝頁](../agent-handoff-kit-ai-install.html)的句子交給 AI。同版本也可補齊缺項;你的自訂內容遇到衝突會保留並停止,不會強行覆寫。檔案齊備只證明安裝結果,實際選單和呼叫仍須在所用工具確認。
28
+
29
+ ### 使用成本
30
+
31
+ 叫 AI 執行指令及平常保存紀錄會使用一些 token。進度頁開啟後,查看、篩選和自動更新由本機程式處理,不再叫 AI 寫報告。[進度頁說明](progress.md)包含重開、斷線和資料不完整時的處理。
32
+
33
+ ## Shortcuts
34
+
35
+ This guide includes updates that have not been released yet. Features available to download depend on the published version.
36
+
37
+ Enter shortcuts in your project’s AI conversation, not in the terminal. Claude Code, Gemini CLI and Antigravity CLI use /; Codex uses $, or selection through /skills. For example, Codex uses `$handoff-kit-start`.
38
+
39
+ | What you want to do | Shortcut |
40
+ |---|---|
41
+ | Pick up where you left off | [`/handoff-kit-start`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#start) |
42
+ | See the whole project | [`/handoff-kit-progress`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#progress) |
43
+ | Finish this conversation | [`/handoff-kit-close`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#close) |
44
+ | Get help getting started | [`/handoff-kit-onboard`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#onboard) |
45
+ | Find the right shortcut | [`/handoff-kit-help`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#help) |
46
+ | Help the next AI find an important file | [`/handoff-kit-align`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#align) |
47
+ | Keep a working preference for next time | [`/handoff-kit-remember`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#remember) |
48
+ | Check whether the tool is installed correctly | [`/handoff-kit-check`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#check) |
49
+ | Get the latest released version | [`/handoff-kit-update`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html#update) |
50
+
51
+ Start, Progress and Wrap up are the everyday shortcuts; use the others as needed. Examples and limits for each are in the [guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html), so you do not need a second set of instructions.
52
+
53
+ ### Installation and menus
54
+
55
+ Installation and upgrades include the shortcuts for this project only, not shared computer-wide settings. No separate activation is needed. If an older conversation does not show them, reopen the project conversation; Gemini CLI can use `/commands reload`. Codex has short bilingual labels such as “開工 / Start”.
56
+
57
+ For missing entries, give the AI the sentence on the [setup page](../agent-handoff-kit-ai-install.en.html). Reapplying the same version can fill missing files. Conflicting custom content is kept and the operation stops, without forced overwrites. Complete files prove installation only; check menus and invocation in the tool you use.
58
+
59
+ ### Usage cost
60
+
61
+ Asking the AI to run a shortcut and saving normal records use some tokens. Once the dashboard is open, viewing, filtering and automatic updates run locally without asking the AI to write another report. [Dashboard help](progress.md) covers reopening, disconnections and incomplete data.
@@ -0,0 +1,73 @@
1
+ # Agent Handoff Kit 進度頁
2
+
3
+ [English](#dashboard)
4
+
5
+ 在專案的 AI 對話輸入 `/handoff-kit-progress`;Codex 用 `$handoff-kit-progress`,或從 `/skills` 選取。AI 會開啟或重用這個專案的頁面。先看頁面上的專案名稱,避免認錯專案。
6
+
7
+ ## 可以看到甚麼
8
+
9
+ - **總覽**:目前工作、成果、未完成、等待和待驗收事項。「正在查看」只是你選中的工作,不會改動紀錄。工作排列不是完成順序,完成子項也不代表整項完成。
10
+ - **歷程**:用近 7 日、近 30 日、自選日期、關鍵字和工作篩選,找回已保存的改變。日期篩選不會隱藏目前未完事項。長期紀錄分批讀取,還有內容時可繼續載入;日期排序只包括已載入結果。
11
+ - **文件地圖**:看重要文件的用途、關係及原文。這裏只列已登記文件,不是整個資料夾的所有檔案;沒有記錄的關係不會自行猜補。
12
+
13
+ ## 何時更新,會用多少 token
14
+
15
+ AI 正常保存工作紀錄後,頁面自行更新,不用刷新,也不用重新設計。AI 只維護有變的進度和必要紀錄,不必記下每一步操作或再寫一份報告。
16
+
17
+ 叫 AI 開頁面和保存紀錄會使用一些 token;之後瀏覽、篩選、動畫和畫面更新不呼叫 AI。沿用安裝時已有的 Node.js 和瀏覽器,不需另外安裝資料庫、Python 或購買金鑰。進度頁程式會隨正常安裝/升級一併準備好;開頁不需下載工具或連接 npm。
18
+
19
+ 頁面可切換繁體中文和英文。若紀錄本身沒有翻譯,就保留原文。動畫只提示選取或資料變更,不表示 AI 正在思考或工作已驗收。
20
+
21
+ ## 看到缺漏或舊資料時
22
+
23
+ | 情況 | 意思與做法 |
24
+ |---|---|
25
+ | 未記錄/尚未分類 | 原有紀錄沒有這項資料。AI 不會猜進度百分比或完成狀態;可查看原文,或請 AI 在正常保存時補清楚。 |
26
+ | 紀錄只顯示一部分 | 首頁先顯示摘要,其餘可看完整工作或原文。歷史資料太多、缺檔或格式有問題時,頁面會提示未讀齊;縮窄日期或請 AI 查明原因。 |
27
+ | 斷線/更新失敗 | 畫面保留上次資料並提示,會自動重試。可按「立即重連」;仍失敗就再用進度頁指令。 |
28
+ | 升級中 | 暫停讀取,等升級完成後再看,避免把更新到一半的內容當作最新。 |
29
+ | 版本未核實/版本不同 | 頁面從專案讀取這套工具的版本;讀不到不會猜。「資料依據」另列開啟頁面的工具版本。有疑問用 `handoff-kit-check`;查最新正式版用 `handoff-kit-update`。 |
30
+
31
+ 「交接保存」是交接文件的保存時間,不是所有專案檔案最後修改的時間。未保存的聊天內容不會出現。頁面只整理已保存的內容,不能證明 AI 已讀齊交接或成果已經驗收。
32
+
33
+ ## 關掉後怎樣重開
34
+
35
+ 頁面開着時會持續連線。全部頁面關閉後,本機服務保留八小時;閒置時不反覆讀檔。超過時間、電腦重啟或服務停止後,再用同一個進度頁指令即可。舊網址不能自己啟動已停止的程式。
36
+
37
+ 這是你電腦上的檢視頁,不會公開上網。查看、篩選和點選文件不會改檔;它只讀取專案內已登記、允許顯示的文件,原文以文字顯示。請勿把密碼等秘密寫進專案紀錄。
38
+
39
+ ## Dashboard
40
+
41
+ In your project’s AI conversation, enter `/handoff-kit-progress`. In Codex, use `$handoff-kit-progress` or select it through `/skills`. The AI opens or reuses that project’s page. Check the displayed project name so you know which project you are viewing.
42
+
43
+ ### What you can see
44
+
45
+ - **Overview**: current work, results, unfinished items, things waiting and work awaiting checks. “Viewing” identifies your selection without changing records. The order of work items is not a completion sequence, and completing a child does not complete its parent.
46
+ - **History**: find saved changes using the last 7 days, last 30 days, custom dates, keywords and work filters. Date filters do not hide current outstanding items. Long histories load in batches; load more when available. Date sorting covers only loaded results.
47
+ - **Documents**: see important files, their purpose, connections and source text. Only registered files appear, not every file in the folder. Unrecorded connections are not invented.
48
+
49
+ ### Updates and token use
50
+
51
+ The page updates when the AI saves normal work records, without a refresh or redesign. The AI maintains changed progress and necessary records, rather than logging every action or writing a second report.
52
+
53
+ Asking the AI to open the page and saving records use some tokens. After that, browsing, filters, animation and page updates make no AI calls. It uses the tool’s existing Node.js and your browser; no database, Python or purchased key is needed. Normal installation or upgrade supplies the progress program; opening it requires no tool download or npm connection.
54
+
55
+ The interface switches between Traditional Chinese and English. Records without a translation keep their original language. Animation indicates a selection or changed data, not AI thinking or accepted work.
56
+
57
+ ### Missing or older information
58
+
59
+ | What you see | What it means and what to do |
60
+ |---|---|
61
+ | Unrecorded / unclassified | The records lack that information. No progress percentages or completion states are guessed. Read the source or ask the AI to clarify it during a normal save. |
62
+ | Only part of the history | Home shows summaries with links to full work or sources. Large histories, missing files or formatting problems produce an incomplete-coverage notice. Narrow the dates or ask the AI to investigate. |
63
+ | Disconnected / update failed | The page keeps the last data with a warning and retries. Select “Reconnect now”, or use the Progress shortcut again if it still fails. |
64
+ | Upgrade in progress | Reading pauses until the upgrade finishes, so partly updated files are not treated as current. |
65
+ | Version unverified / versions differ | The page reads the version recorded in this project and does not guess if it is unavailable. Sources also lists the tool version that opened the page. Use `handoff-kit-check` for concerns or `handoff-kit-update` to check the latest release. |
66
+
67
+ “Handoff saved” is the handoff file’s save time, not the last change to every project file. Unsaved chat content does not appear. The page organizes saved records; it does not prove that the AI has read the full handoff or that the work has passed its checks.
68
+
69
+ ### Reopening the page
70
+
71
+ The service stays connected while a page is open. After all pages close, it remains available for eight hours without repeatedly reading files while idle. After that, a computer restart or a stopped service, use the same Progress shortcut again. An old browser address cannot start a stopped program by itself.
72
+
73
+ This is a view on your computer, not a public website. Browsing, filtering and selecting files do not edit them. Only registered files within the project that are allowed for display are read, and their contents are shown as text. Do not put passwords or other secrets into project records.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.67",
3
+ "version": "0.4.1",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,6 +11,8 @@
11
11
  "runtime-core/",
12
12
  "packs/",
13
13
  "README.md",
14
+ "docs/progress.md",
15
+ "docs/commands.md",
14
16
  "LICENSE"
15
17
  ],
16
18
  "engines": {