@amaster.ai/pi-lark 0.1.2-beta.52 → 0.1.2-beta.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.2-beta.52",
+  "version": "0.1.2-beta.54",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.2-beta.52"
+    "@amaster.ai/pi-shared": "0.1.2-beta.54"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-apps
 version: 1.0.0
-description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用协作者与协作权限设置、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用协作者/开发权限、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -44,6 +44,7 @@ lark-cli auth login --domain apps
 | 调试应用运行时缓存：查看/删除单个业务 key、清空指定环境缓存 | `+cache-get`/`+cache-delete`/`+cache-clear` | [`lark-apps-cache.md`](references/lark-apps-cache.md) |
 | **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | 本地开发链路先按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 确认本次改动已 git commit + git push，再用 `+release-create` / `+release-get`；查历史用 `+release-list` | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`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 |
+| 管理应用协作者（列出/添加/改权限/移除）或协作权限设置 | `+member-list`, `+member-add`, `+member-update`, `+member-remove`, `+member-settings-get`, `+member-settings-set` | 本文「应用协作者与协作权限设置」 |
 | 创意模式（html）应用的评论相关操作 | 创意模式应用评论走 lark-drive 文档评论体系，读取 [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) 了解评论能力 | [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) |
 | 管理 `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) |
@@ -60,26 +61,58 @@ lark-cli auth login --domain apps
 - **设置环境变量**：如果用户只给应用名，仍先 `+list --keyword` 解析 app_id；设置 online 环境且用户已经明确说“确认/直接执行”时，调用 `+env-set --environment online ... --yes`，不要再次要求确认。回复和日志摘要里只提 key / env / app，不回显真实 value；需要传复杂值时优先用 `@file` 或 stdin。
 - **删除环境变量**：`+env-delete` 是破坏性操作。除非用户在同一轮已经明确确认删除这个 app/env/key，否则先向用户确认应用、环境、key 和删除后果；确认后再加 `--yes`。不要因为认证失败/重登完成就自动继续删除，必须保留确认门槛。
 
+## 应用协作者与协作权限设置
+
+这组命令管理妙搭应用的开发协作者和协作策略，不等同于 `+access-scope-*` 的运行时访问范围，也不等同于 `+role-*` 的应用内业务角色。所有命令使用 `app_...` 应用 ID 和 `--as user`。不要读取或判断 `app_type` 来预判支持范围，直接调用对应的协作者命令。
+
+- `+member-list`、`+member-settings-get` 是只读命令，需要 `spark:app:read`。
+- `+member-add`、`+member-update`、`+member-remove`、`+member-settings-set` 是高风险写命令，需要 `spark:app:write`。先用 `--dry-run` 核对目标、URL 和请求体；dry-run 不需要 `--yes`。用户已确认具体应用、成员/设置及影响，或已按下方「高影响动作：确认与预授权」对整条流程明确预授权时，真实执行加 `--yes`；否则在 dry-run 后停下请求确认。批量移除成员仍执行「禁止预授权判定底线」，不能从泛化的“直接做”推导出 `--yes`。
+- 添加、更新、移除成员时必须显式提供匹配的外部 ID 类型，禁止传内部数字 ID、猜测类型或做隐式转换：用户 `--member-type openid --member-id ou_...`；群组 `--member-type openchat --member-id oc_...`；部门 `--member-type opendepartmentid --member-id od-...`。
+- `+member-list --member-type` 的筛选枚举是响应对象类型 `user` / `department` / `chat`，与写命令的 ID 类型枚举不同。可再用 `--role view|edit|full_access` 筛选。
+- `+member-list` 一次返回应用的全部直接协作者，不提供分页参数；可用 `--member-type` 和 `--role` 缩小结果范围。
+- 成员响应不包含应用详情。需要名称、类型或发布状态时单独调用 `+get --app-id <app_id>`，不要期待成员分页重复返回 `app`。
+- 收到 subtype `feature_not_available`（OpenAPI code `3340005`；直连服务可能为 `40005`）时，立即停止 CLI 自动化，不切换 `app_type`，也不尝试用 access scope、应用角色或其它成员命令绕过。向用户说明该应用暂不支持通过 lark-cli 设置协作者，并引导其在妙搭后台的权限设置中操作。
+- `external_invite` 只在 `+member-settings-get` 的响应中读取，不能独立设置；它会跟随 `external_access`。CLI 不注册 `--external-invite`，需要改变外部协作能力时只设置 `--external-access`。
+- `copy_download_by` 也只在 `+member-settings-get` 的响应中读取。CCM 当前明确不支持为妙搭对象写入复制、打印和下载权限，因此 CLI 不注册 `--copy-download-by`。保留读取结果，不要尝试写入，也不要改用其它权限字段模拟。
+
+```bash
+# 读取协作者和当前协作策略
+lark-cli apps +member-list --app-id <app_id> --as user
+lark-cli apps +member-settings-get --app-id <app_id> --as user
+
+# 写操作先预览精确的 typed-ID 字段；确认后把 --dry-run 换成 --yes
+lark-cli apps +member-add --app-id <app_id> --member-type openid --member-id ou_xxx --perm view --dry-run --as user
+lark-cli apps +member-update --app-id <app_id> --member-type openchat --member-id oc_xxx --perm edit --dry-run --as user
+lark-cli apps +member-remove --app-id <app_id> --member-type opendepartmentid --member-id od-xxx --dry-run --as user
+lark-cli apps +member-settings-set --app-id <app_id> --external-access disabled --comment-by viewer --dry-run --as user
+```
+
 ## 选择开发路径（进意图路由前先判这步）
 
 新建必先定 **app_type** 和**开发方式**两件正交的事；修改已有先按「app_id 获取」指认到 app，指认不到就问用户，不擅自 `+create`。开发方式（本地 vs 云端）只看用户对"谁来写代码"的偏好，与应用复杂度、要不要数据库无关。
 
