# @dsh-agentic-roleplay/state 中文文档

规范地址：https://npmcn.com/package/%40dsh-agentic-roleplay/state/

版本：0\.12\.4
npm 元数据更新时间：2026-11-12T16:33:37.462Z
中文译文更新时间：2026-11-12T21:25:39.782Z
软件包许可：GPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dsh-agentic-roleplay/state
原文对照：https://npmcn.com/package/%40dsh-agentic-roleplay/state/?lang=original
项目主页：https://firefox2100.github.io/dsh-agentic-roleplay/docs/developers/state
源码仓库：https://github.com/Firefox2100/dsh-agentic-roleplay

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| \>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/dsh \>=0\.2\.2-rc\.1 \<0\.2\.3，@deepseek-ai/schemastery ^3\.18\.5
- 首次发布：2026-10-12T19:22:17.190Z
- 最新版本发布：2026-11-12T16:33:37.001Z
- 近 30 天下载量：6483（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

角色扮演会话状态的DSH插件:每会话一个SQLite数据库,作为服务于canonical模型而被其他插件所曝光.

## 安装

```sh
npm install @dsh-agentic-roleplay/state
```

也可以使用：`pnpm add @dsh-agentic-roleplay/state`、`yarn add @dsh-agentic-roleplay/state`、`bun add @dsh-agentic-roleplay/state`

## README

# @ dsh- 代理角色/ 状态

Firefox2100维护的DSH Agentic Lockersplay的持久性会话状态和内存服务.

大多数用户应安装 [`@dsh-agentic-roleplay/all`](https://www.npmjs.com/package/@dsh-agentic-roleplay/all)。当另一个DSH插件需要角色扮演数据库,寄存器,召回引擎,或者没有完整的角色扮演界面的模型化记录工具时,单独安装此包.

一个DeepSeek Harness 插件, 保持角色扮演会话状态: 一个 SQLite 每个会话的数据库,通过存储器与犬科模型连接。 这个 没有管弦乐,也没有UI,所以可以自行安装以获得一个 角色扮演数据库和状态管理没有其他角色扮演捆绑. 其他插件通过 `roleplayState` 服务。 建模工具 包含并可通过其配置启用.

需要 DSH 0.2 和节点 22.19 或 后期( 它使用内置) `node:sqlite`) (中文(简体) ).

```sh
dsh plugin --profile <name> add @dsh-agentic-roleplay/state
```

## 使用另一个插件

```ts
import type {} from '@dsh-agentic-roleplay/state'            // types `ctx.roleplayState`
import type { Context } from '@deepseek-ai/cordis'

export const inject = ['roleplayState']

export function apply(ctx: Context) {
  // Creates sessions/<uuid>/session.sqlite and opens it.
  const session = ctx.roleplayState.createSession('/path/to/sessions', {
    name: 'First night',
    world: { id: 'blackwater-observatory', name: 'The Blackwater Observatory' },
  })

  session.transaction(() => {
    const mayor = session.characters.add({ name: 'Eleanor Graves', /* … */ control: 'agent' })
    session.characterStates.create(mayor.id, { publicState: '…', innerState: '…', activity: '…' })
    session.intents.add(mayor.id, { type: 'agenda', name: '…', /* … */ })
  })

  session.characters.findByName('the mayor')       // by name or alias, ignoring case
  session.characterStates.update(1, { activity: 'looking for the key' }, { expectedVersion: 3 })
}
```

该服务在您给出的会话文件夹下创建并打开会话, 每个会话共享一个连接, 当插件卸下时全部关闭 :

| 方法 | 对 |
| --- | --- |
| `createSession(sessionsDir, init)` | 创建会话文件夹和数据库并返回其寄存器。 id是生成的(UUID v4),除非给出. 万一失败,任何事物都不会被留下. |
| `openSession(sessionsDir, id)` | 返回现有会话的存储器. |
| `listSessions(sessionsDir)` | 文件夹下每个会话的元数据( 名称、 世界、 创建时间、 上次播放时间、 回合) 。 无法读取的会话报告于 `problems`而不是抛出. |
| `closeSession(sessionsDir, id)` | 释放连接; 重新打开连接 . |
| `deleteSession(sessionsDir, id)` | 关闭会话并删除其文件夹. |

