Archprint

Archprint

挖掘代码仓库已经遵循的架构规则，并附上相应证据。

在浏览器中试用，无需安装 · 快速开始 · 在 CI 中使用 · 与 AI Agent 配合使用 · 文档

通俗来说，它的作用

每个代码库都有不成文的规则。“页面绝不直接与数据库交互。”“共享代码绝不反向依赖应用。”没人把这些规则写下来，但代码一直遵循着它们，直到某天有人（或 AI 助手）在不知情的情况下打破了规则。

Archprint 会读取 TypeScript 项目，找出代码已经遵循的规则，并展示每条规则的依据：有多少文件遵循了规则、哪些文件违反了规则，以及判断有多大把握。你信任的规则会变成团队现有工具中的自动检查，因此一旦有人违反规则，下次运行 lint 时（在编辑器、pre-commit 钩子或 CI 中）就能发现，而不是等到几周后的代码审查才发现。

可以把它想成一位建筑检查员：先勘察房屋，再记录房屋实际的建造方式，而不是从别处拿来一本规则手册交给你。

• **面向开发者和技术负责人：**为 ESLint 和 dependency-cruiser 推断并生成有证据支持的 lint 规则，通过 init 生成、用 wire 接入，并用 eject 移除。
• 面向代码审查者：archprint check 只会标记拉取请求新引入的规则违反，并直接显示在 GitHub 上，绝不会标记已有的积压问题。
• **面向使用 AI 编码 Agent 的团队：**Claude Code、Cursor 等 Agent 可以在编写代码前，向 Archprint 查询项目规则及其证据。
• **面向评估代码库的任何人：**快速、客观地了解项目的实际结构。

你的 CLAUDE.md 提供指导，lint 规则负责执行。Archprint 根据代码库已经展现的模式生成执行规则，弥合两者之间的差距，让你采用值得信任的规则，而不必手动编写。

实际效果

以下录屏使用的是 archprint-demo，这是一个小型 Next.js API，其路由仅通过服务层访问数据库。

1. 找出代码已经遵循的规则。 每条规则都附有证据。

2. 看看为什么一条规则值得信任。 一步步查看置信度检查。

3. 启用规则，观察违规被捕获，然后彻底移除所有改动。 Archprint 会写入所需文件，在 ESLint 配置中添加一行；lint 会标记直接导入数据库的路由，而 eject 会将项目精确恢复到原样。

亲自试用，无需安装：在 StackBlitz 中打开演示。 演示打开后会立即运行扫描，演示的 README 会逐步介绍如何在 ESLint 中启用规则、违反规则，以及通过 MCP 查询规则。

与 AI 编码 Agent 搭配使用

AI 编码 Agent 可以通过 MCP 查询 Archprint 获取项目规则。MCP 是一种开放标准，让 Agent 能够使用外部工具。你用日常语言提问；Agent 会自行调用 Archprint，并根据证据作答。Archprint 只负责报告，规则仍由你的 linter 强制执行。

Claude Code 会列出规则，说明哪些规则已强制执行、哪些规则暂留审核，然后添加一个路由，并在回复前使用 archprint 检查自己的改动：

Cursor 的用法也一样。 这些录屏中的 Cursor 使用的是 Grok 4.7，而不是 Claude。在桌面应用的聊天中，Cursor 的 Agent 会自行调用 Archprint 的 scan 工具；此截图展示了工具结果和回答：

在终端（cursor-agent）中，它也会执行相同操作：列出规则，然后添加路由并使用 archprint_check 检查：

测量结果：同一个问题，在使用和不使用 Archprint 时的对比

我们在演示应用（70 个文件）中向 Claude Code（Opus 5.5）提问：“这个仓库已经遵循了哪些架构规则？”，每种方式各运行 5 次。中位数［范围］：

	不使用 Archprint	使用 Archprint
读取的 Token 数	81k［58k 到 96k］	52k［52k 到 52k］
写入的 Token 数	1.1k［1.1k 到 1.4k］	0.6k［0.6k 到 0.6k］
每个问题的成本	$0.083［$0.078 到 $0.153］	$0.037［$0.032 到 $0.076］
时间	17 秒［15 到 19］	10 秒［9 到 31］
工具调用次数	5［4 到 10］	2［2 到 2］

