guard

@codapult/guard

面向 AI 编码 Agent 的架构护栏

@codapult/guard 是一款本地优先、与模型无关的面向 AI 编码 Agent 的架构护栏软件。它可用于检测架构偏移、强制执行已批准的软件架构规则，以及检查 JavaScript 和 TypeScript 项目中的代码变更。

Guard 会学习代码库的结构，将项目架构记录为可供审查的记忆，并依据团队批准的规则检查后续变更。它将 AI 编码 Agent 与这些规则相连，并在变更引入受规则覆盖的架构回归时，返回确定性证据。你可以在本地和 CI 中运行相同的项目专属检查。

看看一次变更的效果

假设某个 SaaS 项目已经确立了以下边界：

Client → Server Action → Service → Repository → Database

AI Agent 仍可能生成符合 TypeScript 规范、却跨越该边界的代码：

Client → Database

项目明确批准了匹配的导入规则或确定性契约后，Guard 就会检查变更文件，并以确定性方式报告匹配的违规：

Codapult Guard (changed files)
Scanned 1 source file(s); suppressed 12 baseline finding(s).

src/app/settings/page.tsx:1 [client-no-persistence-import]
  Client modules should not import persistence-layer modules.
  import: @/lib/db/client

✗ 1 issue(s) found
Exit code: 1

文件路径、规则 ID、消息和计数取决于项目。以下是实际 CLI 输出的格式：Guard 不会推断所有 Client → Database 关系都被禁止，也不会静默启用提案。团队先批准相关策略；随后，现有问题可以设为基线，而新匹配的违规则会导致门禁失败，并为 Agent 提供有界证据以便修复。

Guard 不会要求所有项目采用相同的架构。 它会发现项目现有的架构，再由团队决定哪些内容应成为策略。

核心功能适用于各种项目。最受优先支持的场景是 Next.js SaaS 和 AI 辅助开发，包括服务端／客户端边界、路由、持久化、身份验证、计费、后台任务、环境配置和 AI 集成。

Guard 存在的原因

AI Agent 可能会生成语法有效、却违反真实项目架构的代码：客户端组件导入仅限服务端使用的代码、新操作绕过既有的身份验证边界、路由直接写入数据库，或重复实现已有服务。

现有工具仍然必不可少，但它们解决的是不同的问题：

工具类别	核心问题	Guard 的作用
TypeScript	代码是否符合类型要求？	将项目的类型检查作为可选关卡。
ESLint / Biome	代码是否遵循语言和样式规则？	不重复实现它们的 lint 规则。
测试	行为是否符合可执行的预期？	启用时运行已配置的检查；不替代测试。
SAST / 依赖扫描器	是否存在已知的安全或依赖风险？	可连接适配器；专注于架构和变更影响。
PR 审查服务	审查者应考虑哪些语义问题？	为选定的 AI 主机生成范围明确、经过脱敏的审查资料包。
Guard	项目的架构是否在逐渐恶化？	维护项目专属的架构记忆和回归关卡。

安装

要求：Node.js >=20.19，以及 JavaScript 或 TypeScript 项目。

pnpm add -D @codapult/guard
# or
npm install --save-dev @codapult/guard

该软件包提供 codapult-guard 二进制文件：

pnpm exec codapult-guard init

npm 软件包的作用域为 @codapult/guard；为便于发现并与独立产品名称保持一致，可执行文件有意命名为 codapult-guard。

60 秒快速入门

在项目根目录运行：

# 1. Build the initial project model and baseline
pnpm exec codapult-guard init

# 2. Inspect only new and changed architecture findings
pnpm exec codapult-guard check --changed

# 3. Prepare deterministic context for an AI review
pnpm exec codapult-guard review --requirement docs/acceptance.md

# 4. Run the configured completion gate
pnpm exec codapult-guard verify --json

init 受到保护，不会覆盖现有基线。只有在有意替换项目记忆时才使用 init --force。使用 analyze 可刷新已发现的事实，而不重置基线。

运行模式

Guard 将事实、策略、验证和决策分开处理：

