@xia-sc/dsh-git 0.5.1

package/README.en.md

@@ -0,0 +1,284 @@
+# @xia-sc/dsh-git
+
+[中文](./README.md) | English
+
+Complete Git management for the DeepSeek Harness Web GUI, presented as a
+**collapsible floating block** that **follows the current session's workspace
+in real time** — click a different session/workspace in the sidebar and the
+panel rebinds to that repository instantly.
+
+**Workflow supported:** branch switch · fetch · pull (fast-forward only) ·
+stage all · commit (with an AI-drafted message) · push · status · recent
+commits · uncommitted-file list · **click a change to see its diff** ·
+new-branch-from-base.
+
+## UI
+
+- **Floating block** (`shell.overlay`): collapsed = renders nothing (no
+  floating element that could cover the input); expanded = the full Git
+  workbench (status line, branch switcher with **dirty-tree pre-check** —
+  selecting a branch while uncommitted changes exist shows a warning listing
+  the affected files instead of switching, with a "switch anyway" escape
+  hatch, fetch/pull actions, a **commit area** — stage-all button, draft-basis
+  picker, "✨ AI draft" button, message input and commit button — collapsible
+  changes and recent-commit lists, last-operation output). The panel is
+  **draggable by its header bar**
+  (the top row with the Git title — press, drag, release; it stays where
+  dropped and is clamped inside the viewport; header buttons/inputs never
+  start a drag; double-click the header to snap back to center).
+  A "＋ New branch" button beside the branch switcher opens an inline form:
+  new branch name + base-branch picker (local branches or full remote refs
+  like `origin/feature/x`) — confirming creates the branch from the base and
+  switches to it.
+- **Click a change to see its diff**: clicking any row of the change list grows
+  the panel from its 400px single column into two panes — the full workbench on
+  the left, that file's unified diff on the right (see *The diff viewer* below).
+  Clicking the same row again, or the diff header's `×`, folds it back.
+- **Composer dock pill** (`conversation.input.dock`): a compact, left-aligned
+  status pill at the textarea's top-left (branch summary or "not a git
+  repository"); clicking it toggles the floating panel.
+- Both seats share one store, so they always agree, and both re-bind when the
+  current session (and its cwd) changes. Rebinding clears the selected file —
+  the panel never shows another repository's content.
+
+### The diff viewer
+
+Clicking a row of the change list shows that file's git diff on the right. The
+list is the viewer's navigation: the highlighted row is the file on screen, and
+the first selection expands the list to its full length.
+
+- **Resizable**: the handle is the panel's own right edge — dragging it widens the
+  panel (the workbench keeps its width) and the diff takes the rest, 1:1 with the
+  pointer because the panel anchors its left edge on grab. Double-clicking the
+  edge resets the width, and the panel always stays inside the viewport.
+- **Staged / unstaged**: by default the pane follows the data — unstaged when
+  that side has anything, staged otherwise — with two chips to switch by hand
+  (an empty side is dimmed). When a file has changes on both sides, one click
+  shows the side you care about and the other is one chip away.
+- **Self-refreshing**: staging, committing, switching branches, or refreshing
+  re-reads the open diff; when the unstaged side empties, the pane falls back to
+  the staged side on its own.
+- **Line numbers and colour**: per-side gutters taken from each hunk header,
+  `+`/`-` rows in the theme's success/error colours, hunk headers on their own
+  row, `` dimmed.
+- **Every edge has its own notice**: nothing on this side / a binary file has no
+  text diff / the diff was too large and only its beginning is shown / N more
+  untracked files were not expanded / the read failed. A diff past 1500 rows
+  renders its first 1500 with a button to expand the rest (so a huge patch never
+  becomes tens of thousands of nodes).
+- **Untracked files** are diffed against the empty blob and read as a
+  `new file mode` addition; an untracked **directory** is expanded file by file
+  (capped at 50, the rest counted in that notice).
+- **Renames** hand git both the old and the new path as the pathspec: naming only
+  the new one leaves git unable to pair them and turns a rename into a whole-file
+  addition.
+
+### The commit area and AI drafting
+
+The commit area follows the real order of operations: **stage all → draft → commit**.
+
+- **Stage all**: `git add --all` (deletions and untracked files included).
+  Disabled while the tree is clean. This is the answer to "only unstaged
+  changes exist, so Commit fails" — committing itself still never stages
+  implicitly.
+- **Draft basis**: one of `Staged` (default), `Unstaged`, `Everything` — which
+  part of the change set is handed to the model. `Staged` is the default
+  because **it is the only basis whose content the commit actually records**;
+  a message drafted from anything else may describe changes that will not be
+  committed.
+- **✨ AI draft**: sends the selected change set (diffstat + diff, truncated)
+  to the model the current session has selected and drops the generated
+  message into the input. Edit it, or just write your own.
+
+The model route comes from the current session's `modelSelection` projection
+(pending pick first, then last used), falling back to the host's first
+registered route. Failures are reported in the last-operation output with a
+localized sentence (no changes / no model configured / draft failed, …).
+
+## Architecture
+
+One dual-face npm package:
+
+| Half | File | Role |
+| --- | --- | --- |
+| Host | `lib/index.js` | Cordis plugin (bundle row `dsh-git`) registering the `/dsh-git-rpc` prefix route on its own `ctx.webServer`, speaking the same Connection RPC envelope the browser's `connection.rpc.call` sends and reusing the connection service's Host/Origin + browser-session fence (`connection.requestRejection`). Endpoints: `status`, `branches`, `checkout`, `createBranch`, `fetch`, `pull`, `stage`, `diff`, `commit`, `push`, `log`, `generateMessage`. All git runs via `execFile` (no shell), timeouts (30s local / 120s network), strict input validation. AI drafting goes through the injected `llm` service. |
+| Browser | `lib/client.js` | `dsh.client` bundle (served at `/plugins/@xia-sc/dsh-git/client.js`): floating panel + dock line + shared store, hand-written against the module table (only `react`). |
+
+### Why the route is self-owned (dsh >= 0.1.5-rc.1)
+
+Since dsh 0.1.5-rc.1 an outside plugin can no longer call
+`ctx.connection.rpc.handle()`: `HostConnectionService.rpc` closes over the
+connection plugin's **own** Context (`inject` is only `["credentials"]`) and
+registers through it (`owner.effect(() => owner.webServer.register(route))`),
+while that plugin only resolves `webServer` inside an inner
+`ctx.inject(["webServer"], …)` scope. Whatever the caller injects, the row
+therefore failed to mount with `cannot get property "webServer" without inject`
+— which is exactly what 0.3.0 did. This build registers `/dsh-git-rpc` itself
+and implements the same RPC envelope; the request fence still comes from the
+connection service's `requestRejection`, so the channel is exactly as trusted
+as `/api`. `test/host-mount.mjs` guards this against a real Cordis host and the
+real Connection service.
+
+### The session binding belongs to the session-scoped seat (dsh >= 0.1.6-alpha.2)
+
+Both faces used to read `current` (the current session id) out of the sessions
+list snapshot. 0.1.6-alpha.2 dropped that field — the snapshot is now `ids` /
+`byId` / `phase` / `subagentsByParent` / `jobsBySession`, and the current
+session reaches **session-scoped** seats through the renderer's scope adapter
+(`SlotScopeAdapter.current`, derived from `retainedBy.mainView`), which a
+root-scoped `shell.overlay` entry cannot read (the symptom is the pill and the
+panel silently disappearing, with no error anywhere).
+
+Now the **pill** (`conversation.input.dock`, session-scoped: the framework hands
+it `sessionId`) reads that session's `cwd` from the `useSessions` snapshot and
+calls `store.bindSession(sessionId, cwd)`; the **panel** only reads the shared
+store's `sessionId` / `cwd` (it also uses the identity to resolve the
+`modelSelection` projection behind the AI draft route). `byId[id].retainedBy.mainView`
+keeps an embedded Conversation (a subagent chat tab) from taking the workbench
+over; a snapshot without that count is treated as main-view so the pill never
+vanishes for want of it.
+
+## Install
+
+```sh
+dsh plugin --profile web add @xia-sc/dsh-git
+```
+
+Or install straight from the source (both channels are the same code: the npm
+version is the artifact of the matching tag):
+
+```sh
+dsh plugin --profile web add https://github.com/xia-sc/dsh-git
+```
+
+Then **restart `dsh web`** (bundle rows and the browser roster compose at
+boot). After refresh, the dock pill appears above the composer once the current
+session's workspace is a git repository; click it to open the panel.
+
+Requires **dsh >= 0.1.5-rc.1** (the host half owns its `/dsh-git-rpc` route; see
+the architecture note above).
+
+Uninstall:
+
+```sh
+dsh plugin --profile web remove @xia-sc/dsh-git
+```
+
+## RPC contract (`/dsh-git-rpc`)
+
+The browser calls `ctx.connection.rpc.call("/dsh-git-rpc", endpoint, { args })`;
+the host side is this plugin's own `/dsh-git-rpc/*` prefix route, speaking the
+same Connection envelope as `/api`:
+
+- Request: `POST /dsh-git-rpc/<endpoint>`, `content-type: application/json`,
+  `{ type: "client-request", rpcId, method: <endpoint>, payload: { args } }`
+- Response: `{ type: "server-response", rpcId, result: { ok: true, value } | { ok: false, error } }`
+- Fence: `connection.requestRejection` (Host/Origin + browser session cookie);
+  non-`POST` → 405, non-JSON → 415, oversized body → 413, path outside the
+  channel → 404.
+
+Payloads use the `{ args }` convention. `cwd` must be an absolute path;
+`branch` matches `^[A-Za-z0-9][A-Za-z0-9._/-]*$` (no leading `-`, no `..`,
+`@{`, `\`, whitespace, control chars); `remote` is a plain segment. The commit
+message is a real message: one subject line plus an optional multi-line body.
+CRLF becomes LF, trailing whitespace is stripped per line, leading/trailing
+blank lines are dropped and runs of blank lines collapse to one (so the single
+blank line between subject and body is preserved); empty, over-long (>10000
+characters), and control-character-carrying messages are rejected with
+`invalid-message`. The message reaches git on stdin via
+`git commit --cleanup=whitespace --file=-`, so spaces, quotes, line feeds,
+shell metacharacters, and leading dashes are all recorded verbatim.
+
+| Endpoint | args | Result (`value`) |
+| --- | --- | --- |
+| `status` | `{ cwd }` | `{ repo, branch, detached, oid, upstream, ahead, behind, dirty, changes: [{status, path, index, worktree, file, origFile}] }`. `path` is the display string (a rename reads `old → new`), `file`/`origFile` are the pathspec `diff` needs, and `index`/`worktree` are the two porcelain-v2 letters. |
+| `branches` | `{ cwd }` | `{ repo, current, local: [{name, current, upstream, sha}], remote: [{name, short}] }` |
+| `checkout` | `{ cwd, branch }` | `{ branch, detached, oid, message? }` via `git switch --guess`; the browser pre-checks dirty state and warns before switching; a refusal caused by "local changes would be overwritten" is surfaced with a readable prefix. |
+| `createBranch` | `{ cwd, branch, base? }` | `{ branch, detached, oid, message? }` via `git switch --create <branch> <base>` (omitted base = HEAD); creates the branch from the base branch and switches to it. |
+| `fetch` | `{ cwd, remote? }` | `{ message }` (120s timeout) |
+| `pull` | `{ cwd }` | `{ message }` via `git pull --ff-only` (never implicit-merge) |
+| `stage` | `{ cwd }` | `{ message }` via `git add --all` |
+| `diff` | `{ cwd, path, origPath? }` | `{ repo, path, origPath, untracked, skipped, worktree: {diff, binary, truncated}, index: {…} }`. Both sides are read in one round trip (`git diff [--cached] --no-ext-diff --no-color -- <path> [<origPath>]`); `path` must be repository-relative (absolute paths, `..`, a leading `-`, control characters, and surrounding whitespace are rejected with `invalid-path`). An untracked path is diffed with `git diff --no-index -- /dev/null <path>` (exit code 1 tolerated); an untracked directory is expanded with `git ls-files --others --exclude-standard` (capped at 50, the rest counted in `skipped`). A side past 400k characters is truncated at a line boundary and flagged `truncated`; a binary side is flagged `binary`. **Read-only**: it never writes the index, the working tree, or any config. |
+| `commit` | `{ cwd, message }` | `{ message }`; `missing-author` error when `user.name/email` unset |
+| `push` | `{ cwd }` | `{ message }` (120s timeout) |
+| `log` | `{ cwd, count? }` | `{ repo, commits: [{sha, author, subject, refs}] }` (clamped 1..50) |
+| `generateMessage` | `{ cwd, mode?, provider?, model? }` | `{ message, mode, provider, model }`. `mode` is `staged` (default) / `unstaged` / `all`; anything else is `invalid-mode`. Failure code in `error.details.code`: `no-changes`, `no-provider`, `no-model`, `llm-empty`, `cancelled`, `llm-failed`. |
+
+> A failed result carries `error.code === "internal"` on the wire (the Connection
+> envelope only requires a string), with the plugin's own diagnostic in
+> `error.details.code`; the client localizes from that code.
+
+## Design decisions & boundaries
+
+- **pull is `--ff-only`**: no surprise merge commits; conflicts surface as an
+  error the user resolves in their own tooling.
+- **commit does not stage**: it commits what is staged. To commit everything at
+  once, use the commit area's **Stage all** button (`git add --all`) rather than
+  making commit stage implicitly.
+- **AI drafting sends the change set's diff to whichever model provider you
+  configured** — possibly a third-party gateway. It only happens when you click
+  "✨ AI draft"; the plugin itself never calls the network. The diff is
+  truncated to 12000 characters, and nothing outside the repository is sent.
+- **push/pull credentials** come from the system (Git Credential Manager /
+  SSH agent); the plugin never touches credential storage. AI drafting never
+  touches credentials either — the model adapter resolves its own API key.
+- **The plugin never mutates git config**; missing author reports a clear
+  error instead.
+- **The diff viewer is strictly read-only**: its endpoint runs only `git diff` /
+  `git ls-files` — it never writes the index, the working tree, or any config —
+  and it deliberately does **not** depend on the host's right-Sidebar tab API
+  (that surface is still moving fast). The two panes live inside the panel
+  instead, and the diff renderer is written here as well (this bundle depends on
+  `react` only): unified-diff parsing, both line-number gutters, `+`/`-`
+  colours, and no syntax-highlighting dependency.
+- **A rename needs both names in the pathspec**: git only pairs them when the old
+  path is named too; naming the new path alone reports a whole-file addition
+  (`test/diff.mjs` guards this).
+- **porcelain-v2 status parsing**: a `2` (rename/copy) record carries its path in
+  the 10th field with the old name TAB-separated after it, and a `u` (conflict)
+  record carries its path in the 11th field and is always a conflict. Both were
+  read from `slice(8)` / `slice(9)` before — off by the score and hash columns —
+  and are now built by `changeEntry()`.
+- **The plugin imports no `@deepseek-ai/*` runtime package** (only `node:`
+  builtins and `@deepseek-ai/cordis`). Under a pnpm `link:` install the host
+  packages do not resolve from the plugin's real source path, so such an import
+  would make the plugin fail at load time; the request construction and stream
+  assembly generation needs are therefore implemented locally and tested
+  directly by `test/generate.mjs`.
+- Panel operations are plain UI actions (like the Cordis panel) and are not
+  written to the session log / model prompt. AI drafting only fills the input;
+  it never commits by itself.
+
+## Development notes
+
+- The browser bundle is hand-written (no build step); edits to `lib/client.js`
+  are picked up on refresh (no-cache), host-side edits need a `dsh web`
+  restart.
+- Tests (`npm test` runs all four):
+  - `node test/smoke.mjs` — route, envelope, endpoint dispatch and input
+    validation (no git spawn: the session sandbox blocks child-process piped
+    stdio);
+  - `node test/host-mount.mjs` — mounts the row on a real Cordis host with the
+    real `dsh-client-connection` (resolved from the `DSH_HOME` profile; SKIPs
+    when no profile is installed);
+  - `node test/generate.mjs` — the AI-draft units: route resolution, prompt
+    assembly, truncation, stream assembly (both the `block-end` and the
+    delta-only path), terminal failure / abort / empty output;
+  - `node test/render.mjs` — real React SSR render of both seats, including the
+    three commit-area controls, the diff parser (line numbers, row kinds, a
+    removed line starting with `--`), the row renderer, the diff pane's header,
+    and `act()`'s result plumbing and localization (needs a react/react-dom copy,
+    e.g. via `DSH_GIT_REACT_ROOT`; SKIPs without one).
+- `npm run test:commit` — **end-to-end**: really spawns git in a throwaway
+  repository, commits through the plugin's own `/dsh-git-rpc/commit` route, and
+  reads the message back with `git log --format=%B` (multi-line, CRLF, non-ASCII,
+  leading `-`, shell metacharacters…), then confirms a rejected message creates
+  no commit.
+- `npm run test:diff` — **end-to-end**: drives `/dsh-git-rpc/diff` in a throwaway
+  repository through every shape the change list can produce — both sides of the
+  index, an untracked file and an untracked **directory**, **rename pairing**, a
+  deletion, a binary blob, the 400k truncation, path validation, and a directory
+  outside any work tree.
+- The last two need piped child-process stdio, so they are deliberately **not**
+  part of `npm test` — run them from an ordinary terminal.
+- The git command set is verified end-to-end against the running server.

package/README.md

@@ -0,0 +1,225 @@
+# @xia-sc/dsh-git
+
+[English](./README.en.md) | 中文
+
+DeepSeek Harness Web GUI 的完整 Git 管理插件，形态为一个**可折叠的悬浮面板**，
+**实时跟随当前会话的工作区**——在侧边栏点击不同的会话/工作区，面板会瞬间
+重新绑定到对应仓库。
+
+**支持的工作流：** 分支切换 · 拉取更新(fetch) · 拉取合并(pull，仅快进) ·
+暂存全部 · 提交(commit，可用 AI 起草提交信息) · 推送(push) · 状态(status) ·
+最近提交 · 未提交文件列表 · **点击变更看差异** · 基于某分支新建分支。
+
+## 界面
+
+- **悬浮面板**（`shell.overlay`）：折叠时不渲染任何元素（不会遮挡输入框）；
+  展开后是完整的 Git 工作台（状态行、带 **脏树预检** 的分支切换器——在有
+  未提交修改时选择分支，会先显示受影响文件列表警告而不是直接切换，并提供
+  "仍要切换"按钮；fetch/pull 操作；**提交区**——"暂存全部"按钮、AI 生成依据
+  选择器、"✨ AI 生成"按钮、提交信息输入框（多行文本框，回车换行、
+  Ctrl/Cmd+Enter 提交）与提交按钮；可折叠的变更列表与
+  最近提交列表；上次操作输出）。面板**可通过顶栏拖动**（按住带 Git 标题的
+  那一行，拖到哪里就停在哪里，不会拖出视口；顶栏上的按钮/输入框不会触发
+  拖动；双击顶栏回到居中位置）。
+  分支切换器旁边的"＋ 新建分支"按钮会展开一个内联表单：新分支名 + 基分支
+  选择器（本地分支或 `origin/feature/x` 这样的完整远端引用）——确认后从
+  该基分支创建新分支并切换过去。
+- **点击变更看差异**：点变更列表里的任意一行，面板会从 400px 的单栏展开成
+  两栏——左边照旧是完整工作台，右边是该文件的 unified diff（见下文
+  「差异查看」）。再点同一行、或点差异标题栏的 `×`，就收回单栏。
+- **输入框胶囊**（`conversation.input.dock`）：输入框左上角的紧凑型左对齐
+  状态胶囊（分支摘要，或"当前工作区不是 Git 仓库"）；点击它展开/收起悬浮面板。
+- 两处界面共享同一个 store，状态永远一致，并都会随当前会话（及其 cwd）
+  切换而重新绑定。切换工作区会清空已选中的文件——绝不让面板显示别的仓库的内容。
+
+### 差异查看
+
+点变更列表里的一行，就在右侧显示该文件的 git diff。左侧列表是它的导航：
+行高亮表示"正在看这一个"，首次点击会自动把变更列表展开成完整列表。
+
+- **可拖拽调宽**：拖动**面板最右侧那条边**即改差异栏宽度——左栏（工作台）宽度不变，
+  面板整体变宽、差异栏跟着长；双击这条边复位。面板始终留在视口内，窗口变窄时
+  会自动收回；拖动时面板会就地锚定左边缘，所以指针与这条边是 1:1 跟手的。
+- **未暂存 / 已暂存**：默认自动跟随数据——未暂存有内容就显示未暂存，否则显示
+  已暂存；顶部两个 chip 可手动切换，空的一侧置灰。同一个文件两边都有改动时，
+  一次点击看到的是最关心的那一侧，另一侧一键可达。
+- **自动刷新**：暂存、提交、切分支、刷新之后，打开的差异会自己重读——未暂存
+  变空时会自动落到已暂存。
+- **行号与配色**：左右两列行号（旧/新）取自每个 hunk 头，`+`/`-` 行走主题的
+  成功/错误色，hunk 头单独一行，`` 灰显。
+- **边界都有明确提示**：这一侧没有改动 / 二进制文件没有文本差异 / 差异过大只
+  显示开头一段 / 未跟踪目录里还有 N 个文件未展开 / 读取失败。超过 1500 行的
+  差异先渲染前 1500 行，按钮可展开全部（避免一次渲染几万个节点）。
+- **未跟踪文件**：与空文件对比，显示成 `new file mode` 的新增 diff；未跟踪
+  **目录**会把里面的文件逐个展开（上限 50 个，其余计入提示）。
+- **重命名**：同时把旧名与新名作为 pathspec 交给 git，否则 git 无法配对，会把
+  一次重命名报成整文件新增。
+
+### 提交区与 AI 起草
+
+提交区按真实操作顺序排列：**暂存全部 → AI 生成 → 提交**。
+
+- **暂存全部**：`git add --all`（含删除与未跟踪文件）。工作区干净时置灰。
+  这是"只有未暂存改动、点提交却报错"的正解——提交本身依然**不会**隐式暂存。
+- **AI 生成依据**：三选一，决定把哪一部分改动交给模型：
+  `已暂存`（默认）、`未暂存`、`全部`。默认 `已暂存`，因为**只有它是本次
+  提交真正会记录的内容**——用其他依据生成的描述可能与实际提交不符。
+- **✨ AI 生成**：把选中的改动（diffstat + diff，截断后）交给当前会话所选
+  模型，生成的提交信息直接填入输入框；不满意可改，也可以直接手写。
+
+生成用的模型路由取当前会话的 `modelSelection` 投影（待生效的选择优先，
+其次是上次实际使用），取不到时回落到宿主注册的第一条路由。失败会以
+本地化文案显示在"上次操作输出"里（无可用改动 / 未配置模型 / 生成失败等）。
+
+## 架构
+
+一个双面 npm 包：
+
+| 半边 | 文件 | 职责 |
+| --- | --- | --- |
+| 宿主 | `lib/index.js` | Cordis 插件（bundle 行 `dsh-git`），在自己的 `ctx.webServer` 上注册 `/dsh-git-rpc` 前缀路由，收发浏览器 `connection.rpc.call` 的同一套 Connection RPC 信封，并复用 connection 服务的 Host/Origin + 浏览器会话围栏（`connection.requestRejection`）。端点：`status`、`branches`、`checkout`、`createBranch`、`fetch`、`pull`、`stage`、`diff`、`commit`、`push`、`log`、`generateMessage`。所有 git 调用都走 `execFile`（无 shell）、带超时（本地 30s / 网络 120s）、严格入参校验。AI 生成走注入的 `llm` 服务。 |
+| 浏览器 | `lib/client.js` | `dsh.client` bundle（服务于 `/plugins/@xia-sc/dsh-git/client.js`）：悬浮面板 + dock 行 + 共享 store，对照模块表手写（仅依赖 `react`）。 |
+
+### 为什么自持 HTTP 路由（dsh ≥ 0.1.5-rc.1）
+
+dsh 0.1.5-rc.1 起，外部插件不能再调用 `ctx.connection.rpc.handle()`：
+`HostConnectionService.rpc` 闭包持有的是 **connection 插件自己的 Context**（`inject`
+只有 `["credentials"]`），注册时执行
+`owner.effect(() => owner.webServer.register(route))`，而该插件只在内部的
+`ctx.inject(["webServer"], …)` 作用域里取得到 `webServer`。于是无论调用方 inject 了
+什么，这一行都会以 `cannot get property "webServer" without inject` 挂载失败
+（0.3.0 正是如此，插件在 0.1.5-rc.1 上装不起来）。本插件因此改为自己注册
+`/dsh-git-rpc` 路由、自己实现同一套 RPC 信封；请求围栏仍交给 connection 服务的
+`requestRejection`，安全等级与 `/api` 完全一致。`test/host-mount.mjs` 在真实 Cordis +
+真实 Connection 服务上守护这一点。
+
+### 会话绑定由会话座位提供（dsh ≥ 0.1.6-alpha.2）
+
+两个界面此前都从 sessions 列表快照里读 `current`（当前会话 id）。0.1.6-alpha.2 把这个
+字段去掉了——列表快照只剩 `ids` / `byId` / `phase` / `subagentsByParent` /
+`jobsBySession`，当前会话改由渲染器的作用域适配器（`SlotScopeAdapter.current`，由
+`retainedBy.mainView` 推出）投递给**会话作用域**的座位，根作用域的 `shell.overlay`
+读不到它（症状是胶囊和面板一起静默消失，没有任何报错）。
+
+现在：**胶囊**（`conversation.input.dock`，会话作用域，框架直接给出 `sessionId`）
+从 `useSessions` 快照里取该会话的 `cwd`，调用 `store.bindSession(sessionId, cwd)`；
+**面板**只读共享 store 的 `sessionId` / `cwd`（它另外用 `sessionId` 取
+`modelSelection` 投影来定 AI 起草的路由）。`byId[id].retainedBy.mainView` 用来排除
+右栏里的嵌入式会话（子会话 chat），快照不带这个计数时按主视图放行。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @xia-sc/dsh-git
+```
+
+也可以直接从源码装（两个渠道同源，npm 上的版本就是对应 tag 的产物）：
+
+```sh
+dsh plugin --profile web add https://github.com/xia-sc/dsh-git
+```
+
+然后**重启 `dsh web`**（bundle 行与浏览器 roster 在启动时组合）。刷新后，
+当前会话工作区是 git 仓库时，输入框上方会出现 dock 胶囊，点击即可展开面板。
+
+要求 **dsh ≥ 0.1.5-rc.1**（宿主半自持 `/dsh-git-rpc` 路由，见上文架构说明）。
+
+卸载：
+
+```sh
+dsh plugin --profile web remove @xia-sc/dsh-git
+```
+
+## RPC 约定（`/dsh-git-rpc`）
+
+浏览器侧通过 `ctx.connection.rpc.call("/dsh-git-rpc", endpoint, { args })` 调用；宿主侧
+是本插件自持的 `/dsh-git-rpc/*` 前缀路由，收发与 `/api` 相同的 Connection 信封：
+
+- 请求：`POST /dsh-git-rpc/<endpoint>`，`content-type: application/json`，
+  `{ type: "client-request", rpcId, method: <endpoint>, payload: { args } }`
+- 响应：`{ type: "server-response", rpcId, result: { ok: true, value } | { ok: false, error } }`
+- 围栏：`connection.requestRejection`（Host/Origin + 浏览器会话 Cookie）；非 `POST` → 405，
+  非 JSON → 415，请求体超限 → 413，路径不属于本通道 → 404。
+
+载荷使用 `{ args }` 约定。`cwd` 必须是绝对路径；`branch` 匹配
+`^[A-Za-z0-9][A-Za-z0-9._/-]*$`（不允许前导 `-`、`..`、`@{`、`\`、空白、
+控制字符）；`remote` 为普通单段。提交信息是真正的提交信息：一行主题 +
+可选的多行正文。CRLF 会归一为 LF，逐行去掉行尾空白，去掉首尾空行并把连续
+空行折叠为一行（因此主题与正文之间那一行空行会保留）；空、超长（>10000
+字符）、含控制字符的信息报 `invalid-message`。信息经 stdin 以
+`git commit --cleanup=whitespace --file=-` 传入，因此空格、引号、换行、shell
+元字符、前导 `-` 都会被原样记录。
+
+| 端点 | 参数 | 结果（`value`） |
+| --- | --- | --- |
+| `status` | `{ cwd }` | `{ repo, branch, detached, oid, upstream, ahead, behind, dirty, changes: [{status, path, index, worktree, file, origFile}] }`。`path` 是展示串（重命名读作 `old → new`），`file`/`origFile` 是交给 `diff` 的 pathspec，`index`/`worktree` 是 porcelain-v2 的两个字母。 |
+| `branches` | `{ cwd }` | `{ repo, current, local: [{name, current, upstream, sha}], remote: [{name, short}] }` |
+| `checkout` | `{ cwd, branch }` | `{ branch, detached, oid, message? }`，经 `git switch --guess`；浏览器会预检脏树并提前警告；因"本地修改会被覆盖"被拒绝时会带上可读前缀。 |
+| `createBranch` | `{ cwd, branch, base? }` | `{ branch, detached, oid, message? }`，经 `git switch --create <branch> <base>`（缺省 base 即 HEAD）；从基分支创建新分支并切换过去。 |
+| `fetch` | `{ cwd, remote? }` | `{ message }`（120s 超时） |
+| `pull` | `{ cwd }` | `{ message }`，经 `git pull --ff-only`（绝不隐式合并） |
+| `stage` | `{ cwd }` | `{ message }`，经 `git add --all` |
+| `diff` | `{ cwd, path, origPath? }` | `{ repo, path, origPath, untracked, skipped, worktree: {diff, binary, truncated}, index: {…} }`。两侧一次读回（`git diff [--cached] --no-ext-diff --no-color -- <path> [<origPath>]`）；`path` 必须是仓库内相对路径（拒绝绝对路径、`..`、前导 `-`、控制字符、首尾空白），非法时报 `invalid-path`。未跟踪路径用 `git diff --no-index -- /dev/null <path>`（容忍退出码 1），未跟踪目录用 `git ls-files --others --exclude-standard` 展开（上限 50 个，其余计入 `skipped`）。单侧超过 40 万字符在行边界截断并置 `truncated`；二进制置 `binary`。**只读**，不碰 index / 工作区 / 配置。 |
+| `commit` | `{ cwd, message }` | `{ message }`；未配置 `user.name/email` 时报 `missing-author` 错误 |
+| `push` | `{ cwd }` | `{ message }`（120s 超时） |
+| `log` | `{ cwd, count? }` | `{ repo, commits: [{sha, author, subject, refs}] }`（钳制 1..50） |
+| `generateMessage` | `{ cwd, mode?, provider?, model? }` | `{ message, mode, provider, model }`。`mode` 为 `staged`（默认）/`unstaged`/`all`，非法值报 `invalid-mode`；失败码见 `error.details.code`：`no-changes`、`no-provider`、`no-model`、`llm-empty`、`cancelled`、`llm-failed`。 |
+
+> 失败结果的 `error.code` 在线路上固定为 `"internal"`（Connection 信封只要求它是字符串），
+> 插件自己的诊断码放在 `error.details.code`；客户端按该码做本地化文案。
+
+## 设计决策与边界
+
+- **pull 固定 `--ff-only`**：不产生意外的合并提交；冲突以错误形式呈现，
+  由用户在自己的工具里解决。
+- **commit 不暂存**：只提交已暂存的内容。想一次提交全部改动，用提交区的
+  "暂存全部"按钮（`git add --all`），而不是让提交隐式暂存。
+- **AI 生成会把改动的 diff 发给你配置的模型提供方**——可能是第三方网关。
+  这是显式点击"✨ AI 生成"才会发生的联网行为；插件本身不联网。diff 截断到
+  12000 字符后发送，且不发送任何仓库外的内容。
+- **push/pull 凭据**来自系统（Git Credential Manager / SSH agent）；插件
+  绝不碰凭据存储。AI 生成同样不接触凭据——API key 由模型适配器自己解析。
+- **插件绝不修改 git config**；缺 author 时给出明确错误而不是悄悄补写。
+- **差异查看是纯只读的**：`diff` 端点只跑 `git diff` / `git ls-files`，不写
+  index、不动工作区、不改配置；它**不依赖**宿主右侧 Sidebar 那套标签页 API
+  （那部分还在快速迭代），而是面板内自带两栏——左侧工作台照旧，右侧差异栏。
+  差异渲染也是自己写的（本 bundle 只依赖 `react`）：解析统一 diff、双行号、
+  `+`/`-` 配色，不引任何语法高亮依赖。
+- **重命名必须同时传旧名与新名**：git 只在旧名也在 pathspec 里时才配对，只给
+  新名会把一次重命名报成整文件新增（`test/diff.mjs` 守护这一点）。
+- **status 的 porcelain-v2 解析**：`2`（rename/copy）记录的路径在第 10 个字段、
+  与旧名以 TAB 分隔，`u`（冲突）记录的路径在第 11 个字段且状态恒为冲突——这
+  两处曾按 `slice(8)` / `slice(9)` 取值而错位，现在由 `changeEntry()` 统一构造。
+- **插件不导入任何 `@deepseek-ai/*` 运行时包**（只用 `node:` 内置模块和
+  `@deepseek-ai/cordis`）。以 pnpm `link:` 方式安装时，宿主包无法从插件的真实
+  源码路径解析，声明这类导入会让插件在加载期就崩溃；生成所需的请求构造与流
+  式拼装因此就近实现。`test/generate.mjs` 直接测这些单元。
+- 面板操作是普通 UI 行为（和 Cordis 面板一样），不会写入会话日志 /
+  模型提示词。AI 生成只填输入框，不会自动提交。
+
+## 开发说明
+
+- 浏览器 bundle 为手写（无构建步骤）；改 `lib/client.js` 刷新即生效
+  （no-cache），改宿主半需要重启 `dsh web`。
+- 测试：
+  - `node test/smoke.mjs` —— 路由/信封/端点分发/入参校验（不 spawn git：会话沙箱
+    拦截子进程管道 stdio）；
+  - `node test/host-mount.mjs` —— 在真实 Cordis + 真实 `dsh-client-connection`
+    上挂载插件行（从 `DSH_HOME` 的 profile 解析 DSH 包，找不到则 SKIP）；
+  - `node test/generate.mjs` —— AI 生成单元测试：路由解析、prompt 组装、截断、
+    流式拼装（block-end 与纯 delta 两条路径）、终止失败/取消/空输出；
+  - `node test/render.mjs` —— 双界面真实 React SSR 渲染，含提交区三个控件、
+    diff 解析器（行号 / 分类 / `--` 开头的删除行）、行渲染、差异面板标题栏与
+    `act()` 的结果回传/本地化（需要一份 react/react-dom，可用
+    `DSH_GIT_REACT_ROOT` 指定，找不到则 SKIP）。
+  - 也提供 `npm test`（依次跑四个）。
+  - `npm run test:commit` —— **端到端**：在临时仓库里真起 git，走插件的
+    `/dsh-git-rpc/commit` 路由提交，再用 `git log --format=%B` 逐字节比对提交
+    信息（多行、CRLF、中文、前导 `-`、shell 元字符等），并确认非法信息被拒且
+    不产生提交。
+  - `npm run test:diff` —— **端到端**：临时仓库里逐个验证 `diff` 端点：工作区
+    / 已暂存两侧、未跟踪文件与**未跟踪目录**、**重命名配对**、删除、二进制、
+    40 万字符截断、以及路径校验与非仓库目录。
+  - 后两个都必须 spawn git 的管道 stdio，故**不在 `npm test` 内**——请在没有
+    该限制的环境（普通终端）单独运行。
+  git 命令集对照运行中的服务端做端到端验证。

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# @xia-sc/dsh-git — browser-surface bundle layer.
+#
+# Applied after the dsh-web-app layer, so the `connection` service (the host
+# half of the web transport) is already available. The host half of this
+# package (lib/index.js) mounts the /dsh-git-rpc RPC channel that the browser
+# half (lib/client.js, a dsh.client row) calls for the full Git workflow:
+# status, branches, checkout, createBranch, fetch, pull, stage, commit, push,
+# log, and AI commit-message generation.
+#
+# No `inject` key here on purpose: the module's own exported `inject`
+# (webServer + connection + llm) is the declaration Cordis reads, and repeating
+# it in the row would only create a second place to keep in sync.
+- insert:
+    - id: dsh-git
+      name: '@xia-sc/dsh-git'