Beants/dsh-trellis

dsh-trellis

简体中文 · English

把 Trellis 任务驱动开发工作流集成进
DeepSeek Harness（dsh）：
全套 Trellis 技能、/trellis- 命令、一键 .trellis/ 脚手架、每轮工作流状态注入——不依赖平台 hook 事件。

生态话题：#dsh-plugin · #dsh · #trellis

本项目（本插件 + Trellis 上游的 dsh 平台注册）完全由 DeepSeek V4 Flash
（max reasoning effort）+ DeepSeek Harness 会话完成，见
本项目是如何实现的。

特性

| 能力 | 说明 |
| --- | --- |
| 15 个 Trellis 技能 | trellis-start / continue / finish-work、五个工作流技能（brainstorm / before-dev / check / break-loop / update-spec）、DSH 版子代理派发定义（trellis-agent-implement/check/research）、内置技能（trellis-channel / trellis-session-insight / trellis-spec-bootstrap / trellis-meta） |
| /trellis- 命令 | /trellis-init 在会话工作区一键生成 .trellis/；/trellis-status 查看会话状态；/trellis-start / continue / finish-work 会话指引 |
| 每轮工作流状态注入 | 插件用 per-agent 的 systemPrompt section（每次 prompt 组装重新求值）复刻 Trellis 的 inject-workflow-state——每轮都携带当前任务 + workflow.md 的阶段指引。注入走 system 前缀而非对话消息（DSH 另有 agent/pre-step waterfall 可注入 user-role 消息，见下文路线说明） |
| Web 状态卡 | 会话头部状态胶囊 + 「trellis workflow」标签页（进度轨道 / 介入收件箱 / 活动流 / 验证链），只读端点供数，非 Trellis 工作区零打扰 |
| 完全自包含 | 运行时不依赖 Trellis CLI：渲染好的技能内容与 .trellis/ 脚手架都随包分发，上游更新后用 scripts/prepare-assets.mjs 一键再生成 |

工作原理（与 hook 平台的对照）

Trellis 在带 hook 的平台（Claude Code、Cursor、Qoder、OpenCode…）上自动注入上下文。
DSH 提供 cooperative waterfall 扩展点（agent/pre-step / agent/request-error /
agent/turn-stopping，官方 dsh-agent-instructions 插件即用 agent/pre-step 在每步
向消息批注入 user-role 消息），但本插件没有走消息注入路线，而是把每个 hook 映射为
prompt-section 等价机制：

| 上游 hook | 做的事 | dsh-trellis 的等价实现 |
| --- | --- | --- |
| session-start | 首条消息注入完整会话上下文 | trellis-start 技能：模型按技能指示用 bash 跑 get_context.py（pull-based；DSH 的 prompt section 必须同步，无法直接执行 Python） |
| inject-workflow-state | 每一轮注入  面包屑（workflow.md 的 [workflow-state:STATUS] 标签 + 当前 task.json 状态） | app:trellis prompt section，每次 prompt 组装重新求值： 块带 Task:  () 与 workflow.md 对应阶段的指引正文 |
| inject-subagent-context | 子代理 prompt 注入 prd/implement.jsonl 上下文 | trellis-agent- 技能的 pull-based prelude：派发 prompt 首行 Active task: ，子代理自行读取 prd.md / implement.jsonl |

行为细节：

- 注入路线取舍：systemPrompt section 每轮重组进 system 前缀——token 形态稳定、KV cache 友好、不向对话历史塞消息、无全局开关可使其失效。备选路线均已源码级评估（结论沉淀于 .trellis/spec/dsh-plugin/）：agent/pre-step 手动注入的消息会持久化进会话历史（无去重则逐轮累积）；DSH 原生的 systemPrompt.context() 路线仅在内容变化时物化 user-role 快照（自动去重），是未来若迁移的首选路径。现路线无痛点，维持不动。代价是 prompt section 必须同步求值（无法直接执行 Python），因此完整上下文走 pull-based；
- 面包屑只注入主会话（子代理的派发 prompt 自带任务行，与上游跳过子代理的行为一致）；
- 任务状态解析对齐 Trellis 自身契约（与 Web 状态卡共用同一解析函数）：优先精确会话指针 sessions/.json，其次恰好一个指针文件（多窗口 refuse-to-guess），再回退 .trellis/.current-task；
- 非 Trellis 工作区完全不打扰（不注册 section）。

