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

package/assets/skills/lossless-document-authoring/references/d4f-workflow.md

@@ -0,0 +1,155 @@
+# D4F 无损入库与证据回答
+
+## 入库前
+
+CLI source 可以是项目内路径或绝对外部 UTF-8 `.txt/.md/.markdown` regular file。外部原文直接交给 `ingest`：Host 校验后逐字节复制到 `.worldengine/imported-sources/<content-hash>.<ext>`，返回物理 `sourceStoragePath`，并以 `external-source/<path-hash>.<ext>` 作为稳定逻辑 `sourcePath`。content hash 只定位物理副本，初始 source identity 仍由 `local_scenario_id` 与逻辑路径推导。外部原件不改写、不执行；不能改写 BOM、换行、Unicode 或空白。PDF/Word 需明确区分原始二进制与用户确认的转换文本。
+
+如果用户仍在讨论版本或逐项确认事实，只维护候选映射，不启动 ingest。明确收到成稿、生成、应用或写入意图后才进入 request/accept/commit；每轮聊天都写入会把废案变成 authority，禁止这样做。
+
+初次导入全新来源时，从当前 manifest 读取 `local_scenario_id`，与规范化项目相对文件路径一起稳定推导 `scope-id`、`source-id` 与初始 `source-revision`；这些是内部 CLI identity，不要求作者选择。已有来源沿用 source document readback 的 identity；只有旧 identity 与当前文件冲突且无法从 readback 消歧时才询问。相同 bytes/revision 的恢复必须沿用原 operation；内容变化是新 revision，不能覆盖旧 checkpoint 冒充继续。
+
+结构化抽取与分段语义由外部 harness 使用其当前模型完成；Host 只提供原文窗口/schema、校验、checkpoint 与 commit。Agent Kit 不分发或要求配置 DeepSeek/OpenRouter provider key；agent/harness 不枚举环境、不读取 `.env`，也不自行调用 provider。
+
+## 整本 ingest 与恢复
+
+从项目根运行以下真实入口；path/query 必须作为独立 argv 传入，按当前 shell 正确引用，不能将用户文本拼接为可执行 shell 代码：
+
+```text
+.\worldengine.cmd --help
+.\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 recall prepare [scope-id]
+.\worldengine.cmd ask <scope-id> <query>
+.\worldengine.cmd dump <document-id> <output-relative-dir>
+.\worldengine.cmd review prepare <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+.\worldengine.cmd review submit <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+.\worldengine.cmd review status <operation-key>
+```
+
+一次传入完整文件即可，首个回执在 stdout 返回 `{ receipt, next }`。Host 保存原始 bytes 并准备 unit/window；外部 harness 使用 `next.request.structuredRequest.messages` 调用当前模型，以其 `jsonSchema` 约束项目内不超过 8 MiB 的 candidate JSON，再以相同 operation/request identity 调用 `accept`。Host 校验并保存 checkpoint，不重打 raw bytes。循环 `next`，ready 后 `commit` 最终成书的 source document、chunks、nodes 与 edges。讨论、推理草稿、中间对话与废案不写入作品。
+
+立即保存首个 stdout `{ receipt, next }` 的 `operationId`，它是 harness-v1 的崩溃恢复 identity。旧 adapter 可能仍输出 stderr JSONL 进度，但它只属于相应 legacy journal；不能拿旧 stderr 行替代新 stdout 合同，也不能混成一个 JSON。
+
+从 ingest/resume 最终回执核对 `rawByteSha256`、`rawByteLength`、`roundtripVerified` 与 `sourceCoverage`。分别报告 `status`、`graphStatus`、`processedWindows`、`pendingWindows`、`failedWindows` 与 `embeddingStatus`。新编辑态回执的 `embeddingStatus.status=pending` 是预期状态，不把它误报成导入失败或 review-ready。`status=staged` 表示原文与中间结果已暂存，本次图还未提交；进程退出成功也不表示全书完成。
+
+`ingest status` 返回 journal 的 `phase`、`completedSegmentIds`、`failedSegments` 与 `commitReceipt`，不是另一份 coverage 回执。提交后可从 `commitReceipt` 读取上述结果；未提交且没有完整回执时，不猜测 pending 总数或图完整性。
+
+失败后先查 status，再以同一个 `operationId` resume；ready 时 resume 直接 commit，否则返回下一条 request。原始文件已移除时，若 descriptor 已持久化且通过 Host 校验，仍可恢复。Host 跳过已落盘窗口并复用 checkpoint；旧 provider method 没有 adapter 时明确失败，绝不把 journal 静默迁移成 harness method。
+
+v3/v4 都把 validator diagnostics 与 repair policy 绑定到 method identity。partial 时只恢复坏窗口，并把上次拒绝原因、分段问题及诊断 fingerprint 交给下一次有限 repair；诊断连续不变仍不得同参无限重抽。达到 Host 的有界尝试上限后返回 non-retryable failure，保留每次诊断，完整窗口零重抽。具体次数、错误码与 checkpoint transition 由当前 Host 执行，不由 harness 复制或改写。
+
+`semantic-negation-v4` 对否定 edge 使用不带否定前缀的正向 canonical predicate，并以显式 negation qualifier 保存极性。原文 assertion 仍保留自然语言否定。检索路径、展示和冲突分析必须同时读回 predicate 与 qualifier；在对应 caller 尚未证明正确处理前，不能把否定边显示或裁决为正向事实，也不能仅按 `not_` 名称推断新数据极性。
+
+429/50x 只按临时过载重试，不修改 source、请求身份或模型来绕过。非重试错误、持续失败或 stale project revision 时报告脱敏错误、受影响 operation 与恢复条件；不要清空 journal、换 operation/revision 或无限循环。`graphStatus=partial` 仍是部分图，不能称完整；新 deferred operation 在部分窗口时保持 staged，不可提审。历史已提交 partial 图也不能靠新流程自动重抽；当前 CLI 没有重抽已提交窗口的参数，报告这一能力缺口，不能伪造 revision 绕过。
+
+提交完成、`roundtripVerified=true`、完整 source coverage、`graphStatus=complete` 且无 pending/failed，才可报告“编辑态导入完成”；这仍不证明所有模型抽取事实都正确，也不表示 review-ready。只有后续提审已对冻结 revision 的全部静态检索文本完成向量 identity 校验并完成同源审核，才可报告 review-ready。
+
+聊天式渐进编辑也留在无向量编辑态：通过 runtime 实际提供的 schema/read/apply/readback 修改中性作者源与 raw graph，不把原文改写成摘要，不为每次编辑触发 embedding。内容变化遵守当前 source identity/revision 与 CAS 回执，不能覆盖旧 authority 冒充同一 revision。
+
+## 提审、向量与同源质量封分
+
+提审是独立于编辑 head 的冻结步骤，不推进 source head，也不重新从最新草稿拼装数据。每次先以当前 `.\worldengine.cmd --help` 确认 `review prepare|submit|status` 仍由已安装版本公开。该 CLI 只在 `worldengine.project.json` 的 `project_id` 与桌面注入的短期 ProjectAuthBroker capability 匹配时访问远端；缺失、过期或错项目必须 fail closed。不要读取或复述 broker capability 环境值。
+
+需要向量的 prepare 必须先登录本机 `127.0.0.1:11450`，并按账户余额结算；它从 project-bound author-source 读取并解密 source-ready revision，核对远端 `local_project_wesp` 与本地 authority 相同，再运行当前合同声明的正式 compiler、View build、Rust/WASM 与独立本地向量准备。prepare 在本地保存随机密文恢复材料，远端写次数必须为 0。submit 复用完全相同的 wire；重启或结果不确定时先 readback，不能重新 capture、embedding、build 或随机加密。具体命令与 receipt 字段以当前 help/schema 为准。
+
+真实提审必须捕获一个不可变 source revision/artifact/digest，并消费 `127.0.0.1:11450` 已登录服务产生的独立本地向量。回执须能证明服务/profile、dimension、输入 text identity 和覆盖全部一致；缺失、陈旧或不一致向量不得进入 ready 产物。从已含向量的同一冻结产物初始化内存 Ladybug 或重建派生索引可以复用既有向量，不等于重新向量化。
+
+D4F 审核与质量判断只消费该同一冻结 artifact、coverage 和原文 authority。全部可理解业务字段都要有主覆盖，结构化引用绑定 record、JSON Pointer、chunk 与 source identity；来源包装、控制元数据和 overlap 不重复计权。不能以原文摘要、标签、节点名、24k 抽样或可变 ScenarioRecord 代替全文语义；局部分块通过不自动证明跨块全局一致性。缺少任何必需调用、coverage 或同源证据时保持未审核，不落最终结果。
+
+`structural_score` 是去除原文重复存储、base64、hash、向量、ID、空属性、悬空/重复边和控制包装后的结构基础分。`quality_factor`/既有 `llm_bias_factor` 是闭区间 `[0,1]`：`0` 是合法的低质量审核结果，`1` 也可表示没有严重质量问题；未知、资料不足、审核拒绝、调用失败或 provider 错误既不是 `0` 也不是 `1`。只有审核同一冻结版本成功后才封存 `static_system_score = round(structural_score × quality_factor, 2)`；失败不得用默认因子封分。编辑期估值、已审核静态分、`player_score`、`mixed_score` 与 `dynamic_score` 必须分开标注。
+
+prepare 只证明本地冻结成功，submit 的 `pending_review` 只证明远端已接收审核。只有远端 D4F 审核、coverage 与质量封分的实际 readback 才表示 ready；review 不等于 publish。发布只能消费通过上述门槛的不可变 digest，不能改写该次静态分或转而读取最新草稿。
+
+只依据本项目当前 source/WESP receipt、graph status、已安装版本公开的容量门及真实上传/提审 readback 判断状态。任何局部运输实验都不代表 production transport；在真实入口、身份绑定、容量门与回执落地前，不得把新的 chunk transport 写成已支持，也不得声称可上传、可提审、事实完整或质量通过。
+
+## 图与 provenance 验证
+
+抽样首段、中段、末段以及跨章节引用：
+
+- `world_get`（或 `.\worldengine.cmd read <entity-id>`）读回回执的 `documentId`，确认 `world_source_document` 的 `raw_base64` 解码 bytes 与输入 hash/长度一致；原文 authority 不依赖 embedding。
+- chunk 的 `index_text` 必须与原文 UTF-16 `[start_offset, end_offset)` 切片逐字相等，`content_sha256` 对应该文本 UTF-8 hash；不能把 UTF-16 offset 当字节 offset，也不能先去 BOM/归一化再核验。核对 node/edge metadata、evidence unit IDs 和来源 revision。
+- `world_search` 验证别名或同义召回；命中必须保留来源 identity，不以相似分数替代证据。
+- `world_traverse` 从确定起点按方向读取多跳链；核查事实链时使用工具输入 `semantic_only: true`，省略或为 `false` 时保留兼容的结构遍历。结构边由端点 kind 与结构属性共同识别，不能按谓词名把 `part_of`、`mentions` 一律剔除，它们也可能是真实语义关系。逐跳核对 edge 方向、两端 node、parents/aliases 与原文 evidence。
+
+不要绕过 exact-21 发送 Cypher、直接读取 projection，或把 graph partial 表述成 source 丢失。
+
+中文词法检索仅对派生 index 与 query 对称执行 OpenCC 繁转简、Intl 中文分词与词内 Han bigram（不跨词边界），并使用按 scope/profile 隔离的只读专名词表；当前实现未采用 jieba。这些处理不转换原文 bytes、hash、offset、evidence 或 embedding 输入；分词命中、简繁或字形碰撞只产生检索候选，不能据此合并实体身份或裁决事实真假。
+
+已知旧版词法 checkpoint 只有在从其 canonical entities 重建的完整旧 profile 逐字段验证一致后，才原子更新为新版派生词法 profile 并重建索引。此过程保持实体、关系、属性、provenance、既有向量及其 identity、batch 与 digest 不变，不新增 embedding 请求；未知版本或 hash/corpus 校验失败仍拒绝恢复，不清空 checkpoint 或绕过校验。词法索引重建成功不表示语义抽取缺口已修复，也不是端到端准确率通过。
+
+## D4F ask 验收
+
+用户要求查书时，先说明 semantic 检索要求产品登录，`recall prepare [scope-id]` 会按账户余额计费；登录态就是这次产品模型调用的授权，不再要求 provider key。prepare 当前 revision 后再 `ask`。Host 只做 scoped hybrid search、有界有向 traversal、原文 readback 与完整性校验；不要把未暴露的 depth/path-budget 当作 CLI flags。
+
+答案、证据验证、抽取、plan 和 route 都使用外部 harness 当前模型与其配置；Host 不替用户设置或切换全局模型。请求使用有界输出和尝试次数；超限或截断明确失败，不通过几何增加预算、追加调用或切换模型绕过。embedding 与这些模型调用分离，只走已登录的本机 `127.0.0.1:11450` 服务。
+
+已提交的 partial 图也可以 ask，但必须标明抽取范围不完整：只回答当前证据能证明的局部事实，不把结果推广成全书穷尽结论。尚未提交的新 revision 不可冒充已被 ask 消费，先核对回答引用的 source revision。
+
+读取 `candidates`、`graphPaths`、`pathOptions`、`evidence`、`integrity` 与 `retrievalTrace`。这些是候选证据，不含 `answerable`、成品 `answer` 或 `citations`。外部 harness 依据原文 evidence、否定/时间 qualifiers 与每跳方向自行回答；只相关但证据链不闭合时说明不可回答，不能从空候选猜原因或用常识补齐。引用时保留 evidence identity 与原文定位。
+
+先把 `pathOptions` 与 `graphPaths` 当候选导航，用 `evidence` 核对每一跳的主体、方向、对象、否定与时间限定，再由 harness 写答案。证据 bundle 的完整性校验只证明 readback 自洽，不会替 harness 判定答案是否真正回答问题；不要自行批准 bundle 之外的新路径。
+
+“不知道某事实”不能代替用户请求的那个事实；但用户问的是“是否已知/是否有记载”时，有原文支持的未知状态可以回答该元问题。导航路径只负责找证据，不强制成为最终 proof；同名不同物理 ID 不可拼接，原文足够的纯文本回答可以没有 `graphPaths`，但不得冒充已有图证明。
+
+直接调用 `world_traverse` 或从 `ask` 取得的 `graphPaths` 都仍是候选，须继续核查 proof；不能拿路径存在或首尾实体命中替代中间证据。检索候选、截断信息与最终回答证据要分开报告；这不表示抽取已语义穷尽，也不表示其他候选均已证实。显式内部 model adapter 的旧答案回执不是 npm 作者 CLI 的当前合同。
+
+审阅证据时仍逐跳读回 raw spans，确认主体、方向、对象和限定条件。跨句、跨段的间接指代若需要桥接，还须保留把指代对象连回具名实体的原文证据，不能省略这一步后宣称链已闭合。
+
+对不同书籍、文章与来源使用相同证据标准；引用涉及多篇文章时分别核对各自的来源 identity 与原文。不为特定书加入人物白名单或预置题目答案，也不改 source 或证据来凑验收分数。
+
+至少验证一次末段事实和一次需要两跳以上的有向问题。关闭并重新打开 Host 后重问，证据链与 provenance 仍应成立。没有完成真实全书运行时，只报告候选或局部验证，不声称 D4F 全书通过。
+
+## Plain-text 审阅与守恒统计
+
+从已提交回执或 source document readback 取得 `documentId`，运行 `.\worldengine.cmd dump <document-id> <output-relative-dir>`。Host 从一次已提交 WESP authority readback 枚举该文档同 source/revision 的 logical graph，导出原文、当前已提交图与统计供人或 LLM 审阅。不要把 staging operation ID 当作 document ID，也不要从 semantic search 的有限命中自行拼成全量图。导出范围是当前已提交的该文档图，不是整个项目所有来源；`graphStatus=partial` 时仍明确是部分图，`complete` 也不表示模型抽取已语义穷尽。跨来源端点只保留名称/引用；若该边由本书 `source_chunk_ids` 支持，仍导出本书断言与校验后的本书证据。未归属于本书的外部边只列端点/谓词，不导出其他来源正文。
+
+输出路径是项目相对的新目录，不接受绝对路径、`..`、ADS 或 junction；目录已存在时即使为空也拒绝覆盖。选用明确的新目录，不自动删除旧 dump。四个文件逐个发布，`manifest.json` 最后发布作为完成标记；中断留下的部分目录不是完整结果，应保留并用另一个新目录重试。
+
+| 文件 | 用途 |
+| --- | --- |
+| `source.txt` | source authority 的原始 UTF-8 bytes，供 byte/hash 守恒核对。 |
+| `graph.txt` | 实体、别名、自然语言断言、全部相关有向边及验证后的原文证据；结构边与语义边分别标注。 |
+| `review.txt` | 完整原文、图与机械验证清单组成的审阅材料，含额外包装文字，不用于原始 bytes hash 比对。 |
+| `manifest.json` | 来源、WESP hash、计数、覆盖与警告；不是模型审阅结论。 |
+
+stdout 只返回摘要、项目相对文件路径、每个文件的 `byteLength`/`sha256`、`integrity`、source 统计与总节点/边/chunk 数，不返回正文。读取 manifest 的 `integrity.status` 与 `warnings`；`incomplete` 可以伴随已成功生成的四文件，不能因退出成功就声称完整。`verified` 只表示机械检查通过，不等于语义审阅通过。
+
+`source.integrityStatus=verified` 独立证明原文字节完整；`projection.status=verified` 表示同 WESP hash/revision 下真实 native Ladybug 的本书实体、关联边及非向量属性与 authority 一致。`projection` 的 `counts`、`missing`、`extra`、`mismatch` 用于定位投影差异；`not_checked` 不是通过，缺少真实投影能力会使总体 `integrity.status=incomplete`。raw 100% 与 projection verified 都不能覆盖 manifest 的 `extraction.graphStatus=partial`，后者仍不得宣称抽取完整。
+
+直接读取 manifest 的 `extraction`，无需另找 ingest 回执：`graphStatus` 为 `partial`、`complete` 或 `not_recorded`；`processedWindows` 为已处理窗口数或 `null`；`authorityMarkerId` 为绑定的 marker ID 或 `null`。这些字段来自同一已提交 WESP 中严格匹配 document、来源、revision 与原文 hash 的 source control marker，不读取 staging；identity 冲突会拒绝导出。`not_recorded` 只表示缺少可用记录，不可猜为 complete；`complete` 也仅表示已提交抽取校验状态，不等于语义穷尽或审阅通过。
+
+需要复核详细计数时读取 manifest，不把 CLI 摘要的总 `counts.nodes` 当语义实体数：
+
+- `source` 分别记录 `byteLength`、`sha256`、`utf16Length`、`unicodeCodePoints`、`hanCharacters`。
+- `chunks` 提供 `count`、`reconstructedSha256`、`coverageRatio`、`gaps`、`overlaps`、`invalidCount`；coverage 只累计通过内容与 hash 验证的原文区间并集。
+- `graph` 区分 `semanticEntityCount`、`semanticEdgeCount`、`structuralEdgeCount`、`unknownEdgeCount`、`statementAssertionCount`、`edgeAssertionCount` 与 `uniqueAssertionCount`。实体/边数按已存记录计数，不声称已经做同义实体或关系的语义去重；`uniqueAssertionCount` 按主体、目标、谓词、断言、值、限定内容去重。
+- `graph.assertionBodyUtf16Length` 仅累计精确去重后的自然语言 assertion 字符串 UTF-16 长度，不计 ID、值、限定、引用、结构文本或向量；它与独立断言数量不是同一个统计口径。
+- `evidence.uniqueSpanCount` 是不同原文片段区间数；`coveredUtf16Length`/`coverageRatio` 按通过逐字校验的 `evidence.spans` 区间并集计算，重复引用不增加覆盖；同时检查 `invalidCount`。多片段的首尾包络只作定位，不能把中间间隔计入覆盖；旧数据无 spans 时，仅连续 quote 与原文区间逐字匹配才通过。
+
+`unknownEdgeCount` 与 `relation_role_unknown` 警告表示现有端点/属性不足以判定关系角色，不是边已丢失，也不能把它算作已证实的语义边。dump 仍保留这些边并单独标注；结构、语义与 unknown 三类共同覆盖总边数。先读回该边的端点与属性解释警告，不按同名谓词强行归类或把警告隐藏成通过。
+
+审阅时把三层证据分开：
+
+- 原始 bytes：导出的原文必须与 source authority 的 bytes、长度和 hash 完全一致，包括 BOM、CRLF 与 Unicode；这是 100% 硬守恒要求，不是模型质量分数。
+- Chunk 覆盖：检查原文区间覆盖、空隙、重叠以及各 chunk 的内容/hash/offset 一致性。原文保存在 source document 中，不会自动证明 chunks 已覆盖全文。
+- 语义抽取：分别看独立实体、有向边、自然语言断言的数量与文字量，再看证据区间合并去重后的覆盖。重复引用、ID、结构标签、原文重贴与包装文字不能计作理解量；多条断言引用同一区间不能累计成超过原文长度的覆盖。
+
+计数按 manifest 的实际坐标与去重口径解读，区分 bytes、UTF-16 code units 与 Unicode code points，不能统称为“字”后相除。只在同一 source/revision 的坐标域内合并 evidence，不把跨版本引用或重叠 chunk 重复累计。
+
+语义文字比原文短不直接证明原文字节丢失；原文字节可完整复现，也不代表实体关系与事实已穷尽。语义文字比原文长同样不证明理解更多；即使证据覆盖达到全文，也仍须逐项审阅事实、方向、限定条件和遗漏。证据覆盖不足 100% 也不能单独判定失败，需结合预期事实；布局与不含所需事实的文字未必应形成语义断言。
+
+dump 只是机械导出与守恒检查，不会额外请求模型、不需要 provider 凭据，也不新增 MCP 工具。将审阅材料交给当前 LLM 不代表它已完整阅读或审核：报告实际读过的范围和 findings，未覆盖部分保持未审阅；不能自动调用额外付费模型或把文件生成成功表述成 audit 通过。
+
+## GUI 与 Trigger 证据
+
+作者 GUI 修改 TMW3 的时间、自然语言条件或 AND/OR/NOT 时，必须经当前真实工具、CAS 与已提交投影 readback 形成证据；数据库/trigger CRUD 的成功返回还要继续核对读回值。界面通知、preview URL、候选预筛、旧内存数组或失联的 TriggerProgramV1 都不能证明保存成功。
+
+条件预筛不是真假裁决。自然语言条件的 Judge 必须消费具体文本与有界图证据；低置信度、provider 失败或证据不足不能持久化假 latch，也不能借 NOT 反转成真。Browser Creator 与 Desktop Tauri 各自需要实际 readback/交互证据，不能互相替代。
+
+生产 TMW runtime 当前只产出 `logical_seq` 与 `world_time`；引用 `presentation_seq` 或 `real_time` 的文档在 production compile 必须拒绝。simulation 可选择四个时钟域是测试输入能力，不表示生产 runtime 已提供 presentation 或 real-time authority。
+
+Desktop 本地结构评分可用于草稿反馈，但没有正式审核回执时 quality factor 与审核分保持 `null`，不能用 0、1 或旧值代填。平台 tag 对比只由已认证且已绑定当前 scenario 的正式 caller 获取；未绑定、认证缺失或请求失败时保持不可用，不回退到猜测 tag 或默认基准。

