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

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/assets/README.md

@@ -0,0 +1,58 @@
+# WorldEngine Authoring Kit
+
+本套件把 Local Author Project 的唯一 system prompt、开发接口文档、Skills、各客户端 MCP 配置与作者工作流物化到 `docs/authoring/`。它不包含 agent supervisor，也不安装 Codex、Claude Code 或 DeepSeek Harness。
+
+## Harness 入口
+
+- Codex：从项目根打开并允许 project trust 后读取 `AGENTS.md`、`.agents/skills` 与 `.codex/config.toml`；`.codex/skills` 保留为同一 Skill 树的兼容入口。harness cwd 已是项目根，因此 MCP 配置使用 `cwd = "."`，并只转发网络与当前公开 capability 环境变量。该修复需重新打包初始化 CMD 后才进入最终分发物。
+- Claude Code：读取 `CLAUDE.md`、`.claude/skills` 与项目 `.mcp.json`。
+- DeepSeek Harness：仅支持其自行消费通用 `.mcp.json` 或 `worldengine` CLI 的形态；套件未安装该 harness，也不声明真机验证。
+- 通用 CLI：读取 `AGENT.md` 和 `.agents/skills`，在 Windows 运行 `.\worldengine.cmd --help` 获取当前命令合同；它优先 portable Node，不要求全局 Node/npm/npx。系统 Node 已存在时，`npx --no-install worldengine --help` 是等价入口且禁止下载。
+
+根 `AGENTS.md`、`CLAUDE.md` 与 `AGENT.md` 都 hardlink 到 `docs/authoring/system-prompt.md`，不存在另一份 project instructions 或补充 system prompt。任何接口在使用前先查 `docs/authoring/development/`；MCP 工具还必须以本次实时 `tools/list` 为准，未知接口不得猜测。外部工具资料只查维护者官方文档。
+
+三份根 instruction 是同一个 canonical 文件的 hardlink，三套 skill 目录是 `docs/authoring/skills` 的 junction。各客户端配置与根 launcher 分别 hardlink 到 `docs/authoring/configs` 和 `docs/authoring/launchers` 的 canonical 文件。内部编排、恢复和发布 Skills 保持 disabled；缺少分发许可的 Skills 保持 HOLD。
+
+若当前 Codex 版本不能自动发现项目级 MCP，从项目根显式启动：
+
+```powershell
+.\worldengine-codex.ps1
+.\worldengine-codex.ps1 exec --ephemeral --sandbox read-only "只调用 world_schema"
+```
+
+launcher 在运行时定位 canonical project root，验证项目内 `@world-engines/project-host` identity，并以 argv array 仅覆盖本次 Codex 进程的 `mcp_servers.worldengine`。`worldengine.cmd` 是通用 CLI 入口，`worldengine-mcp.cmd` 复用它启动固定 `mcp` 子命令；二者和 Codex launcher 都优先使用项目内 `.worldengine/runtime/node/node.exe`，仅当 portable runtime 缺失时才接受系统 Node.js >=24。它们不改 PATH、不写用户配置、不设置 provider/auth，也不移除其他 MCP server。
+
+Claude Code 也应从项目根打开并由作者完成其 project trust；套件不会替作者静默改 trust、用户级配置或全局 harness 模型。
+
+`worldengine` 使用 server-scoped `default_tools_approval_mode = "writes"`：Host 标记为 read-only 的 schema/read/search 工具无需写入批准，持久化 effect 与未标记只读的交互工具仍要求批准。此设置不改变其他 MCP 或 Codex 的全局审批策略。
+
+`.\worldengine.cmd gui` 从已安装的 ProjectHost 启动固定 `http://127.0.0.1:11451/` 服务并默认打开系统浏览器；自动化使用 `.\worldengine.cmd gui --no-open`。View scripts 使用 `.\worldengine.cmd npm run <script>`，由 portable runtime 执行，不依赖全局 Node/npm，也不修改全局 PATH。
+
+## 全文进入 Ladybug
+
+先运行当前 `.\worldengine.cmd --help` 获取真实入口；CLI 合同变化时以已安装版本为准，不从本文臆造新参数。职责边界固定如下：
+
+```text
+.\worldengine.cmd ingest <path> <scope-id> <source-id> <source-revision>
+.\worldengine.cmd ingest next <operation-id>
+.\worldengine.cmd ingest accept <operation-id> <request-id> <candidate-json-file>
+.\worldengine.cmd ingest commit <operation-id>
+.\worldengine.cmd ingest status <operation-id>
+.\worldengine.cmd ingest resume <operation-id>
+.\worldengine.cmd ask <scope-id> <query>
+.\worldengine.cmd recall prepare [scope-id]
+.\worldengine.cmd recall <query> [limit]
+.\worldengine.cmd read <entity-id>
+```
+
+首个 `ingest` 在 stdout 返回 `{ receipt, next }`；harness 用 `next.request.structuredRequest.messages` 调用自己的模型，并按同处的 `jsonSchema` 生成候选。候选 JSON 必须是项目内不超过 8 MiB 的文件，交给 `accept` 校验并落 checkpoint；ready 后 `commit`。Host 不重打 raw bytes。`resume` 若已 ready 则 commit，否则返回下一个 request；旧 provider journal 没有 adapter 时明确失败，绝不静默迁移。讨论、推理草稿、中间对话与废案不写入作品。
+
+初次导入全新文件时，harness 根据当前 manifest 的 `local_scenario_id` 与规范化项目相对路径稳定生成 scope/source/revision 参数，不让作者理解内部 identity；只有既有 source identity 冲突且 readback 无法消歧时才询问。
+
+Agent Kit 绝不分发 provider key，也不要求作者配置 DeepSeek/OpenRouter key。embedding 只能在用户已登录后通过本机 `127.0.0.1:11450` 服务生成，并按账户余额结算；不得绕过该入口直连 provider。独立本地向量准备、混合检索与多跳查询只在当前 CLI/MCP schema 已公开相应接口后使用。semantic/reopen 验收与 Trigger 顺序见 `docs/authoring/guides/long-form-ladybug-trigger.md`。
+
+用户要求查书时，先说明 semantic 检索需要产品登录且 `recall prepare [scope-id]` 按账户余额计费，再准备当前 revision。`ask` 在外部 harness 路径只返回 `candidates`、`graphPaths`、`pathOptions` 与 `evidence` 等证据 bundle；最终答案由 harness 基于证据生成，不把候选冒充结论。
+
+启用的 `lossless-document-authoring` Skill 说明原始 bytes、checkpoint、精确原文定位与有向证据问答。`staged` 不等于已入图，完整 source coverage 不等于完整抽取；恢复使用 Host 返回的 operation ID。此套件本身不构成真实全书验收证明。
+
+需要环境代理时，作者在启动 harness/CLI 前自行设置 `NODE_USE_ENV_PROXY=1` 及适用的 proxy 变量。配置中的 `env_vars` 只负责转发现有值；仅设置 `HTTP_PROXY` 不代表 Node fetch 已启用环境代理。套件不写全局环境，也不固定代理端口。

