根治Repository checks本地漏检
修复 Agent 失败展示变更中的 import 排序错误 统一 CI 与 master pre-push 的 Repository checks 入口 让 staged JS 和 TS 自动执行 ESLint 修复与 Prettier 补充部分暂存、忽略文件和待推 SHA 回归测试 同步分支保护与本地门禁流程文档
This commit is contained in:
@@ -1,5 +1,12 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-08-12 Repository checks 采用 CI 与本地共用的单一门禁入口
|
||||
|
||||
- 背景：master run 1037 的 Backend/Frontend 已通过，但 `Repository checks` 因 3 个 `simple-import-sort/imports` 错误失败。原 pre-commit 只运行 Prettier，Prettier 不处理 ESLint import 排序；推送前又未运行完整仓库 lint，因此本地与 CI 的覆盖范围长期存在漂移。
|
||||
- 决策：`npm run check:repository-ci` 成为 Repository checks 唯一仓库入口，统一执行 lint、生产构建、内容检查和基线到候选提交的空白差异检查；Gitea workflow 与 master pre-push 只调用该入口。pre-push 必须验证待推 master SHA 是当前 `HEAD` 且已跟踪工作树干净，无法确认候选内容时失败关闭；feature 分支不运行该重门禁。
|
||||
- 提交门禁：lint-staged 对 staged JS/TS 先运行按 ESLint 配置过滤 ignored 文件的 autofix wrapper，再运行 Prettier。回归测试覆盖 import 排序、部分暂存恢复、ignored 文件、feature push 跳过、master push 参数绑定，以及 workflow/hook 共用入口。
|
||||
- 权威边界：本地 hook 可被 `--no-verify` 绕过，不能从制度上保证 master 永远不红。服务端根治要求禁止日常直接 push master，统一走 PR，并要求当前 head 的 Repository/Frontend/Backend/Native 四项检查全部成功后合并；紧急白名单只能最小化保留。
|
||||
|
||||
## 2026-08-12 Agent 失败原因使用稳定分类贯穿 Runtime 与正式展示面
|
||||
|
||||
- 背景：Codex app-server 的 failed turn 已携带 `turn.error.codexErrorInfo`，但适配器曾丢弃该字段并写固定失败句；Runtime、事件 `publicText`、最近任务、game-chat 阶段记录和多个 Agent 卡片又各自用固定文案覆盖已有安全原因。自主构建 final-reply 已形成确定性完成文案时还对任意错误 fallback 成成功，导致鉴权、额度、上下文、策略、sandbox、配置或网络失败可能被伪装为完成。
|
||||
|
||||
@@ -611,13 +611,15 @@ npm run check:server-rs-ddd
|
||||
- 页面交互 smoke
|
||||
- 移动端视口检查
|
||||
|
||||
### 提交前 TypeScript 自动格式化
|
||||
### 提交与 master 推送前自动门禁
|
||||
|
||||
仓库级 Git `pre-commit` hook 通过 `lint-staged`，只对当前已暂存的 `*.ts`、`*.tsx` 文件运行 Prettier 自动格式化，并把格式化结果更新到本次提交的暂存区；未暂存的其他文件不进入格式化范围。格式化或暂存恢复失败时提交会中止，应先处理失败原因并重新检查 staged diff，不能等 CI 再暴露格式问题。
|
||||
仓库级 Git `pre-commit` hook 通过 `lint-staged`，只对当前已暂存的 `*.js`、`*.mjs`、`*.cjs`、`*.ts`、`*.tsx` 文件依次运行 ESLint autofix 和 Prettier，并把修复结果更新到本次提交的暂存区；ESLint wrapper 会按仓库配置过滤 ignored 文件，避免 ignored warning 与 `--max-warnings 0` 组合造成误阻塞。未暂存的其他文件不进入处理范围，修复或暂存恢复失败时提交会中止，应先处理失败原因并重新检查 staged diff，不能等 CI 再暴露 import 排序或格式问题。
|
||||
|
||||
部分暂存同一 TS / TSX 文件时，`lint-staged` 会临时隐藏该文件未暂存的改动，以暂存快照执行格式化，随后恢复未暂存内容。因此提交前后都应分别检查 `git diff --cached` 和 `git diff`，确认格式化后的暂存内容属于本次提交，未暂存工作没有被误带入；若恢复产生冲突，先人工整理暂存边界再重新提交。
|
||||
部分暂存同一 JS / TS 文件时，`lint-staged` 会临时隐藏该文件未暂存的改动，以暂存快照执行修复和格式化，随后恢复未暂存内容。因此提交前后都应分别检查 `git diff --cached` 和 `git diff`，确认修复后的暂存内容属于本次提交，未暂存工作没有被误带入；若恢复产生冲突，先人工整理暂存边界再重新提交。
|
||||
|
||||
`git commit --no-verify` 会绕过该 hook，只允许在已明确原因的紧急场景使用。绕过时仍须对本次暂存的 TS / TSX 文件手动执行等价的 Prettier 格式化、重新暂存并核对 staged diff；`--no-verify` 不代表可以跳过格式化或其他提交门禁。
|
||||
`Repository checks` 的唯一仓库入口是 `npm run check:repository-ci`，依次运行 `npm run lint`、生产构建、内容检查和基线到候选提交的空白差异检查。Gitea `Repository checks` job 和本地 master `pre-push` 必须共同调用该入口，禁止各自复制或删减子命令；本地 hook 还会确认待推 master SHA 等于当前 `HEAD` 且已跟踪工作树干净，无法确认时失败关闭。普通 feature 分支 push 不运行这条重门禁，进入 master 前仍以 PR required checks 为权威。
|
||||
|
||||
`git commit --no-verify` 和 `git push --no-verify` 都会绕过本地 hook，只允许在已明确原因的紧急场景使用；绕过不代表可以跳过等价门禁。真正阻止红提交进入 master 依赖 Gitea 分支保护：禁止日常直接 push，统一经 PR，并要求 `Repository checks`、`Frontend tests`、`Backend tests`、`Native shell tests` 四个当前 head context 全部成功后合并。本地 hook 只负责提前反馈，不能替代服务端分支保护。
|
||||
|
||||
前端原则：
|
||||
|
||||
|
||||
@@ -236,7 +236,7 @@ npm run check
|
||||
|
||||
仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 或 `codex/ai-game-creator-app` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成四个必须通过的 job：
|
||||
|
||||
- `Repository checks`：执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。
|
||||
- `Repository checks`：调用唯一入口 `npm run check:repository-ci`，执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。本地 master `pre-push` 复用同一入口，禁止在 workflow 与 hook 中维护两份近似命令。
|
||||
- `Frontend tests`：按根 lockfile 与 `apps/ai-game-creator-shell/package-lock.json` 分别执行干净的 `npm ci`，再独立执行根 `npm run test`、`npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，让 Vitest、Node test smoke harness 及不依赖真实服务的生产巡检 / 发布 / 部署行为 fixture 在 Gitea job 中持续执行；其中 `.test.mjs` 使用 Node test runner，不依赖 Vitest 的 `scripts/**/*.test.ts` 收集规则。
|
||||
- `Backend tests`：先对 `server-rs/Cargo.lock` 执行带 5 次整命令级有界重试的 `cargo fetch --locked`，再执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；依赖准备必须位于会触发 Cargo build 的 DDD / 产物边界门禁之前，避免锁新增依赖未命中镜像缓存时绕过既有下载重试。runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
|
||||
- `Native shell tests`：按根 lockfile 与 AI 游戏创作壳独立 lockfile 安装依赖后执行 `npm run check:native-shells`，覆盖微信壳、Expo 和 Tauri 的完整验收，并确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。`codex/ai-game-creator-app` 分支的同名脚本还会执行 `npm run ai-game-creator-shell:check` 和 AI 游戏创作壳 release build smoke；共享 Agent Runtime 后台锁 suite 固定 `--test-threads=1`，不能用并行偶发失败后的逐项通过替代整套稳定门禁。
|
||||
@@ -268,6 +268,8 @@ bash scripts/gitea-ci-job-image.sh load-runner
|
||||
|
||||
workflow 首次成功运行后，在 Gitea `master` 分支保护中把 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)` 四个完整 context 都设为合并必需检查，并从最近一周已上报 context 表复核名称后再保存。不能只填裸 job 名，否则无法匹配 Gitea 实际上报的 `<workflow> / <job> (<event>)`。只提交 workflow 文件不会自动创建 runner，也不会自动修改分支保护；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。
|
||||
|
||||
master 日常交付必须禁止直接 push，只允许经 PR 在当前 head 的四个 required context 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。
|
||||
|
||||
视觉小说负向扫描与验收门禁：
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user