@tansr/serve Changelog

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

0.16.0(未发)

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

新增

• 平台会话装配协商 adjudicator-policy-slots-v1：复用与 SDK 共同的 kernel 实现，消费应用生效的主备模型与每个策略槽的档位、预算与升级处置；只有原本可信的零出站故障可切到合法备用槽，否决、预算耗尽、受理结果未知与已开始输出不换备；保留宿主询问姿态、权限硬边界与同引擎累计预算。
• 纳入已合入主线的持久化公开加法：会话事件日志快照、冷材料耐久覆盖，以及 ./extensions 中的共享归档、MySQL 预算 / 命令存储、冷存储索引与维护。这些是显式装配的宿主能力，不因更新包自动启用，也不改变冻结的远端执行合同；自定义 Store / 后端实现须对照随包声明重新类型检查。

变更

• 已协商双槽的会话在合法配置恢复后保留原权限引擎预算、显式关闭不复活；Task 在裁决关闭或没有可用裁决配置时不再借父主模型继续机器裁决，原人工询问通道仍保留；撤权后结算已发生的用量时按实际请求的模型归属，不记到配置刷新后的另一模型。
• 旧前缀行为保持：缺省 legacyPrefixes 仍为 readwrite。0.15.0 的发布说明曾计划在 0.16.0 改为 readonly，本候选不执行该迁移；显式 readonly / off 沿原合同，后续退役动作另行按原兼容与授权边界实施。
• 相对 0.15.1，根与子入口导出在候选登记时有 79 项新增、17 项签名变化、零删除，最终差集以冻结候选的构建与导出门为准；原生各语言客户端仍经 HTTP 连接服务端，不要求复制本地裁决实现，实际能力由所连服务端运行物决定。

本版尚未发布到 npm：以上为候选源码的候发内容，以实际发版为准；公开可安装的最新版仍是 0.15.1，升级平台管理配置不能替代升级实际的服务端运行物。

0.15.1(2026-10-10)

变更

• 业务工具（客户端声明的工具）沿设备执行链支持受控实时输出：输出走终端输出管道，总量由服务端固定为该绑定的 limits.maxRetainedBytes（客户端参数、平台声明或新的观察窗口都不能加额），分块与批次按 maxBlockBytes / maxBatchBytes 校验，正文只在原调用仍在进行时受理（完成后可读保留窗，取消或期限届满后不能继续追加）；工具未声明超时时沿用既有的 30 s 缺省；执行恒不回落到 tansr serve 主机。对你意味着：接设备执行链的原生客户端可以边执行边看到业务工具输出，预算与权限边界与此前相同。迁移：无。

修复

• 首次设备绑定不再被循环前置卡住：绑定资格与「连接已就绪」分开判断，GET /api/sessions/:id/capabilities 执行域的 bound-device 能力按绑定资格取源，不再要求目标已经绑定；可执行能力仍由原身份、平台与策略授权决定，资格判断只读、不刷新策略、不续租、不改绑定。对你意味着：原生客户端（Go / Rust / C++ 等）在新会话上首次绑定设备时不再遇到「能力不可用」。
• 统一错误信封的映射修正：result_unknown 的 retryAction 只会是 query-status 或 rebind（原域动作留在 detail.domainRetryAction），不再因域动作映射变成重发建议；未登记在映射矩阵的域码统一答 internal_error / HTTP 500（原状态留在 detail.domainStatus），此前会保留原状态码；未知的审批错误保留原错误语义。对你意味着：按统一 code / retryAction 编写的客户端不会再被引导重发副作用未知的请求。
• 检查点恢复与压缩重写先结算已消费的材料，保持未消费与仍持有材料的约束；材料生命周期与来源确认不被绕过。
• 旧前缀窗口缺省仍为 readwrite，本版不提前启用只读窗口。

本版 npm 包已于 2026-10-10 发布（与 @tansr/sdk 0.19.0、@tansr/cli 0.10.3 同批）；导出名集与签名相对 0.15.0 零差量（根入口 434 项 + ./extensions 98 项 + ./process 6 项），为纯修复版。

0.15.0(2026-10-06)

新增