package/assets/docs/development/README.md

@@ -0,0 +1,25 @@
+# WorldEngine 作者开发文档
+
+这是随 Local Author Project 安装的完整开发入口。canonical 安装位置是 `docs/authoring/development/`；本目录只是 npm 包内的源投影，不要在生成后的项目里再维护一套接口权威。
+
+## 推荐阅读顺序
+
+1. [安装、Node 24 与项目结构](installation-and-structure.md)
+2. [AuthoringBridge 当前工具面](authoring-bridge.md)
+3. [worldengine CLI](cli.md)
+4. [本地 GUI 与 HTTP endpoints](local-gui.md)
+5. [长文、世界图、Trigger、Layout 与 Retrieval](authoring-workflows.md)
+6. [ChatPlay SDK 与 React/Vite View](chatplay-view.md)
+7. [Scene 作者状态](scene-authoring.md)
+7. [登录、传输、提审、恢复与安全](desktop-transfer-security.md)
+
+## Authority 速查
+
+- Scenario 的唯一作者源：`scenario/source.wes`。只能由 GUI、`worldengine` MCP 或等价 CLI effect 修改。
+- View 的唯一源码树：`view/`。作者直接编辑 TypeScript/React/Vite 源码，再运行 typecheck/build。
+- `worldengine.project.json` 是 project identity、revision 与两部分 digest 的 manifest，不是第三份业务内容源。
+- `.worldengine/` 保存本项目的 snapshot、operation、projection、恢复材料与 project-bound 登录态；不得手改、提交或复制到别的项目。
+- `docs/authoring/system-prompt.md` 是作者 system prompt 的唯一文档投影；根 instructions、各 harness Skills/config 与本文档都链接回同一 Agent Kit source，不在项目里复制改写语义。
+- 当前工具面以 MCP `tools/list` 与本地 `worldengine --help` 为运行时权威。本文的重复接口投影由脚本和 source SHA 防漂移。
+
+`prepared`、`pending_review` 和“已提交审核”都不等于 `ready`；审核也不等于 publish。此作者工具链没有 publish、部署、账户权限或远程删除命令。

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

