@weniatall/dsh-file-viewer 0.2.11 → 0.3.1

package/README.md

@@ -59,10 +59,46 @@ dsh plugin --profile web add <release-tgz-url>
   - **右键上下文菜单**：在文件树右键点击任意文件，选择 `⬇️ 下载文件` 即可直接提取；
   - **二进制/超大文件兜底区**：对于无法在线渲染的二进制文件或大文件，提示卡片内提供“下载到本地”按钮，完美解决 Web/远程模式下无法提取文件的痛点。
 
+### 调整宽度
+
+两处宽度可以分开拖动，互不影响：
+
+- **面板整体宽度**：拖动抽屉**左边缘**（鼠标移到左侧边框会出现高亮提示条）。抽屉贴在窗口右侧，所以**往左拖是加宽**、往右拖是收窄。最小 420px，最大不超过窗口宽度——上限是窗口本身，避免把面板自己的关闭按钮推出屏幕。双击手柄恢复默认宽度（`min(64vw, 1100px)`），拖动结果会记住。
+- **侧栏宽度**：拖动文件树与预览之间那条分隔线，调整的是侧栏占面板内部的比例；双击恢复默认 280px。
+
+两个宽度分别持久化（`dsh-file-viewer.shell-width` 与 `dsh-file-viewer.tree-width`），所以调宽面板不会改变侧栏比例。
+
+左边缘手柄也支持键盘：聚焦后 `←` / `→` 每次 ±16px（按住 Shift 为 ±64px），`Home` 到最小宽度，`End` 到窗口宽度。
+
+手机端（宽度 ≤ 960px）与全屏模式下抽屉已经铺满可视区域，左边缘手柄自动隐藏。
+
 手机端抽屉占满全屏，文件列表与内容单列切换（左上角 `‹` 返回列表）。
 
 桌面端（Windows）抽屉会自动避让窗口右上角的原生标题栏按钮（最小化 / 最大化 / 关闭）：宿主在 `<html>` 上标记 `data-windows-titlebar` 并给出 `--dsh-windows-titlebar-height`，抽屉顶部从其下方开始，因此标题栏里的图标不会再压在窗口按钮下面；窗口进入全屏后该条带消失，抽屉相应贴到顶边。
 
+## Git 面板
+
+左侧栏顶部有两个页签：**文件**（目录树）与 **Git**（源代码管理）。Git 页签按 VSCode 源代码管理面板的方式组织：仓库 → 分支 → 提交记录 → 该提交的改动文件。
+
+- **仓库识别**：当前根目录本身是仓库时直接读取它；根目录不是仓库、但一级子目录里有仓库时，逐个列出（例如一个工作区下并列多个项目）。根目录位于某个仓库内部（工作区是仓库的子目录）时，读取的仍是那个仓库，且只能打开根目录以内的文件——其余文件在列表里标为「根目录外」并禁用。
+- **分支**：下拉框按「本地分支 / 远程分支」分组，只切换**查看哪条分支的历史**；右侧「检出」按钮才会真正执行 `git checkout` 改写工作区，两者分开以避免误触。远程分支（`origin/xxx`）标注为**只读**，检出按钮禁用——检出远程分支只会得到游离 HEAD 或悄悄新建本地分支，不是用户以为的切换。工作区有未提交改动、git 拒绝检出时，面板直接给出「工作区有未提交的改动，无法切换分支」，不会静默失败。
+- **工作区改动**：面板上部常驻工作区变更列表，按 VSCode 的习惯分成**冲突 / 已暂存 / 未暂存 / 未跟踪**四组；同一个文件既暂存又再修改时标「部分暂存」。点击任一条目在右侧显示该文件的 diff，可暂存/未暂存两侧切换；未跟踪文件没有 diff，按「整文件都是新增」渲染。
+- **提交记录**：按 30 条一页加载，显示标题、短 SHA、作者与日期，底部「加载更多」按需追加，并显示「已显示 N / 总数」。
+- **改动文件列表**：点击任一提交，右侧显示该提交的完整信息（标题、完整 SHA、作者、时间、正文）与相对**第一父提交**的改动文件列表（合并提交同理；根提交与空树比对）。`A / M / D / R / C` 等状态用颜色区分。
+- **该提交的 diff**：提交详情有「变更文件 / 改动内容」两个页签，后者是该提交针对同一基准（第一父提交）的完整 patch，按文件分段并各自标注 `+N -M`。两个页签取的是同一对 revision，不会出现列表与 diff 基准不一致的情况。
+- **跳转到文件**：点击改动文件会在右侧已有的预览器里打开**该提交中的版本**，而不是工作区当前内容——两者恰恰在历史最有价值的时候不同。被该提交删除的文件从父提交读取，所以删除行也能打开；重命名显示旧路径的内容。预览顶部会标明来源提交，避免被误认为当前文件。`‹` 返回侧栏继续浏览提交。
+
+只读操作（列出仓库、分支、历史、改动文件）不会修改仓库；面板中唯一的写操作是用户显式点击「检出」。
+
+### 边界与安全约束
+
+- **检出范围**：如果当前根目录只是某个仓库的**子目录**（仓库在上级），检出会一并改写根目录以外的文件。面板会先显示醒目提示，并在执行前要求确认；宿主端在未收到显式同意时直接拒绝（`checkout-outside-root`），不会默认放行。
+- **仓库探测上限**：为控制开销，子目录探测最多 32 个候选目录。达到上限时面板明确提示「列表可能不完整」，而不是静默返回一个看似完整的空列表。
+- **环境隔离**：每次调用 `git` 都会剥离 `GIT_DIR`、`GIT_WORK_TREE`、`GIT_INDEX_FILE` 等变量，避免宿主进程环境把命令重定向到根目录以外的仓库；检出时用 `-c core.hooksPath=` 禁用仓库 hooks，不会执行用户仓库里的脚本。
+- **错误如实上报**：`git` 不存在报 `git-unavailable`，diff 失败报 `git-failed`，都不会伪装成「没有仓库」或「没有改动」。
+
+Git 页签在首次打开时才请求仓库信息（识别仓库需要对子目录做 `git` 探测），切换根目录会丢弃已缓存的仓库与历史；刷新会保留正在浏览的分支。
+
 ## 访问边界与安全访问路径
 
 插件**内置可访问**所有**已注册的工作区目录**以及**各会话的工作目录**。