cortico 0.1.0

package/src/web/client/console-pages/loader.ts

@@ -0,0 +1,132 @@
+/**
+ * 按 manifest URL 懒加载扩展；进行中的加载去重，成功模块缓存，失败允许重试。
+ * 浏览器仍可能缓存失败的 ESM URL；重新构建后的内容 hash URL 可避开该缓存。
+ * JS 与 CSS URL 均校验清单规定的路径和字符。
+ */
+
+import {
+  isConsoleClientBundle,
+  type ConsoleClientBundle,
+  type ConsolePanel,
+} from '../../shared/client-panel.ts';
+import { isSafeAssetUrl, type ConsoleAssetEntry } from '../../shared/console-protocol.ts';
+import { S } from './strings.ts';
+
+export interface StyleLink {
+  rel: string;
+  href: string;
+  dataset: { [key: string]: string | undefined };
+}
+
+export interface LoaderDeps {
+  importModule(url: string): Promise<unknown>;
+  /** 注入 `<link rel=stylesheet>` 的宿主（一般是 document.head）。 */
+  styleHost: { appendChild(node: unknown): void };
+  createLink(): StyleLink;
+  log?(message: string, detail?: Record<string, unknown>): void;
+}
+
+export class PanelBundleError extends Error {
+  readonly pageId: string;
+  constructor(pageId: string, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'PanelBundleError';
+    this.pageId = pageId;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+export class ConsolePageLoader {
+  private readonly deps: LoaderDeps;
+  private readonly loaded = new Map<string, ConsoleClientBundle>();
+  private readonly inFlight = new Map<string, Promise<ConsoleClientBundle>>();
+  private readonly styled = new Set<string>();
+
+  constructor(deps: LoaderDeps) {
+    this.deps = deps;
+  }
+
+  /** 已加载的扩展集合，供核对懒加载行为。 */
+  get loadedPages(): string[] {
+    return [...this.loaded.keys()];
+  }
+
+  async load(pageId: string, asset: ConsoleAssetEntry | undefined): Promise<ConsoleClientBundle> {
+    const cached = this.loaded.get(pageId);
+    if (cached) return cached;
+
+    const pending = this.inFlight.get(pageId);
+    if (pending) return pending;
+
+    const task = this.loadOnce(pageId, asset);
+    this.inFlight.set(pageId, task);
+    try {
+      const bundle = await task;
+      this.loaded.set(pageId, bundle);
+      return bundle;
+    } finally {
+      // 成功与否都要摘掉:失败不缓存,下次可以重来。
+      this.inFlight.delete(pageId);
+    }
+  }
+
+  private async loadOnce(
+    pageId: string,
+    asset: ConsoleAssetEntry | undefined,
+  ): Promise<ConsoleClientBundle> {
+    if (!asset) {
+      throw new PanelBundleError(pageId, S.noBundle(pageId));
+    }
+    if (!isSafeAssetUrl(asset.js)) {
+      throw new PanelBundleError(pageId, S.badBundleUrl(pageId));
+    }
+    let mod: unknown;
+    try {
+      mod = await this.deps.importModule(asset.js);
+    } catch (err) {
+      throw new PanelBundleError(pageId, S.bundleLoadFailed(pageId, String(err)), err);
+    }
+
+    const candidate = (mod as { default?: unknown } | null)?.default;
+    if (!isConsoleClientBundle(candidate)) {
+      throw new PanelBundleError(pageId, S.badDefaultExport(pageId));
+    }
+    // 样式在 js 装成之后再注入:装不上的页不该在页面里留下一个 404 的 link。
+    this.injectStyle(pageId, asset);
+    return candidate;
+  }
+
+  /** 每页样式只注入一次，面板卸载时保留。 */
+  private injectStyle(pageId: string, asset: ConsoleAssetEntry): void {
+    if (!asset.css || this.styled.has(pageId)) return;
+    if (!isSafeAssetUrl(asset.css)) {
+      this.deps.log?.(`「${pageId}」的样式地址不合法，已跳过`, { href: String(asset.css) });
+      return;
+    }
+    this.styled.add(pageId);
+    const link = this.deps.createLink();
+    link.rel = 'stylesheet';
+    link.href = asset.css;
+    link.dataset.provider = pageId;
+    this.deps.styleHost.appendChild(link);
+  }
+
+  /** 获取声明的面板实现；缺失时错误列出扩展提供的面板键。 */
+  async resolvePanel(
+    pageId: string,
+    panelId: string,
+    asset: ConsoleAssetEntry | undefined,
+  ): Promise<ConsolePanel> {
+    const bundle = await this.load(pageId, asset);
+    const panel = bundle.panels[panelId];
+    // 分别报告键缺失与实现不合法。
+    if (!(panelId in bundle.panels)) {
+      const known = Object.keys(bundle.panels).join(' / ') || S.none;
+      throw new PanelBundleError(pageId, S.noSuchBundlePanel(pageId, panelId, known));
+    }
+    if (!panel || typeof panel.mount !== 'function') {
+      throw new PanelBundleError(pageId, S.badPanelImpl(pageId, panelId));
+    }
+    return panel;
+  }
+}

package/src/web/client/console-pages/strings.ts

@@ -0,0 +1,90 @@
+import { pick } from '../core/language.ts';
+
+const zh = {
+  protocolMismatch: (server: string, page: string) =>
+    `控制台协议版本不一致：服务端 ${server}，页面 ${page}。请强制刷新页面。`,
+  pageFailed: (pageId: string) => `页面「${pageId}」打开失败`,
+  noPage: (pageId: string) => `控制台页面不存在：「${pageId}」`,
+  noPageHint: '请检查页面地址及模块激活状态。',
+  noPanels: (label: string) => `「${label}」没有声明任何面板。`,
+  noSuchPanel: (label: string, wanted: string) => `「${label}」没有面板「${wanted}」`,
+  provides: (list: string) => '可用面板：' + list,
+  panelFailed: (title: string) => `面板「${title}」加载失败`,
+  configEmpty: '配置组不可用。',
+  configTitle: '配置',
+  configDesc: '修改自动保存到 config.json。标注需重启的配置在重启后生效，其余立即生效。',
+  assembly: '装配',
+  notInstalled: "不可用",
+  notActivated: '未激活',
+  hidden: '已隐藏',
+  reloadPrefix: '前缀待重载 · 点此重载',
+  open: '打开',
+  configTab: '配置',
+  promptsTab: '提示词模板',
+  storageTab: '数据',
+  toolsTab: '工具表',
+  storageTitle: '数据',
+  storageDesc: '本页声明的存储项;清除范围与结果由各项的实现决定。',
+  reloadTitle: '重载 system 前缀？',
+  reloadBody: '重读全部前缀源并替换当前 session 的系统前缀，保留已有对话。',
+  prefixReloaded: '前缀已重载',
+  noBundle: (pageId: string) =>
+    `「${pageId}」缺少面板构建产物。仓内页面请先停止 bot，再运行 pnpm build:web；`
+    + 'extensions/ 下的扩展请在包目录构建，再重启进程。',
+  badBundleUrl: (pageId: string) => `「${pageId}」的面板产物地址不合法，已拒绝加载`,
+  bundleLoadFailed: (pageId: string, err: string) => `「${pageId}」的面板产物加载失败: ${err}`,
+  badDefaultExport: (pageId: string) => `「${pageId}」的面板产物缺少有效的 default 导出，格式应为 { panels: { … } }`,
+  none: '(无)',
+  noSuchBundlePanel: (pageId: string, panelId: string, known: string) =>
+    `「${pageId}」的面板产物中没有「${panelId}」。可用面板：${known}`,
+  badPanelImpl: (pageId: string, panelId: string) =>
+    `「${pageId}」的面板「${panelId}」缺少 mount 方法`,
+  noBuiltinPanel: (name: string, known: string) =>
+    `内置面板「${name}」不存在。可用面板：${known}`,
+};
+
+const en: typeof zh = {
+  protocolMismatch: (server: string, page: string) =>
+    `Console protocol version mismatch: server ${server}, this page ${page}.`
+    + ' Force a page refresh.',
+  pageFailed: (pageId: string) => `Could not open "${pageId}"`,
+  noPage: (pageId: string) => `Console page not found: "${pageId}"`,
+  noPageHint: 'Check the page address and module activation status.',
+  noPanels: (label: string) => `"${label}" declares no panels.`,
+  noSuchPanel: (label: string, wanted: string) => `"${label}" has no panel "${wanted}"`,
+  provides: (list: string) => 'Available panels: ' + list,
+  panelFailed: (title: string) => `Panel "${title}" failed to load`,
+  configEmpty: 'Configuration groups unavailable.',
+  configTitle: 'Config',
+  configDesc: 'Changes are saved to config.json automatically. Settings marked as requiring a restart apply after restarting; the rest apply immediately.',
+  assembly: 'Assembly',
+  notInstalled: "Unavailable",
+  notActivated: 'not activated',
+  hidden: 'hidden',
+  reloadPrefix: 'Prefix drifted · click to reload',
+  open: 'Open',
+  configTab: 'Config',
+  promptsTab: 'Prompt templates',
+  storageTab: 'Data',
+  toolsTab: 'Tools',
+  storageTitle: 'Data',
+  storageDesc: 'Storage items declared by this page; what a clear covers and returns is up to each item.',
+  reloadTitle: 'Reload the system prefix?',
+  reloadBody: 'Re-reads all prefix sources and replaces the current session\'s system prefix. Existing conversation messages are kept.',
+  prefixReloaded: 'Prefix reloaded',
+  noBundle: (pageId: string) =>
+    `Panel bundle missing for "${pageId}". For repository pages, stop the bot first, then run pnpm build:web;`
+    + ' for packages under extensions/, build in the package directory and restart the process.',
+  badBundleUrl: (pageId: string) => `Panel bundle URL of "${pageId}" is invalid; refused to load`,
+  bundleLoadFailed: (pageId: string, err: string) => `Panel bundle of "${pageId}" failed to load: ${err}`,
+  badDefaultExport: (pageId: string) => `Panel bundle of "${pageId}" has no valid default export; expected { panels: { … } }`,
+  none: '(none)',
+  noSuchBundlePanel: (pageId: string, panelId: string, known: string) =>
+    `Panel bundle of "${pageId}" has no panel "${panelId}". Available panels: ${known}`,
+  badPanelImpl: (pageId: string, panelId: string) =>
+    `Panel "${panelId}" of "${pageId}" is missing the mount method`,
+  noBuiltinPanel: (name: string, known: string) =>
+    `Built-in panel "${name}" not found. Available panels: ${known}`,
+};
+
+export const S = pick({ zh, en });

package/src/web/client/console-pages/tools/strings.ts

@@ -0,0 +1,49 @@
+import { pick } from '../../core/language.ts';
+
+const zh = {
+  ioGroup: (name: string | undefined) => `IO 工具 · ${name}`,
+  groupCore: '原生动作 · core',
+  groupPersona: '记忆 / 文件工具 · Persona',
+  noDescription: '（未填写工具说明）',
+  paramCount: (n: number) => `${n} 个参数`,
+  paramHeadPath: '参数路径',
+  paramHeadType: '类型',
+  paramHeadConstraint: '约束',
+  paramHeadDesc: '说明',
+  required: '必填',
+  optional: '可选',
+  noParams: '这个工具没有声明参数',
+  copySchema: '复制 schema',
+  fullSchema: '完整 JSON Schema',
+  toolsTitle: '工具库',
+  toolsDesc: '当前提供给模型的工具定义，只读。',
+  toolCount: (n: number) => `${n} 个`,
+  toolsFilter: '筛选工具名或说明…',
+  toolsEmpty: '工具表为空——主循环启动后会在这里出现',
+  loadFailed: (msg: string) => `工具表接口不可用：${msg}`,
+};
+
+const en: typeof zh = {
+  ioGroup: (name: string | undefined) => `IO tools · ${name}`,
+  groupCore: 'Native actions · core',
+  groupPersona: 'Memory / file tools · Persona',
+  noDescription: '(no tool description)',
+  paramCount: (n: number) => `${n} params`,
+  paramHeadPath: 'Path',
+  paramHeadType: 'Type',
+  paramHeadConstraint: 'Constraint',
+  paramHeadDesc: 'Description',
+  required: 'required',
+  optional: 'optional',
+  noParams: 'This tool declares no parameters',
+  copySchema: 'Copy schema',
+  fullSchema: 'Full JSON Schema',
+  toolsTitle: 'Tool library',
+  toolsDesc: 'Current tool definitions provided to the model. Read-only.',
+  toolCount: (n: number) => `${n} tools`,
+  toolsFilter: 'Filter by tool name or description…',
+  toolsEmpty: 'Tool table is empty — it appears here once the main loop starts',
+  loadFailed: (msg: string) => `Tool table endpoint unavailable: ${msg}`,
+};
+
+export const S = pick({ zh, en });

package/src/web/client/console-pages/tools/view.ts

@@ -0,0 +1,215 @@
+/**
+ * 只读工具表与完整 JSON Schema，由 Persona 页的框架页签承载。
+ * 按后端 owner 分组并保留装配顺序，前端不维护具体 World 名单；复制由 ui.copyButton 处理。
+ */
+
+import type { ConsoleUi } from '../../../shared/client-panel.ts';
+import type { ToolSchemaDoc } from '../../features/live/protocol.ts';
+import { S } from './strings.ts';
+
+/** schema 节点的类型名。联合/枚举/组合都给一个能读的词,不返回空。 */
+export function schemaTypeLabel(node: unknown): string {
+  if (!node || typeof node !== 'object') return '—';
+  const n = node as Record<string, unknown>;
+  if (Array.isArray(n.type)) return n.type.join(' | ');
+  if (n.type) return String(n.type);
+  if (n.enum) return 'enum';
+  if (n.oneOf) return 'oneOf';
+  if (n.anyOf) return 'anyOf';
+  if (n.allOf) return 'allOf';
+  return 'schema';
+}
+
+export interface SchemaParamRow {
+  path: string;
+  type: string;
+  required: boolean;
+  description: string;
+}
+
+/** 参数表:递归展开 `properties`,数组元素记成 `x[]`。 */
+export function schemaParameterRows(parameters: unknown): SchemaParamRow[] {
+  const rows: SchemaParamRow[] = [];
+  const walk = (node: unknown, prefix: string): void => {
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    const props = n.properties as Record<string, unknown> | undefined;
+    if (!props) return;
+    const required = new Set(Array.isArray(n.required) ? (n.required as string[]) : []);
+    for (const [name, child] of Object.entries(props)) {
+      const path = prefix ? `${prefix}.${name}` : name;
+      const c = (child ?? {}) as Record<string, unknown>;
+      rows.push({
+        path,
+        type: schemaTypeLabel(child),
+        required: required.has(name),
+        description: typeof c.description === 'string' ? c.description : '',
+      });
+      walk(child, path);
+      if (c.items && typeof c.items === 'object') walk(c.items, `${path}[]`);
+    }
+  };
+  walk(parameters ?? {}, '');
+  return rows;
+}
+
+/** 按 owner 分栏。返回顺序固定:原生动作、Persona、各 World(按出场顺序)。 */
+export function groupTools(
+  schemas: readonly ToolSchemaDoc[],
+): Array<[string, ToolSchemaDoc[]]> {
+  const core: ToolSchemaDoc[] = [];
+  const persona: ToolSchemaDoc[] = [];
+  const worlds = new Map<string, ToolSchemaDoc[]>();
+  for (const t of schemas) {
+    const owner = t.owner ?? ((t.tags ?? []).includes('flow') ? { kind: 'core' } : { kind: 'persona' });
+    if (owner.kind === 'core') {
+      core.push(t);
+      continue;
+    }
+    if (owner.kind !== 'world') {
+      persona.push(t);
+      continue;
+    }
+    const name = S.ioGroup(owner.label || owner.id);
+    const bucket = worlds.get(name);
+    if (bucket) bucket.push(t);
+    else worlds.set(name, [t]);
+  }
+  return [
+    [S.groupCore, core],
+    [S.groupPersona, persona],
+    ...worlds.entries(),
+  ];
+}
+
+/** 卡片与它的可搜文本(筛选时按这一串比对)。 */
+interface CardEntry {
+  el: HTMLElement;
+  haystack: string;
+}
+
+function toolSchemaCard(ui: ConsoleUi, schema: ToolSchemaDoc): CardEntry {
+  const card = ui.h('details', 'tool-schema-card');
+  const summary = ui.h('summary', 'tool-schema-summary');
+  const rows = schemaParameterRows(schema.parameters);
+  summary.append(
+    ui.h('span', 'tool-schema-title', schema.name),
+    ui.h('span', 'tool-schema-short', schema.description || S.noDescription),
+    ui.pill(S.paramCount(rows.length)),
+  );
+  card.appendChild(summary);
+
+  const body = ui.h('div', 'tool-schema-body');
+  const rootDesc = (schema.parameters as { description?: unknown } | null)?.description;
+  if (typeof rootDesc === 'string' && rootDesc !== '') {
+    body.appendChild(ui.h('div', 'schema-root-description', rootDesc));
+  }
+
+  if (rows.length) {
+    const wrap = ui.h('div', 'schema-param-wrap');
+    const table = ui.h('table', 'schema-param-table');
+    const thead = ui.h('thead');
+    const htr = ui.h('tr');
+    for (const t of [S.paramHeadPath, S.paramHeadType, S.paramHeadConstraint, S.paramHeadDesc]) {
+      htr.appendChild(ui.h('th', null, t));
+    }
+    thead.appendChild(htr);
+    const tbody = ui.h('tbody');
+    for (const row of rows) {
+      const tr = ui.h('tr');
+      tr.append(
+        ui.h('td', 'schema-param-path', row.path),
+        ui.h('td', 'schema-param-type', row.type),
+        ui.h('td', 'schema-param-required', row.required ? S.required : S.optional),
+        ui.h('td', 'schema-param-description', row.description || '—'),
+      );
+      tbody.appendChild(tr);
+    }
+    table.append(thead, tbody);
+    wrap.appendChild(table);
+    body.appendChild(wrap);
+  } else {
+    body.appendChild(ui.h('div', 'placeholder schema-empty-params', S.noParams));
+  }
+
+  const raw = ui.h('details', 'schema-raw');
+  const rawText = JSON.stringify(schema, null, 2);
+  const tools = ui.h('div', 'schema-raw-tools');
+  tools.appendChild(ui.copyButton(() => rawText, { label: S.copySchema }));
+  raw.append(ui.h('summary', null, S.fullSchema), tools, ui.h('pre', 'mono', rawText));
+  body.appendChild(raw);
+  card.appendChild(body);
+
+  const haystack = `${schema.name} ${schema.description || ''} ${rows
+    .map((r) => `${r.path} ${r.description}`)
+    .join(' ')}`.toLocaleLowerCase();
+  return { el: card, haystack };
+}
+
+export interface ToolsView {
+  el: HTMLElement;
+  render(schemas: readonly ToolSchemaDoc[]): void;
+  /** 拉不到完整工具表时的说明(仍然把当前主循环的那份画出来) */
+  note(text: string): void;
+}
+
+export function createToolsView(ui: ConsoleUi): ToolsView {
+  const sheet = ui.sheet({
+    title: S.toolsTitle,
+    en: 'tool schemas',
+    desc: S.toolsDesc,
+  });
+  const bar = ui.rowbar();
+  const count = ui.chip(S.toolCount(0));
+  const search = ui.input({
+    type: 'search',
+    placeholder: S.toolsFilter,
+    onInput: (v) => applyFilter(v),
+  });
+  bar.append(count, search);
+  const groups = ui.h('div', 'schema-groups');
+  const noteLine = ui.msgline('');
+  sheet.body.append(bar, noteLine, groups);
+
+  /** 分栏与卡片,筛选时按这两张表逐个开关,不重建 DOM。 */
+  let sections: Array<{ el: HTMLElement; cards: CardEntry[] }> = [];
+
+  function applyFilter(raw: string): void {
+    const q = raw.trim().toLocaleLowerCase();
+    for (const sec of sections) {
+      let any = false;
+      for (const card of sec.cards) {
+        const hit = !q || card.haystack.includes(q);
+        card.el.className = hit ? 'tool-schema-card' : 'tool-schema-card hidden';
+        any = any || hit;
+      }
+      sec.el.className = any ? 'toolgroup schema-group' : 'toolgroup schema-group hidden';
+    }
+  }
+
+  return {
+    el: sheet.el,
+    render(schemas) {
+      while (groups.children.length) groups.children[0].remove();
+      sections = [];
+      count.textContent = S.toolCount(schemas.length);
+      if (!schemas.length) {
+        groups.appendChild(ui.placeholder(S.toolsEmpty));
+        return;
+      }
+      for (const [name, tools] of groupTools(schemas)) {
+        if (!tools.length) continue;
+        const section = ui.h('section', 'toolgroup schema-group');
+        section.appendChild(ui.h('div', 'gt', name));
+        const cards = tools.map((t) => toolSchemaCard(ui, t));
+        for (const c of cards) section.appendChild(c.el);
+        groups.appendChild(section);
+        sections.push({ el: section, cards });
+      }
+      applyFilter(search.value);
+    },
+    note(text) {
+      noteLine.textContent = text;
+    },
+  };
+}

package/src/web/client/core/api.ts

@@ -0,0 +1,200 @@
+/**
+ * 控制台 HTTP 接口；面板通过 ctx.invoke、invokeBinary、pickPath、setConfig 调用。
+ * 请求携带界面语言并接受取消信号；panelRoute 负责 page id 的编码。
+ * 非 2xx 与解析失败抛 ConsoleInvokeError，消息优先使用服务端 error，附带响应片段。
+ * AbortError 原样抛出；空成功响应返回 null，二进制接口返回 Blob。
+ */
+
+import {
+  CONSOLE_MANIFEST_ROUTE,
+  panelRoute,
+  type ConsoleManifest,
+} from '../../shared/console-protocol.ts';
+import { ConsoleInvokeError } from '../../shared/client-panel.ts';
+import type { ConfigValue } from '../../../core/config-schema.ts';
+import {
+  PATH_PICKER_ROUTE,
+  type PathPickerOptions,
+  type PathPickerResponse,
+} from '../../shared/path-picker.ts';
+import { languageHeaders, pick } from './language.ts';
+
+const zh = {
+  httpStatus: (status: number, snippet: string) => `HTTP ${status}：${snippet}`,
+  notJson: (status: number, snippet: string) => `响应不是合法 JSON（HTTP ${status}）：${snippet}`,
+};
+const en: typeof zh = {
+  httpStatus: (status: number, snippet: string) => `HTTP ${status}: ${snippet}`,
+  notJson: (status: number, snippet: string) => `Response is not valid JSON (HTTP ${status}): ${snippet}`,
+};
+const S = pick({ zh, en });
+
+/** 所有请求都接受一个取消信号；面板一律传 `ctx.signal`。 */
+export interface RequestOptions {
+  signal?: AbortSignal;
+  keepalive?: boolean;
+}
+
+/** 错误消息附带的响应片段长度上限。 */
+const SNIPPET_MAX = 200;
+
+function snippet(text: string): string {
+  const s = text.trim();
+  return s.length > SNIPPET_MAX ? `${s.slice(0, SNIPPET_MAX)}…` : s;
+}
+
+/** 按 name 识别 AbortError，兼容跨 realm 异常。 */
+function isAbortError(err: unknown): boolean {
+  return (err as { name?: unknown } | null)?.name === 'AbortError';
+}
+
+/** 把任意异常收敛成 `ConsoleInvokeError`；abort 与已经归一化过的原样放行。 */
+function normalizeError(err: unknown, status: number): never {
+  if (isAbortError(err)) throw err;
+  if (err instanceof ConsoleInvokeError) throw err;
+  throw new ConsoleInvokeError(String(err), status);
+}
+
+async function send(path: string, init: RequestInit, opts?: RequestOptions): Promise<Response> {
+  try {
+    return await fetch(path, {
+      ...init,
+      headers: { ...languageHeaders(), ...(init.headers as Record<string, string> | undefined) },
+      ...(opts?.signal ? { signal: opts.signal } : {}),
+      ...(opts?.keepalive ? { keepalive: true } : {}),
+    });
+  } catch (err) {
+    // fetch reject = 网络层没走到 HTTP，没有状态码可言，记 0。
+    normalizeError(err, 0);
+  }
+}
+
+/** 读取响应体也可能抛出 AbortError，原样传递。 */
+async function readText(res: Response): Promise<string> {
+  try {
+    return await res.text();
+  } catch (err) {
+    normalizeError(err, res.status);
+  }
+}
+
+/** 非 2xx 的统一出口：优先服务端措辞，其次 `HTTP <status>`（带响应片段）。 */
+async function throwHttpError(res: Response): Promise<never> {
+  const text = await readText(res);
+  let message = `HTTP ${res.status}`;
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown } | null;
+    const err = parsed?.error;
+    if (typeof err === 'string' && err !== '') message = err;
+  } catch {
+    if (text.trim() !== '') message = S.httpStatus(res.status, snippet(text));
+  }
+  throw new ConsoleInvokeError(message, res.status);
+}
+
+/** 成功响应解析为 JSON；204 或空正文返回 null，解析失败抛 ConsoleInvokeError。 */
+async function readJson<T>(res: Response): Promise<T> {
+  if (!res.ok) await throwHttpError(res);
+  if (res.status === 204) return null as T;
+  const text = await readText(res);
+  if (text.trim() === '') return null as T;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new ConsoleInvokeError(S.notJson(res.status, snippet(text)), res.status);
+  }
+}
+
+async function readBlob(res: Response): Promise<Blob> {
+  if (!res.ok) await throwHttpError(res);
+  try {
+    return await res.blob();
+  } catch (err) {
+    normalizeError(err, res.status);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 通用动词
+// ---------------------------------------------------------------------------
+
+export async function get<T>(path: string, opts?: RequestOptions): Promise<T> {
+  return readJson<T>(await send(path, { method: 'GET' }, opts));
+}
+
+/**
+ * `post` 只负责序列化传进来的 body —— `{ args }` 这个形状是 panel RPC 的约定，
+ * 由 `invokePanel` 负责，不在这里硬编码。
+ */
+export async function post<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+  const init: RequestInit = {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+  };
+  return readJson<T>(await send(path, init, opts));
+}
+
+/** 上传二进制正文。 */
+export async function postBlob<T>(
+  path: string,
+  body: Blob,
+  opts?: RequestOptions,
+): Promise<T> {
+  return readJson<T>(await send(path, {
+    method: 'POST',
+    headers: { 'Content-Type': body.type || 'application/octet-stream' },
+    body,
+  }, opts));
+}
+
+/** 打开运行 WebApp 的主机上的本机路径选择器。 */
+export async function pickPath(options: PathPickerOptions, opts?: RequestOptions): Promise<string | null> {
+  const response = await post<PathPickerResponse>(PATH_PICKER_ROUTE, options, opts);
+  return response.path;
+}
+
+/** 控制台页面板写配置的窄入口；服务端仍按组 schema 校验。 */
+export async function setConfig(
+  groupId: string,
+  values: Record<string, ConfigValue>,
+  opts?: RequestOptions,
+): Promise<string> {
+  const response = await post<{ result?: string }>('/api/config', { group: groupId, values }, opts);
+  return response.result || groupId;
+}
+
+// ---------------------------------------------------------------------------
+// Console 协议
+// ---------------------------------------------------------------------------
+
+export async function fetchManifest(opts?: RequestOptions): Promise<ConsoleManifest> {
+  return get<ConsoleManifest>(CONSOLE_MANIFEST_ROUTE, opts);
+}
+
+/** 面板数据面调用。走 POST，body 形如 `{"args":[...]}`。 */
+export async function invokePanel<T>(
+  pageId: string,
+  panelId: string,
+  method: string,
+  args?: unknown[],
+  opts?: RequestOptions,
+): Promise<T> {
+  return post<T>(panelRoute(pageId, panelId, method), { args: args ?? [] }, opts);
+}
+
+/** 同上，但按二进制取回（音频试听、图片这类）。 */
+export async function invokePanelBinary(
+  pageId: string,
+  panelId: string,
+  method: string,
+  args?: unknown[],
+  opts?: RequestOptions,
+): Promise<Blob> {
+  const init: RequestInit = {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ args: args ?? [] }),
+  };
+  return readBlob(await send(panelRoute(pageId, panelId, method), init, opts));
+}