@tbox.cn/app-contracts 0.1.3 → 0.9.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.
- package/dist/cards.d.ts +171 -4
- package/dist/context-slot.d.ts +23 -0
- package/dist/host-effect.d.ts +66 -0
- package/dist/identity.d.ts +15 -4
- package/dist/index.d.ts +9 -0
- package/dist/integrations-config.d.ts +3 -0
- package/dist/memory-tool.d.ts +64 -0
- package/dist/memory.d.ts +94 -0
- package/dist/no-inline-secrets.d.ts +1 -0
- package/dist/pre-tool.d.ts +56 -0
- package/dist/protocol.d.ts +90 -3
- package/dist/providers.d.ts +368 -0
- package/dist/runtime.d.ts +12 -2
- package/dist/runtime.js +509 -3
- package/dist/skill.d.ts +49 -0
- package/package.json +14 -10
- package/tests/__snapshots__/integrations-config-parity.test.ts.snap +354 -0
- package/tests/integrations-config-parity.test.ts +81 -0
- package/tests/integrations-config.test.ts +274 -0
package/dist/cards.d.ts
CHANGED
|
@@ -17,8 +17,6 @@ export interface CardMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
|
|
|
17
17
|
cardType: string;
|
|
18
18
|
/** 卡片预期接收的数据形状(zod schema) */
|
|
19
19
|
dataSchema: TSchema;
|
|
20
|
-
/** 允许哪些 tool 触发此卡片(白名单;SDK 依此自动生成 tool→card 绑定,声明即绑定) */
|
|
21
|
-
allowedTools: readonly string[];
|
|
22
20
|
/** 显示名(给开发者看的) */
|
|
23
21
|
displayName: string;
|
|
24
22
|
/** 卡片功能描述(给开发者文档 / IDE hover / AGENTS.md 自动列表用) */
|
|
@@ -30,10 +28,57 @@ export interface CardMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
|
|
|
30
28
|
* - 选一组"看起来漂亮"的数据,让画廊呈现最佳状态
|
|
31
29
|
*/
|
|
32
30
|
sampleData: zInfer<TSchema>;
|
|
31
|
+
/**
|
|
32
|
+
* 附加状态样本集(可选;沉淀自 mall dev-gallery)。
|
|
33
|
+
* - dev 卡片预览页(/_tbox/card-preview)与模块单测消费;
|
|
34
|
+
* - 不含基准态——基准态恒出自 sampleData(防双源漂移),预览页由 sampleData
|
|
35
|
+
* 合成"初始态"样本后附加本集;
|
|
36
|
+
* - 缺省 = 仅 sampleData 初始态,存量模块零改动零迁移。
|
|
37
|
+
*/
|
|
38
|
+
samples?: CardSample<zInfer<TSchema>>[];
|
|
33
39
|
/** 卡片数据契约版本(一期启用;缺省视为 1) */
|
|
34
40
|
schemaVersion?: number;
|
|
35
41
|
/** 历史快照 schema 迁移:oldData → 新版本数据(001 §7.4) */
|
|
36
42
|
migrate?: (oldData: unknown, oldVersion: number) => Record<string, unknown>;
|
|
43
|
+
/**
|
|
44
|
+
* 信封投影(P1):data → 标题/副标题/通知/过期时间的纯函数派生视图。
|
|
45
|
+
* - 快照零改动:持久化只存 data,恢复(restoreCardSnapshot)与出卡(build)同公式重投影
|
|
46
|
+
* ——过期态随时间正确演化,历史卡无信封字段漂移;
|
|
47
|
+
* - 模块组件零感知(消费宿主 = CardRenderer 包装层)。
|
|
48
|
+
*/
|
|
49
|
+
project?: (data: Record<string, unknown>) => CardEnvelopeProjection;
|
|
50
|
+
}
|
|
51
|
+
/** 信封投影结果(P1:CardMeta.project 派生;字段与 TboxCardPayload 信封槽位同名) */
|
|
52
|
+
export interface CardEnvelopeProjection {
|
|
53
|
+
title?: string;
|
|
54
|
+
subtitle?: string;
|
|
55
|
+
/** 通知条(卡顶渲染,按 level 着色) */
|
|
56
|
+
notices?: CardNotice[];
|
|
57
|
+
/** 过期时间(epoch ms;CardRenderer 挂载期求值置灰,非实时跳动) */
|
|
58
|
+
expiresAt?: number;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* 单卡附加预览状态样本(沉淀自 mall dev-gallery;基准态恒出自 sampleData,不在此重复)。
|
|
62
|
+
* 一格 = 一个卡上看得出差别的状态;视觉等价输入合并一格并在 note 列全。
|
|
63
|
+
*/
|
|
64
|
+
export interface CardSample<T = unknown> {
|
|
65
|
+
/** 样本名(考察点短标签) */
|
|
66
|
+
label: string;
|
|
67
|
+
/** 考察点说明(含等价输入合并说明) */
|
|
68
|
+
note?: string;
|
|
69
|
+
/** 分组标题(考察维度,如「缴费卡·优惠矩阵」) */
|
|
70
|
+
group?: string;
|
|
71
|
+
data: T;
|
|
72
|
+
/** 历史卡形态(动作禁用分支) */
|
|
73
|
+
isHistory?: boolean;
|
|
74
|
+
/** 令牌缺席形态(授权过期分支——预览页不铸 token,按钮置灰) */
|
|
75
|
+
noTokens?: boolean;
|
|
76
|
+
}
|
|
77
|
+
/** 信封通知(P1:时效/提示的结构化表达,替代正文夹带) */
|
|
78
|
+
export interface CardNotice {
|
|
79
|
+
code: string;
|
|
80
|
+
level: 'info' | 'warning' | 'error';
|
|
81
|
+
message: string;
|
|
37
82
|
}
|
|
38
83
|
/**
|
|
39
84
|
* AG-UI CUSTOM('tbox:card') 事件的 value 形状。
|
|
@@ -51,6 +96,20 @@ export interface TboxCardPayload {
|
|
|
51
96
|
data: Record<string, unknown>;
|
|
52
97
|
status: 'ready' | 'error';
|
|
53
98
|
error?: string;
|
|
99
|
+
/**
|
|
100
|
+
* 卡片可执行动作(011 E7,声明即绑定;P1 富形状按 kind 分发):
|
|
101
|
+
* - actions:动作声明列表(渲染端据此显示按钮/入口,CardRenderer 按 kind 分发);
|
|
102
|
+
* - actionTokens:actionId → HMAC 授权 token(moduleAction 专用;kind 为
|
|
103
|
+
* sendMessage/openLink 的动作纯客户端语义,不签发)。
|
|
104
|
+
*/
|
|
105
|
+
actions?: CardActionPresentation[];
|
|
106
|
+
actionTokens?: Record<string, string>;
|
|
107
|
+
/** 信封字段(P1:CardMeta.project 出卡/恢复时盖章;CardRenderer 包装层消费) */
|
|
108
|
+
title?: string;
|
|
109
|
+
subtitle?: string;
|
|
110
|
+
notices?: CardNotice[];
|
|
111
|
+
/** 过期时间(epoch ms;过期置灰挂载期求值) */
|
|
112
|
+
expiresAt?: number;
|
|
54
113
|
/** 历史恢复卡片标志(true=历史恢复,禁交互;false/缺省=实时下发) */
|
|
55
114
|
isHistory?: boolean;
|
|
56
115
|
/** 数据契约版本(恢复时用于迁移) */
|
|
@@ -80,12 +139,115 @@ export interface CardSnapshot {
|
|
|
80
139
|
}
|
|
81
140
|
/** AG-UI CUSTOM 事件 name(卡片通道) */
|
|
82
141
|
export declare const TBOX_CARD_EVENT_NAME = "tbox:card";
|
|
83
|
-
/**
|
|
142
|
+
/**
|
|
143
|
+
* AG-UI CUSTOM 事件 name(卡片原地更新通道):载荷为完整 TboxCardPayload,
|
|
144
|
+
* 客户端按 id 原位替换(未命中丢弃;仅达当前连接,不落库不持久化)。
|
|
145
|
+
*/
|
|
146
|
+
export declare const TBOX_CARD_UPDATE_EVENT_NAME = "tbox:card-update";
|
|
147
|
+
/**
|
|
148
|
+
* AG-UI CUSTOM 事件 name(动作域瞬态反馈通道):无视觉投影结果
|
|
149
|
+
* (card/update 均缺省)时,result.text 经此通道下发;动作执行失败时
|
|
150
|
+
* 由服务端错误映射(toNoticeText)下发 error 级提示。仅达当前连接,
|
|
151
|
+
* 不落库不持久化。
|
|
152
|
+
*/
|
|
153
|
+
export declare const TBOX_NOTICE_EVENT_NAME = "tbox:notice";
|
|
154
|
+
/** tbox:notice 载荷:瞬态 toast 反馈(客户端按 level 分 tone 展示) */
|
|
155
|
+
export interface TboxNoticePayload {
|
|
156
|
+
level: 'info' | 'success' | 'error';
|
|
157
|
+
text: string;
|
|
158
|
+
/** 产生通知的卡片实例;动作反馈用于收敛卡内中间态。 */
|
|
159
|
+
surfaceId?: string;
|
|
160
|
+
}
|
|
161
|
+
/** 单张卡片组件:data(各卡自己定具体类型)+ cardId(交互卡用作 sendUiAction 的 surfaceId)+ isHistory(历史恢复标志)
|
|
162
|
+
* + actionTokens(015 P5:卡内表单提交通道——组件内自持输入状态,经
|
|
163
|
+
* sendUiAction(cardId, {type:'moduleAction', actionId, contextToken}, formData) 提交) */
|
|
84
164
|
export type CardComponent<T = unknown> = ComponentType<{
|
|
85
165
|
data: T;
|
|
86
166
|
cardId: string;
|
|
87
167
|
isHistory: boolean;
|
|
168
|
+
actionTokens?: Record<string, string>;
|
|
88
169
|
}>;
|
|
170
|
+
/**
|
|
171
|
+
* 原地更新结果(P0 卡片原地更新):目标恒为被点击卡(surfaceId),不出新卡、
|
|
172
|
+
* 不进候选池、不落库。data 经目标卡 dataSchema 校验后整体替换(schema 即合同)。
|
|
173
|
+
*/
|
|
174
|
+
export interface CardActionUpdateResult {
|
|
175
|
+
/** 完整卡片数据(dispatcher build + dataSchema 校验后整体替换目标卡 data) */
|
|
176
|
+
data: Record<string, unknown>;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* 卡片动作按钮声明(P1 富形状):payload.actions 条目,CardRenderer 默认按钮条按 kind 分发。
|
|
180
|
+
* - 词汇对齐 UiAction 联合的三个服务端/本地可分发变体(F16:信封用服务端动作词汇,
|
|
181
|
+
* TIER1 ActionDraft(条目级,itemActions)原地不动);
|
|
182
|
+
* - kind 缺省 = moduleAction(既有语义,需 actionTokens 配对);
|
|
183
|
+
* - sendMessage/openLink 为纯客户端语义(经 onAction 桥本地分发),不签发 token。
|
|
184
|
+
*/
|
|
185
|
+
export interface CardActionPresentation {
|
|
186
|
+
actionId: string;
|
|
187
|
+
label?: string;
|
|
188
|
+
kind?: 'moduleAction' | 'sendMessage' | 'openLink';
|
|
189
|
+
/** sendMessage:发出的文本(缺省用 label) */
|
|
190
|
+
value?: string;
|
|
191
|
+
/** sendMessage:是否落用户气泡(缺省 true) */
|
|
192
|
+
visible?: boolean;
|
|
193
|
+
/** openLink:目标 URL(https:/tel:) */
|
|
194
|
+
url?: string;
|
|
195
|
+
/** 视觉样式(缺省 secondary 描边) */
|
|
196
|
+
style?: 'primary' | 'secondary' | 'link';
|
|
197
|
+
/** 可用性(缺省 true;false 置灰 + title 提示 disabledReason) */
|
|
198
|
+
enabled?: boolean;
|
|
199
|
+
disabledReason?: string;
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* 卡片动作结果(011 E1-E7):模块动作执行产物。
|
|
203
|
+
* - card 实时直发(不经候选池);text 在动作域无视觉投影(无 card/update)时经
|
|
204
|
+
* tbox:notice 下发为可见反馈;effects 经 EffectRuntime.project 出事件;
|
|
205
|
+
* - update 原地更新被点击卡(与 card 互斥,dispatcher 运行时断言)。
|
|
206
|
+
*/
|
|
207
|
+
export interface CardActionResult {
|
|
208
|
+
/** 结果卡片(可缺省:仅文字/效果) */
|
|
209
|
+
card?: {
|
|
210
|
+
cardType: string;
|
|
211
|
+
data: Record<string, unknown>;
|
|
212
|
+
};
|
|
213
|
+
/** 原地更新(P0):data 整体替换被点击卡;与 card 互斥 */
|
|
214
|
+
update?: CardActionUpdateResult;
|
|
215
|
+
/** 附带文字 */
|
|
216
|
+
text?: string;
|
|
217
|
+
/** 宿主效果(封闭集合,见 EffectRuntime) */
|
|
218
|
+
effects?: unknown[];
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* 卡片写动作声明(011 E1,模块声明式):
|
|
222
|
+
* 模块 serverModule 内声明,模板/装配层收集注册 + 签发授权 token。
|
|
223
|
+
*/
|
|
224
|
+
export interface CardAction {
|
|
225
|
+
/** 动作 id(卡片 payload.actions 引用;全局唯一,模块前缀命名) */
|
|
226
|
+
actionId: string;
|
|
227
|
+
/** 入参 schema(zod;submitForm 表单数据或固定入参) */
|
|
228
|
+
inputSchema: unknown;
|
|
229
|
+
/** 一次性(缺省 false):consume 后令牌即失效 */
|
|
230
|
+
singleUse?: boolean;
|
|
231
|
+
/**
|
|
232
|
+
* 效果回调动作(015 P5):不进 payload.actions 按钮条、不出卡预签 token——
|
|
233
|
+
* 其 grant 由 dispatcher 补签(effect.callback.contextToken),client runner 回传专用。
|
|
234
|
+
*/
|
|
235
|
+
hidden?: boolean;
|
|
236
|
+
/**
|
|
237
|
+
* 按钮呈现(P1,透传 payload.actions;kind 缺省 moduleAction):
|
|
238
|
+
* sendMessage/openLink 为纯客户端语义,不参与授权签发。
|
|
239
|
+
*/
|
|
240
|
+
label?: string;
|
|
241
|
+
kind?: 'moduleAction' | 'sendMessage' | 'openLink';
|
|
242
|
+
value?: string;
|
|
243
|
+
visible?: boolean;
|
|
244
|
+
url?: string;
|
|
245
|
+
style?: 'primary' | 'secondary' | 'link';
|
|
246
|
+
enabled?: boolean;
|
|
247
|
+
disabledReason?: string;
|
|
248
|
+
/** 执行(输入 → 结果;授权已在 dispatcher 完成) */
|
|
249
|
+
execute(input: unknown, ctx: unknown): Promise<CardActionResult>;
|
|
250
|
+
}
|
|
89
251
|
/**
|
|
90
252
|
* 卡片反向通道动作(client 侧,与 protocol.ts 的 UiClientAction 对齐)。
|
|
91
253
|
* 由卡片 React 组件直接调 chatStore.sendUiAction 触发。
|
|
@@ -93,13 +255,18 @@ export type CardComponent<T = unknown> = ComponentType<{
|
|
|
93
255
|
export type UiAction = {
|
|
94
256
|
type: 'sendMessage';
|
|
95
257
|
value: string;
|
|
96
|
-
visible?: boolean;
|
|
258
|
+
visible?: boolean; /** 用户气泡显示文本;有值时气泡展示此,value 仍完整透传给 AI */
|
|
259
|
+
displayText?: string;
|
|
97
260
|
} | {
|
|
98
261
|
type: 'submitForm';
|
|
99
262
|
formId: string;
|
|
100
263
|
} | {
|
|
101
264
|
type: 'openLink';
|
|
102
265
|
url: string;
|
|
266
|
+
} | {
|
|
267
|
+
type: 'moduleAction';
|
|
268
|
+
actionId: string;
|
|
269
|
+
contextToken: string;
|
|
103
270
|
} | {
|
|
104
271
|
type: 'toast';
|
|
105
272
|
content: string;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ContextSlot 协议(上下文统一化 TIER0 原语):attributes 的结构化扩展。
|
|
3
|
+
*
|
|
4
|
+
* 领域扩展(如商圈 mallSlot)与应用自定义扩展共用同一协议——定义方持有 key 与
|
|
5
|
+
* parse 校验,消费方经 read(attributes) fail-soft 读取(解析失败/缺省 → undefined,
|
|
6
|
+
* 调用方自行降级)。协议刻意极简 `{ key, read }`:不做类型收窄包装(下游服务
|
|
7
|
+
* 反正要重新 parse,收窄只供养 as 断言——评审定案砍除)。
|
|
8
|
+
*/
|
|
9
|
+
export interface ContextSlot<T, K extends string = string> {
|
|
10
|
+
/** attributes 内的槽位键(如 'mall') */
|
|
11
|
+
readonly key: K;
|
|
12
|
+
/** fail-soft 读取:解析失败/缺省返回 undefined,调用方自行降级 */
|
|
13
|
+
read(attributes?: Record<string, unknown>): T | undefined;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* 定义 context 槽位(TIER0 零领域语义):
|
|
17
|
+
* @param opts.key attributes 内的槽位键
|
|
18
|
+
* @param opts.parse 原始值校验/解析(如 zod safeParse;返回 undefined = 视为缺省)
|
|
19
|
+
*/
|
|
20
|
+
export declare function defineContextSlot<K extends string, T>(opts: {
|
|
21
|
+
key: K;
|
|
22
|
+
parse: (raw: unknown) => T | undefined;
|
|
23
|
+
}): ContextSlot<T, K>;
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 宿主效果协议单源(015 P1)。
|
|
3
|
+
* 服务端(effect-runtime 投影)与客户端(host-effect-runner 执行)共用,
|
|
4
|
+
* 先例 = skill.ts / pre-tool.ts(协议常量与形状只在 contracts 定义一次)。
|
|
5
|
+
*
|
|
6
|
+
* 封闭集合纪律(011 I14):无 custom 槽位,新增宿主效果类型走提案评审。
|
|
7
|
+
* client 约定:未识别 type 一律 no-op + warn,不 throw 不回传(015 F4)。
|
|
8
|
+
*/
|
|
9
|
+
/** 宿主效果事件名(CUSTOM 事件下行) */
|
|
10
|
+
export declare const TBOX_EFFECT_EVENT_NAME = "tbox:effect";
|
|
11
|
+
/**
|
|
12
|
+
* 回调通道(015 P2 dispatcher 补签注入):
|
|
13
|
+
* payment / authorization 效果完成后,client 经 UI_ACTION moduleAction
|
|
14
|
+
* 携 contextToken 回传结果——single-use grant(TTL 10min,服务端签发)。
|
|
15
|
+
*/
|
|
16
|
+
export interface EffectCallback {
|
|
17
|
+
/** 回调动作 id(模块 register 期注册;dispatcher 校验归属后写入) */
|
|
18
|
+
actionId: string;
|
|
19
|
+
/** single-use context token(grant) */
|
|
20
|
+
contextToken: string;
|
|
21
|
+
}
|
|
22
|
+
/** 宿主效果封闭集合 */
|
|
23
|
+
export type HostEffect = {
|
|
24
|
+
type: 'navigation.open';
|
|
25
|
+
routeId: string;
|
|
26
|
+
params?: Record<string, string>;
|
|
27
|
+
} | {
|
|
28
|
+
type: 'payment';
|
|
29
|
+
/** 停车/收银台支付引用(report-payment-result 回传定位用) */
|
|
30
|
+
paymentRef: string;
|
|
31
|
+
/** 厂商签名拉起串(不透明透传给 my.tradePay;服务端 StateStore 已持久化对应 PaymentOperation 供对账) */
|
|
32
|
+
orderInfo: string;
|
|
33
|
+
/** 支付结果回调动作 id(dispatcher 补签校验 + 注入 callback) */
|
|
34
|
+
resultActionId: string;
|
|
35
|
+
/** 由 dispatcher 补签注入(模块不填写) */
|
|
36
|
+
callback?: EffectCallback;
|
|
37
|
+
} | {
|
|
38
|
+
type: 'share';
|
|
39
|
+
} | {
|
|
40
|
+
type: 'download';
|
|
41
|
+
} | {
|
|
42
|
+
type: 'authorization.alipay-user-profile';
|
|
43
|
+
/** 申请的授权 scope(如 ['auth_user']) */
|
|
44
|
+
scopes: string[];
|
|
45
|
+
/** 授权结果回调动作 id(dispatcher 补签校验 + 注入 callback) */
|
|
46
|
+
resultActionId: string;
|
|
47
|
+
/** 由 dispatcher 补签注入(模块不填写) */
|
|
48
|
+
callback?: EffectCallback;
|
|
49
|
+
} | {
|
|
50
|
+
/**
|
|
51
|
+
* 平台通知:会话凭证已升级(如入会成功),宿主应刷新会话(清缓存重登 + 重连拿新 credentials)。
|
|
52
|
+
* 通知型效果——无 callback/resultActionId(宿主侧执行,无结果回传),幂等由宿主守卫承担
|
|
53
|
+
* (去重器对无 contextToken 恒放行)。
|
|
54
|
+
*/
|
|
55
|
+
type: 'session.credentials-refreshed';
|
|
56
|
+
/** 升级动因(模块自述,仅供日志/埋点;enrolled=入会 / reauthorized=重新授权) */
|
|
57
|
+
reason?: 'enrolled' | 'reauthorized';
|
|
58
|
+
};
|
|
59
|
+
/** 客户端回传的执行结果(moduleAction formData 形状,供回调动作 inputSchema 消费) */
|
|
60
|
+
export interface HostEffectResult {
|
|
61
|
+
status: 'success' | 'cancel' | 'failure' | 'unavailable';
|
|
62
|
+
/** payment:回传 paymentRef 定位操作 */
|
|
63
|
+
paymentRef?: string;
|
|
64
|
+
/** authorization:成功时携带授权码 */
|
|
65
|
+
authCode?: string;
|
|
66
|
+
}
|
package/dist/identity.d.ts
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* - userId 命名(006 D4 修订):local/dev 由模板生成,前缀 local_/dev_;**external 原样保留
|
|
8
8
|
* (外部系统自管命名空间,不加前缀/不归一化)**;anonymous 服务端生成、不签发 JWT。
|
|
9
9
|
* - RequestContext 单一运行上下文(identity + conversationId + credentials + attributes),
|
|
10
|
-
*
|
|
10
|
+
* 显式通道读取(0.11.0 上下文统一化:handle 第四参 / 工具 execute 第二参读取器——ctx.auth 已拆除)。
|
|
11
11
|
*/
|
|
12
12
|
export type UserIdSource = 'local' | 'external' | 'dev' | 'anonymous';
|
|
13
13
|
export interface Identity {
|
|
@@ -18,14 +18,20 @@ export interface Identity {
|
|
|
18
18
|
displayName?: string;
|
|
19
19
|
avatar?: string;
|
|
20
20
|
}
|
|
21
|
-
/** 外部原始凭据(嵌自有 JWT 的 external claim;组件经
|
|
21
|
+
/** 外部原始凭据(嵌自有 JWT 的 external claim;组件经 reqCtx.credentials 显式取用) */
|
|
22
22
|
export interface ExternalCredentials {
|
|
23
|
-
/** 外部原始 token(JWT / opaque / session
|
|
23
|
+
/** 外部原始 token(JWT / opaque / session);空串 = 在场但无会话型凭证(如 joycity 非会员身份登录) */
|
|
24
24
|
token: string;
|
|
25
25
|
/** 外部 provider 标识(如 alipay-iap / mall-gateway) */
|
|
26
26
|
provider: string;
|
|
27
27
|
/** 外部 token 过期时间(ms epoch;未知则不传) */
|
|
28
28
|
expiresAt?: number;
|
|
29
|
+
/**
|
|
30
|
+
* provider 语义自管命名空间的外部身份属性(假名 id,非 PII;如 joycity 三元组
|
|
31
|
+
* lightuid/openid/signid),原样内嵌 external claim 随自有 JWT 流动,消费端经
|
|
32
|
+
* reqCtx.credentials.attributes 直取(如入会注册链)。
|
|
33
|
+
*/
|
|
34
|
+
attributes?: Record<string, string>;
|
|
29
35
|
}
|
|
30
36
|
/** 换发结果:身份 +(可选)外部原始凭据,成对流动 */
|
|
31
37
|
export interface ExchangeResult {
|
|
@@ -58,7 +64,12 @@ export interface RequestContext {
|
|
|
58
64
|
*/
|
|
59
65
|
export interface IdentityExchange {
|
|
60
66
|
readonly provider: string;
|
|
61
|
-
|
|
67
|
+
/**
|
|
68
|
+
* code → ExchangeResult。
|
|
69
|
+
* @param context 域中性业务上下文槽位(对齐 HelloEvent.context 先例:消费方自定键,TIER0 零领域语义;
|
|
70
|
+
* 路由层保证 plain object 且体积约束,实现方可宽松读取所需键)
|
|
71
|
+
*/
|
|
72
|
+
exchangeByCode(code: string, platform?: string, context?: Readonly<Record<string, unknown>>): Promise<ExchangeResult>;
|
|
62
73
|
}
|
|
63
74
|
export declare const AUTH_ERROR_CODES: {
|
|
64
75
|
/** 401:凭证缺失/非法 */
|
package/dist/index.d.ts
CHANGED
|
@@ -4,3 +4,12 @@ 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 './memory-tool';
|
|
10
|
+
export * from './providers';
|
|
11
|
+
export * from './integrations-config';
|
|
12
|
+
export * from './no-inline-secrets';
|
|
13
|
+
export * from './host-effect';
|
|
14
|
+
export * from './memory';
|
|
15
|
+
export * from './context-slot';
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 记忆召回前端表达协议(018 tool-debug 视图):
|
|
3
|
+
* - server 实时合成事件与 client 显示共用 tool-call 表达形状;
|
|
4
|
+
* - 单一来源:实时合成与显示经同一序列化单点,禁止两端各自 hardcode;
|
|
5
|
+
* - 纯协议无 UI 语义:文案/渲染留装配层(SDK describeToolCall + 模板 ToolCallBlock);
|
|
6
|
+
* - 隐私边界:仅 toolDebug 开启时由服务端发射,不持久化、不进历史重建
|
|
7
|
+
* (debug 期间实时可见、历史不可回看)。
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* 前端记忆召回表达专用 tool-call 名(内部伪工具,对齐 __tbox_skill / __tbox_pretool 先例)。
|
|
11
|
+
*/
|
|
12
|
+
export declare const MEMORY_TOOL_CALL_NAME = "__tbox_memory";
|
|
13
|
+
/** 记录预览 text 截断上限(构造器内置——有界暴露,构造端无需重复截断) */
|
|
14
|
+
export declare const MEMORY_RECORD_PREVIEW_MAX_CHARS = 200;
|
|
15
|
+
/** 合成 tool-call args(实时 ARGS 事件共用) */
|
|
16
|
+
export interface MemoryToolCallArgs {
|
|
17
|
+
query: string;
|
|
18
|
+
topK?: number;
|
|
19
|
+
}
|
|
20
|
+
/** 记录预览(text 已按 MEMORY_RECORD_PREVIEW_MAX_CHARS 截断) */
|
|
21
|
+
export interface MemoryRecordPreview {
|
|
22
|
+
id: string;
|
|
23
|
+
kind: string;
|
|
24
|
+
text: string;
|
|
25
|
+
}
|
|
26
|
+
/** 合成 tool-call result(实时 RESULT 事件共用) */
|
|
27
|
+
export interface MemoryToolCallResult {
|
|
28
|
+
status: 'hit' | 'miss' | 'degraded' | 'skipped';
|
|
29
|
+
/** 命中条数(hit 时 ≥1,其余缺省) */
|
|
30
|
+
hits?: number;
|
|
31
|
+
records?: MemoryRecordPreview[];
|
|
32
|
+
/** skipped 原因(机器值,如 'intent'——意图命中轮) */
|
|
33
|
+
reason?: string;
|
|
34
|
+
/** degraded 时错误信息 */
|
|
35
|
+
error?: string;
|
|
36
|
+
/** 召回耗时 ms(best-effort 观测) */
|
|
37
|
+
durMs?: number;
|
|
38
|
+
}
|
|
39
|
+
/** 记录输入形状(MemoryRecord 最小投影——contracts 不反向依赖 SDK 内部类型) */
|
|
40
|
+
export interface MemoryRecallRecordInput {
|
|
41
|
+
id: string;
|
|
42
|
+
kind: string;
|
|
43
|
+
content: string;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* 载荷序列化单点(实时路径两事件共用;text 截断内置):
|
|
47
|
+
* JSON 形状只存在于本函数。
|
|
48
|
+
*/
|
|
49
|
+
export declare function buildMemoryToolCallPayload(input: {
|
|
50
|
+
query: string;
|
|
51
|
+
topK?: number;
|
|
52
|
+
status: MemoryToolCallResult['status'];
|
|
53
|
+
records?: MemoryRecallRecordInput[];
|
|
54
|
+
reason?: string;
|
|
55
|
+
error?: string;
|
|
56
|
+
durMs?: number;
|
|
57
|
+
}): {
|
|
58
|
+
args: string;
|
|
59
|
+
result: string;
|
|
60
|
+
};
|
|
61
|
+
/** 容错解析(前端显示用):非法 JSON / 缺 query → undefined(调用方降级默认文案) */
|
|
62
|
+
export declare function parseMemoryToolCallArgs(args?: string): MemoryToolCallArgs | undefined;
|
|
63
|
+
/** 容错解析:非法 JSON / 非法 status → undefined */
|
|
64
|
+
export declare function parseMemoryToolCallResult(result?: string): MemoryToolCallResult | undefined;
|
package/dist/memory.d.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent 长期记忆契约(017):跨会话/跨重启的用户偏好与事实记忆。
|
|
3
|
+
* TIER0 types-only(+ 错误码/协议常量),双端共享:server 存储/检索/注入,client 管理面消费。
|
|
4
|
+
*
|
|
5
|
+
* 设计要点(评审冻结):
|
|
6
|
+
* - 7 字段纯语义结构:治理字段(contentHash/scopeKey)下沉实现层纯函数派生,契约零漂移;
|
|
7
|
+
* - MemoryStore 四方法正交(save/search/list/delete),混合配额检索策略上移引擎单点(F1);
|
|
8
|
+
* - capabilities 能力描述符:构造期门控(工具注册/recall/提示词/路由四消费点),
|
|
9
|
+
* 缺省全真(内存实现不声明即全支持;知识库实现按平台现状保守声明);
|
|
10
|
+
* - 错误码常量在 contracts、Error 类在 SDK(对齐 AUTH_ERROR_CODES 先例);
|
|
11
|
+
* - MEMORY_REMINDER_ATTR 注入块协议单源(server 构造/剥离共用,双端禁 hardcode)。
|
|
12
|
+
*/
|
|
13
|
+
/** 记忆类型:preference(偏好)/ fact(事实)/ episode(事件经历) */
|
|
14
|
+
export type MemoryKind = 'preference' | 'fact' | 'episode';
|
|
15
|
+
/**
|
|
16
|
+
* 记忆记录(7 字段纯语义):
|
|
17
|
+
* - id:`mem_<8hex>`(实现 B 中 = segmentId);
|
|
18
|
+
* - userId:隔离主键(匿名在引擎层拦截,不进 store);
|
|
19
|
+
* - scope:隔离副键(如 mall:{ mallId });同 userId 不同 scope 互不可见;
|
|
20
|
+
* - importance:0~1,检索排序与容量淘汰依据(基线 preference/fact 0.7、episode 0.6);
|
|
21
|
+
* - createdAt:ms epoch。
|
|
22
|
+
*/
|
|
23
|
+
export interface MemoryRecord {
|
|
24
|
+
id: string;
|
|
25
|
+
userId: string;
|
|
26
|
+
kind: MemoryKind;
|
|
27
|
+
content: string;
|
|
28
|
+
scope?: Record<string, string>;
|
|
29
|
+
importance: number;
|
|
30
|
+
createdAt: number;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* 存储能力描述符:实现声明的真实可用能力(缺省全真)。
|
|
34
|
+
* 构造期门控:search=false → 不注册 memory_search 工具、recall 跳过 search 半;
|
|
35
|
+
* list=false → recall 跳过 list 半、HTTP GET 501;delete=false → 不注册 memory_forget、HTTP DELETE 501。
|
|
36
|
+
*/
|
|
37
|
+
export interface MemoryStoreCapabilities {
|
|
38
|
+
save: boolean;
|
|
39
|
+
search: boolean;
|
|
40
|
+
list: boolean;
|
|
41
|
+
delete: boolean;
|
|
42
|
+
}
|
|
43
|
+
export interface MemorySaveInput {
|
|
44
|
+
userId: string;
|
|
45
|
+
scope?: Record<string, string>;
|
|
46
|
+
kind: MemoryKind;
|
|
47
|
+
content: string;
|
|
48
|
+
}
|
|
49
|
+
export interface MemorySearchInput {
|
|
50
|
+
userId: string;
|
|
51
|
+
scope?: Record<string, string>;
|
|
52
|
+
query: string;
|
|
53
|
+
topK?: number;
|
|
54
|
+
}
|
|
55
|
+
export interface MemoryListInput {
|
|
56
|
+
userId: string;
|
|
57
|
+
scope?: Record<string, string>;
|
|
58
|
+
limit?: number;
|
|
59
|
+
}
|
|
60
|
+
export interface MemoryDeleteInput {
|
|
61
|
+
userId: string;
|
|
62
|
+
scope?: Record<string, string>;
|
|
63
|
+
id: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* 记忆存储接口(实现职责分界——store 管留存,引擎管注入):
|
|
67
|
+
* - save:治理内嵌(contentHash 命中合并 importance 取大;超容量淘汰最低分/同分最旧);
|
|
68
|
+
* - search:纯相关性排序(实现自定:内存 BM25 / 知识库语义);
|
|
69
|
+
* - list:importance 降序、同分 createdAt 降序;limit 缺省 50、上限 200;
|
|
70
|
+
* - delete:归属校验(userId+scope+id 不匹配返回 false——安全不变量);
|
|
71
|
+
* - capabilities:缺省全真;知识库实现按平台现状保守声明(缺口期诚实降级)。
|
|
72
|
+
*/
|
|
73
|
+
export interface MemoryStore {
|
|
74
|
+
save(input: MemorySaveInput): Promise<MemoryRecord>;
|
|
75
|
+
search(input: MemorySearchInput): Promise<MemoryRecord[]>;
|
|
76
|
+
list(input: MemoryListInput): Promise<MemoryRecord[]>;
|
|
77
|
+
delete(input: MemoryDeleteInput): Promise<boolean>;
|
|
78
|
+
readonly capabilities?: MemoryStoreCapabilities;
|
|
79
|
+
}
|
|
80
|
+
export declare const MEMORY_ERROR_CODES: {
|
|
81
|
+
/** 知识库实现:segment upsert 接口未开放(平台缺口 #1)——save 不可用 */
|
|
82
|
+
readonly KB_SEGMENT_UPSERT_NOT_SUPPORTED: "MEMORY_KB_SEGMENT_UPSERT_NOT_SUPPORTED";
|
|
83
|
+
/** 知识库实现:segment delete 接口未开放(平台缺口 #2)——delete 不可用 */
|
|
84
|
+
readonly KB_SEGMENT_DELETE_NOT_SUPPORTED: "MEMORY_KB_SEGMENT_DELETE_NOT_SUPPORTED";
|
|
85
|
+
/** 知识库实现:检索通道无 pre filter 能力——search 硬失败(永不无过滤检索,INV-1) */
|
|
86
|
+
readonly KB_SEARCH_FILTER_NOT_SUPPORTED: "MEMORY_KB_SEARCH_FILTER_NOT_SUPPORTED";
|
|
87
|
+
/** 知识库实现:排序通道不可用——list 硬失败 */
|
|
88
|
+
readonly KB_LIST_FIELDSORT_NOT_SUPPORTED: "MEMORY_KB_LIST_FIELDSORT_NOT_SUPPORTED";
|
|
89
|
+
/** 知识库实现:启动校验失败(异步闸门降级态)——记忆功能不可用,调用时报错 */
|
|
90
|
+
readonly MEMORY_KB_VALIDATION_FAILED: "MEMORY_KB_VALIDATION_FAILED";
|
|
91
|
+
};
|
|
92
|
+
export type MemoryErrorCode = (typeof MEMORY_ERROR_CODES)[keyof typeof MEMORY_ERROR_CODES];
|
|
93
|
+
/** 注入块标签属性(`<system-reminder memory>`)——server 构造/剥离单源锚点 */
|
|
94
|
+
export declare const MEMORY_REMINDER_ATTR = "memory";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function assertNoInlineSecrets(config: unknown, path?: string): void;
|
|
@@ -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;
|