@adamchanadam/agent-handoff-kit 0.3.66 → 0.4.0
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.en.md +230 -197
- package/README.md +222 -189
- package/bin/agent-handoff-kit.mjs +200 -59
- package/bin/commands.mjs +86 -0
- package/bin/handoff-read.mjs +88 -0
- package/bin/migration-baselines/official-origin-catalog.json +381 -1
- package/bin/progress/ICON-LICENSE.txt +21 -0
- package/bin/progress/agent-handoff-kit-logo2-256.png +0 -0
- package/bin/progress/dashboard-hero.png +0 -0
- package/bin/progress/dashboard.mjs +134 -0
- package/bin/progress/icons.svg +36 -0
- package/bin/progress/index.html +28 -0
- package/bin/progress/open.mjs +42 -0
- package/bin/progress/projection.mjs +144 -0
- package/bin/progress/renderer.js +151 -0
- package/bin/progress/server.mjs +76 -0
- package/bin/progress/styles.css +31 -0
- package/docs/commands.md +59 -0
- package/docs/progress.md +67 -0
- package/package.json +3 -1
- package/packs/closeout.md +72 -67
- package/runtime-core/AGENTS.core.md +124 -103
- package/runtime-core/PROJECT_INDEX.md +8 -1
- package/runtime-core/SESSION_HANDOFF.md +158 -148
- package/runtime-core/SESSION_LOG.md +2 -0
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
// Fixed, bilingual UI. No model requests or project-specific content.
|
|
2
|
+
'use strict';
|
|
3
|
+
(()=>{
|
|
4
|
+
const $=s=>document.querySelector(s),dict={
|
|
5
|
+
handoffSaved:['交接保存:{date}','Handoff saved: {date}'],recordedCurrent:['交接記錄的目前工作','Current work recorded in handoff'],legacyWork:['尚未分類;以下直接顯示交接紀錄。','Not classified yet. Showing the handoff records below.'],morePending:['另有 {n} 項,查看全部工作','{n} more items · View all work'],moreLegacy:['另有 {n} 項,查看交接原文','{n} more items · Read the handoff'],coreScope:['圖中顯示 {n} 份 Kit 核心文件;清單另列已登記的專案文件。','The map shows {n} Kit core documents. The list includes other registered project files.'],listScope:['已列出 {n} 份文件;只讀已登記路徑,不掃描整個專案。','{n} listed files; only registered paths are read, without scanning the whole project.'],
|
|
6
|
+
retryNow:['立即重連','Reconnect now'],reopenPrompt:['開啟專案進度頁','Open the project dashboard'],reopenCopy:['複製重開口令','Copy reopen prompt'],reconnectNote:['連線暫時中斷,保留上次資料並自動重連。若服務已停止,請在此專案的 AI 輸入重開口令。','Connection interrupted. Keeping the last data and reconnecting automatically. If the service stopped, use the reopen prompt in this project’s AI.'],projectKit:['專案 Kit','Project Kit'],viewerKit:['頁面工具','Dashboard tool'],versionUnknown:['版本未核實','Version unverified'],versionDifference:['版本不同','Versions differ'],versionDifferenceNote:['專案與頁面工具版本不同;開啟頁面不會升級專案。','Project and dashboard tool versions differ. Opening this page does not upgrade the project.'],versionSource:['專案版本讀自 PROJECT_INDEX.md 的 Stack;頁面工具版本讀自啟動套件。','Project version comes from PROJECT_INDEX.md Stack; dashboard tool version comes from the running package.'],
|
|
7
|
+
workRetained:['更新暫停,這裏顯示上次有效紀錄。','Updates paused. Showing the last valid record.'],eventSnapshot:['這則為開啟時的紀錄;來源已變,請從歷程重新選取。','This is the record opened earlier. Its source changed; reselect it in History.'],allWorkstreams:['所有工作線','All workstreams'],selectMap:['點選節點,突出顯示相關文件。','Select a node to highlight related documents.'],skip:['跳到內容','Skip to content'],overview:['總覽','Overview'],history:['歷程','History'],documents:['文件地圖','Document map'],project:['專案工作總覽','PROJECT DASHBOARD'],workstreams:['本專案工作','Project work'],recent:['最近變更','Recent changes'],viewHistory:['查看歷程','View history'],outstanding:['待辦事項','Outstanding work'],allWork:['全部工作','All work'],results:['成果與參考','Results & references'],documentRelations:['文件關係','Document connections'],documentIntro:['從目前交接,找回紀錄與依據。','Find the records and sources behind your handoff.'],viewMap:['查看地圖','View map'],projectHistory:['專案歷程','Project history'],historyIntro:['找回每次改變與交接的脈絡。','Follow the changes and the context behind each handoff.'],last7:['近7日','7 days'],last30:['近30日','30 days'],allDates:['全部日期','All dates'],from:['由','From'],to:['至','To'],search:['查找紀錄','Search records'],apply:['查看','Show'],loadMore:['繼續查閱紀錄','Continue reading'],dateBoundary:['日期只篩選歷程,目前未完事項不受影響。','Dates filter recorded events, not current outstanding work.'],documentsHeading:['專案文件導覽','Project documents'],documentsIntro:['核心文件看關係,其他已登記文件看清單。','Explore core document relationships or browse the registered file list.'],map:['核心關係','Core map'],list:['文件清單','File list'],mapBoundary:['連線表示已記錄的文件角色或關係;不代表已驗收。','Connections show declared roles and relationships, not acceptance.'],boundary:['依已保存紀錄更新;未保存的工作不會出現在這裏。','Updates from saved records. Unsaved work is not shown.'],sources:['資料依據','Sources'],empty:['尚未讀到交接紀錄。','No handoff records available yet.'],missing:['尚未記錄','Not recorded'],connected:['已連線','Connected'],offlineLabel:['連線中斷','Disconnected'],waiting:['連接中','Connecting'],interrupted:['更新待恢復','Updates paused'],close:['關閉','Close'],saved:['最後保存:{date}','Last saved: {date}'],focus:['正在查看','Viewing'],viewWork:['查看這項工作','View this work'],moreWork:['另有 {n} 條工作線','{n} more workstreams'],noWork:['尚未整理工作主線;可先查看目前交接。','Workstreams are not recorded yet. Read the current handoff.'],unknownState:['狀態未記錄','State not recorded'],noOutstanding:['未有明確記錄的未完項目;不代表全部完成。','No explicit outstanding items are recorded. This does not imply completion.'],noResults:['尚未登記成果入口。','No result links are registered yet.'],noEvents:['所選期間未找到紀錄。','No records found in this date range.'],noRecent:['尚未讀到近期紀錄。','No recent records loaded yet.'],showSource:['查看來源','Read source'],showDocument:['查看文件','Read document'],copied:['已複製','Copied'],copyPath:['複製路徑','Copy path'],copyFailed:['未能自動複製,請選取上方路徑。','Select the path above to copy it manually.'],sourceText:['原始紀錄','Source record'],purpose:['用途','Purpose'],parent:['所屬工作','Parent work'],children:['相關子項目','Related work'],relationships:['文件關係','Document relationships'],available:['檔案存在','File present'],notAvailable:['檔案未找到','File not found'],fileUnknown:['此格式可從專案檔案開啟;這裏不執行文件。','Open this format from the project. This page does not execute files.'],sourceChanged:['來源已更新,內容已同步。','Source updated. This view is current.'],loading:['正在讀取…','Loading…'],unavailable:['暫未能讀取,保留已顯示的內容。','Could not read this record. Existing content is retained.'],offline:['連接暫時中斷,保留上次資料,恢復後自動更新。','Connection interrupted. Last valid data is retained and will update on reconnection.'],upgrade:['Kit 正在升級,暫停讀取。','Kit upgrade in progress. Reading is paused.'],invalid:['部分紀錄暫未能完整讀取;保留上一次有效內容。','Some records cannot be read completely. Last valid data is retained.'],workInvalid:['工作項目格式有問題;暫不更新工作狀態。','Work records are invalid. Work state updates are paused.'],legacy:['此處顯示既有原文;尚未整理工作項目。','Existing source text is shown. Structured work items are not recorded.'],coverage:['這是已保存紀錄的導覽,不是 AI 完整接收交接或獨立驗收的證明。','Saved-record navigation does not prove full AI handoff reception or independent acceptance.'],readScope:['首頁讀現況;歷程按需讀主紀錄與封存。程式不寫回來源,也不呼叫 AI。','Current state loads first. History reads logs and archives on demand, without source writes or model calls.'],historyWindow:['已顯示 {n} 則;查閱 {files} / {total} 份相關紀錄檔。','Showing {n} events; checked {files} of {total} relevant files.'],historyMore:['尚有紀錄待查閱。','More records remain to be read.'],historyWarning:['部分歷史未能核實,不能把這個結果視作完整歷史。','Some history could not be verified. Results are not a complete history.'],historyChanged:['紀錄正在變動,請重新查看所選日期。','History changed while reading. Apply the date range again.'],dateError:['請選擇有效的起訖日期。','Choose a valid date range.'],archived:['封存紀錄','Archived record'],recentRecord:['近期紀錄','Recent record'],updated:['紀錄已更新','Records updated'],unclassified:['未分組','Ungrouped'],summary:['摘要','Summary'],done:['完成紀錄','Recorded work'],qc:['驗收紀錄','Checks'],pending:['尚未完成','Outstanding'],risks:['限制與風險','Constraints'],changed:['改變了甚麼','What changed'],reason:['原因','Reason'],boundaryField:['範圍','Scope'],focusFallback:['目前工作','Current work'],unknownGoal:['專案目標尚未記錄;目前任務請看下方。','The project goal is not recorded. Current work is shown below.'],profileFallback:['交接中的任務目標','Task goal from handoff'],sourceDate:['紀錄日期','Record date'],readTime:['最後成功讀取','Last successful read'],noMatches:['沒有符合條件的項目。','No matching items.'],continueSearch:['繼續查閱','Continue search'],allWorkTitle:['工作與交接狀態','Work and handoff state'],state:['狀態','Status'],notAStage:['工作線,並非完成順序','Workstreams, not a completion sequence'],linksEmpty:['未記錄其他關係。','No other relationships recorded.'],recordFields:['當次紀錄','Recorded details']
|
|
8
|
+
};
|
|
9
|
+
const roles={handoff:['目前交接','Current handoff'],log:['工作紀錄','Session log'],archive:['歷史封存','Archive index'],index:['文件索引','Project index'],rules:['工作規則','Working rules'],packs:['規則入口','Rule router'],decisions:['重要決定','Decisions'],sync:['同步關係','Sync registry'],document:['參考文件','Reference'],artifact:['成果','Result']};
|
|
10
|
+
const statuses={planned:['待完成','Planned'],active:['進行中','In progress'],waiting:['等待','Waiting'],review:['待驗收','Awaiting review'],done:['已完成','Done'],paused:['已暫停','Paused'],dropped:['已停止','Stopped']};
|
|
11
|
+
const incomingText={routes:['由此文件指向','routed from'],governs:['依循','governed by'],archives:['收錄自','archived from'],references:['被參考於','referenced by'],mirrors:['同步鏡像','mirrored by'],checks:['檢查由此觸發','checked with']};
|
|
12
|
+
const relationText={routes:['指向','routes to'],governs:['規範','governs'],archives:['封存至','archives to'],references:['參考','references'],mirrors:['同步鏡像','mirrors'],checks:['需一併檢查','also checks']};
|
|
13
|
+
const purposes={handoff:['保存目前目標、未完事項與接續位置。','Stores the current goal, outstanding work and resume point.'],log:['記錄每次工作發生過甚麼;不取代目前狀態。','Records what happened in each session, not current state.'],archive:['定位較早的工作紀錄,按需查閱。','Locates earlier records for on-demand reading.'],index:['指出文件位置、用途與必要來源。','Maps document locations, roles and sources.'],rules:['定義本專案的工作邊界與基本流程。','Defines project boundaries and working procedures.'],packs:['按任務選取需要的規則。','Routes tasks to the relevant rules.'],decisions:['保留重要選擇及其理由。','Preserves important decisions and rationale.'],sync:['記錄變更時哪些文件需要一併檢查或同步。','Records which documents need checks or synchronization.']};
|
|
14
|
+
let lang='zh-Hant';try{const v=localStorage.getItem('ahk-ui-language');if(['zh-Hant','en'].includes(v))lang=v;}catch{}const requested=new URLSearchParams(location.search).get('lang');if(['zh-Hant','en'].includes(requested))lang=requested;
|
|
15
|
+
const tr=(k,v={})=>(dict[k]?.[lang==='en'?1:0]||k).replace(/\{(\w+)\}/g,(_,x)=>String(v[x]??'')),pick=p=>p?.[lang==='en'?1:0]||'',esc=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
|
|
16
|
+
const icon=name=>`<svg aria-hidden="true"><use href="icons.svg#${name}"></use></svg>`;
|
|
17
|
+
const title=w=>lang==='zh-Hant'&&w.titleZh||w.title,summary=w=>lang==='zh-Hant'&&w.summaryZh||w.summary;
|
|
18
|
+
const short=(s,n=140)=>{s=String(s||'').replace(/\s+/g,' ').trim();return s.length>n?s.slice(0,n)+'…':s;};
|
|
19
|
+
const pill=s=>`<span class="pill ${esc(s)}">${esc(pick(statuses[s])||tr('unknownState'))}</span>`;
|
|
20
|
+
const cite=r=>r?.source?`<p class="citation">${esc(r.source.file)} · ${lang==='en'?'line':'第'} ${r.source.line}${lang==='en'?'':' 行'}</p>`:'';
|
|
21
|
+
function date(s,brief=false){if(!s)return tr('missing');const d=new Date(/^\d{4}-\d{2}-\d{2}$/.test(s)?s+'T12:00:00':s);if(Number.isNaN(d.getTime()))return s;return new Intl.DateTimeFormat(lang==='en'?'en-GB':'zh-Hant',{...(!brief||d.getFullYear()!==new Date().getFullYear()?{year:'numeric'}:{}),month:'short',day:'numeric',...(!brief&&s.includes('T')?{hour:'2-digit',minute:'2-digit'}:{})}).format(d);}
|
|
22
|
+
const reduced=matchMedia('(prefers-reduced-motion: reduce)');
|
|
23
|
+
function motion(el,keyframes,options={}){if(el&&!reduced.matches)el.animate(keyframes,{duration:260,easing:'cubic-bezier(.22,.8,.3,1)',...options});}
|
|
24
|
+
function reveal(el){motion(el,[{opacity:.3,transform:'translateY(8px)'},{opacity:1,transform:'translateY(0)'}]);}
|
|
25
|
+
function updated(el){motion(el,[{backgroundColor:'#e2edff'},{backgroundColor:'transparent'}],{duration:1800});}
|
|
26
|
+
const relationLabel=(link,id)=>pick((link.from===id?relationText:incomingText)[link.type]);
|
|
27
|
+
const eventTitle=r=>lang==='zh-Hant'&&(r.titleZh||r.fields?.['title zh-hant'])||r.title;
|
|
28
|
+
const eventSummary=r=>lang==='zh-Hant'&&(r.summaryZh||r.fields?.['summary zh-hant'])||r.summary;
|
|
29
|
+
let data=null,online=false,session='',sequence=-1,selected=null,view='overview',lastRead=null,drawerState=null,drawerRequest=0,returnTo=null,returnSelector=null,historyItems=[],historyNext=null,historyMeta=null,historyRequest=0,historyLoaded=false,historyDirty=false,historyQuery=null,mapMode='map',mapSelected='handoff';
|
|
30
|
+
const drawer=$('#drawer');const work=()=>data?.dashboard?.work?.items||[],documents=()=>data?.dashboard?.documents||[];
|
|
31
|
+
const docName=d=>pick(roles[d.role])+(d.role==='document'||d.role==='artifact'?': '+(lang==='zh-Hant'&&d.titleZh||d.title||d.file):'');
|
|
32
|
+
const docByFile=file=>documents().find(d=>d.file===file);
|
|
33
|
+
let stream=null,reconnectTimer=null,reconnectAttempts=0,connectionPaused=false;
|
|
34
|
+
function route(){const name=location.hash.slice(1).split('/')[0];const previousView=view;view=['overview','history','documents'].includes(name)?name:'overview';for(const v of ['overview','history','documents'])$('#'+v+'-view').hidden=view!==v;document.querySelectorAll('[data-view]').forEach(a=>{if(a.dataset.view===view)a.setAttribute('aria-current','page');else a.removeAttribute('aria-current');});if(view==='history'&&data&&online&&(!historyLoaded||historyDirty))loadHistory(false,historyDirty);if(view==='documents')renderDocuments();if(previousView!==view)reveal($('#'+view+'-view'));}
|
|
35
|
+
function versionInfo(){const project=data?.dashboard?.projectKitVersion||null,raw=data?.kitVersion,tool=typeof raw==='string'&&/^\d+\.\d+\.\d+$/.test(raw)?raw:null;const different=!!(project&&tool&&project!==tool);return{project,tool,different,label:project?'v'+project+(different?' · '+tr('versionDifference'):''):tr('versionUnknown'),description:tr('projectKit')+': '+(project?'v'+project:tr('versionUnknown'))+' · '+tr('viewerKit')+': '+(tool?'v'+tool:tr('versionUnknown'))+(different?' — '+tr('versionDifferenceNote'):'')};}
|
|
36
|
+
function render(){
|
|
37
|
+
document.documentElement.lang=lang;$('#language').value=lang;document.querySelectorAll('[data-i18n]').forEach(e=>e.textContent=tr(e.dataset.i18n));document.querySelectorAll('[data-placeholder]').forEach(e=>e.placeholder=tr(e.dataset.placeholder));$('#close').ariaLabel=tr('close');
|
|
38
|
+
const version=versionInfo(),badge=$('#kit-version');badge.textContent=version.label;badge.title=version.description;badge.setAttribute('aria-label',version.description);badge.dataset.state=!version.project?'unverified':version.different?'different':'matched';
|
|
39
|
+
const errors={...(data?.errors||{}),...(data?.dashboard?.errors||{})};const hasErrors=Object.keys(errors).length>0;document.body.dataset.live=String(online&&!hasErrors);$('#sync').textContent=tr(!online?(data?'offlineLabel':'waiting'):hasErrors?'interrupted':'connected');
|
|
40
|
+
const warning=!online&&(data||reconnectAttempts)?'offline':errors.lock?'upgrade':errors.work?'workInvalid':hasErrors?'invalid':null;$('#warning').hidden=!warning;$('#warning').innerHTML=warning==='offline'?esc(tr('reconnectNote'))+' <button class="text-link" data-action="retry">'+tr('retryNow')+'</button> <button class="text-link" data-copy="'+esc(tr('reopenPrompt'))+'">'+tr('reopenCopy')+'</button>':warning?esc(tr(warning)):'';
|
|
41
|
+
const p=data?.dashboard?.profile||{};const name=(lang==='zh-Hant'&&p.nameZh)||p.name||data?.project?.name||tr('missing');$('#project-title').textContent=name;$('#history-project').textContent=name;$('#documents-project').textContent=name;document.title=name+' · Agent Handoff Kit';
|
|
42
|
+
const saved=data?.sources?.find(s=>s.file.includes('HANDOFF'))?.updated;$('#freshness').innerHTML=icon('calendar')+esc(tr('handoffSaved',{date:date(saved||data?.recordDate)}));$('#empty').hidden=!!data?.available;
|
|
43
|
+
const current=data?.project?.current?.text;$('#recorded-current').textContent=tr('recordedCurrent')+':'+short(current||tr('missing'),150);$('#recorded-current').title=current||tr('missing');
|
|
44
|
+
const workValue=$('#history-work').value;$('#history-work').innerHTML='<option value="">'+tr('allWorkstreams')+'</option>'+work().map(w=>'<option value="'+esc(w.id)+'">'+esc(title(w))+'</option>').join('');$('#history-work').value=workValue;renderWork();renderRecent();renderStrip();if(view==='documents')renderDocuments();if(view==='history')renderHistory();route();
|
|
45
|
+
}
|
|
46
|
+
function legacyWorkHTML(){
|
|
47
|
+
const collections=['pending','risks'].map(kind=>({kind,items:data?.sections?.[kind]?.items||[],total:data?.sections?.[kind]?.total||0}));
|
|
48
|
+
const visible=collections.reduce((n,c)=>n+c.items.length,0),total=collections.reduce((n,c)=>n+c.total,0);
|
|
49
|
+
const warning=data?.errors?.handoff||data?.errors?.lock;
|
|
50
|
+
let html=warning?`<p class="scope-note">${tr(data?.available?'workRetained':'unavailable')}</p>`:'';
|
|
51
|
+
if(visible){html+=`<p class="scope-note">${tr('legacyWork')}</p>`+collections.filter(c=>c.items.length).map(c=>`<h3 class="legacy-label">${tr(c.kind)}</h3>`+c.items.map(r=>`<button class="work-row" data-document="handoff"><span>${esc(short(r.text,180))}</span></button>`).join('')).join('');
|
|
52
|
+
if(total>visible)html+=`<button class="text-link" data-document="handoff">${tr('moreLegacy',{n:total-visible})}</button>`;
|
|
53
|
+
}else html+=`<p class="empty">${tr(data?.available?'noOutstanding':'unavailable')}</p>`;
|
|
54
|
+
return html+`<button class="text-link" data-document="handoff">${tr('showSource')}</button>`;
|
|
55
|
+
}
|
|
56
|
+
function renderWork(){
|
|
57
|
+
const items=work(),roots=items.filter(x=>!x.parent);if(!items.some(x=>x.id===selected))selected=items.find(x=>x.status==='active')?.id||roots[0]?.id||null;
|
|
58
|
+
const selectedWork=items.find(x=>x.id===selected);let selectedRoot=selected;for(let w=selectedWork;w?.parent;w=items.find(x=>x.id===w.parent))selectedRoot=w.parent;
|
|
59
|
+
$('#work-route').innerHTML=roots.length?roots.slice(0,5).map((w,i)=>`<button class="route-node" data-work-select="${esc(w.id)}" aria-pressed="${w.id===selectedRoot}"><span class="node-circle">${icon(i===2?'grid':'document')}</span><strong>${esc(title(w))}</strong><span class="description">${esc(short(summary(w),100))}</span><span class="relation">${esc(pick(statuses[w.status]))}</span></button>`).join(''):`<p class="empty">${tr('noWork')}</p>`;
|
|
60
|
+
$('#work-route').ariaLabel=tr('notAStage');$('#work-scope').textContent=tr('notAStage');$('#work-scope').hidden=!roots.length;$('#more-work').hidden=roots.length<=5;$('#more-work').textContent=tr('moreWork',{n:roots.length-5});
|
|
61
|
+
if(selectedWork)$('#focus').innerHTML=`<h2>${tr('focus')}:${esc(title(selectedWork))}</h2>${pill(selectedWork.status)}<div class="focus-actions"><button class="primary" data-work="${esc(selectedWork.id)}">${tr('viewWork')}${icon('arrow')}</button></div>`;
|
|
62
|
+
else $('#focus').innerHTML=`<h2>${tr('focusFallback')}</h2><p class="focus-summary">${esc(short(data?.project?.current?.text||tr('missing'),240))}</p><div class="focus-actions"><button class="primary" data-document="handoff">${tr('showDocument')}</button></div>`;
|
|
63
|
+
const pending=items.filter(w=>!['done','dropped'].includes(w.status)&&(!items.some(c=>c.parent===w.id)||w.status!=='active'));
|
|
64
|
+
$('#pending-list').innerHTML=!items.length?legacyWorkHTML():pending.length?pending.slice(0,3).map(w=>`<button class="work-row" data-work="${esc(w.id)}">${pill(w.status)}<span><strong>${esc(title(w))}</strong><small>${esc(short(summary(w),80))}</small></span></button>`).join('')+(pending.length>3?`<button class="text-link" data-action="all-work">${tr('morePending',{n:pending.length-3})}</button>`:''):`<p class="empty">${tr('noOutstanding')}</p><button class="text-link" data-document="handoff">${tr('showDocument')}</button>`;
|
|
65
|
+
const results=items.filter(w=>w.artifact).slice(0,3);$('#result-list').innerHTML=results.length?results.map(w=>{const d=docByFile(w.artifact);return`<button class="result-row" data-document="${esc(d?.id||'handoff')}">${icon('document')}<span><strong>${esc(title(w))}</strong><small>${esc(w.artifact.split('/').pop())}</small></span></button>`;}).join(''):`<p class="empty">${tr('noResults')}</p>`;
|
|
66
|
+
}
|
|
67
|
+
function renderRecent(){const rows=data?.recent?.items||[];$('#recent-list').innerHTML=rows.length?rows.slice(0,3).map((r,i)=>`<button class="recent-row" data-recent="${i}"><time>${esc(date(r.title.slice(0,10),true))}</time><span><strong>${esc(eventTitle({...r,title:r.title.slice(10).replace(/^\s*[—–-]\s*/,'' )}))}</strong><small>${esc(short(eventSummary({...r,summary:r.summary?.text?.replace(/^Summary[::]\s*/i,'')}),95))}</small></span></button>`).join(''):`<p class="empty">${tr('noRecent')}</p>`;}
|
|
68
|
+
function renderStrip(){const ids=['handoff','log','archive','index'];$('#document-strip').innerHTML=ids.map(id=>documents().find(d=>d.id===id)).filter(Boolean).map(d=>`<button class="strip-node" data-document="${d.id}"><span class="mini-node">${icon(d.id==='archive'?'archive':d.id==='index'?'map':'document')}</span><span><strong>${esc(docName(d))}</strong><small>${esc(d.file.split('/').pop())}</small></span></button>`).join('');}
|
|
69
|
+
function renderDocuments(){const docs=documents(),links=data?.dashboard?.links||[];$('#document-status').textContent=data?.dashboard?.errors.documents?tr('invalid'):'';
|
|
70
|
+
$('#document-map').hidden=mapMode!=='map';$('#document-list').hidden=mapMode!=='list';$('#map-mode').setAttribute('aria-pressed',String(mapMode==='map'));$('#list-mode').setAttribute('aria-pressed',String(mapMode==='list'));
|
|
71
|
+
const order=['index','handoff','log','archive','packs','rules','decisions','sync'];const core=docs.filter(d=>order.includes(d.role)).sort((a,b)=>order.indexOf(a.role)-order.indexOf(b.role));const linked=new Set(links.filter(l=>l.from===mapSelected||l.to===mapSelected).flatMap(l=>[l.from,l.to]));linked.add(mapSelected);
|
|
72
|
+
const scope=tr(mapMode==='map'?'coreScope':'listScope',{n:mapMode==='map'?core.length:docs.length});$('#document-status').textContent=scope+(data?.dashboard?.errors.documents?' '+tr('invalid'):'');
|
|
73
|
+
$('#document-map').innerHTML='<svg class="map-lines" aria-hidden="true"></svg>'+core.map(d=>`<button class="doc-node ${d.available?'':'missing'} ${linked.has(d.id)?'related':'subdued'}" data-role="${d.role}" data-map="${d.id}" aria-pressed="${d.id===mapSelected}"><span class="node-circle">${icon(d.role==='archive'?'archive':d.role==='index'?'map':'document')}</span><strong>${esc(docName(d))}</strong><small>${esc(d.file.split('/').pop())}</small></button>`).join('');
|
|
74
|
+
const d=docs.find(x=>x.id===mapSelected);if(d){const related=links.filter(l=>l.from===d.id||l.to===d.id);$('#map-detail').innerHTML=`<div><h2>${esc(docName(d))}</h2><p>${esc(pick(purposes[d.role])||d.title||'')}</p></div><div class="map-relations">${related.map(l=>{const other=docs.find(x=>x.id===(l.from===d.id?l.to:l.from));return `<span>${esc(relationLabel(l,d.id))} <button class="text-link" ${core.some(x=>x.id===other.id)?'data-map':'data-document'}="${esc(other.id)}">${esc(docName(other))}</button></span>`;}).join('')||tr('linksEmpty')}</div><button class="primary" data-document="${esc(d.id)}">${tr('showDocument')}${icon('arrow')}</button>`;}
|
|
75
|
+
$('#map-detail').hidden=mapMode!=='map';$('#document-list').innerHTML=docs.map(d=>`<button data-document="${esc(d.id)}"><strong>${esc(docName(d))}</strong><small>${esc(d.file)}</small><small>${tr(d.available?'available':'notAvailable')}</small></button>`).join('');requestAnimationFrame(drawConnections);
|
|
76
|
+
}
|
|
77
|
+
function drawConnections(){if(view!=='documents'||mapMode!=='map')return;const box=$('#document-map'),svg=box.querySelector('svg'),bounds=box.getBoundingClientRect();if(!bounds.width)return;svg.setAttribute('viewBox',`0 0 ${bounds.width} ${bounds.height}`);svg.innerHTML='<defs><marker id="arrowhead" markerWidth="7" markerHeight="7" refX="6" refY="3.5" orient="auto"><path d="M0 0 L7 3.5 L0 7" fill="currentColor" stroke="none"/></marker></defs>'+(data.dashboard.links||[]).map(l=>{const a=box.querySelector('[data-map="'+l.from+'"] .node-circle'),b=box.querySelector('[data-map="'+l.to+'"] .node-circle');if(!a||!b)return '';const ar=a.getBoundingClientRect(),br=b.getBoundingClientRect(),ax=ar.x+ar.width/2-bounds.x,ay=ar.y+ar.height/2-bounds.y,bx=br.x+br.width/2-bounds.x,by=br.y+br.height/2-bounds.y,dx=bx-ax,dy=by-ay,len=Math.hypot(dx,dy)||1,rad=43,x1=ax+dx/len*rad,y1=ay+dy/len*rad,x2=bx-dx/len*rad,y2=by-dy/len*rad;return `<path class="${l.from===mapSelected||l.to===mapSelected?'lit':''}" d="M${x1} ${y1} C${x1} ${(y1+y2)/2},${x2} ${(y1+y2)/2},${x2} ${y2}" marker-end="url(#arrowhead)"/>`;}).join('');}
|
|
78
|
+
new ResizeObserver(()=>requestAnimationFrame(drawConnections)).observe($('#document-map'));
|
|
79
|
+
function focusSelector(el){if(el?.id)return '#'+CSS.escape(el.id);for(const key of ['work','document','event','recent','workSelect','action'])if(el?.dataset?.[key]!==undefined)return 'main [data-'+key.replace(/[A-Z]/g,x=>'-'+x.toLowerCase())+'="'+CSS.escape(el.dataset[key])+'"]';return null;}
|
|
80
|
+
function openDrawer(state,titleText,body,kicker=''){if(!drawer.open){returnTo=document.activeElement;returnSelector=focusSelector(returnTo);}drawerState=state;$('#drawer-title').textContent=titleText;$('#drawer-kicker').textContent=kicker;$('#drawer-content').innerHTML=body;if(!drawer.open){drawer.showModal();motion(drawer,[{transform:'translateX(50px)',opacity:.4},{transform:'translateX(0)',opacity:1}],{duration:300});}}
|
|
81
|
+
function showWork(id,update=false){const w=work().find(x=>x.id===id);if(!w)return;const children=work().filter(x=>x.parent===id),parent=work().find(x=>x.id===w.parent);let body=pill(w.status)+`<p>${esc(summary(w)||tr('missing'))}</p>`;if(parent)body+=`<h3>${tr('parent')}</h3><button class="text-link" data-work="${esc(parent.id)}">${esc(title(parent))}</button>`;if(children.length)body+=`<h3>${tr('children')}</h3><div class="work-list">${children.map(c=>`<button class="work-row" data-work="${esc(c.id)}">${pill(c.status)}<span><strong>${esc(title(c))}</strong><small>${esc(summary(c))}</small></span></button>`).join('')}</div>`;body+=cite(w)+`<div class="drawer-actions"><button class="secondary" data-document="handoff">${tr('showSource')}</button>${w.artifact?`<button class="primary" data-document="${esc(docByFile(w.artifact)?.id||'handoff')}">${tr('showDocument')}</button>`:''}</div>`;if(update)body=`<p class="updated-note">${tr(data?.errors?.handoff||data?.errors?.lock||data?.dashboard?.errors?.work?'workRetained':'sourceChanged')}</p>`+body;openDrawer({kind:'work',id},title(w),body,tr('state'));}
|
|
82
|
+
async function showDocument(id,update=false){const previousBody=update?$('#drawer-content').innerHTML:null;const d=documents().find(x=>x.id===id);if(!d)return;const requestId=++drawerRequest,scroll=update?drawer.scrollTop:0;const relation=(data?.dashboard?.links||[]).filter(l=>l.from===id||l.to===id);const base=`<p>${esc(pick(purposes[d.role])||d.title||tr('missing'))}</p><p class="citation">${esc(d.file)}</p><div class="drawer-actions"><button class="secondary" data-copy="${esc(d.file)}">${icon('copy')}${tr('copyPath')}</button>${d.role==='log'||d.role==='archive'?`<button class="secondary" data-action="history">${tr('viewHistory')}</button>`:''}</div>${relation.length?`<h3>${tr('relationships')}</h3>${relation.map(l=>{const other=documents().find(x=>x.id===(l.from===id?l.to:l.from));return`<p>${esc(relationLabel(l,id))} <button class="text-link" data-document="${esc(other.id)}">${esc(docName(other))}</button></p>`;}).join('')}`:''}`;openDrawer({kind:'document',id},docName(d),base+`<p>${tr('loading')}</p>`,tr('sources'));try{const r=await fetch('/api/document?id='+encodeURIComponent(id));if(!r.ok)throw Error();const result=await r.json();if(requestId!==drawerRequest||!drawer.open)return;$('#drawer-content').innerHTML=(update?`<p class="updated-note">${tr('sourceChanged')}</p>`:'')+base+`<h3>${tr('sourceText')}</h3>`+(result.text!==null?`<pre tabindex="0">${esc(result.text)}</pre>`:`<p>${tr('fileUnknown')}</p>`);drawer.scrollTop=scroll;}catch{if(requestId===drawerRequest&&drawer.open)$('#drawer-content').innerHTML=(previousBody||base)+`<p class="warning">${tr(d.available?'unavailable':'notAvailable')}</p>`;}}
|
|
83
|
+
function showEvent(item){const map={summary:'summary',changed:'changed',done:'done',qc:'qc',pending:'pending',risks:'risks',reason:'reason',boundary:'boundaryField'};let body=`<p class="citation">${esc(date(item.date))}${item.work?' · '+esc(work().some(w=>w.id===item.work)?title(work().find(w=>w.id===item.work)):item.work):''}</p>`;const f=item.fields||{};let fields=Object.entries(map).filter(([k])=>f[k]);body+=fields.length?fields.map(([k,label])=>`<h3>${tr(label)}</h3><p>${esc(lang==='zh-Hant'&&f[k+' zh-hant']||f[k])}</p>`).join(''):`<p>${esc(item.summary||item.body||tr('missing'))}</p>`;body+=cite(item);if(item.body)body+=`<details><summary>${tr('sourceText')}</summary><pre>${esc(item.body)}</pre></details>`;openDrawer({kind:'event',item},eventTitle(item),body,tr(item.source?.file.includes('_archive/')?'archived':'recentRecord'));}
|
|
84
|
+
function showSources(){const version=versionInfo();const body=`<div class="source-row">${esc(version.description)}<small>${esc(tr('versionSource'))}</small></div>`+(data?.sources||[]).map(s=>`<div class="source-row">${esc(s.file)}<small>${esc(tr('saved',{date:date(s.updated)}))}</small></div>`).join('')+`<p class="citation">${tr('readTime')}:${esc(date(lastRead))}</p><p>${tr('readScope')}</p><p class="citation">${tr('coverage')}</p>`;openDrawer({kind:'sources'},tr('sources'),body);}
|
|
85
|
+
function showAllWork(){openDrawer({kind:'all'},tr('allWorkTitle'),work().length?`<div class="work-list">${work().map(w=>`<button class="work-row" data-work="${esc(w.id)}">${pill(w.status)}<span><strong>${esc(title(w))}</strong><small>${esc(summary(w))}</small></span></button>`).join('')}</div>`:legacyWorkHTML());}
|
|
86
|
+
function refreshDrawer(){if(!drawer.open)return;const s=drawerState,scroll=drawer.scrollTop;if(s?.kind==='work')showWork(s.id,true);else if(s?.kind==='document')showDocument(s.id,true);else if(s?.kind==='sources')showSources();else if(s?.kind==='all')showAllWork();else if(s?.kind==='event'){const recent=(data.recent?.items||[]).find(r=>r.id===s.item.id);const current=historyItems.find(r=>r.id===s.item.id);if(current||recent){showEvent(current||{...recent,date:recent.title.slice(0,10),title:recent.title.slice(10).replace(/^\s*[—–-]\s*/,''),summary:recent.summary?.text});}else if(!$('#event-update'))$('#drawer-content').insertAdjacentHTML('afterbegin',`<p id="event-update" class="updated-note">${tr('eventSnapshot')}</p>`);}drawer.scrollTop=scroll;}
|
|
87
|
+
function localDay(d){return [d.getFullYear(),String(d.getMonth()+1).padStart(2,'0'),String(d.getDate()).padStart(2,'0')].join('-');}
|
|
88
|
+
function setRange(days){const now=new Date();$('#to').value=days==='all'?'':localDay(now);const start=new Date(now);start.setDate(start.getDate()-Number(days||30)+1);$('#from').value=days==='all'?'':localDay(start);document.querySelectorAll('[data-days]').forEach(b=>b.setAttribute('aria-pressed',String(b.dataset.days===String(days))));}
|
|
89
|
+
async function loadHistory(more=false,automatic=false){if(!data)return;const from=automatic&&historyQuery?historyQuery.from:$('#from').value,to=automatic&&historyQuery?historyQuery.to:$('#to').value;if(from&&to&&from>to){$('#history-status').textContent=tr('dateError');return;}const requestId=++historyRequest;const q={from,to,search:automatic&&historyQuery?historyQuery.search:$('#search').value,work:automatic&&historyQuery?historyQuery.work:$('#history-work').value};if(more&&historyNext)q.cursor=historyNext;const oldItems=historyItems,oldCount=historyItems.length;const anchor=[...document.querySelectorAll('[data-event]')].find(e=>e.getBoundingClientRect().top>=0);const anchorId=anchor?.dataset.event,anchorY=anchor?.getBoundingClientRect().top;historyLoaded=true;historyDirty=false;$('#history-status').textContent=tr('loading');$('#history-more').disabled=true;$('#history-list').setAttribute('aria-busy','true');
|
|
90
|
+
try{let combined=more?[...historyItems]:[],result,pages=0;do{const r=await fetch('/api/history?'+new URLSearchParams(q));if(!r.ok)throw Error();result=await r.json();if(requestId!==historyRequest)return;const ids=new Set(combined.map(x=>x.id));combined.push(...result.items.filter(x=>!ids.has(x.id)));q.cursor=result.next;pages++;}while(automatic&&result.next&&combined.length<oldCount&&pages<5);
|
|
91
|
+
historyQuery={from,to,search:q.search,work:q.work};historyItems=combined;historyNext=result.next;historyMeta=result;historyDirty=false;renderHistory();if(automatic&&anchorId){const nextAnchor=$('[data-event="'+anchorId+'"]');if(nextAnchor)window.scrollBy(0,nextAnchor.getBoundingClientRect().top-anchorY);}else reveal($('#history-list'));if(automatic){const oldById=new Map(oldItems.map(x=>[x.id,x.fingerprint]));document.querySelectorAll('[data-event]').forEach(el=>{const entry=combined.find(x=>x.id===el.dataset.event);if(entry&&oldById.get(entry.id)!==entry.fingerprint)updated(el);});}if(drawerState?.kind==='event')refreshDrawer();
|
|
92
|
+
}catch{if(requestId===historyRequest){historyDirty=true;$('#history-status').textContent=tr(more?'historyChanged':'unavailable');}}finally{if(requestId===historyRequest){$('#history-more').disabled=false;$('#history-list').removeAttribute('aria-busy');}}}
|
|
93
|
+
function renderHistory(){if(!historyLoaded)return;const groups=new Map();for(const item of [...historyItems].sort((a,b)=>b.date.localeCompare(a.date))){if(!groups.has(item.date))groups.set(item.date,[]);groups.get(item.date).push(item);}
|
|
94
|
+
$('#history-list').innerHTML=groups.size?[...groups].map(([day,rows])=>`<section class="day"><h2>${esc(date(day))}</h2><div class="day-events">${rows.map(r=>`<button class="event" data-event="${esc(r.id)}"><strong>${esc(eventTitle(r))}</strong><p>${esc(short(eventSummary(r),200))}</p><span class="event-meta">${esc(r.work?(work().some(w=>w.id===r.work)?title(work().find(w=>w.id===r.work)):r.work):tr('unclassified'))} · ${tr(r.source.file.includes('_archive/')?'archived':'recentRecord')}</span></button>`).join('')}</div></section>`).join(''):`<p class="empty">${tr(historyNext?'historyMore':'noEvents')}</p>`;
|
|
95
|
+
if(historyMeta)$('#history-status').textContent=tr('historyWindow',{n:historyItems.length,files:historyMeta.filesChecked,total:historyMeta.totalFiles})+' '+(historyMeta.warnings.length?tr('historyWarning'):'')+' '+(historyNext?tr('historyMore'):'')+(historyDirty?' '+tr('updated'):'');$('#history-more').hidden=!historyNext;
|
|
96
|
+
}
|
|
97
|
+
$('#close').onclick=()=>drawer.close();drawer.onclose=()=>{drawerRequest++;drawerState=null;const target=returnTo?.isConnected?returnTo:returnSelector?$(returnSelector):null;(target||document.querySelector('nav [aria-current=page]'))?.focus({preventScroll:true});};
|
|
98
|
+
document.addEventListener('click',async e=>{const b=e.target.closest('button');if(!b||b.disabled)return;
|
|
99
|
+
if(b.dataset.workSelect){selected=b.dataset.workSelect;renderWork();reveal($('#focus'));motion($('[data-work-select="'+selected+'"] .node-circle'),[{transform:'scale(.95)'},{transform:'scale(1.12)'},{transform:'scale(1.08)'}],{duration:350});$(`[data-work-select="${selected}"]`)?.focus({preventScroll:true});}
|
|
100
|
+
else if(b.dataset.map){mapSelected=b.dataset.map;renderDocuments();reveal($('#map-detail'));$('#document-map [data-map="'+mapSelected+'"]')?.focus({preventScroll:true});}
|
|
101
|
+
else if(b.dataset.work)showWork(b.dataset.work);
|
|
102
|
+
else if(b.dataset.document)showDocument(b.dataset.document);
|
|
103
|
+
else if(b.dataset.recent!==undefined){const r=data.recent.items[Number(b.dataset.recent)];showEvent({...r,title:r.title.slice(10).replace(/^\s*[—–-]\s*/,''),date:r.title.slice(0,10),summary:r.summary?.text||'',fields:r.fields,body:r.body,source:r.source});}
|
|
104
|
+
else if(b.dataset.event){const item=historyItems.find(x=>x.id===b.dataset.event);if(item)showEvent(item);}
|
|
105
|
+
else if(b.dataset.copy){try{await navigator.clipboard.writeText(b.dataset.copy);b.textContent=tr('copied');}catch{b.textContent=b.dataset.copy===tr('reopenPrompt')?b.dataset.copy:tr('copyFailed');}}
|
|
106
|
+
else if(b.dataset.days){setRange(b.dataset.days);loadHistory();}
|
|
107
|
+
else if(b.dataset.action==='retry')connect();else if(b.dataset.action==='sources')showSources();else if(b.dataset.action==='all-work')showAllWork();else if(b.dataset.action==='history'){drawer.close();location.hash='history';}
|
|
108
|
+
});
|
|
109
|
+
$('#language').onchange=e=>{lang=e.target.value;try{localStorage.setItem('ahk-ui-language',lang);}catch{}render();refreshDrawer();};$('#history-filter').onsubmit=e=>{e.preventDefault();document.querySelectorAll('[data-days]').forEach(b=>b.setAttribute('aria-pressed','false'));loadHistory();};$('#history-more').onclick=()=>loadHistory(true);$('#map-mode').onclick=()=>{mapMode='map';renderDocuments();};$('#list-mode').onclick=()=>{mapMode='list';renderDocuments();};window.addEventListener('hashchange',route);setRange(30);
|
|
110
|
+
function disconnect(current){
|
|
111
|
+
if(stream!==current)return;
|
|
112
|
+
current.close();stream=null;online=false;
|
|
113
|
+
if(!connectionPaused&&reconnectTimer===null){
|
|
114
|
+
const delay=Math.min(30000,1000*2**Math.min(reconnectAttempts++,5));
|
|
115
|
+
reconnectTimer=setTimeout(()=>{reconnectTimer=null;connect();},delay);
|
|
116
|
+
}
|
|
117
|
+
render();
|
|
118
|
+
}
|
|
119
|
+
function connect(){
|
|
120
|
+
if(connectionPaused||location.protocol!=='http:'||location.hostname!=='127.0.0.1'||!window.EventSource)return;
|
|
121
|
+
clearTimeout(reconnectTimer);reconnectTimer=null;
|
|
122
|
+
if(stream){if(online)return;stream.close();}
|
|
123
|
+
const current=new EventSource('/events');stream=current;
|
|
124
|
+
current.onmessage=e=>{
|
|
125
|
+
if(stream!==current)return;
|
|
126
|
+
try{
|
|
127
|
+
const next=JSON.parse(e.data);if(next.schemaVersion!==2||!next.dashboard||typeof next.session!=='string')throw Error();
|
|
128
|
+
if(next.session===session&&next.version<sequence)return;
|
|
129
|
+
const oldData=data,hadData=!!data,resumed=hadData&&!online,restarted=hadData&&next.session!==session;
|
|
130
|
+
const changed=hadData&&(resumed||restarted||next.version!==data.version||next.dashboard.revision!==data.dashboard.revision);
|
|
131
|
+
if(hadData&&(resumed||restarted||next.dashboard.historyRevision!==data.dashboard.historyRevision))historyDirty=true;
|
|
132
|
+
if(resumed||restarted){historyNext=null;historyRequest++;drawerRequest++;}
|
|
133
|
+
session=next.session;sequence=next.version;data=next;online=true;reconnectAttempts=0;lastRead=new Date().toISOString();
|
|
134
|
+
const active=document.activeElement,focusKey=active?.dataset.workSelect;render();
|
|
135
|
+
if(!hadData){document.querySelectorAll('.route-node,.overview-grid .panel').forEach((el,i)=>motion(el,[{opacity:0,transform:'translateY(12px)'},{opacity:1,transform:'none'}],{delay:i*60,duration:380}));}
|
|
136
|
+
else{for(const w of work()){const old=oldData.dashboard.work.items.find(x=>x.id===w.id);if(JSON.stringify(old)!==JSON.stringify(w))updated($('[data-work-select="'+w.id+'"]'));}}
|
|
137
|
+
if(focusKey)$('[data-work-select="'+focusKey+'"]')?.focus({preventScroll:true});
|
|
138
|
+
if(changed){refreshDrawer();$('#announcement').textContent=tr('updated');}
|
|
139
|
+
document.body.dataset.version=String(data.version);
|
|
140
|
+
}catch{disconnect(current);}
|
|
141
|
+
};
|
|
142
|
+
current.onerror=()=>disconnect(current);
|
|
143
|
+
}
|
|
144
|
+
const wake=()=>{if(!online&&!stream&&!connectionPaused)connect();};
|
|
145
|
+
window.addEventListener('online',wake);window.addEventListener('focus',wake);
|
|
146
|
+
document.addEventListener('visibilitychange',()=>{if(document.visibilityState==='visible')wake();});
|
|
147
|
+
window.addEventListener('pagehide',()=>{connectionPaused=true;clearTimeout(reconnectTimer);reconnectTimer=null;stream?.close();stream=null;online=false;});
|
|
148
|
+
window.addEventListener('pageshow',()=>{connectionPaused=false;wake();});
|
|
149
|
+
connect();
|
|
150
|
+
render();
|
|
151
|
+
})();
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import http from 'node:http';
|
|
2
|
+
import {readFileSync,realpathSync} from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import {fileURLToPath} from 'node:url';
|
|
5
|
+
import {randomUUID,createHash} from 'node:crypto';
|
|
6
|
+
import {spawn} from 'node:child_process';
|
|
7
|
+
import {createSource} from './projection.mjs';
|
|
8
|
+
import {createDashboard} from './dashboard.mjs';
|
|
9
|
+
|
|
10
|
+
const assets=path.dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
// Fingerprint the shipped view so an old process is not reused after a source update.
|
|
12
|
+
const buildId=createHash('sha256');
|
|
13
|
+
for(const file of ['server.mjs','projection.mjs','dashboard.mjs','renderer.js','styles.css','index.html','agent-handoff-kit-logo2-256.png','dashboard-hero.png','icons.svg','../upgrade-inventory.mjs'])buildId.update(readFileSync(path.join(assets,file)));
|
|
14
|
+
const build=buildId.digest('hex');
|
|
15
|
+
export const PROGRESS_IDLE_MS=8*60*60*1000;
|
|
16
|
+
export function progressIdentity(root,version='unknown'){
|
|
17
|
+
const canonical=realpathSync(path.resolve(root));
|
|
18
|
+
return {service:'agent-handoff-kit-progress',rootId:createHash('sha256').update(canonical).digest('hex'),version,build};
|
|
19
|
+
}
|
|
20
|
+
export function openProgressBrowser(url){
|
|
21
|
+
const command=process.platform==='win32'?'rundll32.exe':process.platform==='darwin'?'open':'xdg-open';
|
|
22
|
+
const args=process.platform==='win32'?['url.dll,FileProtocolHandler',url]:[url];
|
|
23
|
+
try{const child=spawn(command,args,{windowsHide:true,stdio:'ignore',detached:process.platform!=='win32'});child.once('error',()=>console.error('Open the progress URL in your browser.'));child.unref();}catch{console.error('Open the progress URL in your browser.');}
|
|
24
|
+
}
|
|
25
|
+
export async function startProgress({root,port=0,openBrowser=true,version='unknown',idleMs=PROGRESS_IDLE_MS,onReady=null}={}){
|
|
26
|
+
if(!Number.isInteger(port)||port<0||port>65535)throw Error('progress --port must be an integer from 0 to 65535');
|
|
27
|
+
if(!Number.isSafeInteger(idleMs)||idleMs<1||idleMs>2147483647)throw Error('Invalid progress idle timeout');
|
|
28
|
+
const source=createSource(root);source.refresh({immediate:true});
|
|
29
|
+
const dashboard=createDashboard(root,source);dashboard.refresh();
|
|
30
|
+
if(source.state.errors.handoff==='missing')throw Error('No dev/SESSION_HANDOFF.md found. Select an installed Kit project with --root.');
|
|
31
|
+
const identity=progressIdentity(root,version),session=randomUUID(),clients=new Set(),sockets=new Set();let boundPort=0,stopping=false,watch=null,heartbeat=null,idleTimer=null;
|
|
32
|
+
const envelope=()=>({templateVersion:'dashboard-1',kitVersion:version,session,...source.snapshot(),dashboard:dashboard.snapshot()});
|
|
33
|
+
const json=(res,status,data)=>{res.writeHead(status,{'Content-Type':'application/json; charset=utf-8','Cache-Control':'no-store','X-Content-Type-Options':'nosniff'});res.end(JSON.stringify(data));};
|
|
34
|
+
const broadcast=()=>{const payload=`data: ${JSON.stringify(envelope())}\n\n`;for(const client of clients)client.write(payload);};
|
|
35
|
+
const refresh=(immediate=false)=>{const changed=source.refresh({immediate});const dashboardChanged=dashboard.refresh();return changed||dashboardChanged;};
|
|
36
|
+
const stopPolling=()=>{clearInterval(watch);clearInterval(heartbeat);watch=null;heartbeat=null;};
|
|
37
|
+
const deferShutdown=()=>{clearTimeout(idleTimer);idleTimer=null;if(!stopping&&!clients.size)idleTimer=setTimeout(()=>void close(),idleMs);};
|
|
38
|
+
const resumePolling=()=>{clearTimeout(idleTimer);idleTimer=null;if(!watch)watch=setInterval(()=>{if(refresh())broadcast();},500);if(!heartbeat)heartbeat=setInterval(()=>{for(const client of clients)client.write(': keepalive\n\n');},5000);};
|
|
39
|
+
const server=http.createServer((req,res)=>{
|
|
40
|
+
const host=`127.0.0.1:${boundPort}`;
|
|
41
|
+
if(req.headers.host!==host||(req.headers.origin&&req.headers.origin!==`http://${host}`)||req.headers['sec-fetch-site']==='cross-site'){json(res,403,{error:'origin'});return;}
|
|
42
|
+
if(req.method!=='GET'){json(res,405,{error:'read_only'});return;}
|
|
43
|
+
try{
|
|
44
|
+
const url=new URL(req.url,`http://${host}`);
|
|
45
|
+
if(url.pathname==='/events'){
|
|
46
|
+
if(refresh(true))broadcast();
|
|
47
|
+
res.writeHead(200,{'Content-Type':'text/event-stream; charset=utf-8','Cache-Control':'no-store','Connection':'keep-alive','X-Content-Type-Options':'nosniff'});res.write(`data: ${JSON.stringify(envelope())}\n\n`);clients.add(res);resumePolling();
|
|
48
|
+
res.on('close',()=>{clients.delete(res);if(!clients.size){stopPolling();deferShutdown();}});return;
|
|
49
|
+
}
|
|
50
|
+
if(url.pathname==='/api/identity'){if(url.searchParams.get('reopen')==='1')deferShutdown();json(res,200,identity);return;}
|
|
51
|
+
if(['/api/state','/api/document','/api/history','/api/section'].includes(url.pathname)){if(refresh(true))broadcast();deferShutdown();}
|
|
52
|
+
if(url.pathname==='/api/state'){json(res,200,envelope());return;}
|
|
53
|
+
if(url.pathname==='/api/document'){json(res,200,dashboard.document(url.searchParams.get('id')));return;}
|
|
54
|
+
if(url.pathname==='/api/history'){json(res,200,dashboard.history(Object.fromEntries(['from','to','search','work','cursor'].map(k=>[k,url.searchParams.get(k)||'']))));return;}
|
|
55
|
+
if(url.pathname==='/api/section'){
|
|
56
|
+
if(Number(url.searchParams.get('version'))!==source.snapshot().version){json(res,409,{error:'changed'});return;}
|
|
57
|
+
const offset=url.searchParams.get('offset')||'0';if(!/^\d{1,7}$/.test(offset))throw Error('query');json(res,200,source.page(url.searchParams.get('kind'),Number(offset)));return;
|
|
58
|
+
}
|
|
59
|
+
const routes={'/':'index.html','/index.html':'index.html','/styles.css':'styles.css','/renderer.js':'renderer.js','/agent-handoff-kit-logo2-256.png':'agent-handoff-kit-logo2-256.png','/dashboard-hero.png':'dashboard-hero.png','/icons.svg':'icons.svg'};
|
|
60
|
+
const file=Object.hasOwn(routes,url.pathname)?routes[url.pathname]:null;if(!file){json(res,404,{error:'not_found'});return;}
|
|
61
|
+
deferShutdown();
|
|
62
|
+
const type=file.endsWith('.png')?'image/png':file.endsWith('.svg')?'image/svg+xml':file.endsWith('.css')?'text/css':file.endsWith('.js')?'text/javascript':'text/html';
|
|
63
|
+
res.writeHead(200,{'Content-Type':type+'; charset=utf-8','Cache-Control':'no-store','X-Content-Type-Options':'nosniff','Content-Security-Policy':"default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"});res.end(readFileSync(path.join(assets,file)));
|
|
64
|
+
}catch{json(res,400,{error:'unavailable'});}
|
|
65
|
+
});
|
|
66
|
+
const close=()=>new Promise(resolve=>{if(stopping){resolve();return;}stopping=true;stopPolling();clearTimeout(idleTimer);for(const c of clients)c.end();server.close(resolve);for(const socket of sockets)socket.destroy();process.removeListener('SIGINT',signal);process.removeListener('SIGTERM',signal);});
|
|
67
|
+
server.on('connection',socket=>{sockets.add(socket);socket.once('close',()=>sockets.delete(socket));});
|
|
68
|
+
const signal=()=>{void close();};
|
|
69
|
+
await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(port,'127.0.0.1',()=>{server.removeListener('error',reject);resolve();});});
|
|
70
|
+
boundPort=server.address().port;const url=`http://127.0.0.1:${boundPort}`;
|
|
71
|
+
deferShutdown();
|
|
72
|
+
process.once('SIGINT',signal);process.once('SIGTERM',signal);
|
|
73
|
+
const result={url,close,source,server};if(onReady)onReady(result);
|
|
74
|
+
if(openBrowser)openProgressBrowser(url);
|
|
75
|
+
return result;
|
|
76
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
@charset "UTF-8";
|
|
2
|
+
.brand-label{display:flex;flex-direction:column;align-items:flex-start;line-height:1.25;gap:3px}.kit-version{font-size:11px;font-weight:500;line-height:1.25;letter-spacing:.15px;color:var(--muted)}.kit-version[data-state=different],.kit-version[data-state=unverified]{color:#805400}
|
|
3
|
+
:root{color-scheme:light;--paper:#faf8f3;--ink:#121720;--muted:#67707c;--line:#e5e3df;--blue:#1454ff;--red:#ee303e;--yellow:#ffcf13;--green:#00997b;--radius:18px;--control-face:linear-gradient(150deg,#fffefa,#f0ede6);--control-border:#dedbd3;--control-shadow:inset 0 1px 1px #fff,inset 0 -1px 2px #897d6414,0 4px 10px #4b453714;--control-pressed:inset 0 2px 5px #53493424,0 1px 2px #fff;--action-face:linear-gradient(155deg,#3862ba,#244a98 56%,#183a7f);--action-shadow:inset 0 1px 1px #ffffff60,inset 0 -2px 3px #10255340,0 6px 14px #254c8f28;font:16px/1.65 "Segoe UI","Microsoft JhengHei","PingFang TC",sans-serif}
|
|
4
|
+
*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);min-width:320px}h1,h2,h3,p{margin:0}h1,h2,h3{line-height:1.3}button,input,select{font:inherit;color:inherit}button,a,input,select{outline-offset:5px}button:focus-visible,a:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--blue)}button{border:0;background:none;cursor:pointer}button:disabled{opacity:.5;cursor:default}a{color:inherit;text-decoration:none}button,a{touch-action:manipulation}[hidden]{display:none!important}svg{width:23px;height:23px;fill:none;stroke:currentColor;stroke-width:1.7;flex-shrink:0}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.skip{position:fixed;top:-80px;left:20px;z-index:50;background:var(--yellow);padding:10px 20px}.skip:focus{top:12px}
|
|
5
|
+
.brandbar{min-height:90px;padding:14px max(4vw,24px);display:flex;align-items:center;justify-content:space-between;gap:24px;border-bottom:1px solid var(--line);background:#fffaf4a6}.brand{display:flex;align-items:center;gap:14px;font-size:21px;font-weight:750;white-space:nowrap;letter-spacing:-.5px}.brand img{width:47px;height:47px;object-fit:contain}nav{display:flex;gap:34px;align-self:stretch;align-items:center}nav a{font-size:15px;font-weight:650;padding:18px 2px;position:relative}nav a[aria-current=page]:after{content:"";height:4px;border-radius:5px;background:var(--action-face);box-shadow:inset 0 1px 1px #ffffff55,0 2px 4px #26488920;position:absolute;bottom:4px;left:0;right:0}.tools{display:flex;align-items:center;gap:24px}#sync{font-size:13px;color:var(--muted);white-space:nowrap}#sync:before{content:"";display:inline-block;width:9px;height:9px;background:#a78326;border-radius:50%;margin-right:9px}body[data-live=true] #sync:before{background:#119961}#language{border:1px solid var(--control-border);border-radius:14px;background:var(--control-face);box-shadow:var(--control-shadow);padding:10px 14px;font-size:14px;min-height:44px}main{max-width:1500px;margin:auto;padding:0 40px}button,.node-circle,.panel{transition:background-color .18s,box-shadow .18s,transform .18s,border-color .18s}.project{padding:36px 20px 16px;position:relative}.eyebrow{font-size:12px;letter-spacing:1.2px;color:var(--muted);margin-bottom:10px}h1{font-size:clamp(30px,3.4vw,48px);font-weight:750;letter-spacing:-1.3px}#goal{font-size:19px;color:#535c68;line-height:1.65;max-width:970px;margin:12px 0 12px;overflow-wrap:anywhere}.quiet{font-size:13px;color:var(--muted);padding:8px 0;display:inline-flex;align-items:center;gap:9px;min-height:40px}.quiet svg{width:18px;height:18px}.text-link{color:#2758b0;font-size:13px;font-weight:550;display:inline-flex;align-items:center;gap:7px;padding:9px 0;min-height:40px}.text-link:hover,.quiet:hover{color:var(--blue);text-decoration:underline}.text-link svg{width:17px;height:17px}.journey{padding:4px 36px 22px;text-align:center}.work-route{display:flex;justify-content:space-around;align-items:flex-start;gap:20px;position:relative}.route-node{min-width:0;flex:1;max-width:360px;position:relative;padding:0 15px 12px;z-index:1}.route-node:before{content:none;height:2px;position:absolute;left:calc(50% + 45px);right:calc(-50% + 5px);top:48px;background:var(--ink);z-index:-1}.route-node:last-child:before{display:none}/* Shared matte material: local light, shade and contact shadow for every object icon. */
|
|
6
|
+
.node-circle,.mini-node{--object-light:#f7745b;--object-mid:#d63b31;--object-dark:#98231f;--object-glow:#b833242c;--object-shadow:inset 2px 2px 3px #ffffff57,inset -5px -7px 12px #0012232e,0 10px 18px var(--object-glow);background:radial-gradient(ellipse at 27% 18%,#ffffff26,transparent 58%),linear-gradient(145deg,var(--object-light),var(--object-mid) 55%,var(--object-dark));border:1px solid #ffffff50;box-shadow:var(--object-shadow)}
|
|
7
|
+
.node-circle{width:94px;height:94px;border-radius:50%;display:flex;align-items:center;justify-content:center;margin:0 auto 20px;color:#fffaf1}.route-node:nth-child(3n+2) .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.route-node:nth-child(3n) .node-circle{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.route-node[aria-pressed=true] .node-circle{border-color:#ffffffc4;outline:1px solid #bdcceb;outline-offset:7px;box-shadow:var(--object-shadow),0 0 0 7px #edf1fb,0 12px 24px #254a8b21;transform:scale(1.08)}.route-node:hover .node-circle{transform:translateY(-3px)}.node-circle svg{width:37px;height:37px;stroke-width:1.8;filter:drop-shadow(0 2px 1px #15332c35)}.route-node strong{display:block;font-size:20px;font-weight:700;margin-bottom:7px;overflow-wrap:anywhere}.route-node .description{display:block;font-size:14px;line-height:1.7;color:var(--muted);max-width:270px;margin:auto;overflow-wrap:anywhere}.route-node .relation{display:block;font-size:12px;color:var(--muted);margin-top:6px}.focus-panel{display:inline-block;text-align:center;max-width:740px;min-width:min(440px,100%);padding:20px 28px 17px;border:1px solid #dbe1ec;background:linear-gradient(155deg,#fffefa,#f0f3f9);border-radius:16px;margin-top:14px;box-shadow:inset 0 1px 1px #fff,0 8px 24px #273b560a}.focus-panel h2{font-size:18px;line-height:1.6}.focus-panel .focus-summary{font-size:14px;color:var(--muted);max-width:610px;margin:7px auto 8px;overflow-wrap:anywhere}.focus-actions{display:flex;gap:10px;align-items:center;justify-content:center;margin-top:10px}.primary{background:var(--action-face);box-shadow:var(--action-shadow);text-shadow:0 1px 1px #102f6650;color:#fff;padding:10px 24px;border-radius:10px;font-size:14px;font-weight:650;min-height:43px;display:inline-flex;align-items:center;justify-content:center;gap:12px;border:1px solid #244a8e}.primary:hover{box-shadow:var(--action-shadow),0 9px 20px #254c8f20;filter:brightness(1.06);transform:translateY(-2px)}.secondary{background:var(--control-face);box-shadow:var(--control-shadow);border:1px solid var(--control-border);border-radius:10px;padding:10px 16px;min-height:43px;font-size:14px}.secondary:hover{border-color:#a7b7ce;box-shadow:var(--control-shadow),0 6px 14px #3c486514;transform:translateY(-1px)}.pill{--pill-bg:#eef1f5;display:inline-flex;align-items:center;gap:7px;border-radius:20px;background:linear-gradient(155deg,#ffffff8f,#ffffff00),var(--pill-bg);border:1px solid #ffffff8c;box-shadow:inset 0 1px 0 #ffffffb8,0 2px 4px #463e3010;color:#455264;font-size:12px;padding:3px 11px;margin:6px 3px;white-space:nowrap}.pill:before{content:"";width:7px;height:7px;border-radius:50%;background:currentColor;box-shadow:inset 0 1px 1px #ffffff77,0 1px 2px #19202a24}.pill.active{--pill-bg:#e5edff;color:#1954e3}.pill.waiting,.pill.review{--pill-bg:#fff3c3;color:#7b5700}.pill.done{--pill-bg:#dcf3e9;color:#006c52}.pill.paused,.pill.dropped{--pill-bg:#ececec;color:#555}.overview-grid{display:grid;grid-template-columns:.95fr 1.12fr;gap:20px}.panel{background:#ffffffd9;border:1px solid #edecea;border-radius:var(--radius);padding:22px 27px;min-width:0;box-shadow:0 5px 20px #2e2d2303}.section-heading{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-bottom:12px}.section-heading h2{display:flex;gap:12px;align-items:center;font-size:17px}.section-heading h2>svg{width:29px;height:29px;padding:5px;box-sizing:border-box;border-radius:9px;background:var(--control-face);border:1px solid #ffffffb8;box-shadow:var(--control-shadow)}.section-heading .text-link{flex-shrink:0}.recent-list{position:relative}.recent-row{display:grid;grid-template-columns:16px 75px 1fr;gap:14px;text-align:left;width:100%;padding:11px 0;min-width:0;position:relative}.recent-row:before{content:"";width:11px;height:11px;background:#111;border-radius:50%;margin-top:7px;box-shadow:0 0 0 4px white;z-index:1}.recent-row:first-child:before{background:var(--blue)}.recent-row:not(:last-child):after{content:"";position:absolute;left:5px;top:28px;bottom:-6px;width:1px;background:#b5b9be}.recent-row time{font-size:13px;color:var(--muted);padding-top:3px}.recent-row strong{display:block;font-size:14px;line-height:1.6}.recent-row small{display:block;color:var(--muted);font-size:12px;line-height:1.6;margin-top:4px}.recent-row:hover strong{color:var(--blue)}.pending-columns{display:grid;grid-template-columns:1.25fr .8fr;gap:20px}.work-row{display:flex;align-items:flex-start;gap:10px;width:100%;text-align:left;padding:11px 0;border-bottom:1px solid var(--line)}.work-row:last-child{border:0}.work-row .pill{margin:0;flex-shrink:0}.work-row strong{font-size:14px;line-height:1.6;display:block}.work-row small{display:block;font-size:12px;color:var(--muted);line-height:1.6;margin-top:4px}.results{border-left:1px solid var(--line);padding-left:20px}.results h3{font-size:14px;margin:4px 0 12px}.result-row{display:flex;gap:10px;text-align:left;width:100%;padding:9px 0;align-items:flex-start}.result-row svg{color:var(--blue);width:22px;height:22px}.result-row strong{font-size:13px;display:block}.result-row small{font-size:11px;color:var(--muted);display:block;overflow-wrap:anywhere}.document-strip{display:flex;align-items:center;gap:24px;margin-top:20px;padding:20px 26px}.strip-intro{flex:0 0 215px}.strip-intro h2{font-size:16px;margin-bottom:5px}.strip-intro p{font-size:12px;color:var(--muted)}#document-strip{display:flex;justify-content:space-around;gap:24px;flex:1}.strip-node{display:flex;align-items:center;gap:12px;text-align:left;position:relative}.mini-node{width:50px;height:50px;color:#fffaf1;border-radius:50%;display:flex;align-items:center;justify-content:center;flex-shrink:0}.mini-node svg{filter:drop-shadow(0 1px 1px #15332c35)}.strip-node:nth-child(2) .mini-node{--object-light:#ffe077;--object-mid:#edb723;--object-dark:#be8612;--object-glow:#af7a0929;color:#151515}.strip-node:nth-child(3) .mini-node{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.strip-node:nth-child(4) .mini-node{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.strip-node strong{font-size:13px;display:block}.strip-node small{font-size:10px;color:var(--muted);display:block;max-width:135px;overflow-wrap:anywhere}.warning{padding:15px 20px;background:#fff3d6;border:1px solid #eed394;border-radius:12px;margin:20px 0;font-size:14px}.empty{font-size:14px;color:var(--muted);padding:16px 0;line-height:1.8}.view-header{padding:38px 20px 24px;display:flex;align-items:center;justify-content:space-between;gap:20px}.view-header p:not(.eyebrow){color:var(--muted);margin-top:10px}.filterbar{display:flex;flex-wrap:wrap;gap:12px;align-items:center;margin:0 20px 8px}.filterbar label{display:flex;align-items:center;gap:8px;font-size:13px}.filterbar input{box-shadow:inset 0 2px 4px #6057400d,0 1px 0 #fff;border:1px solid var(--control-border);border-radius:10px;padding:9px 12px;background:#fff;min-height:44px;font-size:14px}.search-label input{width:160px}.segmented{display:inline-flex;border:1px solid var(--control-border);border-radius:12px;padding:4px;background:#eae7df;box-shadow:inset 0 1px 3px #51473114,0 1px 0 #fff;gap:3px}.segmented button{border-radius:9px;padding:8px 14px;font-size:13px;min-height:36px}.segmented button[aria-pressed=true]{background:var(--action-face);box-shadow:var(--action-shadow);color:#fff}.segmented button:not([aria-pressed=true]):hover{background:var(--control-face);box-shadow:var(--control-shadow)}.scope-note{color:var(--muted);font-size:12px;margin:10px 20px 16px;line-height:1.8}.timeline{max-width:1040px;padding:18px 20px 25px}.day{display:grid;grid-template-columns:125px 1fr;gap:28px}.day>h2{font-size:18px;padding-top:18px}.day-events{border-left:2px solid #c2c7ce;padding:0 0 23px 30px}.event{display:block;width:100%;text-align:left;padding:18px 22px;background:white;border:1px solid var(--line);border-radius:13px;position:relative;margin-bottom:14px}.event:before{content:"";position:absolute;left:-38px;top:24px;width:12px;height:12px;border:2px solid var(--paper);border-radius:50%;background:var(--blue);box-shadow:0 0 0 1px var(--blue)}.event:hover{border-color:#9cb8ff;transform:translateX(3px)}.event strong{font-size:17px;line-height:1.55}.event p{font-size:14px;color:var(--muted);margin:7px 0}.event .event-meta{font-size:11px;color:var(--muted)}#history-more{margin:0 20px 25px}.document-map{position:relative;min-height:520px;display:grid;grid-template-columns:repeat(4,1fr);gap:40px 34px;padding:48px 40px;background:#ffffff7a;border:1px solid var(--line);border-radius:20px}.doc-node{position:relative;z-index:1;display:flex;align-items:center;flex-direction:column;text-align:center;gap:10px;padding:15px 10px;border:1px solid transparent;border-radius:14px}.doc-node:hover,.doc-node.related{background:#f0f4ff;border-color:#dce5ff}.doc-node .node-circle{width:73px;height:73px;margin:0 0 5px;border-width:1px}.doc-node[data-role=handoff] .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e;color:white}.doc-node[data-role=log] .node-circle{--object-light:#ffe077;--object-mid:#edb723;--object-dark:#be8612;--object-glow:#af7a0929;color:#111}.doc-node[data-role=decisions] .node-circle{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.doc-node strong{font-size:16px}.doc-node small{font-size:11px;color:var(--muted);overflow-wrap:anywhere;max-width:200px}.doc-node .relations{font-size:11px;color:#526c96}.doc-node.missing{opacity:.6}.document-list{background:white;border:1px solid var(--line);border-radius:16px;overflow:hidden}.document-list button{width:100%;display:grid;grid-template-columns:210px 1fr 110px;padding:18px 24px;border-bottom:1px solid var(--line);text-align:left;gap:16px}.document-list small{color:var(--muted);overflow-wrap:anywhere}footer{padding:25px 0 20px;display:flex;align-items:center;justify-content:space-between;gap:20px;color:var(--muted);font-size:12px}dialog{position:fixed;inset:0 0 0 auto;margin:0;width:min(560px,95vw);max-width:none;height:100dvh;max-height:none;border:0;border-left:1px solid var(--line);background:#fffefa;color:var(--ink);padding:32px;box-shadow:-15px 0 70px #141f3415;overflow:auto;overscroll-behavior:contain}dialog::backdrop{background:#18223126;backdrop-filter:blur(2px)}dialog>header{display:flex;justify-content:space-between;align-items:flex-start;gap:18px;border-bottom:1px solid var(--line);padding-bottom:22px;margin-bottom:22px}dialog h2{font-size:26px;line-height:1.5;overflow-wrap:anywhere}dialog h3{font-size:15px;margin:22px 0 9px}.icon-button{width:40px;height:40px;min-width:40px;display:flex;align-items:center;justify-content:center;border-radius:50%;background:var(--control-face);border:1px solid var(--control-border);box-shadow:var(--control-shadow)}.icon-button:hover{transform:translateY(-1px)}.icon-button:active,.segmented button:active{box-shadow:var(--control-pressed);transform:translateY(1px)}dialog p,dialog pre{overflow-wrap:anywhere;white-space:pre-wrap;font:14px/1.85 "Segoe UI","Microsoft JhengHei",sans-serif}dialog pre{background:#f8f7f2;padding:16px;border:1px solid var(--line);border-radius:10px}dialog .citation{font-size:12px;color:var(--muted);margin:20px 0;overflow-wrap:anywhere}.drawer-actions{display:flex;gap:10px;flex-wrap:wrap;margin:20px 0}.source-row{padding:14px 0;border-bottom:1px solid var(--line)}.source-row small{display:block;color:var(--muted);font-size:12px}.updated-note{font-size:12px;color:#175994;margin:12px 0}.work-list .work-row{padding:16px 0}.work-list .work-row strong{font-size:16px}.view{animation:arrive .22s ease-out}@keyframes arrive{from{opacity:.4;transform:translateY(4px)}to{opacity:1;transform:none}}
|
|
8
|
+
@media(min-width:1500px){.project{padding-top:45px}.journey{padding-top:12px;padding-bottom:28px}}
|
|
9
|
+
@media(max-width:1100px){.brandbar{gap:18px;padding:14px 25px}.brand{font-size:17px}nav{gap:22px}.tools{gap:12px}.overview-grid{grid-template-columns:1fr 1fr}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0;display:flex;gap:18px;flex-wrap:wrap}.results h3{width:100%;margin:0}.result-row{width:auto}.document-strip{flex-wrap:wrap}.strip-intro{flex-basis:100%}#document-strip{gap:18px}.strip-node small{max-width:100px}.document-map{grid-template-columns:repeat(3,1fr)}.route-node strong{font-size:18px}}
|
|
10
|
+
@media(max-width:760px){main{padding:0 20px}.brandbar{flex-wrap:wrap;gap:8px 14px;padding:12px 20px}.brand{font-size:16px}.brand img{width:38px;height:38px}.tools{margin-left:auto}#sync{font-size:11px}#language{font-size:12px;padding:7px;min-height:38px}nav{order:3;width:100%;justify-content:center;gap:40px}nav a{padding:12px 2px;font-size:14px}.project{padding:26px 2px 16px}h1{font-size:32px;letter-spacing:-.6px}#goal{font-size:16px}.journey{padding:8px 0 22px}.work-route{gap:8px;overflow-x:auto;justify-content:flex-start;padding:10px 6px;scroll-snap-type:x proximity}.route-node{min-width:150px;padding:0 7px;scroll-snap-align:center}.route-node .description{font-size:12px}.route-node strong{font-size:15px}.node-circle{width:70px;height:70px;border-width:1px;margin-bottom:15px}.node-circle svg{width:30px;height:30px}.route-node:before{top:35px;left:calc(50% + 35px);right:calc(-50% + 1px)}.focus-panel{padding:17px 18px;width:100%;min-width:0}.focus-panel h2{font-size:16px}.overview-grid{grid-template-columns:1fr;gap:15px}.panel{padding:20px}.pending-columns{grid-template-columns:1.2fr 1fr;gap:16px}.results{display:block;border-left:1px solid var(--line);border-top:0;padding:0 0 0 15px}.results h3{margin-bottom:8px}.document-strip{gap:14px}#document-strip{display:grid;grid-template-columns:1fr 1fr;width:100%;gap:17px}.strip-node small{max-width:120px}.document-strip>.text-link{margin-left:auto}.recent-row{grid-template-columns:12px 58px 1fr;gap:12px}.recent-row time{font-size:11px}.view-header{padding:28px 0 20px;flex-wrap:wrap}.view-header .segmented{margin-left:auto}.filterbar{margin:0;gap:10px}.filterbar label{flex:1}.filterbar input{min-width:0;width:100%;font-size:13px}.filterbar .search-label{flex-basis:65%}.segmented button{font-size:12px;padding:8px 11px}.scope-note{margin:12px 0}.timeline{padding:12px 0}.day{grid-template-columns:1fr;gap:10px}.day>h2{padding-top:4px;font-size:16px}.day-events{margin-left:8px;padding-left:22px}.event:before{left:-30px}.event{padding:15px}.event strong{font-size:15px}.event p{font-size:13px}#history-more{margin-left:0}.document-map{grid-template-columns:repeat(2,1fr);gap:15px;padding:20px 10px}.doc-node{padding:10px 6px}.doc-node strong{font-size:14px}.doc-node small{font-size:10px}.document-list button{grid-template-columns:1fr;padding:15px;gap:5px}footer{font-size:11px;align-items:flex-start}footer .quiet{font-size:11px;flex-shrink:0}dialog{padding:24px;width:min(540px,100vw)}dialog h2{font-size:23px}}
|
|
11
|
+
@media(max-width:420px){.tools{gap:8px}#sync{display:none}.brand{font-size:15px}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0}.result-row{padding:6px 0}}
|
|
12
|
+
@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}}
|
|
13
|
+
/* Brand geometry supports navigation; motion is driven by state and user input. */
|
|
14
|
+
.brandbar{min-height:82px}.project{padding:28px 20px 12px}.project:after{content:"";position:absolute;right:26px;top:25px;width:95px;height:95px;background:var(--yellow);border-radius:50%;box-shadow:88px -35px 0 10px var(--red);opacity:.92;pointer-events:none}.project:before{content:"";position:absolute;right:72px;top:33px;width:145px;height:100px;border:1.5px solid #222;border-left-style:dashed;border-bottom-style:dashed;border-radius:0 32px 32px 22px;pointer-events:none}#goal{font-size:20px;margin:10px 0 6px;padding-right:170px}.journey{padding:0 40px 18px}.journey-label{font-size:11px;font-weight:500;color:var(--muted);text-align:left;margin:0 0 6px;letter-spacing:1px}.route-node{padding-bottom:5px}.node-circle{width:86px;height:86px;margin-bottom:12px}.route-node:before{top:43px}.route-node:after{content:none;position:absolute;width:11px;height:11px;background:var(--ink);border:3px solid var(--paper);border-radius:50%;right:-17px;top:38px}.route-node:last-child:after{display:none}.route-node .description{font-size:14px;max-width:290px}.route-node .relation{margin-top:3px;font-size:11px}.focus-panel{margin-top:12px;padding:14px 24px;position:relative;min-width:400px}.focus-panel:before{content:"";position:absolute;top:-7px;left:calc(50% - 6px);width:12px;height:12px;border-left:1px solid #dbe1ec;border-top:1px solid #dbe1ec;background:#fffefa;transform:rotate(45deg)}.focus-panel .pill{margin:5px 3px}.focus-actions{margin-top:4px}.focus-panel .primary{min-height:40px;padding:8px 24px}.panel{padding:18px 24px}.recent-row{padding:9px 0}.work-row{padding:8px 0}.result-row small{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}.document-strip{margin-top:16px;padding:18px 24px}.section-heading{margin-bottom:8px}.strip-intro{flex-basis:190px}.map-lines{position:absolute;inset:0;width:100%;height:100%;stroke-width:1.6;color:#9ba3af;overflow:visible;pointer-events:none}.map-lines>path{fill:none;stroke:currentColor;opacity:.35;transition:opacity .2s}.map-lines>path.lit{stroke:var(--blue);color:var(--blue);opacity:1;stroke-dasharray:7 5;animation:trace .7s ease-out}.document-map{min-height:450px;gap:46px 38px;padding:35px 40px}.doc-node{transition:opacity .2s,transform .2s,background-color .2s}.doc-node.subdued{opacity:.5}.doc-node .node-circle{box-shadow:var(--object-shadow),0 0 0 7px var(--paper)}.doc-node[aria-pressed=true]{background:linear-gradient(150deg,#fffefa,#eaf0fa);border-color:#c6d7ec;box-shadow:var(--control-shadow);transform:translateY(-3px)}.doc-node.related:not([aria-pressed=true]){background:transparent}.doc-node:hover{opacity:1;transform:translateY(-3px)}.doc-node.missing{opacity:.5}.map-detail{margin-top:18px;display:flex;align-items:center;justify-content:space-between;gap:24px}.map-detail h2{font-size:18px}.map-detail p{font-size:14px;color:var(--muted);margin-top:5px}.map-relations{display:flex;flex-direction:column;font-size:13px}.map-relations .text-link{padding:2px;min-height:30px}.filterbar select{border:1px solid var(--control-border);background:var(--control-face);box-shadow:var(--control-shadow);border-radius:10px;min-height:44px;padding:8px 12px;font-size:13px;max-width:200px}.timeline{position:relative;min-height:100px}.timeline[aria-busy=true]:before{content:"";height:3px;background:var(--blue);width:25%;position:absolute;top:0;left:20px;animation:read .9s ease-in-out infinite alternate;border-radius:4px}.route-node:hover .node-circle{box-shadow:var(--object-shadow),0 12px 24px #293a5214;transform:translateY(-4px)}.strip-node:hover .mini-node{transform:translateY(-3px);box-shadow:var(--object-shadow),0 8px 16px #293a5214}.mini-node{transition:transform .2s,box-shadow .2s}.event:hover{box-shadow:0 6px 18px #234c8410}.primary:active,.secondary:active{transform:translateY(1px) scale(.985);box-shadow:var(--control-pressed)}@keyframes trace{from{stroke-dashoffset:40;opacity:.2}to{stroke-dashoffset:0;opacity:1}}@keyframes read{from{transform:translateX(0)}to{transform:translateX(220%)}}
|
|
15
|
+
@media(max-width:1100px){.project:after,.project:before{opacity:.4;transform:scale(.75);transform-origin:top right}#goal{padding-right:170px}.map-detail{flex-wrap:wrap}.map-detail>div:first-child{flex:1 1 100%}.document-map{grid-template-columns:repeat(4,1fr);padding:30px 20px;gap:40px 10px}}
|
|
16
|
+
@media(max-width:760px){.brandbar{min-height:0}.project{padding:26px 2px 16px}.project:before,.project:after{display:none}#goal{padding-right:0;font-size:16px}.journey{padding:0 0 18px}.journey-label{margin-bottom:0}.node-circle{width:70px;height:70px}.route-node:before{top:35px}.route-node:after{top:30px;right:-14px}.focus-panel{min-width:0;padding:14px}.panel{padding:20px}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0}.document-map{grid-template-columns:repeat(2,1fr);gap:30px 12px;padding:22px 10px}.map-detail{gap:12px}.map-relations{width:100%}.doc-node strong{font-size:14px}.doc-node small{max-width:135px}.filterbar select{max-width:none;width:100%}.project h1{font-size:30px}.filterbar .segmented{flex-basis:100%}.timeline[aria-busy=true]:before{left:0}}
|
|
17
|
+
@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}.timeline[aria-busy=true]:before{width:100%;opacity:.35}}
|
|
18
|
+
|
|
19
|
+
.route-node .description{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;min-height:48px}.route-node .relation{position:static;width:auto;height:auto;overflow:visible;clip:auto}.doc-node.subdued{opacity:1}.doc-node.subdued .node-circle{filter:saturate(.55);opacity:.8}.doc-node[data-role=index] .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.work-route{padding-top:2px}.focus-panel{margin-top:8px}.project{overflow:hidden}
|
|
20
|
+
.recent-row strong,.recent-row small{display:-webkit-box;-webkit-line-clamp:1;-webkit-box-orient:vertical;overflow:hidden}@media(max-width:760px){.recent-row strong{-webkit-line-clamp:2}}
|
|
21
|
+
.project:before,.project:after{display:none;content:none}
|
|
22
|
+
.project{display:grid;grid-template-columns:minmax(0,1fr) minmax(280px,38%);grid-template-rows:1fr auto;gap:10px 32px;align-items:center;padding:20px 20px 24px;overflow:visible}
|
|
23
|
+
.project-copy{grid-column:1;grid-row:1;min-width:0;align-self:end}.project-meta{grid-column:1;grid-row:2;min-width:0;align-self:start}
|
|
24
|
+
.project-art{grid-column:2;grid-row:1 / span 2;width:100%;height:auto;max-height:280px;object-fit:contain;display:block;pointer-events:none}
|
|
25
|
+
@media(max-width:760px){.project{grid-template-columns:minmax(0,1fr) 115px;grid-template-rows:auto auto;gap:12px;padding:24px 2px 18px}.project-copy{align-self:center}.project-art{grid-row:1;width:115px}.project-meta{grid-column:1 / -1;grid-row:2}.project h1{font-size:28px}.project .eyebrow{font-size:10px;letter-spacing:.7px}}
|
|
26
|
+
|
|
27
|
+
.journey-label{font-size:13px;margin:0 0 4px;text-align:center}.journey{padding-top:0}.focus-panel{margin-top:4px}
|
|
28
|
+
|
|
29
|
+
.recorded-current{display:block;text-align:left;max-width:min(970px,100%);line-height:1.5;overflow-wrap:anywhere;padding-top:0}.legacy-label{font-size:13px;margin-top:12px}#work-scope{margin:0 0 14px}.route-node .relation{font-weight:600}
|
|
30
|
+
|
|
31
|
+
#pending-list>.text-link{display:block;margin-top:10px}
|
package/docs/commands.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# 快捷入口 / Kit shortcuts
|
|
2
|
+
|
|
3
|
+
啟用後,在專案的 AI 對話輸入短口令即可。Claude Code、Gemini CLI、Antigravity CLI 用 `/handoff-kit-help`;Codex 用 `$handoff-kit-help`,或輸入 `/skills` 選擇 `handoff-kit-help`。Codex 並不提供相同的直接 `/handoff-kit-*` 自訂命令。
|
|
4
|
+
|
|
5
|
+
| 用途 | Claude / Gemini / Antigravity | Codex |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| 開工、接收交接 | `/handoff-kit-start` | `$handoff-kit-start` |
|
|
8
|
+
| 收工、保存及檢查交接 | `/handoff-kit-close` | `$handoff-kit-close` |
|
|
9
|
+
| 開啟自動更新的進度頁 | `/handoff-kit-progress` | `$handoff-kit-progress` |
|
|
10
|
+
| 檢查文件是否接上治理 | `/handoff-kit-align` | `$handoff-kit-align` |
|
|
11
|
+
| 新手引導 | `/handoff-kit-onboard` | `$handoff-kit-onboard` |
|
|
12
|
+
| 保存日後要遵守的工作規則 | `/handoff-kit-remember` | `$handoff-kit-remember` |
|
|
13
|
+
| 檢查 Kit 安裝狀態 | `/handoff-kit-check` | `$handoff-kit-check` |
|
|
14
|
+
| 顯示這份功能選單 | `/handoff-kit-help` | `$handoff-kit-help` |
|
|
15
|
+
|
|
16
|
+
可在口令後補充目標,例如 `/handoff-kit-align docs/plan.md`、`/handoff-kit-remember 回覆請用繁體中文`,或 `/handoff-kit-start 繼續完成目前目標`。單獨開工只接收狀態;未指定文件的對齊先列候選,不自行整理整個專案。收工會執行原有完整流程,但不新增提交或發佈權限。原有「開工」「收工」等自然語句仍可使用。
|
|
17
|
+
|
|
18
|
+
## 每個專案啟用一次
|
|
19
|
+
|
|
20
|
+
對 AI 說:「在這個專案啟用 Kit 常用快捷入口。」正常 AI 安裝教學亦包含這一步。AI 應先完成 Kit 安裝/升級及其驗收,再執行:
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --dry-run
|
|
24
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --yes
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
預設建立全部平台入口;`--agent claude|gemini|codex|antigravity` 可只建立指定平台。Codex 與 Antigravity 共用一份 `.agents/skills`。程序只建立缺少的入口;相同內容保持不動;任何同名差異會在寫入前停止,不覆寫用戶設定。中斷時保留已完成入口,重新預覽再補齊。此程序不代替 Kit 健康檢查,亦不修改全機設定或官方規則正文。
|
|
28
|
+
|
|
29
|
+
快捷入口只可安裝在專案內。預覽及啟用都會拒絕使用者主目錄、磁碟根目錄,以及已知的 AI 全域設定位置(包括環境變數指定的位置);即使目錄已有 Kit 檔案也不例外。若任何入口的輸出位置會落入全域範圍,整批停止,不建立檔案或目錄。主目錄下的一般專案及 Codex 管理的 `worktrees` 內專案仍可使用;全域設定資料夾本身不能當作專案。
|
|
30
|
+
|
|
31
|
+
如入口未出現,重新開啟該專案的 AI 對話;Gemini CLI 亦可用 `/commands reload`。舊版 CLI 若顯示不認識 `commands`,代表執行的套件未包含此功能。未發佈開發版必須使用已選定的本機套件,不能把 npm 舊版當成新功能驗收。
|
|
32
|
+
|
|
33
|
+
入口由 `bin/commands.mjs` 統一產生。Claude 使用 `.claude/skills/handoff-kit-*/SKILL.md`,Gemini 使用 `.gemini/commands/handoff-kit-*.toml`,Codex/Antigravity 使用 `.agents/skills/handoff-kit-*/SKILL.md`。規則仍由專案 `AGENTS.md`、`dev/RULE_PACKS.md` 及其指向的文件負責。這些入口不會因被 AI 自動發現便授權執行。
|
|
34
|
+
|
|
35
|
+
## 進度頁與使用成本
|
|
36
|
+
|
|
37
|
+
`handoff-kit-progress` 自動開啟頁面,同一專案重複使用會重用相符服務。全部頁面斷線後保留 8 小時,閒置時暫停讀檔;其後服務才自動停止,下次再用口令會重新啟動。不同專案各自識別;頁面正在顯示哪個專案,以頁面專案名稱為準。詳見[進度頁說明](progress.md)。
|
|
38
|
+
|
|
39
|
+
口令本身由 AI 處理,會使用少量對話內容;進度頁之後由本機程式讀取既有紀錄並自動更新,不需 AI 再寫報告、重做 HTML 或逐步呼叫更新。使用既有 Node.js 18+ 與瀏覽器,不需額外安裝 Python 或服務平台。`npx` 取得工具可能需要網絡;頁面服務本身只在本機運行。
|
|
40
|
+
|
|
41
|
+
## English
|
|
42
|
+
|
|
43
|
+
Use `/handoff-kit-*` in Claude Code, Gemini CLI and Antigravity CLI. In Codex, use `$handoff-kit-*` or select the skill through `/skills`; direct custom `/handoff-kit-*` commands are not equivalent Codex syntax.
|
|
44
|
+
|
|
45
|
+
The eight entries are **handoff-kit-start** (resume), **handoff-kit-close** (save and verify the full handoff), **handoff-kit-progress** (open the live overview), **handoff-kit-align** (check document governance links), **handoff-kit-onboard** (guided introduction), **handoff-kit-remember** (save an explicitly requested future working rule), **handoff-kit-check** (check the Kit installation), and **handoff-kit-help** (menu).
|
|
46
|
+
|
|
47
|
+
Add context after an entry, such as `/handoff-kit-align docs/plan.md` or `/handoff-kit-start continue the current objective`. Bare start only recovers state. Alignment without a target lists candidates before any edits. Closeout follows the existing complete workflow without granting Git or publishing permission. Natural-language requests still work.
|
|
48
|
+
|
|
49
|
+
Ask the AI to “Enable Kit shortcuts in this project.” After installing/upgrading Kit and verifying that operation, run the two commands above: preview, then enable with `--yes`. This setup step is included in the AI installation guide. The default enables all platforms; `--agent claude|gemini|codex|antigravity` selects one. Codex and Antigravity share `.agents/skills`. Missing files are created, identical files kept, and any different same-name file stops the preflight with zero writes. After interruption, completed files remain and a new preview shows what is left. This setup does not replace health checks, change global settings or rewrite official rules.
|
|
50
|
+
|
|
51
|
+
Shortcuts are project-local only. Preview and enable both refuse user home directories, filesystem roots and known shared AI configuration locations, including environment-configured locations, even if Kit files exist there. If any generated entry would land in global scope, the whole operation stops without creating files or directories. Ordinary projects beneath home and projects inside Codex-managed `worktrees` remain supported; the global configuration folder itself cannot serve as a project.
|
|
52
|
+
|
|
53
|
+
Reopen the project's AI session if entries do not appear; Gemini also supports `/commands reload`. An unrecognized `commands` option means the running package lacks this feature. Use the selected local package for unreleased development; testing npm's older release cannot verify new features.
|
|
54
|
+
|
|
55
|
+
`bin/commands.mjs` owns the shared content and generates Claude `.claude/skills/handoff-kit-*/SKILL.md`, Gemini `.gemini/commands/handoff-kit-*.toml`, and Codex/Antigravity `.agents/skills/handoff-kit-*/SKILL.md`. Project `AGENTS.md`, `dev/RULE_PACKS.md` and their routed owners still define procedures. Automatic skill discovery does not authorize action.
|
|
56
|
+
|
|
57
|
+
`handoff-kit-progress` opens the view and reuses a matching service for the same project. The service stays available for eight hours after all pages disconnect, without idle file polling; invoke the entry again to reuse it or restart it after expiry. Projects have separate identities; check the displayed project name. See [the progress guide](progress.md). An AI invocation uses some conversation tokens; subsequent page updates read existing records locally, without more AI reports, redesigned HTML or per-step update calls. It uses the existing Node.js 18+ environment and a browser; no Python or hosting platform is required. `npx` tool acquisition may need network access, while the view itself runs locally.
|
|
58
|
+
|
|
59
|
+
Platform references: [Claude skills](https://code.claude.com/docs/en/skills), [Gemini custom commands](https://geminicli.com/docs/cli/custom-commands/), [Antigravity CLI skills](https://antigravity.google/docs/skills?app=cli), [Codex skills](https://learn.chatgpt.com/docs/build-skills).
|
package/docs/progress.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# 專案總覽 / Project dashboard
|
|
2
|
+
|
|
3
|
+
對 AI 說「開啟專案進度頁」,或啟用[快捷入口](commands.md)後使用 `/handoff-kit-progress`。Codex 使用 `$handoff-kit-progress` 或從 `/skills` 選取。這是每個已安裝 Kit 的專案共用的固定頁面,無須重新設計 HTML。
|
|
4
|
+
|
|
5
|
+
## 三個入口
|
|
6
|
+
|
|
7
|
+
- **總覽**:專案名稱、交接記錄的目前工作、各項工作狀態、待完成/等待/待驗收事項、成果及最近變更。「正在查看」只表示你選中的工作,不改變交接狀態。工作排列不表示先後順序,子項完成也不表示整項完成。
|
|
8
|
+
- **歷程**:近 7 日、近 30 日、自選日期、關鍵字及工作線篩選。日期標示年份,按封存索引逐批查閱歷史;日期不隱藏目前未完事項。
|
|
9
|
+
- **文件導覽**:核心關係圖顯示八種 Kit 文件角色;清單另列已登記的專案文件,並非專案所有檔案。點選節點突出相關文件與方向,查看用途、原文及來源,也可切換清單。沒有明確記錄的關係不靠 AI 猜補。
|
|
10
|
+
|
|
11
|
+
保存紀錄後自動更新,不需要刷新。點選主線、日期及文件時有短動畫;新資料短暫標示改變處,支援減少動畫設定。動畫不代表 AI 正在思考、已驗收或已完整接收交接。
|
|
12
|
+
|
|
13
|
+
品牌旁的版本讀取專案 `PROJECT_INDEX.md` 的 `Stack`,沿用 Kit 共用讀取方法;「資料依據」另列啟動頁面工具的套件版本。兩者不同會提示,缺失或格式無效則顯示「版本未核實」,不以工具版本代替專案版本。讀取不查網絡、不呼叫 AI,也不升級專案。
|
|
14
|
+
|
|
15
|
+
## 少量維護,不另寫報告
|
|
16
|
+
|
|
17
|
+
AI 在正常、已授權的保存時,維護 Index 的專案名稱/目標與 Handoff 的精簡工作表;只改有變的事項,不記錄每一步終端操作。兩份模板定義欄位格式,詳細證據保留在原有位置。尚無工作表項目的專案,直接顯示已有「下一步」及「風險與阻礙」,標明尚未分類,不猜測其狀態。首頁只顯示有界摘要;其餘項目數量與查看完整工作/交接原文的入口一併列出。缺失資訊保持未記錄,不捏造階段、百分比或完成數字。「交接保存」專指交接檔案保存時間,不代表整個專案最後有變更的時間。
|
|
18
|
+
|
|
19
|
+
介面支援繁中/英文。來源可選 `Name zh-Hant`、`Goal zh-Hant`、`Title zh-Hant`、`Summary zh-Hant`,缺少則保留原文;日誌也可在正常保存時加入簡短中文標題/摘要,不必回寫歷史翻譯。讀取、篩選、動畫及同步由程式處理,**不呼叫 AI、不要求第二份進度 JSON 或重複報告**。
|
|
20
|
+
|
|
21
|
+
## 啟動及環境
|
|
22
|
+
|
|
23
|
+
沿用 Kit 的 Node.js 與瀏覽器,不需要資料庫、Python、建置工具或 API key。
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
npx --yes @adamchanadam/agent-handoff-kit@latest progress --background --root <project-root>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`npx` 可能下載 CLI 至快取;未發佈版本使用選定的本機套件。`progress` 自身不查網絡版本、不安裝/升級、不寫回專案。`--background` 啟動或重用同專案、版本與頁面內容的背景服務,開啟瀏覽器後返回。`--no-open` 只給網址;`--port <0-65535>` 指定埠。不停止不相符的服務。
|
|
30
|
+
|
|
31
|
+
只綁定 `127.0.0.1`,拒絕跨網站請求及寫入。有頁面連線時持續運作;全部頁面斷線後保留 8 小時,未曾開啟亦保留 8 小時。無連線時停止輪詢紀錄,再次開啟立即讀取最新內容並延長保留時間。超時、電腦重啟或服務結束後,使用既有快捷入口便會重新啟動;舊網址不能自行啟動已停止的本機程式。前景模式可按 Ctrl+C 立即停止。
|
|
32
|
+
|
|
33
|
+
## 來源及邊界
|
|
34
|
+
|
|
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 |
|
|
42
|
+
|
|
43
|
+
自訂文件關係在 Index 的 `## Document Relations` 使用 `From | To | Relation`:已登記的相對路徑及 `references`、`routes`、`mirrors`、`checks`。只表達關係,不授權同步。只讀專案內登記文件,拒絕越界、隱藏設定、機密名稱及遷移內部檔;原文以純文字顯示,不執行 HTML 等內容。已知憑證模式會遮蔽,不代替來源的機密管理。
|
|
44
|
+
|
|
45
|
+
首頁與歷程共用同一日誌欄位讀取方式,支援逐行欄位、項目符號、粗體欄位名及縮排續行;中文標題與摘要在兩處一致使用。識別欄位不會被當成摘要。歷程只涵蓋索引登記批次。缺索引、格式錯誤、缺檔、未封口/過大條目、同 Event ID 內容衝突及超限都明示覆蓋不足。日誌可選 `Event ID` 用於搬移去重、`Work` 對應工作 ID;無 Event ID 則用原標題與內容辨識;原有 ID 是 agent/session 識別,可重複。單則上限 64 KiB;每查詢最多記住 10,000 事件,超過請收窄日期。最多 32 個分頁查詢,十五分鐘到期;來源改變即拒絕舊分頁。日期排序只涵蓋已載入結果。
|
|
46
|
+
|
|
47
|
+
有頁面連線時每半秒檢查狀態,無變動不重讀內容。斷線時保留已顯示資料,以 1、2、4、8、16、30 秒間隔重試,其後每 30 秒一次;回到頁面會提早重連,也可按「立即重連」。服務重啟後會更新歷程及詳情,保留日期、工作選擇及介面語言。失敗提示附可複製的重開口令。首頁不掃歷史;最近查過的 128 份封存檔會監看。文件地圖只檢查登記檔案的存在及時間。讀前/後核對身份與穩定性;無效來源保留上次有效畫面並告警,升級鎖存在即暫停。歷程自動更新每輪最多五個有界請求,更多可繼續查閱。
|
|
48
|
+
|
|
49
|
+
一般 Markdown 不是交易格式:結構完整的中間狀態不能永遠與最終意圖區分。來源完成聲稱不等於獨立驗收;總覽不代替 AI 全文接收交接包。
|
|
50
|
+
|
|
51
|
+
## English
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
60
|
+
|
|
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.
|
|
62
|
+
|
|
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.
|
|
64
|
+
|
|
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.
|
|
66
|
+
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
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": {
|