@yandy0725/pi-lark 0.1.0

package/skills/lark-approval/references/lark-approval-instance-value-sourcing.md

@@ -0,0 +1,108 @@
+# 审批提单值来源
+
+## 目的
+
+本文用于回答一个固定问题：在调用 `approval instances create` 发起原生审批实例时，**每个要填写的值从哪里拿**。
+
+阅读顺序固定如下：
+
+1. `lark-cli schema approval.instances.create`
+2. `approval approvals get` 返回的 `form` / `node_list`
+3. [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md)
+4. 本文
+
+## 总原则
+
+- `schema` / `meta` 决定请求字段名、字段层级、节点参数结构。
+- `approvals.get.form` 决定控件 `id`、`type`、选项值范围、子控件结构。
+- `approvals.get.node_list` 决定节点 key、是否必须补审批人、是否允许多人。
+- [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 决定各控件 `value` 的最终结构。
+- 除非本文明确允许，否则不要猜值来源，不要把展示文案直接当成可提交值。
+
+## 默认来源
+
+- 审批定义、`approval_code`、`is_external`、`create_link` 等基础信息，默认从 `approval approvals search` 获取。
+- 控件 `id`、`type`、选项值、子控件结构，默认从 `approval approvals get.form` 获取。
+- 节点 key、`need_approver`、`approver_chosen_multi` 等节点信息，默认从 `approval approvals get.node_list` 获取。
+- 本文只补充 **这些默认来源之外** 的取值规则，以及当前必须由用户直接提供的值。
+
+## 控件值来源规则
+
+### 联系人 `contact`
+
+- 只推荐写 `open_ids`。
+- 不再推荐双写 `value(user_id)` + `open_ids`，避免复杂度继续上升。
+- 如果用户给的是姓名、邮箱或账号，先用 `lark-contact` 解析成 `open_id`。
+
+### 部门 `department`
+
+- 最优先：用户直接提供 `open_department_id`。
+- 若用户说“我的部门”或“张三的部门”，先用 `lark-contact` 查询对应人员信息，再取其所属部门里的 `open_department_id`。
+- 如果查到该人员只有一个部门，可直接使用。
+- 如果查到多个部门，不自动猜，必须让用户明确选一个，或直接输入 `open_department_id`。
+- 如果仍无法确定，则明确告知当前不支持自动决定部门值。
+
+### 附件 `attachmentV2`
+
+- 当前 `lark-approval` 不负责上传文件。
+- 用户必须直接提供 file code。
+- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
+
+### 图片 `image` / `imageV2`
+
+- 当前 `lark-approval` 不负责上传图片。
+- 用户必须直接提供 file code。
+- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
+
+### 文档 `document`
+
+- 用户可直接提供 `token` / `document_id`。
+- 如果用户给的是飞书文档链接，应先尝试从链接中提取 token。
+- 若链接提取失败，再要求用户手动输入 token。
+
+### 关联审批 `connect`
+
+- 用户直接提供目标审批实例的 `instance_code`。
+- 当前不默认做“搜索关联实例再反查 code”的自动流程。
+
+### 地址 `address`
+
+- 用户直接提供地理库 `id`。
+- 若用户无法提供该 `id`，当前不支持自动取值。
+
+## 特殊控件组
+
+以下控件组的结构仍按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 组装：
+
+- `leaveGroupV2`
+- `workGroup`
+- `outGroup`
+- `shiftGroup`
+
+补充规则：
+
+- 控件组自身和子控件的 `id` / `type` 从 `approval approvals get.form` 中识别。
+- 组内单选/多选或业务枚举值，优先从 `approval approvals get.form` 返回的选项结构中取。
+- 不要把控件组整体当成普通字符串或扁平对象提交。
+
+## 不支持自动准备的值
+
+以下值当前不建议由 `lark-approval` 自动准备：
+
+- 文件上传后的 file code
+- 图片上传后的 file code
+- 地址控件的地理库 `id`
+- 无法唯一确定的部门 `open_department_id`
+
+遇到这类值时，应明确告诉用户需要提供什么，而不是继续猜测。
+
+## 最小决策表
+
+| 场景 | 处理 |
+|---|---|
+| 用户说“找张三当审批人” | 用 `lark-contact` 解析张三，取 `open_id` |
+| 用户说“我的部门” | 先查当前用户部门；若多个部门，让用户选 |
+| 用户给了文档链接 | 先尝试提取 token |
+| 用户要填图片/附件 | 要求直接提供 file code |
+| 用户要填关联审批 | 要求直接提供 `instance_code` |
+| 用户要填地址 | 要求直接提供地理库 `id` |

package/skills/lark-apps/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: lark-apps
+version: 1.0.0
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、可见范围时使用。不负责普通云盘文件上传（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 生成）。
+
+## 意图路由
+
+按具体操作查命令（开发路径先用下方「选择开发路径」判定表定好再进来取命令）：
+
+| 用户意图 | 先用 | 按需读取 |
+|---|---|---|
+| 创建**新**应用资产、拿 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) |
+| 改应用名或描述 | `+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) |
+| 看表、看 schema、跑 SQL、初始化 dev/online 多环境 DB | `+db-table-list`, `+db-table-get`, `+db-execute`, `+db-env-create` | 对应 `lark-apps-db-*.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 |
+| 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.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) |
+
+## 选择开发路径（进意图路由前先判这步）
+
+新建必先定 **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` 查当前范围）。
+
+## 能力边界
+
+- lark-cli **不支持**配置应用的权限（应用内 RBAC、成员角色、协作者权限）/ 自动化 / 插件。`+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限。
+- 用户要配置权限 / 自动化 / 插件时，引导其使用开发态连接前往云端开发（妙搭 web）处理。
+
+## 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` 确认；② `+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-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)。

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

