diegomarino/fable-audits

# fable-audits 用于编码 Agent 的对抗性审计 prompt。将 Agent 指向一个代码仓库，你将获得一份按严重程度排序、带有证据标签的发现报告，供修复 Agent 直接执行——而不是模棱两可的主观感受。 包含六个审计模块、一个编排器和一个修复器： | 规范 | 范围 | ID | 报告 | |---|---|---|---| | `commands/audit-codebase.md` | 整个代码仓库 — 正确性、设计、易用性、测试、DX | C | `docs/audits/codebase-audit-.md` | | `commands/audit-docs.md` | 整个代码仓库 — 漂移、结构、覆盖率、可发现性 | D | `docs/audits/docs-audit-.md` | | `commands/audit-process.md` | 整个代码仓库 — 端到端工作流、重新运行、恢复、agent/CI 工效学 | P | `docs/audits/process-audit-.md` | | `commands/audit-security.md` | 整个代码仓库 — 威胁模型、身份认证/授权 (authn/authz)、密钥、供应链（防御性，针对自有仓库） | S | `docs/audits/security-audit-.md` | | `commands/audit-ux.md` | 整个代码仓库 — 发布产物与终端用户的对话：输入负担、消息、术语、流程、恢复、反馈 | U | `docs/audits/ux-audit-.md` | | `commands/audit-change.md` | 单个 diff — 工作区或 `--base `；发布 / 需要关注结论 | X | `docs/audits/change-audit-.md` | | `commands/audit-full.md` | 编排器 — 为每个审计启动一个全新的 subagent，然后生成一个综合的 backlog | F | `docs/audits/fixes-backlog-.md` | | `commands/fix.md` | 按 ID 执行发现 — 重新验证、修复、证明、台账 | — | `-fixes-.md`，与其报告并列 | 每个规范都是**自包含的**：插件 frontmatter 和完整的 prompt body 位于同一个文件中。`dev/` 目录下的所有内容都是仓库的底层机制（schema、脚本、fixtures、约定），绝不会带入到目标项目中。 编排运行（`audit-full`）将其所有产物归组到一个运行目录中——`docs/audits/-/`——这样在同一天对同一项目进行多次审计时，可以保持彼此分离且内部清晰。独立审计会直接平铺写入 `docs/audits/`，并带有 `-2`、`-3` 的冲突后缀。 ## 安装 **作为 Claude Code 插件：** ``` /plugin marketplace add diegomarino/fable-audits /plugin install fable-audits@fable-audits ``` 然后使用 `/fable-audits:audit-codebase`、`:audit-docs`、`:audit-process`、`:audit-security`、`:audit-ux`、`:audit-change --base origin/main`、`:audit-full`、`:fix docs/audits/.md`。 **作为平铺文件（适用于任何测试框架/harness）：** 粘贴来自 [`_fable-audits.txt`](_fable-audits.txt) 的单个 `/goal` — 它会通过 `gh` 将规范克隆到 `/tmp`（位于目标仓库之外：将它们复制到项目中会污染代码树，并触发套件的 clean-tree 预检），并执行指定的规范。Agent 会从磁盘读取规范 body；在 Claude Code 之外，frontmatter 可以被忽略。 ## 工作原理 - **证据标签，而非置信度评分。** 每一个发现要么是 CONFIRMED（已确认）、PLAUSIBLE（看似合理），要么是 BLOCKED（已阻塞，附带本该运行的确切命令），或者是 NOT REPRODUCED（无法复现）。标签在综合过程中会被保留；它们绝不会被平均抵消。 - **验收检查。** Critical/High（严重/高）级别的发现包含当前失败且一旦修复即会通过的确切命令或测试——发现是可闭环的契约。 - **快照纪律。** 报告会记录 commit SHA 以及 clean/dirty（干净/脏）状态；完整的套件默认要求一个干净的代码树 (clean tree)，并在审计过程中发生漂移时中止。 - **证伪优先。** 审计员在报告发现前必须尝试推翻它，并且宁可要一个有力的发现，也不要几个薄弱的发现。 - **人工把关的修复。** 审计从不修改代码，也从不触碰 git。backlog 只是一份计划；`fix.md` 是一个单独的调用，拥有自己的结果台账（FIXED / STALE / NOT REPRODUCED / BLOCKED / NEEDS-DECISION / DECLINED）。 - **机器可读的附带文件。** 每份报告都会发布一个 `*.findings.json`（参见 `dev/findings.schema.json`），以便验证和修复过程可以脚本化。 这些不变量的权威声明位于 [`dev/conventions.md`](dev/conventions.md)；`dev/scripts/lint-prompts.mjs` 负责强制确保每个规范仍然包含它们。 ## 开发 ``` node dev/scripts/lint-prompts.mjs # specs carry the canon node dev/scripts/validate-report.mjs dev/fixtures/codebase-audit-2026-01-01.md # validator self-test ``` 两者均在 CI 中运行。变更策略：首先编辑约定文件，然后传播到 prompt，并保持 lint 通过。 ## 路线图 - 推荐建议上的修复置信度徽章（等待与 `fable-fix` 的 NEEDS-DECISION 结果达成对账规则）。 - 针对 PLAUSIBLE 发现的可证伪预测格式。 - 已接受风险登记表——仅在具备 prompt 注入加固（将结构化数据作为数据读取，绝不作为指令读取）的情况下推出。 - Router 和单仓库设置 skills；用于 Stop hooks/CI 的 ALLOW/BLOCK 门控变体。 - 待 `skills/` 插件布局稳定后，将 `commands/` 迁移至该新布局（`commands/` 至今仍完全受支持）。 ## 致谢 这里的方法论是在对照两个优秀的公开代码仓库进行打磨时完善的： [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0 — 失败成本攻击面、发现校准，以及“一个有力发现”的纪律均呼应了其对抗性审查 prompt) 以及 [mattpocock/skills](https://github.com/mattpocock/skills) (MIT — 完成标准、测试反模式“特征”以及 skill 编写理论)。有少数单行表述是在这些许可下近乎逐字改编的；其余部分则是趋同的灵感启发，刻意未作直接导入。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI编程助手, Claude, CVE检测, MITM代理, 数据可视化, 模块化设计, 自动化修复, 自定义脚本, 防御加固