@steerable/agent-shell-web 0.6.15

package/src/lib/pending-first-message.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import {
+  setPendingFirstMessage,
+  takePendingFirstMessage,
+} from './pending-first-message';
+
+describe('pending-first-message（首页首条消息接力）', () => {
+  it('按 chatId 取出一次后清空，错配的 chatId 不消费', () => {
+    setPendingFirstMessage({ chatId: 'chat-a', content: '秋天到了，随便聊一句吧。' });
+    expect(takePendingFirstMessage('chat-b')).toBeNull();
+    expect(takePendingFirstMessage('chat-a')).toEqual({
+      chatId: 'chat-a',
+      content: '秋天到了，随便聊一句吧。',
+    });
+    expect(takePendingFirstMessage('chat-a')).toBeNull();
+  });
+});

package/src/lib/pending-first-message.ts

@@ -0,0 +1,36 @@
+/**
+ * 首页输入框 → 新对话首条消息的接力棒。
+ *
+ * EmptyChatGate（无 chatId 的落地页）的输入框提交时，流程是
+ * "先 createChat → 再 navigate → 新 chat 视图挂载后才发得出消息"。
+ * 但 submit 时拿到的文本在 navigate 之后就离开了作用域——react-router 的
+ * location.state 能跨跳转，可 hash 路由 + HMR 下它不够稳（刷新即丢，
+ * 且 AgentChatLoader 的 key 重挂载语义会让读取时机变得微妙）。
+ *
+ * 这里用模块级单例暂存：写入方（EmptyChatGate）在拿到 chatId 后、跳转前
+ * set；消费方（AgentChatView）挂载后 take 一次并自动发送。take 按
+ * chatId 匹配且取出即清，StrictMode 双跑 effect / 重复挂载都不会重发。
+ * 页面刷新后暂存丢失——可接受：刷新发生在流式开始前的话，chat 已经建好，
+ * 用户重发一次即可。
+ */
+
+export interface PendingFirstMessage {
+  chatId: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+let pending: PendingFirstMessage | null = null;
+
+export function setPendingFirstMessage(msg: PendingFirstMessage): void {
+  pending = msg;
+}
+
+export function takePendingFirstMessage(
+  chatId: string,
+): PendingFirstMessage | null {
+  if (!pending || pending.chatId !== chatId) return null;
+  const msg = pending;
+  pending = null;
+  return msg;
+}

package/src/lib/slash-sources.ts

@@ -0,0 +1,191 @@
+/**
+ * Slash sources — the local skills + MCP tools behind every `/` token.
+ *
+ * One source of truth for two surfaces that must agree on "is `/foo` a real
+ * tool?":
+ *   - `ChatInput` — the `/` suggestion menu and the composer's tool chips.
+ *   - `Markdown` — the same chips replayed inside sent message bubbles.
+ *
+ * The catalog is cached at module scope and shared by every subscriber, so a
+ * chat with 50 rendered messages still costs one fetch. `refreshSlashSources`
+ * re-reads it (MCP servers and skills can be added/removed in settings while
+ * a chat is open) and pushes the result to all live subscribers.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import { getPackHiddenSlashSkills } from '../packs/registry';
+import { getElectronBridge, isElectron } from './electron-bridge';
+
+export type SkillItem = {
+  /** Skill directory name (e.g. `70-plan-mode`); absent on hand-built items. */
+  id?: string;
+  name: string;
+  displayName?: string;
+  description: string;
+  isBuiltin?: boolean;
+};
+
+export type McpToolItem = {
+  /** First-class tool name `mcp__<serverKey>__<toolName>`, inserted verbatim. */
+  token: string;
+  toolName: string;
+  serverKey: string;
+  serverName: string;
+  description: string;
+};
+
+export interface SlashSources {
+  skills: SkillItem[];
+  mcpTools: McpToolItem[];
+}
+
+/**
+ * 系统内置的身份/约束/指导类技能：由引擎按条件自动注入系统提示词，不是用户
+ * 手动指定执行的业务技能，因此不进 "/" 菜单，也不渲染成工具卡片。技能名与
+ * 目录名都登记，两种写法都能命中。
+ */
+const HIDDEN_SLASH_SKILLS = new Set([
+  // 助手身份人设底座
+  '00-identity',
+  'identity',
+  // 计划模式约束（由输入框底部的 Agent/Plan 开关专控）
+  '70-plan-mode',
+  'plan-mode',
+  // 工具调用规范
+  '80-tool-usage',
+  'tool-usage',
+  // 零容忍光说不做
+  '81-anti-deferred',
+  'anti-deferred',
+  'anti-deferred-execution',
+  // 零容忍捏造与过时缓存
+  '82-data-grounding',
+  'data-grounding',
+  // 本地命令/文件读写规范
+  '85-local-exec',
+  'local-exec',
+  // 主动编程补位规范
+  '86-proactive-coding',
+  'proactive-coding',
+  // 场景包的隐藏技能由包渲染层声明，
+  // 见 getPackHiddenSlashSkills（0.4 起不再硬编码在这里）。
+]);
+
+/** True for skills the engine injects on its own; they never reach the user. */
+export function isHiddenSlashSkill(skill: SkillItem): boolean {
+  const packHidden = getPackHiddenSlashSkills();
+  return (
+    HIDDEN_SLASH_SKILLS.has(skill.name) ||
+    (skill.id !== undefined && HIDDEN_SLASH_SKILLS.has(skill.id)) ||
+    packHidden.has(skill.name) ||
+    (skill.id !== undefined && packHidden.has(skill.id))
+  );
+}
+
+/**
+ * `/token` occurrences: line start or after whitespace, no inner slash. Keeps
+ * paths (`/mnt/c`), URLs and fractions out — same rule the backend's
+ * `parseUserMessageTriggers` uses to decide what counts as a trigger.
+ */
+export const SLASH_TOKEN_PATTERN = /(?:^|\s)(\/[^\s/]+)/g;
+
+export type SlashToolRef = { type: 'skill' | 'mcp'; id: string; label: string };
+
+/**
+ * Resolve a bare `/` token name to the tool it names, or null when nothing
+ * matches. `mcp__*` resolves even without a catalog entry: the namespace is
+ * unambiguous and the server may be temporarily disconnected.
+ */
+export function resolveSlashTool(
+  name: string,
+  skills: SkillItem[] = [],
+  mcpTools: McpToolItem[] = [],
+): SlashToolRef | null {
+  const key = name.toLowerCase();
+
+  const mcp = mcpTools.find((t) => t.token.toLowerCase() === key);
+  if (mcp) return { type: 'mcp', id: mcp.token, label: name };
+  if (key.startsWith('mcp__')) return { type: 'mcp', id: name, label: name };
+
+  const skill = skills.find(
+    (s) =>
+      s.name.toLowerCase() === key ||
+      (s.displayName !== undefined && s.displayName.toLowerCase() === key),
+  );
+  if (skill && !isHiddenSlashSkill(skill)) {
+    return { type: 'skill', id: skill.name, label: name };
+  }
+  return null;
+}
+
+const EMPTY: SlashSources = { skills: [], mcpTools: [] };
+
+let cached: SlashSources = EMPTY;
+let inflight: Promise<SlashSources> | null = null;
+const listeners = new Set<(sources: SlashSources) => void>();
+
+async function load(): Promise<SlashSources> {
+  const bridge = getElectronBridge();
+  if (!bridge) return cached;
+
+  let skills = cached.skills;
+  let mcpTools = cached.mcpTools;
+
+  try {
+    const res = await bridge.localBackend.request<{ skills: SkillItem[] }>({
+      method: 'GET',
+      path: '/api/v2/chat-agents/skills',
+    });
+    skills = (res.skills || []).filter((s) => !isHiddenSlashSkill(s));
+  } catch (err) {
+    console.error('slash-sources failed to fetch skills:', err);
+  }
+
+  try {
+    const res = await bridge.localBackend.request<{ mcpTools: McpToolItem[] }>({
+      method: 'GET',
+      path: '/api/v2/chat-agents/mcp-tools',
+    });
+    mcpTools = res.mcpTools || [];
+  } catch (err) {
+    // MCP 服务不可用时静默降级——技能候选不受影响
+    console.error('slash-sources failed to fetch MCP tools:', err);
+  }
+
+  cached = { skills, mcpTools };
+  for (const listener of listeners) listener(cached);
+  return cached;
+}
+
+/** Re-read the catalog. Concurrent callers share one in-flight request. */
+export function refreshSlashSources(): Promise<SlashSources> {
+  if (!isElectron()) return Promise.resolve(cached);
+  if (!inflight) {
+    inflight = load().finally(() => {
+      inflight = null;
+    });
+  }
+  return inflight;
+}
+
+/**
+ * Subscribe to the shared catalog. Fetches once on first mount; call
+ * `refresh` when the `/` menu opens so a just-connected MCP server shows up.
+ */
+export function useSlashSources(): SlashSources & {
+  refresh: () => Promise<SlashSources>;
+} {
+  const [sources, setSources] = useState<SlashSources>(cached);
+
+  useEffect(() => {
+    listeners.add(setSources);
+    void refreshSlashSources();
+    return () => {
+      listeners.delete(setSources);
+    };
+  }, []);
+
+  const refresh = useCallback(() => refreshSlashSources(), []);
+
+  return { skills: sources.skills, mcpTools: sources.mcpTools, refresh };
+}