• 旧 /v2、/v3/* 前缀的退役窗口旋钮：StartServerOptions.legacyPrefixes?: 'readwrite' | 'readonly' | 'off'（缺省 readwrite；环境变量 TANSR_SERVE_LEGACY_PREFIX）与 legacyPrefixSunset?: string（环境变量 TANSR_SERVE_LEGACY_SUNSET，HTTP-date 或 ISO-8601，缺省不发 Sunset）。只在门面在场（--v2）时装配，SDK1-only 部署零变化。readwrite = 旧前缀全部受理，体与状态同 0.14.0；readonly = 旧前缀上 manifest 登记为 write 的 38 个操作答 410 gone 统一信封（code: gone、retryAction: rediscover、detail.domainCode: legacy_prefix_retired，message 指向对应的 /api 操作），39 个读操作与 4 个流操作仍受理，manifest 未登记的旧路径不拒；off = 旧前缀全部答 404 not_found 统一信封。非法值 → startServer 抛 TypeError（环境变量非法值按既有规则告警并忽略）。对你意味着：本版升级无行为变化；要提前演练只读窗口的部署设 TANSR_SERVE_LEGACY_PREFIX=readonly 并观察 api.legacy_prefix_rejected，回滚只需改回 readwrite、无数据变化。迁移：请用 route 标签把 /v2/…、/v3/… 的写流量清零；缺省切到 readonly 的版本届时另出说明。
• 旧前缀响应附 Deprecation / Link / Sunset 头（RFC 9745 / 8288 / 8594；对「旧前缀逐字节不变」纪律的有意例外）：门面在场时 /v2、/v3/* 的每个响应（含 SSE，含 readonly / off 的拒绝）附 Deprecation: @1790900340（即 0.13.0 公告退役的时刻 2026-10-02T00:19:00Z）与 Link: </api/manifest>; rel="deprecation"；设置 legacyPrefixSunset 后再附 Sunset: <IMF-fixdate>（本版不内置日期）。readwrite 下响应体与状态码逐字节不变；/api 响应不附这些头。对你意味着：旧前缀客户端若有「未知响应头即拒绝」的规则须放行这三个标准头（@tansr/api-client 0.3.x / 0.4.0 均忽略）。迁移：无。
• 结构化日志两个新事件（warn 级）：api.legacy_prefix_mixed——同一会话 id 先后经 /api/sessions/:id/** 与 /v2/sessions/:id/** 或 /v3/sdk2/sessions/:id/** 访问时记一条 { route, family, from, to }（按会话 id 保留最近 4096 条，每次切换记一次；本版只留痕不拒绝）；api.legacy_prefix_rejected——readonly / off 下每个 method route 模板首次被拒记一条 { route, method, mode, status }。对你意味着：两事件计数持续为 0 一个观察窗（建议不短于一个发布周期）即可作为切到只读窗口的证据。迁移：无。
• 环境变量表由 36 键增至 38 键（即上述两键）；ServeRuntimeEnvStringFormat 加 'http-date'，TANSR_SERVE_LEGACY_SUNSET 为非法日期时告警 HTTP date (IMF-fixdate) or ISO-8601 timestamp 并忽略该键。

本版 npm 包已于 2026-10-06 发布（与 @tansr/cli 0.10.2、@tansr/api-client 0.4.0 同批）；导出名集不变（根入口 434 项 + ./extensions 98 项 + ./process 6 项），签名加法 5 处（StartServerOptions、ServeRuntimeServerOptions、ServeRuntimeEnvStringFormat，以及根入口与 ./process 的 LOG_EVENT）。/api 面、manifest（revision 7）与旧前缀响应体零变化，旧前缀响应头是本版唯一的有意例外。同批的 @tansr/api-client 0.4.0 把 ./sdk2 / ./terminal 冻结入口的缺省路由表改到 /api 门面，仍要打旧前缀的调用方须显式注入旧路由表。

0.14.0(2026-10-04)

新增

• /api 请求侧三头生效：Idempotency-Key（ASCII 1–128，仅写操作）经门面鉴权后映射到各域的 requestId——同键同义返回原响应、副作用恰一次，同键异义答 409 conflict（detail.reason: idempotency_key_reused），同键在飞等待首请求落定，首响应不可保留时答 503 result_unknown（retryAction: query-status）；响应缓存按用户 256 条 / 全局 4096 条 / 10 分钟有界。有版本资源（档案绑定、档案状态与绑定目标、缓存绑定、终端配置、记忆）的 2xx JSON 响应派生 ETag: "<revision>"，If-Match: "<revision>" 映射到该域的 expectedRevision，版本陈旧统一答 412 precondition_failed（retryAction: refresh，detail.reason: if_match_stale，原码留 detail.domainCode），不适用或弱校验器答 400 invalid_request。deadline（RFC 3339）到达时已过期答 408 invalid_request（detail.reason: deadline_exceeded），不受理、不触及下游、不占幂等窗。三头需要读体时请求体上限 1 MiB（超出 413 payload_too_large）。错误码不新增（仍 19 码），detail.reason 细因由 2 个增至 17 个。对你意味着：不携这三个头 = 行为逐字节不变；412 precondition_failed 自此既可能是围栏陈旧（rediscover）也可能是资源版本陈旧（refresh），按 detail.reason / detail.domainCode 区分。迁移：无。
• /api 新增操作 approval.credential.submit（POST /api/approvals/:id/credential，会话域，写）：鉴权 = 多租 Bearer + x-tansr-end-user，体 { digest, verdict: approve | deny, approver }，成功 200 { challengeId, result: "accepted" }；拒绝经统一信封——未知挑战 404 not_found、已过期 410 gone、摘要不符或已裁决 409 conflict（detail.submitCode 留原码），审批能力未接线 404 capability_unavailable。对你意味着：接审批凭据投递的 --v2 部署不再需要 --legacy-v1；/v1 直连面逐字节不变。迁移：把投递目标改到 /api/approvals/:id/credential。
• manifest revision 6 → 7（全部加法；11 族 / 81 操作 / 38 能力项）：每条操作新增 etagPath（2xx 体内资源版本键路径）与 expectedRevision（If-Match 映射目标，只登记在写操作），每个族新增 requestIdPath（Idempotency-Key 落到体内的位置）；GET /api/manifest 响应随之多出这三键，tansr-manifest-revision: 7。对你意味着：消费方可直接从 manifest 得知哪些操作有 ETag、接受 If-Match、幂等键落在何处，不必读源码；旧消费方忽略新键即可。unified-v1 合同 schema 同步补齐（precondition_failed 允许 retryAction 为 refresh 或 rediscover）。
• 绑定设备记忆的每轮 IO 预算可由可信宿主显式配置：memoryFor(scope) 返回值新增可选 deviceIoBudgetMs（整数 1 000–120 000 ms，越界在准备屏障按 invalid_request 400 拒绝、零设备派工）；缺省仍 10 000 ms、行为逐字节不变，人审等待不计入窗口，超预算仍只降级本轮不中断轮次。它不是权限、不授予读取；只在明确知道设备介质或往返延迟慢于缺省假设时放宽。

变更

• 显式 ownership 模式的会话所有权租约不再因慢 IO 自判失效：owner 自身的操作只按代际围栏判定、不再看 expiresAt，expiresAt 只决定他人的接管资格，owner 每次持锁写元数据顺带续约。对你意味着：启用所有权的可信宿主在病态慢盘上不再出现「无对手却自判死亡」的会话不可用；独占性仍由文件锁加代际围栏保证，接管方与活 owner 不会双写。须知：纯流式一轮里的续约仍靠排队中的心跳，接管窗口等于续约落地间隔，带 runtimeRecovery 的多 Serve 部署在病态慢盘上仍可能合法接管仍活着的 owner（活性损失、非双写，此前版本即如此）；本条只覆盖文件实现，共享事务 Store 的 owner 仍按数据库时间自判过期。未启用所有权的 tansr serve --v2 生产路径零变化。迁移：无。
• ServeSessionOwnershipOptions.leaseMs 下限由 1000 提高到 5000（文件与共享事务两实现同步）：显式传 1000–4999 的装配自本版抛 TypeError，缺省 30000 不变，[5000, 300000] 内不变。迁移：把 leaseMs 调到 ≥ 5000。
• tansr serve --legacy-v1 / TANSR_SERVE_LEGACY_V1 保留并标废弃（1.0.0 移除）：显式开启时输出恰一条结构化 warn 事件 server.deprecated_option（LOG_EVENT.serverDeprecatedOption；字段 option / env / source / deprecatedSince: "0.14.0" / removal: "1.0.0" / replacement: "approval.credential.submit" / replacementPath），未开启零条。/v1 直连面、/v2、/v3/* 本版零变化，只读窗口尚未开始。
• /api 观测模板中票据段占位统一为 :ticketId（wire 仍为 requestId），只改模板文本，路由匹配不受影响，无 wire 变化。
• 自托管 ServeCacheHost 的缓存热窗口与冷恢复更省（与 @tansr/sdk 0.18.1 同一改动）：每次缓存交换的原帧与在飞标记合为一次 SQLite 事务，准备之后、发送之前崩溃的请求不再留下耐久痕迹、不再恢复为 result_unknown；冷恢复接续时旧运行绑定读取与新运行心跳并行发出，任一失败即整体失败。装配面、错误码、帽值与 /v2 /v3 wire 零变化；已有缓存库无需转换。

修复

• 轮末 checkpoint 失败后会话 phase 不再永停 running：所有权已失（已被接管、释放、删除或记录损坏）时立即关闭驱动并发出 session.ended，接管方按其读到的状态恢复；其它错误（IO、锁、资源未落定等）由心跳拍在驱动空闲时有界重试（最多 3 次，新轮正在跑则留到下一拍），耗尽仍失败才关闭；两条在飞链互不等待，失败经 onStoreError 与结构化日志上报，不外泄为未处理拒绝。对你意味着：慢盘下不再出现「轮已完成但 phase 永停 running、接管者长时间挂起」的情形，以 phase === 'idle' 作稳定判据的宿主不再被挂起；关闭路径只复用既有 turn.error { errorKind: 'store_commit_failed' } 与 session.ended 帧，wire 不变。
• /v2/sessions 兜底 500 的结构化日志 kernel.server.request_unhandled 按真实方法与路径记录，创建请求（POST）的 500 不再被误记为列表请求（GET）；无 wire 变化。

本版 npm 包已于 2026-10-04 发布（与 @tansr/sdk 0.18.1、@tansr/cli 0.10.1、@tansr/api-client 0.3.0 同批）；导出名集不变（根入口 434 项 + ./extensions 98 项 + ./process 6 项），签名加法 3 处（AgentExecutionOptions、LOG_EVENT / LOG_EVENT_NAMES），行为收紧一处（leaseMs 下限）。如实披露：缓存宿主的性能目标在本版正式测量后仍未全部达成（每映射常驻内存增量仍无法判定达标；缓存局部 P95 增量 24.9 / 24.2 / 174.9 ms，允许 10 / 10 / 50 ms，较上版改善；同步压力档未达 2 倍线，不劣化；热窗口提交次数 2 → 1 成立），功能仍缺省关闭、显式 opt-in，目标值不改。

0.13.0(2026-10-02)

新增

• /api 统一调用面正式可用（合同 unified-v1）：装配了 /v2 面的部署自动在链首装配门面，除 /v1 外的 77 条旧路由各有 /api 对应物（manifest revision 6：11 族 / 80 操作 / 38 能力项），会话族经请求头 tansr-session-family 或部署首选族选择、路径不再区分族；领域载荷字节不变，/v2、/v3/* 响应逐字节不变。全部 /api/* 响应携 tansr-contract / tansr-manifest-revision / tansr-domain / tansr-schema-hash 四头；Idempotency-Key / If-Match / deadline 三个请求头本版已定义但不读取（0.14.0 起生效）。对你意味着：新集成只需读一份 GET /api/manifest 与一张路由表；旧前缀本版仍可用；响应缺 tansr-contract 头即该部署没有门面，应按「合同不可用」上报而不是猜旧版本回退。迁移：/v2/sessions/** → /api/sessions/**、/v3/sdk2/bindings/** → /api/archive/bindings/**、/v3/sdk2/cache/** → /api/cache/**、/v3/terminal*/** → /api/terminal/**，查询串里的合同修订标识照写；同一会话族只经一种前缀。
• 统一错误信封：/api 委托路径上 ≥ 400 的 JSON 错误统一为 { contract: 'unified-v1', traceId, requestId, code, status, retryAction, message, detail }，code 为 17 个映射码加门面自有的 precondition_failed（412）/ not_canonical（400）共 19 码，retryAction 取 none / same-request / query-status / rebind / refresh / rediscover 六值之一；原族码、状态与动作留在 detail.domainCode / domainStatus / domainRetryAction，detail.path 与 message 里的内部前缀改写回所请求的 /api 路径。例外：/api/archive/sync/:id 暂透传原信封。旧前缀错误体字节不变。对你意味着：一套 switch (code) 覆盖全部域；result_unknown / commit_unknown 只会给出 query-status 或 rebind。迁移：统一读 code，需要原码时读 detail.domainCode。
• 统一事件包络显式协商：请求头 tansr-event-envelope: unified-v1 在场时，/api/sessions/:id/events、/api/archive/bindings/:id/events、/api/terminal/executors/:id/events、/api/terminal/sessions/:id/tool-output 四条 SSE 路由逐帧把 data: 改写为固定 7 键 { contract, eventId, domain, type, cursorSet { eventCursor, archiveCoverage, outputWatermark, materialConsumed, ackReceipt }, terminalStatus, raw } 并回响同名响应头确认；eventId 即本帧 SSE id:（缺席为 null），不出 seq / payload，原事件对象只在 raw 携带一份，未知 type 照常进 raw；未携头或未回响 = 未协商，帧字节与旧前缀逐字节相同。对你意味着：五个游标位分离、不得互换；terminalStatus 取 null / accepted / completed / aborted / unknown，SSE 结束与 HTTP 202 都不是完成。迁移：新代码携头并按包络读；旧代码不携头零变化。
• 能力发现与会话级围栏：GET /api/manifest（含 runtime.installed）、GET /api/capabilities（部署级）、GET /api/sessions/:id/capabilities（closureId + 会话内各操作 enabled / disabled / unavailable 三态）；携 tansr-closure-id 的写操作与当前围栏不等答 412，越围栏答 403 / 404；会话作用域别名 /api/sessions/:id/{memory,configuration}。对你意味着：撤权、工具不可用、域未装配在调用前即可见，installed: false 与「无权」分开表达。
• 新增子入口 @tansr/serve/extensions（98 项）：全部为可信宿主显式装配的扩展，不改根入口、不改既有缺省行为，tansr serve 命令行不自动开启——归档宿主 createServeArchiveHost（security: 'trusted-single-application' 必填；挂 /v3/sdk2/**，门面别名 /api/archive/**）、归档同步 startServeArchiveSync、显式卸载宿主 createServeOffloadArchiveHost（客户端显式选 sessionContract: 'sdk2-offload-v1'，不支持 fork）、缓存宿主 createServeCacheHost（配置、密钥与签发器只在可信服务进程保存，不收终端 JSON）、持久介质 openSqliteArchiveSpool、共享事务 Store createTransactionalServeAgentSessionStore / createMysqlAgentSessionTransactionBackend（与 transactionalExecution 配对，与 execution.spoolFor 装配互斥）、记忆生命周期与发布介质 createPlatformMemoryLifecycle 及 createSqliteMemoryPublicationStore / createBlobMemoryPublicationStore / createTerminalMemoryPublicationStore、终端合同锚 TERMINAL_CONTRACT_SCHEMA_REVISION / TERMINAL_CONTRACT_SCHEMA_SHA256 与 clientToolDefinitionDigest。
• 新增子入口 @tansr/serve/process（6 项）：installProcessGuards / ProcessGuardOptions / ProcessGuardTarget / LOG_EVENT / ServeLogger 的窄出口，与根出口同一实现与日志词表，导入不装配 HTTP / 会话 / 平台运行时。自托管宿主把 import { installProcessGuards } from '@tansr/serve' 改为 '@tansr/serve/process' 可减少启动导入；根入口照旧可用，无需迁移。
• 根入口新增 18 项导出：显式远端执行档（AgentExecutionOptions / AgentExecutionPolicy / AgentExecutionAuthority / AgentExecutionStorage / AgentExecutionObservation / AgentExecutionObservationInput，经 createAgentSessionFactory({ platform, execution }) 接线；缺省限额全局 256 执行器连接 / 512 会话、每用户 16 / 8，越界 429 capacity_exceeded；远端 Shell 须应用授权、具名策略、设备执行后端与可信解释器确认四者同时在场；未配置 execution 的旧接入路径零变化）、可信宿主扩展（PlatformTrustedScope / PlatformTrustedExtensions / PlatformSystemConfiguration，只能由宿主代码登记，HTTP 不能提交可执行模块；beforeTool 只收紧，超时 / 异常 / 取消都不算允许）、空闲期配置（AgentSessionModelBinding / AgentSessionConfiguration / AgentConfigureRequest / AgentConfigureOptions / AgentConfigureResult / AgentConfigurationRejection / AgentSetModelResult / AgentSetThinkingResult；HTTP 面 GET / POST /v3/terminal/sessions/:id/configuration，门面别名 /api/sessions/:id/configuration，须启用 terminal: { contract: 'terminal-services-v1' }，changes 只含授权模型别名与 thinking，窗口不兼容要求显式迁移、不静默重建上下文）与 createServeLogger(sink, { level = 'warn' })（固定 10 s 窗口按事件分组限量，超出以 log.repeated 汇总、分组过多记 log.overflow，全部级别脱敏、有界）。
• 新增运维旋钮 TANSR_SERVE_LOG_LEVEL（缺省 warn）、TANSR_SERVE_SSE_MAX_FRAME_BYTES、TANSR_SERVE_AUTH_MAX_PENDING / TANSR_SERVE_AUTH_TIMEOUT_MS、TANSR_SERVE_LEGACY_V1，环境变量表由 31 键增至 36 键；新日志事件 execution.rejected / execution.result / log.repeated / log.overflow。

变更

• /v1 单租户面下线（对外契约变更）：装配了门面（options.v2 在场）的部署上 /v1/sessions*、/v1/status、/v1/approvals/:id/credential 缺省返回 404；disableV1 升为公开 StartServerOptions.disableV1（缺省 = 门面在场即 true；显式装配的归档 / 缓存宿主在场时恒关、不能重开），过渡旋钮 tansr serve --legacy-v1 / TANSR_SERVE_LEGACY_V1=1；不装配门面的部署保留 /v1。本版两处尚无 /api 对应物：GET /v1/status（探针改走 /readyz）与 POST /v1/approvals/:id/credential（接审批投递的 --v2 部署须显式 --legacy-v1，对应操作随 0.14.0 补齐）。对你意味着：健康检查改走免 Bearer 的 /healthz / /readyz，会话面改 /api/sessions（多租鉴权：Bearer + x-tansr-end-user）。迁移：确需保留 /v1 的门面部署显式 --legacy-v1；nginx / k8s 模板加 /api 分片。
• /v2、/v3/* 退役预告：自本版起定义为内部适配入口，本版不移除任何路由、不改响应字节；进入混用告警与只读窗口前会另出说明，1.0.0 移除外部入口，V2_ROUTE_TABLE 导出形保留。对你意味着：请在窗口内把客户端切到 /api；观测 route 标签以 /v2/、/v3/ 开头的样本即尚未迁移的调用。
• 根入口 33 项签名变化（全部为可选键 / 可选尾参 / 常量词表加法，零删除），不传新键即 0.12 行为，其中须注意：ServeRuntimeOptions 新增必填字段 logLevel（resolveServeRuntimeOptions 产物自带；自行构造该字面量的宿主须补上）；StartServerOptions.terminal? 显式启用 /v3/terminal/** 路由族（门面 /api/terminal/**，未配置时全部 404）；PlatformServeSessionFactoryOptions / PlatformAgentSessionOptions 加 trustedExtensionsFor? / systemFor? / memoryFor? / memoryPublicationFor?、四个查询护栏 temperature? / stopSequences? / maxToolRounds? / maxConsecutiveErrors? 与输出硬上限 maxOutputTokens?（原 maxTokens 自此是单次主查询的初始输出预算，缺省 8192，触帽后可在 maxOutputTokens 内升档）；V2SessionMetaView.applicationPrompt?（GET /v2/sessions/:id?include=applicationPrompt 显式请求才返回，不含正文；其它 include 值 400）；CreateServeAgentSessionStoreOptions.ownership?（同一可信主机多 Serve 进程共享会话目录，启用前须停旧单写者，跨主机须由具原子写围栏的 Store 提供）与 ServeAgentSessionStore 一组可选能力位（claimOwner? / runtimeCheckpoints? / attachmentCheckpoints? / attachmentSourceCheckpoints? / memorySelectionCheckpoints? / 配置三法 / recordUsageSnapshot?——声明某能力位即承诺其原子保存合同，不得伪造缺失状态；内置文件 Store 已全部实现，自定义 Store 不实现任何可选项即 0.12 行为）；CreateAgentSessionFactoryOptions.configuration? / execution? / transactionalExecution?（两种装配互斥）/ platform.onSessionArchived?；资源限界 AgentSessionsOptions.authentication?、SseOptions.maxFrameBytes?（有限值超界只断开该订阅）、EventRingBufferOptions.maxEventBytes?、AttachOptions.beforeFlush?；AgentSessionBridge.registerToolCall 加第 7 个可选参，并收紧为重复的在途 / 已终局 callId 再次登记即拒绝（此前会覆盖原挂起项）。CreateSessionBodySchema / PermissionReceiptSchema / CompactBodySchema 三项仅声明哈希变化，源声明与 wire 形零变化，消费方零迁移。

修复

• 执行路由的 connectionId 此前未经 Id 校验即进入处理，现按 Id 形校验、非法值答 400。

本版 npm 包已于 2026-10-02 发布（与 @tansr/sdk 0.18.0、@tansr/cli 0.10.0、@tansr/protocol 0.2.0 同批）；根入口导出集相对 0.12.0 由 416 项增至 434 项，另加子入口 ./extensions 98 项与 ./process 6 项，零删除。如实披露：缓存宿主所依赖的三项性能目标在发布时仍未达成——每映射常驻内存 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.12.0(2026-09-16)

新增

• 移动托管会话按平台应用的 tools.webFetch / tools.http 能力位装配网页抓取（WebFetch）与 HTTP 请求（Http）两个公网工具，缺省关闭；服务端显式配置的工具白名单只能进一步收窄，不能放宽。迁移：升级服务并在平台为应用开启能力后，新建会话或从存储重新装配会话才生效。

变更

• 托管的 Http 工具设有宿主私网访问上限，并禁止引用宿主环境变量里的凭据；WebFetch 沿用既有的出网规则与跨主机跳转审批，不绕过共享权限链。
• 默认文本日志补齐审批结果与有限的裁决诊断，不记录完整工具参数、用户内容或凭据；裁决超时仍回落为询问用户。

本版 npm 包已于 2026-09-16 发布（与 @tansr/sdk 0.17.0、@tansr/cli 0.9.0 同批）；导出集相对 0.11.0 零增删、零签名变化（仍为 416 项），0.11.0 及其 tag 保持不变。HTTP 路径与事件包络不变。

0.11.0(2026-09-15)

新增

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

变更

• 公开签名变化（契约 contract-v0.29）随 0.x 规则以 minor 发布；不传新字段零变化。HTTP 路径与事件包络不变。

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

0.10.0(2026-09-14)

新增

• 历史接口透传媒体产物：GET /v2/sessions/:id/history 的工具结果携 artifact，热 / 冷恢复与检查点一并保留，端侧恢复后可重建图像 / 视频 / 语音工具卡。HTTP 路径与事件包络不变；旧的纯文本历史不自动补媒体。

变更

• 含媒体产物的会话存储升为版本 2；旧版本程序不能继续写已升级的卷。迁移：升级前备份，并把写同一会话存储的 writer（tansr serve / 自托管 @tansr/serve / SDK 宿主）统一升级。

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

0.9.0(2026-09-14)

新增

• 非活跃会话的 lastSeq 返回真值：GET /v2/sessions/:id、GET /v2/sessions 列表项与 GET …/history 对不在内存的会话，lastSeq 自此为存储里落盘的水位（此前恒 0；旧卷无水位记录仍为 0，无元信息仍 404，活跃径不变）。对你意味着：客户端（含 Android / iOS）不得再以 lastSeq === 0 判「无事件」，请按值作 Last-Event-ID 续传起点；判休眠看 live: false。自实现存储读取器不回填该值时仍为 0。
• server.replay.gap 帧形态进入契约门：事件名、载荷键集与 reason 词表（'evicted' / 'ahead_of_log'）单一事实源，公共类型 ReplayGapNotice 字段与可选性不变；SDK 契约清单 MANIFEST.json revision 6 → 7（事件型表 54 → 55，新增的 session.events_dropped 为 SDK 专属事件，见下方说明）。
• TANSR_SERVE_HOST_SHELL=posix|powershell：权限引擎解析 Shell 命令的词法方言，缺席随平台（Windows → powershell，其余 posix），既有部署零改动；只改判定方言，执行器实际派生的 shell 仍随平台。库面同缝新增可选字段 hostShell?。
• 停机 closeAll 有界：StartServerOptions.closeAllTimeoutMs（缺省 5 000 ms；Infinity = 旧的无界等待）到点记一条 server.close_timeout 警告并继续停监听；closeAll() 返回 { timedOut, pending }。对你意味着：一个永不落定的会话泵不再能拖住整机停机；依赖「必等全部落定」的宿主显式传 Infinity。
• tansr serve 信号矩阵：SIGINT / SIGTERM / SIGHUP / SIGBREAK 首枚触发一次幂等有界 drain（预算 drainTimeoutMs + 15 s，到点记 process.hard_exit 后退出码 2），第二枚立即退出码 2；SIGHUP 独立紧急预算 ≤ 3 s。
• tansr serve --v2 建店接入存储告警：store_unknown_kinds / store_prefix_mismatch / store_pending_rewrite / store_seal_failed 以 warn 级复用既有 store.error 日志事件出线，不再静默；自托管 @tansr/serve 宿主可经 createServeAgentSessionStore({ onStoreWarning }) 接进自己的 logger。
• 会话级预算跨重启：带 init.budget 的会话每轮末随历史在存储里落一条累计用量快照（不进消息面 / 不进 SSE 历史页），resume 后自快照续算；快照落后于历史（进程在轮末快照前终止）时，resume 首连重放多一帧 server.platform.warning { code: 'usage_snapshot_stale' }（消息携落后数），只丢末轮用量、不静默低报。自实现存储需自行保存 / 返回 usageSnapshot 才能续算，否则退化为每次 resume 从 0 起算即此前行为。
• ServeSessionDriverOptions.toolResultBudget?：工具结果超帽时落会话目录 spill/ 全文、历史里存根替身，压缩前快照落 checkpoints/ 并签发 session.checkpointed；tansr serve / tansr acp 自此与 TUI / headless 同款接线，不传者零变化。

变更

• resume 后的 seq 不再从 0 起：新纪元起点 = 存储里落盘的水位 + 1（正常关闭封印的会话恰为 lastSeq + 1，旧游标 Last-Event-ID 续传零 gap；异常收口 / 旧记录取 max(lastSeq + 1, now − createdAt 毫秒) 守卫地板）。旧游标早于起点 → gap reason: 'evicted'；Last-Event-ID 缺席恒全量重放。POST /v2/sessions 的 resume 响应 lastSeq 由恒 0 变为新纪元水位（客户端 L3 恒弃游标经 history 重建，不读该值）。对你意味着：多设备 / 冷启动持旧游标重连不再必然重建。自实现存储可选实现 recordSeqWatermark（缺席 = 不封印、按守卫地板起新纪元，仍安全）。
• SSE 有界写：maxSubscriberBufferBytes（缺省 2 MiB）自此同时是每次 socket 写的字节上界——attach 重放段分片交付、突发批量分片写出，帧文本与顺序逐字节不变、小流量零分片。曾依赖「非 paused 期队列无界」吞下超 2 MiB 突发的慢客户端，此后可能被判慢消费者并按 Last-Event-ID 重连重放。
• 音频直连两端点的错误信封：平台上游 401 / 403 / 5xx 与网络故障归一为 503 upstream_unavailable 固定词条 + Retry-After，上游状态与原文只进结构化日志事件 upstream.rejected；业务 4xx（asr_not_configured、insufficient_balance 等）维持原码透传。对你意味着：端侧不再因平台侧 401 误判本地令牌失效；此前依赖 403 model_not_authorized / 502 原样到端的调用方改读日志。
• tansr serve 每轮墙钟缺省 30 分钟：TANSR_SERVE_TURN_WALL_CLOCK_MS 缺席 = 1 800 000 ms，显式 0 = 停用（不再被判为非法值告警）。此前缺省无墙钟，一轮可无限期占用会话并发槽；单轮预期超过 30 分钟的部署需显式设更大值或 0。仅 tansr serve 装配面，库 startServer 不受影响。
• 会话预算账本按行归账（contract-v0.27）：带 init.budget 的会话按每一行的（供应商，模型）取能力位 quirks.reasoningTokens 处置思考 token——'separate' 行的思考量并入该行输出计量与计价，缺省 'subset_of_output' 照旧不叠加；会话内切换模型与子代理另选模型各按自身能力位。当前内置表零 'separate' 行，已部署会话的用量与金额逐字节零变化。
• 客户端申报工具（clientTools）不受内核中央入参校验影响：本地 schema 只是申报投影，调度器不剥参、不改权限 digest 输入，坏参仍由既有路径以 tool.completed { isError: true } 出线。无需迁移。

修复

• TypeScript 成品声明可直接检查：index.d.ts 移除误混入的 createRequire 运行时垫片，未开启 skipLibCheck 的 NodeNext 消费方不再遇到 TS1046 / TS1254；运行时与公开类型签名不变，无需迁移。
• 内置文件存储：带预算的会话卷因尾部含用量快照记录而退出「尾部纯消息」快路、GET /v2/sessions/:id/history 对大卷全量读的问题已闭合——按提交链尾的见证取消息数，快照记录自然跳过；只有无可信见证的旧卷或被外部写者动过的卷仍退全量读以求精确。结果恒不变。
• /v1 优雅关闭期的 retry: 帧经 writer 记账，sseStats().frames / writes 自此计入；行为不变。

本版 npm 包已于 2026-09-14 发布（与 @tansr/sdk 0.14.0、@tansr/cli 0.7.0 同批）；导出集相对 0.8.1 由 404 项增至 413 项，零删除。SDK 专属事件 session.events_dropped（contract-v0.27）只在 @tansr/sdk 进程内事件积压越界时出现，@tansr/serve 恒不发出、不进 /v2 事件流 / 重放窗 / journal，客户端无需为它写分支。

0.8.1(2026-09-11)

变更

• 统一系统媒体工具与平台提供方的说明，明确移动端媒体工具在会话服务执行，用户主动转写 / 朗读与模型工具调用分别保留。
• 同步 SDK 媒体说明修正；不改变会话协议、能力授权、媒体产物、工具执行或计费行为，不新增公共导出。

0.8.0(2026-09-10)

新增

• /v2 新增输入能力发现、严格同轮文本投递与状态查询接口，绑定会话、历史代际和目标轮；旧 messages 接口保持兼容。
• ServerHandle.settleResources() 可等待真实资源收尾，与原有关闭及业务排水分开。
• 应用系统提示词按平台 fallback / prepend 策略与 platform.system 组合；platform.systemAppend 追加宿主说明。Android / iOS 仍通过 /v2 发送普通用户消息，不新增客户端 system 入口；后续新一轮前刷新平台提示词与策略，当前执行轮固定，历史保留。需要配套 API 与 serve 版本。
• 就绪帧 TANSR_READY {json} 与 /readyz 探针(/healthz / /readyz 在 CLI 入口始终开启);建会返回 429 / 503 时携 Retry-After。部署件探针建议由 /healthz 改为 /readyz。
• 会话保留期:sessions.retention{ maxAgeDays, maxPerEndUser, maxBytes } 与 store.sweepRetention;环境变量 TANSR_SERVE_SESSION_MAX_AGE_DAYS / TANSR_SERVE_SESSION_MAX_PER_END_USER;保留天数可按组织在平台配置的值生效,缺省 30 天。
• 轮末 webhook 出站:环境变量 TANSR_SERVE_NOTIFY_URL / TANSR_SERVE_NOTIFY_SECRET,tansr serve --v2 进程可直接发送;签名双版本 x-tansr-signature: v2=…, v1=…,可配 webhook.signatureVersions;导出 signWebhookDelivery。
• 指标暴露独立开关 TANSR_SERVE_EXPOSE_METRICS;就绪帧输出流选择 TANSR_SERVE_READY_STREAM;运维环境变量以当前公开表为准,.env.example 与 README 由表生成。
• 新导出:installProcessGuards 一族、V2_ROUTE_TABLE / V2_SESSION_ACTIONS、就绪帧解析与格式化函数、ReplayGapNotice.reason、PermissionReceiptSchema.reason、AgentSessionFactory.sweepRetention、AppTokenMinter.invalidate、SECRET_WARNING_VALUE 等(均为可选,缺席即现状)。
• 新指标 tansr_serve_pump_errors_total / tansr_serve_token_invalidations_total{reason};新日志事件 process.unhandled_rejection / process.uncaught_exception / process.drain_failed / store.error / session.retention_swept / bridge.permission_receipt。
• tarball 随附 NOTICE(内联第三方依赖的名称、版本与许可文本)。

变更

• 丢失输入响应后先查询原输入状态，不通过隐式开启新轮重试；当前只支持文本与内存 ACK。
• 手机重连原会话后，下一显式新轮自动刷新平台提示词；轮中追加不刷新 system，也不改变权限、预算和会话归属。
• 同一 sessionId 并发建会,后到者返回 200 并附着到已有会话(此前触发 500 并可能留下未处理拒绝)。
• /v2 错误信封的 message 改为固定文案,原始错误(含服务器本机路径)只进结构化日志;依赖 message 原文判因的客户端请改读 error.code / detail。
• /v2 事件泵抛错即关闭驱动(driver.status() 为 'ended'),不再静默挂起。
• 恢复会话时的工作目录默认取存储值('stored')并重过策略闸,被拒返回 409 cwd_unavailable(detail.reason 四值);TANSR_SERVE_CWD_ON_RESUME=current 可显式回到旧行为。
• 会话落盘失败不再只进日志,改以可恢复的 turn.error{ recoverable: true, scope: 'server.persistence' } 出线;端侧按 recoverable 位区分咨询与失败。
• 客户端超前订阅(afterSeq 大于日志末序)也会收到 gap 帧,reason 为 'ahead_of_log'。
• 控制帧一律携 ts;server.tool.request / permission.request / question.request 携 ttlMs;权限请求的应答(PermissionReceipt)可带 reason(目前仅 expired_on_arrival)。
• 指标与日志的 route 标签值集按当前公开路由表变动,仪表板与告警请随动。
• 缓存的应用令牌收到 401 且属失效码时自动逐出、重铸并重试一次;失效码集与 SDK 同源。
• bundle 缓存键改为四维(基址 / 应用 / 径别 / 能力位);自实现 bundle 缓存的宿主请按四维键对齐。
• 裁决装配与 SDK 同源:未接确认通道且裁决人未授予资格档的会话不再切换到 auto 模式,工作区内写 / 删改为征求确认(无通道即拒绝);机器放行帧 tool.permission.decided 经既有通道出线。
• 会话文件存储切到统一内核实现;应急开关 TANSR_SESSION_STORE_CORE=legacy(一版后删除)。
• 库内不再自行挂载进程级兜底;自托管 @tansr/serve 的宿主须在入口调用 installProcessGuards(tansr serve 已内置),否则未处理拒绝按 Node 缺省行为崩溃(与 0.6.x 相同,无回归)。

修复

• 服务关闭时保持原有 readiness 语义并拒绝新建会话；真实资源等待保留旧句柄的兼容边界。
• 分叉会话读历史分页时 total 偏 1 导致翻页漏项。
• 运行时外部依赖声明与实际打包一致(zod),包内说明文字同步订正。

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

0.7.0

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

0.6.1(2026-09-06)

新增

• 存储出口补齐:createFsBlobStore / createChaosBlobStore / runStorageConformance 及相关类型经 @tansr/serve 再导出,第三方适配器不再需要直装内核包。

无其他行为变化。

0.6.0(2026-09-06)

新增

• /v2 会话持久化:会话存储、分叉与恢复。
• 权限裁决姿态与裁决协议 v4 / 应用协议。
• 音频模态与媒体能力内核化。
• 套餐(plan)信息在端上可见。

变更

• MCP 重连契约升级(v0.21–v0.24)。

工程变更原文(CHANGELOG)

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

发版门(scripts/release/gate.mjs,十王修案 FX-C-25)③ 步要求:每个发布版本在此有 ## <version> 段且段体非空; ④ 步以 packages/server/exports.snapshot.json 与上一 tag 比判 semver——0.x 期任何导出集变化(增 / 删 / 签名变)至少 minor,patch 不得携新导出 (doc/89 §3.3「0.x minor = breaking」)。发版回执落 doc/release/serve-<version>.md;无回执无 tag(tag 形 @tansr/serve@<version>)。 0.6.x 及更早版本为追溯登记(当时无本文件;本文件由十王修案第五波 C-γ「CHANGELOG 三包就位」建立,不发版)。

面向 serve 宿主(自托管 @tansr/serve 库 / tansr serve 运维方 / tansrd 池)的公共面变更登记:公共导出(packages/server/src/index.ts)、 /v1 · /v2 HTTP 面、进程协议帧、运维旋钮(SERVE_RUNTIME_ENV 表)、指标 / 结构化日志事件、webhook 出线形。kernel / sdk 内部改动不入此表 (sdk 面见 packages/sdk/CHANGELOG.md)。版本号 = packages/server/package.json(包目录 server,发布名 @tansr/serve); 每条写「变了什么 · 对你意味着什么 · 迁移方式」。0.6.0 之前的历史见 git(git log -- packages/server)。

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

MODEL-ROLE 发行准备：本段描述候选源码，尚未发布到 npm。公开 @tansr/serve@0.15.1 于2026-10-10发行，不含后续模型角色和主备独立策略；升级平台管理配置不能替代升级实际 Serve 运行物。

• 平台会话装配协商 adjudicator-policy-slots-v1，复用共同 SDK／kernel 消费 App 有效主备模型与每槽档位、预算、升级处置。仅原可信零出站故障可切合法备用；否决、预算尽、未知受理和已输出不换备。保留宿主询问姿态、权限硬边界与同引擎累计预算。
• 复用已协商双槽会话的合法配置恢复，保留原权限引擎预算，显式关闭不复活；Task 在裁决关闭或没有可用裁决配置时不再借父主模型继续机器裁决，原人工询问通道仍保留。撤权后结算已发生用量时，按实际请求模型归属，避免记到配置刷新后的另一模型。
• 纳入已合主线的持久化公开加法：会话事件日志快照、冷材料耐久覆盖，以及 ./extensions 中的共享归档、MySQL预算／命令存储、冷存储索引与维护。自定义 Store／后端实现须对照随包声明重新类型检查；这些显式宿主能力不因更新包自动启用，也不改变冻结远端执行合同。
• 相对正式0.15.1的已提交根／子入口快照有79项新增、17项签名变化，原0.x导出门要求minor；最终差集由冻结候选的原构建及exports门确认。原生各语言客户端仍经HTTP连接Serve；本次不要求它们复制本地TS裁决实现，实际能力由所连Serve运行物决定。
• 旧前缀行为保持： 本版默认 legacyPrefixes 仍为 readwrite。0.15.0历史发行说明曾计划0.16.0改为readonly，本次模型角色与消费修复不执行该协议迁移；显式readonly／off选项沿原合同。后续退役动作须单独按原兼容与授权边界实施。

0.15.1 — 2026-10-10

REL-FULL-20261010：纳入公开 0.15.0 之后已合主线的 Go、Rust 与 C++ 消费修复，发布状态以本版发行回执为准。

• 首次设备绑定解除对尚未建立 capability 的循环前置，继续由原身份、平台与策略授权决定可执行能力（GO-01）。
• 业务工具沿原设备执行链支持受控实时输出，并保留工具既有的默认执行超时；不向 Serve 宿主回落执行（RUST-03）。
• 修正统一错误状态与重试动作的合同映射，未知审批错误保留原错误语义（RUST-02 / RUST-03）。
• 检查点恢复先结算已消费的材料，保持未消费及仍持有的材料约束；原材料生命周期与来源 ACK 不被绕过（CPP-04）。
• 旧前缀窗口默认仍为 readwrite，不提前启用 0.16.0 的 readonly 计划；不纳入未合主线的 persistence 开发内容。

0.15.0 — 2026-10-06

「0.15.0 车」(REL-0.15.0;UAPI 方案 §0 D51,用户 2026-10-06 18:33「发车」;冻结 2026-10-06;发布状态以 doc/release/serve-0.15.0.md 回执为准)。本车 = 迁移报告 §3.4 / §3.5 的服务端动作(同会话跨前缀混用告警 + 旧前缀退役窗口旋钮 + 机器可读退役头)与 @tansr/api-client 0.4.0 冻结入口缺省切 /api 同车(D36 一版间隔:本版旋钮缺省 readwrite,0.16.0 缺省 readonly,1.0.0 移除)。版本号按 gate ④ 口径 minor:导出名集仍 434(根)+ ./extensions 98 + ./process 6,签名加法四处(StartServerOptions 新增两可选键、ServeRuntimeServerOptions Pick 同步、ServeRuntimeEnvStringFormat 加 'http-date'、LOG_EVENT 两新事件)→ 根 +0 / −0 / ~4、./process ~1(LOG_EVENT),所需 minor、实际 minor。/api 面、manifest(r7)、旧前缀响应体零变化;旧前缀响应头是有意例外(第二条)。

• 旧 /v2 /v3/* 前缀退役窗口旋钮 StartServerOptions.legacyPrefixes?: 'readwrite' | 'readonly' | 'off'(缺省 readwrite;环境 TANSR_SERVE_LEGACY_PREFIX,SERVE_RUNTIME_ENV legacy 组)与 legacyPrefixSunset?: string(TANSR_SERVE_LEGACY_SUNSET,HTTP-date 或 ISO-8601;缺省不发 Sunset)(packages/server/src/api/legacy-window.ts,http-server.ts 在 dispatchLegacy 前一行接线):只在门面在场(options.v2)时装配,SDK1-only 部署零变化。readwrite(本版缺省)= 旧前缀全部受理,体与状态同 0.14.0;readonly = manifest kind: write 的 38 个操作在旧前缀答 410 gone 统一信封(contract: unified-v1、code: gone、retryAction: rediscover、requestId: null、detail: { domainCode: legacy_prefix_retired, mode, route, operation, apiPath },tansr-contract: unified-v1 头在场;message 指向对应 /api 操作),read(39)/ stream(4)仍受理,manifest 未登记的旧路径不拒;off = 旧前缀全部 404 not_found 统一信封(1.0.0 形预演)。非法值 → startServer 抛 TypeError(环境变量非法值按既有律 warnings 提示并忽略)。对你意味着:本版升级无行为变化;要提前演练只读窗口的部署设 TANSR_SERVE_LEGACY_PREFIX=readonly 并看 api.legacy_prefix_rejected;回滚 = 改回 readwrite,无数据变化。迁移:0.16.0 缺省将改为 readonly,请在此前用 route 标签把 /v2/… /v3/… 的写流量清零(迁移报告 §3.5 验证列)。
• 旧前缀响应附 Deprecation / Link / Sunset 头(RFC 9745 / 8288 / 8594;对「旧前缀逐字节不变」纪律(方案 §7 ②)的有意例外,迁移报告 §3.5 已预告):门面在场时 /v2、/v3/* 的每个响应(含 SSE、含 readonly / off 的拒绝)附 Deprecation: @1790900340(= 0.13.0 公告退役的时刻 2026-10-02T00:19:00Z)与 Link: </api/manifest>; rel="deprecation";设置 legacyPrefixSunset 后再附 Sunset: <IMF-fixdate>(1.0.0 计划日待拍板,本版不内置日期)。readwrite 下响应体与状态码逐字节不变;/api 响应不附这些头。对你意味着:旧前缀客户端若有「未知响应头即拒绝」的律须放行这三个标准头(@tansr/api-client 0.3.x / 0.4.0 均忽略);旧链回归卷断言体与状态,不断言头集。迁移:无。
• 结构化日志两新事件(LOG_EVENT.apiLegacyPrefixMixed = 'api.legacy_prefix_mixed'、LOG_EVENT.apiLegacyPrefixRejected = 'api.legacy_prefix_rejected',warn;LOG_EVENT_NAMES +2):同一会话 id 先后经 /api/sessions/:id/** 与 /v2/sessions/:id/** / /v3/sdk2/sessions/:id/** 访问时记一条 { route, family: 'api' | 'v2' | 'v3', from, to }(按会话 id LRU 4096 条,每次切换记一次;迁移报告 §3.4「本步不拒绝」,readwrite 下只留痕);readonly / off 下每个 method route 模板首次被拒记一条 { route, method, mode, status }。对你意味着:两事件计数为 0 持续一个观察窗(建议 ≥ 一个发布周期)= 可进 0.16.0 缺省 readonly 的证据。迁移:无。
• SERVE_RUNTIME_ENV 36 → 38 键(上两键;pnpm env:example 再生 packages/server/.env.example 与 README 表,deploy/serve-v2/.env.example / README 同步注释行与两表行)。ServeRuntimeEnvStringFormat 加 'http-date'(TANSR_SERVE_LEGACY_SUNSET 非法日期 → warnings 提示 HTTP date (IMF-fixdate) or ISO-8601 timestamp,忽略该键)。

0.14.0 — 2026-10-04

「0.14.0 批」(USDK-11;UAPI 方案 §0 D23,冻结 2026-10-04;发布状态以 doc/release/serve-0.14.0.md 回执为准)。本段由 SRV-OWNER-01 / CI-FLAKY-TRIAGE-01 / U7-HDR / U7-OPS / PERF-01 (c)(d) 五批候选登记合并,各批引言保留为事实;版本号按 gate ④ 口径定为 minor:导出名集仍 434 项(根)+ ./extensions 98 + ./process 6,签名加法两处(AgentExecutionOptions.memoryFor() 返回键 deviceIoBudgetMs?;LOG_EVENT / LOG_EVENT_NAMES 新增 serverDeprecatedOption),行为收紧一处(leaseMs 下限 1000 → 5000),/api 操作加法 r7。导出集相对 @tansr/serve@0.13.0(tag → 29a21769)的实测差量(gate ④,冻结日重建 dist 再生快照与仓内一致):+0 / −0 / ~3(AgentExecutionOptions / LOG_EVENT / LOG_EVENT_NAMES 三项 signatureHash),所需 minor、实际 minor(读数登记于 doc/report/USDK-11-发行执行单-2026-10-03.md §4)。

SRV-OWNER-01(2026-10-02;对抗审查已过,无阻断项,12 条非阻断建议的处置见 doc/report/SRV-OWNER-01-所有权租约续约解耦-2026-10-02.md §8)。只动显式 ownership 模式的会话所有权租约语义与装配,tansr serve --v2 生产路径(未启用 ownership)零变化;公共导出集无变化(exports.snapshot.json 再生一致 434 项,新符号均内部);单看本批本可为 0.13.1,与下文签名加法同车故为 0.14.0。

• 会话所有权租约不再因慢 IO 自判失效(CreateServeAgentSessionStoreOptions.ownership):此前 owner 的续约 renew() 与过期判定 current() 都排在同会话持久队列之后,且 current() 先判 expiresAt <= now 再放行——会话目录介质一次 fsync 持续到 ≈ leaseMs/10 时(缺省 30 s 租约 ≈ 3.5–5 s、旧下限 1000 ms ≈ 150 ms),活着的 owner 在一连串慢 fsync 排队后把自己判死,表现为创建 500、轮中 turn.aborted、或轮末 phase 永停 running。改为:owner 自身操作只按代际围栏(ownerId/claimId/attempt/host/released)判定,不看 expiresAt;expiresAt 只决定他人接管资格;owner 的每次持锁 meta 写(beginTurn/checkpoint/commit 等)顺带前推 expiresAt(活动即续约)。对你意味着:启用 ownership 的可信宿主在病态慢盘上不再出现「无对手却自判死亡」的会话不可用;独占性仍由文件锁 + 代际围栏保证,接管方与活 owner 不会双写(接管必然改写 claimId/attempt,旧 owner 下一次持锁操作即 owner_stale)。边界须知:(a) 事件泵的逐帧 fence 只核验代际、不写 meta、不前推 expiresAt,纯流式一轮里续约仍靠排队中的心跳 renew(),接管窗口 = 续约落地间隔而非一次写——在病态慢盘上,活 owner 可在轮中处于「expiresAt 已过、可被接管」状态数秒;带 runtimeRecovery 的多 Serve 部署此时可能合法接管并 fence 掉仍活的 owner(活性损失:旧 owner 后续操作 owner_stale、在飞模型调用重复;非双写),该窗口在此前版本即存在,本版只增加续约来源、未放宽接管资格;(b) 本条只覆盖文件实现——createTransactionalServeAgentSessionStore(共享事务 Store)的 owner 仍按 DB 时间自判过期(agent-session-transaction.ts 的 current():expiresAt <= tx.now;assertCurrent:now() >= expiresAt),且只有 renew() 一种续约来源,不享本条自愈,两实现目前没有共同的 ServeSessionOwner 合同测试;本版对它只同步下限(下一条)。迁移:无;行为更稳,API 形不变。
• leaseMs API 下限 1000 → 5000(ServeSessionOwnershipOptions.leaseMs,文件与共享事务两实现同步):下限只需覆盖「心跳一拍 + 一次持锁持久写的排队与落盘」,5000 ≈ 10 × 受压宿主 fsync 尾延迟,是实测不误接管的最小量级。对你意味着:显式传 leaseMs 在 1000–4999 的装配将抛 TypeError(此前接受);缺省 30000 不变,[5000, 300000] 内不变。迁移:把 leaseMs 调到 ≥ 5000(多数宿主本就用缺省 30000;测试夹具已随改)。
• 轮末 checkpoint 失败后 phase 不再永停 running:所有权已失(owner_stale 已被接管/释放/删除、owner_corrupted 记录损坏)→ 立即 fail-closed 关闭驱动(session.ended,此前同场景是报错后继续、后续轮的 checkpoint 链被毒化),接管方按其读到的状态走 reconciliation / runtimeRecovery;其它错误(IO/锁/资源未 settle,以及 initializeConfiguration 因首个稳定点未落地抛出的 reconciliation_required——它不等于所有权失守)→ 由心跳拍在驱动空闲时有界重试(≤ 3 次;新轮正在跑则留到下一拍,不丢弃),耗尽仍失败才关闭。心跳续约与该重试是两条互不等待的在飞链,重试挂起(资源 settle 未归)不会拖停续约;任一链自身的拒绝都被接住并经 onStoreError / 结构化日志上报,不外泄为 unhandledRejection。对你意味着:慢盘下不再出现「轮已完成但 phase 永停 running、接管者 90 s 挂起」的签名;以 phase==='idle' 作稳定判据的宿主不再被挂起;新增的关闭路径只复用既有 turn.error{errorKind:'store_commit_failed'} + session.ended 帧,wire 不变。
• 兜底 500 日志按真实方法/路径记录(/v2/sessions 发布水位屏障):replayReady 的未处理错误此前恒记为 GET /v2/sessions(字面量),创建请求(POST)的 500 被误记成列表请求。改为按实际 req.method/路径记录。对你意味着:结构化日志 kernel.server.request_unhandled 的 method/path 字段对这条路径不再误导;无 wire 变化。

CI-FLAKY-TRIAGE-01(2026-10-02)。一处公共导出签名加法:AgentExecutionOptions.memoryFor() 返回对象新增可选键,exports.snapshot.json 中 AgentExecutionOptions 的 signatureHash 再生(导出名集合不变,pnpm exports:check 绿)。0.x 期按 gate ④ 口径签名变化至少 minor,本版 0.14.0 据此定。

U7-HDR(2026-10-03;UAPI-01;方案 §0 D27 用户授权代拍)。/api 门面委托径新读三个请求头,旧前缀 /v2 /v3/* 零变化;公共导出集无变化(exports.snapshot.json 再生一致 434 项;request-headers.ts 不进包入口)。手册 §16.4 已随改;报告 doc/report/UAPI-三头接线-2026-10-03.md。

• /api 请求侧三头接线:Idempotency-Key / If-Match+ETag / deadline(packages/server/src/api/request-headers.ts,facade.ts 委托前一行调用):语义只按 RFC-UAPI-1 §1.2 既定文本实现,错误码不新增(19 码表既有码 + detail.reason 细因)。Idempotency-Key(ASCII 1–128,仅写操作)→ 门面鉴权后映射到各域 requestId(SDK2 / recovery / cache 族 request.requestId、terminal 族顶层 requestId 缺席时填入并 canonical 重编;在场且不等 → 409 conflict / request_id_conflict;/v2 族按请求指纹去重);同键同义返原回执、副作用恰一次,同键异义 → 409 conflict(reason: idempotency_key_reused),同键在飞等首请求落定,首回执不可保留 → 503 result_unknown / query-status(reason: receipt_not_retained);回执缓存进程内有界:每用户 256 条(= V2_LIMITS.receiptTombstones)/ 全局 4096 / TTL 10 分钟,按 endUserId + 操作名 + manifest revision 隔离。ETag:有版本资源(档案绑定 / 档案状态 / 绑定目标、缓存 binding、终端配置、记忆)的 2xx JSON 响应派生 "<revision>",无版本资源不伪造;If-Match: "<revision>" → 该域 expectedRevision(体内缺席填入、不等 → 412 precondition_failed),域以 binding_conflict / stale_revision / revision_conflict 拒绝 → 统一改出 412 precondition_failed(retryAction: refresh,原码留 detail.domainCode,reason: if_match_stale),一字未写;不适用 / 弱校验器 → 400 invalid_request。deadline(RFC-3339)到达时已过期 → 408 invalid_request(none,reason: deadline_exceeded),不受理、不触及下游、不占幂等窗。三头需要体时请求体帽 1 MiB(超 → 413 payload_too_large,reason: header_body_limit)。对你意味着:不携这三个头 = 行为逐字节不变;携 Idempotency-Key 的请求门面会先鉴权一次(域 handler 再鉴权一次,与 tansr-closure-id 同律);412 precondition_failed 现在既可能是围栏陈旧(closure_stale / rediscover)也可能是资源版本陈旧(if_match_stale / refresh),按 detail.domainCode 区分。迁移:无。待并入:VERSIONED_RESOURCES / REQUEST_ID_PATHS 两张按操作名的映射表并入路由表 / manifest 操作目录;unified-v1.schema.json 的 detail.reason 枚举、precondition_failed.retryAction、FacadeCode 随 revision 7 再生补齐(本泳道不改 manifest)。

U7-OPS(2026-10-03;UAPI-01;方案 §0 D26 / D28 / D34 用户授权代拍)。统一 /api 操作加法 + manifest revision 6 → 7 + 三头事实并入 manifest;旧前缀 /v1 直连面、/v2 /v3/* 零变化;公共导出名集不变(434 项;api/** 不进包入口),唯一签名加法:LOG_EVENT / LOG_EVENT_NAMES 新增 serverDeprecatedOption = 'server.deprecated_option'(exports.snapshot.json 该两项 signatureHash 再生,pnpm exports:check 绿)。报告 doc/report/UAPI-操作加法与manifest-r7-2026-10-03.md。

• /api 新增操作 approval.credential.submit(POST /api/approvals/:id/credential,会话域,写;T-K11 审批凭证回执,计划 §四 32):内部适配 /v1/approvals/:id/credential——manifest 操作目录中唯一的 /v1 内部路径(generate-manifest.mjs validateOperations 单点放行,其余操作恒 /v2 /v3)。只由门面委托进入(http-server.ts 门面专用委托,不进 dispatchLegacy),鉴权 = 多租 Bearer + x-tansr-end-user;体 { digest, verdict: approve|deny, approver }(RFC-K11 §3.2);200 { challengeId, result: "accepted" };拒绝经统一信封:unknown_challenge → 404 not_found、expired → 410 gone、digest_mismatch / already_resolved → 409 conflict(detail.submitCode 留原 SubmitCode);approvals 缝未接线 → 404 capability_unavailable(不泄漏端点存在性)。围栏(closure.ts)登记为 independent:挑战有自己的寿命,不随会话关闭而禁用。对你意味着:接审批投递的 --v2 部署不再需要 --legacy-v1;/v1 直连面仍返 approval_<code> 文本码,逐字节不变。迁移:投递方把回执目标改到 /api/approvals/:id/credential。

• D26 票据段占位统一 :ticketId:/api 观测模板中票据段占位由 :targetId 改口 :ticketId(wire 仍为 requestId,内部 /v2 /v3 模板占位仍 :targetId);archive-sync 入口占位改口 :id。只改模板文本,路由匹配按占位位置、不看占位名,无 wire 变化;API_ROUTE_TEMPLATES 与 manifest apiPath 同步。

• manifest revision 7(packages/server/contract/api-manifest.json / manifest.generated.ts,全部加法):① 操作 approval.credential.submit;② archive-sync-v1 族改用独立 doc/rfc/archive-sync-v1.schema.json 源指纹,sdk2-cache-v1 / sdk2-cache-core-v1 两族增手写消费方指纹门(cache-wire.ts / cache-core-wire.ts 头注 SHA 与源同值,--check 核);③ 三头事实并入:每条操作新增 etagPath: KeyPath | null(2xx JSON 体内资源版本键路径,派生 ETag)与 expectedRevision: { path: KeyPath, kind: sequence|integer } | null(If-Match 映射目标,只允许登记在写操作),每个族条目新增 requestIdPath: KeyPath | null(Idempotency-Key → 体内域 requestId 位;agent-session-v1 / archive-sync-v1 为 null,不伪造)——生成器 VERSIONED_RESOURCES(16 条:档案 6 / 缓存 6 / 终端 4)/ FAMILY_REQUEST_ID_PATHS(11 族)为盘点源,--check 核键集与读写约束;request-headers.ts 的 VERSIONED_RESOURCES / REQUEST_ID_PATHS 改为只读生成物派生(导出名与形不变,行为逐字节不变,U7-HDR「待并入」项结清)。GET /api/manifest 响应随之多出这三键(加法;tansr-manifest-revision: 7)。对你意味着:消费方可从 manifest 直接得知哪些操作有 ETag / 接受 If-Match、各族幂等键落在体内何处,不必读源码;旧消费方忽略新键即可。

• unified-v1.schema.json 随 r7 补齐(schemaSha256 随改;golden 同步):ManifestFamily.requestIdPath、ManifestOperation.etagPath / expectedRevision(新定义 KeyPath;读 / 流操作 expectedRevision 恒 null 的 allOf 约束);UnifiedErrorDetail.reason 枚举 2 → 17(+ 三头 15 细因 idempotency_key_* / receipt_* / if_match_* / deadline_* / header_*),detail.limitBytes 登记;UnifiedError 的 precondition_failed 允许 retryAction: refresh(If-Match 资源版本陈旧)与 rediscover(围栏陈旧)两值;FacadeCode 维持 8——三头拒绝信封携 requestId / detail.domainCode,形同域错误,按 UnifiedError 校验(U7-HDR 报告 §8.2 建议落定)。golden 正例 unified-error-if-match-conflict 由 RFC 构造形(conflict/412)改为 U7-HDR 真实形(precondition_failed/412/refresh/if_match_stale),新增 unified-error-idempotency-key-reused 正例与 3 条 manifest r7 字段负例。

• D34:tansr serve --legacy-v1 / TANSR_SERVE_LEGACY_V1 0.14.0 保留并标废弃,1.0.0 移除(实现与文案在 packages/cli,见根 CHANGELOG.md 0.10.1 段):显式开启时新增结构化 warn 事件 server.deprecated_option(LOG_EVENT.serverDeprecatedOption;字段 option / env / source: flag|env / deprecatedSince: "0.14.0" / removal: "1.0.0" / replacement: "approval.credential.submit" / replacementPath),恰一条、未开启零条。前一泳道提交 1d84fa84 的「删 --legacy-v1」只改了 tansrd 池参数(POOL_SERVE_FACE_ARGS = ['--v2']),CLI 解析与效果从未移除,本段为其纠偏登记。

• 绑定设备记忆每轮 IO 预算可由可信宿主显式配置(memoryFor(scope).deviceIoBudgetMs?: number):此前每轮设备记忆读取(M0 / 导入 / M1 / M2 / paths 主题)的累计 IO 窗口固定 10 s(USDK-08),窗口计时的是整段远端读取——含 Serve 自身耐久派工 / 回执落盘与两次 HTTP 往返——慢介质或高 RTT 设备上 ≈ 25 次串行读取即可耗尽,产品按设计降级本轮(memory_source_partial,召回不进本轮)。改为:缺省仍 10 000 ms、行为逐字节不变;可信宿主可在 memoryFor() 返回里显式给整数 1 000–120 000 ms,越界在准备屏障按 invalid_request(400)拒绝、零设备派工。人审等待仍不计入窗口;超预算仍只降级本轮不中断轮次。对你意味着:只在你明确知道设备介质 / RTT 慢于缺省假设时放宽;它不是权限、不授予读取。迁移:无;不传 = 原行为。README「绑定工作区记忆」节已随改。

PERF-01 (c)(d)(2026-10-03;报告 doc/report/PERF-01-CD-耐久点合并与冷恢复加法-2026-10-03.md)。ServeCacheHost 与 runtime-continuity.ts 经同一 @tansr/providers 路径(twp/cache-client.ts / internal/host-runtime-continuity.ts)受益,本包源码零变化;公共导出集无变化(434 项),manifest 不 bump(r7 不变)。sdk 面同文见 packages/sdk/CHANGELOG.md 0.18.1 段;正式读数见 doc/report/PERF-01-正式测量-2026-10-04.md(D30 空闲窗口 2026-10-04:热窗口 COMMIT 2 → 1 成立;P95 / 压力门仍红,结论不在本段改口)。

• 缓存宿主 C2 热窗口单一耐久点与冷恢复并行拉取(PERF-01 (c)(d)):(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 读与新运行心跳并行发出,心跳由 source_conflict 判定之后挪到判定之前(对新运行自身幂等、不触碰 binding / ticket),任一失败整体失败且不发出 continuations 控制 POST。对你意味着:自托管 ServeCacheHost 的装配面、错误码、帽值与 /v2 /v3 wire 零变化;热窗口少一次 FULL 同步 COMMIT、冷恢复少一次串行往返;已有缓存库无需转换。迁移:无。

0.13.0 — 2026-10-02

已发布(“2026.10 统一 API 发行车”,源码 29a21769,npm @tansr/serve@0.13.0 dist-tag latest;回执 doc/release/serve-0.13.0.md)。本段由 REL-PREP-2(2026-10-01)自 doc/release/UAPI-0.13.0-发行说明草案.md 附录 A.1 落实;原按集成分支 36f793cc 写作、三处标「随车」的条目(/v1 下线 / 事件包络 7 键 / manifest revision)已由主线按收编事实 5fce791d(U6-CODE 94116d54、U3-ALIGN 854d6ae8、manifest revision 6)回填,本段不再含「尚未收编」的承诺。导出集相对 @tansr/serve@0.12.0(tag → e9752cc8)的实测差量(REL-PREP-3,2026-10-01;tag 内 exports.snapshot.json 对集成分支 15bcd675 仓内 exports.snapshot.json + exports.subpaths.snapshot.json 逐名比对,0.12.0 无子入口快照):根入口 416 → 434,+18 / −0 / ~33;新增子入口 ./extensions 98 快照项(子入口自身 1 + 具名 97)、./process 6(1 + 5);合计 +122 / −0 / ~33——比 S10 执行单 §2 对 main d1818d8f 的预判(~31)多 2 项签名变,即 UAPI-01 公开 disableV1 带来的 ServeRuntimeServerOptions / ServeRuntimeEnvGroup(快照再生 0367ef53);gate ④ 至少 minor,发行时以版本 bump 同笔再生的快照为准。SDK2.0 收口语义条目由 REL-PREP-3 按 S10 执行单 §5.3「A 起草」补入(U 定稿),每条括注卡号 / 提交与源码位置。

• /api 统一调用面 GA(unified-v1;UAPI-01 阶段一～三,用户拍板 D2):options.v2 在场的部署链首装配门面,83 条旧路由中 /v1 以外 77 条各有 /api 对应物(路由表 packages/server/src/api/route-table.ts 单一事实源;manifest revision 6 = 11 族 / 80 操作 / 38 能力项,unified-v1 族 candidate),会话族经请求头 tansr-session-family 或部署首选族选择、路径不再区分族;领域 payload 字节不变,/v2 /v3/* 响应逐字节不变。全部 /api/* 响应携 tansr-contract / tansr-manifest-revision / tansr-domain / tansr-schema-hash 四头;Idempotency-Key / If-Match / deadline 已在 RFC 定义、本版不读取。对你意味着:新集成只读一份 manifest(GET /api/manifest)与一张路由表;旧前缀本版仍可用;响应缺 tansr-contract 头 = 该部署没有门面,按「合同不可用」上报而不是猜旧版本回退。迁移:按手册第十六章 §16.2 表逐条改前缀(/v2/sessions/** → /api/sessions/**、/v3/sdk2/bindings/** → /api/archive/bindings/**、/v3/sdk2/cache/** → /api/cache/**、/v3/terminal*/** → /api/terminal/**),查询串合同修订标识(protocol=sdk2-ext-v1 等)照写;同一会话族只经一种前缀。
• /v1 单租户面下线(对外契约变更;用户授权代拍 D3 / D11,范围按 D14 = B;UAPI-01 阶段六 U6-CODE,24709c2c…d4985731):0.13.0 起 /v1/sessions*、/v1/status、/v1/approvals/:id/credential 在门面在场(options.v2 在场)的部署缺省 404;disableV1 由内部策略位(此前只由 SDK2 显式宿主 extensions/archive-host.ts 传入)升为公开 StartServerOptions.disableV1(缺省 = 门面在场即 true;SDK2 显式宿主在场时恒关、不能重开),过渡旋钮 tansr serve --legacy-v1 / TANSR_SERVE_LEGACY_V1=1(= disableV1:false,已登记 SERVE_RUNTIME_ENV 表);SDK1-only 部署(无门面)保留 /v1 至独立退役项。两处本版尚无 /api 对应物:GET /v1/status(探针改走 /readyz)与 POST /v1/approvals/:id/credential(审批凭据投递)——接审批投递的 tansr serve --v2 部署在 0.13.0 须显式 --legacy-v1,approval.credential.submit 操作登记为 0.14.0 前置项(UAPI 计划 §四 28 / 32)。对你意味着:健检改走免 Bearer 的 /healthz /readyz(deploy/serve/Dockerfile 已如此),会话面改 /api/sessions(多租鉴权:Bearer + x-tansr-end-user)。迁移:确需保留 /v1 的门面部署显式 --legacy-v1;tansrd 池 / orchestrator 的 /v1 消费方已同车迁 /api 操作名(缺 tansr-contract 头显式报错不回退),tansrd 池实例以 --v2 --legacy-v1 过渡;nginx / k8s 模板加 /api 分片(deploy/serve-v2/**)。
• /v2、/v3/* 退役预告(D11):自本版起定义为内部适配入口,本版不移除任何路由、不改响应字节;最早 0.14.0 进入混用告警与只读窗口(写操作答 410 gone、detail.domainCode: legacy_prefix_retired,附 deprecation / sunset 头——这是对「旧前缀逐字节不变」的有意例外,届时另出说明),1.0.0(unified-v1 冻结)移除外部入口;V2_ROUTE_TABLE 导出形保留。对你意味着:至少一个 minor 的窗口把客户端切到 /api;观测 route 标签以 /v2/ /v3/ 开头的样本 = 尚未迁移的调用。本版无行为变化。
• 统一错误信封(RFC-UAPI-1 §2,D7 会签;UAPI-01 阶段三 U3-ERR,1f21da24):/api 委托路径上 ≥ 400 的 JSON 错误统一为 { contract:'unified-v1', traceId, requestId, code, status, retryAction, message, detail }——code = RFC §2.2 的 17 个映射码 + 门面自有 precondition_failed(412)/ not_canonical(400)共 19 码;retryAction ∈ { none, same-request, query-status, rebind, refresh, rediscover };原族码 / 状态 / 动作留 detail.domainCode / domainStatus / domainRetryAction,cache 的 fallback 留 detail.fallback(不进统一层);detail.path 与 message 里的内部前缀改写回所请求的 /api 路径。例外:archive-sync-v1 无码表,/api/archive/sync/:id 的错误暂透传原信封。旧前缀错误体字节不变;出线状态与 wire 原状态不一致的映射(如 session_ended 409 → 410)见错误信封接线报告 §5.2。对你意味着:一套 switch (code) 覆盖全部域;result_unknown / commit_unknown 只允许 query-status 或 rebind。迁移:三种旧读法改为统一读 code,需原码读 detail.domainCode。
• 统一事件包络显式协商(RFC-UAPI-1 §1.5;U3-EVT,0dd625f7):请求头 tansr-event-envelope: unified-v1 在场时,四条 /api SSE 路由(/api/sessions/:id/events、/api/archive/bindings/:id/events、/api/terminal/executors/:id/events、/api/terminal/sessions/:id/tool-output)逐帧把 data: 改写为 D18 定形的 7 键(键序即 wire 序;U3-ALIGN dff97ff7){ contract, eventId, domain, type, cursorSet{ eventCursor, archiveCoverage, outputWatermark, materialConsumed, ackReceipt }, terminalStatus, raw } 并回响同名响应头确认——eventId = 本帧 SSE id:(缺席 null),不出 seq / payload(位置由 cursorSet.eventCursor 表达,原事件对象只在 raw 携带一份);未携头或未回响 = 未协商,帧字节与旧前缀逐字节相同;raw 恒为原事件对象,未知 type 照常入 raw(不丢、不崩);形由 unified-v1.schema.json#EventEnvelope(additionalProperties:false)+ golden 7 正 18 负锁定,并以真实门面响应逐定义合规测试(api-schema-conformance.test.ts)兜底。对你意味着:五个游标位分离、不得互换;terminalStatus ∈ { null, accepted, completed, aborted, unknown },SSE EOF 与 HTTP 202 都不是完成。迁移:新代码携头并按包络读;旧代码不携头零变化。
• 发现与会话级围栏定形(U3-SCHEMA,01fdaeb3):GET /api/manifest(revision 4,含 runtime.installed)、GET /api/capabilities(部署级,无 URL 导航字段)、GET /api/sessions/:id/capabilities(closureId + 76 操作三态 enabled | disabled | unavailable)与统一信封 / 包络 / 头词表由 doc/rfc/unified-v1.schema.json(52 定义、8 顶层形;U3-ALIGN 后)+ unified-v1.golden.json 161 golden 定形;manifest 第 11 族 unified-v1 自 revision 6 起为 candidate(RFC v1.0-rc,1.0.0 冻结时转 frozen),并登记六端消费方(node / go / csharp / android / ios / harmony,各以 manifest revision / sha256 为锁);pnpm api:manifest:check 核 golden schemaSha256。对你意味着:撤权 / 工具不可用 / 域未装配在调用前即可见,installed:false 与「无权」分开表达。迁移:见手册 §16.3。
• 阶段二既有、本版首次随包发布:GET /api/sessions/:id/capabilities 闭合围栏(携 tansr-closure-id 的写操作不等 → 412,越围栏 → 403 / 404)、会话作用域别名 /api/sessions/:id/{memory,configuration}、执行子资源归执行域、观测 route 模板覆盖 /api 与全部 /v3/*(不再落 other)、Serve 差量审计唯一修正:执行路由 connectionId 未经 Id 校验 → 400(5eb7278e)。
• 库面子入口 @tansr/serve/extensions(首次随包;98 快照项 = 子入口 1 + 具名 97):主线 SDK2 / SRV 卡已收编、0.12.0 未含;导出名与签名以 exports.subpaths.snapshot.json 为准,源码 packages/server/src/extensions/index.ts。全部为可信宿主显式装配的扩展——不改根入口、不改 SDK1 缺省行为、tansr serve 命令行不自动开启(见仓根 CHANGELOG.md 0.10.0);用法与边界见 packages/server/README.md「SDK2 远端归档宿主」「统一核心与终端执行」及其子节。按功能群:
  • 归档宿主(SDK2-02 2699e558 / 03 9c19a54a 152b2e8b 91db5ee1 c98b07e7 / 05 269ef440 251c14f5 / 06 810a0516 / 08 b6791ceb):createServeArchiveHost(options: ServeArchiveHostOptions): ServeArchiveHost + ServeArchiveHostError;security: 'trusted-single-application' 必填(受信单应用宿主,不是多租户隔离或不受信工具沙箱);host.start(ServeArchiveStartOptions) 沿原 /v2 认证与会话注册仓挂 /v3/sdk2/**(门面别名 /api/archive/**),构造宿主本身不建库;agent.store 须是同一次安装同包根入口的原 Store 对象。宿主方法:rotateOperationEpoch(可信部署显式轮换,安全空闲边界 CAS)/ deleteSessionHistory({ requestId, scope: 'entire-session' }) / deleteArchiveRecords({ requestId, expectedHead, recordIds })(同绑定记录删除链)/ readRetentionRevision · readRetentionPage · authorizeRetention(新介质精确同步授权回调,不是 revision 数字自证)/ readEffectiveContext(轮末有效上下文引用;不新增 HTTP 路由,终端不能提交引用作权限)/ readArchiveStorageStrategy(本版固定 single-authorized-source + source-ack-with-durable-spool,replication / synchronization 皆 'none')/ verifyArchiveRecords · recordRequiredReplica(仅可信开发者存储服务调用)/ closeOverlay(来源 ACK 与材料责任排空后关闭叠加,保留业务会话与 Store)。类型:ServeArchive{Subject,Operation,Epoch,EpochProvider,HostOptions,StartOptions}、ArchiveHost{Quota,Limits}、ArchiveCompletionAuthorization、ArchiveEffectiveContextReference、ArchiveStorageStrategyView、ArchiveAttachmentSource(trustedAttachmentSourceFor(subject) 选用;URL 只是查表键,serve 不自动 fetch)、ArchiveMaterial{Issue,Artifact,Request}、ArchiveRetention{,Identity}、Archive{Session,Record}Deletion、ArchiveInput{Capabilities,Target,Submission,Receipt,Result}。
  • 归档同步(SDK2-03 152b2e8b「双副本档案同步与保留介质」):startServeArchiveSync + ServeArchiveSyncHost / ArchiveSyncBinding / ArchiveSyncReadGrant——/v3/sdk2/archive-sync/**(门面 /api/archive/sync/:id)的可信同步宿主;错误体本版暂透传原信封(archive-sync-v1 无码表,见上「统一错误信封」例外)。
  • 显式卸载宿主(SDK2-03 f9f7eccf 8c31e452 8b04b8ab;SRV-04):createServeOffloadArchiveHost + OffloadSessionError;新客户端显式选 sessionContract: 'sdk2-offload-v1'(先 GET /v3/sdk2/session-capabilities?protocol=sdk2-ext-v1,门面 /api/capabilities/sessions,确认实际装配;缺省 sdk1 不变;新建须携稳定 requestId,不支持 fork)。宿主在 ServeArchiveHost 之上加 rollbackEffectiveHistory(排空后回读有效史复制到新的旧格式目标,不切身份不删源)/ importEffectiveHistory({ requestId, bytes })(可信宿主向尚无历史的新族目标一次性导入 exportCheckpoint 字节;只迁当前有效消息与自包含附件,来源固定 originalArchive: 'not-proven-before-import' / sourceHandling: 'untouched-by-import';用量 / 运行检查点 / 记忆选择 / 外部附件来源不迁移)/ readEffectiveHistoryOrigin(有效史 digest 与保留代际匹配才回来源,否则 null;新族 GET 单会话 meta 加 historyOrigin)。类型:ServeOffloadArchiveHost(Options)、Serve(Transactional)OffloadPersistenceOptions(maxRollbackBytes ≤ 64 MiB)、OffloadStorageStrategyView、OffloadRollback{Input,Receipt}、OffloadEffectiveHistory{Origin,ImportInput,ImportReceipt}。
  • 缓存宿主(SDK2-09 a9732063「公开可信缓存宿主并复用归档装配」;SDK2-07 接续桥):createServeCacheHost(options) → ServeCacheHost { start, readInventory, dispose } + ServeCacheHostOptions / ServeCacheStartOptions / ServeCache(Store)Inventory。复用原会话工厂、平台 C1 / C2、可信接续与 /v3/sdk2/cache/**(门面 /api/cache/**);配置 / appKey / 加密钥 / 签发器只在可信服务进程保存,不收终端 JSON;私有目录须已存在的绝对路径,重启 mode: 'recover' + 原目录 / 身份 / 密钥。同一缓存宿主只能交给一个独立工厂、createServeArchiveHost({ …, cache }) 或 createServeOffloadArchiveHost({ …, cache })(重复绑定 / 归属不符 / 伪造宿主拒绝;归档持有时须先停监听再归档 dispose());archived: 'cold-new' + 同步 authorizeColdNew 才允许缓存档 410 session_archived 后冷建独立新关系,缺省 'reject'。readInventory() 只给已打开介质的数字与不透明作用域,不含票据 / 正文。
  • 持久介质再出口(SDK2-02;kernel):openSqliteArchiveSpool + SqliteArchiveSpool / OpenSqliteArchiveSpoolOptions——原宿主持久介质的显式出口,供 AgentExecutionOptions.spoolFor / 归档宿主复用;不在终端客户端中运行。
  • 共享事务 Store(USDK-07 bb6fad34「发布共享事务宿主的显式扩展出口」;SRV-04):createTransactionalServeAgentSessionStore / createMysqlAgentSessionTransactionBackend + TransactionalServeAgentSessionStore(Options)、AgentSessionTransaction / AgentSessionTransaction{Backend,State,Scope}、AgentSessionEventOwner、AgentSessionSql{Connection,Pool}、AgentSessionMysqlBackend、AgentExecutionTransactionalOptions——可信宿主显式选择共享事务介质(与 CreateAgentSessionFactoryOptions.transactionalExecution 配对,与原 execution.spoolFor 装配互斥);不替换原文件 Store,不在终端注入数据库依赖;原热冷 / 五方法 Store / SDK1 / no-store 缺省并存。
  • 记忆生命周期与发布介质(SRV-01 42224634「接通终端工具记忆与跨端控制」;SRV-03 共享 kernel):createPlatformMemoryLifecycle + PlatformMemory{Options,PublicationOptions,Scope,LifecycleOptions,Lifecycle} / ServerManagedMemoryOptions(提取 / 固化 / 检索 / 管理 / 晋升全链在共享 kernel,由 PlatformServeSessionFactoryOptions.memoryFor / memoryPublicationFor 逐用户装配);MemoryManagementSource / MemoryManagementError + Memory{Identity,ManagementRequest,ManagementReceipt,ManagementErrorCode,ManagementSourceOptions,ManagementControlOptions,ManagementReconciliation,LeaseReconciliation} / ManagedMemoryHost(Options)(记忆正文权限与宿主元数据 CAS / 租约分开;pin / remember / forget 等管理命令经 /v3/terminal/sessions/:id/memory[/commands[/:opId]],门面别名 /api/sessions/:id/memory…);发布介质 createSqliteMemoryPublicationStore / createBlobMemoryPublicationStore / createTerminalMemoryPublicationStore / memoryPublicationKey / recoverMemoryPublicationTransfers + MemoryPublicationStore / MemoryPublicationPendingTransfer / TerminalMemoryPublication{Options,Store} / RecoveredMemoryPublicationTransfer(终端只保管 publication,核心运行提取 / 固化 / 检索 / 晋升;发布体 4 MiB 帽、分块 12 288 B)。
  • 终端合同锚与业务工具摘要:TERMINAL_CONTRACT_SCHEMA_REVISION / TERMINAL_CONTRACT_SCHEMA_SHA256(SRV-01;terminal-services-v1 当前 schema 修订 2026-09-26.candidate-7 与 sha256,生成件 v2/terminal-contract.generated.ts;C# / Android / iOS / Harmony 按精确哈希消费)· clientToolDefinitionDigest(decl)(USDK-04;旧 clientTools 申报的绑定摘要,端侧注册同名同摘要 handler,结果经 tool.invoke 专属回执回填)。
• 库面子入口 @tansr/serve/process(首次随包;6 快照项 = 子入口 1 + 具名 5;USDK-08 9788f79a):installProcessGuards / ProcessGuardOptions / ProcessGuardTarget / LOG_EVENT / ServeLogger——与根出口同一实现与日志词表的窄出口,导入不装配 HTTP / 会话 / 平台运行时;tansr 的 TUI / headless / acp / mcp-serve 四入口与共享 assembly/process-lifecycle.ts 自此只拉此窄出口(tansr serve 本就装配整包,仍从根入口取)。对你意味着:自托管宿主把 import { installProcessGuards } from '@tansr/serve' 改为 '@tansr/serve/process' 可减少启动导入;根入口照旧可用,无需迁移。
• 根导出 +18(全部为 SDK2 执行档 / 可信宿主 / 空闲期配置的类型加法 + createServeLogger):
  • 显式远端执行档(USDK-04 d7c9e9fd 起,USDK-05 fbb683e9 / 06 f2123174 fdf6fc7f / 07 5e33643a、SDK2-05 d058876b / 10 581a12e5、SRV-01 / 06;源 v2/agent-execution.ts · v2/agent-execution-store.ts):AgentExecutionOptions(必填 applicationScopeId / authorize(req, endUserId) → AgentExecutionAuthority / readPolicy(endUserId, signal) → AgentExecutionPolicy / spoolFor(scope) → AgentExecutionStorage;可选 readAttachmentSource / reconcileObservation / confirmInterpreter / skillsFor / toolsFor / mcpFor / memoryFor / subagentsFor / maxConnections · maxConnectionsPerEndUser · maxSessions · maxSessionsPerEndUser / backgroundRuntimeMs / shellSandbox / now),AgentExecutionPolicy { authorizationRevision, tools, expiresAt? }(缓存实现必须回绝对有效期;到期或取不到有效策略拒绝新执行),AgentExecutionAuthority { controller, executorId? },AgentExecutionStorage { spool, bindingId },AgentExecutionObservation(Input)(查询已存在的可信耐久证据,禁止在回调中重做工具;null 保留 unknown)。接线:createAgentSessionFactory({ platform, execution });缺省限额全局 256 执行器连接 / 512 会话、每用户 16 / 8,越界 429 capacity_exceeded(serve 自保护,不代替套餐额度);远端 Shell 须应用 execution.boundDevice.tools.shell + 具名策略 + 设备 process.exec 后端 + 可信 confirmInterpreter 四者同时在场,缺一 executor_shell_unconfirmed / 拒派。对你意味着:未配置 execution 的旧接入路径零变化;Electron 完整 SDK 不走此档。
  • 可信宿主扩展(SRV-01 42224634 / SRV-06 3d3ceba6 e63c4e70;源 v2/platform-trusted-extensions.ts):PlatformTrustedScope { applicationScopeId, endUserId, sessionId }、PlatformTrustedExtensions { decorateModelClient?, queryHooks?, beforeTool?, timeoutMs?(缺省 10 s,上限 120 s), onClosed? }、PlatformSystemConfiguration { system?, systemAppend? }——经 PlatformServeSessionFactoryOptions.trustedExtensionsFor(scope) / systemFor(scope, signal) 由宿主代码登记,HTTP 不能提交可执行模块;decorateModelClient 与本机代码同级受信、只作用于主会话客户端及其缺省压缩;beforeTool 在原权限决定之后、真实执行之前只收紧;超时 / 异常 / 取消均不能当成允许。
  • 空闲期配置(SRV-05 fd8bfcb7 b988eee0;源 v2/types.ts):AgentSessionModelBinding { client, model, contextWindowTokens?, maxOutputTokens? }、AgentSessionConfiguration { revision, model, thinking }、AgentConfigureRequest { requestId, expectedRevision, changes: { model?, thinking? } }、AgentConfigureOptions { signal?, beforeCommit? }、AgentConfigureResult(changed | replayed | rejected{ reason: … | 'revision_conflict' | 'request_conflict' | 'request_limit' })、AgentConfigurationRejection('turn_running' | 'session_ended' | 'invalid_configuration' | 'context_transition_required' | 'unsupported')、AgentSetModelResult / AgentSetThinkingResult。HTTP 面:GET / POST /v3/terminal/sessions/:id/configuration(门面别名 /api/sessions/:id/configuration;须 startServer({ terminal: { contract: 'terminal-services-v1' } })),changes 只含授权模型别名与 thinking;窗口不兼容要求显式迁移、不静默重建上下文。
  • createServeLogger(sink, { level = 'warn', now })(USDK-06 f2123174;源 observability/log.ts)→ ServeLogger & { flush() }:固定 10 s 窗口按 (level, event, 字段) 分组限量,超出以 log.repeated { originalEvent, suppressed, windowMs } 汇总,组数超 128 以 log.overflow;全部级别(含 debug 与旧文案通道)同样脱敏 / 有界(字段 ≤ 128 个、字符串 ≤ 1 024 字符、整体 ≤ 8 KiB,正文键 prompt / messages / content / body / args / stdout / stderr … 恒 [redacted])。tansr serve 入口已用它包装,旋钮 TANSR_SERVE_LOG_LEVEL(缺省 warn)。自托管宿主可选用;旧自定义 logger 直接注入仍可。
• 根导出 33 项签名变化(逐名;全部为可选键 / 可选尾参 / 常量词表加法 + 3 项「声明未变、哈希变」,零删除;0.x 期以 minor 承载):
  • UAPI-01(3):StartServerOptions.disableV1?(上文 /v1 下线条)· ServeRuntimeServerOptions(Pick 加 'disableV1')· ServeRuntimeEnvGroup(加 'legacy')。
  • 终端服务与可信宿主(SRV-01 42224634 / SRV-05 fd8bfcb7 / SRV-06 3d3ceba6;SDK2-06 ae3f0a9d;9,另 StartServerOptions 已计入上行):StartServerOptions.terminal?: { contract: 'terminal-services-v1'; revalidateMs?; scopeFor?(session) → { applicationScopeId, endUserId, authorizationRevision } }(SRV-01;显式启用 /v3/terminal/** 14 路由 + /v3/terminal-observation/** 2 + /v3/terminal-profile/** 2,门面 /api/terminal/**;须 v2 在场;scopeFor 仅无执行宿主的控制面用,撤权时拒绝返回)· AgentSessionFactory.terminalCapabilities?: readonly ('session-configuration-v1' | 'memory-lifecycle-v1')[](可信装配事实,不由终端 DTO 指定)/ .execution? / .transactionalExecution? · AgentSessionHandle.owner? / .applicationPrompt?() / .setModel?(binding) / .setThinking?(thinking) / .configuration?() / .configure?(request, options)(全部可选方法,旧宿主 / 旧 Store 未接线时缺席)· PlatformServeSessionFactoryOptions 与 PlatformAgentSessionOptions 同缝加 trustedExtensionsFor? / systemFor? / memoryFor? / memoryPublicationFor?(SRV-01 / 06)与四个查询护栏 temperature? / stopSequences? / maxToolRounds? / maxConsecutiveErrors?(SRV-06;缺席沿 kernel 缺省,终端不能经 JSON 覆盖)及 maxOutputTokens?(SDK2-06 ae3f0a9d:宿主输出硬上限,与模型能力取小,约束主查询 / 压缩 / 派生任务;原 maxTokens 自此是「单次主查询初始输出预算(缺省 8192;触帽后可在 maxOutputTokens 内升档)」;独立裁决人 / 记忆选择器仍各自预算) · ServeSessionDriverOptions 加同四个护栏 + @internal 旁带(sessionCapture / contextMaterials / attachmentPersistence / getMemorySelectionCheckpoint / runtimeCostSnapshot / applicationPromptInfo)· ServeSessionExtras.trustedScope? / memoryScope? / configurationThinking?(null 覆盖宿主缺省)/ execution? / persistBackgroundUsage?(undefined = 无持久店、null = 旧店不支持费用单独追加、函数 = 原店写入)+ @internal 旁带 · AssembledSessionModel.readPlatformCatalog? / readPlatformUsage? / refreshApplicationCapabilities?(每次经原身份令牌复核平台目录 / 本人 1 d 用量 / 应用能力;旧注入形缺席即不支持)· V2SessionMetaView.applicationPrompt?: ApplicationPromptInfo(GET /v2/sessions/:id?include=applicationPrompt 显式请求才返回,不含正文;其它 include 值 400)· ServeSessionDriver 类公开方法加 setModel / setThinking / configure / modelBinding / thinking / applicationPrompt / attachmentCheckpoint / … / restoreHistory 重载(宿主 / 工厂接线面;HTTP 消费方不受影响)。对你意味着:不传新键 = 0.12 行为;terminal 未配置的部署 /v3/terminal* 全部 404。
  • 持久所有权与原 Store 可选能力(USDK-07 4ccba1ea 50001269 66d4cf37 / SRV-05 / USDK-08 901c8916 9b117383;源 v2/agent-session-store.ts · v2/agent-session-factory.ts · v2/agent-platform-identity.ts;6):CreateServeAgentSessionStoreOptions.ownership?: ServeSessionOwnershipOptions { ownerId?, leaseMs?, runtimeRecovery?: true }(同可信主机多 Serve 进程共享原会话目录;启用前须停旧单写者,旧二进制 / 在线混模式切换不受支持;跨主机须由具原子写 fence 的 Store 提供)· ServeAgentSessionStore 加可选 claimOwner?() / runtimeCheckpoints?: true / attachmentCheckpoints?: true / attachmentSourceCheckpoints?: true / memorySelectionCheckpoints?: true / initializeConfiguration? · inspectConfiguration? · commitConfiguration?(SRV-05;与原 owner / journal 写围栏同锁)/ recordUsageSnapshot?(…, owner?)(只追加费用快照内部事件,须与同会话 commit / delete 串行),create(init) 的 init.owner?,recordCwdChange? / recordSeqWatermark? 加尾参 owner? · AgentStoreCommitMeta.runtimeCheckpoint? / owner? / attachmentCheckpoint? / attachmentSourceCheckpoint? / memorySelectionCheckpoint?(后三者为内核生成的不透明值,支持的 Store 须与历史原子保存、不解析不构造)· AgentStoredSessionRecord.configuration? / runtimeCheckpoint? / ownershipRequired?: true / attachmentCheckpoint? / attachmentSourceCheckpoint? / memorySelectionCheckpoint?(ownershipRequired = 已用耐久写者的记录,恢复不能靠关闭配置降级绕过)· CreateAgentSessionFactoryOptions.configuration?: { resolveModel? } / execution? / transactionalExecution?(两种装配互斥)/ platform.onSessionArchived?(previous, replacement?) → string(SDK2-07 b89b98cc:普通会话 410 后由工厂持新运行号并确认到原 Store,不再复用已归档 runtime)+ @internal cacheHost / gatewayCache / sessionCapture / contextMaterials · PlatformSessionAssemblerInput.onSessionArchived?。对你意味着:自定义 Store 不实现任何可选项 = 0.12 行为(单写者、轮末稳定点恢复、冷恢复清附件引用但保留累计准入);内置文件 Store 已全部实现;声明某能力位即承诺其原子保存合同,不得伪造缺失状态。迁移:无强制;需要多实例接管 / 冷恢复记忆与附件预算 / 持久 recallSelector 的部署按 README「绑定工作区记忆」与「应用授权与终端能力」节补实现(持久会话启用 recallSelector 时 memorySelectionCheckpoints 与 recordUsageSnapshot 缺一即在模型请求前拒绝)。
  • 资源限界(USDK-08 eceeff0d「限界认证与事件资源并封住执行重入」/ USDK-05 ab62e821 / USDK-06 f2123174;源 types.ts · ring-buffer.ts · subscriber-writer.ts · runtime-options.ts;7):AgentSessionsOptions.authentication?: { maxPending?, timeoutMs? }(基础认证源限界:SDK2 execution / archive / cache 装配缺省 128 个未结束源、每请求 10 s,SDK1-only 缺席零变化;显式任一键即启用;旋钮 TANSR_SERVE_AUTH_MAX_PENDING / TANSR_SERVE_AUTH_TIMEOUT_MS)· ServeRuntimeV2Options(Pick 加 'authentication')· SseOptions.maxFrameBytes?(单帧 UTF-8 字节硬帽,有限值超界只断开该订阅、不拆坏 JSON、不伪造完成;SDK2 装配缺省 2 MiB,TANSR_SERVE_SSE_MAX_FRAME_BYTES;两帽有限时每次写出上界 = max(maxBufferBytes, maxFrameBytes))· EventRingBufferOptions.maxEventBytes?(显式有限模式按 UTF-8 严格总帽;拒收超界事件并清前缀窗口、记原 server.replay.gap;SDK2 装配 eventBufferMaxBytes 缺省 4 MiB)· AttachOptions.beforeFlush?: () => boolean | Promise<boolean>(私有帧批次写出前复核身份,缺席保留原路径)· ServeRuntimeOptions.logLevel: ServeLogLevel(resolveServeRuntimeOptions 产物新增必填字段;TANSR_SERVE_LOG_LEVEL 缺省 warn,SERVE_RUNTIME_ENV 表 31 → 36 键,.env.example / README 旋钮区由表再生)· ServeLogger.log?(level, event, fields, legacyText?)(第 4 可选参:旧文案通道,与结构化字段同样脱敏 / 限量)。对你意味着:自行构造 ServeRuntimeOptions 字面量的宿主须补 logLevel;其余不传 = 0.12 行为。
  • 文案键 / 日志词表 / 桥(SDK2-04 e262d99b / USDK-04 d7c9e9fd / USDK-08 / SRV-05 36d613d8 / SDK2-10 1a7ed04a;5):SERVER_MESSAGE_KEY.materialRequired = 'kernel.context.material_required'(缺必需材料时阻断当前轮推理的文案键)· V2_ASSEMBLY_MESSAGE_KEY 加 memorySourceUnavailable / backgroundUsageStoreRequired / executionPermissionTarget / executionInitializeRequired,appPlatformMismatch 文案保留兼容但不再作 Serve 拓扑判断依据(SRV-05)· LOG_EVENT 加 execution.rejected / execution.result / log.repeated / log.overflow(tansr serve JSON 日志新事件名;仪表板 / 告警按名随动)· buildRemoteTool(decl, bridge, now?, executeBound?)(第 4 可选参:绑定设备执行的本地 handler,缺席走原 bridge.registerToolCall)· AgentSessionBridge.registerToolCall(…, ttlMs?, dispatch?)(第 7 可选参:SDK2 定向资源请求复用同一取消 / 超时 / 回执状态机、不向全部 SSE 观察者广播参数)+ 行为收紧:重复的在途 / 已终局 callId 再次登记即 reject duplicate remote tool call,不再覆盖原挂起项(此前可致首份 Promise 永久悬挂、第二份回执误完成另一调用)。
  • 声明逐字未变、哈希变(3,主线已核因:非 API 变化):CreateSessionBodySchema / PermissionReceiptSchema / CompactBodySchema——git diff @tansr/serve@0.12.0 HEAD -- packages/server/src/v2/contract.ts 只有 V2SessionMetaView.applicationPrompt? 与一行 import,三者源声明零改动、wire 形零变化。主线重建 @tansr/serve@0.12.0 的 dist/index.d.ts 与候选逐声明对比(2026-10-01):三条声明长度逐字节相同,仅 zod 推导对象类型的成员顺序不同(resume / endUser、verdict / digest、instructions / checkpoint 互换)——tsc 声明输出对推导类型成员排序随程序其它内容变化,类型集合与可赋值性完全相同。发布后以两版公开 registry tgz 的 d.ts 复核(REL-TOOL-2,2026-10-03;doc/report/REL-PREP-3-SDK2收口CHANGELOG语义-2026-10-01.md §2.3):重算哈希与两 tag 快照逐一相同,token 多重集相等、Shape 泛型参逐字同,zod 3.25.76 / TypeScript 5.9.3 / rollup-plugin-dts 6.5.1 两版同版——差异只在 z.ZodObject 第 4 / 5 泛型参(推导 Output / Input)的属性序,非 API 变化。gate ④ 按文本哈希计入 ~33 属工具口径(快照不对成员排序归一),不影响 minor 判定;消费方零迁移。
• 性能与延期披露(SDK2-09;用户授权代拍 D12「A 时间盒一轮」→ 到期仍红,转 B):缓存宿主 / 常驻映射的三项原性能门截至 2026-09-28 仍红,功能条件交付、缺省关闭 / 显式 opt-in 不变,不改称外部依赖、不改阈值、不改称通过(SDK2.0 集中交付计划 §26 / §28,证据 archive/20260928-SDK2-performance-closure/**):① 32 KiB 映射常驻——N1 具名不重叠下界 35,395 B(JS 与唯一 backing 7,565 + SQLite 新增运行映射 20,623 + Node 注册容器增长 7,207),超 32,768 B 帽 2,627 B;Store 同次独占恢复 3 次读降 1 次后 N1 桶仍 +7,207 B;② 缓存局部 hot / cold P95(10 / 50 ms)——Windows 140 位置红保留;Linux 四位置只是诊断(short hot 41.5 → 64.2 ms、cold 题 hot 11.8 → 52.3 ms、cold 33.8 → 413.9 ms),不是 P95;单冷诊断 297.7 ms 中 12 次写 COMMIT 179.3 ms 为保留原 FULL 事务与恢复屏障的主要成本,不删屏障求绿;③ 1record / 1KiB 同步压力档——centralized 326 ms / offload 3 188 ms,对计划 2× 652 ms 判 duration_regressed(按压力口径补充裁决:该线只约束此具名支持档,不扩成全部受控题的普适退出门)。S09 时间盒结算(2026-10-01,空闲主机(host-idle-check CPU 五采样 <15% 后开跑,逐组读数披露)、基线 / 候选交替各三组取中位,既有测量器口径;报告 doc/report/SDK2-09-性能门时间盒-2026-10-01.md,证据 archive/20261001-SDK2-09-timebox/):① 32 KiB 常驻 heap lower 34,837 B/映射(n=32 35,040;帽 32,768 → regression,基线 34,824);② P95 Δ short-text hot 30.5 ms(允 10;基线 30.4)、cold-restore hot 27.8 ms(允 10;基线 24.9)、cold-restore cold 181.9 ms(允 50;基线 221.7);③ 压力 centralized 219 / offload 2,293 ms(2× 线 438 → duration_regressed;基线 222 / 2,687)。本版两项无语义变化的优化:预算槽记录解码前剪尾部 0x20 填充(sdk2/cache-vault-reserve.ts,整段字节规范性仍由重编码逐字节比对保证)、SqliteSpool 安装就绪记录结构验证按 (create 摘要, 行字节) 备忘(有界硬帽、close() 清空、耐久事实每次重读)——cold −40 ms、压力 −15%,三门仍红 → 按 B「功能条件交付 + 明确延期披露」关闭、红数原样入账、另开 PERF-01 承接(热窗口两次耐久 COMMIT 合并、冷恢复协议步骤合并、spool 事件链备忘、32 KiB 测量器口径均为决策面 / 跨卡项)。供应商缓存净节费未证明(原 17 h 实账 175.32 元覆盖 2 263 次尝试,840 矩阵 239 pass / 601 fail 为历史终态;集中计划 §25)。

0.12.0 — 2026-09-16

• 移动托管会话根据平台 tools.webFetch / tools.http 能力位装配核心公网工具；能力缺省关闭，显式白名单只能收窄。升级服务并开启应用配置后，新建或从存储重新装配会话才生效（MOB-WEB-01 / REL-12）。
• 托管 Http 设置宿主私网上限并禁用环境凭据引用；WebFetch 保留既有出网和跨主机跳转审批规则，不绕过共享权限链。
• 默认文本日志补齐审批回执和受限裁决诊断，不记录完整工具参数、用户内容或凭据；裁决超时仍回落询问。

0.11.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.10.0 — 2026-09-14

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

历史接口透传 tool_result.artifact，热/冷恢复与 checkpoint 保留媒体产物。含产物存储提升版本 2，旧程序不能继续写升级卷；请备份并统一升级会话 writer。HTTP 路径和事件包络不变，旧文本历史不自动补媒体。发布状态以实际回执为准。

0.9.0 — 2026-09-14

REL-06 按 DEC-RF-24 候选版本重新编译；实际发布状态以 doc/release/serve-0.9.0.md 操作回执为准。核心组件设计审查整改波(RF-03 / RF-05a / RF-05b / RF-06b / RF-08b / RF-08c / RF-P3a / RF-S1 等,2026-09-11 … 13)。导出集相对 @tansr/serve@0.8.1(404 项)→ 413 项(exports.snapshot.json 为准;+9 零删:AgentStoredSeqWatermark / CloseAllOptions / CloseAllReport / MemorySessionEventLogOptions / V2SessionMediaView 与 0.8.1 后并入的语音输入规划 SpeechInputPlan / SpeechInputPlanResult / countSpeechCharacters / planSpeechInput;gate ④ 至少 minor)。

• TypeScript 成品声明可直接检查(REL-06-03)：从 index.d.ts 移除误混入的 createRequire 运行时垫片，修复未开启 skipLibCheck 的 NodeNext 消费方所遇 TS1046 / TS1254。JavaScript 垫片仍保留，运行时与公开类型签名不变；无需迁移。

• /v2 非活跃会话 lastSeq 真值 + tansr serve 店告警接线(RF-S1,核心组件设计审查 DEC-RF-30 / 48;doc/98 §二-⑥ / ⑧ · §三-2 改笔;导出集零漂移):GET ⑥ 会话详情 / ⑦ 列表 / ⑧ history 对非活跃(不在内存)会话返回的 lastSeq 自此 = store meta 持久化水位(RF-05b 落盘的 lastSeq:正常关闭封印值或最近轮末 / 改写检查点值),此前恒 0;旧卷 / 无水位记录仍 0,无 meta 记录仍 404,活跃径不变。wire 形 / 键集 / 键序 / 公共类型零变化——StoredSessionMeta 形不变,createAgentSessionFactory 的 storeReader 以内部加法位回填(自实现 AgentStoreReader 不回填 = 仍 0;坏形值按 0);⑧ 非活跃径为取水位在历史在场后多一次 store.getMeta(历史缺席 404 先于之;meta 读抛错与既有读拒绝同码 500 store_corrupted,原文只进 store.error 日志)。对你意味着:客户端(含 Android / iOS)不得再以 lastSeq === 0 判「无事件」,应按值作 Last-Event-ID 续传起点(封印记录恰续;未封印记录可能收 gap evicted 后 L2 重建)。同笔 tansr serve --v2 宿主建店接 onStoreWarning:店核警告(store_unknown_kinds / store_prefix_mismatch / store_pending_rewrite / store_seal_failed)自此不再静默,以 warn 级复用既有 store.error 事件出线 {code,message,sessionId?,count?,kinds?}(TANSR_SERVE_LOG_FORMAT=json 一行 JSON 落 stderr;text 形态回落 stderr 同形 JSON 行);LOG_EVENT 不加键、字段恒不含消息内容。自托管 @tansr/serve 宿主如需同样可观测,自行 createServeAgentSessionStore({ onStoreWarning }) 接进自己的 logger。

• SSE 有界写(RF-05a,核心组件设计审查 RV-4-01):maxBufferBytes(doc/98 §六 2 MiB)自此是每次 res.write 的字节上界——attach 重放段惰性分片交付(SseSubscriber.replay? 可选面;SubscriberWriter.replay 必有)、同 tick 批量入队越界即刻分片写出、flush() / end() 不再整队一次写出;socket 拒收后残量按既有慢消费者判据裁决(disconnect / drop-oldest 语义、两参数值不变)。帧文本与顺序逐字节不变,小流量零分片。对你意味着:大重放 / 突发不再一次把数 MiB 塞进 socket 缓冲;曾靠「非 paused 期队列无界」吞下超 2 MiB 突发的慢客户端此后可能被判慢消费者并按 Last-Event-ID 重连重放。SubscriberWriterStats 加 replaying。

• /v1 drain 的 retry: 帧经 writer 记账(RV-4-08):sseStats().frames / writes 自此计入;http-server.ts 直接 res.write 调用归零。行为不变。

• ⑳㉑ 音频面错误信封(RV-4-05 / V-C-09):上游 transport_error 与上游 401 / 403 / 5xx 归一 503 upstream_unavailable 固定词条 + Retry-After,上游状态 / 码 / 人话只进新结构化日志事件 upstream.rejected{face,sessionId,upstreamStatus?,upstreamCode,message,status};上游业务 4xx(409 / 429 / 400 / 402 …)维持 doc/98 §二-⑳㉑ 原码透传。对你意味着:端侧不再因平台侧 401 unauthorized 误判本地令牌失效;此前依赖 403 model_not_authorized / 502 http_502 原样到端的调用方改读日志。LOG_EVENT 加一名。

• server.replay.gap 帧形态进契约门(RV-4-06):事件名 / 载荷键集 / reason 词表单源于 v2/contract.ts(REPLAY_GAP_EVENT / REPLAY_GAP_REASON / ReplayGapNoticeSchema),ReplayGapNotice 公共类型由 interface 改为 schema 推导 type(字段与可选性不变);改形不 pnpm contract:manifest --bump 即 contract:check 红。sdk contract/MANIFEST.json revision 随之 +1,端侧 vendored 拷贝由镜像卡更新。

• /v2 seq 会话内单调 + 起点规则(RF-05b,核心组件设计审查 RV-4-02;doc/98 §三-2 改笔,§3 代拍 #2 = B):resume 起的新纪元 seq 不再从 0 起,起点 = store 持久化水位 + 1——文件 store 在每次轮末 / 改写检查点把 lastSeq 落 meta.json(只增不减),正常关闭(session.ended 后)落最终值并封印 seqSealed: true;播种规则 seedInitialSeq:封印 → 恰 lastSeq + 1(旧游标 Last-Event-ID 续传零 gap),未封印(崩溃 / 旧记录)→ max(lastSeq + 1, now − createdAt ms) 守卫地板(单纪元平均 > 1 事件/ms 为唯一理论失效窄窗,见 doc/98 §三-2)。旧游标落在新纪元起点之前 → gap reason: 'evicted';空日志水位 = 起点 − 1;Last-Event-ID 缺席恒全量重放。wire 形零改动;resume 201 响应 lastSeq 由恒 0 变为新纪元水位(L3 客户端恒弃游标重建,不读本值)。对你意味着:多设备 / 冷启动持旧游标重连不再必然重建;自实现 ServeAgentSessionStore 可选实现 recordSeqWatermark(缺席 = 不封印,按守卫地板起新纪元,仍安全)、commit 的 meta 多 lastSeq?;自实现 SessionEventLog 收 SessionEventLogContext.epochStartSeq?(可忽略)。加法导出:ServeSessionDriverOptions.initialSeq? / ServeSessionExtras.initialSeq? / AgentSessionHandle.firstSeq?() / AgentStoredSessionMeta.{lastSeq?,seqSealed?} / AgentStoredSeqWatermark / MemorySessionEventLogOptions.floorSeq?。

• 停机 closeAll 有界(RF-03,核心组件设计审查 RV-4-03):server.close() 等 /v1 store 与 /v2 registry 会话泵收口的末段不再无界——StartServerOptions.closeAllTimeoutMs(缺省 5 000 ms;Infinity = 旧的无界等待)到点即记一条 server.close_timeout{face,pending,timeoutMs}(warn,非失败)并继续停监听 / 切连接;/readyz 先 503 的时序不变。库面加法:SessionStore.closeAll(options?: CloseAllOptions) / AgentSessionRegistry.closeAll(options?) 返回 CloseAllReport { timedOut, pending }(缺席 timeoutMs = 等到全部落定 = 旧行为);LOG_EVENT 加 server.close_timeout 与 process.hard_exit(后者由 tansr serve 等进程入口在 drain 预算到点 / 第二枚信号硬退前留痕)。对你意味着:一个永不落定的会话泵不再能拖住整机停机;自托管宿主若依赖「closeAll 必等全部落定」,显式传 closeAllTimeoutMs: Infinity。

• tansr serve 每轮墙钟缺省(RF-03,§3 代拍 #9 = A;仅 serve 装配面,库 startServer 与 TUI / headless 不受影响):TANSR_SERVE_TURN_WALL_CLOCK_MS 缺席时自此为 1 800 000 ms(30 min),显式 0 = 停用(不再被库解析判为非法值告警),其他值照旧。此前缺省无墙钟,一轮可无限期占用会话并发槽。对你意味着:单轮预期超过 30 min 的部署需显式设更大值或 0;deploy/serve*/README.md、.env.example、doc/11 §5.4 / §6.1 / §7.2 同步改口。

