@godv61/dsh-task-engine 0.24.0 → 0.26.0

package/docs/BRIEF-FOR-REVIEW.md

@@ -1,163 +1,163 @@
-# 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，插件该怎么定位（追最新？固定版本？）
+# 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 模板、语义化版本、变更日志规范、安全策略、行为准则？

package/docs/CHANGELOG.md

@@ -4,6 +4,55 @@
 
 按版本查阅功能变化。当前使用方式以[项目首页](../README.md)和使用指南为准；历史条目中的实现方式、限制与测试数量可能已被后续版本替代。
 
+## 0.26.0
+
+- 修复旧内联阶段绑定与新 `skill_profiles` 同时存在时，技能档案规则未展开、同一技能跨节点误报冲突的问题；明确的技能档案现在覆盖旧内联副本，并在任务创建时冻结实际生效的规则。
+- 技能规则改为项目级 `skill_profiles`，节点在 `.dsh/eng.json` 中只保存 `skill_refs`。旧内联绑定继续读取；没有明确技能档案时，同一技能在不同节点的规则或证据冲突会明确报错，保存时转换为单一配置。
+- “技能”页可集中编辑技能规则和完成凭证。流程页只选择技能，并可查看当前节点的有效规则；修改同一技能的配置会同步其所有节点引用。
+- 任务快照以资源类型、来源、名称定位技能和规则，避免同名资源正文串用；任务创建时拒绝缺失的绑定资源，并在运行时披露冻结的技能与规则正文。
+- `complete` 检查终态技能、证据与缺失规则，完成后禁止继续修改任务（可通过 `revise` 返工）。`status` 增加完成状态和完成阻塞原因。
+- `manual` 技能证据通过宿主人工审批记录，不再强制执行 shell；`artifact` 证据要求该阶段有产物定义且必填字段完整。
+- `commit_required: false` 同时取消离开提交检查点的强制提交要求。返工会使受影响阶段的技能结果失效。
+- 增加配置保存读回、同名资源、人工审批、终态阻塞及返工证据回归测试。
+- 工作台改用更宽的自适应布局；流程页用双栏穿梭框绑定技能，技能卡片和已绑定技能都可打开右侧规则配置抽屉，窄屏自动改为纵向布局。
+
+## 0.25.0
+
+针对 2026-09-24 复评的改造。**这是一个破坏性版本**：预设不再自带任何技能、产物或提交格式，`SkillBinding` 新增 `evidence` 字段，敏捷流程的门禁语义与版本号都变了。核心是落实产品原则：**流程只控制状态，业务方法由用户配置，Rule 真正归属 Skill。**
+
+已有项目不会因此失效，但**行为会变**：预设不再提供内置技能，所以一个从未采用推荐配置的项目，其节点将没有绑定。升级后打开工作台点一次「采用推荐配置」即可获得与升级前等价的起点，此后完全由你控制——删除的不再补回，升级也不覆盖。已有任务按各自的冻结快照执行，不受影响。
+
+### 流程骨架与可选推荐配置（破坏性）
+
+预设此前把技能、提交规则和产物字段烘焙进解析结果，`mergeBindings` 又只做**追加**——于是内置技能无法移除，而用户给内置技能配自己的规则时，条目会因引用已存在被整个跳过，静默保留预设规则。工作台里选择流程也会一并写入这些内容，等于选择流程即接受内置工作方法。
+
+现在分成两层：
+
+- **骨架**只含阶段图、每条边的守卫，以及提交规则中属于**流程控制**的那一半：何时需要提交、哪个节点是检查点、是否强制文件范围。最后一项留在骨架上是有意的——高风险检查读它作为安全底线，不能因为用户没采用推荐配置就消失。
+- **推荐配置**（`FlowRecommendation`）单独存放技能绑定、提交**文本**约定、产物字段与审查深度。
+- `adoptRecommendation()` 只在用户显式请求时写入。这是一次性动作：此后这些值就是用户的普通配置，用户删除的值不会回来，升级也不覆盖。
+- `resolveFlow` 逐字采用项目配置。用户没配的节点就是没有绑定，这是合法状态，不是待补齐的空缺。
+- 工作台新增「采用推荐配置」按钮；**选择流程不再写入任何绑定**。
+
+### 冻结真正接入执行链
+
+此前 `flow.resources` 只**存档**正文，`status` 与阶段披露仍走 `readRuleAt` 读实时文件——改一条规则会无声改变进行中任务所遵循的内容，正是快照本该阻止的不稳定。现在解析优先使用冻结正文，并把漂移**报告**出来：源被改动记为 `stale_source_rules`（source edited），源被删除也记为漂移而非缺失——任务手里已有内容，说它缺失是错的。没有快照的旧任务继续读实时文件并把删除报为缺失，两条路径可区分，不会互相悄悄退化。
+
+### 缺失资源、节点结果与完成条件改为真正阻塞
+
+- **规则无法解析则不可推进**。`missing_rules` 以前只披露不阻塞，删掉绑定规则仍能推进——阶段在缺少既定约束的情况下走完，而记录看起来正常。判定实现为引擎里的纯函数，工具与 hook 从同样输入得到同样结论。
+- **完成检查流程声明的节点结果**。此前只查「是否站在终态、实施项是否完成、有无提交」，于是一个在进入终态的路上声明了 `review_passed` 的流程，只要**到达**就满足——审核被 blocked 仍能完成。要求由 `terminalRequirements` 从流程推导，没声明验证门禁的流程不会被强加。
+- 敏捷流程的审查要求需要另一种机制：`审查` 是终态且**就是**审查本身，没有出边可承载守卫。把 `review_passed` 挂到 `交付 → 审查` 会要求「在产生结论的阶段之前就有结论」，还会挡住 `交付` 的提交（提交要求其出边守卫全部满足）。改用 `completion_guards` 显式声明，这正是 `complete` 作为独立操作存在的原因。敏捷版本号升至 4。
+
+### 技能声明自己需要哪类证据
+
+每种非内置技能都必须记录「真实验收命令」，于是需求或设计类技能——产出是一份文档——被迫运行一条无关命令来满足门禁。证据本来就有，只是形态不同。技能绑定现在可声明 `evidence`：`command` / `artifact` / `review` / `manual` / `none`，引擎按各自形态检查对应记录。未声明时保持历史行为（命令回执），因此既有配置与冻结快照不受影响。
+
+### 保存完整配置 + 列表可用性
+
+- **保存不再只写 `flow` 与 `stage_bindings`**。提交规则、产物声明、审查深度与 `commit_required` 以前只用于预览，保存时被静默丢弃——面板显示一套配置、文件里是另一套。写入载荷与面板状态现在都覆盖全部字段。
+- **技能与规则列表在规模增长后可用**：加搜索（匹配名称、说明与来源层）、「仅看已选」筛选，展开的规则列表改为**有界滚动区**。一条规则贯穿全部筛选：**已绑定或预设自带的条目任何查询下都保持可见**——面板展示的是配置本身，筛选藏起正在生效的资源会让面板与它显示的配置不一致，那比列表长更糟。
+
 ## 0.24.0
 
 针对 2026-09-23 外部深度评测的改造。**这是一个破坏性版本**：配置里的 `stage_bindings[*].rules` 不再作为节点级规则读取，`skills` 的格式也从字符串数组改为带来源的对象。已有配置会继续工作——旧的节点级规则以 `legacy_rules` 保留并**仍然生效**——但它们的归属需要你确认一次，见下面「规则改为只挂在技能下」。

