# dsh-plugin-soulbridge 中文文档

规范地址：https://npmcn.com/package/dsh-plugin-soulbridge/

版本：0\.0\.102
npm 元数据更新时间：2026-11-03T12:50:10.892Z
中文译文更新时间：2026-11-03T12:58:51.742Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/dsh-plugin-soulbridge
原文对照：https://npmcn.com/package/dsh-plugin-soulbridge/?lang=original
项目主页：https://github.com/Jason0826/dsh-plugin-soulbridge#readme
源码仓库：https://github.com/Jason0826/dsh-plugin-soulbridge

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

- 包体积（解压后）：106 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.18
- 运行依赖：1 个
- 首次发布：2026-11-03T12:45:29.784Z
- 最新版本发布：2026-11-03T12:50:10.758Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

在DSH会话中注入灵魂桥的内容，并以观察的形式反馈用户回返。

## 安装

```sh
npm install dsh-plugin-soulbridge
```

也可以使用：`pnpm add dsh-plugin-soulbridge`、`yarn add dsh-plugin-soulbridge`、`bun add dsh-plugin-soulbridge`

## README

# dsh-plugin-soulbridge

把 [soulbridge](https://github.com/Jason0826/soulbridge) 接到 DSH 上的宿主适配器。

soulbridge 的核心不知道 DSH 的存在；这个包只做**接线**：在正确的时机调用四个动词， 把结果放进系统提示，并在失败时安静降级（[ADR 0024](https://github.com/Jason0826/soulbridge/blob/main/docs/adr/0024-adapters.md)）。

## 它做什么

| 时机 | 调用 | 现状 |
| --- | --- | --- |
| 提示组装 | `context({ track: false })` → 注入 `<soul>` / `<style>` / `<affect>` / `<memories>` | 🚧 目前是占位标记 |
| 每条**用户**消息 | `observe(turn)` → 写记忆 + 情绪采样 | ✅ 已实现 |
| 会话结束 | `reflect(turns)` | ❌ 未接：`observe` 已逐轮蒸馏，`session/disposed` 在桌面端不触发 |
| 模型主动查询 | `recall` / `remember` 工具 | 🚧 未接 |

**不会做**：改变事实判断、编造记忆、把个人记忆写进项目文件。

日志：`~/.soulbridge/plugin.log`（`SOULBRIDGE_HOME` 可覆盖）。数据落在 `~/.soulbridge/soul.db`， 与 CLI 和任何其他工具共享同一个库。

## 安装（正式发版前，走 git 标签）

```powershell
cd $env:USERPROFILE\.dsh\profiles\desktop
dsh plugin --profile desktop add "github:Jason0826/dsh-plugin-soulbridge#v0.0.4"
```

然后确认它出现在 `package.json` 的 `dsh.profile.bundles` 里，重启 DSH。

> `dsh plugin add` 会调用 pnpm；如果提示 store / virtual-store 不一致，见文末「已知问题」。

## 依赖

| 包 | 版本 | 说明 |
| --- | --- | --- |
| `soulbridge` | `^0.0.6` | 从 npm 安装，是第一个暴露库入口（`main`/`exports`）的版本 |

## 判读日志

| 日志 | 含义 |
| --- | --- |
| `apply() called (v0.0.2)` | 插件被加载（标签是历史遗留，不代表版本号） |
| `section registered` + `section.text() evaluated` | 注入通路成立 |
| `user/message source=user chars=N` | 收到用户消息 |
| `soul ready: db=… soul=… user=…` | core 与数据库就绪 |
| `observe ok: chars=… written=… affect=… confidence=…` | **整条链路成功** |
| `skipping profile bundle …` (stderr) | bundle 被启动器跳过，原因就在后面 |

## 卸载

```powershell
cd $env:USERPROFILE\.dsh\profiles\desktop
node "…/pnpm.mjs" remove dsh-plugin-soulbridge
# 或 dsh plugin --profile desktop remove dsh-plugin-soulbridge
```

再从 `dsh.profile.bundles` 里删掉 `dsh-plugin-soulbridge`，重启。

## 已知问题

### `dsh plugin add` 报 store / virtual-store 不一致

`~/.dsh` 若是指向另一块盘的目录联接，而 profile 的 `node_modules` 是在联接建立**之前**创建的， pnpm 会同时报 `ERR_PNPM_UNEXPECTED_STORE` 和 `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`。

修复：在**真实路径**下重装一次依赖，让 `.modules.yaml` 记录的路径与 pnpm 的解析一致。

### profile 的 `package.json` 带 BOM 会让应用起不来

DSH 启动器对 `package.json` 直接 `JSON.parse`，不剥 BOM。用 Windows PowerShell 的 `Set-Content -Encoding utf8` 改它会写入 BOM，导致启动崩溃或 bundle 被静默跳过。 本仓库用 `scripts/profile-manifest.ps1` 改写清单，用 `scripts/check-encodings.ps1` 检查编码。

## 配置（可选）

`~/.soulbridge/plugin-config.json`：

```json
{
  "distill": "llm",
  "provider": "deepseek-account",
  "model": "deepseek-flash",
  "maxLlmChars": 2000
}
```

| 字段 | 作用 |
| --- | --- |
| `distill` | `rules`（默认）只在本地做规则抽取；`llm` 在**规则没抽到**时再问宿主模型 |
| `provider` / `model` | 宿主模型路由；只在 `distill: llm` 时使用 |
| `maxLlmChars` | 超过此长度的消息不送模型（跳过并记录，不做截断） |

为什么是"规则优先、模型补漏"：实测规则精确率 1.00，但 26 条真实消息里漏了 19 条； 让模型覆盖规则没有收益，只在漏掉时补才有。宿主模型**只能在真实轮次内调用**， 启动时调用会被账号 provider 拒绝（见 `docs/experiment-2026-10-29-host-llm.md`）。

## 升级提示：新增工具需要新开会话

`ctx.inject(['tools'])` 注册的工具在**会话创建时**进入该会话的工具集。插件升级后 新增了工具，已经存在的会话仍然看不到它——需要新开一个会话（`/s new` 或界面新建）。 已经在会话里的注入、观察不受影响。

## 常见问题

### dsh-plugin-soulbridge 是什么？

在DSH会话中注入灵魂桥的内容，并以观察的形式反馈用户回返。

### 如何安装 dsh-plugin-soulbridge？

在项目目录运行 npm install dsh-plugin-soulbridge，或使用 pnpm add / yarn add / bun add。

### dsh-plugin-soulbridge 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dsh-plugin-soulbridge 是否存在。

### dsh-plugin-soulbridge 支持 ESM 还是 CommonJS？

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

### dsh-plugin-soulbridge 需要什么版本的 Node\.js？

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

### dsh-plugin-soulbridge 可以商用吗？

dsh-plugin-soulbridge 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-plugin-soulbridge 还在维护吗？

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