@hcmai/sdk 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -310,10 +310,20 @@ interface AttachmentMeta {
 }
 declare function guessMimeType(filePath: string): string;
 /**
- * 上传本地文件到 HCM 文档存储（web ChatInput 同端点同 storageCategory），
- * 返回 message.create 可直接携带的附件元数据。类型限制跟随服务端校验。
+ * 上传本地文件到 HCM 文档存储，返回可直接携带的附件元数据。
+ * 类型限制跟随服务端校验。
+ *
+ * @param storageCategory 存储分类。**必须是目标环境里真实存在的分类**——
+ *   它是服务端数据而非枚举，不同环境的分类表可以不同。
+ *   聊天附件传 {@link CHAT_ATTACHMENT_CATEGORY}；报表模板一类传 `flex-report`。
+ *
+ * <p>🔴 此前这里硬编码 `'ai-conversation'`，于是 `hcm upload <任意文件>` 在
+ * 没有该分类的环境上**一律失败**，而错误被包成
+ * `BUSINESS_RULE_VIOLATION: Request failed with status code 404`——看不出真因是
+ * 「分类不存在」。2026-08-26 按交付技能跑弹性报表端到端时，Step 4「上传模板」
+ * 卡在这里；模板是报表的必需件，这条不通整条链就断了。
  */
