@wovoon/polaris 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PROTOCOL.md CHANGED
@@ -34,7 +34,7 @@
34
34
 
35
35
  | 字段 | 类型 | 必填 | 规则 |
36
36
  |---|---|---|---|
37
- | `backend` | string | 否 | `platform` / `external`;仅 Web 可声明 external,前端始终平台托管,自建后端独立维护 |
37
+ | `backend` | string | 否 | 仅支持 `platform`;省略时使用平台默认模式 |
38
38
  | `protocol` | integer | 否(默认 1) | 当前仅支持 `1`;其他值在上传扫描时被拒绝 |
39
39
  | `capabilities` | string[] | 否 | 能力声明,见下表;集合能力形如 `collection:<name>`,name 为 2-32 位小写字母开头的小写字母/数字/下划线。竞技扩展(协议 1 追加):`room:competitive`(房间上行 30Hz/8KB/二进制帧)、`gamelogic`(权威房间逻辑 roomservers/<mode>.js,见 docs/recipes/competitive-games.md) |
40
40
  | `entry` | string | 否 | **入口声明**:包内相对路径的 HTML(如 `game/index.html`,不得以 `/` 开头或含 `..`)。多入口/壳结构作品(典型:TapTap H5 导出包根目录是加载器壳、真游戏在 `game/` 子目录)必须声明真实入口;未声明时平台按"入口页本地引用可解析比例"自动识别并可能给出建议。声明了不存在/非 HTML 的入口会在托管时被拒绝(报错自带修复指引) |
@@ -56,7 +56,7 @@
56
56
 
57
57
  - 作品经平台安全扫描与内容审核后,由平台静态托管(受控运行域),在**沙箱 iframe** 中运行(平台隔离运行域保留 allow-same-origin,平台前台同源场景使用不透明源);
58
58
  - 玩家通过平台"开始游玩"获得**运行票据**;作品内 SDK 以票据换取身份与能力授权;
59
- - Web 应用可声明 `backend: "external"`,由平台托管前端、创作者自行部署后端;前端直接通过 HTTPS / WSS 连接后端,仍遵循沙箱与运行会话规则。
59
+ - 网络业务通过平台 SDK 使用 Wovoon 云能力,仍遵循沙箱与运行会话规则。
60
60
 
61
61
  ## 4. 能力契约(Capability APIs)
62
62
 
@@ -107,14 +107,9 @@
107
107
  - `join` 只影响返回嵌入,不改变主查询的 where/orderBy/limit/分页;对连接字段做过滤请用云函数组合;
108
108
  - 包体:静态托管默认上限 4GB / 100,000 文件(可配置覆盖)。
109
109
 
110
- ## 自建后端 Web 应用(协议 1)
110
+ ## 平台后端与迁移
111
111
 
112
- 可选字段 `backend` 支持 `"platform"`、`"external"`,省略兼容旧协议。`external` 仅用于 Web:上传静态前端,后端独立部署。纯自建后端无需平台 SDK 或云能力;需要混合使用平台云能力时仍按实际调用声明 `capabilities`。
112
+ 作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
113
113
 
114
- ```json
115
- {"protocol":1,"backend":"external","capabilities":[]}
116
- ```
117
-
118
- 前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
114
+ 已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
119
115
 
120
- 平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
package/README.md CHANGED
@@ -26,15 +26,11 @@ room.send({ text: "你好" });
26
26
 
27
27
  零构建页面可直接用平台同源下发的全局版:`<script src="/api/cloud/sdk.js"></script>` → `WovoonCloud.*`。
28
28
 
29
- ## 自建后端 Web 应用
29
+ ## 平台后端与迁移
30
30
 
31
- 从 0.6.1 起,`WovoonManifest` 类型支持可选的 `backend: "platform" | "external"`。自建后端模式将 Web 静态前端上传并托管到 wovoon,后端和数据库由作者自行部署:
31
+ 作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
32
32
 
33
- ```json
34
- {"protocol":1,"backend":"external","capabilities":[]}
35
- ```
36
-
37
- 纯自建后端无需平台 SDK;同时调用平台能力时按实际用途声明 `capabilities`。前端使用绝对 HTTPS API / WSS 地址,后端配置实际运行域名的 CORS、WebSocket Origin 和独立身份校验。服务端密钥不进入前端包,平台 Cookie、令牌与运行票据不发送给外部后端。本地清单校验使用 `@wovoon/cli` 0.12.6 或更高版本。
33
+ 已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
38
34
 
39
35
  ## 资源打包最佳实践(大游戏必读)
40
36
 
package/dist/client.d.ts CHANGED
@@ -2,7 +2,7 @@ import { PolarisAds } from "./ads.js";
2
2
  import { PolarisCommerce } from "./commerce.js";
3
3
  import { PolarisGame, type GameOptions } from "./game.js";
4
4
  export interface PolarisRequestInit {
5
- /** 覆盖 API 基址(本地模拟器/自建环境用),默认同源。 */
5
+ /** 覆盖 API 基址(本地模拟器/平台测试环境用),默认同源。 */
6
6
  baseUrl?: string;
7
7
  }
