胶囊系统主流程需求简报HERMES & AGENT ENGINEERING · 课时 07

# 胶囊系统主流程需求简报

> 用途：作为 `$speckit-specify` 的输入，生成胶囊系统第一版 SPEC。
>
> 来源：`gingery-wiki/hermes-logamee/book/第10章-胶囊系统：让知识真正进入你的思考`。
> 本简报以该章的系统设计为来源，并纳入后续对版本范围、媒体资料和证据保留规则所做的裁剪，同时以项目宪章为最高约束。

## 要解决的问题

1. 资料被收藏或保存以后，往往只是在系统里多了一条孤立记录。随着时间流逝，资料越积越多，知识结构却没有随之成长。

2. 大量资料堆积在一起，查询和重新使用都不方便。

3. 资料没有得到精炼和融合，系统里会留下很多重复或无效的记录。

胶囊系统要解决的不是“把资料放到另一个收藏夹”，而是让外部资料经过接收、证据固定、索引管理、关系理解和知识页演化，逐渐变成用户可以反复阅读、引用和修正的个人 Wiki。胶囊系统不追求大而全，追求的是清晰、有序、不乱。用户每次提交资料后，系统都应给出明确的证据处理结果：已生成文字证据、不生成文字证据或待用户确认。

## 使用者

本次先考虑个人用户。资料提交者、知识页使用者和不可逆操作的最终确认者是同一个人。

这也决定了项目的**底色**：它是一个服务个人学习和记录的知识库，不是用于生产、审计或合规场景的企业证据系统。第一版允许一定程度的来源缺失，并且不接管 PDF、图片、音频和视频等原始媒体文件。

## 期望结果

一份资料进入系统后，不能停在“保存成功”。系统必须保留可核对的证据，记录处理状态，判断它与已有知识的关系，并让相关知识页产生可解释的变化。

用户最终接触到的主要成果不是资料列表，而是持续演化的主题页和概念页。符合条件的资料统一转换成文字形式的衍生证据；资料存在来源 URL 时，另外保存该 URL 作为原始证据。没有 URL 时，PDF、图片、音频或视频等原始文件不作为证据保存，也不进入常规检索、引用和知识页演化流程。

对于系统无法识别、无法归类或无法演化的资料，不能直接放弃。系统应当说明流程停在了哪一步、为什么无法继续，并给出可以采取的处理建议，然后将它送入统一的审核队列。知识冲突和需要用户确认的删除等不可逆操作，也由这个队列统一处理。用户作出决定后，系统根据已保留的处理记录和用户新增的信息从中断处继续。如果资料没有 URL，而后续判断仍需要原始内容，用户需要重新提交资料；用户也可以决定终止本次处理。

在资料内容层，系统只持久保存文本内容和来源 URL，绝对不保存任何非文本附件。PDF、图片、音频和视频都是一次性处理输入。系统只在本次处理中读取它们，不会把原始文件复制进内部存储，也不负责后续保留或删除。原始文件仍由用户在原来的位置管理；如果不再需要，由用户自行删除。

这条限制也适用于 Wiki 知识页。Wiki 可以展示表格、流程图或关系图，但保存的源内容必须是文字。系统不保存或嵌入网页原图，也不通过外部图片地址把原图直接显示在 Wiki 中。

## 系统要完成的主流程

### 1. 接收资料

用户可以把纯文本、PDF、独立图片、音频、视频或网页 URL 交给 Hermes。Hermes 是胶囊系统的交互入口，具体从终端还是已接入的消息渠道提交，不改变后续处理规则。
第一版中的复合资料只指网页；Word、Excel 和 PowerPoint 等其他文件格式暂不处理。

系统首先处理能够直接确认的重复，例如相同 URL、相同文件或相同消息。入口去重只负责拦截确定性重复，不能代替后续对内容价值的判断。

### 2. 固定证据

资料进入系统后，系统先判断它能否形成证据。符合条件的资料需要转换成可检查、可引用的文字，再进行总结或理解。这份清理、提取后的文字称为衍生证据。

- 纯文本保留原意。
- PDF 一律提取或 OCR 成文字，不处理其中的图片，PDF 文件不作为证据保存。
- 独立图片只有在自身能够完整、独立地表达知识时，才生成衍生证据；无法判断时进入审核队列。用户同时提交正文、图注或说明时，需要把图片与这些文字放在一起理解，不再按独立图片判断。原始图片不进入证据层。
- 独立音频和视频处理方式同独立图片一致，转写、清理成文字；如果用户同时提交补充说明，需要把补充说明与独立音频视频一并判断。原始媒体文件不进入证据层。
- 网页只保存页面 URL，不单独保存图片 URL，同时抽取并清理正文。装饰性图片，或者只是重复正文的图片，直接忽略。图片包含正文无法替代的信息，并且系统能够可靠识别时，将其转换成文字、表格或文本定义的图形。如果无法可靠转换，图片不进入衍生证据和 Wiki；图片不影响正文理解时，记录省略结果并继续处理，网页的核心内容依赖该图片时，将处理结果标记为证据不完整并送入审核队列。