@@ -0,0 +1,52 @@
+# AuthoringBridge 当前工具面
+
+AuthoringBridge 是 Scenario 作者操作的唯一公共工具合同。它只校验与分发，不自行实现 Ladybug、Trigger、Layout、preview 或远端服务。MCP `tools/list` 返回本进程真实的 descriptor 和 `worldengine/toolAvailability`；adapter 未声明的能力会 fail closed。
+
+完整逐工具 JSON Schema 见机械投影 [generated/authoring-bridge-contract.md](generated/authoring-bridge-contract.md)，机器可读版本见 [generated/authoring-bridge-contract.json](generated/authoring-bridge-contract.json)。
+
+## 当前工具与返回边界
+
+| 工具 | effect | 主要输入 | 返回合同 |
+|---|---:|---|---|
+| `world_schema` | 否 | `{}` | 当前世界图 schema/capability |
+| `world_search` | 否 | `query`, `mode`; 可选 `limit,cursor,filters` | 分页命中；semantic 只能消费 prepared 向量 |
+| `world_get` | 否 | `ids` 或 `limit`; 可选 `cursor,include_relations` | 实体及可选关系 readback |
+| `world_traverse` | 否 | `start_ids,direction,depth`; 可选 scope/kind/limit | 有向遍历结果，depth 1..4 |
+| `world_apply` | 是 | 非空 `operations` | 标准 effect receipt；含 Ladybug 与 spatial mutation |
+| `world_history` | 否 | 非空 `target_ids`; 可选 cursor/limit | 目标历史页 |
+| `trigger_schema` | 否 | `{}` | 当前 Trigger 文档 schema |
+| `trigger_read` | 否 | 可选 `trigger_ids,include_document` | Trigger 文档/readback |
+| `trigger_apply` | 是 | 非空 `operations` | 标准 effect receipt |
+| `trigger_validate` | 否 | `candidate_document` | validation issues/通过结果，不持久化 |
+| `trigger_simulate` | 否 | `event,state` | 确定性模拟命中/动作结果，不持久化 |
+| `interaction_layout_read` | 否 | `viewport: pc|mobile` | 当前交互布局 |
+| `interaction_layout_apply` | 是 | `viewport,patch` | 标准 effect receipt |
+| `trigger_blueprint_layout_read` | 否 | 可选 `trigger_ids` | Trigger 蓝图布局 |
+| `trigger_blueprint_layout_apply` | 是 | `patch` | 标准 effect receipt |
+| `retrieval_config_read` | 否 | `{}` | 当前 retrieval config |
+| `retrieval_config_apply` | 是 | `patch` | 标准 effect receipt |
+| `retrieval_probe` | 否 | `query,candidate_config`; 可选 `top_k` | 候选配置探测结果，不保存配置 |
+用户确认走当前 harness 对话，不调用内部 `ask_user`。预览检查优先使用本次 `tools/list` 标记 available 的 `preview_inspect`/`preview_interact`：它们由独立 Chrome adapter 执行，不需要额外环境桥接；`preview_inspect` 返回的真实 image 才是像素证据。不可用时再按 CLI 启动预览并使用 harness 的 Browser/screenshot 工具；两条路径都必须 fail closed，不伪造截图或交互。
+
+`preview_inspect`/`preview_interact` 不持久化项目，不得携带 `effect_identity`。五个 project effect 是 `world_apply`、`trigger_apply`、`interaction_layout_apply`、`trigger_blueprint_layout_apply`、`retrieval_config_apply`。
+
+## effect identity 与幂等
+
+每个 effect 必须额外提供：
+
+```json
+{
+  "operation_id": "author-stable-id-001",
+  "expected_project_revision": 7
+}
+```
+
+`operation_id` 是一次逻辑意图的稳定 identity；同 ID、同 canonical call 可重放，绑定到不同 call 返回 `E_OPERATION_ID_CONFLICT`。`expected_project_revision` 是调用前 readback 的非负安全整数。stale 时必须重读并重新合并意图，不能只替换 revision 后盲重试。
+
+成功 effect receipt 固定包含 `schema_version=1`、相同 `operation_id`、`project_id`、`previous_project_revision`、`next_project_revision`、唯一非空 `changed_sections`、64 位 hex `project_snapshot_digest` 与 `readback_verified=true`。无变化时 revision 不变；有变化时只加 1。缺字段、identity 不匹配或未验证 readback 都以 `E_EFFECT_RECEIPT_INVALID` 包装为 `E_VALIDATION_FAILED`。
+
+## 错误合同
+
+公共错误对象包含 `code`、脱敏 message 与可选 details。稳定 code 是：`E_PROJECT_NOT_OPEN`、`E_PROJECT_BUSY`、`E_PATH_OUTSIDE_PROJECT`、`E_STALE_PROJECT_REVISION`、`E_SCHEMA_INVALID`、`E_VALIDATION_FAILED`、`E_REFERENCE_MISSING`、`E_OPERATION_ID_CONFLICT`、`E_OPERATION_UNCERTAIN`、`E_PREVIEW_NOT_RUNNING`、`E_AUTH_REQUIRED`、`E_REMOTE_FORBIDDEN`、`E_CONFIRMATION_REQUIRED`、`E_ROLLBACK_FAILED`。
+
+adapter 缺 capability/handler 时 details 的 `failure` 分别为 `E_CAPABILITY_UNAVAILABLE`/`E_HANDLER_UNAVAILABLE`。CLI 对 schema 错误退出 2，其他公开错误退出 1；stderr 不打印 secret 或内部 details。`E_OPERATION_UNCERTAIN` 的恢复动作是按同 operation readback/reconcile，不是新建 operation。

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

