zero-ai 1.0.75 → 1.0.79

package/r2mo-init/.obsidian/types.json

@@ -0,0 +1,28 @@
+{
+  "types": {
+    "aliases": "aliases",
+    "cssclasses": "multitext",
+    "tags": "tags",
+    "TQ_explain": "checkbox",
+    "TQ_extra_instructions": "text",
+    "TQ_short_mode": "checkbox",
+    "TQ_show_backlink": "checkbox",
+    "TQ_show_cancelled_date": "checkbox",
+    "TQ_show_created_date": "checkbox",
+    "TQ_show_depends_on": "checkbox",
+    "TQ_show_done_date": "checkbox",
+    "TQ_show_due_date": "checkbox",
+    "TQ_show_edit_button": "checkbox",
+    "TQ_show_id": "checkbox",
+    "TQ_show_on_completion": "checkbox",
+    "TQ_show_postpone_button": "checkbox",
+    "TQ_show_priority": "checkbox",
+    "TQ_show_recurrence_rule": "checkbox",
+    "TQ_show_scheduled_date": "checkbox",
+    "TQ_show_start_date": "checkbox",
+    "TQ_show_tags": "checkbox",
+    "TQ_show_task_count": "checkbox",
+    "TQ_show_tree": "checkbox",
+    "TQ_show_urgency": "checkbox"
+  }
+}

package/r2mo-init/task/command/ex-api.yaml.example

@@ -0,0 +1,13 @@
+# 复制为 ex-api.yaml 后按项目修改
+# ai ex-api 使用 .r2mo/task/command/ex-api.yaml
+metadata:
+  identifier: "核心标识符"
+  brief: "接口描述"
+  resource: "resource.ambient"
+  level: 1
+  ptype: "权限集 S_PERM_SET 类型"
+  pname: "权限集 S_PERM_SET 名称"
+# target 可选；存在时需配置 ZERO_MODULE 且 DPA 目录 zero-exmodule-{module} 存在
+# target:
+#   root: "ZERO_MODULE"
+#   module: "ambient"

package/r2mo-init/task/task-001.md

