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）

绝对禁止的行为

❌ 禁止自行脑补骰子结果：你不能根据"剧情需要"或"玩家体验"自行决定成功或失败。

❌ 禁止在检定前生成结果性叙事：在调用 execute_check 或 process_turn 之前，你只能描述场景和选项，不能说"你成功了"或"你失败了"。

❌ 禁止覆盖骰子结果：即使骰子显示"大失败"，你也不能写成"虽然失败了但意外有好事发生"。

3. 【强制】自动保存机制（v4.4.0+）

保存行为已被引擎接管

每回合 process_turn 返回时，自动保存已经由引擎强制执行完成。

你不需要、也不应该自己决定"是否要保存"。保存是引擎层的强制行为，不是你的决策。

process_turn 返回的保存信息

{
  "turn": 3,
  "action": "我说服守卫放我过去",
  "narrative": "...",
  "auto_save": {
    "save_id": "auto_turn_3_1712567823",
    "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. 【必须】调用 process_turn（内部自动执行 analyze + execute_check + narrative）
   ↓
4. 向玩家展示完整结果

使用 execute_check 的示例

当需要单独控制检定流程时：

// 第1步：分析行动（可选，用于预览DC）
// analyze_action
{"action": "我说服守卫放我过去"}
// 返回: {"primary_attribute": "INFLUENCE", "base_dc": 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 一步完成：

// 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 选项（或调用 generate_turn_options）
  ↓
3. 等待玩家选择（A/B/C/D/E 或自由输入）
  ↓
4. process_turn — 让引擎执行 d20 检定并返回叙事/后果
  ↓
5. 你将引擎返回的叙事润色后展示给玩家
  ↓
[回到第 2 步，直到结局触发]

关于 options（选项）

• A/B/C/D：你可以自己根据剧情设计，也可以调用 generate_turn_options() 让引擎提供灵感。
• E（自由选项）：玩家总是可以说"我想做别的"。
• 每个预设选项末尾可以提示 DC 和关联属性，例如：(DC 12 [MIND])，增加策略感。
• 战术选项：在 v4.3.0 中，你可以设计一些选项专门用于“建立优势”（如观察环境、布置陷阱、请求同伴掩护），这些选项本身可能不直接推进主线，但成功后会为后续回合提供 active_benefit。

5. 快速启动：一局游戏怎么开？

Step 1: 初始化

调用 start_game：

{
  "world_setting": "水浒传",
  "player_role": "深藏不露的酒楼老板",
  "player_name": "少龙"
}

引擎返回初始属性和世界观。默认生成 6 项通用属性（FORCE, MIND, INFLUENCE, REFLEX, RESILIENCE, LUCK），值在 8-16 之间。

Step 2: 你的第一次输出

向玩家介绍：

• 世界观氛围（2-3 句话）
• 角色名、身份、初始属性
• 第一个场景：将玩家置入一个有冲突的情境中
• 选项 A/B/C/D + E

6. 处理玩家回合

当玩家做出选择后

用 process_turn 传递玩家的行动描述：

{
  "player_input": "我笑着给张捕头倒酒，暗中塞给他银子拖延时间"
}

引擎内部会：

1. 分析意图 → 确定主属性（比如 INFLUENCE）和 DC
2. 掷骰子 → d20 + 修正 >= DC
3. 返回叙事 + 后果（JSON）
4. 自动更新 GameState

你应该怎么展示结果？

推荐格式：

━━━━━━━━━━━━━━
【d20 检定】魅力 +2 = 14 + 2 = 16 (DC 12) → 成功！
━━━━━━━━━━━━━━

你笑眯眯地迎上去，三碗烈酒下肚，张捕头的眼神开始发飘……
（此处展开 150-300 字的剧情描述）

【状态更新】
- 财富: 100 → 70 (-30)
- 获得标签: 长袖善舞
- 张捕头 态度变为: 收了银子仍猜忌

注意：如果 show_dice=True（默认），引擎会直接返回完整的骰子结果，你可以原样展示。

7. d20 检定制：这是不可违抗的物理法则

公式

d20 + (属性 - 10) / 2（向下取整） >= DC

结果程度（叙事必须严格遵守）

六项通用属性

8. 战术增强系统（v4.3.0）

v4.3.0 在单回合 d20 框架内引入了 加成链 机制。玩家可以通过前置行动积累 active_benefits，在关键时刻一举释放，提升策略深度。

6.1 三大战术来源

6.2 active_benefit 的结构

每个加成包含：

• name: 加成名称（如“居高临下”）
• description: 描述
• dc_modifier: DC 修正（通常为负数，如 -3 表示降低 DC）
• advantage: 是否提供优势（优势 = 掷两颗 d20 取高）
• applies_to: 适用的属性列表（空数组表示适用所有属性）
• remaining_uses: 剩余使用次数（默认 1）

6.3 计算有效 DC 与优势

在玩家决定执行最终行动前，调用 calculate_effective_dc：

{
  "base_dc": 15,
  "attribute": "FORCE"
}

引擎会自动叠加所有符合条件的 active_benefits，返回：

• effective_dc: 最终 DC
• advantage: 是否有优势
• disadvantage: 是否有劣势
• applied_benefits: 本次生效的加成列表

然后，将计算结果传入 process_turn：

{
  "player_input": "我从房梁一跃而下，挥刀劈向敌首",
  "dc_modifier": -3,
  "advantage": true
}

注意：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. 存档管理

保存

{"save_id": "shaolong_001"}

加载

{"save_id": "shaolong_001"}

v4.2.0+ 引擎内置 _migrate_legacy_save()，v3.x 旧存档会自动迁移，无需额外处理。

12. 关键 API 速查

13. 完整示例：从开局到第一回合

初始化

// start_game
{
  "world_setting": "1960年代香港黑帮",
  "player_role": "卧底警察",
  "player_name": "阿超"
}

Agent 生成开场

游戏开始：1960年代香港黑帮
角色：阿超（卧底警察）
属性：FORCE 12 | MIND 14 | INFLUENCE 10 | REFLEX 13 | RESILIENCE 11 | LUCK 9

场景：九龙城寨的一家地下赌档里，你刚收到线报——今晚有人要"做掉"你的上线老鬼。

A. 不动声色，继续赌钱，同时找机会通风报信 (DC 14 [REFLEX])
B. 故意闹事，制造混乱让老鬼有机会脱身 (DC 12 [FORCE])
C. 直接亮出警徽制止火并 (DC 16 [INFLUENCE])
D. 你注意到角落里坐着社团红棍丧彪——他曾欠你一条命 (DC 10 [INFLUENCE]，需关系≥20)
E. 做其他你想做的事...

玩家选择

玩家：A

Agent 调用 process_turn

// process_turn
{"player_input": "不动声色，继续赌钱，同时找机会通风报信"}

引擎返回（示例）

{
  "check": {
    "roll": 15, "modifier": 1, "total": 16, "dc": 14,
    "degree": "成功", "success": true
  },
  "narrative": "你低下头继续摸牌，右手却在桌底悄悄将一张纸条塞给旁边的擦鞋童...",
  "consequences": {
    "tags_gained": ["沉着冷静"],
    "flags_set": {"老鬼已获救": true}
  }
}

Agent 润色后输出

（按第 4 节推荐的格式展示给玩家）

14. 战术示例：加成链的实际运用

场景：酒楼对峙

第 1 回合 - 环境互动

玩家选择：先悄悄把油灯挪到对方身后，让对方的影子暴露在我的视野中。

Agent 调用：

1. set_scene_objects 预先设置 [{"id":"oil_lamp","name":"油灯","description":"一盏黄豆大的油灯","interaction_hint":"可以移动位置改变光影","benefit":{"name":"光影掌控","dc_modifier":-2,"applies_to":["REFLEX","FORCE"]}}]
2. interact_with_scene_object 处理玩家的移动油灯行动。
3. 成功后，引擎返回该 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：

{
  "player_input": "趁他影子晃动的瞬间，从柜台后扑出去制服他",
  "dc_modifier": -2,
  "advantage": true
}

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