CJ-SH/dsh-plugin-trellis-statusline

dsh-plugin-trellis-statusline

在 dsh 网页聊天中显示当前工作空间的活动 Trellis 任务——这正是 Claude Code 的 statusline.py 钩子在终端中所做的工作，也是 dsh 的网页 shell 所没有的状态栏。

这是一个状态栏：一个紧凑的小药丸，始终可见，就在你正在查看的聊天中。

[P2] Add the importer · 进行中
[P1] Release 0.2 · 进行中 · 父任务
[P2] Wire the importer · 进行中 · 子任务

它是什么

Trellis 将每一项工作作为一个任务保存在 .trellis/tasks/ 下，并记录某个会话正在处理哪一个。dsh 的网页 shell 会显示工作空间和模型，但不会显示任务——因此你必须切回终端，或者询问 agent，才能知道你实际正在做什么。

这个插件把这一事实放进聊天中：

- 会话头部，位于会话预设选择器的右侧，作为一个紧凑的小药丸；
- 新会话视图，用于尚未发送第一条消息的会话。

它是纯读取的：它从不写入 Trellis，不启动或归档任何东西，并且在没有任何任务时完全不显示任何内容。

要求

| | |
|---|---|
| dsh | 带有 web 配置文件。已针对 0.1.5-rc.2 验证；它所附加的座位是内部的，因此 dsh 升级可能会移动它们——参见故障排除 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 一个由 Trellis 管理的工作空间 | dsh 是 Trellis 第 22 个受支持的平台——在工作空间中运行 trellis init --dsh（Trellis 文档）。会话的工作目录随后包含 .trellis/，这就是此插件所读取的全部内容 |

它在运行时不需要 Python，也不需要 trellis CLI。与那些驱动 task.py 的插件不同，这个插件只读取 Trellis 写入的 JSON。

安装

这个包是一个 dsh bundle：它声明了带有 cordis.patch.yml 的 dsh.bundle，安装它会把该 bundle 追加到配置文件中并应用其补丁层（官方指南）。

从 npm 安装——尚未发布，这是它发布后的命令：

dsh plugin --profile web add dsh-plugin-trellis-statusline

目前，直接从仓库安装。要么克隆：

git clone https://github.com/CJ-SH/dsh-plugin-trellis-statusline
dsh plugin --profile web add ./dsh-plugin-trellis-statusline

……要么使用 git URL，这样你无需自己克隆：

dsh plugin --profile web add github:CJ-SH/dsh-plugin-trellis-statusline

git 方式在这里无需通常的 prepare 脚本和 allowBuilds 许可即可工作，因为没有什么需要构建：lib/ 是提交到仓库中的纯 JavaScript，因此 git 安装
已经获取可运行的产物。用 TypeScript 编写的插件两者都需要，而 allowance 是允许在安装时在你的机器上运行其代码的许可——参见
官方说明。

然后检查该行是否已写入，并重启 dsh——插件的加载发生在启动时，而重启会结束任何 agent 进程，所以请自行运行：

dsh --profile web --dump-config | grep trellis-statusline

可用的安装无需任何配置：插件会读取它所渲染所在的会话，并且不保存任何设置。

卸载

dsh plugin --profile web remove dsh-plugin-trellis-statusline

它不存储任何内容，因此卸载无需清理。

不会触碰其他 bundle 的行

该补丁只插入一行 loader，别无其他。Host 部分在组合的 webServer 上注册自己的路由，并在每次应答前向 connection 请求信任围栏
（requestRejection → 401/403，当该接缝缺失时为 503）——这与随附的 dsh-host-open-in-app 使用的形态相同。

较早的版本改为扩展随附的 connection 行的 inject。这正是
connection.rpc.handle 所需要的——它在那一行的上下文上注册其物理路由——而这使该插件的可用性依赖于另一个 bundle 配置的一部分以及层顺序。自己拥有该路由消除了这种耦合：这里的任何内容都不会因补丁冲突而被悄悄移除。

你将看到什么

该 pill 显示为 [priority] title · status。根据任务不同，有三种形态：

| 会话的任务是 | 该 pill 显示为 |
|---|---|
| 独立存在 | [P2] Title · 进行中 — 无角色、无点击目标、无 Tab 停靠点 |
| 树的根 | [P1] Title · 进行中 · 父任务 |
| 树中的其他任何位置 | [P2] Title · 进行中 · 子任务 |

只存在两种角色。 树的最顶层祖先是唯一一个父任务；其他所有成员——包括孙级——都是子任务。深度从不改变措辞，因此很深的树也能保持可读。

当任务位于树中时，该 pill 变为可点击。 下拉菜单显示真实结构（每层深度缩进一级，并带有一条引导线），并高亮显示会话的任务。独立任务完全不可点击——没有按钮、没有焦点环、没有 Tab 停靠点。

显示每 10 秒刷新一次，并在头部切换到另一个会话时立即刷新，因此 task.py start 或 task.py archive 会在一次轮询内显示出来。

任务来自哪里

