Merge branch 'refactor/thin-channel-thick-runner' into fork-main-tmp

Author: 2233admin

.env.example

@@ -10,6 +10,16 @@ APP_ENV=production
 DEBUG=false
 SECRET_KEY=change-me-in-production-use-long-random-string
 
+# Fleet 鉴权（ADR-0005）：所有 /api 路由的静态 Bearer Token。
+# 留空 = 关闭鉴权（开发姿态，启动时仅允许绑定 localhost）；
+# 非 localhost 绑定（如 Docker 的 0.0.0.0）必须设置，否则启动直接拒绝。
+# 前端取值：构建期 VITE_API_AUTH_TOKEN，或浏览器 localStorage 'apiAuthToken'（优先）。
+# MCP server / CLI（backend/mcp_server.py、backend/cli.py）读同名环境变量。
+# 一旦设置此值，边缘 Agent（backend/agent_server.py）也必须设置同值的 AGENT_API_TOKEN
+# （或直接复用 API_AUTH_TOKEN）——覆盖 HTTP 注册（/api/v1/nodes/register）和
+# WS 反向通道（/api/v1/nodes/ws、/api/v1/browsers/agents/ws）两条握手路径。
+API_AUTH_TOKEN=
+
 # 服务端口（两种启动模式均生效）
 API_PORT=8031        # API 服务对外端口
 FRONTEND_PORT=8030   # 前端页面对外端口
@@ -39,6 +49,32 @@ TASK_EXECUTOR=local
 # ODP_INGEST_URL=http://odp-ingest:8040
 # III_URL=ws://iii-engine:49134
 
+# ── ODP 数据面（Python 侧：backend/pipeline/odp_client.py）───────────────────
+# ODP ingest（Rust 热路径）的 HTTP 地址。留空 = 不转发（走 sqlite legacy 路径）。
+# ODP_INGEST_URL=http://odp-ingest:8040
+# ODP HTTP 请求超时（秒）。默认 10。
+# ODP_INGEST_TIMEOUT=10
+# ODP 转发失败时的语义（backend/pipeline/storer.py）：
+#   unset/false（默认，fail-open）— 转发异常仅 log warning，继续走 sqlite legacy 路径，不中断采集
+#   true/1/yes（fail-closed）     — 转发异常直接 raise，中断该次采集任务
+# ODP_INGEST_REQUIRED=false
+
+# ── ODP 数据面（Rust 侧：odp-rs/crates/*）──────────────────────────────────
+# odp-store 的 Postgres 连接串；未设置时回退读 DATABASE_URL（见 odp-store/src/main.rs）。
+# ODP_DATABASE_URL=postgresql://opencli:opencli_secret@postgres:5432/opencli_admin
+# odp-store 每批写入 Postgres 的最大行数。默认 500。
+# ODP_STORE_BATCH_SIZE=500
+# Redis Stream 消费者组名（odp-bus）。默认 "odp-store"。
+# ODP_BUS_GROUP=odp-store
+# Redis Stream 消费者实例名（odp-bus）。默认 "<hostname>-<pid>"，同组内建议每实例唯一。
+# ODP_BUS_CONSUMER=
+# odp-ingest 允许无 Redis bus 启动的显式开关（commit d1f33d9）。
+#   默认关闭 = fail-fast：没有可用的 Redis bus（ODP_REDIS_URL/REDIS_URL 未设置或不可达）时，
+#     odp-ingest 直接拒绝启动 —— 没有 bus 就没有持久化，装作 202 accepted 是在撒谎。
+#   =1 才是显式的 dev/test-only 例外：仅在内存里跑，事件全部当作未持久化处理（见 handlers.rs），
+#     绝不能在生产/NAS 部署中打开。
+# ODP_INGEST_ALLOW_NO_BUS=0
+
 # 采集模式
 # local  — 默认，API 直接驱动本地 Docker 网络内的采集器（Chrome、爬虫等）
 # agent  — 分布式边缘采集；采集任务分发到远端 Agent 节点执行
