# 变更日志

遵循 [语义化版本](https://semver.org/lang/zh-CN/)：`主版本.次版本.修订号`

- **主版本**：规则格式或目录结构发生不兼容变更（升级需手工迁移）
- **次版本**：新增能力（新流程、新模板、新分层、新的协作机制）
- **修订号**：规则内容与文案修正

---

## [0.26.8] - 2026-10-05

### 发版脚本给出的登录命令会登录到镜像源

**原因**：`scripts/release.ps1` 结尾提示 `npm login`（不带 registry），
而本机 `~/.npmrc` 默认 registry 是国内镜像。

**问题**：照提示执行会**登录到镜像**，随后的发布也落到镜像上 ——
命令"成功"，但 npm 官方源上永远没有这个包。
（与 0.26.7 修的是同一件事的两半：一个改发布目标，一个改登录指引。）

**解决方法**：提示改为 `npm login --registry https://registry.npmjs.org/`，
并注明"必须带 --registry，否则会登录到镜像"。

---

## [0.26.7] - 2026-10-05

### 发布目标指向镜像源，`npm publish` 不会发到 npm

**原因**：本机 `~/.npmrc` 配置为 `registry=https://registry.npmmirror.com`（国内镜像），
`npm publish` 默认使用该配置。

**问题**：`npm publish --dry-run` 显示
`Publishing to https://registry.npmmirror.com` —— 镜像对普通用户是只读的，
即使命令"成功"，包也不会出现在 npm 官方源上，
用户执行 `npx agent-development-constraints` 依然找不到。

**解决方法**：`package.json` 增加

```json
"publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
```

只影响**本包的发布目标**，不改变本机镜像配置（安装仍走镜像，速度不受影响）。
干跑确认：`Publishing to https://registry.npmjs.org/ with tag latest and public access`。

---

## [0.26.6] - 2026-10-05

### 脚本把 CHANGELOG 写成 0 字节

**原因**：用 PowerShell 给 CHANGELOG 插条目时，
`[System.IO.File]::ReadAllText("CHANGELOG.md")` 按**进程 CWD**
（不是 PowerShell 的 `cd` 位置）解析相对路径而抛异常，变量为 null；
而 PowerShell 对非终止性错误**继续执行后续语句**。

**问题**：随后的 `WriteAllText($null)` 把 **654 行的 CHANGELOG 覆盖为 0 字节**。
靠 `git checkout -- CHANGELOG.md` 恢复（内容已提交，无实际损失）。

**解决方法**：
- 新增规则 **R-017**（用变量"读 → 改 → 写回"文件前必须确认非空），
  并在「构建 / 命令 / 环境」症状表中加入「文件被写空 / 内容丢失」
- 教训一并写入规则：PowerShell 里给 .NET API 传路径**一律用绝对路径**
  （`cd` 不改 `[System.IO.*]` 的当前目录）；这类破坏**不受文件版本守卫保护**

---

## [0.26.5] - 2026-10-05

### hooks 命令是「假安装」：装了钩子却不装检查脚本

**原因**：`bin/cli.js` 的 `installHooks()` 只复制 `.githooks/` 并设置
`core.hooksPath`，未复制 `sanitize-check.ps1` / `.sh` 与 `.sanitize-deny.txt`；
而 `pre-commit` 找不到检查脚本时打印提示后 **exit 0**（放行）。

**问题**：在 python2 博客项目上实测 —— `hooks` 报告"✓ git hooks 已启用"，
但每次提交只打印「⚠️ 找不到脱敏检查脚本，跳过」，**一条规则都没执行**。
提交里的凭据不会被拦，而用户以为自动化已生效。

**解决方法**：
- `installHooks()` 一并安装 `scripts/sanitize-check.ps1`、
  `scripts/sanitize-check.sh`、`.sanitize-deny.txt`；
  已存在的一律不覆盖（保留用户按自己项目改过的黑名单）
- 新增测试：断言这 4 个文件必须就位，且钩子里含 `-ExecutionPolicy Bypass`

### 钩子在非 C: 盘上每次提交都被拒

**原因**：`pre-commit` 调用 PowerShell 时未指定执行策略。实测同一份未签名脚本
在 C: 盘可运行，在 F: 盘被按"来源不可信"拦下（实际生效策略为 RemoteSigned）。

**问题**：脚本被拦 → 退出码 1 → 钩子判定"检查不通过" → **每次提交都被拒绝**，
且报错内容是执行策略而非命中的规则，很难定位。

**解决方法**：两处调用加 `-ExecutionPolicy Bypass`（开发钩子的标准做法）。

### 检查脚本读不了文件即崩溃

**原因**：`scripts/sanitize-check.ps1` 用 `[System.IO.File]::ReadAllLines` 直读，
没有异常处理。

**问题**：`-All` 模式扫到 PyInstaller 的 `_MEI` 临时目录（文件被占用）时抛
`Access to the path ... is denied`，整次检查以异常结束 ——
一个与检查无关的文件就能让检查没有结论。

**解决方法**：读取包在 try/catch 中，读不了就跳过并打印提示。

---

## [0.26.4] - 2026-10-05

### 发版脚本被 PowerShell 的 stderr 误判中断

**原因**：`scripts/release.ps1` 开头是 `$ErrorActionPreference = 'Stop'`，
而 `git push` 会把进度写到 **stderr**；PowerShell 在该设置下把原生命令的
stderr 当作 `NativeCommandError` 抛出并中断脚本。
（规则库 `stacks/shell.md` 已记录此类症状：退出码 1，但命令实际成功了。）

**问题**：0.26.3 发版时 `git push origin main` **实际成功**，脚本却报失败并停在
打标签之前 —— 远端 `main` 已更新而标签缺失，分支与标签不一致。

**解决方法**：
- 改为 `$ErrorActionPreference = 'Continue'`；正确性由每步显式
  `$LASTEXITCODE` 判断 + `Fail()` 退出保证；PS 7.3+ 另关闭
  `$PSNativeCommandUseErrorActionPreference`
- 脱敏检查的调用改用 `*>&1`，接住所有输出流
- 补打 `v0.26.3` 标签并推送
- 本次发版（0.26.4）用它真跑一遍，验证修复有效

---

## [0.26.3] - 2026-10-05

### 改动只进了源码，没进宿主实际加载的那一份

**原因**：插件以 `"agent-development-constraints": "file:F:/agent-constraints"`
装入 DSH profile。npm 对 `file:` 依赖是**安装时拷贝一份**（非软链），
之后源码改动不会同步到 `node_modules`；且宿主进程已把旧 `index.mjs` 载入内存。

**问题**：连续 6 个提交（新增 `action=symptom`、注入改成目录、R-013~C-015）
全部提交并推送、源码版本已到 0.26.2，而宿主加载的仍是 **0.24.0** ——
本次会话内所有插件改动实际未生效。用户以
"我都安装插件了 应该更新到插件里了"指出。

**解决方法**：
- 用 `npm pack`（尊重 `package.json` 的 `files` 白名单）重新打包并覆盖
  `~\.dsh\profiles\desktop\node_modules\agent-development-constraints`，
  旧版备份为 `…bak-0.24.0`
- 核对安装态：版本号、`extractSymptomIndex`、`symptom` 动作、
  R-013 ~ R-016 均已存在
- 新增规则 **R-016**（改插件/依赖源码后必须更新安装态副本并重启宿主），
  并把「插件 / 宿主集成」症状表中原本只指向 R-008 的那一行
  改为同时指向 R-016（症状：改了插件/依赖代码但行为没变）
- 交付说明中写明：新插件代码需**重启 DSH** 才加载（本次无法自行重启，
  会话正运行在该宿主内）

---

## [0.26.2] - 2026-10-05

### 变更日志写成叙事文

**原因**：变更日志没有可执行的格式约束。规则库 C-004（记录要沉淀成规则，
不能只写故事）是原则性规定，没有对应的检查。

**问题**：0.25.0 ~ 0.26.1 的条目以叙事结构书写（用户原话、排查经过、自我检讨），
原因机制、可验证后果与具体改法散落在段落中，难以检索与复用。

**解决方法**：
- 0.25.0 ~ 0.26.1 四个条目按「原因 / 问题 / 解决方法」重写；
  该三项之外的补充信息改放引用块，不单开小节
- 新增 `templates/changelog-entry.md`：规定结构、写作要求与反例
- 新增两条测试：0.25.0 起每个 `###` 小节必须含三个要素；
  条目中不得出现叙事化措辞（引用块豁免）
- 已知阳性验证：删掉一处 `**原因**` → 报 `[0.26.1] 安装指令不可用 —— 缺 原因`；
  插入叙事措辞 → 对应测试失败

### 发版脚本未推送主分支

**原因**：`scripts/release.ps1` 只执行 `git push origin <tag>`。

**问题**：打标签后远端 `main` 仍停留在上一个提交，分支内容与标签不一致。

**解决方法**：改为先 `git push origin main`，再推送标签。

---

## [0.26.1] - 2026-10-05

### 安装指令不可用

**原因**：`package.json` 从未发布到 npm（`npm view agent-development-constraints`
返回 404），而 README、插件未安装提示、`bin/cli.js` 注释、`docs/verify-in-dsh.md`
共 12 处给出的是 npm 短形式安装命令；同时仓库只有 `v0.6.0` / `v0.7.0` 两个标签。

**问题**：`npx agent-development-constraints install` 必然失败，
用户照文档装不上插件；GitHub 首页只显示旧版本。

**解决方法**：
- 12 处改用实测可用的 `npx github:962599627/agent-development-constraints <cmd>`；
  README 注明"必须带 `github:` 前缀"及原因
- 新增发布一致性测试：`VERSION` / `package.json` / `CHANGELOG` 首条三处必须一致；
  文档不得出现短形式命令；README 列出的 CLI 子命令必须是 `bin/cli.js` 真支持的；
  所有 `.ps1` 必须带 UTF-8 BOM
- 新增 `scripts/release.ps1` / `scripts/release.sh`：
  测试 → 脱敏 → 三处版本一致性 → 工作区干净 → 打标签并推送 → 打印发布步骤
- 打标签 `v0.26.0` / `v0.26.1` 并推送

### `scripts/release.ps1` 无法执行

**原因**：文件存为无 BOM 的 UTF-8，Windows PowerShell 5.1 对无 BOM 的 `.ps1`
按 ANSI/GBK 读取。

**问题**：中文注释变成乱码，脚本报「字符串缺少终止符」，无法运行。
（规则库 `stacks/shell.md` 已记录此类症状。）

**解决方法**：补 UTF-8 BOM；新增测试要求所有 `.ps1` 带 BOM，
并修掉脚本内部用 `pwsh -File` 调外部脚本的写法（多数 Windows 只有 `powershell.exe`）。

> **仍需账号持有人操作**：`npm login` + `npm publish`（包未发布）；
> GitHub Release 条目需在网页创建（`gh` CLI 未安装，标签已推送）。

---

## [0.26.0] - 2026-10-05

### 规则库缺少可检索入口

**原因**：插件注入的内容是一句「请调用 constraints 工具」，而规则库虽然已有
`## 快速定位 · 按症状查` 目录，但工具没有查询该目录的动作。

**问题**：出问题时无法按症状定位；AI 不主动调用工具时规则完全不生效 ——
实测连续多轮把规则库里已记录的 C-005（面向人的命令不要有长等待循环）踩了一遍。

**解决方法**：
- 注入内容改为**目录**（10 个分类 + 条目数 + 检索提示，149 字符 ≈ 93 tokens，
  每会话一次）
- 新增 `constraints action=symptom`：不带 `q` 返回完整目录；带 `q` 返回命中条目
  **及对应规则全文**；查不到时给出可用分类
- 检索用**字符二元组重合度**（中文无词边界），并把"换个说法也要命中"写成测试
- 新增 5 条测试：目录可解析、paraphrase 命中、命中给全文、未命中不抛错、
  注入体积 < 400 字符且每 agent 只注入一次

### 检索漏命中

**原因**：第一版按空格切词 + 子串匹配。

**问题**：与表内原文措辞不同的查询全部失败，例如
「没反应也不报错」（表内为「没反应、也不报错」，差一个顿号）、
「扫描报0」（表内为「扫描报告"0 处问题"，但实际有」）、
「未登录返回email」（表内为「未登录接口返回 email / username」）。

**解决方法**：改为忽略标点的字符二元组重合度；补齐目录中只有英文写法的条目。

### 注入体积超预算

**原因**：第一版把目录的全部症状逐条注入。

**问题**：1261 字符 ≈ 788 tokens，超过此前被否决的方案（约 280 tokens），
而该消息会进入会话历史并被每轮重发。

**解决方法**：注入改为章级目录（分类 + 计数），细目按需查询 —— 降至 93 tokens。

### 文档与检查器

**原因**：README 的「分四组」未随目录扩充更新；`parameters.enum` 测试钉死了动作清单。

**问题**：README 描述与实际（10 类）不符；新增动作后该测试失败。

**解决方法**：README 中英双份更新为真实分类并补充用法；同步更新 enum 断言。
括号配平检查器不识别正则字面量，改掉两处含引号/反引号的正则写法，
并在检查器旁注明该局限。

---

## [0.25.1] - 2026-10-05

### README 显示过期版本号

**原因**：`README.md` / `README.zh-CN.md` 正文硬编码 `Version: 0.7.0`，
而版本一致性测试只覆盖 `index.mjs` 与 `dsh/client.js`，未覆盖文档。

**问题**：仓库首页长期显示 `0.7.0`，实际版本已到 `0.25.0`。

**解决方法**：README 不再复述版本号，改为指向 `VERSION`；
新增测试扫描 `README*.md` / `CONTRIBUTING.md` / `docs/*.md`（引用块豁免）
中的硬编码版本号。

---

## [0.25.0] - 2026-10-05

### 测试夹具使用生产级密码哈希

**原因**：`settings.py` 未在测试时替换 `PASSWORD_HASHERS`，
而 Django 的 `setup_test_environment()` 不会自动降级
（`PBKDF2 iterations = 1,200,000`，单次 `make_password` 0.250 秒）。
测试用例与登录流程累计产生大量哈希运算。

**问题**：511 个用例耗时 150 秒（对照实验：换用 `MD5PasswordHasher` 后 5.5 秒，
相差 27 倍）。

**解决方法**：`if "test" in sys.argv` 时改用 `MD5PasswordHasher`，
并保留 `KEEP_SLOW_HASHERS` 环境变量以便需要真实哈希时切回；
记入 R-013（含"耗时是某常数整数倍即为哈希/加密成本"的诊断方法）。

### 检测脚本产生假阴性

**原因**：脚本用 `getattr(模型类, 字段)` 取模型字段，得到的是描述符而非
`FileField` 实例；另有非贪婪 `<template>` 截断、混合引号正则、
`{1,80}` 不接受空串、只扫 `<script>` 等问题。

**问题**：泄漏审计报告"0 处问题"，而实测未登录可下载 14.7MB 原片；
其余四处会把在用代码报成死代码。

**解决方法**：字段改用 `model._meta.get_field()`；记入 R-014
（扫描工具须先证明能报出已知问题）。

### 轮播图 HLS 分支从未执行

**原因**：此前轮播图取得的是 mp4，依靠 `<video src>` 与 `autoplay` 属性播放，
HLS 分支无执行机会；改为 HLS 后该分支首次运行。

**问题**：暴露三个缺陷 —— `ref="el => …"` 漏写冒号（函数 ref 未执行，无任何报错）、
自定义 `xhrSetup` 强制 `responseType="text"` 并重写 `xhr.send`、
缺"引用未变就返回"守卫导致 `Maximum recursive updates exceeded`。

**解决方法**：改为 `:ref`；删除 `xhrSetup`；按 `Home.vue` 补守卫。
记入 R-015（改数据源会激活从未执行的分支；「没反应且无报错」≈ 代码未执行）。

### 用户判断优先于环境假设

**原因**：把 150 秒的全量测试视为正常，未做测量；对比实验可一步定位。

**问题**：连续多轮把等待成本转嫁给用户，且两次运行超时被中断、未取得结果。

**解决方法**：记入 C-015（用户报慢/卡/没反应时先测量，不要先归因于环境差异）。

## [0.24.0] - 2026-10-05

### 新增：C-014「空」必须被解释 —— 一条用五个版本换来的 L1 规则

**这是这一轮最贵的一个教训**：一个症状，五个版本，五次误判，占用用户多次重启；
**而真正的修法只有十几行**。

**事情的经过**：设置页卡片的「上下文占用」区一直不显示。

| # | 我的判断 | 真相 |
|---|---|---|
| 1 | 浏览器缓存了旧 bundle | ❌ |
| 2 | 必须完全退出 DSH 进程 | ❌ |
| 3 | host 缓存有时序缺口 | ⚠️ 真实缺陷，但不是主因 |
| 4 | HTTP 响应被缓存 | ⚠️ 真实缺陷，但不是主因 |
| 5 | 重试窗口太短（15 秒） | ⚠️ 真实缺陷，但不是主因 |

**真因**：占用数据由 host 在**第一个 `agent/pre-step`**（= 用户发出第一条消息）
时才产生。用户在发消息**之前**打开设置页看到空白 —— **那完全正确**。

**但卡片把"正在等待会话开始"和"出错了"显示成了同一个空白。**
于是用户以为坏了（截图来问），我也以为坏了（追了五轮）。

**最后是用户一句"是不是还没发消息时截的图"结束了它。**

**据此新增 L1**：

| 规则 | 内容 |
|---|---|
| **C-014** | **「空」必须被解释。** 任何在正常情况下会显示为空的界面都必须区分三种状态：**还没有**（正常等待）/ **取不到**（异常）/ **有但就是空**。等待态要说明：在等什么、怎么才会不空、还在不在努力。技术细节默认折叠。最坏的写法是「暂无数据」——它把三种状态全盖住了 |

**C-012 / C-013 / C-014 是一族**：

```
C-012  别被"印象"骗   —— 去拿数据
C-013  别被"成功"骗   —— 没报错 ≠ 拿全了
C-014  别被"空白"骗   —— 空 ≠ 坏了
```

**同期改动（卡片体验）**：

- 等待态给人话：「⏳ 等待本会话的第一条消息…（已重试 N 次 · 最近一次 HH:mm:ss）」
- 故障态给警示，并与"长时间未取到"分开
- 技术诊断（version / cwd / cwdSource / hasAudit）收进可折叠的「技术诊断」按钮
- 重试策略改为**数据齐备前不放弃**（间隔 1.5s → 10s），因为"用户何时发第一条消息"不可预知

**测试**：20/20 通过。

### 关于本文件本身的漂移（值得记一句）

写 0.17.0 条目时，我在 **commit message 里随手写了 `v0.18.0`**，而真实版本是 `0.17.0`。
三处数据源都对，只有提交信息是错的 —— **而没有任何机制能发现它**。
这正是 R-011 扩写里那句"**测试管不到的地方，就是最容易漂移的地方**"的来源。

---

## [0.17.0] - 2026-10-05

### 新增：跨会话用量统计 + 一条关于「静默的部分成功」的 L1 规则

> 说明：0.11.0 ~ 0.16.0 是同日连续迭代（成本感知、卡片、条形图、版本号修复等），
> 未逐版记录。可在 `git log` 查看；本条只记这一轮最有价值的改动。

**起因**：`cost(action="disable")` 的判据是**只看当前会话**。
于是"我这个会话恰好没调 SSH"会被判成"你不需要 SSH" ——
**用样本代替总体**，会建议用户关掉真正在用的东西。

**实测确认了这个误报确实存在**：

```
当前会话：某些工具 0 次调用          -> 被判为"没用过"
跨会话：  它们在历史里被调用了 20+ 次 -> 完全不该关
```

**改成跨会话**（最近 8 个会话 / 14 天内）；读不到历史时**降级**为当前会话，
并在输出里**明确标注用的是哪个判据** —— 不让调用者以为结论可比。

### 中间踩到一个静默失败的坑，值得单独记

会话文件是**流式追加**的，内部是**多个 zstd frame 串接**
（实测 648 KB 里有 20+ 个 frame，起点在 `0, 212, 537, 1879, ...`）。
而 `zstdDecompressSync` **只解第一个 frame**。

**后果很有迷惑性**：

```
1.5 MB 的会话文件  ->  只解出「一行会话头」
                   ->  看起来像「这个会话没有任何工具调用」
                   ->  没有任何异常、没有任何警告
```

**如果没识破，disable 会得出与事实完全相反的结论。**
解法：扫描 zstd magic（`28 B5 2F FD`）找出所有 frame 起点，
逐段解压再拼接；坏帧只计数不抛错。

**据此新增 L1**：

| 规则 | 内容 |
|---|---|
| **C-013** | **静默的部分成功：没报错 != 拿全了。** 流式/分块/多帧/分页的读取必须独立核对完整性指标；结果异常小时第一反应应是"我是不是只拿到一部分"，而不是"数据本来就这么小" |

**C-013 与 C-012 是一对**：C-012 说"别靠印象，去拿数据"，
C-013 补上下半句"**拿到数据后还要确认它没缺页**"。

**同期改动**：

- `decompressSessionFile()` —— 多 frame 解压
- `listSessionFiles()` / `analyzeRecentSessions()` —— 跨会话统计
- 卡片的占用数据**同步改用跨会话判据** ——
  否则卡片标红而 `disable` 不列它，同一个插件给出两个矛盾结论
- 成本：5 个会话约 450 ms，只在 `pre-step` 首次与工具调用时跑，不进热路径

**测试**：20/20 通过。

---

## [0.10.0] - 2026-10-05

### 新增：设置页配置卡片 + 两条关于「成本」和「排查」的 L1 规则

**起因（两件独立的事）**：

**① 用户装了插件，却在设置里找不到它。**
查明 dsh 0.1.7 起插件配置卡片在**设置页**，通过 `settings.section` 这个 slot
注册（字段照 `@linxin666/dsh-web-all` 的用法：`{ name, id, order, label }`）。
我最初照 `modlens` 挂到了 `plugins.bundle.config`（插件列表页）—— **判断错了**：
照抄工作正常的插件没错，但**必须先确认那个插件和我要做的是不是同一件事**。

于是新增 `dsh/client.js`（手写 lazy-CJS bundle，**无需构建**）+
Host 侧状态路由 `GET /agent-development-constraints/status`。
现在设置页左侧会出现「开发约束」，显示版本、规则库位置、会话目录、注入开关。

**② 用户问"这个插件会不会造成 token 大量消耗"。**
**问得非常好 —— 量化后发现一个致命的成本结构问题**：

- 工具 description 随**每个请求**发送（常驻成本）
- **注入的消息会进入 session 历史，之后每一轮都要重发它**

而最初的注入实现**每步写 454 字符、还列出全部 12 条 L0 铁律标题**：

```
一个 turn 有 5 步 → 5 条注入进历史 → 之后每轮重发
```

**结果**：信息量没变，成本却是"每轮订阅制"。
改为「**一句话指路 + 每会话只注入一次**」（`WeakSet` 去重）后，
**284 tokens → 41 tokens**，且从"每步"变成"每会话一次"。

> ⚠️ 最反直觉的一点：**当初列全部铁律是出于好意**（"让 AI 一眼看到约束"）。
> 好心反而制造了成本 —— **"信息更全"不等于"设计更好"**。

**据此新增两条 L1**：

| 规则 | 内容 |
|---|---|
| **C-011** | 常驻成本要算总账：能按需就别常驻。写进上下文 = 订阅制，按需查询 = 按次付费 |
| **C-012** | 给数据打报告，不要凭印象。同一个现象凭代码推测三次全错，写探针一次定位 |

**C-011 的证据**：本次注入优化（284 → 41 tokens）。
**C-012 的证据**：本次插件排查 —— 先怪 import、再怪 pre-step、再怪 ctx.inject，
**三次全错**；第四次写探针，一次拿到真相（`ctxKeys: ["on"]`，即 `ctx.tools` 不存在）。

**同期修复**（均为实测驱动，不再是推测）：

- **会话崩溃**（`Cannot read properties of undefined (reading 'kind')`）：
  根因是 `pre-step` 处理器"原样透传" `next()` 的结果，而返回值可能是 `undefined`。
  **"原样透传"听起来最保守，实际是把上游的空值往下游传了** → 已摘除该注入。
- **插件加载但工具不出现**：我自己删掉了 `export const inject = ['tools']`，
  且用 try/catch 静默跳过注册 —— **失败静默 = 把最难查的问题留给自己**。
- **`pnpm add file:` 不更新已装包**（把本地路径当依赖链接，不复制内容）。

**测试**：15 个用例（含"零外部依赖""只允许监听 agent/pre-step"
"pre-step 必须原样返回、绝不改写"等事故防线）。

---

## [0.9.0] - 2026-10-05

### 新增：DSH 插件形态 + 两条从真实事故中来的 L1 规则

**起因**：让这个工具能上 DSH 插件市场（`awesome-dsh-plugin`），
于是把它从「指令包 + CLI」改造成真正的 DSH 插件（`dsh.bundle` + `cordis.patch.yml`）。

**改造过程本身出了事故，值得完整记录**：

第一版插件装进真实 DSH 后，**直接让宿主会话崩溃**
（`Cannot read properties of undefined (reading 'kind')`），使用者只能手动禁用。
两个根因：

1. **顶层 import 了装不上的包** —— `@deepseek-ai/dsh-tools` 声明在 `peerDependencies`，
   而目标 profile 设了 `autoInstallPeers: false`，peer 依赖根本不会被安装。
2. **参数 schema 格式错误** —— 用了 `defineTool` 的 DSL，而手写的 `ToolDefinition`
   必须是 JSON Schema。

**更值得记的是为什么测试没挡住**：测试自己造了那个包的 stub，
于是 **11 个用例全绿**，而真实环境里根本没有它。
**假依赖掩盖了真实的环境问题** —— 当时的全绿是有害的。

据此新增：

| 规则 | 内容 |
|---|---|
| **C-009** | 装进别人运行环境的代码，任何失败都只能降级，绝不能把宿主拖垮 |
| **C-010** | 假依赖会掩盖真实的环境问题 |

以及 L2 新文件 [`core/stacks/dsh-plugin.md`](core/stacks/dsh-plugin.md) ——
DSH 插件开发的 7 个坑（宿主崩溃 / 加载 / 参数格式 / cwd / 注入 / 热替换 / 交付前自查），
每条都带「症状」。

**插件实现的关键取舍**：
- **零外部依赖**：只 import `node:` 内置模块，任何人装上都不会因解析失败而崩
- **`apply()` 全程 try/catch**：任何异常只让插件降级
- **`pre-step` 只做最小介入**：`kind !== 'enter'` 时原样透传，不改写宿主的决定

**测试**：16 个用例，其中 5 条是"绝不崩"防线 ——
包括"不得有 `node:` 以外的 import"这条静态检查，以及 5 种畸形 `ctx`
与 6 种畸形 `next()` 返回值下都必须只降级不抛错。

---

## [0.7.0] - 2026-04-25

### 新增：可 npx 安装的 npm 包

**起因**：使用者在 GitHub 的「包」页面看到空白，问「还是空的」。

先厘清了三个概念：

| 区域 | 是什么 | 需要吗 |
|---|---|---|
| **Releases** | 版本化下载包 | 需要 |
| **Packages** | npm / pip / Docker 那种 registry | **本版本做了** |
| **Use this template** | 一键生成自己的仓库 | 仍然最推荐 |

**做成 npm 包的好处**：把安装从「clone → 找脚本 → 传路径」变成**一行**：

```bash
npx agent-development-constraints install
```

**新增文件**

- `package.json` —— 包元数据；`files` 白名单只含真正需要分发的东西（32 个文件 / 72 kB）
- `bin/cli.js` —— CLI 入口，命令：`install` / `check` / `contribute` / `hooks` / `version` / `help`

**设计原则：CLI 只做转交，不重新实现逻辑** ——
否则 npx 版和 clone 版的行为会慢慢分叉。唯一例外是 `hooks`：
安装脚本以"自身位置"找仓库根，在 npx 场景下那是 **npm 缓存目录**，
所以 `hooks` 必须在**目标项目**里自己实现。

**实测验证**

| 场景 | 结果 |
|---|---|
| `node bin/cli.js version` / `help` | ✓ |
| `install` 到临时项目 | ✓ 装出完整结构（含 core/stacks/ 6 个文件） |
| `hooks` 到临时项目 | ✓ 写入**目标项目**的 .githooks，而非缓存目录 |
| `npm pack --dry-run` | ✓ 32 个文件 / 72.1 kB，内容完整 |

**过程中修掉两个 bug**

1. **CLI 找错脚本位置**：`install`/`contribute` 在**包根目录**，
   而 `sanitize-check`/`install-hooks` 在 `scripts/` 下 ——
   我一开始统一按 `scripts/` 找，install 直接报"找不到"
2. **`package.json` 的 `files` 漏了 4 个根目录脚本** ——
   发布出去的包会缺少 install/contribute，**别人根本装不上**

> 第 2 个尤其值得记：`npm pack --dry-run` 是**唯一**能在发布前发现这类问题的办法。
> 只看本地文件都在，是发现不了的。

---

## [0.6.0] - 2026-04-25

### 方向纠偏：它是「会学习的学生」，不是「防贼的工具」

**使用者的一句话点破了问题**：

> 我需要的是一个不断学习的学生 而不是一个偷敏感数据的小偷

回头看，0.5.0 造的 `sanitize-check` **姿态完全跑偏**了：
黑名单、扫描、拦截、拒绝提交 —— **全是"不许做什么"**，读起来像在审查使用者。
而本包从一开始要做的，是**从开发中学习的闭环**。

### 新增 `PRIVACY.md`：可验证的硬承诺

不是"我们尊重隐私"这种空话，而是**能自己跑命令验证**的：

| 承诺 | 怎么验证 |
|---|---|
| **零网络** | `grep -rnE 'Invoke-WebRequest\|curl\|HttpClient\|smtp' --include='*.ps1' --include='*.sh' .` → 无输出 |
| **只读仓库内** | 代码里只有 `git ls-files` 与 `\` 下的路径 |
| **不保存 / 缓存 / 自动提交** | 结果只打印终端；`contribute` 只写一个本地文件 |
| **只学模式，不学秘密** | 自检：把规则库整个公开，你会不安吗？ |
| **不锁死你** | 安装幂等；删掉本包，自己的规则照样能用 |

**同时审计确认**：全部脚本**零网络调用**、读取范围**仅限仓库内**。

### 重新定位：学习是内核，脱敏是可选的安全网

- **README（中英）新增「它不会做什么」**，放在显眼位置
- **`sanitize-check` 的语气改了**：
  - 旧：「发现 N 处可能暴露自身安全的信息」（像判决）
  - 新：「提醒：有 N 处内容可能不适合带出去（这是安全网，不是审判）」
- **明确可以删**：删掉 `scripts/`、`.githooks/`、`.sanitize-deny.txt`，
  规则库与三套流程照常工作

### 方向，一句话

```
❌ 防贼：扫描你的东西 → 发现违规 → 拦住你
✅ 学生：从每次踩坑学到一点 → 越用越懂 → 只在你要求时提醒别带错东西
```

---

## [0.5.0] - 2026-04-25

### 新增：强制脱敏检查（每次提交自动运行）

**起因**：使用者提出「更新的时候要脱敏，不能有暴露自身安全的信息」。

这是个**持续性要求** —— 而靠"记得手动检查"必然失效。
本包自己就是证据：准备公开时发现 **31 处项目专名** + 一个把本地路径 `F:\python2`
写进**文件名**的示例文件，全是"当时觉得无所谓"留下的。所以做成了**机制**。

**新增文件**

- **`.sanitize-deny.txt`** —— 脱敏黑名单（正则），覆盖四类：
  | 类别 | 例子 |
  |---|---|
  | 凭据 | 赋值形式的密码/密钥/token、连接串 `scheme://user:pass@`、私钥内容 |
  | **本地路径** | `C:\Users\<本机用户名>`、开发盘符下的项目路径 |
  | 个人信息 | 常见邮箱域、中国大陆手机号 |
  | 项目专名 | 留给使用者追加 |

  支持 `!` 开头的**允许清单**，放过 `your_password` 这类无害占位符。
  ⚠️ 文件本身会公开，所以**只写模式、不写真实值**。

- **`scripts/sanitize-check.ps1` / `.sh`** —— 检查脚本，扫**已跟踪文件**
  （未跟踪的东西还不会被推送出去，这是唯一需要担心的范围），命中即退出码 1
- **`.githooks/pre-commit`** —— 提交前自动检查，**不通过就拒绝提交**
- **`scripts/install-hooks.ps1` / `.sh`** —— 一键启用（`git config core.hooksPath .githooks`）

**新增规则 · L1 · C-008 每次提交前必须过脱敏检查**

**实测验证**（不是写完就交）

| 场景 | 结果 |
|---|---|
| 全量扫描本仓库（23 文件 / 10 条规则） | ✓ 通过 |
| 造含 4 类敏感信息的测试文件 | ✓ **4/4 全部命中** |
| 占位符 `your_password="xxx"` | ✓ 正确放过（不误报） |
| **实际执行 `git commit`** | ✓ **被 hook 拒绝**，指出文件、行号、命中的规则 |

**过程中发现并修掉的漏洞**：黑名单最初只写了英文 `password`，
**实测漏掉了 `数据库密码: "xxx"` 这种中文写法** —— 而这是中文项目最常见的标注方式。
已补上中文规则（`密码|口令|密钥|秘钥|令牌`）。

> 这条漏洞本身就是 C-008 的证据：**检查方法的有效性必须实测，不能想当然**。

### 顺带

- `install.ps1/.sh` 现在会带上脱敏工具；**`.githooks` 复制到目标项目根** ——
  git 只认仓库根的 `.githooks`，放在 `agent-constraints/` 下面**不会生效**
- `pre-commit` 会自动在 `agent-constraints/scripts/` 与 `scripts/` 两处找检查脚本，
  让它**既能当工具包被安装、也能作为本仓库自身**使用

### 一个新的设计模式：把"要求"变成"机制"

用户的原话是「更新的时候要脱敏」。这类要求如果只写进文档，
下次换个人、换个仓库就会失效。本包的转化路径是：

```
一句要求
  ↓ 定义成规则（C-008，含可执行检查）
规则 + 可运行的脚本（sanitize-check）
  ↓ 接到自动执行点（pre-commit hook）
不通过就拒绝提交 —— 不再依赖任何人记得
  ↓ 同时在症状索引里留入口
出问题时也能查到
```

**四层都落地了，要求才真正生效。**

---

### 修复（提交后立刻发现的）

**hook 只检查了第一个文件** —— 一次 13 个文件的提交，hook 报告「检查了 1 个」。

- **原因**：把**多行文件名变量**一次性交给 `pwsh -Path`，
  PowerShell 只收到第一个参数，**后面的文件静默漏检**
- **修复**：改为**逐个文件调用**
- **实测**：造三个文件、把敏感信息放在**第 3 个** →
  前两个「通过」、第三个被抓到、提交被拒 —— 证明每个文件都真的被查了

> 这个 bug 的形状值得记住：**它不报错，只是"少做"**。
> 如果我当时没注意 hook 输出里的文件数，它会一直静默地只检查一个文件 ——
> 而人看到「脱敏检查通过」就会以为安全了。
>
> 教训：**自动化的东西必须验证它"做了多少"，而不只是"有没有报错"**。

---

## [0.4.2] - 2026-04-25

### 变更：为公开仓库做脱敏

准备把仓库从私有改为公开，先清理内容：

- **原项目名 → `某博客项目`**（31 处，分布在 `core/stacks/` 6 个文件与 `core/MERGE.md`）
- **`examples/python2-blog.md` → `examples/case-study-blog.md`** ——
  原名把本地路径 `F:\python2` 暴露在**文件名**里
- 同步更新 README 中对该文件的引用

**为什么不能只改可见性**：`CONTRIBUTING.md` 里已经写明
「项目名可以匿名化 —— 写「某电商后台」就够了」，**而自己却写着真项目名**，前后不一致。
且公开后原项目名会**永久关联到作者**。

### 顺带

- README 版本号同步更新为 `0.4.2`（遵守 **C-007**：改版本号必须同步文档）
- 用 C-007 的检查方法复检了全部 markdown 链接，**4/4 有效**

### 公开时的仓库设置（结论记录在这里，免得以后忘）

| 设置 | 值 | 为什么关键 |
|---|---|---|
| **可见性** | **Public** | 私有 = 没人能用 →「用的人越多越厉害」直接失效 |
| **Template repository** | **勾选** | 别人可 "Use this template" **一键生成干净的仓库**，比下载解压友好得多 |
| **Issues** | **开启** | 这是 `CONTRIBUTING.md` 承诺的贡献入口；关了别人无处可提 |
| Wikis | **不开** | 文档要跟代码放一起才不会漂移（正是 C-007 的教训） |
| Allow squash merging | 开 | 一次贡献通常是一个完整改动，压成一个 commit 历史更清晰 |
| Automatically delete head branches | 开 | 合并后自动清理 |
| Auto-close issues with merged PRs | 开 | 写 `Closes #12` 就自动关 |

**危险区域一律不碰**（禁用分支保护、转让、归档、删除）。

---

## [0.4.1] - 2026-04-25

### 新增规则

**L1 · C-007 改了结构就要回头改文档**

- **规则**：变更目录结构 / 版本号 / 核心概念时，必须同步更新 README 与说明；
  文档里出现的路径必须真实存在
- **触发**：增删顶层文件、拆分模块、改版本号、重命名概念、调整安装流程
- **检查**：把文档里的路径抽出来逐条核对：
  ```bash
  grep -oE '[A-Za-z0-9_./-]+\.(md|sh|ps1)' README.md | sort -u | while read f; do
    [ -e "$f" ] || echo "文档引用了不存在的文件: $f"
  done
  ```
  版本号也要核对 `README.md` 与 `VERSION` 是否一致
- **证据**：本包自己的 README 长期停留在 `0.1.0` —— 版本号、目录结构、L2 描述全部过时，
  而 0.2 / 0.3 两次迭代都没回头改它。**这正是 0.4.0 花时间修正的东西**
- **代价**：文档漂移会让人**照着错的信息操作**，比没有文档更糟

同时把它加进了「快速定位 · 按症状查」表的**构建 / 命令 / 环境**组
（症状：*文档里的路径/版本对不上实际*）——
否则这条规则"查不到"，等于不存在。

### 这一版的特别之处

C-007 是**从修正上一版文档漂移的过程里提炼出来的** ——
一个完整的自我迭代闭环：

```
0.3.0 拆了 stacks/ 但没改 README
   ↓ 0.4.0 发现 README 全是过时内容（因为要做中英双语才回头看）
修正它
   ↓ 顺手问一句：这件事能不能变成下次自动生效的约束？
C-007 诞生（0.4.1）
```

**这正是本包存在的意义**：教训不是记下来就完了，要变成**下次不用重新发现**的东西。

---

## [0.4.0] - 2026-04-25

### 新增：README 中英双语

- **`README.md`** → 改为**英文版**（GitHub 仓库首页默认渲染它，面向国际访客）
- **`README.zh-CN.md`** → 新增**中文版**（完整内容）
- 两个版本顶部互相链接：`**English** | [中文](README.zh-CN.md)`

**为什么英文版放在 `README.md`**：GitHub 首页固定渲染 `README.md`。
本包的**规则内容本身是中文的**（那是给使用者自己看的），
但**项目介绍**应该让国际访客读得懂 —— 所以默认英文、顶部一键切中文。

### 顺带修正 README 里一批过时内容

它们还停留在 0.1.0，属于"文档漂移"：

- 版本号 `0.1.0` → `0.4.0`
- 目录结构缺 `core/stacks/`、`MERGE.md`、`CONTRIBUTING.md`、`contribute.*`、`README.zh-CN.md`
- L2 的描述仍写「技术栈备忘那节」，实际早已拆成 `core/stacks/` 五个文件
- 新增「快速定位 · 按症状查」章节（0.3.0 的核心能力，README 里此前完全没提）
- 「安装后做三件事」的指引更新（指向 `stacks/`，而不是过时的"L2 那节"）
- 设计理念补两条：**安装幂等**、**技术栈坑位按需加载**

### 修复

- `install.ps1` / `install.sh` 未拷贝 `README.zh-CN.md`

> 顺带一提：**这次修正本身就是约束包要解决的问题的一个实例** ——
> 文档过时却没人发现，因为没有机制强制"改了结构就回头改文档"。
> 值得提炼成一条 L1 规则（见下个版本）。

---

## [0.3.0] - 2026-04-25

### 新增：按症状快速定位 + 技术栈坑位库拆分

**要解决的问题**：L2 原本是一节流水账（`Django / DRF / Vue / git / PowerShell / Windows` 混在一起），
找问题时得通读；而且**出问题时人手上拿的是症状（报错原文），不是"我在写哪个语言"**，
按语言分类还得多想一步"该翻哪节"。

**两个改动**

**① `constraints.md` 新增「快速定位 · 按症状查」**（本版本核心）

四组症状表，直接命中：

| 组 | 覆盖 |
|---|---|
| 构建 / 命令 / 环境 | 连接超时、退出码误报、编码乱码、行尾、保留名文件 |
| 测试 | 单跑通过整套失败、大批 403/429、限流不触发 |
| 接口 / 数据 / 安全 | 隐私泄露、参数 500、密码进历史、日期分组 NULL |
| 界面 / 交互 | 按钮误跳转、编辑按钮消失、数字对不上、递归更新 |

每行给出「症状 → 很可能的原因 → 详见（文件 or 规则号）」。

**② L2 拆成 `core/stacks/`（按需加载）**

| 文件 | 覆盖 |
|---|---|
| `python.md` | Python / Django / DRF / simplejwt |
| `javascript.md` | JS / TS / Vue / Vite |
| `shell.md` | PowerShell / bash |
| `git.md` | git / 版本控制 |
| `platform.md` | Windows / MySQL / Docker / Redis |

**设计要点**：AI 平时只读精简的 `constraints.md`；
只在**命中症状索引**或**明确在改某个栈**时才翻具体文件 —— **上下文是稀缺资源**。

**③ 每个坑必须带「症状 → 原因 → 修法 → 来源」**

没有「症状」的条目**不许加** —— 它无法被索引命中，等于不存在。
这一条也写进了 `core/stacks/README.md`。

### 内容扩充

L2 从 5 条一句话备忘，扩充到 **5 个文件、约 40 条带症状的条目**，
覆盖：Django 时区/热重载、DRF 权限覆写/序列化类型、Vue 非法嵌套/key/递归更新、
TS 类型与运行时不一致、PowerShell 四类陷阱、bash 行尾与 `set -e`、
git 传输层与历史、Windows 保留名与提权、MySQL 时区表、Docker 与部署静默降级、Redis 缓存污染。

### 修复

- `install.ps1` / `install.sh` 未拷贝新增的 `core/stacks/` 目录
- 安装后的提示文案仍指向「L2 技术栈那节」（已改为指向 `stacks/` 与症状索引）

---

## [0.2.1] - 2026-04-25

### 新增规则（约束包用自己的一次真实迭代）

把这门工具**自己开发过程中踩的坑**提炼了进去 —— 这是它应有的用法示范。

**L1 新增**

- **C-005 面向人的命令不要有长等待循环**
  给别人跑的命令单次不应可能等待超过约 30 秒；需要重试就丢到后台并主动告知。
  *证据*：推送仓库时写了「重试 6 次 × 每次 sleep 10 秒」的循环，
  网络不稳时数分钟零输出，被误判为卡死，用户连续追问"卡了吗"。
- **C-006 别用"重试 + 长等待"对付网络问题，先分层诊断**
  先分辨应用层还是传输层：`curl --max-time 5` 探 HTTPS →
  通则说明网络没问题、问题在客户端传输层。
  *证据*：`git push` 连续报 `Failed to connect ... port 443`，
  同一时刻 `curl https://github.com` 返回 **200**。

**L2 新增**

- **git · HTTP/2 挂起**：`push`/`fetch` 报连接超时但 `curl` 能通时，
  执行 `git config http.version HTTP/1.1`（实测改完立刻推送成功）
- **PowerShell · 退出码误报**：外部程序把进度写到 stderr 时，
  PowerShell 会令 `$LASTEXITCODE` 变成 1，**即使命令实际成功** ——
  判断成败要看 stdout 的真实结果，不能只信退出码
- **PowerShell · `.ps1` 必须带 UTF-8 BOM**（否则 5.1 按 ANSI 读 → 中文乱码 → 解析失败）
- **PowerShell · 双引号里反引号是转义符**：`` `a `` 会变成 BEL 字符，
  注入路径时会吃掉开头的 `a`（实测：路径变成 `gent-constraints`），路径要用单引号

### 本次迭代的意义

约束库最初的规则是从**别的项目**提炼的；这一次是从**它自己的开发过程**提炼的 ——
说明这个闭环是通的：**任何一次开发（包括维护这个工具本身）都应该产出规则**。

---

## [0.2.0] - 2026-04-25

### 新增：协作进化能力（本版本的核心）

**要解决的问题**：0.1.0 只在**单个项目内**闭环。每个项目各自积累规则、彼此不知道 ——
**"用的人越多越厉害"只是一句口号**，人多不产生任何额外价值。

**解法：独立发现次数（independent sightings）**

一条规则的**可信度**由「有多少个项目**各自独立**踩到同一个坑」决定：

| 独立发现次数 | 层级 |
|---|---|
| 1 | L2 技术栈 / 项目内 |
| 2 | L1 协作约定 |
| **≥ 3** | **L0 铁律** |
| 被 ≥2 个项目证伪 | 降级 / 归档 |

**为什么这样有效**：不是投票，是**独立复现**。
一条规则在一个项目出现可能是个例；在三个独立项目出现，
说明它命中的是**普遍的人性或工具链缺陷**。

### 新增文件

- **`core/MERGE.md`** —— 合并流程（维护者视角）。含四项操作：
  匹配（是否同一违反场景）→ 抽象（抽出上位规则）→ 定级（按独立发现次数）→ 留痕。
  另含**证伪处理**：规则也会过时或误推广。
- **`CONTRIBUTING.md`** —— 贡献指南。三种贡献方式，
  其中「为已有规则补充来源」（+1 独立发现）价值最高。
  含硬性质量标准和常见退回原因。
- **`contribute.ps1` / `contribute.sh`** —— 贡献脚本。
  靠**安装时保存的基线**自动找出「你新增的规则」，导出成不含主库噪音的贡献包。
- **`agent-constraints/.baseline`**（安装时生成）—— 记录安装时的规则 ID 列表。

### 重要设计决策

- **基线只在首次安装时写入，之后永不更新**
  - 若每次安装都刷新，用户自己新增的规则会被当成主库原有内容而**漏报（丢失资产）**
  - 代价是主库升级带来的新规则可能出现在贡献包里 —— 属于可接受的噪音
  - 宁可噪音，不可丢失用户资产
- **贡献包只含新增规则，不含主库原有内容**
  - 否则维护者要在一堆已有规则里挑，合并成本极高
- **规则格式新增「独立发现」与「来源」字段**
  - 「来源」让规则**抗删**：有 3 个来源的规则，没人敢随便删
  - 同时可判断：若三个来源都是同一种技术栈，说明它可能只该待在 L2

### 修复

- `install.ps1` 未拷贝 `VERSION`，导致贡献包显示「基于版本：unknown」
- `install.ps1` 未拷贝新增的 `CONTRIBUTING.md` / `CHANGELOG.md` / `contribute.*`
- `install.ps1` 双引号字符串里的反引号被 PowerShell 当转义符，
  注入路径变成 `gent-constraints`（`` `a `` 被解析成 BEL 字符）→ 改用单引号
- `.ps1` 缺少 BOM：Windows PowerShell 5.1 会按 ANSI 读取 → 中文乱码、脚本解析失败
- `.sh` 行尾统一为 LF（bash 无法执行 CRLF 脚本）

---

## [0.1.0] - 2026-04-25

首次发布。

### 新增

- **`core/constraints.md`** —— 约束库，四层结构：
  - **L0 铁律**（12 条，硬上限 15）：跨项目通用、代价高、每条都有自动化检查方法
  - **L1 协作约定**（4 条）：人机/机机协作规则
  - **L2 技术栈备忘**（5 条）：Django / DRF / simplejwt / Vue / Windows，换项目时整节替换
  - **L3 归档**：保留失效条目的名字，避免同一件事被反复重新发现
- **`core/DISTILL.md`** —— 提炼流程：四步法（收集 → 筛选 → 抽象 → 立卡），
  含可直接使用的提示词，以及"本次未收录"留痕要求
- **`core/PRUNE.md`** —— 精简流程：四项操作（合并 / 降级 / 改写 / 归档），
  含自检清单与精简提示词
- **`templates/rule.md`** —— 单条规则模板（四要素：规则 / 触发 / 检查 / 证据）
- **`templates/session-log.md`** —— 会话记录模板（提炼原料格式，末尾带"要不要提炼"勾选项）
- **`install.ps1` / `install.sh`** —— 幂等安装脚本（Windows / Linux-macOS）

### 设计决策（记录下来，避免以后被"优化"掉）

- **每条规则必须带「证据」**：没有证据，后人精简时会当废纸删掉
- **每条规则必须带「触发」和「检查」**：没有触发 AI 想不起；没有检查无法验证。
  因此明确禁止"注意…""尽量…"这类无法判断是否违反的表述
- **L0 硬上限 15 条**：约束的价值随长度递减，超了 AI 会开始忽略
- **只删"被工具链替代"的，其余降级归档**：归档成本极低，重新发现同一个坑的成本很高
- **安装脚本幂等**：`constraints.md` 是用户积累的资产，重复安装绝不覆盖

### 来源

规则内容由某 Django + Vue 博客项目的一次完整开发会话提炼而来：
项目 `job.md` 已积累 538 行开发记录，但"必须遵守"区长期只有 2 条 ——
大量教训（凭据硬编码、限流污染测试、非法 HTML 嵌套、热重载失效、
并行写入冲突、隐私字段泄露、入口缺失掩盖 bug）只以"故事"形式躺在记录里，没有变成约束。