@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/miaoda-modern/lark-apps-ops/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/miaoda-modern/lark-apps-ops/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/miaoda-modern/lark-apps-ops/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/miaoda-modern/lark-apps-ops/references/lark-apps-release-create.md

@@ -0,0 +1,30 @@
+# apps +release-create
+
+为妙搭应用创建发布 release。运行时命令事实以 `lark-cli apps +release-create --help` 为准。
+
+## 何时用
+
+用于把全栈应用的代码分支推进到发布流程。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选：`--branch`；省略时服务端使用默认发布分支。
+- 返回 `release_id` 和 `status`，后续用 `+release-get` 轮询。
+
+## 示例
+
+```bash
+lark-cli apps +release-create --app-id "$app_id"
+lark-cli apps +release-create --app-id "$app_id" --branch sprint/default --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.release_id` 和 `data.status`；`release_id` 是后续 `+release-get` 的入参。
+- `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
+- `+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/miaoda-modern/lark-apps-ops/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_id" --release-id <release_id>
+```
+
+## 输出契约
+
+- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
+- `status=publishing` 继续轮询。此时尚无 `online_url`；不要拿其它链接（如应用主页 / 开发态预览 URL）冒充"本轮发布的访问链接"——只回报 `release_id`、`status`，并说明 `finished` 后才有 `online_url`。
+- `status=finished` 发布成功——**本命令输出已含 `online_url`，直接读取它作为本轮发布的线上访问链接**返回用户。
+- `status=failed` 发布失败——**本命令输出已含 `error_logs`（`step`/`error_log`），直接据此向用户转述关键失败步骤和可行动修复**。
+- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"；未经 `+release-get` 确认 `finished` 的任何旁证都不能证明最新版本已部署。

package/miaoda-modern/lark-apps-ops/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_id" --page-size 10
+lark-cli apps +release-list --app-id "$app_id" --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`），而不是取全量再本地截断。

package/miaoda-modern/lark-apps-ops/references/lark-apps-update.md

@@ -0,0 +1,30 @@
+# apps +update
+
+部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。
+
+## 何时用
+
+只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 至少提供一个：`--name` 或 `--description`。
+- 只发送用户提供的字段，不会清空未提供字段。
+
+## 示例
+
+```bash
+lark-cli apps +update --app-id "$app_id" --name "审批系统"
+lark-cli apps +update --app-id "$app_id" --description "用于部门审批流转"
+lark-cli apps +update --app-id "$app_id" --name "审批系统" --description "用于部门审批流转" --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
+- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。
+
+## Agent 规则
+
+更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。

package/{shared/lark-apps → miaoda-modern/lark-apps-ops}/references/openapi-key.md

@@ -1,6 +1,6 @@
 # apps openapi-key 命令族（开放 API Key）
 
-管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `miaoda-lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
 
 ## 命令路由
 
@@ -18,12 +18,12 @@
 命令均带 `--app-id "$app_id"`（当前沙箱应用），如：
 
 ```bash
-miaoda-lark-cli apps +openapi-key-list --app-id "$app_id"
+lark-cli apps +openapi-key-list --app-id "$app_id"
 ```
 
 ## 密钥红线（安全关键，务必遵守）
 
-- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 miaoda-lark-cli 保存，请立即复制到你自己的密钥管理器）。
+- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 lark-cli 保存，请立即复制到你自己的密钥管理器）。
 - **绝不**把原始密钥写入 cache / config / recent / debug log / 错误信息，也不要在后续对话里回显完整密钥；只向用户转述一次并提示自行妥善保管。
 - **密钥丢失不能找回**：`list` / `get` 不回显原始密钥。唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
 