层级	包含内容	生成方式
事实	AST、文件、导入、依赖、路由、调用、能力、图、Git 历史	确定性的本地发现
策略	规则、契约、约定、基线	观察所得的提案加上团队的明确批准
验证	变更文件检查、影响分析、契约、项目检查、审查资料包	本地 CLI、MCP、CI 和现有项目工具
决策	通过、失败、警告、需要审查、未配置	开发者或使用 Guard 证据的 AI 主机

Guard 不假设项目采用固定的 UI → actions → services → repositories → database 架构。若项目实际呈现这种结构，它可以发现该结构；但只有经过明确批准，观察到的模式才会成为可强制执行的规则。

策略路径会按相对于项目的路径进行验证。Guard 会拒绝路径遍历、绝对路径，以及逃逸出项目根目录的符号链接；导入边界检查涵盖导入、重新导出和字面量动态导入。

策略范围与状态变更

Guard 在项目级别存储策略，而每项策略都可以针对更窄的边界：

策略项	范围控制
规则	files、导入模式和规则类型
契约	scope、entrypoints、导入/包约束和必需调用
预算	scope、指标、限值、严重性和书面理由
基线	已接受为历史债务的确切发现指纹
豁免	一个有效的发现指纹，以及负责人、理由和到期时间

常规检查不会更改源代码、规则、契约、基线或豁免。会更改策略的命令是明确的：init、rules approve、contracts approve|reject、baseline accept|remove 和 waiver add|renew|remove。analyze 会刷新派生的项目事实，而 verify 可能会运行项目配置的命令并记录本地运行清单；两者都不会更改已批准的策略。

有关完整的变更契约以及主机/CI 控制，请参阅 策略变更控制。

Guard 会发现什么

此模型具备框架感知能力，但不依赖特定框架：

领域	发现的证据示例
JavaScript / TypeScript	AST 模块、声明、调用、指令、别名、重新导出、动态导入
Next.js / React	App Router 路由、路由方法、Server Actions、客户端/服务端边界
API 边界	路由处理程序、API 模块、入口点、影响路径
数据	ORM 包、架构、迁移、仓库、持久化边界
能力	身份验证、支付、电子邮件、AI/RAG、队列、存储、缓存、搜索、分析、内容
运维	环境引用、配置、部署、可观测性、webhook
仓库结构	工作区、包脚本、依赖项、循环依赖、导入热点、Git 历史记录
测试	测试文件、测试脚本、工作区检查、已更改文件

能力只是证据，不是要求。Vite 应用、Express 服务、Hono 项目、Node 包、monorepo 或 Next.js SaaS 都可以使用相同的 Guard 核心。

Guard 是什么——又不是什么

Guard 是面向 AI 辅助开发的架构控制平面。它使用本地事实、已批准的策略和确定性验证，保护项目特定的边界并管理变更影响。

Guard 不能替代 ESLint、TypeScript、测试、SAST 或通用 PR 机器人。这些工具回答的问题各不相同；Guard 将它们的结果与 AI 编码 Agent 在更改仓库之前和之后所需的架构记忆联系起来。

常规循环

init once → edit → check --changed → review → verify → commit / merge
                         ↘ analyze after structural changes

1. init 构建项目记忆并建立初始基线。
2. check 扫描当前项目；check --changed 是快速的变更范围架构门禁。
3. review 为 AI 宿主准备范围受限且已脱敏的差异数据包；它不会调用大模型。
4. verify 运行 Guard 策略、已配置的项目检查、适配器、运行时诊断和契约验证。
5. audit 检查完整的当前状态，包括基线已接受的问题。

如需解释某项变更的影响，请使用 codapult-guard impact <file...> 或对应的 codapult_guard_impact MCP 工具。它会报告依赖图的两个方向：变更模块所用的内容，以及可能受影响的传递调用方。review 会为 AI 宿主附上相同的影响数据包，以及带类型标注的 Git 变更（added、modified、deleted 和 renamed）。

Guard 状态存储在 .codapult/guard/ 中：

