@sanqianx/claude-ai-workbench 0.13.2-rc.13 → 0.13.2-rc.14

package/README.md

@@ -10,11 +10,17 @@
 
 重复收到当前项目的嵌入通知不会取消正在创建的会话；真正切换项目时仍隔离迟到的响应和草稿。项目查找尚未完成时，以最新的选择为准。
 
+Agent 发现为异步扫描，最多两个并发、每项 5 秒、整轮 12 秒；`GET /agents` 立即返回缓存及 `scan` 状态、代次和更新时间，`POST /agents/refresh` 强制发起或合并后台扫描并立即返回 202。不确定的超时保留上次探测结果，不误报卸载。界面先绑定控件再独立读取数据，手动重扫、页面重新可见和联网恢复可合并刷新；`kb:visibility` / `kb:refresh` 回执为 `kb:refreshed`，不重载 iframe、不清空草稿或运行会话。嵌入时可用 `transport=live` 选择同源外壳注入的 EventSource 兼容传输；独立运行保留原 SSE。
+
 受信任本地外壳通过 `KB_WORKBENCH_RUNTIME_TOKEN`、`KB_EVENT_BRIDGE_URL` 和引擎地址连接后台服务。原生工作台捕获原始用户输入及成功最终回答，通过持久化 outbox 投递到 bridge 的鉴权入口；不捕获系统提示词、注入的知识、工具输出或供应商凭据。`/api/health` 中 `conversationCapture` 展示启用状态、待投递数和错误；已有用户显式关闭的捕获设置不会被覆盖。桥接不可用时保留待投递记录，恢复或重启后继续，不伪造会话。
 
 工作台是产品供应商与凭据的活动配置源。后台维护默认模型持久化，不随会话临时模型切换；解析后的凭据只交给鉴权本地服务，不进入浏览器消息。SDK 会话从当前项目登记的工作区恢复，也兼容旧登记文件。
 
-四客户端的会话历史使用同目录临时文件原子替换。磁盘写满、临时写入失败或 Windows 拒绝替换时保留上一次完整记录，不截断或删除原历史；空间恢复后新会话仍可正常持久化。已经被旧版截断的历史不能凭空恢复。
+四客户端的运行快照使用同目录临时文件原子替换；5000 条实时事件只用于短期回放，不再作为完整会话历史。Workbench 在自己的数据目录 `session-history/` 中独立追加保存历史，并合并连续文字增量；页面先读取近期 20 轮，向上翻阅或点击“加载更早记录”时按轮分页，补入记录与断线恢复均保持阅读位置。浏览器关闭不停止历史采集。磁盘写入失败或记录损坏时保留已有数据，在页面明确提示不完整并写入本地诊断，实时对话不因此中断。
+
+旧版已截断的 Claude 会话在原始 CLI 记录仍完整且会话空闲时，可只读恢复用户问答与工具过程，包括沿上下文压缩的逻辑父节点恢复早期记录；不修改原始文件、不调用模型。原始记录不存在、损坏或链路不完整时，只展示实际保存的部分并明确提示，不能凭空补造历史。新历史接口为 `GET /sessions/{sessionId}/history?limit=20&before=<cursor>`，Client SDK 对应 `loadHistory()`；现有快照与 SSE 游标保持兼容。
+
+持续输出时，向上的滚轮或翻页键立即停止自动跟随；发送请求的迟到回执不会重新拉回底部。向下滚回底部或点击“回到底部”后恢复跟随，无需切换会话。
 
 MiniMax 向量模型使用独立的 `/v1/embeddings` 接口，不复用聊天的 `/anthropic` 路由。官方域名的已知接口后缀在运行期规范化为服务根地址，现有配置文件不被迁移或改写；自定义网关路径保持原样。
 

package/apps/agent-terminal/app.css

