@xbzbing/dsh-git-panel 1.7.0 → 1.8.1

package/README.en.md

@@ -11,37 +11,44 @@ The panel only reads the Git repository at the current session's working directo
 ## Install
 
 ```bash
-# npm (default)
+# Stable release (npm)
 dsh plugin --profile web add @xbzbing/dsh-git-panel@latest
 
-# or from the GitHub repository (the built tree is committed, no local build needed)
-dsh plugin --profile web add github:xbzbing/dsh-git-panel
+# Pre-release (GitHub Release asset; never published to npm)
+dsh plugin --profile web add https://github.com/xbzbing/dsh-git-panel/releases/download/v1.8.0-rc.1/xbzbing-dsh-git-panel-1.8.0-rc.1.tgz
 ```
 
-After installing or updating, restart the `dsh web` service and refresh the page; the **Git** panel then appears in the workspace tab bar (after Chat and Trajectory). The plugin has a host half and a client half, and both the host mount and the client bundle manifest are fixed when the service starts, so code updates (installing, or an `add` that overwrites `lib`) usually need a service restart — a page refresh alone may not pick them up. In-panel settings (the input-bar marker toggle and the default diff view on the detail page) are hot-written and apply immediately without a restart.
+Pre-release versions carry a `-` suffix (e.g. `1.8.0-rc.1`): they appear only as GitHub prereleases, are never pushed to npm, and never trigger the in-panel "update available" prompt. A stable release ships to npm and as a stable GitHub Release at the same time. `lib/` is not committed to the repository — do not install with `dsh plugin add github:…`; use the npm or Release asset URL above.
 
-> **Compatibility**: verified on `dsh@0.2.1-alpha.4` — installation, the Git panel, the input-bar marker, and the host RPC all work normally.
+After installing or updating, the **Git** panel appears in the workspace tab bar (after Chat and Trajectory) with no service restart and no page refresh: dsh's hmr watches the profile's `package.json` and patch files and mounts the plugin live, while the client bundle (`lib/client.js`) is picked up within a second of being replaced and pushed to the browser over `/plugins/events`, where the old fiber is torn down and the new code remounted in place — already-open pages get the update without reloading. Only host-half modules (`lib/host/*.js`, whose loaded code keeps running until the next restart) and profile changes made while hmr is unavailable still need a restart. In-panel settings (the input-bar marker toggle and the default diff view on the detail page) are hot-written and apply immediately.
+
+> **Compatibility**: verified on `dsh@0.2.1-rc.2` — installation, the Git panel, the input-bar marker, and the host RPC all work normally.
 
 ## Features
 