答案显示：

• 两种方式都找到了主要规则：路由只能通过 lib/services/ 访问数据库。
• 使用 Archprint 时，每次运行都会给出每条规则的依据，并指出违反其中一条规则的文件（lib/db.ts 在配置层之外读取 process.env）。不使用 Archprint 的运行中，没有一次注意到这一点。
• 不使用 Archprint 时，Claude 还描述了 Archprint 不检查的命名约定。

请谨慎解读这些数据：两列中读取的 Token 都有约 50k 来自 Claude Code 自身的系统提示词，而且这只是一个小型仓库；尚未测量更大的仓库。 方法、测试框架和所有答案。

Claude Desktop、Claude Code、Cursor 和其他客户端的设置说明见 MCP 设置。

快速开始

需要 Node 20 或更高版本。请在包含 tsconfig.json 的文件夹中运行以下命令。在单体仓库中，scan 和 recommend 也接受根目录，并会检查其中的每个应用；而 init 和 generate 一次只处理一个应用（例如 apps/web）。如果根目录下有多个应用，它们会停止运行、列出应用，并提示你指定一个应用后重新运行。

# 1. See the rules your code already follows, with the evidence. Changes nothing.
npx archprint scan .

# 2. Ask why one rule is trusted (use a rule label from the scan)
npx archprint explain AP-001 .

# 3. Set up enforcement for the rules your code already follows cleanly,
#    and record what to review or adopt next in .archprint/config.json
npx archprint init .

# 4. Connect the generated rules to your ESLint / dependency-cruiser config (one managed line)
npx archprint wire

# 5. Run your linter as usual. Your code passes today; a new import that breaks a rule fails.
npx eslint .

# To undo everything, exactly:
npx archprint eject

看看它如何发现问题。 第 4 步之后，故意违反一条规则：例如，让路由文件直接导入数据库客户端，然后运行代码检查工具。这就是演示在浏览器中展示的完整流程。

如果想将它安装到项目中，而不是使用 npx：npm install --save-dev archprint。

更多命令，适用于按步骤进行的完整设置：

# Inspect the evidence behind one rule
archprint explain AP-002 apps/web

# Write the auto-trusted (mechanical) rules to .archprint/, only for the linters your repo uses.
# Structural-inference rules are held for review; add --include-structural to emit them too.
archprint generate apps/web

# Confirm the generated rules pass on your repo before wiring
archprint generate apps/web --check

# Generate a single rule by id after reviewing it (including a SUGGEST rule)
archprint generate apps/web --rule AP-001

# Adopt only the rules you choose, including reviewed layer boundaries
archprint generate apps/web --include-structural --rules AP-002,no-utils-to-app

# Recommend a rule set from the evidence and the detected stack (fresh repos too)
archprint recommend apps/web

# Upgrading from 0.5.x? Move an older archprint-rules/ setup to the .archprint layout
archprint migrate

也可以从源代码构建：

git clone https://github.com/Tommkruix/archprint
cd archprint
npm ci
npm run build
node dist/cli.js scan <path-to-your-app>

它如何决定信任什么

Archprint 有意保持谨慎：错误的规则造成的危害大于没有规则。每条候选规则在为你启用前都要通过两项检查。

1. 证据足够吗？ 看到 5 个文件中有 5 个遵循某种模式，并不能证明什么；40 个文件中有 40 个遵循才算。Archprint 使用威尔逊评分下界为每条规则评分。这是一种标准统计指标，会综合考量规则成立的频率以及接受检查的文件数量。每条规则会归入以下三组之一：

• AUTO（可强制执行）：一致性 95% 下界至少为 90%，例外不超过 3 个，并且角色分类有充分把握。
• SUGGEST（暂定）：至少 80% 的文件符合该模式，且角色的确定性至少为 50%，但有一项 AUTO 条件未达标：置信度下限低于 90%（文件过少或违反规则的文件过多）、违反规则的文件超过 3 个，或角色的确定性低于 80%。会列出供审查，不会自动生成。
• REJECT：信号不足。