注入效果示例

每轮 prompt 组装时，app:trellis section 会注入类似下面的块（正文来自
workflow.md 对应 [workflow-state:STATUS] 标签，不是写死的文案）：

Status: no_task
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
Simple conversation / small task: ask only whether this turn should create a Trellis task. ...

This workspace uses the Trellis workflow. Follow it: load the trellis-start skill at session start and when a new task arrives, route per the skill routing table in .trellis/workflow.md, and run python3 .trellis/scripts/get_context.py / task.py current for live state. Do not skip the DO-NOT-skip steps.

有活动任务时，首行变成 Task:  ()，正文换成对应阶段（
planning / in_progress / completed…）的指引。完整会话上下文
（developer、git 状态、spec 索引）仍需模型按 trellis-start 技能用 bash
拉取——注入的是“轨道”，不是“全量数据”。

前置要求

- 正在运行的 DeepSeek Harness profile（如 dsh web）
- Python 3.9+（跑 .trellis/scripts/ 的 task.py、get_context.py 等）
- PATH 上有 pnpm（dsh plugin 依赖）

安装

从 GitHub 安装（公开仓库）
dsh plugin --profile web add git+https://github.com/Beants/dsh-trellis.git

或本地 checkout
dsh plugin --profile web add /path/to/dsh-trellis

在 ~/.dsh/profiles/web/cordis.patch.yml 中启用（追加一条顶层 insert）：

- insert:
- name: dsh-trellis
config: {}

验证并重启：

dsh --profile web --dump-config   # 组合树中出现 dsh-trellis 行
重启 dsh web，然后刷新浏览器

快速开始

1. 把会话工作区切到你的项目。
2. 执行 /trellis-init 你的名字——生成 .trellis/（config.yaml、workflow.md、scripts/、agents/ 等）并追加 .gitignore 条目。
3. 用自然语言描述开发任务。agent 会加载 trellis-start，走 规划 → 实现 → 验证 → 收尾 循环：brainstorm 产出 prd.md、派发 trellis-agent-implement / trellis-agent-check 子代理实现与校验，最后 trellis-finish-work 归档任务并写工作日志。

命令

| 命令 | 作用 |
| --- | --- |
| /trellis-init [名字] | 在会话工作区生成/补齐 .trellis/ |
| /trellis-status | 查看当前任务、git 状态、激活任务；输出尾部带 git 护栏（未提交变更清单 + 最近提交，收尾前对账） |
| /trellis-start / /trellis-continue / /trellis-finish-work | 会话入口 / 续作 / 收尾指引 |

配置

配置分三层（后者覆盖前者），上层两层免重启热生效：

schema 默认值 ← profile 插件 config（cordis.patch.yml，需重启）
← ~/.dsh/settings.yaml 的 dsh-trellis 段（外部编辑热发布）

profile 的 patch 层声明全部字段：

- id: dsh-trellis
name: dsh-trellis
config:
injectWorkflowState: true    # 是否注入每轮  面包屑（默认 true；新会话生效）
workflowSectionOrder: -97    # prompt section 顺序（默认 -97；新会话生效）
pythonCommand: python3       # .trellis/scripts 的解释器；Windows 上设为 python
statusCard: true             # Web 状态卡：注册 /trellis-card 路由（默认 true；无 webServer 的 profile 自动跳过）
stallMinutes: 15             # 判定「疑似卡住」的无活动分钟数
circuitBreakerThreshold: 3   # meta.rollbacks.count 达到该值触发熔断警示
dispatchLoopThreshold: 4     # implement↔check 往返达到该轮数才提示打环（默认 4，健康 3 轮不告警）

