@tbox.cn/app-contracts 0.1.5 → 0.10.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 +132 -32
- package/dist/client-slot.d.ts +27 -0
- package/dist/context-slot.d.ts +23 -0
- package/dist/domain-assembly.d.ts +22 -0
- package/dist/host-effect.d.ts +66 -0
- package/dist/identity.d.ts +15 -4
- package/dist/index.d.ts +8 -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/protocol.d.ts +62 -7
- package/dist/providers.d.ts +290 -4
- package/dist/runtime.d.ts +12 -3
- package/dist/runtime.js +365 -12
- 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/protocol.d.ts
CHANGED
|
@@ -10,10 +10,24 @@ type RunScopedErrorEvent = RunErrorEvent & {
|
|
|
10
10
|
threadId?: string;
|
|
11
11
|
runId?: string;
|
|
12
12
|
};
|
|
13
|
+
/**
|
|
14
|
+
* 工具执行失败终态(2026-09-03 tool-error 断链修复):
|
|
15
|
+
* - isError: true 标记该 RESULT 为错误终态(模型路径工具 execute 抛错 / 模块工具
|
|
16
|
+
* undefined 返回经 wrapper 显式 throw——两路同通道);缺省/undefined = 正常结果;
|
|
17
|
+
* - errorMessage: 面向用户的错误文案(不含 stack;200 字符内截断由发射端保证);
|
|
18
|
+
* - preTool 通道不携带本扩展(错误语义经 content 内 JSON envelope 派生,R''8 不变);
|
|
19
|
+
* - 向后兼容:旧 client 忽略未知字段(事件通道零 schema 校验,JSON.parse 直通)。
|
|
20
|
+
*/
|
|
21
|
+
type ToolCallResultErrorEvent = ToolCallResultEvent & {
|
|
22
|
+
isError?: true;
|
|
23
|
+
errorMessage?: string;
|
|
24
|
+
};
|
|
13
25
|
/** 所有服务端 → 客户端事件 */
|
|
14
|
-
export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent |
|
|
26
|
+
export type ServerEvent = RunStartedEvent | RunFinishedEvent | RunScopedErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultErrorEvent | ReasoningStartEvent | ReasoningMessageStartEvent | ReasoningMessageContentEvent | ReasoningMessageEndEvent | ReasoningEndEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent
|
|
15
27
|
/** HELLO 鉴权成功应答(011 F4) */
|
|
16
|
-
| HelloAckEvent
|
|
28
|
+
| HelloAckEvent
|
|
29
|
+
/** 传输层业务保活(双向对称;连接级事件,无身份/顺序语义) */
|
|
30
|
+
| PingEvent | PongEvent;
|
|
17
31
|
export interface SendMessageMediaItem {
|
|
18
32
|
fileId: string;
|
|
19
33
|
type: 'image' | 'video' | 'audio' | 'file';
|
|
@@ -62,7 +76,7 @@ export interface HelloEvent {
|
|
|
62
76
|
/**
|
|
63
77
|
* HELLO 鉴权成功后的应答(011 F4):
|
|
64
78
|
* - mallScope 回显服务端确认的会话 scope(TIER0 槽位,领域语义由 TIER1 解析器赋予);
|
|
65
|
-
* - chatConfig
|
|
79
|
+
* - chatConfig 由服务端下发(快捷指令 + settings 会话 UI 设置单一真源,本地文件仅 fallback)。
|
|
66
80
|
*/
|
|
67
81
|
export interface HelloAckEvent {
|
|
68
82
|
type: 'HELLO_ACK';
|
|
@@ -70,17 +84,38 @@ export interface HelloAckEvent {
|
|
|
70
84
|
mallScope?: Record<string, string>;
|
|
71
85
|
/** 会话配置(快捷指令等) */
|
|
72
86
|
chatConfig: HelloAckChatConfig;
|
|
87
|
+
/**
|
|
88
|
+
* 018 tool-debug:工具调试视图旗标(TBOX_TOOL_DEBUG env 单源解析,服务端信任锚点)。
|
|
89
|
+
* 仅开启时出现(条件发射——关闭态与现状字节级一致);旧 client 忽略未知字段。
|
|
90
|
+
*/
|
|
91
|
+
toolDebug?: true;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* 会话 UI 设置(服务端运行时下发单一真源;全 optional 条件在场,缺席键 → client 回落构建期快照)。
|
|
95
|
+
* 键名与 config/chat.json 字段 1:1(零翻译映射)。
|
|
96
|
+
* 演进规则:新键先落两处(本接口 + SDK toWsChatConfig pick 清单),client 需消费时才落第三处
|
|
97
|
+
* (模板静态 store + 水合)——server 白名单 ⊆ client 认知,白名单单点在 server pick。
|
|
98
|
+
* settings 由新 server 恒发——optional 只服务旧 server 兼容,勿加条件发射逻辑。
|
|
99
|
+
*/
|
|
100
|
+
export interface ChatUiSettings {
|
|
101
|
+
enableImageUpload?: boolean;
|
|
102
|
+
enableVideoUpload?: boolean;
|
|
103
|
+
enableTTS?: boolean;
|
|
104
|
+
enableVoiceInput?: boolean;
|
|
105
|
+
defaultInputMode?: 'TEXT' | 'VOICE';
|
|
73
106
|
}
|
|
74
107
|
export interface HelloAckChatConfig {
|
|
75
108
|
quickCommands: {
|
|
76
109
|
label: string;
|
|
77
110
|
prompt: string;
|
|
78
111
|
}[];
|
|
79
|
-
|
|
112
|
+
/** 会话 UI 设置(chat.json 运行时读取下发) */
|
|
113
|
+
settings?: ChatUiSettings;
|
|
80
114
|
}
|
|
81
115
|
/**
|
|
82
116
|
* 卡片反向通道动作。
|
|
83
|
-
* - sendMessage value 作为用户消息走 chat 流程;visible=false
|
|
117
|
+
* - sendMessage value 作为用户消息走 chat 流程;visible=false 时不显示在聊天历史;
|
|
118
|
+
* displayText 有值时气泡显示此文本(value 仍透传给 AI,用于隐藏上下文如 merchantId)
|
|
84
119
|
* - submitForm formData 由 client React 卡片通过 sendUiAction 收集,作为虚拟 tool result 注入 Agent 上下文
|
|
85
120
|
* - openLink 客户端本地处理,不应发到服务端
|
|
86
121
|
* - toast 客户端本地轻提示,不应发到服务端
|
|
@@ -90,6 +125,7 @@ export type UiClientAction = {
|
|
|
90
125
|
type: 'sendMessage';
|
|
91
126
|
value: string;
|
|
92
127
|
visible?: boolean;
|
|
128
|
+
displayText?: string;
|
|
93
129
|
} | {
|
|
94
130
|
type: 'submitForm';
|
|
95
131
|
formId: string;
|
|
@@ -105,7 +141,7 @@ export type UiClientAction = {
|
|
|
105
141
|
}
|
|
106
142
|
/** 写+确定性动作(011 E1):actionId + 一次性授权 token,经 ActionGrant 校验后执行 */
|
|
107
143
|
| {
|
|
108
|
-
type: '
|
|
144
|
+
type: 'moduleAction';
|
|
109
145
|
actionId: string;
|
|
110
146
|
contextToken: string;
|
|
111
147
|
};
|
|
@@ -119,4 +155,23 @@ export interface UiActionEvent {
|
|
|
119
155
|
/** submitForm 时携带的表单数据(由 client React 卡片构造) */
|
|
120
156
|
formData?: Record<string, unknown>;
|
|
121
157
|
}
|
|
122
|
-
export type ClientEvent = SendMessageEvent | CancelRunEvent | UiActionEvent | HelloEvent;
|
|
158
|
+
export type ClientEvent = SendMessageEvent | CancelRunEvent | UiActionEvent | HelloEvent | PingEvent | PongEvent;
|
|
159
|
+
/** 保活漏检上限:timeout = intervalMs × KEEPALIVE_MISS_LIMIT(对齐 nextAuthFailState 的 max=3 惯例) */
|
|
160
|
+
export declare const KEEPALIVE_MISS_LIMIT = 3;
|
|
161
|
+
export type KeepaliveAction = 'none' | 'ping' | 'dead';
|
|
162
|
+
/**
|
|
163
|
+
* 保活判定核(协议语义组成部分,双端共用单源实现):
|
|
164
|
+
* idle ≥ 3×interval → dead;idle ≥ interval → ping;否则 none。
|
|
165
|
+
* 全部基于同钟 delta(Date.now 差值),无时钟跳变敏感性;ts 字段仅诊断回显。
|
|
166
|
+
*/
|
|
167
|
+
export declare function nextKeepaliveAction(idleMs: number, intervalMs: number): KeepaliveAction;
|
|
168
|
+
/** 保活探测(client↔server 双向):收到即回 PONG 并原样回显 ts */
|
|
169
|
+
export interface PingEvent {
|
|
170
|
+
type: 'PING';
|
|
171
|
+
ts?: number;
|
|
172
|
+
}
|
|
173
|
+
/** 保活应答:双端传输层拦截,不进入业务事件处理 */
|
|
174
|
+
export interface PongEvent {
|
|
175
|
+
type: 'PONG';
|
|
176
|
+
ts?: number;
|
|
177
|
+
}
|
package/dist/providers.d.ts
CHANGED
|
@@ -2,11 +2,16 @@
|
|
|
2
2
|
* Provider 抽象契约(011,TIER0 纯通用——零领域语义):
|
|
3
3
|
* 外部服务 Provider 的实例/模版/凭证/传输层类型定义,双端可消费(types-only)。
|
|
4
4
|
*
|
|
5
|
-
* 设计要点(011 G1-G7
|
|
5
|
+
* 设计要点(011 G1-G7;integrations v4 现状):
|
|
6
6
|
* - scope 是通用路由键(Record<string,string>),领域语义由 TIER1 赋予(mall 场景 = { miniAppId, mallId });
|
|
7
|
-
* - transport 缓存责任在 SDK(
|
|
7
|
+
* - transport 缓存责任在 SDK(integrations v2 键 = service + instanceId + provider + implementation;
|
|
8
|
+
* 换绑后旧 transport 留存复用,配置无热轮换——重载即重启进程);
|
|
8
9
|
* - connector 缓存责任在模块(key = templateId + mallId);
|
|
9
|
-
* - credentialRef 指向 EnvironmentSecretProvider('secret
|
|
10
|
+
* - credentialRef 指向 EnvironmentSecretProvider(v2 形态 'secret://<stem>'——档内凭据文件名
|
|
11
|
+
* stem 直引,env UPPER_SNAKE 派生兜底),生产缺引用即 fail-fast;
|
|
12
|
+
* - 绑定继承(v3 起,v4 延续):绑定组(provider + implementation)从最特异层整组取
|
|
13
|
+
* (inst > slot > domain > root),组内 implementation 缺席经 SupplyLookup 从 catalog 派生
|
|
14
|
+
* (唯一命中;零命中/歧义/未注入查表 → binding-unresolved)。
|
|
10
15
|
*/
|
|
11
16
|
/** Provider 实例(部署配置三段之一:providerInstances 元素) */
|
|
12
17
|
export interface ProviderInstance {
|
|
@@ -52,6 +57,8 @@ export interface AuthenticatedTransport {
|
|
|
52
57
|
request(opts: {
|
|
53
58
|
/** API 路径(相对 baseUrl;baseUrl 由 transport 内部持有) */
|
|
54
59
|
path: string;
|
|
60
|
+
/** HTTP 方法(缺省 POST;GET 无 body,业务参数经 query 携带) */
|
|
61
|
+
method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
|
|
55
62
|
query?: Record<string, string>;
|
|
56
63
|
body?: unknown;
|
|
57
64
|
timeoutMs?: number;
|
|
@@ -72,7 +79,7 @@ export declare function stableSerializeScope(scope?: Record<string, string>): st
|
|
|
72
79
|
export declare const PROVIDER_ERROR_CODES: {
|
|
73
80
|
/** 实例被禁用(enabled=false) */
|
|
74
81
|
readonly INSTANCE_DISABLED: "PROVIDER_INSTANCE_DISABLED";
|
|
75
|
-
/** 无匹配实例(templateId + scope
|
|
82
|
+
/** 无匹配实例(templateId + scope / service 槽无 instanceId 实例) */
|
|
76
83
|
readonly INSTANCE_NOT_FOUND: "PROVIDER_INSTANCE_NOT_FOUND";
|
|
77
84
|
/** 凭证引用缺失(生产 fail-fast) */
|
|
78
85
|
readonly CREDENTIAL_REF_MISSING: "PROVIDER_CREDENTIAL_REF_MISSING";
|
|
@@ -84,5 +91,284 @@ export declare const PROVIDER_ERROR_CODES: {
|
|
|
84
91
|
readonly RESPONSE_TOO_LARGE: "PROVIDER_RESPONSE_TOO_LARGE";
|
|
85
92
|
/** 传输失败归类(429/5xx/NETWORK/TIMEOUT) */
|
|
86
93
|
readonly TRANSPORT_FAILURE: "PROVIDER_TRANSPORT_FAILURE";
|
|
94
|
+
/** 服务槽未配置(integrations.services 无该 service) */
|
|
95
|
+
readonly SERVICE_NOT_CONFIGURED: "PROVIDER_SERVICE_NOT_CONFIGURED";
|
|
96
|
+
/** provider 标识未命中 catalog(解引用失败) */
|
|
97
|
+
readonly PROVIDER_NOT_FOUND: "PROVIDER_NOT_FOUND";
|
|
98
|
+
/** 内联声明未实施态(无 adapter 实现注册) */
|
|
99
|
+
readonly PROVIDER_NOT_IMPLEMENTED: "PROVIDER_NOT_IMPLEMENTED";
|
|
100
|
+
/** 绑定未解析(绑定组无任何层 provider 声明,或 implementation 派生零命中/歧义/未注入查表——v3 起) */
|
|
101
|
+
readonly BINDING_UNRESOLVED: "PROVIDER_BINDING_UNRESOLVED";
|
|
87
102
|
};
|
|
88
103
|
export type ProviderErrorCode = (typeof PROVIDER_ERROR_CODES)[keyof typeof PROVIDER_ERROR_CODES];
|
|
104
|
+
/**
|
|
105
|
+
* 预期缺席判定(017 槽位原子化:模块 ports 兜底矩阵的唯一谓词):
|
|
106
|
+
* 三码 = 「配置即声明下该槽确实没有可用供给」的运行期投影(槽未配置/实例缺失/实例禁用)。
|
|
107
|
+
* true → 调用方落本地兜底(InMemory/本地空数据);false(含 NOT_IMPLEMENTED 等其余码)→ 上抛。
|
|
108
|
+
*/
|
|
109
|
+
export declare function isExpectedProviderAbsence(e: unknown): boolean;
|
|
110
|
+
/**
|
|
111
|
+
* 内联厂商声明(仅槽级 provider 字段可用;实例级 provider 恒字符串)。
|
|
112
|
+
* integrations.json 内直接声明供给,不经 provider 包 manifest。
|
|
113
|
+
* 未实施态语义:catalog/adapter 均无对应实现 → doctor warning + resolve 抛 PROVIDER_NOT_IMPLEMENTED
|
|
114
|
+
* (F5 交互化的「先声明后实施」闭环)。
|
|
115
|
+
*/
|
|
116
|
+
export interface InlineVendorDeclaration {
|
|
117
|
+
/** 厂商名(= 档位名 = provider 包轴,如 'wanda') */
|
|
118
|
+
provider: string;
|
|
119
|
+
/** 认证类型('-' 表示无凭据) */
|
|
120
|
+
credentialType: string;
|
|
121
|
+
/** config schema 引用(可选;相对应用 config/;受控子集校验归 doctor 谓词) */
|
|
122
|
+
configSchema?: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* 槽实例(instances 键 = instanceId,mall 场景 = mallId;per-instance 唯一写位)。
|
|
126
|
+
* 激活不变式(v4):service 在 scope k 生效 ⟺ instances[k] 在场(或 instances['*'] 通配在场,
|
|
127
|
+
* **或 instances 键整体缺席 = 通配激活**——对任意 instanceId 含 '' 命中);任意生效点的
|
|
128
|
+
* per-instance 凭据均可写 instances[k].credentialRef(root ByInstance 是唯一例外层)。
|
|
129
|
+
* 通配边界:仅 instances 查找层生效——configByInstance/credentialRefByInstance 保持精确键语义。
|
|
130
|
+
*/
|
|
131
|
+
export interface ServiceInstanceConfig {
|
|
132
|
+
/** 实例级厂商覆盖(绑定组头;恒字符串。impl-only 非法——implementation 需伴随 provider) */
|
|
133
|
+
provider?: string;
|
|
134
|
+
/** 实例级实现覆盖('id@version';缺席 = 绑定组内派生(SupplyLookup 唯一命中)) */
|
|
135
|
+
implementation?: string;
|
|
136
|
+
/** 连接参数(非机密项;configSchema 校验) */
|
|
137
|
+
config?: Record<string, unknown>;
|
|
138
|
+
/** 机密引用:'secret://{ref}'(local provider 免) */
|
|
139
|
+
credentialRef?: string;
|
|
140
|
+
/** 缺省 true;false → resolve → INSTANCE_DISABLED */
|
|
141
|
+
enabled?: boolean;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* 槽级配置(v3:provider/implementation 可选——双双缺席回落 domain/root 继承;
|
|
145
|
+
* 显式在场 = 显式即真值(不派生——存量全显式文件零影响)。impl-only 非法:
|
|
146
|
+
* implementation 需伴随 provider(provider 是绑定组头)。内联声明仍仅槽级且必带
|
|
147
|
+
* implementation(内联无派生源)。
|
|
148
|
+
* config/credentialRef = 服务级 scope-free 默认。
|
|
149
|
+
*/
|
|
150
|
+
export interface ConfiguredService {
|
|
151
|
+
/** 绑定组头(字符串厂商 = 派生位;内联声明 = 显式供给,必带 implementation) */
|
|
152
|
+
provider?: string | InlineVendorDeclaration;
|
|
153
|
+
/** 绑定组尾('id@version';缺席 = 派生(SupplyLookup 唯一命中)) */
|
|
154
|
+
implementation?: string;
|
|
155
|
+
config?: Record<string, unknown>;
|
|
156
|
+
credentialRef?: string;
|
|
157
|
+
/** 实例激活表(v4 可选:键缺席 = 通配激活 ≡ {"*":{}};显式空集 = 显式零激活) */
|
|
158
|
+
instances?: Record<string, ServiceInstanceConfig>;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* 模块域全局配置(键 = 槽位域前缀,moduleDomainOf 派生;域 ≠ 模块名——auth 域由登录链消费)。
|
|
162
|
+
* 域 ≠ 部署边界:单应用单厂商部署门禁不因 domains 表达力放开(混绑 die 原样)。
|
|
163
|
+
*/
|
|
164
|
+
export interface DomainConfig {
|
|
165
|
+
/** 域级默认厂商(implementation 恒派生——域层无精确绑定语义) */
|
|
166
|
+
provider?: string;
|
|
167
|
+
/** 域级共享配置(该域全部槽合并进 config 级联,与绑定来源层无关) */
|
|
168
|
+
config?: Record<string, unknown>;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* 部署实例(业务主体拓扑条目;root instances 注册表元素——v4 参考表)。
|
|
172
|
+
* 域属性经 attributes 由 TIER1 赋义(mall 场景:miniAppId/contactPhone/location)——
|
|
173
|
+
* TIER0 全程 opaque;本表纯元数据(展示/默认解析),永不充当解析闸门
|
|
174
|
+
* (闸门唯一表达位 = 槽 instances 激活表形态,见 ServiceInstanceConfig)。
|
|
175
|
+
*/
|
|
176
|
+
export interface DeploymentInstance {
|
|
177
|
+
/** 实例 id = instanceId 注册来源(槽激活表/ByInstance 键引用它);禁 '*'(通配保留字) */
|
|
178
|
+
id: string;
|
|
179
|
+
/** 展示名(品牌区回显等域消费) */
|
|
180
|
+
name: string;
|
|
181
|
+
/** 域属性袋(TIER0 opaque;TIER1 投影 zod 赋义) */
|
|
182
|
+
attributes?: Record<string, unknown>;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* provider 实例声明快照(SDK declareProviderInstances 产物 / 域装配惰性融合消费形态):
|
|
186
|
+
* 键 = provider 厂商名;值 = 该 provider 的隐式部署实例(register 期声明;COW——
|
|
187
|
+
* 快照为拷贝并冻结,快照引用变更即「声明发生变化」信号,下游据此失效投影缓存)。
|
|
188
|
+
*/
|
|
189
|
+
export type ProviderInstanceDeclarations = Readonly<Record<string, readonly DeploymentInstance[]>>;
|
|
190
|
+
/** normalizeInstances 产物(模板装配 / CLI doctor / 根脚本共用消费形态) */
|
|
191
|
+
export interface NormalizedInstances {
|
|
192
|
+
instances: readonly DeploymentInstance[];
|
|
193
|
+
/** 显式 ?? 单候选唯一解;null = 无默认(多实例无显式默认 = 合法,doctor warning) */
|
|
194
|
+
defaultInstanceId: string | null;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* integrations.json 根形状(loadIntegrations 产物 zod 目标)。
|
|
198
|
+
* 全链唯一 ByInstance 层 = root 四字段(configByInstance/credentialRefByInstance);约束域 = provider
|
|
199
|
+
* 解析链(services/domains/instances);modules 资源轴正交不受此限。
|
|
200
|
+
* service/instance 层级内 per-instance 语义由 instances 键承载。
|
|
201
|
+
* v3 绑定继承:绑定组从最特异层整组取(inst > slot > domains[d] > root)。
|
|
202
|
+
* v4 部署实例注册表:instances = 参考表(纯元数据);defaultInstanceId = 默认实例
|
|
203
|
+
* (无 scope 参数访问兜底;单实例免填——唯一解;无参考表时独立在场 = env 注入动态默认形态)。
|
|
204
|
+
*/
|
|
205
|
+
export interface IntegrationsConfig {
|
|
206
|
+
/** 应用全局默认厂商(root 继承层;implementation 恒派生) */
|
|
207
|
+
provider?: string;
|
|
208
|
+
/** 部署级 scope-free 默认配置 */
|
|
209
|
+
config?: Record<string, unknown>;
|
|
210
|
+
/** 部署级 per-instance 默认配置(键 = instanceId) */
|
|
211
|
+
configByInstance?: Record<string, Record<string, unknown>>;
|
|
212
|
+
/** 部署级 scope-free 默认凭据(文件必须 scope:{}) */
|
|
213
|
+
credentialRef?: string;
|
|
214
|
+
/** 部署级 per-instance 默认凭据表(键 = instanceId;商户级凭据主写位) */
|
|
215
|
+
credentialRefByInstance?: Record<string, string>;
|
|
216
|
+
/** 模块域全局层(键 = moduleDomainOf(service);无 ByInstance——全链唯一 ByInstance 层恒 root) */
|
|
217
|
+
domains?: Record<string, DomainConfig>;
|
|
218
|
+
/** 部署实例注册表(参考表);缺席 = 无参考表;空数组非法(zod 拒——无表 = 键缺席唯一写法) */
|
|
219
|
+
instances?: DeploymentInstance[];
|
|
220
|
+
/** 默认实例 id(单实例免填;∈instances ids;无表时独立在场 = 动态默认形态) */
|
|
221
|
+
defaultInstanceId?: string | null;
|
|
222
|
+
/** 模块资源绑定(v5 新轴——与 domains 正交:domains = provider 绑定默认,modules = 资源绑定;
|
|
223
|
+
* 键 = install id(.tbox/app.json entry.id / packages/ 目录名;仓内家族包恒等 manifest name 属规约);
|
|
224
|
+
* 无 per-instance 层(扩展位词汇预选 resourcesByInstance——instances 词恒属 services 激活语义) */
|
|
225
|
+
modules?: Record<string, ModuleConfig>;
|
|
226
|
+
services: Record<string, ConfiguredService>;
|
|
227
|
+
}
|
|
228
|
+
/** 级联求值产物(ok 态) */
|
|
229
|
+
export interface EffectiveService {
|
|
230
|
+
provider: string | InlineVendorDeclaration;
|
|
231
|
+
implementation: string;
|
|
232
|
+
/** 五层浅合并一层:root.config → root.configByInstance[k] → domain.config → slot.config → inst.config */
|
|
233
|
+
config: Readonly<Record<string, unknown>>;
|
|
234
|
+
credentialRef?: string;
|
|
235
|
+
}
|
|
236
|
+
export type EffectiveServiceResolution = {
|
|
237
|
+
status: 'ok';
|
|
238
|
+
effective: EffectiveService;
|
|
239
|
+
} | {
|
|
240
|
+
status: 'service-not-configured';
|
|
241
|
+
} | {
|
|
242
|
+
status: 'instance-not-found';
|
|
243
|
+
} | {
|
|
244
|
+
status: 'instance-disabled';
|
|
245
|
+
} | {
|
|
246
|
+
status: 'binding-unresolved';
|
|
247
|
+
message: string;
|
|
248
|
+
};
|
|
249
|
+
/**
|
|
250
|
+
* 通配 scope 键(instances 查找层兜底):显式键优先;显式禁用实例胜通配。
|
|
251
|
+
* 仅 instances 查找层生效——configByInstance/credentialRefByInstance 保持精确键语义。
|
|
252
|
+
* ('*' 字面量与 doctor 谓词文件内联一致;语义由双侧包测试交叉锁死。)
|
|
253
|
+
*/
|
|
254
|
+
export declare const WILDCARD_INSTANCE_KEY = "*";
|
|
255
|
+
/** 槽位域前缀(domains 键控轴):首个点号前段;无点号取整串。域 ≠ 模块名(auth 域由登录链消费)。 */
|
|
256
|
+
export declare function moduleDomainOf(service: string): string;
|
|
257
|
+
/** 派生查表(buildSupplyLookup 产物):键 `${provider}\u0000${service}` → implementation 清单('id@version')。 */
|
|
258
|
+
export type SupplyLookup = Record<string, readonly string[]>;
|
|
259
|
+
/**
|
|
260
|
+
* 级联细则(一句话:层序优先于 scope 特异度;层内 per-instance 胜标量):
|
|
261
|
+
* - 绑定组(provider + implementation):最特异层整组取(inst > slot > domain > root)——
|
|
262
|
+
* 独立 `??` 继承会产生跨层非法组合(inst.provider=wanda + 继承 slot 的 joycity impl),
|
|
263
|
+
* 故组不可拆;组内 implementation 缺席 → supplies 派生(唯一命中;
|
|
264
|
+
* 零命中/歧义/未注入查表 → binding-unresolved);双字段显式在场 = 显式即真值(不派生,
|
|
265
|
+
* 存量全显式文件零影响)。内联声明仅槽级且必带 implementation(防御分支兜底)。
|
|
266
|
+
* - config 五层浅合并:root.config → root.configByInstance[k] → domain.config → slot.config →
|
|
267
|
+
* inst.config(service 标量胜 root ByInstance[k]——层序优先于 scope 特异度;
|
|
268
|
+
* domain.config 恒参与该域全部槽,与绑定来源层无关)
|
|
269
|
+
* - credentialRef:inst ?? slot ?? root.credentialRefByInstance[k] ?? root.credentialRef(v3 零改动;
|
|
270
|
+
* domain 层无 credentialRef——链位预留 slot 后、root ByInstance 前)
|
|
271
|
+
* 不抛领域错误;status 由 SDK registry 映射 PROVIDER_* 错误码
|
|
272
|
+
* (binding-unresolved → PROVIDER_BINDING_UNRESOLVED;hasProviderBinding 点查 status !== 'ok' → false)。
|
|
273
|
+
*/
|
|
274
|
+
export declare function resolveEffectiveService(integrations: IntegrationsConfig, service: string, instanceId: string, supplies?: SupplyLookup): EffectiveServiceResolution;
|
|
275
|
+
/**
|
|
276
|
+
* root 部署实例注册表归一化(v4 wire → 消费形态单源):
|
|
277
|
+
* - instances 缺席 = 空表(无参考表——wanda 动态形态;空数组已在 zod 拒,此处纯防御);
|
|
278
|
+
* - defaultInstanceId 解析:undefined(未填)→ 单候选唯一解(instances 恰一项);
|
|
279
|
+
* 显式 null = 显式无默认(不派生——「显式即真值」原则同 v3 绑定组);无默认 → null。
|
|
280
|
+
* 调用方:TIER1 控制平面投影(mallControlPlaneOf)、CLI doctor(多实例无默认 warning)、
|
|
281
|
+
* 根脚本(real-env-plan 默认实例探测)——禁止各自重写解析逻辑。
|
|
282
|
+
*/
|
|
283
|
+
export declare function normalizeInstances(config: Pick<IntegrationsConfig, 'instances' | 'defaultInstanceId'>): NormalizedInstances;
|
|
284
|
+
/**
|
|
285
|
+
* provider manifest 单槽供给声明(tbox.module.json contributes.providers.slots 元素)。
|
|
286
|
+
* provider = 厂商名(= 档位名 = provider 包轴);implementation = 'id@version' 形态。
|
|
287
|
+
*/
|
|
288
|
+
export interface ProviderManifestSlot {
|
|
289
|
+
/** 供给的 service 槽('parking.query' 形态;点分域——017 起粒度 = Port,词汇真源 service-slots.json) */
|
|
290
|
+
service: string;
|
|
291
|
+
/** 厂商名('wanda' / 'joycity' / 'mock';catalog 嵌套第一轴键) */
|
|
292
|
+
provider: string;
|
|
293
|
+
/** 实现标识('membership-read@1';catalog 嵌套第二轴键) */
|
|
294
|
+
implementation: string;
|
|
295
|
+
/** 认证类型('-' = 无凭据;authStrategies 注册点匹配键) */
|
|
296
|
+
credentialType: string;
|
|
297
|
+
/** local 供给(免 transport/凭据/credentialRef——mock 形态短路) */
|
|
298
|
+
local?: boolean;
|
|
299
|
+
/** config schema 文件引用(相对包根) */
|
|
300
|
+
configSchema?: string;
|
|
301
|
+
/** credential schema 文件引用(相对包根) */
|
|
302
|
+
credentialSchema?: string;
|
|
303
|
+
}
|
|
304
|
+
/** catalog provider 聚合条目(providers[vendor][implementation] 两跳可达;自描述双字段) */
|
|
305
|
+
export interface CatalogProviderEntry {
|
|
306
|
+
/** 厂商名(嵌套第一轴;与条目键一致便于透传) */
|
|
307
|
+
provider: string;
|
|
308
|
+
/** 实现标识(嵌套第二轴;'id@version') */
|
|
309
|
+
implementation: string;
|
|
310
|
+
/** 认证类型(authStrategies 匹配键;'-' 无凭据) */
|
|
311
|
+
credentialType: string;
|
|
312
|
+
/** 宿主 npm 包名(诊断归属;多槽同包同 owner) */
|
|
313
|
+
owner: string;
|
|
314
|
+
/** local 供给(mock 形态) */
|
|
315
|
+
local?: boolean;
|
|
316
|
+
/** config schema 引用 */
|
|
317
|
+
configSchema?: string;
|
|
318
|
+
/** credential schema 引用 */
|
|
319
|
+
credentialSchema?: string;
|
|
320
|
+
/** 供给槽清单(service id) */
|
|
321
|
+
services: string[];
|
|
322
|
+
}
|
|
323
|
+
/** catalog 需求侧聚合条目(模块 manifest contributes.services 元素聚合;services 键 = service id) */
|
|
324
|
+
export interface CatalogServiceEntry {
|
|
325
|
+
/** 可选槽(未配置不 error——doctor warning 级) */
|
|
326
|
+
optional: boolean;
|
|
327
|
+
/** manifest defaults(F5 页面预填缺省供给) */
|
|
328
|
+
defaults: Array<{
|
|
329
|
+
provider: string;
|
|
330
|
+
implementation: string;
|
|
331
|
+
}>;
|
|
332
|
+
/** 声明方模块(moduleId 清单) */
|
|
333
|
+
owners: string[];
|
|
334
|
+
}
|
|
335
|
+
/** loadProviderCatalog 产物:全应用 provider 供给与需求聚合(.tbox/app.json npmModules 真源) */
|
|
336
|
+
export interface ProviderCatalog {
|
|
337
|
+
/** 嵌套形态:厂商级语义一跳、F5 厂商→实现级联枚举天然序;migrate 反查表 = 本表自身 */
|
|
338
|
+
providers: Record<string, Record<string, CatalogProviderEntry>>;
|
|
339
|
+
services: Record<string, CatalogServiceEntry>;
|
|
340
|
+
/** credentialType 直达索引(F5/doctor 单跳;同名共享单例先例) */
|
|
341
|
+
credentialTypes: Record<string, {
|
|
342
|
+
owner: string;
|
|
343
|
+
credentialSchema?: string;
|
|
344
|
+
}>;
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* catalog → 派生查表(展开 providers[vendor][impl].services 为
|
|
348
|
+
* `${provider}\u0000${service}` → implementation 清单)。
|
|
349
|
+
* 调用方在工厂构造期构建一次(SDK registry / CLI doctor 谓词 / F5 页面 state),求值期 O(1) 查表。
|
|
350
|
+
*/
|
|
351
|
+
export declare function buildSupplyLookup(catalog: ProviderCatalog): SupplyLookup;
|
|
352
|
+
/**
|
|
353
|
+
* 资源类型词汇表(封闭 union;新类型 = 加 union 分支,编译期破坏显性化)。
|
|
354
|
+
* 命名规则:与既有配置面词汇同源('knowledge' ← config/knowledge.json knowledge_bases)。
|
|
355
|
+
*/
|
|
356
|
+
export declare const RESOURCE_TYPE_IDS: readonly ["knowledge"];
|
|
357
|
+
export type ResourceTypeId = (typeof RESOURCE_TYPE_IDS)[number];
|
|
358
|
+
/** knowledge 资源声明(wire 形态;datasetId/ref 至少其一,并存时 datasetId 优先——resolver 层裁决) */
|
|
359
|
+
export interface KnowledgeResourceSpec {
|
|
360
|
+
type: 'knowledge';
|
|
361
|
+
/** datasetId 直填(免台账) */
|
|
362
|
+
datasetId?: string;
|
|
363
|
+
/** knowledge.json 台账条目名(展开锚 = integrations.json 所在目录——与数据同源旅行) */
|
|
364
|
+
ref?: string;
|
|
365
|
+
topK?: number;
|
|
366
|
+
scoreThreshold?: number;
|
|
367
|
+
}
|
|
368
|
+
/** 资源声明(discriminated by type;SDK zod / CLI doctor / 未来 app-toolkit 共用 wire 形状) */
|
|
369
|
+
export type ResourceSpec = KnowledgeResourceSpec;
|
|
370
|
+
/** 模块资源配置(modules 节元素;strict 单字段——provider/config/instances 进 modules 即非法,防与 domains 双写位) */
|
|
371
|
+
export interface ModuleConfig {
|
|
372
|
+
/** resourceId → 类型化资源声明(resourceId 词汇真源 = 模块 manifest contributes.resources) */
|
|
373
|
+
resources: Record<string, ResourceSpec>;
|
|
374
|
+
}
|
package/dist/runtime.d.ts
CHANGED
|
@@ -1,11 +1,20 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 契约包协议常量 + 协议纯函数(004 D5
|
|
2
|
+
* 契约包协议常量 + 协议纯函数(004 D5:契约包允许协议常量级运行时值)。
|
|
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,
|
|
7
|
+
export { TBOX_CARD_EVENT_NAME, TBOX_CARD_UPDATE_EVENT_NAME, TBOX_NOTICE_EVENT_NAME, } from './cards';
|
|
8
8
|
export { AUTH_ERROR_CODES, authCodeToStatus } from './identity';
|
|
9
|
-
export { stableSerializeScope, PROVIDER_ERROR_CODES } from './providers';
|
|
9
|
+
export { stableSerializeScope, PROVIDER_ERROR_CODES, resolveEffectiveService, WILDCARD_INSTANCE_KEY, moduleDomainOf, buildSupplyLookup, normalizeInstances, isExpectedProviderAbsence, RESOURCE_TYPE_IDS, } from './providers';
|
|
10
|
+
export { parseIntegrationsConfig } from './integrations-config';
|
|
11
|
+
export { assertNoInlineSecrets } from './no-inline-secrets';
|
|
12
|
+
export { defineContextSlot } from './context-slot';
|
|
10
13
|
export * from './skill';
|
|
11
14
|
export * from './pre-tool';
|
|
15
|
+
export * from './memory';
|
|
16
|
+
export * from './memory-tool';
|
|
17
|
+
export { TBOX_EFFECT_EVENT_NAME } from './host-effect';
|
|
18
|
+
export { KEEPALIVE_MISS_LIMIT, nextKeepaliveAction } from './protocol';
|
|
19
|
+
export { KNOWN_CLIENT_SLOT_IDS } from './client-slot';
|
|
20
|
+
export { SCOPE_ASSEMBLY_KIND } from './domain-assembly';
|