@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.7b2c2ad → 0.1.0-dev.7cbbb20

package/miaoda/lark-apps-ops/references/lark-apps-export.md

@@ -0,0 +1,46 @@
+# apps +export
+
+把妙搭应用的源码打成 zip 下载到本地。运行时命令事实以 `lark-cli apps +export --help` 为准。只读操作。
+
+## 何时用
+
+只要一份源码快照的场景：读代码、审计、归档、做静态分析、把源码喂给别的工具。
+
+**跨应用是它的核心价值**：创意应用的分享链接（`/page/<token>`）指向别人的应用，你对那个仓库没有权限，`git clone` 走不通；`+export` 只要求你对该应用有下载权限。
+
+## 不要用它的时候
+
+当前应用要继续开发时不用它——当前应用源码通常已在工作区，直接改。`+export` 只给一个 zip：无 git 历史、无远端、无凭证、不拉环境变量，改完发不回去，只适合「拿一份只读快照」。
+
+## 导出的是「最后一次提交」，不是沙箱当前状态
+
+服务端对远端仓库跑 `git archive`，从不读沙箱文件系统。沙箱里改了文件但没提交或发布，**那些改动不在归档里**。若导出结果看起来"少了刚写的代码"，先确认改动是否已提交，而不是重试导出。
+
+## 命令骨架
+
+- `--app-id` 与 `--meta-token` **恰传其一**：前者是应用 ID（`$app_id`），后者是分享链接 `/page/<token>` 里的 token。两者作为独立字段走 `POST /apps/export`（`app_id` / `meta_token`），服务端按传入字段区分。
+- 两者都只收**裸标识符**。拿到的是整条链接（`.../app/<app_id>` 或 `.../page/<token>`）时只传最后一段——整条 URL 传进来会被本地拦下并提示，不会变成看起来像"应用不存在"的 404。
+- `--output` 可选，相对当前目录；省略时用服务端给的文件名（通常 `<app_id>.zip`）。
+
+## 示例
+
+```bash
+lark-cli apps +export --app-id "$app_id" --output ./src.zip
+lark-cli apps +export --app-id "$app_id"                     # 存成 ./<app_id>.zip
+lark-cli apps +export --meta-token <share-token>             # 别人分享给你的应用
+lark-cli apps +export --app-id "$app_id" --dry-run
+```
+
+## 输出契约
+
+- 成功时 stdout 是 JSON envelope，含 `output`（落盘的绝对路径）与 `size_bytes`；传了 `--app-id` 时还会回显 `app_id`。
+- 归档以流式写盘，不会整包驻留内存，大仓库也安全。
+- 失败时不会留下半个文件。
+
+## 错误处理
+
+| 情况 | 怎么办 |
+|---|---|
+| 应用尚未发布（`code 40901 app not published`） | 该应用是产物托管形态（如静态 HTML 应用），导出的是「最新已发布产物」，而它还没有成功发布过版本，此刻没有可导的东西。**先发布应用再重试**——不是 app_id 写错，重试也没用 |
+| 权限不足（403） | 需要该应用的下载权限。**持有分享 token 不等于有权限** |
+| 应用不存在（404） | 核对 `--app-id` / `--meta-token` 传的是不是对应的裸标识符（不是整条 URL） |