# 智能体开发约束包

[English](README.md) | **中文**

一套**会自我进化**的开发约束系统：把开发中踩过的坑，自动沉淀成下次生效的规则。

**当前版本**：见 [`VERSION`](VERSION) · [变更日志](CHANGELOG.md)

> ⚠️ **这里刻意不写版本号。**
> 曾经写的是 `0.7.0`，而 `VERSION` 早就走到 0.25 —— 十几个版本没人同步，
> 用户在仓库首页看到的永远是旧版本。
> 现在版本只有**一个来源**（`VERSION` 文件），README 只负责指过去。
> 仓库测试 `【R-011】` 会扫 README/docs，再出现硬编码版本号就会失败。

---

## 它解决什么问题

大多数项目都有开发记录，但**记录 ≠ 约束**。典型症状：

```
job.md 写了 538 行开发记录
└── 但"必须遵守"区只有 2 条
```

于是同样的坑反复踩 —— **教训只被"记录"了，没被"执行"**。

本包打通「记录 → 规则 → 生效」这条链路，**并防止规则库自己膨胀成没人读的文档**。

---

## 快速开始

### 安装到项目

**一行命令，不用 clone：**

```bash
npx github:962599627/agent-development-constraints install
```

> ⚠️ **这里必须写 `github:` 前缀。**
> 包**还没有发布到 npm**（`npm view agent-development-constraints` 返回 404），
> 所以更短的 `npx agent-development-constraints install` **现在会失败**。
> 之前的 README 一直写着短形式 —— 那是一条**不可能成功的指令**。
> 等发布到 npm 之后，短形式才可用；在那之前请用上面的 github 形式。
>
> 实测（2026-10-05）：`npx github:... install` 能完整跑通 ——
> 规则库、`.githooks/pre-commit`、`AGENTS.md` 引用、基线都会就位。

就这样 —— 规则库、三套流程、可选的安全网会落到 `./agent-constraints/`，
并在你的 `AGENTS.md` 里加一段引用。

其余命令（同样带 `github:` 前缀）：

```bash
npx github:962599627/agent-development-constraints check        # 脱敏检查（可选安全网）
npx github:962599627/agent-development-constraints contribute   # 提取【你】新增的规则
npx github:962599627/agent-development-constraints hooks        # 启用提交前检查
npx github:962599627/agent-development-constraints help
```

**或者从 clone 安装**（效果相同 —— CLI 只是转交给这些脚本）：

```powershell
# Windows
.\install.ps1 F:\my-project
```

```bash
# Linux / macOS
./install.sh /path/to/project
```

脚本是**幂等**的：

| 文件 | 重复安装时的行为 |
|---|---|
| `core/constraints.md`（你的规则库） | **保留不覆盖** —— 这是你积累的资产 |
| `core/DISTILL.md` / `PRUNE.md` / `MERGE.md`、`core/stacks/` | 更新（随包升级） |
| `templates/` | 更新 |
| `AGENTS.md` 的引用段 | 原地刷新（靠 HTML 标记定位，不会重复追加） |

> 想连规则库一起覆盖加 `--force`（先备份）。不想改 `AGENTS.md` 加 `--skip-agents`。

### 安装后做三件事

1. **打开 `agent-constraints/core/constraints.md`**，删掉不适用的条目 ——
   尤其看看**「快速定位 · 按症状查」**表，那是出问题时的入口
2. **打开 `agent-constraints/core/stacks/`** —— 技术栈坑位库
   （`python` / `javascript` / `shell` / `git` / `platform`），整组替换成你自己的栈
3. **把规则库纳入版本管理**，它会随项目一起进化

### 日常使用（关键）

```
开发完成 / 修完 bug
   ↓
问一句：这次有没有可以变成"下次自动生效"的约束？
   ↓ 有                                   ↓ 没有
跑 core/DISTILL.md 的流程提炼              结束
   ↓
跑 core/PRUNE.md 检查是否超限
   ↓
更新 constraints.md + 变更日志
```

