研究图谱 moazzamak/dsh-knowledge-dag

dsh-knowledge-dag

一个 DSH 插件，用来展示研究图谱：有哪些问题、它们从什么推导而来、依托什么、最终落到什么结果，每个节点配一页用大白话写的说明。它从磁盘读取节点存储——每个节点一个 JSON 文件，外加为每个节点生成的 markdown 页面——然后放进 harness 右侧面板，呈现为节点-连线图、可筛选看板和引导前沿，同样的内容也以 knowledge_dag 工具的形式提供给模型。这个存储是通用的：最初为某份研究记录而写，那是第一个数据源，模型自己的知识库可以作为第二个。

这个包只有四个文件，没有构建步骤，直接安装即可：

- index.mjs —— 宿主侧，纯 ESM JavaScript
- client.cjs —— 浏览器侧，采用 harness 客户端 bundle 格式
- cordis.patch.yml —— bundle 补丁，把插件接入配置档
- package.json —— 清单文件，注册面很小：

"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "platform": "web" }
}

安装

用插件管理器把 bundle 装进配置档：

dsh plugin --profile <profile> add github:moazzamak/dsh-knowledge-dag

指定你实际启动的那个配置档，然后重启 harness。

从本地检出安装

改为让配置档指向这个目录。在配置档目录（~/.dsh/profiles/<profile>）里：

1. 把这个包加为依赖，用 file: 说明符指向这个目录；
2. 在同一个 package.json 里把它的名字追加到 dsh.profile.bundles，这样这个包里的 bundle 补丁才会生效；
3. 运行 pnpm install --no-frozen-lockfile，并设置 CI=true：pnpm 在没有终端时拒绝删除 modules 目录，而在 CI 下它默认使用冻结锁文件，新依赖会让锁文件失效；
4. 重启 harness，确认启动审计没有列出待处理项。

先备份 package.json。如果安装失败，就恢复它，否则配置档会留下一个并不存在的依赖声明，可能导致无法启动。安装后的副本从 ~/.dsh/profiles/<profile>/node_modules/dsh-knowledge-dag 读取。

你会得到什么

在浏览器里

- 一个框架触发按钮。 图按钮固定在框架右上角（shell.overlay，位于所有列之上）。点一下打开面板和标签页，再点一下关闭面板。它的状态从面板针对当前屏幕会话的已打开标签页清单读取，所以刷新后依然保留，而在从未打开过它的会话里也不会显示为已打开。
- 一个引导入口。 面板的「+」菜单列出「Knowledge graph」，走的是内置 Files 和 Terminal 标签页所用的同一套标签页注册（sidebarRightTabs，kind 为 knowledge-dag）。
- 面板，一次拉取数据，三种视图：
- Graph —— 把记录呈现为节点-连线图。分层 DAG 布局（节点的列等于它下方父节点最长链的长度， barycenter 在列内排序），以 SVG 绘制：每个节点一个方框，每条 lineage 边一个箭头，边跨轨道时画成虚线。节点的圆点带有状态色调；搜索和筛选只做淡化，不删除，所以「这个在哪」这个问题不会破坏记录的形状。
拖动平移，滚轮缩放，fit 查看整条记录，点击节点打开它的页面。
布局是确定性的，所以节点始终停在读者上次找到它的位置。
- Board —— 同样的节点排成行，由搜索框、状态列表和轨道列表筛选，并显示实时计数。
- Frontier —— 处于 open 或 running 的内容，每项都带它的预测、它的证伪条件和它的决策菜单。
- 节点详情页，从图谱、board 或 frontier 打开：问题、英文写成的故事节拍（investigating、assumed、found、what it means）、登记在案的预测和证伪条件、如何度量、决策菜单以及每条路径意味着什么、 lineage 标签、带数字的实测结果，以及它的结构类比 —— 下方是库生成的 markdown 页面，所以视图和记录不会互相矛盾。

在模型的工具列表里

knowledge_dag 响应四种操作，每种都作用于默认 store 或指定的 store：

- list —— 每个节点及其 kind、track、status 和 verdict
- show —— 按 id 查看单个节点的完整内容
- frontier —— 处于 open 或 running 的内容，每项带预测和证伪条件
- analogs —— 与某个节点结构匹配的节点（相同的关系形状：预测、证伪条件、决策菜单、实测数字、lineage），而它们的表层 —— track、topic —— 不同

通过 HTTP

/dsh-knowledge-dag 下有四个 GET 路由：

- GET /dsh-knowledge-dag/graph —— 整条记录，带它的 lineage 边和已配置 store 的名称
- GET /dsh-knowledge-dag/frontier —— open 或 running 的子集
- GET /dsh-knowledge-dag/node?id=<id> —— 单个节点及其 markdown 页面
- GET /dsh-knowledge-dag/analogs?id=<id> —— 单个节点的结构类比

每个都接受 ?store=<name>。节点 id 以查询参数传递，而不是路径段，格式错误的 id 会在触碰任何文件之前被拒绝。这些路由只在浏览器载体出现的地方注册：host 那一半用延迟形式，所以工具在 headless 配置档里依然可用。

配置

bundle 补丁挂载一行。它的 config：

| 字段 | 默认值 | 含义 |
| store | analysis/graph/nodes | <id>.json 节点文件所在目录 |
| pages | analysis/nodes | <id>.md 页面所在目录 |
| workspace | ""，即宿主进程的工作目录 | 相对 store 或 pages 解析时的基准目录 |
| stores | {} | 更多命名 store，每个为 { store, pages } |

示例行：

