{ "title": "共享包 API", "locale": "zh", "page": "shared", "route": "/zh/reference/api/shared", "package": "@plingjs/core", "version": "0.1.0-alpha.2", "since": "0.1.0-alpha.2", "stability": "preview", "categories": [ { "id": "declarations", "title": "页面声明", "summary": "声明动作、记录、区域、状态、页面反馈、任务入口与敏感值。", "entries": [ { "id": "sensitive", "anchor": "api-sensitive", "name": "sensitive", "kind": "function", "summary": "标记一个值在出站时隐藏、遮罩、代号化或只给提示，同时保留字段名。", "imports": [ "@plingjs/core" ], "signature": "sensitive(value: T, options?: SensitivityMode | SensitiveOptions): SensitiveValue", "parameters": [ { "name": "value", "type": "T", "required": true, "defaultValue": "", "description": "Value that enters page context and the model transcript.", "descriptionZh": "会进入页面上下文与模型对话的值。" }, { "name": "options", "type": "\"masked\" | \"hidden\" | SensitiveOptions", "required": false, "defaultValue": "\"masked\"", "description": "Controls whether the model sees a placeholder or no value. The real value remains in the browser.", "descriptionZh": "控制模型看到占位代号还是不看到值。真值仍留在浏览器内。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Mask a phone number", "titleZh": "脱敏电话号码", "code": "const phone = sensitive(customer.phone, \"masked\");", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "sensitive" }, { "package": "@plingjs/vue", "name": "sensitive" }, { "package": "@plingjs/react", "name": "sensitive" } ], "reference": "/reference/core-declarations-actions-records-regions-state" } ] }, { "id": "types", "title": "共享选项类型", "summary": "声明所引用的选项结构。适配器使用不同名称时，会同时列出别名。", "entries": [ { "id": "RecordValue", "anchor": "api-recordvalue", "name": "RecordValue", "kind": "type", "summary": "一行数据，或带显式 id、label、fields 的完整记录声明。", "imports": [ "@plingjs/core" ], "signature": "type RecordValue =\n | object\n | {\n data: object;\n id?: string | number;\n label?: string;\n fields?: Record;\n }", "parameters": [ { "name": "plain object.id | key", "type": "string | number", "required": false, "defaultValue": "", "description": "Default primary key when the row itself is passed as a plain object.", "descriptionZh": "直接把行对象作为记录时，默认从 `id` 或 `key` 读取主键。" }, { "name": "envelope.data", "type": "object", "required": "conditional", "defaultValue": "", "description": "Row data wrapped in the explicit record envelope.", "descriptionZh": "使用显式记录包装时承载的行数据。" }, { "name": "envelope.id", "type": "string | number", "required": false, "defaultValue": "", "description": "Overrides the primary key when the field is not named id or key.", "descriptionZh": "主键字段不叫 `id` / `key` 时用它覆盖。" }, { "name": "envelope.label", "type": "string", "required": false, "defaultValue": "", "description": "Human- and model-readable row label.", "descriptionZh": "给人也给模型看的行说明。" }, { "name": "envelope.fields", "type": "Record", "required": false, "defaultValue": "", "description": "Allowlist of fields visible to the model. Without it, all row fields except the primary key are exposed.", "descriptionZh": "模型可见字段白名单。不写时暴露除主键外的全部行字段。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Explicit field allowlist", "titleZh": "显式字段白名单", "code": "const value = {\n data: order,\n id: order.code,\n label: `订单 ${order.code}`,\n fields: { customer: order.customer, total: order.total },\n};", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "RecordValue" }, { "package": "@plingjs/vue", "name": "RecordValue" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "Kind", "anchor": "api-kind", "name": "Kind", "kind": "type", "summary": "动作的风险等级，供确认策略使用。", "imports": [ "@plingjs/core" ], "signature": "type Kind = \"read\" | \"write\" | \"danger\"", "parameters": [ { "name": "read", "type": "\"read\"", "required": false, "defaultValue": "", "description": "No business state change. Visibility, navigation, and inspection belong here.", "descriptionZh": "不改变业务状态。查看、导航和检查属于这一档。" }, { "name": "write", "type": "\"write\"", "required": false, "defaultValue": "", "description": "Changes business state but is not destructive or irreversible.", "descriptionZh": "改变业务状态，但不是破坏性或不可逆操作。" }, { "name": "danger", "type": "\"danger\"", "required": false, "defaultValue": "", "description": "Destructive, irreversible, or high-impact. Approval defaults to stricter handling.", "descriptionZh": "破坏性、不可逆或影响较大的操作。确认策略默认更严格。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Choose a risk level", "titleZh": "选择风险等级", "code": "pling.tool(deleteButton, { desc: \"删除此订单\", kind: \"danger\" });", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "Kind" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "ParamDeclaration", "anchor": "api-paramdeclaration", "name": "ParamDeclaration", "kind": "type", "summary": "用于校验动作参数的数组简写或 JSON Schema。", "imports": [ "@plingjs/core" ], "signature": "type ParamDeclaration = readonly ToolParam[] | JsonSchema", "parameters": [ { "name": "[].name", "type": "string", "required": true, "defaultValue": "", "description": "Argument key received by run and visible to the model.", "descriptionZh": "`run` 收到的参数键，也是模型看到的参数名。" }, { "name": "[].label", "type": "string", "required": true, "defaultValue": "", "description": "Required explanation of the argument. It is the model's only semantic hint.", "descriptionZh": "必填的参数说明，是模型唯一可依赖的语义提示。" }, { "name": "[].type", "type": "\"string\" | \"number\" | \"boolean\"", "required": false, "defaultValue": "\"string\"", "description": "Argument type. Includes coercion from obvious string forms and rejects invalid values.", "descriptionZh": "参数类型。会把明显的字符串形式规整为对应类型，并拒绝无效值。" }, { "name": "[].optional", "type": "boolean", "required": false, "defaultValue": "false", "description": "Marks the argument optional. Arguments are required by default.", "descriptionZh": "把参数标为可选。参数默认必填。" }, { "name": "[].values", "type": "readonly (string | number)[]", "required": false, "defaultValue": "", "description": "Closed static value set. Use it when the model must choose from known values.", "descriptionZh": "静态封闭值集合。模型只能从已知值里选择时使用。" }, { "name": "[].options", "type": "() => readonly ParamOption[]", "required": false, "defaultValue": "", "description": "Dynamic value set, re-read for each snapshot and execution.", "descriptionZh": "动态值集合，每次快照与执行前重新读取。" }, { "name": "[].min | [].max", "type": "number | (() => number)", "required": false, "defaultValue": "", "description": "Numeric bounds for number arguments, including dynamic bounds.", "descriptionZh": "数字参数的上下界，也支持动态边界。" }, { "name": "[].minLength | [].maxLength", "type": "number", "required": false, "defaultValue": "", "description": "String length bounds.", "descriptionZh": "字符串长度边界。" }, { "name": "[].pattern", "type": "RegExp | string", "required": false, "defaultValue": "", "description": "Regular-expression constraint for a string argument.", "descriptionZh": "字符串参数的正则约束。" }, { "name": "[].format", "type": "\"date\"", "required": false, "defaultValue": "", "description": "Semantic format validation. A date must be a real calendar date.", "descriptionZh": "语义格式校验。`date` 还要求是真实存在的日期。" }, { "name": "JSON Schema.type", "type": "\"object\"", "required": "conditional", "defaultValue": "\"object\"", "description": "The direct JSON Schema form must describe an object.", "descriptionZh": "直接传 JSON Schema 时，根类型必须是对象。" }, { "name": "JSON Schema.properties", "type": "Record", "required": false, "defaultValue": "", "description": "Property schemas for the direct JSON Schema form.", "descriptionZh": "直接 JSON Schema 形式的属性定义。" }, { "name": "JSON Schema.required", "type": "string[]", "required": false, "defaultValue": "", "description": "Required property names for the direct JSON Schema form.", "descriptionZh": "直接 JSON Schema 形式的必填属性名。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Compact parameter declaration", "titleZh": "参数简写", "code": "const params = [\n { name: \"orderId\", label: \"订单号\", pattern: /^SO-\\d{4}$/ },\n { name: \"note\", label: \"新备注\", maxLength: 200 },\n { name: \"notify\", label: \"是否通知客户\", type: \"boolean\", optional: true },\n];", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "ParamDeclaration" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "Expectation", "anchor": "api-expectation", "name": "Expectation", "kind": "type", "summary": "动作结束后检查的成功条件。", "imports": [ "@plingjs/core" ], "signature": "interface Expectation {\n desc?: string;\n check(): boolean | Promise;\n timeout?: number;\n}", "parameters": [ { "name": "desc", "type": "string", "required": false, "defaultValue": "", "description": "Human-readable statement of the expected outcome. It is included in success and failure receipts.", "descriptionZh": "对预期结果的人话说明。会出现在成功与失败回执里。" }, { "name": "check", "type": "() => boolean | Promise", "required": true, "defaultValue": "", "description": "Predicate evaluated after execution. Exceptions remain developer errors and are not swallowed.", "descriptionZh": "执行后求值的判断函数。函数自身异常会原样抛出，不会被吞掉。" }, { "name": "timeout", "type": "number", "required": false, "defaultValue": "2000", "description": "Maximum wait in milliseconds before reporting EXPECTATION_FAILED.", "descriptionZh": "成立前的最长等待时间；超过后报告 `EXPECTATION_FAILED`。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Verify a new row exists", "titleZh": "确认新记录真的出现", "code": "const expect = {\n desc: \"新待办出现在列表中\",\n check: () => todos.some((todo) => todo.text === \"准备发布\"),\n timeout: 3000,\n};", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "Expectation" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "HandoffStep", "anchor": "api-handoffstep", "name": "HandoffStep", "kind": "type", "summary": "人工接力时展示给用户的一条步骤说明。", "imports": [ "@plingjs/core" ], "signature": "interface HandoffStep {\n text: string;\n highlight?: string;\n}", "parameters": [ { "name": "text", "type": "string", "required": true, "defaultValue": "", "description": "Instruction shown to the person who takes over.", "descriptionZh": "交给接手人看的操作说明。" }, { "name": "highlight", "type": "string", "required": false, "defaultValue": "", "description": "Optional guide-target id or action id to highlight while the step is active.", "descriptionZh": "可选的高亮目标：引导目标 id 或动作 id。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Guide a human step", "titleZh": "引导人工步骤", "code": "const steps = [\n { text: \"填写短信验证码\", highlight: \"captcha\" },\n { text: \"点击提交\", highlight: \"submit\" },\n];", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "HandoffStep" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "FlowStep", "anchor": "api-flowstep", "name": "FlowStep", "kind": "type", "summary": "复合动作中的一步。步骤不是第二条执行通道。", "imports": [ "@plingjs/core" ], "signature": "interface FlowStep {\n action: string;\n args?: Record | ((params: Record) => Record);\n expect?: Expectation;\n desc?: string;\n optional?: boolean;\n idempotent?: boolean;\n}", "parameters": [ { "name": "action", "type": "string", "required": true, "defaultValue": "", "description": "Registered action id to execute. It may contain {{parameter}} placeholders.", "descriptionZh": "要执行的已注册动作 id，可包含 `{{参数}}` 占位符。" }, { "name": "args", "type": "Record | ((params) => Record)", "required": false, "defaultValue": "", "description": "Step arguments. Strings may reference flow parameters; a function receives the complete parameter object.", "descriptionZh": "步骤参数。字符串可引用流程参数；函数形式收到完整参数对象。" }, { "name": "expect", "type": "Expectation", "required": false, "defaultValue": "", "description": "Overrides the step action's own success criterion.", "descriptionZh": "覆盖该步骤动作自身声明的成功判据。" }, { "name": "desc", "type": "string", "required": false, "defaultValue": "", "description": "Human-readable step description used in progress and receipts.", "descriptionZh": "用于进度与回执的人话步骤说明。" }, { "name": "optional", "type": "boolean", "required": false, "defaultValue": "false", "description": "A failed optional step is skipped instead of aborting the flow.", "descriptionZh": "可选步骤失败时跳过，不中断整个流程。" }, { "name": "idempotent", "type": "boolean", "required": false, "defaultValue": "false", "description": "Allows safe retry after an execution or expectation failure. Pre-execution failures are always retryable.", "descriptionZh": "允许执行后或判据失败后重试。执行前失败本身就可以重试。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Reference a parameter in a step", "titleZh": "在步骤中引用参数", "code": "const steps = [\n { action: \"edit@order:{{orderId}}\", desc: \"打开订单\" },\n { action: \"dialog_note\", args: { text: \"{{note}}\" }, desc: \"填写备注\" },\n { action: \"dialog_save\", desc: \"保存\" },\n];", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "FlowStep" }, { "package": "@plingjs/vue", "name": "FlowStep" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "RegionRole", "anchor": "api-regionrole", "name": "RegionRole", "kind": "type", "summary": "区域的结构角色。", "imports": [ "@plingjs/core" ], "signature": "type RegionRole =\n | \"page\"\n | \"header\"\n | \"nav\"\n | \"main\"\n | \"aside\"\n | \"section\"\n | \"form\"\n | \"dialog\"\n | \"toolbar\"\n | \"list\"\n | \"footer\"", "parameters": [ { "name": "role", "type": "\"page\" | \"header\" | \"nav\" | \"main\" | \"aside\" | \"section\" | \"form\" | \"dialog\" | \"toolbar\" | \"list\" | \"footer\"", "required": true, "defaultValue": "", "description": "Adds structural context for disambiguating actions with similar names. It does not grant or restrict permissions.", "descriptionZh": "为同名动作提供结构上下文。它不会授予或限制权限。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Disambiguate two confirm buttons", "titleZh": "区分两个确认按钮", "code": "pling.scope(dialog, { id: \"edit_dialog\", role: \"dialog\", label: \"编辑订单\" });\npling.scope(toolbar, { id: \"bulk_toolbar\", role: \"toolbar\", label: \"批量操作\" });", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "RegionRole" }, { "package": "@plingjs/vue", "name": "RegionRole" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "PlingUiOptions", "anchor": "api-plinguioptions", "name": "PlingUiOptions", "kind": "type", "summary": "共享助手界面的语言、主题、文案覆盖与类名。", "imports": [ "@plingjs/ui" ], "signature": "interface PlingUiOptions {\n locale?: PlingLocale;\n theme?: PlingTheme;\n messages?: PlingCatalogOverrides;\n classNames?: PlingClassNames;\n}", "parameters": [ { "name": "locale", "type": "\"en-US\" | \"zh-CN\" | \"auto\" | string", "required": false, "defaultValue": "en-US", "description": "Language used by the built-in assistant UI. \"auto\" follows the browser language.", "descriptionZh": "内置助手界面的语言。传 `auto` 时跟随浏览器语言。" }, { "name": "theme", "type": "\"light\" | \"dark\" | \"auto\" | PlingThemeOverrides", "required": false, "defaultValue": "light", "description": "Theme for the built-in surfaces. An object can override tokens or choose a mode.", "descriptionZh": "内置界面的主题。传对象时可选择模式或覆盖设计令牌。" }, { "name": "theme.mode", "type": "\"light\" | \"dark\" | \"auto\"", "required": false, "defaultValue": "light", "description": "Explicit mode when the theme is an object. \"auto\" follows the operating-system preference.", "descriptionZh": "主题传对象时指定的模式。`auto` 跟随操作系统外观。" }, { "name": "theme.tokens", "type": "Partial", "required": false, "defaultValue": "", "description": "Overrides individual design tokens such as colours, radii, shadows, and font families. Keys not supplied keep the selected light or dark defaults.", "descriptionZh": "覆盖颜色、圆角、阴影、字体等单个设计令牌。未提供的键沿用所选明色或暗色主题的默认值。" }, { "name": "messages", "type": "PlingCatalogOverrides", "required": false, "defaultValue": "", "description": "Adds or replaces message catalog entries for one or more locales.", "descriptionZh": "为一个或多个语言补充或替换界面文案。" }, { "name": "messages.", "type": "Partial>", "required": false, "defaultValue": "", "description": "Message overrides for one BCP 47 locale. Missing keys fall back to the built-in catalog.", "descriptionZh": "某个 BCP 47 语言的文案覆盖。未提供的键回退到内置文案。" }, { "name": "classNames", "type": "PlingClassNames", "required": false, "defaultValue": "", "description": "Extra class names applied to the built-in chat, dock, launcher, and panel.", "descriptionZh": "为内置对话、浮窗、启动按钮和面板附加 class。" }, { "name": "classNames.dock", "type": "string", "required": false, "defaultValue": "", "description": "Extra class for the dock shell.", "descriptionZh": "浮窗外壳的附加 class。" }, { "name": "classNames.panel", "type": "string", "required": false, "defaultValue": "", "description": "Extra class for the panel shell.", "descriptionZh": "面板外壳的附加 class。" }, { "name": "classNames.launcher", "type": "string", "required": false, "defaultValue": "", "description": "Extra class for the launcher button.", "descriptionZh": "启动按钮的附加 class。" }, { "name": "classNames.chat", "type": "string", "required": false, "defaultValue": "", "description": "Extra class for the chat surface.", "descriptionZh": "对话界面的附加 class。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Chinese UI with a token override", "titleZh": "中文界面与令牌覆盖", "code": "const ui = {\n locale: \"zh-CN\",\n theme: { mode: \"light\", tokens: { colorPrimary: \"#0b6bcb\" } },\n classNames: { dock: \"product-assistant\" },\n};", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/ui", "name": "PlingUiOptions" }, { "package": "@plingjs/vue", "name": "PlingUiOptions" } ], "reference": "/reference/ui-messages-theme-locale" } ] }, { "id": "runtime", "title": "Agent 运行时", "summary": "模型配置、会话、确认与人工接力、钩子、跟踪，以及共享运行时辅助函数。", "entries": [ { "id": "AgentRuntimeOptions", "anchor": "api-agentruntimeoptions", "name": "AgentRuntimeOptions", "kind": "type", "summary": "AgentSetup 背后的运行时契约：配置、注册表、模型、事件、钩子、闸门、跟踪与连续性。", "imports": [ "@plingjs/agent" ], "signature": "interface AgentRuntimeOptions {\n config: AgentConfig;\n registry?: Registry;\n llm?: Llm;\n responseLocale?: string | (() => string);\n telemetry?: Telemetry;\n trace?: boolean | AgentTraceOptions;\n settle?: () => Promise;\n hooks?: HookRegistry;\n onEvent?: SessionEventListener;\n onApproval?: (pending: PendingApproval | null) => void;\n onHandoff?: (pending: PendingHandoff | null) => void;\n gate?: () => boolean;\n policy?: ConfirmGate;\n approvalTimeoutMs?: number;\n handoffTimeoutMs?: number;\n handoff?: HandoffGate;\n id?: string;\n onLeaseLost?: () => void;\n continuity?: ContinuitySetting;\n}", "parameters": [ { "name": "config", "type": "AgentConfig", "required": true, "defaultValue": "", "description": "Fully resolved model and runtime configuration.", "descriptionZh": "已经解析完成的模型与运行时配置。" }, { "name": "registry", "type": "Registry", "required": false, "defaultValue": "", "description": "Page capability registry. Omit it for a chat-only runtime.", "descriptionZh": "页面能力注册表。纯聊天运行时可省略。" }, { "name": "llm", "type": "Llm", "required": false, "defaultValue": "", "description": "Injects the model call function. Use it for a test model, a server proxy, or a non-OpenAI-compatible transport.", "descriptionZh": "注入模型调用函数。可用于测试模型、服务端代理或非 OpenAI 兼容传输。" }, { "name": "responseLocale", "type": "string | (() => string)", "required": false, "defaultValue": "", "description": "Locale used when composing the response-language instruction. A function is re-read before each model request.", "descriptionZh": "拼接回答语言约束时使用的语言。传函数时，每次模型请求前重新读取。" }, { "name": "telemetry", "type": "Telemetry", "required": false, "defaultValue": "", "description": "Collects token, duration, cost, and retry metrics for the current runtime.", "descriptionZh": "收集当前运行时的 token、耗时、成本与重试指标。" }, { "name": "trace", "type": "boolean | AgentTraceOptions", "required": false, "defaultValue": "false", "description": "Keeps a bounded in-memory trace of model requests for the read-only inspector. Disabled by default.", "descriptionZh": "在内存中保留有界的模型请求记录，供只读诊断面板查看。默认关闭。" }, { "name": "settle", "type": "() => Promise", "required": false, "defaultValue": "", "description": "Replaces the page-settle wait used between actions. Most useful in deterministic tests and non-browser hosts.", "descriptionZh": "替换动作之间的页面落定等待。主要用于确定性测试和非浏览器宿主。" }, { "name": "hooks", "type": "HookRegistry", "required": false, "defaultValue": "", "description": "Tool lifecycle hooks shared by every surface created from this application runtime.", "descriptionZh": "由该应用运行时创建的界面共用的工具生命周期钩子。" }, { "name": "onEvent", "type": "(event: SessionEvent) => void", "required": false, "defaultValue": "", "description": "Receives the same session event stream that powers the chat and activity views.", "descriptionZh": "接收与对话、运行视图相同的会话事件流。" }, { "name": "onApproval", "type": "(pending: PendingApproval | null) => void", "required": false, "defaultValue": "", "description": "Called when an approval request appears or clears. Use it to connect a custom approval UI.", "descriptionZh": "确认请求出现或清除时调用。可用来接自己的确认界面。" }, { "name": "onHandoff", "type": "(pending: PendingHandoff | null) => void", "required": false, "defaultValue": "", "description": "Called when a human-handoff request appears or clears.", "descriptionZh": "人工接力请求出现或清除时调用。" }, { "name": "policy", "type": "ConfirmGate", "required": false, "defaultValue": "", "description": "Replaces the default approval gate. When provided, the built-in gate and chat approval buttons are not used.", "descriptionZh": "替换默认确认闸门。传入后不再使用内置闸门和对话中的确认按钮。" }, { "name": "approvalTimeoutMs", "type": "number", "required": false, "defaultValue": "60000", "description": "Time to wait for a human approval before treating it as denied.", "descriptionZh": "等待人工确认的最长时间；超时按拒绝处理。" }, { "name": "handoffTimeoutMs", "type": "number", "required": false, "defaultValue": "300000", "description": "Default time to wait for a human handoff. A tool-level handoff.timeout overrides it.", "descriptionZh": "人工接力的默认等待时间。单个工具的 `handoff.timeout` 可以覆盖。" }, { "name": "handoff", "type": "HandoffGate", "required": false, "defaultValue": "", "description": "Replaces the built-in handoff queue with a custom channel.", "descriptionZh": "用自定义通道替换内置人工接力队列。" }, { "name": "id", "type": "string", "required": false, "defaultValue": "", "description": "Stable session id for multi-session hosts.", "descriptionZh": "多会话宿主使用的稳定会话 id。" }, { "name": "onLeaseLost", "type": "() => void", "required": false, "defaultValue": "", "description": "Called when another tab or host takes over the shared session lease.", "descriptionZh": "共享会话租约被另一个标签页或宿主接管时调用。" }, { "name": "continuity", "type": "ContinuitySetting", "required": false, "defaultValue": "", "description": "Enables bounded conversation continuity across full-page navigation. \"tab\" uses sessionStorage. Omit to disable it.", "descriptionZh": "开启跨整页导航的有界对话连续性。`\"tab\"` 使用 sessionStorage；省略即关闭。" }, { "name": "gate", "type": "() => boolean", "required": false, "defaultValue": "true", "description": "Returns false to disable the built-in confirmation channel for this application. Defaults to enabled.", "descriptionZh": "返回 `false` 时关闭该应用的内置确认通道。默认开启。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Create a page-operating runtime", "titleZh": "创建可操作页面的运行时", "code": "const runtime = createAgentRuntime({\n config: resolveAgentConfig({ config: { model: \"gpt-4.1-mini\" } }),\n registry: pling.registry,\n hooks,\n trace: true,\n});", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "AgentRuntimeOptions" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "AgentConfigOverrides", "anchor": "api-agentconfigoverrides", "name": "AgentConfigOverrides", "kind": "type", "summary": "部分模型配置。未指定的字段继续来自环境变量与默认值。", "imports": [ "@plingjs/agent" ], "signature": "type AgentConfigOverrides =\n Partial> & {\n limits?: Partial;\n retry?: Partial;\n };", "parameters": [ { "name": "baseUrl", "type": "string", "required": false, "defaultValue": "\"\"", "description": "OpenAI-compatible API root. A relative path such as /llm/v1 routes through the application server and does not require a browser-side key.", "descriptionZh": "OpenAI 兼容接口根地址。`/llm/v1` 这类相对路径会经过应用服务器，不需要浏览器侧密钥。" }, { "name": "model", "type": "string", "required": false, "defaultValue": "\"\"", "description": "Model name sent to the provider.", "descriptionZh": "发给模型服务商模型名。" }, { "name": "apiKey", "type": "string", "required": false, "defaultValue": "\"\"", "description": "Browser-visible provider key. Leave empty when using a relative proxy URL.", "descriptionZh": "浏览器可见的服务商密钥。使用相对代理地址时应留空。" }, { "name": "temperature", "type": "number", "required": false, "defaultValue": "0.3", "description": "Sampling temperature for model responses.", "descriptionZh": "模型回答的采样温度。" }, { "name": "maxTokens", "type": "number", "required": false, "defaultValue": "1024", "description": "Maximum output tokens for one model response. This is not the conversation context budget.", "descriptionZh": "单次模型响应的最大输出 token。它不是整个对话的上下文预算。" }, { "name": "systemPrompt", "type": "string", "required": false, "defaultValue": "\"\"", "description": "Application-specific instructions appended after the framework rules. It does not replace the framework rules.", "descriptionZh": "追加在框架规则之后的应用说明。不会替换框架规则。" }, { "name": "stream", "type": "boolean", "required": false, "defaultValue": "true", "description": "Uses streaming when the provider supports it.", "descriptionZh": "服务商支持时使用流式响应。" }, { "name": "defaultApproval", "type": "\"danger\" | \"kind\"", "required": false, "defaultValue": "\"danger\"", "description": "Declaration-time approval policy for tools that omit confirm.", "descriptionZh": "工具未写 `confirm` 时的声明期确认策略。" }, { "name": "minActionIntervalMs", "type": "number", "required": false, "defaultValue": "0", "description": "Minimum delay between actions in the same model turn. Useful when UI transitions need to remain visible.", "descriptionZh": "同一模型轮次内两个动作之间的最小间隔。需要让界面过渡可见时使用。" }, { "name": "retry.maxRetries", "type": "number", "required": false, "defaultValue": "3", "description": "Additional model-request retries after the first attempt. Valid range is 0–5.", "descriptionZh": "首次请求之外的重试次数。有效范围 0–5。" }, { "name": "retry.baseDelayMs", "type": "number", "required": false, "defaultValue": "500", "description": "Initial exponential-backoff delay.", "descriptionZh": "指数退避的初始延迟。" }, { "name": "retry.maxDelayMs", "type": "number", "required": false, "defaultValue": "4000", "description": "Maximum delay for one retry.", "descriptionZh": "单次重试的最大延迟。" }, { "name": "limits.maxTurns", "type": "number", "required": false, "defaultValue": "10", "description": "Maximum model/tool round trips within one send.", "descriptionZh": "一次发送内最大的模型/工具往返轮数。" }, { "name": "limits.contextTokens", "type": "number", "required": false, "defaultValue": "8192", "description": "Estimated conversation context budget.", "descriptionZh": "估算的对话上下文预算。" }, { "name": "limits.reserveForOutput", "type": "number", "required": false, "defaultValue": "1024", "description": "Tokens reserved for the model response inside the context budget.", "descriptionZh": "上下文预算中预留给模型输出的 token。" }, { "name": "limits.compactRatio", "type": "number", "required": false, "defaultValue": "0.8", "description": "History is compacted when estimated usage reaches this ratio of the usable budget. Valid range is (0, 1].", "descriptionZh": "估算用量达到可用预算的该比例时压缩历史。有效范围 `(0, 1]`。" }, { "name": "limits.keepRecent", "type": "number", "required": false, "defaultValue": "6", "description": "Recent history entries kept verbatim during compaction.", "descriptionZh": "压缩历史时原样保留的最近条目数。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Override only the necessary fields", "titleZh": "只覆盖必要的字段", "code": "const config = {\n model: \"gpt-4.1-mini\",\n maxTokens: 1600,\n limits: { maxTurns: 14, keepRecent: 8 },\n retry: { maxRetries: 2 },\n};", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "AgentConfigOverrides" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "HookRegistry", "anchor": "api-hookregistry", "name": "HookRegistry", "kind": "class", "summary": "PreToolUse 与 PostToolUse 钩子，用于应用策略、脱敏与审计，不引入第二套执行器。", "imports": [ "@plingjs/agent" ], "signature": "class HookRegistry {\n addPreToolUse(handler: PreToolUseHandler): () => void;\n addPostToolUse(handler: PostToolUseHandler): () => void;\n firePreToolUse(payload: PreToolUsePayload): Promise<{ blocked: boolean; reason?: string }>;\n firePostToolUse(payload: PostToolUsePayload): Promise;\n}", "parameters": [ { "name": "addPreToolUse(handler)", "type": "PreToolUseHandler", "required": false, "defaultValue": "", "description": "Adds a hook before execution. Returns an unsubscribe function. Returning { blocked: true, reason } stops the tool.", "descriptionZh": "增加执行前钩子，返回移除函数。返回 `{ blocked: true, reason }` 会阻止工具执行。" }, { "name": "addPostToolUse(handler)", "type": "PostToolUseHandler", "required": false, "defaultValue": "", "description": "Adds a hook after execution. It may return a replacement ExecResult for later hooks and the caller.", "descriptionZh": "增加执行后钩子。可返回替换后的 `ExecResult`，供后续钩子与调用方使用。" }, { "name": "payload.id", "type": "string", "required": false, "defaultValue": "", "description": "Original page action id.", "descriptionZh": "页面声明里的原始动作 id。" }, { "name": "payload.tool", "type": "string", "required": false, "defaultValue": "", "description": "Model-facing legal tool name.", "descriptionZh": "发给模型的合法化工具名。" }, { "name": "payload.args", "type": "Record", "required": false, "defaultValue": "", "description": "Validated call arguments.", "descriptionZh": "校验后的调用参数。" }, { "name": "payload.turn", "type": "number", "required": false, "defaultValue": "", "description": "Current model/tool turn.", "descriptionZh": "当前模型/工具轮次。" }, { "name": "payload.result", "type": "ExecResult", "required": false, "defaultValue": "", "description": "Post-hook only: current execution result before this hook runs.", "descriptionZh": "仅执行后钩子：当前钩子运行前的执行结果。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Block and rewrite tool results", "titleZh": "拦截并改写工具结果", "code": "const hooks = new HookRegistry();\nhooks.addPreToolUse(({ id }) => id === \"delete_all\" ? { blocked: true, reason: \"批量删除已禁用\" } : undefined);\nhooks.addPostToolUse(({ result }) => redactResult(result));", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "HookRegistry" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "SessionEvent", "anchor": "api-sessionevent", "name": "SessionEvent", "kind": "type", "summary": "对话、运行记录、审计与评测视图共同消费的单一事件流。", "imports": [ "@plingjs/agent" ], "signature": "type SessionEvent =\n | { type: \"user\"; text: string }\n | { type: \"assistant\"; text: string }\n | { type: \"assistant_delta\"; text: string }\n | { type: \"tool_call\"; id: string; tool: string; args: Record }\n | { type: \"tool_result\"; id: string; tool: string; result: ExecResult }\n | { type: \"blocked\"; id: string; tool: string; reason: string }\n | { type: \"handoff\"; id: string; tool: string; status: \"requested\" | \"completed\" | \"cancelled\" | \"timeout\"; reason: string }\n | { type: \"notice\"; text: string }\n | { type: \"final\"; text: string }\n | { type: \"cancelled\" }\n | { type: \"error\"; code: string; message: string; messageKey?: string; params?: MessageParams };", "parameters": [ { "name": "type: \"user\"", "type": "{ text: string }", "required": false, "defaultValue": "", "description": "Echo of the user's input.", "descriptionZh": "用户输入回显。" }, { "name": "type: \"assistant\"", "type": "{ text: string }", "required": false, "defaultValue": "", "description": "Non-final assistant narration.", "descriptionZh": "非最终的助手说明。" }, { "name": "type: \"assistant_delta\"", "type": "{ text: string }", "required": false, "defaultValue": "", "description": "Streaming increment, not accumulated text.", "descriptionZh": "流式增量，不是累计文本。" }, { "name": "type: \"tool_call\"", "type": "{ id; tool; args }", "required": false, "defaultValue": "", "description": "A tool is about to execute.", "descriptionZh": "工具即将执行。" }, { "name": "type: \"tool_result\"", "type": "{ id; tool; result: ExecResult }", "required": false, "defaultValue": "", "description": "The structured result of a tool call.", "descriptionZh": "工具调用的结构化结果。" }, { "name": "type: \"blocked\"", "type": "{ id; tool; reason }", "required": false, "defaultValue": "", "description": "A hook blocked the tool before execution.", "descriptionZh": "钩子在执行前阻止了工具。" }, { "name": "type: \"handoff\"", "type": "{ id; tool; status; reason }", "required": false, "defaultValue": "", "description": "Human handoff requested or resolved.", "descriptionZh": "人工接力的请求或结果。" }, { "name": "type: \"notice\"", "type": "{ text: string }", "required": false, "defaultValue": "", "description": "Loop-level guidance such as a turn limit or empty response.", "descriptionZh": "轮数上限、空回复等循环级提示。" }, { "name": "type: \"final\"", "type": "{ text: string }", "required": false, "defaultValue": "", "description": "Final assistant answer for this send.", "descriptionZh": "本次发送的最终助手回答。" }, { "name": "type: \"cancelled\"", "type": "{}", "required": false, "defaultValue": "", "description": "The user cancelled the run.", "descriptionZh": "用户取消了本次运行。" }, { "name": "type: \"error\"", "type": "{ code; message; messageKey?; params? }", "required": false, "defaultValue": "", "description": "A loop or model error. code remains the authoritative identifier.", "descriptionZh": "循环或模型错误。`code` 仍是权威标识。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Audit the event stream", "titleZh": "审计事件流", "code": "for await (const event of runtime.session.events) {\n if (event.type === \"tool_result\") audit(event);\n}", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "SessionEvent" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "AgentTraceOptions", "anchor": "api-agenttraceoptions", "name": "AgentTraceOptions", "kind": "type", "summary": "限制只读调试器保留的模型调用数量。", "imports": [ "@plingjs/agent" ], "signature": "interface AgentTraceOptions { maxCalls?: number }", "parameters": [ { "name": "maxCalls", "type": "number", "required": false, "defaultValue": "20", "description": "Maximum model calls retained in the in-memory inspector. Omit it to use the default; lower values bound memory in long sessions.", "descriptionZh": "内存诊断器保留的最大模型调用数。省略时使用默认值；长会话可调低以限制内存。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Keep the last eight calls", "titleZh": "只保留最近八次调用", "code": "const trace = { maxCalls: 8 };", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "AgentTraceOptions" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "waitFor", "anchor": "api-waitfor", "name": "waitFor", "kind": "function", "summary": "在 run 或结果判据中等待异步 UI 条件成立。", "imports": [ "@plingjs/core" ], "signature": "waitFor(check: () => boolean | Promise, options?: WaitForOptions): Promise", "parameters": [ { "name": "check", "type": "() => boolean | Promise", "required": true, "defaultValue": "", "description": "Predicate to evaluate. It is checked immediately and then at the configured interval.", "descriptionZh": "要判断的条件。先立即检查一次，之后按间隔轮询。" }, { "name": "options.timeout", "type": "number", "required": false, "defaultValue": "2000", "description": "Maximum wait. Zero checks once without waiting. Timeout returns false rather than throwing.", "descriptionZh": "最长等待时间。传 `0` 只检查一次。超时返回 `false`，不抛异常。" }, { "name": "options.interval", "type": "number", "required": false, "defaultValue": "30", "description": "Delay between checks.", "descriptionZh": "两次检查之间的延迟。" }, { "name": "options.now", "type": "() => number", "required": false, "defaultValue": "", "description": "Clock injection for deterministic tests.", "descriptionZh": "供确定性测试注入时钟。" }, { "name": "options.sleep", "type": "(ms: number) => Promise", "required": false, "defaultValue": "", "description": "Sleep injection for deterministic tests.", "descriptionZh": "供确定性测试注入等待函数。" }, { "name": "options.signal", "type": "AbortSignal", "required": false, "defaultValue": "", "description": "Cancels the wait and returns false as soon as it is aborted.", "descriptionZh": "取消等待；一旦中止立即返回 `false`。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Wait inside a custom runner", "titleZh": "在自定义执行函数中等待", "code": "await waitFor(() => document.querySelector(\".saved\"), { timeout: 1500 });", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "waitFor" }, { "package": "@plingjs/vue", "name": "waitFor" } ], "reference": "/reference/core-declarations-actions-records-regions-state" }, { "id": "describeFlow", "anchor": "api-describeflow", "name": "describeFlow", "kind": "function", "summary": "生成复合动作的模型可读说明，不执行动作。", "imports": [ "@plingjs/core" ], "signature": "describeFlow(report: FlowReport): string", "parameters": [ { "name": "report", "type": "FlowReport", "required": true, "defaultValue": "", "description": "Result returned by a flow execution. The formatter reports completed, failed, skipped, handoff, and expectation states.", "descriptionZh": "流程执行返回的结果。格式化后会报告完成、失败、跳过、人工接力与成功判据状态。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Render a flow receipt", "titleZh": "渲染流程回执", "code": "const text = describeFlow(result.resume?.report ?? report);", "lang": "ts" } ], "support": { "vue3": "native", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "describeFlow" }, { "package": "@plingjs/vue", "name": "describeFlow" } ], "reference": "/reference/core-declarations-actions-records-regions-state" } ] }, { "id": "page", "title": "页面身份与连续性", "summary": "读取页面身份、在同源框架间共享运行时，并检查声明覆盖率。", "entries": [ { "id": "PlingPage", "anchor": "api-plingpage", "name": "PlingPage", "kind": "interface", "summary": "由多个框架岛或同源 iframe 共享的页面级运行时。", "imports": [ "@plingjs/dom" ], "signature": "interface PlingPage {\n readonly registry: Registry;\n readonly scopes: ScopeController;\n readonly feedback: FeedbackCollector;\n destroy(): void;\n}", "parameters": [ { "name": "registry", "type": "Registry", "required": false, "defaultValue": "", "description": "Shared action, record, state, and feedback registry.", "descriptionZh": "共享的动作、记录、状态与反馈注册表。" }, { "name": "scopes", "type": "ScopeController", "required": false, "defaultValue": "", "description": "Shared region visibility and occlusion controller.", "descriptionZh": "共享的区域可见性与遮挡控制器。" }, { "name": "feedback", "type": "FeedbackCollector", "required": false, "defaultValue": "", "description": "Page-level feedback collector that observes the document once.", "descriptionZh": "每个页面只观察一次文档的反馈收集器。" }, { "name": "destroy()", "type": "void", "required": false, "defaultValue": "", "description": "Stops page observers and clears automatic scopes. Adapters should destroy their declarations first.", "descriptionZh": "停止页面观察器并清空自动区域。适配器应先释放自己的声明。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Share one page runtime", "titleZh": "共享一个页面运行时", "code": "const page = createPlingPage();\nconst vuePling = createPling({ shared: page });\nconst reactPling = createPling({ shared: page });", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "native" }, "symbols": [ { "package": "@plingjs/dom", "name": "PlingPage" }, { "package": "@plingjs/vue", "name": "PlingPage" }, { "package": "@plingjs/react", "name": "PlingPage" }, { "package": "@plingjs/vanilla", "name": "PlingPage" } ], "reference": "/reference/continuity-and-projection" }, { "id": "createPlingPage", "anchor": "api-createplingpage", "name": "createPlingPage", "kind": "function", "summary": "创建共享注册表、作用域与页面身份，适配器可通过 shared 加入。", "imports": [ "@plingjs/dom" ], "signature": "createPlingPage(options?: PlingPageOptions): PlingPage", "parameters": [ { "name": "options.registry", "type": "Registry", "required": false, "defaultValue": "", "description": "Existing registry to share. A new registry is created when omitted.", "descriptionZh": "要共享的已有注册表。省略时新建一个。" }, { "name": "options.scopes", "type": "ScopeControllerOptions", "required": false, "defaultValue": "", "description": "Visibility and hit-testing overrides for the shared page.", "descriptionZh": "共享页面的可见性与命中测试覆盖项。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Create a mixed-framework page runtime", "titleZh": "创建混合框架页面运行时", "code": "const page = createPlingPage();\n\n// Pass the same page to Vue, React, or Vanilla islands:\nconst pling = createPling({ shared: page, namespace: \"orders\" });", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "native" }, "symbols": [ { "package": "@plingjs/dom", "name": "createPlingPage" }, { "package": "@plingjs/vue", "name": "createPlingPage" }, { "package": "@plingjs/react", "name": "createPlingPage" }, { "package": "@plingjs/vanilla", "name": "createPlingPage" } ], "reference": "/reference/continuity-and-projection" }, { "id": "sharePlingPageWithFrame", "anchor": "api-shareplingpagewithframe", "name": "sharePlingPageWithFrame", "kind": "function", "summary": "把页面运行时共享给同源 iframe，并返回清理函数。", "imports": [ "@plingjs/dom" ], "signature": "sharePlingPageWithFrame(frame: HTMLIFrameElement, page: PlingPage): () => void", "parameters": [ { "name": "frame", "type": "HTMLIFrameElement", "required": true, "defaultValue": "", "description": "Same-origin iframe that should receive the shared page runtime.", "descriptionZh": "接收共享页面运行时的同源 iframe。" }, { "name": "page", "type": "PlingPage", "required": true, "defaultValue": "", "description": "Runtime created by createPlingPage.", "descriptionZh": "由 `createPlingPage` 创建的运行时。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Share a runtime with a same-origin frame", "titleZh": "向同源 iframe 共享运行时", "code": "const page = createPlingPage();\nconst stop = sharePlingPageWithFrame(iframe, page);\n\n// On teardown:\nstop();\npage.destroy();", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "native" }, "symbols": [ { "package": "@plingjs/dom", "name": "sharePlingPageWithFrame" }, { "package": "@plingjs/vue", "name": "sharePlingPageWithFrame" }, { "package": "@plingjs/react", "name": "sharePlingPageWithFrame" }, { "package": "@plingjs/vanilla", "name": "sharePlingPageWithFrame" } ], "reference": "/reference/continuity-and-projection" }, { "id": "plingPageFromParent", "anchor": "api-plingpagefromparent", "name": "plingPageFromParent", "kind": "function", "summary": "当前文档是嵌入 frame 时，从父窗口读取共享页面运行时。", "imports": [ "@plingjs/dom" ], "signature": "plingPageFromParent(win?: Window): PlingPage | undefined", "parameters": [ { "name": "win", "type": "Window", "required": false, "defaultValue": "window", "description": "Window whose parent should be checked. Defaults to the current window.", "descriptionZh": "要检查父窗口的窗口对象。默认当前窗口。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Read a shared page synchronously", "titleZh": "同步读取共享页面运行时", "code": "const page = plingPageFromParent();\nif (page) createPling({ shared: page });", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "native" }, "symbols": [ { "package": "@plingjs/dom", "name": "plingPageFromParent" }, { "package": "@plingjs/vue", "name": "plingPageFromParent" }, { "package": "@plingjs/react", "name": "plingPageFromParent" }, { "package": "@plingjs/vanilla", "name": "plingPageFromParent" } ], "reference": "/reference/continuity-and-projection" }, { "id": "waitForPlingPageFromParent", "anchor": "api-waitforplingpagefromparent", "name": "waitForPlingPageFromParent", "kind": "function", "summary": "等待父 frame 发布页面运行时。", "imports": [ "@plingjs/dom" ], "signature": "waitForPlingPageFromParent(options?: WaitForFramePageOptions): Promise", "parameters": [ { "name": "options.window", "type": "Window", "required": false, "defaultValue": "window", "description": "Child window to listen on. Defaults to the current window.", "descriptionZh": "要监听的子窗口。默认当前窗口。" }, { "name": "options.timeoutMs", "type": "number", "required": false, "defaultValue": "5000", "description": "Maximum wait. Zero waits indefinitely. Rejects when another positive timeout expires.", "descriptionZh": "最长等待时间。传 `0` 表示一直等；其他正数超时后 Promise 会拒绝。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Wait for the parent runtime", "titleZh": "等待父页面运行时", "code": "const page = await waitForPlingPageFromParent({ timeoutMs: 8000 });\ncreatePling({ shared: page });", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "native" }, "symbols": [ { "package": "@plingjs/dom", "name": "waitForPlingPageFromParent" }, { "package": "@plingjs/vue", "name": "waitForPlingPageFromParent" }, { "package": "@plingjs/react", "name": "waitForPlingPageFromParent" }, { "package": "@plingjs/vanilla", "name": "waitForPlingPageFromParent" } ], "reference": "/reference/continuity-and-projection" }, { "id": "inspectCoverage", "anchor": "api-inspectcoverage", "name": "inspectCoverage", "kind": "method", "summary": "扫描已挂载页面中尚未声明的交互控件。它只报告，不注册动作。", "imports": [ "@plingjs/dom" ], "signature": "inspectCoverage(root: Element | null): CoverageReport", "parameters": [ { "name": "root", "type": "Element | null", "required": false, "defaultValue": "", "description": "Application root to scan. Vue uses its mount root; React and DOM callers may pass any root.", "descriptionZh": "要扫描的应用根。Vue 使用挂载根；React 与原生调用方可传任意根元素。" }, { "name": "return.total", "type": "number", "required": false, "defaultValue": "", "description": "Recognized actionable controls in the root.", "descriptionZh": "根元素内识别到的可操作控件总数。" }, { "name": "return.declared", "type": "number", "required": false, "defaultValue": "", "description": "Controls with a direct declaration.", "descriptionZh": "有直接声明的控件数。" }, { "name": "return.derived", "type": "number", "required": false, "defaultValue": "", "description": "Controls produced by optional L1 derivation.", "descriptionZh": "由可选 L1 派生生成的动作数。" }, { "name": "return.grouped", "type": "number", "required": false, "defaultValue": "", "description": "Controls covered by a declaration on an ancestor. Review these manually.", "descriptionZh": "由祖先声明覆盖的控件数。需要人工复核映射关系。" }, { "name": "return.missing", "type": "number", "required": false, "defaultValue": "", "description": "Actionable controls with no declaration in their ancestry.", "descriptionZh": "祖先链上没有任何声明的可操作控件数。" }, { "name": "return.coveragePercent", "type": "number | null", "required": false, "defaultValue": "", "description": "Covered controls divided by total; null when there are no controls.", "descriptionZh": "覆盖控件数除以总数；没有控件时为 `null`。" }, { "name": "return.targets", "type": "CoverageTarget[]", "required": false, "defaultValue": "", "description": "Grouped and missing controls with labels and nearby action ids.", "descriptionZh": "分组与缺失控件列表，包含标签和附近动作 id。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Inspect a DOM root", "titleZh": "检查 DOM 根元素", "code": "const report = inspectCoverage(document.querySelector(\"#app\"));", "lang": "ts" } ], "support": { "vue3": "native", "react": "native", "vue2": "none", "vanilla": "none" }, "symbols": [ { "package": "@plingjs/dom", "name": "inspectCoverage" } ], "reference": "/reference/vue-3-adapter" } ] }, { "id": "testing", "title": "测试与执行辅助", "summary": "用于测试、外部 Agent 与高级宿主的确定性模型回放、评测、页面上下文渲染与核心执行器。", "entries": [ { "id": "createReplayLlm", "anchor": "api-createreplayllm", "name": "createReplayLlm", "kind": "function", "summary": "用预先写好的轮次创建确定性模型。它走真实的循环、工具分发、确认与失败路径，但不需要网络。", "imports": [ "@plingjs/agent" ], "signature": "createReplayLlm(turns: readonly ReplayTurn[]): ReplayLlm", "parameters": [ { "name": "turns[].content", "type": "string", "required": false, "defaultValue": "", "description": "Assistant text returned for that turn.", "descriptionZh": "该轮返回的助手文本。" }, { "name": "turns[].calls", "type": "readonly ReplayCall[]", "required": false, "defaultValue": "", "description": "Tool calls requested in that turn.", "descriptionZh": "该轮请求的工具调用。" }, { "name": "turns[].calls[].tool", "type": "string", "required": true, "defaultValue": "", "description": "Original page action id. The replay adapter converts it to the model-facing tool name.", "descriptionZh": "页面原始动作 id。replay 适配器会转换为模型工具名。" }, { "name": "turns[].calls[].args", "type": "Record", "required": false, "defaultValue": "", "description": "Arguments serialized into the tool call.", "descriptionZh": "序列化进工具调用的参数。" }, { "name": "turns[].calls[].id", "type": "string", "required": false, "defaultValue": "", "description": "Explicit tool-call id. A deterministic id is generated when omitted.", "descriptionZh": "显式工具调用 id。省略时生成确定性 id。" } ], "definition": "interface ReplayCall {\n tool: string;\n args?: Record;\n id?: string;\n}\n\ninterface ReplayTurn {\n content?: string;\n calls?: readonly ReplayCall[];\n}\n\ninterface ReplayLlm extends Llm {\n readonly received: readonly (readonly LlmMessage[])[];\n readonly toolsSeen: readonly (readonly LlmToolSchema[])[];\n readonly turn: number;\n reset(): void;\n}", "returns": null, "defaults": [], "examples": [ { "title": "Replay a two-step task", "titleZh": "回放两步任务", "code": "const llm = createReplayLlm([\n { content: \"先添加待办。\", calls: [{ tool: \"add_task\", args: { text: \"准备发布\" } }] },\n { content: \"已经添加。\" },\n]);", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "createReplayLlm" }, { "package": "@plingjs/agent", "name": "ReplayTurn" }, { "package": "@plingjs/agent", "name": "ReplayLlm" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "EvalCase", "anchor": "api-evalcase", "name": "EvalCase", "kind": "type", "summary": "一条评测用例：输入、期望与禁止调用的动作、可选工具错误预算，以及业务状态检查。", "imports": [ "@plingjs/agent" ], "signature": "interface EvalCase {\n name?: string;\n input: string;\n expectIncludes?: readonly string[];\n expectTools?: readonly string[];\n expectNotTools?: readonly string[];\n maxToolErrors?: number;\n verify?: () => boolean | Promise;\n}", "parameters": [ { "name": "name", "type": "string", "required": false, "defaultValue": "", "description": "Display name. Defaults to the input text.", "descriptionZh": "显示名称。默认使用输入文本。" }, { "name": "input", "type": "string", "required": true, "defaultValue": "", "description": "User message sent to the evaluated agent run.", "descriptionZh": "发给被评估 agent 运行的用户消息。" }, { "name": "expectIncludes", "type": "readonly string[]", "required": false, "defaultValue": "", "description": "Strings that must appear in the final answer.", "descriptionZh": "最终回答中必须出现的字符串。" }, { "name": "expectTools", "type": "readonly string[]", "required": false, "defaultValue": "", "description": "Action ids that must be called.", "descriptionZh": "必须调用的动作 id。" }, { "name": "expectNotTools", "type": "readonly string[]", "required": false, "defaultValue": "", "description": "Action ids that must not be called.", "descriptionZh": "不得调用的动作 id。" }, { "name": "maxToolErrors", "type": "number", "required": false, "defaultValue": "", "description": "Maximum number of tool errors allowed for the case.", "descriptionZh": "该用例允许的最大工具错误数。" }, { "name": "verify", "type": "() => boolean | Promise", "required": false, "defaultValue": "", "description": "Business-state assertion executed after the run.", "descriptionZh": "运行结束后执行的业务状态断言。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Assert a completed task", "titleZh": "断言任务完成", "code": "const testCase = {\n name: \"完成第一条待办\",\n input: \"把第一条待办标记为完成\",\n expectTools: [\"toggle_task\"],\n expectNotTools: [\"delete_task\"],\n verify: () => todos[0].done === true,\n};", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "EvalCase" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "runEvaluation", "anchor": "api-runevaluation", "name": "runEvaluation", "kind": "function", "summary": "通过同一个宿主回调运行一组 EvalCase，在用例之间重置状态，并返回通过/失败报告。", "imports": [ "@plingjs/agent" ], "signature": "runEvaluation(options: EvaluateOptions): Promise", "parameters": [ { "name": "run", "type": "(input: string) => Promise", "required": true, "defaultValue": "", "description": "Executes one case and returns the final assistant answer.", "descriptionZh": "执行一个用例并返回最终助手回答。" }, { "name": "hooks", "type": "HookRegistry", "required": true, "defaultValue": "", "description": "Hooks whose pre/post events are observed for this evaluation.", "descriptionZh": "评估期间用于观察执行前/后事件的钩子注册表。" }, { "name": "cases", "type": "readonly EvalCase[]", "required": true, "defaultValue": "", "description": "Cases to run in order.", "descriptionZh": "按顺序运行的用例。" }, { "name": "reset", "type": "() => void | Promise", "required": false, "defaultValue": "", "description": "Resets application state between cases.", "descriptionZh": "用例之间重置应用状态。" }, { "name": "measure", "type": "() => EvalMetrics", "required": false, "defaultValue": "", "description": "Returns tokens, duration, cost, or other numeric metrics per case.", "descriptionZh": "返回每个用例的 token、耗时、成本或其他数值指标。" }, { "name": "events", "type": "() => readonly SessionEvent[]", "required": false, "defaultValue": "", "description": "Returns the event stream for the most recent run.", "descriptionZh": "返回最近一次运行的事件流。" } ], "definition": "interface EvaluateOptions {\n run: (input: string) => Promise;\n hooks: HookRegistry;\n cases: readonly EvalCase[];\n reset?: () => void | Promise;\n measure?: () => EvalMetrics;\n events?: () => readonly SessionEvent[];\n}", "returns": null, "defaults": [], "examples": [ { "title": "Run a small deterministic suite", "titleZh": "运行小型确定性用例集", "code": "const report = await runEvaluation({\n run: (input) => session.send(input),\n hooks,\n cases: [completeFirstTodo],\n reset: () => store.reset(),\n});\nconsole.log(formatReport(report));", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "runEvaluation" }, { "package": "@plingjs/agent", "name": "EvalReport" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "createAgentLoop", "anchor": "api-createagentloop", "name": "createAgentLoop", "kind": "function", "summary": "为测试与自定义宿主创建较低层的对话循环。大多数应用应使用 AgentSetup 或 createAgentRuntime。", "imports": [ "@plingjs/agent" ], "signature": "createAgentLoop(options: LoopOptions): AgentLoop", "parameters": [ { "name": "llm", "type": "Llm", "required": true, "defaultValue": "", "description": "Model call implementation.", "descriptionZh": "模型调用实现。" }, { "name": "registry", "type": "Registry", "required": false, "defaultValue": "", "description": "Page capability registry. Omit it for a chat-only loop.", "descriptionZh": "页面能力注册表。纯聊天循环可省略。" }, { "name": "policy", "type": "ConfirmGate", "required": false, "defaultValue": "", "description": "Approval gate. Omit it for fail-closed behavior when a tool needs approval.", "descriptionZh": "确认闸门。省略时，需要确认的工具按 fail-closed 拒绝。" }, { "name": "handoff", "type": "HandoffGate", "required": false, "defaultValue": "", "description": "Human-handoff gate. Omit it to fail handoff tools rather than simulate them.", "descriptionZh": "人工接力通道。省略时人工接力工具会失败，而不是被模拟执行。" }, { "name": "systemPrompt", "type": "string", "required": false, "defaultValue": "", "description": "Additional system instructions. Framework rules remain in force.", "descriptionZh": "附加系统说明。框架规则仍然有效。" }, { "name": "responseLocale", "type": "string | (() => string)", "required": false, "defaultValue": "", "description": "Response-language hint; a function is re-read each turn.", "descriptionZh": "回答语言提示；传函数时每轮重新读取。" }, { "name": "context", "type": "ContextOptions", "required": false, "defaultValue": "", "description": "Bounds for actions, records, state, scopes, feedback, and page identity in model context.", "descriptionZh": "模型上下文中动作、记录、状态、区域、反馈与页面身份的有界设置。" }, { "name": "history", "type": "HistoryOptions", "required": false, "defaultValue": "", "description": "Context budget, compaction threshold, recent retention, and tool-result cap.", "descriptionZh": "上下文预算、压缩水位、最近条目保留数与工具结果上限。" }, { "name": "historyState", "type": "HistorySnapshot", "required": false, "defaultValue": "", "description": "Restores a summary and message list from a checkpoint. System context is rebuilt for the current page.", "descriptionZh": "从检查点恢复摘要与消息；系统上下文会按当前页面重建。" }, { "name": "hooks", "type": "HookRegistry", "required": false, "defaultValue": "", "description": "Tool lifecycle hooks.", "descriptionZh": "工具生命周期钩子。" }, { "name": "telemetry", "type": "Telemetry", "required": false, "defaultValue": "", "description": "Token, duration, cost, and retry metrics.", "descriptionZh": "token、耗时、成本与重试指标。" }, { "name": "trace", "type": "AgentTraceRecorder", "required": false, "defaultValue": "", "description": "Bounded request trace for diagnostics.", "descriptionZh": "用于诊断的有界请求记录。" }, { "name": "maxTurns", "type": "number", "required": false, "defaultValue": "10", "description": "Maximum model/tool round trips in one run.", "descriptionZh": "一次运行内最大的模型/工具往返轮数。" }, { "name": "loopThreshold", "type": "number", "required": false, "defaultValue": "", "description": "Repeated identical tool calls before LOOP_DETECTED.", "descriptionZh": "相同工具与参数重复达到多少次后报告 `LOOP_DETECTED`。" }, { "name": "errorBudget", "type": "number", "required": false, "defaultValue": "", "description": "Cumulative tool failures before the loop asks the model to answer directly.", "descriptionZh": "累计多少次工具失败后，要求模型直接回答。" }, { "name": "maxNudges", "type": "number", "required": false, "defaultValue": "", "description": "Consecutive empty model replies allowed before stopping.", "descriptionZh": "模型连续空回复多少次后停止。" }, { "name": "settle", "type": "() => Promise", "required": false, "defaultValue": "", "description": "Waits for DOM, animation, and navigation to settle before snapshots.", "descriptionZh": "取快照前等待 DOM、动画与导航落定。" }, { "name": "minActionIntervalMs", "type": "number", "required": false, "defaultValue": "0", "description": "Minimum delay between actions in one model turn.", "descriptionZh": "同一模型轮次内动作之间的最小间隔。" }, { "name": "sleep", "type": "(ms: number) => Promise", "required": false, "defaultValue": "", "description": "Sleep injection for deterministic tests.", "descriptionZh": "供确定性测试注入等待函数。" }, { "name": "shouldStop", "type": "() => boolean", "required": false, "defaultValue": "", "description": "Cooperative cancellation checked at safe points.", "descriptionZh": "在安全点检查协作式取消。" }, { "name": "observe", "type": "(id: string, args: Record) => void | Promise", "required": false, "defaultValue": "", "description": "Post-action observation hook supplied to the executor.", "descriptionZh": "传给执行器的动作后观察钩子。" }, { "name": "evidence", "type": "boolean", "required": false, "defaultValue": "true", "description": "Captures before/after snapshots and attaches changed evidence.", "descriptionZh": "抓取动作前后快照并附带变更证据。" }, { "name": "onEvent", "type": "(event: SessionEvent) => void", "required": false, "defaultValue": "", "description": "Session event callback.", "descriptionZh": "会话事件回调。" }, { "name": "now", "type": "() => number", "required": false, "defaultValue": "", "description": "Clock injection for deterministic tests.", "descriptionZh": "供确定性测试注入时钟。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Create a page-operating loop", "titleZh": "创建页面操作循环", "code": "const loop = createAgentLoop({\n llm,\n registry: pling.registry,\n policy: createPolicy(confirm),\n maxTurns: 12,\n evidence: true,\n});", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "createAgentLoop" }, { "package": "@plingjs/agent", "name": "AgentLoop" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "defaultSettle", "anchor": "api-defaultsettle", "name": "defaultSettle", "kind": "function", "summary": "在读取下一份页面快照前，等待 DOM 更新、一个浏览器帧与短暂的静默窗口。", "imports": [ "@plingjs/agent" ], "signature": "defaultSettle(): Promise", "parameters": [], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Use the browser settle strategy", "titleZh": "使用浏览器落定策略", "code": "const settle = defaultSettle;", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "defaultSettle" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "renderPageContext", "anchor": "api-renderpagecontext", "name": "renderPageContext", "kind": "function", "summary": "渲染发给模型的有界页面上下文：区域、动作、记录、状态、反馈与页面身份。", "imports": [ "@plingjs/agent" ], "signature": "renderPageContext(snapshot: Snapshot, options?: ContextOptions): string", "parameters": [ { "name": "snapshot", "type": "Snapshot", "required": true, "defaultValue": "", "description": "Bounded page snapshot produced by the registry.", "descriptionZh": "注册表生成的有界页面快照。" }, { "name": "options.maxActions", "type": "number", "required": false, "defaultValue": "40", "description": "Maximum actions listed, default 40.", "descriptionZh": "最多列出的动作数，默认 40。" }, { "name": "options.maxRecords", "type": "number", "required": false, "defaultValue": "20", "description": "Maximum record rows listed, default 20.", "descriptionZh": "最多列出的记录行数，默认 20。" }, { "name": "options.includeState", "type": "boolean", "required": false, "defaultValue": "true", "description": "Whether read-only state views are included.", "descriptionZh": "是否包含只读状态视图。" }, { "name": "options.maxIdsInHint", "type": "number", "required": false, "defaultValue": "30", "description": "Maximum action ids repeated in hints, default 30.", "descriptionZh": "提示中最多重复的动作 id 数，默认 30。" }, { "name": "options.maxUnavailable", "type": "number", "required": false, "defaultValue": "6", "description": "Maximum unavailable actions listed, default 6.", "descriptionZh": "最多列出的不可用动作数，默认 6。" }, { "name": "options.maxStateChars", "type": "number", "required": false, "defaultValue": "1200", "description": "Character budget for state, default 1200.", "descriptionZh": "状态段的字符预算，默认 1200。" }, { "name": "options.maxRecordChars", "type": "number", "required": false, "defaultValue": "1500", "description": "Character budget for records, default 1500.", "descriptionZh": "记录段的字符预算，默认 1500。" }, { "name": "options.maxScopes", "type": "number", "required": false, "defaultValue": "24", "description": "Maximum page regions listed, default 24.", "descriptionZh": "最多列出的页面区域数，默认 24。" }, { "name": "options.maxFeedback", "type": "number", "required": false, "defaultValue": "8", "description": "Maximum feedback entries listed, default 8.", "descriptionZh": "最多列出的反馈条目数，默认 8。" }, { "name": "options.maxFeedbackChars", "type": "number", "required": false, "defaultValue": "800", "description": "Character budget for feedback, default 800.", "descriptionZh": "反馈段的字符预算，默认 800。" }, { "name": "options.maxPageChars", "type": "number", "required": false, "defaultValue": "500", "description": "Character budget for page identity, default 500.", "descriptionZh": "页面身份段的字符预算，默认 500。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Render a smaller context", "titleZh": "渲染更小的上下文", "code": "const text = renderPageContext(registry.snapshot(), {\n maxActions: 20,\n maxRecords: 8,\n maxStateChars: 600,\n});", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "renderPageContext" } ], "reference": "/reference/agent-runtime-sessions-context-limits" }, { "id": "createExecutor", "anchor": "api-createexecutor", "name": "createExecutor", "kind": "function", "summary": "创建页面内 Agent 与外部 Surface 宿主共用的执行器。只有这条路径会统一应用权限、可用性、执行与成功判据。", "imports": [ "@plingjs/core" ], "signature": "createExecutor(options: ExecutorOptions): Executor", "parameters": [ { "name": "registry", "type": "Registry", "required": true, "defaultValue": "", "description": "Registry that resolves actions and computes snapshots.", "descriptionZh": "解析动作并生成快照的注册表。" }, { "name": "policy", "type": "ConfirmGate", "required": true, "defaultValue": "", "description": "Approval gate applied before an action executes.", "descriptionZh": "动作执行前应用的确认闸门。" }, { "name": "handoff", "type": "HandoffGate", "required": false, "defaultValue": "", "description": "Human-handoff gate for tools declared with handoff.", "descriptionZh": "声明了人工接力的工具使用的接力通道。" }, { "name": "observe", "type": "(id: string, args: Record) => void | Promise", "required": false, "defaultValue": "", "description": "Observation window after execution, for routes, async rendering, or animation.", "descriptionZh": "执行后的观察窗口，用于路由、异步渲染或动画。" }, { "name": "evidence", "type": "boolean", "required": false, "defaultValue": "true", "description": "Captures changed evidence and includes it in successful results.", "descriptionZh": "抓取变更证据并放进成功结果。" }, { "name": "settle", "type": "() => Promise", "required": false, "defaultValue": "", "description": "Wait used before the after-snapshot.", "descriptionZh": "取执行后快照前使用的落定等待。" }, { "name": "betweenSteps", "type": "() => Promise", "required": false, "defaultValue": "", "description": "Optional pause between steps in a flow.", "descriptionZh": "复合流程步骤之间的可选停等。" }, { "name": "return.execute", "type": "(id: string, argsJson?: string) => Promise", "required": false, "defaultValue": "", "description": "Executes one action and never throws action errors to the caller.", "descriptionZh": "执行一个动作；动作错误会作为结构化结果返回，不向调用方抛出。" } ], "definition": "interface ExecutorOptions {\n registry: Registry;\n policy: ConfirmGate;\n handoff?: HandoffGate;\n observe?: (id: string, args: Record) => void | Promise;\n evidence?: boolean;\n settle?: () => Promise;\n betweenSteps?: () => Promise;\n}", "returns": null, "defaults": [], "examples": [ { "title": "Execute through the shared pipeline", "titleZh": "通过共享执行管线执行", "code": "const executor = createExecutor({\n registry: pling.registry,\n policy: createPolicy(confirm),\n});\n\nconst result = await executor.execute(\"add\", JSON.stringify({ text: \"准备发布\" }));", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "createExecutor" }, { "package": "@plingjs/core", "name": "Executor" } ], "reference": "/reference/surface-protocol" }, { "id": "createPolicy", "anchor": "api-createpolicy", "name": "createPolicy", "kind": "function", "summary": "创建确认策略。没有确认通道时按 fail-closed 处理，拒绝需要批准的动作。", "imports": [ "@plingjs/core" ], "signature": "createPolicy(confirm?: Confirm | null): Policy", "parameters": [ { "name": "confirm", "type": "Confirm | null", "required": false, "defaultValue": "null", "description": "Approval callback. Null means no confirmation channel; actions requiring approval fail closed.", "descriptionZh": "确认回调。传 `null` 表示没有确认通道；需要确认的动作按 fail-closed 拒绝。" }, { "name": "request.id", "type": "string", "required": false, "defaultValue": "", "description": "Action id being approved.", "descriptionZh": "等待确认的动作 id。" }, { "name": "request.kind", "type": "Kind", "required": false, "defaultValue": "", "description": "Action risk level.", "descriptionZh": "动作风险等级。" }, { "name": "request.approval", "type": "Approval", "required": false, "defaultValue": "", "description": "Resolved approval policy for this action.", "descriptionZh": "该动作解析后的确认策略。" }, { "name": "request.description", "type": "string", "required": false, "defaultValue": "", "description": "Model-facing description shown to the approver.", "descriptionZh": "展示给批准人的动作说明。" }, { "name": "request.args", "type": "Record", "required": false, "defaultValue": "", "description": "Validated call arguments.", "descriptionZh": "校验后的调用参数。" }, { "name": "request.flow.steps", "type": "readonly string[]", "required": false, "defaultValue": "", "description": "Step ids for a one-approval composite flow.", "descriptionZh": "复合流程一次确认时包含的步骤 id。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Connect a confirmation dialog", "titleZh": "接入确认对话框", "code": "const policy = createPolicy(async (request) => {\n return window.confirm(request.description) ? true : false;\n});", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/core", "name": "createPolicy" }, { "package": "@plingjs/core", "name": "Policy" } ], "reference": "/reference/surface-protocol" } ] }, { "id": "diagnostics", "title": "诊断与错误", "summary": "稳定错误码与本地化渲染辅助函数。跨语言时以错误码为准。", "entries": [ { "id": "describePlingError", "anchor": "api-describeplingerror", "name": "describePlingError", "kind": "function", "summary": "通过共享文案目录渲染 Pling 错误，同时保留机器可读错误码。", "imports": [ "@plingjs/ui" ], "signature": "describePlingError(error: PlingErrorText, t: PlingTranslator): string", "parameters": [ { "name": "error.code", "type": "string", "required": true, "defaultValue": "", "description": "Stable machine-readable error code. The code is preserved in the rendered summary.", "descriptionZh": "稳定的机器可读错误码。渲染摘要中会保留该错误码。" }, { "name": "error.message", "type": "string", "required": false, "defaultValue": "", "description": "Developer detail added after the localized label when it adds information.", "descriptionZh": "开发者细节；只有提供额外信息时才追加在本地化标签之后。" }, { "name": "error.messageKey", "type": "string", "required": false, "defaultValue": "", "description": "Fully localized catalog key, used before the generic code mapping.", "descriptionZh": "完全本地化的文案 key，优先于通用错误码映射。" }, { "name": "error.params", "type": "MessageParams", "required": false, "defaultValue": "", "description": "Interpolation values for the catalog message.", "descriptionZh": "文案插值参数。" }, { "name": "t", "type": "PlingTranslator", "required": true, "defaultValue": "", "description": "Translator that receives a message key and interpolation values.", "descriptionZh": "接收文案 key 与插值参数的翻译函数。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Render a localized error", "titleZh": "渲染本地化错误", "code": "const text = describePlingError(\n { code: \"EXPECTATION_FAILED\", message: \"未等到新行出现\" },\n pling.ui.t,\n);", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/ui", "name": "describePlingError" } ], "reference": "/reference/error-codes-and-diagnostics" }, { "id": "describePlingDiagnostic", "anchor": "api-describeplingdiagnostic", "name": "describePlingDiagnostic", "kind": "function", "summary": "渲染结构化配置诊断，包括缺失的模型字段与无效限额。", "imports": [ "@plingjs/ui" ], "signature": "describePlingDiagnostic(diagnostic: PlingDiagnosticText, t: PlingTranslator): string", "parameters": [ { "name": "diagnostic.ready", "type": "boolean", "required": true, "defaultValue": "", "description": "When true, the function returns an empty string.", "descriptionZh": "为 `true` 时返回空字符串。" }, { "name": "diagnostic.code", "type": "string", "required": false, "defaultValue": "", "description": "Stable diagnostic code such as MODEL_BASE_URL_MISSING or LIMITS_INVALID.", "descriptionZh": "稳定诊断码，例如 `MODEL_BASE_URL_MISSING` 或 `LIMITS_INVALID`。" }, { "name": "diagnostic.params", "type": "MessageParams", "required": false, "defaultValue": "", "description": "Non-sensitive interpolation values such as the environment variable name.", "descriptionZh": "非敏感插值参数，例如环境变量名。" }, { "name": "diagnostic.hint", "type": "string", "required": false, "defaultValue": "", "description": "Developer-facing fallback used only when no structured code exists.", "descriptionZh": "没有结构化诊断码时使用的开发者兜底说明。" }, { "name": "t", "type": "PlingTranslator", "required": true, "defaultValue": "", "description": "Translator used for the diagnostic catalog.", "descriptionZh": "用于诊断文案目录的翻译函数。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Render configuration guidance", "titleZh": "渲染配置提示", "code": "const hint = describePlingDiagnostic(\n { ready: false, code: \"MODEL_NAME_MISSING\", params: { env: \"VITE_AGENT_MODEL\" } },\n pling.ui.t,\n);", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/ui", "name": "describePlingDiagnostic" } ], "reference": "/reference/error-codes-and-diagnostics" }, { "id": "resolveAgentConfig", "anchor": "api-resolveagentconfig", "name": "resolveAgentConfig", "kind": "function", "summary": "合并默认值、环境变量与显式覆盖，得到最终模型配置。", "imports": [ "@plingjs/agent" ], "signature": "resolveAgentConfig(options?: { env?; config? }): AgentConfig", "parameters": [ { "name": "options.env", "type": "Record", "required": false, "defaultValue": "", "description": "Environment-like object. Browser adapters normally pass import.meta.env; Node callers can pass process.env.", "descriptionZh": "类环境变量对象。浏览器适配器通常传 `import.meta.env`；Node 调用方可传 `process.env`。" }, { "name": "options.config", "type": "AgentConfigOverrides", "required": false, "defaultValue": "", "description": "Explicit overrides applied after defaults and environment values.", "descriptionZh": "在默认值与环境变量之后应用的显式覆盖。" } ], "definition": null, "returns": null, "defaults": [], "examples": [ { "title": "Resolve configuration outside an adapter", "titleZh": "在适配器之外解析配置", "code": "const config = resolveAgentConfig({\n env: import.meta.env,\n config: { model: \"gpt-4.1-mini\", limits: { maxTurns: 12 } },\n});", "lang": "ts" } ], "support": { "vue3": "core", "react": "core", "vue2": "core", "vanilla": "core" }, "symbols": [ { "package": "@plingjs/agent", "name": "resolveAgentConfig" } ], "reference": "/reference/agent-runtime-sessions-context-limits" } ] } ] }