validator-setup

/validator-setup

扫描项目，发现工具，并为 agent-validator 配置检查和评审。

开始之前，请先阅读 references/check-catalog.md，了解检查类别详情、YAML 架构和配置示例。

步骤 1：检查配置是否存在

读取 .validator/config.yml。如果文件不存在，请告知用户先运行 agent-validate init，然后停止——不要继续执行后续步骤。

步骤 2：检查现有配置

读取 .validator/config.yml 中的 entry_points 字段。

在判断项目是否已配置之前，请检查 .validator/ 的 git 状态：

• 如果这是一个 git 仓库，运行 git status --porcelain -- .validator。
• 如果 .validator/ 或 .validator/config.yml 是未跟踪或新添加的，则视为全新安装，即使该目录已存在也是如此。agent-validate init 会先创建脚手架；/validator-setup 仍需配置检查和入口点。
• 如果无法使用 git、项目不是 git 仓库，或者状态不明确，不要声称 Agent Validator 之前已完成设置。请询问用户这是全新安装，还是他们想修改现有配置。

不要仅仅因为 .validator/ 存在，就得出“不需要处理”或“已完成设置”的结论。只有已提交的配置包含有实际内容的入口点/检查，或用户确认这是现有配置时，才能将项目视为已完成设置。

如果 entry_points 为空（[]），或仅包含生成的根入口点（path: "."）且没有 checks： 这是全新设置。继续执行步骤 3（检测项目结构）。除非用户明确要求重新配置评审，否则保留该生成的根入口点上已有的 reviews。

如果 entry_points 已有内容： 向用户展示当前配置摘要：

• 列出每个入口点的 path、checks 和 reviews