package/assets/skills/platform-conversion/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: platform-conversion
+description: 将已有代码、网页、工程、游戏原型或剧本文本转换为 WorldEngine 可用的 Scenario、ChatPlay View 或两者。用户说“把已有剧本/代码转换为平台支持”，或要求导入、移植、适配、转换现有素材时必须使用；从零创作、只解释或只审阅时不使用。
+license: LicenseRef-WorldEngine-Project
+---
+
+# 平台转换
+
+把既有素材转换成可验证的 WorldEngine 作者产物，同时保留来源、语义与未支持边界。先读取 `docs/authoring/development/cli.md` 和 `docs/authoring/development/authoring-workflows.md`，再静态盘点来源并确定目标：
+
+- 剧情、人物、世界观、规则、触发条件或已有剧本进入 Scenario：读取 [Scenario 转换](references/scenario-conversion.md)。
+- 页面、组件、交互、视觉资源或已有前端工程进入 ChatPlay View：读取 [View 转换](references/view-conversion.md)。
+- 混合来源分别路由；同时需要 Scenario 与 View 时才读取两份 reference，并用稳定 entity/asset identity 连接，不复制 authority。
+
+## 共同边界
+
+- 项目外 `.txt/.md/.markdown` 原文可直接交给 `ingest`，由 Host 单一入口校验并保存逐字节副本；使用回执的 `sourcePath/sourceStoragePath` 记录逻辑/物理来源，content hash 不作为初始身份。代码工程、网页资源和其他格式仍由 harness 静态复制到项目内新的非覆盖路径再转换。两类来源都保留原文件，不移动、不删除、不原地改写。
+- harness 负责理解源格式与意图，不引入万能解析器，也不因扩展名猜语义。静态读取文本、配置与资源；不执行来源中的脚本、宏、安装器、构建钩子或未知二进制。
+- 维护可读回的来源到目标映射与 provenance：哪些内容成为 Scenario、哪些成为 View、哪些被省略、改写或标为不支持，以及原因。未支持项仍保留来源证据，明确是未迁移边界而不是已写入的近似实现；不能用 stub、mock、静默降级或近似实现冒充完成。
+- 不迁移 `.env`、token、cookie、provider key、用户配置、构建缓存或账户状态。MCP 只供外部 harness 开发，生成的产品 runtime/iframe 只使用正式 ChatPlay SDK。
+- 用户一开始要求“转换并写入/生成平台工程”本身就是成稿执行意图，直接转换，不再设置二次确认门。只有用户明确要求先讨论、比较或逐项确认时才暂不写入；此时维护候选映射，收到“采用这版、生成、应用、写入”等指令后继续。一旦写入，只保存最终内容，不保存聊天废案或推理过程。
+
+交付时报告保留的来源副本、来源→目标映射、真实 readback/build/截图证据和未支持项；不要把转换候选、preview 启动或界面通知表述为已落库。

