DSH Task Engine

先理解工作方式

一个项目可以有很多会话和任务。项目配置保存团队通用的 Skill、Rule 与可选 SonarQube 连接；每个新任务由模型根据需求复杂度选择一条流程，创建时冻结阶段顺序。项目配置不会把普通会话或该项目的所有任务强制放进同一流程。

元技能负责本阶段要做什么、交给下一阶段什么；项目 Skill 说明如何在该项目做；Rule 给出具体约束。任务台账保存实施项、验证回执与审核记录。模型可以执行工作，但阶段和质量门禁由 dev_task 检查。

安装与检查

插件必须安装到你实际启动的 DSH 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

1. 关闭已有的 DSH Web 或桌面进程，再用相同 profile 启动，避免旧进程继续加载旧包。
2. 侧边栏找到工程任务；新建会话能选工程化开发引擎。
3. 在工作台顶部选择项目工作区。项目路径应是代码库根目录；先确认当前 Git 分支。

只在某个目录执行 npm install 不会把插件挂进 DSH profile。没有入口时先核对安装和启动的 profile，再查看启动日志。Windows 桌面版的工作台会避开标题栏菜单与窗口按钮；浏览器版使用完整页面空间。升级后如仍出现顶部重叠，请重启正在运行的 DSH 进程。

首次初始化项目

打开“工程任务 → 项目初始化”，选择项目根目录。页面先只读扫描目录与构建清单，显示候选 Skill 和已有资源。六个内置元技能已经负责需求分析、架构设计、任务编排、代码开发、测试和审核的基础方法；初始化不强制生成项目 Skill 或 Rule。项目地图、技术栈、业务能力、领域编码 Skill 均按仓库证据选做，不会为六个阶段机械生成同名 Skill，也不会凭语言或依赖自动生成编码 Rule。已有阶段 Skill 保留并继续挂载。通用规则与单项生成模板默认收起；当前步骤的专属证据单独列出来源文件和可编辑提示词。项目地图步骤使用整个仓库的模块清单和可选的 CodeGraph 索引；其它候选步骤只读取相应的有限源码。模板中的 {{target}}、{{previous}}、{{meta_skills}}、{{limit}} 按步骤填入。可选：点击“安装 CodeGraph 并建立索引”或“更新项目索引”。使用者可修改当前步骤提示词，再点击生成下一项，审阅并修改后继续；也可点击连续生成全部。每一步模型只生成一个资源，格式错误会自动重试；持续失败时停在当前步骤并保留已完成草案，检查提示词后点击继续连续生成。刷新后也可在当前浏览器恢复；点击“从头开始”可清除草案。全部生成后检查正文、简介和元技能挂载；编辑或移除建议后点击检查修改，最后点击确认写入项目。

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

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

页面被动加载不会安装 CodeGraph。使用者明确点击索引按钮后，缺少 CLI 时插件会在运行 DSH 的机器上执行全局 npm 安装，然后在所选项目执行 codegraph init --yes；已有索引执行 codegraph sync。索引位于项目 .codegraph/。项目地图步骤会读取图谱状态、目录结构和可信符号线索；低置信度匹配会被排除，不能仅凭图谱推断业务含义、调用关系或团队规则。CodeGraph 和 OpenSpec 都不是初始化前置条件；插件不会自动安装 OpenSpec。

提案还会建议可选的 <项目名>-business-capabilities Skill。只有页面、路由、接口、测试或业务文档能支持业务能力描述时才保留；每项能力应给出证据路径，并分别标注代码事实、合理推导和待业务确认。它可挂载到需求分析和架构设计，供后续需求复用。

团队共享时，审阅后将 .dsh/skills/、.dsh/rules/、.dsh/meta.json 纳入 Git。Token 和本地审核报告不应随代码提交。

Skill 与 Rule 如何生效

内置核心 Skill 对应需求分析、架构设计、任务编排、代码开发、测试和代码审核。你可以给这些元技能挂载项目 Skill，并在 Skill 的 profile.json 配置 Rule。项目 Skill 可来自 .dsh/skills/，工作台也能发现 .agents/skills/ 中的 Codex 项目技能；用户级资源可跨项目复用。