.codapult/guard/
├── project.json       discovered project model
├── architecture.json  observed architecture and capabilities
├── conventions.json   recurring project conventions
├── rules.json         active and proposed deterministic rules
├── contracts.json     project-specific boundaries and required calls
├── proposals.json     evidence and approval history
├── baseline.json      accepted pre-existing findings
├── agent.json         AI-host completion-gate configuration
├── waivers.json       time-bounded exceptions to active findings
└── history/           project snapshots and local verification run manifests

团队需要共享防护规则时，请提交策略和基线文件。根据项目策略将缓存产物视为可丢弃内容，且切勿提交机密信息。

基线指纹不包含行号，因此格式调整和行位置移动不会重新产生相同的问题。指纹包含规则以及受影响文件／导入的标识，因此重命名或模块迁移可能会生成新的指纹，在将其纳入基线之前应明确审查。

临时豁免

基线记录 Guard 引入时已存在的历史问题。豁免则不同：它会暂时抑制一个当前问题，并且必须注明负责人、原因和到期日期。

codapult-guard waiver add <fingerprint> \
  --owner platform-team \
  --reason "Migration in progress" \
  --expires 2026-12-28
codapult-guard waiver list
codapult-guard waiver renew <id> --expires 2027-01-31 --reason "Migration continues"
codapult-guard waiver remove <id> --reason "Migration completed"

当豁免进入配置的提醒期限（默认 14 天）时，Guard 会发出警告。豁免到期后，原问题会重新生效。受保护的策略可以禁止通过 MCP 更改豁免，这样 Agent 可以提出豁免，但无法自行批准。豁免有意与特定指纹绑定；违反规则的代码一旦变更，豁免便会失效。

团队可以选择在 rules.json 中通过 waiverPolicy.maxDays 限制每次新建或续期豁免的有效期：

"waiverPolicy": { "warningDays": 14, "maxDays": 90 }

此限制适用于当前操作所申请的豁免期限；它不会静默删除或改写现有豁免。严重性为 error 的边界问题会导致 check 失败；警告问题和豁免到期提醒仍仅供参考。

运行 codapult-guard doctor 可检测客户端或软件包边界是否被明确降级。Doctor 会将其报告为警告，不会更改项目策略。

可选的范围预算

预算属于策略，而非通用风格规则。仅在指定风险边界（例如服务、路由处理程序或依赖繁重的模块）时添加预算：

{
  "id": "service-lines",
  "description": "Services must remain reviewable.",
  "metric": "lines",
  "scope": ["src/services"],
  "limit": 300,
  "severity": "warning",
  "reason": "Keep service changes reviewable by one owner.",
  "status": "active"
}

请将预算放在 .codapult/guard/rules.json 的 budgets 数组中。支持的度量指标包括 lines、bytes 和 imports。除非在 scope 中明确包含，否则不会检查生成文件、架构、迁移文件和其他路径；* 这样的通配符可用于有意覆盖项目根目录。无效的绝对路径、父目录路径或不存在的范围都会导致 Guard 门禁失败。更改预算属于策略决策： 请审查差异并更新其书面 reason，不要静默提高限额。

AI Agent 与 MCP

Guard 刻意保持模型无关。它不会将源代码发送给远程 LLM，也不会自行编辑源文件。AI 主机负责模型调用、权限、修复循环和最终决策。

通过 stdio 启动独立 MCP 服务：

pnpm exec codapult-guard mcp-server

在项目根目录中，将该命令注册到 MCP 客户端。例如，Cursor 可以使用 .cursor/mcp.json：

