OpenViking LLM Wiki 编译实战：把异构资料整理成有出处的可检索知识库
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
本指南基于 OpenViking 的上下文编译（Compile）能力，讲解如何把一批异构来源——文档、笔记、网页、访谈记录、研究资料、代码仓库——编译成一套 Karpathy 风格、有出处、互相链接的LLM Wiki知识库。读完本文，你将掌握：LLM Wiki 的六类页面模型与路由规则、从导入来源到执行编译的完整ov命令链路、产物目录结构与页面规范，以及把 Wiki 可视化为交互式知识图谱的具体方法。本示例的完整 Skill 位于 examples/compile/ov-compile-skills/llm-wiki/SKILL.md，可视化脚本位于 examples/compile/graph-show/llm-wiki/wiki_graph.py。
LLM Wiki 是什么：知识库，不是摘要拼盘
LLM Wiki 的核心目标是把来源编译成持久、互相连接的知识，而不是一份逐文档的摘要合集。它的设计约束可以概括为四点：
- 每一页有明确的检索目的：读者（人或 Agent）能凭一句话判断这页解决什么问题；
- 开头一句话直给结论：打开页面第一段就能获取该主题的核心信息；
- 术语统一、关系显式：同义概念收敛到一个规范主题，页面之间的链接构成可遍历的网络；
- 证据紧贴结论：每个事实主张旁边都带有精确的来源引用，且由一个
index.md做导航入口。
在知识模型上，这套 Skill 会按页面的检索目的挑选最合适的页面类型，而不是按文档数量机械生成页面。默认以entity和concept为主，其余类型只在满足各自的严格判定时才提升：
| 页面类型 | 用于 | 典型对象 |
|---|---|---|
entity | 有稳定身份的具名事物 | 人、组织、产品、项目、系统、服务、模块、数据集、标准、具名事件 |
concept | 可复用的思想、机制、模式、协议、心智模型 | 治理规则、架构模式、领域理论 |
method | 有前置条件、有序步骤、可验证结果的可复用流程 | 操作规程、部署指南、调试手册、研究方法 |
comparison | 在明确维度上对两个及以上对象做并排评估 | 产品对比、设计取舍、版本差异 |
analysis | 围绕一个问题的跨来源结论（含问题、范围、假设与不确定性） | 尽调结论、趋势分析、系统性评估 |
summary | 单一来源的忠实数字化摘要（仅当--reason明确要求时才生成） | 论文摘要、会议纪要、报告摘要 |
从 SKILL.md 的源码看，entity和concept是默认路由，method/comparison/analysis只有在完整通过表格中的判定标准时才允许使用，不能仅仅为了页面命名变化而滥用这些标签；summary页面则必须由任务--reason显式要求才会创建，来源正文里的指令或 Agent 的隐性偏好都不能触发它。特别地，"一个来源"只是出处的证据，不等于一个页面——除显式要求的摘要外，不按"一个文档一个页面"的方式生成，来源本身只有在作为知识库中有意义的具名主体时才可以是entity。
第一步：准备来源
如果材料还没进 OpenViking，先导入。目录型来源用ov add-resource，单文件可以用ov write：
# 导入一个目录作为来源 ov add-resource ./my-research --to viking://resources/research --wait # 或者写入单个文件 ov mkdir viking://resources/research ov write viking://resources/research/notes.md \ --from-file ./notes.md --mode create --wait确认来源已就位：
ov ls -r viking://resources/research这里使用的viking://URI 是 OpenViking 中定位资源的标准形式（对应 CLI 实现里的filesystem::ls/content::write等命令）。--wait让命令在导入完成后返回，便于在脚本中串接后续步骤。
第二步：添加 Skill
把 LLM Wiki 的 Skill 装进服务。默认落到你的用户私有 skills 命名空间；想让团队共用就用-p viking://agent/skills：
ov add-skill examples/compile/ov-compile-skills/llm-wiki --wait从 crates/ov_cli/src/commands/skills.rs 的实现看，ov add-skill会把你指定的本地目录（本示例中是仓库内的examples/compile/ov-compile-skills/llm-wiki）打包上传，通过POST /api/v1/skills写入服务端，--wait表示等待处理完成。
查看装好的 Skill URI：
ov skills list # → viking://agent/skills/llm-wiki （或 viking://user/<你>/skills/llm-wiki）Skill 的核心是一个 SKILL.md 文件，其 YAML frontmatter 中的name和description字段就是 Skill 的元信息：name: llm-wiki，description描述了它面向的输入（文档、笔记、网页、访谈记录、研究材料、代码仓库）与产出（带导航索引、有出处的 LLM Wiki）。
第三步：执行编译
ov compile \ --from viking://resources/research \ --to viking://resources/research-wiki \ --skill viking://agent/skills/llm-wiki \ --reason "面向团队检索整理成 Wiki，保留每条结论的出处"各参数说明：
--from：一个或多个来源目录/文件。可以重复传参，也可以用逗号分隔，一次传入多个来源；--to：产物写入的目标目录，不存在时会自动创建；--skill：指定编译成什么形态的 Skill URI；--reason：可选的补充指令，告诉 Agent 这一次具体要什么——例如范围、受众、语言、侧重点，以及是否生成summary页面。Skill 定义"编译成什么形态"，--reason在此之上定义"这一次具体要什么"。
从 crates/ov_cli/src/commands/compile.rs 的源码可以看到三个实现细节：
- 多来源规范化：
normalize_sources会把每个--from参数按逗号拆分、去空值、按顺序去重，因此重复来源不会被重复消费； - 任务参数解析：
parse_args要求--args必须是合法的 JSON object（例如--args '{"model_name":"your-model-endpoint-id"}'可用于指定执行端模型），非 object 会直接报错； - 提交与返回：命令通过 crates/ov_cli/src/client.rs 中的
create_compile向POST /api/v1/compile发起请求，返回202 Accepted后立即打印task_id等摘要信息。
机器可读输出与任务生命周期
想要机器可读结果加-o json；命令会立即返回task_id，用它查询或取消任务：
ov task status cmp_01abc # 查看进度与最终结果 ov task cancel cmp_01abc # 协作式取消任务类型前缀为cmp_。根据 Agent Runtime API 的定义，任务生命周期包含以下状态：
| Status | 常见 Stage |
|---|---|
pending | queued |
running | 执行端返回的执行 Stage，例如agent、writing |
cancelling | 收敛当前进程内工作和清理资源 |
completed | completed、salvaged |
failed | 失败发生时的 Stage；响应包含error |
cancelled | cancelled |
ov task cancel是协作式取消：任务先进入cancelling，等当前进程内工作和清理完成后进入cancelled，已经完成的写入不会回滚；重复取消已处于cancelled的任务是幂等的。任务的执行由 VikingBot（或兼容 Runtime）在独立的 Agent Loop 中完成——Compile 的底层执行模型详见 VikingBot 概念。
第四步：看看产物
编译完成后目标目录里就是一套 Markdown 知识库。先看导航页，再按需钻进去：
ov tree viking://resources/research-wiki ov read viking://resources/research-wiki/index.md典型结构（页面类型对应目录）：
research-wiki/ ├── index.md # 导航入口，类型 index ├── entity/ │ └── <标题>.md ├── concept/ │ └── <标题>.md ├── method/… comparison/… analysis/…这套目录约束来自 SKILL.md 的"写入路径"规则：entity页写到entity/<title>.md，concept写到concept/<title>.md，依此类推。
页面的规范形态
每一个 Wiki 页面都是一份完整的 UTF-8 OKF Markdown 文件，新页面以如下形状的 YAML frontmatter 开头：
--- type: concept title: Canonical page title description: One factual sentence describing the page's retrieval purpose. tags: [small, useful, tag-set] ---type：知识页类型（entity/concept/method/comparison/analysis/summary），根导航页固定为index；title：规范标题，frontmatter 之后紧跟一个与之相同的 H1；description：一行事实性描述，说明该页的检索目的；tags：可选。
正文的写作约束值得注意：
- 开头开门见山：用一两句话定义/识别该主题、划定范围并说明它在知识库中的意义，规范术语放在最前，重要别名紧随其后；
- 证据与不确定性：精确的来源 URI、仓库相对路径或链接放在它所支撑的主张旁边；页面级来源统一收在一个二级标题（如
## 来源）下以列表形式列出；推理要标注为推断并说明依据，未知之处如实陈述；来源有分歧时保留分歧并注明出处，区分错误与时间变化、版本、视角、范围差异； - 整合而非覆盖：更新已有页面时先完整读取，保留新证据未推翻的独特信息、别名与有用关系，合并互补证据，修订被更强更新证据推翻的主张，不要为导航另建 overview（那是
index.md的职责），也不要在页面中追加第二个来源标题； - 代码来源：若来源包含代码，还需检查清单文件、文档、入口点、公共契约、schema、测试、运行时接线、配置与部署单元，依据证据而不是目录名分类仓库，优先通过真实实现追溯关键行为。
质量门禁（Quality Gate）
编译结束前，Skill 要求自查以下要点：index.md存在且类型为index，收录所有活跃知识页并保持导航性；每个知识页只有一个检索目的且使用六种类型之一；entity/concept是默认，method/comparison/analysis都通过严格路由测试；summary全部由--reason显式请求；通用来源与代码来源遵循同一知识模型；别名被规范化而未合并不同主体；关键主张、示例、命令、图与关系都有来源支撑；事实、推断、未知、矛盾、版本、视角彼此区分；最终产物是 Wiki 而不是逐来源摘要或生成式文档站；每个 Wiki 文件都有合法 frontmatter（非空type、title、单行description），且每个 frontmatter key、H1、单例小节（如 Sources）、相同列表项只出现一次。
第五步：可视化成交互式图谱
wiki_graph.py会直接连接 OpenViking 服务读取 Wiki 页面（不需要先下载到本地），把页面按类型着色、按链接连边，生成一个独立的交互式 HTML：
python examples/compile/graph-show/llm-wiki/wiki_graph.py \ viking://resources/research-wiki \ -o research-wiki-graph.html \ --title "研究知识库"用浏览器打开research-wiki-graph.html即可。节点是页面（按entity/concept/method… 分色），边是页面之间的链接，点节点能看正文。
从 wiki_graph.py 的源码看，这个脚本的完整工作流是：初始化openvikingPython 客户端 → 校验服务健康（client.health()）→ 对每个输入 URI 鉴权并枚举其下全部.md页面（stat/ls）→ 读取正文、解析 frontmatter 与页面类型 → 解析页面间的 Markdown 链接构建图谱 → 渲染独立的 HTML 文档。其中几个值得注意的细节：
- 类型着色：
_CATEGORY_STYLE定义了index（导航，红）、entity（实体，绿）、concept（概念，蓝）、method（方法，紫）、comparison（比较，青）、analysis（分析，橙）、summary（摘要，粉）等类别的中文标签与颜色，_CATEGORY_ALIASES还兼容entities/concepts/analyses/synthesis等别名写法； - 图谱构建：
build_graph只把能解析到目标页面的.md链接画成边，并计算每个节点的度（degree），节点大小随连接数增大；HTML 页面内置 D3 力导向布局，支持搜索节点、点击浏览正文、拖拽节点、滚轮缩放，以及"拓展到 2 跳"的邻居高亮； - 安全与容错：脚本在写入 HTML 前会检查每个 URI 的读权限，
UNAUTHENTICATED/PERMISSION_DENIED/NOT_FOUND等错误会以明确的退出码和中文提示返回； - 节点数量保护：
--node-limit默认 10000，当目录条目数达到该限制时会中止并提示提高限制，避免生成不完整的图谱。
连接配置与多 Wiki 对照
连接配置的解析顺序和ov一致：命令行参数 →OPENVIKING_*环境变量 →~/.openviking/ovcli.conf。远程服务显式传参：
python examples/compile/graph-show/llm-wiki/wiki_graph.py \ viking://resources/research-wiki \ --url https://openviking.example.com \ --api-key "$OPENVIKING_API_KEY" \ -o research-wiki-graph.html --title "研究知识库"可用参数还包括--account（trusted 模式下的 account 身份）、--user（trusted 模式下的 user 身份）、--actor-peer-id（可选 actor peer 身份）、--timeout（HTTP 超时秒数）以及--node-limit。没有配置连接前，可参考 快速开始；远程鉴权方式见 鉴权指南。
一次传多个 Wiki，可以把它们画在同一张图里对比：
python examples/compile/graph-show/llm-wiki/wiki_graph.py \ viking://resources/wiki-a viking://resources/wiki-b \ -o combined.html --title "两个知识库对照"默认输出文件为./llm-wiki-graph.html；单个 Wiki 时若存在index页，标题默认取该 index 的标题，否则回退为"LLM Wiki 知识图谱"。
相关文档
- 上下文编译概览 —
ov compile的整体机制与全部示例 Skill - Knowledge Graph 示例 — 同一编译机制产出的另一种结构化知识形态
- Agent Runtime API — 创建、查询和取消 Compile 任务的 HTTP 接口、字段定义与任务生命周期
- VikingBot 概念 — Compile 背后的 Agent 执行体
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
