@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-apps/references/lark-apps-git-credential.md

@@ -0,0 +1,37 @@
+# apps Git credential
+
+妙搭 Git 凭证用于本地原生 `git clone/pull/push`。运行时命令事实以 `lark-cli apps +git-credential-init --help`、`+git-credential-list --help`、`+git-credential-remove --help` 为准。
+
+## 命令
+
+```bash
+lark-cli apps +git-credential-init --app-id app_xxx
+lark-cli apps +git-credential-list
+lark-cli apps +git-credential-remove --app-id app_xxx
+```
+
+## 输出契约
+
+- `+git-credential-init` 成功后读取 `data.repository_url`；不要展示或保存其中的凭据细节，只用于下一步 `git clone`。
+- `+git-credential-list` 返回本地记录和状态；可用来判断是否需要重新 init。
+- `+git-credential-remove` 只清本地配置；成功后告知不会删除云端应用或仓库。
+
+## 行为规则
+
+- `+git-credential-init` 返回 `repository_url`，并配置 URL-scoped Git credential helper。后续 clone/pull/push 使用原生 git。
+- `+git-credential-list` 列出本地已配置的妙搭 Git 凭证，不需要 `--app-id`。
+- `+git-credential-remove` 只移除本地凭证/helper，不删除云端应用或仓库。
+- 看到 Repository URL 后继续：
+
+```bash
+git clone <repository_url>
+cd <repo>
+git checkout sprint/default
+```
+
+## Agent 规则
+
+- 不要手动打印、保存或拼接 token。
+- clone、pull、push、diff、log 等代码仓库操作都使用原生 `git`；不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
+- 不要 push/force-push `main`；`main` 是发布态快照，由 `apps +release-create` 成功后服务端推进，直推/force-push 会被服务端护栏拒绝。
+- Git 认证失败、本地凭证损坏或 helper 缺失时，重新执行 `+git-credential-init --app-id <id>` 覆盖本地配置；不要让用户复制 token 到 remote URL。

package/skills/lark-apps/references/lark-apps-html-publish.md

@@ -0,0 +1,62 @@
+# apps +html-publish
+
+把本地 HTML 文件或静态目录发布为妙搭应用访问 URL。运行时命令事实以 `lark-cli apps +html-publish --help` 为准。
+
+## 何时用
+
+用于把已经存在的本地 HTML 文件或静态产物目录发布成妙搭访问 URL。它不负责生成 HTML 内容，也不负责全栈应用代码发布。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--path`。
+- `--path` 可以是单个文件或目录；入口必须是 `index.html`。
+- 可选：`--allow-sensitive`，跳过凭据文件扫描。
+- 客户端打包 tar.gz 上传发布。三条硬性大小限制，任一超限即被客户端拒绝、无法发布：单个 `.html` 文件 ≤ 10MB、打包后 tar.gz ≤ 20MB、未压缩候选文件总量 ≤ 200MB。
+
+## 示例
+
+```bash
+lark-cli apps +create --name "Demo" --app-type html
+lark-cli apps +html-publish --app-id app_xxx --path ./dist
+lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
+```
+
+## 输出契约
+
+根据应用类型，输出字段不同：
+
+- **静态 HTML 应用**：`data.url` 是本轮发布后的访问链接，一步完成发布。
+- **其他 HTML 应用**：`data.release_id` 是发布标识，命令内部已完成产物上传和发布创建。用 `+release-get --app-id <app_id> --release-id <release_id>` 轮询发布状态直到 `finished`。
+
+判断走哪条路径：有 `url` 字段说明已直接发布完成；有 `release_id` 字段说明需要用 `+release-get` 轮询。
+
+- 业务失败如构建失败、应用不存在通常带 `error.hint`；优先转述 hint。网络/服务端失败则建议稍后重试。
+
+## 链接边界
+
+- 开发态链接可由 `app_id` 拼出：`https://miaoda.feishu.cn/app/{app_id}`，用于进入妙搭编辑/开发态。
+- 发布态访问链接以本命令成功返回的 `data.url` 为准。
+- 重新发布前，`+list` 的 `is_published=true` 只能说明历史上发布过，不代表当前本地产物已经部署。
+
+## 发布前置门（第一步，先于任何其他动作）
+
+收到发布意图后，第一个动作是量三个尺寸，不是读文件内容、不是打包：
+1. 单个 `.html` ≤ 10MB / tar.gz ≤ 20MB / 未压缩总量 ≤ 200MB。
+2. 任一超限 → 立即 STOP，把超限数字转述给用户，交还决定权。
+3. 三项都通过 → 才进入下面的命令骨架。
+
+## 预览与发布边界
+
+- 用户只说“用 HTML 写个 PPT/页面给我看看”时，先生成本地文件或目录，返回路径并问是否发布到妙搭分享；不要默认创建应用或部署。
+- 用户明确说“部署出去/发链接/可分享”时，才创建 `html` 应用并用 `+html-publish`。
+- 用户要发布但没有 app_id 时，先 `+create --app-type html` 创建应用；应用名可从页面/站点主题生成，不要让用户手动提供 app_id。
+- 若产物首页不是 `index.html`，发布前改名或复制为 `index.html`；目录发布时只传干净产物目录，例如 `./dist`。`.git` 目录会被自动排除，不会进入压缩包。
+- 重新部署同一个 HTML 应用时复用原 `app_id`，只重新执行 `+html-publish --app-id <id> --path <dir-or-index.html>`。
+
+## 安全规则
+
+默认会拦截 `.env`、`.npmrc`、`.aws/credentials` 等凭据文件。只有用户明确要发布凭据示例文件或教程内容时，才追加 `--allow-sensitive`；追加前先说明将包含哪些敏感候选文件。
+
+## 常见失败
+
+- 缺少 `index.html`：目录根放置 `index.html`，或单文件路径直接指向名为 `index.html` 的文件。