已有代码的写法不能自动证明是团队规范。SonarQube 的规则保留在项目质量配置和审核阶段，无需在初始化时复制成大量 Rule；只有确认有效且可复用的问题才适合沉淀。

同名 Skill 的优先级：项目级优先于用户级，用户级优先于插件内置。项目同名版本使用自己的 Rule 列表，不把低优先级版本的 Rule 自动混进来。Rule 挂在 Skill 下，不是给某个阶段随意叠加；同一个 Skill 被不同元技能使用时遵守同一组 Rule。

项目挂载保存在 .dsh/meta.json；工作台“项目流程与审核”可完成配置。左侧选择元技能，右侧查看核心与已挂载 Skill；可以搜索要挂载的 Skill。点击 Skill 旁的“配置 Rule”会打开右侧抽屉，可按名称、来源或已选状态筛选规则。页面底部的“保存项目流程与审核设置”将 Skill 挂载和可选 Sonar 设置写入 .dsh/meta.json，只影响新建任务；Rule 抽屉单独保存 Skill 的规则档案。“重新读取已保存设置”会重新加载项目配置和 Skill/Rule 列表，未保存的页面修改需先确认丢弃。编辑正文后，下一次加载读取最新文件，但已创建任务仍按创建时的阶段图和资源引用运行。删除正在引用的 Skill/Rule 会阻止流转。

例如某种后端写法反复导致代码审核失败：确认适用范围和正确写法，在“规则”页创建项目 Rule，再到“项目流程与审核 → 代码开发 → 核心 Skill code-development → 配置 Rule”选择并保存。核心 Skill 的 Rule 配置会保存为同名项目 Skill 的档案，之后创建的任务使用该配置。误报或未确认意见不应沉淀为 Rule。

完成凭证的“未单独设置”：保存时不在 Skill 的 profile.json 写入 evidence，并非沿用旧版配置。新建自适应任务时，需求分析、架构设计、任务编排核心 Skill 默认检查产物；代码审核核心 Skill 默认检查审核结果；代码开发、测试核心 Skill 和额外挂载的项目 Skill 默认“无需凭证”。弹出的选项会显示这个 Skill 的实际默认值。可以显式改为命令执行记录、产物内容、审核结果或人工确认。“无需凭证”只免除该 Skill 的单独完成证明，仍须加载 Skill、遵守 Rule，并通过阶段自身的产物、测试和审核门禁。它不改变 SonarQube 规则。

项目 Rule 应有明确触发条件、适用边界和正确示例。Sonar 审核失败后，只有真实、已修复、可复用的案例才适合用 learn_rule propose → apply 写入项目 Rule；误报不应被教给下一次开发。

四档流程与阶段交接

需求分析交付目标、范围、非目标和可验证的验收条件；架构设计交付边界、影响与取舍；任务编排交付按实现先后排列的实施项 ID、依赖和交接产物；代码开发交付变更文件及逐项规格/质量审查；测试交付真实命令与覆盖说明；代码审核交付结论及可选 Sonar 报告。实施项是推进顺序，不是给团队成员派活。风险等级与复杂度独立判断。

目前插件调用 CodeGraph 的位置是索引准备与项目地图生成；任务阶段没有自动图谱查询接口。若代理能调用已安装的 CodeGraph CLI，可按需辅助定位调用方和影响范围，并以源码复核；不可用时直接读源码。内置元技能不依赖 OpenSpec；团队已有经批准的外部规格时，可在任务产物中记录其路径和编号。dev_task 仍保存任务台账、阶段产物和测试，不自动安装或同步外部规格工具。

执行一个任务

1. 新会话使用“工程化开发引擎”预设并描述需求。先调用 dev_task status 查当前工作区和分支是否已有任务；新需求用 assess 预览复杂度和技能，再用 create 创建任务。
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_check（若启用 Sonar），处理问题后记录 review。通过门禁后按 status.commit 的提示提交并完成任务。

给会话的第一条需求示例

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

