dsh-graph

dsh-graph

把工作组织成目标看板的 DeepSeek Harness（DSH）插件 —— 基于图的目标管理（Graph-based Goal Management）。

当前版本 v0.22.0 —— npm 包名 dsh-graph，一个包同时提供面向 Agent 的 51 个 graph_* 工具（含 /api/dsh-graph* REST 端点）与内嵌 DSH Web 的二维泳道看板。

最新亮点（v0.22.0）

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

变更史见 CHANGELOG.md。

平台状态

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

安装

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

需要 Node ≥ 22。依赖说明、宿主兼容范围（engines.dsh 声明与实测宿主）、侧边栏用法、数据目录等完整内容，见 dsh-graph-host/README.md（即 npm 包内 README）。升级宿主后若 Web 看板半边不激活（web boot: … did not activate），见该 README 的「升级残留自检与清理」。

核心概念

• 基于图的目标管理：目标是自足实体 —— 自然语言任务 + 动态生成的取证计划与质量判据；任务类型不预先模板化，结构化的是生命周期与求值语义。
• 四阶段生命周期：描述 → 收集 → 执行 → 确认，由引擎强制的状态机：draft → planning → collecting → ready → in_progress → review → delivered（任意阶段可进入 blocked）。
• 判据先于执行：进入执行前先登记质量判据，评审按逐条判据核验产出物。
• 上下文卡片：目标 Runner 的种子上下文，生命周期 empty → collecting → filled → reviewed；形态分文本 / 文件 / 图片 / 数据。
• 排期：Backlog（暂存池）↔ Version（批量质量管理）↔ 独立目标（standalone）；看板泳道顺序是展示态，可拖拽调整。
• 分级评审与策略配置：支持配置项目专属模块区域 review.regions、冻结契约 review.contract_paths 与排除前缀 review.non_product_prefixes，未登记区域自动安全升级 strict，空契约默认 M1 不触发。
• 换会话交接：graph_handoff 生成交接文档（board 投影 + 长期记忆 + 环境事实），graph_claim_supervisor 由新会话幂等接管。
• 目标间关系：目标之间可标记「取代 / 调整 / 补充 / 相关」四类关系（graph_set_relation，可增可删）；关系只记在目标 frontmatter 这一处真源，看板卡片与目标弹窗直接可见。
• Profile 全局设置：子代理默认 provider / model、推理档位、执行模式、提示词语言与补充提示词，可在「设置 → 看板设置」「右侧栏 → 插件 → dsh-graph」两处任一打开，两处读写同一份 profile 配置（workspace project.yaml 明确配置优先）。

提供的工具

51 个 graph_* 工具，按功能分组（逐个说明见 dsh-graph-host/README.md 或 graph_help）：

看板（浏览器客户端）

浏览器二维泳道看板：横向为生命周期阶段列（描述 / 收集 / 执行 / 确认 / 交付 / 阻塞），每个版本一条泳道，另有 Backlog 与独立目标区；支持拖拽排期、判据 / 上下文卡片抽屉、实时状态显示、阻塞折叠等。以下为虚构演示数据（nebula-notes）截图：

侧边栏与数据目录

侧边栏入口、窄档（<480px）分档行为与「怎么把看板放进窄档」的实测说明，以及数据目录 <workspace>/.dsh-graph（纯文本 + 只追加 events.jsonl，git 友好、可 graph_rebuild 对账）的完整说明，均见 dsh-graph-host/README.md。

仓库结构（monorepo）

• core/ —— 核心层源码（唯一事实源），经 scripts/sync-core.sh 编译成 dist/core/*.js 进发布包；核心层不依赖 DSH。
• dsh-graph-host/ —— 单包发布物源码：index.js（工具 + REST 端点）、lib/client/*.js（看板源模块，构建产物为 dist/lib/client.js）、cordis.patch.yml、supervisor-guide.{zh,en}.md、README.md、LICENSE。
• schema/、docs/、scripts/ —— 数据 / 设计文档 / 构建脚本；一切构建产物落在 dist/（gitignored）。

开发

bash scripts/build.sh                 # 同步 core + 客户端产物 + 复制发布资产到 dist/
node --test core/tests/*.test.ts      # 全量测试
./node_modules/.bin/tsc --noEmit -p tsconfig.json
# 隔离测试实例（不碰主 GUI）：DSH_HOME 与 workspace 均在 ./tmp/dsh-test/ 下
bash scripts/dsh-test-web.sh <DSH版本> [--port PORT]

构建与实验一律在隔离 worktree（.worktrees/<goal>-att-<NN>）内进行；约定见 AGENTS.md，隔离实例参数与开发回路见 docs/dev-instance-guide.md。README 截图用 scripts/dsh-graph-mock-seed.mjs 生成虚构演示数据后复现。

License

MIT（Copyright © 2026 miuzel）—— 见 dsh-graph-host/LICENSE。