• tansr serve 信号矩阵(RF-03):SIGINT / SIGTERM / SIGHUP / SIGBREAK 共用同一 listener,首枚 → 幂等有界 drain(整链预算 drainTimeoutMs + 15 s,到点记 process.hard_exit 后 exit 2),第二枚 → 立即 exit 2(此前被 stopping 位吞掉,只能等 drain 自然结束);SIGHUP 独立紧急预算 ≤ 3 s。退出码沿用 cli exit-code.ts 表(2 = 中断 / 外部信号 / 停机)。

• serve hostShell 透传(RF-08c / DEC-RF-33,AC-08 08c-2;纯加法,缺省随平台 = 现行):运维旋钮表新增 TANSR_SERVE_HOST_SHELL=posix|powershell(group session,target session.hostShell;SERVE_RUNTIME_ENV 31 键,.env.example / README 旋钮表随表再生),ServeRuntimeSessionOptions.hostShell? / PlatformAgentSessionOptions.hostShell? / PlatformServeSessionFactoryOptions.hostShell? 三处可选字段同缝展开(...runtime.session 既有形零改动),落到会话 PermissionEngine 的 hostShell(kernel PermissionEngineConfig:Shell 命令词法 / 结构树 / hard-safety / 分类器事实所用方言);CLI tansr serve 经同一 session 段进 createServeSessionFactory({ hostShell })。缺席不落键 = kernel 缺省 detectHostShell()(win32 → powershell,其余 posix),既有部署零改动。对你意味着:跨平台装配 / 词法对齐时可显式钉方言;它只改判定方言,执行器实际派生的 shell 仍随平台。sdk 侧 CreateSessionOptions.hostShell? 归 RF-02c。

