@baize-ai/core 0.2.0 → 0.3.1

package/.dockerignore

@@ -1,18 +1,8 @@
-# Exclude node_modules at every depth, not just the repo root. Nested
-# skills/*/node_modules can carry host-compiled native binaries (e.g.
-# better-sqlite3) built for the host's Node ABI; leaking them into an image
-# running a different Node major triggers NODE_MODULE_VERSION load errors.
-# With these excluded, each skill's in-image `npm install` pulls the matching
-# prebuilt binary instead.
-**/node_modules
-.git
-.github
-*.log
-*.env
-.env.*
-!.env.example
-test
-docs
-assets
-README*.md
-CHANGELOG.md
+# Publish-mode build context: source code is NOT copied into the image.
+# Only entrypoint + PM2 ecosystem + pre-bundled Claude binary are needed.
+*
+!Dockerfile
+!docker/entrypoint.sh
+!templates/pm2/ecosystem.config.cjs
+!.claude-local/claude
+!.claude-local/claude.version

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to baize-core will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-08-25
+
+### Added
+- web-console「定时任务」只读列表视图（`/api/admin/scheduler/tasks`：tasks 表列表，无管理操作；scheduler 未启动容错）
+
+## [0.3.0] - 2026-08-25
+
+### Added
+- A2A 运行模式（单机/集群）：`baize a2a enable/disable/status` 完整事务（daemon 启动 → 身份就绪轮询 → 注册，失败回滚）；web 控制台 A2A 页模式卡 + tar.gz 上传安装（D25）
+- 证书自动生成（自签 CA + CA 签发服务器证书，共享 CA 模型）
+- `baize add` 孤儿残留自动清理（中断安装重试不再死循环，KI-024）
+- web-console `/api/admin/a2a/install`（manifest/大小/防路径穿越校验 + `--ignore-scripts`）
+- 打包脚本 `scripts/pack-release.sh`（A2A 套件私有交付）
+
+### Changed
+- A2A CLI 集成（`baize a2a` 子命令，D21-D24：card 编辑/发现重构/能力认知/凭证轮换）
+- 渠道组件 upgrade 走 npm（D18，KI-006）
+- add/uninstall 持组件锁（D20，KI-007）
+
+### Fixed
+- web-console 上传安装校验（D25 Review：身份就绪验证/凭证 issuer/CA 互信/审批抖动）
+- 组件安装残留死循环（KI-024）
+
 ## [0.2.0] - 2026-08-23
 
 ### Added
@@ -52,7 +75,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Baize (白泽) inception**: forked from zylos-core v0.7.1 as an independent project. All identifiers renamed (`zylos` → `baize`): CLI (`baize`), npm package (`@baize-ai/core`), runtime root (`~/baize/`), config dir (`~/.baize/`), env vars (`BAIZE_*`), instruction file (`BAIZE.md`), skills (`baize-memory`), PM2 service names, Docker image (`ghcr.io/baize-ai/baize-core`), and the agent persona in system templates.
+- **Baize (白泽) inception**: forked from zylos-core v0.7.1 as an independent project. All identifiers renamed (`zylos` → `baize`): CLI (`baize`), npm package (`@baize-ai/core`), runtime root (`~/baize/`), config dir (`~/.baize/`), env vars (`BAIZE_*`), instruction file (`BAIZE.md`), skills (`baize-memory`), PM2 service names, Docker image (`ghcr.io/baize01-ai/baize-core`), and the agent persona in system templates.
 
 ### Removed
 

package/Dockerfile

@@ -12,7 +12,7 @@
 
 FROM node:22-slim
 
-LABEL org.opencontainers.image.source="https://github.com/baize-ai/baize-core"
+LABEL org.opencontainers.image.source="https://github.com/baize01-ai/baize-core"
 LABEL org.opencontainers.image.description="Baize — autonomous AI agent infrastructure"
 
 # ── System packages ───────────────────────────────────────────────────────────
@@ -26,20 +26,31 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       procps \
       # For `baize doctor` network checks
       dnsutils \
