@hcmai/cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -4186,11 +4186,16 @@ import {
   fromAxiosError as fromAxiosError12,
   uploadDocument as uploadDocument2
 } from "@hcmai/sdk";
+var DEFAULT_UPLOAD_CATEGORY = "attachment";
 async function uploadCommand(filePath, args) {
   try {
     const ctx = await getActiveAuthContextFromCli(args);
     const client3 = HcmClient14.fromAuthContext(ctx);
-    const meta2 = await uploadDocument2(client3.raw(), filePath);
+    const meta2 = await uploadDocument2(
+      client3.raw(),
+      filePath,
+      args.category ?? DEFAULT_UPLOAD_CATEGORY
+    );
     const fmt = args.output ?? "json";
     if (fmt !== "json") {
       process.stdout.write(
@@ -4220,10 +4225,18 @@ init_exit();
 import { promises as fsp } from "fs";
 import os2 from "os";
 import path2 from "path";
+import { createHash } from "crypto";
 import {
   createHttpClient as createHttpClient2,
   fetchSkillCatalog,
   fetchSkillMarkdown,
+  fetchSkillReference,
+  resolveChironBase,
+  assertSafeSkillId,
+  assertSafeReferencePath,
+  normalizeReferences,
+  parseSkillRequirements,
+  resolveSkillInstallOrder,
   matchSkills,
   filterByStage,
   formatObject as formatObject13,
@@ -4234,6 +4247,10 @@ import {
   CliError as CliError14,
   CliErrorCode as CliErrorCode13
 } from "@hcmai/sdk";
+var SKILLS_STATE_FILE = ".hcm-skills.json";
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
 async function resolveEndpoint(args) {
   if (args.endpoint) return args.endpoint.replace(/\/+$/, "");
   const g = await loadGlobalConfig6();
@@ -4247,13 +4264,45 @@ async function resolveEndpoint(args) {
   }
   return env2.endpoint.replace(/\/+$/, "");
 }
-function anonHttp(endpoint) {
-  return createHttpClient2({
+async function exists(target) {
+  try {
+    await fsp.stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectTarget(cwd) {
+  if (await exists(path2.join(cwd, ".claude"))) return "claude";
+  if (await exists(path2.join(cwd, "AGENTS.md"))) return "codex";
+  if (await exists(path2.join(cwd, ".codex"))) return "codex";
+  return void 0;
+}
+async function resolveInstallLayout(args, cwd = process.cwd()) {
+  const requested = args.target && args.target !== "auto" ? args.target : void 0;
+  const target = requested ?? await detectTarget(cwd) ?? "claude";
+  if (target === "codex") {
+    const root = args.global ? path2.join(os2.homedir(), ".codex") : cwd;
+    return {
+      target,
+      baseDir: args.dir ? path2.resolve(args.dir) : path2.join(root, "hcm-skills"),
+      agentsFile: path2.join(root, "AGENTS.md")
+    };
+  }
+  return {
+    target,
+    baseDir: args.dir ? path2.resolve(args.dir) : args.global ? path2.join(os2.homedir(), ".claude", "skills") : path2.join(cwd, ".claude", "skills")
+  };
+}
+async function chironClient(args) {
+  const endpoint = await resolveEndpoint(args);
+  const http = createHttpClient2({
     endpoint,
     getAccessToken: async () => null,
     onRefresh: async () => {
     }
   });
+  return { http, endpoint, base: await resolveChironBase(http) };
 }
 function fail3(e, args) {
   const err = e;
@@ -4266,8 +4315,8 @@ function fail3(e, args) {
 }
 async function skillsListCommand(keyword, args) {
   try {
-    const endpoint = await resolveEndpoint(args);
-    const manifest2 = await fetchSkillCatalog(anonHttp(endpoint));
+    const { http, endpoint, base } = await chironClient(args);
+    const manifest2 = await fetchSkillCatalog(http, base);
     const fmt = args.output ?? "table";
     let cats = manifest2.categories ?? [];
     if (args.category) cats = cats.filter((c) => c.key === args.category);
@@ -4337,8 +4386,8 @@ async function skillsListCommand(keyword, args) {
 }
 async function skillsShowCommand(id, args) {
   try {
-    const endpoint = await resolveEndpoint(args);
-    const md = await fetchSkillMarkdown(anonHttp(endpoint), id);
+    const { http, base } = await chironClient(args);
+    const md = await fetchSkillMarkdown(http, id, base);
     process.stdout.write(md.endsWith("\n") ? md : md + "\n");
     process.exit(0);
   } catch (e) {
@@ -4347,52 +4396,493 @@ async function skillsShowCommand(id, args) {
 }
 async function skillsInstallCommand(id, args) {
   try {
-    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) {
+    assertSafeSkillId(id);
+    const layout = await resolveInstallLayout(args);
+    let documents;
+    let endpoint;
+    let base;
+    let manifest2;
+    if (args.from) {
+      documents = await resolveLocalSkillDocuments(path2.resolve(args.from), id);
+    } else {
+      const client3 = await chironClient(args);
+      endpoint = client3.endpoint;
+      base = client3.base;
+      manifest2 = await fetchSkillCatalog(client3.http, base);
+      const order = resolveSkillInstallOrder(manifest2, id);
+      documents = await Promise.all(
+        order.map((skill) => fetchSkillDocument(client3.http, skill, endpoint, base))
+      );
+    }
+    const result = await installSkillDocuments(documents, id, layout.baseDir, Boolean(args.force), {
+      endpoint,
+      base,
+      target: layout.target
+    });
+    const agents = layout.agentsFile ? await syncAgentsIndex(layout, manifest2) : void 0;
+    const fmt = args.output ?? "table";
+    if (fmt === "json" || fmt === "yaml") {
+      process.stdout.write(formatObject13({ ...result, target_agent: layout.target, agentsFile: layout.agentsFile, agents }, { format: fmt }) + "\n");
+    } else {
+      process.stdout.write(`\u2705 ${id} \u2192 ${result.target}
+`);
+      if (result.installed.length > 1) {
+        process.stdout.write(`   \u5DF2\u5B89\u88C5 ${result.installed.join(" \u2192 ")}
+`);
+      }
+      if (result.unchanged.length > 0) {
+        process.stdout.write(`   \u5DF2\u5B58\u5728\u4E14\u7248\u672C\u4E00\u81F4 ${result.unchanged.join(", ")}
+`);
+      }
+      const referenceCount = documents.reduce((n, d) => n + (d.references?.length ?? 0), 0);
+      if (referenceCount > 0) {
+        process.stdout.write(`   \u53C2\u8003\u6587\u4EF6 ${referenceCount} \u4E2A\uFF08references/ \u4E0B\uFF09
+`);
+      }
+      if (layout.agentsFile) {
+        process.stdout.write(`   \u5DF2${agents === "created" ? "\u521B\u5EFA" : "\u66F4\u65B0"} ${layout.agentsFile} \u91CC\u7684\u6280\u80FD\u7D22\u5F15\uFF08Codex \u8BFB\u8FD9\u91CC\uFF09
+`);
+      }
+      process.stdout.write(`   \u6765\u6E90 ${result.source}
+`);
+      process.stdout.write(`   \u4EA7\u54C1\u66F4\u65B0\u540E\u8DD1 hcm skills update \u5347\u7EA7
+`);
+    }
+    process.exit(0);
+  } catch (e) {
+    fail3(e, args);
+  }
+}
+async function fetchSkillDocument(http, skill, endpoint, base) {
+  const relatives = normalizeReferences(skill.references, skill.id);
+  const references = await Promise.all(relatives.map(async (relative2) => ({
+    path: relative2,
+    content: await fetchSkillReference(http, skill.id, relative2, base)
+  })));
+  return {
+    id: skill.id,
+    markdown: await fetchSkillMarkdown(http, skill.id, base),
+    source: `${endpoint}${base}/skills/${skill.id}.md`,
+    references
+  };
+}
+async function syncAgentsIndex(layout, manifest2) {
+  if (!layout.agentsFile) return void 0;
+  const state = await readSkillsState(layout.baseDir);
+  if (!state) return void 0;
+  const catalog = /* @__PURE__ */ new Map();
+  for (const category of manifest2?.categories ?? []) {
+    for (const skill of category.skills ?? []) catalog.set(skill.id, skill);
+  }
+  const agentsDir = path2.dirname(layout.agentsFile);
+  const entries = Object.keys(state.skills).sort().map((id) => {
+    const known = catalog.get(id);
+    const absolute = path2.join(layout.baseDir, id, "SKILL.md");
+    let relative2 = path2.relative(agentsDir, absolute);
+    if (!relative2.startsWith(".")) relative2 = `./${relative2}`;
+    return {
+      id,
+      title: known?.title ?? id,
+      description: known?.description ?? "",
+      relativePath: relative2.split(path2.sep).join("/")
+    };
+  });
+  return upsertAgentsBlock(layout.agentsFile, renderAgentsBlock(entries));
+}
+async function resolveLocalSkillDocuments(sourceRoot, targetId) {
+  assertSafeSkillId(targetId);
+  const state = /* @__PURE__ */ new Map();
+  const pathStack = [];
+  const order = [];
+  const visit = async (id, requiredBy) => {
+    const current = state.get(id);
+    if (current === "done") return;
+    if (current === "visiting") {
+      const start = pathStack.indexOf(id);
+      throw invalid(`\u6280\u80FD\u4F9D\u8D56\u5B58\u5728\u73AF: ${[...pathStack.slice(Math.max(0, start)), id].join(" -> ")}`);
+    }
+    assertSafeSkillId(id);
+    const local = path2.join(sourceRoot, id, "SKILL.md");
+    let markdown;
+    try {
+      markdown = await fsp.readFile(local, "utf8");
+    } catch (cause) {
+      if (cause?.code === "ENOENT") {
+        throw invalid(requiredBy ? `\u672C\u5730\u6280\u80FD ${requiredBy} \u4F9D\u8D56\u4E0D\u5B58\u5728: ${id}\uFF08${local}\uFF09` : `\u672C\u5730\u76EE\u5F55\u91CC\u6CA1\u6709 ${id}/SKILL.md\uFF1A${path2.join(sourceRoot, id)}`);
+      }
+      throw cause;
+    }
+    if (!markdown.trim()) throw invalid(`\u6280\u80FD ${id} \u5185\u5BB9\u4E3A\u7A7A`);
+    state.set(id, "visiting");
+    pathStack.push(id);
+    const document = {
+      id,
+      markdown,
+      source: local,
+      references: await readLocalReferences(path2.join(sourceRoot, id))
+    };
+    for (const required of parseSkillRequirements(markdown, id)) {
+      await visit(required, id);
+    }
+    pathStack.pop();
+    state.set(id, "done");
+    order.push(document);
+  };
+  await visit(targetId);
+  return order;
+}
+async function readSkillsState(baseDir) {
+  try {
+    const raw = await fsp.readFile(path2.join(baseDir, SKILLS_STATE_FILE), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !parsed.skills) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function writeSkillsState(baseDir, state) {
+  await fsp.mkdir(baseDir, { recursive: true });
+  const file = path2.join(baseDir, SKILLS_STATE_FILE);
+  const temp = `${file}.${process.pid}.tmp`;
+  await fsp.writeFile(temp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  await fsp.rename(temp, file);
+}
+var AGENTS_BLOCK_BEGIN = "<!-- hcm-skills:begin -->";
+var AGENTS_BLOCK_END = "<!-- hcm-skills:end -->";
+function renderAgentsBlock(entries) {
+  const lines = [
+    AGENTS_BLOCK_BEGIN,
+    "## HCMnext \u4EA4\u4ED8\u6280\u80FD\uFF08\u7531 `hcm skills install` \u7EF4\u62A4\uFF0C\u52FF\u624B\u5DE5\u7F16\u8F91\u672C\u5757\uFF09",
+    "",
+    "\u9047\u5230\u4E0B\u9762\u8FD9\u4E9B\u6D3B\u513F\uFF0C**\u5148\u8BFB\u5BF9\u5E94\u6587\u4EF6\u518D\u52A8\u624B**\u2014\u2014\u91CC\u9762\u662F\u8FD9\u5957\u4EA7\u54C1\u7684\u6B63\u786E\u505A\u6CD5\uFF0C",
+    "\u7167\u7740\u505A\u4E0D\u7528\u7FFB\u6E90\u7801\uFF0C\u4E5F\u4E0D\u7528\u731C API\u3002",
+    ""
+  ];
+  for (const e of entries) {
+    lines.push(`- \`${e.relativePath}\` \u2014 **${e.title}**`);
+    if (e.description) lines.push(`  ${e.description}`);
+  }
+  lines.push("", AGENTS_BLOCK_END);
+  return lines.join("\n");
+}
+async function upsertAgentsBlock(agentsFile, block) {
+  let existing = "";
+  try {
+    existing = await fsp.readFile(agentsFile, "utf8");
+  } catch (cause) {
+    if (cause?.code !== "ENOENT") throw cause;
+    await fsp.mkdir(path2.dirname(agentsFile), { recursive: true });
+    await fsp.writeFile(agentsFile, block + "\n", "utf8");
+    return "created";
+  }
+  const begin = existing.indexOf(AGENTS_BLOCK_BEGIN);
+  const end = existing.indexOf(AGENTS_BLOCK_END);
+  if (begin >= 0 && end > begin) {
+    const next = existing.slice(0, begin) + block + existing.slice(end + AGENTS_BLOCK_END.length);
+    await fsp.writeFile(agentsFile, next, "utf8");
+    return "replaced";
+  }
+  const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+  await fsp.writeFile(agentsFile, existing + separator + block + "\n", "utf8");
+  return "appended";
+}
+async function installSkillDocuments(documents, requestedId, baseDir, force, meta2) {
+  assertSafeSkillId(requestedId);
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = documents.map((document) => {
+    assertSafeSkillId(document.id);
+    if (seen.has(document.id)) throw invalid(`\u5B89\u88C5\u95ED\u5305\u5305\u542B\u91CD\u590D\u6280\u80FD: ${document.id}`);
+    seen.add(document.id);
+    if (!document.markdown.trim()) throw invalid(`\u6280\u80FD ${document.id} \u5185\u5BB9\u4E3A\u7A7A`);
+    return {
+      ...document,
+      target: path2.join(baseDir, document.id, "SKILL.md"),
+      bytes: Buffer.byteLength(document.markdown)
+    };
+  });
+  const requested = candidates.find((candidate) => candidate.id === requestedId);
+  if (!requested) throw invalid(`\u5B89\u88C5\u95ED\u5305\u4E0D\u5305\u542B\u76EE\u6807\u6280\u80FD: ${requestedId}`);
+  const unchanged = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    let existing;
+    try {
+      existing = await fsp.readFile(candidate.target, "utf8");
+    } catch (cause) {
+      if (cause?.code !== "ENOENT") throw cause;
+    }
+    if (existing === void 0 || force) continue;
+    if (candidate.id !== requestedId && existing === candidate.markdown) {
+      unchanged.add(candidate.id);
+      continue;
+    }
+    const kind = candidate.id === requestedId ? "\u76EE\u6807\u6280\u80FD\u5DF2\u5B58\u5728" : "\u524D\u7F6E\u6280\u80FD\u4E0E\u76EE\u6807\u73AF\u5883\u7248\u672C\u4E0D\u4E00\u81F4";
+    throw invalid(`${kind}\uFF1A${candidate.target}\u3002\u7528 --force \u8986\u76D6\u6574\u4E2A\u4F9D\u8D56\u95ED\u5305\uFF0C\u6216 --dir <path> \u88C5\u5230\u522B\u5904`);
+  }
+  const pending = candidates.filter((candidate) => !unchanged.has(candidate.id));
+  await writeSkillDocuments(pending, baseDir);
+  await recordInstalled(baseDir, candidates, {
+    ...meta2,
+    directIds: /* @__PURE__ */ new Set([requestedId]),
+    keepInstalledAt: unchanged
+  });
+  return {
+    id: requestedId,
+    target: requested.target,
+    source: requested.source,
+    bytes: requested.bytes,
+    installed: pending.map((candidate) => candidate.id),
+    unchanged: candidates.filter((candidate) => unchanged.has(candidate.id)).map((candidate) => candidate.id),
+    files: candidates.map((candidate) => ({
+      id: candidate.id,
+      target: candidate.target,
+      source: candidate.source,
+      bytes: candidate.bytes,
+      status: unchanged.has(candidate.id) ? "unchanged" : "installed"
+    }))
+  };
+}
+async function readLocalReferences(skillDir) {
+  const root = path2.join(skillDir, "references");
+  const out = [];
+  const walk = async (dir, prefix) => {
+    let items;
+    try {
+      items = await fsp.readdir(dir, { withFileTypes: true });
+    } catch (cause) {
+      if (cause?.code === "ENOENT") return;
+      throw cause;
+    }
+    for (const item of items.sort((a, b) => a.name.localeCompare(b.name))) {
+      const relative2 = prefix ? `${prefix}/${item.name}` : item.name;
+      if (item.isDirectory()) {
+        await walk(path2.join(dir, item.name), relative2);
+        continue;
+      }
+      if (!item.isFile()) continue;
+      assertSafeReferencePath(relative2);
+      out.push({ path: relative2, content: await fsp.readFile(path2.join(dir, item.name), "utf8") });
+    }
+  };
+  await walk(root, "");
+  return out;
+}
+async function writeSkillDocuments(documents, baseDir) {
+  const staged = [];
+  try {
+    for (const document of documents) {
+      const target = path2.join(baseDir, document.id, "SKILL.md");
+      await fsp.mkdir(path2.dirname(target), { recursive: true });
+      const temp = path2.join(path2.dirname(target), `.SKILL.md.${process.pid}.${Date.now()}.tmp`);
+      await fsp.writeFile(temp, document.markdown, "utf8");
+      staged.push({ temp, target });
+      for (const reference of document.references ?? []) {
+        assertSafeReferencePath(reference.path);
+        const referenceTarget = path2.join(baseDir, document.id, "references", reference.path);
+        await fsp.mkdir(path2.dirname(referenceTarget), { recursive: true });
+        const referenceTemp = `${referenceTarget}.${process.pid}.${Date.now()}.tmp`;
+        await fsp.writeFile(referenceTemp, reference.content, "utf8");
+        staged.push({ temp: referenceTemp, target: referenceTarget });
+      }
+    }
+    for (const file of staged) await fsp.rename(file.temp, file.target);
+  } catch (cause) {
+    await Promise.all(staged.map((file) => fsp.unlink(file.temp).catch(() => void 0)));
+    throw cause;
+  }
+}
+async function recordInstalled(baseDir, documents, meta2) {
+  const state = await readSkillsState(baseDir) ?? {
+    version: 1,
+    target: meta2.target ?? "claude",
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    skills: {}
+  };
+  state.version = 1;
+  if (meta2.target) state.target = meta2.target;
+  if (meta2.endpoint) state.endpoint = meta2.endpoint;
+  if (meta2.base !== void 0) state.base = meta2.base;
+  state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  for (const document of documents) {
+    const previous = state.skills[document.id];
+    state.skills[document.id] = {
+      source: document.source,
+      sha256: sha256(document.markdown),
+      installedAt: meta2.keepInstalledAt?.has(document.id) && previous ? previous.installedAt : state.updatedAt,
+      // 已经是直接安装的，不因为这次作为依赖被带进来就降级
+      direct: meta2.directIds.has(document.id) || Boolean(previous?.direct),
+      references: Object.fromEntries(
+        (document.references ?? []).map((reference) => [reference.path, sha256(reference.content)])
+      )
+    };
+  }
+  await writeSkillsState(baseDir, state);
+  return state;
+}
+function invalid(message) {
+  return new CliError14({ code: CliErrorCode13.INVALID_ARGUMENT, message });
+}
+async function readInstalled(baseDir, id) {
+  try {
+    return await fsp.readFile(path2.join(baseDir, id, "SKILL.md"), "utf8");
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return void 0;
+    throw cause;
+  }
+}
+async function readInstalledReference(baseDir, id, relative2) {
+  try {
+    return await fsp.readFile(path2.join(baseDir, id, "references", relative2), "utf8");
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return void 0;
+    throw cause;
+  }
+}
+async function planSkillUpdate(options) {
+  const { state, manifest: manifest2, baseDir, force, fetchDocument } = options;
+  const recorded = Object.entries(state.skills);
+  const directIds = recorded.some(([, r]) => r.direct) ? recorded.filter(([, r]) => r.direct).map(([id]) => id) : recorded.map(([id]) => id);
+  const entries = [];
+  const closure = /* @__PURE__ */ new Map();
+  for (const id of directIds.sort()) {
+    try {
+      for (const skill of resolveSkillInstallOrder(manifest2, id)) {
+        if (!closure.has(skill.id)) closure.set(skill.id, skill);
+      }
+    } catch {
+      entries.push({
+        id,
+        status: "removed-upstream",
+        note: "\u4EA7\u54C1\u8FD9\u4E00\u7248\u7684\u6280\u80FD\u76EE\u5F55\u91CC\u5DF2\u7ECF\u6CA1\u6709\u5B83\u4E86\uFF1B\u672C\u5730\u6587\u4EF6\u4FDD\u7559\u4E0D\u52A8"
+      });
+    }
+  }
+  const documents = [];
+  for (const skill of closure.values()) {
+    const record = state.skills[skill.id];
+    const onDisk = await readInstalled(baseDir, skill.id);
+    if (onDisk === void 0) {
+      documents.push(await fetchDocument(skill));
+      entries.push({
+        id: skill.id,
+        status: "added",
+        note: record ? "\u672C\u5730\u6587\u4EF6\u7F3A\u5931\uFF0C\u91CD\u65B0\u88C5\u56DE" : "\u4EA7\u54C1\u65B0\u589E\u7684\u524D\u7F6E\u6280\u80FD"
+      });
+      continue;
+    }
+    const remote = await fetchDocument(skill);
+    const remoteReferences = remote.references ?? [];
+    let differsFromRemote = remote.markdown !== onDisk;
+    let editedLocally = record !== void 0 && sha256(onDisk) !== record.sha256;
+    for (const reference of remoteReferences) {
+      const installed = await readInstalledReference(baseDir, skill.id, reference.path);
+      if (installed !== reference.content) differsFromRemote = true;
+      const recordedSha = record?.references?.[reference.path];
+      if (installed !== void 0 && recordedSha && sha256(installed) !== recordedSha) editedLocally = true;
+    }
+    if (!differsFromRemote) {
+      entries.push({ id: skill.id, status: "unchanged" });
+      continue;
+    }
+    if (editedLocally && !force) {
+      entries.push({
+        id: skill.id,
+        status: "locally-modified",
+        note: "\u672C\u5730\u6539\u8FC7\uFF0C\u6CA1\u6709\u8986\u76D6\uFF1B\u786E\u5B9A\u8981\u7528\u4EA7\u54C1\u8FD9\u4E00\u7248\u5C31\u52A0 --force"
+      });
+      continue;
+    }
+    documents.push(remote);
+    entries.push({
+      id: skill.id,
+      status: "updated",
+      note: editedLocally ? "\u672C\u5730\u6539\u8FC7\uFF0C--force \u5DF2\u8986\u76D6" : void 0
+    });
+  }
+  entries.sort((a, b) => a.id.localeCompare(b.id));
+  return { entries, documents };
+}
+var UPDATE_STATUS_LABEL = {
+  updated: "\u5DF2\u66F4\u65B0",
+  added: "\u5DF2\u8865\u88C5",
+  unchanged: "\u5DF2\u662F\u6700\u65B0",
+  "locally-modified": "\u672C\u5730\u6539\u8FC7\xB7\u8DF3\u8FC7",
+  "removed-upstream": "\u4EA7\u54C1\u5DF2\u79FB\u9664"
+};
+async function skillsUpdateCommand(args) {
+  try {
+    const layout = await resolveInstallLayout(args);
+    const state = await readSkillsState(layout.baseDir);
+    if (!state || Object.keys(state.skills).length === 0) {
       throw new CliError14({
         code: CliErrorCode13.INVALID_ARGUMENT,
-        message: `\u6280\u80FD id \u53EA\u80FD\u662F\u5C0F\u5199\u5B57\u6BCD/\u6570\u5B57/\u8FDE\u5B57\u7B26\uFF0C\u6536\u5230 "${id}"`
+        message: `${path2.join(layout.baseDir, SKILLS_STATE_FILE)} \u4E0D\u5B58\u5728\u6216\u4E3A\u7A7A \u2014\u2014 \u8FD9\u4E2A\u76EE\u5F55\u4E0B\u8FD8\u6CA1\u6709\u7528\u672C CLI \u88C5\u8FC7\u6280\u80FD\u3002\u5148 \`hcm skills install <id>\`\uFF1B\u5982\u679C\u6280\u80FD\u662F\u624B\u5DE5\u62F7\u8FDB\u6765\u7684\uFF0C\u91CD\u88C5\u4E00\u6B21\u5373\u53EF\u63A5\u7BA1\u5347\u7EA7\u3002`
       });
     }
-    let md;
-    let source;
-    if (args.from) {
-      const local = path2.resolve(args.from, id, "SKILL.md");
-      md = await fsp.readFile(local, "utf8");
-      source = local;
-    } else {
-      const endpoint = await resolveEndpoint(args);
-      md = await fetchSkillMarkdown(anonHttp(endpoint), id);
-      source = `${endpoint}/skills/${id}.md`;
-    }
-    if (!md.trim()) {
-      throw new CliError14({ code: CliErrorCode13.INVALID_ARGUMENT, message: `\u6280\u80FD ${id} \u5185\u5BB9\u4E3A\u7A7A` });
-    }
-    const baseDir = args.dir ? path2.resolve(args.dir) : args.global ? path2.join(os2.homedir(), ".claude", "skills") : path2.resolve(".claude", "skills");
-    const target = path2.join(baseDir, id, "SKILL.md");
-    const exists = await fsp.access(target).then(() => true).catch(() => false);
-    if (exists && !args.force) {
-      process.stderr.write(`\u5DF2\u5B58\u5728\uFF1A${target}
-\u7528 --force \u8986\u76D6\uFF0C\u6216 --dir <path> \u88C5\u5230\u522B\u5904
-`);
-      process.exit(1);
+    const endpoint = args.endpoint ? args.endpoint.replace(/\/+$/, "") : await resolveEndpoint(args).catch((e) => {
+      if (state.endpoint) return state.endpoint;
+      throw e;
+    });
+    const { http, base } = await chironClient({ ...args, endpoint });
+    const manifest2 = await fetchSkillCatalog(http, base);
+    const plan = await planSkillUpdate({
+      state,
+      manifest: manifest2,
+      baseDir: layout.baseDir,
+      force: Boolean(args.force),
+      fetchDocument: (skill) => fetchSkillDocument(http, skill, endpoint, base)
+    });
+    if (!args.check && plan.documents.length > 0) {
+      await writeSkillDocuments(plan.documents, layout.baseDir);
+      await recordInstalled(layout.baseDir, plan.documents, {
+        endpoint,
+        base,
+        target: layout.target,
+        directIds: /* @__PURE__ */ new Set()
+      });
+      if (layout.agentsFile) await syncAgentsIndex(layout, manifest2);
     }
-    await fsp.mkdir(path2.dirname(target), { recursive: true });
-    await fsp.writeFile(target, md, "utf8");
+    const changed = plan.entries.filter((e) => e.status === "updated" || e.status === "added");
     const fmt = args.output ?? "table";
     if (fmt === "json" || fmt === "yaml") {
-      process.stdout.write(
-        formatObject13({ id, target, source, bytes: Buffer.byteLength(md) }, { format: fmt }) + "\n"
-      );
+      process.stdout.write(formatObject13({
+        endpoint,
+        baseDir: layout.baseDir,
+        target: layout.target,
+        dryRun: Boolean(args.check),
+        changed: changed.length,
+        entries: plan.entries
+      }, { format: fmt }) + "\n");
+      process.exit(0);
+    }
+    process.stdout.write(`\u777F\u620E\u6280\u80FD\u5347\u7EA7 \u2014 ${endpoint}
+`);
+    process.stdout.write(`\u843D\u70B9 ${layout.baseDir}\uFF08${layout.target}\uFF09
+
+`);
+    for (const entry of plan.entries) {
+      const mark = entry.status === "unchanged" ? " " : entry.status === "locally-modified" ? "!" : "\xB7";
+      process.stdout.write(`  ${mark} ${entry.id.padEnd(30)} ${UPDATE_STATUS_LABEL[entry.status]}
+`);
+      if (entry.note) process.stdout.write(`      ${entry.note}
+`);
+    }
+    process.stdout.write("\n");
+    const skipped = plan.entries.filter((e) => e.status === "locally-modified").length;
+    const removed = plan.entries.filter((e) => e.status === "removed-upstream").length;
+    const tail = [
+      skipped > 0 ? `${skipped} \u4E2A\u672C\u5730\u6539\u8FC7\u88AB\u8DF3\u8FC7\uFF08--force \u8986\u76D6\uFF09` : "",
+      removed > 0 ? `${removed} \u4E2A\u4EA7\u54C1\u5DF2\u79FB\u9664\uFF08\u672C\u5730\u6587\u4EF6\u4FDD\u7559\uFF09` : ""
+    ].filter(Boolean).join("\uFF0C");
+    if (changed.length === 0 && skipped === 0 && removed === 0) {
+      process.stdout.write(args.check ? "  \u5168\u90E8\u5DF2\u662F\u6700\u65B0\uFF08--check \u53EA\u770B\u4E0D\u52A8\uFF09\n" : "  \u5168\u90E8\u5DF2\u662F\u6700\u65B0\uFF0C\u6CA1\u6709\u6539\u52A8\n");
     } else {
-      process.stdout.write(`\u2705 ${id} \u2192 ${target}
-   \u6765\u6E90 ${source}
+      const head = args.check ? changed.length > 0 ? `\u6709 ${changed.length} \u4E2A\u53EF\u4EE5\u66F4\u65B0\uFF0C\u53BB\u6389 --check \u5C31\u4F1A\u5199\u5165` : "\u6CA1\u6709\u53EF\u5199\u5165\u7684\u66F4\u65B0" : changed.length > 0 ? `\u5DF2\u66F4\u65B0 ${changed.length} \u4E2A` : "\u6CA1\u6709\u5199\u5165\u4EFB\u4F55\u6539\u52A8";
+      process.stdout.write(`  ${[head, tail].filter(Boolean).join("\uFF1B")}
 `);
     }
     process.exit(0);
   } catch (e) {
-    if (e?.code === "ENOENT" && args.from) {
-      exitWithError(new Error(`\u672C\u5730\u76EE\u5F55\u91CC\u6CA1\u6709 ${id}/SKILL.md\uFF1A${path2.resolve(args.from, id)}`));
-    }
     fail3(e, args);
   }
 }
@@ -5289,7 +5779,7 @@ async function walkWorkspaceRawFiles(rootDir, relativeDir, files) {
       localPath,
       absolutePath,
       content,
-      sha256: sha256(content),
+      sha256: sha2562(content),
       size: Buffer.byteLength(content, "utf-8")
     });
   }
@@ -5356,7 +5846,7 @@ function buildWorkspaceRawPushPlan(manifest2, localFiles, remoteFiles) {
   for (const entry of status) {
     const remote = remoteByLocal.get(entry.localPath);
     const base = baseByLocal.get(entry.localPath);
-    const remoteSha = remote ? sha256(remote.content) : void 0;
+    const remoteSha = remote ? sha2562(remote.content) : void 0;
     if (entry.status === "added") {
       if (remote) {
         conflicts.push(workspaceRawConflict(entry, "remote file already exists but was not in local snapshot"));
@@ -5621,7 +6111,7 @@ function normalizeRelativePath(value) {
 function toPosix(value) {
   return value.split(path3.sep).join("/");
 }
-function sha256(content) {
+function sha2562(content) {
   return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
 }
 function stringRequired(value, field) {
@@ -6059,7 +6549,11 @@ var cache = program.command("cache").description("\u6A21\u578B\u7F13\u5B58\u8FD0
 cache.command("stats <Model>").description("\u67E5\u770B\u6A21\u578B\u7F13\u5B58\u7EDF\u8BA1").option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((model, opts) => cacheStatsCommand(model, opts));
 cache.command("clear <Model>").description("\u6E05\u6A21\u578B\u5B9E\u4F53\u7F13\u5B58\uFF08\u5E42\u7B49\uFF0C\u4E0D\u7834\u574F\u6570\u636E\uFF09").option("--id <id>", "\u53EA\u6E05\u5355\u6761\uFF08\u9ED8\u8BA4\u6E05\u5168\u90E8\uFF09").option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((model, opts) => cacheClearCommand(model, opts));
 cache.command("clear-meta <Model>").description("\u6E05\u5143\u6570\u636E\u7F13\u5B58\uFF08Code \u7EA7 YAML + Action \u5B9A\u4E49\uFF09\u2014\u2014\u6539 meta YAML \u540E\u5FC5\u8DD1").option("--type <type>", "\u5143\u6570\u636E\u7C7B\u578B\uFF1Alist | info | view | filter | page\u2026\uFF08\u9ED8\u8BA4\u5168\u6E05\uFF09").option("--state <state>", "\u72B6\u6001\u53D8\u4F53\uFF08\u5982 self\uFF09\uFF0C\u914D\u5408 --type").option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((model, opts) => cacheClearMetaCommand(model, opts));
-program.command("upload <file>").description("\u4E0A\u4F20\u672C\u5730\u6587\u4EF6\u5230 HCM \u6587\u6863\u670D\u52A1\uFF0C\u8FD4\u56DE documentId").option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((file, opts) => uploadCommand(file, opts));
+program.command("upload <file>").description("\u4E0A\u4F20\u672C\u5730\u6587\u4EF6\u5230 HCM \u6587\u6863\u670D\u52A1\uFF0C\u8FD4\u56DE documentId").option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").option(
+  "--category <name>",
+  "\u5B58\u50A8\u5206\u7C7B\uFF08\u987B\u662F\u76EE\u6807\u73AF\u5883\u91CC\u771F\u5B9E\u5B58\u5728\u7684\u5206\u7C7B\uFF0C\u5982 flex-report / template / attachment\uFF09",
+  "attachment"
+).action((file, opts) => uploadCommand(file, opts));
 var tenant = program.command("tenant").description("\u79DF\u6237\u5F00\u901A\u4E0E\u751F\u547D\u5468\u671F");
 tenant.command("bootstrap").description("\u5F00\u901A\u65B0\u79DF\u6237\uFF08\u5EFA\u79DF\u6237 + admin \u7528\u6237 + \u7ED3\u6784 reconcile\uFF09\u2014\u2014\u4E0D\u53EF\u9006\uFF0C\u9ED8\u8BA4\u8FC7\u786E\u8BA4\u95F8").requiredOption("--tenant-id <id>", "\u79DF\u6237 ID").requiredOption("--admin-username <user>", "\u7BA1\u7406\u5458\u7528\u6237\u540D").option("--admin-password <pwd>", "\u7BA1\u7406\u5458\u5BC6\u7801\uFF08\u4F1A\u6CC4\u6F0F\u5230 history/ps\uFF0C\u5EFA\u8BAE --admin-password-stdin\uFF09").option("--admin-password-stdin", "\u4ECE\u6807\u51C6\u8F93\u5165\u8BFB\u7BA1\u7406\u5458\u5BC6\u7801\uFF08\u63A8\u8350\uFF09").option("--tenant-name <name>", "\u79DF\u6237\u540D\u79F0\uFF08\u9ED8\u8BA4\u53D6 tenantId\uFF09").option("--bootstrap-key <key>", "bootstrap \u5BC6\u94A5\uFF08\u5EFA\u8BAE\u7528 HCM_BOOTSTRAP_KEY \u73AF\u5883\u53D8\u91CF\uFF09").option("--bootstrap-key-stdin", "\u4ECE\u6807\u51C6\u8F93\u5165\u8BFB bootstrap \u5BC6\u94A5").option("--endpoint <url>", "\u540E\u7AEF\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("-y, --yes", "\u8DF3\u8FC7\u786E\u8BA4\uFF08CI \u7528\uFF09").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((opts) => tenantBootstrapCommand(opts));
 var meta = program.command("meta").description("\u79DF\u6237\u5143\u6570\u636E\u8BFB\u5199\uFF08\u9875\u9762/\u5B57\u6BB5/\u5217\u8868\u914D\u7F6E\uFF09");
@@ -6070,7 +6564,8 @@ meta.command("delete <path>").description("\u5220\u9664 meta\uFF08\u4E0D\u53EF\u
 var skills = program.command("skills").description("\u777F\u620E Chiron \u4EA4\u4ED8\u6280\u80FD\u5E93\uFF1A\u5217\u51FA / \u67E5\u770B / \u5B89\u88C5\u4EA4\u4ED8\u6280\u80FD\uFF08\u514D\u8BA4\u8BC1\uFF0C\u65E0\u9700\u5148 login\uFF09");
 skills.command("list [keyword]").description("\u5217\u51FA\u76EE\u6807\u73AF\u5883\u8FD9\u4E00\u7248\u7684\u4EA4\u4ED8\u6280\u80FD").option("--category <key>", "\u53EA\u770B\u67D0\u4E2A\u5206\u7C7B").option("--stage <key>", "\u53EA\u770B\u67D0\u4E2A\u4EA4\u4ED8\u9636\u6BB5\uFF1Ahandover | baseline | configure | migrate | integrate | golive | operate").option("--by-stage", "\u6309\u4EA4\u4ED8\u751F\u547D\u5468\u671F\u5206\u7EC4\u5C55\u793A\uFF08\u9ED8\u8BA4\u6309\u529F\u80FD\u5206\u7C7B\uFF09").option("--endpoint <url>", "\u6280\u80FD\u5E93\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "table").action((kw, opts) => skillsListCommand(kw, opts));
 skills.command("show <id>").description("\u6253\u5370\u6280\u80FD\u539F\u6587\uFF08\u7BA1\u9053\u53CB\u597D\uFF09").option("--endpoint <url>", "\u6280\u80FD\u5E93\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").action((id, opts) => skillsShowCommand(id, opts));
-skills.command("install <id>").description("\u88C5\u5230 agent \u6280\u80FD\u76EE\u5F55\uFF08\u9ED8\u8BA4 ./.claude/skills/\uFF09").option("--global", "\u88C5\u5230 ~/.claude/skills/ \u800C\u975E\u5F53\u524D\u9879\u76EE").option("--dir <path>", "\u88C5\u5230\u6307\u5B9A\u76EE\u5F55").option("--from <dir>", "\u4ECE\u672C\u5730\u76EE\u5F55\u88C5\uFF08\u73B0\u573A\u6539\u8FC7\u7684\u7248\u672C\uFF09\uFF0C\u4E0D\u8D70\u7F51\u7EDC").option("--force", "\u8986\u76D6\u5DF2\u5B58\u5728\u7684\u540C\u540D\u6280\u80FD").option("--endpoint <url>", "\u6280\u80FD\u5E93\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "table").action((id, opts) => skillsInstallCommand(id, opts));
+skills.command("install <id>").description("\u8FDE\u540C requires \u524D\u7F6E\u6280\u80FD\u4E0E\u53C2\u8003\u6587\u4EF6\u88C5\u5230 agent \u6280\u80FD\u76EE\u5F55").option("--target <agent>", "\u88C5\u7ED9\u54EA\u4E2A agent\uFF1Aclaude\uFF08.claude/skills/\uFF09| codex\uFF08hcm-skills/ + AGENTS.md\uFF09| auto", "auto").option("--global", "\u88C5\u5230\u7528\u6237\u7EA7\u76EE\u5F55\u800C\u975E\u5F53\u524D\u9879\u76EE").option("--dir <path>", "\u88C5\u5230\u6307\u5B9A\u76EE\u5F55").option("--from <dir>", "\u4ECE\u672C\u5730\u76EE\u5F55\u88C5\uFF08\u73B0\u573A\u6539\u8FC7\u7684\u7248\u672C\uFF09\uFF0C\u4E0D\u8D70\u7F51\u7EDC").option("--force", "\u8986\u76D6\u5DF2\u5B58\u5728\u7684\u540C\u540D\u6280\u80FD").option("--endpoint <url>", "\u6280\u80FD\u5E93\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "table").action((id, opts) => skillsInstallCommand(id, opts));
+skills.command("update").description("\u628A\u88C5\u8FC7\u7684\u6280\u80FD\u5347\u5230\u76EE\u6807\u73AF\u5883\u8FD9\u4E00\u7248\uFF08\u4EA7\u54C1\u5347\u7EA7\u540E\u8DD1\u5B83\uFF09").option("--check", "\u53EA\u770B\u4F1A\u53D8\u4EC0\u4E48\uFF0C\u4E0D\u5199\u76D8").option("--target <agent>", "claude | codex | auto\uFF08\u9ED8\u8BA4\u6309\u5DF2\u5B89\u88C5\u76EE\u5F55\u63A2\uFF09", "auto").option("--global", "\u5347\u7EA7\u7528\u6237\u7EA7\u76EE\u5F55\u91CC\u7684\u6280\u80FD").option("--dir <path>", "\u5347\u7EA7\u6307\u5B9A\u76EE\u5F55\u91CC\u7684\u6280\u80FD").option("--force", "\u8FDE\u672C\u5730\u6539\u8FC7\u7684\u6280\u80FD\u4E00\u8D77\u8986\u76D6\u6210\u4EA7\u54C1\u8FD9\u4E00\u7248").option("--endpoint <url>", "\u6280\u80FD\u5E93\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6\u5B89\u88C5\u65F6\u8BB0\u5F55\u7684\u5730\u5740\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "table").action((opts) => skillsUpdateCommand(opts));
 program.command("update <Model>").description("\u66F4\u65B0\u4E00\u6761 Model \u8BB0\u5F55\uFF08\u8D70\u540E\u7AEF\u5B8C\u6574\u6821\u9A8C\uFF09").requiredOption("--id <id>", "\u8BB0\u5F55 ID").requiredOption("--data <JSON>", `\u8981\u66F4\u65B0\u7684\u5B57\u6BB5 JSON\uFF0C\u4F8B\u5982 '{"name":"\u65B0\u540D\u79F0"}'`).option("--env <name>", "\u4E34\u65F6\u5207\u73AF\u5883\uFF08\u8986\u76D6 activeEnv\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--as <identity>", "\u4E34\u65F6\u6362\u8EAB\u4EFD\uFF08\u8986\u76D6 env defaultIdentity\uFF0C\u672C\u6B21\u547D\u4EE4\uFF09").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((model, opts) => updateCommand(model, opts));
 program.command("version").description("\u67E5\u540E\u7AEF\u7248\u672C\uFF08commit / tag / \u6784\u5EFA\u65F6\u95F4\uFF09\u2014\u2014\u514D\u8BA4\u8BC1\uFF0C\u65E0\u9700\u5148 login").option("--endpoint <url>", "\u540E\u7AEF\u5730\u5740\uFF08\u9ED8\u8BA4\u53D6 activeEnv \u7684 endpoint\uFF09").option("--env <name>", "\u4ECE\u8BE5 env \u89E3\u6790 endpoint").option("--output <fmt>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atable | json | yaml", "json").action((opts) => versionCommand(opts));
 var setting = program.command("setting").description("\u79DF\u6237\u7CFB\u7EDF\u53C2\u6570\uFF08\u767B\u5F55\u7B56\u7565 / \u5BC6\u7801\u7B56\u7565 / \u529F\u80FD\u5F00\u5173 / \u96C6\u6210\u53C2\u6570\uFF09");