dsh-trellis

Trellis 工作流适配进 DeepSeek Harness —— 每步触发 · 技能引导 · 阶段可见



每回合注入项目任务状态面包屑，把 trellis-* 技能随项目供给，
并提供建任务 / 查阶段的原生工具与 Web 界面阶段徽标。

dsh-trellis 是 Trellis 工作流在 DeepSeek Harness（DSH）上的适配移植—— 本项目只是把 Trellis 的流程语义接到 DSH 上，不是新的工作流体系，也不属于 Mindfold 的官方产物。自包含、MIT、零外部运行时：不需要 Python、 不携带任何 Trellis AGPL 源码，状态机与技能内容均为本包重写；运行时按各项目自身的 .trellis/ 读取，因此直接继承已有 Trellis 项目的沉淀。

✨ 功能一览

• 🧭 每步触发（面包屑注入）：订阅 agent/pre-step waterfall，命中白名单项目后读取 .trellis/.runtime/sessions/*.json 的 current_task → task.json.status → 阶段，并把一条 user 角色面包屑注入本轮消息流（等价 Trellis 官方 per-turn breadcrumb，提醒而非强制）。只在新 用户消息的首步注入；消息含 no-trellis 等关键词时整轮跳过。
• 🧩 技能随项目供给：15 个 trellis-* 技能随包携带（包内 skills/ 为权威副本），会话开始时 检测项目 .agents/skills/——缺则复制（含共享 _templates/）、有则跳过；由 harness 内置的 dsh-skill-filesystem provider 从项目根发现（source: project-agents），无需注册、无需改 profile。项目可自由增改自己的技能副本，删掉的技能下轮自动补回。
• 🛠️ 建任务一步到位：trellis_task_create 一次性完成「写 .trellis/tasks/<slug>/task.json （status=planning）+ 播种该工作类型的产物模板 + 首次使用初始化 .trellis/templates/ + 同步写 .trellis/.runtime/sessions/ 的 current_task 指针」——修掉"只建 task 不同步 session，导致 解析不到 active task"的常见问题。
• 🔍 阶段诊断：trellis_state 工具随时回答"某项目当前处于工作流的哪个阶段"，并校验任务 slug。
• 🏷️ Web 阶段徽标：web profile 下会话标题行右侧嵌入一枚徽标（官方 additive 座位 conversation.session.header.utilities），紧凑展示当前活动任务的类型与阶段（如 功能 · design）， 悬停/点击展开该工作类型的完整阶段轨道；数据来自 host 按会话发布的只读缓存摘要，浏览器请求 绝不触发项目解析或文件读取。headless（无 web 服务）profile 下此功能整体不激活，其余功能不受影响。
• ✅ slug 校验：活动任务目录必须符合 <work-type>-<mm-dd>-<name>（如 feat-01-15-billing-export）；不合规时每轮面包屑与 trellis_state 都会给出修正提示。

🧠 工作流模型

插件内置三类工作流——通用化改编自 CodeStable （FTM/CodeStable 思路，内容为本包重写、MIT），由 _templates/work-types.md 路由表驱动：

• 原生 status 仍只用 planning → in_progress → completed（archive）；细阶段放在 work.stage + 产物文件，仓库产物优先于聊天历史。
• Standard 车道带人卡点：design 需用户 approve、design-review 需独立 reviewer passed、check 必须通过后才能 archive；人卡点未过时禁止写 status=in_progress。
• 新任务目录名必须为 <work-type>-<mm-dd>-<短名>（mm-dd 为创建日期）。

随包 15 个技能（skills/，权威副本，按需复制到项目 .agents/skills/）：

trellis-start · trellis-brainstorm · trellis-before-dev · trellis-check · trellis-update-spec · trellis-finish-work · trellis-continue · trellis-break-loop · trellis-channel · trellis-meta · trellis-session-insight · trellis-spec-bootstrap · trellis-feat · trellis-issue · trellis-refactor

外加共享产物模板 _templates/（feat/ issue/ refactor/ + work-types.md 路由表），随技能一并 复制到项目 .agents/skills/_templates/。

🚀 安装

前置：DSH 已装好（dsh web 能正常运行），Node.js ≥ 20。

# 从 npm registry（发布后）
dsh plugin --profile <name> add dsh-trellis

# 从本地源码 checkout（开发）
dsh plugin --profile <name> add link:/abs/path/to/dsh-trellis

# 从打包 tarball（pnpm pack，无需发布）
dsh plugin --profile <name> add file:/abs/path/to/dsh-trellis-0.1.0.tgz

包声明了 dsh.bundle.patch（随包的 cordis.patch.yml），add 后由 loader 的 reconcile 自动把包 并入该 profile 的 dsh.profile.bundles 层栈，重启 DSH 即挂载（host 半改动；client 半硬刷新 浏览器生效）。卸载同样走 CLI，配置行与依赖一并清除：

dsh plugin --profile <name> remove dsh-trellis

dsh plugin --profile <name> add dsh-trellis

⚙️ 配置

cordis.patch.yml（或宿主 profile）中挂载本插件的行：

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

配置分层：

schema 默认值 <- cordis.patch.yml 的 config（base）<- Web 设置页的用户文档

🛠️ 开发与构建

dsh-trellis/
  package.json            # ESM cordis 插件包（name: dsh-trellis, MIT）
  cordis.patch.yml        # dsh.bundle.patch 自激活层（insert 插件行）
  lib/
    index.js              # 主入口：agent/pre-step 面包屑 + 技能供给 + trellis_state / trellis_task_create + Web 徽标
    task.js               # trellis_task_create 写入侧：slug 校验 / task.json 构造 / 模板播种 / session 指针同步
    resolve.js            # cwd → 项目根 + .trellis 资产路径
    state.js              # 阶段解析：session → 活跃任务 → status → phase + workflow.md 面包屑 + 任务摘要/轨道
    breadcrumb.js         # createUserMessage 构造注入消息 + no-trellis 逃生口
    trust.js              # 本地同源 / 防 DNS-rebinding 围栏（Web 只读路由）
    skills.js             # 技能供给：检测项目 .agents/skills/ 并复制缺失技能与 _templates/
    settings.js           # 可选 settings 命名空间（Web 设置页）
    meta.js               # 名称 / 配置 Schema / 默认值
    types/index.d.ts
  skills/trellis-*/SKILL.md   # 15 个随包技能（权威副本）
  skills/_templates/          # 产物模板 + work-types.md 路由表
  scripts/install.mjs         # 传统安装器（bin: trellis-install）

