dsh-task-engine

DSH Task Engine

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

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

它解决什么问题

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

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

项目初始化                        每个新需求                            交付
结构地图 · 技术栈 · 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。

首次初始化项目

1. 在工程任务顶部选择代码库根目录作为工作区，并确认当前 Git 分支。
2. 打开项目初始化 → 项目 Skill 初始化（可选）。页面先只读扫描项目，列出候选 Skill、已有资源和扫描范围。“通用规则与单项生成模板”默认收起，只保存所有步骤共用的约束和简短项目概况；当前步骤的专属证据单独显示在下方，可检查来源文件并编辑。项目地图步骤读取整个仓库的模块清单；若已有 CodeGraph 索引，还会读取其目录与可信符号线索。后端、前端等步骤分别取对应文件，不把全仓源码反复塞给每个 Skill。模板中的 {{target}}、{{previous}}、{{meta_skills}}、{{limit}} 会按步骤填入。CodeGraph 可选：点击安装 CodeGraph 并建立索引或更新项目索引。安装按钮会在运行 DSH 的机器上执行全局 npm 安装；已有 CLI 时只在当前项目建立或增量更新索引。没有 CodeGraph 也可继续。
3. 可以修改通用提示词、单项模板及当前步骤证据，再点击生成下一项逐项审阅；也可以点击连续生成全部。内置六个元技能已承担通用阶段工作；项目地图、技术栈、业务能力、后端/前端 Skill 均是按证据生成的可选补充，全部跳过也能运行。初始化不凭构建依赖自动生成编码 Rule。项目地图和技术栈可挂到架构设计与代码开发等元技能，让通用执行方法读取当前项目事实；已有的专属阶段 Skill 会继续保留并挂载。每次模型调用只要求一个资源。连续生成遇到单项模型格式错误会自动重试；如果仍失败，会停在该项并显示原因，已完成草案保存在当前浏览器。检查证据后点击继续连续生成即可从失败处接着运行。刷新页面也会恢复草案；升级前的旧草案在已完成步骤和资源仍匹配时也会恢复。切换项目或修改通用提示词会启动新的草案。点击从头开始可清除当前草案。此阶段不写入正式项目配置。
4. 逐项检查草稿正文、简介、元技能挂载及 Rule 关联。可直接修改或移除不合适的建议；修改后点击检查修改。
5. 检查通过后点击确认写入项目。若提案包含项目地图，工作台会核对全仓覆盖；同时检查同名文件和配置版本，只写入刚审阅的提案。若项目配置或文件已变化，重新生成或检查。不要把某一条需求的实现方案当成整个项目的结构地图。

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

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

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

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

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

元技能、Skill 和 Rule

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

已有代码中的某种写法只说明它存在，不自动证明它是规范。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 正文下次读取会更新，删除正在引用的资源会阻止流转。

例如后端写法反复被代码审核判定为问题：先确认规则适用范围和正确写法，在工程任务 → 规则创建项目 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 服务器规则是两套独立配置。

四档流程与交接

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

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

执行一个开发任务

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

请在当前项目实现“设备授权范围”需求。先读取已有项目 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. 记录实现与逐项审查。 用 dispatch 和 review_item 留痕。开发者可以在当前会话直接实施，不要求把任务派给其他人。把所有变更文件登记到任务 files 范围；代码变动会使旧测试和审核回执失效。
5. 验证与审核。 verify 执行真实命令；进入代码审核后，若启用 Sonar，调用 sonar_check 并处理结果，再记录 review。门禁通过后按 status.commit 提示提交并完成任务。

测试回执的要求： 退出码为 0 只是必要条件。Maven Surefire/Failsafe、Node TAP/Jest/Vitest、pytest、Go test、Cargo test 的常见输出，以及本次 Gradle test 执行新生成的 JUnit XML，必须证明至少执行一个实际通过的测试；全部跳过、没有可识别证据，或仅运行 true、编译命令时不能算通过。验证命令不能通过串联、管道、重定向或命令替换掩盖失败。项目使用其他运行器时，先用能输出受支持摘要的测试命令；记录未覆盖项，不能用文字自报通过。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 且有有效验证回执。多会话并行时，建议每个任务使用独立分支或工作区，避免其他任务的未提交文件混入本次范围和审核。

按项目配置 SonarQube

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

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

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/reviews/<任务 ID>/ 生成 Markdown 报告；最近一次结构化结果写入 .dsh/task-<任务 ID>.json，历次完整结果另存于 .dsh/reviews/<任务 ID>/ 中的 JSON 详情文件；主台账仅保留历史索引。

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

任务台账与项目文件

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

常见问题

文档与参与

• HTML 使用手册：适合下载后分享给团队使用者，覆盖安装、初始化、任务、Sonar 与排障。
• 开发指南：插件架构、构建、测试和发布前检查。
• 反馈问题 · MIT License

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