企业官网建设流程全解析

OpenViking Knowledge Graph 编译技能：用ov compile构建可溯源、可可视化的实体关系图谱

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

导读

本篇围绕 OpenViking 仓库中的knowledge-graph编译技能（Skill）展开，它定义了一套将文档、笔记、网页内容、转录稿、研究材料甚至代码仓库编译为有证据支撑、可可视化知识图谱的产物规范与工作流。读者将掌握ov compile加载该技能后生成entities/*.md实体节点与根目录relations.jsonl关系边文件的方法、实体与边的 schema 约束、溯源（provenance）规则、增量刷新策略，以及如何借助仓库自带的渲染脚本把产物变成交互式 HTML 图谱。

一、技能定位与产物模型

knowledge-graph技能位于 examples/compile/ov-compile-skills/knowledge-graph/SKILL.md，是 OpenVikingov compile命令可加载的官方编译技能之一。它的目标非常明确：把供给的语料转成 Agent 可以按实体、类型、关系遍历的持久化图，而不是一份"摘要堆"。

技能要求最终产物落在如下工件树中：

entities/ <entity-id>.md relations.jsonl

• entities/目录存放每个命名实体的节点文件，文件名为稳定、路径安全的实体 ID；
• 根目录relations.jsonl存放全部有向关系边，每行一个 JSON 对象。

与此同时，技能对语料处理定下三条铁律：

1. 来源只读：绝不修改供给的源材料；
2. 范围由任务决定：按ov compile的--reason决定范围、语言、受众与深度，未指定时采用源材料的主导语言；
3. 一切以源为据：每个节点、每条实质断言和每条边都必须落地到源材料中。来源被视为**溯源证据（provenance）**而非领域节点——除非某个来源本身就是领域中有名的主题（如一份被引用的合同、标准或出版物）。

这套产物规范与仓库中另外几个编译技能形成互补：llm-wiki技能（examples/compile/ov-compile-skills/llm-wiki/SKILL.md）产出 Karpathy 风格的 LLM Wiki 页面，knowledge-distillation技能（examples/compile/ov-compile-skills/knowledge-distillation/SKILL.md）面向跨来源的高阶结论提炼，而knowledge-graph则把知识建模为可遍历的实体-关系图。

二、实体节点：entities/<entity-id>.md

2.1 什么应该成为节点

技能规定：为具有稳定身份或边界的命名事物创建节点，例如：

• 人物（person）、组织（organization）、群体（group）、动物（animal）
• 地点（place）、产品（product）、项目（project）、系统（system）、服务（service）
• 模块（module）、数据集（dataset）、标准（standard）、文档（document）、工件（artifact）、命名事件（event）

选择实体的优先级也有明确指导：优先选择核心的、反复出现的、被任务点名的、连接度高的、对理解源领域重要的实体。反之，不要仅仅因为某个源文件、目录、段落或分块存在就为它建节点；只有当其身份和关系对图谱有意义时才把源文档建模为领域实体（如命名合同、标准、出版物、报告）。

2.2 节点文件结构

每个节点存储在entities/<entity-id>.md，结构如下（技能原文示例）：

--- type: entity id: 取经队伍 title: 取经队伍 entity_type: group description: 由唐三藏率领、以西行取经为目标的行动团体。 aliases: [唐僧师徒, 师徒五众] sources: - viking://resources/source.md ---

字段语义：

2.3 entity_type 词汇表

entity_type应使用稳定的小写snake_case取值，技能给出的基准词汇表为：

person organization group animal place product project system service module dataset standard document artifact event

刷新既有图谱时应复用已建立的类型词汇；只有当细分类型能实质改进过滤或可视化时才引入更窄的类型。值得注意的是，仓库自带的可视化脚本knowledge_graph.py（examples/compile/graph-show/knowledge-graph/knowledge_graph.py）对类型做了归一化别名映射（human/character/people → person、location/region/site → place、team/collective → group等），并把识别不了的类型归入other，还定义了每种类型的显示标签、颜色与形状（圆形/三角/菱形/星形/方形/六边形）。这与技能"复用既有类型词汇、缩小粒度需谨慎"的规则互为印证。

2.4 description 与正文的边界

description必须写成一句稳定的身份句，不允许把单集事件的动作、临时状态、来源特定观点或抽取历史塞进去。例如"某团队在西行途中收服了成员"这类剧情事实应放在正文或建模为事件节点，而不是写进身份描述。

frontmatter 之后可以跟简洁的 Markdown（仅当它能提供超出"指纹"之外的有用上下文时），用## Overview这类二级标题组织稳定的属性、职责、接口、边界或来源限定上下文，空章节一律省略。同时注意两条纪律：

• 实体与实体之间的事实不要用散文重复——它们属于relations.jsonl；
• 字面属性仅在有用且有据时保留，例如团队的成员关系应建模为member_of边，而不是只靠一句话罗列成员。

2.5 节点命名一致性规则

技能对 ID 的稳定性要求非常严格：

• 使用一个规范名（canonical name），有用的替代名放进aliases；
• 创建稳定、路径安全的 ID：拉丁文本优先小写kebab-case；其他文字体系保留字母与数字，空白或标点替换为连字符；
• 非拉丁规范名直接保留原文：当输出语言与规范名为中文时，直接使用中文名作为 ID 和文件名，绝不翻译或转写成英文 ID。示例中的取经队伍正是这条规则的落地；
• id等于去掉.md的文件名，type恒为entity；
• 既有节点代表同一身份时复用既有 ID 与路径；不要仅为本地化而重命名既有 ID——title才是本地化显示名；
• 同形异义词用最小上下文消歧，保持为不同节点。

三、类型化边：relations.jsonl

3.1 行格式

每个有向边占一行，技能给出的示例：

{"from":"孙悟空","relation":"member_of","label":"属于","to":"取经队伍","evidence":["viking://resources/source.md"]}

每行可读作一句陈述式<from> <relation> <to>。字段约束：

3.2 语义一致性要求

技能的若干规则值得单独强调：

• relation与label必须表达同一语义：不能用works_for表达群体成员关系、用belongs_to表达地理来源，只因本地化标签看起来像；
• 图谱内同一个谓词只允许一个一致的label；刷新时保留既有边的谓词编码，仅为缺失 label 的保留边补上本地化标签；
• 重复的(from, relation, to)三元组合并为一行，evidence并集去重；
• 当且仅当携带有用、有据的语义时才添加反向/互逆边，且要有清晰、可复用的谓词——不要机械地为每条边镜像一个逆边；
• 两个端点都必须存在于最终实体集中；
• 输出为紧凑的独立 JSON 对象（无外层数组），行按from→relation→to排序以保证确定性输出。

3.3 复杂关系建模

技能明确要求把关系本身建模为节点，条件是：关系有自身身份，或超过两个参与方、限定条件、状态变化是本质的。命名合同、协议、任命、交易、会议、事件都应作为中间节点，而不是把语义塞进一个长谓词。示例：把一方连接到命名协议用party_to，再把协议连接到被治理工件用governs_use_of；不要把signs_agreement直接编码到工件上。

建立边的依据必须是明确的源陈述或权威源材料所展示的行为。共现（co-occurrence）只能作为发现线索，只有在其含义与方向被证据支持后才编码成关系。

四、溯源规则：把领域知识与证据分开

knowledge-graph技能对 provenance 的约束可以直接作为编写者的行为规范：

1. 实体节点的sources列表：用于支撑该实体身份与稳定描述的证据；
2. 边的evidence列表：用于支撑该条三元组的证据；
3. 正文中额外 Markdown 断言的证据：紧挨着它所支撑的断言放置；
4. 保留提供的精确 URI、仓库相对路径、链接与可用锚点，绝不虚构来源引用或位置；
5. 把来源引用视为"支撑"，而非"背书"——源材料之间的冲突、范围、时序与不确定性都要保留；
6. 严禁输出无标题的来源：...或Source: ...行。frontmatter 的sources字段是默认的页面级来源清单；只有当任务明确要求人读来源列表时，才在## 来源或## Sources下以 Markdown 列表渲染一次，且不在此处重复 claim 级链接。

这条规则在渲染层有代码级的呼应：仓库的WikiRenderer（bot/vikingbot/compile/renderer.py）中，_render_source_fallback会在页面正文缺失来源链接时按输出语言自动补## 来源/## Sources小节，把每个 source root 渲染为label形式的链接；_citation_target_allowed则限制引用目标必须位于声明的 source root 之下，从机制上防止编造外部引用。

五、显示契约：标识符与呈现分离

可视化或其他人类可读视图必须遵守：

• 节点显示title，而非id；
• 边显示label，而非relation；relation只作为机器键，仅在读取无label的旧边时作为回退；
• 用entity_type决定节点的形状、颜色、分组与过滤；
• 来源与证据在详情面板或检查视图中提供，而不是渲染成普通领域节点。

仓库的knowledge_graph.py正是这条契约的完整实现：它按entity_type映射颜色与符号、把实体title作为节点标签、把label显示在边上并隐藏relation谓词（仅在图例中展示label与<code>relation</code>的对照），同时提供类型过滤器（_type_filters）、谓词图例（_relation_legend）与选中实体后的属性、别名、关系与证据链检查面板。

六、工作流：Survey → Normalize → Extract → Integrate

Survey（勘察）

盘点来源的种类、权威性、时序、词汇与覆盖范围。刷新既有图谱前先检查现有实体工件与relations.jsonl。对代码来源，需要检查相关 manifest、文档、公开契约、schema、测试、入口点、运行时装配与配置，以确立实体身份与关系。

Normalize（归一化）

构建规范名、别名、候选 ID、身份线索、语义实体类型、证据与既有节点匹配的工作集。合并拼写变体与真正同义词；在来源提供足够身份证据前，把有歧义的引用保持未解决状态。

Extract（抽取）

对每个候选节点，把稳定指纹与来源限定事实分开；对每条候选边，确定源节点、目标节点、精确谓词与支撑证据。选择保留源语义的谓词，并在写散文之前识别需要中间事件/协议/文档/关系节点的关系。

Integrate（整合）

保留准确既有节点与边、合并互补证据、加入新图谱知识、用更强或更新的证据修正被推翻的事实。合并重复节点时，把所有受影响边的端点改写为幸存实体的 ID，未变化节点保持既有路径提交完整工件集。

这套工作流与ov compile运行时给 Agent 注入的"survey → 定向精读"策略完全同构：BotCompileService（bot/vikingbot/compile/service.py）的_source_reading_workflow会指导模型先用openviking_list/openviking_glob盘点语料，再对样本文件按 head/middle/tail 三个窗口采样推断结构，最后用openviking_grep/openviking_multi_read或对物化文件exec定向精读，并强调"绝不以文件头几行判断价值"。

七、质量检查清单

技能要求在收尾前逐项核对：

1. 每个节点代表一个可识别实体，且文件与 frontmatter 的 ID 一致；
2. 每个节点有受支持的entity_type、稳定的description与非空sources；
3. 每个新建的非拉丁规范 ID 遵循来源语言规则，既有 ID 保持稳定；
4. 规范身份、别名与语义类型在全图一致；
5. 每条实质断言与边在正确粒度上有精确的供给证据；
6. 每条关系满足 JSONL schema、精确方向谓词与非空本地化显示标签；
7. 谓词与标签语义等价，成员、雇佣、来源、归属、包含没有被混淆；
8. 每个重复谓词在所选语言中使用一个一致标签；
9. 每条边的端点都能解析到实体节点；
10. 每个核心或选定实体至少参与一条有据边（除非来源确实未建立关系且保留孤立节点明确有用）；
11. 节点正文中描述的实体-实体关系都被表示为边，核心多方关系使用合适的中间节点；
12. 重复三元组已合并、关系行确定性排序；
13. 实体文件中没有无标题的来源：.../Source: ...行；
14. 最终工件树包含完整实体集与relations.jsonl。

八、用ov compile运行该技能

8.1 命令与参数

依据 docs/design/ov-compile-design.md 中的设计，ov compile通过 CLI → OpenViking Bot Proxy → VikingBot Compile AgentLoop → OpenViking content APIs 的链路执行：

ov compile \ --from viking://resources/周报 \ --to viking://resources/团队知识库 \ --reason "按月整理团队的成本优化进展" \ --skill viking://agent/skills/monthly_wiki

任务创建后 CLI 立即返回task_id: cmp_...、status: accepted与目标目录，不阻塞等待；用户通过ov task status <task_id>查询、ov task cancel <task_id>取消。任务状态机覆盖accepted → running(loading_skill / collecting_context / agent / rendering) → committing(writing / refreshing / salvaging) → completed / failed，并有BOT_RESTARTED等错误码。

8.2 运行时的资源上限

vbot/vikingbot/compile/models.py 的CompileLimits集中定义了可测试的资源上限（默认值节选）：

对knowledge-graph场景，这意味着：图谱产物中的实体节点数与关系行数受output_pages（128）与output_files（128）约束；所有entities/*.md与relations.jsonl通过一次批量提交写入，最终 UTF-8 内容不超过 4 MiB。

8.3 产物提交与确定性校验

Agent 通过submit_wiki_bundle工具提交结构化WikiBundleDraft，其中files字段专门承载"技能规定的精确路径工件"，即entities/*.md与relations.jsonl这类文件（见 models.py 中CompileFileDraft与WikiBundleDraft的字段说明：path/update_uri二选一、content/workspace_path二选一，超大内容先写入 task workspace 再以workspace_path提交，字节原样保留）。

渲染与写入由 renderer.py 完成，其中对知识图谱产物相关的确定性规则包括：

• 保留文件名.abstract.md、.overview.md、.relations.json、.source.json等为保留名（_RESERVED_FILENAMES），禁止覆盖 OpenViking 派生的语义 sidecar；
• 对声明了 OKF frontmatter 的 Markdown 工件执行validate_declared_okf_markdown：必须是 UTF-8、YAML frontmatter 合法、type非空字符串；
• 以upsert模式批量写回；created/updated/unchanged由最终 raw bytes 比对决定，未变化的页面不触发写入，因此重复执行同一技能只会收敛而不会产生无意义更新。

九、把产物渲染成交互式 HTML 图谱

仓库提供了与knowledge-graph技能配套的渲染脚本 examples/compile/graph-show/knowledge-graph/knowledge_graph.py。它期望的输入布局与技能产物完全一致：

knowledge-graph/ entities/ <entity-id>.md relations.jsonl

用法示例：

python knowledge_graph.py /path/to/journal-to-the-west-knowledge-graph python knowledge_graph.py /path/to/graph -o graph.html --title "西游知识图谱"

脚本在写出任何内容前会先完整校验图谱，这可以作为knowledge-graph技能质量检查清单的自动化落地：

• entities/目录必须存在且含 Markdown 文件，relations.jsonl必须存在；
• 每个实体文件必须有 YAML frontmatter，id非空且与文件名（path.stem）一致，id不允许重复，title非空；
• 每行relations.jsonl必须是合法 JSON 对象，from/to/relation非空字符串，relation必须匹配^[a-z][a-z0-9_]*$（小写 snake_case），evidence必须是非空字符串数组；
• 谓词 label 一致性检查：同一relation谓词在文件内只能有一个 label，出现不一致直接报错——这正是技能"一个谓词一个一致 label"规则的可执行版本；
• 重复(from, relation, to)三元组自动合并 evidence 并去重，输出按(source, relation, target)确定性排序。

生成的 HTML 基于 D3 力导向图，按entity_type着色与区分形状、提供实体搜索、类型过滤、谓词图例、聚焦邻居与实体详情检查面板（属性、别名、来源与证据链）。也就是说，从ov compile产出图谱数据到人类可交互浏览，整条链路在仓库内即可闭环。

十、小结

knowledge-graph技能把"知识图谱"从抽象概念落实为一套严格的产物契约：entities/<entity-id>.md负责稳定身份，relations.jsonl负责类型化有向关系，sources/evidence负责语句级溯源，Display contract 负责机器键与人读界面的解耦，而 Survey → Normalize → Extract → Integrate 工作流与质量检查清单保证了图谱可增量刷新且始终有据可查。配合ov compile的任务编排、WikiRenderer的确定性校验以及knowledge_graph.py的可视化脚本，开发者可以用一条命令把任意语料编译成 Agent 可遍历、人类可交互、证据可追溯的持久化知识图谱。

若需进一步探索，可继续阅读：

• 技能本体：examples/compile/ov-compile-skills/knowledge-graph/SKILL.md
• 同目录兄弟技能：llm-wiki、knowledge-distillation、daily-report
• 编译任务编排：bot/vikingbot/compile/service.py、bot/vikingbot/compile/models.py
• 确定性渲染与校验：bot/vikingbot/compile/renderer.py
• 可视化渲染：examples/compile/graph-show/knowledge-graph/knowledge_graph.py
• 整体设计文档：docs/design/ov-compile-design.md

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking