Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion skills/lark-doc/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: lark-doc
description: "飞书云文档 / Docx / 知识库 Wiki 文档(v2):创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token,或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板(含 SVG 画板)、引用或同步块时,也先用本 skill 读取和提取 token,再切到对应 skill 下钻。使用本 skill 时,docs +create、docs +fetch、docs +update 必须携带 --api-version v2;默认使用 DocxXML,也支持 Markdown。"
description: "飞书云文档 / Docx / 知识库 Wiki 文档(v2):创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token,或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板(含 SVG 画板)、引用或同步块时,也先用本 skill 读取和提取 token,再切到对应 skill 下钻。使用本 skill 时,docs +create、docs +fetch、docs +update 必须携带 --api-version v2;默认使用 DocxXML,也支持 Markdown。注意:doubao.com 等基于飞书基础设施的域名,其 /docx/ /wiki/ 路径的 URL 同样适用本 skill,判断依据是路径模式而非域名。"
metadata:
requires:
bins: ["lark-cli"]
Expand Down Expand Up @@ -32,6 +32,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
> - **精准编辑场景**(`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令):优先使用 XML(`--doc-format xml`,即默认值)。XML 能稳定表达 block 结构和样式,局部精修更可控;不要因为 Markdown 更简单就自行切换。

## 快速决策
- **doubao.com 等 URL**:`/docx/`、`/wiki/` 路径的 URL 同样适用本 skill,判断依据是路径模式而非域名,详见 [lark-doc-fetch.md URL 识别规则](references/lark-doc-fetch.md#url-识别规则)
- 用户需要在文档内**创建、复制或移动**资源块(画板、电子表格、多维表格等)时,必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
- 写文档时,重要信息(核心流程、架构、对比、风险、路线图、关键指标、因果关系)优先规划为画板,不要只用文字或表格承载
- 新增画板必须隔离到 SubAgent:简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`,不读 `lark-whiteboard`;复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`,再启动 SubAgent 读取 `lark-whiteboard` 写入
Expand Down
15 changes: 14 additions & 1 deletion skills/lark-doc/references/lark-doc-fetch.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
| 参数 | 必填 | 说明 |
|------|------|------|
| `--api-version` | 是 | 固定传 `v2` |
| `--doc` | 是 | 文档 URL 或 token(支持 `/docx/` 和 `/wiki/`) |
| `--doc` | 是 | 文档 URL 或 token(支持 `/docx/` 和 `/wiki/` 路径,lark-cli 自动提取 token;域名不限,见下方 URL 识别规则) |
| `--doc-format` | 否 | `xml`(默认)\| `markdown` \| `text` |
| `--detail` | 否 | `simple`(默认)\| `with-ids` \| `full` |
| `--revision-id` | 否 | 文档版本号,`-1` = 最新(默认) |
Expand All @@ -114,6 +114,19 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
| `--max-depth` | 否 | `outline` = 标题层级上限;其它 = 子树深度(`-1` 不限,默认) |
| `--format` | 否 | `json`(默认)\| `pretty` |

### URL 识别规则

`--doc` 的判断依据是 **URL 路径模式**,而非域名。lark-cli 会自动从 URL 路径中提取 token,任何域名的 URL 只要路径匹配以下模式,都应使用 `docs +fetch` 读取:

| 路径模式 | 示例 | 说明 |
|----------|------|------|
| `/docx/TOKEN` | `https://xxx.feishu.cn/docx/Z1Fj...tnAc` | 飞书云文档 |
| `/wiki/TOKEN` | `https://xxx.feishu.cn/wiki/Z1Fj...tnAc` | 飞书知识库 |
| `/docx/TOKEN` | `https://www.doubao.com/docx/UN0vdw8...` | 豆包云文档 |
| `/wiki/TOKEN` | `https://www.doubao.com/wiki/UN0vdw8...` | 豆包知识库 |

**策略**:遇到匹配路径模式的 URL 时,直接用 `docs +fetch --api-version v2 --doc <URL>` 尝试读取。如果返回权限错误或 404,再告知用户可能无法访问。不要因为域名不是 `feishu.cn` 就跳过 lark-cli 而改用 WebFetch。

## 图片、文件、画板的处理

**文档中的素材以 XML 标签形式出现:**
Expand Down
Loading