@michengai/dsh-btw 0.1.0

package/lib/index.js

@@ -0,0 +1,322 @@
+// src/locales.ts
+var zh = {
+  "locale.id": "zh",
+  "bubble.label": "\u65C1\u95EE\u56DE\u7B54",
+  "bubble.image": "\u56FE\u7247",
+  "action.copy": "\u590D\u5236\u56DE\u7B54",
+  "action.copied": "\u5DF2\u590D\u5236",
+  "action.expand": "\u5C55\u5F00\u56DE\u7B54",
+  "action.collapse": "\u6298\u53E0\u56DE\u7B54",
+  "action.close": "\u5173\u95ED\u65C1\u95EE",
+  "action.retryClose": "\u91CD\u8BD5\u5173\u95ED",
+  "status.answering": "\u6B63\u5728\u56DE\u7B54\u2026",
+  "status.closing": "\u6B63\u5728\u5173\u95ED\u2026",
+  "command.hint": "\u65C1\u95EE\u5185\u5BB9",
+  "menu.group": "\u65C1\u95EE",
+  "command.description": "\u6839\u636E\u5F53\u524D\u4E0A\u4E0B\u6587\u56DE\u7B54\u65C1\u95EE",
+  "error.copy": "\u590D\u5236\u5931\u8D25\uFF0C\u8BF7\u9009\u62E9\u56DE\u7B54\u6587\u5B57\u590D\u5236\u3002",
+  "error.images": "\u65C1\u95EE\u53EA\u63A5\u53D7\u6587\u5B57\uFF0C\u56FE\u7247\u4ECD\u4FDD\u7559\u5728\u8F93\u5165\u6846\u4E2D\u3002",
+  "error.removeImages": "\u65C1\u95EE\u53EA\u63A5\u53D7\u6587\u5B57\uFF0C\u8BF7\u5148\u79FB\u9664\u56FE\u7247\u3002",
+  "error.backend": "BTW \u540E\u7AEF\u5C1A\u672A\u542F\u7528\uFF0C\u8BF7\u68C0\u67E5\u63D2\u4EF6\u914D\u7F6E\u3002",
+  "error.empty": "\u8BF7\u8F93\u5165\u65C1\u95EE\u5185\u5BB9\u3002",
+  "error.length": "\u65C1\u95EE\u6700\u591A\u652F\u6301 8000 \u4E2A\u5B57\u7B26\u3002",
+  "error.capacity": "\u6B63\u5728\u5904\u7406\u7684\u65C1\u95EE\u8F83\u591A\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
+  "error.close": "\u5173\u95ED\u5931\u8D25\uFF0C\u53EF\u91CD\u8BD5\u3002{detail}",
+  "error.requestLength": "\u65C1\u95EE\u5185\u5BB9\u8FC7\u957F\u3002",
+  "error.request": "\u65C1\u95EE\u8BF7\u6C42\u65E0\u6548\u3002",
+  "error.id": "\u65C1\u95EE\u6807\u8BC6\u65E0\u6548\u3002",
+  "error.provider": "\u5F53\u524D fork provider \u4E0D\u652F\u6301\u7EE7\u627F\u4E0A\u4E0B\u6587\u5E76\u7981\u7528\u5DE5\u5177\uFF0C\u65C1\u95EE\u672A\u542F\u52A8\u3002",
+  "error.stopped": "\u65C1\u95EE\u63D2\u4EF6\u5DF2\u505C\u6B62\u3002",
+  "error.duplicate": "\u8BE5\u65C1\u95EE\u5DF2\u63D0\u4EA4\u6216\u5DF2\u5173\u95ED\u3002",
+  "error.cancelled": "\u65C1\u95EE\u5DF2\u53D6\u6D88\u3002",
+  "error.timeout": "\u65C1\u95EE\u8D85\u65F6\uFF0C\u5DF2\u53D6\u6D88\u3002",
+  "error.incomplete": "\u65C1\u95EE\u672A\u5B8C\u6210\uFF08{reason}\uFF09\u3002{detail}",
+  "error.noText": "\u6A21\u578B\u672A\u8FD4\u56DE\u6587\u5B57\u56DE\u7B54\u3002",
+  "error.cleanup": "\u8D44\u6E90\u6E05\u7406\u5931\u8D25\uFF0C\u8BF7\u518D\u6B21\u5173\u95ED\u91CD\u8BD5\u3002{detail}"
+};
+var en = {
+  "locale.id": "en",
+  "bubble.label": "Side question answer",
+  "bubble.image": "Image",
+  "action.copy": "Copy answer",
+  "action.copied": "Copied",
+  "action.expand": "Expand answer",
+  "action.collapse": "Collapse answer",
+  "action.close": "Close side question",
+  "action.retryClose": "Retry closing",
+  "status.answering": "Answering\u2026",
+  "status.closing": "Closing\u2026",
+  "command.hint": "Side question",
+  "menu.group": "Side Questions",
+  "command.description": "Ask a side question using the current context",
+  "error.copy": "Copy failed. Select the answer text to copy it.",
+  "error.images": "Side questions accept text only. Your images remain in the input.",
+  "error.removeImages": "Side questions accept text only. Remove the images first.",
+  "error.backend": "The BTW backend is unavailable. Check the plugin configuration.",
+  "error.empty": "Enter a side question.",
+  "error.length": "Side questions are limited to 8,000 characters.",
+  "error.capacity": "Too many side questions are running. Try again shortly.",
+  "error.close": "Could not close. Try again. {detail}",
+  "error.requestLength": "The side question request is too long.",
+  "error.request": "Invalid side question request.",
+  "error.id": "Invalid side question ID.",
+  "error.provider": "The fork provider cannot inherit context with tools disabled. The side question was not started.",
+  "error.stopped": "The side question plugin has stopped.",
+  "error.duplicate": "This side question was already submitted or closed.",
+  "error.cancelled": "Side question cancelled.",
+  "error.timeout": "The side question timed out and was cancelled.",
+  "error.incomplete": "The side question did not complete ({reason}).{detail}",
+  "error.noText": "The model returned no text.",
+  "error.cleanup": "Cleanup failed. Close again to retry. {detail}"
+};
+function translate(locale = "zh") {
+  const dictionary = locale === "zh" ? zh : en;
+  return (key, params) => dictionary[key].replace(/\{(\w+)\}/g, (match, name2) => String(params?.[name2] ?? match));
+}
+function normalizeLocale(value) {
+  return value === void 0 || typeof value === "string" && /^zh(?:-|$)/i.test(value) ? "zh" : "en";
+}
+
+// src/shared.ts
+var RUN_COMMAND = "btw-run";
+var CLOSE_COMMAND = "btw-close";
+var MAX_QUESTION_LENGTH = 8e3;
+function parseRequest(raw) {
+  if (raw.length > 6e4) throw new Error(translate()("error.requestLength"));
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(translate()("error.request"));
+  }
+  if (typeof value !== "object" || value === null) throw new Error(translate()("error.request"));
+  const request = value;
+  const locale = normalizeLocale(request.locale);
+  const t = translate(locale);
+  if (typeof request.id !== "string" || !/^[a-zA-Z0-9-]{8,80}$/.test(request.id)) throw new Error(t("error.id"));
+  if (typeof request.question !== "string" || !request.question.trim()) throw new Error(t("error.empty"));
+  if (request.question.length > MAX_QUESTION_LENGTH) throw new Error(t("error.length"));
+  return { id: request.id, question: request.question.trim(), locale };
+}
+
+// src/server/jobs.ts
+var failure = (error) => ({ kind: "error", text: error instanceof Error ? error.message : String(error) });
+var SideJobs = class {
+  constructor(start, timeoutMs = 9e4) {
+    this.start = start;
+    this.timeoutMs = timeoutMs;
+  }
+  jobs = /* @__PURE__ */ new Map();
+  retired = /* @__PURE__ */ new Map();
+  disposed = false;
+  get size() {
+    return this.jobs.size;
+  }
+  ask(scope, id, question, signal, context, locale = "zh") {
+    const key = JSON.stringify([scope, id]);
+    const t = translate(locale);
+    this.prune();
+    if (this.disposed) return Promise.resolve(failure(t("error.stopped")));
+    if (this.jobs.has(key) || this.retired.has(key)) return Promise.resolve(failure(t("error.duplicate")));
+    if (this.jobs.size >= 8) return Promise.resolve(failure(t("error.capacity")));
+    const job = { controller: new AbortController(), finished: Promise.resolve({ kind: "success", text: "" }), t };
+    this.jobs.set(key, job);
+    const cancel = () => job.controller.abort(new Error(t("error.cancelled")));
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted) cancel();
+    const timer = setTimeout(() => job.controller.abort(new Error(t("error.timeout"))), this.timeoutMs);
+    timer.unref?.();
+    job.finished = this.execute(job, { scope, id, question, signal: job.controller.signal, toolFilter: { allow: [] }, context, locale }).finally(() => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", cancel);
+      if (!job.run) {
+        this.jobs.delete(key);
+        this.retire(key);
+      }
+    });
+    return job.finished;
+  }
+  /** 关闭可先于启动到达；短期墓碑阻止网络乱序重新启动请求。 */
+  async close(scope, id) {
+    const key = JSON.stringify([scope, id]);
+    this.retire(key);
+    const job = this.jobs.get(key);
+    if (!job) return { kind: "success", text: "" };
+    job.controller.abort(new Error(job.t("error.cancelled")));
+    await job.finished;
+    try {
+      await this.cleanup(job);
+      this.jobs.delete(key);
+      return { kind: "success", text: "" };
+    } catch (error) {
+      return failure(error);
+    }
+  }
+  async dispose() {
+    this.disposed = true;
+    const outcomes = await Promise.all([...this.jobs.keys()].map((key) => {
+      const [scope, id] = JSON.parse(key);
+      return this.close(scope, id);
+    }));
+    const errors = outcomes.filter((outcome) => outcome.kind === "error");
+    if (errors.length) throw new Error(errors.map((error) => error.text).join("\n"));
+  }
+  async execute(job, request) {
+    let result;
+    let off = () => {
+    };
+    try {
+      request.signal.throwIfAborted();
+      job.run = await this.start(request);
+      const interrupted = new Promise((_, reject) => {
+        const abort = () => reject(request.signal.reason);
+        request.signal.addEventListener("abort", abort, { once: true });
+        off = () => request.signal.removeEventListener("abort", abort);
+        if (request.signal.aborted) abort();
+      });
+      const response = await Promise.race([job.run.result, interrupted]);
+      request.signal.throwIfAborted();
+      const text = response.output.filter((block) => block.type === "text").map((block) => block.text ?? "").join("").trim();
+      if (response.stopReason !== "completed") throw new Error(job.t("error.incomplete", { reason: response.stopReason, detail: text ? `
+
+${text}` : "" }));
+      if (!text) throw new Error(job.t("error.noText"));
+      result = { kind: "success", text };
+    } catch (error) {
+      result = failure(error);
+    } finally {
+      off();
+    }
+    try {
+      await this.cleanup(job);
+    } catch (error) {
+      return failure(job.t("error.cleanup", { detail: error instanceof Error ? error.message : String(error) }));
+    }
+    return result;
+  }
+  async cleanup(job) {
+    if (!job.run) return;
+    if (!job.cleanup) {
+      job.cleanup = Promise.resolve().then(() => job.run?.dispose()).then(() => {
+        job.run = void 0;
+      }).catch((error) => {
+        job.cleanup = void 0;
+        throw error;
+      });
+    }
+    await job.cleanup;
+  }
+  retire(key) {
+    this.retired.set(key, Date.now());
+    this.prune();
+  }
+  prune() {
+    for (const [key, time] of this.retired) if (Date.now() - time > 3e5 || this.retired.size > 1e3) this.retired.delete(key);
+  }
+};
+
+// src/server/tool-guard.ts
+function createAnswerOnlyGuard(labels) {
+  const owned = /* @__PURE__ */ new WeakSet();
+  return ({ agent }) => {
+    if (!agent) return void 0;
+    if (!owned.has(agent)) {
+      const event = agent.session.snapshotEvents().findLast((item) => item.type === "subagent/descriptor");
+      const data = event?.data;
+      if (typeof data !== "object" || data === null || !("label" in data) || typeof data.label !== "string" || !labels.has(data.label)) return void 0;
+      owned.add(agent);
+    }
+    return "BTW \u4EC5\u5141\u8BB8\u6587\u5B57\u56DE\u7B54\uFF0C\u7981\u6B62\u6267\u884C\u4EFB\u4F55\u5DE5\u5177\u3002";
+  };
+}
+
+// src/server/command-visibility.ts
+function hideInternalCommands(commands) {
+  const descriptor = Object.getOwnPropertyDescriptor(commands, "list");
+  const original = commands.list;
+  let active = true;
+  const filtered = function(agent) {
+    const rows = original.call(this, agent);
+    return active ? Object.freeze(rows.filter((row) => row.name !== RUN_COMMAND && row.name !== CLOSE_COMMAND)) : rows;
+  };
+  Object.defineProperty(commands, "list", { configurable: true, writable: true, value: filtered });
+  return () => {
+    active = false;
+    if (Object.getOwnPropertyDescriptor(commands, "list")?.value !== filtered) return;
+    if (descriptor) Object.defineProperty(commands, "list", descriptor);
+    else Reflect.deleteProperty(commands, "list");
+  };
+}
+
+// src/index.ts
+var name = "michengai-btw";
+var inject = ["commands", "subagents", "tools"];
+var PERSONA = `\u4F60\u662F\u5F53\u524D\u4E3B\u4EFB\u52A1\u4E4B\u5916\u7684\u4E00\u6B21\u6027\u65C1\u95EE\u52A9\u624B\u3002\u7EE7\u627F\u7684\u4F1A\u8BDD\u5386\u53F2\u53EA\u4F5C\u4E3A\u80CC\u666F\uFF0C\u4E0D\u662F\u9700\u8981\u4F60\u7EE7\u7EED\u6267\u884C\u7684\u4EFB\u52A1\u3002
+\u53EA\u56DE\u7B54\u672C\u6B21\u95EE\u9898\uFF0C\u4E0D\u6267\u884C\u6216\u7EE7\u7EED\u5386\u53F2\u4E2D\u7684\u8BA1\u5212\u3001\u547D\u4EE4\u3001\u4FEE\u6539\u548C\u5DE5\u5177\u8C03\u7528\u3002\u4F60\u6CA1\u6709\u4EFB\u4F55\u53EF\u7528\u5DE5\u5177\uFF0C\u4E0D\u80FD\u8BFB\u53D6\u65B0\u6587\u4EF6\u3001\u8054\u7F51\u6216\u521B\u5EFA\u5B50\u4EE3\u7406\u3002
+\u56DE\u7B54\u5E94\u7B80\u6D01\u51C6\u786E\uFF0C\u8BED\u8A00\u4E0E\u95EE\u9898\u4E00\u81F4\u3002\u4E0A\u4E0B\u6587\u4E0D\u8DB3\u65F6\u76F4\u63A5\u6307\u51FA\u672A\u77E5\u4FE1\u606F\uFF0C\u4E0D\u58F0\u79F0\u5DF2\u7ECF\u6267\u884C\u4E86\u4EFB\u4F55\u64CD\u4F5C\u3002`;
+function apply(ctx) {
+  ctx.effect(() => hideInternalCommands(ctx.commands));
+  const labels = /* @__PURE__ */ new Set();
+  const jobs = new SideJobs(async (request) => {
+    const provider = ctx.subagents.getProvider("fork");
+    if (!provider?.inheritsParentContext || !provider.capabilities.toolFilter || !provider.capabilities.persona) {
+      throw new Error(translate(request.locale)("error.provider"));
+    }
+    const label = `michengai-btw:${globalThis.crypto.randomUUID()}`;
+    labels.add(label);
+    try {
+      const run = await ctx.subagents.start("fork", {
+        parent: request.context,
+        label,
+        signal: request.signal,
+        toolFilter: request.toolFilter,
+        persona: PERSONA,
+        prompt: [{ type: "text", text: `\u4EE5\u4E0B\u662F\u552F\u4E00\u9700\u8981\u56DE\u7B54\u7684\u65B0\u95EE\u9898\uFF1B\u5148\u524D\u5185\u5BB9\u4EC5\u4F9B\u53C2\u8003\u3002
+
+${request.question}` }]
+      });
+      return {
+        result: run.result,
+        dispose: async () => {
+          await run.dispose();
+          labels.delete(label);
+        }
+      };
+    } catch (error) {
+      labels.delete(label);
+      throw error;
+    }
+  });
+  ctx.effect(() => ctx.commands.register({
+    name: RUN_COMMAND,
+    description: "BTW \u6C14\u6CE1\u5185\u90E8\u8BF7\u6C42",
+    recordInput: false,
+    handler: (invocation) => {
+      try {
+        const request = parseRequest(invocation.rawInput);
+        return jobs.ask(invocation.agent.session.header.id, request.id, request.question, invocation.signal, invocation.agent, request.locale);
+      } catch (error) {
+        return { kind: "error", text: error instanceof Error ? error.message : translate()("error.request") };
+      }
+    }
+  }));
+  ctx.effect(() => ctx.commands.register({
+    name: CLOSE_COMMAND,
+    description: "\u5173\u95ED\u5E76\u6E05\u7406\u6307\u5B9A BTW \u8BF7\u6C42",
+    recordInput: false,
+    handler: (invocation) => {
+      const id = invocation.rawInput.trim();
+      if (!/^[a-zA-Z0-9-]{8,80}$/.test(id)) return { kind: "error", text: translate()("error.id") };
+      return jobs.close(invocation.agent.session.header.id, id);
+    }
+  }));
+  ctx.effect(function* () {
+    yield ctx.tools.guard(createAnswerOnlyGuard(labels));
+    yield () => jobs.dispose();
+  });
+}
+export {
+  apply,
+  inject,
+  name
+};

