@sanqianx/project-knowledge 4.6.1 → 4.8.0

package/_modules/knowledge-engine/ui/app.js

@@ -0,0 +1,297 @@
+'use strict';
+
+const $ = selector => document.querySelector(selector);
+const $$ = selector => [...document.querySelectorAll(selector)];
+const viewMeta = {
+  overview: ['knowledge control plane', '知识脉搏'],
+  runs: ['generation pipeline', '生成流水线'],
+  knowledge: ['canonical knowledge', '知识状态'],
+  retrieval: ['retrieval verification', '检索验证'],
+  projects: ['integration diagnostics', '项目接线'],
+  events: ['immutable evidence stream', '事件流'],
+};
+let currentView = 'overview';
+let scopedProjectId = '';
+let toastTimer;
+let runPollTimer;
+let selectedRunId = null;
+let viewEpoch = 0;
+const embedParams = new URLSearchParams(location.search);
+const embedded = embedParams.get('embed') === '1';
+let embedVisible = !embedded;
+const apiBase = embedParams.get('apiBase') || '/api';
+const parentOrigin = document.referrer ? new URL(document.referrer).origin : location.origin;
+document.body.classList.toggle('kb-embedded', embedded);
+
+async function api(path, options = {}) {
+  const init = { headers: { 'Content-Type': 'application/json' }, ...options };
+  if (init.body && typeof init.body !== 'string') init.body = JSON.stringify(init.body);
+  const response = await fetch(path.replace(/^\/api(?=\/|$)/, apiBase), init);
+  const payload = await response.json().catch(() => ({ ok: false, error: 'BAD_JSON' }));
+  if (!response.ok || payload.ok === false) {
+    toast(payload.message || payload.error || `HTTP ${response.status}`);
+    throw new Error(payload.error || 'API_ERROR');
+  }
+  return payload;
+}
+
+function toast(message) {
+  $('#toast').textContent = message;
+  $('#toast').classList.add('show');
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => $('#toast').classList.remove('show'), 2600);
+}
+
+function escapeHtml(value) { return String(value ?? '').replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char])); }
+function fmtTime(iso) {
+  if (!iso) return '–';
+  const date = new Date(iso);
+  return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}:${String(date.getSeconds()).padStart(2, '0')}`;
+}
+function fmtDuration(ms) { return ms == null ? '–' : ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`; }
+function shortSha(sha) { return sha ? sha.slice(0, 7) : '–'; }
+function stateBadge(state) { return `<span class="badge ${escapeHtml(state)}">${escapeHtml(({ queued: '排队', running: '运行中', succeeded: '可检索', failed: '失败', 'index-pending': '索引待修复' })[state] || state)}</span>`; }
+function typeBadge(type) { return `<span class="badge type">${escapeHtml(type)}</span>`; }
+function scopedPath(path) { return scopedProjectId ? `${path}${path.includes('?') ? '&' : '?'}projectId=${encodeURIComponent(scopedProjectId)}` : path; }
+function successfulRun(runs) { return runs.find(run => run.promotedAt) || null; }
+
+function setView(view) {
+  currentView = view;
+  viewEpoch++;
+  const [kicker, title] = viewMeta[view];
+  $('#viewKicker').textContent = kicker;
+  $('#viewTitle').textContent = title;
+  $$('.nav-item').forEach(button => button.classList.toggle('on', button.dataset.view === view));
+  $$('.view').forEach(section => section.classList.toggle('on', section.id === `view-${view}`));
+  refreshView(view);
+}
+
+$$('.nav-item').forEach(button => button.addEventListener('click', () => setView(button.dataset.view)));
+$$('[data-goto]').forEach(button => button.addEventListener('click', () => setView(button.dataset.goto)));
+$('#scopeProject').addEventListener('change', () => { scopedProjectId = $('#scopeProject').value; selectedRunId = null; viewEpoch++; refreshView(currentView); });
+
+async function pollHealth() {
+  try {
+    const health = await api('/api/health');
+    document.body.classList.toggle('engine-debug', health.debug === true);
+    $('#healthDot').classList.add('up');
+    $('#healthText').textContent = `v${health.version} · 游标 ${health.journal.cursor}`;
+    return health;
+  } catch {
+    $('#healthDot').classList.remove('up');
+    $('#healthText').textContent = '服务离线';
+    return null;
+  }
+}
+
+async function loadProjectScope() {
+  const { projects } = await api('/api/projects');
+  const select = $('#scopeProject');
+  const previous = scopedProjectId || select.value;
+  select.innerHTML = '<option value="">全部项目</option>' + projects.map(project => `<option value="${escapeHtml(project.projectId)}">${escapeHtml(project.name)}</option>`).join('');
+  if ([...select.options].some(option => option.value === previous)) select.value = previous;
+  else { select.value = ''; scopedProjectId = ''; }
+  return projects;
+}
+
+async function refreshView(view) {
+  if (view === 'overview') loadOverview();
+  if (view === 'runs') { await loadProjectSelects(); loadRuns(); }
+  if (view === 'knowledge') loadKnowledge();
+  if (view === 'retrieval') loadProjectSelects();
+  if (view === 'projects') loadProjects();
+  if (view === 'events') loadEvents();
+}
+
+function setFlowState(id, className) {
+  const element = $(id);
+  element.classList.remove('is-active', 'is-done');
+  if (className) element.classList.add(className);
+}
+
+async function loadOverview() {
+  const epoch = viewEpoch;
+  const [health, projects, runPayload, eventPayload] = await Promise.all([
+    pollHealth(), loadProjectScope().catch(() => []), api(scopedPath('/api/runs')).catch(() => null), api('/api/events?limit=20').catch(() => null),
+  ]);
+  if (!health || !runPayload || epoch !== viewEpoch) return;
+  const runs = runPayload.runs;
+  const events = (eventPayload?.events || []).filter(event => !scopedProjectId || event.projectId === scopedProjectId);
+  const succeeded = runs.filter(run => run.promotedAt);
+  const failed = runs.filter(run => run.state === 'failed' || run.state === 'index-pending');
+  const running = runs.filter(run => run.state === 'queued' || run.state === 'running');
+  const latestSuccess = successfulRun(runs);
+  const latestEvent = events[0];
+  $('#statProjects').textContent = scopedProjectId ? '1' : projects.length;
+  $('#statProjectsDetail').textContent = scopedProjectId ? '当前选定项目' : '已登记的引擎接线';
+  $('#statRunning').textContent = running.length;
+  $('#statRunningDetail').textContent = running.length ? '正在推进生成链路' : '没有待处理运行';
+  $('#statSucceeded').textContent = succeeded.length;
+  $('#statSucceededDetail').textContent = latestSuccess ? `最近 ${shortSha(latestSuccess.commitSha)}` : '尚未晋升知识';
+  $('#statFailed').textContent = failed.length;
+  $('#statFailedDetail').textContent = failed.length ? '打开运行记录处理' : '没有失败运行';
+  setFlowState('#flowJournal', health.journal.enabled && !health.journal.error ? 'is-done' : '');
+  $('#flowJournalText').textContent = health.journal.error || (health.journal.enabled ? `${Object.keys(health.journal.cursors).length} 份日志正在消费` : '尚未移交自动维护所有权');
+  setFlowState('#flowReconcile', latestEvent ? 'is-done' : '');
+  $('#flowReconcileText').textContent = latestEvent ? `${latestEvent.type} · ${fmtTime(latestEvent.at)}` : '等待 commit boundary';
+  setFlowState('#flowAnalyze', running.length ? 'is-active' : latestSuccess ? 'is-done' : '');
+  $('#flowAnalyzeText').textContent = running.length ? `${running.length} 个运行正在分析` : latestSuccess ? `最近完成 ${shortSha(latestSuccess.commitSha)}` : '没有运行中的分析';
+  setFlowState('#flowPromote', latestSuccess ? 'is-done' : '');
+  $('#flowPromoteText').textContent = latestSuccess ? `${latestSuccess.staging?.operations?.length || 0} 项知识变更已晋升` : '尚未生成暂存产物';
+  setFlowState('#flowIndex', latestSuccess?.indexState === 'succeeded' ? 'is-done' : latestSuccess?.indexState === 'running' ? 'is-active' : '');
+  $('#flowIndexText').textContent = latestSuccess?.indexState === 'succeeded' ? '知识与派生索引一致' : latestSuccess ? '知识已更新，索引尚未完成' : '等待首次知识晋升';
+  $('#flowPhase').textContent = health.journal.enabled ? '日志消费已启用' : '自动维护待切换';
+  $('#overviewRuns').innerHTML = runs.slice(0, 6).map(run => `<tr class="click" data-open-run="${escapeHtml(run.runId)}"><td class="mono">${shortSha(run.commitSha)}</td><td>${escapeHtml(run.projectId)}</td><td>${stateBadge(run.state)}</td><td class="mono">${run.staging?.operations?.length || 0} 项</td><td class="mono">${fmtDuration(run.durationMs)}</td></tr>`).join('') || '<tr><td colspan="5" class="empty">暂无知识运行。</td></tr>';
+  $$('[data-open-run]').forEach(row => row.addEventListener('click', () => { selectedRunId = row.dataset.openRun; setView('runs'); }));
+  if (failed.length) {
+    $('#attentionTitle').textContent = `${failed.length} 个运行需要处理`;
+    $('#attentionBody').textContent = `最近异常 ${shortSha(failed[0].commitSha)}：${failed[0].error?.message || '未提供错误详情'}。`;
+  } else if (running.length) {
+    $('#attentionTitle').textContent = '知识正在生成';
+    $('#attentionBody').textContent = `${running.length} 个 commit 已被认领。打开流水线可查看当前阶段和暂存产物。`;
+  } else if (latestSuccess) {
+    $('#attentionTitle').textContent = '链路目前稳定';
+    $('#attentionBody').textContent = `最近已为 ${shortSha(latestSuccess.commitSha)} 晋升 ${latestSuccess.staging?.operations?.length || 0} 项知识变更。`;
+  } else {
+    $('#attentionTitle').textContent = '等待第一份知识证据';
+    $('#attentionBody').textContent = '引擎已就绪；提交 commit boundary 后，对账器会创建首个分析运行。';
+  }
+  $('#serviceInfo').innerHTML = `<div><dt>服务版本</dt><dd class="mono">${health.version}</dd></div><div><dt>服务 uptime</dt><dd class="mono">${Math.floor(health.uptimeSec / 60)}m ${health.uptimeSec % 60}s</dd></div><div><dt>事件消费者</dt><dd>${escapeHtml(health.journal.consumer)}</dd></div><div><dt>状态目录</dt><dd class="mono">${escapeHtml(health.dataDir)}</dd></div>`;
+}
+
+async function loadProjectSelects() {
+  const { projects } = await api('/api/projects');
+  const options = projects.map(project => `<option value="${escapeHtml(project.projectId)}">${escapeHtml(project.name)}</option>`).join('');
+  for (const select of [$('#triggerProject'), $('#retrievalProject'), $('#runProjectFilter')]) {
+    const previous = select.value;
+    const isFilter = select === $('#runProjectFilter');
+    select.innerHTML = (isFilter ? '<option value="">全部项目</option>' : '') + options;
+    const preferred = previous || (!isFilter ? scopedProjectId : '');
+    if ([...select.options].some(option => option.value === preferred)) select.value = preferred;
+  }
+}
+
+async function loadRuns() {
+  const epoch = viewEpoch;
+  const selectedProject = $('#runProjectFilter').value;
+  const selectedState = $('#runStateFilter').value;
+  const { runs } = await api(selectedProject ? `/api/runs?projectId=${encodeURIComponent(selectedProject)}` : scopedPath('/api/runs'));
+  if (epoch !== viewEpoch) return;
+  const visibleRuns = selectedState ? runs.filter(run => run.state === selectedState) : runs;
+  $('#runsBody').innerHTML = visibleRuns.map(run => `<tr class="click ${run.runId === selectedRunId ? 'sel' : ''}" data-run="${escapeHtml(run.runId)}"><td class="mono">${shortSha(run.commitSha)}</td><td>${escapeHtml(run.projectId)}</td><td class="mono">${escapeHtml(run.trigger)}</td><td>${stateBadge(run.state)}</td><td class="mono">${fmtTime(run.startedAt)}</td><td class="mono">${fmtDuration(run.durationMs)}</td></tr>`).join('') || '<tr><td colspan="6" class="empty">没有符合条件的运行。</td></tr>';
+  $$('[data-run]').forEach(row => row.addEventListener('click', () => { selectedRunId = row.dataset.run; showRunDetail(selectedRunId); loadRuns(); }));
+  if (selectedRunId) showRunDetail(selectedRunId).catch(() => {});
+  clearTimeout(runPollTimer);
+  if (embedVisible && runs.some(run => run.state === 'queued' || run.state === 'running') && currentView === 'runs') runPollTimer = setTimeout(loadRuns, 800);
+}
+
+function runTimeline(run) {
+  const stages = ['排队', '冻结证据', '分析会话', '校验晋升', '更新索引', '可检索'];
+  const activeIndex = ({ queued: 0, recovering: 1, preparing: 1, analyzing: 2, promoting: 3, promoted: 4, indexing: 4, 'index-pending': 4, ready: 6 })[run.phase] ?? 2;
+  return stages.map((stage, index) => `<li class="${['failed', 'index-pending'].includes(run.state) && index === activeIndex ? 'failed' : index < activeIndex ? 'done' : index === activeIndex ? 'current' : ''}">${stage}</li>`).join('');
+}
+
+async function showRunDetail(runId) {
+  const { run } = await api(`/api/runs/${encodeURIComponent(runId)}`);
+  if (runId !== selectedRunId || (scopedProjectId && run.projectId !== scopedProjectId)) return;
+  $('#runDetail').classList.remove('hidden');
+  $('#runDetailId').textContent = run.runId;
+  $('#runTimeline').innerHTML = runTimeline(run);
+  $('#runMeta').innerHTML = `<div><dt>状态</dt><dd>${stateBadge(run.state)}</dd></div><div><dt>项目 / commit</dt><dd>${escapeHtml(run.projectId)} · <span class="mono">${shortSha(run.commitSha)}</span></dd></div><div><dt>触发入口</dt><dd class="mono">${escapeHtml(run.trigger)}</dd></div><div><dt>错误</dt><dd>${run.error ? escapeHtml(run.error.message) : '–'}</dd></div>${run.error?.retryable ? '<div><dt>恢复</dt><dd><button class="btn" id="retryRun">重试失败阶段</button></dd></div>' : ''}`;
+  $('#retryRun')?.addEventListener('click', async () => { await api(`/api/runs/${encodeURIComponent(runId)}/retry`, { method: 'POST' }); loadRuns(); });
+  $('#runStaging').textContent = run.staging ? JSON.stringify(run.staging, null, 2) : '该运行没有 staging 产物。';
+}
+
+$('#runProjectFilter').addEventListener('change', loadRuns);
+$('#runStateFilter').addEventListener('change', loadRuns);
+$('#btnShowTrigger').addEventListener('click', async () => { $('#triggerForm').classList.toggle('hidden'); if (!$('#triggerForm').classList.contains('hidden')) await loadProjectSelects(); });
+$('#btnCancelTrigger').addEventListener('click', () => $('#triggerForm').classList.add('hidden'));
+$('#triggerForm').addEventListener('submit', async event => {
+  event.preventDefault();
+  const data = Object.fromEntries(new FormData(event.target));
+  data.simulateFailure = event.target.simulateFailure.checked;
+  await api('/api/runs', { method: 'POST', body: data });
+  event.target.reset(); $('#triggerForm').classList.add('hidden'); toast('已加入真实维护队列。'); loadRuns();
+});
+
+async function loadKnowledge() {
+  const epoch = viewEpoch;
+  const [projects, payload] = await Promise.all([api('/api/projects'), api(scopedPath('/api/runs'))]);
+  if (epoch !== viewEpoch) return;
+  const project = scopedProjectId ? projects.projects.find(item => item.projectId === scopedProjectId) : projects.projects[0];
+  const runs = scopedProjectId ? payload.runs : payload.runs.filter(run => !project || run.projectId === project.projectId);
+  const latest = successfulRun(runs);
+  $('#knowledgeProjectName').textContent = project ? project.name : '尚未登记项目';
+  $('#knowledgePath').textContent = project?.knowledgePath || '等待 project-knowledge-base 外壳投递 knowledgePath';
+  $('#knowledgeLastCommit').textContent = latest ? shortSha(latest.commitSha) : '–';
+  $('#knowledgeLastAt').textContent = latest ? `${fmtTime(latest.promotedAt)} · ${latest.staging?.operations?.length || 0} 项已晋升` : '尚无晋升记录';
+  $('#knowledgeIndexState').textContent = latest?.indexState === 'succeeded' ? '可检索' : latest ? '待同步' : '等待运行';
+  const operations = latest?.staging?.operations || [];
+  $('#knowledgeOperationCount').textContent = `${operations.length} 项`;
+  $('#knowledgeOperations').innerHTML = operations.map(operation => `<article class="knowledge-operation"><span class="operation-kind">${escapeHtml(operation.operation)}</span><div><strong>${escapeHtml(operation.path)}</strong><small>${escapeHtml(operation.reason)}</small></div><em>${escapeHtml(operation.evidenceReferences?.[0] || '无证据')}</em></article>`).join('') || '<p class="empty">成功运行后，暂存清单会在这里展示知识树将受到的影响。</p>';
+}
+
+async function loadProjects() {
+  const { projects } = await api('/api/projects');
+  $('#projectsBody').innerHTML = projects.map(project => `<tr><td><strong>${escapeHtml(project.name)}</strong><br><span class="mono">${escapeHtml(project.projectId)}</span></td><td class="mono wrap">${escapeHtml(project.repoPath || '–')}</td><td class="mono wrap">${escapeHtml(project.knowledgePath || '–')}</td><td class="mono">${shortSha(project.lastCommitSha)}</td><td><button class="btn danger" data-del="${escapeHtml(project.projectId)}">摘除接线</button></td></tr>`).join('') || '<tr><td colspan="5" class="empty">尚无来自外壳的项目接线。</td></tr>';
+  $$('[data-del]').forEach(button => button.addEventListener('click', async () => {
+    if (!confirm(`摘除项目 ${button.dataset.del} 的引擎接线？知识树与运行历史会保留。`)) return;
+    await api(`/api/projects/${encodeURIComponent(button.dataset.del)}`, { method: 'DELETE' });
+    if (scopedProjectId === button.dataset.del) scopedProjectId = '';
+    loadProjects();
+  }));
+}
+
+$('#btnShowRegister').addEventListener('click', () => $('#registerForm').classList.toggle('hidden'));
+$('#btnCancelRegister').addEventListener('click', () => $('#registerForm').classList.add('hidden'));
+$('#registerForm').addEventListener('submit', async event => {
+  event.preventDefault();
+  await api('/api/projects', { method: 'POST', body: Object.fromEntries(new FormData(event.target)) });
+  event.target.reset(); $('#registerForm').classList.add('hidden'); loadProjects();
+});
+
+$('#btnSearch').addEventListener('click', async () => {
+  const projectId = $('#retrievalProject').value;
+  const query = $('#retrievalQuery').value.trim();
+  if (!projectId || !query) return toast('先选择项目并输入查询。');
+  const { results } = await api('/api/search', { method: 'POST', body: { projectId, query, limit: Number($('#retrievalLimit').value) || 5 } });
+  $('#searchBody').innerHTML = results.map(hit => `<tr><td class="mono">${escapeHtml(hit.path)}</td><td>${escapeHtml(hit.title)}</td><td class="score">${hit.score}</td><td class="wrap">${escapeHtml(hit.snippet)}</td></tr>`).join('') || '<tr><td colspan="4" class="empty">没有命中的知识文档。</td></tr>';
+});
+$('#btnAsk').addEventListener('click', async () => {
+  const projectId = $('#retrievalProject').value;
+  const query = $('#retrievalQuery').value.trim();
+  if (!projectId || !query) return toast('先选择项目并输入查询。');
+  const result = await api('/api/ask', { method: 'POST', body: { projectId, query } });
+  $('#askPanel').classList.remove('hidden');
+  $('#askAnswer').textContent = result.answer;
+  $('#askCitations').innerHTML = result.citations.map(citation => `<li><span class="mono">${escapeHtml(citation.path)}</span> · ${escapeHtml(citation.title)} · <span class="score">${citation.score}</span></li>`).join('') || '<li>无引用</li>';
+});
+
+async function loadEvents() {
+  const { events } = await api('/api/events?limit=100');
+  const visible = events.filter(event => !scopedProjectId || event.projectId === scopedProjectId);
+  $('#eventCursor').textContent = `游标 ${events[0]?.seq || 0}`;
+  $('#eventsBody').innerHTML = visible.map(event => `<tr><td class="mono">${event.seq}</td><td>${typeBadge(event.type)}</td><td>${escapeHtml(event.projectId || '–')}</td><td class="wrap">${escapeHtml(event.summary)}</td><td class="mono">${fmtTime(event.at)}</td></tr>`).join('') || '<tr><td colspan="5" class="empty">暂无事件。</td></tr>';
+}
+$('#btnInjectEvent').addEventListener('click', async () => { await api('/api/events', { method: 'POST', body: { type: 'commit-boundary', projectId: scopedProjectId || null, summary: '手动注入的测试事件' } }); loadEvents(); });
+
+window.addEventListener('message', async event => {
+  if (!embedded || event.source !== parent || event.origin !== parentOrigin || !event.data) return;
+  const message = event.data;
+  if (message.type === 'kb:theme') document.body.dataset.kbTheme = message.theme === 'dark' ? 'dark' : 'light';
+  if (message.type === 'kb:visibility') {
+    embedVisible = message.visible === true;
+    clearTimeout(runPollTimer);
+    if (embedVisible) refreshView(currentView);
+  }
+  if (message.type === 'kb:select-project') {
+    scopedProjectId = message.projectId || ''; selectedRunId = null; viewEpoch++;
+    await loadProjectScope(); await refreshView(currentView);
+    parent.postMessage({ type: 'kb:project-selected', projectId: scopedProjectId, requestId: message.requestId }, parentOrigin);
+  }
+  if (message.type === 'kb:refresh') refreshView(currentView);
+});
+if (embedded) { document.body.dataset.kbTheme = 'light'; parent.postMessage({ type: 'kb:ready', module: 'engine' }, parentOrigin); }
+pollHealth();
+loadOverview();
+setInterval(() => { if (embedVisible && currentView === 'overview') loadOverview(); }, 5000);