2. 规则本身可能有误吗？ 即使通过了数据检验，如果 Archprint 错误猜测了某个文件夹的用途，规则仍可能有误。因此，只有依赖明确无歧义信号的机械类规则才会在未经审查的情况下获得信任：禁止导入（AP-001、AP-002）、循环依赖、测试隔离、导入风格、控制台隔离和公共 API 汇总文件。对四个真实代码库进行三轮对抗式正确性审计后，每轮在这些规则中都没有发现误报。除循环依赖外，所有规则都会写成 lint 规则；代码库在文件数量足以通过门槛时，如果没有循环依赖，就会采用“禁止循环依赖”这条规则，archprint check 会在每次拉取请求时执行该检查（循环依赖需要完整的导入图，因此无法为其编写 lint 规则）。

结构类规则会根据路径推断“层级”或“角色”，而推断可能出错（层级和角色边界、UI/数据分离、入口纯净性、服务端/客户端、功能切片和应用隔离、环境变量访问、工作区包 API、故事隔离）。依赖规范和依赖声明也暂不启用，因为前者可能过度标记。这些规则默认都留待你审查；只有使用 --include-structural 时才会作为强制规则写入，无论其统计评分如何，直到它们也取得同样可靠的记录为止。任何可能出错的规则，都不会在你未选择启用的情况下强制执行。

生成的规则天生是绿色的：每条规则都会放行推断时已知的少数例外文件，因此采用它不会导致 lint 失败，同时仍能捕获新增违规；此外，一致性检查会拒绝写入证据无法相互印证的规则。要在接入生成的规则前先用它们检查代码，请运行 archprint generate --check。

它可以检测什么

提供方式： Auto = 启用为强制规则（机械类规则）。Review = 默认留待你审查；使用 --include-structural 输出。Check = 在每次拉取请求中由 archprint check 强制检查。Report = 仅展示，不强制执行。

Archprint 可以识别技术栈（Next.js、Nest、SvelteKit、Nuxt、Remix），并能分类 React（.tsx）、Angular（.component.ts、.directive.ts）以及 Vue 和 Svelte 单文件组件中的 UI 组件（它会读取 .vue/.svelte 文件的 <script> 块），因此无论使用哪种框架，组件感知规则都适用。

检测器	可推断的规则	随附方式
禁止导入（AP-001、AP-002）	AP-001：请求入口（路由处理程序）不得导入 DB 客户端。AP-002：服务端入口不得导入 UI 层	自动
循环依赖	模块图应保持无环；在不存在循环时采用，且 archprint check 报告新循环时也采用	检查
测试隔离	生产代码（非测试代码）不得导入测试或规范文件	自动
依赖卫生	从第三方包的公共入口导入，而非依赖项的 src/internal 内部模块	审查
依赖声明	每个导入的第三方包都必须在 package.json 中声明（不得存在幽灵依赖或传递依赖）	审查
导入风格	优先使用工作区别名，而非深层相对导入（../../../）	自动
控制台隔离	库代码（非 CLI）不得调用 console.*	自动
公共 API（聚合导出）边界	功能或包以外的文件必须通过其 index 聚合导入，不得深层导入其内部模块	自动
分层边界	同一层中的文件不得导入另一层；根据主要依赖方向推断	审查
角色分层	语义层级须保持方向性（REPOSITORY 不得导入 SERVICE，SERVICE 不得导入 CONTROLLER）	审查
入口纯度	框架入口（页面、路由、布局）不得被其他一方代码导入	审查
UI / 数据分离	可复用 UI 组件不得直接导入 DB/数据层	审查
服务端 / 客户端边界	Next.js "use client" 模块不得导入 server-only 模块	审查
功能切片隔离	features/modules/slices/domains 容器下的同级切片不得互相导入	审查
应用隔离	apps/services 容器下的同级应用不得直接互相导入	审查
环境变量访问	仅在配置/环境层读取 process.env	审查
工作区包 API	通过名称导入单体仓库工作区包，而非深入其源码路径	审查
故事文件隔离	Storybook .stories 文件不得被其他代码导入	审查
孤立模块	没有任何导入者且不是框架入口的文件（可能是死代码）	报告
传递可达性	普通导入规则未能拦截、但通过中间层泄漏的层边界	报告
recommend（以及 init）会将每个规则类别分为多个层级：代码已遵循的规则（立即强制执行）；代码已遵循、但 Archprint 仅报告而不会写入的规则；证据有限的规则（审查并采用）；以及同类代码库普遍遵循、但你的代码库尚未遵循的规则（从第一天起采用）。每条建议都会附上同类代码库（使用检测到的技术栈；否则使用总体数据）中已强制执行该规则的比例，该数据来自对数万个公开 TypeScript 代码库的普查。因此，即使新代码库中可供分析的代码很少，也能获得符合其技术栈的基线，并以生态系统的实际做法为依据，而不是采用精心挑选的默认设置。

