dsh-qiyu-stack 0.0.0-stage → 0.15.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qiyu-dsh-stack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# 栖语栈 · dsh-qiyu-stack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让一个智能体**住进 QQ**：能听会说、记得住人、有自己的作息，还不会在群里刷屏。
+
+名字来自「栖」——模型不是被调用一次就消失的 API，它得有地方住：有人格、有记忆、有作息的日常。
+
+---
+
+## 它解决什么问题
+
+自己从头搭一个「住在 QQ 里的智能体」，最难的往往不是模型，是这几件脏活：
+
+1. **怎么稳定收发 QQ 消息** —— 这块的坑深到离谱（见 [docs/deployment.md](docs/deployment.md)）
+2. **怎么让她像人** —— 什么时候说话、什么时候闭嘴、被 @ 要应、不刷屏
+3. **怎么记住人** —— 记忆不是把聊天记录全塞回去
+4. **怎么有日常** —— 作息、主动搭话、别半夜冒出来
+
+栖语栈把这四件事做成**能直接跑的东西**，而不是一份教程。
+
+---
+
+## 一个设计决定：行为给默认，性格留白
+
+| 层 | 默认给不给 | 内容 |
+|---|---|---|
+| **行为层** | ✅ 给 | 怎么说话、群里何时闭嘴、被 @ 要应、不刷屏、不编记忆、边界 |
+| **性格层** | ⬜ 留白 | 名字、年龄、口吻、喜欢/讨厌、口头禅、写给她的信、表情包 |
+
+原因很实在：**纯白纸的智能体在群里会翻车**——它不知道「群消息可以不理」，会每条都接；
+不知道「不要一次发五条」，会刷屏。这些是**工程问题**，不该让每个使用者重踩一遍。
+
+而「她叫什么、几岁、说话冲不冲」才是该留白的部分。
+
+所以默认起来是：**行为层齐全 + 性格层空白 + 一个空表情包目录**（她不会自己发自拍）。
+
+---
+
+## 第二条红线：默认值里不许有「别人的东西」
+
+这条是踩了一脚写下来的。某个插件把作者的称呼 `小鱿鱼` 写成了默认值，
+还落进了用户的配置 —— 用户打开设置页，看到一个自己从没设过的名字。
+
+所以栖语栈里：
+
+- **代码默认值**只能是空的或中性的（`port: 0`、`container: 'napcat-qq'`、`音色: ''`）
+- **模板**里全是空字段，一个真实 QQ 号、真实路径、作者名字都不许出现
+- **你自己的值**放在本机配置里，且不进版本库：`qiyu.config.json`、`characters/<名字>/`
+- `qiyu doctor` 会**自动扫模板**，发现本机路径 / 作者角色名 / 像 QQ 号的数字 / 令牌就报警
+
+判断标准只有一句：**换一个陌生人来装，这个值还对吗？**
+
+细节和反面例子：[docs/conventions.md](docs/conventions.md)
+
+---
+
+## 快速开始
+
+```bash
+# 0. 先看这台机器行不行（Node / Windows / WSL / 路径 / 空间 / 网络 / 杀软 / DSH / 模型 / Python）
+npx dsh-qiyu-stack preflight
+
+# 1. 建一个角色 —— 会问你几个问题（名字 / QQ / 称呼 / 作息 / 性格 / 能不能自己改性格）
+npx dsh-qiyu-stack init
+
+#    不想被问就带名字，全用默认值：npx dsh-qiyu-stack init 小满
+
+# 2. 填她自己的东西
+#    characters/小满/AGENTS.md      「性格」那几行
+#    characters/小满/character.json  QQ 号 / 称呼 / 语音 / 路径（模板里全是空的）
+
+# 3. 起 NapCat —— 一条命令：建目录、写 OneBot 配置、跑容器、出码
+npx dsh-qiyu-stack deploy --qq 你的QQ号
+
+# 4. 把运行时（QQ 桥/记忆/心情/作息）装进 DSH，并让她成为「活动角色」
+npx dsh-qiyu-stack install --character 小满 --yes      # 装完重启 DSH（关掉窗口再开，不用重启电脑）
+
+# 5. 扫码（图会自动打开），然后自查
+npx dsh-qiyu-stack doctor
+```
+
+> **用 npx 也没关系。** `install` 会先把运行时装一份到 `~/.dsh/qiyu/runtime/`，
+> profile 里的 `file:` 依赖指向那份**稳定副本**，不是 qiyu 包自己的位置。
+> npx 的临时缓存被清掉、或者你把 qiyu 删了，DSH 那边照样能跑。
+
+`doctor` 会逐项告诉你：Docker 在不在、容器起没起、三个端口通不通、OneBot 认不认得出人、
+事件流连不连得上、DSH 桥接没接上。**每条失败都带一句怎么修。**
+
+---
+
+## 目录结构
+
+```
+dsh-qiyu-stack/              引擎（角色无关，可升级）
+├── bin/qiyu.mjs             命令行入口
+├── src/
+│   ├── config.mjs           配置（文件 + 环境变量）
+│   ├── init.mjs             建角色包
+│   ├── deploy.mjs           起 NapCat（建目录/写配置/跑容器/出码）
+│   ├── doctor.mjs           自检
+│   └── qr.mjs               取二维码并直接打开
+├── tools/
+│   └── merge-settings-tabs.mjs   把插件设置合并成「一个页面 + 页签」
+├── runtime/                 运行时五块（从真跑着的机器上搬来、洗过私人值）
+│   ├── bridge/              QQ ↔ DSH 双向（全配置驱动）
+│   ├── memory/              长期记忆（含 1MB 中文词典）
+│   ├── mood/                心情
+│   ├── rhythm/              作息 / 主动搭话
+│   └── voice/               语音转写脚本（TTS 还在 bridge 里，待拆）
+├── templates/
+│   └── blank/               默认模板：行为齐全、性格空白、character.json 全空
+├── docs/
+│   ├── deployment.md        部署（含 Windows 版为什么一定失败）
+│   ├── settings-tabs.md     插件设置合并成页签（含回滚）
+│   └── conventions.md       默认值里不许有别人的东西（含反面例子）
+└── examples/                样板角色（以后放去隐私后的例子）
+
+characters/小满/              你的角色包（不进版本库）
+├── AGENTS.md                人格
+├── character.json           她的号 / 称呼 / 语音 / 路径（模板里全空）
+├── schedule.json            作息
+├── letters/                 写给她的信（默认空）
+├── stickers/                表情包（默认空）
+├── inbox/                   收到的图（默认空）
+├── diary/                   日记本（默认空）
+├── voice/                   她说的话（默认空）
+└── memory/                  长期记忆（默认空）
+```
+
+---
+
+## 现在的进度（v0.9）
+
+已经能用：
+
+- [x] **`qiyu init` 向导**：问名字、QQ、称呼、作息、性格、「能不能自己改性格」；
+      每个问题都有默认值，回车就过；带名字调用则全用默认值（给脚本用）
+- [x] **`qiyu deploy`** 一条命令起 NapCat：查 Docker → 查端口 → 建目录 → 写 OneBot/WebUI 配置
+      → 拉镜像 → 跑容器 → 等 WebUI → **直接打开二维码**；令牌自动生成并写回 `qiyu.config.json`
+- [x] `qiyu doctor` 全链路自检 + **模板体检**（扫出别人的路径/名字/QQ号/令牌）
+- [x] `qiyu qr` 取登录二维码并**自动打开**（不是甩个路径让你自己找）
+- [x] `tools/merge-settings-tabs.mjs` 一条命令把五六个插件的设置收进「插件」页做页签，
+      带 `--dry-run` / `--restore`（见 [docs/settings-tabs.md](docs/settings-tabs.md)）
+- [x] 部署文档：Docker + NapCat + 一个必勾的「下次登录无需确认」
+- [x] 行为层人格模板
+- [x] 默认值红线：中性默认 + 本机配置分离（见 [docs/conventions.md](docs/conventions.md)）
+- [x] **runtime/ 五块已收进仓库**：bridge 全配置驱动、memory/mood/rhythm 原样搬、voice 只搬了脚本
+      （私人路径/角色名/QQ号/令牌已清干净，见 [runtime/README.md](runtime/README.md)）
+- [x] **`qiyu install`** 把 runtime 装进 DSH profile：默认只列清单，`--yes` 才动手；
+      目标已存在就跳过（`--force` 覆盖且先备份），`profile/package.json` 改动前必留 `.bak`
+- [x] **语音拆干净了**：`bridge/lib/voice.mjs` 管「说 + 听」，桥只管「向 NapCat 要 wav」；
+      `install` 会把转写脚本放到 `~/.dsh/qiyu/`
+- [x] **配置收敛到活动角色**：`install --character 小满` 把角色包拷到 `~/.dsh/qiyu/`，
+      桥读身份的优先级变成 **`character.json` > `qq-bridge-config.json` > 代码默认值**
+      （改人只改角色包，不碰插件配置）
+
+- [x] **端到端真跑过一次**：空白 DSH profile → `qiyu install` → 起独立实例 → 桥接上备号
+      → 发消息进群 ✅ → 群里 @ 她，话被转进会话 ✅（最后「她回话」那步因测试 profile 没配模型没验）
+
+还差的：
+
+- [x] ~~`memory` / `mood` / `rhythm` 也改读活动角色~~ —— 都接上了：
+      rhythm 读 `schedule.json` 的时段、mood 读 `名字`/`称呼.主人`、memory 的名字兜底读 `名字`
+
+> 五块现在**都从活动角色读配置**了：改 `characters/<名字>/` 就能换人，不用碰插件配置。
+
+> 这一段是**从已验证能跑的实现里抽出来的**，不是照文档重写。
+
+---
+
+## 许可
+
+MIT。你养出来的角色，是你自己的。

