角色陪伴工作区 Red0tsnow/dsh-companion

dsh-companion · 鲸屋

给 DSH 中的角色一个独立工作区：保存人设、日记和长期记忆，按需接入 Minecraft、QQ、B站与自备的小黑盒工具。只配置人设即可开始 DSH 对话，其余通道可以一直留空。

这不是独立 App。 它是 DeepSeek Harness（DSH）的插件——没有 DSH 就装不上、也跑不起来。它不是模型，不提供对话能力，用的是你自己 DSH 里已经配好的模型。

当前版本 0.7.3，MIT 许可，源码与发行包都在本仓库。

为什么用它

| 没有它 | 有了它 |
| 每次开新会话，角色都像第一次认识你 | 人设、日记、长期记忆存在独立目录；关掉 DSH 再开，还是同一个她 |
| 人设挤在系统提示词里，超长被悄悄截断 | 人设是独立文件，超过 4000 个 UTF-16 单位会明确拒绝保存，不静默截断 |
| 角色只能聊天 | 可选接 Minecraft（能进世界走动、挖、放、打怪）、QQ（私聊找你）、B站、小黑盒；不接任何一个也能正常聊天 |
| 想让她做点什么，只能一条条下指令 | 可选的三项日常：自己接着做、主动找你、写自己的日记 |
| 性格写死在代码里 | 行动层是一个可编辑的 .mjs 文件，角色自己能改（试用端口验过才生效，失败可回滚） |

前置条件

必装，缺一不可：

| 项 | 要求 | 说明 |
| DSH | 能自己正常聊天 | 插件挂在 DSH 上运行，不自己起服务；DSH 关掉插件就停了 |
| 模型 | 宿主里已配置、能成功回复 | 复用 DSH 的模型，不需要另外填 key |
| Node.js | 22 或更高 | 插件工具进程使用；可用 runtime.nodePath 或 DSH_NODE 指定 |
| 操作系统 | Windows | 这是首个验证平台，其他系统未验证 |
| 磁盘空间 | 约 1 GB 起 | 开 Minecraft 世界再占几百 MB |

不装 DSH 的人用不了这个插件——这一点请不要误会成"下载即用"。

四个通道各需要什么

全部可选。 只想要"能记住你的对话角色"，装完填人设就行，下面四个都可以一直留空。

| 通道 | 你要准备 | 插件替你做 | 现状 |
| Minecraft | 三种里选一种：① 什么都不用，插件帮你新建世界；② 自己开游戏内「对局域网开放」；③ 已有服务端目录。要进世界玩还需要你自己的 Java 版客户端和游戏授权 | 自动选支持的版本、按需准备对应 Java（26.1 用 Java 25，1.21.8 用 Java 21）、下载官方服务端、起停世界、让角色进入、换版本时保留旧世界 | 已实测 1.21.4 / 1.21.8 / 26.1 |
| QQ | 两个 QQ 号（你的 + 角色专用的那个）、手机装 QQ 用来扫码 | 下载并校验官方便携版 NapCat（固定版本 + sha256，不执行安装器、不要管理员权限）、解压后直接运行、自动写入连接参数、隔离自己的数据目录 | 便携版启动和重启已实测；真实账号的完整往返没跑通 |
| B站 | 一个希望角色使用的 B站账号，用 App 扫码确认 | 获取登录二维码、本地保存登录态、提供一套工具链（看视频内容、评论、动态、私信、弹幕、额度） | 登录与只读能力已测；写操作取决于平台返回 |
| 小黑盒 | 你自己准备的 Node CLI（本仓库不分发） | 用你指定的 CLI，展示返回状态 | 只做调用与展示，不含任何签名实现或内部常量 |

各通道的额外说明

QQ / B站账号风险提示： 新建小号或多年未使用的小号可能触发平台风控、验证或账号限制。本插件尚未在长期使用的账号上进行测试，不推荐使用主号。请自行评估并承担使用风险；本插件不承担由此产生的账号限制或其他损失。QQ 小号还可能因风控或风险提醒，需要每隔一段时间重新扫码登录，不能保证登录态长期有效。