package/src/main.tsx

@@ -0,0 +1,103 @@
+import { StrictMode, lazy, Suspense, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { createHashRouter, RouterProvider } from 'react-router-dom';
+import { AppShell } from './AppShell';
+import { AgentLayout } from './layouts/AgentLayout';
+import { AgentPage } from './pages/AgentPage';
+import { SettingsPage } from './pages/SettingsPage';
+import { getPackRoutes } from './packs/registry';
+import { getBrandLogoUrl, BRAND_NAME } from './brand';
+import './styles/index.css';
+
+// 浏览器 dev mock 的安装在 bootstrap() 开头（动态 import + DEV 门）。
+
+// Dev-only preview harness. Lazy-loaded behind `import.meta.env.DEV` so the
+// chunk vanishes from production builds entirely — Rollup tree-shakes the
+// dynamic import when the condition is statically `false`. The route itself
+// is also conditionally registered; in prod a stray `#/preview/chat` URL
+// falls through to react-router's default "no match" handling (the layout
+// outlet just renders nothing).
+const ChatPanelPreviewPage = import.meta.env.DEV
+  ? lazy(() => import('./pages/ChatPanelPreviewPage'))
+  : null;
+
+// 用 HashRouter 而不是 BrowserRouter：Electron loadFile() 加载本地 index.html
+// 时 URL 是 file://... 没有真正的 server 解析路径段，BrowserRouter 在刷新或
+// 跳转时会 404。HashRouter 把路由放进 # 后面，纯客户端解析，跟 file:// 兼容。
+//
+// 路由分层：
+//   AppShell                 全局顶层 chrome（浏览器预览提示等）
+//     ├─ AgentLayout         带 sidebar 的主界面（终端是它的内嵌面板，不是路由）
+//     │    ├─ /              默认进 AgentPage（无 chatId）
+//     │    ├─ /agent
+//     │    ├─ /agent/:chatId
+//     │    └─ /settings      设置页（智能体 / Skill / MCP / 综合，按 ?section= 分页面）
+//     └─ <包路由>            场景包注册的独立页（如包的调试日志窗）
+/**
+ * web 应用 bootstrap（2.3 起由产品入口调用）。
+ *
+ * shell 本体不装载任何包的渲染层贡献：产品入口
+ * （products/<id>/web/main.tsx）先静态调用包的 register*Renderer()，
+ * 再调本函数——路由注册发生在路由表创建之前。
+ */
+export async function bootstrap(): Promise<void> {
+  if (import.meta.env.DEV) {
+    // 动态 import：prod 构建里 Rollup 把 DEV 分支连同 mock（含其 fixtures）
+    // 整体树摇掉，浏览器 dev mock 数据不进产物。
+    const { installBrowserDevElectronMock } = await import('./lib/browser-dev-electron-mock');
+    installBrowserDevElectronMock();
+  }
+
+  // 标题与 favicon 在 bootstrap 时设置——此刻产品入口已完成包注册
+  // （品牌 logo 由包经 setBrandLogoUrl 注入，见 brand.ts）。
+  document.title = BRAND_NAME;
+  document.querySelector<HTMLLinkElement>('link[rel="icon"]')?.setAttribute('href', getBrandLogoUrl());
+
+  const router = createHashRouter([
+    {
+      path: '/',
+      element: <AppShell />,
+      children: [
+        {
+          element: <AgentLayout />,
+          children: [
+            { index: true, element: <AgentPage /> },
+            { path: 'agent', element: <AgentPage /> },
+            { path: 'agent/:chatId', element: <AgentPage /> },
+            { path: 'settings', element: <SettingsPage /> },
+          ],
+        },
+        ...getPackRoutes().map(({ path, Component }) => ({
+          path,
+          element: <Component />,
+        })),
+        // Dev-only visual harness. Route is omitted entirely in prod builds so
+        // the chunk doesn't ship to end users; `ChatPanelPreviewPage` is
+        // intentionally not exported from any production code path either.
+        ...(ChatPanelPreviewPage
+          ? [
+              {
+                path: 'preview/chat',
+                element: (
+                  <Suspense fallback={(<div>loading preview…</div>) as ReactNode}>
+                    <ChatPanelPreviewPage />
+                  </Suspense>
+                ),
+              },
+            ]
+          : []),
+      ],
+    },
+  ]);
+
+  const rootEl = document.getElementById('root');
+  if (!rootEl) {
+    throw new Error('Missing #root element in index.html');
+  }
+
+  createRoot(rootEl).render(
+    <StrictMode>
+      <RouterProvider router={router} />
+    </StrictMode>,
+  );
+}

package/src/packs/registry.ts

@@ -0,0 +1,64 @@
+/**
+ * 渲染层包注册表（0.3f）—— ScenarioPack.renderer 的 web 侧归宿。
+ *
+ * 包的渲染层代码住在 `packages/pack-<id>/web/`，经产品 web 入口
+ * （products/<id>/web/main.tsx，2.3 起）静态注册——产品编译单元只含
+ * 自己的包，未激活包代码物理上不进 bundle（不再依赖树摇正确性）。
+ *
+ * 槽位：routes / settingsPanels / chatSlots 均有真实包消费者（见各包
+ * 的 web/ 目录）。
+ */
+
+import type {
+  PackChatSlotAutoRevealApi,
+  PackChatSlotContribution,
+  PackChatSlotProps,
+  PackRendererContributions,
+  PackRouteContribution,
+  PackSettingsPanelContribution,
+} from '@steerable/pack-sdk/web';
+
+// 类型单一真源在 @steerable/pack-sdk/web（阶段 2.2）；re-export 兼容既有调用方。
+export type {
+  PackChatSlotAutoRevealApi,
+  PackChatSlotContribution,
+  PackChatSlotProps,
+  PackRendererContributions,
+  PackRouteContribution,
+  PackSettingsPanelContribution,
+};
+
+const routes: PackRouteContribution[] = [];
+const settingsPanels: PackSettingsPanelContribution[] = [];
+const chatSlots: PackChatSlotContribution[] = [];
+const hiddenSlashSkills = new Set<string>();
+const registeredPacks = new Set<string>();
+
+/** 注册一个包的渲染层贡献。重复注册同一包抛错（组装期笔误，fail fast）。 */
+export function registerPackRenderer(packId: string, contributions: PackRendererContributions): void {
+  if (registeredPacks.has(packId)) {
+    throw new Error(`[pack-renderer] duplicate registration for pack: ${packId}`);
+  }
+  registeredPacks.add(packId);
+  routes.push(...(contributions.routes ?? []));
+  settingsPanels.push(...(contributions.settingsPanels ?? []));
+  chatSlots.push(...(contributions.chatSlots ?? []));
+  for (const name of contributions.hiddenSlashSkills ?? []) hiddenSlashSkills.add(name);
+}
+
+export function getPackRoutes(): readonly PackRouteContribution[] {
+  return routes;
+}
+
+export function getPackSettingsPanels(): readonly PackSettingsPanelContribution[] {
+  return settingsPanels;
+}
+
+export function getPackChatSlots(): readonly PackChatSlotContribution[] {
+  return chatSlots;
+}
+
+/** 包贡献的隐藏 slash 技能名集合（bootstrap 完成后稳定，渲染期只读）。 */
+export function getPackHiddenSlashSkills(): ReadonlySet<string> {
+  return hiddenSlashSkills;
+}