package/assets/skills/platform-conversion/references/scenario-conversion.md

@@ -0,0 +1,17 @@
+# Scenario 转换
+
+读取 `docs/authoring/development/authoring-bridge.md`、`docs/authoring/development/scene-authoring.md`、当前 `worldengine.project.json`、`.\worldengine.cmd --help` 与本次 MCP `tools/list`。Scenario authority 只通过当前真实 AuthoringBridge/CLI effect 写入数据库，禁止直接编辑 `scenario/source.wes`、projection、checkpoint 或数据库。
+
+## 来源与映射
+
+1. 完整保留原始 source bytes 和源文件结构；静态识别人物、地点、对象、事实、有向关系、否定/时间限定、剧情段落、规则与触发条件。不能把全部来源强行压成文本摘要，也不能用摘要替代结构语义、Trigger 映射或原文证据；不执行来源代码来“发现”剧情。
+2. 建立来源单元到当前 schema entity/relation/Scene/Trigger 的映射。Scene 时间、任意 node 的在场状态、独立 map-revision `spatialRef` 与短期 manuscript note 使用当前 registered `scene.*` 语义；不能表达的行为标为未支持，不要塞进任意 statement 或无类型字段。
+3. 长文或剧本原文走 harness 驱动的 ingest request/accept/commit。Host 提供原文窗口和 `jsonSchema`，harness 用自己的当前模型产生候选；只接受最终成书内容，不把转换讨论写入候选。提交后以读回的数据库 `world_source_document` 验证原始 bytes/hash/长度无损，并验证抽取 entity/relation/Scene/Trigger 的 provenance 可追溯到稳定 source identity/revision 与原文证据。
+
+## 写入
+
+用户已请求“转换并写入/生成”时直接执行；只有明确要求先讨论或逐项比较时才等其选定版本。写入前读当前 revision 与相关实体，再依次执行 schema/read、candidate validation、稳定 operation identity 的 apply、receipt 与数据库 readback；apply receipt 本身不等于已落库。Trigger 必须继续执行 schema/read → validate → apply → readback → simulate；只引用已读回 entity 或 stable `spatial_ref`。
+
+若来源已经包含稳定身份，保留并映射它；若与项目既有身份冲突，先读 reverse impact，再请用户只裁决无法由证据消歧的冲突。不能表达的来源行为逐项保持 provenance 并报告为未支持，不得把它们写成无类型事实、占位内容或“已迁移”。来源 bytes 完整、数据库 source_document/readback、抽取及 provenance 完整、Trigger 生效和审核 ready 是不同结论，分别报告。
+
+旧 `next-system-prompt` 或等价下一轮写作指令映射为 `scene.note.add`：逐字保留 writer manuscript data，按原语义选择 `once` 或 `scene_end`。它不是 system prompt，也不能永久化为 entity attribute/world fact。不要因作者工具或模拟可用就声称旧 SAV 迁移或 production writer 已部署。

