dsh-oh-my-terminal 0.2.2

package/CLAUDE.md

@@ -0,0 +1,167 @@
+# CLAUDE.md
+
+本文件为 `dsh-oh-my-terminal` 仓库提供 Claude Code (claude.ai/code) 的编码指导。
+
+## 必读文档
+
+AI agent 或人类开发者在动手修改任何代码或文档之前，**必须先阅读**以下两份规范：
+
+- [docs/git-workflow.md](docs/git-workflow.md) — Git 分支管理与提交规范（分支创建、合并方向、commit message 格式、agent 检查清单）
+- [docs/type_script_style.md](docs/type_script_style.md) — TypeScript 编程规范（注释、命名、模块结构、类型约定）
+
+未读这两份文档就动手改代码视为违规。
+
+## 语言要求
+
+本仓库的所有交流、代码注释、提交信息、文档一律使用**中文**。
+
+## 这是什么
+
+`dsh-oh-my-terminal` 是 DSH Web GUI 的底部终端面板插件，基于 `@lydell/node-pty` 提供多终端交互式面板（Windows ConPTY / POSIX openpty），经 WebSocket 与浏览器端的 xterm.js 前端通信。用户通过 `dsh plugin --profile web add dsh-oh-my-terminal` 安装。
+
+VSCode 风格界面：+号旁下拉菜单（新建/拆分/按种类新建）、拆分终端（同组水平并排）、右侧终端列表（替代水平 tab 栏）、右键重命名。
+
+架构分为两半加共享工具层：
+
+- **宿主半**（`src/index.ts` + `src/routes.ts` + `src/ws-handler.ts`）：Cordis 插件入口、HTTP 路由分发、WebSocket 升级与数据转发、settings 集成、会话生命周期管理
+- **浏览器半**（`src/client.tsx` + `src/client/`）：React 组件，xterm.js 底部面板，useReducer 统一状态管理、拆分终端、右侧列表、下拉菜单、快捷键、拖拽调高、剪贴板
+- **持久化层**（`src/persistence.ts`）：`SessionStore` 封装会话日志落盘/清理、元数据读写、启动恢复
+- **平台适配层**（`src/platform.ts`）：`PlatformAdapter` 接口与 POSIX/Windows 适配器，封装 OS 差异，动态探测 Git Bash 与默认 shell
+- **常量**（`src/constants.ts`）：协议前缀、尺寸约束、快捷键默认值、环境变量名等具名常量
+- **工具函数**（`src/server-command.ts`、`src/shortcut.ts`、`src/logger.ts`）：命令行解析、快捷键解析、统一日志
+
+**插件形态必须构建**：dsh loader 经纯 ESM import 加载插件、不走 tsx，所以必须用 `scripts/build.ts` 产出 `lib/` 构建产物。`lib/` 纳入版本控制——pnpm 11 对声明了安装类脚本的 git-hosted 包直接报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，且只看 `package.json` 字段、不看脚本内容做什么，所以本仓库**不声明任何生命周期脚本**（`prepare`/`postinstall` 都没有）。构建由开发者手动 `pnpm run build` 完成，产物 `lib/` 随源码一起提交。
+
+## 常用命令
+
+**本机开发默认 pnpm 11.7.0**（`package.json` 的 `packageManager` 钉版本）。不要用 npm——peer 依赖钉死具体版本，npm 在残留旧树上做增量解析必报 ERESOLVE。
+
+```bash
+# 类型检查
+pnpm run typecheck
+
+# 构建（esbuild 双入口 → lib/index.js + lib/client.js + lib/xterm.css）
+pnpm run build
+
+# 单元测试（纯函数模块）
+pnpm exec tsx --test tests/unit/*.test.ts
+```
+
+`pnpm-workspace.yaml` 的 `allowBuilds` 只放行 `esbuild`——`@lydell/node-pty` 的各平台二进制随子包 tarball 分发，安装期既不编译也不下载，所以不需要（也不应）为它放行构建脚本；`minimumReleaseAge: 0` 避免拦截当天发布的依赖。
+
+## 架构
+
+```
+src/
+├── index.ts                # 宿主半入口（cordis 插件壳 + settings 集成 + 会话生命周期 + loadPty 懒加载）
+├── routes.ts               # HTTP 路由处理器工厂（createRouteHandler + 辅助函数）
+├── ws-handler.ts           # WebSocket 处理器工厂（createWsHandlers + WebServer 类型导出）
+├── client.tsx              # 浏览器半入口（TerminalPanel 组合壳 + 插件注册 + injectStyles 调用）
+├── client/
+│   ├── types.ts            # 共享类型定义（TerminalInstance, TerminalGroup, TerminalState, TerminalAction, API 响应）
+│   ├── hooks.ts            # 自定义 Hooks（terminalReducer + useTerminalState + useConfig + usePanelHeight + usePanelGeometry + useTerminalTabs）
+│   ├── term-pane.tsx       # TermPane 组件（xterm + WebSocket + resize）+ RestartButton 组件
+│   ├── styles.ts           # CSS 样式常量（PANEL_CSS）+ Campbell 暗色主题 + xterm 调优常量 + injectStyles()
+│   ├── dropdown.tsx        # +号旁下拉菜单组件（新建/拆分/按种类新建）
+│   ├── side-list.tsx       # 右侧终端列表面板（树形前缀 + 右键重命名 + useMemo 缓存）
+│   ├── terminal/
+│   │   └── use-tabs.ts     # 终端标签页状态管理（useTerminalTabs Hook：newTab/splitTerminal/closeTerminal/renameTerminal）
+│   ├── settings/
+│   │   ├── types.ts        # 设置页面类型定义（SettingsPageProps、ConfigWithProfiles）
+│   │   ├── store.ts        # 设置页面状态管理（useSettingsState Hook）
+│   │   └── card.tsx        # 设置卡片组件（SettingsCard）
+│   ├── icons.tsx           # SVG 图标组件集合（10 个纯函数）
+│   └── clipboard.ts        # 剪贴板纯函数（Async Clipboard API + legacy 双层降级）
+├── terminal/
+│   ├── index.ts            # 终端模块统一导出（kinds/detect/resolve/store）
+│   ├── kinds.ts            # 终端种类定义（TerminalKind 联合类型 + KIND_SPECS 平台映射表）
+│   ├── detect.ts           # 终端探测（resolveCommand/detectGitBash/detectTerminalProfiles）
+│   ├── resolve.ts          # 配置解析（resolveProfile：TerminalProfile → node-pty spawn 参数）
+│   └── store.ts            # 配置表校验（validateAdd/validateUpdate/validateDelete/addProfile/updateProfile/deleteProfile）
+├── settings/
+│   ├── namespace.ts        # Settings 命名空间定义（SettingsNamespace）
+│   └── bridge.ts           # Settings 桥接层（prepareProfiles：配置表与探测结果合并）
+├── persistence.ts          # 会话持久化层（SessionStore：日志落盘/清理、元数据读写、启动恢复）
+├── platform.ts             # 平台适配层（PlatformAdapter 接口 + POSIX/Windows 适配器 + 默认 shell 探测）
+├── constants.ts            # 协议/尺寸/快捷键/环境变量/文件名常量
+├── server-command.ts       # 命令行解析工具（shell 命令拆分与转义）
+├── shortcut.ts             # 快捷键解析工具（toggle 快捷键字符串 → KeyboardEvent 匹配）
+└── logger.ts               # 统一日志工具（createLogger：结构化 [时间戳][级别][模块] 内容）
+```
+
+### 依赖方向
+
+```
+宿主半：
+  index.ts → routes.ts → terminal/, settings/, constants.ts, platform.ts, persistence.ts, server-command.ts, logger.ts
+  index.ts → ws-handler.ts → constants.ts, persistence.ts
+  index.ts → terminal/, settings/, constants.ts, platform.ts, persistence.ts, logger.ts
+  settings/bridge.ts → terminal/detect.ts, terminal/kinds.ts, logger.ts
+  terminal/detect.ts → terminal/kinds.ts
+  terminal/resolve.ts → terminal/kinds.ts, platform.ts
+  terminal/store.ts → terminal/kinds.ts
+  platform.ts → terminal/detect.ts（复用 resolveCommand）
+  persistence.ts → constants.ts, logger.ts
+
+浏览器半：
+  client.tsx → client/types.ts, client/icons.tsx, client/clipboard.ts,
+               client/dropdown.tsx, client/side-list.tsx, client/hooks.ts,
+               client/styles.ts, client/term-pane.tsx, client/settings/,
+               client/terminal/, logger.ts
+  client/hooks.ts → client/types.ts, shortcut.ts, logger.ts
+  client/terminal/use-tabs.ts → client/types.ts, logger.ts
+  client/settings/card.tsx → client/settings/types.ts, client/settings/store.ts, client/icons.tsx
+  client/settings/store.ts → client/settings/types.ts
+  client/dropdown.tsx → client/types.ts, client/icons.tsx
+  client/side-list.tsx → client/types.ts, client/icons.tsx
+  client/term-pane.tsx → client/types.ts, client/clipboard.ts, client/icons.tsx, client/styles.ts
+
+两半经 WebSocket 通信，路由前缀 /api/dsh-oh-my-terminal，不直接 import。
+@lydell/node-pty 是外部原生依赖，宿主半只在首次创建会话时 await import()。
+```
+
+### 状态管理
+
+浏览器半使用 `useReducer` 统一管理终端状态（`TerminalState`），消除原先 instances/groups/activeInstanceId 三轨独立 state 的同步负担。所有 CRUD 操作通过 `dispatch(TerminalAction)` 提交，reducer 是纯函数。`/config` 只拉取一次（`useConfig` Hook），同时获取快捷键配置和终端配置表（`terminalProfiles`）。
+
+### 终端配置模型（type / name / path）
+
+终端种类不再硬编码在 `platform.ts`，而是由配置表驱动：
+
+| 字段 | 说明 |
+|------|------|
+| `type` | 终端类型（`TerminalKind`）：pwsh / powershell / cmd / bash / zsh / fish / gitbash / nushell / custom。决定 spawn 语义与交互参数 |
+| `name` | 下拉菜单显示名。用户可改，跨重启保留 |
+| `path` | 可执行文件路径。留空则按 `type` 在 `$PATH` 中解析 |
+| `origin` | `auto`（启动探测）/ `user`（手动新增）。`auto` 项不可删除、path 不可改，但可改名 |
+
+**启动流程**：`prepareProfiles()` 在 apply 时跑一次 `$PATH` 探测（`detectTerminalProfiles()`），与已保存的配置表合并（`mergeProfiles()`：已保存项全保留，探测到的新 type/path 补进去）。首次运行（配置表为空）时把结果写回配置。
+
+**路径解析**：`resolveProfile()` 把 `TerminalProfile` 转成 node-pty 的 `{ file, args }`。**Windows 上 node-pty 不做 PATH/PATHEXT 查找**，裸命令名（`pwsh`、`cmd`）会直接以 `File not found: ` 失败，必须给完整路径——`resolveCommand()` 用 `where`/`which` 解析，并过滤 `WindowsApps` 下的 App Execution Alias 占位符（0 字节重解析点，spawn 必失败）。
+
+**持久化**：配置表在 `Config` schema 里是 **JSON 字符串**（`terminalProfiles`），不是嵌套数组——schemastery 对对象数组的 round-trip 行为不保证，字符串是唯一稳定形态。空串 = 用启动探测结果。
+
+**API 契约**：客户端只传 `profileId`（配置表 id），不传路径与参数。`POST /sessions` 的 `profileId` 字段与宿主半 `routes.ts` 的读取字段名必须一致——曾因客户端发 `terminalType`、宿主半读 `profileId` 导致下拉菜单静默失效（始终回落到默认 shell）。
+
+## 经验教训与硬约束
+
+- **插件形态**：宿主产物必须 ESM；命令名匹配 `/^[a-z][a-z0-9_-]*$/`；defineTool 的 object 节点必须写 `additionalProperties`；路由只走已鉴权通道
+- **ESM 合规**：所有源文件是 ESM 模块，**禁止使用 `require()`**——必须用顶层 `import` 或动态 `await import()`。esbuild 会把 `require()` 转成 `__require()` 包装，在 DSH 的 Electron 进程中可能失败（曾导致 Git Bash 探测静默失败）
+- **@lydell/node-pty**：`spawn` 时 `cwd` 必须存在且可访问，否则进程立即退出；Windows 上用 ConPTY，POSIX 上用 openpty，不要手动 `fork`
+- **原生绑定懒加载**：宿主半不写顶层静态 `import { spawn } from '@lydell/node-pty'`。ESM 的异常发生在模块求值期，原生绑定一旦加载失败，整个 `lib/index.js` 就变成不可导入、dsh 报 `failed to import`，插件连 `apply` 都执行不到；改成首次创建会话时 `await import()`，失败被收敛在会话创建这一步，错误消息可读，插件其余路由仍可用
+- **精确钉 `@lydell/node-pty@1.1.0`**：它是 microsoft/node-pty 的预编译分发版（API 同源），N-API 产物一份二进制同时覆盖 ABI 127（Node 22）与 ABI 137（Node 24）；但该包 `dist-tags.latest` 指向 1.2.0-beta 系列，所以必须精确写 `1.1.0`，不能用 `^` 或 `latest`
+- **为什么换掉 node-pty**：旧包 tarball 的 `prebuilds/` 只有 darwin 与 win32，Linux 上依赖安装期执行 `node scripts/prebuild.js || node-gyp rebuild`；而 pnpm 10 对未授权的构建脚本只警告并跳过，`build/Release/pty.node` 从未生成。`@lydell/node-pty` 拆六个平台子包、二进制在 tarball 内，运行期不下载不编译，且 `package.json` 连 `scripts` 字段都不存在（不是空对象），pnpm 10/11/12 对没有脚本字段的包都不进入构建授权判断分支
+- **WebSocket**：socket error 必须在 destroy 之前挂 error 监听器，未处理 error 事件会直接掀翻进程；关闭时要成对清理 `data`/`close`/`error` 监听器
+- **xterm.css**：构建时从 `node_modules/@xterm/xterm/css/xterm.css` 复制到 `lib/xterm.css`，由宿主半 serve
+- **终端数据绝不进日志**：pty 输出与 WebSocket 数据帧是用户会话内容，不写日志
+- **CSS overflow:hidden 陷阱**：包含 `position:absolute` 浮层（如下拉菜单）的容器不能设 `overflow:hidden`，否则浮层被裁剪不可见
+- **Windows 上 spawn 必须给完整路径**：node-pty 的 `spawn` 在 Windows 上**不做 PATH/PATHEXT 查找**，传裸命令名（`pwsh`、`cmd`、`bash`）直接以 `File not found: ` 失败（错误消息里的路径是空串，极易误判为 cwd 问题）。所有终端命令都要先经 `where`/`which` 解析成绝对路径，并过滤 `WindowsApps` 下的 App Execution Alias 占位符
+- **跨半字段名必须逐字对齐**：宿主半与浏览器半经 HTTP 通信、无编译期校验，字段名拼写不一致会静默回落到默认分支（曾因客户端发 `terminalType`、宿主半读 `profileId`，导致下拉菜单选了任何类型都开出默认 shell，且无任何报错）
+- **单文件行数阈值**：建议 <600 行。超过时按职责边界拆分到子模块，不要按"太长了"随意切半
+
+## 约束
+
+- 客户端可能是 Windows/Linux/macOS，宿主半跑在 dsh 所在机器上。`@lydell/node-pty` 自动按平台选 ConPTY 或 openpty。
+- 不落明文凭据：日志和错误消息不打印密钥、令牌、口令内容。
+- 新增运行时依赖必须写进 `package.json`，版本锁定或用窄范围；带原生绑定的依赖（如 `@lydell/node-pty`）一律精确钉版本，不留 `^` 浮动空间。
+- **禁止声明生命周期脚本**：`prepare`/`postinstall` 等一概不要加——pnpm 11 对声明了安装类脚本的 git-hosted 包直接报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，拦截只看 `package.json` 字段、不看脚本内容。反过来，选依赖时也可以用这条判断：`@lydell/node-pty` 就是这个约束的正面对照——它的 `package.json` 里根本没有 `scripts` 字段，pnpm 10 的只警告并跳过、11 起的默认报错退出、12 的现状，对没有脚本的包都不进入判断分支，因此不产生任何版本差异。这是本仓库能在 pnpm 10-12 上装得上、跑得起来的关键。

