@lark-apaas/miaoda-cli 0.1.0 → 0.1.1

package/dist/api/file/detect.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * 判断用户输入应当作为 **path**（后端存储 key）还是 **file_name** 处理。
+ *
+ * 背景：
+ * - file-storage 的 `filePath` 是 bucket 内 unique 的对象存储 key，既可能是用户在
+ *   upload 时指定的自定义路径（如 `logs/2026/data.csv`），也可能是后端 preUpload
+ *   自动生成的 fileKey（固定长度的 alphanumeric，可带扩展名，如 `abcdef1234567890.png`）
+ * - `file_name` 是上传时随文件一起登记的人类可读名字（可以含空格 / 中文 / 重复）
+ *
+ * CLI 默认让用户直接传一个字符串，不强制加 `--name`。当字符串"看起来像后端 key"时
+ * 走 path 语义（HEAD 直连），否则走 file_name 语义（FilterExpression `name eq`）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikePath = looksLikePath;
+exports.toAbsolutePath = toAbsolutePath;
+/**
+ * 后端 preUpload 生成的 fileKey 特征（实测 file-storage 响应）：
+ *   - base 段是 **16+ 位纯十进制数字**（snowflake ID，如 `1863152526384148`）
+ *   - 可选 1~2 段扩展名（`.ext` / `.tar.gz`），每段 ≤ 10 位字母或数字
+ *
+ * 例：
+ *   - `1863152526384148`              ✓  （16 位 snowflake）
+ *   - `1863152526384148.jpg`          ✓
+ *   - `1858533158493259.tar.gz`       ✓  （2 段扩展）
+ *   - `618a80ddb3b7e1496.jpg`         ✗  （含字母，是用户起的 file_name）
+ *   - `1234`                          ✗  （位数不够）
+ *   - `报告.xlsx` / `my file.doc`     ✗  （非 ASCII / 含空格）
+ *
+ * 修紧到纯数字是为了避开"用户上传时把文件命成 16+ 位 hex"的真实场景 ——
+ * 后端 fileKey 至今都是纯十进制，二者不重叠。
+ */
+const BACKEND_KEY_PATTERN = /^\d{16,}(?:\.[a-zA-Z0-9]{1,10}){0,2}$/;
+/**
+ * 输入"看起来像 path"的判断：
+ * 1. 以 `/` 开头 → 显式绝对路径
+ * 2. 含 `/`（但不以 `/` 开头）→ 命名空间形式的 key，如 `logs/2026/data.csv`
+ * 3. 匹配 `BACKEND_KEY_PATTERN` → 后端生成的 fileKey
+ * 其他情况一律视为 file_name。
+ */
+function looksLikePath(input) {
+    if (!input)
+        return false;
+    if (input.startsWith("/"))
+        return true;
+    if (input.includes("/"))
+        return true;
+    return BACKEND_KEY_PATTERN.test(input);
+}
+/**
+ * 规整为带前导 `/` 的展示/HEAD 形式。
+ * 便于从 auto-detected 的 "abc123...xyz.txt" 回到统一的 `/abc123...xyz.txt`。
+ */
+function toAbsolutePath(input) {
+    return input.startsWith("/") ? input : `/${input}`;
+}

