dsh-qiyu-stack 0.15.6 → 0.15.7

package/AGENTS.md

@@ -20,6 +20,19 @@ npx dsh-qiyu-stack doctor --json      # 5. 验收
 
 **不要 `git clone` 仓库**——`npx` 就够了，clone 反而会让人以为要改源码。
 
+## 第六步：给她一个会话（命令装不出来，必须人来做）
+
+五条命令只装东西，**不会创建 DSH 工作区，也不会创建会话**。装完还要人工做三件：
+
+1. 在 DSH 里**新建一个会话**，工作目录选 **`install` 打印的那个绝对路径**
+   （就是部署文件夹里的 `characters/<角色名>`）
+   ——她的 `AGENTS.md` 在这一层，DSH 才会每一轮读到；**别选 DSH 默认工作区，也别选 `~/.dsh/qiyu`**
+   （那是运行时副本，不是她的角色包）
+2. 设置 → 通到 QQ → **「目标会话」选这个会话**（不选的话，QQ 消息进来会被直接丢掉）
+3. **打开「总开关」**（`install` 默认关着——关着就只收不发）
+
+判断标准：`doctor --json` 里「桥还没选目标会话」是 **fail**；「总开关关着」「试运行开着」是 warn。
+
 ## 必须先问用户，不许猜
 
 | 要问什么 | 为什么 |
@@ -59,14 +72,15 @@ v0.15.4 起 `qiyu` 会自动兜底（把输出重定向到临时文件再读）
 
 **永远不要**在拿到「沙箱限制」标记时，让用户重装 Docker / 改配置。
 
-## 必须交还给人做的四件事
+## 必须交还给人做的五件事
 
-这四件 agent **做不了，也不该做**，直接告诉用户：
+这五件 agent **做不了，也不该做**，直接告诉用户：
 
 1. **装 Docker Desktop** —— 要管理员权限 + 重启电脑。给他链接和步骤，等他做完再回来
 2. **重启 DSH** —— 装完之后必须重启。**重启会结束当前会话**，所以先把状态写下来（见下）
 3. **手机扫码** —— `deploy` 会自动打开二维码图片，但"用哪个号扫"只有人知道
 4. **在手机确认页勾「下次登录无需确认」** —— 不勾的话每次重启容器都要重新验证
+5. **建她的会话并选目标会话** —— 见上面「第六步」。DSH 的会话只能在界面里建，CLI 没有这个权限
 
 ## 千万别碰的东西
 
@@ -89,11 +103,27 @@ npx dsh-qiyu-stack doctor --json
 ```
 
 - `不通`（fail）必须为 **0**
-- `待看`（warn）可以有——通常是"Windows 上别装 Windows 版 NapCat"这类提示
+- **「目标会话」必须是 `ok`** —— 是 fail 就说明桥还不知道该把消息送进哪个会话
+- `待看`（warn）可以有——但「总开关关着」「试运行开着」这两条要处理，不是可以忽略的提示
 - 模板体检必须是 `ok`（说明没有别人的私人值混进来）
 
 过了这关，才算装完。
 
+## 部署完成后：写交接文档
+
+`doctor --json` 过了（目标会话 ok、总开关已开）之后，跑：
+
+```bash
+npx dsh-qiyu-stack handover
+```
+
+它会在部署文件夹生成 `交接.md`：部署位置、QQ、容器、桥的目标会话、升级命令、
+回退方法，以及一段「直接丢给新会话」的开场白。**你还要做**：
+
+1. 把 doctor 里发现的问题、用户的特殊设置补进去（文档末尾有「用户自己补」）
+2. 提醒用户：这份含 QQ 号，别公开、别提交到公开仓库
+3. 让用户把这份归档——以后 GitHub 升级、换会话、回退，新会话都从它开始
+
 ## 出问题去哪查
 
 - 部署细节和踩过的坑：`docs/deployment.md`

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 更新记录
+
+> 每次发版都往这里加一段——`qiyu install` 会把当前版本的这段写进
+> `~/.dsh/qiyu/version.json`，设置里「栖语 → 版本」页签会显示它。
+
+## 0.15.7（2026-10-23）
+
+- 设置面板新增「版本」页签：栈版本、安装时间、各运行时版本，以及**这次更新做了什么**
+- 新增 `qiyu handover`：在部署文件夹生成 `交接.md`（位置 / QQ / 桥的目标会话 / 升级命令 / 回退方法 / 给新会话的开场白）
+- `doctor` 新增验收：桥没选「目标会话」→ **fail**；目标会话没开着 / 总开关关着 / 试运行开着 → warn
+- `install` 的交接语补上「第六步」：新建会话（工作目录选绝对路径）、选目标会话、打开总开关
+- `install` 不再说「设置里已经填好了，不用改」——地址和令牌填好，但目标会话/总开关要人来选
+- 文档：`AGENTS.md` / `README` 补第六步和交接文档说明
+
+## 0.15.6（2026-10-23）
+
+- `doctor` 自动探测 DSH 端口：不再被 `qiyu.config.json` 里的旧端口骗（DSH 每次启动端口可能变）
+- 新增 `src/dsh-port.mjs`：先试配置端口，再扫本机监听端口，按特征认（`/dsh-qq-bridge/state` 或根路径 401 的提示语）
+
+## 0.15.5（2026-10-23）
+
+- `doctor` 也接上沙箱降级：Docker / 容器 / 端口相关的 fail 在受限沙箱里降成 warn，不再让 agent 误以为装失败
+- `qr.mjs` 的 `docker cp` 改走 `跑()`：沙箱里不再假失败「拿不到二维码」
+
+## 0.15.4（2026-10-23）
+
+- 新增 `src/run.mjs`：管道被拒（EPERM）时改成「重定向到临时文件再读」，受限沙箱里也能跑外部命令
+- `preflight` 沙箱降级：读不到命令输出的结论标成「沙箱限制，这条不可信」
+- `AGENTS.md` 进 npm 包（从这版起 80 个文件）
+
+## 0.15.3（2026-10-23）
+
+- 仓库根加 `AGENTS.md`：给部署助手看的说明书（五条命令、必须先问的、沙箱、交还给人做的事）
+- `preflight --json` / `doctor --json`：给 agent 机器判断用
+- `install` 交接语改写：重启后回原会话，或开新会话跑 `doctor --json`
+
+## 0.15.1（2026-10-23）
+
+- 首个发布版：`npx dsh-qiyu-stack` 可跑，含 preflight / deploy / install / doctor / qr

package/README.md

@@ -76,6 +76,15 @@ npx dsh-qiyu-stack install --character 小满 --yes      # 装完重启 DSH（
 
 # 5. 扫码（图会自动打开），然后自查
 npx dsh-qiyu-stack doctor
+
+# 6. 给她一个会话 —— 这一步命令装不出来，得人在界面里做：
+#    · 新建会话，工作目录选 install 打印的那个绝对路径（部署文件夹里的 characters/小满）
+#      她的 AGENTS.md 在这一层，DSH 才会每轮读到；别选 DSH 默认工作区，也别选 ~/.dsh/qiyu
+#    · 设置 → 通到 QQ → 「目标会话」选这个会话，再打开「总开关」
+#    · 再跑一次 npx dsh-qiyu-stack doctor：目标会话应该是 ok
+
+# 7. 写交接文档 —— 以后升级 / 换会话 / 回退都从这份开始
+npx dsh-qiyu-stack handover
 ```
 
 > **用 npx 也没关系。** `install` 会先把运行时装一份到 `~/.dsh/qiyu/runtime/`，