@@ -0,0 +1,48 @@
+# 世界图、长文、Trigger、Layout 与 Retrieval
+
+## 世界图编辑
+
+1. 读 `world_schema`、当前 project revision 与目标实体。
+2. 用 `world_search/get/traverse/history` 收集事实与 reverse impact。
+3. 构造 `world_apply.operations`；空间对象也由此工具承载：`spatial_create` 使用稳定 kebab-case key、kind、label、有限 x/y，update/remove 使用既有 id，remove 还要 `confirmed`。
+4. 以稳定 effect identity apply；核对 receipt，再 `world_get` readback。
+
+Ladybug/Trigger 只保存 stable entity/spatial 引用，不复制空间树。删除或改名之前先查被引用面。
+
+## Scene
+
+先读 `world_schema.scene`、`trigger_schema.local_effect_capabilities` 与 [Scene 作者状态](scene-authoring.md)。直接修改只经 `world_apply` 的 9 个 `scene.*` operations，随后用 `world_get` 读回 `metadata.initial_scene`；Trigger 使用同名 registered capability 及其当前 `argument_schema`，再 validate/apply/readback/simulate。
+
+Scene 的 `worldTime` 是单一世界时间；在场对象可引用任意现存 logical graph node。`spatialRef.sourceRevision` 是地图自身 revision，不是 project revision。manuscript note 只保存 writer-facing 原文，lifetime 为 `once|scene_end`，不是 system prompt、永久 fact 或 entity attribute。作者工具/模拟可用不表示旧 SAV 迁移或 production writer 已部署。
+
+## 长文无损导入与恢复
+
+初次全新来源由 harness 根据当前 manifest 的 `local_scenario_id` 与规范化项目相对文件路径稳定生成 CLI identity；只有既有 identity 冲突且 source readback 无法消歧时才询问作者。
+
+`ingest` 可直接接收绝对外部 `.txt/.md/.markdown` 路径。Host 在单一入口以打开句柄复核 path/inode/大小与读取期变化，逐字节复制到 `.worldengine/imported-sources/<content-hash>.<ext>`，返回 `sourceStoragePath`；稳定逻辑 `sourcePath` 是 `external-source/<path-hash>.<ext>`。最终 `world_source_document` 保留 logical path、storage path、raw bytes、长度与 SHA-256。物理 content hash 只用于副本存储，不是初始 source identity；外部原件保持不变，也不会被执行。代码工程或其他资源仍由 harness 静态安全复制后转换。多轮讨论可以逐项确认映射，但不会写 DB；只有用户明确表达成稿/生成/写入意图后才进入 ingest。
+
+`ingest <path> <scope-id> <source-id> <source-revision>` 一次捕获整本原始 bytes，并在 stdout 返回 `{ receipt, next }`；这只建立 source/checkpoint，不写 DB。外部 harness 自己处理 `next.request.structuredRequest.messages`，以其 `jsonSchema` 校验输出，把项目内不超过 8 MiB、经路径/大小/编码/读取期 TOCTOU 复核的最终 candidate JSON 通过 `ingest accept <operation-id> <request-id> <candidate-json-file>` 交回 Host；`accept` 只校验并分批落 checkpoint，绝不保存对话或候选废案，也不写 DB。循环 `ingest next`，全部窗口 ready 后才由显式 `ingest commit` 以一次 CAS 写入最终成书内容。Host 不重打 raw bytes。`resume` 在 ready 时 commit、否则返回 next；旧 provider journal 没有 adapter 时明确失败，不静默迁移。
+
+进度/结果至少检查：`operationId`、`rawByteSha256`、`roundtripVerified`、`sourceCoverage`、`graphStatus`、`pendingWindows`、`failedWindows`、`embeddingStatus` 与最终 `commitReceipt`。`staged` 不等于入图；source coverage 完整不等于 graph 完整；`graphStatus=partial` 永远只能称部分图。v3/v4 只修复有已保存 diagnostics 的坏窗口，不重抽完整窗口，不无限重复相同诊断。
+
+进程退出、网络中断或结果不确定时：保存首个 stdout `{ receipt, next }` 中的 operation ID，运行 `ingest status`，再对同一 ID `ingest resume`。不要删 journal/checkpoint、换 source identity 或重发已完成窗口。旧 adapter 的 stderr JSONL 只属于 legacy journal，不是 harness-v1 的 operation identity 来源。
+
+用户要求查书时，先说明需产品登录且 `recall prepare [scope-id]` 按账户余额计费，再准备当前 revision。外部 harness 的 `ask` 只返回 candidates、graphPaths、pathOptions、evidence 等证据 bundle；harness 自己依据原文和每跳有方向的路径作答，没有证据就明确不可回答，不能用模型常识补齐。`dump` 分别导出 source bytes、图、组合审阅材料与 manifest；导出成功不提升图完整度或审核状态。
+
+## prepared 向量与召回
+
+编辑态 raw graph 不为每次改动生成 embedding。向量准备是独立本地阶段，必须在产品登录后通过 `127.0.0.1:11450` 按账户余额结算；Agent Kit 不分发或要求配置 provider key。semantic/hybrid、多跳查询与相关验收必须消费当前 source revision 的 prepared vector snapshot，且 service/profile/dimension/text identity 与覆盖闭合。缺失或 stale 时 fail closed，不能回退关键词；具体 prepare/query 命令和错误码只从当前 CLI help/MCP schema 读取。
+
+验收至少包含：同义查询命中、无关查询被距离门拒绝、末段独特事实命中、`read` provenance（stable sourceId、项目相对 path、digest/revision）以及 Host 重启后的相同结果。
+
+## Trigger
+
+固定顺序是 `trigger_schema` → `trigger_read` → entity/spatial readback → `trigger_validate(candidate_document)` → `trigger_apply` → `trigger_read` → `trigger_simulate(event,state)`。validate/simulate 不保存；apply 保存完整 candidate mutation。issue 未清零不 apply；simulate 要覆盖至少一个预期命中与一个预期不命中。
+
+## Layout
+
+交互布局按 `pc` 与 `mobile` 分开 read/apply。先读当前 viewport 布局，合并 patch，再 apply/readback。Trigger blueprint layout 是另一份投影，用 `trigger_blueprint_layout_read/apply`；它只组织蓝图呈现，不改变 Trigger 语义。不要用布局 patch 写 Scenario 实体或把 PC 布局复制为 mobile authority。
+
+## Retrieval config
+
+先 `retrieval_config_read`。对候选 patch 使用 `retrieval_probe(query,candidate_config,top_k)` 比较代表性、否定、无关和尾部样本；probe 不保存。只有接受候选后才 `retrieval_config_apply`，再 readback。调 config 不会生成 embedding，也不能把 pending raw graph 变成 prepared。

