@godv61/dsh-task-engine 0.29.3 → 0.30.0

package/skills/code-development/SKILL.md

@@ -1,11 +1,11 @@
----
-name: code-development
-description: 按验收条件和有序任务清单实现代码，并遵守绑定的项目规则。
-whenToUse: 自适应任务进入代码开发元技能时。
----
-
-# 代码开发元技能
-
-先读取当前阶段绑定的项目地图、领域编码技能和规则。按任务先后顺序修改代码，遵守已有接口和技术栈约束。每个实施项完成时记录结果及对应审核；不要为了分发给多个开发者而拆项。发现需求或方案发生变化时使用 `revise` 回到相应阶段。
-
-交接给测试：变更文件、实现要点、验收场景及已知限制。SonarQube 若启用，在代码审核阶段运行，不在每次编辑时触发。
+---
+name: code-development
+description: 按验收条件和有序任务清单实现代码，并遵守绑定的项目规则。
+whenToUse: 自适应任务进入代码开发元技能时。
+---
+
+# 代码开发元技能
+
+先读取当前阶段绑定的项目地图、领域编码技能和规则。按任务先后顺序修改代码，遵守已有接口和技术栈约束。每个实施项完成时记录结果及对应审核；不要为了分发给多个开发者而拆项。发现需求或方案发生变化时使用 `revise` 回到相应阶段。
+
+交接给测试：变更文件、实现要点、验收场景及已知限制。SonarQube 若启用，在代码审核阶段运行，不在每次编辑时触发。

package/skills/code-review/SKILL.md

@@ -1,11 +1,13 @@
----
-name: code-review
-description: 审核需求符合性、代码质量与可选的 SonarQube 结果，推动失败项修复。
-whenToUse: 自适应任务进入代码审核元技能时。
----
-
-# 代码审核元技能
-
-对照需求、任务产物、变更和测试回执审核。项目若启用 SonarQube，在本阶段读取本次分支或合并请求的新代码分析与质量门禁结果；有阻断问题时记录、修复、重新测试和复审，不能只填一个通过结论。使用 `dev_task review` 记录结果。
-
+---
+name: code-review
+description: 审核需求符合性、代码质量与可选的 SonarQube 结果，推动失败项修复。
+whenToUse: 自适应任务进入代码审核元技能时。
+---
+
+# 代码审核元技能
+
+对照需求、任务产物、变更和测试回执审核。项目若启用 SonarQube，在本阶段读取本次分支或合并请求的新代码分析与质量门禁结果；有阻断问题时记录、修复、重新测试和复审，不能只填一个通过结论。使用 `dev_task review` 记录结果。
+
 对可复用的失败案例提出项目 Rule 候选，包含触发场景、错误与正确示例、对应 Sonar 规则；经审阅后挂到相应代码开发 Skill。不要把单次误报或整个 Quality Profile 原样写成规则。
+
+本地规则审核的疑似误报先核对代码语义、规则说明与位置。确属误报时，使用 `sonar_disposition` 逐条提交具体原因和证据，等待人工批准；原始命中与原始门禁仍留在审核文件。此处置仅对当前未变化的本地审核有效，不能用于 CI 或上传式服务端 Quality Gate。已确认误报不应作为 `learn_rule` 的候选。

package/skills/eng-delivery/SKILL.md

@@ -4,18 +4,21 @@ description: 使用 dev_task 读取任务状态、执行流程门禁与完成条
 whenToUse: 在启用工程化交付会话预设后，开始或继续开发任务时先读取状态；阶段流转与完成必须通过 dev_task。
 ---
 
