@xx529

dsh-terminal-panel

Name: dsh-terminal-panel
Availability: InStock
Author: xx529

DeepSeek Harness 插件「终端」：在会话头部聚合当前会话 / 子代理 / Agent Team 队友的 bash、后台任务与持久终端实时输出（只读）。

Stars: 0
Language: JavaScript
Created: Oct 26, 2026
Updated: Oct 26, 2026

Web UI

GitHub repo

Introduction

dsh-terminal-panel · 终端

DSH（DeepSeek Harness）插件：在会话头部新增「终端」View tab，把 当前会话 + 子代理 + Agent Team 队友 的 bash 前台执行、后台任务（jobs）、持久终端（terminals）输出聚合成只读的卡片网格面板（v8）。

仓库：https://github.com/xx529/dsh-terminal-panel

状态：v0.1.0 代码侧已交付（2026-10-26，v11） — Host 半端 + Client 半端实现完成、真机安装与视觉验收待做（见 docs/install.md）。门禁：364 tests / 364 pass / 0 fail / 0 skip / 0 todo；smoke 91/91；npm run verify exit 0（tester T60 最终报告）。v7 真机反馈 5 项已代码侧修复（见下方「真机反馈修复（v7）」），真机复验待做。

门	结果	命令
语法自检	通过	`npm run check`
单测	364 tests / 364 pass / 0 fail / 0 skip / 0 todo（`node:test` 零依赖；tester T60 最终报告）	`npm test`
Host mock 冒烟	PASS — 91/91 checks passed，exit 0	`npm run smoke`
一键全验	check → test → smoke，exit 0	`npm run verify`
契约	v11（P0 会话隔离：帧/增量/removed/prune/resync 按会话树）	`docs/architecture/contract.md`

T6 集成审计（commit ad39516）：无 CRITICAL；HIGH H1（Tier2 单 Run livelock）与 MEDIUM M2（选择集错配）已由 backend 修复（commit 4bc721e，含 R1/R2 回归），M1（菜单两项）已裁决不做；LOW L1–L5 见 contract §12.10。

真机反馈修复（v7，代码侧已修 / 真机复验待做）

2026-10-26 用户真机反馈驱动（5 项缺陷 + scout 补充 2 项显示/状态），Lead 裁决契约 v6→v7（Host = T31，Client = T32）：

#	缺陷	修复（代码侧）
1	轮次里有 `terminal_open/send/read`，面板「终端」恒 0 条	Host 发现链路（v7 纠偏）：`terminals.list(agent)`（agent PTY）→ `tools/execute` 事件兜底（默认有效）；`terminalController`（侧栏终端注册表）默认关闭、开启时标 `sidebar` 且不与 agent PTY 混排；agent 缺失不再删 Run（`meta-only` + `notice` + tier3 片段），`PollResult.diagnostics` 每帧可查
2	界面每 250ms 跳动	入场动画只首挂载播放；工具栏单行不换行；面板填满高度（运行列固定 + 已完成区自适应滚动）；倒计时徽标固定占位；跟随滚动只用容器 `scrollTop`（禁 `scrollIntoView`）
3	标题只看得到半截命令	标题只显示命令第一条非空行（折叠空白、超长 `…`、多行 `+N 行`），完整命令在 `title` 与输出面板
3b	输出区看不到输入	输出区顶部新增输入块：bash/job 完整 `command`（`$` 前缀）；terminal `$ name` + `inputs`（`›` 前缀）+ 分隔线；空输出仍显示；`notice` 提示行在输入块上方
4	命令结束立刻收起、收起后还在倒计时	终态后先展开 + 倒计时 10s（v7 历史机制，已废弃、不生效），到点才折叠（`expanded:false` 且 `deadline:null`），折叠后不再显示倒计时/进度条；新增 `collapseVisual` 纯函数
5	终端 tab 仍显示会话输入框	终端 tab 激活时隐藏 composer（优先官方能力；否则 `[data-conversation-content]` + `data-tp-composer-hidden` + CSS 隐藏 `[data-composer-seat]`，找不到锚点静默降级）；失败不影响其它 tab，卸载幂等恢复
6	行内 agent/会话名显示 sessionId 长串	显示名按 `sessionTitle → sessions 标题 → team/subagent 名称 → 「当前会话」` 取，空值 `—`；rootAgent 缺失仍能列出队友（`Agent` 无 `name` 字段）
7	meta-only 列误导（看起来在运行）	必须显示 `notice` 降级提示、不显示「运行中」动画；tier3 片段标注「非实时全量」

