alexei-led/archfit
GitHub: alexei-led/archfit
archfit 是一款面向 AI agent 和 CI 的多语言架构适配度检查 CLI 工具，通过确定性门禁、平衡耦合评分和结构化修复任务防止架构侵蚀。
Stars: 0 | Forks: 0
# archfit
[](https://github.com/alexei-led/archfit/actions/workflows/ci.yaml)
[](https://github.com/alexei-led/archfit/actions/workflows/release.yaml)
[](https://github.com/alexei-led/archfit/tags)
[](https://github.com/alexei-led/archfit/pkgs/container/archfit)
[](https://github.com/alexei-led/archfit/pkgs/container/archfit)
[](https://pkg.go.dev/github.com/alexei-led/archfit)
[](https://goreportcard.com/report/github.com/alexei-led/archfit)
[](LICENSE)
**面向 AI agent 和 CI 的架构适配度检查。**
`archfit` 用于检查代码是否依然遵循你预期的架构。
它从语言分析器中读取代码结构事实，然后对照 `.archfit.yaml` 对其进行评估：
包含边界、层次、公开 API、循环依赖，以及
[平衡耦合](docs/guide/concepts.md)。
平衡耦合是一种判断依赖关系是健康还是存在风险的方法。它关注三个方面：依赖的强度、耦合部分之间的距离，以及它们变更的频率。
其输出专为自动化设计：确定性的门禁违规、面向 agent 的结构化修复任务，以及分段式架构评分表。架构偏移将成为你的 agent 和 CI 可以在演变为代码审查难题之前采取行动的依据。
## 为什么需要
AI agent 擅长进行局部修改，但不擅长在上下文中统筹整个系统的设计。
这一缺陷至关重要。一个 agent 可能会做出通过测试的修改，但同时也悄悄地：
- 跨越了被禁止的边界进行导入；
- 绕过了模块的公开 API；
- 在不同层之间添加了捷径；
- 增加了依赖循环。
每一次单独的修改看起来可能都无害。但随着时间的推移，这些捷径就会变成实际的架构。耦合不断增加，bug 在相距甚远的模块中级联发生，并且未来的每一次修复都需要更多的人类上下文、更多的 agent token 以及更多的重试。
`archfit` 在这个循环中加入了架构适配度的信号：
```
flowchart LR
A[Agent edits files] --> C[archfit check]
C -->|clean| P([PR opened])
C -->|violation + agent_tasks| R[Agent applies the repair order]
R --> C
classDef ok fill:#d3f9d8,stroke:#2f9e44,color:#000;
classDef gate fill:#ffe3e3,stroke:#e03131,color:#000;
class P ok;
class C gate;
```
当门禁失败时，`archfit` 会发出一个 `agent_tasks` 条目。这是一道修复指令，而不是一行模糊的日志：
```
{
"rule_id": "no_internal_access",
"goal": "Replace the internal-API access from pkg/a/a.go to pkg/b/internal/impl.go with b's public API.",
"constraints": [
"Use only the public API of module b",
"public surface of \"b\": [pkg/b/api/**]"
],
"files": ["pkg/a/a.go", "pkg/b/internal/impl.go"],
"validation": ["archfit check -c .archfit.yaml --full"]
}
```
该任务包含了目标、限制条件、需要检查的文件，以及用于验证修复效果的命令。
## 工作原理
`archfit` 将事实、门禁和叙述分离开来。
语言适配器负责收集代码结构事实。确定性的核心程序根据你的配置对这些事实进行评估。可选的 LLM 功能可以解释证据并对其进行优先级排序，但它们绝不会决定门禁是否通过。
```
flowchart TB
subgraph tools[External extractors]
direction LR
T1[go list]
T2[dependency-cruiser]
T3[ast-grep]
T4[grimp]
end
CFG[".archfit.yaml"]
tools -->|dependency facts| core
CFG --> core
subgraph core["archfit core — deterministic, no LLM"]
direction LR
CL[classify] --> RU[gates]
CL --> ME[metrics] --> SC[score]
end
core --> OUT["SARIF · JSON · Markdown · text
agent_tasks · scorecard"] OUT -. off-gate · advisory only .-> LLM["review · enrich · autopilot
narrate & prioritize evidence"] classDef side fill:#f3f0ff,stroke:#7048e8,color:#000; class LLM side; style core fill:#e7f5ff,stroke:#1971c2,color:#000; ``` 对于相同的输入，门禁的输出在字节级别上是一致的。这使得它非常适用于 CI 以及对比不同的 commit。如果缺少可选的分析器，相关指标会报告为 `n/a` 并附带启用步骤，而不是假装一切正常。 ## 你能得到什么 - **确定性的门禁**，用于检测被禁止的依赖、公开 API 边界、 层级的方向、导入循环以及配置的阈值。 - **`agent_tasks` 修复块**，让 AI agent 能够直接获取修复方案，而不仅仅是错误信息。 - **分段式的 7 维度评分表**（`archfit score`）：边界完整性、 耦合平衡度、依赖图健康状况、内聚性、变更局部性、 架构适配度，以及分析置信度。 - **平衡耦合报告** — 强度 × 距离 × 波动率，分组汇总展示，而不是为每一条依赖边显示单独的一行。 - **诚实客观的覆盖率** — 缺失的工具会显示为 `n/a`，而不是显示虚假的通过状态；在每种输出格式中都会报告存在的缺口。 - **基线**，确保被接受的当前技术债不会掩盖新的发现。 - **语法事实**（`tools.syntax.enabled: on`）— 针对 Go、 TypeScript、Python 和 Rust 统计声明数量、公开 API 总数，以及架构角色（handler/service/repository/domain）。支持三种新规则类型： `forbidden_role_dependency`、`public_api_max` 和 `public_api_change`。 - **门禁之外的 LLM 叙述**（`review`、`enrich`、`autopilot`）只能叙述和优先排序已收集的证据，绝不捏造门禁违规。 ## 方法论 — 平衡耦合 耦合并不总是坏事。有些部分理应共同演进。问题在于出现了对于当前设计而言强度过高、距离过远或波动太大的耦合。 `archfit` 将 Vlad Khononov 的平衡耦合模型中可检查的部分进行了实用化。它通过三个维度对跨边界关系进行评分，并解释该关系看起来是内聚的，还是存在风险的： ``` flowchart LR S["Integration strength
contract → intrusive"] --> J{coupling
verdict} D["Distance
same module → cross deploy-unit"] --> J V["Volatility
low → high change-rate"] --> J J -->|high strength · low distance| G["Cohesion
balanced — leave it"] J -->|high strength · high distance · high volatility| B["Cascading change
distributed-monolith risk"] classDef good fill:#d3f9d8,stroke:#2f9e44,color:#000; classDef risk fill:#ffe3e3,stroke:#e03131,color:#000; class G good; class B risk; ``` 它并不能取代架构审查 — 它只是使得收集可复现的证据变得低成本，并且在 CI 中运行是安全的。有关从理论到信号的映射，请参阅 [概念](docs/guide/concepts.md) 和 [指标](docs/guide/metrics.md)。 ## 对比分析 特定语言的边界 linter 依然有用。`archfit` 位于比它们更高一层的抽象级别。 那些工具提供事实。而 `archfit` 将这些事实转化为针对预期架构、平衡耦合风险、分数变动和修复任务的量化判定。 | 工具 | 语言 | 面向 agent/CI 的输出 | 耦合模型 | LLM 叙述 | | ------------------ | ---------------------------------------- | ------------------------------------ | ------------------------- | ------------- | | **archfit** | 参见 [语言支持](docs/guide/languages.md) | SARIF + JSON + `agent_tasks` + score | Balanced Coupling (S/D/V) | off-gate | | dependency-cruiser | TS/JS | JSON/HTML, 规则违规 | 基于规则 | 否 | | import-linter | Python | 文本, 契约通过/失败 | 分层契约 | 否 | | ArchUnit | Java/JVM (.NET/TS) | 构建中的测试断言 | 基于规则 | 否 | 当你想要在单一技术生态中进行构建时的细粒度断言时，请使用单语言 linter。当你需要统一的架构配置、一份机器可读的判定结果，以及专为 AI agent 修复循环设计的反馈时，请使用 `archfit`。 ## 快速开始 安装 CLI（在可复现的文档中使用特定的 release tag，而不是 `@latest`）： ``` go install github.com/alexei-led/archfit/cmd/archfit@v0.6.1 ``` 或者使用包含内置工具链的 Docker 镜像运行： ``` docker run --rm -v "$(pwd):/repo" ghcr.io/alexei-led/archfit:v0.6.1 \ check --config /repo/.archfit.yaml --full ``` 在代码仓库中运行首次检查： ``` archfit doctor # check available analyzers archfit init --root . --output .archfit.yaml # generate a starter config $EDITOR .archfit.yaml archfit check --config .archfit.yaml --full # run the gates archfit score --config .archfit.yaml --full # banded scorecard ``` 如果当前的检查结果代表的是已知的技术债，可以将其接受为基线： ``` archfit baseline --full --config .archfit.yaml ``` 针对常见项目结构的入门配置位于 [`examples/`](examples/README.md)。需要 Docker、CI、可选分析器、平台 包管理器或 PATH 修复？请从 [指南](docs/guide/README.md) 和 [工具参考](docs/guide/tooling.md) 开始。 ## 核心命令 | 命令 | 用途 | | ---------------------- | --------------------------------------------------- | | `archfit doctor` | 检查本地分析器/工具的可用性。 | | `archfit init` | 生成一个入门的 `.archfit.yaml`。 | | `archfit update` | 将 `.archfit.yaml` 与当前结构同步。 | | `archfit check` | 运行架构门禁和指标检查。 | | `archfit score` | 输出分段的 7 维度评分表。 | | `archfit scan` | 生成完整的 Markdown 审计报告。 | | `archfit baseline` | 保存被接受的当前检查结果。 | | `archfit review` | 门禁之外的 LLM 证据叙述审查。 | | `archfit enrich` | 起草门禁之外的 LLM 耦合标签优化。 | | `archfit autopilot` | 通过 LLM 起草完整的 `.archfit.yaml`（仅供审查）。 | | `archfit explain` | 通过指纹前缀解释某一个发现。 |
| `archfit install` | 检查或安装常用的分析器工具。 |
请参阅 [命令指南](docs/guide/commands.md) 了解参数、格式和退出
代码。通过指定 `--root` 指向代码仓库，并将 `--config` 指向其他位置，即可在分析目录之外运行 archfit（外部 CI）。
## 文档
- [指南](docs/guide/README.md) — 文档导航。
- [概述](docs/guide/overview.md) — 什么是 archfit 以及何时使用它。
- [为什么架构适配度很重要](docs/guide/why-architecture-fitness.md) —
架构侵蚀、AI agent 带来的风险，以及为什么这不仅仅是依赖 lint。
- [概念](docs/guide/concepts.md) — 让平衡耦合变得可执行。
- [指标](docs/guide/metrics.md) — 每一个指标及其评分方式。
- [安装](docs/guide/install.md) — 二进制文件安装、Docker 以及首次分析器检查。
- [工具](docs/guide/tooling.md) — 平台配置、包管理器、工具版本，
主页以及 PATH 检查。
- [快速开始](docs/guide/quick-start.md) — 首次实用运行。
- [语言支持](docs/guide/languages.md) — 支持的语言及相关配置。
- [配置](docs/guide/configuration.md) — `.archfit.yaml` 基础。
- [CI](docs/guide/ci.md) — pull-request 和 pipeline 配置。
- [Agent 反馈](docs/guide/agent-feedback.md) — `agent_tasks`、SARIF 和
`change_locality`。
- [LLM 增强](docs/guide/llm-enrich.md) — 经人工审查的门禁外草稿。
- [示例](examples/README.md) — `.archfit.yaml` 入门模板。
- [贡献](CONTRIBUTING.md) — 本地开发和发布说明。
## 许可证
Apache-2.0。请参阅 [LICENSE](LICENSE)。
agent_tasks · scorecard"] OUT -. off-gate · advisory only .-> LLM["review · enrich · autopilot
narrate & prioritize evidence"] classDef side fill:#f3f0ff,stroke:#7048e8,color:#000; class LLM side; style core fill:#e7f5ff,stroke:#1971c2,color:#000; ``` 对于相同的输入，门禁的输出在字节级别上是一致的。这使得它非常适用于 CI 以及对比不同的 commit。如果缺少可选的分析器，相关指标会报告为 `n/a` 并附带启用步骤，而不是假装一切正常。 ## 你能得到什么 - **确定性的门禁**，用于检测被禁止的依赖、公开 API 边界、 层级的方向、导入循环以及配置的阈值。 - **`agent_tasks` 修复块**，让 AI agent 能够直接获取修复方案，而不仅仅是错误信息。 - **分段式的 7 维度评分表**（`archfit score`）：边界完整性、 耦合平衡度、依赖图健康状况、内聚性、变更局部性、 架构适配度，以及分析置信度。 - **平衡耦合报告** — 强度 × 距离 × 波动率，分组汇总展示，而不是为每一条依赖边显示单独的一行。 - **诚实客观的覆盖率** — 缺失的工具会显示为 `n/a`，而不是显示虚假的通过状态；在每种输出格式中都会报告存在的缺口。 - **基线**，确保被接受的当前技术债不会掩盖新的发现。 - **语法事实**（`tools.syntax.enabled: on`）— 针对 Go、 TypeScript、Python 和 Rust 统计声明数量、公开 API 总数，以及架构角色（handler/service/repository/domain）。支持三种新规则类型： `forbidden_role_dependency`、`public_api_max` 和 `public_api_change`。 - **门禁之外的 LLM 叙述**（`review`、`enrich`、`autopilot`）只能叙述和优先排序已收集的证据，绝不捏造门禁违规。 ## 方法论 — 平衡耦合 耦合并不总是坏事。有些部分理应共同演进。问题在于出现了对于当前设计而言强度过高、距离过远或波动太大的耦合。 `archfit` 将 Vlad Khononov 的平衡耦合模型中可检查的部分进行了实用化。它通过三个维度对跨边界关系进行评分，并解释该关系看起来是内聚的，还是存在风险的： ``` flowchart LR S["Integration strength
contract → intrusive"] --> J{coupling
verdict} D["Distance
same module → cross deploy-unit"] --> J V["Volatility
low → high change-rate"] --> J J -->|high strength · low distance| G["Cohesion
balanced — leave it"] J -->|high strength · high distance · high volatility| B["Cascading change
distributed-monolith risk"] classDef good fill:#d3f9d8,stroke:#2f9e44,color:#000; classDef risk fill:#ffe3e3,stroke:#e03131,color:#000; class G good; class B risk; ``` 它并不能取代架构审查 — 它只是使得收集可复现的证据变得低成本，并且在 CI 中运行是安全的。有关从理论到信号的映射，请参阅 [概念](docs/guide/concepts.md) 和 [指标](docs/guide/metrics.md)。 ## 对比分析 特定语言的边界 linter 依然有用。`archfit` 位于比它们更高一层的抽象级别。 那些工具提供事实。而 `archfit` 将这些事实转化为针对预期架构、平衡耦合风险、分数变动和修复任务的量化判定。 | 工具 | 语言 | 面向 agent/CI 的输出 | 耦合模型 | LLM 叙述 | | ------------------ | ---------------------------------------- | ------------------------------------ | ------------------------- | ------------- | | **archfit** | 参见 [语言支持](docs/guide/languages.md) | SARIF + JSON + `agent_tasks` + score | Balanced Coupling (S/D/V) | off-gate | | dependency-cruiser | TS/JS | JSON/HTML, 规则违规 | 基于规则 | 否 | | import-linter | Python | 文本, 契约通过/失败 | 分层契约 | 否 | | ArchUnit | Java/JVM (.NET/TS) | 构建中的测试断言 | 基于规则 | 否 | 当你想要在单一技术生态中进行构建时的细粒度断言时，请使用单语言 linter。当你需要统一的架构配置、一份机器可读的判定结果，以及专为 AI agent 修复循环设计的反馈时，请使用 `archfit`。 ## 快速开始 安装 CLI（在可复现的文档中使用特定的 release tag，而不是 `@latest`）： ``` go install github.com/alexei-led/archfit/cmd/archfit@v0.6.1 ``` 或者使用包含内置工具链的 Docker 镜像运行： ``` docker run --rm -v "$(pwd):/repo" ghcr.io/alexei-led/archfit:v0.6.1 \ check --config /repo/.archfit.yaml --full ``` 在代码仓库中运行首次检查： ``` archfit doctor # check available analyzers archfit init --root . --output .archfit.yaml # generate a starter config $EDITOR .archfit.yaml archfit check --config .archfit.yaml --full # run the gates archfit score --config .archfit.yaml --full # banded scorecard ``` 如果当前的检查结果代表的是已知的技术债，可以将其接受为基线： ``` archfit baseline --full --config .archfit.yaml ``` 针对常见项目结构的入门配置位于 [`examples/`](examples/README.md)。需要 Docker、CI、可选分析器、平台 包管理器或 PATH 修复？请从 [指南](docs/guide/README.md) 和 [工具参考](docs/guide/tooling.md) 开始。 ## 核心命令 | 命令 | 用途 | | ---------------------- | --------------------------------------------------- | | `archfit doctor` | 检查本地分析器/工具的可用性。 | | `archfit init` | 生成一个入门的 `.archfit.yaml`。 | | `archfit update` | 将 `.archfit.yaml` 与当前结构同步。 | | `archfit check` | 运行架构门禁和指标检查。 | | `archfit score` | 输出分段的 7 维度评分表。 | | `archfit scan` | 生成完整的 Markdown 审计报告。 | | `archfit baseline` | 保存被接受的当前检查结果。 | | `archfit review` | 门禁之外的 LLM 证据叙述审查。 | | `archfit enrich` | 起草门禁之外的 LLM 耦合标签优化。 | | `archfit autopilot` | 通过 LLM 起草完整的 `.archfit.yaml`（仅供审查）。 | | `archfit explain
标签：AI智能体, EVTX分析, Go, Ruby工具, 云安全监控, 日志审计, 架构分析, 请求拦截, 静态分析