@LastHopeOfGPNU

dsh-spec-graph

Name: dsh-spec-graph
Availability: InStock
Author: LastHopeOfGPNU

PRD-to-implementation planning, dependency graph & execution tracking for coding agents (DeepSeek Harness plugin)

Stars: 0
Language: JavaScript
Created: Sep 7, 2026
Updated: Sep 7, 2026

Coding

GitHub repo

Introduction

SpecGraph

PRD 到实现的规划、依赖图与执行追踪（面向编码智能体的 DeepSeek Harness 插件）

简体中文 | English

SpecGraph 把一个项目的 PRD 与当前代码库转化为可追溯的实现 DAG：

PRD 需求 → 功能模块 → 实现任务 → 依赖关系 → 执行状态

核心设计原则：PRD 定义要构建什么（WHAT），当前代码库提供在哪里、如何构建的地面真相（WHERE / HOW）。

规划结束后依赖图仍然有效：编码过程中任务执行状态可随时更新，并自动在依赖图 UI 中反映。

1. 功能总览

结构化规划：PRD + 仓库扫描 → 需求 IR → 模块 → 任务 → 依赖边（DAG）
确定性图引擎：缺失节点 / 重复 / 自依赖 / 环检测、拓扑排序、关键路径（结构）、可并行任务识别——全部由确定性代码完成，从不交给 LLM
执行状态机：pending / ready / in_progress / blocked / completed / failed / skipped（ready 与 blocked 为派生状态，不落盘）
执行证据：变更文件、测试结果、commit、备注；完成传播自动使下游任务变为 ready
依赖图 UI：模块分组泳道、状态着色 + 符号 + 文字标签（颜色不是唯一指示）、节点详情面板、自动刷新
Mermaid 导出：.specgraph/graph.mmd（派生产物；结构化数据才是唯一事实源）
全局语言策略：所有人类可读输出默认简体中文；机器标识符、枚举值、schema 键永远保持英文

2. 安装

2.1 获取代码

git clone https://github.com/LastHopeOfGPNU/dsh-spec-graph.git specgraph
cd specgraph
npm install   # 无运行时依赖；仅用于本地测试

2.2 在 DeepSeek Harness 中启用

本项目自带两种 Harness 集成：

方式	说明
动态插件（本会话可用）	`tools/build-plugin.js` 生成 `dist/specgraph.host.js` 与 `dist/specgraph.client.js`，通过 Harness 的动态 Cordis 插件机制（`cordis_define` / `cordis_run`）注册。Host 半注册 `specgraph_*` 工具、`/specgraph` 斜杠命令与 UI RPC；Client 半在 `conversation.view` 槽位注册「SpecGraph」视图与运行卡片状态条。
CLI	`node src/cli.js <command>`，可独立于 Harness 使用。

动态插件 Host 半通过 Harness 的 shell 服务调用本项目的 CLI（node src/cli.js …），因此确定性引擎只有一份源代码（src/core/），由 96 个确定性测试覆盖；插件的语义规划循环（LLM 调用 + 提示词组装）在进程内完成。

提示：npm run build:plugin 重新生成 dist/；npm test 运行全部确定性测试。

3. 使用

3.1 Harness 工具（Harness-native 界面）

工具	作用
`specgraph_plan`	从 PRD + 代码库生成实现计划（仓库发现 → LLM 提取需求 → LLM 设计模块/任务/依赖 → 确定性 DAG 校验 + 最多 2 轮修复 → 持久化 + 渲染）
`specgraph_ingest`	导入结构化计划（YAML/JSON，无需 LLM；规划智能体已产出结构化数据时使用）
`specgraph_show`	实现进度概览
`specgraph_next`	当前可执行任务（确定性排序：关键路径 → 依赖深度 → 任务 ID；`one: true` 只取一个并返回完整任务契约）
`specgraph_status`	查询 / 更新任务状态（自动持久化证据、重算 ready/blocked、刷新渲染产物）
`specgraph_validate`	运行确定性 DAG 校验
`specgraph_graph`	导出 Mermaid 图
`specgraph_task` / `specgraph_module`	任务 / 模块详情
`specgraph_refresh`	重算派生状态并刷新渲染产物
`specgraph_config`	查看 / 修改项目配置（`set.language`）