package/assets/skills/platform-conversion/references/view-conversion.md

@@ -0,0 +1,19 @@
+# View 转换
+
+读取 `docs/authoring/development/chatplay-view.md` 与当前生成的 ChatPlay SDK descriptor。目标是现有 Local Author Project 的 `view/` React + TypeScript 工程；沿用其 Vite、构建和样式结构，不另造 runtime 或第二套框架。
+
+## 静态转换
+
+1. 静态盘点入口、组件、状态、样式、字体、图片、音视频与交互。不要运行来源工程的 dev server、安装脚本、宏、postinstall 或未知构建插件；不要复制 `node_modules`、`dist`、缓存、凭据与用户配置。
+2. 把可迁移 UI 适配到现有 React/TypeScript 组件与正式 ChatPlay SDK。来源若是 Vue、原生 HTML、游戏引擎或其他框架，由 harness 理解其行为后重写目标组件；不要嵌套运行原工程或构造万能兼容层。
+3. 数据和宿主交互只使用 descriptor 已公开的 ChatPlay SDK。禁止访问 top window、cookie、项目文件系统或 AuthoringBridge；禁止把 MCP client/server 打包进 View runtime 或 iframe。
+
+成品必须能在生产 sandboxed iframe 中只凭宿主注入的正式 ChatPlay SDK 运行；iframe 内把 MCP 视为未知且不可用，不能探测、调用或依赖 harness 的 MCP 生命周期。开发时使用 MCP 只是在 iframe 外驱动预览和截图，不得形成产物依赖。
+
+## 验证与差异
+
+用户已要求转换并生成时直接修改 `view/`；仅明确讨论时等待成稿选择。通过 portable runtime 运行 `.\worldengine.cmd npm run typecheck`、`.\worldengine.cmd npm run build` 与项目提供的 View smoke。预览优先使用 `tools/list` available 的 MCP `preview_inspect/interact` 独立 Chrome adapter，并消费 inspect 返回的真实 image；不可用时运行 `.\worldengine.cmd npm run dev` 并使用 harness 的真实 Browser/screenshot 工具。DOM、日志、占位图或 preview URL 不能代替截图证据。
+
+截图修改使用多模态闭环：先取得当前真实截图 image，将其与来源截图/视觉目标逐项比较，记录可见偏差及对应组件/样式；只修改目标 `view/` 文件，重新 typecheck/build/smoke，再取得新截图验证偏差确已消失。每轮都以最新真实像素为输入，不能凭文字描述猜测完成，也不能把来源截图直接当成成品截图。
+
+对无法等价迁移的浏览器权限、服务端能力、原生插件、动态执行或专有资源逐项报告。未经授权或缺少正式 SDK 能力时保持未实现，不注入 shim、mock 或 MCP runtime 冒充支持。

