ability-cli 0.1.0

package/README.md

@@ -0,0 +1,323 @@
+# ability-cli
+
+## 1. 项目简介
+
+**ability-cli** 是面向原子能力平台的命令行工具，用于在终端中搜索能力、查看详情、执行调用，以及直接访问底层 HTTP 接口。
+
+采用**双层设计**：
+
+- **上层工作流命令**：面向日常使用的 `search`、`inspect`、`exec`，用自然语言或能力 ID 完成「找能力 → 看 schema → 调能力」的闭环。
+- **下层接口直通 `raw`**：按路径映射网关 REST 接口，便于联调、脚本化与排障。
+
+---
+
+## 2. 安装
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd ability-cli
+
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm build
+
+# 全局链接（可选，Windows 推荐）
+npm link
+```
+
+构建完成后，可通过 `ability-cli`（或 `node dist/index.js`）运行。若使用全局链接，请确保 `pnpm` 的全局 bin 目录在 `PATH` 中。
+
+---
+
+## 3. 快速上手
+
+```bash
+# 配置（首次使用）
+ability-cli config set --app-id <your-app-id> --app-secret <your-secret>
+
+# 搜索能力
+ability-cli search "帮我导航回家" --device-id abc123
+
+# 查看能力详情
+ability-cli inspect --ability-id 20001
+
+# 生成参数模板
+ability-cli inspect --ability-id 20001 --gen-template > params.json
+
+# 执行能力
+ability-cli exec --ability-id 20001 --params params.json --device-id abc123
+
+# 健康检查
+ability-cli doctor
+```
+
+---
+
+## 4. 命令参考
+
+### 全局选项
+
+下列选项可写在任意子命令**之前**，作用于本次整条命令（例如 `ability-cli --env prod search "查询天气"`）。
+
+| 选项 | 说明 |
+|------|------|
+| `--env <env>` | 环境：`test` / `prod`，决定使用配置文件中哪一套 `profiles` |
+| `--app-id <id>` | `zy-app-id` |
+| `--app-secret <secret>` | `appSecret` |
+| `--auth-token <token>` | `Authorization` 请求头 |
+| `--base-url <url>` | 网关根地址 |
+| `--magic-sign` | 测试环境跳过验签（`zy-sign` 固定为测试用魔数） |
+| `-v, --verbose` | 详细输出（请求 URL、头、体与响应等） |
+
+### 上层命令
+
+#### `search [query]`
+
+搜索能力（自然语言或配合筛选条件，底层调用能力列表接口）。
+
+| 选项 | 说明 |
+|------|------|
+| `[query]` | 自然语言检索，映射为查询参数 `nl` |
+| `--device-id <id>` | 设备 ID；未指定时使用配置文件 `defaults.deviceId` |
+| `--app-name <name>` | 应用名称 |
+| `--type <type>` | 能力二级分类 |
+| `--capability-type <ct>` | 能力三级分类 |
+| `--json` | 仅输出 JSON（`data` 部分） |
+
+#### `inspect`
+
+查看能力详情与 `inputSchema`。
+
+| 选项 | 说明 |
+|------|------|
+| `--ability-id <id>` | **必填**，能力 ID |
+| `--gen-template` | 根据 `inputSchema` 生成参数模板 JSON 并输出 |
+| `--json` | 仅输出 JSON（`data` 部分） |
+
+#### `exec`
+
+执行能力（异步 `call-tool`）。
+
+| 选项 | 说明 |
+|------|------|
+| `--ability-id <id>` | **必填**，能力 ID |
+| `--params <json>` | 参数：JSON 字符串，或指向 JSON 文件的路径 |
+| `--device-id <id>` | 设备 ID；默认可来自 `defaults.deviceId` |
+| `--session-id <id>` | `sessionId` |
+| `--tool-call-id <id>` | `toolCallId` |
+| `--task-id <id>` | `taskId` |
+| `--message-id <id>` | `messageId` |
+| `--trace-id <id>` | `traceId`；未指定时自动生成 |
+| `--timeout <ms>` | 超时（毫秒），默认 `30000` |
+| `--json` | 以 JSON 展示返回 `data` |
+
+### 下层命令：`raw`
+
+`raw` 子命令与网关路径一一对应，适合精确控制请求参数。
+
+#### `raw ability-list`
+
+GET 能力列表。
+
+| 选项 | 说明 |
+|------|------|
+| `--device-id <id>` | 设备 ID |
+| `--app-name <name>` | 应用名称 |
+| `--type <type>` | 能力二级分类 |
+| `--capability-type <ct>` | 能力三级分类 |
+| `--nl <text>` | 自然语言筛选 |
+| `--json` | JSON 输出 |
+
+#### `raw ability-record`
+
+POST 能力上报。
+
+| 选项 | 说明 |
+|------|------|
+| `--file <path>` | **必填**，请求体 JSON 文件路径 |
+| `--json` | JSON 输出 |
+
+#### `raw app-info`
+
+GET 应用信息。
+
+| 选项 | 说明 |
+|------|------|
+| `--package-name <pkg>` | **必填**，应用包名 |
+| `--json` | JSON 输出 |
+
+#### `raw ability-info`
+
+GET 能力详情。
+
+| 选项 | 说明 |
+|------|------|
+| `--ability-id <id>` | **必填**，能力 ID |
+| `--json` | JSON 输出 |
+
+#### `raw call-tool`
+
+POST 执行能力。
+
+| 选项 | 说明 |
+|------|------|
+| `--file <path>` | **必填**，请求体 JSON 文件路径 |
+| `--json` | JSON 输出 |
+
+#### `raw category-list`
+
+GET 全量分类。
+
+| 选项 | 说明 |
+|------|------|
+| `--json` | JSON 输出 |
+
+### 工具命令
+
+#### `config set`
+
+写入 `~/.ability-cli/config.json`。
+
+| 选项 | 说明 |
+|------|------|
+| `--env <env>` | 目标环境；影响写入哪一段 `profiles`，并更新当前 `env` |
+| `--app-id <id>` | `zy-app-id` |
+| `--app-secret <secret>` | `appSecret` |
+| `--auth-token <token>` | Authorization token |
+| `--base-url <url>` | 网关地址 |
+| `--device-id <id>` | 默认设备 ID（`defaults.deviceId`） |
+| `--device-model <model>` | 默认设备型号 |
+| `--os-version <ver>` | 默认系统版本 |
+
+#### `config show`
+
+打印当前完整配置（JSON）。
+
+#### `sign debug`
+
+打印签名用原串与 `zy-sign`，便于对齐服务端验签逻辑。
+
+| 选项 | 说明 |
+|------|------|
+| `--app-id <id>` | 覆盖 `zy-app-id`（默认取自当前上下文） |
+| `--app-secret <secret>` | 覆盖密钥 |
+| `--nonce <nonce>` | 固定 nonce |
+| `--timestamp <ts>` | 固定时间戳 |
+
+#### `doctor`
+
+检查配置文件路径、当前环境、`zy-app-id` / `appSecret` / `baseUrl` 是否已配置，并请求 `{baseUrl}/time` 做网关连通性探测。
+
+---
+
+## 5. 配置
+
+### 配置文件
+
+默认路径：**`~/.ability-cli/config.json`**。
+
+首次运行若文件不存在，会使用内置默认：当前环境 `test`，`test` / `prod` 各有一套 `baseUrl`（测试/生产网关），`zy-appId`、`appSecret` 等为空；`defaults` 中可存默认设备信息等。
+
+通过 `ability-cli config set` 写入后，会按 `env` 更新对应 `profiles[env]` 下的 `baseUrl`、`zyAppId`、`appSecret`、`authToken` 等。
+
+### 环境变量
+
+| 变量 | 作用 |
+|------|------|
+| `ABILITY_CLI_ENV` | 选用 `profiles` 的环境键（如 `test` / `prod`） |
+| `ABILITY_CLI_APP_ID` | 覆盖 `zy-app-id` |
+| `ABILITY_CLI_APP_SECRET` | 覆盖 `appSecret` |
+| `ABILITY_CLI_AUTH_TOKEN` | 覆盖 Authorization |
+| `ABILITY_CLI_BASE_URL` | 覆盖网关根地址 |
+
+### 优先级
+
+对 **appId / appSecret / authToken / baseUrl** 等请求上下文：**命令行全局选项 > 对应环境变量 > 配置文件当前 profile > 内置默认值**。
+
+当前激活的 **profile（test 或 prod）** 由 **`ABILITY_CLI_ENV`（若设置）** 与配置文件中的 **`env`** 字段共同决定（环境变量优先）。
+
+---
+
+## 6. 签名机制
+
+请求头中的 `zy-sign` 使用 **HMAC-SHA256** 计算：
+
+1. 拼接**原串**（字符串直接相连，无分隔符）：  
+   `zy-app-id` + `zy-nonce` + `zy-timestamp` + `appSecret`
+2. 以 **`appSecret` 作为 HMAC 密钥**，对原串做 UTF-8 编码后的 HMAC-SHA256，结果取 **hex** 字符串，作为 `zy-sign`。
+
+同时会带上 `zy-app-id`、`zy-nonce`、`zy-timestamp`。
+
+在**测试环境**下，若使用全局选项 **`--magic-sign`**，则跳过上述计算，`zy-sign` 使用固定测试值（便于跳过网关验签联调）。
+
+---
+
+## 7. 输出格式
+
+- **默认**：表格（如能力列表）或带颜色的分段文本（如能力详情、成功/错误提示）。
+- **`--json`**：标准响应输出 `data`；非标准响应则输出原始响应 JSON，便于排障。
+- **`-v` / `--verbose`**：将请求与响应细节输出到 stderr，不影响主结果结构。
+
+---
+
+## 8. 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 参数错误或未捕获的运行时错误 |
+| 2 | 网络错误（如连接被拒绝、DNS 失败等） |
+| 3 | 签名/认证失败 |
+| 4 | 业务错误（接口返回 `code !== 200`） |
+
+---
+
+## 9. 开发
+
+```bash
+pnpm install
+pnpm dev      # watch 模式构建
+pnpm build    # 生产构建
+pnpm test     # 运行测试（Vitest）
+```
+
+---
+
+## 10. 发布
+
+### 首次发布
+
+1. 在 `package.json` 中把占位符替换为真实地址：
+   - `repository.url`
+   - `homepage`
+   - `bugs.url`
+2. 登录 npm：
+
+```bash
+npm login
+```
+
+3. 本地预检：
+
+```bash
+pnpm build
+pnpm test
+npm pack
+```
+
+4. 发布（公有包）：
+
+```bash
+npm publish --access public
+```
+
+### 版本升级发布
+
+```bash
+npm version patch   # 或 minor / major
+git push --follow-tags
+npm publish --access public
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/config.ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+var DEFAULT_CONFIG = {
+  env: "prod",
+  profiles: {
+    test: {
+      baseUrl: "https://biz-gw.zyqltest.com",
+      zyAppId: "",
+      appSecret: "",
+      authToken: ""
+    },
+    prod: {
+      baseUrl: "https://biz-gw.zyql.com",
+      zyAppId: "",
+      appSecret: "",
+      authToken: ""
+    }
+  },
+  defaults: {
+    deviceId: "",
+    deviceModel: "",
+    osVersion: "",
+    timeout: 30
+  }
+};
+function getDefaultConfigPath() {
+  return path.join(os.homedir(), ".ability-cli", "config.json");
+}
+function loadConfig(configPath) {
+  const p = configPath ?? getDefaultConfigPath();
+  if (!fs.existsSync(p)) return structuredClone(DEFAULT_CONFIG);
+  const raw = fs.readFileSync(p, "utf-8");
+  return { ...structuredClone(DEFAULT_CONFIG), ...JSON.parse(raw) };
+}
+function saveConfig(configPath, config) {
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+function getActiveProfile(config) {
+  const env = process.env.ABILITY_CLI_ENV ?? config.env;
+  return config.profiles[env] ?? config.profiles.prod;
+}
+function resolveOption(flag, envVar, configVal, defaultVal) {
+  return flag ?? envVar ?? configVal ?? defaultVal;
+}
+
+// src/output.ts
+import chalk from "chalk";
+import Table from "cli-table3";
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function printSuccess(msg) {
+  console.log(chalk.green("\u2714 ") + msg);
+}
+function printError(msg) {
+  console.error(chalk.red("\u2716 ") + msg);
+}
+function printAbilityTable(abilities) {
+  const table = new Table({
+    head: [
+      chalk.cyan("ID"),
+      chalk.cyan("\u80FD\u529B\u540D\u79F0"),
+      chalk.cyan("\u5E94\u7528"),
+      chalk.cyan("\u63CF\u8FF0"),
+      chalk.cyan("\u8C03\u7528\u65B9\u5F0F"),
+      chalk.cyan("\u6743\u9650")
+    ],
+    colWidths: [8, 20, 12, 30, 8, 6],
+    wordWrap: true
+  });
+  for (const a of abilities) {
+    table.push([
+      a.abilityId ?? "",
+      a.name ?? "",
+      a.appName ?? "",
+      a.description ?? "",
+      a.callingMethod ?? "",
+      a.permission ?? ""
+    ]);
+  }
+  console.log(table.toString());
+}
+function printAbilityDetail(a) {
+  console.log(chalk.bold.cyan(`
+\u2500\u2500 \u80FD\u529B\u8BE6\u60C5 \u2500\u2500
+`));
+  console.log(`  ${chalk.gray("ID:")}         ${a.abilityId}`);
+  console.log(`  ${chalk.gray("\u540D\u79F0:")}       ${a.name}`);
+  console.log(`  ${chalk.gray("\u5E94\u7528:")}       ${a.appName} (${a.packageName})`);
+  console.log(`  ${chalk.gray("\u63CF\u8FF0:")}       ${a.description}`);
+  console.log(`  ${chalk.gray("\u8C03\u7528\u65B9\u5F0F:")}   ${a.callingMethod}`);
+  console.log(`  ${chalk.gray("\u8D85\u65F6:")}       ${a.timeout}s`);
+  console.log(`  ${chalk.gray("\u6743\u9650:")}       ${a.permission}`);
+  console.log(`  ${chalk.gray("\u8BBE\u5907\u7C7B\u578B:")}   ${a.deviceType}`);
+  if (a.inputSchema) {
+    console.log(chalk.bold.cyan(`
+\u2500\u2500 inputSchema \u2500\u2500
+`));
+    console.log(JSON.stringify(a.inputSchema, null, 2));
+  }
+}
+function handleApiResponse(res, jsonMode, formatter) {
+  const hasStandardEnvelope = res && typeof res === "object" && Object.prototype.hasOwnProperty.call(res, "code");
+  if (hasStandardEnvelope && res.code !== 200) {
+    const msg = res.msg ?? res.message ?? JSON.stringify(res);
+    printError(`\u63A5\u53E3\u8FD4\u56DE\u9519\u8BEF: [${res.code}] ${msg}`);
+    process.exit(4);
+  }
+  const payload = hasStandardEnvelope ? res.data : res;
+  if (jsonMode) {
+    printJson(payload);
+  } else {
+    formatter(payload);
+  }
+}
+
+// src/commands/config.ts
+function registerConfigCommand(program2) {
+  const cfg = program2.command("config").description("\u7BA1\u7406 CLI \u914D\u7F6E");
+  cfg.command("set").description("\u8BBE\u7F6E\u914D\u7F6E\u9879").option("--env <env>", "\u73AF\u5883 (test/prod)").option("--app-id <id>", "zy-app-id").option("--app-secret <secret>", "appSecret").option("--auth-token <token>", "Authorization token").option("--base-url <url>", "\u7F51\u5173\u5730\u5740").option("--device-id <id>", "\u9ED8\u8BA4\u8BBE\u5907ID").option("--device-model <model>", "\u9ED8\u8BA4\u8BBE\u5907\u578B\u53F7").option("--os-version <ver>", "\u9ED8\u8BA4\u7CFB\u7EDF\u7248\u672C").action((opts) => {
+    const configPath = getDefaultConfigPath();
+    const config = loadConfig(configPath);
+    const env = opts.env ?? config.env;
+    config.env = env;
+    if (!config.profiles[env]) {
+      config.profiles[env] = { baseUrl: "", zyAppId: "", appSecret: "", authToken: "" };
+    }
+    const p = config.profiles[env];
+    if (opts.appId) p.zyAppId = opts.appId;
+    if (opts.appSecret) p.appSecret = opts.appSecret;
+    if (opts.authToken) p.authToken = opts.authToken;
+    if (opts.baseUrl) p.baseUrl = opts.baseUrl;
+    if (opts.deviceId) config.defaults.deviceId = opts.deviceId;
+    if (opts.deviceModel) config.defaults.deviceModel = opts.deviceModel;
+    if (opts.osVersion) config.defaults.osVersion = opts.osVersion;
+    saveConfig(configPath, config);
+    printSuccess(`\u914D\u7F6E\u5DF2\u4FDD\u5B58\u5230 ${configPath}`);
+  });
+  cfg.command("show").description("\u67E5\u770B\u5F53\u524D\u914D\u7F6E").action(() => {
+    const config = loadConfig();
+    printJson(config);
+  });
+}
+
+// src/context.ts
+function buildContext(opts) {
+  const config = loadConfig();
+  if (opts.env) config.env = opts.env;
+  const profile = getActiveProfile(config);
+  profile.zyAppId = resolveOption(opts.appId, process.env.ABILITY_CLI_APP_ID, profile.zyAppId, "");
+  profile.appSecret = resolveOption(opts.appSecret, process.env.ABILITY_CLI_APP_SECRET, profile.appSecret, "");
+  profile.authToken = resolveOption(opts.authToken, process.env.ABILITY_CLI_AUTH_TOKEN, profile.authToken, "");
+  profile.baseUrl = resolveOption(opts.baseUrl, process.env.ABILITY_CLI_BASE_URL, profile.baseUrl, "https://biz-gw.zyql.com");
+  return {
+    profile,
+    signOpts: { magicSign: opts.magicSign },
+    verbose: opts.verbose
+  };
+}
+function getDefaults() {
+  return loadConfig().defaults;
+}
+
+// src/signer.ts
+import { createHmac, randomBytes } from "crypto";
+function sign(message, secret) {
+  return createHmac("sha256", secret).update(message, "utf8").digest("hex");
+}
+function buildSignHeaders(appId, appSecret, opts = {}) {
+  const nonce = opts.nonce ?? randomBytes(8).toString("hex");
+  const timestamp = opts.timestamp ?? Date.now().toString();
+  const zySign = opts.magicSign ? "123456" : sign(`${appId}${nonce}${timestamp}${appSecret}`, appSecret);
+  return {
+    "zy-app-id": appId,
+    "zy-nonce": nonce,
+    "zy-timestamp": timestamp,
+    "zy-sign": zySign
+  };
+}
+
+// src/http-client.ts
+function buildUrl(base, path2, params) {
+  const url = new URL(path2, base);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== "") url.searchParams.set(k, v);
+    }
+  }
+  return url.toString();
+}
+function buildRequestHeaders(signHeaders, authToken) {
+  const headers = { ...signHeaders };
+  if (authToken) headers["Authorization"] = authToken;
+  return headers;
+}
+async function apiGet(ctx, path2, params) {
+  const signHeaders = buildSignHeaders(ctx.profile.zyAppId, ctx.profile.appSecret, ctx.signOpts);
+  const headers = buildRequestHeaders(signHeaders, ctx.profile.authToken);
+  const url = buildUrl(ctx.profile.baseUrl, path2, params);
+  if (ctx.verbose) {
+    console.error(`[verbose] GET ${url}`);
+    console.error(`[verbose] Headers: ${JSON.stringify(headers, null, 2)}`);
+  }
+  const res = await fetch(url, { headers });
+  const body = await res.json();
+  if (ctx.verbose) console.error(`[verbose] Response: ${JSON.stringify(body, null, 2)}`);
+  return body;
+}
+async function apiPost(ctx, path2, data) {
+  const signHeaders = buildSignHeaders(ctx.profile.zyAppId, ctx.profile.appSecret, ctx.signOpts);
+  const headers = buildRequestHeaders(signHeaders, ctx.profile.authToken);
+  headers["Content-Type"] = "application/json";
+  const url = buildUrl(ctx.profile.baseUrl, path2);
+  if (ctx.verbose) {
+    console.error(`[verbose] POST ${url}`);
+    console.error(`[verbose] Headers: ${JSON.stringify(headers, null, 2)}`);
+    console.error(`[verbose] Body: ${JSON.stringify(data, null, 2)}`);
+  }
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(data)
+  });
+  const body = await res.json();
+  if (ctx.verbose) console.error(`[verbose] Response: ${JSON.stringify(body, null, 2)}`);
+  return body;
+}
+
+// src/commands/raw.ts
+import fs2 from "fs";
+function registerRawCommand(program2) {
+  const raw = program2.command("raw").description("\u539F\u59CB\u63A5\u53E3\u76F4\u901A\uFF08\u8054\u8C03/\u6392\u969C\uFF09");
+  raw.command("ability-list").description("GET \u80FD\u529B\u5217\u8868").option("--device-id <id>", "\u8BBE\u5907ID").option("--app-name <name>", "\u5E94\u7528\u540D\u79F0").option("--category <category>", "\u4E09\u7EA7\u5206\u7C7B").option("--natural-lang <text>", "\u81EA\u7136\u8BED\u8A00\u7B5B\u9009").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const params = {};
+    if (opts.deviceId) params.deviceId = opts.deviceId;
+    if (opts.appName) params.appName = opts.appName;
+    if (opts.category) params.category = opts.category;
+    if (opts.naturalLang) params.naturalLang = opts.naturalLang;
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/list", params);
+    handleApiResponse(res, opts.json, (data) => printAbilityTable(data));
+  });
+  raw.command("ability-record").description("POST \u80FD\u529B\u4E0A\u62A5").requiredOption("--file <path>", "JSON \u6587\u4EF6\u8DEF\u5F84").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const data = JSON.parse(fs2.readFileSync(opts.file, "utf-8"));
+    const res = await apiPost(ctx, "/ability-service/api/v1/ability/record", data);
+    handleApiResponse(res, opts.json, () => printSuccess("\u80FD\u529B\u4E0A\u62A5\u6210\u529F"));
+  });
+  raw.command("app-info").description("GET \u5E94\u7528\u4FE1\u606F").requiredOption("--package-name <pkg>", "\u5E94\u7528\u5305\u540D").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/appInfo", { packageName: opts.packageName });
+    handleApiResponse(res, opts.json, (data) => printJson(data));
+  });
+  raw.command("ability-info").description("GET \u80FD\u529B\u8BE6\u60C5").requiredOption("--ability-id <id>", "\u80FD\u529BID").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/abilityInfo", { abilityId: opts.abilityId });
+    handleApiResponse(res, opts.json, (data) => printJson(data));
+  });
+  raw.command("call-tool").description("POST \u6267\u884C\u80FD\u529B").requiredOption("--file <path>", "JSON \u6587\u4EF6\u8DEF\u5F84").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const data = JSON.parse(fs2.readFileSync(opts.file, "utf-8"));
+    const res = await apiPost(ctx, "/ability-service/api/mcp/async/call-tool", data);
+    handleApiResponse(res, opts.json, (data2) => printJson(data2));
+  });
+  raw.command("category-list").description("GET \u5168\u91CF\u5206\u7C7B").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/category");
+    handleApiResponse(res, opts.json, (data) => printJson(data));
+  });
+}
+
+// src/commands/search.ts
+function registerSearchCommand(program2) {
+  program2.command("search [query]").description("\u641C\u7D22\u80FD\u529B\uFF08\u652F\u6301\u81EA\u7136\u8BED\u8A00\uFF09").option("--device-id <id>", "\u8BBE\u5907ID").option("--app-name <name>", "\u5E94\u7528\u540D\u79F0").option("--category <category>", "\u4E09\u7EA7\u5206\u7C7B").option("--natural-lang <text>", "\u81EA\u7136\u8BED\u8A00\uFF08\u4F18\u5148\u4E8E query\uFF09").option("--json", "JSON \u8F93\u51FA").action(async (query, opts) => {
+    const ctx = buildContext(program2.opts());
+    const defaults = getDefaults();
+    const params = {};
+    const deviceId = opts.deviceId ?? defaults.deviceId;
+    if (deviceId) params.deviceId = deviceId;
+    const naturalLang = opts.naturalLang ?? query;
+    if (naturalLang) params.naturalLang = naturalLang;
+    if (opts.appName) params.appName = opts.appName;
+    if (opts.category) params.category = opts.category;
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/list", params);
+    handleApiResponse(res, opts.json, (data) => {
+      const list = Array.isArray(data) ? data : [];
+      if (list.length === 0) {
+        console.log("\u672A\u627E\u5230\u5339\u914D\u7684\u80FD\u529B");
+        return;
+      }
+      printAbilityTable(list);
+    });
+  });
+}
+
+// src/commands/inspect.ts
+function generateTemplate(schema) {
+  if (!schema || !schema.properties) return {};
+  const result = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    switch (prop.type) {
+      case "string":
+        result[key] = prop.default ?? "";
+        break;
+      case "number":
+        result[key] = prop.default ?? 0;
+        break;
+      case "bool":
+        result[key] = prop.default ?? false;
+        break;
+      case "array":
+        result[key] = prop.items ? [generateTemplate(prop.items)] : [];
+        break;
+      case "object":
+        result[key] = generateTemplate(prop);
+        break;
+      default:
+        result[key] = null;
+    }
+  }
+  return result;
+}
+function registerInspectCommand(program2) {
+  program2.command("inspect").description("\u67E5\u770B\u80FD\u529B\u8BE6\u60C5\u4E0E inputSchema").requiredOption("--ability-id <id>", "\u80FD\u529BID").option("--gen-template", "\u751F\u6210\u53C2\u6570\u6A21\u677F JSON").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/abilityInfo", { abilityId: opts.abilityId });
+    handleApiResponse(res, opts.json, (data) => {
+      if (opts.genTemplate && data.inputSchema) {
+        printJson(generateTemplate(data.inputSchema));
+      } else {
+        printAbilityDetail(data);
+      }
+    });
+  });
+}
+
+// src/commands/exec.ts
+import { randomUUID } from "crypto";
+import fs3 from "fs";
+function registerExecCommand(program2) {
+  program2.command("exec").description("\u6267\u884C\u80FD\u529B").requiredOption("--ability-id <id>", "\u80FD\u529BID").option("--params <json>", "\u53C2\u6570 JSON \u5B57\u7B26\u4E32\u6216\u6587\u4EF6\u8DEF\u5F84").option("--device-id <id>", "\u8BBE\u5907ID").option("--session-id <id>", "sessionId").option("--tool-call-id <id>", "toolCallId").option("--task-id <id>", "taskId").option("--message-id <id>", "messageId").option("--trace-id <id>", "traceId").option("--timeout <ms>", "\u8D85\u65F6\u65F6\u95F4(\u6BEB\u79D2)", "30000").option("--json", "JSON \u8F93\u51FA").action(async (opts) => {
+    const ctx = buildContext(program2.opts());
+    const defaults = getDefaults();
+    let params = {};
+    if (opts.params) {
+      if (fs3.existsSync(opts.params)) {
+        params = JSON.parse(fs3.readFileSync(opts.params, "utf-8"));
+      } else {
+        params = JSON.parse(opts.params);
+      }
+    }
+    const body = {
+      abilityId: Number(opts.abilityId),
+      traceId: opts.traceId ?? randomUUID().replace(/-/g, ""),
+      sessionId: opts.sessionId ?? "",
+      toolCallId: opts.toolCallId ?? "",
+      taskId: opts.taskId ?? "",
+      messageId: opts.messageId ?? "",
+      deviceId: opts.deviceId ?? defaults.deviceId ?? "",
+      timeoutMillis: Number(opts.timeout),
+      params
+    };
+    const res = await apiPost(ctx, "/ability-service/api/mcp/async/call-tool", body);
+    handleApiResponse(res, opts.json, (data) => {
+      printSuccess("\u80FD\u529B\u6267\u884C\u5B8C\u6210");
+      printJson(data);
+    });
+  });
+}
+
+// src/commands/sign.ts
+import chalk2 from "chalk";
+function registerSignCommand(program2) {
+  const signCmd = program2.command("sign").description("\u7B7E\u540D\u5DE5\u5177");
+  signCmd.command("debug").description("\u8C03\u8BD5\u7B7E\u540D\uFF08\u6253\u5370\u539F\u4E32\u548C\u7ED3\u679C\uFF09").option("--app-id <id>", "zy-app-id").option("--app-secret <secret>", "appSecret").option("--nonce <nonce>", "\u6307\u5B9A nonce").option("--timestamp <ts>", "\u6307\u5B9A timestamp").action((opts) => {
+    const ctx = buildContext(program2.opts());
+    const appId = opts.appId ?? ctx.profile.zyAppId;
+    const secret = opts.appSecret ?? ctx.profile.appSecret;
+    const headers = buildSignHeaders(appId, secret, {
+      nonce: opts.nonce,
+      timestamp: opts.timestamp
+    });
+    const rawStr = `${appId}${headers["zy-nonce"]}${headers["zy-timestamp"]}${secret}`;
+    console.log(chalk2.bold.cyan("\n\u2500\u2500 \u7B7E\u540D\u8C03\u8BD5 \u2500\u2500\n"));
+    console.log(`  ${chalk2.gray("appId:")}     ${appId}`);
+    console.log(`  ${chalk2.gray("nonce:")}     ${headers["zy-nonce"]}`);
+    console.log(`  ${chalk2.gray("timestamp:")} ${headers["zy-timestamp"]}`);
+    console.log(`  ${chalk2.gray("\u539F\u4E32:")}      ${rawStr}`);
+    console.log(`  ${chalk2.gray("zy-sign:")}   ${headers["zy-sign"]}`);
+  });
+}
+
+// src/commands/doctor.ts
+import chalk3 from "chalk";
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("\u68C0\u67E5\u914D\u7F6E\u5B8C\u6574\u6027\u548C\u7F51\u5173\u8FDE\u901A\u6027").action(async () => {
+    const config = loadConfig();
+    const profile = getActiveProfile(config);
+    let ok = true;
+    console.log(chalk3.bold.cyan("\n\u2500\u2500 CLI \u5065\u5EB7\u68C0\u67E5 \u2500\u2500\n"));
+    const checks = [
+      ["\u914D\u7F6E\u6587\u4EF6", getDefaultConfigPath(), true],
+      ["\u5F53\u524D\u73AF\u5883", config.env, true],
+      ["zy-app-id", profile.zyAppId || "(\u7A7A)", !!profile.zyAppId],
+      ["appSecret", profile.appSecret ? "******" : "(\u7A7A)", !!profile.appSecret],
+      ["baseUrl", profile.baseUrl || "(\u7A7A)", !!profile.baseUrl]
+    ];
+    for (const [label, val, pass] of checks) {
+      const icon = pass ? chalk3.green("\u2714") : chalk3.red("\u2716");
+      console.log(`  ${icon} ${chalk3.gray(label + ":")} ${val}`);
+      if (!pass) ok = false;
+    }
+    try {
+      const res = await fetch(`${profile.baseUrl}/time`);
+      const body = await res.json();
+      if (body.code === 200) {
+        console.log(`  ${chalk3.green("\u2714")} ${chalk3.gray("\u7F51\u5173\u8FDE\u901A:")} ${body.data}`);
+        const serverTs = Number(String(body.data).slice(0, -1) + "0");
+        const drift = Math.abs(Date.now() - serverTs);
+        if (drift > 3e4) {
+          console.log(`  ${chalk3.yellow("\u26A0")} ${chalk3.gray("\u65F6\u949F\u504F\u5DEE:")} ${drift}ms\uFF08\u5EFA\u8BAE\u4F7F\u7528 --sync-time\uFF09`);
+        }
+      } else {
+        console.log(`  ${chalk3.red("\u2716")} ${chalk3.gray("\u7F51\u5173\u8FDE\u901A:")} \u8FD4\u56DE code=${body.code}`);
+        ok = false;
+      }
+    } catch (e) {
+      console.log(`  ${chalk3.red("\u2716")} ${chalk3.gray("\u7F51\u5173\u8FDE\u901A:")} ${e.message}`);
+      ok = false;
+    }
+    console.log();
+    if (ok) {
+      console.log(chalk3.green("  \u4E00\u5207\u6B63\u5E38\uFF0C\u53EF\u4EE5\u5F00\u59CB\u4F7F\u7528\uFF01"));
+    } else {
+      console.log(chalk3.yellow("  \u5B58\u5728\u95EE\u9898\uFF0C\u8BF7\u68C0\u67E5\u4E0A\u65B9\u6807\u8BB0 \u2716 \u7684\u9879\u76EE"));
+    }
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("ability-cli").description("\u539F\u5B50\u80FD\u529B\u5E73\u53F0 CLI \u5DE5\u5177").version("0.1.0").option("--env <env>", "\u73AF\u5883 (test/prod)").option("--app-id <id>", "zy-app-id").option("--app-secret <secret>", "appSecret").option("--auth-token <token>", "Authorization").option("--base-url <url>", "\u7F51\u5173\u5730\u5740").option("--magic-sign", "\u6D4B\u8BD5\u73AF\u5883\u8DF3\u8FC7\u9A8C\u7B7E").option("-v, --verbose", "\u8BE6\u7EC6\u8F93\u51FA");
+registerConfigCommand(program);
+registerRawCommand(program);
+registerSearchCommand(program);
+registerInspectCommand(program);
+registerExecCommand(program);
+registerSignCommand(program);
+registerDoctorCommand(program);
+process.on("unhandledRejection", (err) => {
+  if (err?.cause?.code === "ECONNREFUSED" || err?.cause?.code === "ENOTFOUND") {
+    printError(`\u7F51\u7EDC\u9519\u8BEF: ${err.message}`);
+    process.exit(2);
+  }
+  printError(err?.message ?? "\u672A\u77E5\u9519\u8BEF");
+  process.exit(1);
+});
+program.parseAsync().catch((err) => {
+  printError(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ability-cli",
+  "version": "0.1.0",
+  "description": "原子能力平台 CLI 工具",
+  "repository": {
+    "type": "git",
+    "url": "<repo-url>"
+  },
+  "homepage": "<repo-url>",
+  "bugs": {
+    "url": "<repo-url>/issues"
+  },
+  "type": "module",
+  "bin": {
+    "ability-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.28.2",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3"
+  }
+}