@pi-harness/pi-harness 0.1.2 → 0.1.3

package/packages/client-web/src/design-contract.ts

@@ -1,9 +1,69 @@
-export interface DesignWorkspace { readonly path: string; readonly sessions: string; readonly live: boolean; readonly branch: string; readonly dirty: string; }
-export interface DesignSession { readonly id: string; readonly title: string; readonly meta: string; readonly state: "running" | "ok" | "warn" | "error"; readonly group: "今天" | "昨天" | "更早"; readonly ws: string; }
-export interface DesignTurn { readonly kind: "user" | "reasoning" | "plugin" | "tool" | "text" | "approval" | "subagent" | "todo" | "stats"; readonly text?: string; readonly name?: string; readonly hook?: string; readonly target?: string; readonly output?: string; readonly dur?: string; readonly stat?: string; readonly statFg?: string; readonly glyph?: string; readonly isDiff?: boolean; readonly diff?: readonly { no: string; sign: string; text: string }[]; readonly preset?: string; readonly goal?: string; readonly lineage?: string; readonly steps?: readonly { tool: string; target: string; dur: string }[]; readonly verdict?: string; readonly progress?: string; readonly todos?: readonly { text: string; done: boolean }[]; readonly stats?: readonly string[]; }
-export interface DesignEvent { readonly ts: string; readonly source: string; readonly summary: string; readonly by: string; readonly dur: string; }
-export interface DesignPlugin { readonly name: string; readonly ver: string; readonly capability: string; readonly on: boolean; readonly update: boolean; readonly local?: boolean; readonly desc: string; readonly hooks: readonly string[]; }
-export interface DesignProvider { readonly id: string; readonly name: string; readonly state: string; readonly ok: boolean; readonly protocol: "openai" | "anthropic"; readonly baseUrl: string; readonly key: string; readonly models: readonly string[]; readonly latency: string; readonly by: string; }
+export interface DesignWorkspace {
+  readonly path: string;
+  readonly sessions: string;
+  readonly live: boolean;
+  readonly branch: string;
+  readonly dirty: string;
+}
+export interface DesignSession {
+  readonly id: string;
+  readonly title: string;
+  readonly meta: string;
+  readonly state: "running" | "ok" | "warn" | "error";
+  readonly group: "今天" | "昨天" | "更早";
+  readonly ws: string;
+}
+export interface DesignTurn {
+  readonly kind: "user" | "reasoning" | "plugin" | "tool" | "text" | "approval" | "subagent" | "todo" | "stats";
+  readonly text?: string;
+  readonly name?: string;
+  readonly hook?: string;
+  readonly target?: string;
+  readonly output?: string;
+  readonly dur?: string;
+  readonly stat?: string;
+  readonly statFg?: string;
+  readonly glyph?: string;
+  readonly isDiff?: boolean;
+  readonly diff?: readonly { no: string; sign: string; text: string }[];
+  readonly preset?: string;
+  readonly goal?: string;
+  readonly lineage?: string;
+  readonly steps?: readonly { tool: string; target: string; dur: string }[];
+  readonly verdict?: string;
+  readonly progress?: string;
+  readonly todos?: readonly { text: string; done: boolean }[];
+  readonly stats?: readonly string[];
+}
+export interface DesignEvent {
+  readonly ts: string;
+  readonly source: string;
+  readonly summary: string;
+  readonly by: string;
+  readonly dur: string;
+}
+export interface DesignPlugin {
+  readonly name: string;
+  readonly ver: string;
+  readonly capability: string;
+  readonly on: boolean;
+  readonly update: boolean;
+  readonly local?: boolean;
+  readonly desc: string;
+  readonly hooks: readonly string[];
+}
+export interface DesignProvider {
+  readonly id: string;
+  readonly name: string;
+  readonly state: string;
+  readonly ok: boolean;
+  readonly protocol: "openai" | "anthropic";
+  readonly baseUrl: string;
+  readonly key: string;
+  readonly models: readonly string[];
+  readonly latency: string;
+  readonly by: string;
+}
 
 export const DESIGN_WORKSPACES: readonly DesignWorkspace[] = [
   { path: "~/work/checkout-svc", sessions: "6", live: true, branch: "fix/3ds-timeout", dirty: "4 处未提交" },
@@ -24,16 +84,92 @@ export const DESIGN_TURNS: readonly DesignTurn[] = [
   { kind: "user", text: "支付成功率从昨天上线后掉了很多，日志里全是 3DS challenge timeout。定位一下，能改就直接改，改完跑测试。" },
   { kind: "reasoning", dur: "6s", text: "先找超时配置在哪定义，再看是不是 2.4.0 版本引入的默认值变化。优先只读检索，确认后再动代码。" },
   { kind: "plugin", name: "context-repo-map", hook: "context_provider", text: "注入仓库地图与最近 3 次提交摘要（1,842 tok）" },
-  { kind: "tool", glyph: "⌕", name: "grep", target: "\"3DS\" src/**/*.ts", dur: "0.4s", stat: "12 命中", statFg: "#61666B", output: "src/payment/threeds.ts:41  const CHALLENGE_TIMEOUT_MS = 8_000\nsrc/payment/threeds.ts:88  if (elapsed > CHALLENGE_TIMEOUT_MS) throw new ChallengeTimeout\nsrc/payment/gateway.ts:114  retries: 0\ntest/payment/threeds.spec.ts:23  vi.advanceTimersByTime(8_100)" },
-  { kind: "tool", glyph: "▤", name: "read", target: "src/payment/threeds.ts:30-96", dur: "0.1s", stat: "66 行", statFg: "#61666B", output: "const CHALLENGE_TIMEOUT_MS = 8_000\n\nexport async function runChallenge(ctx: Ctx) {\n  const started = now()\n  const res = await sdk.challenge(ctx.token)   // sdk 2.4.0\n  const elapsed = now() - started\n  if (elapsed > CHALLENGE_TIMEOUT_MS) throw new ChallengeTimeout()\n  return res\n}" },
-  { kind: "text", text: "原因找到了：sdk 2.4.0 起 iOS 端 challenge 平均耗时从 3.1s 涨到 9.4s，而我们的超时仍是 8s，且 retries 为 0，一次超时就直接失败。\n\n我按两处改：超时放宽到 20s，并加一次带抖动的重试。" },
-  { kind: "tool", glyph: "✎", name: "edit", target: "src/payment/threeds.ts", dur: "0.2s", stat: "+9 −2", statFg: "#22C55E", isDiff: true, diff: [{ no: "41", sign: "-", text: "const CHALLENGE_TIMEOUT_MS = 8_000" }, { no: "41", sign: "+", text: "const CHALLENGE_TIMEOUT_MS = 20_000" }, { no: "42", sign: "+", text: "const CHALLENGE_MAX_ATTEMPTS = 2" }, { no: "86", sign: "-", text: "  const res = await sdk.challenge(ctx.token)" }, { no: "86", sign: "+", text: "  const res = await withRetry(CHALLENGE_MAX_ATTEMPTS, () =>" }, { no: "87", sign: "+", text: "    sdk.challenge(ctx.token), { jitter: true })" }] },
+  {
+    kind: "tool",
+    glyph: "⌕",
+    name: "grep",
+    target: '"3DS" src/**/*.ts',
+    dur: "0.4s",
+    stat: "12 命中",
+    statFg: "#61666B",
+    output:
+      "src/payment/threeds.ts:41  const CHALLENGE_TIMEOUT_MS = 8_000\nsrc/payment/threeds.ts:88  if (elapsed > CHALLENGE_TIMEOUT_MS) throw new ChallengeTimeout\nsrc/payment/gateway.ts:114  retries: 0\ntest/payment/threeds.spec.ts:23  vi.advanceTimersByTime(8_100)",
+  },
+  {
+    kind: "tool",
+    glyph: "▤",
+    name: "read",
+    target: "src/payment/threeds.ts:30-96",
+    dur: "0.1s",
+    stat: "66 行",
+    statFg: "#61666B",
+    output:
+      "const CHALLENGE_TIMEOUT_MS = 8_000\n\nexport async function runChallenge(ctx: Ctx) {\n  const started = now()\n  const res = await sdk.challenge(ctx.token)   // sdk 2.4.0\n  const elapsed = now() - started\n  if (elapsed > CHALLENGE_TIMEOUT_MS) throw new ChallengeTimeout()\n  return res\n}",
+  },
+  {
+    kind: "text",
+    text: "原因找到了：sdk 2.4.0 起 iOS 端 challenge 平均耗时从 3.1s 涨到 9.4s，而我们的超时仍是 8s，且 retries 为 0，一次超时就直接失败。\n\n我按两处改：超时放宽到 20s，并加一次带抖动的重试。",
+  },
+  {
+    kind: "tool",
+    glyph: "✎",
+    name: "edit",
+    target: "src/payment/threeds.ts",
+    dur: "0.2s",
+    stat: "+9 −2",
+    statFg: "#22C55E",
+    isDiff: true,
+    diff: [
+      { no: "41", sign: "-", text: "const CHALLENGE_TIMEOUT_MS = 8_000" },
+      { no: "41", sign: "+", text: "const CHALLENGE_TIMEOUT_MS = 20_000" },
+      { no: "42", sign: "+", text: "const CHALLENGE_MAX_ATTEMPTS = 2" },
+      { no: "86", sign: "-", text: "  const res = await sdk.challenge(ctx.token)" },
+      { no: "86", sign: "+", text: "  const res = await withRetry(CHALLENGE_MAX_ATTEMPTS, () =>" },
+      { no: "87", sign: "+", text: "    sdk.challenge(ctx.token), { jitter: true })" },
+    ],
+  },
   { kind: "plugin", name: "guard-secret-scan", hook: "before_write", text: "改动无凭据外泄风险，放行" },
   { kind: "approval", name: "bash — pnpm vitest run test/payment", text: "cd ~/work/checkout-svc && pnpm vitest run test/payment --reporter=dot" },
-  { kind: "tool", glyph: "$", name: "bash", target: "pnpm vitest run test/payment", dur: "12.4s", stat: "exit 0", statFg: "#22C55E", output: "···········\n Test Files  3 passed (3)\n      Tests  27 passed (27)\n   Duration  11.8s\n\n✓ threeds.spec.ts (9)\n✓ gateway.spec.ts (12)\n✓ webhook.spec.ts (6)" },
-  { kind: "subagent", name: "reviewer", preset: "read-only", goal: "复核 threeds.ts 的改动是否引入回归", dur: "8.1s", lineage: "session #s1 › turn 6 › subagent reviewer（继承 workspace，权限降级为只读）", steps: [{ tool: "read", target: "src/payment/threeds.ts", dur: "0.1s" }, { tool: "read", target: "src/payment/with-retry.ts", dur: "0.1s" }, { tool: "grep", target: "\"CHALLENGE_TIMEOUT_MS\" test/**", dur: "0.3s" }], verdict: "改动本身正确。两点提醒：test/payment/threeds.spec.ts:23 仍按 8s 断言，会在下次改动时误报通过；withRetry 的抖动上限没设，最坏情况下总耗时可能到 44s，建议加 maxTotalMs。" },
-  { kind: "todo", progress: "3 / 4", todos: [{ text: "定位超时来源", done: true }, { text: "放宽超时并加重试", done: true }, { text: "跑 payment 相关测试", done: true }, { text: "补一条针对 20s 边界的回归用例", done: false }] },
-  { kind: "text", text: "测试全绿。还剩一条回归用例没补：现有 spec 里 `advanceTimersByTime(8_100)` 断言的是旧阈值，需要改成 20s 边界并新增一条「首次超时后重试成功」的用例。要我继续补吗？" },
+  {
+    kind: "tool",
+    glyph: "$",
+    name: "bash",
+    target: "pnpm vitest run test/payment",
+    dur: "12.4s",
+    stat: "exit 0",
+    statFg: "#22C55E",
+    output:
+      "···········\n Test Files  3 passed (3)\n      Tests  27 passed (27)\n   Duration  11.8s\n\n✓ threeds.spec.ts (9)\n✓ gateway.spec.ts (12)\n✓ webhook.spec.ts (6)",
+  },
+  {
+    kind: "subagent",
+    name: "reviewer",
+    preset: "read-only",
+    goal: "复核 threeds.ts 的改动是否引入回归",
+    dur: "8.1s",
+    lineage: "session #s1 › turn 6 › subagent reviewer（继承 workspace，权限降级为只读）",
+    steps: [
+      { tool: "read", target: "src/payment/threeds.ts", dur: "0.1s" },
+      { tool: "read", target: "src/payment/with-retry.ts", dur: "0.1s" },
+      { tool: "grep", target: '"CHALLENGE_TIMEOUT_MS" test/**', dur: "0.3s" },
+    ],
+    verdict:
+      "改动本身正确。两点提醒：test/payment/threeds.spec.ts:23 仍按 8s 断言，会在下次改动时误报通过；withRetry 的抖动上限没设，最坏情况下总耗时可能到 44s，建议加 maxTotalMs。",
+  },
+  {
+    kind: "todo",
+    progress: "3 / 4",
+    todos: [
+      { text: "定位超时来源", done: true },
+      { text: "放宽超时并加重试", done: true },
+      { text: "跑 payment 相关测试", done: true },
+      { text: "补一条针对 20s 边界的回归用例", done: false },
+    ],
+  },
+  {
+    kind: "text",
+    text: "测试全绿。还剩一条回归用例没补：现有 spec 里 `advanceTimersByTime(8_100)` 断言的是旧阈值，需要改成 20s 边界并新增一条「首次超时后重试成功」的用例。要我继续补吗？",
+  },
   { kind: "stats", stats: ["输入 34.2k tok", "缓存命中 61%", "输出 4.8k tok", "用时 1m 42s", "$0.28"] },
 ];
 
@@ -42,7 +178,7 @@ export const DESIGN_EVENTS: readonly DesignEvent[] = [
   { ts: "02:14:01", source: "context_injection", summary: "注入仓库地图与最近提交（1,842 tok）", by: "context-repo-map", dur: "88ms" },
   { ts: "02:14:02", source: "user_message", summary: "支付成功率下降，定位并修复", by: "用户", dur: "—" },
   { ts: "02:14:03", source: "reasoning", summary: "先只读检索超时配置，再判断是否与 sdk 版本相关", by: "ds-coder-v3", dur: "6.0s" },
-  { ts: "02:14:09", source: "tool_call", summary: "grep \"3DS\" src/**/*.ts", by: "内置", dur: "0.4s" },
+  { ts: "02:14:09", source: "tool_call", summary: 'grep "3DS" src/**/*.ts', by: "内置", dur: "0.4s" },
   { ts: "02:14:10", source: "tool_result", summary: "12 命中，定位 threeds.ts:41", by: "内置", dur: "—" },
   { ts: "02:14:11", source: "tool_call", summary: "read src/payment/threeds.ts:30-96", by: "内置", dur: "0.1s" },
   { ts: "02:14:14", source: "tool_call", summary: "edit src/payment/threeds.ts (+9 −2)", by: "内置", dur: "0.2s" },
@@ -55,19 +191,106 @@ export const DESIGN_EVENTS: readonly DesignEvent[] = [
 ];
 
 export const DESIGN_PLUGINS: readonly DesignPlugin[] = [
-  { name: "context-repo-map", ver: "1.4.2", capability: "上下文", on: true, update: false, desc: "把仓库结构、入口文件与最近提交压缩成上下文，超预算时自动裁剪", hooks: ["context_provider", "before_step"] },
-  { name: "guard-secret-scan", ver: "2.0.1", capability: "策略", on: true, update: true, desc: "写入与提交前扫描凭据、私钥、token，命中即拦截并说明位置", hooks: ["before_write", "before_commit"] },
-  { name: "subagent-review", ver: "0.8.5", capability: "子代理", on: true, update: false, desc: "改动落盘后派生只读 reviewer 子代理复核 diff，产出可执行意见", hooks: ["after_write"] },
-  { name: "sandbox-landlock", ver: "1.1.0", capability: "沙箱", on: true, update: false, desc: "Linux Landlock 限制子进程可写路径与出网，越权直接拒绝", hooks: ["shell_exec"] },
-  { name: "model-deepseek", ver: "3.2.0", capability: "模型", on: true, update: true, desc: "DeepSeek 官方模型路由，支持 prompt 缓存与推理内容透传", hooks: ["model_provider"] },
-  { name: "store-sqlite", ver: "1.0.7", capability: "存储", on: true, update: false, desc: "会话事件流落地到本地 SQLite，支持 resume、fork、replay", hooks: ["session_store"] },
-  { name: "vision-handoff", ver: "path", capability: "上下文", on: true, update: false, local: true, desc: "图片交给独立视觉模型描述后回填上下文，从本地路径加载（../pi-pkg-vision-handoff）", hooks: ["context_provider"] },
-  { name: "notify-webhook", ver: "0.3.1", capability: "通知", on: false, update: false, desc: "任务结束或需要确认时推送到自定义 webhook", hooks: ["after_turn"] },
+  {
+    name: "context-repo-map",
+    ver: "1.4.2",
+    capability: "上下文",
+    on: true,
+    update: false,
+    desc: "把仓库结构、入口文件与最近提交压缩成上下文，超预算时自动裁剪",
+    hooks: ["context_provider", "before_step"],
+  },
+  {
+    name: "guard-secret-scan",
+    ver: "2.0.1",
+    capability: "策略",
+    on: true,
+    update: true,
+    desc: "写入与提交前扫描凭据、私钥、token，命中即拦截并说明位置",
+    hooks: ["before_write", "before_commit"],
+  },
+  {
+    name: "subagent-review",
+    ver: "0.8.5",
+    capability: "子代理",
+    on: true,
+    update: false,
+    desc: "改动落盘后派生只读 reviewer 子代理复核 diff，产出可执行意见",
+    hooks: ["after_write"],
+  },
+  {
+    name: "sandbox-landlock",
+    ver: "1.1.0",
+    capability: "沙箱",
+    on: true,
+    update: false,
+    desc: "Linux Landlock 限制子进程可写路径与出网，越权直接拒绝",
+    hooks: ["shell_exec"],
+  },
+  {
+    name: "model-deepseek",
+    ver: "3.2.0",
+    capability: "模型",
+    on: true,
+    update: true,
+    desc: "DeepSeek 官方模型路由，支持 prompt 缓存与推理内容透传",
+    hooks: ["model_provider"],
+  },
+  {
+    name: "store-sqlite",
+    ver: "1.0.7",
+    capability: "存储",
+    on: true,
+    update: false,
+    desc: "会话事件流落地到本地 SQLite，支持 resume、fork、replay",
+    hooks: ["session_store"],
+  },
+  {
+    name: "vision-handoff",
+    ver: "path",
+    capability: "上下文",
+    on: true,
+    update: false,
+    local: true,
+    desc: "图片交给独立视觉模型描述后回填上下文，从本地路径加载（../pi-pkg-vision-handoff）",
+    hooks: ["context_provider"],
+  },
+  {
+    name: "notify-webhook",
+    ver: "0.3.1",
+    capability: "通知",
+    on: false,
+    update: false,
+    desc: "任务结束或需要确认时推送到自定义 webhook",
+    hooks: ["after_turn"],
+  },
 ];
 
 export const DESIGN_PROVIDERS: readonly DesignProvider[] = [
-  { id: "deepseek", name: "DeepSeek", state: "已连接", ok: true, protocol: "openai", baseUrl: "https://api.deepseek.com/v1", key: "sk-••••••••••••••••7f3a", models: ["ds-coder-v3", "ds-chat", "ds-reasoner"], latency: "41ms", by: "model-deepseek" },
-  { id: "anthropic", name: "Anthropic", state: "已连接", ok: true, protocol: "anthropic", baseUrl: "https://api.anthropic.com", key: "sk-ant-••••••••••2c91", models: ["claude-sonnet", "claude-haiku"], latency: "128ms", by: "model-anthropic" },
+  {
+    id: "deepseek",
+    name: "DeepSeek",
+    state: "已连接",
+    ok: true,
+    protocol: "openai",
+    baseUrl: "https://api.deepseek.com/v1",
+    key: "sk-••••••••••••••••7f3a",
+    models: ["ds-coder-v3", "ds-chat", "ds-reasoner"],
+    latency: "41ms",
+    by: "model-deepseek",
+  },
+  {
+    id: "anthropic",
+    name: "Anthropic",
+    state: "已连接",
+    ok: true,
+    protocol: "anthropic",
+    baseUrl: "https://api.anthropic.com",
+    key: "sk-ant-••••••••••2c91",
+    models: ["claude-sonnet", "claude-haiku"],
+    latency: "128ms",
+    by: "model-anthropic",
+  },
 ];
 
 export const DESIGN_TOML = `# ~/.config/pi/pi.toml
@@ -109,4 +332,3 @@ palette   = "cmd+k"
 settings  = "cmd+,"
 interrupt = "ctrl+c"
 `;
-

package/packages/client-web/src/index.ts

@@ -4,18 +4,31 @@ import { Context } from "@deepseek-ai/cordis";
 import { ControlRoomView } from "./react-room.js";
 import { createClientApi, type ClientApi } from "./control-room.js";
 
-declare module "@deepseek-ai/cordis" { interface Context { clientRoot: HTMLElement; clientApi: ClientApi; } }
+declare module "@deepseek-ai/cordis" {
+  interface Context {
+    clientRoot: HTMLElement;
+    clientApi: ClientApi;
+  }
+}
 
 export class AppWebEntry {
   readonly context: Context;
   readonly root: HTMLElement;
+  readonly version?: string;
   #reactRoot?: Root;
-  constructor(root: HTMLElement) { this.root = root; this.context = new Context(); }
+  constructor(root: HTMLElement, options: { readonly version?: string } = {}) {
+    this.root = root;
+    this.version = options.version;
+    this.context = new Context();
+  }
   run(): void {
     this.context.provide("clientRoot", this.root);
     this.context.provide("clientApi", createClientApi());
     this.#reactRoot = createRoot(this.root);
-    this.#reactRoot.render(createElement(ControlRoomView, { api: this.context.clientApi }));
+    this.#reactRoot.render(createElement(ControlRoomView, { api: this.context.clientApi, appVersion: this.version }));
+  }
+  async dispose(): Promise<void> {
+    this.#reactRoot?.unmount();
+    await this.context.fiber.dispose();
   }
-  async dispose(): Promise<void> { this.#reactRoot?.unmount(); await this.context.fiber.dispose(); }
 }

package/packages/client-web/src/markdown.tsx

@@ -0,0 +1,22 @@
+import createDOMPurify from "dompurify";
+import { marked } from "marked";
+
+const markdownOptions = { gfm: true, breaks: true } as const;
+const purifier = typeof window === "undefined" ? undefined : createDOMPurify(window);
+
+function renderMarkdown(source: string): string {
+  const html = marked.parse(source, markdownOptions);
+  if (typeof html !== "string") return "";
+  return (
+    purifier?.sanitize(html, {
+      USE_PROFILES: { html: true },
+      ALLOWED_TAGS: ["a", "blockquote", "br", "code", "del", "em", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "li", "ol", "p", "pre", "strong", "ul"],
+      ALLOWED_ATTR: ["href", "rel", "target"],
+      FORBID_ATTR: ["style", "class", "id"],
+    }) ?? ""
+  );
+}
+
+export function MarkdownMessage({ text, onMouseUp }: { text: string; onMouseUp?: () => void }) {
+  return <div className="turn-markdown" dangerouslySetInnerHTML={{ __html: renderMarkdown(text) }} onMouseUp={onMouseUp} />;
+}

package/packages/client-web/src/marketplace-catalog.ts

@@ -0,0 +1,10 @@
+import type { ClientApi, ClientMarketplacePlugin } from "./control-room.js";
+
+export const loadMarketplaceCatalog = async (api: Pick<ClientApi, "listMarketplace">): Promise<readonly ClientMarketplacePlugin[]> => {
+  const items: ClientMarketplacePlugin[] = [];
+  for (let page = 0; ; page += 1) {
+    const result = await api.listMarketplace("", "", page, 100);
+    items.push(...result.items);
+    if (!result.hasNext || result.items.length === 0 || items.length >= result.total) return items;
+  }
+};

package/packages/client-web/src/marketplace-navigation.ts

@@ -0,0 +1,46 @@
+export function marketplaceDetailPath(id: string): string {
+  return `?page=marketplace&plugin=${encodeURIComponent(id)}`;
+}
+
+export function readMarketplaceDetailId(params: URLSearchParams): string | undefined {
+  if (params.get("page") !== "marketplace") return undefined;
+  const id = params.get("plugin")?.trim();
+  return id || undefined;
+}
+
+export interface MarketplaceCategoryTab {
+  readonly id: string;
+  readonly label: string;
+  readonly count: number;
+}
+
+export function marketplaceCategoryTabs(categories: readonly MarketplaceCategoryTab[]): readonly MarketplaceCategoryTab[] {
+  const total = categories.reduce((sum, category) => sum + category.count, 0);
+  return [{ id: "", label: "全部", count: total }, ...categories];
+}
+
+export interface MarketplaceStatisticsInput {
+  readonly downloads30d?: number;
+  readonly quality?: number;
+  readonly updatedAt?: string;
+}
+
+export interface MarketplaceStatisticItem {
+  readonly label: string;
+  readonly value: string;
+}
+
+function compactDownloadCount(value: number): string {
+  if (value >= 10_000) return `${(value / 10_000).toFixed(1).replace(/\.0$/, "")} 万`;
+  return new Intl.NumberFormat("zh-CN").format(value);
+}
+
+export function marketplaceStatisticItems(statistics: MarketplaceStatisticsInput | undefined): readonly MarketplaceStatisticItem[] {
+  if (statistics === undefined) return [];
+  const items: MarketplaceStatisticItem[] = [];
+  if (statistics.downloads30d !== undefined) items.push({ label: "近 30 天下载量", value: compactDownloadCount(statistics.downloads30d) });
+  if (statistics.quality !== undefined) items.push({ label: "npm 质量分", value: String(Math.round(statistics.quality * 100)) });
+  if (statistics.updatedAt !== undefined && Number.isFinite(Date.parse(statistics.updatedAt)))
+    items.push({ label: "npm 更新时间", value: statistics.updatedAt.slice(0, 10) });
+  return items;
+}

package/packages/client-web/src/message-content.ts

@@ -0,0 +1,51 @@
+export function messageText(message: Record<string, unknown>): string {
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (typeof part === "string") return part;
+      if (typeof part !== "object" || part === null) return "";
+      const typedPart = part as { type?: unknown; text?: unknown };
+      return (typedPart.type === undefined || typedPart.type === "text") && typeof typedPart.text === "string" ? typedPart.text : "";
+    })
+    .join("");
+}
+
+export function messageThinking(message: Record<string, unknown>): string {
+  const content = message.content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (typeof part !== "object" || part === null) return "";
+      const typedPart = part as { type?: unknown; thinking?: unknown };
+      return typedPart.type === "thinking" && typeof typedPart.thinking === "string" ? typedPart.thinking : "";
+    })
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export interface ChatTurn {
+  readonly role: "user" | "assistant";
+  readonly text: string;
+  readonly thinking: string;
+}
+
+export function projectChatTurns(messages: readonly Record<string, unknown>[]): readonly ChatTurn[] {
+  const turns: ChatTurn[] = [];
+  for (const message of messages) {
+    if (message.role === "toolResult") continue;
+    const role = message.role === "user" ? "user" : message.role === "assistant" ? "assistant" : undefined;
+    if (!role) continue;
+    const text = messageText(message);
+    const thinking = role === "assistant" ? messageThinking(message) : "";
+    if (!text && !thinking) continue;
+    const previous = turns.at(-1);
+    if (role === "assistant" && previous?.role === "assistant") {
+      turns[turns.length - 1] = { role, text: previous.text + text, thinking: previous.thinking + thinking };
+    } else {
+      turns.push({ role, text, thinking });
+    }
+  }
+  return turns;
+}