+      # Native-module build toolchain (better-sqlite3 etc.): prebuild download
+      # can fail at build/runtime (GitHub Releases is a flaky source); with the
+      # toolchain present npm falls back to source compile instead of leaving a
+      # broken binary in the image (D19 container crash root cause).
+      python3 \
+      make \
+      g++ \
     && rm -rf /var/lib/apt/lists/*
 
 # ── Global npm tools ──────────────────────────────────────────────────────────
 RUN npm install -g pm2@latest
 
-# ── Claude Code CLI (pre-bundled) ─────────────────────────────────────────────
+# ── Claude Code CLI (pre-bundled, pinned version) ─────────────────────────────
 # The official install.sh downloads a ~340MB binary at container runtime, which
 # is unreliable inside container networks (fails ~90% through on Docker
-# Desktop). Bundle the verified binary in the image instead: place it at
-# .claude-local/claude in the build context (gitignored). Fetch with:
+# Desktop). Bundle a PINNED, verified binary in the image instead:
 #   curl -fsSL https://downloads.claude.ai/claude-code-releases/<ver>/linux-arm64/claude
-# and verify against the checksum in .../manifest.json (platforms.linux-arm64).
+#   (verify against .../manifest.json platforms.linux-arm64 checksum)
+#   echo <ver> > .claude-local/claude.version
+# Upgrade = replace the binary + bump claude.version, then rebuild the image
+# (explicit release decision — never auto-fetch latest at build time).
 COPY .claude-local/claude /usr/local/bin/claude
 RUN chmod +x /usr/local/bin/claude
+COPY .claude-local/claude.version /usr/local/bin/claude.version
+LABEL org.opencontainers.image.claude-version="$(cat .claude-local/claude.version 2>/dev/null || echo unknown)" 
 
 # ── Create baize user (non-root) ──────────────────────────────────────────────
 RUN useradd -m -s /bin/bash baize \
@@ -49,15 +60,58 @@ USER baize
 ENV HOME=/home/baize
 ENV NPM_CONFIG_PREFIX=/home/baize/.npm-global
 ENV PATH="/home/baize/.npm-global/bin:/home/baize/.local/bin:/usr/local/bin:${PATH}"
+# Web console must listen on all interfaces for Docker port mapping to work
+# (default is 127.0.0.1, which Docker Desktop cannot reach). PM2 fork mode
+# inherits process env, so this reaches the web-console service even when the
+# bundled ecosystem.config.cjs predates the WEB_CONSOLE_BIND field.
+ENV WEB_CONSOLE_BIND=0.0.0.0
 
-# ── Install baize-core from local source ─────────────────────────────────────
-# COPY the repo (filtered by .dockerignore) and install from it, so the image
-# always matches the exact commit/tag being built.
+# ── Install baize-core from the npm package ─────────────────────────────────
+# The image pulls the published @baize-ai/core package (no source code in the
+# build context) — source stays private, the image matches the npm version
+# exactly. Build with: docker build --build-arg BAZE_CORE_VERSION=0.2.0 .
+ARG BAZE_CORE_VERSION=latest
 WORKDIR /home/baize
-COPY --chown=baize:baize . /tmp/baize-core
-RUN npm install -g --install-links /tmp/baize-core \
-    && rm -rf /tmp/baize-core \
-    && baize --version
+RUN npm install -g @baize-ai/core@${BAZE_CORE_VERSION} \
+    && baize --version \
+    # ── Build-time skill dependency preinstall (reproducibility) ─────────
+    # `baize init` reinstalls skill deps at runtime; doing it here bakes the
+    # native modules (better-sqlite3 etc.) into the image with a known-good
+    # result and the toolchain above as fallback. Same selection logic as
+    # init.js installSkillDependencies (skills with a package.json that has
+    # dependencies).
+    && for skill_dir in /home/baize/.npm-global/lib/node_modules/@baize-ai/core/skills/*/; do \
+         if [ -f "${skill_dir}package.json" ]; then \
+           deps=$(node -e "const p=require('${skill_dir}package.json');console.log(p.dependencies?1:0)" 2>/dev/null || echo 0); \
+           if [ "$deps" = "1" ]; then \
+             (cd "$skill_dir" && npm install --production --no-audit --no-fund) || exit 1; \
+           fi; \
+         fi; \
+       done \
+    # ── Force local native-module compilation ──────────────────────────
+    # better-sqlite3 12.x prebuild download can return the WRONG platform
+    # binary (observed: macOS Mach-O inside linux build → ERR_DLOPEN_FAILED
+    # at runtime). Rebuild forces node-gyp compile with the toolchain above,
+    # guaranteeing a correct linux ELF regardless of prebuild availability.
+    && for skill_dir in /home/baize/.npm-global/lib/node_modules/@baize-ai/core/skills/*/; do \
+         if [ -d "${skill_dir}node_modules/better-sqlite3" ]; then \
+           (cd "${skill_dir}node_modules/better-sqlite3" && npm rebuild better-sqlite3) || exit 1; \
+         fi; \
+       done \
+    # ── Bake deps into the runtime skills dir ──────────────────────────
+    # init's skill sync preserves existing node_modules and (since the
+    # idempotent-dep check) skips reinstall when deps are loadable — so
+    # pre-baking here makes runtime init never touch the compiled binaries.
+    && mkdir -p /home/baize/baize/.claude/skills \
+    && for skill_dir in /home/baize/.npm-global/lib/node_modules/@baize-ai/core/skills/*/; do \
+         name=$(basename "$skill_dir"); \
+         if [ -d "$skill_dir" ] && [ -f "$skill_dir/package.json" ]; then \
+           mkdir -p "/home/baize/baize/.claude/skills/$name"; \
+           cp -r "$skill_dir"/. "/home/baize/baize/.claude/skills/$name/"; \
+         fi; \
+       done \
+    && node -e "const D=require('/home/baize/baize/.claude/skills/web-console/node_modules/better-sqlite3'); new D(':memory:')" \
+    && echo "native modules OK (locally compiled, baked into runtime skills)"
 
 # ── Workspace directories ─────────────────────────────────────────────────────
 # ~/baize is mounted as a single volume in docker-compose.yml.

