Mieksido/surfcore

SurfCore — 给 DSH agent 一个真实的身份：QQ × B站 × 桌宠

中文 | English

一句话：它不是"把大模型接进 QQ"的机器人框架，而是给模型一个身份、一套会遗忘的记忆、

一份作息、两只手（QQ / B站）和一个能坐在你桌面上的分身。

| | | | --- | --- | | 版本 | 0.6.20 | | 目标 DSH | 0.2.1-rc.2 或更新（rc.3 已能安装，功能未完整回归）（npm run verify:adaptation 可逐项复核） | | 平台 | Windows（沙箱 ACL / SnowLuma / 启动脚本都与它绑定） | | 许可 | MIT（SnowLuma 是第三方专有运行时，不随本仓库分发） | | 配套仓库 | surfvoicelocal · surfvoicecloud · surfpet |

🔒 本仓库不含任何真实数据：角色卡是脱敏示例（roles/），记忆卡是空壳（examples/），

群号 / 群友名单 / QQ 号 / B站 mid 全部为占位符。运行时数据永远只在你自己的机器上。

---

让 DSH 自己装（也可以只发一条链接）

把这句话发给 DSH：

帮我安装 https://github.com/Mieksido/surfcore ，按 README 的步骤来。

顺序很重要（DSH 常常先 install_bundle、后装依赖，结果激活时报 Cannot find module '@deepseek-ai/schemastery'）： 1. npm install（没有 npm 就用 DSH 自带的 pnpm：~/.dsh/dsh-runtimes/.../pnpm/bin/pnpm.cjs） 2. 再 plugin_manager install_bundle（或 node scripts/setup-dsh.mjs） 3. 重启 DSH → 设置 → SurfCore → 诊断 → 一键安装

用 junction 链接安装时，模块是从仓库真实路径解析的，所以仓库根必须有 node_modules —— 这就是第 1 步不能省的原因。

两个实测踩过的点（v0.4.5）：

• 必须从仓库根目录安装：插件里有 19 处 ../../../src/xxx.js（人设、存储、token 预算等），

只装 plugins/surfcore 会去找 D:\src\... 然后报模块不存在。

• 装完要刷新页面（F5）或重启 DSH：客户端模块图是页面加载时的快照，新 bundle 要重新拉，

否则设置里暂时看不到 SurfCore —— 不是装坏了。

第一次装（4 条命令）

```powershell git clone --depth 1 https://github.com/Mieksido/surfcore.git cd surfcore npm install node scripts/setup-dsh.mjs # 自动判断 DSH 用的 profile，不用填 ``` 重启 DSH → 设置 → SurfCore → 诊断 → 一键安装（全部）（自动发现 SnowLuma、写白名单、起桥接）。

不想敲命令：powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/Mieksido/surfcore/main/scripts/bootstrap.ps1 | iex"

前置：Windows + Node ≥22.13 + DSH 0.2.1-rc.2 或更新（rc.3 已能安装，功能未完整回归） + SnowLuma（第三方，需自己装并扫码）。详见 INSTALL.md。 ---

目录

• 一、这是什么
• 二、安装（新用户从这里开始）
• 三、日常使用
• 四、能力总览
• 五、架构一图
• 六、文档地图
• 七、安全与边界
• 八、常见问题（FAQ）
• 九、开发
• 十、许可与合规

---

一、这是什么

一个跑在你自己电脑上的双进程系统：

• 一条腿在 DSH 里：surfcore 插件 —— 设置窗口、B站 生物钟、记忆卡维护、桌宠接口。
• 一条腿是独立进程：src/bridge.js —— QQ 收发、会话映射、控制台、安全闸门。

合起来，它让 agent 能： 1. 在 QQ 里当一个群友：自己判断要不要看、要不要说、说几条、引用谁；说完能判断"这段可以结束了"，带着"下次怎么接"潜水。 2. 在 B站 当一个用户：有自己的作息、偏好、每日额度；看视频会打分、会评论、会回帖、会发动态。 3. 记得住也忘得掉：一份会衰减的记忆卡（进提示词）+ 一份永不遗忘的全量卡（只存档）。 4. 会主动找你：从近期记忆里提炼"我想弄明白/想做点什么"，安静时段主动分享或索取；载体可选 QQ 或桌宠。 5. 有一个桌面分身：仓库外的 Electron 桌宠可以跟她文字/语音对话，也能接主动搭话的气泡。

