文档 / 质量与治理

Gate 与治理中心

一个 gate 在每次提交、推送和流水线中强制执行契约，而治理中心汇集了完整的生命周期。

质量契约规定了团队的要求，gate 负责强制执行。它是引擎中的一条命令，Git hooks、CI、yuli-mcp gate 命令以及智能体的 hooks 都以相同方式使用它。结果与调用者无关。

命令

agent-engine gate --project <raíz> --stage pre-commit|commit-msg|pre-push|ci \
  [--message-file <archivo>] [--base <revisión>] [--format text|json]

如果省略 --project，则使用当前文件夹。没有 Git 的文件夹总是通过。

退出码 含义
0 通过。
1 被阻止：某项检查未通过。
2 用法错误。

各阶段检查的内容

阶段 比较对象 检查项
pre-commit 已加入 stage 的内容 下方所有检查。
commit-msg 提交信息 仅检查 AI 署名和豁免。
pre-push 与 @{upstream}（或 origin/HEAD）比较 下方所有检查。
ci 与 PR 或 MR 的目标分支（或 HEAD~1）比较 下方所有检查。

检查项

检查 Yuli 中的标签 结果
新增行中的机密 机密 阻止。报告类型和行号，绝不报告值。
测试中的作弊 测试完整性 如果配置档阻止作弊则阻止；否则警告。
更改规模 更改大小 严格执行时阻止；否则警告。
触及受保护的文件 受保护的路径 严格执行时阻止；否则警告。
提交信息中的 AI 署名 AI 署名 检查是否存在来自 AI 的 Co-Authored-By。
已过期的豁免 豁免 警告。绝不阻止。
没有测试的现有代码 安全网 警告。绝不阻止。

测试防作弊

急于完成的智能体可能会去“修复”测试，而不是修复代码。Yuli 能检测到这种情况。

在测试中：

  • 删除断言或删除测试。
  • 跳过测试：@Disabled、@Ignore、.skip(、xit、#[ignore]、pytest 或 unittest 的 skip、t.Skip。
  • 无意义的断言，如 assertTrue(true) 或 expect(true).toBe(true)。
  • 为让测试通过而修改期望值。
  • 在测试中使用捕获一切的 catch。

在构建和 CI 中：

  • 降低最低覆盖率。
  • 在构建中跳过测试。
  • 忽略失败，如 npm test || true。
  • 将测试脚本替换为空脚本。
  • 关闭质量关卡或禁用测试任务。

安全网

如果修改了没有特征化测试或单元测试的现有代码文件，gate 会发出警告：更改必须保持原有行为。它绝不会阻止提交。

安装 Git hooks

在治理中心的 关卡 标签页中，点击 安装 hooks。

  1. Yuli 写入 .githooks/pre-commit、.githooks/commit-msg 和 .githooks/pre-push。
  2. 配置 git config --local core.hooksPath .githooks。

如果 core.hooksPath 已指向其他工具（例如 husky），或者存在并非由 Yuli 写入的 hook，Yuli 不会安装任何内容。如果引擎不可用，hook 会发出警告并放行：绝不会让你无法提交。

卸载 hooks 会移除配置，并且只删除 Yuli 的脚本。

在 CI 中

由 创建 CI 生成的流水线包含“契约关卡”步骤，该步骤执行 agent-engine gate --stage ci。这样，CI 与你本地团队应用的是同一套规则。

治理中心

从右侧边栏（更多工具 → 治理中心）或命令面板中的 打开治理中心 打开。共有 10 个标签页。

标签页 内容
契约 关键性、阈值、受保护的路径、豁免、分层、SLO、许可证策略、独立评审者、数据分类、FinOps 预算和历史记录。
关卡 针对某个阶段运行 gate、安装或卸载 hooks，以及 CI 卡片。
敏感数据 离开你的电脑时被脱敏的值、代码中已分类的字段，以及 Git 历史中的机密。
分析 需求（EARS 模式、歧义、ISO 25010 属性、Gherkin）和术语表。
设计 决策（ADR）、威胁（STRIDE）、API（OpenAPI）、C4、SLO 和遗留系统。
度量 架构适应度函数、LCOM4、变更耦合、bus factor、技术债登记、twelve-factor 和 feature flags。
测试 不稳定测试与隔离、变异测试、测试类型、竞态条件和负载。
供应链 依赖与许可证、SBOM、IaC、容器、DAST、来源证明（SLSA、cosign）、CODEOWNERS 和历史记录。
交付 CI、发布、回滚、渐进式部署、runbook、事后复盘、DORA、SPACE、构建和 FinOps。
智能体 上下文、评审、遥测、学习、基准测试和注入。

生成的文档

文档 路径
ADR（架构决策记录） docs/architecture/adr/
STRIDE 威胁模型 docs/architecture/threat-model.md
C4 图 docs/architecture/c4.md
SBOM docs/reports/sbom.cdx.json 和 docs/reports/sbom.spdx.json
Runbook docs/operations/runbook.md
事后复盘 docs/operations/postmortems/

DORA

交付标签页会计算四项 DORA 指标：部署频率、lead time、变更失败率和 MTTR，并分为精英、高、中、低四个档次。它使用已记录的部署或 CI 数据。Yuli 无法看到生产环境的 APM。

独立评审

由另一个系列的模型评审更改。它绝不会使用与编写该更改的模型相同的系列。如果没有配置任何可用模型，会显示为不可用。在受监管和安全关键配置档中，独立评审是必需的。

所有智能体的上下文

在 智能体 → 上下文 中，“所有智能体的上下文”部分会为每个工具写入相同的规则：

目标 文件
Claude Code (CLAUDE.md) .claude/CLAUDE.md
AGENTS.md（Codex 及其他） AGENTS.md
Kiro (.kiro/steering) .kiro/steering/yuli.md
Antigravity .agent/rules/yuli.md
Cursor (.cursor/rules) .cursor/rules/yuli.mdc
GitHub Copilot .github/copilot-instructions.md
Gemini (GEMINI.md) GEMINI.md

内容写在受管理的区块中；你在区块之外写的内容会被保留。默认情况下这些文件不纳入 Git；可通过 纳入 Git 版本管理 启用。每个目标都会显示其状态：已是最新、已过时、不存在 或 已手动编辑。

习得的规则

当同一发现项在 30 天内的至少 2 个任务中出现 3 次或以上时，它会变成 .ai/rules/learned.md 中的一条规则。你可以在 智能体 → 学习 中拒绝它；只有当其证据翻倍时才会再次提出。

坦诚说明局限

  • DAST（OWASP ZAP）、容器扫描（Trivy 或 Grype）和签名（cosign）只有在已安装时才会运行，并且始终需要确认。如果缺失，Yuli 会如实说明，不会模拟结果。
  • 预防性规则和 IaC 规则基于文本模式。每个发现项都附带文件和行号，以便由人工确认。