Skip to content

docs: clarify lark-doc content file paths #1477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ZEden0 wants to merge 1 commit into from
Closed

docs: clarify lark-doc content file paths #1477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions skills/lark-doc/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
> **格式选择规则（全局）：**
> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
> - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
> - **本地文件输入**：`--content @path` 只接受 cwd 内相对路径（如 `@./draft.md`）；绝对路径或逃出 cwd 的路径禁止。用户给绝对路径时，先 `cd` 到文件目录再用 `@./filename`。`@@` 字面量和 `--content -` 行为不变。

## 快速决策
- 用户需要“某个 block 的直达链接 / 锚点链接”时：返回 `文档基础 URL#block_id`。如果当前只有文档 URL 没有 block_id，先用 `docs +fetch --detail with-ids` 拿到目标 block 的 id
Expand Down
2 changes: 2 additions & 0 deletions skills/lark-doc/references/lark-doc-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@

> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。

> **本地文件输入：** `--content @path` 只接受 cwd 内相对路径（如 `@./draft.md`）；用户给绝对路径时，先进入文件目录再用 `@./filename`。

## 命令

```bash
Expand Down
4 changes: 3 additions & 1 deletion skills/lark-doc/references/lark-doc-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
>
> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。

> **本地文件输入：** `--content @path` 只接受 cwd 内相对路径（如 `@./file.md`）；用户给绝对路径时，先进入文件目录再用 `@./filename`。

## 参数

| 参数 | 必填 | 说明 |
Expand Down Expand Up @@ -67,7 +69,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
--doc-format markdown --pattern "旧内容" --content "新内容"

# Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；"..."/'...' 里的 \n 是字面量）
# 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑
# 多行内容推荐 heredoc 或本地文件输入，避免 shell 转义踩坑
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
--doc-format markdown \
--pattern "$(printf '## 旧标题\n\n第一段原文\n\n第二段原文')" \
Expand Down
Loading