它不做：不代你登录/扫码/绕过平台风控，不做多用户，不把控制台暴露到内网以外，

不删除任何不可恢复的数据。完整边界见 BOUNDARIES.md。

---

二、安装（新用户从这里开始）

2.1 环境要求

| 需要 | 版本 / 说明 | 必装？ | | --- | --- | --- | | Windows | 10/11（沙箱 ACL 与 .bat 启动器按 Windows 写） | ✅ | | Node.js | ≥ 22.13（node -v 确认） | ✅ | | DeepSeek Harness（DSH） | 0.2.1-rc.2 或更新（rc.3 已能安装，功能未完整回归），能正常打开 Web GUI | ✅ | | SnowLuma2 | 第三方 QQ 运行时，自己去官方 Releases 下载并扫码登录 | ✅（只收 QQ 才需要） | | 语音引擎 | 两个配套仓库之一（本地/云端） | ⭕ 可选 | | 桌宠 | 配套仓库 surfpet | ⭕ 可选 |

⚠️ SurfCore 不下载、不安装、不打包 SnowLuma（EULA §5.4）。它只做"检测已安装 + 一键打开窗口 + 连接状态"，

登录与扫码始终由你自己完成。

2.2 五步装好

第一次装、或卡在某一步：看 INSTALL.md（手把手，含 SnowLuma 配置、白名单、排错表）。

```bash

1) 取代码

git clone https://github.com/Mieksido/surfcore.git cd surfcore

2) 装依赖（postinstall 会自动修补 @snowluma/sdk 的 ESM bug）

npm install

3) 复制配置模板，然后编辑 config.json（见 2.3，只填 4 处）

Windows CMD: copy config.example.json config.json

cp config.example.json config.json

4) 装进 DSH（preset + 三个 MCP server + surfcore bundle，幂等，可重复跑）

node scripts/setup-dsh.mjs

5) 重启 DSH → 设置里出现 SurfCore →

在「概览」点「启动QQ」（或命令行 npm start / start.bat）

``` setup-dsh.mjs 做三件事： 1. 把 qq-chat / qq-chat-v2 两条 agent preset 插进 DSH profile（DSH 0.1.7 起的 bundle patch 机制）； 2. 在 profile 的 cordis.patch.yml 挂 三个 MCP server（QQ 工具 / SnowLuma 探活 / 只读联网搜索）； 3. 在 profile package.json 注册唯一一个 bundle：surfcore。

需要装到别的 profile：node scripts/setup-dsh.mjs <profile名>（默认 web）。

2.3 最小配置（只填这 4 处）

打开仓库根目录的 config.json： | 位置 | 填什么 | 不填会怎样 | | --- | --- | --- | | snowluma.wsUrl / httpUrl / accessToken | SnowLuma 的 OneBot WS、HTTP、token（HTTP 与 WS 可能是两个不同的值） | 桥接连不上 QQ，控制台显示"未连接" | | ownerQQ | 你自己的 QQ 号（closed-agent 模式只认这个人） | 管理员功能失效 | | allow.private / allow.groups | 允许她接触的私聊/群（数组） | 白名单为空 = 谁都不响应（不是全放行） | | consoleToken | 控制台令牌；留空会自动生成到 state/console-token | 控制台需要令牌才能进 | 最小可用示例（把占位符换成你的）： ```jsonc { "snowluma": { "wsUrl": "ws://127.0.0.1:3001", "httpUrl": "http://127.0.0.1:3000", "accessToken": "" }, "ownerQQ": 1000000001, "allow": { "private": [1000000001], "groups": [100000004] }, "consoleToken": "" } ```

其余几百个键都有默认值，全部含义见 DATA-AND-CONFIG.md §1。

装好之后建议一切都在设置页里改（保存即生效，且会自动备份）。

2.4 首次验证

```bash npm run test:audit # 离线回归（不联网、不发消息） node scripts/check-onebot-status.mjs # OneBot 连通性（只读） node scripts/verify-dsh-020-adaptation.mjs # 对本机 DSH 版本逐项复核 ``` 真机验证三件事：在群里 @ 她 → DSH 里出现对应会话 → 回复回到 QQ。

2.5 安装常见失败

