QianziTech / dsh-trellis-dashboard

dsh-trellis-dashboard

Trellis × DSH workspace dashboard. Adds a Trellis tab to the DSH conversation-view ring that projects the current workspace's .trellis/ state:

1. 当前任务 + 进度 — task list + current-task resolution (per-session pointer only; no guessing from task statuses — an unbound conversation shows "暂无 trellis 任务" instead of another task) + task card with the prd.md acceptance checklist; a "设为当前任务" button writes the per-session pointer.
2. 规范 / 技能使用 — live spec-file reads (fs/observed on .trellis/spec/**, .agents/skills/**, .dsh/skills/**) and skill tool loads (tools/result), scoped per session (exec.agent.id) so one conversation's activity never leaks into another's dashboard.
3. 工作区会话汇总 — developer journal index + latest journal-N.md excerpt.

Markdown is rendered in the tab (headings, lists, task lists, tables, code, blockquotes) with a small built-in renderer — no external runtime dependency.

Folder structure

dsh-trellis-dashboard/
├── package.json          # dsh plugin manifest (bundle patch + dsh.client)
├── cordis.patch.yml      # inserts the HOST row into the web profile composition
├── lib/
│   ├── index.js          # HOST half  — fs reads + usage tracking + HTTP JSON API (webServer)
│   └── client.js         # CLIENT half — conversation.view tab + markdown rendering (browser bundle)
├── README.md
└── LICENSE

• package.json → exports["."] = host entry, exports["./client"] = client bundle.
• dsh.bundle.patch → the cordis patch that loads the host half.
• dsh.client → the web client-module manifest (platform: "web" + inject).

Architecture

• Host half reads .trellis/ through ctx.fs (never runs python task.py scripts) and exposes the dashboard JSON API as webServer HTTP routes (GET /dsh-trellis-dashboard/state, POST /dsh-trellis-dashboard/set-current-task). It also subscribes to fs/observed + tools/result for the usage section.
• Client half registers conversation.view (id trellis, order 20 — pure addition, no shipped UI replaced), resolves the current workspace from useWorkspaces, polls the host API every 5 s while the tab is mounted, and renders with React.createElement + a self-contained markdown renderer.
• Published channel is HTTP (host.call / harness.handle exist only for dynamic runtime plugins). The client polls because there is no Host→Client push channel.
• .trellis/ is read-only except the one session-pointer write in set-current-task (replicates trellis task.py set_active_task).

There is also a dynamic runtime prototype (the same feature delivered as a cordis_define/cordis_run plugin, using harness.handle/host.call) — its reference copy lives in plans/trellis-dashboard-plugin.js (FROZEN historical snapshot, behavior synced to lib/ as of 2026-08-17: pointer-only current-task resolution + per-session usage scoping). The published package in lib/ is the source of truth going forward.

部署指南（Deployment）

本插件有两种部署形态：发布包（装进 web profile，长期可用）和动态原型（当前会话临时生效，无需安装）。部署约定对照官方文档 Package and install a plugin。

方式 A：发布包 → 装进 web profile（推荐长期使用）

本仓库根目录即一个 dsh bundle（package.json 声明 dsh.bundle.patch；dsh.client 声明浏览器半）。安装到 $DSH_HOME/profiles/web：

# 1) 本地目录安装（从仓库上一级目录执行）
dsh plugin --profile web add /path/to/dsh-trellis-dashboard
#    首次会初始化 profile，pnpm 链接本包并追加到 dsh.profile.bundles

# 2) 验证组合层已生效（无需启动即可看插入的行）
dsh --profile web --dump-config        # 应出现 "# == dsh-trellis-dashboard" 层

# 3) 重启 dsh web（重新加载组合 + 重建客户端模块）
#    打开 http://127.0.0.1:3080 → 会话头部出现 Trellis 标签

从 GitHub 安装（拉源码，非产物，需要两侧配合）：

dsh plugin --profile web add github:QianziTech/dsh-trellis-dashboard#<sha>
# ① 作者：package.json 需提供 `prepare` 脚本（构建 lib/ 产物）
# ② 用户：pnpm≥10 拒绝运行 git 依赖的 prepare，需在 profile 的
#    pnpm-workspace.yaml 加入并重新 add：
#      allowBuilds:
#        dsh-trellis-dashboard: true

从 npm / tarball 安装（分发预构建产物，无需任何构建授权）：

npm publish                              # 发布到 registry
dsh plugin --profile web add dsh-trellis-dashboard

pnpm pack                                # 打 tarball
dsh plugin --profile web add ./dsh-trellis-dashboard-0.1.0.tgz

重要：发布版 lib/client.js 是自包含浏览器 bundle，改动后需重建 web 产物（重跑对应 profile 的 web build / dev:web watcher）才会生效；host 半（lib/index.js）随组合重启加载。安装方式 A 后，Client→Host 走 webServer HTTP 路由（GET/POST /dsh-trellis-dashboard/…）。

卸载：

dsh plugin --profile web remove dsh-trellis-dashboard   # 移除依赖 + 组合层

方式 B：动态原型（当前会话临时，无需安装/重建）

运行时动态插件（cordis_define / cordis_run），使用 harness.handle/host.call 包私有 RPC 和 styles/host 全局；参考源码在 plans/trellis-dashboard-plugin.js。 在 GUI 会话中 cordis_define 定义、cordis_run 激活（需批准），修改后追加新 Package 再 update。 动态形态无需重建 web 产物，适合快速迭代；重启进程后丢失，长期使用应回到方式 A。

排错速查

现象	处理
装完没有 Trellis 标签	客户端 bundle 未重建 → 重跑 web build / dev:web；或组合未含本层 → --dump-config 核对
host 路由 404	webServer 路由未注册 → 确认 inject: ['fs','webServer'] 且 profile 是 web
动态插件激活失败	cordis_inspect_self(pluginId, packageId) 读诊断 → 同插件追加修正版再 update
GitHub 安装报 pnpm 拒绝构建	见上 allowBuilds，并核对 prepare 脚本

Development

npm run check   # node --check lib/index.js && node --check lib/client.js
npm test        # node --test test/ — contract + coupling + spec-consistency tests

插件开发规范（框架级）已沉淀到 .trellis/spec/dsh-plugin/；对应自动化测试见 test/（manifest / cordis / host / client / coupling / spec-consistency）。

The plugin is dependency-free plain JavaScript. No build step is required to read the sources; the client bundle is written directly in the web app's window.__ModuleLoader__.load({ id, factory }) format.

License

MIT