@@ -147,6 +147,10 @@ body.light .top-strip .st { color:#2f5fd0; }
 
 /* ===== 消息流(ZCode 风格:过程折叠,正文直出)===== */
 .stream { flex:1; overflow-y:auto; padding:8px 24px 24px; }
+.stream:focus { outline:none; }
+.history-bar { max-width:860px; margin:0 auto 16px; display:flex; align-items:center; justify-content:center; gap:8px; color:var(--muted); font-size:12px; }
+.history-bar[hidden], .history-bar [hidden] { display:none; }
+.history-bar button:disabled { opacity:.6; cursor:wait; }
 .col { max-width:860px; margin:0 auto; }
 .empty-hint { text-align:center; color:var(--muted); margin-top:18vh; font-size:13px; line-height:1.7; }
 .empty-hint .big { display:flex; align-items:center; justify-content:center; margin-bottom:12px; }

package/apps/agent-terminal/app.js

@@ -14,6 +14,7 @@ let selectionEpoch = 0;
 let sessionEpoch = 0;
 let sessionCreationEpoch = 0;
 let pendingEmbedSelection = null;
+let historyView = null;
 const projectDrafts = new Map();
 function savedProjectDraft(projectId, text) {
   try {
@@ -51,8 +52,12 @@ function forgetSessionSelection(sessionId) {
   }
 }
 
+function embeddedTransport() {
+  try { if (embedded && embedParams.get('transport') === 'live' && window.parent.location.origin === location.origin && window.parent.KnowledgeLive) return { EventSource: window.parent.KnowledgeLive.EventSource }; } catch { /* Cross-origin hosts retain standalone SSE. */ }
+  return {};
+}
 const client = window.createClaudeWorkbenchClient
-  ? window.createClaudeWorkbenchClient({ apiBase })
+  ? window.createClaudeWorkbenchClient({ apiBase, ...embeddedTransport() })
   : null;
 
 const PERMISSION_LABELS = { default: '默认防护', acceptEdits: '接受编辑', plan: '计划模式', bypassPermissions: '完全访问' };
@@ -61,6 +66,8 @@ const AGENT_LABELS = { 'claude-code': 'Claude Code', codex: 'Codex', opencode: '
 
 const state = {
   agents: [],
+  agentsScan: { state: 'idle' },
+  agentsError: false,
   projects: [],
   profiles: [],
   profilesStatus: 'idle', // idle | loading | ready | error (error keeps the last good list)
@@ -78,6 +85,7 @@ const state = {
   attachments: [],
   busy: false,
   follow: true, // auto-scroll sticks to bottom until the user scrolls away
+  scrollIntent: null,
   replaying: false, // true while replaying a session snapshot: no live timers/durations
   expanded: new Set(),
   caps: null,
@@ -128,7 +136,7 @@ function applyPreferences(values) {
 
 async function loadPreferences() {
   try {
-    const response = await fetch(`${apiBase}/ui-preferences`);
+    const response = await fetch(`${apiBase}/ui-preferences`, { signal: AbortSignal.timeout(3000) });
     if (!response.ok) return;
     const body = await response.json();
     savedPreferences = { ...(body && body.values || {}) };
@@ -154,14 +162,6 @@ function savePreferences(partial) {
 /* ===================== init ===================== */
 
 async function init() {
-  try {
-    const health = await client.health();
-    $('app-version').textContent = `v${health.version}`;
-    $('about-text').textContent = `Agent Terminal v${health.version} · API ${health.apiVersion} · ${health.sessions} 个会话`;
-  } catch { /* server unreachable is surfaced by the panels themselves */ }
-  await Promise.all([refreshAgents(), refreshProfiles()]);
-  await loadPreferences();
-  await refreshProjects();
   wireChrome();
   wireComposer();
   wireSettings();
@@ -169,6 +169,13 @@ async function init() {
   $('view-terminal').inert = false;
   $('view-terminal').setAttribute('aria-busy', 'false');
   $('view-settings').inert = false;
+  const healthJob = client.health().then(health => {
+    $('app-version').textContent = `v${health.version}`;
+    $('about-text').textContent = `Agent Terminal v${health.version} · API ${health.apiVersion} · ${health.sessions} 个会话`;
+  }).catch(() => {});
+  const preferences = loadPreferences();
+  const projects = preferences.then(() => refreshProjects()).catch(error => toast(`项目读取失败：${error.message}`, true));
+  await Promise.allSettled([healthJob, refreshAgents(), refreshProfiles(), projects]);
   if (!state.activeSessionId) $('session-title').textContent = '选择或创建一个会话';
   // Ready is the usable-page boundary: the host may immediately select a
   // project or open settings, so data and handlers must both be available.
@@ -177,11 +184,21 @@ async function init() {
 
 /* ===================== agents & capabilities ===================== */
 
-async function refreshAgents() {
-  try { state.agents = await client.listAgents(); } catch { state.agents = []; }
+let agentsRefreshJob = null, agentsPollTimer = null;
+function refreshAgents(force = false) {
+  if (agentsRefreshJob) return force ? agentsRefreshJob.then(() => refreshAgents(true)) : agentsRefreshJob;
+  agentsRefreshJob = (async () => {
+  try {
+    const result = force && client.refreshAgents ? await client.refreshAgents() : client.agentStatus ? await client.agentStatus() : { agents: await client.listAgents() };
+    state.agents = result.agents || []; state.agentsScan = result.scan || { state: 'ready' }; state.agentsError = false;
+  } catch { state.agentsError = true; }
   renderAgentSummary();
   renderAgentCards();
   applyCapabilityGates();
+  clearTimeout(agentsPollTimer);
+  if (state.agentsScan.state === 'scanning') agentsPollTimer = setTimeout(() => refreshAgents(), 500);
+  })().finally(() => { agentsRefreshJob = null; });
+  return agentsRefreshJob;
 }
 
 function renderAgentSummary() {
@@ -191,7 +208,8 @@ function renderAgentSummary() {
   dot.style.background = available.length ? 'var(--good)' : 'var(--bad)';
   $('agent-summary').textContent = available.length
     ? `已发现 ${available.length} 个 Agent:${available.map(a => a.label).join(' · ')}`
-    : '未发现可用 Agent';
+    : state.agentsScan.state === 'scanning' ? '正在检查 Agent…' : state.agentsError ? 'Agent 状态读取失败，请重试' : '未发现可用 Agent';
+  if (available.length && (state.agentsError || state.agentsScan.state === 'scanning')) $('agent-summary').textContent += state.agentsError ? ' · 刷新失败，显示上次结果' : ' · 正在检查';
 }
 
 function renderAgentCards() {
@@ -203,7 +221,7 @@ function renderAgentCards() {
     const body = el('div', 'a-body');
     const name = el('div', 'a-name');
     name.append(el('span', null, agent.label));
-    const chip = el('span', 'chip ' + (agent.available ? 'good' : ''), agent.available ? (agent.version ? `v${agent.version}` : '可用') : '不可用');
+    const chip = el('span', 'chip ' + (agent.available ? 'good' : ''), agent.scanState === 'unknown' ? '待检查' : agent.scanState === 'error' ? '检查未完成' : agent.available ? (agent.version ? `v${agent.version}` : '可用') : '不可用');
     name.append(chip);
     body.append(name);
     body.append(el('div', 'a-meta', `${agent.transport} · 认证:${agent.authModes.join(' / ')}${agent.reason ? ` · ${agent.reason}` : ''}`));
@@ -487,7 +505,11 @@ function renderModelMenu() {
 /* ===================== projects & sidebar ===================== */
 
 async function refreshProjects(keepActive) {
-  try { state.projects = await client.listProjects(); } catch { state.projects = []; }
+  const epoch = selectionEpoch;
+  let projects;
+  try { projects = await client.listProjects(); } catch { toast('项目读取失败，保留上次内容', true); return; }
+  if (epoch !== selectionEpoch) return;
+  state.projects = projects;
   if (!keepActive || !state.projects.some(p => p.id === state.activeProjectId)) {
     state.activeProjectId = state.projects.length ? state.projects[0].id : null;
     if (state.activeProjectId && !state.expanded.has(state.activeProjectId)) state.expanded.add(state.activeProjectId);
@@ -703,6 +725,15 @@ async function openSession(sessionId, options = {}) {
   let snapshot;
   try { snapshot = await client.loadSession(sessionId); } catch (error) { if (epoch !== sessionEpoch) return; state.activeSessionId = null; if (error.status === 404) forgetSessionSelection(sessionId); toast(error.message, true); return; }
   if (epoch !== sessionEpoch || state.activeSessionId !== sessionId) return;
+  let page = null, historyError = false;
+  if (typeof client.loadHistory === 'function') {
+    try { page = await client.loadHistory(sessionId); } catch { historyError = true; }
+    if (epoch !== sessionEpoch || state.activeSessionId !== sessionId) return;
+  }
+  historyView = { sessionId, epoch, events: [...(page?.events || snapshot.events || [])],
+    nextCursor: page?.nextCursor || null, incomplete: page?.incomplete === true, error: historyError,
+    supported: typeof client.loadHistory === 'function', loading: false, revision: 0 };
+  renderHistoryBar();
   const summary = snapshot.session;
   state.sessionSummary = summary;
   state.activeProjectId = summary.contextId || state.activeProjectId;
@@ -716,15 +747,16 @@ async function openSession(sessionId, options = {}) {
   renderModeLabel();
   $('session-title').textContent = sessionTitle(summary);
   setBusyState(summary.state);
-  let last = 0;
+  let last = Number(page?.highWater) || 0;
+  let streamOpened = false;
   let replayThrough = 0;
   // Timers and per-step durations are wall-clock side effects; replayed
   // snapshots did not witness them, so the stream must not fake them.
   state.replaying = true;
   try {
-    for (const event of snapshot.events || []) { renderEvent(event); last = Math.max(last, event.sequence || 0); }
+    for (const event of historyView.events) { renderEvent(event); if (!page) last = Math.max(last, event.sequence || 0); }
   } finally { state.replaying = false; }
-  rememberTitleFromEvents(snapshot.events || []);
+  rememberTitleFromEvents(historyView.events);
   // The SSE replay window can overlap the snapshot (a slow turn raced the
   // open, or the server answered a stale cursor with a full replay). Late or
   // duplicate events are dropped by session sequence so each renders once.
@@ -735,6 +767,13 @@ async function openSession(sessionId, options = {}) {
   state.unsub = client.subscribe(sessionId, event => {
     if (epoch !== sessionEpoch || state.activeSessionId !== sessionId) return;
     if (event.type === 'workbench/resync') {
+      if (historyView?.supported && !historyView.error) {
+        last = Number(event.highWater) || 0;
+        // The replay cache is not conversation truth. Re-read durable history
+        // on a gap without replacing the full transcript with its 5000-event tail.
+        void reloadHistory(historyView);
+        return;
+      }
       last = 0;
       replayThrough = Number(event.highWater);
       if (!Number.isFinite(replayThrough) || replayThrough < 0) replayThrough = 0;
@@ -748,8 +787,14 @@ async function openSession(sessionId, options = {}) {
       last = sequence;
     }
     if (state.replaying && !(Number.isFinite(sequence) && sequence > 0 && sequence <= replayThrough)) state.replaying = false;
+    if (historyView?.sessionId === sessionId) historyView.events.push(event);
+    state.liveRevision = (state.liveRevision || 0) + 1;
     renderEvent(event);
-  }, () => {}, { afterSequence: last });
+  }, () => {}, { afterSequence: last, onOpen: () => {
+    if (epoch !== sessionEpoch || state.activeSessionId !== sessionId) return;
+    if (streamOpened) { lastVisibleRefresh = 0; void refreshVisibleState(); }
+    streamOpened = true;
+  } });
   await renderProjectList();
   refreshContextUsage();
   if (embedded) {
@@ -761,6 +806,95 @@ async function openSession(sessionId, options = {}) {
   }
 }
 
+function renderHistoryBar() {
+  const bar = $('history-bar'), more = $('history-more'), status = $('history-status');
+  if (!bar || !more || !status) return;
+  const view = historyView;
+  bar.hidden = !view || (!view.nextCursor && !view.incomplete && !view.error && !view.loading);
+  more.hidden = !view?.nextCursor && !view?.error;
+  more.disabled = view?.loading === true;
+  more.textContent = view?.loading ? '正在加载…' : view?.error ? '重试读取历史' : '加载更早记录';
+  status.textContent = view?.error ? '完整历史读取失败，当前记录可能不完整。'
+    : view?.incomplete ? '旧版记录已截断；当前仅展示实际保存的部分。' : '';
+}
+
+function historyEventKey(event) { return JSON.stringify([event.type, event.id || '', event.sequence || 0, event.at || '', event.text || '']); }
+
+function rebuildHistory(view, events, prepend = true) {
+  const stream = $('stream');
+  const top = stream.scrollTop, height = stream.scrollHeight, following = state.follow, intent = state.scrollIntent;
+  const prompts = [...($('stream-col').querySelectorAll?.('.msg.user') || [])];
+  const streamY = stream.getBoundingClientRect?.().top;
+  const anchor = streamY == null ? null : prompts.filter(node => node.getBoundingClientRect().top <= streamY + 8).pop() || prompts[0];
+  const anchorKey = anchor?.dataset.historyKey;
+  const anchorY = anchor ? anchor.getBoundingClientRect().top - streamY : 0;
+  const folds = [...($('stream-col').querySelectorAll?.('details') || [])].map(node => node.open);
+  const busyState = state.sessionState;
+  resetStream();
+  state.follow = false;
+  state.replaying = true;
+  try { for (const event of events) renderEvent(event); }
+  finally { state.replaying = false; state.follow = following; state.scrollIntent = intent; }
+  const rebuiltFolds = [...($('stream-col').querySelectorAll?.('details') || [])];
+  const offset = rebuiltFolds.length - folds.length;
+  if (offset >= 0) for (let i = 0; i < folds.length; i++) rebuiltFolds[offset + i].open = folds[i];
+  if (busyState) setBusyState(busyState);
+  const restoredAnchor = anchorKey && [...($('stream-col').querySelectorAll?.('.msg.user') || [])].find(node => node.dataset.historyKey === anchorKey);
+  stream.scrollTop = following ? stream.scrollHeight : restoredAnchor
+    ? stream.scrollTop + restoredAnchor.getBoundingClientRect().top - streamY - anchorY
+    : top + (prepend ? stream.scrollHeight - height : 0);
+  view.events = events;
+  renderHistoryBar();
+}
+
+async function loadEarlierHistory() {
+  const view = historyView;
+  if (!view || view.loading) return;
+  if (view.error) return reloadHistory(view);
+  if (!view.nextCursor) return;
+  view.loading = true; renderHistoryBar();
+  const revision = ++view.revision;
+  try {
+    const page = await client.loadHistory(view.sessionId, { before: view.nextCursor });
+    if (historyView !== view || view.epoch !== sessionEpoch || revision !== view.revision) return;
+    view.nextCursor = page.nextCursor;
+    view.incomplete = page.incomplete;
+    view.error = false;
+    rebuildHistory(view, [...page.events, ...view.events]);
+  } catch { if (historyView === view) view.error = true; }
+  finally { if (historyView === view && revision === view.revision) { view.loading = false; renderHistoryBar(); } }
+}
+
+async function reloadHistory(view) {
+  if (!view || historyView !== view || !view.supported) return;
+  const revision = ++view.revision;
+  view.loading = true; renderHistoryBar();
+  const oldCursor = view.nextCursor;
+  const oldest = view.events.find(event => event.type === 'claude/user-prompt') || view.events[0];
+  const oldestKey = oldest && historyEventKey(oldest);
+  const buffered = view.events;
+  const liveStart = buffered.length;
+  try {
+    let page = await client.loadHistory(view.sessionId);
+    let events = page.events, nextCursor = page.nextCursor;
+    // Preserve the amount of history the reader already loaded, including a
+    // fully-read thread; a reconnect must not silently drop its older pages.
+    const seen = new Set();
+    while (nextCursor && (!oldCursor || (oldestKey && !events.some(event => historyEventKey(event) === oldestKey)))) {
+      if (seen.has(nextCursor)) throw new Error('history cursor did not advance');
+      seen.add(nextCursor);
+      const older = await client.loadHistory(view.sessionId, { before: nextCursor });
+      events = [...older.events, ...events]; nextCursor = older.nextCursor;
+      if (historyView !== view || revision !== view.revision) return;
+    }
+    if (historyView !== view || view.epoch !== sessionEpoch || revision !== view.revision) return;
+    const queued = buffered.slice(liveStart).filter(event => Number(event.sequence) > page.highWater);
+    view.nextCursor = nextCursor; view.incomplete = page.incomplete; view.error = false;
+    rebuildHistory(view, [...events, ...queued], false);
+  } catch { if (historyView === view) view.error = true; }
+  finally { if (historyView === view && revision === view.revision) { view.loading = false; renderHistoryBar(); } }
+}
+
 function publishKnowledge(projectId, sessionId, knowledge) {
   if (embedded) window.parent.postMessage({ type: 'kb:knowledge', app: 'agent-terminal', projectId, sessionId, knowledge }, document.referrer ? new URL(document.referrer).origin : location.origin);
 }
@@ -770,6 +904,8 @@ function detachSession(options = {}) {
   if (state.unsub) { try { state.unsub(); } catch {} state.unsub = null; }
   state.activeSessionId = null;
   state.sessionSummary = null;
+  historyView = null;
+  renderHistoryBar();
   if (!options.preserveAttachments) state.attachments = [];
   $('btn-ctx').hidden = true;
   renderAttachmentTray();
@@ -790,6 +926,7 @@ function resetStream() {
   col.textContent = '';
   turn = null;
   state.follow = true;
+  state.scrollIntent = null;
   const jump = $('jump-latest');
   if (jump) jump.hidden = true;
 }
@@ -956,7 +1093,7 @@ function endTurnVisuals(durationMs) {
       const meta = step.querySelector('.s-meta');
       if (meta) { meta.classList.remove('running'); meta.textContent = t.interrupted ? '已中断' : '完成'; }
     }
-    t.proc.open = false;
+    if (state.replaying || state.follow) t.proc.open = false;
   }
   turn = null;
 }
@@ -1038,6 +1175,7 @@ function renderEvent(event) {
       rememberTitleFromEvents([event]);
       if (state.activeSessionId && event.text) state.sessionTitles.set(state.activeSessionId, event.text.replace(/\s+/g, ' ').slice(0, 24));
       const wrap = el('div', 'msg user');
+      wrap.dataset.historyKey = historyEventKey(event);
       const bubble = el('div', 'bubble', event.text || '');
       wrap.append(bubble);
       const copy = el('button', 'bubble-copy');
@@ -1084,7 +1222,8 @@ function renderEvent(event) {
       if (event.type === 'claude/text-delta') {
         ctx.liveRaw += event.text || '';
         ctx.liveText._rawFull = ctx.liveRaw;
-        ctx.liveText._pacer.push(ctx.liveRaw);
+        if (state.replaying) ctx.liveText._pacer.finish(ctx.liveRaw);
+        else ctx.liveText._pacer.push(ctx.liveRaw);
       }
       break;
     }
@@ -1678,6 +1817,7 @@ function fmtTokens(value) {
 /* ===================== busy / activity / context ===================== */
 
 function setBusyState(sessionState) {
+  state.sessionState = sessionState;
   state.busy = ['running', 'thinking', 'tool-running', 'spawning', 'pending-permission'].includes(sessionState);
   const status = $('session-status');
   const send = $('btn-send');
@@ -1841,6 +1981,10 @@ async function sendCurrent() {
   renderAttachmentTray();
   const sentSessionId = state.activeSessionId, sentProjectId = state.activeProjectId;
   rememberProjectDraft(sentProjectId, { text: '', attachments: [], sessionId: sentSessionId });
+  // Engage before awaiting the backend: output can arrive while send is still
+  // pending, and its eventual acknowledgement must not undo an upward scroll.
+  state.follow = true;
+  state.scrollIntent = null;
   try {
     const accepted = await client.send({
       sessionId: state.activeSessionId,
@@ -1852,7 +1996,6 @@ async function sendCurrent() {
     if (accepted?.knowledge && state.activeSessionId === sentSessionId) publishKnowledge(sentProjectId, sentSessionId, accepted.knowledge);
     if (state.activeSessionId !== sentSessionId) return;
     setBusyState(accepted?.state || 'running');
-    state.follow = true; // sending a message re-engages follow mode
   } catch (error) {
     if (state.activeProjectId !== sentProjectId || state.activeSessionId !== sentSessionId) {
       const draft = projectDrafts.get(sentProjectId) || {};
@@ -1933,6 +2076,7 @@ function renderModeLabel() {
 /* ===================== settings ===================== */
 
 function openSettings(tab) {
+  if (tab === 'agents') void refreshAgents();
   closePops();
   document.querySelectorAll('.stab').forEach(node => node.classList.toggle('active', node.dataset.s === tab));
   document.querySelectorAll('.spanel').forEach(node => node.classList.remove('active'));
@@ -1955,7 +2099,7 @@ function wireSettings() {
       $(`s-${tab.dataset.s}`).classList.add('active');
     });
   });
-  $('btn-rescan').addEventListener('click', async () => { await refreshAgents(); toast('已重新扫描', false, true); });
+  $('btn-rescan').addEventListener('click', async () => { await refreshAgents(true); toast(state.agentsError ? '检查未完成，请重试' : '正在重新检查 Agent', state.agentsError); });
   $('mgmt-add').addEventListener('click', () => renderProviderDetail(null));
   wireCaptureSetting();
 }
@@ -2433,16 +2577,38 @@ function wireChrome() {
   const stream = $('stream');
   const jump = $('jump-latest');
   if (stream && stream.addEventListener) {
+    const pauseFollow = () => {
+      state.follow = false;
+      state.scrollIntent = 'up';
+      if (jump) jump.hidden = false;
+    };
+    // Wheel intent precedes the browser's scroll action. Waiting for a 120px
+    // distance lets a fast delta repeatedly win against small wheel steps.
+    stream.addEventListener('wheel', event => {
+      if (event.deltaY < 0) pauseFollow();
+      else if (event.deltaY > 0) state.scrollIntent = 'down';
+    }, { passive: true });
+    stream.addEventListener('keydown', event => {
+      if (['ArrowUp', 'PageUp', 'Home'].includes(event.key) || (event.key === ' ' && event.shiftKey)) pauseFollow();
+      else if (['ArrowDown', 'PageDown', 'End', ' '].includes(event.key)) state.scrollIntent = 'down';
+    });
+    let previousTop = stream.scrollTop;
     stream.addEventListener('scroll', () => {
       const distance = stream.scrollHeight - stream.scrollTop - stream.clientHeight;
-      if (distance > 120) state.follow = false;
-      else if (distance < 40) state.follow = true;
+      if (stream.scrollTop < previousTop - 1 && distance > 2) state.follow = false;
+      if (distance > 2) state.follow = false;
+      else if (state.scrollIntent !== 'up') state.follow = true;
+      previousTop = stream.scrollTop;
       if (jump) jump.hidden = state.follow;
+      if (stream.scrollTop < 80 && historyView?.nextCursor && !historyView.loading) void loadEarlierHistory();
     });
   }
+  const historyMore = $('history-more');
+  if (historyMore) historyMore.addEventListener('click', loadEarlierHistory);
   if (jump) {
     jump.addEventListener('click', () => {
       state.follow = true;
+      state.scrollIntent = null;
       jump.hidden = true;
       if (stream) stream.scrollTop = stream.scrollHeight;
     });
@@ -2474,6 +2640,28 @@ function embedAllowedOrigin(origin) {
     return origin === (document.referrer ? new URL(document.referrer).origin : location.origin);
   } catch { return false; }
 }
+let visibleRefreshJob = null, lastVisibleRefresh = 0, embedVisible = false;
+function refreshVisibleState() {
+  if (visibleRefreshJob) return visibleRefreshJob;
+  if (Date.now() - lastVisibleRefresh < 1000) return Promise.resolve();
+  const project = state.activeProjectId, session = state.activeSessionId, epoch = sessionEpoch;
+  visibleRefreshJob = (async () => {
+    await Promise.allSettled([refreshAgents(), refreshProfiles(), refreshProjects(true)]);
+    if (epoch !== sessionEpoch || project !== state.activeProjectId || session !== state.activeSessionId || !session) return;
+    try {
+      if (historyView?.supported) await reloadHistory(historyView);
+      const revision = state.liveRevision;
+      const snapshot = await client.loadSession(session);
+      if (epoch !== sessionEpoch || session !== state.activeSessionId || revision !== state.liveRevision) return;
+      state.sessionSummary = snapshot.session;
+      setBusyState(snapshot.session.state);
+    } catch { /* Stream stays alive; never erase an active conversation on a failed read. */ }
+  })().finally(() => { visibleRefreshJob = null; lastVisibleRefresh = Date.now(); });
+  return visibleRefreshJob;
+}
+window.addEventListener('focus', () => { void refreshVisibleState(); });
+window.addEventListener('online', () => { lastVisibleRefresh = 0; void refreshVisibleState(); });
+document.addEventListener('visibilitychange', () => { if (!document.hidden) void refreshVisibleState(); });
 function setEmbedSidebarVisible(visible) {
   document.body.classList.toggle('embed-collapse', !visible);
 }
@@ -2518,6 +2706,16 @@ window.addEventListener('message', async ev => {
   if (!data || typeof data !== 'object') return;
   const reply = payload => { if (ev.source) ev.source.postMessage(Object.assign({ app: 'agent-terminal', requestId: data.requestId }, payload), ev.origin); };
   if (data.type === 'kb:theme') { document.body.classList.toggle('light', data.theme !== 'dark'); document.body.dataset.kbTheme = data.theme === 'dark' ? 'dark' : 'light'; reply({ type: 'kb:configured', theme: document.body.dataset.kbTheme }); return; }
+  if (data.type === 'kb:visibility' || data.type === 'kb:refresh') {
+    if (data.type === 'kb:visibility') {
+      const wasVisible = embedVisible; embedVisible = data.visible === true;
+      if (!embedVisible || wasVisible) return;
+    }
+    const project = state.activeProjectId, session = state.activeSessionId, epoch = selectionEpoch;
+    await refreshVisibleState();
+    if (epoch === selectionEpoch && project === state.activeProjectId && session === state.activeSessionId) reply({ type: 'kb:refreshed', project, sessionId: session, ok: !state.agentsError });
+    return;
+  }
   if (data.type === 'kb:open-settings') { openSettings('providers'); return; }
   if (data.type === 'kb:sidebar') setEmbedSidebarVisible(!!data.visible);
   else if (data.type === 'kb:select-project') {

package/apps/agent-terminal/index.html

@@ -40,7 +40,11 @@
       <button class="ghost" id="btn-top-settings" title="设置（模型供应商）"><svg class="ics" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33h.01a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51h.01a1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82v.01a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg></button>
     </div>
 
-    <div class="stream" id="stream">
+    <div class="stream" id="stream" tabindex="0" aria-label="会话记录">
+      <div class="history-bar" id="history-bar" hidden>
+        <button class="linklike" id="history-more" type="button">加载更早记录</button>
+        <span id="history-status" role="status"></span>
+      </div>
       <div class="col" id="stream-col">
         <div class="empty-hint" id="empty-hint">
           <div class="big"><span class="hint-wrap"><span class="hint-art"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m5 8 4 4-4 4"/><path d="M13 16h6"/></svg></span><span class="hint-spark"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3l1.9 5.8L20 12l-6.1 3.2L12 21l-1.9-5.8L4 12l6.1-3.2z"/></svg></span></span></div>

package/docs/sdk/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Claude AI Workbench API
-  version: 0.13.2-rc.13
+  version: 0.13.2-rc.14
   description: Versioned local API for AI Profile, credential and Claude Code session management.
 servers:
   - url: http://127.0.0.1:5760/api/claude-workbench/v1
@@ -48,6 +48,13 @@ paths:
                   agents:
                     type: array
                     items: { $ref: "#/components/schemas/AgentInfo" }
+  /agents/refresh:
+    post:
+      tags: [Agents]
+      operationId: refreshAgents
+      responses:
+        "202":
+          description: Background scan started or reused; previous agents remain available with scan state and generation.
   /projects:
     get:
       tags: [Projects]
@@ -311,6 +318,37 @@ paths:
       responses:
         "200": { description: Session snapshot }
         "404": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/history:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    get:
+      tags: [Sessions]
+      operationId: getSessionHistory
+      description: Durable conversation history, separate from the bounded SSE replay cache. Pages contain whole turns in chronological order.
+      parameters:
+        - in: query
+          name: before
+          description: Cursor returned by the previous page. Omit for recent turns.
+          schema: { type: string }
+        - in: query
+          name: limit
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+      responses:
+        "200":
+          description: History page; incomplete is true when an earlier prefix cannot be recovered.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [events, nextCursor, incomplete, highWater]
+                properties:
+                  events: { type: array, items: { type: object } }
+                  nextCursor: { type: string, nullable: true }
+                  incomplete: { type: boolean }
+                  highWater: { type: integer, minimum: 0 }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+        "503": { $ref: "#/components/responses/Error" }
   /sessions/{sessionId}/events:
     parameters:
       - $ref: "#/components/parameters/SessionId"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/claude-ai-workbench",
-  "version": "0.13.2-rc.13",
+  "version": "0.13.2-rc.14",
   "description": "Shared Claude Code terminal and Anthropic-compatible AI profile modules for local developer tools.",
   "type": "commonjs",
   "main": "src/index.js",

package/packages/client/index.d.ts

@@ -15,6 +15,7 @@ import type {
   AttachmentInput,
   SlashCommand,
   SessionSnapshot,
+  SessionHistoryPage,
   SessionSummary,
   WorkbenchContext,
   WorkbenchEvent,
@@ -41,12 +42,15 @@ export interface ClaudeWorkbenchClientOptions {
   apiBase?: string;
   fetch?: typeof fetch;
   EventSource?: typeof EventSource;
+  readTimeoutMs?: number;
 }
 
 export interface ClaudeWorkbenchClient {
   health(): Promise<HealthResult>;
   runtime(): Promise<RuntimeInfo>;
   listAgents(): Promise<AgentStatus[]>;
+  agentStatus(): Promise<{ agents: AgentStatus[]; scan?: { state: string; generation: number; updatedAt: string | null } }>;
+  refreshAgents(): ReturnType<ClaudeWorkbenchClient['agentStatus']>;
   listProjects(): Promise<Project[]>;
   createProject(project: ProjectInput): Promise<Project>;
   getProject(id: string): Promise<Project>;
@@ -62,6 +66,7 @@ export interface ClaudeWorkbenchClient {
   listSessions(context: WorkbenchContext | string, options?: ListSessionsOptions): Promise<SessionSummary[]>;
   startSession(context: WorkbenchContext, options?: StartSessionOptions): Promise<SessionSummary>;
   loadSession(id: string, options?: RequestOptions): Promise<SessionSnapshot>;
+  loadHistory(id: string, options?: RequestOptions & { before?: string; limit?: number }): Promise<SessionHistoryPage>;
   listCommands(id: string, options?: RequestOptions): Promise<SlashCommand[]>;
   subscribe(id: string, handlers: StreamHandlers | ((event: WorkbenchEvent) => void), onError?: (error: Error) => void, options?: {afterSequence?: number}): () => void;
   send(sessionId: string, text: string, options?: SendOptions): Promise<unknown>;