@world-engines/agent-kit 0.1.0-alpha.0

package/assets/docs/development/generated/chatplay-sdk/descriptor.md

@@ -0,0 +1,363 @@
+## ChatPlay SDK 接口描述
+
+Runtime release 3.1 / protocol 3 / schema 3
+
+玩家剧本 view 沙箱 iframe 内可调形态 await window.ChatPlay.<method>(...args) 直接调高层 wrapper
+真源 高层 src/player-client/ui-shell/src/chat-play-sdk/runtime.ts 内联 window.ChatPlay api 对象图
+真源 低层 src/player-client/ui-shell/src/chat-play-sdk/methods/*.ts (host-only RPC 附录见末尾)
+入口必先 await window.ChatPlay.ready 同步握手完成后才能调任何 wrapper
+
+### view 内可调高层 wrapper
+
+#### ready (property)
+- 形态 N/A (property)
+- 返回 `Promise<{ scriptId: string; saveId: string; locale: string; theme: ThemeSnapshot; capabilities: SdkCapabilities }>`
+- 说明 同步握手 Promise 入口必先 await window.ChatPlay.ready 完成后才能调任何 wrapper
+
+#### context
+- 参数 `()`
+- 返回 `{ scriptId: string; saveId: string; locale: string; theme: ThemeSnapshot; capabilities: SdkCapabilities } | null`
+- 说明 同步取当前握手 context ready 之前返回 null
+
+#### listMessages
+- 参数 `(opts?: { after?: string; before?: string; limit?: number })`
+- 返回 `Promise<PersistedListItem[]>`
+- 说明 拉当前 save 持久化消息列表 支持 after/before 切片与 limit 截断
+
+#### sendUserMessage
+- 参数 `(text: string)`
+- 返回 `Promise<{ messageId: string; turnId: string }>`
+- 说明 通过宿主受控 chat.sendUserMessage 发送非空 user 消息；不暴露底层 RPC
+
+#### listAssets
+- 参数 `()`
+- 返回 `Promise<Array<{ id: string; url: string; size: number; mime: string; filename: string; scriptId: string; createdTs: number }>>`
+- 说明 列出当前 script 名下所有资产
+
+#### getAssetUrl
+- 参数 `(id: string)`
+- 返回 `Promise<string>`
+- 说明 把 asset id 解析成运行时可访问 URL (blob:)
+
+#### loadCustomState
+- 参数 `(key: string)`
+- 返回 `Promise<unknown>`
+- 说明 读 view 端自定义状态 缺省 key 返回 undefined
+
+#### listCustomStateKeys
+- 参数 `()`
+- 返回 `Promise<string[]>`
+- 说明 列出当前 save 下所有 custom state key
+
+#### customState (property)
+- 形态 N/A (property)
+- 返回 `ReadonlyCustomStateApi`
+- 说明 按当前 view 作用域只读查询自定义状态；写入、删除和批量提交不暴露给 TMW3 view
+
+#### events (property)
+- 形态 N/A (property; emit(eventType: string, payload: Readonly<Record<string, TmwViewJsonValue>>, interactionId: string))
+- 返回 `TmwViewEventsApi { emit(eventType: string, payload: Readonly<Record<string, TmwViewJsonValue>>, interactionId: string): TmwViewEventEmitReceipt }`
+- 说明 TMW3 view interaction capability；仅可提交 manifest 预声明 eventType，返回 interactionId 与 nonce 回执；最终激活结果通过 interactionResult 事件异步回传，不生成或扩大宿主权限
+
+#### worldline (property)
+- 形态 N/A (property)
+- 返回 `ReadonlyPlayerWorldlines`
+- 说明 TMW3 same-Save worldline API. Scope is host-derived; no Save identifier is accepted or returned.
+
+#### getScenarioMeta
+- 参数 `()`
+- 返回 `Promise<{ scriptId: string; title: string; schemaVersion: number }>`
+- 说明 取当前剧本元信息
+
+#### getProgress
+- 参数 `()`
+- 返回 `Promise<number>`
+- 说明 取进度比 0..1
+
+#### getVariable
+- 参数 `(name: string)`
+- 返回 `Promise<unknown>`
+- 说明 读取当前 save 的触发器变量；scope 由宿主固定为 save，View 不可改写
+
+#### getUnlock
+- 参数 `(target: "node" | "edge", id: string)`
+- 返回 `Promise<{ unlocked: boolean }>`
+- 说明 读取当前 save 中指定节点或边的触发器解锁状态
+
+#### getOwnedResources
+- 参数 `()`
+- 返回 `Promise<OwnedResourceGroup[]>`
+- 说明 返回当前已解锁资源 按节点和属性锚点分组
+
+#### openModelSettings
+- 参数 `()`
+- 返回 `Promise<{ ok: true }>`
+- 说明 请求宿主打开模型设置面板；只返回是否接受意图，不读取或返回任何配置
+
+#### getLocale
+- 参数 `()`
+- 返回 `Promise<string>`
+- 说明 取当前 UI locale (zh / en / ja)
+
+#### getTheme
+- 参数 `()`
+- 返回 `Promise<ThemeSnapshot>`
+- 说明 只读获取宿主主题选择和当前解析后的明暗配色
+
+#### runtimeVersion
+- 参数 `()`
+- 返回 `{ major: number; patch: number }`
+- 说明 同步返回 SDK runtime 版本号
+
+#### on
+- 参数 `(event: ChatPlayEvent, listener: (payload: unknown) => void)`
+- 返回 `() => void`
+- 说明 订阅 SDK 事件 返回取消订阅函数；interactionResult 只关联本 iframe 的 interactionId/nonce，不暴露 committed event envelope、capability 或原始错误；tmwDelivery 不参与互动结果关联
+
+### save.* reserved (返回 EPERM view 永远不可用)
+
+- `save.list` 返回 EPERM 保留给宿主 UI
+- `save.create` 返回 EPERM 保留给宿主 UI
+- `save.delete` 返回 EPERM 保留给宿主 UI
+- `save.rename` 返回 EPERM 保留给宿主 UI
+- `save.load` 返回 EPERM 保留给宿主 UI
+- `save.export` 返回 EPERM 保留给宿主 UI
+
+### 附录 低层 RPC (host-only 不可在 view 内直接调 通过高层 wrapper 间接触达)
+
+以下 callRpc 协议 仅宿主 UI 与 SDK runtime 内部使用 view 端不暴露 callRpc 入口
+
+#### system.ready
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ scriptId: string; saveId: string; locale: Lang; theme: ThemeSnapshot; capabilities: SdkCapabilities; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### system.getLocale
+- 参数类型 `void`
+- 返回类型 `Promise<Lang>`
+- 标记 host-only 不可在 view 内直接调
+
+#### system.getTheme
+- 参数类型 `void`
+- 返回类型 `Promise<ThemeSnapshot>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.listMessages
+- 参数类型 `unknown` 推断形态 `{ after: string; before: string; limit: number }`
+- 返回类型 `Promise<Message[]>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.sendUserMessage
+- 参数类型 `unknown` 推断形态 `{ text: string; meta: Record<string, unknown>; visibility: unknown; abortPending: unknown }`
+- 返回类型 `Promise<{ userMessageId: string; streamId: string; assistantMessageId: string; turnId: string; extractionMessageId: string; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.abort
+- 参数类型 `unknown` 推断形态 `{ streamId: string; reason: string }`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.editMessage
+- 参数类型 `unknown` 推断形态 `{ id: string; content: string }`
+- 返回类型 `Promise<WorldlineEditResult & { streamId?: string; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.deleteMessage
+- 参数类型 `void`
+- 返回类型 `Promise<never>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.rewindToMessage
+- 参数类型 `unknown` 推断形态 `{ id: string }`
+- 返回类型 `Promise<WorldlineRewindResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.forkAtMessage
+- 参数类型 `unknown` 推断形态 `{ id: string; title: string }`
+- 返回类型 `Promise<WorldlineForkResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.cloneFullSave
+- 参数类型 `unknown`
+- 返回类型 `Promise<CloneFullSaveResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.regenerate
+- 参数类型 `unknown` 推断形态 `{ assistantMessageId: string }`
+- 返回类型 `Promise<WorldlineRegenerateResult & { streamId: string; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### chat.retryPersistence
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ status: string; turnId: string; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### save.list
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### save.create
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### save.delete
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### save.rename
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### save.load
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### save.export
+- 参数类型 `unknown`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调 / reserved EPERM
+
+#### state.get
+- 参数类型 `unknown` 推断形态 `{ key: string }`
+- 返回类型 `Promise<unknown>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.getEntry
+- 参数类型 `unknown` 推断形态 `{ key: string }`
+- 返回类型 `Promise<CustomStateEntry | undefined>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.set
+- 参数类型 `unknown` 推断形态 `{ key: string; scope: unknown; authorizedUserIds: unknown; value: unknown }`
+- 返回类型 `Promise<{ ok: boolean; generation: number; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.delete
+- 参数类型 `unknown` 推断形态 `{ key: string }`
+- 返回类型 `Promise<{ ok: boolean; generation: number; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.keys
+- 参数类型 `unknown`
+- 返回类型 `Promise<readonly string[]>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.commitBatch
+- 参数类型 `unknown` 推断形态 `{ idempotencyKey: string; mutations: unknown[]; expectedGeneration: unknown }`
+- 返回类型 `Promise<CustomStateCommitResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### state.requestCheckpoint
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ generation: number; entryCount: number; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### asset.upload
+- 参数类型 `unknown` 推断形态 `{ data: string; filename: string; mime: string }`
+- 返回类型 `Promise<{ url: string; id: string; scriptId: string; saveId: string; sha256: string; r2Key: string; uri: string; cloudRefVerified: boolean; eventSeq: number | null; filename: string; mime: string; size: number; createdTs: number; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### asset.list
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ url: string; id: string; scriptId: string; saveId: string; sha256: string; r2Key: string; uri: string; cloudRefVerified: boolean; eventSeq: number | null; filename: string; mime: string; size: number; createdTs: number; }[]>`
+- 标记 host-only 不可在 view 内直接调
+
+#### asset.delete
+- 参数类型 `unknown` 推断形态 `{ id: string }`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### asset.getUrl
+- 参数类型 `unknown` 推断形态 `{ id: string }`
+- 返回类型 `Promise<string>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.getVariable
+- 参数类型 `unknown` 推断形态 `{ name: string; scope: unknown }`
+- 返回类型 `Promise<TmwVariableV1>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.getUnlock
+- 参数类型 `unknown` 推断形态 `{ id: string; target: unknown }`
+- 返回类型 `Promise<{ unlocked: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.getMeta
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ scriptId: string; title: string; schemaVersion: number; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.getProgress
+- 参数类型 `unknown`
+- 返回类型 `Promise<number>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.setProgress
+- 参数类型 `unknown` 推断形态 `{ ratio: number }`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### scenario.getOwnedResources
+- 参数类型 `void`
+- 返回类型 `Promise<OwnedResourceGroup[]>`
+- 标记 host-only 不可在 view 内直接调
+
+#### ui.requestExit
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### ui.requestReturnToSaveList
+- 参数类型 `unknown`
+- 返回类型 `Promise<ReturnToSaveListAck>`
+- 标记 host-only 不可在 view 内直接调
+
+#### ui.requestFullscreen
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### ui.requestSettings
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### ui.requestHistory
+- 参数类型 `unknown`
+- 返回类型 `Promise<{ ok: boolean; }>`
+- 标记 host-only 不可在 view 内直接调
+
+#### view.querySnapshot
+- 参数类型 `unknown`
+- 返回类型 `Promise<ViewQuerySnapshotResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### view.applyPatch
+- 参数类型 `unknown`
+- 返回类型 `Promise<ViewApplyPatchResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### worldline.list
+- 参数类型 `unknown`
+- 返回类型 `Promise<WorldlineListResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### worldline.fork
+- 参数类型 `unknown`
+- 返回类型 `Promise<ProtocolWorldlineForkResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### worldline.activate
+- 参数类型 `unknown`
+- 返回类型 `Promise<WorldlineActivateResult>`
+- 标记 host-only 不可在 view 内直接调
+
+#### worldline.trim
+- 参数类型 `unknown`
+- 返回类型 `Promise<WorldlineTrimResult>`
+- 标记 host-only 不可在 view 内直接调

package/assets/docs/development/installation-and-structure.md

@@ -0,0 +1,70 @@
+# 安装、Node 24 与项目结构
+
+## 前置条件
+
+- Windows 网络可访问正式依赖源，且系统浏览器可用；安装和首次登录不是离线流程。
+- 一个新的空目录。把正式分发的单个 WorldEngine 初始化 `.cmd` 放进该目录，不放其他文件。
+- 初始化 CMD 自带 portable Node.js `>=24` 和 npm；不要求系统预装 Node/npm/npx。
+
+## 单 CMD 初始化
+
+双击该 CMD，或在其所在空目录运行它。CMD 始终以自身目录为项目目标，不要求另传 target，也不会把工程创建到用户目录或当前 shell 的其他 cwd。它会联网安装并验证固定依赖闭包，保留自身作为 bootstrap/recovery 入口，然后自动启动本地 GUI。账户登录与模型/embedding 代理使用 `127.0.0.1:11450`；作者 GUI 使用 `127.0.0.1:11451`。
+
+当前 `@world-engines/create-project` 尚未作为可用 npx 包发布；不要向新用户提供 `npx --yes @world-engines/create-project...` 作为安装方式，也不要用源码工作区命令冒充正式分发。
+
+初始化成功后，从项目根打开 Codex 或 Claude Code，并在客户端明确允许该项目的 trust。项目级 Codex MCP 的 `cwd = "."` 指向这个 harness project root；`".."` 会错误跳出项目。初始化器不替用户修改 trust、全局 harness 模型或用户级配置。只有包含当前 Agent Kit 的重新打包 CMD 才能作为该修复的最终分发证据。随后可运行：
+
+```powershell
+.\worldengine.cmd doctor
+.\worldengine.cmd npm --version
+```
+
+初始化成功 stdout 是 JSON receipt。失败时保留 stderr 的公开错误码；网络、下载、hash、安装或验证未完成时，不要把半成品目录当作成功项目。
+
+安装器会把 portable Node 放在 `.worldengine/runtime/node/node.exe`。项目根 `worldengine.cmd`、`worldengine-mcp.cmd` 与 `worldengine-codex.ps1` 优先使用它；仅在 portable runtime 缺失时才 fallback 到系统 Node.js >=24。入口不改系统 PATH 或 harness 全局环境。
+
+## 本地 GUI
+
+项目安装完成后运行：
+
+```powershell
+.\worldengine.cmd gui
+```
+
+Host 固定监听 `http://127.0.0.1:11451/` 并默认用系统浏览器打开；自动化或无桌面环境使用 `.\worldengine.cmd gui --no-open`。它不会换端口、结束占用端口的未知进程，也不会读取 Editor 站构建产物。initializer 会验证已安装 Host 的 CLI 与 `assets/gui/index.html`、`app.js`、`styles.css`；任一缺失都不会标记 ready。已有项目出现 `E_GUI_UNAVAILABLE` 时修复项目本地 `@world-engines/project-host` 安装，不要全局安装或改用平台 EXE。
+
+## 两部分项目
+
+```text
+project-root/
+  worldengine.project.json       # project id/revision + Scenario/View digest
+  scenario/
+    source.wes                   # Scenario 唯一作者源（二进制 WESP）
+  view/                          # View 唯一源码树
+    package.json
+    package-lock.json
+    src/
+    public/
+  docs/authoring/development/    # 本文档的安装投影
+  .worldengine/                  # 本地状态、ledger、snapshot、登录与恢复材料
+  AGENTS.md / AGENT.md / CLAUDE.md
+  .codex/skills / .claude/skills / .agents/skills
+```
+
+项目只有 `scenario` 与 `view` 两个可传输 part。下载可选择 `scenario`、`view` 或 `both`；上传的冻结 snapshot 同时绑定这两部分及 manifest revision。`view/dist`、`view/node_modules` 是生成/依赖目录，不是 View source tree authority。
+
+Agent Kit 用项目根内 hardlink/junction 投影 instructions 与 Skills。它不会写用户级 Codex/Claude 配置，也不会安装第三方 harness。从项目根打开 Codex 或 Claude Code，并由作者允许该项目的 trust；Agent Kit 不会静默修改 trust 或全局 harness 模型。Codex 项目 MCP 只有在项目被标记为 trusted 后才会加载；自动发现失败时从项目根运行 `./worldengine-codex.ps1`。
+
+## 最小开发循环
+
+Scenario：先读取当前 revision，再调用 read/schema/validate，最后用稳定 `operation_id` 执行 effect 并核对 receipt/readback。不要直接编辑 `source.wes`。
+
+View：
+
+```powershell
+.\worldengine.cmd npm run typecheck
+.\worldengine.cmd npm run build
+.\worldengine.cmd npm run dev
+```
+
+`.\worldengine.cmd snapshot` 在两部分当前 bytes 上形成可恢复 snapshot；`.\worldengine.cmd sync status` 只读显示本地 transfer/snapshot 状态。`worldengine.cmd npm ...` 使用 portable npm 且只修改子进程 PATH。

package/assets/docs/development/local-gui.md

@@ -0,0 +1,94 @@
+# 本地作者 GUI
+
+本页记录 npm Local Author Project 的 Windows 作者 GUI 设计与当前源码边界。它不是“旧 GUI 已全部迁移”的验收声明：共享组件、真实 WASM Worker 与部分 Host adapter 已有源码证据，但最终 npm 安装树、Browser 交互、Trigger 多画布以及内嵌 Vite 仍需各自的集成回执。
+
+## 启动与 authority
+
+公开 18 包闭包不包含 desktop-win32-x64。GUI 由项目本地 `@world-engines/project-host` 的 NodeHost/browser 路径提供；launcher 仅以 canonical `--project-root` 启动该路径，并把状态限制在 `<project-root>/.worldengine`。
+
+GUI 只是 `scenario/source.wes` 与 `view/` 两部分 authority 的受信编辑宿主：Scenario mutation 必须经过 ProjectHost、revision、operation identity、receipt 与 source readback；View 文件只在项目 `view/` 内读写。UI 内存 state、ReactFlow position、通知或“保存成功”文案都不是 authority。
+
+## Trigger 工作区
+
+本轮设计把 Trigger 编辑面扩展为占满主体区域的 canvas，并提供鼠标右键多级菜单、端口连线、节点编辑/删除、模拟、校验与提交。Trigger 的语义 authority 始终是一份 `TriggerDocumentV3`：
+
+- `event`、`condition`、`effect`、`presentation` 都是同一 TMW3 文档中的节点，不因画布分组而编译成多个 Trigger 文档。
+- `boards` 只保存命名画布定义；membership 只描述一个节点出现在哪些 board；position 按 board 分片保存。它们是作者布局，不改变节点 identity、边 identity 或 TMW3 编译语义。
+- 跨 board 边仍引用同一对 stable node IDs；隐藏在当前 board 之外不等于删除。
+- begin → draft mutation → validate/simulate → commit 的事务门保持不变；布局保存不能绕过 Trigger source revision。
+
+当前共享 UI 已有 `TmwBlueprint`、`TmwFlowLane`、节点增删改、连线/断线、simulation draft、单份 `TriggerDocumentV3` parser 与 `layout_positions` adapter seam。全 body canvas、右键多级菜单、boards membership/分片 position 的最终 Host wire 与重开恢复尚未在本文声称通过；需以安装后的联合 readback 和 Browser 验收为准。
+
+## 世界图工作区
+
+世界图节点详情应维持四个明确页签，而不是把旧 source 压成一个通用 JSON：
+
+1. `metadata`：名称数组/别名、kind、节点 view access、联网补充设定等顶层字段。
+2. `attributes`：递归属性树、类型、`initial_available`、属性 `view_access`、trigger/state/source refs。
+3. `incoming`：`to_id` 为当前节点的关系。
+4. `outgoing`：`from_id` 为当前节点的关系。
+
+旧 wire codec 必须无损保留。实体名称仍是顶层 `name: string[]`；relation identity 是 `relation_id/from_id/to_id`，不能降级成只有 `src/dst/kind/props`；属性既可以是裸值，也可以是带 `_system_prop_envelope_v1` 的值。共享 `normalizeEntityProps` / `serializeEntityProps` 已位于 `@world-engines/authoring-ui/entity-props`，负责递归 value、view access、trigger、states、title、`initial_available` 与 source refs 的往返。未知字段不得因打开并保存 Inspector 而丢失。
+
+CG 不属于 entity props。它的 authority 是 Scenario `runtime_definitions.cg_defs`（wire 路径/兼容读回可见 `runtime_defs.cg_defs`），通过 node/edge/attr anchor 关联世界图对象；GUI 不能把 CG 定义塞回某个节点 attributes。当前 Host schema 明确 `attr_path_supported:false`：只支持顶层属性 CG anchor，深层 `attr_path` 按钮必须禁用并提示，不能截断路径后错误绑定。
+
+当前 `LadybugExplorer` 已接共享 GraphCanvas、分页/search projection、关系增删、实体/属性 mutation 与 spatial ref 校验，但完整四页签编辑和所有旧 codec 字段的 Browser 往返仍需最终集成验收。旧 GUI 的远端媒体库/上传、Puppet/人偶编辑、voice catalog 与成就专用 UI 尚未迁移到本地 npm GUI；不要把通用 View、CG 或属性编辑器称为这些专用能力的替代品。
+
+## 图布局、Worker 与保存
+
+共享 GraphCanvas 使用圆心坐标作为物理模块接口；ReactFlow 左上角坐标只在 canvas seam 转换。节点半径随内容度量，任意两节点的最小圆心距离为：
+
+```text
+r1 + r2 + 3 * max(r1, r2)
+```
+
+真实求解器位于后台 module Worker，并加载真实 Rust/WASM，不允许在 Worker 失败时悄悄切回主线程同步 force 来伪装成功：
+
+- `packages/worldengine-authoring-ui/src/ladybug/graph-layout-worker.ts`
+- `packages/worldengine-authoring-ui/src/ladybug/graph-layout-solver.ts`
+- `packages/worldengine-authoring-ui/src/ladybug/graph-layout-wasm.ts`
+- `packages/worldengine-authoring-ui/src/ladybug/graph-layout.wasm`
+- `packages/worldengine-authoring-ui/wasm/graph-layout/src/lib.rs`
+
+主线程和 Worker 都用递增 generation 做 latest-frame-wins。新帧会 reject/supersede 未完成旧帧；WASM 下载期间到达的新帧也替代旧帧。每个 canvas 持有一个 solver handle，unmount 或场景切换必须 `dispose()`，终止 Worker、移除 listener 并拒绝 pending solve。
+
+拖动时可以先显示乐观位置，但持久化必须异步串行合并：保存中到达的新 position 标为 dirty，当前写完成后用最新 readback/revision 再保存；stale revision 时重读并合并仍 dirty 的位置，不能用旧全量 position 覆盖外部修改。失败必须保持可见且保留 dirty 状态供恢复。当前 Worker/WASM/generation/dispose 有源码和测试入口；完整延迟保存、stale 合并与 Browser 帧体验仍待安装态验收。
+
+## View 与内嵌预览
+
+`ViewWorkspace` 当前公开文件选择、源码编辑、保存与 `refreshPreview()` seam，并允许桌面宿主注入 Monaco/preview slot。内嵌 Vite 已有第一版实现，但仍是 WIP：在最终真机回执到齐前，不得写成已经验收，也不要以外部浏览器或静态 iframe 冒充。
+
+当前安全实现可确认这些边界：preview iframe 只有 `sandbox="allow-scripts"`，不含 `allow-same-origin`；`local-preview-bridge.js` 只为当前 opaque iframe 提供 ChatPlay protocol-v3 `system.ready`，其他 Host method 返回 `EPERM`，ready context 的业务能力为空（asset/edit/delete/worldline 均不可用）；load/clear/dispose 都递增 generation，旧 iframe 或 stale message 不能写回。
+
+Vite 子进程限定在项目 `view/` 与内核分配的 loopback strict port。每个 preview session 另生成不可预测的 128-bit capability 路径，URL 形态只应记录为占位：`http://localhost:<port>/_worldengine_preview/<capability>/`。HTML、模块、Worker、样式和 HMR 都必须留在同一 base；不能记录、复用或输出真实 capability。sandbox 请求仍显示 opaque `Origin: null`，但准入不依赖真 Browser 不稳定的 `Referer`，而由随机 base、Host/path、fetch destination 与原生 Vite WebSocket token 共同约束。
+
+Host 为每个 session 在项目 `.worldengine/` 内以 `wx`/`0600` 创建随机临时 config，检查用户 config 唯一且非 symlink，并在启动失败、退出或 stop 时按 owner pattern 删除。临时 config 注入随机 `base`、`frame-ancestors`、`no-store`、`nosniff`、opaque-origin module fetch gate 与 HMR WebSocket Host/Origin/base gate，保留原生 WebSocket token 校验，且不改写用户的 canonical Vite config。
+
+GUI 的 ready 状态必须按顺序推进：Vite listener 已由 child process tree 验证 → iframe `load` 属于当前 generation → bridge 收到当前 iframe 的 `system.ready` 并完成响应。只看到端口、frame load 或 HMR 连接都不能提前显示“预览就绪”。
+
+启停、HMR、无缓存刷新、子进程回收、真实 ChatPlay 握手和上述 generation/session 防护已有 Node 实现与定向测试入口；完整 Browser 安全与安装态行为仍待最终验收。
+
+## 登录与远端操作边界
+
+登录 cookie/token 只存在于项目专属 WebView/native session，不进入 Node、View iframe、CLI stdout 或项目文件。Node 只使用由 Windows SID、`project_id` 与短期随机 challenge 共同绑定的 named pipe；challenge 不写日志或持久化。transfer request 还要经过 method/path allowlist、body size/digest 和稳定 operation identity 校验。
+
+上传、下载和提审继续服从各自的 plan/confirm/operation/readback 合同。打开 GUI、登录成功、上传 terminal 或 review submitted 都不等于 publish。
+
+## 品牌与 11 项发布资产
+
+品牌标题的唯一源是仓库 `resources/WELogo-title.svg`。npm GUI 的构建只能从这一源生成/复制发布资源，不能在 package、Tauri 或 View 内维护第二份手改 SVG。当前可核对的图布局资产源包括 `graph.css`、Rust source、WASM wrapper、Worker/protocol、WASM binary 及其构建/复制脚本；公开包不携带 Windows desktop launcher。
+
+ProjectHost 的当前 package gate 精确要求 11 个 regular file，且拒绝 symlink：
+
+| 区域 | 文件 |
+|---|---|
+| `assets/gui/` 原样资产 | `index.html`、`app.js`、`local-preview-bridge.js`、`styles.css`、`WELogo-title.svg` |
+| `dist/gui/` 构建资产 | `graph.js`、`graph.css`、`trigger.js`、`trigger.css`、`graph-layout-worker.js`、`graph-layout.wasm` |
+
+`packages/worldengine-project-host/scripts/build-gui.mjs` 从根 `resources/WELogo-title.svg` 复制品牌源，使用 esbuild 生成 graph/trigger/Worker 的无外部 bare import ESM bundle，并复制 authoring-ui 的真实 WASM。`verifyLocalGuiAssets()` 在 `worldengine gui` 启动前验证上述闭包；任一缺失都返回 `E_GUI_UNAVAILABLE`。`app.js` 直接导入 `local-preview-bridge.js`，所以 bridge 是第 11 项，不是可选附件。
+
+Node 层的 package-gate 与 bridge 测试覆盖：11 项闭包逐项 fail closed；bridge 只响应当前 opaque iframe 的 protocol-v3 `system.ready`，拒绝其他 source/origin 和 Host capability，并在 clear/dispose 后拒绝 stale message。测试源码已落；本次文档更新尝试执行这两个定向测试时，本机既有 pnpm store 缺少 `vitest.mjs`，因此不能把它们写成本轮实际 PASS。这些仍只是实施级测试入口，不等于 npm tarball、全新项目安装或 Browser 安全验收。精确发布 hash 以最终 package manifest、`npm pack --dry-run` 与安装 readback 为准。
+
+## 当前完成判据
+
+只有同时拿到以下证据，才可以宣称本地 GUI 对应能力完成：Windows x64 安装树中的真实 PE/品牌/Worker/WASM identity；同一 Scenario source 的 Trigger/世界图/CG readback；布局重开恢复与 stale 合并；真实后台 Worker/WASM 最新帧与 dispose；sandbox preview 的 SDK 握手；以及 Browser 对关键右键、拖动、四页签、跨 board 与错误恢复路径的验收。在此之前应逐项报告已验证能力，不使用“完整旧 GUI 全功能齐全”。

package/assets/docs/development/scene-authoring.md

@@ -0,0 +1,74 @@
+# Scene 作者状态
+
+Scene 表达当前场景的时间、在场对象、空间位置与短期 writer 稿件提示。作者态初值属于 `scenario/source.wes#metadata.initial_scene`；当前作者工具和 Trigger 模拟已公开，旧 SAV 迁移与 production writer 是否部署必须另看对应 runtime/deployment 回执，本文不替它们背书。
+
+## 发现与读回
+
+1. 调用 `world_schema`，读取返回的 `scene` descriptor。当前公开操作是 `scene.begin`、`scene.end`、`scene.present.add`、`scene.present.remove`、`scene.present.replace`、`scene.time.set`、`scene.location.set`、`scene.note.add`、`scene.note.remove`；不要新增 Scene tool 名。
+2. 调用 `trigger_schema`，从 `local_effect_capabilities` 中读取同名 `scene.*` capability 的当前 `argument_schema`。参数、required 字段与限制以该注册 schema 为准，不从本文复制机械规则。
+3. 使用 `world_get` 的 ids 或分页模式读取结果中的 `metadata.initial_scene`。`world_get` 仍是现有 world read tool，不存在单独的 Scene read tool。
+
+## 语义边界
+
+- `scene.begin` 建立新的 Scene 初值；其后用 present/time/location/note 操作做 typed mutation，`scene.end` 结束整个 Scene。
+- `worldTime` 是 Scene 的单一可写世界时间。不要另建永久时间属性或让 scheduler/Trigger 持有第二份可写时钟。
+- `presentEntityNodeIds` 可以引用当前 logical graph 中任何现存 node，不限人物 kind。删除或替换被引用 node 前先移出 Scene；不存在的 node 必须拒绝。
+- `spatialRef` 与在场对象是独立字段。它绑定 `{ worldId, sourceRevision, spatialId }`，其中 `sourceRevision` 是 Spatial World 自身的 map revision，不是 project revision；地图 identity/revision/object 任一不匹配都不能写入或模拟。
+- `scene.note.add` 的 `text` 是 writer-facing manuscript data，逐字保留空白、换行和 Unicode。它不是 system prompt、永久 world fact、entity attribute 或检索语料；不要把它复制进这些位置。
+- note lifetime 只能是 `once` 或 `scene_end`。`once` 只在成功 writer commit 的精确 receipt 绑定消费后移除；失败或重试不能提前消费。`scene_end` 留到 Scene 结束。作者工具只负责 author source/模拟，不能据此宣称 production writer 已部署。
+
+## 写入与 Trigger
+
+直接作者修改继续使用 `world_apply.operations` 承载上述 9 个 `scene.*` type，携带稳定 `operation_id` 与当前 `expected_project_revision`；Host 会在同一事务更新普通地图编辑相关的 stable ref revision，输入仍严格校验 identity/revision/object。写入后用 `world_get` 核对 `metadata.initial_scene`。不要直接编辑 metadata、WESP 或 SAV。
+
+Trigger effect 使用 `trigger_schema.local_effect_capabilities` 已注册的同名 capability 和其 `argument_schema`，不创建自定义 action。按 `trigger_read` → `trigger_validate` → `trigger_apply` → `trigger_read` → `trigger_simulate` 验证，并检查模拟结果的 `state.scene`。模拟会用当前 author source 校验 node 存在性和 Spatial World map revision，不能通过自造 input state 绕过。
+
+转换旧剧本时，把旧 `next-system-prompt` 或等价“一次性下一轮写作指令”映射为 `scene.note.add`，默认按其真实生命周期选择 `once`；只有原语义明确持续到场景结束时才用 `scene_end`。原文逐字作为 manuscript `text`，不能升级成永久 fact/attribute，也不能作为 system prompt 注入。
+
+## Trigger 到 View 的显式通知
+
+`event.start` 与 `event.broadcast` 可以在 capability `arguments` 中选填 `viewVisiblePayload`。它是专门给 View 的公开数据面：最多 64 个平铺字段，每个值只能是 JSON primitive（`string`、finite `number`、`boolean` 或 `null`）。缺省时不产生 View 通知；不要把 writer 文本、Scene note、内部 event payload 或 receipt 放入此字段。
+
+该字段只会在 Runtime3 成功提交由冻结 author capability 创建的 event lifecycle 投递后进入下行；writer、system、View 入站事件不能自行声明其来源。延迟与即时广播都使用同一规则。它是 live best-effort 通知：没有历史回放、没有 ACK，也不能作为存档重放、业务确认或可靠队列。
+
+View manifest 的 `view_deliveries` 只能从 `viewVisiblePayload` 逐键映射，不能从 `event.payload` 映射。最小配对如下；`event.start` 的目标 `event.signal` 与 manifest 的 `eventType` 都对应实际下行事件 `scene.signal`：
+
+```json
+{
+  "capability_id": "event.start",
+  "arguments": {
+    "eventNodeId": "event.signal",
+    "count": 1,
+    "delay": { "domain": "world_time", "value": 5 },
+    "payload": { "internalRouting": "never-visible" },
+    "viewVisiblePayload": { "action": "open" }
+  }
+}
+```
+
+```json
+{
+  "view_deliveries": [{
+    "deliveryId": "scene.toast",
+    "eventType": "scene.signal",
+    "payloadSchema": {
+      "type": "object",
+      "additional_properties": false,
+      "properties": { "action": { "type": "string", "required": true } },
+      "max_bytes": 128
+    },
+    "fields": { "action": { "from": "viewVisiblePayload", "path": ["action"] } }
+  }]
+}
+```
+
+先用 `trigger_validate` 验证 capability 参数，再用 `trigger_simulate` 检查 state 与已注册 effect；`authorViewEvents` 仅由真实 Runtime 的成功提交 receipt 产生，不是 Host 模拟输出。构建工具链中等价的最小 parse/compile 检查如下（`document` 是完整 TriggerDocumentV3，`manifest` 是完整 ViewInteractionManifestV3）：
+
+```ts
+const parsedManifest = parseViewInteractionManifestV3(manifest);
+if (parsedManifest === null) throw new Error("manifest invalid");
+const compiled = await compileTmw3(document, getCanonicalTmwCapabilityRegistryV3());
+if (!compiled.ok) throw new Error(compiled.diagnostics.map((item) => item.code).join(","));
+```
+
+任何一侧缺失、schema 不匹配或非 primitive 值都 fail closed，不以一般 committed event payload 兜底。