dsh-graph-host

dsh-graph

中文 | English

---

中文

概述

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

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

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

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

---

安装方式

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

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

当前版本：v0.22.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 隔离实例无豁免复验）。该区间顺带覆盖的 0.1.8 系在 npm 上从未发布（0.1.7-rc.2 之后直接跳版到 0.2.0-rc.1），故为空集，不构成未实测声明。

平台状态：

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

最新亮点（v0.22.0）

• 完成摘要去冗余瘦身与交回报文精简：目标弹窗的「完成摘要」页签全面重构，告别动辄数十 KB 的历史评论与流程沿革全量搬运，收敛为聚焦最新成果、判据达成与自动化证据引用的「终态交付快照」；子代理交回报文骨架彻底解耦执行者与评审者结构，阅读负担与无谓 Token 消耗直降 90% 以上。
• 目标删除与隔离工作树清理防护闭环：删除已归档目标前主动检测其关联的 Git 隔离工作树，存在未清理分支树时严格阻断，防止残留失控；同时支持安全清理已删除目标的残留孤儿工作树，彻底消解真实宿主归属标记下的清理死锁。
• 共享卡片全生命周期与保底解除通道：工具层补齐安全删除零引用共享卡片的能力（非零引用严格拒绝）；在工作区按需裁剪关闭共享卡片模块后，依然为目标保留保底解除引用的操作手段，彻底根除模块裁剪时的配置死锁。
• 目标流转评审记录自愈消除死链：目标在跨版本排期、移回独立目录或归档/取消归档移动过程中，其历史独立评审记录自动同步重写文件新路径，根除因目标物理搬迁导致的评审报告死链。
• 全新官方插件图标与评审统计口径披露：新增符合 DSH 插件规范的高质感拓扑看板官方矢量图标（icon.svg）；并在使用说明中完整披露代码评审变更规模统计中非产品路径（如 docs/*）的白名单判定与计算规则，消除认知与策略偏差。

完整变更史见 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-client-runtime"' | head -1

隔离实例实测结果（dsh 0.2.0-rc.2）：

• ① → ["@deepseek-ai/dsh-client-ui-settings","@deepseek-ai/dsh-client-ui-primitives","@deepseek-ai/dsh-client-ui-sidebar-right"]
• ② → 0
• ③ → 无输出
• ④ → 无输出；curl 返回 200、35125 字节（同一命令对清单里确实存在的行名如 @deepseek-ai/dsh-client-ui-settings 能打印出来）
• 命令有效性反证（都不是恒真空跑）：在一份确实含该名字的清单文件上 ② 打印 1；在 profile 里放入名为 dsh-client-runtime 的目录后 ③ 确实打印出该路径（随即移除）

清理（可选，先备份）：仅当你确实想清干净、且 ②非 0 或 ③有输出时：先备份 profile，再删除 ③ 打印出的残留目录（并在 ② 命中的清单里去掉对应条目），然后重启宿主 —— 客户端包元数据在激活期缓存，增删客户端插件必须重启才生效。风险提示：在 live profile 上直接删目录/改清单有改坏环境的风险；更稳妥的替代是重装同版本 dsh-graph 或新建一个干净 profile。自行清理前务必留备份，异常时用备份复原。

未验证：无桌面壳环境可用（@deepseek-ai/dsh-desktop 在 npm 为 E404）。上述现象与成因链引用外部报告与宿主源码， 不声称已复现桌面壳症状。

---

核心特性

• 四阶段生命周期状态机： 引擎严格约束状态迁移：draft → planning → collecting → ready → in_progress → review → delivered（任何阶段均可标记进入 blocked 阻塞状态）。
• 判据先于执行（Criteria Before Execution）： 在目标派发执行前必须登记明确的质量验收判据，最终评审严格依照逐条判据核验交付物，杜绝模糊交付。
• 结构化上下文卡片： 支持文本（Text）、文件（File）、图片（Image）、数据（Data）等多种上下文类型。经历 empty → collecting → filled → reviewed 闭环生命周期，为执行子代理提供精确的上下文种子。
• 二维泳道看板： 横向按生命周期阶段划分列，纵向按排期划分版本（Version）、暂存池（Backlog）与独立目标（Standalone）泳道；支持拖拽排期。
• 目标间关系标记： 目标之间可标记「取代 / 调整 / 补充 / 相关」四类关系（也可解除），关系只记在目标文件（frontmatter）这一处真源；看板卡片显示关系徽标，目标弹窗在「目标描述」下方直接列出关系清单（含跨版本与已归档标注）。
• 流畅跨会话交接（Handoff & Supervisor Claim）： 支持生成包含看板投影、长期记忆与关键环境事实的 HANDOFF.md，换会话后新 Supervisor 可幂等认领上下文并快速接管。
• 现代交互与双主题适配： 完整适配深色与浅色双套主题（自动跟随 DSH 全局主题变量）；外部数据更新时支持微光动画提醒（支持系统的 prefers-reduced-motion 无障碍降级）；弹窗拖拽防误关。

---

设计哲学（面向首次接触本插件的用户）

想先弄懂「dsh-graph 为什么这样组织开发」——目标生命周期与状态机、判据门禁与人工 gate、派发与隔离三件套、 attempt 与结果面、独立复核与留痕真源、版本泳道与发布红线、记忆分级、事件先行——请读 设计哲学（中文）： 它逐条给出代码真源引用，并附 archify 交互式图（内联静态预览 + 可交互 HTML）；图只画今天已实现的 状态流转与角色分工，图内不含文件、函数或内部产物名，1.0 路线见文档 §13。

---

Agent 工具速查表

dsh-graph 为 Agent 提供了完善的工具链（共 51 个 graph_* 工具），按功能划分为以下分类：

---

浏览器看板说明

内嵌于 DSH Web 界面：

• 二维泳道布局：清晰展现多个版本的推进节奏，支持灵活查看不同泳道和阶段；
• 分级评审策略支持：通过 graph_get_settings / graph_update_settings 配置项目实际的 review.regions / review.contract_paths / review.non_product_prefixes，未登记区域安全升级 strict，空契约默认 M1 不触发；
• 实时流式更新：卡片与顶部状态栏直观反映 Agent 汇报的最新执行状态；外部文件变更触发动画闪烁；
• 丰富弹窗与抽屉交互：点击卡片可展开目标详情弹窗，查看质量判据、上下文卡片与 Attempt 历史。

---

侧边栏用法

右侧栏的「看板」与会话页的「看板」页签是同一份实现——同一个看板组件、同一套头部与窄档逻辑，两侧完全一致（零 host 门控），任选其一即可。

• 入口：在会话里打开右侧栏 → 点「看板」磁贴；打开的看板面板会成为右侧栏顶部的一个页签常驻，随时切回。
• ⋯ 工具：刷新 / 标签筛选 / 记忆 / 项目知识库（共享条目）/ 看板设置 / 已归档。工具条按头部实测宽度装不下自动折叠为这一项（不是写死的窗口断点）。
• [🏷️] 版本管理：角落的方形图标按钮（可访问名称为「🏷️ 版本管理」），点开版本管理抽屉；紧邻其右是同一行等高的 创建版本。
• 版本选择器：位于泳道行 [+]（新建目标）左侧，切换当前显示的泳道（具体版本 / Backlog / 独立目标）。
• 窄档行为（分档依据是看板根容器实测宽度——即看板组件自身元素的 clientWidth，不是窗口宽度、也不是浏览器视口宽度）：
  • ≥ 480px（宽档）：多泳道横向并排，各版本 / Backlog / 独立目标可同时查看；
  • < 480px（单泳道档）：阶段列由横向并排改为纵向堆叠，泳道内容由版本选择器决定（具体版本 / Backlog / 独立目标三选一；工作区一个版本都没有时，默认落点就是「独立目标」，选择器当前项显示「独立目标」）；该档没有版本折叠开关（收起来等于空板），并同时把工具条强制折叠为「⋯ 工具」、隐藏 DEBUG 行。
  • 怎么把看板放进 < 480px：宿主页签的宽度由页签布局模式决定，不是拖出来的——实测（1600px 视口）单页签 719px、页签上的 分栏 之后每页签 359px（该档随窗口宽度变化）、全屏 799px。所以默认单页签宽度（719px）落在宽档，此时不会出现单泳道；需要单泳道档时用页签上的 分栏，或把窗口收窄到看板面板实测宽度 <480px。进入后一眼可验：六个阶段块纵向堆叠，且泳道标题右侧出现版本选择器（当前项为具体版本 / Backlog / 独立目标）。
  • 宽档残留（实测）：宽档网格的最小宽度实测约 956px，所以看板面板实测宽度在这之下时（例如默认单页签 719px），宽档网格仍会横向滚动、把「确认 / 批量接受」列推到可视区外；真正消除横向滚动的是单泳道档（<480px）。
  • 版本选择器只在单泳道档渲染：宽档下整个看板没有版本选择器（该元素不渲染）。因此宽档里能看到的「全部版本」只可能来自打开的下拉选项列表，而不是当前选中项；单泳道档未显式选择任何视图时，当前项是「独立目标」而不是「全部版本」。

效果截图见仓库 screenshot/sidebar-kanban.png（虚构演示数据 nebula-notes，右侧栏宽度落在 < 480px 单泳道档）；本 npm 包不包含仓库的 screenshot/ 目录，故此处只给出仓库路径。

---

Profile 全局设置（子代理默认值）

子代理默认 provider / model、推理档位、执行模式、提示词语言与补充提示词是 profile 级全局默认 —— 写入当前 DSH profile、跨 workspace 生效，且 workspace 的 project.yaml 明确配置与单次派发参数都更优先。

同一个设置页在两个入口都能打开，两处是同一份实现、读写同一份 profile 配置：

• 设置 → 看板设置：左侧设置导航里的独立设置页；
• 右侧栏 → 插件 → dsh-graph：组合包详情页里的配置区（按包名 dsh-graph 绑定）。

宿主未提供某个位面时（精简 profile / 旧宿主），对应席位自动不出现，看板与工具不受影响；两处都取不到设置服务时，页面如实提示当前 profile 未暴露设置服务，而不是假装已启用。配置文件落在 profile 的设置文档里（0.2.0 系宿主为 profile 的 cordis.patch.yml 中 dsh-graph-host 条目，0.1.6 系宿主为 $DSH_HOME/settings.yaml 的 dsh-graph 命名空间）。

---

数据存储说明

插件数据保存在当前工作区下的 .dsh-graph/ 目录：

• 自动初始化：首次在工作区运行工具时自动生成数据骨架，不包含多余 Demo 数据；
• Git 友好：所有数据由纯文本 YAML/Markdown 与只追加（append-only）的 events.jsonl 组成；
• 事件流对账：events.jsonl 记录每一次状态流转与操作，是唯一事实来源，可通过 graph_rebuild 随时对账；
• 多 Worktree 适配：Git Linked Worktrees 自动解析归一到主工作树的同一 .dsh-graph/ 根目录。

---

English

Overview

dsh-graph is a goal-oriented kanban plugin for DeepSeek Harness (DSH), bringing Graph-based Goal Management into Agent workflows.

Distributed as a single unified package (npm package name: dsh-graph), it provides both halves out-of-the-box:

• Host Side: Exposes 51 graph_* tools to DSH Agents covering the entire goal lifecycle, along with /api/dsh-graph* REST endpoints for board projections, goal details, and mutations;
• Client Side: A browser 2D swimlane kanban board integrated into DSH Web (the conversation.view slot) for intuitive visualization and real-time tracking.

All data is stored locally as human-readable files and an append-only event log under .dsh-graph/, making it Git-friendly, easily auditable, and collaborative.

---

Installation

Install the plugin using the DSH CLI:

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

Current version: v0.22.0. Requirements: Node.js ≥ 22 (includes the precompiled core runtime). Core packages provided by the DSH host (@deepseek-ai/cordis, @deepseek-ai/schemastery, @deepseek-ai/dsh-settings) are declared under peerDependencies with peerDependenciesMeta.optional (standard DSH ecosystem convention) and provided by the host runtime without peer warnings; yaml is retained in dependencies as a plugin-specific runtime dependency, preventing duplicate core package instances.

Host compatibility range: engines.dsh and peerDependencies["@deepseek-ai/dsh-settings"] declare >=0.1.5-rc.2 <0.2.2-0 in lockstep (the -0 upper bound excludes every 0.2.2 prerelease and final release; the entire 0.2.1 line is now inside the range); engines.dsh is what host-aware markets such as dsh-market read for card display and install/update pre-flight. ⚠️ The host's install/boot gate reads peerDependencies only, never engines.dsh, so both fields must be widened together (widening engines.dsh alone has no effect). Hosts verified: 0.1.6-alpha.2 through 0.1.7-rc.2, 0.2.0-rc.1, 0.2.0-rc.2 (verified by the maintainer on 2026-09-30), and 0.2.1-alpha.2 (verified on 2026-10-09 in an isolated instance with no version exemption). The 0.1.8 line incidentally covered by that range was never published on npm (versions jump straight from 0.1.7-rc.2 to 0.2.0-rc.1), so it is an empty set and adds no unverified claim.

Platform status:

All three platforms share the same package. Known limitations: (1) APFS, the macOS default, is case-insensitive — entries that differ only by case resolve to the same entity, so do not rely on case alone to distinguish goal ids or version lanes; (2) on macOS a workspace path that is explicitly supplied and contains a symlink (e.g. under /tmp or /var) is rejected with graph root symlink is not allowed; paths derived from process.cwd() are unaffected.

What's new (v0.22.0)

• Concise Results Summaries & Streamlined Report Skeletons: Completely redesigned the goal completion summary modal tab, moving away from bloating dozens of kilobytes of verbatim historical comments and timeline logs to a lean "Final Deliverable Snapshot" focusing on latest attempt accomplishments, criteria verifications, and automated test evidence; decoupled the child agent report skeleton between executor and reviewer structures, reducing cognitive overhead and token waste by over 90%.
• Worktree Orphan Cleanup & Goal Deletion Protection: Proactively inspects associated Git isolated worktrees before deleting archived goals, strictly blocking deletion when active/uncleaned trees remain; safely cleans orphan worktrees from previously deleted goals, fully resolving cleanup deadlocks caused by host attribution markers.
• Shared Card Full Lifecycle & Fallback Detachment: Enhances tooling to safely delete zero-reference shared cards (strictly rejecting deletion when references exist); retains a fallback detachment mechanism for goals even when the shared_cards module is deactivated in the workspace, eliminating configuration deadlocks.
• Self-Healing Review Report Paths on Goal Relocation: Automatically rewrites relative/absolute paths of historical review reports when goals are scheduled across versions, moved back to standalone goals, or archived/unarchived, completely eliminating dead links caused by directory moves.
• Official Plugin Icon & Review Scale Classification Disclosure: Ships a high-quality topological kanban vector icon (icon.svg) matching DSH plugin specifications; thoroughly documents non-product path rules (such as docs/* counting as 0 product lines) in the usage guide to align user expectations with code review policies.

See the CHANGELOG for the full history. Official releases are distributed via npm and the dsh-market ecosystem.

---

Upgrade-residue self-check and cleanup

Symptom (externally reported): after upgrading the host, a Web GUI cold start reports web boot: N entry did not activate / <plugin>: failed — the plugin's host half (graph_* tools) works and hot reload works, but its browser half never activates.

Cause: dsh.client.inject is not a directory listing, it is a load-order edge. The browser-side loader (@deepseek-ai/dsh-client-modules/lib/client.js) preloads only those inject names that already exist in the client manifest, and silently skips the rest. @deepseek-ai/dsh-client-runtime is no longer shipped with the host since dsh 0.2.x (absent from the install trees of dsh 0.1.5-rc.2 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-alpha.2), yet its package manifest still declares dsh.client. If an old entry/copy of it survives an upgrade in your profile, it becomes a client manifest row again; that row's load failure cascades into client-modules: "<plugin>" not loaded because dependency "…" failed, dragging down every plugin that still declares it. A clean install has no such row, which is why it does not reproduce. dsh-graph has dropped that declaration — even if the residue is still present, this plugin is no longer one of its consumers.

Preferred action: just upgrade dsh-graph to a build that contains this fix — the residue needs no handling. A fixed build no longer declares the dead name, so whether or not an old copy survives in your profile, this plugin is no longer one of its consumers and can no longer be dragged down by it. The self-check below is only a read-only way to inspect the current state; cleaning up the residue is an optional advanced step.

Self-check (read-only; every command below was measured on isolated instances of dsh 0.2.0-rc.2 / 0.1.7-rc.2):

Replace <DSH_HOME> with your DSH home: for the Web build it defaults to ~/.dsh (or wherever DSH_HOME points); the desktop build uses a different path — take the profile directory shown in that shell's configuration or logs.

# (1) This plugin's declaration — expect three names, without 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"

# (2) Does the profile manifest still list it? — expect the number 0
#     (note: `grep -c` exits 1 when the count is 0 — read the printed number, not the exit code)
grep -c dsh-client-runtime "<DSH_HOME>/profiles/web/package.json"

# (3) Is there still a directory named dsh-client-runtime anywhere under the DSH home? — expect no output
find "<DSH_HOME>" -type d -name dsh-client-runtime 2>/dev/null

# (4) Optional, Web build with a running instance only: is it still a row in the client manifest? — expect no output
#     `dsh web` prints a tokenized URL on startup; paste it verbatim as <URL>
curl -sL -b "" "<URL>" | grep -o '"@deepseek-ai/dsh-client-runtime"' | head -1

Measured on an isolated instance (dsh 0.2.0-rc.2):

• (1) → ["@deepseek-ai/dsh-client-ui-settings","@deepseek-ai/dsh-client-ui-primitives","@deepseek-ai/dsh-client-ui-sidebar-right"]
• (2) → 0
• (3) → no output
• (4) → no output, while curl returned 200 with 35125 bytes (the same command does print a row name that is present in the manifest, e.g. @deepseek-ai/dsh-client-ui-settings)
• Command-sanity counter-checks (neither command is vacuously silent): (2) prints 1 on a manifest file that really contains the name, and (3) did print the path after a directory named dsh-client-runtime was deliberately placed into the profile (removed again immediately).

Cleanup (optional, back up first): only if you really want a clean slate and (2) is non-zero or (3) has output: back up the profile first, then remove the residu