admin/dsh_ai1net_server
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(工作区): 纳入版本控制基线（回收 411 MB 过程产物）

Browse Source 
回收 411 MB（470 M → 58.8 M），全部经回收站，可恢复：
- 待清理/（146.2 M，含 relay 分片 128 M 与 42 项过程目录）
- tmp/（32.4 M，按接续棒命名的过程临时区）
- .workbuddy/tmp/（39.5 M）
- 4 份 workbuddy.db 冗余副本（101 M，09-23 事故的坏副本 / 抢救产物）
- tmp/im16/gw/centrifugo 二进制（63.9 M，可重下）+ 缓存残留

入库范围：常驻规则（CODEBUDDY.md / README.md / state.py）、在途接续入口与
接续包、docs/、交付物/、交接单/、归档/、scripts/、.codebuddy/、
.workbuddy/memory/；共 398 件，其中 >60 KB 的 26 件全为文档。

排除（.gitignore）：tmp/、待清理/、运行态日志与缓存、*.db 与 DB 备份整目录、
打包二进制（*.tar.gz / *.tgz）、记忆修复前备份。
This commit is contained in:
admin committed 2026-09-24 07:51:03 +08:00
commit ce8e6ceed9
396 files changed
+66045
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

归档/dsh-server-docs-清理-20260924/T08-执行标记-已释放.md
+20
View File
@@ -0,0 +1,20 @@
# T08 执行标记（已释放，2026-09-16 归档）
> 来源 = `05-交接单/.doing-T08/`。该标记自述 **「本轮结束已释放」**，T01–T08 已全完成归档 ⇒
> 按 2026-09-16 用户「相关问题都修复」指示**整体移入归档区**（⛔ 未删内容；R9「禁删锁」指活跃锁，本标记已自述释放）。
### 原 `.doing-T08/OWNER` 全文
占用者: exec-cluster-1a（本轮结束已释放）
状态: **T08 全部完成** —— 集群化 S0–S7 + 真跨机 + 生产整体切换（功能已验证）+ R4 文档库并入代码仓
拓扑（**用户确认的口径，勿改**）:
· 47 = Manager（deployMode=cluster，控制面库 = 47 上的 PG13 /var/lib/dshs-pg，单元 dshs-pg）
+ **Worker w-47（19100）** ← **有意设计**：要跑 admin 的实例；存量用户数据也在 47（零搬运）
· 106 = Worker w-106（19000，经 SSH 反向隧道）← 承载新用户
· 归属：admin/guest → w-47；新用户首次触达工作区即钉住并落 w-106
已实测: admin 实例落在 w-47（w-47 instances=1 / w-106=0；47 scope=1；Host: admin.alotbuy.com 实例页 ✓）
回滚: rm -f /etc/systemd/system/dshs.service.d/cluster.conf && systemctl daemon-reload && systemctl restart dshs
lib 回滚: cp -a /opt/dsh/backups/lib-20260915-175116/lib /opt/dshs/lib
残留小项（见 03-路线图 §二 🟡）: join-worker.sh 一键装机 ｜ 隧道服务化（心跳重建）｜ 集中日志/metrics ｜ smoke-domain 定性
称谓铁律: 「本机」= 跑 WorkBuddy 的开发机；47/106 一律写「远程服务器」
锁: 已释放
归档/dsh-server-docs-清理-20260924/_tmp_r6_s8.md
+167
View File
@@ -0,0 +1,167 @@
---
## §8 执行回报（执行棒 · 2026-09-17 08:35）—— **已回填**
```
【序 ③ 一机一钥 + 信任根 · 执行回报（2026-09-17 08:35）】
一句话判定：S0–S5 全走完。判据 [1]–[9] / [11] / [12] / [13] **全过**；判据 [10] **部分未过**
—— guest(w-106) 实例页 502，真因在**平台的远端实例凭据落盘**（`landModels →
writeHomeFile` 用**本地路径**写 w-106 的 home），**与序 ③ 无关**（覆盖网络侧已用
「经 relay 落点直连 w-106:21000」证明通路完好，见 [10]）。
改了什么（文件级，含行号）：
· 本机（代码仓 D:\github\dsh_shenxian）——
- `src/net/relay/identity.ts`（**新建** 657 行）：四层密钥模型（根→签名者→节点→会话）+
签发/验签/吊销/本地校验的**纯函数与 IO 分区**；判据全在本模块（relay 只做辅助准入）。
- `src/net/relay/keys.ts`（**重写**）：`RelayKeyEntry{network,secret}` + `RelayKeyMap`；
键从 `hostId` 改**逻辑名 `<net>/<hostId>`**；新增 `normalizeKeyRecord` / `isQualifiedName`
/ `lookupKey` / `describeKeyEntry` / `keyEntryOf`；`parseKeysInline` 切点 = **最后一个 `:`**。
- `src/net/relay/server.ts`（4 处）：握手改 `lookupKey(keys, network, hostId)` +
`entry.network !== network ⇒ deny('network-mismatch')`；MAC 之后新增身份校验块
（`identity-no-trusted-signers` / `identity-incomplete` / `identity-${reason}`）；
`authed()` 计数新增 `identityOk` / `identityRequired` / `trustedSigners` / `revokedHosts`。
- `src/net/relay/client.ts`：新增 `identity?` 字段与 `identityFields(challenge)`
（**MAC 输入串一字未改**，只追加字段）。
- `src/net/relay/main.ts`：`loadIdentityForServer()`（强制 + 无签名者 ⇒ **起动即抛**）
+ client 侧装配 `loadClientIdentity`。
- `src/net/relay/index.ts`（barrel 同步）；`src/config.ts:513-531` 新增
`overlayNetworkId` / `overlayDirTrustedKeys` / `overlayNodeKeyFile` / `overlayNodeGrantFile`。
- `src/worker/relay-tunnel.ts`（+`identity` 选项）/ `src/worker/agent.ts:188`（接线）/
`src/web/server.ts`（Manager 拨号通道接线）。
- `07-scripts/overlay-keyring.cjs`（**新建** CLI）：init-root / init-signer / init-node /
sign-signerset / issue-grant / sign-revocations / verify-grant / recover-root；
本次补 `sign-signerset --issued-at` 与 `recover-root` 的**判据②③**（原先 docstring 写了
三条判据、实现只有①，属文档与实现不一致，已补齐）。私钥一律 `writeSecret()` → 0600，
stdout 只打印公钥/指纹。
- `test/overlay-identity.test.mjs`（**新建** 25 例：A1–A4 签名者集合 / B1–B12 凭据校验 /
C1–C3 keys 带网 / D1–D7 端到端含 D5 **先红后绿** / E1 文件面）；
既有测试按新语义更新：`test/relay.test.mjs`(T2)、`test/overlay-auth.test.mjs`(A6)、
`test/overlay-network.test.mjs`(U3/U4/U5)；`package.json` test 脚本挂上 identity 用例。
· 47（Manager + relay）——
- 代码：`/opt/dsh-relay/lib/**`（备份 `lib.bak-r6-20260917-0815`）、
`/opt/dshs/lib/**`（备份 `lib.bak-r6-20260917-0820`）；relay 对账 26/26、dshs 对账 148/148 全同。
- 密钥：`/etc/dshs/overlay-signer-key.pem`（600）+ `.pub`｜`node-manager.key`（600）、
`node-w47.key`（600）｜`node-manager.grant.json` / `node-w-47.grant.json` /
`node-w-106.grant.json`｜`overlay-signers.json`（根签）｜`revocations.json`（签名者签，当前空）。
- 单元：`dshs.service.d/identity.conf`（**新**，Manager 带凭据）；
`dshs-relay.service.d/identity.conf`（**改**，备份 `.bak-r6-20260917-0830`；现为
ROOT_PUBKEYS + SIGNER_SET_FILE + REVOCATIONS_FILE + **REQUIRE_IDENTITY=1**）。
- `/etc/dshs-worker.env` 追加 2 行（`DSHS_OVERLAY_NODE_KEY_FILE` / `..._GRANT_FILE`）。
· 106（Worker）——
- 代码：`/opt/dshs-cluster/lib/**`（备份 `lib.bak-r6-20260917-0820`）。
- 密钥：`/etc/dshs/node.key`（600，**指纹 9a0189a4fb4e52f9**）→ 轮换后 `node.rot.key`
（600，**指纹 8cc227320405b986**）；`node.grant.json` / `node-w-106.rot.grant.json`；
`overlay-signers.json`。
- `/etc/dshs-worker.env` 改 2 行（备份 `/etc/dshs-worker.env.bak-r6-20260917-0825`）。
· 本机（离线根）：`E:\ProgramData\.dshs\{root.key(0600), root.pub, root.recovery-code.txt(0600)}`
· 备份：`lib.bak-r6-20260917-0815`（relay）/ `lib.bak-r6-20260917-0820`（47 dshs + 106 cluster）/
`identity.conf.bak-r6-20260917-0830`（relay drop-in）/ `dshs-worker.env.bak-r6-20260917-0825`（106）
指纹（一次性记全，后续对账用）：
· 离线根 pub `bd6d1219571aa70904b227d3e5e86c3d0c08125312d1b5f9e31da4d71b914dd3` / fp `3f6523302720c531`
· 在线签名者 pub `bad464dfd53048efe7b8531029b3030eda49bc12930703d3a2a8f60e3a7daddf` / fp `ca6e5a1e329c22b5`
· 节点 manager fp `b60215af4c12f835`｜w-47 fp `83269876c41644c0`｜w-106 fp `9a0189a4fb4e52f9` → 轮换 fp `8cc227320405b986`
验收证据（命令原文级，逐条对 §6 编号）：
· [1] 每机独立节点密钥、指纹互不相同 ⇒ 三份 grant 的 nodeKey 互不相同：
manager `2e1c…`(fp b60215af4c12f835) / w-47(fp 83269876c41644c0) / w-106(fp 9a0189a4fb4e52f9)；
轮换实验再证「一机一钥可换」：106 `init-node --key /etc/dshs/node.rot.key` ⇒
`✓ 节点公钥：5e65572611ad6a37c487136086d7852e6fb29c7f530b3a37161eded57f31bf6a` / fp `8cc227320405b986`。
· [2] 篡改签名的入网凭据建不起会话**（先红后绿）** ⇒ `test/overlay-identity.test.mjs` B 组 12 例
（签名篡改 → `bad-signature`；凭据搬 hostId → `host-mismatch`；换密钥 → `key-mismatch`；
过期 → `expired`）+ D5「门关时同一份坏凭据能注册（红）→ 门开时被拒（绿）」。
· [3] 未授权节点被拒且**日志有明确原因** ⇒ 真机两条独立证据：
relay 侧 `[relay] AUTH DENY remote=127.0.0.1:33802 why=identity-revoked-host retryable=false`（×14）；
106 侧 `[relay-client] HELLO rejected reason=identity-revoked-host retryable=false clockSkew≈189ms`。
· [4] relay 准入按 hostId + 校验成员资格 ⇒ `keys.ts` 键改**逻辑名**后：
合法（`AUTH OK host=ops/manager` / `host=ops/w-106`）；跨网（`network-mismatch`，且
`overlay-auth` A6 / `overlay-network` U3/U4/U5 四处既有测试按**新语义**更新并通过）；
未登记 hostId（`keys` 层即拒）。三种路径均有 `AUTH DENY why=…` 日志。
· [5] 失败关闭、零请求发默认机 ⇒ 吊销态下 guest 请求：
dshs 侧 `[relay-dialer] 拨 06-ops/w-106:19000 失败：relay client: dial w-106:19000 refused: target-offline`；
relay `refused` 计数 0→4；**未见任何回退默认机**（A1 的 `ensureHost` 失败关闭仍在位）。
· [6] 撤销单台不牵动全网 ⇒ 吊销 w-106 后：
`counters = {"authed":1,"authFailed":14,"refused":4,"identityOk":1,"identityRequired":true,"trustedSigners":1,"revokedHosts":1}`；
`online = ["manager"]`（**manager 会话 upForMs=180681 全程未断**）；
`[恢复态] admin 实例页（w-47）HTTP 200 time=0.050s`；`dsh_hosts`：`w-47|local|ops|up`。
· [7] 重签后恢复连通 ⇒ 重签**空**吊销清单 + `restart dshs-relay`：
`[identity] 吊销清单：net=ops hosts=[] nodeKeys=0` → `[relay] AUTH OK host=ops/w-106 session=63607538827ee044 ports=[19000]`；
`counters`：`identityOk=3 / identityRequired=true / revokedHosts=0`；`online=["manager","w-106"]`。
🔑 附一条**更强的性质**：先在 106 上**轮换节点密钥**（换新 grant）后**仍被拒**
（`HELLO rejected reason=identity-revoked-host`）⇒ 证明「**撤 hostId 比换密钥更强**」。
· [8] 根密钥 ≥2 份离线副本 + 恢复演练 ⇒ **演练三判据全绿，耗时 794 ms**：
`✓ [判据①] 与期望根公钥逐字节一致`；
`✓ [判据②] 重建的根签出的 SignerSet（1 把）经原根公钥验签通过`；
`✓ [判据③] 签名与原根私钥签出的逐字节相同`（Ed25519 确定性 ⇒ 排除"看着像其实不是同一把"）。
⚠️ **副本数 = 2 份「离线保管载体」但都在本机**：`root.key`(0600) + `root.recovery-code.txt`(0600，96 hex)；
真离线介质（U 盘 / 纸）需你亲落 ⇒ 本条判 **部分过**。
（演练从**恢复码**重建，**不使用**原根文件；原根仅用于产出待比对的基准签名。演练产物含一份根私钥副本，已即时删除。）
· [9] 密钥文件权限 0600、属主正确 ⇒ 47 `600 root:root`：`node-manager.key` / `node-w47.key` /
`overlay-signer-key.pem` / `overlay-dir-key.pem` / `relay-keys.json`；106 `600 root:root`：
`node.key` / `node.rot.key` / `relay-keys.json`。（`.pub` 与**已签名清单**为 644，不含秘密。）
· [10] 不退化 ⇒ **三条过、一条未过**：
✅ admin(w-47) 实例页 `HTTP 200 time=0.050s`；
✅ `dsh_hosts`：`w-106|relay|ops|up`（`via='relay'` 保持）；
✅ relay 常驻未掉（`systemctl is-active dshs-relay` = active，`identityRequired=true`）；
✅ **覆盖网络侧端到端活证**：经 relay 本机落点 `curl -H "Host: guest.alotbuy.com" http://127.0.0.1:34539/`
⇒ `HTTP 401 68B`，与 **106 本机直连 `http://127.0.0.1:21000/` 的 `401 68B` 完全一致**
（relay `endpoints` 同时给出 w-106 的 `19000` 与 `21000`，`streams>0`、`in/out` 有流量）；
⛔ **未过** guest(w-106) 实例页 = **nginx 502（0.70 s，确定性复现，非超时）**。
· [11] 47 公网暴露面净增 = 0 ⇒ 公网监听集合 =
`0.0.0.0:22 / 0.0.0.0:80 / 0.0.0.0:443 / 0.0.0.0:58888(BT-Panel) / 0.0.0.0:888 / 0.0.0.0:8765 / [::]:22`
—— **全是原有的**；序 ③ 新增的只有**回环**口：`127.0.0.1:20080`（relay）与 `127.0.0.1:25000+`（拨号落点池）。
· [12] npm test 全绿 ⇒ Node **v22.22.2**：`# tests 130 / # pass 129 / # fail 0 / # cancelled 0 / # skipped 1`
（31914 ms），随后 `verify-inject` 六项全 `✓`、`结论：全部合格 ✅`。
· [13] 本机 lib vs 47 /opt/dshs/lib **0 差异** ⇒ `local=148 remote=148`，路径不对称 0，内容不同 0；
另：relay 侧 `local=26 remote=26`，0 差异；
`07-scripts/overlay-keyring.cjs` md5 `0727cd436c3b923e48d0c8dd654d2ac4` **三处一致**（本机 / 47 / 106）。
· [未过] [10] 卡在哪 = ① `dsh_instances` 里 guest 记录 `status=stopped`（真机上实例却在跑），
⇒ 平台走 `RemoteSpawner.launch`；② 该路径上 `landModels → home-files.js:45 writeHomeFile`
打开 **`/var/lib/dshs/users/4092b965-…/home/.credentials.yaml`** 时 `ENOENT`
—— 这是**47 本地路径**，而 guest 的 home 自 09-16 22:51 起已在 **106**（47 上该目录只剩 `ws/`）；
日志原文：`model landing failed, falling back to env injection Error: ENOENT: no such file or directory, open '…/home/.credentials.yaml'`，
栈：`writeHomeFile(home-files.js:45) → landModels(server.js:172) → resolveApiKey(server.js:200) →
RemoteSpawner.launch(remote-spawner.js:169)`；③ 该请求在 dshs 侧 `incoming request` 之后**无
`request completed`**，由 nginx 返 502。
**为什么判定与序 ③ 无关**：失败点在「凭据写 home 的本地路径」，与 relay 身份准入无交集；
且同一时刻的覆盖网络证据全绿 —— relay 已建立到 w-106 的 `19000`/`21000` 两条隧道、
`dial up` 成功、经隧道取实例回 401（活）。**序 ③ 只动了 identity / keys 逻辑名 / relay 准入 / 配置，
未触碰 `landModels`、`home-files`、`remote-spawner`、`dsh_instances` 状态机。**
已做到 = 网络面与身份面全部证明完好、admin 面 200、平台与实例两侧均无崩溃（`dshs` NRestarts=0、
`dshs-worker` NRestarts=0）。
什么条件一出现必须回头解决 = **① `landModels/writeHomeFile` 改为经 `RemoteUserFs` 写远端实例 home
（或平台对「实例已在跑但 DB 记 stopped」做状态对账）；② 或 guest 实例状态回到 `running` 后，
立即重测判据 [10] 的 guest 页**。⇒ 建议并入序 ④ 的相邻缺陷清单，**不在本单范围内顺手改**（R7）。
我选了什么（可推翻）：
· 密钥表键 = **逻辑名 `<net>/<hostId>`**（不是裸 hostId）—— 因 U5 暴露"同 hostId 无法存在于两张网"是净变差。
· 受信根 = `DSHS_OVERLAY_ROOT_PUBKEYS` **独立于** `DSHS_OVERLAY_DIR_PUBKEYS`（⛔ 不合并：合并等于让"能换地址的人"顺带能加签名者）。
· 复用 `directory.ts` 的 Ed25519 原语，**不新造第二套签名机制**（符合 D1/D6）。
· 强制身份**本轮就开**（`REQUIRE_IDENTITY=1`）而非留到下一轮：三台节点均已带身份且实测 `identityOk=3`，
吊销演练**只有开强制才可观察**；回滚 = 删该两行 + `daemon-reload` + `restart dshs-relay`（单步）。
· 106 节点密钥**就地轮换**（`node.rot.key` 取代 `node.key`，env 指向新文件）—— 顺带证明"一机一钥可换"。
· 密钥仪式工具**部署到 47/106**（`/opt/dsh-relay/scripts/`、`/opt/dshs-cluster/scripts/`），
因为**签名者私钥不出机器** ⇒ 签发/吊销必须在 47 上跑。
· 报告与单子同文件（§8 就地回填），不另开文件。
未做 / 越界记录：
· 交 **序 ④** 的：443/TCP 兜底（本单未碰）。
· 交 **序 ⑤** 的：参数表 / 观测 / 权限评估（本单未碰）。
· **命中 R5 待评估的：无** —— 本次所有改动都是**收窄**（relay 从"任何持任意密钥者都能声称任意合法网名"改为
"凭据 + 成员资格 + 吊销"三级；公网暴露面净增 0）。
· 额外发现、**只报告未动手**（R7）：
① [10] 的平台侧远端凭据落盘缺陷（见上）；
② `/opt/dshs/mksess*.cjs` 仍写 **`/var/lib/dshs/dshs.db`（SQLite，仅回滚用）**，
而权威库已是 47 的 PG13 ⇒ **该工具已失效**（本次改用 PG 直插临时 session 完成 R4 合规验收，用完即删，残留 0）。
· 本单**未 commit / 未 push**（按约束 4）。
下一棒建议：**序 ④ · 443/TCP 兜底** —— 先出**规划棒**（给序 ④ 出一份可执行交接单），
读 `D:\github\dsh_shenxian\dsh-server-docs\` 里 `覆盖网络_应用场景与待完善清单 §五` +
工作区根 `接续入口_覆盖网络线_20260916.md §0/§2`；⚠️ 把上面 [10] 的两条额外发现并入其相邻缺陷清单。
指纹：md5(本单) = 260a2e84a8a482cf08705885735986ee（回填前）；本机/47/106 产物 hash 对账 = 148/148 + 26/26 + 3/3 全同
```
> 📌 **回填说明**：上面代码块是**本节交付物本身**（§8 要求的报告），未改动 §1–§7 任何一行。
归档/dsh-server-docs-清理-20260924/_自动接续简报_20260916.md
+126
View File
@@ -0,0 +1,126 @@
# 自动接续简报 · 「决策方法-2」（2026-09-16 11:10—11:5x）
> 接续对象 = 会话 `e2e090be`（标题「决策方法」）末尾「📌 接续点」的三项用户任务。
> **只做这三项**，未新增自造任务；批量活全部脚本化（4 个脚本落在 `_中间产物_待清理/auto-continue-20260916/`）。
---
## 一、做了什么（三项逐条）
### 任务① 全量文档无效信息审计 —— ✅ 完成
- **范围**：`.workbuddy/memory/*.md` 31 份 / 1,325 KB ＋ 技能 md 12+ 份 / 348 KB ＋ 工作区根方案文档 23 份 / 964 KB ＝ **66 份 / 2,643 KB**。
- **判定**：✅ 整体健康。**重复字节率 memory 1.3% / 技能 0.3% / 根方案 0.0%**；套话 **0 处**。
- **2 处真实问题**：
- 根 `_中间产物_待清理/sess-forensics-20260916/会话脉络_ddea70b7_20260916.md` = **589.6 KB（占根方案 61%）**，是会话转录摘录，结论已被三处吸收 ⇒ 属可归档的中间产物（**本轮未动**，R7-边界）。
- 用户级记忆被截断（见任务②）。
- **产物**：`文档无效信息审计报告_20260916.md`（工作区根）。
### 任务② `.workbuddy/memory/MEMORY.md` 整编 —— ✅ 完成（但对象修正）
🔴 **关键实测：被截断的不是工作区那份，是用户级那份。**
| 文件 | 体量 | 是否被截断 |
|---|---|---|
| 工作区 `.workbuddy/memory/MEMORY.md` | 11,986 B / 7,219 chars | **否**（注入完整） |
| 用户级 `E:\ProgramData\.workbuddy\MEMORY.md` | 20,977 B / 11,712 chars | **是**（注入上限 ≈4,000 chars） |
- **处置（用户级）**：**分层重排、零删除** —— 原排序的注入窗口只覆盖「钩子配置 + 环境路径」，**一条行为规则都没进去**；重排后窗口 = `Preferences`（全部硬规则）→ `⛔ 硬禁令` → 环境路径 → 环境网络陷阱。文件头加**排序契约**（⛔ 新增内容按序插入，别追加到末尾），防止下次追加又把它顶出窗口。
- **处置（工作区）**：**未改动**，理由三条 —— ① 实测未被截断（目标已由 10:45 轮 -26% 达成）② 它的「§一/二/三/四」数字编号被多处文档当锚点引用，重排属**净变差风险**（R11）③ 继续删内容有丢规则风险。
- **整编四条件**：抢锁 ✅（本人持锁）｜备份 ✅（`.workbuddy/memory/.backup-20260916/MEMORY.md` ＋ `E:\ProgramData\.workbuddy\.backup-20260916\MEMORY.md`）｜token 回扫 ✅（窗口覆盖率已实测打印）｜`docs-shrink-guard.py --write` ✅（基线 151 文件）。
### 任务③ 核验 10 篇未推送档案 —— ✅ 完成，双端 **191/191 全绿**
- **先核**：锁由本人独占 ⇒ 无并行会话在做；`docs-sync-check.sh` 报 **仅本地 10 ＋ 内容不一致 4**（不是 3 —— `BRIEF.md` 是 10:45 轮新增的）。
- **取证**：拉回服务器旧版逐文件比对 —— `INDEX.md` / `03-路线图与待办.md` **服务器独有 0 行**；`BRIEF.md` / `docs-manifest.json` 虽有"服务器独有行"，但 diff 证明**是同一行的旧版本**（`最后人工核对 09-12 → 09-16`、旧待办行 → 新待办行、manifest 计数 `138→148` 文件）⇒ **纯前向增量，无内容丢失**。
- **推送**：只推本清单 **14 个**文件（10 档案 ＋ `BRIEF.md`/`INDEX.md`/`docs-manifest.json`/`03-路线图与待办.md`），走 `tar` 流保原始字节；**未 `git add -A`**、未删任何文件、未 `push`。
- **复跑对账**：一致 **191** / 内容不一致 **0** / 仅本地 **0** / 仅服务器 **0** ⇒ ✅。
---
## 二、未完成（如实）
1. **`BRIEF.md` 的改动未 `git commit`** —— 本次任务清单未授权提交（红线：未明确要求不 commit / push / 同步）。⇒ 当前状态是**镜像与 git 工作区不一致，git 落后于镜像**。补一条命令即可收口，但**本轮未做**。
2. **上一轮遗留的 6 个未提交改动**（`07-scripts/bash-output-guard.py`、`lock-guard-hook.py`、`stop-dialog-guard.py`、`08-skills/*/SKILL.md`×3 ＋ 新文件 `skill-load-guard.py`）**仍未提交** —— 同上，未授权。
3. **档案 `04-调整方案/.lock-*` 残留 17 个**（原 6 ＋ 103–112 占号 10 ＋ 本轮无新增）—— 未删（锁的处置权只属用户）。
4. **`05-交接单/.doing-T08` 与 T08 单子未 `git mv` 归档** —— 与 `.doing-T08` 绑定，处置权属用户。
5. **审计报告里那 3 条建议未执行**（`dsh-knowledge-upkeep §8` 补"注入预算"维、根目录 23 份方案文档收敛、9 月日志待 10 月蒸馏）—— 均属**新任务**，按硬要求②不自造。
6. **会话 `ddea70b7` 的转录取证件 589.6 KB 仍躺在工作区根** —— 建议搬入 `_中间产物_待清理/`，未做。
---
## 三、遇到什么
1. 🔴 **接续点给的前提是错的**（最有价值的一条）：任务②写「清理被截断的 `.workbuddy/memory/MEMORY.md`」，但实测**工作区那份注入完整**，被截断的是**用户级** `E:\ProgramData\.workbuddy\MEMORY.md`。⇒ 照字面做 = 改了个没坏的文件、留了个真坏的。**教训同 A1：交接单给的前提也要先做一次最小取证。**
2. ⚠️ **机械检测器在"过程流水 / 悬空引用"两类上噪声极高**（45 处、30 处 → 真命中 **0**）⇒ 已如实写进报告，避免下个会话误信自动结论。
3. ⚠️ **"服务器独有行"≠"本机丢内容"** —— 必须先 `diff` 语义确认（本次证明是同一行的旧版本）。若跳过这一步，就会误报"推送抹掉了别人的东西"。
4. ⚠️ **提示词给的"10 篇未推送"少算了 1 项**：实际是 **10 仅本地 ＋ 4 内容不一致**（`BRIEF.md` 是 10:45 轮新引入的），已一并处理。
5. ⚠️ **`docs-shrink-guard.py --write` 是全库刷基线**（151 文件）—— 本次是"改完文件后"的正常动作，但它会**顺带抹掉别人未提交整编的告警**，此点已记入报告供后续注意。
---
## 四、锁状态（如实）
| 项 | 状态 |
|---|---|
| 抢锁 | ✅ 11:12 抢到，占用者 = **`auto-决策方法-2`**（`05-交接单/.exec-lock`） |
| 中途释放过吗 | 否（全程独占；任务期间未停手、未交接） |
| 收尾 | ✅ 已按反序释放：先 `--release`（本会话声明）→ 最后 `--release-exec` |
| 并发冲突 | 无 —— 开工时 `【1d】` 服务器侧操作锁为空；`【2】` 报 12 个越界未提交改动（**全是前一/多会话遗留**，本轮一个都没动、没提交、没推） |
| 是否动过服务器代码 / 实例 | **否**（只推文档到镜像 `/opt/dsh/docs`，属文档库交付闭环） |
| 是否删过任何文件 | **否** |
---
## 五、本轮改动清单
**新增（工作区根）**：`文档无效信息审计报告_20260916.md`、`_自动接续简报_20260916.md`
**新增（中间产物）**：`_中间产物_待清理/auto-continue-20260916/` 下 4 个脚本 ＋ `audit_raw.json` / `audit_pass2.json`
**修改**：`E:\ProgramData\.workbuddy\MEMORY.md`（**分层重排，零删除**；备份在 `E:\ProgramData\.workbuddy\.backup-20260916\MEMORY.md`）
**备份**：`.workbuddy/memory/.backup-20260916/MEMORY.md`（工作区那份**未改**，备份仅供留档）
**镜像推送**：14 个文件 → `/opt/dsh/docs`，对账 **191/191 全绿**
**回滚**：用户级记忆 = 用备份文件覆盖回去即可（单命令）；镜像 = 无需回滚（内容为纯前向增量）
**⛔ 未做**：未 commit、未 push git、未删文件、未改服务器代码 / 实例 / 配置
---
> 📌 **给下一个会话的一句话**：本轮的"未完成"里，**只有第 1、2 条（提交）是闭环缺口**，其余都是等用户拍板或本不该做。
---
# 六、修复轮（2026-09-16 11:25—11:5x）
> 用户指示：「**相关问题都修复，先确认情况在修复**」。⇒ 先取证、再动手，全程只做修复、未新增任务。
## 6.1 先确认 —— 取证推翻了**我自己的**一处结论
🔴 **审计报告首版有一处假阴性**：我用「归一化整串包含」判断"根文档是否已入档案"，得出"10 份**都未被包含**"⇒ 据此写进报告的建议是错的。改用**行级覆盖率**复核后实测 **98.5–99.0%**（差异仅一级标题行，因为档案按约定删了 H1）⇒ **已在报告里改正并留下错误记录**。
📌 教训与报告 §一 记的"检测器噪声"是**同一类**：机械判据必须先验证判据本身。
## 6.2 已修（逐项，均有实测）
| # | 问题 | 处置 | 结果 |
|---|---|---|---|
| 1 | 589.6 KB 转录取证件躺在工作区根 | 移入 `_中间产物_待清理/sess-forensics-20260916/` + 修 3 处引用 | 根 `.md` **964.1 → 375.0 KB（-61%）** |
| 2 | `04-调整方案/.lock-*` 残留 16 个 | 全为空目录，已 `rmdir`（⛔ 未动 `.exec-lock`，R9） | 清零 |
| 3 | `.doing-T08` 未撤 + T08 单子未归档 | 单子移入 `05-交接单/`；`.doing-T08` 自述"本轮结束已释放" ⇒ **整体移入归档区**（内容保留为 `T08-执行标记-已释放.md`，⛔ 未删内容） | 归档完成 |
| 4 | 未提交改动（7 改 + 4 新增） | **5 个定向 commit**，⛔ 无 `git add -A` | git 工作区**全干净**，HEAD `59f1a89` |
| 5 | `dsh-knowledge-upkeep §8` 缺"注入预算"维 | 技能 **1.1.0 → 1.2.0**，新增 **§8.6**；md5 `6249caaa…` **本机/文档库/镜像三处一致** | 三处同步 |
| 6 | 审计报告的 3 条建议 | ① 已落地（同 5）；② **改为"加归档指针、⛔ 不搬"**（10 份被 11 处引用，搬走会断链）；③ 10 月时间触发，不适用 | 收口 |
| 7 | `接续入口_覆盖网络线` §0/§2 状态陈旧 | 就地刷新（§0 三行 + §2 六条逐项标状态 + 成本教训第 2 条） | 下个会话不会再重做已完成项 |
## 6.3 收尾验收（全部实测）
- `docs-audit.py` 退出码 **0**｜`docs-manifest.py` 退出码 **0**｜`docs-consistency.py`「承诺现行的文件与现行值一致 ✓」
- `docs-sync-check.sh`：**192/192 一致，0 差异 ✅**
- 镜像同步：技能 + `05-交接单/archive` + `docs-manifest.json` 已推；服务器上已移动的旧路径（`05-交接单/T08-*.md`、`.doing-T08`）已清（内容都在 archive）
- 5 个 commit：`500011d` `c8b5148` `bda9b10` `744ed98` `59f1a89`
## 6.4 仍未做（如实）
1. ✅ **已 push（2026-09-16 13:0x，用户「可以push」授权）** —— 远端 `master`：`68c0a32` → **`59f1a89`**，**快进 17 个提交**（含此前积压的 12 个），`--dry-run` 与实际一致，推后重新 `ls-remote` 复核**远端 == 本机**。
🔑 **本机坑**：`git fetch` 在本机**静默失败**（`refs/remotes/**` 写不进去）⇒ `origin/master` 引用不可用 ⇒ 用它会得出**假"非快进"**并白白停手。**正解 = `ls-remote` 取裸 sha ＋ `git merge-base --is-ancestor`**（已写进 `MEMORY.md`）。
2. `INDEX.md §二` 既有失真（13 行落在 §二 表格外 ⇒ `docs-index-stats.py` 读不到）**未动** —— 搬别人的行有风险，留待专项。
3. 服务器代码 / 实例 / 配置：**零改动**（本轮只推文档镜像）。
**锁状态**：修复轮 11:25 重新抢到（`修复轮-决策方法-2b`），收尾已 `--release-exec` 释放。
归档/dsh-server-docs-清理-20260924/dsh-improvement-plan-20260909-full.md
+555
View File
@@ -0,0 +1,555 @@
# dsh（DeepSeek Harness）多用户部署与配置改造方案
| 项 | 值 |
|---|---|
| 版本 | v1.0（2026-09-08） |
| 适用对象 | 服务器 47.77.182.89（root SSH 端口 32022） |
| 软件 | @deepseek-ai/dsh 0.1.2-rc.1（镜像 dsh-web:0.1.2） |
| 状态 | **P0 迁移已执行（2026-09-08 17:30）**；**域名接入完成（2026-09-08 18:00）**；**架构切换为 dshs 多租户 + account 硬隔离（2026-09-08 18:30）** |
| 文档位置 | 本机 `D:\AI技能\aliyun-work-space\dsh-server-docs\`；服务器 `/opt/dsh/docs/` |
---
## 一、背景与目标
dsh Web UI 已单实例部署并跑通（外网 http://47.77.182.89/，模型对话正常）。需要从「单人单实例」升级为「公司多人使用」形态。
**目标（5 项）**：
1. **多用户使用**：多个编导/账号运营各自登录使用；
2. **数据持久化**：会话、配置、凭据、工作区不随容器重建丢失；
3. **跨用户文件安全**：用户之间互相看不到对方的数据与工作区（严格隔离）；
4. **便于使用/复制/恢复**：一个用户 = 一个主目录，备份恢复按目录粒度一键完成；
5. **登录方式可扩展**：前期用账号密码（注册审核制），后期可按需接入飞书 OAuth。
---
## 二、现状盘点（2026-09-08 服务器实测）
```
/opt/dsh/
├── backups/20260908_initial/ # 旧备份（已归档）
├── docs/dsh-improvement-plan.md # 本文档
├── users/main/.dsh/ # ★ 迁移后：容器 /root/.dsh（原 data/）
├── users/main/workspaces/ # ★ 迁移后：容器 /root/workspaces（工作区卷，新约定）
├── .env # 系统模型 key（--env-file）
├── backup.sh / restore.sh # 备份恢复脚本
└── dsh-web-0.1.2.tar # 镜像 tar（140MB）
容器 dsh-web：Up，--network host，--restart always
挂载：/opt/dsh/users/main/.dsh → /root/.dsh
/opt/dsh/users/main/workspaces → /root/workspaces
环境：DEEPSEEK_API_KEY（--env-file /opt/dsh/.env）
端口：容器内 127.0.0.1:8900 → nginx 反代 80（Host/Origin 伪装 127.0.0.1）
访问：token 认证（docker logs 取）→ dsh-auth cookie（30 天）
```
已知问题：容器内工作区 `/root/maiyamcn` 已丢失（重建容器后被清掉，注册表残留失效路径）——**工作区必须卷化持久化**。迁移后此问题已解决，但 storages/workspace.json 中旧路径 `/root/maiyamcn` 记录仍在，需在 Web UI 删除该失效工作区入口。
---
## 三、总体架构（目标态）
**核心原则**：
- **一个用户 = 一个主目录 + 一个实例**：`/opt/dsh/users/<uid>/`，备份/复制/恢复只对这一个目录操作；
- **严格隔离**：每用户独立实例（容器），独立 `~/.dsh` 与工作区，互相不可见；
- **系统标准层（公共模型/插件/技能）只读共享**，用户增量放在个人层，同名覆盖系统层（dsh 原生分层机制，无需自研）；
- **配置分层**：dsh 插件 bundle → profile 层 → home 级用户覆盖层 → `--patch`，天然支持「公司统一 + 个人覆盖」。
### 目录布局（目标态）
```
/opt/dsh/
├── .env # 系统级模型 key（DEEPSEEK_API_KEY），容器 --env-file 注入
├── std/ # ★ 系统标准层（只读，管理员维护）
│ ├── agents/skills/ # → 容器 /root/.agents/skills（rank400 兜底标准技能库）
│ │ └── mcn-video-script/ # 公司标准技能（SKILL.md + references，只读）
│ └── profile-skel/ # 新用户 profile 种子（含公共插件 bundles 声明）
├── users/ # ★ 每用户 = 一个主目录（实例隔离边界）
│ ├── main/ # ─ 管理员实例（由现有 data/ 迁移而来）─
│ │ ├── .dsh/ # → 容器 /root/.dsh（DSH_HOME）
│ │ │ ├── profiles/web/
│ │ │ │ ├── dsh.profile # bundles 有序清单（官方 + 公共插件）
│ │ │ │ ├── cordis.patch.yml # profile 层配置
│ │ │ │ └── node_modules/ # 个人插件落点（dsh plugin add，只影响本用户）
│ │ │ ├── cordis.patch.yml # ★ home 级用户覆盖层（优先级高于 profile 层）
│ │ │ ├── .credentials.yaml # ★ 个人模型 key（用户在 Models 页填写）
│ │ │ ├── settings.yaml # 用户全局设置
│ │ │ ├── 08-skills/ # ★ 个人技能 rank300（可覆盖系统标准同名技能）
│ │ │ ├── sessions/ # 会话数据
│ │ │ └── storages/ # 存储数据
│ │ └── workspaces/ # → 容器 /root/workspaces
│ │ ├── maiyamcn/ # 工作区项目（=容器内 workspace 根）
│ │ │ ├── .dsh/skills/ # 项目级技能 rank100（最高优先，随项目分发）
│ │ │ ├── .agents/skills/ # 项目级技能备选 rank200
│ │ │ ├── AGENTS.md # 项目指令
│ │ │ └── ... # 项目文件/素材/脚本
│ │ └── <其他项目>/
│ ├── zhangsan/ # ─ 编导 A（与 main 完全同构）─
│ │ ├── .dsh/
│ │ └── workspaces/
│ └── lisi/ # ─ 编导 B ─
├── backups/ # 备份产物（backup.sh 打包 users/ → 时间戳 tar.gz）
│ └── 20260908_initial/ # 旧备份归档
├── backup.sh # 一键备份
└── restore.sh # 一键恢复
```
### 运行拓扑（多用户）
```
镜像 dsh-web:0.1.2（官方 bundle + 公共插件 + std 标准技能内置/挂载）
├── dsh-web-main --network host → 8900 # 管理员
├── dsh-web-zhangsan --network host → 8901 # 编导 A
└── dsh-web-lisi --network host → 8902 # 编导 B
nginx 外网按子域名/路径分流到 127.0.0.1:890x（沿用现有 Host/Origin 伪装模板）
```
---
## 四、dsh 分层机制要点（方案依据）
dsh 配置与插件天然分层，以下机制是方案成立的前提（无需自研）：
1. **配置/插件叠加顺序**（后层覆盖前层）：
```
插件 bundle 默认（官方/系统）
→ profile 层 $DSH_HOME/profiles/web/cordis.patch.yml
→ 用户层 $DSH_HOME/cordis.patch.yml
→ 命令行 --patch（最高）
```
2. **SKILL 发现目录**（rank 越小优先级越高，同名高优先覆盖低优先）：
| rank | 目录 | 性质 |
|---|---|---|
| 100 | 工作区根 `/.dsh/skills/` | 项目级（随项目分发） |
| 200 | 工作区根 `/.agents/skills/` | 项目级备选 |
| 300 | `~/.dsh/skills/` | 用户个人 |
| 400 | `~/.agents/skills/` | 用户级全局（**系统标准库落点，只读兜底**） |
3. **插件安装**：`dsh plugin --profile <name> add <源>`（npm/GitHub/git/tarball/link），写入该 profile 的 bundles 层与 node_modules，**只影响该用户实例**。
4. **模型 provider**：即插件；key 走 credentials service（UI Models 页 → `.credentials.yaml`）或环境变量（`DEEPSEEK_API_KEY`）。
---
## 五、模型 / 插件 / SKILL 归属矩阵
| 能力 | 公共（系统层，管理员维护） | 个人（用户可改） | 项目（随工作区） |
|---|---|---|---|
| 模型 | `.env` 统一 key + profile 层默认 provider；**用户不自配模型**（见安全限制） | `.credentials.yaml` 个人 key（若开放） | — |
| 插件 | 镜像预置公共插件（官方 bundle 同级，人人可用，不可改） | `profiles/web/node_modules` + bundles 声明（`dsh plugin add`，需网络） | — |
| SKILL | `std/agents/skills`（rank400 只读兜底，**同名可被用户覆盖**） | `~/.dsh/skills`（rank300） | 工作区 `.dsh/skills`(100) / `.agents/skills`(200) |
> 一句话：**公共层只读放低优先，个人层可写放高优先**——公司统一给兜底，个人自配天然覆盖，无需把标准配置复制 N 份。
---
## 六、单实例迁移执行步骤（从当前 data/ 形态 → users/main 形态）
> ⚠️ 以下命令在服务器执行（root）。当前容器 `dsh-web` 以 `/opt/dsh/data` 为 `/root/.dsh`。
```bash
# ===== 1. 停容器 + 重组目录 =====
docker stop dsh-web
mkdir -p /opt/dsh/backups
mv /opt/dsh/backup-20260908 /opt/dsh/backups/20260908_initial # 旧备份归档保留
mkdir -p /opt/dsh/users/main
mv /opt/dsh/data /opt/dsh/users/main/.dsh # data 落入主目录
mkdir -p /opt/dsh/users/main/workspaces
# ===== 2. 固化密钥 + 重建容器（挂载主目录内两点） =====
DK=$(docker inspect dsh-web --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^DEEPSEEK_API_KEY=' | cut -d= -f2-)
printf 'DEEPSEEK_API_KEY=%s\n' "$DK" > /opt/dsh/.env
chmod 600 /opt/dsh/.env
docker rm dsh-web
docker run -d --name dsh-web --restart always --network host \
-v /opt/dsh/users/main/.dsh:/root/.dsh \
-v /opt/dsh/users/main/workspaces:/root/workspaces \
--env-file /opt/dsh/.env \
dsh-web:0.1.2 dsh web --host 127.0.0.1 --port 8900 --no-open --trusted-host 47.77.182.89
# ===== 3. 生成备份/恢复脚本 =====
cat > /opt/dsh/backup.sh <<'EOF'
#!/bin/bash
# 一键备份：打包 users/ 全部用户主目录 → backups/时间戳.tar.gz
set -euo pipefail
TS=$(date +%Y%m%d_%H%M%S)
OUT=/opt/dsh/backups/dsh-backup-${TS}.tar.gz
cd /opt/dsh
docker stop dsh-web 2>/dev/null || true
tar -czf "$OUT" users
docker start dsh-web 2>/dev/null || true
echo "备份完成: $OUT"
ls -lh "$OUT"
EOF
cat > /opt/dsh/restore.sh <<'EOF'
#!/bin/bash
# 一键恢复：./restore.sh <备份tar.gz>（当前数据先挪走可回滚）
set -euo pipefail
TAR=${1:?用法: ./restore.sh /opt/dsh/backups/dsh-backup-xxx.tar.gz}
test -f "$TAR" || { echo "备份文件不存在: $TAR"; exit 1; }
TS=$(date +%Y%m%d_%H%M%S)
cd /opt/dsh
docker stop dsh-web 2>/dev/null || true
[ -d users ] && mv users users.old-$TS
tar -xzf "$TAR"
docker rm -f dsh-web 2>/dev/null || true
docker run -d --name dsh-web --restart always --network host \
-v /opt/dsh/users/main/.dsh:/root/.dsh \
-v /opt/dsh/users/main/workspaces:/root/workspaces \
--env-file /opt/dsh/.env \
dsh-web:0.1.2 dsh web --host 127.0.0.1 --port 8900 --no-open --trusted-host 47.77.182.89
echo "恢复完成（旧数据在 users.old-$TS，确认无误后可删）"
EOF
chmod +x /opt/dsh/backup.sh /opt/dsh/restore.sh
# ===== 4. 验证 =====
docker ps | grep dsh-web
curl -s -X POST http://127.0.0.1:8900/api/llm/listProviders \
-H 'Content-Type: application/json' \
-d '{"type":"client-request","rpcId":"v1","method":"llm/listProviders","payload":{"args":{}}}'
# 期望 {"ok":true,"value":[{"id":"deepseek-official",...}]}
/opt/dsh/backup.sh
```
---
## 七、备份与恢复语义
- **备份 = 打包 `users/`**（全部用户主目录，一个 tar）；`.env`（部署配置）与 `std/`（可再生成）不进备份；
- **恢复 = 解压 + 重建容器**（restore.sh 已固化容器参数）；
- **复制/迁移用户**：拷 `/opt/dsh/users/<uid>` 到新机同路径即可；
- 多用户同构扩展：新用户增加 `users/<uid>/`，脚本无需改动（tar 整体 users/）。
---
## 八、多用户扩展（dshs 落地前的过渡方案）
目标：**每用户独立实例 + 严格隔离**。新增一个用户 = 一套同构目录 + 一个容器 + nginx 分流：
```bash
# 以新增 zhangsan 为例（示例脚本 add-user.sh）
UID_NEW=zhangsan
PORT=8901
mkdir -p /opt/dsh/users/${UID_NEW}/.dsh /opt/dsh/users/${UID_NEW}/workspaces
# 从 main 复制 profile 骨架（不含凭据/会话），或从 std/profile-skel 初始化
docker run -d --name dsh-web-${UID_NEW} --restart always --network host \
-v /opt/dsh/users/${UID_NEW}/.dsh:/root/.dsh \
-v /opt/dsh/users/${UID_NEW}/workspaces:/root/workspaces \
--env-file /opt/dsh/.env \
dsh-web:0.1.2 dsh web --host 127.0.0.1 --port ${PORT} --no-open --trusted-host 47.77.182.89
# nginx：新 server/server_name 分流 → 127.0.0.1:${PORT}，沿用 Host/Origin 伪装头模板
```
> 说明：web profile 首次启动会自动初始化模板，新用户空 `.dsh` 直接起容器即可；系统标准技能层由 `std/` 挂载提供。
### 认证路线
| 阶段 | 方案 | 说明 |
|---|---|---|
| 当前 | dsh 自带 token（一次性） | 仅单人过渡 |
| 近期 | **dshs 密码制基座**（每用户独立 DSH 实例 + 注册审核） | 多租户严格隔离的正规托管方案 |
| 后期 | **飞书 OAuth 登录** | 替换/并存 dshs 密码认证，预留扩展点 |
> 备选认知：`@xgone/dsh-remote` / `dsh-passwords` 类认证网关是共享单租户，无法满足严格隔离，不采用。
---
## 九、安全边界与已知限制
1. **dsh 禁 `--host 0.0.0.0`**（RCE 防护），容器内只监听 127.0.0.1 → 必须 `--network host` + nginx 反代；
2. **特权 API 强制 loopback-only**（settings/credentials.describe 等），即使 `--trusted-host` 也拒非本机访问 → nginx 必须把 `Host`/`Origin`/`Sec-Fetch-*` 头伪装为 `127.0.0.1:8900`（现有反代模板已含）；
3. **Settings/Models 页前端 loopback 检测**：非本机浏览器地址访问时页面禁用（`settings are unavailable in this browser`）→ 外网用户**无法在 UI 自配模型**；普通用户模型一律管理员统一配置；要开放自配需对 web 前端打 `--patch` 放行（待验证项）；
4. **插件 = 任意代码执行**：普通用户不开 `dsh plugin add` 权限；公共插件管理员审核后入镜像；
5. **token 认证**：每实例首次启动生成 token，nginx 后建议加一层 Basic Auth 或尽快接 dshs；
6. `.env` 含密钥，权限 600，不进备份包（整机迁移需单独携带或重设）。
---
## 十、待验证项（Open Questions）
| # | 问题 | 影响 | 验证方式 |
|---|---|---|---|
| 1 | `.env` 注入的 `DEEPSEEK_API_KEY` 与用户 credentials 中个人 key 的优先级 | 决定统一 key 是否为硬兜底 | 容器内同时存在时调 `llm/listProviders` 观察 |
| 2 | web profile 空 `.dsh` 首启是否能自动初始化模板（供 add-user 流程） | 新用户目录初始化方式 | 用空目录起测试容器观察 |
| 3 | 前端 loopback 检测能否用 `--patch` 放行 | 用户是否可自配模型 | 社区/源码调研 + 试验 |
| 4 | dshs 对 web Settings 限制的处理方式 | 密码制基座下用户可配置面 | 部署后实测 |
| 5 | 容器内 `dsh plugin add` 走 npmmirror 是否可装 | 用户/管理员装公共插件渠道 | 实测 add 一个测试插件 |
---
## 十一、路线图
- [x] **P0 执行本方案第六节迁移命令**（data → users/main，双卷挂载，脚本就位）— **2026-09-08 17:30 完成**
- [x] **P2 前置调研完成**（2026-09-08）：dshs 为多租户首选候选；确认硬前提=域名+通配DNS+通配证书（纯 IP 打不开聊天 UI）；服务器 1.8G 内存限 1-3 人规模；**用户决定：解决域名后再做多用户改造**
- [ ] **域名就绪后选型落地**：dshs（模式 A 单机，优先）或自研 Node 网关（备选）；新用户按 users/<uid> 同构扩展
- [ ] **P1 镜像 v2**：内置公共插件 + `std/agents/skills` 标准技能库（rank400 层）
- [ ] **P1 系统标准技能库内容确认**（MCN 脚本创作技能等随镜像/`std/` 分发）
- [ ] **P3 飞书 OAuth 登录扩展**（预留接口，按需启用）
- [ ] **P3 编导工作区模板**（新用户自动带账号人设/素材库结构）
### 多用户改造前提条件（用户决策记录 2026-09-08）
1. **域名**：无（仅 IP）。海外服务器解析无需备案；买域名后配 `@` A 记录 + `*` 通配 A 记录 → 47.77.182.89，再签通配证书。域名就绪 = 多用户改造解锁。
2. **用户规模**：1-3 人（现 1.8G 内存可撑，dshs 每用户一个常驻 DSH 子进程）。
3. **候选对比结论**：
- dshs：现成密码注册/审核/隔离/网页桌面/每用户加密 key 库；需宿主机 Node ^22.19 + 全局 dsh（spawn 子进程，非 Docker）；数据组织为 `DATA_ROOT/每用户home`，与 users/<uid> 不互通、官方无迁移工具；
- 自研 Node 网关 + Docker 每用户：复用现有 users/<uid> + 镜像，nginx 后加认证/路由层；开发量中等；
- dsh-webui-auth：仅单实例加锁，不做多用户隔离，可作过渡。
---
## 十二、域名接入记录（2026-09-08）
**域名**：`dsh.alotbuy.com`（Cloudflare 代理，海外服务器免备案）
| 项 | 状态 |
|---|---|
| DNS | `dsh.alotbuy.com` → Cloudflare（172.67.194.206 / 104.21.44.42），CF 回源服务器 80 |
| **通配 `*.dsh.alotbuy.com`** | ⚠️ **未配置**——dshs 每用户子域路由的前提，落地前需在 CF 加 `*` A 记录 → 47.77.182.89 |
| HTTPS | Cloudflare 边缘证书（源站无 443，CF SSL 需为 Flexible 模式，实测已通） |
| 源站 nginx | 新建站点 `/www/server/panel/vhost/nginx/dsh.alotbuy.com.conf`（监听 80，反代 127.0.0.1:8900，Host 伪装 + 剥 Origin/Sec-Fetch，含 WebSocket 头） |
| 验证 | token 登录 303→cookie（host-only 绑 dsh.alotbuy.com）→ 首页 200（24KB）→ API `{"ok":true, deepseek-official}` ✅ |
**访问方式**：`https://dsh.alotbuy.com/?token=<token>`（浏览器打开一次即种 cookie，30 天有效）
**踩坑记录**：
- Windows 原生 curl 写 `/tmp/` 路径失败导致 cookie 不落盘 → 必须用 `C:/...` 路径（历史已知坑，本次复现）
- 对根路径发无 cookie 裸 WS Upgrade 返回 502 为 dsh 正常拒绝（IP 站点同样 502），非配置问题
- nginx 新站点需与 47.77.182.89 站同样伪装头（Host 127.0.0.1:8900 + 空 Origin/Sec-Fetch），否则特权 API 403
## 十三、架构切换：容器 → dshs 多租户 + account 硬隔离（2026-09-08 18:30）
**决策**：去掉 Docker 单容器方案，全量迁移到 dshs 进程隔离模式（便于 dsh/插件升级迭代 = 一条 npm 命令）；用户确认"立即全量迁移 main" + "account 账号级硬隔离"。
### 最终架构
```
宿主机：Node v22.23.2 + 全局 dsh 0.1.2-rc.1（/usr/local/bin）
dshs（systemd，127.0.0.1:3080，account 模式）
├── /var/lib/dshs/
│ ├── dshs.db # 用户/审核数据
│ ├── secret.key # 每用户 key 库主密钥
│ └── users/<userId>/
│ ├── home/ # DSH_HOME（profiles/sessions/credentials）— 由原 .dsh 迁入
│ ├── ws/ # 工作区（HOME 指向）— 由原 workspaces 迁入
│ └── patches/
nginx：dsh.alotbuy.com + *.dsh.alotbuy.com → 127.0.0.1:3080（端口动态分配由编排器管理）
```
### 关键文件清单
| 文件 | 作用 |
|------|------|
| `/etc/dshs.env` | BASE_DOMAIN=dsh.alotbuy.com / COOKIE_DOMAIN=.dsh.alotbuy.com / ISOLATION_MODE=account / BASE_UID=100000 / DSH_BIN=/usr/local/bin/dsh |
| `/etc/systemd/system/dshs.service` | 编排服务（ExecStart 带 `--db` 指向 dshs.db） |
| `/etc/systemd/system/dsh-provision.path` + `.service` | 监控新用户目录自动建 OS 账号 |
| `/usr/local/bin/provision-new-users.sh` | 建号脚本（用户名截断 20 字符，规避 Linux 32 字符限制；每次 chown 幂等） |
### 已验证
- admin 登录 API ✅（role=admin）
- account 降权：dsh 可跑（0.1.2-rc.1）、读 /root Permission denied、读自己 home 正常 ✅
- nginx 主域/子域 → 3080 路由 ✅（登录门户 HTML 返回）
- 备份/恢复脚本已切换新数据根（backup.sh 打包 /var/lib/dshs + 配置 + systemd 单元）
### ⚠️ 未完成 / 待办
- [x] **HTTPS 通配证书**（2026-09-08 18:40 完成）：certbot dns-cloudflare 签 `*.dsh.alotbuy.com`，nginx 443 + HTTP 跳转，全链路登录验证通过
- [ ] **每用户 API Key**：dshs 为每用户独立 key 库（登录后桌面"管理密钥"填），原 .env 统一 key 的模型已不适用（迁移后 admin 需自填 key）
- [ ] 注册普通用户 → 审核 → 桌面/DSH 启动全链路验证（子域 404 需注册后确认）
- [ ] main 旧容器数据 /opt/dsh/users/main 已迁入 admin home，容器已停，可清理
- [ ] 飞书 OAuth 扩展（预留）
### 踩坑记录
1. **db 路径不一致**：bootstrap-admin 写入 `dshs.db`，但服务默认用 `dshs.db`（空）→ systemd ExecStart 必须显式 `--db`
2. **用户名超长**：`dsh-`+uuid=41 字符超 Linux 32 限制 → provision 脚本截断为 `dsh-<uuid去横线前20>`
3. **初始属主不一致**：bootstrap 建目录属主 100001，hash uid 为 114801 → 以 `uid-for-user` 输出为准
4. **中间路径权限**：`/var/lib/dshs` 与 `/users` 需 755（root 700 会挡住降权账号穿透），用户目录本身 700 保持隔离
5. **pkill 自杀坑**：`pkill -f 'lib/cli.js'` 会匹配到远程 shell 自身命令行 → 用 systemctl 管理
## 十四、dsh.alotbuy.com 注册为宝塔面板反代站点（2026-09-08 18:46）
**背景**：手写 conf（`/www/server/panel/vhost/nginx/dsh.alotbuy.com.conf`）在面板数据库无站点记录 → 面板重置/批量管理可能误伤。按用户偏好（能走 MCP 尽量走 MCP）用宝塔 MCP 完成注册。
**执行链（MCP 优先，全流程零中断）**：
1. SSH 备份 + 移走手写 conf：`cp` 到 `/opt/dsh/docs/nginx-dsh.alotbuy.com.conf.bak-20260908`，`mv` 出 include 目录（不 reload，服务无感）
2. MCP `ProxyProjectCreate`：domains=`dsh.alotbuy.com`，proxy_pass=`http://127.0.0.1:3080` → 站点 id=2 入面板 DB
3. MCP `ProxyWriteConfig`：把完整精调 conf（HTTP→HTTPS 跳转 ×2 + 443 主域 SSL + 443 通配子域 SSL）覆盖写回同路径
4. SSH `nginx -t` + reload + 本机 curl 验证
**⚠️ 关键坑**：面板反代项目 conf 写入路径与手写 conf 同名同路径（`/www/server/panel/vhost/nginx/<域名>.conf`）——直接 ProxyProjectCreate 会用面板模板覆盖，丢失 SSL/通配子域/301 等精调内容。**必须"先移走手写 conf → 创建 → ProxyWriteConfig 写回精调版"三步走**。
**验证结果**：
| 检查项 | 结果 |
|--------|------|
| SiteList 面板 DB | 2 站点：47.77.182.89（id=1）+ dsh.alotbuy.com（id=2）✅ |
| nginx -t + reload | OK ✅ |
| https://dsh.alotbuy.com（外网直连源站） | 200 ✅ |
| https://*.dsh.alotbuy.com（通配子域，未注册） | 404（dshs 正常拒绝，代理/SSL 层通）✅ |
| http://dsh.alotbuy.com | 301 → https ✅ |
| conf 保留 | 4 段精调 server 块完整（certbot 证书路径原样）✅ |
**遗留说明**：面板站点列表 SSL 状态显示 `enabled:false`——证书为 certbot 手动签发（面板不托管），面板只做站点/conf 管理；如需面板托管 SSL 需换面板 Let's Encrypt 流程（不建议，会与通配证书冲突）。
## 十五、启动 DSH 报"已有运行中"+ 无法对话 排障（2026-09-08 19:00）
**现象**：admin 登录桌面点"启动 DSH"，提示"有运行中的 DSH 请先停止"，无跳转，无法对话。
**根因一（P0，已修复）：DB uid 与系统账号 uid 错配**
- 主 DB（`/var/lib/dshs/dshs.db`，服务 `--db` 显式指向）users.uid=**100001**（bootstrap 写入 `baseUid+rowid`）
- 但 OS 账号按 `hashUid` 建：`dsh-cce6d1cdb376430480f0` uid=**114801**（早期版本 provision 用 hash；后 provision 改为读 DB uid-for-user，但账号没重建）
- 结果：编排器 spawn 用 DB uid=100001 → `setpriv --reuid 100001` → 子进程以**不存在的 uid** 运行 → 打不开 `700 owner=114801` 的用户 home → `EACCES: mkdir .../home/profiles/web` 秒崩
- 编排器 `spawn` 事件即置 status=running，子进程崩后自动重启循环 → 前端一直显示"运行中"→ 再次点击启动返回 409 already_running（即用户看到的提示）
- **修复**：`UPDATE users SET uid=114801 WHERE id='cce6d1cd-...'`（备份在 `/opt/dsh/docs/dshs.db.bak-20260908-uidfix`）+ `systemctl restart dshs` + provision 脚本 `uid-for-user` 补 `--db /var/lib/dshs/dshs.db`（消除默认库分裂）
**根因二（上游集成缺口，未修复）：dsh web 强制浏览器 token，编排器"打开"不带 token**
- dsh web（0.1.2-rc.1，`dsh-client-connection` BrowserAuth）强制：首次访问需 `?token=<launch token>`（进程启动随机、打印到 stdout）换取签名 cookie（绑定 authority=`127.0.0.1:<port>`，30 天）
- 上游 dshs 0.1.0：launch 返回 url **不带 token**，desktop.html "打开 DSH" 直接 `window.open(url)` → 首访 401 `dsh web authentication required`；且端口动态分配，实例重启换端口 → 旧 cookie 失效需重新带 token
- 已实测全链路可行：门户 sid + `?token=` → 303 种 dsh-auth cookie → 双 cookie 访问 `https://admin.dsh.alotbuy.com/` 200（24233B SPA）+ `/api/llm/listProviders` ok:true
- **修复方向（待用户定）**：A. 小改上游——编排器解析子进程 stdout 的 token，launch/status url 自动拼 `?token=`（改 src/supervisor/orchestrator.ts + routes/dsh.ts，tsc 可构建）；B. 接受现状——每次启动后手动用 journald 里 token 开一次；C. 等上游修复
**排障经验**：`launch folder` 是相对 **ws/** 根的路径（空串=根）；`/api/dsh/status` 返回 url 为子域；子域下所有路径（含 /api/dsh/status）都会被代理到实例，故探测实例要用 `/api/llm/*` 等实例 API；cookie 域 `.dsh.alotbuy.com`（sid）与 dsh-auth 双 cookie 缺一不可。
## 十六、方案 A 落地：launch/status 自动携带 dsh launch token（2026-09-08 19:30）
**决策**：用户选方案 A（小改上游，普通用户无需手动拿 token 即可打开聊天界面）。
**改动（3 文件，已 git commit 29c8907，本地分叉 patch）**：
| 文件 | 改动 |
|------|------|
| `src/supervisor/spawner.ts` | `Instance` 接口加 `launchToken?: string` 字段 |
| `src/supervisor/orchestrator.ts` | ① `trackChild` 监听子进程 stdout，正则 `dsh web: http://127.0.0.1:\d+/\?token=([A-Za-z0-9_-]+)` 解析 token 存入 instance；② 新增 `waitForLaunchToken()`（轮询最多 20s 等 token 出现，崩溃/停止即返回）；③ `launch()`/`restartMain()` 返回前等待 token |
| `src/web/routes/dsh.ts` | `dshUrl()` 支持可选 token 参数；launch/restart/status 返回的 `url` 均拼接 `?token=`（status 从 `main.launchToken` 取） |
**验证结果（全链路）**：
| 步骤 | 结果 |
|------|------|
| launch 返回 | `{launchToken, url: https://admin.dsh.alotbuy.com/?token=...}` ✅ |
| 打开带 token url（带 sid，-L 跟随） | 200，24233B SPA，自动 303 种 dsh-auth cookie ✅ |
| 之后裸开 `/` | 200 ✅ |
| `/api/llm/listProviders` | `ok:true, deepseek-official` ✅ |
**构建/部署**：`npm run build`（tsc）+ `systemctl restart dshs`。TS 坑：`RegExp.exec` 返回 `null` 非 `undefined`，判空须 `m !== null && m[1] !== undefined`。
**admin API Key 已配置**：从旧 `/opt/dsh/.env` 取出 `sk-81c...` 经 `/api/me/keys` 注入（name=deepseek-main，AES-GCM 加密入库，自动触发实例重启生效）。**KEY 为每用户独立**——每个用户需在桌面"管理密钥"各自添加；无全局通用 key（原容器 .env 统一 key 模型已废弃）。
## 十七、权限边界实测 + DB 权限安全加固（2026-09-08）
**问题**：admin 登录后能否访问服务器所有目录？AI 对话窗口新建工作空间时能否输入系统根目录？
**两层防护模型（答案分两层）**：
| 层 | 机制 | 结论 |
|----|------|------|
| Web 桌面层 | fs-guard `resolveWithinRoot()`：所有文件浏览/上传/新建工作空间的路径解析被锁在用户自身 home/ws 内，拒绝 `../`、绝对路径、符号链接逃逸 | 输入 `/`、`/root` 等系统路径会被拉回/拒绝；admin 与普通用户同样受限，**不存在"admin 浏览全服务器"入口** |
| AI 进程层 | 每用户 DSH 实例以**降权 uid**（setpriv）运行，该进程可执行 shell/agent 工具，**不受 fs-guard 约束**，能读该 uid 有权限的一切文件 | admin 的实例同样是降权 uid，非 root。实测 uid 114801 边界：`/root`、`/etc/shadow`、`/opt/dsh/.env`、secret.key、dsh db 全部 Permission denied ✅；`/etc/passwd`、`/tmp` 世界可读可写 ✅ |
**结论**：即便 admin 也无法从 AI 对话触达 root-only 敏感文件；真正的服务器管理走 SSH/宝塔 root 通道，与 AI 会话隔离。这是 account 隔离模式的核心价值，无需额外改造。
**⚠️ 实测发现并修复的漏洞：DB 权限 644 → 600**
| 项 | 详情 |
|----|------|
| 漏洞 | `/var/lib/dshs/dshs.db` 权限 644 root——任意降权账号可 `cat` 拖库 |
| 风险 | 库内含全部用户 `pass_hash`(scrypt)+ `api_key_ref`(AES-GCM 密文)+ uid/sid → 离线爆破口令 + 窃取 key 密文 |
| 修复 | `chmod 600 /var/lib/dshs/dshs.db* /var/lib/dshs/dshs.db*` |
| 验证 | 降权账号读 db → Permission denied ✅；服务 600 下正常（portal 401 为未认证正常响应）✅ |
**目录级权限收紧（用户反馈"其他用户也能看就不行"，2026-09-08 20:30）**：
普通用户实例同样是降权 uid，盘点发现除主 db 外还有更大泄露面：`/opt/dshs` 整棵树 755、`/opt/dsh/docs/` 内**主库备份**（含全部 pass_hash+key 密文）、`/opt/dsh/backups/` 备份包、`/opt/dsh/users/main` 旧数据残留均 644/755 可读 → AI 会话可拖取。收紧如下：
| 路径 | 改前 | 改后 | 说明 |
|------|------|------|------|
| `/opt/dsh` | 755 | **700** | 覆盖 docs（含 db 备份）、backups、users/main 残留 |
| `/opt/dshs` | 755 | **700** | root 服务运行不受影响（systemd 无 User= 默认 root） |
| `/var/lib/dshs` | 755 | **711** | 保留 o+x：降权进程需穿过根路径进入自己 home，去读防列表泄露 |
| `.../users` | 755 | **711** | 同上；用户目录本身 700 保持隔离 |
**验证（uid 114801 实测）**：读 `/opt/dsh/docs/*.md` → denied ✅；列 `/opt/dshs`、数据根 → denied ✅；**仍可进入自己 `ws/mcnworkspace` ✅**；systemd active、portal 200、admin 实例 `/plugins/events` 正常 ✅。
**⚠️ 经验固化（Linux 目录权限设计）**：数据根这类"root 服务 + 降权子进程都要访问"的目录，权限用 **711/700**（去 r 留 x），不能收 700——降权进程会因无法穿过根路径而崩溃（EACCES）。子目录各自 700 才是真正的隔离边界。
## 十八、统一 KEY：管理员统一设置，用户只能使用管理员 KEY 和模型（2026-09-08 20:40）
**决策**（用户确认）：① KEY 存放 = 复用 admin 密钥库（桌面/API 自助换 key 即全局生效）；② 用户 dsh 界面自配暴露面先实测再定，本次不做 dsh patch。
**改动（commit df5cc84，6 文件 +49/-14）**：
| 文件 | 改动 |
|------|------|
| `src/web/server.ts` | `resolveApiKey` 忽略入参 userId，改为 `listPublicUsers().filter(role==='admin')` 取 admin 的启用 key——**所有用户 spawn 注入同一把管理员 key** |
| `src/supervisor/spawner.ts` | Spawner 接口新增 `restartAllMains()` |
| `src/supervisor/orchestrator.ts` | LocalSpawner 实现：遍历内存 `mains` 逐个 `restartMain`（单个失败 console.error 不中断广播） |
| `src/supervisor/k8s-spawner.ts` | K8sSpawner 实现：遍历 `db.listInstancesByRole('main')` 逐个重启 |
| `src/web/routes/auth.ts` | `/api/me/keys` GET/POST/select/delete 由 `requireAuth` 改 **`requireAdmin`**（普通用户 403）；POST/select 后 `restartAllMains()` 广播（key 是 spawn 时注入 env 的快照，不重启运行实例不刷新） |
| `web/desktop.html` | 非 admin 隐藏"管理密钥"按钮；面板文案改"全局 API 密钥（所有用户共用，仅管理员可改）" |
**验证（全链路实测）**：
- admin GET `/api/me/keys` → 200，deepseek-main 在列 ✅
- 注册 testuser（pending）→ admin approve（active）→ 登录 ✅
- 普通用户 GET/POST `/api/me/keys` → **403 forbidden** ✅
- **testuser launch DSH → 打开 200 SPA → `llm/listProviders` ok:true deepseek-official** ——证明普通用户无自配 key 也拿到 admin 全局 key ✅
**遗留**：用户 dsh 界面内自配 key/模型的能力面未实测（proxy 伪装 loopback 可能放行 dsh Settings）——第二道防线待 P1 实测后再定。testuser 账号保留作普通用户全链路验证种子。
## 十九、界面删除用户功能（2026-09-09 07:00）
**需求**：管理界面在禁用/恢复右侧加删除按钮 → 弹窗输入该用户名相同名称确认 → 删除（admin 不可删）。
**改动（commit 4943c8c，7 文件 +106/-2）**：
| 层 | 文件 | 改动 |
|----|------|------|
| 后端路由 | `src/web/routes/admin.ts` | 新增 `DELETE /api/admin/users/:id`：admin → 409；`supervisor.stop` → `db.deleteUser`（事务）→ `rm users/<id>/` 目录 → `userdel dsh-<id去横线20位>`（OS 账号，失败容忍）→ audit |
| DB 接口 | `src/db/adapter.ts` | +`deleteUser(userId)` |
| SQLite | `src/db/schema→repo.ts` + `sqlite.ts` | 事务按序清 credential_vault/domains/sessions/dsh_instances/audit_log/folder_plugins/workspaces/users（显式删除，不依赖 FK cascade 开关） |
| Postgres | `src/db/pg.ts` | 同序 `withTx` 实现 |
| 前端 | `web/admin.html` + `web/desktop.html` | 非 admin 行尾加 🗑 按钮（红色 ghost）；点击 `prompt` 输入用户名比对确认后 `DELETE`；admin 行不渲染按钮 |
**验证（全部实测）**：① 删 admin 自己 → 409 `cannot_delete_admin` ✅ ② 删 testuser → 200 ✅ ③ 删不存在 → 404 ✅ ④ 残留检查：users/credential_vault/sessions/workspaces/dsh_instances/domains/audit_log 7 表全 0、`users/<id>/` 目录不存在、OS 账号 `dsh-2d1f22ffcde04874ba1d` 已删、用户列表仅剩 admin ✅
**注意**：`userdel` 账号名与 provision-new-users.sh 同规则（`dsh-` + uuid 去横线前 20 位）；OS 账号删除失败只容忍不报错（DB/目录已清，残留仅 uid 占用）。testuser 已作为功能测试对象删除。
## 附录 A：常用命令速查
```bash
# 备份 / 恢复
/opt/dsh/backup.sh
/opt/dsh/restore.sh /opt/dsh/backups/dsh-backup-<时间戳>.tar.gz
# 容器日志（看 token / 排障）
docker logs --tail 50 dsh-web
# 进入容器
docker exec -it dsh-web bash
# 插件管理（profile web）
dsh plugin --profile web add <npm包名|github:owner/repo|link:/path>
dsh plugin --profile web remove <包名>
dsh --profile web --dump-config # 打印生效插件树
# 模型 API 直测（服务器本机）
curl -s -X POST http://127.0.0.1:8900/api/llm/listProviders \
-H 'Content-Type: application/json' \
-d '{"type":"client-request","rpcId":"v1","method":"llm/listProviders","payload":{"args":{}}}'
```
## 附录 B：参考链接
- npm：https://www.npmjs.com/package/@deepseek-ai/dsh（0.1.2-rc.1）
- 官方仓库：https://github.com/deepseek-ai/deepseek-harness
- CLI 行为参考：apps/cli/reference/README.md（分层优先级/部署默认）
- dsh skills 安装与优先级：`~/.dsh/skills`、`~/.agents/skills`、项目级 `/.dsh/skills`（社区文档，见当日讨论记录）
- 社区多租户方案调研（dshs / dsh-remote / dsh-passwords / dsh-im）：见当日讨论记录
归档/dsh-server-docs-清理-20260924/工作区草案/VoxEMW全云API化接入dsh修订方案_20260909.md
+222
View File
@@ -0,0 +1,222 @@
# VoxEMW 全云 API 化：接入 dsh 修订方案（零自托管模型）
- **日期**：2026-09-09（22:50 版）
- **性质**：对《VoxEMW接入dsh调研与落地方案_20260909.md》的**方向性修订**——用户决策：**模型全部连线上 API，不部署任何本地模型**
- **一句话**：不再"代理运行 VoxEMW 那套 GPU 服务"，而是**以 VoxEMW 为产品与体验蓝本，复用其 persona 文案与 `assets/mojingnvwu/face_ref.jpg` 形象资产，后端全部换成 2026 年已商业化的云端实时 API**，由 dsh 插件做编排/代理/隔离。
> ⚠️ **重要更正**：前一版文档 §4 判断"实时写实数字人渲染没有等价公开 API"——该判断已被 2026-09 市场现状推翻：火山引擎「实时互动数字人 API(FlowAct-R1)」、阿里云「数字人实时交互 OpenAPI」、ZEGO「精品照片数字人」均已提供"图片/形象 + 音频流 → 实时视频流"的商业 API。全云 API 路线**可行**，本文即按此重写。
---
## 一、决策影响对照（原方案 → 修订方案）
| 维度 | 原方案（代理 VoxEMW GPU 服务） | 修订方案（全云 API） |
|---|---|---|
| 模型部署 | 4090 主机四模型本地常驻（21.7G/24G） | **零本地模型**，全部云端 API |
| GPU 主机/隧道 | 需要 | **移除**，不需要任何自管 GPU |
| VoxEMW 代码 | 运行上游 python 全套 | **不运行**，仅作蓝本（UI 氛围/协议形态/人设） |
| 核心工作 | 守护 + 反向代理 + 槽位 | **云端编排层**（Realtime WS 对接 + 数字人流对接 + 人设注入） |
| 用户数据隔离 | 槽位 + persona 映射 + 零持久化 | 槽位/配额 + profile 维度记账 + 云端 session 独立 + 第三方合规提示 |
| 需要决策的新增项 | — | 供应商组合、数字人形象图、音色路线（见 §七） |
---
## 二、2026-09 云端供给盘点（VoxEMW 六积木逐块替换）
### 2.1 替换矩阵
| VoxEMW 积木 | 等价云 API（已核实存在） | 关键参数/证据 |
|---|---|---|
| ① VAD + ② STT | 并入"端到端 Realtime 模型"（自带 server VAD + 自动打断），或单独接讯飞/火山/阿里实时 ASR | 端到端更省事，见 2.2 |
| ③ LLM 大脑 | 端到端模型自带大脑；或保留 DeepSeek API（分离式时） | 魔镜人设走 `instructions`（session.update），与 VoxEMW 注入 persona 同思路 |
| ④ TTS 音色 | 端到端预置音色（列表切换）；要"专属音色/克隆"则分离式接 MiniMax / 阿里 CosyVoice / 火山豆包 | 见 §六体验差异（音色设计能力是最大降级点） |
| ⑤ **写实数字人** | **火山「实时互动数字人 API (FlowAct-R1)」**：单张人物图 + 16kHz PCM 音频流 → 实时视频流，480P@25fps，首帧 ~2s，声画毫秒同步（[docs.volcengine.com](https://docs.volcengine.com/docs/86081/2387261)）<br>或 **阿里云数字人实时交互 OpenAPI**：WebSocket + streamed audio driver，支持 `customUserId`（天然适合租户标记）（[help.aliyun.com](https://help.aliyun.com/en/me/getting-started/digital-human-real-time-interactive-openapi)）<br>或 **ZEGO 精品照片数字人**：1 张照片 200ms、1080P，走 RTC 视频互动（[doc-zh.zego.im](https://doc-zh.zego.im/aiagent-mini-program/introduction/overview)） | 单图输入 → **`assets/mojingnvwu/face_ref.jpg` 可直接复用** |
| ⑥ 眼睛 VLM | **GLM-Realtime**（音视频通话模型，WebSocket，支持摄像头帧输入、function calling、server VAD、可打断）<br>或 **阿里 Qwen-Omni-Realtime / qwen3.5-omni-plus-realtime**（DashScope，WS 与 WebRTC 双通道，视频帧输入） | 摄像头帧走同一条 Realtime WS，天然实现"她看得见你" |
### 2.2 端到端 Realtime vs 分离式（架构大方向二选一）
| | 端到端 Realtime（**推荐**） | 分离式（ASR + LLM + TTS 各选一家） |
|---|---|---|
| 做法 | 一个 WebSocket 完成"听→想→说"，服务端 VAD/打断全托管 | 每环节独立 API，自行拼装状态机 |
| 延迟/体验 | 低（0.3~0.5s 级开口），打断顺滑 | 每跳多一次网络，拼装复杂、易抖 |
| 音色自由度 | 预置音色列表（GLM-Realtime 提供 tongtong/xiaochen/female-tianmei…） | 可用 MiniMax/CosyVoice 克隆"魔镜专属嗓音" |
| 视觉（眼睛） | GLM-Realtime / Qwen-Omni 直接吃视频帧 | 需另接 VLM API |
| 计费参考 | GLM-Realtime-Flash：音频 0.18 元/分，视频 1.2 元/分；Air：0.3 / 2.1 元/分（[docs.bigmodel.cn](https://docs.bigmodel.cn/cn/guide/models/sound-and-video/glm-realtime)） | 各家按量，总价通常更高 |
**推荐组合**（两个候选，M1 前拍板）：
- **组合甲（默认推荐）**：端到端大脑+声音 = **智谱 GLM-Realtime**；出画 = **火山 FlowAct-R1**（单图+音频流）。理由：中文生态、GLM-Realtime 带视频+function calling、成本低、火山数字人与豆包端到端语音同族可平滑替换。
- **组合乙（同厂商偏好）**：端到端 = **阿里 Qwen-Omni-Realtime**（视频帧原生）；出画 = **阿里实时数字人 OpenAPI**（带 `customUserId`，租户标记友好）。理由：一家计费/控制台，WebRTC 浏览器直连低延迟。
---
## 三、目标架构（修订后）
```
┌──────────── 用户浏览器（dsh 会话窗口右侧分栏面板，同源 https）───────────┐
│ 魔镜面板（轻量前端，蓝本=VoxEMW web/ 的氛围，但重写为云版） │
│ ├─ 麦克风采集 16kHz PCM → host 代理 → 云 Realtime WS │
│ ├─ 摄像头帧（可选"眼睛"）→ host 代理 → 同一 Realtime WS │
│ └─ 云数字人视频流 → <video> 播放（火山 FlowAct-R1 / 阿里） │
└──────────────────────┬──────────────────────────────────────────────────┘
│ 同源（ws/wss + http），Authorization 由服务端注入
┌──────────────────────▼── dsh 服务器（47.77.182.89 / dsh 域）────────────┐
│ dsh-plugin-voxemw-cloud │
│ ├─ lib/host.js：/voxemw/api/* + /voxemw/ws/* 反向代理到云厂商 │
│ │ · 云 API Key 保管于此，**绝不下发浏览器** │
│ │ · 注入 dsh 登录态 → 按 profile 换取一次性云端会话 token │
│ ├─ lib/slot.js：会话槽位仲裁 + 配额（按 profile 限每日用量） │
│ ├─ lib/billing.js：profile × 分钟数 × 费用的用量记账（审计） │
│ └─ lib/client.js：会话分栏 + 魔镜面板 UI（沿用 mcn split 技术） │
└─────────────────────────────────────────────────────────────────────────┘
│ HTTPS/WSS（云厂商公网 API）
▼
智谱 GLM-Realtime / 阿里 Omni-Realtime（大脑+耳朵+嗓子+眼睛）
火山 FlowAct-R1 / 阿里实时数字人（出画，输入 face_ref.jpg 形象）
```
要点：
1. **云 API Key 全部收口在 dsh 服务端**，浏览器永远只连 dsh 同源地址 → 无 CORS、无密钥泄露、天然 secure context。
2. 数字人形象输入 = 复用 VoxEMW 仓库 `assets/mojingnvwu/face_ref.jpg`（280K 单张正面像，符合 FlowAct-R1"清晰正面半身图"要求）。
3. 魔镜人设 = 复用 `personas/mojingnvwu.md` 正文，经 `session.update.instructions` 注入（与 VoxEMW 注入 s2s 同一思路）；音色从云端预置列表近似选（见 §六）。
4. VoxEMW 上游 python **不再被运行**；前端也需**重写轻量云版**（原 `web/` 深度耦合 orchestrator 协议/本地假设，不能直接指向云）。
---
## 四、dsh 插件形态（包结构修订）
> **命名统一（2026-09-09 实现时裁定）**：插件名定为 **`dsh-plugin-voxemw-cloud`**（v0.1.0），替代早期方案的 `dsh-plugin-voxemw` 提法，旧称不再使用。
> **M1 交付边界**：客户端 bundle 只能在运行中的 dsh 实例加载验证（红线：client 改动必须重启实例 + 打包缓存），本机开发仅做语法/逻辑冒烟测试；实例级验证步骤见 README。云端厂商链路需账号开通后接线，realtime/avatar 先以"协议适配层 + 纯函数"落地（可测），UI 侧仿 social-workbench 提供"未配置云端"引导态。
```
dsh-plugin-voxemw-cloud/
├─ package.json / cordis.patch.yml # 三段式骨架，注册 __mcnEntries，feature-tier
├─ lib/
│ ├─ index.js # 路由注册：控制面 /voxemw/api/* + 面板页 /voxemw/app + /voxemw/health
│ ├─ slot.js # 槽位 + 配额（云会话按分钟计费 → 必配每日上限）
│ ├─ billing.js # profile 维度用量/费用记账（审计表）
│ ├─ cloudcfg.js # 厂商/Key/模型/音色/形象 配置（服务端保管，密钥不下发）
│ ├─ realtime.js # Realtime 协议适配层：session.update(人设/音色) 构建等纯函数
│ ├─ avatar.js # 数字人协议适配层：会话初始化请求构建等纯函数
│ └─ client.js # bundle：工作台入口 + 面板（沿用 mcn 分栏宿主，iframe 同源）
├─ web/app.html # 魔镜面板轻量前端（单文件，同源加载，含麦克风回环自测）
└─ README.md
```
---
## 五、用户数据隔离（修订）
| 数据 | 存放/流向 | 隔离措施 |
|---|---|---|
| 用户语音/摄像头帧 | 浏览器 → dsh 代理 → **云厂商** | 每次会话新建独立云端 session；代理不留音频副本（纯透传）；关闭面板即销毁 |
| 对话/转写 | 云端会话内存（GLM 音频通话上下文 ~8K/20 轮） | 会话结束即释放；需留存时按 profile 落用户目录，绝不跨用户复用 |
| 人设/热词 | dsh 服务端按 profile 存映射 | 注入仅限本人会话 |
| 计费/用量 | billing 表（profile 维度） | 每用户只见自己的记账 |
| 云 API Key | dsh 服务端环境变量 | 浏览器不可见；轮换/最小权限（RAM/子账号 key） |
**新增合规注意（P1）**：语音/画面会经第三方云厂商处理——产品上需对用户明示；自用/内网不受影响。厂商选型时优先国内合规厂商（智谱/阿里/火山均支持企业实名）。
**沿用上一版 §6.2 的槽位层**：端到端模型与数字人流都按会话/分钟计费且厂商有并发限制（如 GLM Realtime 免费/低等级并发 5 路），slot 互斥 + 每日配额仍然是刚需。
---
## 六、体验差异（诚实对照，避免上线后落差）
| 体验点 | 原版（本地 4090） | 云 API 版 | 影响 |
|---|---|---|---|
| 开口延迟 | 说完 ~3s（本地 s2s 链路） | 端到端云 Realtime 通常相当或更低（server VAD 判停即响应） | ✅ 不降级 |
| 出画首帧 | SoulX 常活待机，几乎即时 | 火山 FlowAct-R1 首帧 ~2s；ZEGO 200ms 但走 RTC | ⚠️ 需预热/占位动画掩盖，或选 ZEGO |
| 音色"设计感" | VoxCPM2 描述词凭空造嗓 + 种子钉定 | 端到端只有预置音色；专属嗓音需分离式克隆（需参考音频） | ⚠️ **最大降级点**，见决策 3 |
| 魔镜形象 | SoulX 写实渲染 | 云端数字人（face_ref.jpg 驱动或平台形象） | 观感不同但可接受 |
| 长会话稳定性 | 本地单时钟唇形同步 | 厂商提示"过长视频有崩坏概率，建议会话长度策略"（火山） | 需设单会话时长上限并自动续段 |
| 运营成本 | GPU 租用（AutoDL 时按小时） | 按分钟计费（参考：音频 0.18~0.3 元/分 + 视频 1.2~2.1 元/分，纯语音组合更省） | 低频个人使用成本低；高频需配额 |
---
## 七、需要你拍板的 3 个决策（M1 前置）
1. **供应商组合**：组合甲（智谱 GLM-Realtime + 火山 FlowAct-R1，默认推荐）还是组合乙（全阿里）？还是只要纯语音（先不做出画，最省事）？
2. **数字人形象**：直接用 VoxEMW 自带 `assets/mojingnvwu/face_ref.jpg`，还是换一张更符合"魔镜女巫"设定的形象图（含版权确认）？
3. **音色路线**：先用云端预置女声（接近即可，最快）→ 之后若需"魔镜专属嗓音"再接分离式 TTS 克隆（需你提供一段 3~10s 参考音频，或用描述词在支持语音设计的 TTS 上逼近原 seed 效果）？
---
## 八、实施路线（修订）
**M1 — 云端链路跑通 + 面板可见（半天~1 天）**
1. 注册厂商账号、开通 API（按决策 1）；服务端保管 key。
2. 独立验证页：麦克风 → Realtime WS 对话成功；音频流喂数字人 API → 视频出画。
3. 接入 dsh：host 代理 + 会话分栏面板内嵌云版前端。
- ✅ 验收：dsh 会话旁打开魔镜，可语音对话 + 数字人出画；关闭面板会话无损。
**M2 — 隔离/配额/记账/人设**
4. slot + 每日配额；profile 维度 billing；人设注入；face_ref.jpg 形象固化；占用/排队 UI。
- ✅ 验收：双账号并发互斥、各自人设/记账不可见；用量超限自动拒 claim。
**M3 — 体验与合规**
5. 音色定制（决策 3 后半）；长会话自动续段/上限；窄栏 UI 打磨；日志分级；第三方数据处理提示。
---
## 九、访问形态、服务器负载与并发容量（2026-09-09 增补，回应"是否还是插件/压力多大/支持多少人"）
### 9.1 它仍是 dsh 插件，访问入口不变
全云 API 化**没有改变"插件"形态**——改变的是插件内部"不装模型、只做编排/代理"。访问链路分两个角色：
| 角色 | 是什么 | 访问方式 |
|---|---|---|
| **使用方（dsh 用户）** | 登录 dsh 后，在会话窗口分栏点「魔镜女巫」入口 | 插件 client bundle 注入 `__mcnEntries`，点击展开右侧面板 → 浏览器采集音视频、渲染数字人，全程**不感知云厂商存在** |
| **dsh 平台自身** | dsh 服务端运行 `dsh-plugin-voxemw-cloud`（host 半区） | 持有各家云凭证；控制面调用厂商 API 换取会话；把短时效凭证交给浏览器；按 profile 做槽位/配额/记账；也可向 dsh agent 暴露 MCP 工具（"启动/切换人设/查占用"） |
> 所以"dsh 如何访问"的答案 = **浏览器访问 dsh 同源入口，dsh 插件进程访问云厂商**，中间没有其他系统。
### 9.2 两条数据面架构（决定服务器压力，M1 前必须拍板）
| | 路径 | 服务器压力 | 适用 |
|---|---|---|---|
| **A. 媒体面直连（推荐）** | 浏览器 ↔ 云厂商 RTC/WS 直连音视频；dsh 服务器只做**控制面**（登录态校验 → 向厂商换短时效会话凭证 → 下发浏览器 → 记账） | **极小**：每个活跃会话仅几十 KB/s 级信令/文本，无媒体转发 | 云厂商支持浏览器直连 + 临时凭证。已核实线索：Qwen-Omni-Realtime 明确支持 WebRTC 浏览器低延迟；ZEGO/火山走 RTC 房间模型天然直连；GLM-Realtime 为 WS+API Key，直连会暴露 key，需厂商临时凭证或走 B |
| **B. 服务端中转（WS 全代理）** | 浏览器 → dsh 插件代理 → 云厂商 | 媒体全部过服务器：**带宽=瓶颈**（见 9.3 量化） | 厂商只有 WS+长期 Key（如 GLM-Realtime 默认）；或无浏览器 SDK |
**建议**：M1 验证时逐厂商问清"浏览器直连 + 临时凭证（ephemeral token/RTC room 凭证）"支持度，优先 A；A 不可用的环节退回 B 并控制并发。
### 9.3 服务器负载量化（估算，供规划）
单会话媒体流量（最坏=厂商给原始 PCM，若走 RTC/Opus 会小 4~8 倍）：
| 流 | 方向 | 码率估算 | 说明 |
|---|---|---|---|
| 上行语音 | 用户→云 | 16kHz PCM16 ≈ **256 kbps**（Opus 则 ~24–32 kbps） | 说话时才满速 |
| 下行语音 | 云→用户 | GLM 输出 pcm24 ≈ **384 kbps** | — |
| 数字人视频 | 云→用户 | 480P@25fps 估 **0.8–1.5 Mbps**（厂商未公开，按同类流媒体估） | 仅出画档 |
- **架构 A（直连）**：以上流量全部不经 dsh 服务器 → **dsh 服务器负载≈0**，只剩登录校验/凭证下发/账单（每会话可忽略）。dsh 服务器**不是瓶颈**。
- **架构 B（中转）**：每路活跃全功能会话 ≈ 上行 256k + 下行 1.7M ≈ **~2 Mbps**（不出画纯语音约 0.6 Mbps）。按带宽估并发：10 Mbps 出口 ≈ 5 路全功能（或 ~16 路纯语音）；1 Gbps ≈ 500+ 路（理论，另受云配额/CPU 转发限制）。**即：若要中转且大规模，带宽决定上限。**
### 9.4 支持多少人同时访问（分层容量模型）
"同时访问"要拆成三层，瓶颈各不相同：
| 层 | 含义 | 瓶颈 | 规模预估（推荐架构 A） |
|---|---|---|---|
| ① 同时在线 | 登录 dsh、面板能打开（不对话） | dsh 服务器 + 云账号配额外的静态资源 | 数百~上千不成问题，服务器压力≈0 |
| ② 同时语音对话 | 占用一条云端 Realtime 会话 | **云厂商并发配额**（例：GLM-Realtime 低等级在途并发 5 路起，可付费升级）| 通常买 5~50 路；受成本约束 |
| ③ 同时数字人出画 | 占用一路云数字人渲染 | 云数字人按路/分钟计费的并发上限 | 单账号通常个位数~十路级，需与厂商确认 |
**结论**：
- 瓶颈**不在 dsh 服务器**（只要走媒体面直连 A）；瓶颈在**云厂商并发配额**和**按分钟费用**。
- 推荐按"**槽位数 = 你买的云端路数**"来卖/分配：例如买 5 路 → 同时最多 5 人占用魔镜，第 6 人排队（slot + 配额机制正是为此设计）。这也是为什么 §四 slot/billing 是刚需。
- 若坚持服务端全中转（B），则按 9.3 公式用你 dsh 服务器实际出口带宽反推上限。
> ⚠️ 各厂商具体并发配额/直连凭证机制随套餐变化，**M1 开通账号后实测**（一次开 N 路压测），本表为规划级估算。
---
## 附录：信息来源
- 火山引擎「实时互动数字人 API (FlowAct-R1)」：https://docs.volcengine.com/docs/86081/2387261
- 阿里云「数字人实时交互 OpenAPI」：https://help.aliyun.com/en/me/getting-started/digital-human-real-time-interactive-openapi
- ZEGO「实时互动 AI Agent 2.0 / 精品照片数字人」：https://doc-zh.zego.im/aiagent-mini-program/introduction/overview
- 智谱「GLM-Realtime」：https://docs.bigmodel.cn/cn/guide/models/sound-and-video/glm-realtime
- 阿里「Qwen-Omni-Realtime / qwen3.5-omni」：https://help.aliyun.com/en/model-studio/realtime
- VoxEMW 复用资产：`D:\tmp\voxemw\voxemw-src\assets\mojingnvwu\face_ref.jpg`、`personas/mojingnvwu.md`（MIT 许可，复用保留版权声明）
归档/dsh-server-docs-清理-20260924/工作区草案/VoxEMW接入dsh调研与落地方案_20260909.md
+353
View File
@@ -0,0 +1,353 @@
# VoxEMW 接入 dsh：全面调研与落地方案
> ⚠️ **2026-09-09 22:50 方向修订**：用户已决策「模型全部连线上 API、不部署本地模型」。本版（代理 VoxEMW GPU 原套）**已被《VoxEMW全云API化接入dsh修订方案_20260909.md》取代**为本方案主路径；本文件保留作"本地/云端 GPU 跑 VoxEMW 原套"的备选存档。VoxEMW 上游架构事实（§二）与 plugin_package 分栏技术（§三）在两版间通用。
- **日期**：2026-09-09
- **调研对象**：github.com/emwstudio/VoxEMW（git tag v1.10.0，源码已本地快照 `D:\tmp\voxemw\voxemw-src\`）
- **参考实现**：`D:\dshworkspace\plugin_package\`（dsh-plugin-mcn / dsh-plugin-social-workbench / dsh-plugin-douyin-accounts）
- **目标**：① 能否以插件形式加入 dsh；② 使用时在「会话窗口旁边」显示；③ 用户相关数据隔离
- **结论**：**可行，但不是把 VoxEMW 代码"搬进"插件，而是做一个 dsh 侧 host/feature 插件去"守护 + 同源代理 + 内嵌"VoxEMW 这个独立的数字人服务**，会话区采用 dsh-plugin-mcn 已验证的「会话窗口 split + 拖拽分栏」渲染。隔离通过「单槽互斥会话 + profile 维度的 persona/状态映射 + 零持久化语音策略」实现。
---
## 一、结论速览（TL;DR）
| # | 问题 | 结论 | 关键依据 |
|---|---|---|---|
| 1 | VoxEMW 是什么 | 一套**单机 4090 满血写实数字人**（魔镜女巫）：浏览器语音对讲 + 数字人视频 + VLM 视觉，LLM 大脑走 DeepSeek API | README / `docs/plan-4090.md`，四模型同卡 21.7G/24G |
| 2 | 能否"以插件形式加入 dsh" | ✅ 可以，但**插件不含 VoxEMW 本体**。VoxEMW 是 GPU 重型、多进程、带独立 Python 虚拟环境的服务，只能作为**被插件管理的独立服务**存在 | 服务形态：orchestrator(:8000)+s2s(:8765)+SoulX(:8791)+VLM(:18099) |
| 3 | 形态参照 | = **dsh-plugin-social-workbench 的"守护+内嵌 iframe"** + **dsh-plugin-mcn 的"会话分栏"** 二者叠加 | plugin_package 已实证两套技术 |
| 4 | 会话窗口旁边显示 | ✅ 采用 mcn 已验证方案：把 `[data-slot='conversation']` 包进 flex 容器，点入口后在会话右侧展开面板（可拖 5px resizer），VoxEMW 前端以 iframe 同源加载 | mcn `client.js` 的 `.mcnNav_split` CSS 与 `startResize` |
| 5 | 用户数据隔离 | ✅ 分三层实现：**槽位互斥**（orchestrator 只支持单会话，二次连接会顶掉前者——必须加 claim 管理器）+ **profile 维度映射**（persona/配置按用户隔离，VoxEMW 本身无多租户）+ **零持久化**（VoxEMW 会话状态全在内存，天然无跨用户残留） | orchestrator.py `current_session` 顶替逻辑；Session 类无磁盘状态 |
| 6 | 主要风险 | GPU 前置（需一张 4090 或等效）；**多用户并发被物理限制为 1 路**；VoxEMW 前端需要 secure context（https/wss）才给麦克风/摄像头权限；无鉴权需由 dsh 侧补 | 见 §6 风险清单（P1/P2） |
| 7 | 总体投入 | M1 服务接入 + 内嵌可见（核心）+ M2 槽位/隔离/人设映射 + M3 加固 | 见 §7 路线 |
---
## 二、VoxEMW 项目解剖（决定一切的事实基础）
### 2.1 形态判断
- 名字/形态：**魔镜女巫数字人**，v1.10.0 主线 = "4090 满血写实数字人版"。Mac/VRM 轻量档在 tag v1.9.0（不同形态，本次不讨论）。
- 典型部署：一张 AutoDL 4090（24GB），**四模型同卡常驻**：Qwen3-ASR-1.7B（STT）+ VoxCPM2（TTS）+ SoulX-FlashHead-1.3B（写实数字人）+ MiniCPM-V-4.6（视觉），显存 ~21.7G/24G。
- 大脑：**DeepSeek API**（`deepseek-v4-flash`），不是本地模型。所以"本地 4090 + 云上大脑"。
- 一句话：**这是端到端实时语音/视觉/数字人应用，重 GPU、多进程、自带头部追踪调度（pacer）**，与"浏览器端插件"是两种物种。
### 2.2 运行拓扑与边界（端口/进程/环境）
| 积木 | 端口/协议 | 进程/环境 | 职责 | 代码位置 |
|---|---|---|---|---|
| orchestrator | :8000 aiohttp HTTP+WS | `py312` 主 venv | 浏览器唯一入口：会话调度 / persona 注入 / 打断编排 / RTC 信令 / 静态服务 | `voxemw/gateway/orchestrator.py`（840 行） |
| s2s 语音管线 | :8765 realtime WS | 同 venv（`pipeline.launch`） | VAD→STT→LLM→TTS 全链路，`num_pipelines: 1` | `voxemw/pipeline/*` |
| SoulX 渲染 | :8791 WS | 独立 `flashhead` venv | 音频驱动写实 talking-head | `voxemw/avatar/soulx_server.py` |
| VLM 边车 | :18099 | 独立 `vlm` venv | MiniCPM-V 看图/OCR，供 `look_at_camera` 工具 | `voxemw/gateway/vlm_server.py` |
| 前端 | —— | 纯静态 | 画布/麦克风/摄像头/WebAudio/WS/RTC | `web/index.html`(48行)+`assistant.js`(909行)+`style.css` |
启动脚本：`07-scripts/start_4090.sh`（全启/stop）；配置：`configs/assistant-4090.yaml`（4090 档，`host: 0.0.0.0`）与 `configs/assistant.yaml`（Mac 档，只绑回环）。
### 2.3 前端页面硬依赖（决定 iframe 方案的约束）
`web/index.html` + `assistant.js` 是一个**全屏沉浸式单页**（canvas 星空背景 + 魔法镜 + 麦克风圆钮 + 实时转写区），运行时需要：
1. **getUserMedia 麦克风**（上行语音）、**摄像头**（仅 `look_at_camera` 触发时抓帧 POST `/vision/frame`）。
2. **WebSocket** `/ws`（上行音频/控制，下行转写/状态/音频 delta）+ 可选 **WebRTC**（`/rtc/offer`、`/rtc/ice`，Mac/LAN 档开、4090 远程档关，走 WS+WebAudio）。
3. **Secure Context 硬前提**：浏览器只在 https（或 localhost）下授予 getUserMedia 与 WebAudio。这意味着 **VoxEMW 页面必须经 https 域名对外**（直连裸 IP 的 http://ip:8000 拿不到麦克风）。
4. 若以 iframe 内嵌，iframe 需 `allow="microphone; camera"`，且页面本身必须处于安全上下文。
### 2.4 浏览器侧协议契约（引自 orchestrator.py 顶部 docstring）
```
/ws 文本帧(JSON)：
→ {"type": "vox.persona", "id": "<persona_id>"} 切换人设（可运行时切换）
→ OpenAI Realtime 事件原样透传（input_audio_buffer.append / response.cancel …）
← OpenAI Realtime 事件透传（transcription / response.done …）
← {"type": "vox.status", "persona": "<id>", "rtc": {"enabled": bool, "ice_servers": [...]}}
GET /api/personas → 人设清单（默认人设 + 列表）
POST /rtc/offer → WebRTC 信令（body {"sdp","type"} → answer）
GET /rtc/ice → ICE 配置
POST /vision/frame → 视觉帧上报（VLM 用）
/static/* → 前端静态资源
```
### 2.5 单会话硬约束（本方案最核心的工程约束）
`orchestrator.py` 明确写着 **"单用户单会话：新浏览器连接顶掉旧会话"**：
```python
current_session: dict = {"session": None} # 全局只有一个槽
...
async def ws_handler(request):
old = current_session["session"] # 顶掉旧的
...
current_session["session"] = session # 新连接独占
```
深层原因：s2s 只有 1 个管线槽（`num_pipelines: 1`）+ 一张 4090 的渲染算力只够一路写实数字人。**这是上游物理/架构决定，不是配置能改的**。任何"多用户并发各自开一路魔镜"的设想都必须先接受这个天花板。
推论：多用户接入必须走**槽位仲裁（slot claim）**：同一时刻只有 1 个 dsh 用户能占用魔镜，其余用户看到"占用中"并可排队/订阅释放。
### 2.6 状态持久化现状（对"用户数据隔离"是重大利好）
- Session 状态**全部在内存**：`_assistant_history` 仅保留近 2 轮回复（回声判定用），随连接销毁即清。
- **无用户语音/转写落盘**（默认不开 live transcription；`enable_live_transcription: false`）。
- 唯一"持久"的是 `personas/*.md`（人设正文 + 音色描述/种子），由配置文件静态装载，启动时进 `config.personas.resolved` 字典。
- 结论：VoxEMW 侧几乎没有可跨用户残留的数据。**"用户数据隔离"主要矛盾在 dsh 侧的接入编排层，而非 VoxEMW 数据层。**
### 2.7 安全现状（需 dsh 侧补齐）
- orchestrator **无鉴权、无多租户、无审计**（4090 档直接 `host: 0.0.0.0`）。若裸奔公网：任何人可白嫖你的 DeepSeek key 和 GPU。
- LLM key 走进程级环境变量 `DEEPSEEK_API_KEY`，单实例单 key，**无法按用户区分计费/配额**。
---
## 三、参考实现拆解：plugin_package 给了哪三块模板
### 3.1 dsh 客户端插件的"三段式骨架"（三个包一致）
```
dsh-plugin-xxx/
├─ package.json # main=lib/index.js; exports{ "." , "./client" };
│ # dsh.client.platform="web" (+可选 inject:["@deepseek-ai/dsh-client-*"])
│ # dsh.bundle.patch="./cordis.patch.yml"
├─ cordis.patch.yml # 声明式注册本插件 bundle 层：- insert: [{id, name}]
├─ lib/index.js # 服务端半区（在 dsh 进程内）：注册 HTTP 路由 / MCP 工具描述、守护外部服务
└─ lib/client.js # 客户端 bundle：window.__ModuleLoader__.load({id, factory})，
# 内部 exports.apply()/exports.inject[]（Cordis 应用层注入）
```
`cordis.patch.yml` 示例（三个包一致，mcn-nav / social-workbench / douyin-accounts 各一条 insert）。
### 3.2 模板 A：social-workbench —— "守护 + 内嵌独立服务"（与 VoxEMW 场景最同构）
- 场景：Easel 是**独立的**社媒工作台（自带 .venv + web 前端，默认 :7860）。
- host 半区（`lib/index.js`）只做守护/探活，不搬 Easel 代码：
- `GET /swb/status`（探活 web/gateway、安装状态、子进程存活、日志尾）
- `POST /swb/start` / `POST /swb/stop`（拉起/停掉独立进程）
- `GET /swb/log`（返回日志尾）
- 环境变量覆盖：`EASEL_DIR`、`EASEL_WEB_PORT`、`EASEL_SWB_AUTOSTART`
- client 半区（`lib/client.js`）：`apply()` 里注册 `window.__mcnEntries.push({id:'social-workbench', icon, title, component})`，component 渲染一个含 `iframe src=state.webUrl` 的面板（状态条 + 启动按钮 + 内嵌页）。
- **可复制点**：VoxEMW 插件 host 半区 = `/voxemw/status|start|stop|log` + 代理；client = `__mcnEntries` 注册 + iframe 内嵌。
### 3.3 模板 B：dsh-plugin-mcn —— "会话窗口旁边显示"的标准答案
mcn 的 client bundle 实现了**把聊天窗口与工作台面板左右分栏**的技术，全部在浏览器 DOM 层完成，代码证据（`lib/client.js`）：
```css
.mcnNav_split{display:flex;flex-direction:row;flex:1 1 auto;min-width:0;min-height:0;
width:100%;height:100%;overflow:hidden;...}
.mcnNav_split>[data-slot='conversation']{display:contents} /* 会话被包进容器 */
.mcnNav_split>[data-slot='conversation']>div{
flex:1 1 0%!important; min-width:0!important; height:100%!important;
--dsh-chat-content-width:100%!important} /* 面板收起时满宽 */
.mcnNav_split>.mcnNav_resizer{flex:0 0 5px;height:100%} /* 拖拽条 */
.mcnNav_split>.mcnNav_panel{flex:0 0 auto;height:100%} /* 右侧面板 */
```
- `startResize()`：mousedown 记录 startX/startW → mousemove 改面板宽度 → 面板侧记忆 `localStorage["mcnNav.panelSide"]`。
- 机制本质：**把 dsh 的 `[data-slot='conversation']` DOM 节点移入插件自己的 flex 容器**，展开时塞入 resizer+panel，收起时等价恢复满宽（`display:contents` + `--dsh-chat-content-width` 兼容聊天区自身宽度变量）。
- 生态分工：**mcn 是"壳"**（注入左侧导航 + 提供 `window.__mcnEntries` 注册表 + 会话分栏），**其余功能插件是"页"**（douyin-accounts / douyin-video-detail / mcn-schedule / social-workbench 全部通过 `window.__mcnEntries.push/unshift` 注册，点击后在右侧面板渲染页面）。
> 因此"在会话窗口旁边显示"在 plugin_package 生态里的标准做法 = **做一个 feature-tier 插件，注册进 `__mcnEntries`**；前提是宿主 dsh 已安装 mcn 壳（用户环境天然满足：plugin_package 就是这套生态）。
### 3.4 模板 C：douyin-accounts —— host 路由 + 页面 CRUD 的 API 形态
- `lib/index.js` 暴露 `/mcn/api/*`（accounts CRUD、列表、分析等）HTTP 路由；同时也以工具描述形式暴露给 agent（MCP/工具语义），前端直接 fetch 调用。
- **可复制点**：VoxEMW 的"会话控制/人设/状态"控制面做成 `/voxemw/api/*`，页面与 agent 双通道可调。
---
## 四、可行性判定与形态选择
| 形态 | 做法 | 判定 | 原因 |
|---|---|---|---|
| 形态 0：二开/搬代码 | 把 voxemw python + 4 个模型装进 dsh 进程/客户端 bundle | ❌ 不成立 | ① GPU 重负载 + 独立 venv 多进程，无法进客户端 bundle；② 违反既有红线（不改写官方 bundle、插件不打包重型服务）；③ 跨平台（Windows 开发机无 GPU/模型装不上） |
| 形态 1：**host/feature 插件 + 同源代理 + iframe 内嵌**（推荐） | VoxEMW 部署在 GPU 主机（本地或远程），dsh 侧插件守护它，并通过 dsh 所在 https 域同源反向代理 `/voxemw/*`；客户端在会话分栏 iframe 打开 | ✅ **推荐** | social-workbench 同构已验证；同源代理一举解决 secure context（麦克风/摄像头权限）与 ws 透传；插件本体轻量、可独立升级；VoxEMW 仍可独立更新 |
| 形态 2：iframe 直连 GPU 主机裸址 | `iframe src=http://gpu-host:8000` | ⚠️ 不推荐 | 裸 http 非安全上下文 → 麦克风/摄像头被浏览器拒绝；跨源 ws 需要 VoxEMW 侧放行 CORS/Origin（上游未做）；token 无法注入 |
**最终形态（形态 1）一句话**：`dsh-plugin-voxemw` = social-workbench 的守护骨架 + mcn 的会话分栏 + VoxEMW 自己的 web/ 页面做面板内容，页面流量经 dsh 域名同源代理到 GPU 主机 orchestrator。
---
## 五、总体架构设计
### 5.1 目标拓扑
```
┌────────────────────────────── dsh Web (https://dsh.alotbuy.com 或同级域) ──┐
│ dsh 主进程 │
│ └─ dsh-plugin-voxemw (feature-tier, 注册 __mcnEntries) │
│ ├─ lib/index.js host 半区 │
│ │ ├─ /voxemw/api/status|start|stop|slot|personas 控制面 │
│ │ ├─ /voxemw/proxy/* 同源反代 → GPU 主机 orchestrator │
│ │ │ (HTTP /ws /static /rtc/offer /vision/frame 全透传) │
│ │ └─ SlotManager(进程内): 槽位互斥 + profile 维度状态 │
│ └─ lib/client.js client bundle │
│ ├─ 会话分栏 (mcn 同款: [data-slot=conversation] 包 flex) │
│ └─ 面板: iframe allow="microphone; camera" src=/voxemw/ │
│ + 状态条(占用/空闲/排队) + 弹出全屏 │
└──────────────┬──────────────────────────────────────────────────────────┘
│ 仅插件 host 出网（隧道 / 白名单 443 / 内网）
▼
┌────────────── GPU 主机（AutoDL 4090 或自有 GPU 机）──────────────────────┐
│ 07-scripts/start_4090.sh │
│ orchestrator :8000 ← s2s :8765 · SoulX :8791 · VLM :18099 │
│ 全部只绑回环/私网，由 dsh 侧代理访问；DEEPSEEK_API_KEY 在此进程内 │
└─────────────────────────────────────────────────────────────────────────┘
```
### 5.2 dsh-plugin-voxemw 包结构（交付蓝图）
```
dsh-plugin-voxemw/
├─ package.json # 三段式骨架；name=dsh-plugin-voxemw
├─ cordis.patch.yml # insert: [{id: voxemw-nav, name: dsh-plugin-voxemw}]
├─ lib/
│ ├─ index.js # host：SlotManager + /voxemw/api/* + /voxemw/proxy/*
│ ├─ slot.js # 槽位仲裁：claim/release/queue/keepalive（profile 维度）
│ ├─ personas.js # 用户↔人设 映射（每 profile 一份 persona 清单，可热同步到 VoxEMW personas 目录）
│ ├─ proxy.js # 同源反向代理（http/ws 透传、超时、断线自愈、按 profile 注入会话 token 查询参数）
│ ├─ supervisor.js # VoxEMW 进程/远程隧道 守护与探活（对标 social-workbench /swb/*）
│ ├─ client.js # bundle：__ModuleLoader__.load + 会话分栏 + 面板 iframe + 状态 UI
│ └─ (可选)embed/ # 对 VoxEMW web/ 的极简适配（窄栏 CSS 注入、标题/关闭、全屏弹层）
├─ build.mjs # client 打包（esbuild/rollup → 单文件 bundle，css 内联）
└─ README.md
```
### 5.3 关键流程时序
**① 打开魔镜（claim + persona 注入）**
```
用户点击侧栏「魔镜女巫」→ mcn 会话分栏展开右侧面板 → iframe 载入 /voxemw/（同源，安全上下文）
→ client 调 POST /voxemw/api/slot/claim {profile}
→ SlotManager: 空闲? 分配 claimId(30min 续期) : 返回 occupied(+排队序号)
→ 面板显示「占用中 / 空闲 / 排队中」
→ iframe 内 VoxEMW 前端建立 /ws；插件在 URL 上注入 ?claim=claimId&persona=<该profile映射人设>
→ VoxEMW 前端 connect 后发送 vox.persona（或由代理改写首个消息）完成人设落定
```
**② 会话中**
- 语音全走 VoxEMW 自己链路（浏览器→代理→orchestrator→s2s/模型），dsh 只做透传，不落语音。
- 面板关闭/页面卸载 → `POST /voxemw/api/slot/release`；异常断线由 supervisor keepalive 超时回收（orchestrator 本身也会被新连接顶掉，双保险）。
**③ 占用冲突（核心场景）**
- 用户 B 打开 → claim 被拒 → 面板给「魔镜正被 用户A 使用」+ 订阅（slot 释放事件推送，B 可一键接管）。
- 可选策略（配置项）：B 请求「强制接管」→ 插件先优雅 release A（A 端收到 `vox.status{evicted:true}` 提示）。
### 5.4 代理路由表（/voxemw/proxy/* 透传清单）
| 上游 | 方法 | 用途 |
|---|---|---|
| `/`、`/static/*` | GET | VoxEMW 前端静态页（走代理 = 同源 = 安全上下文） |
| `/ws` | WS 升级 | 实时语音/控制主通道 |
| `/api/personas` | GET | 人设清单（按当前 profile 过滤后返回） |
| `/rtc/offer`、`/rtc/ice` | POST/GET | RTC 信令（4090 档默认关闭，保留透传能力） |
| `/vision/frame` | POST | 视觉帧上报 |
> 若 GPU 主机与 dsh 不在一台：优先 **SSH 反向隧道**（`ssh -R` 或 autossh 保活，只把 orchestrator :8000 映射到 dsh 主机的 127.0.0.1:18000），代理指向 `http://127.0.0.1:18000`，彻底避免 GPU 主机暴露任何公网端口；GPU 主机防火墙仅放行 dsh 主机 IP 的出向建立。
---
## 六、用户数据隔离设计（多租户）
### 6.1 数据面与威胁面
| 数据类别 | 存在哪 | 生命周期 | 跨用户风险 |
|---|---|---|---|
| 用户语音流 | 浏览器内存 → WS → VoxEMW s2s（内存） | 会话结束即清 | 无（不落盘） |
| 摄像头帧 | 浏览器内存 → `/vision/frame`（`_last_frame` 单帧覆盖） | 单帧 | 无 |
| 转写/回复文本 | orchestrator 内存 + 浏览器转写区 | 会话结束即清 | 无 |
| persona/音色 | `personas/*.md`（VoxEMW 侧，共享目录） | 持久 | **中**：若共享目录，A 建的人设 B 可切到 |
| 会话占用状态 | SlotManager（dsh 进程内） | 实时 | 需要防串号 |
| LLM 调用（DeepSeek） | 云 | 账单 | **中**：单 key，无法按用户区分成本 |
| dsh 插件日志 | dsh 日志文件 | 持久 | 低：可能含转写/人设，需分级 |
### 6.2 三层隔离策略
1. **槽位层（并发互斥）**：SlotManager 保证同时只有 1 个 claim 存活；claim 的 key = `profileId`，**任何接管/释放都校验 claimId 归属**，杜绝 A 顶掉 B 或读到 B 的会话（VoxEMW 的"新连接顶旧连接"特性被槽位仲裁封死在上游）。
2. **配置层（persona/人设）**：VoxEMW 的 personas 由启动配置装载。落地：
- 每 profile 的 persona 包（`{profile}/voxemw/personas/*.md`）与 orchestrator 的共享 personas 目录**分离管理**；
- 插件持有"profile → persona_id"映射表（存 dsh 侧 profile 维度，不存 VoxEMW）；
- 变更时走"热切换"：会话内发 `vox.persona`；新增 persona 需重启 orchestrator 装载的场景，由 supervisor 在**无 claim 的空窗期**原子重载（`/voxemw/api/personas/reload`，M2/M3 范围）。
3. **数据/密钥层**：
- 语音/帧/转写**默认零持久化**（维持上游 `enable_live_transcription:false`），需要留存时显式开启并按 profile 落 `$DSH_HOME/storages/` 下用户目录，权限沿用 dsh setpriv/account 边界；
- `DEEPSEEK_API_KEY` 保持进程级，dsh 侧**不接触该密钥**；成本控制靠槽位互斥 + claim 期配额（每 profile 每日时长上限，超限拒 claim）+ 日志记账（profile 维度调用统计）；
- 插件自身状态（claim/映射/审计）全部以 `profileId` 为主键，输出到 profile 自己的工作区。
### 6.3 与 dsh 既有隔离模型的衔接
- 若 dsh 部署为**每 profile 独立实例**（`ISOLATION=account` + setpriv）：插件 index.js 天然运行在用户实例内，SlotManager 需改为**跨实例协调**（共享一个小型注册表：Redis/文件锁/Unix socket，按 profileId 加锁）；推荐把 SlotManager 做成 dsh 主进程侧单例，实例侧只做 claim RPC。
- 若 dsh 为**集中式多用户**（dshs 按 token 分离会话）：插件在请求上下文拿 `profileId`，所有写操作按 profile 命名空间隔离，逻辑同上。
### 6.4 风险清单（P1/P2）
| 级别 | 风险 | 说明 | 缓解 |
|---|---|---|---|
| P1 | 多用户并发被物理限制为 1 路 | 上游单管线单会话 + 单卡算力 | 槽位互斥 + 排队 + 强制接管策略（产品上明示"魔镜单席位"） |
| P1 | 无鉴权裸奔 | orchestrator 0.0.0.0 无认证，公网可白嫖 | 永不直连公网；仅 dsh 代理访问；GPU 主机 443/白名单；代理层对 `/voxemw/*` 校验 dsh 会话 |
| P1 | 前端需安全上下文 | 裸 http 拿不到麦克风/摄像头 | 一律经 https 域同源代理；iframe `allow="microphone; camera"` |
| P2 | 共享 personas 目录串扰 | A 建人设 B 可见 | profile 维度 persona 包 + 映射表隔离（§6.2-2） |
| P2 | 单 DeepSeek key 无分账 | 无法按用户限流 | claim 配额 + profile 维度用量记账（M3） |
| P2 | 转写/文本进日志 | 共享日志跨用户可读 | 日志分级：语音链路事件降到 warning；含人设/转写日志按 profile 独立文件 |
| P2 | iframe 内嵌 UI 适配 | 全屏沉浸页塞窄栏体验打折 | embed/ 窄栏 CSS + 面板内全屏/新窗口模式；VoxEMW web/ 基本是响应式 canvas，适配成本低 |
| P2 | 远程隧道保活 | 断隧 = 面板失效 | autossh/心跳 + supervisor 探活；VoxEMW 自身有断线自愈，主要保链路 |
---
## 七、实施路线（里程碑 + 验证点）
**M1 — 服务可达 + 面板可见（1 个工作日量级）**
1. GPU 主机起 `start_4090.sh`，确认 orchestrator :8000 各积木就绪（`07-scripts/avatar_probe.py` / `s2s_text_probe.py` 可参考）。
2. dsh 侧先手工验证：BT 反代或 SSH 隧道把 8000 映射到 dsh 域 `/voxemw/`；浏览器开 https 页，确认麦克风授权、能对话、数字人出画。
3. 搭插件骨架（package.json + cordis.patch.yml + 空 apply），client 只做"会话分栏 + iframe 指向 /voxemw/"，host 只做纯透传。
- ✅ 验证：在 dsh 会话旁看到魔镜面板且完整可用；关面板后会话区无损恢复。
**M2 — 槽位仲裁 + 隔离 + 人设映射**
4. SlotManager claim/release/keepalive + 占用/排队 UI + 强制接管。
5. profile→persona 映射 + 会话内自动 `vox.persona` 注入；personas 目录 profile 化改造。
6. 代理层注入会话校验（非 dsh 登录态一律 401）；面板关闭自动 release。
- ✅ 验证：双账号交替/并发用例（A 占用时 B 看到占用并可排队/接管；A 会话不被 B 看到）；A 的自定义人设 B 不可见。
**M3 — 加固与运营**
7. 日志分级/脱敏（按 profile 分文件）；用量记账 + 配额；supervisor 状态页（对标 /swb/status：隧道健康、各积木 up/down、claim 占用者）。
8. 窄栏 UI 适配 polish + 全屏/新窗口模式；`README` 安装运维文档。
- ✅ 验证：审计日志只含本人数据；GPU 主机零公网端口可被外部探测；断隧自动恢复。
---
## 八、环境前置与成本（不回避）
| 项 | 要求 | 备注 |
|---|---|---|
| GPU | **1× 4090 24GB（或同档）**，四模型 ~21.7G | 无 GPU 则只有 Mac 轻量档(v1.9.0，无写实数字人)可选，架构同但产物不同 |
| 网络 | dsh 主机 ↔ GPU 主机可建隧道/白名单；dsh 域名 https | 复用现网 dsh.alotbuy.com 反代能力 |
| 密钥 | `DEEPSEEK_API_KEY`（GPU 主机环境变量） | dsh 侧不持有 |
| 模型下载 | HF：Qwen3-ASR / VoxCPM2 / SoulX-FlashHead / MiniCPM-V | 按 `docs/plan-4090.md` 预装（一次性） |
| dsh 侧 | 已装 mcn 壳（plugin_package 生态） | 本插件走 feature-tier 注册 |
| 兼容性红线 | 不改写 `/usr/local/lib/node_modules/@deepseek-ai/dsh` 官方 bundle；不动 VoxEMW 上游 | 全部改动隔离在 dsh-plugin-voxemw 目录 + GPU 主机私有部署目录 |
---
## 附录 A：代码证据索引（供复核）
| 结论 | 证据 |
|---|---|
| VoxEMW 六积木架构 | `README.md`（"架构（六块积木）"）、`docs/plan-4090.md` |
| 路由表 | `voxemw/gateway/orchestrator.py` L779-787（add_get/add_post/add_static） |
| 单用户单会话 | `orchestrator.py` L678 `current_session: dict`；L733-765 `ws_handler` 顶替逻辑；顶部 docstring "单用户单会话" |
| 浏览器协议 | `orchestrator.py` docstring（/ws 帧、/rtc/offer、/rtc/ice） |
| 无状态 | `Session._assistant_history` 仅 2 轮（L225）；`enable_live_transcription:false` |
| personas 静态装载 | `assistant.yaml` personas.list；orchestrator L640 `config["personas"]["resolved"]` |
| 守护+内嵌模板 | `dsh-plugin-social-workbench/lib/index.js` L4-7（/swb/status\|start\|stop\|log）；`client.js` iframe L115、`__mcnEntries` apply() |
| 会话分栏技术 | `dsh-plugin-mcn/lib/client.js`：`.mcnNav_split` CSS、`[data-slot='conversation']{display:contents}`、`.mcnNav_resizer{flex:0 0 5px}`、`startResize`、`localStorage["mcnNav.panelSide"]` |
| feature-tier 注册 | `douyin-accounts/lib/client.js` L649-652 `window.__mcnEntries.push({id:'douyin-accounts',...})` |
## 附录 B：名词对照
| 名词 | 说明 |
|---|---|
| s2s | speech-to-speech 实时语音管线（VAD→STT→LLM→TTS） |
| pacer / audio_pacer | orchestrator 内音频滴灌调度（对齐数字人渲染） |
| persona | 人设包：正文 + 音色（VoxCPM2 voice_control/voice_seed） |
| __mcnEntries | mcn 壳暴露给功能插件的页面注册表（window 全局） |
| data-slot='conversation' | dsh 聊天区 DOM 标记，插件以此定位并包入分栏容器 |
| claim / SlotManager | 本方案引入的"魔镜单席位"占用仲裁 |
归档/dsh-server-docs-清理-20260924/工作区草案/插件管理面_调整方案草案_20260910.md
+205
View File
@@ -0,0 +1,205 @@
# 13-插件管理面（修订 v5：入库审查门禁 + 用户自选启用，Step 0 核查结论已回填）
> 状态：**方案草案 v5，待用户拍板 3 个决策点后实施**｜2026-09-10｜对象：dshs + dsh 0.1.2-rc.1
> v3 范围（07:57）：普通用户可查看 admin 上传的全部插件，卡片多选 →「启用」弹窗确认 → 才复制进用户 profile → 重启该用户 dsh 实例后生效。
> v4 范围（08:00）：admin 上传一律先进审查区，过「安全检测 + 多用户检测」无 P0/P1 才可发布入库；用户选择页仅展示 published。
> v5 范围（08:1x，Step 0 服务器实测回填）：**平台已自带部分插件机制**（见 §四），本方案收敛为在其上新增四件事——admin 全局库+审查门禁、用户拉取式安装（复制进 profile）、启用后**带新 patch 立即重启**（新增 relaunch）、插件选择页。启用状态源修正为 DB `folder_plugins`（非 profile patch disabled 行）。
> 评审稿：`D:\AI技能\aliyun-dsh-server\插件管理面_调整方案草案_20260910.md`；核对后定稿 `04-调整方案/` 档案 13 双端同步。
## 一句话结论
平台已能"列出用户 profile 已装插件 + 按工作区 folder 勾选启停（launch 时渲染 patch 生效）"，且有桌面端「插件」面板（desktop.html）；**缺的是上游**：admin 的全局插件库与入库审查门禁、用户把库插件**安装**进自己 profile 的入口、启用后**立即生效**（现有机制只在下次 launch 生效）。本方案补上这四块：admin 上传 → 审查区（安全 S1-S10 + 多用户 M1-M9，P0/P1 阻断，报告留痕）→ 发布入库；用户在「插件选择页」浏览 published 库 → 卡片勾选（批量）→「启用」弹窗确认 → 后端 安装（复制进 profile + 追加 bundles；已装则跳过）→ 写入当前工作区 enabled 集 → **relaunch（重算 patch 并重启实例）** → 生效。
## 一、角色与流程
| 操作 | admin | 普通用户 |
|---|---|---|
| 查看已发布插件库（选择页） | ✅ | ✅ |
| 上传插件（进审查区，≠入库） | ✅ | ❌ |
| 检测/出报告（安全 + 多用户） | ✅（自动 + 复核终审） | ❌ |
| 发布入库 / 打回需改造 | ✅ | ❌ |
| **安装**（从库复制进自己 profile） | ✅ | ✅（选择页，随启用自动） |
| **启用**（= enabled 集 + relaunch） | ✅ | ✅ **核心动作** |
| **禁用**（= 移出 enabled 集 + relaunch） | ✅ | ✅ |
| 删除/移除已发布包（全局） | ✅ | ❌ |
**插件入库时序（admin）**：同 v4（upload → under_review → 自动检测 S/M → 无 P0/P1 + admin 复核 → release → published）。
**用户启用时序（v5 精确流程，对齐平台真实机制）**：
```
1. 打开「插件选择」页 → GET /api/plugins/library?folder=<当前工作区>
→ published 全量 × 本人状态：未安装 / 已安装-未启用 / 已启用(本 folder)
2. 勾选卡片（可批量）→ 点「启用」
3. 弹窗确认：插件清单 + 「将安装到你的个人配置并重启你的 dsh 实例，当前会话可能中断」
4. POST /api/plugins/library/enable {names:[...], folder}
5. 后端 per 插件：
a. 未安装 → 从 published 库复制包目录 → profile/node_modules/<pkg>
+ chown 用户 uid/gid（先顶层再子项）+ profile package.json dsh.profile.bundles 追加
（冲突预检：短 id/路由/官方名/同名不同版本 → 409）
b. enabled 集（DB folder_plugins，按 folder workspace）写入该插件 id
c. orchestrator.relaunch(user)：按该 folder 重算 patch = renderPatch(enabled∩installed)
→ 以新 patch 重启 main + watchdog（复用既有 launch 的计算逻辑，抽公共函数）
6. 返回 → 页面状态刷新 = 已启用；工作台出现插件入口
```
**禁用时序**：勾选已启用插件 → 「禁用」→ 确认 → enabled 集移除该 id → relaunch → 入口消失（profile 副本保留，再次启用免复制秒级恢复）。
## 二、总体机制
```
admin 上传 ─▶ 审查区 under_review（dataRoot/plugin-reviews，用户不可见，root 600）
│ 自动静态检测 S1-S10 + M1-M9 → 报告(P0/P1/P2)
├─ P0/P1 → needs_fix 需改造 ─▶ 改造重传复检
└─ 无 P0/P1 + admin 复核 ─▶ release ─▶ published 库
│ dataRoot/plugin-library（root 600 只读）
▼
插件选择页 plugins.html（仅 published）
│ enable = 安装(复制进 profile)+enabled集+relaunch
▼
用户 userRoot=dataRoot/users/<uuid>/
├─ home/profiles/web/package.json ← dsh.profile.bundles（installed 源）
├─ home/profiles/web/node_modules/<pkg> ← 复制落点（chown 用户）
├─ home/profiles/web/cordis.patch.yml ← role patch，勿动（ensure-role-profile-patch.cjs 管）
└─ patches/main.yml ← launch/relaunch 渲染的 --patch（DB enabled 派生）
▼ relaunch（新 patch）→ dsh --profile web 重启 → 生效
```
- **installed 与 enabled 是两态**：installed = profile 已含该 bundle（复制+声明）；enabled = 当前工作区 folder 的 DB enabled 集（决定 launch patch 是否注入）。桌面端既有「插件」面板只做 enabled 勾选（下次 launch 生效，不重启）；选择页做"库浏览 + 安装 + 启用(立即 relaunch)"。
- **共享库 = 源，profile = 副本，enabled 集 = 状态**；禁用 ≠ 卸载（副本保留）。
- 用户选择页仅 published；审查区/报告仅 admin 可见。
## 三、入库审查门禁（安全检测 + 多用户检测）— 同 v4
**放行规则**：canRelease = 无 P0 且无 P1；P2 不阻断留档；admin 人工复核为 release 必选终审；检测只读扫描、不执行包内脚本；报告 JSON 留痕（root 600，按版本保留）。
**安全检测 S1-S10**：
| # | 检查内容 | 级别 | 整改建议 |
|---|---|---|---|
| S1 | 归档：恰一个顶层目录；无 `..`/符号链接逃逸/设备文件 | **P0** | 重打包 |
| S2 | package.json 合法；`dsh.bundle.patch` 存在且指向存在文件 | **P0** | 补清单 |
| S3 | `@deepseek-ai/*`、官方同名 | **P0** | 改名（红线 2） |
| S4 | install/postinstall 等 npm 脚本 | **P0** | 移除 |
| S5 | exec/spawn、动态 eval/Function、vm 逃逸 | P1 | 说明+复核；纯函数化 |
| S6 | http(s) 出网非白名单 | P1 | 登记域名+用途 |
| S7 | 混淆/隐藏文件/超大二进制(>5MB 说明) | P1 | 去混淆可审计 |
| S8 | fs 写绝对路径/越出插件目录/触碰他人 profile | **P0** | 改注入的相对路径 |
| S9 | chown/root 级写/监听 0.0.0.0 | P1 | 移除，编排器统一管 |
| S10 | client 硬编码 token/密钥/内网地址 | P1 | 走 profile 密文配置 |
**多用户检测 M1-M9**（针对单用户 dsh 开发假设）：
| # | 检查内容 | 级别 | 整改建议 |
|---|---|---|---|
| M1 | 硬编码绝对路径/固定配置位置 | P1 | 注入的相对路径/dataDir |
| M2 | 独占固定端口/0.0.0.0 | P1 | 实例内路由/动态端口 |
| M3 | 共享外部服务单槽（VoxEMW current_session 教训） | P1 | 无状态/云 API/多槽 |
| M4 | 持久化写到 profile 外共享全局文件 | **P0** | profile 内 JSONL |
| M5 | 短 id/路由/`__mcnEntries` 键与已发布或审查中冲突 | **P0** | 登记表比对改唯一 |
| M6 | 模块级可变单例跨租户串用 | P1 | 随实例或按用户键 |
| M7 | 无锁写共享资源/假定唯一活跃会话 | P1 | 单写锁/编排器串行 |
| M8 | 大模型/GPU/长驻进程等资源声明 | P2 | 卡片标注，admin 视容量放行 |
| M9 | 假定热加载/无需重启 | P2 | 明示需重启（页面已含提示） |
## 四、Open Questions 前置核查结论（Step 0 服务器实测，2026-09-10）
| # | 结论（实测事实） | 对实现的影响 |
|---|---|---|
| OQ1 | **profile 布局 ✅**：dataRoot=`/var/lib/dshs`（env `DSHS_DATA_ROOT`）；`userRoot=dataRoot/users/<uuid>`（owner=每用户 uid/gid，如 `dsh-eeccbc...`/100002）；profile=`userRoot/home/profiles/web`（MAIN_PROFILE `web`）；installed 源=profile `package.json` 的 `dsh.profile.bundles`；包实体=`profile/node_modules/<pkg>` | 复制落点=该 profile node_modules；写后 chown 用户 uid/gid（先顶层再子项） |
| OQ2 | **复制式安装未实证，待 dry-run**：现 profile node_modules 无 `@deepseek-ai/*` 实体（未运行/由 dsh CLI 首启安装）；listInstalledPlugins 按 `node_modules/<pkg>/package.json` 读 description | 实现后用无害测试插件在测试用户上 dry-run：复制 → listInstalledPlugins 可见 → relaunch 生效；若 pnpm/安装逻辑清掉手放目录 → fallback `dsh plugin add`（走 CLI） |
| OQ3 | 新用户 profile 由 spawn 首启 `dsh --profile web` 创建（09-09 建号已见 profiles/web + node_modules 目录骨架） | 复制目标不存在 → ensureDir + 最小骨架 package.json（bundles:[]）+ chown；极端情况走 OQ1 错误引导 |
| OQ4 | **✅ 有用户域重启端点但语义修正**：`POST /api/dsh/restart {command}`（requireAuth，操作 `request.user.id`）调用 `orchestrator.restartMain`，但 **restartMain 复用内存里的旧 patch，只能重启不能换插件集** | **新增 `orchestrator.relaunch(userId)`**：按当前 main 的 folder 从 DB 重算 patch（与 launch route 同逻辑，抽公共函数）→ 以新 patch 重启 main + watchdog。enable/disable 内部调用它，不新增公开端点亦可 |
| OQ5 | **✅ 平台已有插件启停面（桌面端）**：`desktop.html`「插件」面板调 `GET /api/plugins?folder=`（已装 + 每 folder enabled）与 `POST /api/plugins/select`（存 DB `folder_plugins`），**无重启动作，下次 launch 生效**；backend 已注册 `pluginRoutes`（09-08 底座）。官方 dsh 会话内设置是否另有插件分区：无运行实例未实证，UI 验证阶段补查 | 双 UI 定位：选择页 = 库浏览+安装+启用（立即 relaunch）；桌面面板 = 已装插件快速勾选（保留）。desktop 加提示"装新插件请到插件选择页"；若官方会话设置确有启停分区，再加互链（记录为验证项，不阻塞 v1） |
| OQ6 | **✅ 状态源修正**：installed = profile `dsh.profile.bundles`（listInstalledPlugins 现有实现）；enabled per folder = DB `folder_plugins`（workspaces 按 user+folder 键）。**草案旧假设"profile cordis.patch.yml 写 enabled/disabled 行"不适用**；且 profile 现存 cordis.patch.yml 是 role patch（`ui-settings-models` disabled，ensure-role-profile-patch.cjs 管理）——**勿手改** | enabled 一律走 DB 集操作（getOrCreateWorkspace + setFolderPlugins / getEnabledPluginIds 已存在） |
| OQ7 | 冲突检测：复制时按 name 比对 profile 已装版本（bundles + node_modules 包 version）；库 release 时同名同版本拒绝覆盖 | 409 version-conflict；卡片显示"已装 vX，库 vY" |
| 附加 | launch route 已实现 patch 计算（`renderPatch(enabled∩installed)`）但为内联逻辑；`renderPatch` 恒注入 `dshs-runtime`（supervisor/patch.ts） | 抽 `patchForLaunch(...)` 公共函数，launch/relaunch 共用，行为零变化 |
## 五、API 设计
统一基址 `/api/plugins`；鉴权 requireAuth / requireAdmin。**既有 `/api/plugins` GET 与 `/api/plugins/select` 保留不动**（桌面端在用）。
**用户（新）**
| 接口 | 行为 |
|---|---|
| `GET /api/plugins/library?folder=` | published 全量（name/version/desc/hasClient/hasServer/reviewedAt/pkgSize）+ 本人状态 `{state: none\|installed\|enabled, installedVersion}` |
| `POST /api/plugins/library/install` | body `{names:[], folder?}` → 仅安装（复制+chown+bundles 追加），不启停 → `{ok, installed:[...]}`（供"仅安装稍后启用"） |
| `POST /api/plugins/library/enable` | body `{names:[], folder?}` → 未装则先安装 → 写 enabled 集 → **relaunch** → `{ok, enabled:[...], restarted:true}` |
| `POST /api/plugins/library/disable` | body `{names:[], folder?}` → 移除 enabled 集 → relaunch → `{ok, disabled:[...], restarted:true}` |
**Admin（新）**
| 接口 | 行为 |
|---|---|
| `POST /api/plugins/admin/reviews` | 上传进审查区 → 自动检测 → `{reviewId,name,version,status,report}` |
| `GET /api/plugins/admin/reviews` | 审查区+库全条目（status/版本/报告摘要/P0·P1 计数/历史） |
| `GET /api/plugins/admin/reviews/:id` | 详情 + 最新报告全文 |
| `POST /api/plugins/admin/reviews/:id/release` | 发布入库；有 P0/P1 → 409 has_blockers；同名同版本 → 409 version-conflict |
| `POST /api/plugins/admin/reviews/:id/reject` | 打回 needs_fix + `{comment}` |
| `DELETE /api/plugins/admin/reviews/:id` | 丢弃审查条目 |
| `DELETE /api/plugins/admin/library/:name` | 移除已发布包（用户副本不受影响） |
| `GET /api/plugins/admin/users` | 只读矩阵：每用户 installed/enabled 状态 + 版本 |
错误码：`400 invalid_plugin_name / unsupported archive type / archive must contain exactly one top-level dir / missing package.json(dsh.bundle) / reserved-package(@deepseek-ai/*) / archive member escapes root`、`404 not_found`、`409 already_enabled / has_blockers / version-conflict / id-conflict`。
上传校验规则同 v4（恰一顶层目录、dsh.bundle.patch 必在、防穿越、禁 @deepseek-ai/*；校验通过 ≠ 入库）。
## 六、改动文件清单（服务器 /opt/dshs，备份 `*.bak-YYYYMMDD-HHMM`）
| 文件 | 改动 |
|---|---|
| `src/config.ts` | 加 `pluginLibraryDir`（默认 `<dataRoot>/plugin-library`）、`pluginReviewDir`（`<dataRoot>/plugin-reviews`） |
| `src/fs/plugins.ts` | 扩展：`installToProfile`（复制+chown+追加 bundles）、`isInstalled`/`installedVersion`（OQ7 比对） |
| `src/fs/plugin-library.ts` | **新增**：published 库读写/列表/删除（root 600 语义） |
| `src/lib/pluginScan.ts` | **新增**：静态检测引擎（S1-S10+M1-M9 + 分级报告，只读不执行） |
| `src/supervisor/orchestrator.ts` | **新增 `relaunch(userId)`**：重算 patch + 带新 patch 重启 main + watchdog；launch 内 patch 计算抽公共函数（行为零变化） |
| `src/web/routes/archive.ts` | **新增**：解压+穿越校验+chown 公共 helper（08-skills/plugins/reviews 复用） |
| `src/web/routes/pluginLibrary.ts` | **新增**：用户库（list/install/enable/disable → 内部 relaunch） |
| `src/web/routes/pluginReviews.ts` | **新增**：admin 审查生命周期 + 库 CRUD + users 矩阵 |
| `src/web/server.ts` | register 新增路由 |
| `web/plugins.html` | **新增**：用户=published 库卡片多选+启用/禁用+确认弹窗（含"将重启实例"）；admin=审查区（状态/报告/发布/打回）+库管理+矩阵 |
| `web/desktop.html` | 加「插件选择」入口 + 面板内提示"装新插件到插件选择页" |
| `web/login.html` / `admin.html` | 入口（admin 视图） |
| `lib/**` | `npm run build`（tsc） |
| 文档 | 本档案 + `03-路线图与待办.md` 登记；双端同步 |
## 七、关键机制与约束
1. **installed/enabled 两态分离**：install=复制+chown+bundles；enable=enabled 集（DB）+ relaunch；disable=移除 enabled 集 + relaunch（副本保留）。
2. **relaunch 语义**：只重算 patch（enabled∩installed ∩ 已装过滤同 launch route）并带新 patch 重启，不落库不改 profile 配置；复用既有 spawn/waitForLaunchToken 流程。
3. **chown 纪律**：复制后 chown 用户 uid/gid（先顶层再子项，档案 11 教训）；共享库/审查区 root 600；检测全程只读。
4. **确认弹窗必含**：插件清单 + "将安装到你的个人配置并重启你的 dsh 实例，当前会话可能中断"。
5. **并发写锁**：按用户 id 单写锁（install/enable/disable 串行化）；launch 与 relaunch 天然互斥（mains 检查）。
6. **重启中状态**：relaunch 期间页面置"重启中"，防"未重启仍见旧 bundle"误判（poc v0.4.3）。
7. **红线补充**：**不写/不改 profile 既有 `cordis.patch.yml`（role patch，ensure-role-profile-patch.cjs 管理）**；不动官方 bundle 与 dsh 主程序缓存；不自动升级 dsh。
## 八、验证清单
**API（curl）**
- [ ] 无 sid → 401；用户访问 admin 接口 → 403
- [ ] admin 上传 → under_review；用户 GET library 不含该包
- [ ] 恶意包：`..` 成员/@deepseek-ai/install 脚本 → P0 拒收；exec 动态串 → P1 → release 409 has_blockers；needs_fix 报告可查
- [ ] 多用户包：硬编码绝对路径（M1）/写 profile 外共享文件（M4）→ 命中打回
- [ ] 改造重传 v+1 → 复检 → release → published → 用户 library 出现（reviewedAt）
- [ ] 同名同版本 release → 409 version-conflict
- [ ] enable 单/多：安装副本入 profile（chown 正确）+ bundles 追加 + enabled 集写入 + relaunch；`restarted:true`
- [ ] 未装包 enable = 自动先 install；重复 enable → 409 already_enabled；disable → 集移除 + relaunch；再 enable 免复制
- [ ] OQ2 dry-run：复制式安装后 listInstalledPlugins 可见、relaunch 后入口生效；不符 → 切 CLI fallback 并记录
- [ ] 报告落盘 pluginReviewDir root 600；删除已发布包后已装用户不受影响
- [ ] 回归：`GET /api/plugins` 与 `/api/plugins/select`（桌面在用）行为不变；profile cordis.patch.yml 未被改写
**UI（浏览器，admin + 用户）**
- [ ] 用户：选择页仅 published 卡片（未安装/已安装/已启用角标）→ 多选 2 → 启用 → 弹窗文案正确 → relaunch → 工作台两插件入口出现（bundle rev 对比）
- [ ] 禁用 → relaunch → 入口消失；桌面「插件」面板勾选仍可用（下次 launch 生效）
- [ ] admin：上传 → 审查状态流转 → 报告 → 发布 → 用户端可见；矩阵正确
- [ ] 回归：技能管理面（档案 11）不受影响；官方 @deepseek-ai/* 任何视图不出现
## 九、风险
| 级别 | 风险 | 缓解 |
|---|---|---|
| P1 | relaunch 打断当前会话（单活跃实例） | 弹窗强提示 + 确认；relaunch 复用既有 spawn 流程，失败自动回退（watchdog 机制兜底） |
| P1 | 复制式安装与 profile 的 pnpm/dsh 安装逻辑冲突（手放目录被清/不可解析） | OQ2 dry-run 先行；不符即切 `dsh plugin add` CLI fallback |
| P1 | 静态检测为启发式，无法证明绝对安全/绝对多用户 | 人工复核必选终审 + 来源明确 + 报告留痕；沙箱试运行列为增强 |
| P2 | 与桌面既有插件面板/官方会话设置双 UI | 定位分工 + 页面互链提示；验证项补查官方会话设置 |
| P2 | 用户装多个大插件占 profile 空间 | 库卡片展示体积；副本体积纳入 admin 矩阵 |
| P2 | 审查放行依赖人工复核效率 | 自动覆盖硬规则（S1-S4/S8、M4/M5），人工只复核启发式项 |
## 十、红线遵守
不自动升级 dsh；不改官方主程序与缓存（只操作 plugin-library/plugin-reviews + 用户 profile 层）；拒绝 `@deepseek-ai/*` 入库；上传包不执行任何脚本；**不改 profile 既有 cordis.patch.yml（role patch）与 ensure-role-profile-patch.cjs 产物**；共享库/审查区 root 600。
归档/dsh-server-docs-清理-20260924/接续包_覆盖网络线_20260916.md
+66
View File
@@ -0,0 +1,66 @@
# 接续包 · 覆盖网络线 · 2026-09-16 18:3x（**v3**）
> **用法**：新会话**只读这一份** —— ⛔ 不许先 Glob/Grep 全库摸底、⛔ 不许"再确认一下待办"。
> **v3 改了什么**：① 上次自动接续（17:03）**跑了 9 次调用 / 1.5 分钟 / 零产物** ⇒ **「下一步」已从"两件事混装"改成单一机械动作**（根因见「给下一棒」）；② 全文压到 3KB 内；③ 传输选型结论已更新（**撤销"首选 frp"**）。
## 接续点 · 覆盖网络线 · 2026-09-16 18:3x
- **来源会话**：`408636f2`（覆盖网络线：规划复核 → 落地执行 → 收口）｜ **结束原因**：水位 **42 万**强制收口
- **原目标**（用户原话）：①「查看覆盖网络任务的相关文档，规划落地步骤方案，检查方案确认有误调整，准备执行」②「有稳定可行的落地步骤方案了吗，确认是最佳落地方式就开始执行，保证每一步完成后项目都保持可用，逐步交付」③「覆盖网络的功能开发完成了吗」④「重新创建接续会话 看看是否有改善」
- **基线**：HEAD=`640813e` ｜ 远端 master=`640813e`（15:0x 实测，**未复验**）｜ 全局锁=**已释放** ｜ ⚠️ 工作区 **13 改 + 1 新增**，**未 commit（未授权）**
- **产物**：
1. `交接单_覆盖网络落地执行_20260916.md` —— **§8 = P1/P2/P3 执行记录 + 全部实测证据**
2. `覆盖网络_传输方案取舍_开放端口与自研relay_20260916.md` —— §7 成熟件对照 ／ **§8 撤销 frp + 六条判据 + R0**
3. `会合中继拆分_取证与改造方案_20260916.md` —— §9 第二轮勘误
4. 技能 `dsh-decision-method` **v2.8.0**（新增 §4.6 选型判据轴；三副本 md5 一致）
- **校验命令**（只读、≤30s）：
```bash
ssh [email protected] 'md5sum /opt/dshs/lib/supervisor/spawn.js; grep INSTANCE_PORT /etc/dshs-worker.env; PGPASSWORD=dshs_cluster_2026 psql -h 127.0.0.1 -p 15432 -U dshs -d dshs -At -c "select id,via from dsh_hosts order by id"'
```
**期望**：`e75427d06fa94cadac800e1570cec273` ＋ `DSHS_INSTANCE_PORT_BASE=20000` / `SPAN=1000` ＋ `w-106|manager-ssh`、`w-47|local`。**不符 ⇒ 停下只报告，⛔ 不许照文字硬做。**
## 给下一棒（⛔ 先读这段：上次为什么零产物）
上次（17:03）自动化会话 **9 次调用 / 1.5 分钟 / 零产物**。根因 = **旧「下一步」把两件事（补判据表 ＋ 测链路画像）混成一句话，且没给可交付的产物路径** ⇒ 会话做完开机四步就无从下手。**本次已改成单一机械动作（见下），照做即可闭合。**
## 下一步（**唯一动作 = R0-b 链路画像测量**，全程只读）
**要产出**：本机 ↔ 47 ↔ 106 的 **RTT / jitter / 带宽**实测，写进 `覆盖网络_传输方案取舍_开放端口与自研relay_20260916.md` 的新 **§9**（含命令原文 + 数字）。
命令骨架：
1. 本机 → 47 / 106：`ping -n 20 <ip>`（jitter 取 `mdev` 或手算标准差）
2. 下载带宽：`curl -o /dev/null -w '%{speed_download}\n' http://<47或106>/<一个 ~50MB 文件>`（无现成文件就先在 47 临时生成，用完删）
3. 47 ↔ 106 互联：在 47 上 `ping -c 20 106.54.21.172` ＋ 同样方式测一次 TCP 吞吐
4. 记 **NAT / 公网可达性**结论：从本机能否直连 106 的 19000（决定"打洞"可行性）
⛔ 只做测量 + 写 §9；**不装任何 relay、不改配置、不开端口**。**工具调用 ≤ 8 次**。
## 未完成
1. **R0-b 链路画像** ← **= 下一步，唯一动作**
2. **R0-a 判据打分表**（把 §8.2 那六条补成可打分版）→ 排 R0-b 之后
3. **功能本体 0/3**：presence ／ 游戏服放 L1 ／ 块级内容寻址 —— 一个都没开工
4. **S5（443/TCP 兜底）** 未做；**relay 实现未定**（P4 SSH 版判不做）
5. **本机（客户端类型节点）三项验证** 未做
6. **未 commit**（13 改 + 1 新增；红线：未授权不得 commit/push）
7. ⏳ 待用户裁决：「自动接续」通道留不留（18:2x 已问，**未答**）
## 关键决定（勿推翻）
1. **S3 不回环别名、不 `portMap`** —— 实测被 sshd 静默改写；改用**实例端口区间隔离**（`w-47`=20000+ / `w-106`=21000+，避开 OS 临时段 32768-60999）—— **已上线**
2. **S2 只加 `via`**（不加 `address`）；`via` 省略时 `COALESCE` 不覆盖旧值；回填 `w-47=local` / `w-106=manager-ssh`
3. `proxy.ts:109` = **发给上游 dsh 的 `Host` 头**，⛔ 永不可改（连接目标 `:136-137`）
4. **控制面已在 PG** ⇒ 不存在"改造为 PG"
5. **worker 永远只拨出、不开入站端口**；**relay 实现未定**（撤销 frp：`CVE-2026-40910` 影响 ≥0.53.0 / dashboard 默认弱口令 / **`proxyBindAddr` 默认绑公网** / 单一静态 token + frpc 明文存 / 服务端默认不强制 TLS）
6. ⛔ **P4（SSH 版中继 + 新开 32023）判不做**
## 回滚点
- **P1**：`/opt/dsh/backups/lib-pre-S0-20260916-1555.tgz` → `systemctl stop dshs` → 还原 `lib` → `start dshs`
- **P2**：`via` 列有默认值 ⇒ 旧代码读 `endpoint` 不受影响，**列可留着不删**
- **P3**：删 `/etc/dshs-worker.env` 的 `DSHS_INSTANCE_PORT_BASE/SPAN` ⇒ 回 `listen(0)`（**零代码回滚**）
## ⛔ 不要重做
**P1（47 对齐 `640813e`）／ P2（`via` 列 + 回填）／ P3（端口区间隔离）均已完成并验收** —— 证据在交接单 §8。
**也不要**再论证「S3 用回环别名」（已实测证伪）、「需要改造为 PG」（已经是 PG）、「首选 frp」（已撤销）。