@@ -67,6 +103,11 @@ CELERY_RESULT_BACKEND=redis://redis:6379/1
 API_KEY_ENABLED=false
 API_KEY=
 
+# CLI 渠道二进制白名单（ADR-0005，审计 P0-4）。cli 渠道会执行任意二进制，
+# 只有列在这里的二进制才允许运行；逗号分隔完整路径/名称，留空（默认）= 全部拒绝。
+# 例：CLI_CHANNEL_ALLOWED_BINARIES=/usr/bin/mycli,C:\tools\other.exe
+CLI_CHANNEL_ALLOWED_BINARIES=
+
 # 邮件发送（通知渠道使用）
 SMTP_HOST=
 SMTP_PORT=587

.github/workflows/ci.yml

@@ -30,9 +30,15 @@ jobs:
       - name: Install dependencies
         run: npm ci --legacy-peer-deps
 
+      - name: Typecheck
+        run: npm run typecheck --if-present
+
       - name: Test
         run: npm run test
 
+      - name: Lint (design token gate)
+        run: npm run lint
+
       - name: Build
         run: npm run build
 
@@ -63,6 +69,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Typecheck
+        run: npm run typecheck
+
       - name: Build
         run: npm run build
 
@@ -93,5 +102,112 @@ jobs:
       - name: Backend syntax check
         run: python -m compileall backend
 