会话 ids 成为文件夹名称, 因此只接受一个 UUID v4 。 套装也 输出与平面函数相同的操作`createSession`, (中文(简体) ), `openSession`, (中文(简体) ), `createSessionStore`,.)用于不运行在DSH内部的代码,例如测试.

## 记录 API 和模型化工具

该套件拥有一个故事是如何被记住的,而不仅仅是它存储的地方:

-   `session.edit(edit)` 改变故事的纪录(特征状态,事件与谁收录,信仰,线条) 一起或完全不收. 它先检查整个编辑然后扔出去 `InvalidEditError` 命名每个问题,所以一个模型的错误可以报告给它. `parseRecordsEdit(json)` 读取线条格式模型写入( snake case)和 `recordsEditSchema({ characters, changes })` 是它的JSON schema,用于模型的结构输出或工具的参数.
-   `session.records(scope)` 以同样的电线格式读取记录.
-   `session.recall({ characterId, situation, turn, policy })` 一个人物被提醒的是什么: 它所经历的事件和它相信的东西, 通过局势谁提到, 共享的言语和标签, 重要性和故事时间的调整 `policy.flaky` 年长和不重要的人被说成是淡出或模糊的,或者已经消失。 年龄已经过了故事时间 `session.clock`从不计数 一个不重要的事件有六层楼的半生 它计算它带回的记忆, 它使它持续的时间更长.
-   `session.recallStored(query, { queryVector? })` 将会话的搜索索引添加到提示中:通过文字来匹配情况,并与情况向量相匹配的文本,以含义来对应. `session.searchEvents({ text, vector?, fromTurn, toTurn, minImportance, limit })` 找到同一两次搜查的经过 由对等等级合并.
-   `session.recallRanked(query, signal, { queryVector? })` 需要任何能提醒某样东西的功能: `recall`,在插件以 `roleplayState.rankMemories(ranker)` (嵌入模型,重排;见 `docs/capabilities.md`) (中文(简体) ). `session.recallCandidates(query)` 给出可以召回的, 与文本匹配的, 一个分级。 与 `explain: true` 在查询中每个被召回的东西 `why`:瞬间之提示(人名,言语相通,地地相通),每次搜索的得分,重要程度,是多久以前,所想的多少,以及排名的多少.
-   `session.knowledge` 地点、物品和直接出口的封闭世界意识图(`learn`, (中文(简体) ), `knows`, (中文(简体) ), `get`, (中文(简体) ), `list`, (中文(简体) ), `forget`) (中文(简体) ). 方向关系是相应的字符对字符边缘. 认识只提供身份,不提供现状或下落. `session.planKnownMove` 计划只通过一个角色已知的地点和出口; `planMove` 仍然是权威的世界规划者.
-   `session.factions`, (中文(简体) ), `factionStates`, (中文(简体) ), `factionMemberships`, (中文(简体) ), `factionRelationships` 财务报告和审定财务报表 `factionIntents` 将持久性组织与在场景中发挥作用的字符分开存储。 成员众多;涉及派别的关系是方向性的,是封闭世界认识边缘的两倍.
-   `roleplayState.bind(resolver)` 告诉一个代理商在哪个角色扮演会话中工作的工具(运行代理商的插件提供它,同时播放转盘和内存政策).

