# dsh-trellis
Trellis 工作流扩展 · DeepSeek Harness
结构化阶段流转 · 步骤状态机 · 质量验收门禁 · 可选规划期只读保护

License: MIT Node Version Step State Machine Verification Gate
🌏 中文 · English
--- ## 项目简介 `dsh-trellis` 是为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 开发的工程化工作流插件，借鉴了 [Trellis](https://github.com/mindfold-ai/trellis) 的阶段规范与状态机设计思想。 在大模型长程编程任务中，常见以下协作问题： 1. **未理清方案便直接修改代码**：容易引入方向性错误或破坏现有架构； 2. **任务待办散落各处**：需求文档、草稿文件与上下文记录多处待办，状态脱节； 3. **缺乏验收约束**：代码编写完成后直接标记完成，缺少自测验证或人工审核卡点。 `dsh-trellis` 通过统一的步骤状态机、任务阶段流转和运行时工具过滤，帮助大模型在复杂任务中遵循“先方案后编码、验证后再完结”的工程规范。 --- ## 核心特性 - **结构化阶段流转**：提供特性开发（feat）、缺陷修复（issue）与代码重构（refactor）三条标准阶段轨道，引导模型逐步推进。 - **统一执行清单**：以任务根目录下的 `task.json.steps` 作为唯一的执行状态依据，避免分散维护清单带来的状态不一致。 - **质量验收门禁**：细化步骤流转状态（`pending`、`in_progress`、`verifying`、`blocked`、`completed`），支持区分自动化测试（AI 验证）与人工审批卡点，并在任务完结时严格检查验收状态。 - **可选规划期只读保护**：开启配置项后，可在方案获批前于运行时过滤掉代码写工具（`write` / `edit`），仅开放文档受控修改通道，确保方案敲定后再动代码。 - **会话级状态隔离**：各会话的任务绑定关系独立存储在 `.trellis/.runtime/sessions/` 中，多会话与并发子代理并行工作时互不串扰。 - **双模态任务看板（视觉语言 v2）**：常态为极简紧凑弹窗（当前绑定任务置顶为焦点卡片，内置高亮步骤清单与折叠态；下方按状态分组列出任务流），可一键展开为全屏大看板（按「进行中 / 规划中 / 已完成」分组表格，支持 `⌘K` 实时搜索与工作流类型筛选）；右侧详情面板内置 **Step Tracker 步骤流水线**、阶段轨道节点与产物文件列表。看板遵循**单强调色设计**与**克制交互**——不直接改任务状态，仅提供「▶ 推进任务」将指令安全填入输入框交由 Agent 执行，产物点击生成 `@.trellis/tasks/...` 原生文件引用交给 DSH 原生查看。 - **Git 干净度校验（支持局部校验）**：任务完成和归档时自动检查 Git 工作区状态，防止遗留未提交的脏代码。若工作区存在与任务无关的未提交改动，可在 `trellis_task_update` / `trellis_task_archive` 中通过 `modified_files` 声明任务实际改动文件，校验将限缩到清单内文件（须已提交），清单外未提交改动仅告警、不再阻塞；未传该参数时保持全局严格校验。 --- ## 快速上手 ### 1. 安装插件 确保环境 Node.js ≥ 20，在终端运行： ```sh dsh plugin --profile web add @banana-peeljj12/dsh-trellis@latest ``` 安装完成后**重启 DSH 服务**。 > **桌面版（DeepSeek Harness App）请用自带的 carrier CLI。** 普通 `dsh` CLI 会以 > `error: profile "desktop" is managed exclusively by the Electron application` 拒绝操作 > `desktop` profile（该名字被硬编码保护）。请改用桌面版自带的 CLI： > > ```sh > & "F:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:F:\dsh-plugins\dsh-trellis > ``` > > 装的若是本地开发目录，用 `link:<仓库绝对路径>`；装完成后**完整退出并重启桌面版** > （含托盘图标，确认任务管理器中不再有 `DeepSeek Harness.exe`）才会生效。 > **版本兼容性**：插件声明的 `@deepseek-ai/dsh-*` peer 范围必须覆盖当前 DSH 运行时版本。 > DSH 会在安装前置检查（pnpm 运行之前）与 profile 启动时校验该范围，不匹配会直接 > `installation rejected` 并拒绝加载——这不是代码问题，而是声明问题： > 例如运行时为 `0.2.0-rc.2` 时，`^0.1.7-rc.1`（= `>=0.1.7-rc.1 <0.2.0-0`）不覆盖它， > 必须提升到 `^0.2.0-rc.2`。升级 DSH 后若插件突然失效，请先核对 peer 范围。 > 本仓库当前面向 **DSH 0.2.0-rc.2**；审计证据见 > [`docs/ref/dsh-0.2.0-rc.2-audit.md`](docs/ref/dsh-0.2.0-rc.2-audit.md)。 ### 2. 配置白名单目录（重要） 为避免非预期介入，插件默认不会拦截未授权的目录。请在 Web 端或配置文件中添加生效路径： 1. 打开 DSH Web 客户端，点击左侧边栏的 **「插件」** 图标，在 **「已安装」** 分区点击 **@banana-peeljj12/dsh-trellis** 进入详情页（配置表单直接位于详情页最外层，无需再展开「包含的组件」）； 2. 在 **白名单项目 (allowlist)** 中添加需要启用该工作流的项目根目录绝对路径——既可手动输入， 也可点击 **浏览…** 按钮弹出系统文件夹选择器直接选取，保存后即时生效。 > **提示**：若希望在方案定稿前限制模型修改源码，可在该详情页同时开启 **规划期只读保护 (enforceReadonlyPlanning)** 开关。 ### 3. 开始使用 在对话中提出较复杂的需求时，模型会引导创建或推进工作流任务： - **新增功能**：创建 `feat-mm-dd-name`，推进 `prd` → `design` → `impl` → `review` → `check`； - **修复问题**：创建 `issue-mm-dd-name`，推进 `report` → `analyze` → `fix` → `fix-note`； - **重构优化**：创建 `refactor-mm-dd-name`，推进 `scan` → `design` → `apply` → `done`。 如需在某轮对话中临时跳过工作流拦截，在消息中包含 `no-trellis` 即可。 --- ## 工作流与轨道规范 插件内置了三类标准工作流轨道，任务状态与当前所处阶段（`work.stage`）紧密挂钩： | 工作流类型 | 命名规范 | 阶段推进顺序 | 说明 | |---|---|---|---| | **功能特性 (`feat`)** | `feat-MM-DD-name` | `prd` → `design` → `impl` → `review` → `check` | 适合从 0 到 1 开发新特性或重大功能调整 | | **缺陷修复 (`issue`)** | `issue-MM-DD-name` | `report` → `analyze` → `fix` → `fix-note` | 适合排查和定位 bug、回归问题及异常情况 | | **代码重构 (`refactor`)** | `refactor-MM-DD-name` | `scan` → `design` → `apply` → `done` | 保持对外行为不变的前提下进行架构或代码优化 | --- ## 核心机制详解 ### 1. 步骤状态机与验收门禁 任务的 `steps` 数组为执行清单，支持 5 种状态： - `pending`：步骤待开始； - `in_progress`：当前正在实施该步骤； - `verifying`：代码实施完毕，等待验证； - `blocked`：遇到外部阻塞，必须附带 `blockedReason`； - `completed`：验证通过后完结。 #### 验证模式说明： - **自动化验证 (`verification: 'ai'`)**：模型编写代码后，必须先运行测试并调用 `trellis_task_update` 填入 `verified: true` 与 `verificationNotes` 测试记录，随后才允许将状态更新为 `completed`，防止单次调用跳过测试。 - **人工验收卡点 (`verification: 'human'`)**：用于涉及核心契约或高风险操作的步骤。只有在用户明确同意且记录 `verifiedBy: 'human'` 后，该步骤才被允许标记为 `completed`。 - **任务完结审计**：当任务标记为完成或发起归档时，系统会校验所有步骤是否均已完成并通过验证，同时校验 Git 工作区是否干净。 ### 2. 双模态任务看板（紧凑浮层与全屏工作台） 在 DSH Web 客户端中，顶部阶段徽章支持交互式展开任务看板，具备以下双模态形态： #### 紧凑浮层视图（常态）与全屏任务看板 常态下点击徽标展开紧凑弹窗：顶部将当前绑定任务展示为焦点卡片，内置 **Step Tracker 步骤清单**（加粗当前实施步骤、展示验收标准，并支持已完成步骤折叠），下方按生命周期状态清晰分组；点击右上角放大按钮可平滑展开为全屏大看板，支持 `⌘K` 实时搜索与右侧完整详情抽屉：

