docs: simplify selection anchor skill guidance

This commit is contained in:
sunpeiyang.996
2026-07-09 14:24:42 +08:00
parent 7d97755de5
commit 1401eeec8d
2 changed files with 4 additions and 30 deletions

View File

@@ -14,7 +14,7 @@ metadata:
```bash
# 常用示例
lark-cli docs +fetch --doc "文档URL或token"
lark-cli docs +fetch --doc "文档URL或token,后缀有 #share-... 锚点时会局部读取"
lark-cli docs +create --content '<title>标题</title><p>内容</p>'
lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
```
@@ -35,7 +35,6 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
## 快速决策
- 用户要**复制文档 / 创建文档副本 / 另存为副本**时,切到 [`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`
- 用户给出带 `#share-...` / `#part-...` 的文档 URL 时,按 [`lark-doc-fetch.md`](references/lark-doc-fetch.md) 的「选区锚点」优先局部读取;普通 `#block_id` 仍按 block 直达链接处理
- 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) 的「三、资源块」章节

View File

@@ -17,23 +17,10 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
# 按 block id 区间精读
lark-cli docs +fetch --doc Z1Fj...tnAc \
--scope range --start-block-id blkA --end-block-id blkB --detail with-ids
lark-cli docs +fetch --doc Z1Fj...tnAc --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
# URL 带选区锚点时自动局部读取(仅 #share- / #part-
lark-cli docs +fetch \
--doc 'https://bytedance.larkoffice.com/wiki/wikcnInnPln2MWskas4CZT6iynf#share-CUE3d6Ykno2fkexEvt8cGF8Wnse'
# 显式读取选区锚点
lark-cli docs +fetch \
--doc 'https://bytedance.larkoffice.com/wiki/wikcnInnPln2MWskas4CZT6iynf' \
--scope range \
--start-block-id '#share-CUE3d6Ykno2fkexEvt8cGF8Wnse'
# 强制全文读取时忽略选区锚点
lark-cli docs +fetch \
--doc 'https://bytedance.larkoffice.com/wiki/wikcnInnPln2MWskas4CZT6iynf#share-CUE3d6Ykno2fkexEvt8cGF8Wnse' \
--scope full
# URL 带 #share 选区锚点时自动局部读取
lark-cli docs +fetch --doc 'docURL#share-anchor'
# 读整个章节(以标题 id 为锚点,自动展开到下一个同级/更高级标题前)
lark-cli docs +fetch --doc Z1Fj...tnAc \
@@ -65,18 +52,6 @@ lark-cli docs +fetch --doc Z1Fj...tnAc \
> 💡 **多关键词用 `\|` 拼接OR 语义,任一命中即返回)**:例 `"部署\|发布\|上线"`,三词任一命中都进结果,适合**同义词/别名/多业务术语**一次召回(如 `bug\|缺陷\|故障`)。
### 选区锚点(`#share-...` / `#part-...`
用户给出带 `#share-...``#part-...` fragment 的文档 URL 时,优先只读取该选区。必须用引号包住 URL 或锚点,避免 shell 把 `#` 当注释。
- 直接传 URL`--doc '...#share-xxx'`,且未显式 `--scope full`CLI 会自动等价为 `--scope range --start-block-id '#share-xxx'`
- 显式写法:`--scope range --start-block-id '#share-xxx'``--scope range --start-block-id '#part-xxx'`
- 强制全文URL 即使带 `#share-...` / `#part-...`,只要传 `--scope full` 就读全文。
- 普通 `#block_id` 不是选区锚点,不会自动触发局部读取;需要 block 级读取时显式使用 `range` / `section`
- 选区锚点只允许放在 `--start-block-id`,不要传给 `--end-block-id`
- 不要在 Agent 侧换算真实 block IDCLI/SDK 会把选区锚点交给后端解析。
- 如果当前安装的 `lark-cli` 不支持该语法,说明客户端较旧;可以先全文读取或提示升级,不要手写锚点换算逻辑。
**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`
- `--max-depth``outline` = 标题层级上限3 = h1~h3其它模式 = 被选块的子树遍历深度(`-1` 不限,`0` 仅块自身)。