QQ / Bilibili account risks: New secondary accounts, or accounts unused for years, may trigger risk checks, verification, or restrictions. This plugin has not been tested with accounts in long-term regular use. Using your main account is not recommended. Assess and accept the risks yourself; this plugin accepts no responsibility for resulting restrictions or other losses. Secondary QQ accounts may require periodic QR sign-in after security alerts; continued login validity is not guaranteed.

平台协议风险： 用第三方客户端或自动化方式使用 QQ、B站、小黑盒，可能违反这些平台的用户协议。平台有权因此限制或封停账号——这是平台条款层面的风险，不是法律诉讼，但后果由你承担。插件只在你本机调用公开协议和你自己准备的工具，不绕过任何平台的安全机制，也不代替你做出这个决定。B站与小黑盒的自动化操作特别容易被判定为异常；请自行判断是否值得。
平台条款： 把第三方客户端或自动化工具用于 QQ、Bilibili 或小黑盒，可能违反这些平台的服务条款。平台可能因此限制或封禁账号——这是合同层面的风险，不是法律主张，但后果由你承担。插件只从你自己的机器上使用公开协议，并调用你提供的工具；它不绕过平台安全机制，也不替你做出这个决定。

- Minecraft：服务端 jar、Java、NapCat 都在你明确确认后从官方来源下载并校验；公开包里不含这些东西。角色身体第一次由包内模板生成到 runtime/mc/mc-daemon.mjs。
- QQ：插件使用 OneBot v11 公开协议；不读取、不修改其他 QQ 插件，不接管宿主全局消息钩子。私聊默认只认你配的主人号。
- B站：视频抽帧需要 FFmpeg 在 PATH 里或设置 FFMPEG；普通登录检测不需要。
- 小黑盒：契约是 node <你的CLI> whoami --json，stdout 只输出一个 JSON。工具必须支持 DSH_COMPANION_CREDENTIALS 环境变量才能用插件保存的凭据。
- 可选媒体处理：Python / Pillow 只用于额外的图片处理能力检测；缺失只影响对应功能，插件不会替你装。

隐私

插件不上传任何数据：没有账号服务器、没有遥测、没有崩溃上报。日记、记忆、人设、媒体和凭据都只存在你的数据目录里；凭据不出现在任何接口响应中。对外请求只发往硬编码白名单里的官方下载源，且每个都需要你明确确认。

你和角色的对话会发给你 DSH 里配置的模型服务方——这是 DSH 的行为，不是插件记录的。生成内容由该模型与平台负责。

完整清单（数据位置、请求目标、删除方式、你的责任）见 隐私与数据。 / The plugin uploads nothing and has no telemetry; see privacy for data locations, the outbound host allowlist and deletion.

明确的限制

写在这里，免得装完才发现。

平台与验收

- 只在 Windows 上验证过；macOS / Linux 未验证。
- 首次安装有过一次真实用户验证（2026-10-26）：一位完全没有 Node 基础的 Windows 用户，按说明让 DSH 完成安装，并接好了 Minecraft 与 QQ，没有卡住。
- B站仍未验证：那次验证的对方没有小号，扫码之后的真实往返没跑过。
- QQ 验证到「能连上、能往返」，长期稳定性（掉线重连、多久要重新扫码）没有验证。
- 这是一次验证，不是长期回归。0.6.0 之后加的功能（自主循环、三类回顾、空世界自动关）还没有经过真实唤醒的验证。

功能边界

- 人设上限 4000 个 UTF-16 单位（汉字通常占 1，部分 emoji 占 2）。超了拒绝保存，不会截断。
- 三个日常功能（自己接着做 / 主动找你 / 写日记）默认全关，而且需要另装 dsh-proactive@0.3.1；缺了会在面板上明示不可用。
- Paper 皮肤只支持 1.21.8 build 60 这一个版本；其他版本仍走原版。
- 插件不生成语音；媒体库不会仅因上传文件就自动发到 QQ 或别的平台。
- 小黑盒不含签名实现，你得自己有可用的 CLI。
- 模型调用产生的费用由你自己承担，插件不提供额度。

行为约束

