no-negative-echo 扫描器教程:如何用 check_surface.py 快速检出标题/注释/PR 残留?
no-negative-echo 扫描器教程:如何用 check_surface.py 快速检出标题/注释/PR 残留?
no-negative-echo 是让 AI Agent(Codex、Claude Code、Cursor 等)在交付时不重复会话中被否方案的 Skill,其内置扫描器 check_surface.py 能对标题、注释、commit、PR 等交付文本做精确词检查,帮助你在交付前快速检出「会话残留」。本文用 3 个步骤讲清用法。
为什么需要检查「残留」?
代码已经改成番茄炒蛋,标题却还写着「番茄炒蛋(无东坡肉)」,注释还在解释为什么这里不加东坡肉——这正是 BACKGROUND.md 记录的典型负向回声:被否决的方案在最终产物里又响了一次。
提示词层规则能约束 Agent「自觉」,而扫描器负责兜底:只要禁词出现在最终文本或文件名里,扫描立刻判失败。🔍
第一步:拿到扫描器
扫描器是位于 Skill 目录下的单文件 Python 脚本(需 Python 3.10+,纯标准库、零依赖):
如果还没有本地仓库,先克隆:
git clone https://gitcode.com/gh_mirrors/no/no-negative-echo
cd no-negative-echo
也可以先跑一下确认脚本可用(INSTALL.md 的验证步骤同样如此):
python3 -I no-negative-echo/scripts/check_surface.py --help
若通过 Skill 安装合约装到了本机,脚本会在 ~/.agents/skills/no-negative-echo/scripts/check_surface.py(以 Codex 宿主为例)。
第二步:写禁词文件并执行扫描
把「不应出现在最终交付物里的词」写进一个纯文本文件,每行一个:
redis
东坡肉
然后把待交付的产物(commit 说明、PR 正文、源文件等)作为位置参数传入:
python3 -I no-negative-echo/scripts/check_surface.py \
--terms-file terms.txt \
commit.txt pr-body.md src/main.py
核心参数一览:
| 参数 | 必填 | 说明 |
|---|---|---|
--terms-file |
是 | 禁词文件,每行一个词 |
--root |
否 | 额外检查相对 root 的完整路径(含目录名) |
paths... |
是 | 一个或多个待检查的交付文件 |
项目自己的命令习惯是给 python3 加 -I(isolated 模式),避免环境中的 site 包干扰。
第三步:读懂结果
脚本只打印一行 JSON,而且从不打印禁词本身——报告不会把「东坡肉」再说一遍。
全部干净时:
{"status": "PASS", "files_checked": 3, "failures": [], "reviews": []}
出现命中时(退出码 1):
{"status": "FAIL", "files_checked": 3, "failures": [{"file_index": 2, "matched_term_count": 2, "surfaces": ["content"]}], "reviews": []}
| status | 退出码 | 含义 |
|---|---|---|
PASS |
0 | 内容与文件名均未检出禁词 |
FAIL |
1 | 检出禁词,明细见 failures |
REVIEW |
1 | 未命中禁词,但内容或文件名含零宽/双向控制等不可见字符 |
ERROR |
2 | 输入无法安全扫描,看 reason_code |
failures 会告诉你:哪个文件(file_index)、命中了几个词(matched_term_count)、命中在哪个面(surfaces:content 正文 / filename 文件名 / relative_path 相对 root 的路径);REVIEW 对应把禁词藏进不可见字符的规避手法,reason_code 为 default_ignorable_or_bidi,需要人工确认。
5 个值得知道的细节
- 大小写与全半角归一化:禁词与目标文本都会做 NFKC + 小写化,
REDIS、全角redis同样会被检出。 - 文件名也在检查范围:不带
--root时检查文件基名;带上--root <仓库根>后,目录名也一并检查——high-assurance-finalization.md 的高保障流程正是这样要求的。 - 路径防逃逸:符号链接、
..等指向 root 之外的路径组件会直接报ERROR(unsafe_path_component);扫描期间文件发生变化、非常规文件也都会失败退出。 - 输入上限:目标文件最大 16MB,禁词文件最大 1MB、4096 个词,支持 UTF-8/UTF-16 文本。
- 防规避:零宽空格、双向控制符等不可见字符不会让文本「看起来干净」,而是判
REVIEW交给人判断。
这些行为在 tests/test_installer_scanner.py 中都有对应测试用例覆盖。
边界:PASS ≠ 无残留
SKILL.md 里有两个坦白的提醒:
- 零匹配的扫描检测不到语义转述,
PASS不代表合规。「队列改用 PostgreSQL 实现」在语义上仍是提及被否方案的回声,扫描器不会拦截。 - 扫描器只适合稳定、非敏感的禁词;凭据、内部代号等敏感信息应交给专门的密钥/DLP 工具,不要把敏感值写进
terms.txt。
实操建议:内容每次修改后重新扫一遍;hook 或工具改写过文件后,先读回真实内容再扫描。⚠️
小结
| 步骤 | 动作 |
|---|---|
| 1 | 克隆仓库(或安装 Skill),定位 check_surface.py |
| 2 | 把本次任务的禁词逐行写入 terms.txt |
| 3 | python3 -I .../check_surface.py --terms-file terms.txt <交付文件> |
| 4 | FAIL 就重写交付文案并重扫,直到 PASS 且无 REVIEW |
扫描器是确定性兜底,Skill 的判断流程是主力,两者组合就是 no-negative-echo「从最终状态生成 + 交付前检查」的完整闭环。
