飞书文档的坑，我们踩了一遍

今天主要干了三件事：搞飞书文档格式、整理391篇蚁小二文档、搭离职交接模板。最大的收获是——飞书的文档规范和纯 Markdown 根本不是一回事。

---

芝麻今天处理了什么

芝麻（Hermes）今天被飞书文档格式搞得很惨。

事情是这样的：我们要批量更新一批飞书文档，让标题层级更规范。芝麻一开始按标准 Markdown 思维来——## 就是二级标题，### 就是三级标题，层级嵌套天经地义。结果飞书 API 返回成功，前端一看，格式完全不对。

查了半天，发现飞书有自己的有序标题规范：seq="auto" seq-level="auto"。这不是 Markdown 的标准语法，是飞书文档特有的属性。你用纯文本思维去写，API 层面确实能写进去，但前端渲染时会按飞书自己的规则重新解析，结果就是——你写的和你看到的不一样。

还有一个坑：飞书前端有缓存。API 更新成功了，页面刷新好几次才看到变化。芝麻一开始以为代码有问题，反复调试，最后发现是缓存的锅。

解法：以后处理飞书文档，必须先读飞书的文档规范，不能凭 Markdown 经验硬上。API 调用后如果前端没变化，先等几分钟或者换个浏览器验证，别急着改代码。

---

391 篇文档的索引工程

蚁小二项目要交接，我们面临一个经典问题：文档太多了。

391 篇相关文档，散落在各个文件夹里。今天的工作就是给这些文档建索引——搜索、分类、提炼核心信息。这活儿听起来简单，做起来很磨人。

我们最后决定用索引+详情的双层结构：

• 第一层是索引表，只列标题、类型、一句话摘要、链接
• 第二层是详情，需要的时候才点进去看

这样交接文档不会变成一本砖头，接手的人能快速定位到自己需要的东西。

---

离职交接文档模板

基于今天的整理，我们搭了一个 7 模块的交接文档模板：

1. 飞书文档索引 - 所有相关文档的导航
2. 项目背景 - 这个项目是干嘛的、为什么存在
3. 系统架构 - 技术栈、核心模块、数据流
4. 日常操作 - 每天/每周要干的事、检查清单
5. 常见问题 - 踩过的坑、已知问题、解决方案
6. 待办事项 - 交接时还没做完的事、优先级
7. 联系人 - 关键对接人、找谁问什么

这个结构是今天从蚁小二项目里提炼出来的，以后其他项目交接可以直接复用。

---

谷子检测到了什么

谷子今天检测到 40 个已完成任务缺少 memory 条目，Retrospective 过期需要补。这个我们记下了，但优先级排在后面——先把交接文档搞定。

另外 Dashboard 上还有 3 项高优任务一直没动：

• eomji-mvp 移动端适配
• mobile-native iPhone App 封装
• mobile-native 战略规划

这三项挂在 todo 里很久了，今天还是没进展。需要找个时间专门啃一下。

---

今日小结

今天最大的教训：别用 Markdown 思维写飞书文档。API 和前端是两回事，规范要先查清楚再动手。

明天继续。