package/docs/README.md

@@ -1,41 +1,41 @@
-# 使用文档
-
-[← 返回项目首页](../README.md)
-
-DSH Task Engine 是 DeepSeek Harness 的个人工程流程工作台。先完成安装，再按需要配置流程、技能和规则。
-
-## 开始使用
-
-| 文档 | 内容 |
-| :--- | :--- |
-| [安装与启用](getting-started.md) | 安装到 Web profile、启用工程会话、确认安装结果。 |
-| [流程配置](configuration.md) | 三个内置流程、阶段绑定、配置文件与任务快照。 |
-| [技能与规则安装](resource-install.md) | 系统文件选择、安装预览、项目/个人范围和格式要求。 |
-| [常见问题](faq.md) | 预设区别、资源使用、项目目录与能力限制。 |
-| [完整 HTML 手册](manual.html) | 详细操作、工具说明与任务走查；下载后在浏览器中打开。 |
-
-## 参与开发
-
-| 文档 | 内容 |
-| :--- | :--- |
-| [开发指南](development.md) | 构建、测试、包结构与可选 host 接入。 |
-| [功能规划](roadmap.md) | 已发布能力与规划中的范围。 |
-| [更新日志](CHANGELOG.md) | 按版本查阅变化；**这是版本信息的唯一权威来源**。 |
-| [插件收录材料](listing/submission.md) | Awesome DSH Plugin 的提交条件、条目内容与收录结果。 |
-
-## 历史记录
-
-以下文档是**各自版本当时的快照**，用于追溯当时的验证范围与已知边界。其中的测试数量、
-实现细节和界面描述可能已被后续版本替代——当前行为以「开始使用」和[更新日志](CHANGELOG.md)为准。
-
-| 文档 | 内容 |
-| :--- | :--- |
-| [0.23.2 验证记录](testing/0.23.2/测试报告.md) | 两轮完整开发、归档回退与门禁专项的实际结果。 |
-| [0.23.2 发布说明](releases/0.23.2.md) | 验证命令单次审批修复、提交指引与管控边界。 |
-| [0.23.1 验证记录](testing/0.23.1/测试报告.md) | 自动化、安装包与实机证据的适用范围。 |
-| [0.23.1 发布说明](releases/0.23.1.md) | 真实项目发现的问题、修复及能力边界。 |
-| [0.23.1 回归迭代说明](workflow-regression.md) | 真实项目逐轮问题的处理记录。 |
-| [0.23.0 验证记录](testing/0.23.0/测试报告.md) | 资源导入、工作台交互与包入口的验证。 |
-| [0.23.0 发布说明](releases/0.23.0.md) | 早期安装交互及界面调整。 |
-
+# 使用文档
+
+[← 返回项目首页](../README.md)
+
+DSH Task Engine 是 DeepSeek Harness 的个人工程流程工作台。先完成安装，再按需要配置流程、技能和规则。
+
+## 开始使用
+
+| 文档 | 内容 |
+| :--- | :--- |
+| [安装与启用](getting-started.md) | 安装到 Web profile、启用工程会话、确认安装结果。 |
+| [流程配置](configuration.md) | 三个内置流程、阶段绑定、配置文件与任务快照。 |
+| [技能与规则安装](resource-install.md) | 系统文件选择、安装预览、项目/个人范围和格式要求。 |
+| [常见问题](faq.md) | 预设区别、资源使用、项目目录与能力限制。 |
+| [完整 HTML 手册](manual.html) | 详细操作、工具说明与任务走查；下载后在浏览器中打开。 |
+
+## 参与开发
+
+| 文档 | 内容 |
+| :--- | :--- |
+| [开发指南](development.md) | 构建、测试、包结构与可选 host 接入。 |
+| [功能规划](roadmap.md) | 已发布能力与规划中的范围。 |
+| [更新日志](CHANGELOG.md) | 按版本查阅变化；**这是版本信息的唯一权威来源**。 |
+| [插件收录材料](listing/submission.md) | Awesome DSH Plugin 的提交条件、条目内容与收录结果。 |
+
+## 历史记录
+
+以下文档是**各自版本当时的快照**，用于追溯当时的验证范围与已知边界。其中的测试数量、
+实现细节和界面描述可能已被后续版本替代——当前行为以「开始使用」和[更新日志](CHANGELOG.md)为准。
+
+| 文档 | 内容 |
+| :--- | :--- |
+| [0.23.2 验证记录](testing/0.23.2/测试报告.md) | 两轮完整开发、归档回退与门禁专项的实际结果。 |
+| [0.23.2 发布说明](releases/0.23.2.md) | 验证命令单次审批修复、提交指引与管控边界。 |
+| [0.23.1 验证记录](testing/0.23.1/测试报告.md) | 自动化、安装包与实机证据的适用范围。 |
+| [0.23.1 发布说明](releases/0.23.1.md) | 真实项目发现的问题、修复及能力边界。 |
+| [0.23.1 回归迭代说明](workflow-regression.md) | 真实项目逐轮问题的处理记录。 |
+| [0.23.0 验证记录](testing/0.23.0/测试报告.md) | 资源导入、工作台交互与包入口的验证。 |
+| [0.23.0 发布说明](releases/0.23.0.md) | 早期安装交互及界面调整。 |
+
 > 0.23.3 起的版本变化全部记录在[更新日志](CHANGELOG.md)中，不再单独出具发布说明。

