Feishu Readability

飞书文档格式优化与安全修改规范。**必须在通过MCP修改任何mi.feishu.cn文档之前加载此skill**。包括最小修改原则、富文本保护、段落间距、加粗规范。触发条件：用户要求修改飞书文档内容或格式，涉及mi.feishu.cn域名，或调用小米飞书MCP的update-doc工具。

Security Scan

The skill's instructions and requirements are largely consistent with its stated purpose (Feishu/Lark doc readability and cautious edits); it is instruction-only, asks for no installs or credentials, but has a few minor inconsistencies and operational risks you should review before use.

Purpose & Capability

Name/description state a narrowly scoped readability/formatting policy for mi.feishu.cn documents; the SKILL.md focuses on exact selection, spacers, and token preservation which matches that purpose. Minor inconsistency: the doc emphasizes a ‘minimal modification’ rule and preferring insert_before/insert_after, yet several concrete examples use replace_range — this is explainable but worth checking with the maintainer.

Instruction Scope

All runtime instructions stay within document editing scope: fetch-doc, analyze, and perform precise edits via the MCP update-doc calls. The skill explicitly warns to fetch tokens for paragraphs containing images/callouts and to preserve them — this is appropriate given the service’s tokenized rich-text model. It does not instruct reading unrelated files, system state, or exfiltrating data.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest-risk install posture. There are no external downloads, packages, or nonstandard installs.

Credentials

The skill declares no required environment variables or credentials, which matches the instruction-only nature. However, it assumes availability of MCP toolchains (mcp_FeishuMCP_update-doc, fetch-doc) and that those tools have the necessary permissions; the skill itself does not request or document the credential/permission scope it relies on, so verify that the platform-provided MCP integration will be limited to the intended mi.feishu.cn scope.

Persistence & Privilege

Skill is user-invocable and not always-on; it does not request elevated persistence or modify other skills or global agent settings. Autonomous invocation is allowed by default but not unusual; no 'always: true' or other high-privilege flags are present.

Assessment

This skill appears coherent for its stated job: improving Feishu doc formatting with precise, token-aware edits. Before installing: (1) Confirm your agent/platform provides the MCP fetch-doc/update-doc tools and review the exact permissions those tools will have (limit to mi.feishu.cn if possible). (2) Test the skill on a copy of a document first — some examples use replace_range which can remove content if selection context is wrong. (3) Verify that image and other rich-text tokens are preserved by fetch-and-rewrite flows as described. (4) Ask the skill author to clarify the replace_range vs insert_before/after guidance to avoid accidental wide replacements. If you require stricter assurance, request an explicit permissions list for the MCP integration and a small test run log before using it on production documents.

飞书文档可读性优化 Skill

概述

本 Skill 旨在解决飞书云文档（Lark Doc）在自动化编辑中常见的格式问题，重点提升文档的视觉层次感和可读性。它基于对飞书 Markdown 渲染引擎底层逻辑（API vs. 交互式编辑）的深入理解，提供了一套经过验证的“最佳实践”。

🏆 三大核心原则

1. 🚀 核心铁律：最小修改原则 (The Principle of Minimal Modification)

权重：最高 (Critical) 定义：任何格式优化都必须是“手术刀式”的精准微调，严禁因为修改一个标点而重写整个段落，更不可重写整篇文档。

❌ 绝对禁止：

• 严禁使用 overwrite 模式：除非旨在清空文档重写，否则绝不允许使用 overwrite 进行修改，这会导致评论、历史记录、图片 Token 和未知的富文本属性丢失。
• 严禁大范围选区：selection_with_ellipsis 不得跨越多个不相关的段落或标题。
• 严禁盲目重构：不得在未获取该段落完整 Token（如图片、公式）的情况下重写包含该 Token 的段落。

✅ 最佳实践：

• 字节级定位：selection 应短至仅仅包含“待修改目标 + 确保唯一的最小上下文”。
  • ✅ 优秀：selection="token=\"xxx\"...**标题" （利用 Token 定位）
  • ✅ 优秀：selection="。**下一标题" （利用标点定位）
  • ❌ 错误：selection="上一段开头...下一段结尾" （范围太广，极易误伤）