说明：以上为代码侧修复；真机复验清单见 docs/design/ui-spec.md v5 §9 的 A1–A13（A7–A13 含 manual 项），不得据此宣称已真机验收。

展示层 v8（真机反馈修复，代码侧已修 / 真机复验待做）

2026-10-26 展示层重构（契约 v8 / ui-spec v6；Host 协议不变）：

#	变更	说明
1	执行区网格	固定宽卡片（默认 352，可拖 280–640）自动换行 + 整体纵向滚动；横向滑动/横向滚动条/右侧 `›` 溢出按钮作废（取代 v5 横向列）
2	Run 三态	`running → linger`（终态后滞留 3s；v8 原 10s，v11.1 起 3s：倒计时 + 「收起」按钮，hover/focus 暂停） `→ completed`（移入已完成分组）；v7「新终态自动展开分组」删除（替换）
3	会话状态缓存	模块级 `SESSION_CACHE`（LRU 4 / TTL 30min）保存 `{view,cursors,revision,savedAt}`；切 tab 回首屏不空、游标续传；`retryToken` 变化不清 view
4	动画 + 加载态	离开执行区 fade+scale ≈180ms + 其余卡片 FLIP 200ms（仅 transform/opacity，`prefers-reduced-motion` 瞬时）；首帧前 skeleton，loading ≠ 空态（避免 job-only 抖动）
5	Host 一致性补丁	`panel.poll {resync:true}` 全量重同步（不发 removed）；`removed`/`runs` 同帧互斥（runs 优先，`prune(protect)` 防 job 抖动）；`revision` 回退=服务端重建 → 清 view + resync（不再冻住）

以上为代码侧修复；真机复验清单见 docs/design/ui-spec.md v6 §9 A14–A22（均含 manual/Unverified），不得据此宣称已真机验收。

可达性 / 视觉 v9（真机修复，代码侧已修 / 真机复验待做）

2026-10-26 真机反馈驱动的可达性与视觉修订（契约 v9 / ui-spec v7）：

#	变更	说明
1	已完成行独立展开	展开由 `view.group.expandedIds` 布尔集合驱动，行头/组头均可点击；已完成行不再渲染 10s 倒计时/进度条（v7 历史值，不生效；样式/词典暂留，测试兼容；修复「点不开 + 仍显示 10s 后收起」）
2	执行区按行铺满	CSS flex：`.tp-cell{flex:1 1 var(--tp-card-w,352px);min-width:min(280px,100%);max-width:100%}`，基准 352、拖右缘 280–640、窄容器单列，无横向滚动；不计算列数/不做 resize 重算；取代 v8 固定 352 自动换行
3	状态色板	进行中黄、已完成绿、失败红（`--dsw-alias-state-{warn,success,error}-primary`）；hover/focus 不改布局尺寸
4	树外 owner terminal 可 live	tier1 Agent 解析范围扩为 `scopes ∪ terminal ownerSessionId`；树外 owner 命中 live 即读实时输出并清 `notice`（未命中仍 meta-only 可见）
5	诊断扩展	`diagnostics` 增 `agentsService` / `agentsProbe{getOk,sampleIds}` / `terminalOwners{captured,alive,inScope,outOfScope}`，便于真机定位

以上为代码侧修复；真机复验清单见 docs/design/ui-spec.md v7 §9 A23–A28（均含 manual/Unverified），不得据此宣称已真机验收。

视觉 / 结构 v10（真机修复，代码侧已修 / 真机复验待做）