原始证据只保存 URL。资料有 URL 时，将它与衍生证据关联；没有 URL 时，不建立原始证据。不将原始载体保存为证据，是本项目作为个人学习与记录工具所做的范围裁剪。系统也不会为了等待人工审核而保存一份原始文件副本。衍生证据和后续生成的知识页必须分开，知识页的改写不能反向覆盖证据。

### 3. 建立资料索引

每份进入系统的资料都需要有可持续读取的索引记录。索引用于说明资料从哪里来、是否生成了衍生证据、当前处理到哪一步、关联哪个主题、是否参与了知识页演化。有来源 URL 时，索引还要与该 URL 关联。

索引是证据与知识页之间的连接，也是中断后继续处理的依据。处理判断不能只存在于一次对话中。

资料处理、知识冲突或不可逆操作进入待确认状态时，索引还要记录审核类型、中断位置、原因和处理建议。对于有 URL 的资料，系统可以根据用户反馈重新读取来源；如果没有 URL，索引只保留处理记录，不保留原始文件。后续判断仍然需要原始内容时，用户需要重新提交资料。

### 4. 理解资料关系

Hermes 读取证据后，需要形成结构化的理解结果，至少回答：

- 资料涉及哪些主题，应该进入已有主题还是形成新主题。
- 资料中真正有价值的关键观点是什么。
- 它与已有资料或知识页有哪些重复。
- 它补充了哪些新解释、新例子、新边界或新场景。
- 它是否修正或挑战了已有判断，冲突具体发生在哪里。

理解层负责回答“它与现有知识是什么关系”，但不会进行演化与融合（只判断）

### 5. 演化知识页

系统根据理解结果更新长期存在的 Wiki 页面。更新必须是重新组织和融合，而不是把
“新增资料摘要”追加到页面末尾。

第一版的知识页分为两类：

- **主题页**：围绕一条可长期维护的知识线组织内容。新资料进入后，主题页可以延伸边界、补充案例、删除重复表达或校正旧判断，但仍应保持为一篇结构完整的文章。
- **概念页**：解释一个会被多个主题复用的基础概念，重点说明定义、边界、相近概念和典型用法，避免各主题页重复解释。

新资料可以同时影响主题页和概念页。系统必须判断应该新建还是更新页面，并控制页面粒度：
主题页不能粗到退化成资料仓库，也不能细到退化成标签列表。

Wiki 中的图形化内容也必须遵守纯文本保存规则。系统可以把衍生证据重新组织成 Markdown 表格、Mermaid 图或 ASCII 图，再由 Wiki 渲染成可视内容。这些内容的保存源必须能够回到文字，不得用原图副本或外部图片链接代替。

### 6. 进入审核队列

后文统一把这组等待用户决定的记录称为**审核队列**，其中每条记录称为**审核项**。它不代表一个必须实现的页面，只表示系统已经暂停处理，正在等待用户完成系统无法代替的判断。第一版先处理三类情况：

- 系统无法识别、归类或演化资料，流程中断。
- 新资料与已有知识冲突，系统无法自动决定如何采纳。
- 系统建议删除已保存的原始证据 URL 或衍生证据，或者执行其他不可逆操作，需要用户确认。

每个审核项都要展示审核类型和中断位置，说明失败或冲突的原因，并给出可用的来源 URL、衍生证据和已保留的处理信息。如果已经影响了某个主题页或概念页，系统还要展示受影响的页面、证据分析、处理建议，以及每个选择可能产生的后果。

用户可以补充上下文、重试、指定主题、重新提交资料或终止处理。没有 URL 且后续判断仍需要原始内容时，用户必须重新提交原始资料。面对知识冲突时，还可以保留双方观点、限定各自的适用条件、采纳其中一方或暂缓处理；面对不可逆操作时，则可以确认或拒绝。

## 资料采纳、重复与冲突

入口去重和内容去重必须区分：

- 入口去重处理相同 URL、文件或消息等确定性重复。
- 内容去重判断一份不同资料是否给现有知识带来新增价值。

只要资料补充了一个有效例子、边界、解释或修正，就视为参与了本次演化，并只融合新增部分。对当前知识页没有任何帮助的资料可以标记为“不被采纳”，不再进入主题演化，但系统必须保留其处理记录和判断理由。

这里的“采纳”与前面的证据处理结果不是同一个判断。前者决定某项内容是否参与知识页演化，后者决定当前输入能否形成文字证据。

