Checktrail

Checktrail

通过 CLI、MCP 工具和实际运行记录进行本地代码验证。

本地 MCP 服务通过所选 MCP 宿主运行。该宿主负责 AI 选择以及订阅/API 身份验证；Checktrail 无需登录模型服务。直接调用提供商是另一个可选接口。有关已实现的工具、计划中的审查阶段以及新会话强制执行的限制，请参阅 MCP 审查工作流。

原名 Repo Verifier。现有源代码检出请参阅更名指南。

已发布预览版：0.1.0-alpha.5。 公开源代码位于 stsepelin/checktrail。 在依赖适配器之前，请参阅实现状态、计划和 语言矩阵。 安装指南涵盖 CLI、Claude Code 和 Codex。 Agent 技能提供可通过 npx skills add stsepelin/checktrail 安装的设置、验证和审查工作流。 项目设置涵盖 init、doctor 和 MCP 配置生成器。 发布准备记录了发布和验证门槛。里程碑审计区分已实现的配置与尚未完成的验收工作；客户端检查记录了实际应用覆盖情况。 公开采用情况记录了五个固定版本库上的已发布软件包，包括设置过程中的阻碍和兼容性缺口。 Alpha.3 修复了记录在案的 TypeScript 4.9.5 不兼容问题。 设置范围指南说明了语言、文档和工作流的覆盖范围。 Alpha.5 新增了带有逐项检查排除项的具名 Go 构建标签配置。 其发布记录 包含软件包、客户端和升级/回滚验证。

托管矩阵 在 Linux 和 macOS 上通过了发布提交 832a044 的检查。已验证确切的 npm 压缩包以及全新 CLI/MCP 安装。 MCP Registry 条目 目前处于启用状态；默认情况下仍禁用执行。

Checktrail 会发现项目、规划已注册的检查，在明确获得信任时调用原生工具，并报告结果，不会将跳过的检查或空检查判为成功。同一引擎服务于开发者、CI 和 MCP 客户端。

可选的库任务存储会在重启后保留本地验证结果。库工作器增加了原生执行、轮询和取消功能。MCP 报告仍使用内存；标准 Tasks 集成尚未完成。

尝试本地检出版本

需要 Node.js 22 或更高版本。目前执行目标平台为 macOS 和 Linux。

npm ci --ignore-scripts
npm run build
node dist/src/cli.js plan --root examples/javascript --detailed
node dist/src/cli.js run --root examples/javascript --trust-project --detailed

plan 和 inspect 会读取文件，但不会执行项目代码。run 需要 --trust-project：测试、编译器插件和项目配置可能会以你的用户权限执行 代码。这不是沙箱。

除帮助和版本信息外，成功的命令会返回 JSON；输入错误会写入 stderr。退出代码：

Code	含义
0	所选检查通过、只读操作成功，或建议性实验已完成
1	至少一项所选检查失败
2	所需证据不完整、执行不受信任或输入无效

通过的运行仅适用于所选检查和范围。PHP 语法检查通过 并不意味着其应用测试也通过。未知框架和空计划均视为不完整。 验证期间源代码发生变更，则不会判定整体通过。

初始适配器

