桌面分身 Mieksido/surfcore

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

一句话：它不是「把大模型接进 QQ」的机器人框架，而是给模型一个身份、一套会遗忘的记忆、一份作息、两只手（QQ / B站）和一个能坐在你桌面上的分身。

| 版本 | 0.8.4 |
| 目标 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 条命令）

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 收发、会话映射、控制台、安全闸门。

合起来，它让智能体可以：

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 配置、白名单、排错表）。

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 | 控制台需要令牌才能进 |

最小可用示例（把占位符换成你的）：

{
"snowluma": { "wsUrl": "ws://127.0.0.1:3001", "httpUrl": "http://127.0.0.1:3000", "accessToken": "<SnowLuma token>" },
"ownerQQ": 1000000001,
"allow": { "private": [1000000001], "groups": [100000004] },
"consoleToken": ""
}

其余几百个键都有默认值，全部含义见 DATA-AND-CONFIG.md §1。
装好之后建议一切都在设置页里改（保存即生效，且会自动备份）。

2.4 首次验证

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=<consoleToken> |
| 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/<id>/）。
- 记忆：QQ/B站/桌宠 三个场景写进同一张卡；每 10 分钟摄取一次，会衰减、会遗忘，80/90/100% 告警。
- 示例人格卡在 roles/（已脱敏），记忆卡空壳在 examples/。

3.8 浏览器控制台（可选）

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

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。 |
| 改名/换角色会丢记忆吗？ | 不会。角色包整包隔离，切换带快照，可回档。 |

九、开发

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）或 在线版说明。