跳过主要内容
G

graph-dsh

gary2402/graph-dsh

Native DeepSeek Harness plugin for evidence-traceable DAG computation and interactive HTML export.

安装

dsh plugin --profile web add github:gary2402/graph-dsh

README

Graph DSH

面向 DeepSeek Harness 的证据可追溯图插件

Evidence-grounded graph for DeepSeek Harness.

npm version Node.js

Graph DSH 接入流程： 材料 → 证据 → 事实 → 输入变量 → 计算 DAG → 输出页面 DeepSeek Harness (DSH)。

它提供四个原生 Agent 工具，支持结构化数据校验、确定性计算、来源追溯及独立 HTML/JSON 导出。

项目定位：

Graph DSH 是 DeepSeek Harness 的原生计算工具插件。

r3_export 可以生成独立的交互式 HTML 内容，但不会自动保存或发布文件。

✨ 核心功能

工具功能
r3_validate验证 R3 数据包结构及约束
r3_compute执行确定性 DAG 计算
r3_trace追溯计算依赖与来源证据
r3_export导出交互式 HTML 或 JSON

1. 结构化数据验证

检查输入的数据包是否符合 graph-runtime/1.0 协议。

验证内容包括：

  • JSON 结构与字段约束
  • 节点引用关系
  • 循环依赖
  • 输入参数范围
  • 不合法的计算表达式
  • 数据完整性

2. 确定性图计算

通过有向无环图（DAG）描述变量之间的计算依赖。

计算结果由输入参数和计算规则确定，而不是由语言模型直接生成数值。

支持情景参数覆盖和重新计算。

3. 证据链追溯

从某个结果节点出发，可以向上追溯：

  • 依赖的计算节点
  • 输入变量
  • 关联事实
  • 支撑证据
  • 原始材料

帮助使用者理解计算结果的来源与形成过程。

4. 交互式结果导出

支持输出：

  • 独立 HTML 页面
  • JSON 分析结果
  • 当前情景计算值
  • 结果对应的 SHA-256 校验值

HTML 页面可以独立于 DSH 使用。

📦 快速安装

环境要求

  • Node.js ≥ 24.9.0
  • DeepSeek Harness
  • 兼容的 Cordis 与 DSH Tools 版本

当前版本主要针对以下组件进行验证：

组件版本
Node.js≥24.9.0
Cordis4.1.0
DSH Tools0.2.2-rc.1
Graph DSH1.0.0

其他 DSH 版本尚不能保证兼容。

方法一：DSH 插件管理器

打开 DeepSeek Harness 的插件管理器。

搜索：

graph-dsh

安装并启用插件。

根据 DSH 的热重载配置，可能需要重启应用。

方法二：命令行安装

在终端执行：

dsh plugin --profile desktop add graph-dsh

如果使用其他 Profile，请将 desktop 替换为实际名称。

也可以安装指定版本：

dsh plugin --profile desktop add graph-dsh@1.0.0

安装完成后，DSH 将通过包内的 cordis.patch.yml 加载插件。

验证安装

确认 DSH 中已经注册以下四个工具：

r3_validate
r3_compute
r3_trace
r3_export

建议先使用仓库提供的最小示例进行测试。

注意：源码仓库已经验证 Linux 环境下真实 Cordis/DSH 工具组件的注册和调用。完整 Windows/macOS Desktop、模型自主调用、PTC 端到端和浏览器交互仍需在目标环境中验证。

详细测试记录见 TEST-REPORT.md。

🚀 使用方法

基本流程

       Materials
          │
          ▼
       Evidence
          │
          ▼
         Facts
          │
          ▼
        Inputs
          │
          ▼
    Computation DAG
          │
          ▼
        Results
          │
     ┌────┴────┐
     ▼         ▼
   Trace     Export
     │         │
     ▼         ▼
 Evidence    HTML / JSON

Graph DSH 使用完整的 R3 数据包作为输入。

当前支持的核心协议：

graph-runtime/1.0

示例数据

项目包含以下示例：

在 DSH 中调用

可以向 Agent 输入以下任务：

请读取 examples/minimal.package.json， 首先调用 r3_validate 检查数据结构。

验证通过后，使用 r3_compute 执行计算。

然后选择一个输出节点，通过 r3_trace 展开其依赖关系和证据链。

最后使用 r3_export 生成交互式 HTML，并通过文件工具将返回的 content 保存为 HTML 文件。

使用前需要确保 Agent 可以访问示例文件或其 JSON 内容。

情景分析

Graph DSH 允许在已定义的参数范围内修改输入变量。

例如：

{
  "quantity": {
    "kind": "exact",
    "value": 8
  }
}

情景参数变化后，可以重新执行计算。

需要注意：

用户修改的输入属于情景假设，不等于已经获得证据支持的新事实。

🔧 工具 API

r3_validate

验证完整 R3 数据包。

输入参数：

{
  "package_json": "<完整的 graph-runtime/1.0 JSON 字符串>"
}

返回结果包括：

  • valid
  • errors
  • 其他验证信息

非法数据包通常作为业务校验结果返回。

r3_compute

执行计算图。

输入参数：

{
  "package_json": "<完整 JSON 字符串>",
  "overrides_json": "{}"
}

主要返回：

  • ok
  • values
  • order
  • warnings

其中 overrides_json 为可选参数。

r3_trace

追溯指定节点的计算与证据关系。

输入参数：