package/bin/qiyu.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// 栖语栈 CLI —— 只有一个入口，命令都在这里分发。
+//
+//   qiyu init <名字> [--preset blank]   生成一个角色包
+//   qiyu deploy                         一条命令起 NapCat：建目录、写配置、跑容器、出码
+//   qiyu doctor                         自检：Docker / 容器 / 端口 / OneBot / 桥
+//   qiyu qr                             取登录二维码并直接打开
+//   qiyu config                         看一眼当前配置从哪来
+//   qiyu help
+
+import { init } from '../src/init.mjs'
+import { doctor } from '../src/doctor.mjs'
+import { qr } from '../src/qr.mjs'
+import { deploy } from '../src/deploy.mjs'
+import { install } from '../src/install.mjs'
+import { preflight } from '../src/preflight.mjs'
+import { 读配置, 配置文件路径 } from '../src/config.mjs'
+
+const 参数 = process.argv.slice(2)
+const 命令 = 参数[0] || 'help'
+
+function 取值(名, 兜底 = null) {
+  const i = 参数.indexOf(名)
+  if (i === -1) return 兜底
+  const 下一个 = 参数[i + 1]
+  if (!下一个 || 下一个.startsWith('--')) return 兜底
+  return 下一个
+}
+
+function 有开关(名) {
+  return 参数.includes(名)
+}
+
+const 帮助 = `
+栖语栈 qiyu —— 让一个智能体住进 QQ
+
+用法：
+  qiyu init                     进向导：问名字、QQ、称呼、作息、性格、能不能自己改
+       qiyu init <名字>          跳过向导，全部用默认值直接建
+       --preset <模板>          blank（以后再加）
+       --qq / --as / --rhythm / --personality / --self-edit   非交互时直接给值
+       --force                  目录已存在时覆盖
+
+  qiyu preflight                装之前先查这台机器：Node / Docker / Windows / WSL / 路径 /
+                                空间 / 网络 / 杀软 / DSH / 模型凭证 / Python
+                                （不假设 Docker 已经装了）
+       --fix                    能修的帮你修：启动 Docker 引擎、停掉占端口的容器、装 edge-tts
+                                （每一项都会先问一句，非交互环境不动手）
+
+  qiyu deploy                   一条命令起 NapCat：建目录、写 OneBot 配置、跑容器、出码
+       --dir <目录>             数据放哪（默认挑非系统盘里空间最大的；会检查空间和中文路径）
+       --move                   换目录时，把旧目录的数据整体搬过去
+       --qq <号>                她的 QQ 号（给了就开快速登录，重启容器免扫码）
+       --name <容器名>          默认 napcat-qq
+       --token/--ws-token/--webui-token   自己指定令牌（不给就随机生成）
+       --dry-run                只把 docker 命令打出来，不动手
+
+  qiyu doctor                   自检：Docker / 容器 / 端口 / OneBot / 桥
+       --json                   只输出 JSON（给脚本用）
+       --skip-ws                跳过 WebSocket 检查
+
+  qiyu qr                       把登录二维码取出来并**直接打开**给你扫
+                                （不会只给一个路径让你自己找文件）
+
+  qiyu install                  把 runtime 五块装进 DSH profile
+       --profile <目录>         默认 ~/.dsh/profiles/desktop
+       --character <名字>       顺便把这个角色设为「活动角色」（拷到 ~/.dsh/qiyu/）
+       --only bridge,memory     只装其中几块
+       --dry-run                只列清单，不动手
+       --yes                    真装（不加就只提示）
+       --force                  已存在也覆盖（覆盖前自动备份）
+
+  qiyu config                   显示配置来源（文件 / 环境变量 / 默认值）
+
+配置文件：qiyu.config.json（当前目录），也可以用环境变量覆盖：
+  QIYU_ONEBOT_TOKEN   OneBot HTTP 令牌
+  QIYU_WS_TOKEN       OneBot WS 令牌
+  QIYU_DSH_PORT       DSH 的端口（不配就跳过 DSH 桥检查）
+`
+
+async function 主() {
+  if (命令 === 'help' || 命令 === '--help' || 命令 === '-h') {
+    console.log(帮助)
+    return 0
+  }
+
+  if (命令 === 'init') {
+    const 名字 = 参数[1]
+    // 不带名字 = 进向导（问名字、作息、性格…）；带名字 = 老样子，用默认值直接建
+    if (!名字 || 名字.startsWith('--')) {
+      if (有开关('--yes')) {
+        console.error('--yes 需要一个名字：qiyu init 小明 --yes')
+        return 1
+      }
+      const { wizard } = await import('../src/wizard.mjs')
+      return await wizard()
+    }
+    return await init(名字, {
+      模板: 取值('--preset', 'blank'),
+      覆盖: 有开关('--force'),
+      答案: {
+        qq: 取值('--qq', ''),
+        称呼: 取值('--as', '你'),
+        作息: 取值('--rhythm', 'regular'),
+        性格: 取值('--personality', 'blank'),
+        自改: 取值('--self-edit', 'ask'),
+      },
+    })
+  }
+
+  if (命令 === 'doctor' || 命令 === 'status') {
+    return await doctor({ 只输出JSON: 有开关('--json'), 跳过WebSocket: 有开关('--skip-ws') })
+  }
+
+  if (命令 === 'preflight' || 命令 === 'check') {
+    return await preflight({ 修复: 有开关('--fix') })
+  }
+
+  if (命令 === 'qr' || 命令 === 'login') {
+    return await qr()
+  }
+
+  if (命令 === 'deploy') {
+    return await deploy({
+      名字: 取值('--name'),
+      镜像: 取值('--image'),
+      目录: 取值('--dir'),
+      qq: 取值('--qq'),
+      token: 取值('--token'),
+      ws令牌: 取值('--ws-token'),
+      webui令牌: 取值('--webui-token'),
+      搬: 有开关('--move'),
+      干跑: 有开关('--dry-run'),
+    })
+  }
+
+  if (命令 === 'install') {
+    return await install({
+      profile: 取值('--profile'),
+      只: 取值('--only'),
+      角色: 取值('--character'),
+      干跑: 有开关('--dry-run'),
+      确认: 有开关('--yes'),
+      覆盖: 有开关('--force'),
+    })
+  }
+
+  if (命令 === 'config') {
+    const 配置 = 读配置()
+    console.log('配置文件：' + 配置文件路径())
+    console.log(JSON.stringify(配置, null, 2))
+    return 0
+  }
+
+  console.error('不认识的命令：' + 命令)
+  console.log(帮助)
+  return 1
+}
+
+主()
+  .then((码) => process.exit(码 || 0))
+  .catch((错) => {
+    console.error('出错了：' + ((错 && 错.message) || 错))
+    process.exit(1)
+  })

