# 变更日志

接口、事件、SDK、CLI 与 manifest 的每一次变化，最新的在前。v1 内只加不改；要删的先弃用，至少 6 个月。

## 2026-11-06

### k3 命令：查看部署、比例灰度、回退，退出码可用于流水线

类别：CLI

k3 deployments 和 k3 deployment <id> 查看应用的部署：状态、版本、操作者、时间、范围，以及步骤、没有升级的租户按原因计数和监测窗口里新旧版本的数字，没有的数字显示为 —，不含租户 id。k3 rollout <version> --percent n [--max-5xx] [--min-requests] 开始灰度，k3 rollout advance <percent> 和 k3 rollout abort 找到正在进行的那一个。k3 rollback 找到现在在用的部署，显示从哪个版本退到哪个版本以及留在原地的迁移，不加 --yes 就询问，标准输入不是终端时从不询问；迁移里有旧版本可能无法运行的改动时，只加 --yes 会被拒绝，要再加 --accept-contract。rollout 和 advance 的 --wait 跟随到监测有了结论，灰度被中止或超过 --timeout 则退出码为 1。退出码：0 完成，1 失败、被中止、被拒绝或超时，2 用法错误。

### 托管应用的比例灰度：按比例放量，出问题自动退回

类别：接口

POST /api/dev/apps/{id}/versions/{version}/rollout 把已批准的版本给一定比例的租户，POST …/deployments/{did}/advance 提高比例，只增加租户，同一个比例永远是同一批租户。关了自动升级、要先同意、管理员在灰度期间自己选了版本的租户不动，都按原因计数。新安装拿到已发布的版本。发布就是 100% 并结束灰度，/abort 和发布后的 /rollback 照常可用。灰度进行中不能发布别的版本，也不能再开指定租户的灰度。平台按分钟统计每个版本的请求、5xx 和不可用：最近 10 分钟 5xx 占比超过 autoAbort.max5xx（默认 2%）且请求不少于 autoAbort.minRequests（默认 100），或进程持续 5 分钟不在运行，就自动中止，记录里 by 是 system，reason 里有当时的数字，你们的组织会收到通知。部署详情并排给出新旧版本的计数，不含租户 id。

### 部署记录、开发者回滚和中止灰度；要同意的版本不再自动移动

类别：接口

每次发布、灰度、回滚、中止和撤回都留一条部署记录：GET /api/dev/apps/{id}/deployments 和 /{did}，记录里只有数量，没有租户 id，只有你们自己的测试企业会列出来。POST …/deployments/{did}/rollback 把这次部署之前的版本再部署一次，不走审核，只能回到发布过且没有被撤回的版本，只有造成当前已发布版本的那次部署能回滚。POST …/deployments/{did}/abort 中止进行中的灰度，每个租户回到它原来的版本，这个版本仍是已批准。迁移不会撤销：一个应用的所有版本共用一个模式，回到的版本要能在现在的模式上运行；部署详情和回滚的应答列出没有撤销的迁移，有破坏性变更时给出警告。行为变化：发布和灰度不再移动这样的安装：新版本要的权限比它现在的版本多（能力、权限点、范围），它们留在原版本，等管理员同意后自己升级。灰度不再移动关了自动升级的租户。这两种都按原因计数，见应答的 stayed。灰度的应答去掉了 movedTenants，改为数量 moved。站点：GET /api/sites/{id}/deployments，发布旧版本记为回滚。

## 2026-11-04

### 开放接口的旧地址删除，请求返回 404

类别：接口

