stop-that-shit README

The project's README from github.com/lennney/stop-that-shit. As one markdown file: README.md.

Stop That Shit（别再造史了）AI Agent 任务边界 Guard 的红色 STOP 印章

Stop That Shit（别再造史了）

最新版本 构建状态 MIT 许可证

把活干完。把多余的停下。

Skill + Guard，帮 AI coding agent 停止无用防御和任务越界。
Codex · Claude Code · OpenCode · Hermes Agent CLI · Pi
SHIT 哲学 · 看个例子 · 安装 · 案例库 · English · 한국어

你只让 Agent 导出一个文件，它顺手算了份没人读取的 SHA-256，说是“以防万一”。

你让它 Review，它找到问题就开始改。你让它修一个点，它又想重构旁边的模块。检查已经回答了当前问题，它还想再拉一个 Agent，“最后确认一下”。

理由一个比一个严谨。东西还没交付，token 已经花了一截，你还得盯着它，别让任务继续跑偏。

活还没拿到，我先当上了 Agent 的监工。

我也试过往 AGENTS.md 里补规则：“不要乱改”“别过度设计”“没让我做的先别做”。每气一次就补一条，写着写着，AGENTS.md 自己也开始造史了。

Stop That Shit。别再造史了。 该干的干完整，没用的别往上堆。

SHIT 是哪四种

我们把这些行为叫作 SHIT：

把当前责任承担完整，让复杂度随真实需要增长。 需要多改几个文件、补齐迁移或跑跨组件测试，就做完整。

前后对比

下游只读取 report.csv，没有发布校验，摘要也没有其他用途。导出逻辑却写成了这样：

await writeFile("report.csv", csv);
await writeFile("report.csv.sha256", createHash("sha256").update(csv).digest("hex"));

按 STS 的判断，保留：

await writeFile("report.csv", csv);

这个简化示例省掉了无用校验和，文件照常交付。更多场景见案例库。

如果发布流程会读取 checksum，并在不一致时拒绝使用文件，就保留，用 hash=allow 放行。

必要的工作要做全。 修复配置迁移时，旧数据已经发布且仍需支持，就把迁移、读写双方和兼容性测试一起补齐。哪怕 diff 更大，也不能留下坏掉的调用方。

验证到了什么

公开的 18 个 Bad/Good 判定用例，检查规则能否停下多余动作、保留必要工作，覆盖只读审查、必要调用方、已发布数据迁移、发布校验和，以及文件、依赖和 subagent 边界。模型在真实任务中的表现另看对照运行。

完整证据记录测试、历史 Codex / GPT-5.6 运行和没有差异的结果；复现方法见对照测试说明。

它怎么判断

遇到这些 SHIT，先读相关代码、查清调用链，再按顺序判断：

1. 当前要交付什么？     → 明确结果、授权和已有支持承诺
2. 已有能力够用吗？     → 从直接可用的方案开始
3. 还有什么具体缺口？   → 补齐现在需要的行为和保障
4. 这层防御起什么作用？ → 保留有效的，省掉无用的，修正有害的
5. 结果验证完成了吗？   → 没有范围内阻塞，就结束

先看已有代码、标准库、平台原生能力和已安装依赖。符合所需行为和状态生命周期的就用，有具体缺口再加机制。

新机制说不清用途，可以暂缓；已有保护用途不明，先查清再动。真实的信任边界和已有支持承诺，都足以说明保护的必要，不必等事故发生。

代码行数、文件数量和检查次数不能代替判断。完整规则。

快速安装

一般宿主需要 Node.js 18+；Pi 0.84.4 自身要求 Node.js 22.19+。完整安装说明见 INSTALL.md。

展开你使用的宿主。只想用规则、不需要执行拦截，可以只装 Skill。

Claude Code

下载并解压 0.2.5 源码，在仓库根目录执行：

claude plugin validate .
claude plugin marketplace add ./
claude plugin install stop-that-shit@stop-that-shit

重启 Claude Code 或执行 /reload-plugins，然后使用：

/stop-that-shit:stop-that-shit review -- Review 这个 diff，只报告问题，不要修改。
Codex 
codex plugin marketplace add lennney/stop-that-shit --ref 0.2.5
codex plugin add stop-that-shit@stop-that-shit

--ref 把安装固定到版本 tag，不跟随可变的 main。重启 Codex。在新的 CLI TUI 中输入 /hooks，对照该 tag 的 Hook 清单检查并信任命令。也可以把 INSTALL_FOR_AGENTS.md 交给 Codex，让它完成非交互步骤。

OpenCode 从 GitHub 安装

OpenCode 1.18.18 或更高版本可以全局安装这个仓库，无需 clone：

opencode plugin github:lennney/stop-that-shit -g

重启 OpenCode 后用 $stop-that-shit review -- ... 设置契约。该命令安装 Guard；内置 Skill 和可选 /sts 别名不会自动注册。详见 INSTALL.md。

Hermes Agent CLI

