alint：把仓库结构、文件内容和 Agent 约束一起 lint 掉

很多团队已经有一整套 code lint。

JavaScript 有 ESLint；
Rust 有 Clippy；
安全语义有 Semgrep；
CI 里还会再挂一层 format、test、policy check。

但仓库里其实还有一大块经常没人管的东西：

某些文件必须存在；
某些目录命名必须符合约定；
package.json、Cargo.toml、GitHub Actions workflow 里的字段应该满足团队规范；
每个 package 都要有 README；
每个文档链接都应该指向真实文件；
给 AI agent 的 AGENTS.md 和仓库约束不应该长期漂移。

今天想记下的 asamarts/alint，就是专门去补这一层空白的工具。它不是再做一门语言的语法 lint，而是把“这个仓库整体应该长什么样”抽成一份 declarative 配置，再用一个 Rust CLI 去执行。

按 GitHub 仓库页面、release 页面和项目站点在 2026-06-22 的公开信息，这个仓库当前大约有 43 stars、1 fork，主要语言是 Rust，仓库创建于 2026-04-18，最近公开更新时间是 2026-06-22。GitHub 页面显示它采用 Apache-2.0 / MIT 双许可证；当前最新 release 是 v0.13.0，发布时间为 2026-06-17。

项目概览

属性	详情
仓库	asamarts/alint
定位	面向仓库结构、文件内容和跨文件关系的通用 linter
Stars	43
Forks	1
主要语言	Rust
创建时间	2026-04-18
最近更新时间	2026-06-22
License	Apache-2.0 / MIT
当前版本	v0.13.0
版本日期	2026-06-17

它管的不是“代码写得像不像”，而是“仓库长得对不对”

alint 的切入点很清楚：它关注的是 repository shape。

README 和官网反复强调的不是 AST 级规则，而是下面这些更偏仓库层的问题：

文件是否存在；
文件名和路径是否符合约定；
JSON / YAML / TOML / XML 里的字段是否满足规则；
若干文件之间是否满足一对一或一对多关系；
某些仓库事实存在时，才启用某些规则；
输出结果是否适合 CI、PR 注释，甚至直接给 agent 读取。

这个位置很有意思。因为很多规则严格说不属于某一门语言，但它们又真实影响仓库质量。

比如：

“每个 package 都必须有 README” 不属于 TypeScript，也不属于 Rust；
“所有 GitHub Actions 都必须 pin 到 commit SHA” 不属于 YAML 语法检查；
“所有 Cargo.toml 都必须写 edition = 2024” 不完全只是 Rust 语义；
“每个新增目录都要有对应文档条目” 更像仓库治理问题。

这些要求平时常常散落在团队约定、PR review 习惯和 wiki 里。alint 做的事情，就是把它们从“大家应该记住”变成“仓库自己能检查”。

一份 `.alint.yml`，想统一描述结构、内容和关系

这个项目最顺手的地方，是它没有把配置拆成很多互不相干的小系统，而是试图让一份 .alint.yml 成为统一入口。

从 README 和官网给出的示例看，它可以在一份配置里同时表达：

继承哪些 bundled ruleset；
哪些路径必须存在；
哪些配置文件的字段必须匹配某个值或正则；
哪些目录要遵循命名规范；
哪些文件之间要建立配对或唯一性约束；
哪些规则要在 has_rust、has_node 之类事实成立时才启用。

这比写一堆零散 shell 脚本更像一个可以长期维护的约束层。

项目站点列出来的能力面也比较完整：89 种 rule kind、13 个规则家族、22 个 bundled ruleset、12 种 fix 操作、10 个 subcommand、8 种输出格式。这些数字本身不是价值，但它们至少说明这不是一个只会检查“有没有 README”的小脚本，而是一个已经开始形成系统边界的 repo linter。

它最实用的一点，是把“跨文件关系”当成一等公民

我觉得 alint 真正和很多普通 lint 工具拉开差距的地方，是它对 cross-file relations 的重视。

代码 lint 很擅长看单文件或单语言上下文，但仓库治理里很多常见问题，本质上都要跨文件判断：

每个 workflow 是否有对应文档；
每个 package 是否有 README；
每个 Markdown 链接是否真的指向存在的目标；
每个目录是不是都配套了某种元数据文件；
同一类标识符是否只出现一次。

这些规则如果全靠 shell 管道去拼，通常会变成脆弱、难懂、难迁移的 CI 脚本。alint 把它抽成 declarative 规则之后，至少可读性和可移植性会高很多。

