AI-RULES

AI-RULES 是一款具备规则感知能力的命令行工具，专为 AI 辅助的代码治理而设计。它能够将 Markdown 格式的项目规则转化为结构化的规则元数据、轻量级本地证据以及确定性的审计与修复提示，从而帮助 AI 编码助手更一致地遵循你的架构、设计模式和 UI 标准。

为什么选择 AI-RULES

AI 编码助手功能强大，但它们往往生成的是“大致正确”的代码，而非完全符合你仓库实际架构的代码。例如，它们可能会从 UI 组件中直接调用数据层、绕过服务边界、忽略项目特定的目录结构，在日志中泄露敏感信息，或者返回下游修复流程无法可靠处理的审计报告格式。

AI-RULES 在代码进入评审、CI 或合并门禁之前，为这些助手提供一份针对项目的操作契约。它将你的工程标准打包成 .ai-rules.md、rules-config.json 和 config.json 文件，然后将其转化为具有规则感知能力的审计和修复提示，包括启用的规则、严重性阈值、本地证据、路径别名、例外情况以及修复指导。

其实际好处包括：

• AI 生成的代码从一开始就更有可能遵循你的架构和分层规则。
• 代码评审速度加快，因为重复出现的违规行为只需在规则中定义一次，而无需每次都进行解释。
• 提示更加确定性，因为规则、路径、严重性和报告格式都经过结构化处理。
• 非标准的仓库布局可以通过 config.json 中的路径别名来处理，而无需修改每一条规则。
• 审计和修复工作流在 Codex、Cursor、Claude Code 或任何基于提示的编码环境中都更加稳定。

简而言之：仓库治理工具保护的是合并边界；而 AI-RULES 则是在 AI 编写和修复代码的过程中对其进行引导。

功能概述

• 初始化适用于不同技术栈的可复用规则模板
• 解析 .ai-rules/.ai-rules.md 和 rules-config.json
• 合并规则和配置中的 extends 链
• 根据模板默认值、检测到的项目配置以及本地的 AI-RULES 覆盖，解析高级 AST 配置
• 收集用于 regex 和 import/include 类型规则的轻量级本地证据
• 收集用于 function-lines 和 params-count 等最小化计数规则的轻量级本地证据
• 收集支持的前端 JS/TS/Vue 规则的 AST 支持的本地证据
• 支持配置级别的 thresholds，以实现参数化的规则行为
• 支持配置级别的 exceptions，用于按规则模式抑制已知安全的文件
• 生成具有规则感知能力的审计提示，而非静态提示文本
• 对 ai-rule-report.json 进行规范化和验证
• 结合报告和本地规则元数据，生成更强的修复提示

高价值内置覆盖范围

当前的模板除了原始的架构基线之外，还覆盖了一批高优先级的工程规则。

前端 / React / Vue

• 现已支持部分 JS/TS 规则的 AST 支持的本地证据
• UI 代码不得直接调用网络或数据层
• 通过 innerHTML 或 dangerouslySetInnerHTML 直接注入 HTML 的行为会被标记，并可生成 AST 支持的本地证据
• 从不受信任的富内容流向 DOM 汇的语义 XSS 流会被指出
• 通过 eval() 或 Function() 进行动态执行的行为会被标记，并可生成 AST 支持的本地证据
• 硬编码的前端密钥或 API 密钥会被标记
• 未使用 SRI 的第三方 HTML 脚本标签会被标记
• Hooks 必须遵守 React Hook 调用规则
• React 列表不应使用数组索引作为 key，对于支持的 React 文件，可生成 AST 支持的本地证据
• React 基于 Effect 的远程请求应使用稳定的依赖控制
• Vue computed 属性必须保持纯函数特性
• Vue props 不得被直接修改，对于支持的 .vue 文件，可生成 AST 支持的本地证据
• Vue 列表不应使用循环索引作为 :key，对于支持的 .vue 文件，可生成 AST 支持的本地证据
• 不建议在 Vue 组件中直接访问 DOM

Python 基础 / FastAPI

• 建议避免使用裸 except 和广泛捕获异常
• 可变默认参数会被标记
• 弱密码哈希算法如 MD5/SHA1 会被标记
• 可能泄露敏感信息的日志记录模式会被标记
• 外部 HTTP 调用应明确设置超时时间
• Python 函数的行数应低于配置的阈值
• Python 函数的参数数量应低于配置的阈值
• FastAPI 路由不应直接访问数据库会话或存储库
• 在 FastAPI 代码中通过插值或拼接构建的 SQL 查询会被标记
• FastAPI 请求日志应避免记录令牌、Cookie、认证头和明文凭据
• FastAPI 端点应使用 Pydantic 输入模型
• FastAPI 端点应明确声明 response_model
• 列表形式的 FastAPI 端点应强制实施分页或限制返回结果的数量
• 异步路径应避免阻塞 HTTP 客户端和使用 time.sleep

