@xiaoming_z/dsh-git 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# dsh-git — DSH 会话视图里的 git 面板
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 DSH 的会话视图区（与「运行轨迹」并列）提供一个 Git 视图：审查自上次标记以来的改动，管理暂存与提交，浏览提交图和历史，切换、新建分支并拉取/推送，还能把改动文件或提交以 `@git` 引用的形式交给模型。
+
+## 安装
+
+已发布为 npm 包 `@xiaoming_z/dsh-git`。推荐用插件管理器安装：
+
+```js
+plugin_manager({ action: 'install_bundle', target: '@xiaoming_z/dsh-git' })
+```
+
+本地目录装（比如正在改这个插件），把 target 换成插件目录的绝对路径：
+
+```js
+plugin_manager({ action: 'install_bundle', target: '/绝对路径/dsh-git' })
+```
+
+也可以直接在界面里装：打开侧边栏的**「插件」页**，点**「添加插件」**（或箭头菜单里的**「安装第三方插件」**），输入包名 `@xiaoming_z/dsh-git` 或插件目录的绝对路径，点**「安装」**，装完点**「立即启用」**。（设置里的插件列表只读，不能在那里安装。）
+
+几点说明：
+
+- 装好通常立即生效，一般不用重启应用。如果视图没有出现，刷新页面或重启应用再试。
+- **桌面端不要用命令行安装**：`dsh plugin --profile desktop add …` 会被拒绝，因为桌面端 profile 由应用自己管理。请用上面的插件管理器或「插件」页。
+- 非桌面 profile 也可以用命令行：`dsh plugin --profile <profile> add <包名或 link:绝对路径>`，然后重启 `dsh web`。
+- 卸载、停用同样在侧边栏「插件」页完成。
+
+## 打开面板
+
+面板出现在会话的**视图区**，和「运行轨迹」并列，标签名是 **Git**。
+
+- 面板默认打开**当前会话的工作区**对应的仓库，不需要手填路径。
+- **新会话要先发一条消息**：会话还没进入对话时，视图区（包括「运行轨迹」和「Git」）本来就不显示。
+- 顶部一行是当前分支名（后面可能带 `↑n` / `↓n`，表示领先/落后上游多少个提交）、仓库路径框和**「刷新」**按钮。
+- 想临时看别的仓库，在路径框输入仓库路径并回车；切换会话后，面板自动回到跟随新会话工作区。
+
+## 三个视图
+
+顶部标签依次是 **审查**、**工作区**、**历史**，右侧显示当前变更总数（如「14 项变更」）。默认打开的是审查。
+
+### 审查
+
+审查视图回答「自从我上次标记之后，一共发生了什么」。比较对象是**工作区**，所以 agent 没有提交的改动也在里面。
+
+- 还没有标记时，这里是一段说明和**「标记为已审查」**按钮：把当前 HEAD 记为审查点。
+- 有标记后，顶部显示概览，例如「自 2 小时前以来：29 个提交、23 个文件、+2985 −710（含未提交改动）」；同一行里的**「标记为已审查」**负责把标记挪到最新的 HEAD。
+- 文件按**需要留意的程度**排序：冲突 → 删除 → 二进制 → 大改动（增删合计 ≥200 行）→ 其余按改动量。每行标出命中的原因和 `+/−` 行数，点进去看该文件自标记点以来的 diff。
+- 没有变化时显示「与审查点相比没有变化」。
+- 标记失效时（例如经历了一次 rebase）会提示「审查点已失效（可能被 rebase 删掉了），请重新标记」，而不是显示成空白。
+- 审查视图是只读的：看 diff、复制引用在这里；暂存和提交去工作区视图。
+
+### 工作区
+
+左边是变更文件，右边是 diff，上方是提交框。
+
+- 文件按**冲突 / 已暂存 / 未暂存 / 未跟踪**分组，组标题带数量。
+- 未暂存和未跟踪的行有**「暂存」**，已暂存的行有**「取消」**（取消暂存）；冲突分组没有按钮，需要先在终端（或其他 git 工具）里解决冲突并暂存，再回面板提交。点文件看 diff，未跟踪文件也能看，显示为整文件新增。
+- 打开已跟踪文件的 diff 后，每个改动块（hunk）都有自己的**「暂存此块」**或**「取消此块」**，可以只暂存一部分改动。未跟踪文件没有块级操作。
+- 提交框里填提交信息，按 **Enter** 或点**「提交 N 项」**（N 是已暂存的文件数）提交；没有暂存内容时输入框会提示先暂存。提交成功后提示「已提交 <短哈希>」。
+- 工作区干净时显示「工作区干净」。
+
+### 历史
+
+三栏：**分支树 | 提交 | 变更内容**。
+
+- 中间一栏是提交图：分支线、短哈希、提交标题和相对时间；点一个提交，右侧列出它改了哪些文件，点文件看该提交对这个文件的补丁。打开提交时默认选中第一个文件。
+- 点分支树里的分支会从那个分支重新查看提交（提交栏顶部显示「分支 <ref> · N 提交」）；再点一次回到 HEAD 的提交列表。
+
+## 标记（审查点）
+
+标记是一个**提交**，表示「我看到这里了」。它不改变仓库，也不产生任何提交。
+
+- 设置：在审查视图点**「标记为已审查」**，把当前 HEAD 记为审查点。
+- 重置：已有标记时再点一次同一个按钮，标记挪到当前 HEAD，已经看过的改动就从列表里消失。
+- 比较方式是「标记 → 工作区」，所以设置标记之后新产生的提交、以及还没提交的工作区改动都会显示出来；未提交的改动会一直留在列表里，直到它被提交。
+- 标记按仓库保存：同一个仓库不管从哪个路径打开，共用同一个标记。
+- 标记所在的提交如果被 rebase 删掉，标记会失效，面板会明确提示重新标记。
+
+## 分支与远端
+
+分支操作都在历史视图最左边的分支栏里。
+
+- 分支树分 **HEAD / 本地 / 远程** 三组；当前分支带 ★，远程分支按 remote 名分组。
+- **检出**：本地分支行上的「检出」直接切过去；远程分支行上的「检出」会检出对应的本地分支（已经存在同名本地分支时直接切过去，否则建一个跟踪分支）。成功后提示「已检出 <ref>」，并自动回到 HEAD 的提交列表。
+- **新建分支**：点本地分组标题旁的「新建」，输入分支名，按 **Enter** 创建并切过去，按 **Esc** 取消。基点是当前正在查看的分支（没有筛选时就是 HEAD）。
+- **拉取**：分支栏顶部的选择器可选「快进 / 合并 / 变基」，默认快进，旁边是「拉取」按钮。快进在分叉时失败，既不改写历史也不造合并提交；合并允许在分叉时生成一个合并提交；变基会把本地提交重放到远端之上。完成后提示「已更新 <旧> → <新>」或「已是最新」。
+- **推送 / 发布**：当前分支没有上游时按钮显示「发布」，推送的同时设置上游；有上游时显示「推送」。完成后提示「已推送 <旧> → <新>」「远端已是最新」或「已发布 <分支>」。
+- 没有 force push。拉取分叉失败、推送被拒之类的错误会原样显示 git 的提示。
+
+## 把改动交给模型
+
+### 在 @ 菜单里引用
+
+输入框的 `@` 菜单里有一个 **git** 来源，候选是**当前会话工作区仓库的改动文件**（最多 30 个）和**最近的提交**（最近 30 条），分成「改动的文件」和「最近的提交」两组；输入内容可以按文件路径、提交标题或哈希过滤。
+
+选中后会以引用形式插入消息，发送时展开成一段说明。它**只包含元信息**：文件路径、状态（修改 / 新增 / 删除 / 重命名等）、增删行数，或者提交哈希、标题，以及一条查看命令；**不包含 diff 正文**。所以模型知道「哪里变了、变了多少、该怎么去看」，但要真正看到改动内容，还需要自己读文件或执行一次命令。
+
+### 复制引用
+
+审查视图和工作区视图里的每个改动文件行都有**「复制引用」**，把同一段说明复制到剪贴板；粘进输入框即可，和用 `@` 选一样。它只在客户端复制，不会自动发送——发不发、发哪几条由你决定。提交没有行内按钮，要引用提交就在 `@` 菜单里选。
+
+### 输入框里的分支标签
+
+输入框底部那一行（和权限、模型选择器同一行）会显示**当前工作区的分支名**：分支图标 + 名字。
+
+![输入框里的当前分支标签](docs/composer-branch-chip.png)
+
+- **只展示，不切换**：切分支是面板的事。
+- **跟随会话自己的工作区**，和面板里手动填的路径无关。
+- 不是 git 仓库的目录不显示，detached HEAD（没有分支名）也不显示。
+- 分支可能在终端里被 agent 改掉，标签会自动更新，不需要手动刷新。
+
+## 高级配置
+
+面板默认只信任宿主进程启动时所在的目录（桌面端的默认范围很小）。通常不用配置：**harness 自己注册过的工作区总是被信任**，所以「跟随会话工作区」开箱即用，桌面端也一样。
+
+如果确实需要访问别的目录，编辑插件包里的 `cordis.patch.yml`，给 `git` 那一行加 `config`（文件里有注释掉的样例）：
+
+- `allowedRoots`：额外允许的路径前缀，默认是启动目录；写 `["*"]` 表示不限制（不建议）。
+- `defaultRoot`：请求没有给出仓库路径时使用的仓库，默认是启动目录。
+
+改完重启 `dsh web` 或应用后生效。
+
+## 常见问题 / 已知限制
+
+- **刻意没做**：Shelf、stash、删除分支、force push；merge / rebase 只能作为拉取策略，不能单独当动作执行。
+- 暂存只做到**改动块**，不支持块内逐行挑选。
+- 未跟踪文件可以看整文件新增的 diff，但没有块级暂存。
+- 输入框的分支标签只展示、不切换。
+- 面板（以及「运行轨迹」）只在会话进入对话后才出现；全新的空会话没有视图区，先发一条消息。
+- 工作区和历史视图里的列宽可以拖动分隔条调整，松手后会记住，下次打开保持。
+- 面板文案跟随应用的语言设置（English / 中文），插件没有单独的语言选项。
+- 兼容性：在当前的 DSH 桌面端上验证可用。
+- 出错时先看面板顶部的提示：git 自己的报错（路径不是仓库、拉取分叉、推送被拒等）通常会原样显示。
+
+## 卸载或停用
+
+在侧边栏「插件」页里停用或卸载；也可以用插件管理器：
+
+```js
+plugin_manager({ action: 'remove_bundle', target: '@xiaoming_z/dsh-git' })
+```
+
+停用后 Git 视图、输入框里的分支标签和 `@` 菜单里的 git 来源都不再出现。卸载不会改动你的仓库。
+
+## 许可证
+
+MIT。