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

package/shared/lark-cli/lark-whiteboard/references/lark-whiteboard-export.md

@@ -0,0 +1,59 @@
+# whiteboard +export（导出画板）
+
+导出画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                                                     |
+|----------------------|----|------------------------------------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
+| `--output-type`      | 是  | 输出格式：`preview`（预览图片）、`svg`（SVG 矢量图）、`source`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
+| `--output`           | 否  | 输出路径。当 `--output-type preview` 时必填；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
+| `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
+
+## 输出格式
+
+- `preview`：预览图片。保存时会根据接口实际返回的 `Content-Type` 决定扩展名，例如 `image/jpeg` 会保存为 `.jpg`。
+- `svg`：导出画板为标准 SVG 矢量图。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
+- `source`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
+- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式适合查看画板节点的原始结构，不适合直接编辑复杂布局或内容。
+  - 需要把节点结构交给后续处理时，用 `--output <file>` 写入文件：文件里是裸的节点 JSON；直接输出到终端的结果会多一层 `{ ok, identity, data }` 包装，两者形状不同，别混用。
+
+## 示例
+
+### 示例 1：导出画板为预览图片
+
+```bash
+lark-cli whiteboard +export \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output-type preview \
+  --output ./preview
+```
+
+### 示例 2：提取画板中的代码并直接输出
+
+```bash
+lark-cli whiteboard +export \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output-type source
+```
+
+### 示例 3：导出画板为 SVG 矢量图
+
+```bash
+lark-cli whiteboard +export \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output-type svg \
+  --output ./whiteboard.svg \
+  --as user
+```
+
+### 示例 4：导出画板原始节点结构到文件
+
+```bash
+lark-cli whiteboard +export \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output-type raw \
+  --output ./nodes.json \
+  --overwrite
+```

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

@@ -0,0 +1,50 @@
+# wiki (v2)
+
+## 身份说明
+
+知识空间和节点是用户的个人资源，本 skill 的所有命令统一显式带 `--as user`。`--as` 的默认值是
+`auto`，不显式指定时可能不按用户身份解析，导致列出的是应用可见的空间而非用户自己的；所以下面
+的每条命令与示例都带 `--as user`（`my_library` 个人文档库更是只在 `--as user` 下才有效）。
+
+## 快速决策
+
+- 用户要**按特定主题 / 关键词 / 内容线索查找资料并收集到知识库节点或新建知识库节点下**：先用 Drive 全量搜索召回，再按 Wiki 目标解析、确认和移动；不要只用 Wiki 节点列表做局部遍历。
+- 用户要**整理 / 盘点 / 归类 / 重构知识库、个人文档库、文档库目录或 Wiki 节点结构**，或要生成整理方案、目标目录树、移动计划时，不要只使用 Wiki 节点 API；应先完成 Drive / Wiki / 个人文档库的统一入口解析、资源盘点、分类计划、写前确认和结果验证。
+- 用户给的是知识库 URL（`.../wiki/<token>`）且要查节点详情：用 `lark-cli wiki +node-get --node-token '<url>' --as user --format json` 解析出 `node_token` / `obj_token` / `space_id`。**获取或解析 Wiki 节点统一优先用 `+node-get`**，包括只为拿到 `space_id`、`node_token`、`obj_token`、`obj_type` 的中间步骤——从返回的 `data.space_id` 读空间 ID。只有当任务确实需要 `+node-get` 未输出的原始响应字段时，才回退到 `wiki spaces get_node`（读 `data.node.space_id`），且回退前先跑 `lark-cli schema wiki.spaces.get_node`。节点解析与后续操作必须使用同一身份。
+- 截断的 wiki node token 会被直接拒绝：不要把肉眼截短、复制不全的 token 拼进 `--node-token` 试探，先要回完整 URL 或 token。
+- 用户要列出 Wiki 节点：先用 `lark-cli wiki +space-list --as user` 拿数字 `space_id`，再用 `lark-cli wiki +node-list --space-id <space_id> --as user`。不要把 wiki URL、node token、doc token、名称直接当 `--space-id`。钻子节点时 `--parent-node-token` 必须是 wiki node token；如果用户给的是 docx/sheet/base URL，先用 `lark-cli wiki +node-get --node-token <url> --as user` 解析出 `node_token`。
+- `wiki +node-list` 命中 `invalid_parameters`、`not_found`、`permission_denied` 时，不要重复调用同一参数；按 hint 修 `space_id` / `parent_node_token` / 权限。只有 `rate_limit` 才做退避重试。
+- 用户要**查看 / 列出空间成员**：先拿到数字 `space_id`（见上，用 `+space-list` 或 `+node-get` 解析），再调用 `wiki members list`（先 `lark-cli schema wiki.members.list` 查参数结构，再 `lark-cli wiki members list ... --as user`）；多成员场景按返回的 `page_token` 翻页。这是只读查询，不涉及成员的增删。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用只读查询的高级封装（`lark-cli wiki +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+space-list`](references/lark-wiki-space-list.md) | List all wiki spaces accessible to the caller |
+| [`+node-list`](references/lark-wiki-node-list.md) | List wiki nodes in a space or under a parent node (supports pagination) |
+| [`+node-get`](references/lark-wiki-node-get.md) | Get a wiki node's details by node_token / obj_token / Lark URL |
+
+## API Resources
+
+```bash
+lark-cli schema wiki.<resource>.<method>   # 调用原生 API 前必须先查看 --data / --params 参数结构，不要猜测字段格式
+lark-cli wiki <resource> <method> [flags]  # 调用 API
+```
+
+沙箱里 wiki 域**仅以下只读 API 可用**，不要臆造其它 service/resource/method 组合：
+
+### spaces
+
+- `get` — 获取知识空间信息
+- `get_node` — 获取知识空间节点信息
+- `list` — 获取知识空间列表
+
+### members
+
+- `list` — 获取知识空间成员列表
+
+### nodes
+
+- `list` — 获取知识空间子节点列表

package/shared/lark-cli/lark-wiki/references/lark-wiki-node-get.md

@@ -0,0 +1,59 @@
+# lark-wiki +node-get
+
+Get a wiki node's details by `node_token`, `obj_token`, or a Lark URL. Use this as the "what am I about to touch?" read step before deciding where a node lives.
+
+## Usage
+
+```bash
+lark-cli wiki +node-get \
+  --node-token <node_token | obj_token | Lark URL> \
+  [--obj-type <doc|docx|sheet|bitable|mindnote|slides|file>] \
+  [--space-id <space_id>] \
+  [--format json|pretty|table|csv|ndjson] \
+  [--as user]
+```
+
+## Flags
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--node-token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one (e.g. `https://feishu.cn/wiki/<token>` or `https://feishu.cn/docx/<token>`). |
+| `--token` | string | — (deprecated) | — | Deprecated original name; still accepted for backward compatibility but emits a `Flag --token has been deprecated, use --node-token instead` warning on stderr. New scripts should use `--node-token`. |
+| `--obj-type` | enum | No | — | Needed when `--node-token` is a raw `obj_token`; auto-inferred from typed Lark URLs. If omitted for a raw token, the shortcut treats it as a wiki `node_token`. |
+| `--space-id` | string | No | — | Optional cross-check: fail if the resolved node does not live in this space |
+| `--format` | enum | No | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
+| `--as` | enum | No | `auto` | Identity `user`; wiki is user-centric → always pass `--as user` |
+
+## Output
+
+```json
+{
+  "space_id": "7160145948494381236",
+  "node_token": "wikcnEXAMPLE",
+  "obj_token": "docxEXAMPLE",
+  "obj_type": "docx",
+  "node_type": "origin",
+  "parent_node_token": "wikcnPARENT",
+  "origin_node_token": "",
+  "title": "Design Spec",
+  "has_child": true,
+  "creator": "ou_xxx",
+  "owner": "ou_yyy",
+  "obj_edit_time": "1700000000",
+  "obj_create_time": "1690000000",
+  "node_create_time": "1690000001",
+  "updated_at": "2023-11-14T22:13:20Z"
+}
+```
+
+## Notes
+
+- The underlying API is `GET /open-apis/wiki/v2/spaces/get_node`. For a `node_token` no `obj_type` is sent; for an `obj_token` the `obj_type` (explicit or URL-inferred) is required.
+- `creator` falls back to `creator` when `node_creator` is absent. `updated_at` is `obj_edit_time` formatted as RFC3339.
+- No `url` is returned: `get_node` does not provide one and a synthesized `www.feishu.cn/wiki/<node_token>` link is non-canonical/misleading for a read command. Use `node_token` / `obj_token` as the identifiers.
+- Prefer this shortcut over the raw `wiki spaces get_node` API for every node-resolution step, including when you only need `space_id` — read it from `data.space_id` (the raw API nests it under `data.node.space_id`).
+- A truncated `node_token` is rejected outright rather than sent as a lookup. If the token you were given looks cut off, ask for the full URL or token instead of retrying variants.
+
+## Required Scope
+
+`wiki:node:retrieve`