package/assets/docs/development/chatplay-view.md

@@ -0,0 +1,111 @@
+# ChatPlay SDK 与 React/Vite View
+
+View 运行在不含 `allow-same-origin` 的 sandboxed iframe。它只能通过 ChatPlay SDK 与宿主通信，不能访问 top window、http-only cookie、AuthoringBridge、项目文件系统或 `.worldengine/`。
+
+完整接口投影随包提供：
+
+- [generated/chatplay-sdk/descriptor.md](generated/chatplay-sdk/descriptor.md)：人类可读 descriptor
+- [generated/chatplay-sdk/chatplay-sdk.d.ts](generated/chatplay-sdk/chatplay-sdk.d.ts)：TypeScript declaration
+- [generated/chatplay-sdk/descriptor.json](generated/chatplay-sdk/descriptor.json)：机器可读 descriptor
+- [generated/chatplay-sdk/SOURCE.json](generated/chatplay-sdk/SOURCE.json)：上游文件 SHA-256 与同步命令
+
+这些文件逐字来自 `packages/chatplay-sdk-descriptor/generated/`。更新 canonical generator 后运行：
+
+```powershell
+node packages/worldengine-agent-kit/scripts/sync-development-contracts.mjs
+node packages/worldengine-agent-kit/scripts/sync-development-contracts.mjs --check
+```
+
+## React/Vite 起点
+
+initializer 已创建 React 18、TypeScript、Vite、Tailwind 和 Three.js 工程。`vite.config.ts` 使用 `@world-engines/view-sdk` 的 `chatPlay()` plugin；结构化抽取与前端开发使用用户在外部 harness 中自行选择或登录的模型；本项目不代配 harness 模型或分发 key。只有平台 embedding 等经用户已登录的本机 `127.0.0.1:11450` 账户代理按余额结算，不需要或接收 provider API key，也不写进浏览器 bundle。
+
+```tsx
+import { useEffect, useState } from "react";
+
+type Message = Awaited<ReturnType<Window["ChatPlay"]["listMessages"]>>[number];
+
+export function App() {
+  const [messages, setMessages] = useState<readonly Message[]>([]);
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    const refresh = async () => {
+      try {
+        await window.ChatPlay.ready;
+        const next = await window.ChatPlay.listMessages({ limit: 100 });
+        if (active) setMessages(next);
+      } catch (reason) {
+        if (active) setError(reason instanceof Error ? reason.message : "读取消息失败");
+      }
+    };
+    const stops = ["messageAdded", "messageUpdated", "messageDeleted"].map((event) =>
+      window.ChatPlay.on(event as "messageAdded" | "messageUpdated" | "messageDeleted", () => { void refresh(); }),
+    );
+    void refresh();
+    return () => { active = false; stops.forEach((stop) => stop()); };
+  }, []);
+
+  const submit = async () => {
+    const text = draft.trim();
+    if (text === "") return;
+    try {
+      await window.ChatPlay.ready;
+      await window.ChatPlay.sendUserMessage(text);
+      setDraft("");
+    } catch (reason) {
+      setError(reason instanceof Error ? reason.message : "发送消息失败");
+    }
+  };
+
+  return <main>
+    {error !== null && <p role="alert">{error}</p>}
+    <ol>{messages.map((message) => <li key={message.id}>{message.text}</li>)}</ol>
+    <div>
+      <input value={draft} onChange={(event) => setDraft(event.target.value)} />
+      <button type="button" onClick={() => { void submit(); }}>发送</button>
+    </div>
+  </main>;
+}
+```
+
+入口必须先 `await window.ChatPlay.ready`。新项目 scaffold 的 `src/chatplay.ts` 和 `src/App.tsx` 就是同一模式的可执行版本：只经 `listMessages`、`sendUserMessage` 和消息事件展示、发送与刷新。实际 wrapper、request/response/event payload、能力协商与错误字段必须以随包 descriptor 为准。不要调用附录标记 host-only 的低层 RPC，也不要手写 `postMessage` 绕过高层 wrapper。
+
+MCP 只在 iframe 外用于开发、预览和截图；产品 bundle 中 MCP 不存在也不可探测。不要把 MCP client/server、AuthoringBridge、账户代理、cookie 或 Scenario 原文导入 `view/` runtime。
+
+## TMW 作者通知
+
+View 只能接收作者显式公开的 TMW 通知。作者在 `event.start` 或 `event.broadcast` 的 `viewVisiblePayload` 中声明最多 64 个平铺 JSON primitive；未声明就没有通知。manifest 的 `view_deliveries` 只能以 `{ "from": "viewVisiblePayload", "path": ["单个键"] }` 选择这些字段，不能映射 `event.payload`、Scene note、writer 文本、内部 event 或 receipt。
+
+`tmwDelivery` 是 live best-effort 通知，不回放历史、没有 ACK，不能用作业务确认或可靠队列。`opaqueId` 只能用于当前 View 的去重。
+
+```tsx
+useEffect(() => {
+  const stop = window.ChatPlay.on("tmwDelivery", (delivery) => {
+    if (delivery.deliveryId !== "scene.toast") return;
+    const action = delivery.payload.action;
+    if (typeof action === "string") console.info(action);
+  });
+  return stop;
+}, []);
+```
+
+与该 View 配对的 manifest 字段必须是：
+
+```json
+{ "action": { "from": "viewVisiblePayload", "path": ["action"] } }
+```
+
+## 本地验证
+
+```powershell
+.\worldengine.cmd npm run typecheck
+.\worldengine.cmd npm run build
+.\worldengine.cmd npm run dev
+```
+
+该入口使用项目 portable Node 自带的 npm，并只为当前子进程前置 Node 目录到 PATH；不修改用户或系统 PATH。系统 Node/npm 已明确可用时，普通 `npm run ...` 是等价入口。
+
+验证 PC/mobile viewport、console、network、runtime error 和真实预览宿主。Vite HMR 只证明本地 View 变化；Scenario readback、snapshot、上传或提审是不同证据。资源加载必须异步；不要把远端凭据、Scenario 原文或 decrypted bin 放进 bundle/localStorage/IndexedDB。

