narraeon

v0.5.3

Published

4 days ago

A local-first workspace for living worlds.

0High
0Medium
0Low

llwwbb

ai rpg local-first storytelling

Narraeon

简体中文 | English

Narraeon 是一个用于开放式 AI 角色扮演的本地优先工作区。你用易读的 YAML 和 Markdown 文件搭好世界，连接自己想用的模型服务，再通过浏览器连接同一台机器上的 Runtime 开始玩。

模型负责故事语义：扮演人物、回应玩家行动、按需读取世界材料，并提出需要持续保存的变化。Runtime 负责不应该交给模型记忆的部分：验证文件操作、保存精确的已提交叙事、维护不可改写的历史、故障恢复，以及创建彼此独立的世界分叉。

Narraeon 提供什么

**文件原生的世界。**人物、地点、规则、当前情境、开场白和世界专属指令都是普通 YAML／Markdown 文件。
**可持续的连续性。**重要变化会写回自然承载它的文档；玩家和主持的精确原文则作为叙事历史提交。
**模型主导的游玩。**同一条调用链里，模型可以叙事、读取额外材料，也可以通过 Runtime 工具更新世界文档。
**可检查的提示词。**Prompt Preview 直接展示真实的逻辑 role、选中材料、工具定义、Provider 映射和缓存边界，不会调用模型。
**不破坏旧历史。**修改早期玩家行动会调整当前时间线，但不删除旧 Authority 记录；“创建分叉”则会得到一个可以独立演化的新世界。
**数据归你所有。**世界、配置、凭据、提示词、历史和恢复数据都保存在本机。模型请求只会发往你明确配置的 Provider 端点。

运行要求

Docker Engine／Docker Desktop，或 Node.js 24.12.0 或更高版本，二选一
现代浏览器
如果要进行 AI 游玩或设定完善，还需要与以下任一适配器兼容的模型端点和 API 凭据：
- OpenAI Responses API
- OpenAI 兼容的 Chat Completions
- Anthropic Messages

Narraeon 内置了多家 Provider 的连接预设，也允许手动填写自定义端点。建议选择工具调用能力稳定的模型。

快速启动

无需全局安装，直接运行已发布的 Web 应用：

npx narraeon web

Narraeon 会在 http://127.0.0.1:4317 启动并打开默认浏览器。使用期间需要保持终端进程运行；按 Ctrl+C 停止服务。

常用选项：

npx narraeon web --port 4318
npx narraeon web --no-open
npx narraeon --help

服务只监听 127.0.0.1。如果选定端口已经运行兼容的 Narraeon，CLI 会直接复用；如果端口被其他程序占用，启动会明确失败，不会连接未知服务。

也可以直接运行 GitHub Container Registry 上的发布镜像：

docker run --detach --name narraeon \
  --publish 127.0.0.1:4317:4317 \
  --volume narraeon-data:/var/lib/narraeon \
  ghcr.io/narraeon/narraeon:latest

然后打开 http://127.0.0.1:4317。命名卷会在重建容器后继续保留世界、配置、凭据、日志和恢复数据。宿主机一侧应继续绑定 127.0.0.1；绑定所有网卡会把本地单用户 Runtime 不必要地暴露出去。Narraeon 当前不内置 Web 认证或访问控制，只应运行在回环地址或受信任私网中；在统一安全模型设计完成前，不支持暴露到公网。稳定版会移动 latest，预发布版会移动 next，每次发布还会保留精确版本标签。

从源码运行

git clone https://github.com/narraeon/narraeon.git
cd narraeon
npm ci
npm run build
npm start

然后打开 http://127.0.0.1:4317。如果想通过已构建的 CLI 启动，而不是直接运行源码服务：

node dist/node/cli/main.js web

首次使用

**选择界面语言。**在顶部切换语言，选择会保存在本机。它会改变界面和 Runtime 自带的默认提示词，但不会重写你已经保存的内容或自定义提示词。
**配置模型连接。**打开“模型连接”，选择 Provider 预设或自定义端点，填写 API Key、模型 ID，以及模型真实的上下文窗口和最大输出限制。保存时会同时启用这份连接。

**准备内容包。**新建一份空白内容包，或者导入 ZIP。内容包是世界模板，不是正在游玩的存档。它主要包含：