Java / Spring

• 控制器不应直接依赖于存储库
• 控制器应保持精简，避免业务分支和编排逻辑
• @Valid 应用于 @RequestBody 输入校验
• 过于宽松的 CORS 配置会被标记
• 可能泄露堆栈跟踪的异常处理器会被标记
• 可能暴露凭证的日志记录模式会被标记
• 敏感的 Spring 端点应有明确的认证和授权保护
• 过于宽松的 Spring Security 配置，如广泛的 permitAll() 或全局保护关闭，会被标记
• 写操作应明确事务边界
• @Transactional 注解不应出现在控制器上
• 写操作相关的服务逻辑应保持明确的事务语义
• 循环不应在没有批处理、超时和并发控制的情况下进行无限制的远程调用
• 业务异常应与系统或基础设施故障区分开

当前范围

AI-RULES 尚未成为完整的静态分析引擎。

• regex 和 import/include 检测可以收集本地证据
• 最小化计数检测可以收集 function-lines 和 params-count 的本地证据
• 部分前端 ast 规则现在可以生成解析器支持的本地证据
• 不支持的 ast 规则和语义规则仍然由 AI 引导，并被视为 ai-only
• CLI 帮助组织上下文和输出，而最终的审计决策仍由 AI 做出。

语言支持

内置的本地化文件支持以下语言：

• zh-CN: 简体中文，完整
• en: 英文，完整
• zh-TW: 繁体中文，部分支持，回退至英文
• ja: 日文，部分支持，回退至英文
• ko: 韩文，部分支持，回退至英文
• es: 西班牙文，部分支持，回退至英文
• fr: 法文，部分支持，回退至英文

目前，这些部分支持的语言仅翻译核心模板名称和提示说明。缺失的规则级别文本会自动回退到英文，以便在翻译逐步完善的同时，新语言也能继续使用。

安装

需要 Node.js >=18。

全局安装：

npm install -g ai-law

或者在本仓库中进行本地开发时：

npm install
npm test

快速入门

cd your-project

# 1. 在当前项目中初始化规则
ai-law init

# 2. 检查规则/配置是否有效
ai-law doctor

# 3. 生成一个基于规则的审计提示
ai-law audit

# 4. 默认情况下，`audit` 还会写入本地辅助文件：
#    - .ai-rules/cache/audit-context.json
#    - .ai-rules/cache/ai-rule-report.template.json

# 5. 或者直接检查结构化的审计上下文
ai-law audit --json

# 6. 也可以选择强制刷新上下文转储
ai-law audit --dump-context

# 7. 当您的 AI 工具生成 `ai-rule-report.json` 后，对其进行验证
ai-law validate-report

# 8. 为某个问题生成修复提示
ai-law fix --issueId ISSUE-001

# 9. 或者为整个报告生成分组修复提示
ai-law fix --all --group-by-rule

工作流程

1. 初始化

ai-law init 会在您的项目中创建 .ai-rules/ 目录，并根据所选模板生成相关文件。

示例目录结构：

.ai-rules/
├── .ai-rules.md
├── rules-config.json
├── config.json
├── base/
│   ├── .ai-rules.md
│   ├── rules-config.json
│   └── config.json
└── cache/
    ├── audit-context.json
    └── ai-rule-report.template.json

2. 验证本地规则设置

ai-law doctor 会验证以下内容：

• .ai-rules/ 目录是否存在
• rules-config.json 是否可以加载并支持 extends 继承
• 规则文件是否可以正确解析
• enabledRuleIds 是否指向有效的规则
• 规则的作用范围与配置范围是否匹配
• 规则中是否包含必需字段

使用 ai-law doctor --strict 可将警告视为错误。

3. 生成审计上下文

ai-law audit 现在会读取当前项目的规则，并基于以下内容构建提示：

• 合并后的配置
• 解析后的规则
• 启用的规则 ID
• 本地证据候选
• 严格的报告格式要求

常用选项：

ai-law audit --locale zh-CN
ai-law audit --json
ai-law audit --summary
ai-law audit --dry-run
ai-law audit --dump-context

--json 会输出结构化的审计上下文，而不是提示文本。

默认情况下，ai-law audit 会写入：

• .ai-rules/cache/audit-context.json
• .ai-rules/cache/ai-rule-report.template.json

您可以将生成的提示提交给您的 AI 工具，并将 AI 的结果保存为 ai-rule-report.json 文件到项目根目录下。

--dump-context 会强制重新写入 .ai-rules/cache/audit-context.json。 --summary 会打印启用的规则数量、本地与 AI 的覆盖情况、被抑制的文件以及配置的阈值。 --dry-run 会打印包含/排除模式、可在本地运行的规则 ID、仅由 AI 处理的规则 ID 以及生效的异常模式。

