morluto/smokinggun

SmokingGun

面向智能体的优化证据：发现复杂度热点，并检验提议的变更是否值得实施。

它将静态发现、估算、导入的测量结果和行为证据区分开来，以便智能体能够决定接下来要调查什么。

安装智能体技能

可选的 smokinggun 技能会教导兼容的智能体宿主如何使用该 CLI。使用共享的 Skills CLI 安装它：

npx skills add https://github.com/morluto/smokinggun --skill smokinggun

Skills CLI 负责技能放置、冲突处理和更新。SmokingGun 不会修改智能体配置，也不会自行安装技能。

安装 CLI

npm install -g smokinggun

或者在不进行全局安装的情况下引导执行一次扫描：

npx --yes --package=smokinggun -- smokinggun scan .

此命令可能会访问 npm 注册表。SmokingGun 需要 Node 22.18 或更高版本。

使用 CLI

扫描一个仓库：

smokinggun scan .
smokinggun scan . --format markdown
smokinggun scan . --format sarif --output smokinggun.sarif
smokinggun scan . --source-profile all

报告包含热点、支持性证据、覆盖率、假设以及接下来所需的验证。

默认的 runtime 配置文件会抑制来自测试、文档、示例和夹具的发现，同时将这些文件保留在仓库清单中。使用 --source-profile all 扫描所有受支持的源文件，或使用 --only  明确聚焦于某个辅助区域。

静态扫描是只读的、离线的，不会执行仓库代码或修改源文件。发现是候选结果，而非证据。SmokingGun 从现有的基准测试工具导入测量证据；它不会启动工作负载或重写代码。

语义扫描器直接使用捕获的源代码快照。基准测试、性能剖析和测量产物跨越导入边界，但不会被授予工作负载执行权限。有关这些选择背后的所有权规则，请参阅权限架构。

输入要求

文本输入——包括配置、报告和 JSON 证据产物——必须是有效的 UTF-8。SmokingGun 会拒绝格式错误的字节序列，而不是静默替换它们，因为替换文本将不再代表所捕获的证据。诸如 gzip 压缩的 pprof 性能剖析文件等二进制格式在其格式解码器处理它们之前保持为二进制。

pprof 的数值字段必须落在 JavaScript 的精确整数范围内（Number.MIN_SAFE_INTEGER 到 Number.MAX_SAFE_INTEGER）。SmokingGun 会拒绝超出该范围的值，而不是对标识符或测量结果进行舍入。

关于

SmokingGun 的权威路径是：不可变捕获、基于快照的扫描、真实的覆盖率、内容寻址的报告以及显式的证据导入。SARIF、SCIP、基准测试、性能剖析和测量结果仍然是外部输入。缺失或失败的覆盖率会保持可见，而不会变成一次干净的扫描。

开发

需要 Node 22+ 和 pnpm 11.20.0。
pnpm install
pnpm typecheck && pnpm test && pnpm build

质量门禁：pnpm lint（oxlint）、pnpm format:check（oxfmt）、pnpm knip、pnpm check:boundaries 和 pnpm test:coverage。运行 pnpm changeset 以记录发布变更意图。pnpm test:cli 和 pnpm test:package 会对构建后的包进行端到端测试。