7.7 KiB
name, description, version, updated_at, last_change, agent_created
| name | description | version | updated_at | last_change | agent_created |
|---|---|---|---|---|---|
| dsh-local-env | 「**在 Windows 本机把官方 dsh 跑起来 / 本机开发环境**」的总入口 —— 覆盖两半：① **本机跑起官方 dsh 并端到端取证**（web 实例 `apps/cli` 的 `dsh` CLI：起实例 / 查回环监听 / token＋cookie jar 取 200 / 探测 Windows 沙箱后端；桌面壳 `apps/desktop`：源码构建、Electron 参数、CDP 真跑取证、**离线可用**验证、自研 client 插件真跑）② **环境引导 / 搬迁 / 改名**（「换电脑了」「改了工作区路径」「迁移到新环境」「规则会不会丢」「新环境还没配好」；以及**改名/搬家后的路径残留清理**）。⚠️ **边界**：本技能管**本机源码/开发态**；「**服务器上**单个用户实例打不开 / OOM / 崩溃重启」⇒ `dsh-diagnose`；「**服务器实例里**插件没 UI / 没生效」⇒ `dsh-diagnose`。核心 = 两形态先选对入口 ＋ **Node 22** ＋ **监听 ≠ 就绪** ＋ **判据写窄＝假红** ＋ 换环境的"**规则齐备优先**"顺序 ＋ **路径残留分类要细到「行」**。判据实体在主干，**全文在 `references/`（2 档）**。 | 1.0.0 | 2026-09-28 | 【2026-09-28】**由 `dsh-desktop-dev-shell`（v1.3.1）＋ `dsh-env-bootstrap`（v1.2.0）合并而成**（两个原名退役）。按 `dsh-knowledge-upkeep §10`「主干 + 详情档」形态：判据实体留主干、全文下沉 `references/`（**内容守恒：逐行 0 丢失**，含原 frontmatter 变更历史）。合并理由：两者都是「**本机环境**」域 —— 一个管"把 dsh 跑起来并取证"，一个管"换环境/改路径后规则与残留"。⚠️ 并按对账结论处置了版本分叉：`desktop-dev-shell` 本机版为**超集**（比文档库多 §11.6–11.8 等 131 行）⇒ 取**本机版**；`env-bootstrap` 本机版为**超集**（多 §3 迁移清理 67 行，文档库的"设计红线/自检"是其真子集）⇒ 取**本机版**。⛔ 未删任何判据。 | true |
dsh-local-env — Windows 本机 dsh 环境总入口
🔴 第 0 步：先分诊
情形 去哪 要在本机跑起 dsh（web 实例 / 桌面壳）并取证 §1 改了插件后界面没变化 / 壳起不来 / pnpm 卡住 §1 换电脑 / 改工作区路径 / 迁移 / 改名 §2 改名后发现还有地方指着旧路径 §2 → 路径残留清理（分类细到「行」） 服务器上实例崩了 / OOM / 插件没 UI ⛔ 不属本技能 ⇒ dsh-diagnose
1. 本机跑起官方 dsh 并取证
先选对入口（两个形态别混）：web 实例（apps/cli 的 dsh CLI）｜桌面壳（apps/desktop，需源码构建，可挂自研 client 插件做真跑验证）。
🔴 三条必须先知道的判断：
- Node 22（版本不对会以各种"像工程问题"的方式失败）；
- 🔴 「监听 ≠ 就绪」 —— 端口在听 不代表 实例能服务（实测：监听起来了但仍是 401/白屏）⇒ 判据必须做到"能取到 200"这一层；
- 🔴 判据写窄＝假红 —— 会把本来正确的产品行为判成故障，然后你去改对的东西。⚠️ 同类：陈旧写锁会让实例永久起不来。
依赖安装：pnpm 在本机"卡在 added ~100"有真根因（不是慢）⇒ 见详情档。
启动：⛔ 不要用 pnpm run dev:desktop；Electron 启动参数与 --no-sandbox 判据见详情档。
改插件后必须重启壳（插件树不热加载）。
真跑取证（怎么拿到硬证据）：用 CDP 连真窗口。⚠️ 选 CDP 目标时 DevTools 自己也是一个 type:'page' ⇒ 别选错。
「离线可用」怎么验：⛔ **别用"没人监听的端口"**造断网（那验不出东西）；要用黑洞服务造"挂起" ＋ 有界超时 ＋ 如实状态。
⚠️ 造假的 ctx 有个必踩的语义坑（假 ctx 与真 ctx 的语义差异 ⇒ 会让你得出错误结论）。
两条本机环境坑：safe-delete 护栏（删 node_modules 前必读）；⚠️ Windows 上 taskkill /F 会被 MSYS 路径改写成 taskkill 'F:/' ⇒ 报"无效参数"。
📂 全文 ⇒ references/00-本机跑起来与取证.md（含两形态完整命令与判据、pnpm 卡安装真根因、Electron 参数实测、CDP 取证配方、离线可用验证、safe-delete 护栏、自研 client bundle 必须 lazy-CJS 封包、真 host 的 RPC 调用（token→cookie ＋ 信封口径）、桌面快捷方式链路）
2. 环境引导 / 搬迁 / 改名后的路径残留
换环境的正确顺序：🔴 把"规则齐备"放在第一步（先确认工作区常驻规则带着走，再谈别的）。
工具：references/dsh-env-bootstrap/resident-rules.py —— --check（校验关键规则齐备，默认只报不改）/ --inject（标记块内替换，首次需 --init）/ --env-check（路径与 hooks 命令自检）/ --snapshot（由权威重生成快照）。
🔴 设计红线：权威方向单向（规则文件为权威，快照为副本）⇒ ⛔ 别把它用成"第二真相源"。
🔴 路径残留清理：分类要细到「行」，⛔ 不能只到「文件」（血的教训）：
- 第一层｜文件分两类：活载体（会被读取并据以行动：状态脚本 / 规则文件头部的路径声明 / 可执行脚本 / 当前工作线入口与接续包）⇒ 改写；历史档案（记录过去某一棒做过什么：日志 · 归档 · tmp · 交付物 · 历史草案）⇒ ⛔ 不动。
- 🔴 第二层（最易漏、代价最大）｜同一个"活载体"文件里，也有不能改的行**：① 「污染源」记录本身（改了就变成"它们写成了正确路径"⇒ 事故记录自毁）②
旧 A → 新 B配对里的 A 侧（改了就成新 → 新，脚本参数变重复）。 - 两类「改不动」的残留：⛔ 别硬改、⛔ 别猜。
- 改名必须同步的「机制层」两处：⛔ 漏了会静默失效。
📂 全文 ⇒ references/01-环境引导与迁移.md（含脚本完整参数、换环境顺序、分类细则与三类"不能改的行"、改不动的残留清单、机制层两处、三条可复跑验收）
📂 快照 ⇒ references/dsh-env-bootstrap/常驻规则-快照.md ｜ 脚本 ⇒ references/dsh-env-bootstrap/resident-rules.py
3. 详情档索引（跨档引用按此表定位）
| 档 | 覆盖的原技能 | 原章节 |
|---|---|---|
references/00-本机跑起来与取证.md |
dsh-desktop-dev-shell（v1.3.1 本机超集版，全文） |
§0 为什么存在 / §1 两形态 / §2 桌面壳三判断 / §3 pnpm 卡安装 / §4 启动 / §5 Electron 参数 / §6 真跑验证 / §7 本机环境坑 / §8 壳里打开不是登录页（不是 bug）/ §9 safe-delete 护栏 / §10 纪律 / §11 web 实例形态（含 §11.6–11.8 本机独有） |
references/01-环境引导与迁移.md |
dsh-env-bootstrap（v1.2.0 本机超集版，全文） |
§0 为什么存在 / §1 命令 / §2 换环境顺序 / §3 迁移·改名后的路径残留清理（含 §3.1–§3.5）/ §4 设计红线 / §5 自检 |
references/dsh-env-bootstrap/ |
原附属档 | 常驻规则-快照.md · resident-rules.py |
🔴 两个原名已退役（dsh-desktop-dev-shell / dsh-env-bootstrap）⇒ 别处见到按本技能对应档读。
⚠️ 边界：本技能管「本机」；服务器侧的实例与插件 ⇒ dsh-diagnose。
⚠️ 已并入的版本分叉：文档库侧旧版比本机少 §11.6–11.8（本机为超集）⇒ 已按本机版定稿，⛔ 别用旧副本反向覆盖。