2026-10-26 真机驱动的视觉/结构修订（契约 v10 / ui-spec v8，纯客户端）：

#	变更	说明
1	2px 状态边框	`.tp-col`/`.tp-row` 生效 2px（旧 1px 仅供旧测试断言）；进行中黄 65%、linger/已完成绿 60%、失败红 65%；hover/focus 用 `inset box-shadow` 视觉加粗、不改盒尺寸
2	统一卡宽 + grid 铺满	`repeat(auto-fill,minmax(min(100%,var(--tp-card-w,352px)),1fr))` + gap 12（禁 auto-fit）；所有卡等宽、整行铺满、最后一行单卡不拉伸；拖右缘 = 统一列宽 280–640；容器 <716px 单列单卡占满（已知边界）
3	重排动效替换	退场 ghost 改为渲染期同步派生、插回原槽位（不再晚一帧追加末尾）；180ms 淡出后其余卡 FLIP 200ms；signature=`activeKey\|exitingKey` 在 layout effect arm；同帧 >2 张跳过 fade；reduced-motion 瞬时

以上为代码侧修复；真机复验清单见 docs/design/ui-spec.md v8 §9 A29–A33（均为 manual/Unverified），不得据此宣称已真机验收。

会话隔离 v11（P0，代码侧已修 / 真机双会话复验待做）

2026-10-26 P0 修复（契约 v11 / ui-spec v9）：Host 单实例单 store 下曾出现跨会话数据泄漏（A 会话能看到 B 的 Runs/终端），修复为所有帧与存储操作按会话树隔离：

#	变更	说明
1	Host 帧/存储隔离	`frameSelection({sessionIds})`、`takeEntries({sessionIds})`、`drainRemoved(sessionIds)`（内部 `Map<runId,owner>`）、`prune(now,{protect,sessionIds})`（每会话配额）、`resync({sessionIds})`、`mergeClientCursors(cursors,sessionIds)`；异会话 Run 不进帧、不消费其增量、不 prune、不 removed
2	terminal owner 收紧	`terminalScopes` 只等于会话树（v9「树外 owner 升级 live」作废）；树外 owner 不展示/不解析，计 `droppedForeignRuns`；`knownSessionIds` 只清理本 root 曾见并离开的 terminal
3	诊断	`diagnostics` 增 `frameSessionId/allowedSessions/scopedRuns/droppedForeignRuns/removedSent`，便于双会话核对
4	客户端纵深防御	异会话帧整帧丢弃（限流 warn 一次）；`mergePoll` 不跨会话改写；`SESSION_CACHE_VERSION='v11-1'` + sanitize；切会话清 ghost/timers/FLIP/undo/armed/drag/最大化

真机双会话验证见 docs/testing/report.md §16.4（7 步 manual/Unverified）；ui-spec v9 §9 A34–A38。不得据此宣称已真机验收。

快速验证

npm run check     # node --check lib/index.js && node --check lib/client.js
npm test          # node --test "tests/**/*.test.mjs"（364 用例）
npm run smoke     # node scripts/smoke-host.mjs（91 checks，exit 0）
# 或一次跑完：
npm run verify

本仓库不安装依赖（宿主包由 DSH profile 提供；Node 22.19+）。测试与冒烟均离线可跑。

安装 / 发布

一键脚本（推送 + 安装进 DSH profile；先 --dry-run 看计划，不改任何文件）：

./deploy/publish-and-install.sh --dry-run
./deploy/publish-and-install.sh --timeout 300   # 安装阶段联网 pnpm 默认 120s 超时，超时 exit 6；优先离线

--timeout <秒>（默认 120，范围 10–3600）覆盖 dsh plugin add/install 与 pnpm install 调用（安装与回滚同路径）；无 GNU timeout 时依次降级 gtimeout → perl alarm，超时统一 exit 6（shell 可能打印一行 Alarm clock: 14，属正常）。完整选项/回滚见 docs/install.md §1.3。

链接

设计规格（v9，验收基线）：docs/design/ui-spec.md
设计图（A–F 六板）：.figma/assets/e7b0e68d-51fe-4f9a-9247-0698ba78ee0d/
Figma 原型恢复指南：docs/design/figma-restore.md（本地可导入资产见 docs/design/figma-export/）
架构与接口契约（v11）：docs/architecture/contract.md
验收矩阵：docs/testing/acceptance-matrix.md
测试报告（T5 基线 236；v11 回归后 364，tester T60 最终报告）：docs/testing/report.md
集成报告（T6，已完成）：docs/testing/integration-report.md（commit ad39516；H1/M2 已修复于 4bc721e）
取证报告（scout T1）：docs/research/dsh-plugin-apis.md
安装 / 生效 / 验证 / 回滚：docs/install.md
复盘（T4 结构性调整）：docs/retro/2026-10-26-bash-live-source.md
许可证：LICENSE（MIT）
项目级 agent 指引见 AGENTS.md；一键发布+安装见 deploy/publish-and-install.sh。

功能一览（验收基线 = ui-spec v5 + 本 README「已知限制」）

能力	说明
集成方式	客户端 Slot `conversation.view`（`id: terminal-panel`，`order: 30`），复用内建 tab 样式，不自绘 tab
进行中列表	每个 Run 一列，横向排列；超出左右滚动（滚动条 + `›` + 剩余数角标）
列宽	默认 352，可拖 280–640，双击右缘复位，按会话记忆
agent 归属	列头 `类型标签 + agent chip`；子代理蓝、队友琥珀、当前会话无竖条
已完成	32px 紧凑行，分组默认折叠；展开由 `expandedIds` 驱动（无倒计时/进度条，样式暂留测试兼容）
跟随	默认贴底；输出区滚轮只滚自身；上翻暂停并提示「N 条新输出 ↓」，回底自动恢复
筛选	类型 chips（带全局计数）+ 会话范围多选（默认全部会话）+ 命令/输出即时搜索
最大化	`⤢` 打开 980×600 只读弹窗（Esc/✕ 关闭，可停止/复制全部）
只读	不注入键盘、不 `startSend`；唯一的写操作是「停止」（两击确认）
数据源	后台任务 `ctx.jobs`（增量）、持久终端三级发现（`terminals.list` → `terminalController.list` → `tools/execute` 事件；无 Agent 时 meta-only + notice）、前台 bash `tools/execute` + `tools/result`（终态）

已知限制（已裁决，见 contract §12 + v4/v5 附录）