package/docs/configuration.md

@@ -24,32 +24,35 @@
 }
 ```
 
-`stage_bindings` 的键是当前流程中的阶段名称，值只有 `skills`——**节点只选择技能，规则属于技能**。
+`stage_bindings` 的键是当前流程中的阶段名称，`skill_refs` 只保存技能引用。`skill_profiles` 为每个技能保存唯一的规则列表和证据类型。
 
 ```json
 {
   "flow": "standard",
   "stage_bindings": {
     "开发": {
-      "skills": [
-        { "skill": { "source": "bundled", "name": "code-implement" },
-          "rules": [{ "source": "bundled", "name": "coding-conventions" },
-                    { "source": "project", "name": "api-contract" }] }
-      ]
+      "skill_refs": [{ "source": "bundled", "name": "code-implement" }]
+    }
+  },
+  "skill_profiles": {
+    "bundled:code-implement": {
+      "rules": [{ "source": "bundled", "name": "coding-conventions" },
+                { "source": "project", "name": "api-contract" }],
+      "evidence": "none"
     }
   }
 }
 ```
 
-**规则挂载在技能下,节点不提供规则追加、禁用或覆盖。** 打开一个技能就能看到它完整的规则列表;把它挂到任何节点,都是同一套规则。需要同一技能在不同节点用不同规则时,**复制成另一个独立技能**,再分别配置——不建立隐式继承关系。
+**规则挂载在技能下,节点不提供规则追加、禁用或覆盖。** 在工作台“技能”页或流程页的技能规则侧栏配置规则；同一技能挂到任何节点,都是同一套规则。需要不同规则组合时,复制成另一个独立技能。旧版把规则内联在各节点技能绑定的配置仍可读取；保存后会转为上述格式。若旧内联绑定与 `skill_profiles` 同时存在，明确配置的技能档案优先，所有节点使用它的规则和凭证；若没有技能档案而同一旧技能在不同节点的规则不同，系统会要求先复制为独立技能，不会任意选一套覆盖另一套。
 
 规则引用带来源(`bundled:` / `project:` / `user:`),因此同名资源不会被混淆。同一份规则可被多个技能引用,不需要复制正文;编辑共享规则时界面会显示受影响的技能。
 
-[默认配置示例](../defaults/eng.json)列出了标准流程的完整绑定。
+[默认配置示例](../defaults/eng.json)列出了标准流程采用推荐配置后的样子。
 
-当前绑定采用追加方式:项目增加的**技能**会与预设默认项合并去重,按来源标识比较;取消预设技能的勾选不会移除它。内置同名资源优先,自建资源请使用不同名称。
+**预设不带任何绑定。** 一个只写了 `flow` 的配置就是字面意思:该流程的节点没有绑定,阶段仍按流程骨架流转。要一份现成的工程起点,在工作台点「采用推荐配置」,它会把技能、提交信息格式与产物字段**写入**你的配置一次;此后这些值就是你的普通配置,删掉不会补回,升级也不覆盖。
 
-进入阶段后,`dev_task` 披露该阶段全部技能的规则内容。新任务离开阶段前会检查 Harness 的 skill 工具成功加载记录;附加技能还须记录 `skill_result`(技能名、执行场景、真实验收命令回执)。`status.skill_obligations` 中的 `command_receipts_required` 列出需要回执的技能;七个内置技能使用已有的记录、验证、审核和提交操作,无需重复登记附加回执。安装一个技能不会自动执行其中的脚本。
+进入阶段后,`dev_task` 披露该阶段技能和规则的冻结正文。新任务离开阶段前会检查 Harness 的 skill 工具成功加载记录;技能可声明证据类型(`command` / `artifact` / `review` / `manual` / `none`)。`manual` 通过宿主人工审批记录，不要求执行命令；`artifact` 需要该阶段有产物定义且必填字段完整。未声明时沿用命令回执。`status.skill_obligations` 中的 `command_receipts_required` 列出需要命令回执的技能。
 
 挂在终态(例如"完成")的技能在进入终态前执行。测试技能通常建议挂在"交付";现有"完成"绑定也会在审核阶段执行后才放行。标准流程 v2 在审核通过后提交,并核对真实 Git HEAD。修改文件或声明范围后,旧验证回执失效。
 
@@ -69,6 +72,6 @@
 
 新任务记录创建时的完整流程快照，后续按该快照执行。修改项目配置影响之后创建的任务，不会自动迁移进行中的任务。
 
-验证命令还可以由配置中的 `verify_command` 指定；未指定时根据项目类型选择默认命令。当前工作台保存流程时只写入 flow 和 stage_bindings，手写的额外字段可能被移除；使用此项时请检查保存后的文件。这一问题纳入后续配置编辑器改造。
+任务开始时会冻结所引用的技能和规则正文。资源类型、来源和名称共同构成身份，因此同名技能和规则不会混淆。缺失的必需资源会阻止新任务创建；已完成任务若需返工，使用 `revise` 显式重开。
 
 下一步：[资源安装](resource-install.md) · [常见问题](faq.md)

package/docs/development.md

@@ -25,7 +25,7 @@ CI 在 Windows 的 Node 22/24 上运行。每次功能修改选择相关验证
 | 位置 | 职责 |
 | :--- | :--- |
 | [src/engine.ts](../src/engine.ts) | 状态机、阶段条件和提交规则检查。 |
-| [src/workflows.ts](../src/workflows.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) | 导入校验、安装预览、独占写入与失败清理。 |

package/docs/faq.md

@@ -16,19 +16,19 @@
 
 ## 安装资源后就会自动使用吗？
 
-还需要到“流程配置”选择阶段并挂载资源。任务执行时按阶段披露对应内容；安装行为本身不会执行资源中的脚本。
+还需要为技能配置规则，再到“流程配置”选择阶段并挂载技能。任务执行时按阶段披露对应内容；安装行为本身不会执行资源中的脚本。
 
 ## 改了流程，原来的任务会变化吗？
 
 任务保存创建时的流程快照。修改项目配置不会自动改变进行中的任务；新任务使用保存后的配置。
 
-## 能移除默认技能、覆盖内置规则吗？
+## 能移除推荐技能、修改内置规则吗？
 
-预设绑定只能追加，内置资源只读且同名优先。需要自建资源时使用新名称；同名资源会同时保留在各自来源，绑定选择按名称去重。
+流程预设没有强制技能绑定。「采用推荐配置」只是一次性写入项目配置，之后可任意增删技能和规则。内置资源的正文只读；可新建自己的规则并挂到技能下，也可选择不同来源的同名资源，引用会保留来源，不按名称混用。
 
 ## 工具显示验证或审核通过，能完全相信吗？
 
-新建任务的验证需要真实命令回执，要求退出码为 0 且未超时、中止或被沙箱拒绝；代码修改后需重验。附加技能记录加载、命令和场景证据；审核和实施项结论仍由模型记录。命令覆盖是否充分、审核是否准确仍需判断，不能把一个成功退出码当作全部需求已验证。
+新建任务的验证需要真实命令回执，要求退出码为 0 且未超时、中止或被沙箱拒绝；代码修改后需重验。技能按配置记录加载情况及所需的命令、产物、审核或人工批准证据；审核和实施项结论仍需判断。命令覆盖是否充分、审核是否准确仍需判断，不能把一个成功退出码当作全部需求已验证。
 
 ## 验证命令被沙箱阻止怎么办？
 

package/docs/listing/godv61__dsh-task-engine.yml

@@ -1,6 +1,6 @@
-url: https://github.com/godv61/dsh-task-engine
-name: godv61/dsh-task-engine
-category: workflow
-description:
-  en: 'Preset engineering workflows for DeepSeek Harness: a dev_task tool that gates stage transitions, artifacts, verification, review and commit scope, plus a web workbench for installing project or user skills and rules.'
+url: https://github.com/godv61/dsh-task-engine
+name: godv61/dsh-task-engine
+category: workflow
+description:
+  en: 'Preset engineering workflows for DeepSeek Harness: a dev_task tool that gates stage transitions, artifacts, verification, review and commit scope, plus a web workbench for installing project or user skills and rules.'
   zh: '为 DeepSeek Harness 提供预设工程流程：dev_task 工具把阶段流转、产物、验证、审核与提交范围做成硬门禁，并带一个安装项目级与个人级技能和规则的工作台。'