@deepseek-ai/dsh-plugin-session-terminal

Readme

# dsh-plugin-session-terminal

> DeepSeek Harness（DSH）Web 端的**会话终端观察插件**。  
> 在会话视图环中新增「终端」页签，以只读方式实时展示当前会话执行的 bash 命令、工作目录、执行状态、输出与耗时，帮助用户和智能体在对话界面内直接追踪命令执行过程。

---

## 项目定位

- **纯前端观察插件**：Host 侧无业务逻辑，Client 侧直接订阅会话运行时数据，不提供任何服务端接口。
- **只读安全边界**：只展示命令记录，不执行、不修改、不提供交互式终端能力。
- **会话级隔离**：每个会话只展示自己的 bash 调用记录，不跨会话混叠。

## 功能特性

- **会话视图环新增「终端」页签**：与轨迹、容器、虚拟机等页签并列，顺序为 `order: 11`。
- **实时命令流**：自动展示当前会话正在执行的 bash 调用；命令完成后即时补充结果与耗时。
- **完整元数据**：每条记录包含命令、工作目录、描述、开始时间、结束时间与耗时（毫秒级精度）。
- **状态标识**：区分成功、失败 / 非零退出码、运行中三种状态，视觉上使用不同颜色与脉冲动画。
- **可展开输出**：点击命令行可展开查看完整标准输出或错误信息；运行中的命令显示等待提示。
- **清空展示**：支持清空当前会话的展示记录；清除标记按会话保存在浏览器本地存储中，刷新后依然生效。
- **自动滚动**：新记录出现时若用户未上翻，列表自动跟随到底部；手动上翻后暂停跟随，避免打扰回溯。
- **仅观察当前会话**：不跨会话聚合，不修改任何命令、结果或会话状态。

## 架构

```
浏览器 (client, lib/client.js)
┌──────────────────────────────────────────────────────────────┐
│ window.__ModuleLoader__.load({...})                          │
│   └─ slots.inject('conversation.view', order: 11)            │
│        └─ TerminalView                                       │
│             ├─ useSession(s => s.nodes)        已完成命令     │
│             ├─ useSession(s => s.runningCalls) 运行中命令     │
│             ├─ localStorage 清除标记                          │
│             └─ 只读展示 / 展开输出 / 自动滚动                  │
└──────────────────────────────────────────────────────────────┘
```

- **Host 半区**：仅保留空的 `apply()` 入口，用于满足插件加载协议；不注册工具、不监听事件、不占用进程资源。
- **Client 半区**：通过 DSH 客户端运行时提供的 `useSession` 获取当前会话的节点与运行中调用，筛选 `bash` 工具记录后渲染为终端时间线。
- **无网络请求**：终端数据来自内存态会话数据，不新增 HTTP 路由，也不依赖后端服务。

## 安装

### 方式 A：从 GitHub Releases 安装预构建 tarball（推荐）

从 [Releases](https://github.com/GHJIVHIDD/dsh-plugin-session-terminal/releases) 下载 `dsh-plugin-session-terminal-0.0.2.tgz` 后执行：

```bash
dsh plugin --profile web add ./dsh-plugin-session-terminal-0.0.2.tgz
```

插件带有 `dsh.bundle` 声明，`dsh plugin` 会自动加入 profile 的 `bundles` 层，并应用 `cordis.patch.yml` 自动插入「终端」页签。

### 方式 B：从 GitHub 源码直接安装

仓库根目录本身是标准 DSH 组合包（bundle），可直接从 GitHub 源码安装：

```bash
dsh plugin --profile web add github:GHJIVHIDD/dsh-plugin-session-terminal
```

建议锁定 commit，避免后续推送改变实际安装的代码：

```bash
dsh plugin --profile web add github:GHJIVHIDD/dsh-plugin-session-terminal#<commit-sha>
```

> **pnpm 构建授权说明**  
> 从 GitHub 源码安装时，pnpm 会尝试执行仓库的 `prepare` 脚本以生成 `lib/`。  
> - 若 pnpm 授权策略为 `ask`，安装过程可能弹出确认提示；  
> - 若策略已改为 `never`，CLI 不会询问并会直接跳过 `prepare`，可能导致 `lib/` 缺失。  
> 遇到上述情况，请在 profile 的 `pnpm-workspace.yaml` 中显式放行本包后重新安装：
>
> ```yaml
> # 文件位置：~/.dsh/profiles/web/pnpm-workspace.yaml
> allowBuilds:
>   "@deepseek-ai/dsh-plugin-session-terminal": true
> ```
>
> 之后重新执行安装命令。若希望完全绕开 pnpm 构建，请使用方式 A 的预构建 tarball 或方式 C 的免 pnpm 安装脚本。

### 方式 C：免 pnpm 手动安装

```bash
git clone https://github.com/GHJIVHIDD/dsh-plugin-session-terminal.git
cd dsh-plugin-session-terminal
./install.sh
```

脚本会：

1. 将插件文件复制到 `~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-plugin-session-terminal`。
2. 若 `cordis.patch.yml` 中还没有 `ui-session-terminal`，自动追加补丁条目。

可通过环境变量指定自定义位置：

```bash
DSH_HOME=/path/to/.dsh DSH_PROFILE=web ./install.sh
```

### 方式 D：手动复制 + patch

```bash
# 1. 复制插件包到 profile 的 node_modules
mkdir -p ~/.dsh/profiles/web/node_modules/@deepseek-ai
cp -R dsh-plugin-session-terminal ~/.dsh/profiles/web/node_modules/@deepseek-ai/

# 2. 确认 ~/.dsh/profiles/web/cordis.patch.yml 中包含：
# - insert:
#     - id: ui-session-terminal
#       name: '@deepseek-ai/dsh-plugin-session-terminal'
```

## 使用

安装后重启或刷新：

```bash
dsh --profile web
```

打开 Web 界面进入任意会话，在会话视图环中点击「终端」即可看到该会话实时执行的 bash 命令记录。

## 兼容性

- 面向 DeepSeek Harness `web` profile。
- 需要 Web 端已启用 `@deepseek-ai/dsh-client-runtime` 与 `@deepseek-ai/dsh-client-ui-conversation`（标准 web profile 自带）。
- 当前版本：0.0.2。

## 目录结构

```text
dsh-plugin-session-terminal/
├── package.json               # 仓库根即插件包（含 dsh.bundle / dsh.client 声明）
├── scripts/
│   └── prepare.mjs            # 根包 prepare：构建 dsh-plugin-session-terminal/lib
├── install.sh                 # 免 pnpm 安装脚本
└── dsh-plugin-session-terminal/
    ├── package.json           # 内层插件包（用于 tarball / 手动安装）
    ├── cordis.patch.yml       # 自动插入「终端」页签的 patch 层
    ├── src/
    │   ├── index.js           # Host 侧空实现（源文件）
    │   └── client.js          # 浏览器端终端页签实现（源文件）
    ├── lib/                   # prepare 生成的发布入口（已提交，便于手动安装）
    │   ├── index.js
    │   └── client.js
    └── scripts/
        └── prepare.mjs        # 内层包 prepare：构建 lib/
```


### License

This project is licensed under the Apache License 2.0.
See the full license at https://www.apache.org/licenses/LICENSE-2.0.