@asiainfo-sdd/multica-cli-test 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @asiainfo-sdd/multica-cli — multica（daemon 客户端）安装帮助包
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通过 npm 安装数字工厂 multica 命令（daemon 客户端二进制，含主机线能力）。
+**本包负责安装二进制与部署级配置**：npm install 时按平台自动下载、sha256 校验、落位，
+并把 `server_url` / `app_url` 合并写入 `~/.multica/config.json`（只填空，不覆盖已有值）；
+**不写 token、不登录、不启动/停止 daemon**——个人凭据与 daemon 生命周期始终由用户掌控。
+
+## 部署级配置的取值优先级
+
+```
+MULTICA_SERVER_URL / MULTICA_APP_URL 环境变量（安装时）
+  > manifest.json 顶层 server_url / app_url（运维改下载源即可，无需重发 npm 包）
+  > 包内 lib/dist-config.json（发布时按 profile 固化）
+```
+
+二进制下载源基址同样三级：`MULTICA_DOWNLOAD_BASE` 环境变量 > manifest 对应环境的 `lib/dist-config.json` 的 `download_base` > 包内置默认。
+
+用户 `~/.multica/config.json` 中已有的值**一律不覆盖**，仅提示。
+
+## 适用人群与前置
+
+- 内网办公电脑/服务器上的开发者，机器可访问下载源（可覆盖）
+- 已安装 Node.js ≥ 18 与 npm
+- 支持平台：darwin / linux / windows × amd64 / arm64
+
+## 安装
+
+```bash
+# 全局安装（推荐：npm 全局 bin 目录已在 PATH）
+npm i -g @asiainfo-sdd/multica-cli
+
+# 或项目内安装（用 npx 调用）
+npm i @asiainfo-sdd/multica-cli
+npx multica version
+```
+
+安装完成后按提示自行完成剩余步骤（若下载源已带 server_url 则只需两步）：
+
+```bash
+multica config set server_url https://<服务器地址>   # 仅当安装时未自动写入
+multica login --token mul_<个人令牌>                  # 令牌在 Web 端“设置→令牌”生成
+multica daemon start                                 # 需本机已装至少一个 agent CLI（claude/codex/opencode…）
+```
+
+日常管理：`multica daemon status` / `multica daemon logs` / `multica daemon stop`。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `MULTICA_DOWNLOAD_BASE` | 覆盖二进制下载源基址（源根需有 `manifest.json` 与 `v<版本>/` 目录） |
+| `MULTICA_SERVER_URL` / `MULTICA_APP_URL` | 安装时写入 `~/.multica/config.json` 的部署级配置（优先级高于 manifest 与包内置；不覆盖已有值） |
+| `MULTICA_SKIP_BINARY_INSTALL=1` | 跳过 postinstall 下载（`--ignore-scripts` 环境或自备二进制时用） |
+| `http_proxy` / `https_proxy` / `NO_PROXY` | 走内网代理时识别（Node 自带 fetch 不认这些变量，本包已自实现） |
+
+## 故障恢复
+
+| 症状 | 处理 |
+| --- | --- |
+| 安装时看不到“上手”提示 | npm ≥ 7 默认隐藏 postinstall 输出（脚本失败时才显示）；加 `--foreground-scripts` 参数即可看到，或安装后执行 `multica version` 确认可用 |
+| 执行 `multica` 提示二进制未下载 | `npm rebuild @asiainfo-sdd/multica-cli`（常见于 `--ignore-scripts` 安装或当时下载源不可达） |
+| 提示“multica 不是命令” | 重新打开终端；或用 `npx multica ...` |
+| 升级时提示文件被占用 | daemon 正在运行：先 `multica daemon stop`，再 `npm i -g @asiainfo-sdd/multica-cli@<版本>` |
+| 下载源不可达 | 确认 `MULTICA_DOWNLOAD_BASE`；检查代理变量 |
+
+## 升级
+
+```bash
+npm i -g @asiainfo-sdd/multica-cli@<新版本>
+```
+
+npm 包版本与二进制版本一一对应；postinstall 检测到版本变化会重新下载。
+daemon 的 auto-reload 默认开启：二进制替换后运行中的 daemon 会自动重启到新版本。
+
+## 版本发布（维护者）
+
+本包位于 multica 仓 `apps/multica-cli-installer/`（与 `server/` 同仓管理，随主仓 git 提交发布）。
+同一份源码按 profile 发布两个 npm 包（差异仅包名与内置部署级配置），发布流程：
+
+1. 本仓 `server/extensions/agentfoundry/build/build.sh cli-all <版本>`：
+   6 平台 CLI 产物 + `manifest.json` 落 `server/extensions/agentfoundry/dist/cli/`
+2. 如需随包分发部署级配置，在 `manifest.json` 顶层加 `server_url` / `app_url`
+3. 将 `dist/cli/` 整目录同步到目标环境下载源的 HTTP 静态根（MinIO `daemon-download/` 前缀）
+4. 在 `apps/multica-cli-installer/` 下按 profile 发布：
+   - 生产包：`node scripts/publish.mjs prod [版本]`
+   - 测试包：`node scripts/publish.mjs test`（连接测试环境，配置见 `publish/profiles.json`）
+   - 加 `--dry-run` 只打 tarball 检查，不实际发布
+5. 版本号在源 `package.json` 上推进（`lib/dist-config.json` 保持生产默认值；测试包的差异由 profile 注入）
+
+> 两包 bin 命令名均为 `multica`，同一台机器互斥安装；切换环境用
+> `npm rm -g <A> && npm i -g <B>`，安装时会自动覆盖式更新 `~/.multica/config.json`
+> 的 server_url/app_url 并提示（token 需重新登录生成）。
+
+## FAQ
+
+**Q: 为什么不把二进制打进 npm 包？**
+每个平台 17-68MB，6 平台约 200MB；HTTP 运行时下载让 npm 包保持 KB 级，且安装哪台机器才拉哪个平台。
+
+**Q: postinstall 下载失败了怎么办？**
+安装不会失败到阻断——失败时打印修复指引，之后 `npm rebuild @asiainfo-sdd/multica-cli` 重试。
+
+**Q: daemon 会自动升级吗？**
+self-host 场景下 daemon 的 auto-update 默认关闭；升级由你通过 npm 主动控制。

