krzysztofdudek/Yggdrasil

# Yggdrasil **只说一次。** 编写一条规则，它将在之后的每一次会话中生效，无需你重复自己。在 agent 编辑文件之前，它只会获取与该文件相关的规则，而不是全部两百条。编辑完成后会进行检查，违规将作为错误返回，agent 必须在继续操作前将其修复。相同的检查会在 CI 中免费重新运行，且无需任何 API key。 [](https://github.com/krzysztofdudek/Yggdrasil/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@chrisdudek/yg) [](https://opensource.org/licenses/MIT) [](https://codecov.io/gh/krzysztofdudek/Yggdrasil) [](https://github.com/krzysztofdudek/Yggdrasil/discussions) ## 你可能感觉不到这个问题，而这正是有趣的地方 如果你曾是下班后独自一人阻挡在 agent 和生产环境之间的唯一防线，为了快速验证某个东西是否值得开发而将其迅速发布，那你一定体会过那堵墙。代码产出的速度超过你维持质量的速度。接下来的发展只有两种可能：要么你因为必须亲自监视一切而导致进度缓慢，要么你失去线索，最终陷入无法追溯到决策的 bug 中。 如果你所在的公司愿意为质量买单，你可能从未碰过那堵墙。代码审查、QA 和 sprint 的节奏为你挡住了它。但同样的，这也意味着你也从未见识过自己不受限制的速度有多快。 没人从任何一个方向衡量过这件事。目前可用的最佳研究表明，在有 AI 辅助的实际任务中，经验丰富的开发者的速度**慢了 19%**，而他们却自认为快了 20% ([METR, 2025](https://arxiv.org/abs/2507.09089))。无论是感觉很快的人，还是感觉谨慎的人，手里都没有测量工具。 脚手架的存在不是为了阻止你跌倒。它的存在是为了让“刹车”不必由人来充当。 ## 五分钟实现你的第一条强制规则 需要 Node.js 22+。你可以在没有 API key 的情况下开始：`yg init` 提供了**“暂时不需要”**作为切实可行的选项，此后脚本规则、依赖控制和 CI 门控都可以在没有 key 且不调用模型的情况下正常运作。 ``` npm install -g @chrisdudek/yg cd your-project yg init yg check ``` 第一次检查是绿色的，并且诚实地说明了原因： ``` yg check: PASS (1 warning) 0 nodes · 0/50 files (0%) · 0 aspects · 0 flows uncovered (50) Not under a coverage.required root. Visible, non-blocking. ``` 目前还没有强制执行任何规则，因为你还没有声明什么才是重要的。没有任何东西在伪装。那个列表是你的待办事项，而不是检查结果。 所以，向你的 agent 说一件事： 它会编写规则并映射模块。此时 `yg check` 会失败，因为该规则从未针对你的代码进行过验证。`yg check --approve` 会对其进行验证。从那时起，该规则将生效，任何破坏它的更改都会在到达你手中之前，作为错误反馈给 agent。 这就是整个循环，也是看到效果的最短、最诚实的路径。 更希望被引导？告诉你的 agent **“带我熟悉 Yggdrasil”**。在一个已配置好的仓库中，agent 了解指导手册，并会在你自己的代码上，用你自己的语言教你。 ## 它是如何运作的 规则：每一笔扣款都要记录一个审计事件。agent 编写了一个跳过该事件的退款逻辑。 ``` async function refund(req) { await payments.refund(req.body.chargeId) return { ok: true } } ``` `yg check` 拒绝了它：**退款更改了扣款，但没有审计事件。** agent 添加了调用，重新运行，通过了。 ``` async function refund(req) { await payments.refund(req.body.chargeId) await audit('refund', req.body.chargeId) // added return { ok: true } } ``` 你什么都没审查。这就是循环：agent 编写代码，检查运行，agent 在你查看之前自行修复了它的问题。 你只需附加一次规则，工具就会自动计算它适用的所有地方。你永远不需要将它粘贴到每个文件上，也永远不需要把整个规则手册交给 agent。 ## 两种规则 **脚本规则**提供一个在本地运行的 `check.mjs`，每次执行都是零成本的。它是确定性的，并且不存在理解偏差。这是你应该依赖的层级，也正是那种当它仅仅是规则文件中的一行文字时，会被 agent 悄悄忽略的规则。 **判断规则**是纯 Markdown，由单独的模型读取，用于处理脚本确实无法做出的判断。 ``` # 审计每个 payment mutation Any function that creates, updates, or refunds a charge must call `auditLog.emit()` before it returns. A mutation with no audit event is a refusal. ``` 判断规则是方差较大的层级，因此请保持这些组件小巧，并在强制执行新规则之前先将其作为建议运行。一条规则要么是这种，要么是那种，绝不兼有。 词汇表的其余部分，包括组件、流程、端口、状态和谓词语言，都在[文档](https://krzysztofdudek.github.io/Yggdrasil/)中。你不需要了解这些就能获得第一次检查结果。 ## 其他地方真正没有的功能 每一个裁决（无论是来自脚本还是模型）都会根据产生它的所有内容的哈希值进行记录。CI 不会重新运行你的模型审查。它会重新计算哈希值，并免费重新证明现有的裁决，且无需任何 API key。 在实践中，你只需为每段代码支付一次审查费用，而不是为每个 pull request 支付。每个按量计费的 AI 审查产品都会因为未更改的代码而再次向你收费，而且如果不破坏它们自己的定价模式，它们就无法停止这种行为。 如果代码发生了变化，哈希值就会改变，裁决就会失效，检查就会变红。绿色的构建绝不能悄悄地意味着“我们跳过了那项检查”。 ## 为什么这样构建 这个工具里的所有东西之所以存在，是因为在某些时刻我需要它，但当时没有。没有任何东西是因为它在功能列表上听起来不错而被添加的。如果某个机制看起来出奇地具体，通常就是这个原因，而提交历史会告诉你具体时间。 我是在独自一人、追求极致速度发布东西时构建了这个工具，这也是上面提到的那堵墙的来源。这只是个人的经验，不是一项研究。请据此自行判断。 ## 安装前的两个限制 **它强制执行的是结构，而非运行时行为。** 它可以要求你调用审计工具。它无法证明审计在生产环境中确实触发了。 **绿色的检查结果好坏完全取决于背后的规则。** 浅薄的规则会放过浅薄的代码。强制执行是实打实的。但决定什么值得强制执行，仍然取决于你。 ## 查看完整图谱 `yg portal` 会在浏览器中将所有内容渲染为只读地图：每个组件、每条规则，以及每一项是否针对当前的代码进行了验证。没有任何东西会被粉饰为绿色。`yg portal --static` 会生成一个独立的文件，你可以把它发给没有代码仓库克隆的人。