package/skills/lark-apps/references/lark-apps-init.md

@@ -0,0 +1,36 @@
+# apps +init
+
+`+init` 初始化妙搭应用的代码（clone 仓库、scaffold/同步源码、拉取本地环境变量）。运行时命令事实以 `lark-cli apps +init --help` 为准。
+
+## 何时用
+
+用于把妙搭全栈应用源码拉到本地并准备开发环境。用户只是要云端 Agent 生成应用时，不要初始化本地仓库。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选：`--dir`，clone 目标目录；省略时默认 `./<app-id>`。
+- 固定 checkout 分支：`sprint/default`。
+- `+init` 会初始化 Git 凭证、clone 仓库、切到工作分支并生成/同步本地项目。
+
+## 示例
+
+```bash
+lark-cli apps +init --app-id app_xxx --dir ./my-app
+lark-cli apps +init --app-id app_xxx --dir /absolute/path/my-app
+lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
+```
+
+## 输出契约
+
+- 真跑时 stdout 是 JSON envelope；stderr 会有 `->` / `→` 进度行。成功读 stdout，失败解析 stderr 末尾的 JSON 错误。
+- 成功普通初始化读取 `data.clone_path`、`branch`、`committed`、`pushed`；`repository_url` 已脱敏，不要当凭据使用。
+- `scaffold=already_initialized` 表示目录已初始化：跳过 clone/scaffold/commit，但仍会执行一次 env-pull 刷新本地环境变量（输出含 `env_pulled`，成功时含 `env_file`，失败时含 `env_pull_error` 且退出码仍为 0）；此时通常没有 `repository_url` / `branch`。
+- `--dry-run` 只打印计划，不执行 git / npx；若输出含 `dir_error`，真跑前先让用户换目录。
+
+## Agent 规则
+
+- 目标目录必须不存在、为空目录，或已含 `.spark/meta.json` 且其 app_id 与 `--app-id` 一致的已初始化仓库。
+- 目标目录已含 `.spark/meta.json` 时，`+init` 会跳过 clone/scaffold，但仍执行一次 env-pull 刷新本地环境变量；告知用户“仓库已初始化，本地环境变量已刷新，可直接开发”，不要误报失败或重复 clone。
+- `+init` 输出没有必要原样复述；告诉用户 clone path、分支和下一步即可。
+- 新建应用做本地初始化时，若选定的目标目录已存在，不要复用，改用一个不冲突的目录名（已预授权”放手做”时自动追加后缀如 `-2`；否则向用户确认目录名）。

package/skills/lark-apps/references/lark-apps-list.md

