lark-hirono

Lark Hirono — 飞书文档工具包

将 Markdown 上传为样式化的飞书文档，优化现有页面，并获取、分析、标注和验证文档。

技能文件位置

此技能的支持文件相对于此 SKILL.md 存放：

• references/optimization-guide.md — 文档转换的质量标准和参考模式
• references/mermaid-guide.md — 何时以及如何生成 mermaid 图表；常见模式示例

运行 CLI

在每个会话开始时，按顺序尝试以下步骤，确定正确的调用方式**（仅需确定一次）**：

1. 全局安装 — 检查 PATH 中是否有 lark-hirono：

   command -v lark-hirono
   

   如果找到，则对所有命令使用 lark-hirono <action> [options]。 如果未找到，则使用 npm install -g lark-hirono 安装；并通过 npm update -g lark-hirono 更新到最新版本

2. 本地开发仓库 — 仅在克隆的 lark-hirono 仓库内工作时（即包含 "name": "lark-hirono" 的 package.json 文件所在目录），确保已安装依赖（npm install），然后运行：

   npx tsx bin/lark-hirono.ts <action> [options]
   

以下示例均以 lark-hirono 作为简写 — 请替换为已确定的命令。

首次设置

首次使用前，请运行以下步骤。每一步都是下一步的前置条件。

1. 安装 lark-hirono

npm install -g lark-hirono

2. 安装 lark-cli

lark-hirono 会在子进程中调用 lark-cli 二进制文件（>= 1.0.9）来执行所有飞书 API 操作。如果尚未安装：

mkdir -p /tmp/larkcli && cd /tmp/larkcli
npm init -y && npm install @larksuite/cli
node node_modules/@larksuite/cli/scripts/install.js

或者，将 LARK_CLI 环境变量设为现有 lark-cli 二进制文件的路径。

验证安装：

lark-cli --version   # should print >= 1.0.9

3. 配置 lark-cli

初始化 lark-cli 用于调用飞书 API 的应用凭证：

lark-cli config init

这是一个交互式设置 — 按照提示提供飞书应用 ID 和密钥。有关应用设置和权限范围的详情，请参阅 lark-shared 技能（lark-cli config init / lark-cli auth login）。

4. 身份验证

lark-hirono auth login --domain docs
# or equivalently: lark-cli auth login --domain docs

这会打开浏览器以进行飞书 OAuth 登录。登录后，lark-cli 会缓存令牌（通常位于 ~/.config/lark/）。

验证身份验证：

lark-hirono auth status

如果令牌已过期，请重新运行 auth login。

5. 可选配置文件

在项目目录中创建 lark-hirono.json，用于设置默认值（知识库空间、节点、后台模式）。此文件为可选项 — 也可以通过 CLI 标志传入所有值。

前置条件摘要

• Node.js 20+
• lark-cli >= 1.0.9（已安装并完成身份验证）
• lark-hirono.json 配置文件（可选，用于设置知识库空间／知识库节点的默认值）

数据位置

• 配置文件：当前目录或上级目录中的 lark-hirono.json
• 令牌缓存：由 lark-cli 管理（通常位于 ~/.config/lark/）
• 关键词批次：<input.md>.keywords_batch_N.json（由 highlight extract 生成）
• 已选关键词：<input.md>.selected_keywords.json（大模型输出，由工作流使用）

参数

$ARGUMENTS 应为：ACTION [ARGS...]

根据用户意图确定操作：

用户意图	操作
将本地 Markdown 上传到飞书	upload <input.md>
优化现有飞书文档	技能工作流（获取 → 编辑 → 上传）
根据本地文件更新飞书文档	optimize --doc <id> --input <file>
将飞书文档获取为 Markdown	fetch --doc <id>
分析文档结构	analyze <input.md>
提取表格标题供大模型使用	highlight extract <input.md>
应用关键词高亮	highlight apply <input.md> <keywords.json>
验证飞书文档质量	verify --doc <id>
管理身份验证	auth <subcommand>

---

操作：上传

将本地 Markdown 文件上传为样式化的 Feishu 文档。

