aurora-selfcheck

把 Aurora 设计规范的自检门禁一条命令装进任意项目——agent 自认完成（Stop 时机）时统一自检一次： 纯结构静态规则机器硬卡，需 d.ts / 看渲染才能判的规则委托你正在用的 agent 自查→修→确认。 支持 Claude Code / Codex / Trae 三个 agent 环境。

0.2.0 起：唯一 gate = Stop hook，已砍掉 PostToolUse 写时门禁。 写时门禁靠「工具名 matcher + 产物路径筛选」在异构项目里不可靠（Trae 真机实锤：复杂页面写工具名不在 matcher → 静默漏检；路径解析处处假设布局）。改为 Stop 统一委托宿主 agent（它懂自己项目）→ 跨项目更稳、确定性更高。升级时 init 会自动清理旧版 PostToolUse 残留条目。

它和 eval/ 的关系（先看这个，别搞混）

自检逻辑不在本目录，在 eval/src/。 本目录（eval/aurora-selfcheck/）只是个发布外壳：

eval/src/                       ← 真正的自检逻辑（checker / registry / 三环境安装器）
  staticChecker / auroraTruthChecker / inventory / checkFile   确定性 checker
  registry.ts + registry/checks.yaml                            检查标准
  selfcheck/  config·hookConfigs·init·stop·screenshot·cli       外发适配层（配置解耦 + Stop 委托 + CLI）

eval/aurora-selfcheck/          ← 发布外壳（零业务逻辑）
  package.json                  包名 / bin / deps
  build.mjs                     esbuild：从 eval/src/selfcheck/cli.ts 打包成 dist/cli.js
  dist/                         构建产物（gitignore，勿手改）

build.mjs 用 esbuild 以 eval/src/selfcheck/cli.ts 为入口、顺着它的 import 把整条 checker 链 内联成单文件 dist/cli.js，再把 eval/registry/checks.yaml 拷成 dist/checks.yaml。 所以本目录是 eval/ 的「出厂盒子」，不是第二份实现。改逻辑只在 eval/src/ 改，绝不手改 dist/。

同一份 checker 有两条交付通道：本仓内自己用走 pnpm eval:install-hooks（eval/src/installHooks.ts）； 发给别的项目走本包。

给使用方：其他项目怎么装

已发布到 registry 后（目标形态）

在你的项目根目录：

npx aurora-selfcheck init        # 探测 .claude/.codex/.trae → 装 Stop hook + 脚手架 config

它会：

1. 探测项目里有哪个 agent 环境（.claude / .codex / .trae），把 Stop 自检 hook 幂等写进对应配置（都没探测到则三种全装），并清理旧版 PostToolUse 残留；
2. 脚手架 aurora-selfcheck.config.json（按项目实际改）；
3. 之后该环境里 agent 自认完成（Stop 时机）→ 对本轮改动的 src/routes/**/*.tsx 产物跑纯结构静态硬门禁 + 委托 agent 自查 Aurora API 真实性/视觉语义 → 有问题就回灌让 agent 当场改再收工。

指定环境：npx aurora-selfcheck init --env claude,codex。手动检查单文件（CI/离线，全维度含 d.ts 对照）：npx aurora-selfcheck check --file <path>（block→exit 1）。

还没发布、想先试

• 本地绝对路径（--local）：hook 命令写成 node <abs>/dist/cli.js，不走 npx：

  cd /你的项目
  node /path/to/aurora-skill-lab/eval/aurora-selfcheck/dist/cli.js init --local

  （先在本目录跑过 node build.mjs 生成 dist/。）
• 本地 tarball：在本目录 npm pack 出 .tgz → 到用方项目 npm i ./aurora-selfcheck-*.tgz → npx aurora-selfcheck init。

配置（aurora-selfcheck.config.json）

外部项目布局各异，这几项可配（都有默认值，缺省即自动发现/包内置）：

| 字段 | 默认 | 说明 | |---|---|---| | routesDir | src/routes | 被测产物根目录 | | artifactExt | .tsx | 产物扩展名 | | registryPath | 包内置 | checks.yaml 路径（一般不用改） | | cssEntry | 自动发现 | Tailwind 入口 CSS（token 真实性 oracle 用） | | dtsEntry | node_modules/@ecom/aurora/dist/index.d.ts | 组件库 d.ts（防幻觉 API；委托 agent 跑 tsc 时也指它） | | baseURL | 无 | 视觉自检的建议 dev server 根地址：配了就写进 review-request 当默认 URL 提示。0.3.0 起 hook 不再自己起服务/截图，截图由 agent 主动调 shot --url 完成 |

给维护者：怎么改、怎么发

改逻辑