会话应先展示复杂度依据和任务状态。若发现已有任务，先核对任务 ID 与分支，避免把这条需求写进其他任务。你可以随时在“任务台账”查看它记录的实施项和下一门禁。

一个任务只负责其记录的分支、文件范围和流程。多会话并行时应给不同任务使用独立分支或工作区，避免另一任务的未提交代码混进本次审核。

需要拦截直接执行的 git commit 时，在工程会话调用 dev_task install_hook 和 verify_hook。安装器登记当前 Git 工作区；仓库子目录也能定位任务。已有其它 commit-msg 钩子时安装会停止，需人工组合；更新已有 DSH 钩子前会备份。提交时钩子要求当前分支唯一对应一个未完成任务，并核对真实验证回执、任务范围和暂存内容。测试后改动代码、暂存不同版本，或旧任务只有 passed=true 而无回执时，应重新运行 verify。任务 JSON 可以由拥有工作区写权限的人修改，因此门禁用于防止遗漏和误操作，不是防恶意篡改机制。

测试和证据

dev_task verify 保存命令、退出码、标准输出、标准错误和文件范围指纹。退出码 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。旧回执缺少当前要求的测试证据或文件指纹时需重新验证。

构建、单元测试、接口、数据库、页面和消息验证覆盖不同风险。缺测试账号或独立数据库时，应在交接中写清未覆盖场景，不能把编译或静态检查当成业务验收。真实命令在 DSH 会话沙箱中执行；权限被拒绝时按宿主审批提示处理，不要反复换命令绕过。

按项目配置 SonarQube

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

需要 Sonar：先在工作台顶部选对项目，再开启 Sonar，填写并保存服务地址和项目 Key。项目 Key 在 Sonar 项目设置中查；Token 在 Sonar 个人安全设置生成，需能读取该项目的规则。Token 在同页单独保存到本机 DSH 凭据存储，绑定当前工作区、服务地址和项目 Key，只显示“已配置”，不会写入 .dsh/meta.json 或审核报告。换项目、地址或 Key 时需重新保存 Token；旧版只按工作区保存的 Token 升级后需重新输入。内部 HTTP 服务可用，但传输没有 TLS 保护，应核对网络边界。

保存项目配置和 Token 后，可点击准备本地 Sonar 检查。首次在运行 DSH 的机器上下载官方 SonarLint 后台组件及配套 Java（约 93 MiB），校验后保存在本机 DSH 缓存；已有组件则复用。随后按当前项目 Key 连接 SonarQube，检查语言分析器和生效的 Quality Profile。此时不会审核或上传项目代码；未预先点击时，首次代码审核也会自动准备。

SonarQube 服务器更改了此项目的规则或参数后，点击重新同步本项目 Sonar 规则。插件重新建立此项目的本地绑定并同步规则；成功后显示手动更新时间，后续代码审核使用新绑定。更新失败则继续使用此前成功的配置。更新不会扫描或上传代码，也不计算服务端 Quality Gate；其它项目不受影响。

点击查看本项目 Sonar 规则，可按语言查看 Quality Profile 名称和启用规则清单，按编号、名称或严重性搜索，并打开 SonarQube 规则详情。默认只显示最近一次分析涉及的语言，也可展开其它语言配置。规则清单与本地分析器状态是两种信息：SYNCED 表示该语言分析器可用，不能证明清单中的每条规则都能在本地执行。Quality Profile 决定启用规则；Quality Gate 根据服务端扫描结果判断是否通过，提交前本地检查不计算完整 Quality Gate。

提交前审核如何运行

测试通过并进入代码审核阶段后，代码审核元技能自动调用 dev_task sonar_check。默认以 HEAD 为基线，分析任务中尚未提交的 Git 变更行；无需提交、推送或在页面手动发起。首次审核会下载并校验官方 SonarLint 后台组件，保存在 DSH_HOME/sonarlint-runtime/（未设置时为 ~/.dsh/sonarlint-runtime/）；组件再从 SonarQube 同步当前项目的语言分析器和 Quality Profile 规则。首次安装要求可访问 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 扫描为准。旧任务原有的审核设置可以继续读取，新项目页面只提供提交前审核。