package/bin/multica.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+
+// bin wrapper：把参数原样转给 vendor/ 下的平台二进制。
+// 对外唯一命令名是 multica（aido 入口已移除）。
+// 二进制的子命令（daemon/login/config/...）与参数原样透传。
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { detectPlatform, vendorBinaryPath } = require('../lib/platform');
+const pkg = require('../package.json');
+
+const plat = detectPlatform();
+const binary =
+  plat && vendorBinaryPath(path.join(__dirname, '..', 'vendor'), plat);
+
+if (!binary || !fs.existsSync(binary)) {
+  console.error('✗ multica 二进制尚未下载。');
+  console.error(`  修复方式：npm rebuild ${pkg.name}`);
+  console.error('  （或设置 MULTICA_SKIP_BINARY_INSTALL=1 显式跳过后自备二进制）');
+  process.exit(127);
+}
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+// Windows 上 Ctrl-C 走 SIGINT/Break；转发常见终止信号。
+['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'].forEach((sig) => {
+  process.on(sig, () => child.kill(sig));
+});
+// Windows spawn .exe 时 kill('SIGTERM') 可能不生效，兜底强杀。
+process.on('exit', () => {
+  if (!child.killed) child.kill();
+});
+
+child.on('error', (err) => {
+  console.error(`✗ 无法执行 multica 二进制：${err.message}`);
+  process.exit(126);
+});
+
+child.on('close', (code, signal) => {
+  if (signal) {
+    process.exit(128);
+  }
+  process.exit(code ?? 1);
+});

package/lib/dist-config.json