紧凑任务浮层与步骤清单卡片   全屏任务看板与详情面板

#### 工作流分类过滤与多状态概览 大看板顶栏支持按「功能 / 缺陷 / 重构」分类药丸即时过滤。当选择特定工作流（如代码重构）时，视图聚焦当前分类任务，配合右侧详情抽屉呈现阶段流水线节点、完整步骤状态机与交付物文档：

重构工作流过滤与任务详情面板

- **单强调色设计**：类型采用清晰无彩文字，统一使用品牌蓝标识当前会话与进行中状态，红/黄色警告仅用于外部阻塞与待验证门禁，视觉层级干净克制。 - **克制交互原则**：看板保持纯粹的监控与导航定位，不直接在界面端篡改任务底层状态；仅通过右侧「▶ 推进任务」将规范提示词安全填入输入框，交由 Agent 按工作流状态机推进。 - **原生文件联动**：产物列表中点击「打开」会自动生成 `@.trellis/tasks/...` 原生文件引用，无缝调起 DSH 侧边栏文件预览。 ### 3. 规划期只读保护（可选增强） 当在配置中启用 `enforceReadonlyPlanning: true` 时，插件会根据当前任务状态**仅裁剪指定的工具**（denylist，其余工具——包括其他插件注册的工具——原样保留）： | 授权状态 | 触发条件 | 被裁剪的工具 | 说明 | |---|---|---|---| | `undecided` | 项目在白名单内、无活跃任务且未声明跳过 | `write` / `edit` + `trellis_task_update` / `trellis_artifact_update` / `trellis_task_archive` / `trellis_ui_update` | 移除代码写工具与任务写工具，避免盲目直接改写源码；`trellis_task_create` / `trellis_task_skip` 与所有其他工具（含其他插件工具）保留 | | `planning` | 任务处于规划类阶段（`prd`, `design`, `scan`, `report` 等） | `write` / `edit` + `trellis_task_create` / `trellis_task_skip` / `trellis_task_archive` / `trellis_ui_update` | 移除通用 `write` / `edit` 工具与任务生命周期工具，仅放行受控的任务产物更新；`trellis_task_update` / `trellis_artifact_update` 与所有其他工具保留 | | `authorized` | 任务进入实施阶段（`impl`, `fix`, `apply`）或用户已跳过 | 无（不裁剪） | 允许根据设计方案修改项目源码 | > 注：`trellis_artifact_update` 仅允许写入当前任务目录（`.trellis/tasks//`）内的白名单文档，杜绝跨目录修改。 --- ## 扩展工具 (Tools) 说明 插件向运行时注册了以下专用工具： - **`trellis_task_create`**：创建新的工作流任务，生成初始 `task.json` 与阶段交付物模板，并自动绑定当前会话。 - **`trellis_task_update`**：推进任务阶段、更新步骤进度、记录验证证据或更新任务信息，不改变当前会话绑定。显式传入 `slug` 只选择更新目标；切换任务请使用看板的激活按钮。 - **`trellis_artifact_update`**：安全更新任务交付文档（如 `prd.md`, `design.md`, `check.md` 等），受白名单和路径校验约束。 - **`trellis_task_archive`**：将已完成的任务归档至 `.trellis/tasks/archive/YYYY-MM/` 目录下，并解除当前会话绑定。 - **`trellis_task_skip`**：经用户同意后，在当前会话跳过 Trellis 工作流约束，直接放行全量工具权限。 - **`trellis_state`**：诊断并返回当前项目的 Trellis 运行时状态与任务信息。 - **`trellis_ui_update`**：主动刷新 Web 界面顶部的阶段徽章状态。 --- ## 配置项参考 可在左侧 **「插件」** 页（进入 **@banana-peeljj12/dsh-trellis** 详情页最外层即可见）或 `~/.dsh/settings.yaml` 中进行配置： | 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | `allowlist` | `string[]` | `[]` | **生效白名单**：允许插件接入的项目根目录绝对路径列表。为空时不介入任何项目 | | `enforceReadonlyPlanning` | `boolean` | `false` | **规划期只读保护**：开启后，方案定稿前在运行时移除代码修改工具 | | `injectSpecIndex` | `boolean` | `true` | **注入项目文档**：项目配置 `.trellis/doc.json` 时注入 `files` 列出的文档**正文**（上限由下面的注入预算控制，超出部分截断并标注路径）；未配置时兼容扫描 `.trellis/spec/` 只注入索引 | | `docFileBudgetKB` | `number` | `8` | **单文件注入预算（KB）**：单个文档正文最多注入多少 KB，硬顶 128KB；项目可在 `.trellis/doc.json` 的 `budgets.fileKB` 逐项目覆盖 | | `docTotalBudgetKB` | `number` | `32` | **正文合计注入预算（KB）**：全部文档正文合计最多注入多少 KB，硬顶 512KB；项目可在 `.trellis/doc.json` 的 `budgets.totalKB` 逐项目覆盖 | | `skipKeywords` | `string[]` | `['no-trellis']` | **跳过关键词**：用户消息包含这些词时，该轮跳过面包屑注入与拦截（系统提示词段的 `injectSpecIndex` / `enforceReadonlyPlanning` 属会话级，不受单轮关键词抑制，请用各自开关关闭） | | `injectStep` | `number` | `1` | 面包屑提示词的注入步数，默认仅在每轮交互第 1 步注入 | | `inline` | `boolean` | `false` | 是否开启 codex-inline 风格的阶段解析模式 | --- ## 项目文档入口配置 项目可用 `.trellis/doc.json` 显式声明 Trellis 应读取的 Markdown 文件： ```json { "root": ".trellis/spec", "files": [ ".trellis/spec/guides/index.md", ".trellis/spec/trellis-workflow/task-engine/index.md" ], "budgets": { "fileKB": 16, "totalKB": 64 } } ``` - `files`：运行时注入白名单。每项必须是项目根相对的 Markdown 完整路径；支持多个文件，按配置顺序注入并去重。**注入的是正文**，不是路径。 - `budgets`（可选）：本项目自己的注入预算，单位 KB，只写想覆盖的那一项即可。优先级 **`doc.json` 的 `budgets` > 插件设置 `docFileBudgetKB` / `docTotalBudgetKB` > 内置默认 8KB / 32KB**；单文件硬顶 128KB、合计硬顶 512KB，超出的值会被夹紧。写 `0`、负数或非数字视为未设置，自动回退上一级。 - **注入预算**：单文件与合计各有一档上限（默认 8KB / 32KB，UTF-8 字节）。超出的部分会截断，并标注「已截断 / 超出预算，请 read <路径>」，模型可据此补读；读取失败的文件同样标注路径。提示词头会回显本次真实生效的两个上限。 - `root`：仅供 `trellis-spec-bootstrap`、`trellis-update-spec` 等 Skill 作为文档发现与沉淀的默认根目录，不拼接或过滤 `files`，也不改变运行时注入结果。 - 未配置 `.trellis/doc.json` 时继续扫描 `.trellis/spec/`（只注入索引，不注入正文）；显式配置后未列入 `files` 的旧 Spec 不再注入。 - 显式配置无效时不会静默回退旧 Spec，而是注入一条简短修复提示。 - 新增需长期注入的文档时，必须同步加入 `files`。已有 Docs 的项目可运行 `trellis-spec-bootstrap` 的迁移分支；新项目使用其初始化分支。 - **可视化配置**：在会话顶部视图栏切到 **「项目文档」**（与「对话 / 轨迹 / Git」同级），即可查看和编辑当前项目的 `.trellis/doc.json`：增删/排序文件、在「注入预算」里直接改本项目的单文件 / 合计上限（留空 = 继承插件设置，非法值就地标红且不能保存）、查看每个文件的注入状态（完整 / 将截断至 生效上限 / 仅保留路径）与预算占用；未配置时可一键载入现有 `.trellis/spec` 索引作为初稿。保存后下一次注入立即生效，无需重启。 --- ## 项目结构 ```text dsh-trellis/ ├── lib/ │ ├── index.js # 插件入口：注册 pre-step 钩子、运行时工具过滤与 API 路由 │ ├── task.js # 任务执行逻辑：步骤流转、验证门禁检查与状态校验 │ ├── skills.js # 技能供给：向项目注入 standard 工作流技能与产物模板 │ ├── breadcrumb.js # 上下文提示：提取焦点步骤与构建面包屑 │ ├── readonly.js # 只读策略：推导 undecided / planning / authorized 授权状态 │ ├── spec.js # 规范索引：读取 .trellis/doc.json files 白名单或兼容扫描 .trellis/spec │ ├── state.js # 状态解析：阶段推断、会话指针与 slug 格式校验 │ ├── artifact.js # 产物写入：受控文档更新与路径安全限制 │ ├── archive.js # 归档处理：任务完结检查、目录归档迁移与 Git 干净度校验 │ ├── board.js # 看板数据：任务记录（含 steps 聚合）、阶段轨道与归档列表 │ ├── client.js # 前端界面：Web 阶段徽章、双模态看板（紧凑浮层 + 全屏工作台）与设置项 │ └── types/index.d.ts # TypeScript 类型定义 ├── skills/ # 内置的工作流技能与各阶段 Markdown 模板 ├── docs/images/ # 界面截图与架构图素材 └── test/ # 自动化单元测试套件 ``` --- ## 开源协议与致谢 - 本项目基于 [MIT 许可证](./LICENSE) 开源； - 致谢 [Trellis](https://github.com/mindfold-ai/trellis)（Mindfold）：阶段规范与面包屑设计的灵感来源； - 致谢 [CodeStable](https://github.com/codestable/CodeStable)：优秀的三大工作流路由划分思路； - 致谢 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)：灵活可靠的 Agent 运行时环境。