Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/lark-skills/lark-wiki

lark-wiki

Verified

【何时用:仅当用户明确指向飞书/Lark 知识库;泛指做文档默认走本地工具】飞书知识库:创建/查询知识空间、管理空间成员、管理节点层级(移动/复制/删除)、组织文档与快捷方式。doubao.com 的 /wiki/ URL 也走本 skill。不负责:上传文件(走 lark-drive)、编辑文档/表格/Base 内容(走 lark-doc/lark-sheets/lark-base)。

references/lark-wiki-delete-space.md

View on GitHub
# wiki +delete-space

> **前置条件:** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

删除一个飞书知识空间(知识库)。OpenAPI 对应 `DELETE /open-apis/wiki/v2/spaces/:space_id`。

- **不可逆**:该操作会将知识空间连同其下所有节点彻底删除,执行前必须反复确认
- **同步 / 异步两种返回**:
  - 如果接口直接返回空 `task_id`,说明删除同步完成,shortcut 立即返回 `ready=true`
  - 如果接口返回非空 `task_id`,shortcut 会先对任务做有限轮询;轮询窗口内仍未完成会输出 `next_command`,引导调用方使用 `lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID>` 继续查

## 命令

```bash
# 同步或异步删除一个知识空间(必须显式加 --yes 确认)
lark-cli wiki +delete-space \
  --space-id <SPACE_ID> \
  --yes

# 预览底层调用链(不会真的删除)
lark-cli wiki +delete-space \
  --space-id <SPACE_ID> \
  --dry-run
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--space-id` | 是 | 要删除的知识空间 ID |
| `--yes` | 是(真删时) | 高风险写操作确认。不传则 CLI 直接返回 `confirmation_required` 错误 |

## 行为说明

- **请求**:对 `/open-apis/wiki/v2/spaces/{space_id}` 发送 `DELETE`
- **同步返回**:响应 `data.task_id` 为空字符串时直接返回 `ready=true`、`failed=false`、`status_msg="success"`
- **异步返回**:响应 `data.task_id` 非空时进入有限轮询
- **任务轮询**:调用 `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=delete_space`,读取 `data.task.delete_space_result.status`
  - `status=success` → `ready=true`
  - `status=failure` / `status=failed` → 返回错误(`wiki delete-space task failed: <status_msg 或 status>`)
  - 其他值(如 `processing`、`running`)→ 视为进行中,继续轮询
- **有限轮询窗口**:固定最多轮询 `30` 次,每次间隔 `2` 秒
- **轮询超时不是失败**:如果窗口结束任务仍在处理中,会返回 `task_id`、`status`、`status_msg`、`ready=false`、`timed_out=true`、`next_command`
- **继续查询**:看到 `next_command` 后,改用 `lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID>` 继续查
- **轮询请求全部失败时直接报错**:如果任务已创建,但后续每一次状态查询都失败,shortcut 会返回带 hint 的错误,并给出继续查询命令

## 返回结果

### 同步删除

```json
{
  "space_id": "7629741305993170448",
  "ready": true,
  "failed": false,
  "status": "success",
  "status_msg": "success"
}
```

### 异步删除完成

```json
{
  "space_id": "7629741305993170448",
  "task_id": "7631425120875056669-965458aec67417f5982250806c97950697ccb82f",
  "ready": true,
  "failed": false,
  "status": "success",
  "status_msg": "success"
}
```

### 异步轮询超时

```json
{
  "space_id": "7629741305993170448",
  "task_id": "7631425120875056669-965458aec67417f5982250806c97950697ccb82f",
  "ready": false,
  "failed": false,
  "status": "processing",
  "status_msg": "processing",
  "timed_out": true,
  "next_command": "lark-cli drive +task_result --scenario wiki_delete_space --task-id 7631425120875056669-965458aec67417f5982250806c97950697ccb82f --as user"
}
```

**输出字段说明:**

- `space_id`:入参的知识空间 ID
- `ready`:任务是否已经完成
- `failed`:任务是否已失败(显式返回 `failure` / `failed` 时为 `true`)
- `task_id`:异步任务 ID,仅异步场景返回
- `status` / `status_msg`:异步任务的原始状态和可读标签
- `timed_out`、`next_command`:轮询窗口内未完成时返回

## dry-run 编排

dry-run 会展示两步调用链:

1. `DELETE /open-apis/wiki/v2/spaces/{space_id}`
2. `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=delete_space`(仅异步时真实发生)

## 权限说明

