@godv61/dsh-task-engine 0.29.8 → 0.30.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 模板、语义化版本、变更日志规范、安全策略、行为准则？