package/README.md

@@ -20,7 +20,7 @@ subscription (or an OpenAI Codex setup — Codex CLI v0.129.0+ required,
 0.146+ recommended).
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/baize-ai/baize-core/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/baize01-ai/baize-core/main/scripts/install.sh | bash
 ```
 
 This installs dependencies (git, tmux, Node.js, PM2, the `baize` CLI) and runs
@@ -36,17 +36,26 @@ baize init
 **Docker deployment:**
 
 ```bash
+# Global (GitHub Container Registry)
 docker run -d --name baize \
   -p 3456:3456 \
   -v baize-data:/home/baize/baize \
   -v claude-config:/home/baize/.claude \
-  ghcr.io/baize-ai/baize-core:latest
+  ghcr.io/baize01-ai/baize-core:latest
+
+# China (Aliyun ACR — fast, no mirror needed)
+docker run -d --name baize \
+  -p 3456:3456 \
+  -v baize-data:/home/baize/baize \
+  -v claude-config:/home/baize/.claude \
+  crpi-8bg62qbrjs3cr3as.cn-hangzhou.personal.cr.aliyuncs.com/baize01/baize-core:latest
 ```
 
-Open `http://localhost:3456` for the web console (see below); configure
-authentication in 模型设置 (Claude API key / setup token / custom endpoint /
-Codex / ChatGPT login). See `docs/docker.md` for Compose setup, optional auth
-environment variables, and volume details.
+The image is built from the published `@baize-ai/core` npm package — no source
+code in the build. Open `http://localhost:3456` for the web console (see
+below); configure authentication in 模型设置 (Claude API key / setup token /
+custom endpoint / Codex / ChatGPT login). See `docs/docker.md` for Compose
+setup, optional auth environment variables, and volume details.
 
 `baize init` is idempotent and supports interactive and non-interactive modes.
 It will:
@@ -181,6 +190,72 @@ session, audit trail, and memory.
 
 ---
 
