ability-cli 0.1.0 → 0.2.1

package/README.md

@@ -13,6 +13,18 @@
 
 ## 2. 安装
 
+### 从 npm 安装（推荐）
+
+```bash
+npm install -g ability-cli
+# 或
+pnpm add -g ability-cli
+```
+
+安装完成后在终端执行 `ability-cli --help` 即可。若提示找不到命令，请确认 npm / pnpm 的全局 bin 目录已加入 `PATH`（可先执行一次 `pnpm setup` 配置 pnpm 的全局目录）。
+
+### 从源码安装
+
 ```bash
 # 克隆仓库
 git clone <repo-url>
@@ -24,11 +36,12 @@ pnpm install
 # 构建
 pnpm build
 
-# 全局链接（可选，Windows 推荐）
-npm link
+# 全局链接（开发调试）
+pnpm link --global
+# 或 npm link
 ```
 
-构建完成后，可通过 `ability-cli`（或 `node dist/index.js`）运行。若使用全局链接，请确保 `pnpm` 的全局 bin 目录在 `PATH` 中。
+构建完成后，可通过 `ability-cli`（或 `node dist/index.js`）运行。
 
 ---
 
@@ -41,8 +54,8 @@ 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
+# 查看能力详情（端侧能力需带设备 ID，也可用 config 里的 defaults.deviceId）
+ability-cli inspect --ability-id 20001 --device-id <device-id>
 
 # 生成参数模板
 ability-cli inspect --ability-id 20001 --gen-template > params.json
@@ -80,11 +93,11 @@ ability-cli doctor
 
 | 选项 | 说明 |
 |------|------|
-| `[query]` | 自然语言检索，映射为查询参数 `nl` |
+| `[query]` | 自然语言检索；与 `--natural-lang` 二选一或组合（`--natural-lang` 优先） |
 | `--device-id <id>` | 设备 ID；未指定时使用配置文件 `defaults.deviceId` |
 | `--app-name <name>` | 应用名称 |
-| `--type <type>` | 能力二级分类 |
-| `--capability-type <ct>` | 能力三级分类 |
+| `--category <category>` | 三级分类 |
+| `--natural-lang <text>` | 自然语言（优先于 `[query]`） |
 | `--json` | 仅输出 JSON（`data` 部分） |
 
 #### `inspect`
@@ -94,6 +107,7 @@ ability-cli doctor
 | 选项 | 说明 |
 |------|------|
 | `--ability-id <id>` | **必填**，能力 ID |
+| `--device-id <id>` | 设备 ID；**端侧能力**查询详情时通常必填；未指定时可使用 `defaults.deviceId` |
 | `--gen-template` | 根据 `inputSchema` 生成参数模板 JSON 并输出 |
 | `--json` | 仅输出 JSON（`data` 部分） |
 
@@ -126,9 +140,8 @@ GET 能力列表。
 |------|------|
 | `--device-id <id>` | 设备 ID |
 | `--app-name <name>` | 应用名称 |
-| `--type <type>` | 能力二级分类 |
-| `--capability-type <ct>` | 能力三级分类 |
-| `--nl <text>` | 自然语言筛选 |
+| `--category <category>` | 三级分类 |
+| `--natural-lang <text>` | 自然语言筛选 |
 | `--json` | JSON 输出 |
 
 #### `raw ability-record`
@@ -156,6 +169,7 @@ GET 能力详情。
 | 选项 | 说明 |
 |------|------|
 | `--ability-id <id>` | **必填**，能力 ID |
+| `--device-id <id>` | 设备 ID；**端侧能力**时通常必填；未指定时可使用 `defaults.deviceId` |
 | `--json` | JSON 输出 |
 
 #### `raw call-tool`
@@ -290,10 +304,7 @@ pnpm test     # 运行测试（Vitest）
 
 ### 首次发布
 
-1. 在 `package.json` 中把占位符替换为真实地址：
-   - `repository.url`
-   - `homepage`
-   - `bugs.url`
+1. （可选）在 `package.json` 中填写真实仓库地址：`repository`、`homepage`、`bugs`。
 2. 登录 npm：
 
 ```bash

package/dist/index.js

@@ -260,9 +260,13 @@ function registerRawCommand(program2) {
     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) => {
+  raw.command("ability-info").description("GET \u80FD\u529B\u8BE6\u60C5").requiredOption("--ability-id <id>", "\u80FD\u529BID").option("--device-id <id>", "\u8BBE\u5907 ID\uFF1B\u5F53\u80FD\u529B\u4E3A\u7AEF\u4FA7\u80FD\u529B\u65F6\u5FC5\u586B").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 });
+    const defaults = getDefaults();
+    const params = { abilityId: opts.abilityId };
+    const deviceId = opts.deviceId ?? defaults.deviceId;
+    if (deviceId) params.deviceId = deviceId;
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/abilityInfo", params);
     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) => {
@@ -271,6 +275,12 @@ function registerRawCommand(program2) {
     const res = await apiPost(ctx, "/ability-service/api/mcp/async/call-tool", data);
     handleApiResponse(res, opts.json, (data2) => printJson(data2));
   });
+  raw.command("ability-callback").description("POST \u4E0A\u62A5\u80FD\u529B\u6267\u884C\u7ED3\u679C").requiredOption("--file <path>", "JSON \u6587\u4EF6\u8DEF\u5F84\uFF0C\u9700\u5305\u542B requestId\uFF0Cbody \u53EF\u9009").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/callback", 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");
@@ -330,9 +340,13 @@ function generateTemplate(schema) {
   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) => {
+  program2.command("inspect").description("\u67E5\u770B\u80FD\u529B\u8BE6\u60C5\u4E0E inputSchema").requiredOption("--ability-id <id>", "\u80FD\u529BID").option("--device-id <id>", "\u8BBE\u5907 ID\uFF1B\u5F53\u80FD\u529B\u4E3A\u7AEF\u4FA7\u80FD\u529B\u65F6\u5FC5\u586B").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 });
+    const defaults = getDefaults();
+    const params = { abilityId: opts.abilityId };
+    const deviceId = opts.deviceId ?? defaults.deviceId;
+    if (deviceId) params.deviceId = deviceId;
+    const res = await apiGet(ctx, "/ability-service/api/v1/ability/abilityInfo", params);
     handleApiResponse(res, opts.json, (data) => {
       if (opts.genTemplate && data.inputSchema) {
         printJson(generateTemplate(data.inputSchema));
@@ -448,7 +462,7 @@ function registerDoctorCommand(program2) {
 
 // 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");
+program.name("ability-cli").description("\u539F\u5B50\u80FD\u529B\u5E73\u53F0 CLI \u5DE5\u5177").version("0.2.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);

package/package.json

@@ -1,47 +1,53 @@
-{
-  "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"
-  }
-}
+{
+  "name": "ability-cli",
+  "version": "0.2.1",
+  "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": "npm run build && npm test"
+  },
+  "keywords": [
+    "ability",
+    "cli",
+    "atomic-ability",
+    "mcp",
+    "zyql"
+  ],
+  "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"
+  }
+}