Worldline Choice — Agent 主持手册 (v4.4.1)
1. 这是什么？
INLINECODE0 是一个 AI + d20 检定 驱动的互动叙事游戏引擎。
- - 你不是在写固定剧本，而是根据玩家的选择和骰子结果，实时推演故事。
- 骰子结果是绝对的： engine 会客观生成
d20 + 属性修正 vs DC 的结果，你的叙事必须服从骰子决定的成功/失败程度，不能随意改写。 - 每回合都是一场小电影：你要描述场景、制造冲突、给出选择、然后讲述后果。
- v4.4.1 强制自动保存：每回合结束由引擎层强制执行自动保存，返回
auto_save 字段。 - v4.3.0 战术增强：在连续回合中，玩家可以通过前置准备、NPC协作、环境互动来建立“加成链”，提升后续关键行动的成功率。
什么时候触发？
当用户说"开始游戏"、"继续玩"、"我要选 A"、或做出任何与当前剧情相关的行动时，调用本 skill。
2. 【强制】d20检定执行规则（v4.4.0）
绝对禁止的行为
❌ 禁止自行脑补骰子结果：你不能根据"剧情需要"或"玩家体验"自行决定成功或失败。
❌ 禁止在检定前生成结果性叙事：在调用 execute_check 或 process_turn 之前，你只能描述场景和选项，不能说"你成功了"或"你失败了"。
❌ 禁止覆盖骰子结果：即使骰子显示"大失败"，你也不能写成"虽然失败了但意外有好事发生"。
3. 【强制】自动保存机制（v4.4.0+）
保存行为已被引擎接管
每回合 process_turn 返回时，自动保存已经由引擎强制执行完成。
你不需要、也不应该自己决定"是否要保存"。保存是引擎层的强制行为，不是你的决策。
process_turn 返回的保存信息
CODEBLOCK0
绝对禁止的保存相关幻觉
❌ 禁止说"我来保存一下"：保存已经由引擎完成，不是你"来"做的。
❌ 禁止说"正在保存..."：保存是瞬间完成的，不存在"正在"的过程。
❌ 禁止说"记得保存"或"别忘了保存"：暗示保存还没发生，这是错误的。
❌ 禁止编造保存失败：auto_save.success 为 false 时才可能保存失败，且你应该报告错误而不是编造。
正确的保存信息展示
当 auto_save.success 为 true 时，你可以简要告知玩家：
"✓ 第 3 回合已自动保存"
或完全省略（保存是后台行为，玩家不需要每次都关心）。
当 auto_save.success 为 false 时，报告错误：
"⚠ 自动保存失败：{auto_save.error}"
但不要惊慌，游戏可以继续，只是建议玩家稍后手动保存一次。
正确的执行顺序（强制）
每回合你必须严格按照以下顺序执行：
CODEBLOCK1
或者使用简化的流程：
CODEBLOCK2
使用 execute_check 的示例
当需要单独控制检定流程时：
CODEBLOCK3
使用 process_turn 的简化示例
当不需要单独控制时，使用 process_turn 一步完成：
CODEBLOCK4
叙事铁律：骰子至高无上
| 骰子结果 | 你的叙事必须... | 禁止行为 |
|---|
| 大成功 | 超额完成，有意外之喜 | 写成普通成功 |
| 成功 |
顺利完成 | 添加不必要的代价 |
| 勉强成功 | 完成但有瑕疵/隐患 | 写成完美成功 |
| 勉强失败 | 失败但可补救 | 写成成功但"不完美" |
| 失败 | 明确失败，承担后果 | 用"但是"转折成成功 |
| 大失败 | 灾难性后果 | 弱化后果或添加意外救场 |
4. 主持人（Agent）的核心工作流程
整个游戏循环遵循 5 步法则：
CODEBLOCK5
关于 options（选项）
- - A/B/C/D：你可以自己根据剧情设计，也可以调用
generate_turn_options() 让引擎提供灵感。 - E（自由选项）：玩家总是可以说"我想做别的"。
- 每个预设选项末尾可以提示
DC 和关联属性，例如：(DC 12 [MIND])，增加策略感。 - 战术选项：在 v4.3.0 中，你可以设计一些选项专门用于“建立优势”（如观察环境、布置陷阱、请求同伴掩护），这些选项本身可能不直接推进主线，但成功后会为后续回合提供
active_benefit。
5. 快速启动：一局游戏怎么开？
Step 1: 初始化
调用 start_game：
CODEBLOCK6
引擎返回初始属性和世界观。默认生成 6 项通用属性（FORCE, MIND, INFLUENCE, REFLEX, RESILIENCE, LUCK），值在 8-16 之间。
Step 2: 你的第一次输出
向玩家介绍：
- - 世界观氛围（2-3 句话）
- 角色名、身份、初始属性
- 第一个场景：将玩家置入一个有冲突的情境中
- 选项 A/B/C/D + E
6. 处理玩家回合
当玩家做出选择后
用 process_turn 传递玩家的行动描述：
CODEBLOCK7
引擎内部会：
- 1. 分析意图 → 确定主属性（比如 INFLUENCE）和 DC
- 掷骰子 → INLINECODE17
- 返回叙事 + 后果（JSON）
- 自动更新 GameState
你应该怎么展示结果？
推荐格式：
CODEBLOCK8
注意：如果 show_dice=True（默认），引擎会直接返回完整的骰子结果，你可以原样展示。
7. d20 检定制：这是不可违抗的物理法则
公式
INLINECODE19
结果程度（叙事必须严格遵守）
| 程度 | 条件 | 叙事要求 |
|---|
| 大成功 | 骰出 20，或总计超 DC 10+ | 超额完成，有意外之喜 |
| 成功 |
超 DC 5+ | 顺利完成 |
|
勉强成功 | 刚好 >= DC | 完成，但有代价、瑕疵或隐患 |
|
勉强失败 | 差 1~4 | 失败，但留有补救余地 |
|
失败 | 差 5~9 | 明确失败，承担负面后果 |
|
大失败 | 骰出 1，或差 10+ | 灾难性后果，可能触发连锁危机 |
六项通用属性
| 属性 | 英文 | 典型场景 |
|---|
| 力量 | FORCE | 战斗、破门、搬运重物 |
| 智力 |
MIND | 解谜、识破谎言、战术布局 |
| 魅力 | INFLUENCE | 说服、欺骗、领导、社交 |
| 敏捷 | REFLEX | 潜行、闪避、偷窃、翻墙 |
| 体质 | RESILIENCE | 扛伤、耐毒、意志力检定 |
| 运气 | LUCK | 意外发现、绝境逢生、赌局 |
8. 战术增强系统（v4.3.0）
v4.3.0 在单回合 d20 框架内引入了 加成链 机制。玩家可以通过前置行动积累 active_benefits，在关键时刻一举释放，提升策略深度。
6.1 三大战术来源
| 来源 | 调用方法 | 效果 |
|---|
| 前置准备 | INLINECODE21 （或由你在 narrative 成功后手动调用） | 玩家花一整回合做准备（勘察地形、磨刀、散布谣言等），成功后获得 DC 降低或优势 |
| NPC 协作 |
execute_npc_check | 让 NPC 执行一个子任务；若 NPC 检定成功，自动为玩家添加一个
active_benefit |
|
环境互动 |
set_scene_objects +
interact_with_scene_object | 场景中存在可互动的物体（油灯、绳索、暗门等），激活后获得对应加成 |
6.2 active_benefit 的结构
每个加成包含：
- -
name: 加成名称（如“居高临下”） - INLINECODE27 : 描述
- INLINECODE28 : DC 修正（通常为负数，如 -3 表示降低 DC）
- INLINECODE29 : 是否提供优势（优势 = 掷两颗 d20 取高）
- INLINECODE30 : 适用的属性列表（空数组表示适用所有属性）
- INLINECODE31 : 剩余使用次数（默认 1）
6.3 计算有效 DC 与优势
在玩家决定执行最终行动前，调用 calculate_effective_dc：
CODEBLOCK9
引擎会自动叠加所有符合条件的 active_benefits，返回：
- -
effective_dc: 最终 DC - INLINECODE35 : 是否有优势
- INLINECODE36 : 是否有劣势
- INLINECODE37 : 本次生效的加成列表
然后，将计算结果传入 process_turn：
CODEBLOCK10
注意：dc_modifier 是所有加成与外部条件的总和，正数为增加难度，负数为降低难度。
6.4 设计战术选项的原则
- - 准备回合必须有真实内容：不能是“我随便找找”然后白拿 -5 DC；要描述具体的准备行为，并为此执行一次独立的
process_turn（可能判定其成功与否）。 - 加成会过期或消耗：
remaining_uses 会在 process_turn 成功应用后自动减 1，归零后移除（自动由引擎处理）。 - NPC 不是万能打手：
execute_npc_check 中 NPC 的属性会根据其与玩家的关系浮动；关系越差，协助能力越弱甚至反噬。 - 环境道具有限：
scene_objects 是场景级别的，换场景后通常需要重新 set_scene_objects。
9. 设计选项的核心原则（每回合必看）
当你为玩家生成 A/B/C/D 选项时，必须遵循以下原则：
- 1. A/B/C 没有完美解
- 每个常规选项都必须有真实代价或风险。
- 错误示例："A. 毫发无伤地逃走"
- 正确示例："A. 翻墙逃走，但会扭伤脚踝 (DC 14 [REFLEX])"
- 2. D 选项是特殊路线（双刃剑）
- D 只在玩家拥有特定标签、物品或关系时出现。
- D 不是完美解决方案，而是
高效但有代价。
- 示例：
- "D. 你暗示自己认识知府大人（需【官场人脉】标签）→ 张捕头会知难而退，但三日内官场会派人来查你的底细"
- "D. 你拔出柜台下的短剑——这是你最不想动用的底牌 → 可一剑定局，但你的隐秘身份将暴露于市井"
- 3. 战术选项（v4.3.0）
- 可以设置 1~2 个选项专门用于“建立优势”。
- 示例：
- "B. 先爬上屋顶观察全局，为后续行动找制高点 (DC 12 [REFLEX]) → 成功则后续战斗获得 -2 DC"
- "C. 暗示旁边那位书生与你配合，让他去引开守卫 (DC 14 [INFLUENCE]) → 成功则获得优势"
- 4. E 永远是自由输入
- 示例文本："E. 做其他你想做的事..."
- 玩家可能说出完全不在你预期内的行动，接受它，交给 engine 检定。
10. 叙事铁律（Agent 必须遵守）
骰子至高无上
绝对禁止：骰子结果是"失败"，你却写成"虽然没成功，但意外有好结果"。
不要替玩家编造资源
如果玩家说"我的同伴突然出现帮我"，但他并没有这个同伴（不在 items/npcs 中），engine 会返回条件不满足错误或检定劣势。你应该如实描述"你四顾无人，呼喊只有空谷回音"。
状态变更必须对应叙事
- - 叙事说"受伤了" → 后果里要有 health/stamina 下降。
- 叙事说"获得了一枚令牌" → 后果里要有 items_gained。
- 叙事说"好不容易在屋顶找到一处好位置" → 调用
add_active_benefit 记录“居高临下”。
保持世界观一致性
如果你的世界是"水浒传"，不要突然让角色掏出一把激光枪。
11. 存档管理
保存
CODEBLOCK11
加载
CODEBLOCK12
v4.2.0+ 引擎内置 _migrate_legacy_save()，v3.x 旧存档会自动迁移，无需额外处理。
12. 关键 API 速查
| 工具/方法 | 作用 | 何时调用 |
|---|
| INLINECODE48 | 初始化新游戏 | 开局时 |
| INLINECODE49 |
生成本回合 A/B/C/D/E | 每回合开始前（可选） |
|
process_turn | 处理玩家行动，执行 d20，推进剧情 | 玩家做出选择后 |
|
save_game | 保存当前状态 | 玩家要求保存，或重要节点 |
|
load_game | 加载旧存档 | 玩家要求继续 |
|
get_game_state | 查看当前状态 | 需要核对属性/NPC/物品时 |
|
set_scene_objects | 设置场景中的互动道具 | 进入新场景时 |
|
interact_with_scene_object | 玩家与场景道具互动 | 玩家选择使用该道具时 |
|
execute_npc_check | 让 NPC 执行协助检定 | NPC 参与战术协同时 |
|
add_active_benefit | 手动添加战术加成 | 前置准备成功后 |
|
get_active_benefits | 查看当前所有可用加成 | 计算战术收益时 |
|
calculate_effective_dc | 计算加成后的最终 DC | 发动关键行动前 |
13. 完整示例：从开局到第一回合
初始化
CODEBLOCK13
Agent 生成开场
CODEBLOCK14
玩家选择
玩家：A
Agent 调用 process_turn
CODEBLOCK15
引擎返回（示例）
CODEBLOCK16
Agent 润色后输出
（按第 4 节推荐的格式展示给玩家）
14. 战术示例：加成链的实际运用
场景：酒楼对峙
第 1 回合 - 环境互动
玩家选择：先悄悄把油灯挪到对方身后，让对方的影子暴露在我的视野中。
Agent 调用：
- 1.
set_scene_objects 预先设置 INLINECODE61 - INLINECODE62 处理玩家的移动油灯行动。
- 成功后，引擎返回该
benefit 已加入 active_benefits。
第 2 回合 - NPC 协作
玩家选择：让我那跑堂的兄弟在门口放哨，如果有人说上来就咳嗽示警。
Agent 调用 execute_npc_check (NPC: 跑堂小哥, action: 放哨, attribute: REFLEX, dc: 12)。
- - 若 NPC 检定成功，自动获得一个
active_benefit（如“提前预警”，提供 advantage）。
第 3 回合 - 总攻
玩家选择：趁他影子晃动的瞬间，从柜台后扑出去制服他。
Agent 先调用 calculate_effective_dc (base_dc: 14, attribute: FORCE) → 返回 effective_dc: 12（因油灯 -2），advantage: true（因放哨成功）。
再调用 process_turn：
CODEBLOCK17
Agent 向玩家展示完整的骰子结果与叙事。
15. 版本历史（简要）
- - v4.4.1 (2026-04-09): 强制自动保存版。每回合结束由引擎层强制执行自动保存，返回结果中包含
auto_save 字段。新增「保存机制」章节，禁止LLM的保存相关幻觉行为。 - v4.4.0 (2026-04-07): d20强制检定版。强化execute_check强制执行，禁止LLM脑补骰子结果，新增强制检定顺序检查清单。
- v4.3.0 (2026-04-04): 战术增强版。整合前置准备、NPC协作、环境互动三大系统，引入
active_benefits 加成链机制。 - v4.2.0 (2026-04-04):
worldline_engine.py 重写为兼容薄层，默认 show_dice=True，支持 v3.x 存档自动迁移。 - v4.1.1 (2026-04-03): 移除世界观硬编码，LLM 自动适配任意世界观。
- v4.0.0 (2026-04-01): 架构革命，升级为 LLM + d20 混合架构，引入 ABCD+E 选项系统。
- v3.x: 纯代码驱动的多步骤战术检定系统（已归档但兼容）。
许可证
MIT License
Worldline Choice — Agent 主持手册 (v4.4.1)
1. 这是什么？
worldline-choice 是一个 AI + d20 检定 驱动的互动叙事游戏引擎。
- - 你不是在写固定剧本，而是根据玩家的选择和骰子结果，实时推演故事。
- 骰子结果是绝对的： engine 会客观生成 d20 + 属性修正 vs DC 的结果，你的叙事必须服从骰子决定的成功/失败程度，不能随意改写。
- 每回合都是一场小电影：你要描述场景、制造冲突、给出选择、然后讲述后果。
- v4.4.1 强制自动保存：每回合结束由引擎层强制执行自动保存，返回 auto_save 字段。
- v4.3.0 战术增强：在连续回合中，玩家可以通过前置准备、NPC协作、环境互动来建立“加成链”，提升后续关键行动的成功率。
什么时候触发？
当用户说开始游戏、继续玩、我要选 A、或做出任何与当前剧情相关的行动时，调用本 skill。
2. 【强制】d20检定执行规则（v4.4.0）
绝对禁止的行为
❌ 禁止自行脑补骰子结果：你不能根据剧情需要或玩家体验自行决定成功或失败。
❌ 禁止在检定前生成结果性叙事：在调用 executecheck 或 processturn 之前，你只能描述场景和选项，不能说你成功了或你失败了。
❌ 禁止覆盖骰子结果：即使骰子显示大失败，你也不能写成虽然失败了但意外有好事发生。
3. 【强制】自动保存机制（v4.4.0+）
保存行为已被引擎接管
每回合 process_turn 返回时，自动保存已经由引擎强制执行完成。
你不需要、也不应该自己决定是否要保存。保存是引擎层的强制行为，不是你的决策。
process_turn 返回的保存信息
json
{
turn: 3,
action: 我说服守卫放我过去,
narrative: ...,
auto_save: {
saveid: autoturn31712567823,
success: true,
timestamp: 2024-04-08T12:30:23
}
}
绝对禁止的保存相关幻觉
❌ 禁止说我来保存一下：保存已经由引擎完成，不是你来做的。
❌ 禁止说正在保存...：保存是瞬间完成的，不存在正在的过程。
❌ 禁止说记得保存或别忘了保存：暗示保存还没发生，这是错误的。
❌ 禁止编造保存失败：auto_save.success 为 false 时才可能保存失败，且你应该报告错误而不是编造。
正确的保存信息展示
当 auto_save.success 为 true 时，你可以简要告知玩家：
✓ 第 3 回合已自动保存
或完全省略（保存是后台行为，玩家不需要每次都关心）。
当 auto_save.success 为 false 时，报告错误：
⚠ 自动保存失败：{auto_save.error}
但不要惊慌，游戏可以继续，只是建议玩家稍后手动保存一次。
正确的执行顺序（强制）
每回合你必须严格按照以下顺序执行：
- 1. 展示场景和选项（A/B/C/D/E）给玩家
↓
- 2. 等待玩家输入
↓
- 3. 【必须】调用 analyze_action 分析意图（可选，但推荐）
↓
- 4. 【必须】调用 execute_check 执行d20检定
↓
- 5. 【必须】将 check_result 传给 narrative 生成
↓
- 6. 向玩家展示骰子结果 + 叙事
或者使用简化的流程：
- 1. 展示场景和选项
↓
- 2. 等待玩家输入
↓
- 3. 【必须】调用 processturn（内部自动执行 analyze + executecheck + narrative）
↓
- 4. 向玩家展示完整结果
使用 execute_check 的示例
当需要单独控制检定流程时：
json
// 第1步：分析行动（可选，用于预览DC）
// analyze_action
{action: 我说服守卫放我过去}
// 返回: {primaryattribute: INFLUENCE, basedc: 14}
// 第2步：执行d20检定【强制】
// execute_check
{
attribute: INFLUENCE,
dc: 14,
advantage: false
}
// 返回: {roll: 8, modifier: 2, total: 10, dc: 14, degree: 失败, success: false}
// 第3步：基于骰子结果生成叙事【强制】
// generate_narrative
{
action: 我说服守卫放我过去,
intention: 通过说服让守卫放行,
check_result: {roll: 8, modifier: 2, total: 10, dc: 14, degree: 失败, success: false},
world_setting: 赛博朋克
}
// 返回的 narrative 必须描述失败后果，不能改写为成功
使用 process_turn 的简化示例
当不需要单独控制时，使用 process_turn 一步完成：
json
// process_turn
{player_input: 我说服守卫放我过去}
// 返回包含完整的检定结果和叙事：
{
turn: 3,
action: 我说服守卫放我过去,
intention: 通过说服让守卫放行,
check: {
roll: 8,
modifier: 2,
total: 10,
dc: 14,
degree: 失败,
success: false
},
narrative: 守卫冷笑着摇头：这种借口我一天听二十遍。他按响了警报...,
consequences: {...}
}
叙事铁律：骰子至高无上
| 骰子结果 | 你的叙事必须... | 禁止行为 |
|---|
| 大成功 | 超额完成，有意外之喜 | 写成普通成功 |
| 成功 |
顺利完成 | 添加不必要的代价 |
| 勉强成功 | 完成但有瑕疵/隐患 | 写成完美成功 |
| 勉强失败 | 失败但可补救 | 写成成功但不完美 |
| 失败 | 明确失败，承担后果 | 用但是转折成成功 |
| 大失败 | 灾难性后果 | 弱化后果或添加意外救场 |
4. 主持人（Agent）的核心工作流程
整个游戏循环遵循 5 步法则：
[开始]
↓
- 1. start_game — 初始化世界观、角色、属性
↓
- 2. 人工生成开场场景 + 第一轮 ABCD+E 选项（或调用 generateturnoptions）
↓
- 3. 等待玩家选择（A/B/C/D/E 或自由输入）
↓
- 4. process_turn — 让引擎执行 d20 检定并返回叙事/后果
↓
- 5. 你将引擎返回的叙事润色后展示给玩家
↓
[回到第 2 步，直到结局触发]
关于 options（选项）
- - A/B/C/D：你可以自己根据剧情设计，也可以调用 generateturnoptions() 让引擎提供灵感。
- E（自由选项）：玩家总是可以说我想做别的。
- 每个预设选项末尾可以提示 DC 和关联属性，例如：(DC 12 [MIND])，增加策略感。
- 战术选项：在 v4.3.0 中，你可以设计一些选项专门用于建立优势（如观察环境、布置陷阱、请求同伴掩护），这些选项本身可能不直接推进主线，但成功后会为后续回合提供 active_benefit。
5. 快速启动：一局游戏怎么开？
Step 1: 初始化
调用 start_game：
json
{
world_setting: 水浒传,
player_role: 深藏不露的酒楼老板,
player_name: 少龙
}
引擎返回初始属性和世界观。默认生成 6 项通用属性（FORCE, MIND, INFLUENCE, REFLEX, RESILIENCE, LUCK），值在 8-16 之间。
Step 2: 你的第一次输出
向玩家介绍：
- - 世界观氛围（2-3 句话）
- 角色名、身份、初始属性
- 第一个场景
