@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-apps/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: lark-apps
+version: 1.0.0
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +<cmd> --help"
+---
+
+# apps (v1)
+
+妙搭应用属于用户资产。默认用 `--as user`；认证、scope、exit-10、高风险确认、`_notice` 等通用处理只读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不要在本 skill 里复制。妙搭应用有三条开发路径：**本地全栈**（拉源码本地写）/ **HTML 托管**（发布静态产物）/ **云端会话**（妙搭 AI 生成）。
+
+## 身份与授权
+
+妙搭应用是用户的个人资产，统一 `--as user`（见开头）。已有用户身份可用时直接执行业务命令，**不要为了预防权限问题主动重新登录**，否则可能中断原任务并触发不必要的设备授权。仅当 CLI 明确返回未登录或缺少本域 scope 时，一次性执行：
+
+```bash
+lark-cli auth login --domain apps
+```
+
+因缺权限失败（`error.subtype == "missing_scope"`）时的通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，同样按 `--domain apps` 授权；授权成功后只恢复原业务操作，不扩展任务范围。
+
+## 意图路由
+
+按具体操作查命令（开发路径先用下方「选择开发路径」判定表定好再进来取命令）：
+
+| 用户意图 | 先用 | 按需读取 |
+|---|---|---|
+| 创建**新**应用资产、拿 app_id | `+create` | [`lark-apps-create.md`](references/lark-apps-create.md) |
+| 找已有 app_id、按名字过滤应用 | `+list --keyword <name>` | [`lark-apps-list.md`](references/lark-apps-list.md) |
+| 查单个应用详情（类型、名称、发布状态等） | `+get --app-id <app_id>` | [`lark-apps-get.md`](references/lark-apps-get.md) |
+| 改应用名或描述 | `+update` | [`lark-apps-update.md`](references/lark-apps-update.md) |
+| 发布本地 `index.html` 或静态目录为可访问 URL | `+html-publish` | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
+| 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)；修改源码还须遵守下方「平台资源与应用源码边界」 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
+| 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
+| 管理应用环境变量（查看/设置/删除） | `+env-list`, `+env-set`, `+env-delete` | [`lark-apps-env.md`](references/lark-apps-env.md) |
+| 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`, `+log-get`, `+trace-list`, `+trace-get`, `+metric-list`, `+analytics-list` | [`lark-apps-observability.md`](references/lark-apps-observability.md) |
+| 看表 / 看结构 / 初始化多环境 / 导入导出数据 / 变更追溯 / 行级审计 / dev→online 发布 / 时间点恢复 / 查 DB 用量 | `+db-table-list`、`+db-table-get`、`+db-env-create`、`+db-data-export`/`+db-data-import`、`+db-changelog-list`、`+db-audit-status`/`+db-audit-enable`/`+db-audit-disable`/`+db-audit-list`、`+db-env-diff`/`+db-env-migrate`、`+db-recovery-diff`/`+db-recovery-apply`、`+db-quota-get` | [`lark-apps-db.md`](references/lark-apps-db.md) |
+| 逐条执行 SQL（SELECT / DML / DDL）；建表 / 改表 / 写 SQL 的平台规范 | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)（含「平台 SQL 规范」：审计列 / RLS / `user_profile` / 禁用 SQL / PG 陷阱） |
+| 管理应用文件存储：上传/下载本地文件、列出/查看/删除已存文件、生成临时分享链接、查存储用量 | `+file-upload`/`+file-download`/`+file-list`/`+file-get`/`+file-sign`/`+file-delete`/`+file-quota-get` | [`lark-apps-file.md`](references/lark-apps-file.md) |
+| **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）, `+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）, `+release-list` | [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
+| 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
+| 管理 `app_...` 应用内角色、角色成员，或查询用户匹配角色 | `+role-list/get/create/update/delete`, `+role-member-list/add/remove`, `+role-match-list` | [`lark-apps-role.md`](references/lark-apps-role.md) |
+| 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
+| 管理妙搭应用开放 API Key（创建/查看/启停/重置/删除凭证；密钥仅 create/reset 一次性返回） | `+openapi-key-list/get/create/update/enable/disable/delete/reset` | [`lark-apps-openapi-key.md`](references/lark-apps-openapi-key.md) |
+| 管理妙搭应用自动化触发器（定时/记录变更/Webhook/飞书审批四类触发器的查询/创建/更新/启停；Webhook URL·Token 一次性回显、不落盘） | `+automation-list/get/create/update/enable/disable` | [`lark-apps-automation.md`](references/lark-apps-automation.md) |
+| 查看某次会话某一轮（turn）的回复消息（含仍在生成中的本轮）/ 导出上一轮模型回复（"这一轮回复了什么""上一轮的回复""导出某轮消息"） | 先 `+session-get`（取 `latest_turn.turn_id`）-> `+session-messages-list --turn-id <id>`（仅 user 身份；分页用 `--page-token`） | [`lark-apps-session-messages-list.md`](references/lark-apps-session-messages-list.md) |
+| 外部能力(AI模型能力和飞书平台能力)集成/插件/Plugin/Capability | `+plugin-install`, `+plugin-list`, `+plugin-uninstall` | [`lark-apps-plugin-install.md`](references/lark-apps-plugin-install.md), [`lark-apps-plugin-uninstall.md`](references/lark-apps-plugin-uninstall.md), [`lark-apps-plugin-list.md`](references/lark-apps-plugin-list.md) |
+
+## 高频路径
+
+- **性能/监控/观测指标**：用户问“接口请求量、错误量、错误率、接口慢、延迟、CPU、内存、最近一小时/七天趋势”时，不要去当前工作区搜索监控文件，也不要询问“监控数据在哪”。先按「app_id 获取」解析应用：`lark-cli apps +list --keyword "<应用名>" --as user`；拿到 `app_id` 后读 [`lark-apps-observability.md`](references/lark-apps-observability.md)，用 `+metric-list`。
+- **请求量 + 错误量 + 延迟**：请求量/错误量用 `lark-cli apps +metric-list --app-id <app_id> --metric requests --since <range> --as user`（不传 `--series` 会同时返回 total/error）；延迟用 `--metric latency`（不传 `--series` 会返回 p50/p99）。如果用户给了具体接口，再加 `--api <path-or-name>`；不要臆造 group-by 参数。
+- **PV/UV/访问量/活跃用户**：先解析 `app_id`，再用 `+analytics-list`，不要误用 `+metric-list`。
+- **设置环境变量**：如果用户只给应用名，仍先 `+list --keyword` 解析 app_id；设置 online 环境且用户已经明确说“确认/直接执行”时，调用 `+env-set --environment online ... --yes`，不要再次要求确认。回复和日志摘要里只提 key / env / app，不回显真实 value；需要传复杂值时优先用 `@file` 或 stdin。
+- **删除环境变量**：`+env-delete` 是破坏性操作。除非用户在同一轮已经明确确认删除这个 app/env/key，否则先向用户确认应用、环境、key 和删除后果；确认后再加 `--yes`。不要因为认证失败/重登完成就自动继续删除，必须保留确认门槛。
+
+## 选择开发路径（进意图路由前先判这步）
+
+新建必先定 **app_type** 和**开发方式**两件正交的事；修改已有先按「app_id 获取」指认到 app，指认不到就问用户，不擅自 `+create`。开发方式（本地 vs 云端）只看用户对"谁来写代码"的偏好，与应用复杂度、要不要数据库无关。
+
+| 信号 | 判定 |
+|---|---|
+| 静态展示 / 单页 / PPT/demo / 无后端状态 | `app_type=html`，跳过本地/云端轴，开发完按 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)（含"未提部署→先问是否发布"） |
+| 登录 / 数据库 / 持久化 / 多人协作 / 增删改查 / 报名 / 投票 / 站会 / OKR / 泛称"系统·工具" | `app_type=full_stack` |
+| 用户要自己写 / 本地 IDE·code agent / 拉源码到本地 / 交研发 | 本地全栈，读 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) |
+| 让妙搭 AI 云端生成 / 对话式 / 自己不碰代码 | 云端会话，读 [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
+| 未表达"谁来写"偏好 | **必须先问**（本地代码开发 vs 云端 AI 生成）；选定前不擅自选边、不暗示默认，不得以"需求不模糊"为由跳过提问直接 `+init` / `git clone` / `+session-create` / 首轮 `+chat` |
+| 修改已有 + 当前目录是 `.spark/meta.json` 项目 | 直接继续本地按意图路由，不必问也不必判云端 |
+| 修改已有 + 有云端偏好 | 云端会话；未表达偏好且非本地项目 → 默认本地；判不准先问 |
+
+## 发布态护栏
+
+- **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。
+- 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。
+- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`：进应用编辑/开发态、管理与继续开发应用的入口。发布成功后，连同发布态链接一并提供给用户（说明"管理 / 继续开发去这里"）；但它仅进编辑态，**不能**顶替发布态链接当分享链接。
+- 发布态链接来源：html → `+html-publish` 的 `data.url`；全栈 → `+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`。
+- **可见范围**：发布态链接（html 的 `data.url`、全栈的 `online_url`）默认仅**创建者可见**，发给他人对方会无权限打不开。当可分享链接交付给用户前，先告知当前仅本人可见，再询问是否用 `+access-scope-set`（`tenant`/`public`/`specific`）放开（可先 `+access-scope-get` 查当前范围）。
+
+## 平台资源与应用源码边界
+
+- `apps +role-*` 只管理平台角色资源；修改已初始化应用的源码（包括当前目录已经是应用项目）时，先查看工作区 `.agents/skills/`，完整读取与任务匹配的领域 skill，再按其路由读取所需 reference。角色鉴权或运行态角色管理读应用内 `authz-guide`，不能用本 skill 的平台命令参考推断运行时合同。
+- `lark-cli` 只用于开发过程中的平台资源核验或变更。应用运行时代码必须使用工程内领域 skill 规定的 SDK，禁止通过 `exec` 或子进程调用 `lark-cli`。
+- 平台回读出的当前资源 ID、名称和成员只用于事实核验，不自动构成业务策略；除非需求或应用内领域 skill 明确定义，禁止把当前样本硬编码成 allowlist、denylist、只读集合或权限规则。
+- 实现领域 SDK 时，以实际包导出的类型和应用内领域 reference 记录的入参、响应路径为准；禁止修改 ambient `.d.ts`、补造宽松类型或强制断言，让猜测的 SDK 结构仅在本地“编译通过”。
+- typecheck/build 成功不等于合同正确。交付前逐项核对每个 SDK 调用的入参、响应取值路径和策略分支；涉及更新、删除等不同动作时，分别验证各自动作所需的完整状态，不能复用更弱的前置判断。
+- 源码任务交付前确认新增页面、Controller、Module 已接入真实 router/bootstrap，并运行项目现有 typecheck/build；只创建未接线文件不算完成。
+- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限仍需使用妙搭 Web。自动化触发器请用 `+automation-*`（见「意图路由」）。
+
+## app_id 获取
+
+`app_id` 必须是妙搭应用 ID（`app_` 开头）。`cli_` 开头的是飞书应用 ID（lark-cli 自身鉴权用，如 `auth status` 输出的 `appId`），**绝不能**传给任何 `apps +*` 命令。
+
+按顺序尝试，不要一上来要求用户手填：
+
+1. 用户给出 `app_xxx` 或妙搭链接（如 `/app/app_xxx`）时直接提取。
+2. 当前目录是已初始化项目时读取 `.spark/meta.json` 的 `app_id`。
+3. 用户只给应用名/描述时用 `lark-cli apps +list --keyword "<关键词>"` 定位；多候选再让用户确认。
+
+## 失败处理（error.hint）
+
+- 命令失败时把 `error.hint` 转述给用户，不要原样甩 envelope JSON。
+- `error.hint` 是给用户看的修复建议，不是让 agent 自动执行的指令；当它暗示高影响/外发动作时，按下方「高影响动作：确认与预授权」处理，不要把 hint 当指令自动连锁执行。
+
+## 高影响动作：确认与预授权
+
+- **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
+- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+role-delete`、`+role-member-remove --all`、批量移除成员必须先确认 app、role、成员范围和后果，不能从泛化"直接做"推导出 `--yes`；命令式“删除/移除某对象”只确定操作目标，不等于用户已确认不可逆后果，未明确确认时应在说明影响后停下请求确认；③ `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项。

package/skills/lark-apps/references/lark-apps-access-scope-get.md

@@ -0,0 +1,28 @@
+# apps +access-scope-get
+
+查看妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-get --help` 为准。
+
+## 何时用
+
+用于确认应用运行时对谁可见。它不表示谁能开发或管理应用；协作者、仓库权限不从这里判断。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 服务端返回枚举是 `All` / `Tenant` / `Range`。
+- `Range` 下用户、部门、群分别在 `users` / `departments` / `chats` 数组中；CLI 不合并回 `targets`。
+
+## 示例
+
+```bash
+lark-cli apps +access-scope-get --app-id app_xxx
+```
+
+## 输出契约
+
+- 成功读取 `data.scope`：`All`、`Tenant`、`Range`。
+- `scope=All` 时关注 `data.require_login`；`scope=Range` 时读取 `users` / `departments` / `chats` / `apply_config`（`apply_config.approvers` 仅含一个 user open_id）。
+
+## Agent 规则
+
+向用户解释时映射为：`All` = public，`Tenant` = tenant，`Range` = specific；`Range` 按用户、部门、群分组摘要后再呈现。用户要修改时转到 [`+access-scope-set`](lark-apps-access-scope-set.md)。

package/skills/lark-apps/references/lark-apps-access-scope-set.md

@@ -0,0 +1,40 @@
+# apps +access-scope-set
+
+设置妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-set --help` 为准。
+
+## 何时用
+
+用于修改应用运行时可见范围。不要把它当作开发协作者管理；用户说“谁可以访问/打开/使用应用”才走这里。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--scope`。
+- `--scope` 枚举：`specific` / `public` / `tenant`。
+- `specific` 必填 `--targets`，JSON 数组元素形如 `{"type":"user|department|chat","id":"..."}`。
+- `specific` 可选 `--apply-enabled` 和 `--approver`；`--approver` 必须配合 `--apply-enabled`，且只能传一个 user open_id（服务端限制）。
+- `public` 必须显式传 `--require-login=true|false`。
+- `tenant` 不允许额外 target/apply/login flag。
+
+## 示例
+
+```bash
+lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
+
+lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=true
+
+lark-cli apps +access-scope-set --app-id app_xxx --scope specific \
+  --targets '[{"type":"user","id":"ou_xxx"},{"type":"chat","id":"oc_xxx"}]'
+```
+
+## 输出契约
+
+- 成功时 `data` 可能为空；根据已执行的 `--scope` 和 targets 给用户总结结果。
+- 互斥参数错误会在本地 validation 阶段失败，不会发请求。
+
+## Agent 规则
+
+这是运行时访问范围，不是开发协作者权限。收窄可见范围前向用户说明影响，并在执行前确认目标用户、部门或群。
+
+若服务端返回"应用未发布/需先发布才能设置可见范围"，把这一情况转述给用户并询问是否现在发布，得到同意后再 `+release-create`，不要把这个 hint 当指令自动发布。
+
+用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od-` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od-` / `oc_`。

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

@@ -0,0 +1,164 @@
+# apps automation 触发器命令族 SOP
+
+管理妙搭应用的自动化触发器（定时 / 记录变更 / Webhook / 飞书审批四类）。全部操作需 `--as user`（AuthType: user）。`--help` 是参数细节的完整来源；本文件只记录 Agent 不看就会做错的领域规则。
+
+## 何时用本 skill（路由锚点）
+
+**当用户消息里出现「妙搭应用名 / app_id」+ 以下任一意图，路由本 skill，不要走 lark-event 或 lark-openapi-explorer：**
+
+- 「（每天 / 定时 / 每 N 小时 / 每周 X）自动跑 / 自动触发 / 定时同步」→ `+automation-create --trigger-type cron`
+- 「数据表 / 记录 / 表里 X 字段（新增 / 更新 / 删除 / 变化）时（触发 / 通知 / 处理）」→ `+automation-create --trigger-type record-change`
+- 「（webhook / 外部回调 / 外部系统调用 / HTTP 触发）」→ `+automation-create --trigger-type webhook`
+- 「（审批 / 报销 / 请假 / 出差）（通过 / 拒绝 / 提交 / 撤回）后自动 X」→ `+automation-create --trigger-type feishu-approval`
+- 「这个应用配了哪些（自动化 / 触发器 / 定时任务）」→ `+automation-list`
+- 「（暂停 / 停用 / 先别自动跑 / 关掉自动触发）某个（触发器 / 定时任务 / 自动化）」→ `+automation-disable`（不是 update 改条件、不是 delete——本 skill 不提供删除）
+- 「换 / 重置 webhook 回调地址 / URL」→ `+automation-update --reset-url --app-env <preview|runtime>`
+- 「换 / 重置 / 轮换 webhook token / bearer」→ `+automation-update --reset-token`
+
+**边界（防误路由）**：`lark-event` 是**实时事件流消费**（agent 长连接订阅事件），不管妙搭应用触发器的**配置**；用户说「配 / 设置一个触发器」而不是「订阅事件流」时，本 skill 才是正确选择。「审批通过触发」在妙搭应用语境下属于本 skill 的 `feishu-approval` 类型，不是 lark-event。
+
+### 回应「怎么配」类问题的正确姿势
+
+用户问「怎么配 / 怎么设置一个 X 触发器」时，**先展示完整命令模板 + 你对核心参数的推断**（让用户能确认你理解对了），再追问缺失的必填项（`--name` 之类）或可选项。**不要跳过展示、直接连环追问**，那样用户没法确认你有没有理解意图。
+
+示范：用户说「报销审批一旦通过就自动触发处理，怎么配？」
+- ✅ 正确：先写出「这是 feishu-approval 类型，命令模板：`apps +automation-create --app-id <id> --name <name> --trigger-type feishu-approval --event-type approval_instance --instance-status APPROVED [--approval-code <code>]`。需要你确认：(1) 触发器名 `<name>`；(2) 是否限定特定审批流程——限定就传 `--approval-code`（从飞书审批管理后台拿），不传则匹配所有审批定义」。
+- ❌ 错误：直接问「叫什么名字？监听哪个审批？」——用户没法确认你有没有把「审批通过」映射到 `--event-type approval_instance --instance-status APPROVED`。
+
+同理，cron/record-change/webhook 三类的「怎么配」都遵循此模式：先给命令 + 参数推断，后追问缺项。
+
+## 命令路由
+
+| 命令 | 用途 | Risk |
+|---|---|---|
+| `+automation-list` | 列出应用所有触发器（可按类型过滤、`--all` 聚合翻页） | read |
+| `+automation-get` | 查看单个触发器完整配置（Webhook Bearer Token 恒脱敏） | read |
+| `+automation-create` | 创建触发器，四类共用一条命令，按 `--trigger-type` 分派 | write |
+| `+automation-update` | 改条件/描述，或经专用 flag 管理 Webhook URL·Token | high-risk-write |
+| `+automation-enable` | 启用触发器（`status→enabled`，开始自动触发） | write |
+| `+automation-disable` | 停用触发器（`status→disabled`，停止触发，不删除） | write |
+
+触发器以 **应用内唯一的 `--name`** 定位（不是 id）。所有单条命令都用 `--app-id` + `--name`；名字忘了先 `+automation-list` 查。
+
+## 四类触发器 payload
+
+`--trigger-type` 用面向 Agent 的 kebab-case（`cron` / `record-change` / `webhook` / `feishu-approval`），CLI 内部转 snake_case 下推。类型专属 flag 只在对应类型生效。
+
+### cron（定时）
+
+```bash
++automation-create --app-id <id> --name daily --trigger-type cron \
+  --cron '0 9 * * *' [--timezone Asia/Shanghai]
+```
+
+- `--cron` 是**五段式**（`minute hour day month weekday`），非六段。
+- **最小间隔 30 分钟**：`--cron '* * * * *'`（每分钟）或 `*/n`（n<30）会被 CLI 本地拦截报错；后端也会二次校验。
+- `--timezone` 缺省补 `Asia/Shanghai`（IANA 时区名）。
+
+### record-change（记录变更）
+
+```bash
++automation-create --app-id <id> --name onUpd --trigger-type record-change \
+  --table <table_name> --event UPDATE [--fields '["status"]']
+```
+
+- `--event` 是**大写枚举**：`INSERT` / `UPDATE` / `UPSERT` / `DELETE`（CLI 会 uppercase，但请按枚举传）。
+- `--table` 是应用数据库里的**表名**（对应 `+db-table-list` / `+db-table-get` 输出里 `.name` 字段的值），必填。妙搭应用的 dataloom 表以名称作为稳定标识符，没有独立的 `table_id`。
+- `--fields` 是 JSON 字符串数组，仅对 `UPDATE`/`UPSERT` 有意义；`'["*"]'` 表示监听所有字段；不传表示不限定字段。
+
+### webhook（外部回调）
+
+```bash
++automation-create --app-id <id> --name hook --trigger-type webhook \
+  [--white-ip-list '["1.1.1.1","2.2.2.2"]']
+```
+
+- 创建时可选 `--white-ip-list`（JSON 字符串数组）限制回调来源 IP。
+- 回调 URL 分 **preview / runtime 两套**，创建时不回显；用 `+automation-get` 查当前配置，用 `+automation-update --reset-url --app-env <preview|runtime>` 轮换。
+- Bearer Token 是回调鉴权凭证，见下方「凭证脱敏与一次性回显」。
+
+### feishu-approval（飞书审批）
+
+```bash
++automation-create --app-id <id> --name apv --trigger-type feishu-approval \
+  --event-type approval_instance --instance-status APPROVED [--approval-code <code>]
+```
+
+- `--event-type` 必填，取 `approval_instance` 或 `approval_task`，决定状态用哪套 flag：
+  - `approval_instance` → `--instance-status`（可重复）
+  - `approval_task` → `--task-status`（可重复）
+- **领域规则**：状态按 `event-type` 分桶校验，两桶枚举**不完全相同**（`PENDING`/`APPROVED`/`REJECTED`/`REVERTED`/`OVERTIME_CLOSE`/`OVERTIME_RECOVER` 两桶共享；`TRANSFERRED`/`ROLLBACK`/`DONE` 仅 task 有；`CANCELED`/`DELETED` 仅 instance 有）；传错桶的状态会被 CLI 本地拦截，错误信息会打印该桶的合法值列表。具体枚举见命令 `--help`。
+
+## approval-code 获取路径
+
+`--approval-code` **可选**。不传时匹配所有审批定义；要限定某个审批流程时，从**飞书审批管理后台**获取具体的 code 传给它。触发器 OpenAPI 不提供审批定义查询能力，具体 code 需去审批管理后台查。
+
+## 凭证脱敏与一次性回显（安全关键）
+
+- `+automation-get` / `+automation-list`：**恒不返回明文 Bearer Token**——`trigger_condition.token_value` 被抹为 `null`。用户想知道「token 是什么」时，list/get 都查不到明文。
+- `+automation-update --enable-token` / `--reset-token`：明文 Bearer Token **仅当次 stdout 回显一次**，同时 stderr 打印一次性告警：
+  ```text
+  warning: this bearer token is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.
+  ```
+- Webhook URL 同理：`--reset-url` 后新 URL 仅当次回显一次，旧 URL 立即失效。
+- CLI 不落盘任何明文 token/URL（不写 cache / config / recent / debug log / 错误信息）。
+- **Token 丢失只能 reset**：找不回，唯一恢复方式是 `+automation-update --reset-token`（旧 token 同时失效）。
+
+## 高危确认
+
+`+automation-update` 整体是 `high-risk-write`，任何一次调用都需显式 `--yes`；缺少时框架会要求确认（退出码 10）。**不要自动补 `--yes`**——需用户明确确认后再加。以下 Webhook 动作 flag 尤其不可逆：
+
+- `--reset-url`（旧回调 URL 立即失效，需配 `--app-env preview|runtime`）
+- `--reset-token`（旧 token 立即失效）
+- `--disable-token`（关闭 token 校验，**不可逆**）
+
+四个 Webhook 动作 flag（`--reset-url` / `--enable-token` / `--disable-token` / `--reset-token`）**每次只能传一个**。不确定影响时先跑 `--dry-run` 看将发出的请求（不含明文）。
+
+### 执行前必须完成的确认步骤（高危写强制协议）
+
+**在带 `--yes` 执行任何高危写之前，Agent 必须先完成以下 3 件事**，缺一不可——即使用户口气很急、即使命令一眼就明：
+
+1. **确认目标唯一**：不允许"猜名字"或"批量试所有可能的名字"。若不确定 `--name`，先 `+automation-list --app-id <id>` 让用户在候选中点名；`--name` 不明的绝不执行写操作，更不要 for 循环批量试。
+2. **确认可选参数已定**：`--reset-url` 必须由用户明确指定 `--app-env preview` 还是 `runtime`；不要默认取 runtime 或 preview。同一触发器的 preview/runtime 是两条独立的 URL，误重置另一条不可回退。
+3. **告知不可逆后果并等确认**：把即将发生的 3 件事复述给用户——（a）旧 URL/Token 立即永久失效；（b）新 URL/Token 仅当次回显一次、CLI 不保存；（c）本次操作无法撤销——等用户回复"确认"再加 `--yes` 跑。
+
+只要有一项没做，就先跟用户对齐、不要执行。这些是 skill 层的护栏，不是 CLI 层的（CLI 只强制 `--yes`，不强制上面 3 件事）。
+
+## ⚠️ 安全告警：无鉴权公网回调组合态
+
+`--disable-token`（关闭 Bearer Token 校验，不可逆）**叠加** `--white-ip-list '[]'`（清空 IP 白名单）会让 Webhook 触发器进入「**无鉴权公网回调**」组合态——**任何来源都能触发该 Webhook**，没有任何一道防线拦截。
+
+- 两道防线：Token 校验（谁能调）+ IP 白名单（从哪能调）。**不要同时关闭这两道防线。**
+- 若确需关闭 Token（例如对端无法带 Bearer 头），务必**保留 IP 白名单**收敛来源；反之若要放开 IP，务必**保留 Token 校验**。
+- 用户同时要求「关 token 校验 + 清空 IP 白名单」时，Agent 的正确响应是**在识别到该请求的第一时间**（不要等命令跑失败才补警告）向用户输出以下 3 件事，再等确认——不要只描述"没有任何防线"就停下：
+  1. 复述后果：这会形成无鉴权公网回调，任何来源都能触发。
+  2. **主动给出替代方案**：明确建议"要么只关 Token 保留 IP 白名单，要么只放开 IP 保留 Token"，让用户在保留一道防线的两条备选里选一条。
+  3. 只有用户明确回复"我理解风险、就是要两道都关"时，才继续按高危写协议（见上节「执行前必须完成的确认步骤」）走。
+
+## 默认 disabled
+
+`+automation-create` 创建后触发器**默认 disabled**，不会自动触发。需 `+automation-enable` 才开始按条件自动运行（且触发器执行的是**线上已发布**的应用代码——应用未发布时即便 enable 也不会有实际效果）。
+
+**Agent 行为约束**：用户只说"创建/配一个触发器"时，**不要**主动在同一个 turn 里 `+automation-enable`。让用户自己在下一轮决定是否启用；主动启用会：
+- 让 webhook 类型立即可被外部调用（原本用户可能只是想"备好 URL 稍后用"）
+- 让 cron 到点真实触发（原本用户可能想"先建好观察配置"）
+- 让 record-change 立即响应表变更
+
+创建成功后的推荐话术：`已创建 <name>，当前 disabled；需要真正开始自动运行时告诉我，我用 +automation-enable 启用它。` **不要**在创建成功后立即启用，即使 skill 里说"需 enable 才自动触发"——这条是给用户的说明，不是给 agent 的行动指令。
+
+## 常见错误与决策场景
+
+| 现象 / 用户意图 | 正确处理 |
+|---|---|
+| 创建报名字冲突（`--name` 应用内唯一） | 换名或加后缀重试 |
+| cron 报非法 / 间隔过小 | 检查是否五段式、分钟字段是否 `*` 或 `*/n`(n<30) |
+| `--reset-url` 报缺 app-env | 补 `--app-env preview` 或 `--app-env runtime` |
+| 想把 cron 触发器改成 webhook（跨类型改） | update 不支持换类型，本 skill 也不提供删除。旧触发器只能 `+automation-disable` 停用（保留在应用里），另建一个 webhook 触发器；若要真正清理旧触发器，请到妙搭 web 手动删除 |
+| 触发器 enable 了但不触发 | 确认应用**已发布**；触发器跑的是线上已发布代码 |
+| 「token 泄露了」 | 优先 `+automation-update --reset-token --yes` 轮换（旧 token 立即失效），而非直接 disable-token 关校验 |
+| 「回调 URL 泄露了」 | `+automation-update --reset-url --app-env <env> --yes` 轮换 |
+
+## 不在本 skill 范围
+
+- 审批定义查询、Webhook 消费端实现、实时触发日志 tail：本期不支持。
+- 身份选择、权限不足处理、exit-10 审批、通用「禁输出密钥」红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。

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

@@ -0,0 +1,120 @@
+# lark-apps 云端会话开发
+
+适用：用户希望让云端妙搭 Agent 生成或迭代应用，而不是把代码拉到本地开发。
+
+## 核心流程
+
+整个开发在云端进行：本地只负责「发消息 + 轮询状态」，不拉源码、不产出代码、不启动本地 dev server。所有 session/chat 命令都以用户身份执行（`--as user`）。
+
+### 资源模型：app → session → turn
+
+三层父子关系，下层都挂在上层之下：
+
+- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。云端生成应用类型用 `full_stack`。
+- **session（会话）**：一个 app 下的一段独立对话上下文，由 `+session-create` 创建并拿到 `session_id`。一个 app 可有多个 session；`is_active` 表示该 session 当前是否可写（可发起对话）。
+- **turn（轮）**：一个 session 里的一轮交互 = 一条用户消息 + 妙搭 Agent 针对它的生成/迭代。`+chat` 发一条消息就发起一轮；轮的句柄是 `turn_id`，状态看 `latest_turn.status`。
+
+### 执行模型：异步 + 轮询
+
+`+chat` 把消息入队后**立即返回、不等生成完成，响应不带 `turn_id`**；本轮状态与轮询节奏全靠 `+session-get` 读 `latest_turn.status` / `is_streaming` / `next_poll_after_ms`。
+
+`+session-get` 关键字段：
+
+- `is_streaming`：当前是否有一轮正在跑（`true`=还在生成）。
+- `latest_turn.status`：最近一轮的状态，只有 `running` / `completed` / `failed` / `cancelled`。
+- `latest_turn.turn_id`：最近一轮的句柄（`+session-stop --turn-id` 用它）。
+- `latest_turn.user_message`：本轮用户发的消息。
+- `latest_turn.messages`：本轮完成后回看全貌的消息列表，按时序排列、每条带 `role`（用户消息、模型回复、工具调用等都在内，role 取值如 `user` / `assistant` / `tool`）。注意它在 `latest_turn` 仍 running/初始化期可能为空——该轮**进行中**的实时进展改用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读（见下方轮询规则）。
+- `queued_messages` / `queued_count`：还没开始跑、排在后面的消息。
+- `next_poll_after_ms`：建议的下次轮询间隔（毫秒，固定值）；非空时优先用它。
+
+轮询规则：
+
+- 节奏按 [初始化 vs 增量修改](#初始化-vs-增量修改) 判定：增量 5-10 秒一次；初始化 60-120 秒一次；`next_poll_after_ms` 非空时用它。
+- `is_streaming=true`、`building` / `running` / `streaming` 表示仍在生成，继续轮询，不傻等也不提前放弃；初始化阶段单次 sleep 拉到 60-120 秒，进入 `streaming` 或属增量修改时切回 5-10 秒。
+- `is_streaming=false` 且 `latest_turn.status=completed` 表示本轮完成，可发下一条。
+- `failed` / `cancelled` 时转述错误字段或 hint，由用户决定是否重试，不要静默重发。
+- 不知道某 app 有哪些 session 时，先 `+session-list --app-id <id>`，再选最近活跃的或让用户确认，别直接猜 `session_id`。
+- 要中止正在运行的一轮，从 `+session-get` 的 `latest_turn.turn_id` 取值，再调用 `+session-stop --turn-id <turn_id>`。
+- 状态与节奏看 `+session-get`，本轮实时内容看 `+session-messages-list`：想在 running 期间向用户播报"云端 Agent 此刻在做什么"，用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读已产出的增量消息（running 期间即可读，不必等本轮结束）。复用上面的轮询节奏、不另起更密的轮询；续拉时把上次响应的 `next_page_token` 作 `--page-token` 只取新消息，转述时简述进展、不原样打印整段消息或工具输出。
+
+### 典型链路
+
+```bash
+# 1) 建 app，拿 app_id（云端生成走 full_stack）
+lark-cli apps +create --name "待办应用" --app-type full_stack \
+  --description "支持新增、完成、筛选待办"
+
+# 2) 在该 app 下建 session，拿 session_id
+lark-cli apps +session-create --app-id app_xxx
+
+# 3) 发消息发起一轮（异步入队，立即返回，无 turn_id）
+lark-cli apps +chat --app-id app_xxx --session-id sess_xxx --message "做一个待办清单页面"
+
+# 4) 轮询本轮状态；完成后从 latest_turn.messages 读取结果
+lark-cli apps +session-get --app-id app_xxx --session-id sess_xxx
+
+# 找该 app 已有的会话（续聊/不确定 session 时用）
+lark-cli apps +session-list --app-id app_xxx
+```
+
+## 完成态不等于发布态
+
+通用发布态判定（is_published 语义、开发态链接拼接、发布态链接来源）见 SKILL.md「发布态护栏」。本 reference 只补云端会话特有的措辞：
+
+- `+session-get` 返回 `is_streaming=false` 且 `latest_turn.status=completed`，只说明本轮云端生成/迭代结束，不等于已发布部署。
+- 如果只完成了云端会话、没有确认发布完成，就明确告诉用户“开发态链接可进入继续编辑，发布态是否为最新版本尚未确认”。
+
+## 需求发送
+
+- 只有用户明确选择云端路径，或明确说“让妙搭 Agent / 云端 AI 生成/迭代”时，才进入本 reference；不要因为用户只说“做个 X”或“给我链接”就默认云端。
+- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先建 `full_stack` app，再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
+- 如果需求过泛，可在 `+chat --message` 中保留原话，并只补一句“请先生成通用版本，后续可继续迭代”，不要用多轮追问阻塞生成。
+
+## 会话落点
+
+| 情形 | 动作 |
+|---|---|
+| 全新应用 + 云端生成 | 先 `+create --app-type full_stack` 拿 `app_id`，再 `+session-create` -> `+chat` |
+| 已知 app_id，用户没指定会话 | 先 `+session-list`；有活跃会话时问用户继续现有还是新开 |
+| 用户说“新开一段/换个话题” | `+session-create` 后再 `+chat` |
+| 用户说“接着刚才” | 复用上下文 session_id；拿不到就 `+session-list` 让用户选 |
+| 用户问会话“进行到哪一步/当前状态/最新进展” | 用 `+session-get --session-id <sid>` 读状态。`+session-list` 只负责发现/选择会话，不含执行状态；它返回空不等于无状态可查（session_id 也可能来自上下文），别用 `+session-list`/`+release-list` 代替 `+session-get` 回答进度 |
+
+## 初始化 vs 增量修改
+
+`+chat` 单轮的耗时差距很大，取决于目标 app 是否**已初始化**。两者的轮询节奏不同，**`+chat` 前先把状态判定清楚**，不要拿"是不是第一次发消息"当代理判断——session 是新建的不代表 app 没初始化过。
+
+### 判定规则
+
+**已初始化**（满足任一即认为已初始化）：
+
+1. 本地存在该 app 的项目目录（已 `+init` 或 clone 过），**且** git commit 数 > 2；
+2. 应用维度（云端）至少有一个已提交的版本，按以下任一信号判断：
+   - `lark-cli apps +session-get --app-id <app_id> --session-id <session_id>` 的返回里出现已提交版本信息；
+   - 在 `lark-cli apps +list`（必要时配 `--keyword <name>` 定位）的目标 app 条目里 `is_published: true`。
+
+**未初始化**（两个条件同时成立）：
+
+1. 本地不存在该 app 的项目目录；
+2. 应用维度没有任何已提交版本（即上面两路云端信号都判 false）。
+
+### 两种 `+chat` 的行为
+
+| 状态 | 服务端动作 | 单轮耗时 | 轮询建议 |
+|---|---|---|---|
+| 已初始化 → **增量修改** | 云端 Agent 在已有云端工作区上对**已提交代码**做局部修改，跳过方案设计与首次生成 | 通常分钟级 | `next_poll_after_ms` 为空时 5-10 秒一次 |
+| 未初始化 → **首次初始化 + 生成** | 服务端跑完整的应用初始化流程：需求分析、技术方案、数据模型、UI 与后端代码生成、首版代码提交到云端工作区 | 视需求复杂度，**通常 20~50 分钟** | `next_poll_after_ms` 为空时 60-120 秒一次 |
+
+初始化阶段 `+session-get` 可能长时间持续返回 `building` / `running`，是正常状态，**不要按失败处理，也不要催用户**。
+
+## 字段注意
+
+所有字段统一 snake_case，顶层和嵌套 turn 字段都一样：`session_id`、`is_active`、`is_streaming`、`next_poll_after_ms`、`latest_turn.turn_id`、`latest_turn.status`、`latest_turn.user_message`、`latest_turn.messages`。
+
+`+session-stop` 只停止正在运行的当前轮，不关闭会话；停完仍可继续 `+chat`。
+
+## 不适用
+
+- 用户已有本地 HTML/dist，要马上发布 URL：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+- 用户要本地写代码、改仓库、跑 dev server：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。

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

@@ -0,0 +1,40 @@
+# apps +create
+
+创建妙搭应用。运行时命令事实以 `lark-cli apps +create --help` 为准。
+
+## 何时用
+
+用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先创建 `full_stack` app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。
+
+## 命令骨架
+
+- 必填：`--name`、`--app-type`。
+- app type 语义取值为 `html` / `full_stack`；CLI 会把输入归一成小写后校验。
+- 可选：`--description`、`--icon-url`。
+
+## 示例
+
+```bash
+lark-cli apps +create --name "客户调研问卷" --app-type html
+
+lark-cli apps +create --name "审批系统" --app-type full_stack \
+  --description "部门审批系统，支持登录、提交申请、多级审批"
+
+lark-cli apps +create --name "Demo" --app-type html --dry-run
+```
+
+## 输出契约
+
+- 成功默认 JSON envelope 中读取 `data.app.app_id`，同时可用 `data.app.name` / `description` 向用户确认结果。
+- pretty 输出只适合人看；后续命令需要 app_id 时，用 JSON 或 `--jq '.data.app.app_id'`。
+
+## app type 与命名
+
+- `--app-type` 取值与判定信号见 SKILL.md「选择开发路径」，此处不重复。
+- 用户只给自然语言需求时，据此生成简洁的 `--name` 和一句 `--description` 直接创建；不满意再用 `+update` 改。
+
+创建后按用户路径继续：
+
+- 发布现成 HTML/静态目录：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+- 本地全栈开发：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
+- 云端 Agent 生成/迭代：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。