-- **Overview** — three columns. The left column is the branch / tag list; clicking a ref filters history by it. The middle column is the commit history graph, searchable by commit message, commit hash, author, or date; hovering a commit shows a card with its full commit message (comment). The right column is the selected commit's changed-file tree and commit message; click a file to see its diff within that commit in a modal.
-- **Changes** — the local working tree. The left column has a statistics bar (file count / added·deleted lines / last-change time), the uncommitted change list with per-file checkboxes, and a commit box with an **Amend** checkbox; per-file stage / unstage / discard and manual commit are supported. The right column is the selected file's diff.
-- **AI commit-message suggestion** — the "AI suggest" button beside the commit box writes a commit message from the current uncommitted changes (restricted to your checked files when any are selected) in the style of the repository's existing commits, using the model you have configured in DSH; the result lands in the commit box for you to edit before committing (while it runs, the box turns read-only and shows a loading icon inside it, so your typing cannot race the result; on success it is filled and focused, and a failure never overwrites what you already wrote). No changes to summarize, a missing model service, and generation failures all report a clear message. **The language is automatic by default**: it is inferred from the repository's own commit history (a recency-weighted vote that ignores mechanical commits such as releases, merges and reverts, and looks only at the current git author's commits once they number 3 or more), so a Chinese repository gets Chinese and an English one gets English; the plugin detail page can also pin 中文 or English. **Privacy note: the generation request sends your diff content to the provider of the model you configured in DSH.** The plugin detail page can turn the button off and tune the input budget (diff bytes sent to the model, default 128 KiB), the output limit (default 4096 tokens; reasoning counts against it on thinking models), and the generation timeout (default 15 s).
-- **Tag management** — the commit-detail header in the Overview right column creates a tag at the selected commit (lightweight, or annotated with a message); tags already on that commit show as deletable chips, and deletion asks for confirmation. Creating and deleting tags only affects the local repository and is never pushed to the remote; run `git push <remote> <tagname>` (or `--tags`) yourself to sync.
-- **Stash** — the Changes page stashes the current uncommitted changes (with an optional message); the stash list below supports apply / pop / drop. A pop or apply that conflicts keeps the stash entry and reports it, so nothing is lost halfway. Drop asks for confirmation.
-- **Switch branch** — hovering a local branch or remote ref in the Overview left column reveals a "Switch" button at the end of the row (on a narrow panel the rows of the "Filter branch" bottom sheet carry it; touch devices always show it). The checked-out branch has none, and clicking the row itself still filters the history. Clicking "Switch" opens a confirm dialog. A remote ref is never checked out directly (that would detach HEAD): an existing local branch of the same name is switched to, otherwise the confirm step runs `git checkout -b <name> --track <origin/name>` to create and track it. The dialog shows the current → target switch, and when there are uncommitted changes it reports the count and offers both ways out — switch directly (git refuses and leaves the work tree untouched if the changes collide with the target) or stash first (untracked files included) and restore them afterwards from Changes → Stash (never restored automatically; restoring may need manual conflict resolution). A landed switch reloads the history, branch list, change list, and the Files tab's directory cache.
-- **Commit undo** — the same commit-action area can "Revert this commit" (appends a reverse commit, leaving the work tree untouched) or "Reset to here" (reset in soft / mixed / hard modes). Hard reset lists the uncommitted changes it will permanently discard and requires an extra acknowledgement; it is never the default, and whenever uncommitted changes are present a note warns they may be work the dsh AI is doing. Both revert and reset only rewrite the local repository and are never pushed to the remote; sync the remote branch yourself.
-- **Shared-worktree guards** — tag / stash / revert / reset and other write actions share the repository with the dsh AI, so every dialog footer suggests letting the AI run Git for you; a `.git/index.lock` clash (another process is working) retries once and surfaces a friendly "Git is busy" message instead of the raw error.
-- **File browser** — opening the workspace Git tab selects Files outside a Git repository, Overview in a clean repository, or Changes when there are uncommitted changes. Non-Git directories use the current directory as the browse root. The resizable tree loads one directory at a time and hides `.git`, shows dsh's official type icons per file, and dims entries excluded by `.gitignore`; the preview shows code/text or images, with a button to copy the file's relative path and placeholders for oversized or binary files. Markdown defaults to source; choose Rendered to use dsh's built-in Markdown view. HTML also defaults to source; choose Rendered to preview the page inside a locked-down sandbox (`allow-scripts`, no same-origin) — it never auto-runs. The source view is row-virtualized for large files (only the visible rows render); very large files disable highlighting and over-long lines are truncated, keeping it responsive.
-- **Image zoom** — the file preview and the diff panes share one zoom component: pinch on a Mac trackpad (delivered as a Ctrl+wheel event by Chromium/Firefox/Safari 15+, as Safari gesture events earlier) and Ctrl+wheel both zoom around the cursor (10%–800%); once zoomed, pan with two-finger scrolling, the wheel, the scrollbars, or a **left-button mouse drag** (grab cursor — a drag never doubles as a double click, and dragging the browser's own scrollbar is left alone); a floating zoom bar offers − / percentage / + / Fit / fullscreen (fullscreen lives in the bar only: an inline click entry would swallow the first click of every double click); double-click toggles between fit and 100%; the lightbox keeps zoom and pan, and closes on <kbd>Esc</kbd>, the close control, or a press on its empty area.
-- **In-code find** — the file source preview and the diff views support <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>F</kbd> to find in place: every match is highlighted preserving syntax colors, with an active/total count, <kbd>Enter</kbd> / <kbd>Shift</kbd>+<kbd>Enter</kbd> or `‹` `›` to walk matches, a case-sensitivity toggle (insensitive by default), and <kbd>Esc</kbd> to close. Match counting scans the whole content, so matches outside the viewport are counted and reachable too.
-- **Syntax-highlighted diffs** — the overview modal, changes page, and file browser share dsh's built-in highlighter. Languages are selected by file extension and grammars load on demand; word-level change emphasis remains available in the diff views.
-- **Diff modes** — unified / split / before / after views. Unified is a single inline column (each change shown as adjacent `-`/`+` lines, saving horizontal space); split is side-by-side. Both carry on-demand expansion of hidden between-hunk context and word-level emphasis on changed lines. The default view is selectable on the plugin detail page (unified / split) and can be switched per diff from the toolbar.
-- **Mobile / narrow-panel layout** — at 620px wide or below (a phone in portrait, or a sidebar squeezing the panel) the UI switches to a single-column drill-in: the three columns collapse to one, and you tap from a list into its detail / diff / preview and come back with a Back button. The Overview branch filter becomes a bottom sheet, commit rows go two-line for easier tapping, the tab-bar controls wrap onto a second row instead of hiding, and the side-by-side diff mode is dropped on narrow screens. Widening the panel restores the three-column layout, so the desktop experience is unchanged. On touch devices (e.g. tablets) the per-file row actions stay visible and hit targets grow.
-- **Show input-bar marker toggle** — the plugin detail page can toggle the input-bar marker; when off, the input bar stays clean and the Git tab shows a status dot instead (green = synced, orange = dirty). The two are mutually exclusive and changes apply immediately. The same config section also sets the default diff view (unified / split) and the commit-graph line style (parallel VSCode style / compact git-log style, parallel by default). "AI commit message" is its own config card: besides the button toggle it sets the generation language (Auto / 中文 / English; Auto by default, following the language you write commits in for that repository) and tunes the input budget / output limit / generation timeout (ranges 16–512 KiB / 256–16384 tokens / 5–120 s; out-of-range values clamp to the boundary).
-- **Input-bar Git marker** — a zsh-theme `<repo> (<branch>)` marker: the repo name is cyan, `(branch)` is green when in sync and orange when there are uncommitted changes; hover shows the full repository path, and clicking jumps to the panel (to Changes when dirty, otherwise to Overview); in non-Git directories the input-bar marker is hidden, while the workspace Git tab still opens the file browser.
+- **Overview** — three columns: the branch / tag list, a searchable (commit message, hash, author, date) commit history graph, and the selected commit's changed-file tree and message; click a file to see its diff within that commit in a modal.
+- **Changes** — per-file stage / unstage / discard and batch discard of the checked changes (with confirmation), manual commit and **Amend**, stash (create / apply / pop / drop), plus file-count and added·deleted statistics.
+- **Common Git actions** — switch branch (a remote ref becomes a same-named tracking branch, never a detached HEAD; uncommitted changes can be stashed first), create and delete tags, and revert / reset a commit (hard reset lists the changes it will discard and requires an extra acknowledgement). All of them only rewrite the local repository and never push automatically.
+- **AI commit-message suggestion** — writes a commit message from the current uncommitted changes in the style of the repository's existing commits, with the language inferred from the repository history by default (or pinned to 中文 / English); the model can be pinned on the detail page from the DSH model list (provider → model → reasoning-effort cascade, **following the current session by default**), where the suggestion can also be turned off and the input budget, output limit, and timeout tuned. **Generation sends your diff content to the provider of the model you picked.**
+- **Input-bar Git marker** — a zsh-style `<repo> (<branch>)`, green when in sync and orange when there are uncommitted changes; hover shows the repository path and a click jumps to the panel. It can be turned off on the plugin detail page, which moves the status to a dot beside the Git tab.
+- **File browser** — browse the workspace tree inside the panel (loaded on demand, `.gitignore` entries dimmed, `.git` hidden) and preview code / Markdown / HTML / images (local images embedded in rendered Markdown display inline, e.g. README figures; ```mermaid fences render as diagrams with a code-block fallback); the source preview wraps long lines by default and can switch to horizontal scrolling; it also works outside a Git repository, rooted at the current working directory.
+- **Diff and source viewing** — unified / split / before / after views with syntax highlighting, word-level emphasis, on-demand expansion of hidden context, and <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>F</kbd> find-in-place; images zoom around the cursor (10%–800%) and can be panned by dragging or opened fullscreen.
+- **Narrow panel / mobile** — at 620px wide or below the UI switches to a single-column drill-in (branch filter as a bottom sheet, two-line commit rows) and restores the three columns when widened.
+- **Shared-worktree guards** — write actions share the repository with the dsh AI, so dialog footers suggest letting the AI run Git for you; a `.git/index.lock` clash retries once and reports a friendly "Git is busy".
 - The UI follows the DSH system language, in Simplified Chinese and English.
 
+## Permissions and data boundaries
+
+The panel runs with the DSH process's privileges. These are the boundaries worth knowing before installing:
+
+- **Git commands** — every git command goes through the host `subprocess` service: argv arrays, no shell string concatenation, cwd locked to the repository root, with a per-command timeout and output caps. It never uses `--force` and never touches your git config.
+- **File access** — it only reads files inside the workspace (diffs, file browser, the AI-suggestion input), after validation plus a realpath containment check: symlinks pointing outside the repository are refused and `.git` is not browsable. The one write is **discarding an untracked entry** — it deletes the working-tree file after your confirmation, and refuses the whole batch when an entry is itself a Git repository.
+- **Network** — the plugin itself makes exactly one request, `GET https://api.github.com/repos/<owner>/<repo>/releases/latest`, for the "new version available" notice in the version bar (5 s timeout, cached in-process). `fetch` / `pull` / `push` / `publish` reach the network only after you click, through git commands, and credentials stay with git: the plugin never reads, stores, or returns a token or credential.
+- **External service** — only "AI commit message" sends diff content to the model provider you configured in DSH; the host performs the call and the plugin holds no credentials.
+- **System dependency** — the `git` CLI. Without git, or outside a Git repository, only the file browser is shown, rooted at the current working directory.
+
+The client bundle (`lib/client.js`) makes no network requests of its own — it talks to the host over same-origin RPC — and the plugin collects no telemetry. UI-only preferences such as the panel font size and pane widths live in browser localStorage and never contain repository content. Apart from git commands and the confirmed deletion, the plugin's code reads and writes nothing outside the workspace; the detail-page settings are persisted by the host into the profile config.
+
 ## Screenshots
 
 | Overview | File-diff modal |
@@ -49,6 +56,8 @@ After installing or updating, restart the `dsh web` service and refresh the page
 | ![Overview: branches, commit graph, commit detail, hover card](docs/assets/screenshots/1-git-panel-overview.png) | ![File-diff modal: syntax-highlighted unified / split diff with on-demand gap expansion and word-level emphasis](docs/assets/screenshots/2-overview-tab.png) |
 | Changes | File browser |
 | ![Changes: stats bar, uncommitted list, commit box, diff](docs/assets/screenshots/3-changes.png) | ![File browser: lazy directory tree, official type icons, dimmed ignored entries, and file preview](docs/assets/screenshots/4-files.png) |
+| Narrow / mobile | Plugin config |
+| ![Narrow / mobile: single-column drill-in layout with stats bar, change list, and commit box](docs/assets/screenshots/5-mobile-panel.png) | ![Plugin config: marker toggle, default diff view, graph style, and AI generation settings](docs/assets/screenshots/6-plugin-config.png) |
 
 ## Architecture
 
@@ -67,7 +76,7 @@ npm run test:e2e    # isolated file:// headless-browser e2e (never touches a run
 npm test            # unit + e2e
 ```
 
-The host output is emitted one file per `src/host/` module (stack traces land in the module that raised) and is never minified: the typert gateway validates arguments by method parameter name, and minification would rename them and break the wire contract. Client changes are not hot-reloaded — rebuild and refresh the page. `lib/` is committed as a build artifact so `dsh plugin add github:…` installs the built tree directly; after editing `src/` you must rebuild and commit, or a GitHub install loads a stale entry. The test-time `lib/testkit.mjs` is not committed. For local development, add the plugin to a dsh web profile's `dsh.profile.bundles` with a `file:` dependency pointing at this directory; a rebuild makes it effective.
+The host output is emitted one file per `src/host/` module (stack traces land in the module that raised) and is never minified: the typert gateway validates arguments by method parameter name, and minification would rename them and break the wire contract. Client changes are hot-reloaded: after rebuilding `lib/client.js`, the running dsh detects the file change within a second and pushes it to the browser for an in-place swap (old fiber torn down, new code remounted) — no page refresh needed; host changes still need a restart, since loaded modules keep running their previous code. `lib/` is local build output and is not committed; for local development, add the plugin to a dsh web profile's `dsh.profile.bundles` with a `file:` dependency pointing at this directory, then run `node build.mjs`.
 
 ## Project structure
 
@@ -98,6 +107,10 @@ src/
     diff.ts         unified diff → side-by-side rows + inline rows + stats
 ```
 
+## Acknowledgements
+
+Thanks to [@ivanant](https://github.com/ivanant) for the many optimization suggestions and iteration requests filed against this project. Mobile layout, batch selection in the changes page, AI commit messages, commit-graph and icon polish, and publishing a branch that has no upstream all came mostly from his real-world usage reports — feedback that moved the panel well past "it works".
+
 ## License
 
 [MIT License](LICENSE).

package/README.md

@@ -11,37 +11,44 @@
 ## 安装
 
 ```bash
-# npm（默认）
+# 正式版（npm）
 dsh plugin --profile web add @xbzbing/dsh-git-panel@latest
 
-# 或从 GitHub 仓库安装（仓库已提交构建产物，无需本地构建）
-dsh plugin --profile web add github:xbzbing/dsh-git-panel
+# 预发布（GitHub Release 附件，不发 npm）
+dsh plugin --profile web add https://github.com/xbzbing/dsh-git-panel/releases/download/v1.8.0-rc.1/xbzbing-dsh-git-panel-1.8.0-rc.1.tgz
 ```
 
-安装或更新后，重启 `dsh web` 服务再刷新页面，工作区标签栏（「对话」「轨迹」之后）就会出现 **Git** 面板。插件分 host 与 client 两半，宿主挂载和 client bundle 清单都在服务启动时定型，因此代码更新（安装、`add` 覆盖 `lib`）通常需要重启服务，仅刷新页面可能看不到变化。面板内的配置项（详情页的输入框标记开关、差异默认视图）走配置热写，改动即时生效、无需重启。
+预发布版本号带 `-`（如 `1.8.0-rc.1`），只出现在 GitHub Release，不会推送 npm，也不会触发面板里的「有新版本」提示；正式版发布时 npm 与稳定 Release 同时上线。`lib/` 不随仓库提交，请不要用 `dsh plugin add github:…` 安装——改用上面的 npm 或 Release 附件 URL。
 
-> **兼容性**：已在 `dsh@0.2.1-alpha.4` 上实测，安装、Git 面板、输入框标记与 host RPC 均可正常使用。
+安装或更新后，工作区标签栏（「对话」「轨迹」之后）就会出现 **Git** 面板，无需重启服务、也无需刷新页面：dsh 的 hmr 监听 profile 的 `package.json` 与 patch 文件，插件装好即热挂载；client 半产物（`lib/client.js`）被替换后也会被秒级轮询拾取，经 `/plugins/events` 推给浏览器原地热替换（拆掉旧 fiber 重挂新代码），已打开的页面不刷新即可拿到更新。仅 host 半模块（`lib/host/*.js`，进程内已加载的旧代码会一直跑到重启为止）与 hmr 不可用时的 profile 变更仍需重启服务。面板内的配置项（详情页的输入框标记开关、差异默认视图）走配置热写，改动即时生效。
+
+> **兼容性**：已在 `dsh@0.2.1-rc.2` 上实测，安装、Git 面板、输入框标记与 host RPC 均可正常使用。
 
 ## 功能
 
-- **Git 总览**：三栏布局。左栏是分支 / 标签列表，点击某个引用即按它过滤历史；中栏是提交历史图，支持按提交信息、commit 哈希、作者、日期搜索，悬停某条提交弹出卡片显示完整提交信息（comment）；右栏是选中提交的变更文件树与提交信息，点击文件在弹出的 modal 里查看该文件在此提交中的差异。
-- **变更记录**：面向本地工作区。左栏是统计条（文件数 / 增删行数 / 最近变更时间）、带复选框的未提交变更列表、以及含 **Amend** 复选框的提交框，支持逐文件暂存 / 取消暂存 / 丢弃与手动提交（「放弃更改」只出现在未暂存行——丢弃是工作区操作，已暂存的文件要撤销请先「取消暂存」再放弃），勾选若干文件后可「放弃选中的更改」批量丢弃工作区改动（二次确认只报将丢弃的文件数量，丢弃后不可恢复；选中项里来自暂存侧的条目不在放弃范围，会在确认框里单独说明）；未跟踪目录会整目录删除；若该条目本身就是一个 Git 仓库（嵌套仓库、子模块或 bare 仓库），递归删除会连带删掉整个内部仓库，因此会整批拒绝、一个都不删（若该仓库是在删除过程中才出现的，同批更早的条目可能已被删除，提示会说明并要求刷新），两种情况都提示此操作请在终端中完成；只「包含」仓库的普通目录仍作为整体删除；鼠标移到文件行尾的图标按钮上会给出该操作的功能说明；右栏是选中文件的差异对照。
-- **AI 生成提交信息**：提交框旁的「AI 生成」按钮根据当前未提交变更（勾选了文件则只看这些文件）与仓库既有提交风格，调用你在 DSH 中配置的模型生成提交信息，填入提交框后可编辑再提交（生成期间提交框转为只读并在框内显示 loading 图标，避免手写内容与生成结果竞争；成功后自动填入并聚焦，失败不覆盖已有草稿）；没有可生成的变更、模型服务不可用或生成失败都会给出明确提示。**生成语言默认自动**：从仓库历史提交的语言推断（按新旧加权的投票，忽略 release / merge / revert 等机械提交；当前 git 作者在此仓库有 ≥3 条提交时只看本人的），中文仓库即生成中文、英文仓库即生成英文，也可在插件详情页固定为中文或 English。**隐私提示：生成请求会把 diff 内容发送给你在 DSH 中所配置模型的供应商。** 可在插件详情页关闭该按钮，并调整输入预算（发送给模型的 diff 上限，默认 128 KiB）、输出上限（默认 4096 tokens，思考模型的推理计入该预算）与生成超时（默认 15 秒）。
-- **标签管理**：在「Git 总览」右栏的提交详情顶部可为选中的提交创建标签（轻量标签，或带说明的附注标签）；该提交上已有的标签以可删除的标签片呈现，删除走二次确认。创建与删除标签都只作用于本地仓库，不会推送到远程，如需同步需自行 `git push <remote> <tagname>`（或 `--tags`）。
-- **切换分支**：鼠标移到 Git 总览左栏的本地分支或远程引用行上，行尾出现「切换」按钮（窄面板在「筛选分支」底部弹层的行上，触屏设备按钮常显）；当前分支没有该按钮，单击行本身仍是筛选提交历史。点击「切换」后弹出确认框。远程引用不会直接检出（那会游离 HEAD）：已有同名本地分支就切换它，否则确认后执行 `git checkout -b <名> --track <origin/名>` 创建本地分支并设置跟踪。确认框显示「当前 → 目标」；有未提交变更时列出数量并提供两种选择——直接切换（与目标分支冲突时由 Git 拒绝、工作区不变），或先贮藏（含未跟踪文件）再切换，之后到「变更记录 → 贮藏」手动恢复（不会自动恢复，恢复冲突需手动解决）。切换成功后提交历史、分支列表、变更列表与文件浏览的目录缓存一并刷新。
-- **提交回撤**：同一处提交操作区可「还原此提交」（revert，追加一个反向提交、不动工作区）或「重置到此」（reset，软 / 混合 / 硬三挡）。硬重置会列出将被永久丢弃的未提交改动并要求额外勾选确认，始终不作为默认方式；检测到未提交改动时提示这些改动可能是 dsh AI 正在进行的工作。还原与重置都只改写本地仓库，不会推送到远程，远端分支需你自行推送同步。
-- **贮藏（stash）**：「变更记录」页可将当前未提交更改贮藏起来（可填说明），下方的贮藏列表支持应用 / 弹出 / 丢弃；弹出或应用遇到冲突时保留贮藏条目并提示，不会半途丢失。丢弃走二次确认。
-- **共享工作区护栏**：标签 / 贮藏 / 还原 / 重置等写操作与 dsh 的 AI 共用同一仓库，弹窗底部统一提示「可直接让 AI 执行 Git 操作」；撞上 `.git/index.lock`（另一进程正在操作）会自动重试一次并给出「Git 正忙」提示而非原始报错。
-- **文件浏览**：直接打开工作区「Git」标签时，非 Git 目录默认进入文件浏览；Git 仓库中无未提交变更则进入「Git 总览」，有未提交变更则进入「变更记录」。非 Git 目录也能浏览，以当前工作目录为根。左栏目录树按需加载（点开才读取下一层，不显示 `.git`），按文件类型显示 dsh 官方图标，被 `.gitignore` 忽略的条目半透明呈现，宽度可拖动；右栏可预览代码、文本和图片，顶部可复制文件相对路径，过大文件或其他二进制文件显示提示。Markdown 默认显示源码，可点击「渲染」切换到 dsh 自带的 Markdown 视图；HTML 默认显示源码，可点击「渲染」在隔离沙箱（`allow-scripts`、无同源权限）中预览页面，不会自动执行。大文件的源码视图按行虚拟化（只渲染视口内的行），超大文件关闭语法高亮、超长行截断，保证流畅。
-- **图片缩放**：文件浏览与差异对照的图片共用同一缩放组件——Mac 触控板双指捏合（Chromium/Firefox/Safari 15+ 以 Ctrl+滚轮事件送达、旧 Safari 走 gesture 事件）与 <kbd>Ctrl</kbd>+滚轮都以光标为锚点缩放（10%–800%），放大后可用双指滚动、滚轮、滚动条或**鼠标左键拖拽**平移（抓手光标；拖拽不会被当成双击，另拖原生滚动条不受影响），浮动工具栏提供 − / 百分比 / + / 适应窗口 / 全屏（全屏入口只在工具栏，图片单击不触发，否则每次双击都会被第一次单击打断），双击在适应窗口与 100% 间切换，灯箱内可继续缩放拖拽，<kbd>Esc</kbd>、点关闭钮或点灯箱空白区域退出。
-- **代码内查找**：文件浏览的源码视图与差异对照都支持 <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>F</kbd> 就地查找——高亮全部命中并保留语法着色，显示「当前 / 总数」，<kbd>Enter</kbd> / <kbd>Shift</kbd>+<kbd>Enter</kbd> 或 `‹` `›` 在命中间跳转，可切换区分大小写（默认不敏感），<kbd>Esc</kbd> 关闭。命中统计覆盖整份内容，视口外的命中同样计入并可跳转。
-- **语法高亮差异**：总览弹窗、变更记录和文件浏览共用 dsh 官方语法高亮，按文件扩展名选择语言，语法资源按需加载；差异视图的改动词级强调保留原有交互。
-- **对照模式**：差异支持「统一 / 对照 / 变更前 / 变更后」四种视图切换。统一视图为单栏行内对比（改动行前后紧邻，省横向空间），对照视图为左右并排；两种视图都带块间隐藏上下文的按需展开与改动行的词级高亮。默认视图可在插件详情页选择（统一 / 并排），也可在每个差异视图工具栏临时切换。
-- **移动端 / 窄面板自适应**：面板宽度收窄到 620px 及以下（手机竖屏，或右侧栏挤压面板）时自动切换为单栏「钻取」布局——三栏折叠为一栏，列表与详情 / 差异 / 预览之间点击进入、带「返回」按钮退出；Git 总览的分支筛选改为从底部升起的面板（bottom sheet），提交行改为两行式更易点按，顶栏控件换行到第二行而非隐藏，差异对比在窄屏隐藏「对照」（并排）模式。面板变宽后自动恢复三栏布局，桌面体验不变。触控设备（如平板）上逐文件操作按钮常驻显示、点按区域放大。
-- **显示输入框标记开关**：插件详情页可切换输入框标记；关闭后输入框不再显示分支标记，改为在「Git」标签旁显示状态圆点（绿=已同步、橙色=有变更），两者互斥，保存后立即生效。同一处配置区还可设置差异对比的默认视图（统一 / 并排）、提交历史图的线条样式（平行线 VSCode 风格 / 紧凑 git log 风格，默认平行线）。「AI 生成提交信息」为独立配置卡片：开关按钮之外，可设置生成语言（自动 / 中文 / English，默认自动——跟随你在此仓库的提交语言）并调整输入预算 / 输出上限 / 生成超时三项（范围 16–512 KiB / 256–16384 tokens / 5–120 秒，超出范围的值会被夹到边界）。
-- **输入框 Git 标记**：一个 zsh 主题风格的 `<仓库名> (<分支>)` 标记，仓库名青色，`(分支)` 在已同步时为绿色、有未提交变更时为橙色；悬停显示完整仓库路径，点击跳转面板（有未提交变更进入变更记录，否则进入 Git 总览）；非 Git 目录不显示输入框标记，可通过工作区的「Git」标签进入文件浏览。
+- **Git 总览**：三栏——分支 / 标签列表、可搜索（提交信息、commit 哈希、作者、日期）的提交历史图、选中提交的变更文件树与提交信息；点文件在 modal 里查看该文件在此提交中的差异。
+- **变更记录**：逐文件暂存 / 取消暂存 / 丢弃与批量放弃选中改动（二次确认）、手动提交与 **Amend**、贮藏（创建 / 应用 / 弹出 / 丢弃），以及文件数与增删行统计。
+- **常用 Git 操作**：分支切换（远程引用落为同名跟踪分支，不留游离 HEAD；有未提交改动可先贮藏再切换）、标签创建与删除、提交还原 / 重置（硬重置会列出将丢弃的改动并要求额外勾选）。都只改写本地仓库，不自动推送。
+- **AI 生成提交信息**：按当前未提交变更与仓库既有提交风格生成提交信息，语言默认跟随仓库历史自动推断（也可固定中文 / English）；模型可在详情页从 DSH 模型列表中固定选择（提供方 → 模型 → 推理强度三级级联，**默认跟随当前会话**），并可关闭生成或调整输入预算、输出上限与超时。**生成会把 diff 内容发送给你所选模型的供应商。**
+- **输入框 Git 标记**：zsh 风格的 `<仓库名> (<分支>)`，已同步为绿色、有未提交变更为橙色；悬停显示仓库路径，点击跳转面板。可在插件详情页关闭，改为在「Git」标签旁显示状态圆点。
+- **文件浏览**：面板内直接浏览工作区目录树（按需加载、`.gitignore` 项半透明、不显示 `.git`）并预览代码 / Markdown / HTML / 图片（Markdown 渲染视图内嵌的本地图片可直接显示，如 README 配图；```mermaid 代码块渲染为图表，解析失败回退为代码块）；源码预览默认自动换行，可切换为横向滚动查看长行；非 Git 目录也能用，以当前工作目录为根。
+- **差异与源码查看**：统一 / 对照 / 变更前 / 变更后四种视图，语法高亮、词级改动强调、块间隐藏上下文按需展开，<kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>F</kbd> 就地查找；图片以光标为锚点缩放（10%–800%）、可拖拽平移与全屏。
+- **窄面板 / 移动端**：宽度 ≤620px 时自动切为单栏「钻取」布局（分支筛选改为底部弹层、提交行改两行式），变宽后自动恢复三栏。
+- **共享工作区护栏**：与 dsh 的 AI 共用同一仓库，写操作弹窗统一提示「可直接让 AI 执行 Git 操作」；撞上 `.git/index.lock` 会自动重试一次并提示「Git 正忙」。
 - UI 跟随 DSH 系统语言设置，支持简体中文和英文。
 
+## 权限与数据边界
+
+面板以 DSH 进程的权限运行，安装前值得知道这些边界：
+
+- **Git 命令**：所有 git 命令都经宿主的 `subprocess` 服务执行——argv 数组、不拼接 shell 字符串、工作目录锁定在仓库根，每条命令带超时与输出上限；不使用 `--force`，也不改动 git 配置。
+- **文件访问**：只读工作区内的文件（差异、文件浏览、AI 生成的输入），路径经校验并做 realpath 包含检查——软链指向仓库外一律拒绝，`.git` 不可浏览。**唯一的写盘动作**是「放弃未跟踪条目」：按你的确认直接删除工作区文件，条目本身是 Git 仓库时整批拒绝。
+- **网络**：插件自身只发起一个请求——`GET https://api.github.com/repos/<owner>/<repo>/releases/latest`，用于版本条上的「有新版本」提示（5 秒超时，结果带进程内缓存）。`fetch` / `pull` / `push` / `publish` 只在你点击后经 git 命令联网，凭据始终由 git 处理；插件不读取、不存储、不返回任何令牌或凭据。
+- **外部服务**：只有「AI 生成提交信息」会把 diff 内容发送给你在 DSH 中配置的模型供应商；模型调用由宿主完成，插件不持有凭据。
+- **系统依赖**：需要 `git` CLI；未安装 git 或目录不是 Git 仓库时只显示文件浏览，以当前工作目录为根。
+
+客户端 bundle（`lib/client.js`）不发起网络请求，只与宿主走同源 RPC；插件不采集遥测。面板字号、分栏宽度这类界面偏好只存在浏览器 localStorage，不含仓库内容。除 git 命令与被确认的删除外，插件代码不在工作区之外读写文件；详情页的配置项由宿主写进 profile 配置。
+
 ## 界面
 
 | Git 总览 | 文件差异 modal |
@@ -49,6 +56,8 @@ dsh plugin --profile web add github:xbzbing/dsh-git-panel
 | ![Git 总览：分支、提交历史图、提交详情与 hover 卡片](docs/assets/screenshots/1-git-panel-overview.png) | ![文件差异 modal：语法高亮的统一 / 并排对照、块间按需展开与词级高亮](docs/assets/screenshots/2-overview-tab.png) |
 | 变更记录 | 文件浏览 |
 | ![变更记录：统计条、未提交变更列表、提交框与差异对照](docs/assets/screenshots/3-changes.png) | ![文件浏览：懒加载目录树、官方类型图标、忽略项半透明与文件预览](docs/assets/screenshots/4-files.png) |
+| 窄面板 / 移动端 | 插件配置 |
+| ![窄面板 / 移动端：≤620px 单栏钻取布局，统计条、变更列表与提交框纵向排列](docs/assets/screenshots/5-mobile-panel.png) | ![插件配置：输入框标记开关、差异默认视图、提交图样式与 AI 生成设置](docs/assets/screenshots/6-plugin-config.png) |
 
 ## 架构
 
@@ -67,7 +76,7 @@ npm run test:e2e    # 隔离的 file:// 无头浏览器 e2e（不碰任何运行
 npm test            # 单测 + e2e
 ```
 
-host 产物按 `src/host/` 逐模块输出（一个源文件一个 js，堆栈直接落在出问题的模块），且不做压缩：typert 网关靠方法参数名做参数校验，压缩会改名并破坏 wire 契约。client 改动没有热重载，需重新构建并刷新页面。`lib/` 作为构建产物随 git 提交入库，改动 `src/` 后必须重新构建并提交，否则从 GitHub 安装会加载到过期入口；测试期生成的 `lib/testkit.mjs` 不入库。本地联调：把插件加入 dsh web profile 的 `dsh.profile.bundles`，用 `file:` 依赖指向本目录，构建后即生效。
+host 产物按 `src/host/` 逐模块输出（一个源文件一个 js，堆栈直接落在出问题的模块），且不做压缩：typert 网关靠方法参数名做参数校验，压缩会改名并破坏 wire 契约。client 改动有热重载：重新构建 `lib/client.js` 后，运行中的 dsh 秒级检测到文件变化并推给浏览器原地热替换，无需刷新页面；host 半改动仍需重启（已加载的旧代码跑到重启为止）。`lib/` 是本地构建产物、不入库；本地联调：把插件加入 dsh web profile 的 `dsh.profile.bundles`，用 `file:` 依赖指向本目录，`node build.mjs` 后即生效。
 
 ## 项目结构
 
@@ -98,6 +107,10 @@ src/
     diff.ts         unified diff → 并排行 + 统一行 + 统计
 ```
 
+## 致谢
+
+感谢 [@ivanant](https://github.com/ivanant) 为项目提出的各种优化建议和迭代需求。移动端布局、变更记录的批量选择、AI 生成提交信息、提交图与图标的细节打磨、没有远程分支时的推送（publish）等改进，大多来自他持续反馈的真实使用场景；这些反馈把面板从「能用」推到了现在的形态。
+
 ## 许可证
 
 本项目采用 [MIT License](LICENSE)。