需要 Node.js 18+。

hermes plugins install lennney/stop-that-shit/.hermes-plugin --no-enable
hermes plugins enable stop-that-shit
hermes plugins list

启用后，CLI 用户需要启动新的 Hermes CLI 进程或会话；Gateway 用户需要执行：

hermes gateway restart

这些操作不需要每次使用插件时重复。只有启用、禁用、更新、回滚或重装插件后， 才需要重启对应的 Hermes 进程。

Pi Coding Agent

当前适配固定验证 @earendil-works/pi-coding-agent 0.84.4。从包含该 Adapter 的本地 checkout 安装：

pi install /absolute/path/to/stop-that-shit

启动新的 Pi 进程，或修改资源后在 TUI 执行 /reload。然后使用：

/skill:stop-that-shit review -- Review 这个 diff，只报告问题，不要修改。

从上述固定 tag 安装即可获得 Pi Adapter 和两个 Skill。详见 INSTALL.md。

Oh My Pi

已在 @oh-my-pi/pi-coding-agent 18.4.4 验证独立 Extension。 0.2.5 包含 OMP 独立 Extension；从该版本源码或解压后的发布包启动：

omp -e /absolute/path/to/stop-that-shit/omp/stop-that-shit.ts --skills /absolute/path/to/stop-that-shit/skills --sts-contract "review agents=0 -- inspect"

确认扩展加载后，发送 /sts change -- ... 切换模式，/sts status 查看合同。 该原生命令也用于 RPC。TUI 还支持首行 $stop-that-shit 指令。 详见 INSTALL.md。

使用

在 Codex 或支持宿主无关指令的 prompt 中，把一条指令放在消息首个非空行，不要包在引用或代码块里。用 -- 分隔任务正文：

$stop-that-shit review -- Review 这个 diff，只报告问题，不要修改。
$stop-that-shit change -- 修复配置读取失败，补齐受影响的调用方和检查。

Claude Code 插件用 /stop-that-shit:stop-that-shit，Pi Skill 用 /skill:stop-that-shit。

指令 用途
review 审查并报告问题
answer 回答问题
monitor 持续检查和报告
change 允许完成任务需要的修改
watch 观察动作，不阻断
status / runtime 查看当前状态和本地记录

需要更具体的边界时，加上参数：

$stop-that-shit lock change files=src/config.cjs|test/config.test.cjs -- 修复这个行为。
$stop-that-shit change deps=allow -- 添加我要求的解析器依赖。
$stop-that-shit change hash=allow -- 生成发布流程需要的校验和。
$stop-that-shit change agents=1 -- 使用一个独立测试 subagent。

还不知道全部受影响文件，就别急着锁 files=。先沿调用链查清楚。

红章管到哪里

Skill 负责工程判断。Guard 在受支持的工具调用前检查明确边界：

动作 Guard 启用后的默认处理
在 review、answer 或 monitor 中写文件 停止
添加依赖 询问；deps=allow 放行
启动 subagent 超出 agents=N 预算时停止
添加可识别的 hash 操作 停止；hash=allow 放行
写入 files= 之外的路径 停止

Guard 不会看到 cache、retry 或 migration 就替你断定它们多余。宿主事件如何接入，见 Adapter 合同。

可选：Stop That Shit Slop（别再废话）

Agent 活干完了，嘴还没停。STSS 删掉无用辩护、收紧重复犹豫，保留影响理解与决定的条件。它也用于文章和图注，处理起草时附加的防御性说明。这是固定离线案例中的一组：

输入：我们也许大概有可能在六到八周内完成迁移，具体取决于访问审批。
输出：预计六到八周完成迁移，前提是获得访问审批。

时间范围和审批条件都保留。如果审批必须在工作开始前完成，就应明确写成“获得审批后，预计需要六到八周”。

完整插件包含 STSS；它也可以单独安装，不需要 Hook。在仓库根目录执行：

npx skills add ./skills/stss --global

rewrite 改写文本，也是贴出文本时的默认模式；audit 只报告问题和最小修改建议。

宿主 改写 审核
Codex $stss rewrite -- 把这个提案写直接。 $stss audit -- 找出防御性废话。
Claude Code 插件 /stop-that-shit:stss rewrite -- ... /stop-that-shit:stss audit -- ...
Claude Code 单独 Skill /stss rewrite -- ... /stss audit -- ...
Pi /skill:stss rewrite -- ... /skill:stss audit -- ...

完整方法见 STSS Skill，成对案例和必须保留的反例见 STSS examples。

FAQ

所以 checksum 都该删？

发布完整性校验、去重、跳过重复处理，都可以是实际用途。对照可信来源给出的预期摘要，发现文件不一致就拒绝使用，即使多算一次也值得。需要做就用 hash=allow 放行。Guard 检查授权，具体用途仍要根据任务判断。

刚装上，为什么还没拦？

安装后默认是 OBSERVING / unconfirmed。显式使用 review、answer、monitor 或 change 后，Guard 才进入 ARMED。watch 始终只观察。只装 Skill 则没有执行拦截。