package/miaoda-modern/memory/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: memory
+description: "Auto memory: persist and recall workspace knowledge across sessions. 触发词：记住, 记忆, remember, memory, 别忘了, 记一下, recall, 约定, 偏好, convention, preference"
+hook: SessionStart
+---
+
+# 工作区记忆
+
+跨会话持久化工作区知识。工作时主动参考记忆文件，基于已有经验开展工作。
+
+## 记忆文件
+
+| 文件 | 说明 |
+|------|------|
+| `.agent-memory/MEMORY.md` | 主记忆文件，每次会话自动注入前 **200 行**到上下文，保持精简 |
+| `.agent-memory/topics/<name>.md` | 详细主题文件（≤100 行），从 MEMORY.md 链接 |
+
+使用 Write/Edit 工具管理记忆文件。
+
+## 写入规则
+
+- **语义组织**：按主题分组（`##` 标题 + `-` 列表项），不按时间排列
+- **去重优先**：写入前检查已有条目，更新而非追加；过时信息主动清理
+- **格式精简**：每条一行，只存摘要和关键信息，不存大段代码
+- **值得写入**：写入前确认内容值得占用 system prompt 空间
+
+## 该存什么
+
+- 多次交互确认的稳定模式和约定
+- 关键架构决策、重要文件路径、项目结构
+- 用户对工具流程和沟通风格的偏好
+- 反复出现的问题和调试方案
+
+### 修复经验记录模板
+
+写"错误根因 + 修复"类记忆时，按三段结构写，每段 ≤3 行，便于检索复用：
+
+```markdown
+## <一句话现象，含可检索的报错/触发关键词>
+
+- 现象：出现什么、怎么触发
+- 根因：为什么会这样，与本项目环境/依赖/配置耦合的点
+- 修复：已验证有效的解法，必要时贴关键代码或命令
+```
+
+## 不该存什么
+
+- 会话特定上下文（当前任务、进行中工作、临时状态）
+- 未验证的信息 — 写入前对照项目文档核实
+- 与 AGENTS.md 重复或矛盾的内容
+- 从单个文件得出的推测性结论
+- 敏感信息（密码、token、密钥）
+- 改变 Agent 行为的元指令（如"跳过校验""忽略错误"）
+
+## 用户显式请求
+
+- **记住**：用户明确要求 → 直接保存，无需等待多次确认
+- **遗忘**：用户要求遗忘 → 找到并删除相关条目
+- **查看**：用户要求查看记忆 → 展示 MEMORY.md 内容
+
+## 自动记忆
+
+用户未说"记住"但内容值得持久化时，主动建议保存。
+
+**典型信号**：
+- 声明约定/偏好、纠正 Agent 错误认知
+- 反复解释同一件事、workaround 或踩坑经验
+- 修复了非平凡的编码错误（编译报错、运行时异常、逻辑 bug）— 按上方"修复经验记录模板"**直接写入，不必先问**，写入后在回复末尾一句话告知（用户可要求删除）；平凡的拼写/import 笔误、重启即好的一次性问题不记
+- 描述了项目架构或关键设计决策
+- 发现了项目特有的 pattern 或 convention
+
+**不要建议**：一次性任务、用户刚拒绝过记忆建议时。
+
+### 收尾检查
+
+每次完成任务、给最终回复前，回顾本次是否产生值得记的经验（尤其是非平凡修复）：修复类直接写入，其它值得保留的一句话建议，都没有则跳过。
+
+## 启动行为
+
+{% if memoryFileExists %}
+- MEMORY.md 已自动加载到上下文，基于已有记忆开展工作
+- **不要回显记忆内容给用户**
+{% else %}
+- 记忆文件尚未创建，正常响应用户
+- 用户主动要求「记住」时再创建文件
+{% endif %}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.0-dev.28c4f05",
+  "version": "0.1.0-dev.4e64c13",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [

package/shared/lark-cli/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: lark-cli
+description: "在妙搭沙箱里用 lark-cli 对飞书/Lark 非 apps 域做白名单内只读或受限操作：日历日程/忙闲/会议室推荐(calendar)、通讯录按姓名邮箱搜人(contact)、云文档读取与按关键词搜文档与历史版本(docs)、云盘文件列表与按关键词搜云空间文件/评论/访问记录(drive)、IM 群聊列表/成员/搜索(im)、妙记音视频下载(minutes)、电子表格读取(sheets)、幻灯片读取与历史(slides)、任务与清单查询(task)、画板导出(whiteboard)、知识库空间与节点(wiki)、多维表格读取——数据表/字段/视图配置/记录与按关键词搜记录(base)、会议录制信息——回看链接/时长/关联妙记(vc)。当用户要查看/读取/搜索/下载/导出这些飞书资源的内容时使用；命令通道一律是 lark-cli 的非 apps 域。用户消息里出现飞书资源链接就属于本 skill 的场景——链接域名同时存在 feishu.cn / feishu-boe.cn / larkoffice.com / doubao.com 多种环境，路由只看路径与 token 形态、不看域名；这类链接无法用 web_fetch 或浏览器读取，必须走本 skill。触发词：飞书文档, 云文档, 飞书链接, 文档链接, 电子表格, 表格链接, 多维表格, Base, bitable, 维表, 知识库, wiki 空间, 节点, 妙记, 会议纪要, 逐字稿, 日程, 忙闲, 排期, 通讯录, 找人, 群聊, 群消息, 置顶消息, 表情回复, 任务清单, 待办, 画板, 白板, 幻灯片, 云空间, 我的云盘, 文件夹, 会议录制, /docx/, /sheets/, /base/, /wiki/, /slides/, /minutes/, /drive/folder/, feishu.cn, feishu-boe.cn, larkoffice.com。NOT for 妙搭应用操作（走 lark-apps 系列 skill）、未列出的域、以及各域未开放的写/管理命令（本沙箱屏蔽的能力不要拼）；也 NOT for 用插件（plugin / capabilityClient / CapabilityService）读取飞书资源——插件只用于生成出来的应用在运行时访问飞书，Agent 在生成期读取内容一律用 bash 调 lark-cli。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli --help; lark-cli <domain> --help"
+require-knowledge-sources:
+  - lark_cli
+control-by-feature-ab: true
+---
+
+# lark-cli（非 apps 域）· 沙箱版
+
+在妙搭沙箱里通过 `lark-cli` 对飞书/Lark 资源做**白名单内只读或受限操作**的入口 skill，按域拆分为 13 个子文档，本文件只做沙箱约定与意图路由。
+
+## 沙箱约定（先读）
+
+> 本约定块只出现在本根 SKILL.md 一份，13 个域共用；
+> 子域 `lark-<域>/README.md` 不重复本块。
+
+- **命令名**：一律 `lark-cli <域> +<cmd>`（快捷命令）或 `lark-cli <域> <resource> <method>`（各域白名单内的原生 API）；命令 / flag 细节以 `--help` 为准。
+- **不要鉴权自举**：沙箱运行环境负责准备并随请求带上这次会话所需的鉴权材料（token 经
+  `x-aily-token` 注入）；**不要**自行执行登录或初始化配置命令，遇到身份或权限不足的报错
+  也不需要自行引导补登录或补配置——本沙箱不涉及这些步骤。
+- **失败处理**：命令失败时把 `error.hint` 转述给用户，不要原样甩 envelope JSON。
+- **身份**：多数域默认以当前登录用户身份运行（`--as user`）；wiki 域默认 `auto`、需显式带 `--as user`，以各域 README 的「身份」节为准。能否读到目标资源取决于该用户的可见范围。
+- **原生 API 先查 schema**：调用 `lark-cli <域> <resource> <method>` 前，先 `lark-cli schema <域>.<resource>.<method>` 确认参数结构，不要凭直觉拼 `--params`。
+
+## 高风险写操作审批（exit-10）
+
+`risk: high-risk-write` 的命令不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
+
+1. 识别 exit code=10 且 `error.type=="confirmation_required"`；
+2. 把 `error.risk.action` + 关键参数转述给用户，明确"高风险"，等显式同意；
+3. 同意 → 原始 argv 末尾加 `--yes` 重试；拒绝 → 终止；
+4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）。
+
+**绝不**看到 exit 10 就默认补 `--yes` 静默重试。
+
+## 意图路由
+
+**执行某域操作前 MUST 先读对应域的 README.md，再按其指引读 references/**；不要只看本文件就拼命令。
+
+| 用户意图 | 读取 |
+|---|---|
+| 查日程、搜日程、看忙闲、找会议室、推荐时间块、取日程关联的会议信息 | [lark-calendar/README.md](lark-calendar/README.md) |
+| 按姓名/邮箱搜人拿 open_id、查他人或自己的资料 | [lark-contact/README.md](lark-contact/README.md) |
+| 读云文档内容（整篇或锚点局部）、列文档历史版本 | [lark-doc/README.md](lark-doc/README.md) |
+| 列云盘文件夹子项、查文档评论列表、查文档访问记录 | [lark-drive/README.md](lark-drive/README.md) |
+| 列群聊、搜群、看群成员、查置顶/表情回复等群状态 | [lark-im/README.md](lark-im/README.md) |
+| 下载妙记音视频、查妙记基础信息 | [lark-minutes/README.md](lark-minutes/README.md) |
+| 读电子表格数据/公式/样式/对象配置、看历史版本与变更 | [lark-sheets/README.md](lark-sheets/README.md) |
+| 读演示文稿整份或单页 XML、看历史版本与回滚任务状态 | [lark-slides/README.md](lark-slides/README.md) |
+| 搜索或列取任务/任务清单（分配给我、我创建、我关注等） | [lark-task/README.md](lark-task/README.md) |
+| 导出画板为预览图/SVG/代码/原始节点结构 | [lark-whiteboard/README.md](lark-whiteboard/README.md) |
+| 列知识库空间、列/查 wiki 节点、看空间成员 | [lark-wiki/README.md](lark-wiki/README.md) |
+| 读多维表格：列表/字段/视图配置/记录、按关键词搜记录 | [lark-base/README.md](lark-base/README.md) |
+| 查会议录制：回看链接、时长、关联妙记 | [lark-vc/README.md](lark-vc/README.md) |
+
+### calendar —— 日程与会议安排
+
+- 触发词：日程、日历、会议安排、今天/本周有什么会、忙闲、空闲时段、会议室、约个时间。
+- 能力：日程查询（`+agenda` / `+get` / `+search-event`）、忙闲（`+freebusy`）、会议室查找（`+room-find`）、时间块推荐（`+suggestion`）、日程关联视频会议信息（`+meeting`）。
+- 入口：[lark-calendar/README.md](lark-calendar/README.md)
+
+```bash
+lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17
+lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27
+```
+
+### contact —— 通讯录搜人
+
+- 触发词：找人、搜员工、某人的 open_id、查某人的部门/邮箱、我的资料。
+- 能力：按姓名/邮箱搜人拿 open_id（`+search-user`）、按 open_id 取资料、查看自己（`+get-user`）。
+- 拿到 open_id 后想发消息 / 新建日程的限制见下方「能力边界」的跨域协作条目。
+- 入口：[lark-contact/README.md](lark-contact/README.md)
+
+```bash
+lark-cli contact +search-user --query "张三" --has-chatted
+lark-cli contact +get-user
+```
+
+### doc —— 云文档读取
+
+- 触发词：读文档、看飞书文档、docx/wiki 链接内容、文档历史版本。
+- 能力：`docs +fetch`（整篇或 `#share-...` / `#block_id` 锚点局部读取）、`docs +history-list`（历史版本列表）、`docs +search`（按关键词搜云文档）。本沙箱仅这三个只读入口。
+- 入口：[lark-doc/README.md](lark-doc/README.md)
+
+```bash
+lark-cli docs +fetch --doc "文档URL或token"
+lark-cli docs +history-list --doc "文档URL或token" --page-size 20
+lark-cli docs +search --query "<关键词>"
+```
+
+### drive —— 云盘盘点与评论/访问记录
+
+- 触发词：云盘里有什么、列文件夹、文档评论、谁看过这个文档。
+- 能力：`drive +search`（按关键词搜云空间文件，支持类型/归属/时间窗过滤）、`drive files list`（列子项、可递归盘点）、`drive file.comments list`（评论）、`drive file.view_records list`（访问记录）。仅 1 个快捷命令 + 3 个只读原生 API。
+- 入口：[lark-drive/README.md](lark-drive/README.md)
+
+```bash
+lark-cli schema drive.files.list   # 调用原生 API 前先看参数结构
+lark-cli drive files list --params '{"folder_token":"<folder_token>","page_size":200}'
+lark-cli drive +search --query "<关键词>" --doc-types file --mine
+```
+
+### im —— 群聊与成员查询
+
+- 触发词：我有哪些群、搜群名、群里都有谁、群里的机器人、置顶消息、表情回复。
+- 能力：`+chat-list` / `+chat-search` / `+chat-members-list` 三个只读快捷命令，及 pins、reactions 等白名单只读 API。
+- 入口：[lark-im/README.md](lark-im/README.md)
+
+```bash
+lark-cli im +chat-list --sort active_time
+lark-cli im +chat-search --query "项目群"
+```
+
+### minutes —— 妙记
+
+- 触发词：妙记、会议录制、minutes 链接、下载音视频、妙记信息。
+- 能力：`+download`（下载妙记音视频媒体）、`minutes minutes get`（标题/时长/所有者等基础信息）。
+- 入口：[lark-minutes/README.md](lark-minutes/README.md)
+
+```bash
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output ./meeting.mp4
+```
+
+### sheets —— 电子表格读取
+
+- 触发词：读表格、看电子表格、汇总某列、公式对不对、图表/透视表配置、表格历史版本。
+- 能力：读数据（`+csv-get` / `+table-get` / `+cells-get`）、结构与对象配置（工作表/图表/透视表/条件格式/筛选器/迷你图/浮动图片）、历史与变更（`+history-list` / `+changeset-get`）、公式自检（`+formula-verify`）。
+- 入口：[lark-sheets/README.md](lark-sheets/README.md)
+
+```bash
+lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实表名>" --range "A1:F30"
+```
+
+### slides —— 幻灯片读取
+
+- 触发词：看演示文稿、读 slides、某页幻灯片内容、幻灯片历史版本。
+- 能力：整份 XML（`slides xml_presentations get`）、单页 XML（可指定历史版本）、历史版本列表与回滚任务状态查询。
+- 入口：[lark-slides/README.md](lark-slides/README.md)
+
+```bash
+lark-cli schema slides.xml_presentation.history.list   # 先看参数结构
+lark-cli slides xml_presentation.history list --as user --params '<json_params>'
+```
+
+### task —— 任务与清单查询
+
+- 触发词：我的任务、分配给我的待办、我创建/关注的任务、任务清单、截止日期。
+- 能力：任务搜索（`+search`）、我的任务（`+get-my-tasks`）、与我相关（`+get-related-tasks`）、清单搜索（`+tasklist-search`）。
+- 「待办」一词有归属歧义（飞书任务 vs 妙记待办），先按 lark-task README 的归属判断节确认。
+- 入口：[lark-task/README.md](lark-task/README.md)
+
+```bash
+lark-cli task +get-my-tasks
+lark-cli task +search --query "上线"
+```
+
+### whiteboard —— 画板导出
+
+- 触发词：看画板、导出画板图片、画板 SVG、画板是不是代码画的、画板节点结构。
+- 能力：`+export` 导出预览图 / SVG / Mermaid·PlantUML 源码 / 原始节点结构（raw）。
+- 入口：[lark-whiteboard/README.md](lark-whiteboard/README.md)
+
+```bash
+lark-cli whiteboard +export --whiteboard-token "wbcnxxxxxxxx" --output-type preview --output ./preview
+```
+
+### wiki —— 知识库查询
+
+- 触发词：知识库、wiki 空间、wiki 节点、知识库目录、空间成员。
+- 能力：列空间（`+space-list`）、列节点（`+node-list`）、查节点详情/解析 wiki URL（`+node-get`）、列空间成员（`wiki members list`）。
+- 入口：[lark-wiki/README.md](lark-wiki/README.md)
+
+```bash
+lark-cli wiki +space-list --as user
+lark-cli wiki +node-get --node-token "<wiki URL 或 token>" --as user
+```
+
+### base —— 多维表格读取
+
+- 触发词：多维表格、Base、bitable、表里的记录、视图筛选、字段类型。
+- 能力：定位（`+url-resolve`）、元信息（`+base-get`）、结构（`+table-list` / `+field-list` / `+view-list`）、视图配置（7 个 `+view-get*`）、记录（`+record-list` / `+record-search`）。仅这 8 类只读入口。
+- 入口：[lark-base/README.md](lark-base/README.md)
+
+```bash
+lark-cli base +url-resolve --url "<Base URL>"
+lark-cli base +record-list --base-token <t> --table-id <tbl> --view-id "<视图名>"
+```
+
+### vc —— 会议录制
+
+- 触发词：会议录制、回看链接、录了多久、meeting_id。
+- 能力：`vc +recording`（按 `--meeting-ids` 或 `--calendar-event-ids` 查录制的 `recording_url` / `duration` / `minute_token`）。仅这一个只读入口。
+- 输入：`meeting_id` 或日程实例 ID 二者之一，**必须由用户直接提供**；只拿到会议链接或会议号时向用户索取 ID。
+- 入口：[lark-vc/README.md](lark-vc/README.md)
+
+```bash
+lark-cli vc +recording --meeting-ids <meeting_id>
+```
+
+### 跨域串联提示
+
+一次请求常跨多个域，按链路顺序读各域 README：
+
+- **找人 → 发消息/排日程**：先 contact 搜人拿 `open_id`；发消息、新建日程 / 邀请会议在当前沙箱不可用（im 域仅开放群相关的只读查询、calendar 域无写能力），拿到 open_id 后告知用户该限制，不要用其它域命令替代；查日程 / 忙闲走 calendar 只读查询。
+- **找文件 → 读内容**：只知道文件名不知道 URL 时，先在 drive / wiki 定位资源拿 token，再回 doc / sheets / slides 读内容。
+- **wiki 链接 → 具体文档**：`/wiki/<token>` 链接先走 wiki `+node-get` 解析出 `obj_token` 与 `obj_type`，再按类型转 doc / sheets / slides 域读取。
+- **约会议**：时间不明确时先在 calendar 用 `+suggestion` 推荐时间块，确认时间块后再用 `+room-find` 找会议室；无明确时间块禁止直接调 `+room-find`。
+- **「待办」归属**：上下文含妙记/会议纪要时不走 task 域，归属判断细则见 lark-task README。
+
+## 能力边界
+
+- **只开放各域 README 列出的白名单命令**：各域 README 未列出的命令与 flag 在本沙箱被屏蔽，不要凭上游文档或直觉拼；原生 API 仅各域 README「API Resources」白名单内的可用。
+- **未列出的域不可用**：本 skill 只覆盖上述 13 个非 apps 域；未列出的域未开放，不要尝试。
+- **写/管理操作默认不开放**：创建、编辑、删除、上传、权限管理等能力大多被屏蔽；个别高风险写入口命中 exit 10 门禁时，按上文「高风险写操作审批（exit-10）」协议处理，绝不静默补 `--yes`。
+- **妙搭应用操作不在这里**：对当前妙搭应用的操作（部署发布、改应用名、环境变量、线上日志与监控、插件、开放 API Key、可见范围等）走 [`lark-apps-ops`](../lark-apps-ops/SKILL.md) 系列 skill。
+- **不要用插件代替本 skill 读资源**：你现在要读的飞书资源，一律用 bash 跑 `lark-cli` 读。插件（plugin / `capabilityClient` / `CapabilityService`）是写进应用代码、由**生成出来的应用在运行时**调用的，不是你的读取工具；多维表格尤其容易混——用户给了 Base 链接要你先读懂再建应用，走 base 域，不要去装插件或生成插件调用代码。反过来，应用本身需要在运行时读写飞书（页面上展示多维表格数据、发飞书通知）才用插件，那部分看 `plugin-guide`。

package/shared/lark-cli/lark-base/README.md

@@ -0,0 +1,56 @@
+# base (v3)
+
+> [!IMPORTANT]
+> - 运行 `lark-cli --version`，确认可用，无需询问用户。
+
+## 身份
+
+base 域命令默认使用 `--as user`。
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+url-resolve`](references/lark-base-commands.md) | 把 Base / Wiki / 记录分享 URL 解析成 `base_token` + 所选块的 `block_type` 与对应 ID |
+| [`+base-get`](references/lark-base-commands.md) | 读 Base 本体元信息 |
+| [`+table-list`](references/lark-base-commands.md) | 列数据表 |
+| [`+field-list`](references/lark-base-commands.md) | 列字段（含类型与选项） |
+| [`+view-list`](references/lark-base-commands.md) | 列视图，按视图名取 `view_id` |
+| [`+view-get`](references/lark-base-commands.md) 及 `+view-get-card` / `+view-get-filter` / `+view-get-group` / `+view-get-sort` / `+view-get-timebar` / `+view-get-visible-fields` | 读视图配置（共 7 个） |
+| [`+record-list`](references/lark-base-commands.md) | 读记录，可按视图 / filter-json / sort-json 取 |
+| [`+record-search`](references/lark-base-commands.md) | 按关键词搜记录（`--keyword`） |
+
+- 使用 Shortcut 前，必须先读 [references/lark-base-commands.md](references/lark-base-commands.md)。
+
+## 先拿 base_token —— 定位规则
+
+**不要把 Base / Wiki URL、wiki token 或孤立 raw token 直接当 `--base-token`。**
+
+| 用户给了什么 | 怎么做 |
+|---|---|
+| Base / Wiki / 记录分享 URL | `lark-cli base +url-resolve --url "<URL>" --as user`，取 `base_token`；**`table_id` 只在返回的 `block_type` 为 `table` 时才可用**（URL 里的 `table=` 是顶层块，可能是仪表盘/workflow/文档，不是数据表 ID）。不是 `table` 就走 `+table-list` 按表名定位。详见 [commands](references/lark-base-commands.md) |
+| 文档里的 `<bitable token="..." table-id="...">` 标签 | 直接把 `token` 当 `base_token`、`table-id` 当 `--table-id`，不用再 `+url-resolve` |
+| 只有 Base 名称或关键词 | 本域没有按名称搜 Base 的能力；改用 [lark-drive](../lark-drive/README.md) 的 `+search --doc-types bitable` 先定位到 URL，再 `+url-resolve` |
+
+`--table-id` / `--view-id` 既接 ID（`tbl...` / `vew...`）也接名称。
+
+## 意图路由
+
+| 用户需求 | 命令 |
+|---|---|
+| 这个 Base 里有哪些表 | `+table-list --base-token <t>` |
+| 这张表有哪些字段、字段类型/选项是什么 | `+field-list --base-token <t> --table-id <tbl>` |
+| 读表里的记录 | `+record-list --base-token <t> --table-id <tbl>` |
+| 只读某个视图筛选后的记录 | `+record-list ... --view-id "<视图名或 vew...>"` |
+| 按关键词搜记录 | `+record-search ... --keyword "<关键词>"` |
+| 只要某几个字段 | 追加 `--field-id <字段名>`（可重复） |
+| 这个视图的筛选/排序/分组/可见字段怎么配的 | `+view-get-filter` / `+view-get-sort` / `+view-get-group` / `+view-get-visible-fields` |
+| Base 叫什么、归谁 | `+base-get --base-token <t>` |
+
+## 分页
+
+`+table-list` 的 `--limit` 范围 1-100（默认 50）；`+field-list` / `+view-list` / `+record-list`
+的 `--limit` 范围 1-200（默认 100）；`+record-search` 的 `--limit` 默认 10。都配 `--offset` 翻页。
+
+结果被 `--limit` 截断时，不要拿这一页的内容回答「一共有多少」「最大的是哪个」这类全局问题，
+先翻完或收窄条件。