dsh_shenxian/dsh-server-docs/README.md

dsh 多租户平台 — 改造方案文档库

服务器：47.77.182.89（Alibaba Cloud Linux al8）｜ 平台：dshs + dsh 0.1.2-rc.1（account 硬隔离） 域名：ai1net.com（门户）／<用户名>.ai1net.com（用户实例）｜ 旧域 alotbuy.com 自 2026-09-19 仅作 301 过渡装置（档案 22 / 域名迁移_ai1net_20260919） 服务：systemd dshs（127.0.0.1:3080）｜ 现行状态与部署细节见 DEPLOY-本部署.md

⚠️ 两处 docs/ 勿混（档案 19 §C10）：

• 本仓库（dsh-server-docs）＝ 本项目改造文档（档案 01-53、06-ops/、07-scripts/、09-archive/、08-skills/）；
• 代码仓库（/opt/dshs/docs/）＝ 上游 dshs 自带 7 篇（blueprint / deployment / k8s-deploy …），不要往里写我们的改造记录。 构建/部署/回滚与依赖清单一律看根目录 DEPLOY-本部署.md。

阅读约定（先读这 7 条，避免歧义）

0. 首读 BRIEF.md（现状卡）：30 秒拿到"现在是什么样、该读哪篇"；需要筛档时用 python3 07-scripts/docs-manifest.py（产出机读 docs-manifest.json）。

1. 两套编号互不相同：根级 01/02/03/06 是长期文档（架构、运维、路线图、UI 规范）；04-调整方案/NN- 是一次性改造成档案。说"档案 NN"时默认指后者。

2. 单一来源：清单与状态 = INDEX.md §二；待办与优先级 = 01-规范/03-路线图与待办.md；部署/构建/回滚 = DEPLOY-本部署.md。其余文件提到这些内容时只做指针，不复制（历史上 README/INDEX 各存一份清单，已漂移 —— 见档案 53）。

3. 术语以档案 38b 为准：统一称「功能插件」（早期档案写"业务插件"= 同一事物；历史档案保留原文，不回改）。

4. 域名以 ai1net.com 为准：2026-09-19 由 alotbuy.com 迁入（档案 22 / 09-archive/域名迁移_ai1net_20260919/）。早期档案里的 dsh.alotbuy.com、alotbuy.com 属当时事实，保留原文；现行入口一律 ai1net.com。

5. AI 默认不读：09-archive/（历史全文）、07-scripts/ 06-ops/（工具与配置）、*.bak*、04-调整方案/poc/（源码）—— 需要时再按需打开。

6. 档案头部格式：- 日期： ＋ - 状态：（✅已完成 / 🔄进行中 / ⏸暂缓 / ❌关闭）＋ - 触发：；正文用「需求 → 改动点 → 验证」三段。

模块一览

