| name | pi-rp-engine |
| description | LLM-neutral roleplay engine as pi.dev extension — context assembly, card management, worldbook → Skill compilation |
| version | 1.0.0 |
PI RP Engine — pi.dev 扩展版
一个 pi.dev 扩展，提供角色扮演上下文装配、卡片管理、世界书→Skill 编译能力。
引擎本身不调 LLM，专注给 LLM 准备最优上下文。
安装
确保已安装 pi.dev (≥ v0.75)，然后在项目目录下：
cd pi-rp-engine
npm install
pi
工作原理
生命周期集成
pi.dev 事件 pi-rp-engine 扩展
──────────────────────────────────────────────────
session:start → 初始化 StateStore + Collector
input → 装配上下文，注入 system prompt
before:agent:start → 注入编译好的 Skill 文件
turn:end → Agent 管线 + 持久化 + 世界书→Skill
session:shutdown → 持久化 + 清理
世界书→Skill 编译（核心创新）
常开设定不直接拼入 prompt，而是编译为 pi.dev Skill 文件：
世界书 [常开]设定/
├── 规则类 → .pi/skills/rp-engine/00-core-rules.md
├── 文风类 → .pi/skills/rp-engine/style-protocol.md
├── 判定类 → .pi/skills/rp-engine/judgment-system.md
└── 变量类 → .pi/skills/rp-engine/variable-protocol.md
每轮 turn:end 自动重新编译，before:agent:start 注入。LLM 以"技能"形式原生理解这些规则，而非被动接收数据文本。
可用工具
| 工具 | 触发方式 | 作用 |
|---|
read_state | LLM 自动调用 | 读取角色状态变量 |
update_state | LLM 自动调用 | 更新角色状态（类型校验+钳制） |
advance_time | LLM 自动调用 | 推进游戏内时间 |
search_worldbook | LLM 自动调用 | 按关键词搜索触发词条（兼容旧式） |
可用命令
| 命令 | 作用 |
|---|
/card list | 列出所有已注册卡片 |
/card activate <id> | 激活卡片 |
/card deactivate <id> | 停用卡片 |
/status | 查看引擎状态 |
/reset | 重置当前 session |
/diag prompt | 查看上下文装配 trace |
角色扮演流程
每次用户发消息，pi.dev 自动执行以下步骤（无需手动操作）：
- input 事件 → 引擎装配上下文，注入 system prompt
- before:agent:start → 注入世界书编译的 Skill 文件
- LLM 生成回复（使用注入的上下文+技能）
- turn:end → Agent 管线 + 状态持久化 + 世界书重新编译
引擎全程自动运行，无需手动调 HTTP API。
架构
用户 → pi.dev
│
├─ 调 LLM（prompt = 引擎装配的上下文 + Skill 规则）
│
└─ pi-rp-engine 扩展（.pi/extensions/rp-engine/）
├─ lifecycle/ → session / input / turn 事件
├─ tools/ → read_state / update_state
├─ commands/ → /card / /status / /diag
└─ skill-injector → 世界书→Skill 编译
引擎层不调 LLM，专注上下文装配 + 状态管理 + 世界书→Skill。