@@ -0,0 +1,37 @@
+# apps +list
+
+列出当前用户可见的妙搭应用，用于从应用名定位 `app_id`。运行时命令事实以 `lark-cli apps +list --help` 为准。
+
+## 何时用
+
+在下游操作需要 `app_id`、而用户只给了应用名/描述时,用 `--keyword` 定位。无明确目的的全量枚举会浪费上下文,优先按关键词缩小范围。
+
+## 命令骨架
+
+- 支持 `--keyword` 按应用名模糊搜索。
+- `--ownership` 枚举：`all` / `mine` / `shared`（默认 `all` = 我创建的 + 共享给我的；`mine` = 仅我创建；`shared` = 仅共享给我）。
+- `--app-type` 枚举：`html` / `full_stack`。
+- 分页：`--page-size` 默认 20，`--page-token` 传上一页 cursor。
+
+## 示例
+
+```bash
+lark-cli apps +list --keyword "审批"
+lark-cli apps +list --ownership mine --app-type full_stack
+lark-cli apps +list --page-token "<cursor>"
+```
+
+## 输出契约
+
+- 成功读取 `data.items[]`；保留字段为 `description`、`app_id`、`name`、`is_published`、`online_url`、`updated_at`，用于候选展示的核心字段是 `name`、`app_id`、`updated_at`。
+- `is_published=true` 只代表应用历史上有发布版本，不代表最新云端会话、最新代码提交或最新 HTML 产物已经部署。
+- `online_url` 是当前已有发布态入口；若你没有在本轮确认发布完成，不要把它描述成“最新版本链接”。
+- 默认输出已裁掉 `icon_url`（图片 URL，agent 无法渲染）和 `created_at`（与 `updated_at` 冗余）；需要时可用 `--jq` 过滤上述保留字段。
+- `data.items` 可能为空；不要把空列表当失败。
+- 若有 `has_more=true`，用返回的 `page_token` / `next_page_token` 继续翻页。
+
+## Agent 规则
+
+多候选时展示名称、app_id、updated_at 让用户确认。用户描述里已经有 `app_xxx` 或妙搭链接时，直接提取，不再 `+list`。
+
+把 `+list` 当定位工具和发布态快照工具，不要把 `is_published` 当部署完成证明。需要证明“最新内容已上线”时，使用对应发布命令的完成状态：全栈看 `+release-get` 的 `finished`，HTML 看 `+html-publish` 的成功返回。

package/skills/lark-apps/references/lark-apps-local-dev.md

