Open-source agent skill中文小说 → 可玩网页游戏

把一本中文小说,
做成能玩的游戏。

不是让模型一句话生成游戏,而是一条可核查的流水线:清洗切章、逐章抽取、人物归并、知识账本、分阶段角色卡、玩法模拟、3D 场景。每一环都有量化门槛与人工核对过的金标;NPC 只能知道自己当时知道的事。

10个步骤
8道门槛
38个离线测试
MIT许可
01

它产出什么

What it makes
01 / READ

正史回放

按账本里的场景逐场读原文,对白标注说话人,场景切换带动 3D 画面与节点地图。主线始终是原著。

02 / CHOICE

关键处抉择

每个锚点停一次。原著做法是 canon,其余是处境下合理的别的做法,各有得失、后果旁白,再用一段 bridge 接回原著。

03 / MANAGE

用书里的单位经营

2–4 个属性、一个阶段目标、每章末的空闲行动、明确的失败结局。钱就写书里的钱数,不用 0–100 的空泛评分。

04 / INTEL

说出口才算情报

找 NPC 打听,对方真的把要点说出来才解锁之后某个抉择里更好的选项;吊胃口、卖关子不算。

05 / TALK

有边界的角色

人设来自上一个已结束阶段的角色卡,记忆来自账本,回答里出现玩家没提、且更晚才登场的名字会被打回。

06 / LOOK

离线可用的 3D

three.js 低多边形实时渲染:人物有心情与姿势,地点按参数生成,锚点有定格。AI 图是可选增强,不是前提。

游戏的主线始终是原著;玩家走偏时,由旁白把他接回下一场。 Soft regression
02

三层分工

Architecture
LAYER 01

框架

n2g/

只放对所有中文小说都成立的机制:编码识别、切章、抽取提示词与校验、人物归并、知识账本、角色卡、引擎、NPC 运行时、3D 渲染、门槛。不含任何一本书的词、名或阈值。

LAYER 02

每一本书

games/<slug>/

书型、词表、噪声 / 合并 / 知情 / 地点四类规则、抽取说明、插件、人工金标、笔记;build/ 下是全部产物,可随时重建。

LAYER 03

作业手册

SKILL.md + stage*.md

九份阶段说明与一份问题模式库:每阶段怎么跑、看哪个指标、抽查什么、遇到问题修在哪一层。智能体照它干活,人照它验收。

修复落点:从上往下找第一个能解决的位置

  1. 1书型profile
  2. 2词表vocab.json
  3. 3规则noise / merge /
    knowledge / place
  4. 4抽取说明extract_guide.md
  5. 5插件plugins/*.py
  6. 6框架n2g/

同一个问题,先判断它属于哪一层,写在最上面能解决它的地方。框架层只有在两本以上的书里都遇到、并且能用通用规则解决时才改;改完在所有书上回归。

03

架构总图

Architecture map
技术架构总图:控制面、批处理十步、产物链、运行时

左右滑动查看全图

四条横向带:控制面决定按哪个阶段干活、过哪道门槛;批处理是十个步骤,实心点表示这一步要调用模型、计入额度;产物是 build/ 下的数据契约,任何一步都能从上游重建;运行时用同一个 engine.py 同时服务网页和模拟器。虚线是外部依赖或可选增强。

04

流水线

Pipeline · 点开看每一步

需要 API key 与额度离线免费

每一步都先看指标再过门槛。gate 记录指标与该阶段输入的哈希;改了规则或代码,status 会把受影响的阶段标成 stale——旧的“通过”不算数。

05

为什么可信

Why trust it
01

证据优先

实体名必须在本章原文出现;每条事实附逐字引文;每个引号必须有说话人。不满足就退回模型重做,三轮不过标 unverified,下游(账本、角色卡、NPC 记忆)不当证据用。

02

门槛 · 金标 · 过期指纹

八道门槛各有量化指标;金标是人工对照原文确认过的判断(这句谁说的、是不是同一个人、某章在不在场),每次重建自动复查。改了东西,过期检测告诉你哪一步要重跑。

03

分层修复

六个落点,从上往下找第一个能解决的。写进框架的修复会污染所有书,所以框架层要两本书都遇到才动,动完全量回归。

04

通用性由测试强制

一个守卫测试拿每本书的 S/A 级人名、别名、常用地点,反向扫描框架、测试和文档——往框架里写某本书的词,测试会当场失败。

05

玩法可验证

模拟器与网页共用同一个引擎,跑三类玩家:永远选原著(必须活到最后)、按权重规划(必须能赢)、随机(必须可能输)。数值不对就让模型改,最多三轮,留最好的一版。

06

可见性约束

NPC 回答前只给四样东西:已结束阶段的角色卡、账本里他此刻知道的事、当前场景与玩家已读原文、玩法层的好感与情报。回答后再拦一次“未来名字”。

10Steps
8Gates
38Offline tests
6Fix layers
06

技术栈与仓库

Stack
chinese-novel-to-game/
├── SKILL.md              agent 入口:原则、落点表、阶段总览
├── stage0…stage8*.md     9 份阶段手册
├── patterns.md           问题模式库
├── NOTICE.md             法律声明
├── n2g/                  框架,42 个 .py
│   ├── text/             清洗 · 切章 · 引号 · 噪声
│   ├── extract/          逐章抽取与校验
│   ├── consolidate/      人物归并 · 分词词典
│   ├── knowledge/        角色卡 · 账本 · 地点
│   ├── game/             引擎 · NPC · 设计 · 模拟 · 3D
│   └── art/              可选:AI 图
├── tests/                38 个离线测试
└── examples/             自写 5 章示例(CC0)
  • Python 3纯标准库 + 少量依赖;在 3.13 上验证,无数据库、无消息队列,全部是文件。
  • httpx异步客户端:磁盘缓存、重试、单次运行预算上限、JSON 修复。密钥只从环境变量读。
  • FastAPI本地服务只监听 127.0.0.1;存档在服务端,刷新不丢。
  • jieba分词与每本书的自定义词典,用于人物归并和记忆检索。
  • three.js随仓库附带,无 CDN、可离线;所有外观都是枚举参数,校验器把不认识的值换成默认并记录。
  • BM25NPC 记忆默认用 BM25 + 本书词典排序;可选本地句向量,缺省下完全可用。
07

快速开始

Get started
  1. 装好环境

    克隆、虚拟环境、依赖,然后把密钥写进 .env。任何 OpenAI 兼容的接口都可以。

  2. 先用示例跑通 ⓪①

    仓库自带 5 章自写文本,清洗、切章、书型诊断都不调用模型,不花钱。

  3. 换成你的书

    长篇先做切片:在 book.json 写 "pilot": "0:30",只在 20–30 章上走通全流程,估好费用再放开。

  4. 玩

    python -m n2g play --slug demo,浏览器打开 127.0.0.1:8765。

测试全部离线,不读 .env,不需要模型:pytest -q。⓪① 免费;从 ② 起需要 API key 与额度,所有付费命令都支持 --budget。

git clone https://github.com/NorwinYu/chinese-novel-to-game.git
cd chinese-novel-to-game
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env       # 填 base_url / api_key / model

python -m n2g init examples/demo-novel.txt --slug demo --title 示例
python -m n2g ingest  --slug demo
python -m n2g profile --slug demo

# 之后按阶段往下,每步先过门槛
python -m n2g extract   --slug demo --chapters 0:30 --budget 1
python -m n2g gate extract --slug demo