1. 在 eval/src/ 改（checker 规则 / selfcheck/ 适配层）；登记表标准在 eval/registry/checks.yaml。
2. 跑测试：pnpm eval:test（含 eval/src/selfcheck/*.test.ts）。
3. 重建产物：cd eval/aurora-selfcheck && node build.mjs。
4. 本地验证：node dist/cli.js check --file <某产物>，或 node dist/cli.js init --local 后真触发 hook。

不要直接编辑 dist/——它每次 build.mjs 都重新生成。

发布

已配好 publishConfig.registry=registry.npmjs.org（直发公网 npm）+ prepublishOnly（发布前自动 build）。所以：

cd eval/aurora-selfcheck
npm version patch    # 升版本（npm 不允许覆盖同版本号）
npm publish          # prepublishOnly 自动 build；publishConfig 自动发公网

要点：

• 公网发布需 npm login + 2FA：无验证器时去 npm 网页生成 Granular Access Token（Read and write + All packages + 勾 Bypass 2FA），npm config set //registry.npmjs.org/:_authToken <token> 后再 npm publish。
• files 只含 dist，发布的是 bundle + checks.yaml（README/package.json 由 npm 自动带上），不含 eval/ 其它源码。
• typescript / tailwindcss / playwright 是 dependencies，使用方 npx 时一并拉取。
• 包名/scope：若改 scope（如 @ecom/aurora-selfcheck），同步：package.json 的 name、eval/src/selfcheck/hookConfigs.ts 的 BIN/DEFAULT_BIN（决定写进各项目 hook 的 npx -y <名字>）、本 README。
• 发布需网络 + 登录，在你自己的机器上跑。

装的唯一门禁：Stop（自认完成时，无引擎）

agent 自认完成（Stop 生命周期）触发一次自检，分两层——hook 自己只跑零路径依赖的鲁棒确定性核，其余全委托：

1. 纯结构静态硬门禁（机器判，零 LLM、零项目路径依赖）：对本轮改动产物只跑纯 AST 静态反模式 （原生控件、Card 嵌套、任意视觉值、emoji 文案、Tag 拉伸、ProTable noPadding 等）。只读改动文件自身 AST， 不碰 d.ts/CSS/项目布局 → 跨项目永不崩、永不误报。输出会明示一行 🔬 结构静态检查已执行：N 个产物 × M 条规则 → K 处必修，让你一眼确认它跑了。
2. 委托宿主 agent 自查（无引擎）：剩下两类——
   • Aurora API 真实性（组件/props/token 是否真实存在）：让 agent 跑 tsc / 读自己项目的 @ecom/aurora d.ts 核对（它有真实 d.ts，幻觉 API 会被 tsc 报错）；
   • 视觉/语义（要看渲染才能判的）：委托 agent 派 subagent 渲染受影响路由 + 对照截图逐条判。

一次性给全 context（0.3.0）：每轮 Stop 把「结构必修项 + 委托自查清单」一起通过 decision:block 回灌 （落 .aurora-selfcheck/review-request.md，按「靠类型核对 / 靠看渲染」分组讲清「怎么查」），让 agent 一趟全修完， 而非串行多轮一个个修。结构 block 永远硬卡到改对为止；委托清单在首轮给一次，stop_hook_active 防重复 nag。 全程不需任何 API key/订阅，用你自己的额度。

截图能力稳定可达（0.3.0）：hook 不再自己起 dev server / 自动截图（那是「通用 hook 起一个它不了解的 项目」的脆弱点）。改为：playwright 随 init 预装，暴露成 npx aurora-selfcheck shot --url <URL> --out <png>—— agent 起好自己的 dev server、把它已就绪的 URL 传进来，我们只负责连+截整页图。截图能力由本包保证， 不赌项目能被 hook 起来、也不依赖 agent 自带截图工具。

为何 d.ts 真实性 / 截图都下放给 agent 驱动：两者都依赖「解析/启动这个具体项目」，正是跨项目脆弱点。 交给最懂自己项目、且有 tsc 的 agent → hook 只剩零依赖的纯 AST 硬核 + 提供稳定的截图能力，绝不因项目差异翻车。

限制 / 注意

• 委托这层是「agent 自评」：不如独立冻结裁判严格（适合开发时门禁；严格 benchmark 仍用本仓 eval:full）。
• 截图由 agent 主动调 shot --url：init 会顺带 playwright install chromium（下机器全局缓存，能力稳定可达）； agent 负责起 dev server / 给就绪 URL，hook 不替它起。baseURL 配了则作建议默认 URL 写进委托请求。
• Codex 为实验支持：Stop hook schema 与 Claude 同构（都 decision:block），但事件结构待真机确认。
• 改共享组件的反查（改 X 组件→命中用它的路由）为 v1；当前 Stop 只看「改动的产物文件」所属路由。
• 门禁自身鲁棒：Stop hook 任何内部异常（config 坏、git 不可用、单个文件解析失败）都降级放行 + 留 stderr 痕迹，绝不卡住宿主 session。
• typescript / tailwindcss / playwright 为运行期依赖（npx 安装时一并拉取）。