@@ -0,0 +1,78 @@
+# lark-apps 本地全栈开发
+
+适用：用户要把妙搭全栈应用源码拉到本地，用本地 code agent/IDE 开发、调试数据库，再发布。
+
+## 新建 vs 已有应用
+
+新建还是修改已有，由上方入口（SKILL.md「选择开发路径」）判定；进到本地流程后按分支走：
+
+- **新建**：从 `+create` 开始走下面的端到端流程。
+- **已有应用**（本地还没有源码）：跳过 `+create`，先按下方「存量应用入口」拿 `app_id`，再 `+init`（或 `+git-credential-init` + `git clone`）把它拉到本地，然后照常开发。
+
+## 端到端流程（新建应用）
+
+`+create(full_stack)` -> `+init`（或手动 `+git-credential-init` + `git clone`）-> 读仓库 Skill -> `npm install && npm run dev` -> 按需 `+db-*` 调库 -> `git add` + `git commit`（提交本次改动）-> `git push origin sprint/default` -> `+release-create` -> `+release-get`。
+
+```bash
+# 新建 full_stack 应用
+lark-cli apps +create --name "审批系统" --app-type full_stack \
+  --description "支持登录、提交申请、多级审批、状态查询"
+
+# 初始化本地仓库（--dir 取值见下方「领域规则」，勿照抄此处示例值）
+lark-cli apps +init --app-id app_xxx --dir ./approval-app
+
+# 进入仓库后按项目脚手架启动
+cd ./approval-app
+npm install
+npm run dev
+
+# 开发完成后：提交本次改动 -> git push origin sprint/default -> +release-create。
+# +release-create 部署的是远端 sprint/default 上已 push 的代码，不是本地工作区——没 commit + push 的改动不会进入发布。
+git add <本次开发的文件>          # 提交粒度见下方「改完代码后部署上线」
+git commit -m "feat: ..."
+git push origin sprint/default
+lark-cli apps +release-create --app-id app_xxx
+```
+
+`+init` 是推荐便捷入口；想逐步手动控制时，先 `+git-credential-init` 拿 `repository_url`，再用原生 `git clone` / `git checkout sprint/default`。
+
+**`+init` 完成后必须执行**：`cat <project-path>/.agents/skills/plugin-guide/SKILL.md`，读取仓库插件指引。该文件包含插件目录、实例配置规则和调用代码生成方式——不读就无法正确集成插件能力。文件不存在则跳过。
+
+## 改完代码后部署上线
+
+已拉到本地、改完代码，用户说"推上去""部署""上线""发布到云端"时，按此序列。
+
+> `+release-create` 部署的是远端 `sprint/default` 上**已 push** 的代码，不是你本地工作区——未 commit / 未 push 的改动不会进入这次发布。所以发布前务必先把本次改动提交并推送。
+
+1. `git status` 看本次改动；`git add <本次相关文件>` 暂存后 `git commit` 提交。只提交本次任务相关的改动即可，无关的零散文件不必强求清空——发布门禁是「**本次相关改动已提交并推送**」，不是「工作区绝对干净」。
+2. `git push origin sprint/default` 把工作分支推到云端（遇非 fast-forward：先 `git pull --rebase origin sprint/default` 解决冲突再推，绝不 force-push）。
+3. `lark-cli apps +release-create --app-id <app_id>` 发起部署上线，记下返回的 `release_id`。
+4. `lark-cli apps +release-get --app-id <app_id> --release-id <release_id>` 轮询：`publishing` 继续轮询；`finished` 成功时该命令输出已含 `online_url`，直接读取它返回给用户（这是本轮发布完成后的可分享链接），无需再调 `+list`；`failed` 时该命令输出已含 `error_logs`，直接据此给出失败原因（`+list` 仅作独立查询入口）。
+
+## 领域规则
+
+- 代码读写走原生 `git`；CLI 负责凭证、初始化、发布和数据库调试。不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
+- `+init` 会编排 `+git-credential-init`、`git clone`、切到 `sprint/default`、运行脚手架，并在有变更时提交/推送。
+- `+init --dir` 选目录：用户已预授权或表达"不要询问"（见 SKILL.md「预授权判定」）→ 按应用名派生 `./<app-name>` 直接传 `--dir`、不停问；否则先问用户用哪个目录再传。目标已存在/非空时回问换目录。
+- `sprint/default` 是工作分支；`main` 是发布态快照，由 `+release-create` 成功后服务端 fast-forward 推进；服务端护栏禁直推 `main`、拒 force-push、要求 `sprint/default` fast-forward。
+- 已拉到本地后，pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
+- 环境变量由脚手架在本地启动时处理；需要手动刷新时用 `+env-pull`。
+- DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`；不要裸连数据库或自行拼连接串。
+- DB 分 `dev` / `online`；日常调试优先 `--env dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
+- 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --env dev`。这是不可逆 high-risk 操作。
+- 只从 `+list` 看到 `is_published=true`，不能证明本地刚推送的代码已经部署；必须有本轮 `+release-get finished`。
+
+## 存量应用入口
+
+已有项目目录先读 `.spark/meta.json` 取 `app_id`；没有本地项目但知道应用名时用：
+
+```bash
+lark-cli apps +list --keyword "应用名"
+```
+
+拿到 `app_id` 后再 `+init` 或 `+git-credential-init`。
+
+## 何时不用
+
+- 用户只想发布现成 HTML / 静态目录拿分享链接：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+- 用户明确要云端妙搭 Agent 生成/迭代，而不是本地写代码：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。

package/skills/lark-apps/references/lark-apps-observability.md

@@ -0,0 +1,48 @@
+# apps observability
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+
+查询妙搭应用的线上运行观测和产品访问分析。所有 observability 命令只支持 `--environment online`；省略 `--environment` 时默认就是 online，传 dev 或其他环境是不支持的。不要使用旧的 `--env`，也不要使用短选项。
+
+日志和 trace 的用户侧环境仍然是 online；但 OpenAPI 请求体里的后端 `app_env` 固定发送 `runtime`，因为线上应用的运行时日志和 trace 存储在 runtime 观测环境下。dry-run 输出会展示这个后端参数。
+
+metric / analytics 的 `--environment` 只是 CLI 侧 online-only 校验：`+metric-list` 和 `+analytics-list` 不会向 OpenAPI body 发送 `env` 或 `app_env`。dry-run 里看不到环境字段是预期行为，不要补造参数。
+
+时间过滤支持相对时间（如 `30s`、`5m`、`0.5h`、`2h`、`3d`、`1w`）、本地日期 / 时间和 RFC3339。
+
+## 命令选择
+
+- 日志检索：用 `+log-list` 搜索日志，用 `+log-get` 按 log ID 取单条日志。
+- `+log-list` 不再支持 `--log-id`；已有 log ID 时直接用 `+log-get --log-id <log_id>`。
+- 前端 ERROR 日志详情：`+log-get` 可能补充 `source_stack`；没有独立的 source-stack 命令。
+- Trace 检索：用 `+trace-list` 搜索 trace，用 `+trace-get` 按 trace ID 取详情。
+- 运行时指标：请求数、错误、延迟、CPU、memory 用 `+metric-list`。
+- 产品分析：PV、UV、访问量这类业务访问分析用 `+analytics-list`，不要放到 runtime metric 里混查。
+- `+analytics-list` 按最新 OpenAPI 发送 `metric_types`、纳秒时间戳和 `need_pack_lack_point=false`；`group_by` 暂不支持。
+- 用户询问“最近一小时接口请求量、错误量、延迟、接口慢/报错多”时，这是平台运行时监控，不是本地项目文件。先用 `apps +list --keyword` 找 `app_id`，再查 `+metric-list`。
+
+## 示例
+
+```bash
+lark-cli apps +log-list --app-id <app_id> --level error --keyword timeout --since 0.5h
+lark-cli apps +log-get --app-id <app_id> --log-id <log_id>
+lark-cli apps +trace-list --app-id <app_id> --trace-id <trace_id>
+lark-cli apps +trace-get --app-id <app_id> --trace-id <trace_id>
+lark-cli apps +metric-list --app-id <app_id> --metric requests --series total --since 1d
+lark-cli apps +metric-list --app-id <app_id> --metric requests --since 1h
+lark-cli apps +metric-list --app-id <app_id> --metric latency --since 1h
+lark-cli apps +metric-list --app-id <app_id> --metric latency --series p99 --since 1d
+lark-cli apps +metric-list --app-id <app_id> --metric cpu --since 1h
+lark-cli apps +metric-list --app-id <app_id> --metric memory --since 1h
+lark-cli apps +analytics-list --app-id <app_id> --analytics users --series active-users --granularity day
+lark-cli apps +analytics-list --app-id <app_id> --analytics page-view --granularity day
+```
+
+## 使用边界
+
+- 如果用户问“接口慢、报错多、CPU/内存高”，优先走 `+metric-list`。
+- `+metric-list --metric requests` 不传 `--series` 会同时返回请求总量 total 和错误量 error；`--metric latency` 不传 `--series` 会同时返回 p50 和 p99。只想看单条曲线时再传 `--series total|error|p50|p99`。
+- 按接口收窄范围时使用 `--api <path-or-name>`；当前没有 `group-by` 参数，不要臆造。
+- `+metric-list` 未显式传 `--down-sample` 时会按时间范围自动选择粒度：短范围用 `1m`，中等范围用 `1h`，长范围用 `1d`；显式传入时尊重用户指定。
+- 如果用户问“页面访问量、PV、UV、活跃用户”，优先走 `+analytics-list`。
+- 如果用户已有 `trace_id` 或 `log_id`，直接用对应 get 命令；不知道 ID 时先 list。

package/skills/lark-apps/references/lark-apps-openapi-key.md

@@ -0,0 +1,79 @@
+# apps openapi-key 命令族 SOP
+
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。全部操作需 `--as user`（AuthType: user）。`--help` 是参数细节的完整来源；本文件只记录 Agent 不看就会做错的领域规则。
+
+## 命令路由
+
+| 命令 | 用途 |
+|---|---|
+| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
+| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
+| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
+| `+openapi-key-update` | 改名或改 config（不改 status） |
+| `+openapi-key-enable` | 启用 Key（status→1） |
+| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
+| `+openapi-key-delete` | 永久删除 Key（不可逆） |
+| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见** |
+
+## 脱敏口径（安全关键）
+
+- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
+- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次；同时在 stderr 打印一次性提示：
+  ```
+  warning: this api_key is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.
+  ```
+- 原始密钥绝不写入 cache / config / recent / debug log / 错误信息。
+
+## 一次性密钥语义
+
+CLI 不保存原始密钥。密钥在 `create` / `reset` 时仅随响应返回一次。**密钥丢失不能用 `get` 找回**——唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
+
+## scope 结构与 CLI 表达
+
+后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：
+
+```json
+{
+  "allow_all": true,
+  "http_infos": [
+    { "http_method": "GET", "http_path": "/openapi/some-path" }
+  ]
+}
+```
+
+- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
+- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。
+
+CLI 提供三种互斥的 scope 表达方式：
+
+| flag | 用途 | 备注 |
+|---|---|---|
+| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
+| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
+| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |
+
+### scope 值来源
+
+妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。
+
+## 高风险操作
+
+`delete` 和 `reset` 是高风险（`high-risk-write`），有以下约束：
+
+- 需显式传 `--yes`（框架 `cmdutil.RequireConfirmation`）；缺少时退出码 10，**不要自动补 `--yes`**（遵循 lark-shared 安全红线）。
+- 支持 `--dry-run` 查看将要执行的 HTTP 请求（不含密钥）；不确定时先 dry-run。
+- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 enable 恢复，delete 不可逆。
+
+## 典型决策场景
+
+| 用户意图 | 正确操作 |
+|---|---|
+| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
+| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
+| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
+| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |
+
+## 不在本 skill 范围
+
+- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。
+- 身份选择、权限不足处理（`missing_scopes`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。

package/skills/lark-apps/references/lark-apps-plugin-install.md

@@ -0,0 +1,36 @@
+# apps +plugin-install
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+安装插件包到项目。运行时命令事实以 `lark-cli apps +plugin-install --help` 为准。
+
+## 何时用
+
+用户要接入 AI 能力或飞书平台能力，需要先安装对应的插件包。安装后才能创建插件实例。具体有哪些可用插件、该选哪个，读取创建的应用仓库 Skill：`.agents/skills/plugin-guide/SKILL.md`。
+
+**插件包 ≠ npm 包**：插件包写入 `actionPlugins`，npm 写入 `dependencies`，两套独立机制。禁止用 `npm install` 代替本命令。
+
+## 命令骨架
+
+- `--name <key>`：插件包 key（从仓库 Skill 的「AI 插件目录」获取）。不传则批量安装 `actionPlugins` 中声明的所有插件。
+- `--version <ver>`：指定版本（如 `1.0.0`）。不传则安装最新版。
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+# 安装最新版
+lark-cli apps +plugin-install --name <plugin-key>
+
+# 安装指定版本
+lark-cli apps +plugin-install --name <plugin-key> --version 1.0.0
+
+# 批量安装已声明的所有插件
+lark-cli apps +plugin-install
+```
+
+## 输出契约
+
+- 已安装同版本会跳过（status=already_installed）。
+- 失败时 hint 指示原因（网络/版本不存在/package.json 缺失）。

