diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 10b6876db..18ff4ec84 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -24,12 +24,12 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '

**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：** 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用） 2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`` / `` 输出结构） -3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和 [`lark-doc-style.md`](references/style/lark-doc-style.md)（元素选择、丰富度规则、颜色语义）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md) +3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和必读 [`lark-doc-style.md`](references/style/lark-doc-style.md)（写作原则：默认段落、按体裁、组件克制）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md) **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。** > **格式选择规则（全局）：** -> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。 +> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。 ## 快速决策 @@ -39,7 +39,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '

- 连续执行多个文档写操作时，必须按 [`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) 的「三、资源块」章节 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化 -- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `完整 SVG`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 ``，再启动 SubAgent 读取 `lark-whiteboard` 写入 +- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview` - 用户明确说"下载素材" → 用 `lark-cli docs +media-download` - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover` diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md index 17fa6bc2a..53f6be784 100644 --- a/skills/lark-doc/references/lark-doc-create.md +++ b/skills/lark-doc/references/lark-doc-create.md @@ -2,14 +2,14 @@ > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可： > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)） -> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义） -> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略） +> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制） +> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写） > > **未读完以上文件就生成内容会导致格式错误。** 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。 -> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。 +> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。 ## 命令 @@ -71,8 +71,8 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'# ## 参考 -- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略） -- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义） +- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写） +- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制） - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档 diff --git a/skills/lark-doc/references/lark-doc-update.md b/skills/lark-doc/references/lark-doc-update.md index 918408fa6..a2b374489 100644 --- a/skills/lark-doc/references/lark-doc-update.md +++ b/skills/lark-doc/references/lark-doc-update.md @@ -3,8 +3,8 @@ > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可： > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)） -> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义） -> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略） +> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制） +> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写） > > **未读完以上文件就生成内容会导致格式错误。** @@ -232,7 +232,7 @@ lark-cli docs +update --doc "" --command str_replace \ > **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 ``，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。 -画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。 +画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。 ## 最佳实践 @@ -252,8 +252,8 @@ lark-cli docs +update --doc "" --command str_replace \ ## 参考 -- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略） -- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义） +- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写） +- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制） - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档 - [`lark-doc-create.md`](lark-doc-create.md) — 创建文档 diff --git a/skills/lark-doc/references/lark-doc-word-stat.md b/skills/lark-doc/references/lark-doc-word-stat.md index b20b74ced..156b85912 100644 --- a/skills/lark-doc/references/lark-doc-word-stat.md +++ b/skills/lark-doc/references/lark-doc-word-stat.md @@ -13,6 +13,13 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \ `$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。 +## 统计范围 + +先判断用户要求的是**整篇文档**还是**局部内容**： + +- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。 +- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。 + 如需在自动化或回归验证中发现未覆盖块类型，追加严格参数： ```bash @@ -36,6 +43,15 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \ 如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。 +## 字数遵循校验 + +当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。 + +1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`` 分段写入。 - - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。 - -### 步骤二：分段撰写（并行 Agent） - -4. Spawn Agent 并行撰写各章节。每个 Agent 需收到： - - 文档 token、负责的章节范围、用户目标、目标读者和已有风格线索 - - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取） - - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容 - -### 步骤三：整合审查与画板识别（串行） - -5. `docs +fetch --detail with-ids` 获取文档，审查整体效果 -6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材 -7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容 - -### 步骤四：画板处理与润色（并行 Agent） - -8. **优先处理步骤三识别出的画板需求**： - 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。 -9. Spawn 内容改写 Agent 定向润色： - - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `` / `` / `` - - 需要明显分隔的主题可补充 `
`，不强制章节间都使用 - - 本地图片使用 `docs +media-insert` 插入 +3. `docs +create` 创建并撰写： + - **短文档**：一次写入完整内容 + - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复 + - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入 + - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒 + - ⚠️ 若先建骨架写了占位摘要，补正文时**删除占位摘要**，不要留残渣 + - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理 +### 步骤二：整合审查与画板识别（串行） -## Agent 子任务要求 +4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果 +5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正 +6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容 -内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。 +### 步骤三：画板处理与润色 -Mermaid 图由主 Agent 直接插入 `...`，无需 SubAgent。 +7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent +8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `
`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `
`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入 -SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `...`，不改其他正文，也不读取 `lark-whiteboard`。 +### 步骤四：专项校验（按需执行） -已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。 +9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果 diff --git a/skills/lark-doc/references/style/lark-doc-style.md b/skills/lark-doc/references/style/lark-doc-style.md index 1a09a80f4..71ba1bd97 100644 --- a/skills/lark-doc/references/style/lark-doc-style.md +++ b/skills/lark-doc/references/style/lark-doc-style.md @@ -1,86 +1,68 @@ -# 文档表达组件参考 +# 飞书文档写作原则 -本文件说明飞书文档可用的结构化表达方式，供模型在需要时选择。它不是固定模板，也不是强制排版规范。 +写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。 +本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。 -默认原则：优先理解用户目标、受众、素材形态和已有文档风格，由模型自主决定结构、语气和视觉呈现。只有当用户明确要求“美化、重排版、做成报告/方案/看起来更专业”等，或内容本身明显需要结构化承载时，才主动使用下列组件。 +## 一、用户明确要求优先 -## 一、核心原则 +用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。 -1. **服务内容，而非套模板**：先判断信息最自然的表达方式，再选择段落、列表、表格、分栏、画板等元素 -2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件 -3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠 -4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式 -5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达 +## 二、默认写连贯段落 -## 二、元素选择指南 +用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题： -需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `` 直接内嵌；其他新图表可启动 SubAgent 插入 `完整 SVG`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。 +| 内容 | 用什么 | ❌ 别 | +|---|---|---| +| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 | +| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 | +| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 | +| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 | +| 任务清单 / 检查项 / 待办事项 | **``** | 用普通列表替代可交互待办 | +| 纯短并列项（无描述，如材料清单） | 列表 | — | +| 章节（内容成块、需在目录导航） | 标题层级 | — | -| 场景 | 可选表达方式 | -|--------------------------------------------|---------------------------------------| -| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒 | 需要视觉提醒时可用 ``；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 | -| 方案对比 / 优劣势 / Before vs After | 简短对比可用段落、列表或 ``；维度较多且需要逐项比较时再考虑 `
` 或画板 | -| 简短低风险对比 | `` 2 列分栏 | -| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期 | 可用 `
`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 | -| 任务清单 / 检查项 | `` | -| 代码片段 | `
`         |
-| 引用 / 公式                                    | `
` / ``            |
-| 操作入口 / 跳转链接                                | `
` / `` / `` 承载 -- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。 - -## 三、颜色语义 - -如果使用颜色，建议保持语义一致；不需要颜色时可以保持朴素文本风格： - -| 语义 | emoji 前缀 | callout 背景色 | 文字色 | -|-|-|-|-| -| 信息、说明 | ℹ️ "说明：" | `light-blue` | `blue` | -| 成功、推荐 | ✅ "推荐：" | `light-green` | `green` | -| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` | -| 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` | -| 中性、辅助 | — | `light-gray` | — | - -- 表头可使用 `background-color="light-gray"`，也可以保持默认样式 -- 关键指标如使用 `` 突出，建议同时用 ↑↓ 或 +/- 标注方向（色觉无障碍） - -## 四、排版规范 - -- 标题层级、段落长度、列表嵌套和 Grid 列数应以可读性为准，避免过深层级和过宽分栏 -- 文档开头可以是结论、背景、摘要、问题陈述、目录或直接正文，不强制使用 `` - -## 五、质量自检 - -生成内容后可以从以下角度自检，但不要把这些项当作硬性比例或固定模板： - -| 指标 | 自检问题 | -|-|-| -| 信息表达 | 当前结构是否符合用户目标，而不是套用固定报告模板？ | -| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多的问题？ | -| 风格匹配 | 是否延续了用户给定样例或已有文档风格？ | -| 组件必要性 | callout、grid、table、whiteboard 等是否真的提升理解？ | -| 保真度 | 改写时是否保留了原文事实、引用、图片、附件和资源块？ | +| 信息、说明 | `light-blue` | `blue` | +| 成功、推荐 | `light-green` | `green` | +| 警告 / 错误 / 风险 | `light-red` | `red` | +| 注意、待确认 | `light-yellow` | `yellow` | +| 中性、辅助 | `light-gray` | — | + +## 六、写完自检 + +交付前快速回看： +- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。 +- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。 +- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。 +- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。 +- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。 diff --git a/skills/lark-doc/references/style/lark-doc-update-workflow.md b/skills/lark-doc/references/style/lark-doc-update-workflow.md index 9ff07c4d0..31ed97477 100644 --- a/skills/lark-doc/references/style/lark-doc-update-workflow.md +++ b/skills/lark-doc/references/style/lark-doc-update-workflow.md @@ -5,7 +5,7 @@ ## 核心方法论 — Code-Act Loop 通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行： 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么 -2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进 +2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二） 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环 @@ -23,33 +23,26 @@ - 需要精确跨节区间 → `docs +fetch --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾） - 用户只给了模糊关键词 → `docs +fetch --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids` - 用户明确要改整篇 → `docs +fetch --detail with-ids` - - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope" + - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) 中「选 `--scope`（读取范围）」小节 2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解 -3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段 +3. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段 4. 向用户简要说明改进计划（包含识别出的画板机会） -### 步骤二：定向改写（并行 Agent） +### 步骤二：定向改写（单 Agent 串行） -5. **优先处理步骤一识别出的画板候选段落**： - 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。 -6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID： +5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent +6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效： - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版 - - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性 - - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步 + - 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`） + - 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步 ### 步骤三：验证（串行） 7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格 -8. 检查是否满足用户目标并保留原有关键内容；如仍有明显问题则定向修正，向用户呈现结果 +8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正 -## Agent 子任务要求 +### 步骤四：专项校验（按需执行） -内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。 +9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果 -Mermaid 图由主 Agent 直接插入 `...`，无需 SubAgent。 - -SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `...`，不改其他正文，也不读取 `lark-whiteboard`。 - -已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。 - -**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。 +**上下文节省提示**：主 Agent 改某节时如需重新读取，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉当前章节，不要重复拉全文。