package/assets/skills/setup-matt-pocock-skills/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/assets/skills/setup-matt-pocock-skills/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: setup-matt-pocock-skills
+description: Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
+disable-model-invocation: true
+license: MIT
+---
+
+# Setup Matt Pocock's Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+
+Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+**Section B — Triage label vocabulary.**
+
+> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
+
+**Section C — Domain docs.**
+
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+
+Confirm the layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/assets/skills/setup-matt-pocock-skills/SOURCE.md

@@ -0,0 +1,11 @@
+# Matt Pocock 工程技能套件来源说明
+
+- 上游仓库：<https://github.com/mattpocock/skills>
+- 上游目录：`skills/engineering/`
+- 许可权威：仓库根 MIT License。
+- 核验基准：2026-09-07 核验上游 `main` commit `3cca18b368ae95cdbdebbff572ccafa662551015`。
+- 随包保留的唯一许可全文：[LICENSE.md](LICENSE.md)
+
+Agent Kit 携带 `setup-matt-pocock-skills`、`diagnose`、`tdd`、`to-issues`、`to-prd`、`triage`、`zoom-out` 与 `improve-codebase-architecture` 的本地适配快照。原有 invocation policy 与技能行为保持不变；本地改动只适配仓库合同文字，并移除指向未随包携带的上游 sibling skill 文件的路径。这些文件不声称与当前上游逐字相同。
+
+本文只记录现有套件的来源与许可，不创建新技能，也不声称获得上游背书。

package/assets/skills/setup-matt-pocock-skills/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/assets/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/assets/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -0,0 +1,23 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.

package/assets/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -0,0 +1,19 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.

package/assets/skills/setup-matt-pocock-skills/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.