@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-whiteboard-cli/scenes/treemap.md

@@ -0,0 +1,210 @@
+# 矩形树图 (Treemap)
+
+## Content 约束
+
+- 分类 3-5 个，每个分类下子项 2-4 个
+- 总面积比例需预先计算：每个矩形面积 = 父矩形面积 * (本项数值 / 同级总数值)
+- 每个叶子节点标签必须包含数值（如 "{{LABEL}} ({{VALUE}})"）
+
+## Layout 选型
+
+- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .js 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
+- 不适合手动心算坐标
+
+## Layout 规则
+
+- 使用交替切分法（Slice-and-Dice）：奇数层水平切分 width，偶数层垂直切分 height
+- 父矩形内必须为标题预留 30-40px 顶部空间，子矩形从 y + 35 开始放置
+- 子节点必须完全落在父矩形范围内
+- 水平切分时：子 width = 父 width * (子数值 / 父总数值)，子 x 依次累加
+- 垂直切分时：子 height = (父 height - 35) * (子数值 / 父总数值)，子 y 依次累加（注意扣除父标签预留的 35px）
+
+### 面积比例计算规则
+
+1. **面积与数值严格成正比**：任何层级的节点，其矩形面积 `width * height` 必须与数值成比例
+2. **奇数层水平切分**（如第一层分类）：
+   - 父矩形的 `height` 和 `y` 坐标传给所有子节点（扣除标签预留空间后）
+   - 按子节点数值占父节点的比例切分父矩形的 `width`：`子width = 父width * (子数值 / 父总数值)`
+   - 子节点的 `x` 坐标依次向右累加
+3. **偶数层垂直切分**（如第二层子项）：
+   - 父矩形的 `width` 和 `x` 坐标传给所有子节点
+   - 按子节点数值占父节点的比例切分父矩形的 `height`：`子height = 父height * (子数值 / 父总数值)`
+   - 子节点的 `y` 坐标依次向下累加
+4. **层层递归**：不断交替水平和垂直切分方向，直到所有叶子节点都被分配了精确的坐标和宽高
+
+### 父标签预留空间
+
+每个非叶子节点的矩形，顶部必须预留 30-40px 放置分类标签。子矩形从父矩形的 `y + 35` 开始放置，可用高度为 `父height - 35`。
+
+示例：父矩形 `{ x: 40, y: 40, height: 700 }`，则：
+- 父标签放在 `y: 46`（留 6px 上边距）
+- 子矩形从 `y: 75` 开始放置（40 + 35）
+- 子矩形可用高度为 `700 - 35 = 665`
+
+## 骨架示例
+
+2 层 treemap：3 个分类（硬件 40、软件 35、服务 25），各含 2 个子项。
+
+根矩形 1100x700，第一层水平切分 width，第二层垂直切分 height。
+
+```json
+{
+  "version": 2,
+  "nodes": [
+    {
+      "type": "rect",
+      "id": "root",
+      "x": 40, "y": 40,
+      "width": 1100, "height": 700,
+      "borderWidth": 2, "borderRadius": 6
+    },
+    {
+      "type": "text",
+      "x": 48, "y": 46,
+      "width": 1084, "height": 24,
+      "text": "{{ROOT_TITLE}}",
+      "fontSize": 14
+    },
+
+    {
+      "type": "rect",
+      "id": "cat-A",
+      "x": 40, "y": 75,
+      "width": 440, "height": 665,
+      "borderWidth": 2, "borderRadius": 6
+    },
+    {
+      "type": "text",
+      "x": 48, "y": 81,
+      "width": 424, "height": 24,
+      "text": "{{CAT_A}}",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-A-item-1",
+      "x": 40, "y": 110,
+      "width": 440, "height": 380,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 48, "y": 116,
+      "width": 424, "height": 24,
+      "text": "{{ITEM_A1}} (24)",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-A-item-2",
+      "x": 40, "y": 490,
+      "width": 440, "height": 250,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 48, "y": 496,
+      "width": 424, "height": 24,
+      "text": "{{ITEM_A2}} (16)",
+      "fontSize": 14
+    },
+
+    {
+      "type": "rect",
+      "id": "cat-B",
+      "x": 480, "y": 75,
+      "width": 385, "height": 665,
+      "borderWidth": 2, "borderRadius": 6
+    },
+    {
+      "type": "text",
+      "x": 488, "y": 81,
+      "width": 369, "height": 24,
+      "text": "{{CAT_B}}",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-B-item-1",
+      "x": 480, "y": 110,
+      "width": 385, "height": 380,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 488, "y": 116,
+      "width": 369, "height": 24,
+      "text": "{{ITEM_B1}} (20)",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-B-item-2",
+      "x": 480, "y": 490,
+      "width": 385, "height": 285,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 488, "y": 496,
+      "width": 369, "height": 24,
+      "text": "{{ITEM_B2}} (15)",
+      "fontSize": 14
+    },
+
+    {
+      "type": "rect",
+      "id": "cat-C",
+      "x": 865, "y": 75,
+      "width": 275, "height": 665,
+      "borderWidth": 2, "borderRadius": 6
+    },
+    {
+      "type": "text",
+      "x": 873, "y": 81,
+      "width": 259, "height": 24,
+      "text": "{{CAT_C}}",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-C-item-1",
+      "x": 865, "y": 110,
+      "width": 275, "height": 399,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 873, "y": 116,
+      "width": 259, "height": 24,
+      "text": "{{ITEM_C1}} (15)",
+      "fontSize": 14
+    },
+    {
+      "type": "rect",
+      "id": "cat-C-item-2",
+      "x": 865, "y": 509,
+      "width": 275, "height": 231,
+      "borderRadius": 4
+    },
+    {
+      "type": "text",
+      "x": 873, "y": 515,
+      "width": 259, "height": 24,
+      "text": "{{ITEM_C2}} (10)",
+      "fontSize": 14
+    }
+  ]
+}
+```
+
+面积比例验证（第一层水平切分 width）：
+- 硬件 40/100 * 1100 = 440，软件 35/100 * 1100 = 385，服务 25/100 * 1100 = 275
+- 子矩形从 y=75 开始，可用高度 665
+
+## 陷阱
+
+- **父标签被子矩形遮挡**（最严重）：子矩形必须从 y + 35（相对父矩形顶部）开始放置，为父分类标签留出空间
+- **分类标签不可见**：分类标签 text 节点必须在其子矩形 rect 节点之前添加（z-index 靠后的节点在上层）
+- **面积比例不正确**：必须用脚本预先计算比例，不要心算
+- **缺少配色区分**：不同顶层分类必须用不同背景色（从色板选取），所有子节点继承对应色系

