ai_member_xiaobian/.agents/skills/lark-wiki/references/lark-wiki-delete-space.md

wiki +delete-space

前置条件： 先阅读 ../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> 继续查

命令

# 同步或异步删除一个知识空间（必须显式加 --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 直接返回 unsafe_operation_blocked 错误

行为说明

• 请求：对 /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 的错误，并给出继续查询命令

返回结果

同步删除

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

异步删除完成

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

异步轮询超时

{
  "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-cli auth login --scope "wiki:space:write_only wiki:space:read"。

异步超时后的 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>）

lark-cli wiki spaces get_node \
  --params '{"token":"<wiki_token>"}' \
  --format json

读取 data.node.space_id。

3. 只有知识库名称

调用 wiki spaces list：

# 第一页
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（若有）

示例话术：

根据 "客户台账" 找到以下候选：
  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 后：

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

Important

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

风险等级

• Risk：high-risk-write
• 框架会强制要求 --yes 确认；不传 --yes 时命令会直接返回 unsafe_operation_blocked 错误，不会真的发请求

Caution

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

参考

• lark-wiki -- 知识库全部命令
• lark-shared -- 认证和全局参数
• drive +task_result -- 异步任务的续跑查询命令