合规规则（护栏）

合规规则是确定性检查，用于根据您的架构决策验证代码变更。它们强制执行命名约定、技术约束、层边界和安全模式——全程不涉及任何 AI。

在侧边栏中前往 代理中心 管理您的合规规则。

为什么需要合规规则？

AI 编程代理（Claude Code、Cursor、Copilot）生成代码时，并不了解您的架构决策。合规规则把这些决策编码为可执行的约束：

• 如果您的技术雷达规定使用 PostgreSQL，代理就不能使用 MongoDB
• 如果您的架构要求使用服务层，代理就不能在 HTTP handler 中直接调用数据库
• 如果您的团队使用结构化日志，代理就不能添加 fmt.Println

规则以确定性方式评估——没有 LLM，也没有概率性输出。相同的代码始终产生相同的结果。

规则类型

Archyl 支持七种合规规则类型：

必需模式

检查代码中必须存在或不得存在的模式。

配置：

• File glob — 仅检查匹配某个模式的文件（例如 *.go、*.{ts,tsx}）
• Forbidden patterns — 一旦匹配即触发违规的正则表达式模式
• Required patterns — 缺失时触发违规的正则表达式模式

文件 glob 支持花括号展开：*.{js,jsx,ts,tsx} 可匹配所有 JavaScript 和 TypeScript 文件。

命名约定

验证文件、类型和函数的命名模式。

配置：

• Patterns — 由范围（文件/类型/函数）+ 正则表达式 + 描述组成的列表

技术约束

限制容器中允许使用的语言和库。

配置：

• Allowed languages — 以逗号分隔的列表（例如 go, typescript）
• Forbidden imports — 每行一个导入

层边界

强制执行整洁架构、六边形架构或 DDD 的分层导入规则。

配置：

• Layers — 为每个层定义名称、路径模式（glob）以及允许的导入来源
• 点击层名称即可切换导入权限

契约合规

验证端点 handler 文件是否包含规范的 API 契约文档。

配置：

• Contract type — HTTP (OpenAPI)、gRPC、GraphQL 或 AsyncAPI
• Endpoint file patterns — 匹配包含端点定义的文件的 glob
• Strict mode — 启用后，任何缺少契约文档的匹配文件都会触发违规

依赖规则

禁止架构边界之间出现指定的导入路径。

配置：

• Scope — 容器级或组件级
• Forbidden pairs — 绝不能相互依赖的源路径与目标路径模式（例如 **/service/** -> **/handler/**）

事件通道合规

验证事件生产者/消费者模式是否遵循命名约定。

配置：

• Producer patterns — 识别事件生产代码的正则表达式模式（例如 kafka\.Send）
• Consumer patterns — 识别事件消费代码的正则表达式模式
• Topic regex — 有效 topic 名称必须匹配的模式（例如 ^[a-z]+\.[a-z]+\.[a-z]+$）

规则包

规则包是精心整理的规则集合，可一键安装。您无需逐条添加规则，只需安装一个规则包，即可获得适合您技术栈的完整规则集。

点击工具栏中的 Packs 浏览可用的规则包。

架构规则包

语言规则包

领域规则包

规则目录

Archyl 内置一个包含 169 条预置规则的目录，覆盖 23 种技术。在代理中心点击 浏览目录 即可查看。

覆盖的技术

Go、TypeScript、JavaScript、Python、Java、Kotlin、Rust、C#、C/C++、Ruby、PHP、Swift、React、Vue、Angular、Next.js、Docker、Kubernetes、Terraform、SQL、Shell、YAML、GitHub Actions

类别

点击目录中的任意规则即可添加——配置表单会自动预填。

严重级别

每条规则都有一个严重级别，决定其影响程度：

只要发现任何严重或高级别的违规，合规检查即判定为失败。中、低级别的违规会被报告，但不会导致检查失败。

合规仪表板

代理中心的 仪表板 标签页实时汇总您所有项目的合规检查情况。

显示内容

• 统计卡片 — 检查总数、通过率（按颜色区分）、通过数、失败数
• 通过 / 失败比 — 直观的比例条，一眼看清两者占比
• 最新检查横幅 — 显示最近一次检查的状态，并附有完整报告的链接
• 最近检查列表 — 列出所有检查，包括状态、触发类型、项目名称、文件数、违规数以及距今时间

筛选

使用顶部的项目下拉菜单按项目筛选检查，或选择“所有项目”查看全部。

检查报告

点击任意检查即可深入查看完整报告：

• 严重级别分布条 — 按比例展示严重/高/中/低各级别的违规
• 按文件分组的违规 — 可折叠的分区，列出每条违规的严重级别、标题、描述和修复建议
• 检查元数据 — 触发类型、提交 SHA、开始时间、耗时

每份检查报告都有独立的可分享 URL（例如 /agent/dashboard/:checkId）。

删除检查

使用多选批量删除检查：

1. 勾选单个检查旁的复选框，或使用“全选”
2. 点击随之出现的红色 Delete 按钮
3. 检查及其违规记录将被永久删除

CI/CD 集成

合规规则可以在每个拉取请求上自动运行。设置说明请参阅 GitHub Actions 集成。

工作原理

1. 在 GitHub 上创建或更新 PR
2. Archyl GitHub Action 获取变更的文件
3. 文件被发送到 Archyl API 进行评估
4. 结果以 PR 评论和提交状态检查的形式呈现
5. 如果发现严重或高级别的违规，工作流将失败

PR 评论

发现违规时，Archyl 会在 PR 上发布一条详细评论：

• 按严重级别统计违规数量的摘要表
• 按文件列出的违规，附带描述和建议
• 后续推送时会更新这条评论（而不是重复发布）

管理规则

创建规则

1. 点击 Packs 为您的技术栈安装精选规则集，或
2. 点击 浏览目录 从 169 条预置规则中浏览并添加，或
3. 点击 自定义规则 手动创建新规则

启用/禁用规则

切换任意规则旁的开关即可启用或禁用该规则。禁用的规则不会被评估。

编辑规则

点击任意规则上的编辑图标（铅笔）即可修改其名称、描述、严重级别或配置。

删除规则

点击删除图标（垃圾桶），然后确认。此操作无法撤销。

筛选规则

• 搜索 — 按规则名称或描述筛选
• 类型筛选 — 点击类型标签，仅显示特定类型的规则

MCP 集成

AI 代理可以通过 MCP 服务器访问合规规则：

可用的 MCP 工具

从代理运行检查

run_conformance_check 工具让 AI 代理能够在提交前验证代码。代理会发送它正在处理的文件：

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

响应包含：

• passed — 检查是否通过（没有严重/高级别违规）
• violations — 违规列表，包含严重级别、文件路径、标题和建议
• rulesEvaluated — 评估了哪些规则
• filesAnalyzed — 分析了多少个文件
• checkId — 检查 ID（可在仪表板中查看）

代理可以根据这些反馈，在提交代码之前修复违规。

代理上下文

MCP 工具 get_agent_context 会将所有生效的合规规则作为架构简报的一部分返回。在开始工作前调用该工具的 AI 代理会知道需要遵守哪些护栏。

REST API

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

所有端点都需要身份验证（JWT，或在执行变更操作时使用具有写入权限范围的 API 密钥）。