dsh-trellis

Trellis 工作流适配进 DeepSeek Harness
_{让 AI 编程先规划后动手 · 步骤清晰 · 阶段可视 · 告别失控}



每轮对话自动注入任务状态面包屑，把 15+ trellis-* 工作流技能随项目自动补齐，
并提供开箱即用的任务管理工具与 Web 端可视化阶段徽标 / Mini 任务看板。

💡 为什么需要 dsh-trellis？

在日常使用 AI Agent 写代码时，你是否经常遇到这些痛点：

• 🤯 聊着聊着就跑偏：多轮对话后，AI 忘了原本的目标是什么，开始乱改不相干的代码。
• 🏃 不假思索直接瞎写：提一个新需求，AI 连架构和影响面都没搞清楚就直接写代码，产生大量回归 Bug。
• ❓ 进度完全黑盒：不知道 AI 到底在做需求设计、写代码还是在做测试，卡住了也难以排查。

dsh-trellis 把成熟的 Trellis 结构化工程工作流带到了 DeepSeek Harness (DSH)。

它让 AI 像资深工程师一样工作：

1. 🧠 有记忆、不迷路：每轮对话开始时，插件会自动将当前任务进度和阶段目标提醒给 AI。
2. 📐 先规划、后动手：遵循规范的工作流——做功能先写 PRD/方案，修 Bug 先分析定位，通过审查验收后再归档。
3. 📊 直观可视化：Web 界面右上角常驻当前任务徽标，点击一键展开任务看板与阶段进度，随时切换与回顾。
4. 🪶 轻量零负担：纯 Node.js ESM 实现，零外部依赖，不需要 Python，不侵入项目源码。

⚡ 30 秒极速上手

1. 安装插件

确保环境满足 Node.js ≥ 20 且 DSH 正常运行，在终端执行：

# 安装插件
dsh plugin --profile web add @banana-peeljj12/dsh-trellis

# 更新插件到最新版本
dsh plugin --profile web add @banana-peeljj12/dsh-trellis@latest

# 本地源码开发安装
dsh plugin --profile web add link:/abs/path/to/dsh-trellis

安装完成后，重启一次 DSH 服务。

2. 添加项目到白名单

插件默认不拦截未授权的项目。重启后，只需在 Web 界面完成一次配置：

1. 刷新 DSH 浏览器页面。
2. 点击左下角 设置 → 插件 → Trellis 工作流。
3. 在 白名单项目 (allowlist) 中填入你的项目绝对路径（如 /home/user/my-project 或 D:/projects/my-project），点击保存即可即时生效。

💡 也可以直接在 ~/.dsh/settings.yaml 中配置 trellis-workflow.allowlist，详见下方配置章节。

3. 开始使用！

在会话中直接像平时一样提需求即可，例如：

“帮我在用户系统里加一个微信扫码登录功能”

AI 将会自动识别意图，引导你创建 Trellis 任务（如 feat-08-20-wechat-login），生成 PRD 需求规划，一步一步稳健推进！

🧭 三大内置工作流

dsh-trellis 内置了三套经过实战检验的标准工程流，由路由表自动分发：

🚀 快速通道 vs 🛡️ 标准通道

• 快速通道 (quick)：适用于局部小改动、挂载点明确的轻量任务，跳过繁重评审直接进入实现与验证。
• 标准通道 (standard)：关键节点设置人工卡点（如设计方案必须经由用户确认、代码必须通过独立 review 与测试验收后方可归档），适合中大型复杂特性。

✨ 核心特性一览

1. 🧭 静默且聪明的状态提醒（面包屑注入）

• 每当用户发送一条新消息时，插件会自动在首步为 AI 注入当前任务状态（包含当前处于哪个阶段、下一步该做什么）。
• 不刷屏：仅在每轮新消息的首步提醒，中间工具调用步骤保持干净。
• 随时逃生：只要用户消息中包含 no-trellis 关键字，该轮对话即完全跳过工作流拦截。

2. 🧩 15+ 工作流技能随项目自动供给

• 随包内置 15 个经过精细调优的 trellis-* 技能及模板（位于包内 skills/）。
• 打开会话时，插件会自动检查项目根目录的 .agents/skills/，缺什么补什么，无需手动复制或修改 Profile。
• 项目自身可以自由修改已生成的技能副本；如果不小心删除了，下一轮会自动补齐。

3. 🏷️ Web 阶段徽标 & Mini 任务看板

