@svadmin/surface 0.16.0 → 0.17.0

package/README.md

@@ -119,6 +119,31 @@ if (response.ok && response.value.action === 'propose') {
 
 Use the same task-scoped catalog for generation, validation and rendering. JSON Schema narrows generation but does not replace cross-source binding checks, field policy or server authorization. The schema is not claimed to match every vendor's restricted structured-output subset.
 
+### Inline chat answers
+
+A chat host can answer with prose plus one inline card instead of a JSON-only reply. Pass `{ presentation: 'chat' }`, then split the streamed answer with `splitSurfaceAgentText()`:
+
+```ts
+import {
+  SURFACE_AGENT_FENCE_TAG,
+  buildSurfaceAgentMessages,
+  parseSurfaceAgentResponse,
+  splitSurfaceAgentText,
+} from '@svadmin/surface';
+
+const messages = buildSurfaceAgentMessages(request, catalog, policy, { presentation: 'chat' });
+// 边生成边切分；未闭合的 surface 围栏返回 complete: false。
+for (const segment of splitSurfaceAgentText(streamedText, { streaming: true })) {
+  if (segment.kind === 'text') renderMarkdown(segment.text);
+  else if (segment.complete) {
+    const parsed = parseSurfaceAgentResponse(segment.json, catalog, policy);
+    if (parsed.ok && parsed.value.action === 'propose') renderPreview(parsed.value.spec);
+  }
+}
+```
+
+Only fences tagged `surface` (```` ```surface ````) are treated as proposals; every other fence stays in the prose, so ordinary JSON or shell snippets are never mistaken for a card. An unterminated fence becomes an incomplete segment only while `streaming` is true, which keeps partial JSON out of the renderer while the answer is still generating. Segmentation is presentation only: it does not validate, query data, render, or replace the host approval step.
+
 `buildSurfaceAgentPrompt()` and `parseSurfaceAgentProposal()` remain compatible with the legacy proposal-only `surface-agent/v1` envelope. The new message API uses `surface-agent/v2` with a structured `cannot-fulfill` alternative. `createSurfaceAgentStream()` buffers bounded text and validates at `finish()`; it does **not** render partial JSON or implement OpenUI Lang streaming.
 
 ## Revisioned edits and explicit preview

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.16.x",
+  "surface": "0.17.x",
   "minimumSupported": {
     "@svadmin/core": "0.53.0",
     "@svadmin/ui": "0.73.0",

package/dist/agent-text.d.ts

@@ -0,0 +1,27 @@
+/** 聊天回答里标记界面提案的围栏标签，例如 ```surface。 */
+export declare const SURFACE_AGENT_FENCE_TAG = "surface";
+/** 聊天回答切分后的片段：普通正文，或一段待校验的界面提案 JSON。 */
+export type SurfaceAgentTextSegment = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'proposal';
+    readonly json: string;
+    readonly complete: boolean;
+};
+export interface SurfaceAgentTextOptions {
+    /** 生成尚未结束时，未闭合的 surface 围栏作为未完成提案返回。 */
+    readonly streaming?: boolean;
+}
+/**
+ * 把聊天回答切成正文与界面提案，供宿主内联渲染。
+ *
+ * 只识别 `surface` 标签的围栏；其它围栏（例如 json 代码块）原样留在正文里，
+ * 避免把普通代码误当成界面提案。片段内容不做校验，宿主仍需按 catalog 和
+ * policy 调用 `parseSurfaceAgentResponse()` 或 `parseSurfaceAgentProposal()`。
+ *
+ * @param text 模型输出的完整或增量文本。
+ * @param options 生成中时传入 `streaming: true`，未闭合围栏按未完成提案返回。
+ * @returns 按出现顺序排列的片段；正文与提案互不重叠，围栏行不出现在正文里。
+ */
+export declare function splitSurfaceAgentText(text: string, options?: SurfaceAgentTextOptions): readonly SurfaceAgentTextSegment[];

package/dist/agent-text.js

@@ -0,0 +1,94 @@
+import { SURFACE_AGENT_LIMITS } from './agent-contract.js';
+/** 聊天回答里标记界面提案的围栏标签，例如 ```surface。 */
+export const SURFACE_AGENT_FENCE_TAG = 'surface';
+const OPEN_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)[^`]*$/u;
+const CLOSE_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/u;
+function openingFence(line) {
+    const match = OPEN_FENCE.exec(line);
+    if (!match?.[1])
+        return undefined;
+    return { marker: match[1], tag: (match[2] ?? '').toLowerCase(), line };
+}
+function closesFence(line, fence) {
+    const match = CLOSE_FENCE.exec(line);
+    if (!match?.[1])
+        return false;
+    return match[1][0] === fence.marker[0] && match[1].length >= fence.marker.length;
+}
+/**
+ * 把聊天回答切成正文与界面提案，供宿主内联渲染。
+ *
+ * 只识别 `surface` 标签的围栏；其它围栏（例如 json 代码块）原样留在正文里，
+ * 避免把普通代码误当成界面提案。片段内容不做校验，宿主仍需按 catalog 和
+ * policy 调用 `parseSurfaceAgentResponse()` 或 `parseSurfaceAgentProposal()`。
+ *
+ * @param text 模型输出的完整或增量文本。
+ * @param options 生成中时传入 `streaming: true`，未闭合围栏按未完成提案返回。
+ * @returns 按出现顺序排列的片段；正文与提案互不重叠，围栏行不出现在正文里。
+ */
+export function splitSurfaceAgentText(text, options = {}) {
+    if (typeof text !== 'string' || text.length === 0)
+        return [];
+    // 超长输入按上限截断扫描，其余内容作为正文交还宿主，避免无界遍历。
+    const bounded = text.slice(0, SURFACE_AGENT_LIMITS.maxInputCharacters);
+    const overflow = text.slice(bounded.length);
+    const segments = [];
+    let prose = [];
+    let fence;
+    let proposal;
+    const flushProse = () => {
+        const value = prose.join('\n');
+        prose = [];
+        if (value === '')
+            return;
+        segments.push({ kind: 'text', text: value });
+    };
+    const flushProposal = (complete) => {
+        if (proposal === undefined || fence === undefined)
+            return;
+        flushProse();
+        segments.push({ kind: 'proposal', json: proposal.join('\n').trim(), complete });
+        proposal = undefined;
+        fence = undefined;
+    };
+    for (const line of bounded.split(/\r?\n/u)) {
+        if (proposal !== undefined && fence !== undefined) {
+            if (closesFence(line, fence))
+                flushProposal(true);
+            else
+                proposal.push(line);
+            continue;
+        }
+        if (fence !== undefined) {
+            // 其它围栏内的内容原样保留，围栏内的 surface 字样不是提案。
+            prose.push(line);
+            if (closesFence(line, fence))
+                fence = undefined;
+            continue;
+        }
+        const open = openingFence(line);
+        if (open === undefined) {
+            prose.push(line);
+            continue;
+        }
+        fence = open;
+        if (open.tag === SURFACE_AGENT_FENCE_TAG)
+            proposal = [];
+        else
+            prose.push(line);
+    }
+    if (proposal !== undefined && fence !== undefined) {
+        if (options.streaming === true)
+            flushProposal(false);
+        else {
+            // 非流式输出里未闭合的围栏是残缺内容，交还正文而不是静默丢弃。
+            prose.push(fence.line, ...proposal);
+            fence = undefined;
+            proposal = undefined;
+        }
+    }
+    flushProse();
+    if (overflow.length > 0)
+        segments.push({ kind: 'text', text: overflow });
+    return segments;
+}

package/dist/agent.d.ts

@@ -37,8 +37,14 @@ export declare function parseSurfaceAgentProposal(input: unknown, catalog: Surfa
 export declare function parseSurfaceAgentResponse(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentResponseResult;
 /** 兼容旧 v1 输出，同时补齐从组件契约派生的完整参数/结构 schema。 */
 export declare function buildSurfaceAgentPrompt(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): string;
+/** 模型回答的呈现方式：纯 JSON 信封，或聊天正文加一个内联界面提案。 */
+export type SurfaceAgentPresentation = 'json' | 'chat';
+export interface SurfaceAgentMessageOptions {
+    /** 默认 `json`，保持既有调用方的行为不变。 */
+    readonly presentation?: SurfaceAgentPresentation;
+}
 /** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
-export declare function buildSurfaceAgentMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): readonly SurfaceAgentMessage[];
+export declare function buildSurfaceAgentMessages(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy, options?: SurfaceAgentMessageOptions): readonly SurfaceAgentMessage[];
 export interface SurfaceAgentStream {
     /** 接收文本，不解析、不渲染、不查询数据。 */
     push(chunk: string): {

package/dist/agent.js

@@ -1,6 +1,7 @@
 import { Type } from 'typebox';
 import { Compile } from 'typebox/compile';
 import { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_AGENT_SCHEMA_VERSION, createSurfaceAgentResponseSchema, createSurfaceCatalogManifest, createSurfaceGenerationSpecSchema, surfaceCannotFulfillSchema, surfaceSchemaToJson, } from './agent-contract.js';
+import { SURFACE_AGENT_FENCE_TAG } from './agent-text.js';
 import { validateSurfaceSpec, surfaceSchemaIssues } from './validation.js';
 import { parseSurfaceJson, surfaceWireError } from './wire.js';
 export { SURFACE_AGENT_SCHEMA_VERSION } from './agent-contract.js';
@@ -77,9 +78,12 @@ export function buildSurfaceAgentPrompt(request, catalog, policy) {
     return boundedPrompt(`${request}\n\n[svadmin surface agent protocol]\nReturn only a human-reviewable fenced JSON proposal. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(schema)}\nIf the request cannot be represented safely, explain the limitation without inventing fields or capabilities. For machine-readable cannot-fulfill responses use the surface-agent/v2 message API.`);
 }
 /** 系统契约与用户需求分开传递；不绑定某个模型厂商或 CSS 编译器。 */
-export function buildSurfaceAgentMessages(request, catalog, policy) {
+export function buildSurfaceAgentMessages(request, catalog, policy, options = {}) {
     validateRequest(request);
-    const content = boundedPrompt(`[svadmin surface agent protocol]\nReturn exactly one JSON object matching the output schema, without markdown or prose. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${JSON.stringify(createSurfaceAgentResponseSchema(catalog, policy))}\nIf the request cannot be represented, return action "cannot-fulfill" with a reason and a short message. Never invent capabilities or return an incomplete spec.`);
+    const schema = JSON.stringify(createSurfaceAgentResponseSchema(catalog, policy));
+    const content = options.presentation === 'chat'
+        ? boundedPrompt(`[svadmin surface agent protocol]\nAnswer the user in short prose first, then embed exactly one interface proposal in a \`\`\`${SURFACE_AGENT_FENCE_TAG} fenced block matching the output schema. Emit at most one such block, do not add other fenced blocks, and do not repeat the JSON outside the fence. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${schema}\nIf the request cannot be represented, answer in prose and omit the fenced block; never invent capabilities or return an incomplete spec.`)
+        : boundedPrompt(`[svadmin surface agent protocol]\nReturn exactly one JSON object matching the output schema, without markdown or prose. ${safetyInstructions}\n${contractContext(catalog, policy)}\nOutput JSON Schema: ${schema}\nIf the request cannot be represented, return action "cannot-fulfill" with a reason and a short message. Never invent capabilities or return an incomplete spec.`);
     return [{ role: 'system', content }, { role: 'user', content: request }];
 }
 /** 有界传输缓冲，不冒充 OpenUI 增量渲染；半成品不进入运行时。 */