3.2 斜杠命令

/specgraph next
/specgraph show
/specgraph status AUTH-001 in_progress
/specgraph status AUTH-001 completed
/specgraph graph
/specgraph validate
/specgraph plan PRD.md
/specgraph refresh

3.3 CLI

node src/cli.js plan <prd> [--data plan.yaml] [--emit-prompt]   # 规划
node src/cli.js ingest plan.yaml          # 导入结构化计划（stdin 用 -）
node src/cli.js show                      # 进度概览
node src/cli.js next [--one]              # 当前可执行任务
node src/cli.js status [任务] [新状态] [--evidence 文件] [--force]
node src/cli.js validate                  # 校验
node src/cli.js graph [--out 文件]        # Mermaid 导出
node src/cli.js task <id> | module <id>
node src/cli.js refresh                   # 重算派生状态
node src/cli.js config [--set language=zh-CN]
通用参数：--root <目录>  --lang <zh-CN|en|ja>

示例输出（默认简体中文）：

当前可执行任务：

AUTH-001  添加 OTP 服务  (MOD-AUTH)
DB-002    创建 Session 数据结构  (MOD-DB)

以上任务可并行执行。

4. 架构

┌────────────────────────── 动态 Cordis 插件 ──────────────────────────┐
│  Host 半（plugins/host.js，薄适配层）                                │
│    · specgraph_* 工具注册（harness.defineTool/registerTool）        │
│    · /specgraph 斜杠命令                                             │
│    · specgraph-state / specgraph-task RPC（UI 数据）                 │
│    · 语义规划循环：提示词组装 + llm.stream 调用（唯一 LLM 接触点）   │
│  Client 半（plugins/client.js + src/core/layout.js）                 │
│    · conversation.view「SpecGraph」依赖图视图（模块泳道、状态着色） │
│    · tool.view.cordis 运行卡片状态条（2.5s/6s 轮询 Host）            │
└──────────────────────────────────┬──────────────────────────────────┘
                                   │ shell 服务：node src/cli.js <cmd>
                                   ▼
┌────────────────────────── 确定性引擎（唯一事实源）───────────────────┐
│  src/core/   ids · status · graph · state · scheduler · yaml ·       │
│              i18n · mermaid · layout · store · repo-scan · planner · │
│              project · plan-render · report                          │
│  src/cli.js  命令行入口                                              │
│  src/ui-json.js  UI 快照 JSON（客户端渲染数据源）                    │
│  test/        96 个确定性测试（不依赖 LLM）                          │
└──────────────────────────────────────────────────────────────────────┘

4.1 职责边界（产品边界）

LLM             → 语义规划（需求提取、模块/任务/依赖设计、修复）
SpecGraph 运行时 → 图语义、校验、状态转移、持久化、
                  调度原语、UI 状态、渲染——全部确定性

5. 规划流水线

1.  PRD 摄入（路径 / 文本）
2.  需求提取（LLM，阶段 A）
3.  仓库/代码库发现（确定性：清单文件、入口点、框架、目录、测试）
4.  功能分解 + 模块边界 + 任务生成 + 依赖提取（LLM，阶段 B）
5.  DAG 校验（确定性；失败 → 携带错误信息回炉修复，最多 2 轮）
6.  持久化 + 实现计划渲染 + 依赖图渲染（确定性）

规划策略提示词位于 prompts/planner-policy.md，其策略源自 agency-agents 仓库中四个代理的 采纳/简化（prompts/reference/ 记录了取舍）： Senior Project Manager（需求提取、可追溯性、验收标准、范围控制）、 Software Architect（模块边界、依赖方向、以现有架构为证据）、 Master Plan Architect（文件清单、排序、风险、验证策略）、 Sprint Prioritizer（仅工程部分：依赖分析、关键路径、并行/阻塞；排除 RICE、Kano、速率等产品管理框架）。

