@lark-apaas/miaoda-cli 0.1.0-alpha.c783fb5

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# miaoda-cli
+
+妙搭开发平台 Code Agent 命令行工具，为 Agent 提供原子能力。
+
+## 安装
+
+```bash
+pnpm add -g @lark-apaas/miaoda-cli
+```
+
+## 使用
+
+```bash
+# 设置默认应用（需要应用上下文的命令可用 --app-id 覆盖）
+export MIAODA_APP_ID=app_demo_xxx
+
+# 插件管理
+miaoda plugin list-packages
+miaoda plugin install @demo/example-plugin
+```
+
+JSON 结构化输出（Agent 推荐）：
+
+```bash
+# 输出全部字段
+miaoda plugin list --json
+
+# 可选字段级选择
+miaoda plugin list --json id,name
+
+# 或通过 --output 指定格式
+miaoda plugin list --output json
+```
+
+## 命令树
+
+命令以"域"作为第一级命名空间：
+
+| 域 | 用途 |
+|---|---|
+| `miaoda plugin ...` | 插件管理：安装、更新、移除、插件实例查询 |
+
+完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
+
+## 全局参数
+
+- `--json [fields]`：输出结构化 JSON，可选字段级选择（如 `--json id,name`）。
+- `--output <pretty|json>`：输出格式，默认 `pretty`。
+- `--verbose`：输出调试日志到 stderr。
+
+> `--app-id <id>` 非全局参数，需要应用上下文的命令会各自声明，默认读取 `MIAODA_APP_ID` 环境变量。
+
+## 环境变量
+
+- `MIAODA_APP_ID`：默认应用 ID，等价于 `--app-id`。
+- `MIAODA_CANARY_HEADER`：设置后所有 HTTP 请求自动带上 `x-tt-env: <值>` 小流量头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。
+
+## 输出契约
+
+- 默认文本输出（pretty），`--json` 或 `--output json` 切换为 JSON。
+- 错误始终写 stderr，业务数据写 stdout。
+- 完整的输出格式、JSON envelope、错误 shape、错误码前缀、退出码分类等见 [Agent 友好 CLI 设计规范](./docs/agent-friendly-cli.md)。
+
+## 贡献
+
+详见 [AGENTS.md](./AGENTS.md)。

package/bin/miaoda.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/main.js");

package/dist/api/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plugin = void 0;
+const _plugin = __importStar(require("../api/plugin/index"));
+exports.plugin = { ..._plugin };