- 外部世界（你自己起的服务端）可以由插件识别，但关闭要回原控制台；插件不会强制结束归属不明的 Java 进程。
- 身体是可以被改的：没改过的身体升级时自动更新（先备份），改过的一个字都不动，只留 runtime/mc/BODY-UPGRADE.md 说明。

安装

先确认 DSH 自己能正常聊天，再来装插件。插件不自带模型。

两种装法，任选一种：

A. 用发行包（推荐）

从 Releases 下载 dsh-companion-0.7.3.tgz，在已安装 DSH 的终端里：

dsh plugin --profile desktop add ./dsh-companion-0.7.3.tgz

B. 从源码自己打包

npm ci
npm run build
npm test
npm run check
npm pack
dsh plugin --profile desktop add ./dsh-companion-0.7.3.tgz

装完重启该 DSH profile。插件入口在 DSH 设置里的「鲸屋 / Whale House」。

默认 profile 名是 desktop，用别的 profile 就替换掉。开发时也可以直接链源码目录：dsh plugin --profile desktop add "link:<插件绝对路径>"。

第一次使用

完全没接触过？ 看 从零开始：第一次用——按面板上真实出现的按钮一步步写，包含"看到什么、点哪里"，以及卡住时该查哪个日志。

下面是速览：

1. 打开面板，填写角色名、关系、语气，编辑并保存人设。可载入空白模板或脱敏示例。
2. 人设上限为规范化换行后的 4000 个 UTF-16 单位；通常汉字占 1，部分 emoji 占 2。界面和服务端均检查，超限不会保存或静默截断。
3. 点击“打开角色对话”。会话身份保存在角色数据目录，重启后继续使用同一个身份。
4. 需要哪个通道，就点击对应的“开始一起玩”“连接 QQ”或“扫码连接 B站”。跟着向导完成准备；技术字段收在“高级设置”中。灰色“未接入”是正常状态。
5. 「角色写的」查看公共日记、私人日记、手札、长期记忆、印象、便签和睡前一句。页面可见时每 10 秒刷新。

通道细节与安全

- QQ 只接受你配置的主人私聊；群聊可在高级设置中填写允许的群号并 @ 角色。WS token 与 Cookie 存在独立凭据文件里，读取配置只返回「是否已设置」。
- 外部组件（Java、Minecraft 服务端、NapCat）都在你明确确认后从官方来源下载并校验；运行副本与安装包分开。NapCat 固定版本与哈希，版本对不上就拒绝下载，等插件更新。公开包不含 Java、Minecraft jar、NapCat、QQ 或小黑盒签名实现。
- 新手步骤见 连接向导，高级配置与故障说明见 使用指南。

角色的新能力 / Character capabilities

| 能力 / Capability | 使用方式与边界 / Use and limits |
| 会自己接着做（可关） / Keep going independently (optional) | Minecraft 身体在线且空闲时接着做一小步，连续最多十次；世界里没有别人时不会唤醒；默认关闭 / Online, idle world only; never wakes while no other player is in the world; up to ten consecutive wakes; off by default |
| 会主动找你（独立开关，一天一条） / Think of you (independent switch, once daily) | 随机窗口、40 字以内；普通角色私聊，允许安静跳过 / Random window, at most 40 characters in the ordinary private conversation; silence is allowed |
| 会写自己的日记（一天一段，必须新起日期） / A personal diary (one newly dated entry daily) | 工具自动添加日期和账本，连续三天没写会提示 / Tool-managed headings and ledger, with a notice after three empty days |

世界里没有别人超过 15 分钟（可在面板改成任意值，0 表示不关）就自动关掉世界，免得空世界一直占内存。她正在做任务时不会关。 / When nobody has been in the world for 15 minutes (configurable, 0 disables) the world is shut down so an empty world does not keep holding memory. A task in progress is never interrupted.

日常唤醒依赖可选的 dsh-proactive@0.3.1 文件表工具；不随包安装，也不改它的额度或安静时段。缺少能力会明示不可用，核心对话照常使用。身体还提供 mc snapshot、后台 mc do、mc places 和技能结果验收。完整步骤见 连接与日常使用。 / Wake features need the optional dsh-proactive 0.3.1 schedule-file tools. The provider is neither bundled nor reconfigured. Snapshot, background intents, named places and skill acceptance are also available.

