dsh-graph

dsh plugin --profile web add dsh-graph

dsh-graph

[中文](#中文) | [English](#english)

<p align="center">

<img src="https://raw.githubusercontent.com/miuzel/dsh-graph/main/docs/banner.webp" alt="dsh-graph —— Agent 工作的目标化管理" width="100%">

</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-graph"><img src="https://img.shields.io/npm/v/dsh-graph?style=flat-square&label=npm&color=cb3837" alt="npm version"></a>

<a href="https://www.npmjs.com/package/dsh-graph"><img src="https://img.shields.io/npm/dm/dsh-graph?style=flat-square&label=downloads&color=cb3837" alt="npm downloads"></a>

<a href="https://raw.githubusercontent.com/miuzel/dsh-graph/main/dsh-graph-host/package.json"><img src="https://img.shields.io/node/v/dsh-graph?style=flat-square" alt="node engine"></a>

<a href="https://awesome-dsh-plugin.com"><img src="https://img.shields.io/badge/awesome--dsh--plugin-listed-2f6feb?style=flat-square" alt="awesome-dsh-plugin listed"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license MIT"></a>

<a href="https://raw.githubusercontent.com/miuzel/dsh-graph/main/dsh-graph-host/package.json"><img src="https://img.shields.io/badge/DSH-%3E%3D0.1.5--rc.2%20%3C0.2.2--0-2f6feb?style=flat-square" alt="DSH host range"></a>

</p>

---

中文

概述

dsh-graph 是面向 DeepSeek Harness (DSH) 的目标看板插件。它将大模型智能体（Agent）的工作流组织为基于图的目标管理（Graph-based Goal Management）。

本插件采用一体化单包分发（npm 包名 dsh-graph），同时集成两大核心能力：

• Host 端：向 DSH Agent 提供覆盖目标全生命周期的 53 个 graph_ 工具，并暴露 /api/dsh-graph REST API（支持看板投影、目标详情查询与写操作）；
• Client 端：无缝内嵌于 DSH Web 控制台（conversation.view 槽位）的浏览器二维泳道看板，提供直观的可视化交互与实时追踪。

数据以本地纯文本与事件流形式存储于工作区的 .dsh-graph/ 目录，Git 友好、天然支持协同对账与审计追踪。

---

安装方式

在 DSH 环境中运行以下命令即可安装：

dsh plugin --profile <profile-name> add dsh-graph

当前版本：v0.23.0。环境要求：Node.js ≥ 22（包内预编译 core 运行时）。宿主提供的核心包（@deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-settings）以 peerDependencies + peerDependenciesMeta.optional（DSH 生态惯例）声明，由 DSH 宿主环境提供，安装不产生 peer 告警；yaml 为插件自带运行依赖（声明在 dependencies 中），避免产生重复的核心包实例。

宿主兼容范围：engines.dsh 与 peerDependencies["@deepseek-ai/dsh-settings"] 同步声明 >=0.1.5-rc.2 <0.2.2-0（上界 -0 排除 0.2.2 的一切预发布与正式版；整条 0.2.1 线已在范围内），engines.dsh 供 dsh-market 等宿主感知型市场在卡片展示与安装/更新预检中读取。⚠️ 宿主的安装/启动门禁只读 peerDependencies、不读 engines.dsh，故两处必须同步放宽（只改 engines.dsh 无效）。实测通过的宿主：0.1.6-alpha.2 ~ 0.1.7-rc.2、0.2.0-rc.1、0.2.0-rc.2（负责人 2026-09-30 真机复验）、0.2.1-alpha.2（2026-10-09 隔离实例无豁免复验）。⚠️ 上列是历史轮次的安装/启停/REST 结论，覆盖的是各自版本的产品代码；g-507 引入的 HTTP 鉴权入口只在 0.2.1-rc.2 实测（见下文「HTTP 鉴权」一节），不得据本段推断其它版本上的鉴权结论。该区间顺带覆盖的 0.1.8 系在 npm 上从未发布（0.1.7-rc.2 之后直接跳版到 0.2.0-rc.1），故为空集，不构成未实测声明。

平台状态：

平台 · 本版状态

Linux / WSL2 · ✅ 已实测通过（本版全量测试 fail 0；H 系列共享探针在本版全绿）

原生 Windows · ✅ 本版已实测通过（2026-11-02，win32/x64 + Node v24.21.0，宿主 0.2.1-rc.5，通过 22 / 失败 0 / 告警 0）：详见 platform-gate §7.13 回填表 —— T1 静态/台账（67 项 268 处命中未登记 0）/ 派发可用（零硬编码 shell 名）/ H 组合探针（H1–H6 除 H3 外全绿）全部通过；T3 看板文件系统生命周期 32 步盘面断言全通过；T4/T5 实例启动就绪与 REST 鉴权换票冒烟通过。

macOS · ⏳ 本版未验证：v0.23.0 未在原生 macOS 上执行真机门禁 ⇒ 不得读出「已通过」；结论同样以 platform-gate §7 回填表（不随包发布）为准。历史记录见 platform-gate §7.4 / §7.7，只覆盖各自版本的产品代码。

三平台使用同一安装包。已知限制：① macOS 默认文件系统 APFS 大小写不敏感 —— 仅大小写不同的目标编号 / 版本泳道会落到同一实体，请勿只用大小写区分；② macOS 上若工作区路径经显式传入且含符号链接（如位于 /tmp、/var 之下），会被拒绝并报 graph root symlink is not allowed；由 process.cwd() 推导的路径不受影响。

最新亮点（v0.23.0）

• 长任务智能关照与僵局干预：主管空闲期间对进行中的子代理长任务按生效间隔自动发起巡检与状态把关；支持连续未回复/进展停滞自动升级等待人工，到期只触发巡检而不武断中断执行，支持整组关照的暂停、继续与重置。
• 子代理时间预算调度与动态基准重算：支持在目标中显式配置预计任务时间预算（未配置继承项目/全局默认阈值）；首次派发、运行中调整预算或主管向运行中子代理发送新消息时，立即依据最新时间基准重新计算关照截止，并保持至少 5 分钟无答有效冷却防频发唤醒。
• 运行轮次精确隔离与历史保真追溯：子代理运行按起止时点划定独立轮次，停止即停表，重新运行自起新轮；精确记录每轮起始预算与变更时间线，禁止以停止时刻预算冒充整轮预算，正常宿主重建遇到同一运行中任务不拆分轮次并如实标注观察空窗。
• 主管会话智能保活机制：名下有子代理在运行且主管处于空闲时，自动在适当时机进行有界续期与单次防离线保活，避免长时间未交互导致上下文失效。
• 插件 HTTP 接口安全加固与派发去重：全面封闭无凭证访问风险，对齐宿主统一鉴权与身份白名单校验；强化派发准入门禁，严格防止同一目标并发派发重复执行尝试，杜绝状态冲突与资源争用。

完整变更史见 CHANGELOG。已发布版本支持通过 npm 与 dsh-market 生态分发。

---

升级残留自检与清理

现象（外部报告）：升级宿主后 Web GUI 冷启动报

web boot: N entry did not activate / <插件名>: failed —— 插件的 host 半边（graph_* 工具）正常、热加载也正常，只有浏览器半边不激活。

成因：dsh.client.inject 不是「名录」，而是加载顺序边。浏览器端 loader

（@deepseek-ai/dsh-client-modules/lib/client.js）只对 inject 中已存在于客户端清单的包名做前置加载，

名字不在清单里就静默跳过。而 @deepseek-ai/dsh-client-runtime 自 dsh 0.2.x 起不再随宿主分发

（在 dsh 0.1.5-rc.2 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.2 的安装树里均无此包），但它的包清单仍声明 dsh.client：

升级过程中若这个旧条目/旧副本残留在 profile 里，它会重新变成一条客户端清单行；该行的加载失败会被级联成

client-modules: "<插件>" not loaded because dependency "…" failed，把任何仍声明它的插件一起拖死。

干净安装没有这一行，所以不复现。dsh-graph 已删除该声明（即使残留仍在，本插件也不再是它的消费者）。

首选动作：把 dsh-graph 升级到含本修复的版本即可，残留无需处理。 含本修复的版本已不再声明该死引用 ⇒ 无论 profile 里是否还残留旧副本，本插件都不再是它的消费者，也不会被它拖死。下面的自检只是「想确认现状」时的只读排查；清理残留是可选的进阶动作。

自检（全部只读；下述命令已在隔离实例 dsh 0.2.0-rc.2 / 0.1.7-rc.2 上实测）：

把 <DSH_HOME> 换成你的 DSH home：web 版默认是 ~/.dsh（也可由 DSH_HOME 环境变量指定）；桌面版是另一套路径，请以该壳的配置/日志里显示的 profile 目录为准。

# ① 本插件的声明 —— 期望 3 项，且不含 dsh-client-runtime
node -e 'console.log(JSON.stringify(require(process.argv[1]).dsh.client.inject))' \
  "<DSH_HOME>/profiles/web/node_modules/dsh-graph/package.json"

# ② profile 清单里是否还列着它 —— 期望输出 0
#    （注意：grep -c 在计数为 0 时退出码是 1，看打印出的数字即可，不要看退出码）
grep -c dsh-client-runtime "<DSH_HOME>/profiles/web/package.json"

# ③ 整个 DSH home 内是否还有名为 dsh-client-runtime 的目录 —— 期望无输出
find "<DSH_HOME>" -type d -name dsh-client-runtime 2>/dev/null

# ④（可选，仅在 Web 版且实例正在运行时）客户端清单里是否还有该行 —— 期望无输出
#    「dsh web」启动行会打印带 token 的 URL，把它原样填进 <URL>
curl -sL -b "" "<URL>" | grep -o '"@deepseek-ai/dsh-cl

…(truncated)