@@ -0,0 +1,144 @@
+---
+runAt: 2026-02-12.22-47-18
+title: 开发 ai ex-api 命令
+---
+
+# 任务
+
+开发 `ai ex-api` 命令对已经开发好的 API 进行授权，此命令为固定命令，要完成全套执行操作，系统重启后要保证权限生效，且命令必须拥有幂等性。
+
+### 前置条件
+
+1. 当前项目中 `.r2mo/task/command/ex-api.yaml` 配置文件必须存在，不存在则直接退出，并且提示用户配置文件缺失。
+2. 环境变量必须，检查这些环境变量必须存在，不存在则跳出
+	```bash
+	export Z_DB_TYPE="MYSQL"   # 数据库类型: MYSQL /   SQLSERVER / ORACLE / POSTGRESQL  
+	export Z_DB_HOST="127.0.0.1"  
+	export Z_DB_PORT="3306"
+	export Z_DBS_INSTANCE=""
+	export Z_DB_APP_USER="r2admin"  
+	export Z_DB_APP_PASS="r2admin"
+	```
+3. 环境变量检查（这个步骤必须）
+	```bash
+	export Z_APP_ID=???
+	export Z_TENANT=???
+	export Z_SIGMA=???
+	```
+4. `ex-api.yaml` 的基本格式
+	```yaml
+	metadata:
+	  identifier: "核心标识符"
+	  brief: "接口描述"
+	  resource: "resource.ambient"
+	  level: ???
+	  ptype: "权限集 S_PERM_SET 类型"
+	  pname: "权限集 S_PERM_SET 名称"
+      keyword: "app.test.data"
+	target:
+	  root: "ZERO_MODULE"
+	  module: "ambient"
+	```
+5. 存在 target 配置多检查一个环境变量 ZERO_MODULE，并且检查`{ZERO_MODULE}/zero-exmodule-{module}` 是否一个标准的DPA架构，若不是则命令退出
+
+### 执行逻辑
+
+1. 检查前置条件是否满足，不检查 `ex-api.yaml` 的格式问题
+2. 参数检查：
+	- `-r "<METHOD> <uri>"` ，其中 `r` 的全称是 `request`
+	- `-s`，其中 `s` 的全称是 `skip`，若如此则只生成 Excel，可能最终不完美（没做去重检查），但交给开发人员处理
+3. 定义表信息
+	- `S_RESOURCE`：资源定义
+	- `S_ACTION`：操作定义
+	- `S_PERMISSION`：权限定义
+	- `S_PERM_SET`：权限集定义
+	- `R_ROLE_PERM`：角色权限定义
+4. 先检查 `S_ACTION` 中是否已经存在当前参数，按列名开发（`METHOD, URI`；不唯一时追加 `SIGMA, APP_ID, TENANT_ID`），只有当 `METHOD, URI` 无法提取唯一记录时追加后续三个查询条件
+	- 若存在不创建数据记录，提取 `S_ACTION` 中的 ID
+	- 若不存在则创建数据记录 / `S_RESOURCE` 需要同步创建（因为 `S_RESOURCE` 资源是新的）
+5. 询问用户：追加新权限 / 执行已有权限，若执行已有权限，按 `S_PERMISSION` 中的 identifier 进行查询让用户选择追加到那个权限（追加到已有权限则直接跳过额外的数据库操作）
+6. 提取数据库中已有的 `S_ROLE` 角色信息，可多选，让用户选择当前 API 授权给哪些角色
+
+## 输出说明
+
+### 数据库输出
+
+- 同步五张表的信息，注意要幂等性，不引起异常
+
+### Excel输出
+
+1. 如果存在 `target` 的配置，则输出项目根目录应该是 `${ZERO_MODULE}/zero-exmodule-{module}`，它必须是 DPA 架构，生成的 `excel` 的信息应该位于 `${ZERO_MODULE}/zero-exmodule-{module}/zero-exmodule-{module}-domain` 的资源目录下，开发时查看一下，有一个 `plugins/***/security/RBAC_RESOURCE` 目录。
+2. Excel 直接覆盖，不提示选择文件；文件名固化为 `identifier-method-uri.xlsx`（uri 中 `/` 转 `-`）；无 target 时输出到 **-api** 项目下 `plugins/.../security/`。
+3. `plugins/***/security/RBAC_ROLE/ADMIN.SUPER/`（固定）写入带 **falcon** 前缀的同名文件（`falcon-identifier-method-uri.xlsx`）；若没有 `target` 则写入当前/ -api 项目下的 `plugins/zero-launcher-configuration/security/` 目录下。
+4. `plugins` 都是从 maven 项目的 src/main/resources 开始计算
+5. 在目标路径下生成对应的 `*.xlsx` 或更改现有的内容
+
+### Excel 样式约定
+
+- **默认模板**：模板位于 R2MO-INIT 项目固定路径 `src/_template/EXCEL/ex-api`，与执行命令所在项目无关；任意项目执行 ai ex-api 均使用该默认模板驱动。
+- **仅填数据，样式与模板完全一致**：除写入的数据单元格 value 外，不修改任何 style（格式、颜色、边框、合并单元格、行数等）。不删行、不清格式、不填色、不设边框，输出与模板在视觉和结构上一致。
+
+### 属性规则
+
+-  `S_RESOURCE`
+	- 资源名称，从 `ex-api.yaml` 中提取
+	- `modelRole` -> UNION 固定值
+	- 资源编码 `res` 前缀加 `S_ACTION` 的 code
+	- `identifier / type / level` 这些配置文件中有
+- `S_ACTION`
+	- 操作编码，读取当前 `identifier` 下的核心操作编码追加 `act` 前缀
+	- 操作名称同 `brief`（和资源一样）
+	- 操作级别同 `S_RESOURCE`
+- `S_PERMISSION`
+	- 权限名称同 `brief`（备注也想通）
+	- 权限码 `perm` 前缀
+	- 所属模型 `identifier`
+- `S_PERM_SET`：参考前边规则提取，配置文件中有
+- 如果出现 `keyword`，则所有编码名称直接追加，不计算，比如
+	- `res.${keyword}`
+	- `act.${keyword}`
+	- `perm.${keyword}`
+
+### 核心输出
+
+- 数据库中建立关系
+- Excel中建立管理
+- Excel中的UUID值固化
+
+### 全局列补充（仅数据库，不写入 Excel）
+
+仅**实体表**写入全局列：S_RESOURCE、S_ACTION、S_PERMISSION。若表中包含以下列则一并写入；Excel 中不输出这些列。关系表 R_ROLE_PERM 只有 ROLE_ID、**PERM_ID** 两列，无全局列。
+
+| 列名 | 取值来源 |
+|------|----------|
+| `sigma` | 环境变量 `Z_SIGMA` |
+| `appId` | 环境变量 `Z_APP_ID` |
+| `tenantId` | 环境变量 `Z_TENANT` |
+| `scope` | 环境变量 `Z_APP` |
+| `createdBy` | 固定值 `9a0d5018-33ad-4c64-80bf-8ae7947c482f`（R2_BY） |
+| `updatedBy` | 固定值 `9a0d5018-33ad-4c64-80bf-8ae7947c482f`（R2_BY） |
+| `createdAt` | 当前时间（R2_NOW） |
+| `updatedAt` | 当前时间（R2_NOW） |
+
+- 全局列在开发时按建表固定写好，执行时不查元数据；Excel 输出中不包含上述全局列，仅做数据库同步。
+
+### 表列信息（开发时对齐，执行时不查元数据）
+
+**所有 SQL 与 Excel 表头列名在开发时按 RBAC 建表（如 zero-exmodule-rbac Flyway）固定写好；ai ex-api 执行时只执行 DML，不访问数据库元数据（不执行 SHOW COLUMNS 等）。**
+
+- **R_ROLE_PERM**：关系表，仅两列 **ROLE_ID**、**PERM_ID**（无 `PERMISSION_ID`）。
+- S_RESOURCE、S_ACTION、S_PERMISSION 实体表列名与 Flyway 一致：S_ACTION 用 **SIGMA/APP_ID/TENANT_ID**（非 Z_*），S_PERMISSION 用 **COMMENT**（非 REMARK）；唯一性查询带 SIGMA 以保证幂等。全局列（SIGMA/APP_ID/TENANT_ID/CREATED_BY/UPDATED_BY/CREATED_AT/UPDATED_AT）在代码中写死，不运行时查表。
+- 开发阶段可用 `node script/scan-rbac-schema.js`（可选 `--write`）核对库表列名与脚本一致；不修改 RBAC 的 Flyway 配置。
+
+### 执行约定（仅 DML，不查元数据）
+
+- ai ex-api 执行时**只执行 DML**（SELECT/INSERT/INSERT IGNORE），**不访问数据库元数据**（如 SHOW COLUMNS）。
+- 表列名在**开发时**按 RBAC 建表（如 Flyway）固定写好，运行时不再查询表结构。
+- **假设**：执行时数据表已存在且结构固定；**禁止**表扫描、DDL、元数据提取（已知表结构，无需运行时获取）。
+
+### 完整打印（成功与失败）
+
+- **启动**：配置路径、request 参数、skip、数据库连接信息。
+- **步骤**：已存在/已创建 S_RESOURCE、S_ACTION、S_PERMISSION，R_ROLE_PERM 同步角色数，Excel 写出路径。
+- **成功**：`[ex-api] 执行完成（幂等）` 及汇总（ACTION_ID、RESOURCE_ID、PERMISSION_ID、授权角色数、Excel 路径）。
+- **失败**：`[ex-api] 执行失败` + 错误信息、错误码、sqlMessage、sql 语句、堆栈。

