@zhama/a2ui-core 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -36,40 +36,6 @@ type BooleanOrPath = boolean | {
36
36
  type StringArrayOrPath = string[] | {
37
37
  path: string;
38
38
  };
39
- /**
40
- * v0.8 格式的字符串值(带有 literalString/path 区分)
41
- */
42
- interface StringValue {
43
- path?: string;
44
- literalString?: string;
45
- /** @deprecated 使用 literalString */
46
- literal?: string;
47
- }
48
- /**
49
- * v0.8 格式的数值(带有 literalNumber/path 区分)
50
- */
51
- interface NumberValue {
52
- path?: string;
53
- literalNumber?: number;
54
- /** @deprecated 使用 literalNumber */
55
- literal?: number;
56
- }
57
- /**
58
- * v0.8 格式的布尔值(带有 literalBoolean/path 区分)
59
- */
60
- interface BooleanValue {
61
- path?: string;
62
- literalBoolean?: boolean;
63
- /** @deprecated 使用 literalBoolean */
64
- literal?: boolean;
65
- }
66
- /**
67
- * v0.8 格式的字符串数组值
68
- */
69
- interface StringArrayValue {
70
- path?: string;
71
- literalArray?: string[];
72
- }
73
39
  /**
74
40
  * Context value - 用于 Action context 中的值
75
41
  */
@@ -77,4 +43,4 @@ type ContextValue = string | number | boolean | {
77
43
  path: string;
78
44
  };
79
45
 
80
- export type { BooleanOrPath as B, ContextValue as C, NumberOrPath as N, StringOrPath as S, StringArrayOrPath as a, StringValue as b, NumberValue as c, BooleanValue as d, StringArrayValue as e };
46
+ export type { BooleanOrPath as B, ContextValue as C, NumberOrPath as N, StringOrPath as S, StringArrayOrPath as a };
@@ -36,40 +36,6 @@ type BooleanOrPath = boolean | {
36
36
  type StringArrayOrPath = string[] | {
37
37
  path: string;
38
38
  };
39
- /**
40
- * v0.8 格式的字符串值(带有 literalString/path 区分)
41
- */
42
- interface StringValue {
43
- path?: string;
44
- literalString?: string;
45
- /** @deprecated 使用 literalString */
46
- literal?: string;
47
- }
48
- /**
49
- * v0.8 格式的数值(带有 literalNumber/path 区分)
50
- */
51
- interface NumberValue {
52
- path?: string;
53
- literalNumber?: number;
54
- /** @deprecated 使用 literalNumber */
55
- literal?: number;
56
- }
57
- /**
58
- * v0.8 格式的布尔值(带有 literalBoolean/path 区分)
59
- */
60
- interface BooleanValue {
61
- path?: string;
62
- literalBoolean?: boolean;
63
- /** @deprecated 使用 literalBoolean */
64
- literal?: boolean;
65
- }
66
- /**
67
- * v0.8 格式的字符串数组值
68
- */
69
- interface StringArrayValue {
70
- path?: string;
71
- literalArray?: string[];
72
- }
73
39
  /**
74
40
  * Context value - 用于 Action context 中的值
75
41
  */
@@ -77,4 +43,4 @@ type ContextValue = string | number | boolean | {
77
43
  path: string;
78
44
  };
79
45
 
80
- export type { BooleanOrPath as B, ContextValue as C, NumberOrPath as N, StringOrPath as S, StringArrayOrPath as a, StringValue as b, NumberValue as c, BooleanValue as d, StringArrayValue as e };
46
+ export type { BooleanOrPath as B, ContextValue as C, NumberOrPath as N, StringOrPath as S, StringArrayOrPath as a };
@@ -0,0 +1,2 @@
1
+ 'use strict';var n={CHAT:"@chat",RECOMMENDATION:"@recommendation",INPUT_FORM:"@input-form",ORCHESTRATION:"@orchestration",STATUS:"@status",RESULT:"@result",CONFIRM:"@confirm",NOTIFICATION:"@notification"},c=0;function i(e="surface"){return c++,`${e}-${Date.now()}-${c}`}function C(){c=0;}var p="https://a2ui.dev/specification/0.9/standard_catalog_definition.json";function u(e,t=p){return {createSurface:{surfaceId:e,catalogId:t}}}function g(e,t){return {updateComponents:{surfaceId:e,components:t}}}function f(e,t,a,r="replace"){return {updateDataModel:{surfaceId:e,...a,op:r,...r!=="remove"&&{value:t}}}}function d(e){return {deleteSurface:{surfaceId:e}}}function o(e,t,a){let r=a??i();return t.find(l=>l.id===e)||console.warn(`[A2UI] Root component "${e}" not found in components list`),{messages:[u(r),g(r,t)],surfaceId:r}}function S(e,t,a,r){let s=r??i();return {messages:[u(s),g(s,t),f(s,a)],surfaceId:s}}function M(e){return d(e)}function I(e,t){return o(e,t,n.CHAT)}function T(e,t){return o(e,t,n.RECOMMENDATION)}function x(e,t){return o(e,t,n.INPUT_FORM)}function D(e,t){return o(e,t,n.ORCHESTRATION)}function A(e,t){return o(e,t,n.STATUS)}
2
+ exports.SURFACE_IDS=n;exports.createA2UISurface=o;exports.createA2UISurfaceWithData=S;exports.createChatSurface=I;exports.createDeleteSurfaceMessage=M;exports.createInputFormSurface=x;exports.createOrchestrationSurface=D;exports.createRecommendationSurface=T;exports.createStatusSurface=A;exports.generateSurfaceId=i;exports.resetSurfaceIdCounter=C;
@@ -0,0 +1,165 @@
1
+ import { ServerToClientMessageV09, ComponentInstance, DataObject } from '../types/index.cjs';
2
+ import '../primitives-DLbBDhLq.cjs';
3
+
4
+ /**
5
+ * Surface IDs and Configuration
6
+ *
7
+ * 预定义的 Surface ID 常量和配置
8
+ * 前端根据这些 ID 决定渲染位置和样式
9
+ */
10
+ /**
11
+ * 标准 Surface ID 常量
12
+ *
13
+ * 前端可以根据这些 ID 决定:
14
+ * - 渲染位置(聊天区、侧边栏、模态框等)
15
+ * - 渲染样式(卡片、全屏、浮动等)
16
+ * - 交互行为(自动消失、持久化等)
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * import { SURFACE_IDS, createA2UISurface } from '@zhama/a2ui-core';
21
+ *
22
+ * const surface = createA2UISurface('root', components, SURFACE_IDS.CHAT);
23
+ * ```
24
+ */
25
+ declare const SURFACE_IDS: {
26
+ /** 聊天内容区 - 普通对话消息 */
27
+ readonly CHAT: "@chat";
28
+ /** 智能体推荐区 - 展示推荐的智能体列表 */
29
+ readonly RECOMMENDATION: "@recommendation";
30
+ /** 输入收集表单 - 收集用户输入 */
31
+ readonly INPUT_FORM: "@input-form";
32
+ /** 编排面板 - 多智能体编排状态 */
33
+ readonly ORCHESTRATION: "@orchestration";
34
+ /** 临时状态提示 - loading/thinking/error 等 */
35
+ readonly STATUS: "@status";
36
+ /** 结果展示区 - 智能体执行结果 */
37
+ readonly RESULT: "@result";
38
+ /** 确认对话框 - 需要用户确认的操作 */
39
+ readonly CONFIRM: "@confirm";
40
+ /** 通知区 - 系统通知 */
41
+ readonly NOTIFICATION: "@notification";
42
+ };
43
+ /**
44
+ * Surface ID 类型
45
+ */
46
+ type SurfaceIdType = (typeof SURFACE_IDS)[keyof typeof SURFACE_IDS];
47
+ /**
48
+ * Surface 配置
49
+ */
50
+ interface SurfaceConfig {
51
+ /** Surface ID */
52
+ id: SurfaceIdType | string;
53
+ /** 是否自动消失 */
54
+ autoHide?: boolean;
55
+ /** 自动消失延迟(毫秒) */
56
+ autoHideDelay?: number;
57
+ /** 是否可关闭 */
58
+ closable?: boolean;
59
+ /** 优先级(数字越大越优先显示) */
60
+ priority?: number;
61
+ }
62
+ /**
63
+ * 生成唯一的 Surface ID
64
+ *
65
+ * @param prefix - ID 前缀
66
+ * @returns 唯一的 Surface ID
67
+ *
68
+ * @example
69
+ * ```typescript
70
+ * const id = generateSurfaceId('status'); // 'status-1703123456789-1'
71
+ * ```
72
+ */
73
+ declare function generateSurfaceId(prefix?: string): string;
74
+ /**
75
+ * 重置 Surface ID 计数器
76
+ * 主要用于测试
77
+ */
78
+ declare function resetSurfaceIdCounter(): void;
79
+
80
+ /**
81
+ * Surface Builder
82
+ *
83
+ * 提供 A2UI Surface 的构建工具函数
84
+ * 基于 v0.9 格式
85
+ *
86
+ * 参考:https://a2ui.org/
87
+ */
88
+
89
+ /**
90
+ * Surface 构建结果
91
+ */
92
+ interface SurfaceResult {
93
+ /** 构建的消息数组 */
94
+ messages: ServerToClientMessageV09[];
95
+ /** Surface ID */
96
+ surfaceId: string;
97
+ }
98
+ /**
99
+ * 创建 A2UI Surface 消息
100
+ *
101
+ * @param rootId - 根组件 ID
102
+ * @param components - 组件列表(v0.9 格式)
103
+ * @param surfaceId - Surface ID(可选,自动生成)
104
+ * @returns Surface 构建结果
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * import { createA2UISurface, h1, column, SURFACE_IDS } from '@zhama/a2ui-core';
109
+ *
110
+ * const title = h1('Hello', { id: 'title' });
111
+ * const root = column(['title'], { id: 'root' });
112
+ *
113
+ * const { messages, surfaceId } = createA2UISurface('root', [title, root], SURFACE_IDS.CHAT);
114
+ * ```
115
+ */
116
+ declare function createA2UISurface(rootId: string, components: ComponentInstance[], surfaceId?: string): SurfaceResult;
117
+ /**
118
+ * 创建带数据模型的 A2UI Surface
119
+ *
120
+ * @param rootId - 根组件 ID
121
+ * @param components - 组件列表(v0.9 格式)
122
+ * @param dataModel - 数据模型对象
123
+ * @param surfaceId - Surface ID(可选)
124
+ * @returns Surface 构建结果
125
+ *
126
+ * @example
127
+ * ```typescript
128
+ * const { messages } = createA2UISurfaceWithData(
129
+ * 'root',
130
+ * [title, greeting, root],
131
+ * { user: { name: 'John' } },
132
+ * SURFACE_IDS.CHAT
133
+ * );
134
+ * ```
135
+ */
136
+ declare function createA2UISurfaceWithData(rootId: string, components: ComponentInstance[], dataModel: DataObject, surfaceId?: string): SurfaceResult;
137
+ /**
138
+ * 创建删除 Surface 的消息
139
+ *
140
+ * @param surfaceId - 要删除的 Surface ID
141
+ * @returns 删除消息
142
+ */
143
+ declare function createDeleteSurfaceMessage(surfaceId: string): ServerToClientMessageV09;
144
+ /**
145
+ * 创建聊天区 Surface
146
+ */
147
+ declare function createChatSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
148
+ /**
149
+ * 创建智能体推荐区 Surface
150
+ */
151
+ declare function createRecommendationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
152
+ /**
153
+ * 创建输入表单区 Surface
154
+ */
155
+ declare function createInputFormSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
156
+ /**
157
+ * 创建编排面板 Surface
158
+ */
159
+ declare function createOrchestrationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
160
+ /**
161
+ * 创建状态提示 Surface
162
+ */
163
+ declare function createStatusSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
164
+
165
+ export { SURFACE_IDS, type SurfaceConfig, type SurfaceIdType, type SurfaceResult, createA2UISurface, createA2UISurfaceWithData, createChatSurface, createDeleteSurfaceMessage, createInputFormSurface, createOrchestrationSurface, createRecommendationSurface, createStatusSurface, generateSurfaceId, resetSurfaceIdCounter };
@@ -0,0 +1,165 @@
1
+ import { ServerToClientMessageV09, ComponentInstance, DataObject } from '../types/index.js';
2
+ import '../primitives-DLbBDhLq.js';
3
+
4
+ /**
5
+ * Surface IDs and Configuration
6
+ *
7
+ * 预定义的 Surface ID 常量和配置
8
+ * 前端根据这些 ID 决定渲染位置和样式
9
+ */
10
+ /**
11
+ * 标准 Surface ID 常量
12
+ *
13
+ * 前端可以根据这些 ID 决定:
14
+ * - 渲染位置(聊天区、侧边栏、模态框等)
15
+ * - 渲染样式(卡片、全屏、浮动等)
16
+ * - 交互行为(自动消失、持久化等)
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * import { SURFACE_IDS, createA2UISurface } from '@zhama/a2ui-core';
21
+ *
22
+ * const surface = createA2UISurface('root', components, SURFACE_IDS.CHAT);
23
+ * ```
24
+ */
25
+ declare const SURFACE_IDS: {
26
+ /** 聊天内容区 - 普通对话消息 */
27
+ readonly CHAT: "@chat";
28
+ /** 智能体推荐区 - 展示推荐的智能体列表 */
29
+ readonly RECOMMENDATION: "@recommendation";
30
+ /** 输入收集表单 - 收集用户输入 */
31
+ readonly INPUT_FORM: "@input-form";
32
+ /** 编排面板 - 多智能体编排状态 */
33
+ readonly ORCHESTRATION: "@orchestration";
34
+ /** 临时状态提示 - loading/thinking/error 等 */
35
+ readonly STATUS: "@status";
36
+ /** 结果展示区 - 智能体执行结果 */
37
+ readonly RESULT: "@result";
38
+ /** 确认对话框 - 需要用户确认的操作 */
39
+ readonly CONFIRM: "@confirm";
40
+ /** 通知区 - 系统通知 */
41
+ readonly NOTIFICATION: "@notification";
42
+ };
43
+ /**
44
+ * Surface ID 类型
45
+ */
46
+ type SurfaceIdType = (typeof SURFACE_IDS)[keyof typeof SURFACE_IDS];
47
+ /**
48
+ * Surface 配置
49
+ */
50
+ interface SurfaceConfig {
51
+ /** Surface ID */
52
+ id: SurfaceIdType | string;
53
+ /** 是否自动消失 */
54
+ autoHide?: boolean;
55
+ /** 自动消失延迟(毫秒) */
56
+ autoHideDelay?: number;
57
+ /** 是否可关闭 */
58
+ closable?: boolean;
59
+ /** 优先级(数字越大越优先显示) */
60
+ priority?: number;
61
+ }
62
+ /**
63
+ * 生成唯一的 Surface ID
64
+ *
65
+ * @param prefix - ID 前缀
66
+ * @returns 唯一的 Surface ID
67
+ *
68
+ * @example
69
+ * ```typescript
70
+ * const id = generateSurfaceId('status'); // 'status-1703123456789-1'
71
+ * ```
72
+ */
73
+ declare function generateSurfaceId(prefix?: string): string;
74
+ /**
75
+ * 重置 Surface ID 计数器
76
+ * 主要用于测试
77
+ */
78
+ declare function resetSurfaceIdCounter(): void;
79
+
80
+ /**
81
+ * Surface Builder
82
+ *
83
+ * 提供 A2UI Surface 的构建工具函数
84
+ * 基于 v0.9 格式
85
+ *
86
+ * 参考:https://a2ui.org/
87
+ */
88
+
89
+ /**
90
+ * Surface 构建结果
91
+ */
92
+ interface SurfaceResult {
93
+ /** 构建的消息数组 */
94
+ messages: ServerToClientMessageV09[];
95
+ /** Surface ID */
96
+ surfaceId: string;
97
+ }
98
+ /**
99
+ * 创建 A2UI Surface 消息
100
+ *
101
+ * @param rootId - 根组件 ID
102
+ * @param components - 组件列表(v0.9 格式)
103
+ * @param surfaceId - Surface ID(可选,自动生成)
104
+ * @returns Surface 构建结果
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * import { createA2UISurface, h1, column, SURFACE_IDS } from '@zhama/a2ui-core';
109
+ *
110
+ * const title = h1('Hello', { id: 'title' });
111
+ * const root = column(['title'], { id: 'root' });
112
+ *
113
+ * const { messages, surfaceId } = createA2UISurface('root', [title, root], SURFACE_IDS.CHAT);
114
+ * ```
115
+ */
116
+ declare function createA2UISurface(rootId: string, components: ComponentInstance[], surfaceId?: string): SurfaceResult;
117
+ /**
118
+ * 创建带数据模型的 A2UI Surface
119
+ *
120
+ * @param rootId - 根组件 ID
121
+ * @param components - 组件列表(v0.9 格式)
122
+ * @param dataModel - 数据模型对象
123
+ * @param surfaceId - Surface ID(可选)
124
+ * @returns Surface 构建结果
125
+ *
126
+ * @example
127
+ * ```typescript
128
+ * const { messages } = createA2UISurfaceWithData(
129
+ * 'root',
130
+ * [title, greeting, root],
131
+ * { user: { name: 'John' } },
132
+ * SURFACE_IDS.CHAT
133
+ * );
134
+ * ```
135
+ */
136
+ declare function createA2UISurfaceWithData(rootId: string, components: ComponentInstance[], dataModel: DataObject, surfaceId?: string): SurfaceResult;
137
+ /**
138
+ * 创建删除 Surface 的消息
139
+ *
140
+ * @param surfaceId - 要删除的 Surface ID
141
+ * @returns 删除消息
142
+ */
143
+ declare function createDeleteSurfaceMessage(surfaceId: string): ServerToClientMessageV09;
144
+ /**
145
+ * 创建聊天区 Surface
146
+ */
147
+ declare function createChatSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
148
+ /**
149
+ * 创建智能体推荐区 Surface
150
+ */
151
+ declare function createRecommendationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
152
+ /**
153
+ * 创建输入表单区 Surface
154
+ */
155
+ declare function createInputFormSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
156
+ /**
157
+ * 创建编排面板 Surface
158
+ */
159
+ declare function createOrchestrationSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
160
+ /**
161
+ * 创建状态提示 Surface
162
+ */
163
+ declare function createStatusSurface(rootId: string, components: ComponentInstance[]): SurfaceResult;
164
+
165
+ export { SURFACE_IDS, type SurfaceConfig, type SurfaceIdType, type SurfaceResult, createA2UISurface, createA2UISurfaceWithData, createChatSurface, createDeleteSurfaceMessage, createInputFormSurface, createOrchestrationSurface, createRecommendationSurface, createStatusSurface, generateSurfaceId, resetSurfaceIdCounter };
@@ -0,0 +1,2 @@
1
+ var n={CHAT:"@chat",RECOMMENDATION:"@recommendation",INPUT_FORM:"@input-form",ORCHESTRATION:"@orchestration",STATUS:"@status",RESULT:"@result",CONFIRM:"@confirm",NOTIFICATION:"@notification"},c=0;function i(e="surface"){return c++,`${e}-${Date.now()}-${c}`}function C(){c=0;}var p="https://a2ui.dev/specification/0.9/standard_catalog_definition.json";function u(e,t=p){return {createSurface:{surfaceId:e,catalogId:t}}}function g(e,t){return {updateComponents:{surfaceId:e,components:t}}}function f(e,t,a,r="replace"){return {updateDataModel:{surfaceId:e,...a,op:r,...r!=="remove"&&{value:t}}}}function d(e){return {deleteSurface:{surfaceId:e}}}function o(e,t,a){let r=a??i();return t.find(l=>l.id===e)||console.warn(`[A2UI] Root component "${e}" not found in components list`),{messages:[u(r),g(r,t)],surfaceId:r}}function S(e,t,a,r){let s=r??i();return {messages:[u(s),g(s,t),f(s,a)],surfaceId:s}}function M(e){return d(e)}function I(e,t){return o(e,t,n.CHAT)}function T(e,t){return o(e,t,n.RECOMMENDATION)}function x(e,t){return o(e,t,n.INPUT_FORM)}function D(e,t){return o(e,t,n.ORCHESTRATION)}function A(e,t){return o(e,t,n.STATUS)}
2
+ export{n as SURFACE_IDS,o as createA2UISurface,S as createA2UISurfaceWithData,I as createChatSurface,M as createDeleteSurfaceMessage,x as createInputFormSurface,D as createOrchestrationSurface,T as createRecommendationSurface,A as createStatusSurface,i as generateSurfaceId,C as resetSurfaceIdCounter};
@@ -1,2 +1,2 @@
1
- 'use strict';function t(e){return "createSurface"in e||"updateComponents"in e||"updateDataModel"in e}function n(e){return "beginRendering"in e||"surfaceUpdate"in e||"dataModelUpdate"in e}var a="https://a2ui.dev/specification/0.9/standard_catalog_definition.json",o="https://a2ui.org/a2a-extension/a2ui/v0.8",r="https://a2ui.dev/specification/0.9",s="application/json+a2ui";
2
- exports.A2UI_EXTENSION_URI=r;exports.A2UI_EXTENSION_URI_V08=o;exports.A2UI_MIME_TYPE=s;exports.STANDARD_CATALOG_ID=a;exports.isV08Message=n;exports.isV09Message=t;
1
+ 'use strict';function t(e){return "createSurface"in e||"updateComponents"in e||"updateDataModel"in e}var n="https://a2ui.dev/specification/0.9/standard_catalog_definition.json";var r="https://a2ui.dev/specification/0.9",a="application/json+a2ui";
2
+ exports.A2UI_EXTENSION_URI=r;exports.A2UI_MIME_TYPE=a;exports.STANDARD_CATALOG_ID=n;exports.isV09Message=t;
@@ -1,5 +1,5 @@
1
- import { S as StringOrPath, N as NumberOrPath, B as BooleanOrPath, a as StringArrayOrPath } from '../primitives-nmkVz-tB.cjs';
2
- export { d as BooleanValue, C as ContextValue, c as NumberValue, e as StringArrayValue, b as StringValue } from '../primitives-nmkVz-tB.cjs';
1
+ import { S as StringOrPath, N as NumberOrPath, B as BooleanOrPath, a as StringArrayOrPath } from '../primitives-DLbBDhLq.cjs';
2
+ export { C as ContextValue } from '../primitives-DLbBDhLq.cjs';
3
3
 
4
4
  /**
5
5
  * A2UI Component Types
@@ -24,25 +24,6 @@ interface Action {
24
24
  */
25
25
  context?: Record<string, StringOrPath | NumberOrPath | BooleanOrPath>;
26
26
  }
27
- /**
28
- * v0.8 格式的 Action 上下文项
29
- */
30
- interface ActionContextItem {
31
- key: string;
32
- value: {
33
- path?: string;
34
- literalString?: string;
35
- literalNumber?: number;
36
- literalBoolean?: boolean;
37
- };
38
- }
39
- /**
40
- * v0.8 格式的 Action
41
- */
42
- interface ActionV08 {
43
- name: string;
44
- context?: ActionContextItem[];
45
- }
46
27
  /**
47
28
  * 组件公共属性
48
29
  */
@@ -547,18 +528,19 @@ type ServerToClientMessage = ServerToClientMessageV08 | ServerToClientMessageV09
547
528
  * 判断是否为 v0.9 消息
548
529
  */
549
530
  declare function isV09Message(message: ServerToClientMessage): message is ServerToClientMessageV09;
550
- /**
551
- * 判断是否为 v0.8 消息
552
- */
553
- declare function isV08Message(message: ServerToClientMessage): message is ServerToClientMessageV08;
554
531
  /**
555
532
  * 用户操作事件
533
+ * @see https://a2ui.dev/specification/0.9/client_to_server.json
556
534
  */
557
535
  interface UserActionEvent {
558
536
  /**
559
- * 操作名称
537
+ * 操作名称(来自组件的 action.name)
560
538
  */
561
- actionName: string;
539
+ name: string;
540
+ /**
541
+ * 触发操作的 Surface ID
542
+ */
543
+ surfaceId: string;
562
544
  /**
563
545
  * 触发组件的 ID
564
546
  */
@@ -568,9 +550,9 @@ interface UserActionEvent {
568
550
  */
569
551
  timestamp: string;
570
552
  /**
571
- * 操作上下文(解析后的值)
553
+ * 操作上下文(解析数据绑定后的键值对)
572
554
  */
573
- context?: Record<string, unknown>;
555
+ context: Record<string, unknown>;
574
556
  }
575
557
  /**
576
558
  * 数据变更事件
@@ -593,6 +575,54 @@ interface DataChangeEvent {
593
575
  */
594
576
  sourceComponentId: string;
595
577
  }
578
+ /**
579
+ * 验证失败错误
580
+ * @see https://a2ui.dev/specification/0.9/client_to_server.json
581
+ */
582
+ interface ValidationFailedError {
583
+ /**
584
+ * 错误代码
585
+ */
586
+ code: 'VALIDATION_FAILED';
587
+ /**
588
+ * 发生错误的 Surface ID
589
+ */
590
+ surfaceId: string;
591
+ /**
592
+ * 验证失败的字段路径(JSON Pointer 格式)
593
+ * @example "/components/0/text"
594
+ */
595
+ path: string;
596
+ /**
597
+ * 错误描述
598
+ */
599
+ message: string;
600
+ }
601
+ /**
602
+ * 通用错误
603
+ */
604
+ interface GenericError {
605
+ /**
606
+ * 错误代码(非 VALIDATION_FAILED)
607
+ */
608
+ code: string;
609
+ /**
610
+ * 发生错误的 Surface ID
611
+ */
612
+ surfaceId: string;
613
+ /**
614
+ * 错误描述
615
+ */
616
+ message: string;
617
+ /**
618
+ * 其他附加信息
619
+ */
620
+ [key: string]: unknown;
621
+ }
622
+ /**
623
+ * 客户端错误消息
624
+ */
625
+ type ClientErrorMessage = ValidationFailedError | GenericError;
596
626
  /**
597
627
  * 客户端到服务器消息
598
628
  */
@@ -600,6 +630,8 @@ type ClientToServerMessage = {
600
630
  userAction: UserActionEvent;
601
631
  } | {
602
632
  dataChange: DataChangeEvent;
633
+ } | {
634
+ error: ClientErrorMessage;
603
635
  };
604
636
  /**
605
637
  * 数据模型值类型
@@ -619,10 +651,6 @@ type DataArray = DataValue[];
619
651
  * A2UI 标准 Catalog ID
620
652
  */
621
653
  declare const STANDARD_CATALOG_ID = "https://a2ui.dev/specification/0.9/standard_catalog_definition.json";
622
- /**
623
- * A2UI 扩展 URI (v0.8)
624
- */
625
- declare const A2UI_EXTENSION_URI_V08 = "https://a2ui.org/a2a-extension/a2ui/v0.8";
626
654
  /**
627
655
  * A2UI 扩展 URI (v0.9)
628
656
  */
@@ -632,4 +660,4 @@ declare const A2UI_EXTENSION_URI = "https://a2ui.dev/specification/0.9";
632
660
  */
633
661
  declare const A2UI_MIME_TYPE = "application/json+a2ui";
634
662
 
635
- export { A2UI_EXTENSION_URI, A2UI_EXTENSION_URI_V08, A2UI_MIME_TYPE, type Action, type ActionContextItem, type ActionV08, type AnyComponent, type AudioPlayerComponent, type BeginRenderingMessage, BooleanOrPath, type ButtonComponent, type CardComponent, type CheckBoxComponent, type ChildrenProperty, type ChoicePickerComponent, type ClientToServerMessage, type ColumnComponent, type ComponentCommon, type ComponentInstance, type ComponentInstanceV08, type ComponentType, type CreateSurfaceMessage, type DataArray, type DataChangeEvent, type DataModelUpdateMessage, type DataObject, type DataValue, type DateTimeInputComponent, type DeleteSurfaceMessage, type DeleteSurfaceMessageV08, type DividerComponent, type IconComponent, type ImageComponent, type ListComponent, type ModalComponent, NumberOrPath, type RowComponent, STANDARD_CATALOG_ID, type ServerToClientMessage, type ServerToClientMessageV08, type ServerToClientMessageV09, type SliderComponent, type StandardIconName, StringArrayOrPath, StringOrPath, type SurfaceUpdateMessage, type TabsComponent, type TextComponent, type TextFieldComponent, type Theme, type UpdateComponentsMessage, type UpdateDataModelMessage, type UserActionEvent, type ValueMap, type VideoComponent, isV08Message, isV09Message };
663
+ export { A2UI_EXTENSION_URI, A2UI_MIME_TYPE, type Action, type AnyComponent, type AudioPlayerComponent, BooleanOrPath, type ButtonComponent, type CardComponent, type CheckBoxComponent, type ChildrenProperty, type ChoicePickerComponent, type ClientErrorMessage, type ClientToServerMessage, type ColumnComponent, type ComponentCommon, type ComponentInstance, type ComponentType, type CreateSurfaceMessage, type DataArray, type DataChangeEvent, type DataObject, type DataValue, type DateTimeInputComponent, type DeleteSurfaceMessage, type DividerComponent, type GenericError, type IconComponent, type ImageComponent, type ListComponent, type ModalComponent, NumberOrPath, type RowComponent, STANDARD_CATALOG_ID, type ServerToClientMessageV09, type SliderComponent, type StandardIconName, StringArrayOrPath, StringOrPath, type TabsComponent, type TextComponent, type TextFieldComponent, type Theme, type UpdateComponentsMessage, type UpdateDataModelMessage, type UserActionEvent, type ValidationFailedError, type VideoComponent, isV09Message };