---

## 目录结构

```
agent-constraints/
├── README.md              英文版（GitHub 默认）
├── README.zh-CN.md        中文版（本文件）
├── VERSION                版本号
├── CHANGELOG.md           变更日志（含设计决策的理由）
├── CONTRIBUTING.md        怎么贡献规则
├── install.ps1 / .sh      幂等安装脚本
├── contribute.ps1 / .sh   靠安装时的基线，自动提取"你新增的规则"
├── core/
│   ├── constraints.md     ★ 规则库（唯一需要 AI 读的产物）
│   ├── DISTILL.md         提炼流程 + 可复用提示词
│   ├── PRUNE.md           精简流程 + 可复用提示词
│   ├── MERGE.md           合并流程（维护者视角）+ 可复用提示词
│   └── stacks/            技术栈坑位库（按需加载）
│       ├── python.md          Python / Django / DRF
│       ├── javascript.md      JS / TS / Vue / Vite
│       ├── shell.md           PowerShell / bash
│       ├── git.md             git
│       └── platform.md        Windows / MySQL / Docker / Redis
├── templates/
│   ├── rule.md            单条规则模板（四要素）
│   └── session-log.md     会话记录模板（提炼原料格式）
└── examples/
    └── case-study-blog.md    真实案例：从某博客项目提炼出的规则
```

---

## 快速定位 · 按症状查

规则库开头就是**症状索引** —— 因为出问题时，你手上拿的是**报错原文**，
不是"我现在在写哪个语言"。按语言找还得多想一步，按症状是直接命中：

| 症状 | 很可能的原因 | 详见 |
|---|---|---|
| `Failed to connect ... port 443` 但 `curl` 能通 | git 在 HTTP/2 上挂起 | `stacks/git.md` |
| 退出码 1，但命令实际成功了 | PowerShell 把 stderr 当错误 | `stacks/shell.md` |
| 脚本报语法错误 + 中文乱码（`鏅鸿兘`） | `.ps1` 缺 UTF-8 BOM | `stacks/shell.md` |
| **单独跑通过、放进整套就失败** | 共享状态（限流/缓存）污染 | **R-003 / R-009** |
| **本人主页看不到"编辑"按钮** | 身份判断用了可变的展示名 | **R-004** |
| 点行内按钮**误触发跳转** | `<a>` 里嵌了 `<button>`（非法 HTML） | **R-005** |
| **两处数字对不上** | 缺一致性测试 | **R-011** |
| **整套测试慢得离谱**（几十上百秒） | 夹具在做生产级哈希/加密，框架不会自动降级 | **R-013** |
| **扫描报告"0 处问题"，实际却有** | 检测脚本自身的假阴性 | **R-014** |
| **没反应、也不报错** | 代码根本没执行（函数 ref 漏冒号之类） | **R-015** |
| `Maximum recursive updates exceeded` | 渲染/回调里写响应式状态，缺"值未变则返回"守卫 | **R-015** |

## 按症状查：这本书的目录

规则库不只是规则清单 —— 它前面有一张**按症状查的目录**。
出问题时你手上拿的是**症状**（报错原文、异常现象），
不是"我在写哪个语言"；所以先看目录定位，再翻具体条目。

```bash
constraints action=symptom                    # 看完整目录（分类 + 症状 + 规则编号）
constraints action=symptom q="整套测试慢"      # 按症状查 → 命中条目 + 规则全文
constraints action=l0                         # 铁律
constraints action=show                       # 全部规则
```

目前 **10 类**：构建/命令/环境 · 测试 · 排查工具/扫描脚本 · 改了数据源/格式之后 ·
接口/数据/安全 · 界面/交互 · 插件/宿主集成 · 成本/排查 · 多副本不一致 · 空/等待/故障。