@@ -83,7 +92,7 @@ npx dsh-qiyu-stack doctor
 > npx 的临时缓存被清掉、或者你把 qiyu 删了，DSH 那边照样能跑。
 
 `doctor` 会逐项告诉你：Docker 在不在、容器起没起、三个端口通不通、OneBot 认不认得出人、
-事件流连不连得上、DSH 桥接没接上。**每条失败都带一句怎么修。**
+事件流连不连得上、DSH 桥接没接上、**桥有没有选「目标会话」、总开关开没开**。每条失败都带一句怎么修。
 
 ---
 
@@ -100,11 +109,12 @@ dsh-qiyu-stack/              引擎（角色无关，可升级）
 │   └── qr.mjs               取二维码并直接打开
 ├── tools/
 │   └── merge-settings-tabs.mjs   把插件设置合并成「一个页面 + 页签」
-├── runtime/                 运行时五块（从真跑着的机器上搬来、洗过私人值）
+├── runtime/                 运行时五块 + 设置面板（从真跑着的机器上搬来、洗过私人值）
 │   ├── bridge/              QQ ↔ DSH 双向（全配置驱动）
 │   ├── memory/              长期记忆（含 1MB 中文词典）
 │   ├── mood/                心情
 │   ├── rhythm/              作息 / 主动搭话
+│   ├── panel/               设置总面板（「栖语」页 + 页签，含「版本」页签）
 │   └── voice/               语音转写脚本（TTS 还在 bridge 里，待拆）
 ├── templates/
 │   └── blank/               默认模板：行为齐全、性格空白、character.json 全空
@@ -149,12 +159,13 @@ npx dsh-qiyu-stack doctor       # 自检（加 --json 给 agent 用）
       每个问题都有默认值；带名字调用则全用默认值（给脚本用）
 - [x] **`qiyu deploy`**：查 Docker（没开就**静默拉起、不弹窗**）→ 选目录（挑非系统盘、查中文路径和空间）
       → 写 OneBot/WebUI 配置 → 跑容器 → **直接打开二维码**；令牌写回 `qiyu.config.json`
-- [x] **`qiyu install`**：把 runtime 四块装进 DSH profile；**按内容判断要不要替换**，
+- [x] **`qiyu install`**：把 runtime 四块 + 设置面板装进 DSH profile；**按内容判断要不要替换**，
       换代码时保留用户自己的文件（原图之类），`package.json` 改动前必留 `.bak`
 - [x] **`qiyu preflight`**：Node / Docker / Windows / WSL / 路径 / 空间 / 网络 / 杀软 /
       DSH / 模型凭证 / Python；`--fix` 能修引擎启动、占端口容器、edge-tts
 - [x] **`qiyu doctor`**：全链路自检 + 模板体检 + **runtime 与已装副本的代码一致性**
-- [x] **runtime 四块**：bridge / memory / mood / rhythm（去个性化，配置统一读活动角色）
+- [x] **runtime 四块 + 设置面板**：bridge / memory / mood / rhythm / panel（去个性化，配置统一读活动角色）
+- [x] **设置里「栖语」页签里的「版本」**：显示栈版本 / 安装时间 / 各运行时版本（来自 `~/.dsh/qiyu/version.json`）
 - [x] **语音拆干净**：`bridge/lib/voice.mjs` 管说和听，桥只管向 NapCat 要 wav
 - [x] 端到端：空白 profile → install → 独立实例 → 备号收发都通
 

package/bin/qiyu.mjs

@@ -14,6 +14,7 @@ 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 { handover } from '../src/handover.mjs'
 import { 读配置, 配置文件路径 } from '../src/config.mjs'
 
 const 参数 = process.argv.slice(2)
@@ -63,7 +64,7 @@ const 帮助 = `
   qiyu qr                       把登录二维码取出来并**直接打开**给你扫
                                 （不会只给一个路径让你自己找文件）
 
-  qiyu install                  把 runtime 五块装进 DSH profile
+  qiyu install                  把运行时（桥/记忆/心情/作息 + 设置面板）装进 DSH profile
        --profile <目录>         默认 ~/.dsh/profiles/desktop
        --character <名字>       顺便把这个角色设为「活动角色」（拷到 ~/.dsh/qiyu/）
        --only bridge,memory     只装其中几块
@@ -73,6 +74,11 @@ const 帮助 = `
 
   qiyu config                   显示配置来源（文件 / 环境变量 / 默认值）
 
