@webskill/chatbot 0.16.0 → 0.17.0

package/dist/index-B25ux241.d.ts

@@ -0,0 +1,390 @@
+import "react";
+import "react/jsx-runtime";
+//#region ../ui-kit/src/i18n/types.d.ts
+/** @stable */
+type Locale = 'zh' | 'en';
+/**
+ * 宿主 / 用户提供的、随界面语言切换的短文案（0.13.0 分册 21 FR-21.1）。
+ * SDK 自己的界面文案走 `createI18n` 字典，不用这个类型。
+ * 允许只填部分语种，缺的语种由 `resolveLocalizedText` 借用已填的。
+ * @experimental
+ */
+type LocalizedText = Partial<Record<Locale, string>>;
+/** 单语言词条：key → 文案（支持 {name} 占位插值） */
+type LocaleMessages = Record<string, string>;
+/** 双语字典：zh/en 两个 locale 的键集必须一致（见 assertDictionaryComplete） */
+interface Dictionary {
+  en: LocaleMessages;
+  zh: LocaleMessages;
+}
+type DictionaryKey<D extends Dictionary> = keyof D['en'] & string;
+type InterpolationParams = Record<string, string | number>;
+/** t(key, params?)：查当前 locale 词条并做 {name} 插值 */
+type TranslateFn<D extends Dictionary = Dictionary> = (key: DictionaryKey<D>, params?: InterpolationParams) => string;
+//#endregion
+//#region ../runtime/src/sandbox/bridgeProtocol.d.ts
+/**
+ * 能力模式：true 直通 / false 关闭（TOOL_UNSUPPORTED）/ 'require-approval' 调用前强制授权
+ * （布尔语义与现状完全兼容）
+ */
+type CapabilityMode = boolean | 'require-approval';
+/** 授权粒度：'once-per-run'（默认，run 内同类能力批准一次）/ 'every-call'（每次调用都问） */
+type ApprovalScope = 'once-per-run' | 'every-call';
+//#endregion
+//#region ../runtime/src/sandbox/networkPolicy.d.ts
+/**
+ * 网络策略类型 + 匹配逻辑（单一来源：browser worker 经函数字符串注入、
+ * node worker 直接 import，禁止各自重复实现）。
+ *
+ * 注意：isNetworkAllowed 会被 toString() 内嵌进浏览器 Worker bootstrap，
+ * 函数体必须自包含（不引用模块内其它符号），且不得使用模板字符串/反引号。
+ */
+type NetworkPolicy = 'deny-all' | 'allow-all' | {
+  allow: string[];
+};
+//#endregion
+//#region ../ui-kit/src/runtime-config/quickPrompts.d.ts
+/**
+ * 快捷指令可选图标名（0.12.0 分册 21）。
+ * 用受控枚举而不是让宿主传组件：SDK 的图标集不进公开契约，
+ * 换实现（lucide → 别的）时宿主代码不用动。
+ *
+ * 0.13.0 分册 17 FR-17.1：真值源从 `@webskill/chatbot` 迁到这里，
+ * 让 console 的配置界面也能用同一份枚举；`@webskill/chatbot` 原样 re-export，
+ * 公开面逐字不变。
+ * @experimental
+ */
+type QuickPromptIconName = 'chart' | 'document' | 'report' | 'search' | 'list' | 'bug' | 'test' | 'metric' | 'compare' | 'page' | 'run' | 'warn' | 'sparkles' | 'settings';
+/**
+ * 带图标的快捷指令（0.12.0 分册 21）。
+ * @experimental
+ */
+interface QuickPrompt {
+  /**
+   * 点击后发出的文本，同时作为按钮可见文案。
+   * 0.13.0 分册 21 FR-21.1：改为按语种取值，可只填部分语种。
+   */
+  text: LocalizedText;
+  /** 缺省或取值不在枚举内时按无图标渲染 */
+  icon?: QuickPromptIconName;
+}
+/**
+ * `RuntimeConfig` 里持久化的快捷指令条目（0.13.0 分册 17）。
+ * 比 `QuickPrompt` 多一个稳定 `id`：列表增删改需要它做定位，
+ * 用 `text` 当 key 在「两条同文案」时会塌陷。`id` 不进任何发给模型的字符串。
+ * @experimental
+ */
+interface RuntimeQuickPrompt {
+  id: string;
+  text: LocalizedText;
+  icon?: QuickPromptIconName;
+}
+//#endregion
+//#region ../ui-kit/src/runtime-config/types.d.ts
+/**
+ * 运行环境配置模型（P2）：console Configure Tab 编辑、chatbot ChatEngine 装配应用，
+ * 宿主经 RuntimeConfigStore 接线同一存储源（playground localStorage / 集成 OPFS 文件）。
+ * 默认值严格对齐 SDK（AgentLoop/InteractionPolicy/executor 缺省）。
+ */
+interface RuntimeLoopConfig {
+  maxTurns: number;
+  totalTimeoutMs: number;
+  toolTimeoutMs: number;
+  temperature?: number;
+  toolResultMaxBytes: number;
+  maxHistoryMessages: number;
+  /** `file` 分片的 base64 上限；超出即拒绝并说明，不截断（FR-23.4） */
+  maxDocumentBytes: number;
+  /** `document-text` 分片的字节上限；同样拒绝而不截断（FR-23.4） */
+  maxDocumentTextBytes: number;
+}
+interface RuntimeInteractionConfig {
+  missingParams: 'user' | 'llm';
+  confirmations: 'required' | 'auto-approve';
+  interactionTimeoutMs: number;
+  approvalScope: ApprovalScope;
+}
+type RuntimeRouterStrategy = 'progressive' | 'full-disclosure';
+/** 生命周期钩子执行策略（`HookRunnerOptions` 的可配置部分） */
+interface RuntimeHooksConfig {
+  timeoutMs: number;
+  /** true 时钩子异常终止 run；缺省隔离为 warning */
+  failOnHookError: boolean;
+}
+/** 浏览器宿主执行器档位；Node 宿主的 in-process/worker/process 由宿主侧扩展展示 */
+type RuntimeSandboxExecutor = 'auto' | 'blob-worker' | 'iframe-sandbox';
+/**
+ * 用户自己声明的取数源（0.14.0 分册 19）。
+ *
+ * 存在的理由：从别的宿主导出的技能会声明本宿主没有的源 id，没有这一段就永远跑不起来。
+ * 它不放宽任何闸门——`url` 照过 `sandbox.remoteUrl` 判定，取数照受 `capabilities.fetchData` 管，
+ * 变的只是「谁来写这个地址」：宿主开发者，还是宿主的使用者。
+ */
+interface RuntimeDataSourceEntry {
+  id: string;
+  /** 绝对 http(s) 地址 */
+  url: string;
+  description: string;
+}
+interface RuntimeSandboxConfig {
+  executor: RuntimeSandboxExecutor;
+  networkPolicy: NetworkPolicy;
+  capabilities: {
+    readReference: CapabilityMode;
+    /** 同时管 readAsset 与 readAssetBinary */
+    readAsset: CapabilityMode;
+    writeArtifact: CapabilityMode;
+    confirm: CapabilityMode;
+    /**
+     * 脚本按宿主声明的数据源取数（分册 16）。
+     * 与 `readAsset` **相反**，缺省 `false`：它会出网，缺省开等于每个技能默认拿到出站能力。
+     */
+    fetchData: CapabilityMode;
+  };
+  /**
+   * 单次取数结果的字节上限（分册 16）。超出即拒绝，**不截断**
+   * ——截断后的 JSON 解不出来，比拒绝更糟。结果回到脚本，不进模型上下文，
+   * 所以不受 `toolResultMaxBytes` 约束。
+   */
+  maxDataSourceBytes: number;
+  /**
+   * 用户声明的取数源（0.14.0 分册 19）；缺省空数组 = 只有宿主代码写死的那些。
+   * 与宿主源撞 id 时宿主的那条胜出——否则用户配置就能改写宿主的授权面。
+   */
+  dataSources: RuntimeDataSourceEntry[];
+  /**
+   * 出站 URL 准入策略（`RemoteUrlPolicy` 的可配置部分）：技能安装、MCP 端点连接
+   * 这类由宿主发起的取数都按它判定。两项都默认关，即 https-only 且拒绝内网/环回。
+   */
+  remoteUrl: RuntimeRemoteUrlConfig;
+  /** 浏览器沙箱的 TypeScript 支持；关闭时 `.ts` 脚本按 `TOOL_UNSUPPORTED` 拒绝 */
+  typescript: RuntimeTypeScriptConfig;
+  /**
+   * 读取用户下载的文件（0.14.0 分册 20）。缺省 `false`。
+   *
+   * **不放进 `capabilities`**：那张表的语义是三态 `CapabilityMode`（关 / 需批准 / 开），
+   * 而本能力的「需批准」是恒定的，放进去会凭空多出一个「开且不批准」的非法组合。
+   */
+  downloadedFiles: boolean;
+  /**
+   * 让技能脚本读用户本轮上传的文件（0.15.0 分册 17）。缺省 `false`。
+   *
+   * **不放进 `capabilities`**，理由同 `downloadedFiles`：本能力的「需批准」是恒定的。
+   * 关闭时脚本上下文里连那两个成员都不存在，而不是存在但总失败。
+   */
+  uploadFiles: boolean;
+  /**
+   * 单个上传文件交给脚本的字节上限（分册 17）。超出即拒，**不截断**
+   * ——截一半的 xlsx / 图片解不开，而脚本看不出它残缺。
+   */
+  maxUploadFileBytes: number;
+}
+/**
+ * 只做类型擦除，不做类型检查。`esbuildUrl` 为绝对 http(s) 地址时按 `remoteUrl` 判定；
+ * 同源相对路径与打包器 specifier 不属于出站请求，不参与判定。
+ */
+interface RuntimeTypeScriptConfig {
+  enabled: boolean;
+  /** esbuild-wasm 的 JS 入口地址；enabled 时必填 */
+  esbuildUrl?: string;
+  /** esbuild.wasm 二进制地址；缺省由 esbuild 自行推导 */
+  wasmUrl?: string;
+}
+/** 与 `@webskill/core` 的 `RemoteUrlPolicy` 同形，但两个字段都是必填（配置需要确定值） */
+interface RuntimeRemoteUrlConfig {
+  allowHttp: boolean;
+  allowPrivateHosts: boolean;
+}
+/** `chrome-builtin` 走浏览器 Prompt API，无端点与密钥；其余三档是云端 HTTP 协议 */
+type RuntimeLlmProvider = 'openai-compatible' | 'anthropic' | 'google' | 'chrome-builtin';
+/**
+ * 单个模型的能力声明（FR-11.4 / FR-14.2）。`image` 缺省视为 `false`：
+ * 猜测支持会把图片发给纯文本模型，拿到的是 provider 的不可读报错。
+ * `tools` 反过来，缺省视为 `true`：云端模型几乎都支持，默认关会把存量配置里
+ * 没标能力的条目全部降级成纯对话。
+ * @experimental
+ */
+interface RuntimeLlmCapabilities {
+  image: boolean;
+  /** 是否支持原生工具调用；false 时 Agent 走纯对话路径 */
+  tools: boolean;
+}
+/**
+ * 单个模型条目。`id` 稳定，会话记录与消息归属存的是它，用户改名不影响历史；
+ * `label` 只用于展示——同一个 `model` 可能配了两个不同的 `baseUrl`（公司代理与直连），
+ * 光看 `model` 区分不出来。
+ */
+interface RuntimeLlmEntry {
+  id: string;
+  label: string;
+  provider: RuntimeLlmProvider;
+  baseUrl?: string;
+  apiKey?: string;
+  model: string;
+  requestTimeoutMs?: number;
+  capabilities?: RuntimeLlmCapabilities;
+  /**
+   * Anthropic extended thinking 预算（0.10.0 遗留项 #1）：仅 anthropic 条目有意义；
+   * 设置面是开关，开启写入 `DEFAULT_THINKING_BUDGET_TOKENS`。
+   * 0.10.0 #40.4：缺省（undefined）视为**开启**（按默认预算），显式关闭存 0。
+   * @experimental
+   */
+  thinkingBudgetTokens?: number;
+}
+/** 模型列表 + 默认项。`defaultId` 由 `mergeRuntimeConfigDefaults` 归一到真实存在的条目 */
+interface RuntimeLlmSelection {
+  entries: readonly RuntimeLlmEntry[];
+  defaultId?: string;
+}
+/**
+ * Agent 能力开关（0.5.0）。默认值逐项经需求评审确定，不适用「新能力一律默认关」的通则。
+ * `todo`：待办清单，默认**开启**——不引入新攻击面、提示词体积远小于生成式 UI catalog，
+ * 且关闭时多步任务体验明显更差。
+ * `skillGeneration`：技能自动生成，默认**关闭**——会把对话内容写进持久化的候选，
+ * 属于新增攻击面（AC-G7 判据一）。
+ * `generativeUi`：生成式 UI，默认**关闭**——catalog 描述约 14 KB 计入每次请求。
+ * `uiPresets`：开放给模型的场景预设，默认全开——预设本体按需加载，
+ * 只有名字与一行摘要计入请求；置空列表等于完全关闭预设。
+ */
+interface RuntimeAgentCapabilitiesConfig {
+  todo: boolean;
+  skillGeneration: boolean;
+  generativeUi: boolean;
+  /** 串行委派（FR-11.8）：默认关。一句话可能展开成多个子 run，调用量对用户不可预期 */
+  delegation: boolean;
+  uiPresets: string[];
+}
+/**
+ * 未签名技能的处置策略（与 core 的 `UnsignedPolicy` 同形，配置层独立命名）。
+ * 默认 `'warn'` 由需求评审定下（FR-1.2）：`deny` 会让现存未签名技能立即不可用，
+ * 且默认信任库为空时接受集为空；`allow` 等于策略不存在。
+ */
+type UnsignedSkillPolicy = 'allow' | 'warn' | 'deny';
+interface RuntimeSecurityConfig {
+  unsignedSkills: UnsignedSkillPolicy;
+}
+/** 生成式 UI 的渲染器档位。ui-kit 不依赖 `@webskill/ui`，因此这里写字面量联合 @experimental */
+type RuntimeRendererId = 'native' | 'a2ui' | 'openui' | 'vercel';
+/**
+ * 外观配置（0.6.0 FR-20.1）。0.5.x 之前外观由宿主自持并单独存一份，
+ * 导致 chatbot 与 console 各看各的；纳入 `RuntimeConfig` 后两端共用同一份。
+ * `dictationLang` 只对 chatbot 有意义（console 无语音输入），但同属外观段。
+ * @experimental
+ */
+interface RuntimeAppearanceConfig {
+  theme: 'light' | 'dark';
+  locale: Locale;
+  renderer: RuntimeRendererId;
+  dictationLang: string;
+}
+/**
+ * 多模态输入配置（0.6.0 FR-11.3 / FR-11.6 / FR-12.3）。
+ * `imageAttachments` 与 `pageImageCapture` 默认都关（AC-G5）：
+ * 两者都会把图像随请求外发给模型提供方，属新增攻击面。
+ * @experimental
+ */
+/**
+ * 文档投放面（0.11.0 分册 18）。
+ *
+ * **只有一个闸门字段**。CSP 白名单不在这里：它由 viewer 路由的**响应头**
+ * 下发（FR-18.3 第 1 条），是宿主部署时调 `viewerCspHeader` 的入参；
+ * 浏览器侧的运行时配置改不动已经发出去的响应头，携在这里只会是个不生效的假开关。
+ */
+interface RuntimeDocumentSurfaceConfig {
+  /** 关着即没有这个投放面；开启还要求宿主额外提供一条 viewer 路由 */
+  enabled: boolean;
+}
+interface RuntimeMultimodalConfig {
+  imageAttachments: boolean;
+  /** 页面图像抓取总开关（FR-12.3）；关时感知只走纯文本路径 */
+  pageImageCapture: boolean;
+  /** 附件与取像共用 */
+  maxImageBytes: number;
+  /** 附件与取像共用 */
+  maxImagesPerMessage: number;
+  /**
+   * 页面取像时小于该面积（平方像素）的元素视作工具图标，不占名额（0.13.0 FR-20.4）。
+   * `0` 是合法值，意为关闭过滤；只作用于页面取像，不管用户上传的附件。
+   */
+  minImageArea: number;
+}
+/**
+ * 用户画像配置（0.6.0 FR-19.6）。`enabled` 默认**关**（AC-G5）：
+ * 开启后会把用户的提问与填写持久化到本地，属新增攻击面；
+ * `encrypted` 默认**开**——它不新增采集，只决定已采集的数据怎么落盘，默认明文无正当理由。
+ * chatbot 与 console 共用这一份。
+ * @experimental
+ */
+interface RuntimeUserProfileConfig {
+  enabled: boolean;
+  /** 画像注入系统提示的字节上限（FR-19.4） */
+  injectMaxBytes: number;
+  /** 行为记录容量上限，超出淘汰最旧（FR-19.2） */
+  recordLimit: number;
+  /** 本地存储加密（FR-19.5） */
+  encrypted: boolean;
+}
+/** @experimental */
+interface RuntimeSkillStateConfig {
+  /**
+   * 技能连续失败自动隔离阈值（0.10.0 UI-UX5 #48-12；#49-2 起默认 5），
+   * 与 governance `SkillStatePolicy` 的缺省对齐。读点在 console 的
+   * GovernanceFacade 装配处（`failureThreshold`），守卫本身不读配置。
+   */
+  quarantineThreshold: number;
+}
+/** @experimental */
+interface RuntimeConfig {
+  loop: RuntimeLoopConfig;
+  interaction: RuntimeInteractionConfig;
+  router: {
+    strategy: RuntimeRouterStrategy;
+  };
+  hooks: RuntimeHooksConfig;
+  streaming: boolean;
+  renderResult: boolean;
+  sandbox: RuntimeSandboxConfig;
+  llm: RuntimeLlmSelection;
+  agentCapabilities: RuntimeAgentCapabilitiesConfig;
+  security: RuntimeSecurityConfig;
+  appearance: RuntimeAppearanceConfig;
+  multimodal: RuntimeMultimodalConfig;
+  documentSurface: RuntimeDocumentSurfaceConfig;
+  userProfile: RuntimeUserProfileConfig;
+  skillState: RuntimeSkillStateConfig;
+  /**
+   * 快捷指令的**唯一权威**（0.13.0 分册 21 FR-21.5）。
+   * `ChatbotConfig.quickPrompts` 降级为一次性种子源，不再参与渲染判断。
+   */
+  quickPrompts: readonly RuntimeQuickPrompt[];
+  /**
+   * 宿主种子是否已注入过（FR-21.6）。
+   * 不得用 `quickPrompts.length === 0` 推断：「从未配置」与「用户删光了」都是空数组，
+   * 靠数组本身分不开——这正是 D-17-3 当年绕不过去的地方。
+   */
+  quickPromptsSeeded: boolean;
+  /** 空态与动态指令条最多展示多少条；超出的部分截断。取值 1..{@link MAX_QUICK_PROMPT_LIMIT} */
+  quickPromptLimit: number;
+  /** 被用户删掉的自动模型条目 id（FR-14.3）：删一次就不该再自己长回来 */
+  dismissedAutoEntries: readonly string[];
+}
+/** @experimental */
+interface RuntimeConfigStore {
+  /**
+   * Loads the runtime configuration. Implementations SHOULD return a complete
+   * RuntimeConfig; consumers wrap stores with `withRuntimeConfigDefaults` so partial
+   * or legacy data is normalized through `mergeRuntimeConfigDefaults` on the read
+   * path. Callers must not apply their own additional fallback merge.
+   */
+  load(): Promise<RuntimeConfig>;
+  save(config: RuntimeConfig): Promise<void>;
+  reset(): Promise<void>;
+  /**
+   * Subscribes to configuration changes; returns an unsubscribe function.
+   * Optional: stores without it degrade to the previous behaviour where hosts
+   * remount consumers after a save.
+   */
+  subscribe?(listener: () => void): () => void;
+}
+//#endregion
+export { RuntimeRendererId as a, RuntimeQuickPrompt as c, TranslateFn as d, RuntimeLlmEntry as i, Locale as l, RuntimeConfig as n, QuickPrompt as o, RuntimeConfigStore as r, QuickPromptIconName as s, RuntimeAppearanceConfig as t, LocalizedText as u };