.trae/skills/lark-document/SKILL.md

📄 文档.trae/skills/lark-document/SKILL.md

🌱 创建于2026-04-30 21:00

✏️ 修改于2026-06-27 01:04

👁️ 浏览量—

🔗 短链接/~learn/s/20ddc88f

🔐 可见性

--- name: "lark-document" description: "Use when output will be pasted into a Lark or Feishu document from Markdown, especially for specs, architecture analysis, and process writeups." ---

Lark Document

Overview

这个 skill 用来生成对 Lark / Feishu document 更友好的 Markdown 文档。

目标不是写"通用 Markdown"，而是写"贴到飞书后结构尽量稳定、标题层级清晰、Mermaid 可直接预览"的 Markdown。

When to Use

用户明确提到 飞书、Lark、docx、飞书文档、飞书目录
用户要求"先写本地 md，后续贴到飞书"
用户要输出分析文档、方案文档、架构说明、模块图、流程图、时序图、关系图
用户强调"按飞书文档格式生成"或"按这套标准输出"

不要在普通 README、纯代码注释、只面向 GitHub 渲染的 Markdown 中使用这套约束，除非用户明确要求兼容飞书。

Core Rules

1. 输出目标

先判断目标是不是 Lark document：

如果用户要的是飞书文档内容，默认输出"可落地到飞书的 Markdown 正文"
如果没有可用的飞书写入工具，不伪造"已经写进飞书"，而是明确说明限制，并把内容写到本地 .md
如果用户给了飞书链接，但当前环境无法直接写入，仍然按飞书兼容格式生成 Markdown

2. 标题层级

飞书友好格式优先，不追求通用 Markdown 的层级美观。

规则如下：

文档主标题使用一个 #
正文一级章节也使用一个 #
章节内子标题使用 ###
更细一级的小标题使用 ####
不要把正文主章节写成 ##

推荐结构：

# 文档标题

# 一、背景

### 1. 模块职责
定位说明...

#### A. 核心流程
流程说明...

3. 标题文字格式

标题本身要"飞书粘贴友好"：

标题里不要使用反引号包裹文件名、模块名、字段名
标题里不要多余引号
标题末尾不要保留多余空格
标题后不要额外留出一整行空白，尤其是 ### 和 ####

正确示例：

### 1. handler.py
定位：统一入口层。

#### A. 触发事件标准化
无论来源是：

错误示例：

### 1. `handler.py`

#### A. 触发事件标准化

无论来源是：

4. 正文格式

正文里遵循这些约束：

文件名、函数名、表名、字段名在正文中可以使用反引号
列表尽量单层，避免深层嵌套列表
一段话尽量只表达一个结论，减少飞书粘贴后段落断裂
引用块、表格、任务列表仅在确实必要时使用
分隔段落优先使用自然空行，其次才是 ---

5. 列表格式

为了降低飞书二次排版走样的概率：

优先使用单层 - 列表
能改写成平铺列表时，不要写多层嵌套
如果必须分层，先尝试拆成"标题 + 单层列表"
枚举步骤优先使用 1. 2. 3. 样式

优先写法：

### 关键职责
- 接收触发请求
- 做登录态校验
- 派发下游任务

慎用写法：

- 一级
  - 二级
    - 三级

Mermaid Rules

1. 何时画图

如果文档要解释结构、关系、流程、时序，优先补 Mermaid 图，而不是只给纯文字。

常见图类型：

架构图：跨端或跨模块关系
模块图：包内模块职责与依赖
流程图：事件如何流转
时序图：一条请求从触发到结果的顺序
关系图：表关系、对象关系、状态关系

2. 图文并存

不要只给图，不要只给大段文字。

每张图附近最好同时具备：

一句说明这张图在解释什么
Mermaid 源码（使用 ``mermaid 代码框）


图后要点说明




3. Mermaid 输出格式
Mermaid 图直接使用标准 mermaid 代码块即可，飞书和大多数现代工具已支持直接预览：