文件	内容	用途
BRIEF.md	现状卡（AI / 人首读）：现行事实（入口/服务/运行时/隔离/可见面/清理阈值/定时/证书/红线）+ 当前待办 top5 + 高频问题→档案映射 + 4 步读取顺序	先看这份：30 秒对齐现状，再决定读哪篇
01-规范/01-规划与架构.md	背景/现状盘点、总体架构、目录布局、dsh 分层机制、归属矩阵、安全边界（一~五、九章）、架构切换实施记录（十三章）	理解平台怎么搭的、为什么这样隔离
DEPLOY-本部署.md	本部署说明：拓扑/目录/env 键/依赖版本/脚本族/构建部署回滚三步/红线	重建或交接先看这份
01-规范/02-运维手册.md	迁移执行步骤、备份/恢复语义、多用户过渡方案、域名接入、面板反代站点、uid 排障、命令速查（六~八、十二、十四、十五章 + 附录）	日常操作对照查：重启/备份/看 token/改 key 流程
01-规范/03-路线图与待办.md	待验证项结论（Open Questions 已实测）、路线图（已完成/待办）、历史决策记录	追踪未完成事项与优先级
01-规范/06-工作台UI规范.md	前端 UI 强制基线：设计 Token（色/字/圆角/阴影/间距）、布局框架与滚动规则、页面路由、组件规范（按钮/输入/表格/Tab/卡片/徽章/弹窗/Toast/空状态/分页/评分/图标）、关键交互约定、9 条已知坑与规避	开发/改任何前端页面前必读并遵循（门户页 desktop/admin/08-skills/plugins + 工作台页）；权威源 mcn-work-shop/docs/工作台UI规范.md
08-skills/dsh-workflow/	作业流程总入口 skill（v1.0.0）：由 dsh-change-workflow ＋ dsh-auto-handoff-chain 合并（两个原名退役）。两半：① 平台改造六阶段（需求识别→调研→规划→开发→验证→归档）＋ 红线 R1–R11 原文速查 ＋ 并行调度协议（三把锁）② 多棒自动接力（规划棒 ↔ 执行棒 · 六件套 prompt 骨架 · 登记门禁 · 收尾四件套 · 排期两条铁律）。详情已拆到 references/（2 档 ＋ 11 个附属档）。	执行平台改造 / 跑跨会话长任务时对照。⚠️ 红线以本档为准（R1–R11） —— 只到 R8 的是 2026-09-21 之前的旧版。同步方向：工作副本在本机 .workbuddy/skills/，本目录为服务器归档副本 —— 改动后单向推进来（本机 → 此处），勿反向覆盖
08-skills/dsh-decision/	决策总入口 skill（v1.0.0）：由 dsh-decision-method ＋ dsh-feature-first 合并（两个原名退役）。两半：① 决策方法论（判定矩阵 · 「确认最优解」十问 · 验收口径分级 L1–L5 · 技术选型先立判据轴）② 功能优先协作协议（功能卡 4 问 · 9 类自决白名单永不问 · 只准上抛的 3 类 · 上抛语言转换表）。详情已拆到 references/（2 档 ＋ 3 个素材库）。	⛔ 用户点名「决策方法 / 按你的规划 / 别问我 / 自行决策」时必须加载；管「怎么想、怎么定」，落地 ⇒ dsh-workflow。同步方向：工作副本在本机 .workbuddy/skills/，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）
08-skills/dsh-knowledge/	项目知识与架构资产维护 skill（v1.0.0）：由 dsh-knowledge-upkeep ＋ dsh-architecture-lifecycle 合并（两个原名退役）。两半：① 知识库维护与纠偏（六层结构 L0–L5 ＋ 分层判据「实体 vs 指针」 ＋ Lint 四件套 ＋ 漂移 SOP ＋ §9 技能集体检 10 层 ＋ §10 技能重组：主干 + references/）② 过程/定稿分层机制（两个目录的唯一分工判据 ＋ 定稿命名 ＋ 收敛五步 ＋ 冲突仲裁「以定稿为准」＋ 过时档案只加状态块）。详情已拆到 references/（2 档 ＋ 2 个附属档）。	文档与现状不符 / 事实打架 / 定期体检 / 要定稿架构级结论时用。同步方向：工作副本在本机 .workbuddy/skills/，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）
08-skills/agent-operating-rules/	AI 会话作业总规矩 skill（v1.0.0）：跨工作区通用的会话级规则集 —— 上抛唯一判据（边界内自决 / 边界外八类）、回复排版契约（结论先行 · 层级 ≤3 · 每节 ≤7 行 · 待拍板项落最后一节且候选竖排成段）、§2.5 去 AI 味（说话要像人，含语言组织与排版）、工作区归属三律、一把锁纪律、落位·提交·批量红线、交付门禁、多棒自动接力、环境陷阱速查、§10.1 技能要不要合并的判据、§10.2 机制扩面后必须清退绕行方案；重内容已拆到 references/（01 协作与上抛判据 / 02 工作区纪律 / 03 多棒接力编排 / 04 去AI味与说话方式）	任何工作区开工前加载：管「怎么想、怎么说、怎么不越界」，与 dsh-change-workflow（怎么落地）、dsh-decision-method（怎么定案）分工互补。⛔ 本技能零硬编码路径，加载后不读取任何具体工作区文档 ⇒ 不影响其他工作区。同步方向同上（本机 → 此处，勿反向覆盖）
08-skills/dsh-local-env/	本机 dsh 环境总入口 skill（v1.0.0）：由 dsh-desktop-dev-shell ＋ dsh-env-bootstrap 合并（两个原名退役）。两半：① 在 Windows 本机跑起官方 dsh 并取证（web 实例 / 桌面壳两形态 · Node 22 · 「监听 ≠ 就绪」 · 判据写窄＝假红 · CDP 真跑 · 离线可用验证）② 环境引导 / 搬迁 / 改名后的路径残留清理（换环境先保「规则齐备」· 分类要细到「行」· 权威单向）。详情已拆到 references/（2 档 ＋ 2 个附属档）。	⚠️ 边界：本技能管本机；服务器上的实例与插件 ⇒ dsh-diagnose。同步方向：工作副本在本机 .workbuddy/skills/，本目录为服务器归档副本（本机 → 此处，勿反向覆盖）
08-skills/dsh-diagnose/	平台故障诊断总入口 skill（v1.0.0）：由三者合并（dsh-instance-diagnose ＋ dsh-plugin-diagnose ＋ dsh-distributed-state-readback，三个原名已退役）。按症状分三层：① 服务器实例（打不开 / 起不来 / 挂了 / 一直重启 / 503·502 / 内存不够）② 业务插件（没 UI / 装了界面没变化 / GLIBC / 改了还是老行为）③ 跨机状态回流（某字段跨机恒为 false / 状态回不来）。各层第一原则：实例＝先读 journal 再分服务/实例/会话三级；插件＝静默失败当默认假设；跨机＝先判「缺失能力 vs 代码缺陷」。判据实体留在主干，全文已下沉 references/（00 服务器实例故障 / 01 业务插件故障 / 02 跨机状态回流，共 3 档）。	⚠️ 与 dsh-desktop-dev-shell 的边界：本技能管服务器上的实例与插件；「本机 Windows 上把官方 dsh 跑起来」属对方。同步方向同上（本机 → 此处，勿反向覆盖）
08-skills/dsh-opensource-release/	开源导出与版本迭代 skill（v1.0.0）：把私有代码仓导出成可公开的开源副本 —— 脱敏（含"曾用名必须在 LEAK_PROBES 里"的教训：探针只探最老名字会漏中间名）+ 去插件 / 分层授权（LICENSE 原样 ＋ COMMERCIAL-LICENSE.{md,zh-CN.md} 两条平行许可各自成文件，⛔ 不给 AGPL/MIT 附加限制）+ 重写说明文档 + 按 commit 取树避免混入并行会话未提交的改动 + 发布前阻断性探针 + 重内容已拆到 references/（01 保留移除与脱敏口径 / 02 多远端推送 / 03 实测坑 / 04 交互式图示-archify / 05 已知待办与漂移，共 5 档）。	说「开源一份」「导出到 GitHub / CNB」「发新版本」「开源那份同步一下」时用。⚠️ 唯一例外：dsh-univer-office 经特许保留原名。同步方向同上（本机 → 此处，勿反向覆盖）
交接单/	规划会话 → 执行会话的任务单（目标 / 只读前置 / 范围 / 决策点 / 步骤 / 验收 / 回滚 / 回报格式）+ 交接约定	要执行某个任务时才读；单子完成后移入 交接单/
04-调整方案/	每个功能改造一份档案：需求 → 改动文件 → commit → 验证结果	核对用：某功能当时怎么改的
02-架构设计/	已定稿的架构设计（一个目录装全部架构，文件名＝架构名）：当前 = 覆盖网络-顶层架构全貌.md（两图分离 · 三层权威 · 多根与角色升格 · 缺口与推进序）。与 04-调整方案/ 的分工 = 过程 vs 成品：那目录答「为什么这么做」（调研/推演/取证/权衡，会过时），本目录答「现在该做成什么样」（收敛后可施工，不轻易变）；两者冲突以本目录为准	想施工 / 想理解全局时读这份；04-调整方案/ 只用来追根因与看证据
09-archive/	dsh-improvement-plan-20260909-full.md：拆分前的 19 章完整时间线归档	保留历史全文，防拆分遗漏