对 monorepo 或多语言仓库来说，这个方向尤其合理。因为“仓库结构”本来就是跨语言问题，放到某个单语言 linter 里总感觉不对位。

对 AI 辅助开发来说，它补的是“结构护栏”这一层

alint 还有一个我觉得很贴近当下工作流的设计：它明显在考虑 AI-touched repos。

README 和官网都提到两件事：

支持 --format agent，把结果输出成更适合 LLM 消费的 JSON；
提供 export-agents-md，把当前规则集导出到 AGENTS.md。

这两个点单独看都不算巨大创新，但放在一起就很实用。

现在越来越多仓库会让 agent 直接改文件。问题不是 agent 会不会写代码，而是它经常不知道仓库有哪些结构性约束，于是反复犯同一类错误：

新增目录但漏掉配套文档；
改 workflow 却破坏团队规定；
新增文件命名不符合约定；
更新配置文件时改坏字段结构；
写了 AGENTS.md 但规则和仓库现状慢慢脱节。

如果一个工具能把这些约束压缩成机器可读的统一输出，它就不只是给 CI 用，也是在给 agent 提供一层“先读规则，再动手”的护栏。

从这个角度看，alint 有点像把 repo hygiene、policy-as-code 和 agent guardrail 往一起拢。

它和传统 lint / policy 工具的边界也很清楚

官网有一段定位我觉得非常重要：ESLint 和 Clippy 管代码，Semgrep 管语义，alint 站在代码和策略之间，专门管仓库文件系统形状。

这个表述很准。

它说明 alint 的价值不是替代现有 lint，而是补上另一层：

它不分析业务逻辑；
不试图理解某门语言的全部语义；
不抢单语言 lint 的位置；
重点在“仓库约束的声明和执行”。

这也是为什么它看起来会同时碰到 README、license、workflow、lockfile、JSONPath、目录结构、文档链接、Unicode hygiene 这些杂事。因为这些问题本来就不住在一个 AST 里，而是散在整个仓库树上。

如果一个团队已经有完整代码质量体系，alint 不是重复建设；更像是在告诉你：还有一层以前只能靠 review 记忆力兜底的规则，现在也可以系统化。

这个项目的信息密度挺高，而且不像“只做概念演示”

单看 README，alint 已经不是一个非常早期的玩具：

仓库页面显示目前有 55 个 release；
最新 release v0.13.0 距离今天只过了几天；
README 提到仓库里附带 30 个开源项目配置示例；
开发部分还直接写了 450+ tests 和 end-to-end scenario 结构；
官网给出了 benchmark、rules、cookbook、compare、roadmap 等一整套文档入口。

这类信号不等于项目一定成熟到适合所有团队，但至少说明作者不是只停留在“提出一个想法”，而是在认真打磨一个可以持续扩展的工具面。

尤其对这类“横跨仓库治理、CI 和 agent 工作流”的工具来说，文档和样例往往跟功能本身一样重要。因为用户不是只想知道它能不能跑，还想知道：

我应该从哪个 ruleset 起步；
它和现有 CI 怎么拼；
什么时候该用它，什么时候不该；
约束写多了之后会不会难维护。

alint 至少在“把自己的边界和使用方式讲清楚”这件事上，做得比很多小工具认真。

当然，它也不是万能仓库治理器

我觉得写这种工具时，最容易出现的误区是“什么都想管”。从公开材料看，alint 的边界目前还算克制，但使用上仍然有几个需要自己把握的点：

规则太多时，团队可能会把简单约束堆成复杂治理系统；
某些组织流程问题，不一定适合硬编码成 lint；
如果规则设计得过细，CI 噪音会迅速上升；
它能约束仓库形状，但不能替代真正的代码设计判断。

所以更合理的用法大概不是“一上来把所有东西都 lint 掉”，而是先抓那些稳定、重复、可审计、跨语言的规则。

例如：

必备文件；
文档和目录的配对；
workflow 权限和写法底线；
config 文件里的固定结构；
agent 协作里最容易反复踩坑的仓库约束。

这些地方最适合先让工具接管。

小结

asamarts/alint 值得看的地方，不是它又造了一个新 lint，而是它把很多团队长期口头维护的“仓库形状规则”收拢成了一层可声明、可执行、可被 agent 读取的约束系统。

它不抢 ESLint、Clippy 或 Semgrep 的位置，而是专门补那层更容易被忽视的 repository hygiene。对多语言仓库、monorepo，尤其是已经开始让 AI agent 直接碰代码库的团队来说，这个方向很实用。

如果你也经常觉得“仓库里总有一些明明重要、却没人系统检查的结构规则”，那 alint 可能正是在补这个洞。