在DSH工具登记册上注册的工具(`defineTool`,键入输出,遵守调用 `signal`),通过约束解决: `list_characters`, (中文(简体) ), `get_character`, (中文(简体) ), `search_events`, (中文(简体) ), `recall_memories`, (中文(简体) ), `list_threads`,并仅在插件配置时 `writeTools: true`, (中文(简体) ), `update_character_state`, (中文(简体) ), `record_event`, (中文(简体) ), `remember`, (中文(简体) ), `open_thread`, (中文(简体) ), `resolve_thread`。对于一个在没有角色扮演会话中工作的代理商,它们以一个简单的信息失败。 字符和其他一发子剂没有看到它们(它们开始时没有工具).

## 配置

| 外地 | 默认 | 含义 |
| --- | --- | --- |
| `journalMode` | `delete` | `delete` 将每个会话保存在一个可以复制的文件; `wal` 允许读者在写作时. |
| `writeTools` | `false` | 还登记改变记录的模型化工具。 离开其他特工负责的地方. |

## 层

| 层 | 这是什么 |
| --- | --- |
| 条形模型 | 类型 `dsh-roleplay-model` (在此再出): `Character`, (中文(简体) ), `CharacterState`, (中文(简体) ), `CharacterIntent`, (中文(简体) ), `SessionMetadata`,, , , , , , , , |
| 仓库 | `MetadataRepository`, (中文(简体) ), `CharacterRepository`, (中文(简体) ), `CharacterStateRepository`, (中文(简体) ), `IntentRepository`: 数据的唯一访问. 他们取回犬形模型,并将错误扔到下面. |
| SQLite 执行 | 将地图行到模型并返回;是唯一知道表格和SQL的地方. |
| 驱动程序 | `SqlDriver` 编号 : `SqlDatabase`:执行需要的少数业务`exec`, (中文(简体) ), `run`, (中文(简体) ), `get`, (中文(简体) ), `all`, (中文(简体) ), `transaction`) (中文(简体) ). `nodeSqliteDriver` 以 `node:sqlite`。 。 。 . |

一切都是同步的,就像嵌入的 SQLite 库一样.