+**app_type 三类边界**（先判"要不要把数据存到服务端"，再判"纯展示还是有交互"）：
+
 | 信号 | 判定 |
 |---|---|
-| 静态展示 / 单页 / PPT/deck / demo / 落地页 / 仪表盘 / UI mockup / 可交互原型 / 线框图 / 视觉探索 / 无后端状态 | `app_type=html`，加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） |
-| 登录 / 数据库 / 持久化 / 多人协作 / 增删改查 / 报名 / 投票 / 站会 / OKR / 泛称"系统·工具" | `app_type=full_stack` |
+| 含数据库 / 后端持久化：登录 / 增删改查 / 报名·投票·站会存记录 / 多人协作 / 泛称"系统·工具"且明确要存数据 | `app_type=full_stack` |
+| 纯静态展示（给人"看"的物料，无 JS 交互）：PPT/deck / demo / 落地页 / 海报 / UI mockup / 线框图 / 静态仪表盘 / 视觉探索 | `app_type=html`，加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） |
+| 有 JS 交互但无数据库（给人"用"的前端应用）：可交互原型 / SPA / 表单校验 / 动态计算 / 调用外部 API / 泛称"工具·系统"但未明确要存数据 | `app_type=frontend`（**默认倾向**：用户未明确提出数据库需求时默认引导 frontend，不默认 full_stack） |
+| 类型模糊（尤其"要不要存数据"不清） | **追问**，话术偏向 frontend，例："看起来是个前端应用，需要保存数据吗？"；确认要存数据再转 full_stack，确认纯展示再转 html |
 | 用户要自己写 / 本地 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` 项目 | 直接继续本地按意图路由，不必问也不必判云端 |
 | 修改已有 + 有云端偏好 | 云端会话；未表达偏好且非本地项目 → 默认本地；判不准先问 |
 
+**类型升级**：`frontend` 应用后续需要数据库/后端能力时，本地 CLI 不提供类型升级；引导用户到云端会话（打开 `https://miaoda.feishu.cn/app/{app_id}`），用自然语言描述后端需求（如"给这个应用加登录和数据存储"）即可触发升级，无需特殊指令。
+
 ## 发布态护栏
 
 - **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。
 - 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。
-- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（仅 full_stack 应用）：进应用编辑/开发态、管理与继续开发应用的入口。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。
-- 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html 和 full_stack 统一走 `+release-get`）。
+- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（full_stack / frontend 应用）：进应用编辑/开发态、管理与继续开发应用的入口，也是 frontend 升级为 full_stack 的入口（云端会话）。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。
+- 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html / frontend / full_stack 统一走 `+release-get`）。
 - html 应用的主链路是创意模式开发方式：按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 初始化仓库、在仓库内产出 HTML 及关联文件，并通过 git commit / git push / `+release-create` / `+release-get` 发布部署。任何 git 操作（clone / pull / push）报错时，先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令。如果刷新凭证也失败，**停止并向用户报告**：原始 git 错误、凭证刷新失败原因，以及是否可能是当前环境（操作系统、沙箱）限制导致（如 macOS Keychain 在沙箱中不可用、Linux 加密文件目录不可写等）。不要改走 `+html-publish`，也不要把 `+html-publish` 当作本地开发链路的 fallback。
 - 创意模式（html）应用的链接格式为 `https://{租户域名}/page/{meta_token}`，**开发态和发布态是同一个链接**（区别于 full_stack 应用两者分开）。此链接形似飞书文档链接。`+get --app-id <meta_token>` 可获取应用信息（含 `app_id`），`+get --app-id <app_id>` 可获取 `meta_token`。看到 `/page/xxx` 链接时，它是妙搭创意模式应用，不要当成飞书文档跳过。
 