lark-hirono upload <input.md> [title] [options]

选项：

• --title <title> — 文档标题（默认：第一个 H1）
• --wiki-space <id> — Wiki 空间 ID
• --wiki-node <id> — 父节点 ID
• --bg-mode <mode> — 标题背景：light | dark
• --image-dir <dir> — 下载图片的目录
• --strip-title — 移除第一个 H1 标题
• --no-highlight — 跳过关键词高亮
• --frontmatter-as-callout — 将 YAML frontmatter 转换为 Meta 提示框（blockquote → Feishu 提示框）。不使用此标记时，frontmatter 将原样保留。
• --mention-map <path> — 按文档 URL 索引的 JSON 映射：{ "<url>": { "obj_token": "…", "obj_type"?: 22, "title"?: "…" } }。上传后，任何匹配键的 text_run 链接都会改写为原生 mention_doc 元素，从而填充 Feishu 的反向链接面板和关系图视图。
• --verify — 上传后获取并验证
• --dry-run — 仅预处理，将 Markdown 输出到 stdout
• -v, --verbose — 详细日志

输入格式说明：

• [^name] 行内脚注引用和 [^name]: body 定义会被自动检测并改写为 Unicode 上标（⁽¹⁾…），并在末尾添加 ## Footnotes 部分。此操作可重复执行；对于没有脚注定义的输入则不做任何处理。围栏代码块中的内容不会改动。

对于 catalog_table 文档（包含 Code/Title 列的表格）：

1. 先运行 highlight extract input.md
2. 将 JSON 发送给 LLM，并保存为 .selected_keywords.json
3. 如果文件存在，上传时会自动应用关键词

示例：

lark-hirono upload my-doc.md "My Document" --wiki-space 123456

---

操作：优化

轻量优化 Feishu wiki 文档：修正错误、修复损坏内容、改善格式，同时保留作者的语气、风格和意图。

核心原则：原始文档是权威依据。参考文档仅用于指导格式结构。切勿大幅改写或重组内容。

输出：在参考文档下创建一个包含优化版本的新版 wiki 子页面。

工作方式：此技能使用 CLI 命令（fetch、upload、analyze）作为工具，同时运用 LLM 判断来检测内容损坏、确定强调方式并进行质量审查。

参数

• SOURCE_URL：要优化的 Feishu wiki URL，例如 https://my.feishu.cn/wiki/Abc123
• DEST_URL（可选）：格式良好的参考文档 URL；将在其父节点下创建新页面

从 URL 中提取 ID：

• Wiki URL https://my.feishu.cn/wiki/Abc123XYZ → 文档/节点 ID 为 Abc123XYZ（/wiki/ 后的路径片段）
• 在 --doc、--wiki-node CLI 标记中使用此 ID

工作流

按顺序完成以下任务：

1. 读取源文档 — 获取并理解源文档
2. 读取参考文档 — 获取并分析参考文档的格式
3. 格式分析 — 比较结构并找出格式差异
4. 内容审查 — 找出事实错误、不完整的描述和小问题
5. 生成优化版本 — 进行轻量改进 5.5. 内容保留审计 — 确认没有内容被删除或缩短 5.6. 强调审计 — 确认颜色/粗体的使用密度适当 5.7. 渲染布局回归检查 — 确认没有视觉回归
6. 写入 Feishu — 创建包含优化内容的新子页面

任务 1：读取源文档

lark-hirono fetch --doc <source-doc-id>

保存完整输出。这是要优化的文档。

仔细分析：主题、目的、写作风格/语气、标题结构、内容脉络、格式模式，以及必须保留的技术内容（数字、公式、系统、部署事实、实验设置、引文、注意事项）。记录观察结果，供任务 5 使用。

任务 2：读取参考文档

lark-hirono fetch --doc <reference-doc-id>

保存完整输出。这仅作为格式参考，不是内容来源。

**仅分析格式：**标题层级、章节组织、格式惯例（粗体、列表）、内容密度、结构元素（分隔线、引用、代码块）。

任务 3：格式分析