package/shared/lark-cli/lark-wiki/references/lark-wiki-node-list.md

@@ -0,0 +1,95 @@
+# lark-wiki +node-list
+
+List wiki nodes in a space or under a specific parent node. **Default fetches a single page** (large knowledge bases can have thousands of nodes — opt into `--page-all` explicitly with an eye on `--page-limit`).
+
+## Usage
+
+```bash
+# Default: single page of root nodes
+lark-cli wiki +node-list --space-id <SPACE_ID> --as user
+
+# Drill into a sub-directory (still single page by default)
+lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token <NODE_TOKEN> --as user
+
+# Drill with a wiki URL (CLI normalizes /wiki/<token> to node_token)
+lark-cli wiki +node-list --space-id <SPACE_ID> --parent-node-token "https://feishu.cn/wiki/wikcn_xxx" --as user
+
+# Personal document library (user identity only)
+lark-cli wiki +node-list --space-id my_library --as user
+
+# Walk every page (capped by --page-limit, default 10)
+lark-cli wiki +node-list --space-id <SPACE_ID> --page-all --as user
+
+# Walk every page with a higher cap
+lark-cli wiki +node-list --space-id <SPACE_ID> --page-all --page-limit 30 --as user
+
+# Resume from a cursor
+lark-cli wiki +node-list --space-id <SPACE_ID> --page-token <TOKEN> --as user
+
+# Pretty / table output
+lark-cli wiki +node-list --space-id <SPACE_ID> --format pretty --as user
+```
+
+## Flags
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--space-id` | string | **Yes** | — | Numeric wiki space ID. Use `my_library` for personal document library (user only) |
+| `--parent-node-token` | string | No | — | Parent wiki node token, or a `/wiki/<token>` URL; omit to list the space root |
+| `--page-size` | int | No | 50 | Page size, 1-50 |
+| `--page-token` | string | No | — | Page cursor; implies single-page fetch (no auto-pagination) |
+| `--page-all` | bool | No | `false` | Automatically paginate through all pages (capped by `--page-limit`) |
+| `--page-limit` | int | No | 10 | Max pages with `--page-all` (0 = unlimited) |
+| `--format` | enum | No | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
+| `--as` | enum | No | `auto` | Identity `user`; wiki is user-centric → always pass `--as user` (`my_library` requires `--as user`) |
+
+## Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "nodes": [
+      {
+        "space_id": "6946843325487912356",
+        "node_token": "wikcn_EXAMPLE_TOKEN",
+        "obj_token": "doccn_EXAMPLE_TOKEN",
+        "obj_type": "docx",
+        "parent_node_token": "",
+        "node_type": "origin",
+        "title": "Getting Started",
+        "has_child": true
+      }
+    ],
+    "has_more": false,
+    "page_token": ""
+  },
+  "meta": { "count": 1 }
+}
+```
+
+When the default single-page fetch (or `--page-all` capped by `--page-limit`) does not exhaust the upstream cursor, `has_more=true` and `page_token=<cursor>` so the caller can resume via `--page-token` or by increasing `--page-limit`.
+
+## Traverse the wiki tree
+
+To list all content recursively, call `+node-list` again with each node's `node_token` as `--parent-node-token` when `has_child` is `true`.
+
+```bash
+# Step 1: list root nodes
+lark-cli wiki +node-list --space-id 6946843325487912356 --as user
+
+# Step 2: drill into a node that has children
+lark-cli wiki +node-list --space-id 6946843325487912356 --parent-node-token wikcn_EXAMPLE_TOKEN --as user
+```
+
+## Notes
+
+- `--space-id my_library` is a per-user alias and only valid with `--as user`.
+- `--space-id` is a numeric wiki `space_id`. Do not pass a wiki URL, wiki node token, document token, or title. Use `lark-cli wiki +space-list --as user` to discover it.
+- `--parent-node-token` must resolve to a wiki node token. If you have a docx/sheet/base/file URL, first run `lark-cli wiki +node-get --node-token <url> --as user` and use the returned `node_token`.
+- Treat `invalid_parameters` (`space_id is not int`, `invalid page_token`), `not_found` (`node not found by parent node token`), and `permission_denied` as terminal for the current arguments. Fix the argument or permission before retrying.
+- For `rate_limit`, stop immediate retries and retry later with exponential backoff or a smaller `--page-limit`.
+
+## Required Scope
+
+`wiki:node:retrieve`

