@lark-apaas/miaoda-cli 0.1.22 → 0.1.24

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/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/deploy/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.batchSavePluginInstances = exports.LocalReleaseStatus = exports.getModernLastPublishedVersion = exports.getModernReleaseStatus = exports.createModernRelease = exports.callbackStatic = exports.updateLocalRelease = exports.createLocalRelease = exports.preRelease = exports.queryPipelineInstance = exports.getErrorLog = exports.listPipelineInstances = exports.createRelease = void 0;
+exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.batchSavePluginInstances = exports.TosActionType = exports.LocalReleaseStatus = exports.applyTosDiff = exports.getModernLastPublishedVersion = exports.getModernReleaseStatus = exports.createModernRelease = exports.callbackStatic = exports.updateLocalRelease = exports.createLocalRelease = exports.preRelease = exports.queryPipelineInstance = exports.getErrorLog = exports.listPipelineInstances = exports.createRelease = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "createRelease", { enumerable: true, get: function () { return api_1.createRelease; } });
 Object.defineProperty(exports, "listPipelineInstances", { enumerable: true, get: function () { return api_1.listPipelineInstances; } });
@@ -14,8 +14,10 @@ Object.defineProperty(exports, "callbackStatic", { enumerable: true, get: functi
 Object.defineProperty(exports, "createModernRelease", { enumerable: true, get: function () { return modern_1.createRelease; } });
 Object.defineProperty(exports, "getModernReleaseStatus", { enumerable: true, get: function () { return modern_1.getReleaseStatus; } });
 Object.defineProperty(exports, "getModernLastPublishedVersion", { enumerable: true, get: function () { return modern_1.getLastPublishedVersion; } });
+Object.defineProperty(exports, "applyTosDiff", { enumerable: true, get: function () { return modern_1.applyTosDiff; } });
 var modern_types_1 = require("./modern-types");
 Object.defineProperty(exports, "LocalReleaseStatus", { enumerable: true, get: function () { return modern_types_1.LocalReleaseStatus; } });
+Object.defineProperty(exports, "TosActionType", { enumerable: true, get: function () { return modern_types_1.TosActionType; } });
 var plugin_instances_1 = require("./plugin-instances");
 Object.defineProperty(exports, "batchSavePluginInstances", { enumerable: true, get: function () { return plugin_instances_1.batchSavePluginInstances; } });
 var schemas_1 = require("./schemas");

package/dist/api/deploy/modern-types.js

@@ -8,7 +8,7 @@
 //
 // 远端部署链路（B/C）所需的 release 接口先预留类型骨架，待 B/C 落地时启用。
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalReleaseStatus = void 0;
+exports.TosActionType = exports.LocalReleaseStatus = void 0;
 /**
  * localPublish 状态枚举（数值，与服务端 IDL 对齐）。
  * CLI updateLocalRelease 只翻 Finished / Failed 两个终态；其它由后端流转。
@@ -21,3 +21,6 @@ exports.LocalReleaseStatus = {
     Canceled: 4,
     Rollback: 5,
 };
+// ── applyTosDiff（design-html 增量发布；后端应用 TOS diff） ──
+/** 对齐 IDL publish.TosActionType（UNSPECIFIED=0 不用） */
+exports.TosActionType = { CREATE: 1, UPDATE: 2, DELETE: 3 };

package/dist/api/deploy/modern.js

@@ -17,6 +17,7 @@ exports.callbackStatic = callbackStatic;
 exports.createRelease = createRelease;
 exports.getReleaseStatus = getReleaseStatus;
 exports.getLastPublishedVersion = getLastPublishedVersion;
+exports.applyTosDiff = applyTosDiff;
 const http_1 = require("../../utils/http");
 const devops_error_1 = require("../../utils/devops-error");
 const DEFAULT_ERR_CODE = 'INTERNAL_DEVOPS_ERROR';
@@ -76,3 +77,10 @@ async function getLastPublishedVersion(req) {
     const url = `/v1/devops/app/${encodeURIComponent(appID)}/last_published_version`;
     return (0, http_1.postInnerApi)(url, {}, envelopeOpts('Failed to get last published version'));
 }
+// ── applyTosDiff ──
+/** POST /v1/devops/app/:appID/apply_tos_diff —— 增量应用 TOS 文件 diff */
+async function applyTosDiff(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/apply_tos_diff`;
+    return (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to apply tos diff'));
+}

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/app/index.js

@@ -166,7 +166,7 @@ function registerAppInit(parent) {
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
         .option('--app-type <type>', 'aPaaS 业务类型（html / modern_html / jspage / full_stack）；未传 --template 时用于解析技术栈')
         .option('--source-path <path>', '导入源目录：把该目录内容聚合进脚手架 src/（当前仅 --app-type modern_html 生效）')
-        .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
+        .option('--conf [json]', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
         .option('--async-install', '派发后台进程装依赖并立即返回（与 --skip-install 互斥）', false)
         .addOption((0, shared_1.appIdOption)())
@@ -252,7 +252,9 @@ JSON 输出
     }));
 }
 function parseInitConf(raw) {
-    if (raw === undefined)
+    // --conf 为可选值：未传（undefined）、裸 --conf（Commander 给 true）、空/纯空白字符串
+    // 一律视为不配置，回退默认（latest）。
+    if (raw === undefined || typeof raw === 'boolean' || raw.trim() === '')
         return undefined;
     let parsed;
     try {

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDeployCommandsModern = registerDeployCommandsModern;
 const shared_1 = require("../../../cli/commands/shared");
 const modern_1 = require("../../../cli/handlers/deploy/modern");
+const index_1 = require("../../../cli/handlers/deploy/index");
 /**
  * modern scene (MIAODA_APP_TYPE=7) 专用 deploy 注册。
  * 仅披露顶层 `miaoda deploy`，CLI 表面对齐 openclaw-cli：`--dir / --skip-build`。
@@ -56,4 +57,37 @@ JSON 输出（stdout）
             conf: rawOpts.conf,
         });
     }));
+    const patchCmd = deployCmd
+        .command('patch')
+        .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('--session-id <id>', '会话 ID，发布时透传给下游（可选）')
+        .addHelpText('after', `
+--dir 为项目目录（与 deploy 同名参数，默认当前目录）。
+仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
+禁绝对路径与 ".."。--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>}}
+
+示例
+  $ miaoda deploy patch --update index.html
+  $ miaoda deploy patch --create blog/post.html --delete blog/old.html
+  $ miaoda deploy patch --update assets/app.js --update assets/app.css
+`);
+    patchCmd.action((0, shared_1.withHelp)(patchCmd, async (rawOpts) => {
+        await (0, index_1.handleDeployPatch)({
+            appId: (0, shared_1.resolveAppId)({}),
+            dir: deployCmd.opts().dir ?? '.',
+            creates: rawOpts.create,
+            updates: rawOpts.update,
+            deletes: rawOpts.delete,
+            sessionID: rawOpts.sessionId,
+        });
+    }));
 }

package/dist/cli/commands/index.js

@@ -9,11 +9,14 @@ 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/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)
 //   4 = AppType_DESIGN(design-stack,SSR 渲染、无业务逻辑、无数据库)
 //   7 = miaoda-cli 自定义 modern 占位(后端枚举无 7,沙箱目前不传)
+//   8 = AppType_DESIGN_HTML(design-html,buildless 静态 HTML,命令集同 modern)
 //   其它(0/1/2/5/6 / 未设)→ default(命令全开,本地 dev / CI / 兼容回退)
 // stack 维度(nestjs-react-fullstack / vite-react / ...)是正交的,
 // skills sync 内部按 .spark/meta.json.stack 拉对应 coding-steering/steering/<stack>/ 子目录。
@@ -24,6 +27,8 @@ function resolveScene(appType, _archType) {
         return 'application';
     if (appType === '4')
         return 'design';
+    if (appType === '8')
+        return 'design-html';
     return 'default';
 }
 const SCENE_REGISTRARS = {
@@ -37,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 技能)
@@ -53,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。
@@ -61,6 +69,17 @@ 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。
+    // 额外挂 registry(shadcn 式 copy-in SDK,design-html scene 专属)。
+    'design-html': (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, modern_1.registerDeployCommandsModern)(p);
+        (0, index_6.registerSkillsCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
+        (0, index_7.registerCommentCommands)(p);
     },
 };
 function readEnv(name) {

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRegistryCommands = registerRegistryCommands;
+const shared_1 = require("../../../cli/commands/shared");
+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 文件放在包根的 components/ · scripts/ · stylesheets/ 三个目录下（这三个顶层目录里的代码文件
+ * 才算条目）；文件可带 USAGE 注释块（可选，声明描述 / 用法 / Depends）。CLI 抓 tarball、按
+ * .spark/meta.json.stack → runtime → 包名 选包，把 SDK 文件**拍平**copy-in 到用户项目根。
+ * 不写安装记账文件——项目文件树即状态（skip-by-disk）。
+ */
+function registerRegistryCommands(program) {
+    const registryCmd = program
+        .command('registry')
+        .description('组件 registry：列出 / copy-in design-html SDK 文件')
+        .usage('<command> [flags]');
+    registryCmd.action(() => {
+        registryCmd.outputHelp();
+    });
+    registryCmd.addHelpText('after', `
+概念
+  - 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 → 项目 x.js）；同名 basename 撞车时后者覆盖前者
+
+前置
+  当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack=design-html）
+`);
+    registerRegistryList(registryCmd);
+    registerRegistryAdd(registryCmd);
+}
+function registerRegistryList(parent) {
+    const cmd = parent
+        .command('list')
+        .description('列出 registry 可用 SDK 条目，输出各文件的 USAGE 块原文')
+        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
+        .addHelpText('after', `
+输出
+  默认（pretty）：各条目 USAGE 块原文拼接，带文件名分隔，给 Agent 直接读注释
+
+JSON 输出
+  {"data": [{"name": "...", "file": "...", "usage": "<原文>", "dependsOn": [...]}, ...]}
+  （usage 保持 USAGE 块原文，不解析成结构化字段）
+
+示例
+  $ miaoda registry list
+  $ miaoda registry list --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleRegistryList)({
+            dir: rawOpts.dir,
+            version: rawOpts.version,
+        });
+    }));
+}
+function registerRegistryAdd(parent) {
+    const cmd = parent
+        .command('add')
+        .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', `
+行为
+  - 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 才覆盖
+  - 不写任何安装记账文件（项目文件树即状态）
+
+输出（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
+  $ miaoda registry add deck-slide theme --dry-run
+  $ miaoda registry add deck-slide --overwrite --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (names, rawOpts) => {
+        await (0, index_1.handleRegistryAdd)({
+            names,
+            dir: rawOpts.dir,
+            version: rawOpts.version,
+            overwrite: rawOpts.overwrite,
+            dryRun: rawOpts.dryRun,
+        });
+    }));
+}

package/dist/cli/handlers/app/init.js

@@ -61,8 +61,12 @@ async function handleAppInit(opts) {
     // source_path 导入：当前仅 app_type=modern_html 生效。渲染完模板后、装依赖前叠加进 src/。
     const sourceImport = applySourcePathImport(opts, targetDir);
     // 先建 logs/,防止 user 跑 dev 之前 AI/工具 redirect 到 logs/*.log 因为父目录不存在直接挂
-    // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)
-    (0, logs_dir_1.ensureLogsDir)(targetDir);
+    // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)。
+    // 仅本地开发需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景,
+    // 不预建 logs/ 以免在沙箱工作区留空目录。
+    if (!(0, env_1.isSandboxEnv)()) {
+        (0, logs_dir_1.ensureLogsDir)(targetDir);
+    }
     // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
     // activateGitHooks（之前会让 .spark/meta.json 没写，下次 init 半渲染状态又得重跑全套）。
     // 按运行环境（isSandboxEnv：MIAODA_DEP_CACHE_DIR 非空）分流 outputLayout，不绑 stack:

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');
+}