istarshine 1.1.0 → 1.2.0

package/bin/cli.js

@@ -17,7 +17,7 @@ const program = new Command();
 program
   .name('istarshine')
   .description('iStarshine Skills Hub CLI - 一键安装和管理 Skills')
-  .version('1.0.2');
+  .version('1.2.0');
 
 // install 子命令
 program
@@ -26,6 +26,7 @@ program
   .option('-d, --dir <path>', '安装目标目录', './skills')
   .option('--server <url>', 'Skills Hub 服务器地址', 'https://skills.istarshine.com')
   .option('--api-key <value>', '指定 API Key（覆盖环境变量和配置文件）')
+  .option('--force', '强制重新安装所有依赖', false)
   .action(async (skill_name, options) => {
     await install_skill(skill_name, options);
   });

package/lib/deps.js

@@ -0,0 +1,127 @@
+/**
+ * 依赖解析模块
+ * 负责从后端 API 获取依赖信息，构建安装队列
+ */
+
+import { fetch_json } from './api.js';
+
+/**
+ * 解析指定 skill 的完整依赖，生成安装队列
+ * 优先使用后端返回的 resolved_dependencies（已扁平化的完整传递依赖列表）
+ * 安装队列 = resolved_dependencies + 目标 skill 本身
+ *
+ * @param {string} skill_name - 目标 skill 名称
+ * @param {string} server - Skills Hub 服务器地址
+ * @returns {Promise<string[]>} 安装队列（依赖在前，目标在后）
+ */
+export async function resolve_install_queue(skill_name, server) {
+  try {
+    // 调用后端依赖查询 API
+    const url = `${server}/api/skills/by-name/${encodeURIComponent(skill_name)}/dependencies`;
+    const data = await fetch_json(url);
+
+    // 优先使用后端已解析的完整传递依赖列表
+    if (data.resolved_dependencies && data.resolved_dependencies.length > 0) {
+      return [...data.resolved_dependencies, skill_name];
+    }
+
+    // resolved_dependencies 为空但 dependencies 非空，回退到 CLI 侧递归解析（任务 4.2 实现）
+    if (data.dependencies && data.dependencies.length > 0) {
+      return await resolve_deps_recursive(skill_name, server, new Set());
+    }
+
+    // 无依赖，仅安装目标 skill
+    return [skill_name];
+  } catch {
+    // API 调用失败（网络错误、404 等），回退到仅安装目标 skill
+    return [skill_name];
+  }
+}
+
+// 最大递归深度，超过时终止并报错
+const MAX_RECURSION_DEPTH = 10;
+
+/**
+ * CLI 侧回退递归解析
+ * 当后端 resolved_dependencies 不可用时，CLI 自行递归解析依赖图
+ * 深度优先后序收集，最终去重
+ *
+ * @param {string} skill_name - 目标 skill 名称
+ * @param {string} server - Skills Hub 服务器地址
+ * @param {Set<string>} [visited] - 已访问集合，用于检测循环依赖
+ * @param {number} [depth=0] - 当前递归深度
+ * @returns {Promise<string[]>} 安装队列（依赖在前，目标在后，已去重）
+ */
+export async function resolve_deps_recursive(skill_name, server, visited, depth = 0) {
+  // 初始调用时创建 visited 集合
+  if (!visited) {
+    visited = new Set();
+  }
+
+  // 超过最大递归深度，终止并报错
+  if (depth > MAX_RECURSION_DEPTH) {
+    throw new Error(`依赖解析超过最大递归深度 ${MAX_RECURSION_DEPTH} 层，可能存在异常依赖链`);
+  }
+
+  // 循环检测：已访问过则返回空数组
+  if (visited.has(skill_name)) {
+    return [];
+  }
+
+  // 标记为已访问
+  visited.add(skill_name);
+
+  // 后序收集结果
+  const result = [];
+
+  try {
+    // 调用 API 获取当前 skill 的直接依赖
+    const url = `${server}/api/skills/by-name/${encodeURIComponent(skill_name)}/dependencies`;
+    const data = await fetch_json(url);
+
+    const deps = data.dependencies;
+    if (Array.isArray(deps) && deps.length > 0) {
+      // 对每个直接依赖递归解析
+      for (const dep of deps) {
+        if (typeof dep !== 'string') continue;
+        const sub_result = await resolve_deps_recursive(dep, server, visited, depth + 1);
+        // 收集子依赖的结果
+        for (const item of sub_result) {
+          result.push(item);
+        }
+      }
+    }
+  } catch (err) {
+    // API 调用失败时（网络错误、404 等），将当前 skill 加入结果并继续
+    // 不阻塞整体解析流程
+  }
+
+  // 后序插入：先插入子依赖，再插入当前 skill
+  result.push(skill_name);
+
+  // 去重（保持顺序，首次出现的保留）
+  const seen = new Set();
+  const deduped = [];
+  for (const item of result) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      deduped.push(item);
+    }
+  }
+
+  return deduped;
+}
+
+/**
+ * 校验 Skill 名称是否合法
+ * 规则：由小写字母、数字和横杠组成，不以横杠开头或结尾
+ *
+ * @param {string} name - 待校验的 Skill 名称
+ * @returns {boolean} 合法返回 true，否则返回 false
+ */
+export function validate_skill_name(name) {
+  if (typeof name !== 'string' || name === '') {
+    return false;
+  }
+  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(name);
+}