opening.md                 玩家首次看到的故事正文
world/                     初始人物、地点、规则和当前情境
control/frame.yaml         决定提示材料的确定性编排
control/blocks/*.md        只属于这个世界的指令
control/player-views.yaml  故事旁边常驻显示的信息

**手工编辑或让模型完善设定。**你可以直接编辑文件，也可以让模型先生成一份可见计划，再在隔离候选中创作。必须先审阅完整文件差异并明确接受，AI 修改才会生效。
**检查玩法预设。**系统自带的默认预设可以直接使用，并会跟随当前语言。预设包含可复用的主持方法、叙事提示、后置请求和可选界面扩展。
**创建世界。**可用的内容包可以复制成一个独立世界。之后继续修改源内容包，不会改动已经创建的世界。

怎么玩

打开世界后，已提交的故事是页面主体，玩家视图则在旁边常驻显示。写下你的角色准备做什么、说什么，或者作出什么决定，然后选择这次怎样发送：

| 操作 | 会做什么 | 不会做什么 | | ---------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- | | 全新上下文 | 从世界当前端点、当前提示词、选定材料和近期叙事重建模型上下文，再追加新的玩家原文。 | 不会清空世界、页面上的故事或已保存的调用链历史。 | | 追加上下文 | 继续当前模型 transcript，并追加新玩家原文。没有既有上下文时，会自动按全新上下文开始。 | 当前上下文仍然活跃时，不会重新编译世界 bootstrap。 | | 空输入时追加 | 上次请求中断时，原样重发已保存的 Provider 请求；上次响应完整时，从当前 transcript 继续生成。 | 不会偷偷补一条玩家指令，也不会提交空玩家消息。 |

响应会实时流式显示在页面上。模型可以直接叙事、精确读取一份文档或历史、更新世界文档、创建文档，也可以组合叙事和工具调用。工具调用只会修改未提交候选；Runtime 验证后才会接受并提交结果。后续 Provider 请求失败，也不会撤销前面已经提交的结果。

跨上下文保持连续

Narraeon 不依赖一段无限增长的聊天。全新上下文会从当前世界重新编译，已提交叙事和重要文档变化仍然作为持久连续性保留。短期场景细节可以留在近期叙事里；一旦忘掉就会导致明显矛盾的事实，则应当写进相关人物、地点、物品、规则或当前情境文档。

调用链面板保留真实请求轨迹供检查：玩家消息、模型正文、Runtime 工具及结果、usage、失败，以及 Provider 真实返回的 reasoning。内部处理过程不会被写成故事正文。

修改、修正和分叉

| 操作 | 结果 | | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | 修改已提交的玩家消息 | 留在当前世界。Narraeon 从这条消息的逻辑父端点追加一笔时间线修订，再从修改稿继续。旧 Authority 记录仍可恢复。 | | 创建分叉 | 把选中的 Authority 前缀复制成一个全新的独立世界。来源世界不变，两个世界之后可以分别继续。 | | 连续性修正 | 在故事之外明确修正当前文档，以新提交保存，不会假装这笔修正是剧情内发生的事。 |

内容包与设定完善

内容包在创建世界前可以自由编辑。你可以保留多份内容包、复制、导出 ZIP，或者导入新包，不会覆盖已有的本地身份。

AI 设定完善只作用于内容包候选。在“先生成计划”的路径中，模型会先读取选定材料并给出可见的创作计划，然后才开始修改；你也可以明确跳过计划。两条路径都必须通过文件、引用、控制、玩家视图和真实 Prompt Preview 检查，才能作为一笔原子的内容包更新应用。已经创建的世界永远不会被内容包完善改动。

更详细的创作方法见 docs/content-package-setting-authoring.md。

语言行为

默认界面语言为英文。切换到简体中文后，以下内容会同步改变：

Web 界面；
Runtime 自带的默认主持提示和叙事提示；
Runtime 工具说明和工具使用契约；
新建空白内容包时使用的初始文件。

已有内容包、世界、导入预设、复制预设和用户编辑过的提示文件不会被自动翻译或重写。

本地数据与隐私

Narraeon 默认使用当前操作系统的标准用户应用目录。如果要隔离一份独立实例，或者自行指定存放位置，可在启动前设置：

| 环境变量 | 用途 | | ---------------------- | ---------------------------------- | | NARRAEON_DATA_ROOT | 内容包、世界、Authority 历史和产物 | | NARRAEON_CONFIG_ROOT | 模型连接、应用偏好和玩法预设 | | NARRAEON_LOG_ROOT | Runtime 日志和 AI 失败诊断 | | NARRAEON_PORT | 本地 Web 端口，默认为 4317 |

容器镜像把前三类存储目录统一放在 /var/lib/narraeon 下，因此 Docker 示例只需要持久化这一个目录。

默认情况下，浏览器只与同机 Runtime 通信。“本地优先”不等于远程模型推理也离线：提示词、选中的世界材料、工具交换和生成文本会发送到你配置的 Provider。API Key 保存在本地配置中，保存后不会再返回给浏览器。

发生 Provider、响应格式、Runtime 工具或候选检查错误时，Narraeon 会在 NARRAEON_LOG_ROOT/ai-failures 下创建 JSONL 事故记录。它会保存原始 Provider 交换和后续恢复尝试，包括 Provider 真实返回的 reasoning／thinking。它不会伪造隐藏思考，也不会记录 API Key 和请求 header。不过日志仍可能包含私密提示词、世界内容、工具参数和 Provider 返回的思考，因此应当把该目录视为敏感数据。

仓库开发

npm ci
npm run build
npm run check
npx playwright install chromium
TMPDIR=/tmp npm run test
TMPDIR=/tmp npm run test:package

npm run test:package 会生成真实 npm tarball，在仓库外的临时目录安装，再检查发布版 CLI、健康端点、首页和重复启动行为。

项目契约与架构文档：

CONTEXT.md —— 领域词汇
docs/product-foundation.md —— 当前 V1 产品契约
docs/adr/ —— 架构决策

License

Apache-2.0