From a2be6326d21237369fb08378658ad7d3f03872fb Mon Sep 17 00:00:00 2001 From: xiongz-c <50195037+xiongz-c@users.noreply.github.com> Date: Thu, 30 Jul 2026 20:45:08 +0800 Subject: [PATCH 1/2] docs: add agent-readable document context workflow --- skills/lark-doc/SKILL.md | 1 + .../lark-doc/references/lark-doc-context.md | 73 +++++++++++++++++++ skills/lark-doc/references/lark-doc-fetch.md | 3 + 3 files changed, 77 insertions(+) create mode 100644 skills/lark-doc/references/lark-doc-context.md diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 478be8bb9f..34b31e5df1 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -35,6 +35,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '

## 快速决策 - 用户要**复制文档 / 创建文档副本 / 另存为副本**时，切到 [`lark-drive`](../lark-drive/SKILL.md)，按其中的复制指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文，也不要走 `drive +export` / `drive +import`。 - 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full` +- 用户要求“完整理解 / 深度阅读 / 审阅”文档，且结论可能依赖评论、图片、画板或嵌入 Sheet/Base 时，先读 [`lark-doc-context.md`](references/lark-doc-context.md)，用一个任务意图编排已有只读能力；不要把“完整”误解为无条件下载所有素材 - block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids` - 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节 diff --git a/skills/lark-doc/references/lark-doc-context.md b/skills/lark-doc/references/lark-doc-context.md new file mode 100644 index 0000000000..4fee67608f --- /dev/null +++ b/skills/lark-doc/references/lark-doc-context.md @@ -0,0 +1,73 @@ +# Agent 可消费的文档上下文读取 + +当用户要求“完整理解 / 深度阅读 / 审阅”一篇文档，且正文之外的评论、图片、画板或嵌入数据可能影响结论时，使用本工作流。 + +目标是让用户只表达一次读取意图，由 Agent 编排已有只读命令。“完整”是覆盖与任务相关的信息类型，不是把所有能力塞进一次 API 请求，也不是无界抓取。 + +## 工作流 + +### 1. 先选择最小读取模式 + +| 用户意图 | 首选路径 | +|-|-| +| 只要标题、类型、canonical token / URL | `lark-cli drive +inspect --url ''`，不读取正文 | +| 阅读或总结正文 | `docs +fetch --detail simple` | +| 连同评审意见理解文档 | 正文 + `drive +list-comments` | +| 结论依赖图片、画板或嵌入数据 | 正文 + 第 3 节的按需补全 | + +读取正文时，按 [`lark-doc-fetch.md`](lark-doc-fetch.md) 选择最小充分范围： + +- 文档较短且任务涉及整体：`docs +fetch --detail simple` +- 长文档或只涉及部分主题：先读 `outline`，再按 `section` / `range` 精读 +- 需要把评论定位回正文 block：改用 `--detail with-ids` + +不要因为用户说“完整”就默认使用 `--detail full`；`full` 用于保真编辑元数据，不等于更完整的业务语义。 + +### 2. 按任务决定是否读取评论 + +评论属于 `lark-drive`，不是 `lark-doc`。以下场景才补充评论： + +- 用户明确要求查看评论、评审意见或讨论结论 +- 用户要求审阅文档，且未解决评论可能改变对当前方案状态的判断 + +```bash +# 默认只读取未解决评论 +lark-cli drive +list-comments --url '' + +# 需要把评论定位到 Docx 正文时 +lark-cli drive +list-comments --url '' --need-relation +``` + +只有用户明确要求包含已解决评论时才添加 `--solved-status all`。评论细节与回复限制以 [`lark-drive`](../../lark-drive/SKILL.md) 为准。 + +### 3. 识别需要补全的结构化上下文 + +检查 fetch 内容中的结构化标签，并只处理会影响当前任务结论的项目： + +| 信号 | 处理方式 | +|-|-| +| `` / `` | 图片、截图或附件承载关键信息时，用 `docs +media-preview` 预览；不要默认下载全部素材 | +| `` | 架构、流程或决策依赖画板时，用 `docs +media-download --type whiteboard` 获取缩略图并查看 | +| `` / `` | 提取 `token` 与 `sheet-id`，切到 `lark-sheets` 读取相关范围 | +| `` / `` | 提取 `token` 与 `table-id`，切到 `lark-base` 查询相关字段和记录 | +| `` | 提取 `src-token` 与 `src-block-id`，只读取对应源 block | + +素材预览会写入本地文件；遵守 [`lark-shared`](../../lark-shared/SKILL.md) 的相对路径和安全规则。 + +### 4. 处理长文档与降级 + +- 优先用 `outline` + `section` 分段读取，避免一份超长响应挤占 Agent 上下文 +- 同一 token 和同一资源只读取一次 +- 某个补充能力失败时保留已获得的正文，并明确标记评论、素材或嵌入数据未覆盖；不要把局部失败伪装成整篇读取失败 +- 用户需要稳定的本地导出文件时，切到 `lark-drive` 的 `drive +export`；不要给 `docs +fetch` 虚构本地输出参数 + +## 输出要求 + +最终回答应区分： + +1. 正文直接陈述的事实 +2. 评论、图片、画板或嵌入数据补充的事实 +3. 基于上述证据的推断 +4. 未读取或无法访问、且可能影响结论的上下文 + +不要声称“已完整读取”而不说明实际覆盖了哪些上下文类型。 diff --git a/skills/lark-doc/references/lark-doc-fetch.md b/skills/lark-doc/references/lark-doc-fetch.md index 04e1ad1515..abadd50330 100644 --- a/skills/lark-doc/references/lark-doc-fetch.md +++ b/skills/lark-doc/references/lark-doc-fetch.md @@ -139,8 +139,11 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \ 返回中可能含 ``、``、``。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。 +如果用户要求完整理解或深度审阅，正文之外还可能需要评论、关键图片/画板与嵌入数据；按 [`lark-doc-context.md`](lark-doc-context.md) 用一个任务意图编排已有只读能力，不要无条件展开全部资源。 + ## 参考 +- [lark-doc-context](lark-doc-context.md) — 按需补全文档评论、素材与嵌入数据 - [lark-doc-create](lark-doc-create.md) — 创建文档 - [lark-doc-update](lark-doc-update.md) — 更新文档 - [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材 From dac99e10054a96bea2fc9b293e7dd74d01ca1fd2 Mon Sep 17 00:00:00 2001 From: xiongz-c <50195037+xiongz-c@users.noreply.github.com> Date: Thu, 30 Jul 2026 21:00:43 +0800 Subject: [PATCH 2/2] docs: refine document context workflow --- skills/lark-doc/SKILL.md | 2 +- skills/lark-doc/references/lark-doc-context.md | 15 ++++++++------- skills/lark-doc/references/lark-doc-fetch.md | 3 --- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 34b31e5df1..7c2e17fe45 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -35,7 +35,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '

## 快速决策 - 用户要**复制文档 / 创建文档副本 / 另存为副本**时，切到 [`lark-drive`](../lark-drive/SKILL.md)，按其中的复制指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文，也不要走 `drive +export` / `drive +import`。 - 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full` -- 用户要求“完整理解 / 深度阅读 / 审阅”文档，且结论可能依赖评论、图片、画板或嵌入 Sheet/Base 时，先读 [`lark-doc-context.md`](references/lark-doc-context.md)，用一个任务意图编排已有只读能力；不要把“完整”误解为无条件下载所有素材 +- 用户要求“完整理解 / 深度阅读 / 审阅”文档，且结论可能依赖评论、图片、画板或同步引用，或正文包含嵌入 Sheet/Base 时，先读 [`lark-doc-context.md`](references/lark-doc-context.md)，用一个任务意图编排已有只读能力；不要把“完整”误解为无条件下载所有素材 - block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids` - 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节 diff --git a/skills/lark-doc/references/lark-doc-context.md b/skills/lark-doc/references/lark-doc-context.md index 4fee67608f..e3343f039f 100644 --- a/skills/lark-doc/references/lark-doc-context.md +++ b/skills/lark-doc/references/lark-doc-context.md @@ -1,6 +1,6 @@ # Agent 可消费的文档上下文读取 -当用户要求“完整理解 / 深度阅读 / 审阅”一篇文档，且正文之外的评论、图片、画板或嵌入数据可能影响结论时，使用本工作流。 +当用户要求“完整理解 / 深度阅读 / 审阅”一篇文档，且正文之外的评论、图片、画板、同步引用或嵌入数据可能影响结论时，使用本工作流。 目标是让用户只表达一次读取意图，由 Agent 编排已有只读命令。“完整”是覆盖与任务相关的信息类型，不是把所有能力塞进一次 API 请求，也不是无界抓取。 @@ -17,8 +17,9 @@ 读取正文时，按 [`lark-doc-fetch.md`](lark-doc-fetch.md) 选择最小充分范围： +- 用户给出具体术语、错误码或标识：先用 `keyword` 定位，需要更多上下文时再按返回的 `top-block-id` 用 `section` / `range` 精读 - 文档较短且任务涉及整体：`docs +fetch --detail simple` -- 长文档或只涉及部分主题：先读 `outline`，再按 `section` / `range` 精读 +- 长文档或只涉及部分主题，且没有具体关键词：先读 `outline`，再按 `section` / `range` 精读 - 需要把评论定位回正文 block：改用 `--detail with-ids` 不要因为用户说“完整”就默认使用 `--detail full`；`full` 用于保真编辑元数据，不等于更完整的业务语义。 @@ -42,22 +43,22 @@ lark-cli drive +list-comments --url '' --need-relation ### 3. 识别需要补全的结构化上下文 -检查 fetch 内容中的结构化标签，并只处理会影响当前任务结论的项目： +检查 fetch 内容中的结构化标签。Sheet/Base 标签按主 Skill 的路由规则必须下钻；其他资源只在会影响当前任务结论时处理： | 信号 | 处理方式 | |-|-| | `` / `` | 图片、截图或附件承载关键信息时，用 `docs +media-preview` 预览；不要默认下载全部素材 | | `` | 架构、流程或决策依赖画板时，用 `docs +media-download --type whiteboard` 获取缩略图并查看 | -| `` / `` | 提取 `token` 与 `sheet-id`，切到 `lark-sheets` 读取相关范围 | -| `` / `` | 提取 `token` 与 `table-id`，切到 `lark-base` 查询相关字段和记录 | -| `` | 提取 `src-token` 与 `src-block-id`，只读取对应源 block | +| `` / `` | 必须提取 `token` 与 `sheet-id`，切到 `lark-sheets` 读取相关范围 | +| `` / `` | 必须提取 `token` 与 `table-id`，切到 `lark-base` 查询相关字段和记录 | +| `` | 源内容可能影响结论时，提取 `src-token` 与 `src-block-id`，只读取对应源 block | 素材预览会写入本地文件；遵守 [`lark-shared`](../../lark-shared/SKILL.md) 的相对路径和安全规则。 ### 4. 处理长文档与降级 - 优先用 `outline` + `section` 分段读取，避免一份超长响应挤占 Agent 上下文 -- 同一 token 和同一资源只读取一次 +- 只去重等价请求；revision、scope、range、detail 或 fields 不同时视为不同请求 - 某个补充能力失败时保留已获得的正文，并明确标记评论、素材或嵌入数据未覆盖；不要把局部失败伪装成整篇读取失败 - 用户需要稳定的本地导出文件时，切到 `lark-drive` 的 `drive +export`；不要给 `docs +fetch` 虚构本地输出参数 diff --git a/skills/lark-doc/references/lark-doc-fetch.md b/skills/lark-doc/references/lark-doc-fetch.md index abadd50330..04e1ad1515 100644 --- a/skills/lark-doc/references/lark-doc-fetch.md +++ b/skills/lark-doc/references/lark-doc-fetch.md @@ -139,11 +139,8 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \ 返回中可能含 ``、``、``。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。 -如果用户要求完整理解或深度审阅，正文之外还可能需要评论、关键图片/画板与嵌入数据；按 [`lark-doc-context.md`](lark-doc-context.md) 用一个任务意图编排已有只读能力，不要无条件展开全部资源。 - ## 参考 -- [lark-doc-context](lark-doc-context.md) — 按需补全文档评论、素材与嵌入数据 - [lark-doc-create](lark-doc-create.md) — 创建文档 - [lark-doc-update](lark-doc-update.md) — 更新文档 - [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材