@tansr/sdk Changelog

按版本列出 @tansr/sdk 的用户可见变更;每版分「新增 / 变更 / 修复」三段,涉及迁移的条目写明迁移方式。工程视角的完整变更记录见页末折叠段。

0.20.0(未发)

本版尚未发布;以下为候发内容,以实际发版为准。

新增

• 平台模型角色与主备裁决策略的公共类型：AppBundleModelRole / AppBundleModelRoles / AppBundleModelRoleSelection / AppBundleModelRoleRevision、AppBundleAdjudicatorPolicies、PlatformRoleModel，并声明能力 adjudicator-policy-slots-v1：会话按应用生效的 main / fast / adjudicator 三角色主备与实际使用的策略槽运行，模型许可、档位、预算与超限处置采用同一实际槽；否决、预算耗尽、受理结果未知或已开始输出时不借备用槽绕过；平台默认不是用户档位的上限。接入方须升级真实的 SDK 安装物，管理端保存成功不代表旧包已具备配对消费能力。
• defineTool 新增可选 permission: 'inherit' | 'allow' | 'ask'：缺省 inherit 沿原权限链；allow 只豁免缺省询问、ask 每次交用户确认，两者都不调用裁决模型；拒绝规则、硬安全边界与应用能力边界仍优先。query / createSession 派生的 Task 子、孙代理复用宿主的 permission.askUser，显式 ask 每次重新询问，无通道则拒绝。远端 SDK2 / 统一 API 的声明不增加该字段。

变更

• 已协商双槽裁决、但首次装配没有可用裁决人的会话：合法配置修复后同一会话可恢复裁决，继续使用原权限引擎与累计预算；显式 adjudication: { enabled: false } 不会因配置刷新被重新启用；配置刷新沿原身份隔离、失效与合法恢复边界，同一引擎的预算不因刷新重置。Electron 仍在主进程使用完整 SDK / kernel 与 IPC，不改为远端客户端。
• 相对 @tansr/sdk 0.19.0，根入口公共类型有新增与签名变化（候选登记时为 6 项新增、13 项签名变化，最终以冻结后的导出门为准）；使用 bundle 公共类型、自定义工具或装配扩展的调用方升级后须重新做类型检查。未变的 SDK2 / 统一 API 冻结合同不随此版本重定义。

本版尚未发布到 npm：以上为候选源码的候发内容，以实际发版为准；公开可安装的最新版仍是 0.19.0，不含这些模型角色与主备策略能力。

0.19.0(2026-10-10)

新增

• 新增非聊天操作客户端 createPlatformNonchatClient(options)（返回 PlatformNonchatClient；失败抛 PlatformNonchatError，携 status / platformCode / outcomeUnknown / taskId，区分「确定被拒」与「提交结果未知」）：以应用令牌、稳定幂等键与有界查询调用平台的嵌入（embeddings）、重排（rerank）、文档（document）、音乐（music）、音色（voice）与视频（video）操作，listModels 列出授权候选目录，submit / getTask / wait 提交并轮询任务（unknown / failed / succeeded 都停止轮询，资金状态以账单为准），listVoices / getVoice 找回当前身份的私有音色，uploadMusicSource / listMusicSources / getMusicSource / getMusicSourceByTask 管理私有音乐素材。这些操作只在你显式调用时发出，不会在聊天会话中自动执行。随之导出 NONCHAT_PROTOCOL、NONCHAT_OPERATION_PATHS 与 Nonchat* / Embeddings* / Rerank* / Document* / Music* / Voice* / PlatformOperationModel / PlatformVideoInput 等类型及对应的 *Schema 值。
• 新增实时连接合同：createRealtimeSession / getRealtimeSession / realtimeConnectionOptions（子协议常量 REALTIME_SUBPROTOCOL；类型 RealtimeSessionInput / RealtimeSessionSubmission / RealtimeSessionState / RealtimeHandshake / RealtimeConnectionOptions）：返回经校验的同源连接材料，供你的 WebSocket 工厂单次消费，SDK 不自动连接、不重连；连接票据过期或握手不可用时抛 PlatformNonchatError。
• 新增文档临时上传与显式清理：uploadDocument 把文档暂存到平台当前实例十分钟（不要求幂等键、不自动重提、不提交收费模型任务），deleteDocumentUpload 幂等删除；上传引用、有效期与资源归属仍由平台按授权校验，你需要沿这组接口管理自己的资源生命周期。新增应用额度类型 AppQuota / AppQuotaSchema（日 token、每终端用户日 token、RPM / TPM、图像张数 / 视频秒数 / 识别秒数 / 合成字数与操作单元等上限字段，均可为 null）。

变更

• CLIENT_FEATURES 新增 'nonchat-operations-v1'，出线头 x-tansr-client-features 的缺省声明串随之变化，升级后首次装配会按新指纹重拉一次 bundle（旧指纹条目自然失效，无需手清缓存）；对 ClientFeature 做穷举 switch 的代码补该分支。AppCapabilitiesSchema 加可选位 realtimeAudio；SpeakInput 加可选 voiceRef（应用私有音色资源引用，与系统 voice 互斥，作用域与目标模型由平台校验）。迁移：无需动作。
• 原 createSession / query 用法、Electron 主进程完整 SDK 与 IPC 接线保持兼容；档案材料生命周期的实现随主线修正内联进本版，调用面零变化。

本版 npm 包已于 2026-10-10 发布（与 @tansr/serve 0.15.1、@tansr/cli 0.10.3 同批）；根入口导出集相对 0.18.1 由 532 项增至 581 项（新增 49、删除 0；签名变化 3 处：CLIENT_FEATURES / AppCapabilitiesSchema / SpeakInput，均为加法），./extensions 子入口零差量。本版把此前已合入主线、但未随 0.18.1 发布的平台非聊天能力正式纳入发布物。

0.18.1(2026-10-04)

变更

• ./extensions 本地缓存宿主（createNodeCacheHost）的热窗口与冷恢复更省：每次缓存交换的原帧与在飞标记由两次 SQLite 事务改为一次，恢复语义收紧为「两键皆有或皆无」——准备之后、发送之前崩溃的请求不再留下耐久痕迹，也不再被恢复为 result_unknown；冷恢复接续时旧运行的绑定读取与新运行的心跳并行发出，任一失败即整体失败、不发出接续控制请求。旧格式缓存库照常恢复并在首次重放补齐。对你意味着：调用面、错误码、帽值与 readCacheContinuity 读面零变化，空闲机上热窗口约省 5 ms、冷恢复约省 4 ms。迁移：无；已有缓存库无需转换。

本版 npm 包已于 2026-10-04 发布（与 @tansr/serve 0.14.0、@tansr/cli 0.10.1、@tansr/api-client 0.3.0 同批）；SDK 源码自 0.18.0 零改动、导出集零差量（仍为根入口 532 项 + ./extensions 41 项），随车是因为 ./extensions 打进包内的缓存宿主代码有上述改动。如实披露：./extensions 缓存宿主的性能目标在本版正式测量后仍未全部达成——每映射常驻内存增量仍无法判定达标（一次性常数项约 1.86 MB 单独披露）、缓存局部 P95 增量 24.9 / 24.2 / 174.9 ms（允许 10 / 10 / 50 ms，较上版改善）、同步压力档未达 2 倍线（不劣化）；功能仍为缺省关闭、显式 opt-in，目标值不改。

0.18.0(2026-10-02)

新增

• 新增子入口 @tansr/sdk/extensions（41 项：子入口自身 1 + 具名导出 40），提供两组需显式装配的本地宿主；都不是 createSession 的缺省开关，Electron 完整 SDK / IPC 接线零变化，不 import 该子入口的消费者零变化。其一是本地归档宿主 createNodeArchiveHost(options)（含 NodeArchiveHostError）：host.open({ mode: 'fresh' | 'resume', … }) 完成归档安装或恢复后返回原 AgentSession，构造宿主本身不建库、首次 open 才初始化持久介质；archive.contextMaterials: true 显式安装材料链；读面有 readArchiveBinding / readArchiveStorageStrategy（本版固定单一授权来源加来源确认与耐久缓冲，不做复制与多设备同步，不是备份）/ 有界 readArchiveRecords / readArchiveArtifact（单对象 32 MiB 帽）/ readEffectiveContext（仅空闲已安装会话，不是防回滚凭证）/ flushArchive；同轮插入 inputCapabilities / getInputTarget / submitInput / getInputStatus；材料经 requestMaterials 有界分块上传，received 只证送达，enqueueMaterials 交下一查询屏障核验，完整档案不自动回灌。
• 本地缓存宿主 createNodeCacheHost(options)：平台令牌档经 cacheHost.open({ mode: 'fresh' | 'resume', sessionId, session }) 取得原 AgentSession；须显式传原 createFileSessionStore、applicationScopeId / endUserId / baseUrl、cache: { directory（绝对路径）, storeId, key: { id, bytes }, mode: 'create' | 'recover' } 与同步 authorize 回调（拒绝抛错）。readCacheContinuity(sessionId) 纯本地读连续性（无上游实报时命中 / 用量 / 计费恒 unknown）；lookup 只查已受理或已存响应；delete 须在全部宿主会话关闭之后、dispose() 之前执行，未知结果保留同一 requestId 供重试；dispose() 不代替保存与删除，也不关闭借用的 Store。410 session_archived 为终态，只有显式 archived: 'cold-new' 且获当前授权才建独立新关系。接口在场不等于已证明供应商缓存节费（见下方披露）。
• 新增 4 个类型导出 AppBundleAdapterDiagnosticStatus / AppBundleRequestAdapterDiagnostic / AppBundleBillingAdapterDiagnostic / AppBundleModelAdapterDiagnostics，配合 AppBundleModel.adapterDiagnostics?（只读投影，描述当前目录证据是否足以选择请求 / 计费适配器，供界面展示模型的调用与计量能力；不携供应商凭据或价格原文，平台未下发时为 undefined，段坏形只丢诊断不丢模型条目，旧 SDK / 旧 bundle 零行为变化）。

变更

• SessionStore / SessionRecord / SessionStoreCommitMeta 各加可选键：Store 声明 attachmentCheckpoints?: true 即承诺把附件准入状态与历史原子保存；SessionStoreCommitMeta.attachmentCheckpoint? 是 SDK 生成的不透明值，SessionRecord.attachmentCheckpoint? 原样回传，attachmentReferencesInvalidated? 表示 Store 修复过本次历史。内置 createFileSessionStore 已实现，createSession({ resume }) 自此把附件准入状态（累计注入字节 / 拒绝计数 / 条目）随历史冷恢复；不声明该位的自定义 Store 行为与 0.17 相同。迁移：自定义 Store 无需改动；要承接冷恢复的 Store 声明该位并把 meta.attachmentCheckpoint 与消息同次保存、get() 原样返回，不得解析、构造或以客户端元数据替代该值。
• ToolContext 加可选 executionTarget? / turnId?，GateDecision 加可选 executionTarget?：进程内 SDK（createSession / query / defineTool / 自定义工具与权限门）这三个键恒缺席，只有会话服务的显式远端执行档会填入，表示该调用将在远端绑定设备或受控服务执行。迁移：零；自定义门或工具若读到 executionTarget，不得回落宿主本机资源（缺资源即拒）。
• AppCapabilitiesSchema 加可选段 execution（bound-device-v1 绑定设备工具授权；缺位 = 未授权，绝不合并回进程内 tools；进程内 SDK 不消费该段，设备工具授权只在会话服务的显式远端执行档生效）；CLIENT_FEATURES 新增 'bound-device-v1'，出线头 x-tansr-client-features 的缺省声明串随之变化，升级后首次装配会按新指纹重拉一次 bundle（旧指纹条目自然失效，无需手清缓存）；fetchAppBundle 新增第 6 个可选参 requireCapabilities，为 true 时 bundle 缺 capabilities 段或段坏形即抛 AppConfigRequestError，缺省 false 为 0.17 行为。迁移：对 ClientFeature 做穷举 switch 的代码补 'bound-device-v1' 分支；按位置参调用 fetchAppBundle 的代码不受影响。
• 统一 API 合同对本包无行为变化：Electron 完整 SDK / IPC 模式不经 /api，会话服务的 /api 正式可用、/v1 缺省关闭与 /v2 /v3 退役预告对 SDK 内嵌 API 零影响；/api 调用面见 @tansr/serve 0.13.0 发布说明与 @tansr/api-client 的 ./api 子入口。

