@amaster.ai/pi-lark 0.1.7 → 0.1.9

package/skills/lark-whiteboard/references/lark-whiteboard-update.md

@@ -17,7 +17,7 @@
 |----------------------|----|--------------------------------------------|
 | `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
 | `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等；最少 10 个字符，建议使用时间戳 + 场景标识拼接（如 `1744800000-board-1`）。同一次逻辑更新只生成一次该 token，重试时须原样复用；切勿在每次重试时重新生成时间戳或幂等 key，否则会重复写入 |
-| `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
+| `--overwrite`        | 否  | 写入模式：带上则覆盖更新（写入前删除画板所有现有内容再写入）；省略则为增量追加（保留原有内容，新内容叠加写入）。默认 false（增量追加）|
 | `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
 | `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw`  |
 
@@ -27,7 +27,7 @@
 
 思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
 
-而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
+而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
 
 ## 示例
 
@@ -71,7 +71,7 @@ lark-cli whiteboard +update \
 
 ### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
 
-whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板)
 
 ```bash
 # 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
@@ -85,7 +85,7 @@ npx -y @larksuite/whiteboard-cli@^0.2.13 -i <产物文件> --to openapi --format
 
 ### 示例 4：先生成产物文件，再从文件读取更新
 
-whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板)
 
 ```bash
 # 生成 OpenAPI 格式到文件

package/skills/lark-whiteboard/references/lark-whiteboard-workflow.md

@@ -1,4 +1,4 @@
-# 画板创作/修改工作流
+# 画板创作/编辑工作流
 
 ## 创作 Workflow
 
@@ -19,23 +19,24 @@
 
 ---
 
-## 修改 Workflow
+## 编辑 Workflow
 
 **Step 1：获取 board_token**（同创作 Workflow Step 1）
 
-**Step 2：判断修改策略**
+**Step 2：探测可编辑性 / 是否由代码绘制**
 