生态系统	此基础中的执行方式
JavaScript	原生 Node 测试；显式运行 ESLint 检查，并提供逐文件覆盖率证据
Python	显式运行 unittest/pytest 测试和 Ruff/mypy 检查
Go	gofmt 检查、go vet、禁用缓存并输出 JSON 事件的 go test
PHP	语法检查和显式 PHPStan 分析；原生验证结果列于状态中
TypeScript	显式 javascript.typescript：本地 tsc、禁止输出文件、文件纳入证据
Jest	显式 javascript.jest：原生结果统计；待运行测试视为未完成
Vue	显式 javascript.vue-tsc：SFC 和 TS 检查；可选启用 javascript.vue-router 路由契约
Vitest	显式 javascript.vitest：原生 JSON 计数和精确的测试文件统计
Playwright	显式 javascript.playwright：原生测试/项目证据及已准备的浏览器
其他框架测试运行器	清单发现；计划添加执行集成
Rust	锁定的离线 Cargo 构建、显式工作区/目标配置、Clippy/libtest/doctests 和 Cargo/Rustfmt
Ruby	MRI 语法检查；可选启用范围受限的 RuboCop/RSpec/Minitest，并提供源代码和生命周期证据
Swift	语法检查；范围受限的 Linux ARM64 SwiftPM 构建、XCTest/Swift Testing 和显式 SwiftLint 规则
C / C++	已准备的 Clang 检查；范围受限的 C17/C++20 CMake 构建、CTest、clang-format 和 clang-tidy
Java	显式类路径编译，以及范围受限且版本固定的 Checkstyle、Maven reactor 和 Gradle 模块测试
C# / .NET	显式 C# 编译；可选启用范围受限的 C#/F#/VB 构建/NUnit 和 C#/VB 空白检查
GitHub Actions	静态工作流检查，并进行原生逐文件统计
Kubernetes	范围受限的离线 kubeconform 文档/架构验证，并提供物理源代码地址
Kustomize	范围受限的本地资源/前缀/副本组装，并进行原生渲染核对及源代码绑定的架构检查
Terraform	范围受限的无提供程序多文件 JSON 模块验证，并提供原生源代码诊断
Helm	根 chart 及可选的本地应用/子 chart 别名验证，并提供原生约束和源代码诊断
Kotlin	可选启用版本固定的 detekt 轻量分析，并统计每个已选文件的规则、源代码、抑制项和完成情况
Scala	可选启用版本固定的 Scala 2/3 编译；显式处理混合/生成/仅编译脚本及有序宏阶段
必须已安装工具。引擎不会安装依赖、自动修复问题、启动服务、执行迁移、提交或部署。
Go 执行会禁用模块代理下载和工具链自动下载。Rust 配置文件使用锁定的离线 Cargo，并禁用 rustup 自动安装。其他
被调用的工具和测试代码仍可能访问网络。

选择检查项

如果未进行配置，则对每个检测到的项目应用已注册的默认项。 仅当脚本与 node --test 完全一致时，才会自动选择 Node 测试。 Python 需要显式选择，因为清单无法确定测试运行器。 在被检查的根目录中创建 checktrail.json：

{
  "schemaVersion": 1,
  "projects": [
    { "path": "web", "checks": ["javascript.node-test", "javascript.eslint"] },
    { "path": "library", "checks": ["javascript.typescript"] },
    { "path": "service", "checks": ["go.format", "go.vet", "go.test"] },
    { "path": "worker", "checks": ["python.unittest"] }
  ]
}

存在此文件时，它只会选择列出的项目/检查项。路径必须是相对于 --root 的 已发现项目根目录；若指向该根目录本身，请使用 .。 配置不能提供任意命令，也不能启用执行权限。 schema 会拒绝未知字段，检查项 ID 由引擎验证。私有配置和规则无需公开发布。 本地公开/私有 JSON 包以及可叠加的操作员覆盖配置已实现； 请参阅策略包。显式的 fetch-pack 命令可以通过 HTTPS 下载固定版本的纯数据包，供之后离线使用。显式的 fetch-adapter 命令会在发布私有文件前验证 固定版本可执行包中的每个制品；注册和可信执行是分开的操作。

由操作员注册的外部适配器可以运行固定版本的 本地 Node、Python、PHP 或原生可执行包。仓库配置可以选择这些已注册的检查项；执行仍需获得操作员信任。该协议会检查证据是否完整，而分析的正确性仍由适配器作者负责。