+  qiyu handover                 在部署文件夹写「交接.md」：位置 / QQ / 桥的目标会话 /
+                                升级命令 / 回退方法 / 给新会话的开场白
+       --character <名字>       不指定时自动认（配置里记的，或 characters/ 下唯一的那个）
+       --out <文件名>           默认 交接.md
+
 配置文件：qiyu.config.json（当前目录），也可以用环境变量覆盖：
   QIYU_ONEBOT_TOKEN   OneBot HTTP 令牌
   QIYU_WS_TOKEN       OneBot WS 令牌
@@ -153,6 +159,10 @@ async function 主() {
     return 0
   }
 
+  if (命令 === 'handover' || 命令 === '交接') {
+    return await handover({ 角色: 取值('--character'), 输出: 取值('--out', '交接.md') })
+  }
+
   console.error('不认识的命令：' + 命令)
   console.log(帮助)
   return 1

package/docs/status.md

@@ -6,10 +6,41 @@
 
 **能用了，也发出去了，但还没被陌生人在干净机器上验证过。**
 
-- npm：`dsh-qiyu-stack@0.15.6`（`latest`）
+- npm：`dsh-qiyu-stack@0.15.7`（`latest`）
 - GitHub：<https://github.com/aesfls/dsh-qiyu-stack>（公开，main）
 - 千语（爸爸本人的实例）：正常运行中，桥、NapCat、Docker 都通
 