6. 语言策略（全局）

默认语言：简体中文（zh-CN）。即便 PRD 与代码库都是英文且无任何配置，人类可读输出仍为简体中文。
解析优先级：

显式用户指令（--lang / language 参数）
        ↓
项目级配置（.specgraph/config.yaml 的 language: zh-CN|en|ja）
        ↓
SpecGraph 全局默认：zh-CN

机器面向内容永远英文稳定：需求/模块/任务 ID、YAML/JSON 字段名、枚举值（pending…skipped、hard…test、confirmed…out_of_scope）、API 名、CLI 命令名、文件路径、代码符号。
内部表示 → 本地化表示层：

TaskStatus.COMPLETED（内部）
        ↓ 渲染层
zh-CN → 已完成    en → Completed    ja → 完了

技术术语按需保留英文（DAG、API、CLI、runtime、migration、dependency……），以中文技术写作习惯组织。
UI 文本不散落硬编码：src/core/i18n.js 集中提供 zh-CN/en/ja 词典；客户端所有标签由 Host 下发。

7. 数据模型与持久化

项目内 .specgraph/ 目录：

文件	内容
`config.yaml`	项目配置（`version`、`language`、`planning`、`ui`）
`requirements.yaml`	需求 IR（机器可读）
`modules.yaml`	模块（职责、对应需求、现有代码、证据）
`tasks.yaml`	任务（实现步骤、涉及文件、验收标准、验证方案、`risks`、`open_questions`）
`graph.yaml`	依赖边（`from`/`to`/`type`/`reason`）
`execution.yaml`	运行时执行状态 + 证据 + 历史（增量更新，不重写规划图）
`derived.yaml`	派生状态快照（每次变更后重算）
`repo-scan.yaml`	代码库扫描结果（ground truth）
`implementation-plan.md`	人类可读实现计划（默认简体中文）
`graph.mmd`	Mermaid 渲染（派生产物）

语义规划数据 / 运行时执行状态 / 渲染产物严格分离；更新一个任务状态只写 execution.yaml 与派生产物。

7.1 需求状态

confirmed             PRD 直接支持
ambiguous             PRD 信息不足或冲突（明确暴露，尽力规划，不静默发明产品行为）
inferred_technical    实现显式需求所必需的技术前提（不得冒充 confirmed）
out_of_scope          明确排除 / 超出本期范围

7.2 任务状态与转移规则

pending → ready           所有门槛依赖（除 soft 外）已满足
ready → in_progress       开始实现
in_progress → completed   实现且验证通过（建议附带证据）
in_progress → failed      实现或必要验证失败
pending/ready → blocked   门槛依赖进入失败/跳过/阻塞状态（派生）
blocked → ready           阻塞解除（派生，自动）
pending/ready → skipped   按策略显式跳过
failed → in_progress      仅 force=true（管理覆盖）

ready / blocked 为派生状态：不可手动设置；单一事实源 = execution.yaml 中的持久化状态 + 图结构。
completed 无任何证据时仅给出警告（COMPLETED_WITHOUT_EVIDENCE），不硬性拒绝；鼓励提交测试、变更文件或 commit。

8. 依赖方向与类型

方向语义：from: A, to: B 表示 B 依赖 A，A 通常应先于 B 完成。此约定全局一致，绝不反转。

hard       目标在源完成前无法有意义地开工（门槛依赖）
soft       可部分先行，需要协调（不参与 ready 门槛）
api        目标消费源创建/修改的 API/接口
data       目标依赖源的数据结构 / schema / 持久化表示
runtime    运行时执行依赖
migration  目标依赖迁移 / schema 变更
build      目标依赖构建 / 配置 / 工具链工作
test       目标验证依赖源的测试基础设施 / fixture

9. 图校验

确定性校验覆盖：空计划、缺失节点、重复任务/模块/需求、无效 ID、自依赖、无效边类型、重复边、环检测、拓扑排序、阻塞任务、可执行任务、并行组、结构关键路径（无工期估计时为结构依赖路径，非时间排程）。