本版 npm 包已于 2026-10-02 发布（与 @tansr/serve 0.13.0、@tansr/cli 0.10.0、@tansr/protocol 0.2.0 同批）；根入口导出集相对 0.17.0 由 528 项增至 532 项，另加子入口 41 项，零删除；9 项签名变化均为可选键 / 可选尾参 / 常量词表加法，位置参调用源兼容。如实披露：./extensions 缓存宿主所依赖的三项性能目标在发布时仍未达成——每映射常驻内存 34,837 B（目标 32,768 B）、缓存局部 P95 增量 30.5 / 27.8 / 181.9 ms（允许 10 / 10 / 50 ms）、同步压力档 2,293 ms（上限 438 ms）；功能按条件交付、缺省关闭、显式 opt-in，目标值不改，供应商缓存净节费尚未证明。

0.17.0(2026-09-16)

新增

• 移动托管应用可分别开启网页抓取（WebFetch）与 HTTP 请求（Http）：平台应用能力合同中的可选托管位 tools.webFetch / tools.http 自本版与平台 API、控制台及 @tansr/serve 的装配保持一致；两位缺省关闭，未开启的应用行为不变。

变更

• 随包的核心 Http 工具支持由宿主设置私网访问上限；托管服务不允许引用宿主环境变量里的凭据，也不因此扩大终端权限。冻结协议与会话合同的指纹不变。

本版 npm 包已于 2026-09-16 发布（与 @tansr/serve 0.12.0、@tansr/cli 0.9.0 同批）；导出集相对 0.16.0 零增删、零签名变化（仍为 528 项），0.16.0 及其 tag 保持不变。

0.16.0(2026-09-15)

新增

• planSpeechInput 新增可选的原子输入限制 inputLimit（{ max, unit }，单位为 Unicode 码点、UTF-16 码元或 UTF-8 字节三者之一），与原有加权字数帽同时预检；整批预检时纯空白分段以新拒绝原因 empty_segment 拒绝——不自动删除空白、不自动拆分、不重试收费请求。迁移：对 SpeechInputPlanResult.reason 做穷举判别的宿主补齐 empty_segment。
• AudioTtsConstraints.inputLimit：客户端声明特性 tts-input-limit-v1 后，平台在语音模型约束里下发厂商的原子输入上限；未声明的旧客户端继续拿到保守的加权字数投影。加权 maxChars 帽与原子帽同时成立，自定义策略不能放宽厂商上限。平台侧的下发已于 2026-09-15 上线；模型约束里 inputLimit 缺席时 planSpeechInput 仍按原有加权字数单帽预检。

变更

• 公开签名变化（契约 contract-v0.29）：planSpeechInput 选项与 AudioTtsConstraints 各携一个可选字段，不传即零变化；按 0.x 规则以 minor 发布。随附的 Electron / serve 示例已对齐本版，遇到无法表达的原子限制时会明确要求升级 SDK，而不是静默放行。

本版 npm 包已于 2026-09-15 发布（与 @tansr/serve 0.11.0、@tansr/cli 0.8.0 同批）；0.15.0 及其 tag 保持不变。

0.15.0(2026-09-14)

新增

• 媒体产物随 tool_result 保留：图像 / 视频 / 语音工具的产物（artifact）进入会话历史，resume / 检查点恢复后可重建对应的工具卡；模型仍只消费原 content。SessionView 的工具调用卡新增 artifactUnavailable，表达历史携产物但预览无法安全恢复的情形（不改变工具完成状态；旧的无产物历史不设置）。
• 文件会话存储可选的有界容错读取：createFileSessionStore({ recovery: { mode: 'verified-ir', quarantineDir?, onRecovery? } }) 在完整校验链内隔离确定无效的消息记录，原始证据写到会话目录之外的隔离目录（缺省同级 .session-recovery-quarantine），并以 SessionRecoveryReport（数量、位置与内容指纹，不含正文）通知宿主；缺省仍为严格读取。新导出 SessionRecoveryPolicy / SessionRecoveryReport / SESSION_RECOVERY_VERSION（启用前核对已装运行包的能力版本，防旧包静默忽略新选项）。

变更

• 含媒体产物的会话存储升为版本 2（契约 contract-v0.28）。迁移：升级后不得再用旧版本的 writer 写同一目录；升级前备份，并把写同一会话存储的所有宿主（SDK / tansr serve / 命令行）一起升级。

本版 npm 包已于 2026-09-14 发布（与 @tansr/serve 0.10.0 同批）。

0.14.0(2026-09-14)

新增

• createSession({ trustProjectHooks })：项目层 hooks 信任门。缺省 false = 工作区 .tansr/settings.json / settings.local.json 声明的 command / http hooks 零执行、零 hook.* 事件（用户层 / 托管层 hooks 照常）；true = 宿主代表用户为该工作区授信。SDK 不持久化信任、不读 tansr 命令行的信任记录；门住的项目层 hooks 在场时经 onWarning 通报一次 project_hooks_untrusted（detail 携 cwd 与登记到的层），缺席回落事件流 turn.error { scope: 'sdk.notice', recoverable: true }。行为收紧：此前克隆仓库、createSession 一起就会跑起来的项目层 hooks 缺省不再执行；已向用户确认工作区可信的宿主传 trustProjectHooks: true。单轮 query() 暂无授信位，项目层 hooks 在其中恒不启用。
• createSession({ hostShell: 'posix' | 'powershell' })：权限引擎解析 Shell 命令的词法方言。缺席随平台（与内置 Shell 工具实际派生的 shell 一致，零现状变化）；显式值供测试或跨平台演练，与真实执行 shell 错配会让词法守卫与执行环境脱节，生产宿主不应设置。三档皆生效。
• createSession({ budget })：会话预算闸，形 { maxUsd?, maxTotalTokens?, onExceeded?: 'block' | 'warn' }，与配置文件 budget 段同形、与 tansr 命令行各形态走同一闸门语义。触顶时 'block'（缺省）在下一次模型调用前终止本轮（turn.aborted { reason: 'budget_exceeded' }，会话保持打开、后续轮同拦），'warn' 每次查询至多一条 turn.error { scope: 'budget', recoverable: true } 后继续；两上限都缺席 = 不接闸。maxTotalTokens = 输入 + 输出 + 缓存读 + 缓存写（思考 token 按模型能力位并入输出、不重复计）；maxUsd 只对以 USD 计价的模型出数（托管 / 注入档内置价目为 CNY、不设防），币种无关兜底用 maxTotalTokens。非法取值在任何 IO 前以 invalid_options 拒绝；不新增事件类型。新导出类型 SessionBudgetOptions。
• 会话事件积压有界：首订阅者到来前的积压受 createSession({ events: { maxBacklogEvents, maxBacklogBytes } }) 条数 / 近似字节双上界约束，缺省 1000 条 / 2 MiB（正数或 Infinity）；越界丢最旧、最新一条恒保留，队首以恰一条一等事件 session.events_dropped { scope: 'sdk.events', droppedCount, reason: 'count_limit' | 'bytes_limit', droppedBytes, firstDroppedSeq, lastDroppedSeq, maxEvents?, maxBytes? } 通报（contract-v0.27；契约清单 revision 6 → 7，事件型表 54 → 55）。SessionView 把它归入 notices（code: 'session.events_dropped'、无 message），Narrator 出一行 events dropped [scope]: N event(s) dropped (reason)。对你意味着：长跑会话即便忘记订阅也不会耗尽内存；在 send() 前挂上订阅者的既有代码零改动；按 type 判别通报的宿主改判 session.events_dropped。
• drain({ force: true }) / closeAsync({ force: true }) / 单轮 cleanup.drain({ force: true })：违约适配器（settle() 回 pending > 0 或超时）不再让收尾永久悬挂——预算耗尽后释放屏障，对仍在飞的收尾记 query_settlement_forced / compaction_settlement_forced，随后直接释放自有资源（会话级 MCP host 的 close 被调用）并以同一预算等待完成，结果恒 status: 'failed' 携结构化失败。对未关闭会话无效。缺省 drain() 只观察不释放，语义不变。
• token 接受 () => string getter：bundle / heartbeat、模型直连、媒体工具、session.platform 直连客户端、提示词刷新器五类平台请求发起时取现值，令牌轮换后无需重建会话；getter 须回非空字符串。query() 同律。
• query() 收尾失败 / 超时时的 SdkLifecycleError 新增 error.result（已完成的 QueryResult，onLifecycleError 同携）；需要终态文本的调用方读 error.result?.finalText。
• QueryCounters 新增只读计数 apiRounds（模型派发总数，恒不退还）与 recoveryAttempts（同轮恢复重试次数）；modelTurns 仍是预算口径。用 deepEqual 锁定整个计数对象的测试需补这两个字段。
• 补登 0.13.1 之后并入、此前未在发布说明列出的 18 项导出（均为加法）：应用提示词失败呈现 ApplicationPromptFailure / ApplicationPromptFailureReason / ApplicationPromptRetry / describeApplicationPromptFailure / applicationPromptFailureMessage 与 AppConfigRequestError；上下文与模型状态 SessionContextState / SessionModelState / ContextBudgetState / SwitchModelOptions / SwitchModelResult / ModelTransitionBackup；同轮投递 SendBlocksResult / SessionUserBlock；语音输入规划 planSpeechInput / countSpeechCharacters / SpeechInputPlan / SpeechInputPlanResult。导出集相对 0.13.1 由 506 项增至 525 项，零删除。

变更