用户覆盖层写入 ~/.dsh/settings.yaml（下次命令调用/状态轮询/新会话即时生效）：

dsh-trellis:
statusCard: false
stallMinutes: 10

也可以直接在 Web 界面改：设置 → 插件 → Trellis 工作流 标签页可视化读写
全部字段（含「已覆盖默认」标记与一键重置），走 DSH 标准设置写入通道
（revision 冲突保护），无需重启。

Web 状态卡（浏览器半侧）

启用 web profile 时，插件随包下发浏览器 bundle：会话头部一枚状态胶囊
[● 阶段词 · ⚠N]（圆点=健康度，⚠N=待介入数），外加与「对话」「轨迹」并列的
trellis workflow 标签页。面板采用单一设计令牌源并自适应 DSH 明暗主题，包含
三段进度轨道（对齐 workflow Phase Index：规划/执行/收尾 + 段内子状态，当前节点呼吸环、
缺失产物 ⚠ 态）与段位卡片（全段进度常显：每段一张卡，步骤结构与 workflow.md 同步、
完成态按产物/门禁/commit 锚点判定、无锚点步骤「？」态，产物物证行缺失就近红显，产物徽章
可点击——点击经 DSH 原生 workspaces.openPath 在系统默认编辑器中打开（与对话内文件 chip 同
链路）；服务不可用时回退 /api/artifact 文本链接（限任务目录内、防路径遍历、超 2MB 拒绝）、
介入收件箱（PRD 待确认 / 熔断 /
baseline 回归 / 连败 / 卡住 / 证据滞后 / PRD 确认后修订 / 验证链缺口，全部正常时显式安心态）、
按天分组的竖轨时间线、验证链 chips（点击展开节点输出），以及默认折叠的
门禁与基线明细。阶段模型声明化：段位自动跟随 workflow.md 的 Phase 标题，语义可经
.trellis/phase-map.json 覆盖（模板见 assets/phase-map.default.json；两边不一致时收件箱出
info 漂移告警）。面板头部附任务选择器（ 列未归档任务 + 归档历史按需加载——
轮询 payload 只带 archiveTotal 目录计数，下拉内「加载归档…」才拉取最近 10 条
（归档 · 2026-08 形式的按月原生 optgroup，选中即查看该任务的冻结终态），
「再加载 10 条（已加载 N/M）」逐步向旧翻页、加载尽显示「已加载全部 M 条」；
切换即生效并持久化至
sessionStorage）与 ↻ 手动刷新按钮 + "N 秒前更新" 新鲜度标签（只计成功拉取，在途守卫防竞态）。数据由插件
在 dsh 进程内挂载的只读端点 /trellis-card/api/status?cwd=&sessionId=&taskId=（约 5s
轮询、页面不可见暂停）与 /trellis-card/api/archive?cwd=&limit=&offset=（按需分页）提供；
非 Trellis 工作区不渲染任何内容。

会话 ↔ 任务绑定：技能与 /trellis-status 会指引模型以
TRELLIS_CONTEXT_ID="$DSH_SESSION_ID" 前缀运行 task.py，任务即写入当前窗口的
.trellis/.runtime/sessions/.json 指针——多窗口各看各的任务。

技能清单

| 技能 | 作用 |
| --- | --- |
| trellis-start | 会话入口：加载工作流上下文并路由任务 |
| trellis-brainstorm | 需求澄清：逐题提问、调研、收敛 MVP，产出 prd.md |
| trellis-before-dev | 编码前注入 .trellis/spec/ 规范 |
| trellis-check | 质量校验：spec 合规 + lint/typecheck/test + 跨层检查 |
| trellis-break-loop | 深层 bug 分析，沉淀防复发机制 |
| trellis-update-spec | 把新认知写回 .trellis/spec/ |
| trellis-continue / trellis-finish-work | 续作 / 收尾（归档 + 日志） |
| trellis-agent-implement / trellis-agent-check / trellis-agent-research | DSH 版子代理派发定义（subagent 工具 prompt 模板） |
| trellis-channel | 实时多 agent 协作：spawn 工作线程、跨 agent 审查、进度检查、forum 频道 |
| trellis-session-insight | 通过 trellis mem 检索历史会话记忆 |
| trellis-spec-bootstrap | 用 GitNexus 分析代码库 → 生成/刷新 .trellis/spec/ |
| trellis-meta | Trellis 本地架构与自定义指南（多文件，含 references） |

