@tbox.cn/app-contracts 0.12.2 → 0.12.4

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
@@ -46,17 +46,25 @@ export interface CardMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
46
46
  * - 标记原因须写明类型:暂停型(工具恢复时移除标记)或永久型(注明决策出处)。
47
47
  */
48
48
  hidden?: boolean;
49
+ /**
50
+ * 预览目录序位(additive,缺席合法):dev 卡片预览目录组内排序位,小者在前。
51
+ * - 排序键 = 属主模块 → order → cardType;缺省卡恒排在已声明 order 卡之后,
52
+ * 组内剩余按 cardType 字母序兜底(存量模块零改动维持现序);
53
+ * - 仅影响 dev 预览目录(buildCatalog)——不进出卡管线/候选池次序
54
+ * (出卡顺序由模型决策条序决定)、不进历史快照。
55
+ */
56
+ order?: number;
49
57
  /** 历史快照 schema 迁移:oldData → 新版本数据(001 §7.4) */
50
58
  migrate?: (oldData: unknown, oldVersion: number) => Record<string, unknown>;
51
59
  /**
52
- * 信封投影(P1):data → 标题/副标题/通知/过期时间的纯函数派生视图。
60
+ * 信封投影:data → 标题/副标题/通知/过期时间的纯函数派生视图。
53
61
  * - 快照零改动:持久化只存 data,恢复(restoreCardSnapshot)与出卡(build)同公式重投影
54
62
  * ——过期态随时间正确演化,历史卡无信封字段漂移;
55
63
  * - 模块组件零感知(消费宿主 = CardRenderer 包装层)。
56
64
  */
57
65
  project?: (data: Record<string, unknown>) => CardEnvelopeProjection;
58
66
  }
