fix(deps): preflight runtime dependencies

.github/workflows/ci.yaml

@@ -233,6 +233,15 @@ jobs:
       - name: Regression test tokenless catalog version mismatch detection
         run: bash tests/test-check-component-versions.sh
 
+  check-build-runtime-deps:
+    name: Check build runtime dependencies
+    runs-on: anolisa-k8s-general-ci-x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Test aggregated runtime dependency preflight
+        run: bash tests/test-build-all-runtime-deps.sh
+
   # =========================================================================
   # Step 3: Build & Lint copilot-shell
   # =========================================================================

.github/workflows/sec-core-source-code-build.yaml

@@ -36,7 +36,7 @@ jobs:
         if: matrix.container != ''
         run: |
           sed -i -e "s/cloud.aliyuncs/aliyun/g" /etc/yum.repos.d/*.repo
-          dnf install -y tar git sudo
+          dnf install -y tar git sudo bubblewrap gnupg2 jq
           # Fix sudo PAM in container: replace with permissive config
           cat > /etc/pam.d/sudo <<'EOF'
           #%PAM-1.0
@@ -45,12 +45,44 @@ jobs:
           session    sufficient   pam_permit.so
           EOF
       - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Expose Node.js in the system PATH
+        run: |
+          node_backup="${RUNNER_TEMP}/anolisa-system-node-backup"
+          if sudo test -e /usr/local/bin/node || sudo test -L /usr/local/bin/node; then
+            sudo mv /usr/local/bin/node "$node_backup"
+          fi
+          restore_node() {
+            sudo rm -f /usr/local/bin/node
+            if sudo test -e "$node_backup" || sudo test -L "$node_backup"; then
+              sudo mv "$node_backup" /usr/local/bin/node
+            fi
+          }
+          trap restore_node ERR
+          sudo ln -s "$(command -v node)" /usr/local/bin/node
+          PATH=/usr/local/bin:/usr/bin:/bin node --version
+          echo "ANOLISA_NODE_BACKUP=${node_backup}" >> "$GITHUB_ENV"
+          trap - ERR
+      - name: Install runtime dependencies (Ubuntu 22.04)
+        if: matrix.container == ''
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bubblewrap gnupg jq
       - uses: dtolnay/rust-toolchain@1.93.0
         with:
           components: clippy, rustfmt, rust-src
       - name: Build and install
         run: |
-          ./scripts/build-all.sh --component sec-core
+          build_status=0
+          ./scripts/build-all.sh --component sec-core || build_status=$?
+          if (( build_status != 0 )); then
+            echo "::group::sec-core build failure log"
+            tail -n 200 target/build.log 2>/dev/null || echo "target/build.log is unavailable"
+            echo "::endgroup::"
+            exit "$build_status"
+          fi
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
       - name: Verify CLI
         run: |
@@ -60,6 +92,17 @@ jobs:
         run: agent-sec-daemon --help
       - name: Verify sandbox
         run: linux-sandbox --help
+      - name: Verify runtime dependencies
+        run: |
+          sec_runtime_path=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+          PATH="$sec_runtime_path" bwrap --version
+          if PATH="$sec_runtime_path" command -v gpg >/dev/null; then
+            PATH="$sec_runtime_path" gpg --version
+          else
+            PATH="$sec_runtime_path" gpg2 --version
+          fi
+          PATH="$sec_runtime_path" node --version
+          PATH="$sec_runtime_path" jq --version
       - name: Verify deployment
         run: |
           echo "=== Skills ==="
@@ -90,12 +133,40 @@ jobs:
           ls ~/.local/lib/anolisa/sec-core/venv/bin/agent-sec-cli
       - name: Run E2E tests
         run: make -C src/agent-sec-core test-e2e-source-build
+      - name: Restore system Node.js
+        if: always()
+        run: |
+          [[ -n "${ANOLISA_NODE_BACKUP:-}" ]] || exit 0
+          sudo rm -f /usr/local/bin/node
+          if sudo test -e "$ANOLISA_NODE_BACKUP" || sudo test -L "$ANOLISA_NODE_BACKUP"; then
+            sudo mv "$ANOLISA_NODE_BACKUP" /usr/local/bin/node
+          fi
 
   system-build:
     name: Source Build System Install (Ubuntu 22.04)
     runs-on: anolisa-k8s-general-ci-x64
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Expose Node.js in the system PATH
+        run: |
+          node_backup="${RUNNER_TEMP}/anolisa-system-node-backup"
+          if sudo test -e /usr/local/bin/node || sudo test -L /usr/local/bin/node; then
+            sudo mv /usr/local/bin/node "$node_backup"
+          fi
+          restore_node() {
+            sudo rm -f /usr/local/bin/node
+            if sudo test -e "$node_backup" || sudo test -L "$node_backup"; then
+              sudo mv "$node_backup" /usr/local/bin/node
+            fi
+          }
+          trap restore_node ERR
+          sudo ln -s "$(command -v node)" /usr/local/bin/node
+          PATH=/usr/local/bin:/usr/bin:/bin node --version
+          echo "ANOLISA_NODE_BACKUP=${node_backup}" >> "$GITHUB_ENV"
+          trap - ERR
       - uses: dtolnay/rust-toolchain@1.93.0
         with:
           components: clippy, rustfmt, rust-src
@@ -105,14 +176,32 @@ jobs:
           sudo apt-get install -y passwd util-linux
       - name: Build and install in system mode
         run: |
-          ./scripts/build-all.sh --component sec-core --system
+          build_status=0
+          ./scripts/build-all.sh --component sec-core --system || build_status=$?
+          if (( build_status != 0 )); then
+            echo "::group::sec-core build failure log"
+            tail -n 200 target/build.log 2>/dev/null || echo "target/build.log is unavailable"
+            echo "::endgroup::"
+            exit "$build_status"
+          fi
       - name: Verify system commands
         run: |
           agent-sec-cli --version
           agent-sec-cli --help
           agent-sec-cli scan-pii --help >/dev/null
           agent-sec-daemon --help
           linux-sandbox --help
+      - name: Verify runtime dependencies
+        run: |
+          sec_runtime_path=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+          PATH="$sec_runtime_path" bwrap --version
+          if PATH="$sec_runtime_path" command -v gpg >/dev/null; then
+            PATH="$sec_runtime_path" gpg --version
+          else
+            PATH="$sec_runtime_path" gpg2 --version
+          fi
+          PATH="$sec_runtime_path" node --version
+          PATH="$sec_runtime_path" jq --version
       - name: Verify system deployment
         run: |
           echo "=== System binaries ==="
@@ -149,5 +238,14 @@ jobs:
           esac
           namei -l /usr/local/lib/anolisa/sec-core/venv/bin/python
           sudo useradd -m -s /bin/bash secprobe || true
+          sudo -u secprobe env PATH=/usr/local/bin:/usr/bin:/bin node --version
           sudo -u secprobe /usr/local/bin/agent-sec-cli --version
           sudo -u secprobe /usr/local/bin/agent-sec-cli scan-pii --help >/dev/null
+      - name: Restore system Node.js
+        if: always()
+        run: |
+          [[ -n "${ANOLISA_NODE_BACKUP:-}" ]] || exit 0
+          sudo rm -f /usr/local/bin/node
+          if sudo test -e "$ANOLISA_NODE_BACKUP" || sudo test -L "$ANOLISA_NODE_BACKUP"; then
+            sudo mv "$ANOLISA_NODE_BACKUP" /usr/local/bin/node
+          fi

AGENTS.md

@@ -29,7 +29,7 @@ This file provides context for AI coding assistants (Qoder, Claude, etc.) workin
 # Unified build (recommended — handles deps, build, and user install)
 ./scripts/build-all.sh                                        # integrated default components
 ./scripts/build-all.sh --no-install                           # build only, skip install
-./scripts/build-all.sh --ignore-deps                          # skip dep installation
+./scripts/build-all.sh --ignore-deps                          # skip dependency setup and runtime verification
 ./scripts/build-all.sh --component cosh --component sec-core  # selected components
 
 # Partial convenience test runner (five components; may skip unavailable suites)

docs/BUILDING.md

@@ -15,8 +15,9 @@ git clone https://github.com/alibaba/anolisa.git
 cd anolisa
 ```
 
-The common prerequisites are Git, Bash, `make`, a C compiler for native Rust
-or Python extensions, and a working network connection for package downloads.
+The common prerequisites are Git, Bash 4.3 or newer, `make`, a C compiler for
+native Rust or Python extensions, and a working network connection for package
+downloads.
 Platform-specific requirements are listed in the component matrix below. The
 repository does not define one global Rust version. Use the `rust-toolchain.toml`
 or `rust-version` declared by the component you are changing.
@@ -68,6 +69,15 @@ directory so rustup can select the pin automatically. For an unpinned
 component, check its `Cargo.toml` and the installed stable toolchain before
 building.
 
+uv-managed Python runtimes default to the official
+`astral-sh/python-build-standalone` downloads on GitHub. If that endpoint is
+unreachable, set `UV_PYTHON_INSTALL_MIRROR` to the base URL of a compatible
+mirror before building:
+
+```bash
+export UV_PYTHON_INSTALL_MIRROR="https://your-mirror.example/python-build-standalone"
+```
+
 ## 4. Unified build script
 
 `scripts/build-all.sh` is a convenience entry point, not a complete monorepo
@@ -88,6 +98,15 @@ system dependency installation may still request `sudo`. Use `--system` (or
 invoke `sudo`. `--no-install` builds and stages artifacts without installing
 them.
 
+Before installing component files, the script collects and checks the runtime
+contract for every selected component. In user mode, missing native runtime
+packages are reported together with one package-manager command and the script
+exits without installing component files. In system mode, installable native
+runtime packages are handled in one transaction, while missing language
+runtimes or platform capabilities stop the run before package mutation. A
+system install that needs Node.js requires Node.js 20 or newer in the standard
+system PATH.
+
 ```bash
 # Default six components, user install
 ./scripts/build-all.sh
@@ -117,6 +136,10 @@ them.
 ./scripts/build-all.sh --help
 ```
 
+`--ignore-deps` skips both dependency setup and runtime dependency
+verification. Use it only on a pre-provisioned host; the caller is responsible
+for ensuring that installed components have all required runtimes.
+
 Valid `--component` names are `cosh`, `skills`, `sec-core`, `tokenless`,
 `ws-ckpt`, `memory`, `cosh-ng`, and `sight`. The script may build a component
 in `target/` before installing it, and a component's own install policy still

docs/BUILDING_zh.md

@@ -13,9 +13,10 @@ git clone https://github.com/alibaba/anolisa.git
 cd anolisa
 ```
 
-通用前置条件包括 Git、Bash、`make`、用于编译 Rust 或 Python 原生扩展的 C 编译器，
-以及可下载依赖的网络环境。组件矩阵会列出平台特有的要求。仓库没有统一的 Rust
-版本，构建某个组件时请遵循该组件声明的 `rust-toolchain.toml` 或 `rust-version`。
+通用前置条件包括 Git、Bash 4.3 或更高版本、`make`、用于编译 Rust 或 Python
+原生扩展的 C 编译器，以及可下载依赖的网络环境。组件矩阵会列出平台特有的要求。
+仓库没有统一的 Rust 版本，构建某个组件时请遵循该组件声明的
+`rust-toolchain.toml` 或 `rust-version`。
 
 ## 2. 仓库结构
 
@@ -60,6 +61,14 @@ Linux-only 组件。
 组件有固定工具链时，从该组件目录执行命令，rustup 会自动选择对应版本。没有固定
 版本的组件应先查看自己的 `Cargo.toml` 和当前 stable 工具链，再开始构建。
 
+由 uv 管理的 Python runtime 默认从 GitHub 官方
+`astral-sh/python-build-standalone` 下载。若当前网络无法访问该地址，请在构建前将
+`UV_PYTHON_INSTALL_MIRROR` 设置为兼容镜像的 base URL。
+
+```bash
+export UV_PYTHON_INSTALL_MIRROR="https://your-mirror.example/python-build-standalone"
+```
+
 ## 4. 统一构建脚本
 
 `scripts/build-all.sh` 是便捷入口，并不负责构建整个 monorepo。当前脚本支持 8 个
@@ -77,6 +86,12 @@ Linux-only 组件。
 `--install-mode system`）切换到系统路径，脚本会暂存文件并可能调用 `sudo`。
 `--no-install` 只构建并暂存制品，不执行安装。
 
+安装组件文件前，脚本会集中收集并检查所有已选组件的 runtime contract。user mode
+若缺少系统 runtime package，会一次性列出缺失项和 package manager 安装命令，然后
+在安装任何组件文件前退出。system mode 会用一次事务安装可自动处理的原生 runtime
+package；若缺少 language runtime 或 platform capability，则在修改 package 前退出。
+需要 Node.js 的 system install 必须能从标准 system PATH 找到 Node.js 20 或更高版本。
+
 ```bash
 # Default six components, user install
 ./scripts/build-all.sh
@@ -106,6 +121,9 @@ Linux-only 组件。
 ./scripts/build-all.sh --help
 ```
 
+`--ignore-deps` 会同时跳过 dependency setup 和 runtime dependency verification。
+它只适用于已经准备好全部依赖的主机，调用者需要自行保证安装后的组件具备所需 runtime。
+
 `--component` 的合法名称为 `cosh`、`skills`、`sec-core`、`tokenless`、`ws-ckpt`、
 `memory`、`cosh-ng` 和 `sight`。脚本可能先在 `target/` 中生成构建结果，再执行安装，
 最终行为仍由组件自己的安装规则决定。例如 `ws-ckpt` 只有在 `--system` 下才会安装

docs/user-guide/en/agent-security/agent-sec-core/QUICKSTART.md

@@ -58,6 +58,12 @@ Developers building from source should use the repository-level entry point:
 ./scripts/build-all.sh --component sec-core
 ```
 
+Before installing files, the source-build entry point checks Node.js 20 or
+newer, bubblewrap, GnuPG, and `jq`. User mode reports all missing system
+runtime packages with one install command and exits; install them and rerun the
+same command. `--ignore-deps` bypasses this verification for pre-provisioned
+hosts.
+
 The source build installs the runtime and integration resources in user paths,
 but it does not register `sec-core` in ANOLISA state. Do not follow it with
 `anolisa adapter enable`; use the source integration scripts documented below.

docs/user-guide/zh/agent-security/agent-sec-core/QUICKSTART.md

@@ -56,6 +56,11 @@ sudo anolisa --install-mode system adopt sec-core
 ./scripts/build-all.sh --component sec-core
 ```
 
+安装文件前，源码构建入口会检查 Node.js 20 或更高版本、bubblewrap、GnuPG 和
+`jq`。user mode 会一次性列出缺少的系统 runtime package 和安装命令，然后退出；
+安装这些依赖后重新执行同一命令即可。已提前准备好依赖的主机可以用
+`--ignore-deps` 跳过检查。
+
 源码构建会把运行时和集成资源安装到用户目录，但不会在 ANOLISA 状态中注册
 `sec-core`。这种安装方式不能继续执行 `anolisa adapter enable`，请使用下文的
 源码集成脚本。