package/server/assets/skills/lark-tools/cli-skills/lark-wiki/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: lark-wiki
+version: 1.0.0
+description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli wiki --help"
+---
+
+# wiki (v2)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+> **成员管理硬限制：**
+> - 如果目标是“部门”，先判断身份，再决定是否继续。
+> - `--as bot` 对应 `tenant_access_token`。官方限制：这种身份下不能使用部门 ID (`opendepartmentid`) 添加知识空间成员。
+> - 遇到“部门 + --as bot”时，禁止先调用 `lark-cli wiki members create` 试错；直接说明该路径不可行。
+> - 如果用户明确要求“以 bot 身份运行”，且目标是部门，必须停下说明 bot 路径无法完成，不要静默切到 `--as user`。
+
+## 快速决策
+
+- 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
+- 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
+- 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门”三类之一，再决定 `member_type`，不要先调 `wiki members create` 再根据报错反推类型。
+- 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki members create --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。
+- 用户说“用户 / 群 + 添加成员”：先解析对应 ID，再执行 `wiki members create`。
+
+## 成员添加流程
+
+- 调用 `lark-cli wiki members create` 前，先把自然语言里的“人 / 群 / 部门”解析成正确的 `member_id`，不要猜格式。
+- 用户场景默认优先 `member_type=openid`：用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --format json` 获取 `open_id`。
+- 群组场景使用 `member_type=openchat`：用 `lark-cli im +chat-search --query "<群名关键词>" --format json` 获取 `chat_id`。
+- `userid` / `unionid` 只在下游明确要求时才使用；先拿到 `open_id`，再调用 `lark-cli api GET /open-apis/contact/v3/users/<open_id> --params '{"user_id_type":"open_id"}' --format json` 读取 `user_id` / `union_id`。
+- 部门场景使用 `member_type=opendepartmentid`：当前 CLI 没有 shortcut，需调用 `lark-cli api POST /open-apis/contact/v3/departments/search --as user --params '{"department_id_type":"open_department_id"}' --data '{"query":"<部门名>"}'` 获取 `open_department_id`。
+- 只有在目标类型和身份都已确认可行后，才调用 `lark-cli wiki members create`。对于部门场景，这意味着必须是 `--as user`。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+move`](references/lark-wiki-move.md) | Move a wiki node, or move a Drive document into Wiki |
+| [`+node-create`](references/lark-wiki-node-create.md) | Create a wiki node with automatic space resolution |
+
+## 目标语义约束
+
+- `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
+- 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
+- 不要因为缺少显式 `space_id` 就退化成 `drive +move`
+- 如果用户明确说的是 Drive 文件夹、云空间根目录、`我的空间`，才进入 Drive 域处理
+
+## API Resources
+
+```bash
+lark-cli schema wiki.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli wiki <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### spaces
+
+- `get` — 获取知识空间信息
+- `get_node` — 获取知识空间节点信息
+- `list` — 获取知识空间列表
+
+### members
+
+- `create` — 添加知识空间成员
+- `delete` — 删除知识空间成员
+- `list` — 获取知识空间成员列表
+
+### nodes
+
+- `copy` — 创建知识空间节点副本
+- `create` — 创建知识空间节点
+- `list` — 获取知识空间子节点列表
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `spaces.get` | `wiki:space:read` |
+| `spaces.get_node` | `wiki:node:read` |
+| `spaces.list` | `wiki:space:retrieve` |
+| `members.create` | `wiki:member:create` |
+| `members.delete` | `wiki:member:update` |
+| `members.list` | `wiki:member:retrieve` |
+| `nodes.copy` | `wiki:node:copy` |
+| `nodes.create` | `wiki:node:create` |
+| `nodes.list` | `wiki:node:retrieve` |