@@ -0,0 +1,5 @@
+{
+  "server_url": "http://10.19.198.57:8080",
+  "app_url": "http://10.19.198.57:8080",
+  "download_base": "http://10.15.32.126:9090/aird-api/business/api/v1/external/daemon-download"
+}

package/lib/http.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// 零依赖 HTTP 客户端：Node 自带 fetch（undici）不认 http_proxy/https_proxy
+// 环境变量，内网代理场景必须自己处理。支持：
+//   - 直连 http/https
+//   - http_proxy / https_proxy / HTTP_PROXY / HTTPS_PROXY
+//   - NO_PROXY（逗号分隔主机名，支持后缀匹配）
+//   - https over proxy：CONNECT 隧道
+// 流式响应，供下载侧边收边算 sha256。
+
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const KEEP_ALIVE_AGENT_OPTIONS = { keepAlive: false };
+
+function proxyFromEnv(targetURL) {
+  const url = new URL(targetURL);
+  if (matchesNoProxy(url.hostname)) return null;
+  const proto = url.protocol === 'https:' ? 'https' : 'http';
+  const raw =
+    process.env[`${proto}_proxy`] || process.env[`${proto}_PROXY`] || '';
+  if (!raw) return null;
+  try {
+    const proxy = new URL(raw);
+    if (!/^https?:$/.test(proxy.protocol)) return null;
+    return proxy;
+  } catch {
+    return null;
+  }
+}
+
+function matchesNoProxy(hostname) {
+  const list = (process.env.NO_PROXY || process.env.NO_PROXY === '' ? process.env.NO_PROXY : process.env.no_proxy) || '';
+  if (!list) return false;
+  return list
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+    .some((entry) => {
+      if (entry === '*') return true;
+      if (entry.startsWith('.')) return hostname.endsWith(entry);
+      return hostname === entry || hostname.endsWith(`.${entry}`);
+    });
+}
+
+// http 目标 + http 代理：向代理发绝对 URI 的 GET。
+// https 目标 + 任意代理：先 CONNECT 隧道再在隧道上发 GET。
+function request(targetURL, { headers = {}, timeoutMs = 120000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(targetURL);
+    } catch (err) {
+      reject(new Error(`invalid URL: ${targetURL}`));
+      return;
+    }
+    const proxy = proxyFromEnv(targetURL);
+
+    const onConnectError = (err) =>
+      reject(new Error(`proxy connect failed: ${err.message}`));
+
+    if (url.protocol === 'https:' && proxy) {
+      const proxyPort = Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80);
+      const connectReq = http.request({
+        host: proxy.hostname,
+        port: proxyPort,
+        method: 'CONNECT',
+        path: `${url.hostname}:${url.port || 443}`,
+        headers: { Host: `${url.hostname}:${url.port || 443}` },
+        timeout: timeoutMs,
+      });
+      connectReq.on('connect', (res, socket) => {
+        if (res.statusCode !== 200) {
+          socket.destroy();
+          reject(new Error(`proxy CONNECT failed: ${res.statusCode}`));
+          return;
+        }
+        const agent = new https.Agent({ ...KEEP_ALIVE_AGENT_OPTIONS, socket });
+        const req = https.get(
+          {
+            host: url.hostname,
+            port: url.port || 443,
+            path: url.pathname + url.search,
+            headers,
+            agent,
+            timeout: timeoutMs,
+          },
+          resolve,
+        );
+        req.on('timeout', () => {
+          req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+      });
+      connectReq.on('error', onConnectError);
+      connectReq.on('timeout', () => {
+        connectReq.destroy(new Error(`proxy connect timed out after ${timeoutMs}ms`));
+      });
+      connectReq.end();
+      return;
+    }
+
+    const isHttps = url.protocol === 'https:';
+    const mod = isHttps ? https : http;
+    const options = {
+      host: proxy ? proxy.hostname : url.hostname,
+      port: proxy
+        ? Number(proxy.port) || (proxy.protocol === 'https:' ? 443 : 80)
+        : Number(url.port) || (isHttps ? 443 : 80),
+      method: 'GET',
+      path: proxy ? targetURL : url.pathname + url.search,
+      headers,
+      timeout: timeoutMs,
+    };
+    // https 代理入口（少见于内网）不支持时直接报错，不做二次降级。
+    if (proxy && proxy.protocol === 'https:') {
+      reject(new Error('https proxy entry is not supported'));
+      return;
+    }
+    const req = mod.get(options, resolve);
+    req.on('timeout', () => {
+      req.destroy(new Error(`request timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+  });
+}
+
+function checkStatus(res, what) {
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    res.resume();
+    throw new Error(`${what} failed: HTTP ${res.statusCode} ${res.statusMessage || ''}`.trim());
+  }
+  return res;
+}
+
+async function fetchText(url, { timeoutMs = 10000 } = {}) {
+  const res = checkStatus(await request(url, { timeoutMs }), `fetch ${url}`);
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// 流式下载到可写流，返回 { statusCode 后已校验的响应流 }。
+// onProgress(bytesDone, totalOrNull) 仅在有内容时回调。
+function downloadToStream(url, dest, { timeoutMs = 300000, onProgress } = {}) {
+  return new Promise(async (resolve, reject) => {
+    let res;
+    try {
+      res = await request(url, { timeoutMs });
+      checkStatus(res, `download ${url}`);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const total = Number(res.headers['content-length']) || null;
+    let done = 0;
+    let lastTick = 0;
+    res.on('data', (chunk) => {
+      done += chunk.length;
+      const now = Date.now();
+      if (onProgress && (now - lastTick > 200 || done === total)) {
+        lastTick = now;
+        onProgress(done, total);
+      }
+    });
+    res.on('error', reject);
+    dest.on('error', reject);
+    res.pipe(dest);
+    dest.on('finish', () => resolve());
+  });
+}
+
+module.exports = { request, fetchText, downloadToStream };

package/lib/install.js

@@ -0,0 +1,337 @@
+'use strict';
+
+// postinstall 主流程：按平台下载 multica CLI 二进制（-tags agentfoundry
+// 构建，含 daemon 主机线能力）并落位到包内 vendor/。
+// 只管安装：不读写 ~/.multica 配置、不登录、不启动/停止 daemon。
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const { detectPlatform, manifestKey, vendorBinaryPath } = require('./platform');
+const { applyServerConfig } = require('./server-config');
+const http = require('./http');
+
+const pkg = require('../package.json');
+
+// 下载源兜底基址（生产）。实际取值：MULTICA_DOWNLOAD_BASE 环境变量
+// > lib/dist-config.json 的 download_base（发布脚本按 profile 注入）> 此默认值。
+const DEFAULT_DOWNLOAD_BASE = 'https://aido.asiainfo.com/aird-api/business/api/v1/external/daemon-download';
+const LOCK_STALE_MS = 5 * 60 * 1000;
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function downloadBase() {
+  const fromConfig = require('./dist-config.json').download_base;
+  return (
+    process.env.MULTICA_DOWNLOAD_BASE || fromConfig || DEFAULT_DOWNLOAD_BASE
+  ).replace(/\/+$/, '');
+}
+
+function vendorDir() {
+  return path.join(__dirname, '..', 'vendor');
+}
+
+function installedMarkerPath() {
+  return path.join(vendorDir(), '.installed.json');
+}
+
+function readInstalled() {
+  try {
+    return JSON.parse(fs.readFileSync(installedMarkerPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ---------- manifest ----------
+
+function fallbackManifest() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(__dirname, 'manifest.fallback.json'), 'utf8'),
+    );
+  } catch {
+    return null;
+  }
+}
+
+async function loadManifest() {
+  const base = downloadBase();
+  try {
+    const text = await http.fetchText(`${base}/manifest.json`, { timeoutMs: 10000 });
+    return { manifest: JSON.parse(text), source: base };
+  } catch (err) {
+    log(`⚠ 无法从 ${base} 获取 manifest（${err.message}），改用包内置兜底清单`);
+    const fb = fallbackManifest();
+    if (fb) return { manifest: fb, source: 'fallback' };
+    return { manifest: null, source: 'none' };
+  }
+}
+
+function pickEntry(manifest, version) {
+  return manifest?.versions?.[version] || null;
+}
+
+// ---------- 锁 ----------
+
+function acquireLock(dir) {
+  const lockPath = path.join(dir, '.lock');
+  fs.mkdirSync(dir, { recursive: true });
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return { release: () => fs.rmSync(lockPath, { force: true }) };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const st = fs.statSync(lockPath);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+          fs.rmSync(lockPath, { force: true });
+          continue; // 陈旧锁已破，重试获取
+        }
+      } catch {
+        continue; // 锁文件刚被对方释放
+      }
+      if (attempt > 60) {
+        throw new Error('另一进程正在下载 multica 二进制，等待超时；请稍后重试 npm rebuild');
+      }
+      const until = Date.now() + 2000;
+      while (Date.now() < until) {} // 同步安装脚本内简短等待
+    }
+  }
+}
+
+// ---------- 下载与校验 ----------
+
+function progressPrinter(isTTY) {
+  if (!isTTY) {
+    let announced = false;
+    return (done, total) => {
+      if (!announced) {
+        announced = true;
+        log(`… 开始下载${total ? `（共 ${(total / 1048576).toFixed(1)} MB）` : ''}，完成后报告`);
+      }
+    };
+  }
+  return (done, total) => {
+    const mb = (n) => (n / 1048576).toFixed(1);
+    const pct = total ? ` (${Math.floor((done / total) * 100)}%)` : '';
+    process.stdout.write(`\r  下载中 ${mb(done)}${total ? `/${mb(total)} MB` : ' MB'}${pct}   `);
+  };
+}
+
+function sha256Of(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', reject);
+    stream.on('data', (c) => hash.update(c));
+    stream.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+async function downloadOnce(url, tmpPath, expectedSize) {
+  await new Promise((resolve, reject) => {
+    fs.mkdirSync(path.dirname(tmpPath), { recursive: true });
+    const out = fs.createWriteStream(tmpPath);
+    const onProgress = progressPrinter(process.stdout.isTTY);
+    http
+      .downloadToStream(url, out, { onProgress })
+      .then(resolve, reject);
+  });
+  if (process.stdout.isTTY) process.stdout.write('\n');
+  if (expectedSize && fs.statSync(tmpPath).size !== expectedSize) {
+    throw new Error(`大小不符：期望 ${expectedSize}，实际 ${fs.statSync(tmpPath).size}`);
+  }
+}
+
+function hintRunRebuild() {
+  log(`  修复方式：稍后执行  npm rebuild ${pkg.name}`);
+}
+
+// 把部署级配置(server_url/app_url)写入 ~/.multica/config.json（覆盖式）。
+// manifest 失败时传 null,退回 env > 包内置默认值。
+function applyServerConfigSafe(manifest) {
+  let result;
+  try {
+    result = applyServerConfig(manifest);
+  } catch (err) {
+    log(`⚠ 写入服务器配置失败（${err.message}），请手工执行 multica config set server_url <地址>`);
+    return;
+  }
+  if (!result) return;
+  for (const { key, value } of result.written) {
+    log(`✓ 已写入 ${key} = ${value}（${require('./server-config').multicaConfigPath()}）`);
+  }
+  for (const { key, from, to } of result.updated) {
+    log(`✓ 已更新 ${key}：${from} → ${to}（环境切换；token 需重新登录生成）`);
+  }
+}
+
+async function install() {
+  if (process.env.MULTICA_SKIP_BINARY_INSTALL === '1') {
+    log('ℹ MULTICA_SKIP_BINARY_INSTALL=1，跳过二进制下载。');
+    log(`  需要时执行 npm rebuild ${pkg.name} 完成下载。`);
+    return;
+  }
+
+  const plat = detectPlatform();
+  if (!plat) {
+    log(`⚠ 当前平台 ${process.platform}/${process.arch} 不在支持矩阵（darwin/linux/windows × amd64/arm64），跳过下载。`);
+    log('  如需在其他机器安装，请确认平台受支持后重试。');
+    return;
+  }
+
+  const version = pkg.version;
+  const key = manifestKey(plat);
+  const { manifest } = await loadManifest();
+  const versionEntry = pickEntry(manifest, version);
+  const entry = versionEntry?.[key];
+
+  if (!entry) {
+    log(`⚠ 下载清单中未找到 v${version} 的 ${key} 产物，暂不下载。`);
+    log(`  下载源：${downloadBase()}（可用 MULTICA_DOWNLOAD_BASE 覆盖）`);
+    hintRunRebuild();
+    return;
+  }
+
+  const dir = vendorDir();
+  const target = vendorBinaryPath(dir, plat);
+
+  // 幂等：已装同版本且校验通过则跳过。
+  const installed = readInstalled();
+  if (
+    installed &&
+    installed.version === version &&
+    installed.sha256 === entry.sha256 &&
+    fs.existsSync(target)
+  ) {
+    log(`✓ multica v${version} 已就绪（${path.basename(target)}，无需重复下载）`);
+    applyServerConfigSafe(manifest);
+    printUsage(version);
+    return;
+  }
+
+  const url = `${downloadBase()}/${entry.path.replace(/^\/+/, '')}`;
+  log(`→ 安装 multica（daemon 客户端）v${version}（${key}）`);
+  log(`  下载源：${url}`);
+
+  const lock = acquireLock(dir);
+  try {
+    // 拿到锁后复查：等锁期间对方可能已完成安装。
+    const recheck = readInstalled();
+    if (
+      recheck &&
+      recheck.version === version &&
+      recheck.sha256 === entry.sha256 &&
+      fs.existsSync(target)
+    ) {
+      log(`✓ multica v${version} 已就绪（并发安装合并，跳过下载）`);
+      printUsage(version);
+      return;
+    }
+
+    const tmpPath = path.join(dir, `.tmp-${process.pid}`);
+    let lastErr = null;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      try {
+        await downloadOnce(url, tmpPath, entry.size);
+        const actual = await sha256Of(tmpPath);
+        if (actual.toLowerCase() !== entry.sha256.toLowerCase()) {
+          throw new Error(`sha256 校验失败：期望 ${entry.sha256}，实际 ${actual}`);
+        }
+        lastErr = null;
+        break;
+      } catch (err) {
+        lastErr = err;
+        fs.rmSync(tmpPath, { force: true });
+        if (attempt === 1) log(`  下载/校验失败（${err.message}），重试一次…`);
+      }
+    }
+    if (lastErr) {
+      log(`✗ 二进制下载失败：${lastErr.message}`);
+      log(`  请检查网络与下载源 ${downloadBase()} 是否可达（代理变量 http_proxy/https_proxy 会被识别）`);
+      hintRunRebuild();
+      process.exitCode = 1;
+      return;
+    }
+
+    try {
+      fs.rmSync(target, { force: true });
+      fs.renameSync(tmpPath, target);
+    } catch (err) {
+      if (err.code === 'EPERM' || err.code === 'EBUSY' || err.code === 'EACCES') {
+        log('✗ 无法替换二进制文件：文件被占用（通常是 daemon 正在运行）。');
+        log(`  请先执行 multica daemon stop，再运行 npm rebuild ${pkg.name}。`);
+      } else {
+        log(`✗ 落位失败：${err.message}`);
+      }
+      hintRunRebuild();
+      process.exitCode = 1;
+      return;
+    }
+
+    if (process.platform !== 'win32') fs.chmodSync(target, 0o755);
+    if (process.platform === 'darwin') {
+      // ad-hoc 签名，避免 Gatekeeper 拦截 spawn；失败不致命。
+      const r = spawnSync('codesign', ['-s', '-', '--force', target], { stdio: 'ignore' });
+      if (r.status !== 0) log('  （codesign ad-hoc 签名失败，可忽略）');
+    }
+
+    fs.writeFileSync(
+      installedMarkerPath(),
+      JSON.stringify(
+        { version, sha256: entry.sha256, installedAt: new Date().toISOString() },
+        null,
+        2,
+      ),
+    );
+    log(`✓ multica v${version} 安装完成：${target}`);
+    applyServerConfigSafe(manifest);
+    printUsage(version);
+  } finally {
+    lock.release();
+  }
+}
+
+function printUsage(version) {
+  log('');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  log(`  multica（daemon 客户端）v${version} 已就绪`);
+  const configPath = require('./server-config').multicaConfigPath();
+  // 以用户配置文件里最终的 server_url 为准（含此前手工配置过的场景）。
+  let effectiveServerUrl = '';
+  try {
+    effectiveServerUrl =
+      JSON.parse(require('fs').readFileSync(configPath, 'utf8')).server_url || '';
+  } catch {
+    // 文件缺失/损坏：走三步指引
+  }
+  if (effectiveServerUrl) {
+    log(`  ✓ 服务器地址已就绪：${configPath}（server_url = ${effectiveServerUrl}）`);
+    log('  接下来请自行完成两步：');
+    log('    1. multica login --token mul_<个人令牌>   ← 令牌在 Web 端“设置→令牌”生成');
+    log('    2. multica daemon start   ← 需本机已装至少一个 agent CLI（claude/codex/opencode…）');
+  } else {
+    log('  接下来请自行完成三步：');
+    log('    1. multica config set server_url https://<服务器地址>');
+    log('    2. multica login --token mul_<个人令牌>   ← 令牌在 Web 端“设置→令牌”生成');
+    log('    3. multica daemon start   ← 需本机已装至少一个 agent CLI（claude/codex/opencode…）');
+  }
+  log('  日常管理：multica daemon status / logs / stop');
+  log('  提示“multica 不是命令” → 重新打开终端，或用 npx multica ...');
+  log('  本包只负责安装与部署级配置：不会写 token、不会登录、不会启动 daemon。');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+}
+
+install().catch((err) => {
+  log(`✗ 安装脚本异常：${err.stack || err.message}`);
+  hintRunRebuild();
+  process.exitCode = 1;
+});

package/lib/platform.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// platform/arch → 下载资产维度。产物命名与 multica 仓
+// server/extensions/agentfoundry/build/build.sh 的 cli-all 模式对齐：
+// multica-af-<os>-<arch>[.exe]
+
+const OS_MAP = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows',
+};
+
+const ARCH_MAP = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+// 返回 null 表示当前平台不在 6 平台支持矩阵内。
+function detectPlatform(platform = process.platform, arch = process.arch) {
+  const os = OS_MAP[platform];
+  const mappedArch = ARCH_MAP[arch];
+  if (!os || !mappedArch) return null;
+  return { os, arch: mappedArch, ext: platform === 'win32' ? '.exe' : '' };
+}
+
+function assetName({ os, arch, ext }) {
+  return `multica-af-${os}-${arch}${ext}`;
+}
+
+// manifest.json 里的平台键。
+function manifestKey({ os, arch }) {
+  return `${os}-${arch}`;
+}
+
+function vendorBinaryPath(vendorDir, plat) {
+  const path = require('path');
+  return path.join(vendorDir, assetName(plat));
+}
+
+module.exports = {
+  detectPlatform,
+  assetName,
+  manifestKey,
+  vendorBinaryPath,
+};

package/lib/server-config.js

@@ -0,0 +1,102 @@
+'use strict';
+
+// 安装时把部署级配置(server_url/app_url)写入 ~/.multica/config.json,
+// 免去用户手工 multica config set。规则:
+//   - 取值优先级: MULTICA_SERVER_URL/MULTICA_APP_URL env > manifest 顶层
+//     server_url/app_url(运维可不重发 npm 包直接改) > lib/dist-config.json
+//   - server_url/app_url 两个部署级 URL【覆盖式】更新: 与本次安装源不一致时
+//     直接覆盖并打印 新值 ← 旧值(升级环境后旧地址上的 token 验证/daemon 连接
+//     必然失败,覆盖是唯一正确动作;自定义地址用户可从日志看到旧值并改回)
+//   - 其余字段(token/workspace_id/各超时/backends 等)一律不动
+//   - 目标文件是 multica CLI 的标准配置(daemon 只认这里的 token),
+//     多 profile 场景(--profile)不在此处理,留给用户手动 config set
+// token 属于个人凭据,始终由用户自行 multica login --token 写入。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONFIG_KEYS = ['server_url', 'app_url'];
+
+function multicaConfigPath() {
+  return path.join(os.homedir(), '.multica', 'config.json');
+}
+
+function readUserConfig() {
+  const file = multicaConfigPath();
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { config: {}, existed: false };
+    throw err;
+  }
+  const config = JSON.parse(raw); // 解析失败向上抛,由调用方决定跳过
+  return { config, existed: true };
+}
+
+// env > manifest > dist-config;返回只含非空键的 {server_url?, app_url?}。
+function resolveDesired(manifest) {
+  const distConfig = require('./dist-config.json');
+  const desired = {};
+  const fromEnv = {
+    server_url: process.env.MULTICA_SERVER_URL,
+    app_url: process.env.MULTICA_APP_URL,
+  };
+  for (const key of CONFIG_KEYS) {
+    const value =
+      (fromEnv[key] && fromEnv[key].trim()) ||
+      (manifest && typeof manifest[key] === 'string' && manifest[key].trim()) ||
+      (typeof distConfig[key] === 'string' && distConfig[key].trim()) ||
+      '';
+    if (value) desired[key] = value;
+  }
+  return desired;
+}
+
+// 返回 {written: [{key, value}], updated: [{key, from, to}]} 供上层打印;
+// 无可写内容或文件损坏时返回 null(不产生任何变更)。
+// written = 原来为空、本次填入;updated = 原有不同值、本次覆盖。
+function applyServerConfig(manifest) {
+  const desired = resolveDesired(manifest);
+  if (!desired.server_url && !desired.app_url) return null;
+
+  let userConfig;
+  let existed;
+  try {
+    ({ config: userConfig, existed } = readUserConfig());
+  } catch {
+    logWarn(`已存在 ${multicaConfigPath()} 但无法解析,已跳过配置写入——请手工 multica config set server_url`);
+    return null;
+  }
+
+  const written = [];
+  const updated = [];
+  let changed = false;
+  for (const key of CONFIG_KEYS) {
+    if (!desired[key]) continue;
+    if (!userConfig[key]) {
+      userConfig[key] = desired[key];
+      written.push({ key, value: desired[key] });
+      changed = true;
+    } else if (userConfig[key] !== desired[key]) {
+      updated.push({ key, from: userConfig[key], to: desired[key] });
+      userConfig[key] = desired[key];
+      changed = true;
+    }
+  }
+
+  if (!changed) return { written, updated };
+
+  const file = multicaConfigPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // 保留用户已有其余字段,仅更新部署级键;不写 token。
+  fs.writeFileSync(file, JSON.stringify(userConfig, null, 2) + '\n');
+  return { written, updated };
+}
+
+function logWarn(msg) {
+  process.stdout.write(`⚠ ${msg}\n`);
+}
+
+module.exports = { applyServerConfig, multicaConfigPath, resolveDesired };

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@asiainfo-sdd/multica-cli-test",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "数字工厂 daemon 客户端安装帮助包（测试环境）：连接测试环境服务器与测试环境二进制下载源",
+  "bin": {
+    "multica": "bin/multica.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "multica": {
+    "configKeysWrittenAtInstall": [
+      "server_url",
+      "app_url"
+    ],
+    "notes": "安装时只填空写入部署级配置（env MULTICA_SERVER_URL/MULTICA_APP_URL > manifest 顶层 > lib/dist-config.json）；不写 token、不覆盖已有值"
+  }
+}