# @godv61/dsh-task-engine 中文文档

规范地址：https://npmcn.com/package/%40godv61/dsh-task-engine/

版本：0\.41\.1
npm 元数据更新时间：2026-11-16T09:28:13.491Z
中文译文更新时间：2026-11-16T18:05:19.305Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40godv61/dsh-task-engine
原文对照：https://npmcn.com/package/%40godv61/dsh-task-engine/?lang=original
项目主页：https://github.com/godv61/dsh-task-engine#readme
源码仓库：https://github.com/godv61/dsh-task-engine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.3 MB，265 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.2，@deepseek-ai/dsh-llm 0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3，@deepseek-ai/dsh-scope 0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3，@deepseek-ai/dsh-tools 0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3，@deepseek-ai/dsh-session 0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3，@deepseek-ai/dsh-typert-protocol 0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3
- 首次发布：2026-09-08T07:53:34.521Z
- 最新版本发布：2026-11-16T09:28:13.318Z
- 近 30 天下载量：4760（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

任务范围工程工作流程为DeepSeek Harness:四个复杂等级,可选项目Skill初始化,可核实测试,以及审查时间SonarQube检查.

## 安装

```sh
npm install @godv61/dsh-task-engine
```

也可以使用：`pnpm add @godv61/dsh-task-engine`、`yarn add @godv61/dsh-task-engine`、`bun add @godv61/dsh-task-engine`

## README