它会向你的项目写入什么

archprint generate（以及 init）会写入 .archprint/config.json，并为仓库中已运行且有可执行规则的每个 linter 写入一个文件。典型的 ESLint 项目会得到两个文件：config.json 和 eslint.mjs；如果仓库也采用了 dependency-cruiser 规则，则会多出第三个文件。archprint 会检测 ESLint 和 dependency-cruiser，因此不会留下你并未使用的工具配置。--emit <eslint|dependency-cruiser|all> 可强制指定输出格式。

• .archprint/config.json（始终生成）：记录你采用的每条规则的精确定义、采用时记录的证据以及生成时使用的解析模式（archprint check 会读取它，因此检查时不会重新推断规则）、你允许且附有原因的例外，以及当前强制执行、仅跟踪并报告、暂缓审核和值得采用的规则，还有 eject 会移除的托管输出文件列表。
• .archprint/eslint.mjs（存在 ESLint 时生成）：一个独立的 ESLint 扁平配置文件，内嵌所有推断出的 ESLint 规则（基于标记的禁止导入、no-restricted-imports 导入风格边界、console 隔离，以及在包含结构规则且未使用 dependency-cruiser 时的分层边界、未声明（幻影）依赖、服务端／客户端边界、包内部结构和入口纯度），无需额外插件：它会将规则添加到你现有的 ESLint 配置中，该配置已经能够解析 TypeScript。因此你可以提交它、发布它，或交给另一个仓库，只需一行即可采用（import archprint from './.archprint/eslint.mjs'）。分层边界是个例外：它会根据文件的位置查找应用，因此只适用于生成它时所在的位置。它会自动忽略 **/.archprint/**。禁止导入（AP-）规则和这些结构规则以内嵌的本地 eslint 插件形式生成，因此接入 ESLint 配置后也会强制执行这些规则，无需额外安装。
• .archprint/dependency-cruiser.json（存在 dependency-cruiser 时生成）：包含机械性边界（公共 API 深层导入、测试隔离）的 forbidden 规则集；暂缓审核的规则（分层、角色分层、功能切片、应用隔离、入口纯度、依赖内部结构、幻影依赖、服务端／客户端）只有在你审核后使用 --include-structural 才会添加。
• README.md 中的托管部分：总结当前强制执行、仅跟踪并报告、暂缓审核和值得采用的内容（由 init 或 generate --readme 写入），并添加托管的 .prettierignore 条目，避免格式化工具处理生成的文件。

--expand 还会在 .archprint/ 中写入细粒度产物：按规则族划分的 ESLint 和 dependency-cruiser JSON、每条规则的卡片（.md），其中包含通过和失败的测试样例、eslint-plugin-boundaries element-types 配置、ts-arch 测试，以及 Mermaid 和 Graphviz DOT 分层图。

保持同步，并干净退出。 重新运行 generate（或 init）会刷新 .archprint/，并移除证据已不再支持的规则，因此输出始终与代码保持一致。wire 会在仓库使用的每个强制执行工具中插入一个托管引用（扁平 ESLint 配置、.dependency-cruiser.json），并且这些引用在重新生成后仍会保留；对于无法安全编辑的配置（例如 JS dependency-cruiser 配置），它会打印出可直接粘贴的确切代码片段。eject 会移除 Archprint 的文件和所有接入的引用，并将每个配置精确恢复原状。generate --check 会使用生成的 ESLint 规则检查你的仓库并报告是否通过，让你在接入前确认结果。要从 0.5.x 升级？archprint migrate 会将旧版 archprint-rules/ 配置迁移到此布局，并就地重新接入你的配置。

在 CI 中使用

与基准分支相比，archprint check 只报告变更引入的违规项，检查的是团队通过 init 或 generate 采纳的规则。现有待处理项不会出现，每条发现都附有证据。它适用于任何 CI；在 GitHub 上，还会在拉取请求中为每条发现添加行内评论 （查看演示拉取请求）。

在 GitHub 上，使用 archprint check Action（位于 GitHub Marketplace）：

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: Tommkruix/archprint-action@v1

它会检出拉取请求本身，因此无需单独的检出步骤。以下是不使用 Action、通过普通步骤运行相同检查的方法：

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - run: npx archprint check --base ${{ github.event.pull_request.base.sha }} --format github

• 默认仅警告。 添加 --fail-on new（或在 Action 中设置 fail-on: new），即可在出现新违规项时使任务失败；随后在分支保护中将该任务设为必需的状态检查，这样引入违规项的拉取请求就无法合并。

• 仅检查已采纳的规则。 check 会读取 .archprint/config.json 中由 init 和 generate 写入的已采纳规则，并且只检查其中记录的规则：机械规则，以及通过 --include-structural 采纳的层级边界规则。在同一个拉取请求中采纳的规则会列出，但不会据此判定该拉取请求违规。

• 无法解析的导入由 TypeScript 负责。 在 CI 中运行 tsc --noEmit，或使用 next build 默认运行的类型检查：它会根据项目自身的模块解析方式报告缺失模块（TS2307）。Archprint 不会生成这条规则；对于 TypeScript 应用，import/no-unresolved 或 dependency-cruiser 的 not-to-unresolvable 往往会在 paths 别名、包的 exports 和 ?raw 等打包器后缀上误报。

• 合理的例外需要说明理由。 如果文件确有原因需要违反规则，请记录下来： npx archprint allow AP-001 app/api/health/route.ts --reason "Health check queries the database directly"。 记录会写入 .archprint/config.json 的 allowed 列表；check 不再将其计入违规项，并会在拉取请求中列出该例外及其理由；下次运行 archprint generate 时，生成的规则也不会再将其标记为违规。没有理由的条目会被拒绝，不再需要的条目则会被指出。目前，dependency-cruiser（公共 API）强制执行的规则尚未涵盖这一侧。

• 移除规则绝不会悄无声息。 如果拉取请求删除了 .archprint/config.json，或删除了其中基准分支已有的规则，check 会发出警告，并列出所有不再检查的规则。它不会使任务失败，因为删除规则可能是团队有意作出的决定。若要确保此决定需要审核，请添加 CODEOWNERS 条目，并在分支保护中启用“要求 Code Owners 审核”：

  /.archprint/ @your-team
  /.github/workflows/ @your-team
  

• 升级： 从 0.8.x 或更早版本升级时，运行一次 archprint generate 以记录已采纳的规则。在此之前，check 会提示检查未运行并以状态码 0 退出。0.9.0 至 0.11.x 的配置可照常使用：check 仍会读取其中的 rules.json 和 allow.json，下次运行 generate 时会将两者迁移到 config.json。

• 其他 CI 系统： --format json 会输出以版本为键的数据，退出码是约定：0 表示正常，使用 --fail-on new 时，1 表示存在新违规项，2 表示 CI 配置有误（例如浅克隆中没有基准提交）。请检出完整历史记录（fetch-depth: 0 或 CI 系统中的等效设置）。

• 可安全用于来自 fork 的拉取请求。 它只需读取权限，不使用任何密钥，也绝不会运行你的代码。

MCP 配置

archprint mcp 会通过 stdio 将 Archprint 作为 MCP 服务运行，让 Agent 在编写代码前询问代码仓库已有的架构规则及其依据。它提供四个只读工具：archprint_scan、archprint_recommend、archprint_explain 和 archprint_check。每条规则都会以通俗易懂的文字说明，并附上依据、违反规则的文件，以及 archprint 是强制执行该规则、将其留待审查，还是仅作报告。archprint_explain 接受扫描结果中的任意规则标签（例如 AP-002 或 env-access）。archprint_check 会报告 Agent 当前改动（包括未提交的编辑）违反的已采纳规则，以便它在完成前修正。将 Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端指向它：

{
  "mcpServers": {
    "archprint": { "command": "npx", "args": ["-y", "archprint", "mcp"] }
  }
}

可以向 Agent 提出的问题。 无需指定工具；由 Agent 自行选择：

• “这个代码仓库已经遵循哪些架构规则？”
• “哪个文件违反了 env-access 规则，我该如何修复？”
• “我正在添加一个新的 API 路由。在这个代码库中，它应该遵循哪些规则？”
• “我们现在应该强制执行哪些规则，又有哪些规则值得采纳？”

你的代码会留在自己的机器上。 默认情况下，这是一个本地服务：它会读取你本地的检出内容，因此适用于私有代码；无论你使用哪个 Git 托管平台，源代码都不会离开你的机器。

如果服务无法启动。 如果客户端提示服务启动失败或找不到 npx，说明它无法读取你的 shell 的 PATH。从 Dock 或开始菜单打开的桌面应用不会加载该路径；如果 Node 来自 nvm 或 Homebrew，这种情况很常见。仅提供 npx 的完整路径还不够，因为 npx 本身需要在 PATH 中找到 node。将二者都指向 dirname "$(which node)" 输出的文件夹，例如 /opt/homebrew/bin：

{
  "mcpServers": {
    "archprint": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "archprint", "mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

从终端启动编辑器也可以，因为这样编辑器会继承你的 shell 的 PATH。

一行安装。 在 Claude Code 中：

claude mcp add archprint -- npx -y archprint mcp

在 Cursor 中，将上面的 JSON 放入项目中的 .cursor/mcp.json（若要应用于所有项目，则放入 ~/.cursor/mcp.json），然后在 Settings > MCP 下启用 archprint。

通过 URL 扫描公开代码仓库。 archprint mcp --http 会改为运行远程服务。它会将代码仓库浅克隆到临时目录，运行相同的只读分析，返回结果，然后删除克隆副本（仅支持 github.com、gitlab.com 和 bitbucket.org 上的公开 URL；不会写入或保留任何内容）。此时，工具会接收一个 repo URL（以及可选的 ref）。默认情况下，它会监听 0.0.0.0:8848/mcp（设置 --host 127.0.0.1 可将其限制在自己的机器上，或通过 --port/$PORT 更改端口），并在 /health（Cloud Run 会占用 /healthz，因此请使用此路径）和 /healthz 提供健康检查。每个请求都会克隆并扫描代码仓库，因此任何人都能访问的服务会代替任何人消耗计算资源：除非你愿意承担这项成本，否则请将其置于身份验证保护之后，例如使用 Cloud Run 的 IAM。

这些工具均为只读（绝不会写入代码仓库）；若要实际生成并强制执行规则，请使用 CLI 的 generate/wire。

对比

成熟的 TypeScript 工具（dependency-cruiser、eslint-plugin-boundaries、Nx、Sheriff、ts-arch）都强制执行你手动编写的架构规则。Archprint 会从实际导入图中推断规则，并在提出每条规则前，以统计证据作为门槛。随后，它会将规则导出为这些工具支持的格式，因此它能补充你的技术栈，而不是取而代之。

已根据各工具的文档（TypeScript 生态）进行验证。最关键的是其他 TypeScript 工具都无法填补的这两列：

工具	强制执行架构规则	自动从导入图中推断	附带统计证据
Archprint	是	是	是
dependency-cruiser	是	否	否
eslint-plugin-boundaries	是	否	否
@nx/enforce-module-boundaries	是	否	否
Sheriff	是	否	否
ts-arch	是	否	否
madge / knip	仅分析	否	否

坦诚地说：在其他生态中，Tach（Python）和 ArchLint（Java）也能自动推断模块边界，因此 Archprint 的特定定位是在 TypeScript 生态中实现自动推断并以统计证据作为门槛。Archprint 在检测能力上也与 dependency-cruiser（循环依赖、孤立项、可达性）和 knip（死代码）有所重叠；它不会与它们竞争，而是会以这些工具支持的格式编写生成的规则。

命令

• archprint init [path]：零配置设置。检测技术栈，强制执行代码当前遵循的规则， 并写入 .archprint/ 和一个受管理的 README 章节。选项：--expand、--include-structural、 --out <dir>、--fast、--force。
• archprint scan [path]：报告仓库当前遵循的规则，并提供依据。不做任何更改。 --deep 会沿着 barrel 和别名解析。
• archprint explain <id> [path]：显示一条规则的门控分析，为每个例外提供代码框，并说明 如何修复、何时不应使用以及如何强制执行。
• archprint recommend [path]：根据仓库证据和检测到的技术栈推荐一套规则（也适用于全新仓库），并指出 能写入的每条规则将由哪个已安装工具强制执行。
• archprint generate [path]：为仓库使用的代码检查工具，将自动信任的机械规则写入 .archprint/；结构规则则保留待审核。--emit <eslint|dependency-cruiser|all> 强制指定格式， --only <family> 和 --rules <ids> 可缩小输出范围（--rules 仅保留指定规则，例如 AP-002、import-style 或层级规则 no-lib-to-app），--check 会对仓库运行生成的规则， --readme 添加 README 章节，--expand 还会写入按类别划分的文件、卡片、夹具和图表，而 --rule <id> 则输出一条已审核的规则。还可使用 --include-structural、--no-graph、--out <dir>、--fast。
• archprint check [path]：与 --base <branch or commit> 指定的基准相比，报告更改引入的、违反已采用规则的情况。 默认仅发出警告，除非使用 --fail-on new。--format text|json|github、 --out <dir>。参见在 CI 中使用。
• archprint allow <rule> <file> --reason "..."：允许某个文件违反一条已采用的规则，并提供原因；记录在 .archprint/config.json 中。check 将不再计入此违规，并会在拉取请求中列出； generate 生成的规则也不再将其标记为违规。使用 --remove 可撤销豁免。
• archprint wire：通过受管理且可撤销的引用，将生成的规则关联到仓库使用的强制执行工具（flat eslint 配置、.dependency-cruiser.json）。--out <dir>、--dry-run。
• archprint eject：移除 Archprint 生成的文件、配置、受管理的 README 章节以及所有关联的引用，并将每项配置精确还原。--out <dir>、--dry-run。
• archprint migrate（别名 upgrade）：将旧版 archprint-rules/ 设置迁移到 .archprint/ 布局， 并就地重新关联配置。--dry-run。
• archprint mcp：将 Archprint 作为 MCP 服务运行，使 Claude、Cursor 和其他 Agent 能够调用只读的 scan、recommend、explain 和 check 工具。默认通过 stdio 提供服务；--http 会运行一个可通过 URL 扫描公开仓库的远程服务（scan、recommend 和 explain）。

scan --json、recommend --json 和 check --format json 会输出稳定且按版本标记的 JSON，供脚本使用。退出 代码即为约定：成功时为 0，出错时为 1（对于 check：使用 --fail-on new 时存在新增违规），如果 check 因 CI 设置问题无法运行，则为 2。

真实仓库示例

对 inbox-zero 进行真实扫描（apps/web，提交 11281be，包含 2,232 个 TypeScript 文件），并精简为每个章节的首批规则：

Scanned 2,232 TypeScript files
Workspace aliases: 18 resolved

GENERATED RULES
  AP-002  no-ui-layer-in-server-entry      confidence 97%
          A request handler must not import UI components.
          Evidence: 216 of 217 files it applies to follow it (99.5%)
          Exceptions: 1

LAYER BOUNDARIES (review before enforcing)
  utils !-> app  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 451 app file(s) depend on utils
          Exceptions: 3
  utils !-> components  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 160 components file(s) depend on utils
          Exceptions: 3
  hooks !-> app  layer boundary   confidence 94%
          Evidence: 65/65 hooks files conform (100%); 121 app file(s) depend on hooks

AP-002 属于机械规则类别，因此会自动生成为强制规则。层级边界是推断得出的，因此仅供审核，不会写入为强制规则，除非传入 --include-structural。所有数值 均根据导入关系图测得，而非估算。

采用你认可的层边界

由于文件夹名称可能被误认为一个层，因此会保留层边界供审核。阅读证据后，按 ID 采用你认可的边界：utils !-> app 会变为规则 no-utils-to-app。

# 1. Read the boundaries and their evidence
archprint scan apps/web

# 2. Write the rules you chose: AP-002 plus two of the boundaries above
archprint generate apps/web --include-structural --rules AP-002,no-utils-to-app,no-hooks-to-app

# 3. Reference the generated rules from your ESLint config (once)
archprint wire

如果不使用 dependency-cruiser，每条边界都会成为 .archprint/eslint.mjs 中的一条 ESLint 规则，例如 archprint/no-utils-to-app，无需额外插件；使用 dependency-cruiser 时，则会添加到其中。规则会豁免已经违反边界的文件，因此 lint 仍能通过；如果有新的导入跨越边界，无论使用相对路径还是别名，规则都会捕获。archprint check 会在拉取请求中报告新的违规，而 archprint allow 会记录有理由的例外。--rules 只保留它列出的规则，因此请在同一次运行中列出所有想要使用的规则。如果 CI 固定了 archprint 版本（例如 GitHub Action 的 archprint-version），请先在那里使用 0.13.0 或更高版本。规则参考 明确说明了规则会读取哪些导入和文件。

技术说明

快速模式与深度模式。 scan 默认执行快速说明符级扫描（不使用类型检查器）。generate 默认执行深度扫描，会解析 barrel 和工作区别名，因为生成是确定规则的关键步骤。结构分析（循环依赖、孤立项、可达性、公共 API）始终使用快速图：对于这些分析，快速图与深度解析结果一致；实际上，公共 API 检测必须使用快速图（深度解析会穿过 barrel 解析，从而抹去 barrel 与深层模块之间的信号）。

确定性。 同一版本的同一仓库会生成相同的输出。分析是纯粹且经过排序的；没有随机性，分析引擎也固定为精确版本。

状态

已发布到 npm，可安全地在真实仓库中运行。默认情况下，每条规则都必须经过审核；可通过一条命令撤销（archprint eject），且结果具有确定性。生成的规则在推导所依据的代码上必然通过。

• 已通过大规模验证： 最新普查（archprint 0.12.2，2026 年 10 月）对 92,861 个公开 TypeScript 仓库运行了 scan，没有发生崩溃；其中 494 个（0.5%）无法获取或运行超时，大多是已删除或规模极大的仓库。完整工作流（init、check、allow、generate、check、wire、eject）在一个分层抽样的 2,019 个仓库样本上运行：发现了一个 bug，问题出在 Next.js [id] 等路由文件夹中的例外情况，已在 0.12.3 中修复；运行成功的 2,012 个仓库在执行 eject 后都完全恢复原样。
• 现已可用于生产： scan 和 recommend、用于拉取请求的 check、以及对机械规则类别的自动强制执行，并具备生成时的一致性自检、面向全新仓库的 init 脚手架，以及对 React、Angular、Vue 和 Svelte 的框架支持。分析引擎（包含二十个检测器、置信度门槛，以及用于生成独立 ESLint 文件、dependency-cruiser、ts-arch 和层级图的生成器）已就绪并经过测试。
• 后续工作： 加强结构规则类别，为自动强制执行做好准备（可靠的逐文件角色置信度度量、层内聚性、角色分类器排序）。
• **版本仍处于 0.x，**因此 CLI 接口和规则格式可能会在次要版本之间调整。这是一个正在成熟的接口，而非实验性分析。精简的 .archprint/ 布局于 0.6.0 引入；archprint migrate 可原地升级较旧的配置。

配套基准测试 AgentRuleBench 直接衡量指导与强制执行之间的问题（对其测试的边界进行了预注册，并诚实地报告了未发现效果的结果）。

此处使用的术语

• 导入： 在一个文件中使用另一个文件代码的语句。Archprint 的规则规定哪些文件可以导入哪些文件。
• Lint 规则 / linter： 自动运行的代码检查（ESLint 是最常见的 linter），会在你编写代码时标记问题。
• AUTO / SUGGEST / REJECT： Archprint 对规则的置信程度；请参阅 它如何决定信任哪些内容。
• 机械型 / 结构型系列： 基于明确无歧义信号的规则（无需审核即可信任），与依赖推测文件夹用途的规则（留待你审核）。
• MCP： 一种开放标准，允许 AI Agent 使用 Archprint 等外部工具。

文档

完整文档见 tommkruix.github.io/archprint 和 docs/： 入门指南、概念（置信度门槛、机械型与结构型、快速与深入、生成／接入／移除的生命周期），以及 规则系列参考（各规则检测的内容、发布方式，以及不适用的情况）。

贡献

请参阅 CONTRIBUTING.md。项目会对自身运行 lint、类型检查和测试；每次更改都会确保覆盖率高于阈值，并附带一个 changeset。

许可证

MIT