package/dist/api/plugin/api.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginVersions = getPluginVersions;
+exports.getPluginVersion = getPluginVersion;
+exports.downloadPlugin = downloadPlugin;
+exports.getCachePath = getCachePath;
+exports.hasCachedPlugin = hasCachedPlugin;
+exports.listCachedPlugins = listCachedPlugins;
+exports.cleanAllCache = cleanAllCache;
+exports.cleanPluginCache = cleanPluginCache;
+exports.reportEvents = reportEvents;
+exports.reportInstallEvent = reportInstallEvent;
+exports.reportCreateInstanceEvent = reportCreateInstanceEvent;
+const http_client_1 = require("@lark-apaas/http-client");
+const http_1 = require("../../utils/http");
+const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ── Plugin Version API ──
+async function getPluginVersions(keys, latestOnly = true) {
+    const client = (0, http_1.getHttpClient)();
+    const response = await client.post(`/api/v1/studio/innerapi/plugins/-/versions/batch_get?keys=${keys.join(",")}&latest_only=${String(latestOnly)}`);
+    if (!response.ok) {
+        throw new error_1.HttpError(response.status, response.url, `Failed to get plugin versions: ${String(response.status)} ${response.statusText}`);
+    }
+    const result = (await response.json());
+    if (result.status_code !== "0") {
+        throw new error_1.AppError("INTERNAL_API_ERROR", `API error: ${result.message ?? "unknown"}`);
+    }
+    return result.data.pluginVersions;
+}
+async function getPluginVersion(pluginKey, requestedVersion) {
+    const isLatest = requestedVersion === "latest";
+    const versions = await getPluginVersions([pluginKey], isLatest);
+    const pluginVersions = versions[pluginKey];
+    if (!pluginVersions || pluginVersions.length === 0) {
+        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not found: ${pluginKey}`, { next_actions: ["检查包名拼写，或确认该插件已在插件市场发布"] });
+    }
+    if (isLatest) {
+        return pluginVersions[0];
+    }
+    const targetVersion = pluginVersions.find((v) => v.version === requestedVersion);
+    if (!targetVersion) {
+        throw new error_1.AppError("VERSION_NOT_FOUND", `Version ${requestedVersion} not found for plugin ${pluginKey}`, { next_actions: [`可用版本：${pluginVersions.map((v) => v.version).join(", ")}`] });
+    }
+    return targetVersion;
+}
+// ── Plugin Download ──
+function parsePluginKey(key) {
+    const match = /^(@[^/]+)\/(.+)$/.exec(key);
+    if (!match) {
+        throw new error_1.AppError("INVALID_PLUGIN_KEY", `Invalid plugin key format: ${key}`, { next_actions: ["插件 key 必须形如 @scope/name"] });
+    }
+    return { scope: match[1], name: match[2] };
+}
+async function downloadFromInner(pluginKey, version) {
+    const client = (0, http_1.getHttpClient)();
+    const { scope, name } = parsePluginKey(pluginKey);
+    const url = `/api/v1/studio/innerapi/plugins/${scope}/${name}/versions/${version}/package`;
+    const response = await client.get(url);
+    if (!response.ok) {
+        throw new error_1.HttpError(response.status, url, `Failed to download plugin: ${String(response.status)} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+async function downloadFromPublic(downloadURL) {
+    const client = new http_client_1.HttpClient({ timeout: 60000 });
+    const response = await client.get(downloadURL);
+    if (!response.ok) {
+        throw new error_1.HttpError(response.status, downloadURL, `Failed to download from public URL: ${String(response.status)} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+const MAX_RETRIES = 2;
+async function withRetry(operation, description, maxRetries = MAX_RETRIES) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries) {
+                (0, logger_1.log)("plugin", `${description} failed, retrying (${String(attempt + 1)}/${String(maxRetries)})...`);
+            }
+        }
+    }
+    throw lastError ?? new error_1.AppError("INTERNAL_RETRY_EXHAUSTED", `${description} failed after ${String(maxRetries)} retries`, { retryable: true, next_actions: ["检查网络后重试，--verbose 可查看重试日志"] });
+}
+/** 插件缓存目录 */
+const PLUGIN_CACHE_DIR = "node_modules/.cache/miaoda-cli/plugins";
+function getPluginCacheDir() {
+    return node_path_1.default.join(process.cwd(), PLUGIN_CACHE_DIR);
+}
+function ensureCacheDir() {
+    const cacheDir = getPluginCacheDir();
+    if (!node_fs_1.default.existsSync(cacheDir)) {
+        node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+    }
+}
+function getTempFilePath(pluginKey, version) {
+    ensureCacheDir();
+    const safeKey = pluginKey.replace(/[/@]/g, "_");
+    const filename = `${safeKey}@${version}.tgz`;
+    return node_path_1.default.join(getPluginCacheDir(), filename);
+}
+async function downloadPlugin(pluginKey, requestedVersion) {
+    const pluginInfo = await getPluginVersion(pluginKey, requestedVersion);
+    let tgzBuffer;
+    if (pluginInfo.downloadApproach === "inner") {
+        tgzBuffer = await withRetry(() => downloadFromInner(pluginKey, pluginInfo.version), "Download");
+    }
+    else {
+        tgzBuffer = await withRetry(() => downloadFromPublic(pluginInfo.downloadURL), "Download");
+    }
+    const tgzPath = getTempFilePath(pluginKey, pluginInfo.version);
+    node_fs_1.default.writeFileSync(tgzPath, tgzBuffer);
+    return {
+        tgzPath,
+        version: pluginInfo.version,
+        pluginInfo,
+    };
+}
+// ── Cache ──
+function getCachePath(pluginKey, version) {
+    ensureCacheDir();
+    const safeKey = pluginKey.replace(/[/@]/g, "_");
+    const filename = `${safeKey}@${version}.tgz`;
+    return node_path_1.default.join(getPluginCacheDir(), filename);
+}
+function hasCachedPlugin(pluginKey, version) {
+    const cachePath = getCachePath(pluginKey, version);
+    return node_fs_1.default.existsSync(cachePath);
+}
+function listCachedPlugins() {
+    const cacheDir = getPluginCacheDir();
+    if (!node_fs_1.default.existsSync(cacheDir)) {
+        return [];
+    }
+    const files = node_fs_1.default.readdirSync(cacheDir);
+    const result = [];
+    for (const file of files) {
+        if (!file.endsWith(".tgz"))
+            continue;
+        const match = /^(.+)@(.+)\.tgz$/.exec(file);
+        if (!match)
+            continue;
+        const [, rawName, version] = match;
+        const name = rawName.replace(/^_/, "@").replace(/_/, "/");
+        const filePath = node_path_1.default.join(cacheDir, file);
+        const stat = node_fs_1.default.statSync(filePath);
+        result.push({ name, version, filePath, size: stat.size, mtime: stat.mtime });
+    }
+    return result;
+}
+function cleanAllCache() {
+    const cacheDir = getPluginCacheDir();
+    if (!node_fs_1.default.existsSync(cacheDir)) {
+        return 0;
+    }
+    const files = node_fs_1.default.readdirSync(cacheDir);
+    let count = 0;
+    for (const file of files) {
+        if (file.endsWith(".tgz")) {
+            node_fs_1.default.unlinkSync(node_path_1.default.join(cacheDir, file));
+            count++;
+        }
+    }
+    return count;
+}
+function cleanPluginCache(pluginKey, version) {
+    const cacheDir = getPluginCacheDir();
+    if (!node_fs_1.default.existsSync(cacheDir)) {
+        return 0;
+    }
+    const safeKey = pluginKey.replace(/[/@]/g, "_");
+    const files = node_fs_1.default.readdirSync(cacheDir);
+    let count = 0;
+    for (const file of files) {
+        if (version) {
+            if (file === `${safeKey}@${version}.tgz`) {
+                node_fs_1.default.unlinkSync(node_path_1.default.join(cacheDir, file));
+                count++;
+            }
+        }
+        else {
+            if (file.startsWith(`${safeKey}@`) && file.endsWith(".tgz")) {
+                node_fs_1.default.unlinkSync(node_path_1.default.join(cacheDir, file));
+                count++;
+            }
+        }
+    }
+    return count;
+}
+// ── Telemetry ──
+async function reportEvents(events) {
+    if (events.length === 0)
+        return true;
+    try {
+        const client = (0, http_1.getHttpClient)();
+        const response = await client.post("/api/v1/studio/innerapi/resource_events", { events });
+        if (!response.ok) {
+            (0, logger_1.log)("telemetry", `Failed to report events: ${String(response.status)} ${response.statusText}`);
+            return false;
+        }
+        const result = (await response.json());
+        if (result.status_code !== "0") {
+            (0, logger_1.log)("telemetry", `API error: ${result.message ?? "unknown"}`);
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        (0, logger_1.log)("telemetry", `Failed to report events: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+async function reportInstallEvent(pluginKey, version) {
+    await reportEvents([
+        {
+            resourceType: "plugin",
+            resourceKey: pluginKey,
+            eventType: "install",
+            details: { version },
+        },
+    ]);
+}
+async function reportCreateInstanceEvent(pluginKey, version) {
+    await reportEvents([
+        {
+            resourceType: "plugin",
+            resourceKey: pluginKey,
+            eventType: "create_instance",
+            details: { version },
+        },
+    ]);
+}

package/dist/api/plugin/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportCreateInstanceEvent = exports.reportInstallEvent = exports.reportEvents = exports.hasCachedPlugin = exports.getCachePath = exports.downloadPlugin = exports.getPluginVersion = exports.getPluginVersions = void 0;
+var api_1 = require("./api");
+Object.defineProperty(exports, "getPluginVersions", { enumerable: true, get: function () { return api_1.getPluginVersions; } });
+Object.defineProperty(exports, "getPluginVersion", { enumerable: true, get: function () { return api_1.getPluginVersion; } });
+Object.defineProperty(exports, "downloadPlugin", { enumerable: true, get: function () { return api_1.downloadPlugin; } });
+Object.defineProperty(exports, "getCachePath", { enumerable: true, get: function () { return api_1.getCachePath; } });
+Object.defineProperty(exports, "hasCachedPlugin", { enumerable: true, get: function () { return api_1.hasCachedPlugin; } });
+Object.defineProperty(exports, "reportEvents", { enumerable: true, get: function () { return api_1.reportEvents; } });
+Object.defineProperty(exports, "reportInstallEvent", { enumerable: true, get: function () { return api_1.reportInstallEvent; } });
+Object.defineProperty(exports, "reportCreateInstanceEvent", { enumerable: true, get: function () { return api_1.reportCreateInstanceEvent; } });

package/dist/api/plugin/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ── Plugin (原 action-plugin) ──
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli/commands/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCommands = registerCommands;
+const index_1 = require("../../cli/commands/plugin/index");
+function registerCommands(program) {
+    (0, index_1.registerPluginCommands)(program);
+}

package/dist/cli/commands/plugin/index.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPluginCommands = registerPluginCommands;
+const index_1 = require("../../../cli/handlers/plugin/index");
+function registerPluginCommands(program) {
+    const pluginCmd = program
+        .command("plugin")
+        .description("插件管理：安装/更新/移除插件包，查询 capability 实例");
+    pluginCmd.action(() => {
+        pluginCmd.outputHelp();
+    });
+    pluginCmd.addHelpText("after", `
+概念
+  - 插件包 (plugin package)：.tgz 包，释放到 ./node_modules/<name>
+  - actionPlugins：./package.json 里的字段，记录 { "@scope/name": "version" }，作为
+                   当前应用项目依赖的插件清单；install/update/remove/init 读写此字段
+  - capability 实例：./server/capabilities/<id>.json，描述该应用下具体使用的
+                    插件实例（pluginKey + formValue + paramsSchema）
+  - 充血 (hydrate)：读取插件 manifest.json，把 capability 与 manifest 的
+                    inputSchema/outputSchema 合并输出完整 action 定义
+
+作用范围
+  本地落点统一为 cwd 下的 package.json / node_modules / server/capabilities。
+  - install / update / init：通过 platform HTTP 拉取插件版本与 .tgz
+  - remove / list / list-packages：纯本地 FS，不走网络
+`);
+    pluginCmd
+        .command("install")
+        .description("拉取插件包并安装到当前应用项目")
+        .argument("<names...>", "插件名，格式 @scope/name 或 @scope/name@version；未带版本默认 latest")
+        .addHelpText("after", `
+行为
+  - 拉取 .tgz 到本地缓存，解压到 ./node_modules/<name>
+  - 在 ./package.json 的 actionPlugins 字段记录 <name>: <version>
+  - 自动补齐插件声明的 peerDependencies
+  - 同版本已安装则跳过（幂等）
+
+前置
+  - 当前工作目录必须包含 package.json
+
+JSON 输出
+  {
+    "installed": ["@demo/example-plugin@1.2.3", ...],
+    "skipped":   ["@demo/existing-plugin", ...],
+    "failed":    [{"name": "@demo/bad", "error": "..."}]
+  }
+
+退出码
+  0：全部成功；1：至少一个失败（其余仍会尝试）
+
+示例
+  $ miaoda plugin install @demo/example-plugin
+  $ miaoda plugin install @demo/example-plugin@1.2.3 @demo/other-plugin --json
+
+  # 报错：包名格式不合法
+  $ miaoda plugin install bad-name
+  Error: Invalid plugin name format: bad-name. Expected: @scope/name or @scope/name@version
+    hint: 示例：@demo/example-plugin 或 @demo/example-plugin@1.2.3
+`)
+        .action(async (names) => { await (0, index_1.handlePluginInstall)({ names }); });
+    pluginCmd
+        .command("update")
+        .description("把已安装插件升级到 latest 版本")
+        .argument("<names...>", "插件名，格式 @scope/name；带 @version 也只取 name 部分")
+        .addHelpText("after", `
+行为
+  - 仅对已在 actionPlugins 里的插件生效；未安装的插件返回 notInstalled
+  - 拉取 latest 版本 .tgz，覆盖安装到 ./node_modules/<name>
+  - 版本一致则跳过（幂等）；版本变化时同步写回 actionPlugins
+
+前置
+  - 当前工作目录必须包含 package.json
+
+JSON 输出
+  {
+    "updated":      [{"name": "...", "from": "1.0.0", "to": "1.2.3"}],
+    "skipped":      ["..."],            // 已是 latest
+    "notInstalled": ["..."],            // 未安装，未尝试
+    "failed":       [{"name": "...", "error": "..."}]
+  }
+
+退出码
+  0：全部成功或仅有 notInstalled；1：至少一个 failed
+
+示例
+  $ miaoda plugin update @demo/example-plugin
+  $ miaoda plugin update @demo/a @demo/b --json
+
+  # 场景：插件未登记（非抛错，出现在返回的 notInstalled）
+  $ miaoda plugin update @demo/not-installed --json
+  {"updated":[],"skipped":[],"notInstalled":["@demo/not-installed"],"failed":[]}
+`)
+        .action(async (names) => { await (0, index_1.handlePluginUpdate)({ names }); });
+    pluginCmd
+        .command("remove")
+        .description("从当前项目移除一个已安装的插件")
+        .argument("<name>", "插件名，格式 @scope/name")
+        .addHelpText("after", `
+行为
+  - 删除 ./node_modules/<name> 目录
+  - 从 ./package.json 的 actionPlugins 字段移除对应条目
+
+前置
+  - 插件必须已登记在 actionPlugins 中，否则抛 NOT_FOUND
+
+JSON 输出
+  {"removed": "@demo/example-plugin"}
+
+示例
+  $ miaoda plugin remove @demo/example-plugin
+
+  # 报错：插件未登记
+  $ miaoda plugin remove @demo/not-installed
+  Error: Plugin @demo/not-installed is not installed
+    hint: 运行 miaoda plugin list-packages 查看已安装插件
+`)
+        .action((name) => { (0, index_1.handlePluginRemove)({ name }); });
+    pluginCmd
+        .command("init")
+        .description("按 package.json 的 actionPlugins 批量安装所有插件")
+        .addHelpText("after", `
+行为
+  - 读取 ./package.json 的 actionPlugins，对每个条目按固定版本安装
+  - 已经是目标版本的跳过（幂等），用于 clone 项目后首次同步 / CI
+
+前置
+  - 当前工作目录必须包含 package.json
+
+JSON 输出
+  {
+    "installed": ["@demo/a@1.0.0", ...],
+    "skipped":   ["@demo/b", ...],
+    "failed":    [{"name": "...", "error": "..."}]
+  }
+  当 actionPlugins 为空时输出 {"message": "No plugins found in package.json", "installed": [], "skipped": []}
+
+退出码
+  0：全部成功；1：至少一个 failed
+
+示例
+  $ miaoda plugin init --json
+
+  # 报错：当前目录没有 package.json
+  $ miaoda plugin init
+  Error: package.json not found in current directory
+    hint: 在应用项目根目录运行
+`)
+        .action(async () => { await (0, index_1.handlePluginInit)(); });
+    pluginCmd
+        .command("list")
+        .description("列出当前项目的 capability 实例（./server/capabilities/*.json）")
+        .option("--summary", "不 hydrate（不充血），直接返回 capability 文件的原始 JSON")
+        .option("--id <id>", "只查询指定 id 的单个 capability")
+        .addHelpText("after", `
+行为
+  - 扫描 ./server/capabilities/*.json（排除 capabilities.json）
+  - 默认对每条 capability 做 hydrate：读取 ./node_modules/<pluginKey>/manifest.json，
+    合并得到每个 action 的最终 inputSchema / outputSchema
+  - hydrate 失败不抛错，每条结果上带 _hydrateError 字段
+
+前置
+  - ./server/capabilities 目录必须存在，否则抛 NOT_FOUND
+  - 充血模式下需要对应插件已安装在 ./node_modules，否则该条 _hydrateError
+
+JSON 输出
+  - 无 --id：数组，元素为 hydrate 后的 capability，含 actions[].inputSchema 等
+  - 带 --id：单个对象
+  - 带 --summary：不做 hydrate，返回原始 RawCapability 结构
+
+示例
+  $ miaoda plugin list --json
+  $ miaoda plugin list --id cap_demo_xxx --json
+  $ miaoda plugin list --summary --json
+
+  # 报错：capability 目录不存在
+  $ miaoda plugin list
+  Error: server/capabilities directory not found
+    hint: 当前目录必须是含 server/capabilities/ 的应用项目
+`)
+        .action(async (opts) => { await (0, index_1.handlePluginList)(opts); });
+    pluginCmd
+        .command("list-packages")
+        .description("列出 package.json actionPlugins 里已声明的插件包")
+        .addHelpText("after", `
+行为
+  - 读取 ./package.json 的 actionPlugins 字段
+  - 只看声明，不校验 ./node_modules 下是否实际存在
+
+JSON 输出
+  {
+    "plugins": [{"name": "@demo/example-plugin", "version": "1.2.3"}, ...],
+    "total":   <number>
+  }
+
+示例
+  $ miaoda plugin list-packages --json
+
+  # 报错：当前目录没有 package.json
+  $ miaoda plugin list-packages
+  Error: package.json not found in current directory
+    hint: 在应用项目根目录运行
+`)
+        .action(() => { (0, index_1.handlePluginListPlugins)(); });
+}

package/dist/cli/commands/shared.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appIdOption = appIdOption;
+exports.softRequiredOption = softRequiredOption;
+exports.resolveAppId = resolveAppId;
+exports.withHelp = withHelp;
+exports.failArgs = failArgs;
+const commander_1 = require("commander");
+const error_1 = require("../../utils/error");
+/** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
+function appIdOption() {
+    return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
+}
+/**
+ * soft-required: Commander 类型上 optional，runtime 校验必填。
+ */
+function softRequiredOption(name, desc) {
+    return new commander_1.Option(name, desc);
+}
+/** 解析 appId，CLI flag > env > 抛错 */
+function resolveAppId(opts) {
+    const id = opts.appId ?? process.env.MIAODA_APP_ID;
+    if (!id) {
+        throw new error_1.AppError("APP_ID_MISSING", "未指定应用", {
+            next_actions: [
+                "传入 --app-id <id>",
+                "设置 export MIAODA_APP_ID=<id>",
+            ],
+        });
+    }
+    return id;
+}
+/** 包裹 handler，缺 soft-required 参数时打 help 并退出 */
+function withHelp(cmd, handler) {
+    return async (opts) => {
+        try {
+            await handler(opts);
+        }
+        catch (err) {
+            if (err instanceof error_1.AppError && err.code === "ARGS_INVALID") {
+                process.stderr.write(`Error: ${err.message}\n`);
+                cmd.outputHelp();
+                process.exitCode = 2;
+                return;
+            }
+            throw err;
+        }
+    };
+}
+/** 参数校验失败时抛出，配合 withHelp 自动打 help */
+function failArgs(message) {
+    throw new error_1.AppError("ARGS_INVALID", message);
+}

package/dist/cli/handlers/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../../cli/handlers/plugin/index"), exports);