no-negative-echo 扫描器教程:如何用 check_surface.py 快速检出标题/注释/PR 残留?

原创2026-10-23 23:28:411,402 阅读

no-negative-echo 扫描器教程:如何用 check_surface.py 快速检出标题/注释/PR 残留?

no-negative-echo 是让 AI Agent(Codex、Claude Code、Cursor 等)在交付时不重复会话中被否方案的 Skill,其内置扫描器 check_surface.py 能对标题、注释、commit、PR 等交付文本做精确词检查,帮助你在交付前快速检出「会话残留」。本文用 3 个步骤讲清用法。

no-negative-echo 扫描器检出残留的概念:丢弃会话草稿,交付干净最终结果

为什么需要检查「残留」?

代码已经改成番茄炒蛋,标题却还写着「番茄炒蛋(无东坡肉)」,注释还在解释为什么这里不加东坡肉——这正是 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 个值得知道的细节

  1. 大小写与全半角归一化:禁词与目标文本都会做 NFKC + 小写化,REDIS、全角 redis 同样会被检出。
  2. 文件名也在检查范围:不带 --root 时检查文件基名;带上 --root <仓库根> 后,目录名也一并检查——high-assurance-finalization.md 的高保障流程正是这样要求的。
  3. 路径防逃逸:符号链接、.. 等指向 root 之外的路径组件会直接报 ERROR(unsafe_path_component);扫描期间文件发生变化、非常规文件也都会失败退出。
  4. 输入上限:目标文件最大 16MB,禁词文件最大 1MB、4096 个词,支持 UTF-8/UTF-16 文本。
  5. 防规避:零宽空格、双向控制符等不可见字符不会让文本「看起来干净」,而是判 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「从最终状态生成 + 交付前检查」的完整闭环。

登录后查看全文
no-negative-echo