这是一个独立的社区项目,不是官方的DSH软件包. [文档](https://firefox2100.github.io/dsh-agentic-roleplay/docs/developers/state) • 妇女 [来源](https://github.com/Firefox2100/dsh-agentic-roleplay) • 妇女 [问题](https://github.com/Firefox2100/dsh-agentic-roleplay/issues) \* 仅限GPL-3.0

## 会议

一个会话是文件夹 `sessions/<uuid>/` 及其数据库 `session.sqlite`。 。 。 . 数据库是状态需要的唯一文件; 默认日记模式 保留一个可以复制或存档的文件.

世界本身没有储存. `metadata` 保持一个 **世界参考**页:1 世界稳定编号 `id` 联合国 `world.json`名称, 并选择一个版本,会话内容的指纹开始 来源和自由形式 `extra` 字段。 它保存为一个文档,所以 原产地可以在不改变计划的情况下增长.

元数据还包含会议列表显示的内容: `name` (创作时的选择),其创作时间,最后一出戏的时间 (不在场,直到一个转弯已经播放)和转弯次数. 随便啦 播放旋转调用 `metadata.recordTurn()`,它计算它和设定时间.

字符有会话本地整数 ID. `source_id` 保持编号 性格在世界上,所以一个会话可以追溯到它的世界; 播放时创建的字符没有.

## Schema(第1版)

| 图表 | 持有 |
| --- | --- |
| `metadata` | 密钥/ 值行 : `session.id`, (中文(简体) ), `session.name`, (中文(简体) ), `session.created_at`, (中文(简体) ), `session.last_played_at`, (中文(简体) ), `session.turns`, (中文(简体) ), `world` (JSON),外加自由式命名空间条目. |
| `characters` | 定义:姓名、年龄、性别、代名词、类型、层次、角色、摘要、个性、背景、外貌、言论、以及 `control` (单位:千美元)`player` 或者说 `agent`页:1. `source_id` 这是独一无二的. |
| `character_aliases` | 每个别名一行,按顺序排列,并有可打字的字箱密钥来取取. |
| `character_state` | 游戏中变化的状态:公共状态,内在状态,活动, `version`, (中文(简体) ), `updated_at`。每个角色一行. |
| `character_emotion` | 可选基线和一国的直接价值/激励/支配. |
| `intents` | 字符的用意:类型,名称,描述,状态,地平线,优先,紧急,计划,开放线程,约束,最后期限. |
| `relationships`, (中文(简体) ), `consolidation_items` | 人物如何站在另一个(每个方向的简介:标签,摘要,熟悉度,信任度,亲和度,紧张度)上,以及游戏中构成的人物和地点仍然必须适应于世界. `lintWorld` 报告内容不一致。 当编辑是作者的变体时,编辑可以制作字符、地点和方式(`recordsEditSchema({ authoring: true })`) (中文(简体) ). |
| `entity_knowledge` | 明确性格到位置/物品/外出意识:第一个被学习到的转弯和最后一个直接观察的可选转弯. 缺席意味着未知;目前的事实仍在状态、认知和记忆中. |
| `factions`, (中文(简体) ), `faction_aliases`, (中文(简体) ), `faction_state`, (中文(简体) ), `faction_memberships`, (中文(简体) ), `faction_relationships`, (中文(简体) ), `faction_intents` | 组织、机构状况和战略、许多成员以及涉及某一派别的方向关系. |
| `slots`, (中文(简体) ), `items`, (中文(简体) ), `item_holdings`, (中文(简体) ), `openers`, (中文(简体) ), `event_items` | 物品(物品,设备及容器的一种:数量,条件,显著,隐藏,所穿插的槽口,容器状态,所有者),每件物品所在的地方(一个地方,人物的手或一个槽口,或容器物品内),身上的地上可以穿出一些东西(默认,每个会话的数据),打开每个锁口(物品和出入口)的是什么,以及哪些事件是有关物品的. `changeItem` 做一个角色用某事(取出,放出,给出,放出,穿戴,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取出,取,取出. |
| `clock`, (中文(简体) ), `time_log` | 故事本身的时间: 有模式的一行(`simulated` 或者说 `real`)和瞬间,以及它所走的每一步(起步、过去、真实、跳跃、回转),与转和回转. `session.clock` 开始,向前移动,当模式改变时将其设置为任意方向,并显示回合何时开始. |
| `routine_windows`, (中文(简体) ), `engagements`, (中文(简体) ), `engagement_participants` | 每个性格的反复出现之日(当天的窗口与它的行为和在哪里适用,首先适用),与谁共同做出承诺,以及承诺是否得到遵守. `session.routines` 财务报告和审定财务报表 `session.engagements`· ; `agendaAt` 把它们与角色的目标合并( name`intents`) (中文(简体) ). |
| `locations`, (中文(简体) ), `exits`, (中文(简体) ), `placements` | 地点(有特征),它们之间的道路(各一个方向, `open` 编号 : `locked` 编号 : `blocked`,可选出行秒),以及事物所处位置(一个字符:位置,位置,特征;同一表格会放置项目). `session.planMove` 编号 : `session.move` 仅在打开的出入口上移动字符( e)`InvalidMoveError` 名称每个原因);编辑的线条格式可以使位置,改变出入口并移动字符. |
| `events` | 客观上发生的事情:倒转,回转,文字,重要性(1到5),标记. `event_involves` 列出一个事件所涉及的字符。 事件是不可改变的:草稿直到 `sealed`之后的最后决定(`events.seal()`); 更新或去除被密封的投出 `ConflictError`。 。 。 . |
| `perceptions` | 一个人物对一个事件采取了什么,用它自己的术语:模式(目击者,听到,告诉,推断),内容,当它消失时的要旨,精确的标签(从未向人物显示),以及被召回的频率. 每个角色和事件一个. |
| `memories`, (中文(简体) ), `memory_evidence` | 一个人物所相信或知道的东西超越了单个事件:善良,文字,主题,重要性,信心,形成转折,以及支持或相矛盾的观念. |
| `story_threads` | 事情还没有解决:承诺,神秘,目标;开放或解决,以及玩家的性格是否知道每一个(在告知,看到或接受之前保密). |
| `summaries` | 谈话头部故事的叙述:近代曲折的文摘和更年长的曲折的章节,每篇都以曲折所覆盖. |
| `recall_items`, (中文(简体) ), `recall_fts`, (中文(简体) ), `recall_vocab`, (中文(简体) ), `recall_vec` | 搜索索引:每感知,内存和事件一行,以单词(FTS5)为索引,一经向量存储,就按意义(sqlite-vec,cosine,被字符分割)为索引. `store.recallIndex` 列出没有向量的文本( n)`pending`),存储向量(`store`,它规定了会议向量的模型和尺寸)和搜索(`lexical`, (中文(简体) ), `vector`) (中文(简体) ). 矢量支持是可选的: 没有扩展, 一切除外 `vector` 工作时. |
| `pending_commits` | 有记录的回合,其事件和记忆尚未被写出,保留下来,以致失败一无所获. |

