dsh-terminal-panel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BaiZhi967
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="assets/banner.svg" width="900" alt="dsh-plugin-terminal-panel banner"/>
+</p>
+
+# dsh-plugin-terminal-panel
+
+[English](README_EN.md) | 中文
+
+[![npm](https://img.shields.io/npm/v/dsh-terminal-panel)](https://www.npmjs.com/package/dsh-terminal-panel)
+[![license](https://img.shields.io/github/license/BaiZhi967/dsh-plugin-terminal-panel)](LICENSE)
+[![stars](https://img.shields.io/github/stars/BaiZhi967/dsh-plugin-terminal-panel?style=flat)](https://github.com/BaiZhi967/dsh-plugin-terminal-panel)
+
+**在 DSH 网页里开终端**：侧栏点一下，主区域就多出一个和「对话」同级的终端面板，里面是**真 PTY**（node-pty / ConPTY），不是假的输出框，也不弹系统窗口。
+
+- 终端跑在 **DSH 宿主进程**里，输出通过 SSE 实时推给页面；
+- 关掉页面、刷新页面都不掉线，PTY 存活并**回放最近 256 KB 输出**，回来画面还在；
+- 面板宽度变化会自动 `resize` PTY，shell 的重绘跟着走。
+
+## ✨ 功能
+
+| 能力 | 说明 |
+|---|---|
+| **侧栏入口** | 左栏面板图标区多一个终端图标，与「插件」图标同级；点它主区域切到终端面板，机制与「对话」面板完全一致 |
+| **活跃计数** | 图标右上角实时显示运行中的终端数量，为 0 时自动隐藏；悬停提示同步带上数量 |
+| **多标签** | 一个面板里开多个终端（上限 12 个），每个一个标签，带状态点和关闭按钮 |
+| **重命名** | 双击标签名，或点标签上的 ✎；`Enter` 提交、`Esc` 取消、失焦自动提交（中文 / emoji 正常） |
+| **自绘终端** | 内置一个小型 VT 引擎：ANSI 颜色（16 / 256 / 真彩）、光标定位、清行清屏、备用屏幕、滚动区域、宽字符 |
+| **跟随主题** | 亮 / 暗两套 ANSI 调色板：亮色主题下 `37`／`93` 映射为深灰 / 深黄，白底上也能看清（PowerShell 的输入高亮不再"隐形"） |
+| **文本选择** | 标签栏 ⧉ 一键切到「选择文本」模式（暂停键盘输入），可直接框选复制输出 |
+| **中文输入** | 独立输入通道，IME 组合输入、中文、emoji 都能正确送进 PTY |
+| **热重载** | 改 `impl.js` 后 `POST /__reload` 即可生效，不用重启 DSH；客户端代码改动由 DSH 的模块热更新自动送达页面 |
+
+## 📦 安装
+
+```sh
+dsh plugin --profile web add dsh-terminal-panel
+dsh --profile web
+```
+
+装好后刷新一次页面（或直接看侧栏），左栏面板图标区就会出现终端图标。
+
+> 若 `dsh plugin add` 拉不到包（刚发布、或公司/国内镜像尚未同步），用下面的源码方式安装。
+
+从源码安装（本地开发、二次修改）：
+
+```sh
+git clone https://github.com/BaiZhi967/dsh-plugin-terminal-panel.git
+cd dsh-plugin-terminal-panel
+
+# 在插件目录的「父目录」执行，dsh 会把相对路径锚定到调用目录
+dsh plugin --profile web add ../dsh-plugin-terminal-panel
+dsh --profile web
+```
+
+也可以直接写进 profile 的 `cordis.patch.yml`：
+
+```yaml
+- insert:
+    - id: terminal-panel
+      name: dsh-terminal-panel
+```
+
+> 环境要求：DSH `>= 0.1.6-alpha.2`、Node `^22.19.0 || >=24.0.0`；宿主进程需要有可用 PTY（本插件用 `subprocess.spawnTerminal`，即宿主自带的 node-pty）。
+
+## 🚀 用法
+
+1. 点左栏的**终端图标** → 主区域打开终端面板；
+2. 点 **+ 新建终端** → 立即分配一个 PTY，shell 自动选 `pwsh` → `powershell` → 宿主默认 shell，工作目录默认取最新工作区；
+3. 直接在面板里敲命令（点击面板即聚焦输入）；
+4. 双击标签名改名；✎ 也是改名；✕ 关闭（进程树会被终止）；
+5. 面板随窗口变化自动 `resize`。
+
+## 🧱 结构
+
+```
+dsh-plugin-terminal-panel/
+├── host.js           # 宿主入口：只承载路由 + 热重载外壳
+├── impl.js           # 宿主实现：PTY 生命周期、SSE 推送、write/resize/close/rename
+├── client.js         # 客户端：终端面板、侧栏图标、VT 引擎、输入处理
+├── cordis.patch.yml  # bundle 补丁：向 profile 插入插件行
+└── package.json      # dsh.bundle.patch + dsh.client 声明
+```
+
+两侧如何协作：
+
+```
+侧栏图标 / 终端面板 (client.js)
+        │  同源 HTTP（回环地址）
+        ▼
+GET  /system-terminals/api/stream?id=…   ← SSE：先回放缓冲，再推实时输出
+POST /system-terminals/api/{list,create,write,resize,close,rename,remove}
+        ▼
+impl.js ── subprocess.spawnTerminal() ──► 真 PTY（node-pty / ConPTY）
+```
+
+设计上有意分成两个文件：**加载过的 ESM 模块会在宿主进程里被永久缓存**，所以 `host.js` 保持极简、把逻辑放进 `impl.js`，由 `host.js` 用带缓存参数的动态 `import()` 拉取 —— 这样替换 `impl.js` 后一次 `POST /__reload` 就能生效，无需重启 DSH。
+
+### 本地 API
+
+路由前缀 `/system-terminals/api`，仅监听 DSH 自己的回环地址，无需登录态（与生态内其他插件的私有路由一致）：
+
+| 方法 | 作用 |
+|---|---|
+| `GET /health` | 版本、平台、shell、PTY 可用性 |
+| `GET /list` | 终端列表（id、标题、cwd、pid、行列、状态、是否可 resize） |
+| `POST /create` | `{cwd?, cols?, rows?}` → 新建终端 |
+| `POST /write` | `{id, data}` → 写入 PTY（原始字节，UTF-8） |
+| `POST /resize` | `{id, cols, rows}` |
+| `POST /close` | `{id}` → 终止进程 |
+| `POST /rename` | `{id, title}` → 改名（去空白、上限 60 字） |
+| `POST /remove` | `{id}` → 从列表移除已退出的终端 |
+| `GET /stream?id=` | SSE：`history` / `data` / `status` / `exit` 事件，base64 负载 |
+| `POST /__reload` | 开发用：重新加载 `impl.js` |
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 BaiZhi967

package/README_EN.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="assets/banner.svg" width="900" alt="dsh-plugin-terminal-panel banner"/>
+</p>
+
+# dsh-plugin-terminal-panel
+
+English | [中文](README.md)
+
+[![npm](https://img.shields.io/npm/v/dsh-terminal-panel)](https://www.npmjs.com/package/dsh-terminal-panel)
+[![license](https://img.shields.io/github/license/BaiZhi967/dsh-plugin-terminal-panel)](LICENSE)
+[![stars](https://img.shields.io/github/stars/BaiZhi967/dsh-plugin-terminal-panel?style=flat)](https://github.com/BaiZhi967/dsh-plugin-terminal-panel)
+
+**Terminals inside the DSH web UI.** Click the sidebar icon and a terminal panel opens in the main column, as a peer of the Conversation panel. It is a **real PTY** (node-pty / ConPTY) — not a fake output box, and never an OS window.
+
+- Terminals live in the **DSH host process**; output is streamed to the page over SSE.
+- Refreshing or closing the page does not kill them: the PTY survives and **replays the last 256 KB**, so the screen comes back.
+- Resizing the panel resizes the PTY, so the shell redraws at the new width.
+
+## ✨ Features
+
+| Feature | Detail |
+|---|---|
+| **Sidebar entry** | One terminal icon in the sidebar's panel-icon row, next to the built-in Plugins icon. Clicking it switches the main column to the terminal panel — the same mechanism the Conversation panel uses |
+| **Active count** | A live badge on the icon shows how many terminals are running (hidden at zero); the tooltip carries the count too |
+| **Tabs** | Several terminals in one panel (up to 12), each with a status dot and a close button |
+| **Rename** | Double-click a tab, or use its ✎ button; `Enter` commits, `Esc` cancels, blur commits. CJK and emoji round-trip correctly |
+| **Own VT engine** | A small terminal renderer written for this plugin: ANSI colour (16 / 256 / truecolor), cursor addressing, erase, alternate screen, scroll regions, wide characters |
+| **Theme aware** | Separate light and dark ANSI palettes: on a light theme `37` / `93` map to dark grey / dark yellow, so PowerShell's input highlighting stays readable |
+| **Text selection** | The ⧉ button in the tab bar pauses keyboard input so you can select and copy output |
+| **IME input** | A dedicated input channel: composed Chinese, CJK and emoji reach the PTY correctly |
+| **Live reload** | Edit `impl.js` and `POST /__reload` — no DSH restart. Client-side edits are hot-updated by DSH's module table |
+
+## 📦 Install
+
+```sh
+dsh plugin --profile web add dsh-terminal-panel
+dsh --profile web
+```
+
+Reload the page once and the terminal icon appears in the sidebar.
+
+> If `dsh plugin add` cannot resolve the package yet (a fresh publish, or a mirror that has not synced), install it from source instead.
+
+From source (local development, or your own fork):
+
+```sh
+git clone https://github.com/BaiZhi967/dsh-plugin-terminal-panel.git
+cd dsh-plugin-terminal-panel
+
+# run from the plugin's PARENT directory: a relative path is anchored there
+dsh plugin --profile web add ../dsh-plugin-terminal-panel
+dsh --profile web
+```
+
+Or mount it by hand in the profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: terminal-panel
+      name: dsh-terminal-panel
+```
+
+> Requirements: DSH `>= 0.1.6-alpha.2`, Node `^22.19.0 || >=24.0.0`, and a host with a working PTY (this plugin uses `subprocess.spawnTerminal`, i.e. the bundled node-pty).
+
+## 🚀 Usage
+
+1. Click the **terminal icon** in the sidebar → the terminal panel opens in the main column.
+2. Click **+ New Terminal** → a PTY is allocated immediately. The shell is picked as `pwsh` → `powershell` → the host default, and the working directory defaults to the newest workspace.
+3. Type directly in the panel (clicking it focuses the input).
+4. Double-click a tab (or use ✎) to rename; ✕ closes the terminal and terminates its process tree.
+5. The panel resizes the PTY automatically as the window changes.
+
+## 🧱 Layout
+
+```
+dsh-plugin-terminal-panel/
+├── host.js           # host entry: the route carrier + reload shell only
+├── impl.js           # host implementation: PTY lifecycle, SSE, write/resize/close/rename
+├── client.js         # client: terminal panel, sidebar icon, VT engine, input handling
+├── cordis.patch.yml  # bundle patch: inserts the plugin row into a profile
+└── package.json      # dsh.bundle.patch + dsh.client declarations
+```
+
+How the halves talk:
+
+```
+sidebar icon / terminal panel (client.js)
+        │  same-origin HTTP on the loopback listener
+        ▼
+GET  /system-terminals/api/stream?id=…   ← SSE: replay buffer first, then live output
+POST /system-terminals/api/{list,create,write,resize,close,rename,remove}
+        ▼
+impl.js ── subprocess.spawnTerminal() ──► real PTY (node-pty / ConPTY)
+```
+
+The two-file host split is deliberate: **a loaded ES module stays cached in the host process for its lifetime**, so `host.js` stays minimal and pulls the implementation in through a cache-busted dynamic `import()`. Replacing `impl.js` then takes effect with one `POST /__reload`, no DSH restart.
+
+### Local API
+
+Prefix `/system-terminals/api`, bound to DSH's own loopback listener, no session auth — the same shape other plugins in this ecosystem use for their private routes:
+
+| Method | Purpose |
+|---|---|
+| `GET /health` | Version, platform, shell, PTY availability |
+| `GET /list` | Terminals: id, title, cwd, pid, cols/rows, status, resizable |
+| `POST /create` | `{cwd?, cols?, rows?}` → open a terminal |
+| `POST /write` | `{id, data}` → write raw UTF-8 bytes to the PTY |
+| `POST /resize` | `{id, cols, rows}` |
+| `POST /close` | `{id}` → terminate the process |
+| `POST /rename` | `{id, title}` → rename (whitespace collapsed, 60 chars max) |
+| `POST /remove` | `{id}` → drop an exited terminal from the list |
+| `GET /stream?id=` | SSE: `history` / `data` / `status` / `exit` events, base64 payloads |
+| `POST /__reload` | Development: reload `impl.js` |
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 BaiZhi967

package/assets/banner.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="220" viewBox="0 0 900 220" role="img" aria-label="dsh-plugin-terminal-panel">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="1" stop-color="#131f36"/>
+    </linearGradient>
+  </defs>
+  <rect width="900" height="220" rx="18" fill="url(#bg)"/>
+
+  <!-- left rail: the sidebar panel icon with its active-terminal badge -->
+  <rect x="26" y="30" width="52" height="160" rx="12" fill="#0e1a2e"/>
+  <rect x="38" y="52" width="28" height="24" rx="6" fill="none" stroke="#4d6bfe" stroke-width="2"/>
+  <path d="M45 60l5 4-5 4" fill="none" stroke="#4d6bfe" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M54 70h7" stroke="#4d6bfe" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="68" cy="50" r="9" fill="#4d6bfe"/>
+  <text x="68" y="54" font-family="Segoe UI,Helvetica,Arial,sans-serif" font-size="11" font-weight="700" fill="#ffffff" text-anchor="middle">2</text>
+
+  <!-- main column: the terminal panel -->
+  <rect x="94" y="30" width="780" height="160" rx="14" fill="#080f1c" stroke="#22304a"/>
+  <rect x="94.5" y="30.5" width="779" height="34" rx="13" fill="#101c30" stroke="#22304a"/>
+  <rect x="108" y="40" width="146" height="20" rx="6" fill="#17253d"/>
+  <circle cx="121" cy="50" r="4" fill="#16a34a"/>
+  <text x="131" y="54" font-family="Segoe UI,Helvetica,Arial,sans-serif" font-size="12" fill="#dbe6f5">Terminal 1</text>
+  <text x="266" y="54" font-family="Segoe UI,Helvetica,Arial,sans-serif" font-size="12" fill="#7d8fae">+ New Terminal</text>
+
+  <!-- screen -->
+  <text x="116" y="96" font-family="Cascadia Mono,Consolas,Menlo,monospace" font-size="13.5" fill="#dbe6f5">PS E:\DSH&gt; npm run dev</text>
+  <text x="116" y="122" font-family="Cascadia Mono,Consolas,Menlo,monospace" font-size="13.5" fill="#b5ba00">&gt; vite --port 5173</text>
+  <text x="116" y="148" font-family="Cascadia Mono,Consolas,Menlo,monospace" font-size="13.5" fill="#7d8fae">  ready in 412 ms</text>
+  <rect x="116" y="158" width="8" height="15" fill="#4d6bfe" opacity="0.85"/>
+  <text x="136" y="171" font-family="Cascadia Mono,Consolas,Menlo,monospace" font-size="13.5" fill="#dbe6f5">PS E:\DSH&gt;</text>
+</svg>