@@ -93,7 +126,7 @@ lark-cli auth login --domain apps
 - 实现领域 SDK 时，以实际包导出的类型和应用内领域 reference 记录的入参、响应路径为准；禁止修改 ambient `.d.ts`、补造宽松类型或强制断言，让猜测的 SDK 结构仅在本地"编译通过"。
 - typecheck/build 成功不等于合同正确。交付前逐项核对每个 SDK 调用的入参、响应取值路径和策略分支；涉及更新、删除等不同动作时，分别验证各自动作所需的完整状态，不能复用更弱的前置判断。
 - 源码任务交付前确认新增页面、Controller、Module 已接入真实 router/bootstrap，并运行项目现有 typecheck/build；只创建未接线文件不算完成。
-- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限仍需使用妙搭 Web。自动化触发器请用 `+automation-*`（见「意图路由」）。
+- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限使用 `+member-*` 和 `+member-settings-*`，应用内业务角色使用 `+role-*`。自动化触发器请用 `+automation-*`（见「意图路由」）。
 
 ## app_id 获取
 

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

@@ -10,7 +10,7 @@
 
 三层父子关系，下层都挂在上层之下：
 
-- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。云端生成应用类型用 `full_stack`。
+- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。`--app-type` 沿用 SKILL.md「选择开发路径」判定的类型（有数据库需求→`full_stack`；纯前端交互、未提数据库→默认 `frontend`），云端生成不写死 `full_stack`。
 - **session（会话）**：一个 app 下的一段独立对话上下文，由 `+session-create` 创建并拿到 `session_id`。一个 app 可有多个 session；`is_active` 表示该 session 当前是否可写（可发起对话）。
 - **turn（轮）**：一个 session 里的一轮交互 = 一条用户消息 + 妙搭 Agent 针对它的生成/迭代。`+chat` 发一条消息就发起一轮；轮的句柄是 `turn_id`，状态看 `latest_turn.status`。
 
@@ -41,7 +41,8 @@
 ### 典型链路
 
 ```bash
-# 1) 建 app，拿 app_id（云端生成走 full_stack）
+# 1) 建 app，拿 app_id（--app-type 用主路由判定的类型；此例"待办应用"要存待办→full_stack，
+#    若是纯前端交互工具且未提数据库则用 frontend）
 lark-cli apps +create --name "待办应用" --app-type full_stack \
   --description "支持新增、完成、筛选待办"
 
@@ -68,14 +69,14 @@ lark-cli apps +session-list --app-id app_xxx
 ## 需求发送
 
 - 只有用户明确选择云端路径，或明确说“让妙搭 Agent / 云端 AI 生成/迭代”时，才进入本 reference；不要因为用户只说“做个 X”或“给我链接”就默认云端。
-- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先建 `full_stack` app，再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
+- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先按主路由判定的 `--app-type` 建 app（有数据库需求→`full_stack`，纯前端交互未提数据库→默认 `frontend`），再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
 - 如果需求过泛，可在 `+chat --message` 中保留原话，并只补一句“请先生成通用版本，后续可继续迭代”，不要用多轮追问阻塞生成。
 
 ## 会话落点
 
 | 情形 | 动作 |
 |---|---|
-| 全新应用 + 云端生成 | 先 `+create --app-type full_stack` 拿 `app_id`，再 `+session-create` -> `+chat` |
+| 全新应用 + 云端生成 | 先按主路由判定的类型 `+create --app-type <frontend\|full_stack>`（未提数据库默认 frontend）拿 `app_id`，再 `+session-create` -> `+chat` |
 | 已知 app_id，用户没指定会话 | 先 `+session-list`；有活跃会话时问用户继续现有还是新开 |
 | 用户说“新开一段/换个话题” | `+session-create` 后再 `+chat` |
 | 用户说“接着刚才” | 复用上下文 session_id；拿不到就 `+session-list` 让用户选 |

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

@@ -4,12 +4,12 @@
 
 ## 何时用
 
-用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先创建 `full_stack` app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。
+用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先按 SKILL.md「选择开发路径」判定的 `--app-type`（有数据库需求→`full_stack`，纯前端交互未提数据库→默认 `frontend`）创建 app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。
 
 ## 命令骨架
 
 - 必填：`--name`、`--app-type`。
-- app type 语义取值为 `html` / `full_stack`；CLI 会把输入归一成小写后校验。
+- app type 取值为小写 `html` / `frontend` / `full_stack`；框架按枚举精确校验（不做大小写归一），非法值直接报错。
 - 可选：`--description`、`--icon-url`。
 
 ## 示例
@@ -17,6 +17,9 @@
 ```bash
 lark-cli apps +create --name "客户调研问卷" --app-type html
 
+lark-cli apps +create --name "JSON 格式化工具" --app-type frontend \
+  --description "纯前端交互工具，无需数据库"
+
 lark-cli apps +create --name "审批系统" --app-type full_stack \
   --description "部门审批系统，支持登录、提交申请、多级审批"
 
@@ -35,5 +38,5 @@ lark-cli apps +create --name "Demo" --app-type html --dry-run
 
 创建后按用户路径继续：
 