• ServeSessionDriverOptions.toolResultBudget?(RF-08c,核心组件设计审查 §2.8 装配矩阵;加法字段,一个导出签名变化 → 下一版至少 minor):驱动逐轮把它原样透传 runQuery.toolResultBudget(kernel ToolResultBudgetOptions:persist 落盘存根 / spill 内容寻址外置 / maxChars),缺席不落键 = kernel 缺省纯截断即此前行为。tansr serve / tansr acp 装配面自此与 TUI / headless 同款接线:工具结果超帽 → 会话目录 spill/ 落全文、历史里存根替身;压缩前 pre_compaction 快照落 <sessionDir>/checkpoints/<sid>/(--checkpoints-dir / TANSR_CHECKPOINTS_DIR / settings 独立根照旧生效)并签发 session.checkpointed。对你意味着:自托管宿主直构 ServeSessionDriver 时可选接同一预算件;不传者零变化。/v2 平台工厂自带 checkpointStore 时压缩前钩仍以平台持久化钩为准(后绑者胜)。

• /v2 客户端申报工具不受 kernel 中央入参校验影响(RF-08b,核心组件设计审查 RV-2-06;导出集零变化、wire 零变化):申报工具与 MCP 桥同律声明 argsValidation: 'remote'——本地 schema 只是申报投影(无 parameters 时为空对象 schema),调度器不剥参、不改权限 digest 输入,坏参仍由既有 execute 内自校以 tool.completed { isError: true }(invalid <name> args: …)出线,tool.request 照旧不下发。无需迁移。