package/docs/conventions.md

@@ -0,0 +1,111 @@
+# 默认值里不许有「别人的东西」
+
+这条是踩了一脚才写下来的。
+
+## 教训
+
+`dsh-bili-subagent` 里有个字段 `ownerName`（设置页叫「称呼」），代码里写着：
+
+```js
+ownerName: z.string().default('小鱿鱼')
+```
+
+`小鱿鱼` 是插件作者自己的称呼。它不只是个默认值 —— 它被写进了用户的
+`cordis.patch.yml`，而配置优先级是「设置页 > 插件 config.json > 代码默认值」，
+于是用户打开设置页，看到的是**一个自己从没设过的名字**，还以为是自己填错了。
+
+**一个默认值，能让用户对自己的配置产生怀疑。**
+
+## 规矩
+
+| 层 | 放什么 | 例子 |
+|---|---|---|
+| **代码默认值** | 空的，或对任何陌生人都成立的中性值 | `port: 0`、`container: 'napcat-qq'`、`音色: ''` |
+| **模板** | 空字段 + 说明「这里填你自己的」 | `templates/blank/character.json` |
+| **本机配置** | 用户自己的真实值，且**不进版本库** | `qiyu.config.json`、`characters/<名字>/` |
+
+## 对用户说的话，还有两条硬规矩
+
+### ① 「重启」必须带宾语
+
+用户看到「重启一下」会愣住：重启电脑？重启 DSH？重启 Docker？
+
+所以每一处都写清**重启的对象和范围**：
+
+| 场景 | 该怎么说 |
+|---|---|
+| 装完 Docker Desktop | 「重启**这台电脑**（不是重启 DSH）」 |
+| 装完插件 / bundle | 「重启 **DSH**：把窗口关掉再打开（不用重启电脑）」 |
+| 改了容器配置 | 「重启**容器**：`docker restart <名>`（不用重启电脑）」 |
+| 改了 client.js 样式 | 「**刷新页面**（Ctrl+R）就行，不用重启」 |
+
+### ② 会自动弹窗的动作，必须提前说清「弹的是什么」
+
+用户最怕的是：莫名其妙跳出来一个页面，上面问要 token。
+
+所以凡是会自己打开东西的地方，**先一句预告，再动手**——而且要说到「这是什么、为什么要它」：
+
+- **二维码**：「会弹出 QQ 的登录码（图片窗口）。用你要登的那个号拿手机 QQ 扫它，扫完那个号就登进容器了，之后别人发消息才会走到你这边。」
+  （只说「弹出一张二维码」不够——用户不知道扫码是在干什么。）
+- **启动 DSH**：「DSH 启动时可能自己弹一个浏览器窗口，那是它自己的界面，不是报错；里面的 QQ 设置已经填好了，不用改。」
+- **NapCat 的 WebUI**：能不提就不提。真要提，一句话说清「日常用不到、只监听本机、token 在哪」。
+  实测：NapCat 容器里没有浏览器，它自己**不会**开弹窗；用户看到的窗口多半是 DSH 开的。
+
+反面例子（真实发生过）：用户第一次部署，浏览器弹出 NapCat 的 token 输入页，他不知道那是什么、也不知道 token 在哪，只能来问。
+
+## 一个值能不能当默认值？问一句：
+
+> **换一个陌生人来装，这个值还对吗？**
+
+对 → 可以。不对 → 不能。
+
+| 值 | 能不能当默认 | 为什么 |
+|---|---|---|
+| OneBot HTTP 端口 `3000` | ✅ | 是 OneBot 的惯例，人人都用 |
+| DSH 端口 `55861` | ❌ | 每台机器随机分配，这里是作者的 |
+| 容器名 `napcat-qq` | ✅ | 中性，谁装都叫这个 |
+| 容器名 `my-bot-container` | ❌ | 作者自己起的名字 |
+| 音色 `zh-CN-XiaoxiaoNeural` | ✅ | edge 的通用女声 |
+| 音色 `zh-CN-XiaoyiNeural` | ❌ | 作者给某个角色选的 |
+| 转写脚本 `D:\某人\语音转写.py` | ❌ | 作者的盘符和目录 |
+| 称呼 `小鱿鱼` | ❌ | 作者本人 |
+
+## 实测踩到的「漏出来」清单
+
+这些是真的从别人机器上漏进过配置的：
+
+- `ownerName: 小鱿鱼` —— 作者称呼，出现在设置页
+- `转写脚本: D:\某人\语音转写.py` —— 作者路径，写死在代码默认值里
+- `if (uid === 10001)` —— 作者角色的 QQ 号，写死在逻辑里
+- `表情目录: D:\某人\表情包` —— 作者路径
+
+前两条已经改成读配置；后两条由使用者在 `character.json` 里填自己的。
+
+## 那「示例」怎么办？
+
+想让人看懂格式，又不想漏私人值：
+
+1. **用明显假的**：`123456789`、`C:\path\to\file`、`某甲 / 某乙`
+2. **放 `examples/`，默认不加载**，并在 README 里说明「这是样板，不是默认值」
+3. **说明文字里提一句**「比如：小鱿鱼」——只要它只是文案、不是值
+
+## 自检
+
+`qiyu doctor` 会扫一遍 `templates/`，看到这些就报警：
+
+| 规则 | 抓什么 |
+|---|---|
+| `[A-Z]:\\(Users|AI)\\` | 别人的本机路径 |
+| `云千语\|小鱿鱼` | 作者的角色名 |
+| 连续 8–11 位数字 | 像 QQ 号的数字 |
+| `SESSDATA` / `mQ-…` | 令牌 |
+
+扫不到东西会显示：**模板体检通过：没有别人的私人值**。
+
+## 给插件作者的一条建议
+
+写 `default` 之前，把「我自己的值」从手指底下挪开：
+
+- `default('')` 永远比 `default('我的名字')` 安全
+- 想给用户看格式 → 写在 `description` 里，不是写在 `default` 里
+- 配置项一旦落盘，用户很难分清「这是我设的」还是「插件给我的」