@wovoon/polaris 0.6.1 → 0.6.2
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/LICENSE +21 -0
- package/PROTOCOL.md +114 -0
- package/README.md +2 -2
- package/dist/client.d.ts +16 -0
- package/dist/client.js +56 -13
- package/dist/index.d.ts +1 -4
- package/dist/index.js +1 -4
- package/dist/protocol.d.ts +9 -2
- package/docs/cli.md +105 -0
- package/docs/errors.md +184 -0
- package/docs/index.md +65 -0
- package/docs/manifest.md +74 -0
- package/docs/quickstart.md +194 -0
- package/docs/recipes/competitive-games.md +55 -0
- package/docs/recipes/express-to-cloud.md +70 -0
- package/docs/recipes/localstorage-to-cloud.md +68 -0
- package/docs/recipes/relational-data.md +89 -0
- package/docs/recipes/static-site-add-manifest.md +50 -0
- package/docs/recipes/taptap-h5.md +41 -0
- package/docs/recipes/web-asset-optimization.md +77 -0
- package/docs/sdk.md +165 -0
- package/llms.txt +42 -0
- package/package.json +10 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 wovoon contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/PROTOCOL.md
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# wovoon 平台协议 v1(Polaris)
|
|
2
|
+
|
|
3
|
+
> 本文件是 wovoon 开发者协议的**正典定义**(canonical spec)。前端永远静态托管;后端能力由 wovoon 大后台按本协议提供。
|
|
4
|
+
> 版本规则:协议字段一经发布**只加不改不删**;破坏性变更必须升协议版本号。
|
|
5
|
+
> 本协议面向人类与 AI coding 工具同等优化:任何 LLM 依据本文档即可完成开发与改造。
|
|
6
|
+
|
|
7
|
+
## 1. 包契约(Package Contract)
|
|
8
|
+
|
|
9
|
+
作品以静态归档提交(ZIP / TAR.GZ / TGZ,≤2 GB),须满足:
|
|
10
|
+
|
|
11
|
+
| 项 | 要求 |
|
|
12
|
+
|---|---|
|
|
13
|
+
| 入口 | 根目录(或唯一一级子目录根)存在 `index.html` |
|
|
14
|
+
| 平台标识 | 归档内存在 `.wovoon` 文件(任意层级;建议根目录)。**缺失则无法提交审核**。旧名 `.wovoongame` 作为别名继续接受,新作品一律用 `.wovoon` |
|
|
15
|
+
| 文件类型 | 静态托管文件白名单(html/js/css/图片/音视频等);`.wovoon`、`.DS_Store`、`__MACOSX/` 被静默忽略不发布 |
|
|
16
|
+
| 禁止 | 隐藏文件(除上述忽略项)、符号链接、凭据文件(`.env`、私钥等,扫描直接拦截) |
|
|
17
|
+
|
|
18
|
+
## 2. `.wovoon` 清单(Manifest)
|
|
19
|
+
|
|
20
|
+
- **空文件** = 使用协议 1 默认(等价于 `{"protocol":1}`),完全向后兼容;
|
|
21
|
+
- 非空时必须是 **UTF-8 JSON 对象**,≤4 KB,字段如下:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"protocol": 1,
|
|
26
|
+
"entry": "game/index.html",
|
|
27
|
+
"capabilities": ["identity", "collection:scores", "function", "room"]
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
| 字段 | 类型 | 必填 | 规则 |
|
|
32
|
+
|---|---|---|---|
|
|
33
|
+
| `backend` | string | 否 | `platform` / `external`;仅 Web 可声明 external,前端始终平台托管,自建后端独立维护 |
|
|
34
|
+
| `protocol` | integer | 否(默认 1) | 当前仅支持 `1`;其他值在上传扫描时被拒绝 |
|
|
35
|
+
| `capabilities` | string[] | 否 | 能力声明,见下表;集合能力形如 `collection:<name>`,name 为 2-32 位小写字母开头的小写字母/数字/下划线。竞技扩展(协议 1 追加):`room:competitive`(房间上行 30Hz/8KB/二进制帧)、`gamelogic`(权威房间逻辑 roomservers/<mode>.js,见 docs/recipes/competitive-games.md) |
|
|
36
|
+
| `entry` | string | 否 | **入口声明**:包内相对路径的 HTML(如 `game/index.html`,不得以 `/` 开头或含 `..`)。多入口/壳结构作品(典型:TapTap H5 导出包根目录是加载器壳、真游戏在 `game/` 子目录)必须声明真实入口;未声明时平台按"入口页本地引用可解析比例"自动识别并可能给出建议。声明了不存在/非 HTML 的入口会在托管时被拒绝(报错自带修复指引) |
|
|
37
|
+
|
|
38
|
+
**能力命名(协议 1 冻结,即公共 API,永不改名)**:
|
|
39
|
+
|
|
40
|
+
| 能力 | 含义 | 状态 |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `identity` | 玩家身份:运行票据换取每作品稳定 `playerId`(等同 openid 语义) | 已实现 |
|
|
43
|
+
| `collection:<name>` | 数据集合:带权限规则(读 WORLD/PLAYER,写 OWNER/SERVER)的 JSON 文档 CRUD 与排序查询 | 已实现 |
|
|
44
|
+
| `function` | 云函数:服务端权威逻辑(受限 Node 沙箱) | 已实现 |
|
|
45
|
+
| `room` | 房间实时通道:WebSocket 消息中继(多人在线) | 已实现 |
|
|
46
|
+
|
|
47
|
+
- 未知顶层字段、非法能力名、非法 JSON、不支持协议版本 → **上传扫描直接拒绝**,报错信息包含修复指引;
|
|
48
|
+
- 能力声明将在对应服务上线后成为**调用前置条件**(未声明则接口拒绝)。
|
|
49
|
+
|
|
50
|
+
## 3. 运行契约(Runtime Contract)
|
|
51
|
+
|
|
52
|
+
- 作品经平台安全扫描与内容审核后,由平台静态托管(受控运行域),在**沙箱 iframe** 中运行(平台隔离运行域保留 allow-same-origin,平台前台同源场景使用不透明源);
|
|
53
|
+
- 玩家通过平台"开始游玩"获得**运行票据**;作品内 SDK 以票据换取身份与能力授权;
|
|
54
|
+
- Web 应用可声明 `backend: "external"`,由平台托管前端、创作者自行部署后端;前端直接通过 HTTPS / WSS 连接后端,仍遵循沙箱与运行会话规则。
|
|
55
|
+
|
|
56
|
+
## 4. 能力契约(Capability APIs)
|
|
57
|
+
|
|
58
|
+
协议 1 的能力 API 面由 `@wovoon/polaris` SDK(本仓库)承载,数据形状:
|
|
59
|
+
|
|
60
|
+
- `identity`:`POST /api/cloud/session` → `{appId, playerId, loggedIn, displayName, avatarUrl}`;
|
|
61
|
+
- `collection:<name>`:`/api/cloud/{app}/collections/{name}/docs` 的 CRUD + `?orderBy=<field>&order=desc&limit=` 数值排序;
|
|
62
|
+
- `function` / `room`:M3 交付后在此定稿(先占名,不改名)。
|
|
63
|
+
|
|
64
|
+
## 5. 错误风格(对 AI 工具的关键约定)
|
|
65
|
+
|
|
66
|
+
所有协议类拒绝(缺标识、manifest 非法、能力未声明等)的报错必须包含:**缺什么 + 怎么修 + 规范锚点**。示例:
|
|
67
|
+
|
|
68
|
+
> 未在作品包中检测到 .wovoon 标识文件,请检查作品包是否支持在 wovoon 上运行(可在包根目录添加 .wovoon 文件后重新上传)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
## 云函数(function,协议 1)
|
|
72
|
+
|
|
73
|
+
- 作品包站点根下 `functions/<name>.js`(CommonJS),文件名即函数名(2-31 位小写字母开头);
|
|
74
|
+
- 每作品最多 16 个、单文件 64KB、总量 256KB;`.wovoon` 声明 `function` 能力即可调用;
|
|
75
|
+
- 形态:`exports.main = async (event, context) => (任意 JSON)`;入参/返回 ≤32KB;
|
|
76
|
+
- 沙箱:默认限时 3s,声明可到 60s;最多 16 个并发执行。作品进程无网络、无平台环境变量和数据令牌,通过受信任代理读写集合。Linux 使用只读 Docker 容器(128 MB、0.5 CPU、16 PID);macOS 本地开发使用系统沙箱和 Node 权限模型(64 MB V8 堆,非总内存配额);
|
|
77
|
+
- `context`:`{ player: {playerId, loggedIn}, cloud: { collection(name): {query, add, set} } }`;
|
|
78
|
+
- 数据面写权限:仅 `writeRule=SERVER` 的集合(创作者经 manage 接口设置),玩家对该类集合只读;
|
|
79
|
+
- 计量:作品日调用 200,000 次上限,玩家 30 次/分钟;调用接口 `POST /api/cloud/{app}/functions/{name}`;
|
|
80
|
+
- 声明式集合:包站点根 `collections.json`(`{"集合名":{"read":"WORLD|PLAYER","write":"OWNER|SERVER"}}`,≤8 条,64KB),发布时自动创建/对齐权限——AI 工具零控制台交互路径;
|
|
81
|
+
- 控制台在线管理(创作者登录态):`/api/cloud/manage/{app}/functions` 列表 / `PUT` 保存即部署 / `DELETE` / `POST .../test` 测试调用(系统身份);保存会重新读取函数自描述元数据;
|
|
82
|
+
- 常驻化声明(写在函数代码内,平台静态读取):`exports.timeoutMs`(1s~60s 长任务档)、
|
|
83
|
+
`exports.cron`(五字段 cron,分钟粒度调度,事件 `{type:'cron',scheduledAt}`)、
|
|
84
|
+
`exports.onDocs=['集合名']`(订阅集合写入,事务提交后异步触发,事件 `{type:'doc',collection}`)。
|
|
85
|
+
|
|
86
|
+
## 房间实时通道(room,协议 1)
|
|
87
|
+
|
|
88
|
+
- 端点:`WS /api/cloud/rooms/{app}/{roomId}`(同源,凭 play 会话 Cookie 鉴权;声明 `room` 能力);
|
|
89
|
+
- roomId:1-64 位字母/数字/`_`/`-`;房间 256 人、每玩家 4 连接、每作品 5000 房间、空闲 90s 回收;
|
|
90
|
+
- 帧:连接即加入并收到 `{type:'joined', roomId, you, players}`;`{type:'msg', data}` 广播为
|
|
91
|
+
`{type:'msg', from, data}`(≤4KB,300 帧/30s);在线广播 `{type:'join'|'leave', playerId}`;文本 `PING` 得 `{type:'PONG'}`;
|
|
92
|
+
- 容量:每房 256 人、每玩家 4 连接、每作品 5000 房、空闲 90s 回收;
|
|
93
|
+
- 查询:`collection.query` 支持 `where` 过滤(字段等值或 `{gte,lte,gt,lt,ne,in}`,平台数据库过滤、本地模拟器内存求值);
|
|
94
|
+
- 查询:`collection.query` 支持 `join` 嵌入连接(每次最多 2 个,服务端拼装):
|
|
95
|
+
- 单值:`{"author": "users.authorId"}` —— 主文档 `authorId` 字段的值 = `users` 集合文档 id,
|
|
96
|
+
结果嵌入拍平对象(数据字段 + `id/ownerPlayerId/seq/createdAt/updatedAt` 平台字段优先)或 `null`;
|
|
97
|
+
- 多值:`{"comments": ["comments", "postId"]}` —— `comments` 集合 `postId` 字段的值 = 主文档 id,
|
|
98
|
+
结果嵌入数组(按插入序,每侧最多 200 条,超出截断);
|
|
99
|
+
- 被连接集合必须同样在 `.wovoon` capabilities 中声明(能力门禁逐集合执行);
|
|
100
|
+
玩家面对 PLAYER 读规则的目标集合逐文档过滤(只见自己的),SERVER 面不受限;
|
|
101
|
+
- `join` 只影响返回嵌入,不改变主查询的 where/orderBy/limit/分页;对连接字段做过滤请用云函数组合;
|
|
102
|
+
- 包体:静态托管默认上限 4GB / 100,000 文件(可配置覆盖)。
|
|
103
|
+
|
|
104
|
+
## 自建后端 Web 应用(协议 1)
|
|
105
|
+
|
|
106
|
+
可选字段 `backend` 支持 `"platform"`、`"external"`,省略兼容旧协议。`external` 仅用于 Web:上传静态前端,后端独立部署。纯自建后端无需平台 SDK 或云能力;需要混合使用平台云能力时仍按实际调用声明 `capabilities`。
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{"protocol":1,"backend":"external","capabilities":[]}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
|
|
113
|
+
|
|
114
|
+
平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
|
package/README.md
CHANGED
|
@@ -46,8 +46,8 @@ SDK 只负责云能力;**游戏资源的加载速度取决于打包方式**。
|
|
|
46
46
|
- 加载用 `Promise.all` 并行 fetch + `WebAssembly.instantiateStreaming` 流式编译;
|
|
47
47
|
首包(引擎+开场)控制在 3MB 内,其余按场景分包按需下载。
|
|
48
48
|
|
|
49
|
-
完整配方(含 Godot/TapTap
|
|
49
|
+
完整配方(含 Godot/TapTap 导出还原步骤):[资源优化配方](./docs/recipes/web-asset-optimization.md)。
|
|
50
50
|
`wovoon validate` 与平台发布扫描会对以上反模式给出同文案 WARN。
|
|
51
51
|
|
|
52
|
-
- 协议正典与完整能力说明见仓库 [PROTOCOL.md](
|
|
52
|
+
- 协议正典与完整能力说明见仓库 [PROTOCOL.md](./PROTOCOL.md) 与 [llms.txt](./llms.txt)
|
|
53
53
|
- 本地开发与校验:`npx @wovoon/cli init / dev / validate`
|
package/dist/client.d.ts
CHANGED
|
@@ -29,6 +29,7 @@ export interface PolarisDocumentView {
|
|
|
29
29
|
}
|
|
30
30
|
export interface PolarisQueryOptions {
|
|
31
31
|
limit?: number;
|
|
32
|
+
afterSeq?: number;
|
|
32
33
|
orderBy?: string;
|
|
33
34
|
order?: "asc" | "desc";
|
|
34
35
|
ownerOnly?: boolean;
|
|
@@ -45,6 +46,8 @@ export declare class PolarisClient {
|
|
|
45
46
|
private readonly baseUrl;
|
|
46
47
|
private sessionPromise;
|
|
47
48
|
private target;
|
|
49
|
+
readonly collectionsWatch: CollectionsWatchState;
|
|
50
|
+
webSocketOrigin(): string;
|
|
48
51
|
/** 同房号的活动连接登记:重复 room(同房号) 自动离开旧连接(重连安全)。 */
|
|
49
52
|
private readonly activeRooms;
|
|
50
53
|
constructor(init?: PolarisRequestInit);
|
|
@@ -56,6 +59,7 @@ export declare class PolarisClient {
|
|
|
56
59
|
private request;
|
|
57
60
|
private detectTarget;
|
|
58
61
|
session(): Promise<PolarisSessionView>;
|
|
62
|
+
ready(): Promise<PolarisSessionView>;
|
|
59
63
|
identity(): Promise<{
|
|
60
64
|
playerId: string;
|
|
61
65
|
loggedIn: boolean;
|
|
@@ -119,4 +123,16 @@ export declare class PolarisClient {
|
|
|
119
123
|
};
|
|
120
124
|
};
|
|
121
125
|
}
|
|
126
|
+
interface CollectionsWatchState {
|
|
127
|
+
listeners: Array<{
|
|
128
|
+
collection: string;
|
|
129
|
+
cb: (notice: {
|
|
130
|
+
action: string;
|
|
131
|
+
id: string;
|
|
132
|
+
}) => void;
|
|
133
|
+
}>;
|
|
134
|
+
socket: WebSocket | null;
|
|
135
|
+
pending: boolean;
|
|
136
|
+
generation: number;
|
|
137
|
+
}
|
|
122
138
|
export { parseData };
|
package/dist/client.js
CHANGED
|
@@ -19,15 +19,28 @@ function parseData(raw) {
|
|
|
19
19
|
}
|
|
20
20
|
}
|
|
21
21
|
export class PolarisClient {
|
|
22
|
+
webSocketOrigin() {
|
|
23
|
+
const runtime = String(globalThis.__wovoonRuntimeWsBase ?? "");
|
|
24
|
+
return this.baseUrl || runtime || (typeof location === "undefined" ? "http://localhost" : location.origin);
|
|
25
|
+
}
|
|
22
26
|
constructor(init = {}) {
|
|
23
27
|
this.sessionPromise = null;
|
|
24
28
|
this.target = "";
|
|
29
|
+
this.collectionsWatch = { listeners: [], socket: null, pending: false, generation: 0 };
|
|
25
30
|
/** 同房号的活动连接登记:重复 room(同房号) 自动离开旧连接(重连安全)。 */
|
|
26
31
|
this.activeRooms = new Map();
|
|
27
32
|
this.baseUrl = (init.baseUrl ?? "").replace(/\/$/, "");
|
|
28
33
|
}
|
|
29
34
|
/** 指定作品目标:deploymentId(运行地址自动识别)或 appId。 */
|
|
30
35
|
configure(options) {
|
|
36
|
+
for (const room of this.activeRooms.values())
|
|
37
|
+
room.leave();
|
|
38
|
+
this.collectionsWatch.generation++;
|
|
39
|
+
this.collectionsWatch.pending = false;
|
|
40
|
+
this.collectionsWatch.listeners.length = 0;
|
|
41
|
+
const watchSocket = this.collectionsWatch.socket;
|
|
42
|
+
this.collectionsWatch.socket = null;
|
|
43
|
+
watchSocket?.close();
|
|
31
44
|
this.target = options.deploymentId ?? options.appId ?? this.target;
|
|
32
45
|
this.sessionPromise = null;
|
|
33
46
|
return this;
|
|
@@ -74,12 +87,18 @@ export class PolarisClient {
|
|
|
74
87
|
this.sessionPromise = Promise.reject(new PolarisError("未识别作品:请通过 wovoon 平台运行,或 configure({deploymentId})", "WOVOON_TARGET_MISSING"));
|
|
75
88
|
return this.sessionPromise;
|
|
76
89
|
}
|
|
77
|
-
|
|
90
|
+
const promise = this.request("POST", "/api/cloud/session", {
|
|
78
91
|
deploymentId: target,
|
|
79
92
|
appId: target,
|
|
93
|
+
}).catch((error) => {
|
|
94
|
+
if (this.sessionPromise === promise)
|
|
95
|
+
this.sessionPromise = null;
|
|
96
|
+
throw error;
|
|
80
97
|
});
|
|
81
|
-
|
|
98
|
+
this.sessionPromise = promise;
|
|
99
|
+
return promise;
|
|
82
100
|
}
|
|
101
|
+
ready() { return this.session(); }
|
|
83
102
|
identity() {
|
|
84
103
|
return this.session().then((data) => ({
|
|
85
104
|
playerId: data.playerId,
|
|
@@ -126,7 +145,7 @@ export class PolarisClient {
|
|
|
126
145
|
if (data instanceof ArrayBuffer)
|
|
127
146
|
socket.send(data);
|
|
128
147
|
else if (data instanceof Uint8Array)
|
|
129
|
-
socket.send(data
|
|
148
|
+
socket.send(new Uint8Array(data));
|
|
130
149
|
else
|
|
131
150
|
socket.send(JSON.stringify({ type: "msg", data }));
|
|
132
151
|
},
|
|
@@ -143,6 +162,7 @@ export class PolarisClient {
|
|
|
143
162
|
onPresence: (callback) => { listeners.presence.push(callback); },
|
|
144
163
|
onClose: (callback) => { listeners.close.push(callback); },
|
|
145
164
|
};
|
|
165
|
+
this.activeRooms.set(roomId, handle);
|
|
146
166
|
this.session().then((data) => {
|
|
147
167
|
if (left || typeof WebSocket === "undefined") {
|
|
148
168
|
if (!left)
|
|
@@ -152,10 +172,10 @@ export class PolarisClient {
|
|
|
152
172
|
// CDN 加速域不支持 WebSocket:优先用入口页注入的 __wovoonRuntimeWsBase(平台主站,直连源站),
|
|
153
173
|
// 并以启动片段的 wovoon_play_sid 作为跨主机凭证(与 play cookie 同一游玩会话)。
|
|
154
174
|
const wsBase = String(globalThis.__wovoonRuntimeWsBase ?? "").replace(/\/+$/, "");
|
|
155
|
-
const origin = this.
|
|
175
|
+
const origin = this.webSocketOrigin();
|
|
156
176
|
const scheme = origin.startsWith("https") ? "wss" : "ws";
|
|
157
177
|
const roomPath = `/api/cloud/rooms/${data.appId}/${encodeURIComponent(roomId)}`;
|
|
158
|
-
const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(location.hash ?? ""))?.[1];
|
|
178
|
+
const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(typeof location === "undefined" ? "" : location.hash ?? ""))?.[1];
|
|
159
179
|
const query = [];
|
|
160
180
|
if (sid)
|
|
161
181
|
query.push(`wovoon_play_sid=${sid}`);
|
|
@@ -163,7 +183,8 @@ export class PolarisClient {
|
|
|
163
183
|
query.push(`mode=${encodeURIComponent(options.mode)}`);
|
|
164
184
|
socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}${roomPath}${query.length ? "?" + query.join("&") : ""}`);
|
|
165
185
|
socket.binaryType = "arraybuffer";
|
|
166
|
-
socket.onopen = () => {
|
|
186
|
+
socket.onopen = () => { if (left)
|
|
187
|
+
socket?.close(); };
|
|
167
188
|
socket.onmessage = (event) => {
|
|
168
189
|
if (event.data instanceof ArrayBuffer) {
|
|
169
190
|
emit("message", { binary: true, data: new Uint8Array(event.data) });
|
|
@@ -184,6 +205,8 @@ export class PolarisClient {
|
|
|
184
205
|
emit("presence", frame);
|
|
185
206
|
else if (frame.type === "error")
|
|
186
207
|
emit("message", { error: frame.message });
|
|
208
|
+
else if (frame.type === "world")
|
|
209
|
+
emit("message", { from: "server", data: frame.data });
|
|
187
210
|
else if (frame.type === "matched")
|
|
188
211
|
emit("message", frame);
|
|
189
212
|
};
|
|
@@ -245,12 +268,14 @@ export class PolarisClient {
|
|
|
245
268
|
collection(name) {
|
|
246
269
|
if (!name)
|
|
247
270
|
throw new PolarisError("collection(name) 需要集合名", "WOVOON_ARGUMENT");
|
|
248
|
-
const ready = this.session().then((data) => data.appId);
|
|
249
|
-
const docUrl = (id) => ready.then((appId) => `/api/cloud/${appId}/collections/${encodeURIComponent(name)}/docs${id ? "/" + id : ""}`);
|
|
271
|
+
const ready = () => this.session().then((data) => data.appId);
|
|
272
|
+
const docUrl = (id) => ready().then((appId) => `/api/cloud/${appId}/collections/${encodeURIComponent(name)}/docs${id ? "/" + encodeURIComponent(id) : ""}`);
|
|
250
273
|
const client = this;
|
|
251
274
|
return {
|
|
252
275
|
query: (options = {}) => {
|
|
253
276
|
const params = [`limit=${options.limit ?? 20}`];
|
|
277
|
+
if (options.afterSeq !== undefined)
|
|
278
|
+
params.push(`afterSeq=${options.afterSeq}`);
|
|
254
279
|
if (options.orderBy)
|
|
255
280
|
params.push(`orderBy=${encodeURIComponent(options.orderBy)}`);
|
|
256
281
|
params.push(`order=${options.order === "asc" ? "asc" : "desc"}`);
|
|
@@ -273,15 +298,22 @@ export class PolarisClient {
|
|
|
273
298
|
};
|
|
274
299
|
}
|
|
275
300
|
}
|
|
276
|
-
const collectionsWatch = { listeners: [], socket: null };
|
|
277
301
|
function attachCollectionsWatch(client) {
|
|
278
|
-
|
|
302
|
+
const collectionsWatch = client.collectionsWatch;
|
|
303
|
+
if (collectionsWatch.socket || collectionsWatch.pending || !collectionsWatch.listeners.length || typeof WebSocket === "undefined")
|
|
279
304
|
return;
|
|
305
|
+
collectionsWatch.pending = true;
|
|
306
|
+
const generation = collectionsWatch.generation;
|
|
280
307
|
client.session().then((data) => {
|
|
308
|
+
if (generation !== collectionsWatch.generation)
|
|
309
|
+
return;
|
|
310
|
+
collectionsWatch.pending = false;
|
|
311
|
+
if (!collectionsWatch.listeners.length)
|
|
312
|
+
return;
|
|
281
313
|
const wsBase = String(globalThis.__wovoonRuntimeWsBase ?? "").replace(/\/+$/, "");
|
|
282
|
-
const origin =
|
|
314
|
+
const origin = client.webSocketOrigin();
|
|
283
315
|
const scheme = origin.startsWith("https") ? "wss" : "ws";
|
|
284
|
-
const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(location.hash ?? ""))?.[1];
|
|
316
|
+
const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(typeof location === "undefined" ? "" : location.hash ?? ""))?.[1];
|
|
285
317
|
const query = sid ? `?wovoon_play_sid=${sid}` : "";
|
|
286
318
|
const socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}/api/cloud/rooms/${data.appId}/__collections${query}`);
|
|
287
319
|
collectionsWatch.socket = socket;
|
|
@@ -302,13 +334,17 @@ function attachCollectionsWatch(client) {
|
|
|
302
334
|
catch { /* 非 JSON 帧忽略 */ }
|
|
303
335
|
};
|
|
304
336
|
socket.onclose = () => {
|
|
337
|
+
if (collectionsWatch.socket !== socket)
|
|
338
|
+
return;
|
|
305
339
|
collectionsWatch.socket = null;
|
|
306
340
|
if (collectionsWatch.listeners.length)
|
|
307
341
|
setTimeout(() => attachCollectionsWatch(client), 2000);
|
|
308
342
|
};
|
|
309
|
-
}).catch(() => {
|
|
343
|
+
}).catch(() => { if (generation === collectionsWatch.generation)
|
|
344
|
+
collectionsWatch.pending = false; });
|
|
310
345
|
}
|
|
311
346
|
function watchCollections(client, collection, cb) {
|
|
347
|
+
const collectionsWatch = client.collectionsWatch;
|
|
312
348
|
const listener = { collection, cb };
|
|
313
349
|
collectionsWatch.listeners.push(listener);
|
|
314
350
|
attachCollectionsWatch(client);
|
|
@@ -317,6 +353,13 @@ function watchCollections(client, collection, cb) {
|
|
|
317
353
|
const index = collectionsWatch.listeners.indexOf(listener);
|
|
318
354
|
if (index >= 0)
|
|
319
355
|
collectionsWatch.listeners.splice(index, 1);
|
|
356
|
+
if (!collectionsWatch.listeners.length) {
|
|
357
|
+
collectionsWatch.generation++;
|
|
358
|
+
collectionsWatch.pending = false;
|
|
359
|
+
const socket = collectionsWatch.socket;
|
|
360
|
+
collectionsWatch.socket = null;
|
|
361
|
+
socket?.close();
|
|
362
|
+
}
|
|
320
363
|
},
|
|
321
364
|
};
|
|
322
365
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,4 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @wovoon/polaris SDK 入口(v0.1 协议层)。
|
|
3
|
-
* 当前导出协议 1 的冻结类型与常量;运行时客户端(identity/collection 等)在 M1 第 2~3 步落地。
|
|
4
|
-
*/
|
|
1
|
+
/** Polaris protocol 1: identity, collections, functions and realtime rooms. */
|
|
5
2
|
export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
|
|
6
3
|
export { PolarisClient, PolarisError, parseData } from "./client.js";
|
|
7
4
|
export type { WovoonCapability, WovoonCollectionName, WovoonManifest, WovoonSession, WovoonDocument, WovoonQueryOptions, WovoonFunctionEvent, WovoonFunctionResult, WovoonRoomFrame, } from "./protocol.js";
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @wovoon/polaris SDK 入口(v0.1 协议层)。
|
|
3
|
-
* 当前导出协议 1 的冻结类型与常量;运行时客户端(identity/collection 等)在 M1 第 2~3 步落地。
|
|
4
|
-
*/
|
|
1
|
+
/** Polaris protocol 1: identity, collections, functions and realtime rooms. */
|
|
5
2
|
export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName, CAPABILITY_PATTERN, isValidCapability, WovoonProtocolError, } from "./protocol.js";
|
|
6
3
|
export { PolarisClient, PolarisError, parseData } from "./client.js";
|
package/dist/protocol.d.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
/** 协议版本。协议 1 是当前唯一支持的版本。 */
|
|
6
6
|
export declare const WOVOON_PROTOCOL_VERSION: 1;
|
|
7
7
|
/** 协议 1 冻结的能力名。集合能力形如 `collection:${WovoonCollectionName}`。 */
|
|
8
|
-
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room";
|
|
8
|
+
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room" | "room:competitive" | "gamelogic";
|
|
9
9
|
/** 集合名:2-32 位,小写字母开头,仅小写字母/数字/下划线。运行时校验用下方正则。 */
|
|
10
10
|
export type WovoonCollectionName = string;
|
|
11
11
|
export declare const COLLECTION_NAME_PATTERN: RegExp;
|
|
@@ -38,6 +38,13 @@ export type WovoonRoomFrame = {
|
|
|
38
38
|
type: "msg";
|
|
39
39
|
from: string;
|
|
40
40
|
data: unknown;
|
|
41
|
+
} | {
|
|
42
|
+
type: "world";
|
|
43
|
+
data: unknown;
|
|
44
|
+
} | {
|
|
45
|
+
type: "matched";
|
|
46
|
+
roomId: string;
|
|
47
|
+
mode?: string;
|
|
41
48
|
} | {
|
|
42
49
|
type: "error";
|
|
43
50
|
message: string;
|
|
@@ -54,7 +61,7 @@ export interface WovoonSession {
|
|
|
54
61
|
export interface WovoonDocument {
|
|
55
62
|
id: string;
|
|
56
63
|
ownerPlayerId: string | null;
|
|
57
|
-
data:
|
|
64
|
+
data: string;
|
|
58
65
|
seq: number;
|
|
59
66
|
createdAt: string;
|
|
60
67
|
updatedAt: string;
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# wovoon CLI 参考(CLI 0.12.4)
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
wovoon init [目录] [--template minimal|game|arena] [--name 名称]
|
|
5
|
+
wovoon dev [目录] [--port 5179] [--player 玩家名]
|
|
6
|
+
wovoon validate [目录] [--json]
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
SDK 依赖固定为 @wovoon/polaris 0.6.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
|
|
10
|
+
|
|
11
|
+
## wovoon init
|
|
12
|
+
|
|
13
|
+
从官方模板创建应用。默认目录 `./my-app`,默认模板 `game`,目录必须为空。
|
|
14
|
+
|
|
15
|
+
wovoon init todo-app --template minimal --name 待办清单
|
|
16
|
+
|
|
17
|
+
`--name` 会替换模板页面的 `<title>`。生成后 `cd` 进目录即可开发。
|
|
18
|
+
|
|
19
|
+
## wovoon dev
|
|
20
|
+
|
|
21
|
+
本地模拟大后台(localhost 全能力,无需登录):
|
|
22
|
+
|
|
23
|
+
wovoon dev # 游客模式
|
|
24
|
+
wovoon dev --player 阿明 # 模拟登录玩家(可写云数据)
|
|
25
|
+
|
|
26
|
+
- 静态托管:`/api/public/static/dec0de11-0000-4000-8000-000000000001/`(生产同路径,SDK 自动识别作品;根路径 `/` 会 302 过去)。
|
|
27
|
+
- 平台 SDK:`GET /api/cloud/sdk.js`(与生产同源同路径)。
|
|
28
|
+
- 云能力:`POST /api/cloud/session`、`GET|POST|PUT|DELETE /api/cloud/{app}/collections/{name}/docs[/{id}]`。
|
|
29
|
+
- 校验/配额/报错与生产一字不差(能力门禁、集合与文档配额、权限、limit 钳制)。
|
|
30
|
+
- `.wovoon`/`.wovoongame`/`.DS_Store`/`__MACOSX/` 不对外发布(与生产一致)。
|
|
31
|
+
- 云函数:`functions/*.js` 在独立系统沙箱执行,数据访问经过受信任代理,作品进程没有平台凭据或网络权限。macOS 使用 sandbox-exec 和 Node 权限模型;Linux 需要 Docker 和预先拉取的 `node:20-alpine` 镜像。Windows 的云函数/权威房间执行暂不支持,静态服务和校验可用。
|
|
32
|
+
- 管理接口需要 CLI 启动时显示的 Bearer 管理令牌;内部函数数据接口使用单独的随机令牌。服务只接受当前本地端口的 Host/Origin,静态文件和函数源文件不得通过符号链接越过项目目录。
|
|
33
|
+
- 云函数同时最多 16 个,默认 3 秒、声明上限 60 秒;权威房间最多 64 个,具有空房回收及进程退出清理。Linux 单进程容器限制为 128 MB、0.5 CPU、16 PID、只读文件系统和无网络。macOS 开发环境使用 64 MB V8 堆上限,不能等同于容器总内存限额。
|
|
34
|
+
- 房间:`WS /api/cloud/rooms/{app}/{roomId}` 本机中继(协议同生产)。
|
|
35
|
+
- 内存态存储:重启即清空;权限默认 WORLD 读 / OWNER 写。
|
|
36
|
+
|
|
37
|
+
## wovoon validate
|
|
38
|
+
|
|
39
|
+
生产规则镜像校验,顺序与平台一致:
|
|
40
|
+
|
|
41
|
+
1. 归档扫描:符号链接、文件数(≤20,000)、展开大小(≤1 GB)、凭据文件(`.env`/`id_rsa`/`.p12`…)、文本密钥泄露(私钥/AK/LTAK/token/连接串)、云元数据地址;
|
|
42
|
+
2. `.wovoon` 标识存在性;
|
|
43
|
+
3. manifest 解析(4 KB / JSON 对象 / 未知字段 / protocol / 能力名);
|
|
44
|
+
4. 静态托管结构(非空、`index.html` 存在且唯一根目录);
|
|
45
|
+
5. 手机兼容性预检(viewport + 可交互输入信号,作为提示输出)。
|
|
46
|
+
|
|
47
|
+
wovoon validate --json # 机器可读报告(AI 工具友好)
|
|
48
|
+
|
|
49
|
+
报错文案与线上**一字不差**:本地看到什么错误,上传平台就是什么错误。修完再跑一次确认 exit 0。
|
|
50
|
+
|
|
51
|
+
## wovoon login
|
|
52
|
+
|
|
53
|
+
wovoon login --token wovoon_pat_xxx [--api http://localhost:8081]
|
|
54
|
+
|
|
55
|
+
保存创作者 API 令牌到 `~/.wovoon/credentials.json`(0600 权限)。令牌在创作者平台 → 设置 → API 令牌 签发
|
|
56
|
+
(或 `POST /api/developer/tokens`),明文只在签发时出现一次;库内只存 SHA-256 哈希,可随时吊销。
|
|
57
|
+
Bearer 令牌请求不携带 Cookie,因此不受 CSRF 校验影响,适合 CLI 与 CI。
|
|
58
|
+
|
|
59
|
+
## wovoon deploy
|
|
60
|
+
|
|
61
|
+
wovoon deploy [目录] [--version 1.2.0] [--notes 更新说明]
|
|
62
|
+
|
|
63
|
+
一条命令完成发布:`validate`(不过即停,文案与线上一致)→ 打包(自动排除 `wovoon.config.json`、
|
|
64
|
+
`README.md`、`.wovoon-deploy-archive/`、`node_modules/`、`.git/`)→ 上传作品包/图标/宣传视频 →
|
|
65
|
+
首次创建作品、之后发新版本 → 提交审核(退回时终端直接显示审核意见)→ 开通静态托管 → 打印运行地址。
|
|
66
|
+
|
|
67
|
+
**素材零门槛**:项目未提供图标/宣传视频时自动使用 CLI 内置默认素材(`assets/defaults/`)——
|
|
68
|
+
不支持多模态的 AI 工具也能完成发布;有素材时在 `wovoon.config.json` 里指 `icon`/`video` 路径。
|
|
69
|
+
|
|
70
|
+
**wovoon.config.json**(首次 deploy 自动生成,可改):
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"api": "http://localhost:8081",
|
|
75
|
+
"name": "作品名", "tagline": "一句话简介", "description": "作品介绍",
|
|
76
|
+
"category": "休闲益智",
|
|
77
|
+
"icon": "assets/icon.png", "video": "assets/demo.mp4",
|
|
78
|
+
"supportedDevices": "desktop", "inputMethods": "MOUSE",
|
|
79
|
+
"appId": "首次发布后自动写回"
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## wovoon versions / rollback
|
|
84
|
+
|
|
85
|
+
wovoon versions # 部署历史(序号/版本/时间/运行地址)
|
|
86
|
+
wovoon rollback --to 0 # 回退到第 0 次部署
|
|
87
|
+
|
|
88
|
+
每次 deploy 都生成**新版本**(不覆盖历史),并把当次发布的作品包/图标/视频归档到项目内
|
|
89
|
+
`.wovoon-deploy-archive/`。回退 = 归档重传为更新的版本号(`-rb` 后缀),不依赖平台旧资产存活,
|
|
90
|
+
线上内容立即还原。归档目录随项目走,纳入版本控制即可团队共享回退能力。
|
|
91
|
+
|
|
92
|
+
## CI 建议
|
|
93
|
+
|
|
94
|
+
- run: npx -y @wovoon/cli login --token ${{ secrets.WOVOON_TOKEN }}
|
|
95
|
+
- run: npx -y @wovoon/cli deploy --notes "CI ${{ github.sha }}"
|
|
96
|
+
|
|
97
|
+
令牌放 CI 密钥;本地环境变量 `WOVOON_API` 可覆盖默认平台地址。
|
|
98
|
+
|
|
99
|
+
## 发布恢复与验收
|
|
100
|
+
|
|
101
|
+
成功必须同时满足目标版本已发布、该版本托管 RUNNING、作品运行地址等于该托管地址。旧版在线不能满足新版成功条件。
|
|
102
|
+
|
|
103
|
+
归档、单个上传结果、作品绑定和审核阶段逐步原子写入 wovoon.config.json。失败后再次运行同一目录的 deploy 会恢复原版本;审核退回后保留绑定,修改作品再发布。创建响应丢失时先按本次上传包查找作品,无法唯一确认时要求核对 appId,不自动重复创建。待恢复期间不能用 rollback 覆盖该状态。
|
|
104
|
+
|
|
105
|
+
`npm test` 执行 SDK、模板、模拟器、上传凭据边界和发布恢复的行为回归;CI 在 macOS/Linux 运行。生产部署、多人压力和真机网络验收仍须另行完成。
|