8
8
  export declare class PolarisError extends Error {
@@ -19,8 +19,8 @@ export interface WovoonManifest {
19
19
  protocol?: typeof WOVOON_PROTOCOL_VERSION;
20
20
  /** 包内 HTML 入口相对路径,例如 game/index.html;不可包含 .. 或以 / 开头。 */
21
21
  entry?: string;
22
- /** Web 前端仍由平台托管;external 表示使用创作者自行部署的后端,可同时声明实际使用的平台能力。 */
23
- backend?: "platform" | "external";
22
+ /** 在线玩法统一使用平台后端;省略时兼容已有平台作品。 */
23
+ backend?: "platform";
24
24
  /** 声明使用的能力;未声明的能力在对应服务上线后不可调用。 */
25
25
  capabilities?: WovoonCapability[];
26
26
  }
package/docs/cli.md CHANGED
@@ -1,4 +1,4 @@
1
- # wovoon CLI 参考(CLI 0.22.0)
1
+ # wovoon CLI 参考(CLI 0.23.0)
2
2
 
3
3
  ```
4
4
  wovoon init [目录] [--template minimal|game|arena|mode|rewarded] [--name 名称]
@@ -6,7 +6,7 @@ wovoon preview [目录] [--target web|mobile] [--player 玩家名]
6
6
  wovoon validate [目录] [--json]
7
7
  ```
8
8
 
9
- SDK 依赖固定为 @wovoon/polaris 0.15.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
9
+ SDK 依赖固定为 @wovoon/polaris 0.16.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
10
10
 
11
11
  作品激励广告使用 `wovoon ads init/status/plan/apply` 管理 `wovoon.ads.json`,只有作品所有者可同步正式奖励规则。该文件不会随作品公开发布。`rewarded` 模板和顷悟模拟预览无需广告联盟密钥,见 [激励接入](ads.md)。
12
12
 
package/docs/errors.md CHANGED
@@ -181,4 +181,4 @@ API 错误响应形态:`{"success":false,"message":"…","code":"…"}`,SDK
181
181
 
182
182
  ### manifest-backend
183
183
 
184
- `backend` 只接受 `platform` 或 `external`;自建后端 Web 应用使用 `external`,前端仍上传到 Wovoon 托管。不是后端 URL,不接受对象、空值或其他字符串。
184
+ `backend` 仅接受 `platform`;其他值均拒绝,需完成平台适配后重新打包。不是后端 URL,不接受对象、空值或其他字符串。
package/docs/manifest.md CHANGED
@@ -19,7 +19,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
19
19
 
20
20
  | 字段 | 类型 | 必填 | 说明 |
21
21
  |---|---|---|---|
22
- | `backend` | 字符串 | 否 | `platform` / `external`;external 表示自建后端 Web 应用,前端仍托管于平台 |
22
+ | `backend` | string | 否 | 仅支持 `platform`;省略时使用平台默认模式 |
23
23
  | `entry` | 字符串 | 否 | 包内 HTML 相对路径,不得以 `/` 开头或包含 `..` |
24
24
  | `protocol` | 整数 | 否 | 协议版本,当前唯一支持 `1`;缺省为 1 |
25
25
  | `capabilities` | 字符串数组 | 否 | 声明的能力;缺省为空 |
@@ -52,7 +52,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
52
52
  3. 必须是 JSON 对象(不能是数组/字符串/数字);
53
53
  4. 只允许 `protocol`、`capabilities`、`entry` 与 `backend` 字段;
54
54
  5. `protocol` 存在时必须是整数 `1`;
55
- 6. `backend` 存在时只支持 `platform` 或 `external`;
55
+ 6. `backend` 存在时只支持 `platform`;
56
56
  7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|room:competitive|gamelogic|ads|commerce|collection:[a-z][a-z0-9_]{1,31})$`。
57
57
 
58
58
  本地预检:`wovoon validate`(规则镜像,报错文案与线上一字不差)。
@@ -66,14 +66,9 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
66
66
 
67
67
  - **不发布**:`.wovoon` 只用于平台识别,不会随静态站点对外发布(`.wovoongame`、`.DS_Store`、`__MACOSX/` 同样跳过)。
68
68
 
69
- ## 自建后端 Web 应用(协议 1)
69
+ ## 平台后端与迁移
70
70
 
71
- 可选字段 `backend` 支持 `"platform"`、`"external"`,省略兼容旧协议。`external` 仅用于 Web:上传静态前端,后端独立部署。纯自建后端无需平台 SDK 或云能力;需要混合使用平台云能力时仍按实际调用声明 `capabilities`。
71
+ 作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
72
72
 
73
- ```json
74
- {"protocol":1,"backend":"external","capabilities":[]}
75
- ```
76
-
77
- 前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
73
+ 已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
78
74
 
79
- 平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
@@ -59,7 +59,7 @@ renderBalance(spent.balanceAfter);
59
59
 
60
60
  `consumeReward` 原子扣减、不允许负余额;同 ID 同参数返回原结果,不重复扣减;
61
61
  同 ID 改参数拒绝。API 不向客户端提供加奖接口。余额属于服务器账本,不等同于任意游戏
62
- 存档里的金币;有自建后端的游戏应由业务服务器按操作 ID 处理实际道具,不能信任客户端通知。
62
+ 存档里的金币;实际道具应由平台服务端逻辑按操作 ID 幂等处理,不能信任客户端通知。
63
63
 
64
64
  当前版本通过 `ads.consumeReward` 幂等消费作品奖励;不提供把广告奖励消费与权威房间 SERVER 集合写入合并的 `ctx.settle` 接口。不要向 `ctx.settle` 传 `rewardKey`,也不能以客户端自报结果向权威房间发放道具。
65
65
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wovoon/polaris",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端(身份/数据集合/云函数/房间实时),协议 1",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",