Back to Details

lark-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

apps (v1)

Apps (v1)

bash

undefined

bash

undefined

常用示例

常用示例

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

undefined

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

undefined

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

Prerequisites — Must Read Before Execution

CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：

```
../lark-shared/SKILL.md
```
— 认证、权限处理、全局参数（所有操作通用）
创建应用（
apps +create
） → 必读
```
lark-apps-create.md
```
更新应用元信息（
apps +update
） → 必读
```
lark-apps-update.md
```
（部分更新，未传字段不变）
发布 HTML / PPT / 静态网站（
apps +html-publish
） → 必读
```
lark-apps-html-publish.md
```
（
```
--path
```
文件 vs 目录、tar.gz 打包不做过滤）
设置可用范围（
apps +access-scope-set
） → 必读
```
lark-apps-access-scope-set.md
```
（specific / public / tenant 三态互斥校验、targets JSON 结构）

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

CRITICAL — Before performing the corresponding operations, you MUST use the Read tool to read the following files, none can be omitted:

```
../lark-shared/SKILL.md
```
— Authentication, permission handling, global parameters (applicable to all operations)
Create App (
apps +create
) → Must read
```
lark-apps-create.md
```
Update App Metadata (
apps +update
) → Must read
```
lark-apps-update.md
```
(partial update, unpassed fields remain unchanged)
Publish HTML / PPT / Static Website (
apps +html-publish
) → Must read
```
lark-apps-html-publish.md
```
(
```
--path
```
file vs directory, tar.gz packaging without filtering)
Set Access Scope (
apps +access-scope-set
) → Must read
```
lark-apps-access-scope-set.md
```
(mutual exclusion check for specific / public / tenant, targets JSON structure)

Failing to read the above files before performing operations will lead to incorrect parameter selection, violation of mutual exclusion rules, or incorrect file packaging.

身份与一次性授权

Identity and One-Time Authorization

妙搭应用是用户的个人资产，统一使用
--as user
（CLI 默认

--as auto

会按 shortcut 声明自动落到 user）。

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

bash

lark-cli auth login --domain apps

Miaoda apps are users' personal assets, use
--as user
uniformly (the CLI default

--as auto

will automatically fall to user according to shortcut declarations).

Obtain all scopes of this domain in one go before the first operation to avoid triggering a new round of authorization for each command's first run:

bash

lark-cli auth login --domain apps

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

End-to-End Process (HTML / PPT / Static Website Publishing)

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

用户表达	意图	处理
"部署 ./xxx 的 HTML"、"发布到妙搭"、"开发 xxx 并部署成可分享的网站 / 可访问的链接"、"生成可分享 URL"	明示部署 / 分享	不停下追问，HTML 写完直接走下表 step 1→2
"用 HTML 写一个 PPT / 幻灯片 / 演示文稿"、"做个可演示的 demo"、"写个介绍 xxx 的页面"（没提部署 / 分享 / URL）	仅演示	HTML 写完先输出本地文件路径 + 简要说明，主动追问一句："要部署到妙搭以便分享给别人吗？"用户同意再走 step 1→2；用户说不用就停

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

步骤	命令	说明
1. 新建应用	`apps +create --name "<根据内容主题起的应用名>" --app-type HTML` → 从响应里拿 `app_id`	默认都走新建（不要尝试搜索 / 枚举已有应用）。用户明确要复用现有应用时让他提供妙搭应用链接或 app_id 字符串（详见下方"快速决策"）； `--app-type` 必填，当前只支持 `HTML` （区分大小写），未来扩展
1.5 预检	`apps +html-publish --app-id <id> --path <path> --dry-run` 看 `warnings` 字段	命中 `.git` / `.env` / `.pem` / `.key` 等敏感文件时停下来*，把 warnings 列给用户看，确认要继续才走 step 2；用户没确认前不要去掉 `--dry-run` 真发
2. 发布 HTML	`apps +html-publish --app-id <id> --path <文件或目录>`	必走
3. 设置可用范围（可选）	`apps +access-scope-set --app-id <id> --scope tenant\|public\|specific ...`	用户说"公开 / 全员可见 / 让 Alice 看 / 互联网可分享"等

报告给用户的话术：

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

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

Step 1: Determine whether the user's intention is "Explicit Deployment" or "Demo Only":

User Expression	Intention	Handling
"Deploy HTML in ./xxx", "Publish to Miaoda", "Develop xxx and deploy it as a shareable website / accessible link", "Generate a shareable URL"	Explicit Deployment / Sharing	Do not pause to ask questions, directly follow step 1→2 in the table below after completing the HTML
"Write a PPT / slides / presentation with HTML", "Create a demoable demo", "Write a page introducing xxx" (no mention of deployment / sharing / URL)	Demo Only	After completing the HTML, first output the local file path + brief description, proactively ask: "Do you want to deploy it to Miaoda for sharing with others?" Follow step 1→2 only if the user agrees; stop if the user says no

Step 2: After the user agrees to deploy / has explicitly requested deployment, follow the complete process below and return the final URL to the user:

