feishu-writer

# 飞书高级写作助手 (Feishu Writer) 本技能用于生成极致专业、具有"人味"的飞书文档。写作规范依据 Aime 完整调研（2026-07-25）。 ## 🧭 与 lark-doc / lark-wiki 的协作分工 | 场景 | 用谁 | |------|------| | 创建 / 读取 / 局部编辑普通文档 | `lark-doc`（`lark-cli docs +create/+fetch/+update`） | | 知识空间节点管理、挂文档到 Wiki | `lark-wiki` | | 多维表格（项目追踪/字段表/风险登记册） | `lark-base` | | 复杂架构图（自由排版、SVG） | `lark-whiteboard`（`whiteboard +update`） | | **原生 Mermaid add_ons 块注入（block_type=40）** | **本技能 `add_mermaid.py`** | | **按正文文本定位 → 删除旧块 → 在锚点后插入新 Mermaid** | **本技能 `move_chart.py`** | | **把文档所有权从 bot 转给用户** | **本技能 `transfer_owner.py`** | | 长文方略、去 AI 味排版、视觉节奏 | **本技能（写作规范）** | **铁律**：本技能脚本是 lark-doc 的补充，不重新实现 `docs +create/+fetch/+update`。当用户的需求落在 lark-doc 已覆盖的通用操作上时，优先走 lark-doc；只有需要 add_ons Mermaid 块、按文本移动图、转移所有权时才用本技能脚本。 ## 🛡️ 核心铁律 (Hardlines) 1. **去 AI 味排版**： - 严禁署名（如 "by AI"）。 - 禁止在正文写进度信息。 - 标题要么纯中文，要么纯英文，禁止中英混杂（机翻感）。 - 严禁使用"1. 执行摘要"、"总结"等 AI 惯用语，必须严格遵守"黄金开局"（# 概述 → ## 背景 → ## 目标）；去掉所有章节数字编号（如 `## 1.`），保持专业感。 2. **黄金开局**：必须采用「封面+元信息+背景摘要 Callout」起手式（详见 [文档结构](#1-文档结构设计)）。 3. **视觉纵深（每篇必有图）**： - **每篇文档至少 1 张全景流程图/架构图**；核心 H2 章节尽量各配 1 张图（流程图/架构图/时序图/数据图表）。 - **素材配图**：若文档基于外部资料（论文/报告/网页）撰写，必须从资料中提取有价值的图（架构图、实验结果图、流程图等）插入正文，不要只有文字。详见工作流「写入阶段 · 章节配图」。 - 严禁扁平架构图。 - **Mermaid 优先**：流程图/时序图/ER 图优先使用 Mermaid（飞书原生渲染）。 - **架构图**：复杂架构图优先 Draw.io 导出 SVG；条件不允许时用 Mermaid 三层架构图模板（见 [references/diagram-templates.md](references/diagram-templates.md)）。 - **Mermaid 净化**：节点必须用双引号包裹 `A["节点名"]`，严禁包含斜杠或括号以防客户端崩溃。注入前必须剔除节点名中的 Emoji 和特殊符号。 --- ## 📐 写作规范（Aime 完整调研落地） ### 1. 文档结构设计 #### 1.1 开头（封面 + 元信息 + 背景摘要） ``` [封面区域] 文档标题（H1，全文唯一，名词短语《XXX 方案设计》） 副标题/一句话摘要（正文色弱化，斜体） [元信息区域] — 用表格或信息列表 - 作者 / 创建时间 / 最后更新 - 状态：🟡 草稿 / 🟢 已发布 / 🔴 已废弃 - 阅读对象：[目标读者] - 预计阅读时长：X 分钟 [背景摘要区域] — 用蓝色 Callout 📌 本文要解决的问题是 XXX，读完你将了解 A、B、C。 ``` 规则： - 标题必须回答"这篇文档是关于什么的"，避免"XXX方案v2"这种版本化标题 - 摘要 Callout 限制在 **3 句以内**，点明问题、解法、收益 - 元信息一定要有，方便追溯 #### 1.2 主体段落结构（"总-分-收"三段式） ``` H2 章节标题（说明这一节要回答什么问题） └─ 一句引导句：解释本节的核心结论或主旨（1句，加粗） └─ H3 子节 A → 正文内容 + 代码块/表格/图片 └─ H3 子节 B → 正文内容 └─ 小结句（1-2句，用斜体或引用块收尾） ``` **章节命名策略**： - **H1**：文档总标题，全文唯一，用名词短语（《XXX 方案设计》） - **H2**：主功能模块，用动宾或疑问句（"为什么要做 XXX"、"如何配置 XXX"） - **H3**：具体子话题，用名词或短句（"配置参数说明"） - **H4**：不推荐常规使用 #### 1.3 结尾收束 ``` H2 总结 / 下一步 [总结 Callout — 绿色 ✅] ✅ 本文核心结论： - 结论 A / 结论 B / 结论 C [下一步 / 待办] — 表格 | 行动项 | 负责人 | 截止时间 | 状态 | [相关链接] - 🔗 上游依赖：相关文档 A - 🔗 下游影响：相关文档 B - 🔗 参考资料：相关文档 C ``` ### 2. 排版样式 #### 2.1 字体与字号 | 层级 | 飞书对应 | 使用场景 | |------|----------|----------| | H1 | 标题1 | 文档主标题，全文唯一 | | H2 | 标题2 | 主要章节分割 | | H3 | 标题3 | 子话题 | | 正文 | 正文 | 所有正文内容 | | 说明文字 | 正文+斜体 | 注释、补充说明 | - 不推荐在正文中手动放大字号，破坏层级一致性 - 例外：封面大标题可手动加大到 H1 以上 #### 2.2 加粗 / 斜体 / 颜色 **加粗（Bold）** — 每段不超过 3 处： - ✅ 用于：核心结论句、重要名词、警告性内容、数字指标 - ❌ 不用于：整段加粗、标题 **斜体（Italic）** — 语气弱化/引用/补充： - ✅ 用于：术语初次出现、引用文献、补充注释 - ❌ 不用于：中文长段（可读性差） **颜色标注** — 全文不超过 3 种，每页不超过 5 处： | 颜色 | 用途 | |------|------| | 🔴 红色 | 错误、危险、禁止做的事 | | 🟡 橙/黄色 | 警告、注意事项、待确认 | | 🔵 蓝色 | 链接（系统默认） | | 🟢 绿色 | 正确做法、已完成状态 | | ⚫ 灰色 | 已废弃、低优先级 | #### 2.3 列表使用规则 - **无序列表**：并列关系，每条不超过 2 行，嵌套不超过 2 层 - **有序列表**：有执行顺序的步骤，每条末尾不加句号 - **引用块**：仅用于引用他人原话/文档，不用于自己的观点（用 Callout 代替） ### 3. 布局组件 #### 3.1 高亮块（Callout Block）— 飞书最核心的视觉组件 | 颜色/图标 | 使用语义 | 示例 | |-----------|----------|------| | 💡 黄色 | 提示、技巧、推荐做法 | 💡 这里有个更快的方法… | | ⚠️ 橙色 | 警告、注意事项 | ⚠️ 此操作不可逆 | | 🚫 红色 | 错误、禁止、高风险 | 🚫 不要在生产环境执行 | | ✅ 绿色 | 总结、已确认结论 | ✅ 本节核心结论 | | 📌 蓝色 | 背景说明、前提条件 | 📌 阅读本节前，请先了解… | | 📝 灰色 | 编辑备注、草稿注释 | 📝 TODO：此处待补充数据 | 规则： - 每个 H2 章节 Callout **不超过 2 个** - 连续 Callout 之间必须有正文间隔 - 不要用 Callout 包裹超过 5 行的大段正文 #### 3.2 折叠块 适合折叠：详细参数说明、历史版本、FAQ、长代码、附录 不适合折叠：核心结论、重要警告、关键步骤 命名规则：`▶ 展开：完整配置参数说明`，不要写"详情"、"更多" #### 3.3 分栏 | 场景 | 推荐分栏 | |------|----------| | 对比两个方案 | 2 栏 | | 并排展示图片 | 2-3 栏 | | 参数说明 | 不分栏，用表格 | | 移动端阅读 | 不分栏 | 规则：每栏正文不超过 200 字；不在分栏内再嵌套分栏；用于"视觉并排展示"，不用于"节省空间"。 #### 3.4 表格排版 - 表头加粗 + 浅灰底色（#F5F5F5） - 每列宽度按内容比例，不要全部等宽 - 状态列用颜色编码（🔴🟡🟢） - 超过 10 行加说明"共 X 项，按 XXX 排序" - 最多 6-7 列，超过请拆分 ### 4. 视觉层次与阅读节奏 **创造视觉纵深的 5 个手法**： 1. **留白节奏**：H2 前后各空一行，每 3-4 段插入视觉元素打断 2. **层级递进**：H1→H2→H3 不跳级 3. **对齐一致**：列表缩进方式统一 4. **视觉锚点**：每 500 字左右设置一个"小地标"（Callout/图/表/分割线） 5. **段落长度控制**：单段不超过 5 行 **标准 H2 章节节奏模板**： ``` H2 标题（锚点） ↓ 引导句（1句，加粗核心观点） ← 快速扫读者决定要不要继续读 ↓ 正文段落 A（3-4行） ↓ 视觉元素（表格/代码块/Callout）← 阅读减速带 ↓ 正文段落 B（3-4行） ↓ 小结/结论句（1-2句，斜体或 Callout）← 快速扫读者获得结论 ``` ### 5. 内容充实策略 #### 5.0 篇幅底线（反偷懒硬约束） **写少了就是没做完。** 一份正经文档不是"把要点列出来"就交差，读者要的是能读懂、能落地的深度内容。 | 文档类型 | 正文字数底线 | H2 章节数 | |----------|-------------|-----------| | 论文/技术方案解读 | **≥ 3000 字** | ≥ 5 | | 设计文档/研报 | **≥ 2500 字** | ≥ 4 | | 普通整理/纪要 | ≥ 1500 字 | ≥ 3 | - **每个 H2 章节正文不少于 300 字**，不能只有一句话 + 一张表就结束。 - **每个核心论点展开三层**：是什么 → 为什么/怎么做 → 举例/数据佐证。只写第一层就是偷懒。 - **表格/图不能代替正文**：图表是"减速带"，前后都要有文字讲清楚它说明了什么、边界在哪。见 gotchas「图多文少」。 - 如果自我感觉"好像写得有点短"，那就是真的短了 —— 回到每个章节按"所以呢？"再扩一轮。 #### 5.1 核心原则："所以呢？" **每句话都要回答"所以呢？"** — 每个论断后面必须跟 **数据/案例/原因/对比** 中的至少一个。 - ❌ 空洞写法：「我们采用了微服务架构。」 - ✅ 充实写法：「我们采用微服务架构，将用户服务、订单服务、支付服务解耦，单个服务故障不影响全局可用性，上线频率从每月 2 次提升到每天 10+ 次。」 #### 5.2 章节内容清单 | 章节类型 | 必须包含 | 加分项 | |----------|----------|--------| | 背景/问题定义 | 现状、痛点量化、为什么现在解决 | 历史背景、失败尝试 | | 方案设计 | 核心思路、方案对比、选型理由 | 架构图、伪代码、决策矩阵 | | 实施步骤 | 有序步骤、前置条件、预期结果 | 截图、示例输出、常见错误 | | 结论/总结 | 核心结论列表、量化收益、后续计划 | 风险与局限、Q&A | #### 5.3 数据嵌入策略 | 数据规模 | 呈现方式 | |----------|----------| | 1-2 个指标 | 行内数据，加粗：`延迟从 800ms 降至 120ms，降幅 85%` | | 2-4 个维度 | 2 栏布局或 before/after 表格 | | 5 个以上指标 | 嵌入多维表格图表（转交 lark-base） | 规则：数据必须注明来源；不要写没有对比基准的数据；估算数据用"约"、"~"标注。 #### 5.4 案例嵌入（STAR 简化版） ``` 📌 案例：[案例名称] - 背景：XXX 场景下，遇到了 YYY 问题 - 做法：我们采用了 ZZZ 方案 - 结果：最终达成 AAA 效果（量化） ``` 案例用 Callout（灰色/蓝色）包裹，多个案例用折叠块收纳。 ### 6. 飞书高阶特性 | 特性 | 触发场景 | 实现路径 | |------|----------|----------| | **多维表格（Bitable）** | 项目追踪/甘特图、风险登记册、接口字段表、问题 Backlog | 转交 `lark-base`；状态字段用"单选"🟢🟡🔴⚫，责任人用"人员"类型，截止日期开"到期提醒" | | **内嵌图表** | 指标趋势、资源分配饼图、任务进度条 | 多维表格录入数据 → 新建图表视图 → 嵌入正文 | | **公式块（LaTeX）** | 算法复杂度、统计公式、ML 模型公式 | 行内 `$...$`；块级用公式块 | | **目录块** | 长文档（超过 5 个 H2）必须插入 | 放在元信息表格之后、第一个 H2 之前，上方加分割线 | | **任务列表（To-do）** | 文档的"合同"，责任人必须填写 | `[动词+对象+验收标准]`，如"完成用户服务接口联调，通过压测报告" | | **代码块头部注释** | 所有独立代码段 | `# 文件：xxx.py / 作者 / 最后更新 / 用途` | | **关联文档** | 上游依赖/下游影响/参考资料 | `@文档名` 创建关联，不用粘贴 URL | | **版本与评论** | 里程碑评审 | 重要节点手动加版本备注；评审意见用"选中文字→评论"，不在正文写"【待确认】" | ### 7. 架构图与流程图 **按内容选图种（严禁一篇全是同款流程图，见铁律 3）**： | 要表达的内容 | 用哪种图 | Mermaid 语法 | |--------------|----------|--------------| | 系统由哪些模块组成、如何分层 | 架构图 | `flowchart` + `subgraph` 分层 | | 全局视角、整体链路一图看全 | 全景架构/全景流程图（每篇必有 1 张） | `flowchart LR/TD` + 多 subgraph | | 多角色/多系统按时间交互 | 时序图 | `sequenceDiagram` | | 跨部门/跨角色的流程流转 | 泳道图 | `flowchart` + 泳道 subgraph（模板库 #8） | | 有分支判断的处理逻辑 | 流程图 | `flowchart` + 菱形 `{}` | | 数据实体关系 | ER 图 | `erDiagram` | | 对象在生命周期里的状态流转 | 状态图 | `stateDiagram-v2`（模板库 #9） | **工具选型优先级**： 1. 流程图/时序图/ER图/状态图/泳道图 → **Mermaid**（飞书原生渲染，首选） 2. 系统架构图 → **Draw.io 导出 SVG**（保持矢量清晰度） 3. 快速草图/讨论稿 → **飞书白板**直接嵌入 **配色方案（字节/现代科技风）**： | 用途 | 色号 | 说明 | |------|------|------| | 主色（核心服务） | `#4A90D9` | 标准蓝，核心/主链路 | | 辅色（外部依赖） | `#7B68EE` | 中紫，第三方/外部系统 | | 成功/数据存储 | `#52C41A` | 绿色，数据库/缓存/存储 | | 警告/异步流程 | `#F5A623` | 橙色，消息队列/异步任务 | | 危险/失败路径 | `#FF4D4F` | 红色，错误处理/降级 | | 背景/分组区域 | `#F0F5FF` | 浅蓝，框定服务组 | | 文字（深色节点） | `#FFFFFF` | 白色 | | 文字（浅色节点） | `#262626` | 深灰 | **节点形状语义、流程图/时序图/ER 图/三层架构图完整模板**：见 [references/diagram-templates.md](references/diagram-templates.md) **图表嵌入最佳实践**： 1. Mermaid 直接嵌入：代码块 → 语言选 mermaid → 飞书自动渲染（首选） 2. SVG 优先于 PNG：Draw.io 导出 SVG，放大不失真 3. 图片必须加图注：`图 X：[图表标题]（[数据来源/创建时间]）`，用斜体正文 4. 大图用折叠块包裹：避免撑开页面 5. 不要截图代替矢量图：高 DPI 屏幕模糊 ### 8. 发布前 Checklist 发布前**必须**逐项检查 [references/writing-checklist.md](references/writing-checklist.md)。 --- ## 🛡️ 核心工作流 (Workflow) ### 1. 规划阶段 (Planning) - 超过 5000 字长文必须"分而治之"：先出提纲 → 标注章节字数 → 报备给用户。 - 任何文档先确定：① 目标读者 ② 状态（草稿/已发布）③ 预计阅读时长。 ### 2. 写入阶段 (Execution) - **分片注入**：每 20 个 Block 切割一次进行插入（单次上限 50）。 - **章节配图（关键，边写边配）**：每写完一个 H2 章节就立即检查是否需要配图，**不要等全文写完再补**——趁该章节上下文还在，当场画图或插图。图种速选： | 要表达的内容 | 用哪种图 | Mermaid 语法 | |---|---|---| | 全局链路/整体流程一图看全 | 全景流程图（每篇必有 1 张） | `flowchart LR/TD` + 多 `subgraph` | | 系统模块组成、如何分层 | 架构图 | `flowchart` + `subgraph` 分层 | | 多角色/多系统按时间交互 | 时序图 | `sequenceDiagram` | | 有分支判断的处理逻辑 | 流程图 | `flowchart` + 菱形 `{}` | | 数据实体关系 | ER 图 | `erDiagram` | | 对象生命周期状态流转 | 状态图 | `stateDiagram-v2` | 配图来源：① 自己画 Mermaid（首选）；② 从外部资料提取的图片（论文 Figure、报告截图等，用 `docs +media-insert` 插入）；③ Draw.io 导出 SVG。每张图后必须配一段文字拆解（见 gotchas「图多文少」）。 - **原生表格**：必须采用"原地 PATCH"法（读取 cell 内默认 block 并替换），严禁产生空行。 - **图片搬运**：严禁复制旧文档的 Token。必须先 `download` 到本地再 `insert`。 - **目录块**：长文档（>5 个 H2）必须在元信息表格后插入目录块。 ### 3. 发布前 (Review) - 按 [references/writing-checklist.md](references/writing-checklist.md) 逐项核对。 - 评审意见用"选中文字 → 评论"，不在正文写"【待确认】"。 - 评审通过后手动加版本备注（"v1.0 评审通过版"）。 --- ## 🧰 脚本工具箱 所有脚本均从 `~/.ethan/.secrets/my_feishu.json` 读取飞书自建应用凭证（`app_id` / `app_secret`），**绝不硬编码**。文件格式： ```json { "app_id": "cli_xxxxxxxxxx", "app_secret": "xxxxxxxxxxxxxxxxxx" } ``` 如果该文件缺失或字段不全，脚本会以非零退出码报错，不会回退到任何内置默认值。 ### `scripts/add_mermaid.py` — 注入原生 Mermaid add_ons 块 将一段 Mermaid 代码作为 `block_type=40` 的 add_ons 块追加到指定文档末尾（或指定 index）。适合需要"原生 Mermaid 渲染"而非 SVG 画板的场景。 ```bash