-      - name: Unit tests
-        run: pytest tests/unit -m "not live" --no-cov
+      # Coverage visibility, not a gate: pyproject.toml bakes in
+      # `--cov-fail-under=80` via [tool.pytest.ini_options].addopts, but the
+      # current suite sits at ~70% total. Enforcing 80% here would turn CI red
+      # immediately for pre-existing gaps, not for anything this PR changes.
+      # `--cov-fail-under=0` overrides the pyproject default (last CLI value
+      # wins) so the job stays green while the report is printed every run.
+      # TODO(ratchet): once real coverage is measured for a few weeks, raise
+      # this floor incrementally (e.g. 70 -> 75 -> 80) instead of jumping
+      # straight to the pyproject target.
+      - name: Unit tests (with coverage report)
+        run: pytest tests/unit -m "not live" --cov=backend --cov-report=term-missing --cov-fail-under=0
+
+  migrations:
+    runs-on: ubuntu-latest
+    name: Alembic Migrations
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: opencli_admin
+          POSTGRES_USER: opencli
+          POSTGRES_PASSWORD: opencli_secret
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U opencli"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      # backend/config.py Settings.database_url (case-insensitive env,
+      # see backend/migrations/env.py which overrides alembic.ini's
+      # sqlalchemy.url from settings.database_url at runtime).
+      DATABASE_URL: postgresql+asyncpg://opencli:opencli_secret@localhost:5432/opencli_admin
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Wait for Postgres
+        run: python -c "import time; time.sleep(2)"
+
+      - name: alembic upgrade head
+        run: alembic upgrade head
+
+      # Catches broken downgrade() bodies / non-reversible migrations before
+      # merge: a chain that only ever gets tested via upgrade() can silently
+      # rot (dropped columns with no re-add, wrong op order, etc.).
+      - name: alembic downgrade/upgrade smoke test
+        run: |
+          alembic downgrade -1
+          alembic upgrade head
+
+      # AUDIT follow-up (c): the cursor concurrency tests run on SQLite in the
+      # backend job, where `SELECT ... FOR UPDATE` is a silent no-op — they
+      # prove the code path but not that the lock serializes writers. Re-run the
+      # Postgres-gated variant here (schema already at head above, DATABASE_URL
+      # is Postgres so the test's skip-gate activates), where the row lock is
+      # actually enforced, so a regression in cursor_store's per-source locking
+      # is caught. --no-cov: this is a targeted single-test step, not a coverage
+      # run (pyproject's addopts would otherwise fail it under the 80% gate).
+      - name: cursor FOR UPDATE locking (Postgres)
+        run: pytest tests/unit/pipeline/test_db_cursor_store.py -k postgres --no-cov -p no:cacheprovider
+
+  cargo:
+    runs-on: ubuntu-latest
+    name: ODP Rust (odp-rs)
+    defaults:
+      run:
+        working-directory: odp-rs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - name: Cache cargo registry + target
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            odp-rs/target
+          key: ${{ runner.os }}-cargo-odp-rs-${{ hashFiles('odp-rs/Cargo.lock', 'odp-rs/**/Cargo.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-odp-rs-
+
+      # No live Redis/Postgres here: odp-bus/odp-ingest/odp-store tests are
+      # unit-level (dedup logic, contract (de)serialization, stream naming).
+      # If integration tests that need a real broker/DB are added later, gate
+      # them behind a feature flag or #[ignore] + a service-container job,
+      # the same way `pytest -m live` is deselected in the backend job.
+      - name: cargo test --workspace
+        run: cargo test --workspace
+
+      - name: cargo clippy --workspace -- -D warnings
+        run: cargo clippy --workspace --all-targets -- -D warnings

CLAUDE.md

@@ -0,0 +1,12 @@
+# opencli-admin
+
+## 前端样式 — 必读
+
+改 `frontend/src` 下任何 UI 前, 先读 [docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md)（锁定版设计系统, 顶部有 30 秒速查表）。
+
+硬规则速记:
+- 背景只用 `bg-ops-black/panel/raised` 三级, 禁手写近黑 hex
+- 灰阶只用 zinc; 交互色只用 primary; 状态色 emerald/amber/red/sky/violet
+- 字号禁 `text-[Npx]` 任意值, 用 `text-2xs`(11px)/`text-3xs`(10px)
+- 圆角: 控件 `rounded-xs`, 面板 `rounded-md`; 阴影用 `shadow-panel/overlay/drag`
+- 缺 ui 原语用 `npx shadcn@latest add <x>` 拉, 禁手搓

CONTEXT.md

@@ -4,14 +4,14 @@ OpenCLI Admin is an operations console for collection work that needs browser se
 
 ## Language
 
-**Collection Operations Console**: The primary operator surface for turning collection work into captured, triaged, owned, stateful, and closed work. It is the product shape that contains Run Inbox, Data Sources, Live Collection View, and Diagnostic Canvas without making any one visualization the whole product.
-_Avoid_: Dashboard wall, canvas-first app
+**Collection Operations Console**: The primary operator surface for turning collection work into captured, triaged, owned, stateful, and closed work. It is the product shape that contains Run Inbox, Data Sources, Live Collection View, and the Collection Canvas.
+_Avoid_: Dashboard wall
 
-**Collection Operations**: The operator-facing domain for deciding what should be collected, when collection should run, what recently happened, and which actions are currently safe. It groups Data Sources, Collection Plans, Recent Runs, and Node Actions without making a canvas the primary operating surface.
-_Avoid_: Source Workflow Workbench, canvas-first operations
+**Collection Operations**: The operator-facing domain for deciding what should be collected, when collection should run, what recently happened, and which actions are currently safe. It groups Data Sources, Collection Plans, Recent Runs, and Node Actions.
+_Avoid_: Source Workflow Workbench
 
-**Diagnostic Canvas**: A secondary view for understanding relationships among collection entities when troubleshooting or explaining system state. It is not the default place to configure routine collection work.
-_Avoid_: Main workflow, primary operating surface
+**Collection Canvas**: The primary authoring surface for collection logic — the graph IS the program. Defining and editing what a source collects happens on the canvas; forms survive only as the inspector panel of a selected node. Absorbs the old Diagnostic Canvas's troubleshooting role.
+_Avoid_: Diagnostic Canvas (superseded 2026-07-02: canvas promoted from secondary diagnostic view to primary authoring surface), form-first configuration
 
 **Live Collection View**: The operator-facing view of an active collection run as it happens, including streamed progress, rendered browser or pipeline state, and run-specific artifacts. It is anchored to a Recent Run, not to the default configuration surface.
 _Avoid_: Static task log, canvas-only monitoring
@@ -21,3 +21,46 @@ _Avoid_: Clock shop, always-on dashboard wall
 
 **Run Inbox**: The operator-facing queue of collection runs that need observation, review, retry, acknowledgement, or dismissal. It treats a run as work to triage and close, not as a passive row in a log table.
 _Avoid_: Recent tasks table, static run history
+
+### Control
+
+**Advisory Mode**: The control-loop operating mode in which suggested actions are surfaced to the operator and recorded as evidence, but never executed.
+_Avoid_: dry-run mode, suggestion mode
+
+**Automatic Mode**: The control-loop operating mode in which the Actuator may execute suggestions itself, opened per state class only when accumulated evidence justifies it.
+_Avoid_: autopilot, self-healing mode
+
+**Actuator**: The component that carries out control actions against the collection system. It executes only whitelisted safe actions; everything else it downgrades.
+_Avoid_: executor, auto-fixer
+
+**Evidence Ledger**: The durable record of every control suggestion and execution, together with the outcome later judged from post-decision measurements.
+_Avoid_: action log, audit trail
+
+**Recovery Rate**: The share of judged suggestions whose triggering state later cleared. It is the quantified basis for opening Automatic Mode.
+_Avoid_: success rate, fix rate
+
+**Require-Review Downgrade**: The policy that suggestions too dangerous to automate are executed only as "flag the source for human review", never as the suggested action itself.
+_Avoid_: blocked action, action rejection
+
+**Control Cycle**: The background loop that periodically measures every source, decides, and — in Automatic Mode — acts. It runs regardless of whether any UI is open.
+_Avoid_: polling-driven control, frontend-triggered control
+
+### Plan
+
+**Plan**: A free multi-source graph on the Collection Canvas — any number of source nodes, transforms, merges, and sinks in one graph. The Plan is the program; a Data Source's legacy config is the degenerate single-node Plan.
+_Avoid_: per-source pipeline (rejected 2026-07-02 in favor of free graphs), workflow (overloaded)
+
+**Two-Tier Attribution**: The observability contract for Plans. A source node is a real Data Source and its collection segment keeps per-source measurement unchanged (the control kernel is untouched); everything downstream of a merge belongs to Plan Health, and a shared-segment failure is never written into any source's state.
+_Avoid_: blaming all upstream sources, plan-only attribution
+
+**Plan Health**: The health of a Plan's shared (post-merge) segments, measured per plan node, kept as its own dimension beside per-source measurement. A dedupe node failing does not make its upstream sources DEGRADED.
+_Avoid_: folding plan failures into source state
+
+**Preset**: A packaged, one-click node configuration (e.g. an opencli site + command + format bundled as "雪球·热帖") registered in the node library and searchable from the palette. Presets are fed from backend adapter metadata, never hardcoded in the frontend. The advanced inspector still exposes raw parameters.
+_Avoid_: raw site/command dropdowns as the default UI
+
+**Draft Source Node**: A source node placed on the Collection Canvas that does not yet reference a real Data Source. It renders visibly unmaterialized, cannot run, and does not enter the control loop until it is materialized into an entity.
+_Avoid_: fake canvas-only nodes that look real
+
+**Dry-Run Preview**: The in-browser execution of a Plan on fixture data, explicitly labeled as a preview. It never produces collection results — the backend Plan executor is the only authoritative execution.
+_Avoid_: browser-side "real" runs, split-brain execution

README.md

@@ -6,7 +6,7 @@
 
 ## v0.4 前端基线
 
-- `frontend/` 是唯一生产前端主线：React + Vite。
+- `frontend/` 是唯一生产前端主线：React + Vite。改 UI 前先读 [docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md)（锁定版设计系统, 顶部 30 秒速查表）。
 - `experiments/next-web/` 只是 Next.js 实验壳，不接入默认 Docker、CI 或导航。
 - 默认 `docker compose up --build` 会构建仓库内的 `frontend/`，不会拉取旧的上游前端镜像。
 - 拓扑画布属于实验能力；设置 `VITE_ENABLE_TOPOLOGY_LAB=true` 后才开放 `/labs/topology`。

backend/agent_runtimes/__init__.py

@@ -0,0 +1 @@
+"""Agent-runtime adapter package. Import registry to trigger auto-registration."""