package/_modules/knowledge-engine/ui/index.html

@@ -0,0 +1,95 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>knowledge-engine · 知识生命周期控制台</title>
+<link rel="stylesheet" href="./app.css">
+</head>
+<body>
+<div id="app">
+  <aside>
+    <div class="brand">
+      <div class="mark">KE</div>
+      <div class="brand-copy"><strong>knowledge-engine</strong><span>知识生命周期控制台</span></div>
+    </div>
+    <nav class="nav" aria-label="知识引擎导航">
+      <p class="nav-label">运行</p>
+      <button class="nav-item on" data-view="overview"><span class="nav-symbol">◎</span>知识脉搏</button>
+      <button class="nav-item" data-view="runs"><span class="nav-symbol">↳</span>生成流水线</button>
+      <button class="nav-item" data-view="knowledge"><span class="nav-symbol">□</span>知识状态</button>
+      <button class="nav-item" data-view="retrieval"><span class="nav-symbol">⌕</span>检索验证</button>
+      <p class="nav-label nav-label-lower">调试</p>
+      <button class="nav-item" data-view="projects"><span class="nav-symbol">↔</span>项目接线</button>
+      <button class="nav-item" data-view="events"><span class="nav-symbol">≋</span>事件流</button>
+    </nav>
+    <div class="side-foot"><span class="dot" id="healthDot"></span><span id="healthText">连接中…</span></div>
+  </aside>
+
+  <main>
+    <header class="topbar">
+      <div><p class="eyebrow" id="viewKicker">knowledge control plane</p><h1 id="viewTitle">知识脉搏</h1></div>
+      <label class="scope-control">范围<select id="scopeProject"><option value="">全部项目</option></select></label>
+    </header>
+
+    <section id="view-overview" class="view on">
+      <div class="view-intro"><p>从 commit 证据到可引用知识：这里看见每一段链路是否连续，而不是只看一串运行日志。</p><button class="btn primary" data-goto="runs">查看生成流水线</button></div>
+      <section class="flow-panel" aria-labelledby="flowTitle">
+        <div class="panel-heading"><div><p class="section-kicker">当前知识流</p><h2 id="flowTitle">证据正在如何成为知识</h2></div><span class="phase-pill" id="flowPhase">正在读取运行状态</span></div>
+        <ol class="flow-track">
+          <li class="flow-step" id="flowJournal"><span class="flow-number">01</span><div><strong>事件入站</strong><small id="flowJournalText">journal 等待连接</small></div></li>
+          <li class="flow-step" id="flowReconcile"><span class="flow-number">02</span><div><strong>提交对账</strong><small id="flowReconcileText">等待 commit boundary</small></div></li>
+          <li class="flow-step" id="flowAnalyze"><span class="flow-number">03</span><div><strong>证据分析</strong><small id="flowAnalyzeText">没有运行中的分析</small></div></li>
+          <li class="flow-step" id="flowPromote"><span class="flow-number">04</span><div><strong>校验与晋升</strong><small id="flowPromoteText">尚未生成暂存产物</small></div></li>
+          <li class="flow-step is-pending" id="flowIndex"><span class="flow-number">05</span><div><strong>检索就绪</strong><small id="flowIndexText">等待接入 vector-hub</small></div></li>
+        </ol>
+      </section>
+      <div class="metric-grid">
+        <article class="metric"><span>本范围项目</span><strong id="statProjects">–</strong><small id="statProjectsDetail">等待服务响应</small></article>
+        <article class="metric"><span>进行中</span><strong id="statRunning">–</strong><small id="statRunningDetail">队列与分析会话</small></article>
+        <article class="metric"><span>已晋升</span><strong id="statSucceeded">–</strong><small id="statSucceededDetail">成功完成的知识运行</small></article>
+        <article class="metric metric-warn"><span>需要处理</span><strong id="statFailed">–</strong><small id="statFailedDetail">失败或中断的运行</small></article>
+      </div>
+      <div class="overview-grid">
+        <section class="panel run-panel"><div class="panel-heading"><div><p class="section-kicker">运行记录</p><h2>最近知识变更</h2></div><button class="quiet-link" data-goto="runs">全部运行 →</button></div><div class="table-wrap"><table><thead><tr><th>commit</th><th>项目</th><th>状态</th><th>产物</th><th>耗时</th></tr></thead><tbody id="overviewRuns"></tbody></table></div></section>
+        <section class="panel attention-panel"><div class="panel-heading"><div><p class="section-kicker">可操作项</p><h2 id="attentionTitle">正在检查链路</h2></div></div><p class="attention-body" id="attentionBody">正在读取运行、事件和服务健康状态。</p><dl class="service-list" id="serviceInfo"></dl></section>
+      </div>
+    </section>
+
+    <section id="view-runs" class="view">
+      <div class="view-intro compact"><p>查看提交证据、分析进度、知识晋升与索引结果。提交由事件入口自动进入维护队列。</p><button class="btn debug-only" id="btnShowTrigger">手动维护</button></div>
+      <div class="toolbar filters"><select id="runProjectFilter"><option value="">全部项目</option></select><select id="runStateFilter"><option value="">全部状态</option><option value="queued">排队</option><option value="running">运行中</option><option value="succeeded">可检索</option><option value="index-pending">索引待修复</option><option value="failed">失败</option></select></div>
+      <form id="triggerForm" class="panel form hidden"><div class="panel-heading"><div><p class="section-kicker">维护诊断</p><h2>分析一次真实提交</h2></div></div><div class="form-row"><label>项目<select name="projectId" id="triggerProject" required></select></label><label>commit SHA<input name="commitSha" placeholder="输入仓库中的真实提交 SHA" pattern="[a-fA-F0-9]{7,64}" required></label></div><label class="checkbox debug-only"><input type="checkbox" name="simulateFailure"> 模拟失败态（调试模式）</label><div class="form-actions"><button type="submit" class="btn primary">开始维护</button><button type="button" class="btn" id="btnCancelTrigger">取消</button></div></form>
+      <section class="panel"><div class="table-wrap"><table><thead><tr><th>commit</th><th>项目</th><th>入口</th><th>状态</th><th>开始</th><th>耗时</th></tr></thead><tbody id="runsBody"></tbody></table></div></section>
+      <section class="panel hidden" id="runDetail"><div class="panel-heading"><div><p class="section-kicker">运行追溯</p><h2>运行 <span class="mono" id="runDetailId"></span></h2></div></div><ol class="run-timeline" id="runTimeline" aria-label="运行状态时间线"></ol><div class="detail-grid"><dl class="kv" id="runMeta"></dl><div><p class="panel-sub">staging manifest</p><pre class="code" id="runStaging">该运行没有 staging 产物。</pre></div></div></section>
+    </section>
+
+    <section id="view-knowledge" class="view">
+      <div class="view-intro compact"><p>知识树是唯一事实源；引擎只记录其生成证据、晋升结果与派生索引的同步状态。</p><button class="btn" data-goto="retrieval">验证检索</button></div>
+      <div class="knowledge-hero panel"><div><p class="section-kicker">知识树</p><h2 id="knowledgeProjectName">选择一个项目</h2><p class="mono knowledge-path" id="knowledgePath">–</p></div><div class="knowledge-summary"><span>最近晋升</span><strong id="knowledgeLastCommit">–</strong><small id="knowledgeLastAt">尚无成功运行</small></div></div>
+      <div class="overview-grid knowledge-grid"><section class="panel"><div class="panel-heading"><div><p class="section-kicker">本次知识影响</p><h2>已晋升变更清单</h2></div><span class="phase-pill" id="knowledgeOperationCount">0 项</span></div><div class="knowledge-list" id="knowledgeOperations"></div></section><section class="panel"><div class="panel-heading"><div><p class="section-kicker">可用性</p><h2>派生能力状态</h2></div></div><div class="readiness-list"><div><span class="readiness-dot is-ok"></span><p><strong>规范知识树</strong><small>由晋升路径单写；检索只读。</small></p><b>事实源</b></div><div><span class="readiness-dot is-ok"></span><p><strong>文件检索</strong><small>读取现存知识文件；向量离线时降级，不返回过期文件。</small></p><b>已接入</b></div><div><span class="readiness-dot is-pending"></span><p><strong>vector-hub 索引</strong><small>从知识树派生，可重建，不反向写入。</small></p><b id="knowledgeIndexState">等待运行</b></div></div></section></div>
+    </section>
+
+    <section id="view-retrieval" class="view">
+      <div class="view-intro compact"><p>验证开发 agent 实际获得的上下文：命中来源、得分、摘要和可追溯引用应在同一处可见。</p></div>
+      <div class="panel form retrieval-form"><div class="form-row"><label>项目<select id="retrievalProject"></select></label><label class="grow">查询<input id="retrievalQuery" placeholder="例如：commit 之后分析是怎么触发的"></label><label>limit<input id="retrievalLimit" type="number" value="5" min="1" max="30" class="w70"></label></div><div class="form-actions"><button class="btn primary" id="btnSearch">search</button><button class="btn" id="btnAsk">ask</button></div></div>
+      <section class="panel hidden" id="askPanel"><div class="panel-heading"><div><p class="section-kicker">带引用回答</p><h2>ask 结果</h2></div><span class="phase-pill">确定性拼接</span></div><div class="answer" id="askAnswer"></div><p class="panel-sub">引用</p><ol class="citations" id="askCitations"></ol></section>
+      <section class="panel"><div class="panel-heading"><div><p class="section-kicker">检索证据</p><h2>search 命中</h2></div></div><div class="table-wrap"><table><thead><tr><th>路径</th><th>标题</th><th>得分</th><th>摘要</th></tr></thead><tbody id="searchBody"><tr><td colspan="4" class="empty">输入查询后执行 search。</td></tr></tbody></table></div></section>
+    </section>
+
+    <section id="view-projects" class="view">
+      <div class="view-intro compact"><p>项目主档、设置和密钥属于 <span class="mono">project-knowledge-base</span> 外壳。本页只用于核对其向引擎投递的运行接线。</p><button class="btn" id="btnShowRegister">调试注册</button></div>
+      <form id="registerForm" class="panel form hidden"><div class="panel-heading"><div><p class="section-kicker">维护诊断</p><h2>登记真实目录绑定</h2></div></div><div class="form-row"><label>项目ID<input name="projectId" placeholder="my-project" required></label><label>名称<input name="name" placeholder="显示名"></label></div><div class="form-row"><label>仓库路径<input name="repoPath" placeholder="D:\path\to\repo" required></label><label>知识库路径<input name="knowledgePath" placeholder="D:\path\to\knowledge" required></label></div><div class="form-actions"><button type="submit" class="btn primary">登记</button><button type="button" class="btn" id="btnCancelRegister">取消</button></div></form>
+      <section class="panel"><div class="table-wrap"><table><thead><tr><th>项目</th><th>仓库</th><th>知识树</th><th>最近 commit</th><th>接线</th></tr></thead><tbody id="projectsBody"></tbody></table></div></section>
+    </section>
+
+    <section id="view-events" class="view">
+      <div class="view-intro compact"><p>event-bridge 是唯一入口。引擎先持久化证据与任务，再推进各项目的消费游标；封存提交不代表消费者已经读取。</p><button class="btn debug-only" id="btnInjectEvent">注入测试事件</button></div>
+      <section class="panel"><div class="panel-heading"><div><p class="section-kicker">原始事实</p><h2>事件流</h2></div><span class="phase-pill" id="eventCursor">游标 –</span></div><div class="table-wrap"><table><thead><tr><th>seq</th><th>类型</th><th>项目</th><th>摘要</th><th>时间</th></tr></thead><tbody id="eventsBody"></tbody></table></div></section>
+    </section>
+  </main>
+</div>
+<div id="toast" role="status" aria-live="polite"></div>
+<script src="./app.js"></script>
+</body>
+</html>

