@vantaloom/cli 0.15.36 → 0.15.37

package/src/lib/install.mjs

@@ -151,7 +151,7 @@ export async function applyPackage(packageRoot, prefix, options) {
 
   // Copy package contents to install prefix
   const optionalDirs = new Set()
-  for (const name of ["bin", "web", "cli"]) {
+  for (const name of ["bin", "web", "cli", "skills"]) {
     const src = path.join(packageRoot, name)
     const dst = path.join(prefix, name)
     if (!existsSync(src)) {
@@ -243,7 +243,7 @@ export async function applyPackage(packageRoot, prefix, options) {
 }
 
 export function assertRuntimePackage(packageRoot) {
-  for (const name of ["bin", "web", "cli", "manifest.json"]) {
+  for (const name of ["bin", "web", "cli", "skills", "manifest.json"]) {
     if (!existsSync(path.join(packageRoot, name))) {
       throw new Error(`invalid Vantaloom package, missing ${name}: ${packageRoot}`)
     }
@@ -352,6 +352,19 @@ export function assertSourceRoot(sourceRoot) {
   return sourceRoot
 }
 
+// copyAgentSkills 把仓库里的 agent skill 打进 runtime 包。skill 是给外部 agent
+// （Claude Code / Cursor / Codex）读的使用手册，"vantaloom mcp install --skill"
+// 从这里取——装了 runtime 的机器上通常没有源码仓库，不随包分发就等于没有。
+export async function copyAgentSkills(sourceRoot, buildSkills) {
+  const src = path.join(sourceRoot, "integrations", "agent-skills")
+  if (!existsSync(src)) {
+    console.error("  warning: integrations/agent-skills not found; runtime package ships without skills")
+    return
+  }
+  removeKnownPath(buildSkills, path.dirname(buildSkills))
+  await copyDir(src, buildSkills)
+}
+
 export async function copyStaticWeb(sourceRoot, buildWeb) {
   const exportRoot = path.join(sourceRoot, "apps", "vantaloom", "out")
   if (!existsSync(exportRoot)) {
@@ -464,7 +477,7 @@ export function writeRuntimePackageMetadata(packageRoot, sourceRoot, platform) {
         type: "module",
         os: [runtimeOS],
         cpu: [cpu],
-        files: ["bin", "web", "cli", "manifest.json", "VERSION", "README.md"],
+        files: ["bin", "web", "cli", "skills", "manifest.json", "VERSION", "README.md"],
         publishConfig: {
           access: "public",
         },

package/src/lib/mcp.mjs

@@ -0,0 +1,264 @@
+// vantaloom mcp —— 把跨机执行信道（vantaloom-mcp）注册给外部 agent。
+//
+// 为什么需要这条命令：MCP 服务端是随 runtime 分发的一个二进制，装在
+// <prefix>/bin/ 下。要用它，用户（或一个 agent）得先知道那个绝对路径，再手动
+// 编辑三家客户端各自格式不同的配置文件——这一步足以劝退绝大多数人，也让「让
+// 另一个 agent 自己接上」变成一次寻宝游戏。这条命令把路径与配置都算好，能自动
+// 写的就直接写。
+//
+// 三家客户端的配置位置与格式（都用「读—合并—原子写」，先备份）：
+//   - Claude Code：~/.claude.json          JSON，mcpServers 顶层键
+//   - Cursor：     ~/.cursor/mcp.json      JSON，mcpServers 顶层键
+//   - Codex：      ~/.codex/config.toml    TOML，[mcp_servers.<name>] 段
+
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { binaryName, defaultPrefix, safeDirectory } from "./platform.mjs"
+
+// serverName 是注册进各客户端的 MCP 服务端名字，与 skill 同名以便对应。
+const serverName = "vantaloom-fleet"
+
+// mcpBinaryPath 返回本机 MCP 服务端的绝对路径（不校验存在性）。
+export function mcpBinaryPath(prefix) {
+  return path.join(safeDirectory(prefix ?? defaultPrefix()), "bin", binaryName("vantaloom-mcp"))
+}
+
+// clientTargets 描述三家客户端的配置落点。
+function clientTargets() {
+  const home = os.homedir()
+  return {
+    claude: { label: "Claude Code", file: path.join(home, ".claude.json"), kind: "json" },
+    cursor: { label: "Cursor", file: path.join(home, ".cursor", "mcp.json"), kind: "json" },
+    codex: { label: "Codex", file: path.join(home, ".codex", "config.toml"), kind: "toml" },
+  }
+}
+
+// serverEntry 是 JSON 客户端的服务端条目。env 里显式写上 VANTALOOM_API：本机
+// 换过端口时用户改一处就够，不必去猜默认值。
+function serverEntry(binary, apiBase) {
+  return { command: binary, env: { VANTALOOM_API: apiBase } }
+}
+
+// tomlBlock 是 Codex 的 TOML 段（它的配置不是 JSON，得单独拼）。
+function tomlBlock(binary, apiBase) {
+  const escaped = binary.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+  return [
+    `[mcp_servers.${serverName}]`,
+    `command = "${escaped}"`,
+    `args = []`,
+    ``,
+    `[mcp_servers.${serverName}.env]`,
+    `VANTALOOM_API = "${apiBase}"`,
+    ``,
+  ].join("\n")
+}
+
+// writeAtomic 先落临时文件再 rename，避免写到一半把用户的配置写坏。
+function writeAtomic(file, content) {
+  mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.vantaloom-tmp`
+  writeFileSync(tmp, content, "utf8")
+  renameSync(tmp, file)
+}
+
+// backupOnce 在首次改动前留一份 .bak（已存在则不覆盖——保住最原始那份）。
+function backupOnce(file) {
+  if (!existsSync(file)) return
+  const bak = `${file}.vantaloom-bak`
+  if (existsSync(bak)) return
+  try {
+    copyFileSync(file, bak)
+  } catch {}
+}
+
+// installJSONClient 把服务端条目合并进 JSON 配置的 mcpServers。
+function installJSONClient(target, binary, apiBase, force) {
+  let config = {}
+  if (existsSync(target.file)) {
+    const raw = readFileSync(target.file, "utf8").trim()
+    if (raw) {
+      try {
+        config = JSON.parse(raw)
+      } catch (error) {
+        // 解析不了就停手：这是用户的配置文件，宁可让他自己看一眼，也不能拿一个
+        // 空对象覆盖掉（那会静默清空 Claude Code 的全部本地状态）。
+        return { ok: false, detail: `配置文件不是合法 JSON，未改动：${error.message}` }
+      }
+    }
+  }
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    return { ok: false, detail: "配置文件顶层不是对象，未改动" }
+  }
+  const servers = config.mcpServers && typeof config.mcpServers === "object" ? config.mcpServers : {}
+  const existing = servers[serverName]
+  if (existing && !force) {
+    const same = existing.command === binary
+    return {
+      ok: true,
+      detail: same ? "已注册（未改动）" : `已存在同名条目且路径不同（${existing.command}）——加 --force 覆盖`,
+      skipped: true,
+    }
+  }
+  servers[serverName] = serverEntry(binary, apiBase)
+  config.mcpServers = servers
+  backupOnce(target.file)
+  writeAtomic(target.file, `${JSON.stringify(config, null, 2)}\n`)
+  return { ok: true, detail: existing ? "已更新" : "已注册" }
+}
+
+// installTOMLClient 往 Codex 的 config.toml 追加一段。TOML 只做「不存在才追加」：
+// 就地改写 TOML 需要一个完整的解析器，为了一段配置引入那种复杂度不划算，而
+// 追加对合法 TOML 恒安全。
+function installTOMLClient(target, binary, apiBase, force) {
+  let existing = ""
+  if (existsSync(target.file)) {
+    existing = readFileSync(target.file, "utf8")
+  }
+  if (existing.includes(`[mcp_servers.${serverName}]`)) {
+    if (!force) {
+      return { ok: true, detail: "已注册（未改动）", skipped: true }
+    }
+    return {
+      ok: false,
+      detail: `已存在 [mcp_servers.${serverName}] 段，请手动编辑 ${target.file}（TOML 就地改写不做自动合并）`,
+    }
+  }
+  backupOnce(target.file)
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : ""
+  writeAtomic(target.file, `${existing}${prefix}\n${tomlBlock(binary, apiBase)}`)
+  return { ok: true, detail: "已注册" }
+}
+
+// installSkill 把 vantaloom-fleet skill 复制到 Claude Code 的技能目录。
+function installSkill(prefix) {
+  const src = path.join(safeDirectory(prefix ?? defaultPrefix()), "skills", serverName)
+  if (!existsSync(src)) {
+    return { ok: false, detail: `runtime 未附带 skill（缺 ${src}）——需要 ≥0.15.37 的 runtime` }
+  }
+  const dst = path.join(os.homedir(), ".claude", "skills", serverName)
+  mkdirSync(path.dirname(dst), { recursive: true })
+  rmSync(dst, { recursive: true, force: true })
+  cpSync(src, dst, { recursive: true, force: true })
+  return { ok: true, detail: dst }
+}
+
+// runMcp 是 "vantaloom mcp [path|print|install]" 的入口。
+export async function runMcp(subcommand, options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const binary = mcpBinaryPath(prefix)
+  const apiBase = (options.api ?? "http://127.0.0.1:8780").replace(/\/+$/, "")
+  const action = subcommand ?? "status"
+
+  if (action === "path") {
+    console.log(binary)
+    return
+  }
+
+  if (action === "print") {
+    printSnippets(binary, apiBase)
+    return
+  }
+
+  if (action === "status") {
+    printStatus(binary, apiBase, prefix)
+    return
+  }
+
+  if (action !== "install") {
+    throw new Error(`unknown "vantaloom mcp" subcommand "${action}" (expected: status|path|print|install)`)
+  }
+
+  if (!existsSync(binary)) {
+    throw new Error(
+      `未找到 MCP 服务端：${binary}\n` +
+        `请先安装/更新 runtime（vantaloom update），或用 --prefix 指定安装目录。`
+    )
+  }
+
+  const targets = clientTargets()
+  const requested = String(options.client ?? "all").toLowerCase()
+  const names = requested === "all" ? Object.keys(targets) : requested.split(",").map((s) => s.trim())
+
+  console.log(`MCP 服务端：${binary}`)
+  for (const name of names) {
+    const target = targets[name]
+    if (!target) {
+      console.error(`  ${name}: 未知客户端（可选 claude / cursor / codex / all）`)
+      continue
+    }
+    let result
+    try {
+      result =
+        target.kind === "json"
+          ? installJSONClient(target, binary, apiBase, Boolean(options.force))
+          : installTOMLClient(target, binary, apiBase, Boolean(options.force))
+    } catch (error) {
+      result = { ok: false, detail: error.message }
+    }
+    const mark = result.ok ? (result.skipped ? "•" : "✓") : "✗"
+    console.log(`  ${mark} ${target.label}: ${result.detail} (${target.file})`)
+  }
+
+  if (options.skill !== false) {
+    const skill = installSkill(prefix)
+    console.log(`  ${skill.ok ? "✓" : "✗"} skill: ${skill.detail}`)
+  }
+
+  console.log(
+    `\n重启对应客户端后，让它「列出我的 Vantaloom 机器」即可验证（会调用 machines_list）。` +
+      `\n注意：MCP 服务端由客户端拉起，与 Vantaloom 运行时各自独立——但它需要本机运行时在跑。`
+  )
+}
+
+function printStatus(binary, apiBase, prefix) {
+  const installed = existsSync(binary)
+  console.log(`MCP 服务端：${binary}${installed ? "" : "  (未找到——先跑 vantaloom update)"}`)
+  console.log(`本机 API：  ${apiBase}`)
+  console.log(`skill：     ${path.join(prefix, "skills", serverName)}`)
+  console.log("")
+  const targets = clientTargets()
+  for (const [, target] of Object.entries(targets)) {
+    let state = "未注册"
+    if (existsSync(target.file)) {
+      const raw = readFileSync(target.file, "utf8")
+      if (target.kind === "json") {
+        try {
+          const parsed = JSON.parse(raw || "{}")
+          if (parsed?.mcpServers?.[serverName]) state = "已注册"
+        } catch {
+          state = "配置文件无法解析"
+        }
+      } else if (raw.includes(`[mcp_servers.${serverName}]`)) {
+        state = "已注册"
+      }
+    } else {
+      state = "未找到配置文件"
+    }
+    console.log(`  ${target.label.padEnd(12)} ${state}  (${target.file})`)
+  }
+  console.log(`\n一键注册：vantaloom mcp install            （全部客户端 + skill）`)
+  console.log(`单独注册：vantaloom mcp install --client cursor`)
+}
+
+function printSnippets(binary, apiBase) {
+  const jsonSnippet = JSON.stringify({ mcpServers: { [serverName]: serverEntry(binary, apiBase) } }, null, 2)
+  console.log("# Claude Code (~/.claude.json) / Cursor (~/.cursor/mcp.json)")
+  console.log(jsonSnippet)
+  console.log("\n# Codex (~/.codex/config.toml)")
+  console.log(tomlBlock(binary, apiBase))
+}
+
+// mcpHint 是 install/update 结束时打印的一行指引。
+export function mcpHint(prefix) {
+  return `提示：让 Claude Code / Cursor / Codex 驱动这台机器与整个组网 —— vantaloom mcp install（MCP 服务端在 ${mcpBinaryPath(prefix)}）`
+}

package/src/lib/package.mjs

@@ -1,56 +1,61 @@
-import { mkdirSync } from "node:fs"
-import path from "node:path"
-import { platformId, removeKnownPath, runPnpm } from "./platform.mjs"
-import {
-  buildGo,
-  copyStaticWeb,
-  copyCliDirectory,
-  writeBuildManifest,
-  writeRuntimePackageMetadata,
-  runtimeConfigFromSource,
-  gitVersion,
-  npmPackageVersion,
-} from "./install.mjs"
-
-export async function buildRuntimePackage(sourceRoot, packageRoot, options) {
-  // Every build — npm release AND local/dev — stamps VERSION/manifest with the
-  // npm package version. There is exactly ONE product version (the npm semver);
-  // the git hash is recorded separately as manifest `commit` for diagnostics.
-  // History: pre-0.13.5 local builds stamped the git hash into VERSION, which
-  // split the version universe in two (the desktop shell read VERSION, the
-  // settings page read cli/package.json) and broke update prompts both ways.
-  const version = npmPackageVersion(sourceRoot)
-  const commit = gitVersion(sourceRoot)
-  const platform = options.target ?? platformId()
-  const buildBin = path.join(packageRoot, "bin")
-  const buildWeb = path.join(packageRoot, "web")
-
-  removeKnownPath(packageRoot, path.dirname(packageRoot))
-  mkdirSync(buildBin, { recursive: true })
-
-  buildGo(sourceRoot, buildBin, "vantaloom-api", platform)
-  buildGo(sourceRoot, buildBin, "vantaloom-agent", platform)
-  buildGo(sourceRoot, buildBin, "vantaloomctl", platform)
-  // vantaloom-mcp：跨机执行信道的 MCP 服务端（agent-bridge）。随 runtime bin 分发，
-  // 外部 agent（Claude Code / Codex / Cursor）配置指向它即可驱动整个组网。
-  buildGo(sourceRoot, buildBin, "vantaloom-mcp", platform)
-  // 0.14.26: the browser moved into the official optional PLUGIN
-  // (@vantaloom/browser-plugin-<platform>, built by scripts/build-browser-plugin.ps1) —
-  // the runtime no longer builds the vantaloom-browser sidecar nor bundles the
-  // Obscura engine. The Windows system-tray app (vantaloom-tray) was removed
-  // earlier — it crash-looped on some Windows 11 builds. Neither is built here.
-
-  if (options.buildWeb) {
-    runPnpm(["--filter", "vantaloom-app", "build"], { cwd: sourceRoot })
-  }
-
-  await copyStaticWeb(sourceRoot, buildWeb)
-  await copyCliDirectory(path.join(packageRoot, "cli"), sourceRoot, runtimeConfigFromSource(sourceRoot))
-  writeBuildManifest(packageRoot, version, platform, commit)
-
-  return { platform, version }
-}
-
-// copyObscura was removed in 0.14.26: the Obscura engine ships inside the
-// official browser PLUGIN packages (scripts/build-browser-plugin.ps1), not the
-// runtime.
+import { mkdirSync } from "node:fs"
+import path from "node:path"
+import { platformId, removeKnownPath, runPnpm } from "./platform.mjs"
+import {
+  buildGo,
+  copyStaticWeb,
+  copyAgentSkills,
+  copyCliDirectory,
+  writeBuildManifest,
+  writeRuntimePackageMetadata,
+  runtimeConfigFromSource,
+  gitVersion,
+  npmPackageVersion,
+} from "./install.mjs"
+
+export async function buildRuntimePackage(sourceRoot, packageRoot, options) {
+  // Every build — npm release AND local/dev — stamps VERSION/manifest with the
+  // npm package version. There is exactly ONE product version (the npm semver);
+  // the git hash is recorded separately as manifest `commit` for diagnostics.
+  // History: pre-0.13.5 local builds stamped the git hash into VERSION, which
+  // split the version universe in two (the desktop shell read VERSION, the
+  // settings page read cli/package.json) and broke update prompts both ways.
+  const version = npmPackageVersion(sourceRoot)
+  const commit = gitVersion(sourceRoot)
+  const platform = options.target ?? platformId()
+  const buildBin = path.join(packageRoot, "bin")
+  const buildWeb = path.join(packageRoot, "web")
+
+  removeKnownPath(packageRoot, path.dirname(packageRoot))
+  mkdirSync(buildBin, { recursive: true })
+
+  buildGo(sourceRoot, buildBin, "vantaloom-api", platform)
+  buildGo(sourceRoot, buildBin, "vantaloom-agent", platform)
+  buildGo(sourceRoot, buildBin, "vantaloomctl", platform)
+  // vantaloom-mcp：跨机执行信道的 MCP 服务端（agent-bridge）。随 runtime bin 分发，
+  // 外部 agent（Claude Code / Codex / Cursor）配置指向它即可驱动整个组网。
+  buildGo(sourceRoot, buildBin, "vantaloom-mcp", platform)
+  // 0.14.26: the browser moved into the official optional PLUGIN
+  // (@vantaloom/browser-plugin-<platform>, built by scripts/build-browser-plugin.ps1) —
+  // the runtime no longer builds the vantaloom-browser sidecar nor bundles the
+  // Obscura engine. The Windows system-tray app (vantaloom-tray) was removed
+  // earlier — it crash-looped on some Windows 11 builds. Neither is built here.
+
+  if (options.buildWeb) {
+    runPnpm(["--filter", "vantaloom-app", "build"], { cwd: sourceRoot })
+  }
+
+  await copyStaticWeb(sourceRoot, buildWeb)
+  await copyCliDirectory(path.join(packageRoot, "cli"), sourceRoot, runtimeConfigFromSource(sourceRoot))
+  // agent skill：外部 agent（Claude Code 等）用来学会怎么用 vantaloom-mcp。
+  // 随 runtime 分发，"vantaloom mcp install --skill" 才有东西可装——否则用户
+  // 得先去仓库里找它，而装了 runtime 的机器上多半没有仓库。
+  await copyAgentSkills(sourceRoot, path.join(packageRoot, "skills"))
+  writeBuildManifest(packageRoot, version, platform, commit)
+
+  return { platform, version }
+}
+
+// copyObscura was removed in 0.14.26: the Obscura engine ships inside the
+// official browser PLUGIN packages (scripts/build-browser-plugin.ps1), not the
+// runtime.