dsh-graph

dsh-graph

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

🚀 v0.15.0 新功能

• 适配 DeepSeek Harness 0.1.6 宿主 API 变更：会话导航/focus 职责从 sessions 服务迁移到 uiWorkspace，统一走 openSessionTarget；子代理聚焦、点击「转到对话」、「交给产品经理」与用户反馈派发链路在新宿主下全部恢复可用。
• 看板实时会话区在 0.1.6 下恢复显示：按新宿主的 retain 生命周期先保留会话引用再借取 binding，不再出现「⚠️ 会话未接入（不在会话列表）」与「模型目录不可用」，真实 tokens / ctx / 模型可正常渲染；0.1.5 无 retain 时自动回退被动 binding，双向兼容。
• 批量接受的主管通知在 0.1.6 下恢复：通知派发改为能力探测分流，单卡接受与批量接受同形路径一并修复。
• 并发槽位耗尽给出可操作提示：0.1.6 引入子代理激活上限（默认 8 个活跃 continuable 子代理），容量耗尽或冷恢复被拒时不再只透出英文错误码。
• 看板刷新按钮重置自动刷新倒计时：点击刷新后倒计时立即回到完整周期，不再沿旧终点继续递减。
• 「定义/润色」复制模板改写为自述式主管指令：标题标明由主管处理，明确接收者角色、下一步动作与本次边界（仅处理定义/润色，不执行代码、不推进状态或版本）。

✅ DSH 版本兼容性（重点）：v0.15.0 支持 DeepSeek Harness 0.1.2-rc.1 ~ 0.1.6-alpha.2。本次周期在 0.1.6-alpha.2 与 0.1.5-rc.2 两个宿主版本上做了双向兼容实测：0.1.6-alpha.2 上完成会话导航/focus、实时会话区、批量接受通知与并发槽位提示的实机验证；0.1.5-rc.2 上完成被动 binding 回退路径的实机验证（无 retain 时不破坏既有行为）。更早的 0.1.2-alpha.x ~ 0.1.5 系列按工具与提示词契约向后兼容，但未在本次周期复跑。

✅ 跨平台（v0.11.0 起）：Windows 原生不可用问题已修复，并在原生 Windows（win32/x64）与 macOS（darwin/arm64）真机复验通过；v0.15.0 已在原生 Windows 上重跑 T1–T5 门禁并全绿（通过 10 项 / 失败 0 项 / 告警 0 项）。

已知限制：macOS 上若工作区路径经显式传入且含符号链接（例如位于 /tmp、/var 之下），会被拒绝并报 graph root symlink is not allowed；由 process.cwd() 推导的路径不受影响。

单包发布：npm 包名 dsh-graph（当前版本 v0.15.0）。一个包同时提供：

• 面向 agent 的 44 个 graph_* 工具（覆盖目标全生命周期）+ /api/dsh-graph* REST 端点；
• 浏览器二维泳道看板（lib/client.js），渲染进 conversation.view 槽。

数据以文件 + 事件流形式落在工作区 .dsh-graph 目录，git 友好、可审计。

核心概念

• 基于图的目标管理：目标是自足实体——自然语言任务 + 动态生成的取证计划与质量判据；任务类型不预先模板化，结构化的是生命周期与求值语义。
• 四阶段生命周期：描述 → 收集 → 执行 → 确认，由引擎强制的状态机：draft → planning → collecting → ready → in_progress → review → delivered（任意阶段可进入 blocked）。
• 判据先于执行：进入执行前先登记质量判据，评审按逐条判据核验产出物。
• 上下文卡片：目标 Runner 的种子上下文，生命周期 empty → collecting → filled → reviewed；形态分文本 / 文件 / 图片 / 数据。
• 排期：Backlog（暂存池）↔ Version（批量质量管理）↔ 独立目标（standalone）；看板泳道顺序是展示态，可拖拽调整。
• 换会话交接：graph_handoff 生成交接文档（board 投影 + 长期记忆 + 环境事实），graph_claim_supervisor 由新会话接管。

当前功能状态

• 全链路 i18n（v0.9.2）：看板 UI、工具描述与全部 LLM 提示词中英双语；整篇提示词文档按语言后缀文件区分（supervisor-guide.zh.md / .en.md），跟随 DSH 界面语言（locale.preference）或可在看板设置中显式指定。
• 结构化执行状态（v0.9.2）：graph_report_status 支持 state 枚举（working/blocked/done/error），看板活跃判断以结构化状态优先、关键词匹配仅作遗留回退。
• 目标描述就地编辑（v0.9.2）：目标弹窗中描述可直接进入 Markdown 编辑态保存（graph_set_description）。
• 更新强调：目标被外部编辑后，看板卡片播放更新强调动画；弹窗打开期间的变化在关闭弹窗时补播；系统开启 reduced-motion 时降级为静态高光。
• 浅色主题：看板、弹窗与抽屉完整适配浅色 / 深色两套主题（跟随 DSH 主题变量）。
• 信息收集：目标详情弹窗的上下文卡片区显示「🔎 信息收集」。
• 卡片标题：直接显示目标标题，无 🎯 前缀。
• 弹窗交互：从弹窗内容开始框选文本并拖到弹窗外松开，不会误关闭弹窗。