| 症状 | 原因 | 处理 | | --- | --- | --- | | 设置页找不到 SurfCore | bundle 没装上 / DSH 没重启 | 重跑 setup-dsh.mjs，重启 DSH | | 桥接起来了但收不到消息 | SnowLuma 未登录 / token 不对 / WS 端口不是 3001 | 控制台「运行总览」看状态；对照 config.json 的 snowluma.* | | 群里 @ 她没反应 | 白名单没加这个群 / 模式不对 / 已暂停 | 看「访问与安全」页；确认 allow.groups | | agent 只会说话、不调工具 | MCP 没挂上 / 工具被安全守卫隐藏 / 工具开关关了 | 重跑 setup-dsh.mjs；看设置页工具开关 | | 控制台 401 | 没带令牌 | 用 http://127.0.0.1:3100/?token= | | npm install 后启动报 ESM 错 | postinstall 补丁没跑 | npm rebuild 或手动 node scripts/patch-snowluma-sdk.mjs | 更多故障与恢复见 BOUNDARIES.md §3。 ---

三、日常使用

3.1 设置页（DSH → 设置 → SurfCore）

14 个标签：概览 / 角色 / 目的 / QQ / 语音 / 桌宠 / B站 / Token 额度 / 观看历史 / 记忆 / 对齐 / 扩展 / 全部参数 / 诊断。 逐个说明见 UI-AND-CONSOLE.md。

3.2 四种运行模式

| 模式 | 她是谁 | 能干什么 | | --- | --- | --- | | chat | 群友 | 白名单内聊天，工具面受安全守卫限制 | | closed-agent | 只理管理员 | 私聊 owner，可用完整 DSH 工具 | | reserved | 一代仿真群友 | 状态机 + 空格分条 + [SILENT] | | reserved2 | 二代仿真群友（默认） | 一切皆工具：自己看消息、发言、等待、潜水、收尾 |

3.3 让她主动找你（可选）

设置页「目的」：选载体（QQ / 桌宠）、节奏、安静时段；先点预览（零副作用）再"试一次"。 硬闸门：安静时段 / 每日上限 / 主人在聊 / token 额度 / 专注模式。

3.4 可选装语音

两个独立仓库（surfvoicelocal / surfvoicecloud），装在仓库外面： | 仓库 | 端口 | 特点 | | --- | --- | --- | | surfvoicelocal | 8765 | 本地 GPT-SoVITS，免费、断网可用 | | surfvoicecloud | 8767 | 云端声音复刻，质量最好、按字符计费 | 装法：git clone 到 surfcore/state/voice-packs/voice-local（或 voice-cloud）→ 按该仓库 README 下载模型 → run.bat → 回到 SurfCore 设置 → 语音 选本地/云端并点「启动」。 AI 发语音默认关闭（socialV2.voice.enabled=false + 工具开关 tools.sendVoice），要显式打开。

模型不进 GitHub（太大）。仓库里只有启动脚本、配置与说明；模型按各自 README 的 fetch-models 下载。

3.5 可选装桌宠

surfpet：Electron 桌面分身（Release 里有安装包）。用户装 Release 的 zip，开发者 clone 源码自己构建。 装法：设置页 桌宠 → 填 zip 地址/目录 → 安装 → 选 electron.exe → 启动。 装好后：右键「文本对话 / 语音对话」，气泡上所有她的话都有「回复」按钮，右键/托盘有专注模式。

桌宠通过 ~/.dsh/surfcore/pet/host.json 发现插件接口（本机 + 一次性令牌），不需要 DSH 的登录态。

3.6 B站（可选）

设置页 B站 → 扫码登录 → 填作息窗口（例如 20:00–24:00）→ 选偏好 → 设额度。 她会在窗口内自己看视频、打分、评论、发动态；默认不分享到 QQ（可开）。

3.7 角色与记忆

• 角色包 = 人格卡 + 记忆卡 + B站 行为账本，整包切换。
• 新建：设置页「角色」→ 新建（或复制 examples/character/ 到 ~/.dsh/surfcore/characters//）。
• 记忆：QQ/B站/桌宠 三个场景写进同一张卡；每 10 分钟摄取一次，会衰减、会遗忘、80/90/100% 告警。
• 示例人格卡在 roles/（已脱敏），记忆卡空壳在 examples/。

3.8 浏览器控制台（可选）

http://127.0.0.1:3100/?token=：运行总览、会话与审批、令牌与花费、访问与安全、调试与运维、工具参考。 只接受本机回环访问。

3.9 检查更新