package/shared/lark-cli/lark-wiki/references/lark-wiki-space-list.md

@@ -0,0 +1,68 @@
+# lark-wiki +space-list
+
+List wiki spaces accessible to the caller. **Default fetches a single page** (matches the rest of the CLI's list shortcuts); pass `--page-all` to walk every page.
+
+## Usage
+
+```bash
+# Default: single page (first up to --page-size items)
+lark-cli wiki +space-list --as user
+
+# Walk every page (capped by --page-limit, default 10)
+lark-cli wiki +space-list --page-all --as user
+
+# Walk every page, no cap (use with care if you have many spaces)
+lark-cli wiki +space-list --page-all --page-limit 0 --as user
+
+# Resume from a specific cursor (single-page fetch regardless of --page-all)
+lark-cli wiki +space-list --page-token <TOKEN> --as user
+
+# Pretty / table / csv / ndjson output
+lark-cli wiki +space-list --format pretty --as user
+lark-cli wiki +space-list --format table --as user
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--page-size` | int | 50 | Page size, 1-50 |
+| `--page-token` | string | — | Page cursor; implies single-page fetch (no auto-pagination) |
+| `--page-all` | bool | `false` | Automatically paginate through all pages (capped by `--page-limit`) |
+| `--page-limit` | int | 10 | Max pages with `--page-all` (0 = unlimited) |
+| `--format` | enum | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
+| `--as` | enum | `auto` | Identity `user`; wiki is user-centric → always pass `--as user` |
+
+## Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "spaces": [
+      {
+        "space_id": "6946843325487912356",
+        "name": "Engineering Wiki",
+        "description": "...",
+        "space_type": "team",
+        "visibility": "private",
+        "open_sharing": "closed"
+      }
+    ],
+    "has_more": false,
+    "page_token": ""
+  },
+  "meta": { "count": 1 }
+}
+```
+
+When the default single-page fetch (or `--page-all` capped by `--page-limit`) does not exhaust the upstream cursor, `has_more=true` and `page_token=<cursor>` so the caller can resume via `--page-token` or by increasing `--page-limit`.
+
+## Notes
+
+- **The underlying API never returns the my_library personal library**; resolve it via `lark-cli wiki spaces get --params '{"space_id":"my_library"}' --as user`.
+- Use `space_id` from the output as `--space-id` for `+node-list`.
+
+## Required Scope
+
+`wiki:space:retrieve`

package/miaoda-design/attachment/SKILL.md

@@ -1,58 +0,0 @@
----
-name: attachment
-description: "Use when user mentions attachments, uploaded files, or shared files. Handles preprocessing: listing, extracting archives, and reading files in .agent/{conversation_id}/attachments directory."
----
-
-# Attachment Preprocessing
-
-Preprocess user-uploaded attachments to make them accessible for subsequent workflows.
-
-**Important**: This skill only handles attachment preprocessing (listing, extracting, reading). Subsequent processing workflows should be determined based on the extracted file contents.
-
-## Storage Location
-
-```text
-.agent/{conversation_id}/attachments/
-```
-
-## Preprocessing Steps
-
-### 1. List Attachments
-
-```bash
-ls -la .agent/{conversation_id}/attachments/
-```
-
-### 2. Handle Archives
-
-For `.zip` and other archive files, preview first then extract:
-
-```bash
-# Preview contents
-unzip -l .agent/{conversation_id}/attachments/archive.zip
-
-# Extract in place
-unzip -o .agent/{conversation_id}/attachments/archive.zip -d .agent/{conversation_id}/attachments/
-```
-
-### 3. Read Files
-
-Use the Read tool to read text file contents.
-
-## What Happens Next
-
-After preprocessing, **determine subsequent processing based on file contents**:
-
-- Code files → May need analysis, refactoring, or project integration
-- Config files → May need to apply to project configuration
-- Data files → May need data analysis or visualization
-- Image files → May need to copy to project resource directories
-- Document files → May need reading, comprehension, or information extraction
-
-**This skill does not prescribe specific processing methods** — determine based on user intent and file contents.
-
-## Notes
-
-- All operations are confined to `.agent/{conversation_id}/attachments/` directory
-- Use `offset` and `limit` parameters when reading large files
-- Attachments may be cleaned up after conversation ends