Mieksido/surfcore

选用指南

AI 根据 README 整理 · 2026/11/1 07:52:08

适用场景

适用于希望在 QQ 群中模拟群友、在 B站 自动互动，并拥有记忆和主动搭话能力的 DSH agent 用户。

查看 README 依据

- **一条腿是独立进程**：`src/bridge.js` —— QQ 收发、会话映射、控制台、安全闸门。 合起来，它让 agent 能： 1. **在 QQ 里当一个群友**：自己判断要不要看、要不要说、说几条、引用谁；说完能判断"这段可以结束了"，带着"下次怎么接"潜水。 2. **在 B站 当一个用户**：有自己的作息、偏好、每日额度；看视频会打分、会评论、会回帖、会发动态。 3. **记得住也忘得掉**：一份会衰减的记忆卡（进提示词）+ 一份永不遗忘的全量卡（只存档）。 4. **会主动找你**：从近期记忆里提炼"我想弄明白/想做点什么"，安静时段主动分享或索取；载体可选 QQ 或桌宠。 5. **有一个桌面分身**：仓库外的 Electron 桌宠可以跟她文字/语音对话，也能接主动搭话的气泡。 > 它**不做**：不代你登录/扫码/绕过平台风控，不做多用户，不把控制台暴露到内网以外， > 不删除任何不可恢复的数据。完整边界见 [BOUNDARIES.md](docs/guides/BOUNDARIES.md)。 --- ## 二、安装（新用户从这里开始） ### 2.1 环境要求 | 需要 | 版本 / 说明 | 必装？ | | --- | --- | --- |

> 模型不进 GitHub（太大）。仓库里只有启动脚本、配置与说明；模型按各自 README 的 `fetch-models` 下载。 ### 3.5 可选装桌宠 [surfpet](https://github.com/Mieksido/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站 行为账本，整包切换。

使用方式

通过命令行安装和配置，运行 npm install 和 setup 脚本，然后通过 DSH 设置页使用。

查看 README 依据

# 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 探活 / 只读联网搜索）；

部署要求

需要 Windows 10/11、Node.js ≥22.13 和 DSH 0.2.1-rc.2 或更新版本；若需 QQ 功能必须安装 SnowLuma2（第三方）。

查看 README 依据

| 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](docs/guides/INSTALL.md)（手把手，含 SnowLuma 配置、白名单、排错表）。 ```bash # 1) 取代码 git clone https://github.com/Mieksido/surfcore.git cd surfcore

已知限制

不支持 Linux/macOS（暂不支持），无法多用户或远程访问，控制台仅限本机回环。

查看 README 依据

| 支持 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](docs/FOLDER_MAP.md)；代码分层与"改什么要重启什么"见