dokiworlds-app-sdk 0.1.0 → 0.4.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/GUIDE.md ADDED
@@ -0,0 +1,257 @@
1
+ # dokiworlds-app-sdk 使用指南
2
+
3
+ 适用版本:`dokiworlds-app-sdk@0.4.0`。主要入口是 `createAppClient`、`client.whenReady`、`client.input`、`client.apps.launch`、`client.complete`、`client.requestExit` 和独立世界的 `createLlmRuntime`;宿主侧可用 `createAppHost` 和 `createAppsHostExtension`。协议仍为 v2。
4
+
5
+ ## 平台 LLM 代理
6
+
7
+ `dokiworlds-app-sdk/llm_config` 只提供平台代理调用:`createLlmRuntime({ worldId }).listModels()` 查询当前可用文本模型,`invoke(...)` 发起调用。SDK 不包含 API key、provider 或 base URL。世界必须由 DokiWorlds 启动,后端会写入短期 HttpOnly 世界会话;直接打开 HTML 时 LLM 调用会被拒绝。模型 ID 必须取自 `listModels()` 的返回值,不能硬编码 Provider 模型名。
8
+
9
+ `0.1.0` 的客户端没有初始化输入读取 API,不能直接用于下面的检定演出插槽。
10
+
11
+ ## 安装与运行条件
12
+
13
+ 在 App 的源码项目中安装工作区包(Windows 示例,按本机仓库位置调整):
14
+
15
+ ```bash
16
+ npm install D:/GameDev/dokiworlds/packages/dokiworlds-app-sdk
17
+ ```
18
+
19
+ SDK 是浏览器端 ESM。App 必须运行在支持 `postMessage` 的 iframe 中,由实现 `dokiworld.app` v2 的宿主加载;`apps.launch` 另外要求宿主允许拉起子 App。`npm install` 只提供 SDK,不会自行创建 App 目录、列表或弹窗。若 App 以静态文件放在 `public/apps`,请用自己的构建工具把 `dokiworlds-app-sdk` 打包进浏览器脚本;浏览器不能直接从静态页面解析 `import ... from 'dokiworlds-app-sdk'` 这个 npm 裸包名。异地交付也可以在包目录运行 `npm pack`,将生成的 tgz 交给同事安装;这不等于发布 npm。
20
+
21
+ ## 检定演出插槽:给 App 作者
22
+
23
+ `check_reveal` 用于展示已经由游戏结算的检定。App 不掷新骰、不改变成功/失败、不发奖励,也不负责推进任务。操作小游戏不复用此插槽;已注册的宝箱使用下文的独立适配器。
24
+
25
+ 启动输入是 `doki.check-reveal.input` v1:
26
+
27
+ ```json
28
+ {
29
+ "contract": "doki.check-reveal.input",
30
+ "version": 1,
31
+ "data": {
32
+ "presentationId": "本次演出唯一标识",
33
+ "locale": "zh-CN",
34
+ "title": "说得孙癞子自己松口",
35
+ "check": { "attribute": "CHA", "roll": 15, "modifier": 1, "total": 16, "dc": 11, "passed": true }
36
+ }
37
+ }
38
+ ```
39
+
40
+ 按原值展示 `check`;`attribute` 是内容中的属性标识,不要求一定为示例中的 `CHA`。完成输出必须且只能包含本次 `presentationId` 与 `status: 'viewed'`:
41
+
42
+ ```js
43
+ import { createAppClient } from 'dokiworlds-app-sdk';
44
+
45
+ // 填游戏宿主的实际 origin;跨域时不能写小游戏自己的 window.location.origin。
46
+ const client = createAppClient({ appId: 'fortune-reveal', targetOrigin: 'https://game.example' });
47
+ client.connect();
48
+ window.addEventListener('pagehide', () => client.dispose(), { once: true });
49
+
50
+ const input = await client.whenReady({ timeoutMs: 10_000 });
51
+ if (input.contract !== 'doki.check-reveal.input' || input.version !== 1) {
52
+ client.requestExit();
53
+ throw new Error('Unsupported input contract');
54
+ }
55
+ const { presentationId, title, check, locale } = input.data;
56
+ // App 在这里使用 title、check、locale 播放自己的演出。
57
+ // 只有演出真实结束或玩家点击 App 内“看完”时,才调用这个函数。
58
+ async function finishPresentation() {
59
+ const acknowledgement = await client.complete({
60
+ contract: 'doki.check-reveal.result', version: 1,
61
+ data: { presentationId, status: 'viewed' },
62
+ });
63
+ if (acknowledgement !== 'accepted') throw new Error('Presentation rejected');
64
+ client.dispose();
65
+ }
66
+ // iframe 中的按键不会冒泡到游戏:App 应把 Escape/自己的退出按钮接到 requestExit。
67
+ window.addEventListener('keydown', (event) => {
68
+ if (event.key === 'Escape') client.requestExit();
69
+ });
70
+ ```
71
+
72
+ `client.input` 在初始化前为 `null`,初始化后为输入副本;修改副本不会改变宿主输入。`whenReady` 可在 connect 前后订阅,已经初始化时立即返回;超时和 dispose 会拒绝等待。App 也应处理自己的加载/播放错误并调用 `requestExit`。
73
+
74
+ 宿主有 10 秒初始化上限、初始化后 30 秒演出上限;始终提供正式结果和继续/跳过入口。关闭、跳过、超时、返回旧演出 ID 或错误契约都不会改变已结算结果。减少动态效果时直接显示正式结果,不加载 App。这个插槽不允许 `apps.launch`,调用会收到 `unsupported-operation`。
75
+
76
+ ## 检定演出插槽:给接入方
77
+
78
+ 1. 同事提供固定 `appId`、可嵌入的部署地址,并实现上述契约。服务器需允许游戏域名嵌入(检查 CSP `frame-ancestors` 和 `X-Frame-Options`)。
79
+ 2. 在 `frontend/src/lib/app-registry.ts` 的 `APP_REGISTRY` 登记经过审核的地址,例如:
80
+
81
+ ```ts
82
+ { id: 'fortune-reveal', name: '检定演出', url: 'https://apps.example/fortune/', slots: ['check_reveal'] }
83
+ ```
84
+
85
+ 3. 在剧本源 `pack.yaml` 的现有 `presentation` 中添加以下内容,再经原有编译/版本流程交付:
86
+
87
+ ```yaml
88
+ presentation:
89
+ # 保留原有字段
90
+ app_slots:
91
+ check_reveal:
92
+ app_id: fortune-reveal
93
+ ```
94
+
95
+ 剧本只能引用登记的 ID,不能提供 URL。正式插槽要求与游戏不同源的 HTTPS 地址;开发模式允许独立 localhost/127.0.0.1 端口的 HTTP 服务。独立 App 不应和游戏共享登录凭据。iframe 仅允许脚本、同源资源访问与指针锁,不授予宿主状态、导航或子 App 拉起能力。
96
+
97
+ 未配置插槽时,正常游戏会检查部署方许可的 Physics Dice 是否支持下述服务端结果协议;兼容时使用骰子演出,否则保留原来的抽签/结果界面。显式配置其他 App 时沿用 `APP_REGISTRY`(当前静态表为空),配置不存在或不合法时显示正式结果。目录本身不能注入新的 App 地址。
98
+
99
+ 开发 **APPS** 目录扫描仅供调试,不等于正式登记;直接从目录启动时输入为空,不能代替一次真实检定联调。`AppFrame.tsx` 由开发入口与正式插槽共用;正式触发点包括 `ContextCard.tsx` 的结果卡与对话中最新的 `ActionResultReceipt.tsx`,统一经过 `GameCheckReveal.tsx`。历史回执不补播演出。
100
+
101
+ ## 宝箱:给玩法接入方
102
+
103
+ 已接入 `game-loot-chest` 的 `doki.game.chest-input` v2 / `doki.game.chest-result` v2。部署地址由 `frontend/src/free-roam/loot-chest-contract.ts` 登记,剧本不能传入可执行 URL。接口依据:[同事发布的接入文档](https://static-doki.aimeng.ai/apps/game-loot-chest/docs/integration.zh-CN.md)。
104
+
105
+ **普通游玩的任务交付已默认接入。** Runtime 根据正式 `Quest Transition.status=completed` 绑定识别交付 Action;当其为独立无检定的 `quest_resolution`,且原效果含可展示的物品/货币报酬时,原交付按钮直接进入宝箱。奖励取自原 Action 的固定授予/真实 NPC 转移,不按任务名猜奖励,不新增任何资产。领取时原消费、NPC 扣款、玩家入账、XP 和任务完成仍原子提交。关闭保留待交付任务;旧存档已完成任务不会补发。App 加载失败可直接领取确定的报酬,仍经相同后端校验。
106
+
107
+ 这一适配同时作用于正式剧本和已有存档,无需开启调试或改写已发布 Pack;不适用的有检定/出牌/既有小游戏行动保留原规则。官渡焚粮记“夜径密探粮情”、挂印封金“白马坡前探敌情”可在正常任务流程中验证。**场景中新增独立宝箱**则使用下面的作者配置。
108
+
109
+ 在合法的独立玩家 Action 上配置 `payload.kind: interaction`、`payload.verb: receive`,不能同时配置 Check 或出牌结算。保留 Action 的 ID、目标、条件、时间成本、反馈等必填字段,增加:
110
+
111
+ ```yaml
112
+ minigame:
113
+ version: 1
114
+ kind: loot_chest
115
+ title: 物资宝箱
116
+ instructions: 打开宝箱并领取物资。
117
+ labels: []
118
+ chest:
119
+ table_id: supplies
120
+ table_version: 1
121
+ root:
122
+ type: all
123
+ children:
124
+ - type: item
125
+ itemId: currency:coin
126
+ name: 铜钱
127
+ quantity: {min: 2, max: 5}
128
+ - type: item
129
+ itemId: item_supplies
130
+ name: 物资
131
+ quantity: {fixed: 1}
132
+ ```
133
+
134
+ 物品必须在同一 Pack 中定义为堆叠物品;`currency:coin` 引用 world 中已有的 `coin`。实例装备奖励暂不支持。掉落树支持 `item / empty / all / choose / repeat`,后端编译时校验结构和引用。独立场景宝箱入口需作者按原有草稿、编译、预览、发布流程配置。
135
+
136
+ 后端 start 保存唯一 attempt/session、完整掉落树、版本摘要和 `mulberry32-v1` seed。App 的开锁属于交互表现,不把客户端操作当作权威技能检定。领取时提交原始输出,由后端重算奖励,连同 Action 的正式效果一次提交。一个 Action 在一份存档中只能领取一次;重复请求不会重复发奖。关闭不扣资源、不推进实践;重新打开同一宝箱不重抽。刷新恢复冻结输入,领取失败可重试。只有正式领取才运行任务和引导的正常结算链。需消耗钥匙时使用 Action 条件和领取时的正式效果。
137
+
138
+ 调试模式中,官渡焚粮记/挂印封金的 **玩法测试 → 操作小游戏 → 开启宝箱** 使用独立测试存档,经过同一正式结算 API。直接从 APPS 预览不发游戏奖励。传输校验仅是第一层;只有游戏后端的领取回执表示实际入账。
139
+
140
+ Physics Dice v1.0.7 当前文档明确不接收指定点数或 seed,不能展示现有权威检定的骰点。游戏侧正式入口已接入兼容性检查,但当前版本不会加载;需发布支持 `doki.check-reveal.input` v1 / `doki.check-reveal.result` v1 的指定结果模式。匹配本文固定 App 身份与地址的兼容版本会进入正常检定演出流程,仍需真实 App 联调验收。[骰子接口说明](https://static-doki.aimeng.ai/apps/game-physics-dice/docs/integration.zh-CN.md)
141
+
142
+ 2026-09-29 已确认采用服务端骰点,App 只展示同一结果。供 App 作者实现的输入、完成回执、边界案例与正式入口交接见[物理骰子接入说明](../../.yunxing/physics-dice-server-result-handoff-20260929.md)。
143
+
144
+ 工程边界、验证和渐进呈现见 [ADR 0024](../../.yunxing/adr/0024-loot-chest-app.md)。
145
+
146
+ ## 在本仓库启动本地 App
147
+
148
+ 在 `frontend/public/apps/` 下为每个 App 建一个子目录,例如 `frontend/public/apps/hello-app/index.html`。目录名就是 SDK 的 `appId`,只接受小写字母、数字、`.` 和 `-`,且必须以字母或数字开头和结尾。打开游戏后点击 **APPS** 按钮即可启动调试界面:本地开发时可选择本机目录或管理员已发布到 `https://dev.aimeng.ai/api/game-admin/catalog` 的线上 App;部署环境只显示该线上发布目录。
149
+
150
+ 如果入口不是 `index.html`,或需要指定输入契约,可放置 `manifest.json`:
151
+
152
+ ```json
153
+ {
154
+ "entry": "index.html",
155
+ "locales": { "zh-cn": { "name": "你好" }, "en": { "name": "Hello App" } },
156
+ "runtime": { "input": { "contract": "demo.hello.input", "version": 1 } }
157
+ }
158
+ ```
159
+
160
+ `entry` 必须是目录内的相对文件路径。列表名称优先使用 `locales.zh-cn.name`,没有中文名时使用 `locales.en.name`。未提供 manifest 时,宿主使用 `index.html`、目录名作为显示名称,以及 `{ "contract": "doki.dev.launch", "version": 1, "data": {} }` 作为初始输入。manifest 中的 `runtime.input` 只定义 `contract` 和 `version`;从 **APPS** 按钮直接启动时,`data` 是空对象。当前本地宿主只枚举存在入口文件的子目录,最多读取前 100 个合法目录。
161
+
162
+ 本地 App 使用与宿主同源的 iframe,以便加载 ES module 和静态资源。这个调试入口只应放入可信任的开发 App。
163
+
164
+ ## App 请求拉起另一个 App
165
+
166
+ 下面是 App 源码示例。先 `connect()`,等 `runId` 非空后再调用 `apps.launch`;否则 SDK 会拒绝尚未初始化的发送动作。`targetOrigin` 填实际宿主 origin;本地开发时可使用 `window.location.origin`。
167
+
168
+ ```js
169
+ import { AppsCapabilityError, createAppClient } from 'dokiworlds-app-sdk';
170
+
171
+ const client = createAppClient({
172
+ appId: 'hello-app',
173
+ targetOrigin: window.location.origin,
174
+ });
175
+ client.connect();
176
+ window.addEventListener('pagehide', () => client.dispose(), { once: true });
177
+
178
+ await client.whenReady({ timeoutMs: 10_000 });
179
+
180
+ try {
181
+ const result = await client.apps.launch({
182
+ appId: 'child-app',
183
+ input: {
184
+ contract: 'demo.child.input',
185
+ version: 1,
186
+ data: { level: 1 },
187
+ },
188
+ });
189
+
190
+ if (result.status === 'completed') {
191
+ console.log('Child output:', result.output);
192
+ } else {
193
+ console.log('Child App was closed without a result');
194
+ }
195
+ } catch (error) {
196
+ if (error instanceof AppsCapabilityError) {
197
+ console.error(`Launch failed: ${error.code}`);
198
+ } else {
199
+ console.error('Launch failed:', error);
200
+ }
201
+ }
202
+
203
+ ```
204
+
205
+ `launch` 返回一个 Promise。子 App 调用 `client.complete(...)` 后,父 App 收到 `{ status: 'completed', output }`;用户关闭子 App 时收到 `{ status: 'cancelled' }`。本地宿主一次最多允许五层 App,会拒绝不存在的 `appId`。
206
+
207
+ `input` 和 `output` 均使用版本化契约 `{ contract, version, data }`。`contract` 是非空字符串,`version` 是正整数,`data` 必须能序列化为有界 JSON。单条 payload 的 JSON 上限为 64 KiB。调用方应提前与目标 App 约定契约名、版本和数据结构。
208
+
209
+ ## App 返回完成结果
210
+
211
+ 被拉起的 App 可以通过 `complete` 把结果交给宿主:
212
+
213
+ ```js
214
+ import { createAppClient } from 'dokiworlds-app-sdk';
215
+
216
+ const client = createAppClient({
217
+ appId: 'child-app',
218
+ targetOrigin: window.location.origin,
219
+ });
220
+ client.connect();
221
+
222
+ // 等待宿主初始化;实际 App 可在自己的 UI 中禁用完成按钮直到初始化成功。
223
+ await client.whenReady({ timeoutMs: 10_000 });
224
+
225
+ // 用户完成操作之后调用。
226
+ const acknowledgement = await client.complete({
227
+ contract: 'demo.child.result',
228
+ version: 1,
229
+ data: { score: 42 },
230
+ });
231
+
232
+ if (acknowledgement !== 'accepted') {
233
+ throw new Error('Host rejected the result');
234
+ }
235
+ client.dispose();
236
+ ```
237
+
238
+ 这里同样需要先初始化;`0.2.0` 推荐用 `await client.whenReady()` 替代轮询并直接读取返回的输入。`complete` 返回 `'accepted'` 或 `'rejected'`;宿主未在约 3 秒内确认时会拒绝 Promise。关闭 App 前应等待确认,避免结果丢失。
239
+
240
+ ## 宿主侧职责与错误处理
241
+
242
+ 宿主负责选择可用 App、校验是否允许拉起、创建目标 iframe,并处理协议消息。`launch` handler 必须返回 `{ status: 'completed', output }` 或 `{ status: 'cancelled' }`。本仓库的宿主协议实现位于 `frontend/src/lib/dev-app-host.ts`,共用 iframe 位于 `frontend/src/free-roam/ui/AppFrame.tsx`,开发入口位于 `frontend/src/free-roam/ui/DevAppLauncher.tsx`,目录读取位于 `frontend/src/lib/dev-app-catalog.ts`。本项目宿主不依赖公开 SDK 包;外部 App 才安装并使用 `dokiworlds-app-sdk`。
243
+
244
+ 常见的 `AppsCapabilityError.code`:
245
+
246
+ | code | 含义 |
247
+ | --- | --- |
248
+ | `invalid-request` | `appId` 或输入契约无效,或 payload 超出限制 |
249
+ | `app-unavailable` | 本地目录中没有目标 App |
250
+ | `app-limit` | 本地宿主已达到嵌套层数上限 |
251
+ | `unsupported-operation` | 宿主没有提供 `apps.launch` handler |
252
+ | `invalid-host-result` | 宿主返回的结果不符合契约 |
253
+ | `operation-failed` | 宿主处理失败;不会向 App 暴露内部异常文本 |
254
+ | `timeout` | 拉起请求超过默认一小时;自定义 channel 可通过 `createAppsClientExtension(..., { launchTimeoutMs })` 调整 |
255
+ | `disposed` | 调用前 capability 已释放,或等待期间被释放 |
256
+
257
+ 只有 `result.status === 'completed'` 才读取 `result.output`。`cancelled` 是正常结束分支;上述错误会拒绝 Promise,需要用 `try/catch` 处理。
package/README.md CHANGED
@@ -1,26 +1,48 @@
1
- # dokiworlds-app-sdk
2
-
3
- An App embedded in DokiWorlds can request that its host launch another App. This first release exposes only `apps.launch`; the host controls catalog lookup, permission checks, presentation, and the launched App's lifecycle.
4
-
5
- ```js
6
- import { createAppClient } from "dokiworlds-app-sdk";
7
-
8
- const client = createAppClient({ appId: "my-app", targetOrigin: "https://host.example" });
9
- client.connect();
10
-
11
- const result = await client.apps.launch({
12
- appId: "other-app",
13
- input: { contract: "doki.example.input", version: 1, data: { level: 1 } },
14
- });
15
-
16
- if (result.status === "completed") console.log(result.output);
17
- client.dispose();
18
- ```
19
-
20
- `launch` resolves to `{ status: "completed", output }` or `{ status: "cancelled" }`. A completed output has a versioned `{ contract, version, data }` envelope. Invalid requests, host failures, disposal, and the default one-hour timeout reject the promise with an `AppsCapabilityError` (`code` describes the failure). You can set `launchTimeoutMs` when attaching the capability to a custom channel via `createAppsClientExtension`.
21
-
22
- The package uses the `dokiworld.app` protocol v2 handshake and `dokiworld-app-apps-request`/`dokiworld-app-apps-response` session messages from the original `@dokiworld/app-sdk`. A host with an established session channel can register `createAppsHostExtension(host, { launch })`; that session must allow the `apps` module. Installing this package alone does not add an App catalog or launch UI to the DokiWorlds host.
23
-
24
- ## Local development in this repository
25
-
26
- Place an App at `frontend/public/apps/<app-id>/index.html`, then open a game in a development build and use the **APPS** button. IDs use lowercase letters, digits, dots, and hyphens. An optional `manifest.json` can provide `entry` (a relative HTML path), `locales.en.name`, and `runtime.input` (`contract` and `version`); otherwise `index.html`, the folder name, and the `doki.dev.launch` v1 input contract are used. Local Apps run with the host origin so module scripts and local assets load normally; only put trusted development Apps in this directory. A nested `apps.launch` may target another App in the same local catalog; its completion output is returned to the caller, while closing the child returns `{ status: "cancelled" }`.
1
+ # dokiworlds-app-sdk
2
+
3
+ 中文完整使用说明见 [GUIDE.md](./GUIDE.md)。
4
+
5
+ 完整 HTML 世界的 ZIP 结构、`packageType: "world"` 清单和平台 LLM 接入见 [WORLD_PACKAGE_GUIDE.md](./WORLD_PACKAGE_GUIDE.md)。
6
+
7
+ Version 0.4.0 adds `llm.listModels()` for standalone worlds. An embedded App can read its versioned input, return a completion, and request another App when the host grants that capability. The host controls catalog lookup, permissions, presentation, and lifecycle. See GUIDE.md for the check-reveal slot contract and local package installation.
8
+
9
+ ## Platform LLM proxy
10
+
11
+ Internal worlds can import `dokiworlds-app-sdk/llm_config` and call the platform proxy. The SDK contains no provider URL or API key; the running world must first receive a platform-issued world session.
12
+
13
+ ```js
14
+ import { createLlmRuntime } from 'dokiworlds-app-sdk/llm_config';
15
+
16
+ const llm = createLlmRuntime({ worldId: 'my-world' });
17
+ // The catalog is dynamic: choose a model returned for this player/session.
18
+ const models = await llm.listModels();
19
+ const model = models.find((item) => item.recommended)?.modelId ?? models[0]?.modelId;
20
+ if (!model) throw new Error('No DokiWorlds text model is currently available');
21
+ const reply = await llm.invoke({ model, messages: [{ role: 'user', content: 'Hello' }] });
22
+ ```
23
+
24
+ Do not hard-code a provider model name. `listModels()` returns only text models currently enabled by the platform for the launched world; each item has `modelId`, and may include `tierId`, `recommended`, and `priceDiamonds`. The available list can change with platform configuration, player entitlement, or provider availability.
25
+
26
+ ```js
27
+ import { createAppClient } from "dokiworlds-app-sdk";
28
+
29
+ const client = createAppClient({ appId: "my-app", targetOrigin: "https://host.example" });
30
+ client.connect();
31
+ const input = await client.whenReady();
32
+
33
+ const result = await client.apps.launch({
34
+ appId: "other-app",
35
+ input: { contract: "doki.example.input", version: 1, data: { level: 1 } },
36
+ });
37
+
38
+ if (result.status === "completed") console.log(result.output);
39
+ client.dispose();
40
+ ```
41
+
42
+ `launch` resolves to `{ status: "completed", output }` or `{ status: "cancelled" }`. A completed output has a versioned `{ contract, version, data }` envelope. Invalid requests, host failures, disposal, and the default one-hour timeout reject the promise with an `AppsCapabilityError` (`code` describes the failure). You can set `launchTimeoutMs` when attaching the capability to a custom channel via `createAppsClientExtension`.
43
+
44
+ The package uses the `dokiworld.app` protocol v2 handshake and `dokiworld-app-apps-request`/`dokiworld-app-apps-response` session messages from the original `@dokiworld/app-sdk`. A host with an established session channel can register `createAppsHostExtension(host, { launch })`; that session must allow the `apps` module. Installing this package alone does not add an App catalog or launch UI to the DokiWorlds host.
45
+
46
+ ## Local development in this repository
47
+
48
+ Place an App at `frontend/public/apps/<app-id>/index.html`, then open a game in a development build and use the **APPS** button. IDs use lowercase letters, digits, dots, and hyphens. An optional `manifest.json` can provide `entry` (a relative HTML path), `locales.zh-cn.name` (falling back to `locales.en.name`), and `runtime.input` (`contract` and `version`); otherwise `index.html`, the folder name, and the `doki.dev.launch` v1 input contract are used. Local Apps run with the host origin so module scripts and local assets load normally; only put trusted development Apps in this directory. A nested `apps.launch` may target another App in the same local catalog; its completion output is returned to the caller, while closing the child returns `{ status: "cancelled" }`.
@@ -0,0 +1,116 @@
1
+ # 独立世界包发布指南
2
+
3
+ 本指南用于把完整 HTML 世界发布到 DokiWorlds 的访客入口。它不同于嵌入式 App:世界拥有自己的页面、脚本和资源,平台只提供发布与直接入口;它不会显示在登录后世界广场的剧情包目录中。
4
+
5
+ ## 打包结构
6
+
7
+ 将下面目录的内容压缩为 ZIP;也可以在 ZIP 中额外套一层目录。`index.html` 和 `manifest.json` 必须在同一层。
8
+
9
+ ```text
10
+ honglou-opening.zip
11
+ ├── manifest.json
12
+ ├── index.html
13
+ ├── assets/
14
+ │ ├── cover.webp
15
+ │ └── scene.webp
16
+ └── scripts/
17
+ └── main.js
18
+ ```
19
+
20
+ 所有入口、封面和资源引用都应使用相对路径。不要使用以 `/` 开头的资源路径;世界在平台中从 `/worlds/<id>/` 加载。
21
+
22
+ ### 资源性能要求
23
+
24
+ 图片、音频、字体、脚本和样式必须作为 ZIP 内的独立文件,通过相对路径引用;不要把它们编码为 `data:` / Base64 URI 塞进 `index.html`。内联大资源会阻塞入口 HTML 的首次解析,也无法按资源粒度复用浏览器缓存。
25
+
26
+ 发布后的入口 HTML 继续从 DokiWorlds 同源加载,以保持平台会话与 SDK 的 `/api/...` 调用;平台会将相对静态资源解析到当前 `version-contentHash` 的 CDN release。该 release 路径不可变,图片、音频、字体和脚本可被浏览器与 CDN 长期缓存;更新世界时提高 `version` 并重新上传整个 ZIP 即会使用新路径。
27
+
28
+ ## manifest.json
29
+
30
+ `packageType` 为 `world` 时,Game Admin 会把 ZIP 作为独立世界发布。旧 App 清单未填写该字段时仍按 `app` 处理。
31
+
32
+ ```json
33
+ {
34
+ "schemaVersion": 3,
35
+ "packageType": "world",
36
+ "id": "honglou-opening",
37
+ "version": "1.0.0",
38
+ "entry": "index.html",
39
+ "cover": "assets/cover.webp",
40
+ "locales": {
41
+ "zh-cn": {
42
+ "name": "红楼开篇",
43
+ "description": "从大观园的一段序章开始。"
44
+ },
45
+ "en": {
46
+ "name": "Honglou Opening",
47
+ "description": "An opening chapter in the Grand View Garden."
48
+ }
49
+ },
50
+ "world": {
51
+ "genre": "古风剧情",
52
+ "tags": ["红楼梦", "叙事", "角色扮演"],
53
+ "aiEnabled": true
54
+ }
55
+ }
56
+ ```
57
+
58
+ 字段要求:
59
+
60
+ - `id`:小写字母、数字和连字符;发布后不可与其他世界冲突。
61
+ - `version`:递增的 `major.minor.patch`。同一世界不能重复或降低版本。
62
+ - `entry`、`cover`:ZIP 内已有的安全相对路径;`cover` 是访客入口卡片所需字段。
63
+ - `locales.zh-cn` 与 `locales.en`:都必须有非空 `name` 和 `description`。
64
+ - `world.genre`:非空分类名称;`world.tags`:最多 8 个非空标签。
65
+ - `world.aiEnabled`:布尔值。设为 `true` 后,平台启动的世界可使用平台 LLM;设为 `false` 时 LLM 运行会话与调用都会被拒绝。
66
+
67
+ ## 使用平台 LLM
68
+
69
+ 安装私有 SDK 后,在打包前将其编译进浏览器脚本。静态 HTML 不能直接解析 npm 裸模块名。
70
+
71
+ ```js
72
+ import { createLlmRuntime } from 'dokiworlds-app-sdk/llm_config';
73
+
74
+ const llm = createLlmRuntime({ worldId: 'honglou-opening' });
75
+ const models = await llm.listModels();
76
+ const model = models.find((item) => item.recommended)?.modelId ?? models[0]?.modelId;
77
+ if (!model) throw new Error('当前没有可用的 DokiWorlds 文本模型');
78
+ const reply = await llm.invoke({
79
+ model,
80
+ messages: [{ role: 'user', content: '问问府中事' }],
81
+ });
82
+ console.log(reply.content);
83
+ ```
84
+
85
+ 模型由平台实时提供。必须先调用 `llm.listModels()`,再从返回项的 `modelId` 选择;不要硬编码 Provider 的模型名。返回项可能包含 `tierId`、`recommended` 和 `priceDiamonds`,可用于世界自己的模型选择界面。可用列表会随平台配置、身份、额度或 Provider 可用性变化。
86
+
87
+ 从访客入口启动时,平台会用访客 ID 建立同样短期、世界作用域的 HttpOnly 运行会话。访客调用当前不扣钻石,但平台会记录世界、模型、token 与估算成本;后续可能按访客 ID 增加额度。世界不得自行保存或要求 API key。
88
+
89
+ 模型、消息和系统提示词由世界作者传入;登录玩家仍按普通游玩 LLM 调用进行登录校验、余额/额度预留和结算,访客则走平台记录的免费试玩路径。
90
+
91
+ ## 上传与更新
92
+
93
+ 1. 在 Game Admin 选择 ZIP,等待预览通过。
94
+ 2. 确认预览中显示“独立世界”,再点击发布。
95
+ 3. 平台先上传全部文件到 `worlds/<id>/releases/<version>-<contentHash>/`,随后更新 `worlds/catalog.json`;访客入口会显示其封面、标题、描述、分类和标签。
96
+ 4. 更新时提高 `version` 并重新上传整个 ZIP。
97
+
98
+ 当前 P0 版本采用“刷新即最新版本”:新的目录条目一经发布,刷新后的玩家会加载新版,旧页面可能因资源或接口变化而失效。没有世界存档、版本回滚、审核队列或旧会话固定版本保证。
99
+
100
+ ## 本地调试
101
+
102
+ 无需上传 OSS,也无需创建 ZIP。将解压后的完整世界目录放入本仓库的 `frontend/public/apps/<id>/`,例如:
103
+
104
+ ```text
105
+ frontend/public/apps/honglou-opening/
106
+ ├── manifest.json
107
+ ├── index.html
108
+ └── assets/...
109
+ ```
110
+
111
+ 本地前端与后端运行时,会把其中 `packageType: "world"` 的清单加入访客入口;它从 `/apps/<id>/<entry>` 直接加载。该目录已经被 Git 忽略,不会被提交。`packageType` 不是 `world` 的目录仍按原有本地 App 方式处理。
112
+
113
+ ## 常见错误
114
+
115
+ - `WORLD_MANIFEST_INVALID`:核对必填字段、路径是否在 ZIP 内,以及中英文展示信息。
116
+ - `402 insufficient_balance`:玩家余额或额度不足;这是平台正常的游玩计费结果。
package/package.json CHANGED
@@ -1,20 +1,24 @@
1
- {
2
- "name": "dokiworlds-app-sdk",
3
- "version": "0.1.0",
4
- "type": "module",
5
- "exports": {
6
- ".": {
7
- "types": "./src/index.d.ts",
8
- "default": "./src/index.js"
9
- }
10
- },
11
- "files": ["src", "README.md"],
12
- "scripts": {
13
- "test": "node --test tests/*.test.mjs",
14
- "typecheck": "tsc --noEmit -p tsconfig.json",
15
- "prepublishOnly": "npm test && npm run typecheck"
16
- },
17
- "devDependencies": {
18
- "typescript": "^5.9.3"
19
- }
20
- }
1
+ {
2
+ "name": "dokiworlds-app-sdk",
3
+ "version": "0.4.0",
4
+ "type": "module",
5
+ "exports": {
6
+ ".": {
7
+ "types": "./src/index.d.ts",
8
+ "default": "./src/index.js"
9
+ },
10
+ "./llm_config": {
11
+ "types": "./src/llm_config.d.ts",
12
+ "default": "./src/llm_config.js"
13
+ }
14
+ },
15
+ "files": ["src", "README.md", "GUIDE.md", "WORLD_PACKAGE_GUIDE.md"],
16
+ "scripts": {
17
+ "test": "node --test tests/*.test.mjs",
18
+ "typecheck": "tsc --noEmit -p tsconfig.json",
19
+ "prepublishOnly": "npm test && npm run typecheck"
20
+ },
21
+ "devDependencies": {
22
+ "typescript": "^5.9.3"
23
+ }
24
+ }