@lark-apaas/miaoda-cli 0.1.19-alpha.6dad9cd → 0.1.19-alpha.7856c6b

package/README.md

@@ -11,12 +11,17 @@ pnpm add -g @lark-apaas/miaoda-cli
 ## 使用
 
 ```bash
-# 设置默认应用（需要应用上下文的命令可用 --app-id 覆盖）
+# 设置默认应用（需要应用上下文的命令从 MIAODA_APP_ID 读取）
 export MIAODA_APP_ID=app_demo_xxx
 
 # 文件操作
 miaoda file ls
 miaoda file upload ./local/path
+
+# 评论操作
+miaoda comment list --json
+miaoda comment list --only-unresolved --json
+miaoda comment resolve 1703677660120110076 --json
 ```
 
 JSON 结构化输出（Agent 推荐）：
@@ -41,9 +46,38 @@ miaoda file ls --output json
 | `miaoda file ...`          | 文件操作：上传、下载、元数据、签名下载、批量删除     |
 | `miaoda db ...`            | 数据操作：SQL 执行、表结构查询、数据导入导出         |
 | `miaoda observability ...` | 线上日志、链路、前端源码堆栈反查、监控指标、运营指标 |
+| `miaoda comment ...`       | 应用评论：查看评论列表、解决评论                     |
+| `miaoda registry ...`      | 组件 registry：列出 / copy-in design-html SDK 文件（本地执行）     |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 组件 registry（design-html）
+
+`miaoda registry` 为 design-html 技术栈提供 shadcn 式的「组件 registry」：把 SDK 文件**拷进**当前项目（copy-in），而非作为依赖安装。registry 是独立 npm 包，按运行时分发（design-html → buildless runtime → `@lark-apaas/coding-registry-buildless`）。
+
+前置：当前目录（或 `--dir`）已走过 `miaoda app init`，`.spark/meta.json` 含 `stack=design-html`。
+
+```bash
+# 列出可用 SDK 条目（输出各文件 USAGE 注释块原文，便于 Agent 直接读用法）
+miaoda registry list
+miaoda registry list --json
+
+# 把条目 copy-in 到当前项目（自动按 USAGE 块的 Depends 解析依赖闭包一并拷入）
+miaoda registry add deck-slide
+miaoda registry add foo.css theme --dry-run        # 只报告将写 / 将跳，不落盘
+miaoda registry add deck-slide --overwrite         # 目标已存在时覆盖（默认跳过以保护改动）
+```
+
+要点：
+
+- **条目**：registry 包根 `components/` · `scripts/` · `stylesheets/` 三个顶层目录（任意深度）下的代码文件即条目。USAGE 注释块**可选**（有则提供描述 + Depends，无则空描述、无依赖）；包根直放文件、其它目录、非代码文件都不算条目。
+- **寻址**：`add` / `Depends` 的 token 可写三种形式 —— `name`（去扩展名，如 `foo`）/ 完整文件名（如 `foo.css`）/ relPath（如 `stylesheets/foo.css`）。`name` **不要求唯一**，`list --json` 的 `file`（relPath）是永远无歧义的 canonical 地址。
+- **多匹配全拉**：token 命中多个同名条目时全部 copy-in（如 `add foo` 把 `foo.jsx` + `foo.css` 一起拉），想只要其一就用完整文件名或 relPath。
+- **拍平落地**：所有文件**拍平**到项目根（`scripts/deck-slide.js` → 项目 `deck-slide.js`，不保留子目录）；闭包内同名 basename 撞车时后者覆盖前者。
+- **skip-by-disk**：项目已有同名（拍平后的 basename）文件默认跳过，`--overwrite` 才覆盖；不写任何安装记账文件，项目文件树即状态。
+- **add 回执带 usage**：`add` 结果的 `entries` 只列**你请求的条目**（不含被 `Depends` 传递拉进来的依赖——依赖照常落地在 `added`/`skipped`，但那是"管道"），逐条给出 `usage`（USAGE 块原文）与 `dependsOn`，Agent `add` 完即可直接读用法，无需再 `registry list`。请求的条目即使已存在被跳过也回带 usage（`status` 标 `added`/`skipped`，据此判断磁盘上是 registry 版还是你改过的旧版）。`--json` 结构为 `{registryVersion, added, skipped, dryRun, entries}`；pretty（默认）输出 `registry@<ver>` + `added:`/`skipped:` 逗号列表 + 各请求条目的 USAGE 块，稳定 label、无 JSON 数组、无截断，对 Agent 与人同样可读。
+- `--version <ver>` 指定 registry 包版本或 dist-tag（缺省 `latest`），`--dir <path>` 指定项目目录（缺省当前目录）。
+
 ## 全局参数
 
 - `--json [fields]`：输出结构化 JSON，可选字段级选择（如 `--json id,name`）。
@@ -55,7 +89,7 @@ miaoda file ls --output json
 ## 环境变量
 
 - `MIAODA_APP_ID`：默认应用 ID，等价于 `--app-id`。
-- `MIAODA_CANARY_HEADER`：HTTP 请求的 `x-tt-env` 小流量头取值。未设置时默认 `boe_miaoda_doubao`；设为空字符串则不带该头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。值形如 `ppe_xxx` 时额外带上 `x-use-ppe: 1`。
+- `MIAODA_CANARY_HEADER`：HTTP 请求的 `x-tt-env` 小流量头取值。未设置时默认 `boe_miaoda_ccm`；设为空字符串则不带该头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。值形如 `ppe_xxx` 时额外带上 `x-use-ppe: 1`。
 
 ## 输出契约
 

package/bin/miaoda.js

@@ -1,2 +1,34 @@
 #!/usr/bin/env node