package/skills/lark-apps/references/lark-apps-plugin-list.md

@@ -0,0 +1,23 @@
+# apps +plugin-list
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+列出已声明的插件包及安装状态。运行时命令事实以 `lark-cli apps +plugin-list --help` 为准。
+
+## 何时用
+
+查看当前项目声明了哪些插件、是否已安装。`declared_not_installed` 状态表示需要运行 `+plugin-install` 安装。
+
+## 命令骨架
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+lark-cli apps +plugin-list --format json
+```
+
+## 输出契约
+
+- `data.plugins[]` 包含 `key`、`version`、`status`（`installed` / `declared_not_installed`）。

package/skills/lark-apps/references/lark-apps-plugin-uninstall.md

@@ -0,0 +1,25 @@
+# apps +plugin-uninstall
+
+> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。
+
+卸载插件包。运行时命令事实以 `lark-cli apps +plugin-uninstall --help` 为准。
+
+## 何时用
+
+用户不再需要某个插件能力时，卸载对应的插件包。卸载前应先删除该插件的所有实例。
+
+## 命令骨架
+
+- `--name <key>`：要卸载的插件包 key。
+
+在项目根目录下运行（和 npm 一样，无需指定路径）。
+
+## 示例
+
+```bash
+lark-cli apps +plugin-uninstall --name <plugin-key>
+```
+
+## 输出契约
+
+- 删除 `node_modules/{key}` + 移除 `actionPlugins` 条目。

package/skills/lark-apps/references/lark-apps-release-create.md

@@ -0,0 +1,32 @@
+# apps +release-create
+
+为妙搭应用创建发布 release。运行时命令事实以 `lark-cli apps +release-create --help` 为准。
+
+## 何时用
+
+用于把全栈应用的代码分支推进到发布流程。它不是 HTML 静态发布入口；本地 `index.html` / `dist` 要读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选：`--branch`；省略时服务端使用默认发布分支。
+- 返回 `release_id` 和 `status`，后续用 `+release-get` 轮询。
+
+## 示例
+
+```bash
+lark-cli apps +release-create --app-id app_xxx
+lark-cli apps +release-create --app-id app_xxx --branch sprint/default --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.release_id`、`data.status` 和 `data.sync`；`release_id` 是后续 `+release-get` 的入参。
+- `sync=true` 表示同步部署（服务端等待部署完成后才返回），`sync=false` 或缺失表示异步部署。
+- `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
+- `status=finished` 表示部署已完成（同步部署时可能直接返回此状态）。
+- `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。
+
+## Agent 规则
+
+`+release-create` 部署的是远端 `sprint/default` 上已 push 的代码，不是本地工作区——本地若有你修改但未推送的改动，需要先 `git add` + `git commit` 并 `git push` 到 `sprint/default`，否则这些改动不会进入这次发布。发布后若 status 是 `publishing`，用 [`+release-get`](lark-apps-release-get.md) 查询。`+release-create` 部署上线属高影响动作——作为别的命令的连带前置时，按 SKILL.md「高影响动作：确认与预授权」先征得用户同意再发布。

package/skills/lark-apps/references/lark-apps-release-get.md

@@ -0,0 +1,28 @@
+# apps +release-get
+
+按 release ID 查询单次发布详情。运行时命令事实以 `lark-cli apps +release-get --help` 为准。
+
+## 何时用
+
+用于跟进已知 `release_id` 的发布状态。没有 `release_id` 时先读 [`lark-apps-release-list.md`](lark-apps-release-list.md)，不要让用户手填。
+
+`release_id` 是妙搭发布 ID（`+release-create` 返回），不是飞书审批实例号；查发布进度/失败都在 `apps +release-*` 命令族内完成，不要路由到 lark-approval。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--release-id`。
+- `release_id` 来自 `+release-create` 或 `+release-list`。
+
+## 示例
+
+```bash
+lark-cli apps +release-get --app-id app_xxx --release-id release_yyy
+```
+
+## 输出契约
+
+- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
+- `status=publishing` 继续轮询。此时尚无 `online_url`；不要拿其它链接（如 `+list` 里的应用主页 / 开发态预览 URL）冒充"本轮发布的访问链接"——只回报 `release_id`、`status`，并说明 `finished` 后才有 `online_url`。
+- `status=finished` 发布成功——**本命令输出已含 `online_url`，直接读取它作为本轮发布的线上访问链接**返回用户，无需再调 `+list`（`+list` 仍可用于按应用名浏览，但不是发布主流程的必经步骤）。
+- `status=failed` 发布失败——**本命令输出已含 `error_logs`（`step`/`error_log`），直接据此向用户转述关键失败步骤和可行动修复**。
+- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"。单独从 `+list` 看到 `is_published=true` 不能证明最新版本已部署。

