快速开始：制作一个 Creator Source Package v1

本流程适用于已经获得项目 source access、会与 Meet-U 工程团队共同维护 package 的技术合作方。大多数 IP owner 可以先完成非技术 Pilot worksheet，再按照协作流程由团队协助结构化。

技术流程从一张人类创作 worksheet 开始，依次完成七个 YAML 文件，最后用当前 compiler 生成并复核本地 owner-preview bundle。它不会把已有 package 当成模板盲目替换名字，也不会把成功编译误写成 Creator approval。

精确字段类型和所有允许值请随时对照完整字段清单。创作含义与跨文件关系见语义创作指南。

0. 准备环境

从仓库根目录工作。当前项目要求 Python 3.11+ 和 uv；完整本地应用还要求 Node.js 20.19+ 与 Docker。先运行仓库 setup：

bash

npm run setup

只编译 package 不需要启动 PostgreSQL 或开发服务器。下面所有命令都假设当前目录是仓库根目录。

1. 先写一页创作 worksheet

不要从 YAML 字段开始设计故事。先由 Creator 明确以下内容：

角色核心：她是谁、想要什么、害怕什么、有什么不可逾越的边界？
关系前提：为什么她会与 world 之外的用户交流？用户可以影响什么，不能做什么？
眼前 dilemma：现在发生了什么，为什么必须由她作出决定？
决定空间：列出 2–4 个都忠于角色、但价值取向和代价不同的选择。不要把它们写成用户按钮。
世界结果：每个角色决定会确定地产生什么 outcome？哪些 fact 是公开的，哪些是 private 的？
回来告诉用户：角色观察到什么，为什么联系用户，可以说什么、必须保留什么？
验收反例：用户支持、施压、质疑、拒绝或声称自己在 world 中行动时，什么反应才忠于角色？

如果这张 worksheet 还不能回答“为什么这个选择只能由角色作出”，先解决创作问题，不要让 compiler 或模型替 Creator 决定。

在创作新 package 前，可以先用完全合成的英文 compiler canary 验证本机路径。它只验证通用 compiler，不代表新 package 已经安装到 owner preview：

bash

uv run --project apps/api meet-u-compile-pilot \
  --content-root apps/api/tests/fixtures \
  --output-root /tmp/meet-u-orbital-bundles \
  --package-id orbital-garden-relay \
  --version 1

uv run --project apps/api meet-u-compile-pilot \
  --content-root apps/api/tests/fixtures \
  --output-root /tmp/meet-u-orbital-bundles \
  --package-id orbital-garden-relay \
  --version 1 \
  --check

第一条普通 compile 必须先成功并保留 output，第二条 --check 才有可比对的已有 artifact。canary 本身是 synthetic test material，不是生产内容、Creator approval 或权利声明。

2. 选择默认语言

当前可编译的 package.default_locale 只有：

中文：zh-CN
英文：en-US

一个 package version 只能选一个默认 locale。本教程假设使用 zh-CN；英文 package 把默认 locale 及所有 recovery surface 的 locale 一起改为 en-US，并由 Creator 提供英文 opening、voice、follow-up、Journal 和 alt text。

不要把两套完整文案随意混在同一份字段中。no_eligible_guidance.public_projection.text 可以同时放 zh-CN 与 en-US，但当前 v1 没有为其余全部创作字段提供 locale map。详细限制见当前能力与限制。

3. 建立目录和七文件闭包

选择一个小写、以连字符分隔的 package ID，例如 my-pilot，再建立：

text

content/creator-sources/my-pilot/v1/
├── source-package.yaml
├── character.yaml
├── relationship.yaml
├── arc.yaml
├── dialogue.yaml
├── visual.yaml
├── acceptance.yaml
└── assets/
    ├── portrait.png
    └── outcomes/
        ├── outcome-a.png
        └── outcome-b.png

package.id 必须等于目录中的 my-pilot，package.version: 1 必须等于目录中的 v1。目录、source module 和 asset 都不能是 symlink。