• SessionNotice.message 变为可选：turn.error { recoverable: true } 归约仍带 message，session.events_dropped 归约不带。迁移：宿主按 code 渲染、message 只作兜底（如 notice.message ?? notice.code）。
• SessionView 的 narrate() 对 turn.error { recoverable: true } 的一行文案由 … — recoverable, you can retry 改为 … — recoverable, session continues：SDK 只担保会话仍开、可继续发送，是否重试由宿主决定。按该文案做字符串匹配的宿主（不建议）需改判；按 notices[].code / scope 判别者零变化。事件形不变。
• close() 后 setModel / setThinking / interrupt 一律 throw session_closed（此前静默改状态 / 空操作），setModel(alias) 先于别名解析拒绝；只读方法照旧可读。迁移：改为在 close 前调用或捕获 session_closed。
• AgentSession.pushBody 自公开类型声明剥离（运行时对象保留一个版本周期，close 后调用 throw session_closed）；它从未是承诺面，外部代码请勿依赖。
• createSession / query 的 env 决定出网代理：HTTPS_PROXY / HTTP_PROXY / NO_PROXY 参与 WebFetch / Http 工具与 hooks http 的代理决策，process.env 不再被读取（缺席仍为进程级单例）。迁移：依赖 process.env 代理却传了自定义 env 的宿主，把代理三变量并入所传 env。
• 查询事件流关闭即取消：对 events 调 return() / throw()（含 for await 提前 break）现在会取消本轮，在飞模型流与工具经 signal 见到中止（'iterator_closed'），不再签发终局事件；compactNow() 对已关闭查询立即以 query_closed 返回。依赖「退出循环后在飞工具仍会跑完」的调用方需改为消费到终局事件再退出。
• 会话预算的 totalTokens 口径由内核单点给出：思考 token 视为输出的子集不再叠加计入；已配置 budget.maxTotalTokens 的会话可能比此前更晚触顶，属口径修正。
• 工具入参由调度器按 Tool.inputSchema 中央校验（只作门、原参下行）：不合法即以 tool.failed { errorType: 'invalid_args' } + isError 结果回喂模型，execute 不被调用、不触发权限裁决。
• signal 的 abort 监听在 close() 时解除，多会话共享 shutdown signal 时已关闭会话可被回收；createSession({ fork }) 的新会话记录改在装配成功后落 store，失败时不留孤儿记录。无需迁移。

本版 npm 包已于 2026-09-14 发布（与 @tansr/serve 0.9.0、@tansr/cli 0.7.0、@tansr/api-client 0.2.0 同批）。本段合并了同期登记的两个小段（查询计数与事件流关闭语义、工具入参中央校验）。

0.13.1(2026-09-11)

变更

• 统一四类媒体系统工具的说明与缺少平台连接时的错误提示，补齐 tools.builtin 中英文示例，明确平台提供方授权与工具归属的区别。
• 旧 tools.platform 兼容别名、错误码、授权字段、默认显式选择与计费行为保持，无需迁移现有调用；公共声明注释整理不新增导出、不改签名。

0.13.0(2026-09-10)

新增

• AgentSession 新增同轮文本投递、目标与能力发现、状态查询接口；accepted 表示内存接纳，consumed 表示已进入历史，均不代表模型完成。
• session.drain()、session.closeAsync() 与可等待的 MCP 关闭用于观察真实资源完成；超时后仍可继续等待，不把逻辑关闭当成清理完成。
• query() 可显式装配 MCP 和 skills，与多轮会话共用装配能力。
• 应用系统提示词支持平台配置：默认 fallback 在 SDK 未传 system 时使用平台段；可选 prepend 保留平台段在前，即使 SDK 显式传入空数组。需要配套 API 与 SDK 版本。
• systemAppend 可追加宿主指南而不覆盖平台默认；AgentSession.applicationPrompt 提供只读来源与策略摘要，不含正文。低阶 runAgent 可手动使用 resolveApplicationSystem 组合已验证的配置。平台提示词与策略在后续新一轮前刷新，当前执行轮固定，会话与历史保留。
• zeroAppCapabilities(platform)、AppBundle.capabilitiesIssues、PlatformWarning.detail:capabilities 段解析失败时可拿到具体问题。
• 快照:listCheckpointsDetailed / planCheckpointRetention、类型 CheckpointRetention、WriteCheckpointResult.retentionWarning。
• 裁决人通报码集 ADJUDICATOR_UNAVAILABLE_WARNING 与 DEVELOPER_ONLY_ADJUDICATOR_WARNING_CODES。
• 令牌失效码集与谓词:TOKEN_INVALIDATING_CODES / APP_TOKEN_REJECT_REASONS / APP_TOKEN_TRANSIENT_REASONS、isTokenInvalidatingCode / isTransientAppTokenReason 及类型 TokenInvalidatingCode / AppTokenRejectReason(由平台 OpenAPI 生成,随平台新增错误码自动跟进)。
• bundle governance.sessionRetentionDays 透传:parseAppBundle 产物新增 governance,类型 AppBundleGovernance。
• 媒体错误提示:hintFor(face, code, audience?)、类型 MediaHintAudience / MediaHintFace;PlatformMediaProviderOptions 新增 audience 与 hintOf 覆写缝。
• assembleTooling / buildSdkToolSet 选项 imageInput(读取图片的能力判定注入缝;createSession / query 已内部接好)。
• ErrorView.detail(透传 turn.error.detail,首个取值 { scope: 'plan' })。
• AppTokenMinter.invalidate:按平台返回的失效原因逐出缓存令牌。
• 类型 AssembleToolingAdjudication。

变更

• 同轮追加仅支持文本与内存 ACK；持久投递和原生多媒体追加明确不支持。结果仅保留当前及上一轮，不能作为永久去重保证。
• 公开 API 的 IDE 悬停说明和类型文档面向使用者改写，导出集与签名不因注释整理改变。
• permission.mode 与默认注入的裁决人不再互斥抛错:显式给了 permission.mode 即视为「自管模式」,裁决人不装,并经 onPlatformWarning / onWarning 通报 adjudicator_skipped_by_mode;显式 adjudication 与 permission.mode 同现仍抛 invalid_options。要静默自管:adjudication: { enabled: false }。
• 未接 permission.askUser、且裁决人未授予资格档的会话不再切换到 auto 模式:工作区内写 / 删从自动放行变为征求确认(无通道即拒绝,decisionSource: 'policy')。要保留放行:在控制台为应用的裁决人授予资格档(≥ low),或接入 permission.askUser。
• 机器放行也会发出 tool.permission.decided 事件(decisionSource: 'classifier';模式放行对非只读调用为 'mode'),onDecision 形不变。
• ErrorView.recoverable 由可选改为必填;可恢复的咨询类错误进入 SessionView.notices(最多保留 20 条),不再覆盖 lastError。自定义投影请补该字段。
• 工具失败以 tool.completed.isError 出线,不再伪装成 tool.failed;reducer 把 isError: true 归为失败卡。
• capabilities 段在场但整段坏形时回落零能力档(此前回落默认档,等于放开七项能力)并通报 capabilities_unparsed;段内未知键改为剥除而非整段判坏。段缺席时行为不变。
• AppBundleModel.modelId 改为可选:平台剥掉该键后条目照收,读取方按 string | undefined 处置。
• 词表外媒体错误码的 MediaProviderError.hint 从空串变为缺席;按 hint === '' 判「无指引」的宿主请改判缺席。not_found 新增提示。
• assembleTooling 选项 adjudicator 改为 adjudication({ classifier, posture, tier, explicit });仅直接调用该函数的进阶用户受影响,createSession / query 用户无需改动。
• turn.error 新增可选 detail;套餐配额拒绝(plan_concurrency_exceeded / plan_end_users_exceeded / plan_required / plan_tier_insufficient)携 detail.scope = 'plan',与 serve HTTP 面同键同值。
• 平台 bundle 缓存键改为四维(基址 / 应用 / 径别 / 能力位),不同径别或能力位组合不再串档。

修复

• 会话初始化失败会尝试释放已装配的自有 MCP 资源；持久化与用户回调同时失败时保留两类错误。
• 读取图片改按当前模型能力放行(setModel 热切换即时生效);此前 SDK 面一律拒绝且提示文案有误。
• 分叉出的会话读历史分页时 total 少一。
• 权限门重判改为按替换后参数的真实归因判定;hook 明示 ask 不再被裁决人代批;两处重判不再重跑 hooks 或二次咨询。

本版 npm 包已发布，包含此前未单独发布的 0.12.0 候选能力。单文件可执行版与移动端安装包的发布、签名和真机验收另行确认。

0.12.0

历史候选，未单独发布；相关能力与兼容变化并入 0.13.0，请参阅该版说明。

0.11.1(2026-09-06)

新增

• 存储出口补齐:createFsBlobStore / createChaosBlobStore / runStorageConformance(会话存储一致性套件)及相关类型经 @tansr/sdk 导出。

无其他行为变化。

0.11.0(2026-09-06)

新增

• 权限裁决姿态:adjudication 选项(posture / callBudget / enabled / endUser),姿态缺席时按 permission.askUser 是否在场推导;askUser 第三参 decision 携来源与理由。
• 裁决协议 v4 与应用协议单阶段;bundle 裁决人资格档解析;onPlatformWarning 新增六种裁决人通报码(adjudicator_unavailable 等)。
• 会话持久化:SessionStore / createFileSessionStore,会话可分叉与恢复。

变更

• 破坏性变更:令牌档默认装配 bundle 裁决人,permission.mode 与之同现会抛 TansrSdkError('invalid_options')(0.10 及更早为静默择一)。当时的迁移方式:删 permission.mode,或传 adjudication: { enabled: false } 自管模式。0.12.0 起以兼容径收回。

工程变更原文(CHANGELOG)

以下为工程变更原文,逐字取自包内 CHANGELOG(面向贡献者,含内部编号);仅标题层级整体下调两级,指向源码仓内文件的相对链接改为纯文本路径。

发版门(scripts/release/gate.mjs,十王修案 FX-C-25)③ 步要求:每个发布版本在此有 ## <version> 段且段体非空; ④ 步以 exports.snapshot.json 与上一 tag 比判 semver——0.x 期任何导出集变化(增 / 删 / 签名变)至少 minor,patch 不得携新导出 (doc/89 §3.3「0.x minor = breaking」)。发版回执落 doc/release/sdk-<version>.md;无回执无 tag。 0.11.x 及更早版本为追溯登记(当时无本文件;doc/49 · doc/129 L20 回执位随主线改口)。

面向 SDK 消费方(开发者)的公共面变更登记;kernel / protocol 内部改动不入此表。版本号 = packages/sdk/package.json; 每条写「变了什么 · 对你意味着什么 · 迁移方式」。0.11.0 之前的历史见 git(git log -- packages/sdk)。 tansr 命令行 / serve 宿主面分别见仓根 CHANGELOG.md 与 packages/server/CHANGELOG.md(三包同律,doc/release/README.md)。

0.20.0 — 候选(待发布;MODEL-ROLE-04)

MODEL-ROLE 发行准备：本段描述候选源码，尚未发布到 npm。公开 @tansr/sdk@0.19.0 于2026-10-10发行，不含后续合入的模型角色与主备独立策略；历史同版本本地候选不能当作公开发行物。

• 新增 AppBundleModelRoles 等角色类型、AppBundleAdjudicatorPolicies 和 PlatformRoleModel，并声明 adjudicator-policy-slots-v1：按 App 的有效 main／fast／adjudicator 主备和实际槽策略运行。模型许可、档位、预算与超限处置采用同一实际槽，否决、预算尽、受理未知或已输出不借备用绕过；平台默认不是用户档位上限。接入方须升级真实 SDK 安装物，管理端保存成功不代表旧包已具备配对消费。
• 修复已协商裁决双槽、但首次装配没有可用裁决人的会话：合法配置修复后，同一会话可恢复裁决，继续使用原权限引擎及累计预算；显式 adjudication: { enabled: false } 不因配置刷新重新启用。接入方无需为这类合法恢复重建会话，原许可与宿主权限边界保持。
• 配置刷新继续沿原身份隔离、失效与合法恢复边界；同一引擎的预算不因刷新重置。SDK token 档原默认裁决及显式关闭语义保持，CLI 的启用开关和权限模式不在本发行中改动。Electron 仍在主进程使用完整 SDK／kernel 与 IPC，不改为远端客户端。
• 相对正式 @tansr/sdk@0.19.0 的已提交根／子入口快照有6项新增、13项签名变化，原0.x导出门要求minor；最终差集以本候选冻结后原构建和exports门为准。使用 bundle 公共类型、自定义工具或装配扩展的调用方须重新类型检查；未变的SDK2／UAPI冻结合同不随此版本重定义。