1. 会话的工作目录——来自活动会话自身的头部，或来自工作区注册表，后者也涵盖不再活动的会话。
2. 会话指针——.trellis/.runtime/sessions/dsh_.json，由
task.py start 写入。只要它指向一个真实任务，它就优先。
3. 扫描 .trellis/tasks//task.json——in_progress 优先于 planning，在同等条件下取最新的 MM-DD- 任务。被扫描到的任务还必须至少启动过一次，而一个
已记录的 branch 证明。

最后一条规则很有价值：trellis init 会留下一个脚手架任务（Bootstrap Guidelines），其
status: in_progress 且没有 branch，永远如此。如果没有这项检查，每个全新的 Trellis 项目
都会将其报告为活动工作——在构建此插件时所针对的五个真实工作区中，有四个恰好存在这个陈旧任务。
参见设计说明。

它不做什么

- 它从不写入。 Host 部分导入 node:fs/promises 仅用于 readFile 和 readdir，
完全不包含任何写入路径；自检证明一次完整读取后 .trellis/ 保持字节级一致。
- 它不会启动、切换或归档任务——那仍然是 task.py 的职责。下拉菜单只是一个视图，
而非控件：其行不可点击。
- 它不会重复 dsh 已经显示的内容（模型、token、耗时）。
- 对于由扫描发现的 review 任务，它没有可显示的内容（指针仍会显示它，
显示为 审核中 / in review）。要改变这一点，请在 lib/index.js 中扩大 RUNNING_STATUSES。

故障排除

完全没有显示任何内容。 按可能性排序：工作区没有 .trellis/；有 .trellis/ 但从未在其中
启动过任何任务（参见分支规则）；你处于新会话视图，且无法测量
composer；另一个 bundle 占用了确切路由 /trellis-statusline/task/read（Host 会在启动时记录
[trellis-statusline] route unavailable）；或者 dsh 升级移动了座位。该插件从不显示占位符，
也从不报告错误——不显示 pill 就是失败模式，这是设计使然。

它显示了错误的任务。 检查 python ./.trellis/scripts/task.py current --source。如果这与
pill 不一致，说明插件的扫描与 Trellis 的指针解析已经出现分歧——请同时附上两者提交 issue。

它显示工作区最新的任务，而不是你启动的那个。 如果 dsh 是从另一个 Trellis 会话内部启动的
——比如一个 Claude Code 或 Codex 窗口——Trellis 0.6.15 会继承该会话的 TRELLIS_CONTEXT_ID，
并可能将运行时指针写入外层*上下文键下（一般情况已在上游跟踪，
mindfold-ai/Trellis#549；
Trellis 0.6.15 已针对 dsh 专门修复了此问题）。此插件随后找不到自己会话的指针，便回退到
工作区扫描——这正是该回退存在的原因。在启动 dsh 前取消设置 TRELLIS_CONTEXT_ID，或者
在 dsh 会话本身中运行 python ./.trellis/scripts/task.py start .trellis/tasks/。

它在一个会话中出现，但在另一个会话中不出现。 这就是设计：每个会话报告自己的工作目录，
因此不同工作区中的并行会话会显示不同的任务。

开发

没有依赖，也没有构建步骤：浏览器部分直接以 shell 所消费的形式编写，Host 部分除 node:
内置模块外不导入任何内容，测试套件对两者都进行断言。

node --check lib/index.js && node --check lib/client.js   # 两半都能解析
npm test                                                  # 197 条断言，四个测试框架

这些测试框架位于仓库中，而不在发布的 tarball 里——files 只发布 lib、
补丁、README、设计说明和许可证——所以请从检出目录运行 npm test。

| 测试框架 | 覆盖内容 |
|---|---|
| test/host.test.mjs | 在一次性工作区中解析任务：优先指针、扫描回退、排序、branch 规则、每一种树情况，以及读取永不写入的前后哈希证明 |
| test/client.test.mjs | 打包契约：id、仅 react 的 require、两个席位（slot key 与 cell id 与顺序）、locale 命名空间、样式表生命周期、跨半部分常量 |
| test/cell.test.mjs | 最小 hook 运行时下的真实 cell：全部三种 pill 形态、下拉菜单及其关闭路径、Hero cell 的空白会话门控与测量位置、监听器和定时器清理 |
| test/integration.test.mjs | 两半相互对接——真实的 Host 半部分读取真实的 .trellis 树，并且该确切回复被送入真实 cell，因此线格式漂移无法被忽视 |

| 文件 | 作用 |
|---|---|
| lib/index.js | Host 半部分——session → cwd → task，以及 /trellis-statusline/task/read 路由 |
| lib/client.js | 浏览器半部分——模块加载器 bundle、席位注册、cell |
| cordis.patch.yml | 加载器行；不修补任何其他 bundle 的行 |
| docs/design-notes.md | 为什么这样工作：席位、测量、推导规则 |

许可证

MIT © 2026 HenTaiCJN

Trellis 是 Mindfold LLC 的一个独立项目，采用
AGPL-3.0-only 许可。本插件与其无关联，既不捆绑也不派生自其代码：
它读取 Trellis 写入的 .trellis/ 文件。