package/assets/docs/development/cli.md

@@ -0,0 +1,145 @@
+# `worldengine` CLI
+
+所有命令从项目根运行。Windows 优先使用 portable runtime launcher：
+
+```powershell
+.\worldengine.cmd --help
+```
+
+系统 Node.js >=24 已存在时，`npx --no-install worldengine --help` 是等价入口；`--no-install` 禁止下载。launcher 不改全局 PATH。
+
+stdout 是 JSON receipt/readback；harness-v1 的首个 `ingest` 直接返回 `{ receipt, next }`，不依赖 stderr 取得 operation identity。旧 ingestion adapter 可能仍输出 stderr JSONL 进度。失败 stderr 只给公开错误码，schema/用法错误退出 2，其他失败退出 1。
+
+## 本地与 AuthoringBridge
+
+```text
+worldengine doctor
+worldengine snapshot [operation_id expected_project_revision]
+worldengine sync status
+worldengine operation <operation-id>
+worldengine tool <registered-tool-name> --input-json-file <project-relative-json> [operation_id expected_project_revision]
+worldengine preview
+worldengine gui
+worldengine gui --no-open
+worldengine mcp
+```
+
+示例：
+
+PowerShell 调用 `.cmd` 时推荐先把输入保存为项目内 JSON 文件，避免 shell 引号和转义改变参数。例：创建 `requests/world-search.json`：
+
+```json
+{
+  "query": "北门守卫",
+  "mode": "keyword",
+  "limit": 10
+}
+```
+
+```powershell
+.\worldengine.cmd doctor
+.\worldengine.cmd tool world_search --input-json-file requests\world-search.json
+.\worldengine.cmd snapshot snapshot-release-001 8
+```
+
+`--input-json-file` 只接受项目根内不超过 8 MiB 的 UTF-8 JSON object regular file；不得指向项目外路径、凭据文件、reparse point 或把 secret 写入请求。具体字段始终以当前 `tools/list` 返回的 input schema 为准。直接 Node/harness 调用若能以参数数组逐项传递，可以使用 inline `<input-json>`，但它不是 PowerShell `.cmd` 的推荐形式。
+
+`snapshot` 不带 identity 时会从 project id、当前 revision 与固定请求确定性派生 operation ID。`operation` 读取 snapshot ledger。`preview` 从 `view/` 启动 loopback Vite；`gui` 在 `127.0.0.1:11451` 启动持续的项目本地 Node 服务并默认打开系统浏览器，`--no-open` 只跳过打开动作；`mcp` 独占 stdio，不与普通 stdout 日志混用。端口被占用时命令失败，不换端口、不结束未知进程。
+
+本地 GUI 的同源 HTTP 合同见 [本地 GUI 与 HTTP endpoints](local-gui.md)。
+
+## 长文与查询
+
+```text
+worldengine ingest <path> <scope-id> <source-id> <source-revision>
+worldengine ingest next <operation-id>
+worldengine ingest accept <operation-id> <request-id> <candidate-json-file>
+worldengine ingest commit <operation-id>
+worldengine ingest status <operation-id>
+worldengine ingest resume <operation-id>
+worldengine status <operation-id>
+worldengine resume <operation-id>
+worldengine ask <scope-id> <query>
+worldengine dump <document-id> <new-output-relative-dir>
+worldengine recall prepare [scope-id]
+worldengine recall <query> [limit]
+worldengine read <entity-id>
+```
+
+```powershell
+.\worldengine.cmd ingest docs\lore.md scenario-main lore-book rev-2026-09-07
+.\worldengine.cmd ingest next world_ingest_...
+.\worldengine.cmd ingest accept world_ingest_... request_... .worldengine\candidates\request.json
+.\worldengine.cmd ingest commit world_ingest_...
+.\worldengine.cmd ingest status world_ingest_...
+.\worldengine.cmd ingest resume world_ingest_...
+.\worldengine.cmd recall prepare scenario-main
+.\worldengine.cmd ask scenario-main '谁见证了北门盟约？'
+.\worldengine.cmd recall '北侧城门的守约人' 8
+.\worldengine.cmd read entity:...
+.\worldengine.cmd dump document:... review-export
+```
+
+source 可以是项目内路径，也可以是绝对外部 UTF-8 `.md/.markdown/.txt` regular file。外部路径由 Host 单一入口校验并逐字节复制到 `.worldengine/imported-sources/<content-hash>.<ext>`；stdout receipt 返回物理 `sourceStoragePath`，逻辑 `sourcePath` 固定为 `external-source/<path-hash>.<ext>`。原件不移动、不改写、不执行；content hash 只选择物理副本，不参与初始 source identity。CLI identity 必须非空、trim 后不变且 NFC；初次全新来源由 harness 根据 manifest 的 `local_scenario_id` 与稳定逻辑路径生成，只有既有 identity 冲突且 readback 无法消歧时才询问作者。
+
+首个 `ingest` 在 stdout 返回 `{ receipt, next }`；harness 自己处理 `next.request.structuredRequest.messages`，并按其 `jsonSchema` 生成输出。`accept` 只接受项目内不超过 8 MiB 的 candidate JSON 文件，并以 operation/request identity 校验后落 checkpoint；Host 不重新发送 raw bytes。ready 后 `commit`，`resume` 在 ready 时 commit、否则返回 next。旧 provider journal 没有 adapter 时明确失败，不静默迁移。只保存最终成书内容，不记录 harness 对话、推理草稿或废案。
+
+`dump` 只写尚不存在的项目内相对目录。向量准备与查询是独立本地阶段：用户要求查书时先说明必须登录产品，`recall prepare [scope-id]` 通过 `127.0.0.1:11450` 按账户余额计费；登录态就是产品授权，不索取 provider key。semantic/hybrid 与多跳查询只消费当前 source revision 对应的 prepared vector snapshot；缺失或 stale 时 fail closed，不能降级成 keyword 冒充 semantic。
+
+外部 harness 调用 `ask <scope-id> <query>` 得到的是 `candidates`、`graphPaths`、`pathOptions`、`evidence`、`integrity` 与 `retrievalTrace`，不是 `answerable`/成品答案/citations。harness 必须依据原文 evidence 和有向路径自行回答，并在证据不足时明确不可回答。
+
+## 冻结提审
+
+```text
+worldengine review prepare <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+worldengine review submit <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+worldengine review status <operation-key>
+```
+
+```powershell
+.\worldengine.cmd review prepare review-lore-001 --review-note '首轮作者提审'
+.\worldengine.cmd review submit review-lore-001
+.\worldengine.cmd review status review-lore-001
+```
+
+三步必须使用同一 operation key。`prepare` 运行当前合同声明的本地 source capture/compiler/View build/Rust-WASM/独立向量准备/冻结组装，远端写为 0；`submit` 对同一 frozen wire 只做一次 POST；不确定时先 `status`。需要向量时必须已登录 `127.0.0.1:11450` 且账户余额可用；三步都需要匹配 `project_id` 的 Node ProjectAuth transport。
+
+## 上传
+
+```text
+worldengine upload plan <operation-id> <expected-project-revision> <expires-at-ms> --targets-json <json>
+worldengine upload confirm --plan-json <frozen-plan-json> [--confirm-plan <digest>]
+worldengine upload operation <operation-id>
+worldengine upload reconcile <operation-id>
+worldengine upload retry <operation-id>
+worldengine upload undo <operation-id>
+worldengine upload bind-review-target <operation-id> [--target <client-target-key>]
+```
+
+`--targets-json` 形如 `{"targets":[...]}`。先把 `plan` stdout 原样保存为 frozen plan；非交互确认必须回传其 digest：
+
+```powershell
+$expiresAtMs = [DateTimeOffset]::UtcNow.AddMinutes(10).ToUnixTimeMilliseconds()
+.\worldengine.cmd upload plan upload-001 8 $expiresAtMs --targets-json '{"targets":[{"client_target_key":"primary","scenario_id":"s1","view_id":"v1","creates_scenario":false,"creates_view":false,"copy_on_bind":false}]}'
+.\worldengine.cmd upload confirm --plan-json '<上一步完整 JSON>' --confirm-plan '<plan_digest>'
+.\worldengine.cmd upload operation upload-001
+```
+
+交互 CLI 可以逐目标确认；裸 `--yes`/`--force` 被拒绝。失败重试沿用 operation ID；结果不确定先 `operation` 或 `reconcile`。`undo` 只执行该 operation 已定义的可恢复回滚。成功上传不等于 review、ready 或 publish。
+
+## 下载替换
+
+```text
+worldengine download plan <target-pair-id> --parts scenario|view|both
+worldengine download confirm --plan-json <frozen-plan-json> --confirm-plan <digest>
+worldengine download operation <operation-id>
+worldengine download reconcile <operation-id>
+worldengine download restore <operation-id>
+```
+
+```powershell
+.\worldengine.cmd download plan pair-001 --parts both
+.\worldengine.cmd download confirm --plan-json '<上一步完整 JSON>' --confirm-plan '<plan_digest>'
+```
+
+plan 冻结远端 identity、object digest、选择的 parts 与本地覆盖摘要；confirm 才替换。Host 使用 staging、preimage 与 readback fence；崩溃后按同 operation `reconcile`，需要回退时 `restore`。不要手工复制远端对象越过确认边界。