当前 shortcut 声明的权限为 `wiki:space:write_only` 和 `wiki:space:read`。前者用于发起删除请求,后者用于轮询同一命令内的异步任务状态;如果本地 token 缺失任一权限,CLI 会提示补授权——按 lark-shared 按需授权流程执行 `lark-cli auth login --scope "wiki:space:write_only wiki:space:read" --no-wait --json`(勿跑阻塞式登录)。

异步超时后的 `lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID>` 只需 `wiki:space:read`(纯读任务状态)。

## 空间解析:如何拿到 `space_id`

`wiki +delete-space` 只接受 `--space-id` 作为目标。用户在对话里常常只说知识库的**名称**或贴一条**知识库 URL**,这时**不能**把名称 / URL 原样当成 `space_id` 传进去,必须先解析。三种输入路径:

### 1. 已经有 `space_id`
直接用,无需解析。

### 2. 只有知识库 URL(`.../wiki/<token>`)

先确定后续 `wiki +delete-space` 使用的身份:默认使用 `user`;用户明确要求应用 / bot 视角时使用 `bot`。下面展示默认 user 身份;下游使用 bot 时将两步都改为 `--as bot`。节点解析和删除必须使用相同身份。

```bash
lark-cli wiki +node-get \
  --node-token '<wiki_url>' \
  --as user \
  --format json
```

读取 `data.space_id`。

### 3. 只有知识库名称

调用 `wiki spaces list`:

```bash
# 第一页
lark-cli wiki spaces list --format json

# 如果需要继续翻页(看下方停止条件),带上 page_token
lark-cli wiki spaces list --params '{"page_token":"<上一页返回的 page_token>"}' --format json
```

#### 翻页与匹配策略

**边翻边匹配**:每拿一页就在已累计的 items 上对 `name` 做精确匹配(区分大小写、保留空格),满足任一条件即停止翻页:

- (A) **累计精确匹配 ≥ 1 条** → 停止翻页,已找到目标
- (B) **`has_more=false`**(已翻完所有页)→ 停止翻页

结束后:

1. 如果累计精确匹配 ≥ 1:把**所有**精确匹配作为候选列给用户
2. 如果精确匹配 = 0(此时必然已走到 `has_more=false`,已收集全量 items):在全量 items 上做**宽松匹配**(`name` trim 空格 + 大小写不敏感 + 子串包含),作为候选
3. 宽松匹配也 0 条:停下来问用户是不是名字拼错、或者调用方没权限看到这个空间;**不要**自己改名字重试

> 不做更激进的归一化(比如去括号、去版本号尾缀),那些容易把 "客户台账(归档)" 误命中到 "客户台账"。

#### 早停的小边界

早停(条件 A)意味着**可能漏掉**位于更后面页的同名空间。这种重名 corner case 由下面的"用户确认"兜底:LLM 展示候选时应照抄 `name + space_id`,用户如果觉得不是自己想删的那一个,可以要求继续翻页。

#### 确认流程(硬约束)

**无论精确还是模糊,无论命中 1 条还是多条,发起删除前都必须先把候选列给用户**,由用户明确回选一个 `space_id`。不要因为"只命中一条"就跳过确认直接删。

列候选时至少包含以下字段,方便用户分辨:

- `name`(原始值,不做归一化)
- `space_id`
- `space_type`(`team` / `person` 等)
- `description`(若有)
- `visibility`(若有)

示例话术:

```text
根据 "客户台账" 找到以下候选:
  1) name="客户台账", space_id=7629...0448, space_type=team, description="销售部"
  2) name="客户台账(归档)", space_id=7629...0449, space_type=team, description="2023 以前"
请回复序号或 space_id 确认要删除的那一个;如果都不是请说明。
```

命中 0 条:停下来问用户是名称拼错了、还是调用方无权限看到这个空间;**不要**自动尝试改名字再查一次。

#### 执行删除

用户明确选定 `space_id` 后:

```bash
lark-cli wiki +delete-space --space-id <RESOLVED_SPACE_ID> --yes
```

> [!IMPORTANT]
> 删库不可逆。关键不变量:**发给服务端的 `--space-id` 必须是用户在上一轮对话里明确指认过的那一个**,不是 LLM 单方面"从匹配结果自动选"。

## 风险等级

- Risk:**`high-risk-write`**
- 框架会强制要求 `--yes` 确认;不传 `--yes` 时命令会直接返回 `confirmation_required` 错误,不会真的发请求

> [!CAUTION]
> `wiki +delete-space` 是**不可逆的写入操作**。执行前务必与用户再次确认 `--space-id`,并清楚该空间下的所有节点都会一并被删除。

## 参考

- [lark-wiki](../SKILL.md) -- 知识库全部命令
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
- [drive +task_result](../../lark-drive/references/lark-drive-task-result.md) -- 异步任务的续跑查询命令
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall