mirror of
https://github.com/larksuite/cli.git
synced 2026-07-09 18:34:03 +08:00
docs: simplify selection anchor skill guidance
This commit is contained in:
@@ -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) 的「三、资源块」章节
|
||||
|
||||
@@ -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 ID;CLI/SDK 会把选区锚点交给后端解析。
|
||||
- 如果当前安装的 `lark-cli` 不支持该语法,说明客户端较旧;可以先全文读取或提示升级,不要手写锚点换算逻辑。
|
||||
|
||||
**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。
|
||||
|
||||
- `--max-depth`:`outline` = 标题层级上限(3 = h1~h3);其它模式 = 被选块的子树遍历深度(`-1` 不限,`0` 仅块自身)。
|
||||
|
||||
Reference in New Issue
Block a user