package/skills/lark-apps/references/lark-apps-release-list.md

@@ -0,0 +1,31 @@
+# apps +release-list
+
+分页查询妙搭应用发布历史，最新发布在前。运行时命令事实以 `lark-cli apps +release-list --help` 为准。
+
+## 何时用
+
+用户问"最近发布""历史版本""上次为什么失败"，但没有提供 `release_id` 时使用。拿到候选 release 后再接 `+release-get`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选 `--status`：`publishing` / `finished` / `failed`。
+- 可选 `--page-size`：默认 20，最大 500；总是发送给服务端。
+- 可选 `--page-token`：上一页 cursor。
+
+## 示例
+
+```bash
+lark-cli apps +release-list --app-id app_xxx --page-size 10
+lark-cli apps +release-list --app-id app_xxx --status failed
+```
+
+## 输出契约
+
+- 成功读取 `data.releases[]`；关键字段是 `release_id`、`status`、`created_at`、`updated_at`。
+- `release_id` 用于继续查 `+release-get`。
+- 若 `has_more=true`，用 `next_page_token` / `page_token` 翻页。
+
+## Agent 规则
+
+用户限定只看 N 条（"最近 N 条""最新 N 个""只要前 N 条"）时用 `--page-size N`（如"最近一次发布"→ `--page-size 1`），而不是取全量再本地截断。