+## 发版规矩（以后照做）
+
+每次版本更新：先在 `CHANGELOG.md` 写一段「这版做了什么」，再发 npm。
+
+- `qiyu install` 会把当前版本这段写进 `~/.dsh/qiyu/version.json`
+- 设置里「栖语 → 版本」页签显示版本、安装时间、这次更新内容、各运行时版本
+- `qiyu handover` 也会把它写进 `交接.md`
+
+## 2026-10-23 第六轮：把「第六步」补上（v0.15.7）
+
+陌生人在默认会话里部署会发现：五条命令全绿，桥却其实是哑的。原因有四层：
+
+1. `qiyu` 全程**不创建 DSH 工作区/会话**（CLI 在 DSH 进程外，没有会话 API 权限）
+2. 桥的「目标会话」是空的，收到 QQ 消息只记一句「还没填目标会话，这轮不转」，直接丢掉
+3. 她的 `AGENTS.md` 在 `characters/<名字>/` 或 `~/.dsh/qiyu/`，不在默认会话的 AGENTS.md 链上
+4. 总开关默认关着，`install` 原来的交接语却写「设置里已经填好了，不用改」
+
+0.15.7 补：
+
+1. `AGENTS.md` / `README` 新增「第六步：给她一个会话」——建会话（工作目录选 `characters/<名字>`）、
+   桥设置里选目标会话、打开总开关；「交还给人做的四件事」改成五件
+2. `install` 的交接语把这三件事写清楚，不再说「不用改」
+3. `doctor` 新增：目标会话为空 → **fail**；目标会话没开着 → warn；总开关关着 / 试运行开着 → warn
+4. `install` 的交接语给出**绝对路径**，并区分「部署文件夹」和「NapCat 数据目录」，
+   明确说会话工作目录要选部署文件夹里的 `characters/<名字>`（不是 `~/.dsh/qiyu`）
+5. 新增 `qiyu handover`：在部署文件夹写 `交接.md`——位置 / QQ / 桥的目标会话 /
+   升级命令 / 回退方法 / 直接丢给新会话的开场白，方便归档和 GitHub 升级后接手
+6. 设置面板新增「版本」页签：显示栈版本 / 安装时间 / 各运行时版本；
+   `install` 会把这份信息写进 `~/.dsh/qiyu/version.json`，面板通过
+   `/dsh-qiyu-panel/version` 读（没有记录就现场读各插件 package.json）
+
 ## 2026-10-23 第五轮：DSH 端口自动探测（v0.15.6）
 
 `qiyu.config.json` 里的 `dsh.port` 是某一次写下的快照，而 DSH 的端口会变

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qiyu-stack",
-  "version": "0.15.6",
+  "version": "0.15.7",
   "description": "栖语栈：让一个智能体住进 QQ —— QQ 双向桥、长期记忆、心情、语音、作息，以及把 NapCat 部署这件事一次做对",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
     "tools",
     "runtime",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "repository": {
     "type": "git",

package/runtime/panel/cordis.patch.yml

@@ -0,0 +1,7 @@
+# 「栖语」设置总面板
+#
+# 这一行激活宿主半边（空的）+ 这个包在 package.json 里声明的 dsh.client 网页半边。
+# id 是加载器里的行名，两处要一致。
+- insert:
+    - id: qiyu-panel
+      name: 'dsh-qiyu-panel'

package/runtime/panel/lib/client.js

@@ -0,0 +1,272 @@
+// 栖语面板 · 网页半边
+//
+// 在 DSH 设置的左侧栏加一项「栖语」，里面是一个页签容器：
+// 别家插件把设置页注册到 qiyu.tab，就变成这里的一个页签。
+//
+// 关键点（都是 DSH 的插槽契约里写死的）：
+//   1. renderSlot(key) 只允许渲染「自己 children 里声明过的槽位」，
+//      所以这里用 children 声明 qiyu.tab，而不是去借用别家的槽位。
+//   2. 页签列表通过 inject 提供的 hooks.tabs 拿到（跟内置「内置插件」页一个写法），
+//      组件那边就拿到一个 useTabs(props)。
+//   3. 改完这个文件不用重启 DSH，刷新页面即可 —— 客户端 bundle 的版本号按文件 mtime 算。
+
+window.__ModuleLoader__.load({
+  id: 'dsh-qiyu-panel',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+
+    const React = require('react')
+    const inject = ['slots']
+    const h = React.createElement
+
+    const 槽位 = 'qiyu.tab'
+
+    const S = {
+      wrap: { padding: '4px 2px 24px', fontSize: 13, lineHeight: 1.7 },
+      head: { fontSize: 15, fontWeight: 600, margin: '0 0 2px' },
+      intro: { opacity: 0.6, fontSize: 12, margin: '0 0 14px' },
+      tabs: {
+        display: 'flex',
+        gap: 4,
+        flexWrap: 'wrap',
+        borderBottom: '1px solid var(--dsw-alias-border-l1, rgba(0,0,0,.10))',
+        marginBottom: 14,
+        // ⭐ 钉在顶部：某个页签里的配置很长时，往下滚页签条不会跟着跑掉
+        position: 'sticky',
+        top: 0,
+        zIndex: 5,
+        paddingTop: 6,
+        background: 'var(--dsw-alias-bg-layer-1, rgba(255,255,255,.94))',
+        backdropFilter: 'saturate(1.1) blur(6px)',
+        WebkitBackdropFilter: 'saturate(1.1) blur(6px)',
+      },
+      tab: {
+        border: 'none',
+        background: 'transparent',
+        color: 'inherit',
+        opacity: 0.6,
+        fontSize: 12.5,
+        padding: '7px 12px',
+        cursor: 'pointer',
+        borderBottom: '2px solid transparent',
+        marginBottom: -1,
+      },
+      tabOn: {
+        border: 'none',
+        background: 'transparent',
+        color: 'inherit',
+        fontSize: 12.5,
+        padding: '7px 12px',
+        cursor: 'pointer',
+        fontWeight: 600,
+        borderBottom: '2px solid var(--dsw-alias-state-business-primary, #4d6bfe)',
+        marginBottom: -1,
+      },
+      panel: { minHeight: 60 },
+      empty: { opacity: 0.6, fontSize: 12.5, padding: '18px 4px' },
+      badge: {
+        fontSize: 11,
+        opacity: 0.55,
+        marginLeft: 6,
+      },
+      row: {
+        display: 'flex',
+        gap: 12,
+        padding: '6px 0',
+        borderBottom: '1px solid var(--dsw-alias-border-l1, rgba(0,0,0,.06))',
+      },
+      rowKey: { opacity: 0.6, minWidth: 96, flex: '0 0 auto' },
+      rowVal: { wordBreak: 'break-all' },
+    }
+
+    function 取标签(原) {
+      try {
+        const v = typeof 原 === 'function' ? 原() : 原
+        return v == null ? '' : String(v)
+      } catch (e) {
+        return ''
+      }
+    }
+
+    function Panel(props) {
+      const renderSlot = props && props.renderSlot
+      const useTabs = props && props.useTabs
+      const rows = typeof useTabs === 'function' ? useTabs((v) => v) : []
+      const [active, setActive] = React.useState()
+
+      const 选中 = rows.find((r) => r.id === active) ? active : rows[0] && rows[0].id
+
+      return h(
+        'div',
+        { style: S.wrap },
+        h('div', { style: S.head }, '栖语'),
+        h('div', { style: S.intro }, '住在这里的几件事：QQ、心情、记忆、主动搭话、刷 B 站。'),
+
+        rows.length === 0
+          ? h('div', { style: S.empty }, '还没有插件注册页签到 qiyu.tab。')
+          : h(
+              React.Fragment,
+              null,
+              h(
+                'div',
+                { style: S.tabs, role: 'tablist' },
+                rows.map((r) =>
+                  h(
+                    'button',
+                    {
+                      key: r.id,
+                      type: 'button',
+                      role: 'tab',
+                      style: r.id === 选中 ? S.tabOn : S.tab,
+                      'aria-selected': r.id === 选中,
+                      onClick: () => setActive(r.id),
+                    },
+                    r.label || r.id,
+                  ),
+                ),
+              ),
+              h(
+                'div',
+                { style: S.panel, role: 'tabpanel' },
+                typeof renderSlot === 'function' && 选中
+                  ? renderSlot(槽位, {}, { only: 选中 })
+                  : h('div', { style: S.empty }, '这个页签还是空的。'),
+              ),
+            ),
+      )
+    }
+
+    function VersionTab() {
+      const [数据, set数据] = React.useState(null)
+      const [错, set错] = React.useState('')
+
+      React.useEffect(() => {
+        let 活 = true
+        fetch('/dsh-qiyu-panel/version', { cache: 'no-store' })
+          .then((r) => r.json())
+          .then((j) => {
+            if (活) set数据(j)
+          })
+          .catch((e) => {
+            if (活) set错(String((e && e.message) || e))
+          })
+        return () => {
+          活 = false
+        }
+      }, [])
+
+      if (错) return h('div', { style: S.empty }, '读不到版本：' + 错)
+      if (!数据) return h('div', { style: S.empty }, '正在读版本…')
+
+      const 行 = (标签, 值) =>
+        h(
+          'div',
+          { key: 标签, style: S.row },
+          h('span', { style: S.rowKey }, 标签),
+          h('span', { style: S.rowVal }, 值 || '—'),
+        )
+
+      const 模块 = 数据.模块 || {}
+      const 更新 = String(数据.更新内容 || '')
+        .split('\n')
+        .map((s) => s.replace(/^[-*]\s*/, '').trim())
+        .filter(Boolean)
+
+      return h(
+        'div',
+        { style: S.wrap },
+        h('div', { style: S.head }, '当前版本'),
+        h('div', { style: S.intro }, '这一套装了什么、哪一版，以及这次更新改了什么。'),
+        行('栖语栈', 数据.栈),
+        行('安装时间', 数据.安装时间),
+        行('设置面板', 数据.面板),
+        更新.length
+          ? h(
+              'div',
+              { style: { marginTop: 14 } },
+              h('div', { style: { fontWeight: 600, marginBottom: 4 } }, '这次更新做了什么'),
+              更新.map((s, i) =>
+                h(
+                  'div',
+                  { key: i, style: { display: 'flex', gap: 8, padding: '3px 0' } },
+                  h('span', { style: { opacity: 0.45 } }, '•'),
+                  h('span', { style: S.rowVal }, s),
+                ),
+              ),
+            )
+          : null,
+        Object.keys(模块).length
+          ? h(
+              'div',
+              { style: { marginTop: 14 } },
+              h('div', { style: { fontWeight: 600, marginBottom: 4 } }, '运行时'),
+              Object.keys(模块)
+                .sort()
+                .map((k) => 行(k, 模块[k])),
+            )
+          : null,
+        数据.提示 ? h('div', { style: { ...S.empty, padding: '10px 0 0' } }, 数据.提示) : null,
+      )
+    }
+
+    function apply(ctx) {
+      const slots = ctx.get('slots')
+      if (!slots) return
+
+      // 页签列表：跟内置「内置插件」页同一套写法，靠 version 判断要不要重算
+      let 上次版本 = -1
+      let 缓存 = []
+      const 快照 = () => {
+        const 版本 = slots.getVersion(槽位)
+        if (版本 !== 上次版本) {
+          上次版本 = 版本
+          缓存 = slots.entries(槽位)
+            .map((entry) => ({
+              id: (entry.options && entry.options.id) || '',
+              order: (entry.options && entry.options.order) || 0,
+              label: 取标签(entry.options && entry.options.label),
+            }))
+            .sort((a, b) => a.order - b.order)
+        }
+        return 缓存
+      }
+
+      const 注入 = () => ({
+        hooks: {
+          tabs: {
+            getSnapshot: 快照,
+            subscribe: (listener) => slots.subscribe(槽位, listener),
+          },
+        },
+      })
+
+      slots.inject('settings.section', () =>
+        slots.register(
+          {
+            name: 'settings.section',
+            id: 'qiyu',
+            order: 48,
+            label: () => '栖语',
+            inject: 注入,
+            // ⭐ 自己声明页签槽位 —— renderSlot 只认这个
+            children: { [槽位]: { kind: 'list', scope: 'root' } },
+          },
+          Panel,
+        ),
+      )
+
+      // ⭐ 版本页签：面板自己注册进自己的 qiyu.tab，永远排在最后
+      slots.inject('qiyu.tab', () =>
+        slots.register(
+          { name: 'qiyu.tab', id: 'version', order: 99, label: () => '版本' },
+          VersionTab,
+        ),
+      )
+    }
+
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/runtime/panel/lib/host.js

@@ -0,0 +1,81 @@
+// 栖语面板 · 宿主半边
+//
+// 面板本身没有业务，只多做一件事：给「版本」页签提供一个只读接口
+//   GET /dsh-qiyu-panel/version
+// 数据来自 qiyu install 写的 $DSH_HOME/qiyu/version.json（没有就退回现场读各插件 package.json）。
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const 包根 = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+function 读JSON(路径) {
+  try {
+    if (!existsSync(路径)) return null
+    return JSON.parse(readFileSync(路径, 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return null
+  }
+}
+
+/** 现场读已装插件的版本（version.json 缺字段时兜底） */
+function 现场模块版本(profile的node_modules) {
+  const 出 = {}
+  for (const 名 of ['dsh-qq-bridge', 'dsh-fish-memory', 'dsh-feiyu-mood', 'dsh-speak-up']) {
+    const j = 读JSON(join(profile的node_modules, 名, 'package.json'))
+    if (j && j.version) 出[名] = j.version
+  }
+  return 出
+}
+
+function 版本信息() {
+  const 家 = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const 记录 = 读JSON(join(家, 'qiyu', 'version.json')) || {}
+  const 自己 = 读JSON(join(包根, 'package.json')) || {}
+  const profile = process.env.DSH_PROFILE_DIR || join(家, 'profiles', 'desktop')
+
+  let 模块 = 记录.模块 || {}
+  if (!Object.keys(模块).length) {
+    try {
+      模块 = 现场模块版本(join(profile, 'node_modules'))
+    } catch {
+      模块 = {}
+    }
+  }
+
+  return {
+    ok: true,
+    栈: 记录.版本 || '',
+    安装时间: 记录.安装时间 || '',
+    更新内容: 记录.更新内容 || '',
+    面板: 自己.version || '',
+    模块,
+    提示: 记录.版本 ? '' : '还没有安装记录 —— 跑一次 npx dsh-qiyu-stack install 就会写上。',
+  }
+}
+
+export const inject = ['webServer']
+
+export function apply(ctx) {
+  const 注册 = () =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-qiyu-panel/version',
+      handler: async (req, res) => {
+        const 体 = JSON.stringify(版本信息())
+        res.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8',
+          'cache-control': 'no-store',
+        })
+        res.end(体)
+      },
+    })
+
+  try {
+    if (typeof ctx.effect === 'function') ctx.effect(注册)
+    else 注册()
+  } catch {
+    // 拿不到 webServer 就只是没有版本接口；不影响设置页其他功能
+  }
+}

package/runtime/panel/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "dsh-qiyu-panel",
+  "version": "0.1.1",
+  "description": "栖语 · 设置总面板：把各插件的设置收进一个「栖语」页，按页签组织。",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/host.js",
+  "exports": {
+    ".": "./lib/host.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "slots"
+      ],
+      "external": [
+        "react"
+      ]
+    }
+  }
+}