阅读 [references/optimization-guide.md](/references/optimization-guide.md)，了解详细的比较框架和已知格式规范。

参考规范：

• 优化指南是风格参考，不是对整篇文档进行全面改写的许可
• 除非存在明显的格式缺陷，否则保留源文档的宏观结构
• 如果源文档已有稳定的标题层级，不要仅为匹配参考模式而重新编号或加深标题层级
• 如果开篇区块、元数据区块或摘要布局已能正常使用，应优先做轻微整理，而非重新设计

根据以下具体格式规范检查源文档：

规范	预期模式
开篇提示框	使用 [!callout]，包含描述和论文／仓库链接
编号标题	## 1 标题 / ### 1.1 子标题
标题分组	整篇文档连续编号
层级冲突	分组／章节标题与子项处于正确层级
提示框／引用	可在全文中自由使用 |> / [!callout] / > 📌
代码块标签	每个代码块都标注语言
关键术语加粗	首次提及重要技术术语时加粗
行内强调	关键要点使用 {red:...}；关键术语使用 {green:...}

硬性约束：

• 如果源文档已有清晰一致的层级结构，不要认为标题必须编号
• 例外——中文序数标题始终属于缺陷：## 一、、## 二、、## 三、……使用的汉字不会触发工具的蓝色数字着色。务必转换为 ## 1 标题、## 2 标题……格式。这是强制要求。
• 不要仅因参考文档更细化，就强行增加子标题层级
• **同一标题层级的所有同级标题都必须统一编号或统一不编号。**如果已编号的同级标题中有一个标题未编号（例如 ## Cheatsheet），则必须为其分配下一个连续编号。
• 开篇布局、元数据布局和文档顶部摘要布局都是高风险区域，过度编辑很可能导致页面退化

重要：只指出格式差异。不要比较内容主题。

任务 4：内容审查（轻度处理）

检查源文档中需要修复的问题，无论格式如何：

修复以下问题：

• 事实错误：技术信息有误、版本号错误、链接失效
• 描述不完整：句子戛然而止、缺少解释、TODO／占位文本
• 明显的拼写错误：拼写错误、会改变含义的语法错误
• 格式损坏：Markdown 未闭合、列表缩进不一致
• 飞书导出导致的损坏：段落变成标题、标题层级错乱、内容合并

不要改动：

• 作者的语气：如果作者行文随意，就保留这种风格
• 内容重点：尊重作者对特定主题的强调
• 技术观点：保留作者对工具或方法的推荐
• 原始结构：只有在结构明显违反参考格式时才进行调整
• 细节程度：如果作者对某个主题简略带过，可能是有意为之

任务 4.5：Mermaid 图表（尽力而为）

阅读 [references/mermaid-guide.md](/references/mermaid-guide.md)，了解模式、规则和放置示例。

判断：本文档是否适合配图？如果文档描述了多阶段流水线、系统架构、分支算法或流程，则生成一个 Mermaid 代码块（放在开篇提示框之后、第一个标题之前）。如果是参考表、常见问题、目录，或不包含流程结构的文档，则跳过。有疑虑时就跳过——糟糕的图表还不如没有图表。

所有视觉样式都由流水线自动处理。你只需编写结构。

---

任务 5：生成优化版本

重要：写作前请仔细阅读本节。

80/20 规则

优化后的文档应与原文 80% 以上相同。修改应是细微改进，而不是重写。

修改内容：

1. 开篇提示框——叙述性文档必须添加（内容以文字为主、表格较少）。目录表格或数据表格文档无需添加。

   • 将提示框作为第一个内容块，置于所有标题之前。
   • 格式：<callout emoji="ICON" background-color="light-blue" border-color="light-blue">——选择一个图标（例如 gift、bulb、bookmark、pushpin、rocket、star）
   • 将文档的介绍或摘要描述放入提示框内，并以 </callout> 结束
   • 如果原文已有介绍段落、引用块或摘要章节用于描述文档，请将其作为提示框正文复用或稍作优化——不要编造新的摘要内容
   • 如果没有此类内容，请根据文档的主题和范围撰写 1–3 句话的摘要
   • 流水线安全措施：流水线会在必要时自动将首段注入为后备内容——请始终显式编写提示框，以控制内容和表情符号。