TypeScript 检查需要本地 tsconfig.json，并且配置根目录内必须安装编译器（位于项目本地或提升到某个祖先目录）。它会禁用 noCheck、代码生成和增量状态。项目中清点的每个 .ts、.tsx、.mts 和 .cts 文件都必须出现在编译器的文件列表中。若编译器干净退出但排除了源文件，结果将不完整。严格性和声明检查等其他编译器选项来自项目配置。对于具有新鲜内存中 声明的项目引用解决方案，请使用 javascript.typescript-build。 Vue SFC 检查使用单独的适配器。 集成测试使用 TypeScript 6.0.3 进行验证；其他版本未经验证。 javascript.vue-router 捕获选定的原生测试路由器，并验证其完整参与声明的 URL 探测；有关版本和投影限制，请参阅 Vue Router 配置说明。 javascript.nuxt-runtime 会构建全新的 SSR 测试程序集，并在进程内请求后检查原生路由器捕获情况。选择加入配置版本 2 后，还会验证原生服务端处理程序、中间件调用、运行时配置边界、生成的 API 消费者类型以及受控响应。有关版本和范围限制，请参阅 Nuxt 配置说明 和程序集契约。 python.fastapi-routes 捕获已配置 FastAPI 应用的原生路由。选择加入配置版本 2 后，还会检查声明的挂载／托管程序集、安全依赖项、响应模型、中间件／生命周期顺序以及受控 ASGI 响应。有关版本和范围限制，请参阅 FastAPI 配置说明 和程序集契约。 python.django-routes 在 Django 设置完成后捕获受支持的嵌套 URL 解析器链；请参阅 Django 配置说明。 php.laravel-runtime 捕获测试程序集的路由、中间件、监听器、计划任务和容器绑定投影。选择加入配置版本 2 后，会比较所有声明的原生集合、选定的模型默认值以及受控 HTTP 响应。有关引导行为和限制，请参阅 Laravel 配置说明 和程序集契约。

javascript.eslint 使用已安装的 ESLint 和项目本地 JavaScript 扁平配置。被忽略的文件、不匹配的配置以及未启用任何规则的文件都会导致检查不完整。错误和警告都会导致检查失败。它会保留现有 lint 缓存，且不会执行修复。有关范围、配置要求和已验证的工具支持，请参阅 ESLint 契约。

javascript.vitest 运行已安装的 Vitest 一次，要求报告中包含每个计划测试文件，并拒绝空结果或全部跳过的结果。它会禁用聚焦测试、快照更新和自动依赖安装。有关已测试版本和限制，请参阅 Vitest 契约。

javascript.playwright 会核对原生测试、项目和重试结果，要求浏览器已预先安装，并保护快照。请参阅 Playwright 契约。

javascript.jest 要求提供原生断言和文件核算信息，并保守地将待处理测试视为不完整。请参阅 Jest 契约。 javascript.vue-tsc 会检查 Vue SFC 和 TypeScript，且不生成输出，并拒绝禁用模板检查的情况。请参阅 Vue 契约。

python.pytest 会核对原生收集信息以及设置／调用／拆卸阶段的证据。有关范围和预备运行时，请参阅 pytest 契约。

python.ruff 要求提供精确的原生文件选择和活动规则证据，并禁用修复。请参阅 Ruff 契约。

python.mypy 会检查显式指定的源文件，要求提供原生源文件计数证据，并拒绝宽泛的模块错误抑制。请参阅 mypy 契约。 go.test-race 增加了可选启用的原生竞态检测，并提供未缓存的测试证据。 请参阅 Go 竞态检测约定。Go 检查会将原生包选择与已清点的源代码进行核对；go.staticcheck 则增加了显式的全规则分析和规范化问题发现。请参阅 Go 范围。受约束的 go.golangci-lint 配置允许显式选择原生 linter，同时禁用隐藏的问题过滤器和修复功能。 Alpha.5 增加了 Go 构建标签配置，为每项选定的原生检查提供一份显式配置。Alpha.4 不包含此功能；可运行示例见 examples/go-build。 当前源代码还实现了版本 2 的重复标签／目标配置，以及显式的生产环境 go.build 检查；这些新增功能尚未发布。没有目标执行器时，跨目标测试仍不可用。请参阅 Go 构建配置。

php.phpstan 将逐文件分析统计与原生 JSON 诊断结合起来。 请参阅 PHPStan 约定。