数据、迁移和升级

默认数据根目录为 $DSH_HOME/companion；未设置 DSH_HOME 时使用用户的 .dsh/companion。可设置 DSH_COMPANION_HOME 或宿主插件配置 dataDir 改用独立目录。角色工作区位于其中的 workspace，与安装包分开。

人设原件是 workspace/AGENTS.md，persona.md 是插件管理的镜像。secrets.json 是凭据来源；bili/credentials.json、xhh/xhh-cookie.json 是工具使用的派生视图，保存凭据时同步，不在配置响应中返回。请备份整个数据目录，勿把它提交到公开仓库。

迁移默认只预览：

node tools/migrate.mjs --source "<旧DSH数据目录>" --target "<新角色数据目录>"
node tools/migrate.mjs --source "<旧DSH数据目录>" --target "<新角色数据目录>" --apply

仅在确实需要复制凭据时添加 --credentials。原件保留、目标已有文件保留，旧会话日志不自动搬运。迁入闹钟默认停用，需检查路径、时区与目标后再启用。完整说明见 迁移与回滚。

备份：数据全在这一个目录里——workspace（人设、日记、记忆、便签、技能、地点）、runtime（运行中的身体与日志）、schedules、secrets.json 和各通道凭据。磁盘坏了、系统重装或误删，就一起没了；没有云端，也没有第二份。备份就是把整个目录复制走（含凭据，放在自己的加密盘或私有位置）：

先退出 DSH（或至少停掉身体和世界），避免复制到写了一半的文件 $data = "$env:USERPROFILE\.dsh\companion" # 改过 DSH_COMPANION_HOME/dataDir 就换成实际路径 Copy-Item $data "$env:USERPROFILE\Backup\companion-$(Get-Date -Format yyyyMMdd-HHmm)" -Recurse

恢复：退出 DSH，把备份目录放回原路径（目录名仍是 companion），再启动。升级前、换机器前各备份一次。

升级：备份数据目录，安装新版包并重启 DSH。运行中的身体位于 runtime/mc，角色自行修改的身体不会被新版模板静默覆盖。

卸载：dsh plugin --profile desktop remove dsh-companion，然后重启该 profile。卸载保留角色数据；Minecraft 世界请先在面板显式关闭。回滚时安装保留的旧版 .tgz，必要时恢复自己备份的数据目录。

开发与验证

npm run dev 启动隔离的本地面板预览；它使用真实插件服务，未接入 DSH 时不会伪造对话成功。npm test 运行行为测试；npm run check 检查发布源码语法、相对导入、个人路径与身份泄漏、QQ 实现边界及小黑盒签名排除规则。npm pack --dry-run --json 可查看发行清单。

实现与测试限制见 已知问题。许可证为 MIT，自有源码改编记录与第三方依赖见 NOTICE。

English quick start

把包装进你的 DSH 配置档，重启 DSH，打开 Settings → Whale House。保存人设，再打开角色对话。四个外部渠道全部可选。Windows 是首个验证目标；DSH 和它配置的模型必须保持可用。

Minecraft 指南提供三种方式：托管世界，支持动态选择版本；局域网发现；或使用已有服务器目录。托管安装需要下载并确认 EULA。Paper 皮肤只对已验证的 1.21.8 构建启用；托管世界运行时，填入直接指向 PNG 的 URL 即可应用。NapCat 使用固定版本的便携压缩包，需要明确确认版本与哈希，并使用隔离的进程数据路径。指南支持重启辅助进程并扫描新的二维码。Bilibili 支持 App 扫码登录。Heybox 需要你自己的命令行工具；插件不附带任何签名实现或内部常量。插件复用宿主模型，不需要额外的 API key。证据缺失时显示为未知。

不带 --apply 运行迁移，可先预览。迁移保留源文件和目标位置已有文件。升级前请备份配套数据目录。卸载插件后，该数据仍会保留。当前细节与限制见 usage、migration 和 verification。