+
+// BOE 沙箱自动转发到 @dev 版本：让 BOE 沙箱内始终跑最新 dev 包，
+// 本地版本仅作引导壳。避免无限递归靠 __MIAODA_BOE_FORWARDED sentinel。
+// 逃生舱：MIAODA_DISABLE_BOE_FORWARD=1 时无论如何走本地。
+const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === "boe";
+const alreadyForwarded = process.env.__MIAODA_BOE_FORWARDED === "1";
+const disabled = process.env.MIAODA_DISABLE_BOE_FORWARD === "1";
+
+if (isBoe && !alreadyForwarded && !disabled) {
+  const { spawnSync } = require("node:child_process");
+
+  if (process.env.MIAODA_DEBUG_BOE_FORWARD === "1" || process.argv.includes("--verbose")) {
+    process.stderr.write("[miaoda] BOE detected, forwarding to @lark-apaas/miaoda-cli@dev via npx\n");
+  }
+
+  const args = process.argv.slice(2);
+  const result = spawnSync(
+    "npx",
+    ["-y", "@lark-apaas/miaoda-cli@dev", ...args],
+    {
+      stdio: "inherit",
+      env: { ...process.env, __MIAODA_BOE_FORWARDED: "1" },
+    },
+  );
+
+  if (result.error) {
+    process.stderr.write(`[miaoda] BOE forward failed: ${result.error.message}\n`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}
+
 require("../dist/main.js");

package/dist/api/comment/api.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getComments = getComments;
+exports.resolveComment = resolveComment;
+const http_1 = require("../../utils/http");
+/**
+ * 评论接口走管理端 inner-api（getHttpClient + 小写 status_code 信封），与 app / deploy /
+ * observability 等域一致：统一的 verbose 请求/响应日志、错误映射、信封解析，不再域内自实现。
+ */
+/** GET /api/v1/studio/innerapi/apps/:appID/comments — 获取应用评论列表 */
+async function getComments(appID, onlyUnresolved = false) {
+    let url = `/api/v1/studio/innerapi/apps/${encodeURIComponent(appID)}/comments`;
+    if (onlyUnresolved)
+        url += '?onlyUnresolved=true';
+    const body = await (0, http_1.getInnerApi)(url, {
+        errPrefix: 'Failed to list comments',
+    });
+    return body.items ?? [];
+}
+/** POST /api/v1/studio/innerapi/apps/:appID/comments/:commentID/resolve — 解决评论 */
+async function resolveComment(appID, commentID) {
+    const url = `/api/v1/studio/innerapi/apps/${encodeURIComponent(appID)}/comments/${encodeURIComponent(commentID)}/resolve`;
+    await (0, http_1.postInnerApi)(url, undefined, { errPrefix: 'Failed to resolve comment' });
+}

package/dist/api/comment/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveComment = exports.getComments = void 0;
+var api_1 = require("./api");
+Object.defineProperty(exports, "getComments", { enumerable: true, get: function () { return api_1.getComments; } });
+Object.defineProperty(exports, "resolveComment", { enumerable: true, get: function () { return api_1.resolveComment; } });

package/dist/api/comment/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * 评论相关类型，镜像 inner-api 返回的 data 结构（snake_case 原样，与 lark docs 评论体一致）。
+ * ID 为 int64 itoa 后的字符串；时间为秒级 epoch。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/index.js

@@ -33,16 +33,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deploy = exports.app = exports.observability = exports.db = exports.file = exports.plugin = void 0;
+exports.comment = exports.deploy = exports.app = exports.observability = 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"));
 const _observability = __importStar(require("../api/observability/index"));
 const _app = __importStar(require("../api/app/index"));
 const _deploy = __importStar(require("../api/deploy/index"));
+const _comment = __importStar(require("../api/comment/index"));
 exports.plugin = { ..._plugin };
 exports.file = { ..._file };
 exports.db = { ..._db };
 exports.observability = { ..._observability };
 exports.app = { ..._app };
 exports.deploy = { ..._deploy };
+exports.comment = { ..._comment };

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

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCommentCommands = registerCommentCommands;
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/comment/index");
+function registerCommentCommands(program) {
+    const commentCmd = program
+        .command('comment')
+        .description('应用评论：查看评论列表、解决评论')
+        .usage('<command> [flags]');
+    commentCmd.action(() => {
+        commentCmd.outputHelp();
+    });
+    commentCmd.addHelpText('after', `
+作用范围
+  操作当前应用的评论。应用上下文：--app-id <id> 或环境变量 MIAODA_APP_ID。
+`);
+    const listCmd = commentCmd
+        .command('list')
+        .description('查看应用评论列表')
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option('--only-unresolved', '仅返回未解决的评论', false)
+        .addHelpText('after', `
+JSON 输出
+  {"data": [{"comment_id": "...", "content": "...", "user_id": "...",
+             "finish": 0, "resolved": false, "create_time": 1700000000}]}
+
+示例
+  $ miaoda comment list --json
+  $ miaoda comment list --only-unresolved --json
+`);
+    listCmd.action((0, shared_1.withHelp)(listCmd, async (rawOpts) => {
+        (0, shared_1.rejectCliOverride)(listCmd, 'appId');
+        await (0, index_1.handleCommentList)({
+            appId: rawOpts.appId,
+            onlyUnresolved: rawOpts.onlyUnresolved,
+        });
+    }));
+    const resolveCmd = commentCmd
+        .command('resolve')
+        .description('把一条评论标记为已解决')
+        .argument('<commentID>', '待解决的评论 ID')
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText('after', `
+JSON 输出
+  {"data": {"comment_id": "...", "resolved": true}}
+
+示例
+  $ miaoda comment resolve 1703677660120110076 --json
+`);
+    resolveCmd.action((0, shared_1.withHelp)(resolveCmd, async (commentId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(resolveCmd, 'appId');
+        await (0, index_1.handleCommentResolve)(commentId, { appId: rawOpts.appId });
+    }));
+}

package/dist/cli/commands/deploy/modern.js

@@ -59,15 +59,18 @@ JSON 输出（stdout）
     }));
     const patchCmd = deployCmd
         .command('patch')
-        .description('design-html 增量发布：按文件 create/update/delete，.html 变化时同步 routes.json')
+        .description('design-html 增量发布：按文件 create/update/delete，.html 增删时同步 routes.json')
         .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--update <relpath>', '覆盖已有文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
