维护者指南
本节面向修改项目本身的开发者和编码智能体。插件开发介绍外部插件如何使用扩展点；本节说明怎样修改持久化、智能体协议和 DSH 集成而不破坏已有故事。
必须保持的不变量
- 世界文件是创作定义；会变化的故事状态属于会话 SQLite 数据库。
- 事件封存后不可修改；角色的感知和信念可以改变，但不能倒改事件。
- 知识采用封闭世界：没有关系或实体知识边，就表示角色不知道该实体。
- 智能体只能通过经过验证的工具修改状态；世界创作修改默认需要用户批准，明确启用自动模式时仍 使用同一套验证和可恢复文件写入。
- 文本交付不等待记录、世界整合、建议、离场行动或图片生成。
- 记忆年龄只按故事时间计算，不按回合数或现实时间计算。
- 媒体以文件系统为准；稳定路径和图片内嵌/伴随元数据就是可维护的索引。
- 同步单元传输期间不能被读写；两边发生分歧时必须由用户明确选择。
- 服务、监听器、插槽、路由和定时器都通过 Cordis
ctx注册，以便热重载清理。
包的职责
| 包 | 职责 |
|---|---|
dsh-roleplay-model | 规范类型、常量和跨包词汇；不做 I/O |
@dsh-agentic-roleplay/state | SQLite 架构与迁移、仓库、回忆、记录工具、快照 |
@dsh-agentic-roleplay/core | 文件世界、界面、会话、智能体循环、提示词、导入和图片 |
dsh-agentic-roleplay | Bundle 清单和 roleplay 智能体预设 |
不要在 core 和 state 各自重定义模型。私有 model 包必须被完整打包；构建后检查 JavaScript 和声明文件里没有悬空的 dsh-roleplay-model 导入。
一个故事模型功能只有在下列层次全部一致后才算完成：规范模型；迁移、行映射和仓库；会话初始化及快照；记录编辑协议、解析、JSON Schema、回读和 lint；记录员、角色、回忆与 GM 上下文；HTTP/界面；测试和中英文文档。
修改前以当前源码为准。通过已有解析器与仓库读写，不要直接改 JSON 或 SQLite；保留工作区内无关的用户改动，也不要复制第三方插件代码。文件协调与冲突处理见多设备同步。