@tansr/sdk 0.11.1 → 0.13.1

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.
Files changed (6) hide show
  1. package/NOTICE +18 -0
  2. package/README.md +78 -8
  3. package/contract/MANIFEST.json +66 -0
  4. package/dist/index.d.ts +3291 -1932
  5. package/dist/index.js +18805 -2409
  6. package/package.json +5 -2
package/NOTICE ADDED
@@ -0,0 +1,18 @@
1
+ NOTICE — @tansr/sdk
2
+ ===================
3
+
4
+ Generated by `pnpm release:verify-notice --write --package sdk` (tansr FX-C-29, inline-declaration rule).
5
+ Do not edit by hand: `pnpm release:verify-notice --check` regenerates this file from the esbuild metafile and fails
6
+ on any difference. Every third-party package compiled into the shipped bundle is listed below, no more and no less;
7
+ each must carry an allow-listed license. Humans review the license column; the machine keeps the table honest.
8
+
9
+ Artifacts covered: dist/index.js
10
+ Runtime dependencies resolved from the consumer's node_modules (declared, not bundled): @vscode/ripgrep, undici, zod, zod-to-json-schema
11
+ Bundled third-party packages: 0
12
+
13
+ BUNDLED THIRD-PARTY PACKAGES
14
+ ----------------------------
15
+ (none — this bundle inlines no third-party code)
16
+
17
+ LICENSE TEXTS
18
+ -------------
package/README.md CHANGED
@@ -27,7 +27,26 @@ for await (const event of session.events) {
27
27
  }