红章是不是说明动作绝对没执行？

permission_deny_returned（OpenCode 为 execution_denial_returned）表示 Guard 返回了拒绝响应。宿主最终是否执行要单独观测，所以 Runtime 将其记为 hostEffect: unobserved。安全隔离由宿主 sandbox 负责。

会保存我的代码和对话吗？

Runtime 事件不保存代码或对话正文；会话状态另存显式路径、关联 ID 和指令错误等控制信息。分享插件数据前应先检查会话状态，详见 PRIVACY.md。

怎么更新、卸载或参与开发？

见更新检查、停用与卸载、本地开发和更新记录。

把反例发过来

Agent 又造史了？提交 Bad Case。

STS 拦住了真正必要的工作？提交 Good Case。这个同样重要。

说清你的请求、它多做或少做了什么，以及哪个事实会改变判断。参考案例库，脱敏和复现方法见贡献指南。

我不想再往 AGENTS.md 里补一百条“不要”，只希望新案例能让下一次判断更准。

觉得有用，给个 Star。也欢迎在 LINUX DO 交流。

License

MIT

stop-that-shit (lennney/stop-that-shit)

Searching Database…

2.7K ·GitHub
Stop-that-shit
这是什么？Stop That Shit 是一个 Hook + 技能守卫（Skill Guard），用于阻止 AI 编程智能体（Codex、Claude Code、OpenCode、Hermes Agent CLI、Pi）做没人要求的工作：生成没人看的校验和、擅自扩大任务范围，或重做已经完成的步骤。
这是独立应用，还是接入我现有智能体的插件？它不是独立应用——而是一个技能（Skill）加一个由机器校验的 Hook，接入你已经在用的宿主（Claude Code、Codex、OpenCode、Hermes Agent CLI 或 Pi），由各宿主的适配器转换为一个共享的决策接口。
如何为我的智能体安装它？安装方式取决于宿主：把插件解压到 Claude Code 的插件目录并重启；Codex 安装需固定到某个版本标签，并在 /hooks 中批准 UserPromptSubmit/PreToolUse；OpenCode 插件从 GitHub 全局安装；Hermes Agent CLI / Pi 适配器则从本地检出的代码进行设置——完整步骤见 INSTALL.md。
安装之前需要什么？大多数宿主需要 Node.js 18+；Pi Coding Agent 适配器则特别要求 Node.js 22.19+（目前针对 @earendil-works/pi-coding-agent 0.84.4）。
它默认真的会拦截智能体吗？不会——安装后立即处于 OBSERVING（观察）/未确认模式，守卫只记录所覆盖的操作，从不拒绝权限；你必须显式切换到 review、answer、monitor 或 change 模式后，它才会真正开始强制执行，而且只装技能（不带 Hook）则完全无法强制执行。
它实际支持哪些编程智能体？Codex、Claude Code、OpenCode、Hermes Agent CLI 和 Pi Coding Agent——五个适配器共享同一个任务边界核心；其他框架可以通过文档中的 before-action 事件契约添加支持。
SHIT 这个缩写到底代表什么？它代表有边界的任务跑偏的四种方式：范围蔓延（只让修一个东西，却重构了半个项目）、哈希/假想加固（生成没人会用的校验和或防御）、意图违背（让它审查代码，它却动手修改）和任务空转（重做已经检查或测试过的工作）。
Stop That Shit Slop（STSS）是什么，它有何不同？STSS 是 0.2.0 新增的可选、可独立安装的技能，针对智能体输出中啰嗦的自我辩解——例如“这个并不全面”之类的含糊措辞——利用声明台账（Claim Ledger）和声明差异（Claim Diff）检查，逐句决定删除（DROP）、校准（CALIBRATE）、挪位（RELOCATE）还是保留（KEEP）。
它为什么专门拦截新的哈希/校验和操作？Hook 能高置信度地识别受支持工具调用中的哈希操作，并默认拒绝任何新增的哈希操作，因为校验和只有在取代更昂贵的步骤并真正约束下一步时才有意义；只有当仓库代码或发布流程证明确有必要时，你才显式传入 hash=allow。
如果我完全不想信任 Hook，还能用它吗？可以——你可以只安装建议性技能（通过 Claude Code 或 Codex 的远程技能安装器），在没有机器强制 Hook 的情况下获得 Stop Ladder 指导，不过这样它就无法真正拦截超出范围的操作。
What are similar projects?pstack-claude, anti-slop, openrig, nuwa-skill, superpowers-zh, agentbox, memex, autoprompt-skill
Which topics is it in?codex-plugin, guardrails, codex-cli, hermes-agent, ai-coding, harness, opencode, local-first, plugin, agent-skills, codex, claude-code
Creator
lennney
Size
0.9 MB
Stars
2.7K
Updated
CommitOct 15Release0.2.5Oct 15
Age
2mo
Commits · 90 Days