@godv61/dsh-task-engine 0.29.8 → 0.30.1

package/README.md

@@ -1,114 +1,216 @@
-<p align="center">
-  <img src="docs/assets/workflow-banner.svg" alt="DSH Task Engine：DeepSeek Harness 的个人工程流程工作台，标准流程从需求评审走向完成" width="100%" />
-</p>
-
-<h1 align="center">DSH Task Engine</h1>
-
-> 自适应流程、项目技能初始化与可选 SonarQube 审核支持复用 CI 分析、上传式本机扫描，以及未提交代码的本地规则审核。新代码范围由参考分支定义。
-
-<p align="center">按每个需求选择工程路径，用项目 Skill 与 Rule 复用团队开发规范。</p>
-<p align="center"><sub>Task-scoped engineering workflows for DeepSeek Harness.</sub></p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@godv61/dsh-task-engine"><img src="https://img.shields.io/npm/v/%40godv61%2Fdsh-task-engine?style=flat-square&amp;color=238636" alt="npm version" /></a>
-  <a href="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml"><img src="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml/badge.svg" alt="Package verification CI" /></a>
-  <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-64748b?style=flat-square" alt="MIT license" /></a>
-</p>
-
-<p align="center">
-  <a href="#快速开始">快速开始</a> ·
-  <a href="#工作台里有什么">工作台</a> ·
-  <a href="docs/README.md">使用文档</a> ·
-  <a href="docs/roadmap.md">功能规划</a> ·
-  <a href="docs/CHANGELOG.md">更新日志</a>
-</p>
-
-## 为什么用它
-
-让 AI 在持续开发的项目中处理不同需求时，按这次需求的复杂度选择低、中、高、超高四档任务流程。元技能规定交接产物，项目 Skill/Rule 承载团队编码规范；同一项目下的多个会话可以各自推进不同任务。
-
-- **知道下一步做什么**：任务创建时选择复杂度并冻结流程，当前阶段的条件和产物清楚可查。
-- **复用自己的工作方法**：把技能和规则安装到项目或个人目录，将规则配置在技能下，再把技能挂到节点上；同一技能在任何节点都使用同一套约束。
-- **找得到过程记录**：任务台账集中查看阶段、实施项、验证与审核状态。
-
-## 快速开始
-
-需要已安装 DeepSeek Harness 和 pnpm。插件装入你使用的 Web profile；下面以 `web` 为例。
-
-```sh
-dsh plugin --profile web add @godv61/dsh-task-engine
-```
-
-1. 重启 Harness Web，打开侧边栏的 **工程任务**。
-2. 选择工作区，在 **自适应流程** 中查看四档路径，按需挂载项目技能。
-3. 新建会话，选择 **工程化开发引擎** 预设，描述要完成的开发任务。
-
-看到“工程任务”入口和“工程化开发引擎”会话预设，就说明工作台与任务工具已接入。使用 Harness 源码启动的安装方式见[安装与启用](docs/getting-started.md)。
-
-> 工程化会话先分析需求复杂度，再以 `dev_task assess` 预览并创建任务；`.dsh/meta.json` 只配置元技能挂载和可选 SonarQube 审核，不强迫项目所有会话走同一条流程。
-
-## 工作台里有什么
-
-| 页面 | 你可以做什么 |
-| :--- | :--- |
-| **项目初始化** | 分开管理 `AGENTS.md` 与项目 Skill/Rule。后者可在页面复制初始化请求，发给“工程化开发引擎”会话后由 `dev_task init_project` 扫描、预览并应用。 |
-| **自适应流程** | 查看四档任务路径、元技能绑定与可选 SonarQube 审核配置；按项目保存 Token 到本机 DSH 凭据存储。 |
-| **任务台账** | 查看实施、验证和审核记录；展开 SonarQube 结果可看触发的规则、问题位置和逐次审核文件。 |
-| **技能** | 安装、编辑技能，并集中维护每个技能唯一的规则列表。 |
-| **规则** | 选择 Markdown 文件安装规则，维护项目或个人开发约定。 |
-
-插件内置会话编排 Skill `eng-delivery` 和六个通用元技能 Skill。项目知识、领域编码方法和 Rule 由使用者创建或通过 init 生成，可放在项目或个人目录；同名项目 Skill 在新任务中覆盖用户级 Skill。
-
-新路径的四档顺序、元技能交接契约、`init_project` 和可选 SonarQube 审核见[自适应工程任务](docs/adaptive-workflows.md)。
-
-**流程与工作方法各有职责。** 四档流程规定阶段与门禁，并在相应阶段加载内置元技能；项目业务技能和规则由使用者配置。同一条规则可由多个技能共享。点击元技能的“配置核心 Skill 的 Rule”，内置或用户级 Skill 可在保存时生成同名项目副本，再挂载项目 Rule。任务的流程与资源引用在创建时确定；Skill/Rule 正文在每次交互读取最新版本，创建时副本仅用于审计。[自适应流程说明](docs/adaptive-workflows.md)
-
-已有任务仍按创建时的快照运行；旧版 `.dsh/eng.json` 也继续可读。工作台只展示自适应流程，旧版配置细节保存在[历史文档](docs/configuration.md)。
-
-## 把自己的技能和规则带进来
-
-**选择文件 → 检查预览 → 选择范围 → 确认安装 → 挂到阶段。**
-
-技能选择含 `SKILL.md` 的文件夹，规则选择一个 `.md` 文件。预览会显示名称、正文、文件数、体积和目标路径；目标目录中已有同名资源不会被覆盖。项目级 Skill 可与内置 Skill 同名，以项目版本优先生效。
-
-| 安装范围 | 存放位置 | 用途 |
-| :--- | :--- | :--- |
-| 项目 | 工作区 `.dsh/skills`、`.dsh/rules` | 当前项目的工作方法与约定；工作台新建资源默认写在这里。 |
-| 个人 | `$DSH_HOME/skills`、`$DSH_HOME/rules` | 在这台电脑上的多个项目间复用。 |
-
-工作台也会发现同一项目 `.agents/skills/<名称>/SKILL.md` 中的 Codex 项目技能，可将它绑定到流程节点，并在技能下配置 DSH 规则；它的正文仍留在原目录。运行时使用 `dev_task` 的 `load_skill` 操作读取该技能及其规则，下一次读取会取得文件的最新内容。[Codex 项目技能说明](docs/configuration.md#技能与规则)
-
-技能的脚本、模板和附件会一并保留。文件格式、大小限制和故障处理见[技能与规则安装指南](docs/resource-install.md)。
-
-## 使用文档
-
-| 想了解什么 | 从这里开始 |
-| :--- | :--- |
-| 安装、启用与第一次使用 | [快速上手](docs/getting-started.md) |
-| 任务级流程、元技能与 SonarQube | [自适应工程任务](docs/adaptive-workflows.md) |
-| 旧项目配置与阶段绑定 | [流程配置](docs/configuration.md) |
-| 技能文件夹与 Markdown 规则 | [资源安装](docs/resource-install.md) |
-| 完整操作说明 | [HTML 手册](docs/manual.html)（下载后在浏览器打开） |
-| 当前能力与常见问题 | [常见问题](docs/faq.md) |
-| 本地开发与验证 | [开发指南](docs/development.md) |
-| 真实项目回归修复 | [0.23.1 发布说明](docs/releases/0.23.1.md) · [回归迭代说明](docs/workflow-regression.md) |
-| 版本变化与验证记录 | [更新日志](docs/CHANGELOG.md) · [0.23.1 测试说明](docs/testing/0.23.1/测试报告.md) |
-
-## 能力说明
-
-`dev_task` 按配置检查阶段、产物和提交条件。新任务的验证要求真实命令回执；技能可按自身配置要求命令、产物、审核、人工批准或无需额外证据，执行义务可在任务状态中查看。任务保存创建时的流程与资源引用；之后修改流程配置不会改变进行中任务的状态机，编辑所引用资源的正文会从下一次交互生效。
-
-审核结论、实施项完成情况和测试覆盖面仍需要你判断。本地提交钩子提供即时检查，不能替代人工审核或项目自己的 CI。详细说明见[常见问题](docs/faq.md)。
-
-小修正允许主代理处理，仍须审核和验证。遇到沙箱权限拒绝应使用宿主审批或报告阻塞，不能靠反复切换命令规避。
-
-状态查询会列出过期验证和附加技能回执；`commit.allowed` 同时检查这些阻塞，文件变化后先补验证再申请提交。
-
-验证命令的单次权限重试先审批后执行，不改变会话权限；操作方式见[验证权限说明](docs/faq.md#验证命令被沙箱阻止怎么办)。
-
-记录需求、方案或评审前，模型可从 `artifact_requirements` 获取当前阶段允许的字段和缺项，避免猜测字段名。
-
----
-
-[MIT License](LICENSE) · [反馈问题](https://github.com/godv61/dsh-task-engine/issues) · Built for DeepSeek Harness
+<p align="center">
+  <img src="https://raw.githubusercontent.com/godv61/dsh-task-engine/main/.github/assets/readme-hero.svg" alt="DSH Task Engine：从项目知识到可验证交付" width="100%" />
+</p>
+
+<h1 align="center">DSH Task Engine</h1>
+
+<p align="center">
+  为 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 提供按需求运行的工程化开发引擎。<br />
+  让项目知识、团队规范、测试证据和代码审核在每次开发中真正生效。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@godv61/dsh-task-engine"><img src="https://img.shields.io/npm/v/%40godv61%2Fdsh-task-engine?style=flat-square&amp;color=0d9488" alt="npm 版本" /></a>
+  <a href="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml"><img src="https://github.com/godv61/dsh-task-engine/actions/workflows/verify.yml/badge.svg" alt="自动验证状态" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-334155?style=flat-square" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <a href="#安装与检查">安装</a> ·
+  <a href="#首次初始化项目">项目初始化</a> ·
+  <a href="#执行一个开发任务">任务操作</a> ·
+  <a href="#按项目配置-sonarqube">SonarQube</a> ·
+  <a href="docs/manual.html">HTML 使用手册</a>
+</p>
+
+---
+
+## 它解决什么问题
+
+一个项目会有许多需求、分支和会话。团队需要复用编码约定，但不同需求不该被迫走完全相同的步骤。
+
+| 常见问题 | Task Engine 的做法 |
+| --- | --- |
+| 大模型反复询问项目结构、版本和编码习惯 | 初始化项目地图、技术栈与开发 Skill；Rule 保存团队约束。 |
+| 小改动流程太重，大改动又缺少分析与拆解 | 按**每项需求**评估复杂度，选择低、中、高、超高四档路径。 |
+| 会话说“测试通过”，实际没有执行测试 | `dev_task` 保存命令和回执；Maven 测试必须证明至少执行一个测试。 |
+| 审核问题散落在聊天记录里 | 任务台账展示阶段、实施项、测试与审核；可选 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，再看 Web 启动日志。
+
+## 首次初始化项目
+
+1. 在**工程任务**顶部选择代码库根目录作为工作区，并确认当前 Git 分支。
+2. 打开**项目初始化 → 项目 Skill / Rule 初始化**，点击**扫描并生成提案**。工作台会读取项目清单与部分源码，用已配置的默认模型生成 Skill / Rule 草稿；无需复制请求到会话。生成过程可能需要一两分钟。
+3. 逐项检查草稿正文、简介、元技能挂载及 Rule 关联。可直接修改或移除不合适的建议；修改后点击**检查修改**。
+4. 检查通过后点击**确认写入项目**。工作台再次核对项目地图覆盖、同名文件和配置版本，只写入刚审阅的提案。若项目配置或文件已变化，重新生成或检查。不要把某一条需求的实现方案当成整个项目的结构地图。
+
+| 阶段 | 会发生什么 | 重点检查 |
+| --- | --- | --- |
+| 扫描并生成提案 | 只读扫描目录、构建清单、代表性源码，用默认模型生成草稿 | 后端、前端和脚本等主要模块是否都被发现。 |
+| 检查修改 | 校验项目地图、Skill、Rule、挂载关系和同名冲突 | 内容是否覆盖整个仓库；版本和规则是否有代码证据。 |
+| 确认写入项目 | 按同一提案哈希写入文件 | 已有同名资源不会被静默覆盖。 |
+
+通常会生成 `.dsh/skills/<项目名>-project-map/SKILL.md`、技术栈与后端/前端编码 Skill，以及 `.dsh/rules/` 下的项目规则。**项目地图应描述整个仓库**的模块职责、依赖和通用入口；当前需求的页面、接口、验收条件应放进任务产物。页面中的 **AGENTS.md 初始化**是另一项操作。
+
+团队共享前，审阅 `.dsh/skills/`、`.dsh/rules/` 和 `.dsh/meta.json`，再提交到 Git。Token 与本地审核报告不应提交。
+
+## 元技能、Skill 和 Rule
+
+内置元技能覆盖**需求分析、架构设计、任务编排、代码开发、测试、代码审核**。元技能约定本阶段做什么、交给下一阶段什么；项目 Skill 说明如何在当前仓库做；Rule 描述更具体的约束、触发条件与适用范围。
+
+项目 Skill 可以放在 `.dsh/skills/`，工作台也能发现 `.agents/skills/` 中的 Codex 项目技能。用户级 Skill 可跨项目复用；**同名 Skill 的优先级是项目级 > 用户级 > 内置**。项目同名版本使用自己的 Rule 列表，不会自动混入被覆盖版本的 Rule。
+
+在**工程任务 → 自适应流程**给元技能挂载 Skill，在对应 Skill 的 `profile.json` 中配置 Rule；项目挂载保存在 `.dsh/meta.json`。Rule 跟随 Skill 生效，不会因为挂在某一阶段就随意叠加给其他 Skill。已创建任务冻结阶段图和资源引用；被引用的 Skill/Rule 正文下次读取会更新，删除正在引用的资源会阻止流转。
+
+## 四档流程与交接
+
+| 档次 | 典型需求 | 默认阶段顺序 |
+| --- | --- | --- |
+| **低 · low** | 边界明确的局部修改 | 代码开发 → 测试 → 代码审核 → 完成 |
+| **中 · medium** | 常规功能或缺陷修复 | 需求分析 → 代码开发 → 测试 → 代码审核 → 完成 |
+| **高 · high** | 跨模块且有实现先后依赖 | 需求分析 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成 |
+| **超高 · ultra** | 完整新模块或大范围重构 | 需求分析 → 架构设计 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成 |
+
+需求分析交付目标、范围、非目标和可验证的验收条件；架构设计交付边界、影响与取舍；任务编排交付按实现先后排列的实施项 ID、依赖和交接产物；开发交付文件与逐项审查；测试交付真实命令；代码审核交付结论和可选 Sonar 报告。**实施项体现推进顺序，不是按人数分派工作。** 风险等级由模型另外判断，不等同复杂度。
+
+## 执行一个开发任务
+
+在项目工作区新建**工程化开发引擎**会话，可以直接这样提出需求：
+
+```text
+请在当前项目实现“设备授权范围”需求。先读取已有项目 Skill/Rule，
+评估需求复杂度并明确验收条件。需要任务编排时，按实现先后列出
+实施项、依赖和交接产物；开发、真实测试和代码审核按任务台账推进。
+只在当前分支工作，不要推送。
+```
+
+随后按台账和 `dev_task` 的门禁推进：
+
+1. **确认任务归属。** 先用 `status` 查看工作区和分支是否已有任务；新需求用 `assess` 预览档次和技能，再用 `create` 创建。发现已有任务时核对任务 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 的 `test`、`verify`、`package`、`install`，输出必须有 Surefire/Failsafe 摘要且至少执行一个测试；显示 0 个测试或没有摘要时不能算通过。编译、静态检查、单元测试、接口测试和业务验收覆盖的风险不同，缺少环境或测试账号时应明确记录未覆盖项。
+
+多会话并行时，建议每个任务使用独立分支或工作区，避免其他任务的未提交文件混入本次范围和审核。
+
+## 按项目配置 SonarQube
+
+**不需要 Sonar：** 保持“自适应流程”中的 Sonar 开关关闭，不必填地址、Key 或 Token；代码审核元技能和项目 Rule 仍会运行。
+
+**需要 Sonar：** 在工作台顶部选对项目，进入**自适应流程 → SonarQube 审核**，依次填写：
+
+| 字段 | 填写方式 |
+| --- | --- |
+| 服务地址 | SonarQube 根地址，如 `https://sonar.example.com`，不带项目页面路径。 |
+| 项目 Key | 当前代码库在 SonarQube 中的项目标识，不同项目可以不同。 |
+| 扫描来源 | 提交前本地规则选 `ide-local`；已有 CI 分析选 `ci`；本机上传扫描选 `local`。 |
+| 分析对象 | 分支或合并请求，与实际扫描目标一致；`ide-local` 使用分支模式。 |
+| 参考分支、审核路径 | 本地规则审核的新代码 Git 基线，以及实际扫描的项目相对路径。 |
+| Token | 在同一页面单独保存到本机 DSH 凭据存储，按工作区隔离；保存后只显示“已配置”。 |
+
+Sonar 的非秘密配置保存在项目 `.dsh/meta.json`；Token **不会写入该文件、任务或报告**。换项目时分别配置。项目的 Quality Profile 和规则本身仍由 SonarQube 服务器管理。
+
+### 三种审核来源
+
+| 来源 | 何时使用 | 提交/推送 | 结果边界 |
+| --- | --- | --- | --- |
+| `ide-local` 本地规则 | 提交前检查新代码，本机具备 SonarLint 后台组件 | **无需提交、无需推送** | 同步 Quality Profile 中可本地运行的规则；不产生 CE task，不等同完整服务端 Quality Gate。 |
+| `ci` CI 分析 | CI 已扫描并能取得本次 CE task ID | 按 CI 触发条件提交并推送 | 读取该次服务端分析的新代码问题与 Quality Gate。 |
+| `local` 本机上传 | 本机有扫描器且服务端支持任务分支分析 | 先提交，无需推送 | 将扫描结果上传 Sonar；Community Build 的分支分析会预先拒绝。 |
+
+`ide-local` 需要选 Git 参考分支或提交作为新代码基线，并用 `include_paths` 限定实际审核范围，例如只扫描后端 Maven 模块。审核前会核对这些目录的 Git 变更是否全部登记在任务 `files`；漏登会报出文件名。扫描范围外的前端或 SQL 不会被称为通过了后端审核。
+
+本地规则审核还需要 DSH 服务进程提供 `DSH_SONARLINT_JAVA`、`DSH_SONARLINT_LIB`、`DSH_SONARLINT_PLUGINS`，分别指向 Java、SonarLint 后台 JAR 目录和分析器 JAR；Windows 多个插件路径用分号分隔。JS/TS/Vue/CSS 分析还需要 Node.js。无法分析的语言会列为“未覆盖”并阻断。需要完整服务端结论时使用 CI 扫描。
+
+### 查看审核、处理误报、沉淀 Rule
+
+测试通过并进入**代码审核**后运行 `dev_task sonar_check`。在**任务台账**展开最近一次审核，可查看来源、原始结果、规则、严重程度、文件位置、人工复核状态和未解决数量。每次扫描在项目 `.dsh/reviews/<任务 ID>/` 生成 Markdown 报告；结构化结果写入 `.dsh/task-<任务 ID>.json`。
+
+- **真实问题：** 修复代码，重新测试并复扫。真实、已修复且可复用的案例，可以通过 `learn_rule phase=propose → apply` 预览并沉淀为项目 Rule，供之后创建的任务使用。
+- **疑似本地规则误报：** 用 `sonar_disposition` 指定本次报告的 `issue_key`，提供具体理由与源码证据，由人逐条批准。原始告警仍保留；未批准、证据不足、代码变化或重新扫描后都不能沿用处置。已确认误报不会自动转成 Rule。
+- **CI 或上传式服务端结果：** 插件不能通过本地误报处置绕过服务端 Quality Gate；应按组织流程在 SonarQube 中处理。若自定义规则本身过宽，应反馈给规则维护者，不要为消除告警而破坏业务实现。
+
+## 任务台账与项目文件
+
+“待开始”表示实施项还未执行；“实施中”表示已记录开始；“待审查”表示缺少该项的规格或质量审查；“代码审核”则是整个任务的后续阶段。它们不是团队成员分派状态。
+
+| 位置 | 内容 | 团队共享建议 |
+| --- | --- | --- |
+| `.dsh/meta.json` | 项目元技能挂载及 Sonar 非秘密配置 | 审阅后提交 |
+| `.dsh/skills/`、`.dsh/rules/` | 项目 Skill、Rule 与 Skill 的 `profile.json` | 审阅后提交 |
+| `.dsh/task-<id>.json` | 任务阶段、实施项、测试和审核回执 | 按团队留痕策略决定 |
+| `.dsh/reviews/` | 逐次 Sonar 报告与误报处置 | 可加入 `.gitignore` 留在本机 |
+| 本机 DSH 凭据存储 | 按工作区隔离的 Sonar Token | 不提交、不分享 |
+
+## 常见问题
+
+<details>
+<summary>安装后看不到“工程任务”或“工程化开发引擎”？</summary>
+
+核对插件是否装在正在运行的 Web profile，关闭旧 Web 进程后重启，查看启动日志。普通预设与工程化预设加载的工具不同。
+
+</details>
+
+<details>
+<summary>项目初始化在哪里操作？</summary>
+
+在工程任务的“项目初始化”页直接点击“扫描并生成提案”，审阅后确认写入。页面使用默认模型；若提示模型未配置，先到“模型”页选择默认模型。工程化会话仍可按需使用 `dev_task init_project` 的 `inspect → propose → apply` 调用。项目根目录的 AGENTS.md 生成功能是独立操作。
+
+</details>
+
+<details>
+<summary>为什么 Maven 构建成功，任务仍不能前进？</summary>
+
+如果验证命令是 Maven 测试目标，插件还要求输出证明至少运行一个测试。检查 Surefire/Failsafe、JUnit 引擎和是否跳过测试；重新运行能看到测试摘要的命令。
+
+</details>
+
+<details>
+<summary>为什么 Sonar 报了业务上必须创建的对象？</summary>
+
+自定义规则可能过宽。保留告警并核对代码语义；本地规则分析可以逐条提交理由和证据由人批准，服务端规则应由维护者修正。不要复用本该独立的实体或挪动代码来隐藏告警。
+
+</details>
+
+<details>
+<summary>为什么审核提示补文件范围？已有任务会随配置改变吗？</summary>
+
+本次扫描路径内的 Git 变更若未登记到任务 `files`，需补入当前任务范围，或把其他任务移到独立分支/工作区。已有任务的阶段图和资源引用在创建时冻结；Skill/Rule 正文下次读取会更新，代码、范围或规则变化后应重新检查证据。
+
+</details>
+
+## 文档与参与
+
+- [HTML 使用手册](docs/manual.html)：适合下载后分享给团队使用者，覆盖安装、初始化、任务、Sonar 与排障。
+- [开发指南](docs/development.md)：插件架构、构建、测试和发布前检查。
+- [反馈问题](https://github.com/godv61/dsh-task-engine/issues) · [MIT License](LICENSE)
+
+<p align="center"><sub>DSH Task Engine · 让项目知识进入开发，让每次交付留下证据。</sub></p>

package/docs/development.md

@@ -1,53 +1,45 @@
-# 开发指南
-
-[← 文档导航](README.md)
-
-插件包含 host 控制器、agent 工具和浏览器工作台。代码为 TypeScript，发布到 npm 的包包含预构建入口与资源文件。
-
-## 本地验证
-
-在插件源码目录执行：
-
-```sh
-npm install
-npm run build
-npm run typecheck
-npm test
-npm run verify:package
-```
-
-`build` 生成 host、浏览器客户端与提交钩子；`typecheck` 检查 host 和 client 两个编译面。`verify:package` 将 tarball 安装到干净临时项目，检查包入口、客户端注册、包内测试和 CLI 语法。
-
-CI 在 Windows 的 Node 22/24 上运行。每次功能修改选择相关验证；文档排版调整只需要文档、链接和渲染检查。测试数量随版本变化，当前值以本地 `npm test` 与 `npm run verify:package` 的输出为准，不在此处固定。
-
-## 代码导航
-
-| 位置 | 职责 |
-| :--- | :--- |
-| [src/engine.ts](../src/engine.ts) | 状态机、阶段条件和提交规则检查。 |
-| [src/workflows.ts](../src/workflows.ts) | 三套流程骨架及可选的推荐配置。 |
-| [src/dev-task.ts](../src/dev-task.ts) | 模型使用的 dev_task 工具与任务文件操作。 |
-| [src/controller.ts](../src/controller.ts) | 工作台读取配置、任务和资源的 Remote 控制器。 |
-| [src/resource-import.ts](../src/resource-import.ts) | 导入校验、安装预览、独占写入与失败清理。 |
-| [src/client](../src/client/) | 工作台界面与客户端 Remote 定义。 |
-| [src/hook.ts](../src/hook.ts) | 提交钩子的源码，构建后输出到 hooks/commit-msg。 |
-| [cordis.patch.yml](../cordis.patch.yml) | Bundle 的 host 挂载声明。 |
-
-## 启用方式
-
-Host 入口挂载工作台控制器，并在 eng 预设不存在时生成“工程化开发引擎”。Agent 入口只在引用它的会话预设中注册工具和技能。
-
-需要将插件接入自己的会话预设时，在该预设的 agent.cordis.yml 加入：
-
-```yaml
-- id: task-engine-agent
-  name: '@godv61/dsh-task-engine/agent'
-```
-
-eng 预设由插件在每次启动时**从当前 Harness 的 `standard` 预设重新派生**，因此 Harness 升级后预设会跟着更新。判断依据是文件里是否带有本插件写入的 agent 行：**插件自己生成的会被更新，手工编辑过的原样保留**。配套的 `enable` 脚本行为更保守——目标已存在时直接拒绝，不覆盖。
-
-## 可选 host 接入
-
-Host 入口优先使用 Harness 的 `workspaceRegistry.resolveByPath` 获取已登记工作区。旧 host 可以通过插件导出的 `registerWorkspace` 和 `enableStrictWorkspaces` 配置注册目录及严格模式，接口定义见 [src/controller.ts](../src/controller.ts)。注册范围不等于会话身份鉴权；个人本机使用不要求为此改造 Harness。
-
-发布前保持 README、使用手册和实际代码一致；不要将规划中的功能描述为已经可用。
+# 开发与发布
+
+[返回项目首页](../README.md) · [使用手册](manual.html)
+
+插件分为 host 控制器、agent 工具和浏览器工作台。源码在 `src/`，构建结果在 `lib/`，npm 包包含预构建入口、内置 Skill、预设和提交钩子。
+
+## 代码位置
+
+| 路径 | 主要职责 |
+| --- | --- |
+| `src/adaptive.ts`、`src/workflows.ts`、`src/engine.ts` | 四档流程、兼容流程与任务状态机。 |
+| `src/dev-task.ts` | `dev_task` 操作、阶段门禁和任务留痕。 |
+| `src/sonarlint-local.ts`、`src/sonar.ts`、`src/sonar-report.ts` | 本地规则分析、服务端结果与 Markdown 报告。 |
+| `src/verification-tests.ts` | Maven 测试摘要门禁。 |
+| `src/project-init.ts` | 项目扫描与初始化覆盖检查。 |
+| `src/controller.ts`、`src/client/` | 工作台读写接口与界面。 |
+| `skills/`、`preset/` | 会话编排与元技能正文。 |
+
+## 本地验证
+
+在插件源码根目录执行：
+
+```sh
+npm install
+npm run typecheck
+npm run build
+npm test
+npm run verify:package
+```
+
+`verify:package` 将当前 tarball 安装到隔离临时目录，检查可发布入口、客户端注册、包内测试和 CLI 语法。CI 在 Windows 的 Node 22、24 上运行。提交前检查 `git status`，确认没有本机凭据、临时审核文件或生成包进入版本控制。
+
+## 当前质量约束
+
+- 本地 Sonar 审核必须先对照参考分支的 Git 差异、项目 `include_paths` 与任务 `files`；漏登文件不得产生“完整审核通过”。
+- `ide-local` 的逐项误报处置只能在当前审核、当前代码指纹上由宿主人工批准；原始告警和结果保留。CI 或上传式服务端 Gate 不接受本地处置。
+- Maven 测试目标在进程成功之外，还需解析到非零 Surefire/Failsafe 测试数。未输出摘要时失败关闭，其他命令按自身回执判断。
+- `items` 默认按 ID 合并；显式 `items_mode=replace` 才允许移除未实施的项目。已完成或有审查记录的项仍保留。
+- 文档只维护项目首页、本 HTML 使用手册和本开发指南，三处描述均以当前功能为准。
+
+## 发布与部署检查
+
+1. 更新 `package.json` 版本，运行上述验证，再检查 `npm pack --dry-run --json` 的文件清单只有当前文档。
+2. 推送提交后发布 npm 包；需要 npm 登录或 WebAuthn 时，保持发布命令等待，由账号持有人完成验证。
+3. 在实际 DSH Web profile 安装刚发布的精确版本并重启，确认侧边栏入口、会话预设和 `dev_task` 能加载。项目 Token 保存在本机凭据中，升级不应把它写进仓库。