@godv61/dsh-task-engine

dsh plugin --profile web add @godv61/dsh-task-engine

<p align="center">

<img src="https://raw.githubusercontent.com/godv61/dsh-task-engine/main/.github/assets/readme-hero.svg" alt="DSH Task Engine：从项目知识到可验证交付" width="100%" />

</p>

<h1 align="center">DSH Task Engine</h1>

<p align="center">

为 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 提供按需求运行的工程化开发引擎。<br />

让项目知识、团队规范、测试证据和代码审核在每次开发中真正生效。

</p>

<p align="center">

<a href="https://www.npmjs.com/package/@godv61/dsh-task-engine"><img src="https://img.shields.io/npm/v/%40godv61%2Fdsh-task-engine?style=flat-square&amp;color=0d9488" alt="npm 版本" /></a>

<a href="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml"><img src="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml/badge.svg" alt="自动验证状态" /></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-334155?style=flat-square" alt="MIT License" /></a>

</p>

<p align="center">

<a href="#安装与检查">安装</a> ·

<a href="#首次初始化项目">项目初始化</a> ·

<a href="#执行一个开发任务">任务操作</a> ·

<a href="#按项目配置-sonarqube">SonarQube</a> ·

<a href="docs/manual.html">HTML 使用手册</a>

</p>

---

它解决什么问题

工程会话先区分交付目标：原因排查、调用链解释和方案评估使用只读分析契约；用户要求修改代码时才进入四档实施流程。项目初始化仍为可选。

分析任务使用 create intent=analysis intent_reason=...，主会话直接查证，使用 submit_analysis 提交结论、方案、未确认项及源码位置，由宿主采集原文与 hash，一次核验并归档。它不会为了完成流程创建测试文件、进入代码开发或触发 Sonar；运行时代码与命令写入工具受限。源码引用核验只能证明引用与内容一致，结论正确性仍须主会话检查。

新实施任务使用 intent=implementation。plan 可原子登记完整实施计划；默认留在主会话，只有明确委派收益时才由 auto 选择子代理。直接实施经真实验证后可用 accept_item 原子记录逐项审核与完成，原有阶段、测试、风险及 Sonar 门禁继续生效。

需要只读委派时，delegate 接收具体问题、引用入口、依赖和委派收益，默认最多两个同时运行。工作台分别展示运行、报告返回与证据采纳状态，并保留失败前的报告和观测到的成本数据；缺失数据标为未知。只读代理可以搜索与读文件，不能写入、执行命令或继续委派。recover_analysis 只有在原父会话通过宿主确认运行停止后恢复，资源清理不明时保持阻塞。

不带交付契约的旧台账继续按原快照执行，不自动转换进行中的任务。分析后要求实施时新建关联任务，保留原始调查证据。

插件 0.40.1 支持 DSH 0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5，使用 rc.5 构建和验证。旧宿主 0.2.0-rc.2 继续固定插件 0.34.1。

本次宿主升级的具体影响、验证结果和限制见 [rc.5 适配记录](docs/testing/dsh-rc5-compatibility.md)。

0.40.1 修复文件范围校验、异常台账展示与验证组恢复，见[版本说明](docs/releases/0.40.1.md)。0.40.0 的任务材料与台账面板介绍见[上一版说明](docs/releases/0.40.0.md)。新任务使用 .dsh/tasks/<任务标识>/，不自动扫描或迁移旧目录记录。可选的[产品确认清单 Skill 示例](examples/skills/product-clarification/SKILL.md)供自行安装挂载，不会自动成为内置技能。

一个项目会有许多需求、分支和会话。团队需要复用编码约定，但不同需求不该被迫走完全相同的步骤。

常见问题 · Task Engine 的做法

大模型反复询问项目结构、版本和编码习惯 · 初始化项目地图、技术栈与开发 Skill；Rule 保存团队约束。

小改动流程太重，大改动又缺少分析与拆解 · 按每项需求评估复杂度，选择低、中、高、超高四档路径。

会话说“测试通过”，实际没有执行测试 · dev_task 保存命令和回执；常见测试运行器必须证明至少执行一个测试。

审核问题散落在聊天记录里 · 任务台账展示阶段、实施项、测试与审核；可选 Sonar 报告落到项目目录。

项目配置是团队知识，流程选择属于当前需求。 同一项目的普通会话不会自动进入工程流程；不同工程任务也可以选择不同档次。

项目初始化                        每个新需求                            交付
结构地图 · 技术栈 · Skill/Rule  →  复杂度评估 → 阶段执行 → 测试 → 代码审核 → 完成
              │                       │                     │
              └── 项目级知识复用 ──────┘                     └── 台账与证据

安装与检查

插件必须安装到实际启动的 DSH profile。以下以 Web profile web 为例：

dsh plugin --profile web add @godv61/dsh-task-engine

如果从 DSH 源码运行，在 DSH 根目录执行：

pnpm dsh plugin --profile web add @godv61/dsh-task-engine
pnpm dsh web --no-open

安装后关闭旧的 DSH Web 或桌面进程，再以同一个 profile 启动。打开页面，检查侧边栏是否出现工程任务，以及新会话的模式菜单是否能选择工程化开发引擎。只在普通项目目录执行 npm install 不会把插件挂进 DSH profile；若没有入口，先核对安装和启动使用的是不是同一个 profile，再看启动日志。

在 Windows 桌面版中，工程任务工作台会自动避开系统标题栏和窗口控件；浏览器版则使用完整页面空间。若升级后仍看到标题与窗口菜单重叠，先确认运行进程已加载新插件并重启 DSH。

首次初始化项目

