lark-safe-write

Lark Safe Write

触发时机：任何需要向 Lark wiki 创建新文档节点、更新现有文档内容或覆盖文档的任务。 核心原则：先解析 token → 再备份 → 再写入 → 最后验证。凡覆盖必备份，写入必验证，验证失败禁止自动重试。

同类 Skill 对比

公司库内

暂无直接同类。公司库现有 lark-wiki（知识库查询）、lark-doc（云文档管理）等操作 skill，但无「写入安全」专项 skill。

外部世界

暂无（未找到公开可验证的 Lark/Feishu wiki 安全写入专项 skill）。

本 skill 独特价值

• 唯一强制四步闭环：预检→备份→写入→验证，把覆盖风险消灭在发生前。
• 精准解决 lark-cli 三大坑：wiki_token/obj_token 混淆、--markdown /path 路径当内容、异步索引导致验证失败。
• 与现有 lark 生态互补：lark-wiki 查、lark-safe-write 写，形成完整读写链。

使用技巧

材料方案

• 首次使用该 skill 前，确保 lark-cli 已配置 bot 身份（lark-cli auth test --as bot 通过）。
• 写入内容包含链接时，禁用 <https://...> 自动链接语法，改用标准 [文本](https://...) 语法，避免飞书 docx 不兼容导致内容丢失。

推荐用法

• 覆盖现有文档时，skill 会自动备份到 .backups/，操作完成后可手动检查备份文件确认无误。
• 验证失败后禁止自动重试，需人工检查原因（常见：异步索引延迟不足、markdown 格式非法）。

已知限制

• 仅支持 docx/doc 类型文档，sheet/bitable/slides 等类型会停止并建议转用对应 skill。
• 无法处理需要复杂权限审批的 wiki 空间（如仅特定部门可见），需先在飞书控制台完成审批。

---

第一步：预检与 Token 解析（不可跳过）

1.1 身份与连通性

• 所有命令必须携带 --bot 标志（或 --as bot）
• 执行 lark-cli auth test --as bot 确认 bot token 有效
• 若失败：暂停执行，提示用户检查 LARK_APP_ID / LARK_APP_SECRET

1.2 解析目标 Token

用户输入可能是 wiki URL 或 wiki_token。

若用户给的是 wiki URL：

https://xxx.larksuite.com/wiki/WIKITOKEN

提取 URL 中 /wiki/ 后的 token 作为 wiki_token。

若用户直接给的是 token：

• 以 wik 开头 → 这是 wiki_token，需要解析
• 以 dox / doc 开头 → 这是 obj_token（真实文档 token），可直接使用

1.3 wiki_token → obj_token 解析（关键！不可跳过）

wiki_token 不能直接用于文档读写。必须先用以下命令解析：

lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --as bot

从返回的 JSON 中提取：

• node.obj_token → 这是真实的文档 token，后续所有读写操作都用它
• node.obj_type → 文档类型（docx / doc / sheet / bitable / slides 等）
• node.title → 文档当前标题

类型检查：

• 若 obj_type 为 docx 或 doc：继续执行本文档流程
• 若 obj_type 为 sheet / bitable / slides 等：停止执行，向用户说明本 skill 仅支持文档类型，建议转用对应的 skill（如 lark-sheets）

1.4 权限确认

首次操作该 wiki 空间时，确认 bot 有 wiki:node:read、wiki:node:create、drive:drive 权限。

---

第二步：备份（更新/覆盖场景必须执行）

仅当文档已存在（即用户提供了已有 wiki 的 URL/token）时执行。创建新文档可跳过。