flowchart TD
    A[Start] --> B[Done]

不再需要额外生成 mermaid.live 的 view/edit 链接。仅当用户明确要求提供在线编辑链接时，才调用mermaid-live-linkskill 生成。




4. Mermaid 生成流程
每次处理 Mermaid，按下面顺序：


先写 Mermaid 源码
检查图类型是否合适

直接用 `mermaid 代码块输出


最后通读上下文，确认图与正文口径一致




Document Content Length



文档内容要"看菜下饭"：文档的篇幅和详实程度，由需求本身的复杂度决定，不是千篇一律套模板。



判断标准



 需求类型  典型场景  文档风格 
--------- --------- ---------
 简单场景  单个模块/单条链路/小功能改动  结构清晰、突出重点、适当精简，3-5 个章节即可 
 中等复杂度  跨模块协作/新功能设计/选型对比  按骨架组织，每个模块展开讲职责和接口，7-10 个章节 
 大型系统设计  子系统/引擎/平台级设计  内容越丰富越详实越好，架构图、类图、流程图、时序图、数据流全上，10+ 章节 



核心原则



小而轻的文档：聚焦核心模块，不追求"大而全"。例如"某个函数的重构方案"，只需要背景、方案、对比、风险四个章节。
大而全的文档：需求复杂、模块多、涉及面广时，才需要完整的架构图、类图、时序图、数据流图等。例如子系统设计/引擎方案/平台架构。
不要为了凑模板而填充：某个章节如果没有实质内容可以写（如"具体案例"不需要展示），直接跳过该章节，不用保留空壳标题。
Mermaid 图的数量同样遵循该原则：简单文档 1-2 张核心图即可；复杂文档可以上 3-5 张不同类型的图。



Recommended Document Shape



适合飞书的分析型文档，优先按这个骨架组织。注意这只是一个参考骨架，根据需求复杂度灵活裁剪章节和篇幅：


# 文档标题

# 文档目标
一句话说明本文回答什么问题。

# 一句话结论
先给结论。

# 模块图 / 架构图
图 + 说明。

# 模块职责
按模块逐条拆解。

# 能力边界
说明负责什么、不负责什么。

# 具体案例
用一条真实链路把流程讲清楚。

# 时序图 / 流程图
图 + 说明。

# 风险点 / 待确认点
只写已知未确认项，不伪造结论。

# 最终总结
用 1 段或 3-5 条 bullet 收口。


Writing Strategy



1. 先结论后展开
飞书阅读通常是扫读式，先给"一句话结论"，再展开细节。



2. 先总图后分解
如果涉及多个模块或多端协作：



先给总览图
再讲每层职责
再讲具体案例



3. 先确认事实，再写风险
如果代码口径不一致：



明确写"当前已确认"
明确写"待确认"
不要把推测写成事实



Final Checklist



交付前逐项检查：

主标题和正文大章节是否都使用了 #

### / #### 标题后是否去掉了多余空行


标题里是否误用了反引号或多余引号
标题末尾是否有空格
列表是否尽量保持单层

Mermaid 源码是否使用独立的 mermaid 代码框


是否有"已写入飞书"这类无法验证的表述
文档篇幅是否与需求复杂度匹配（避免小需求写大文档，或大需求写太简略）




Common Mistakes

把正文主章节写成 ##

把 handler.py 这类标题写成 handler.py

在 ### 或 #### 后面额外空一行


只给 Mermaid 图，不给解释
只给文字，不给能帮助理解的图
把猜测写成确认结论




Example



下面是推荐格式：

``markdown

`trigger_engine 能力梳理与跨端链路分析`





文档目标
本文档用于梳理 trigger_engine 在主动推荐体系中的定位、模块职责与端到端交互过程。



一、trigger_engine 包内模块图


flowchart TD
    A[handler.py] --> B[runtime_ops.py]
    B --> C[(Proactive DB)]


二、trigger_engine 包内模块职责



1. handler.py
定位：统一入口层。





Invocation Hints



当用户出现下面这些说法时，应主动加载本 skill：



"写成飞书文档"
"先写到本地 md，后面贴飞书"
"按飞书格式输出"
"帮我整理成 Lark document"



项目文档存放规则（AData 项目）



在 AData 项目中生成的文档，遵循以下存放和命名规范：



存放位置

所有项目文档、学习笔记、分析文档、推送记录统一放在learn/ 目录下，网站会自动递归扫描并展示。




命名规范（推荐）



 文档类型  命名格式  示例 
--------- --------- ------
 需求/方案文档  learn/YYYY-MM-DD-简短标题/spec.md  learn/2025-01-15-截面选基重构/spec.md 
 专题学习笔记  learn/主题名/序号-标题.md  learn/截面选基-理解手册/01-理解系统.md 
 消息推送记录  learn/消息推送/push_YYYYMMDD_星期X.md  learn/消息推送/push_20250115_周三.md 
 临时草稿  learn/草稿-标题.md  learn/草稿-均线策略对比.md 



私密文档标记



如需标记为私密文档（后续做权限控制），可通过以下方式：

放在 learn/private/ 或 learn/私密/ 目录下

文件名以 private- 或 私密- 开头

在 md 文件顶部添加 private: true




生成文档时的 Checklist

文件保存到 learn/ 目录下（或对应子目录）


文件名使用有意义的名称，推荐加日期前缀
按飞书友好格式组织内容（标题层级、Mermaid 等）

新系统/新模块的文档，同步更新 .claude/CLAUDE.md` 中的「文档目录映射」表格

