@tbox.cn/app-contracts 0.1.3 → 0.1.5

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.
package/dist/cards.d.ts CHANGED
@@ -30,6 +30,11 @@ export interface CardMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
30
30
  * - 选一组"看起来漂亮"的数据,让画廊呈现最佳状态
31
31
  */
32
32
  sampleData: zInfer<TSchema>;
33
+ /**
34
+ * 012:对话路径出主卡优先级(越大越优先;缺省 0;仅出卡决策用,不进快照/历史)。
35
+ * 分级建议:详情(80) < 列表(90) < 目录/FAQ(100) < 比较/导航(110-120),值域 0-999。
36
+ */
37
+ priority?: number;
33
38
  /** 卡片数据契约版本(一期启用;缺省视为 1) */
34
39
  schemaVersion?: number;
35
40
  /** 历史快照 schema 迁移:oldData → 新版本数据(001 §7.4) */
@@ -51,6 +56,16 @@ export interface TboxCardPayload {
51
56
  data: Record<string, unknown>;
52
57
  status: 'ready' | 'error';
53
58
  error?: string;
59
+ /**
60
+ * 卡片可执行动作(011 E7,声明即绑定):
61
+ * - actions:动作声明列表(渲染端据此显示按钮/入口);
62
+ * - actionTokens:actionId → HMAC 授权 token(渲染端点击回传 componentAction)。
63
+ */
64
+ actions?: {
65
+ actionId: string;
66
+ label?: string;
67
+ }[];
68
+ actionTokens?: Record<string, string>;
54
69
  /** 历史恢复卡片标志(true=历史恢复,禁交互;false/缺省=实时下发) */
55
70
  isHistory?: boolean;
56
71
  /** 数据契约版本(恢复时用于迁移) */
@@ -80,12 +95,60 @@ export interface CardSnapshot {
80
95
  }
81
96
  /** AG-UI CUSTOM 事件 name(卡片通道) */
82
97
  export declare const TBOX_CARD_EVENT_NAME = "tbox:card";
98
+ /**
99
+ * 对话路径出卡候选(012):一轮 run 内 cardResolver resolve ready 的卡。
100
+ * 前置契约:入参须按产生顺序 push(同 priority 同 source 平局依赖稳定排序取先产生者)。
101
+ */
102
+ export interface PrimaryCardCandidate {
103
+ cardType: string;
104
+ data: Record<string, unknown>;
105
+ /** 卡 meta priority(push 时从 cardRegistry 读取,缺省 0) */
106
+ priority: number;
107
+ /** 候选来源(平局规则:model > pretool——精确执行优先于预执行猜测) */
108
+ source: 'pretool' | 'model';
109
+ }
110
+ /** 主卡选择器(012 N5:可注入策略;缺省 = defaultPrimaryCardSelector) */
111
+ export type PrimaryCardSelector = (candidates: readonly PrimaryCardCandidate[]) => PrimaryCardCandidate | undefined;
112
+ /**
113
+ * 缺省主卡选择:priority 降序 → source(model 优先)→ 稳定序保底。
114
+ * 空候选 → undefined(不出卡)。纯函数零依赖。
115
+ */
116
+ export declare function defaultPrimaryCardSelector(candidates: readonly PrimaryCardCandidate[]): PrimaryCardCandidate | undefined;
83
117
  /** 单张卡片组件:data(各卡自己定具体类型)+ cardId(交互卡用作 sendUiAction 的 surfaceId)+ isHistory(历史恢复标志) */
84
118
  export type CardComponent<T = unknown> = ComponentType<{
85
119
  data: T;
86
120
  cardId: string;
87
121
  isHistory: boolean;
88
122
  }>;
123
+ /**
124
+ * 卡片动作结果(011 E1-E7):组件动作执行产物。
125
+ * - card 走 cardResolver 出卡;text 补一句文字;effects 经 EffectRuntime.project 出事件。
126
+ */
127
+ export interface CardActionResult {
128
+ /** 结果卡片(可缺省:仅文字/效果) */
129
+ card?: {
130
+ cardType: string;
131
+ data: Record<string, unknown>;
132
+ };
133
+ /** 附带文字 */
134
+ text?: string;
135
+ /** 宿主效果(封闭集合,见 EffectRuntime) */
136
+ effects?: unknown[];
137
+ }
138
+ /**
139
+ * 卡片写动作声明(011 E1,模块声明式):
140
+ * 模块 serverModule 内声明,模板/装配层收集注册 + 签发授权 token。
141
+ */
142
+ export interface CardAction {
143
+ /** 动作 id(卡片 payload.actions 引用;全局唯一,模块前缀命名) */
144
+ actionId: string;
145
+ /** 入参 schema(zod;submitForm 表单数据或固定入参) */
146
+ inputSchema: unknown;
147
+ /** 一次性(缺省 false):consume 后令牌即失效 */
148
+ singleUse?: boolean;
149
+ /** 执行(输入 → 结果;授权已在 dispatcher 完成) */
150
+ execute(input: unknown, ctx: unknown): Promise<CardActionResult>;
151
+ }
89
152
  /**
90
153
  * 卡片反向通道动作(client 侧,与 protocol.ts 的 UiClientAction 对齐)。
91
154
  * 由卡片 React 组件直接调 chatStore.sendUiAction 触发。
@@ -100,6 +163,10 @@ export type UiAction = {
100
163
  } | {
101
164
  type: 'openLink';
102
165
  url: string;
166
+ } | {
167
+ type: 'componentAction';
168
+ actionId: string;
169
+ contextToken: string;
103
170
  } | {
104
171
  type: 'toast';
105
172
  content: string;
package/dist/index.d.ts CHANGED
@@ -4,3 +4,6 @@ export * from './adapters';
4
4
  export * from './identity';
5
5
  export * from './session';
6
6
  export * from './tts';
7
+ export * from './skill';
8
+ export * from './pre-tool';
9
+ export * from './providers';
@@ -0,0 +1,56 @@
1
+ /**
2
+ * 前置工具(pre-tool)前端表达协议(010):
3
+ * - server 实时合成事件与 client 历史重建共用的 tool-call 表达形状;
4
+ * - 单一来源:实时合成与历史表达经同一序列化单点,禁止两端各自 hardcode;
5
+ * - 纯协议无 UI 语义:文案/渲染留装配层(SDK describeToolCall + 模板 ToolCallBlock)。
6
+ */
7
+ /** 前置工具前端表达专用 tool-call 名(内部伪工具,对齐 __tbox_skill / __a2uiFormSubmit 先例) */
8
+ export declare const PRE_TOOL_CALL_NAME = "__tbox_pretool";
9
+ /**
10
+ * 工具 id 防御校验(历史重建用,平台存储数据不可全信):
11
+ * 字符类为 [A-Za-z0-9_-]{1,64}——与 skill 的 ^[a-z0-9-]{1,64}$ 不同(工具 id 合法含大写),不强行统一。
12
+ */
13
+ export declare const PRE_TOOL_NAME_PATTERN: RegExp;
14
+ /** 合成 tool-call args(实时 ARGS 事件 / 历史重建共用) */
15
+ export interface PreToolCallArgs {
16
+ toolName: string;
17
+ description?: string;
18
+ toolArgs?: unknown;
19
+ }
20
+ /** 合成 tool-call result(实时 RESULT 事件 / 历史重建共用) */
21
+ export interface PreToolCallResult {
22
+ toolName: string;
23
+ status: 'done' | 'error';
24
+ result?: unknown;
25
+ error?: string;
26
+ }
27
+ /**
28
+ * 前置工具执行记录(server 持久化 inputs.preTools 与 client 历史消费共用 DTO)。
29
+ * 仅 done 记录落库(失败是实时轮的表达,模型会自行重试,不持久化)。
30
+ */
31
+ export interface PreToolRecord {
32
+ toolName: string;
33
+ description?: string;
34
+ args?: Record<string, unknown>;
35
+ result?: unknown;
36
+ }
37
+ /**
38
+ * ARGS 载荷序列化(实时路径在执行前发射;历史重建共用):
39
+ * JSON 形状只存在于本函数。
40
+ */
41
+ export declare function buildPreToolArgsPayload(input: {
42
+ toolName: string;
43
+ description?: string;
44
+ toolArgs?: unknown;
45
+ }): string;
46
+ /** RESULT 载荷序列化(实时路径执行后发射;历史重建共用) */
47
+ export declare function buildPreToolResultPayload(input: PreToolCallResult): string;
48
+ /** 历史重建组合序列化(PreToolRecord → { args, result },两路径字节级同构) */
49
+ export declare function buildPreToolToolCallPayload(record: PreToolRecord): {
50
+ args: string;
51
+ result: string;
52
+ };
53
+ /** 容错解析(前端显示用):非法 JSON / 缺 toolName → undefined(调用方降级默认文案) */
54
+ export declare function parsePreToolToolCallArgs(args?: string): PreToolCallArgs | undefined;
55
+ /** 容错解析:非法 JSON / 缺 toolName / 非法 status → undefined */
56
+ export declare function parsePreToolToolCallResult(result?: string): PreToolCallResult | undefined;
@@ -11,7 +11,9 @@ type RunScopedErrorEvent = RunErrorEvent & {
11
11
  runId?: string;
12
12
  };
13
13
  /** 所有服务端 → 客户端事件 */
14
- export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent;
14
+ export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent
15
+ /** HELLO 鉴权成功应答(011 F4) */
16
+ | HelloAckEvent;
15
17
  export interface SendMessageMediaItem {
16
18
  fileId: string;
17
19
  type: 'image' | 'video' | 'audio' | 'file';
@@ -51,6 +53,30 @@ export interface CancelRunEvent {
51
53
  export interface HelloEvent {
52
54
  type: 'HELLO';
53
55
  token?: string;
56
+ /**
57
+ * 客户端运行时上下文(011 F1):服务端鉴权后并入该连接 RequestContext.attributes。
58
+ * 通用槽位(TIER0 无领域语义):mall 场景 = { mall: { miniAppId, mallId } },由 TIER1 解析。
59
+ */
60
+ context?: Record<string, unknown>;
61
+ }
62
+ /**
63
+ * HELLO 鉴权成功后的应答(011 F4):
64
+ * - mallScope 回显服务端确认的会话 scope(TIER0 槽位,领域语义由 TIER1 解析器赋予);
65
+ * - chatConfig 由服务端下发(快捷指令等单一真源,本地文件仅 fallback)。
66
+ */
67
+ export interface HelloAckEvent {
68
+ type: 'HELLO_ACK';
69
+ /** 服务端确认的会话 scope(无 scope 绑定的部署缺省) */
70
+ mallScope?: Record<string, string>;
71
+ /** 会话配置(快捷指令等) */
72
+ chatConfig: HelloAckChatConfig;
73
+ }
74
+ export interface HelloAckChatConfig {
75
+ quickCommands: {
76
+ label: string;
77
+ prompt: string;
78
+ }[];
79
+ enableImageUpload: boolean;
54
80
  }
55
81
  /**
56
82
  * 卡片反向通道动作。
@@ -76,6 +102,12 @@ export type UiClientAction = {
76
102
  tone?: 'info' | 'success' | 'error';
77
103
  } | {
78
104
  type: 'closeCard';
105
+ }
106
+ /** 写+确定性动作(011 E1):actionId + 一次性授权 token,经 ActionGrant 校验后执行 */
107
+ | {
108
+ type: 'componentAction';
109
+ actionId: string;
110
+ contextToken: string;
79
111
  };
80
112
  export interface UiActionEvent {
81
113
  type: 'UI_ACTION';
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Provider 抽象契约(011,TIER0 纯通用——零领域语义):
3
+ * 外部服务 Provider 的实例/模版/凭证/传输层类型定义,双端可消费(types-only)。
4
+ *
5
+ * 设计要点(011 G1-G7):
6
+ * - scope 是通用路由键(Record<string,string>),领域语义由 TIER1 赋予(mall 场景 = { miniAppId, mallId });
7
+ * - transport 缓存责任在 SDK(key = templateId + stable(scope) + credentialVersion);
8
+ * - connector 缓存责任在模块(key = templateId + mallId);
9
+ * - credentialRef 指向 EnvironmentSecretProvider('secret://{env}/{seg...}'),生产缺引用即 fail-fast。
10
+ */
11
+ /** Provider 实例(部署配置三段之一:providerInstances 元素) */
12
+ export interface ProviderInstance {
13
+ /** 实例唯一 id */
14
+ providerInstanceId: string;
15
+ /** 模版引用:'id@version' */
16
+ providerTemplateId: string;
17
+ /** 通用路由键(mall 场景 = { miniAppId, mallId });缓存键参与方,必须可稳定序列化 */
18
+ scope?: Record<string, string>;
19
+ /** 实例级配置(连接参数等非机密项;机密走 credentialRef) */
20
+ config?: Record<string, unknown>;
21
+ /** 机密引用:'secret://{env}/{seg...}',由 EnvironmentSecretProvider 解析 */
22
+ credentialRef?: string;
23
+ /** 凭证版本:变更 → SDK transport 缓存整体失效(轮换唯一入口) */
24
+ credentialVersion?: string;
25
+ /** 禁用实例 resolve 直接抛错 */
26
+ enabled: boolean;
27
+ }
28
+ /** Provider 模版声明(文档用途 + 认证策略注册点匹配) */
29
+ export interface ProviderTemplateDeclaration {
30
+ /** 'id@version'(与 ProviderInstance.providerTemplateId 匹配) */
31
+ providerTemplateId: string;
32
+ /** 能力声明(文档用途;capability 运行时概念已砍,见 011 I1) */
33
+ capabilities?: string[];
34
+ /** 配置 schema 文档(校验由 SDK registry 经注入 validator 执行) */
35
+ configSchema?: unknown;
36
+ /** 认证类型:ProviderAuthStrategy.credentialType 注册点匹配键 */
37
+ credentialType: string;
38
+ /** 凭证 schema 文档 */
39
+ credentialSchema?: unknown;
40
+ }
41
+ /** 解析后的机密(EnvironmentSecretProvider.resolve 产物) */
42
+ export interface ProviderCredential {
43
+ /** 凭证适用 scope(与实例 scope 严格匹配才可用) */
44
+ scope: Record<string, string>;
45
+ /** 类型:'static-headers-v1' | 模块自定义 strategy 注册点 */
46
+ type: string;
47
+ /** 机密值(头名/密钥等;应用后即弃,禁止落日志) */
48
+ value: Record<string, unknown>;
49
+ }
50
+ /** 认证后的传输层(模块唯一调用面) */
51
+ export interface AuthenticatedTransport {
52
+ request(opts: {
53
+ /** API 路径(相对 baseUrl;baseUrl 由 transport 内部持有) */
54
+ path: string;
55
+ query?: Record<string, string>;
56
+ body?: unknown;
57
+ timeoutMs?: number;
58
+ extraHeaders?: Record<string, string>;
59
+ }): Promise<unknown>;
60
+ }
61
+ /** resolve 产物:传输层 + 只读实例(模块 connector 构造输入) */
62
+ export interface ResolvedProvider {
63
+ transport: AuthenticatedTransport;
64
+ instance: Readonly<ProviderInstance>;
65
+ }
66
+ /**
67
+ * scope 稳定序列化(缓存键组成):键字典序 + 值 JSON 转义,
68
+ * 与对象字面量键序无关。SDK 缓存键实现必须经本函数(单一来源)。
69
+ */
70
+ export declare function stableSerializeScope(scope?: Record<string, string>): string;
71
+ /** Provider 错误码(SDK transport/registry 抛出;模块据此分支) */
72
+ export declare const PROVIDER_ERROR_CODES: {
73
+ /** 实例被禁用(enabled=false) */
74
+ readonly INSTANCE_DISABLED: "PROVIDER_INSTANCE_DISABLED";
75
+ /** 无匹配实例(templateId + scope) */
76
+ readonly INSTANCE_NOT_FOUND: "PROVIDER_INSTANCE_NOT_FOUND";
77
+ /** 凭证引用缺失(生产 fail-fast) */
78
+ readonly CREDENTIAL_REF_MISSING: "PROVIDER_CREDENTIAL_REF_MISSING";
79
+ /** 凭证 scope 与实例 scope 不匹配 */
80
+ readonly CREDENTIAL_SCOPE_MISMATCH: "PROVIDER_CREDENTIAL_SCOPE_MISMATCH";
81
+ /** 熔断开闸 */
82
+ readonly CIRCUIT_OPEN: "PROVIDER_CIRCUIT_OPEN";
83
+ /** 响应超限(1MB) */
84
+ readonly RESPONSE_TOO_LARGE: "PROVIDER_RESPONSE_TOO_LARGE";
85
+ /** 传输失败归类(429/5xx/NETWORK/TIMEOUT) */
86
+ readonly TRANSPORT_FAILURE: "PROVIDER_TRANSPORT_FAILURE";
87
+ };
88
+ export type ProviderErrorCode = (typeof PROVIDER_ERROR_CODES)[keyof typeof PROVIDER_ERROR_CODES];
package/dist/runtime.d.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  /**
2
- * 契约包协议常量(004 D5:契约包允许协议常量级运行时值)。
2
+ * 契约包协议常量 + 协议纯函数(004 D5:契约包允许协议常量级运行时值;012:含主卡策略)。
3
3
  * .d.ts 为主(tsc emitDeclarationOnly);本文件为唯一运行时 JS(经 tsup/esbuild 出 dist/runtime.js)。
4
4
  * 修订 001 §2.6"契约包 types-only"表述:types-only 为主,允许协议常量级运行时值。
5
5
  */
6
6
  export { EventType } from '@ag-ui/core';
7
- export { TBOX_CARD_EVENT_NAME } from './cards';
7
+ export { TBOX_CARD_EVENT_NAME, defaultPrimaryCardSelector } from './cards';
8
8
  export { AUTH_ERROR_CODES, authCodeToStatus } from './identity';
9
+ export { stableSerializeScope, PROVIDER_ERROR_CODES } from './providers';
10
+ export * from './skill';
11
+ export * from './pre-tool';
package/dist/runtime.js CHANGED
@@ -3,6 +3,13 @@ import { EventType } from "@ag-ui/core";
3
3
 
4
4
  // src/cards.ts
5
5
  var TBOX_CARD_EVENT_NAME = "tbox:card";
6
+ var PRIMARY_SOURCE_RANK = { model: 0, pretool: 1 };
7
+ function defaultPrimaryCardSelector(candidates) {
8
+ if (candidates.length === 0) return void 0;
9
+ return [...candidates].sort(
10
+ (a, b) => b.priority - a.priority || PRIMARY_SOURCE_RANK[a.source] - PRIMARY_SOURCE_RANK[b.source]
11
+ )[0];
12
+ }
6
13
 
7
14
  // src/identity.ts
8
15
  var AUTH_ERROR_CODES = {
@@ -35,9 +42,163 @@ function authCodeToStatus(code) {
35
42
  return 401;
36
43
  }
37
44
  }
45
+
46
+ // src/providers.ts
47
+ function stableSerializeScope(scope) {
48
+ if (!scope) return "";
49
+ const keys = Object.keys(scope).sort();
50
+ const parts = keys.map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(scope[k]))}`);
51
+ return parts.join("&");
52
+ }
53
+ var PROVIDER_ERROR_CODES = {
54
+ /** 实例被禁用(enabled=false) */
55
+ INSTANCE_DISABLED: "PROVIDER_INSTANCE_DISABLED",
56
+ /** 无匹配实例(templateId + scope) */
57
+ INSTANCE_NOT_FOUND: "PROVIDER_INSTANCE_NOT_FOUND",
58
+ /** 凭证引用缺失(生产 fail-fast) */
59
+ CREDENTIAL_REF_MISSING: "PROVIDER_CREDENTIAL_REF_MISSING",
60
+ /** 凭证 scope 与实例 scope 不匹配 */
61
+ CREDENTIAL_SCOPE_MISMATCH: "PROVIDER_CREDENTIAL_SCOPE_MISMATCH",
62
+ /** 熔断开闸 */
63
+ CIRCUIT_OPEN: "PROVIDER_CIRCUIT_OPEN",
64
+ /** 响应超限(1MB) */
65
+ RESPONSE_TOO_LARGE: "PROVIDER_RESPONSE_TOO_LARGE",
66
+ /** 传输失败归类(429/5xx/NETWORK/TIMEOUT) */
67
+ TRANSPORT_FAILURE: "PROVIDER_TRANSPORT_FAILURE"
68
+ };
69
+
70
+ // src/skill.ts
71
+ var SKILL_NAME_SRC = "[a-z0-9-]{1,64}";
72
+ var SKILL_NAME_PATTERN = new RegExp(`^${SKILL_NAME_SRC}$`);
73
+ var SKILL_TOOL_CALL_NAME = "__tbox_skill";
74
+ var SKILL_REMINDER_OPEN_TAG_SRC = String.raw`<system-reminder\s+skill="(${SKILL_NAME_SRC})">`;
75
+ function buildSkillReminderOpenTagPattern() {
76
+ return new RegExp(SKILL_REMINDER_OPEN_TAG_SRC, "g");
77
+ }
78
+ function buildSkillReminderBlockPattern() {
79
+ return new RegExp(
80
+ String.raw`${SKILL_REMINDER_OPEN_TAG_SRC}[\s\S]*?<\/system-reminder>`,
81
+ "g"
82
+ );
83
+ }
84
+ function parseSkillReminders(text) {
85
+ const skills = [];
86
+ if (!text) return { skills, cleanedText: text };
87
+ const re = buildSkillReminderBlockPattern();
88
+ let cleaned = text;
89
+ let m;
90
+ while ((m = re.exec(text)) !== null) {
91
+ if (!skills.includes(m[1])) skills.push(m[1]);
92
+ cleaned = cleaned.replace(m[0], "");
93
+ }
94
+ const cleanedText = skills.length > 0 ? cleaned.replace(/^\s+|\s+$/g, "") : text;
95
+ return { skills, cleanedText };
96
+ }
97
+ function buildSkillToolCallPayload(skill) {
98
+ const args = {
99
+ skillName: skill.name,
100
+ ...skill.description ? { description: skill.description } : {}
101
+ };
102
+ const result = { skillName: skill.name, status: "loaded" };
103
+ return { args: JSON.stringify(args), result: JSON.stringify(result) };
104
+ }
105
+ function parseSkillToolCallArgs(args) {
106
+ if (!args) return void 0;
107
+ try {
108
+ const parsed = JSON.parse(args);
109
+ if (typeof parsed?.skillName !== "string" || !parsed.skillName) return void 0;
110
+ return {
111
+ skillName: parsed.skillName,
112
+ ...typeof parsed.description === "string" ? { description: parsed.description } : {}
113
+ };
114
+ } catch {
115
+ return void 0;
116
+ }
117
+ }
118
+
119
+ // src/pre-tool.ts
120
+ var PRE_TOOL_CALL_NAME = "__tbox_pretool";
121
+ var PRE_TOOL_NAME_PATTERN = new RegExp(`^[A-Za-z0-9_-]{1,64}$`);
122
+ function buildPreToolArgsPayload(input) {
123
+ const args = {
124
+ toolName: input.toolName,
125
+ ...input.description ? { description: input.description } : {},
126
+ ...input.toolArgs !== void 0 ? { toolArgs: input.toolArgs } : {}
127
+ };
128
+ return JSON.stringify(args);
129
+ }
130
+ function buildPreToolResultPayload(input) {
131
+ const result = {
132
+ toolName: input.toolName,
133
+ status: input.status,
134
+ ...input.result !== void 0 ? { result: input.result } : {},
135
+ ...input.error ? { error: input.error } : {}
136
+ };
137
+ return JSON.stringify(result);
138
+ }
139
+ function buildPreToolToolCallPayload(record) {
140
+ return {
141
+ args: buildPreToolArgsPayload({
142
+ toolName: record.toolName,
143
+ ...record.description ? { description: record.description } : {},
144
+ ...record.args !== void 0 ? { toolArgs: record.args } : {}
145
+ }),
146
+ result: buildPreToolResultPayload({
147
+ toolName: record.toolName,
148
+ status: "done",
149
+ ...record.result !== void 0 ? { result: record.result } : {}
150
+ })
151
+ };
152
+ }
153
+ function parsePreToolToolCallArgs(args) {
154
+ if (!args) return void 0;
155
+ try {
156
+ const parsed = JSON.parse(args);
157
+ if (typeof parsed?.toolName !== "string" || !parsed.toolName) return void 0;
158
+ return {
159
+ toolName: parsed.toolName,
160
+ ...typeof parsed.description === "string" ? { description: parsed.description } : {},
161
+ ...parsed.toolArgs !== void 0 ? { toolArgs: parsed.toolArgs } : {}
162
+ };
163
+ } catch {
164
+ return void 0;
165
+ }
166
+ }
167
+ function parsePreToolToolCallResult(result) {
168
+ if (!result) return void 0;
169
+ try {
170
+ const parsed = JSON.parse(result);
171
+ if (typeof parsed?.toolName !== "string" || !parsed.toolName) return void 0;
172
+ if (parsed.status !== "done" && parsed.status !== "error") return void 0;
173
+ return {
174
+ toolName: parsed.toolName,
175
+ status: parsed.status,
176
+ ...parsed.result !== void 0 ? { result: parsed.result } : {},
177
+ ...typeof parsed.error === "string" ? { error: parsed.error } : {}
178
+ };
179
+ } catch {
180
+ return void 0;
181
+ }
182
+ }
38
183
  export {
39
184
  AUTH_ERROR_CODES,
40
185
  EventType,
186
+ PRE_TOOL_CALL_NAME,
187
+ PRE_TOOL_NAME_PATTERN,
188
+ PROVIDER_ERROR_CODES,
189
+ SKILL_NAME_PATTERN,
190
+ SKILL_TOOL_CALL_NAME,
41
191
  TBOX_CARD_EVENT_NAME,
42
- authCodeToStatus
192
+ authCodeToStatus,
193
+ buildPreToolArgsPayload,
194
+ buildPreToolResultPayload,
195
+ buildPreToolToolCallPayload,
196
+ buildSkillReminderOpenTagPattern,
197
+ buildSkillToolCallPayload,
198
+ defaultPrimaryCardSelector,
199
+ parsePreToolToolCallArgs,
200
+ parsePreToolToolCallResult,
201
+ parseSkillReminders,
202
+ parseSkillToolCallArgs,
203
+ stableSerializeScope
43
204
  };
@@ -0,0 +1,49 @@
1
+ /**
2
+ * skill 前端表达协议(009 D9/D10):reminder 文本协议工具 + tool-call 表达形状。
3
+ * - 单一来源:server(合成事件/注入解析)与 client(历史解析/显示)共用,禁止两端各自 hardcode;
4
+ * - 纯协议无 UI 语义:文案/渲染留装配层。
5
+ */
6
+ /** skill 名强校验(与 reminder 开标签解析正则一致,保证解析安全) */
7
+ export declare const SKILL_NAME_PATTERN: RegExp;
8
+ /**
9
+ * 前端 skill 表达专用 tool-call 名(内部伪工具)。
10
+ * 与 mastra 原生 skill_read 命名空间解耦(同名不同义风险),对齐 __a2uiFormSubmit 先例;
11
+ * progressive 模式下模型真实 skill_read 调用不做本协议适配(显示默认工具文案)。
12
+ */
13
+ export declare const SKILL_TOOL_CALL_NAME = "__tbox_skill";
14
+ /** skill 加载记录(server 持久化 inputs.skills 与 client 历史消费共用 DTO) */
15
+ export interface SkillRecord {
16
+ name: string;
17
+ description?: string;
18
+ }
19
+ /** 构造开标签匹配正则(每次 new,无状态)——server scanInjectedSkills 同源使用 */
20
+ export declare function buildSkillReminderOpenTagPattern(): RegExp;
21
+ /**
22
+ * 剥离 reminder 块(纯函数):
23
+ * - 完整块(开标签 + 闭标签)整体移除;skills 返回命中 name 列表(保序去重);
24
+ * - 未闭合/非法 name 不剥离(宁留不误删——name 强校验锚定,SOP 正文禁用完整开标签为既有铁律)。
25
+ */
26
+ export declare function parseSkillReminders(text: string): {
27
+ skills: string[];
28
+ cleanedText: string;
29
+ };
30
+ /** 合成 tool-call args(tbox 协议形状,实时/历史共用) */
31
+ export interface SkillToolCallArgs {
32
+ skillName: string;
33
+ description?: string;
34
+ }
35
+ /** 合成 tool-call result(tbox 协议形状) */
36
+ export interface SkillToolCallResult {
37
+ skillName: string;
38
+ status: 'loaded';
39
+ }
40
+ /**
41
+ * 单点序列化:实时合成事件与历史表达生成共用 → 两路径字节级同构
42
+ * (args/result 的 JSON 形状只存在于本函数)。
43
+ */
44
+ export declare function buildSkillToolCallPayload(skill: SkillRecord): {
45
+ args: string;
46
+ result: string;
47
+ };
48
+ /** 容错解析(前端显示用):非法 JSON / 缺 skillName → undefined(调用方降级默认文案) */
49
+ export declare function parseSkillToolCallArgs(args?: string): SkillToolCallArgs | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tbox.cn/app-contracts",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "type": "module",
5
5
  "description": "平台契约(TIER0,types-only 为主 + 协议常量运行时值):卡片协议 / SDK adapter / 平台 DTO。",
6
6
  "exports": {