当前没有 scaffold 命令。不要复制复杂的现有 package 后只做字符串替换：承诺、deferred expiry 和多条 outcome 会留下难以发现的旧 ID，得到语义错误的 package。参考任何进阶实例时，每个字段都应回到自己的 Creator worksheet。

4. 填写 `source-package.yaml`

manifest 固定声明六个 module 文件，并绑定主角色与 arc：

yaml

schema_version: meet_u.creator_source_package.v1

package:
  id: my-pilot
  version: 1
  display_name: 我的 Pilot
  ip_title: My Original IP
  default_locale: zh-CN
  primary_character_id: my_character
  arc_id: first_dilemma

modules:
  character: character.yaml
  relationship: relationship.yaml
  arc: arc.yaml
  dialogue: dialogue.yaml
  visual: visual.yaml
  acceptance: acceptance.yaml

provenance:
  - role: semantic_normalization_authority
    ref: REPLACE-WITH-A-STABLE-REVIEWED-AUTHORITY-REF

semantic_parity:
  preserves:
    - REPLACE：从 Creator source 或已接受决定中保留的具体意义
  excludes:
    - REPLACE：明确不属于 Creator source 的运行机制或旧行为

示例中的 REPLACE 不是可提交内容。provenance 必须真实描述来源；当前 role vocabulary 很窄，如果新 IP 的来源无法诚实映射到允许值，不要伪造引用来通过编译，应先提出 contract gap。允许值与限制见当前能力与限制。

semantic_parity.preserves 与 semantic_parity.excludes 都必须非空。它们说明这次 normalization 保留和排除了什么，不是 marketing summary。

5. 按依赖顺序填写六个 module

推荐顺序不是 manifest 的字母顺序，而是从创作 authority 到引用闭包逐步展开。

5.1 `character.yaml`：角色自身

先写：

public_identity 和 values
self_concept、core_contradiction、identity_threats
长期/当前/隐藏目标
boundaries 与 prohibited_portrayals
decision_tendencies 和 constructive refusal
knowledge、disclosure、voice

角色 ID 必须等于 manifest 的 primary_character_id。hidden_motives_disclosed_by_default 的唯一允许值是 false。

constructive_refusal.style_anchor 用来校准真正的拒绝。终止 CHAT_ONLY 文案单独写在 dialogue.recovery 里，避免普通生成失败被误说成对用户的判断。

5.2 `relationship.yaml`：用户如何影响她

定义 remote channel 和 influence_vocabulary。当前 channel 的五个 authority boolean 都固定为 false：

yaml

user_has_physical_presence: false
npc_may_receive_user_messages: false
npc_may_contact_user: false
npc_may_verify_user_or_messages: false
character_may_forward_raw_messages: false

influence kind 是对用户表达的语义解释，例如 support、skepticism、pressure；它不是关键词列表。不要加入 quoted phrase、regex、substring 或“这句话直接选择某个决定”的 route。

invented_shared_context、reciprocal_promise 和 durable_episode_meanings 按故事需要填写。前两项可以省略；durable_episode_meanings 字段本身仍需存在，可以是空 list。使用承诺时，user 与 character 必须各有 promise；角色 promise 的 followup_motive 必须出现在每个 arc follow-up 中。

5.3 `arc.yaml`：决定、事实和结果

先给所有概念分配稳定 ID，再按以下顺序写：

narrative_time 和 world.facts/locations/npcs/deadline
progression.initial_character_beliefs
decisions
每个 decision 对应的 outcomes
每个 outcome 对应的一个回访 followups entry
conversation_availability 与 progression.decision_phase；若要把某个分支的后果拆成多拍回访，再写可选的 progression.aftermath，为每个普通拍增加一个专属 follow-up；携带 decision_phase 的决策拍不写 world_event/followup_id，也不占用专属 follow-up

虽然 source schema 把 progression 标为 optional，当前 local_owner_synthetic_preview target 要求它存在，并要求 world.deadline、一个 terminal horizon 和 no-eligible public guidance。