{
  "package_json": "<完整 JSON 字符串>",
  "target": "revenue",
  "overrides_json": "{}"
}

返回内容包括：

  • 目标节点值
  • 祖先节点
  • 依赖关系
  • 来源信息
  • 关联事实与证据

r3_export

生成 HTML 或 JSON。

输入参数：

{
  "package_json": "<完整 JSON 字符串>",
  "format": "html",
  "overrides_json": "{}"
}

返回结果包括：

format
mimeType
filename
content
sha256

支持的格式：

html
json

重要：

r3_export 只返回内容，不会自动写入文件、上传文件或发布网页。

如需保存结果，应由 Agent 使用获得授权的文件工具完成。

🛠️ 本地开发

克隆仓库：

git clone https://github.com/Gary2402/graph-dsh.git

cd graph-dsh

安装依赖：

npm ci --ignore-scripts

执行测试：

npm test

生成本地开发配置：

npm run setup

脚本将生成：

cordis.local.patch.yml

其中包含本机插件入口的绝对路径。

根据终端输出，使用 --patch 参数启动 DSH。

此文件是本地开发配置，不应该提交到 GitHub。

不启动 DSH 的独立测试

项目还提供了独立 CLI：

验证数据包：

node scripts/cli.mjs validate examples/minimal.package.json

执行计算：

node scripts/cli.mjs compute examples/minimal.package.json

追溯指定节点：

node scripts/cli.mjs trace examples/minimal.package.json revenue

导出 HTML：

node scripts/cli.mjs export examples/minimal.package.json html my-analysis.html

发布前检查

npm test
npm pack --dry-run

检查 npm 发布文件是否包含必要的源码、运行时文件和 Bundle 配置。

📂 项目结构

graph-dsh/
│
├── src/
│   └── index.mjs
│
├── runtime/
│   ├── graph_core.js
│   ├── graph_package.js
│   └── service.mjs
│
├── assets/
│
├── examples/
│
├── skills/
│   └── r3-graph/
│       └── SKILL.md
│
├── scripts/
│
├── tests/
│
├── cordis.patch.yml
├── package.json
├── package-lock.json
├── README.md
├── SECURITY.md
├── PROVENANCE.md
└── TEST-REPORT.md

主要组件

src/index.mjs

DSH 原生插件入口。

通过 Cordis 注册四个工具，并向系统提示词注入简短协议指导。

runtime/

R3 Graph Runtime 的核心计算与数据包处理代码。

assets/

包含原始工作台相关资源、页面模板、协议及来源校验信息。

examples/

包含可用于测试和学习的示例数据包。

skills/r3-graph/

提供 R3 数据包的编写流程和使用规则。

该文件是模型使用指南，不代表已经自动注册到 DSH Skill 文件系统。

🔍 设计原则

Evidence First

计算结果应当能够关联其所依据的事实与证据。

证据链的存在并不代表原始材料已经得到独立验证。

Deterministic Computation

计算过程由明确的输入、依赖关系和运算规则决定。

语言模型负责组织分析任务，不直接代替确定性计算引擎。

Traceability

支持从结果追溯到计算节点、输入变量及来源材料。

Explicit Uncertainty

保留未知值与区间信息。

未知值不能被自动视为零。

Portable Output

可以生成独立 HTML 页面，使部分分析结果脱离 DSH 环境进行查看和交互。

⚠️ 当前限制

Graph DSH 目前存在以下边界：

  • 仅支持 graph-runtime/1.0。
  • 不自动迁移旧 AnalysisProtocol。
  • 不自动从互联网获取材料。
  • 不提供数据库或账户系统。
  • 不自动进行单位换算。
  • 区间计算不等同于概率预测。
  • 不自动验证原始材料真实性。
  • 不自动保存或发布导出的 HTML。
  • 未完成所有操作系统上的端到端验证。

核心同步计算也不支持在任意计算步骤中立即中断。

插件会在工具调用前后检查取消信号。

完整说明参见：

📌 版本与发布

当前版本： 1.0.0

npm：

https://www.npmjs.com/package/graph-dsh

GitHub：

https://github.com/Gary2402/graph-dsh

DeepSeek Harness：

https://github.com/deepseek-ai/deepseek-harness

GitHub 源码和 npm 已发布版本可能存在时间差。

生产环境建议固定经过验证的插件版本。

📄 License

当前项目的 package.json 标记为：

UNLICENSED

公开 GitHub 仓库或公开 npm 包不意味着自动授予源码修改、复制或再分发许可。

使用及再分发应遵守适用的权利与授权要求。

English Overview

Graph DSH — Evidence-grounded graph computation for DeepSeek Harness.

Graph DSH integrates the R3 Graph Runtime with DeepSeek Harness through four native tools:

  • r3_validate — Validate structured graph packages.
  • r3_compute — Execute deterministic DAG calculations.
  • r3_trace — Trace dependencies and supporting evidence.
  • r3_export — Export standalone HTML or JS

相关插件

D

deepseek-harness

deepseek-ai/deepseek-harness

201.9k3个月前开发与插件工具MIT
D

dsh-market

dsh-market/dsh-market

12k6小时前开发与插件工具MIT
Z

dsh-web (dsh-plugin-manager)

zhu1090093659/dsh-web

10.4k8小时前开发与插件工具Apache-2.0
Z

dsh-web

zhu1090093659/dsh-web

6.5k2个月前开发与插件工具Apache-2.0