工具许可（ARB，2026-10-11）

• 每个 defineTool 新增可选 permission: inherit | allow | ask：默认沿原链，显式豁免或用户许可跳过模型裁决；拒绝规则、硬安全与应用能力边界仍优先。
• query / createSession 的 Task 子、孙代理复用宿主 permission.askUser，显式 ask 每次重新询问；无通道则拒绝。Electron 完整集成方式不变。
• 本段随0.20.0候选登记，尚未发行；远端SDK2/UAPI声明未增加该字段。新增公共选项按原0.x导出签名门推进minor，不沿用已发布版本号冒称上线。

0.19.0 — 2026-10-10

REL-FULL-20261010：将已合入主线、但未包含在公开 0.18.1 成品中的 REL-10 接口正式纳入发行候选；发布状态以本版发行回执为准。

• 新增 createPlatformNonchatClient / PlatformNonchatError 及非聊天操作、模型发现、任务轮询和私有资源恢复类型，覆盖嵌入、重排、文档、音乐、音色及视频等平台操作；只发送调用方显式请求，不在聊天会话中自动执行这些操作。
• 新增实时连接合同、应用额度类型、文档临时上传与显式清理接口；上传引用、有效期及资源归属仍按平台授权校验，调用方须沿新增接口管理自己的资源生命周期。原 createSession、Electron 主进程完整 SDK 与 IPC 使用方式保持兼容。
• 内联主线已修正的档案材料生命周期实现；没有合入当前 persistence 开发分支。新增导出按 0.x 期至少 minor 规则升至 0.19.0，精确导出差量由本版 exports 门登记。

0.18.1 — 2026-10-04

「0.14.0 批」(USDK-11;UAPI 方案 §0 D23 / D31,冻结 2026-10-04;发布状态以 doc/release/sdk-0.18.1.md 回执为准)。packages/sdk/src 自 0.18.0 零改动、导出集相对 @tansr/sdk@0.18.0(tag → 29a21769)零差量(gate ④ 所需 patch);随车的原因是发布物内容有差量——./extensions 子入口把私有工作区包 @tansr/providers 打进 dist,而其 twp/cache-client.ts / internal/host-runtime-continuity.ts / cache-wire.ts / cache-core-wire.ts 随 PERF-01 (c)(d) 改动(下文第三条);platform/config-error.ts 引用的私有 @tansr/i18n 其 catalogs.generated.json 随 manifest r7 再生。前两条只改仓内测量器与披露口径,包内零字节变化。

• 32 KiB 映射常驻门的测量口径拆分(PERF-01 (b);源 bench/billing/sdk2-cache-executor.mjs measureSdk2CacheMappingMemory,用例 scripts/test/sdk2-cache-executor.test.mjs;./extensions 缓存宿主代码零变化,导出集零变化):候选臂相对基线臂的额外常驻自此拆为「每映射增量」(阈值不变 32,768 B,按原定义)与「常数项」(缓存宿主模块 / JIT / StatementSync 容器等一次性固定成本,独立帽 524,288 B,单独列项);两臂同法——对已填充映射数档位(n ≥ 1)的常驻中位做最小二乘直线,截距差 = 常数项,各档位 (候选 − 基线 − 常数项) / n = 每映射增量,n = 0 档不参与拟合(一次性成本在首条映射处为阶跃)。历史具名下界 35,395 B 不是新帽。归档 JSON 原字段不改名,新增 constantTerm / constantTermBytes / constantCapBytes / constantTermVerdict / rangeBytesPerMappingExcludingConstant / perMappingVerdict,综合 verdict 须两项皆 within;原合并口径保留为 verdictIncludingConstant。对你意味着:只改测量器与披露口径,不改阈值、不改宿主行为;0.18.0 段「性能与延期披露」的红数原样保留,新口径读数与结论见 doc/report/PERF-01-AB-代码缓存与32KiB常数项-2026-10-03.md(手册 doc/90「公开缓存宿主与受信后端桥」节末)。正式读数(2026-10-03 空闲窗口,三轮 × 三组中位):heap 常数项 1,855–1,881 KB(≈ 3.5× 512 KiB 帽,constantTermVerdict = regression);每映射增量(剔常数)heap [−72.6 KB, +8.3 KB],区间跨零,perMappingVerdict = unknown(候选臂稳态每映射增长低于基线臂 ≈ 22 KB,非正增量不代签;一组 rss 侧 lower 42.6 KB 判 regression);旧口径对照 [34.8 KB, 395.3 KB] 与 0.18.0 段红数一致。门未过,SDK2-09 的 B 披露维持,阈值与帽值不改。迁移:无。
• 常数项帽改口径(PERF-01 (b2) / UAPI 方案 §0 D41,用户确认 2026-10-04;源 bench/billing/sdk2-cache-executor.mjs · bench/billing/sdk2-cache-constant-attribution.mjs,用例 scripts/test/sdk2-cache-executor.test.mjs;./extensions 缓存宿主代码零变化,导出集零变化):上条的常数项「独立帽 524,288 B」自此改口径为「已归因的披露项 + 不回退棘轮」——测量器 constantCapBytes 524,288 → 2,097,152(2 MiB;非设计帽:正式三组读数 1.855–1.865 MB + ≈ 12% 余量,JIT 份额随 Node / V8 版本变,任何增长须拍板),归档 JSON 新增加法字段 constantCapBasis: 'ratchet'(与 constantCapBytes 并列,原字段不改名、不删,判定规则不变)。归因(sdk2-cache-constant-attribution.mjs,报告 doc/report/PERF-01-CD-耐久点合并与冷恢复加法-2026-10-03.md §4–§5):JIT 机器码 ≈ 700 KB(≈ 49%,单列为诊断数)、vault 打开 155 KB(RFC 信任锚)、首映射对象 406 KB + 首上下文 68 KB(固有);全关 JIT 仍 719 KB > 512 KiB,可惰性化者为无,不加 JIT 旗标;D30 原 512 KiB 是归因前为堵「把成本挪进常数项」漏洞所设的守卫数,不是 SDK2-09 产品需求。每映射帽 32,768 B 一字不改。对你意味着:只改测量器与披露口径,宿主代码与导出集零变化;常数项判定随之 within,但每映射判定仍 unknown(区间跨零 / 一组 rss regression),SDK2-09 的 B 披露不变,须空闲窗口正式测量每映射 within 后门才算绿。迁移:无。正式测量(2026-10-04 空闲窗口,doc/report/PERF-01-正式测量-2026-10-04.md):候选三有效组每映射剔常数 heap [−71,306, +7,144] B 仍 unknown,常数项 heap [1,856,065, 1,866,497] B 在棘轮内;门不转绿,B 披露不变。同日用户拍板 (a):constantTermVerdict 只对 heap+external 判(棘轮按 heap+external 定义),rss 常数项另列披露字段 constantTermRssVerdict(加法字段,不进综合 verdict;正式读数 2.9–6.6 MB,自 SDK2-09 起即为旁证),verdictBasis 字符串随之写明;每映射门不变。
• 缓存宿主 C2 热窗口单一耐久点与冷恢复并行拉取(PERF-01 (c)(d);源 packages/providers/src/twp/cache-client.ts · packages/providers/src/internal/host-runtime-continuity.ts,经 ./extensions createNodeCacheHost 与 @tansr/serve ServeCacheHost 共用;导出集零变化、manifest 不 bump):(c) 每次 C2 交换的原帧 exchange/<requestId>(core 投影时另有 core-exchange/<requestId> 与首次迁入的 metadata 升格)与在飞标记 flight/<requestId> 由两次 SQLite 事务改为一次,仍在 send 完成能力 / 尺寸 / 令牌 / 证明检查之后、交 fetch 之前(RFC-SDK2-缓存连续性 §4.2);恢复语义收紧为「两键皆有或皆无」——prepare 之后、send 之前崩溃的请求不再留下耐久痕迹、不再把从未出网的请求恢复为 result_unknown,事务中崩溃由热日志回滚,事务后崩溃与此前相同;metadata 升格为客户端级待办,随首个落盘的交换事务提交(多条 Core 请求先后 prepare、后者先 send 亦不会出现「core-exchange/ 行 + 旧格式 metadata」的拒读库);旧格式(无 flight/ 的 exchange/)库照常恢复并在首次重放补齐。(d) 冷恢复接续时旧运行 binding 读(GET)与新运行心跳(POST /heartbeat)并行发出,心跳由 source_conflict 判定之后挪到判定之前(对新运行自身幂等,不触碰 binding / ticket),任一失败整体失败且不发出 continuations 控制 POST;零新增平台 / 门面操作。对你意味着:createNodeCacheHost 的调用面、错误码、帽值(128 控制 / 16 交换 / 4096 完成 / 64 MiB)与 readCacheContinuity 读面零变化;热窗口少一次 FULL 同步 COMMIT、冷恢复少一次串行往返(空闲机 ≈ 5 ms / ≈ 4 ms,正式读数待 doc/report/PERF-01-CD-耐久点合并与冷恢复加法-2026-10-03.md §7 空闲窗口);P95 / 压力门结论不在本条改口。迁移:无;已有缓存库无需转换。

0.18.0 — 2026-10-02

已发布(“2026.10 统一 API 发行车”,源码 29a21769,npm @tansr/sdk@0.18.0 dist-tag latest;回执 doc/release/sdk-0.18.0.md)。导出集相对 @tansr/sdk@0.17.0(tag → e9752cc8)的实测差量(REL-PREP-3,2026-10-01;以 tag 内 exports.snapshot.json 与集成分支 15bcd675 仓内 exports.snapshot.json + exports.subpaths.snapshot.json 逐名比对,0.17.0 无子入口快照):根入口 528 → 532,+4 / −0 / ~9;新增子入口 ./extensions 41 快照项(子入口自身 1 + 具名导出 40);合计 +45 / −0 / ~9,与 S10 执行单 §2 对 main d1818d8f 的预判一致,所需 minor;gate ④ 至少 minor。发行时以版本 bump 同笔再生的快照为准。本段由 REL-PREP-2(2026-10-01)自发行说明草案附录 A.3 落实;SDK2.0 收口语义条目由 REL-PREP-3 按 S10 执行单 §5.3「A 起草」逐条补入(U 定稿),每条括注卡号 / 提交与源码位置。

