@godv61/dsh-task-engine 0.23.0 → 0.23.2

package/docs/assets/workflow-banner.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="400" viewBox="0 0 1280 400" role="img" aria-labelledby="title description">
+  <title id="title">DSH Task Engine · 个人工程流程工作台</title>
+  <desc id="description">标准流程示意：需求评审、设计、开发、交付、代码审核、完成。流程、技能与规则组成个人开发工作台。</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#111b2c"/><stop offset="1" stop-color="#172c35"/></linearGradient>
+    <linearGradient id="accent"><stop stop-color="#86efac"/><stop offset="1" stop-color="#5eead4"/></linearGradient>
+  </defs>
+  <rect width="1280" height="400" rx="24" fill="url(#bg)"/>
+  <path d="M1000 0L1280 280M1120 0L1280 160M920 0L1280 360" stroke="#345454" stroke-opacity=".2" stroke-width="1"/>
+  <g font-family="Segoe UI, PingFang SC, Microsoft YaHei, sans-serif">
+    <rect x="56" y="43" width="30" height="30" rx="8" fill="url(#accent)"/>
+    <path d="M64 58h14m-6-6 6 6-6 6" fill="none" stroke="#14262c" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+    <text x="101" y="65" fill="#d2e8e3" font-size="18" font-weight="600" letter-spacing="2">DSH TASK ENGINE</text>
+    <text x="56" y="141" fill="#f4f7f7" font-size="46" font-weight="650">让每次开发，都有清晰的下一步。</text>
+    <text x="58" y="184" fill="#a6b9bd" font-size="22">DeepSeek Harness 的个人工程流程工作台</text>
+    <text x="58" y="228" fill="#80dcb3" font-size="15" letter-spacing="1">流程预设  /  阶段技能  /  项目规则  /  交付记录</text>
+    <g fill="#1c3440" stroke="#35505a">
+      <rect x="56" y="264" width="168" height="76" rx="13"/><rect x="252" y="264" width="168" height="76" rx="13"/>
+      <rect x="448" y="264" width="168" height="76" rx="13"/><rect x="644" y="264" width="168" height="76" rx="13"/>
+      <rect x="840" y="264" width="168" height="76" rx="13"/><rect x="1036" y="264" width="168" height="76" rx="13"/>
+    </g>
+    <g fill="#e4efee" font-size="21" text-anchor="middle">
+      <text x="140" y="310">需求评审</text><text x="336" y="310">设计</text><text x="532" y="310">开发</text>
+      <text x="728" y="310">交付</text><text x="924" y="310">代码审核</text><text x="1120" y="310" fill="#86efac">完成</text>
+    </g>
+    <g fill="#729a9b" font-size="22" text-anchor="middle"><text x="238" y="310">→</text><text x="434" y="310">→</text><text x="630" y="310">→</text><text x="826" y="310">→</text><text x="1022" y="310">→</text></g>
+    <text x="1204" y="372" fill="#839b9f" font-size="13" text-anchor="end">STANDARD WORKFLOW · 标准流程示意</text>
+  </g>
+</svg>

package/docs/configuration.md

@@ -0,0 +1,49 @@
+# 流程配置
+
+[← 文档导航](README.md)
+
+当前版本通过内置流程和阶段资源绑定配置项目。推荐使用工作台“流程配置”页面；高级用户也可以编辑项目根目录的 `.dsh/eng.json`。
+
+## 选择流程
+
+| flow | 阶段 | 主要特点 |
+| :--- | :--- | :--- |
+| `standard` | 需求评审 → 设计 → 开发 → 交付 → 代码审核 → 完成 | 包含确认、产物、验证、审核与文件范围检查，支持高风险任务。 |
+| `agile` | 需求 → 开发 → 交付 → 审查 | 减少阶段与产物要求，不支持高风险任务。 |
+| `minimal` | 开发 → 交付 | 精简为实施项完成和提交检查点，不支持高风险任务。 |
+
+项目没有配置文件时使用 `standard`；配置文件存在但 flow 缺失或无效时会报错，不会自动忽略错误。
+
+## 追加技能与规则
+
+最小配置如下：
+
+```json
+{
+  "flow": "standard"
+}
+```
+
+`stage_bindings` 的键是当前流程中的阶段名称，值是该阶段需要的技能与规则名称。字段可省略；默认绑定仍然生效。[默认配置示例](../defaults/eng.json)列出了标准流程的绑定。
+
+当前绑定采用追加方式：项目增加的名称会与预设默认项合并去重；取消默认项的勾选不会移除其绑定。内置同名资源优先，使用不同名称来安装自己的资源。
+
+进入阶段后，`dev_task` 披露该阶段的技能名和规则内容。新任务离开阶段前会检查 Harness 的 skill 工具成功加载记录；附加技能还须记录 `skill_result`（技能名、执行场景、真实验收命令回执）。`status.skill_obligations` 中的 `command_receipts_required` 列出需要回执的技能；七个内置技能使用已有的记录、验证、审核和提交操作，无需重复登记附加回执。安装一个技能不会自动执行其中的脚本。
+
+挂在终态（例如“完成”）的技能在进入终态前执行。测试技能通常建议挂在“交付”；现有“完成”绑定也会在审核阶段执行后才放行。标准流程 v2 在审核通过后提交，并核对真实 Git HEAD。修改文件或声明范围后，旧验证回执失效。
+
+资源管理保留项目和个人目录的同名条目，避免来源误标和误操作。绑定仍按名称选择，内置优先；自建同名资源按项目优先于个人解析。技能最终由 Harness 的技能目录加载。
+
+## 哪些内容暂时不能修改
+
+阶段顺序、转移条件、产物必填字段和提交策略由所选预设固定。新建规则可以提供工作指引，但不会改变引擎中的提交消息校验或阶段条件。
+
+可视化自定义流程的范围见[功能规划](roadmap.md)，目前尚未发布。
+
+## 配置与正在进行的任务
+
+新任务记录创建时的完整流程快照，后续按该快照执行。修改项目配置影响之后创建的任务，不会自动迁移进行中的任务。
+
+验证命令还可以由配置中的 `verify_command` 指定；未指定时根据项目类型选择默认命令。当前工作台保存流程时只写入 flow 和 stage_bindings，手写的额外字段可能被移除；使用此项时请检查保存后的文件。这一问题纳入后续配置编辑器改造。
+
+下一步：[资源安装](resource-install.md) · [常见问题](faq.md)