环不会被静默渲染为有效 DAG；校验失败会返回足够信息供规划层修复分解问题。

10. 执行证据契约（编码智能体集成）

编码智能体通过 specgraph_status 提交结果：

{
  "task_id": "AUTH-001",
  "new_status": "completed",
  "evidence": {
    "files_changed": ["app/services/auth.js"],
    "tests": [{ "name": "tests/auth.test.js", "result": "passed" }],
    "commit": "a1b2c3d4",
    "notes": "OTP TTL implemented using the existing ioredis client."
  }
}

编码循环：specgraph_next（拿到任务契约：需求上下文、模块上下文、实现步骤、涉及文件、验收标准、验证方案、依赖）→ 实现 → 验证 → 提交证据 → 状态更新 → SpecGraph 自动重算：完成传播使下游 pending → ready，UI 自动刷新。多智能体并行分支（DAG 的并行组）无需重新设计图模型。

11. 依赖图 UI

位置：会话视图导航中的「SpecGraph」视图（conversation.view 槽位）；cordis_run 卡片内另有状态条。
每个节点显示：任务 ID、标题、模块、状态（着色 + 符号 + 本地化文字标签，颜色不是唯一指示）。
模块泳道分组（不改变依赖语义，跨模块边正常绘制）。
点击节点 → 详情面板：描述、需求引用、实现步骤、涉及文件、验收标准、验证方案、上游/下游依赖、阻塞原因链、执行证据、时间戳。
2.5 秒轮询 Host 的 specgraph-state RPC，状态更新后自动反映。

状态语义：

pending     灰  ○   待执行
ready       蓝  ▶   可执行
in_progress 橙  ●   进行中
blocked     紫  ⛔   阻塞
completed   绿  ✓   已完成
failed      红  ✗   失败
skipped     浅灰 –   已跳过

12. 端到端示例

以一个英文 PRD + 英文仓库、无语言配置的项目为例：

PRD 需求：「Users can log in with a one-time SMS verification code.」（PRD §3.1）
生成需求（默认简体中文，机器键英文）：

id: REQ-001
title: 用户验证码登录
status: confirmed

生成任务：AUTH-001 添加 OTP 持久化服务、AUTH-002 添加登录 API、UI-LOGIN-001 添加登录界面
依赖：AUTH-001 → AUTH-002 → UI-LOGIN-001
初始状态：AUTH-001 ready（蓝）、其余 pending（灰）
编码开始：specgraph_status AUTH-001 in_progress → 节点变橙
验证通过：specgraph_status AUTH-001 completed（带证据）→ 节点变绿，AUTH-002 自动 ready（蓝）
全程无需 LLM 重算任何状态；.specgraph/ 中数据、计划文档、图渲染、UI 状态保持一致。

graph TD
    AUTH001["AUTH-001<br/>添加 OTP 持久化服务"]
    AUTH002["AUTH-002<br/>添加登录 API"]
    UILOGIN001["UI-LOGIN-001<br/>添加登录界面"]
    AUTH001 -->|hard| AUTH002
    AUTH002 -->|api| UILOGIN001

13. 项目生成的依赖图样例

下面是 SpecGraph 引擎逐字生成的 graph.mmd（即 specgraph_graph 工具 / node src/cli.js graph 的输出）。样例来自一个演示计划（4 个模块、7 个任务），展示了状态着色（completed 绿、in_progress 橙、ready 蓝、pending 灰）与多种依赖边类型（hard / soft / api / data）：