package/lib/types/client/BubbleView.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { Bubble, BubbleStore } from './bubbles';
+import type { BtwTranslate } from '../locales';
+export declare function BubbleView({ item, close, t }: {
+    item: Bubble;
+    close: () => void;
+    t: BtwTranslate;
+}): React.JSX.Element;
+export declare function BubbleDock({ store, sessionId, t }: {
+    store: BubbleStore;
+    sessionId: string;
+    t: BtwTranslate;
+}): React.JSX.Element | null;

package/lib/types/client/bubbles.d.ts

@@ -0,0 +1,32 @@
+import { type SideResult } from '../shared';
+import { type BtwTranslate } from '../locales';
+export interface Bubble {
+    id: string;
+    sessionId: string;
+    question: string;
+    answer: string;
+    phase: 'answering' | 'done' | 'error' | 'closing';
+    error?: string;
+    closeFailed?: boolean;
+}
+export interface SideTransport {
+    run(session: string, id: string, question: string, signal: AbortSignal): Promise<SideResult>;
+    close(session: string, id: string): Promise<SideResult>;
+}
+/** 仅内存 UI 状态；关闭请求与答案返回按请求身份分别收敛。 */
+export declare class BubbleStore {
+    private readonly transport;
+    private readonly t;
+    private snapshot;
+    private readonly listeners;
+    private readonly active;
+    private readonly closing;
+    constructor(transport: SideTransport, t?: BtwTranslate);
+    getSnapshot: () => readonly Bubble[];
+    subscribe: (listener: () => void) => (() => void);
+    ask(sessionId: string, question: string): string;
+    close(id: string): Promise<void>;
+    dispose(): Promise<void>;
+    private update;
+    private publish;
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/types/client/styles.d.ts

@@ -0,0 +1 @@
+export declare const CSS = "\n.btw-dock{display:flex;flex:none;flex-direction:column;gap:8px;width:calc(100% - var(--dsh-composer-side-clearance,0px) - var(--dsh-composer-side-clearance,0px));max-width:var(--dsh-composer-card-max-width,100%);margin:0 auto;max-height:440px;overflow:auto;padding:4px 0 10px;box-sizing:border-box;letter-spacing:0}\n.btw-bubble{background:var(--dsw-alias-bg-base);color:var(--dsw-alias-label-primary);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;min-width:0;flex-shrink:0;font-size:13px;line-height:1.6;font-family:var(--dsw-font-family,inherit);letter-spacing:0}\n.btw-header{display:flex;align-items:center;gap:8px;padding:8px 10px 8px 14px;min-width:0;min-height:44px}\n.btw-symbol{display:flex;align-items:center;color:var(--dsw-alias-label-secondary);height:28px;flex-shrink:0}\n.btw-question{flex:1;min-width:0;overflow-wrap:anywhere;font-size:13px;font-weight:500;line-height:22px;max-height:66px;overflow:auto}\n.btw-actions{display:flex;gap:4px;flex-shrink:0}\n.btw-actions button{display:grid;place-items:center;width:28px;height:28px;padding:0;border:0;border-radius:50%;background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;flex:none;transition:background-color 120ms ease}\n.btw-actions button:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}\n.btw-actions button:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary,var(--dsw-alias-label-primary));outline-offset:-2px}\n.btw-actions button:disabled{cursor:wait;opacity:.5}\n.btw-status{display:flex;align-items:center;gap:8px;padding:0 14px 12px;color:var(--dsw-alias-label-secondary);font-size:13px}\n.btw-spinner{animation:btw-spin 1.2s linear infinite}@keyframes btw-spin{to{transform:rotate(360deg)}}\n.btw-answer{padding:0 14px 14px;max-height:300px;overflow:auto;overflow-wrap:anywhere;font-size:13px;line-height:1.7}\n.btw-answer>*:first-child{margin-top:0}.btw-answer>*:last-child{margin-bottom:0}\n.btw-answer p{margin:8px 0}.btw-answer h1,.btw-answer h2,.btw-answer h3{font-size:15px;line-height:1.5;margin:12px 0 6px;font-weight:600}\n.btw-answer pre{max-width:100%;overflow:auto;background:var(--dsw-alias-markdown-code-block);padding:10px;border-radius:8px;white-space:pre;font-size:12px}\n.btw-answer code{font-family:Consolas,monospace;font-size:12px}.btw-answer :not(pre)>code{background:var(--dsw-alias-markdown-code-block);border-radius:4px;padding:1px 3px}.btw-answer a{color:var(--dsw-alias-label-primary);text-decoration:underline;text-underline-offset:2px;overflow-wrap:anywhere}\n.btw-answer table{display:block;max-width:100%;overflow:auto;border-collapse:collapse}.btw-answer th,.btw-answer td{border:1px solid var(--dsw-alias-border-l2);padding:5px 9px}\n.btw-answer ul,.btw-answer ol{padding-left:22px}.btw-answer blockquote{margin:8px 0;padding-left:10px;border-left:2px solid var(--dsw-alias-border-l4);color:var(--dsw-alias-label-secondary)}\n.btw-error{margin:0;padding:0 14px 12px;font-size:13px;color:var(--dsw-alias-state-error-primary);overflow-wrap:anywhere}\n@media(max-width:480px){.btw-dock{max-height:330px}.btw-header{padding:6px 8px 6px 12px;gap:6px}.btw-answer{padding:0 12px 12px;max-height:230px}.btw-status,.btw-error{padding-left:12px}.btw-actions{gap:0}.btw-actions button{width:36px;height:36px}}\n@media(prefers-reduced-motion:reduce){.btw-spinner{animation:none}.btw-actions button{transition:none}}\n";

package/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "michengai-btw";
+export declare const inject: string[];
+/** 宿主命令只负责接入与身份绑定，不创建 HTTP 或持久侧聊接口。 */
+export declare function apply(ctx: Context): void;

package/lib/types/locales.d.ts

@@ -0,0 +1,49 @@
+import type { Translate } from '@deepseek-ai/dsh-client-ui-slots';
+export declare const NS = "michengai.btw";
+export declare const zh: {
+    'locale.id': string;
+    'bubble.label': string;
+    'bubble.image': string;
+    'action.copy': string;
+    'action.copied': string;
+    'action.expand': string;
+    'action.collapse': string;
+    'action.close': string;
+    'action.retryClose': string;
+    'status.answering': string;
+    'status.closing': string;
+    'command.hint': string;
+    'menu.group': string;
+    'command.description': string;
+    'error.copy': string;
+    'error.images': string;
+    'error.removeImages': string;
+    'error.backend': string;
+    'error.empty': string;
+    'error.length': string;
+    'error.capacity': string;
+    'error.close': string;
+    'error.requestLength': string;
+    'error.request': string;
+    'error.id': string;
+    'error.provider': string;
+    'error.stopped': string;
+    'error.duplicate': string;
+    'error.cancelled': string;
+    'error.timeout': string;
+    'error.incomplete': string;
+    'error.noText': string;
+    'error.cleanup': string;
+};
+export type MessageKey = keyof typeof zh;
+export type BtwTranslate = Translate<MessageKey>;
+export type BtwLocale = 'zh' | 'en';
+export declare const en: Record<MessageKey, string>;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'michengai.btw': MessageKey;
+    }
+}
+/** 服务端按请求语言生成提示；客户端使用宿主 locale.bind 和 slot 的 t。 */
+export declare function translate(locale?: BtwLocale): BtwTranslate;
+export declare function normalizeLocale(value: unknown): BtwLocale;