package/docs/development.md

@@ -0,0 +1,53 @@
+# 开发指南
+
+[← 文档导航](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 上运行。具体用例与限制见[测试报告](testing/0.23.0/测试报告.md)；每次功能修改选择相关验证，文档排版调整只需要文档、链接和渲染检查。
+
+## 代码导航
+
+| 位置 | 职责 |
+| :--- | :--- |
+| [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 预设不会被自动覆盖。手工调整前先备份；配套的 enable 脚本也会拒绝覆盖已存在的预设。
+
+## 可选 host 接入
+
+0.23.0 优先使用 Harness 的 `workspaceRegistry.resolveByPath` 获取已登记工作区。旧 host 可以通过插件导出的 `registerWorkspace` 和 `enableStrictWorkspaces` 配置注册目录及严格模式，接口定义见 [src/controller.ts](../src/controller.ts)。注册范围不等于会话身份鉴权；个人本机使用不要求为此改造 Harness。
+
+发布前保持 README、使用手册和实际代码一致；不要将规划中的功能描述为已经可用。

package/docs/faq.md

@@ -0,0 +1,47 @@
+# 常见问题
+
+[← 文档导航](README.md)
+
+## 这是服务器产品吗？
+
+本项目面向本机个人工作台。日常使用重点是选对工作区、明确操作目标、保护现有文件和保留任务记录；多用户服务器的会话权限隔离不属于当前产品的必修项。
+
+## 为什么安装了插件，聊天里没有 dev_task？
+
+安装会添加工作台，但任务工具只在挂载插件 agent 的会话预设中启用。新建会话时选择“工程化开发引擎”，再检查工具是否可用。工作台中的“标准研发”等选项是任务流程，不能代替会话预设开关。
+
+## 能自己增删流程阶段吗？
+
+0.23.0 支持选择三个内置流程和追加阶段资源，不支持自由修改阶段。复制预设、编辑阶段与条件、导入导出已列入[自定义流程方案](roadmap.md)，尚未实现。
+
+## 安装资源后就会自动使用吗？
+
+还需要到“流程配置”选择阶段并挂载资源。任务执行时按阶段披露对应内容；安装行为本身不会执行资源中的脚本。
+
+## 改了流程，原来的任务会变化吗？
+
+任务保存创建时的流程快照。修改项目配置不会自动改变进行中的任务；新任务使用保存后的配置。
+
+## 能移除默认技能、覆盖内置规则吗？
+
+当前预设绑定只能追加，内置资源只读且同名优先。需要自建资源时使用新名称。自定义流程方案会提供自由配置绑定的能力。
+
+## 工具显示验证或审核通过，能完全相信吗？
+
+0.23.1 新建任务的验证需要真实命令回执，要求退出码为 0 且未超时、中止或被沙箱拒绝；代码修改后需重验。旧任务保持原验证约定。附加技能记录加载、命令和场景证据；审核和实施项结论仍由模型记录。命令覆盖是否充分、审核是否准确仍需判断，不能把一个成功退出码当作全部需求已验证。
+
+## 验证命令被沙箱阻止怎么办？
+
+`verify` 和 `skill_result` 默认使用会话沙箱策略。原命令因权限受阻时，可携带 `sandbox_permissions: "danger-full-access"` 与 `justification` 申请单次重试；审批显示实际命令，批准后才执行，不改变后续调用的会话权限。拒绝、取消或缺少审批服务均不运行命令、不写入回执。不要用另一条简单命令替代原验收。详见验证技能说明。
+
+## 本地提交钩子有什么作用？
+
+它在普通 git commit 时检查任务、阶段、消息和文件范围。`--no-verify`、替换 hooksPath 或直接修改本地数据仍可能绕过检查；项目需要更强的提交约束时，应结合自己的 CI 和人工审核。
+
+## hash 和版本号能防止任意篡改吗？
+
+hash 检查流程快照是否与保存的摘要一致，文件版本检查阻止并发覆盖。任务 JSON 没有签名，具有文件修改权限的人可以同时修改内容与摘要；它们不提供独立防篡改认证。
+
+## 为什么 GitHub 上的 HTML 手册显示源码？
+
+GitHub 文件页不会直接作为网页运行 HTML。下载 [manual.html](manual.html) 后用浏览器打开，或先阅读本站点内的 Markdown 指南。

package/docs/getting-started.md

@@ -0,0 +1,51 @@
+# 安装与启用
+
+[← 文档导航](README.md)
+
+本指南适用于已在本机使用 DeepSeek Harness 的用户。安装后，你会获得一个“工程流程”工作台和一个“工程化开发引擎”会话预设。
+
+## 1. 安装插件
+
+确认 pnpm 可用，将插件添加到所用的 Web profile。以下命令使用 `web`。
+
+```sh
+dsh plugin --profile web add @godv61/dsh-task-engine
+```
+
+如果你正在 Harness 源码目录开发，使用：
+
+```sh
+pnpm dsh plugin --profile web add @godv61/dsh-task-engine@0.23.0
+pnpm dsh web --no-open
+```
+
+已有 Web 进程时，先关闭该进程再启动，避免端口冲突。通过 `dsh plugin` 安装会将插件加入对应 profile；仅在任意目录执行 `npm install` 不会完成工作台挂载。
+
+## 2. 检查安装结果
+
+重启后检查两个位置：
+
+- 侧边栏出现 **工程流程**，打开后可以选择工作区。
+- 新建会话时，可以选择 **工程化开发引擎**。
+
+没有看到入口时，先确认安装和启动使用的是同一个 profile，再检查启动日志中的插件加载错误。命令报找不到 pnpm 时，需要先准备好 pnpm 环境。
+
+## 3. 配置第一个项目
+
+1. 在工作台顶部选择工作区。
+2. 进入“流程配置”，按任务复杂程度选择标准研发、敏捷轻量或纯代码。
+3. 如需自己的技能或规则，在对应页面安装，再回到流程配置挂载到阶段。
+4. 保存配置，在使用“工程化开发引擎”预设的会话中描述任务。
+
+后续在“任务台账”查看阶段、实施项与验证审核记录。项目初始化会管理根目录的 `AGENTS.md`：先查看或生成草稿，再确认保存。
+
+## 两种预设的区别
+
+| 位置 | 决定什么 |
+| :--- | :--- |
+| 会话中的“工程化开发引擎” | 是否启用 `dev_task`、配套技能和工程人设。 |
+| 工作台中的三个流程预设 | 任务经过哪些阶段、每一步需要满足什么条件。 |
+
+如果切换到未挂载插件 agent 的其他会话预设，该会话不会启用这套任务工具；侧边栏工作台仍可使用。
+
+下一步：[配置流程](configuration.md) · [安装资源](resource-install.md) · [常见问题](faq.md)

package/docs/manual.html

@@ -35,7 +35,7 @@
   <header class="hero">
     <p class="eyebrow">DSH · ENGINEERING DELIVERY ENGINE</p>
     <h1>工程化交付引擎 使用手册</h1>
-    <p class="lead">这是一套装在 DeepSeek Harness 里的工程流程约束。它把「需求评审 → 设计 → 开发 → 交付 → 代码审核」做成硬门槛：阶段不能跳、关键节点必须人来拍板、验证和提交都被机械检查。团队只选一套流程，再给每个节点挂上合适的 skill 和 rule。</p>
+    <p class="lead">这是一套装在 DeepSeek Harness 里的工程流程约束。它把「需求评审 → 设计 → 开发 → 交付 → 代码审核」做成硬门槛：阶段不能跳、关键节点必须人来拍板、验证和提交都被机械检查。在个人工作台里选一套流程，再给每个节点挂上合适的技能和规则。</p>
     <div class="badges">
       <span class="badge">选流程预设即可</span>
       <span class="badge">standard / agile / minimal</span>
@@ -48,6 +48,7 @@
   <div class="layout">
     <nav aria-label="目录">
       <strong>目录</strong>
+      <a href="https://github.com/godv61/dsh-task-engine#readme">项目首页 ↗</a>
       <a href="#overview">1. 工作原理</a>
       <a href="#install">2. 安装与启用</a>
       <a href="#structure">3. 文件与目录</a>
@@ -74,14 +75,14 @@
       → 需求评审 · requirement-analysis
       → 设计     · solution-design
       → 开发     · code-implement
-      → 交付     · code-verify + code-commit
-      → 代码审核 · code-review</code></pre>
+      → 交付     · code-verify
+      → 代码审核 · code-review + code-commit</code></pre>
         <div class="callout">
           <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时，才触发 <code>dev_task</code> 和这套门禁；换到别的预设，流程完全不介入。</p>
         </div>
         <p>三样东西分工明确：<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」，<strong>Skill</strong> 决定「这一站做什么」，<strong>Rule</strong> 决定「这一站守什么」。任务状态单独落盘，负责「跨会话恢复到哪一步」。</p>
         <div class="callout warn">
-          <p><strong>诚实边界：</strong>阶段流转、提交格式、文件范围、消息里的任务绑定、流程快照 hash、钩子完整性、敏感路径风险策略是<b>代码硬校验</b>（不匹配直接拒绝）；<b>高风险任务的「验证通过」也是真实命令回执</b>——引擎实际运行 <code>verify</code> 命令、取退出码（<code>exit_code === 0</code> 且非超时/中止）才放行，不是模型自报。仍属模型自报、需人工或 CI 兜底的是：常规风险的验证声明、「评审通过」「实施项完成」，以及回执命令本身的覆盖面。只有「需求确认」「方案确认」两扇门由人工批准点亮，风险降级（high_risk → standard）也由人工批准。</p>
+          <p><strong>诚实边界：</strong>阶段流转、提交格式、文件范围、消息里的任务绑定、流程快照 hash、钩子完整性、敏感路径风险策略是<b>代码硬校验</b>（不匹配直接拒绝）；<b>高风险任务的「验证通过」也是真实命令回执</b>——引擎实际运行 <code>verify</code> 命令、取退出码（<code>exit_code === 0</code> 且非超时/中止）才放行，不是模型自报。仍属模型自报、需人工或 CI 兜底的是：旧任务的常规风险验证声明、「评审通过」「实施项完成」，以及回执命令本身的覆盖面。只有「需求确认」「方案确认」两扇门由人工批准点亮，风险降级（high_risk → standard）也由人工批准。</p>
         </div>
       </section>
 
@@ -192,6 +193,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
       </section>
 
       <section id="configure">
+        <p>当前版本支持三个内置流程及追加阶段资源。可视化自定义流程处于规划阶段，尚未发布。</p>
         <h2>7. 配置流程与挂载</h2>
         <p>侧边栏点「工程流程」打开工作台，五个标签页：<strong>项目初始化 / 流程配置 / 任务 / 技能 skill / 规则 rule</strong>，默认落在「项目初始化」（详见第 8 节）。日常配流程只需在「流程配置」页做两件事：</p>
         <ol>
@@ -263,13 +265,14 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
             <tbody>
               <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全，且<b>人点「允许」确认需求</b></td></tr>
               <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全，且<b>人点「允许」确认方案</b></td></tr>
-              <tr><td>开发</td><td>逐项实现，每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done（每项带两阶段评审）</td></tr>
-              <tr><td>交付</td><td>验证、记证据，按门禁提交</td><td>验证通过（高风险必须真实命令回执，退出码 0）</td></tr>
-              <tr><td>代码审核</td><td>评审变更，落「评审记录」</td><td>结论通过且字段填全</td></tr>
+              <tr><td>开发</td><td>独立交付可派子代理，小修正可由主代理实施；每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done（每项带两阶段评审）；已有项可省略标题，改已审核标题须显式重开</td></tr>
+              <tr><td>交付</td><td>执行验证、记录证据</td><td>新任务必须真实命令回执，退出码 0，未超时、取消或被沙箱拒绝</td></tr>
+              <tr><td>代码审核</td><td>评审变更，执行终态技能，受控提交</td><td>结论通过、字段填全、技能义务完成且真实 Git 提交已回写</td></tr>
               <tr><td>完成</td><td>收尾</td><td>—</td></tr>
             </tbody>
           </table>
         </div>
+        <p>新任务离开阶段前检查绑定技能是否通过 skill 工具成功加载；附加技能需通过 <code>skill_result</code> 记录执行场景与真实验收命令；状态中的 <code>command_receipts_required</code> 列出这些技能，七个内置技能无需重复登记。挂在“完成”的技能在前一阶段执行。命令成功只证明该命令通过，不证明测试覆盖完整。审核改动后须重跑验证。旧任务继续使用冻结快照。</p>
         <h3>贯穿全程的硬规则</h3>
         <ul>
           <li>阶段是硬状态：status 说你在哪，就只做那一步，绝不倒带重走、绝不跳。</li>
@@ -326,7 +329,7 @@ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
             </tbody>
           </table>
         </div>
-        <p>提交消息要求 <code>【模块】【TASK】做了什么</code>，且只提交任务 <code>files</code> 范围内的文件。要彻底封死模型绕过 <code>dev_task</code> 直接 <code>git commit</code>，给仓库装一道机械钩子：</p>
+        <p>内置流程的提交消息要求 <code>【任务 id】【TASK】结果说明</code>，第一段填写当前任务 id，第二段使用 <code>dev_task status</code> 返回的 <code>commit.label</code>；自定义格式由任务冻结流程决定。只提交任务 <code>files</code> 范围内的文件。要彻底封死模型绕过 <code>dev_task</code> 直接 <code>git commit</code>，给仓库装一道机械钩子：</p>
         <pre><code>dev_task operation=install_hook   # 装入 .git/hooks/commit-msg，装上后任何 git commit 都被同一套规则校验
 dev_task operation=verify_hook    # 随时比对安装钩子与内置门禁的 hash，被替换/篡改立即报错</code></pre>
         <p><strong>钩子的额外硬校验（0.21/0.22）：</strong>① 任务记录的流程快照带 SHA-256 hash，被手改过的快照一律拒绝提交；② 触及敏感路径（<code>.env</code>、credentials、secrets、<code>.git</code>；<code>.dsh</code> 的任务记录与流程配置由快照 hash 与豁免保护，项目级 rules/skills 属常规内容）的提交，要求任务为 <code>high_risk</code> 且验证有真实命令回执，否则拒绝；③ 删除、类型变换、重命名的旧·新路径都受范围检查。</p>
@@ -354,10 +357,11 @@ risk_level: high_risk   // 涉及鉴权，验证要加证据
 
 ④ 交付
    - 验证：跑鉴权用例，`verify` 传真实命令（high_risk 由引擎取退出码判定）。
-   - 提交：【模块】【TASK】查询接口增加权限校验（只含本任务文件）
+   - 文件改动后必须重新验证，旧回执失效。
 
 ⑤ 代码审核
    - 结论：通过 · 问题：无
+   - 执行挂在完成阶段的附加技能，再提交并回写真实 hash。
 
 ⑥ 完成</code></pre>
         <p>这类任务不应因为「以后可能复用」扩展成多层架构，也不应把推荐项自动当成验收条件。</p>
@@ -378,9 +382,12 @@ risk_level: high_risk   // 涉及鉴权，验证要加证据
         <details><summary>Remote 如何限制工作区？</summary><div>有 <code>workspaceRegistry.resolveByPath</code> 的 Harness 使用主机注册目录；未注册路径拒绝。旧主机保留绝对路径和系统目录检查，并提供严格注册 API。工作区注册不等于当前会话授权；共享多用户部署仍需要调用上下文和主机权限边界。</div></details>
         <details><summary>dev_task 写文件被沙箱拒绝（file access denied）怎么办？</summary><div>沙箱按调用策略放行写入，偶发的越界误判可用一次性升级重试：同一操作加 <code>sandbox_permissions: "workspace-write"（或 "danger-full-access"）</code> 并配 <code>justification</code>（一句话说明原因），升级需要<b>人工批准</b>；无审批服务时直接拒绝。日常任务记录写入默认已在会话工作区内放行，通常无需升级。</div></details>
         <details><summary>「完成」等于上线了吗？</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过；上线、合并、发布需人另行决定。</div></details>
-        <p class="stamp">版本 0.23.0 · 系统文件选择与安装预览 · 工作台交互改进 · 最后更新：2026-09-15</p>
+        <p>状态查询中的 <code>evidence_blockers</code> 列出过期验证和附加技能回执；<code>commit.allowed</code> 同时检查这些阻塞及技能执行义务。<code>legal_next</code> 是流程定义的候选去向，不表示所有门禁已通过。</p>
+        <details><summary>记录需求时提示字段不存在怎么办？</summary><div>先读取 <code>status.artifact_requirements</code>，按当前阶段列出的字段填写。标准需求为 <code>scope</code> 和 <code>acceptance_criteria</code>，敏捷流程只有 <code>scope</code>。疑问、假设或待确认取舍写入字段正文，不新增字段名。错误输入整次不保存，修正后再提交；不需要修改流程配置或历史任务记录。</div></details>
+        <details><summary>验证命令被沙箱阻止怎么办？</summary><div><code>verify</code> 与 <code>skill_result</code> 默认使用会话权限。原命令被沙箱阻止后，用相同命令和 <code>sandbox_permissions: "danger-full-access"</code>、<code>justification</code> 申请单次重试。审批显示命令，批准后才执行；拒绝、取消或审批不可用时不执行、不写回执。授权只对本次调用生效，不改变会话权限。以本次回执的实际模式和退出码判断结果。</div></details>
+        <p class="stamp">版本 0.23.2-rc.1 · 验证命令审批修复候选 · 最后更新：2026-09-17</p>
       </section>
     </main>
   </div>
 </body>
-</html>
+</html>

package/docs/release-0.23.0.md

@@ -1,5 +1,7 @@
 # 0.23.0 修改清单与发布说明
 
+[← 文档导航](README.md)
+
 ## 本次实现
 
 | 分类 | 问题 | 处理 |
@@ -23,11 +25,7 @@
 
 ## 后续建议
 
-1. Harness 层：Typert 注入会话身份与授权 workspace；可信持久化签名与 CI 验证交付回执。注册工作区不能替代会话权限。
-2. 大包导入：改为分块上传、取消与进度、服务端临时包 TTL、并发与内存预算；当前 100 MB 是代码上限，不是远程实测容量承诺。
-3. 资源维护：记录来源与版本、显式升级/差异预览、备份与恢复；当前同名拒绝覆盖。
-4. 产品完善：全量中英语言字典、更多屏幕/浏览器/辅助技术验证，台账分页与完整任务数据 schema。
-5. 市场材料：公开源码、`dsh-plugin` topic、真实截图；符合仓库至少一天的条件后提交收录 PR。
+后续优先讨论可视化自定义流程、资源导入反馈和资源维护。详细范围见[功能规划](roadmap.md)。产品定位为个人本机工作台，会话级服务器隔离不列为当前版本必修项。
 
 ## 验证与发布
 

package/docs/release-0.23.1.md

@@ -0,0 +1,58 @@
+# 0.23.1：真实项目回归后的流程修复
+
+[← 文档导航](README.md)
+
+本版集中修复真实开发中暴露的资源来源、技能执行、审核记录、验证与提交问题，并改善错误提示。仍使用三个预设流程，不包含自定义流程编排。
+
+## 问题与处理
+
+| 问题 | 处理方法 | 约束性质 |
+| --- | --- | --- |
+| 项目与个人同名技能被覆盖，界面来源误标 | 管理目录保留全部来源，绑定按名称去重；项目同名规则优先于个人规则 | 代码修复；技能正文最终解析由 Harness 负责 |
+| Windows 的 BOM/CRLF 导致内置技能加载失败 | 技能注册、列表和正文读取兼容两种格式 | 代码修复及安装包测试 |
+| 技能只披露而不执行，终态技能来不及参与验收 | 新任务检查成功的 skill 工具事件；附加技能登记真实命令回执；终态绑定在进入完成前执行 | 流转和提交门禁 |
+| 内置技能被误当附加技能，重复登记导致多余阻塞 | status 列出 command_receipts_required；可选内置回执不升级为额外门禁 | 代码修复 |
+| 更新实施项丢失审核；模型重写旧标题使审核消失 | 同 ID/标题保留审核，已有项可省略标题；已审核项改名须明确重开 | 写入前校验 |
+| 子代理开工后任务项仍显示待办 | dispatch 提前登记并激活唯一进行项；重派清除旧审核 | 计划记录，不能证明子代理实际执行 |
+| 验证未继承调用会话的权限与取消状态 | 验证传递会话沙箱策略、取消信号，保存退出码、超时和沙箱结果 | 代码修复 |
+| 审核后错过提交窗口，完成缺少实际 Git 证据 | 新标准流程 v2 审核后提交；核对真实 HEAD、摘要及文件，回写哈希后完成 | 新任务门禁 |
+| 文件变化后仍沿用旧测试结论 | 回执关联声明文件摘要，变化后重验 | 流转和提交门禁 |
+| status 显示允许提交，实际被过期回执拒绝 | status.commit.allowed 同时检查技能与回执，evidence_blockers 列出过期原因 | 状态与执行校验一致 |
+| 模型发明记录字段，需求写入被拒绝 | status.artifact_requirements 主动列出当前阶段允许字段和缺项；错误附恢复说明且不保存 | 保持严格校验，改善可发现性 |
+| 小修正也强制派子代理，失败后重复换命令试探 | 小修正允许主代理实施，仍需审核与验证；权限拒绝走正式审批或报告阻塞 | 技能指引，不是硬拦截 |
+| 猜测接口字段、混淆模拟测试与真实联调 | 设计核对原始契约与实际组件；报告区分对象、执行状态及证据来源 | 技能指引和人工审核 |
+
+## 新的状态信息
+
+标准流程在需求阶段返回的字段提示示例：
+
+```json
+{
+  "artifact_requirements": [
+    {
+      "id": "requirement",
+      "name": "需求说明",
+      "fields": ["scope", "acceptance_criteria"],
+      "missing_fields": ["scope", "acceptance_criteria"]
+    }
+  ]
+}
+```
+
+字段来自任务冻结流程，不硬编码同一套字段给所有预设。例如敏捷流程只有 scope；疑问和技术取舍写在已有字段正文，不增加字段名。无记录要求的阶段返回空列表。查询不会更改台账。
+
+`legal_next` 是流程图中的候选去向，不表示门禁已经通过。`commit.allowed` 是阶段、技能和回执层面的提交资格；实际 commit 仍会检查此次输入的文件范围、摘要及所回写的 Git 证据。
+
+## 验证结果与边界
+
+自动化及安装包结果见 [0.23.1 测试说明](testing/0.23.1/测试报告.md)。候选版 rc.3 在一项真实需求中完成了需求/方案审批、8个实施项双阶段审核、测试技能执行、真实验证和本地提交回写。rc.5 与本次字段提示修复有定向回归及包验证，未再次执行整轮真实需求。
+
+该实机过程包含观察方纠正契约、复现异步缺陷和修订报告的干预，不能称为完全自主交付。业务结构树真实联调仍有环境与请求差异待核实，不能用插件本地闭环证明业务端到端可用。
+
+以下问题不由本版解决：Harness 内的文件删除权限限制、同步子代理反馈传播、模型服务鉴权/额度、旧业务项目的 Node/webpack 和测试运行器兼容问题。插件保留失败证据并指导正式恢复，不修改宿主权限系统或模型凭证。
+
+命令退出码成功不证明覆盖充分；本地记录不是防篡改存储；声明文件摘要不涵盖数据库、远程服务和未声明文件。报告准确性与代码质量仍需审核。
+
+## 升级与后续重跑
+
+升级安装后重启 Harness。既有任务沿用冻结流程及原执行约定，不自动迁移到新标准流程；新的执行证据门禁用于带 execution_version=1 的任务。需要比较插件效果时，归档上一轮任务和业务差异，在独立测试项目中将本需求改动恢复到同一基线，再用新会话完整重跑。保留插件修复及历轮证据，不能为重跑无差别清理用户文件。

package/docs/release-0.23.2.md

@@ -0,0 +1,21 @@
+# 0.23.2 发布说明
+
+[← 文档导航](README.md)
+
+本版修复验证命令的单次权限审批，并统一提交消息指引。
+
+## 验证命令在批准后执行
+
+0.23.1 的 `verify` / `skill_result` 先运行命令，再为写入任务台账申请权限；即使用户批准 `danger-full-access`，测试命令仍可能在 `workspace-write` 下失败。实机中，`npm test` 的 Node 子进程因此报 `spawn EPERM`，任务无法完成交付验证。
+
+本版先校验参数并取得批准，再将批准模式传给本次验证命令。审批展示实际命令与工作区；回执保存复用同一次批准。拒绝、取消或审批服务不可用时不执行命令、不写台账。后续调用继续使用原会话策略。`verify` / `skill_result` 的调用字段保持兼容。
+
+## 提交指引与引擎一致
+
+内置流程的第一组括号填写当前任务 id，第二组使用 `status.commit.label`，例如 `【DSH-REG-R03】【TASK】实现批次统计 CLI`。规则与手册不再把模块名写成第一段；自定义格式仍由任务冻结流程决定。
+
+## 验证范围与管控边界
+
+实机测试使用独立 `dshtest` 仓库与标准流程，由 DSH 编写业务代码，观察者审阅审批、执行独立验收并修复插件。每轮业务代码、任务台账与会话日志保留在本地归档，完成轮次回退到同一空业务基线。结果与干预见[测试报告](testing/0.23.2/测试报告.md)。本次不代表 QMS 页面、数据库或生产环境验收。
+
+插件控制 `dev_task` 的阶段、证据与提交登记；通用文件编辑工具不会逐次经过该状态机，模型也可能错误解读证据。直接 Git 提交的机械约束需要安装[提交钩子](manual.html)，本次独立业务轮次验证的是通过 `dev_task` 完成的受控路径。不要把技能指引等同于对所有工具调用的强制拦截。

package/docs/resource-install.md

@@ -1,18 +1,62 @@
-# 安装技能和规则
+# 技能与规则安装
 
-在 Harness 打开「工程流程」，先选择目标工作区，再进入「技能」或「规则」。
+[← 文档导航](README.md)
 
-1. 点「安装技能」，在系统文件选择器中选择技能文件夹；或点「安装规则」选择一个 Markdown 文件。
-2. 查看预览中的名称、正文、目标路径、文件数、体积和冲突提示。
-3. 选择项目或个人范围。切换范围后重新预览。
-4. 点「确认安装」。成功后列表刷新；同名资源拒绝覆盖。新安装的技能仍需在「流程配置」中挂到对应节点。
+技能用于复用工作方法，规则用于描述项目约定。打开工作台后，先选择目标工作区，再进入“技能”或“规则”。
 
-技能根目录包含 UTF-8 的 `SKILL.md`，frontmatter 提供单行 `name` 和 `description`。名称使用小写字母、数字和连字符，例如 `code-check`。规则名称来自 `.md` 文件名，同样采用上述格式。支持 UTF-8 BOM 和 CRLF；其他文本编码请先转换。技能的脚本与附件保留原始字节，安装不会执行脚本。
+## 安装四步
 
-项目范围写入所选工作区 `.dsh/skills` 或 `.dsh/rules`；个人范围写入 `$DSH_HOME/skills` 或 `$DSH_HOME/rules`（默认用户主目录下 `.dsh`）。删除确认框显示实际路径；删除不经过回收站。
+1. **选择资源**：点“安装技能”选择文件夹；点“安装规则”选择一个 `.md` 文件。
+2. **检查预览**：查看名称、正文、文件数、体积、目标路径与同名冲突。
+3. **选择范围**：选择项目或个人，改变范围后会重新预览。
+4. **确认安装**：成功后列表刷新，再到“流程配置”把资源挂到对应阶段。
 
-浏览器选择器访问浏览器所在电脑的文件；高级目录模式访问 Harness 主机的目录。两者在远程部署中可能不是同一台电脑。浏览器不会暴露源文件绝对路径或符号链接元数据，不能宣称浏览器上传也完成了源链接检查。
+预览不写入目标目录。已有同名资源时拒绝覆盖；请先检查现有内容，或给新资源使用不同名称。
 
-导入限制为 1000 文件、100 MB 总量、20 MB 单文件、20 层相对路径；清单和规则正文最多 1 MB。自动排除 `node_modules`、`.git`、`__pycache__`、`.venv`、`venv`、`.cache` 和 `.DS_Store`。禁止路径穿越、Windows ADS、保留名称、大小写重名及文件/目录冲突。高级目录扫描拒绝链接和特殊文件。合法包的上传仍会在内存中编码及校验，大包经远程网关的容量和并发性能未完成压力测试。
+## 准备文件
 
-预览不写入目标。确认时重新校验内容和目标的摘要，并使用独占创建避免覆盖现有资源；失败时清理本次新建的技能目录。此机制不构成针对具有同等主机文件权限的恶意进程的完整隔离。
+技能文件夹中需要 UTF-8 编码的 `SKILL.md`，frontmatter 包含单行 `name` 和 `description`。名称使用小写字母、数字和连字符，例如 `code-check`。脚本、模板和二进制附件可与清单一同安装。
+
+规则是一个 UTF-8 编码的 Markdown 文件，名称来自文件名，使用同样的命名规则，例如 `code-check.md`。支持 BOM 与 CRLF；其他编码请先转换。安装不会执行脚本。
+
+## 选择存放位置
+
+| 范围 | 技能 | 规则 |
+| :--- | :--- | :--- |
+| 项目 | 工作区 `.dsh/skills` | 工作区 `.dsh/rules` |
+| 个人 | `$DSH_HOME/skills` | `$DSH_HOME/rules` |
+
+`DSH_HOME` 默认是用户主目录下的 `.dsh`。删除确认框显示实际路径；确认删除后不经过回收站。内置资源只读，项目和个人资源可以查看、编辑和删除。
+
+## 格式与大小限制
+
+| 项目 | 上限 |
+| :--- | ---: |
+| 技能文件数量 | 1,000 |
+| 总体积 | 100 MB |
+| 单文件 | 20 MB |
+| 相对目录深度 | 20 层 |
+| SKILL.md 或规则正文 | 1 MB |
+
+常见缓存目录会自动排除，包括 `node_modules`、`.git`、`__pycache__`、`.venv`、`venv`、`.cache` 和 `.DS_Store`。不接受越级路径、Windows ADS、保留名称、大小写重名以及文件/目录冲突。
+
+## 安装失败时
+
+| 提示或现象 | 处理方式 |
+| :--- | :--- |
+| 缺少 SKILL.md 或有多个技能 | 直接选择一个技能的根文件夹。 |
+| 名称无效 | 修改源清单的 name 或规则文件名，再重新选择。 |
+| 同名冲突 | 取消安装，检查现有资源；需要共存时使用不同名称。 |
+| 超过限制 | 移除不需要的构建产物与大文件，再重新选择。 |
+| 预览后内容或目标变化 | 重新预览后再确认。 |
+
+确认时会重新校验内容和目标摘要，并使用独占创建避免覆盖。技能写入中途失败时，会清理本次新建的技能目录。
+
+<details>
+<summary>高级：主机目录模式与上传限制</summary>
+
+系统选择器读取浏览器所在电脑的文件；高级目录模式读取 Harness 进程所在电脑的目录。本机个人使用时通常是同一台电脑。主机扫描拒绝符号链接、junction 和特殊文件；浏览器文件 API 不提供源链接元数据。
+
+上传内容在内存中编码、校验。100 MB 是代码限制，不是已经完成大包和并发压力测试的容量承诺；分块、进度和取消见[功能规划](roadmap.md)。
+
+</details>

package/docs/roadmap.md

@@ -0,0 +1,33 @@
+# 功能规划
+
+[← 文档导航](README.md)
+
+本页记录讨论中的方向，不代表已发布功能。当前 npm 版本为 0.23.0；实现范围在开始编码前确认。
+
+## 优先讨论：自定义流程
+
+三个内置流程继续开箱即用，用户可以复制成自己的模板，通过可视化表单配置：
+
+| 能力 | 建议第一版范围 |
+| :--- | :--- |
+| 阶段 | 添加、重命名、删除和调整顺序。 |
+| 条件 | 为阶段设置人工确认、实施完成、验证、审核或必填产物。 |
+| 资源 | 自由添加、替换和移除阶段技能/规则。 |
+| 产物 | 配置名称与必填字段。 |
+| 提交 | 配置提交阶段、方式、格式与文件范围要求。 |
+| 复用 | 保存到项目，支持配置导入/导出。 |
+
+建议采用左侧阶段列表、右侧配置、底部流程预览。第一版以顺序流程为主；分支、循环和并行需要单独设计证据失效和任务恢复逻辑。
+
+运行中的任务保持原流程快照。多次验证、审核和人工确认应绑定到各自阶段，不能自动复用前一个阶段的通过状态。配置保存还应保留 verify_command 等已有项目字段。
+
+## 后续体验方向
+
+- 资源导入：文件选择取消、大包进度、分块上传与取消。
+- 资源维护：来源与版本记录、升级差异预览、备份和恢复。
+- 工作台：未保存内容保护、台账扩展、语言与可访问性完善。
+- 项目展示：真实工作台截图、案例和插件市场收录。
+
+## 产品范围
+
+本项目服务本机个人开发工作台。多用户服务器的会话权限架构不列为当前版本的必修项。日常改进优先解决工作区目标清晰、文件误操作、任务连续性和操作反馈。

package/docs/testing/0.23.1//346/265/213/350/257/225/346/212/245/345/221/212.md

@@ -0,0 +1,34 @@
+# 0.23.1 发布验证
+
+[← 发布说明](../../release-0.23.1.md)
+
+日期：2026-09-16。对象：插件 0.23.1。此文记录插件验证，不等同业务项目端到端验收。
+
+## 检查范围
+
+| 检查 | 内容 | 状态 |
+| --- | --- | --- |
+| 新字段提示回归 | 两个新增用例先失败，修复后通过；错误输入不写入台账，提示按冻结流程变化 | 通过 |
+| 流程回归 | 15项：审核保留、标题保护、派工状态、任务发现、技能回执、沙箱透传、Git回写、过期提示、字段披露及技能来源/注册 | 通过 |
+| host/client 类型检查 | 两个 TypeScript 编译面 | 通过 |
+| P0 与资源测试 | 126项基础检查、18项资源测试 | 通过 |
+| 安装包黑盒 | 打包、干净项目安装、入口导入、客户端注册、包内测试和启用脚本语法 | 通过 |
+
+流程用例名称及断言位于包内 `.workflow-test.mjs`，资源用例位于 `.resource-test.mjs`，基础断言位于 `.p0-test.mjs`。发布前执行日志保留在发布工作区。`npm run typecheck` 与 `npm run verify:package` 均退出0，安装包检查包含实际安装后的包内测试。逐项运行明细见[自动化测试明细](自动化测试明细.md)。
+
+## 新增用例覆盖
+
+1. 当前需求阶段披露 scope/acceptance_criteria；返回准确缺项；未定义字段拒绝时整个记录保持不变；修正字段后可继续。
+2. 敏捷流程仅披露 scope，设计阶段披露自身字段，无记录阶段返回空列表。字段提示从冻结配置读取，不改变历史任务。
+
+新增测试在修复前均失败，避免只断言实现自身返回成功。状态查询一致性、真实提交、验证过期及失败技能等既有回归一并执行。
+
+## 实机证据的适用范围
+
+rc.3 在真实业务需求中走完同一任务的审批、8项实施审核、测试技能、真实命令验证、范围受控本地提交及哈希回写。新增文档后过期的验证和测试技能回执实际阻止过提交，重验后恢复。rc.5 的状态提示修复及本次字段披露有自动化证据；由于用户暂停业务重跑，没有本版完整业务重跑证据。
+
+实机包含观察方干预，不算完全自主。业务结构树真实联调未通过；额外布局与虚拟滚动需求未实施。没有以这些未完成事项宣称产品业务全通过。
+
+## 发布限制
+
+仅已执行检查可标通过。包测试使用模拟宿主与干净安装，不能覆盖所有 Harness 版本、模型行为或共享部署权限场景。技能指引不能强制模型报告内容准确，所有完成结论仍须结合证据审查。