package/dist/components/SurfaceRenderer.svelte

@@ -11,7 +11,7 @@
   import type { SurfaceMessages } from '../localization.js';
   import type {
     SurfaceDataError, SurfaceDataProvider, SurfacePolicy,
-    SurfaceSourceDataState, SurfaceValidationIssue, JsonObject,
+    SurfaceSourceDataState, SurfaceValidationIssue, SurfaceWidgetDataState, JsonObject,
   } from '../types.js';
   import { validateSurfaceSpec } from '../validation.js';
   import { createSurfaceSourceCache, sameSourceIdentity, snapshotSurfaceSource } from '../source-cache.js';
@@ -55,6 +55,18 @@
   const i18n = useTranslation();
   const activeLocale = $derived(locale ?? i18n.locale);
   const activeMessages = $derived(resolveSurfaceMessages(activeLocale, messages));
+  // 统一呈现边界：错误状态只暴露本地化文案，宿主诊断仍留在 onError。
+  function presentSurfaceData(data: SurfaceWidgetDataState): SurfaceWidgetDataState {
+    if (data.status !== 'error') return data;
+    const message = data.error.code === 'access_denied'
+      ? activeMessages.accessDenied
+      : data.error.code === 'provider_result_not_json' || data.error.code === 'binding_pointer_not_found'
+        ? activeMessages.invalidData
+        : activeMessages.providerUnavailable;
+    return data.error.message === message
+      ? data
+      : { ...data, error: { ...data.error, message } };
+  }
   const validation = $derived(validateSurfaceSpec(spec, catalog, policy));
   const widgetRegistrations = $derived(new Map(catalog.widgets.map((widget) => [widget.type, widget])));
   const sourceStates = new SvelteMap<string, SurfaceSourceDataState>();