▶ 📜 变更历史（3 次提交）

4616ca62026-06-27 01:04docs: 同步 learn/ 文档 & 工作区改动

724828b2026-05-12 02:21feat: 设计截面策略方案

f0712912026-04-30 21:00feat: 增加lark doc与mermaid skill

🍃quant 知识库

by 伊甸园和枫

需求类型	典型场景	文档风格
---------	---------	---------
简单场景	单个模块/单条链路/小功能改动	结构清晰、突出重点、适当精简，3-5 个章节即可
中等复杂度	跨模块协作/新功能设计/选型对比	按骨架组织，每个模块展开讲职责和接口，7-10 个章节
大型系统设计	子系统/引擎/平台级设计	内容越丰富越详实越好，架构图、类图、流程图、时序图、数据流全上，10+ 章节

文档类型	命名格式	示例
---------	---------	------
需求/方案文档	learn/YYYY-MM-DD-简短标题/spec.md	learn/2025-01-15-截面选基重构/spec.md
专题学习笔记	learn/主题名/序号-标题.md	learn/截面选基-理解手册/01-理解系统.md
消息推送记录	learn/消息推送/push_YYYYMMDD_星期X.md	learn/消息推送/push_20250115_周三.md
临时草稿	learn/草稿-标题.md	learn/草稿-均线策略对比.md

Lark Document

Overview

When to Use

Core Rules

1. 输出目标

2. 标题层级

3. 标题文字格式

4. 正文格式

5. 列表格式

Mermaid Rules

1. 何时画图

2. 图文并存

3. Mermaid 输出格式

4. Mermaid 生成流程

Document Content Length

判断标准

核心原则

Recommended Document Shape

Writing Strategy

1. 先结论后展开

2. 先总图后分解

3. 先确认事实，再写风险

Final Checklist

Common Mistakes

Example

trigger_engine 能力梳理与跨端链路分析

文档目标

一、trigger_engine 包内模块图

二、trigger_engine 包内模块职责

1. handler.py

Invocation Hints

项目文档存放规则（AData 项目）

存放位置

命名规范（推荐）

私密文档标记

生成文档时的 Checklist

▶ 📜 变更历史（3 次提交）

🔊 播放设置

分享图片

`trigger_engine 能力梳理与跨端链路分析`