前言¶

DeepSeek Harness (DSH) 的设计理念是「一切皆插件」。在使用 DSH 开发或调试智能体时，我们会遇到两类问题：一是知识内容碎片化，容易导致上下文混乱和幻觉；二是缺乏结构化、可验证的知识呈现方式。Open Knowledge Format (OKF v0.2) 提供了一种基于 Markdown + YAML frontmatter 的知识图谱标准，能够将知识建模为可验证、可审计的结构化文档。

dsh-okf 是一个面向 OKF v0.2 的生产级 DSH 插件，由 TorRient 维护。它将 OKF 的规范转化为可执行的 DSH 工具链、Web 可视化与系统提示，帮助智能体在构建知识库时遵循严格的结构与审计要求。

插件定位¶

dsh-okf 是一个 DSH 插件，实现 OKF v0.2 标准的核心功能：包括一套 6 个 DSH Agent 工具、一个交互式 Web 可视化界面、REST API 以及内置的 DSH Skill。它将知识建模为带 YAML frontmatter 的 Markdown 文档，提供强类型校验、链接检查、状态追踪与审计日志，减少智能体幻觉，提升知识管理的确定性。

核心功能¶

6 个 DSH Agent 工具¶

• okf_init：初始化一个符合 OKF v0.2 标准的知识包（index.md、log.md 和基础概念）。
• okf_validate：对知识包进行确定性校验，检查 frontmatter 字段、必需的 type、链接有效性、孤立概念与过时状态。
• okf_search：支持按关键词、类型、标签或验证状态搜索概念。
• okf_concept_read：读取概念的前置 YAML frontmatter、正文内容以及自动计算的入链（incoming backlinks）。
• okf_concept_write：创建或更新概念文件，包含 frontmatter 校验与自动审计日志写入 log.md。
• okf_visualize：导出一个基于 Cytoscape.js 的力导向 HTML 图（viz.html），用于可视化知识图谱。

交互式 Web UI 与 REST API¶

• GET /api/okf/view：全屏浏览器可视化界面，支持搜索、分类筛选、布局切换与侧边栏检查器。
• GET /api/okf/graph：Cytoscape 兼容的 JSON 图数据（节点、边、入链、元数据）。
• GET /api/okf/status：当前工作区的健康状态与合规统计。

DSH 系统提示与技能集成¶

• 插件内置 DSH Skill，路径为 skills/okf/SKILL.md。
• 运行时会将 OKF 实践注入到 DSH 智能体上下文中，使其自动采用 OKF 的结构化写法与校验流程。

安装与启用¶

推荐方式：CLI 安装¶

在 DSH 环境中运行以下命令，从 GitHub 直接安装插件到当前配置文件：

dsh plugin --profile web add github:TorRient/dsh-okf

安装完成后，插件会自动完成以下操作：

• 下载并链接 dsh-okf 到当前配置文件的 node_modules/ 目录。
• 将 dsh-okf 注册到活跃配置的 bundles 中。
• 挂载 6 个 OKF Agent 工具、Web 可视化路由以及内置的 OKF Agent Skill。

本地链接（开发调试）¶

1. 将 dsh-okf 链接到 DSH 配置文件的 node_modules/：

ln -s /path/to/dsh-okf ~/.dsh/profiles/web/node_modules/dsh-okf

2. 在配置文件的 manifest 中注册 bundle（以 package.json 为例）：

{
  "dsh": {
    "profile": {
      "bundles": [
        "...",
        "dsh-okf"
      ]
    }
  }
}

或者在 cordis.patch.yml 中添加条目：

- insert:
    - id: okf
      name: 'dsh-okf'
    - id: okf-skill-filesystem
      name: '@deepseek-ai/dsh-skill-filesystem'
      config:
        providerName: okf-plugin
        includeDefaultRoots: false
        bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-okf/package.json')), 'skills')

典型用法¶

初始化 OKF 知识包¶

使用 okf_init 工具创建一个符合 v0.2 标准的知识包结构：

dsh run okf_init

校验知识包¶

使用 okf_validate 对当前知识包进行结构化检查：

dsh run okf_validate

搜索概念¶

按关键词或类型搜索概念：

dsh run okf_search --keyword payment

读取概念¶

读取某个概念的前置信息与入链：

dsh run okf_concept_read --path concepts/payment-gateway.md

更新概念¶

写入或更新概念文件，系统会自动进行 frontmatter 校验并将变更记录到 log.md：

dsh run okf_concept_write --path concepts/payment-gateway.md --content '...'

可视化知识图谱¶

在浏览器中访问 /api/okf/view 查看交互式图谱，或导出 JSON：

curl http://localhost:3000/api/okf/graph

适用场景与注意¶

dsh-okf 适合需要在 DSH 中构建、管理与可视化结构化知识库的开发者与工程师，尤其是涉及 API 设计、架构文档、系统规范等需要强一致性与可审计性的场景。

注意：插件以当前 DSH 进程的权限运行，安装前应确认源码与许可证（MIT），避免使用未经审查的第三方包。

总结¶

dsh-okf 将 OKF v0.2 标准嵌入到 DSH 工作流中，提供从初始化、校验、读写到可视化的完整能力链路。通过严格的结构化与审计机制，它帮助智能体开发者构建可验证的知识图谱，降低幻觉风险，提升知识管理的一致性。

• 目录页：https://www.skillhub.cn/plugins/TorRient/dsh-okf
• GitHub：https://github.com/TorRient/dsh-okf