+## A2A (Agent-to-Agent Collaboration)
+
+A2A connects multiple Baize instances for direct, **HTTPS P2P** collaboration —
+no central message server. Messages and task delegations travel straight from
+one agent to another, and every instance stays fully independent.
+
+**Components:**
+
+| Component | Role |
+|-----------|------|
+| `@baize-ai/baize-a2a` | npm channel package installed on each enabled instance: HTTPS server, registration/heartbeat client, task worker, and the `baize a2a` CLI |
+| `@baize-ai/baize-admin-workspace` | Standalone control plane (npm package + Docker image + Ant Design Pro console): admission approval, online status, audit, and Card-based discovery — never in the message path |
+
+**Core concepts:**
+
+- **Agent Card is the single source of business truth** — each agent
+  self-reports its `name`, `description`, and `skills` at
+  `GET /.well-known/baize-agent.json`. The admin does not maintain business
+  descriptions; it only governs admission, presence, audit, and discovery.
+- **Receiver-side authorization** — every agent decides for itself who may
+  call it (`authz` in `config.json`: `open` by default, or an `allowlist`).
+- **Card-based discovery** — peers are found through the admin directory by
+  text-matching the Card's name/description/skills, or by exact skill id.
+
+**Quick start:**
+
+```bash
+baize add @baize-ai/baize-a2a              # install the channel
+baize a2a enable --admin <url> --advertise <https://your-agent.example.com>
+# → self-register → admin approves → JWT issued → heartbeat (30s) → discoverable
+baize a2a search <query>                   # discover agents via the admin directory
+baize a2a task <peer> <skill> "<instruction>"  # delegate a task (sync wait)
+```
+
+**CLI (`baize a2a`):**
+
+| Command | Purpose |
+|---------|---------|
+| `status` | Local state: enabled / agent_id / registration / advertise_url |
+| `enable --admin <url> --advertise <url>` | Enable A2A and register with the admin |
+| `disable` | Disable (already-accepted tasks keep running) |
+| `peer list` | Cached peers |
+| `search <query>` | Discover agents via the admin directory |
+| `card <id>` | Agent Card details |
+| `session-summary` | Summary of the currently available peers |
+| `send <peer> <text>` | Plain message (no reply wait) |
+| `task <peer> <skill> "<instruction>"` | Delegate a task; sync wait by default (`--async` returns the task_id only) |
+| `task status <id>` / `task cancel <id>` | Query / cancel a delegated task |
+
+**Card editing and call authorization (web console):** the A2A page edits
+your Agent Card — name, description, and Skills picked from the installed
+SKILL.md list (frontmatter auto-extracted). Saving hot-refreshes the Card
+within seconds and the admin probe syncs the snapshot; the Card can be
+pre-filled even before A2A is enabled. The same page configures 调用授权
+(call authorization): `open` with a block list (default) or `allowlist` —
+rejected calls return 403 and are audited.
+
+**Credential rotation:** each agent holds its own admin-issued JWT (RS256,
+12h validity, per-agent credentials). Agents auto-refresh before expiry and
+re-fetch credentials within 60s after an admin rotation (revocation
+detection + forced recovery). Rotation revokes only the target agent's
+credential and re-signs it with the current key — the global signing key
+stays unchanged, so rotating one agent never affects the others.
+
+---
+
 ## Configuration
 
 Persistent configuration lives in `~/baize/.baize/config.json`:
@@ -243,6 +318,10 @@ baize uninstall --self        # Uninstall Baize entirely
 
 ---
 
+## Release
+
+npm + Docker 发布的完整操作手册（认证 / 四包发布 / ghcr + 阿里云 ACR 镜像）见 [`docs/release.md`](docs/release.md)。
+
 ## License
 
 [MIT](./LICENSE)

package/README.zh-CN.md