package/lib/types/server/command-visibility.d.ts

@@ -0,0 +1,3 @@
+import type { CommandRuntime } from '@deepseek-ai/dsh-commands';
+/** 兼容没有 hidden 选项的宿主：仅过滤目录，find/execute 仍由宿主处理。 */
+export declare function hideInternalCommands(commands: Pick<CommandRuntime, 'list'>): () => void;

package/lib/types/server/jobs.d.ts

@@ -0,0 +1,43 @@
+import type { SideResult } from '../shared';
+import { type BtwLocale } from '../locales';
+export interface ChildResult {
+    stopReason: string;
+    output: readonly {
+        type: string;
+        text?: string;
+    }[];
+}
+export interface ChildRun {
+    result: Promise<ChildResult>;
+    dispose(): Promise<void>;
+}
+export interface ChildRequest {
+    scope: string;
+    id: string;
+    question: string;
+    signal: AbortSignal;
+    toolFilter: {
+        allow: readonly string[];
+    };
+    context?: unknown;
+    locale: BtwLocale;
+}
+export type StartChild = (request: ChildRequest) => Promise<ChildRun>;
+/** 管理一次性任务；父会话和请求标识共同构成所有权边界。 */
+export declare class SideJobs {
+    private readonly start;
+    private readonly timeoutMs;
+    private readonly jobs;
+    private readonly retired;
+    private disposed;
+    constructor(start: StartChild, timeoutMs?: number);
+    get size(): number;
+    ask(scope: string, id: string, question: string, signal?: AbortSignal, context?: unknown, locale?: BtwLocale): Promise<SideResult>;
+    /** 关闭可先于启动到达；短期墓碑阻止网络乱序重新启动请求。 */
+    close(scope: string, id: string): Promise<SideResult>;
+    dispose(): Promise<void>;
+    private execute;
+    private cleanup;
+    private retire;
+    private prune;
+}