如旧项目还使用上传式扫描的 sonar.scan_command，当前只接受单独的 sonar-scanner 或固定 Maven Sonar 目标 org.sonarsource.scanner.maven:sonar-maven-plugin:5.5.0.6356:sonar（可附 -DskipTests、-Dmaven.test.skip=true）。旧配置若因自定义命令或内嵌 Token 校验失败，请改用上述命令，并把 Token 留在项目凭据中。

查看问题、处理误报与沉淀规则

测试通过后，代码审核元技能会自动运行 dev_task sonar_check。任务台账可展开最近一次审核，查看原始结果、问题规则、严重程度、文件位置、分析器状态、人工复核状态与未解决数量。每次扫描在项目 .dsh/reviews/<任务 ID>/ 生成一份 Markdown 报告；项目可将该报告目录加入 .gitignore。最近一次结构化结果保存在 .dsh/task-<任务 ID>.json；历次完整结果另存于 .dsh/reviews/ 的 JSON 详情文件，主台账仅保留历史索引。

真实问题：修复代码，重新验证并复扫。疑似本地规则误报：使用 dev_task sonar_disposition 指定当前报告中的 issue_key，说明具体原因并提供证据；DSH 请求人工逐条批准。批准记录写回本次任务与报告，原始规则结果仍显示原来的 ERROR，任务门禁另显示复核后的未解决数量。未批准、证据不足、代码变化或重新扫描后都不能沿用该处置。服务端 Quality Gate 仍按 SonarQube 中的团队流程处理。

你可以直接对会话说：“请打开任务台账中这条 Sonar 告警，核对代码语义并给出理由和源码证据。确认是误报后发起逐项人工复核；未经我批准不要放行，也不要修改代码来藏掉告警。”审批请求会列出规则、文件、问题编号、理由和证据。多条告警需要分别审查；一条被批准不会自动豁免同规则的其他位置。

真实且具有通用性的修复案例，可以先用 learn_rule phase=propose 预览项目 Rule，再用 phase=apply 挂到对应开发 Skill；会影响之后创建的任务。已确认误报不列为学习候选，不自动转成团队规范。发现服务器自定义规则本身过宽时，应把例子反馈给规则维护者修正其实现或适用范围。

任务台账与项目文件

“待开始”表示实施项还没执行；“实施中”表示已记录开始；“待审查”表示缺逐项规格或质量审查；“代码审核”是整个任务的后续阶段。它们是不同层级的状态，不代表已经把任务分派给团队成员。任务完成后调用 dev_task complete 即归档并只读；上线后的修复或新需求使用新任务 ID，可关联原任务。台账默认显示进行中和待归档任务，也可切换查看已归档记录。任务台账会显示当前阶段、实施项、验证回执、审核结果和可选 Sonar 明细。

常见问题

装好后看不到入口？

检查插件是否装在正在运行的 Web profile，关闭旧 Web 进程并重启，查看启动日志。普通预设与“工程化开发引擎”预设的工具不同。

为什么初始化没有直接生成文件？

工作台会先生成供审阅的草稿，不会在扫描时直接写文件。检查通过后，点击“确认写入项目”。若提示没有默认模型，先在 DSH“模型”页选择模型。工程化会话也保留 init_project inspect → propose → apply 的调用方式。

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

验证命令需要输出至少一个实际测试的结果。检查运行器是否发现测试、是否跳过测试和摘要是否可见；重新运行有明确测试结果的命令。

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

自定义规则可能过宽。保留告警，核查每行对象是否必须独立；本地分析可逐条提交证据由人批准，服务端规则仍应由维护者修正。不要复用同一个实体或挪代码隐藏告警。

为什么审核提示补文件范围？

本次项目扫描范围内有 Git 新增/修改文件未登记到任务 files。核对提示的文件是否属于本任务；属于则补进 scope 并重新验证，不属于则使用独立分支或工作区隔离任务。

已有任务会随着项目配置改变吗？

不会更换创建时冻结的阶段图和资源引用；所引用 Skill/Rule 的正文下一次读取会更新。代码、范围或规则变化后，应重新检查证据、测试和审核。