纯 JavaScript、零构建、零运行时依赖（@deepseek-ai/* 为 peer，由 web profile 提供）；client 半是 手写零构建 bundle，经公共 slot 系统注册（阶段徽标用官方 additive 座位 conversation.session.header.utilities）。传统安装器 scripts/install.mjs 仍是可用的备选工具 （不依赖 dsh.bundle，直接维护 cordis.patch.yml 行 + 依赖链接）：

🔐 安全

• Web 徽标数据来自 host 侧只读缓存：POST /trellis-workflow/api/task-state 只接收 { sessionId }，响应绝不含路径；浏览器请求永不触发项目解析或文件读取（cache miss 返回稳定 空态，与未知会话不可区分，防探测）。
• 路由受本地信任围栏保护（回环 host + 同源标记，等价官方 isTrustedApiRequest 语义），并做 method / 路径 / 请求体大小校验；错误只返回稳定状态词，不泄露内部细节。
• 任务创建与技能复制全部走 ctx.fs + 每调用沙箱策略；沙箱拒绝映射为标准 [sandbox: …] 标记， 与 harness 编辑工具走同一升级流程。
• 技能供给失败只告警、绝不打断当轮注入（缺失技能下轮可补复制）。

⚠️ 已知限制

• headless（无 web 服务）profile 下 Web 阶段徽标整体不激活，其余功能不受影响。
• 只在会话 cwd 命中 allowlist 的项目里注入；项目需自带 .trellis/（无 workflow.md 时用内置 兜底面包屑文案）。
• Web 设置 RPC 仅限本机回环（harness 全局限制）。
• slug 校验是提醒而非强制——不合规的任务仍可推进，只是每轮收到修正提示。
• 只消费 Trellis 流程语义，任务文件布局需与 .trellis/ 约定一致。

🖥️ 平台支持

Windows / Linux / macOS 均可（纯 Node ESM，无原生依赖、无构建产物差异）。Node.js ≥ 20。

🙏 致谢

dsh-trellis 是 Trellis（作者 Mindfold，AGPL-3.0-only）在 DeepSeek Harness 上的适配移植：

• 只复用 Trellis 的流程语义（active-task 面包屑、[workflow-state:*] 阶段块、阶段轨道与 产物约定），不复制其代码与文档正文；
• 本包不含任何 AGPL 源码，状态机、技能与模板均为独立重写，以 MIT 许可发布；
• 本项目与 Mindfold 无隶属、无背书关系，只是 Trellis 思路在 DSH 生态的第三方适配； 部署 Trellis 本体时请遵循其 AGPL-3.0 许可条款。

感谢 Mindfold 团队设计并开源了 Trellis 工作流。

内置的三类工作流（feat / issue / refactor）则通用化改编自 CodeStable（源自 FTM/CodeStable 思路）——同样只参考 流程设计、内容为本包重写；感谢 CodeStable 团队的流程设计。

🔗 友情链接

• DeepSeek Harness —— 本插件的宿主
• dsh-better-sidebar —— 服务化侧边栏工作台插件
• Trellis —— 被适配的工作流本体（本插件仅移植其流程语义）
• CodeStable —— 三类工作流（feat / issue / refactor）的改编来源

许可

MIT。本包不含 Trellis AGPL 源码；工作流语义参考 Trellis，内容为本包重写。