@@ -69,18 +81,8 @@
   ]);
   // 复用 PR #428 的请求所有权与会话隔离实现，不维护第二套缓存。
   const sourceCache = createSurfaceSourceCache({
-    set: (id, state) => {
-      if (state.status !== 'error') {
-        sourceStates.set(id, state);
-        return;
-      }
-      const message = state.error.code === 'access_denied'
-        ? activeMessages.accessDenied
-        : state.error.code === 'provider_result_not_json' || state.error.code === 'binding_pointer_not_found'
-          ? state.error.message
-          : activeMessages.providerUnavailable;
-      sourceStates.set(id, { ...state, error: { ...state.error, message } });
-    },
+    // 缓存只保存原始 source 状态；本地化等呈现规则统一在渲染边界执行。
+    set: (id, state) => { sourceStates.set(id, state); },
     remove: (id) => { sourceStates.delete(id); },
     onError: (state, diagnostic) => { onError?.({ type: 'data', error: diagnostic ?? state.error }); },
   });
@@ -180,7 +182,7 @@
           <div class="surface-widget surface-span-{widget.placement?.columnSpan ?? 12} {semantic ? appearanceClasses(widget.props) : ''}" data-testid="surface-widget-{widget.id}">
             {#if WidgetComponent}
               <WidgetComponent widgetId={widget.id} props={semantic ? withoutSurfaceAppearance(widget.props) : widget.props}
-                data={resolveSurfaceSourceData(widget, widget.binding ? sourceStates.get(widget.binding.sourceId) : undefined)}
+                data={presentSurfaceData(resolveSurfaceSourceData(widget, widget.binding ? sourceStates.get(widget.binding.sourceId) : undefined))}
                 locale={activeLocale} messages={activeMessages} />
             {/if}
           </div>

package/dist/index.d.ts

@@ -3,6 +3,9 @@ export type { JsonObject, JsonPrimitive, JsonValue, ResourceListDataSource, Reso
 export { validateSurfaceSpec } from './validation.js';
 export type { SurfaceMessages } from './localization.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';
+export type { SurfaceAgentTextSegment, SurfaceAgentTextOptions, } from './agent-text.js';
+export type { SurfaceAgentMessageOptions, SurfaceAgentPresentation, } from './agent.js';
 export type { SurfaceAgentProposal, SurfaceAgentProposalV2, SurfaceAgentCannotFulfill, SurfaceAgentResponse, SurfaceAgentResponseResult, SurfaceAgentMessage, SurfaceAgentStream, SurfaceAgentValidationResult, } from './agent.js';
 export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
 export type { SurfaceCatalogManifest } from './agent-contract.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
 export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, buildSurfaceAgentMessages, parseSurfaceAgentProposal, parseSurfaceAgentResponse, createSurfaceAgentStream, } from './agent.js';
+export { SURFACE_AGENT_FENCE_TAG, splitSurfaceAgentText, } from './agent-text.js';
 export { SURFACE_AGENT_LIMITS, SURFACE_AGENT_RESPONSE_SCHEMA_VERSION, SURFACE_CATALOG_SCHEMA_VERSION, createSurfaceCatalogManifest, createSurfaceAgentResponseSchema, selectSurfaceCatalog, } from './agent-contract.js';
 export { SURFACE_EDIT_SCHEMA_VERSION, SURFACE_EDIT_LIMITS, createSurfaceRevision, applySurfaceEditProposal, createSurfaceEditSchema, buildSurfaceEditMessages, } from './edits.js';
 // 只导出 JSON schema，不将可选 SVAR 渲染器加载到协议入口。

package/dist/localization.d.ts

@@ -3,6 +3,7 @@ export interface SurfaceMessages {
     readonly renderErrorTitle: string;
     readonly providerUnavailable: string;
     readonly accessDenied?: string;
+    readonly invalidData?: string;
     readonly metricNoData: string;
     readonly metricInvalidData: string;
     readonly chartLoading: string;

package/dist/localization.js

@@ -2,6 +2,7 @@ const englishMessages = {
     renderErrorTitle: 'Surface could not be rendered',
     providerUnavailable: 'Data provider is unavailable',
     accessDenied: 'Access denied',
+    invalidData: 'Surface data is invalid',
     metricNoData: 'No data',
     metricInvalidData: 'Metric data is invalid',
     chartLoading: 'Loading {title}',
@@ -30,6 +31,7 @@ const simplifiedChineseMessages = {
     renderErrorTitle: '无法渲染 Surface',
     providerUnavailable: '数据提供器不可用',
     accessDenied: '无权访问',
+    invalidData: 'Surface 数据无效',
     metricNoData: '暂无数据',
     metricInvalidData: '指标数据无效',
     chartLoading: '正在加载{title}',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/surface",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Validated declarative surfaces for svadmin dashboards",
   "type": "module",
   "sideEffects": [
@@ -74,8 +74,8 @@
     }
   },
   "peerDependencies": {
-    "@svadmin/core": ">=0.53.0 <0.66.0",
-    "@svadmin/ui": ">=0.73.0 <0.92.0",
+    "@svadmin/core": ">=0.53.0 <0.67.0",
+    "@svadmin/ui": ">=0.73.0 <0.93.0",
     "svelte": "^5.56.10"
   },
   "dependencies": {