-declare function uploadDocument(http: AxiosInstance, filePath: string): Promise<AttachmentMeta>;
+declare function uploadDocument(http: AxiosInstance, filePath: string, storageCategory?: string): Promise<AttachmentMeta>;
 /** 默认产物落盘目录（对标 Claude Code 工具产物本地直接访问）。 */
 declare function defaultDownloadDir(): string;
 /**
@@ -1685,8 +1695,13 @@ declare function createHttpClient(opts: HttpClientOptions): AxiosInstance;
  * 必须先装技能才能建租户。所以本模块只需要 endpoint，不碰 identity/token。
  *
  * 后端契约（ChironController）：
- * - `GET /skills.json`      目录 manifest
- * - `GET /skills/{id}.md`   技能原文
+ * - `GET {base}/skills.json`                        目录 manifest
+ * - `GET {base}/skills/{id}.md`                     技能原文
+ * - `GET {base}/skills/{id}/references/{path}`      技能自带的参考文件
+ *
+ * 🔴 `{base}` 是 `'/api'` 或 `''`，由 {@link resolveChironBase} 探出来。真实部署只把
+ * `/api/**` 路由给后端，根路径归前端 SPA——`GET /skills.json` 在客户环境上拿回来的是
+ * 一段 HTML。而老版本后端只有根路径。两种都要能连上，所以先探再用，不写死。
  */
 interface ChironSkill {
     id: string;
@@ -1697,8 +1712,15 @@ interface ChironSkill {
     description: string;
     /** 交付生命周期阶段（多值）——一个技能天然跨阶段 */
     stages: string[];
+    /** 安装本技能前必须同时安装的其他 Chiron 技能 id；旧服务端缺省时视为空。 */
+    requires?: string[];
     bytes: number;
     markdownUrl: string;
+    /**
+     * 技能自带的参考文件相对路径（相对 `<skill>/references/`）。SKILL.md 正文用
+     * `[x](references/x.md)` 引它们——不跟着装下来就是一堆死链。旧服务端缺省时视为空。
+     */
+    references?: string[];
 }
 interface ChironStage {
     key: string;
@@ -1721,9 +1743,51 @@ interface ChironManifest {
     stages: ChironStage[];
     categories: ChironCategory[];
 }
-declare function fetchSkillCatalog(http: AxiosInstance): Promise<ChironManifest>;
-declare function fetchSkillMarkdown(http: AxiosInstance, id: string): Promise<string>;
+/**
+ * 探出本环境技能库的前缀。
+ *
+ * 为什么不能写死任何一个：
+ * - 真实部署（反代把 `/api/**` 给后端、其余给前端）下根路径返回的是前端 SPA 的 HTML，
+ *   HTTP 200 但根本不是 manifest —— 所以判据必须看**内容**，不能看状态码；
+ * - 还没升级到带 `/api` 别名那一版的后端，只有根路径可用。
+ *
+ * 两条都探不到时抛出可执行的错误，而不是把一段 HTML 当目录解析出满屏乱码。
+ */
+declare function resolveChironBase(http: AxiosInstance): Promise<string>;
+declare function fetchSkillCatalog(http: AxiosInstance, base: string): Promise<ChironManifest>;
+declare function fetchSkillMarkdown(http: AxiosInstance, id: string, base: string): Promise<string>;
+/** 取技能自带的参考文件原文。`relativePath` 相对 `<skill>/references/`。 */
+declare function fetchSkillReference(http: AxiosInstance, id: string, relativePath: string, base: string): Promise<string>;
+/**
+ * 参考文件相对路径约束——与后端 `ChironCatalogService.SAFE_REFERENCE_PATH` 同形。
+ *
+ * 🔴 服务端返回什么，本地就按什么建目录，所以这里是**写文件前**的闸：`..` 段会让
+ * 安装写出技能目录之外。不要因为「服务端已经校验过」就省掉——CLI 可以指向任何 endpoint。
+ */
+declare function assertSafeReferencePath(relativePath: string): void;
+/** 归一 references 字段：旧服务端缺省时视为空，逐条过白名单。 */
+declare function normalizeReferences(raw: unknown, skillId: string): string[];
 declare function flattenSkills(manifest: ChironManifest): ChironSkill[];
+/**
+ * 计算技能安装闭包，返回稳定的「依赖在前、目标在后」顺序。
+ *
+ * 这是纯函数：远程安装与测试共用，不在这里发请求或写文件。旧目录没有 requires 时
+ * 自然退化为只安装目标技能。
+ */
+declare function resolveSkillInstallOrder(manifest: ChironManifest, targetId: string): ChironSkill[];
+/**
+ * 全目录的安装顺序：逐个技能求依赖闭包后合并去重，依赖仍排在被依赖者之前。
+ *
+ * `install --all` 用它。顾问不必知道谁依赖谁，也不该为了装全而写 shell 循环——
+ * 那个循环在 zsh 下 `for id in $(...)` 不分词，会一个都不装却退出码 0。
+ */
+declare function resolveAllSkillsInstallOrder(manifest: ChironManifest): ChironSkill[];
+/** 读 SKILL.md 的 frontmatter；没有 frontmatter 返回空对象，YAML 非法则报错。 */
+declare function parseSkillFrontmatter(markdown: string, skillId: string): Record<string, unknown>;
+/** 从一份 SKILL.md 读取本地安装所需的 requires，不接受正文中的近似语法。 */
+declare function parseSkillRequirements(markdown: string, skillId: string): string[];
+/** Chiron 与公开端点共用的小写安全 id 约束。 */
+declare function assertSafeSkillId(id: string): void;
 /** 按交付生命周期阶段筛选。 */
 declare function filterByStage(skills: ChironSkill[], stage?: string): ChironSkill[];
 /** 关键词匹配 id / 标题 / 描述 / 分类，全部小写包含。 */
@@ -1772,4 +1836,4 @@ declare function resetSettingItem(http: AxiosInstance, domain: string, namespace
  */
 declare function parseSettingAssignment(raw: string): SettingWrite;
 
-export { type ActionHttpMethod, type ActionInput, type ActionMeta, type ActionResult, type ActionScope, type AnyStreamEvent, type ApprovalConfirmPayload, type ApprovalRejectPayload, type AttachmentMeta, type AuthScheme, type BootstrapReconcileResult, type BootstrapTenantRequest, type BootstrapTenantResult, type CacheClearResult, type CacheStats, type ChangePasswordInput, type ChironCategory, type ChironManifest, type ChironSkill, type ChironStage, type ClearMetaCacheOpts, CliError, CliErrorCode, type CliErrorInit, type ClientAuthContext, type ClientCredentialsInput, type ConnectionMessage, type ControlChannelEnvelope, type ConversationListItem, type ConversationListResult, type ConversationState, type CreateResult, type CreatedConversation, DEFAULT_AGENT_ID, DEFAULT_SESSION_TTL_SECONDS, type DescribeOpts, type EnvConfig, ExitCode, type FieldMeta, type Fixture, type FormatOptions, type GlobalConfig, HcmClient, type HcmClientOpts, type HttpClientOptions, type IdentityMeta, type ImportClient, type ImportOptions, type ImportResult, type InteractionAnswerPayload, type InteractionRequest, type InteractionResolved, type ListTenantMetaOpts, type LoginOutcome, MINI_CONTEXT_FILE, MINI_CONTEXT_KIND, MINI_CONTEXT_VERSION, MINI_PULL_MANIFEST_FILE, MINI_REMOTE_ROOT, MINI_STATE_DIR, type MessageClass, type MessageCreatePayload, type MessageStreamHandle, type MigrationSummary, type MiniFileSnapshot, type MiniInitArgs, type MiniLocalFile, type MiniLocalStatus, type MiniPreviewTarget, type MiniProjectContext, type MiniPullArgs, type MiniPullManifest, type MiniPullResult, type MiniPushArgs, type MiniPushConflict, type MiniPushOperation, type MiniPushPlanItem, type MiniPushResult, type MiniSmokeCheckArgs, type MiniSmokeFetch, type MiniSmokeFetchResponse, type MiniSmokeResult, type MiniSmokeTargetKind, type MiniSmokeTargetResult, type MiniStatusEntry, type MiniSurface, type MiniTemplateArgs, type MiniTemplateKind, type MiniValidationResult, type MiniVerifyAgentReport, type MiniVerifyBrowserAcceptance, type MiniVerifyChangedFile, type MiniVerifyNextAction, type MiniVerifyPlan, type MiniVerifyPreviewUrl, type MiniVerifyReport, type MiniVerifySummary, type MiniWritableTemplateConfig, type ModelDescription, type ModelQueryDsl, type OneShotOpts, type OneShotResult, type OneShotToolCall, type OutputFormat, PASSWORD_CHANGE_REQUIRED, PROACTIVE_REFRESH_MARGIN_SECONDS, type PairingLoginInput, type ParsedPlaceholder, type PasswordChangeChallenge, type PasswordLoginInput, type PatLoginInput, type Principal, type ProfileConfig, type QueryResult, RefStore, type RefreshInput, type RelationMeta, type RemoveResult, type ResponseCompletedPayload, type ResponseFailedPayload, type ResponsePartDeltaPayload, type ResponseStartedPayload, type ResumeSummary, type ResumeTurn, type RowResult, type RowStatus, SDK_VERSION, type SaveMetaResult, type SendMessageOpts, type SettingItem, type SettingWrite, type StreamCancelPayload, type StreamCommand, type StreamCommandEnvelope, type StreamCommandType, type StreamEventEnvelope, type StreamEventType, type TaskProgressPayload, type TenantMetaEntry, type TimelineItemLite, type TokenRecord, TokenStore, type ToolCallFailedPayload, type ToolCallResultPayload, type ToolCallStartedPayload, type V4RenderSink, type V4StreamEventType, type WorkspaceFileContent, type WorkspaceFileItem, type WorkspaceFileListResult, WsClient, type WsClientOpts, absoluteDownloadUrl, archiveDir, bootstrapTenant, buildAnswer, buildConfirm, buildInterrupt, buildMiniAppTemplateFiles, buildMiniPreviewTargets, buildMiniVerifyAgentReport, buildReject, buildResumeSummary, buildSteer, camelizeKeys, changePassword, classifyMessage, clearMetaCache, clearModelCache, conversationStateFile, create, createConversation, createHttpClient, createV4Reducer, createWorkspaceFile, credentialsFile, defaultDownloadDir, defaultMiniRequiredScopes, deleteEnv, deleteIdentity, deleteTenantMeta, deleteWorkspaceFile, deriveNamelessToolLabel, describePrincipal, detectDelegationPause, detectDirectInteractionPending, detectPasswordChangeChallenge, displayWidth, downloadDocument, ensureSessionFresh, envDir, envFile, envsDir, exitCodeFor, extractNextSteps, fetchConversationTimeline, fetchConversationTimelineStrict, fetchRecentConversations, fetchSkillCatalog, fetchSkillMarkdown, filterByStage, findLastAssistantSeq, flattenSkills, formatMiniVerifyReport, formatObject, formatRows, fromAxiosError, getCacheStats, getMiniStatus, getSettingDomain, getTenantMeta, globalConfigFile, guessMimeType, hcmConfigDir, identitiesDir, identityDir, identityMetaFile, inferEnvName, inferMiniWritableTemplateOptionsFromModel, initMiniAppProject, isDelegationToolName, isServerSlidingSession, listEnvs, listIdentities, listProfiles, listTenantMeta, listWorkspaceFiles, loadConversationState, loadEnv, loadGlobalConfig, loadIdentity, loadProfile, loadWorkspaceFileContent, loginClientCredentials, loginPairing, loginPassword, loginPat, matchSkills, migrateLegacyProfiles, needsRefresh, oneShot, parseConfirmToolName, parseFixture, parseInteractionRequest, parseInteractionResolved, parsePlaceholder, parseSettingAssignment, patchSettingDomain, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readMiniContext, readPullManifest, refreshToken, remove, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveRefs, runImport, runMiniSmokeChecks, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, sendMessageAndStream, snakeToCamel, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, update, uploadDocument, validateMiniProject };
+export { type ActionHttpMethod, type ActionInput, type ActionMeta, type ActionResult, type ActionScope, type AnyStreamEvent, type ApprovalConfirmPayload, type ApprovalRejectPayload, type AttachmentMeta, type AuthScheme, type BootstrapReconcileResult, type BootstrapTenantRequest, type BootstrapTenantResult, type CacheClearResult, type CacheStats, type ChangePasswordInput, type ChironCategory, type ChironManifest, type ChironSkill, type ChironStage, type ClearMetaCacheOpts, CliError, CliErrorCode, type CliErrorInit, type ClientAuthContext, type ClientCredentialsInput, type ConnectionMessage, type ControlChannelEnvelope, type ConversationListItem, type ConversationListResult, type ConversationState, type CreateResult, type CreatedConversation, DEFAULT_AGENT_ID, DEFAULT_SESSION_TTL_SECONDS, type DescribeOpts, type EnvConfig, ExitCode, type FieldMeta, type Fixture, type FormatOptions, type GlobalConfig, HcmClient, type HcmClientOpts, type HttpClientOptions, type IdentityMeta, type ImportClient, type ImportOptions, type ImportResult, type InteractionAnswerPayload, type InteractionRequest, type InteractionResolved, type ListTenantMetaOpts, type LoginOutcome, MINI_CONTEXT_FILE, MINI_CONTEXT_KIND, MINI_CONTEXT_VERSION, MINI_PULL_MANIFEST_FILE, MINI_REMOTE_ROOT, MINI_STATE_DIR, type MessageClass, type MessageCreatePayload, type MessageStreamHandle, type MigrationSummary, type MiniFileSnapshot, type MiniInitArgs, type MiniLocalFile, type MiniLocalStatus, type MiniPreviewTarget, type MiniProjectContext, type MiniPullArgs, type MiniPullManifest, type MiniPullResult, type MiniPushArgs, type MiniPushConflict, type MiniPushOperation, type MiniPushPlanItem, type MiniPushResult, type MiniSmokeCheckArgs, type MiniSmokeFetch, type MiniSmokeFetchResponse, type MiniSmokeResult, type MiniSmokeTargetKind, type MiniSmokeTargetResult, type MiniStatusEntry, type MiniSurface, type MiniTemplateArgs, type MiniTemplateKind, type MiniValidationResult, type MiniVerifyAgentReport, type MiniVerifyBrowserAcceptance, type MiniVerifyChangedFile, type MiniVerifyNextAction, type MiniVerifyPlan, type MiniVerifyPreviewUrl, type MiniVerifyReport, type MiniVerifySummary, type MiniWritableTemplateConfig, type ModelDescription, type ModelQueryDsl, type OneShotOpts, type OneShotResult, type OneShotToolCall, type OutputFormat, PASSWORD_CHANGE_REQUIRED, PROACTIVE_REFRESH_MARGIN_SECONDS, type PairingLoginInput, type ParsedPlaceholder, type PasswordChangeChallenge, type PasswordLoginInput, type PatLoginInput, type Principal, type ProfileConfig, type QueryResult, RefStore, type RefreshInput, type RelationMeta, type RemoveResult, type ResponseCompletedPayload, type ResponseFailedPayload, type ResponsePartDeltaPayload, type ResponseStartedPayload, type ResumeSummary, type ResumeTurn, type RowResult, type RowStatus, SDK_VERSION, type SaveMetaResult, type SendMessageOpts, type SettingItem, type SettingWrite, type StreamCancelPayload, type StreamCommand, type StreamCommandEnvelope, type StreamCommandType, type StreamEventEnvelope, type StreamEventType, type TaskProgressPayload, type TenantMetaEntry, type TimelineItemLite, type TokenRecord, TokenStore, type ToolCallFailedPayload, type ToolCallResultPayload, type ToolCallStartedPayload, type V4RenderSink, type V4StreamEventType, type WorkspaceFileContent, type WorkspaceFileItem, type WorkspaceFileListResult, WsClient, type WsClientOpts, absoluteDownloadUrl, archiveDir, assertSafeReferencePath, assertSafeSkillId, bootstrapTenant, buildAnswer, buildConfirm, buildInterrupt, buildMiniAppTemplateFiles, buildMiniPreviewTargets, buildMiniVerifyAgentReport, buildReject, buildResumeSummary, buildSteer, camelizeKeys, changePassword, classifyMessage, clearMetaCache, clearModelCache, conversationStateFile, create, createConversation, createHttpClient, createV4Reducer, createWorkspaceFile, credentialsFile, defaultDownloadDir, defaultMiniRequiredScopes, deleteEnv, deleteIdentity, deleteTenantMeta, deleteWorkspaceFile, deriveNamelessToolLabel, describePrincipal, detectDelegationPause, detectDirectInteractionPending, detectPasswordChangeChallenge, displayWidth, downloadDocument, ensureSessionFresh, envDir, envFile, envsDir, exitCodeFor, extractNextSteps, fetchConversationTimeline, fetchConversationTimelineStrict, fetchRecentConversations, fetchSkillCatalog, fetchSkillMarkdown, fetchSkillReference, filterByStage, findLastAssistantSeq, flattenSkills, formatMiniVerifyReport, formatObject, formatRows, fromAxiosError, getCacheStats, getMiniStatus, getSettingDomain, getTenantMeta, globalConfigFile, guessMimeType, hcmConfigDir, identitiesDir, identityDir, identityMetaFile, inferEnvName, inferMiniWritableTemplateOptionsFromModel, initMiniAppProject, isDelegationToolName, isServerSlidingSession, listEnvs, listIdentities, listProfiles, listTenantMeta, listWorkspaceFiles, loadConversationState, loadEnv, loadGlobalConfig, loadIdentity, loadProfile, loadWorkspaceFileContent, loginClientCredentials, loginPairing, loginPassword, loginPat, matchSkills, migrateLegacyProfiles, needsRefresh, normalizeReferences, oneShot, parseConfirmToolName, parseFixture, parseInteractionRequest, parseInteractionResolved, parsePlaceholder, parseSettingAssignment, parseSkillFrontmatter, parseSkillRequirements, patchSettingDomain, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readMiniContext, readPullManifest, refreshToken, remove, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveAllSkillsInstallOrder, resolveChironBase, resolveRefs, resolveSkillInstallOrder, runImport, runMiniSmokeChecks, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, sendMessageAndStream, snakeToCamel, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, update, uploadDocument, validateMiniProject };

package/dist/index.js

@@ -1403,13 +1403,14 @@ var MIME_BY_EXT = {
 function guessMimeType(filePath) {
   return MIME_BY_EXT[path4.extname(filePath).toLowerCase()] ?? "application/octet-stream";
 }
-async function uploadDocument(http, filePath) {
+var CHAT_ATTACHMENT_CATEGORY = "ai-conversation";
+async function uploadDocument(http, filePath, storageCategory = CHAT_ATTACHMENT_CATEGORY) {
   const abs = expandHome(filePath);
   const buf = await fsp.readFile(abs);
   const fileName = path4.basename(abs);
   const form = new FormData();
   form.append("file", new Blob([buf], { type: guessMimeType(abs) }), fileName);
-  form.append("storageCategory", "ai-conversation");
+  form.append("storageCategory", storageCategory);
   form.append("allowEmptyFormId", "true");
   const resp = await http.post("/api/documents/upload", form);
   const meta = resp.data?.data ?? resp.data;
@@ -5002,20 +5003,163 @@ async function deleteTenantMeta(http, path6) {
 }
 
 // src/skills.ts
-async function fetchSkillCatalog(http) {
-  const resp = await http.get("/skills.json");
+import yaml7, { JSON_SCHEMA as JSON_SCHEMA2 } from "js-yaml";
+var CHIRON_BASE_CANDIDATES = ["/api", ""];
+function looksLikeManifest(data) {
+  if (!data || typeof data !== "object") return false;
+  const m = data;
+  return m.name === "chiron" && Array.isArray(m.categories);
+}
+async function resolveChironBase(http) {
+  const tried = [];
+  for (const base of CHIRON_BASE_CANDIDATES) {
+    const url = `${base}/skills.json`;
+    tried.push(url);
+    try {
+      const resp = await http.get(url);
+      const data = resp.data?.data ?? resp.data;
+      if (looksLikeManifest(data)) return base;
+    } catch {
+    }
+  }
+  throw new CliError({
+    code: "INVALID_ARGUMENT" /* INVALID_ARGUMENT */,
+    message: `\u8FD9\u4E2A\u73AF\u5883\u4E0A\u627E\u4E0D\u5230\u777F\u620E\u6280\u80FD\u5E93\uFF08\u8BD5\u8FC7 ${tried.join(" \u548C ")}\uFF09\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u540E\u7AEF\u7248\u672C\u8FD8\u6CA1\u6709 /api/skills \u7AEF\u70B9\uFF0C\u5347\u7EA7\u540E\u7AEF\u5373\u53EF\uFF1B\u2461 endpoint \u586B\u7684\u662F\u524D\u7AEF\u5730\u5740\u4E14\u672A\u53CD\u4EE3\u5230\u540E\u7AEF\uFF1B\u2462 \u5730\u5740\u6216\u7F51\u7EDC\u4E0D\u901A\u3002`
+  });
+}
+async function fetchSkillCatalog(http, base) {
+  const resp = await http.get(`${base}/skills.json`);
   return resp.data?.data ?? resp.data;
 }
-async function fetchSkillMarkdown(http, id) {
-  const resp = await http.get(`/skills/${encodeURIComponent(id)}.md`, {
+async function fetchSkillMarkdown(http, id, base) {
+  const resp = await http.get(`${base}/skills/${encodeURIComponent(id)}.md`, {
+    responseType: "text",
+    transformResponse: [(d) => d]
+  });
+  return String(resp.data ?? "");
+}
+async function fetchSkillReference(http, id, relativePath, base) {
+  assertSafeReferencePath(relativePath);
+  const encoded = relativePath.split("/").map(encodeURIComponent).join("/");
+  const resp = await http.get(`${base}/skills/${encodeURIComponent(id)}/references/${encoded}`, {
     responseType: "text",
     transformResponse: [(d) => d]
   });
   return String(resp.data ?? "");
 }
+function assertSafeReferencePath(relativePath) {
+  const ok = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}(\/[A-Za-z0-9_][A-Za-z0-9._-]{0,63}){0,2}$/.test(relativePath);
+  if (!ok) {
+    throw invalid(`\u53C2\u8003\u6587\u4EF6\u8DEF\u5F84\u4E0D\u5408\u6CD5\uFF1A${JSON.stringify(relativePath)}`);
+  }
+}
+function normalizeReferences(raw, skillId) {
+  if (raw === void 0 || raw === null) return [];
+  if (!Array.isArray(raw)) throw invalid(`\u6280\u80FD ${skillId} \u7684 references \u53EA\u80FD\u662F\u5B57\u7B26\u4E32\u6570\u7EC4`);
+  const out = [];
+  for (const value of raw) {
+    if (typeof value !== "string" || !value.trim()) {
+      throw invalid(`\u6280\u80FD ${skillId} \u7684 references \u53EA\u80FD\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\u6570\u7EC4`);
+    }
+    const rel = value.trim();
+    assertSafeReferencePath(rel);
+    if (!out.includes(rel)) out.push(rel);
+  }
+  return out;
+}
 function flattenSkills(manifest2) {
   return (manifest2.categories ?? []).flatMap((c) => c.skills ?? []);
 }
+function resolveSkillInstallOrder(manifest2, targetId) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const skill of flattenSkills(manifest2)) {
+    if (byId.has(skill.id)) {
+      throw invalid(`\u6280\u80FD\u76EE\u5F55\u5B58\u5728\u91CD\u590D id: ${skill.id}`);
+    }
+    byId.set(skill.id, skill);
+  }
+  if (!byId.has(targetId)) {
+    throw invalid(`\u6280\u80FD\u76EE\u5F55\u4E2D\u4E0D\u5B58\u5728 ${targetId}`);
+  }
+  const state = /* @__PURE__ */ new Map();
+  const path6 = [];
+  const order = [];
+  const visit = (id, requiredBy) => {
+    const current = state.get(id);
+    if (current === "done") return;
+    if (current === "visiting") {
+      const cycleStart = path6.indexOf(id);
+      const cycle = [...path6.slice(Math.max(0, cycleStart)), id];
+      throw invalid(`\u6280\u80FD\u4F9D\u8D56\u5B58\u5728\u73AF: ${cycle.join(" -> ")}`);
+    }
+    const skill = byId.get(id);
+    if (!skill) {
+      throw invalid(`\u6280\u80FD ${requiredBy ?? targetId} \u4F9D\u8D56\u4E0D\u5B58\u5728: ${id}`);
+    }
+    assertSafeSkillId(skill.id);
+    state.set(id, "visiting");
+    path6.push(id);
+    for (const required of normalizeRequirements(skill.requires, skill.id)) {
+      visit(required, skill.id);
+    }
+    path6.pop();
+    state.set(id, "done");
+    order.push(skill);
+  };
+  visit(targetId);
+  return order;
+}
+function resolveAllSkillsInstallOrder(manifest2) {
+  const order = /* @__PURE__ */ new Map();
+  const all = flattenSkills(manifest2).map((skill) => skill.id).sort();
+  for (const id of all) {
+    for (const skill of resolveSkillInstallOrder(manifest2, id)) {
+      if (!order.has(skill.id)) order.set(skill.id, skill);
+    }
+  }
+  return [...order.values()];
+}
+function parseSkillFrontmatter(markdown, skillId) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!match) return {};
+  let frontmatter;
+  try {
+    frontmatter = yaml7.load(match[1] ?? "", { schema: JSON_SCHEMA2 });
+  } catch (cause) {
+    throw new CliError({
+      code: "INVALID_ARGUMENT" /* INVALID_ARGUMENT */,
+      message: `\u6280\u80FD ${skillId} \u7684 frontmatter \u4E0D\u662F\u5408\u6CD5 YAML`,
+      cause
+    });
+  }
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) return {};
+  return frontmatter;
+}
+function parseSkillRequirements(markdown, skillId) {
+  return normalizeRequirements(parseSkillFrontmatter(markdown, skillId).requires, skillId);
+}
+function assertSafeSkillId(id) {
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) {
+    throw invalid(`\u6280\u80FD id \u53EA\u80FD\u662F\u5C0F\u5199\u5B57\u6BCD/\u6570\u5B57/\u8FDE\u5B57\u7B26\uFF0C\u6536\u5230 "${id}"`);
+  }
+}
+function normalizeRequirements(raw, skillId) {
+  if (raw === void 0 || raw === null) return [];
+  const values = Array.isArray(raw) ? raw : [raw];
+  const normalized = [];
+  for (const value of values) {
+    if (typeof value !== "string" || !value.trim()) {
+      throw invalid(`\u6280\u80FD ${skillId} \u7684 requires \u53EA\u80FD\u662F\u975E\u7A7A\u6280\u80FD id \u6570\u7EC4`);
+    }
+    const id = value.trim();
+    assertSafeSkillId(id);
+    if (!normalized.includes(id)) normalized.push(id);
+  }
+  return normalized;
+}
+function invalid(message) {
+  return new CliError({ code: "INVALID_ARGUMENT" /* INVALID_ARGUMENT */, message });
+}
 function filterByStage(skills, stage) {
   if (!stage) return skills;
   return skills.filter((s) => (s.stages ?? []).includes(stage));
@@ -5076,6 +5220,8 @@ export {
   WsClient,
   absoluteDownloadUrl,
   archiveDir,
+  assertSafeReferencePath,
+  assertSafeSkillId,
   bootstrapTenant,
   buildAnswer,
   buildConfirm,
@@ -5122,6 +5268,7 @@ export {
   fetchRecentConversations,
   fetchSkillCatalog,
   fetchSkillMarkdown,
+  fetchSkillReference,
   filterByStage,
   findLastAssistantSeq,
   flattenSkills,
@@ -5162,6 +5309,7 @@ export {
   matchSkills,
   migrateLegacyProfiles,
   needsRefresh,
+  normalizeReferences,
   oneShot,
   parseConfirmToolName,
   parseFixture,
@@ -5169,6 +5317,8 @@ export {
   parseInteractionResolved,
   parsePlaceholder,
   parseSettingAssignment,
+  parseSkillFrontmatter,
+  parseSkillRequirements,
   patchSettingDomain,
   profileDir,
   profileFile,
@@ -5183,7 +5333,10 @@ export {
   resolveActiveEnv,
   resolveActiveIdentity,
   resolveActiveProfile,
+  resolveAllSkillsInstallOrder,
+  resolveChironBase,
   resolveRefs,
+  resolveSkillInstallOrder,
   runImport,
   runMiniSmokeChecks,
   saveConversationState,