审计报告示例：AI 返回一个结构化的 ai-rule-report.json 文件，该文件可以被验证，并用于下一步的修复工作。

4. 验证 AI 报告

当您的 AI 工具返回 ai-rule-report.json 后，运行以下命令：

ai-law validate-report

此命令会将旧版或偏离标准的报告格式规范化为稳定的结构，并检查是否存在以下问题：

• 缺少 issueId
• 缺少 ruleId
• 重复的 issueId
• 无效的 severity

您可以通过以下命令查看规范化的报告：

ai-law validate-report --json

5. 生成修复提示

ai-law fix 现在会结合以下内容：

• 规范化的报告数据
• 来自 .ai-rules 的本地规则元数据
• 规则的意图/要求/修复指导
• 上下文资产
• 报告中的证据和代码片段（如果存在）

示例：

ai-law fix --issueId ISSUE-001
ai-law fix --id ARCH-101
ai-law fix --all
ai-law fix --all --group-by-rule

修复提示示例：ai-law fix 将报告中的一个或多个条目转化为专注于修复的提示，其中包含规则上下文和证据。

规则模型

规则在 .ai-rules.md 中以 RULE 块的形式定义。CLI 目前会解析以下字段：

• RULE
• severity
• scope
• intent
• fix
• detect
• prompt
• context
• extends

示例：

### RULE: ARCH-101
severity: FATAL
scope: ui
intent: UI 组件不得直接发起网络请求。

detect:
  regex: "fetch\\(|axios\\."
  where: filePath in src/components/**
fix: 将请求逻辑移至服务层。
prompt:
  violation: 在 UI 层检测到直接请求逻辑。
  requirement: UI 组件不应包含请求逻辑。
  solution: 将请求移到服务层，并复用共享的客户端。
context:
  - src/services/
  - src/api/client.ts

项目路径配置

模板可以提供一个可选的 .ai-rules/config.json 文件，用于用户自定义的项目布局覆盖。该文件会与 rules-config.json 合并，因此用户可以在不修改每条规则的情况下调整目录约定。

示例：

{
  "pathAliases": {
    "@controller": "app/controllers",
    "@service": "app/services",
    "@repository": "app/repositories",
    "@config": "app/config"
  }
}

规则可以在 context、detect.where、detect.import 和 detect.include 中引用这些别名：

detect:
  include: "@repository/**"
  where: filePath in @controller/**
context:
  - @service

在审计或修复时，CLI 会在收集证据或构建提示之前解析这些别名。

ai-law doctor 和 ai-law audit 会在配置的别名指向不存在的路径时发出显著警告。如果发生这种情况，请打开 .ai-rules/config.json 并调整 pathAliases 以匹配您的仓库布局。

检测支持

目前 CLI 支持的功能包括：

• detect.regex：支持本地证据收集
• detect.import：支持本地证据收集
• detect.include：支持本地证据收集
• detect.ast：首批基于前端 AST 的规则现已支持本地证据收集
• detect.semantic：目前仅由 AI 处理

当前基于 AST 的本地证据主要针对前端 JS/TS 项目，涵盖第一批狭窄范围的规则：

• UI 入口代码中直接发起的网络请求，如 fetch() / axios.*
• 原生 HTML 注入，如 dangerouslySetInnerHTML / innerHTML
• 动态代码执行，如 eval() / Function()
• React 列表渲染时使用循环索引作为 key
• Vue 在 .vue 脚本块中修改 props
• Vue 在 .vue 模板中使用循环索引作为列表 key
• TypeScript 文件中使用 any 类型

这意味着 CLI 现在可以为正则表达式/导入/包含/计数等规则以及第一批基于 AST 的前端规则附上具体的本地证据，同时仍然允许通过 AI 引导来审查更高层次的语义约束和不支持 AST 的规则。

当前的模板有意混合了：

• 针对明显反模式的快速本地规则
• 针对更高层次架构或事务性推理的语义 AI 引导规则

配置扩展

配置模型现在支持两种规则感知的扩展：

ast

用于高级 AST 后端编排。AI-RULES 有意将此配置保持得尽可能小，并在运行时将其与检测到的项目配置合并。

示例：

{
  "ast": {
    "provider": "babel",
    "target": "react",
    "useProjectConfig": true,
    "parserOptions": {
      "sourceType": "module",
      "plugins": ["jsx", "typescript"]
    }
  }
}

在运行时，AI-RULES 按以下顺序解析 AST 设置：

1. 模板默认值
2. 检测到的项目配置，例如 tsconfig.json、.babelrc 或 package.json#babel
3. 本地 .ai-rules/config.json 中的覆盖设置

thresholds

用于可配置的数值限制，本地计数规则可以引用这些限制。

示例：

{
  "thresholds": {
    "maxFunctionLines": 80,
    "maxParamsCount": 5,
    "maxListLimit": 100
  }
}

exceptions

用于在本地证据收集过程中，针对匹配的规则 ID 或规则 ID 模式，抑制已知安全的文件。

示例：

{
  "exceptions": {
    "ARCH-101": [
      "src/integrations/**"
    ],
    "SEC-*": [
      "__mocks__/**",
      "**/*.stories.tsx"
    ]
  }
}