• /v2 平台会话预算账本思考路逐行归账(RF-P3a,contract-v0.27 RFC-RF-3 阶段 2;导出集零变化、wire 零变化):init.budget 在场的会话账本自此按每一行的 (provider, model) 取 providers 内置能力表 quirks.reasoningTokens 处置思考 token——'separate' 行的思考量并入该行输出计量与计价,缺席 / 'subset_of_output' 行照旧(思考 ⊆ 输出,不叠加);会话内模型切换 / 子代理另选模型的行各按自身能力位,工厂不再持会话级能力位(RFC-RF-3 §6 serve 三径「休眠键」闭合)。当前内置表零 'separate' 行,已部署会话的 totalTokens / 金额逐字节零变化;server.platform.* 帧、GET /v2/sessions/:id 面不变。无需迁移。

会话级预算跨重启(RF-06b;五个导出签名变化):

• 会话级预算跨重启:init.budget 在场的会话每轮末随历史在 store 里落一条累计用量快照(内部事件记录,不进消息面 / 不进 SSE 历史页);resume 时内层追踪器自该快照续算,闸门读到的是历史消耗而非 0——「会话级预算」在进程重启 / 多实例接管后仍成立。预算缺席的会话零变化(不写、不读、不提示)。
• 快照落后于历史(进程在轮末快照前终止)时,resume 首连重放里多一帧 server.platform.warning{code:'usage_snapshot_stale'}(消息携落后消息数,server.v2.warning.usage_snapshot_stale);只丢末轮用量,不静默低报。
• 公共面加法字段(既有实现无需迁移;自实现 ServeAgentSessionStore 的宿主若想续算需自行保存 / 返回快照,否则退化为「每次 resume 从 0 起算」即此前行为):AgentStoreCommitMeta.usageSnapshot?(UsageSnapshotRecordPayload,来自 @tansr/kernel)、AgentStoredSessionRecord.usageSnapshot?(RestoredUsageSnapshot:payload + staleMessages)、ServeSessionExtras.usageSnapshot?(CostSnapshot,内层工厂续算起点)、ServeTurnEndInfo.costSnapshot?(内层预算在场时附带的轮末累计快照)、V2_CTX_PERSIST_MESSAGE_KEY.usageSnapshotStale。
• 内置文件 store:带预算的卷尾部含非消息记录(用量快照),历史分页在 RF-06b 时曾因此退出「尾部纯消息」快路全读回退;RF-P3b 已闭合(核 commit 的链尾见证 lastHash + recordCount + messages 与 readTail 吻合即取见证的消息数,快照记录在后缀与被跳过段里自然跳过,不再退全量读),只有无可信见证的旧卷 / 被外部写者动过的卷仍退全量读求精确——结果恒不变,GET /v2/sessions/:id/history 大卷读放大只余该兜底径(RF-Z ㉑ 复核)。