Tab 没有角标：内建 tab 渲染只读 label，无 badge API。运行中数量显示在面板工具栏（「N 个进行中 · M 条记录 · K 个会话」）。
持久终端不是 xterm 屏幕帧：平台模块表不含 xterm 且禁止装依赖 → 终端以「剥离 ANSI 的等宽文本流」呈现；全屏 TUI（vim / htop / less）会退化为文本流，不是屏幕重绘。
前台 bash 过程输出不可得（final-only）：第三方拿不到 ShellExecution 句柄，该类 Run 标「仅终态」、停止按钮禁用；availability.bashLive 需真机安装后确认（mock 环境下 tee 不可用属预期）。需要实时输出时请让 agent 用后台 job（ctx.jobs 天然增量）。
默认会话范围 = 全部会话（ui-spec §4 与 A 板冲突，按 A 板裁决）。
插件不接管输入：不向 PTY 写任何输入；唯一写操作是用户点「停止」。
跨会话聚合待真机验证（scout U6）：服务语义允许按 owner 围栏读取，本机未实测；失败时按来源降级（chip 置灰 + 原因），不影响面板主体。
⋯ 菜单只有 3 项（复制命令 / 复制输出 / 固定展开）：ui-spec §3.7 的「在对话中定位」「在终端中打开（仅终端）」本期不做（Run 契约无 turn/message 引用；插件不接管宿主终端面板），替代见 contract §12.8。已知差异 L1–L5 见 contract §12.10。
非 live root 会话降级：传入的 sessionId 无 live Agent 时返回降级帧（ok:true、树仅 root、availability.tree.available=false、空 runs），不是 session-not-found（仅语法非法才 coded 错误；contract v4 附录）。
terminal 的 truncated 表示「该会话输出未完整覆盖（scrollback 裁剪或窗口未及最旧行）」，不是分页未取完；client 不得据此循环翻页（contract v4 附录）。
terminal 无 Agent 时只能看元信息（v7）：默认走 tools/execute 事件兜底（terminalController 是侧栏终端注册表、默认关闭），outputMode:'meta-only' + notice，读不到连续实时输出（tier3 片段非全量）、停止不可用；但不再静默 0 条（诊断字段见 contract §7.2）。
composer 隐藏是 best-effort（v7）：优先官方能力，否则 [data-conversation-content] 标记 + CSS（找不到锚点才 body 兜底/静默降级）；宿主 DOM 变更可能失效（其它 tab 不受影响）。
v7 真机 5 项修复仅代码侧完成，真机复验待做；ui-spec §9 的 A1–A13 为验收条目（部分 manual）。
v11 行为变更（不是缺陷）：树外 owner 的 terminal 不再展示（v9 升级 live 作废；可靠血缘放开为 v12 未来项）；切会话会清瞬时态并重建 view（缓存+resync 恢复首屏）。
v10 行为变更（不是缺陷）：状态边框生效 2px；执行区改 CSS grid 统一列宽（最后一行单卡不拉伸；容器 <716px 单列单卡占满）；拖右缘只调统一列宽；重排为同步 ghost+FLIP。
v9 行为变更（不是缺陷）：已完成行独立展开且无倒计时；执行区按行铺满；状态色黄/绿/红；树外 owner terminal 可升级 live。
v8 行为变更（不是缺陷）：横向滑动/溢出按钮已废弃（改网格换行）；终态不再自动展开已完成分组（改 linger 3s + 收起按钮；v11.1 起）；切 tab 依赖 LRU 4/TTL 30min 会话缓存（第 5 个会话不保证首屏不空）。terminal 可见性只对部署后新发生的 terminal_* 判定（历史/已卸载 owner 的 pty 不可回读，不计缺陷）。

目录结构

.
├── LICENSE                      # MIT（2026，xx529）
├── package.json                 # 双端 bundle 清单（dsh.bundle.patch + dsh.client + manifestVersion）+ 脚本
├── cordis.patch.yml             # Host 行走线（- insert: { id: terminal-panel, name: dsh-terminal-panel }）
├── icon.svg                     # Plugin Manager 图标（原创终端字形，16/24px 可读）
├── locale/{zh,en}.json          # Plugin Manager 展示元数据（meta.title / meta.description）
├── docs/
│   ├── design/ui-spec.md        # v9 设计规格（验收基线 + A1–A38）
│   ├── architecture/contract.md # 双端契约（v11）
│   ├── research/dsh-plugin-apis.md # scout T1 取证（契约事实来源）
│   ├── research/terminal-panel-followup-2026-10-26.md # v7 真机缺陷取证（若存在）
│   ├── testing/acceptance-matrix.md # 验收矩阵
│   ├── testing/report.md        # 测试报告（T5 基线 236 → v11 364，覆盖说明）
│   ├── testing/integration-report.md # 集成报告（T6，已完成 ad39516）
│   ├── retro/2026-10-26-bash-live-source.md # T4 触发复盘（closed）
│   └── install.md               # 安装 / 生效 / 验证 / 回滚（证据版）
├── lib/
│   ├── index.js                 # [backend] Host 半端入口（ESM）
│   ├── host/*.mjs               # [backend] 采集器 + 纯逻辑（13 个模块，node:test 直接 import）
│   ├── client.js                # [frontend] Client 半端（单文件 classic script，≈3,000 行）
│   └── client/**                # [frontend] 可选纯函数（不 import React）
├── scripts/smoke-host.mjs       # [backend] mock ctx 冒烟（91 checks）
└── tests/                       # [tester] *.test.mjs（host / client / e2e）+ helpers