/k3/open/v1/…（任何路由）和第一个令牌端点 POST /open/v1/token（HTTP Basic，包括 POST /k3/open/v1/token）今天删除，请求返回 404，不再带 Deprecation 与 Sunset。请使用 /open/v1/…，令牌用 POST /open/v1/oauth/token（grant_type=client_credentials，应答是 access_token、token_type、expires_in、scope）；客户令牌用 grant_type=urn:raise:grant-type:customer 加 phone。客户接口 /open/v1/me/* 只在会员应用的域名 membership.apps.{域名} 上，api.{域名} 上是 404。见「接口约定与错误处理」的「旧地址已删除」。

## 2026-11-02

### Go SDK raise-go 与 TypeScript SDK @21stware/raise-sdk 发布 0.7.6

类别：SDK

k3：清单声明了 services 或 events.receives 却没有 opsApi 时，Manifest.Validate 拒绝它；清单的 platform 字段写应用需要的平台 API 版本范围（k3.PlatformAPI、ParsePlatformRange、Manifest.CheckPlatform）；app.uninstalled 是数据事件（appkit.EventAppUninstalled）。access：Lister 与 NodeReader（Client.Tree()），AccessListening 听 access.changed。生成的客户端新增三个原始字节的操作：client.App.Blobs.Put、client.App.Blobs.Get 与 client.App.Models.Transcribe。套件：raise-doc-kit 0.3.0、raise-pages-ui 0.2.0。这是目前的最新版本，需要平台 API 1.2.0 以上（见「应用接口」的兼容矩阵）。逐项见 sdk/go/CHANGELOG.md。

### 数据事件新增 app.uninstalled，customer.merged 发给任何声明了它的应用

类别：Manifest

清单 events.receives 可以写 app.uninstalled：企业卸载本应用时，平台在 POST /k3/events/app.uninstalled 告诉这个应用，subject 是应用自己的 id，至少一次，与 tenant.deleted、site.deleted、customer.merged 走同一条路。卸载不删数据，留什么由应用决定。customer.merged 发给每个声明了它、装在这个企业里的应用。见「应用接口」的「平台的数据事件」。

### Go SDK raise-go 与 TypeScript SDK @21stware/raise-sdk 发布 0.7.5

类别：SDK

access：树形类型带上云盘原来自己记的规则（条目可以到期，根的 Private、KeepManager、Reshare、AlwaysInherit），根与节点有名字（RootSpec.Name、NodeSpec.Name），SetInherit 让节点停止或恢复继承。k3：资源类型的 name、nameEn，用 GET /app/v1/access/{type} 读回；平台的断言带 agent 与 origin。appkit：助手经独立进程的应用读草稿（只读、脱敏）；提供方的拒绝带机器可读的 code。逐项见 sdk/go/CHANGELOG.md。

### 原 /k3/app/… 的 12 个路径删除，请求返回 404

类别：接口

作为别名保留、响应带 Deprecation: true 的 12 个路径，今天删除。请使用 /app/v1。

### 应用接口新增三个路由：一次问多个权限点、解析一句话、上报导入的行

类别：接口

POST /app/v1/access/points（范围 app.access:read）一次问 1 到 100 个权限点，答案与逐个调用 GET /access 相同，不缓存。POST /app/v1/intent/parse（范围 app.intent:parse）只收页面会话，只解析本应用的操作，不写任何东西，调了模型按用量计入企业；应用自己的令牌返回 403。POST /app/v1/imports/{batch}/items（范围 app.imports:write）由应用上报导入的每一行，平台把这一批列在管理员的批次页并写来源；只有租户管理员的页面会话可以上报。站点动作的请求总带 unit，规格要求时带 openid、appid 与 referrer，访客的 IP 只以哈希出现。

### Go SDK raise-go 与 TypeScript SDK @21stware/raise-sdk 发布 0.7.4

类别：SDK

Go 新增 AccessMany、AccessBatcher、Authz.CheckMany（一次最多 100 个权限点）、Client.Imports() 与 Report、Client.Intent()；站点动作的请求带 Unit，规格要求时带 AppID、OpenID 与 Referrer。生成的客户端新增 client.App.Access.CheckMany 与 client.App.Intent.Parse。逐项见 sdk/go/CHANGELOG.md。

### 清单与接口：分享由访问内核保管，资源类型有分享对话框用的名字

类别：Manifest

清单 resources[] 新增 name 与 nameEn（各不超过 20 个字符），GET /app/v1/access/{type} 读回声明的种类，PUT /app/v1/access/{type}/{id}/inherit 让树形类型的节点停止或恢复继承。谁能访问的名单由访问内核保管，也只在内核里改；平台的分享对话框用这个人的页面会话读写，应用自己的令牌调用分享的路由返回 403。名单变化后，应用收到 access.changed {type, id}，留有名单派生物的应用此时从内核重读。见「应用接口」。

## 2026-10-31

### 新增应用接口 /app/v1：已安装的应用向平台要客户、记账、审计、事件和记录链接

类别：接口

与 /open/v1 同一套约定（错误信封、Idempotency-Key、限流头、请求日志）。令牌是应用自己的租户令牌或使用应用页面的人的页面会话，客户令牌返回 403 forbidden。每个路由需要一个 app.* 范围，范围必须写在应用清单的 uses 里。新路由 POST /app/v1/events/emit、GET /app/v1/links、GET /app/v1/links/resolve。原 /k3/app/… 的 12 个路径保留为别名，响应带 Deprecation: true。清单新增 uses、events.emits、providers（sources、referrer、links、deals）与 siteActions，都随版本审核。见「应用接口」。

## 2026-10-28

### 统一的调用地址 https://api.{域名}/open/v1 与令牌地址 POST /open/v1/oauth/token

类别：接口

grant_type=client_credentials 换租户令牌（300 秒），urn:raise:grant-type:customer 换客户令牌（900 秒）；凭证用 HTTP Basic 或放在正文里，正文收表单或 JSON。

### 破坏性：所有错误改为同一个信封

类别：接口

状态 ≥ 400 的正文都是 {"error": {"code", "message", "requestId", "docUrl", "details"}}。以前平铺的 {"error": "…"} 不再返回：按 error.code 分支，不要解析 message。code 共 32 个，列在「接口约定与错误处理」。

### 测试密钥与正式密钥分开：kwo_test_ 只进测试企业，kwo_live_ 只进真实租户

类别：接口

用错了回答 403 wrong_environment。每个响应带 Raise-Environment: test|live。以前发的 kwo_ 开头的密钥按正式密钥处理。

### 每个 POST 收 Idempotency-Key；每次调用带 X-Request-Id 和 X-RateLimit-* 头

类别：接口

同一把键 24 小时内重放第一次的回答（Idempotent-Replayed: true），正文不同是 409 idempotency_conflict。429 另带 Retry-After。

### 多维表的行接口按统一的列表形状回答

类别：接口

列出行是 {"data": […], "nextCursor": "…" 或 null}，用 limit 与 cursor 翻页；读一行直接返回这一行。

### 新事件：app.installed、app.upgraded、app.uninstalled、app.scopes_changed

类别：事件

只发给应用自己的开发者订阅，不需要范围；信封带 tenant、environment、app 和 apiVersion。商店应用装进你的测试企业时也会收到 app.installed。

### Go SDK github.com/21stware/raise-go 发布 v0.1.0

类别：SDK

令牌自动换取、按租户缓存、到期前 60 秒刷新；429 与 5xx 自动重试；POST 自动带 Idempotency-Key；游标迭代器；类型化错误 *raise.Error；webhook 验签；ForCustomer 进入客户模式。

### TypeScript SDK @21stware/raise-sdk 发布 0.1.0，平台另托管一份

类别：SDK

Node 18+ 与边缘运行时，没有外部依赖。平台在 /dl/sdk/ 提供 npm 包、在 /dl/go/ 提供 Go 模块代理，内网也能装。/dl/go/ 只有平台构建时带的那个 raise-go 版本（通常是最新版），别的版本答 404，由 GOPROXY 里的下一个代理（例如 proxy.golang.org）提供。

### k3 新命令：credentials、logs、test-enterprise

类别：CLI

k3 credentials list|create|rotate|revoke 管理应用密钥（新密钥只打印一次）；k3 logs 看最近 7 天的调用，--follow 持续跟随；k3 test-enterprise list|create|users|signin 管理测试企业与测试员工。