@@ -0,0 +1,31 @@
+# apps +db-env-create
+
+把存量单库应用初始化为 `dev` / `online` 多环境数据库。运行时命令事实以 `lark-cli apps +db-env-create --help` 为准。
+
+## 何时用
+
+仅用于存量单库应用需要拆成 `dev` / `online` 两套数据库的场景。普通查看表、查 schema、执行 SQL 不需要先初始化。注意：通过 `+create --app-type full_stack` 新建的应用通常已自带多环境，无需再初始化（重复初始化会返回「已初始化」错误）。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- `--env`：要创建的环境，由调用方传入，目前只支持 `dev`（默认 `dev`）。
+- `--sync-data`：bool 开关，传 `--sync-data` 则把现有 online 数据复制到新环境；不传则不复制（默认）。
+- risk 是 `high-risk-write`；单库拆成 dev/online 后不可逆。
+
+## 示例
+
+```bash
+lark-cli apps +db-env-create --app-id app_xxx --env dev --dry-run
+lark-cli apps +db-env-create --app-id app_xxx --env dev --sync-data --yes
+```
+
+## 输出契约
+
+- 成功读取 `data.status`、`data.environments`、`data.data_synced`；pretty 会提示是否初始化、多环境列表、是否同步数据。
+- 未确认时返回 `confirmation_required` / exit 10；按 lark-shared 询问用户后再补 `--yes` 重试。
+- 如果服务端提示已启用多环境（`Multi-env is already initialized`），转述状态即可，不要重复初始化。
+
+## Agent 规则
+
+不要静默追加 `--yes`。遇到 confirmation_required 时，按 `lark-shared` 的 exit-10 协议向用户确认不可逆风险；用户明确同意后才在原 argv 末尾追加 `--yes` 重试。

package/skills/lark-apps/references/lark-apps-db-execute.md

@@ -0,0 +1,40 @@
+# apps +db-execute
+
+经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。
+
+## 何时用
+
+用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。
+
+## 命令骨架
+
+- 必填：`--app-id`，以及 `--sql` / `--file` 二选一（互斥）。
+- `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
+- `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
+- `--env` 枚举：`dev` / `online`，**默认 `dev`**；需要操作线上环境数据库时，显式指定 `--env online`。
+- risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
+- CLI 永远传 `transactional=false`；不默认包事务。
+
+## 示例
+
+```bash
+lark-cli apps +db-execute --app-id app_xxx --env dev --sql "select * from orders limit 5" --yes
+lark-cli apps +db-execute --app-id app_xxx --env dev --file ./migration.sql --dry-run
+# 绝对路径文件 / cwd 不固定：经 stdin 传入
+lark-cli apps +db-execute --app-id app_xxx --env dev --sql - --yes < /Users/.../migrations/0001_init.sql
+```
+
+## 输出契约
+
+- 成功默认 JSON 读取 `data.results[]`；每个元素对应一条 SQL，常见字段有 `sql_type`、`data`、`record_count`、`affected_rows`。
+- pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
+- 失败可能仍有前序语句已执行；此时 stdout 输出 `ok:false` 的 envelope（exit 非 0），从 `data` 读 `results[]`（全部逐条结果，失败语句 `sql_type` 为 `ERROR`）、`statement_index`、`error_code`、`error_message`、`rolled_back` 和 `note`，决定从哪条继续。
+
+## Agent 规则
+
+- 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
+  - **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
+  - **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
+- 多语句失败时，失败前的语句可能已经 auto-commit。不要整批重跑；按错误 detail/hint 修失败语句，并从剩余语句继续。
+- 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
+- 不要把数据库连接串从 env 中取出来裸连。

package/skills/lark-apps/references/lark-apps-db-table-get.md