> ⚠️ **索引要用"读者会怎么描述"来写词，不能只用原文。**
> 第一版按词切分 + 子串匹配，实测大量漏命中：
> 表里写「没反应、也不报错」，用户说"没反应也不报错"（差一个顿号）就查不到；
> 「扫描报告"0 处问题"」用"扫描报0"也查不到。
> 现在改用**字符二元组重合度**（中文没有词边界），并把"换个说法也要命中"
> 固化成测试 —— 索引不能用原话才能查。

---

## 脱敏：每次提交自动检查

**要求**：更新时不能带出暴露自身安全的信息。

**这不是靠自觉，而是机制** —— 因为"记得检查"迟早会失效：

```powershell
# 安装后启用一次即可
.\agent-constraints\scripts\install-hooks.ps1
```

启用后每次 `git commit` 都会自动扫描**本次暂存的文件**，命中即**拒绝提交**：

```
发现 1 处可能暴露自身安全的信息：
  _hook_test.md
    第 1 行  ←  规则: (?i)(密码|口令|密钥)\s*[:：=]\s*["']?[^\s"']{4,}
      数据库密码: "your_password"
```

**拦截四类**：

| 类别 | 例子 |
|---|---|
| 凭据 | 赋值形式的密码/密钥/token、连接串、私钥内容 |
| **本地路径** | `C:\Users\<本机用户名>`、开发盘符下的项目路径（暴露目录结构） |
| 个人信息 | 邮箱、手机号 |
| 项目专名 | 按需追加到 `.sanitize-deny.txt` |

**手动跑**：

```powershell
.\agent-constraints\scripts\sanitize-check.ps1          # 全部已跟踪文件
.\agent-constraints\scripts\sanitize-check.ps1 -All     # 含未跟踪（公开前体检）
```

**遇到误报**：把无害示例的特征加进 `.sanitize-deny.txt` 的允许清单（以 `!` 开头），
**而不是直接放宽规则**。

> ⚠️ **为什么要在提交前、而不是发布前**：脱敏**只在内容被写进历史的那一刻有效**。
> 一旦提交，`git log` 里就永久留下 —— 事后改文件没用（见 **R-002**）。

---

## 它不会做什么

> 它要做的是**一个不断学习的学生** —— 不是守卫，更不是翻你东西的人。

| 它**不会** | 怎么自己验证 |
|---|---|
| **联网 / 上传任何内容** | 零网络调用 —— 跑 `grep -rnE 'Invoke-WebRequest\|curl\|wget\|HttpClient\|smtp' --include='*.ps1' --include='*.sh' .` → **无输出** |
| **读你仓库外的文件** | 只用 `git ls-files` 与 `$ROOT` 下的路径。不碰浏览器数据、环境变量里的密钥、SSH key、聊天记录 |
| **保存 / 缓存 / 自动提交** | 结果**只打印到终端**，不写日志、不建缓存。`contribute` 只生成**一个本地文件**，提不提交**由你决定** |
| **学你的秘密** | 规则库里积累的是**模式**（"凭据不要硬编码"），不是值。自检：把整个规则库公开，你会不安吗？ |
| **把你锁死** | 安装是**幂等**的 —— `constraints.md` **绝不被覆盖**。随时删掉本包，自己的规则照样能用 |

**内核是「学习」**：四层规则库 + 提炼 / 合并 / 精简三套流程。
**脱敏只是可选的安全网** —— 删掉 `scripts/`、`.githooks/`、`.sanitize-deny.txt`，
其余部分照常工作。

完整承诺见 [PRIVACY.md](PRIVACY.md)。

---

## 规则库的四层结构

| 层 | 内容 | 上限 | 换项目时 |
|---|---|---|---|
| **L0 铁律** | 跨项目通用、代价高、**有自动化检查** | **15 条** | 保留 |
| **L1 协作约定** | 人机 / 机机协作规则 | 无 | 保留 |
| **L2 技术栈坑位库** | 具体框架的坑 | 无 | **整组替换**（`core/stacks/`） |
| **L3 归档** | 已失效的保留名字 | 无 | 保留 |

**L0 的 15 条上限是硬约束** —— 约束的价值随长度递减，超了 AI 就开始忽略它们，
而被忽略的规则库比没有更糟。