04-调整方案/ 档案清单：

档案	对应章节	commit
01-launch-token自动携带.md	十六	29c8907
02-安全加固-权限边界与DB.md	十七	—（chmod 操作）
03-统一KEY管理员管控.md	十八	df5cc84
04-删除用户功能.md	十九	4943c8c
06-登录直达会话窗口.md	—（方案 A 第一步落地，v1+v2）	6f63108 + e39628a
07-红线-禁止dsh自动获取最新版本.md	—（红线+升级流程）	生效
08-实例常驻上限与单活跃会话.md	—（回收+last-wins 落地）	928dde1 + 6336c53
09-普通用户隐藏模型设置-角色化profile-patch.md	—（cordis patch disable 裁剪 client 插件，ensure-role-profile-patch.cjs）	—（工具脚本，2026-09-09 落地）
10-共享技能只读部署-bundledSkillDir.md	—（调研分析 + 实施：编排器 env 注入 + 共享只读目录，dsh 全员可见只读技能层）	—（已实施 2026-09-09；管理面见 11）
11-技能管理面-shared+mine-API与页面.md	—（管理面：编排器新增 /api/08-skills/{shared,mine} + /skills.html；v2 = zip-only 两阶段替换：上传检测→同名提示确认→apply 全量替换）	—（已实施 2026-09-09，v2 同日）
12-VoxEMW全云API化接入dsh-调研与M1落地.md	—（外部产品插件化调研 + 云 API 方案：VoxEMW 魔镜 → dsh-plugin-voxemw-cloud）	—（本地插件 v0.1.0 已实现，2026-09-10；云端链路待接线验证）
13-登录直达冷启动竞态404修复.md	—（登录直达冷启动竞态：enter 等 launch token 到位再返回 URL）	fa718d2
14-实例会话敏感信息暴露面审计与加固.md	—（读取→留存→外传链路审计；uid 段收敛 [100000,199999] + nftables 出网护栏封元数据端点/观测外联）	—（已上线 2026-09-10，dsh-egress.service enabled+active）
15-会话失效401未跳登录页修复与guest可见面复核.md	—（三页注入 401 守卫跳 /login.html；核心插件开关收归 admin；guest 可见面复核）	—（已上线 2026-09-10）
16-页面导航定稿-技能插件管理面三决策落地.md	—（已封板：skills.html 两 tab 管公共面 + 插件三层归属模型 + folder_plugins 已废弃；分阶段实施）	🔄 实施中
17-工作区选择器暴露面核查.md	—（会话内「添加工作区」为何能看到 /：bwrap 合成根还原 + 实测可读/可写/跨租户边界；判定 P1 写边界随会话 cwd、P2 picker 无根白名单与 /etc/passwd 泄露；收敛项 H1-H4）	核查完成，收敛待确认
18-目录选择器收敛为仅见自有目录.md	—（已定稿：自建 host 插件子类化 DirectoryPicker seam，根固定 <userRoot>/ws，含 admin；改走 bundle 路由不动用户 patch；PoC 26/26 通过；P0-1/P0-3 待装包重启）	已定稿，待装包重启
19-方案与代码全面审查.md	—（代码 10 项 + 文档 8 项体检：patch 多 owner 冲突 / 含 admin 注入缺口 / 测试缺口 / 01-02-03 滞后 / 2 组重复文件；含优先级批次与决策点）	审查完成，整改待启动
20-崩溃自愈现状核实与加固方案.md	—（订正档案19 §C4：自愈已在（scheduleRestart 1s 退避）；真缺口=重试无上限/无观测/handoff 悬空；方案 A 加固+观测+handoff 决策，不建议启用 enablePatch）	方案A（熔断+观测）+ handoff 停写 已实施；待 live 实测
21-guest会话卡顿排查.md	—（服务端全链路取证：TTFT 1.0–3.5s、实例 TTFB 2ms、nginx 全 <5s、0 崩溃；体感来自客户端侧 + 两个干扰项：生产启用 HMR 每 65s 连 /plugins/events、无关域名流量误入编排器）	排查完成，待拍板 A1/A2
22-服务域名迁移到alotbuy.com.md	—（走 CF 代理切换服务域名：门户 alotbuy.com + 用户 <用户名>.alotbuy.com；签通配证书、CF 真实 IP 还原、旧域名 301 含用户名映射；含 4 个踩坑与回滚）	✅ 已上线
23-实例内AI能力与权限限制核查.md	—（guest 报的 9 条环境限制逐条判定：1 条 P1 真 bug——合成根缺 /bin /sbin /lib 致 dsh 沙箱探针失败 → bash 工具被整体拒绝，已修复待重启；3 条可优化（ffmpeg/python/rg/jq/浏览器）；4 条设计使然；1 条与平台无关）	修复已编译，待重启生效
24-实例侧401自动恢复.md	—（实例重启后旧标签页 token 失效 → dsh 报 dsh web authentication required 死端页；代理补上「实例侧 401 + 浏览器导航 → 302 带最新 token 原地恢复」；与档案 23 沙箱修复同批重启上线）	✅ 已上线
25-实例崩溃循环修复与not_running兜底.md	—（自造事故修复：插件包内 patch 与 profile 层重复 insert 同一 loader id → duplicate loader entry id → 实例崩溃循环（被档案 20 熔断拦住）→ 用户看到裸 {"error":"not_running"}。修：包内改空补丁单点插入 + 浏览器导航永不吐 JSON + 并发进场等待在飞实例 token）	✅ 已修复上线
26-dsh升级耦合点与回归清单.md	—（回答"是否影响官方包/升级会不会覆盖"：官方包零改动（实测无痕迹/无新 mtime）；升级不覆盖我们的改动，但有 6 类契约耦合点需回归：profile 引用的官方 client 行 id、自建插件继承的 seam 基类、client bundle 契约、bwrap 合成根、proxy 401/not_running 假设等）	清单建立
27-MCN工作台插件平台化评估.md	—（MCN 工作台插件能否作为功能插件投放/多用户/存储/自带 DB 风险/技能整合 vs 外置：可行但 3 处 P0 必改（DSH_HOME 路径、技能路径硬编码 13 处、agent preset 随包投放）；技能结论=外置）	评估完成，改造待启动
28-用户数据清理策略.md	—（ws 三档清理（T1 平台产物 / T2 超 90 天顶层脚本 / T3 永不删）+ 会话阈值回收 + 回收站 30 天 + cron；含平台自身污染 bug 的发现与修复）	✅ 已上线

