istarshine 1.0.3 → 1.1.0

package/bin/cli.js

@@ -10,6 +10,7 @@ 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();
 
@@ -24,6 +25,7 @@ program
   .description('安装指定名称的 Skill 到当前项目')
   .option('-d, --dir <path>', '安装目标目录', './skills')
   .option('--server <url>', 'Skills Hub 服务器地址', 'https://skills.istarshine.com')
+  .option('--api-key <value>', '指定 API Key（覆盖环境变量和配置文件）')
   .action(async (skill_name, options) => {
     await install_skill(skill_name, options);
   });
@@ -56,4 +58,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/install.js

@@ -1,18 +1,20 @@
 /**
  * install 命令实现
  * 根据 skill 名称搜索、下载 zip 并解压到本地目录
+ * 支持自动携带 API Key 认证和 SKILL.md 声明检测
  */
 
 import { fetch_json, download_file } from './api.js';
-import { createWriteStream, mkdirSync, existsSync } from 'fs';
+import { readFileSync, mkdirSync, existsSync } from 'fs';
 import { join, resolve } from 'path';
 import { extract_zip } from './zip.js';
+import { resolve_api_key, mask_api_key } from './config.js';
 
 /**
  * 安装指定名称的 skill
- * 流程: 按名称搜索 -> 找到精确匹配 -> 下载 zip -> 解压到目标目录
+ * 流程: 按名称搜索 -> 找到精确匹配 -> 下载 zip（携带 API Key）-> 解压 -> 检查 SKILL.md 声明
  * @param {string} skill_name - skill 名称
- * @param {object} options - 命令行选项 { dir, server }
+ * @param {object} options - 命令行选项 { dir, server, apiKey }
  */
 export async function install_skill(skill_name, options) {
   const { dir, server } = options;
@@ -23,7 +25,14 @@ export async function install_skill(skill_name, options) {
   const spinner = ora(`正在搜索 Skill: ${skill_name}`).start();
 
   try {
-    // 1. 按名称搜索 skill
+    // 解析 API Key（命令行 > 环境变量 > 配置文件）
+    const api_key = resolve_api_key(options.apiKey);
+    // 构建 auth headers，仅下载接口使用
+    const auth_headers = api_key
+      ? { '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);
 
@@ -40,10 +49,16 @@ export async function install_skill(skill_name, options) {
       process.exit(1);
     }
 
-    // 2. 下载 zip 压缩包
+    // 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);
+    const zip_buffer = await download_file(download_url, auth_headers);
+
+    // 检查响应头 X-Auth-Warning
+    if (zip_buffer.headers && zip_buffer.headers['x-auth-warning']) {
+      // 先不输出，等安装成功后再显示
+      var auth_warning = zip_buffer.headers['x-auth-warning'];
+    }
 
     // 3. 解压到目标目录
     const target_dir = resolve(process.cwd(), dir, skill_name);
@@ -58,8 +73,44 @@ export async function install_skill(skill_name, options) {
     spinner.succeed(chalk.green(`${skill_name}@${skill.version || 'latest'} 安装成功`));
     console.log(chalk.gray(`  安装路径: ${target_dir}`));
 
+    // 安装成功后输出 X-Auth-Warning 警告
+    if (auth_warning) {
+      console.log(chalk.yellow(`  ⚠ ${auth_warning}`));
+    }
+
+    // 4. 检查 SKILL.md 中的认证声明
+    check_skill_auth_declaration(target_dir, api_key, chalk);
+
   } catch (err) {
     spinner.fail(chalk.red(`安装失败: ${err.message}`));
     process.exit(1);
   }
 }
+
+/**
+ * 检查解压后的 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.1.0",
   "description": "iStarshine Skills Hub CLI - 一键安装和管理 Skills",
   "type": "module",
   "main": "index.js",