• 然后询问用户要执行哪项操作：

  1. 添加检查 — 扫描尚未配置的工具。继续执行步骤 3，但过滤掉 entry_points 中已有的检查。
  2. 添加自定义项 — 由用户描述要添加的内容。跳至步骤 7。
  3. 重新配置 — 从头开始。先备份现有配置：
     • 将每个 .validator/checks/*.yml 文件重命名为 .yml.bak（覆盖之前的 .bak 文件）——这些是基于文件的旧版检查
     • 将每个自定义 .validator/reviews/*.md 文件重命名为 .md.bak（覆盖之前的 .bak 文件）
     • 不要重命名 .validator/reviews/*.yml 文件（这些是内置评审配置）
     • 在 config.yml 中将 entry_points 清空为 []
     • 继续执行步骤 3

步骤 3：检测项目结构

扫描各种信号，将项目分类为单体仓库、拆分项目或单一项目。

单体仓库信号

• package.json 中有 workspaces 字段
• pnpm-workspace.yaml
• lerna.json、nx.json、turbo.json
• Cargo.toml 中有 [workspace] 部分
• packages/、apps/ 或 services/ 下有多个子目录，且每个子目录都包含自己的项目清单（package.json、go.mod、Cargo.toml、pyproject.toml）

拆分项目信号

• frontend/ + backend/（或 client/ + server/、web/ + api/）目录各自包含源代码和/或自己的项目清单
• 同一父目录下有多个使用同一种语言的应用或库（例如，apps/web/、apps/api/、apps/worker/ 各自包含源代码和配置）——这通常意味着应使用类似 apps/* 的通配符入口点

单一项目信号

• src/ 或 lib/ 是唯一的源代码目录，或源文件位于项目根目录
• 未发现单体仓库或拆分项目信号

如果是单体仓库或拆分项目： 阅读 references/project-structure.md，了解多项目入口点的详细指南，然后按指南执行步骤 4 至 8。本文件其余部分介绍单一项目的流程。

如果是单一项目： 告知用户检测结果，然后继续下面的内容。

步骤 4：确定入口路径

推断源代码目录：

• 如果 src/ 存在且包含源代码，建议使用 src
• 如果 lib/ 存在且包含源代码，建议使用 lib
• 否则建议使用 .（项目根目录——更安全的默认选项，因为它会捕获所有更改）

如果要向已有且已设置路径的入口添加检查，则跳过此步骤。

步骤 5：扫描工具

扫描项目，查找 references/check-catalog.md 中列出的 6 类检查的工具信号。

**对于“添加检查”路径：**过滤掉 entry_points 中已配置的检查。

**如果未发现任何工具：**提供自定义流程（跳至步骤 7）。仍需包含 code-quality 审查。

步骤 6：展示发现结果并确认

显示已发现检查的表格：

Category        | Tool            | Command                              | Confidence
----------------|-----------------|--------------------------------------|-----------
Build           | npm             | npm run build                        | High
Lint            | ESLint          | npx eslint .                         | High
Typecheck       | TypeScript      | npx tsc --noEmit                     | High
Test            | Jest            | npx jest                             | High
Security (deps) | npm audit       | npm audit --audit-level=moderate     | Medium
Security (code) | Semgrep         | semgrep scan --config auto --error . | Medium

置信度等级：

• 高 — 找到工具配置文件，和／或 package.json／Makefile 中存在明确脚本
• 中 — 在 devDependencies 中发现工具，或从 CI 工作流推断出工具，但没有专用配置
• 低 — 只有间接证据（例如存在测试目录，但未找到运行器配置）

如果某类别未发现工具，则显示 (not found)，并在命令和置信度栏中填入 —。

询问用户：

1. 要启用哪些检查（默认：全部）
2. 是否需要调整任何命令

如果用户拒绝所有检查，仍需包含 code-quality 审查，并提供自定义流程（步骤 7）。

确认后，继续步骤 8（创建文件）。

步骤 7：添加自定义项

询问用户：check（shell 命令）还是 review（AI 代码审查）？

**对于检查：**询问命令、名称和可选设置（run_in_ci、run_locally）。

**对于审查：**使用内置审查（code-quality）还是自定义提示词？询问名称并编写审查内容。

步骤 8：创建文件并更新配置

检查 — 在入口的 checks 数组中以内联形式添加检查。每个内联检查都是单键对象（检查名称 → 配置对象）。包含 command。仅当可选字段（run_in_ci、run_locally）与默认值不同时才添加。架构请参阅 references/check-catalog.md。不要添加顶层 checks 映射——内联检查应放在 entry_points 下。

自定义审查 — 创建 .validator/reviews/<name>.md，并添加 YAML frontmatter（num_reviews: 1）和审查提示词。

内置审查 — 在入口的 reviews 数组中以内联形式添加内置审查（例如 - code-quality: { builtin: code-quality }）。不要为内置审查创建单独文件。

更新 .validator/config.yml 中的 entry_points：

entry_points:
  - path: "<source_dir>"
    checks:
      - build:
          command: npm run build
      - lint:
          command: npx eslint .
    reviews:
      - code-quality:
          builtin: code-quality

对于全新设置，始终在 reviews 中包含 code-quality。对于“添加检查”／“添加自定义项”，将内容追加到相应入口的列表中；如有需要，也可以添加新入口。在一个入口中以内联形式定义的检查或审查，可以在其他入口中通过名称（作为字符串）引用。

步骤 9：“还要添加其他内容吗？”

询问用户。如果是，循环回到步骤 7。如果否，继续。

步骤 10：验证

运行 agent-validate validate。如果失败，尝试修正一次并重新验证。如果仍然失败，则停止并询问用户。

步骤 11：提交配置

提交所有 validator 配置和技能，以便在版本控制中保留设置：

1. 暂存所有新建／修改的文件：.validator/、.claude/skills/validator-*/、.claude/settings.local.json、.gitignore
2. 创建提交：git commit -m "chore: configure agent-validator checks and reviews"

如果没有要提交的更改（所有内容都已提交），则静默跳过此步骤。

步骤 12：推进 validator 基线

运行 /validator-skip，将执行状态基线推进至当前工作树，这样下次运行时就只会与之后的更改进行比较。

步骤 13：建议后续步骤

告知用户：配置已完成。运行 /validator-run 以执行，或再次运行 /validator-setup 以添加更多内容。