流萤简历如何让同一份资料同时服务编辑器、搜索与AI，关键在块级ID与多表示协议

在AI深度介入内容创作的当下，一个看似基础却常被忽视的问题浮现：同一篇资料，如何同时满足人类编辑、搜索引擎索引与AI模型理解三类不同“消费者”的需求？流萤简历作为一款面向求职者的AI资料工作台，其技术方案提供了一个具象化解答——它不依赖单一格式，而是构建了一套分层、可追溯、带身份标识的文档表示协议。

流萤的核心设计原则是明确“谁是权威”。系统将富文本内容以结构化HTML形式存储于sourceDocument字段，作为唯一可信源；而供AI推理、全文检索及人工核对使用的纯文本（content）则作为投影生成，属于有损派生。这一区分至关重要：当AI基于文本生成修改建议后，若直接将其写回为完整文档，原始格式信息（如表格合并单元格、Mermaid图表配色、提示块样式）将不可逆丢失，导致资料逐渐退化为无结构的纯文本。图2清晰展示了该架构：sourceDocument（富文本HTML）是中心节点，向下派生出content（文字投影）、answerDocument（逐题解答）、extensionDocument（拓展内容），并支持CLI工具与Tiptap编辑器双向同步。

为何不选择更友好的Markdown作为主存格式？流萤团队指出，尽管Markdown对人与AI输入友好，但在表达列宽控制、折叠区域、资源卡片、图表视图偏好等编辑器状态时存在表达力不足的问题。若将这些状态拆入独立JSON，又会引发“双真值”维护困境——修改表格时需同步更新Markdown与JSON，AI改写Markdown时又难以保留原JSON语义。因此，当前方案选择以HTML为持久化主干，接受其协作编辑粒度较粗（非字符级）、服务端需严格校验标签白名单等代价，换取文档状态的完整保真。

真正体现工程巧思的是“稳定块ID”机制。传统依赖数组下标（如“第4段”）的定位方式极易因插入/删除操作失效。流萤为每个顶层内容块（段落、标题、列表、表格、代码块）分配唯一的data-flowing-id，该ID在内容未变更时保持稳定，即使页面结构调整或段落顺序变动，目标块的身份仍可被准确识别。图3直观呈现了这一逻辑：页面UUID确保永久地址有效，而块ID则锚定内部结构单元；当用户插入新段落时，新增块获得新ID，原有块ID不变，AI调用Patch接口时必须提交完整顶层块及其ID，从而规避定位歧义。

值得注意的是，稳定ID并非权限凭证。系统仍需结合页面归属与角色校验进行访问控制——仅知道某块ID不能绕过权限检查，否则将把安全寄托于“UUID难猜测”这一脆弱假设上。

对于历史存量文档（无块ID），流萤采用惰性派生策略：服务端htmlBlocks()函数在首次读取时，依据内容哈希、位置与种子值生成确定性摘要作为临时ID；仅当文档实际被编辑后，才写入正式ID并触发版本递增。此举避免了批量初始化带来的无意义版本污染与协作冲突，也防止用户首次打开即弹出“保存提示”的负面体验。

该设计折射出当前AI原生应用开发的一个共性挑战：模型偏爱简洁、线性的文本输入，而真实工作流要求保留丰富结构与上下文。若产品层简单地将“便于AI读取的文本”当作权威源，就会陷入“越用越简陋”的退化陷阱。流萤的应对路径是承认多模态表示的必要性，并通过协议层明确各表示的角色边界——HTML负责保真，text负责分发，blocks负责定位，revision负责版本一致性。

这种思路已在多个专业场景显现价值。例如，在法律合同管理中，条款编号与交叉引用必须在AI摘要与人工修订间保持一致；在技术文档平台中，API参数表格的合并单元格若被转为纯文本，将导致下游自动化测试脚本失效。流萤的实践表明，真正的“AI-ready”文档系统，不是让文档迁就模型，而是为模型构建一套能理解结构、尊重变更历史的输入契约。

从更广视角看，随着RAG（检索增强生成）成为主流架构，向量数据库中存储的“chunk”若缺乏稳定身份标识，将难以支持增量更新与溯源审计。流萤的块ID机制为此类问题提供了可迁移的参考：当检索到某一块内容后，系统不仅应返回文本，还应携带其结构身份与版本上下文，使后续生成与修改具备可追踪性。

目前，该方案已支撑流萤简历中面经资料的全生命周期管理：用户可保留原始面试记录，AI生成逐题解答与知识拓展，所有内容仍可作为富文档继续编辑，标题、列表、表格、公式与Mermaid图表均完整留存，目录亦支持按页面嵌套组织。图1展示了其业务架构图中的实际应用——一份“流萤简历”的业务架构图被嵌入在文档内，既供人阅读，也作为AI理解上下文的结构化信号。

技术选型没有绝对优劣，只有适配场景的权衡。流萤的选择揭示了一个朴素事实：在AI与人类协同工作的前沿，文档本身已成为一种“接口协议”，其设计质量直接决定整个工作流的鲁棒性与可持续性。当一份资料能同时被编辑器精准修改、被搜索引擎高效索引、被AI可靠理解时，它才真正完成了从“静态文件”到“活数据”的跃迁。