dsh-task-engine

DSH Task Engine

为 DeepSeek Harness 提供按需求运行的工程化开发引擎。
让项目知识、团队规范、测试证据和代码审核在每次开发中真正生效。

安装 · 项目初始化 · 任务操作 · SonarQube · HTML 使用手册

---

它解决什么问题

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

分析任务使用 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 适配记录。

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

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

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

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

团队共享前，审阅 .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 指令的自动完成校验仍未包含在内。

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

{"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。示例路径、行号和命令须替换为实际项目内容。

只查原因、给方案：

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

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

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

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

局部代码修改：

{"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 对应技能后，先整理精简需求并取得用户对当前文档版本的确认：

{"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 登记包含实现和必要测试的完整单元，再声明测试组：

{"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 审核或人工审批。

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

请在当前项目实现“设备授权范围”需求。先读取已有项目 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 使用手册：适合下载后分享给团队使用者，覆盖安装、初始化、任务、Sonar 与排障。
• 开发指南：插件架构、构建、测试和发布前检查。
• 反馈问题 · MIT License

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