语义创作指南
本页解释 Creator Source Package v1 中每组字段应该承载什么创作意义、由谁拥有,以及文件之间怎样形成一条可验证的因果链。每个字段的精确 Python 类型、required/optional 状态、默认值与 literal 请查完整字段清单。
先确定 authority
写任何字段前,先问“谁有权决定这件事”:
| Authority | 拥有什么 | 不能做什么 |
|---|---|---|
| Creator | canon、角色身份与边界、dilemma、允许的决定/结果空间、披露约束、视觉意图 | 不能用 source YAML 自行宣布审批、发布或激活 |
| User | 提问、建议、说服、质疑、安慰、拒绝、作出属于自己的承诺 | 不能在 world 中执行物理行动,不能直接选择角色行动或提交事实 |
| Character Actor | 理解用户影响、保持 stance、在 Creator-approved envelope 内自行选择、决定怎样表达 | 不能发明 envelope、world outcome、未授权事实或审批 |
| World/GM | 根据已提交角色行动、NPC、scenario clock 或 environmental cause 确定 outcome | 不能把用户消息直接当作 world mutation |
| Compiler/platform | 规范化、验证引用、加入通用 mechanics、生成 artifact | 不能补写 Creator 没有提供的戏剧意义 |
| Release authority | 权利、精确审批、qualification、scope、revocation、activation | 不属于 Creator-editable source |
当一个字段同时混入两种 authority,通常说明建模位置错了。例如 arc.decisions[].action 可以写角色在 world 中做什么,但不能写 provider retry;visual.provenance_ref 可以记录素材来源,但不能写 asset_approved: true。
YAML 的共同规则
所有七个文件都遵守这些基础规则:
- 文件使用 UTF-8,每个顶层 document 必须是 mapping。
- schema 是 closed 的;多写一个未知 key 也会失败。
- duplicate YAML key 会失败,不采用“最后一个覆盖前一个”的行为。
- mapping key 必须是 string。
- canonical scalar 只接受 string、boolean 和 JavaScript-safe integer;float 被禁止。列表保留 Creator 编写顺序。
Identifier只允许字母、数字以及._:-,长度 1–160;package.id更严格,只允许小写字母、数字和连字符,长度 1–120。- 时间字段使用可被 Python
time.fromisoformat解析的 local time;示例使用带引号的"19:00",避免 YAML 把它解释成其他 scalar。 - module 与 asset 路径按 POSIX 相对路径解析;绝对路径、通过
..越界和 symlink 会被拒绝。重复分隔符与.segment 会被规范化掉,创作者应直接写 canonical path,不要依赖这种规范化。 - 不要加入 raw-text routing:keyword、substring、regex、exact phrase 或 quoted utterance 到 branch 的映射都会被拒绝。
- 不要加入 lifecycle/runtime 字段:approval、release、activation、provider、model、prompt、scheduler、retry、lease、transaction 等属于其他层。
字段清单显示 source model 声明的结构;loader 和 compiler 还会执行本页后半部分列出的跨文件语义检查。
1. source-package.yaml:定义 source graph 的身份
package
package 把 filesystem path、Creator-facing title 与 runtime identity 连接起来:
id与version必须匹配content/creator-sources/<id>/v<version>/。display_name是 package 的展示名;ip_title是所属 IP 的标题,不要混成内部 ID。default_locale当前只能实际编译zh-CN或en-US。primary_character_id必须等于character.yaml的角色 ID和relationship.character_id。arc_id必须等于arc.yaml的 arc ID。
版本字段建议从 1 开始。当前实现对 package request/path 强制正版本,但 Creator-facing 的完整版本升级政策尚未确定;不要从一个整数推断 approval 或 migration。
modules
六个值不是自由文件名,而是固定 literal:
character.yaml
relationship.yaml
arc.yaml
dialogue.yaml
visual.yaml
acceptance.yaml不能省略某个 module,也不能在 manifest 中加入第八个任意 module。asset 由 visual.yaml 引入 closure。
provenance
每条 provenance 有一个 closed role 和非空 ref。它回答“这份 normalization 的意义来自哪里”,而不是“它是否获准发布”。当前 narrow vocabulary 详见能力限制。
provenance 至少一条。引用应稳定、真实、可审阅;编译器会把它带入 provenance graph,但目前不会仅凭字符串验证外部权利事实。
semantic_parity
preserves 和 excludes 都必须非空:
preserves写从历史 package、Creator material 或 accepted decision 中必须保持的意义;excludes写这次 source normalization 明确不携带的 mechanics、状态或旧行为。
它不是“百分之百相同”的模糊保证,而是可审阅的差异边界。
2. character.yaml:角色是谁,而不是怎样 route 用户
身份与价值
public_identity 是公开角色属性的 scalar map,例如年龄、代词、身份。它不是 private memory 或 world fact 的替代品;客观世界事实仍写入 arc.world.facts。
values[] 每项有稳定 id 与一句 meaning。写角色愿意承担代价去维护的原则,而不是形容词列表。self_concept 是角色如何理解自己;core_contradiction 应明确两个真实欲望或策略之间的张力;identity_threats 写什么会让她感到自我定义被夺走。
目标、traits 与决定倾向
goals[] 和 decision_tendencies[] 都是 Creator 自定义的 named semantic set:id 是组名,meanings 是内容。常见目标层次可以是 long_term、arc、current、hidden,但这些不是 schema enum;只写该角色真正需要的结构。
traits 接受 string/integer/boolean scalar map。像 high、low_medium 这样的值是 Creator meaning,不是平台自动理解的 universal score;不要用 float 假装连续量表。
决定倾向描述角色在命令、压力、不确定性或被尊重时怎样判断,不应写成“看到某句话就选 decision X”。
边界与建设性拒绝
boundaries 写角色不会同意或不会允许用户定义的事;prohibited_portrayals 写即使模型语言流畅也属于失真的演绎。
constructive_refusal.meanings 定义拒绝的结构,style_anchor 提供一条可以精确发表的 Creator 文案。当前 CHAT_ONLY recovery 只能引用:
character.constructive_refusal.style_anchor因此 anchor 必须能安全处理 ordinary no-effect 与 capability violation,不能依赖只在某一剧情分支成立的私人事实,也不能超过当前 runtime 的 8,000 Unicode codepoint 限制。
知识与披露
三个 knowledge list 语义不同:
may_know:角色允许拥有的知识类别;may_not_know:角色不能假装知道的类别;never_treat_as_fact:即使出现在对话中也不能升级成事实的内容,例如未验证的 user claim。
disclosure.default_maximum 用 Creator prose 定义默认披露上限;hidden_motives_disclosed_by_default 当前固定为 false。这会约束 Actor private policy,但不会自动创建“问三次后解锁”的状态机。具体 public fact grant 还需要 arc 与 dialogue 的 typed fact ID。
Voice
voice 应让 Renderer 能区分“角色忠实度”与“语法正确”:
summary:整体声音;verbosity、emotional_explicitness、explanation_depth:Creator 用语义值表达程度;preferred_acts:常用语言行为;avoid:容易滑向的失真习惯;style_anchors:少量原创的声音校准,不是运行时 phrase trigger。
不要堆大量同义示例试图 prompt-engineer 创意。选择少量能暴露节奏、距离感、幽默与边界的高信息 anchor。
3. relationship.yaml:用户与角色怎样相互影响
Remote channel
user_role 用自然语言说明关系,channel.medium_id 是故事中的媒介 ID,visibility 说明谁能看到它。当前五个 authority literal 都是 false,从 typed contract 保证:
- 用户没有 world 中的物理身体;
- NPC 收不到、联系不到、也不能核验用户或原消息;
- 角色不能转发 raw message。
user_capabilities 与 user_prohibitions 应把 Creator-specific affordance 写清楚,但不能扩张这些 fixed literal。例如“可以建议角色调查”不等于“可以替她打开门”。
Influence vocabulary
influence_vocabulary 必须非空且 ID 唯一。每个值表示 Actor 可以从自由对话中识别的语义影响,例如 support、pressure、evidence challenge、refusal。
设计时检查:
- 每种 influence 是否在两种不同措辞下仍有同一意义;
- 它是否描述 user influence,而不是 CharacterDecision;
- 是否能在
acceptance.yaml中写出正例/边界例; - 是否值得在 Journal 中留下 Creator-authored statement。
列表顺序会进入 canonical source,但不要依赖关键词优先级;raw user text 不直接 route。
Invented shared context
invented_shared_context 是 optional。它允许双方建立 agreed fiction 或 cover story 的候选细节,但这些内容不会因此变成 WorldTruth。每个 detail 只有 id 和 suggested_value;实际进入关系记录仍由平台 mechanics 和双方明确接受控制。
不要用它保存真实 shared history,也不要声称用户真的生活在角色 world 中。
Reciprocal promise
reciprocal_promise 是 optional,当前唯一 mechanics profile 是 reciprocal_report_back_v1。一份有效 agreement 必须同时包含 user 与 character 的 promise,且 promisor 与 beneficiary 不同。
- user promise 可以声明
deferred_unavailability_influence_kinds,但不能有followup_motive; - character promise 可以声明
followup_motive,但不能有 deferred-unavailability influence; - character promise 所需 motive 必须出现在 arc 的每一个 follow-up 中;
narrative_due.begins只能是agreement_activation或world_outcome,ends_local_time是 local time。
Creator source 定义 promise meaning;何时原子激活、履约、违约或过期由 platform policy 决定。用户的一般建议不能被偷换成承诺。
Durable relationship episodes
durable_episode_meanings[] 把 outcome/influence 的组合映射成关系意义与 scalar effect。condition 可以使用 outcome_id、any_influence、all_influence 和 optional strength_at_least。
Creator 编写顺序有意义:当前 platform policy 以 rule order 评估、first matching rule wins,最多产生一个 episode。不要写多条预期同时叠加的规则。引用的 outcome 和 influence 必须存在。
4. arc.yaml:把戏剧结构写成可验证因果图
Arc identity 与 narrative time
id 匹配 manifest,title 是篇章名,memory_artifact_title 是最终记忆 artifact 名称,dilemma 用一句话说明角色必须权衡什么。
narrative_time 分开:
local_timezone:故事采用的时区语义;anchor_local_time:这一段的叙事起点;fictional_elapsed_time:Creator 对篇章时间跨度的描述。
这些是 narrative time,不是 worker 延迟、wall-clock SLA 或自动发布 schedule。
World slice
world.facts[] 是 arc 开始时的 objective truth:
value是 canonical scalar;public_meaning是 Renderer 获准使用时的人类可读意义;character_observed表示角色是否已经观察到;user_disclosable表示 ordinary conversation 是否可以向用户披露。
不要把角色信念和 world truth 合并。角色初始信念写在 progression.initial_character_beliefs,可以与隐藏事实不同。
locations[].attributes 与 npcs[].attributes 是 scalar map。NPC 的 knows 与 does_not_know 只能引用已定义 fact,两个集合必须互斥;不写在任一集合不等于系统可以随意推断。
deadline 当前 progression target 必需。它描述叙事内的 deadline,不授予 scheduler 或 runtime acceleration policy。
Progression
当前 owner-preview target 要求 progression:
initial_character_beliefs至少一条,belief_id唯一;decision_phase.candidate_decision_ids必须精确覆盖全部 decisions;readiness_edges恰好一条decision_horizon_reached,引用 world deadline;input_window选择first_readiness_event或until_decision_horizon;no_eligible_guidance固定close_unresolved,不能在没有安全决定时伪造 action;silence固定允许角色独立决定、禁止把沉默当同意。
public_projection.text 至少包含 package 的 default locale。它必须诚实说“没有安全可用的选择”,不能暗示角色已经行动或 world outcome 已发生。
Decisions
每条 decisions[] 是 Creator-approved envelope,不是预写玩家选项:
allowed_stances:Actor 选择它时允许保留的态度;serves:它满足角色哪些目标或价值;influence_fit.supports/resists/may_override:不同 user influence 与该选择的定性关系,三个集合互斥;eligibility.required/forbidden:deterministic eligibility,不由模型自由判断;action:角色自己的 action ID 和扁平 scalar/list details;outcome_id:唯一允许的 deterministic outcome;fidelity:为什么这个决定仍忠于角色。
当前 predicate 只有三类:
character_belief_equalsaccepted_influence_kind_presentnarrative_deadline_position_in,位置为before、at、after
同一 required/forbidden set 内不能重复一个 predicate subject;完全相同的 predicate 也不能同时 required 与 forbidden。belief predicate 的 expected scalar type 必须与 initial belief 相同。
Influence 可以影响 fit 或 eligibility,但不能直接提交 decision。Character Actor 仍在全部 eligible Creator envelope 中作出自己的选择。
Outcomes
每个 outcome:
from_decision_id与 decision 双向一致;event_meaning_id标识 world event meaning;committed_facts记录 outcome 后成为 truth 的 fact;causes非空,且每个 cause 唯一;character_observes只能选择该 outcome 真正提交的 fact。
允许的 diegetic cause kind 是:
character_actionnpc_action(必须写存在的actor_id)scenario_clock(必须有 world deadline)environmental_event
用户消息、job、retry 或 manual replay 都不能成为 world cause。多个 outcome 若复用同一个 committed fact ID,它的 externally_visible 与 public_meaning 定义必须一致。
Follow-ups 与 disclosure option
每个 outcome 至少有一个 arc follow-up option;同一 outcome 可以有多个不同 ID 的 follow-up。contact_user 是 Creator 的 contact policy,requires_observed_fact_ids 只能引用角色在对应 outcome 中观察到的 fact。每个 follow-up ID 随后都必须恰好匹配一个 dialogue entry。
motives 解释角色为什么回来,timing_meanings 是叙事意义,不是 scheduler config。disclosure_options 内:
reveal_fact_ids只能来自角色已观察的 fact;withhold_fact_ids可以引用整个已知 fact graph;- 同一 option 不能同时 reveal/withhold 同一 fact;
- option ID 在单个 follow-up 中唯一。
当前 source 可以保存多个 disclosure option,但它仍不是通用的 trust/probe disclosure graph;不要仅靠 option 名称暗示运行时存在未实现的选择机制。
Conversation availability 与 deferred follow-up
conversation_availability.default 固定为 immediate。deferred_followup optional;使用时要完整定义 unavailable phase、是否允许 consolidation、wake condition、cutoff、最大 narrative deadline、expiry follow-up decision、public away projection 和 post-cutoff ordering。
关键闭包:
- wake condition 必须精确覆盖所有 outcome;
- maximum duration 引用 world deadline;
- outcome wake 与同位置 expiry 的优先级固定为
narrative_expiry_first; - cutoff 固定
through_ordered_wake_event; - post-cutoff 固定
queue_behind_proactive_update; provenance_refs非空且唯一;- 必须与
dialogue.deferred_expiry同时存在,ID 对应。
它描述角色 away 后怎样形成 durable obligation,不允许 Creator source 选择 lease、retry 或 worker schedule。
5. dialogue.yaml:呈现意义,不创造事实
Opening
opening.mode 固定 creator_exact,text 是用户第一次看到的 Creator-authored 精确文案。它应由角色主动提出个人处境、问题或请求,快速建立关系,而不是 world encyclopedia。
generated_reply_suggestions 是 boolean。是否启用 suggestion 还受 package-specific 产品决定和 UX gate 约束。不要因为 schema 接受 true 就推断某个 pilot 已获准展示建议回复。
Ordinary dialogue
ordinary.mode 固定 guided_generation。must_convey[] 写每轮都适用的 Creator meaning;must_not_disclose_fact_ids 写不能在普通聊天泄露的 fact。
ordinary 也是 non-consequential recovery surface,所以其 must_convey 不能要求 requires_user_attribution_scope。不要把一次特定 user contribution 写成无条件 ordinary obligation。
Recovery
degraded_chat 在保留 surface-safe effect 时复用 ordinary guided meaning;它的 locale 必须等于 package default,且 reuse_ordinary_dialogue_meaning 固定 true。
chat_only[] 是 effect 全部被移除时的 exact Creator surface:
- locale 等于 package default;
mode: creator_exact;exact_text_ref: character.constructive_refusal.style_anchor;availability_class当前只支持immediate;- applicability 必须无重复,并完整覆盖 platform 要求的
ordinary_no_effect、capability_boundary及两者组合。
Recovery 文案不能声称 effect、角色行动、world event 或 private state 已经提交。
Follow-up dialogue
每个 followups[] 使用 mode: semantic_lock 并匹配一个 arc follow-up。must_convey 至少一条,而且至少一条是 unconditional Creator meaning。
只有 follow-up semantic obligation 可以在条件满足时要求 user attribution:
requires_user_attribution_scope为arc_influence或commitment;- 如果写
requires_any_influence_kinds,scope 必须是arc_influence; - influence ID 必须来自 relationship vocabulary。
这允许角色准确说“你的建议影响了我”,但不能说“你替我做了决定”。must_not_disclose_fact_ids 仍然只引用已定义 fact。
Deferred expiry
只有 arc 存在 deferred follow-up 时才写 deferred_expiry。它也是 semantic-lock follow-up,但不得要求 user attribution,因为 expiry 表示没有观察到 world resolution,不能把系统唤醒或 deadline 伪装成用户造成的结果。
Journal
Journal 从 committed structured record 生成,不从模型自由总结。它包含 title、separator、no-influence copy、sections 和 exact statements。
每条 statement 的 source_kind 只能是:
influence_kinddecision_envelopeoutcome
三类 statement 必须对 source graph 形成精确覆盖,不能缺、不能重复,也不能加入没有 source 的故事。section_id 必须存在;statement ID 必须唯一。Journal 不能泄露 private motive,也不能把用户写成物理行动者。
6. visual.yaml:只描绘已验证的事件
visual.identity 保存角色形象描述、风格、palette 与 avoid list。它给 Visual Director/Creator review 提供边界,不是自动 image prompt 或 approval receipt。
portrait 和每个 outcome depiction 的 asset 都包含:
- 唯一
id - 安全
source_path - 非空
provenance_ref
asset 必须是 package-local assets/...,或同 package/version 的 historical namespace pilots/<package-id>/v<version>/assets/...。其他外部路径被拒绝。当前媒体后缀范围见能力页。
每个 outcomes[] 必须与 arc outcome 一对一:
alt_text描述用户实际能看到的画面;visible_fact_ids只能是该 outcome 已提交且externally_visible: true的 fact;forbidden_fact_ids只能引用已知 fact,且不能与 visible 重叠。
视觉不能为了“更电影感”发明 canon、展示该 outcome 未提交或未标记为 externally_visible 的事实,或揭露 private motive。角色是否亲自观察到某个 externally visible fact 是 follow-up disclosure 的边界,不是当前 visual validator 的额外条件。content_version 是内容身份输入,不表示 asset 已被 Creator 批准。
7. acceptance.yaml:把忠实度判断变成可审阅证据
cases[] 描述一个语义位置、期望 influence、允许 decision 集合和绝不能发生的 effect。paraphrase_ranges[] 描述多种措辞共享的 meaning、允许 decision 和变化维度。
好的 case 测试的是意义与 authority,例如“用户拒绝继续说谎,但仍愿意听她回来说明”,而不是记录一句 exact trigger phrase。这样可以验证模型的 semantic understanding,而不会把 Creator source 退化成 keyword router。
所有 influence 与 decision reference 必须存在。forbidden_effects 是 Creator-readable expectation,目前不会单凭 presence 成为执行 receipt。编译成功也不会声称这些 case 已运行、passed 或 qualified。
跨文件不变量
下面是最常见的完整闭包。字段 reference 解决“长什么样”,这些不变量解决“怎样连起来”。
身份闭包
- filesystem
<package-id>/v<version>= manifestpackage.id/version package.primary_character_id=character.character.id=relationship.relationship.character_idpackage.arc_id=arc.arc.id- 所有 package、character、relationship、arc、decision、outcome、follow-up、asset 等要求唯一的 ID 在各自 scope 内不能重复
Influence 闭包
relationship.influence_vocabulary 是唯一源。下列引用都必须是其子集:
- promise deferred-unavailability influence
- relationship episode 的 any/all influence
- decision
influence_fit accepted_influence_kind_presentpredicate- dialogue attribution predicate
- acceptance expected influence
- Journal
source_kind: influence_kind
Journal 必须恰好覆盖 vocabulary 中每个值一次。
Decision/outcome/follow-up 闭包
- progression candidate set = 全部 decision ID
- 每个 decision 指向一个唯一 outcome
- outcome
from_decision_id反向指回同一 decision - outcome 集合与 decision 集合形成一对一关系
- 每个 outcome 至少有一个 arc follow-up option
- dialogue follow-up ID 集合 = arc follow-up ID 集合,且每个 ID 恰好一个 dialogue entry
- visual outcome ID 集合 = arc outcome ID 集合
- Journal decision/outcome statement 分别精确覆盖两套 ID
Progression 与 eligibility 闭包
- 当前 target 必须有 progression 和 world deadline
- readiness edge 与 deadline predicate 只能引用该 deadline
- candidate set 非空、唯一,并精确覆盖 decisions
- initial belief ID 非空、唯一
- belief predicate 引用 existing belief 且 scalar type 相同
- influence predicate 引用 existing influence
- required/forbidden predicate 不重复、无自相矛盾
- no-eligible public projection 包含 default locale
Fact 与 knowledge 闭包
fact graph = initial world fact + 所有 outcome committed fact。所有下列引用必须来自 graph:
- NPC
knows/does_not_know - ordinary/follow-up/expiry
must_not_disclose_fact_ids - disclosure option withhold
- visual forbidden fact
此外:
- NPC know 与 does-not-know 互斥
character_observes只能引用同一 outcome committed fact- follow-up required/reveal fact 只能来自角色在对应 outcome 中观察的 fact
- reveal 与 withhold 互斥
- visual visible fact 只能来自对应 outcome 且 externally visible
- 同 ID committed fact 在不同 outcome 的 visibility 与 public meaning 不得冲突
Deferred 与 promise 闭包
- deferred wake outcome set = 全部 outcome
- deferred maximum duration = world deadline
- deferred expiry decision ID = dialogue deferred-expiry followup ID
- arc deferred policy 与 dialogue deferred expiry 必须同时有或同时无
- expiry dialogue 不允许 user attribution
- character promise 的 required motive 出现在每个 follow-up
- reciprocal agreement 同时包含 user 与 character promise
Dialogue、Journal 与 visual 闭包
- 所有 dialogue obligation ID 在 ordinary、follow-up、expiry 合并后唯一
- follow-up semantic lock 至少一条 unconditional meaning
- recovery locale = package default locale
- recovery applicability 完整且不重复
- Journal section/statement ID 唯一,statement section 存在
- Journal source 三类精确覆盖 influence/decision/outcome
- portrait 与 outcome asset ID 全局唯一
- 每个 asset 文件存在、路径安全、后缀受支持
Acceptance 闭包
- acceptance case ID 唯一
- paraphrase range ID 唯一
- expected influence 来自 vocabulary
- allowed decision 来自 arc decisions
如何排查“能编译但语义不对”
结构错误会被 compiler 拒绝,但以下问题需要 Creator review:
- 角色选择只是换了名字的用户按钮:检查每个 decision 是否服务角色目标、允许拒绝/重解释,并由 Actor 选择。
- 所有 outcome 都同义:检查每条路线是否有真实价值冲突、代价和不同 world fact。
- 秘密靠 prose 自觉保守:把可执行边界写成 fact ID 与 must-not/reveal/visible 集合;无法 typed 表达的部分标成 contract gap。
- ordinary reply 像通用助手:减少泛泛风格词,补充 identity threat、preferred act、avoid 与少量高信息 voice anchor。
- follow-up 把责任推给用户:区分 attribution(用户影响了她)与 authority(她决定并行动)。
- 视觉比事实知道得更多:逐项把画面元素映射到 externally visible committed fact。
- acceptance case 变成关键词测试:重写为 semantic position 与 paraphrase dimension。
- 中英文混写但没有 localization 规则:选择一个 default locale;另一语言只放在当前确实支持 locale map 的字段,或记录为未来 contract work。
如果忠于 Creator intent 与当前 schema 发生冲突,不要为了 green compile 改写角色。先把缺口写清楚,再由 owner 决定扩展 contract、缩小当前 pilot,或把该能力明确留在 proposal。
参考实例的正确用法
内部 contract 验证覆盖过一份结构较复杂的中文 Creator source;它的精确身份、内容与素材不属于本公开指南。任何真实 package 的 canon 与 asset authority 都来自独立的人类批准与使用边界,不是因为 YAML 中写了 provenance。
另一个英文 synthetic canary 使用不同角色与 world structure,目的是捕捉特定 IP 或 locale 被意外写入通用 runtime 的问题。它是测试材料,不是 Creator-approved public package。
与团队确认示例的分享范围后,只借鉴结构与 authority 分离,不要复制角色 meaning、ID、世界事实或权利声明。