2. 标题结构调整——必要时修正编号和层级：

   • 使用连续递增的编号：顶层标题使用 ## 1、## 2……；第二层标题使用 ### 1.1、### 1.2……
   • 输入格式：写作 ## 1 标题（编号后加空格再写标题——Markdown 中不要加句点）。流水线会为单级编号自动添加句点：## 1 标题 → 渲染为蓝色前缀 1. 标题。多级编号（### 1.1 子标题）不会自动添加句点。
   • 修正中文序数：## 一、标题 → ## 1 标题
   • 修复错乱结构：被误转为标题的段落应恢复为段落
   • 保留层级：除非结构已损坏，否则不要添加或删除标题层级

3. 添加强调标记——使用 {red:...} 和 {green:...} 标记：

   • 红色强调：关键结论、结果和重要主张（长文档中添加 10–20 处）
     • 粗体短语：{red:**重要结论**} → 渲染为红色粗体
     • 普通文本：{red:术语} → 渲染为红色
     • 行内代码：{red:`cmd`} → 渲染为红色代码
   • 绿色强调：关键技术术语首次出现时（添加 5–10 处）
     • 普通文本：{green:术语} → 渲染为绿色
     • 行内代码：{green:`code`} → 渲染为绿色代码
   • 关键——转换获取文档中的原始 <text color> 标签：获取的文档中的原始 HTML <text color="green">BF16</text> 在上传的文档中无法正确渲染——它会显示为普通文本。优化时，请将每个 <text color="COLOR">CONTENT</text> 转换为简写形式：{green:CONTENT}、{red:CONTENT} 等。如果内容中有粗体，应将粗体放在标记内：{green:**CONTENT**}。切勿在优化后的输出中保留原始 <text color> 格式。
   • 保留所有已有强调：源文档中的每个 {red:...}、{green:...} 和 **粗体** 都必须保留在优化后的版本中。在此基础上添加新的强调，绝不要删除原有强调。
   • 关键渲染规则：粗体必须放在颜色标签内（使用 {red:**文本**}，绝不要使用 **{red:文本}**）。标题中不要使用 $formula$。不要用 ** 包裹 $formula$ 的边界。完整模式请参阅优化指南中的“渲染陷阱”章节。

4. 添加行内提示框 — 在文档正文中插入 Markdown 引用块，突出关键见解：

   • 使用 > 📌 **标题**: ... 表示关键见解
   • 使用 > 📚 **背景**: ... 表示背景知识
   • 目标：在长文档中添加 5-15 个此类引用块
   • 流水线自动转换：匹配 TL;DR、核心思想、关键结论、一句话总结、核心区别 等内容的引用块会自动转换为 <callout> XML。不要手动为这些内容编写 <callout> XML——请写成 > TL;DR: ...，交由流水线转换。
   • 重要——<callout> XML 正文中不得添加表情符号前缀：直接编写 <callout> XML 块时，正文不得以表情符号（📌、💡、📚 等）开头。开标签中的 emoji= 属性已经提供图标；在正文中再添加表情符号会导致图标重复显示。只有 > 📌 **标题**: ... 这种引用块语法（会由流水线自动转换）需要表情符号前缀。
   • 重要——不得嵌套 <callout> XML：飞书无法渲染嵌套在另一个 <callout> XML 块中的 <callout> XML 块。如果源文档包含这种结构，请将内部的 <callout> 块转换为普通段落（去掉开闭 XML 标签，保留文本）。<callout> 正文中的 Markdown 引用块（> ...）可以保留，不属于嵌套提示框。

5. 修复代码块 — 如果代码块缺少语言标签，请补上。

6. 修正事实错误 — 修正错别字、失效链接和错误信息。