28
28
  ```
29
29
 
30
- 模型目录与能力位由平台 App 配置(控制台治理)自动下发,本地零配置。
30
+ 模型目录与授权能力由平台 App 配置下发。系统媒体工具须在 `tools.builtin` 中显式选择；仅开启平台授权不会让缺省 SDK 会话自动装入收费媒体工具。
31
+
32
+ ## 应用系统提示词（AP-SP）
33
+
34
+ 平台管理 API 的 `systemPrompt` 是应用业务角色，`systemPromptPolicy` 控制与 SDK `system` 的关系：
35
+
36
+ | 平台策略 | 未传 system | system 有内容 | system: [] |
37
+ | --- | --- | --- | --- |
38
+ | fallback（默认） | 平台 P | SDK S | 无业务段 |
39
+ | prepend（保留） | 平台 P | P → S | 平台 P |
40
+
41
+ 平台正文未配置时，仅使用 SDK 段。`systemAppend` 在业务段选定后追加宿主使用指南，不触发覆盖；工具、Skills、MCP 指南仍按已装配能力追加。不要把平台正文再复制进 SDK 参数。`session.applicationPrompt` 提供实际装配的只读 `source`／`policy`，不包含正文。
42
+
43
+ `PUT /v1/apps/{appId}/config` 写入 `{ systemPrompt, systemPromptPolicy }`，`GET /v1/apps/{appId}` 的 `config` 回读；组织管理另传 `x-tansr-org`。正文最多 16000 Unicode 码点，null／空白清空；策略不接受 null，字段缺席均保留。
44
+
45
+ P 和 S 同为模型 system 输入，拼接次序不保证冲突指令谁胜出。平台适合公共角色集中维护，SDK 适合动态或版本化场景；有矛盾应修改正文或选择 fallback。权限／裁决／额度不靠提示词强制，正文不能存密钥。
46
+
47
+ 已有令牌档会话在下一新轮前自动核验平台 P／策略，不需重建。每轮 ETag 条件请求绕过装配缓存，工具多步保持同轮快照；先应用新段再计算上下文预算。失败发 application_prompt_refresh_failed 并中止本轮，保留历史、可原会话重试；预检30秒上限且可取消。宿主 S/A、模型和工具权限仍沿原装配生命周期。BYOK／注入 client 不读平台默认，runAgent 需宿主显式调用 resolveApplicationSystem。
48
+
49
+ 完整三档 SDK、Windows Electron、serve、Android／iOS 示例见[提示词指南](https://docs.tansr.com/sdk/system-prompts/)与仓内 doc/90 §4.12。此能力仍须发布包含 AP-SP 的 API 与 SDK／serve，旧版本不识别保留策略。
31
50
 
32
51
  ## 三档 API × 三档模型来源
33
52
 
@@ -45,10 +64,12 @@ for await (const event of session.events) {
45
64
 
46
65
  ## 能力面一览
47
66
 
48
- - **三环工具一个入口**:`tools: { builtin: [...], platform: [...], custom: [...] }`
49
- ——环2 内置本地工具(read/glob/grep/shell/…)、环3 平台托管能力(imageGen 图像
50
- 生成,平台代调按张计费)、环1 `defineTool` 业务函数(注册即说明书,JSON 参数表/
51
- zod 双档);
67
+ - **系统工具与业务工具统一入口**:`tools: { builtin: [...], custom: [...] }`。
68
+ 系统工具包括文件、命令、网络及多媒体；`imageGen`、`videoGen`、`speechToText`、
69
+ `textToSpeech` 与其他系统工具一起从 `tools.builtin` 选择，执行骨架统一在内核。
70
+ SDK 媒体后端由平台提供，受应用授权、模型范围和计量约束。`defineTool` 注册业务函数，
71
+ 接受 JSON 参数表或 zod schema。旧 `tools.platform` 仅为四媒体的弃用兼容别名，
72
+ 会并入同一内置工具集合并去重，不代表另一层工具;
52
73
  - **联网搜索双位双门**:webSearch 工具本体是内置 `WebSearch`(写在 `tools.builtin`,
53
74
  旧写法 `tools.platform` 报迁移错),后端恒平台通道(按次计费归 App,SDK 恒无 BYO
54
75
  径)——装配需双位齐开(`tools.webSearch` 工具位 + `platform.webSearch` 通道位)且
@@ -67,15 +88,64 @@ for await (const event of session.events) {
67
88
  `createSession({ thinking: { budget } })` + `session.setThinking(…)`(下一轮生效),
68
89
  与呈现档正交(详见手册 §9.1);
69
90
  - **权限**:`permission: { mode?, rules?, askUser? }`——ask 裁决桥到你的 UI,缺席
70
- fail-closed 降级 deny;
91
+ fail-closed 降级 deny;令牌档缺省装配控制台任命的**裁决人**(`adjudication?: { posture?, callBudget?,
92
+ enabled?, endUser? }`,模式由 kernel 按姿态 × 资格档推导):显式 `permission.mode` 即视为自管模式——
93
+ 裁决人不装并通报 `adjudicator_skipped_by_mode`(0.12 兼容径);**例外**:显式 `adjudication: { … }`
94
+ 与 `permission.mode` 同现即 throw `invalid_options`(真矛盾,fail-fast),静默自管请传
95
+ `adjudication: { enabled: false }`;变更登记见 `CHANGELOG.md`;
71
96
  - **计量**:`cost.usage.updated` 逐请求;终端自查 `/v1/my-usage` 恒无金额字段,
72
97
  开发者对账 `/v1/app-usage/by-end-user` 含金额(恒不代理给终端)。
73
98
 
74
- 能力位(17 工具位 + 3 平台位)在平台控制台按 App 配置;位关而显式选择恒得到装配期
75
- 可读错(`capability_disabled`,含修复指引),恒不静默缺工具。
99
+ 工具与扩展授权以及平台服务授权均在控制台按 App 配置；字段分别为 `capabilities.tools`
100
+ 与 `capabilities.platform`，键集合由 `CAPABILITY_TOOL_KEYS` / `CAPABILITY_PLATFORM_KEYS`
101
+ 提供。授权合同仍为 17 工具位 + 5 平台位；后者控制平台搜索及四媒体服务的使用权，
102
+ 不是工具归属分类。位关而显式选择得到
103
+ `capability_disabled`，不静默缺工具。
104
+
105
+ ### 系统媒体工具示例 / System media tools
106
+
107
+ ```ts
108
+ const session = await createSession({
109
+ token,
110
+ baseUrl: 'https://api.example.com',
111
+ tools: { builtin: ['imageGen', 'videoGen', 'speechToText', 'textToSpeech'] },
112
+ });
113
+ ```
114
+
115
+ 先在应用配置中授权所需媒体服务与模型。示例只选择四个媒体工具；需要文件、网络等工具时，
116
+ 也应显式加入同一个 `builtin` 列表。权限确认、预算与平台计费继续适用。用户主动录音转写或朗读
117
+ 可以调用 `session.platform.transcribe()` / `.speak()`；这些是直连操作，不会伪造模型工具事件或自动写入聊天历史。
118
+
119
+ All four media tools are built-in system tools selected through `tools.builtin`. The platform supplies
120
+ their backend and enforces app permissions, model access, quotas, and billing. The retained
121
+ `capabilities.platform` fields describe service authorization, not a separate tool category.
122
+ Media tools require explicit selection; the default SDK tool set does not enable them automatically.
123
+ The deprecated `tools.platform` selection remains an equivalent alias. User-triggered transcription
124
+ and speech through `session.platform` are direct operations, separate from model tool calls.
76
125
 
77
126
  ## 文档与示例
78
127
 
128
+ ### 可等待生命周期（ARC-07，当前源码能力，待配套发布）
129
+
130
+ `idle()`、`close()`、`session.ended` 维持原有业务语义；它们不证明异步存储、生成器的 `finally` 或 MCP 传输已经完成。离开页面或退出应用时，检查新的回执：
131
+
132
+ ```ts
133
+ const result = await session.closeAsync({ timeoutMs: 30_000, flushStore: true });
134
+ if (result.status !== 'completed') {
135
+ // 保留 session；显示状态/数量即可，不把原始 cause 直接写日志或发给 renderer。
136
+ console.warn({ status: result.status, pending: result.pending, failureCount: result.failureCount });
137
+ // 稍后继续观察：await session.drain({ timeoutMs: 30_000 });
138
+ }
139
+ ```
140
+
141
+ `drain()` 不关闭会话；`closeAsync()` 先逻辑关闭再等待。超时或 `signal` 取消的是本次观察，底层清理继续，其他等待者不受影响。默认观察上限 30 秒，`0` 读取当前状态，`Infinity` 只用于宿主明确管理的真实依赖链。`flushStore` 缺省关闭；借用的 store 永不由 SDK 自动 `close()`。`retryPersistence: true` 显式重试待修复历史提交，不重放业务回调；不要在自己的 `onHistoryCommit` 内等待本会话的 `drain()`。
142
+
143
+ 会话内 `mcp: { servers }` 由 SDK 所有；传入应用级 `McpHost` 是借用。共享 host 必须等全部使用它的会话完成后，再由应用 `await host.dispose()`。`cleanupEvidence` 中 `transport-completion` 指本地传输完成层，第三方连接没有 `settleClose` 时只提供 `connector-close-promise`，不是任意操作系统子进程或 HTTP 远端退出证明。
144
+
145
+ `query()` 提前 `break` 仍发送中止，并等待真实收尾到 `cleanupTimeoutMs`（默认 30 秒）。用 `onLifecycleError(error)` 保留 `SdkLifecycleError.cleanup`，随后可继续 `error.cleanup?.drain()`；消费者自己抛错时，JavaScript 可能优先保留消费者异常，因此第二条回调通道不可省略。托管／令牌档 `query` 现可显式传 `skills`、`mcp`，能力位及所有权规则与 `createSession` 相同；注入档仍不隐式装配工具或读取技能目录。
146
+
147
+ 完整规则见 `doc/90-SDK技术手册.md` §4.13。Electron 真正使用 `closeAsync`，外层 30 秒观察超时可再次等待；Android／iOS 继续现有 serve 会话协议，手机断线不等于删除会话，真实资源收尾由 Node 宿主负责。
148
+
79
149
  - **技术手册(完整)**:仓内 `doc/90-SDK技术手册.md`——安装、三方闭环令牌接入、三档
80
150
  API、能力位、defineTool/skills/MCP、渲染管道、权限、计量、imageGen、错误码排障、
81
151
  安全须知;
package/contract/MANIFEST.json ADDED
@@ -0,0 +1,66 @@
1
+ {
2
+ "revision": 4,
3
+ "sha256": "c57ffb63c51fa37f84814857240785a1c1d433839a7d0e6ebcdedc419838597c",
4
+ "errorCodes": 38,
5
+ "eventTypes": 54,
6
+ "eventTypeNames": [
7
+ "agent.completed",
8
+ "agent.followup",
9
+ "agent.interrupted",
10
+ "agent.progress",
11
+ "agent.report",
12
+ "agent.settled",
13
+ "agent.spawned",
14
+ "cost.cache_miss",
15
+ "cost.model.mismatch",
16
+ "cost.provider.switched",
17
+ "cost.usage.updated",
18
+ "hook.blocked",
19
+ "hook.completed",
20
+ "hook.triggered",
21
+ "mcp.catalog_updated",
22
+ "mcp.closed",
23
+ "mcp.connect_failed",
24
+ "mcp.connected",
25
+ "mcp.discovered",
26
+ "mcp.elicitation_declined",
27
+ "mcp.reconnect_exhausted",
28
+ "mcp.reconnected",
29
+ "mcp.reconnecting",
30
+ "mcp.tool_skipped",
31
+ "msg.block.end",
32
+ "msg.block.start",
33
+ "msg.retracted",
34
+ "msg.text.delta",
35
+ "msg.thinking.delta",
36
+ "plan.todo.updated",
37
+ "session.checkpointed",
38
+ "session.compacted",
39
+ "session.created",
40
+ "session.cwd_changed",
41
+ "session.ended",
42
+ "session.forked",
43
+ "session.locale.changed",
44
+ "session.microcompacted",
45
+ "session.output_style.changed",
46
+ "session.restored",
47
+ "session.resumed",
48
+ "session.workspace_trust.changed",
49
+ "tool.completed",
50
+ "tool.failed",
51
+ "tool.output.delta",
52
+ "tool.permission.decided",
53
+ "tool.permission.requested",
54
+ "tool.progress",
55
+ "tool.proposed",
56
+ "tool.started",
57
+ "turn.aborted",
58
+ "turn.completed",
59
+ "turn.error",
60
+ "turn.started"
61
+ ],
62
+ "eventSchemaSha256": "ddc7afac50d2ff8980ebeab2d8b3089dd197623dc2a23049e76a0944fa15ef59",
63
+ "contractVersion": "v1",
64
+ "sourceCommit": "34a6f37e23036ce8aa7cccd67dbbbd40863d8544",
65
+ "generatedAt": "2026-09-10T02:55:26.356Z"
66
+ }