package/_site/README.md

@@ -1,30 +1,30 @@
-# KB Management Site
-
-本地知识库管理界面，默认监听 `http://127.0.0.1:5757`。
-
-## 启动
-
-```bash
-node _site/server.js
-```
-
-也可以运行项目根目录的 `npm start`，或使用 `_site/start.bat`。
-
-## Commit 自动化
-
-- Git `post-commit` Hook 在应用运行时立即通知服务端。
-- 应用启动时会扫描关闭期间新增的 commit。
-- 每个 commit 生成一个独立 Claude Code 后台任务。
-- 同一项目按提交时间串行执行，不同项目可以并行。
-- 任务直接更新当前项目知识库，没有草稿审核、`autoApply` 或人工批准阶段。
-- 每个 commit 的 `discovered / queued / running / completed / failed` 状态持久化在项目 AI 工作目录中，完成的 commit 不会重复派发。
-
-## 主要接口
-
-- `GET /api/state`：项目与知识库状态。
-- `POST /api/hooks/post-commit`：接收 Hook 事件并执行 commit 对账。
-- `POST /api/projects/:slug/scan`：只读扫描 Git 状态。
-- `GET /api/projects/:slug/automation/runs`：查看自动化运行记录。
-- `GET /api/claude/sessions-stream`：订阅 Claude Code 会话状态。
-
-服务只绑定回环地址。不要将端口直接暴露到公网。
+# KB Management Site
+
+本地知识库管理界面，默认监听 `http://127.0.0.1:5757`。
+
+## 启动
+
+```bash
+node _site/server.js
+```
+
+也可以运行项目根目录的 `npm start`，或使用 `_site/start.bat`。
+
+## Commit 自动化
+
+- Git `post-commit` Hook 在应用运行时立即通知服务端。
+- 应用启动时会扫描关闭期间新增的 commit。
+- 每个 commit 生成一个独立 Claude Code 后台任务。
+- 同一项目按提交时间串行执行，不同项目可以并行。
+- 任务直接更新当前项目知识库，没有草稿审核、`autoApply` 或人工批准阶段。
+- 每个 commit 的 `discovered / queued / running / completed / failed` 状态持久化在项目 AI 工作目录中，完成的 commit 不会重复派发。
+
+## 主要接口
+
+- `GET /api/state`：项目与知识库状态。
+- `POST /api/hooks/post-commit`：接收 Hook 事件并执行 commit 对账。
+- `POST /api/projects/:slug/scan`：只读扫描 Git 状态。
+- `GET /api/projects/:slug/automation/runs`：查看自动化运行记录。
+- `GET /api/claude/sessions-stream`：订阅 Claude Code 会话状态。
+
+服务只绑定回环地址。不要将端口直接暴露到公网。