- id: knowledge-dag
name: dsh-knowledge-dag
config:
workspace: ~/projects/my-record # what the paths below are relative to
store: analysis/graph/nodes # 默认值，保持不变 pages: analysis/nodes stores: model: # 用 store: "model" 读取 store: model/knowledge/graph/nodes pages: model/knowledge/nodes

相对路径的 store/pages 以 workspace 为基准解析。只要记录不是由项目内启动的命令行读取，就要写上它：fs 后端从宿主进程的工作目录解析相对路径，而 Desktop 应用在配置档目录里启动宿主，此时 analysis/graph/nodes 解析不到任何东西，每次读取都返回 not found。store/pages 用绝对路径时不需要 workspace；不写就保持进程目录的行为。

节点存储的约定

一个存储就是两个目录，以及目录里的文件：

- 节点是 JSON 文件，每个节点一个，命名为 <id>.json。文件名的词干就是 id —— 节点正文自身不带 id 字段，页面也按同一个词干命名。
- 页面是生成的 markdown，位于 pages 下，命名为 <id>.md。没有页面的节点仍然是节点：视图会退化为只显示结构化正文。
- id 必须匹配 [a-z0-9][a-z0-9._-]*；其他一律按格式错误的请求拒绝，不会当作路径去解析。

插件只靠四个操作处理任意节点存储，别无其他：

load(store) -> nodes
validate(nodes) -> problems
save(store, nodes)
render(nodes) -> view

视图和工具从节点中提取的字段：

- 身份与结局：kind、track、status、outcome.verdict
- 一行英文：取 question、title、mechanism、statement 中第一个存在的
- 派生关系：lineage，箭头由此绘制，指向父节点 id。不在存储中的父节点会被丢弃，不会画成占位节点
- 登记的不确定性：question、prediction、falsifier、measurement、cost_tier —— 前沿展示的内容
- 决策空间：decision_menu，从选项到其含义的映射
- 叙述：story.investigating、story.assumed、story.found、story.means
- 结果：outcome.verdict、outcome.decision、outcome.reason、outcome.numbers
- 它替换了什么（displacement）以及它的 artifacts

词表是开放的：存储自己命名状态和裁决，视图给它认识的那些着色，其余保持中性，不会硬套一个并不贴切的颜色。

不变量留在库里。校验位于 tools/research_graph.py，也就是本插件为之而写的研究记录中，并由其测试套件强制执行；本插件只读取存储和渲染后的页面，绝不成为第二个更弱的检查器。插件若自行判定什么才算合法图，就会与构建所信任的那一个产生偏差。

读取第二个存储

工具及其路由默认读取一个存储，也可按请求读取任意具名存储，因此第二个来源 —— 模型的知识库 —— 通过与研究记录相同的列表、展示、前沿、类比和页面操作。在行配置中命名存储，如上面的示例所示。然后，不带 store 的 knowledge_dag 读取默认存储，带 store: "model" 则读取命名的那个——HTTP 上同理，/dsh-knowledge-dag/graph?store=model 和 /dsh-knowledge-dag/node?id=<id>&store=model 会响应它。默认存储报告为 research，面板的存储选择器列出该行配置的任何内容。

未知名称会报告为错误，而不是回退到默认值，因此拼写错误不会悄悄显示错误的存储。第二个存储保持相同的约定：节点是 JSON 文件，页面是生成的 markdown。形状不同的存储需要自己的读取器，而不是对这一个的第二种解释。

检查浏览器那一半是否仍能激活

浏览器那一半没有构建步骤，因此没有东西对它做类型检查，也没有东西在浏览器之外加载它：损坏的 client.cjs 只会表现为 harness 启动审计报告此条目未激活。tests/activate.mjs 是无需应用程序就能捕获它的关卡。它评估真实的 client.cjs，在强制 0.2.0 注册表规则的服务假件上调用 apply，将每个注册渲染一次，并检查帧触发器读取的是屏幕上的会话，而不是任何会话：

node tests/activate.mjs

React 来自 deepseek-harness 检出；当检出不是同级或祖父级 deepseek-harness 目录时，设置 DSH_CHECKOUT。

重启才会加载任一半。 宿主在启动时协调客户端包名册，并按内容哈希对其提供的字节进行版本控制，因此在编辑 client.cjs 后，页面重新加载会请求它已持有的修订版并获得缓存副本。更改 index.mjs 或 client.cjs 后重启应用程序，然后重新加载页面。

两半如何组合在一起

宿主半（index.mjs）注册一行：knowledge_dag 工具，以及通过 ctx.inject(['webServer'], …) 延迟的四个路由。两条规则，均取自可用的参考插件 moazzamak/dsh-voice-input，是保持其启动的关键：仅一行，因为启动审计会在任何条目处于待处理状态时失败，而等待浏览器载体的第二行会破坏无头、SDK 和 ACP 配置档；并且绝不在 apply 期间读取载体，因为在那里读取它会看到 undefined——这就是参考插件的路由静默地从未注册的原因。它通过 ctx.fs 读取所有内容，并故意不注入 shell 服务：未挂载 shell-executor 行的配置档可以正常注册调用，但在首次使用时失败。

客户端半（client.cjs）通过 harness 加载器注册自身：

window.__ModuleLoader__.load({ id, factory })

它声明它绑定的服务（slots、sidebarRight， sidebarRightTabs、layout），并注册标签页类型、标签页主体、标题 chip 和框架触发器。节点主体和页面从宿主半边获取，而不是在这里重建，所以视图不会与读者信任的文件产生分歧。