-# 工程任务编排
-
-新需求先按改动范围、实现依赖和架构影响选择 `low`、`medium`、`high` 或 `ultra`，调用 `dev_task assess` 查看相应阶段与有效技能来源。创建时提供 `complexity` 和具体的 `complexity_reason`。低档为局部明确修改；中档先形成需求与验收；高档增加按实现先后顺序的任务编排；超高档适用于完整新模块或大范围重构，增加架构设计。风险等级独立选择。没有 `complexity` 的旧调用继续使用 `.dsh/eng.json`。
-
-自适应任务的当前元技能及附加技能都以 `status.bindings` 为准，用 `dev_task load_skill` 和准确的 `source:name` 加载；项目同名 Skill 覆盖用户与内置 Skill，Rule 由生效 Skill 自身的 `profile.json` 持有。当前任务的流程在创建时冻结，其他会话的任务可选择不同档次。
+# 工程任务编排
+
+首次为项目执行 `init_project` 时，`<项目名>-project-map` 必须概述整个仓库的模块职责、依赖与通用代码入口，可被后续不同需求复用。当前需求的具体页面、接口调用链和验收条件写入任务产物；若确需长期保存领域地图，另建明确命名的领域 Skill，不把它们塞进项目总地图。`inspect` 只提供目录和清单证据，`propose/apply` 的正文由模型拟定，应用前逐项检查范围。
+
+新需求先按改动范围、实现依赖和架构影响选择 `low`、`medium`、`high` 或 `ultra`，调用 `dev_task assess` 查看相应阶段与有效技能来源。创建时提供 `complexity` 和具体的 `complexity_reason`。低档为局部明确修改；中档先形成需求与验收；高档增加按实现先后顺序的任务编排；超高档适用于完整新模块或大范围重构，增加架构设计。风险等级独立选择。没有 `complexity` 的旧调用继续使用 `.dsh/eng.json`。
+
+自适应任务的当前元技能及附加技能都以 `status.bindings` 为准，用 `dev_task load_skill` 和准确的 `source:name` 加载；项目同名 Skill 覆盖用户与内置 Skill，Rule 由生效 Skill 自身的 `profile.json` 持有。当前任务的流程在创建时冻结，其他会话的任务可选择不同档次。
 
 `dev_task` 是任务状态、阶段流转与门禁的唯一事实来源。流程预设决定阶段图与守卫；项目配置决定阶段使用哪些技能、每个技能遵守哪些规则，以及产物字段和提交文本。没有绑定时仅执行状态机，不自行补充技能或规则。
 
-1. 先调用 `dev_task`（operation=status）查找当前工作区和分支的任务；有多个候选时让使用者明确目标。没有任务时评估复杂度，调用 `assess`，然后按实际需求调用 `create`；已有任务从返回的 `stage` 继续。
+1. 先调用 `dev_task`（operation=status）查找当前工作区和分支的任务；有多个候选时让使用者明确目标。没有任务时评估复杂度，调用 `assess`，然后按实际需求调用 `create`；已有任务从返回的 `stage` 继续。
 2. 读取 `status.bindings`、`skill_obligations`、`artifact_requirements`、`legal_next` 和 `commit`。只加载当前及即将进入的终态实际绑定的技能，遵守本次交互读取的最新规则正文；没有绑定时不自行补上技能或规则。
 3. 技能要求的证据以其配置和 `status.skill_obligations` 为准：仅对 `command_receipts_required` 列出的技能通过带真实命令的 `skill_result` 记录；`manual` 通过人工审批记录；`artifact`、`review` 与 `none` 按对应阶段操作或无需额外回执处理。不要把所有技能都当成命令型技能。技能加载成功不等于要求的证据已经完成。
-4. 需要记录产物时，只使用 `artifact_requirements` 给出的 id 与字段。按当前流程要求完成确认、实施项、验证和审核，再调用 `advance`；被拒绝时按返回的阻塞原因修正，不改任务文件绕过门禁。
+4. 需要记录产物时，只使用 `artifact_requirements` 给出的 id 与字段。按当前流程要求完成确认、实施项、验证和审核，再调用 `advance`；被拒绝时按返回的阻塞原因修正，不改任务文件绕过门禁。
+   `items` 默认按 ID 增量合并；只有明确重排或删除尚未实施的项目时才传 `items_mode=replace` 和完整目标列表。审核前对照 Git 变更补齐任务文件范围；插件会拒绝漏登的新增审核文件。
 5. 只在 `status.commit` 允许的检查点申请提交，并按任务创建时的流程配置校验文件范围与消息。提交后按工具要求回写真实 Git HEAD。到达终态后调用 `complete`，以其完成条件为准；需要返工时使用 `revise`。
 
 不同流程的阶段数与守卫不同，不把某一预设的阶段顺序或提交格式当作所有项目的默认工作方法。用户修改流程配置只影响之后创建的任务；进行中的任务继续遵守创建时的阶段与门禁，但在下次交互读取所引用技能和规则的最新正文。

package/skills/requirements-analysis/SKILL.md

