Lark Apps

apps (v1)

# 常用示例
lark-cli apps +create           --name "客户调研问卷" --app-type HTML
lark-cli apps +html-publish     --app-id app_xxx --path ./dist
lark-cli apps +access-scope-set --app-id app_xxx --scope tenant

品牌可用性（先做）

跑 lark-cli apps --help；若提示暂未支持，告诉用户敬请期待并停止。

前置条件 — 执行操作前必读

CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可： 1. `../lark-shared/SKILL.md` — 认证、权限处理、全局参数（所有操作通用） 2. 创建应用（`apps +create`） → 必读 `lark-apps-create.md` 3. 更新应用元信息（`apps +update`） → 必读 `lark-apps-update.md`（部分更新，未传字段不变） 4. 发布 HTML / PPT / 静态网站（`apps +html-publish`） → 必读 `lark-apps-html-publish.md`（--path 文件 vs 目录、tar.gz 打包不做过滤） 5. 设置可用范围（`apps +access-scope-set`） → 必读 `lark-apps-access-scope-set.md`（specific / public / tenant 三态互斥校验、targets JSON 结构） 6. 查看当前可用范围（`apps +access-scope-get`） → 必读 `lark-apps-access-scope-get.md`（响应 scope 枚举 All / Tenant / Range 与 CLI 的 public / tenant / specific 映射；含 jq 复制 scope 配置示例）

未读完以上文件就执行相应操作会导致参数选择错误、互斥违反或文件被错误打包。

身份与一次性授权

妙搭应用是用户的个人资产，统一使用 `--as user`（CLI 默认 --as auto 会按 shortcut 声明自动落到 user）。

首次操作前一次性把本域 scope 全拿到，避免每条命令首次跑都触发新一轮授权：

lark-cli auth login --domain apps

命令失败且 error.subtype == "missing_scope" 时，统一引导用户跑：

lark-cli auth login --domain apps

写 HTML 前的硬约束（避免 publish 阶段被拒）

• 入口文件必须叫 `index.html` — 妙搭以 index.html 作为应用入口；目录形态时根目录下要有 index.html，单文件形态时文件名就是 index.html。命名成 app.html / demo.html 等会被 +html-publish 直接拒绝
• `--path` 内不能含已知凭据文件 — Validate 阶段会扫描 .env / .env.* / .npmrc / .netrc / .git-credentials / .aws/credentials / .docker/config.json / .kube/config，命中就 exit 非 0 拒绝（dry-run 也一样拦）。要么从产物目录里清掉这些文件，要么明确传 --allow-sensitive 跳过这道检查（例如教程站故意 shipping .env.example 作为示例素材）。--path . 本身不再硬拒，cwd 干净就能发

端到端流程（HTML / PPT / 静态网站发布）

第一步：判断用户意图是「明示部署」还是「仅演示」：

第二步：用户同意部署 / 已明示部署后，按下表走完整链路并把最终 URL 返回给用户：

报告给用户的话术：

应用「{name}」已发布，访问链接：{url}

若用户没指定可用范围且场景明显需要分享，主动追问一句"要设为企业全员 / 互联网公开吗？"，但不要为了问而问。

快速决策

