Lyspo/ballast

1876 年，经过 Samuel Plimsoll 多年的奔走呼吁，英国船舶被要求在船体上画一条线。 装载超过这条线，标记就会没入水下——任何人从码头都能看到，无需文书或检查员。极限变得 清晰可读，而非争论不休。 这一规定花了十四年时间才真正发挥作用。1876 年的法案允许船东自行决定画线的位置，有的 人甚至把它画在了烟囱上；直到 1890 年，根据贸易委员会 1886 年的载重线表确定了该标记的 位置并将其作为强制要求后，这个标记才真正具有了意义。 这个故事的第二部分，正是本项目的核心所在。 当前，AI 系统的治理文档恰恰相反：它被写在一个没人会打开的文档里，描述着一套已经变更过 九次的系统。 Ballast 将那条线重新画回了船体上。 ``` git clone https://github.com/Lyspo/ballast && cd ballast pnpm install && pnpm build node dist/cli/index.mjs demo ``` ## 功能说明 ``` ballast init Answer nine questions a scanner cannot answer for you ballast scan Find every model, SDK, prompt, tool definition and credential ballast classify Propose a risk classification — you confirm it ballast generate Write the risk assessment, model cards and compliance matrix ballast check Fail CI when the code and the paperwork disagree ``` 最后一点才是核心。其他所有步骤都只是生成文档；而 `check` 负责确保这些文档名副其实。 ``` ── Governance drift ───────────────────────────────────────────── ! New model gpt-4o-mini is called but not declared. src/screening.ts:42 The AI surface of this repository changed without the manifest being updated. Review the changes, then run `ballast scan --write` to record them, and re-run `ballast classify`. ``` 它运行时无需 API key、无需网络、也没有单次运行成本，因为按 pull request 收费的检查机制 迟早会因为预算被砍掉，而需要密钥的检查则无法在 fork 仓库中运行。 ## 开发动机 欧盟《AI Act》的合规义务正一波波地落地，且这些要求还在不断调整。关于 AI 的《数字综合 法案》——即 [法规 (EU) 2026/1744](https://eur-lex.europa.eu/eli/reg/2026/1744/oj/eng)，自 **2026 年 7 月 27 日**起生效——将 独立的 Annex III 系统的高风险义务推迟至 **2027 年 12 月 2 日**，将嵌入式产品系统的义务推 迟至 **2028 年 8 月 2 日**，同时保留了针对聊天机器人和生成式 AI 的第 50 条透明度义务（生 效日为 **2026 年 8 月 2 日**），以及 GPAI 相关义务（自 **2025 年 8 月 2 日**起保持不变）。 对于已经上市的生成式系统，第 50(2) 条规定的机器可读标记要求宽限至 **2026 年 12 月 2 日**， 除此之外没有其他变动。 因此，对于大多数工程团队而言，当前的紧迫问题并非“《AI Act》是否会到来”，而是一个更棘手 的问题：*哪项*义务适用于*当前*系统，以及*何时*适用。这个问题需要从代码中寻找答案，并且 每当代码发生变更时，答案也会随之改变。 Ballast 正是为那些刚刚被问到“他们的功能是否符合合规要求”的工程师打造的，因为他们才是 真正了解系统实际行为的唯一人选。 **Ballast 在这方面姗姗来迟，本 README 应当坦诚这一点。** 商业平台——如 Credo AI、Holistic AI、OneTrust、IBM watsonx.governance——都在向首席风险官（CRO）推销仪表盘，而那些已经 拿下了这些买家的合规自动化供应商（如 Vanta 和 Drata）也正在其现有的装机量中增加 AI 模块， 这是 Ballast 所不具备的优势。此外，至少有五款开源工具已经在针对《AI Act》读取代码或网 络流量：Systima Comply、Regula、Warden 和 ArkForge 的 MCP 扫描器扫描源代码；AIR Blackbox 则在运行时拦截调用。其中有些做得很好。特别是 Systima Comply，它使用真正的 AST 来检测框 架，而 Ballast 目前使用的是基于行的匹配；并且它也自带了基线与差异比对的命令。 真正的区别在于扫描之后会发生什么。那些工具只是报告发现的问题并生成模板脚手架。而 Ballast 则会基于包含 38 项《AI Act》条款和 48 项义务的带日期知识库，通过带有审查者的 agent pipeline 直接起草实际的文档（如风险评估、模型卡片、合规矩阵）——审查者会攻击草稿， 并设立人工确认门控，在有人接受分类结果之前阻止文档生成。这是否比一个更好的扫描器更有 价值，是一个值得探讨的问题，[docs/business/competitive-analysis.md](docs/business/competitive-analysis.md) 对此进 行了客观的剖析，甚至包含了一张展示竞品在哪些方面更具优势的对比表格。 ## agent 的工作原理 `classify` 和 `generate` 运行着四个职能高度明确的 agent。 | | | | | --- | --- | --- | | **Surveyor** | 读取代码 | 在沙盒中执行 `read_file` / `list_files` / `grep`，仅限于此。确认系统对其调用的模型实际做了什么。报告其无法确定的内容。 | | **Pilot** | 进行分类 | 根据 Surveyor 的观察结果和您的问卷回答，推导出相应的欧盟《AI Act》层级和 NIST AI RMF 映射。 | | **Drafter** | 撰写文档 | 生成文档。每一项实质性陈述都必须附带对发现结果、配置回答或具体条款的引用。 | | **Examiner** | 攻击草稿 | 对抗性审查者。专门搜寻缺乏证据支持的陈述——尤其是那些关于并不存在的控制措施的陈述。 | 三个设计决策承担了大部分核心作用： **模型无法凭空捏造法律。** Pilot 的输出 schema 将引用限制在一个基于内置知识库构建的封闭 枚举集合中。如果捏造了条款编号，将无法通过 schema 验证，因此绝对不会混入文档中。单靠 prompt 是无法在与过度自信的模型交锋中幸存的。 **由人工确认分类结果。** `classify` 将其结论标记为 `proposed`（提议）。在有人工确认接受之 前，`generate` 将拒绝运行，并记录确认人的身份及时间。机器可以提出法律分类建议；但必须 由人来最终接受。 **Examiner 未解决的质疑会被展示出来，而非被掩盖。** 每份文档最多接受 `maxCriticIterations` 次检查（默认为两次，即一次重写），之后任何仍然存在的阻断性质疑都会被打印出来，并带入文 档的未决问题中。如果一个 pipeline 一直循环到审查者放弃为止，那它产出的将是满足审查者的 文档，而不是追求事实真相的文档。 Ballast 还会将自身的模型调用、工具调用、验证重试和人工审批记录到 `ballast/audit-log.jsonl` 中——包括模型版本、token 数量、请求哈希、延迟，以及该调用是实时的还是重放的。如果一个 工具要求其他团队保留其 AI 系统的操作记录，那么它绝不能连自己的记录都做不好。故意不记录 prompt 及响应的*内容*：因为这些文件会被提交到代码库，而 prompt 中往往包含源代码。 ## 安装说明 目前尚未发布到 npm，因此需要从源码安装： ``` git clone https://github.com/Lyspo/ballast && cd ballast pnpm install && pnpm build pnpm link --global # optional: puts `ballast` on your PATH ``` 需要 Node 22 或更高版本以及 pnpm。`scan`、`check` 和 `demo` 绝不会调用模型，也不需要 API key。`classify` 和 `generate` 会使用 `ANTHROPIC_API_KEY`——这是您自己的 key，费用由您自行承 担，每次运行通常只需几美分。这四个 agent 都已经在实时 API 上完成了端到端运行。 [docs/example-run.md](docs/example-run.md) 详细展示了完整的运行过程：21 次模型调用，花费约 1.16 美元，Pilot 拒绝猜测团队究竟属于提供商还是部署者，以及 Examiner 打开了 Drafter 的两个引 用并发现它们并不支持所附属的句子。所有对话记录及生成的文档都已提交，因此无需 key 即可完 整重放整个运行过程： ``` ballast classify examples/resume-screener --offline assets/demo-cassettes/classify.jsonl ballast generate examples/resume-screener --offline assets/demo-cassettes/generate.jsonl ``` 为了让其他人能够离线重放 agent 阶段，您可以针对内置示例录制一次会话： ``` ANTHROPIC_API_KEY=... pnpm cassettes:record ``` 这会将记录写入 `assets/demo-cassettes/`，随后供 `classify --offline` 和 `generate --offline` 重放。这些记录（Cassette）通过包含 prompt 版本的哈希值进行索引，因此修改 prompt 会导致 它们失效，重放时会直接且明确地报错，而不是为您提供一个针对已过时问题的旧答案。 ## 在 CI 中 ``` name: AI governance on: pull_request jobs: ballast: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Lyspo/ballast@main ``` 该 action 会将偏移报告写入工作流摘要，并对外暴露一个 `verdict` 输出。一旦有可用的 tag，请 将其固定到相应的 tag 上；目前的 `@main` 已经如实指明了它当前所指向的位置。 退出代码：`0` 表示正常，`1` 表示存在实质性偏移，`2` 表示没有可用来进行比对检查的已提交基线。 ## 生成的内容 ``` ballast/ ├── manifest.yaml The declared AI surface. Read this one in a PR. ├── surface.json Exact scan baseline. `check` diffs against it. ├── classification.yaml The risk classification and who confirmed it. ├── risk-assessment.md Risks, mitigations, and what could not be established. ├── compliance-matrix.md Obligation → status → evidence, with dates. ├── model-cards/ One per model, describing your use of it. └── audit-log.jsonl Every agent interaction. Not committed by default. ``` 所有这些内容都是为了让您将其提交到版本库中。脱离了版本控制的治理文档既无法进行 review， 也无法进行差异比对，更无法让人相信它能准确描述发布时代码的真实情况。 ## 坦诚说明的局限性 Ballast 只读取源代码和问卷。它无法看到您的生产行为、训练数据、评估结果或运营流程，并且 它会在生成的文档中明确说明这一点，而不是含糊其辞地掩饰这些盲区。 知识库是欧盟《AI Act》和 NIST AI RMF 的精选子集，并带有版本号和日期。它不涵盖国家层面的 实施法律、协调标准或特定行业的法规。对 prompt 和工具定义的检测采用的是启发式算法，且已 明确标注——每一项发现都附带一个置信度等级，该工具绝不会声称其能力超出了其实际所能展示 的范围。 **本工具提供的不是法律意见。** 它是一种用来保持对您的系统行为进行准确、可审查记录的方法， 以便让您与提供法律意见的专业人士的对话能够从事实出发。请参阅 [docs/regulatory-notes.md](docs/regulatory-notes.md) 了解详细的方法论及其适用边界。 ## 文档 - [完整运行示例](docs/example-run.md) — 针对内置示例运行全部四个 agent 的全过程，未经编辑， 且包含对话记录及生成的文档 - [适用于您系统的义务及生效时间](docs/which-obligations-apply.md) — 面向大多数软件团队实际所属的四种形态 提供的一份通俗易懂的指南，其内容基于与分类器相同的知识库生成，因此文章与工具的解释 绝对保持一致 - [架构设计](docs/architecture.md) — 各个组件是如何协同工作的 - [监管合规说明](docs/regulatory-notes.md) — 知识库涵盖了哪些内容，以及未涵盖哪些内容 - [决策记录](docs/adr/) — 为什么选择开源，以及为什么它不是一个仪表盘 - [商业文档](docs/business/) — 随代码一同交付的战略规划 ## 开源协议 MIT © Theo Gandolphe

标签：DevSecOps, MITM代理, 上游代理, 合规自动化, 欧盟人工智能法案, 自动化攻击