package/lib/install.js

@@ -5,24 +5,100 @@
  */
 
 import { fetch_json, download_file } from './api.js';
-import { readFileSync, mkdirSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs';
 import { join, resolve } from 'path';
+import { homedir } from 'os';
 import { extract_zip } from './zip.js';
-import { resolve_api_key, mask_api_key } from './config.js';
+import { resolve_api_key } from './config.js';
+import { resolve_install_queue } from './deps.js';
 
 /**
- * 安装指定名称的 skill
- * 流程: 按名称搜索 -> 找到精确匹配 -> 下载 zip（携带 API Key）-> 解压 -> 检查 SKILL.md 声明
+ * 安装单个 skill 的核心逻辑（模块内部函数）
+ * 流程: 按名称搜索 -> 精确匹配 -> 下载 zip -> 解压 -> 检查 SKILL.md 声明
+ *
  * @param {string} skill_name - skill 名称
- * @param {object} options - 命令行选项 { dir, server, apiKey }
+ * @param {object} options - 命令行选项 { dir, server }
+ * @param {object} auth_headers - 认证请求头（用于下载接口）
+ * @param {object} chalk - chalk 实例
+ * @param {number} index - 当前安装序号（从 1 开始）
+ * @param {number} total - 安装队列总数
  */
-export async function install_skill(skill_name, options) {
+async function install_single_skill(skill_name, options, auth_headers, chalk, index, total) {
   const { dir, server } = options;
-  // 动态导入 chalk 和 ora（ESM 模块）
-  const chalk = (await import('chalk')).default;
   const ora = (await import('ora')).default;
 
-  const spinner = ora(`正在搜索 Skill: ${skill_name}`).start();
+  // 进度前缀，例如 [1/3]
+  const progress_prefix = `[${index}/${total}]`;
+
+  const spinner = ora(`${progress_prefix} 正在搜索 Skill: ${skill_name}`).start();
+
+  // 解析 API Key，用于后续认证声明检查
+  const api_key = resolve_api_key(options.apiKey);
+
+  // 1. 按名称搜索 skill（搜索接口不携带 auth header）
+  const search_url = `${server}/api/skills/search?keyword=${encodeURIComponent(skill_name)}`;
+  const results = await fetch_json(search_url);
+
+  // 精确匹配名称
+  const skill = results.find(s => s.name === skill_name);
+  if (!skill) {
+    spinner.fail(chalk.red(`${progress_prefix} 未找到名为 "${skill_name}" 的 Skill`));
+    if (results.length > 0) {
+      console.log(chalk.yellow('\n你是不是想找:'));
+      results.slice(0, 5).forEach(s => {
+        console.log(`  ${chalk.cyan(s.name)}  ${s.display_name || ''}`);
+      });
+    }
+    throw new Error(`未找到名为 "${skill_name}" 的 Skill`);
+  }
+
+  // 2. 下载 zip 压缩包（下载接口携带 auth header）
+  spinner.text = `${progress_prefix} 正在下载 ${skill_name}@${skill.version || 'latest'}...`;
+  const download_url = `${server}/api/skills/${skill.id}/download`;
+  const zip_buffer = await download_file(download_url, auth_headers);
+
+  // 检查响应头 X-Auth-Warning
+  let auth_warning;
+  if (zip_buffer.headers && zip_buffer.headers['x-auth-warning']) {
+    auth_warning = zip_buffer.headers['x-auth-warning'];
+  }
+
+  // 3. 解压到目标目录
+  const target_dir = resolve(process.cwd(), dir, skill_name);
+  spinner.text = `${progress_prefix} 正在解压到 ${target_dir}...`;
+
+  if (!existsSync(target_dir)) {
+    mkdirSync(target_dir, { recursive: true });
+  }
+
+  await extract_zip(zip_buffer, target_dir);
+
+  spinner.succeed(chalk.green(`${progress_prefix} ${skill_name}@${skill.version || 'latest'} 安装成功`));
+  console.log(chalk.gray(`  安装路径: ${target_dir}`));
+
+  // 安装成功后输出 X-Auth-Warning 警告
+  if (auth_warning) {
+    console.log(chalk.yellow(`  ⚠ ${auth_warning}`));
+  }
+
+  // 5. 自动配置 OpenClaw SecretRef（如果提供了 API Key）
+  if (api_key) {
+    setup_openclaw_secretref(skill_name, api_key, chalk);
+  }
+
+  // 6. 检查 SKILL.md 中的认证声明
+  check_skill_auth_declaration(target_dir, api_key, chalk);
+}
+
+/**
+ * 安装指定名称的 skill（支持依赖自动解析）
+ * 流程: 解析依赖队列 -> 遍历队列 -> 跳过已安装 -> 逐个安装 -> 输出汇总
+ * @param {string} skill_name - skill 名称
+ * @param {object} options - 命令行选项 { dir, server, apiKey, force }
+ */
+export async function install_skill(skill_name, options) {
+  // 动态导入 chalk（ESM 模块）
+  const chalk = (await import('chalk')).default;
 
   try {
     // 解析 API Key（命令行 > 环境变量 > 配置文件）
@@ -32,58 +108,148 @@ export async function install_skill(skill_name, options) {
       ? { 'Authorization': `Bearer ${api_key}` }
       : {};
 
-    // 1. 按名称搜索 skill（搜索接口不携带 auth header）
-    const search_url = `${server}/api/skills/search?keyword=${encodeURIComponent(skill_name)}`;
-    const results = await fetch_json(search_url);
-
-    // 精确匹配名称
-    const skill = results.find(s => s.name === skill_name);
-    if (!skill) {
-      spinner.fail(chalk.red(`未找到名为 "${skill_name}" 的 Skill`));
-      if (results.length > 0) {
-        console.log(chalk.yellow('\n你是不是想找:'));
-        results.slice(0, 5).forEach(s => {
-          console.log(`  ${chalk.cyan(s.name)}  ${s.display_name || ''}`);
-        });
-      }
-      process.exit(1);
+    // 1. 调用 resolve_install_queue 获取安装队列
+    //    如果依赖解析本身抛出异常，回退到仅安装目标 skill
+    let install_queue;
+    try {
+      install_queue = await resolve_install_queue(skill_name, options.server);
+    } catch (resolve_err) {
+      console.log(chalk.yellow(`⚠ 依赖解析失败，仅安装目标 Skill: ${resolve_err.message}`));
+      install_queue = [skill_name];
+    }
+
+    // 2. 如果队列长度 > 1，输出待安装列表（包含依赖数量）
+    if (install_queue.length > 1) {
+      const dep_count = install_queue.length - 1;
+      console.log(chalk.cyan(`\n📦 检测到 ${dep_count} 个依赖，共需安装 ${install_queue.length} 个 Skill:`));
+      install_queue.forEach((name, i) => {
+        const label = name === skill_name ? chalk.bold(name) + ' (目标)' : name;
+        console.log(chalk.gray(`  ${i + 1}. ${label}`));
+      });
+      console.log('');
     }
 
-    // 2. 下载 zip 压缩包（下载接口携带 auth header）
-    spinner.text = `正在下载 ${skill_name}@${skill.version || 'latest'}...`;
-    const download_url = `${server}/api/skills/${skill.id}/download`;
-    const zip_buffer = await download_file(download_url, auth_headers);
+    // 3. 遍历队列，逐个安装
+    const total = install_queue.length;
+    let installed_count = 0;
+    let skipped_count = 0;
 
-    // 检查响应头 X-Auth-Warning
-    if (zip_buffer.headers && zip_buffer.headers['x-auth-warning']) {
-      // 先不输出，等安装成功后再显示
-      var auth_warning = zip_buffer.headers['x-auth-warning'];
+    for (let i = 0; i < total; i++) {
+      const current_name = install_queue[i];
+      const target_dir = resolve(process.cwd(), options.dir, current_name);
+
+      // 检查本地是否已安装（除非 --force）
+      if (existsSync(target_dir) && !options.force) {
+        skipped_count++;
+        console.log(chalk.yellow(`[${i + 1}/${total}] ${current_name} 已安装，跳过 (使用 --force 强制重新安装)`));
+        continue;
+      }
+
+      // 未安装或 --force，调用 install_single_skill 执行安装
+      try {
+        await install_single_skill(current_name, options, auth_headers, chalk, i + 1, total);
+        installed_count++;
+      } catch (install_err) {
+        // 输出失败的 skill 名称和错误原因
+        console.log(chalk.red(`\n✖ Skill "${current_name}" 安装失败: ${install_err.message}`));
+        // 如果还有后续 skill 未安装，输出终止提示
+        if (i < total - 1) {
+          console.log(chalk.yellow(`⚠ 终止后续安装，剩余 ${total - i - 1} 个 Skill 未安装`));
+        }
+        process.exit(1);
+      }
     }
 
-    // 3. 解压到目标目录
-    const target_dir = resolve(process.cwd(), dir, skill_name);
-    spinner.text = `正在解压到 ${target_dir}...`;
+    // 4. 安装完成后输出汇总信息
+    if (install_queue.length > 1) {
+      console.log('');
+      const parts = [];
+      if (installed_count > 0) {
+        parts.push(`成功安装了 ${installed_count} 个 Skill`);
+      }
+      if (skipped_count > 0) {
+        parts.push(`跳过了 ${skipped_count} 个已安装的 Skill`);
+      }
+      console.log(chalk.green(`✔ ${parts.join('，')}`));
+    }
 
-    if (!existsSync(target_dir)) {
-      mkdirSync(target_dir, { recursive: true });
+  } catch (err) {
+    // 处理其他未预期的错误（依赖安装错误已在循环内处理）
+    console.log(chalk.red(`安装失败: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * 将 API Key 写入 OpenClaw SecretRef 体系
+ * 1. 写入 ~/.openclaw/secrets.json（密钥存储）
+ * 2. 在 ~/.openclaw/openclaw.json 中配置 provider + skill apiKey SecretRef 引用
+ *
+ * @param {string} skill_name - skill 名称
+ * @param {string} api_key - API Key 明文
+ * @param {object} chalk - chalk 实例
+ */
+function setup_openclaw_secretref(skill_name, api_key, chalk) {
+  const openclaw_dir = join(homedir(), '.openclaw');
+  const secrets_path = join(openclaw_dir, 'secrets.json');
+  const config_path = join(openclaw_dir, 'openclaw.json');
+
+  // 未安装 openclaw，跳过
+  if (!existsSync(openclaw_dir)) {
+    return;
+  }
+
+  try {
+    // ---- 步骤 1: 写入 secrets.json ----
+    let secrets = {};
+    if (existsSync(secrets_path)) {
+      secrets = JSON.parse(readFileSync(secrets_path, 'utf8'));
     }
+    // 按供应商分组存储，同一供应商的 skill 共用一个 key
+    if (!secrets.skills) secrets.skills = {};
+    if (!secrets.skills.istarshine) secrets.skills.istarshine = {};
+    secrets.skills.istarshine.apiKey = api_key;
 
-    await extract_zip(zip_buffer, target_dir);
+    writeFileSync(secrets_path, JSON.stringify(secrets, null, 2), 'utf8');
+    chmodSync(secrets_path, 0o600);
 
-    spinner.succeed(chalk.green(`${skill_name}@${skill.version || 'latest'} 安装成功`));
-    console.log(chalk.gray(`  安装路径: ${target_dir}`));
+    // ---- 步骤 2: 配置 openclaw.json ----
+    if (!existsSync(config_path)) {
+      return; // 无 openclaw 配置文件，跳过
+    }
+    const config = JSON.parse(readFileSync(config_path, 'utf8'));
 
-    // 安装成功后输出 X-Auth-Warning 警告
-    if (auth_warning) {
-      console.log(chalk.yellow(`  ⚠ ${auth_warning}`));
+    // 2a. 确保 secrets.providers.filemain 存在
+    if (!config.secrets) config.secrets = {};
+    if (!config.secrets.providers) config.secrets.providers = {};
+    if (!config.secrets.providers.filemain) {
+      config.secrets.providers.filemain = {
+        source: 'file',
+        path: '~/.openclaw/secrets.json',
+        mode: 'json'
+      };
     }
 
-    // 4. 检查 SKILL.md 中的认证声明
-    check_skill_auth_declaration(target_dir, api_key, chalk);
+    // 2b. 配置 skill 的 apiKey SecretRef 引用
+    if (!config.skills) config.skills = {};
+    if (!config.skills.entries) config.skills.entries = {};
+    if (!config.skills.entries[skill_name]) config.skills.entries[skill_name] = {};
+    config.skills.entries[skill_name].apiKey = {
+      source: 'file',
+      provider: 'filemain',
+      id: '/skills/istarshine/apiKey'
+    };
+
+    writeFileSync(config_path, JSON.stringify(config, null, 2), 'utf8');
+
+    console.log(chalk.green('  ✔ API Key 已配置到 OpenClaw SecretRef'));
+    console.log(chalk.gray('    密钥文件: ~/.openclaw/secrets.json'));
+    console.log(chalk.gray('    配置引用: skills.entries.' + skill_name + '.apiKey → SecretRef'));
 
   } catch (err) {
-    spinner.fail(chalk.red(`安装失败: ${err.message}`));
-    process.exit(1);
+    // SecretRef 配置失败不阻断安装流程
+    console.log(chalk.yellow(`  ⚠ OpenClaw SecretRef 自动配置失败: ${err.message}`));
+    console.log(chalk.gray('    可手动配置，参考: openclaw secrets configure'));
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "istarshine",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "iStarshine Skills Hub CLI - 一键安装和管理 Skills",
   "type": "module",
   "main": "index.js",