• 单一来源约定（2026-09-11 订正，档案 53）：档案清单与状态的单一来源是 INDEX.md §二；本文件的档案表仅作拆分前（01–26）的历史对照，不再新增行。04-调整方案/README.md 为指针式说明。（此前本文件与 INDEX 各维护一份全量清单 → 已实际漂移，故订正。）

红线（硬性，全部档案同遵守）

1. 禁止启动 dsh 时自动获取最新版本；dsh 版本升级必须先走独立"升级测试→评估→修复"流程再整体更新（详见档案 07）。
2. 不改官方 dsh 主程序与缓存（/usr/local/lib/node_modules/@deepseek-ai/dsh 及依赖）；扩展只走 profile 层官方插件机制（档案 05）。
3. 服务器 docs 只读归档（root 600）；技能同步类红线见各技能 MEMORY 约定。
4. 禁止未经确认的批量 / 全仓写入（2026-09-12 新增，见 R7）：不得对仓库或生产目录做全库遍历改写、通配符重写、批量 chmod/chown、批量换行符转换、cp -r 整目录覆盖；任何可能影响 >10 个文件的操作用前必须先出受影响清单并取得确认。执行过程中发现的额外问题一律"先报告、后动手"，不得顺手改 —— 本机镜像不是沙箱，本机批量改动会经 scp 传导到生产。
5. 中断在线用户的生产变更须先确认（2026-09-12 新增，见 R8）：重启 dshs、drain 实例 scope、批量铺插件、改 MemoryMax/实例 env 等，都会让在线用户掉线；执行前必须先说明「影响谁、断多久」并取得确认，能避开用户活跃时段就避开。