Step	Command	Description
1. Create New App	`apps +create --name "<App name based on content theme>" --app-type HTML` → Get `app_id` from the response	Default to creating a new app (do not attempt to search / enumerate existing apps). When the user explicitly wants to reuse an existing app, ask them to provide either a Miaoda app link or app_id string (see "Quick Decisions" below); `--app-type` is required, currently only `HTML` is supported (case-sensitive), to be expanded in the future
1.5 Precheck	Run `apps +html-publish --app-id <id> --path <path> --dry-run` and check the `warnings` field	If sensitive files like `.git` / `.env` / `.pem` / `.key` are detected, stop* and list the warnings to the user; proceed to step 2 only after user confirmation; do not remove `--dry-run` to publish without confirmation
2. Publish HTML	`apps +html-publish --app-id <id> --path <file or directory>`	Mandatory step
3. Set Access Scope (Optional)	`apps +access-scope-set --app-id <id> --scope tenant\|public\|specific ...`	Use when users say "Make it public / visible to all employees / accessible to Alice / shareable on the internet", etc.

Script to report to users:

App "{name}" has been published, access link:
{url}

If the user does not specify an access scope but the scenario clearly requires sharing, proactively ask "Do you want to set it as visible to all enterprise members / open to the internet?", but do not ask unnecessarily.

快速决策

Quick Decisions

用户明示"部署 / 发布 ./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 复述给用户

When users explicitly say "Deploy / publish HTML in ./xxx", "Develop xxx and deploy it as a shareable website / accessible link", "Deploy to Miaoda" → Directly follow step 1→2 in the "End-to-End Process", use
```
apps +html-publish
```
for automatic deployment and return the URL, do not ask for confirmation
When users only say "Write a PPT / slides / presentation / demo with HTML", "Develop a demoable page" (no mention of deployment / sharing / URL) → After completing the HTML, first output the local path + brief description, proactively ask "Do you want to deploy it to Miaoda for sharing?", only proceed to publish if the user agrees; do not deploy without permission, but do not forget to ask
When users say "Open App X to all employees / the entire company" → Use
```
--scope tenant
```
, do not pass other flags
When users say "Make it public / accessible to anyone / visible on the internet" → Use
```
--scope public --require-login=<bool>
```
, choose one
When users say "Only allow Alice / a certain department / a certain group to access" → Use
```
--scope specific --targets <JSON>
```
; first convert names to
```
ou_id
```
using
```
contact +search-user
```
, convert group names to
```
chat_id
```
using
```
im +chat-search
```
If the user does not provide an app_id → Default to creating a new app with
apps +create --name "<Name based on content theme>" --app-type HTML
. Do not attempt to search / enumerate existing apps — The command to list apps is not visible to the Agent, and forcing a call will only waste an OAPI request. If the user explicitly wants to reuse an existing app, ask them to provide one of the following:
- Miaoda app link: In the format
```
https://miaoda.feishu.cn/app/app_xxxxxxxxxxxxx
```
  (or with trailing slash
```
/app/app_xxx/
```
  ) — The
```
app_id
```
  is the path segment after
```
/app/
```
  (starting with
```
app_
```
  ). Simple way to extract from URL:
```
APP_ID=$(echo "$URL" | sed -E 's|.*/app/([^/?#]+).*|\1|')
```
- app_id string: Directly provided by the user as
```
app_xxxxxxxxxxxxx
```
  , no further processing needed
```
--path
```
can accept either a single HTML file or a directory; directories will be recursively packaged into tar.gz without filtering, remind users to pass clean output directories (e.g.,
```
./dist
```
) to avoid packaging
```
.git
```
/
```
node_modules
```
together
```
apps +update
```
only updates passed fields, unpassed fields remain unchanged; at least one of
```
--name
```
/
```
--description
```
must be passed, otherwise it will be directly blocked during the Validate stage
The three scopes for
```
apps +access-scope-set
```
are mutually exclusive: specific requires
```
--targets
```
and does not allow
```
--require-login
```
; public requires
```
--require-login
```
and does not allow
```
--targets
```
/
```
--apply-enabled
```
/
```
--approver
```
; tenant does not allow any other flags
When failing, prioritize relaying
error.hint
(executable repair suggestions provided by the CLI); if hint is empty, fallback to
```
error.message
```
; do not repeat the envelope JSON as-is to the user

Shortcuts（推荐优先使用）

Shortcuts (Recommended for Priority Use)

Shortcut 是对常用操作的高级封装（

lark-cli apps +<verb> [flags]

）。有 Shortcut 的操作优先使用。

Shortcut	说明
`+create`	创建妙搭应用（name / description / icon-url）
`+update`	部分更新应用名 / 描述（只发传入字段）
`+access-scope-set`	设置应用可用范围（specific / public / tenant，三态互斥校验）
`+html-publish`	把本地 HTML 文件 / 目录 / PPT / 静态网站部署为可分享的妙搭应用，返回访问 URL（用户明示部署 / 分享时直接调；仅说"可演示"时先问用户是否要部署再调）

Shortcuts are advanced encapsulations of common operations (

lark-cli apps +<verb> [flags]

). Use shortcuts preferentially for operations that have them.

Shortcut	Description
`+create`	Create a Miaoda app (name / description / icon-url)
`+update`	Partially update app name / description (only send passed fields)
`+access-scope-set`	Set app access scope (specific / public / tenant, mutual exclusion check)
`+html-publish`	Deploy local HTML files / directories / PPT / static websites as shareable Miaoda apps and return access URLs (call directly when users explicitly request deployment / sharing; ask users whether to deploy first when only "demoable" is mentioned)