istarshine 1.0.3 → 1.2.0

package/bin/cli.js

@@ -10,13 +10,14 @@ import { install_skill } from '../lib/install.js';
 import { search_skills } from '../lib/search.js';
 import { list_skills } from '../lib/list.js';
 import { find_skills } from '../lib/find.js';
+import { config_action } from '../lib/config.js';
 
 const program = new Command();
 
 program
   .name('istarshine')
   .description('iStarshine Skills Hub CLI - 一键安装和管理 Skills')
-  .version('1.0.2');
+  .version('1.2.0');
 
 // install 子命令
 program
@@ -24,6 +25,8 @@ program
   .description('安装指定名称的 Skill 到当前项目')
   .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);
   });
@@ -56,4 +59,15 @@ program
     await find_skills(keyword, options);
   });
 
+// config 子命令
+program
+  .command('config')
+  .description('管理 CLI 配置（API Key 等）')
+  .option('--api-key <value>', '设置 API Key')
+  .option('--show', '查看当前配置')
+  .option('--clear', '清除配置文件')
+  .action(async (options) => {
+    await config_action(options);
+  });
+
 program.parse();

package/lib/api.js

@@ -9,17 +9,27 @@ import { request as http_request } from 'http';
 /**
  * 发送 GET 请求，返回 JSON
  * @param {string} url - 完整请求 URL
+ * @param {object} headers - 可选的自定义请求头
  * @returns {Promise<object>} 解析后的 JSON 对象
  */
