dsh-graph#dsh-graph-host

dsh-graph

中文 | English

中文

概述

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

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

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

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

安装方式

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

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

环境要求：Node.js ≥ 22（包内预编译 core 运行时）。已发布版本支持通过 npm 与 dsh-market 生态分发。

核心特性

四阶段生命周期状态机：

引擎严格约束状态迁移：draft → planning → collecting → ready → in_progress → review → delivered（任何阶段均可标记进入 blocked 阻塞状态）。

判据先于执行（Criteria Before Execution）：

在目标派发执行前必须登记明确的质量验收判据，最终评审严格依照逐条判据核验交付物，杜绝模糊交付。

结构化上下文卡片：

支持文本（Text）、文件（File）、图片（Image）、数据（Data）等多种上下文类型。经历 empty → collecting → filled → reviewed 闭环生命周期，为执行子代理提供精确的上下文种子。

二维泳道看板：

横向按生命周期阶段划分列，纵向按排期划分版本（Version）、暂存池（Backlog）与独立目标（Standalone）泳道；支持拖拽排期。

流畅跨会话交接（Handoff & Supervisor Claim）：

支持生成包含看板投影、长期记忆与关键环境事实的 HANDOFF.md，换会话后新 Supervisor 可幂等认领上下文并快速接管。

现代交互与双主题适配：

完整适配深色与浅色双套主题（自动跟随 DSH 全局主题变量）；外部数据更新时支持微光动画提醒（支持系统的 prefers-reduced-motion 无障碍降级）；弹窗拖拽防误关。

Agent 工具速查表

dsh-graph 为 Agent 提供了完善的工具链，按功能划分为以下分类：

分类	工具名称	核心说明

目标生命周期	`graph_create_goal`	创建目标（默认放入 Backlog，可指定版本）

	`graph_set_description`	设置/更新目标描述正文（Markdown）

	`graph_set_goal_tags`	设置目标标签列表（最多 20 个，乐观并发）

	`graph_transition`	推进目标状态机迁移（进入 blocked 需附原因）

	`graph_archive_goal`	归档已完成或已废弃的目标

	`graph_delete_goal`	安全删除已归档的目标
	`graph_list_worktrees`	查询 Git worktree 清理候选（只读，不自动删除）
质量判据	`graph_set_criteria`	登记目标验收判据（严格在执行前设定）

上下文卡片	`graph_add_card`	创建上下文卡片占位（text / file / image / data）

	`graph_fill_card`	填充卡片内容并生成看板简要摘要
	`graph_delete_card`	删除未在收集中的卡片

附件管理	`graph_store_attachment`	存储文件附件到目标
排期管理	`graph_move_goal`	在 Backlog、独立目标与版本之间移动排期

执行派发	`graph_start_attempt`	派发执行 Attempt，启动并绑定可续轮子代理

	`graph_record_attempt_handoff`	记录前序 Attempt 的返工约束与排查基线

记忆管理	`graph_memory_add`	写入按需/常驻记忆条目

	`graph_memory_remove`	删除指定记忆条目

状态汇报	`graph_report_status`	汇报当前 Attempt 进度（看板卡片实时显示）
评审裁决	`graph_resolve_accept`	裁决交付验收（verdict: accept / object）

协作与交接	`graph_add_comment`	向目标追加可追溯的讨论与反馈历史

	`graph_claim_supervisor`	新会话接管 Supervisor 并更新会话元数据

数据与校验	`graph_validate`	执行全量不变式检查（状态、依赖环、卡片引用）

浏览器看板说明

内嵌于 DSH Web 界面：

二维泳道布局：清晰展现多个版本的推进节奏，支持灵活查看不同泳道和阶段；
实时流式更新：卡片与顶部状态栏直观反映 Agent 汇报的最新执行状态；外部文件变更触发动画闪烁；
丰富弹窗与抽屉交互：点击卡片可展开目标详情弹窗，查看质量判据、上下文卡片与 Attempt 历史。

数据存储说明