package/r2mo-init/task/task-002.md

@@ -0,0 +1,4 @@
+---
+runAt: 2026-02-12.23-18-53
+title: 任务
+---

package/r2mo-init/task/task-003.md

@@ -0,0 +1,4 @@
+---
+runAt: 2026-02-13.08-58-12
+title: 任务
+---

package/r2mo-init/task/thread

@@ -0,0 +1 @@
+5

package/src/commander/ex-api.json

@@ -1,9 +1,8 @@
 {
     "executor": "executeExApi",
-    "description": "对已开发 API 进行授权（数据库 + Excel），需 .r2mo/task/command/ex-api.yaml",
+    "description": "从 ex-api 目录加载多份 yaml（metadata.r），多选后执行授权（数据库+Excel），处理成功后移至 backup 并加 .bak",
     "command": "ex-api",
     "options": [
-        {"name": "request", "alias": "r", "description": "请求方法与 URI，格式：\"<METHOD> <uri>\"，如 \"GET /api/ambient\""},
         {"name": "skip", "alias": "s", "type": "boolean", "description": "仅生成 Excel，跳过去重等检查", "default": false}
     ]
 }

package/src/commander/ex-crud.json

@@ -1 +1 @@
-{"executor":"executeExCrud","description":"按 ex-crud.yaml 从模板生成 CRUD Excel 及 RBAC 授权（RBAC_CRUD + falcon），需 .r2mo/task/command/ex-crud.yaml","command":"ex-crud","options":[{"name":"skip","alias":"s","type":"boolean","description":"仅生成 CRUD 文件，跳过数据库与角色选择","default":false}]}
+{"executor":"executeExCrud","description":"从 ex-crud 目录加载多份 yaml，多选后按 metadata 从模板生成 CRUD Excel 及 RBAC 授权，处理成功后移至 backup 并加 .bak","command":"ex-crud","options":[{"name":"skip","alias":"s","type":"boolean","description":"仅生成 CRUD 文件，跳过数据库与角色选择","default":false}]}