---

## 每条规则的四要素

```markdown
### R-0XX 一句话规则名（动宾结构）
- **规则**：可执行的约束（禁止"注意…""尽量…"这类无法判断是否违反的表述）
- **触发**：什么时候该想起来（列清单，越具体越好）
- **检查**：怎么验证（**必须是一条命令 / grep / 断言**，不是"人工 review"）
- **证据**：哪次真实踩坑换来的 + 代价
```

**为什么四个都要**：

| 缺了哪个 | 后果 |
|---|---|
| 规则 | 变成"注意安全"式的废话 |
| 触发 | AI 想不起来，等于不存在 |
| 检查 | 只能靠自觉，无法验证 |
| 证据 | 后人不知道轻重，精简时会当废纸删掉 |

**判据**：一条规则写完后，能写出一条**断言**或一条**命令**来抓违反吗？不能的话，它还没被想清楚。

---

## 为什么用的人越多它越厉害

这是本包的**核心机制**，不是口号。

**问题**：如果只在单个项目内闭环，每个项目各自积累规则、彼此不知道 ——
**人多不产生任何额外价值**。

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

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

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

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

**数据怎么流动**：

```
主仓库（精华规则）
   ↓ install
项目 A / B / C 各自积累踩坑经验
   ↓ contribute（靠安装时的基线，自动识别你的新增）
贡献包 → 维护者按 MERGE.md 合并
   ↓ 抽象 + 独立发现次数 +1
主仓库更新 → 再分发给所有人
```

**合并时的「抽象」是关键动作**：

```
候选 A：Django 的 settings.py 里别写数据库密码
候选 B：Node 的 docker-compose.yml 里别写密码
候选 C：文档里别记管理员密码
        ↓ 抽象成上位规则（覆盖三种场景）
R-001 凭据绝不硬编码（源码 / 配置 / 文档 / 模板 全都不行）    独立发现：3
```

**副产品**：规则里的「来源」字段让规则**抗删** ——
有 3 个来源的规则，没人在精简时敢随便删掉它。

详见 [`core/MERGE.md`](core/MERGE.md)（维护者流程）与 [`CONTRIBUTING.md`](CONTRIBUTING.md)（贡献指南）。

---

## 设计理念

| 决策 | 理由 |
|---|---|
| 规则必须可执行 | 无法判断是否违反的规则等于没有 |
| 必须留证据 | 证据是规则抗删的唯一依据 |
| L0 设硬上限 | 短而准 > 长而全；宁可只留 10 条被遵守的 |
| 只删被工具链替代的 | 归档成本极低，重新发现同一个坑的成本很高 |
| 「本次未收录」要留痕 | 否则下次会有人重新提出同样的建议 |
| 安装幂等 | 用户的规则库是资产，升级流程不能动它 |
| 记录模板末尾带勾选项 | 开发记录最常见的失效方式是"写完没人回头看" |
| 技术栈坑位按需加载 | 上下文是稀缺资源，库一膨胀就会被整体忽略 |

---

## 与开发记录的关系

本包**不替代**开发记录，而是它的下游：

```
原始记录（会话 / job.md）      ← 又长又碎，人看，AI 不全读
        ↓ DISTILL
约束库（constraints.md）       ← 短、准、可执行，AI 每次必读
        ↓ PRUNE
稳定精华                       ← 长期稳定，新项目直接复用
```

**判断一条信息该放哪**：
- 只有**考古价值**（想回顾当时怎么做的）→ 留在开发记录里
- **下次还会用上** → 提炼成规则

---

## 贡献

最有价值的贡献是：**「我独立踩到了你库里已有的某个坑」** ——
它会给那条规则 +1 独立发现次数，可能把它从 L1 提升到 L0。

详见 [`CONTRIBUTING.md`](CONTRIBUTING.md)，或在你的项目里跑
`contribute.ps1` / `contribute.sh` 自动提取你新增的规则。

## 许可证

见 [LICENSE](LICENSE)。