冲突内容不能被静默覆盖或强行合并。系统需要指出被挑战的既有判断、冲突的新观点以及双方证据，再生成审核项，交由用户决定如何处理。在用户作出决定以前，相关知识页应当保持可核对，已有判断不能被新观点直接改写。

系统可以建议不采纳或删除已保存的证据，但删除建议必须生成审核项。未经用户针对明确对象作出确认，系统不得永久删除已经建立的原始证据 URL 或衍生证据。“不参与演化”“不被采纳”“建议删除”和“永久删除”必须是不同的处理结果。用户在系统之外手动删除原始媒体文件，不属于这里讨论的证据删除。

## 用户能够看到什么

一份资料进入系统后，用户应能够：

1. 查看该资料当前的处理状态和系统判断理由。
2. 资料已经生成衍生证据时，找到并阅读这份证据；资料存在 URL 时，还能回到原始来源。
3. 资料参与知识页演化时，知道它关联或创建了哪些主题。
4. 资料参与知识页演化时，知道它更新了主题页还是概念页。
5. 看出哪些内容被采纳、哪些内容重复、哪些内容存在冲突。
6. 已经更新知识页时，打开页面后看到的是融合后的完整内容，而不是新增资料列表。
7. 在统一的审核队列中，看到哪些资料处理中断、哪些知识存在冲突，以及哪些不可逆操作等待确认。
8. 打开审核项后，看到中断位置、原因、证据分析、受影响的知识页、系统建议和不同选择的后果。
9. 待确认资料没有 URL 时，知道系统没有保留原始文件；如果继续判断仍需要原始内容，需要重新提交资料。
10. 回看自己作出的审核决定，以及系统根据该决定产生的后续处理结果。
11. 网页图片未能转换时，知道哪些信息被省略，以及本次处理是否因此被标记为证据不完整。
12. Wiki 中的表格和图形化内容都能够回到文本源继续编辑，不依赖系统保存或外部引用的原始图片。

## 必须遵守的约束

1. 已经生成衍生证据并被采纳的资料，不能只新增一条记录后结束，必须继续完成关系判断和知识页演化。
2. 知识页中的重要判断必须能够回到相关的衍生证据核对；存在原始证据 URL 时，还应保留对应关系。
3. 整理后的知识页不能替代或覆盖证据。
4. 原始证据只保存 URL；没有 URL 时，不得把 PDF、图片、音频或视频文件保存为原始证据。
5. 在资料内容层，系统只能持久保存文本内容和来源 URL，不得保存任何非文本附件。PDF、图片、音频和视频只是一次性处理输入；系统不得为了归档或人工审核而复制、保存、管理或删除这些原始文件，原始文件由用户自行管理和删除。
6. 网页原图不得进入证据层或 Wiki，也不得通过外部图片地址直接嵌入。只有能够可靠转换的图片信息，才能以文字形式进入衍生证据。
7. Wiki 可以渲染表格、流程图和关系图，但这些内容必须以文本作为可保存、可编辑的源，不得依赖图片附件。
8. 自动判断可以决定资料是否参与本次演化，但不能自动永久删除已保存的原始证据 URL 或衍生证据。
9. 所有采纳、不采纳、重复和冲突判断都必须留下可检查的结果和理由。
10. 系统在无法识别、无法归类或无法演化资料时，必须记录中断位置和原因，给出处理建议，并送入审核队列，不得静默放弃。
11. 系统无法自动处理的知识冲突，以及需要用户确认的不可逆操作，都必须进入审核队列。
12. 系统规则必须稳定执行，不能只依赖当前对话里的临时约定。
13. 需求阶段不预先决定数据库、接口、页面框架、脚本语言或具体工具实现。

## 本次不处理的事情

- 不把胶囊系统做成只会关键词检索或临时生成回答的普通 RAG 系统。
- 不把每份资料保存成一篇孤立摘要。
- 不处理 PDF 中的图片，也不归档或管理 PDF、图片、音频和视频等原始文件。网页原图同样不进入证据层和 Wiki。
- 不接收 Word、Excel、PowerPoint 等第一版范围之外的文件格式。
- 内化层不属于第一版 SPEC 的实现和验收范围。综合页属于内化主题，它围绕用户提出的具体问题，将多个主题页、概念页和关键证据组织成可复用回答，并保留其引用关系。这项需求暂存于 Product Backlog，后续单独生成 SPEC。
- 当前判断、全局主题索引以及在写作和方案中主动调用知识页，暂存于 Product Backlog，后续确定方案后再单独生成 SPEC。
- 不实现企业级的多级审批、角色权限和复杂审核流程。第一版的审核队列只服务于个人用户的最终判断。
- 不在本需求简报中展开技术选型、数据模型、接口设计和任务拆分。

## 希望验证的结果