初始化过程中可切换工程任务的其他菜单或暂时关闭工作台；服务端生成作业继续运行，刷新或关闭浏览器不会取消它。后台作业仅保存在 DSH 进程内存中，不创建项目 .dsh/init-jobs/ 或本机磁盘缓存。已结束结果最多保留 30 分钟，总共最多 100 条，超量时优先淘汰已结束记录。DSH 重启会清空后台作业，不能续接未完成输出；浏览器已经保存的草案和提示词编辑仍可恢复，尚未取回的结果需要重新生成。旧版已有作业文件仅兼容读取。切换工作区在扫描、索引或生成期间会暂时禁用。若某个可选 Skill 证据不足或反复生成失败，可点击跳过当前候选，继续其余步骤；最后仍须审阅草案并点击确认写入项目。

1. 在工程任务顶部选择代码库根目录作为工作区，并确认当前 Git 分支。

2. 打开项目初始化 → 项目 Skill 初始化（可选）。页面先只读扫描项目，列出候选 Skill、已有资源和扫描范围。“通用规则与单项生成模板”保存共用约束和简短概况；各步骤有独立的入口与证据提示词。初始路径清单只是建议查阅入口，不代表模型已经读取。模型通过受限只读工具按需列目录、搜索和读取实际文件；完成后显示读取记录及可选 CodeGraph 查询记录。模板中的 {{target}}、{{previous}}、{{meta_skills}}、{{limit}} 按步骤填入。CodeGraph 可选：点击安装 CodeGraph 并建立索引或更新项目索引。安装按钮会在运行 DSH 的机器上执行全局 npm 安装；已有 CLI 时只在当前项目建立或增量更新索引。没有 CodeGraph 也可继续。

3. 通过步骤选项直接切换查看和编辑，切换不会跳过候选或改变完成进度；提示词编辑按步骤保留。点击生成下一项逐项审阅，或点击连续生成全部。内置六个元技能已承担通用阶段工作；项目地图、技术栈、业务能力、后端/前端 Skill 均为可选补充，全部跳过也能运行。初始化不凭构建依赖自动生成编码 Rule。每次作业只生成一个资源；格式错误会自动重试，仍失败时保留已完成草案并显示原因，检查后可继续。刷新后恢复当前作业及已完成草案；点击从头开始可清除浏览器草案。此阶段保存临时作业记录，不写入正式 Skill 或项目流程配置。

4. 逐项检查草稿正文、简介、元技能挂载及 Rule 关联。可直接修改或移除不合适的建议；修改后点击检查修改。

5. 检查通过后点击确认写入项目。若提案包含项目地图，工作台会核对全仓覆盖；同时检查同名文件和配置版本，只写入刚审阅的提案。若项目配置或文件已变化，重新生成或检查。不要把某一条需求的实现方案当成整个项目的结构地图。

阶段 · 会发生什么 · 重点检查

生成下一项 / 连续生成全部 · 每项按需读取与该 Skill 对应的证据；服务端保存作业结果，浏览器保存草案 · 区分建议入口与实际读取记录；可切换步骤查看，跳过重复或证据不足的建议。

检查修改 · 校验 Skill、Rule、挂载关系和同名冲突；生成了项目地图时检查全仓覆盖 · 项目知识是否可跨需求复用；约束是否有明确来源。

确认写入项目 · 按同一提案哈希写入文件 · 已有同名资源不会被静默覆盖。

内置元技能负责各阶段的通用步骤和交接契约，不要求在每个项目再生成六份同名 Skill。若项目已有 <项目名>-<元技能名> 文件，初始化会保留原文件并自动挂载；团队确有特殊阶段方法时，也可之后手动创建和挂载。

初始化不强制生成项目 Skill 或 Rule。<项目名>-project-map 是可选的全仓知识补充，可挂到需求分析、架构设计、任务编排和代码开发；技术栈与后端/前端编码 Skill 也按证据选做。如果生成项目地图，它应描述整个仓库的模块职责、依赖和通用入口；当前需求的页面、接口、验收条件应放进任务产物。Rule 不按语言预设：团队明确规范或真实、可复用的审核失败案例确认后，再建立具体 Rule 并挂到相关 Skill。页面中的 AGENTS.md 初始化是另一项操作。

初始化不会被动安装 CodeGraph。使用者明确点击索引按钮后，插件才会安装缺失的 CLI 并在所选项目执行 codegraph init --yes；已有索引执行 codegraph sync。项目地图的专属证据会读取 CodeGraph 的目录结构和有限的可信符号线索；图谱查询超时或不可用时继续使用目录与源码证据。低置信度的符号匹配会被排除，不能仅凭图谱推断业务含义、调用关系或团队规范。索引位于项目 .codegraph/，是否提交应遵守团队仓库策略。OpenSpec 不是初始化前置条件，也没有被插件自动安装。

初始化提示词会要求新 Skill 生成简短的 whenToUse，说明适用任务或修改范围；草案中的“使用时机”可审阅和修改，确认写入后保存在 SKILL.md 头部。该字段会随生成、草案恢复、预览及写入保留，供按需加载判断。旧草案没有此字段仍可使用并参考描述；不会自动覆盖已经生成或人工维护的 Skill。初始化新增的项目挂载默认按需，已有挂载保留原方式，核心 Skill 始终强制；写入后可在“项目流程与审核”调整。使用时机内容本身不决定挂载方式。

初始化还会建议一个可选的 <项目名>-business-capabilities Skill：仅当仓库提供页面、路由、接口、测试或业务文档等证据时，才生成可复用的业务能力说明。每项能力应列出代码路径，并区分已确认事实、代码推导和待业务确认；不能凭类名猜功能。它可挂载到需求分析和架构设计元技能。没有足够证据时从提案中删除即可。

项目地图负责模块职责、依赖、启动/构建

…(truncated)