• 会话标题右侧优雅嵌入当前阶段徽标（如 功能 · design）。
• 点击/悬停可展开当前工作类型的完整阶段轨道。
• 点击可呼出 Mini 任务看板：
  • 🔄 快速切换：在多个活跃任务之间一键切换会话绑定。
  • 🗄️ 归档折叠：自动按月份（如 2025-08）折叠已完成的历史任务，清晰易查。
• 极致性能：全部基于 Host 端只读缓存摘要，浏览器端纯展示，绝不触发额外耗时扫描。

4. 🛠️ 规范化的任务全生命周期工具

• trellis_task_create：一键创建任务目录、初始化产物模板（prd/design）、规范命名格式（<type>-<mm-dd>-<name>），并同步绑定到当前会话。
• trellis_task_update：原子化更新任务阶段（stage）与状态（status），自动校验阶段转移合法性并刷新界面徽标。
• trellis_task_archive：任务完成后，一键移入归档目录，自动解绑会话指针，保持看板清爽。
• trellis_state：随时诊断当前项目所处的工作流阶段与健康度。

⚙️ 详细配置

插件支持通过 Web 界面（推荐）、用户全局配置 或 Profile 补丁 进行配置：

配置项说明

方式一：Web 设置界面（免重启、即时生效）

1. 重启 DSH 后，访问左下角 设置 → 插件 → Trellis 工作流。
2. 增删白名单路径或调整参数，点击保存即刻写入生效。

方式二：用户配置文件（settings.yaml，热重载）

编辑 ~/.dsh/settings.yaml（Windows 为 %USERPROFILE%\.dsh\settings.yaml）：

trellis-workflow:
  allowlist:
    - /home/bananapeel/my-awesome-project
    - /mnt/d/code/another-project
  injectStep: 1
  skipKeywords:
    - no-trellis
  inline: false

- id: trellis-workflow
  name: '@banana-peeljj12/dsh-trellis'
  config:
    allowlist:
      - /path/to/your/project
    injectStep: 1
    skipKeywords: ['no-trellis']
    inline: false

🛠️ 二次开发与架构说明

目录结构

dsh-trellis/
├── package.json            # npm 插件包元数据（@banana-peeljj12/dsh-trellis, MIT）
├── cordis.patch.yml        # dsh.bundle 自动挂载层声明
├── lib/
│   ├── index.js            # 插件总入口：注册 pre-step 拦截器、生命周期、RPC 路由与工具集
│   ├── task.js             # 任务创建与更新：slug 规范校验、模板初始化、session 指针同步
│   ├── archive.js          # 任务归档：原子迁移至 archive/<yyyy-mm>/、解绑指针
│   ├── resolve.js          # 路径解析：基于 cwd 识别项目根与 .trellis 资产
│   ├── state.js            # 状态机：解析会话绑定、读取当前 stage、组装摘要与阶段轨道
│   ├── breadcrumb.js       # 构造每轮向 AI 注入的提示词与逃生词过滤
│   ├── trust.js            # 本地回环同源安全校验（防御 DNS-rebinding）
│   ├── skills.js           # 技能供给：按需向项目 .agents/skills/ 补齐权威副本
│   ├── settings.js         # Web 设置页命名空间注册与存储交互
│   └── meta.js             # 配置项 Schema 与默认值
├── skills/                 # 15 个随包权威技能副本
│   ├── trellis-*/SKILL.md  # 技能正文定义
│   └── _templates/         # 任务产物模板 (prd/design/review 等) 与路由表
└── scripts/
    └── install.mjs         # 独立辅助安装脚本

技术要点

• 零构建、纯标准 ESM：无 TypeScript 编译负担，改动即生效。
• 只读缓存隔离：Web 端的查询请求只命中内存只读缓存，杜绝频繁读取磁盘。
• 沙箱与安全隔离：文件操作全部遵循 DSH 的 ctx.fs 沙箱安全规范，避免越权访问。

❓ 常见问题（FAQ）

dsh plugin --profile web remove @banana-peeljj12/dsh-trellis

🙏 致谢

• Trellis（作者 Mindfold，AGPL-3.0-only）： 感谢 Mindfold 团队开源了出色的 Trellis 工作流思路。本项目仅移植了其流程语义（阶段轨道、任务产物规范与面包屑机制），代码与技能内容均为独立重写，不包含任何 AGPL 源码，以 MIT 许可证发布。
• CodeStable： 感谢 CodeStable 团队，内置的三大工作流（feat / issue / refactor）结构通用化改编自其优秀的工程化设计思路。
• DeepSeek Harness： 强大的大模型 Agent 运行时底座。

📄 开源许可证

本项目基于 MIT 许可证 开源发布。