-export function fetch_json(url) {
+export function fetch_json(url, headers = {}) {
   return new Promise((resolve, reject) => {
-    const is_https = url.startsWith('https');
+    const parsed = new URL(url);
+    const is_https = parsed.protocol === 'https:';
     const do_request = is_https ? request : http_request;
 
-    do_request(url, (res) => {
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (is_https ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: 'GET',
+      headers: { ...headers },
+    };
+
+    do_request(options, (res) => {
       // 处理重定向
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return fetch_json(res.headers.location).then(resolve).catch(reject);
+        return fetch_json(res.headers.location, headers).then(resolve).catch(reject);
       }
 
       if (res.statusCode !== 200) {
@@ -41,19 +51,29 @@ export function fetch_json(url) {
 }
 
 /**
- * 下载二进制文件，返回 Buffer
+ * 下载二进制文件，返回带 headers 属性的 Buffer
  * @param {string} url - 完整请求 URL
- * @returns {Promise<Buffer>} 文件二进制数据
+ * @param {object} headers - 可选的自定义请求头
+ * @returns {Promise<Buffer>} 文件二进制数据，附带 .headers 属性（响应头）
  */
-export function download_file(url) {
+export function download_file(url, headers = {}) {
   return new Promise((resolve, reject) => {
-    const is_https = url.startsWith('https');
+    const parsed = new URL(url);
+    const is_https = parsed.protocol === 'https:';
     const do_request = is_https ? request : http_request;
 
-    do_request(url, (res) => {
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (is_https ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: 'GET',
+      headers: { ...headers },
+    };
+
+    do_request(options, (res) => {
       // 处理重定向
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return download_file(res.headers.location).then(resolve).catch(reject);
+        return download_file(res.headers.location, headers).then(resolve).catch(reject);
       }
 
       if (res.statusCode !== 200) {
@@ -64,7 +84,10 @@ export function download_file(url) {
       const chunks = [];
       res.on('data', (chunk) => { chunks.push(chunk); });
       res.on('end', () => {
-        resolve(Buffer.concat(chunks));
+        // 返回 Buffer 并附加响应头属性，便于调用方读取 X-Auth-Warning 等
+        const buffer = Buffer.concat(chunks);
+        Object.assign(buffer, { headers: res.headers });
+        resolve(buffer);
       });
     }).on('error', reject).end();
   });

package/lib/config.js

@@ -0,0 +1,172 @@
+/**
+ * 配置管理模块
+ * 负责 Config_File 的读写和 API Key 多来源优先级解析
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// 配置目录和文件路径
+const CONFIG_DIR = join(homedir(), '.istarshine');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+/**
+ * 读取配置文件，返回解析后的对象
+ * 文件不存在或 JSON 无效时返回 null
+ * @returns {object|null}
+ */
+export function read_config() {
+  try {
+    if (!existsSync(CONFIG_FILE)) return null;
+    const content = readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    // JSON 解析失败或读取失败，返回 null
+    return null;
+  }
+}
+
+/**
+ * 写入配置文件（合并模式，保留已有字段）
+ * 自动创建 CONFIG_DIR，文件权限设为 0o600
+ * @param {object} updates - 要更新的字段
+ */
+export function write_config(updates) {
+  // 确保目录存在
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  // 读取已有配置并合并
+  const existing = read_config() || {};
+  const merged = { ...existing, ...updates };
+  // 写入文件，2 空格缩进
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf8');
+  // 设置文件权限为仅当前用户可读写
+  chmodSync(CONFIG_FILE, 0o600);
+}
+
+/**
+ * 删除配置文件
+ * @returns {boolean} 是否成功删除（文件不存在返回 false）
+ */
+export function clear_config() {
+  try {
+    if (!existsSync(CONFIG_FILE)) return false;
+    unlinkSync(CONFIG_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 按优先级解析 API Key
+ * 1. cli_key（命令行 --api-key 参数）
+ * 2. 环境变量 ISTARSHINE_API_KEY
+ * 3. Config_File 中的 api_key 字段
+ * @param {string|undefined} cli_key - 命令行传入的 key
+ * @returns {string|null}
+ */
+export function resolve_api_key(cli_key) {
+  // 优先级 1：命令行参数
+  if (cli_key) return cli_key;
+  // 优先级 2：环境变量
+  const env_key = process.env.ISTARSHINE_API_KEY;
+  if (env_key) return env_key;
+  // 优先级 3：配置文件
+  const cfg = read_config();
+  if (cfg && cfg.api_key) return cfg.api_key;
+  // 所有来源均无 Key
+  return null;
+}
+
+/**
+ * 将 API Key 脱敏为前缀形式
+ * 如 "sk-acme-a1b2c3d4..." → "sk-acme-a1b2..."
+ * @param {string} key
+ * @returns {string}
+ */
+export function mask_api_key(key) {
+  if (!key) return '';
+  // 格式: sk-{prefix}-{32hex}
+  // 找到最后一个 '-' 的位置，取前4位hex + '...'
+  const last_dash = key.lastIndexOf('-');
+  if (last_dash === -1) {
+    // 非标准格式，只显示前8字符
+    return key.slice(0, 8) + '...';
+  }
+  const before_hex = key.slice(0, last_dash + 1);
+  const hex_part = key.slice(last_dash + 1);
+  return before_hex + hex_part.slice(0, 4) + '...';
+}
+
+// 导出路径常量，供测试使用
+export { CONFIG_DIR, CONFIG_FILE };
+
+/**
+ * config 子命令处理函数
+ * 支持 --api-key、--show、--clear 三个选项
+ * @param {object} options - 命令行选项
+ */
+export async function config_action(options) {
+  const chalk = (await import('chalk')).default;
+
+  // --clear：清除配置文件
+  if (options.clear) {
+    const removed = clear_config();
+    if (removed) {
+      console.log(chalk.green('✔ 配置文件已清除'));
+    } else {
+      console.log(chalk.yellow('配置文件不存在，无需清除'));
+    }
+    return;
+  }
+
+  // --api-key：写入 API Key
+  if (options.apiKey) {
+    try {
+      write_config({ api_key: options.apiKey });
+      const masked = mask_api_key(options.apiKey);
+      console.log(chalk.green(`✔ API Key 已保存: ${masked}`));
+    } catch (err) {
+      console.log(chalk.red(`✖ 写入配置失败: ${err.message}`));
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --show：展示当前配置
+  if (options.show) {
+    const cfg = read_config();
+    const env_key = process.env.ISTARSHINE_API_KEY;
+
+    if (!cfg && !env_key) {
+      console.log(chalk.yellow('尚未配置。使用 istarshine config --api-key <value> 设置 API Key'));
+      return;
+    }
+
+    console.log(chalk.cyan('当前配置:'));
+    if (cfg && cfg.api_key) {
+      console.log(`  API Key (配置文件): ${mask_api_key(cfg.api_key)}`);
+    }
+    if (env_key) {
+      console.log(`  API Key (环境变量 ISTARSHINE_API_KEY): ${mask_api_key(env_key)}`);
+    }
+    if (cfg) {
+      // 展示其他非 api_key 字段
+      for (const [k, v] of Object.entries(cfg)) {
+        if (k !== 'api_key') {
+          console.log(`  ${k}: ${v}`);
+        }
+      }
+    }
+    return;
+  }
+
+  // 无选项时显示帮助
+  console.log(chalk.yellow('请指定选项。用法:'));
+  console.log('  istarshine config --api-key <value>  设置 API Key');
+  console.log('  istarshine config --show              查看当前配置');
+  console.log('  istarshine config --clear             清除配置文件');
+}

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

@@ -1,65 +1,282 @@
 /**
  * install 命令实现
  * 根据 skill 名称搜索、下载 zip 并解压到本地目录
+ * 支持自动携带 API Key 认证和 SKILL.md 声明检测
  */
 
 import { fetch_json, download_file } from './api.js';
-import { createWriteStream, 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 } from './config.js';
+import { resolve_install_queue } from './deps.js';
 
 /**
- * 安装指定名称的 skill
- * 流程: 按名称搜索 -> 找到精确匹配 -> 下载 zip -> 解压到目标目录
+ * 安装单个 skill 的核心逻辑（模块内部函数）
+ * 流程: 按名称搜索 -> 精确匹配 -> 下载 zip -> 解压 -> 检查 SKILL.md 声明
+ *
  * @param {string} skill_name - skill 名称
  * @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 {
-    // 1. 按名称搜索 skill
-    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 || ''}`);
-        });
+    // 解析 API Key（命令行 > 环境变量 > 配置文件）
+    const api_key = resolve_api_key(options.apiKey);
+    // 构建 auth headers，仅下载接口使用
+    const auth_headers = api_key
+      ? { 'Authorization': `Bearer ${api_key}` }
+      : {};
+
+    // 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('');
+    }
+
+    // 3. 遍历队列，逐个安装
+    const total = install_queue.length;
+    let installed_count = 0;
+    let skipped_count = 0;
+
+    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);
       }
-      process.exit(1);
     }
 
-    // 2. 下载 zip 压缩包
-    spinner.text = `正在下载 ${skill_name}@${skill.version || 'latest'}...`;
-    const download_url = `${server}/api/skills/${skill.id}/download`;
-    const zip_buffer = await download_file(download_url);
+    // 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('，')}`));
+    }
 
-    // 3. 解压到目标目录
-    const target_dir = resolve(process.cwd(), dir, skill_name);
-    spinner.text = `正在解压到 ${target_dir}...`;
+  } 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;
+  }
 
-    if (!existsSync(target_dir)) {
-      mkdirSync(target_dir, { recursive: true });
+  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'));
+
+    // 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'
+      };
+    }
+
+    // 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'));
+  }
+}
+
+/**
+ * 检查解压后的 SKILL.md 是否包含 api.auth 或 metadata.openclaw 声明
+ * 如果包含且未配置 API Key，输出配置引导提示
+ * @param {string} target_dir - 解压目标目录
+ * @param {string|null} api_key - 当前解析到的 API Key
+ * @param {object} chalk - chalk 实例
+ */
+function check_skill_auth_declaration(target_dir, api_key, chalk) {
+  const skill_md_path = join(target_dir, 'SKILL.md');
+  if (!existsSync(skill_md_path)) return;
+
+  try {
+    const content = readFileSync(skill_md_path, 'utf8');
+    // 检查是否包含认证声明
+    const has_api_auth = content.includes('api.auth') || content.includes('auth:');
+    const has_openclaw = content.includes('metadata.openclaw') || content.includes('primaryEnv');
+
+    if ((has_api_auth || has_openclaw) && !api_key) {
+      console.log('');
+      console.log(chalk.cyan('  💡 该 Skill 需要 API Key 认证，请配置:'));
+      console.log(chalk.gray('     方式一: npx istarshine config --api-key <your-key>'));
+      console.log(chalk.gray('     方式二: openclaw config set skills.entries.<skill>.apiKey "<your-key>"'));
+    }
+  } catch {
+    // 读取 SKILL.md 失败不影响安装流程
   }
 }

package/package.json

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