package/packages/client-web/src/plugin-navigation.ts

@@ -0,0 +1,9 @@
+export function installedPluginDetailPath(packageName: string): string {
+  return `?page=plugins&plugin=${encodeURIComponent(packageName)}`;
+}
+
+export function readInstalledPluginDetailId(params: URLSearchParams): string | undefined {
+  if (params.get("page") !== "plugins") return undefined;
+  const id = params.get("plugin")?.trim();
+  return id || undefined;
+}

package/packages/client-web/src/plugin-search.ts

@@ -0,0 +1,5 @@
+export const matchesPluginQuery = (query: string, fields: readonly (string | undefined)[]): boolean => {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return true;
+  return fields.some((field) => field?.toLowerCase().includes(normalized));
+};

package/packages/client-web/src/plugin-stars-view.ts

@@ -0,0 +1,19 @@
+export interface PluginStarsRowInput {
+  readonly fullName: string;
+  readonly name: string;
+  readonly stars: number;
+  readonly htmlUrl: string;
+  readonly updatedAt: string;
+}
+
+export interface PluginStarsRow extends PluginStarsRowInput {
+  readonly rank: number;
+}
+
+export function pluginStarsRows(entries: readonly PluginStarsRowInput[], limit: number): readonly PluginStarsRow[] {
+  const normalizedLimit = Math.max(0, Math.min(50, Math.trunc(limit)));
+  return [...entries]
+    .sort((left, right) => right.stars - left.stars || left.fullName.localeCompare(right.fullName))
+    .slice(0, normalizedLimit)
+    .map((entry, index) => ({ ...entry, rank: index + 1 }));
+}

package/packages/client-web/src/prompt-completion.ts

@@ -0,0 +1,24 @@
+export type PromptCompletionKind = "command" | "file";
+
+export interface PromptCompletion {
+  readonly kind: PromptCompletionKind;
+  readonly query: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+export function getPromptCompletion(text: string, caret: number): PromptCompletion | null {
+  const position = Math.max(0, Math.min(caret, text.length));
+  const tokenStart = Math.max(text.lastIndexOf(" ", position - 1), text.lastIndexOf("\n", position - 1)) + 1;
+  const token = text.slice(tokenStart, position);
+  const trigger = token[0];
+  if (trigger !== "/" && trigger !== "@") return null;
+  const query = token.slice(1);
+  if (/\s/.test(query)) return null;
+  return { kind: trigger === "/" ? "command" : "file", query, start: tokenStart, end: position };
+}
+
+export function replacePromptCompletion(text: string, completion: PromptCompletion, value: string): { text: string; caret: number } {
+  const nextText = `${text.slice(0, completion.start)}${value}${text.slice(completion.end)}`;
+  return { text: nextText, caret: completion.start + value.length };
+}