package/server/assets/skills/lark-tools/cli-skills/lark-wiki/references/lark-wiki-move.md

@@ -0,0 +1,183 @@
+# wiki +move
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在飞书知识库中移动已有 Wiki 节点，或将 Drive 文档迁入 Wiki。这个 shortcut 统一封装了两类流程：
+
+- `node` 模式：移动已有 Wiki 节点，可同空间移动，也可跨空间移动
+- `docs_to_wiki` 模式：把 Drive 文档迁入目标知识空间；必要时可提交移动申请，并在异步任务场景下自动有限轮询
+
+当 `docs_to_wiki` 返回 `task_id` 时，shortcut 会先轮询一小段时间；如果轮询窗口内仍未完成，会返回 `next_command`，让调用方继续执行 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>`。
+
+## 与 `drive +move` 的区别
+
+- `wiki +move` 的目标是 **知识空间或 Wiki 父节点**，使用 `--target-space-id` / `--target-parent-token`
+- `drive +move` 的目标是 **Drive 文件夹**，使用 `--folder-token`
+- 如果源对象已经是 Wiki 节点，必须使用 `wiki +move`，而不是 `drive +move`
+- 如果源对象还是 Drive 文档，但用户要“迁入知识库”“挂到某个 Wiki 页面下”，也应使用 `wiki +move`
+- 如果用户只是想整理云空间文件夹，把文件/文件夹挪到另一个 Drive 文件夹，应使用 `drive +move`
+
+## 口语目标识别
+
+- 当用户说“移动到某个知识库”“挂到某个页面下”“迁入 Wiki”时，按 **Wiki 目标** 处理，优先使用 `wiki +move`
+- 当用户说“移动到某个文件夹”“移动到云空间根目录”时，按 **Drive 文件夹目标** 处理，优先使用 `drive +move`
+- 当用户说“移动到我的文档库”“移动到我的知识库”“放到个人知识库”时，应先按 **Wiki 个人知识库目标** 理解，而不是直接退化成 `drive +move`
+- 遇到“我的文档库”这类表述时，可以把它理解成：先用 `my_library` 去查询用户个人知识库，再拿到真实 `space_id`
+- 推荐做法是先执行 `lark-cli wiki spaces get --params '{"space_id":"my_library"}'`，取回真实知识库 `space_id`，再把这个 `space_id` 用到 `wiki +move`
+- 当前 `wiki +move` 文档的主示例仍以显式 `--target-space-id` / `--target-parent-token` 为主；如果调用方只有自然语言目标，不要因为目标暂时不明确就改走 `drive +move`
+
+## 命令
+
+```bash
+# 将已有 wiki 节点移动到另一个父节点下
+lark-cli wiki +move \
+  --node-token <NODE_TOKEN> \
+  --target-parent-token <TARGET_PARENT_TOKEN>
+
+# 将已有 wiki 节点移动到另一个知识空间根目录
+lark-cli wiki +move \
+  --node-token <NODE_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID>
+
+# 将 Drive 文档迁入某个知识空间根目录
+lark-cli wiki +move \
+  --obj-type docx \
+  --obj-token <DOC_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID>
+
+# 将 Drive 文档迁入某个父节点下；如果当前没有直接移动权限，则提交申请
+lark-cli wiki +move \
+  --obj-type sheet \
+  --obj-token <SHEET_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID> \
+  --target-parent-token <TARGET_PARENT_TOKEN> \
+  --apply
+
+# 预览底层调用链
+lark-cli wiki +move \
+  --obj-type docx \
+  --obj-token <DOC_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID> \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--node-token` | 条件必填 | 要移动的 Wiki 节点 token。传入后命令进入 `node` 模式 |
+| `--source-space-id` | 否 | 源知识空间 ID，仅 `node` 模式可用；不传时会根据 `--node-token` 自动解析 |
+| `--target-space-id` | 条件必填 | 目标知识空间 ID。`docs_to_wiki` 模式必填；`node` 模式下如果不传，则必须传 `--target-parent-token` |
+| `--target-parent-token` | 否 | 目标父节点 token。`docs_to_wiki` 不传时表示迁入目标知识空间根目录 |
+| `--obj-type` | 条件必填 | Drive 文档类型，仅 `docs_to_wiki` 模式可用。可选值：`doc`、`sheet`、`bitable`、`mindnote`、`docx`、`file`、`slides` |
+| `--obj-token` | 条件必填 | Drive 文档 token，仅 `docs_to_wiki` 模式可用 |
+| `--apply` | 否 | 仅 `docs_to_wiki` 模式可用；当当前调用方不能直接移动文档时，提交一个 move request |
+
+## 模式选择与校验规则
+
+- **`node` 模式**：只要传了 `--node-token`，就会按“移动已有 Wiki 节点”执行
+- **`docs_to_wiki` 模式**：未传 `--node-token` 时，按“把 Drive 文档迁入 Wiki”执行
+- `node` 模式下，`--node-token` 不能与 `--obj-type`、`--obj-token`、`--apply` 同时使用
+- `node` 模式下，`--target-parent-token` 和 `--target-space-id` 不能同时为空
+- `docs_to_wiki` 模式下，必须同时提供 `--obj-type`、`--obj-token`、`--target-space-id`
+- `docs_to_wiki` 模式下，`--source-space-id` 非法，只能用于 `node` 模式
+
+## 空间解析与一致性校验
+
+### `node` 模式
+
+- **源空间解析**：如果未传 `--source-space-id`，shortcut 会先调用 `GET /open-apis/wiki/v2/spaces/get_node` 查询 `--node-token`，再读取其 `space_id`
+- **目标父节点解析**：如果传了 `--target-parent-token`，shortcut 会先解析该父节点所属的 `space_id`
+- **一致性校验**：如果同时传了 `--target-space-id` 和 `--target-parent-token`，shortcut 会校验两者是否属于同一个知识空间；不一致时直接返回验证错误
+- **移动到空间根目录**：如果只传 `--target-space-id`，则表示移动到该知识空间根目录
+
+### `docs_to_wiki` 模式
+
+- `--target-space-id` 始终必填
+- `--target-parent-token` 可选；不传时表示移动到目标知识空间根目录
+- 请求体会自动映射成 `obj_type`、`obj_token`、`parent_wiki_token`、`apply`
+
+## 行为说明
+
+- **`node` 模式是同步操作**：请求成功后直接返回移动后的节点信息
+- **`docs_to_wiki` 可能是同步，也可能是异步**：
+  - 如果接口直接返回 `wiki_token`，shortcut 会立刻返回 `ready=true`
+  - 如果接口返回 `applied=true`，shortcut 会返回 `ready=false`、`failed=false`、`applied=true` 和 `status_msg="move request submitted for approval"`
+  - 如果接口返回 `task_id`，shortcut 会先进入有限轮询
+- **有限轮询窗口**：固定最多轮询 `30` 次，每次间隔 `2` 秒
+- **轮询超时不是失败**：如果轮询窗口结束任务仍在处理中，会返回 `task_id`、`status`、`status_msg`、`ready=false`、`timed_out=true` 和 `next_command`
+- **继续查询**：看到 `next_command` 后，改用 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>` 继续查
+- **任务失败直接报错**：如果轮询期间任务进入失败态，shortcut 会直接返回错误，不会再输出 `ready=false` 结果
+- **轮询请求全部失败时也直接报错**：如果任务已创建，但后续每一次状态查询都失败，shortcut 会返回带 hint 的错误，并给出继续查询命令
+
+## 返回结果
+
+### `node` 模式典型返回
+
+```json
+{
+  "mode": "node",
+  "source_space_id": "space_src",
+  "target_space_id": "space_dst",
+  "space_id": "space_dst",
+  "node_token": "wikcnode_xxx",
+  "obj_token": "doccn_xxx",
+  "obj_type": "docx",
+  "parent_node_token": "wikcparent_xxx",
+  "node_type": "origin",
+  "origin_node_token": "",
+  "title": "项目计划",
+  "has_child": false
+}
+```
+
+### `docs_to_wiki` 异步超时返回
+
+```json
+{
+  "mode": "docs_to_wiki",
+  "obj_type": "docx",
+  "obj_token": "doccn_xxx",
+  "target_space_id": "space_xxx",
+  "target_parent_token": "wikcparent_xxx",
+  "task_id": "7500000000000000001",
+  "ready": false,
+  "failed": false,
+  "status": 1,
+  "status_msg": "processing",
+  "timed_out": true,
+  "next_command": "lark-cli drive +task_result --scenario wiki_move --task-id 7500000000000000001"
+}
+```
+
+**输出字段说明：**
+
+- `mode`：当前执行模式，值为 `node` 或 `docs_to_wiki`
+- `ready`：任务是否已经完成并可直接继续使用结果
+- `failed`：任务是否已失败
+- `task_id`：异步任务 ID，仅异步场景返回
+- `status` / `status_msg`：异步任务的主状态码和可读状态
+- `wiki_token`：docs-to-wiki 成功后返回的 Wiki 节点 token；同时也会镜像到 `node_token`
+- `space_id`、`node_token`、`obj_token`、`obj_type`、`parent_node_token`、`title` 等：成功拿到节点信息时返回，方便下游继续调用
+
+## dry-run 编排
+
+- `node` 模式下，dry-run 会根据是否需要解析源节点 / 目标父节点，展示 1 到 3 步的调用链
+- `docs_to_wiki` 模式下，dry-run 会展示两步：
+  1. `POST /open-apis/wiki/v2/spaces/{target_space_id}/nodes/move_docs_to_wiki`
+  2. `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=move`
+
+## 权限说明
+
+CLI 会在执行前做本地 scope 预检查；当前 shortcut 声明的权限为 `wiki:node:move`、`wiki:node:read`、`wiki:space:read`（分别覆盖 move 写操作、节点解析读操作、以及异步任务轮询读操作）。如果本地 token 已记录 scopes 且缺失任一权限，命令会直接提示重新执行 `lark-cli auth login --scope ...`。
+
+当异步任务超时后，后续 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>` 只需要 `wiki:space:read` 权限。
+
+> [!CAUTION]
+> `wiki +move` 是**写入操作**。执行前必须确认用户意图，以及目标节点 / 目标知识空间是否明确。
+
+## 参考
+
+- [lark-wiki](../SKILL.md) -- 知识库全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [drive +task_result](../../lark-drive/references/lark-drive-task-result.md) -- docs-to-wiki 异步任务的续跑查询命令

package/server/assets/skills/lark-tools/cli-skills/lark-wiki/references/lark-wiki-node-create.md

@@ -0,0 +1,127 @@
+# wiki +node-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在飞书知识库中创建一个新节点，并自动解析目标知识空间。该 shortcut 对原生 `wiki.nodes.create` 做了一层更适合日常使用的封装：可以直接指定 `space_id`，也可以从父节点自动反查所属空间；在 `user` 身份下，如果同时省略 `--space-id` 和 `--parent-node-token`，还会自动回退到个人知识库 `my_library`。
+
+## 命令
+
+```bash
+# 在个人知识库根目录下创建一个 docx 节点（user 身份默认回退到 my_library）
+lark-cli wiki +node-create \
+  --title "项目计划"
+
+# 在指定知识空间中创建一个 docx 节点
+lark-cli wiki +node-create \
+  --space-id <SPACE_ID> \
+  --title "项目计划"
+
+# 在指定父节点下创建一个子节点
+lark-cli wiki +node-create \
+  --parent-node-token <PARENT_NODE_TOKEN> \
+  --title "迭代记录"
+
+# 显式指定创建到个人知识库（仅 user 身份；bot 不支持 `--space-id my_library`）
+lark-cli wiki +node-create \
+  --space-id my_library \
+  --title "学习笔记"
+
+# 创建一个快捷方式节点（shortcut）
+lark-cli wiki +node-create \
+  --parent-node-token <PARENT_NODE_TOKEN> \
+  --node-type shortcut \
+  --origin-node-token <ORIGIN_NODE_TOKEN> \
+  --title "原文档快捷方式"
+
+# 创建非 docx 类型节点
+lark-cli wiki +node-create \
+  --space-id <SPACE_ID> \
+  --obj-type sheet \
+  --title "周报数据"
+
+# 预览底层调用链
+lark-cli wiki +node-create \
+  --title "Roadmap" \
+  --dry-run
+```
+
+## 返回值
+
+成功后会返回一个 JSON 对象，常见字段包括：
+
+- `resolved_space_id`：最终用于创建的真实知识空间 ID
+- `resolved_by`：空间解析来源，可能是 `explicit_space_id`、`parent_node_token`、`my_library`
+- `node_token`：新建知识库节点 token
+- `obj_token`：节点关联对象 token
+- `obj_type`：节点关联对象类型
+- `node_type`：节点类型
+- `title`：节点标题
+- `permission_grant`（可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 如果节点是**以应用身份（bot）创建**的，如 `lark-cli wiki +node-create --as bot`，在创建成功后 CLI 会**尝试为当前 CLI 用户自动授予该知识库节点的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该知识库节点的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：节点已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该节点
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--space-id` | 否 | 目标知识空间 ID；`user` 身份可传特殊值 `my_library` 表示个人知识库，`bot` 身份不支持该值 |
+| `--parent-node-token` | 否 | 父知识库节点 token；传入后会在该节点下创建新节点 |
+| `--title` | 否 | 节点标题 |
+| `--node-type` | 否 | 节点类型，默认 `origin`；可选值：`origin`、`shortcut` |
+| `--obj-type` | 否 | 节点对应对象类型，默认 `docx`；可选值：`sheet`、`mindnote`、`bitable`、`docx`、`slides` |
+| `--origin-node-token` | 否 | 当 `--node-type=shortcut` 时必填，表示快捷方式指向的源节点 token |
+
+## 空间解析规则
+
+- **优先级**：`--space-id` > `--parent-node-token` > `my_library`
+- **显式 space**：传了 `--space-id` 时，shortcut 会直接使用该空间；如果该值是 `my_library`，则仅 `user` 身份可用，并会先调用 `GET /open-apis/wiki/v2/spaces/my_library` 解析成真实 `space_id`
+- **父节点推断**：未传 `--space-id` 但传了 `--parent-node-token` 时，会先调用 `GET /open-apis/wiki/v2/spaces/get_node` 获取父节点，再读取其 `space_id`
+- **个人知识库回退**：`user` 身份下，如果 `--space-id` 和 `--parent-node-token` 都没传，会自动解析 `my_library`
+- **bot 身份限制**：`bot` 身份既没有“个人知识库”回退语义，也不支持显式传 `--space-id my_library`；请改用真实 `space_id` 或 `--parent-node-token`
+
+## shortcut 节点规则
+
+- `--node-type=shortcut` 时，必须同时提供 `--origin-node-token`
+- `--node-type=origin` 时，不能传 `--origin-node-token`
+- `shortcut` 节点只是知识库中的快捷方式入口；真正被引用的节点由 `--origin-node-token` 指定
+
+## 一致性校验
+
+- 如果同时传了 `--space-id` 和 `--parent-node-token`，shortcut 会校验父节点所属空间是否与 `--space-id` 一致
+- 如果两者解析出的空间不一致，命令会直接返回验证错误，而不会继续创建
+- 对于 `my_library`，`user` 身份下也会先解析出真实 `space_id` 后再做这层校验
+
+## 行为说明
+
+- **默认对象类型**：不传 `--obj-type` 时默认创建 `docx` 节点
+- **默认节点类型**：不传 `--node-type` 时默认创建普通节点 `origin`
+- **dry-run 编排**：
+  - 仅传 `--title`：会展示 `my_library` 解析 + 创建节点 两步调用
+  - 仅传 `--parent-node-token`：会展示“查询父节点 -> 创建节点”两步调用
+  - 同时需要 `my_library` 和父节点时：会展示三步调用链
+- **bot 自动授权**：若使用 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予新建节点的可管理权限
+- **输出结果**：成功后会返回 `resolved_space_id`、`resolved_by`、`node_token`、`obj_token`、`obj_type`、`node_type`、`title` 等字段，便于后续继续操作
+
+## 推荐场景
+
+- 用户说“在我的知识库里新建一篇页面”时，优先用 `lark-cli wiki +node-create --title "..."`
+- 用户已经给出父页面链接或 `parent_node_token` 时，优先传 `--parent-node-token`，让 shortcut 自动推导空间
+- 需要创建知识库快捷方式时，使用 `--node-type shortcut --origin-node-token <token>`
+
+> [!CAUTION]
+> `wiki +node-create` 是**写入操作**，执行前必须确认用户意图。
+
+## 参考
+
+- [lark-wiki](../SKILL.md) -- 知识库全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数