76 lines
7.7 KiB
Markdown
76 lines
7.7 KiB
Markdown
---
|
||
name: dsh-local-env
|
||
description: 「**在 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 档）**。
|
||
version: 1.0.0
|
||
updated_at: 2026-09-28
|
||
last_change: 【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 行，文档库的"设计红线/自检"是其真子集）⇒ 取**本机版**。⛔ 未删任何判据。
|
||
agent_created: 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 插件做真跑验证）。
|
||
|
||
🔴 **三条必须先知道的判断**：
|
||
1. **Node 22**（版本不对会以各种"像工程问题"的方式失败）；
|
||
2. 🔴 **「监听 ≠ 就绪」** —— 端口在听 **不代表** 实例能服务（实测：监听起来了但仍是 401/白屏）⇒ 判据必须做到"**能取到 200**"这一层；
|
||
3. 🔴 **判据写窄＝假红** —— 会把**本来正确的产品行为**判成故障，然后你去改对的东西。⚠️ 同类：**陈旧写锁**会让实例**永久起不来**。
|
||
|
||
**依赖安装**：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（本机为超集）⇒ 已按**本机版**定稿，⛔ 别用旧副本反向覆盖。
|