graph TD
    DB001["DB-001<br/>创建 OTP 数据模型"]
    DB002["DB-002<br/>创建 Session 存储"]
    AUTH001["AUTH-001<br/>添加 OTP 服务"]
    AUTH002["AUTH-002<br/>添加限流中间件"]
    API001["API-001<br/>添加登录 API"]
    API002["API-002<br/>添加登出 API"]
    UI001["UI-001<br/>添加登录界面"]
    classDef scompleted fill:#10b981,stroke:#059669,color:#ffffff
    classDef sinprogress fill:#f59e0b,stroke:#d97706,color:#ffffff
    classDef sready fill:#3b82f6,stroke:#2563eb,color:#ffffff
    classDef spending fill:#9ca3af,stroke:#6b7280,color:#ffffff
    class DB001 scompleted
    class DB002 sinprogress
    class AUTH001 sinprogress
    class AUTH002 sready
    class API001 spending
    class API002 spending
    class UI001 spending
    DB001 -->|hard| AUTH001
    DB001 -->|hard| AUTH002
    AUTH001 -->|soft| AUTH002
    AUTH001 -->|api| API001
    DB002 -->|data| API001
    DB002 -->|data| API002
    API001 -->|api| UI001

生成过程（全部由确定性引擎完成，无需 LLM）：

node src/cli.js ingest plan.yaml --root demo        # 导入结构化计划
node src/cli.js status DB-001 in_progress --root demo
node src/cli.js status DB-001 completed --root demo --evidence evidence.yaml
node src/cli.js status DB-002 in_progress --root demo
node src/cli.js status AUTH-001 in_progress --root demo
node src/cli.js graph --out graph.mmd --root demo   # 导出 Mermaid

classDef / class 行按图中出现的状态自动生成；soft 边不参与 ready 门槛（AUTH-002 在 AUTH-001 完成前已 ready）。
DB-001 完成后，AUTH-001、AUTH-002 自动变为 ready；图中所有状态均无需人工维护。

14. 测试

npm test（node test/run.js，进程内运行以兼容受限沙箱）运行 96 个确定性测试，覆盖：

图序列化/反序列化 · 依赖方向 · 缺失/重复节点 · 环检测 · 拓扑排序 · ready/blocked 计算 · 状态转移（合法/非法/强制）· 完成传播 · 失败依赖行为 · 并行识别 · next 选择 · 状态持久化 · 证据持久化 · Mermaid 生成 · UI 状态映射 · 语言解析优先级（Case A/B/C/D） · zh-CN 默认 · 显式覆盖 · 机器枚举稳定性 · YAML 往返 · 布局确定性 · 仓库发现 · 规划层归一化 · 第 46 节端到端流程。

图/状态测试不依赖 LLM；语义规划层与确定性图逻辑分开测试。

15. 已知边界与扩展点

非目标（MVP）：自主多智能体执行、Jira、速度追踪、RICE、审批工作流、强制 Git 集成、分布式图数据库。
扩展点：增量重规划（ID 稳定 + 图持久化已预留）、Git 元数据（证据中的 commit 字段）、多智能体并行分支（图/状态模型天然支持）、人工审批门槛（Harness 已有审批原语）。
本会话限制：动态插件为会话级（进程重启后需重新 cordis_run）；插件通过会话工作区内的 CLI 引擎工作，因此 SpecGraph 项目需位于当前会话工作区（root 参数仅能指向工作区内目录，与 DSH 文件沙箱策略一致）。

16. 目录结构

specgraph/
├── package.json            # npm test / build:plugin
├── README.md               # 本文档（默认简体中文）
├── README.en.md            # 英文文档
├── prompts/
│   ├── planner-policy.md   # 规划策略（LLM 系统提示词）
│   └── reference/          # agency-agents 采纳/舍弃笔记
├── src/
│   ├── core/               # 确定性引擎（图/状态/调度/YAML/i18n/…）
│   ├── adapters/io-node.js # Node fs 适配器
│   ├── ui-json.js          # UI 快照
│   ├── index.js            # Node 门面
│   └── cli.js              # CLI
├── plugins/
│   ├── host.js             # 动态插件 Host 半（薄适配层）
│   └── client.js           # 动态插件 Client 半（依赖图 UI）
├── tools/build-plugin.js   # 插件捆绑构建 + 自检
├── dist/                   # 生成的插件包（git 忽略）
└── test/                   # 96 个确定性测试