Hyper-Extract CLI 工作流
定义
Hyper-Extract CLI 工作流 是在 Hyper-Extract 中围绕 he 命令行工具组织知识抽取与后续使用的一套完整流程。它的核心对象不是单次大模型调用，而是四类可持续操作的对象：
- 文档输入：被抽取的原始材料，如论文、传记、合同等。
- Knowledge Abstract：
he parse生成的知识抽取结果，是后续增量补充、展示、检索、问答与导出的中心对象。 - 索引：由
he build-index为既有 Knowledge Abstract 建立或重建的检索结构，供语义搜索与问答使用。 - 导出或落盘结果：把 KA 持久化到磁盘，或导出为适合外部知识管理工具消费的结果。
因此，这个工作流强调的是“知识库生命周期”而不是“跑一次抽取命令”。同一个 KA 可以先创建，再逐步补充，再建立索引，再用于搜索、问答、可视化与导出。
在本文档中的语境
在 CLI 文档语境中，he 被定义为一个可直接从终端完成知识抽取的命令行接口，且官方把典型流程明确拆成四个阶段：Create、Enhance、Explore、Save。这个分阶段设计说明 Hyper-Extract 的 CLI 并不把抽取视为终点，而是把抽取结果当作可维护资产持续操作。
对应命令大致如下：
- Create：
he parse - Enhance：
he feed、he build-index - Explore：
he show、he search、he talk - Save：
he dump，以及常见的he export obsidian这类导出操作
除了主线命令，he info、he clean、he list、he config 等命令则承担管理与辅助作用。
四阶段结构
1. Create：用 he parse 创建 Knowledge Abstract
工作流的起点是把一个或多个文档输入交给 he parse，生成一个 Knowledge Abstract。
基本形式包括：
he parse document.md -t general/biography_graph -o ./output/ -l enhe parse paper.md -t general/concept_graph -o ./paper_kb/ -l enhe parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l en
这里有几个重要点：
-t指定模板。CLI 文档把模板作为大多数用户的推荐方式，因为它们是面向领域场景预配置好的抽取方案。-o指定输出位置，也就是生成 KA 的目标目录。-l指定语言，例如en或zh。文档明确说明模板支持多语言，而 method 模式的提示词始终使用英文。
文档还给出另一种入口，即 method：
he parse doc.md -m light_rag
但在工作流层面，不论使用模板还是 method，Create 阶段的本质都相同：从文档生成一个可继续演化的 KA。
2. Enhance：用 he feed 增量补料，用 he build-index 建立索引
Create 之后，KA 并不是静态结果。CLI 文档把增强阶段定义为两个动作：
he feed：向既有 Knowledge Abstract 增量加入文档he build-index：建立或重建搜索索引
he feed 的意义
he feed 的核心价值，是不必为了加入新材料而重新处理全部文档。也就是说，已有 KA 可以在原有基础上继续吸收新文档，形成增量更新，而不是每次都从零重新 parse 全量数据。
这对持续积累资料尤其重要。例如一个研究主题的文献会不断增加、一个人物传记会不断补充新来源、一个合同集合会持续引入新版本；此时 he feed 允许在既有知识抽取结果之上继续添加资料，降低重复处理成本。
CLI 文档也把“Feed incrementally — Add documents over time without reprocessing”列为最佳实践之一，说明增量补料不是边角功能，而是推荐使用方式。
he build-index 的位置与作用
he build-index 用于为 KA 建立或重建索引。命令参考中给出的常见参数是：
-f：强制重建索引
这里的索引不是可有可无的附属物，而是 Explore 阶段里语义能力的前置条件。官方最佳实践明确写出：必须构建索引，搜索与聊天功能都需要它。
换言之：
- 仅有 KA 时，可以做基础展示类操作。
- 需要语义检索或问答时，必须先有索引。
3. Explore：可视化、语义搜索与基于 KA 的问答
Explore 阶段对应三类使用方式：
he show：可视化知识结果he search：在 Knowledge Abstract 中做语义搜索he talk：围绕 Knowledge Abstract 进行问答或对话
he show：直接面向 KA 的可视化
he show 的定位是“Visualize knowledge graph”。它直接利用 KA 进行展示，不依赖索引这一中间层。
因此，在四阶段结构里，he show 的输入是 KA，而 he search 与 he talk 的输入是索引。这一差异很关键：可视化和语义检索不是同一种能力，前者更接近结构浏览，后者依赖索引支持。
示例场景：传记抽取后可执行：
he parse biography.md -t general/biography_graph -o ./bio_kb/ -l enhe show ./bio_kb/
这个例子说明在人物传记场景中，KA 可以被直接可视化，用来查看人生事件等结构化信息。
he search：依赖索引的语义搜索
he search 的定义是“Semantic search in knowledge abstract”，常见参数为：
-n：返回 top-k 结果数量
但文档同时强调，搜索功能要求先建立索引。这意味着没有 he build-index 时，用户不能获得完整的语义检索能力。
示例场景：合同抽取后查找终止条件：
he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l enhe search ./contract_kb/ "termination conditions"
这个例子的语义是：先抽取合同义务相关知识，再对既有结果搜索特定条款，如终止条件。若未建立索引，则这一检索能力不完整，甚至不可用。
he talk：依赖索引的问答接口
he talk 的定义是“Chat with knowledge abstract”，常见参数为：
-i：交互模式-q：直接给出问题
和 he search 一样，he talk 依赖索引。没有先执行 he build-index，就无法获得完整的基于 KA 的语义问答能力。
示例场景：论文抽取后提问主要贡献：
he parse paper.md -t general/concept_graph -o ./paper_kb/ -l enhe talk ./paper_kb/ -q "What are the main contributions?"
这个流程体现的是：先把论文变成 KA，再围绕 KA 提问题，而不是把原文重新交给模型即席回答。也正因为如此，索引是问答阶段的关键依赖。
4. Save：持久化与导出
CLI 工作流中的最后一个阶段是 Save。完整工作流图中明确写的是：
he dump：把 KA 持久化到磁盘
这一步强调 KA 不是瞬时内存对象，而是可以保存下来，在之后继续 feed、build-index、show、search、talk 或导出。
在实际管理场景里，导出命令也应被视为 Save 阶段的重要延伸。其中命令参考明确列出：
he export obsidian：导出到 Obsidian vault
其常见参数包括：
-o：输出目录--name：导出名称-f：强制覆盖
因此，Save 阶段不只是“把结果留在本地”，也包括把 KA 转换到外部知识管理系统中继续使用。对于采用 Obsidian 管理笔记的用户，he export obsidian 就是从 Hyper-Extract 工作流进入 Obsidian 工作流的接口。
管理命令在工作流中的位置
除了主线四阶段命令，CLI 文档还给出若干管理命令，它们不是工作流主体，但在长期维护 KA 时很重要。
he info：查看统计信息
he info 用来显示 Knowledge Abstract 的统计信息。它适合放在以下节点使用：
parse之后，确认 KA 是否已生成feed之后，查看增量补充后的规模变化build-index前后，配合检查当前 KA 状态
它的价值在于让用户面对的是可检查的知识对象，而不是黑盒式的一次性运行结果。
he clean：删除索引或整个 KA
he clean 的用途是移除某个 KA 的索引，或删除整个 KA。常见参数包括：
-a：删除全部-y：跳过确认
这说明 clean 有两个不同层级：
- 只清理索引：适合索引损坏、需要重建、或想释放部分空间的情况
- 清理整个 KA：适合完全放弃当前结果、重新开始的情况
也正因如此，he clean 一般位于工作流的维护与回收阶段，而不是常规探索阶段。
he list 与 he config：工作流前置辅助
虽然本文主轴不是配置，但命令参考中还列出：
he list template/he list method：列出可用模板或方法he config init/show/set：管理配置
配置文件保存在 ~/.he/config.toml。这些命令通常位于工作流开始之前，用来决定抽取入口、检查环境、设置模型或其他 CLI 配置。
关键机制与边界
核心机制 1：工作流以 KA 为中心，而不是以 prompt 为中心
从 parse → feed → build-index → show/search/talk → dump/export 的链条可以看出，Hyper-Extract CLI 工作流的最小长期单位不是提示词，也不是某次模型响应，而是 Knowledge Abstract。只有把知识结果固化为 KA，增量维护、索引构建、可视化、问答和导出才有统一载体。
核心机制 2：索引是语义探索能力的前提
文档明确把“Build the index”写成最佳实践，并指出它是 search 和 chat 功能所必需。这意味着：
he show不以索引为前提he search依赖索引he talk依赖索引
如果没有执行 he build-index，用户不能期待获得完整的语义搜索和基于 KA 的问答能力。
核心机制 3：增量更新优于全量重跑
he feed 的价值在于随时间补充资料，而不必重新处理已有文档。这种机制适合文档集合会持续增长的任务，尤其是研究、知识管理、档案整理和法规/合同维护等场景。
边界 1：模板与 method 都是入口，但推荐模板
CLI 文档明确区分两种抽取方式：
- Templates：面向大多数用户，推荐使用，按领域优化
- Methods：偏高级用法，直接调用底层抽取算法
这属于 Create 阶段的入口选择问题，而不是工作流结构本身的变化。无论走模板还是 method，后续增强、索引、探索、保存的框架不变。
边界 2：语言支持存在差异
模板支持多语言，示例中给出英文 -l en 和中文 -l zh。但 method 模板始终使用英文提示词。因此在非英文文档场景中，选择正确语言参数会直接影响抽取质量，这也是官方最佳实践之一。
典型进入方式
CLI 文档给出了三种很典型的进入工作流方式，分别对应论文、传记和合同。
论文场景：抽取后围绕主要贡献提问
示例命令：
he parse paper.md -t general/concept_graph -o ./paper_kb/ -l enhe talk ./paper_kb/ -q "What are the main contributions?"
这个场景的重点不是“直接让模型读论文回答问题”，而是先得到 KA，再进入基于 KA 的问答流程。若希望问答稳定可用，还应先构建索引。
传记场景：抽取后可视化人生事件
示例命令：
he parse biography.md -t general/biography_graph -o ./bio_kb/ -l enhe show ./bio_kb/
这个场景说明传记类信息适合先结构化，再通过可视化查看事件、关系或时间线式知识结构。
合同场景：抽取后搜索终止条件
示例命令：
he parse contract.md -t legal/contract_obligation -o ./contract_kb/ -l enhe search ./contract_kb/ "termination conditions"
这个场景说明法律或合同类文本不仅需要抽取义务，还需要后续定向检索特定条款。这里同样应把索引视为搜索前提。
使用建议
结合命令说明与最佳实践，可以把 CLI 工作流的经验总结为：
- 优先使用模板完成领域化抽取，除非确实需要底层 method。
- 在需要
search或talk时，先执行he build-index。 - 新文档进入同一知识主题时，优先使用
he feed做增量补充，而不是重新全量parse。 - 非英文文档要显式选择合适语言参数，以改善抽取质量。
- 用
he info检查 KA 状态，用he clean进行索引或整库清理，用he export obsidian把结果接入外部知识管理环境。