@amaster.ai/pi-lark 0.1.2-beta.42 → 0.1.2-beta.43

package/skills/lark-wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-wiki
-version: 1.0.2
+version: 1.0.3
 description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：上传文件到知识库节点下（走 lark-drive）、编辑文档/表格/Base 内容（走 lark-doc / lark-sheets / lark-base）。"
 metadata:
   requires:
@@ -25,6 +25,7 @@ metadata:
 ## 快速决策
 
 - 用户要**整理 / 盘点 / 归类 / 重构知识库、个人文档库、文档库目录或 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`。
 - 用户要**删除**知识空间（`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`。
@@ -49,6 +50,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）
 | Shortcut | 说明 |
 |----------|------|
 | [`+move`](references/lark-wiki-move.md) | Move a wiki node, or move a Drive document into Wiki |
+| [`+move-to-drive`](references/lark-wiki-move-to-drive.md) | Move a wiki node to a Drive folder and poll the async task |
 | [`+node-create`](references/lark-wiki-node-create.md) | Create a wiki node with automatic space resolution |
 | [`+delete-space`](references/lark-wiki-delete-space.md) | Delete a wiki space, polling the async delete task when needed |
 | [`+space-list`](references/lark-wiki-space-list.md) | List all wiki spaces accessible to the caller |
@@ -76,7 +78,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）
 - `我的文档库` / `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 域处理
+- 如果用户明确说的是 Drive 文件夹、云空间（云盘/云存储）根目录、`我的空间`，再按源对象分流：源对象是 Wiki 节点时用 `wiki +move-to-drive`，源对象已在 Drive 时用 `drive +move`
 
 ## API Resources
 

package/skills/lark-wiki/references/lark-wiki-move-to-drive.md

@@ -0,0 +1,122 @@
+# wiki +move-to-drive
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将已有 Wiki 节点移出知识库，并放到指定 Drive 文件夹；省略目标文件夹时放到当前调用身份的“我的空间”根目录。该操作始终创建异步任务，shortcut 会自动有限轮询。
+
+## 何时使用
+
+| 源对象 | 目标位置 | 命令 |
+|--------|----------|------|
+| Wiki 节点 | Wiki 空间或 Wiki 父节点 | `wiki +move` |
+| Drive 文档 | Wiki 空间或 Wiki 父节点 | `wiki +move` |
+| Wiki 节点 | Drive 文件夹或“我的空间”根目录 | `wiki +move-to-drive` |
+| Drive 文件 / 文件夹 | Drive 文件夹或根目录 | `drive +move` |
+
+`--node-token` 必须是 Wiki 节点 token，不是底层文档的 `obj_token`。无法判断时，先执行 `wiki +node-get --node-token <URL_OR_TOKEN>`。
+
+## 命令
+
+```bash
+# 移到指定 Drive 文件夹
+lark-cli wiki +move-to-drive \
+  --node-token <WIKI_NODE_TOKEN> \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --as user
+
+# 移到当前调用身份的“我的空间”根目录
+lark-cli wiki +move-to-drive \
+  --node-token <WIKI_NODE_TOKEN> \
+  --as user
+
+# 预览提交任务和轮询任务两步请求
+lark-cli wiki +move-to-drive \
+  --node-token <WIKI_NODE_TOKEN> \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--node-token` | 是 | 要移出知识库的 Wiki 节点 token |
+| `--folder-token` | 否 | 目标 Drive 文件夹 token；省略时移动到当前调用身份的“我的空间”根目录 |
+
+## 异步协议与续跑
+
+shortcut 会按以下协议执行：
+
+1. `POST /open-apis/wiki/v2/nodes/{node_token}/move_wiki_to_docs`，取得完整、不可拆分的 `task_id`。
+2. `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=move_wiki_to_docs`。
+3. 读取 `data.task.move_wiki_to_docs_result`：`status=1` 表示处理中，`status=0` 表示成功，`status=-1` 表示失败。
+
+任务查询必须使用 `task_type=move_wiki_to_docs`、`move_wiki_to_docs_result` 和数值状态；不要回退到其他 task type、result 字段或字符串状态。
+
+- 最多轮询 30 次，每次间隔 2 秒。
+- 轮询窗口内成功时返回 `ready=true`，并尽可能返回 `obj_token`、`obj_type` 和 `url`。
+- 仍在处理中时返回 `ready=false`、`timed_out=true`、完整 `task_id` 和 `next_command`；超时不代表任务失败。
+- 任务进入失败态时返回结构化错误。
+- `task_id` 是服务端签名的 opaque ID，可能包含多个连字符；必须原样保存，不能自行切分。
+- 续跑必须保持和初始移动相同的 `--profile` 与 `--as user|bot` 身份，否则可能收到权限错误；shortcut 返回的 `next_command` 会保留两者。
+
+手动续跑命令：
+
+```bash
+lark-cli drive +task_result \
+  --scenario wiki_move_to_drive \
+  --task-id <COMPLETE_TASK_ID> \
+  --as user
+```
+
+## 典型返回
+
+成功：
+
+```json
+{
+  "node_token": "wikcnXXX",
+  "folder_token": "fldcnXXX",
+  "task_id": "<OPAQUE_TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": 0,
+  "status_msg": "success",
+  "obj_token": "doxcnXXX",
+  "obj_type": "docx",
+  "url": "https://example.feishu.cn/docx/doxcnXXX"
+}
+```
+
+轮询窗口超时：
+
+```json
+{
+  "node_token": "wikcnXXX",
+  "folder_token": "",
+  "task_id": "<OPAQUE_TASK_ID>",
+  "ready": false,
+  "failed": false,
+  "status": 1,
+  "status_msg": "processing",
+  "timed_out": true,
+  "next_command": "lark-cli drive +task_result --scenario wiki_move_to_drive --task-id <OPAQUE_TASK_ID> --as user"
+}
+```
+
+## 权限与影响
+
+- CLI 写操作预检查使用 `space:document:move`，任务轮询使用 `wiki:space:read`。
+- 调用方必须能移动源 Wiki 节点并写入目标 Drive 文件夹。
+- 成功后源节点会从 Wiki 树中消失，目标文档改用 Drive 目标位置的权限模型；原 Wiki 层级继承权限不再保留。
+- 省略 `--folder-token` 时，“根目录”属于当前 `--as` 身份，user 与 bot 的可见资源范围可能不同。
+
+> [!CAUTION]
+> 这是会改变文档归属和权限继承的**写入操作**。执行前必须确认源 Wiki 节点、目标 Drive 位置和调用身份。
+
+## 参考
+
+- [lark-wiki](../SKILL.md) -- 知识库全部命令
+- [wiki +move](lark-wiki-move.md) -- Wiki 内移动与 Drive 文档迁入 Wiki
+- [drive +task_result](../../lark-drive/references/lark-drive-task-result.md) -- 超时后的任务续跑
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-wiki/references/lark-wiki-move.md

@@ -9,18 +9,19 @@
 
 当 `docs_to_wiki` 返回 `task_id` 时，shortcut 会先轮询一小段时间；如果轮询窗口内仍未完成，会返回 `next_command`，让调用方继续执行 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>`。
 
-## 与 `drive +move` 的区别
+## 与 `wiki +move-to-drive` / `drive +move` 的区别
 
 - `wiki +move` 的目标是 **知识空间或 Wiki 父节点**，使用 `--target-space-id` / `--target-parent-token`
+- `wiki +move-to-drive` 把 **已有 Wiki 节点移出知识库，放入 Drive 文件夹或“我的空间”根目录**，使用 `--folder-token`
 - `drive +move` 的目标是 **Drive 文件夹**，使用 `--folder-token`
-- 如果源对象已经是 Wiki 节点，必须使用 `wiki +move`，而不是 `drive +move`
+- 如果源对象已经是 Wiki 节点：目标仍是 Wiki 时使用 `wiki +move`；目标是 Drive 文件夹或根目录时使用 `wiki +move-to-drive`
 - 如果源对象还是 Drive 文档，但用户要“迁入知识库”“挂到某个 Wiki 页面下”，也应使用 `wiki +move`
 - 如果用户只是想整理云空间（云盘/云存储）文件夹，把文件/文件夹挪到另一个 Drive 文件夹，应使用 `drive +move`
 
 ## 口语目标识别
 
 - 当用户说“移动到某个知识库”“挂到某个页面下”“迁入 Wiki”时，按 **Wiki 目标** 处理，优先使用 `wiki +move`
-- 当用户说“移动到某个文件夹”“移动到云空间（云盘/云存储）根目录”时，按 **Drive 文件夹目标** 处理，优先使用 `drive +move`
+- 当用户说“移动到某个文件夹”“移动到云空间（云盘/云存储）根目录”时，按 **Drive 文件夹目标** 处理；源对象是 Wiki 节点时使用 `wiki +move-to-drive`，源对象已在 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`
@@ -180,4 +181,5 @@ CLI 会在执行前做本地 scope 预检查；当前 shortcut 声明的权限
 
 - [lark-wiki](../SKILL.md) -- 知识库全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [wiki +move-to-drive](lark-wiki-move-to-drive.md) -- 将 Wiki 节点移出知识库并放入 Drive
 - [drive +task_result](../../lark-drive/references/lark-drive-task-result.md) -- docs-to-wiki 异步任务的续跑查询命令