@@ -14,7 +14,7 @@ Baize（白泽）是一个本地软件研发 Agent 工作台：一个自托管
 **前置条件：** Linux 服务器（或 macOS）、[Claude](https://claude.ai) 订阅（或 OpenAI Codex 环境——Codex CLI v0.129.0+，推荐 0.146+）。
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/baize-ai/baize-core/main/scripts/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/baize01-ai/baize-core/main/scripts/install.sh | bash
 ```
 
 安装依赖（git、tmux、Node.js、PM2、`baize` CLI）并运行 `baize init` 初始化 Agent。
@@ -29,14 +29,22 @@ baize init
 **Docker 部署：**
 
 ```bash
+# 海外（GitHub Container Registry）
 docker run -d --name baize \
   -p 3456:3456 \
   -v baize-data:/home/baize/baize \
   -v claude-config:/home/baize/.claude \
-  ghcr.io/baize-ai/baize-core:latest
+  ghcr.io/baize01-ai/baize-core:latest
+
+# 国内（阿里云 ACR，免镜像加速）
+docker run -d --name baize \
+  -p 3456:3456 \
+  -v baize-data:/home/baize/baize \
+  -v claude-config:/home/baize/.claude \
+  crpi-8bg62qbrjs3cr3as.cn-hangzhou.personal.cr.aliyuncs.com/baize01/baize-core:latest
 ```
 
-打开 `http://localhost:3456` 进入网页控制台（见下文）；认证在「模型设置」中配置（Claude API key / setup token / 自定义端点 / Codex / ChatGPT 登录）。Compose 配置、可选认证环境变量与卷说明见 `docs/docker.md`。
+镜像由已发布的 `@baize-ai/core` npm 包构建（构建上下文不含源码）。打开 `http://localhost:3456` 进入网页控制台（见下文）；认证在「模型设置」中配置（Claude API key / setup token / 自定义端点 / Codex / ChatGPT 登录）。Compose 配置、可选认证环境变量与卷说明见 `docs/docker.md`。
 
 `baize init` 幂等，支持交互与非交互模式，它会：
 
@@ -147,6 +155,54 @@ baize search                        # 从当前源动态发现渠道目录
 
 ---
 
+## A2A（Agent-to-Agent 协作）
+
+A2A 让多个 Baize 实例经 **HTTPS P2P** 直接协作——没有中心消息服务器，消息与任务委托直达对端 Agent，每个实例保持完全独立。
+
+**组件：**
+
+| 组件 | 职责 |
+|------|------|
+| `@baize-ai/baize-a2a` | npm 渠道包，装在每个启用实例：HTTPS server、注册/心跳客户端、任务 worker、`baize a2a` CLI |
+| `@baize-ai/baize-admin-workspace` | 独立控制面（npm 包 + Docker 镜像 + Ant Design Pro 控制台）：准入审批、在线状态、审计、基于 Card 的发现——不进消息路径 |
+
+**核心概念：**
+
+- **Agent Card 是唯一业务事实源** —— 每个 agent 在 `GET /.well-known/baize-agent.json` 自报 `name` / `description` / `skills`；admin 不维护业务描述，只管准入、在线、审计与发现。
+- **接收方授权自治** —— 每个 agent 自己决定接受谁的调用（`config.json` 的 `authz`：默认 `open`，或 `allowlist`）。
+- **基于 Card 的发现** —— 经 admin 目录按 Card 的 name/description/skills 文本匹配，或按 skill id 精确匹配发现 peer。
+
+**快速上手：**
+
+```bash
+baize add @baize-ai/baize-a2a              # 安装渠道
+baize a2a enable --admin <url> --advertise <https://your-agent.example.com>
+# → 自注册 → 管理员审批 → 签发 JWT → 心跳（30s）→ 可发现
+baize a2a search <query>                   # 经 admin 目录发现 agent
+baize a2a task <peer> <skill> "<instruction>"  # 委托任务（默认同步等待）
+```
+
+**CLI（`baize a2a`）：**
+
+| 命令 | 用途 |
+|------|------|
+| `status` | 本实例状态：enabled / agent_id / 注册状态 / advertise_url |
+| `enable --admin <url> --advertise <url>` | 启用 A2A 并向 admin 注册 |
+| `disable` | 关闭（已接受任务继续执行） |
+| `peer list` | 本地缓存 peer |
+| `search <query>` | 经 admin 目录发现 agent |
+| `card <id>` | Agent Card 详情 |
+| `session-summary` | 当前可用 peer 摘要 |
+| `send <peer> <text>` | 普通消息（不等待回复） |
+| `task <peer> <skill> "<instruction>"` | 委托任务；默认同步等待终态（`--async` 只拿 task_id） |
+| `task status <id>` / `task cancel <id>` | 查询 / 取消委托任务 |
+
+**名片编辑与调用授权（网页控制台）：** A2A 页可编辑本实例 Agent Card——名称、描述，以及从已安装 SKILL.md 列表勾选 Skills（frontmatter 自动提取）。保存后 Card 秒级热更新，admin 探测同步快照；A2A 未启用也可先编辑预填名片。同页配置「调用授权」：默认 `open` + 黑名单，或 `allowlist`——被拒调用返回 403 并记审计。
+
+**凭证轮换：** 每个 agent 持有 admin 签发的独立 JWT（RS256，12h 有效，凭证独立）。agent 在过期前自动刷新；admin 轮换后 agent 60s 内自动重取凭证（吊销检测 + 强制恢复）。轮换只吊销目标 agent 的凭证并以当前 key 重签——全局签名 key 不变，单 agent 轮换不影响其他 agent。
+
+---
+
 ## 配置
 
 持久化配置在 `~/baize/.baize/config.json`：
@@ -203,6 +259,10 @@ baize uninstall --self        # 完全卸载 Baize
 
 ---
 
+## Release
+
+npm + Docker 发布的完整操作手册（认证 / 四包发布 / ghcr + 阿里云 ACR 镜像）见 [`docs/release.md`](docs/release.md)。
+
 ## License
 
 [MIT](./LICENSE)

package/cli/baize.js

@@ -22,6 +22,7 @@ import { attachCommand } from './commands/attach.js';
 import { doctorCommand } from './commands/doctor.js';
 import { shellCommand } from './commands/shell.js';
 import { runtimeCommand } from './commands/runtime.js';
+import { a2aCommand } from './commands/a2a.js';
 
 const commands = {
   // Environment setup
@@ -45,6 +46,8 @@ const commands = {
   remove: uninstallComponent,
   list: listComponents,
   search: searchComponents,
+  // A2A (Agent-to-Agent)
+  a2a: a2aCommand,
   // Help
   help: showHelp,
 };
@@ -120,6 +123,9 @@ Component Management:
   list                List installed components
   search [keyword]    Search available components
 
+A2A:
+  a2a                 A2A 智能体互联管理（baize a2a --help 查看子命令）
+
 Other:
   help                Show this help
 

package/cli/commands/a2a.js

@@ -0,0 +1,124 @@
+/**
+ * baize a2a — A2A（Agent-to-Agent）互联管理。
+ *
+ * 全部子命令委托 @baize-ai/baize-a2a 的 scripts/cli.js（D19 契约 §6）：
+ * 参数透传 + --json，成功 exit 0，失败 stderr + exit 1。
+ *
+ * Usage:
+ *   baize a2a status
+ *   baize a2a enable --admin <url> --advertise <url>
+ *   baize a2a disable
+ *   baize a2a peer list
+ *   baize a2a search <query>
+ *   baize a2a send <peer> <text>
+ *   baize a2a task <peer> <skill?> <instruction> [--async]
+ *   baize a2a task status <taskId>
+ *   baize a2a task cancel <taskId>
+ */
+
+import { a2aCliPath, runA2aCli, formatA2aOutput } from '../lib/a2a.js';
+import { bold, dim, cyan, error } from '../lib/colors.js';
+
+export const A2A_SUBCOMMANDS = ['status', 'enable', 'disable', 'peer', 'search', 'send', 'task'];
+
+// Contract: sync task waits for a terminal state (timeout 10 min).
+const TASK_TIMEOUT_MS = 660000;
+const DEFAULT_TIMEOUT_MS = 120000;
+
+export function a2aHelp() {
+  return `${bold('baize a2a')} — A2A（Agent-to-Agent）互联管理
+
+委托 @baize-ai/baize-a2a 通道 CLI（定位：BAIZE_A2A_PATH → 全局 npm 包 → ../baize-a2a 开发目录）。
+
+Usage: ${bold('baize a2a <subcommand> [options]')}
+
+Subcommands:
+  ${cyan('status')}                           A2A 身份与注册状态
+  ${cyan('enable')} --admin <url> --advertise <url>
+                              启用并注册：生成 agentId + 向 admin-workspace 提交注册
+  ${cyan('disable')}                          停用（停止心跳/消息接收）
+  ${cyan('peer list')}                        peer 目录（已缓存）
+  ${cyan('search')} <query>                  在 admin Directory 中搜索 agent
+  ${cyan('send')} <peer> <text>              发送一条消息给 peer
+  ${cyan('task')} <peer> <skill?> <instruction> [--async]
+                              派发任务；默认同步等待终态（超时 10 分钟），
+                              ${dim('--async')} 立即返回 taskId
+  ${cyan('task status')} <taskId>            查询任务状态
+  ${cyan('task cancel')} <taskId>            取消任务（queued → canceled；running → cancel_requested）
+
+Options:
+  --help, -h          显示帮助
+  --json              原始 JSON 输出（透传给 baize-a2a CLI）
+
+Examples:
+  baize a2a status
+  baize a2a enable --admin https://admin.example.com --advertise https://a2a.example.com
+  baize a2a peer list
+  baize a2a search doccraft
+  baize a2a send agent_doccraft "帮我生成一份周报"
+  baize a2a task agent_doccraft "生成周报" --async
+  baize a2a task status <taskId>`;
+}
+
+function commandKind(args) {
+  const [sub, sub2] = args;
+  if (sub === 'task') {
+    if (sub2 === 'status') return 'task-status';
+    if (sub2 === 'cancel') return 'task-cancel';
+    return 'task';
+  }
+  if (sub === 'peer') return 'peer-list';
+  return sub;
+}
+
+/**
+ * Entry point for `baize a2a ...`.
+ *
+ * @param {string[]} args CLI args after "a2a"
+ * @param {object} [deps] injectable seams for tests
+ * @param {Function} [deps.runA2aCli] delegated runner (defaults to runA2aCli)
+ * @param {string|Function} [deps.cliPath] cli.js path override (defaults to a2aCliPath())
+ * @param {Function} [deps.exit] process.exit stand-in
+ * @param {Function} [deps.log] stdout writer
+ * @param {Function} [deps.logError] stderr writer
+ */
+export async function a2aCommand(args = [], deps = {}) {
+  const run = deps.runA2aCli || runA2aCli;
+  const exit = deps.exit || ((code) => { process.exit(code); });
+  const log = deps.log || ((s) => console.log(s));
+  const logError = deps.logError || ((s) => console.error(s));
+
+  const first = args[0] || '';
+  if (!first || first === '--help' || first === '-h') {
+    log(a2aHelp());
+    return;
+  }
+  if (!A2A_SUBCOMMANDS.includes(first)) {
+    logError(error(`Unknown a2a subcommand: ${first}`));
+    logError('Usage: baize a2a <subcommand> [options]  （baize a2a --help 查看全部子命令）');
+    return exit(1);
+  }
+
+  const cli = typeof deps.cliPath === 'function' ? deps.cliPath() : (deps.cliPath !== undefined ? deps.cliPath : a2aCliPath());
+  if (!cli) {
+    logError(error('未找到 baize-a2a CLI。请设置 BAIZE_A2A_PATH，安装 @baize-ai/baize-a2a（npm i -g），或确认 ../baize-a2a 开发目录存在。'));
+    return exit(1);
+  }
+
+  // Sync task dispatch waits for a terminal state (contract §6, 10 min).
+  const isTaskSync = first === 'task'
+    && args[1] !== 'status'
+    && args[1] !== 'cancel'
+    && !args.includes('--async');
+  const timeout = isTaskSync ? TASK_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+
+  const result = await run(args, { cliPath: cli, timeout });
+  if (!result.success) {
+    logError(error(result.error || 'a2a 命令失败'));
+    if (result.output && result.output !== result.error) logError(result.output.slice(-800));
+    return exit(1);
+  }
+
+  const json = result.json || {};
+  log(formatA2aOutput(commandKind(args), json));
+}