每条 decision 必须包含角色自己的 action，并且恰好指向一个 outcome。每个 outcome 必须反向指向该 decision；每个 outcome 恰好有一个 outcome 回访 follow-up，只有 progression.aftermath 的普通拍可以为同一 outcome 再各占用一个专属 follow-up（决策拍的回访经由所选 outcome 的回访 follow-up）。分支 decision_phase 与各决策拍的 candidate 集合互斥，并集恰好覆盖全部 decision 一次。不要把 user observation 写成 outcome cause。

5.4 `dialogue.yaml`：如何呈现已获授权的意义

opening 是 creator_exact，会使用 Creator 提供的精确文本。ordinary 是 guided_generation：写必须传达的语义与禁止披露的 fact，不要写一组触发句。

对默认中文 locale，recovery 必须在全部 chat_only surface 中把三种 immediate applicability 各覆盖一次，不能遗漏或重复：

yaml

recovery:
  degraded_chat:
    id: degraded_ordinary_reply
    locale: zh-CN
    mode: guided_generation
    reuse_ordinary_dialogue_meaning: true
  chat_only:
    - id: terminal_no_effect_reply
      locale: zh-CN
      mode: creator_exact
      exact_text: 我刚才没接住。你换个说法，我再答。
      applicability:
        - availability_class: immediate
          recovery_obligation_types:
            - ordinary_no_effect
    - id: terminal_capability_boundary_reply
      locale: zh-CN
      mode: creator_exact
      exact_text: 你可以告诉我你的想法，但不能替我行动或替我决定。
      applicability:
        - availability_class: immediate
          recovery_obligation_types:
            - capability_boundary
        - availability_class: immediate
          recovery_obligation_types:
            - ordinary_no_effect
            - capability_boundary

dialogue.followups[].followup_id 必须与 arc.followups[].id 完全一致：每个 arc follow-up ID 恰好有一个 dialogue entry。每个 semantic-lock follow-up 至少有一条 unconditional must_convey。若 arc 定义了 deferred_followup，dialogue 必须同时定义 ID 对应的 deferred_expiry，反之亦然。

Journal 必须恰好覆盖：

relationship.influence_vocabulary 中的每个 influence；
arc.decisions 中的每个 decision；
arc.outcomes 中的每个 outcome。

5.5 `visual.yaml`：描述意图并引用已有素材

提供角色视觉 identity、portrait、可选的公开 discovery presentation，以及每个 outcome 至多一张、可以省略的 depiction。为了兼容旧 package，visual.discovery 在 schema 中仍为 optional；但 package 要进入动态角色画廊就必须提供它。每个 asset ID 必须唯一；一个 outcome 至多一张 visual，被描绘的 outcome 必须存在，没有 visual 的 outcome（例如决策拍的纯文本 outcome）也合法。

package-local asset 使用：

yaml

source_path: assets/portrait.png

历史 approved namespace 只允许引用同一 package/version 下：

yaml

source_path: pilots/my-pilot/v1/assets/portrait.png

visible_fact_ids 只能引用对应 outcome 中 externally_visible: true 的 committed fact。forbidden_fact_ids 应显式保护 private、未知或不应画出的 fact。provenance_ref 记录来源，但不会批准素材。

portrait 与 outcome asset 可以使用 .avif、.gif、.jpeg、.jpg、.png、 .svg 或 .webp；discovery cover 必须是静态 raster，只允许 .avif、.jpeg、 .jpg、.png 或 .webp。公开封面的 3:4 裁切、焦点、hook、alt text 与 fact boundary 见画廊封面指南。

5.6 `acceptance.yaml`：保存创作者期望

至少写出最可能暴露角色失真的语义位置，例如：

合理支持；
强迫或越界；
用户声称自己在 world 中行动；
用户提出 false fact；
用户拒绝帮助但没有抛弃关系；
同一含义的不同措辞。

semantic_position 和 shared_meaning 描述意义，不存 quoted trigger。allowed_decision_ids 是允许范围，不保证运行时已经执行或通过这些案例。acceptance source 是 Creator review/evaluation input，不是 test receipt 或 qualification。

6. 在编译前做一次人工闭包检查

先快速确认：