## 在 CI 中 ``` - run: npx @chrisdudek/yg check --approve --only-deterministic - run: npx @chrisdudek/yg check ``` 第一行重建了全新检出的代码库中缺失的免费本地缓存。第二行是门控：它会根据记录的裁决重新计算每条规则的输入哈希值，如果有任何未经验证的更改，则会导致失败。不需要 key，也不调用模型。 ## 兼容性 任何读取 `AGENTS.md` 的 agent：Claude Code、Cursor、Copilot、Codex、Cline、OpenCode、Amp、Zed 等。`yg init` 会编写一套通用的规则集，因此你不需要选择平台。 审查服务提供商：Anthropic、OpenAI、Google、OpenAI 兼容接口、本地 Ollama，或者完全委托给已安装的 agent CLI，无需任何 API key。 ## FAQ **这和规则文件有什么不同？** 规则文件是被塞进每个提示词中的扁平文本，没有作用域限制，也没有验证。而在这里，agent 只会获取与它正在编辑的文件相关的规则，并且输出会根据这些规则进行检查。 **这和 pre-commit 或 agent hook 有什么不同？** hook 是一个真正的门控，你应该使用它。将它指向 `yg check` 就大功告成了。单纯的 hook 没有概念区分哪条规则适用于哪个文件，也没有处理需要判断而非脚本的规则的概念，更没有能让 CI 免费重新证明模型裁决的锁定机制。 **这和 AI 审查机器人有什么不同？** 审查机器人根据它们自己对好代码的定义来寻找 bug，并且它们在每个 pull request 上都会重新运行并重新计费。而这里检查的是你特定的规则，那些只有你的团队才知道的规则，并记录下每个裁决的持久证明。 **如果我不想用了怎么办？** 删除 `.yggdrasil/` 和规则文件。没有运行时依赖，没有构建 hook，什么都不会留下。 ## 示例和文档 [`examples/`](examples/) 包含六个可运行的项目，其中四个不需要 key。这个仓库本身就在使用 Yggdrasil，因此 [`.yggdrasil/`](.yggdrasil/) 是一个你可以直接阅读的实时图谱。完整文档请访问 [krzysztofdudek.github.io/Yggdrasil](https://krzysztofdudek.github.io/Yggdrasil/)。 ## License MIT

标签：AI编程助手, Apache Flink, MITM代理, SOC Prime, 代码规范检查, 开发工具, 持续集成(CI), 暗色界面, 自动化攻击