starr ✦

醉后不知天在水，满船清梦压星河。

——唐温如《题龙阳县青草湖》

一个以角色为中心的 DeepSeek Harness（DSH）人工智能（AI）角色养成插件。

starr 将角色人设、长期记忆、情绪状态、会话接续与听说看唱整合在同一个网页控制台中。它通过 SnowLuma 连接 QQ，接入 B站，并让经过授权的跨平台经历沉淀到同一角色的记忆里。你可以在 Obsidian 中阅读、整理笔记，也可以在三维星图里探索记忆之间的联系。

让每一次相遇都有记忆，让每一颗星星都有故事。

当前版本：v0.2.4。主要面向 Windows，已核对的宿主接口版本为 DSH 0.2.1-rc.5；其他系统与宿主版本仍需分别验证。

安装与更新 · 首次配置 · 完整配置 · 版本说明

v0.2.4 将页面整理为聊天、感受与表达、自主活动、记忆四个工作区。常用配置直接放在对应功能页，修改后统一保存。记忆收敛为日记与自由笔记，角色可以修订自己的可见笔记，并把少量长期理解带到新会话；同类后台任务复用会话。插件内 Tabbit 与固定周月年回顾已移除，保留宿主原有能力、B站浏览、连续接听和原生文件读写。

能做什么

能力	说明
角色与人格	创建角色，编辑人设、提示词和说话方式；不同角色的数据与配置独立保存。
长期记忆	由角色维护自由笔记与少量长期理解，支持修订、关联、合并与可恢复归档；新会话按共享范围继续召回。
Obsidian 记忆库	自由笔记统一写入“笔记”，日记保留独立目录与定时保存；支持双链、外部修改核对与备份。旧目录升级时不自动搬动。
记忆阅读与星图	默认列表与全文阅读，可切换时间线、长期理解或三维星图；桌面右侧长文独立滚动，不以摘要替代正文。
心理、情绪与目的	虚拟心理和身体状态、正负混合情绪、需求与目的评估；状态影响表达与回复节奏。
Starr-chat	统一登记 QQ、B站与显式绑定的宿主会话，提供会话接续、上下文注入与有范围的共享记忆。
QQ 互动	分开的私聊与群聊、引用回复、群内@、拍一拍、表情尺寸、图片与语音，以及按权限开放的平台操作。
B站互动	扫码登录、资料与字幕读取、视频关键帧理解、私信和评论，以及经确认或授权的动态与跨平台分享。
听说看唱	免费本地听写、兼容服务语音合成、宿主视觉模型，以及本地 SoulX 翻唱与角色曲库。
找歌与曲库	统一搜索本地曲库、B站和网易云；默认优先高潮／副歌片段，导入后可交给已配置的歌声转换（SVC）模型生成不超过 45 秒的翻唱。
主动行动	默认只观察；管理员开启后，按对象、权限、安静时段和预算执行目的，保留时间线、失败原因与用量。
资源与维护	表情包、曲库音源与单个成品删除，媒体密钥清除，配置审计、记忆整理、数据库一致性备份与运行诊断。

能力是否可用取决于模型、桥接版本、账号权限与实际调用结果。连接检查通过不代表所有功能均已完成真实平台验收，详细范围见验证记录。

安装到 DSH

普通用户可以直接安装发行包，无需配置前端开发环境。

1. 在本仓库的**发行版（Releases）**下载 dsh-starr-0.2.4.tgz（发布后可用）。
2. 在 DSH 的本地插件安装入口选择该文件，或运行以下命令。
3. 完全退出并重新打开 DSH，点击侧栏的 starr，进入新手调试。

dsh plugin --profile desktop add '你的下载目录\dsh-starr-0.2.4.tgz'

将 desktop 换成你实际使用的配置名称，并替换文件路径。包内包含构建后的网页，安装时会自动启用插件、添加侧栏入口并注册 Starr-chat · 角色会话，兼容预设编号为 starr-qqchat。

发行文件的用途如下：

文件	用途
dsh-starr-0.2.4.tgz	给 DSH 安装的插件包。
dsh-starr-0.2.4.zip	运行插件的解压归档；解压后可安装其中的 package 目录。
dsh-starr-0.2.4-source.zip	开发用完整源码，需要安装依赖并构建。

更新已有安装时，安装新的 .tgz 后同样需要完全退出并重新打开 DSH。运行数据与代码分开保存，升级流程保留个人角色、记忆和表情。详见安装与更新。

第一次使用

新手调试可以保存进度，刷新或重启后继续。QQ、B站和扩展媒体可以按需要接入。