php.phpunit 会流式传输全新的原生 JUnit 证据，并统计文件和断言。 请参阅 PHPUnit 约定。现有 JUnit 工件也可以单独导入；导入不会验证当前源代码或执行的新鲜度。

php.pest 在 CI 模式下运行相关测试，并禁用缓存的测试影响重放；请参阅 Pest。php.pint 使用原生文件和规则统计验证格式；请参阅 Pint。

详细报告包含 ESLint、Ruff、PHPStan、Staticcheck、golangci-lint 和 TypeScript 解决方案构建的规范化源代码问题发现。SARIF 导出会保留失败和未完成的执行，不会将空的问题发现列表视为成功。

项目可以声明环境要求，但只能通过操作员的 --allow-env NAME 权限或显式库选项提供这些环境。MCP 工具调用无法授予环境访问权限。

使用工作区依赖和 Git 选择以及 --base REVISION，验证变更项目及其声明的使用方。 影响范围不确定时，将保留完整的已配置计划。

MCP

从已构建的检出目录运行服务：

node dist/src/cli.js serve --root /path/to/your/repository

对于接受命令／参数形式服务定义的客户端：

{
  "mcpServers": {
    "checktrail": {
      "command": "node",
      "args": [
        "/path/to/checktrail/dist/src/cli.js",
        "serve",
        "--root",
        "/path/to/your/repository"
      ]
    }
  }
}

可用工具包括 project_context、validation_plan、validation_run、 validation_report、finding_comparison、runtime_comparison、contract_validation、 architecture_validation、review_guidance、review_context、review_receipt、 review_hypotheses、review_benchmark、review_workflow、review_run、review_refute、review_probe、review_verify、review_score、review_paired_score、review_calibration_fit、 review_calibration_apply、import_context 和 mutation_experiment。前两个目前会返回相同的项目／检查清单；建议性指导和源代码审查分别使用各自的工具。报告保存在内存中（最近十份），并会在进程退出时消失。

仅在信任项目执行时，才将 --allow-execution 添加到服务参数中。 模型无法通过工具参数授予此权限。仅当客户端可以接收路径、命令和原始诊断时，才添加 --detailed。默认摘要会省略这些字段。通过 MCP 客户端返回的数据可能会发送给该客户端的模型提供商。

仅限操作员使用的 review-benchmark-score 命令会根据冻结且密封的合成基准工件计算描述性配对指标；请参阅基准评分。声明、标签、主机隔离和质量均未经验证。 review_benchmark 工作器视图会从固定的原始合成就绪协议中，读取启动时选定的一项匿名试验。操作员命令会冻结成对案例、保留所有预先声明的日志槽位，并准备匿名评审数据包。主机隔离、完整模型尝试和质量仍未验证；现场试验仍需等待必要的实现门槛。请参阅 REVIEW-BENCHMARK.md。

与模型无关的 review_workflow 工具会与主机拥有的 AI 会话及由操作员固定的实时探测交换有界的评审者／反驳者／裁决者任务。前台 review-session CLI 使用相同的引擎。任务输出需要在启动时启用 --detailed --allow-review-source；原生探测还需要执行信任。已完成的阶段仍会将发现和主机隔离标记为未验证。请参阅工作流操作与限制和可选的私有持久化命令审计。

此实现使用官方 MCP v2 SDK。自动化测试会通过 stdio 测试 2026-07-28 协议及 SDK 的旧版协商。这并不能证明与所有编辑器或 Agent 应用程序兼容。

普通验证调用会异步运行，并在原始调用中返回报告。启动时启用 --task-store，即可为支持的请求启用有界的标准 Tasks 轮询配置，同时保留普通调用回退。请参阅 MCP 兼容性，了解经过测试的 SDK 2.3.0 路由、生命周期证据及剩余的客户端／运行时配置。选定的 Windows 私有任务存储后端已新增原生源代码／软件包 CI 控制；其平台验收仍在等待中。