7. 原样保留图片、表格和公式 — 在原位置原样复制 <image token>、<lark-table>、<equation> 标签。不得将 <equation> 改写为 $...$。不得输出带竖线包裹的 |lark-table ...|；请使用 <lark-table> XML 或标准 Markdown 表格。完整的正确和错误示例请参阅 [references/optimization-guide.md](/references/optimization-guide.md) § “已验证语法参考”。

   • 重要——公式：不得在 $...$ 或 <equation> 定界符之外直接写裸 LaTeX 下标（_{\text{...}}）——裸 _ 会变成斜体。多重下标问题：在同一个公式中使用 2 个或更多 _{...} 会导致格式错误（lark-cli 会将 _ 配对为斜体）。解决方法：使用不带花括号的单字符下标（_p、_h）。每个公式中只有一个 _{...} 时是安全的。
   • 重要——<lark-table> 单元格：带下划线内容的 ***粗斜体***（例如 ***sm__throughput***）会导致格式错误——lark-cli 会误解析 *** 内部的 _。对于带下划线的指标名称，请使用反引号代码格式（`sm__throughput`）。

8. <quote-container> 处理方式 — lark-cli 上传不支持 <quote-container>（会静默丢弃）。流水线会自动转换：表格外转换为引用块，表格内转换为灰色 <callout>。请保留原样或手动转换。

不要更改的内容：

• 不要为了改善文风而改写段落
• 不要添加新章节或删除现有章节
• 不要更改技术细节或建议
• 不要重组文档的论证流程

任务 5.5：内容保留审计

重要：写入飞书前，请确认没有内容丢失。

将优化后的版本与源文档进行比较：

• 所有章节均已保留（没有删除章节）
• 所有段落均已保留（没有遗漏段落）
• 所有代码块均已保留（没有删除代码）
• 所有表格均已保留（没有丢失数据）
• 所有链接均已保留（没有删除链接）
• 技术细节完整无缺（数字、公式、命令）
• 所有 <image token="..."> 标签均已保留（比较源文档与输出中的数量，确保没有遗漏）
• 所有 <equation> 块均已保留且未作改动（不得改写或拆分公式）

如果有内容缺失：请补回。优化后的版本必须完整保留原文的全部内容。

任务 5.6：强调效果审查

确认强调密度适当：

• 红色强调：长文档中有 10–20 处（或按长度适当调整）
• 绿色强调：首次出现的技术术语有 5–10 处
• 强调不过度：每段强调项不超过 3 个
• 强调不不足：突出显示关键结论

任务 5.7：渲染布局回归检查

确认优化后的文档不会出现视觉回归：

• 标题渲染正确（层级恰当）
• 代码块带有语言标签
• 表格能正确渲染（Markdown 表格语法正确）
• 提示框能正确渲染（引用语法正确）
• Markdown 语法均已闭合

任务 6：写入飞书

如果源文件是本地文件（例如 report.md）：将优化后的内容写入 report_upload.md（同一目录，添加 _upload 后缀）。切勿修改原始文件。切勿使用 /tmp/ 路径。

如果源文件是从飞书获取的：写入任意方便的临时文件（例如当前目录中的 <title>_upload.md）。

# Step 1: Write optimized content to upload file
# For local source report.md → use report_upload.md
cat > report_upload.md << 'OPTIMIZED_CONTENT_END'
[optimized markdown content here]
OPTIMIZED_CONTENT_END

# Step 2: Upload — default is always to create a new sibling page
lark-hirono optimize --doc <doc-id> --input report_upload.md --new \
  --title "Optimized: [Original Title]"

# Only update in place if the user explicitly asked to overwrite the original:
# lark-hirono optimize --doc <doc-id> --input report_upload.md

请注意，--new 标志会在同一父节点下创建同级页面。请记录返回的 URL/doc-id，以供下方的验证步骤使用。

任务 7：上传后验证（必需）

上传后，请验证渲染后的文档没有回归，然后再向用户报告。

lark-hirono verify --doc <new-doc-id>

检查输出是否满足以下要求：

• 存在提示框（叙述类文档）
• 标题按顺序编号，不使用中文序数
• 没有 \# 残留（转义的井号泄漏到文本中——管道使用 ZWSP 代替）
• 内容中没有可见的纯文本 <text color> 标签
• 内容量合理（没有比源文档短得多）