-- 本地应用开发（含 html 和 full_stack）：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
+- 本地应用开发（含 html / frontend / full_stack）：读 [`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-get.md

@@ -26,7 +26,7 @@ lark-cli apps +get --app-id app_xxx -q '.data.app.app_type'
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `app_id` | string | 应用唯一标识 |
-| `app_type` | string | 应用类型（如 HTML、FULL_STACK、MODERN_HTML） |
+| `app_type` | string | 应用类型（如 HTML、FRONTEND、FULL_STACK、MODERN_HTML） |
 | `name` | string | 应用显示名称 |
 | `description` | string | 应用功能说明 |
 | `icon_url` | string | 应用图标 URL |

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

@@ -10,7 +10,7 @@
 
 - 支持 `--keyword` 按应用名模糊搜索。
 - `--ownership` 枚举：`all` / `mine` / `shared`（默认 `all` = 我创建的 + 共享给我的；`mine` = 仅我创建；`shared` = 仅共享给我）。
-- `--app-type` 枚举：`html` / `full_stack`。
+- `--app-type` 枚举：`html` / `frontend` / `full_stack`。
 - 分页：`--page-size` 默认 20，`--page-token` 传上一页 cursor。
 
 ## 示例

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

@@ -1,6 +1,6 @@
 # lark-apps 本地开发
 
-适用：用户要把妙搭应用（full_stack 或 html）源码拉到本地，用本地 code agent/IDE 开发、调试数据库，再发布。
+适用：用户要把妙搭应用（full_stack、frontend 或 html）源码拉到本地，用本地 code agent/IDE 开发、再发布。其中调试数据库仅 full_stack 适用（frontend / html 无数据库）。
 
 ## 新建 vs 已有应用
 
@@ -36,6 +36,32 @@ git push origin sprint/default
 lark-cli apps +release-create --as user --app-id app_xxx --branch sprint/default
 ```
 
+### frontend
+
+纯前端应用（vite-react，无数据库）。流程与 full_stack 基本一致——`+init` 装依赖、`npm run dev`、commit/push/release——差别是无 `+db-*` 调库步骤。后续需要数据库/后端能力时不在本地升级，按 SKILL.md「类型升级」引导到云端会话。
+
+```bash
+# 新建 frontend 应用
+lark-cli apps +create --as user --name "JSON 格式化工具" --app-type frontend \
+  --description "纯前端交互工具，无需数据库"
+
+# 初始化本地仓库（--dir 取值见下方「领域规则」，勿照抄此处示例值）
+lark-cli apps +init --as user --app-id app_xxx --dir ./json-tool
+
+# 进入仓库后按项目脚手架启动（vite-react）
+cd ./json-tool
+npm install
+npm run dev
+
+# 开发完成后：提交本次改动 -> git push origin sprint/default -> +release-create
+git add <本次开发的文件>
+git commit -m "feat: ..."
+git push origin sprint/default
+lark-cli apps +release-create --as user --app-id app_xxx --branch sprint/default
+# 发布是异步的：用 +release-get 轮询到 status=finished 才算部署完成、拿到 online_url
+lark-cli apps +release-get --as user --app-id app_xxx --release-id <上一步返回的 release_id>
+```
+
 ### html
 
 #### 首次开发（无 app，无代码）

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

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-用于把应用的代码分支推进到发布流程（html 和 full_stack 统一走此入口）。
+用于把应用的代码分支推进到发布流程（html / frontend / full_stack 统一走此入口）。
 
 ## 命令骨架
 

package/skills/lark-base/SKILL.md

@@ -57,7 +57,7 @@ metadata:
 | 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
 | 复制 Base 内单张数据表 | `+table-copy` / `+table-copy-status` | 默认只复制结构；只有用户明确要求复制全表、数据、行或记录时才传 `--range all`；异步任务按返回的 `task_id` 查询或续等 |
 | 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
-| 创建/更新字段 | `+field-create` / `+field-update` | 必读 [lark-base-field-json.md](references/lark-base-field-json.md)；公式读 [formula-field-guide.md](references/formula-field-guide.md)；lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md)；命令细节读 [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md) |
+| 创建/更新字段 | `+field-create` / `+field-update` | 同一表创建多个字段时，默认一次向 `+field-create --json` 传字段对象数组；预计串行运行时间超过 caller/tool timeout 时按时间预算拆分，不按固定条数切块；仅创建一个或多个只含 `name` + `type:text` 的简单字段时按 `+field-create --help` 即可，其他类型或属性必读 [lark-base-field-json.md](references/lark-base-field-json.md)；公式读 [formula-field-guide.md](references/formula-field-guide.md)，lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md)；仍需逐项恢复或命令细节时读 [lark-base-field-create.md](references/lark-base-field-create.md)，更新细节读 [lark-base-field-update.md](references/lark-base-field-update.md) |
 | 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) |
 | 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
 | 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
@@ -113,12 +113,13 @@ metadata:
 ## 写入前置规则
 
 - 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