package/assets/docs/development/desktop-transfer-security.md

@@ -0,0 +1,46 @@
+# 登录、传输、提审、恢复与安全
+
+## GUI 与 project-bound transport
+
+本地 Node GUI 固定绑定命令启动时的 canonical project root。CLI/MCP 不读取网页登录 cookie，也不能自己构造认证 header。Node ProjectAuth transport 的短期 capability 必须绑定当前 `project_id`；从另一个项目复制 `.worldengine` 登录态会 fail closed。
+
+用户确认直接走当前 harness 对话，不调用内部 `ask_user`。预览优先使用 `tools/list` 标记 available 的 MCP `preview_inspect/interact`；当前独立 Chrome adapter 不需要额外环境桥接，`preview_inspect` 必须返回真实 image。能力不可用时按 CLI 文档启动预览并用真实 Browser/screenshot 工具检查；不得使用模拟回答、伪造截图或全局认证绕过。
+
+## 传输状态机
+
+上传和下载都必须经过 `plan → 明确 confirmation → operation → readback/reconcile`。plan 冻结目标、expiry、digest、parts 与覆盖影响；confirmation 绑定 exact plan digest。重试沿用原 operation ID。
+
+- 上传 snapshot 可以绑定已有 Scenario/View，也可以按 plan 新建或 copy-on-bind。
+- 下载只替换作者选中的 `scenario`、`view` 或 `both`，并在 staging 验证 package/dependency 与 object digest 后原子切换。
+- 上传完成只说明远端 transfer operation terminal；它不等于审核、ready 或 publish。
+- `bind-review-target` 只在 terminal source readback 可证明时写本地审核绑定。
+
+## 提审边界
+
+`review prepare` 只在本地形成冻结、加密、可恢复材料并完成正式 compiler、View build、Rust/WASM 和全量 embedding；它不写远端。`review submit` 对相同 operation key/frozen wire 单次 POST；`review status` 用于不确定结果与重启恢复。
+
+`prepared` 表示本地材料完成，`pending_review` 表示远端仍在审，`ready` 必须由远端同源审核、coverage 与质量封分读回证明。review 不包含 publish；当前工具面也没有 publish 命令。
+
+## 故障恢复表
+
+| 症状 | 正确恢复 |
+|---|---|
+| `E_STALE_PROJECT_REVISION` | 重读 revision 与目标，合并新意图，使用新的 operation identity 提交新 call |
+| `E_OPERATION_ID_CONFLICT` | 停止；原 ID 已绑定不同 canonical call，检查调用方 identity bug |
+| `E_OPERATION_UNCERTAIN` | 查询同 operation ledger/operation/reconcile/status；不要新建 ID |
+| `E_REVIEW_PREPARE_REQUIRED` | prepared vectors 缺失或 stale；运行 `review prepare <operation-key>`，不要让 search 隐式生成 embedding |
+| 长文进程中断 | `ingest status <id>` 后 `ingest resume <id>` |
+| upload/download 中断 | `operation` 或 `reconcile`；需要本地回退时使用定义好的 `undo/restore` |
+| review submit 结果未知 | `review status <operation-key>`，不重新 prepare/submit |
+| `E_PROJECT_BUSY` | 等当前 writer lease 释放，随后重读 revision |
+| `E_GUI_UNAVAILABLE` | 修复项目本地 `@world-engines/project-host` 的 `assets/gui` 与 CLI 安装并重新验证；不全局安装、不改用平台 EXE |
+
+## 安全底线
+
+- token/cookie 仅由 project-bound broker 保管；不写 localStorage/IndexedDB、文档、日志、receipt 或源码。
+- Agent Kit 不分发、读取或要求配置 DeepSeek/OpenRouter provider key。结构化抽取使用外部 harness 自己的模型；embedding 只通过已登录的本机 `127.0.0.1:11450` 服务按账户余额结算。
+- `env_vars` 只转发宿主已有值。需要代理时在启动 Host 前由作者配置 `NODE_USE_ENV_PROXY=1` 与适用 proxy 变量；Agent Kit 不改全局环境。
+- `scenario/source.wes` 不直接编辑；`.worldengine` ledger/projection/snapshot 不手改；View 不能访问它们。
+- 所有项目路径必须留在 canonical root；symlink/junction/reparse point 越界会被拒绝。
+- creator-view iframe 没有 `allow-same-origin`。只用 ChatPlay SDK；不要探测 top window、cookie 或宿主文件系统。
+- 不使用 mock、stub、关键词 fallback 或“进程还活着”冒充真实 readback/semantic/review 证明。