dsh_shenxian/dsh-server-docs/08-skills/dsh-env-bootstrap/SKILL.md

---
name: dsh-env-bootstrap
description: DSH 平台项目的「环境引导 / 搬迁」技能 —— 把**工作区常驻规则**（`CODEBUDDY.md` 的关键章节）带走，并在新电脑 / 新工作区路径下**校验与注入**，同时自检环境相关项（绝对路径、hooks 命令、代码仓、备份目录）。当用户说「换电脑了」「改了工作区路径」「迁移到新环境」「规则会不会丢」「新环境还没配好」时使用。
version: 1.0.0
updated_at: 2026-09-15
last_change: 【2026-09-22 按要求统一版本号】frontmatter `version` → `1.0.0`（原 v1.0.4）；正文与历史中的版本号为当时记录，未改动。
agent_created: true
---

# dsh-env-bootstrap — 环境引导（常驻规则的可移植化）

## 0. 为什么存在

项目规则分两层，**能力恰好互补、缺口也恰在这里**：

| 层 | 载体 | 特点 |
|---|---|---|
| **常驻层（权威）** | 工作区 `CODEBUDDY.md`（每会话自动注入 ⇒ **动作前必然生效**） | 它是**工作区文件** ⇒ **换电脑 / 换路径就没了** |
| **可移植层** | 本技能（用户级 `~/.workbuddy/08-skills/`） | 随技能走，但**不自动注入** |

⇒ 本技能把常驻层的关键章节做成**快照**，并提供 **校验 / 注入 / 环境自检**，让"换环境后规则还在"这件事**可执行、可验证**。

## 1. 命令（脚本 `07-scripts/resident-rules.py`）

```bash
S="<本技能目录>/07-scripts/resident-rules.py"
python3 "$S" --env-check      # ① 环境自检：目录存在性 + hooks 命令里的绝对路径（失效 = 全机 Write/Edit 被拒）
python3 "$S" --check          # ② ★校验：关键规则是否齐备（**默认只报**，rc=1 = 有缺失/漂移）
python3 "$S" --inject --init  # ③ 注入：目标无标记块时**追加**（不动既有内容）；有则在块内替换
python3 "$S" --snapshot       # ④ 规则更新后，由权威 CODEBUDDY.md **重生成**技能内快照（单向）
python3 "$S" --goal <路径>     # 可指定别的目标 CODEBUDDY.md
```

## 2. 换环境的正确顺序（**把"规则齐备"放在第一步**）

1. `--env-check` —— 先看路径 / hooks 是否失效（**hooks 绝对路径失配 = fail-closed：该机所有会话的 Write/Edit 全被拒**，2026-09-13 实测）
2. `--check` —— 关键规则缺失？⇒ `--inject --init` 追加标记块 ⇒ **人工去重**（块外原有内容与新块可能重复）⇒ 复跑 `--check` 直到 rc=0
3. 逐项核对快照文末的 **§待核清单**（服务器 / 备份目录 / 代码仓 / 工作区）—— **环境相关项不自动配、也不假装能配**
4. 规则更新时：改**权威** `CODEBUDDY.md` → `--snapshot` 重生成快照（**方向单向**）

## 3. 设计红线（别把它用成"第二真相源"）

- **权威方向单向**：`CODEBUDDY.md` 是权威，快照是它的副本；**只允许 `--snapshot` 从权威生成副本**，⛔ 不许反向手改快照。
- **默认只报不改**（与文档库「体检只报不改」同规）：`--check` **绝不**改任何文件。
- **注入只动标记块**：`<!-- BEGIN resident-rules … --> … <!-- END resident-rules -->` 之间；**首次不自动注入**（避免同一规则在两处并存）。
- **不假装能自动配环境**：环境相关项只做"存在性检查 + 待核清单"。
- ⚠️ **常驻层不可被"搬走"**：本技能**不替代** `CODEBUDDY.md` —— 规则仍必须常驻在**该环境**的 `CODEBUDDY.md`（否则"动作前必然生效"这条就断了）；技能只是**把规则带过去并防丢**。

## 4. 自检（用完之后问自己）

1. 我改的是**权威**还是**快照**？（改快照 = 造漂移源）
2. `--check` 绿了吗？红的那条是**真缺失**还是我刚改错？
3. 环境相关项核对了吗（hooks 路径 / 代码仓 / 备份目录 / 工作区）？
4. 注入后有没有**人工去重**（块外原内容 vs 新块）？
5. 给用户的报告**能被扫吗**？—— 排版按 `dsh-feature-first §5.4`。