package/dist/api/file/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAbsolutePath = exports.looksLikePath = exports.resetBucketCache = exports.getDefaultBucketId = exports.parseTimeFilterMs = exports.resolveInputs = exports.deleteFiles = exports.downloadFile = exports.signDownload = exports.uploadFile = exports.statFile = exports.listFiles = void 0;
+var api_1 = require("./api");
+Object.defineProperty(exports, "listFiles", { enumerable: true, get: function () { return api_1.listFiles; } });
+Object.defineProperty(exports, "statFile", { enumerable: true, get: function () { return api_1.statFile; } });
+Object.defineProperty(exports, "uploadFile", { enumerable: true, get: function () { return api_1.uploadFile; } });
+Object.defineProperty(exports, "signDownload", { enumerable: true, get: function () { return api_1.signDownload; } });
+Object.defineProperty(exports, "downloadFile", { enumerable: true, get: function () { return api_1.downloadFile; } });
+Object.defineProperty(exports, "deleteFiles", { enumerable: true, get: function () { return api_1.deleteFiles; } });
+Object.defineProperty(exports, "resolveInputs", { enumerable: true, get: function () { return api_1.resolveInputs; } });
+Object.defineProperty(exports, "parseTimeFilterMs", { enumerable: true, get: function () { return api_1.parseTimeFilterMs; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "getDefaultBucketId", { enumerable: true, get: function () { return client_1.getDefaultBucketId; } });
+Object.defineProperty(exports, "resetBucketCache", { enumerable: true, get: function () { return client_1.resetBucketCache; } });
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "looksLikePath", { enumerable: true, get: function () { return detect_1.looksLikePath; } });
+Object.defineProperty(exports, "toAbsolutePath", { enumerable: true, get: function () { return detect_1.toAbsolutePath; } });

package/dist/api/file/parsers.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAttachment = parseAttachment;
+exports.parseHead = parseHead;
+/** 安全读取字符串字段（空字符串回退为默认值） */
+function str(value, fallback = "") {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+/** 安全读取数字字段（非正值回退到 0） */
+function int(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.trunc(value);
+    }
+    return 0;
+}
+function readSize(meta) {
+    if (!meta)
+        return 0;
+    const v = meta.size ??
+        meta.fileSize ??
+        meta.file_size ??
+        meta.contentLength ??
+        0;
+    return int(v);
+}
+/**
+ * 展示层 path 统一带前导 `/`（对齐 PRD / SKILL 里的示例）。
+ * 后端存储的 path 实际是无前导 `/` 的，这里补齐。
+ */
+function toDisplayPath(p) {
+    if (!p)
+        return p;
+    return p.startsWith("/") ? p : `/${p}`;
+}
+/** 将后端 attachment 结构映射为 CLI FileInfo（用于 ls） */
+function parseAttachment(att) {
+    const rawPath = str(att.filePath, str(att.name));
+    const info = {
+        file_name: str(att.name),
+        path: toDisplayPath(rawPath),
+        size_bytes: readSize(att.metadata),
+        type: str(att.metadata?.mimeType),
+        uploaded_at: str(att.createdAt),
+    };
+    const downloadUrl = str(att.downloadURL);
+    if (downloadUrl)
+        info.download_url = downloadUrl;
+    // uploaded_by 从 createdBy.name 映射（后端返 {userID, name, email, ...}，空代表匿名）
+    const uploader = str(att.createdBy?.name);
+    if (uploader)
+        info.uploaded_by = uploader;
+    return info;
+}
+/** 将后端 head 响应映射为 CLI FileInfo（用于 stat） */
+function parseHead(data, filePath) {
+    const outer = data?.metadata ?? {};
+    const inner = outer.metadata ?? {};
+    const info = {
+        file_name: str(outer.name),
+        path: toDisplayPath(filePath || str(outer.name)),
+        size_bytes: readSize(inner),
+        type: str(inner.mimeType),
+        uploaded_at: str(inner.lastModified),
+    };
+    const downloadUrl = str(outer.downloadURL);
+    if (downloadUrl)
+        info.download_url = downloadUrl;
+    const uploader = str(outer.createdBy?.name);
+    if (uploader)
+        info.uploaded_by = uploader;
+    return info;
+}

package/dist/api/file/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ── API 响应外层信封（file-storage inner API 统一结构） ──
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/index.js

@@ -33,6 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.plugin = void 0;
+exports.db = exports.file = exports.plugin = void 0;
 const _plugin = __importStar(require("../api/plugin/index"));
+const _file = __importStar(require("../api/file/index"));
+const _db = __importStar(require("../api/db/index"));
 exports.plugin = { ..._plugin };
+exports.file = { ..._file };
+exports.db = { ..._db };

package/dist/api/plugin/api.js

@@ -22,7 +22,7 @@ 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 client = (0, http_1.getRuntimeHttpClient)();
     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}`);
@@ -58,7 +58,7 @@ function parsePluginKey(key) {
     return { scope: match[1], name: match[2] };
 }
 async function downloadFromInner(pluginKey, version) {
-    const client = (0, http_1.getHttpClient)();
+    const client = (0, http_1.getRuntimeHttpClient)();
     const { scope, name } = parsePluginKey(pluginKey);
     const url = `/api/v1/studio/innerapi/plugins/${scope}/${name}/versions/${version}/package`;
     const response = await client.get(url);
@@ -203,7 +203,7 @@ async function reportEvents(events) {
     if (events.length === 0)
         return true;
     try {
-        const client = (0, http_1.getHttpClient)();
+        const client = (0, http_1.getRuntimeHttpClient)();
         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}`);

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

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDbCommands = registerDbCommands;
+const index_1 = require("../../../cli/handlers/db/index");
+function registerDbCommands(program) {
+    const dbCmd = program
+        .command("db")
+        .description("应用数据库（PostgreSQL）的命令行操作集合。")
+        .usage("<command> [flags]")
+        // --env 注册在 db 父级，spec 把它列入 db --help 的 Global Flags；
+        // leaf 命令仍各自接收 --env 值（commander 解析时父级 option 自动适用于子命令）
+        .option("--env <name>", "指定目标环境（dev / online，仅专家模式应用支持）");
+    dbCmd.action(() => {
+        dbCmd.outputHelp();
+    });
+    dbCmd
+        .command("sql")
+        .summary("执行任意 SQL（SELECT / DML / DDL，支持多条分号分隔）")
+        .description("执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
+        "支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n" +
+        "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
+        .usage("<query> [flags]")
+        .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
+        .action(async function (query) {
+        await (0, index_1.handleDbSql)(query, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - SELECT 结果超过 1000 行直接报错（RESULT_SET_TOO_LARGE），不做隐式截断。
+    需要分页时请在 SQL 中用 LIMIT / OFFSET。
+  - 多条语句不自动包事务：失败时后续不执行、已成功的不回滚。
+    需要原子性请显式 BEGIN; ...; COMMIT;
+  - --env 仅在专家模式应用且已 migration init 后可用。
+  - NULL 值在 --json 中是 JSON 原生 null，pretty / 管道中是字面字符串 NULL。
+
+Examples:
+  $ miaoda db sql "SELECT id, name, age FROM users LIMIT 10"
+  id    name     age
+  1001  Alice    28
+  1002  Bob      35
+
+  $ miaoda db sql "INSERT INTO users (name, age) VALUES ('Dave', 25)"
+  ✓ 1 row inserted
+
+  $ miaoda db sql < migration.sql
+  Statement 1: ✓ CREATE TABLE orders
+  Statement 2: ✓ 10 rows inserted
+  ✓ 2 statements executed
+
+  # 报错：SQL 语法错误
+  $ miaoda db sql "SELCT * FROM users"
+  Error: Syntax error at or near "SELCT"
+    hint: Check SQL keyword spelling. Did you mean "SELECT"?
+
+  # 报错：结果超过 1000 行
+  $ miaoda db sql "SELECT * FROM users"
+  Error: Result set exceeds the 1000-row limit (query would return 15234 rows)
+    hint: Add \`LIMIT <n>\` to your SQL to narrow the result.
+`);
+    // schema 二级资源分组
+    const schemaCmd = dbCmd
+        .command("schema")
+        .summary("查看数据库表结构")
+        .description("查看应用数据库的表结构信息。")
+        .usage("<command> [flags]");
+    schemaCmd.action(() => {
+        schemaCmd.outputHelp();
+    });
+    schemaCmd
+        .command("list")
+        .summary("列出所有表的概览（表名、行数、大小等）")
+        .description("列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n" +
+        "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
+        .usage("[flags]")
+        .action(async function () {
+        await (0, index_1.handleDbSchemaList)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema list
+  name      description   rows   size      columns   updated_at
+  users     用户信息          1523   2.1 MB    5         3h ago
+  orders    订单记录          8891   12.4 MB   8         2d ago
+  products  商品目录          342    512 KB    6         2026-03-15
+
+  $ miaoda db schema list --json name,rows
+  {
+    "data": [
+      {"name": "users", "rows": 1523},
+      {"name": "orders", "rows": 8891},
+      {"name": "products", "rows": 342}
+    ],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
+    schemaCmd
+        .command("get")
+        .summary("查看单表完整结构（列定义、索引、约束）")
+        .description("查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n" +
+        "默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
+        .action(async function (table) {
+        await (0, index_1.handleDbSchemaGet)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema get users
+  CREATE TABLE users (
+    id uuid DEFAULT gen_random_uuid() NOT NULL,
+    name varchar(100) NOT NULL,
+    email varchar(255),
+    age integer,
+    PRIMARY KEY (id),
+    UNIQUE (email)
+  );
+  COMMENT ON TABLE users IS '用户信息';
+  ...
+
+  # 报错：表不存在
+  $ miaoda db schema get userss
+  Error: Table 'userss' does not exist
+    hint: Did you mean 'users'? Run \`miaoda db schema list\` to see all tables.
+`);
+    // data 二级资源分组
+    const dataCmd = dbCmd
+        .command("data")
+        .summary("表数据导入导出")
+        .description("表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。")
+        .usage("<command> [flags]");
+    dataCmd.action(() => {
+        dataCmd.outputHelp();
+    });
+    dataCmd
+        .command("import")
+        .summary("从本地 CSV / JSON 文件导入数据到表")
+        .description("从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误（主键冲突、\n" +
+        "类型不匹配、列名不匹配等）会回滚已插入的所有行。\n" +
+        "不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
+        .usage("<file> [flags]")
+        .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
+        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
+        .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
+        .action(async function (file) {
+        await (0, index_1.handleDbDataImport)(file, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 目标表必须已存在；CSV 表头 / JSON 顶层 key 必须与表字段名完全一致。
+  - 导入为原子操作：遇到错误回滚所有已插入行，不会出现部分导入的中间状态。
+  - 仅支持 .csv 和 .json 文件扩展名。
+
+Examples:
+  $ miaoda db data import users.csv
+  ✓ Imported users.csv → table 'users' (1523 rows)
+
+  $ miaoda db data import data.csv --table users
+  ✓ Imported data.csv → table 'users' (1523 rows)
+
+  # 报错：CSV 表头与字段不匹配
+  $ miaoda db data import users.csv
+  Error: Column 'full_name' in CSV does not match any column in table 'users'
+    hint: Expected columns: id, name, email, age. Check CSV header row.
+
+  # 报错：主键冲突（已回滚）
+  $ miaoda db data import users.csv
+  Error: Primary key conflict at row 42 (id=1001 already exists), 0 rows imported
+    hint: Deduplicate input data, or remove conflicting rows first with
+          \`miaoda db sql "DELETE FROM users WHERE id IN (...)"\`.
+`);
+    dataCmd
+        .command("export")
+        .summary("导出表数据到本地 CSV / JSON / SQL 文件")
+        .description("把指定表的所有数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--format <fmt>", "导出格式 csv / json / sql，默认 csv（sql 输出 INSERT 语句，可用 db sql < file.sql 回放）")
+        .option("-f, --file <path>", "输出文件路径，默认 <表名>.<格式>")
+        .option("--limit <n>", "最多导出行数（不超过 5000）")
+        .action(async function (table) {
+        await (0, index_1.handleDbDataExport)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - SQL 格式生成 INSERT 语句，可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放。
+  - 文件已存在时默认报错（FILE_ALREADY_EXISTS），用 --force 覆盖或 -f 改路径。
+
+Examples:
+  $ miaoda db data export users
+  ✓ Exported users → users.csv (1523 rows)
+
+  $ miaoda db data export users --format json
+  ✓ Exported users → users.json (1523 rows)
+
+  $ miaoda db data export users --format sql -f users_backup.sql
+  ✓ Exported users → users_backup.sql (1523 rows)
+
+  $ miaoda db data export users -f ~/Desktop/users.csv
+  ✓ Exported users → ~/Desktop/users.csv (1523 rows)
+
+  # 报错：文件已存在
+  $ miaoda db data export users
+  Error: Output file 'users.csv' already exists
+    hint: Use -f to specify a different path, or --force to overwrite.
+`);
+}

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

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFileCommands = registerFileCommands;
+const index_1 = require("../../../cli/handlers/file/index");
+const error_1 = require("../../../utils/error");
+/**
+ * commander option 校验器：把 --limit <n> 解析成正整数（≥1）。
+ * 默认值（如 "50"）会先经过这里被规范化成 number。
+ * 非整数 / 负数 / 0 抛 AppError("ARGS_INVALID")，由 main.ts 的全局 catch
+ * 走 emitError，同时 process.exitCode 由 commander 自然为 1。
+ */
+function parsePositiveInt(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer (got '${raw}')`);
+    }
+    return n;
+}
+function registerFileCommands(program) {
+    const fileCmd = program
+        .command("file")
+        .description("应用文件存储（TOS）的命令行操作集合。操作对象是 UGC 资源（用户上传的文件、应用运行时\n" +
+        "生成的报表 / 导出文件等），不涉及代码仓库里的本地文件。")
+        .usage("<command> [flags]");
+    fileCmd.action(() => {
+        fileCmd.outputHelp();
+    });
+    fileCmd
+        .command("ls")
+        .summary("列出 / 筛选文件")
+        .description("列出当前应用存储里的文件，支持按文件名、大小、上传时间筛选，以及游标分页。\n" +
+        "默认 pretty 输出省略 download_url（列宽限制），需获取请用 --json。")
+        .usage("[query] [flags]")
+        .argument("[query]", "筛选值：以 / 开头视为路径精确匹配，否则按文件名精确匹配")
+        .option("--path <path>", "按路径精确匹配")
+        .option("--name <name>", "按文件名精确匹配")
+        .option("--type <mime>", "按 MIME 类型筛选（如 image/png）")
+        .option("--size-gt <size>", "文件大小下限（支持 B / KB / MB / GB）")
+        .option("--size-lt <size>", "文件大小上限（支持 B / KB / MB / GB）")
+        .option("--uploaded-since <time>", "上传时间下限（晚于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--uploaded-until <time>", "上传时间上限（早于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--limit <n>", "单次返回上限（正整数,默认 50）", parsePositiveInt, 50)
+        .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
+        .option("--all", "自动翻页返回全部结果")
+        .action(async (query, opts) => {
+        await (0, index_1.handleFileLs)({ ...opts, query });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file ls
+  file_name    path                                size      type              uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png         3h ago
+  hero.jpg     /images/1858537546760217.jpg        128 KB    image/jpeg        2d ago
+  report.pdf   /docs/1858537546760218.pdf          2.1 MB    application/pdf   2026-04-10
+
+  $ miaoda file ls --name logo.png
+  file_name    path                                size      type        uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png   3h ago
+
+  $ miaoda file ls --uploaded-since 7d --size-gt 1MB
+  ...
+`);
+    fileCmd
+        .command("stat")
+        .summary("查看单文件元数据")
+        .description("查看单文件完整元数据，含 download_url（应用内消费）。\n" +
+        "需要公网可访问的临时链接请用 `file sign` 生成 signed_url。")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
+        .action(async (file, opts) => {
+        await (0, index_1.handleFileStat)(file, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐，全局唯一）或 file_name。
+  - file_name 重名时报 AMBIGUOUS_FILE_NAME，需先 \`ls --name\` 拿到 path 再调用。
+
+Examples:
+  $ miaoda file stat /images/brand/1858537546760216.png
+       file_name:  logo.png
+            path:  /images/brand/1858537546760216.png
+            size:  24 KB (24580 bytes)
+            type:  image/png
+     uploaded_by:  alice
+     uploaded_at:  2026-04-15 10:30:00
+    download_url:  /spark/app/.../1858537546760216.png
+
+  # 报错：file_name 多匹配
+  $ miaoda file stat logo.png
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
+    fileCmd
+        .command("cp")
+        .summary("上传或下载文件（方向由路径前缀自动判断）")
+        .description("上传或下载文件，方向由 src/dst 路径前缀自动判断：\n" +
+        "  / 开头           → 远程 TOS 路径\n" +
+        "  ./、~/、裸文件名  → 本地路径")
+        .usage("<src> <dst> [flags]")
+        .argument("<src>", "源：本地文件路径或远程文件路径 / 文件名")
+        .argument("<dst>", "目标：本地路径或远程路径")
+        .option("--rename <name>", "上传后在远端使用的新文件名")
+        .action(async (src, dst, opts) => {
+        await (0, index_1.handleFileCp)(src, dst, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - 单文件上限 100 MB，超过请拆分或用 web console 上传。
+  - 同目录下允许同 file_name 并存（每次上传生成新的 path），不会因重名失败。
+  - 下载时 src 必须是完整 path（裸 file_name 会被识别为本地路径）。
+  - 上传成功返回 download_url，可写入数据库 / 应用代码作为永久引用。
+
+Examples:
+  # 上传：本地 → 远程
+  $ miaoda file cp ./logo.png /images/brand/
+  ✓ Uploaded logo.png → /images/brand/1858537546760216.png
+         file_name:  logo.png
+              path:  /images/brand/1858537546760216.png
+              size:  24 KB (24580 bytes)
+              type:  image/png
+      download_url:  /spark/app/.../1858537546760216.png
+
+  # 下载：远程 → 本地
+  $ miaoda file cp /images/brand/1858537546760216.png ~/Desktop/
+  ✓ Downloaded 1858537546760216.png → ~/Desktop/logo.png (24 KB)
+
+  # 上传时改名
+  $ miaoda file cp ./photo.png /images/ --rename avatar.png
+  ✓ Uploaded photo.png → /images/1858537546760301.png
+
+  # 报错：本地源文件不存在
+  $ miaoda file cp ./missing.png /images/
+  Error: Local file './missing.png' does not exist
+
+  # 报错：超过上传上限
+  $ miaoda file cp ./video.mp4 /videos/
+  Error: File size 230 MB exceeds the 100 MB upload limit
+    hint: Split the file, or use the web console for large uploads.
+`);
+    fileCmd
+        .command("rm")
+        .summary("删除一个或多个文件")
+        .description("删除一个或多个文件。<file> 可传 path（推荐）或 file_name，可混用。\n" +
+        "操作不可撤销（不进回收站），TTY 下默认会要求二次确认。")
+        .usage("[paths...] [flags]")
+        .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
+        .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
+        .option("-y, --yes", "跳过交互确认；非交互场景必加")
+        .action(async (paths, opts) => {
+        await (0, index_1.handleFileRm)(paths, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - 删除不可撤销，没有回收站。
+  - 批量场景下失败项不影响其他项；全部成功退出码 0，任意一项失败退出码 1。
+  - --json 输出每项保留输入顺序，含 status: "ok" | "error" 字段。
+
+Examples:
+  # 单文件删除（TTY 下需确认）
+  $ miaoda file rm /images/brand/1858537546760216.png
+  ? Delete '/images/brand/1858537546760216.png'? (y/N) y
+  ✓ Deleted /images/brand/1858537546760216.png
+
+  # 批量删除（混用 path 与 file_name）
+  $ miaoda file rm /images/A.png /images/B.png /docs/C.pdf --yes
+  ✓ Deleted /images/A.png
+  ✓ Deleted /images/B.png
+  ✓ Deleted /docs/C.pdf
+  Deleted 3 of 3 files
+
+  # 部分失败（其他项仍会被删除）
+  $ miaoda file rm logo.png missing.png report.pdf --yes
+  ✓ Deleted logo.png
+  ✗ missing.png: File does not exist
+  ✓ Deleted report.pdf
+  Deleted 2 of 3 files (1 failed)
+
+  # 报错：file_name 多匹配
+  $ miaoda file rm logo.png --yes
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
+    fileCmd
+        .command("sign")
+        .summary("生成公网可访问的临时下载链接")
+        .description("生成 signed_url——公网可直接访问的临时下载链接，带过期时间。\n" +
+        "仅在需要浏览器打开 / 公网分享时使用；应用代码内引用文件请用 download_url\n" +
+        "（来自 cp 或 stat），无需 sign。")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名")
+        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 等单位（默认 1d，最长 30d）")
+        .action(async (file, opts) => {
+        await (0, index_1.handleFileSign)(file, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐）或 file_name；重名报 AMBIGUOUS_FILE_NAME。
+  - signed_url 会过期，不要持久化到数据库。永久引用请用 download_url。
+
+Examples:
+  $ miaoda file sign /images/brand/1858537546760216.png
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=86400
+
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 30d
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=2592000
+
+  # 报错：过期时间超过上限
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 60d
+  Error: Expires duration '60d' exceeds the maximum of 30d
+    hint: Maximum allowed value is 30d. Use \`--expires 30d\` for the longest link.
+`);
+}

package/dist/cli/commands/index.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCommands = registerCommands;
 const index_1 = require("../../cli/commands/plugin/index");
+const index_2 = require("../../cli/commands/file/index");
+const index_3 = require("../../cli/commands/db/index");
 function registerCommands(program) {
     (0, index_1.registerPluginCommands)(program);
+    (0, index_2.registerFileCommands)(program);
+    (0, index_3.registerDbCommands)(program);
 }

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

@@ -5,7 +5,8 @@ const index_1 = require("../../../cli/handlers/plugin/index");
 function registerPluginCommands(program) {
     const pluginCmd = program
         .command("plugin")
-        .description("插件管理：安装/更新/移除插件包，查询 capability 实例");
+        .description("插件管理：安装/更新/移除插件包，查询 capability 实例")
+        .usage("<command> [flags]");
     pluginCmd.action(() => {
         pluginCmd.outputHelp();
     });