0.8.1 — 2026-09-11

• 统一系统媒体工具与平台提供方的说明，明确移动端工具在会话服务执行，用户主动转写/朗读与模型工具调用分别保留。
• 同步 SDK 媒体说明修正；不改变会话协议、能力授权、媒体产物、工具执行或计费行为，不新增公共导出。

0.8.0 — 2026-09-10

• 汇总此前未发布的 0.7.0 候选能力，并通过 v2 capabilities/inputs/status 接口提供严格同轮文本追加（INJ）；旧 v1/v2 messages 接口兼容。
• SDK 与 serve 共用输入接纳与回执机制，绑定 session/historyEpoch/turnId；丢失响应先查询原票，不通过隐式新轮重试。
• 手机重连原会话后，下一新轮继续自动加载平台提示词；轮中追加不刷新 system，不变更原权限、预算和会话归属。
• 资源排水与真实 settlement 分开；新增公共出口按 minor 推进至 0.8.0。旧 0.7.0 标签保留，正式发布状态以回执为准。

0.7.0

• AP-SP：平台工厂按 systemPromptPolicy=fallback|prepend 选择或拼接应用 systemPrompt 与 platform.system；prepend 下 [] 仍保留平台。platform.systemAppend 追加指南而不覆盖业务段。存活会话及移动端 attach 后的下一新轮自动条件核验平台正文和策略，轮中不变；失败不带旧配置请求模型，保留历史并可重试，取消/超时与令牌续期沿统一预检。移动端只发用户消息，不新增 system wire 字段。