开发（资产再生成）

assets/skills/ 是 trellis init --dsh 的渲染产物（与写入项目的字节一致），
assets/scaffold/ 是 .trellis/ 模板镜像。上游模板更新后一并重新生成：

cd ../Trellis/packages/cli && pnpm build
cd ../../dsh-trellis && node scripts/prepare-assets.mjs   # 同步 skills + scaffold

搭配 dsh-trellis-dashboard（社区插件）

dsh-trellis-dashboard（MIT）是一个
互补的社区插件：本插件是「发动机」（技能 + 命令 + 每轮工作流注入），它是「纯仪表」
（对话视图 Trellis tab：prd.md 验收清单、spec/skill 使用遥测、journal 摘要、
Set-as-current-task 按钮）。两者可同时安装：

- 槽位不冲突：本插件注册 trellis-workflow tab + 状态胶囊 + 设置页，它注册独立的
trellis tab；
- 路由不冲突：/trellis-card vs /dsh-trellis-dashboard/state；
- 它唯一的写操作（会话指针）正是本插件当前任务判定链第一优先读取的同一文件，
天然互通（源码级验证，未实机联跑）。

dsh plugin --profile web add dsh-trellis-dashboard

本仓库计划吸收其 spec/skill 使用遥测与任务卡内容增强（见
.trellis/spec/dsh-plugin/dsh-runtime-pitfalls.md 的来源注记），届时重叠功能以本插件为准。

与 Trellis 上游的配合

本插件完全自包含（运行时行为与 trellis init --dsh 等价，见上方对照表）。
此外，Trellis CLI（packages/cli）现已注册 dsh 平台：

- trellis init --dsh 会把同样的技能写入项目 .dsh/skills/，DSH 的文件系统
技能提供者会自动发现（项目级优先）——适合团队仓库共享标准；
- 插件侧提供命令、脚手架与会话体验，两者可同时使用，内容保持一致。

本项目是如何实现的

本项目（本插件 + Trellis 上游的 dsh 平台注册）完全由 DeepSeek V4 Flash
（max reasoning effort）+ DeepSeek Harness (dsh) 会话完成*，无人工手写代码：

- 设计：研究 DSH 的 Cordis 插件机制（ctx.skills / ctx.commands /
systemPrompt.section / agent/created 事件）与 Trellis 的 14 平台集成架构
（AI_TOOLS 注册表 + configurator + 模板渲染），在 DSH 的 prompt-section
等价机制上推导出 hook 等价注入方案；
- 实现：技能内容由 Trellis CLI 的渲染产物同步（prepare-assets.mjs），
命令、脚手架、面包屑注入均在会话中编写；
- 上游合并：拉取落后 292 个提交，解决 7 处冲突（含上游新增 7 个平台），
1672 个测试全绿后推送；
- 发布：GitHub CLI 建仓、topic、可见性配置均在本会话完成。

致谢与许可证

- Trellis（Mindfold，AGPL-3.0-only）：
感谢其开源的结构化工程工作流。本插件随包分发其技能渲染产物与 .trellis/ 脚手架
（scripts/prepare-assets.mjs 可随上游更新一键再生成），派生关系决定许可证，
因此整体以 AGPL-3.0-only 发布，见 LICENSE。
若未来需要更宽松的许可证，前提是将技能与脚手架内容完全重写而非派生——另一条已知
路线是"流程语义重写 + MIT"（同类项目
@banana-peeljj12/dsh-trellis
即此路线），代价是放弃与上游渲染产物的同步能力。
- DeepSeek Harness：插件运行
其上的 agent 运行时底座（Cordis 插件体系、prompt section、web client bundle、
cooperative waterfall 扩展点）。