安装

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

需要 Node ≥ 22（包内 core 为编译后 .js）。已发布版本经 npm 与 dsh-market 生态（dsh-market / DshMarketPlace / DSH Get，见 docs/release-handbook.md）分发。

依赖说明：宿主提供的核心包（@deepseek-ai/cordis ^4.0.2、@deepseek-ai/schemastery ^3.18.2、@deepseek-ai/dsh-settings ^0.1.5-rc.2）以 peerDependencies + peerDependenciesMeta.optional（DSH 生态惯例）声明，由 DSH 宿主环境提供，安装不产生 peer 告警；yaml 为插件自带运行依赖（声明在 dependencies 中），避免产生重复的核心包实例。

✅ DSH 版本兼容性（重点）：v0.15.0 支持 DeepSeek Harness 0.1.2-rc.1 ~ 0.1.6-alpha.2（最新的 0.1.6-alpha.2 已适配并实测通过）。本次周期在 0.1.6-alpha.2 与 0.1.5-rc.2 两个宿主版本上做了双向兼容实测：0.1.6-alpha.2 上完成会话导航/focus、实时会话区、批量接受通知与并发槽位提示的实机验证；0.1.5-rc.2 上完成被动 binding 回退路径的实机验证（无 retain 时不破坏既有行为）。更早的 0.1.2-alpha.x ~ 0.1.5 系列按工具与提示词契约向后兼容，但未在本次周期复跑。

平台范围：Linux（WSL2）、原生 Windows、macOS 均已验证（三平台使用同一安装包）。本版本（v0.15.0）已在 Linux（WSL2）与原生 Windows 上重新实测——Windows 侧 T1–T5 分层门禁在原生 win32/x64 上全绿（通过 10 项 / 失败 0 项 / 告警 0 项，含跨进程并发 CAS「4 抢 1」）；macOS 最近一次真机复验为 v0.11.0，自 v0.11.0 以来 core/platform.ts 与文件锁相关代码零改动。此前 Windows 不可用的两类问题——① core/ops.ts 使用 POSIX 专用文件锁常量（目录当 fd 打开、O_DIRECTORY、O_NOFOLLOW）；② 宿主提供的核心包被同时写进 dependencies 与 peerDependencies——已在 v0.11.0 修复，并在原生 Windows 与 macOS 真机复验通过。已知限制：macOS 上经显式传入且含符号链接的工作区路径（如位于 /tmp、/var 之下）会被拒绝并报 graph root symlink is not allowed；由 process.cwd() 推导的路径不受影响（Node 返回物理路径），但建议一律使用真实路径（后续版本继续跟进）。

提供的工具

44 个 graph_* 工具，按功能分组：

各工具具体含义见 dsh-graph-host/README.md 或 graph_help。

看板（浏览器客户端）

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

数据目录

<workspace>/.dsh-graph：跟随调用会话的 workspace（session.header.cwd），数据落在每个项目自己的 .dsh-graph，git 友好。包含 backlog/、goals/、versions/、events.jsonl（事件流，唯一事实源）等。首次触达某 workspace 自动生成骨架，幂等、不建 demo 数据；.dsh-graph 也可配置为独立 Git 仓库（见 docs/ 与 scripts/migrate-dsh-graph-repo.sh）。

仓库结构（monorepo）

• core/——核心层源码（唯一事实源），经 scripts/sync-core.sh 编译成 dsh-graph-host/core/*.js 进发布包。可基于core开发各类UI / CLI / REST / agent 工具，核心层不依赖 DSH。
• dsh-graph-host/——单包发布物：index.js（工具 + REST 端点）、lib/client.js（看板）、cordis.patch.yml（dsh.bundle）、supervisor-guide.zh.md、supervisor-guide.en.md、README.md、LICENSE。
• schema/、docs/、scripts/——数据 / 设计文档 / 构建脚本。

开发

bash scripts/sync-core.sh          # 修改 core 后同步进包
node --test core/tests/*.test.ts   # 全量测试

# 复现 README 截图（虚构演示数据，写仓库外 /tmp，不提交 mock .dsh-graph）：
node scripts/dsh-graph-mock-seed.mjs --validate               # 生成 nebula-notes mock 数据
CWD=/tmp/dsh-graph-mock-demo bash scripts/dev-dsh-instance.sh run --port 3082  # 测试实例（开「看板」tab）
# 截图：同一次 seed、同一实例、固定视口——看板全景 → screenshot/screenshot-1.png；
# 点击看板上的目标卡片打开详情弹窗 → screenshot/screenshot-2.png

License

MIT（Copyright © 2026 miuzel）