@@ -0,0 +1,29 @@
+# apps +db-table-get
+
+查看妙搭应用数据库某张表的结构。运行时命令事实以 `lark-cli apps +db-table-get --help` 为准。
+
+## 何时用
+
+用于查看已知表的字段、索引、约束，或给 SQL/迁移生成提供依据。只想知道有哪些表时先 `+db-table-list`。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--table`。
+- `--env` 枚举：`dev` / `online`，默认 `online`。
+- `--format pretty` 会向服务端请求 DDL，并直接输出 DDL 文本；默认 JSON 返回结构化 columns/indexes/constraints/stats。
+
+## 示例
+
+```bash
+lark-cli apps +db-table-get --app-id app_xxx --table orders
+lark-cli apps +db-table-get --app-id app_xxx --table orders --env dev --format pretty
+```
+
+## 输出契约
+
+- 默认 JSON 读取 `data.name`、`columns`、`indexes`、`constraints`、`estimated_row_count`、`size_bytes`。
+- `--format pretty` stdout 是服务端返回的 DDL 文本，不是 JSON envelope；需要建表语句时可原样给用户。
+
+## Agent 规则
+
+需要给用户看建表语句或迁移参照时用 `--format pretty`；需要程序化分析字段/索引/约束时保留默认 JSON。

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

@@ -0,0 +1,31 @@
+# apps +db-table-list
+
+列出妙搭应用某个数据库环境的数据表。运行时命令事实以 `lark-cli apps +db-table-list --help` 为准。
+
+## 何时用
+
+用于先摸清应用数据库里有哪些表，或在用户只给业务对象名时定位可能的表名。已知表名且要字段/索引时直接用 `+db-table-get`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- `--env` 枚举：`dev` / `online`，默认 `online`。
+- 分页：`--page-size` 默认 20，`--page-token` 使用上一页 cursor。
+- pretty 输出列包含 `name`、`description`、`estimated_row_count`、`size`、`columns`（列数）。
+
+## 示例
+
+```bash
+lark-cli apps +db-table-list --app-id app_xxx
+lark-cli apps +db-table-list --app-id app_xxx --env dev --page-size 50
+```
+
+## 输出契约
+
+- 成功读取 `data.items[]`；每项字段是 `name`、`description`、`estimated_row_count`、`size_bytes`、`column_count`（列数）。CLI 默认不透出每表完整 `columns[]`（与 `+db-table-get` 重复且放大 token），只给 `column_count`；要完整列定义/索引/约束用 `+db-table-get`。
+- pretty 输出是 5 列扫描表：`name`、`description`、`estimated_row_count`、`size`、`columns`（即列数）。
+- 若响应带 `has_more=true`，用返回的 `page_token` / `next_page_token` 翻页。
+
+## Agent 规则
+
+用户说“本地/开发库/调试库”时优先 `--env dev`；线上问题排查用 `--env online`。如果 dev 返回服务端错误提示未初始化，多环境入口是 [`+db-env-create`](lark-apps-db-env-create.md)。

package/skills/lark-apps/references/lark-apps-env-pull.md

@@ -0,0 +1,35 @@
+# apps +env-pull
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+
+把妙搭应用的启动期环境变量拉取到本地项目根的 `.env.local`。身份固定 `--as user`；scope `spark:app:read`。`--app-id` 必填，目标项目根默认当前工作目录（`--project-path` 可指定）。
+
+## 何时别用（核心反模式）
+
+**通常不需要手动跑**——脚手架的 `npm run dev` 在起本地开发时会自动后台拉取（非阻塞）。手动再跑会重复做同样的事，并把用户刚改完的 `.env.local` 临时改动覆盖掉。
+
+只在这些兜底场景用：
+
+- 不通过 `npm run dev` 启动（直接跑 `node` / IDE debug）。
+- `.env.local` 被改坏 / 删除，想重新同步。
+
+## 行为
+
+- **合并、不清空**：写入 `.env.local` 时保留你手写的内容与注释——命中的 key 替换值，新 key 追加，不整体覆盖。
+- **安全护栏**：返回的 envelope **不会回显任何 env key / value**（防止 token / 数据库凭据泄漏到日志或 CI 输出）。要看实际值请直接读 `.env.local`。
+
+## 示例
+
+```bash
+lark-cli apps +env-pull --app-id app_xxx
+```
+
+## 失败处理
+
+`missing_scope`（没拿到 `spark:app:read`）时，按 lark-shared 引导 `lark-cli auth login --domain apps`。其余失败优先转述 `error.hint` / `error.message`。
+
+## 参考
+
+- [lark-apps](../SKILL.md) — 妙搭应用全部命令 + 心智模型
+- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地全栈开发端到端流程
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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。