事件是地面真相; 感知(这些感知仍然可以重现: `updatePerception`, (中文(简体) ), `addPerception`),回忆和摘要都来源于它们,可以重建. 仓库是 `events`, (中文(简体) ), `memories`, (中文(简体) ), `threads`, (中文(简体) ), `summaries` 财务报告和审定财务报表 `pendingCommits` 在字符旁边.

删除字符可以删除属于它的一切. 这些表格是: `STRICT`,计数和范围为 `CHECK` 限制, 和外国键是 已执行。 文件记录了它的图案版本在 `user_version` 并携带一个 应用程序 id, 因此一个不是会话数据库的文件被拒绝 .

## 改变计划

当一个会话打开且从未编辑时,按顺序进行迁移 一旦发布: 更改是新条目 `src/sqlite/schema.ts`测试 标定每次释放的迁移。 拒绝更新版本的数据库 而不是损坏.

在更新最新计划后的文件之前,它必须通过 SQLite 的文件 快速完整性检查( 拒绝使用损坏的文件) `CorruptDataError`,未触及) 以及写给 `migration-backups/schema-<version>.sqlite` 在数据库旁边,每旧版本一次. `migrationBackupPath(location, version)` 说在哪里.

## 错误

| 错误 | 何时 |
| --- | --- |
| `NotFoundError` | 一个行,字符或会话文件不存在. |
| `ConflictError` | 重复 `source_id`,一个州创建两次,一个 stale `expectedVersion`,或创建存在会话. |
| `InvalidValueError` | 一个值是计划允许的. |
| `SchemaError` | 文件不是一个会话数据库,或者来自更新的版本. |
| `CorruptDataError` | 存储的数据不能被读取为模型 . |

## 常见问题

### @dsh-agentic-roleplay/state 是什么？

角色扮演会话状态的DSH插件:每会话一个SQLite数据库,作为服务于canonical模型而被其他插件所曝光\.

### 如何安装 @dsh-agentic-roleplay/state？

在项目目录运行 npm install @dsh-agentic-roleplay/state，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh（\>=0\.2\.2-rc\.1 \<0\.2\.3）、@deepseek-ai/schemastery（^3\.18\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dsh-agentic-roleplay/state 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dsh-agentic-roleplay/state 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dsh-agentic-roleplay/state 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.19\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dsh-agentic-roleplay/state 可以商用吗？

@dsh-agentic-roleplay/state 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @dsh-agentic-roleplay/state 的下载量有多少？

根据 npm 官方下载统计，@dsh-agentic-roleplay/state 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,483 次，日均约 216 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dsh-agentic-roleplay/state 还在维护吗？

最新版本 0\.12\.4 发布于 2026/11/13（今天）；至今共发布 34 个版本，其中过去 12 个月发布了 34 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。