+- 严格区分动作语义：用户要求“新增/创建”时，必须用本轮 create 返回的对象、ID 或数量确认完成，不能把已有资源算作本轮新增；目标已存在时按具体命令或 guide 的同名契约处理，不得自行改写用户语义。复合创建任务对每类资源只做一次必要盘点；只有命令明确返回逐项结果时才优先使用批量创建，并继续配置本轮返回的 ID。
 - 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
 - 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
-- 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；请求字段类型不在 reference 已支持类型目录中时，说明当前 CLI 不支持并停止，不要猜测未注册的字段 JSON、service 或 schema，也不要用其他字段类型冒充；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
+- 除上述简单 text fast path 外，写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；请求字段类型不在 reference 已支持类型目录中时，说明当前 CLI 不支持并停止，不要猜测未注册的字段 JSON、service 或 schema，也不要用其他字段类型冒充；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
 - 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
 - 删除、角色更新、字段更新、表单提交（`+form-submit`）等高风险操作遵循 CLI 的 confirmation gate，必须带 `--yes`；目标不明确时先用 get/list 消歧。
-- 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
+- 真正的 batch 写命令遵守各自文档的单批上限；`+field-create` 数组是顺序单项请求，按 caller timeout 而非固定条数拆分；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
 - `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 表单与视图细节

package/skills/lark-base/references/lark-base-data-query-guide.md

@@ -42,6 +42,14 @@ lark-cli base +data-query \
   --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"shaper":{"format":"flat"}}'
 ```
 
+## Common filter values
+
+Common `Condition.value` shapes: select `is` / `isNot` uses exactly one option
+name; datetime `is` / `isGreater` / `isLess` uses `["Today"]` or
+`["ExactDate","<epoch_ms>"]`; `isEmpty` / `isNotEmpty` uses `[]`.
+Use relative date keywords only for relative requests; see
+[lark-base-data-query.md](lark-base-data-query.md) for other field types and operators.
+
 Use `tableName` when the table ID is unavailable but the table name is known:
 
 ```bash

package/skills/lark-base/references/lark-base-field-create.md

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-创建一个字段。
+创建一个或多个字段；同一表的多个字段默认使用一次 JSON 数组输入。预计串行运行时间超过 caller/tool timeout 时按时间预算拆分，不按固定条数切块。
 
 ## Agent 最小工作流
 
@@ -29,6 +29,12 @@ lark-cli base +field-create \
   --base-token <base_token> \
   --table-id <table_id> \
   --json '{"name":"负责人","type":"user","multiple":false,"default_value":[{"$slot":"current_user"}],"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
+
+# 多个字段复用相同字段 JSON 形状，一次传非空数组
+lark-cli base +field-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --json '[{"name":"备注","type":"text"},{"name":"优先级","type":"select","multiple":false,"options":[{"name":"高"},{"name":"低"}]}]'
 ```
 
 ## 参数
@@ -37,7 +43,8 @@ lark-cli base +field-create \
 |------|------|------|
 | `--base-token <token>` | 是 | Base Token |
 | `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--json <body>` | 是 | 字段属性 JSON 对象 |
+| `--json <body>` | 是 | 单个字段 JSON 对象，或多个字段对象组成的非空数组 |
+
 ## API 入参详情
 
 **HTTP 方法和路径：**
@@ -48,8 +55,9 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 
 ## JSON 值规范
 