设置 → 概览 → 更新：一次同时查 SurfCore / 两个语音包 / 桌宠。

• 本体与语音包走 git（fetch 只读 + merge --ff-only；本地有改动会拒绝）；
• 桌宠走 Release 的 version.json（比版本号 → 下 zip → sha256 校验 → 替换，保留 data/）；
• DSH 启动后 20 秒自动查一次，有更新时打开概览会弹窗，可勾「不再提示本次」。

---

四、能力总览

| 子系统 | 你能看到的能力 | 细节 | | --- | --- | --- | | QQ | 群/私聊收发、引用回复、分条、表情包、图片/动图、语音、拍一拍、合并转发展开、上线补历史、提问/审批回传、四种运行模式 | MODULE-BRIDGE.md | | B站 | 扫码登录、看视频/打分/收藏、评论与回帖、发动态、分享到 QQ、私信、直播间监听、34 个 CLI 命令 | SUBSYSTEM-BILI.md | | 记忆 | 衰减卡（清晰度/遗忘/容量告警/压缩）、全量卡（append-only）、三场景共享、隐私 scope、双向记忆 | MEMORY_CARD.md | | 人格 | 多角色整包切换、自动存档/回档、管理员双身份、身份对齐 | CHARACTER_PERSONA.md | | 主动 | 目的机制（目标假设/载体 QQ·桌宠/互斥回落）、对话收尾、二代 proactive | PURPOSE_OUTREACH.md | | 语音 | 语音库发送、本地/云端 TTS 现场合成、语音包安装启停、音量/响度、频率上限；qq_send_voice / qq_list_voices（AI 发语音默认关闭） | SUBSYSTEM-VOICE.md | | 桌宠 | 文本/语音对话、气泡与回复按钮、专注模式、目的载体、断线重连 | SUBSYSTEM-PET.md | | 额度 | 每日 token 额度（QQ/B站/其他/总额，双单位，80% 提醒、100% 停）、消费看板 | DATA-AND-CONFIG.md | | 工具面 | 39 个 qq_* 工具、三个 MCP server、两代 preset、fail-closed 工具守卫 | AGENT-TOOLS-AND-PRESETS.md | | 界面 | 设置页 14 个标签、控制台 10 个页面 | UI-AND-CONSOLE.md | ---

五、架构一图

``` ┌──────────────── 用户可见 ────────────────┐ │ DSH Web GUI 控制台 :3100 桌宠窗口 │ └──────┬──────────────┬─────────────┬──────┘ ┌──────▼──────────────▼─────────────▼──────────────────────────┐ │ DSH 宿主 └─ surfcore 插件（bundle） │ │ 设置页 · 设置页 API · 桌宠 API · B站调度 · 记忆卡 · 额度 │ └──────┬───────────────────────────────────────────────────────┘ │ HTTP（会话 Cookie） + 子进程管理 ┌──────▼───────────────────────────────────────────────────────┐ │ QQ 桥接进程（node src/bridge.js，单实例） │ │ OneBot WS · DSH 客户端 · 控制台 :3100 · 三个 MCP server │ └──┬────────────┬──────────────┬───────────────────────────────┘ │ WS │ stdio │ HTTP ┌──▼────────┐ ┌─▼──────────┐ ┌─▼─────────────────┐ │ SnowLuma2 │ │ DSH MCP │ │ 语音引擎 8765/8767 │ │（第三方） │ │ 客户端 │ │（surfvoice*） │ └───────────┘ └────────────┘ └───────────────────┘ ```

• 两套状态根：桥接数据在 <仓库根>/state/，插件数据在 ~/.dsh/surfcore/。
• 三份配置：config.json（QQ）、~/.dsh/surfcore/config.json（合体层）、~/.dsh/surfcore/bili.config.json（B站）。
• DSH 端口会漂移：桥接与插件都用 discoverDshBaseUrl() 发现，不要硬编码。

完整说明（含 6 条数据流与重启矩阵）：ARCHITECTURE.md。 ---

六、文档地图

2026-10-26 全仓库逐行梳理：12 篇、约 8,700 行、3,150 处 文件:行号。

