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

Read this page in English

本流程适用于已经获得项目 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：

npm run setup

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

1. 先写一页创作 worksheet

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

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

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

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

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，再建立：

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：

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 很重要：当模型无法安全保留 effect 时，CHAT_ONLY recovery 会精确使用这段 Creator 文案。它应该既忠于角色，又能在普通无 effect 和 capability boundary 场景中成立。

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

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

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，再按以下顺序写：

1. narrative_time 和 world.facts/locations/npcs/deadline
2. progression.initial_character_beliefs
3. decisions
4. 每个 decision 对应的 outcomes
5. 每个 outcome 对应的一个或多个 followups
6. conversation_availability 与 progression.decision_phase

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

每条 decision 必须包含角色自己的 action，并且恰好指向一个 outcome。每个 outcome 必须反向指向该 decision；每个 outcome 至少要有一个 arc follow-up option，同一 outcome 可以有多个不同 follow-up ID。不要把 user observation 写成 outcome cause。

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

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

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

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_ref: character.constructive_refusal.style_anchor
      applicability:
        - availability_class: immediate
          recovery_obligation_types:
            - ordinary_no_effect
        - 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 和每个 outcome 的一张 depiction。每个 asset ID 必须唯一，每个 outcome 必须恰好有一张 visual。

package-local asset 使用：

source_path: assets/portrait.png

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

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 记录来源，但不会批准素材。

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；
• dialogue 和 visual 覆盖所有 follow-up/outcome；
• Journal 精确覆盖所有 influence/decision/outcome；
• reveal 的 fact 已由角色观察，画出的 fact 是 externally visible；
• default locale、recovery locale 与 no-eligible 文案一致；
• 所有 asset 文件真实存在且不是 symlink。

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

7. 编译 package

从仓库根目录运行：

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：

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 建立精确覆盖
visual outcome depictions do not match arc outcomes	某 outcome 没有唯一视觉	每个 outcome 恰好定义一张 depiction
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、外部通知或实时图片生成，也不会自动运行刚编译的新 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 和名字。