dsh-trellis

August 27, 2026 · View on GitHub

简体中文 · 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-state>` 面包屑（workflow.md 的 `[workflow-state:STATUS]` 标签 + 当前 task.json 状态）	`app:trellis` prompt section，每次 prompt 组装重新求值：`<trellis-workflow>` 块带 `Task: <id> (<status>)` 与 workflow.md 对应阶段的指引正文
`inject-subagent-context`	子代理 prompt 注入 prd/implement.jsonl 上下文	`trellis-agent-*` 技能的 pull-based prelude：派发 prompt 首行 `Active task: <path>`，子代理自行读取 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/<sessionId>.json，其次恰好一个指针文件（多窗口 refuse-to-guess），再回退 .trellis/.current-task；
非 Trellis 工作区完全不打扰（不注册 section）。

注入效果示例

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

<trellis-workflow>
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.
</trellis-workflow>

有活动任务时，首行变成 Task: <id> (<status>)，正文换成对应阶段（ 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，然后刷新浏览器

快速开始

把会话工作区切到你的项目。
执行 /trellis-init 你的名字——生成 .trellis/（config.yaml、workflow.md、scripts/、agents/ 等）并追加 .gitignore 条目。
用自然语言描述开发任务。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    # 是否注入每轮 <trellis-workflow> 面包屑（默认 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 漂移告警）。面板头部附任务选择器（<select> 列未归档任务 + 归档历史按需加载—— 轮询 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/<sessionId>.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 扩展点）。