| 步 | 读什么 | 读到什么程度 | | --- | --- | --- | | 1️⃣ 5 分钟 | 本文 | 它是什么、怎么装 | | 2️⃣ 15 分钟 | ARCHITECTURE.md | 几个进程、怎么分层、改什么要重启什么 | | 3️⃣ 按需 | 下面分册 | 改哪个子系统翻哪本 | | # | 文档 | 行数 | 什么时候翻它 | | --- | --- | --- | --- | | 1 | ARCHITECTURE.md | 335 | 总纲 | | 2 | DATA-AND-CONFIG.md | 351 | 三份配置每个键、约 95 个状态文件 | | 3 | BOUNDARIES.md | 181 | 做不到什么、坏了怎么恢复 | | 4 | MODULE-BRIDGE.md | 1,020 | 桥接全文 | | 5 | MODULE-CORE-A.md | 1,001 | 记忆/人格/目的/收尾/额度/账本/计价/身份 | | 6 | MODULE-CORE-B.md | 1,098 | B站/鱼群/表情/黑话/文本化/SSRF/DSH 客户端 | | 7 | MODULE-PLUGIN.md | 1,101 | 插件宿主：装配、配置模型、设置页 API、B站 调度 | | 8 | UI-AND-CONSOLE.md | 677 | 设置页 14 标签 + 控制台 10 页 | | 9 | SUBSYSTEM-VOICE.md | 855 | 语音三条链路 | | 10 | SUBSYSTEM-PET.md | 904 | 桌宠全链路 | | 11 | SUBSYSTEM-BILI.md | 981 | B站 34 命令 / 23 库 | | 12 | AGENT-TOOLS-AND-PRESETS.md | 233 | 39 个工具、守卫、两代 preset | 其它：DSH 装配 DSH_SETUP.md · 安全基线 SECURITY_BASELINE.md · 踩坑 PITFALLS.md · 风险台账 RISK_REGISTER.md · 全部索引 docs/README.md。 ---

七、安全与边界（摘要）

• 群友碰不到你的机器：仿真会话的工具面是白名单、fail-closed，本地执行能力全部被 restrict。
• 发送必须命中白名单：没有"管理员例外"这种后门。
• 控制台只接受本机回环 + 令牌（定长比较）+ Host/Origin 校验 + 写操作强制 JSON。
• 密钥不落日志；state/ 用 icacls 切断 ACL 继承。
• 不可逆删除 = 事故：清理一律先隔离到 _backups/。
• 不承诺提示注入的语义层 100% 防护（真正的边界是工具面与白名单）。

详见 SECURITY_BASELINE.md、BOUNDARIES.md、RULES.md。 ---

八、常见问题（FAQ）

| 问题 | 回答 | | --- | --- | | 能不装 SnowLuma 吗？ | QQ 部分不能（它负责登录与收发）。只要 B站/记忆/桌宠可以。 | | 能不用 DSH 吗？ | 不能，插件与 preset 都跑在 DSH 里。 | | 会自己发消息吗？ | 默认不会。主动搭话要显式开「目的」；二代下发言必须调工具。 | | 数据会上传吗？ | 只有拼进提示词的文本会发给模型 API；不想让黑话词条出机就关 slang.autoResearch。 | | 支持 Linux/macOS 吗？ | 暂不支持（沙箱 ACL 与启动脚本按 Windows 写）。 | | 能多用户/远程吗？ | 不做。控制台只接受回环。 | | 语音包/桌宠必须装吗？ | 不必须。不装则语音不可用、目的机制走 QQ。 | | 改名/换角色会丢记忆吗？ | 不会。角色包整包隔离，切换带快照，可回档。 | ---

九、开发

```bash npm run test:audit # 默认门禁（75 个脚本，离线） npm run test:regressions # 桥接/协议回归 cd plugins/surfcore && npm test # 插件侧（含更新检查、桌宠更新保留数据的回归） npm run privacy-scan:strict # 发布前隐私扫描（0 命中才可发布） npm run guard:check # DSH 升级后先跑（asar 会话护栏补丁是否还在） node scripts/setup-dsh.mjs # 重装 preset + MCP ``` 目录结构见 docs/FOLDER_MAP.md；代码分层与"改什么要重启什么"见 ARCHITECTURE.md。 ---

十、许可与合规

• 本仓库 MIT。
• SnowLuma2 是第三方专有组件，不随仓库分发、不打包；按 EULA §5.4，本程序不对它做安装/部署/代扫码。
• 请自行遵守 QQ / B站 服务条款与当地法律；本项目不提供绕过风控的能力。

老版本（≤0.6.18）无法自动更新：用 强制更新提示词.txt（复制给 DSH）或 在线版说明。