@baize-ai/core 0.3.14 → 0.3.16

package/scripts/pack-release.sh

@@ -11,7 +11,7 @@
 #                                     兼容 web 控制台上传与 `baize add --file` 两种安装）
 #   baize-admin-workspace-<v>.tgz     admin 套件源码：server 源码 + admin-ui 构建产物 +
 #                                     Dockerfile + 部署说明（自建镜像 / 自托管用）
-#   baize-admin-workspace-<v>.tar     docker save 的 admin 镜像（docker load 直接运行，推荐）
+#   baize-admin-workspace-<v>.tar     （可选）docker save 的 admin 镜像——仅 BUILD_ADMIN_DOCKER=1 打包时产出
 #   INSTALL.md                        客户侧安装说明（上传 / --file 安装 + 切集群 + admin 部署）
 #
 # 用法：
@@ -155,8 +155,14 @@ build_admin_tgz() {
   log "    → ${out} ($(size "${out}"))"
 }
 
-# ── 3. Admin Docker 镜像（docker save）──────────────────────────────────────
+# ── 3. Admin Docker 镜像（docker save）——可选 ─────────────────────────────
+# 商业版 admin 默认源码交付（tgz 含 server + 已构建 admin-ui/dist）。
+# 仅当 BUILD_ADMIN_DOCKER=1 时才导出 docker save 镜像（需先构建 baize-admin-workspace:test）。
 save_admin_image() {
+  if [ "${BUILD_ADMIN_DOCKER:-0}" != "1" ]; then
+    step "跳过 admin Docker 镜像导出（源码交付模式；需要时 BUILD_ADMIN_DOCKER=1 重跑）"
+    return 0
+  fi
   step "导出 admin Docker 镜像"
   local image="baize-admin-workspace:test"
   if ! docker image inspect "${image}" >/dev/null 2>&1; then
@@ -231,36 +237,35 @@ baize a2a status    # 期望：集群·在线
 ```bash
 baize a2a disable    # 停 daemon，保留配置与注册数据，模式回 standalone
 ```
+### 方式 A：源码部署（推荐——商业版默认交付形态）
 
-## 三、部署 Admin（控制面）
-
-### 方式 A：Docker 镜像（推荐）
+套件已含 server 源码与**构建好的** `admin-ui/dist`，无需前端构建：
 
 ```bash
-docker load -i baize-admin-workspace-__VERSION__.tar
-docker run -d --name baize-admin -p 8080:8080 \
-  -v baize-admin-data:/data \
-  -e BAIZE_ADMIN_TOKEN='<初始口令>' \
-  baize-admin-workspace:test
+tar xzf baize-admin-workspace-__VERSION__.tgz
+cd baize-admin-workspace-__VERSION__
+npm ci --omit=dev                                 # Node ≥ 20.11
+BAIZE_ADMIN_TOKEN='<初始口令>' BAIZE_ADMIN_DIR=/srv/baize-admin \
+  pm2 start server/src/index.js --name baize-admin  # 或 nohup node server/src/index.js
 ```
 
-- 访问 `http://<主机>:8080`，首次登录：`admin` + 初始口令（日志打印或 `BAIZE_ADMIN_TOKEN`）；
-- 登录后立即修改口令；数据全部落在 `/data` 卷（SQLite 库与签名密钥），务必持久化；
-- 公网部署建议放在 HTTPS 反代后面，`baize a2a enable --admin` 使用对外 HTTPS 地址。
+- API 监听 8080；`BAIZE_ADMIN_DIR` 是数据目录（SQLite/CA/签名钥），必须持久化并提前建目录；
+- 前端 `admin-ui/dist` 是静态产物：用 nginx/Caddy 反代到与 API 同源的根路径；
+- 公网部署必须 `TRUST_PROXY=1`（信任反代 X-Forwarded-For，否则限流按代理 IP 计数）；
+- 首次登录 `admin` + 初始口令（日志打印），登录后到「设置」改口令。
 
-### 方式 B：源码套件（自建镜像 / 自托管）
+### 方式 B：Docker（可选——需自建镜像）
 
 ```bash
-tar xzf baize-admin-workspace-__VERSION__.tgz
-cd baize-admin-workspace-__VERSION__
 docker build -t baize-admin-workspace .          # 多阶段：node:22 构建 admin-ui → node:22-slim 运行
-docker run -d --name baize-admin -p 8080:8080 -v baize-admin-data:/data baize-admin-workspace
+docker run -d --name baize-admin -p 8080:8080 \
+  -v baize-admin-data:/data -e BAIZE_ADMIN_TOKEN='<初始口令>' baize-admin-workspace
 ```
 
-- 本地运行：`npm ci && npm start`（Node ≥ 20.11，默认 8080）；
-- 前端构建产物已含在 `admin-ui/dist`（容器内 `/app/dist`），可与 API 同源静态提供。
+> 厂商如需分发 Docker 镜像 tar：打包时 `BUILD_ADMIN_DOCKER=1 ./scripts/pack-release.sh`（本默认交付不包含 tar）。
 
-## 四、卸载
+- 前端构建产物已含在 `admin-ui/dist`，与 API 同源静态提供（nginx/Caddy 指到该目录即可）。
+- API 默认 8080（`PORT` 可改）；本地直跑：`BAIZE_ADMIN_DIR=/srv/baize-admin npm start`。
 
 ```bash
 baize a2a disable          # 先切回单机 / 停服务
@@ -332,13 +337,16 @@ verify() {
     echo "  !! ${admin_tgz} 校验失败（解压或 manifest 不正确）" >&2
     rc=1
   fi
-
-  # docker save 产物：存在且非空
-  if [ -s "${admin_tar}" ]; then
-    log "  OK  ${admin_tar} ($(size "${admin_tar}"))  存在且非空"
+  # docker save 产物：可选（BUILD_ADMIN_DOCKER=1 打包时才存在）
+  if [ -e "${admin_tar}" ] || [ "${BUILD_ADMIN_DOCKER:-0}" = "1" ]; then
+    if [ -s "${admin_tar}" ]; then
+      log "  OK  ${admin_tar} ($(size "${admin_tar}"))  存在且非空"
+    else
+      echo "  !! ${admin_tar} 不存在或为空" >&2
+      rc=1
+    fi
   else
-    echo "  !! ${admin_tar} 不存在或为空" >&2
-    rc=1
+    log "  --  ${admin_tar##*/} 未打包（源码交付模式，BUILD_ADMIN_DOCKER=1 可启用）"
   fi
 
   [ -f "${DIST_DIR}/INSTALL.md" ] && log "  OK  ${DIST_DIR}/INSTALL.md ($(size "${DIST_DIR}/INSTALL.md"))"

package/skills/web-console/public/app.js

@@ -1170,7 +1170,18 @@ async function loadProviders(basePath) {
     const names = { official: 'Anthropic 官方', 'official-openai': 'OpenAI 官方' };
     const prov = (body.providers || []).find((x) => x.id === body.active);
     const label = prov?.name || names[body.active] || body.active || 'official';
-    activeEl.textContent = `当前激活：${label}`;
+    const codexSlug = body.codexProviderKey || prov?.codex?.providerKey || null;
+    const codexKind = prov?.codex?.kind || null;
+    // D51 review P3: surface the kind so openai-official (no block) vs
+    // responses-compatible (provider block) are distinguishable at a glance.
+    const codexTag = codexKind === 'responses-compatible' && codexSlug
+      ? `（codex: ${codexSlug} · responses）`
+      : codexKind === 'openai-official'
+        ? '（codex: OpenAI 官方）'
+        : codexSlug
+          ? `（codex: ${codexSlug}）`
+          : '';
+    activeEl.textContent = `当前激活：${label}${codexTag}`;
   }
   const list = document.getElementById('provider-list');
   if (!list) return;
@@ -1249,7 +1260,8 @@ async function activateProviderFromAdmin(basePath, id) {
     const restartNote = body.restart?.restarted ? '，会话已重启' : (body.restart?.reason === 'no_session' ? '（无运行中会话）' : '');
     const warnNote = body.warnings?.length ? `
 警告：${body.warnings.join('\n')}` : '';
-    setAdminMsg(`已激活 ${body.active}${restartNote}${warnNote}`);
+    const slugNote = body.codexProviderKey ? `（codex: ${body.codexProviderKey}）` : '';
+    setAdminMsg(`已激活 ${body.active}${slugNote}${restartNote}${warnNote}`);
   } else {
     setAdminMsg(`激活失败：${body.error || '未知错误'}`, true);
   }
@@ -1719,10 +1731,10 @@ function updateA2aInstallArea(body) {
   if (!el || !fileInput || !btn) return;
   const version = body && (body.version || body.installedVersion);
   if (version) {
-    el.textContent = `已安装 baize-a2a v${String(version).replace(/^v/, '')}。如需升级请重新上传模块包。`;
+    el.textContent = `已安装 baize-a2a v${String(version).replace(/^v/, '')} — 上传更高版本的模块包（.tgz）可在线升级（相同或更低版本将被拒绝）。`;
     if (state) { state.textContent = '已安装'; state.className = 'channel-state ok'; }
-    fileInput.disabled = true;
-    btn.disabled = true;
+    fileInput.disabled = false;
+    btn.disabled = false;
   } else {
     el.textContent = '未安装 — 上传 baize-a2a 模块包（.tgz）完成安装。';
     if (state) { state.textContent = '未安装'; state.className = 'channel-state warn'; }
@@ -1782,11 +1794,16 @@ function updateA2aHealth(body, peerCountOverride) {
   } else if (_lastA2aPeerCount !== null) {
     peerCount = _lastA2aPeerCount;
   }
+  const bs = body && body.bootstrap ? body.bootstrap : null;
+  const bsLabel = !bs ? '' : (bs.status === 'ok' || bs.status === 'launched'
+    ? `启动中/已启动（${escapeHtml(String(bs.via || bs.status))}）`
+    : `失败：${escapeHtml(String(bs.error || bs.status))}`);
   const rows = [
     ['Daemon 健康', healthy ? '✅ 正常' : '❌ 异常'],
     ['运行模式', modeLabel],
     ['Peer 数', peerCount],
     ['最近心跳', a2aHeartbeatLabel(body)],
+    ...(bsLabel ? [['init 自启动', bsLabel]] : []),
   ].filter(([, v]) => v !== undefined && v !== null && v !== '');
   el.innerHTML = rows.map(([k, v]) => `<div class="conn-summary-row"><span class="conn-summary-name">${escapeHtml(k)}</span><span class="conn-summary-detail">${escapeHtml(String(v))}</span></div>`).join('');
   if (state) {
@@ -1858,13 +1875,11 @@ async function openAgentCardEditor(basePath) {
   let catalogue;
   let card;
   let authz;
-  let peerIds;
   try {
-    const [catRes, cardRes, authzRes, peersRes] = await Promise.all([
+    const [catRes, cardRes, authzRes] = await Promise.all([
       adminFetch(basePath, '/api/admin/a2a/card/skills'),
       adminFetch(basePath, '/api/admin/a2a/card'),
       adminFetch(basePath, '/api/admin/a2a/authz'),
-      adminFetch(basePath, '/api/admin/a2a/peers'),
     ]);
     if (catRes.status !== 200) throw new Error(catRes.body.error || 'skills 列表加载失败');
     if (cardRes.status !== 200) throw new Error(cardRes.body.error || '名片加载失败');
@@ -1872,9 +1887,6 @@ async function openAgentCardEditor(basePath) {
     catalogue = catRes.body.skills || [];
     card = cardRes.body;
     authz = authzRes.body;
-    peerIds = peersRes.status === 200 && Array.isArray(peersRes.body.peers)
-      ? peersRes.body.peers.map((p) => p.agentId).filter(Boolean)
-      : [];
   } catch (err) {
     setAdminMsg(`❌ 无法打开名片编辑器：${err.message}`, true);
     return;
@@ -1912,14 +1924,7 @@ async function openAgentCardEditor(basePath) {
             <label class="authz-mode-option"><input type="radio" name="authz-mode" value="allowlist"> 白名单</label>
           </div>
           <p class="conn-block-desc" id="authz-mode-desc"></p>
-          <div class="agent-card-field-label"><span id="authz-list-title">阻止列表</span> <span class="agent-card-selected-count" id="authz-count"></span></div>
-          <div class="authz-tags" id="authz-tags" aria-live="polite"></div>
-          <div class="authz-add-row">
-            <input type="text" id="authz-peer-input" class="agent-card-input" placeholder="输入 peer agent_id 后添加" autocomplete="off" spellcheck="false">
-            <button type="button" class="btn btn-outline" id="authz-peer-add">添加</button>
-          </div>
-          <div class="agent-card-field-label">从 peer 列表选择</div>
-          <select id="authz-peer-select" class="agent-card-input" aria-label="从 peer 列表选择"></select>
+          <p class="conn-block-desc" style="color:#8c8c8c">允许 / 阻止名单由 admin 控制台统一管控（组织架构 · 调用白名单），此处仅切换本 agent 的授权模式。</p>
         </div>
       </div>
       <div class="agent-card-modal-foot">
@@ -1938,18 +1943,10 @@ async function openAgentCardEditor(basePath) {
   nameInput.value = card.name || '';
   descInput.value = card.description || '';
 
-  // ── 调用授权 tab state (D22 单元 C) ──
-  const allowSet = new Set(Array.isArray(authz.allow) ? authz.allow : []);
-  const blockSet = new Set(Array.isArray(authz.block) ? authz.block : []);
+  // ── 调用授权 tab state (D52: local mode only; lists are admin-managed) ──
   let authzMode = authz.mode === 'allowlist' ? 'allowlist' : 'open';
-  const activeAuthzList = () => (authzMode === 'allowlist' ? allowSet : blockSet);
 
   const authzModeDesc = overlay.querySelector('#authz-mode-desc');
-  const authzListTitle = overlay.querySelector('#authz-list-title');
-  const authzCount = overlay.querySelector('#authz-count');
-  const authzTagsEl = overlay.querySelector('#authz-tags');
-  const authzPeerInput = overlay.querySelector('#authz-peer-input');
-  const authzPeerSelect = overlay.querySelector('#authz-peer-select');
 
   const renderAuthz = () => {
     overlay.querySelectorAll('input[name="authz-mode"]').forEach((r) => {
@@ -1957,19 +1954,8 @@ async function openAgentCardEditor(basePath) {
     });
     const isAllowlist = authzMode === 'allowlist';
     authzModeDesc.textContent = isAllowlist
-      ? '仅允许列表中的 agent 可以调用本 agent（空列表 = 无人可调用）。'
-      : '接受所有已批准 agent，除阻止列表中的 agent。';
-    authzListTitle.textContent = isAllowlist ? '允许列表' : '阻止列表';
-    const list = [...activeAuthzList()];
-    authzCount.textContent = `${list.length} 个`;
-    authzTagsEl.innerHTML = list.length
-      ? list.map((id) => `<span class="authz-tag">${escapeHtml(id)}<button type="button" class="authz-tag-x" aria-label="移除 ${escapeHtml(id)}" data-id="${escapeHtml(id)}">×</button></span>`).join('')
-      : '<span class="cred-state">（空）</span>';
-    const current = new Set(activeAuthzList());
-    const available = peerIds.filter((id) => !current.has(id));
-    authzPeerSelect.innerHTML = `<option value="">${available.length ? '选择 peer 添加到列表…' : '列表已包含所有已知 peer'}</option>`
-      + available.map((id) => `<option value="${escapeHtml(id)}">${escapeHtml(id)}</option>`).join('');
-    authzPeerSelect.disabled = available.length === 0;
+      ? '仅允许白名单中的 agent 调用本 agent（白名单由 admin 控制台配置；空名单 = 无人可调用）。'
+      : '接受所有已批准 agent（除 admin 控制台配置的阻止名单）。';
   };
 
   overlay.querySelectorAll('input[name="authz-mode"]').forEach((r) => {
@@ -1981,42 +1967,6 @@ async function openAgentCardEditor(basePath) {
     });
   });
 
-  const addAuthzPeer = () => {
-    const value = authzPeerInput.value.trim();
-    if (!value) {
-      setAdminMsg('请输入 peer agent_id', true);
-      return;
-    }
-    const list = activeAuthzList();
-    if (list.has(value)) {
-      setAdminMsg(`⚠️ ${value} 已在${authzMode === 'allowlist' ? '允许' : '阻止'}列表中`, true);
-      return;
-    }
-    list.add(value);
-    authzPeerInput.value = '';
-    renderAuthz();
-  };
-  authzPeerInput.addEventListener('keydown', (e) => {
-    if (e.key === 'Enter') {
-      e.preventDefault();
-      addAuthzPeer();
-    }
-  });
-  overlay.querySelector('#authz-peer-add').addEventListener('click', addAuthzPeer);
-  authzPeerSelect.addEventListener('change', () => {
-    const value = authzPeerSelect.value;
-    if (!value) return;
-    activeAuthzList().add(value);
-    renderAuthz();
-  });
-  authzTagsEl.addEventListener('click', (e) => {
-    const btn = e.target.closest('.authz-tag-x');
-    if (btn) {
-      activeAuthzList().delete(btn.dataset.id);
-      renderAuthz();
-    }
-  });
-
   // ── Tab switching ──
   const tabButtons = overlay.querySelectorAll('.agent-card-tab');
   const cardTabEl = overlay.querySelector('#agent-card-tab-card');
@@ -2118,7 +2068,7 @@ async function openAgentCardEditor(basePath) {
         adminFetch(basePath, '/api/admin/a2a/authz', {
           method: 'PUT',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ mode: authzMode, allow: [...allowSet], block: [...blockSet] }),
+          body: JSON.stringify({ mode: authzMode }),
         }),
       ]);
       if (cardRes.status === 401 || authzRes.status === 401) {
@@ -2282,7 +2232,7 @@ async function submitA2aInstall(basePath, btn) {
   }
   const original = btn.textContent;
   btn.disabled = true;
-  btn.textContent = '上传安装中...';
+  btn.textContent = '上传处理中...';
   feedback.textContent = '';
   feedback.className = '';
   const fd = new FormData();
@@ -2291,11 +2241,23 @@ async function submitA2aInstall(basePath, btn) {
     const { status, body } = await adminFetch(basePath, '/api/admin/a2a/install', { method: 'POST', body: fd });
     if (body.ok === true || body.success === true) {
       const version = body.version ? ` v${String(body.version).replace(/^v/, '')}` : '';
-      feedback.textContent = `✅ 安装成功${version}`;
+      const verb = body.upgraded ? '升级' : '安装';
+      let okMsg = `✅ ${verb}成功${version}`;
+      if (body.upgraded && body.restarted === false) {
+        okMsg += `（⚠️ daemon 重启失败：${body.restartError || '未知原因'}，请检查状态卡或手动重启）`;
+      }
+      feedback.textContent = okMsg;
       feedback.className = 'a2a-feedback-ok';
       fileInput.value = '';
-      setAdminMsg(`✅ baize-a2a 安装成功${version}`);
-      loadA2aStatus(basePath); // 刷新版本/模式/健康
+      setAdminMsg(`✅ baize-a2a ${verb}成功${version}`);
+      loadA2aStatus(basePath); // 刷新版本/模式/健康/安装卡
+    } else if (body.error === 'version_not_higher') {
+      const local = body.local ? `v${String(body.local).replace(/^v/, '')}` : '未知';
+      const incoming = body.incoming ? `v${String(body.incoming).replace(/^v/, '')}` : '未知';
+      const msg = `上传版本 ${incoming} 不高于已安装版本 ${local}，未执行升级`;
+      feedback.textContent = `❌ 升级被拒绝：${msg}`;
+      feedback.className = 'a2a-feedback-error';
+      setAdminMsg(`❌ 升级被拒绝：${msg}`, true);
     } else {
       const msg = body.error || body.message || `HTTP ${status}`;
       feedback.textContent = `❌ 安装失败：${msg}`;

package/skills/web-console/public/index.html

@@ -323,7 +323,7 @@
               <div class="cred-state" id="a2a-install-status" role="status" aria-live="polite">加载中...</div>
               <form id="form-a2a-install" class="settings-form">
                 <input type="file" id="a2a-install-file" accept=".tgz,.tar.gz,.zip" aria-label="选择 baize-a2a 模块包">
-                <button type="submit" class="btn btn-primary" id="btn-a2a-install">上传安装</button>
+                <button type="submit" class="btn btn-primary" id="btn-a2a-install">上传安装/升级</button>
               </form>
               <div class="cred-state" id="a2a-install-feedback" role="status" aria-live="polite"></div>
             </div>

package/skills/web-console/scripts/a2a-admin.js

@@ -362,63 +362,76 @@ function rebuildNativeDeps(cwd) {
 }
 
 /**
- * Install @baize-ai/baize-a2a from an uploaded .tar.gz (D25 私有交付).
- * Pipeline: entry listing + path-safety vetting (no `..`/absolute/links) →
- * manifest check (name = @baize-ai/baize-a2a, version present) → extract to
- * SKILLS_DIR/a2a → npm install --omit=dev → components.json registration.
- * Already installed → { ok:false, error } naming the installed version
- * (mirrors `baize add`; version bumps go through `baize upgrade a2a`).
+ * Shared upload vetting for install/upgrade (D25/D49): extension → size →
+ * entry listing → path-traversal scan → link scan → package manifest.
  *
- * @returns {Promise<{ok:boolean, version?:string, error?:string}>}
+ * @returns {{ error: string } | { pkg: object, entries: string[] }}
  */
-export async function installA2aTarball(tarballPath, {
-  skillsDir = defaultSkillsDir(),
-  componentsFile: componentsPath = componentsFile(),
-  installDeps = npmInstallDeps,
-  rebuildDeps = rebuildNativeDeps,
-  originalName = null,
-} = {}) {
-  const file = String(tarballPath || '');
+function validateA2aTarball(file, originalName) {
   const nameForType = String(originalName || file || '');
   if (!/\.(?:tar\.gz|tgz)$/i.test(nameForType)) {
-    return { ok: false, error: '安装包必须是 .tar.gz 归档' };
+    return { error: '安装包必须是 .tar.gz 归档' };
   }
   let stat;
   try {
     stat = fs.statSync(file);
   } catch {
-    return { ok: false, error: '上传文件不存在或不可读' };
+    return { error: '上传文件不存在或不可读' };
   }
   if (stat.size > A2A_INSTALL_MAX_BYTES) {
-    return { ok: false, error: `文件超过 ${A2A_INSTALL_MAX_MB}MB 限制` };
+    return { error: `文件超过 ${A2A_INSTALL_MAX_MB}MB 限制` };
   }
   let entries;
   try {
     entries = listTarballEntries(file);
   } catch (err) {
-    return { ok: false, error: `无法读取归档: ${err.message}` };
+    return { error: `无法读取归档: ${err.message}` };
   }
-  if (entries.length === 0) return { ok: false, error: '归档为空' };
+  if (entries.length === 0) return { error: '归档为空' };
   const unsafe = entries.find(isUnsafeArchiveEntry);
-  if (unsafe) return { ok: false, error: `归档包含不安全的路径条目: ${unsafe}` };
+  if (unsafe) return { error: `归档包含不安全的路径条目: ${unsafe}` };
   try {
     assertNoArchiveLinks(file);
   } catch (err) {
-    return { ok: false, error: err.message };
+    return { error: err.message };
   }
   let pkg;
   try {
     pkg = readTarballPackageJson(file, entries);
   } catch (err) {
-    return { ok: false, error: `manifest 解析失败: ${err.message}` };
+    return { error: `manifest 解析失败: ${err.message}` };
   }
-  if (!pkg) return { ok: false, error: '归档缺少 package.json' };
+  if (!pkg) return { error: '归档缺少 package.json' };
   if (pkg.name !== A2A_PACKAGE_NAME) {
-    return { ok: false, error: `manifest name 不符: 期望 ${A2A_PACKAGE_NAME}，实际 ${pkg.name}` };
+    return { error: `manifest name 不符: 期望 ${A2A_PACKAGE_NAME}，实际 ${pkg.name}` };
   }
   if (typeof pkg.version !== 'string' || !pkg.version.trim()) {
-    return { ok: false, error: 'manifest 缺少 version' };
+    return { error: 'manifest 缺少 version' };
   }
+  return { pkg, entries };
+}
+
+/**
+ * Install @baize-ai/baize-a2a from an uploaded .tar.gz (D25 私有交付).
+ * Pipeline: entry listing + path-safety vetting (no `..`/absolute/links) →
+ * manifest check (name = @baize-ai/baize-a2a, version present) → extract to
+ * SKILLS_DIR/a2a → npm install --omit=dev → components.json registration.
+ * Already installed → { ok:false, error } naming the installed version
+ * (the web route dispatches to upgradeA2aTarball instead — D49 K3).
+ *
+ * @returns {Promise<{ok:boolean, version?:string, error?:string}>}
+ */
+export async function installA2aTarball(tarballPath, {
+  skillsDir = defaultSkillsDir(),
+  componentsFile: componentsPath = componentsFile(),
+  installDeps = npmInstallDeps,
+  rebuildDeps = rebuildNativeDeps,
+  originalName = null,
+} = {}) {
+  const file = String(tarballPath || '');
+  const verdict = validateA2aTarball(file, originalName);
+  if (verdict.error) return { ok: false, error: verdict.error };
+  const { pkg, entries } = verdict;
   const targetDir = path.join(skillsDir, 'a2a');
   const installed = readComponents(componentsPath).a2a;
   if (fs.existsSync(targetDir) || installed) {
@@ -456,6 +469,175 @@ export async function installA2aTarball(tarballPath, {
   return { ok: true, version: pkg.version };
 }
 
+/** Semver compare (no deps; returns -1|0|1, null when unparseable).
+ * Prerelease ranks below release; prerelease identifiers compared
+ * numerically when numeric, lexically otherwise. */
+export function compareA2aSemver(a, b) {
+  const parse = (v) => String(v || '').trim().replace(/^v/, '')
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return null;
+  for (const i of [1, 2, 3]) {
+    const av = Number(pa[i]);
+    const bv = Number(pb[i]);
+    if (av !== bv) return av < bv ? -1 : 1;
+  }
+  if (pa[4] === pb[4]) return 0;
+  if (!pa[4]) return 1;
+  if (!pb[4]) return -1;
+  const aParts = pa[4].split('.');
+  const bParts = pb[4].split('.');
+  for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+    const av = aParts[i];
+    const bv = bParts[i];
+    if (av === bv) continue;
+    if (av === undefined) return -1;
+    if (bv === undefined) return 1;
+    const an = /^\d+$/.test(av) ? Number(av) : null;
+    const bn = /^\d+$/.test(bv) ? Number(bv) : null;
+    if (an !== null && bn !== null) return an < bn ? -1 : 1;
+    if (an !== null) return -1;
+    if (bn !== null) return 1;
+    return av < bv ? -1 : 1;
+  }
+  return 0;
+}
+
+function readInstalledPkgVersion(skillDir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(skillDir, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Upgrade an installed @baize-ai/baize-a2a from an uploaded .tar.gz
+ * (D49 K3 — web 重传 = 升级). Gate: incoming semver must be strictly higher
+ * than the installed one (components.json version first, skill package.json
+ * fallback); otherwise { ok:false, error:'version_not_higher', local, incoming }.
+ * Pipeline: backup skillDir/.backup/<ts> (upgrade.js .backup convention) →
+ * extract over skillDir → npm install --omit=dev + rebuild (D44) →
+ * components.json version bump → a2a CLI `restart` (covers pm2 AND nohup
+ * daemon lifecycles). Extraction/install/rebuild failure rolls the skill dir
+ * back from the backup; restart failure is reported, not rolled back (the
+ * on-disk upgrade itself succeeded).
+ *
+ * @returns {Promise<{ok:boolean, version?:string, previousVersion?:string,
+ *   upgraded?:boolean, restarted?:boolean, restartError?:string, error?:string}>}
+ */
+export async function upgradeA2aTarball(tarballPath, {
+  skillsDir = defaultSkillsDir(),
+  componentsFile: componentsPath = componentsFile(),
+  installDeps = npmInstallDeps,
+  rebuildDeps = rebuildNativeDeps,
+  restartFn = () => runA2aCli(['restart'], { timeout: 120000 }),
+  originalName = null,
+} = {}) {
+  const file = String(tarballPath || '');
+  const verdict = validateA2aTarball(file, originalName);
+  if (verdict.error) return { ok: false, error: verdict.error };
+  const { pkg, entries } = verdict;
+  const targetDir = path.join(skillsDir, 'a2a');
+  const components = readComponents(componentsPath);
+  if (!fs.existsSync(targetDir) || !components.a2a) {
+    return { ok: false, error: 'a2a 未安装，请先安装' };
+  }
+
+  const localVersion = components.a2a.version || readInstalledPkgVersion(targetDir);
+  const cmp = compareA2aSemver(pkg.version, localVersion);
+  if (cmp === null) {
+    return { ok: false, error: '版本号无法解析，拒绝升级', local: localVersion || null, incoming: pkg.version };
+  }
+  if (cmp <= 0) {
+    return { ok: false, error: 'version_not_higher', local: localVersion || null, incoming: pkg.version };
+  }
+
+  // Backup before any write (mirrors cli/lib/upgrade.js step2_backup).
+  // Copied per top-level entry: cpSync refuses a destination that is a
+  // subdirectory of its source (.backup lives inside the skill dir).
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(targetDir, '.backup', timestamp);
+  try {
+    fs.mkdirSync(backupDir, { recursive: true });
+    for (const entry of fs.readdirSync(targetDir, { withFileTypes: true })) {
+      if (['node_modules', '.backup', '.baize'].includes(entry.name)) continue;
+      fs.cpSync(path.join(targetDir, entry.name), path.join(backupDir, entry.name), { recursive: true });
+    }
+  } catch (err) {
+    return { ok: false, error: `备份失败，升级中止: ${err.message}` };
+  }
+
+  // Rollback: clear everything except the backup itself, then copy the
+  // backup back (top-level .backup inside targetDir must survive the wipe).
+  const restoreBackup = async () => {
+    try {
+      for (const entry of fs.readdirSync(targetDir)) {
+        if (entry !== '.backup') fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
+      }
+      fs.cpSync(backupDir, targetDir, { recursive: true });
+      // Best-effort dependency restore for the rolled-back code (node_modules
+      // was excluded from the backup); failure here is reported, not fatal.
+      await installDeps(targetDir);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  try {
+    extractTarballTo(file, targetDir, entries);
+  } catch (err) {
+    const restored = await restoreBackup();
+    return { ok: false, error: `解压失败（${restored ? '已回滚' : '回滚失败，请检查 .backup'}）: ${err.message}` };
+  }
+  const depResult = await installDeps(targetDir);
+  if (!depResult.ok) {
+    const restored = await restoreBackup();
+    return { ok: false, error: `npm install 失败（${restored ? '已回滚' : '回滚失败，请检查 .backup'}）: ${depResult.error}` };
+  }
+  const rebuildResult = await rebuildDeps(targetDir);
+  if (!rebuildResult.ok) {
+    const restored = await restoreBackup();
+    return { ok: false, error: `native 模块重建失败（${restored ? '已回滚' : '回滚失败，请检查 .backup'}）: ${rebuildResult.error}` };
+  }
+
+  components.a2a.version = pkg.version;
+  components.a2a.upgradedAt = new Date().toISOString();
+  try {
+    writeComponents(componentsPath, components);
+  } catch (err) {
+    const restored = await restoreBackup();
+    return { ok: false, error: `components.json 更新失败（${restored ? '已回滚' : '回滚失败，请检查 .backup'}）: ${err.message}` };
+  }
+
+  const restart = await restartFn();
+  return {
+    ok: true,
+    version: pkg.version,
+    previousVersion: localVersion || null,
+    upgraded: true,
+    restarted: Boolean(restart?.success),
+    ...(restart?.success ? {} : { restartError: restart?.error || 'restart 未返回成功' }),
+  };
+}
+
+/**
+ * Web upload entry (D49 K3): 未安装 = 安装（D25 现状）；已安装 = 走升级管线。
+ * The server route delegates here so the dispatch decision lives next to the
+ * install/upgrade implementations.
+ */
+export async function installOrUpgradeA2aTarball(tarballPath, opts = {}) {
+  const skillsDir = opts.skillsDir ?? defaultSkillsDir();
+  const componentsPath = opts.componentsFile ?? componentsFile();
+  const targetDir = path.join(skillsDir, 'a2a');
+  const installed = fs.existsSync(targetDir) || Boolean(readComponents(componentsPath).a2a);
+  if (installed) return upgradeA2aTarball(tarballPath, opts);
+  return installA2aTarball(tarballPath, opts);
+}
+
 function schedulerDbPath() {
   return path.join(baizeDir(), 'scheduler', 'scheduler.db');
 }
@@ -464,6 +646,23 @@ function a2aDbPath() {
   return process.env.BAIZE_A2A_DB || path.join(baizeDir(), 'components', 'a2a', 'a2a.db');
 }
 
+/**
+ * D49: read the `baize init` A2A bootstrap result written by the detached
+ * `cli.js start --background` child (see baize-a2a daemon-ctl.bootstrapStatePath).
+ * Tolerant when the file does not exist (a2a never bootstrapped).
+ * @returns {{status?:string, via?:string, pid?:number, error?:string, at?:string}|null}
+ */
+export function getA2aBootstrapState() {
+  const file = process.env.BAIZE_A2A_BOOTSTRAP_STATE
+    || path.join(baizeDir(), 'components', 'a2a', 'bootstrap-state.json');
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return raw && typeof raw === 'object' ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Task board: task_runs rows created by the A2A worker (source = 'a2a', §3).
  * Tolerant when the table/DB does not exist yet (baize-a2a not started).