使用一组包含新增、重复、补充和冲突关系的真实资料，再加入无法识别、无法归类和无法演化的样例，完整执行主流程后，应当能够验证：

1. 每份提交的资料都有明确的处理状态和可读取的处理记录；符合条件的资料会生成可核对的衍生证据。
2. 对进入关系理解的资料，系统能够说明它与已有主题的关系，而不是只生成资料摘要。
3. 被采纳的内容真正融合进对应知识页，页面仍然是一篇结构完整的文章。
4. 重复表达没有被反复写入知识页，新增价值没有因去重而丢失。
5. 冲突观点及其证据保持可见，旧判断没有被静默覆盖，同时系统会产生审核项，等待用户决定如何处理。
6. 用户能够看出资料影响了哪些主题页或概念页，以及为什么这样处理。
7. PDF 能够形成文字证据，其中的图片不参与处理，PDF 原文件不会进入证据层。
8. 独立图片只在能够完整、独立地表达知识时才生成衍生证据；无效图片不生成证据，无法判断的图片进入审核队列。
9. 音频、视频和网页都会形成清理后的文字证据，媒体文件不作为证据保存；有 URL 时，处理结果与该 URL 保持关联。
10. 网页中的装饰性图片和重复正文的图片会被忽略；能够可靠识别的有效信息会转换成文字、表格或文本定义的图形。如果网页核心内容依赖无法可靠转换的图片，本次处理会被标记为证据不完整并进入审核队列。
11. Wiki 可以把文本渲染成表格、流程图或关系图，但不保存或外部引用网页原图，所有图形化内容都能够回到文本源继续编辑。
12. 任何不采纳或建议删除的资料，在用户确认前都不会导致已保存的原始证据 URL 或衍生证据永久丢失。
13. 系统无法继续处理资料时，会给出原因和建议，并在审核队列中生成一个待办项。
14. 审核队列能够区分处理中断、知识冲突和不可逆操作，并展示作出决定所需的证据、影响范围和系统建议。
15. 用户补充了继续处理所需的信息或作出选择后，流程可以从中断位置继续。没有 URL 且继续判断仍需要原始内容时，系统会请用户重新提交资料；用户也可以决定终止本次处理。这些决定和后续结果都会被保留。
16. PDF、图片、音频和视频不会被复制到系统中用于归档或人工审核。处理结束后，原始文件仍由用户自行保留或删除，系统不会管理这些文件的生命周期。
17. 即使一次对话中断，Hermes 也能根据证据、索引和知识页继续处理。
18. 用户可以从知识页重新阅读和使用已经融合的知识，而不必每次从原始资料重新开始。

## 生成 SPEC 时的要求

生成的 SPEC 应围绕上述完整主流程组织可独立验收的用户场景，并明确主题页和概念页的区别。用户故事应围绕用户目标组织，不要把 PDF、图片、音频和视频等每种输入机械地拆成独立故事。不同媒体的处理差异，应展开为可验收的场景、功能需求和边界情况。网页图片还要分别覆盖忽略、可靠转换和无法可靠转换三种结果，并验证 Wiki 中的图形化内容只保存文本源。

审核队列也要展开成可验收的用户场景。SPEC 需要分别覆盖处理中断、知识冲突和不可逆操作，明确用户如何看到判断依据、作出决定，以及系统如何从中断位置继续或终止处理。SPEC 还必须验证系统不会为了归档或人工审核而复制原始媒体文件，也不会删除用户自行保管的原始文件。

SPEC 必须检查下面八条约束：

1. 已经生成衍生证据并被采纳的新资料，必须继续完成关系判断和知识页演化，不能只增加一条记录。
2. 所有需要保存的媒体证据都必须转换成文字形式的衍生证据；原始证据只能是 URL。
3. 未经用户确认，系统不得永久删除已保存的原始证据 URL 或衍生证据。
4. 无法识别、归类或演化的资料必须进入审核队列，SPEC 需要明确原因、建议、用户决定和后续处理结果。
5. 无法自动处理的知识冲突和需要用户确认的不可逆操作，也必须进入审核队列。
6. 在资料内容层，系统只能持久保存文本内容和来源 URL，不得保存任何非文本附件。PDF、图片、音频和视频只是一次性处理输入；系统不得为了归档或人工审核而保存它们，也不负责删除用户持有的原始文件。
7. 网页原图不得保存或嵌入证据层和 Wiki；网页的核心内容依赖无法可靠转换的图片时，必须标记为证据不完整并进入审核队列。
8. Wiki 中的表格和图形化内容可以被渲染为可视结果，但必须以文本作为可保存、可编辑的源，不得依赖原始图片或外部图片地址。

SPEC 不应在需求阶段替项目决定具体存储产品、字段、接口或技术实现。