基于 Pi coding agent 的角色扮演运行时。项目将世界设定、GM 裁定、状态推进、Writer 正文生成、存档回退和 OpenViking 长期记忆组合成一套可替换世界包的工作流。
当前版本仍在快速迭代，适合本地体验和二次开发，不保证配置与存档格式向后兼容。
| 模块 | 能力 |
|---|---|
| 世界包 | 用 YAML、Markdown 和可选 TypeScript System module 定义世界、初始状态、提示词、资料、角色、写作规则与 Hook；GM / Writer 的 prompt 可自定义为带 role 的有序消息链 |
| 状态 | SQLite 持久化玩家、场景、时间、自定义属性及独立 System state |
| GM / Writer | GM 负责裁定和状态推进，Writer 负责玩家可见正文，避免写作阶段改写确定性状态 |
| 存档 | 提供 /save、/load、/roll，按成功故事回合保存完整状态快照 |
| 子代理 | 支持世界角色、动态角色和角色专属行为工具 |
| 长期记忆 | 可选接入 OpenViking；当前状态仍以 SQLite 为准 |
运行链路：
玩家输入
-> GM 读取状态、固定资料和长期记忆
-> GM 调用角色子代理并推进 Core / System state
-> GM 提交 story elements
-> Writer 生成并修订正文
-> 正文交付后记录 story snapshot
-> Hook 与 OpenViking 异步处理后续工作
- Node.js 22.19 或更高版本（推荐 Node.js 24）
- npm
- 可在
PATH中调用的 Pi coding agent CLI - OpenViking 服务（可选，仅长期记忆需要）
安装 Pi CLI：
npm install --global @earendil-works/pi-coding-agentgit clone https://github.com/lyfmt/rp4pi.git
cd rp4pi
npm ci
cp .env.example .env
./start.sh首次启动会从 .pi/agent/settings.example.json 生成本地的 .pi/agent/settings.json。请将其中的 provider、model 和 thinking 配置改为当前 Pi 环境可用的值。本机已有 ~/.pi/agent/auth.json 时，启动脚本会将其复制到项目的本地配置目录；这些本地认证文件不会被 Git 跟踪。若本机没有现成的 Pi 认证，进入交互界面后先执行 /login 登录。
cp .env.example .env 生成的配置默认已禁用 OpenViking（RP_DISABLE_OPENVIKING=1），全新检出无需本地 OpenViking 服务即可运行。需要长期记忆时，注释掉 .env 里的该行并配置 OPENVIKING_URL（见下方「配置」）。
启动后输入：
开始新游戏。
进入的世界由启动时的 RP_WORLD 决定（见下方「配置」），默认是 worlds/ 下按字母序第一个非 _ 开头的世界。
OpenViking 连接参数可写入本地 .env：
| 变量 | 默认值 | 用途 |
|---|---|---|
OPENVIKING_URL |
http://127.0.0.1:1933 |
OpenViking 服务地址 |
OPENVIKING_API_KEY |
空 | API Key |
OPENVIKING_ACCOUNT |
空 | 账户隔离标识 |
这三项也可写在 .pi/agent/settings.json 的 openViking 字段（url / apiKey / account）。两处同时存在时以 .env / 环境变量优先，settings.json 仅作回退。
其他常用运行参数通过环境变量传入：
| 变量 | 默认值 | 用途 |
|---|---|---|
RP_WORLD |
首个非 _ 开头的世界目录 |
选择 worlds/<name>/ |
RP_SQLITE_PATH |
data/rp.sqlite |
SQLite 状态文件位置 |
RP_DISABLE_OPENVIKING |
1（.env.example 默认设置） |
设为 1 禁用长期记忆连接；启用 OpenViking 时注释掉 .env 里的该行 |
RP_AGENT_ENV_FILE |
.env |
指定 OpenViking 环境配置文件 |
模型可直接在运行中的输入框配置：
/model：切换当前 GM 主模型（Pi 原生命令）。/rpconfig：先选择 Writer、文风增强、惯性审稿、八股审稿或当前世界的静态/动态子代理，再选择目标模型。
/rpconfig 只列出 Pi 中已认证可用的模型，结果写入 .pi/agent/settings.json；已有 thinking 档位和其他设置保持不变。Writer 从下一次渲染起生效，子代理配置写入后立即重新物化。
密钥只应放在 .env、环境变量或 .pi/agent/ 下的本地文件中，不要写入世界包、源码或 Issue。
默认示例是 worlds/border-station/。创建自己的世界：
cp -r worlds/_template worlds/my-world
RP_WORLD=my-world ./start.sh世界包字段和扩展方式见 world-pack 指南。
支持从 SillyTavern 角色卡（PNG / WEBP / JPEG / JSON）迁移。在 Pi 会话里让 agent 使用 migrate-st-card 技能，可按需要提取、审计、改写或省略卡片内容，并自由映射为世界包模块。角色卡提取脚本已收编在 skills/migrate-st-card/scripts/（需 Python >= 3.10）。迁移产物可放在 worlds/<name>/ 世界包中。
npm run typecheck
npm test
npm run validate-world
bash scripts/smoke-demo.sh
bash scripts/smoke-writer-live.shnpm run validate-world 严格校验 worlds/ 下所有世界包（可传世界名只校验一个），任一世界加载失败即以退出码 1 结束。smoke-demo.sh 会执行类型检查、全量测试、扩展启动检查，并在 OpenViking 可达时验证真实的 append / commit 流程。smoke-writer-live.sh 会调用真实模型；可通过 RP_WRITER_LIVE_SMOKE=0 跳过。
运行中的 Slash Commands：
| 命令 | 作用 |
|---|---|
/status |
查看当前玩家、地点、时间和场景 |
/save |
保存并返回 save id |
/load |
切换当前 Pi session 绑定的存档 |
/roll |
回退到上一成功 story snapshot 并重跑当前输入 |
/rpconfig |
选择并修改 Writer、修订阶段或 RP 子代理使用的模型 |
| 路径 | 内容 |
|---|---|
extensions/ |
Pi 扩展入口 |
src/ |
运行时、状态、工具、命令、System 与 OpenViking 集成 |
worlds/ |
世界包模板和可运行示例 |
.pi/agents/ |
Writer 提示词与启动时物化的世界子代理（role 与 tool 两类；GM 提示词在各世界包 prompts/ 下） |
skills/ |
启动、开发、角色生成和迁移技能 |
test/ |
单元、契约和端到端测试 |
docs/design/project-control-plane.md |
当前实现、约束和里程碑的权威说明 |
更完整的演示说明见 docs/demo.md，当前能力边界见 项目控制面。贡献前请阅读 CONTRIBUTING.md；安全问题请按 SECURITY.md 私下报告。