@@ -1,11 +1,11 @@
----
-name: requirements-analysis
-description: 澄清需求目标、边界和可验收结果，形成后续设计与开发的输入。
-whenToUse: 自适应任务进入需求分析元技能时。
----
-
-# 需求分析元技能
-
-读取用户需求与项目现状，区分已确认事实、推断和待澄清问题。给出目标、范围、非目标及可验证的验收条件。只对影响实现的缺口提问；能够依据现有上下文确定的内容直接写明依据。使用 `dev_task record` 写入当前阶段 `requirement` 产物，其字段以任务快照为准。
-
-交接给下一元技能：明确的验收条件、受影响的业务路径和仍未解决的约束。不要把实现步骤伪装成需求。
+---
+name: requirements-analysis
+description: 澄清需求目标、边界和可验收结果，形成后续设计与开发的输入。
+whenToUse: 自适应任务进入需求分析元技能时。
+---
+
+# 需求分析元技能
+
+读取用户需求与项目现状，区分已确认事实、推断和待澄清问题。给出目标、范围、非目标及可验证的验收条件。只对影响实现的缺口提问；能够依据现有上下文确定的内容直接写明依据。使用 `dev_task record` 写入当前阶段 `requirement` 产物，其字段以任务快照为准。
+
+交接给下一元技能：明确的验收条件、受影响的业务路径和仍未解决的约束。不要把实现步骤伪装成需求。

package/skills/task-orchestration/SKILL.md

@@ -1,11 +1,11 @@
----
-name: task-orchestration
-description: 按需求实现的依赖顺序拆解任务，记录每步输入、输出和验收。
-whenToUse: 高或超高复杂度任务进入任务编排元技能时。
----
-
-# 任务编排元技能
-
-把需求和架构决定拆成按实现先后推进的步骤。每步写清依赖、预期代码或文档产物、完成判据及交接给下一步的内容；先实现基础能力，再实现依赖它的能力。拆分服务于正确推进，不按人员或分支数量机械分包。使用 `dev_task record` 写入 `task-plan` 产物，并用 `items` 按此顺序登记实施项。
-
-交接给代码开发：有序任务清单、依赖关系、每步完成定义。负责人和分支仅在用户或团队配置要求时记录。
+---
+name: task-orchestration
+description: 按需求实现的依赖顺序拆解任务，记录每步输入、输出和验收。
+whenToUse: 高或超高复杂度任务进入任务编排元技能时。
+---
+
+# 任务编排元技能
+
+把需求和架构决定拆成按实现先后推进的步骤。每步写清依赖、预期代码或文档产物、完成判据及交接给下一步的内容；先实现基础能力，再实现依赖它的能力。拆分服务于正确推进，不按人员或分支数量机械分包。使用 `dev_task record` 写入 `task-plan` 产物，`steps` 每项单独起行并以稳定 ID 开头（例如 `- I1 数据模型`、`- I2 服务实现`），再用 `dev_task items` 按同样的 ID 和顺序登记全部实施项。进入代码开发前会核对两边的 ID，遗漏项不能静默消失。
+
+交接给代码开发：有序任务清单、依赖关系、每步完成定义。负责人和分支仅在用户或团队配置要求时记录。

package/skills/test-validation/SKILL.md

@@ -1,11 +1,13 @@
----
-name: test-validation
-description: 执行与本次变更相称的验证，并记录可追溯的实际命令回执。
-whenToUse: 自适应任务进入测试元技能时。
----
-
-# 测试元技能
-
+---
+name: test-validation
+description: 执行与本次变更相称的验证，并记录可追溯的实际命令回执。
+whenToUse: 自适应任务进入测试元技能时。
+---
+
+# 测试元技能
+
 根据验收条件选择验证场景，运行真实测试或构建命令，并通过 `dev_task verify` 保存回执。失败时先修复再重新运行；测试范围应覆盖本次改动及其主要回归风险。
 
-交接给代码审核：测试命令、结果、覆盖的场景和未覆盖原因。不要把模型的口头判断当成通过的测试。
+Maven 测试命令必须在输出中证明 Surefire/Failsafe 至少执行了一个测试；退出码为 0 但测试数为 0 或没有测试摘要时，验证不能通过。构建通过不等于测试通过。必要时调整命令让测试摘要可见，并核对原始测试报告。
+
+交接给代码审核：测试命令、结果、覆盖的场景和未覆盖原因。不要把模型的口头判断当成通过的测试。

package/docs/BRIEF-FOR-REVIEW.md