+        .option('--sessionId <id>', '会话 ID，发布时透传给下游（可选）')
         .addHelpText('after', `
 --dir 为项目目录（与 deploy 同名参数，默认当前目录）。
 仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
-禁绝对路径与 ".."。--create/--update 的本地文件必须存在。改动集含 .html 时自动重算并随包
-更新 routes.json。
+禁绝对路径与 ".."。--create/--update 的本地文件必须存在。.html 被新增/删除（路由集合变化）
+时自动重算并随包更新 routes.json；纯 --update 现有 .html 只改内容，不动 routes.json。
+routes.json 每项为 {path, file}：path 为相对路径（不含 base 前缀，由消费侧拼接），file 为
+对应源文件（如 / → index.html）。
 
 JSON 输出
   {"data": {"upsertCount": <n>, "deleteCount": <n>, "actionsSent": <n>, "routesRegenerated": <bool>}}
@@ -84,6 +87,7 @@ JSON 输出
             creates: rawOpts.create,
             updates: rawOpts.update,
             deletes: rawOpts.delete,
+            sessionId: rawOpts.sessionId,
         });
     }));
 }

package/dist/cli/commands/index.js

@@ -9,7 +9,8 @@ const index_4 = require("../../cli/commands/app/index");
 const index_5 = require("../../cli/commands/deploy/index");
 const modern_1 = require("../../cli/commands/deploy/modern");
 const index_6 = require("../../cli/commands/skills/index");
-const index_7 = require("../../cli/commands/registry/index");
+const index_7 = require("../../cli/commands/comment/index");
+const index_8 = require("../../cli/commands/registry/index");
 // scene 跟 dispatcher(MIAODA_APP_TYPE)同语义层级 —— app 业务类型维度,
 // 对齐后端 devops app_common.AppType 枚举:
 //   3 = AppType_APPLICATION(全栈应用,当前仅 nestjs-react-fullstack 一个 stack)
@@ -41,11 +42,13 @@ const SCENE_REGISTRARS = {
         (0, index_1.registerFileCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
     modern: (p) => {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
     // application scene(AppType_APPLICATION=3):
     // 在 default 命令集基础上加 skills(按 meta.json.stack 拉对应 stack 技能)
@@ -57,6 +60,7 @@ const SCENE_REGISTRARS = {
         (0, index_1.registerFileCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
     // design scene(AppType_DESIGN=4):design-stack 仅 SSR 渲染、无后端业务逻辑、
     // 无数据库、无 UGC 文件。命令集裁掉 db / file,保留 deploy / observability / app(init) / skills。
@@ -65,6 +69,7 @@ const SCENE_REGISTRARS = {
         (0, index_5.registerDeployCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
     // design-html scene(AppType_DESIGN_HTML=8):buildless 静态 HTML,
     // 命令集与 modern 一致(app init/sync + modern 拆分版 deploy + skills),不挂 db/file/observability。
@@ -73,7 +78,8 @@ const SCENE_REGISTRARS = {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
-        (0, index_7.registerRegistryCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
 };
 function readEnv(name) {

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

@@ -7,9 +7,9 @@ const index_1 = require("../../../cli/handlers/registry/index");
  * miaoda registry：design-html 技术栈的「组件 registry」（shadcn 式 copy-in）。
  *
  * registry 是独立 npm 包，按 runtime 命名分发（buildless runtime → @lark-apaas/coding-registry-buildless）。
- * SDK 文件按目录组织**平铺在包根**（scripts/ · components/ · stylesheets/），每个文件以 USAGE 注释块
- * 开头（声明描述 / 用法 / Depends）。CLI 抓 tarball、按 .spark/meta.json.stack → runtime → 包名 选包，
- * 把 SDK 文件**保留相对包根的路径** copy-in 到用户项目根。
+ * SDK 文件放在包根的 components/ · scripts/ · stylesheets/ 三个目录下（这三个顶层目录里的代码文件
+ * 才算条目）；文件可带 USAGE 注释块（可选，声明描述 / 用法 / Depends）。CLI 抓 tarball、按
+ * .spark/meta.json.stack → runtime → 包名 选包，把 SDK 文件**拍平**copy-in 到用户项目根。
  * 不写安装记账文件——项目文件树即状态（skip-by-disk）。
  */
 function registerRegistryCommands(program) {
@@ -22,11 +22,14 @@ function registerRegistryCommands(program) {
     });
     registryCmd.addHelpText('after', `
 概念
-  - registry 包：独立 npm 包（按 runtime 命名），SDK 文件平铺在包根（如 scripts/deck-stage.js）
-  - 条目 (entry)：name = 文件名去扩展名（全树唯一）；每个文件以 USAGE 注释块开头
-  - USAGE 块：声明描述 / Exports / Usage / Depends（可选，依赖其他 SDK 的 name）
+  - registry 包：独立 npm 包（按 runtime 命名）
+  - 条目 (entry)：包根 components/ · scripts/ · stylesheets/ 顶层目录（任意深度）下的代码文件；
+    name = 文件名去扩展名（不要求唯一）。包根直放文件、其它目录、非代码文件都不算条目
+  - 寻址：add / Depends 的 token 可写三种形式——name（foo）/ 完整文件名（foo.css）/ relPath（stylesheets/foo.css）
+  - 多匹配全拉：token 命中多个同名条目时全部 copy-in（不报歧义）；想只要其一就写完整文件名 / relPath
+  - USAGE 块：可选元数据，声明描述 / Exports / Usage / Depends；无 USAGE 也是条目（空描述、无依赖）
   - Depends：从 USAGE 块解析的跨条目依赖，add 时传递解析、一并 copy-in
-  - add 落地：保留文件相对包根的路径（包根 scripts/x.js → 项目 scripts/x.js）
+  - add 落地：拍平到项目根（包根 scripts/x.js → 项目 x.js）；同名 basename 撞车时后者覆盖前者
 
 前置
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack=design-html）
@@ -62,23 +65,37 @@ JSON 输出
 function registerRegistryAdd(parent) {
     const cmd = parent
         .command('add')
-        .description('把一个或多个 SDK 文件 copy-in 到当前项目（保留目录结构，含 Depends 闭包）')
-        .argument('<name...>', '条目名（文件名去扩展名），可传多个；Depends 会自动传递解析')
+        .description('把一个或多个 SDK 文件 copy-in 到当前项目（拍平到项目根，含 Depends 闭包）')
+        .argument('<token...>', 'name / 完整文件名 / relPath，可传多个；同名多匹配全拉，Depends 自动传递解析')
         .option('--dir <path>', '项目目录，默认当前目录', '.')
         .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
         .option('--overwrite', '目标文件已存在时覆盖（默认跳过以保护用户改动）', false)
         .option('--dry-run', '只报告将写 / 将跳哪些文件，不落盘', false)
         .addHelpText('after', `
 行为
-  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件从包根 <rel> 按相对路径拷到项目根
-    （包根 scripts/deck-stage.js → 项目 scripts/deck-stage.js，1:1 保留路径）
+  - token 寻址：name（foo）/ 完整文件名（foo.css）/ relPath（stylesheets/foo.css）任一形式
+  - 多匹配全拉：token 命中多个同名条目时全部 copy-in；想只要其一就写完整文件名 / relPath
+  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件**拍平**拷到项目根
+    （包根 scripts/deck-stage.js → 项目 deck-stage.js；同名 basename 撞车时后者覆盖前者）
   - skip-by-disk：目标文件已存在默认跳过；--overwrite 才覆盖
   - 不写任何安装记账文件（项目文件树即状态）
 
-JSON 输出
-  {"data": {"registryVersion": "...", "requested": [...], "resolved": [...],
-            "added": [...], "skipped": [...], "dryRun": false}}
-  （added / skipped 是项目内相对路径，如 scripts/deck-stage.js）
+输出（pretty，默认）
+  registry@<ver>
+  added: <落地 basename 逗号列表>          # 含 Depends 闭包全部落地文件
+  skipped: <逗号列表>                       # 仅有跳过时出现
+  dry-run: true (no files written)          # 仅 --dry-run 时出现
+
+  # <请求条目落地 basename>
+  <该条目 USAGE 块原文>                     # 只列你请求的条目，依赖不占 usage 位
+
+JSON 输出（--json）
+  {"data": {"registryVersion": "...", "added": [...], "skipped": [...], "dryRun": false,
+            "entries": [{"name": "...", "file": "<来源 relPath>", "dest": "<落地 basename>",
+                         "status": "added|skipped", "usage": "<USAGE 块原文>", "dependsOn": [...]}, ...]}}
+  （added / skipped 覆盖依赖闭包全部落地文件；entries 只列**你请求的条目**
+   （不含被 Depends 传递拉入的依赖），逐条给 usage / dependsOn，add 完直接读用法。
+   请求的条目即使已存在被 skip 也回带 usage，status 标 added / skipped）
 
 示例
   $ miaoda registry add deck-slide

package/dist/cli/handlers/comment/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCommentResolve = exports.handleCommentList = void 0;
+var list_1 = require("./list");
+Object.defineProperty(exports, "handleCommentList", { enumerable: true, get: function () { return list_1.handleCommentList; } });
+var resolve_1 = require("./resolve");
+Object.defineProperty(exports, "handleCommentResolve", { enumerable: true, get: function () { return resolve_1.handleCommentResolve; } });

package/dist/cli/handlers/comment/list.js

@@ -0,0 +1,132 @@
+"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.handleCommentList = handleCommentList;
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const output_1 = require("../../../utils/output");
+const fmtTime = output_1.fmt.sec();
+/** 去掉飞书内联 `<at ...>@某人</at>` 标签，保留内部 @文本。 */
+function stripAtTags(s) {
+    return s.replace(/<at\b[^>]*>/g, '').replace(/<\/at>/g, '');
+}
+/** 单个内联元素渲染成文本：text_run 出文本、docs_link 出链接、person 出 @user。 */
+function renderElement(el) {
+    if (el.text_run?.text)
+        return stripAtTags(el.text_run.text);
+    if (el.docs_link?.url)
+        return el.docs_link.url;
+    if (el.person?.user_id)
+        return `@${el.person.user_id}`;
+    return '';
+}
+/** 一条 reply 的正文文本（各 element 拼接、去 at 标签）。 */
+function replyText(r) {
+    return (r.content?.elements ?? []).map(renderElement).join('').trim();
+}
+/**
+ * 评论级 extra 里的 content_anchor_id（评论锚定的页面元素定位）。
+ * extra 后端返回 JSON 字符串（也兼容已是对象的情况），解析失败返回 undefined。
+ */
+function commentAnchor(c) {
+    const { extra } = c;
+    let obj = extra;
+    if (typeof extra === 'string') {
+        try {
+            obj = JSON.parse(extra);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        const anchor = obj.content_anchor_id;
+        if (typeof anchor === 'string' && anchor.length > 0)
+            return anchor;
+    }
+    return undefined;
+}
+/** 一条 reply 的附加标注：图片数量、reaction。 */
+function replyAnnotations(r) {
+    const ann = [];
+    const images = r.extra?.image_list;
+    if (Array.isArray(images) && images.length > 0)
+        ann.push(`[图片×${String(images.length)}]`);
+    for (const rc of r.reactions ?? []) {
+        if (rc.reaction_key)
+            ann.push(`[${rc.reaction_key}×${String(rc.count ?? 0)}]`);
+    }
+    return ann;
+}
+/**
+ * 渲染一条评论为多行块（信息全保留，靠结构化标签 + 列对齐提升可读性）：
+ *   ● [未解决] <comment_id>  ·  N 条回复
+ *     引用  <quote>
+ *     锚点  <content_anchor_id 全量>
+ *     <user 对齐>  <time>  <正文 + 标注>
+ * userWidth 为所有回复 user_id 的最大宽度，用于跨评论列对齐。
+ */
+function renderComment(c, userWidth) {
+    const replies = c.reply_list?.replies ?? [];
+    const lines = [
+        `● ${c.is_solved ? '[已解决]' : '[未解决]'} ${c.comment_id}  ·  ${String(replies.length)} 条回复`,
+    ];
+    if (typeof c.quote === 'string' && c.quote.length > 0)
+        lines.push(`  引用  ${c.quote}`);
+    const anchor = commentAnchor(c);
+    if (anchor !== undefined)
+        lines.push(`  锚点  ${anchor}`);
+    for (const r of replies) {
+        const body = [replyText(r), ...replyAnnotations(r)].filter((p) => p.length > 0).join(' ');
+        lines.push(`  ${(r.user_id ?? '-').padEnd(userWidth)}  ${fmtTime(r.create_time)}  ${body}`);
+    }
+    return lines.join('\n');
+}
+async function handleCommentList(opts) {
+    const appId = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const comments = await api.comment.getComments(appId, opts.onlyUnresolved ?? false);
+    // JSON 模式：原样透传完整评论结构（含 reply_list / replies / reactions …），与 openapi 一致。
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({ data: comments });
+        return;
+    }
+    // pretty 模式：信息密集的分块形态，一条评论一块、每条回复一行（含人 / 时间 / 正文 / 标注）。
+    // 跨评论对齐 user 列：取所有回复 user_id 的最大宽度。
+    const userWidth = Math.max(0, ...comments.flatMap((c) => c.reply_list?.replies ?? []).map((r) => (r.user_id ?? '-').length));
+    const body = comments.length === 0
+        ? '（无评论）'
+        : comments.map((c) => renderComment(c, userWidth)).join('\n\n');
+    process.stdout.write(body + '\n');
+}

package/dist/cli/handlers/comment/resolve.js

@@ -0,0 +1,44 @@
+"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.handleCommentResolve = handleCommentResolve;
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const output_1 = require("../../../utils/output");
+async function handleCommentResolve(commentId, opts) {
+    const appId = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    await api.comment.resolveComment(appId, commentId);
+    (0, output_1.emitOk)({ comment_id: commentId, resolved: true });
+}

package/dist/cli/handlers/deploy/patch.js

@@ -11,6 +11,7 @@ async function handleDeployPatch(opts) {
         creates: opts.creates,
         updates: opts.updates,
         deletes: opts.deletes,
+        sessionId: opts.sessionId,
     });
     (0, output_1.emit)({ data: result });
 }

package/dist/cli/handlers/registry/add.js

@@ -9,7 +9,6 @@ const index_1 = require("../../../services/registry/index");
 const shared_1 = require("./shared");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
-const logger_1 = require("../../../utils/logger");
 /**
  * miaoda registry add <name...> [--overwrite] [--dry-run] [--dir <path>] [--version <ver>]
  *
@@ -35,18 +34,62 @@ async function handleRegistryAdd(opts) {
             overwrite: opts.overwrite === true,
             dryRun: opts.dryRun === true,
         });
-        const verb = opts.dryRun === true ? 'Would add' : 'Added';
-        (0, logger_1.log)('registry', `${verb} ${String(result.added.length)} file(s), skipped ${String(result.skipped.length)} (registry@${reg.version})`);
-        (0, output_1.emit)({
-            data: {
-                registryVersion: reg.version,
-                requested: opts.names,
-                resolved: plan.entries.map((e) => e.name),
-                added: result.added,
-                skipped: result.skipped,
-                dryRun: opts.dryRun === true,
-            },
+        // entries：**只列用户请求的条目**（opts.names 命中的），给它们的 usage / dependsOn，
+        // 让 Agent add 完直接拿到用法、无需再 `registry list`。被 Depends 传递拉进来的依赖是
+        // "管道"（照常在 added/skipped 里落地），不占 usage 位。请求的条目即使已存在被 skip
+        // 也回带 usage（status=skipped，Agent 借此判断磁盘上是 registry 版还是自己改过的旧版）。
+        const requestedRelPaths = new Set();
+        for (const token of opts.names) {
+            for (const e of plan.entries) {
+                if ((0, index_1.tokenMatches)(e, token))
+                    requestedRelPaths.add(e.relPath);
+            }
+        }
+        // relPath → 落地的 PlannedFile（拿 dest / 落地状态）
+        const fileByRelPath = new Map(plan.files.map((f) => [f.srcRelPath, f]));
+        const addedSet = new Set(result.added);
+        const skippedSet = new Set(result.skipped);
+        const entries = plan.entries
+            .filter((e) => requestedRelPaths.has(e.relPath))
+            .map((e) => {
+            const f = fileByRelPath.get(e.relPath);
+            const dest = f?.dest ?? e.relPath.split('/').pop() ?? e.relPath;
+            const status = skippedSet.has(dest) && !addedSet.has(dest) ? 'skipped' : 'added';
+            return {
+                name: e.name,
+                file: e.relPath,
+                dest,
+                status,
+                usage: e.usage,
+                dependsOn: e.dependsOn,
+            };
         });
+        // 只透出对 add 完的 Agent 可操作的字段：项目里实际多了什么(added)、什么没动(skipped)、
+        // 请求条目怎么用(entries)。requested（纯回显）、resolved（包内诊断路径）不透出。
+        const data = {
+            registryVersion: reg.version,
+            added: result.added,
+            skipped: result.skipped,
+            dryRun: opts.dryRun === true,
+            entries,
+        };
+        if ((0, output_1.isJsonMode)()) {
+            (0, output_1.emit)({ data });
+            return;
+        }
+        // pretty 是 Agent 不加 --json 时的默认载荷，也要对 AI 友好：信息量与 JSON 对齐，
+        // 但换成稳定 label + 逗号列表（无 JSON 数组、无 TTY 截断、空/默认值不打印），
+        // summary 在前、各请求条目的 USAGE 块原文在后。整体走一次纯字符串 emit（不进 key-value 渲染）。
+        const summaryLines = [`registry@${reg.version}`];
+        if (opts.dryRun === true)
+            summaryLines.push('dry-run: true (no files written)');
+        if (result.added.length > 0)
+            summaryLines.push(`added: ${result.added.join(', ')}`);
+        if (result.skipped.length > 0)
+            summaryLines.push(`skipped: ${result.skipped.join(', ')}`);
+        const blocks = entries.filter((e) => e.usage !== '').map((e) => `# ${e.dest}\n${e.usage}`);
+        const parts = [summaryLines.join('\n'), ...blocks];
+        (0, output_1.emit)(parts.join('\n\n'));
     }
     finally {
         reg.cleanup();

package/dist/services/deploy/modern/atoms/design-build.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildDesignOutput = buildDesignOutput;
+exports.cleanDesignDist = cleanDesignDist;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const error_1 = require("../../../../utils/error");
@@ -39,3 +40,10 @@ function buildDesignOutput(opts) {
         throw new error_1.AppError('DEPLOY_BUILD_FAILED', `design build failed: ${err.message}`);
     }
 }
+/**
+ * 删除 <projectDir>/dist（本地构建产物）。幂等：不存在也不报错（force）。
+ * design 部署收尾调用，部署动作结束后不在用户项目里留产物。
+ */
+function cleanDesignDist(projectDir) {
+    node_fs_1.default.rmSync(node_path_1.default.join(projectDir, constants_1.DIST_DIR), { recursive: true, force: true });
+}

package/dist/services/deploy/modern/atoms/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.savePluginInstances = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
+exports.savePluginInstances = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.cleanDesignDist = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "prepareDeployContext", { enumerable: true, get: function () { return context_1.prepareDeployContext; } });
 var pre_release_1 = require("./pre-release");
@@ -9,6 +9,7 @@ var build_1 = require("./build");
 Object.defineProperty(exports, "runBuild", { enumerable: true, get: function () { return build_1.runBuild; } });
 var design_build_1 = require("./design-build");
 Object.defineProperty(exports, "buildDesignOutput", { enumerable: true, get: function () { return design_build_1.buildDesignOutput; } });
+Object.defineProperty(exports, "cleanDesignDist", { enumerable: true, get: function () { return design_build_1.cleanDesignDist; } });
 var design_upload_1 = require("./design-upload");
 Object.defineProperty(exports, "uploadDesignArtifacts", { enumerable: true, get: function () { return design_upload_1.uploadDesignArtifacts; } });
 var upload_1 = require("./upload");

package/dist/services/deploy/modern/patch/actions.js

@@ -36,7 +36,8 @@ function isHtml(rel) {
 /**
  * 把 changeset 组成 TosFileAction[]：
  *   - create/update 读本地文件、自动编码；delete 仅 FilePath。
- *   - 任一改动是 .html → 追加 routes.json（TS 重算）的 UPDATE action。
+ *   - .html 被 create / delete（路由集合变化）时，追加重算 routes.json 的 UPDATE action；
+ *     纯 update 现有 .html 只改内容、不改路由集合，不重算 routes.json。
  */
 function buildTosActions(projectDir, cs) {
     const actions = [];
@@ -47,8 +48,8 @@ function buildTosActions(projectDir, cs) {
     for (const rel of cs.deletes) {
         actions.push({ actionType: index_1.TosActionType.DELETE, filePath: normalizeRel(rel) });
     }
-    const touchesHtml = [...cs.creates, ...cs.updates, ...cs.deletes].some(isHtml);
-    if (touchesHtml) {
+    const routeSetChanged = [...cs.creates, ...cs.deletes].some(isHtml);
+    if (routeSetChanged) {
         actions.push({
             actionType: index_1.TosActionType.UPDATE,
             filePath: 'routes.json',

package/dist/services/deploy/modern/patch/index.js

@@ -11,8 +11,8 @@ const actions_1 = require("./actions");
 var actions_2 = require("./actions");
 Object.defineProperty(exports, "buildTosActions", { enumerable: true, get: function () { return actions_2.buildTosActions; } });
 /**
- * design-html 增量发布：读本地文件组 TosFileAction（含 .html 时带 routes.json），
- * 调后端 applyTosDiff 应用到 latest。scope 限 design_local_deploy。
+ * design-html 增量发布：读本地文件组 TosFileAction（create/delete .html 时带重算的
+ * routes.json），调后端 applyTosDiff 应用到 latest。scope 限 design_local_deploy。
  */
 async function patchDesignDeploy(opts) {
     if (opts.creates.length + opts.updates.length + opts.deletes.length === 0) {
@@ -30,7 +30,12 @@ async function patchDesignDeploy(opts) {
     });
     const routesRegenerated = actions.some((a) => a.filePath === 'routes.json');
     (0, logger_1.log)('deploy', `Applying ${String(actions.length)} file action(s)...`);
-    const res = await (0, index_1.applyTosDiff)({ appID: opts.appId, templateKey, actions });
+    const res = await (0, index_1.applyTosDiff)({
+        appID: opts.appId,
+        templateKey,
+        actions,
+        sessionId: opts.sessionId,
+    });
     (0, logger_1.log)('deploy', `Patched: upsert=${String(res.upsertCount)} delete=${String(res.deleteCount)}`);
     return {
         upsertCount: res.upsertCount,

package/dist/services/deploy/modern/patch/routes.js

@@ -2,27 +2,36 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateRoutes = generateRoutes;
 const source_scan_1 = require("./source-scan");
-/** 与 build.sh 一致的 .html → route path 推导。rel 为 posix 相对路径。 */
-function toRoute(rel, base) {
+/**
+ * .html → route path 推导（相对路径，不带 base 前缀）。rel 为 posix 相对路径。
+ * base 前缀交由消费侧（运行时/网关）自行拼接，design-html 链路不在 routes.json 内带前缀。
+ */
+function toRoute(rel) {
     let r = '/' + rel;
     r = r.replace(/\.html$/i, '');
     r = r.replace(/(^|\/)index$/, '$1');
     if (r.length > 1)
         r = r.replace(/\/$/, '');
-    const full = base + r;
-    return full === '' ? '/' : full;
+    return r === '' ? '/' : r;
 }
 /**
- * 扫描 projectDir 下所有 .html（套 source-scan 的 EXCLUDES），生成与 build.sh 同款 routes.json
- * 文本（含尾换行）。CLIENT_BASE_PATH 取自 process.env（平台预置），去尾斜杠后作前缀。
+ * 扫描 projectDir 下所有 .html（套 source-scan 的 EXCLUDES），生成 routes.json 文本（含尾换行）。
+ * 每项为 { path, file }：path 为相对路径（不带 CLIENT_BASE_PATH 前缀，由消费侧拼接），
+ * file 为该路由对应的原始 .html 源文件。按 path 排序、同 path 取字典序靠前的 file 去重。
+ * 零 html 时输出空数组——不伪造解析不到文件的根路由。
  */
 function generateRoutes(projectDir) {
-    const base = (process.env.CLIENT_BASE_PATH ?? '').replace(/\/+$/, '');
     const htmls = (0, source_scan_1.listSourceFiles)(projectDir).filter((f) => f.toLowerCase().endsWith('.html'));
-    const routes = [...new Set(htmls.map((rel) => toRoute(rel, base)))]
-        .sort()
-        .map((p) => ({ path: p }));
-    if (routes.length === 0)
-        routes.push({ path: base ? `${base}/` : '/' });
+    const byPath = new Map();
+    for (const entry of htmls.map((file) => ({ path: toRoute(file), file })).sort(byPathThenFile)) {
+        if (!byPath.has(entry.path))
+            byPath.set(entry.path, entry);
+    }
+    const routes = [...byPath.values()];
     return JSON.stringify(routes, null, 2) + '\n';
 }
+function byPathThenFile(a, b) {
+    return a.path === b.path
+        ? (a.file ?? '').localeCompare(b.file ?? '')
+        : a.path.localeCompare(b.path);
+}

package/dist/services/deploy/modern/patch/source-scan.js

@@ -20,6 +20,8 @@ exports.EXCLUDES = new Set([
     '.gitignore',
     '.npmrc',
     '.agent',
+    '.agents',
+    'skills',
     '.env',
     '.env.local',
     'README.md',

package/dist/services/deploy/modern/pipelines/design-local.js

@@ -20,28 +20,37 @@ async function designLocalPublishPipeline(opts) {
         throw new error_1.AppError('DEPLOY_PRE_RELEASE_DATA_MISSING', 'preRelease did not return a `data` map — backend tcc may not be configured for current template_key');
     }
     const data = pre.data;
-    if (!opts.skipBuild) {
-        (0, index_1.buildDesignOutput)({ projectDir: ctx.projectDir });
-    }
-    (0, logger_1.log)('deploy', 'Creating local release...');
-    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version);
+    // dist 是本地构建产物，部署动作结束（无论成败）都清掉，不在用户项目里留产物。
     try {
-        await (0, index_1.uploadDesignArtifacts)({ projectDir: ctx.projectDir, data });
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
-    }
-    catch (err) {
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
-        throw err;
+        if (!opts.skipBuild) {
+            (0, index_1.buildDesignOutput)({ projectDir: ctx.projectDir });
+        }
+        (0, logger_1.log)('deploy', 'Creating local release...');
+        const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
+            checkPointVersion: opts.checkPointVersion,
+            commitID: opts.commitID,
+        });
+        try {
+            await (0, index_1.uploadDesignArtifacts)({ projectDir: ctx.projectDir, data });
+            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+        }
+        catch (err) {
+            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+            throw err;
+        }
+        if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
+            (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
+        }
+        (0, logger_1.log)('deploy', 'Deployed successfully');
+        return {
+            appId: ctx.appId,
+            version: pre.version,
+            url: release.onlineUrl ?? '',
+            releaseID: release.releaseID,
+            preReleaseID: pre.preReleaseID,
+        };
     }
-    if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
-        (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
+    finally {
+        (0, index_1.cleanDesignDist)(ctx.projectDir);
     }
-    (0, logger_1.log)('deploy', 'Deployed successfully');
-    return {
-        appId: ctx.appId,
-        version: pre.version,
-        url: release.onlineUrl ?? '',
-        releaseID: release.releaseID,
-        preReleaseID: pre.preReleaseID,
-    };
 }

package/dist/services/registry/index.js

@@ -8,7 +8,7 @@ exports.resolveRegistryPackage = resolveRegistryPackage;
 exports.loadRegistry = loadRegistry;
 exports.extractUsageBlock = extractUsageBlock;
 exports.parseDependsOn = parseDependsOn;
-exports.indexEntries = indexEntries;
+exports.tokenMatches = tokenMatches;
 exports.resolveDependencyClosure = resolveDependencyClosure;
 exports.planAdd = planAdd;
 exports.applyAdd = applyAdd;
@@ -95,12 +95,21 @@ function loadRegistry(opts) {
  */
 const SDK_FILE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.css']);
 /**
- * 从包根递归扫整棵树，提取含 USAGE 块的 SDK 条目（任意子目录深度）。
- * 只看代码文件（SDK_FILE_EXTENSIONS）；条目 name 全树唯一，撞名抛错。
+ * 条目所在的顶层目录白名单。只有包根下这几个目录（任意深度）里的代码文件才算条目，
+ * 包根直放的文件（eslint.config.js 等）、其它顶层目录（lib/ 等）一律排除——
+ * 避免 USAGE 可选后把工程配置 / 非 SDK 代码误判为条目。
+ */
+const SDK_TOP_DIRS = new Set(['components', 'scripts', 'stylesheets']);
+/**
+ * 从包根递归扫整棵树，提取 SDK 条目。条目判据：
+ *   1. 在白名单顶层目录下（SDK_TOP_DIRS，任意深度）；
+ *   2. 是代码文件（SDK_FILE_EXTENSIONS）。
+ * USAGE 块**可选**：有则解析描述 + Depends，无则 usage 为空、dependsOn 为空——仍是条目。
+ * name（去扩展名 basename）**不要求唯一**：同名的不同文件全部收录为独立条目，由 relPath
+ * （树内唯一）区分；寻址 / 拉取由 tokenMatches + resolveDependencyClosure 处理（同名 → 全拉）。
  */
 function scanEntries(registryRoot) {
     const entries = [];
-    const byName = new Map(); // name → relPath（撞名诊断）
     const walk = (dir) => {
         for (const dirent of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
             const absPath = node_path_1.default.join(dir, dirent.name);
@@ -110,23 +119,17 @@ function scanEntries(registryRoot) {
             }
             if (!dirent.isFile())
                 continue;
-            // 只扫代码文件，排除 README/LICENSE/package.json 等（它们正文可能含 USAGE 字面量）
+            // 只扫代码文件，排除 README/LICENSE/package.json 等非 SDK 文件
             if (!SDK_FILE_EXTENSIONS.has(node_path_1.default.extname(dirent.name).toLowerCase()))
                 continue;
-            const content = node_fs_1.default.readFileSync(absPath, 'utf-8');
-            const usage = extractUsageBlock(content);
-            if (usage === null)
-                continue; // 非 SDK 文件（无 USAGE 块）
             // 相对包根的路径，统一用 '/' 分隔（落地时再按平台 join）
             const relPath = node_path_1.default.relative(registryRoot, absPath).split(node_path_1.default.sep).join('/');
-            const name = stripExt(dirent.name);
-            const prev = byName.get(name);
-            if (prev !== undefined) {
-                throw new error_1.AppError('REGISTRY_DUPLICATE_NAME', `registry 条目名 "${name}" 重复：${prev} 与 ${relPath}`);
-            }
-            byName.set(name, relPath);
+            // 只认白名单顶层目录下的文件（顶层段 ∈ SDK_TOP_DIRS）
+            if (!SDK_TOP_DIRS.has(relPath.split('/')[0]))
+                continue;
+            const usage = extractUsageBlock(node_fs_1.default.readFileSync(absPath, 'utf-8')) ?? '';
             entries.push({
-                name,
+                name: stripExt(dirent.name),
                 relPath,
                 usage,
                 dependsOn: parseDependsOn(usage),
@@ -135,8 +138,8 @@ function scanEntries(registryRoot) {
         }
     };
     walk(registryRoot);
-    // 稳定排序，便于 list 输出可预期
-    entries.sort((a, b) => a.name.localeCompare(b.name));
+    // 按 relPath（唯一）稳定排序，便于 list 输出可预期
+    entries.sort((a, b) => a.relPath.localeCompare(b.relPath));
     return entries;
 }
 /** 提取 BEGIN/END USAGE 标记之间的原文（含标记行）。无 USAGE 块返回 null。 */
@@ -172,62 +175,81 @@ function stripExt(file) {
     const ext = node_path_1.default.extname(file);
     return ext === '' ? file : file.slice(0, -ext.length);
 }
-/** name → entry 索引，便于依赖解析。 */
-function indexEntries(entries) {
-    const map = new Map();
-    for (const e of entries)
-        map.set(e.name, e);
-    return map;
+/**
+ * 一个 token 是否命中某条目。token 可写三种寻址形式（按特异度，任一相等即命中）：
+ *   - relPath：相对包根路径，如 components/foo.jsx（含 '/'）
+ *   - 完整文件名：含扩展名的 basename，如 foo.jsx
+ *   - name：去扩展名的 basename，如 foo
+ * 三种形式无歧义重叠（relPath 含 '/'，basename 不含；完整文件名含原扩展名，name 不含），
+ * 故用一个等值谓词即可。多个条目可同时命中同一 token（同名 → 全拉），由调用方处理。
+ */
+function tokenMatches(entry, token) {
+    if (token === entry.relPath)
+        return true;
+    const fileName = entry.relPath.split('/').pop() ?? '';
+    if (token === fileName)
+        return true;
+    return token === entry.name;
 }
 /**
- * 解析 Depends 的传递闭包：从 requested 出发，递归把所有依赖一并纳入。
+ * 解析 Depends 的传递闭包：从 requested token 出发，递归把所有依赖一并纳入。
  *
- * 返回拓扑序（依赖在前、被依赖在后），便于按序拷贝。检测循环依赖并抛错；
- * 引用了不存在的条目名也抛错（fail-fast，避免拷半套）。
+ * token 经 tokenMatches 解析成**一组**条目（同名 → 全拉），逐个展开。返回拓扑序
+ * （依赖在前、被依赖在后），便于按序拷贝。token 零命中抛 REGISTRY_ENTRY_NOT_FOUND；
+ * 检测循环依赖并抛 REGISTRY_CYCLE。visited / onStack / 环检测均以 relPath（唯一）为键，
+ * 故同名（去扩展名）的不同文件互不干扰、不会误判成环。
  */
 function resolveDependencyClosure(entries, requested) {
-    const index = indexEntries(entries);
     const ordered = [];
-    const visited = new Set();
-    const onStack = new Set();
-    const visit = (name, trail) => {
-        if (visited.has(name))
-            return;
-        if (onStack.has(name)) {
-            throw new error_1.AppError('REGISTRY_CYCLE', `registry 条目依赖成环：${[...trail, name].join(' -> ')}`);
-        }
-        const entry = index.get(name);
-        if (entry === undefined) {
-            // requested 顶层缺失 vs 依赖链里缺失，都报清楚是谁引的
+    const visited = new Set(); // by relPath
+    const onStack = new Set(); // by relPath
+    // token → 命中条目集合；零命中 fail-fast（避免拷半套）
+    const resolveToken = (token, trail) => {
+        const matches = entries.filter((e) => tokenMatches(e, token));
+        if (matches.length === 0) {
             const via = trail.length > 0 ? `（被 "${trail[trail.length - 1]}" 依赖）` : '';
-            throw new error_1.AppError('REGISTRY_ENTRY_NOT_FOUND', `registry 没有条目 "${name}"${via}`, {
+            throw new error_1.AppError('REGISTRY_ENTRY_NOT_FOUND', `registry 没有条目 "${token}"${via}`, {
                 next_actions: ['用 `miaoda registry list` 查看可用条目'],
             });
         }
-        onStack.add(name);
-        for (const dep of entry.dependsOn) {
-            visit(dep, [...trail, name]);
+        return matches;
+    };
+    const visit = (entry, trail) => {
+        if (visited.has(entry.relPath))
+            return;
+        if (onStack.has(entry.relPath)) {
+            throw new error_1.AppError('REGISTRY_CYCLE', `registry 条目依赖成环：${[...trail, entry.relPath].join(' -> ')}`);
+        }
+        onStack.add(entry.relPath);
+        for (const depToken of entry.dependsOn) {
+            for (const depEntry of resolveToken(depToken, [...trail, entry.relPath])) {
+                visit(depEntry, [...trail, entry.relPath]);
+            }
         }
-        onStack.delete(name);
-        visited.add(name);
+        onStack.delete(entry.relPath);
+        visited.add(entry.relPath);
         ordered.push(entry);
     };
-    for (const name of requested)
-        visit(name, []);
+    for (const token of requested) {
+        for (const entry of resolveToken(token, []))
+            visit(entry, []);
+    }
     return ordered;
 }
 /**
- * 规划 add：解析依赖闭包 → 每个条目按其相对包根的路径落地到项目根 → 标记是否已存在。
- * 纯计算，不落盘（dry-run 与真实 add 共用）。
+ * 规划 add：解析依赖闭包 → 每个条目**拍平为 basename** 落到项目根 → 标记是否已存在。
+ * 纯计算，不落盘（dry-run 与真实 add 共用）。exists 在此快照（落盘前），故闭包内同名
+ * basename 撞车时双方 exists 都为 false、applyAdd 里后者覆盖前者。
  */
 function planAdd(opts) {
     const entries = resolveDependencyClosure(opts.entries, opts.names);
     const files = entries.map((entry) => {
-        // relPath 用 '/' 存，落地时按平台拆分 join，保证 Windows 也正确
-        const destAbs = node_path_1.default.join(opts.targetDir, ...entry.relPath.split('/'));
+        const dest = entry.relPath.split('/').pop() ?? entry.relPath; // 拍平为 basename
+        const destAbs = node_path_1.default.join(opts.targetDir, dest);
         return {
             entry: entry.name,
-            relPath: entry.relPath,
+            srcRelPath: entry.relPath,
+            dest,
             destAbs,
             srcAbs: entry.absPath,
             exists: node_fs_1.default.existsSync(destAbs),
@@ -236,28 +258,36 @@ function planAdd(opts) {
     return { entries, files };
 }
 /**
- * 执行 add 计划：按 skip-by-disk 把 SDK 文件保留相对结构拷到项目根。
- *   - 目标已存在且未 overwrite → skip（保护用户改动）
+ * 执行 add 计划：把 SDK 文件**拍平**拷到项目根。
+ *   - 目标已存在且未 overwrite → skip（skip-by-disk 保护用户改动）
  *   - 目标已存在且 overwrite → 覆盖写
  *   - 目标不存在 → 写
- * dryRun=true 时只分类不落盘。不写任何安装记账文件（项目文件树即状态）。
+ * 闭包内同名 basename 撞车（双方 exists 均为 plan 前快照 false）→ 顺序拷贝、后者覆盖前者，
+ * added 去重只报一次。dryRun=true 时只分类不落盘。不写任何安装记账文件（项目文件树即状态）。
  */
 function applyAdd(files, opts) {
     const added = [];
     const skipped = [];
+    const seen = new Set();
+    const pushUnique = (list, dest) => {
+        if (seen.has(dest))
+            return;
+        seen.add(dest);
+        list.push(dest);
+    };
     for (const f of files) {
         if (f.exists && !opts.overwrite) {
-            skipped.push(f.relPath);
+            pushUnique(skipped, f.dest);
             continue;
         }
         if (!opts.dryRun) {
             if (!node_fs_1.default.existsSync(f.srcAbs)) {
-                throw new error_1.AppError('REGISTRY_FILE_MISSING', `registry 包内缺少文件 ${f.relPath}（条目 "${f.entry}"）`);
+                throw new error_1.AppError('REGISTRY_FILE_MISSING', `registry 包内缺少文件 ${f.srcRelPath}（条目 "${f.entry}"）`);
             }
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(f.destAbs), { recursive: true });
             node_fs_1.default.copyFileSync(f.srcAbs, f.destAbs);
         }
-        added.push(f.relPath);
+        pushUnique(added, f.dest);
     }
     return { added, skipped };
 }

package/dist/utils/http.js

@@ -64,7 +64,7 @@ function createClient(opts) {
  * 默认灰度泳道。当前 miaoda CLI 接入的新接口（modern deploy 等）只在该泳道生效，
  * 缺省走这个。MIAODA_CANARY_HEADER 可显式覆盖；设为空字符串则去掉头。
  */
-const DEFAULT_CANARY_HEADER = 'boe_miaoda_doubao';
+const DEFAULT_CANARY_HEADER = 'boe_miaoda_ccm';
 /**
  * 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.19-alpha.6dad9cd",
+  "version": "0.1.19-alpha.7856c6b",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {