# Pit-Stop
*开进来，修好，出去更快。你不用下车。*
[](LICENSE)
[](https://github.com/Finn763/pit-stop/stargazers)
[]
[English](README.md) | 中文
> 评审 agent 停在"指出问题"。Pit-stop 把活干完。
别的 agent 工具都差一口气：PR 评审只读 PR；单文件评审 skill 只诊断不动手；阶段式技能
教流程却不端到端跑；架构类技能交份报告就走。Pit-stop 是陪你跑完全程的那个：
读、修、验、报，一句话，不用下车。
Pit-stop 是一个跨端 agent skill：**一句话跑完整个改进闭环——装载→找缺点→给建议→改→想点子→汇报，
中途不问你。**
```
用 pit-stop 改进 <项目路径>
```
你只说一句。agent 装载上下文，找缺点（每条带 `路径:行号` 证据），
修→复查循环里改完，用真实工具输出验证，最后一次性给报告
（分已验证/未验证/待定）。推送和发布永远要你亲口说才动手。
---
## 为什么做 pit-stop
为修三个每个 agent 用户都见过的毛病：
- **#1：只说不干。** 评审以"你应该……"结尾，diff 永远没来。**修法：** 循环不停在
finding——改完复查（最多 3 轮，跨轮台账，不收敛升级），然后才汇报。
- **#2："好了"但没证据。** "修好了！"、"测试过了！"——背后没有一条命令输出。
**修法：** 先证据后结论。本轮没跑验证命令，就不许说成功。报告里只放工具输出。
- **#3：越改越臃肿。** 建议全是没人要的抽象。**修法：** 每条发现打 tag
（`delete/stdlib/native/yagni/shrink/perf/security/obs`），Speculative 只报不修。
没活就直说：`Lean already. Ship.`。
> 一次真实战果：发现带 `文件:行号` 证据 8/8（手搓流程只有 5/8），两条口头"成功"被拦下、逼出工具回执。
> [看完整 before/after →](examples/before-after.md) 诚实基线：n=1 仓库，欢迎独立复跑。
---
## 运行环
六阶段一遍过，中途零打扰——护栏在上，升级出口在下。
[▶ 交互版](https://finn763.github.io/pit-stop/architecture.zh-CN.html)
1. **装载** — 读项目自己的说明 + `git status` + 最近提交热区，先写一行 MODE：什么算发现、什么直接拒。
2. **找缺点** — 先定范围再扫；每条发现带 `路径:行号` 证据、tag 和强度。
3. **给建议** — 只列 Strong 项：现象、证据、影响、最小修复、成本——另附"不做"清单。
4. **改** — 独立 reviewer 复查→再修的循环，最多 3 轮；不收敛升级给你。
5. **想点子** — 循环收口后只读头脑风暴：最多 3 条有锚点的 `[idea]` 候选，各带 kill-probe，本轮绝不实施。
6. **汇报** — 改了/验过（工具输出）/没验/剩下（idea 跟在 needs-human 项之后）；本轮没跑验证命令就不许说成功。
---
## 护栏
L2 hook（`hooks/block-destructive.sh`）跑在 Claude 系宿主里，fail-closed——解析不出的命令一律拦。喂它一条它认得出的破坏性命令，exit 2 并给出原因：
```
$ printf '{"tool_input":{"command":"rm -rf ~/projects"}}' | bash hooks/block-destructive.sh
BLOCKED by pit-stop: 'rm -rf ~/projects' matches file deletion (rm). Destructive ops need the human's explicit word.
$ echo $?
2
```
安全命令原样放行（`grep`、`man rm`、`git commit -m "... rm ..."`）。
覆盖命令位 `rm`（含 `sudo`/`do`/`command`/`env`/`nohup`/`time`/`xargs`/`\rm` 变体、
`sudo -u root rm` 这类带 flag 值、路径式 `/bin/rm`、多行命令后续行）、`find -exec rm`/`-delete`、
非 git VCS 强推、破坏性 git 子命令（`push`、`reset --hard`、`clean -f`、`branch -D`、
`checkout .`、`restore .`、`git rm`）。模式匹配是绊线不是沙箱——`sh -c 'rm …'` 这类向量留给
L1 禁令和 L3 终扫。90 例测试矩阵在 `hooks/test-block-destructive.sh`。
