@sswl/ai-manager 0.1.0

package/lib/runtime.js

@@ -0,0 +1,1441 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const cp = require("child_process");
+
+const APP_ROOT = path.join(os.homedir(), ".sswl-ai-coding-platform");
+const REPO_DIR = path.join(APP_ROOT, "repo");
+const STATE_DIR = path.join(APP_ROOT, "state");
+const CLI_STATE_DIR = path.join(STATE_DIR, "cli-manager");
+const LEGACY_GUI_STATE_DIR = path.join(STATE_DIR, "gui-manager");
+const RUNTIME_DIR = path.join(APP_ROOT, "runtime");
+const LOG_DIR = path.join(APP_ROOT, "logs");
+const GUI_INSTALL_DIR = path.join(CLI_STATE_DIR, "installations");
+const PLAN_DIR = path.join(CLI_STATE_DIR, "activation-plans");
+const PROJECTS_DIR = path.join(CLI_STATE_DIR, "projects");
+const SETTINGS_FILE = path.join(CLI_STATE_DIR, "settings.json");
+const LEGACY_SETTINGS_FILE = path.join(LEGACY_GUI_STATE_DIR, "settings.json");
+const DEFAULT_REPO_URL = "http://172.19.105.131/common-components/sswl-ai-coding-platform.git";
+const SUPPORTED_TOOLS = ["claude-code", "codex"];
+const REPO_MARKERS = ["catalog", "registry", "scripts", "standards"];
+
+const TOOL_DETECTORS = {
+  "claude-code": {
+    commands: ["claude"],
+    paths: [path.join(os.homedir(), ".claude")]
+  },
+  codex: {
+    commands: ["codex"],
+    paths: [path.join(os.homedir(), ".codex")]
+  }
+};
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function ensureRuntimeDirs() {
+  [APP_ROOT, STATE_DIR, CLI_STATE_DIR, RUNTIME_DIR, LOG_DIR, GUI_INSTALL_DIR, PLAN_DIR, PROJECTS_DIR].forEach(ensureDir);
+}
+
+function readJson(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) {
+    return fallback;
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function pathExists(targetPath) {
+  return Boolean(targetPath) && Boolean(fs.lstatSync(targetPath, { throwIfNoEntry: false }));
+}
+
+function isDirectory(targetPath) {
+  const stat = fs.lstatSync(targetPath, { throwIfNoEntry: false });
+  return Boolean(stat?.isDirectory());
+}
+
+function removePath(targetPath) {
+  if (!targetPath) {
+    return;
+  }
+  const resolvedTarget = path.resolve(targetPath);
+  const protectedPaths = new Set([
+    path.resolve("."),
+    path.resolve(__dirname, "..", "..", "..", ".."),
+    path.resolve(os.homedir()),
+    path.parse(resolvedTarget).root
+  ]);
+  if (protectedPaths.has(resolvedTarget)) {
+    return;
+  }
+  const stat = fs.lstatSync(targetPath, { throwIfNoEntry: false });
+  if (stat || fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+
+function runCommand(command, args, options = {}) {
+  const result = cp.spawnSync(command, args, {
+    encoding: "utf8",
+    ...options
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+  }
+  return (result.stdout || "").trim();
+}
+
+function streamCommand(command, args, options = {}, hooks = {}) {
+  return new Promise((resolve, reject) => {
+    const child = cp.spawn(command, args, {
+      ...options,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+
+    const emit = (chunk, source) => {
+      const text = chunk.toString();
+      const lines = text.replace(/\r/g, "").split("\n").filter(Boolean);
+      for (const line of lines) {
+        hooks.onLog?.(`[${source}] ${line}`);
+      }
+      return text;
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdout += emit(chunk, command);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += emit(chunk, command);
+    });
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout: stdout.trim(), stderr: stderr.trim() });
+        return;
+      }
+      reject(new Error((stderr || stdout || `${command} failed`).trim()));
+    });
+  });
+}
+
+function findCommandPath(commandName) {
+  const lookupCommand = process.platform === "win32" ? "where" : "which";
+  const result = cp.spawnSync(lookupCommand, [commandName], { encoding: "utf8" });
+  if (result.status !== 0) {
+    return "";
+  }
+  return String(result.stdout || "").split(/\r?\n/).find(Boolean) || "";
+}
+
+function detectInstalledTool(tool) {
+  const detector = TOOL_DETECTORS[tool] || {};
+  const commandPath = (detector.commands || []).map(findCommandPath).find(Boolean) || "";
+  const detectedPath = (detector.paths || []).find((candidate) => candidate && pathExists(candidate)) || "";
+  return {
+    installed: Boolean(commandPath || detectedPath),
+    command_path: commandPath,
+    detected_path: detectedPath
+  };
+}
+
+function normalizeAssetStatus(value) {
+  return String(value || "").trim().toLowerCase() === "release" ? "release" : "dev";
+}
+
+function normalizeArray(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => item !== "[]" && item !== "");
+  }
+  if (value === undefined || value === null || value === "" || value === "[]") {
+    return [];
+  }
+  return [String(value)];
+}
+
+function looksLikeRepoRoot(dirPath) {
+  return REPO_MARKERS.every((name) => pathExists(path.join(dirPath, name)));
+}
+
+function resolveRepoRoot(inputPath) {
+  if (!inputPath) {
+    return "";
+  }
+  let current = path.resolve(inputPath);
+  const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+  if (!stat) {
+    return current;
+  }
+  if (!stat.isDirectory()) {
+    current = path.dirname(current);
+  }
+  while (true) {
+    if (looksLikeRepoRoot(current)) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(inputPath);
+    }
+    current = parent;
+  }
+}
+
+function loadSettings() {
+  ensureRuntimeDirs();
+  const defaults = {
+    repo_url: DEFAULT_REPO_URL,
+    repo_dir: REPO_DIR,
+    current_scope: "project",
+    last_project_root: ""
+  };
+  return {
+    ...defaults,
+    ...(readJson(LEGACY_SETTINGS_FILE, {}) || {}),
+    ...(readJson(SETTINGS_FILE, {}) || {})
+  };
+}
+
+function saveSettings(partial = {}) {
+  const next = {
+    ...loadSettings(),
+    ...Object.fromEntries(Object.entries(partial).filter(([, value]) => value !== undefined))
+  };
+  writeJson(SETTINGS_FILE, next);
+  return next;
+}
+
+function updateSettings(payload = {}) {
+  const settings = saveSettings({
+    repo_url: payload.repo_url ? String(payload.repo_url).trim() : undefined,
+    repo_dir: payload.repo_dir ? resolveRepoRoot(payload.repo_dir) : undefined,
+    current_scope: payload.current_scope || undefined,
+    last_project_root: Object.prototype.hasOwnProperty.call(payload, "last_project_root")
+      ? (payload.last_project_root ? path.resolve(payload.last_project_root) : "")
+      : undefined
+  });
+  return { settings };
+}
+
+function getRepoStatus(repoDir) {
+  if (!fs.existsSync(path.join(repoDir, ".git"))) {
+    return {
+      exists: false,
+      repo_dir: repoDir,
+      repo_url: DEFAULT_REPO_URL,
+      branch: "",
+      commit: "",
+      remote_commit: "",
+      dirty: false
+    };
+  }
+  const branch = runCommand("git", ["-C", repoDir, "rev-parse", "--abbrev-ref", "HEAD"]);
+  const commit = runCommand("git", ["-C", repoDir, "rev-parse", "HEAD"]);
+  const repoUrl = runCommand("git", ["-C", repoDir, "remote", "get-url", "origin"]);
+  const status = runCommand("git", ["-C", repoDir, "status", "--porcelain"]);
+  let remoteCommit = "";
+  try {
+    remoteCommit = runCommand("git", ["-C", repoDir, "rev-parse", "@{u}"]);
+  } catch (_error) {
+    remoteCommit = "";
+  }
+  return {
+    exists: true,
+    repo_dir: repoDir,
+    repo_url: repoUrl,
+    branch,
+    commit,
+    remote_commit: remoteCommit,
+    dirty: Boolean(status)
+  };
+}
+
+function enterpriseProbeTarget(repoUrl = "") {
+  const candidate = String(repoUrl || DEFAULT_REPO_URL).trim();
+  if (!/^https?:\/\//i.test(candidate)) {
+    return "";
+  }
+  try {
+    const parsed = new URL(candidate);
+    return `${parsed.protocol}//${parsed.host}/`;
+  } catch (_error) {
+    return "";
+  }
+}
+
+async function checkEnterpriseReachability({ repoUrl = "", timeoutMs = 2500 } = {}) {
+  const target = enterpriseProbeTarget(repoUrl);
+  if (!target) {
+    return {
+      enforced: false,
+      reachable: true,
+      target: "",
+      checked_at: new Date().toISOString(),
+      status_label: "未配置企业网络探针",
+      error: ""
+    };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(500, Number(timeoutMs) || 2500));
+  try {
+    const response = await fetch(target, {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: { "cache-control": "no-cache" }
+    });
+    return {
+      enforced: true,
+      reachable: true,
+      target,
+      checked_at: new Date().toISOString(),
+      status_label: "企业网络可达",
+      status_code: response.status,
+      error: ""
+    };
+  } catch (error) {
+    return {
+      enforced: true,
+      reachable: false,
+      target,
+      checked_at: new Date().toISOString(),
+      status_label: "未连接企业 VPN / 内网",
+      error: error.name === "AbortError" ? "网络探测超时" : (error.message || String(error))
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function assertEnterpriseReachable({ repoUrl = "", timeoutMs = 2500 } = {}) {
+  const result = await checkEnterpriseReachability({ repoUrl, timeoutMs });
+  if (!result.enforced || result.reachable) {
+    return result;
+  }
+  throw new Error([
+    "当前未连接企业 VPN / 内网，已阻止继续操作。",
+    `探测地址：${result.target || "(empty)"}`,
+    result.error ? `原因：${result.error}` : ""
+  ].filter(Boolean).join("\n"));
+}
+
+function nodeScriptCommand(scriptPath, repoDir) {
+  return {
+    command: process.execPath,
+    args: [scriptPath],
+    label: `node ${scriptPath}`,
+    options: {
+      env: {
+        ...process.env,
+        SSWL_CONTROL_PLANE_REPO_ROOT: repoDir
+      }
+    }
+  };
+}
+
+function platformScriptCommand(scriptBaseName, repoDir) {
+  const jsScriptPath = path.join(repoDir, "scripts", `${scriptBaseName}.js`);
+  if (!pathExists(jsScriptPath)) {
+    throw new Error(`仓库缺少脚本：${jsScriptPath}`);
+  }
+  return nodeScriptCommand(jsScriptPath, repoDir);
+}
+
+function ensureBaseDistDirs(repoRoot) {
+  ensureDir(path.join(repoRoot, "dist"));
+  for (const tool of SUPPORTED_TOOLS) {
+    ensureDir(path.join(repoRoot, "dist", tool));
+  }
+}
+
+async function syncRepo({ repoUrl = "", repoDir = "" } = {}, hooks = {}) {
+  ensureRuntimeDirs();
+  const currentSettings = loadSettings();
+  const requestedRepoUrl = repoUrl ? String(repoUrl).trim() : currentSettings.repo_url || DEFAULT_REPO_URL;
+  await assertEnterpriseReachable({ repoUrl: requestedRepoUrl });
+  const requestedRepoDir = resolveRepoRoot(repoDir || currentSettings.repo_dir || REPO_DIR);
+  const settings = saveSettings({
+    repo_url: requestedRepoUrl,
+    repo_dir: requestedRepoDir
+  });
+  const resolvedRepoUrl = settings.repo_url;
+  const resolvedRepoDir = settings.repo_dir;
+  const reportProgress = (percent, stage, detail = "") => hooks.onProgress?.({ percent, stage, detail });
+
+  if (!fs.existsSync(path.join(resolvedRepoDir, ".git"))) {
+    ensureDir(path.dirname(resolvedRepoDir));
+    reportProgress(8, "clone", "开始克隆仓库");
+    hooks.onLog?.(`[sync] git clone ${resolvedRepoUrl} ${resolvedRepoDir}`);
+    await streamCommand("git", ["clone", resolvedRepoUrl, resolvedRepoDir], {}, hooks);
+  } else {
+    const currentOrigin = runCommand("git", ["-C", resolvedRepoDir, "remote", "get-url", "origin"]);
+    if (resolvedRepoUrl && currentOrigin !== resolvedRepoUrl) {
+      hooks.onLog?.(`[sync] git remote set-url origin ${resolvedRepoUrl}`);
+      runCommand("git", ["-C", resolvedRepoDir, "remote", "set-url", "origin", resolvedRepoUrl]);
+    }
+    reportProgress(18, "fetch", "开始拉取远端变更");
+    hooks.onLog?.(`[sync] git -C ${resolvedRepoDir} fetch --all --prune`);
+    await streamCommand("git", ["-C", resolvedRepoDir, "fetch", "--all", "--prune"], {}, hooks);
+    reportProgress(40, "pull", "开始合并远端变更");
+    hooks.onLog?.(`[sync] git -C ${resolvedRepoDir} pull --ff-only`);
+    await streamCommand("git", ["-C", resolvedRepoDir, "pull", "--ff-only"], {}, hooks);
+  }
+
+  if (!looksLikeRepoRoot(resolvedRepoDir)) {
+    throw new Error(`所选目录不是控制面仓库根目录：${resolvedRepoDir}`);
+  }
+
+  ensureBaseDistDirs(resolvedRepoDir);
+  reportProgress(62, "validate", "开始校验控制面");
+  const validateCommand = platformScriptCommand("validate-control-plane", resolvedRepoDir);
+  hooks.onLog?.(`[sync] ${validateCommand.label}`);
+  await streamCommand(validateCommand.command, validateCommand.args, { cwd: resolvedRepoDir, ...(validateCommand.options || {}) }, hooks);
+  reportProgress(82, "build", "开始构建分发产物");
+  const buildCommand = platformScriptCommand("build-distributions", resolvedRepoDir);
+  hooks.onLog?.(`[sync] ${buildCommand.label}`);
+  await streamCommand(buildCommand.command, buildCommand.args, { cwd: resolvedRepoDir, ...(buildCommand.options || {}) }, hooks);
+  reportProgress(100, "done", "同步完成");
+  return getAppState({ repoDir: resolvedRepoDir });
+}
+
+function parseSimpleYaml(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8").replace(/\r/g, "");
+  const lines = raw.split("\n");
+  const result = {};
+  let currentArrayKey = null;
+  for (const line of lines) {
+    if (!line.trim() || line.trim().startsWith("#")) {
+      continue;
+    }
+    const topMatch = line.match(/^([a-zA-Z0-9_-]+):(?:\s+(.*))?$/);
+    if (topMatch) {
+      currentArrayKey = null;
+      const key = topMatch[1];
+      const value = (topMatch[2] || "").trim();
+      if (value) {
+        result[key] = value;
+      } else {
+        result[key] = [];
+        currentArrayKey = key;
+      }
+      continue;
+    }
+    const listMatch = line.match(/^\s{2}-\s+(.*)$/);
+    if (listMatch && currentArrayKey) {
+      result[currentArrayKey].push(listMatch[1].trim());
+    }
+  }
+  return result;
+}
+
+function parseAssetIndex(repoRoot) {
+  const filePath = path.join(repoRoot, "registry", "assets", "index.yaml");
+  const lines = fs.readFileSync(filePath, "utf8").replace(/\r/g, "").split("\n");
+  const items = [];
+  let current = null;
+  for (const line of lines) {
+    const idMatch = line.match(/^  - id: (.+)$/);
+    if (idMatch) {
+      current = { id: idMatch[1].trim() };
+      items.push(current);
+      continue;
+    }
+    const fieldMatch = line.match(/^    ([a-z_]+): (.+)$/);
+    if (fieldMatch && current) {
+      current[fieldMatch[1]] = fieldMatch[2].trim();
+    }
+  }
+  return items;
+}
+
+function parseProfiles(repoRoot) {
+  const filePath = path.join(repoRoot, "registry", "distributions", "profiles.yaml");
+  const lines = fs.readFileSync(filePath, "utf8").replace(/\r/g, "").split("\n");
+  const profiles = [];
+  let current = null;
+  let section = null;
+  for (const line of lines) {
+    const idMatch = line.match(/^  - id: (.+)$/);
+    if (idMatch) {
+      current = { id: idMatch[1].trim(), supported_tools: [], asset_ids: [] };
+      profiles.push(current);
+      section = null;
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const fieldMatch = line.match(/^    ([a-z_]+): (.+)$/);
+    if (fieldMatch) {
+      current[fieldMatch[1]] = fieldMatch[2].trim();
+      section = null;
+      continue;
+    }
+    const sectionMatch = line.match(/^    ([a-z_]+):$/);
+    if (sectionMatch) {
+      section = sectionMatch[1];
+      if (!Array.isArray(current[section])) {
+        current[section] = [];
+      }
+      continue;
+    }
+    const itemMatch = line.match(/^      - (.+)$/);
+    if (itemMatch && section && Array.isArray(current[section])) {
+      current[section].push(itemMatch[1].trim());
+    }
+  }
+  return profiles;
+}
+
+function readContentPreview(assetDir, manifest) {
+  const contentFile = manifest.content_file;
+  if (!contentFile) {
+    return "";
+  }
+  const targetFile = path.join(assetDir, contentFile);
+  if (!pathExists(targetFile)) {
+    return "";
+  }
+  return fs.readFileSync(targetFile, "utf8")
+    .replace(/\r/g, "")
+    .split("\n")
+    .filter((line) => line.trim() && !line.trim().startsWith("---"))
+    .slice(0, 20)
+    .join("\n");
+}
+
+function readAssetCatalog(repoRoot) {
+  const indexItems = parseAssetIndex(repoRoot);
+  return indexItems.map((item) => {
+    const assetDir = path.join(repoRoot, item.path);
+    const manifest = parseSimpleYaml(path.join(assetDir, "manifest.yaml"));
+    const exposure = manifest.exposure || "public";
+    const installMode = manifest.install_mode || (exposure === "internal" ? "dependency-only" : "direct");
+    const status = normalizeAssetStatus(item.status || manifest.status);
+    return {
+      id: item.id,
+      type: item.type,
+      layer: item.layer,
+      domain: item.domain,
+      status,
+      risk_level: item.risk_level,
+      exposure,
+      install_mode: installMode,
+      installable: exposure !== "internal" && installMode !== "dependency-only",
+      path: item.path,
+      name: manifest.name || item.id,
+      version: manifest.version || "",
+      description: manifest.description || "",
+      owner: manifest.owner || "",
+      audience: normalizeArray(manifest.audience),
+      dependencies: normalizeArray(manifest.dependencies),
+      supported_tools: normalizeArray(manifest.supported_tools),
+      content_file: manifest.content_file || "",
+      content_preview: readContentPreview(assetDir, manifest)
+    };
+  });
+}
+
+function resolveAssetDependencySet(assets, assetIds) {
+  const assetMap = new Map(assets.map((asset) => [asset.id, asset]));
+  const resolved = new Set();
+  const queue = [...new Set(assetIds)];
+  while (queue.length > 0) {
+    const assetId = queue.shift();
+    if (resolved.has(assetId)) {
+      continue;
+    }
+    resolved.add(assetId);
+    for (const dependencyId of normalizeArray(assetMap.get(assetId)?.dependencies)) {
+      if (!resolved.has(dependencyId)) {
+        queue.push(dependencyId);
+      }
+    }
+  }
+  return [...resolved].sort();
+}
+
+function defaultInstallRoot(tool) {
+  if (tool === "codex") {
+    return path.join(os.homedir(), ".codex", "skills");
+  }
+  if (tool === "claude-code") {
+    return path.join(os.homedir(), ".claude", "skills");
+  }
+  return "";
+}
+
+function defaultProjectInstallRoot(projectRoot, tool) {
+  if (!projectRoot) {
+    return "";
+  }
+  if (tool === "claude-code") {
+    return path.resolve(projectRoot);
+  }
+  if (tool === "codex") {
+    return path.join(path.resolve(projectRoot), ".codex");
+  }
+  return "";
+}
+
+function usesNativeProjectLayout(tool) {
+  return tool === "claude-code" || tool === "codex";
+}
+
+function defaultLinkName() {
+  return "sswl-ai-coding-platform";
+}
+
+function loadToolInstallState(tool) {
+  const primary = readJson(path.join(GUI_INSTALL_DIR, `${tool}.json`), null);
+  if (primary) {
+    return primary;
+  }
+  return readJson(path.join(LEGACY_GUI_STATE_DIR, "installations", `${tool}.json`), null);
+}
+
+function loadActivationPlan(tool) {
+  const primary = readJson(path.join(PLAN_DIR, `${tool}.json`), null);
+  if (primary) {
+    return primary;
+  }
+  return readJson(path.join(LEGACY_GUI_STATE_DIR, "activation-plans", `${tool}.json`), null);
+}
+
+function computePlanId(tool, assetIds) {
+  return `custom-${tool}-${crypto.createHash("sha1").update(`${tool}:${assetIds.slice().sort().join(",")}`).digest("hex").slice(0, 10)}`;
+}
+
+function projectIdForRoot(projectRoot) {
+  return crypto.createHash("sha1").update(path.resolve(projectRoot)).digest("hex").slice(0, 12);
+}
+
+function getProjectStateFile(projectRoot) {
+  const projectId = projectIdForRoot(projectRoot);
+  return {
+    projectId,
+    filePath: path.join(PROJECTS_DIR, projectId, "project.json"),
+    legacyFilePath: path.join(LEGACY_GUI_STATE_DIR, "projects", projectId, "project.json")
+  };
+}
+
+function loadProjectState(projectRoot) {
+  if (!projectRoot) {
+    return null;
+  }
+  const resolvedRoot = path.resolve(projectRoot);
+  const { projectId, filePath, legacyFilePath } = getProjectStateFile(resolvedRoot);
+  return readJson(filePath, null) || readJson(legacyFilePath, {
+    project_id: projectId,
+    project_root: resolvedRoot,
+    tools: {}
+  });
+}
+
+function saveProjectState(projectRoot, data) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const { filePath } = getProjectStateFile(resolvedRoot);
+  writeJson(filePath, data);
+}
+
+function listChildDirectories(dirPath) {
+  if (!pathExists(dirPath)) {
+    return [];
+  }
+  return fs.readdirSync(dirPath, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+
+function listChildFiles(dirPath, extension = ".md") {
+  if (!pathExists(dirPath)) {
+    return [];
+  }
+  return fs.readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && (!extension || entry.name.endsWith(extension)))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function findPrimaryMarkdownFile(dirPath) {
+  const files = listChildFiles(dirPath, ".md").filter((name) => name !== "CLAUDE.md");
+  if (!files.length) {
+    return "";
+  }
+  const exactMatch = files.find((name) => path.basename(name, ".md") === path.basename(dirPath));
+  return path.join(dirPath, exactMatch || files[0]);
+}
+
+function copyOptionalRuntimeDirs(sourcePath, targetPath) {
+  for (const optionalName of ["assets", "references", "scripts"]) {
+    const optionalSource = path.join(sourcePath, optionalName);
+    if (pathExists(optionalSource)) {
+      fs.cpSync(optionalSource, path.join(targetPath, optionalName), { recursive: true });
+    }
+  }
+}
+
+function copySkillRuntime(sourcePath, targetPath) {
+  removePath(targetPath);
+  ensureDir(targetPath);
+  const skillFile = path.join(sourcePath, "SKILL.md");
+  if (!pathExists(skillFile)) {
+    throw new Error(`skill missing SKILL.md: ${sourcePath}`);
+  }
+  fs.copyFileSync(skillFile, path.join(targetPath, "SKILL.md"));
+  copyOptionalRuntimeDirs(sourcePath, targetPath);
+}
+
+function copyMarkdownAssetAsSkill(sourcePath, targetPath, assetType) {
+  const sourceFile = findPrimaryMarkdownFile(sourcePath);
+  if (!sourceFile) {
+    throw new Error(`${assetType} missing primary markdown file: ${sourcePath}`);
+  }
+  removePath(targetPath);
+  ensureDir(targetPath);
+  fs.copyFileSync(sourceFile, path.join(targetPath, "SKILL.md"));
+  copyOptionalRuntimeDirs(sourcePath, targetPath);
+}
+
+function renderCustomPackage({ repoDir, tool, assetIds, planId, runtimeRoot = "" }) {
+  const assets = readAssetCatalog(repoDir);
+  const assetMap = new Map(assets.map((asset) => [asset.id, asset]));
+  const packageDir = path.join(runtimeRoot || path.join(RUNTIME_DIR, tool), planId);
+  removePath(packageDir);
+  for (const dirName of ["skills", "commands", "agents", "plugins", "mcp-servers"]) {
+    ensureDir(path.join(packageDir, dirName));
+  }
+  for (const assetId of assetIds) {
+    const asset = assetMap.get(assetId);
+    if (!asset) {
+      continue;
+    }
+    const sourcePath = path.join(repoDir, asset.path);
+    let targetDir = "";
+    if (asset.type === "skill") {
+      targetDir = path.join(packageDir, "skills");
+    } else if (asset.type === "command") {
+      targetDir = tool === "codex" ? path.join(packageDir, "skills") : path.join(packageDir, "commands");
+    } else if (asset.type === "agent") {
+      targetDir = tool === "codex" ? path.join(packageDir, "skills") : path.join(packageDir, "agents");
+    } else if (asset.type === "plugin") {
+      targetDir = path.join(packageDir, "plugins");
+    } else if (asset.type === "mcp_server") {
+      targetDir = path.join(packageDir, "mcp-servers");
+    }
+    if (!targetDir) {
+      continue;
+    }
+    const targetPath = path.join(targetDir, path.basename(sourcePath));
+    if (asset.type === "skill") {
+      copySkillRuntime(sourcePath, targetPath);
+    } else if (tool === "codex" && (asset.type === "command" || asset.type === "agent")) {
+      copyMarkdownAssetAsSkill(sourcePath, targetPath, asset.type);
+    } else {
+      fs.cpSync(sourcePath, targetPath, { recursive: true });
+    }
+  }
+  writeJson(path.join(packageDir, "bundle-metadata.json"), {
+    tool,
+    plan_id: planId,
+    asset_ids: assetIds
+  });
+  return packageDir;
+}
+
+function applyLink({ targetLink, sourcePath }) {
+  ensureDir(path.dirname(targetLink));
+  removePath(targetLink);
+  try {
+    fs.symlinkSync(sourcePath, targetLink);
+  } catch (error) {
+    if (process.platform !== "win32" || !["EPERM", "EACCES", "UNKNOWN"].includes(error.code)) {
+      throw error;
+    }
+    fs.cpSync(sourcePath, targetLink, { recursive: true });
+  }
+}
+
+function claudeGlobalRootFromSkillsRoot(skillsRoot) {
+  return path.basename(skillsRoot) === "skills" ? path.dirname(skillsRoot) : path.join(os.homedir(), ".claude");
+}
+
+function installClaudeGlobalCommands({ packageDir, installRoot }, hooks = {}) {
+  const commandsSource = path.join(packageDir, "commands");
+  const commandNames = listChildDirectories(commandsSource);
+  if (!commandNames.length) {
+    return [];
+  }
+  const claudeRoot = claudeGlobalRootFromSkillsRoot(installRoot);
+  const commandsTarget = path.join(claudeRoot, "commands");
+  ensureDir(commandsTarget);
+  const createdLinks = [];
+  for (const commandName of commandNames) {
+    const sourceFile = findPrimaryMarkdownFile(path.join(commandsSource, commandName));
+    if (!sourceFile) {
+      continue;
+    }
+    const targetFile = path.join(commandsTarget, `${commandName}.md`);
+    hooks.onLog?.(`[apply] claude command ${targetFile} <- ${sourceFile}`);
+    removePath(targetFile);
+    fs.copyFileSync(sourceFile, targetFile);
+    createdLinks.push(targetFile);
+  }
+  return createdLinks;
+}
+
+function mcpNameFromManifest(manifest, serverDir) {
+  return manifest.mcp_name || manifest.server_name || manifest.id || path.basename(serverDir);
+}
+
+function buildMcpServerConfig(serverDir) {
+  const manifestPath = path.join(serverDir, "manifest.yaml");
+  if (!pathExists(manifestPath)) {
+    return null;
+  }
+  const manifest = parseSimpleYaml(manifestPath);
+  const name = mcpNameFromManifest(manifest, serverDir);
+  const serverEntry = manifest.server_entry || "server.js";
+  return {
+    name,
+    config: {
+      command: manifest.command || "node",
+      args: [path.join(serverDir, serverEntry)]
+    }
+  };
+}
+
+function updateProjectMcpConfig(projectRoot, mcpServerDirs) {
+  const mcpFile = path.join(projectRoot, ".mcp.json");
+  const current = readJson(mcpFile, {}) || {};
+  const next = { ...current, mcpServers: { ...(current.mcpServers || {}) } };
+  const managedNames = [];
+  for (const serverDir of mcpServerDirs) {
+    const serverConfig = buildMcpServerConfig(serverDir);
+    if (!serverConfig) {
+      continue;
+    }
+    next.mcpServers[serverConfig.name] = serverConfig.config;
+    managedNames.push(serverConfig.name);
+  }
+  if (!Object.keys(next.mcpServers).length) {
+    return { file: "", managedNames: [] };
+  }
+  writeJson(mcpFile, next);
+  return { file: mcpFile, managedNames: managedNames.sort() };
+}
+
+function removeManagedMcpConfig(projectRoot, managedNames = []) {
+  const mcpFile = path.join(projectRoot, ".mcp.json");
+  const current = readJson(mcpFile, null);
+  if (!current?.mcpServers) {
+    return;
+  }
+  for (const serverName of managedNames) {
+    delete current.mcpServers[serverName];
+  }
+  if (!Object.keys(current.mcpServers).length) {
+    delete current.mcpServers;
+  }
+  if (!Object.keys(current).length) {
+    removePath(mcpFile);
+  } else {
+    writeJson(mcpFile, current);
+  }
+}
+
+function copyMcpRuntime(packageDir, projectRoot, managedRoot, hooks = {}) {
+  const mcpServersSource = path.join(packageDir, "mcp-servers");
+  const mcpServerTargets = [];
+  if (pathExists(mcpServersSource)) {
+    const mcpServersTarget = path.join(managedRoot, "mcp-servers");
+    removePath(mcpServersTarget);
+    ensureDir(mcpServersTarget);
+    for (const serverName of listChildDirectories(mcpServersSource)) {
+      const sourceDir = path.join(mcpServersSource, serverName);
+      const targetDir = path.join(mcpServersTarget, serverName);
+      fs.cpSync(sourceDir, targetDir, { recursive: true });
+      mcpServerTargets.push(targetDir);
+    }
+    hooks.onLog?.(`[apply] project mcp-servers -> ${mcpServersTarget}`);
+  }
+  const mcpConfig = updateProjectMcpConfig(projectRoot, mcpServerTargets);
+  if (mcpConfig.file) {
+    hooks.onLog?.(`[apply] project mcp config -> ${mcpConfig.file}`);
+  }
+  return {
+    mcpConfigFile: mcpConfig.file,
+    mcpServerTargets,
+    managedMcpNames: mcpConfig.managedNames
+  };
+}
+
+function replaceManagedBlock(filePath, blockId, content) {
+  const startMarker = `<!-- ${blockId}:START -->`;
+  const endMarker = `<!-- ${blockId}:END -->`;
+  const existing = pathExists(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+  const block = content.trim() ? `${startMarker}\n${content.trim()}\n${endMarker}` : "";
+  const pattern = new RegExp(`\\n?${startMarker}[\\s\\S]*?${endMarker}\\n?`, "g");
+  let next = existing.replace(pattern, "").trimEnd();
+  if (block) {
+    next = next ? `${next}\n\n${block}\n` : `${block}\n`;
+  } else if (next) {
+    next = `${next}\n`;
+  }
+  if (next) {
+    fs.writeFileSync(filePath, next);
+  } else {
+    removePath(filePath);
+  }
+}
+
+function buildCodexProjectLayout(packageDir, projectRoot, assetIds, previousInstallState = null, hooks = {}) {
+  const managedRoot = path.join(projectRoot, ".codex", "sswl");
+  const skillsTarget = path.join(projectRoot, ".codex", "skills");
+  const commandsTarget = path.join(projectRoot, ".codex", "commands");
+  const agentsTarget = path.join(projectRoot, ".codex", "agents");
+  for (const targetSkillLink of previousInstallState?.target_skill_links || []) {
+    removePath(targetSkillLink);
+  }
+  removePath(skillsTarget);
+  ensureDir(skillsTarget);
+  const skillLinks = [];
+  for (const skillName of listChildDirectories(path.join(packageDir, "skills"))) {
+    const sourceDir = path.join(packageDir, "skills", skillName);
+    const targetDir = path.join(skillsTarget, skillName);
+    copySkillRuntime(sourceDir, targetDir);
+    skillLinks.push(targetDir);
+  }
+  hooks.onLog?.(`[apply] codex project skills -> ${skillsTarget}`);
+  removePath(path.join(projectRoot, ".codex", "prompts"));
+  removePath(commandsTarget);
+  removePath(agentsTarget);
+  const runtime = copyMcpRuntime(packageDir, projectRoot, managedRoot, hooks);
+  return {
+    target_links: [...skillLinks, managedRoot, ...(runtime.mcpConfigFile ? [runtime.mcpConfigFile] : [])],
+    target_skill_links: skillLinks,
+    managed_mcp_names: runtime.managedMcpNames || [],
+    target_link: path.join(projectRoot, ".codex"),
+    source_path: packageDir,
+    asset_ids: assetIds
+  };
+}
+
+function buildClaudeProjectMemory(packageDir, projectRoot, assetIds, previousInstallState = null, hooks = {}) {
+  const managedRoot = path.join(projectRoot, ".claude", "sswl");
+  const skillsTarget = path.join(projectRoot, ".claude", "skills");
+  const commandsTarget = path.join(projectRoot, ".claude", "commands");
+  const agentsTarget = path.join(projectRoot, ".claude", "agents");
+  const memoryDir = path.join(managedRoot, "memory");
+  for (const targetSkillLink of previousInstallState?.target_skill_links || []) {
+    removePath(targetSkillLink);
+  }
+  ensureDir(skillsTarget);
+  const skillLinks = [];
+  for (const skillName of listChildDirectories(path.join(packageDir, "skills"))) {
+    const sourceDir = path.join(packageDir, "skills", skillName);
+    const targetDir = path.join(skillsTarget, skillName);
+    hooks.onLog?.(`[apply] claude project skill ${targetDir} <- ${sourceDir}`);
+    copySkillRuntime(sourceDir, targetDir);
+    skillLinks.push(targetDir);
+  }
+  removePath(commandsTarget);
+  ensureDir(commandsTarget);
+  for (const commandName of listChildDirectories(path.join(packageDir, "commands"))) {
+    const sourceFile = findPrimaryMarkdownFile(path.join(packageDir, "commands", commandName));
+    if (sourceFile) {
+      fs.copyFileSync(sourceFile, path.join(commandsTarget, `${commandName}.md`));
+    }
+  }
+  hooks.onLog?.(`[apply] claude project commands -> ${commandsTarget}`);
+  removePath(agentsTarget);
+  ensureDir(agentsTarget);
+  for (const agentName of listChildDirectories(path.join(packageDir, "agents"))) {
+    const sourceFile = findPrimaryMarkdownFile(path.join(packageDir, "agents", agentName));
+    if (sourceFile) {
+      fs.copyFileSync(sourceFile, path.join(agentsTarget, `${agentName}.md`));
+    }
+  }
+  hooks.onLog?.(`[apply] claude project agents -> ${agentsTarget}`);
+  removePath(memoryDir);
+  const sections = [];
+  for (const pluginName of listChildDirectories(path.join(packageDir, "plugins"))) {
+    const sourceFile = path.join(packageDir, "plugins", pluginName, "CLAUDE.md");
+    if (!pathExists(sourceFile)) {
+      continue;
+    }
+    ensureDir(memoryDir);
+    fs.copyFileSync(sourceFile, path.join(memoryDir, `${pluginName}.md`));
+    sections.push(`- @.claude/sswl/memory/${pluginName}.md`);
+  }
+  const runtime = copyMcpRuntime(packageDir, projectRoot, managedRoot, hooks);
+  const memoryBlock = sections.length
+    ? ["# SSWL Managed Imports", "", "以下内容由 SSWL AI Manager 自动维护，请勿手工编辑此区块内的导入列表。", "", ...sections].join("\n")
+    : "";
+  replaceManagedBlock(path.join(projectRoot, "CLAUDE.md"), "SSWL-MANAGED-IMPORTS", memoryBlock);
+  if (!sections.length && !pathExists(path.join(managedRoot, "mcp-servers"))) {
+    removePath(managedRoot);
+  }
+  return {
+    target_links: [
+      ...skillLinks,
+      commandsTarget,
+      agentsTarget,
+      ...(runtime.mcpConfigFile ? [runtime.mcpConfigFile] : []),
+      path.join(projectRoot, "CLAUDE.md"),
+      managedRoot
+    ],
+    target_skill_links: skillLinks,
+    managed_mcp_names: runtime.managedMcpNames || [],
+    target_link: path.join(projectRoot, ".claude"),
+    source_path: packageDir,
+    asset_ids: assetIds
+  };
+}
+
+function removeClaudeProjectLayout(projectRoot, installState = null) {
+  for (const targetSkillLink of installState?.target_skill_links || []) {
+    removePath(targetSkillLink);
+  }
+  removePath(path.join(projectRoot, ".claude", "commands"));
+  removePath(path.join(projectRoot, ".claude", "agents"));
+  removePath(path.join(projectRoot, ".claude", "sswl"));
+  removeManagedMcpConfig(projectRoot, installState?.managed_mcp_names || []);
+  replaceManagedBlock(path.join(projectRoot, "CLAUDE.md"), "SSWL-MANAGED-IMPORTS", "");
+}
+
+function removeCodexProjectLayout(projectRoot, installState = null) {
+  for (const targetSkillLink of installState?.target_skill_links || []) {
+    removePath(targetSkillLink);
+  }
+  removePath(path.join(projectRoot, ".codex"));
+  removeManagedMcpConfig(projectRoot, installState?.managed_mcp_names || []);
+}
+
+function applyInstallLayout({ tool, installRoot, linkName, linkTarget, packageDir, sourcePath }, hooks = {}) {
+  if ((tool === "claude-code" || tool === "codex") && linkTarget === "skills") {
+    const skillsRoot = path.join(packageDir, "skills");
+    const skillNames = listChildDirectories(skillsRoot);
+    if (!skillNames.length) {
+      throw new Error(`${tool} 安装包中没有可链接的 skill 目录`);
+    }
+    const createdLinks = [];
+    ensureDir(installRoot);
+    const legacyBundleLink = path.join(installRoot, linkName);
+    if (pathExists(legacyBundleLink)) {
+      hooks.onLog?.(`[apply] remove legacy ${tool} bundle link ${legacyBundleLink}`);
+      removePath(legacyBundleLink);
+    }
+    for (const skillName of skillNames) {
+      const targetLink = path.join(installRoot, skillName);
+      const skillSource = path.join(skillsRoot, skillName);
+      hooks.onLog?.(`[apply] ${tool} skill link ${targetLink} -> ${skillSource}`);
+      applyLink({ targetLink, sourcePath: skillSource });
+      createdLinks.push(targetLink);
+    }
+    if (tool === "claude-code") {
+      createdLinks.push(...installClaudeGlobalCommands({ packageDir, installRoot }, hooks));
+    }
+    return {
+      target_links: createdLinks,
+      target_link: "",
+      source_path: packageDir
+    };
+  }
+  const targetLink = path.join(installRoot, linkName);
+  hooks.onLog?.(`[apply] link ${targetLink} -> ${sourcePath}`);
+  applyLink({ targetLink, sourcePath });
+  return {
+    target_links: [targetLink],
+    target_link: targetLink,
+    source_path: sourcePath
+  };
+}
+
+function buildGlobalToolState(tool) {
+  const installState = loadToolInstallState(tool);
+  const plan = loadActivationPlan(tool);
+  const detected = detectInstalledTool(tool);
+  return {
+    tool,
+    scope: "global",
+    manageable: true,
+    detected_installed: detected.installed,
+    detected_command_path: detected.command_path,
+    detected_path: detected.detected_path,
+    install_root: installState?.install_root || defaultInstallRoot(tool),
+    link_name: installState?.link_name || defaultLinkName(),
+    link_target: installState?.link_target || "skills",
+    active_plan_id: installState?.active_plan_id || "",
+    enabled: Boolean(installState),
+    mode: installState?.mode || "managed",
+    last_applied_at: installState?.last_applied_at || "",
+    applied_repo_commit: installState?.applied_repo_commit || "",
+    installed_asset_ids: installState?.installed_asset_ids || plan?.asset_ids || [],
+    asset_snapshots: installState?.asset_snapshots || {},
+    selected_asset_ids: plan?.selected_asset_ids || installState?.selected_asset_ids || installState?.installed_asset_ids || []
+  };
+}
+
+function buildProjectToolState(tool, projectState) {
+  const record = projectState?.tools?.[tool] || {};
+  const installState = record.install || null;
+  const plan = record.plan || null;
+  const detected = detectInstalledTool(tool);
+  const defaultInstallRootForScope = defaultProjectInstallRoot(projectState?.project_root || "", tool);
+  return {
+    tool,
+    scope: "project",
+    manageable: true,
+    detected_installed: detected.installed,
+    detected_command_path: detected.command_path,
+    detected_path: detected.detected_path,
+    install_root: usesNativeProjectLayout(tool) ? defaultInstallRootForScope : (installState?.install_root || defaultInstallRootForScope),
+    link_name: installState?.link_name || defaultLinkName(),
+    link_target: installState?.link_target || "skills",
+    active_plan_id: installState?.active_plan_id || "",
+    enabled: Boolean(installState),
+    mode: installState?.mode || "project-config",
+    last_applied_at: installState?.last_applied_at || "",
+    applied_repo_commit: installState?.applied_repo_commit || "",
+    installed_asset_ids: installState?.installed_asset_ids || plan?.asset_ids || [],
+    asset_snapshots: installState?.asset_snapshots || {},
+    selected_asset_ids: plan?.selected_asset_ids || installState?.selected_asset_ids || installState?.installed_asset_ids || [],
+    inherit_global: Boolean(plan?.inherit_global)
+  };
+}
+
+function getAppState({ repoDir = "", projectRoot = "" } = {}) {
+  ensureRuntimeDirs();
+  const settings = loadSettings();
+  const resolvedRepoDir = resolveRepoRoot(repoDir || settings.repo_dir || REPO_DIR);
+  const resolvedProjectRoot = projectRoot || settings.last_project_root || "";
+  const repoStatus = getRepoStatus(resolvedRepoDir);
+  const assets = repoStatus.exists && looksLikeRepoRoot(resolvedRepoDir) ? readAssetCatalog(resolvedRepoDir) : [];
+  const profiles = repoStatus.exists && looksLikeRepoRoot(resolvedRepoDir) ? parseProfiles(resolvedRepoDir) : [];
+  const projectState = resolvedProjectRoot ? loadProjectState(resolvedProjectRoot) : null;
+  return {
+    repo: repoStatus,
+    settings: {
+      repo_url: settings.repo_url || DEFAULT_REPO_URL,
+      repo_dir: resolvedRepoDir,
+      asset_repo_dir: resolvedRepoDir,
+      asset_source_mode: "git",
+      current_scope: settings.current_scope || "project",
+      last_project_root: resolvedProjectRoot
+    },
+    paths: {
+      app_root: APP_ROOT,
+      repo_dir: resolvedRepoDir,
+      runtime_dir: RUNTIME_DIR,
+      state_dir: CLI_STATE_DIR
+    },
+    tools: SUPPORTED_TOOLS.map(buildGlobalToolState),
+    project: resolvedProjectRoot ? {
+      project_id: projectState?.project_id || projectIdForRoot(resolvedProjectRoot),
+      project_root: resolvedProjectRoot,
+      exists: pathExists(resolvedProjectRoot),
+      tools: SUPPORTED_TOOLS.map((tool) => buildProjectToolState(tool, projectState))
+    } : null,
+    profiles,
+    assets
+  };
+}
+
+async function applyActivationPlan({
+  tool,
+  assetIds = [],
+  selectedAssetIds = [],
+  installRoot = "",
+  linkName = defaultLinkName(),
+  linkTarget = "skills",
+  repoDir = "",
+  repoUrl = "",
+  planName = "",
+  profileId = "",
+  selectionMode = "",
+  scope = "global",
+  projectRoot = "",
+  inheritGlobal = true
+} = {}, hooks = {}) {
+  ensureRuntimeDirs();
+  const currentSettings = loadSettings();
+  const requestedRepoUrl = repoUrl ? String(repoUrl).trim() : currentSettings.repo_url || DEFAULT_REPO_URL;
+  await assertEnterpriseReachable({ repoUrl: requestedRepoUrl });
+  const requestedRepoDir = resolveRepoRoot(repoDir || currentSettings.repo_dir || REPO_DIR);
+  const settings = saveSettings({
+    repo_url: requestedRepoUrl,
+    repo_dir: requestedRepoDir
+  });
+  const resolvedRepoDir = settings.repo_dir;
+  const resolvedRepoUrl = settings.repo_url;
+  if (!SUPPORTED_TOOLS.includes(tool)) {
+    throw new Error(`unsupported tool: ${tool}`);
+  }
+  if (!["global", "project"].includes(scope)) {
+    throw new Error(`unsupported scope: ${scope}`);
+  }
+  if (!assetIds.length) {
+    throw new Error("至少选择一个资产后再应用");
+  }
+  let resolvedProjectRoot = "";
+  let projectState = null;
+  if (scope === "project") {
+    if (!projectRoot) {
+      throw new Error("项目级安装必须提供项目目录");
+    }
+    resolvedProjectRoot = path.resolve(projectRoot);
+    ensureDir(resolvedProjectRoot);
+    projectState = loadProjectState(resolvedProjectRoot);
+    saveSettings({ last_project_root: resolvedProjectRoot, current_scope: "project" });
+  } else {
+    saveSettings({ current_scope: "global" });
+  }
+  if (!looksLikeRepoRoot(resolvedRepoDir)) {
+    if (!fs.existsSync(path.join(resolvedRepoDir, ".git"))) {
+      hooks.onLog?.("[apply] 本地仓库不存在，先执行同步");
+      await syncRepo({ repoDir: resolvedRepoDir, repoUrl: resolvedRepoUrl }, hooks);
+      return applyActivationPlan({
+        tool,
+        assetIds,
+        selectedAssetIds,
+        installRoot,
+        linkName,
+        linkTarget,
+        repoDir: resolvedRepoDir,
+        repoUrl: resolvedRepoUrl,
+        planName,
+        profileId,
+        selectionMode,
+        scope,
+        projectRoot: resolvedProjectRoot,
+        inheritGlobal
+      }, hooks);
+    }
+    throw new Error(`资产源目录不是控制面仓库根目录：${resolvedRepoDir}`);
+  }
+  const resolvedInstallRoot = scope === "project" && usesNativeProjectLayout(tool)
+    ? defaultProjectInstallRoot(resolvedProjectRoot, tool)
+    : (installRoot || (scope === "project" ? defaultProjectInstallRoot(resolvedProjectRoot, tool) : defaultInstallRoot(tool)));
+  if (!resolvedInstallRoot) {
+    throw new Error(`tool '${tool}' 缺少安装目录，请手工指定`);
+  }
+  hooks.onProgress?.({ percent: 18, stage: "build", detail: "读取资产并生成组合包" });
+  const assets = readAssetCatalog(resolvedRepoDir);
+  const globalToolState = buildGlobalToolState(tool);
+  const requestedAssetIdSet = [...new Set(selectedAssetIds.length ? selectedAssetIds : assetIds)].sort();
+  const scopedInputIds = scope === "project" && inheritGlobal
+    ? [...new Set([...(globalToolState.installed_asset_ids || []), ...requestedAssetIdSet])].sort()
+    : requestedAssetIdSet;
+  const uniqueAssetIds = resolveAssetDependencySet(assets, scopedInputIds);
+  const assetSnapshots = Object.fromEntries(
+    assets
+      .filter((asset) => uniqueAssetIds.includes(asset.id))
+      .map((asset) => [asset.id, {
+        id: asset.id,
+        name: asset.name,
+        version: asset.version || "",
+        type: asset.type,
+        domain: asset.domain
+      }])
+  );
+  const planId = computePlanId(tool, uniqueAssetIds);
+  const packageBaseDir = scope === "project"
+    ? path.join(RUNTIME_DIR, "projects", projectIdForRoot(resolvedProjectRoot), tool)
+    : path.join(RUNTIME_DIR, tool);
+  ensureDir(packageBaseDir);
+  const packageDir = renderCustomPackage({
+    repoDir: resolvedRepoDir,
+    tool,
+    assetIds: uniqueAssetIds,
+    planId,
+    runtimeRoot: packageBaseDir
+  });
+  const sourcePath = linkTarget === "package" ? packageDir : path.join(packageDir, "skills");
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`source path not found: ${sourcePath}`);
+  }
+  hooks.onProgress?.({ percent: 58, stage: "link", detail: "写入安装链接" });
+  let linkResult;
+  if (tool === "claude-code" && scope === "project") {
+    linkResult = buildClaudeProjectMemory(packageDir, resolvedProjectRoot, uniqueAssetIds, projectState?.tools?.[tool]?.install || null, hooks);
+  } else if (tool === "codex" && scope === "project") {
+    linkResult = buildCodexProjectLayout(packageDir, resolvedProjectRoot, uniqueAssetIds, projectState?.tools?.[tool]?.install || null, hooks);
+  } else {
+    linkResult = applyInstallLayout({
+      tool,
+      installRoot: resolvedInstallRoot,
+      linkName,
+      linkTarget,
+      packageDir,
+      sourcePath
+    }, hooks);
+  }
+  const now = new Date().toISOString();
+  const plan = {
+    id: planId,
+    tool,
+    scope,
+    name: planName || planId,
+    profile_id: profileId || "",
+    selection_mode: selectionMode || (profileId ? "profile" : "custom"),
+    selected_asset_ids: requestedAssetIdSet,
+    source_type: "git",
+    source_ref: getRepoStatus(resolvedRepoDir).commit,
+    asset_ids: uniqueAssetIds,
+    inherit_global: Boolean(scope === "project" && inheritGlobal),
+    project_root: resolvedProjectRoot,
+    created_at: now,
+    updated_at: now
+  };
+  const installState = {
+    tool,
+    scope,
+    mode: "git",
+    active_plan_id: planId,
+    install_root: resolvedInstallRoot,
+    link_name: linkName,
+    link_target: linkTarget,
+    target_link: linkResult.target_link,
+    target_links: linkResult.target_links,
+    target_skill_links: linkResult.target_skill_links || [],
+    managed_mcp_names: linkResult.managed_mcp_names || [],
+    source_path: linkResult.source_path,
+    repo_dir: resolvedRepoDir,
+    repo_url: resolvedRepoUrl,
+    applied_repo_commit: getRepoStatus(resolvedRepoDir).commit,
+    installed_asset_ids: uniqueAssetIds,
+    selected_asset_ids: requestedAssetIdSet,
+    asset_snapshots: assetSnapshots,
+    project_root: resolvedProjectRoot,
+    inherit_global: Boolean(scope === "project" && inheritGlobal),
+    last_applied_at: now
+  };
+  if (scope === "project") {
+    projectState.tools[tool] = { plan, install: installState };
+    saveProjectState(resolvedProjectRoot, projectState);
+  } else {
+    writeJson(path.join(PLAN_DIR, `${tool}.json`), plan);
+    writeJson(path.join(GUI_INSTALL_DIR, `${tool}.json`), installState);
+  }
+  hooks.onProgress?.({ percent: 84, stage: "state", detail: "写入本地状态" });
+  hooks.onProgress?.({ percent: 100, stage: "done", detail: `${tool} 安装完成` });
+  hooks.onLog?.(`[apply] completed ${tool}`);
+  return getAppState({ repoDir: resolvedRepoDir, projectRoot: resolvedProjectRoot });
+}
+
+function disableTool({ tool, scope = "global", projectRoot = "" } = {}, hooks = {}) {
+  if (!SUPPORTED_TOOLS.includes(tool)) {
+    throw new Error(`unsupported tool: ${tool}`);
+  }
+  hooks.onProgress?.({ percent: 10, stage: "prepare", detail: `准备卸载 ${tool}` });
+  const installState = scope === "project"
+    ? loadProjectState(projectRoot)?.tools?.[tool]?.install || null
+    : loadToolInstallState(tool);
+  if (!installState) {
+    hooks.onProgress?.({ percent: 100, stage: "done", detail: `${tool} 无安装记录` });
+    return getAppState({ projectRoot });
+  }
+  for (const targetLink of installState.target_links || (installState.target_link ? [installState.target_link] : [])) {
+    if (!(scope === "project" && ["claude-code", "codex"].includes(tool))) {
+      removePath(targetLink);
+    }
+  }
+  if (scope === "project") {
+    const projectState = loadProjectState(projectRoot);
+    if (projectState?.tools) {
+      delete projectState.tools[tool];
+      saveProjectState(projectRoot, projectState);
+    }
+    if (tool === "claude-code") {
+      removeClaudeProjectLayout(projectRoot, installState);
+    } else {
+      removeCodexProjectLayout(projectRoot, installState);
+    }
+    removePath(path.join(RUNTIME_DIR, "projects", projectIdForRoot(projectRoot), tool));
+  } else {
+    fs.rmSync(path.join(PLAN_DIR, `${tool}.json`), { force: true });
+    fs.rmSync(path.join(GUI_INSTALL_DIR, `${tool}.json`), { force: true });
+    removePath(path.join(RUNTIME_DIR, tool));
+  }
+  hooks.onProgress?.({ percent: 100, stage: "done", detail: `${tool} 已卸载` });
+  return getAppState({ projectRoot });
+}
+
+async function updateProjectInstallations({ projectRoot = "", repoDir = "", repoUrl = "", tool = "" } = {}, hooks = {}) {
+  const resolvedProjectRoot = projectRoot ? path.resolve(projectRoot) : "";
+  if (!resolvedProjectRoot) {
+    throw new Error("项目更新必须提供项目目录");
+  }
+  const projectState = loadProjectState(resolvedProjectRoot);
+  const targetTools = tool ? [tool] : Object.keys(projectState?.tools || {});
+  if (!targetTools.length) {
+    throw new Error("当前项目没有可更新的安装记录，请先执行项目安装");
+  }
+  const currentSettings = loadSettings();
+  const requestedRepoUrl = repoUrl ? String(repoUrl).trim() : currentSettings.repo_url || DEFAULT_REPO_URL;
+  const requestedRepoDir = resolveRepoRoot(repoDir || currentSettings.repo_dir || REPO_DIR);
+  await syncRepo({ repoDir: requestedRepoDir, repoUrl: requestedRepoUrl }, hooks);
+  let nextState = getAppState({ repoDir: requestedRepoDir, projectRoot: resolvedProjectRoot });
+  for (const currentTool of targetTools) {
+    const record = loadProjectState(resolvedProjectRoot)?.tools?.[currentTool] || null;
+    const plan = record?.plan || null;
+    const install = record?.install || null;
+    if (!plan || !install) {
+      continue;
+    }
+    const liveProfiles = (nextState.profiles || []).filter((profile) => profile.supported_tools.includes(currentTool));
+    const profile = plan.profile_id ? liveProfiles.find((item) => item.id === plan.profile_id) : null;
+    const selectedAssetIds = profile?.asset_ids?.length
+      ? profile.asset_ids
+      : Array.isArray(plan.selected_asset_ids) && plan.selected_asset_ids.length
+        ? plan.selected_asset_ids
+        : Array.isArray(install.selected_asset_ids) && install.selected_asset_ids.length
+          ? install.selected_asset_ids
+          : Array.isArray(plan.asset_ids)
+            ? plan.asset_ids
+            : install.installed_asset_ids || [];
+    nextState = await applyActivationPlan({
+      tool: currentTool,
+      assetIds: selectedAssetIds,
+      selectedAssetIds,
+      installRoot: install.install_root || "",
+      linkName: install.link_name || defaultLinkName(),
+      linkTarget: install.link_target || "skills",
+      repoDir: requestedRepoDir,
+      repoUrl: requestedRepoUrl,
+      planName: plan.name || install.active_plan_id || "project-update",
+      profileId: plan.profile_id || "",
+      selectionMode: plan.selection_mode || "",
+      scope: "project",
+      projectRoot: resolvedProjectRoot,
+      inheritGlobal: Boolean(plan.inherit_global ?? install.inherit_global)
+    }, hooks);
+  }
+  return nextState;
+}
+
+async function getEnterpriseNetworkStatus() {
+  const settings = loadSettings();
+  return checkEnterpriseReachability({ repoUrl: settings.repo_url || DEFAULT_REPO_URL });
+}
+
+module.exports = {
+  DEFAULT_REPO_URL,
+  SUPPORTED_TOOLS,
+  resolveRepoRoot,
+  updateSettings,
+  syncRepo,
+  getAppState,
+  applyActivationPlan,
+  updateProjectInstallations,
+  disableTool,
+  getEnterpriseNetworkStatus
+};