{
  "mcpServers": {
    "codapult-guard": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "codapult-guard", "mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

对于支持通用 stdio 服务的客户端，使用相同的命令，并将其工作目录设为项目根目录。Guard 只读取本地文件；不需要 API 密钥或模型提供商。特定主机的示例见 docs/integrations/。

推荐的 Agent 工作流：

task finished
  → codapult_guard_next_action
  → codapult_guard_context
  → codapult_guard_review(requirement, diff)
  → codapult_guard_verify
  → repair reported failures
  → repeat until pass or bounded iteration limit

codapult_guard_context 会让主机明确了解项目状态：observations 仅包含已发现的事实，proposals.pendingRules 和 proposals.pendingContracts 是尚未批准的策略建议，policy 仅包含生效的规则、合约以及基线和豁免状态，verification 则报告检查是否实际运行过。若上下文响应中的 verification.status: "not-run" 且 findings: null，这并不表示检查通过。

有关 Cursor、Claude Code、Codex、Gemini CLI、GitHub Copilot 和通用主机的信息，请参阅 docs/integrations/。

MCP 注册表

Guard 已发布到官方 MCP 注册表，服务器名称为 io.github.codapult/guard。该注册表是已发布的 @codapult/guard npm 包及其 stdio MCP 服务的发现层；它不会取代 npm 安装或上述特定主机的配置。若要进行确定性设置，请直接安装 npm 包，并使用下方所示的 MCP 配置。

对于作者 Agent 不得批准自身策略建议的工作流，请在 rules.json 中将 Guard 设为受保护模式：

{
  "approval": {
    "mode": "protected",
    "allowMcpApproval": false,
    "requireDistinctActor": true
  }
}

此时，MCP 可以读取并提出策略建议，而批准操作通过 CLI 或受保护的 CI/PR 流程进行。启用 requireDistinctActor 后，CLI 和获准的 MCP 批准操作都需要设置 GUARD_APPROVER；如果提案是通过 GUARD_PROPOSER 生成的，Guard 会拒绝相同的声明操作者。这些变量仅提供声明的来源信息；变更由谁批准，仍需依靠外部分支保护或签名身份来证明。

根据受保护策略进行验证

在 CI 中，应使用受保护的基准提交中的策略来验证拉取请求，而不是使用分支携带的副本：

codapult-guard verify --policy-base "$BASE_SHA" --json

随后，Guard 会使用基准提交中的规则、合约、基线、豁免和完成门禁配置来评估已更改的源代码。结果会报告 policy.source、policy.ref、policy.revision、policy.fingerprint，以及检出版本中的策略是否与该基准不同。分支无法放宽自身策略或禁用门禁，再用放宽后的副本完成同一次验证。

随附的 docs/guard-ci.yml 会获取完整 Git 历史，并自动传入拉取请求的基准 SHA。如果策略变更需要单独审批，请使用 CODEOWNERS 或同等审查控制来保护 .codapult/guard/。例如，仓库可以在 CODEOWNERS 中添加 .codapult/guard/* @architecture-owners。Guard 会报告策略变更；审查者授权由托管平台负责执行。

若要在本次调用中明确将策略变更判定为失败，请添加：

codapult-guard verify --policy-base "$BASE_SHA" --fail-on-policy-change

这适用于专门的策略审查门禁。此设置与使用基准策略进行源代码验证相互独立，因此团队可以自行选择如何在受保护的审查工作流中处理已批准的策略更新。

支持的 AI 主机、CI/PR、策略包、工具适配器、审批治理和可观测性集成，请参阅扩展映射。

CI

将使用者工作流复制到已安装并初始化 Guard 的项目中：

cp node_modules/@codapult/guard/docs/guard-ci.yml .github/workflows/guard.yml

也可以从 docs/guard-ci.yml 复制。该工作流会运行项目验证，并将 Guard 检查结果导出为 SARIF，供 GitHub 代码扫描使用。拉取请求会在不运行生命周期脚本的情况下安装依赖项，并使用确定性的 Guard 检查，不执行由 PR 提供的脚本；受信任的推送则可以运行已配置的项目检查。

软件包仓库会在 .github/workflows/ci.yml 中单独运行自己的单元测试、类型检查、构建和打包检查；而 fixture 工作流则会在真实的项目结构中测试 Guard。

CLI 命令

命令	用途
init	创建项目记忆和初始基线。
analyze	刷新事实，不更改策略或基线。
propose	生成基于证据的规则和契约提案。
check [--changed]	执行有效策略；--changed 将检查结果限制在已更改和未跟踪的文件中。
audit	扫描当前项目的全部内容，包括基线检查结果。
review	为 AI 主机创建范围受限的语义审查包。
verify	运行已配置的完成门禁。
governance	审计已声明的提案／审批来源及决策到运行的可达性。
doctor	诊断无效或缺失的 Guard 产物。
history / history-diff	检查项目模型、模块图和架构边的演变。
impact <files...>	说明文件所影响的依赖项、传递依赖项、功能和契约。
policy explain <id>	说明策略项、其证据和审批历史。
rules / contracts	审批规则；审批或驳回契约。
baseline	审查或有意接受现有检查结果。
waiver	管理归属到负责人、具有时限且针对确切检查结果的例外。

结构发生变化后，请运行 analyze --refresh。doctor --fix-cache 只会删除可丢弃的发现缓存；它不会更改规则、契约、基线或源文件。

Guard 状态可供并发的 CLI／MCP 读取者和写入者安全使用：派生事实以原子代次发布，策略更新使用修订版本，并会等待短暂的写入争用。若进程持有状态锁时意外终止，系统会通过其本地 PID 检测到该情况并恢复锁；若集成需要立即收到争用反馈，请使用 --no-wait。

运行 pnpm exec codapult-guard <command> --help，查看特定命令的选项。 每次运行 verify 还会在 .codapult/guard/history/runs/<run-id>.json 下写入一份本地清单。清单记录各阶段耗时、结果，以及决定结果的策略门禁。它还会记录生效策略的修订版本和指纹；如果提供了基准 ref，也会记录该 ref，以及工作树中的策略是否有所不同。如果某项获批的策略决策促成了当前策略，清单还会保留该决策 ID，从而可以从审批追溯到验证。governance 命令会审计这些元数据，并报告缺失或重叠的声明参与者。清单不包含源代码或外部遥测数据。这些清单让失败的运行过程可解释，同时不会将 Guard 变成生产级追踪系统或身份／签名账本。

清单还包含一个 verification-receipt 对象。这是一份精简的机器可读记录，包含提交、策略基准和指纹、决策 ID、检查状态、发现项数量、契约问题、豁免状态以及 Guard 版本。它有意不包含命令输出和源代码。该回执描述的是 Guard 作出的决定，并非加密签名或 CI 身份证明。提供策略基准时，它会将基准差异与工作树中的脏文件分开记录，避免本地验证悄然呈现不完整的变更集。

安全与数据处理

• 确定性的发现和检查均在本地运行。
• 审查数据包大小有限，并会在返回给 AI 宿主前对常见机密信息进行脱敏。
• Guard 不会调用大模型，也不需要提供方 API 密钥。
• 只有在项目配置启用后，才会运行项目命令和外部适配器。
• 现有发现项可以设为基线，但新的回归仍会清晰呈现。

验证与证明

该仓库通过多个层面验证产品：

• 针对发现、策略、基线、验证、MCP 和输出的单元测试与集成测试；
• 针对别名、重新导出、动态导入和路由边界的 AST 对抗性用例；
• 从违规到修复的端到端黄金流程；
• 在真实 Next.js、React/Vite、Node、Hono、monorepo 和 Express 仓库中进行变更回归检查；
• npm pack 检查，确保发布的制品仅包含预期的构建输出。

在本地运行维护者检查：

pnpm test
pnpm test:guard:golden
pnpm test:guard:fixtures
pnpm test:guard:fixtures:regression
pnpm release:check

文档

• 完整的 Guard 指南
• AI Agent 集成
• 宿主集成
• CI 消费方工作流
• 夹具矩阵
• 发布流程

了解更多 Codapult

想从头开始构建 SaaS？Codapult 是一个可用于生产环境的 Next.js SaaS 基础方案，专为 AI 辅助开发打造，具备 MCP 上下文、内置 AI、模块化架构，并让源代码由你掌控。

许可证

MIT。请参阅 LICENSE。