# CI 基线与编排边界基线（CI Baseline & Orchestration Boundary）

> 维护者：gmh-team1-junior1（CI 基线、关键路径、Jenkins/CI 编排边界）
> 更新：2026-08-05（基线测量基于 `upstream/main` @ `d4d2daef0`）
>
> 本文件是仓库内 CI 编排的专属基线文档：盘点 CI 入口、阶段依赖、串行等待与重复
> setup/build，记录当前关键路径与主要耗时来源的实测基线，并给出已落地与建议的
> 编排/可观测性优化。它不修改 Web 依赖缓存实现（见 Web CI 专项）与 backend shard
> 包定义（见 Backend CI 专项）。

## 1. CI 入口盘点

### 1.1 仓库内入口（可独立验证）

| 入口 | 路径 | 角色 | 归属 |
|---|---|---|---|
| `make harness-fast` | `scripts/harness-fast.sh` | 语言无关 guardrail 预检（检查清单以脚本为准），独立 worker | 本专项（已优化） |
| `make regression-fast` | `Makefile` | 本地聚合回归：backend 快速测试 → import/guardrail 检查 → `harness-fast` → backend validate → web deps → web build | 编排（本专项文档；后端/Web 部分分属 Backend/Web 专项） |
| `make test` | `Makefile` | 本地聚合：backend `go test ./...` → presets → desktop → web build → daemon e2e → web e2e（全串行） | 编排（文档；不属 CI 必需门禁路径） |
| `scripts/ci-backend-required.sh` | validate / list / run <shard> / go-e2e | backend required shard 集合 + 包覆盖校验 + TiDB migration 门禁 | Backend CI 专项 |
| `scripts/ci-web-smoke.sh` | 依赖 preflight → Playwright → dist → smoke runner | required browser smoke 入口 | Web CI 专项 |
| `scripts/ci-web-e2e-lane.sh` | lane 校验 → 依赖 → dist → 单 lane | CI 按 lane 拆分入口 | Web CI 专项 |
| `scripts/ci-web-e2e-full.sh` | 依赖 → dist → full suite | full e2e 入口 | Web CI 专项 |
| `scripts/ensure-web-node-modules.sh` / `ensure-web-dist.sh` | node_modules / dist 复用 | Web 依赖与构建缓存 | Web CI 专项 |

### 1.2 仓库外入口（不可改，本专项只记录证据与建议）

- **Jenkins**：仓库内**不存在** `Jenkinsfile`/`.jenkins`/`.github` 等流水线定义
  （`git ls-tree -r upstream/main | grep -i jenkins` 为空）。Jenkins 编排（阶段、
  并行、worker 分配）在仓库外，无法在仓库内直接修改。
- 仓库内的**间接证据**表明其形态：
  - `scripts/ci-backend-required.sh` 注释将 backend 校验描述为“Go-equipped backend
    validation job”，并区分“language-agnostic harness-fast image”。
  - `scripts/ci-web-smoke.sh` 读取 `JENKINS_URL` 下的认证 Nexus Go proxy 环境
    （`/tmp/agentteam-nexus-go.env`），说明该脚本运行在 Jenkins 环境。
  - `docs/development.md` 描述 `make harness-fast`、`make regression-fast`、
    `make e2e-web` 为 CI/required 门禁路径。

## 2. 阶段依赖与串行等待

### 2.1 harness-fast（已优化，见 §4）

`scripts/harness-fast.sh` 原为**纯串行**：`run()` 依次执行 23 项 guardrail。各检查
均为独立、只读的静态检查（bash/python3；唯一写路径 `check-store-json-tags.py
--allowlist` 由 harness 调用时未传，不触发写）。无跨检查共享可变状态，适合并行。

### 2.2 regression-fast / test（聚合串行链）

- `make regression-fast` 的 recipe 按序执行：backend validate → `ensure-web-deps`
  → `cd web && npm run build`，前三步与后两步相互独立但串行等待。
- `make test` 的 recipe 全串行：backend → presets → desktop → web build → daemon
  e2e → web e2e，各步独立。
- **不落地**：这些改动会触及 Backend/Web 专项的脚本与 Makefile，为避免与并行
  worktree 冲突，仅记录为建议（§6）。

### 2.3 Web smoke / e2e 入口（Web 专项）

`ci-web-smoke.sh`：`ensure_web_node_modules → ensure_playwright_chromium →
web_dist → runner_execution` 串行；`ensure_web_node_modules` 与
`ensure_playwright_chromium` 逻辑上独立但被串行等待。`ci-web-e2e-lane.sh`/
`ci-web-e2e-full.sh` 为依赖 → dist → runner 串行。归属 Web CI 专项，本专项不改。

## 3. 关键路径实测基线（可复现）

> 环境：本仓库 worktree `upstream/main@d4d2daef0`，Linux x86_64，`rg 14.1.0`
> （本地已安装；Jenkins worker 亦含 rg）。时序 `date +%s%3N`。原始串行基线为
> 未修改脚本在相同 checkout 上的实测。

### 3.1 harness-fast 串行基线（before）

| 测量 | wall-clock |
|---|---|
| 原始串行脚本（提交态） | **22,210 ms**，exit 0 |

### 3.2 分项耗时（串行，auditable）