-- `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。
-- 顶层最少包含：`name`、`type`。
+- `--json` 接受单个字段 **JSON 对象**，也接受多个字段对象组成的非空数组；不要再套 `fields` 等外层对象。
+- 数组按顺序创建字段，遇到首个失败即停止且不自动回滚已创建字段；需要原子写入时不要假设数组具备事务语义。
+- 每个字段对象最少包含：`name`、`type`。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
 - 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；`datetime` / `user` 的动态填充用 `$slot`。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。
 - `type` 不同，必填子字段不同：
@@ -86,13 +94,16 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 
 ## 返回重点
 
-- 返回 `field` 和 `created: true`。
-- 如果返回 `field_get_recommended:false` 且 `next_step:"done"`，表示本次是简单字段创建，通常不需要立刻执行 `+field-get`。
-- 如果返回 `field_get_recommended:true` 或 `next_step:"field_get"`，按 `verification_hint` 读回字段；`formula`、`lookup`、`link`、`auto_number` 等计算、关联或生成型字段更适合读回确认服务端最终结构。
+- 单字段返回 `field` 和 `created: true`；多字段完整返回服务端 `fields`、`total` 和 `created: true`。
+- 大数组成功时若不需要逐字段 ID，可追加 `--jq 'if .ok then (.data | {created,total,field_get_recommended,next_step,verification_hint}) else . end'` 控制 stdout 大小；失败分支仍保留完整部分失败明细。需要逐字段 ID 时不要使用该投影。
+- 数组部分失败返回 `ok:false`、`summary` 和有序 `items`，保留已创建字段及 ID、失败项和未执行项。`failed` 项保留 `type`、`subtype`、`code`、`hint`、`retryable`、`log_id`、`troubleshooter`，以及原 typed error 已有的扩展字段，例如权限错误的 `missing_scopes`、`identity`、`console_url` 或安全策略错误的 `challenge_url`；扩展键与部分失败账本的 `index`、`status`、`field`、`error` 冲突时，以带 `error_` 前缀的无冲突别名输出（例如 `field` → `error_field`）。
+- 部分失败统一返回 `next_step:"inspect_items"`；`field_get_recommended` 仅表示已创建字段是否建议读回。`retryable:true` 只表示该 `failed` 项可原样自动重试；否则先按该项 `hint` 完成授权或修正输入，再重新提交该项。`not_attempted` 项应单独继续。
+- 调用方超时且未收到命令终态输出时，不要重投整个数组；先按本次提交的字段名定向读回，再只提交缺失项。没有写前快照时，读回命中的同名项只能标记为 `ambiguous`，不得计作本轮 `created`。
+- 完整成功且返回 `field_get_recommended:false`、`next_step:"done"` 时直接结束；除非用户明确要求读回或额外属性，否则不要再执行 `+field-list/get`。确需核验时用 `--jq` 过滤 `+field-list`，不要把全部字段打印进上下文。
+- `field_get_recommended:true` 表示完成当前 `next_step` 后按 `verification_hint` 读回；完整成功时 `next_step:"field_get"` 表示可直接读回。`formula`、`lookup`、`link`、`auto_number` 等字段更适合读回确认服务端最终结构。
 
 ## 工作流
 
-
 1. formula / lookup 字段必须先阅读对应指南；没读之前不要直接创建。
 2. 创建简单字段时，优先相信命令返回；只有用户要求精确核对额外属性，或返回建议读回时，才继续执行 `+field-get`。
 

package/skills/lark-base/references/lark-base-field-json.md

@@ -6,8 +6,9 @@
 
 ## 1. 顶层规则（必须遵守）
 
-- `--json` 必须是 JSON 对象。
-- 顶层统一使用：`type` + `name` + 类型特有字段。
+- 单个字段定义始终是 JSON 对象，每个字段对象统一使用：`type` + `name` + 类型特有字段。
+- `+field-create --json` 接受一个字段对象或非空字段对象数组。
+- `+field-update --json` 只接受一个字段对象。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
 - 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；省略表示创建时不设置、更新时不修改。
 - 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。

package/skills/lark-doc/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: lark-doc
-version: 2.0.0
-description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。当用户明确要操作飞书思维笔记时，也使用本 skill。"
+description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。文档评论走 lark-drive；表格或 Base 内部数据操作不在本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -11,75 +10,40 @@ metadata:
 
 # docs
 
-**身份：文档操作默认使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
+## 场景与 Shortcut 路由
 
-```bash
-# 常用示例
-lark-cli docs +fetch --doc "文档URL或token；若 URL 存在 #share-... 锚点，优先使用锚点方式读取，不要全文拉取"
-lark-cli docs +create --content '<title>标题</title><p>内容</p>'
-lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
-```
+**CRITICAL：先判断场景，再读取该场景的参考文件；不要在任务开始时一次性读取全部参考文件。每个文件只在首次进入对应阶段时读取一次。**
 
-## 前置条件 — 执行操作前必读
+**身份：文档操作推荐显式指定 `--as user`。**
 
-**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
-1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
-2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
-3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和必读 [`lark-doc-style.md`](references/style/lark-doc-style.md)（写作原则：默认段落、按体裁、组件克制）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
+**所有表示本地文件的 `@path` 均使用 `@./xxx` 形式的相对路径，并以运行 `lark-cli` 时的当前工作目录（CWD）为基准。**
 
-**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
+### 文档内容
 
-> **格式选择规则（全局）：**
-> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
-> - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
+- **读取 / 摘要 — [`+fetch`](references/lark-doc-fetch.md)**：先读参考再获取文档。
+- **从零创作 — [`创建工作流`](references/lark-doc-create-workflow.md)**：先完整执行创建工作流，**简单任务不是跳过的理由**；
+- **导入 / 空文档 — [`+create`](references/lark-doc-create.md)**：仅创建空文档或原样导入用户提供的完整内容时，跳过创建工作流。
+- **编辑 / block 直达链接 — [`+update`](references/lark-doc-update.md)**：语义改写、润色、重组、补写或排版均按 update 参考完成。
 
-## 快速决策
-- 用户要**复制文档 / 创建文档副本 / 另存为副本**时，切到 [`lark-drive`](../lark-drive/SKILL.md)，按其中的复制指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文，也不要走 `drive +export` / `drive +import`。
-- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
-- block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
-- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
-- 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
-- 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
-- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
-- 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
-- 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
-- 用户想把文档回滚到某个 `revision_id` 或某一时刻 → 先读 [`lark-doc-history.md`](references/lark-doc-history.md)，按其中流程操作
-- 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
-- `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
-- 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
-- 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
-- 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
-- 用户需要统计文档的**总字数 / 总字符数**（word count / character count）时，先读取 [`lark-doc-word-stat.md`](references/lark-doc-word-stat.md)，并按其中流程调用 [`scripts/doc_word_stat.py`](scripts/doc_word_stat.py)；统计口径以该脚本为准，不要改用其他方式自行计算。
-- 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理
-- 文档内容中出现嵌入的 `<sheet>`、`<bitable>` 或 `<cite file-type="sheets|bitable">` 标签时 → **必须主动提取 token 并切到对应技能下钻读取内部数据**，不能只呈现标签本身
+### 辅助能力
 