package/lib/types/server/tool-guard.d.ts

@@ -0,0 +1,13 @@
+interface AgentIdentity {
+    session: {
+        snapshotEvents(): readonly {
+            type: string;
+            data: unknown;
+        }[];
+    };
+}
+/** 空白名单过滤继承工具；本保护额外拒绝 PTC 及子作用域自注册工具。 */
+export declare function createAnswerOnlyGuard(labels: ReadonlySet<string>): (execution: {
+    agent?: AgentIdentity;
+}) => string | undefined;
+export {};

package/lib/types/shared.d.ts

@@ -0,0 +1,15 @@
+import { type BtwLocale } from './locales';
+export declare const RUN_COMMAND = "btw-run";
+export declare const CLOSE_COMMAND = "btw-close";
+export declare const MAX_QUESTION_LENGTH = 8000;
+export interface SideRequest {
+    id: string;
+    question: string;
+    locale: BtwLocale;
+}
+export interface SideResult {
+    kind: 'success' | 'error';
+    text: string;
+}
+/** 内部命令使用结构化请求，身份始终由宿主会话提供。 */
+export declare function parseRequest(raw: string): SideRequest;

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@michengai/dsh-btw",
+  "version": "0.1.0",
+  "description": "DSH 一次性只读旁问气泡",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichengAI/dsh-btw.git"
+  },
+  "homepage": "https://github.com/MichengAI/dsh-btw#readme",
+  "bugs": {
+    "url": "https://github.com/MichengAI/dsh-btw/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "assets",
+    "cordis.patch.yml",
+    "docs",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh-CN.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-input-trigger",
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:release": "node --test tests/release.test.mjs",
+    "check": "npm run typecheck && npm test && npm run test:release && npm run build",
+    "preview": "vite preview --host 127.0.0.1",
+    "dev": "vite --host 127.0.0.1",
+    "test:browser": "playwright test",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-commands": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-theme": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-scope": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "0.1.2-rc.1",
+    "@playwright/test": "^1.58.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "esbuild": "^0.25.0",
+    "lucide-react": "^0.468.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "typescript": "~5.7.2",
+    "vite": "^6.4.0",
+    "vitest": "^3.2.0"
+  }
+}