lark-workflow-doc-template-engine

用途

文档模板引擎工作流用于打通飞书「数据层」（Base/Sheets）和「文档层」（Docs），实现数据驱动的文档自动化生成。典型场景包括客户报告、项目通知、合同草稿等需要批量生成的文档。

适用场景包括：用 XX 模板创建文档、基于模板批量生成报告、把多维表格的数据填入文档模板、数据驱动生成文档、批量生成合同/通知/报告、模板引擎、把表的每一行都生成一份文档、mail merge、用 Sheet 的数据填充文档、Doc template engine。

前置条件

支持 user 身份。执行前需确保已授权：

lark-cli auth login --domain doc,base,drive

开始前必须先用 Read 工具读取 lark-shared/SKILL.md，其中包含认证、权限处理和安全规则。

主要能力

工作流整体流程为：用户指定模板 → docs +fetch（读取模板内容）→ 识别变量占位符 {{xxx}} → 用户指定数据源 → base +record-list / sheets → 字段 ↔ 变量映射 → 单条生成 / 批量生成 / 预览模式 → docs +create（生成文档）/ 预览输出。

Step 1：读取模板文档

参考 lark-doc/SKILL.md。

# 读取模板文档内容
lark-cli docs +fetch --doc "<模板doc_token>" --format markdown

从模板内容中识别变量占位符。支持的占位符格式：

{{变量名}} — 标准格式（推荐）
{变量名} — 简化格式
【变量名】 — 中文格式

示例模板：

# {{项目名称}} 项目周报

## 基本信息
- 项目经理：{{负责人}}
- 报告周期：{{开始日期}} ~ {{结束日期}}
- 项目状态：{{状态}}

## 本周进展
{{本周完成内容}}

## 下周计划
{{下周计划内容}}

Step 2：获取数据源

方式 A — 多维表格（Base），参考 lark-base/SKILL.md：

# 获取表字段结构
lark-cli base +field-list --base-token "<base_token>" --table-id "<table_id>" --format json

# 获取记录数据
lark-cli base +record-list --base-token "<base_token>" --table-id "<table_id>" \
  --page-size 100 --format json

# 按关键词搜索特定记录（v1.0.8+，适合快速定位模板对应的数据）
lark-cli base +record-search --base-token "<base_token>" --table-id "<table_id>" \
  --query "<关键词>" --format json

方式 B — 电子表格（Sheets），参考 lark-sheets/SKILL.md：

# 读取电子表格数据（第一行为表头）
lark-cli sheets spreadsheets values get --params '{"spreadsheetToken":"<token>","range":"Sheet1!A1:Z100"}' --format json

方式 C — 用户直接提供数据（单条）：用户口述或以 JSON 形式提供变量值，直接进入 Step 4。

Step 3：变量映射

展示模板变量与数据源字段的映射关系，供用户确认。自动映射规则：

精确匹配：变量名 == 字段名
模糊匹配：变量名包含字段名或字段名包含变量名
未匹配：标注 ⚠️，等用户指定

Step 4：生成文档

安全规则：批量生成前必须让用户确认映射和生成数量。

单条生成：

# 替换变量后创建文档
lark-cli docs +create --title "<替换后的标题>" --markdown "<替换后的内容>"

批量生成：逐条创建（串行，每条间隔 1 秒）。对数据源中的每一行：用该行数据替换模板中的所有变量，然后创建文档。

lark-cli docs +create --title "<按行替换的标题>" --markdown "<按行替换的内容>"

批量安全：单次批量最多 20 条（避免创建过多文档）；超过 20 条提示用户分批执行；提供预览模式（仅展示替换结果，不创建文档）。

演示文稿生成（v1.0.9+，可选）：当用户需要生成 PPT 而非文档时：

# 一步创建演示文稿（v1.0.9+）
lark-cli slides +create --slides "<Markdown 内容>"

提示：slides +create 返回 presentation URL，可直接在报告中链接。

图片写入电子表格（v1.0.9+，可选）：当模板需要在 Sheets 中插入图片时：

# 向电子表格写入图片（v1.0.7+）
lark-cli sheets +write-image --spreadsheet "<token>" --range "<A1>" --image "<image_path>"

创建文档快捷方式归档（v1.0.10+，可选）：当批量生成的文档需要集中归档到同一目录时：

# 为生成的文档创建快捷方式到指定目录（v1.0.10+）
lark-cli drive +create-shortcut --file-token "<doc_token>" --parent-token "<archive_folder_token>"

提示：+create-shortcut 可以在不移动原始文档的情况下，在归档目录中创建引用链接，方便集中管理批量生成的文档。

预览模式会展示替换后的文档内容，并提示确认生成（共 N 条，输入"确认"执行）。

Step 5：输出执行报告

报告包含模板信息（模板文档、数据源、变量数量）和生成结果表格（文档标题、状态、链接），并汇总共生成 N 篇文档。

容错机制

模板中无占位符：提示"未检测到变量占位符"，引导用户在模板中添加
变量未匹配到字段：标注 ⚠️，等用户手动指定或使用固定值
数据源某行缺失字段：将缺失字段替换为"—"，不阻塞
批量超过 20 条：提示分批执行
文档创建失败：记录失败项，继续创建其余文档
模板文档无权限：提示用户检查文档分享设置

权限表

读取模板：docs +fetch，scope 为 docx:document:readonly，必选
Base 数据：base +field-list / +record-list / +record-search，scope 为 bitable:bitable:readonly，可选（Base 数据源时）
Sheets 数据：sheets values get / +write-image，scope 为 sheets:spreadsheet:readonly，可选（Sheets 数据源时）
生成文档：docs +create，scope 为 docx:document:write，必选
生成演示文稿：slides +create，scope 为 slides:presentation:write，可选（PPT 模式时）

参考

lark-shared — 认证、权限（必读）
lark-doc — +fetch、+create 详细用法
lark-base — +field-list、+record-list、+record-search 详细用法
lark-sheets — 电子表格读取、+write-image 详细用法
lark-slides — +create 演示文稿创建

技能介绍

用途