dsh-trellis

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

项目简介

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）紧密挂钩：

核心机制详解

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，其余工具——包括其他插件注册的工具——原样保留）：

注：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 中进行配置：

项目文档入口配置

项目可用 .trellis/doc.json 显式声明 Trellis 应读取的 Markdown 文件：

{
  "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 索引作为初稿。保存后下一次注入立即生效，无需重启。

项目结构

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 许可证 开源；
• 致谢 Trellis（Mindfold）：阶段规范与面包屑设计的灵感来源；
• 致谢 CodeStable：优秀的三大工作流路由划分思路；
• 致谢 DeepSeek Harness：灵活可靠的 Agent 运行时环境。