04-调整方案/poc/：PoC 插件源码档案（portal-entry/ = @dsh-local/portal-entry v0.4.3，含 package.json / cordis.patch.yml / lib/{index,client}.js；版本演进：v0.1.0→v0.1.1 行级 inject:[tools]（host 面）、v0.2.0 client 面 exports["./client"] + dsh.client.platform=web、v0.3.0 bundle 内 exports.inject=["slots"]、v0.3.1 package.json dsh.client.inject=["@deepseek-ai/dsh-client-ui-sidebar"]、v0.3.2 list-slot register id+callback 形式、v0.4.0 footer.action 废弃改 settings.section（id:"platform"，与通用设置/模型/插件/Agent预设 同槽）、v0.4.1 删 exports.default（loader ESM interop 取函数 → 无 inject → settings.section 注册失败，浏览器实测根因，红线 3）+ label 函数形式、v0.4.2 尝试 var() fallback 失败（深色主题下 --dsw-alias-label-primary/--dsw-alias-button-elevated-fill 都已定义 #f9fafb，fallback 永不生效，文字/背景同浅色不可见）、v0.4.3 hardcode 修复（文本 #f9fafb、按钮边框 #43464d、打开管理台 #4f6ef7 蓝底白字、退出登录 #ff4d4f 红字透明底；浏览器验收白字蓝底清晰可见——但部署后首次仍见旧 bundle，根因=实例 pid 147068 16:32 启动 vs tgz 16:40 部署未重启，dsh client bundle 在实例启动时打包缓存；重启走编排器 POST /api/dsh/restart（主域 Host+admin sid），新实例 port 37817→45543，bundle rev 259e7a43027c→936d9012841a）；服务器同步副本在 /opt/dsh/docs/04-调整方案/poc/）。