1. 连接 QQ：按教程启动 SnowLuma，启用 OneBot 11 正向 HTTP 与 WebSocket，填写端口、访问令牌和允许回复的对象，再检查协议与登录状态。当前只连接本机 127.0.0.1。
2. 创建角色：填写名字与时区；已有角色需要明确选择。
3. 编写人格：设置人设、说话方式和相处边界，后续可在“人设与提示词”继续编辑。
4. 创建记忆库：确认记忆目录与独立备份目录。可以选择两个新的空目录，也可明确确认使用带 .obsidian 标记的已有 Obsidian 库，插件会创建独立角色子目录。
5. 接入 B站：按需扫码登录；也可以稍后配置。
6. 配置扩展模型：按需启用听写、说话、视觉与唱歌，均可跳过后再补。
7. 进入控制台：选择 DSH 聊天模型；明确启用 QQ 并完成向导后，插件才开始自动回复。

记忆与备份目录必须分开，不能重叠或相互嵌套。SnowLuma 的访问令牌需要与插件设置一致，它是接口凭据，不是 QQ 登录密码。

详细操作见首次配置、QQ 连接与排错和DSH 会话接入。

控制台导航

工作区	主要内容
回廊共语 · 聊天	人设与说话方式、聊天与连续接听、QQ连接与群聊、表情包。
心观万象 · 感受与表达	情绪与体感、看图与视频、听语音、说话与音色、唱歌与曲库。
逐光而行 · 自主活动	自主活动、B站账号/浏览/发布、跨平台分享。
星海拾忆 · 记忆	笔记与日记、日记与记忆设置、共享与隐私。

查找功能、能力授权、外观与性能、备份与排查统一放在左栏下方。诗意名称用于导航与首页，配置标签使用普通名称。完整页面与配置位置见页面清单。

网页使用 Three.js 三维场景、GSAP 动画和局部模糊，并提供动态效果档位与减少动态模式。记忆详情保留完整正文，桌面端可在右侧独立滚动阅读。

听说看唱怎么配置

能力	推荐配置方式	需要准备什么
听	使用免费本地 Whisper，或填写远程兼容接口。	本地模式需要 Python、准备独立环境，并在首次使用时下载模型权重；免费指无服务接口调用费用。
说	确认本地 Breeze 安装目录与音色，或填写远程语音合成（TTS）接口。	已安装的兼容引擎与权重，或服务地址、模型、音色编号和密钥。
看	优先使用 DSH 已配置且支持图片的模型，也可配置兼容接口。	支持图片的模型；屏幕和摄像头采集需要分别授权。
唱	使用本地 SoulX，导入音源和参考音色后生成翻唱。	SoulX 环境、模型与 FFmpeg；QQ 发送还需开启对应权限。

本地发现只盘点候选文件和服务信息，应用前需要确认，不会自动安装或执行陌生引擎。参考音色能力取决于引擎和模型；没有通用的云端音色训练或云端 SVC 协议。兼容远程唱歌字节节点保留为高级接入方式，需要单独验证。

starr 托管的 Breeze、SoulX 和免费 Whisper 共用本地模型许可，同一时刻只允许一个托管模型推理。切换模型前先卸载空闲模型；Breeze 与 SoulX 闲置满 5 分钟退出，Whisper 转写结束即退出。DSH 宿主视觉模型由宿主管理生命周期。

点歌流程为 检索 → 选择音源 → 导入片段 → SVC 翻唱 → 按权限发送。高潮优先使用标题线索或时间歌词重复定位，无法可靠定位时明确回退到开头，也可手动设置起点。平台版权、付费、地区和试听限制可能阻止入库。详见听说看唱、统一曲库和远程唱歌节点。

会话、共享与自主配置

DSH 提供宿主模型与会话执行，starr 管理角色、记忆、状态和业务能力。每轮请求按预算注入人格、会话接续、状态、目的与相关记忆，需要完整内容时由工具继续读取。

同一角色可以在 QQ 和 B站之间共享经过管理员授权的记忆；会话私密内容、群聊、公开评论与主人私聊仍有各自的读取范围。主人身份来自管理员绑定。普通未绑定的 DSH 会话可以正常聊天，角色工具只提供给 Starr-chat 预设和显式绑定的会话。

角色可以调整管理员允许的日常配置，例如语气、音色、部分记忆参数与兴趣词。路径、可执行程序、凭据、主人绑定、外发权限和角色自身授权由管理员控制。

主动执行默认处于 L0 只观察。管理员可逐级开放可信主人私聊、公开阅读和指定社交能力，并设置预算、冷却与安静时段。失败、未知用量或不明发送回执会阻止相应的后续动作。心理与身体状态属于虚拟角色模拟。

从源码安装与开发

环境要求