-| 标签 / 属性 | 提取字段 | 切到技能 |
-|-|-|-|
-| `<sheet token="..." sheet-id="...">` | `token` -> spreadsheet_token, `sheet-id` | [`lark-sheets`](../lark-sheets/SKILL.md) |
-| `<bitable token="..." table-id="...">` | `token` -> app_token, `table-id` | [`lark-base`](../lark-base/SKILL.md) |
-| `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/SKILL.md) |
-| `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/SKILL.md) |
-| `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
-| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch` 读取 src-token 文档，定位 block |
+- **草稿初始化、解析与统计 — [`+script`](references/lark-doc-script.md)**：支持解析文档 URL / token 与本地 XML，统计字数并返回字符诊断；不支持 Markdown 输入。
+- **历史版本 — [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md)**：查询、回滚文档历史版本或检查回滚任务状态。
 
-## Shortcuts（推荐优先使用）
+### 资源、画板与思维笔记
 
-Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+- **插入本地素材 — [`+media-insert`](references/lark-doc-media-insert.md)**：在文末插入本地图片或文件。
+- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档中的图片、附件或素材。
+- **下载素材 — [`+media-download`](references/lark-doc-media-download.md)**：下载文档中的图片、附件、素材或画板缩略图。
+- **Docx 封面 — [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md)**：下载、更新或删除 Docx 封面。
+- **画板 — [`画板工作流`](references/lark-doc-whiteboard.md)**：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 [`whiteboard +update`](../lark-whiteboard/references/lark-whiteboard-update.md) 写入。
+- **思维笔记 — `mindnotes`**：已有思维笔记走 [`思维笔记链路`](references/lark-doc-mindnote.md)；新建思维笔记走 [`lark-doc-whiteboard`](references/lark-doc-whiteboard.md)。
 