package/LICENSE

@@ -0,0 +1,218 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+---
+
+Copyright 2026 dsh-oh-my-terminal Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,103 @@
+# dsh-oh-my-terminal
+
+[![version](https://img.shields.io/badge/version-0.2.1-blue)](package.json)
+[![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
+
+A bottom terminal panel plugin for DSH Web GUI. Powered by `@lydell/node-pty`, it provides multi-session interactive terminals over WebSocket using xterm.js in the browser. Supports Windows ConPTY and POSIX openpty with no local compilation required.
+
+[中文文档](README.zh.md)
+
+## Features
+
+- **Multiple terminal sessions**: manage several sessions simultaneously; a side list replaces the traditional horizontal tab bar, with right-click rename support
+- **Split terminals**: horizontal splits within the same group; a VSCode-style dropdown next to the `+` button (new / split / new by kind)
+- **Session persistence**: sessions survive panel close/reopen and are automatically restored on startup
+- **Configurable shortcut**: toggle the panel with a keyboard shortcut; on DSH 0.1.7-rc.2+ the plugin integrates with the host shortcut system and the panel label updates to reflect the current binding
+- **Resizable panel**: drag the top edge of the panel to adjust its height
+- **Cross-platform**: Windows ConPTY and POSIX openpty are selected automatically by `@lydell/node-pty`; pre-compiled binaries ship with the package, nothing to compile
+- **Configurable shell**: set a custom shell command and arguments
+
+## Installation
+
+This package is not yet published to npm. Install directly from GitHub:
+
+```bash
+dsh plugin --profile web add github:btsd321/dsh-oh-my-terminal
+```
+
+## Configuration
+
+| Option | Description | Default |
+|---|---|---|
+| `toggleShortcut` | Shortcut to toggle the terminal panel (legacy host only; see below) | `` Ctrl+` `` |
+| `shellCommand` | Shell command for new terminals | System default (bash / PowerShell) |
+
+## DSH 0.1.7-rc.2 shortcut changes
+
+DSH 0.1.7-rc.2 introduced a host-level shortcut system. Its built-in terminal (`` Ctrl+` `` via `terminal.new`) conflicts with the previous default. To avoid double-triggering, this plugin changed its behavior starting with the rc.2-compatible release:
+
+- **Integrated with shortcuts system**: the plugin registers the `terminal-panel.toggle` command with a default binding of `` Ctrl+Shift+` `` (no default on `web:linux`; bind it manually in DSH settings). Change the key in DSH Settings - Keyboard Shortcuts; the panel label updates automatically
+- **Legacy host (0.1.7-rc.1 and earlier)**: falls back to a bare `` Ctrl+` `` listener; the `toggleShortcut` setting still applies
+- **Migration note**: after upgrading the host, `` Ctrl+` `` opens the built-in terminal (side panel). Use `` Ctrl+Shift+` `` for this plugin's panel. To reclaim `` Ctrl+` `` for this plugin, first remove the built-in terminal's binding in DSH keyboard settings
+
+## Development
+
+```bash
+# Install dependencies (@lydell/node-pty ships pre-compiled binaries — ready to use immediately)
+pnpm install
+
+# Type check
+pnpm run typecheck
+
+# Build (esbuild, two entry points, output to lib/)
+pnpm run build
+
+# Unit tests
+pnpm exec tsx --test tests/unit/*.test.ts
+```
+
+> Use `pnpm`, not `npm`. Peer dependencies pin exact versions; npm's incremental resolution on an existing tree will produce ERESOLVE errors.
+
+### About the build output
+
+`lib/` is committed to version control. The DSH loader imports plugins as plain ESM; it does not run tsx. This repo also declares no lifecycle scripts (`prepare`, `postinstall`, etc.) because pnpm 11 rejects git-hosted packages that declare install-time scripts with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`. Run `pnpm run build` manually and commit the output alongside source.
+
+### Native dependency notes
+
+Terminal capability comes from `@lydell/node-pty` (a pre-compiled distribution of microsoft/node-pty with the same API), pinned exactly to `1.1.0`. The `^` range is intentionally omitted: the package's `dist-tags.latest` points at the 1.2.0-beta series.
+
+It is an N-API package. Binaries are split into six platform sub-packages and shipped inside the tarball; no download or compilation happens at install time. A single binary supports both Node 22 and Node 24. Its `package.json` has no `scripts` field at all, so pnpm 10, 11, and 12 never enter the build-authorization path, giving consistent behavior across versions.
+
+The host side lazy-loads the package (`await import()` on first session creation). If the native binding fails to load, the error is contained to session creation; the plugin module itself remains importable and all other routes stay available.
+
+## Architecture overview
+
+```
+src/
+├── index.ts          # Host entry (Cordis plugin + settings + session lifecycle)
+├── routes.ts         # HTTP route handlers
+├── ws-handler.ts     # WebSocket handler (pty data forwarding)
+├── client.tsx        # Browser entry (React components + plugin registration)
+├── client/
+│   ├── types.ts      # Shared types
+│   ├── hooks.ts      # useReducer state management + custom hooks
+│   ├── term-pane.tsx # xterm.js terminal pane component
+│   ├── dropdown.tsx  # Dropdown menu next to the + button
+│   ├── side-list.tsx # Right-side terminal list panel
+│   ├── styles.ts     # CSS constants + Campbell dark theme
+│   ├── icons.tsx     # SVG icon components
+│   └── clipboard.ts  # Clipboard utility functions
+├── persistence.ts    # Session persistence (log storage, metadata, startup restore)
+├── platform.ts       # Platform adapter (POSIX / Windows + shell detection)
+├── constants.ts      # Protocol, size, shortcut, and env var constants
+├── server-command.ts # Command-line parsing utilities
+├── shortcut.ts       # Shortcut parsing utilities
+└── logger.ts         # Structured logger
+```
+
+The host side and browser side communicate over WebSocket at `/api/dsh-oh-my-terminal` and do not import each other directly.
+
+## License
+
+[Apache-2.0](LICENSE)

package/README.zh.md

@@ -0,0 +1,101 @@
+# dsh-oh-my-terminal
+
+[![version](https://img.shields.io/badge/version-0.2.1-blue)](package.json)
+[![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+[![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
+
+DSH Web GUI 的底部终端面板插件，基于 `@lydell/node-pty` 提供多终端交互式面板，经 WebSocket 与浏览器端的 xterm.js 通信。支持 Windows ConPTY 与 POSIX openpty，无需本地编译。
+
+## 功能特性
+
+- **多标签终端**：同时管理多个会话，右侧列表替代水平 tab 栏，支持右键重命名
+- **拆分终端**：同组内水平并排，+号旁下拉菜单（新建 / 拆分 / 按种类新建），VSCode 风格操作
+- **会话持久化**：面板收起后会话保持存活，重新打开后自动恢复
+- **快捷键开关**：可配置快捷键呼出/收起面板；DSH 0.1.7-rc.2+ 接入宿主统一快捷键系统，在设置界面改键后标签跟随更新
+- **拖拽调高**：拖拽面板上边缘调整高度
+- **跨平台**：Windows ConPTY / POSIX openpty，由 `@lydell/node-pty` 自动选择，二进制随 tarball 分发，安装即用
+- **可配置 shell**：自定义 shell 命令与启动参数
+
+## 安装
+
+本仓库尚未发布到 npm，通过 GitHub 地址安装：
+
+```bash
+dsh plugin --profile web add github:btsd321/dsh-oh-my-terminal
+```
+
+## 配置
+
+| 配置项 | 说明 | 默认值 |
+|---|---|---|
+| `toggleShortcut` | 呼出/收起终端面板的快捷键（仅旧宿主生效，见下方适配说明） | `` Ctrl+` `` |
+| `shellCommand` | 终端使用的 shell 命令 | 系统默认（bash / PowerShell） |
+
+## DSH 0.1.7-rc.2 快捷键适配说明
+
+DSH 0.1.7-rc.2 起宿主自带全局快捷键系统，其内置终端（右侧栏 `terminal.new` 命令）占用了 `` Ctrl+` ``。为避免同一按键双重响应，本插件自 rc.2 适配版起做出以下调整：
+
+- **接入 shortcuts 系统**：插件注册 `terminal-panel.toggle` 命令，默认绑定 `` Ctrl+Shift+` ``（`web:linux` 无默认键，需在设置界面手动绑定）。改键在 DSH 设置 - 快捷键中进行，面板提示标签跟随当前有效绑定
+- **旧宿主（0.1.7-rc.1 及更早）**：自动降级为裸 `` Ctrl+` `` 监听，`toggleShortcut` 配置照常生效
+- **迁移指引**：升级宿主后，`` Ctrl+` `` 归内置终端使用，插件面板切换改用 `` Ctrl+Shift+` ``；如需改回 `` Ctrl+` ``，请先在 DSH 快捷键设置中解除内置终端的绑定
+
+## 开发
+
+```bash
+# 安装依赖（@lydell/node-pty 自带各平台预编译二进制，装完即用，无需本地编译）
+pnpm install
+
+# 类型检查
+pnpm run typecheck
+
+# 构建（esbuild 双入口，产物输出到 lib/）
+pnpm run build
+
+# 单元测试
+pnpm exec tsx --test tests/unit/*.test.ts
+```
+
+> 请使用 `pnpm`，不要用 `npm`。peer 依赖钉死具体版本，npm 在旧依赖树上做增量解析会报 ERESOLVE。
+
+### 关于构建产物
+
+`lib/` 已纳入版本控制。DSH loader 通过纯 ESM import 加载插件，不走 tsx；同时本仓库不声明 `prepare`/`postinstall` 等生命周期脚本（pnpm 11 对声明了安装类脚本的 git-hosted 包直接报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`），因此构建产物需开发者手动执行 `pnpm run build` 后随源码一起提交。
+
+### 原生依赖说明
+
+终端能力来自 `@lydell/node-pty`（microsoft/node-pty 的预编译分发版，API 同源），版本精确钉在 `1.1.0`：该包 `dist-tags.latest` 指向 1.2.0-beta 系列，用 `^` 会取到 beta。
+
+它是 N-API 产物，二进制按平台拆成六个子包随 tarball 分发，安装期不下载、不编译，同一份二进制同时支持 Node 22 与 Node 24。其 `package.json` 中不存在 `scripts` 字段，pnpm 10/11/12 对没有脚本字段的包不进入构建授权判断分支，行为一致。
+
+宿主半对它是懒加载（首次创建会话时才 `await import()`）：原生绑定若加载失败，异常只影响会话创建，不会让插件模块本身导入失败。
+
+## 架构概览
+
+```
+src/
+├── index.ts          # 宿主半入口（Cordis 插件 + settings + 会话生命周期）
+├── routes.ts         # HTTP 路由处理器
+├── ws-handler.ts     # WebSocket 处理器（pty 数据转发）
+├── client.tsx        # 浏览器半入口（React 组件 + 插件注册）
+├── client/
+│   ├── types.ts      # 共享类型
+│   ├── hooks.ts      # useReducer 状态管理 + 自定义 Hooks
+│   ├── term-pane.tsx # xterm.js 终端面板组件
+│   ├── dropdown.tsx  # +号旁下拉菜单
+│   ├── side-list.tsx # 右侧终端列表
+│   ├── styles.ts     # CSS 常量 + Campbell 暗色主题
+│   ├── icons.tsx     # SVG 图标组件
+│   └── clipboard.ts  # 剪贴板工具函数
+├── persistence.ts    # 会话持久化层（日志落盘 / 元数据 / 启动恢复）
+├── platform.ts       # 平台适配层（POSIX / Windows + shell 探测）
+├── constants.ts      # 协议 / 尺寸 / 快捷键 / 环境变量常量
+├── server-command.ts # 命令行解析工具
+├── shortcut.ts       # 快捷键解析工具
+└── logger.ts         # 统一日志工具
+```
+
+宿主半与浏览器半经 WebSocket 通信，路由前缀 `/api/dsh-oh-my-terminal`，不直接 import。
+
+## License
+
+[Apache-2.0](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: terminal-panel
+      name: dsh-oh-my-terminal