59
- /** 信封投影结果(P1:CardMeta.project 派生;字段与 TboxCardPayload 信封槽位同名) */
67
+ /** 信封投影结果(CardMeta.project 派生;字段与 TboxCardPayload 信封槽位同名) */
60
68
  export interface CardEnvelopeProjection {
61
69
  title?: string;
62
70
  subtitle?: string;
@@ -89,7 +97,7 @@ export interface CardSample<T = unknown> {
89
97
  */
90
98
  hidden?: boolean;
91
99
  }
92
- /** 信封通知(P1:时效/提示的结构化表达,替代正文夹带) */
100
+ /** 信封通知(时效/提示的结构化表达,替代正文夹带) */
93
101
  export interface CardNotice {
94
102
  code: string;
95
103
  level: 'info' | 'warning' | 'error';
@@ -112,14 +120,14 @@ export interface TboxCardPayload {
112
120
  status: 'ready' | 'error';
113
121
  error?: string;
114
122
  /**
115
- * 卡片可执行动作(011 E7,声明即绑定;P1 富形状按 kind 分发):
123
+ * 卡片可执行动作(声明即绑定; 富形状按 kind 分发):
116
124
  * - actions:动作声明列表(渲染端据此显示按钮/入口,CardRenderer 按 kind 分发);
117
125
  * - actionTokens:actionId → HMAC 授权 token(moduleAction 专用;kind 为
118
126
  * sendMessage/openLink 的动作纯客户端语义,不签发)。
119
127
  */
120
128
  actions?: CardActionPresentation[];
121
129
  actionTokens?: Record<string, string>;
122
- /** 信封字段(P1:CardMeta.project 出卡/恢复时盖章;CardRenderer 包装层消费) */
130
+ /** 信封字段(CardMeta.project 出卡/恢复时盖章;CardRenderer 包装层消费) */
123
131
  title?: string;
124
132
  subtitle?: string;
125
133
  notices?: CardNotice[];
@@ -145,7 +153,7 @@ export interface CardSnapshot {
145
153
  data: Record<string, unknown>;
146
154
  status: 'ready' | 'error';
147
155
  schemaVersion: number;
148
- /** 关联的 assistant 消息(消息 ↔ 卡片关联,P3 新增) */
156
+ /** 关联的 assistant 消息(消息 ↔ 卡片关联, 新增) */
149
157
  messageId?: string;
150
158
  meta?: {
151
159
  createdAt: number;
@@ -174,7 +182,7 @@ export interface TboxNoticePayload {
174
182
  surfaceId?: string;
175
183
  }
176
184
  /** 单张卡片组件:data(各卡自己定具体类型)+ cardId(交互卡用作 sendUiAction 的 surfaceId)+ isHistory(历史恢复标志)
177
- * + actionTokens(015 P5:卡内表单提交通道——组件内自持输入状态,经
185
+ * + actionTokens(卡内表单提交通道——组件内自持输入状态,经
178
186
  * sendUiAction(cardId, {type:'moduleAction', actionId, contextToken}, formData) 提交) */
179
187
  export type CardComponent<T = unknown> = ComponentType<{
180
188
  data: T;
@@ -183,7 +191,7 @@ export type CardComponent<T = unknown> = ComponentType<{
183
191
  actionTokens?: Record<string, string>;
184
192
  }>;
185
193
  /**
186
- * 原地更新结果(P0 卡片原地更新):目标恒为被点击卡(surfaceId),不出新卡、
194
+ * 原地更新结果(卡片原地更新):目标恒为被点击卡(surfaceId),不出新卡、
187
195
  * 不进候选池、不落库。data 经目标卡 dataSchema 校验后整体替换(schema 即合同)。
188
196
  */
189
197
  export interface CardActionUpdateResult {
@@ -191,8 +199,8 @@ export interface CardActionUpdateResult {
191
199
  data: Record<string, unknown>;
192
200
  }
193
201
  /**
194
- * 卡片动作按钮声明(P1 富形状):payload.actions 条目,CardRenderer 默认按钮条按 kind 分发。
195
- * - 词汇对齐 UiAction 联合的三个服务端/本地可分发变体(F16:信封用服务端动作词汇,
202
+ * 卡片动作按钮声明(富形状):payload.actions 条目,CardRenderer 默认按钮条按 kind 分发。
203
+ * - 词汇对齐 UiAction 联合的三个服务端/本地可分发变体(信封用服务端动作词汇,
196
204
  * TIER1 ActionDraft(条目级,itemActions)原地不动);
197
205
  * - kind 缺省 = moduleAction(既有语义,需 actionTokens 配对);
198
206
  * - sendMessage/openLink 为纯客户端语义(经 onAction 桥本地分发),不签发 token。
@@ -214,7 +222,7 @@ export interface CardActionPresentation {
214
222
  disabledReason?: string;
215
223
  }
216
224
  /**
217
- * 卡片动作结果(011 E1-E7):模块动作执行产物。
225
+ * 卡片动作结果(-E7):模块动作执行产物。
218
226
  * - card 实时直发(不经候选池);text 在动作域无视觉投影(无 card/update)时经
219
227
  * tbox:notice 下发为可见反馈;effects 经 EffectRuntime.project 出事件;
220
228
  * - update 原地更新被点击卡(与 card 互斥,dispatcher 运行时断言)。
@@ -225,7 +233,7 @@ export interface CardActionResult {
225
233
  cardType: string;
226
234
  data: Record<string, unknown>;
227
235
  };
228
- /** 原地更新(P0):data 整体替换被点击卡;与 card 互斥 */
236
+ /** 原地更新:data 整体替换被点击卡;与 card 互斥 */
229
237
  update?: CardActionUpdateResult;
230
238
  /** 附带文字 */
231
239
  text?: string;
@@ -233,7 +241,7 @@ export interface CardActionResult {
233
241
  effects?: unknown[];
234
242
  }
235
243
  /**
236
- * 卡片写动作声明(011 E1,模块声明式):
244
+ * 卡片写动作声明(模块声明式):
237
245
  * 模块 serverModule 内声明,模板/装配层收集注册 + 签发授权 token。
238
246
  */
239
247
  export interface CardAction {
@@ -244,12 +252,12 @@ export interface CardAction {
244
252
  /** 一次性(缺省 false):consume 后令牌即失效 */
245
253
  singleUse?: boolean;
246
254
  /**
247
- * 效果回调动作(015 P5):不进 payload.actions 按钮条、不出卡预签 token——
255
+ * 效果回调动作:不进 payload.actions 按钮条、不出卡预签 token——
248
256
  * 其 grant 由 dispatcher 补签(effect.callback.contextToken),client runner 回传专用。
249
257
  */
250
258
  hidden?: boolean;
251
259
  /**
252
- * 按钮呈现(P1,透传 payload.actions;kind 缺省 moduleAction):
260
+ * 按钮呈现(透传 payload.actions;kind 缺省 moduleAction):
253
261
  * sendMessage/openLink 为纯客户端语义,不参与授权签发。
254
262
  */
255
263
  label?: string;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 客户端槽位契约(单一模板统一化 W1-②):壳渲染受控扩展点词汇。
2
+ * 客户端槽位契约(单一模板统一化):壳渲染受控扩展点词汇。
3
3
  *
4
4
  * 应用形态由槽存在性派生(home 槽注册 = home-first 主屏;缺席 = chat 流 + kit 欢迎态)。
5
5
  * 槽 id 为 TIER0 封闭集(新槽 = same-change 本文件 + kit/模块消费方 + docs);
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 域装配契约(单一模板统一化 W1-③):域模块注册、SDK/装配层惰性查表的域装配单元。
2
+ * 域装配契约(单一模板统一化):域模块注册、SDK/装配层惰性查表的域装配单元。
3
3
  *
4
4
  * 消费点(全部运行期查表,register 顺序无关——registerAll 先于 listen,
5
5
  * authExchanges 同款「晚于构造仍生效」先例):
@@ -1,15 +1,15 @@
1
1
  /**
2
- * 宿主效果协议单源(015 P1)。
2
+ * 宿主效果协议单源。
3
3
  * 服务端(effect-runtime 投影)与客户端(host-effect-runner 执行)共用,
4
4
  * 先例 = skill.ts / pre-tool.ts(协议常量与形状只在 contracts 定义一次)。
5
5
  *
6
6
  * 封闭集合纪律(011 I14):无 custom 槽位,新增宿主效果类型走提案评审。
7
- * client 约定:未识别 type 一律 no-op + warn,不 throw 不回传(015 F4)。
7
+ * client 约定:未识别 type 一律 no-op + warn,不 throw 不回传。
8
8
  */
9
9
  /** 宿主效果事件名(CUSTOM 事件下行) */
10
10
  export declare const TBOX_EFFECT_EVENT_NAME = "tbox:effect";
11
11
  /**
12
- * 回调通道(015 P2 dispatcher 补签注入):
12
+ * 回调通道(dispatcher 补签注入):
13
13
  * payment / authorization 效果完成后,client 经 UI_ACTION moduleAction
14
14
  * 携 contextToken 回传结果——single-use grant(TTL 10min,服务端签发)。
15
15
  */
@@ -2,7 +2,7 @@
2
2
  * 统一用户授权鉴权契约(006):身份 / Token / 换发 / 运行上下文。
3
3
  * TIER0 types-only(+ 错误码常量),双端共享:服务端签发/校验、客户端消费。
4
4
  *
5
- * 设计要点(006 §2 / D1-D4 + 2026-09 四源修订):
5
+ * 设计要点(006 §2 /- + 2026-09 四源修订):
6
6
  * - 自有 JWT 唯一形态;外部一律内置换发(三态收敛),原始 token 嵌 `external` claim。
7
7
  * - userId 命名:local/guest 由平台生成,强制前缀 local_/guest_(guest = 服务端随机访客身份,
8
8
  * `guest_<32hex>`);**external 原样保留(外部系统自管命名空间,不加前缀/不归一化)**;
package/dist/memory.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  *
5
5
  * 设计要点(评审冻结):
6
6
  * - 7 字段纯语义结构:治理字段(contentHash/scopeKey)下沉实现层纯函数派生,契约零漂移;
7
- * - MemoryStore 四方法正交(save/search/list/delete),混合配额检索策略上移引擎单点(F1);
7
+ * - MemoryStore 四方法正交(save/search/list/delete),混合配额检索策略上移引擎单点;
8
8
  * - capabilities 能力描述符:构造期门控(工具注册/recall/提示词/路由四消费点),
9
9
  * 缺省全真(内存实现不声明即全支持;知识库实现按平台现状保守声明);
10
10
  * - 错误码常量在 contracts、Error 类在 SDK(对齐 AUTH_ERROR_CODES 先例);
@@ -31,7 +31,7 @@ type ToolCallResultErrorEvent = ToolCallResultEvent & {
31
31
  };
32
32
  /** 所有服务端 → 客户端事件 */
33
33
  export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | RunNotEstablishedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultErrorEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent
34
- /** HELLO 鉴权成功应答(011 F4) */
34
+ /** HELLO 鉴权成功应答 */
35
35
  | HelloAckEvent
36
36
  /** 传输层业务保活(双向对称;连接级事件,无身份/顺序语义) */
37
37
  | PingEvent | PongEvent;
@@ -77,7 +77,7 @@ export interface ResumeConversationEvent {
77
77
  type: 'RESUME_CONVERSATION';
78
78
  }
79
79
  /**
80
- * WS 连接握手事件。客户端在 onOpen 时发送一次,**只做鉴权**(006 D6/D12):
80
+ * WS 连接握手事件。客户端在 onOpen 时发送一次,**只做鉴权**(/):
81
81
  * - 携带自有 JWT(消息体传输,不拼 URL,防泄漏);
82
82
  * - 服务端校验后绑定连接级身份(Identity + 可选外部凭据);
83
83
  * - optional 模式下无 token 的 HELLO → 服务端生成匿名身份并绑定;
@@ -87,13 +87,13 @@ export interface HelloEvent {
87
87
  type: 'HELLO';
88
88
  token?: string;
89
89
  /**
90
- * 客户端运行时上下文(011 F1):服务端鉴权后并入该连接 RequestContext.attributes。
90
+ * 客户端运行时上下文:服务端鉴权后并入该连接 RequestContext.attributes。
91
91
  * 通用槽位(TIER0 无领域语义):mall 场景 = { mall: { miniAppId, mallId } },由 TIER1 解析。
92
92
  */
93
93
  context?: Record<string, unknown>;
94
94
  }
95
95
  /**
96
- * HELLO 鉴权成功后的应答(011 F4):
96
+ * HELLO 鉴权成功后的应答:
97
97
  * - mallScope 回显服务端确认的会话 scope(TIER0 槽位,领域语义由 TIER1 解析器赋予);
98
98
  * - chatConfig 由服务端下发(快捷指令 + settings 会话 UI 设置单一真源,本地文件仅 fallback)。
99
99
  */
@@ -158,7 +158,7 @@ export type UiClientAction = {
158
158
  } | {
159
159
  type: 'closeCard';
160
160
  }
161
- /** 写+确定性动作(011 E1):actionId + 一次性授权 token,经 ActionGrant 校验后执行 */
161
+ /** 写+确定性动作:actionId + 一次性授权 token,经 ActionGrant 校验后执行 */
162
162
  | {
163
163
  type: 'moduleAction';
164
164
  actionId: string;
@@ -2,7 +2,7 @@
2
2
  * Provider 抽象契约(011,TIER0 纯通用——零领域语义):
3
3
  * 外部服务 Provider 的实例/模版/凭证/传输层类型定义,双端可消费(types-only)。
4
4
  *
5
- * 设计要点(011 G1-G7;integrations v4 现状):
5
+ * 设计要点(-G7;integrations v4 现状):
6
6
  * - scope 是通用路由键(Record<string,string>),领域语义由 TIER1 赋予(mall 场景 = { miniAppId, mallId });
7
7
  * - transport 缓存责任在 SDK(integrations v2 键 = service + instanceId + provider + implementation;
8
8
  * 换绑后旧 transport 留存复用,配置无热轮换——重载即重启进程);
@@ -34,7 +34,7 @@ export interface ProviderInstance {
34
34
  export interface ProviderTemplateDeclaration {
35
35
  /** 'id@version'(与 ProviderInstance.providerTemplateId 匹配) */
36
36
  providerTemplateId: string;
37
- /** 能力声明(文档用途;capability 运行时概念已砍,见 011 I1) */
37
+ /** 能力声明(文档用途;capability 运行时概念已砍,见) */
38
38
  capabilities?: string[];
39
39
  /** 配置 schema 文档(校验由 SDK registry 经注入 validator 执行) */
40
40
  configSchema?: unknown;
@@ -111,7 +111,7 @@ export declare function isExpectedProviderAbsence(e: unknown): boolean;
111
111
  * 内联厂商声明(仅槽级 provider 字段可用;实例级 provider 恒字符串)。
112
112
  * integrations.json 内直接声明供给,不经 provider 包 manifest。
113
113
  * 未实施态语义:catalog/adapter 均无对应实现 → doctor warning + resolve 抛 PROVIDER_NOT_IMPLEMENTED
114
- * (F5 交互化的「先声明后实施」闭环)。
114
+ * (交互化的「先声明后实施」闭环)。
115
115
  */
116
116
  export interface InlineVendorDeclaration {
117
117
  /** 厂商名(= 档位名 = provider 包轴,如 'wanda') */
@@ -255,7 +255,7 @@ export declare const WILDCARD_INSTANCE_KEY = "*";
255
255
  /**
256
256
  * integrations v6 形状标记:resolveEffectiveService 接受 ownerOf 第五参、modules 节承载
257
257
  * provider/config(模块所有权模型)。app-toolkit assertContractsUsable 经出口在场性探测
258
- * 本标记——v5 contracts + v6 toolkit 偏斜组合 → 503 第四分支(P1 标记门;防静默忽略 ownerOf)。
258
+ * 本标记——v5 contracts + v6 toolkit 偏斜组合 → 503 第四分支(标记门;防静默忽略 ownerOf)。
259
259
  */
260
260
  export declare const OWNERSHIP_BINDING_V6: true;
261
261
  /**
@@ -338,7 +338,7 @@ export interface CatalogProviderEntry {
338
338
  export interface CatalogServiceEntry {
339
339
  /** 可选槽(未配置不 error——doctor warning 级) */
340
340
  optional: boolean;
341
- /** manifest defaults(F5 页面预填缺省供给) */
341
+ /** manifest defaults(页面预填缺省供给) */
342
342
  defaults: Array<{
343
343
  provider: string;
344
344
  implementation: string;
@@ -348,10 +348,10 @@ export interface CatalogServiceEntry {
348
348
  }
349
349
  /** loadProviderCatalog 产物:全应用 provider 供给与需求聚合(.tbox/app.json npmModules 真源) */
350
350
  export interface ProviderCatalog {
351
- /** 嵌套形态:厂商级语义一跳、F5 厂商→实现级联枚举天然序;migrate 反查表 = 本表自身 */
351
+ /** 嵌套形态:厂商级语义一跳、 厂商→实现级联枚举天然序;migrate 反查表 = 本表自身 */
352
352
  providers: Record<string, Record<string, CatalogProviderEntry>>;
353
353
  services: Record<string, CatalogServiceEntry>;
354
- /** credentialType 直达索引(F5/doctor 单跳;同名共享单例先例) */
354
+ /** credentialType 直达索引(/doctor 单跳;同名共享单例先例) */
355
355
  credentialTypes: Record<string, {
356
356
  owner: string;
357
357
  credentialSchema?: string;
@@ -360,7 +360,7 @@ export interface ProviderCatalog {
360
360
  /**
361
361
  * catalog → 派生查表(展开 providers[vendor][impl].services 为
362
362
  * `${provider}\u0000${service}` → implementation 清单)。
363
- * 调用方在工厂构造期构建一次(SDK registry / CLI doctor 谓词 / F5 页面 state),求值期 O(1) 查表。
363
+ * 调用方在工厂构造期构建一次(SDK registry / CLI doctor 谓词 / 页面 state),求值期 O(1) 查表。
364
364
  */
365
365
  export declare function buildSupplyLookup(catalog: ProviderCatalog): SupplyLookup;
366
366
  /**
package/dist/runtime.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 契约包协议常量 + 协议纯函数(004 D5:契约包允许协议常量级运行时值)。
2
+ * 契约包协议常量 + 协议纯函数(契约包允许协议常量级运行时值)。
3
3
  * .d.ts 为主(tsc emitDeclarationOnly);本文件为唯一运行时 JS(经 tsup/esbuild 出 dist/runtime.js)。
4
4
  * 修订 001 §2.6"契约包 types-only"表述:types-only 为主,允许协议常量级运行时值。
5
5
  */
package/dist/session.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 平台能力凭证 DTO(006 D10 命名消歧:tboxSessionId,区别于已移除的 auth session)。
2
+ * 平台能力凭证 DTO(006 命名消歧:tboxSessionId,区别于已移除的 auth session)。
3
3
  * TIER0 types-only;server 签发(GET /api/tbox/session),client 消费并缓存。
4
4
  */
5
5
  export interface TboxSessionData {
package/dist/skill.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * skill 前端表达协议(009 D9/D10):reminder 文本协议工具 + tool-call 表达形状。
2
+ * skill 前端表达协议(/):reminder 文本协议工具 + tool-call 表达形状。
3
3
  * - 单一来源:server(合成事件/注入解析)与 client(历史解析/显示)共用,禁止两端各自 hardcode;
4
4
  * - 纯协议无 UI 语义:文案/渲染留装配层。
5
5
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tbox.cn/app-contracts",
3
- "version": "0.12.2",
3
+ "version": "0.12.4",
4
4
  "type": "module",
5
5
  "description": "平台契约(TIER0,types-only 为主 + 协议常量运行时值):卡片协议 / SDK adapter / 平台 DTO。",
6
6
  "exports": {