package/src/changelog.mjs

@@ -0,0 +1,33 @@
+// 从 CHANGELOG.md 里取某个版本的「这段写了什么」。
+//
+// 用途：qiyu install 写进 ~/.dsh/qiyu/version.json，设置面板的「版本」页签显示；
+// qiyu handover 也顺手把它写进交接文档。
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const 包根 = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+export function 读更新内容(版本) {
+  try {
+    const 文 = readFileSync(join(包根, 'CHANGELOG.md'), 'utf8')
+    const 行们 = 文.split(/\r?\n/)
+    const 头 = new RegExp('^##\\s*' + String(版本).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?![\\d.])')
+    let 开始 = -1
+    for (let i = 0; i < 行们.length; i++) {
+      if (头.test(行们[i])) {
+        开始 = i + 1
+        break
+      }
+    }
+    if (开始 < 0) return ''
+    const 出 = []
+    for (let i = 开始; i < 行们.length; i++) {
+      if (/^##\s/.test(行们[i])) break
+      出.push(行们[i])
+    }
+    return 出.join('\n').trim()
+  } catch {
+    return ''
+  }
+}

package/src/doctor.mjs

@@ -200,11 +200,36 @@ export async function doctor({ 只输出JSON = false, 跳过WebSocket = false }
   } else {
     try {
       const r = await 请求(`http://127.0.0.1:${探测.端口}/dsh-qq-bridge/state`)
-      if (r.json && r.json.NapCat状态) {
-        const 状 = r.json.NapCat状态
+      const j = r.json
+      if (j && j.配置) {
+        const 状 = j.NapCat状态
         const 注 = 探测.来源 === '自动探测' ? `DSH 端口 ${探测.端口} 是自动探测到的（配置里写的是 ${配置.dsh.port || '空'}）` : ''
-        if (状.用户) 记('ok', `DSH 桥认到：${状.昵称}（${状.用户}）`, 注)
-        else 记('warn', 'DSH 桥连不上 NapCat', JSON.stringify(状).slice(0, 160), '桥的 NapCat 地址/令牌和 qiyu.config.json 要一致')
+        if (状 && 状.用户) 记('ok', `DSH 桥认到：${状.昵称}（${状.用户}）`, 注)
+        else if (状) 记('warn', 'DSH 桥连不上 NapCat', JSON.stringify(状).slice(0, 160), '桥的 NapCat 地址/令牌和 qiyu.config.json 要一致')
+        else 记('warn', 'DSH 桥没有 NapCat 状态', '', '桥的 NapCat 地址/令牌和 qiyu.config.json 要一致')
+
+        // ⭐ 桥连上 NapCat ≠ 能把消息送进会话。
+        //    目标会话为空时，桥收到 QQ 消息只会记一句「还没填目标会话，这轮不转」，直接丢掉。
+        if (!j.配置.目标会话) {
+          记(
+            'fail',
+            '桥还没选「目标会话」',
+            '收到 QQ 消息也不知道该送进哪个会话，会直接丢掉',
+            '设置 → 通到 QQ → 目标会话：选她的会话（工作目录是 characters/<名字> 的那个）'
+          )
+        } else if (!Array.isArray(j.目标情况) || !j.目标情况.length) {
+          记(
+            'warn',
+            '「目标会话」现在没开着',
+            '可能归档了，或者 DSH 刚重启还没恢复',
+            '在 DSH 里打开那个会话；归档了就取消归档，或重新选一个'
+          )
+        } else {
+          记('ok', `目标会话：${j.目标情况[0].标题 || j.配置.目标会话}`)
+        }
+
+        if (j.配置.总开关 !== true) 记('warn', '总开关关着：她收不到也发不出', '消息进不了、也出不去', '设置 → 通到 QQ → 打开「总开关」')
+        if (j.配置.试运行 === true) 记('warn', '试运行开着：不会真的发到 QQ', '', '确认没问题后，在设置里把「试运行」关掉')
       } else {
         记('warn', `DSH 在 ${探测.端口}，但没看到 dsh-qq-bridge`, '', '确认 DSH 里装了 dsh-qq-bridge 插件')
       }
@@ -237,6 +262,7 @@ export async function doctor({ 只输出JSON = false, 跳过WebSocket = false }
       ['memory', 'dsh-fish-memory'],
       ['mood', 'dsh-feiyu-mood'],
       ['rhythm', 'dsh-speak-up'],
+      ['panel', 'dsh-qiyu-panel'],
     ]
     const 问题 = []
     for (const [目录名, 包名] of 模块们) {

package/src/handover.mjs

@@ -0,0 +1,207 @@
+// qiyu handover —— 在部署文件夹里生成「交接.md」。
+//
+// 为什么要有这个：部署完那一刻，负责装的 agent 最清楚所有路径和状态；
+// 过几天用户想升级 / 换会话 / 回退，新会话只能从一份文档开始。
+// 这份文档就是那次「交接」。
+import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { 读配置, 配置文件路径 } from './config.mjs'
+import { 探测DSH } from './dsh-port.mjs'
+import { 读更新内容 } from './changelog.mjs'
+
+const 包根 = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+function 版本() {
+  try {
+    return JSON.parse(readFileSync(join(包根, 'package.json'), 'utf8')).version || '?'
+  } catch {
+    return '?'
+  }
+}
+
+function 时间() {
+  const d = new Date()
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+/** 角色名：参数 > 配置 > characters/ 里唯一那个 */
+function 找角色(配置, 指定) {
+  if (指定) return 指定
+  if (配置.角色) return 配置.角色
+  try {
+    const 根 = resolve(process.cwd(), 配置.character || 'characters')
+    if (!existsSync(根)) return ''
+    const 候选 = readdirSync(根).filter((n) => {
+      try {
+        return statSync(join(根, n)).isDirectory()
+      } catch {
+        return false
+      }
+    })
+    return 候选.length === 1 ? 候选[0] : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 从角色包里读 QQ（桥没跑的时候兜底） */
+function 角色里的QQ(角色目录) {
+  try {
+    const j = JSON.parse(readFileSync(join(角色目录, 'character.json'), 'utf8').replace(/^\uFEFF/, ''))
+    return { qq: String(j.qq || j.QQ || ''), 称呼: j.称呼 || '' }
+  } catch {
+    return { qq: '', 称呼: '' }
+  }
+}
+
+async function 桥状态(配置) {
+  try {
+    const 探测 = await 探测DSH({ 已知端口: 配置.dsh.port })
+    if (!探测 || !探测.有桥) return null
+    const r = await fetch(`http://127.0.0.1:${探测.端口}/dsh-qq-bridge/state`, { signal: AbortSignal.timeout(3000) })
+    if (!r.ok) return null
+    return { 端口: 探测.端口, 状态: await r.json() }
+  } catch {
+    return null
+  }
+}
+
+function 开关(v) {
+  return v === true ? '开' : v === false ? '关' : '（未知）'
+}
+
+export async function handover({ 角色: 指定角色 = '', 输出 = '交接.md' } = {}) {
+  const cwd = process.cwd()
+  const 配置 = 读配置()
+  const 名字 = 找角色(配置, 指定角色)
+  if (!名字) {
+    console.error('✗ 没找到角色。指定一下：qiyu handover --character <名字>')
+    console.error('  （或者在部署文件夹里跑，characters/ 下只有一个角色时也能自动认）')
+    return 1
+  }
+
+  const 角色目录 = resolve(cwd, 配置.character || 'characters', 名字)
+  const 有角色 = existsSync(角色目录)
+  const 有AGENTS = existsSync(join(角色目录, 'AGENTS.md'))
+  const 角色信息 = 有角色 ? 角色里的QQ(角色目录) : { qq: '', 称呼: '' }
+  const 桥 = await 桥状态(配置)
+  const 桥配置 = (桥 && 桥.状态 && 桥.状态.配置) || {}
+  const NapCat = (桥 && 桥.状态 && 桥.状态.NapCat状态) || null
+  const qq = (NapCat && NapCat.用户) || 角色信息.qq || '（还没填）'
+  const 昵称 = (NapCat && NapCat.昵称) || 名字
+  const 目标会话 = 桥配置.目标会话 || ''
+  const 目标标题 =
+    (桥 && Array.isArray(桥.状态.目标情况) && 桥.状态.目标情况[0] && 桥.状态.目标情况[0].标题) || ''
+  const 数据目录 = (配置.napcat && 配置.napcat.dataDir) || ''
+  const 数据目录显示 = 数据目录 ? '`' + 数据目录 + '`' : '（没记录，deploy --dir 时指定的那个）'
+  const 容器 = (配置.napcat && 配置.napcat.container) || 'napcat-qq'
+
+  const 路径 = resolve(cwd, 输出)
+  if (existsSync(路径)) {
+    const 备份 = `${路径}.bak-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`
+    try {
+      renameSync(路径, 备份)
+    } catch {
+      // 备份不了就直接覆盖
+    }
+  }
+
+  const 内容 = `# 栖语部署交接
+
+> 生成时间：${时间()}
+> 这份是给「以后接手的人 / 新会话」看的：升级、迁移、回退都从这份开始。
+> ⚠️ 里面有 QQ 号和本机路径，**别公开、别提交到公开仓库**。
+
+## 一句话
+
+「${名字}」跑在 \`${cwd}\`，QQ ${qq}（${昵称}）${目标会话 ? `，桥盯的会话是 \`${目标会话}\`` : '，**桥还没选目标会话**'}。
+
+## 部署位置
+
+| 东西 | 路径 |
+|---|---|
+| 部署文件夹 | \`${cwd}\` |
+| 她的角色包 | \`${角色目录}\`${有角色 ? '' : '（**不存在**，先 qiyu init）'} |
+| 她的 AGENTS.md | \`${join(角色目录, 'AGENTS.md')}\`${有AGENTS ? '' : '（**不存在**，她会没有性格）'} |
+| NapCat 数据 | ${数据目录显示} |
+| qiyu 配置 | \`${配置文件路径()}\`（**含令牌，别外传**） |
+
+## 现在怎么跑
+
+- 容器：\`${容器}\`（Docker 里的 Linux QQ + NapCat）
+- 端口：3000 OneBot HTTP ／ 3001 WS ／ 6099 WebUI
+- 桥：目标会话 ${目标标题 ? `「${目标标题}」` : '（没选）'}${目标会话 ? ` \`${目标会话}\`` : ''}｜总开关：${开关(桥配置.总开关)}｜试运行：${开关(桥配置.试运行)}
+- 自检：\`npx dsh-qiyu-stack doctor --json\`
+
+## 她的会话（重建时看这里）
+
+会话的工作目录必须是**她的角色包**：\`${角色目录}\`。
+
+> DSH 只会自动读工作目录根上的 AGENTS.md；选错地方，她会变成没有性格的默认助手。
+
+重建步骤：DSH 新建会话 → 工作目录选上面那个路径 → 设置 → 通到 QQ →
+「目标会话」选这个会话 → 打开「总开关」。
+
+## 这次版本更新了什么（${版本()}）
+
+${读更新内容(版本()) || '（这次没写更新记录）'}
+
+## 以后升级到新版本（GitHub / npm）
+
+在部署文件夹里：
+
+\`\`\`bash
+npx dsh-qiyu-stack@latest preflight --json
+npx dsh-qiyu-stack@latest install --character ${名字} --yes
+\`\`\`
+
+然后**重启 DSH**（关掉窗口再开，不用重启电脑），再：
+
+\`\`\`bash
+npx dsh-qiyu-stack@latest doctor --json
+\`\`\`
+
+\`install\` 会按内容替换运行时代码，**保留她的角色包和个人文件**；
+改 \`package.json\` 前会留 \`.bak-qiyuinstall-<时间>\` 备份。
+
+## 回退
+
+- 代码回退：把 profile 里 \`package.json.bak-qiyuinstall-*\` 拷回原名，
+  再把 \`node_modules/*.bak-qiyuinstall-*\` 挪回原名，重启 DSH
+- NapCat 不用动：容器、登录态、数据目录都在 ${数据目录显示}
+
+## 新会话开场白（直接复制给它）
+
+> 你接手一个已经部署好的栖语实例，部署文件夹是 \`${cwd}\`。
+> 先读 \`${join(cwd, '交接.md')}\`，再跑 \`npx dsh-qiyu-stack doctor --json\`，
+> 把结果和你要做的事告诉我。要升级就先跑
+> \`npx dsh-qiyu-stack@latest install --character ${名字} --yes\`，然后提醒我重启 DSH。
+
+## 用户自己补
+
+- [ ] 这份文档之外，还有没有别的改动（改过端口 / 换过号 / 装过别的插件）？
+- [ ] 备份放哪：______________________
+- [ ] 有哪些已知问题：______________________
+
+---
+
+由 \`dsh-qiyu-stack@${版本()}\` 生成。
+`
+
+  try {
+    writeFileSync(路径, 内容, 'utf8')
+  } catch (错) {
+    console.error('✗ 写不了交接文档：' + String(错.message || 错))
+    return 1
+  }
+
+  console.log('✅ 交接文档写好了：' + 路径)
+  console.log('')
+  console.log('  里面有：部署位置、QQ、容器、桥的目标会话、升级命令、回退方法、给新会话的开场白。')
+  if (!有AGENTS) console.log('  ⚠️ 注意：她的 AGENTS.md 不存在，先 qiyu init 或把人设补上。')
+  if (!目标会话) console.log('  ⚠️ 桥还没选「目标会话」——去 设置 → 通到 QQ 选一个，再跑一次 qiyu handover。')
+  console.log('  提醒用户：这份含 QQ 号，别公开。')
+  return 0
+}

package/src/install.mjs

@@ -11,6 +11,7 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, copyFileSync, rmSync, renameSync } from 'node:fs'
 import { 读配置 } from './config.mjs'
+import { 读更新内容 } from './changelog.mjs'
 import { join, resolve, dirname } from 'node:path'
 import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
@@ -25,7 +26,7 @@ const 红 = (s) => `\x1b[31m${s}\x1b[0m`
 const 灰 = (s) => `\x1b[90m${s}\x1b[0m`
 
 // runtime 下这几个目录就是要装的块（voice 目前只是脚本，不当插件装）
-const 模块目录 = ['bridge', 'memory', 'mood', 'rhythm']
+const 模块目录 = ['bridge', 'memory', 'mood', 'rhythm', 'panel']
 
 /**
  * 一个目录的"指纹"：相对路径 → 内容哈希。
@@ -283,6 +284,27 @@ export async function install(选项 = {}) {
   // ---------- 4.5 语音转写脚本 + 活动角色，落到 $DSH_HOME/qiyu ----------
   const 家 = process.env.DSH_HOME || join(homedir(), '.dsh')
   const qiyu家 = join(家, 'qiyu')
+
+  // ---------- 4.4 版本记录：设置面板的「版本」页签读它 ----------
+  try {
+    const 栈版本 = JSON.parse(readFileSync(join(包根, 'package.json'), 'utf8')).version || '?'
+    const 模块版本 = {}
+    for (const m of 模块们) 模块版本[m.名字] = m.版本
+    mkdirSync(qiyu家, { recursive: true })
+    writeFileSync(
+      join(qiyu家, 'version.json'),
+      JSON.stringify(
+        { 版本: 栈版本, 安装时间: new Date().toISOString(), 更新内容: 读更新内容(栈版本), 模块: 模块版本 },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    )
+    console.log(绿('✓') + ` 版本记录 → ${join(qiyu家, 'version.json')}`)
+  } catch (错) {
+    console.log(黄('· 版本记录没写成（不影响使用）：') + String(错.message || 错))
+  }
+
   try {
     const 源 = join(包根, 'runtime', 'voice', '语音转写.py')
     if (existsSync(源)) {
@@ -404,11 +426,24 @@ export async function install(选项 = {}) {
   console.log('  2. 重启后：回到这个会话，或者开一个新会话，先跑一遍')
   console.log('     npx dsh-qiyu-stack doctor --json')
   console.log('     把结果贴回来 —— 东西已经装好了，这一步只是确认，不是重新开始')
-  console.log('  3. 设置里「通到 QQ」应该已经填好了，不用改')
+  const 部署夹 = process.cwd()
+  const 角色夹 = 角色名 ? resolve(部署夹, 'characters', 角色名) : join(部署夹, 'characters', '<名字>')
+  const 本机配置 = 读配置()
+  console.log('  3. **给她一个会话**（这一步命令装不出来，得人来做）：')
+  console.log('     · 部署文件夹（qiyu.config.json 就在这）：' + 部署夹)
+  console.log('     · 新建会话，工作目录选：' + 角色夹)
+  console.log('       （她的 AGENTS.md 在这一层，DSH 才会每一轮读到；不是 ~/.dsh/qiyu，也不是 DSH 默认工作区）')
+  if (本机配置.napcat && 本机配置.napcat.dataDir && resolve(本机配置.napcat.dataDir) !== 部署夹) {
+    console.log('       （NapCat 的数据在 ' + 本机配置.napcat.dataDir + '，那是另一处，会话不要选它）')
+  }
+  console.log('     · 设置 → 通到 QQ → 「目标会话」选这个会话，再打开「总开关」')
+  console.log('     · 再跑一次 doctor：目标会话应该 ok，总开关应该不再 warn')
+  console.log('  4. 写交接文档：npx dsh-qiyu-stack handover')
+  console.log('     它会写 交接.md（部署位置 / 升级命令 / 回退方法 / 给新会话的开场白）')
   console.log('')
   console.log(灰('  注：DSH 启动时可能会自己弹一个浏览器窗口 —— 那是 DSH 自己的界面，不是报错。'))
-  console.log(灰('  里面的「通到 QQ」设置已经帮你填好了（地址和令牌），不用改。'))
-  console.log(灰('  只有换机器/换端口时才会要你填，那时令牌在 qiyu.config.json 的 napcat.token。'))
+  console.log(灰('  桥的地址和令牌已经填好了；但「目标会话」和「总开关」是给你的，不会替你选。'))
+  console.log(灰('  只有换机器/换端口时才需要改地址，那时令牌在 qiyu.config.json 的 napcat.token。'))
   console.log('')
   console.log(灰(`要退回去：把 ${pkg备份.split(/[\\/]/).pop()} 拷回 package.json，`))
   console.log(灰('再把 node_modules 里 *.bak-qiyuinstall-* 挪回原名。'))