前言¶

在 Agent 里做文字冒险，常见问题是「聊得很顺，档却乱了」：回合数、精力、NPC 好感靠模型记忆，多轮之后和 state.md 对不上；或者叙事里说了「体力 -2」，文件里却没改。纯提示词很难长期约束这类细节。

下面介绍的 Skill 把分工写进协议：严格格式与状态变更走 engine.py 命令；世界观、剧情、对白由 LLM 自由发挥。游戏数据落在 Markdown 文件里，Agent 按 SKILL.md 规定的顺序读写，而不是口头宣布状态已变。

这是什么¶

MarkDown 驱动的 LLM 文字冒险引擎（SkillHub 坐标 @user_b591212e/md-game，当前版本 1.0.2）是社区发布的 ai-agent 类 Skill，发布者为 user_b591212e，来源标注为 community。官方一句话简介：LLM 文字冒险引擎。严格格式→命令保证，联想构思→AI 自由。

SkillHub 页面显示：评分 100000，下载 760 次；标签 requires_api_key=false，安装本 Skill 本身不依赖额外 API Key（游戏仍需要你所用 Agent 的大模型能力）。

• Skill 详情页：https://www.skillhub.cn/skills/user_b591212e/md-game
• API 条目：https://api.skillhub.cn/user_b591212e/md-game

核心功能¶

以下能力来自 Skill 包内的 SKILL.md 与 scripts/engine.py，经安装核对。

文件架构与「唯一真相源」¶

每个存档对应一个游戏目录（由 engine.py 在 Skill 下的 games/ 中管理），典型结构为：

{game_dir}/
├── game.md   # 世界、规则、NPC、角色（区块标记，按需读取）
├── state.md  # 快照，每回合必读必写
├── log.md    # 日志（倒序，超过 10 条可压缩）
└── .bak/     # 自动备份（保留最近 5 份）

state.md 被定义为唯一真相源；Agent 每回合必须先 read --hot，再叙事，再用 turn 写入变更。SKILL.md 明确：口头叙述不等于状态生效，turn 是唯一的状态修改途径。

Python 引擎命令¶

scripts/engine.py 提供：

game.md 使用 HTML 注释区块标记，例如 <!--§世界设定§-->…<!--§/世界设定§-->，NPC 为 <!--§npc:名字§-->…<!--§/npc:名字§-->。模板 templates/game-template.md 内带判定表、生存/经济/NPC 自主等规则骨架，供 setup 填充。

Agent 行为协议（SKILL 铁律摘要）¶

SKILL.md 对承载游戏的 Agent 约定了硬性流程，例如：

1. 开局必须走「询问玩家 → init → setup（--npcs 至少 1 个 NPC）→ 开场叙事 → 首次 turn」。
2. 每回合：read {游戏名} --hot → 叙事与判定 → turn 写入 → 再按固定格式回复玩家（叙事、NPC、建议、状态变更、场景等）。
3. 不替玩家做决定；判定需查属性与难度表，不跳过直接给结果。

触发关键词在元数据中包括：玩游戏、开一局、穿越、冒险。

安装与启用¶

方式一：让 Agent 按 SkillHub 指引安装¶

SkillHub 页面给出的提示为：根据 https://skillhub.cn/install/skillhub.md ，安装 @user_b591212e/md-game。

方式二：SkillHub CLI¶

先确认是否已安装 CLI：

command -v skillhub && skillhub --version

未安装时可执行（完整安装，含默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装本 Skill 时，必须用 --dir 指向当前 Agent 的 skills 目录（装到默认 ./skills/ 可能不会被识别）。官方文档中的常用路径示例：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

安装命令（与 skillhub search 输出一致）：

skillhub install md-game --namespace user_b591212e --dir ~/.cursor/skills/

将 ~/.cursor/skills/ 换成你所用客户端的实际 skills 目录即可。安装后按各客户端要求重启或刷新 Skill 列表。

典型用法¶

以下示例摘自 SKILL.md，路径相对于 Skill 根目录；{游戏名} 替换为你的存档名。

1. 开局¶

先向玩家确认世界观与角色，再执行：

python3 scripts/engine.py init {游戏名}

一键填充（setup 必须带 --npcs，每行一个 NPC，字段用 | 分隔）：

python3 scripts/engine.py setup {游戏名} \
  --world '时代:宋朝\n地理:...' \
  --hero '姓名:赵二狗|种族:人|职业:商人|背景:...' \
  --attrs '力3敏5体4智6魅7' \
  --start '兰陵城西市' \
  --atmosphere '喧闹市井' \
  --npcs '王掌柜|西市|正常|15|商会执事
张屠户|西市|正常|5|肉铺老板'

输出开场叙事后，必须执行首次 turn：

python3 scripts/engine.py turn {游戏名} --action '开场:来到起始地' --recent '开场叙事'

--world、--hero 等内容支持 @file 从文件读取。

2. 每回合循环¶

python3 scripts/engine.py read {游戏名} --hot

叙事与判定完成后写入状态（只传变化的字段）：

python3 scripts/engine.py turn {游戏名} --action '行动摘要' --location '新位置' --recent '近事摘要'

常用 turn 增量参数包括 --atmosphere、--weather、--time-advance、--items、--npc-relations、--tense（紧张回合精力额外 -2）等；回合数、默认精力消耗、时间推进等由引擎自动计算。

3. 读取与维护¶

python3 scripts/engine.py read {游戏名} --npc 老陈
python3 scripts/engine.py read {游戏名} --section 世界设定
python3 scripts/engine.py compress {游戏名} --story '故事概要:...'
python3 scripts/engine.py rollback {游戏名}

state.md、scene、日志的更新应走 turn，不要用 write 替代。

适用场景与注意¶

适合谁

• 希望在 Cursor、Claude Code、Codex 等支持 Skill 的 Agent 里跑可存档、可回滚的 LLM 文字冒险或互动叙事原型。
• 愿意用 Markdown + 少量 Python 命令约束状态，而不是全靠长上下文记忆。
• 需要 NPC 列表、判定表、精力/耐力等轻量 RPG 规则骨架，再由模型填剧情。

限制与注意

• 体验依赖 Agent 是否严格遵守 SKILL.md 铁律；若跳过 read/turn，会出现叙事与文件不一致。
• 引擎为本地文件操作，需保证 Agent 有权限在 Skill 目录下执行 python3 scripts/engine.py 并写入 games/。
• SkillHub 统计中的「安装」与「下载」可能不一致，以页面实时数据为准；本文写作时下载量为 760。
• 未在官方资料中单独说明 Windows/macOS 差异；setup 示例使用 python3，环境需自带 Python 3。

结尾¶

MarkDown 驱动的 LLM 文字冒险引擎把「状态与格式」交给 engine.py 和 Markdown 文件，把「联想与叙事」留给大模型，适合在 Agent 里做可维护的文字冒险实验。安装与详情见 SkillHub：

https://www.skillhub.cn/skills/user_b591212e/md-game