manifest、character、relationship、arc 的三个主 ID 一致；
每个 influence、belief、deadline、fact、NPC、decision、outcome、follow-up 和 asset 引用都能找到定义；
decision ↔ outcome 是一对一；每个 outcome 至少一个 arc follow-up，每个 follow-up ID 恰好一个 dialogue entry；
progression 的各 decision phase（分支 phase 加所有决策拍）互斥地恰好覆盖所有 decision 一次；
dialogue 覆盖所有 follow-up；visual 只描绘已定义 outcome，每个 outcome 至多一张；
Journal 精确覆盖所有 influence/decision/outcome；
reveal 的 fact 已由角色观察，画出的 fact 是 externally visible；
default locale、recovery locale 与 no-eligible 文案一致；
所有 asset 文件真实存在且不是 symlink。

完整规则见语义创作指南中的跨文件不变量。

7. 编译 package

从仓库根目录运行：

bash

uv run --project apps/api meet-u-compile-pilot \
  --content-root content \
  --output-root /tmp/meet-u-bundles \
  --package-id my-pilot \
  --version 1

把 my-pilot 和 1 换成 manifest/path 中的真实值。不要传任意 --source-ref；CLI 会根据 package/version 生成 canonical repository ref，非 canonical 值会被拒绝。

成功后，CLI 打印一行 JSON。确认：

status 是 succeeded；
runtime_bundle_content_ref 指向 /tmp/meet-u-bundles/sha256-<digest>/runtime-bundle-content.json；
canonical_ir_ref 指向同一目录内的 canonical-authoring-ir.json；
activatable 是 false，这是正确的权限边界，不是错误。

不要把临时 output 写进 content/creator-sources/。输出是 compiler artifact，不是 Creator source。

8. 用 `--check` 复核相同输出

第一次 compile 成功且 output 仍在原路径后，运行完全相同的命令并加 --check：

bash

uv run --project apps/api meet-u-compile-pilot \
  --content-root content \
  --output-root /tmp/meet-u-bundles \
  --package-id my-pilot \
  --version 1 \
  --check

--check 会在临时目录 fresh compile，然后比较原 output 的目录集合、文件集合与 SHA-256。它不会修改 Creator source，也不会赋予 approval 或 activation。

9. 常见错误怎么处理

错误片段	通常原因	修复方向
`package identity does not match Creator source path`	`package.id/version` 与目录不同	同时检查 `<package-id>/v<version>` 与 manifest
`violates the semantic Creator source contract`	字段缺失、类型错误、未知字段或 literal 不符	看错误 path，并对照完整字段清单
`duplicate YAML key`	同一 mapping 重复键	删除重复键；不要依赖“后者覆盖前者”
`forbidden Creator source field`	把 provider、approval、runtime 或 raw-text route 塞进 source	移到正确 authority 层，或删除未经支持的机制
`platform presentation catalog has no entry for locale`	`default_locale` 不是 `zh-CN`/`en-US`	使用当前支持的 locale，或另行扩展 platform policy
`requires Arc Progression V1`	当前 target 缺少 `arc.progression`	添加完整 progression、deadline 与 no-eligible guidance
`decision/outcome references are not closed`	decision/outcome ID 漏配或错配	恢复一对一双向引用
`dialogue follow-up meanings do not match arc follow-ups`	dialogue 少、漏、重复或多了 follow-up	让 ID 集合与 `arc.followups` 精确相等
`Creator Journal copy must cover every influence, decision, and outcome`	Journal statement 缺失、重复或多余	按三类 source 建立精确覆盖
`one Creator outcome cannot carry two depictions` / `visual depicts an unknown Creator outcome`	同一 outcome 有两张 depiction，或 depiction 指向不存在的 outcome	每个 outcome 至多一张 depiction，且只描绘已定义 outcome
`reveals an unobserved fact`	follow-up 试图说角色未观察到的事实	修改 `character_observes` 的真实因果或不披露该 fact
`visual depicts an uncommitted or private fact`	`visible_fact_ids` 包含 private/未提交 fact	只保留对应 outcome 的 externally-visible fact
`declared source file is missing`	module/asset 路径错误或文件缺失	使用安全相对路径并补齐真实文件
`existing content-addressed bundle differs from a fresh compile`	source、compiler、policy 或已有 output 已变化	先确认变化是否预期，再重新 compile 到清晰的新 output root

