From 2247f6ecce0af4e8df91da5cab147c368d7ed7b5 Mon Sep 17 00:00:00 2001 From: Menghuan1918 Date: Sun, 9 Aug 2026 11:45:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20refresh=20README=20=E2=80=94=20pitch,?= =?UTF-8?q?=20feature=20map,=20shortcut=20cheat-sheet,=20state=20self-heal?= =?UTF-8?q?ing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructures the README for readability: a one-line pitch plus "why use it" bullets, emoji-grouped feature sections, a keyboard-shortcut table, and a quick-start flow. Adds the recently shipped capabilities to the feature map (tab/+ menu icons, the @-reference row button, right-click copy relative/absolute path, persisted-state self-healing) and documents the split-id de-duplication under architecture. --- README.md | 107 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 68 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index d272cce..121e4c3 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,85 @@ # dsh-better-sidebar -DeepSeek Harness Web GUI 的 **VSCode 风格右侧侧边栏**插件：文件资源管理器、文件编辑/预览、交互式终端、Git 面板，**按会话（conversation）记忆与隔离**。样式完全复用 `--dsw-*` 主题变量与 `@deepseek-ai/dsh-client-ui-primitives`，观感与 GUI 原生一致，且**明暗主题自适应**（终端与编辑器就地重着色）。 +> DeepSeek Harness Web GUI 的 **VSCode 风格右侧侧边栏**插件 —— 文件管理、编辑预览、真实终端、Git 面板，一个面板全部搞定。 -image -image +sidebar screenshot 1 +sidebar screenshot 2 -## 功能 +## 为什么用它 -### 文件资源管理器（Explorer） -- 懒加载目录树，根目录 = 当前会话工作目录（cwd） -- 目录优先排序、隐藏文件（点开头）变暗显示、每层 1000 项上限 +- **⚡ 工作流不断档**：编辑文件、跑终端、看 Git 状态、拖 Tab 分栏对比，全在对话旁边完成，无需切窗口 +- **🧠 按会话记忆与隔离**：每个 conversation 拥有独立的布局、分栏、Tab 与目录展开状态，切换会话即切换整套工作台 +- **🎨 与 GUI 浑然一体**：完全复用 DSH 主题变量与官方组件，明暗主题自适应，观感就是原生的 + +--- + +## ✨ 功能一览 + +### 🗂️ 文件资源管理器 + +- 懒加载目录树，根目录 = 当前会话工作目录（cwd）；目录优先、隐藏文件变暗、每层 1000 项上限 - 点击文件在侧边栏打开编辑器；刷新按钮重载 -- **右键行**弹出菜单：复制相对地址 / 复制绝对地址（复制成功后行内短暂显示"已复制"） -- **悬浮行尾的 `@文件` 按钮**：点击把 `@相对路径` 追加到输入框草稿（如 `@src/main.ts`） +- **悬浮行尾 `@文件` 按钮**：一键把 `@相对路径` 追加到输入框草稿（如 `@src/main.ts`），引用文件不再手打路径 +- **右键行 → 复制相对地址 / 复制绝对地址**，复制成功行内短暂显示"已复制" -### 文件编辑与预览（Editor） -- **CodeMirror 6** 编辑器：**自动换行** + 按扩展名**语法高亮**（js/ts/jsx/tsx、json、python、html、css、xml、yaml、sql、java、c/c++、rust、go、php、shell、toml、nginx、dockerfile、properties…），**明暗主题自适应**（跟随应用色系，切换时文档/撤销/滚动不丢） +### 📝 文件编辑与预览 + +- **CodeMirror 6**：自动换行 + 按扩展名语法高亮（js/ts/jsx/tsx、json、python、html、css、xml、yaml、sql、java、c/c++、rust、go、php、shell、toml、nginx、dockerfile、properties…） - 脏点标记 + **Ctrl/Cmd+S 保存**（原子写入）；512KB 截断横幅、二进制文件提示 -- 图片直接预览（媒体路由）；**Markdown 支持 预览/编辑 切换**——预览实时渲染未保存草稿，切换不丢编辑状态 -- 编辑器/终端/资源管理器在**切换 Tab 时不卸载**：终端保持连接与回滚，编辑器保留草稿 +- 图片直接预览；**Markdown 预览/编辑切换**，预览实时渲染未保存草稿 +- 切换 Tab 不卸载：编辑器保留草稿与撤销栈 -### 终端（Terminal） -- xterm.js + node-pty（真实 shell），**每会话最多 3 个**；**Tab 打开期间一直保活**：切换 Tab/分栏、切换会话（30 秒内返回）、刷新页面都重连到**同一个 shell 进程**并回放转录，不受激活状态影响 -- 真正关闭 Tab **立即释放配额**（socket 断开时也由 `pty.close` API 兜底释放）；连续失败后停止重连并显示原因与重试按钮 -- 明暗主题自适应（表面色取自主题 token + one-dark/one-light ANSI 色板） +### 💻 终端 -### Git 面板 -- status（暂存/未暂存分组）、按文件 diff（HEAD vs 工作区/暂存区）、stage/unstage（单个与全部）、commit、分支切换、提交历史——基础集 +- xterm.js + node-pty **真实 shell**，每会话最多 3 个 +- **Tab 打开期间一直保活**：切换 Tab/分栏、切换会话（30 秒内返回）、刷新页面都重连到同一个 shell 进程并回放转录 +- 真正关闭 Tab 立即释放配额；连续失败停止重连并显示原因与重试按钮 -### VSCode 式分栏工作台 -- **拖 Tab 到分栏边缘**（左/右/上/下 25% 区）即拆分新分栏，拖到中间合并；拖到另一个 Tab 上则插入其前 -- 分隔线拖拽调整比例；面板宽度从左侧缘拖拽 -- 面板**折叠**滑出隐藏，右缘展开按钮常驻；全屏展开按钮（还原为内容区一半） +### 🌿 Git 面板 -### Tab 栏 -- Tab 最大宽度 160px、横向滚动；**`+` 按钮紧贴最右 Tab**（溢出时吸附右缘） -- **Tab 与 `+` 菜单均带类型图标**（Explorer=文件夹、Git=分支、终端=终端、编辑器=代码文件） -- `+` 菜单新建 Tab（Explorer / Git / 终端，终端受 3 个上限约束）；**中键点击关闭 Tab** -- 空分栏不再显示空提示，而是**可打开类型卡片**（点击即开） +- status 暂存/未暂存分组、按文件 diff（HEAD vs 工作区/暂存区）、stage/unstage（单个与全部）、commit、分支切换、提交历史 -### 会话隔离与拦截 -- 侧边栏布局/分栏/Tab/目录展开按会话持久化（localStorage），切换会话即切换整套状态 -- 侧边栏**占用布局**（挤窄对话列而非悬浮遮挡，动画过渡）；宽度永不超过视口，陈旧状态自动净化 +### 🧩 VSCode 式分栏工作台 + +- **拖 Tab 到分栏边缘**（左/右/上/下）即拆分新分栏，拖到中间合并，拖到另一个 Tab 上插入其前 +- 分隔线拖拽调整比例；面板宽度从左侧缘拖拽；折叠滑出隐藏 + 全屏展开 + +### 📑 Tab 栏 + +- **Tab 与 `+` 菜单均带类型图标**（文件夹 / 分支 / 终端 / 代码文件） +- `+` 菜单新建 Explorer / Git / 终端（终端受 3 个上限约束）；**中键点击关闭 Tab** +- 空分栏显示可打开类型卡片，点击即开 + +### 🔁 会话隔离与状态自愈 + +- 布局/分栏/Tab/目录展开按会话持久化（localStorage），切换会话即切换整套状态 +- **陈旧状态自动净化**：结构校验、宽度钳制视口、损坏的重复 id 自动重新编号——刷新后分栏与新生成的 id 永不冲突，不会出现"文件开进两个分栏" +- 侧边栏**占用布局**（挤窄对话列而非悬浮遮挡，动画过渡） - 拦截对话"产出文件"行：点击改为在侧边栏打开，而不是系统默认程序 -### 界面风格（对标 GUI 原生） -- 行/按钮/间距/动效对齐应用自身组件：34px 圆角树行 + 22px 缩进步长 + 挂载淡入、28px 圆形图标按钮、36px 分节头部节奏 +### 🎨 界面风格 + +- 行/按钮/间距/动效对齐应用自身组件：34px 圆角树行、28px 圆形图标按钮、挂载淡入 - 键盘焦点可见（focus-visible 环）、`prefers-reduced-motion` 下关闭全部动画 -## 从源码安装 +## ⌨️ 快捷键速查 + +| 操作 | 按键 | +|---|---| +| 保存编辑 | `Ctrl/Cmd + S` | +| Git 提交 | `Ctrl + Enter` | +| 关闭 Tab | 鼠标中键 | +| 拆分分栏 | 拖 Tab 到分栏边缘 | +| 合并分栏 | 拖 Tab 到分栏中间 | +| 引用文件到输入框 | 悬浮行尾 `@文件` 按钮 | +| 复制文件路径 | 右键行 → 复制相对/绝对地址 | + +--- + +## 🚀 快速开始 ### 前置条件 + - 已安装 DSH（`dsh web` 可运行），Node.js ≥ 20、pnpm ≥ 10 - DSH 源码 checkout 位于 `~/.dsh/source/current`（`@deepseek-ai/*` 类型依赖以 `link:` 指向它；若 checkout 在其他路径，修改 `package.json` 中对应的 `link:` 路径） @@ -97,7 +126,7 @@ pm2 restart dsh-web # 或你自己的 dsh web 启动方式 重新 `pnpm build`（host/client 双产物）→ `pm2 restart dsh-web` → 刷新页面；`link:` 引用无需重新 install。 -## 开发 +## 🛠️ 开发 ```sh pnpm typecheck # tsc --noEmit @@ -106,7 +135,7 @@ pnpm build # tsc + tsdown → lib/index.js + lib/client.js pnpm watch # tsdown --watch（client bundle 热重建） ``` -## 架构 +## 🏗️ 架构 一个 npm 包，host/client 双半结构（与 DSH monorepo 内 client 包同构）： @@ -117,16 +146,16 @@ pnpm watch # tsdown --watch（client bundle 热重建） - 所有 API 携带 `sessionId`；cwd 权威值取自会话 header，会话未附加（页面加载竞态）时回退客户端摘要 cwd，再回退进程 cwd；终端按 `${sessionId}:${tabId}` 键控，重连时若权威 cwd 变化则重启 shell 到正确目录 - 路由与 `/api` 同款信任围栏（Host 头 loopback / `connection.trustedHosts`，`src/trust-fence.ts`，拷贝自 `@deepseek-ai/dsh-client-connection`，BSD-3-Clause） -- client 状态按会话持久化到 `localStorage`（`dsh-sidebar:v1:`），读取时结构校验 + 宽度钳制视口 +- client 状态按会话持久化到 `localStorage`（`dsh-sidebar:v1:`），读取时结构校验 + 宽度钳制视口 + 重复 id 重新编号 - client bundle externals 仅模块表词条（react/cordis/ui-primitives 等），xterm/CodeMirror 等全部内联 -## 安全边界 +## 🔐 安全边界 - 路由受 Host 头信任围栏保护（与 `/api` 一致；`0.0.0.0` 部署时由 `dsh web` 启动器动态派生的 LAN IP 列表生效） - `fs.write` 仅文本写入、原子替换（临时文件 + rename）；`/sidebar/file` 仅限会话 cwd 内的媒体文件 - 提交/分支操作仅调用 git CLI，绝不设置 git 身份 -## 已知限制（v1 非目标） +## ⚠️ 已知限制（v1 非目标） - Git 无 push/pull/fetch；无文件 watcher（手动刷新） - 工具行内的文件打开按钮（核心代码）不可拦截，仅"产出文件"行被接管