• 增量操作：优先使用 insert_before / insert_after 插入内容，而非 replace_range 替换内容。
• 格式隔离：确保修改后的 Markdown 文本与原文在“未修改部分”完全一致（包括此时看不到的隐藏字符）。

2. 间距法则 (The Law of Visual Spacing)

权重：高 (High) 问题：API 写入的 Markdown 纯文本会被飞书解析器进行“空白清洗”（Whitespace Optimization），导致标准的空行被合并，文档显得拥挤。

✅ 解决方案：使用 带属性的占位段落 {align="center"}。 只有带有非默认属性（如 Center）的空段落，才会被解析器视为“有意义的内容”而强制保留。

📜 书写规范（基于最小修改原则）：

1. 插入式注入：使用 insert_before 在标题前插入 Spacer，而非 Replace 整个标题块。
2. 必须以空格开头： {align...（无空格会被渲染为乱码文本）。
3. 列表后阻断：若前文是列表，必须使用 双换行 \n\n 先结束列表，再插入标记。

3. 本土化格式卫生 (Formatting Hygiene)

权重：中 (Medium)

加粗规范：

• 冒号隔离：加粗必须止步于冒号之前，且冒号后必须有空格。
  • ✅ 正确：**标题**： 正文（推荐：冒号在加粗外，且有空格）
  • ✅ 可行：**标题：** 正文（若必须在内，冒号后必须分开）
  • ❌ 错误：**标题：**正文（粘连）

列表标点规范：

• 单句无标点：若列表项仅有一句话，去掉末尾的句号。
• 富文本保护：
• 定位时务必避开 <image>、<callout> 等标签。
• 若必须修改包含标签的段落，需先 fetch-doc 获取 Token，并在 markdown 参数中原样写回。

---

🛠️ 标准操作流程 (SOP)

第一步：诊断 (Fetch & Analyze)

获取文档内容，重点检查：

1. 标题前是否拥挤（特别是列表后的标题）。
2. 加粗格式是否粘连。
3. 是否存在特殊的富文本块需避开。

第二步：间距注入 (Spacer Injection)

使用 replace_range 在目标位置精确插入 Spacer。

场景 A：标准标题前（H1-H3）

mcp_FeishuMCP_update-doc(
    mode="replace_range",
    selection_with_ellipsis="前文结尾。\n## 标题", 
    markdown="前文结尾。\n\n {align=\"center\"}\n\n## 标题"
)

场景 B：列表后的标题（高风险点）

mcp_FeishuMCP_update-doc(
    mode="replace_range",
    selection_with_ellipsis="- 列表项结尾\n## 标题",
    # 注意：双换行 + Spacer + 双换行
    markdown="- 列表项结尾\n\n {align=\"center\"}\n\n## 标题"
)

第三步：格式精修 (Refinement)

修复粘连的加粗或排版错误。

mcp_FeishuMCP_update-doc(
    mode="replace_range",
    selection_with_ellipsis="**粘连标题**正文",
    markdown="**粘连标题：** 正文"
)

---

❓ 故障排除速查

现象	原因	解决方案
页面显示 {align="center"} 文字	缺少起始空格	替换为 {align="center"}
标题依然拥挤	列表后未双换行，或 Spacer 未独立占行	确保前后都有 \n
出现 width="100" 乱码	破坏了 <image> 标签	Undo，重写时保留完整 Token
段落莫名消失/重复	replace_range 范围太大或定位不准	缩小定位范围，包含更多唯一的上下文标点

---

✅ 执行前核对清单 (Pre-flight Checklist)

1. 定位准确性：selection_with_ellipsis 是否足够短且唯一？
2. 上下文安全：选区内是否包含了图片或引用块？（如有，需特别小心）
3. Spacer 格式：是否检查了 {align="center"} 的空格和换行？
4. 列表处理：前文如果是列表，是否加了 \n\n？