使用约定

• 新增改造：按主题写进对应文件；功能类改造在 04-调整方案/ 新建档案（编号递增，复跑取号勿写死：ls 04-调整方案/ | sort -n | tail -1；63 为空号，勿补占），模板 = 需求 → 改动点表 → 验证结果。
• 01-规范/基线类（跨页面长期生效）→ 根级编号文档（01-规范/06-工作台UI规范.md），不入 04-调整方案/。
• 工作区根批量入仓（2026-09-17）：工作区根尚未入仓的项目文档已一次性归位 —— 16 份方案 / 评估 / 复盘 / 规范类 → 04-调整方案/113–128；13 份交接单 → 交接单/T09–T21；运行态指针（接续入口_* / 接续包_*）→ 当时入 06-ops/（2026-09-23 再归置：两份覆盖网络接续件 ＋ 域名迁移目录 → 09-archive/）；临时与内部简报 → 09-archive/。档案清单仍以 INDEX.md §二 为单一来源（本文件的 01–26 表按上条约定不新增行）。
• 前端页面改动：先读 01-规范/06-工作台UI规范.md 再动手；视觉判断辅以 .workbuddy/08-skills/impeccable（Operate 模式）与 taste-skill（反 AI 味），冲突时以 06 的实测 Token 为准。
• 排障：追加进 01-规范/02-运维手册.md 排障小节。
• 自查：归档/改动文档后跑一次 python3 07-scripts/docs-audit.py（歧义/悬空引用）与 07-scripts/docs-manifest.py（刷新机读清单）（编号冲突 / 标题号不符 / 悬空引用 / 重复 / 体量）——编号冲突与悬空引用会让它退出码非 0。
• 保留原章节编号（如"十六、"）：方便与 archive 完整版对查。
• 同步：本机 D:\github\dsh_shenxian\dsh-server-docs\ ↔ 服务器 /opt/dsh/docs/ 整目录镜像，改完即 scp（服务器侧档案 chmod 600 保持 root-only，README 保持 644）。
• 对账：bash 07-scripts/docs-sync-check.sh（工作区 07-scripts/，2026-09-10 落地）一条命令输出「一致 / 内容不一致 / 仅本地待推送 / 仅服务器待拉取」，退出码 0=全绿；加 --push 一键推送本机变更（档案 600 / README 644 自动设权）。
• 定位：先查 INDEX.md 的场景速查表（编号规则见「阅读约定」第 1 条）。

目录内其他文件（服务器侧）

• nginx-dsh.alotbuy.com.conf.bak-20260908 / .manual-20260908：面板注册前的手写反代配置备份。
• dshs.db.bak-20260908-uidfix：uid 错配修复前的数据库备份（正式备份见 /opt/dsh/backups/）。