• 用户明示"部署 / 发布 ./xxx 的 HTML"、"开发 xxx 并部署成可分享的网站 / 可访问的链接"、"发到妙搭" → 直接走「端到端流程」step 1→2，apps +html-publish 自动部署并返回 URL，不要追问
• 用户只说"用 HTML 写 PPT / 幻灯片 / 演示文稿 / demo"、"开发一个可演示的页面"（没提部署 / 分享 / URL） → HTML 写完先输出本地路径 + 简要说明，主动问一句"要部署到妙搭以便分享吗？"，用户同意才走 publish；不要擅自部署，但也不要忘了问
• 用户说"把应用 X 开放给全员 / 全公司" → --scope tenant，不要再传别的 flag
• 用户说"公开 / 让任何人都能访问 / 互联网可见" → --scope public --require-login=<bool>，二选一
• 用户说"只让 Alice / 某部门 / 某群访问" → --scope specific --targets <JSON>；姓名先用 contact +search-user 换 ou_id，群名先用 im +chat-search 换 chat_id
• 用户没给 app_id → 默认 `apps +create --name "<根据内容主题起的名字>" --app-type HTML` 新建一个。不要尝试搜索 / 枚举已有应用 —— 列举应用的命令对 Agent 不可见，强行调用也只会浪费一次 OAPI 请求。如果用户明确要复用现有应用，让他提供下列任一种：
• 妙搭应用链接：形如 https://miaoda.feishu.cn/app/app_xxxxxxxxxxxxx（或带尾斜杠 /app/app_xxx/）—— app_id 是 /app/ 后面的 path segment（以 app_ 开头）。从 URL 中提取的简单办法：APP_ID=$(echo "$URL" | sed -E 's|.*/app/([^/?#]+).*|\1|')
• app_id 字符串：用户直接给的 app_xxxxxxxxxxxxx，不需要再做处理
• --path 既可传单个 HTML 文件也可传目录；目录会递归打包成 tar.gz 不做过滤，要提醒用户传干净的产物目录（如 ./dist），避免把 .git / node_modules 一起打进去
• apps +update 只更新传入字段，未传字段保持不变；--name / --description 至少传一个，否则 Validate 阶段直接拦截
• apps +access-scope-set 三种 scope 互斥：specific 必传 --targets、不允许 --require-login；public 必传 --require-login、不允许 --targets / --apply-enabled / --approver；tenant 不允许任何其他 flag
• 失败时优先转述 `error.hint`（CLI 给的可执行修复建议），hint 为空时退回 error.message；不要原样把 envelope JSON 复述给用户。error.subtype == "missing_scope" 例外：按上面「身份与一次性授权」走

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli apps +<verb> [flags]）。有 Shortcut 的操作优先使用。

apps +access-scope-get

前置条件： 先阅读 `../lark-shared/SKILL.md`。

获取应用当前的可用范围配置。一次 GET /apps/{appId}/access-scope 调用，响应原样透传服务端契约（字符串 scope 枚举 + 拆分数组）。

命令

lark-cli apps +access-scope-get --app-id app_xxx

参数

返回值

成功（specific，三种 target 类型混合）：

{
  "ok": true,
  "data": {
    "scope": "Range",
    "users": ["ou_xxx", "ou_yyy"],
    "departments": ["od_xxx"],
    "chats": ["oc_xxx"],
    "apply_config": {
      "enabled": true,
      "approvers": ["ou_approver"]
    }
  }
}

成功（public + 免登）：

{ "ok": true, "data": { "scope": "All", "require_login": false } }

成功（tenant）：

{ "ok": true, "data": { "scope": "Tenant" } }

失败：

{ "ok": false, "error": { "type": "api", "message": "...", "hint": "..." } }

字段语义

• scope 是字符串枚举：
• "All" = 互联网公开 — 对应 apps +access-scope-set --scope public
• "Tenant" = 组织内 — 对应 --scope tenant
• "Range" = 部分人员 — 对应 --scope specific
• users / departments / chats 三个数组（仅 scope="Range" 时）：服务端拆分形态，CLI 不合并回统一 targets
• apply_config（可选，仅 scope="Range" 且申请开启时）：含 enabled 和 approvers（只允许一个 user open_id）
• require_login（仅 scope="All" 时）：bool

典型场景

场景 1：查看当前应用对谁可见

lark-cli apps +access-scope-get --app-id app_xxx

按 scope 值组装报告：

• scope="All" → "应用 {app_id} 当前互联网公开（require_login={require_login}）"
• scope="Tenant" → "应用 {app_id} 当前对企业全员可见"
• scope="Range" → "应用 {app_id} 当前指定可见，包含 N 个用户 / M 个部门 / K 个群"

场景 2：把 GET 响应拼回 +access-scope-set 命令（复制 / 备份可用范围）

