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：

```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。

2. 配置白名单目录（重要）

为避免非预期介入，插件默认不会拦截未授权的目录。请在 Web 端或配置文件中添加生效路径：

1. 打开 DSH Web 客户端，进入左下角 设置 → 插件 → 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 界面顶部的阶段徽章状态。

配置项参考

可在 Web 设置面板（设置 → 插件 → Trellis 工作流）或 ~/.dsh/settings.yaml 中进行配置：

配置项 · 类型 · 默认值 · 说明 allowlist · string[] · [] · 生效白名单：允许插件接入的项目根目录绝对路径列表。为空时不介入任何项目 enforceReadonlyPlanning · boolean · false · 规划期只读保护：开启后，方案定稿前在运行时移除代码修改工具 skipKeywords · string[] · ['no-trellis'] · 跳过关键词：用户消息包含这些词时，该轮跳过工作流注入与拦截 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 授权状态
│   ├── 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：灵活可靠的 Agent 运行时环境。