@tansr/sdk 0.13.0 → 0.13.1

package/README.md

@@ -27,7 +27,7 @@ for await (const event of session.events) {
 }
 ```
 
-模型目录与能力位由平台 App 配置(控制台治理)自动下发,本地零配置。
+模型目录与授权能力由平台 App 配置下发。系统媒体工具须在 `tools.builtin` 中显式选择；仅开启平台授权不会让缺省 SDK 会话自动装入收费媒体工具。
 
 ## 应用系统提示词（AP-SP）
 
@@ -64,10 +64,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 +96,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.
 
 ## 文档与示例