插件数据保存在当前工作区下的 .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 a full suite of 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 (lib/client.js) integrated into DSH Web (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

Requirements: Node.js ≥ 22 (includes precompiled core runtime). Official releases are distributed via npm and the dsh-market ecosystem.

Key Features

Four-Phase Lifecycle State Machine:

Enforced by the core engine: draft → planning → collecting → ready → in_progress → review → delivered (with a blocked escape hatch available at any stage).

Criteria Before Execution:

Acceptance criteria must be explicitly defined prior to execution. Deliverables in the review phase are verified strictly against individual criteria, preventing ambiguous delivery.

Context Cards:

Supports Text, File, Image, and Data cards. Follows a structured lifecycle (empty → collecting → filled → reviewed) to seed precise task context for execution subagents.

2D Swimlane Board:

Columns represent lifecycle stages, while horizontal swimlanes organize goals by Version, Backlog, and Standalone categories, complete with drag-and-drop scheduling.

Seamless Session Handoff:

Generate HANDOFF.md summarizing board projections, long-term memory, and environment facts. A new session can claim the Supervisor role idempotently via graph_claim_supervisor.

Modern UI & Dual-Theme Support:

Full Dark and Light theme adaptation following DSH variables. Subtle pulse animations highlight external updates (with prefers-reduced-motion accessibility support); drag-safe modal text selection.

Agent Tools Reference

dsh-graph equips Agents with a comprehensive set of graph_* tools:

Category	Tool	Description

Goal Lifecycle	`graph_create_goal`	Create a goal (defaults to Backlog, optional Version)

	`graph_set_description`	Set/update goal description body (Markdown)

	`graph_set_goal_tags`	Set goal tags (max 20, optimistic concurrency)

	`graph_transition`	Advance goal through lifecycle states (reason required for blocked)

	`graph_archive_goal`	Archive completed or obsolete goals

	`graph_delete_goal`	Safely delete an archived goal
	`graph_list_worktrees`	Query Git worktree cleanup candidates (read-only, no auto-delete)
Quality Criteria	`graph_set_criteria`	Define quality criteria (required prior to execution)

Context Cards	`graph_add_card`	Create a context card placeholder (text / file / image / data)

	`graph_fill_card`	Populate card content with a concise board summary
	`graph_delete_card`	Delete cards not currently collecting

Attachments	`graph_store_attachment`	Store file attachments to a goal
Scheduling	`graph_move_goal`	Move goals between Backlog, Standalone, and Versions

Execution	`graph_start_attempt`	Dispatch an execution attempt and spawn a continuable subagent

	`graph_record_attempt_handoff`	Record rework constraints, failure notes, and baseline

Memory	`graph_memory_add`	Write on-demand / standing memory entries

	`graph_memory_remove`	Remove a specific memory entry

Status Reporting	`graph_report_status`	Report progress of current attempt (live card display)
Review & Verdict	`graph_resolve_accept`	Accept or object to delivered attempts

Collaboration	`graph_add_comment`	Append historical discussion or human feedback

	`graph_claim_supervisor`	Claim supervisor role in new session & update metadata

Validation	`graph_validate`	Validate full invariants (states, cycles, card refs)

Browser Kanban UI

Embedded directly within the DSH Web console:

2D Swimlane Layout: View the progress of multiple versions and categories simultaneously;
Live Streaming Updates: Cards and the top status bar stream real-time execution updates; external file edits trigger visual highlights;
Interactive Modals & Drawers: Click cards to inspect quality criteria, context cards, attempt histories, and detailed instructions.

Data Storage

All data resides in .dsh-graph/ within your workspace:

Zero-Config Auto-Init: Generates directory structure automatically upon first tool call without dummy demo data;
Git Friendly: Managed as plain YAML/Markdown files and an append-only events.jsonl event log;
Auditability: events.jsonl serves as the authoritative single source of truth, reconcilable at any time via graph_rebuild;
Multi-Worktree Support: Git Linked Worktrees automatically resolve to the canonical graph root in the primary worktree.

License

MIT

專案介紹

專案資訊與收錄訊號

資料評分

安裝與使用

專案截圖

倉庫 README