@@ -1,163 +0,0 @@
-# DSH Task Engine —— 技术简报（供评估与优化讨论）
-
-> 用途：把事实交给 GPT 讨论时使用。以下内容均经代码/实测核对，不是印象。
-
----
-
-## 1. 它是什么
-
-DeepSeek Harness（DSH）的插件：给 AI 编码会话加一套**可检查的工程交付流程**。
-
-- npm: `@godv61/dsh-task-engine`（`latest` = 0.23.9，MIT）
-- GitHub: https://github.com/godv61/dsh-task-engine（**已被 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录**，PR #5681 一次通过）
-- 规模：host 面 **4079 行** TS，client 面 **2173 行** TSX，测试 146 项 P0 断言 + 52 项 `node:test`
-
-### 核心机制
-
-**一个工具 `dev_task`**，7 个操作：`status` / `config` / `init` / `create` / `commit` / `install_hook` / `verify_hook`。
-
-它持有任务状态机，**阶段流转是硬门禁**（模型无法绕过）：
-
-| 守卫 | 含义 |
-| :--- | :--- |
-| `requirement_confirmation` | 需求须经人确认 |
-| `solution_confirmation` | 方案须经人确认 |
-| `artifacts_present` | 阶段产物须齐备 |
-| `todos_done` | 实施项须全部完成 |
-| `verified` | 须有**真实命令回执**（退出码 0，未超时/中止/被沙箱拒） |
-| `review_passed` | 须有审核结论 |
-
-**三个内置流程**（阶段顺序与守卫由预设固化）：
-
-| 流程 | 阶段 |
-| :--- | :--- |
-| `standard` | 需求评审 → 设计 → 开发 → 交付 → 代码审核 → 完成 |
-| `agile` | 需求 → 开发 → 交付 → 审查 |
-| `minimal` | 开发 → 交付 |
-
-**渐进式披露**：每个阶段挂「技能 + 规则」，进入该阶段才披露，避免一次性灌入上下文。
-
-**工作台 5 个标签页**：项目初始化 / 流程配置 / 任务台账 / 技能 / 规则。
-
----
-
-## 2. 已知的设计缺口（当前讨论起点）
-
-### 2.1 技能与规则是平级的，但存在**隐式依赖**
-
-**数据模型**（`src/engine.ts`）：
-
-```ts
-interface StageBinding {
-  skills?: string[]   // 独立数组
-  rules?: string[]    // 独立数组
-}
-```
-
-引擎分别解析：
-
-```ts
-const rules = await resolveRules(binding?.rules ?? [], fs, cwd)   // 不经技能
-```
-
-**但技能文本里引用了具体规则**，例如 `code-implement/SKILL.md`：
-
-> 代码质量：按内置规则 **coding-conventions** 查「做得好不好」
-
-**问题**：这个依赖**只写在散文里，没有结构化**。因此：
-
-- 用户在 UI 勾了 `code-implement` 但没勾 `coding-conventions` → 技能执行时引用一个不存在的规则
-- **引擎不校验，UI 不提示**
-- 默认配置碰巧配对，用户改绑定就可能拆散
-
-**默认配置印证耦合确实存在**：规则 `coding-conventions` 同时挂在「开发」（`code-implement`）和「交付」（`code-verify`）两个阶段。
-
-### 2.2 待决策的四个方案
-
-| 方案 | 做法 | 代价 |
-| :--- | :--- | :--- |
-| **A. 声明式依赖** | `SKILL.md` frontmatter 加 `requires_rules: [...]` | 是 B/C/D 的前置条件；需改 7 个内置技能 |
-| **B. 软提示** | 规则列表全量显示，标注「此技能建议配合 X」 | 保留自由组合；仅提示 |
-| **C. 强联动** | 勾技能 → 规则列表过滤到相关项 | ⚠️ 破坏自由组合（同一规则复用于多技能） |
-| **D. 仅保存时校验** | 不联动 UI，保存时警告「技能 X 引用了未挂载的规则 Y」 | 最轻量；问题暴露较晚 |
-
-**当前倾向**：A + D（先让关系可表达，再做校验），或 A + B。**C 需要在 A 的数据之上才成立。**
-
----
-
-## 3. 其他可能值得评估的方向
-
-### 3.1 流程定制能力的边界
-
-**现状**：阶段顺序与守卫由预设固化，**可视化自定义流程不在计划内**（曾评估，结论是不做——把流程设计负担转嫁给使用者）。
-
-**可调部分**：项目根 `.dsh/eng.json` 只声明 `flow`（选哪套预设）+ `stage_bindings`（每阶段挂什么）。
-
-**待评估**：这个边界是否过窄？例如是否该允许「加一个自定义阶段但保留守卫语义」？
-
-### 3.2 验证与审核的可信度边界
-
-**现状**（README 与 FAQ 都声明）：
-
-> 命令覆盖是否充分、审核是否准确仍需判断，**不能把一个成功退出码当作全部需求已验证**。
-
-- 验证需真实回执，但**回执不等于需求被完整覆盖**
-- 审核/实施项结论**由模型记录**，非独立验证
-- 任务 JSON **无签名**，有文件写权限者可同时改内容与摘要
-
-**待评估**：对「成熟开源产品」而言，这个边界是否需要更强机制（如独立验收、产物哈希链）？
-
-### 3.3 提交门禁可被绕过
-
-**现状**：`hooks/commit-msg` 检查任务、阶段、消息与文件范围。但：
-
-> `--no-verify`、替换 `hooksPath` 或直接改本地数据**仍可能绕过**。
-
-**待评估**：是否需要与 CI 结合的服务端校验？还是明确声明「个人本机工具，不提供防篡改」即可？
-
-### 3.4 多环境一致性
-
-**现状问题**：同一插件需在**桌面版 DSH**（`0.1.2-rc.1`）与**源码版 DSH**（`0.1.7-alpha.1`）上工作，两者契约不同：
-
-- persona 字段：桌面版要 `text`，源码版要 `prefix`（已在 0.23.7 通过「跟着运行环境走」解决）
-- 插件管理：桌面版用 generation 机制，源码版用 pnpm
-
-**已采取的防护**：CI 加 `dsh-contract` job（跑 `scripts/verify-dsh-compat.mjs`），peer 范围用显式 `||` 分支覆盖各版本。
-
-**待评估**：DSH 处于 alpha、**1–3 天一个 tag**，这个跟踪成本是否可持续？
-
-### 3.5 其他
-
-- **国际化**：目前中文为主，README 有中英双版。是否需要完整 i18n？
-- **可访问性**：工作台介入了 `aria-label`，但未系统测试
-- **性能**：任务台账在任务多时的表现未测
-- **文档**：本次刚做过一次重组（发布说明归入 `docs/releases/`，索引分「当前/历史」）
-
----
-
-## 4. 近期已完成的修复（供判断演进方向）
-
-| 版本 | 内容 |
-| :--- | :--- |
-| 0.23.9 | 可搜索绑定选择器（独立搜索/仅看已选/计数/就地滚动/预设默认锁定）；source map 停止内联源码（447→148 KB）；修 10 处 UTF-8 字节损坏 |
-| 0.23.8 | 文档修正（4 处与代码矛盾的陈述）+ 目录重组 |
-| 0.23.7 | persona 字段兼容（新旧 DSH 都能用）——**读源预设用哪个字段就写哪个**，不再硬编码 |
-| 0.23.6 | eng 预设每次启动从运行中 harness 重新派生（此前只在首次生成，DSH 升级后失效） |
-
----
-
-## 5. 环境依赖（影响可测试性）
-
-- **DSH 0.1.7-alpha.1** 曾有 bug 致**所有工具调用失败**（`ctx.tools[TOOL_RUNTIME_SCHEDULER]` 为 `undefined`），社区在 discussions #7035 / #7194 报告，**0.1.7 已修**
-- 源码版用 `pnpm dsh web` 会触发模块双重加载；绕过方式：`node apps/cli/lib/bin.js <profile>`
-- 桌面版插件由 `dshmarket` + generation 机制管理，**不能用 CLI 的 `dsh plugin` 直接操作**（会与它冲突）
-
----
-
-## 6. 想请对方重点回答的问题
-
-1. **技能↔规则依赖**：A/B/C/D 选哪个？还是有更好的模型（如规则直接属于技能、互不独立）？
-2. **流程定制边界**：「不做自定义流程」对一个成熟产品是否合理？还是该提供受限的扩展点？
-3. **可信度声明**：当前「不防篡改」的边界，是明确声明即可，还是需要机制补强？
-4. **对 DSH alpha 的跟踪成本**：1–3 天一个 tag，插件该怎么定位（追最新？固定版本？）
-5. **还缺什么才能称得上「成熟开源产品」**：贡献指南、issue 模板、语义化版本、变更日志规范、安全策略、行为准则？