| 检查 | duration_ms |
|---|---|
| `check-frontend-quality.py` | 4,283 |
| `check-performance-static.py` | 4,214 |
| `check-test-quality.py` | 3,646 |
| `internal-api-clean-code-design.sh` | 2,129 |
| `check-store-refactor-boundaries.sh` | 2,066 |
| `tidb-migration-history-test.sh` | 1,183 |
| `check-code-shape.py` | 949 |
| `specs-and-guardrails-layout.sh` | 763 |
| `check-store-json-tags.py` | 692 |
| `check-observability.sh` | 605 |
| `workspace-boundaries.sh` | 519 |
| `make check-electron-cutover` | 718 |
| 其余 11 项（每项 < 200ms） | ~900 |

串行关键路径 ≈ 各检查之和 ≈ 22.9s；**主要耗时来源**为前 5 项（合计 ~16.3s，
占 71%）。静态论据：串行 makespan = Σ(各检查)；并行 makespan 下界 = max(各检查)
≈ 4.3s（未计调度/争用）。

### 3.3 并行后的 makespan（after）

| 配置 | wall-clock | 相对串行 |
|---|---|---|
| 新脚本 `HARNESS_FAST_JOBS=1`（串行等价） | 22,634 ms | +1.9%（时序/IO 开销） |
| 新脚本默认 `HARNESS_FAST_JOBS=4` | 8,451 ms / 8,420 ms | **−62%** |
| 新脚本 `HARNESS_FAST_JOBS=8` | 7,023 ms | −68% |

所有配置 exit 0、23/23 检查通过、门禁语义不变。

## 4. 已落地优化：harness-fast 并行 + 时序

改动文件：`scripts/harness-fast.sh`、`scripts/harness-fast.test.mjs`。

- **并行执行**：`run` 改为有序入队 + 有界并发（`HARNESS_FAST_JOBS`，默认 4，
  设 1 即复现历史串行行为，作为回滚/降级开关）。每项检查输出捕获到临时文件；
  全部检查无论成败均执行；失败在声明序汇总并回放输出。门禁契约与旧串行循环
  完全一致（`failures` 数组、`- label (exit N)` 汇总、非零退出）。
- **时序可观测性**：每项检查向 stderr 输出
  `[harness:timing] job=… script=harness-fast label=… status=… duration_ms=…`，
  与现有 `[e2e:timing]` 约定一致，便于 Jenkins 日志基线化。
- 并行安全性：已核对 harness 内全部 guardrail 均为只读或使用 `mktemp` 唯一
  临时目录；无固定 `/tmp` 路径（`scope-message-cutover.sh` 的固定路径脚本不在
  harness-fast 调用集内）；无端口绑定。

## 5. 验证

- `bash -n scripts/harness-fast.sh` 通过。
- `node --test scripts/harness-fast.test.mjs`：3/3 通过（含新增并行契约断言：
  `HARNESS_FAST_JOBS` 存在、`run` 分发全部检查、drain 在全部入队后、`[harness:timing]` 输出）。
- 失败语义验证：将 guardrail 替换为 `true/false/sh -c 'exit 3'` 副本，并行下
  3 项失败全部被收集、声明序输出、失败输出回放、exit 1。
- `make harness-fast` 通过（见 §3.3）。

## 6. 仓库外 Jenkins 编排建议（不可在仓库内实施）

以下建议基于 §1.2 证据，供 Jenkins 配置方落地（仓库内无法修改）：

1. **独立并行 stage**：将 `harness-fast`（语言无关）与 backend required 校验
   （Go 装备 worker）拆为并行 stage，避免串行等待；二者无依赖。
2. **Web 入口拆分**：`ci-web-smoke`（required gate）与 `ci-web-e2e-lane` 各 lane
   独立 job 并行；保留 `npm run e2e:ci:plan` 的 wave 顺序（见 `docs/development.md`）。
3. **backend shard 并行**：8 个 shard 已按脚本支持独立 `run <shard>`，应并发启动
   （归属 Backend 专项基线）。
4. **可观测性**：采集 `[e2e:timing]`/`[harness:timing]` 行到 Jenkins 日志索引，
   按 job/step 建 makespan 趋势。

## 7. 兼容性 / 回滚 / 遗留风险

- **兼容性**：`harness-fast.sh` 外部契约（入参、退出码、`failures` 汇总格式、
  `make harness-fast` 委托关系）不变；新增 env 为可选。`HARNESS_FAST_JOBS=1`
  复现历史串行时序。
- **回滚**：删除/还原 `scripts/harness-fast.sh` 与 `scripts/harness-fast.test.mjs`
  两个文件即可；无数据迁移、无 schema 变更、无 Web/Backend 脚本依赖。
- **遗留风险**：
  1. 并行执行下成功检查的实时输出被捕获而非流式（失败时才回放；成功仅保留
     `[harness:timing]` 行）。若需要完整输出，可设置 `HARNESS_FAST_VERBOSE`（当前
     未实现）或降低 `HARNESS_FAST_JOBS`。
  2. 并行争用（CPU/IO）可能在高负载 worker 上放大单检查耗时；建议按 worker 规格
     调 `HARNESS_FAST_JOBS`（4~8）。
  3. 本环境初始缺 `rg`，导致 3 项 guardrail fail-fast（~6ms 级）；Jenkins 已含
     rg，本地运行需安装（见 §3）。与本次优化无关。
  4. `make regression-fast`/`make test` 的聚合串行链未在本提交并行化，仍建议
     优先在 Jenkins 层做 stage 并行（§6）。