package/src/commander-ai/fn.ex.api.js

@@ -8,7 +8,7 @@ const yaml = require("js-yaml");
 const inquirer = require("inquirer");
 const { v4: uuidv4 } = require("uuid");
 
-const CONFIG_PATH = ".r2mo/task/command/ex-api.yaml";
+const CONFIG_DIR = ".r2mo/task/command/ex-api";
 const REQUIRED_ENV_DB = ["Z_DB_TYPE", "Z_DB_HOST", "Z_DB_PORT", "Z_DBS_INSTANCE", "Z_DB_APP_USER", "Z_DB_APP_PASS"];
 const REQUIRED_ENV_APP = ["Z_APP_ID", "Z_TENANT", "Z_SIGMA"];
 const R2_BY_UUID = "9a0d5018-33ad-4c64-80bf-8ae7947c482f";
@@ -175,124 +175,73 @@ function isDpaRoot(dir) {
     return fs.existsSync(apiDir) && fs.existsSync(domainDir);
 }
 
-module.exports = async (options) => {
-    const cwd = process.cwd();
-
-    // 1. 前置：配置文件必须存在；缺失时在配置路径中写入模板
-    const configFullPath = path.resolve(cwd, CONFIG_PATH);
-    if (!fs.existsSync(configFullPath)) {
-        const configDir = path.dirname(configFullPath);
-        if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
-        const template = `# ai ex-api 使用此配置，请按项目修改
-# 参数格式：-r "<METHOD> <uri>"  uri 必须以 /api 为前缀
-metadata:
-  identifier: "核心标识符"
-  brief: "接口描述"
-  resource: "resource.ambient"
-  level: 1
-  ptype: "权限集 S_PERM_SET 类型"
-  pname: "权限集 S_PERM_SET 名称"
-  # keyword 可选；若存在则编码为 res.\${keyword} / act.\${keyword} / perm.\${keyword}，否则按规则计算
-  # keyword: "app.test.data"
-# target 可选；存在时需配置 ZERO_MODULE 且 DPA 目录 zero-exmodule-{module} 存在
-# target:
-#   root: "ZERO_MODULE"
-#   module: "ambient"
-`;
-        fs.writeFileSync(configFullPath, template, "utf-8");
-        Ec.info("配置文件缺失，已在下列路径写入模板：" + configFullPath);
-        Ec.info("请编辑后重新执行。参数格式：  -r \"<METHOD> <uri>\"  （uri 必须以 /api 为前缀）");
-        Ec.info("示例：  ai ex-api -r \"GET /api/ambient\"");
-        process.exit(1);
-    }
+/** 校验 metadata.r：须为 "<METHOD> <uri>"，METHOD 常见动词，uri 以 /api 开头 */
+function validateExApiR(r) {
+    if (!r || typeof r !== "string") return { valid: false, error: "r 为空" };
+    const s = String(r).trim();
+    if (!s) return { valid: false, error: "r 为空" };
+    const parts = s.split(/\s+/);
+    if (parts.length < 2) return { valid: false, error: "r 须为 \"<METHOD> <uri>\" 两段" };
+    const method = (parts[0] || "").toUpperCase();
+    const uri = parts.slice(1).join(" ").trim();
+    const allowed = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+    if (!allowed.includes(method)) return { valid: false, error: "METHOD 须为 " + allowed.join("/") };
+    if (!uri.startsWith("/api")) return { valid: false, error: "uri 须以 /api 为前缀" };
+    return { valid: true };
+}
 
-    // 2. 环境变量：先加载 app.env 再检查
-    const appEnvPath = resolveAppEnvPath(cwd);
-    if (!appEnvPath) {
-        Ec.error(".r2mo/app.env 不存在；DPA 下也未找到 {id}-api/.r2mo/app.env");
-        process.exit(1);
-    }
-    loadAppEnv(appEnvPath);
-    Ec.info("已加载环境变量：" + appEnvPath);
-    checkEnv(REQUIRED_ENV_DB, "数据库环境变量");
-    checkEnv(REQUIRED_ENV_APP, "应用环境变量（Z_APP_ID / Z_TENANT / Z_SIGMA）");
+/** 解析 ex-api 配置目录：cwd / 上级 / 上上级 */
+function resolveExApiConfigDir(cwd) {
+    const primary = path.resolve(cwd, CONFIG_DIR);
+    if (fs.existsSync(primary) && fs.statSync(primary).isDirectory()) return primary;
+    const parent = path.resolve(cwd, "..", CONFIG_DIR);
+    if (fs.existsSync(parent) && fs.statSync(parent).isDirectory()) return parent;
+    const grand = path.resolve(cwd, "..", "..", CONFIG_DIR);
+    if (fs.existsSync(grand) && fs.statSync(grand).isDirectory()) return grand;
+    return primary;
+}
 
-    // 3. 解析 ex-api.yaml（不校验格式）
-    let config;
-    try {
-        config = yaml.load(fs.readFileSync(configFullPath, "utf-8"));
-    } catch (e) {
-        Ec.error("ex-api.yaml 解析失败：" + e.message);
-        process.exit(1);
-    }
-    if (!config || !config.metadata) {
-        Ec.error("ex-api.yaml 需包含 metadata 节点");
-        process.exit(1);
-    }
+/** 表格化打印 ex-api 汇总 */
+function printExApiTable(results) {
+    const rows = results.map((r) => ({
+        identifier: r.identifier || "—",
+        request: r.request || "—",
+        ok: r.ok ? "✓" : "✗",
+        error: r.error || "—"
+    }));
+    const col = (arr, key) => arr.map((x) => String(x[key] != null ? x[key] : ""));
+    const max = (arr) => Math.max(2, ...arr.map((s) => (s && s.length) || 0));
+    const wId = max(col(rows, "identifier"));
+    const wReq = Math.min(max(col(rows, "request")), 48);
+    const wErr = Math.min(max(col(rows, "error")), 32);
+    const sep = " | ";
+    Ec.info("[ex-api] 汇总：");
+    Ec.info("  " + "identifier".padEnd(wId) + sep + "request".padEnd(wReq) + sep + "ok" + sep + "error".padEnd(wErr));
+    rows.forEach((r) => Ec.info("  " + (r.identifier + "").padEnd(wId) + sep + (r.request + "").slice(0, wReq).padEnd(wReq) + sep + r.ok + sep + (r.error + "").slice(0, wErr)));
+}
 
+/** 单条 API 执行：使用 config.metadata.r 作为 request，执行 DB + Excel，返回汇总 */
+async function runOneExApi(cwd, conn, config, requestRaw, skip) {
     const metadata = config.metadata;
     const target = config.target;
-    if (target && target.root && target.module) {
-        const zeroModule = process.env.ZERO_MODULE;
-        if (!zeroModule || !zeroModule.trim()) {
-            Ec.error("存在 target 配置时，环境变量 ZERO_MODULE 必须已设置");
-            process.exit(1);
-        }
-        const dpaRoot = path.resolve(zeroModule, `zero-exmodule-${target.module}`);
-        if (!fs.existsSync(dpaRoot) || !isDpaRoot(dpaRoot)) {
-            Ec.error(`ZERO_MODULE 下 DPA 目录不是标准架构：${dpaRoot}`);
-            Ec.info("需存在 pom.xml 且包含 xxx-api、xxx-domain 子目录");
-            process.exit(1);
-        }
-    }
-
-    // 4. 参数：-r "<METHOD> <uri>" ，-s 可选
-    const parsed = Ut.parseArgument(options);
-    const skip = parsed.skip === true || process.argv.includes("-s") || process.argv.includes("--skip");
     let method = "";
     let uri = "";
-    const requestRaw = parsed.request;
     if (requestRaw && String(requestRaw).trim()) {
         const parts = String(requestRaw).trim().split(/\s+/);
         if (parts.length >= 2) {
             method = parts[0].toUpperCase();
             uri = parts.slice(1).join(" ").trim();
-        } else if (parts.length === 1) {
-            Ec.error("参数 -r 格式应为 \"<METHOD> <uri>\"，例如 \"GET /api/ambient\"");
-            process.exit(1);
         }
     }
     if (!skip && (!method || !uri)) {
-        Ec.error("缺少必需参数：请求方法与 URI");
-        Ec.info("参数格式：  -r \"<METHOD> <uri>\"  或  --request \"<METHOD> <uri>\"");
-        Ec.info("示例：  ai ex-api -r \"GET /api/ambient\"（uri 必须以 /api 为前缀）");
-        process.exit(1);
+        return { identifier: metadata.identifier || "—", request: requestRaw || "—", ok: false, error: "缺少 metadata.r 或格式非 \"<METHOD> <uri>\"" };
     }
     if (!skip && uri && !uri.trim().startsWith("/api")) {
-        Ec.error("参数 uri 必须以 /api 为前缀。");
-        Ec.info("当前 uri：" + (uri || ""));
-        Ec.info("示例：  ai ex-api -r \"GET /api/ambient\"");
-        process.exit(1);
+        return { identifier: metadata.identifier || "—", request: requestRaw || "—", ok: false, error: "uri 必须以 /api 为前缀" };
     }
 
-    Ec.execute("ai ex-api：配置已加载，环境与参数检查通过。");
-
-    const dbConfig = {
-        host: process.env.Z_DB_HOST || "localhost",
-        port: parseInt(process.env.Z_DB_PORT || "3306", 10),
-        user: process.env.Z_DB_APP_USER,
-        password: process.env.Z_DB_APP_PASS,
-        database: process.env.Z_DBS_INSTANCE
-    };
-
-    const mysql = require("mysql2/promise");
-    Ec.info("[ex-api] 配置：" + CONFIG_PATH + " | request=" + (requestRaw || "") + " | skip=" + skip);
-    let conn = await mysql.createConnection(dbConfig);
-    Ec.info("[ex-api] 数据库已连接：" + (dbConfig.database || "") + " @" + (dbConfig.host || "") + ":" + (dbConfig.port || ""));
-
-    // 约定：执行时数据表已存在且结构固定，仅执行 DML（SELECT/INSERT/INSERT IGNORE），禁止表扫描、DDL、元数据查询（如 SHOW COLUMNS）。
     try {
-        const appId = process.env.Z_APP_ID;
+    const appId = process.env.Z_APP_ID;
         const tenantId = process.env.Z_TENANT;
         const sigma = process.env.Z_SIGMA;
 
@@ -799,13 +748,153 @@ metadata:
             Ec.info("[ex-api]   📦 R_ROLE_PERM 本次写入（ROLE_ID, PERM_ID）：");
             insertedRolePerms.forEach((r, i) => Ec.info("[ex-api]      [" + (i + 1) + "] " + r.ROLE_ID + ", " + r.PERM_ID));
         }
+        return {
+            identifier: metadata.identifier || "—",
+            request: requestRaw || "—",
+            actionId: actionId || "—",
+            resourceId: resourceId || "—",
+            permissionId: permissionId || "—",
+            roleCount: roleIds ? roleIds.length : 0,
+            outResPath: outResPath || "—",
+            outRolePath: outRolePath || "—",
+            ok: true
+        };
     } catch (err) {
         Ec.error("[ex-api] 执行失败：" + (err && err.message));
-        if (err && err.code) Ec.error("[ex-api] 错误码：" + err.code);
-        if (err && err.sqlMessage) Ec.error("[ex-api] SQL：" + err.sqlMessage);
-        if (err && err.sql) Ec.error("[ex-api] 语句：" + (typeof err.sql === "string" ? err.sql : err.sql.join(" ")));
-        if (err && err.stack) Ec.error("[ex-api] 堆栈：" + err.stack);
+        return {
+            identifier: (metadata && metadata.identifier) || "—",
+            request: requestRaw || "—",
+            actionId: "—",
+            resourceId: "—",
+            permissionId: "—",
+            roleCount: 0,
+            outResPath: "—",
+            outRolePath: "—",
+            ok: false,
+            error: (err && err.message) || String(err)
+        };
+    }
+}
+
+module.exports = async (options) => {
+    const cwd = process.cwd();
+    const configDir = resolveExApiConfigDir(cwd);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+        const templatePath = path.join(configDir, "ex-api.yaml");
+        const template = `# ai ex-api 使用此配置，请按项目修改
+metadata:
+  r: "GET /api/ambient"
+  identifier: "核心标识符"
+  brief: "接口描述"
+  resource: "resource.ambient"
+  level: 1
+  ptype: "权限集 S_PERM_SET 类型"
+  pname: "权限集 S_PERM_SET 名称"
+  # keyword 可选
+# target 可选；存在时需 ZERO_MODULE 与 zero-exmodule-{module}
+# target:
+#   root: "ZERO_MODULE"
+#   module: "ambient"
+`;
+        fs.writeFileSync(templatePath, template, "utf-8");
+        Ec.info("配置目录缺失，已创建并写入模板：" + templatePath);
+        Ec.info("请编辑后重新执行：  ai ex-api");
+        process.exit(1);
+    }
+
+    const backupDir = path.join(configDir, "backup");
+    const allEntries = fs.readdirSync(configDir, { withFileTypes: true });
+    const yamlFiles = allEntries.filter((e) => !e.isDirectory() && e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml")));
+    const entries = [];
+    for (const e of yamlFiles) {
+        const f = e.name;
+        const full = path.join(configDir, f);
+        try {
+            const config = yaml.load(fs.readFileSync(full, "utf-8"));
+            if (!config || !config.metadata) continue;
+            const r = config.metadata.r != null ? String(config.metadata.r).trim() : "";
+            if (!r) {
+                Ec.info("[ex-api] 跳过（无 metadata.r）：" + f);
+                continue;
+            }
+            const valid = validateExApiR(r);
+            if (!valid.valid) {
+                Ec.info("[ex-api] 警告（r 不合法，已跳过）：" + f + "，" + (valid.error || ""));
+                continue;
+            }
+            const label = (config.metadata.identifier || f) + " | " + (config.metadata.brief || r);
+            entries.push({ path: full, config, label });
+        } catch (_) {}
+    }
+
+    if (entries.length === 0) {
+        Ec.error("[ex-api] 无有效配置：请在 " + configDir + " 下添加含 metadata.r 的 yaml");
         process.exit(1);
+    }
+
+    const answer = await inquirer.prompt([
+        { type: "checkbox", name: "selected", message: "选择要执行的 API（多选）", choices: entries.map((e) => ({ name: e.label, value: e.path })) }
+    ]);
+    const selectedPaths = answer && answer.selected && Array.isArray(answer.selected) ? answer.selected : [];
+    if (selectedPaths.length === 0) {
+        Ec.info("未选择任何项，退出");
+        process.exit(0);
+    }
+
+    const appEnvPath = resolveAppEnvPath(cwd);
+    if (!appEnvPath) {
+        Ec.error(".r2mo/app.env 不存在；DPA 下也未找到 {id}-api/.r2mo/app.env");
+        process.exit(1);
+    }
+    loadAppEnv(appEnvPath);
+    checkEnv(REQUIRED_ENV_DB, "数据库环境变量");
+    checkEnv(REQUIRED_ENV_APP, "应用环境变量（Z_APP_ID / Z_TENANT / Z_SIGMA）");
+
+    const dbConfig = {
+        host: process.env.Z_DB_HOST || "localhost",
+        port: parseInt(process.env.Z_DB_PORT || "3306", 10),
+        user: process.env.Z_DB_APP_USER,
+        password: process.env.Z_DB_APP_PASS,
+        database: process.env.Z_DBS_INSTANCE
+    };
+    const parsed = Ut.parseArgument(options);
+    const skip = parsed.skip === true || process.argv.includes("-s") || process.argv.includes("--skip");
+
+    const mysql = require("mysql2/promise");
+    let conn;
+    try {
+        conn = await mysql.createConnection(dbConfig);
+        Ec.info("[ex-api] 数据库已连接，执行 " + selectedPaths.length + " 条 API");
+        const results = [];
+        for (const configPath of selectedPaths) {
+            const config = yaml.load(fs.readFileSync(configPath, "utf-8"));
+            const requestRaw = config.metadata && config.metadata.r != null ? String(config.metadata.r).trim() : "";
+            if (!requestRaw) {
+                results.push({ identifier: config.metadata?.identifier || "—", request: "—", ok: false, error: "无 metadata.r" });
+                continue;
+            }
+            const valid = validateExApiR(requestRaw);
+            if (!valid.valid) {
+                Ec.info("[ex-api] 警告（r 不合法，跳过执行）：" + path.basename(configPath) + "，" + (valid.error || ""));
+                results.push({ identifier: config.metadata?.identifier || "—", request: requestRaw, ok: false, error: valid.error || "r 不合法" });
+                continue;
+            }
+            Ec.info("[ex-api] 处理：" + (config.metadata.identifier || path.basename(configPath)) + " (" + requestRaw + ")");
+            const one = await runOneExApi(cwd, conn, config, requestRaw, skip);
+            results.push(one);
+            if (one.ok) {
+                if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });
+                const bakPath = path.join(backupDir, path.basename(configPath) + ".bak");
+                try {
+                    fs.renameSync(configPath, bakPath);
+                    Ec.info("[ex-api] 已备份：" + path.basename(configPath) + " -> backup/" + path.basename(configPath) + ".bak");
+                } catch (errBak) {
+                    Ec.info("[ex-api] 备份失败（已忽略）：" + configPath + "，" + (errBak && errBak.message));
+                }
+            }
+        }
+        printExApiTable(results);
     } finally {
         if (conn) await conn.end();
     }