-```
-+export --output-type source
-  ├─ 返回 Mermaid/PlantUML 代码
-  │   → 在原代码上修改 → +update --input_format mermaid/plantuml
-  ├─ 无代码（SVG/DSL 或其他方式绘制的画板）
-  │   ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
-  │   │    → +export --output-type preview → 看图 → +export --output-type raw → 确定新节点坐标和层级  → [§ 渲染 & 写入画板]
-  │   └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
-  │       → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
-  └─ 用户有明确要求 → 以用户要求优先
-```
+- `+export --output-type source` — 能返回单一 Mermaid/PlantUML 源码，说明画板由代码绘制、可走路径①；返回无代码/多图则走路径②③④
+
+**Step 3：选编辑路径**（按上到下匹配，命中即停；用户有明确指定则以用户为准）
+
+| 路径 | 命中条件 | 怎么改 | 写入方式 | 是否有损 |
+|---|---|---|---|---|
+| ①源码重构 | `+export source` 返回单一 Mermaid/PlantUML（即画板由代码绘制） | 在源码上改 → 按源码类型用 `+update --input_format mermaid` 或 `+update --input_format plantuml` | overwrite（整板重建） | ⚠️ **非严格无损，执行前确认** |
+| ②属性微调 | 只改已有节点的文字/颜色 | `+export --output-type raw --output <file>`（**必须写入文件**）→ 编辑文件中目标节点字段；如只能用 `+update --input_format raw --source @<file> --overwrite` 写回，先说明会整板重建并等待用户确认 | overwrite（整板重建） | ⚠️ **有损风险，未确认不得执行** |
+| ③增量追加 | 在原图基础上新增图/元素，保留原内容 | `+export --output-type preview` → 理解原图 → `+export --output-type raw` → 确定新节点坐标 → [§ 渲染 & 写入画板](#渲染--写入画板) 创作&写入 | append（**不加 `--overwrite`**） | 无损（原节点不动） |
+| ④结构重绘 | 需几何变动/增删元素/结构调整/混合编辑 | [`../routes/svg-edit.md`](../routes/svg-edit.md) | overwrite（清空重来） | ⚠️ **有损，必须先经用户确认** |
+
+**⚠️ 止损**：一条路径最多试 2 轮，不行就换条路径尝试一次；仍不行就停下，如实告诉用户卡点，不要在各路径间反复横跳。
 
 ---
 
@@ -45,12 +46,13 @@
 
 **先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
 
-**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
+**然后按当前产物类型 / 图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
 
-按上到下匹配, 命中即停:
+当前产物路由按上到下匹配, 命中即停:
 
 | 图表类型               | 身份                                  | 路径                                             |
 |--------------------|-------------------------------------|------------------------------------------------|
+| 当前要生成/追加的内容包含 @用户提及或图片/配图 | 任何身份                                | [`../routes/dsl.md`](../routes/dsl.md)         |
 | 思维导图、时序图、类图、饼图、甘特图 | 任何身份                                | [`../routes/mermaid.md`](../routes/mermaid.md) |
 | 鱼骨图、金字塔图、流程图    | `Doubao` / `Seed`                   | [`../routes/dsl.md`](../routes/dsl.md)         |
 | 其他图表               | `Claude` / `Gemini` / `GPT` / `GLM` / `Doubao` / `Seed`  | [`../routes/svg.md`](../routes/svg.md)         |
@@ -81,7 +83,7 @@ diagram.png           ← 渲染结果
 
 写入画板时按最终产物类型选择 `+update --input_format`：
 
-- Mermaid / PlantUML / SVG 产物直接用对应的 `mermaid` / `plantuml` / `svg` 写入。
+- Mermaid / PlantUML / SVG 产物直接写入时，`--input_format` 取单值 `mermaid` / `plantuml` / `svg`；写入非空已有画板并需要 overwrite 时，先确认会整板重建；SVG 修改已有画板时先走 [`../routes/svg-edit.md`](../routes/svg-edit.md) 的确认 workflow。
 - 只有 DSL 产物或已明确需要 OpenAPI 原生节点格式时，才先用 `npx -y @larksuite/whiteboard-cli@^0.2.13 --to openapi --format json` 转换，再用 `raw` 写入。
 
 具体命令示例、`--overwrite`、`--idempotent-token` 和 `--as user/bot` 的使用方式，统一参考 [`whiteboard +update`](./lark-whiteboard-update.md)。

package/skills/lark-whiteboard/routes/dsl.md

@@ -33,7 +33,7 @@ Step 3: 渲染 & 审查 → 交付
       npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json --to openapi --format json \
         | lark-cli whiteboard +update --whiteboard-token <board_token> \
             --source - --input_format raw --idempotent-token <时间戳+标识> --as user
-      → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
+      → 完整 dry-run / 确认流程见 [§ 写入画板](../references/lark-whiteboard-workflow.md#写入画板)
   - 交付：向用户报告 board_token 写入成功
 ```
 
@@ -73,7 +73,13 @@ Step 3: 渲染 & 审查 → 交付
 | 循环/飞轮图 | `scenes/flywheel.md`     | 增长飞轮、闭环链路                     |
 | 里程碑      | `scenes/milestone.md`    | 时间线、版本演进                       |
 | 流程图      | `scenes/flowchart.md`    | 业务流、状态机、带条件判断的链路       |
-| 图片展示    | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `elements/image.md` 的图片准备） |
+
+### 插入 @用户提及 / 图片
+
+| 当前内容包含 | 必读指南 |
+|---|---|
+| @用户提及 | [`../scenes/mention.md`](../scenes/mention.md) |
+| 图片 / 配图 | [`../scenes/photo-showcase.md`](../scenes/photo-showcase.md) |
 
 ## 渲染前自查
 

package/skills/lark-whiteboard/routes/mermaid.md

@@ -22,6 +22,6 @@ Step 3: 渲染验证 & 写入画板 & 交付
        npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.mmd --to openapi --format json \
          | lark-cli whiteboard +update --whiteboard-token <board_token> \
              --source - --input_format raw --idempotent-token <时间戳+标识> --as user
-       → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
+       → 完整 dry-run / 确认流程见 [§ 写入画板](../references/lark-whiteboard-workflow.md#写入画板)
   6. 交付：向用户报告 board_token 写入成功
 ```

package/skills/lark-whiteboard/routes/svg-edit.md

@@ -16,11 +16,14 @@ SVG 导出是**纯视觉快照**，再次导入后画板语义（思维导图层
 
 ### 0. 用户确认（强制）
 
-在执行任何编辑前，**必须**向用户说明：
+执行任何编辑前，先判断**紧邻的上一条用户消息**是否已明确确认有损编辑：
+
+- **已确认**（含用户主动预授权，如"我知道有损，直接改"）→ 直接进入 Step 1，不再重复警告。
+- **未确认或回复含糊** → 原样向用户发出下面这句话，**然后立即结束本回合等待回复** —— 同一条消息内不得附带任何导出/编辑/写回命令或工具调用：
 
 > SVG 编辑只保证视觉层面对齐，画板语义（层级/节点类型/思维导图结构/表格结构/连线绑定/容器类型/mention 等）将不可恢复，是否继续？
 
-**用户未确认前不得执行后续步骤。**
+这是**知情确认**（动手前让用户对语义丢失止损）；真正的破坏性写入在 Step 4 还会再经 `--overwrite` dry-run 确认一次，二者职责不同、都不可省。
 
 ### 1. 导出当前画板 SVG
 

package/skills/lark-whiteboard/routes/svg.md

@@ -54,6 +54,8 @@
 - 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
 - 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可);
 
-**⚠️ [!IMPORTANT] 不支持的装饰特性**
+> [!IMPORTANT]
+> ⚠️ **不支持的装饰特性**
+
 - `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
 - 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`

package/skills/lark-whiteboard/scenes/mention.md

@@ -0,0 +1,71 @@
+# 提及用户 (@用户 / mentionUser)
+
+适用于：文本节点内需要 @ 某个飞书用户（如"负责人：@张三"、"@李四 请跟进"）。mention 不是独立节点，而是文本节点富文本中的一段 run，可与普通文字混排。
+
+> 当用户要插入 @用户提及时阅读本页。
+
+## 取值来源（强约束）
+
+- 本页只讲 @用户（mentionUser）。@文档（mentionDoc）暂不支持。
+- `mentionUserId` 必须是**真实的飞书用户 open_id**（形如 `ou_xxxxxxxx`）。
+- 用户只给出**姓名**时，先用 `lark-contact` skill 把姓名解析成 open_id，再填入 `mentionUserId`。
+- **无法解析出真实 open_id 时，停下向用户确认，禁止臆造 id**。假 id 会写入失败或 @ 到错误的人。
+
+## Content 约束（关键）
+
+- 带 `mentionUserId` 的 run，其 `content` **必须非空**，约定填 `"*"`（单字符占位）。
+  - 原因：转换按字符占位来引用样式，`content` 为空串时该 mention 不会产出任何元素（静默丢失）。
+- `content` 的字面内容**不会显示**：画板上显示的是按 open_id 反查到的用户名，不是 `content` 的文字。因此不要把用户名写进 `content`，填单个 `"*"` 即可。
+- 一个 run 只能是一种类型：`mentionUserId` 与 `hyperlink` **互斥**，不能同时出现在同一个 run（校验会报错）。需要"链接 + @用户"时拆成两个 run。
+
+## 骨架示例
+
+`text` 用 `WBTextRun[]`，把 @用户 拆成独立 run（`content: "*"` + `mentionUserId`），前后再接普通文字 run：
+
+```json
+{
+  "type": "text",
+  "width": "fit-content",
+  "height": "fit-content",
+  "text": [
+    { "content": "负责人：", "fontSize": 14 },
+    { "content": "*", "mentionUserId": "ou_xxxxxxxxxxxxxxxx", "fontSize": 14 },
+    { "content": " 请本周内跟进", "fontSize": 14 }
+  ]
+}
+```
+
+写入画板走标准 DSL 路径（`npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json --to openapi --format json | lark-cli whiteboard +update ... --input_format raw`），无需手写 raw JSON。
+
+## 正反例
+
+正确：
+
+```json
+{ "content": "*", "mentionUserId": "ou_abc123" }
+```
+
+错误（content 空串 → 不产出 @用户）：
+
+```json
+{ "content": "", "mentionUserId": "ou_abc123" }
+```
+
+错误（把用户名写进 content → 多余占位，显示仍由 uid 决定）：
+
+```json
+{ "content": "@张三", "mentionUserId": "ou_abc123" }
+```
+
+错误（与 hyperlink 同 run → 校验报错，须拆两个 run）：
+
+```json
+{ "content": "*", "mentionUserId": "ou_abc123", "hyperlink": "https://xxx.com" }
+```
+
+## 陷阱
+
+- **content 为空**：mention 静默丢失，画板上看不到 @用户。必须填 `"*"`。
+- **把用户名写进 content**：无意义，显示名由 open_id 反查决定；且多字符会占用多个字符位。
+- **mentionUserId + hyperlink 同 run**：一个 run 只能是一种元素类型，会被校验拦截，须拆成两个 run。
+- **用假 id 或用户中文名当 id**：`mentionUserId` 只接受真实 open_id，先经 `lark-contact` 解析。

package/skills/lark-wiki/SKILL.md

@@ -27,15 +27,16 @@ metadata:
 - 用户要**按特定主题 / 关键词 / 内容线索查找资料并收集到知识库节点或新建知识库节点下**，必须先阅读 [`../lark-drive/references/lark-drive-workflow.md`](../lark-drive/references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`topic_move_collector`](../lark-drive/references/lark-drive-workflow-topic-move-collector.md) workflow。该 workflow 使用 Drive 全量搜索召回，再按 Wiki 目标解析、确认和移动；不要只用 Wiki 节点列表做局部遍历。
 - 用户要**整理 / 盘点 / 归类 / 重构知识库、个人文档库、文档库目录或 Wiki 节点结构**，或要生成整理方案、目标目录树、移动计划时，不要只使用 Wiki 节点 API。必须先阅读 [`../lark-drive/references/lark-drive-workflow.md`](../lark-drive/references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`knowledge_organize`](../lark-drive/references/lark-drive-workflow-knowledge-organize.md) workflow；该 workflow 负责 Drive / Wiki / 个人文档库的统一入口解析、资源盘点、分类计划、写前确认和结果验证。
 - 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：使用 `wiki +move-to-drive`，不要使用 `wiki +move` 或 `drive +move`。这是会改变节点归属和权限继承的写操作，执行前确认源节点与目标位置。
-- 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
+- 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先确定下游成员操作的身份（默认 `user`；用户明确要求应用 / bot 视角时用 `bot`），再调用 `lark-cli wiki +node-get --node-token '<wiki_url>' --as user --format json`，从 `data.space_id` 获取空间 ID；下游使用 bot 时将示例中的身份改为 `--as bot`。节点解析与后续成员操作必须使用相同身份。
 - 用户要**删除**知识空间（`wiki +delete-space`）但只给了名称或 URL：**不能**把名称 / URL 原样传给 `--space-id`，必须先解析出真实 `space_id`。解析方式：
-  - URL（`.../wiki/<token>`）：`lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --format json`，读 `data.node.space_id`。
+  - URL（`.../wiki/<token>`）：先确定后续 `wiki +delete-space` 的身份（默认 `user`；明确要求 bot 视角时用 `bot`），再调用 `lark-cli wiki +node-get --node-token '<wiki_url>' --as user --format json`，读取 `data.space_id`；下游使用 bot 时将示例中的身份改为 `--as bot`。解析和删除必须使用相同身份。
   - 只知名称：`lark-cli wiki spaces list --format json`，边翻页边收集 items 并按 `name` 精确匹配；**一旦任一页累计到至少 1 条精确匹配就停止翻页**。只有当翻完所有页（`has_more=false`）仍无精确匹配时，才对已收集的全量 items 做宽松匹配（`name` trim 空格、大小写不敏感、子串包含）。
   - **关键安全约束**：无论精确还是模糊，**无论命中 1 条还是多条，发起删除前都必须把候选（`name` + `space_id` + `description` + `space_type`）列给用户，由用户明确选定一个 `space_id` 再执行**。不要因为"只命中一条"就自动执行删除。
   - 命中 0 条：停下来问用户是名称拼错了还是调用方无权限；**不要**自行改名字重试。
   - 用户明确选定后再执行 `lark-cli wiki +delete-space --space-id <ID> --yes`（高风险写操作，必须显式 `--yes`）。
-  - 反例：不要把 wiki URL / 名称直接当 `--space-id`（如 `--space-id "https://.../wiki/<wiki_token>"`）；务必先用 `wiki spaces get_node` 解析出 `data.node.space_id` 再传。
+  - 反例：不要把 wiki URL / 名称直接当 `--space-id`（如 `--space-id "https://.../wiki/<wiki_token>"`）；务必先用 `wiki +node-get` 解析出 `data.space_id` 再传。
 - 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
+- 用户要**原地重命名 Wiki 节点 / 修改节点标题**：使用 `lark-cli drive +update-title --url '<wiki_url>' --title '<new_title>'`。该命令保留同一个 `node_token`，并会根据 API 返回给出准确的缺失 scope 和授权提示；不要探索 raw `wiki.nodes` 的 `update_title` 端点，也不要通过复制或新建第二个节点实现改名。
 - 用户要列出 Wiki 节点：先用 `wiki +space-list --as user` 拿数字 `space_id`，再用 `wiki +node-list --space-id <space_id>`。不要把 wiki URL、node token、doc token、名称直接当 `--space-id`。钻子节点时 `--parent-node-token` 必须是 wiki node token；如果用户给的是 docx/sheet/base URL，先用 `wiki +node-get --node-token <url>` 解析出 `node_token`。
 - `wiki +node-list` 命中 `invalid_parameters`、`not_found`、`permission_denied` 时，不要重复调用同一参数；按 hint 修 `space_id` / `parent_node_token` / 权限。只有 `rate_limit` 才做退避重试。
 - 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门 / 应用”四类之一，再决定 `--member-type`，不要先调 `wiki +member-add` 再根据报错反推类型。
@@ -48,6 +49,8 @@ metadata:
 
 Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
+获取或解析 Wiki 节点统一优先使用 `wiki +node-get`，包括只为获取 `space_id`、`node_token`、`obj_token` 或 `obj_type` 的中间步骤。只有当前 CLI 不提供该 shortcut，或任务明确需要 shortcut 未输出的原始响应字段时，才回退到 `wiki spaces get_node`；回退前先运行 `lark-cli schema wiki.spaces.get_node`。
+
 | Shortcut | 说明 |
 |----------|------|
 | [`+move`](references/lark-wiki-move.md) | Move a wiki node, or move a Drive document into Wiki |
@@ -109,7 +112,8 @@ lark-cli wiki <resource> <method> [flags]  # 调用 API
 
 ## 不在本 skill 范围
 
-- 上传 / 下载文件到知识库节点下 → [`lark-drive`](../lark-drive/SKILL.md)（`drive +upload --wiki-token`）
+- 上传文件到知识库节点下 → [`lark-drive`](../lark-drive/SKILL.md)（`drive +upload --wiki-token`）
+- 下载 Wiki 节点对应的文件（底层 `obj_type` 为 `file`）→ [`lark-drive`](../lark-drive/SKILL.md)：`drive +download --wiki-token <node_token>` 或 `drive +download --url <wiki_url>`（CLI 会先把 Wiki 节点解析到底层文件再下载）；底层是 `docx`/`sheet`/`bitable`/`slides` 等在线文档时改用 `drive +export`
 - 编辑文档正文内容 → [`lark-doc`](../lark-doc/SKILL.md)
 - 表格 / 多维表格数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
 - 按名称搜索文档 / Wiki / 表格文件、评论与权限管理 → [`lark-drive`](../lark-drive/SKILL.md)

package/skills/lark-wiki/references/lark-wiki-delete-space.md

@@ -117,13 +117,16 @@ dry-run 会展示两步调用链：
 
 ### 2. 只有知识库 URL（`.../wiki/<token>`）
 
+先确定后续 `wiki +delete-space` 使用的身份：默认使用 `user`；用户明确要求应用 / bot 视角时使用 `bot`。下面展示默认 user 身份；下游使用 bot 时将两步都改为 `--as bot`。节点解析和删除必须使用相同身份。
+
 ```bash
-lark-cli wiki spaces get_node \
-  --params '{"token":"<wiki_token>"}' \
+lark-cli wiki +node-get \
+  --node-token '<wiki_url>' \
+  --as user \
   --format json
 ```
 
-读取 `data.node.space_id`。
+读取 `data.space_id`。
 
 ### 3. 只有知识库名称
 

package/skills/lark-wiki/references/lark-wiki-node-copy.md

@@ -1,6 +1,6 @@
 # lark-wiki +node-copy
 
-Copy a wiki node (including its content) to a target space or under a target parent node. Used for cross-space migration.
+Copy one Wiki node, including that node's content, to a target space or under a target parent node. Descendant nodes are not copied.
 
 > ⚠️ **High-risk write** — the upstream API is flagged `danger: true`, so this shortcut requires explicit `--yes` confirmation before issuing the request. Forgetting `--yes` returns a `confirmation_required` error and the copy is **not** performed.
 
@@ -46,26 +46,12 @@ lark-cli wiki +node-copy \
 }
 ```
 
-## Migration workflow
-
-To migrate a subtree from one space to another:
-
-```bash
-# 1. List nodes in the source space
-lark-cli wiki +node-list --space-id source_space_id
-
-# 2. Copy each node to the target space
-lark-cli wiki +node-copy \
-  --space-id <source_space_id> \
-  --node-token wikcn_EXAMPLE_TOKEN \
-  --target-space-id <target_space_id> \
-  --yes
-```
-
 ## Notes
 
-- Copying is recursive — the subtree under the node is also copied.
-- There is no native move API; migration = copy to target + (manually delete source if needed).
+- Copying is non-recursive: only the requested node and its content are copied.
+- Descendant nodes must be copied separately.
+- When the Wiki service returns `131009` lock contention, the CLI retries twice with bounded exponential backoff. If contention remains, wait before retrying again and avoid concurrent writes under the same target parent.
+- To move an existing Wiki node without keeping the source, use [`wiki +move`](lark-wiki-move.md) instead of copy-then-delete.
 
 ## Required Scope
 

package/skills/lark-wiki/references/lark-wiki-node-create.md

@@ -78,7 +78,7 @@ lark-cli wiki +node-create \
 | `--parent-node-token` | 否 | 父知识库节点 token；传入后会在该节点下创建新节点 |
 | `--title` | 否 | 节点标题 |
 | `--node-type` | 否 | 节点类型，默认 `origin`；可选值：`origin`、`shortcut` |
-| `--obj-type` | 否 | 节点对应对象类型，默认 `docx`；可选值：`sheet`、`mindnote`、`bitable`、`docx`、`slides` |
+| `--obj-type` | 否 | 节点对应对象类型，默认 `docx`；可选值：`sheet`、`mindnote`、`bitable`、`file`、`docx`、`slides`。`file` 仅支持 `shortcut` 节点 |
 | `--origin-node-token` | 否 | 当 `--node-type=shortcut` 时必填，表示快捷方式指向的源节点 token |
 
 ## 空间解析规则
@@ -89,11 +89,27 @@ lark-cli wiki +node-create \
 - **个人知识库回退**：`user` 身份下，如果 `--space-id` 和 `--parent-node-token` 都没传，会自动解析 `my_library`
 - **bot 身份限制**：`bot` 身份既没有“个人知识库”回退语义，也不支持显式传 `--space-id my_library`；请改用真实 `space_id` 或 `--parent-node-token`
 
-## shortcut 节点规则
+## 节点类型与对象类型
+
+| `node_type` | 支持的 `obj_type` |
+|-------------|-------------------|
+| `origin` | `sheet`、`mindnote`、`bitable`、`docx`、`slides` |
+| `shortcut` | `sheet`、`mindnote`、`bitable`、`file`、`docx`、`slides` |
 
 - `--node-type=shortcut` 时，必须同时提供 `--origin-node-token`
 - `--node-type=origin` 时，不能传 `--origin-node-token`
+- `--obj-type=file` 仅支持 `--node-type=shortcut`；实体节点不支持创建 `file` 类型
 - `shortcut` 节点只是知识库中的快捷方式入口；真正被引用的节点由 `--origin-node-token` 指定
+- 如果 `+node-create` 因上述组合返回参数校验错误，禁止改用 raw `wiki nodes create` 或直接调用 OpenAPI 绕过校验；应修正 `node_type`、`obj_type` 或 `origin_node_token`
+
+```bash
+# 创建一个指向文件的快捷方式节点
+lark-cli wiki +node-create \
+  --space-id <SPACE_ID> \
+  --node-type shortcut \
+  --obj-type file \
+  --origin-node-token <ORIGIN_NODE_TOKEN>
+```
 
 ## 一致性校验
 
@@ -111,6 +127,7 @@ lark-cli wiki +node-create \
   - 同时需要 `my_library` 和父节点时：会展示三步调用链
 - **bot 自动授权**：若使用 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予新建节点的可管理权限
 - **输出结果**：成功后会返回 `resolved_space_id`、`resolved_by`、`node_token`、`obj_token`、`obj_type`、`node_type`、`title` 等字段，便于后续继续操作
+- **结构限制**：返回 `131003` 表示触发了知识空间总节点数、目录深度或单个父节点直属子节点数等结构限制。这不是瞬时错误，禁止使用相同参数重试。根据上游错误信息选择更浅或其他父节点、重新组织现有节点，或清理/改用其他知识空间；不要在无法确认具体限制时盲目增加中间层级。
 
 ## 推荐场景
 

package/skills/lark-wiki/references/lark-wiki-node-get.md

@@ -52,6 +52,21 @@ lark-cli wiki +node-get \
 - `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.
 
