chore(apps): refine lark-apps skill description and surface (#1040)

- description: switch from trigger-word enumeration to a general
  principle (any HTML artifact intended to be independently accessible
  falls under this skill; defer the deploy-vs-demo decision to the
  skill body)
- surface apps +access-scope-get in prerequisites list and Shortcuts
  table so agents can find the read side of access-scope
- add "writing HTML hard constraints" section: index.html is the
  required entry filename, --path cannot equal cwd (both are CLI-side
  hard rejects that previously only lived in the html-publish ref)
This commit is contained in:
raistlin042
2026-05-22 16:39:36 +08:00
committed by GitHub
parent ffcf7781b4
commit d5d2fee848

View File

@@ -1,6 +1,6 @@
---
name: lark-apps
description: "把本地 HTML 文件或目录部署到飞书妙搭Miaoda生成可分享访问的 Web 页面并返回 URL管理应用的创建、更新、列表和访问范围。当用户要把 HTML、静态网站或 Web demo 发布成可分享链接,或提到妙搭 / Miaoda 时使用。不用于:上传普通文件到云空间(用 lark-drive、编辑飞书云文档内容用 lark-doc、创建飞书原生幻灯片 / 演示文稿(用 lark-slides。"
description: "把本地 HTML 文件或目录部署到飞书妙搭Miaoda生成一个公网可访问的应用及其链接URL。当用户要创建 HTML 或要把 HTML、静态网站或 Web demo 发布成公网可访问的链接 / 可分享链接、设置应用共享范围,或提到妙搭 / Miaoda 时使用。凡产出可独立访问的 HTML 产物都属本 skill 的潜在归宿,是否真要部署由 skill 内部协议判断。不用于:上传普通文件到云空间(用 lark-drive、编辑飞书云文档内容用 lark-doc、创建飞书原生幻灯片 / 演示文稿(用 lark-slides。"
metadata:
requires:
bins: ["lark-cli"]
@@ -28,6 +28,7 @@ lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
3. **更新应用元信息(`apps +update`** → 必读 [`lark-apps-update.md`](references/lark-apps-update.md)(部分更新,未传字段不变)
4. **发布 HTML / PPT / 静态网站(`apps +html-publish`** → 必读 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)`--path` 文件 vs 目录、tar.gz 打包不做过滤)
5. **设置可用范围(`apps +access-scope-set`** → 必读 [`lark-apps-access-scope-set.md`](references/lark-apps-access-scope-set.md)specific / public / tenant 三态互斥校验、targets JSON 结构)
6. **查看当前可用范围(`apps +access-scope-get`** → 必读 [`lark-apps-access-scope-get.md`](references/lark-apps-access-scope-get.md)(响应 scope 枚举 `All` / `Tenant` / `Range` 与 CLI 的 `public` / `tenant` / `specific` 映射;含 jq 复制 scope 配置示例)
**未读完以上文件就执行相应操作会导致参数选择错误、互斥违反或文件被错误打包。**
@@ -41,6 +42,11 @@ lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
lark-cli auth login --domain apps
```
## 写 HTML 前的硬约束(避免 publish 阶段被拒)
- **入口文件必须叫 `index.html`** — 妙搭以 `index.html` 作为应用入口;目录形态时根目录下要有 `index.html`,单文件形态时文件名就是 `index.html`。命名成 `app.html` / `demo.html` 等会被 `+html-publish` 直接拒绝
- **`--path` 不能等于当前工作目录(`.` / cwd** — 源码硬拒,避免误把 `.git` / `.env` / `node_modules` 一并打包并通过 share URL 公开。HTML 产物放进具体子目录(如 `./dist``./public``./<page-name>/`)或单文件路径
## 端到端流程HTML / PPT / 静态网站发布)
**第一步:判断用户意图是「明示部署」还是「仅演示」**
@@ -89,4 +95,5 @@ Shortcut 是对常用操作的高级封装(`lark-cli apps +<verb> [flags]`
| [`+create`](references/lark-apps-create.md) | 创建妙搭应用name / description / icon-url |
| [`+update`](references/lark-apps-update.md) | 部分更新应用名 / 描述(只发传入字段) |
| [`+access-scope-set`](references/lark-apps-access-scope-set.md) | 设置应用可用范围specific / public / tenant三态互斥校验 |
| [`+access-scope-get`](references/lark-apps-access-scope-get.md) | 查看应用当前可用范围(响应 scope 枚举 `All` / `Tenant` / `Range`;可作"备份 / 复制 scope 配置"前置读) |
| [`+html-publish`](references/lark-apps-html-publish.md) | **把本地 HTML 文件 / 目录 / PPT / 静态网站部署为可分享的妙搭应用,返回访问 URL**(用户明示部署 / 分享时直接调;仅说"可演示"时先问用户是否要部署再调) |