• 新增子入口 @tansr/sdk/extensions(首次随包;41 快照项 = 子入口 1 + 具名 40,名与签名以 exports.subpaths.snapshot.json 为准;根入口零删除)。两组显式宿主,都不是 createSession 的缺省开关,Electron 完整 SDK / IPC 接线零变化;源码 packages/sdk/src/extensions/**,用法见 packages/sdk/README.md「SDK2 归档宿主」「SDK2 缓存宿主与后端接续」与 doc/90「SDK2 开发候选」节:
  • 本地归档宿主(SDK2-02 2699e558 / 03 9c19a54a / 05 269ef440 / 06 810a0516 / 07 6d65e3d0 / 08 b6791ceb):createNodeArchiveHost(options: NodeArchiveHostOptions): NodeArchiveHost + NodeArchiveHostError。host.open({ mode: 'fresh' | 'resume', … }) 完成归档安装 / 恢复后返回原 AgentSession,构造宿主本身不建库、首次 open 才初始化持久介质;archive.contextMaterials: true 显式安装材料链,省略 / false 只保留归档交接。读面:readArchiveBinding / readArchiveStorageStrategy(本版固定 single-authorized-source + source-ack-with-durable-spool,replication / synchronization 皆 'none'——不是备份、不是多设备同步)/ 有界 readArchiveRecords({ afterSequence, limit, maxBytes }) / readArchiveArtifact(复核 SHA / MIME / 长度,单对象 32 MiB 帽)/ readEffectiveContext(轮末有效上下文引用:仅空闲已安装会话,未决即拒、不修复不重放,不是防回滚凭证)/ flushArchive;同轮插入:inputCapabilities / getInputTarget / submitInput / getInputStatus(不回落 cancel + send);材料:requestMaterials → 有界分块上传 → received 只证送达,enqueueMaterials 把原请求与 lease 交给下一查询屏障的唯一 ContextManager 核验代际 / 摘要覆盖 / 预算,完整档案不自动回灌、摘要覆盖的原文不因重开复活。类型:NodeArchive{Subject,Operation,HostOptions,FreshSessionOptions,ResumeSessionOptions,OpenRequest}、ArchiveHost{Quota,Limits}、ArchiveCompletionAuthorization(finishPendingOnResume 须另给独立 authorizeCompletion)、ArchiveAttachmentSource(可信外置图片源:同步 describe 给出登记时固定的 MIME / 字节数 / SHA256,异步 read 受 signal / maxBytes 约束;URL 只是查表键,SDK 不自动 fetch、不把地址变成文件 / 网络权限;未配置保持原内联附件行为)、ArchiveEffectiveContextReference、Archive{RecordPage,Artifact,BindingView,StorageStrategyView}、ArchiveMaterial{Issue,Request,UploadChunk,UploadStatus,Response,Receipt}、ArchiveInput{Capabilities,Target,Submission,Receipt,Result}。
  • 本地缓存宿主(SDK2-07 c4d23736 / 66f6e1fb;SDK2-09 性能卡只调优不改形):createNodeCacheHost(options: NodeCacheHostOptions): NodeCacheHost。平台令牌档经 cacheHost.open({ mode: 'fresh' | 'resume', sessionId, session }) 取得原 AgentSession(NodeCacheSessionOptions 剥除 Store / sessionId / resume / fork / initialMessages 等宿主持有键;令牌档 baseUrl 须与宿主一致);须显式传原 createFileSessionStore(需其受保护删除能力)、applicationScopeId / endUserId / baseUrl、cache: { directory(绝对), storeId(稳定), key: { id, bytes(32 字节本地介质密钥,应用安全保存) }, mode: 'create' | 'recover' } 与同步 authorize(对 open / resume / cold-new / run / delete 回非负十进制串 authorizationRevision,拒绝抛错)。readCacheContinuity(sessionId) 纯本地读逻辑缓存连续性(provider 命中 / usage / billing 无上游实报恒 unknown);lookup 查原 Core 受理 / 已存响应,不清 pending、不当新用户轮执行;delete({ sessionId, authorization: { token, baseUrl, fetchImpl? } }) 在全部宿主会话 close / drain 之后、dispose() 之前执行,经原 Store 排他锁确认远端墓碑再删史,未知结果保留原 requestId 与 vault 供同一删除重试,删除进行中拒绝 open / dispose,冷宿主未 open 时直接 store.delete 拒 mapping_unavailable(不是「没有来源」);dispose() 不代替保存 / 未知结果确认 / 删除,也不自动关闭借用的 Store。continuity(NodeCacheContinuityBridge:issuerId / sourceNamespace / credential({ sessionId, intentBytes, signal, assertCurrent }))缺省同 runtime(runtimePolicy 省略或 'preserve'),显式 'renew-on-restore' 才向持有同一真实 Store来源权威的受信后端取短期 grant(issuer 私钥不下终端,本地 vault key 不能替代);410 session_archived 为终态,只有显式 archived: 'cold-new' 且获当前授权才建独立新关系、不复用旧 logical / group。类型:NodeCache{HostOptions,OpenRequest,DeleteRequest,LookupRequest,LookupResult,SessionOptions,ContinuityAuthority,ContinuityBridge,ContinuityView}。
  • 对你意味着:不 import @tansr/sdk/extensions 的消费者零变化;两宿主的冷重开 / 删除 / 跨运行接续责任边界以上述方法注释与 README 为准,接口在场不等于供应商缓存节费已证(见本段末「性能与延期披露」)。迁移:无;新消费方按 README 示例显式装配。
• 根导出 9 项签名变化(逐名;0.x 期签名变 = breaking,按 doc/89 §3.3 以 minor 承载。本版 9 项全部是可选键 / 可选尾参 / 常量词表加法,结构实现与位置参调用源兼容,无运行时行为回退):
  • SessionStore / SessionRecord / SessionStoreCommitMeta(USDK-08 901c8916;源 packages/sdk/src/sessions/store.ts)——变了什么:SessionStore.attachmentCheckpoints?: true(Store 承诺附件准入状态与历史原子保存、按会话域原样恢复);SessionStoreCommitMeta.attachmentCheckpoint?: unknown(SDK 生成的不透明值,随 commit 的 meta 下发);SessionRecord.attachmentCheckpoint?: unknown(get() 原样回传 SDK 曾提交的值)+ attachmentReferencesInvalidated?: boolean(Store 实际修复过本次历史时置 true,SDK 据此失效附件引用但保留累计准入预算)。对你意味着:内置 createFileSessionStore 已实现(file-store.ts 声明 attachmentCheckpoints: true,随卷落 / 读回检查点),createSession({ resume }) 自此把附件准入状态(累计注入字节 / 拒绝计数 / 条目)随历史冷恢复(session.ts 只在 Store 声明该位时启用);不声明 attachmentCheckpoints 的自定义五方法 Store 行为与 0.17 相同(SDK 冷恢复保守失效引用、不伪造缺失状态)。迁移:自定义 Store 无需改动;要承接冷恢复的 Store 声明 attachmentCheckpoints: true 并把 meta.attachmentCheckpoint 与 messages 同次保存、get() 原样返回——不得解析、构造或以客户端元数据替代该值。
  • ToolContext(kernel src/tools/types.ts;USDK-04 d7c9e9fd + SRV-06 3d3ceba6)· GateDecision(kernel src/tools/dispatch/permission-decider.ts;USDK-04 d7c9e9fd + SDK2-09 059f8033)——变了什么:ToolContext.executionTarget?: ExecutionTarget、ToolContext.turnId?: string;GateDecision.executionTarget?: ExecutionTarget。ExecutionTarget = { kind: 'device' | 'controlled-service'; executorId; bindingId; bindingRevision; authorizationRevision; workspaceId?; workspaceRevision?; interpreter?: { id; revision; hostShell } }(kernel world/execution-boundary.ts;受信宿主给定的落点事实,不是模型参数、不是客户端自报授权;在 d.ts 内联,不新增根导出名)。对你意味着:进程内 SDK(createSession / query / defineTool / 自定义 Tool.execute / 自定义权限门)这三个键恒缺席——只有 serve SDK2 显式执行档的调度器会填入,表示该调用将在远端绑定设备 / 受控服务执行,原审批摘要与去重域据此区分;turnId 是原查询轮身份,供远端精确重试证明使用。迁移:零;自定义门 / 工具若读到 executionTarget 不得回落宿主本机资源(缺资源即拒,不是宿主兜底)。
  • AppBundleModel(+4 新导出 AppBundleAdapterDiagnosticStatus / AppBundleRequestAdapterDiagnostic / AppBundleBillingAdapterDiagnostic / AppBundleModelAdapterDiagnostics;e2124f0c MODEL-REFACTOR-01,源 packages/sdk/src/platform/bundle.ts)——变了什么:AppBundleModel.adapterDiagnostics?: AppBundleModelAdapterDiagnostics = { request: { adapterId, operation, status, source?: 'routing' | 'compatibility', reason? }, billing: { adapterId, operation, status, reason? }, conflicts: string[] },status ∈ 'ready' | 'review' | 'unresolved'。对你意味着:只读投影,描述当前目录证据是否足以选择请求 / 计费适配器,供界面展示模型的调用 / 计量能力;不携供应商凭据、价格原文或可执行适配器对象;平台未下发时 undefined,段坏形只丢诊断不丢模型条目,旧 SDK / 旧 bundle 零行为变化。迁移:无。(本仓无 MODEL-REFACTOR-01 卡报告,语义据源码 JSDoc;平台侧下发时点另见 api 仓。)
  • AppCapabilitiesSchema / CLIENT_FEATURES / fetchAppBundle(USDK-04 d7c9e9fd,承 USDK-02 应用授权合同;源 packages/sdk/src/platform/contract.ts / client.ts)——变了什么:① AppCapabilitiesSchema 加可选段 execution?: { version: 'bound-device-v1'; boundDevice: { tools: Partial<Pick<CapabilityTools, 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'list' | 'shell' | 'process' | 'skills' | 'mcp' | 'customTools'>> } }(.strip();缺位 = 未授权,绝不合并回旧进程内 tools),推导类型 AppCapabilities 随之加键,normalizeAppCapabilitiesForPlatform 原样保留该段;② CLIENT_FEATURES 由 ['platform-audio', 'tts-input-limit-v1'] 变为 ['platform-audio', 'tts-input-limit-v1', 'bound-device-v1'],ClientFeature 联合多一值,出线头 x-tansr-client-features 缺省声明串随之变——bundle 缓存键的 featuresFingerprint 由该串派生,升级后首次装配按新指纹重拉一次 bundle(旧指纹条目自然失效,无需手清缓存);③ fetchAppBundle(base, token, fetchImpl, ifNoneMatch?, clientFeatures = CLIENT_FEATURES, requireCapabilities = false) 新增第 6 个可选参,true 时 bundle 缺 capabilities 段或段坏形即 throw AppConfigRequestError({ stage: 'app_config', reason: 'invalid_config', retry: 'check_configuration' }),不再回落缺省 / 零能力档(供 serve SDK2 显式远端执行档只接受平台实际下发的有效能力);缺省 false = 0.17 行为。对你意味着:进程内 SDK 不消费 execution 段(设备工具授权只在 serve SDK2 执行档生效;应用经平台 PATCH /v1/apps/:id 携 x-tansr-client-features: bound-device-v1 配置,见 packages/server/README.md「应用授权与终端能力」);旧 desktop / mobile / server 标签与旧 tools 位不推导设备授权。迁移:对 ClientFeature 做穷举 switch 的代码补 'bound-device-v1' 分支;按位置参调用 fetchAppBundle 的代码不受影响;直接用 AppCapabilitiesSchema 判「未知键必拒」的调用方注意 execution 自此是已知键(0.12.0 起本就 .strip() 剥未知键)。
• 性能与延期披露(SDK2-09;用户授权代拍 D12「A 时间盒一轮」→ 到期仍红,转 B):本包 ./extensions 缓存宿主所依赖的三项原性能门——32 KiB 映射常驻归属、缓存局部 hot / cold P95(10 / 50 ms)、1record / 1KiB 同步压力档 2 倍线——截至 2026-09-28 仍红(N1 具名不重叠下界 35,395 B 超 32,768 B 帽 2,627 B;Windows 140 位置 P95 红;centralized 326 ms / offload 3 188 ms 对 2× 652 ms 判 duration_regressed;SDK2.0 集中交付计划 §26 / §28),功能条件交付、缺省关闭 / 显式 opt-in 不变。S09 时间盒结算(2026-10-01,空闲主机、三组取中位,既有测量器;报告 doc/report/SDK2-09-性能门时间盒-2026-10-01.md):32 KiB 常驻 heap lower 34,837 B/映射(帽 32,768,regression);P95 Δ short-text hot 30.5 ms(允 10)/ cold-restore hot 27.8 ms(允 10)/ cold-restore cold 181.9 ms(允 50);压力 centralized 219 / offload 2,293 ms(2× 线 438,duration_regressed);基线同口径 34,824 B / 30.4 / 24.9 / 221.7 ms / 2,687 ms——两项无语义变化的优化(预算槽记录解码前剪尾部填充、安装就绪记录结构验证备忘)带来 cold −40 ms、压力 −15%,三门仍红 → 按 B「功能条件交付 + 明确延期披露」关闭、红数原样入账、另开 PERF-01 承接,阈值不改。不是外部依赖、不改称通过;供应商缓存净节费未证明(集中计划 §25:实测与披露完成、未证明净节费)。详见 packages/server/CHANGELOG.md 0.13.0 同名条。
• 统一 API 合同对本包无行为变化:Electron 完整 SDK / IPC 模式不经 /api,本发行车的 /api GA、/v1 下线、/v2 /v3 退役预告对 @tansr/sdk 内嵌 API(手册 §一～§十五)零影响;/api 调用面见 packages/server/CHANGELOG.md 0.13.0 段、手册第十六章与 @tansr/api-client/api。

0.17.0 — 2026-09-16

• 平台移动能力合同保留可选 tools.webFetch / tools.http，与 API、控制台及 serve 装配一致；缺省关闭，现有未启用应用行为保持（MOB-WEB-01 / REL-12）。
• 随包核心 Http 支持宿主私网访问上限；托管服务禁用宿主环境凭据引用，不扩大终端权限。冻结协议及会话合同指纹未变。

0.16.0 — 2026-09-15

REL-07 将 AUDIO-01 增量以独立 minor 和 contract-v0.29 发布；实际发布状态以对应 doc/release 操作回执为准。已发 SDK 0.15.0 / serve 0.10.0 及其 tag 保持不变。

• planSpeechInput 支持可选原子 inputLimit，整批预检拒绝纯空白分段（empty_segment）；不自动删除空白、不自动拆分或重试收费请求。宿主的拒绝原因穷举须补齐新值。
• SDK 新增 AudioTtsConstraints.inputLimit 与 tts-input-limit-v1 协商；旧客户端继续使用保守加权投影。Electron / serve 示例兼容已发布包，遇到无法表达的原子限制时明确要求升级。
• SDK 0.16.0 / serve 0.11.0 承载本次公开签名变化，原子单位支持码点、UTF-16 码元和 UTF-8 字节；旧加权 maxChars 帽与原子帽同时成立，不允许自定义策略放宽厂商上限。详见 doc/rfc/contract-v0.29.md。

0.15.0 — 2026-09-14

MEDIA-03 已发布；正式源码、门禁及 npm 操作结果见 doc/release/sdk-0.15.0.md。

历史媒体产物随 tool_result 保留，恢复后可重建图像、视频、语音工具卡。新增 artifactUnavailable 表达预览缺失；模型仍只消费原 content。含产物的会话存储使用版本 2，升级后不得用旧 writer 写同一目录。详见 doc/rfc/contract-v0.28.md；发布与安装物见本节正式回执。

0.14.0 — 2026-09-14

REL-06 按 DEC-RF-24 候选版本重新编译；实际发布状态以 doc/release/sdk-0.14.0.md 操作回执为准。核心组件设计审查整改波(RF-01 … RF-11 / RF-P1 … RF-P3 / RF-S1 / RF-Z,2026-09-11 … 13):SDK 资源生命周期整改(RF-04,含代拍 #3 A / #4 B)、 contract-v0.27 换形(RF-P1)、查询计数与事件流关闭即取消(RF-06)、工具入参中央校验(RF-08b)、会话预算闸(RF-P3a)等。导出集相对 @tansr/sdk@0.13.1(506 项)→ 525 项(exports.snapshot.json 为准;+19 零删,gate ④ 至少 minor):RF-04 名单零增删、7 项签名变化 (AgentSession / CreateSessionOptions / ManagedQueryOptions / SessionDrainOptions / SdkCleanupHandle / SdkLifecycleError / SessionNotice); +1 SessionBudgetOptions(RF-P3a,下文);其余 +18 为 0.13.1 之后并入主线、此前未在本表登记的媒体 / 应用提示词 / 上下文状态面加法 (AppConfigRequestError / ApplicationPromptFailure / ApplicationPromptFailureReason / ApplicationPromptRetry / ContextBudgetState / ModelTransitionBackup / SendBlocksResult / SessionContextState / SessionModelState / SessionUserBlock / SpeechInputPlan / SpeechInputPlanResult / SwitchModelOptions / SwitchModelResult / applicationPromptFailureMessage / countSpeechCharacters / describeApplicationPromptFailure / planSpeechInput;能力见 examples/electron-chat/README.md 与仓根 CHANGELOG.md)。

• 会话事件积压有界:首订阅者到来前的积压受 CreateSessionOptions.events 的条数 / 近似字节双上界约束,缺省 1000 条 / 2 MiB; 超界丢最旧、最新一条恒保留,队首以恰一条一等事件 session.events_dropped { scope: 'sdk.events', droppedCount, reason: 'count_limit' | 'bytes_limit', droppedBytes, firstDroppedSeq, lastDroppedSeq, maxEvents?, maxBytes? } 通报(protocol contract-v0.27,RFC-RF-1 / DEC-RF-20;Infinity 上界以键缺席表达; droppedBytes / maxBytes 为 JSON 文本长度近似度量;contract/MANIFEST.json revision 6 → 7,型表 54 → 55)。SessionView 把它归入 notices (code: 'session.events_dropped'、无 message、detail = 载荷去 type / scope),Narrator 出一行 events dropped [scope]: N event(s) dropped (reason)。 上界以内「晚到首订阅者收全量积压」不变;直播后订阅者全部离场期间的事件不再堆积(此前无界增长)。对你意味着:长跑会话即便忘记订阅也不会 耗尽内存;需要更多积压时 events: { maxBacklogEvents, maxBacklogBytes }(正数或 Infinity)。迁移:在 send() 前挂上订阅者的现有代码零改动; 按 type 判别通报的宿主需改判 session.events_dropped——本候选段此前登记的过渡形 turn.error { scope: 'sdk.events', errorKind: 'events_dropped' } 未随任何已发版本发布,一步换形、不双发、不合成旧形。
• 变更:SessionNotice.message 变为可选(message?: string;RFC-RF-1 R2 / DEC-RF-20 QA-RFC-02 (b)):turn.error{recoverable:true} 归约仍带 message,session.events_dropped 归约不带(零文本事件不合成文案)。迁移:宿主按 code 渲染、message 仅作兜底(如 notice.message ?? notice.code)。
• signal 监听释放:会话级 signal 的 abort 监听在 close() 时解除;多会话共享 shutdown signal 时已关闭会话可被 GC,abort 后不重复 close;创建前已 aborted 的信号仍立即 close。无需迁移。
• fork 事务边界:createSession({ fork }) 的新会话记录改在工装 / 模型装配成功后落 store,装配或登记失败时删除已落记录(store 列表 零净增、无 meta.cwd 缺席的孤儿);自建五方法 store 的 fork 回落径 create() 同携 cwd。无需迁移。
• close 后全表 session_closed:setModel / setThinking / interrupt 在已关闭会话上改为 throw session_closed(此前静默改状态 / 空操作),setModel(alias) 先于别名解析拒绝(不构造新 client,currentModel() 不变);只读方法照旧可读。迁移:若曾在 close 后调用 这三者,改为在 close 前调用或捕获 session_closed。
• pushBody 弃用:AgentSession.pushBody 自公开类型声明剥离(@internal;运行时对象保留一个版本周期,close 后调用 throw session_closed)。它从未是承诺面(装配层入流口),外部代码请勿依赖;需要向事件流注入自定义通告的宿主请提需求。
• 令牌 getter:token 接受 () => string:bundle / heartbeat、模型直连、媒体工具、session.platform 直连客户端、提示词刷新器 五类平台请求发起时取现值携 x-tansr-app-token,令牌轮换后无需重建会话;getter 须回非空字符串。字符串形态零变化。query() 同律。
• 收尾悬挂有界 + drain({ force }):违约适配器(settle() 回 pending>0 / 超时)的收尾不再永久悬挂,改为屏障保护——缺省 drain() 只观察不释放自有资源(既有语义);drain({ force: true }) / closeAsync({ force: true }) / 单轮 cleanup.drain({ force: true }) 在预算 耗尽后释放屏障、对仍在飞的收尾记 query_settlement_forced / compaction_settlement_forced,随后直接释放自有资源(会话级 MCP host 的 close 被调用)并以同一预算等待完成,结果 status: 'failed' 携结构化失败。对未关闭会话无效。无需迁移。
• query() 结果保真:收尾观察失败 / 超时时仍以 SdkLifecycleError 结束(既有契约),新增 error.result 携已完成的 QueryResult (不整体替换),onLifecycleError 同携;消费者自身抛错时缺席。迁移:需要终态文本的调用方读 error.result?.finalText。
• env 决定出网代理:CreateSessionOptions.env / ManagedQueryOptions.env 的 HTTPS_PROXY / HTTP_PROXY / NO_PROXY 参与 WebFetch / Http 工具与 hooks http 的代理决策,process.env 不再被读取(缺席仍为进程级单例);同一 env 对象共享连接池。迁移: 依赖 process.env 代理却传了自定义 env 的宿主,把代理三变量并入所传 env。
• 新增:CreateSessionOptions.trustProjectHooks?: boolean——项目层 hooks 信任门(托管档):缺席 / false 时,工作区 .tansr/settings.json / settings.local.json 声明的 command / http hooks 不启用——零执行、零 hook.* 事件(user 层 / managed 层 hooks 照常);true = 宿主代表用户为该工作区授信,项目层 hooks 照跑。SDK 不持久化信任、不读 tansr 命令行的工作区信任记录,授信事实由宿主 自行向用户确认并逐次传入;prompt 型 hook 无执行体,抽取期即丢弃(与授信无关)。门住的项目层 hooks 在场时通报一次 SdkWarning { source: 'sdk', code: 'project_hooks_untrusted', detail: { cwd, registered: { projectShared?, projectLocal? } } }(onWarning; 缺席回落事件流 turn.error { scope: 'sdk.notice', recoverable: true },SessionView.notices 以 scope: 'sdk.notice'、message 前缀 project_hooks_untrusted: 收到)。对你意味着:此前克隆一个仓库、createSession 一起就会跑起来的项目层 hooks,现在缺省不再执行—— 行为收紧,user 层 hooks 与注入 / 令牌档零变化。迁移:已向用户确认工作区可信的宿主传 trustProjectHooks: true;托管 query() 共用 同一装配、同受此门(ManagedQueryOptions 暂无授信位,项目层 hooks 在 query() 内恒不启用,通知只经 onWarning)。
• 新增:CreateSessionOptions.hostShell?: 'posix' | 'powershell'——权限引擎 Shell 命令词法方言:缺席随平台(kernel detectHostShell(), 与内置 Shell 工具实际派生的 shell 一致,零现状变化);显式值直达 kernel 权限引擎(PermissionEngineConfig.hostShell),供测试或跨平台装配 演练(如在 Windows 上按 posix 词法演练规则)。与真实执行 shell 错配会让 Shell 命令词法守卫与执行环境脱节,生产宿主不应设置;三档皆生效。 无需迁移。两项均为可选键纯加法:导出名单零增删,CreateSessionOptions 与派生的 AssembleToolingOptions 两项签名变化。
• 新增:CreateSessionOptions.budget?: SessionBudgetOptions——会话预算闸(DEC-RF-29;导出集 +1 名 SessionBudgetOptions, CreateSessionOptions 签名变化):形 { maxUsd?, maxTotalTokens?, onExceeded?: 'block' | 'warn' },与配置文件 budget 段同形,tansr 命令行 四形态(TUI / headless / serve / acp)与 SDK 自此读同一段形、走同一 kernel 闸门语义——会话累计消耗触顶时,'block'(缺省)在下一次模型调用前 终止本轮(事件流 turn.aborted { reason: 'budget_exceeded' },会话保持打开、后续轮同拦),'warn' 每次查询至多一条 turn.error { scope: 'budget', recoverable: true } 后照常继续;两个上限都缺席 = 不接闸(等价不传)。消耗读会话内部账本(消费本会话 cost.usage.updated,含子代理上卷;思考 token 按各模型能力位并入输出、不重复计):maxTotalTokens = 输入 + 输出 + 缓存读 + 缓存写; maxUsd 只对以 USD 计价的模型出数——令牌档按平台 bundle 计价,托管 / 注入档当前内置价目为 CNY,maxUsd 不设防,币种无关兜底用 maxTotalTokens。 选项非法(非正数 / 非正整数 / 词表外)在任何 IO 前以 TansrSdkError('invalid_options') 拒绝。与 thinking.budget(单轮思考 token 预算)无关。 可观测面只走既有 turn.aborted / turn.error 通道,不新增事件类型(DEC-RF-48)。无需迁移:不传 budget 零变化。
• Narrator 咨询帧文案(RF-Z ⑯;仅 SessionView 的 narrate() 文本,事件形零变化):turn.error { recoverable: true } 一行由 turn notice [scope]: … — recoverable, you can retry 改为 … — recoverable, session continues——SDK 只能担保会话仍开、可继续发送, 「可重试」是宿主的决定,不再替宿主承诺。按该文案做字符串匹配的宿主(不建议)需改判;按 notices[].code / scope 判别者零变化。

查询计数与事件流关闭(RF-06;QueryCounters 签名变化):

• QueryCounters 新增两个可选计数字段 apiRounds(模型派发总数,恒不退还)与 recoveryAttempts(同轮恢复重试:可恢复错误重发 / 上下文溢出压缩重试 / 输出触帽升档重发);modelTurns 仍是预算口径(可恢复错误重试退还),语义不变。只读计数、加法字段,既有消费方无需迁移;用 deepEqual 锁定整个计数对象的测试需补这两个字段。
• 查询事件流关闭即取消:对 events 调 return() / throw()(含 for await 提前 break)现在会取消本轮——在飞模型流与工具经 signal 见到中止(reason 为 'iterator_closed'),句柄进入终态,不再有事件产出,也不签发终局事件。此前提前退出只在下一个屏障点停下,在飞的模型流 / 工具会不受打扰地跑完。compactNow() 对已关闭的查询立即以新增的拒绝原因 query_closed 返回(此前可能悬挂到屏障点)。依赖「退出循环后在飞工具仍会跑完」的调用方需改为消费到终局事件再退出。
• 会话预算的 totalTokens 口径由 kernel 单点 budgetSpendOf 给出:思考(reasoning)token 视为输出的子集不再叠加计入(此前 CLI / serve 装配层各自相加导致重复计费口径);已配置 budget.maxTotalTokens 的会话可能比此前更晚触顶,属口径修正。

工具入参中央校验(RF-08b;Tool 签名变化):

• 工具入参由调度器中央校验(只作门、原参下行):Tool.inputSchema 成为被兑现的契约——每次工具调用执行前,调度器按 inputSchema 校验入参,不合法即以 tool.failed { errorType: 'invalid_args' } + isError 结果回喂模型;工具 execute 不被调用、不触发权限裁决、 不计入工具执行指标。校验只作门:通过后权限裁决与 execute 见到的仍是模型给出的同一个原参对象(不做 zod 缺省补齐、不剥 schema 外键、 含 .transform() 的 schema 其产物也不下行);PreToolUse hook 的 updatedArgs 同过校验、同以原对象下行。诊断文案有界(最多 20 条 issue、约 2 KB,超出附省略标记)。对你意味着:defineTool 工具的坏参此前走到 execute 内自校、以 tool.completed { isError: true } 出线,现在以 tool.failed 出线且无 tool.started / tool.completed;defineTool 的 execute 内自校仍是约定、仍是 handler 参数的 唯一来源(handler 拿到的是自校 parse 出的产物,含 transform / 缺省值 / 剥除 schema 外键),坏参不会再触达它;自定义 Tool 的 execute 收到的是模型原参,需要产物的请自行 parse。迁移:按 tool.completed.isError 识别坏参的消费方改看 tool.failed.errorType === 'invalid_args'; 工具 schema 无需为此改动。
• Tool.argsValidation?: 'dispatcher' | 'remote'(加法可选位;Tool 签名变化,导出名单零增删):缺省 = 调度器校验;'remote' = 本地不校验、原参透传由远端按自身契约裁定,用于 inputSchema 只是远端契约宽松投影的桥接工具(SDK 内建 MCP 桥与 serve /v2 客户端 申报工具自动声明,两者行为零变化)。无需迁移。

0.13.1 — 2026-09-11

• 统一四媒体的系统工具说明与缺少平台连接时的错误提示，补齐 tools.builtin 中英文示例，明确平台提供方授权与工具归属的区别。
• 旧 tools.platform 兼容别名、错误码、授权字段、默认显式选择和计费行为保持；无需迁移现有调用。同步此前公共声明注释整理，不新增导出或改变签名。

0.13.0 — 2026-09-10

• 汇总此前未发布的 0.12.0 候选能力，并增加 AgentSession 的同轮文本投递、目标、能力发现和状态查询公共接口（INJ）；相对旧候发标签按 minor 推进。
• 文本追加继续当前会话与查询循环；accepted 是内存接纳，consumed 是进入权威历史，不代表模型完成或持久投递。当前及上一轮的有限回执不能作为永久幂等保证。
• AP-SP 平台系统提示词与 SDK system/systemAppend 保持原分层；当前轮快照稳定，下一显式新轮自动刷新平台配置。
• 公开 API 的 JSDoc(IDE 悬停 / index.d.ts / docs.tansr.com SDK 参考)改写为面向使用者的说明并补齐 94 处缺注释的导出;不再出现内部编号与流程用语。只改注释,导出集与签名不变,无需迁移(DS-33)。
• 新包携 contract/MANIFEST.json；Demo 在正式 registry 验证后同步依赖。旧 0.12.0 标签和以下候选说明仅作历史记录，真实发布以回执为准。

0.12.0

• AP-SP：应用 systemPromptPolicy 默认 fallback（SDK 显式 system 含 [] 替代平台），prepend 保留平台段在前、SDK 段在后（[] 也保留平台）。新增 systemAppend 宿主指南缝、resolveApplicationSystem 与只读 applicationPrompt 来源；query 含注入档同步追加指南。已有令牌档会话每个新轮前条件核验平台正文与策略，绕过装配缓存；轮内工具多步固定快照，刷新失败中止并保留历史，取消及30秒超时有界收口。宿主段固定；SDK/serve/Windows/Android/iOS 示例和手册同步。

历史候选归档：0.12.0 没有单独发布，以下内容并入 0.13.0；本地旧标签保留在原候选源码。实际发布以回执和 registry 为准。

核心机制整改（CM；历史候选内容）

• 自动/空闲摘要被质量校验拒绝时，已报告用量仍进入公共成本事件；拒绝摘要不替换历史。取消前已到达的用量会保全，不臆造尚未报告的费用（CM-02）。
• 直接调用 runIdleCompaction 的宿主须消费失败结果的 events；IdleCompactionResult 失败支路不再保证空数组，可能包含已报告的成本事件。导出名称数量不变，签名快照随本 minor 更新（CM-02/17）。
• 小上下文窗口的输出回退预算尊重自适应下限、调用方上限和测得的正剩余；零/负估算余量明确告知，并保留实际溢出的既有恢复通道（CM-06）。
• 四媒体工具在 provider 调用前校验参数；文件原子写失败保旧，大文件分页窗口驻留有界，工具超时增加残余操作提示。宿主无需新增一层媒体审批，重试有副作用工具前应确认旧操作已停止（CM-04/08/09/15）。
• 平台 ASR 工具、任务提交与 session.platform.transcribe 共用实际 JSON 体积预检；原始音频 24 MiB 与 JSON 32 MiB 分开守卫，越限在 fetch 前报错。URL 仍可用，BYO 不套用平台 JSON 帽（CM-11）。

发版门接管(FX-C-25)

• prepublishOnly 恒过 gate.mjs 六步;exports.snapshot.json 基线入仓(第二波收编后再生),自本版起导出集变化由门判 semver; README「3 平台位」订正为五平台位并写明 permission.mode × 裁决人例外。

兼容径(收回 0.11.0 的一处 breaking)

• permission.mode 与缺省注入的裁决人不再互斥抛错(FX-B-06;复审 Q-05)。0.10 的合法输入 createSession({ token, baseUrl, permission: { mode: 'acceptEdits' } }) 在 0.11.0 会 throw invalid_options; 自本版起:令牌档 bundle 裁决人是缺省注入(平台底档),你显式给了 permission.mode 即视为「自管模式」—— 裁决人不装、模式按你给的值、onPlatformWarning / onWarning 收一条 adjudicator_skipped_by_mode 通报(含正道指引)。显式 adjudication: { … } 与 permission.mode 同现仍是真矛盾,照旧 fail-fast invalid_options。要静默自管:adjudication: { enabled: false }。

行为变化(收紧)

• B 姿态 × 资格档 none 的会话不再切 auto 模式(FX-B-05;复审 J-03)。裁决人在场时的权限模式由 kernel modeUnderAdjudicator({ posture, tier }) 单点推导:headless × none → default,其余 → auto。此前一律 auto 连带工作区快路径——cwd 内 Write / Edit / rm / mv 零咨询放行;而 tier none 的裁决人对 safe 零软化权, 切 auto 换不到任何裁决对价。受影响形:未接 askUser、bundle 裁决人档无 tier 的会话——cwd 内写删从 「零咨询放行」变为「ask → 无通道 deny(decisionSource:'policy')」。要保留写删放行:给档授格(控制台 → 应用 → 裁决人 → 资格档 ≥ low)或接 permission.askUser(A 姿态照切 auto)。
• 权限门重判律与 cli 门同源(FX-B-10;复审 J-04 / J-05):createSdkPermissionGate 的「PreToolUse hook 入参 替换后重判叠加」「hook 明示 decision:'ask' 恒不被裁决人代批」「fallbackRedecide / approvalRedecide 两重判位 跳过 hooks 重跑与二次咨询」改为 import kernel permissions/gate-recheck.ts 同一份实现。可见差异:同严格度重判 现取替换后参数的真实归因(此前用 > 丢弃);两重判位现被识别(此前 hooks 会重跑、审批桥径会二次咨询)。
• 机器放行也出 tool.permission.decided(FX-B-09):裁决人放行恒发 decided{allow, decisionSource:'classifier'}; 模式放行对非只读调用发 decisionSource:'mode';规则 / 用户 / 策略与只读放行不发。onDecision 缝形不变。
• ErrorView.recoverable 必填 + SessionView.notices(FX-B-29;R-05 / M-08):可恢复的咨询帧(如 serve 落卷失败 turn.error{recoverable:true})不再污染 lastError,改入 notices(FIFO,上限 SESSION_NOTICES_MAX = 20); ErrorView.recoverable 由可选改必填,自定义投影请补该字段。
• 工具失败以 tool.completed.isError 出线(FX-B-25;R-17):四媒体工具超时 / 供应商失败不再伪装成 tool.failed, reducer 把 isError:true 归约为 failed 卡;protocol ToolCompletedEventSchema.isError? 为加法。 contract/MANIFEST.json revision 1 → 2。
• fork 出的会话历史分页不再走尾装载快径(FX-B-24;C-09 / V-B-44):getHistoryPage 对 forkedFrom 会话恒全量读, 修正分页 total 少一的缺陷;API 形不变。
• capabilities 段整段坏形回落零能力档,不再回落平台缺省档(FX-A-15 sdk 半边;复审 Q-02 / V-A-43)。此前 bundle capabilities 段在场却解析失败(位非 boolean / 段非对象)→ DEFAULT_APP_CAPABILITIES(read / glob / grep / list / todoWrite / askUser / customTools 七位被打开,hosted 应用回落 embedded 档 = fail-open);自本版起 → zeroAppCapabilities (platform)(tools 全 false;hosted 回落 hosted 档)并经 onPlatformWarning / onWarning 通报 capabilities_unparsed{ detail.issues: ZodIssue[] }(随 bundle 缓存,每次装配都到)。段缺席(旧 api / 装置键径不发段) 仍回落 DEFAULT_APP_CAPABILITIES、零通报(行为不变)。新导出 zeroAppCapabilities(platform);AppBundle.capabilitiesIssues 加法键(null = 解析成功 / 缺席);PlatformWarning.detail? 加法键。
• capabilities 三 schema .strict() → .strip()(FX-A-15;段内加键零击穿):CapabilityToolsSchema / CapabilityPlatformSchema / AppCapabilitiesSchema 对段内未知键剥除不炸(已知位仍逐项 boolean 校验)。此前 api 段内新增任一键会让整段判坏并回落 缺省档(音频两键教训);自本版起只剥未知键。放宽:直接用三 schema 判「未知键必拒」的调用方须自行加门。
• AppBundleModel.modelId 可选(M-07;候拍 A22):api 令牌径剥 models[].modelId 后条目照收(此前缺键即整条剔除 → bundle 模型面蒸发);缺席 / 空串 / 非串 = 键缺席。读 model.modelId 的调用方按 string | undefined 处置。
• Read 图片分支按会话当前模型放行(FX-B-20;T-15 / V-39):createSession / query 把当前模型的图片输入三态以 getter 注入 kernel Read 门 2(托管档经 registry 含 capability 覆写,令牌 / 注入档回落 providers 内置能力表;setModel 热切换 即时生效)。此前 SDK 面 Read 图片恒拒且文案误称「模型不支持」;现内置表收录且 inputModalities.image:'supported' 的模型返回 image 块,未收录模型仍拒但如实说「本执行面不知道(unknown)」。零配置变化。
• 套餐配额拒绝在事件流面可判(FX-B-20;M-03,protocol contract-v0.26):turn.error 加法可选位 detail, 平台套餐四码(plan_concurrency_exceeded / plan_end_users_exceeded / plan_required / plan_tier_insufficient) 携 detail: { scope: 'plan' }——与 serve HTTP 面 error.detail.scope 同键同值;reducer 落 ErrorView.detail(失败形) / SessionNotice.detail(咨询形),缺席不落键。contract/MANIFEST.json revision 2 → 3(eventSchemaSha256 变)。

加法(进阶 API)

• assembleTooling / buildSdkToolSet 选项 imageInput?: () => InputModalityMode | undefined(FX-B-20 / T-15):Read 图片门 2 谓词注入缝;缺席 = 未接线恒拒(与 0.11 同)。createSession / query 已内部注入,直接调用两函数的进阶用户按需传。

• ErrorView.detail?: Record<string, unknown>(FX-B-20 / M-03):turn.error.detail 透传;首个取值 { scope: 'plan' }。

• 快照是附属能力(FX-B-23):listCheckpointsDetailed / planCheckpointRetention / 类型 CheckpointRetention, WriteCheckpointResult.retentionWarning——单档隔离、GC 不再误删、杂散 notes.json 不再整体 CHECKPOINT_INVALID; listCheckpoints 数组形保留。

• 裁决人通报码集导出(FX-B-11):ADJUDICATOR_UNAVAILABLE_WARNING(冻结 { code, message })与 DEVELOPER_ONLY_ADJUDICATOR_WARNING_CODES(四码,仅开发者受众)。

• 平台 bundle 缓存键四维 bundleKey(base, appId, scope, featuresFingerprint)(FX-C-16;S-08):不同径别 / 能力位组合不再 串档;AppTokenMinter.invalidate?(FX-C-15;R-02)按 api detail.reason 逐出失效令牌。

• 令牌径失效码与 detail.reason 词表由 api openapi 生成(FX-C-15/片段;M-13 / R-02):新导出 TOKEN_INVALIDATING_CODES(今日 ['unauthorized'])/ APP_TOKEN_REJECT_REASONS(六值)/ APP_TOKEN_TRANSIENT_REASONS (['check_unavailable'];收到不失效不重铸)+ 谓词 isTokenInvalidatingCode / isTransientAppTokenReason + 类型 TokenInvalidatingCode / AppTokenRejectReason——皆来自 platform/error-codes.generated.ts(由 vendored contract/openapi.json 顶层 x-tansr-error-codes[] 经 scripts/contract-error-codes.mjs 生成,零时间戳; pnpm contract:check 再生零 diff 门)。持有 x-tansr-app-token 缓存令牌的宿主(serve refreshingFetch)据此判失效, 不再手写码集;api 新增一码带 x-invalidates-token → sdk 再生即得。

• bundle governance.sessionRetentionDays 形状级透传(FX-A-17/片段;M-05):parseAppBundle 新增 governance: AppBundleGovernance({ sessionRetentionDays?: number };整数 ≥ 1 才落键,段缺席 / 坏形 = {}),assemblePlatformModel 产物 AssembledPlatformModel.governance 同形透传;新导出类型 AppBundleGovernance。SDK 自身零消费——宿主(serve 平台会话 工厂)据此把会话保留期缺省 30 d 改读 org 配置值;段内其余键(org / licenseStatus / softLock / budgets)仍不解析。

• 平台媒体错误 hint 单源表 + 受众档(FX-B-26;复审 M-02 / M-08 / M-07 残留):新导出 hintFor(face, code, audience?) 与类型 MediaHintAudience / MediaHintFace;PlatformMediaProviderOptions 加可选键 audience?: 'app' | 'user'(缺省 'app',sdk / serve 令牌档文案逐字不变)与 hintOf?: (code) => string | undefined(覆写缝)。行为变化:词表外码 (如 http_502 / rate_limited)的 MediaProviderError.hint 从 '' 变为缺席,kernel 工具文本据此回落 MEDIA_GENERIC_HINT(与 BYO 径一致);not_found 新增 hint。宿主若按 hint === '' 判「无指引」请改判缺席。

公共面形变(进阶 API)

• assembleTooling 选项 adjudicator?: PermissionClassifierConfig → adjudication?: AssembleToolingAdjudication ({ classifier, posture, tier, explicit };FX-B-05 / FX-B-06)。createSession / query 用户不受影响(两入口内部 已改传);直接调用 assembleTooling 的进阶用户把 adjudicator: assembled.config 改为 adjudication: { classifier: assembled.config, posture: assembled.posture, tier: assembled.tier, explicit } (assembled = assembleTokenTierAdjudicator 产物;explicit = 开发者是否显式给了 adjudication 选项)。 新导出类型 AssembleToolingAdjudication。

0.11.1 (2026-09-06)

• 追溯登记(FX-C-25;当时未发回执):本版为 patch 却携新公共导出 runStorageConformance(会话存储一致性套件)——按 doc/89 §3.3 0.x 口径应为 0.12.0 的 minor;误发已成事实,不回收,自 0.12.0 起由发版门 ④ 步机器禁止「patch 携新导出」。
• 存储出口补齐:createFsBlobStore / createChaosBlobStore / runStorageConformance 及类型经 @tansr/sdk 出口(IO-14)。
• 无其他行为变化。

0.11.0 (2026-09-06;随 @tansr/cli 0.4.0 / @tansr/serve 0.6.0 发版)

Breaking

• BREAKING:令牌档缺省装配 bundle 裁决人,permission.mode 与之同现 fail-fast(doc/113 §4.4 G-5;复审 Q-05 登记为 breaking)。createSession({ token, baseUrl, permission: { mode } }) 这一 0.10 合法输入在本版 throw TansrSdkError('invalid_options', 'assembleTooling: "permission.mode" and an adjudicator are mutually exclusive …') (0.10 及更早:静默择一)。当时的迁移方式:删 permission.mode,或传 adjudication: { enabled: false } 自管模式。 0.12.0 起以兼容径收回(见上),本条保留为历史登记。

加法

• 权限裁决姿态(doc/113):adjudication?: { posture?: 'human-in-loop' | 'headless'; callBudget?; enabled?; endUser? }; 姿态缺席按 permission.askUser 在场性推导;askUser 第三参 decision 携 source:'classifier' + reason。
• 裁决协议 v4 / 应用协议单阶段;bundle adjudicator[s].tier 资格档解析;onPlatformWarning 通报码 adjudicator_unavailable / adjudicator_model_unavailable / adjudicator_budget_exhausted / adjudicator_breaker_tripped / adjudicator_evidence_drifted / adjudicator_posture_overridden。
• 会话持久化一期二期(SessionStore / createFileSessionStore / fork / resume)。
• 其余 0.11.0 变化(令牌档 / 三环工具入口 / 渲染管道等)见 doc/90 技术手册与 doc/49 回执;本文件自 0.12.0 起逐版机器化。

本文是否有帮助?

有帮助没帮助