+## Terminal business errors
+
+These HTTP 200 responses carry a non-zero business code and are not retryable with the same input:
+
+| Code | Meaning | Required action |
+|------|---------|-----------------|
+| `131006` | The current user or app/bot identity lacks access to the Wiki node or space | This is resource access, not app scope authorization. Do not retry the same request, reauthorize, or switch identity as trial and error; ask the node owner or wiki administrator to grant read access, or use an accessible resource |
+| `131012` | The Wiki node has been deleted | Do not retry the same node token; rediscover the node or ask for a current Wiki link |
+| `131013` | The resource token is invalid | Do not switch identity or reauthorize; correct the URL/token |
+| `131014` | The document is not mounted in Wiki | Stop Wiki resolution; use the corresponding docs/sheets/base/drive command, or provide a Wiki URL/node_token |
+
+## Rate limiting
+
+For `99991400` / `rate_limit`: Do not retry immediately. Wait `retry_after_seconds`, or use exponential backoff with jitter. Stop after 3 total attempts (1 initial + 2 retries).
+
 ## Required Scope
 
 `wiki:node:retrieve`

package/skills/lark-wiki/references/lark-wiki-node-list.md

@@ -87,7 +87,7 @@ lark-cli wiki +node-list --space-id 6946843325487912356 --parent-node-token wikc
 - `--space-id my_library` is a per-user alias and only valid with `--as user`. The shortcut will refuse `--as bot` with `my_library` upfront.
 - `--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>` 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.
+- 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. For `131006 permission_denied`, the user or app/bot identity lacks access to the target space or parent node; this is resource access, not app scope authorization. Do not retry the same request, reauthorize, or switch identity as trial and error. Ask the resource owner or wiki administrator to grant read access, or use an accessible resource.
 - For `rate_limit`, stop immediate retries and retry later with exponential backoff or a smaller `--page-limit`.
 
 ## Required Scope