Troubleshooting

故障排查

启动报 dsh-plugin-audit/invariant: pending (waiting for service: invariants)

你把 invariant 行接入了不提供 invariants 服务的 profile。官方 profile（web/headless）都不提供该服务，挂起的行会阻断启动。移除该行——随包的 cordis.patch.yml 默认就不含它，只有手工添加过才会出现此问题。

会话里看不到 plugin_audit 工具

1. 确认包在 profile package.json 的 dsh.profile.bundles 中；
2. 用 --dump-config 确认配置里出现 dsh-plugin-audit 行；
3. 重启 profile。

正常命令频繁触发哨兵询问

• 把目标主机加入 allowedHosts（注意精确规则不覆盖子域名，需要就加 *.example.com 条目）；
• 或者设 sentinelEnabled: false 只保留静态审计。

扫描文件比预期少

遍历上限 400 文件 / 单文件 256 KB / 深度 12 层，且跳过 node_modules、.git、lib、dist 等目录。请审计包的源码目录，而不是安装产物副本。触顶时卡片摘要会标注 file cap reached。

审计结果里出现我没写过的发现

• 字符串和注释中的命中会原样上报（基于文本而非 AST，宁多勿漏）——人工排除即可；
• 依赖表（dependencies）来自 package.json 声明，不代表代码真的调用了它们；
• 如果确认是检测规则的 bug（而非边界取舍），欢迎带最小复现开 Issue。

只发布 dist 的包得了 NOTICE

这是有意行为：没有源码可扫时，插件如实报告"未扫描到任何源文件"，而不是给出没有任何证据支撑的"干净"结论。请向插件作者索要源码，或人工审查构建产物。

升级到 v0.1.2 后行为变化

• 哨兵现在真的会触发了——v0.1.x 因读取错误的 exec 字段在生产环境从不触发（详见 v0.1.2 release notes）。如果升级后突然出现审批提示，那是哨兵开始正常工作，不是新 bug；
• format: "json" 从"文档承诺但未实现"变为真实返回结构化报告。