历史候选归档：0.7.0 没有单独发布，以下内容并入 0.8.0；本地旧标签保留在原候选源码。十王修案 W1–W4 原收编于 cli main 9f09c1b7，实际发布以回执和 registry 为准。 导出集:exports.snapshot.json 由发版门首版基线 364(0.6.1 dist,W2 FX-C-25)→ W2 收编 375 → W3 收编 395(W3 回执 §一)→ W4 收编 395 (导出数不变,AssembledSessionModel / AgentSessionRetentionSweepInput 两签名变;W4 回执 §一)。以下逐条按波次的收编回执与 C-α / C-β 终报为事实源; 每条括注卡号(FX-C-nn)与所属波次。

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

• 平台下发的上下文方案与宿主配置合流后，由查询和压缩共同消费，恢复会话沿用同一有效配置；嵌套阈值只覆盖明确提供的值。owner/app_user 均按各自身份投影生效（CM-03）。
• 空闲或自动摘要即使被质量校验拒绝，已报告用量仍计入公共成本；小窗输出回退遵守测得正剩余，零/负估算余量保留原有恢复规则并明确提示（CM-02/06）。
• CLI serve 工厂按新会话的组织开关和规范化 cwd 绑定项目记忆，恢复到不匹配项目明确拒绝；独立平台工厂保持原有能力面，未隐式增加 CLI 自动记忆或 Read 工具（CM-01）。
• CLI serve 的 TTS 产物在成功和落盘失败两种情形均保持隐路径；失败仍返回已有音频，原始错误由工厂宿主的可选诊断回调消费。远端 SSE 不携该诊断，CLI 默认只记录安全事件与 errno（CM-10）。
• /v2 平台 ASR 代打在向上游发送前检查原始音频和实际 JSON 体积，越限不会发请求或触发无用刷新；入站 HTTP 体帽与出站平台预检分别生效（CM-11）。

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

