@steerable/agent-shell-web 0.6.53 → 0.6.56

package/src/hooks/useChatsAndAgents.ts

@@ -8,7 +8,7 @@
  * adapter:
  *   - It wires the framework hook to the local-backend transport
  *     (`@/lib/local-api`).
- *   - It gates everything behind `isElectron()` so a renderer running in a
+ *   - It gates everything behind `hasHostBridge()` so a renderer running in a
  *     plain browser doesn't fire requests.
  *   - It keeps the legacy `UseChatsAndAgentsResult` shape so callers
  *     (`AgentLayout`, `useChatsAndAgents()` consumers) don't change.
@@ -35,7 +35,7 @@ import {
   type LocalChat,
   type LocalChatAgent,
 } from '@/lib/local-api';
-import { isElectron } from '@/lib/electron-bridge';
+import { hasHostBridge } from '@/lib/host-bridge';
 import { pickDefaultAgentId } from '@/brand';
 
 const CHAT_PAGE_SIZE = 50;
@@ -66,12 +66,12 @@ export interface UseChatsAndAgentsResult {
 }
 
 export function useChatsAndAgents(): UseChatsAndAgentsResult {
-  const isElectronRef = useRef(isElectron());
+  const hasHostBridgeRef = useRef(hasHostBridge());
 
   const transport = useMemo<ChatListTransport<LocalChat, LocalChatAgent>>(
     () => ({
       listChats: async ({ page, pageSize }) => {
-        if (!isElectronRef.current) return { chats: [], hasMore: false };
+        if (!hasHostBridgeRef.current) return { chats: [], hasMore: false };
         const data = await listChats({ page, limit: pageSize });
         return {
           chats: data.chats,
@@ -79,13 +79,13 @@ export function useChatsAndAgents(): UseChatsAndAgentsResult {
         };
       },
       listAgents: async () => {
-        if (!isElectronRef.current) return [];
+        if (!hasHostBridgeRef.current) return [];
         const data = await listChatAgents(false);
         return data.agents;
       },
       createChat: async ({ agentId, projectId }) => {
-        if (!isElectronRef.current) {
-          throw new Error('not in electron');
+        if (!hasHostBridgeRef.current) {
+          throw new Error('not connected to the host');
         }
         const res = await apiCreateChat({
           ...(agentId ? { agentId } : {}),
@@ -94,7 +94,7 @@ export function useChatsAndAgents(): UseChatsAndAgentsResult {
         return res.chatId;
       },
       deleteChat: async (chatId) => {
-        if (!isElectronRef.current) return false;
+        if (!hasHostBridgeRef.current) return false;
         await apiDeleteChat(chatId);
         return true;
       },
@@ -110,7 +110,7 @@ export function useChatsAndAgents(): UseChatsAndAgentsResult {
     pageSize: CHAT_PAGE_SIZE,
     // The renderer mounts before electron decides whether the bridge is live;
     // skip the auto-fetch and trigger it manually after the SSR no-op check.
-    skipInitialLoad: !isElectronRef.current,
+    skipInitialLoad: !hasHostBridgeRef.current,
   });
 
   // Default-select this flavor's builtin expert once the catalog loads.

package/src/hooks/useProjects.ts

@@ -3,7 +3,7 @@
  * 任一侧新建、改名或改目录后调用 refresh，其它订阅者一起更新。
  */
 import { useCallback, useEffect, useSyncExternalStore } from 'react';
-import { isElectron } from '@/lib/electron-bridge';
+import { hasHostBridge } from '@/lib/host-bridge';
 import { hostToolChrome } from '@/lib/host-tools';
 import { listProjects, type LocalProject } from '@/lib/local-api';
 
@@ -36,7 +36,7 @@ export function getProjectsSnapshot(): ProjectsSnapshot {
 /** 重新拉取项目列表并通知所有订阅者。非 Electron 或关掉项目入口时清空。 */
 export async function refreshProjects(): Promise<void> {
   const seq = ++requestSeq;
-  if (!isElectron() || !hostToolChrome('projects')) {
+  if (!hasHostBridge() || !hostToolChrome('projects')) {
     if (snapshot.projects.length > 0 || snapshot.error) {
       snapshot = EMPTY_SNAPSHOT;
       emit();
@@ -51,7 +51,7 @@ export async function refreshProjects(): Promise<void> {
   } catch (err) {
     if (seq !== requestSeq) return;
     const message = err instanceof Error ? err.message : String(err);
-    console.error('获取项目列表失败:', err);
+    console.error('Failed to load projects:', err);
     snapshot = { projects: snapshot.projects, error: message };
     emit();
   }

package/src/i18n/agent-label.ts

@@ -0,0 +1,15 @@
+import { t } from './runtime';
+
+/**
+ * 内置智能体的界面名按 id 翻译。库里的 name 仍是种子原文，切换语言不改历史行。
+ * 用户自建智能体用库里的名字。
+ */
+const BUILTIN_AGENT_LABELS: Record<string, string> = {
+  'local-assistant': 'Computer operator',
+  'all-round-assistant': 'Assistant',
+};
+
+export function agentLabel(agent: { id: string; name: string }): string {
+  const source = BUILTIN_AGENT_LABELS[agent.id];
+  return source ? t(source) : agent.name;
+}

package/src/i18n/index.tsx

@@ -0,0 +1,68 @@
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import {
+  configureI18n,
+  getLocale,
+  registerLocale,
+  setLocale,
+  subscribeI18n,
+  supportedLocales,
+  t,
+} from './runtime';
+
+export { configureI18n, getLocale, registerLocale, setLocale, supportedLocales, t };
+export { LOCALE_STORAGE_KEY, SOURCE_LOCALE, normalizeLocale, resolveLocale } from './translate';
+
+interface I18nContextValue {
+  locale: string;
+  locales: readonly string[];
+  t: typeof t;
+  setLocale: (locale: string) => void;
+}
+
+const I18nContext = createContext<I18nContextValue | null>(null);
+
+/**
+ * 包住应用树。语言变化时用 key 重挂子树，这样直接调用 `t()` 的组件也会换文案。
+ */
+export function I18nProvider({ children }: { children: ReactNode }) {
+  const [locale, setSnapshot] = useState(getLocale);
+  useEffect(() => subscribeI18n(() => setSnapshot(getLocale())), []);
+  const value = useMemo<I18nContextValue>(
+    () => ({
+      locale,
+      locales: supportedLocales(),
+      t,
+      setLocale: (next) => {
+        if (!setLocale(next)) return;
+        window.steerableHost?.setLocale?.(next);
+      },
+    }),
+    [locale],
+  );
+  return (
+    <I18nContext.Provider value={value}>
+      <div key={locale} className="contents">
+        {children}
+      </div>
+    </I18nContext.Provider>
+  );
+}
+
+export function useI18n(): I18nContextValue {
+  const value = useContext(I18nContext);
+  if (value) return value;
+  return {
+    locale: getLocale(),
+    locales: supportedLocales(),
+    t,
+    setLocale,
+  };
+}
+
+/** 语言名用该语言自己的写法，不跟着界面语言翻。 */
+export function localeEndonym(locale: string): string {
+  if (locale === 'zh') return '中文'; // i18n:allow 语言名用该语言自己的写法
+  if (locale === 'en') return 'English';
+  return locale;
+}

package/src/i18n/runtime.ts

@@ -0,0 +1,117 @@
+/**
+ * 渲染进程的当前语言。产品入口在 bootstrap 前 registerLocale，
+ * bootstrap 再 configureI18n。未配置时只有英语。
+ */
+
+import {
+  LOCALE_STORAGE_KEY,
+  SOURCE_LOCALE,
+  resolveLocale,
+  translate,
+} from './translate';
+
+export interface I18nStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+interface I18nState {
+  locales: string[];
+  defaultLocale: string;
+  locale: string;
+  catalogs: Record<string, Record<string, string>>;
+}
+
+const state: I18nState = {
+  locales: [SOURCE_LOCALE],
+  defaultLocale: SOURCE_LOCALE,
+  locale: SOURCE_LOCALE,
+  catalogs: {},
+};
+
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+export function subscribeI18n(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function registerLocale(locale: string, messages: Record<string, string>): void {
+  const normalized = locale.trim();
+  if (!normalized || normalized === SOURCE_LOCALE) return;
+  state.catalogs[normalized] = { ...state.catalogs[normalized], ...messages };
+  emit();
+}
+
+function readStorage(): I18nStorage | null {
+  if (typeof localStorage === 'undefined') return null;
+  return localStorage;
+}
+
+function systemLocale(): string | null {
+  if (typeof navigator === 'undefined') return null;
+  return navigator.language || null;
+}
+
+export function configureI18n(options: {
+  locales: readonly string[];
+  defaultLocale: string;
+  systemLocale?: string | null;
+  storage?: I18nStorage | null;
+}): void {
+  const locales = [...new Set(options.locales.filter((locale) => locale.length > 0))];
+  state.locales = locales.length > 0 ? locales : [SOURCE_LOCALE];
+  state.defaultLocale = options.defaultLocale || SOURCE_LOCALE;
+  const storage = options.storage === undefined ? readStorage() : options.storage;
+  state.locale = resolveLocale({
+    supported: state.locales,
+    defaultLocale: state.defaultLocale,
+    saved: storage?.getItem(LOCALE_STORAGE_KEY) ?? null,
+    system: options.systemLocale === undefined ? systemLocale() : options.systemLocale,
+  });
+  applyDocumentLang(state.locale);
+  emit();
+}
+
+export function getLocale(): string {
+  return state.locale;
+}
+
+export function supportedLocales(): readonly string[] {
+  return state.locales;
+}
+
+export function setLocale(locale: string): boolean {
+  if (!state.locales.includes(locale)) return false;
+  if (state.locale === locale) return true;
+  state.locale = locale;
+  const storage = readStorage();
+  storage?.setItem(LOCALE_STORAGE_KEY, locale);
+  applyDocumentLang(locale);
+  emit();
+  return true;
+}
+
+export function t(message: string, params?: Record<string, string | number>): string {
+  return translate(message, state.locale, state.catalogs, params);
+}
+
+function applyDocumentLang(locale: string): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.lang = locale === 'zh' ? 'zh-CN' : locale;
+}
+
+/** 测试隔离。生产代码不调用。 */
+export function resetI18nForTests(): void {
+  state.locales = [SOURCE_LOCALE];
+  state.defaultLocale = SOURCE_LOCALE;
+  state.locale = SOURCE_LOCALE;
+  state.catalogs = {};
+  listeners.clear();
+}

package/src/i18n/translate.ts

@@ -0,0 +1,65 @@
+/**
+ * 界面文案查找。源语言是英语：调用处写英文句子，应用层语言包把英文映射到译文。
+ * 缺译文时原样返回英文，漏翻在界面上看得见。
+ */
+
+export const SOURCE_LOCALE = 'en';
+export const LOCALE_STORAGE_KEY = 'agent-shell.locale';
+
+/** `zh-CN` / `en-US` 收成语言包用的主标签。不认识的标签保留主段。 */
+export function normalizeLocale(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const lower = raw.trim().toLowerCase().replace(/_/g, '-');
+  if (!lower) return null;
+  if (lower.startsWith('zh')) return 'zh';
+  if (lower.startsWith('en')) return 'en';
+  const primary = lower.split('-')[0];
+  return primary || null;
+}
+
+export function resolveLocale(options: {
+  supported: readonly string[];
+  defaultLocale: string;
+  saved: string | null;
+  system: string | null;
+}): string {
+  const supported = options.supported.filter((locale) => locale.length > 0);
+  const list = supported.length > 0 ? supported : [SOURCE_LOCALE];
+  const pick = (value: string | null): string | null => {
+    if (!value) return null;
+    if (list.includes(value)) return value;
+    const normalized = normalizeLocale(value);
+    if (normalized && list.includes(normalized)) return normalized;
+    return null;
+  };
+  return (
+    pick(options.saved) ??
+    pick(options.system) ??
+    pick(options.defaultLocale) ??
+    list[0] ??
+    SOURCE_LOCALE
+  );
+}
+
+export function formatMessage(
+  template: string,
+  params?: Record<string, string | number>,
+): string {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (whole, name: string) => {
+    const value = params[name];
+    return value === undefined ? whole : String(value);
+  });
+}
+
+/** 语言包的键是英文源句。源语言不查表。 */
+export function translate(
+  message: string,
+  locale: string,
+  catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>,
+  params?: Record<string, string | number>,
+): string {
+  const table = locale === SOURCE_LOCALE ? undefined : catalogs[locale];
+  const template = table?.[message] ?? message;
+  return formatMessage(template, params);
+}

package/src/layouts/AgentLayout.tsx

@@ -8,7 +8,7 @@ import { AskUserPromptProvider } from '@/components/chat/AskUserPromptProvider';
 import { ApprovalPromptProvider } from '@/components/chat/ApprovalPromptProvider';
 import { InsightsConsentBanner } from '@/components/settings/InsightsSettingsPanel';
 import { trackBehavior } from '@/lib/insights';
-import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
+import { getHostBridge, hasHostBridge } from '@/lib/host-bridge';
 import { deleteChatIfEmpty, pruneEmptyChats } from '@/lib/local-api';
 import { PORTABLE_CHATS_CHANGED_EVENT } from '@/lib/portable';
 import { getPackChatSlots, type PackChatSlotContribution } from '@/packs/registry';
@@ -17,6 +17,7 @@ import {
   type UseChatsAndAgentsResult,
 } from '@/hooks/useChatsAndAgents';
 import { hostToolChrome, sanitizeRightPanelKind, settingsChrome } from '@/lib/host-tools';
+import { t } from '@/i18n';
 
 /**
  * AgentLayout wraps `/agent`, `/agent/:chatId`, and `/` (default) with a
@@ -169,7 +170,7 @@ function AgentLayoutContent() {
     refreshChatsRef.current = data.refreshChats;
   }, [data.refreshChats]);
   useEffect(() => {
-    const bridge = getElectronBridge();
+    const bridge = getHostBridge();
     if (!bridge?.onChatTitleUpdated) return;
     const unsubscribe = bridge.onChatTitleUpdated((payload) => {
       patchChatTitleRef.current(payload.chatId, payload.title);
@@ -180,7 +181,7 @@ function AgentLayoutContent() {
   // 现场补建（见 router.handleStream），随后广播 `chat-created`。这里刷一次
   // 侧栏把这条会话拉出来——否则会出现"URL 能聊、列表里却查无此会话"。
   useEffect(() => {
-    const bridge = getElectronBridge();
+    const bridge = getHostBridge();
     if (!bridge?.onChatCreated) return;
     const unsubscribe = bridge.onChatCreated(() => {
       void refreshChatsRef.current();
@@ -198,7 +199,7 @@ function AgentLayoutContent() {
   // 空会话不进侧栏：启动时清掉从未发过消息的残骸；离开一段空对话时丢掉它。
   // except / 离开检测都避开当前打开的 chatId，避免和首页首条发送抢跑。
   useEffect(() => {
-    if (!isElectron()) return;
+    if (!hasHostBridge()) return;
     let cancelled = false;
     void pruneEmptyChats(chatId)
       .then((res) => {
@@ -216,7 +217,7 @@ function AgentLayoutContent() {
   useEffect(() => {
     const prev = prevChatIdRef.current;
     prevChatIdRef.current = chatId;
-    if (!isElectron() || !prev || prev === chatId) return;
+    if (!hasHostBridge() || !prev || prev === chatId) return;
     void deleteChatIfEmpty(prev)
       .then((res) => {
         if (res.deleted) return refreshChatsRef.current();
@@ -415,7 +416,7 @@ function AgentLayoutContent() {
   // so this flips the layout state owned by AgentLayout.
   useEffect(() => {
     if (!hostToolChrome('terminal')) return;
-    const bridge = getElectronBridge();
+    const bridge = getHostBridge();
     if (!bridge?.onMenuOpenTerminal) return;
     bridge.onMenuOpenTerminal(() => {
       toggleRightPanel('terminal');
@@ -560,8 +561,8 @@ function AgentLayoutContent() {
               type="button"
               onClick={toggleSidebarCollapsed}
               className="flex h-7 w-7 items-center justify-center rounded-full text-agent-muted-foreground transition-colors duration-200 hover:bg-agent-foreground/5 hover:text-agent-foreground"
-              title="展开侧边栏"
-              aria-label="展开侧边栏"
+              title={t('Expand sidebar')}
+              aria-label={t('Expand sidebar')}
             >
               <LuPanelLeftOpen className="h-3.5 w-3.5" />
             </button>
@@ -581,11 +582,11 @@ function AgentLayoutContent() {
           <div
             role="separator"
             aria-orientation="vertical"
-            aria-label="调整侧边栏宽度"
+            aria-label={t('Resize sidebar')}
             onMouseDown={() => setIsResizing(true)}
             onDoubleClick={resetWidth}
             className="w-1 flex-shrink-0 cursor-col-resize bg-transparent transition-colors hover:bg-agent-border/60"
-            title="拖拽调整侧边栏宽度（双击恢复默认）"
+            title={t('Drag to resize the sidebar (double-click to reset)')}
           />
         </>
       )}
@@ -612,11 +613,11 @@ function AgentLayoutContent() {
               <div
                 role="separator"
                 aria-orientation="vertical"
-                aria-label="调整右侧面板宽度"
+                aria-label={t('Resize right panel')}
                 onMouseDown={() => setIsTerminalResizing(true)}
                 onDoubleClick={resetTerminalWidth}
                 className="w-1 flex-shrink-0 cursor-col-resize bg-transparent transition-colors hover:bg-agent-border/60"
-                title="拖拽调整右侧面板宽度（双击恢复默认）"
+                title={t('Drag to resize the right panel (double-click to reset)')}
               />
               <div
                 className={`h-full flex-shrink-0 overflow-hidden rounded-agent-lg shadow-sm ${

package/src/lib/app-release.ts

@@ -1,4 +1,5 @@
-import type { AppReleasePhase, AppReleaseSnapshot } from './electron-bridge';
+import { t } from '@/i18n';
+import type { AppReleasePhase, AppReleaseSnapshot } from './host-bridge';
 
 export interface AppReleaseView {
   version: string | null;
@@ -20,21 +21,25 @@ export function sidebarUpdateLabel(
   if (!snap.enabled || snap.phase === 'disabled') return null;
   switch (snap.phase) {
     case 'checking':
-      return '检查中';
+      return t('Checking');
     case 'downloading':
-      return typeof snap.percent === 'number' ? `下载 ${Math.round(snap.percent)}%` : '下载中';
+      return typeof snap.percent === 'number'
+        ? t('Downloading {percent}%', { percent: Math.round(snap.percent) })
+        : t('Downloading…');
     case 'ready':
-      return snap.availableVersion ? `升级 ${snap.availableVersion}` : '升级';
+      return snap.availableVersion
+        ? t('Update to {version}', { version: snap.availableVersion })
+        : t('Update');
     case 'installing':
-      return '正在安装';
+      return t('Installing');
     case 'error':
-      return '重试';
+      return t('Retry');
     case 'idle':
-      if (snap.availableVersion) return `发现 ${snap.availableVersion}`;
+      if (snap.availableVersion) return t('{version} available', { version: snap.availableVersion });
       if (snap.message) return snap.message;
-      return confirmedCurrent ? '已是最新' : '检查更新';
+      return confirmedCurrent ? t('Up to date') : t('Check for updates');
     default:
-      return '检查更新';
+      return t('Check for updates');
   }
 }
 
@@ -43,9 +48,9 @@ export function sidebarUpdateTitle(snap: AppReleaseSnapshot): string | undefined
     return snap.message;
   }
   if (snap.phase === 'ready' && snap.availableVersion) {
-    return `重启并安装 ${snap.availableVersion}`;
+    return t('Restart and install {version}', { version: snap.availableVersion });
   }
-  if (snap.phase === 'downloading') return '正在下载更新';
+  if (snap.phase === 'downloading') return t('Downloading update');
   return undefined;
 }
 

package/src/lib/attachments.ts

@@ -9,7 +9,8 @@
  *   - BS/browser：File 没有路径，这里把字节读成 base64 走 HTTP 端点落盘。
  * 返回的落盘路径会重写消息正文里的文件引用与图像附件元数据。
  */
-import { getElectronBridge } from './electron-bridge';
+import { t } from '@/i18n';
+import { getHostBridge } from './host-bridge';
 
 export interface AttachmentFile {
   name: string;
@@ -82,7 +83,7 @@ export async function saveChatAttachments(
   files: AttachmentFile[],
 ): Promise<SaveChatAttachmentsResult> {
   if (!chatId || files.length === 0) return { files, failures: [] };
-  const bridge = getElectronBridge();
+  const bridge = getHostBridge();
   if (!bridge?.attachments?.save) return { files, failures: [] };
   try {
     // 有真实路径走 path 拷贝（Electron）；没有则读字节走 data 上传（BS/browser）。
@@ -109,7 +110,7 @@ export async function saveChatAttachments(
         kept.push(file);
         return;
       }
-      failures.push({ name: file.name, error: entry?.error || '上传失败', file });
+      failures.push({ name: file.name, error: entry?.error || t('Upload failed'), file });
     });
     return { files: kept, failures };
   } catch (err) {
@@ -123,13 +124,21 @@ export async function saveChatAttachments(
   }
 }
 
-/** 把失败项拼成一条给用户看的中文提示（供各提交入口复用）。 */
+/** 把失败项拼成一条给用户看的提示（供各提交入口复用）。 */
 export function formatAttachmentFailures(failures: AttachmentSaveFailure[]): string {
   if (failures.length === 0) return '';
-  const detail = failures.map((f) => `${f.name}（${f.error}）`).join('；');
+  const detail = failures
+    .map((f) => t('{name} ({error})', { name: f.name, error: f.error }))
+    .join(t('; '));
   return failures.length === 1
-    ? `文件「${failures[0].name}」未能上传，本条消息未包含它：${failures[0].error}`
-    : `${failures.length} 个文件未能上传，本条消息未包含它们：${detail}`;
+    ? t('File "{name}" failed to upload and is not included in this message: {error}', {
+        name: failures[0].name,
+        error: failures[0].error,
+      })
+    : t('{count} files failed to upload and are not included in this message: {detail}', {
+        count: failures.length,
+        detail,
+      });
 }
 
 /**
@@ -142,8 +151,8 @@ export function appendAttachmentRefs(rawText: string, files: AttachmentFile[]):
   if (files.length === 0) return rawText;
   const refs = files.map((f) => `- \`${f.path}\``).join('\n');
   return rawText
-    ? `${rawText}\n\n---\n关联文件:\n${refs}`
-    : `关联文件:\n${refs}`;
+    ? `${rawText}\n\n---\n${t('Related files:')}\n${refs}`
+    : `${t('Related files:')}\n${refs}`;
 }
 
 /**