-| Shortcut | 说明 |
-|----------|------|
-| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
-| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
-| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
-| [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md) | List document history, revert to a `history_version_id`, and query revert task status |
-| [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
-| [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
-| [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
-| [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md) | Download, update, or delete a Docx cover image resource with `--type cover` |
-| [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. |
+### 认证与 Scope
+
+执行 Shortcut 时，不预读 [`lark-shared`](../lark-shared/SKILL.md) 或预跑 `auth status --verify`；仅遇到未认证、token / 身份或 scope 错误时读取该 Skill，修复后重试。认证、身份或 scope 管理请求则直接使用该 Skill。
 
 ## 不在本 Skill 范围
 
-- 文档评论管理 → [`lark-drive`](../lark-drive/SKILL.md)
-- 电子表格或 Base 的数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
-- 云空间文件上传、下载、权限管理 → [`lark-drive`](../lark-drive/SKILL.md)
+- **Drive 文件级操作**：找文档、导入导出、云空间文件上传 / 下载 / 权限管理 → [`lark-drive`](../lark-drive/SKILL.md)。复制文档、创建副本或另存为副本时，按其指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文。
+- **文档评论**：添加、查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)。

package/skills/lark-doc/references/genres/business-analysis.md

@@ -0,0 +1,30 @@
+# Genre Contract: Business Analysis / 商业分析 (`report.business_analysis`)
+
+## 体裁规则表（硬约束）
+
+| 规则项 | 规则 |
+|-|-|
+| 写作风格 | 结论前置、具体、条件化；模型只用于改变比较或暴露约束，不用管理黑话代替判断 |
+| 内容逻辑 | 围绕一个具体决策，比较现状 / 不行动与真实替代项；用统一目标和口径评价价值、全周期成本、风险、约束与可实施性，给出推荐、暂缓或验证门及翻转条件 |
+| 事实 / 边界 | 事实、估算、假设、未知和外部依赖分开；数字标来源、时点、单位、口径和置信范围；利益相关方、不可货币化影响和权限边界显著；分析建议不等于批准或承诺 |
+| 错误 | 为预选方案找论据；无现状基准或真实替代项；口径不一却排名；单一 ROI / BCR / 评分替代平衡判断；套 SWOT；估算冒充事实；忽略全周期成本、依赖或分配影响；未获批写成已承诺；建议不回链证据 |
+
+## 适用与消歧
+
+比较投资、资源、市场、产品、经营或供应选项并支持判断，但正文不要求具名决策者作出选择 / 批准，也不形成授权、资源拨付或执行承诺入口。`商业`、`市场分析`、`SWOT`单独只用于召回；回答研究问题走 [`research-report.md`](research-report.md)，纯指标解读走 [`data-report.md`](data-report.md)，命中上述 ask / 授权入口时走 Workplace Proposal，接口、不变量和实现取舍为主走 Technical RFC。
+
+## 子类型
+
+投资 / 资源配置；build-buy-partner 或 vendor；市场进入 / 扩张；产品 / 组合优先级；经营模式 / 流程；定价 / 商业模式；高不确定性的试点或阶段门。分析深度随金额、复杂度、不可逆性、影响范围和风险提高。
+
+## 证据与方法
+
+- 定义问题、目标、成功标准、范围、约束、决策 owner / 时点和现状 / 不行动基准；记录选项生成与排除理由。
+- 对每个可行选项用相同维度比较收益、全生命周期成本、时间、能力 / 依赖、风险、受影响方、不可货币化影响和可逆性。
+- 现状数据与预测分开；按需说明币种、价格时点、折现和估算方法。不得从官网标价推断销量、收入或份额。
+- 对可能翻转结论的假设做范围、情景或敏感性分析，并给 switching value、决策门或验证信号；评分模型须解释权重和证据，不能只报总分。
+- 缺目标、成功标准、基准或可行选项时只产出 decision frame / options discovery；关键估算用 `[成本区间待核]` 和验证计划，可能翻转结论且无法界定时标记 `blocked`。
+
+## 结构与高质量写法
+
+推荐与条件 → case for change / 目标 / 现状基准 → 选项生成、排除理由与同口径比较 → 关键假设、风险、情景与翻转条件 → 建议为何优于替代 → 阶段门、监测 / 学习计划与未决条件。把现状当真实选项，用区间和场景替代伪精确单点，显著说明谁获益、谁承担成本，以及什么新证据会改变建议。

package/skills/lark-doc/references/genres/data-report.md

@@ -0,0 +1,32 @@
+# Genre Contract: Data Report / 数据报告 (`report.data_report`)
+
+## 体裁规则表（硬约束）
+
+| 规则项 | 规则 |
+|-|-|
+| 写作风格 | 准确、可复算、少形容词；标题表达发现、对象和时点，并保留不确定性 |
+| 内容逻辑 | 先建立指标契约和可比基线，再回答发生了什么、为何重要、还不能断言什么；观测、解释假设与行动条件分开，限制紧邻相关结论 |
+| 事实 / 边界 | 核心指标标定义、单位、分子分母、总体 / 分群、时间窗、来源 / 版本、更新时间和修订状态；比较须同口径，估计须披露可得不确定性，敏感小群体须汇总、抑制或限制访问；数据图须标轴、单位、分母、时点和来源，并提供文字等价信息 |
+| 错误 | 只列数字；隐藏分母或口径变化；不可比数据排名；选择性窗口 / 分群；相关性当因果；图轴、单位或来源缺失；统计显著冒充效应大小或业务胜出；伪精确；限制藏在附录 |
+
+## 适用与消歧
+
+解读已定义指标、趋势、分布、漏斗、监控、估计或实验观察值。`有数据`、`有数字`、`分析一下`单独不决定路由；研究问题、抽样和可推广性为主走 [`research-report.md`](research-report.md)，比较商业选项走 [`business-analysis.md`](business-analysis.md)，组织状态、偏差和下一步走 Workplace 周期报告。
+
+## 子类型
+
+- KPI / 经营表现与趋势；分群、cohort 与分布；漏斗 / 路径与监控异常。
+- A/B 或实验 readout；设计和推断不足时只能报告观察值，不宣布因果胜出。
+- 预测、估计、修订或统计简报；须标模型 / 假设、适用期和修订状态。
+
+## 证据与方法
+
+- 保留可复算的基数、过滤、聚合、估计区间和质量说明；比较前核对定义、总体、时间窗、分母和处理方法。
+- 按误解风险同时给绝对值、绝对变化、相对变化和长期基线；不用多余小数位制造精确感。
+- 覆盖、缺失、偏差、口径变化和修订若会改变解释，须与对应发现同处，并说明可能方向、规模和影响。
+- 描述性差异不得写成因果；解释标为待验证假设。统计显著性不等于效应大小、实际重要性或完整决策依据。
+- 缺定义、分母、时间或来源时使用 `[指标定义待核]`、`[分母待核]`，对应值不得进入结论；不可比数据分开展示。核心决策依赖的质量缺口无法关闭时标记 `blocked`。
+
+## 结构与高质量写法
+
+关键发现与决策限制 → 指标契约 / 数据质量 → 总览与基线 → 必要分维、分布和反例 → 可支持的解释与待验证假设 → 条件式行动 / 验证门 → 方法、修订和来源。每段按“观测 → 基线 / 背景 → 限制 → 含义”推进；复杂图同时给出文字结论和必要精确值，任何视觉不得成为唯一证据。