可通过 CLI、库和 MCP 获取精确的发现基线与例外。发现策略说明了创建、过期、陈旧状态和扩展检查。比较成功时会保留单独的原生验证结果；它绝不会将失败的验证变为通过。

运行时清单比较会检查本地前后程序集工件中的注册项、属性、重复项和顺序变化。导入的工件会保留明确的完整性与来源限制。

公共策略包和私有叠加层会组合已注册的检查，并通过固定的 SHA-256 完整性校验。可在 CLI 调用或 MCP 启动时使用 --policy-overlay，将本地要求添加到已检入的要求中。

已捕获的契约检查会使用严格的使用者架构验证生产者 JSON，并设置工作器截止时间，且对导入的证据单独标注。

限制与证据

详细报告包含工具身份凭据。原生版本探测共用执行限制，且需要操作员信任；缺少身份信息时，不会将成功检查报告为通过。

清单会排除依赖项／构建目录、符号链接和常见的机密文件名，但不会应用 .gitignore。可选的 Git 选择仍会保留这些排除项。限制为 20,000 个条目、深度 32、每个文件 8 MiB，以及文件总字节数 64 MiB。源指纹涵盖纳入的内容和排除项名称，但不涵盖被忽略的依赖项、外部配置、工具二进制文件或服务。

执行设有全程时间预算（默认 30 秒，最高可配置为 120 秒）、每条命令输出上限 1 MiB，以及每次运行输出总量上限 4 MiB。超时、已取消的工作、截断的输出和格式错误的测试证据均视为不完整。详细报告包含进程输出；请勿公开私有仓库的报告。

结果无法证明项目代码没有恶意行为：受信任的测试可以伪造输出、修改其他文件或启动分离进程。隔离和证明属于未来的独立能力。请参阅安全性。

开发

npm run check
npm run format:check
node scripts/smoke-package.mjs

测试涵盖真实进程执行、工具可用时的原生适配器集成、源代码变更检测、输出限制、架构、CLI 退出代码和 MCP 调用。本地运行时缺少的原生工具会明确跳过；CI 会准备工具，并通过必需配置要求使用精确的原生回归名称。更改架构定义后，构建完成时运行 node scripts/generate-schemas.mjs；测试会拒绝已检入的 JSON 架构与定义不一致的情况。

所有示例和测试样例均为合成内容。贡献必须包含一个最小失败案例、对应修复，以及一个适用时的有效近似案例。请参阅贡献指南。采用 MIT 许可。

明确的架构策略会根据字面层级允许列表和可选的循环限制，检查已捕获的项目依赖。导入图的完整性需作为证据声明；这并不意味着会发现原生导入。公开的已构建软件包测试样例会通过消费者类型和运行时检查，测试已安装的生产者。

辅助审查建议

使用 guidance --root PATH，可从计划的检查中选择公开审查问题；也可以添加明确的 --topic。此只读操作不声称具有覆盖率，也不会调用模型。请参阅建议指南。

使用 mutate --root examples/mutations --input mutations.json --trust-project，可在临时源代码副本中进行范围受限的实验。其初始配置支持无依赖项目中的扁平 Node 测试。断言杀死、存活和执行结果不确定是彼此独立的建议结果；请参阅变异实验。

C/C++ 配置会验证准备好的 Clang 参数数组，并要求为清单中的转换单元和头文件提供原生依赖覆盖。单独选择启用的原生工具配置会构建有限的 C17/C++20 CMake 声明，生成整数值头文件，链接静态库和可执行文件，运行已注册的 CTest 回调，并检查格式和明确的分析器规则。两个配置都要求操作员信任才能执行。

Java 配置使用明确的发行版本和固定的本地依赖编译清单中的源代码。不会执行 Maven/Gradle、注解处理器和应用测试。 选择启用的 Checkstyle 配置会使用固定工具和逐文件完成检查，验证已配置的 Java 源代码审计。选择启用的 Maven 和 Gradle 配置会编译声明的 Java 模块，并核对原生测试证据。选择启用的 SpotBugs 配置会分析新编译的 Java 字节码。Kotlin detekt 配置会使用固定的轻量规则分析所选 Kotlin 源代码。Kotlin 编译器配置和 Scala 编译器配置 分别提供单独选择的原生编译证据。更广泛的分析器／平台配置以及生成代码／JPMS 分析器范围仍为必需项。

