@adamchanadam/agent-handoff-kit 0.4.0 → 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.
package/docs/progress.md CHANGED
@@ -1,67 +1,73 @@
1
- # 專案總覽 / Project dashboard
1
+ # Agent Handoff Kit 進度頁
2
2
 
3
- 對 AI 說「開啟專案進度頁」,或啟用[快捷入口](commands.md)後使用 `/handoff-kit-progress`。Codex 使用 `$handoff-kit-progress` 或從 `/skills` 選取。這是每個已安裝 Kit 的專案共用的固定頁面,無須重新設計 HTML。
3
+ [English](#dashboard)
4
4
 
5
- ## 三個入口
5
+ 在專案的 AI 對話輸入 `/handoff-kit-progress`;Codex 用 `$handoff-kit-progress`,或從 `/skills` 選取。AI 會開啟或重用這個專案的頁面。先看頁面上的專案名稱,避免認錯專案。
6
6
 
7
- - **總覽**:專案名稱、交接記錄的目前工作、各項工作狀態、待完成/等待/待驗收事項、成果及最近變更。「正在查看」只表示你選中的工作,不改變交接狀態。工作排列不表示先後順序,子項完成也不表示整項完成。
8
- - **歷程**:近 7 日、近 30 日、自選日期、關鍵字及工作線篩選。日期標示年份,按封存索引逐批查閱歷史;日期不隱藏目前未完事項。
9
- - **文件導覽**:核心關係圖顯示八種 Kit 文件角色;清單另列已登記的專案文件,並非專案所有檔案。點選節點突出相關文件與方向,查看用途、原文及來源,也可切換清單。沒有明確記錄的關係不靠 AI 猜補。
7
+ ## 可以看到甚麼
10
8
 
11
- 保存紀錄後自動更新,不需要刷新。點選主線、日期及文件時有短動畫;新資料短暫標示改變處,支援減少動畫設定。動畫不代表 AI 正在思考、已驗收或已完整接收交接。
9
+ - **總覽**:目前工作、成果、未完成、等待和待驗收事項。「正在查看」只是你選中的工作,不會改動紀錄。工作排列不是完成順序,完成子項也不代表整項完成。
10
+ - **歷程**:用近 7 日、近 30 日、自選日期、關鍵字和工作篩選,找回已保存的改變。日期篩選不會隱藏目前未完事項。長期紀錄分批讀取,還有內容時可繼續載入;日期排序只包括已載入結果。
11
+ - **文件地圖**:看重要文件的用途、關係及原文。這裏只列已登記文件,不是整個資料夾的所有檔案;沒有記錄的關係不會自行猜補。
12
12
 
13
- 品牌旁的版本讀取專案 `PROJECT_INDEX.md` 的 `Stack`,沿用 Kit 共用讀取方法;「資料依據」另列啟動頁面工具的套件版本。兩者不同會提示,缺失或格式無效則顯示「版本未核實」,不以工具版本代替專案版本。讀取不查網絡、不呼叫 AI,也不升級專案。
13
+ ## 何時更新,會用多少 token
14
14
 
15
- ## 少量維護,不另寫報告
15
+ AI 正常保存工作紀錄後,頁面自行更新,不用刷新,也不用重新設計。AI 只維護有變的進度和必要紀錄,不必記下每一步操作或再寫一份報告。
16
16
 
17
- AI 在正常、已授權的保存時,維護 Index 的專案名稱/目標與 Handoff 的精簡工作表;只改有變的事項,不記錄每一步終端操作。兩份模板定義欄位格式,詳細證據保留在原有位置。尚無工作表項目的專案,直接顯示已有「下一步」及「風險與阻礙」,標明尚未分類,不猜測其狀態。首頁只顯示有界摘要;其餘項目數量與查看完整工作/交接原文的入口一併列出。缺失資訊保持未記錄,不捏造階段、百分比或完成數字。「交接保存」專指交接檔案保存時間,不代表整個專案最後有變更的時間。
17
+ 叫 AI 開頁面和保存紀錄會使用一些 token;之後瀏覽、篩選、動畫和畫面更新不呼叫 AI。沿用安裝時已有的 Node.js 和瀏覽器,不需另外安裝資料庫、Python 或購買金鑰。進度頁程式會隨正常安裝/升級一併準備好;開頁不需下載工具或連接 npm。
18
18
 
19
- 介面支援繁中/英文。來源可選 `Name zh-Hant`、`Goal zh-Hant`、`Title zh-Hant`、`Summary zh-Hant`,缺少則保留原文;日誌也可在正常保存時加入簡短中文標題/摘要,不必回寫歷史翻譯。讀取、篩選、動畫及同步由程式處理,**不呼叫 AI、不要求第二份進度 JSON 或重複報告**。
19
+ 頁面可切換繁體中文和英文。若紀錄本身沒有翻譯,就保留原文。動畫只提示選取或資料變更,不表示 AI 正在思考或工作已驗收。
20
20
 
21
- ## 啟動及環境
21
+ ## 看到缺漏或舊資料時
22
22
 
23
- 沿用 Kit 的 Node.js 與瀏覽器,不需要資料庫、Python、建置工具或 API key。
23
+ | 情況 | 意思與做法 |
24
+ |---|---|
25
+ | 未記錄/尚未分類 | 原有紀錄沒有這項資料。AI 不會猜進度百分比或完成狀態;可查看原文,或請 AI 在正常保存時補清楚。 |
26
+ | 紀錄只顯示一部分 | 首頁先顯示摘要,其餘可看完整工作或原文。歷史資料太多、缺檔或格式有問題時,頁面會提示未讀齊;縮窄日期或請 AI 查明原因。 |
27
+ | 斷線/更新失敗 | 畫面保留上次資料並提示,會自動重試。可按「立即重連」;仍失敗就再用進度頁指令。 |
28
+ | 升級中 | 暫停讀取,等升級完成後再看,避免把更新到一半的內容當作最新。 |
29
+ | 版本未核實/版本不同 | 頁面從專案讀取這套工具的版本;讀不到不會猜。「資料依據」另列開啟頁面的工具版本。有疑問用 `handoff-kit-check`;查最新正式版用 `handoff-kit-update`。 |
24
30
 
25
- ```text
26
- npx --yes @adamchanadam/agent-handoff-kit@latest progress --background --root <project-root>
27
- ```
31
+ 「交接保存」是交接文件的保存時間,不是所有專案檔案最後修改的時間。未保存的聊天內容不會出現。頁面只整理已保存的內容,不能證明 AI 已讀齊交接或成果已經驗收。
28
32
 
29
- `npx` 可能下載 CLI 至快取;未發佈版本使用選定的本機套件。`progress` 自身不查網絡版本、不安裝/升級、不寫回專案。`--background` 啟動或重用同專案、版本與頁面內容的背景服務,開啟瀏覽器後返回。`--no-open` 只給網址;`--port <0-65535>` 指定埠。不停止不相符的服務。
33
+ ## 關掉後怎樣重開
30
34
 
31
- 只綁定 `127.0.0.1`,拒絕跨網站請求及寫入。有頁面連線時持續運作;全部頁面斷線後保留 8 小時,未曾開啟亦保留 8 小時。無連線時停止輪詢紀錄,再次開啟立即讀取最新內容並延長保留時間。超時、電腦重啟或服務結束後,使用既有快捷入口便會重新啟動;舊網址不能自行啟動已停止的本機程式。前景模式可按 Ctrl+C 立即停止。
35
+ 頁面開着時會持續連線。全部頁面關閉後,本機服務保留八小時;閒置時不反覆讀檔。超過時間、電腦重啟或服務停止後,再用同一個進度頁指令即可。舊網址不能自己啟動已停止的程式。
32
36
 
33
- ## 來源及邊界
37
+ 這是你電腦上的檢視頁,不會公開上網。查看、篩選和點選文件不會改檔;它只讀取專案內已登記、允許顯示的文件,原文以文字顯示。請勿把密碼等秘密寫進專案紀錄。
34
38
 
35
- | 內容 | 來源 | 界限 |
36
- |---|---|---|
37
- | 名稱/專案目標 | `dev/PROJECT_INDEX.md` → `Project` | 512 KiB |
38
- | 工作/交接 | `dev/SESSION_HANDOFF.md` → `Work Items` 及原有段落 | 1 MiB;128 項工作 |
39
- | 最近變更 | `dev/SESSION_LOG.md` | 頭 64 KiB、十則完整條目;首頁三則 |
40
- | 歷程 | 主日誌及 `dev/SESSION_LOG_archive/INDEX.md` 登記批次 | 每次 256 KiB 日誌、4 檔、20 結果;索引 512 KiB |
41
- | 文件 | Kit 角色、Index Directory Map / Document Relations、工作 Source | 160 文件;文字預覽 1 MiB |
39
+ ## Dashboard
42
40
 
43
- 自訂文件關係在 Index 的 `## Document Relations` 使用 `From | To | Relation`:已登記的相對路徑及 `references`、`routes`、`mirrors`、`checks`。只表達關係,不授權同步。只讀專案內登記文件,拒絕越界、隱藏設定、機密名稱及遷移內部檔;原文以純文字顯示,不執行 HTML 等內容。已知憑證模式會遮蔽,不代替來源的機密管理。
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.
44
42
 
45
- 首頁與歷程共用同一日誌欄位讀取方式,支援逐行欄位、項目符號、粗體欄位名及縮排續行;中文標題與摘要在兩處一致使用。識別欄位不會被當成摘要。歷程只涵蓋索引登記批次。缺索引、格式錯誤、缺檔、未封口/過大條目、同 Event ID 內容衝突及超限都明示覆蓋不足。日誌可選 `Event ID` 用於搬移去重、`Work` 對應工作 ID;無 Event ID 則用原標題與內容辨識;原有 ID 是 agent/session 識別,可重複。單則上限 64 KiB;每查詢最多記住 10,000 事件,超過請收窄日期。最多 32 個分頁查詢,十五分鐘到期;來源改變即拒絕舊分頁。日期排序只涵蓋已載入結果。
43
+ ### What you can see
46
44
 
47
- 有頁面連線時每半秒檢查狀態,無變動不重讀內容。斷線時保留已顯示資料,以 1、2、4、8、16、30 秒間隔重試,其後每 30 秒一次;回到頁面會提早重連,也可按「立即重連」。服務重啟後會更新歷程及詳情,保留日期、工作選擇及介面語言。失敗提示附可複製的重開口令。首頁不掃歷史;最近查過的 128 份封存檔會監看。文件地圖只檢查登記檔案的存在及時間。讀前/後核對身份與穩定性;無效來源保留上次有效畫面並告警,升級鎖存在即暫停。歷程自動更新每輪最多五個有界請求,更多可繼續查閱。
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
48
 
49
- 一般 Markdown 不是交易格式:結構完整的中間狀態不能永遠與最終意圖區分。來源完成聲稱不等於獨立驗收;總覽不代替 AI 全文接收交接包。
49
+ ### Updates and token use
50
50
 
51
- ## English
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
52
 
53
- The brand badge reads the project's Kit version from `PROJECT_INDEX.md` Stack through the shared Kit reader. Sources also shows the running dashboard package version. Different versions are indicated; missing or invalid project metadata displays “Version unverified”, never the tool version as a substitute. This reads locally without model calls, network version checks or project upgrades.
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
54
 
55
- Open the dashboard through your AI or the [command entry](commands.md). The fixed, reusable view has Overview, History and Documents. Overview shows project identity, current work recorded in handoff, declared work and states, outstanding work and references. “Viewing” only identifies the reader's selection; it does not change recorded work. History includes years in date headings and filters saved events by date, keyword and work ID, reading indexed archives in batches. The core map shows eight Kit document roles; the list also includes registered project files, not every project file. It highlights declared relationships and opens source text. Workstream order is not a sequence; child completion never completes its parent.
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
56
 
57
- At normal authorized saves, maintain only changed meaningful rows in Handoff `Work Items` and stable identity in Index `Project`; their templates own the fields. No extra report, per-terminal-step record or progress JSON is required. Without work rows, existing Next Priorities and Risks / Blockers appear directly as unclassified source text, with no inferred status. Home shows bounded excerpts and a remaining count with access to all work or the handoff source. “Handoff saved” is that file's save time, not the last change across the project. Optional `Name zh-Hant`, `Goal zh-Hant`, `Title zh-Hant` and `Summary zh-Hant` provide Chinese counterparts; otherwise source language is preserved. Logs may carry the Chinese title/summary too, without rewriting history. Missing fields stay unrecorded. Viewing, filtering, motion and live updates make no model calls or source writes.
57
+ ### Missing or older information
58
58
 
59
- Run the command above. Background mode reuses a matching project/version/build service; `--no-open` returns its URL, `--port` selects a port. `npx` may fetch the package; progress itself does not check network versions, install or upgrade. It needs existing Node.js and a browser, not a database, Python, build tools or API keys. It binds only to 127.0.0.1, rejects foreign origins and writes, and remains available for eight hours without connected pages, including before the first connection. File polling stops with no clients and resumes with a fresh read on return. Reopening renews the idle window. After expiry, process exit or a computer restart, use the existing command entry to start it again; a cold browser URL cannot launch a stopped local process. Ctrl+C stops foreground mode; unrelated services are not terminated.
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. |
60
66
 
61
- Home and History share one event reader for plain fields, list fields, bold labels and indented continuations, including Chinese titles and summaries. Identity metadata is never used as the summary.
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.
62
68
 
63
- Limits: Handoff 1 MiB/128 work items; Index 512 KiB; 160 registered documents with 1 MiB text previews; home log prefix 64 KiB/ten complete entries, displaying three. Each history request reads at most 256 KiB from four log files and returns twenty events. Archive selection uses the 512 KiB master index. Each entry is limited to 64 KiB; queries track at most 10,000 identities, then require a narrower date range. Up to 32 cursors expire after fifteen minutes and reject source changes. Global date sorting covers loaded results only. Missing/malformed manifests, missing files, incomplete/oversized entries, Event ID conflicts and capacity limits disclose incomplete coverage. Optional log `Event ID` supports move deduplication; `Work` links a work item; otherwise original title/body identify entries; existing `ID` denotes an agent/session and may repeat.
69
+ ### Reopening the page
64
70
 
65
- Only registered project-relative documents are available. Hidden/secret-related paths, migration internals and real paths outside the project are rejected. Text is escaped; HTML and other executable content are never run. Known credential patterns are redacted as a secondary defense. Optional Index `Document Relations` use `From | To | Relation`, registered relative paths and `references`, `routes`, `mirrors` or `checks`; links grant no write permission.
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.
66
72
 
67
- While pages are connected, metadata is checked every half second; unchanged content is not reread. Disconnection retains the last displayed data and retries after 1, 2, 4, 8, 16 and 30 seconds, then every 30 seconds. Returning to the page or Reconnect now retries sooner. Recovery refreshes history and details, including after server restarts, while preserving filters, selection and UI language. The failure notice includes a copyable reopen prompt. Home does not scan archives; the 128 most recently queried archives are watched. Registered document existence/time is checked. Reads verify identity and stability; invalid input retains the last valid state with warnings, and upgrade locks pause reads. History auto-update makes up to five bounded requests per round; further reading is explicit. Brief transitions and change highlights respect reduced motion, never imply agent reasoning or acceptance. Structurally complete intermediate Markdown can be indistinguishable from intended final state. The dashboard proves neither independent acceptance nor full AI handoff reception.
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.4.0",
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": {