Trellis 工作流 1264459640/dsh-trellis

dsh-trellis

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

🌏 中文 · English

项目简介

dsh-trellis 是给 DeepSeek Harness (DSH) 做的工程化工作流插件，借鉴了 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，在终端运行：

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：

& "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。

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/<slug>/）内的白名单文档，杜绝跨目录修改。

扩展工具 (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/spec/ 时，把一份紧凑的规范索引（分层 index.md 路径 + 先读约束）写入系统提示词，让模型在出方案与改码前先对齐规范。只注入索引，不注入规范正文 |
| skipKeywords | string[] | ['no-trellis'] | 跳过关键词：用户消息包含这些词时，该轮跳过面包屑注入与拦截（系统提示词段的 injectSpecIndex / enforceReadonlyPlanning 属会话级，不受单轮关键词抑制，请用各自开关关闭） |
| injectStep | number | 1 | 面包屑提示词的注入步数，默认仅在每轮交互第 1 步注入 |
| inline | boolean | false | 是否开启 codex-inline 风格的阶段解析模式 |

项目结构

dsh-trellis/
├── lib/
│ ├── index.js # 插件入口：注册 pre-step 钩子、运行时工具过滤与 API 路由 │ ├── task.js # 任务执行逻辑：步骤流转、验证门禁检查与状态校验 │ ├── skills.js # 技能供给：向项目注入 standard 工作流技能与产物模板 │ ├── breadcrumb.js # 上下文提示：提取焦点步骤与构建面包屑 │ ├── readonly.js # 只读策略：推导 undecided / planning / authorized 授权状态 │ ├── spec.js # 规范索引：扫描 .trellis/spec、渲染索引与装配 trellis:spec-index 段 │ ├── 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 许可证 开源；
- 致谢 Trellis（Mindfold）：阶段规范与面包屑设计的灵感来源；
- 致谢 CodeStable：优秀的三大工作流路由划分思路；
- 致谢 DeepSeek Harness：灵活可靠的智能体运行时环境。