使用性能测试工具复现合成规划和执行成本。报告会保留原始测量数据和工件标识；文档中记录的快照仅为观测结果，不代表速度保证。

C# 配置使用已准备好的 .NET SDK 和明确的编译设置。项目构建目标、源代码生成器和测试运行程序是单独的功能。

GitHub Actions 配置会使用明确的运行器标签和变量、本地依赖检查以及原生完成证据，检查清单中的工作流。它不会执行工作流任务或操作代码。 开发评估记录了各类别相对于直接原生命令的检测数、误报数和结果不完整数。 这些小规模合成观测无法证明独立审查的质量。 Agent 评估工作流冻结公开来源案例， 将仅使用原生工具的审查者与 MCP 辅助审查者分开，封存评估，并提供 盲法裁定和明确的不完整结果核算。 强制跨类别试点记录了 全新的 Claude/Codex 尝试、交付失败和独立执行审计。

影响测量比较完整验证与 Git 选取的 验证，包括依赖声明错误时遗漏的消费者故障。仅减少选取的检查数量，不能证明运行安全或更快。

可选的 review-context 和 review-receipt 用于交换 范围受限的选定源代码和外部审查者评估。源代码和审查文本 需要 --detailed --allow-review-source；声明和声明的用途仍仅供参考。 核心验证不会调用模型或上传代码。可选的 提供方审查需要单独授予操作者推理和源代码披露权限；常规输出会隐藏源代码和候选文本。 受限的尝试输出会在相同的输出授权范围内保留物理共享引擎 命令输出和通过凭据检查的 API 响应正文； 完整的全尝试及主机使用情况验收仍待完成。

原生审查探测将由操作者固定的控件绑定到 选定源代码和测得的函数/防护执行。原生执行需要操作者信任； 布尔反例仅作为参考证据。

独立反驳会将一个未经验证的假设 发送给全新的无状态验证者，同时隐去先前审查者的标签和判定。 反驳意见仅供参考。原生佐证与独立裁定 现在结合了全新的反驳、实时的操作者固定 Node 探测，以及单独的 原始证据任务。受限观测无法验证生产影响、 声明机制或严重程度；完整的独立发现仍未完成。

审查者评分根据声明的 标签报告适当的概率损失、可靠性、风险/覆盖率，以及明确的不完整/未知项核算。 这不能证明置信度经过校准，也不能证明其可作为质量门槛。

按类别声明的校准会拟合数值型 开发观测，并仅将其应用于使用相同声明模型的互斥保留协议。不可用的类别和超出 训练范围的预测仍标记为未知。拟合不能证明置信度经过校准、 标签已验证、主机隔离独立，或留出集质量达标。

声明的判定概率将数值型 预测与严重程度分开，并将封存评分绑定到原始候选项。独立反驳者和裁定者会收到假设/源代码/原生案例 证据，但看不到先前的候选元数据和汇总判定。这些结构性检查不能证明声明属实、实现全新的主机隔离或置信度经过校准。

范围受限的导入上下文会收集 JS/TS 源代码和 静态消费者边缘，但不会执行项目代码。对于未知或不完整的采集，会为每个已声明项目保留建议性的完整回退方案。 它不会缩小验证计划范围，也不能证明运行时可达性。

实验性的受限 Windows 可执行文件配置 设有专用原生 CI 门禁。 其验收仍待完成；更广泛的 Windows 工具、 Git 和私有持久化配置仍未经验证。 所选的本地 Helm 应用/子图表配置文件会验证已声明的传递依赖图和重复别名图、物理默认值与根级覆盖值、原生值约束，以及绑定到源文件的模板/渲染诊断。它通过同一可信 CLI/MCP 引擎使用已准备好的固定版本工具；任意图表和集群行为需要单独支持。