# 拼一个 --targets JSON 数组（jq）
lark-cli apps +access-scope-get --app-id app_src -q '
  .data
  | (.users        // [] | map({type:"user",       id:.}))
  + (.departments // [] | map({type:"department", id:.}))
  + (.chats        // [] | map({type:"chat",       id:.}))
'

得到 [{"type":"user","id":"ou_x"}, ...] 数组，可作为 apps +access-scope-set --targets '...' 的入参。

协同命令

参考

• lark-apps
• lark-shared

apps +access-scope-set

前置条件： 先阅读 `../lark-shared/SKILL.md`。

设置应用的可用范围。三种 scope 形态互斥：specific（指定可见）、public（互联网公开）、tenant（企业全员）。

命令

# 指定可见 + 允许申请（targets 支持 user / department / chat 三种类型）
lark-cli apps +access-scope-set --app-id app_xxx \
  --scope specific \
  --targets '[{"type":"user","id":"ou_xxx"},{"type":"department","id":"od_xxx"},{"type":"chat","id":"oc_xxx"}]' \
  --apply-enabled \
  --approver ou_yyy

# 互联网公开 + 免登
lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=false

# 企业全员
lark-cli apps +access-scope-set --app-id app_xxx --scope tenant

参数

互斥校验（Validate 阶段，不通过直接报错不发请求）

• scope=specific：必传 --targets；不允许 --require-login
• scope=public：必传 --require-login；不允许 --targets / --apply-enabled / --approver
• scope=tenant：不允许任何其它 flag
• --targets 内每项的 type 必须是 user / department / chat 之一

返回值

成功：

{ "ok": true, "data": {} }

API 失败：

{ "ok": false, "error": { "type": "api", "message": "...", "hint": "..." } }

Validate 失败（互斥违反，CLI 本地校验）：

{ "ok": false, "error": { "type": "validation", "message": "--targets is required when --scope=specific" } }

字段语义

• 成功时 data 为空对象，CLI 端基于 --scope 构造给用户的报告语
• Validate 错的 error.type=validation 是本地校验，不发请求

典型场景

场景 1：用户说"把应用 X 开放给全员"

lark-cli apps +access-scope-set --app-id app_xxx --scope tenant

应用 {app_id} 可用范围已设为企业全员。

场景 2：用户说"把应用 X 设为互联网公开 + 免登"

lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=false

应用 {app_id} 可用范围已设为互联网公开（免登）。

场景 3：用户说"只让 Alice 和 Bob 访问应用 X"

先用 lark-cli contact +search-user --query Alice 拿到 ou_id，再调：

lark-cli apps +access-scope-set --app-id app_xxx \
  --scope specific \
  --targets '[{"type":"user","id":"ou_alice"},{"type":"user","id":"ou_bob"}]'

应用 {app_id} 可用范围已设为指定可见，目标人数 2。

场景 4：用户说"开放给「项目讨论群」"

把群名转 chat_id：用 lark-cli im +chat-search --query "项目讨论群"，再调：

lark-cli apps +access-scope-set --app-id app_xxx \
  --scope specific \
  --targets '[{"type":"chat","id":"oc_xxx"}]'

场景 5：互斥违反

例如 --scope tenant --targets ... —— Validate 本地拦截。不发请求。

场景 6：API 失败

转述 error.hint / error.message。

协同命令

参考

• lark-apps
• lark-shared

apps +create

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

创建一个新的妙搭应用。一次 POST /apps 调用，返回新建应用的元信息。

命令

# 最小调用
lark-cli apps +create --name "客户调研问卷" --app-type HTML

# 全参数
lark-cli apps +create \
  --name "客户调研问卷" \
  --app-type HTML \
  --description "本季度客户满意度调研" \
  --icon-url "https://lf3-static.bytednsdoc.com/.../feisuda/avatar/5.svg"

# Dry-run（仅打印请求，不执行）
lark-cli apps +create --name "Demo" --app-type HTML --dry-run

参数

返回值

成功：

{
  "ok": true,
  "data": {
    "app": {
      "app_id": "app_4k5jepcbjmv6m",
      "name": "客户调研问卷",
      "description": "本季度客户满意度调研",
      "icon_url": "https://lf3-static.bytednsdoc.com/.../feisuda/avatar/5.svg",
      "created_at": "2026-05-18T10:00:00Z"
    }
  }
}

失败：

{
  "ok": false,
  "error": {
    "type": "api",
    "code": 99991400,
    "message": "...",
    "hint": "可执行的修复建议（可能为空）"
  }
}

字段语义

• app_type 是应用类型枚举，区分大小写，当前只允许 HTML，未来会扩展（如 SPA、NATIVE 等）；不在白名单的取值 CLI 端会直接拒绝
• created_at 是 ISO 8601 UTC 时间字符串
• error.hint 是 CLI 给出的可执行修复建议，优先转述给用户；hint 为空时退回 error.message
• 不要原样把 envelope JSON 复述给用户

典型场景

场景 1：用户说"创建一个妙搭应用，名字叫 X"

目前只支持 HTML 类型，统一传 --app-type HTML（用户没说类型时不要追问，直接用大写 HTML，区分大小写）：

lark-cli apps +create --name "X" --app-type HTML

向用户报告：

应用「{name}」已创建（ID: {app_id}）。

可选建议下一步：

接下来用 apps +html-publish --app-id {app_id} --path <你的 HTML 目录> 发布内容。

场景 2：用户提供完整元信息

lark-cli apps +create --name "Q4 调研" --app-type HTML --description "..."

返回后同场景 1。

场景 3：失败处理

转述 error.hint（优先）或 error.message，不要原样输出 envelope JSON。

协同命令

参考

• lark-apps — 妙搭应用全部命令
• lark-shared — 认证和全局参数

apps +html-publish

前置条件： 先阅读 `../lark-shared/SKILL.md`。

把本地的 HTML 文件或目录部署为可访问的妙搭应用，响应返回应用的访问链接 url。

命令

# 发布整个目录
lark-cli apps +html-publish --app-id app_xxx --path ./dist/

# 发布单个 HTML 文件
lark-cli apps +html-publish --app-id app_xxx --path ./index.html

# 预演（打印文件清单 + SHA256 + 目标 endpoint，不发请求）
lark-cli apps +html-publish --app-id app_xxx --path ./dist --dry-run

参数

返回值

成功：

{
  "ok": true,
  "data": {
    "url": "https://miaoda.feishu.cn/app/app_4k5jepcbjmv6m"
  }
}

业务失败（如构建失败、应用不存在）：

{
  "ok": false,
  "error": {
    "type": "api",
    "code": 90001,
    "message": "html-publish failed (code=90001): build failed: dependency conflict",
    "hint": "构建失败：用 `lark-cli apps +html-publish --path <path> --dry-run` 检查打包文件清单"
  }
}

基础设施失败（网络 / HTTP 5xx）：

{
  "ok": false,
  "error": { "type": "network", "message": "...", "hint": "" }
}

Validate 失败（本地校验，如缺 --app-id）：

{
  "ok": false,
  "error": { "type": "validation", "message": "--app-id is required" }
}

字段语义

典型场景

场景 1：用户说"把这个目录发布到妙搭"

lark-cli apps +html-publish --app-id app_xxx --path ./dist

成功后：

应用发布成功！访问 {url} 查看。

可选追加：

如需让其他人访问，可以用 apps +access-scope-set 设置可用范围。

场景 2：用户没有 app_id

APP=$(lark-cli apps +create --name "..." --app-type HTML -q '.data.app.app_id' | tr -d '"')
lark-cli apps +html-publish --app-id "$APP" --path ./dist

场景 3：构建失败（code=90001）

转述 hint：

构建失败，建议用 lark-cli apps +html-publish --app-id <your-app-id> --path ./dist --dry-run 看一下打包文件清单是否完整。

场景 4：应用不存在（code=90002）

hint："应用不存在或无权访问；请用户确认妙搭应用链接 / app_id 是否正确（从 https://miaoda.feishu.cn/app/app_xxx 的 /app/ 后面取）"

转述给用户。

场景 5：网络 / 服务端失败（type=network）

服务暂时不可用，建议稍后重试。

凭据文件拦截

Validate 阶段会扫描 --path 下所有候选文件，命中以下任一模式 直接 exit 非 0（dry-run 和真发都拦，不再是 advisory warning）：

• .env / .env.*（环境变量 / API key）
• .npmrc / .netrc（HTTP 凭据）
• .git-credentials（Git over HTTPS 凭据）
• .aws/credentials、.docker/config.json、.kube/config（云 SDK 凭据）

报错形态：

{
  "ok": false,
  "error": {
    "type": "validation",
    "message": "--path contains 1 credential file(s) that should not be published: dist/.env",
    "hint": "remove these files from the publish payload, OR pass --allow-sensitive if shipping them is intentional (e.g. a docs site demoing credential-file formats)"
  }
}

Agent 行为契约：

• 默认必须从产物里清掉命中的文件后再 publish
• 只有当用户明确意图是 shipping 凭据示例（文档 / 教程站等）时，才追加 --allow-sensitive 旁路；旁路时 dry-run 会在 sensitive_waived 字段列出被放行的文件名，转述给用户确认

不在拦截范围内（旧版扫过、新版不再扫）：.git/ SCM 历史、SSH 私钥 id_rsa* / id_ed25519* 等、*.pem / *.key、.aws/config。如果产物里有这些文件且确实敏感，要靠用户自己保持产物目录干净。

提示

• --path 既可以是 cwd（.）也可以是子目录或单文件；不再硬拒 cwd，cwd 干净（没有命中上面凭据列表）就能发。仍然建议传具体子目录（./dist、./public/ 等）以减少误打包风险
• --path 必须是 cwd 内的相对路径（如 ./dist、./index.html）；绝对路径或越界路径（../、/Users/...）CLI 会直接拒绝。需要发布 cwd 外的目录时，先切到 agent 工作目录再调，不要私自 cd 绕过
• 目录打包成 tar.gz 时不做过滤（.git / node_modules 等会一并打包，只有上面那张凭据 list 才会被 Validate 拦），让用户传干净的产物目录（如 ./dist）
• 旁路写法：apps +html-publish --app-id <id> --path <path> --allow-sensitive
• 不要原样把 envelope JSON 转述给用户

协同命令

参考

• lark-apps
• lark-shared

apps +list

⚠️ Hidden 命令（`Hidden: true`）—— 不对 Agent 暴露：本命令从 --help / tab completion / SKILL.md 的 Shortcuts 表中隐去，Agent 不应主动调用。

>

需要拿现有应用的 app_id 时让用户提供 妙搭应用链接（如 https://miaoda.feishu.cn/app/app_xxxxxxxxxxxxx）然后从 URL 中提取，或者让用户直接给 app_id 字符串。详见 `../SKILL.md` "用户没给 app_id" 一节。

>

本文件保留是因为命令仍然功能可用（手动调用），下面内容仅供人类参考。

前置条件： 先阅读 `../lark-shared/SKILL.md`。

列出当前用户名下的妙搭应用。cursor 分页：默认拉一页（--page-size 20），通过 --page-token 拉下一页。

命令

# 拉第一页（默认 page_size=20）
lark-cli apps +list

# 自定义页大小
lark-cli apps +list --page-size 50

# 翻页（拿上一次响应的 page_token）
lark-cli apps +list --page-token "eyJQaW5PcmRlciI6..."

# 取 ID 列表（脚本场景）
lark-cli apps +list -q '.data.items[].app_id'

# 按名字找 app_id
lark-cli apps +list -q '.data.items[] | select(.name=="客户调研问卷") | .app_id'

参数

返回值

成功：

{
  "ok": true,
  "data": {
    "items": [
      {
        "app_id": "app_4k5jepcbjmv6m",
        "name": "客户调研问卷",
        "description": "...",
        "icon_url": "...",
        "created_at": "2026-05-18T10:00:00Z",
        "updated_at": "2026-05-18T10:05:00Z"
      }
    ],
    "page_token": "cursor_next_xxx",
    "has_more": true
  }
}

成功（空列表）：

{ "ok": true, "data": { "items": [], "has_more": false } }

失败：

{ "ok": false, "error": { "type": "api", "message": "...", "hint": "..." } }

字段语义

• data.items 长度可能为 0（用户没建过应用）
• data.has_more=true 表示还有下一页；用 data.page_token 作为下次 --page-token 传入
• data.has_more=false 且 data.page_token 为空 / 缺省表示已经到末尾

用途

本命令保留可供人类操作员手动调用（例如运维 / 调试场景，按 name 搜应用 ID）。Agent 不应主动调用：默认行为是 apps +create 新建；要复用现有应用，让用户给妙搭应用链接或 app_id，详见 `../SKILL.md` "用户没给 app_id" 一节。

协同命令

参考

• lark-apps
• lark-shared

apps +update

前置条件： 先阅读 `../lark-shared/SKILL.md`。

部分更新一个妙搭应用的元信息（名字 / 描述）。只把传入的字段发给服务端，未传字段保持不变。

命令

lark-cli apps +update --app-id app_xxx --name "调研问卷 v2"
lark-cli apps +update --app-id app_xxx --description "新描述"
lark-cli apps +update --app-id app_xxx --name "v2" --description "新描述"

参数

--name 和 --description 至少传一个，否则 Validate 阶段报错。

返回值

成功：

{
  "ok": true,
  "data": {
    "app": {
      "app_id": "app_4k5jepcbjmv6m",
      "name": "调研问卷 v2",
      "description": "...",
      "icon_url": "https://lf3-static.bytednsdoc.com/.../feisuda/avatar/5.svg",
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:05:00Z"
    }
  }
}

失败：

{
  "ok": false,
  "error": { "type": "api", "message": "...", "hint": "..." }
}

字段语义

• 响应 data.app 含完整应用对象（所有字段），不只是被改的
• created_at / updated_at 都是 ISO 8601 UTC 时间字符串
• 失败时优先转述 error.hint

典型场景

场景 1：用户说"把应用 X 改名叫 Y"

lark-cli apps +update --app-id app_xxx --name "Y"

应用 {app_id} 已更新，新名字「{name}」。

场景 2：缺 --app-id 或没传可更新字段

Validate 直接拦截，提示用户加 flag。

场景 3：失败处理

转述 error.hint / error.message。

协同命令

参考

• lark-apps
• lark-shared