如果发现问题 → 修复本地上传文件，使用 --new 重新上传（或使用页面 ID 覆盖刚创建的页面），然后再次验证。最多重试 3 次。

验证通过后（或 3 次尝试用尽后），向用户报告：

1. 新页面的 URL
2. 所做更改——简要列出应用的格式改进
3. 置信度——说明你对更改有多大把握；注明重试过程中仍未解决的问题

---

操作：fetch

将飞书文档获取为 Markdown。

lark-hirono fetch --doc <doc-id> [--output file.md]

选项：

• --doc <id> — 文档 ID（必需）
• --output <file> — 保存到文件（默认：标准输出）

除非指定 --output，否则将 Markdown 输出到标准输出。

---

操作：analyze

分析 Markdown 文档结构。

lark-hirono analyze <input.md>

返回 JSON，包含：

• document_type — narrative | data_table | catalog_table | mixed
• heading_count — 标题数
• table_count — 表格数
• table_rows — 表格总行数
• suggested_modules — 建议的转换模块

---

操作：highlight

提取表格标题供大模型选择关键词，或将关键词应用于 Markdown。

提取

lark-hirono highlight extract <input.md> [--batch-size N]

从表格中提取 Code/Title 列，并保存为：

• input.md.keywords_batch_0.json
• input.md.keywords_batch_1.json（如果标题超过 200 个）

下一步： 将 JSON 文件发送给大模型，并将响应保存为 input.md.selected_keywords.json

应用

lark-hirono highlight apply <input.md> <keywords.json> [--inplace]

在表格标题中的关键词外添加 {red:**keyword**} 标签。

注意： 如果 .selected_keywords.json 存在，upload 和 optimize 会自动应用关键词。

---

操作：verify

获取并验证飞书文档质量。

lark-hirono verify --doc <doc-id>
lark-hirono verify <doc-id>          # positional form

选项：

• --doc <id> — 文档 ID（必需，除非以位置参数传入）
• -v, --verbose — 详细输出

报告内容：

• 区块/标题/表格数量、标题背景覆盖率
• 红色高亮和加粗表头数量
• 残留 HTML 标签（应为空）
• 结构和内容层面预期的通过/失败检查结果

通过时退出代码为 0，任意检查失败时为 1。

---

操作：auth

飞书身份验证管理（转发至 lark-cli）。

lark-hirono auth login
lark-hirono auth status

---

文档类型

叙述型 — 以文本为主、包含标题的文档

• 转换：规范化、标题、提示框
• 无需 LLM

目录表格 — 包含 Code/Title 列、行数为 50+ 的表格

• 转换：规范化、表格、关键词高亮
• 关键词选择需要 LLM

数据表格 — 行数少于 50 的表格

• 转换：规范化、表格
• 无需 LLM

---

工作流示例

上传叙述型文档

lark-hirono upload my-article.md

上传带关键词的目录表格文档

lark-hirono highlight extract catalog.md
# Send catalog.md.keywords_batch_0.json to LLM
# Save response as catalog.md.selected_keywords.json
lark-hirono upload catalog.md

优化现有飞书文档

lark-hirono optimize --doc CcKqdWjF2o2UzixXZDecXxvInyc

根据本地文件更新飞书文档

lark-hirono optimize --doc CcKqdWjF2o2UzixXZDecXxvInyc --input local.md

上传带 frontmatter 和原生反向链接的笔记

# mentions.json is a JSON object keyed by doc URL:
# { "https://www.feishu.cn/wiki/<node_token>": { "obj_token": "<obj_token>" } }
lark-hirono upload post.md \
  --frontmatter-as-callout \
  --mention-map mentions.json

上传后，指向 mentions.json 中某个 URL 的任何 Markdown 链接都会变为原生飞书文档提及，并在目标文档上填充反向链接面板。

---

支持文件

• references/optimization-guide.md — 质量标准和参考模式
• references/mermaid-guide.md — Mermaid 图表模式和示例