这些异常目前会影响支持的本地检测模式下的本地证据收集。

报告结构

审计提示要求使用严格的 JSON 格式，并采用规范化的结构，如下所示：

{
  "version": "1.1",
  "generatedAt": "2026-03-30T12:00:00Z",
  "project": {
    "cwd": ".",
    "stack": "react-ts"
  },
  "summary": {
    "total": 1,
    "fatal": 0,
    "warn": 1,
    "info": 0
  },
  "violations": [
    {
      "issueId": "ISSUE-001",
      "ruleId": "ARCH-101",
      "severity": "WARN",
      "confidence": 0.82,
      "file": "src/pages/Home.tsx",
      "line": 12,
      "snippet": "const data = fetch('/api')",
      "description": "在 UI 层中发现了直接的网络请求。",
      "fixSuggestion": "将请求逻辑移至服务层。",
      "repairPrompt": "提供一个最小的补丁……",
      "evidence": {
        "source": "local-regex",
        "matchedBy": "detect.regex"
      },
      "context": [
        "src/services/"
      ]
    }
  ]
}

模板

当前模板：

• frontend-base
  • react-js
  • react-ts
  • vue
• python-base
  • python-fastapi
• java-base
  • java-spring
• c-cpp

分支模板通过 extends 继承自基础模板。

CLI 命令

ai-law init
ai-law audit [--locale <code>] [--json] [--summary] [--dry-run] [--dump-context]
ai-law fix --issueId <issue_id>
ai-law fix --id <rule_id>
ai-law fix --all [--group-by-rule]
ai-law doctor [--strict]
ai-law validate-report [--json] [--path <file>]
ai-law setup [--locale <code>] [--provider <name>] [--write]
ai-law -v
ai-law -h

开发说明

当前实现层次：

• cli/src/core/config: 配置加载和 extends 合并
• cli/src/core/rules: 规则解析和验证
• cli/src/core/evidence: 本地证据收集
• cli/src/core/prompt: 审计提示组装
• cli/src/core/report: 报告规范化和模式

运行测试：

npm test

文档

• 英文设计规范：design/design-spec-en.md
• 中文设计文档：design/design-spec-zh.md

AI-RULES 快速上手指南

AI-RULES 是一款面向 AI 辅助编程的治理工具。它能将项目规范（Markdown 格式）转化为结构化的规则元数据和本地证据，生成确定性的审计与修复提示词，确保 AI 生成的代码严格遵循您的架构设计、分层原则及 UI 标准。

环境准备

• Node.js: 版本需 >=18
• 包管理器: npm, yarn 或 pnpm
• 项目依赖: 无特殊前置依赖，直接安装即可使用

国内加速建议：若下载缓慢，可配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

推荐全局安装以便在任何项目中直接使用：

npm install -g ai-law

若需在本地开发或调试，可在项目根目录执行：

npm install

基本使用

以下是从零开始集成 AI-RULES 的核心工作流：

1. 初始化规则

在项目根目录运行以下命令，生成 .ai-rules/ 目录及默认规则模板（包含 .ai-rules.md, rules-config.json 等）：

cd your-project
ai-law init

2. 检查配置有效性

验证规则文件语法、依赖链及配置项是否正确：

ai-law doctor

3. 生成审计提示词

读取当前项目规则与代码特征，生成包含本地证据的结构化审计提示词。同时会缓存上下文文件至 .ai-rules/cache/：

ai-law audit

可选：查看结构化 JSON 上下文

ai-law audit --json

操作指引：将 ai-law audit 输出的提示词发送给您的 AI 编程助手（如 Cursor, Claude Code 等），要求 AI 返回符合规范的 ai-rule-report.json 报告文件。

4. 验证 AI 报告

当 AI 生成 ai-rule-report.json 后，运行此命令校验报告格式（如 issueId 唯一性、严重等级合法性等）并标准化数据结构：

ai-law validate-report

5. 生成修复提示词

基于验证后的报告，生成针对性的代码修复提示词。

修复单个问题：

ai-law fix --issueId ISSUE-001

批量修复所有问题（按规则分组）：

ai-law fix --all --group-by-rule

将生成的修复提示词再次发送给 AI，即可完成符合项目规范的代码修正。