• Node.js 24 或更新版本：使用内置 SQLite，无需另装数据库。
• pnpm 11：当前持续集成固定为 11.19.0。
• FFmpeg：音频裁剪、媒体处理与相关测试需要；插件可使用 DSH 已安装的 FFmpeg，或由管理员指定路径。
• Python 与模型引擎：只在启用对应本地媒体能力时需要。

安装 pnpm

安装 Node.js 后，在终端执行：

npm install --global pnpm@11.19.0
node --version
pnpm --version

安装依赖并启动

克隆本仓库或解压源码包，进入包含 package.json 的源码根目录：

cd dsh-starr
pnpm install --frozen-lockfile
pnpm build
pnpm start

浏览器打开 **http://127.0.0.1:17841/**。

pnpm install 安装源码开发依赖；将插件接入 DSH 时，使用上文的 dsh plugin 安装命令。当前源码清单保留 private: true，防止误发布到 npm；上传 GitHub 不受影响。

独立预览默认将数据保存在用户主目录下的 .local/share/dsh-starr-preview。如需指定测试数据目录，在 PowerShell 中设置后启动：

$env:STARR_DATA_DIR = 'E:\starr-preview\runtime'
$env:STARR_PORT = '17841'
pnpm start

独立预览应使用自己的测试数据，宿主插件默认使用 DSH 主目录下的 starr/runtime，也可由管理员设置 dataRoot。独立预览不提供 DSH 宿主模型驱动。

开发模式同时启动接口和前端：

pnpm dev

前端地址为 **http://127.0.0.1:17842/**，接口端口为 17841。

检查与打包

# 格式、类型检查、正式构建与测试
pnpm format:check
pnpm build
pnpm test

# 检查待发布源码
pnpm release:audit

# 构建并生成 DSH 插件包
pnpm pack:plugin

# 生成完整源码归档
pnpm pack:source

控制台集成测试会读取构建后的 dist。全新克隆或解压源码后，请先运行 pnpm build，再运行 pnpm test；dist 由构建生成，不随源码提交。

打包产物默认写入 release/，该目录不会纳入源码版本控制。pack:plugin 会生成 .tgz、运行归档 ZIP、文件清单与校验信息；pack:source 生成独立源码 ZIP。发布流程见GitHub 上传与发布检查。

数据、凭据与资源管理

角色数据库、记忆笔记、表情原图、曲库、模型和备份保存在独立数据目录，不随源码或插件包分发。

Windows 可通过网页录入媒体密钥和 QQ 令牌，并用当前 Windows 用户的系统数据保护接口（API） 加密保存；接口不回显原文。也支持环境变量引用，环境变量优先；其他系统使用环境变量方式。

管理员可以在网页删除当前角色的表情、曲库音源和单个翻唱成品。单项回收保留文件与元数据，缺失原文件时会说明；目前没有网页恢复入口。删除默认参考音色需要确认解除引用，批量成品清理则明确提示永久删除范围。详见资源管理。

当前范围

• QQ、B站收发、分享与定时动态需要逐项开启。真实可用性以当前环境的实际输入、平台回执与模型结果为准。
• 云端兼容接口、参考音色与远程唱歌均依赖具体提供者，协议测试通过不代表任意服务都兼容。
• 当前采用关键词与关系数据检索；插件内 Tabbit 已移除，宿主自身的浏览工具不受影响。B站资料阅读和视觉能力继续保留；向量检索和完整旧格式合并导入仍未接入。
• 旧版功能的继承、移除和待实现状态见旧配置核验表，不将旧版盘点条目等同于当前已上线能力。
• v0.2.4 验证范围见本版验证记录。真实账号外发、模型理解质量和远程节点仍需按对应环境验收。

更多文档

主题	文档
安装与首次配置	安装 · 新手调试 · QQ 排错
会话与模型	DSH 接入 · 全部有效配置
记忆与角色机制	架构与数据 · 心理、身体与目的
媒体与资源	听说看唱 · 音乐检索 · 资源管理
版本与验证	v0.2.4 · 当前验收记录 · 页面清单 · 历史验证
开发与发布	发布检查 · 实施状态 · 旧配置对照

许可与致谢

本仓库原创代码采用 MIT 许可证。第三方代码、库与模型保留各自许可，详见第三方依赖与设计依据。

感谢 React、Three.js、GSAP、Lucide、ThreeUI、SurfCore，以及 dsh-see-now 等项目提供的工具、设计参考和基础能力。SurfCore 的原作者与 MIT 许可声明见 SurfCore 参考与署名；GSAP 使用其标准许可，See Now 核心保留 Apache-2.0 许可与声明；模型权重不包含在插件发行包中。