@tansr/sdk 0.13.0 → 0.14.0

package/README.md

@@ -27,7 +27,7 @@ for await (const event of session.events) {
 }
 ```
 
-模型目录与能力位由平台 App 配置(控制台治理)自动下发,本地零配置。
+模型目录与授权能力由平台 App 配置下发。系统媒体工具须在 `tools.builtin` 中显式选择；仅开启平台授权不会让缺省 SDK 会话自动装入收费媒体工具。
 
 ## 应用系统提示词（AP-SP）
 
@@ -48,6 +48,39 @@ P 和 S 同为模型 system 输入，拼接次序不保证冲突指令谁胜出
 
 完整三档 SDK、Windows Electron、serve、Android／iOS 示例见[提示词指南](https://docs.tansr.com/sdk/system-prompts/)与仓内 doc/90 §4.12。此能力仍须发布包含 AP-SP 的 API 与 SDK／serve，旧版本不识别保留策略。
 
+## 模型、上下文和图文输入
+
+开发中的新接口须使用包含它们的 SDK 构建；旧 npm 包没有这些接口时，宿主应提示升级。
+`session.contextState()` 和 `session.subscribeContext(listener)` 提供可序列化快照：
+`selected` 是下一轮模型，`active` 是运行轮冻结的模型；`lastObserved` 仅在收到模型用量证据后存在。
+`currentModel({ active: true })` 查询执行轮模型，空闲时返回当前选择。fallback 只报告已观测到的提供方变化。
+`budget` 包含物理与有效窗口、输入估算、输出/思考预留、剩余量、压缩阈值及设置来源。
+未知值为 `null`；本地输入估算与平台累计计费用量分别展示。
+
+大窗口降到小窗口时，在空闲状态 `await session.switchModel(next)`。
+SDK 保留迁移前原文备份，必要时用源模型分段摘要，核验目标预算并落盘后再提交切换；
+图片、工具配对及其前后顺序保留，无法容纳即拒绝。失败或取消不静默截断历史。
+`modelTransitionBackup()` 可取回最近一次迁移备份；需要跨进程恢复时配置 checkpoint/store。
+外部压缩管理器需要通过 `switchModel(next, { compaction })` 显式提供与目标匹配的配置。
+摘要调用可能产生用量；备份不代表摘要语义必然完整，业务关键事实仍应核对。
+
+`sendBlocks([{ t: 'image', mime: 'image/png', data: base64 }, { t: 'text', text: '描述图片' }])`
+提交同一轮图文，返回 `started` 或带原因的 `rejected`。忙时由宿主保留整份草稿，不能自动去图重发。
+图片需满足格式魔数、单图 3.75 MiB、最多 20 张、总图片 30 MiB 和上下文预算限制；
+模型与传输通道都需支持图片。Read 产生的像素随工具结果发送到支持视觉的模型，元数据读取成功不等于模型已看见图片。
+
+`planSpeechInput(text, { maxCharacters, segment })` 使用授权模型 `maxChars` 规划朗读；
+汉字按 2、其他 Unicode 码点按 1 估算。超出单次限制须显式允许分段，总上限 32000、最多 32 段。
+宿主负责逐段执行、取消和保留产物，已成功或结果不明的收费请求不自动重放。
+应用提示词刷新失败提供 `reason`、`stage`、`retry`，继续中止该轮；由宿主换发开发者凭据并决定重试。
+
+The new interfaces above require a build that includes them. `contextState()` separates the next selected
+model, the active turn's frozen model, observed usage, and local context estimates. Unknown values are
+`null`. Await `switchModel()` while idle to prepare and validate a smaller context before committing;
+failure keeps the original history. `sendBlocks()` submits image and text together and rejects busy
+submissions without removing images. Speech planning requires the authorized model's character limit
+and explicit segmentation; completed or uncertain paid requests must not be replayed automatically.
+
 ## 三档 API × 三档模型来源
 
 | API | 形态 | 适用 |
@@ -64,10 +97,12 @@ P 和 S 同为模型 system 输入，拼接次序不保证冲突指令谁胜出
 
 ## 能力面一览
 
-- **三环工具一个入口**:`tools: { builtin: [...], platform: [...], custom: [...] }`
-  ——环2 内置本地工具(read/glob/grep/shell/…)、环3 平台托管能力(imageGen 图像
-  生成,平台代调按张计费)、环1 `defineTool` 业务函数(注册即说明书,JSON 参数表/
-  zod 双档);
+- **系统工具与业务工具统一入口**:`tools: { builtin: [...], custom: [...] }`。
+  系统工具包括文件、命令、网络及多媒体；`imageGen`、`videoGen`、`speechToText`、
+  `textToSpeech` 与其他系统工具一起从 `tools.builtin` 选择，执行骨架统一在内核。
+  SDK 媒体后端由平台提供，受应用授权、模型范围和计量约束。`defineTool` 注册业务函数，
+  接受 JSON 参数表或 zod schema。旧 `tools.platform` 仅为四媒体的弃用兼容别名，
+  会并入同一内置工具集合并去重，不代表另一层工具;
 - **联网搜索双位双门**:webSearch 工具本体是内置 `WebSearch`(写在 `tools.builtin`,
   旧写法 `tools.platform` 报迁移错),后端恒平台通道(按次计费归 App,SDK 恒无 BYO
   径)——装配需双位齐开(`tools.webSearch` 工具位 + `platform.webSearch` 通道位)且
@@ -94,9 +129,32 @@ P 和 S 同为模型 system 输入，拼接次序不保证冲突指令谁胜出
 - **计量**:`cost.usage.updated` 逐请求;终端自查 `/v1/my-usage` 恒无金额字段,
   开发者对账 `/v1/app-usage/by-end-user` 含金额(恒不代理给终端)。
 
-能力位(17 工具位 + 5 平台位:webSearch / imageGen / videoGen / speechToText / textToSpeech,
-`CAPABILITY_TOOL_KEYS` / `CAPABILITY_PLATFORM_KEYS` 为事实源)在平台控制台按 App 配置;位关而显式
-选择恒得到装配期可读错(`capability_disabled`,含修复指引),恒不静默缺工具。
+工具与扩展授权以及平台服务授权均在控制台按 App 配置；字段分别为 `capabilities.tools`
+与 `capabilities.platform`，键集合由 `CAPABILITY_TOOL_KEYS` / `CAPABILITY_PLATFORM_KEYS`
+提供。授权合同仍为 17 工具位 + 5 平台位；后者控制平台搜索及四媒体服务的使用权，
+不是工具归属分类。位关而显式选择得到
+`capability_disabled`，不静默缺工具。
+
+### 系统媒体工具示例 / System media tools
+
+```ts
+const session = await createSession({
+  token,
+  baseUrl: 'https://api.example.com',
+  tools: { builtin: ['imageGen', 'videoGen', 'speechToText', 'textToSpeech'] },
+});
+```
+
+先在应用配置中授权所需媒体服务与模型。示例只选择四个媒体工具；需要文件、网络等工具时，
+也应显式加入同一个 `builtin` 列表。权限确认、预算与平台计费继续适用。用户主动录音转写或朗读
+可以调用 `session.platform.transcribe()` / `.speak()`；这些是直连操作，不会伪造模型工具事件或自动写入聊天历史。
+
+All four media tools are built-in system tools selected through `tools.builtin`. The platform supplies
+their backend and enforces app permissions, model access, quotas, and billing. The retained
+`capabilities.platform` fields describe service authorization, not a separate tool category.
+Media tools require explicit selection; the default SDK tool set does not enable them automatically.
+The deprecated `tools.platform` selection remains an equivalent alias. User-triggered transcription
+and speech through `session.platform` are direct operations, separate from model tool calls.
 
 ## 文档与示例
 

package/contract/MANIFEST.json

@@ -1,8 +1,8 @@
 {
-  "revision": 4,
-  "sha256": "c57ffb63c51fa37f84814857240785a1c1d433839a7d0e6ebcdedc419838597c",
+  "revision": 7,
+  "sha256": "99d86f2b3ac6b6183bee7ca7717cbc6fa4b3af88fc1c8cf2d683488cde610e94",
   "errorCodes": 38,
-  "eventTypes": 54,
+  "eventTypes": 55,
   "eventTypeNames": [
     "agent.completed",
     "agent.followup",
@@ -39,6 +39,7 @@
     "session.created",
     "session.cwd_changed",
     "session.ended",
+    "session.events_dropped",
     "session.forked",
     "session.locale.changed",
     "session.microcompacted",
@@ -59,8 +60,8 @@
     "turn.error",
     "turn.started"
   ],
-  "eventSchemaSha256": "ddc7afac50d2ff8980ebeab2d8b3089dd197623dc2a23049e76a0944fa15ef59",
+  "eventSchemaSha256": "54b587ade59bf20a3d55647a160c3d857dbf2fa73730d82cf7811b7ee4097501",
   "contractVersion": "v1",
-  "sourceCommit": "34a6f37e23036ce8aa7cccd67dbbbd40863d8544",
-  "generatedAt": "2026-09-10T02:55:26.356Z"
+  "sourceCommit": "d346aadf99e1b7ce1db2226b71de03adcc22f3df",
+  "generatedAt": "2026-09-12T09:12:29.149Z"
 }