diff --git a/docs/ci.md b/docs/ci.md index 5bec6922f7c..145b1284d63 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -1,155 +1,63 @@ --- title: CI Pipeline -description: How the OpenClaw CI pipeline works and why jobs are ordered the way they are. +description: How the OpenClaw CI pipeline works --- # CI Pipeline -OpenClaw uses a tiered CI pipeline that fails fast on cheap checks before -running expensive builds and tests. This saves runner minutes and reduces -GitHub API pressure. +The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only docs or native code changed. -## Pipeline Tiers +## Job Overview -``` -Tier 0 — Scope detection (~12 s, free runners) - docs-scope → changed-scope +| Job | Purpose | When it runs | +| ----------------- | ----------------------------------------------- | ------------------------- | +| `docs-scope` | Detect docs-only changes | Always | +| `changed-scope` | Detect which areas changed (node/macos/android) | Non-docs PRs | +| `check` | TypeScript types, lint, format | Non-docs changes | +| `check-docs` | Markdown lint + broken link check | Docs changed | +| `code-analysis` | LOC threshold check (1000 lines) | PRs only | +| `secrets` | Detect leaked secrets | Always | +| `build-artifacts` | Build dist once, share with other jobs | Non-docs, node changes | +| `release-check` | Validate npm pack contents | After build | +| `checks` | Node/Bun tests + protocol check | Non-docs, node changes | +| `checks-windows` | Windows-specific tests | Non-docs, node changes | +| `macos` | Swift lint/build/test + TS tests | PRs with macos changes | +| `android` | Gradle build + tests | Non-docs, android changes | -Tier 1 — Cheapest gates (parallel, ~43 s) - check-format secrets +## Fail-Fast Order -Tier 2 — After format (parallel, ~2 min) - check-lint code-analysis +Jobs are ordered so cheap checks fail before expensive ones run: -Tier 3 — Build (~3 min) - build-artifacts release-check +1. `docs-scope` + `code-analysis` + `check` (parallel, ~1-2 min) +2. `build-artifacts` (blocked on above) +3. `checks`, `checks-windows`, `macos`, `android` (blocked on build) -Tier 4 — Tests (~5 min) - checks (node tsgo / test / protocol, bun test) - checks-windows (lint / test / protocol) +## Code Analysis -Tier 5 — Platform (most expensive) - macos (TS tests + Swift lint/build/test) - android (test + build) - ios (disabled) -``` +The `code-analysis` job runs `scripts/analyze_code_files.py` on PRs to enforce code quality: -## Dependency Graph +- **LOC threshold**: Files that grow past 1000 lines fail the build +- **Delta-only**: Only checks files changed in the PR, not the entire codebase +- **Push to main**: Skipped (job passes as no-op) so merges aren't blocked -``` -docs-scope ──► changed-scope ──┐ - │ -check-format ──► check-lint ──►├──► build-artifacts ──► release-check - ├─► code-analysis ►│ └──► checks-windows - ├──► checks - ├──► macos - └──► android -secrets (independent) -``` +When `--strict` is set, violations block all downstream jobs. This catches bloated files early before expensive tests run. -## Job Details - -### Tier 0 — Scope Detection - -| Job | Runner | Purpose | -| --------------- | --------------- | ----------------------------------------------------------------------- | -| `docs-scope` | `ubuntu-latest` | Detects docs-only PRs to skip heavy jobs | -| `changed-scope` | `ubuntu-latest` | Detects which areas changed (node/macos/android) to skip unrelated jobs | - -### Tier 1 — Cheapest Gates - -| Job | Runner | Purpose | -| -------------- | ----------------- | ------------------------------------------- | -| `check-format` | Blacksmith 4 vCPU | Runs `pnpm format` — cheapest gate (~43 s) | -| `secrets` | Blacksmith 4 vCPU | Runs `detect-secrets` scan against baseline | - -### Tier 2 — After Format - -| Job | Runner | Depends on | Purpose | -| --------------- | ----------------- | -------------- | ----------------------------------------------------------- | -| `check-lint` | Blacksmith 4 vCPU | `check-format` | Runs `pnpm lint` — cleaner output after format passes | -| `code-analysis` | Blacksmith 4 vCPU | `check-format` | Checks LOC thresholds — accurate counts need formatted code | - -### Tier 3 — Build - -| Job | Runner | Depends on | Purpose | -| ----------------- | ----------------- | ----------------------------- | -------------------------------- | -| `build-artifacts` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | Builds dist and uploads artifact | -| `release-check` | Blacksmith 4 vCPU | `build-artifacts` | Validates npm pack contents | - -### Tier 4+ — Tests and Platform - -| Job | Runner | Depends on | Purpose | -| ---------------- | ------------------ | ------------------------------------------------ | ------------------------------------------------------ | -| `checks` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | TypeScript checks, tests (Node + Bun), protocol checks | -| `checks-windows` | Blacksmith Windows | `build-artifacts`, `check-lint`, `code-analysis` | Windows-specific lint, tests, protocol checks | -| `macos` | `macos-latest` | `check-lint`, `code-analysis` | TS tests + Swift lint/build/test (PR only) | -| `android` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | Gradle test + build | - -## Code-Analysis Gate - -The `code-analysis` job runs `scripts/analyze_code_files.py` on PRs to catch: - -1. **Threshold crossings** — files that grew past 1000 lines in the PR -2. **Already-large files growing** — files already over 1000 lines that got bigger -3. **Duplicate function regressions** — new duplicate functions introduced by the PR - -When `--strict` is set, any violation fails the job and blocks all downstream -work. On push to `main`, the code-analysis steps are skipped (the job passes as a -no-op) so pushes still run the full test suite. - -### Excluded Directories - -The analysis skips: `node_modules`, `dist`, `vendor`, `.git`, `coverage`, -`Swabble`, `skills`, `.pi` and other non-source directories. See the -`SKIP_DIRS` set in `scripts/analyze_code_files.py` for the full list. - -## Fail-Fast Behavior - -**Bad PR (formatting violations):** - -- `check-format` fails at ~43 s -- `check-lint`, `code-analysis`, and all downstream jobs never start -- Total cost: ~1 runner-minute - -**Bad PR (lint or LOC violations, good format):** - -- `check-format` passes → `check-lint` and `code-analysis` run in parallel -- One or both fail → all downstream jobs skipped -- Total cost: ~3 runner-minutes - -**Good PR:** - -- Critical path: `check-format` (43 s) → `check-lint` (1m 46 s) → `build-artifacts` → `checks` -- `code-analysis` runs in parallel with `check-lint`, adding no latency - -## Composite Action - -The `setup-node-env` composite action (`.github/actions/setup-node-env/`) -handles the shared setup boilerplate: - -- Node.js 22 setup -- pnpm via corepack + store cache -- Optional Bun install -- `pnpm install` with retry - -The `macos` job also caches SwiftPM packages (`~/Library/Caches/org.swift.swiftpm`) -to speed up dependency resolution. - -This eliminates ~40 lines of duplicated YAML per job. - -## Push vs PR Behavior - -| Trigger | `code-analysis` | Downstream jobs | -| -------------- | ----------------------------- | --------------------- | -| Push to `main` | Steps skipped (job passes) | Run normally | -| Pull request | Full analysis with `--strict` | Blocked on violations | +Excluded directories: `node_modules`, `dist`, `vendor`, `.git`, `coverage`, `Swabble`, `skills`, `.pi` ## Runners -| Name | OS | vCPUs | Used by | -| ------------------------------- | ------------ | ----- | ---------------- | -| `blacksmith-4vcpu-ubuntu-2404` | Ubuntu 24.04 | 4 | Most jobs | -| `blacksmith-4vcpu-windows-2025` | Windows 2025 | 4 | `checks-windows` | -| `macos-latest` | macOS | — | `macos`, `ios` | -| `ubuntu-latest` | Ubuntu | 2 | Scope detection | +| Runner | Jobs | +| ------------------------------- | ----------------------------- | +| `blacksmith-4vcpu-ubuntu-2404` | Most Linux jobs | +| `blacksmith-4vcpu-windows-2025` | `checks-windows` | +| `macos-latest` | `macos`, `ios` | +| `ubuntu-latest` | Scope detection (lightweight) | + +## Local Equivalents + +```bash +pnpm check # types + lint + format +pnpm test # vitest tests +pnpm check:docs # docs format + lint + broken links +pnpm release:check # validate npm pack +``` diff --git a/docs/docs.json b/docs/docs.json index ecd16552c76..d44137c4e1d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1232,6 +1232,16 @@ { "group": "Release notes", "pages": ["reference/RELEASING", "reference/test"] + }, + { + "group": "Experiments", + "pages": [ + "experiments/onboarding-config-protocol", + "experiments/plans/cron-add-hardening", + "experiments/plans/group-policy-hardening", + "experiments/research/memory", + "experiments/proposals/model-config" + ] } ] }, @@ -1751,6 +1761,16 @@ { "group": "发布说明", "pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"] + }, + { + "group": "实验性功能", + "pages": [ + "zh-CN/experiments/onboarding-config-protocol", + "zh-CN/experiments/plans/cron-add-hardening", + "zh-CN/experiments/plans/group-policy-hardening", + "zh-CN/experiments/research/memory", + "zh-CN/experiments/proposals/model-config" + ] } ] }, diff --git a/docs/zh-CN/vps.md b/docs/zh-CN/vps.md index 88e527bc399..26f0c51e0b9 100644 --- a/docs/zh-CN/vps.md +++ b/docs/zh-CN/vps.md @@ -19,8 +19,8 @@ x-i18n: ## 选择提供商 -- **Railway**（一键 + 浏览器设置）：[Railway](/railway) -- **Northflank**（一键 + 浏览器设置）：[Northflank](/northflank) +- **Railway**（一键 + 浏览器设置）：[Railway](/install/railway) +- **Northflank**（一键 + 浏览器设置）：[Northflank](/install/northflank) - **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定） - **Fly.io**：[Fly.io](/install/fly) - **Hetzner（Docker）**：[Hetzner](/install/hetzner) diff --git a/package.json b/package.json index 00c119cd79a..5a9ab169a00 100644 --- a/package.json +++ b/package.json @@ -36,11 +36,10 @@ "build:plugin-sdk:dts": "tsc -p tsconfig.plugin-sdk.dts.json", "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh", "check": "pnpm format:check && pnpm tsgo && pnpm lint", - "check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:build", + "check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:check-links", "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500", "dev": "node scripts/run-node.mjs", "docs:bin": "node scripts/build-docs-list.mjs", - "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links", "docs:check-links": "node scripts/docs-link-audit.mjs", "docs:dev": "cd docs && mint dev", "docs:list": "node scripts/docs-list.js",