• prepublishOnly 恒过 scripts/release/gate.mjs --package server 六步;exports.snapshot.json 基线入仓,自本版起导出集变化由门判 semver; tag 形 @tansr/serve@<version>(非目录名 server);发版回执 doc/release/serve-<version>.md。本文件即门 ③ 所指。

行为变化(收紧 / 修正;宿主须知)

• 建会临界区改票据形 beginCreate(FX-C-01 · W1):/v2 注册仓「合并 / 预留 / 登记」收为单一同步调用,AdoptFailure 经票据双向传, 同 sessionId 并发建会后到者 200 attach(此前 routes.ts:529 裸拒绝 → 500 / unhandledRejection)。宿主若自实现注册仓,按 BeginCreateResult / CreateTicket 形(registry 内部型,非公共导出)对齐;HTTP 消费方无需改动。
• /v2 注册仓事件泵抛错即关闭句柄(FX-C-03 · W1):泵死驱动死(driver.status() → 'ended'),不再静默挂起;新增计数 pumpErrors(治理统计)+ 指标 tansr_serve_pump_errors_total。
• /v2 四处兜底信封 message 改固定 i18n 词条(FX-C-04 · W1):错误原文(含本机路径)只进结构化日志 store.error / session.rejected, 不再出线到客户端;此前信封曾回显 open '/home/…/.tansr/sessions/x'。依赖 message 原文判因的客户端改读 error.code / detail。
• 裁决装配与 sdk 同源(FX-C-50 · W1 → W2 切换;M-01):PlatformAdjudicationOptions = Omit<AdjudicationOptions,'endUser'>;裁决段缺席通报 adjudicator_unavailable(ADJUDICATOR_UNAVAILABLE_CODE / _MESSAGE 与 sdk ADJUDICATOR_UNAVAILABLE_WARNING 同值);开发者向通报码 (DEVELOPER_ONLY_ADJUDICATOR_WARNINGS,六码)只走宿主 onAdjudicationWarning 通道不下发端上;姿态 / 模式经 kernel derivePosture / modeUnderAdjudicator({ posture, tier }) 单点推导——B 姿态 × 资格档 none 的会话不再切 auto(cwd 内写删从零咨询放行变为 ask → 无通道 deny),与 sdk 0.12.0 同律;机器放行帧 tool.permission.decided{allow, decisionSource} 经既有 driver 出线。
• /v2 纪元 gap 单点(FX-C-05 · W2):subscribe 判 afterSeq > lastSeq(客户端超前)亦发 gap 帧,ReplayGapNotice.reason? 加法键 (取值含 'ahead_of_log');MemorySessionEventLog.readAfter 同律双保险。此前超前订阅静默无 gap。
• 会话 store 切 kernel 单核(FX-C-06 · W2;R-11):serve 文件店改经 kernel createSessionStoreCore(pendingRewrite 持久闩 + 前缀校验 + rotate / append 单实现),与 sdk file-store 过同一份 runSessionStoreConformance;快照三法经 #checkpointQueue 串行。应急开关 TANSR_SESSION_STORE_CORE=legacy(常量 SESSION_STORE_CORE_ENV,与 sdk 同名同值;一版后删)。
• 落卷失败可见帧(FX-C-07 · W2;R-03 B 形):会话落盘失败不再只进日志——经 driver.pushBody 出 turn.error{ scope:'server.persistence', recoverable:true, errorKind:'store_commit_failed' | 'store_create_failed' };sdk 0.12.0 reducer 把 recoverable:true 归 SessionView.notices 不落 lastError。不新增 server.platform.warning 控制帧。端侧按 recoverable 位区分咨询 / 失败。
• 恢复会话的 cwd 缺省翻为 'stored'(FX-C-08 · W2 → W3 切换;R-04):配置了 cwdPolicy 的宿主 cwdOnResume 缺省由 'current' 改 'stored', 且 'stored' 重过策略闸——拒绝 → 409 cwd_unavailable{ detail.reason: 'not_allowed' | 'not_allowed_on_resume' | 'missing' | 'not_absolute' } (四值来自 kernel resolveSessionCwdSync / toSessionCwdGateResult,serve 不自写词表)。旋钮 TANSR_SERVE_CWD_ON_RESUME 可显式回 current。
• 会话保留期(FX-C-09 · W2 → W4 收尾;M-05):sessions.retention{ maxAgeDays, maxPerEndUser, maxBytes }(缺席 = 零删除)+ store.sweepRetention(serve 侧唯一物理删除点,日志事件 session.retention_swept)+ 注册仓第 ⑤ 段 onSweep 缝 + checkpoints.retention 透传; 旋钮 TANSR_SERVE_SESSION_MAX_AGE_DAYS / TANSR_SERVE_SESSION_MAX_PER_END_USER。W4 起 maxAgeDays 按 endUser 域真读 bundle governance.sessionRetentionDays(sdk AssembledPlatformModel.governance 透传;api R4 表行 tiers [owner, app_user]):装配产物 AssembledSessionModel.sessionRetentionDays?;store.sweepRetention({ policy, policyFor }) 中 AgentSessionRetentionSweepInput.policyFor?: (endUserKey) => AgentSessionRetentionPolicy | undefined(自实现 store 缺席该缝 = 现状);键缺席 / 坏形 → 30 d 兜底不变。进程重启后 retentionDaysByEndUser 热缓存为空 → 该域首扫按 30 d 直至再建会(W5 C-α「保留期落盘 meta.retentionDays」闭合)。
• 令牌失效反馈缝(FX-C-15 · W2 → W3 切换;R-02 / M-13):refreshingFetch 对携 x-tansr-app-token 的请求收到 401 且 error.code ∈ TOKEN_INVALIDATING_CODES(今日 ['unauthorized'])且 detail.reason ≠ 'check_unavailable' → AppTokenMinter.invalidate? 逐出 + 重铸 + 同请求重试恰一次;指标 tansr_serve_token_invalidations_total{reason},AppTokenMinterStats.invalidations?。W3 起常量与谓词 (isTokenInvalidatingCode / isTransientAppTokenReason)由 sdk platform/error-codes.generated.ts 生成件同源(api openapi x-tansr-error-codes[].x-invalidates-token),serve 不再手写码集(TOKEN_INVALIDATING_CODES / TOKEN_CHECK_UNAVAILABLE_REASON 仍从 serve 出口)。
• bundle 缓存键四维(FX-C-16 · W2;S-08):bundleKey(base, appId, scope, featuresFingerprint),不同径别 / 能力位组合不再串档; resolve / invalidate 入参 scope / clientFeatures,fetchAppBundle / fetchTwpHeartbeat 尾参。自实现 bundle 缓存的宿主按四维键改。
• R-18 α serve 半边真消费(FX-C-11 / FX-C-12 · W2):contextScheme → 压缩方案选项的唯一消费点落 createPlatformSessionAssembler (经 kernel contextSchemeToSchemeOptions,坏形 CONTEXT_SCHEME_UNPARSED 只走宿主通道);assembleAdjudicator({ postureExplicit? }) 随行 pricing(金额 budgets.maxUsd / maxCny 折算 callBudget 上界;不可折算通报);serve 声明集 CONSUMED_BUNDLE_KEYS 加 contextScheme / adjudicator.budgets / adjudicator.escalation / adjudicator.callBudget / governance.sessionRetentionDays, 与 api 消费方表(bundle-consumers.json revision 4)逐键对表(parity 卷 serve 侧零台账)。
• 历史分页对 fork 会话禁用尾装载快径(FX-B-24 serve 同形 · W2;C-09):getHistoryPage 对 forkedFrom 会话恒全量读,修正 total 偏 1 → 翻页洞; 新增 readForkedFrom 单点。API 形不变。
• 控制帧 wire 恒携 ts;三请求帧携 ttlMs(FX-C-22 serve 半边 · W3;contract-v0.26 / E2-12):registry.ts encodeAgentStreamFrame 控制帧 data = { ...payload, ts }(CONTROL_FRAME_TS_KEY,不属任一载荷键集);server.tool.request / permission.request / question.request 加 ttlMs(与 expiresAt 同在场性);权限回执 PermissionReceiptSchema.reason?(词表 PERMISSION_DENY_REASON = { expiredOnArrival: 'expired_on_arrival' },词表外 400,allow 携 reason 被忽略);AgentSessionBridgeOptions.onPermissionReceipt 缝 → 工厂结构化日志 bridge.permission_receipt。sdk contract/MANIFEST.json revision 2 → 3;端侧按 ttlMs 优先、expiresAt − skew 回落判期。
• /v2 观测路由单源(FX-C-45 · W3;S-04):V2_ROUTE_TABLE(21 端点)+ V2_SESSION_ACTIONS(11 动作)导出;request-context.ts 的 route 模板与分发正则皆从表生成——指标 / 日志 route 标签值集变 9 条(此前手写 7 动作模板与实际路径不一),仪表板 / 告警按新表随动。
• webhook 轮末通知双签一版(FX-C-43 · W3):x-tansr-signature: v2=…, v1=…(v2 = protocol WEBHOOK_SIGNATURE_V2 canonical + x-tansr-timestamp / x-tansr-nonce 两头;v1 保留一版供旧接收方)+ webhook.signatureVersions 配置(TurnEndNotifierOptions.signatureVersions?,缺省 DEFAULT_WEBHOOK_SIGNATURE_VERSIONS = ['v2','v1'];词表 WEBHOOK_SIGNATURE_VERSIONS);导出 signWebhookDelivery。接收方(tansrd / orchestrator parseSignatureHeader)任一版本接受、v2 在场只校 v2(防降级)、300 s 窗。v1 弃用时间表归发版令。
• 进程协议:就绪帧 TANSR_READY {json} + /readyz 探针 + 建会退避(FX-C-42 · W3;撤 FX-C-47 止血正则):ready-frame.ts 为唯一形态源 (TANSR_READY_PREFIX / TANSR_READY_FRAME_VERSION / formatReadyFrame / parseReadyFrame / emitReadyFrame + 型 ReadyFrame / ReadyFrameSink;StartServerOptions.readyFrame?);tansrd 池 readyFrom(line) 三形逐行消费(① 帧 → ② JSON 行 → ③ 文案行,③ 为旧 serve 兼容一版); /readyz 探针与 /healthz 在 CLI 入口恒开;建会 429 / 503 携 Retry-After → 池侧实例冷却(PoolLease.release({ retryAfterMs }))。 部署件探针建议由 /healthz 改 /readyz。
• 指标暴露拆旋钮(FX-C-42 · W3):TANSR_SERVE_EXPOSE_METRICS(独立于 TANSR_SERVE_EXPOSE_OBSERVABILITY)+ TANSR_SERVE_READY_STREAM (就绪帧写 stdout / stderr);SERVE_RUNTIME_ENV 表 23(W2 建表)→ 26(W2 C-α 三旋钮)→ 28 键,packages/server/README.md 区段与 .env.example 由表生成 (pnpm env:example / env:check / docs:check 锁住)。
• 轮末 webhook 出站两 env 旋钮(FX-C-09/续 · W5 续):SERVE_RUNTIME_ENV 28 → 30 键,新组 notify——TANSR_SERVE_NOTIFY_URL(新 kind string, 绝对 http(s) URL;非法忽略并告警)/ TANSR_SERVE_NOTIFY_SECRET(新 kind secret,取值恒不入告警 / 日志 / 生成物;只在 URL 生效时生效)→ resolveServeRuntimeOptions().v2.onTurnEndNotify?: { url, secret? };tansr serve --v2 透传进 startServer({ v2 }) 既有缝(serve 进程自此可自发 双签 webhook;此前只有库缝 / demo 宿主);无 URL = 不出站。新导出 SECRET_WARNING_VALUE + 型 ServeRuntimeEnvStringFormat; ServeRuntimeEnvKind 加 'string' | 'secret',ServeRuntimeEnvSpec 加 format? / requires?,ServeRuntimeV2Options 加 onTurnEndNotify?。
• 进程级兜底须由宿主入口安装(FX-C-02 · W1;S1):库内不自挂 unhandledRejection / uncaughtException;新导出 installProcessGuards + PROCESS_GUARD_POLICIES / DEFAULT_PROCESS_GUARD_DRAIN_TIMEOUT_MS / PROCESS_GUARD_STACK_MAX_CHARS / processGuardRecordOf + 型 ProcessGuard*;tansr serve / tansrd 入口安装 drain-exit 策略,acp / mcp-serve / headless / demo 安装 log 策略;旋钮 TANSR_SERVE_ON_UNHANDLED;日志事件 process.unhandled_rejection / process.uncaught_exception / process.drain_failed。自托管 @tansr/serve 的宿主须在入口调 installProcessGuards,否则未处理拒绝按 Node 缺省崩溃(0.6.x 同,无回归)。

加法(公共导出;皆可选,缺席 = 现状)

• AgentSessionFactory.sweepRetention? / AgentSessionFactoryBuild.sweepSessionRetention / sessions.retention 选项 + 5 型 + 2 常量(FX-C-09)。
• AppTokenMinter.invalidate? / AppTokenMinterStats.invalidations? / CreatePlatformSessionAssemblerOptions.metrics?(FX-C-15)。
• AssembledSessionModel.onAdjudicationWarning? / PlatformServeSessionFactoryOptions.onDecision?(FX-C-50 审计缝)。
• AssembledSessionModel.sessionRetentionDays? / AgentSessionRetentionSweepInput.policyFor?(FX-C-09 收尾 M-05;W4 两签名变)。
• ReplayGapNotice.reason?(FX-C-05)· PermissionReceiptSchema.reason? / PermissionDenyReason / PERMISSION_DENY_REASON(FX-C-22)。
• ready-frame.ts 7 项 + StartServerOptions.readyFrame?(FX-C-42)· WEBHOOK_SIGNATURE_VERSIONS / DEFAULT_WEBHOOK_SIGNATURE_VERSIONS / signWebhookDelivery / TurnEndNotifierOptions.signatureVersions?(FX-C-43)· V2_ROUTE_TABLE / V2_SESSION_ACTIONS + 型 V2RouteEntry / V2RouteMethod / V2SessionAction(FX-C-45)。
• installProcessGuards 一族(FX-C-02)· SESSION_STORE_CORE_ENV(FX-C-06)· TOKEN_INVALIDATING_CODES / TOKEN_CHECK_UNAVAILABLE_REASON (FX-C-15;W3 起转出口 sdk 生成件)· ADJUDICATOR_UNAVAILABLE_CODE / ADJUDICATOR_UNAVAILABLE_MESSAGE / DEVELOPER_ONLY_ADJUDICATOR_WARNINGS (FX-C-50)。
• 指标:tansr_serve_pump_errors_total(FX-C-03)· tansr_serve_token_invalidations_total{reason}(FX-C-15)。日志事件:process.* 三名(FX-C-02)· store.error(FX-C-04)· session.retention_swept(FX-C-09)· bridge.permission_receipt(FX-C-22)。

随包(发布链;FX-C-28 / FX-C-29 · W4)

• tarball 随附 NOTICE(files +NOTICE;内联第三方 undici / zod-to-json-schema 版本 · 许可 · 许可文本,由 pnpm release:verify-notice 按真构建 metafile 生成,--check 逐字节幂等);运行时外部依赖恒 = package.json dependencies(今日 zod),build.mjs external 由此生成, banner 改口指向 NOTICE(此前误称「唯一第三方依赖 zod」)。pack-serve 守卫 ⓪ verify-notice / ② external 同源 / ④ 白名单 +NOTICE。

配套(CLI 宿主面;详见仓根 CHANGELOG.md)

• tansr serve --v2 / TANSR_SERVE_V2=1 显式挂 /v2 面(缺省关零变;鉴权 = 同一 Bearer + x-tansr-end-user 自报分域)+ 工厂 cwdRebinder 缺省接线(FX-C-46 · W3);acp session/new | load cwd 经同一 kernel 闸(FX-C-44 · W3);tansr serve 入口安装进程守卫(FX-C-02)。

0.6.1 (2026-09-06)

• 追溯登记(FX-C-25;当时未发回执、无 tag):IO-14 存储出口补齐——createFsBlobStore / createChaosBlobStore / runStorageConformance 及类型经 @tansr/serve 再出口(与 @tansr/sdk@0.11.1 同笔;此前 demo 与第三方适配器被迫直装私有 kernel)。patch 却携新公共导出,按 doc/89 §3.3 0.x 口径应为 minor;误发已成事实,不回收,自 0.7.0 起由发版门 ④ 步机器禁止。发版门首版基线 364 导出即以本版 dist 为准。
• 无其他行为变化。

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

• 追溯登记:自 0.5.0(2026-09-02,/v2 控制帧四族七名 server.platform.warning 下发端上)以来——会话持久化一期二期(/v2 会话 store / fork / resume)、权限裁决姿态与裁决协议 v4 / 应用协议、音频模态与媒体能力内核化、套餐 plan 端上、MCP 重连契约 v0.21–v0.24;详见 doc/98(/v2 契约)与 doc/49 回执。本文件自 0.7.0 起逐版机器化。

이 페이지가 도움이 되었나요?

예아니요