![DSH Task Engine：从项目知识到可验证交付](https://raw.githubusercontent.com/godv61/dsh-task-engine/main/.github/assets/readme-hero.svg)

# DSH Task Engine

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供按需求运行的工程化开发引擎。  
让项目知识、团队规范、测试证据和代码审核在每次开发中真正生效。

[![npm 版本](https://img.shields.io/npm/v/%40godv61%2Fdsh-task-engine?style=flat-square&color=0d9488)](https://www.npmjs.com/package/@godv61/dsh-task-engine) [![自动验证状态](https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml/badge.svg)](https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml) [![MIT License](https://img.shields.io/badge/license-MIT-334155?style=flat-square)](https://npmcn.com/package/%40godv61/dsh-task-engine/LICENSE)

[安装](https://npmcn.com/package/%40godv61/dsh-task-engine/#readme-%E5%AE%89%E8%A3%85%E4%B8%8E%E6%A3%80%E6%9F%A5) · [项目初始化](https://npmcn.com/package/%40godv61/dsh-task-engine/#readme-%E9%A6%96%E6%AC%A1%E5%88%9D%E5%A7%8B%E5%8C%96%E9%A1%B9%E7%9B%AE) · [任务操作](https://npmcn.com/package/%40godv61/dsh-task-engine/#readme-%E6%89%A7%E8%A1%8C%E4%B8%80%E4%B8%AA%E5%BC%80%E5%8F%91%E4%BB%BB%E5%8A%A1) · [SonarQube](https://npmcn.com/package/%40godv61/dsh-task-engine/#readme-%E6%8C%89%E9%A1%B9%E7%9B%AE%E9%85%8D%E7%BD%AE-sonarqube) · [HTML 使用手册](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/manual.html)

* * *

## 它解决什么问题

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

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

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

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

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

> 插件 `0.41.1` 支持 DSH `0.2.2-rc.3`，保留 `0.2.2-rc.1` 和 `0.2.1-rc.3`、`rc.4`、`rc.5`。新宿主使用 Node.js `>=24.9.0`；旧宿主仍验证 Node 22。旧宿主 `0.2.0-rc.2` 继续固定插件 `0.34.1`。

`0.41.1` 修复新宿主的托管子代理调用契约，见[版本说明](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/releases/0.41.1.md)和 [rc.3 适配验收](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/testing/dsh-rc223-compatibility.md)。只升级桌面程序、仍保留插件 `0.41.0` 时不会获得此修复。

`0.41.0` 同时修复提交或 amend 后的 Sonar 审核基线、零文件误报通过和委派入口一致性，见[版本说明](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/releases/0.41.0.md)。兼容性验证结果和验收边界见 [0.2.2-rc.1 适配记录](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/testing/dsh-rc22-compatibility.md)。

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

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

| 常见问题 | Task Engine 的做法 |
| --- | --- |
| 大模型反复询问项目结构、版本和编码习惯 | 初始化项目地图、技术栈与开发 Skill；Rule 保存团队约束。 |
| 小改动流程太重，大改动又缺少分析与拆解 | 按**每项需求**评估复杂度，选择低、中、高、超高四档路径。 |
| 会话说“测试通过”，实际没有执行测试 | `dev_task` 保存命令和回执；常见测试运行器必须证明至少执行一个测试。 |
| 审核问题散落在聊天记录里 | 任务台账展示阶段、实施项、测试与审核；可选 Sonar 报告落到项目目录。 |

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

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

## 安装与检查

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

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

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

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

项目地图负责模块职责、依赖、启动/构建入口及代码导航，业务能力负责业务角色、流程和业务规则。当本轮已有项目地图草案时，业务能力生成会参考其完整正文来定位和避免重复，仍须独立读取源码核实；相同模块名称和证据路径可以引用，目录全表和启动说明不重复展开。没有地图时，业务能力仍可独立生成。内置生成和外部提示词复制使用同一套草案上下文，不以机械的文本重复率删减内容。

团队共享前，审阅 `.dsh/skills/`、`.dsh/rules/` 和 `.dsh/meta.json`，再提交到 Git。Token 与本地审核报告不应提交。

## 元技能、Skill 和 Rule

内置元技能覆盖**需求分析、架构设计、任务编排、代码开发、测试、代码审核**。元技能约定本阶段做什么、交给下一阶段什么；项目 Skill 说明如何在当前仓库做；Rule 描述更具体的约束、触发条件与适用范围。

| 内容 | 何时准备 | 示例 |
| --- | --- | --- |
| 六个元技能的通用方法、阶段顺序与交接契约 | 插件内置，所有项目直接使用 | 需求分析区分事实与推断；代码开发按验收条件实现；测试记录实际执行结果 |
| 跨项目可复用的团队方法 | 使用者确认后作为用户级 Skill，按需挂载 | 统一的需求访谈方法、团队通用的代码审核清单 |
| 仓库知识与特有实现方式 | 扫描具体项目后，审阅证据并选择是否生成项目 Skill | 项目地图、技术栈、业务能力、特有的后端或前端入口 |
| 可执行的项目约束 | 有明确团队规范或真实、可复用的审核失败案例后创建 Rule | 某接口字段校验方式、该仓库的异常处理约定 |
| 某次需求的结论 | 每个任务单独记录为产物，不写进项目 Skill | PRD、实现步骤、改动范围、验收与审核记录 |

已有代码中的某种写法只说明它存在，不自动证明它是规范。SonarQube 的规则保持在项目质量配置和审核阶段；无需在初始化时复制成大量 Rule。只有反复出现、确认有效且能写清正确示例的问题，才适合沉淀为项目 Rule。

安装包只内置这些通用核心 Skill，**不内置 Java 或某团队的业务 Rule**。项目 Rule 由使用者依据明确团队规范或真实审核案例建立，避免把别的项目的规范强加到当前仓库。

项目 Skill 可以放在 `.dsh/skills/`，工作台也能发现 `.agents/skills/` 中的 Codex 项目技能。用户级 Skill 可跨项目复用；**同名 Skill 的优先级是项目级 > 用户级 > 内置**。项目同名版本使用自己的 Rule 列表，不会自动混入被覆盖版本的 Rule。

在**工程任务 → 项目流程与审核**给元技能挂载 Skill，在对应 Skill 的 `profile.json` 中配置 Rule；项目挂载保存在 `.dsh/meta.json`。Rule 跟随 Skill 生效，不会因为挂在某一阶段就随意叠加给其他 Skill。已创建任务冻结阶段图和资源引用；被引用的 Skill/Rule 正文下次读取会更新，删除强制挂载正在引用的资源会阻止流转。

每条挂载关系可选择**强制加载**或**按需加载**，同一个 Skill 在不同阶段可选不同方式；当前阶段的核心 Skill 始终强制。强制项须有真实读取记录，并满足其完成凭证要求；按需项只展示名称、描述和 `whenToUse`，由模型结合需求范围选择，未读取或未提供 Skill 完成凭证不会阻塞。选中 Skill 时仍一并提供其全部 Rule，必须始终遵守的团队约束应挂在强制 Skill 下。旧名称数组默认强制，不自动放宽已有配置；保存后的方式只影响新任务。

同一任务、同一会话已经成功加载的 Skill 和 Rule 可以跨阶段复用，后续阶段或再次 `load_skill` 默认仅返回复用提示。`load_skill detail=true` 可显式恢复全文。读取复用不代替各阶段的产物、命令凭证、测试或审核；独立子代理仍须获得自己的必要上下文，按需正文不会被自动塞入子代理提示。

例如，附加 Skill 可保存为 `"project-map"`（旧格式，强制），或 `{"name":"frontend-guide","loading":"on-demand"}`。加载方式属于阶段挂载，不写入 Skill 的 `profile.json`；`profile.json` 继续保存该 Skill 自己的 Rule 和完成凭证类型。

例如后端写法反复被代码审核判定为问题：先确认规则适用范围和正确写法，在**工程任务 → 规则**创建项目 Rule；再到**项目流程与审核 → 代码开发 → 核心 Skill `code-development` → 配置 Rule**选择它，并在抽屉中保存。核心 Skill 的 Rule 配置会保存为同名项目 Skill 的档案，之后创建的任务使用该项目配置。一次性的误报或尚未确认的意见不应沉淀为 Rule。

配置时先在左侧选择元技能；右侧显示核心 Skill 与已挂载 Skill。用搜索框查找要挂载的 Skill，点该 Skill 旁的**配置 Rule**会立即打开右侧抽屉，可按名称、来源或“已选”筛选规则。**保存项目流程与审核设置**把 Skill 挂载和 Sonar 开关、地址、项目 Key 等写入 `.dsh/meta.json`，只影响新建任务；Rule 抽屉单独保存对应 Skill 的规则档案。**重新读取已保存设置**从该文件和 Skill/Rule 目录重载页面，未保存的页面修改需确认丢弃；没有修改时保存按钮置灰。

**“完成凭证”中的“未单独设置”是什么意思？** 保存时不在该 Skill 的 `profile.json` 写入 `evidence` 字段；不是沿用旧版配置。新建自适应任务时，同名核心 Skill 使用元技能的默认值：需求分析、架构设计、任务编排为**产物内容**，代码审核为**审核结果**，代码开发和测试为**无需凭证**；额外挂载的项目 Skill 默认为**无需凭证**。页面会在选项中显示该 Skill 当前的实际默认值。需要更严格的单独验收时，可显式选择命令执行记录、产物内容、审核结果或人工确认。**无需凭证**只表示该 Skill 不另收一份完成证明；仍须加载 Skill、遵守其 Rule，并通过阶段自身的产物、测试和审核门禁。完成凭证与 SonarQube 服务器规则是两套独立配置。

## 四档流程与交接

| 档次 | 典型需求 | 默认阶段顺序 |
| --- | --- | --- |
| **低 · low** | 边界明确的局部修改 | 代码开发 → 测试 → 代码审核 → 完成 |
| **中 · medium** | 常规功能或缺陷修复 | 需求分析 → 代码开发 → 测试 → 代码审核 → 完成 |
| **高 · high** | 跨模块且有实现先后依赖 | 需求分析 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成 |
| **超高 · ultra** | 完整新模块或大范围重构 | 需求分析 → 架构设计 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成 |

需求分析交付目标、范围、非目标和可验证的验收条件；架构设计交付边界、影响与取舍；任务编排交付按实现先后排列的实施项 ID、依赖和交接产物；开发交付文件与逐项审查；测试交付真实命令；代码审核交付结论和可选 Sonar 报告。**实施项体现推进顺序，不是按人数分派工作。** 风险等级由模型另外判断，不等同复杂度。

新建显式 `intent=implementation` 的自适应任务执行“澄清 → 需求总结 → 用户确认 → 实施”。关键疑问通过 `clarify_requirement` 收集真实用户答复，`record requirement` 整理当前阶段字段，`prepare_requirement` 从同份内容生成 `.dsh/tasks/<任务编号>/requirement.md`（可用 `document_path` 指定普通 Markdown 路径），`confirm_requirement expected_hash` 展示该版本全文并询问用户。台账显示文档、版本、确认状态和修改意见。低档仍保持原阶段数，先在初始阶段给精简总结；中/高/超高档整理目标、范围、非目标、业务规则、异常、验收和依赖。明确需求可直接整理，不重复访谈；含糊需求不能归为低档跳过澄清。

用户确认前只允许查阅、澄清和整理需求，业务写入、项目命令和实施委派会被限制；自动执行权限不代表业务确认。问题未答、用户要求修改或审阅期间版本变化均不放行。范围或验收变化须 `revise revision_kind=requirement` 修订后重新确认；文档的人工修改受保护，不会静默覆盖。用户明确接受的待联调事项可写入总结后确认，不要求所有外部依赖已就绪。文档可按项目约定随任务提交，由需求版本门禁单独核对，不自动加入业务测试文件范围。重复确认同一有效版本会复用原回执；文档恢复为已确认的原始内容后，工具展示与执行权限会同步恢复。

确认前的原生写文件工具和终端仍受限制，需求总结由 `prepare_requirement` 写入。挂载 Skill 可用 `write_requirement_material` 生成 HTML、Markdown、JSON、TXT、CSV、SVG 等文本材料，统一保存在 `.dsh/tasks/<任务编号>/materials/`，台账记录路径、版本和指纹；单份最多 1 MiB，每任务最多登记 64 份。生成材料、填写表单或导出答复都不自动批准需求。材料变更或丢失会阻止确认与业务写入，Git 钩子也核对有效材料；修改需求字段及材料后重新生成总结并请用户确认。

直接写正文与 HTML 模板渲染共用入口。模板必须是当前节点已绑定且本任务／会话实际加载的 Skill 的 `assets/` HTML 文件；插件仅替换指定的 `application/json` 数据区，不运行脚本，不把模板全文重复注入模型。可用 `identity_field` 把内容相关的材料标识填入模板数据字段，隔离改题前后的表单缓存。已有未登记文件或人工修改不会被覆盖；修改未确认的已生成材料须提供当前 `expected_hash`。旧稿不再作为本期依据时，用 `retire_requirement_material`、`material_name` 与当前指纹停用登记，文件及历史元信息保留。多角色签署、任意 Skill 指令的自动完成校验仍未包含在内。

```json
{"operation":"write_requirement_material","task_id":"FIX-1","material_name":"product/questions.md","material_content":"# 待产品确认\n驳回后是否保留填写内容？"}
```

```json
{"operation":"write_requirement_material","task_id":"FIX-1","material_name":"product/checklist-v1.html","material_template":{"skill_name":"user:product-clarification","path":"assets/confirmation-checklist-v1.html","data_id":"card-data","identity_field":"task_id","json":"{\"engine_task_id\":\"FIX-1\",\"revision\":\"v1\",\"title\":\"产品确认 v1\",\"questions\":[{\"kind\":\"逻辑遗漏\",\"question\":\"驳回后是否保留填写内容？\",\"evidence\":\"需求未描述驳回结果\",\"need\":\"请确定驳回后的业务结果\"}]}"}}
```

实施任务统一使用新版需求确认：`create` 必须明确 `intent`、`complexity` 和相应理由，没有兼容模式或关闭开关，漏传参数也不能退回旧流程。缺少新版需求确认结构的未完成任务仅可查看，继续工作需使用新的 `task_id` 重新创建；已有代码和历史台账不自动修改，也不迁移旧确认。已归档记录继续只读展示。普通分析任务仍只交付原因与方案。

\*\*当前 CodeGraph 的插件调用范围是项目索引准备与初始化证据。\*\*任务阶段尚无自动图谱查询接口；若代理能调用已安装的 CodeGraph CLI，可按需辅助查找调用方与影响范围，并以源码复核。没有索引时直接读源码。六个内置元技能不依赖 OpenSpec；团队如已有经批准的外部规格，可把其路径和编号记入对应任务产物。`dev_task` 仍是阶段、实施项、测试及审核的唯一台账，不会自动安装或同步 OpenSpec。

阶段提示和默认 `status` 只返回绑定索引、指纹、进度与回执摘要；通过 `load_skill` 一次取得 Skill 及其全部挂载 Rule 正文。需要完整计划、产物或命令日志时请求 `status detail=true`，无需重新跑验证。子代理与独立审核各自收到完整的适用约束。Sonar 阻断或审核过期时按返回的 `recovery` 先退回实施；缺陷返工可保留计划及输入指纹均匹配的最新通过回执，受影响项的审核仍须重新接受。较新的失败、代码/测试输入变化、计划变化及指令变化不能复用旧通过记录；需求/方案变化与未知影响仍完整失效。

## 执行一个开发任务

### 两个最小调用示例

以下是代理调用 `dev_task` 的参数示例，使用者通常直接用自然语言提出需求。新契约的 `create` 必须带 `task_id`、`title`、`intent`、`intent_reason`；实施任务还必须带已评估的 `complexity` 和 `complexity_reason`。`branch` 可省略，宿主会读取 Git；后续针对单个任务的调用每次都携带 `task_id`。示例路径、行号和命令须替换为实际项目内容。

**只查原因、给方案：**

```json
{"operation":"create","task_id":"TRACE-1","title":"定位产品型号丢失的原因","intent":"analysis","intent_reason":"用户只要求原因和方案，本轮不改代码"}
```

读取相关源码后直接提交，不需要登记实施项、运行测试或进入代码审核：

```json
{"operation":"submit_analysis","task_id":"TRACE-1","conclusion":"转换时遗漏了已有字段","proposal":"在转换入口保留字段，并验证下游映射","limitations":["仅核对静态源码，尚未验证运行数据"],"source_evidence":[{"file":"src/adapter.js","start_line":20,"end_line":28}]}
```

宿主始终保存完整行段及文件/行段指纹；可选 `quote` 只作高亮，不会替代整段源码。成功提交后分析任务归档。

**局部代码修改：**

```json
{"operation":"create","task_id":"FIX-1","title":"修复字段转换并增加回归测试","intent":"implementation","intent_reason":"用户要求实现修复及测试","complexity":"low","complexity_reason":"边界明确的单模块修复","files":["src/adapter.js","test/adapter.test.js"]}
```

读取 `status.bindings` 对应技能后，先整理精简需求并取得用户对当前文档版本的确认：

```json
{"operation":"record","task_id":"FIX-1","artifact":"requirement","fields":{"goal":"保留既有字段","scope":"修改转换并补充回归测试","acceptance":"字段值保持一致，缺失值处理不回归"}}
{"operation":"prepare_requirement","task_id":"FIX-1"}
{"operation":"confirm_requirement","task_id":"FIX-1","expected_hash":"填写上一调用返回的 requirement.hash"}
```

确认由宿主向真实用户询问，模型不能自行设置同意。通过后用 `plan` 登记包含实现和必要测试的完整单元，再声明测试组：

```json
{"operation":"plan","task_id":"FIX-1","plans":[{"id":"I1","title":"保留字段并验证转换结果","files":["src/adapter.js","test/adapter.test.js"],"acceptance":["转换前后的字段值一致，回归覆盖缺失值分支"],"task_boundary":"local","execution_reason":"共享一个局部实现与测试上下文，主会话完成"}]}
{"operation":"plan_verification","task_id":"FIX-1","verification_group":"unit","command":"npm test","files":["src/adapter.js","test/adapter.test.js"],"item_ids":["I1"]}
```

完成修改后运行 `verify`，主会话核对验收和代码，再用 `accept_item` 记录逐项结论；按 `status.legal_next`、技能和项目提交条件完成后续阶段及归档。这些示例不跳过真实测试、适用的 Sonar 审核或人工审批。

在项目工作区新建**工程化开发引擎**会话，可以直接这样提出需求：

```text
请在当前项目实现“设备授权范围”需求。先读取已有项目 Skill/Rule，
评估需求复杂度并明确验收条件。需要任务编排时，按实现先后列出
实施项、依赖和交接产物；开发、真实测试和代码审核按任务台账推进。
只在当前分支工作，不要推送。
```

随后按台账和 `dev_task` 的门禁推进：

1.  **确认任务归属。** 先用 `status` 查看工作区和分支是否已有任务；新需求用 `assess` 预览档次和技能，再用 `create` 创建。发现已有任务时核对任务 ID，避免把需求写进别的任务。 新任务 ID 限 1–64 位 ASCII 字母、数字、连字符或下划线，首位为字母或数字，以避免不同 ID 写到同一个文件。
2.  **记录阶段产物。** 每阶段查看 `status` 给出的 Skill、Rule、必填产物及阻塞原因；用 `record` 写入当前阶段允许的内容，用 `advance` 进入下一阶段。不要手工改任务 JSON 跳过门禁。
3.  **按顺序实施。** 高、超高任务先在计划中列稳定实施项 ID，再用 `items` 登记。`items` 默认按 ID 增量合并；例如只补 I5 不会删掉 I1–I4。确需重排或移除未开始的项目，显式使用 `items_mode=replace` 并提供完整列表；实施中、已完成或已有审查记录的项仍受保护。
4.  **记录实现与逐项审查。** 新 `intent=implementation` 契约的直接实施使用真实 `verify` 后的 `accept_item`，无需额外 `dispatch`、`review_item` 和 `items`；委派实现仍通过 `dispatch`。旧契约继续使用 `dispatch`、`review_item` 和 `items done`。把所有变更文件登记到任务 `files` 范围；代码变动会使旧测试和审核回执失效。 `dispatch` 按计划使用 `direct`（主会话）、`spawn`（独立上下文）或 `fork`（宿主允许的已完成会话历史）。委派按顺序执行，保存真实运行 ID 和输出，主代理仍须验证、逐项审查并将该项设为 `done`。中断或释放失败时先确认宿主运行及其后代停止，再由原父会话执行 `recover_dispatch`；无法确认状态时保持锁定。 自适应任务用 `plan` 或 `plan_execution` 记录每项边界、文件范围、验收、依赖与选择理由。新交付契约默认主会话实施，只有明确 `delegation_benefit`（并行、上下文隔离或独立核对收益）才自动委派；独立文件本身不触发子代理。委派默认独立上下文，确需已完成会话历史时才选择继承历史。无需在普通需求里提示“使用子代理”。宿主能力不足时记录回退原因；明确指定不可用方式则报错。用户要求全程主会话时创建任务传 `execution_policy=main_only`。 新交付契约仅高风险项在宿主能力允许时要求 `review_dispatch` 独立只读审核；旧契约保留委派实现或高复杂度也需独立审核的策略。审核工作仅能读文件，核对模型实际收到的行内容是否覆盖当前计划文件，缺页或截断不能通过。结论绑定本项文件、实施轮次及审核上下文。支持原生结构化输出的 DSH 会通过专用结果工具提交结论，缺少有效提交时不接受文本自报。临时启动失败不消耗有效审核轮次；重审先退回实施中。所有交付文件及对应测试必须归属到实施项；主会话执行也须有当前真实测试与逐项审核才可 done。台账显示计划方式、实际方式、选择原因、审核方式与两个运行 ID；历史路径读取记录会明确标为未核对全文。
5.  **验证与审核。** `verify` 执行真实命令；进入代码审核后，若启用 Sonar，调用 `sonar_check` 并处理结果，再记录 `review`。门禁通过后按 `status.commit` 提示提交并完成任务。

**测试回执的要求：** 退出码为 0 只是必要条件。Maven Surefire/Failsafe、Node TAP/Jest/Vitest、pytest、Python 标准库 unittest、Go test、Cargo test 的常见输出，以及本次 Gradle `test` 执行新生成的 JUnit XML，必须证明至少执行一个实际通过的测试；全部跳过、没有可识别证据，或仅运行 `true`、编译命令时不能算通过。验证命令不能通过串联、管道、重定向或命令替换掩盖失败。项目使用其他运行器时，先用能输出受支持摘要的测试命令；记录未覆盖项，不能用文字自报通过。unittest 可用 `python -m unittest discover -s tests -v`，要求完整最终摘要，跳过和预期失败不计为通过。Go 使用 `go test -json ./...`；包级 `ok/pass`、全跳过和无测试包不能冒充测试用例通过。多包运行允许部分包无测试，只要至少有实际通过的测试且没有失败。旧 Go 文本回执须重新验证。Maven 项目的建议命令为 `mvn -B test`，Gradle 项目默认使用 wrapper 的 `test --rerun-tasks`。升级前保存的验证回执若缺少当前要求的测试证据或文件指纹，需重新运行 `verify`。

如需对 `git commit` 启用同一任务门禁，在工程会话调用 `dev_task install_hook`，再调用 `verify_hook`。安装器会登记当前工作区（包括 Git 仓库的子目录）；已有其他团队的 `commit-msg` 或设置了 `core.hooksPath` 时会停止并提示人工组合，更新已有 DSH 钩子前会备份。钩子配置保存在该 Git 工作树的 `.git/hooks/`，不随 Git 提交。提交时钩子要求当前分支能唯一对应一项未完成任务，并核对真实验证回执、任务文件范围与暂存区内容。测试后改过文件、暂存了不同版本，或旧任务只有手写的 `passed=true` 而没有回执时，需要重新运行 `verify`。任务状态仍是工作区内可编辑的 JSON，门禁用来防止误操作和遗漏，**不提供对恶意修改任务文件的防篡改保证**。

删除文件、变更文件类型或触及敏感路径时，提交门禁要求任务为 `high_risk` 且有有效验证回执。多会话并行时，建议每个任务使用独立分支或工作区，避免其他任务的未提交文件混入本次范围和审核。

计划删除或重命名时，在实施前给 `plan_execution` 传 `changes`，例如 `[{"path":"src/old.ts","kind":"delete"}]` 或 `[{"path":"src/old.ts","kind":"rename","to":"src/new.ts"}]`。旧路径和重命名目标都保留在任务与实施项的 `files`。引擎从 Git 捕获旧内容，并另存已有未提交内容的快照；独立审核须读完快照和现有交付文件。缺少受支持的 Git 文本基线时会明确阻塞，不能通过移除旧路径来绕过审核。

发现风险上升时调用 `set_risk high_risk`：按任务冻结的实际流程检查门禁，重新决定逐项审核方式，清除旧接受并重新打开已完成项；若已进入后续阶段，会返回代码开发。未变化的实现和真实测试回执保留，仍须按新策略审核。降级继续需要人工批准。登记提交可传 Git 能唯一解析到当前 HEAD 的短 SHA，台账保存完整 OID；已有短 SHA 记录在重新执行 CI/上传式 `sonar_check` 时先由本地 Git 核验与规范化，服务端分析必须匹配完整提交标识。

初始化会在限定范围内递归发现嵌套构建清单，默认最多列出 1024 个目录、20000 个条目，深度最多 16 层。这是目录发现预算，不是要求模型阅读的文档数。达到预算或部分目录不可读取时，已有证据仍可生成草案；生成的地图会注明发现未完成，已知路径的遗漏仍须补充说明，职责不明的部分标为待确认。没有模块或清单证据时，仍不能通过项目地图校验。

单项 Skill 的模型生成预算默认 **10 分钟**，页面可选 5、10、20、30 分钟；时间包含查阅、模型思考、正文生成与重试，重试不会获得一份新的完整预算。后台作业和浏览器轮询分别额外留出 30 秒和 60 秒的收尾空间。初始化继承 DSH 当前默认模型及其已选思考等级；没有明确选择等级时遵循供应商默认值。不再在固定 110 秒后提前收尾，查阅轮数、工具量及正文长度的保护仍保留。JSON 格式、正文长度及已知路径校验失败时，在原查阅上下文中修复一次；网络中断、限流等可重试错误最多重新尝试一次，新尝试必须重新取得文件证据。超时后可重试当前步骤，其他已完成草案保留。页面“本轮累计已耗时”包含连续生成的多个步骤，不是单次模型调用的时长。

大型项目的查阅和模型思考可能耗时较长。可以使用 **复制当前项提示词（外部生成）**，将当前编辑的要求交给能访问项目源码的编码助手自行生成；普通网页模型需要另行提供相关文件，项目路径本身不代表它能访问。复制内容会展开当前项与模板占位符，并将插件专用工具名换成当前环境的通用查阅要求。生成内容仍须审阅，可以通过“技能”页新建，或整理为 `SKILL.md` 后安装并按需挂载；不要求先完成内置初始化。

重新生成已有草案时，页面会明确显示目标资源以及“取消重新生成 / 确认重新生成”按钮；确认前不发起新的生成请求。仅在获得有效新草案后替换该项内容，失败或未生成有效内容时保留原草案，其他资源保持原有内容。

## 按项目配置 SonarQube

**不需要 Sonar：** 保持“项目流程与审核”中的 Sonar 开关关闭，不必填地址、Key 或 Token；代码审核元技能和项目 Rule 仍会运行。

**需要 Sonar：** 在工作台顶部选对项目，进入**项目流程与审核 → SonarQube 审核**，依次填写：

| 字段 | 填写方式 |
| --- | --- |
| 服务地址 | SonarQube 根地址，如 `https://sonar.example.com`，不带项目页面路径。 |
| 项目 Key | 当前代码库在 SonarQube 中的项目标识，不同项目可以不同。 |
| Git 参考版本 | 高级设置，默认 `HEAD`，审核当前尚未提交的变更；也可填本机已有的分支或提交。 |
| 审核路径 | 高级设置，留空审核本次任务全部代码；项目只需审核后端时填写对应的相对目录。 |
| Token | 先保存服务地址与项目 Key，再在同一页面单独保存到本机 DSH 凭据存储；绑定当前工作区、地址和 Key，只显示“已配置”。 |

Sonar 的非秘密配置保存在项目 `.dsh/meta.json`；Token **不会写入该文件、任务或报告**。换项目，或更改当前项目的服务地址/项目 Key 后，需要为新的连接重新保存 Token。旧版只按工作区保存的 Token 不会自动迁移，升级后需在页面重新输入一次。若使用环境变量，须同时设置 `DSH_SONAR_TRUSTED_HOST` 和 `DSH_SONAR_TRUSTED_PROJECT_KEY` 与当前连接完全一致；不要把通用 Token 交给仓库配置中的任意地址。内部 HTTP Sonar 服务仍可填写，但网络传输没有 TLS 保护，建议由管理员确认网络边界。项目的 Quality Profile 和规则本身仍由 SonarQube 服务器管理。

保存配置和 Token 后，可点击**准备本地 Sonar 检查**。首次在运行 DSH 的机器上下载官方 SonarLint 后台及配套 Java（约 93 MiB），校验后放入 `DSH_HOME/sonarlint-runtime/`；已安装时复用。随后按项目 Key 连接 SonarQube，检查当前项目的语言分析器和 Quality Profile。页面优先显示项目最近一次服务端分析涉及的语言；若没有分析记录，则显示所有可继承的语言配置。此按钮不审核或上传项目代码；未预先点击时，首次代码审核也会自动准备。

服务器修改了当前项目的 Quality Profile 或规则参数后，点击**重新同步本项目 Sonar 规则**。插件为这个项目建立新的本地绑定，重新同步服务器配置；只有本地同步成功，后续审核才切换到新绑定。页面显示上次手动更新时间；更新失败时继续使用上一次成功的绑定。这个操作不扫描或上传代码，也不计算服务端 Quality Gate。每个项目分别更新。

点击**查看本项目 Sonar 规则**可按语言查看对应 Quality Profile 的名称、启用规则总数、规则编号与名称，搜索规则并跳转到 SonarQube 规则详情。默认只显示项目最近一次分析涉及的语言，需要时可展开其它语言配置。此列表来自服务器当前配置；数量核对只证明规则清单读取完整，不能证明每条规则都可在本地执行。**Quality Profile** 决定启用哪些规则；**Quality Gate** 是服务端分析结果的通过条件，提交前本地检查不计算完整 Quality Gate。

### 提交前审核如何运行

测试通过并进入代码审核阶段后，代码审核元技能会调用 `dev_task sonar_check`。默认以 `HEAD` 为基线，读取当前任务尚未提交的 Git 变更，并按 SonarQube 项目的 Quality Profile 分析变更行；**无需提交或推送，也无需在页面手动发起**。首次运行会下载并校验官方 SonarLint 后台组件，缓存在 `DSH_HOME/sonarlint-runtime/`（未设置 `DSH_HOME` 时为 `~/.dsh/sonarlint-runtime/`）；后台从 SonarQube 同步当前项目的语言分析器与规则。安装与同步要求这台机器能访问 Maven Central 和 SonarQube；网络或权限失败时审核会明确报错，不会静默通过。通常无需安装 IDEA、Maven、SonarScanner 或单独配置 JDK。JS/TS/Vue/CSS 分析仍可能需要可用的 Node.js。

首次下载约 93 MiB，网络较慢时会等待较久。如果运行 DSH 的机器访问 Maven Central 必须走代理，在启动 DSH 前设置 `DSH_SONARLINT_PROXY=http://127.0.0.1:7897`（替换为实际代理地址），或使用标准 `HTTPS_PROXY` 环境变量；重启 DSH 后生效。这是安装组件的网络设置，不会写入项目配置。若已手工准备后台组件，仍可用 `DSH_SONARLINT_JAVA` 与 `DSH_SONARLINT_LIB` 指向现有安装。

项目仅审核后端时，可在高级设置的“审核路径”填写实际后端目录，例如 Maven 模块。审核前会核对这些目录的 Git 变更是否全部登记在任务 `files`；漏登会报出文件名。范围外的前端或 SQL 不会被称为已通过本次后端审核。报告会列出项目生效规则数量、分析器状态和未覆盖文件；未覆盖的相关语言会阻断审核。

本地审核只能运行 SonarLint 支持的服务端规则，**通过不等于 SonarQube 服务端 Quality Gate 通过**。涉及全项目数据流、跨文件上下文或仅在服务端实现的规则，仍以团队的 CI 扫描结果为准。旧任务原有的 CI/上传式扫描配置仍可读取，但新项目页面只提供提交前审核。

已有上传式扫描配置若使用 `.dsh/meta.json` 的 `sonar.scan_command`，当前只接受单独的 `sonar-scanner`，或固定 Maven Sonar 目标 `org.sonarsource.scanner.maven:sonar-maven-plugin:5.5.0.6356:sonar`（可附 `-DskipTests`、`-Dmaven.test.skip=true`）。不再接受 shell 串联、自定义 Maven 目标或把 Token 写进命令；升级后配置不通过校验时请改为上述形式，Token 仍通过项目凭据传入。

### 查看审核、处理误报、沉淀 Rule

代码审核元技能自动调用 `dev_task sonar_check`。在**任务台账**展开最近一次审核，可查看原始结果、规则、严重程度、文件位置、分析器状态、人工复核状态和未解决数量。每次扫描在项目 `.dsh/tasks/<任务 ID>/reviews/` 生成 Markdown 报告；最近一次结构化结果写入 `.dsh/tasks/<任务 ID>/task.json`，历次完整结果另存于 `.dsh/tasks/<任务 ID>/reviews/` 中的 JSON 详情文件；主台账仅保留历史索引。

-   **真实问题：** 修复代码，重新测试并复扫。真实、已修复且可复用的案例，可以通过 `learn_rule phase=propose → apply` 预览并沉淀为项目 Rule，供之后创建的任务使用。
-   **疑似本地规则误报：** 用 `sonar_disposition` 指定本次报告的 `issue_key`，提供具体理由与源码证据，由人逐条批准。原始告警仍保留；未批准、证据不足、代码变化或重新扫描后都不能沿用处置。已确认误报不会自动转成 Rule。
-   **自定义规则不准确：** 将问题、代码语义和证据反馈给 SonarQube 规则维护者；不要为消除告警而破坏业务实现。

## 任务台账与项目文件

每个任务使用一个目录 `.dsh/tasks/<id>/`：`task.json` 是唯一状态来源，`requirement.md` 保存需求总结，`materials/` 保存确认材料，`reviews/` 保存逐次审核报告。按需创建产物，不预建空目录。项目级配置、Skill 和 Rule 仍属于整个项目。业务代码及业务测试保留在原来的源码、测试目录。

台账采用左侧任务列表、右侧详情的工作台。可分别阅读概览、需求与方案、实施计划、登记文件、验证与审核，也可切换“文档阅读”连续查阅，或下载 Markdown 阅读副本。导出不写回任务状态，也不产生新的需求批准。登记文件与测试输入分开显示，登记范围不等于实际 Git 变更；阶段条仅标记当前阶段，不推断之前的阶段均已完成。

“待开始”表示实施项还未执行；“实施中”表示已记录开始；“待审查”表示缺少该项的规格或质量审查；“代码审核”则是整个任务的后续阶段。它们不是团队成员分派状态。任务完成后调用 dev\_task complete 即归档并变为只读；同一会话后续出现新需求或上线后的修复时，新建任务 ID。可用 related\_task\_id 和 relation\_kind 关联已归档任务；归属不清时先让使用者选择。台账默认显示进行中与待归档任务，可切换查看已归档记录。

| 位置 | 内容 | 团队共享建议 |
| --- | --- | --- |
| `.dsh/meta.json` | 项目元技能挂载及 Sonar 非秘密配置 | 审阅后提交 |
| `.dsh/skills/`、`.dsh/rules/` | 项目 Skill、Rule 与 Skill 的 `profile.json` | 审阅后提交 |
| `.dsh/tasks/<id>/task.json` | 任务阶段、实施项、测试和审核回执 | 按团队留痕策略决定 |
| `.dsh/tasks/<id>/requirement.md` | 需求总结及本版确认依据 | 可随任务提交 |
| `.dsh/tasks/<id>/materials/` | 产品、技术待确认材料等 | 按材料共享范围决定 |
| `.dsh/tasks/<id>/reviews/` | 逐次 Sonar 报告与误报处置 | 可加入 `.gitignore` 留在本机 |
| 本机 DSH 凭据存储 | 按工作区隔离的 Sonar Token | 不提交、不分享 |

## 常见问题

安装后看不到“工程任务”或“工程化开发引擎”？

核对插件是否装在正在运行的 Web profile，关闭旧 Web 进程后重启，查看启动日志。普通预设与工程化预设加载的工具不同。

项目初始化在哪里操作？

在工程任务的“项目初始化”页查看候选资源与当前步骤专属证据，点击“生成下一项”或“连续生成全部”，逐项审阅后点击“检查修改”与“确认写入项目”。页面使用默认模型；若提示模型未配置，先到“模型”页选择默认模型。工程化会话仍可按需使用 `dev_task init_project` 的 `inspect → propose → apply` 调用。项目根目录的 AGENTS.md 生成功能是独立操作。

为什么 Maven 构建成功，任务仍不能前进？

插件要求验证命令输出证明至少运行一个测试。检查测试运行器是否实际发现用例、是否跳过测试，以及输出中是否有可识别摘要；重新运行有测试结果的命令。

为什么 Sonar 报了业务上必须创建的对象？

自定义规则可能过宽。保留告警并核对代码语义；本地规则分析可以逐条提交理由和证据由人批准，服务端规则应由维护者修正。不要复用本该独立的实体或挪动代码来隐藏告警。

为什么审核提示补文件范围？已有任务会随配置改变吗？

本次扫描路径内的 Git 变更若未登记到任务 `files`，需补入当前任务范围，或把其他任务移到独立分支/工作区。已有任务的阶段图和资源引用在创建时冻结；Skill/Rule 正文下次读取会更新，代码、范围或规则变化后应重新检查证据。

## 文档与参与

新任务按完整实施项交付代码和对应测试，通过 `plan_verification` 声明前端、后端等必要测试组的命令、输入文件与所属实施项，再用 `verify verification_group=...` 分别取得回执。全部必要组有效才可通过任务验证；同组最新失败不会被历史通过覆盖。输入包括相关测试、构建配置和依赖项，覆盖充分性仍由审核核对。

`create`、`scope`、实施计划和验证组中的 `files` 都须逐个填写具体普通文件，不能填写目录或通配符；尚未创建的文件可提前登记。路径后来变成目录、链接或无法读取时，台账保留任务并显示错误路径及所属验证组，`status.file_scope_problems` 提供同样的诊断。使用 `scope`、`plan_execution` 或 `plan_verification` 修正对应清单；多个坏组可逐个修正，旧回执保留但不能据此放行。只读测试配置沿用验证输入策略；交付范围拒绝敏感路径和任务台账自身。不会通过忽略目录来宣称测试有效。

同一轮缺陷返工可用 `revise revision_kind=defect affected_items=[...]` 指定影响范围；共享输入和下游依赖会扩大失效范围。未受影响的回执和逐项审核保留，任务级审核与 Sonar 重新核对。影响未知时省略范围，完整返工；需求和方案变更仍完整失效。缺少新版需求确认结构的活动任务仅可查看，需新建任务继续；历史回执保留，归档任务继续只读。

开发阶段内也可用 defect 修订重新打开已审核项。`plan_execution.files` 是交付范围，`plan_verification.files` 还包括只读取的配置和依赖；共同配置未修改时不必登记为共同交付。`verify` 返回 `group_result` 表示本组结果，`task_verified` 和兼容字段 `ok` 表示任务整体结果，本组通过时可以先逐项验收。

-   [HTML 使用手册](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/manual.html)：适合下载后分享给团队使用者，覆盖安装、初始化、任务、Sonar 与排障。
-   [开发指南](https://npmcn.com/package/%40godv61/dsh-task-engine/docs/development.md)：插件架构、构建、测试和发布前检查。
-   [反馈问题](https://github.com/godv61/dsh-task-engine/issues) · [MIT License](https://npmcn.com/package/%40godv61/dsh-task-engine/LICENSE)

DSH Task Engine · 让项目知识进入开发，让每次交付留下证据。

## 常见问题

### @godv61/dsh-task-engine 是什么？

任务范围工程工作流程为DeepSeek Harness:四个复杂等级,可选项目Skill初始化,可核实测试,以及审查时间SonarQube检查\.

### 如何安装 @godv61/dsh-task-engine？

在项目目录运行 npm install @godv61/dsh-task-engine，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.2）、@deepseek-ai/dsh-llm（0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3）、@deepseek-ai/dsh-scope（0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3）、@deepseek-ai/dsh-tools（0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3）、@deepseek-ai/dsh-session（0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3）、@deepseek-ai/dsh-typert-protocol（0\.2\.1-rc\.3 \|\| 0\.2\.1-rc\.4 \|\| 0\.2\.1-rc\.5 \|\| 0\.2\.2-rc\.1 \|\| 0\.2\.2-rc\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 dsh-task-engine-enable，可以用 npx dsh-task-engine-enable 直接运行。

### @godv61/dsh-task-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @godv61/dsh-task-engine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @godv61/dsh-task-engine 可以商用吗？

@godv61/dsh-task-engine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @godv61/dsh-task-engine 的下载量有多少？

根据 npm 官方下载统计，@godv61/dsh-task-engine 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,760 次，日均约 159 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @godv61/dsh-task-engine 还在维护吗？

最新版本 0\.41\.1 发布于 2026/11/16（今天）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/09/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