修结构错误时不要顺便改变剧情意义。若某条规则迫使 Creator 做出不忠于角色的内容，记录为 contract gap，并让 product/decision owner 判断应修改 schema 还是调整 package。

10. 编译后进行 Creator review

结构通过只是第一关。先对 source 和 compiled contract 人工检查：

ordinary conversation 的 voice/meaning 约束是否像这个角色，而不是通用助手；
用户施压时，允许的角色 stance 是否包含拒绝、重解释或反提议；
user influence 是否只影响角色判断，没有直接选择行动；
outcome contract 是否只来自角色行动、NPC、scenario clock 或 environmental cause；
follow-up source 是否只允许说已观察和获准披露的事实；
Journal 与 visual source 是否只描述对应 outcome 可公开的 causality；
中文或英文文案是否在所有 exact/recovery surface 中一致自然。

当前 application code 的固定 owner preview 可以另外检查普通对话、最小 turn trace 和两次手动 checkpoint：第一次提交角色决定、确定性结果与等待状态；第二次提交经过校验的主动回访、package-approved 静态结果图、结构化 Journal 与 public-safe timeline。它不提供 ambient scheduling（#325 的 opt-in TimeMappingProfile 之外）、外部通知或实时图片生成，也不会自动运行刚编译的新 package。等某个 runtime surface 确实实现并绑定到获批 package 后，再用 acceptance case 检查该 surface 的实际行为；不要把 source review 写成已经跑过的 runtime evaluation。

接下来再根据生命周期与权限边界判断需要哪些审批。不要因为 JSON 中出现 bundle digest 就称它为已发布 package。

进阶实例

当前内部验证使用过一个较复杂的中文 Creator source，以及一个结构和语言都不同的英文 synthetic compiler canary。前者不是最小 scaffold；后者也不具备 IP rights、Creator approval 或发布资格。

与 Meet-U 团队协作时，可以请求一份适合当前 Pilot、已确认分享范围的示例结构。复制任何示例前，先分清可复用的结构范式与某个 IP 独有的创作意义，绝不能只替换 ID 和名字。

快速开始：制作一个 Creator Source Package v1 ​

0. 准备环境 ​

1. 先写一页创作 worksheet ​

2. 选择默认语言 ​

3. 建立目录和七文件闭包 ​

4. 填写 source-package.yaml ​

5. 按依赖顺序填写六个 module ​

5.1 character.yaml：角色自身 ​

5.2 relationship.yaml：用户如何影响她 ​

5.3 arc.yaml：决定、事实和结果 ​

5.4 dialogue.yaml：如何呈现已获授权的意义 ​

5.5 visual.yaml：描述意图并引用已有素材 ​

5.6 acceptance.yaml：保存创作者期望 ​

6. 在编译前做一次人工闭包检查 ​

7. 编译 package ​

8. 用 --check 复核相同输出 ​

9. 常见错误怎么处理 ​

10. 编译后进行 Creator review ​

进阶实例 ​

快速开始：制作一个 Creator Source Package v1

0. 准备环境

1. 先写一页创作 worksheet

2. 选择默认语言

3. 建立目录和七文件闭包

4. 填写 `source-package.yaml`

5. 按依赖顺序填写六个 module

5.1 `character.yaml`：角色自身

5.2 `relationship.yaml`：用户如何影响她

5.3 `arc.yaml`：决定、事实和结果

5.4 `dialogue.yaml`：如何呈现已获授权的意义

5.5 `visual.yaml`：描述意图并引用已有素材

5.6 `acceptance.yaml`：保存创作者期望

6. 在编译前做一次人工闭包检查

7. 编译 package

8. 用 `--check` 复核相同输出

9. 常见错误怎么处理

10. 编译后进行 Creator review

进阶实例