@cerbur/clutch-dsh-worktree 0.1.12 → 0.1.14

package/README.zh.md

@@ -1,404 +1,321 @@
+[English](README.md) | [简体中文](README.zh.md)
+
 # @cerbur/clutch-dsh-worktree
 
-`@cerbur/clutch-dsh-worktree` 为 DSH Web UI 增加 Git Worktree 视图，按
-Workspace → Worktree → Session 组织会话，同时继续由 DSH 作为 Project/Workspace 身份、
-Session 元数据、原生列表和会话历史的唯一事实来源。插件在自己的 sidecar 中保存
-Worktree/Session 外部关系、创建或登记事实及用户编写的 Worktree 指令。
-
-> **预览版：** Worktree Dashboard 是仅插件的早期 MVP 预览版。目前已接入概览、会话
-> 列表与导航、Worktree 指令、新建/归档 Worktree 和在应用中打开入口；Git 详情、派生
-> Worktree、设置及其他标记为**即将推出**的操作仍是占位。
-
-## 界面截图
-
-![中文 Worktree 侧边栏和新会话空白 Hero](assets/screenshots/screenshots-zh.png)
-
-中文截图展示了侧边栏中的 Worktree 模式、包含 Main 和 Worktree 行的 Workspace 树，以及
-新会话空白 Hero 中的只读上下文。
-
-![英文 Worktree 创建/导入弹窗](assets/screenshots/screenshots-import.png)
-
-导入截图展示了现有 Workspace `+` 弹窗：默认选中创建，旁边是导入 Tab，并在普通下拉框中
-使用安全的示例 branch 和路径值。
-
-![Worktree Dashboard 预览（中文界面）](assets/screenshots/screenshots-dashboard.webp)
-
-Dashboard 截图记录了当前预览版界面：Worktree 身份、获取事实、已接入的会话与 Worktree
-操作，以及明确标出的占位卡片。
-
-## 能力
-
-- 从 Local/Main 或 active/archived Worktree 的菜单、行内悬浮操作，或原生 Session 标题行 More actions 按钮
-  左侧的快捷 Dashboard 图标打开 Dashboard，查看真实名称和 cwd、复制完整路径，并切换概览、Git
-  与变更、会话、派生 Worktree 和设置。尚未接入的 MVP 卡片与操作明确标记为“即将推出”。
-- 从 DSH Sidebar footer 进入 Worktree 模式，按 Workspace → Worktree → Session 浏览会话。
-- 搜索 Workspace，并从已有 local branch 创建 Git Worktree 和 branch。
-- 在同一个弹窗中选择导入，发现与当前 Workspace repository 关联、尚未由 sidecar 管理且绑定 branch 的 Git Worktree。第一版不展示 repository root 和 detached HEAD 条目。
-- 导入只登记已有 Worktree，不移动、复制或编辑其目录；导入记录与插件创建的记录共享相同的 Session、binding、health、排序、cwd、投影、刷新和恢复流程。
-- 非破坏性归档 Worktree，保留磁盘文件、活动绑定与运行时 cwd。磁盘清理（`git worktree remove`）需经二次确认，由用户自行确认使用该目录的 Session/子代理与其他任务已停止；亦支持移出插件管理并保留磁盘文件与 Session。
-- 在 Main 或 active Worktree 下创建普通 Session 或 Worktree Session，并直接打开新会话。
-- 对 active Worktree Session，先经明确确认，再请求命名的 `worktree-full-access` 预设。它将
-  DSH 的 `danger-full-access` 与 `ask` 组合：关闭关联 Git 元数据的文件系统限制，但保留
-  审批提示；网络和进程策略不变。原生 Access 菜单中的 `Worktree Full Access` 会显示
-  Worktree branch 图标。
-- 保留用户在 DSH 原生 Access 界面中选择的限制。如果自定义预设不可用，在可能时回退到
-  `workspace-write + ask`；如果无法验证权限能力，则显示可重试的降级状态，不伪称已获得完全访问。
-- 复用原生动画 `StateDot` 展示运行中的 Session，并为最近一条用户发送的 Session 消息显示
-  原生相对时间；hover 或打开菜单时，右侧位置让位给已有的操作菜单。
-- Dashboard 的 Session 卡片在概览预览和完整的 Session 页签中复用同样的状态或相对时间信息，
-  与 Worktree 列表保持一致。
-- 使用 DSH 原生 Session hover 详情卡片展示完整标题、相对时间和当前状态；打开 Session 操作
-  菜单或拖拽行时，详情卡片让位。
-- 补齐原生的等待审批、计划待审、等待回答、已完成、空闲和运行中子代理状态；插件不会复制
-  原生动画实现。
-- 当折叠的 Workspace、Main 或 Worktree 中存在任一未归档的活动 Session 时，在其右侧显示
-  一个原生运行指示器；折叠运行状态会为 28px 指示器和 4px 文字间距预留空间，过长的 Worktree
-  名称会在活动持续期间滚动；展开后恢复普通操作栏。
-- 用户在 Session 中发送新消息后，该 Session 会移动到当前 Main 或 Worktree 视觉分组的队首。
-  该排序只保存在浏览器本地，不修改 DSH Workspace 顺序或 Worktree sidecar。
-- 从 DSH 原生 Workspace session list tab、Worktree view 或 Conversation fork 操作 fork
-  Session。parent 有 active Worktree binding 时，child 会自动绑定到同一个 Worktree 并直接在
-  Worktree 视图中打开；child 仍然是普通 DSH Session。
-- 查看 ready、repair、active 和 detached Worktree 状态，包括可重试的操作错误。
-- 通过 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径；已管理 Worktree 额外通过选项菜单和
-  行内悬浮操作提供 Dashboard。Worktree 分组的右侧操作栏在静止时为零宽度；折叠且有活动时会为 28px 运行指示器和 4px 文字间距
-  预留空间。hover、focus 或打开 menu 时才按实际可用的 Dashboard、menu 和 Session `+` 控件占用宽度；
-  过长的 Worktree 名称会在悬浮或折叠运行期间自动横向滚动，两个触发条件共用一个滚动循环，均不满足
-  后回到原始位置。
-  active Worktree 提供“归档 Worktree”并要求确认。
-- 通过 Local 或 active Worktree 的选项菜单创建新的 Worktree。创建弹窗会以所选行的当前 branch
-  为基线，并预填下一个可用的递增名称，例如 `feature-2` 或 `feature-3`；detached Worktree
-  不显示该动作。
-- 继续使用 DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单。Worktree 可以在所属
-  Workspace 内排序；顺序保存在插件 sidecar 中，Main 固定在第一位。
-- 将 Workspace、Main 和 Worktree 的展开选择保存到浏览器本地存储；Session 五行溢出展开保持临时状态，并在刷新或父级折叠后重置。
-- 在 Worktree Header 提供「全部折叠」按钮，支持一键折叠所有 Workspace 与 Worktree。
-- 在 Worktree view 高亮 DSH 当前 Session；进入 Worktree 模式或切换当前会话时，临时展开其 Workspace/Main/Worktree 路径；只有当前行不在前五行时才展开 Session 五行溢出，随后清空隐藏它的搜索并滚动定位；这一浏览器本地行为不改变已保存的展开选择。
-- 在已有 Conversation 的标题行以及新会话空白 Hero 中，以只读方式显示当前 local branch 或
-  Worktree branch 上下文。
-- 在普通 Worktree Session 的 Session 操作菜单中复制 Session ID。
-- 在同一个 Session 的 snapshot 更新以及 Session 切换期间保持 Conversation 和 Hero 上下文
-  稳定；替换读取进行时保留上一次有效上下文。
-- 过长的 branch 名称在 chip 中折叠，并通过原生 hover card 展示完整值；Sidebar footer action
-  对齐原生字体和排版，Sidebar 折叠后不再额外显示 `WT` 按钮。
-- Worktree Session 仍出现在原始 DSH Project/Workspace 视角中；插件不复制 Session 内容，
-  也不修改消息、prompt、transcript 或历史记录。
-
-### 兼容性与前置条件
-
-Session 重新加载兼容 DSH rc.1 的持久化 header 与新版 DSH 的 header snapshot。
-Worktree Dashboard 预览版会为新 Worktree 记录获取事实，并为 active binding 注入已保存的指令。
-
-兼容性事实表如下：
-
-| 组件 / Component | 最低版本 / Min Version | 说明 / Notes                                            |
-| ---------------- | ---------------------- | ------------------------------------------------------- |
-| DSH Client       | `>=0.1.5-rc.1`         | 依赖 Session/Workspace Controller 及 Client Store       |
-| DSH Host         | `>=0.1.5-rc.1`         | 依赖 Typert Gateway `/api` 协议与 subprocess capability |
-| Git              | `>=2.20.0`             | 要求支持 worktree 核心命令与 branch 发现                |
-| Node.js          | `>=20.0.0`             | 推荐使用 LTS 版本                                       |
+`@cerbur/clutch-dsh-worktree` 为 DSH Web UI 增加 Git Worktree 视图，按 Workspace → Worktree
+→ Session 组织会话，同时保留 DSH 对 Workspace 身份、Session 元数据、原生列表、消息和会话
+历史的事实来源地位。
+
+插件只在自己的 sidecar 中保存 Worktree 关系、获取事实、共享 Worktree 指令以及 Workspace 根目录的
+Main 指令。受管理的 Worktree 提供可选择本地 branch 基线的只读 Git 与变更 Dashboard，Main 提供 Workspace 根目录 HEAD history；
+不会复制 transcript 或改写 DSH Session。
+
+> **预览：** Worktree Dashboard 是仅 plugin 提供的早期 MVP 预览版。Worktree 导航、生命周期操作、
+> Session 操作、Worktree/Main 指令以及受管理 Worktree 或 Main 的 Git 与变更视图已经连接。派生 Worktree、设置和
+> 其他未完成操作仍标记为**即将推出**。
 
 ## 安装
 
-### 从 npm 安装（推荐）
+### 从 npm 安装
 
-在已经安装 DSH CLI 的环境中执行：
+在已安装 DSH CLI 的环境中：
 
 ```bash
 dsh plugin --profile web add @cerbur/clutch-dsh-worktree
 dsh web
 ```
 
-如果使用 `deepseek-harness` 源码 checkout、系统没有独立的 `dsh` 命令，使用等价的转发
-形式：
+如果使用 DeepSeek Harness 源码 checkout 且没有独立的 `dsh` 命令，可使用等价的
+`pnpm dsh` 形式。
 
-```bash
-cd /path/to/deepseek-harness
-pnpm dsh plugin --profile web add @cerbur/clutch-dsh-worktree
-pnpm dsh web
-```
+### 从本地 checkout 安装
 
-可以通过官方 registry 查看当前发布版本：
+先构建本 package 和 DSH 源码 checkout，再用绝对路径添加 package：
 
 ```bash
-npm view @cerbur/clutch-dsh-worktree version --registry=https://registry.npmjs.org/
+cd /absolute/path/to/clutch-dsh
+pnpm install
+pnpm --filter @cerbur/clutch-dsh-worktree build
+
+cd /absolute/path/to/deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh plugin --profile web add /absolute/path/to/clutch-dsh/packages/clutch-dsh-worktree
+pnpm dsh web
 ```
 
-### 从 GitHub 源码安装
+DSH Web profile 必须已经能够正常启动。修改 `package.json` 或 `cordis.patch.yml` 后，需要重新
+执行绝对路径安装命令。
 
-`awesome-dsh-plugin` 生成的源码路径为：
+### 从 GitHub 源码安装（可选）
+
+DSH plugin market 使用的源码依赖形式也可以直接安装：
 
 ```bash
 dsh plugin --profile web add "github:Cerbur/clutch-dsh#path:/packages/clutch-dsh-worktree"
 ```
 
-这是源码 Git 依赖，安装时由构建脚本生成。关于 pnpm 11 的 `allowBuilds` 授权配置、本地开发与贡献者流程，详见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
+该方式会在安装时构建 package。pnpm 构建脚本授权和本地开发细节见
+[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
 
-### 卸载
+## 功能
 
-```bash
-cd /path/to/deepseek-harness
-pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
-```
+| 功能 | 预览 | 作用 |
+| --- | --- | --- |
+| **Worktree 导航** | <img src="assets/screenshots/screenshots-en.png" width="420" alt="包含 Workspace、Main、Worktree 和 Session 行的 DSH Worktree 导航"> | 在 Sidebar 增加 Worktree 模式。每个 Workspace 下可以浏览 Local/Main 和 Git Worktree，再打开对应行绑定的 Session。 |
+| **创建和导入 Worktree** | <img src="assets/screenshots/screenshots-import.png" width="420" alt="Worktree 创建与导入弹窗"> | 从本地 branch 创建 Worktree，或原地登记已有的 branch-attached Worktree。导入不会移动、复制或编辑已有目录。 |
+| **Worktree Dashboard** | <img src="assets/screenshots/screenshots-dashboard.png" width="420" alt="显示 Session 和 Worktree 操作的 Worktree Dashboard 预览"> | 预览版 Dashboard 显示 Worktree 身份、路径、Session、Worktree/Main 指令、已连接操作、由 Host 提供的在应用中打开入口，以及受管理 Worktree 或 Main 的只读 Git 与变更视图。派生 Worktree、设置和其他未完成卡片仍标记为**即将推出**。 |
 
-## 使用说明
+## 使用
 
 ### 打开 Worktree 模式
 
-1. 启动 DSH Web UI，在 Sidebar footer 选择 Worktree。Worktree 模式是附加界面，不会添加
-   独立的 Workspace/Worktree Tab。
-2. 使用 Workspace 树搜索、展开并选择 Main 或 Worktree 视角。每组默认显示五行，更多内容
-   使用 Expand more/Collapse。
+1. 启动 DSH Web，在 DSH Sidebar 底部选择 **Worktree**。
+2. 在 Worktree 树中搜索或展开 Workspace。
+3. 选择 Local/Main 或某个 Worktree 浏览其 Session。这个视角是附加的，DSH 原生的 Workspace
+   和 Session 导航仍然可用。每组初始显示五行，可使用**展开更多**和**收起**查看其余内容。
+4. 使用 header 中的 **Collapse All** 折叠其他无关的 Workspace 和 Worktree，当前 Session 所在的
+   Workspace 与 Worktree 保持展开。
 
-![使用 Worktree 模式时的侧边栏和新会话空白 Hero](assets/screenshots/screenshots-zh.png)
+### 创建 Worktree
 
-上图展示了侧边栏入口以及新会话空白 Hero 中显示的视觉上下文。界面语言跟随 DSH 当前的
-语言设置。
+1. 打开 Local/Main 或 active Worktree 的选项菜单，选择 **Create Worktree**。
+2. 选择本地 base branch，也可以填写新的 branch 名称。
+3. 确认弹窗。插件会创建 Git Worktree，记录获取事实；从该 Worktree 打开 Session 时继续执行
+   正常的 Session 和 binding 流程。
 
-### 打开 Worktree Dashboard
+Git repository、本地 branch 和 initial commit 必须可用。如果仓库尚未准备好，DSH 会显示对应
+的 readiness 提示和可复制的 setup 指引。
 
-Dashboard 是仅插件的预览版 MVP，不会替换 DSH 原生 Session 页面，也不会写入 DSH 管理的
-Workspace/Session 数据。
-
-在 Worktree 模式中，将鼠标悬浮到已管理 Worktree 行并点击 Dashboard 图标，或打开行的选项菜单
-并选择 **Dashboard**。对于具有 ready Main 或 Worktree 上下文的当前 Session，也可以点击 Session
-标题行中原生 **More actions** 按钮左侧的 Dashboard 图标。Dashboard 会临时替换 Sidebar 旁的区域
-（含 Session 页面），原生会话组件保持挂载。点击**返回会话**、按 **Escape**、从 Sidebar 打开
-Session 或退出 Worktree 模式，即可恢复原生页面。打开 Dashboard 不会创建或修改 Session；
-Local/Main 与已管理 Worktree 行都提供行内 Dashboard 图标，当前 Session 仍可使用标题行快捷入口。
-Dashboard 打开后仍可拖动 Sidebar 的宽度。
-
-![Worktree Dashboard 预览](assets/screenshots/screenshots-dashboard.webp)
-
-上图展示了原生 Worktree Sidebar 旁的预览版 Dashboard。已接入的控件仅覆盖 MVP 范围；
-未完成的卡片仍会明确标记。
-
-标题沿用 Worktree 行的已接受分支名称，点击标题即可直接复制分支名称。cwd 展示记录中的完整
-绝对路径，复制按钮明确反馈成功或失败。如果 DSH 无法提供 Main 的当前分支，Dashboard 会标记为
-无法获取且不会提供分支复制。当前分支、可用性与来源使用现有 Worktree 投影；ready 表示 Worktree 可用，**不代表**
-Git 文件没有变更。归档或已清理记录仍展示记录中的路径，该路径不一定仍存在于磁盘。
-
-五个 tab 支持左右方向键、Home 和 End。概览显示当前 Worktree 的前五个会话，会话 tab
-显示完整列表；两者直接消费内存中的 sessions 和 bindings，沿用 Sidebar 排序与可见性规则，
-不受 Sidebar 搜索影响。点击会话返回原生页面。新建会话离开 Dashboard，直接复用现有
-create/bind/open 流程，保留空白会话复用与失败恢复。
-新建 Worktree 呼出已有创建弹窗，预选当前分支和编号名称；归档 Worktree 呼出已有的非破坏性
-确认框。操作沿用 Sidebar 的健康状态、归档状态和进行中操作门禁。
-在 VS Code 中打开使用编码后的 `vscode://file/...` 链接打开记录中的 cwd；浏览器所在机器
-须安装 VS Code 且能访问该路径，浏览器可能要求确认打开应用。链接不核验目录是否存在或
-应用是否成功启动。
-在 Worktree 指令卡片中点击**编辑**，可编辑、保存或清空共享指引（最多 32,000 个 UTF-16
-code units）。内容保存在插件 sidecar，不写入 AGENTS.md；保存后通过 DSH `agent/pre-step`，
-以独立的 `<system-reminder>` 上下文记录进入会话轨迹和下一次模型请求。
-消息由 DSH 记录，不重写已有历史。
-指令内容按原文插入，其中的 `{{...}}` 示例不会被当作模板变量解析。
-归档保留 active binding 和指令；detached binding、清理磁盘或移出管理后停止注入。
-清空或失去 binding 后，下一步追加提醒使旧指令失效。指令未变且消息仍可见时不重复注入，
-重启后也会去重；压缩移除后按需重新注入。保存失败保留草稿，并发编辑会被拒绝；
-取消并重新打开可加载最新内容后重试。
-
-新建 Worktree 显示记录的创建时间和创建时所选基线分支。导入的 Worktree 显示登记时间，
-不推测原始创建时间或基线；缺少这些历史事实时，Dashboard 提示**历史 Worktree 无法获取**，
-不再显示“未知”。基线是创建时的分支名，
-不代表当前 merge-base 或领先/落后计算，checkout 不会修改它。
-Open-editor 分体按钮对齐 DSH 原生样式，并提供主机检测到的应用菜单；不可用时回退到上文
-说明的 VS Code 协议链接。
-
-Git 详情、派生 Worktree、设置及其他标记的快捷操作仍为占位。界面跟随 DSH
-主题，窄屏下卡片纵向排列。Dashboard 选择状态是临时的，刷新页面后不会恢复。
+### 导入已有 Worktree
 
-### 创建 Worktree
+1. 选择 Workspace，打开它的 `+` 操作，然后切换到 **Import**。
+2. 从 branch 和 path 列表中选择候选项。
+3. 选择 **Import Worktree**。插件会原地登记已有目录，不移动、复制或修改其中的文件，随后
+   使用与新建 Worktree 相同的 Session 流程。
 
-新目录使用 `$dshHome/clutch-dsh-worktree/worktree/wt_<12-hex-characters>`
-（文件夹名为 15 个字符，包含 48 位加密随机数）。
-目录名、Git 登记或 sidecar 身份已被占用时自动换名重试；八个随机候选均冲突后，
-依次尝试 `_1`、`_2` 等数字后缀，直到找到可用名称或取消。
-已有 Worktree 的路径和 ID 保持不变；分支冲突与其他 Git 失败沿用原有错误处理。
-
-1. 选择 Workspace，点击它旁边的 `+`，选择基线 local branch，并填写 Worktree name。默认
-   branch 名称为 `dsh/<8-character-random-string>`。
-2. 如果要从已有 Worktree 创建同级 Worktree，打开该 active Worktree 的选项菜单并选择
-   `创建新的 Worktree`。弹窗会以当前 Worktree branch 作为基线，并为名称选择下一个可用的
-   递增序号；已有名称会被跳过。
-3. 目标 Worktree 路径必须是绝对路径，属于同一个 Project，且不能是 Project 根目录。相对
-   路径、其他 Project 的路径或 Project 根目录都会被拒绝。
-4. Git 必须已安装且可在 PATH 中使用。Git 可执行文件缺失时显示安装提示且不显示命令块；请
-   安装 Git、重启 DSH 后重试。如果缺少 repository、初始 commit 或本地 branch，按照弹窗中
-   的可复制 setup 命令修复后重试。插件只展示这些提示，不会执行 setup 或安装命令或编辑
-   业务文件。
+第一版只列出尚未被插件管理、状态 ready、绑定 branch 且不是 repository root 的 Git Worktree。
+Detached、bare、prunable、缺失或无效条目会被省略。导入的 Worktree 仍可在选择本地基线 branch 后
+使用 Git 与变更。
 
-### 导入已有 Worktree
+### 创建并打开 Session
 
-1. 选择 Workspace，点击旁边的 `+`，再选择 `导入` Tab。弹窗通过现有 DSH `/api` Connection
-   加载该 repository 的 Git Worktree 候选项。
-2. 第一版只列出绑定 branch、不是 repository root、且未出现在 plugin sidecar 中的 Worktree。
-   detached HEAD、bare、prunable、目录缺失和 `.git` 缺失的条目会被省略。
-   已管理 Worktree 的 health 与导入资格共用运行时状态映射，提交导入时重新校验；
-   locked Worktree 在其他条件满足时仍可导入。
-   候选项通过普通下拉框选择，每个选项先显示 branch，再显示绝对路径
-   作为诊断信息。
-3. 在下拉框中选择一个选项并点击 `导入 Worktree`。登记只写入 plugin sidecar，已有 Worktree 目录和 Git
-   工作状态保持不变。随后会在该 Worktree cwd 创建或复用 Session，并执行与创建相同的
-   `bind → open → binding refresh` 流程。
-4. 同一 Workspace、同一物理路径的 active external 导入是幂等的。已经由 plugin 管理的路径
-   会报错提示；无效或过期候选项在修复 repository 状态后可以重试。
-
-### 创建 Main 和 Worktree Session
-
-- 使用 Main 的 `+`，在 Project 根目录视角中创建普通 DSH Session。
-- 使用 Worktree 的 `+`，创建或复用以该 Worktree 为运行时工作目录（`cwd`）的 Session。Session
-  直接在 Worktree 视图中打开，不会短暂出现在 Main 列表中。
-- 如果存在目标 cwd 完全匹配的未归档空白 Session，连接器会优先复用它。已绑定的 Session 会直接打开；
-  未绑定的候选会先完成绑定再打开。否则走新建并绑定的流程，同一个 Worktree 的并发点击会合并处理。
-- 如果 DSH 创建 Session 后绑定失败，Session ID 仍会保留，可用于重试或直接打开。插件绝不删除或修改已创建的 DSH Session。
-- 打开 active Worktree Session 前，插件会在 DSH 风格的页面内弹窗中说明关联 Git 元数据为什么
-  可能需要访问 Session 目录之外的内容。弹窗要求明确勾选风险确认；取消会保留 Session 和
-  绑定关系，不改变权限，并留下可重试的待处理状态。需要切换到其他权限模式时，继续使用 DSH
-  原生 Access 选择器。
-- provisional blank Session 遵循 DSH 原生显示规则：只在当前选中的视角中显示，使用本地化
-  的 `New Session` 文案，不显示生成的 ID，也没有 Rename、Fork 或 Archive 菜单。接受第一条
-  prompt 后，它会变为普通 Session 行；隐藏 blank 行不会删除 Session 或 Worktree 绑定。
-
-### Session 活动与排序
-
-- Session 行复用 DSH 原生 `StateDot`：运行中的 Session 以及存在运行中子代理的 Session，使用
-  右侧动画点替代相对时间。等待审批、计划待审和等待回答使用原生 warning 点；已完成 Session
-  保留原生 completed 点。
-- 右侧元数据使用原生紧凑时间单位（刚刚、分钟、小时、天、月、年），来源是 DSH 的
-  `updatedAt`，该字段随最近一条用户消息推进；空白 New Session 不显示时间。时间只在 snapshot
-  render 时按原生规则重新计算，不额外增加每分钟 ticker。
-- 将鼠标悬停在 Worktree Session 行上 500 毫秒后，会打开原生详情卡片，展示完整标题、相对时间
-  和状态；Session 菜单打开或行正在拖拽时不显示卡片。
-- 折叠的 Workspace、Main 或 Worktree 分组，只要任一未归档成员正在运行就显示相同的原生运行点，
-  即使该 Session 被搜索隐藏也会计入。展开后隐藏聚合点；hover、focus 或打开菜单时显示原有
-  操作控件，并只在此时占用操作栏宽度。
-- 用户发送新消息后，Session 会移动到当前 Main 或 Worktree 视觉分组队首。promotion、已观察
-  时间戳和每组顺序只存在浏览器本地；手动拖动仍先调用 DSH 原生排序 API，成功后再更新本地顺序。
-
-### Fork Worktree Session
-
-- 支持通过任意 DSH 原生 fork 入口（会话列表选项、Worktree Session 菜单或会话内的 fork 操作）分叉会话。会话历史截取、标题递增和分叉血缘完全沿用 DSH 原生行为。
-- 当父 Session 拥有活跃的 Worktree 绑定时，分叉出的子 Session 会自动继承并绑定到同一 Worktree，直接在 Worktree 视图中呈现。绑定刷新期间保持当前已就绪内容可见。
-- 如果子 Session 已由 DSH 创建但插件绑定失败，DSH 仍保留该子 Session，界面提供“重试绑定”与“打开已创建会话”恢复操作。后续插件初始化也会根据原生会话血缘重试可恢复的子会话，绝不会自动绑定无关的子代理。
-- 分叉绑定由插件外部索引维护，不修改 DSH 原生工作区持久化存储。
-
-### 排序与管理 Worktree
-
-- 在所属 Workspace 内拖动 Worktree 可进行排序。自定义顺序由插件保存；Main 始终固定在第一行，Worktree 不能跨 Workspace 移动。
-- 新创建或新导入的 Worktree 会插入所属 Workspace 的 Worktree 列表队头；已有 Worktree 顺序保持不变。
-- 打开 Main 和 Worktree 共用的选项菜单可复制所选行的绝对路径。active Worktree 提供“复制路径”与
-  “归档 Worktree”。归档 active Worktree 属于内部归档操作：完整保留磁盘目录、关联绑定与运行时 cwd，并将该 Worktree 移动到工作区底部的“已归档”（Archived）分组中。
-- 工作区底部在存在已归档 Worktree 时渲染“已归档”分组，默认处于折叠状态；标题显示已归档 Worktree 总数，收起时仍然显示。每个 Workspace 维护独立的折叠状态。
-- 处于 repair 状态的 active Worktree 也提供“归档 Worktree”，仅归档记录，保留磁盘文件和绑定。处于 recovery-needed 状态的记录须先完成恢复，不能直接归档。
-- 对于未清理磁盘的已归档 Worktree，选项菜单提供：
-  1. “取消归档”（Unarchive Worktree）：对于仅元数据标记归档且磁盘目录完好的 Worktree，可直接在菜单中点击取消归档，无需二次确认弹窗，立即恢复为活跃状态。
-  2. “清理磁盘”（Clean Up Disk）：弹出二次确认弹窗（明确提示工作树路径与破坏性删除不可逆），告知插件不核验 Session/子代理活动，请用户自行确认使用该目录的任务均已停止，否则删除可能导致任务失败或数据丢失；执行真正的非强制 `git worktree remove`，成功后记录清理完成，关联绑定转为 detached，并将完全访问权限归一化为 `workspace-write + ask`。磁盘清理提交与权限后续解耦：清理成功即确认提交、关闭对话框并将状态转为已清理；权限归一化失败或刷新异常提供独立恢复，不重复执行磁盘删除。如果 Worktree 目录或其 `.git` 入口已在外部删除，确认清理只将插件记录标记为完成并解绑，不再执行 Git 删除。
-  3. “移出管理”（Remove from Management）：弹出确认弹窗，删除该 Worktree 的插件记录与全部关联绑定，完整保留磁盘文件与 DSH 原生 Session；同时定向淘汰该 Worktree 的未决 fork 恢复、投影与权限提示。不需要校验 Session 活动。
-- 对于已清理磁盘的 Worktree，选项菜单提供“移出管理”以彻底移除该插件记录。
-- 会话活动展示仅用于信息参考，不阻断磁盘清理或移出管理。确认磁盘清理前，请自行停止所有使用该目录的任务，插件不会核验任务是否已停止。
-- 删除 Workspace 只会删除 DSH 的 Workspace 登记；其目录、Session、Git Worktree 和插件数据完整保留。
-- DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单继续可用。Session 拖动排序限定在当前视觉 Main 或 Worktree 分组中。
-- Main 分组显示当前 local branch：有分支时为 `本地（branch）`，DSH 没有返回当前分支时回退为 `本地`。如果导入的 Workspace 是 Git 仓库中的子目录，会先解析 Git 根目录，再复用与 Git 根目录相同的 branch/worktree 信息。branch 名称、路径、Workspace 名称、Session 标题以及原始错误信息保持原值。
-- 已有 Session 会在标题行显示只读上下文，格式为 `Session title` → `Agent mode` → `current branch / Worktree branch`。过长值在紧凑 chip 中折叠，并通过 hover card 显示完整内容。原生标题存在且有锚点时，新会话空白 Hero 会在标题后显示 `Workspace (branch)`，并提供相同的完整值 hover card。
-- Sidebar 折叠后，footer 保留原生的 icon-only action 尺寸和排版；插件不会额外绘制独立的 `WT` rail control。
-
-### 同步在 Git 中切换的分支
-
-外部执行 `git checkout` 后，下次 Worktree 读取显示“旧分支 → 当前分支”与分支变化提示。
-刷新或打开 Worktree 菜单时会读取，插件不持续监听 Git。分离 HEAD 会明确标注。
-Session binding 和运行时 cwd 保持不变，普通分支切换不会锁住整个 Workspace。
-
-在活动或归档 Worktree 菜单中选择“采用当前分支”（`Adopt current branch`）并确认，
-只更新插件记录的分支。确认期间 Git 分支或快照已变化时会拒绝操作，请刷新后重新确认。
-分离 HEAD 必须先在 Git 中切换到分支；清理磁盘前必须先采用当前分支。
-Git 明确证明原记录已切走时，允许用空闲的旧分支创建 Worktree；真正被 checkout 的分支仍不可用。
-
-确认失败会在弹窗内显示错误。点击“重试”（`Retry`）重新读取当前分支和快照 token，
-再确认更新后的分支变化；刷新成功前不能再次提交旧确认。如果 Worktree 已不再处于
-分支漂移状态或进入分离 HEAD，弹窗会关闭。从该行创建新 Worktree 使用读到的当前分支，
-无需先采用分支；分离 HEAD 不提供此操作。
-
-`recovery-needed` 行的菜单提供“重试恢复”（`Retry recovery`），作用于所属 Workspace。
-该操作只重试安全 journal 恢复，不自动采用分支、不删除未知路径、不清除未解决的身份问题。
-采用分支和恢复成功后只刷新所属 Workspace，并保留现有 ready 内容。
-
-### 理解状态与恢复提示
-
-- 操作、权限、绑定和刷新失败统一使用 DSH 原生 toast，逐条显示；相同错误不会随每次渲染重复提示。
-  toast 消失后，完整信息及原有重试/打开操作仍保留在可展开的“提示详情与恢复操作”入口。
-  表单校验和 Workspace Git 初始化指引保留在对应输入附近。
-- 悬停或聚焦 active Worktree 行可查看状态、路径以及目录/Git 登记缺失、分支漂移/分离 HEAD、
-  恢复未完成的处理指引。打开菜单或拖动时不显示 hover 卡片。归档确认明确说明插件创建及外部
-  Worktree 都保留目录、Session 绑定和 cwd；“清理磁盘”仍是独立操作。
-- `ready` 表示 Worktree 可用。`cleaned` 表示磁盘清理已完成且保留 sidecar 归档条目。
-  `repair` 表示 Worktree、Session、binding 或 cwd 缺失/无效。`recovery-needed` 表示 Git/sidecar
-  操作或身份校验尚未解决，破坏性操作会被阻止。`detached` 表示 Git Worktree 已被移除，但关系仍然保留。active binding 指向缺失
-  Worktree 时会显示明确的 repair 警告或错误，不会静默切换到其他 Worktree。
-- 没有未完成 Git 事务时，目录缺失的 active 或 archived Worktree 保持 `repair`，可归档，
-  不会阻断健康 Worktree 的 Session 绑定。
-- Worktree health 是 Git 的运行时 projection，不写入 sidecar。Git 前置条件失败按
-  Workspace 显示提示：Git 可执行文件缺失时显示安装提示且不显示命令块，缺少 repository、
-  初始 commit 或本地 branch 时显示可复制的 setup 命令。Connection、Gateway 和未预期的
-  Worktree domain 错误会保留为可重试错误，不会伪装为空列表。
-- 权限状态会明确显示为完全访问、回退到 `workspace-write`、保留用户限制、能力未验证、
-  等待确认或可重试的设置失败，不会静默折叠为空列表或伪造成功。
-- 已经 ready 的视角刷新时会保留当前 projection，直到替换数据可用。同一个 Session 的
-  snapshot 更新不会清空上下文，也不会触发重复读取；没有缓存视角时，首次进入和显式 Retry
-  可以显示 loading 状态。
+- 在 Local/Main 上使用 **+**，创建运行目录为 Workspace root 的普通 DSH Session。
+- 在 Worktree 上使用 **+**，创建运行目录为该 Worktree 的 Session。
+- 如果存在完全匹配目标目录的未归档空白 Session，插件会尽量复用它。
+- 可以使用 Session list、Worktree Session 菜单或 conversation 中的 DSH 原生 fork 操作。
+  Worktree-bound Session 的 child 会绑定到同一个 Worktree，并在该视角打开。
 
-## 界面语言
+如果 DSH 已创建 Session 但 binding 失败，Session 会被保留。Worktree 视图会提供重试或直接打开
+的恢复操作；插件不会删除或改写 DSH Session。
 
-Worktree 模式跟随 DSH 当前界面语言。语言偏好由 DSH 管理；插件不增加独立的语言设置。
-Worktree 入口、Workspace → Worktree → Session 树、菜单、弹窗、状态和重试提示均提供中文
-和 English 文案。
+### 打开 Worktree Dashboard
+
+可以从 Local/Main 或 Worktree 行菜单、悬浮操作，或 Session 标题行原生操作旁边的 Dashboard
+图标打开。Dashboard 是与原生 Session 内容平级的页面，显示在 Sidebar 旁边的主区域；对于绑定 Session
+的目标，会保留已经打开的右侧栏。初始 Session list 处于 pending 时，Dashboard 会等待它变为 ready；如果
+当前 Session 已属于目标 Worktree，就保持当前 Session；否则切换到目标 Worktree 保留顺序中排在最前的
+Session，让两侧视图保持一致。ready 的空 Session list 会打开不绑定当前 Session 的 page-level Dashboard；因为没有目标 Session，
+它会收起当前打开的原生右侧栏，也不会自动创建 Session。只要当前 Session 可以承载右侧栏且右侧栏处于收起状态，
+Dashboard 右上角会保留原生的右侧栏按钮；右侧栏打开后，该按钮按原生行为自动隐藏。
+
+使用 **Back to session**、Escape、Sidebar 中的 Session 或退出 Worktree 模式关闭它。没有 Session 的
+Worktree 中，右上角操作会变为 **New Session**，直接在该 Worktree 中新建会话。当前 MVP 已连接的操作
+包括查看 Overview 和 Sessions、新建 Session 或 Worktree、归档 Worktree、编辑指令、复制路径、在 VS Code
+中打开记录的目录以及查看 Git 与变更。派生 Worktree、设置和其他标记的快捷操作仍是占位内容。VS Code
+必须安装在浏览器所在机器上且能够访问记录的路径；链接不会验证应用是否成功启动。
+
+### 在应用中打开记录的目录
+
+Dashboard 的 **Open in ...** 分割按钮保留插件自己的按钮 UI，但只调用 DSH 官方 Host 路由：
+
+- `GET /open-in-app/apps` 探测可用应用；
+- `GET /open-in-app/icon/<appId>` 获取应用图标；
+- `POST /open-in-app/open` 使用 `{ "app": string, "path": absoluteDirectoryPath }` 启动应用。
+
+按钮使用指向当前 DSH Host 的相对 URL，并传入 Dashboard record 的 `absolutePath`；不会探测操作系统，
+也不会持久化应用选择。应用选择只在当前页面内记忆，刷新后使用第一个可用应用。如果没有可用应用
+或 Host 请求失败，按钮仍保留现有的 VS Code 协议链接 fallback。
+
+### 使用 Git 与变更
+
+从受管理 Worktree 或 Main Dashboard 打开 **Git 与变更** Tab。Main 直接读取当前 Workspace 根目录 HEAD 的
+commit history；当根目录存在 tracked、staged、unstaged 或 untracked 改动时，顶部会加入**未提交的改动** entry。
+默认最多展示 200 个已提交 commit，选中第一个可见目标，并对工作区目标和已提交 history 使用相同的变更文件与 Diff 面板。对于持久化 `baseBranch` 存在且不同于当前
+branch，或带有作为隐式基线的获取 commit 的 managed Worktree，Overview 会通过现有 `/api` Connection
+做一次轻量、按需的 Git 状态读取，分别展示 ahead/behind commit 数量、已提交（基线到 HEAD）和未提交
+（当前工作区）的文件行数。这是临时 projection，不是 watcher，也不会写入 Worktree 记录。Main 没有 Worktree 基线
+比较，因此 Overview 对 ahead/behind 事实仍显示 **待接入**，但 Git Tab 可以展示 Main history。不可用或未选择基线的
+managed 视图会诚实显示 **待接入**。打开 Overview 不会加载 branch 列表；
+第一次进入 Git Tab 时才加载本地 branch，并在基线解析后加载 commit history。要替换基线，可以点击
+Base fact 旁的铅笔图标打开 branch 选择器：搜索框固定在选择器顶部，下方是有固定高度的 branch 列表
+（默认展示约七条），超出部分在列表内滚动，因此过滤 branch 时整个弹窗尺寸保持不变。选择除当前
+Worktree branch 之外的任一本地 branch，再保存。
+保存会替换 plugin sidecar 中持久化的 `baseBranch`；下次打开 Git Tab 时，选择器会以保存后的值作为默认值。
+Git Tab 打开后，直接修改其中的选择器仍只是临时查看选择，会重新加载 history、changed files 和 Diff，
+不会再次写入 Worktree 记录。如果不存在可用的已保存基线（缺失或等于当前 Worktree branch），Git Tab
+和 Overview 会改用 Worktree 不可变的获取 commit 读取，并将该解析出的 commit 显示为 Base fact；只有
+既无可用已保存基线、也无获取 commit 的 Worktree 才会保持未选择状态并提示用户选择。当所选 branch
+已分叉时，Git 会解析两个 branch head 的共同先祖；
+Worktree 在共同先祖之后的 commit 计为 `+N` 领先，base branch 在共同先祖之后的 commit 计为 `-N` 落后，
+history 和文件读取仍然可用。如果两个 head 没有共同先祖，则基线汇总退化为 base branch head 与
+Worktree `HEAD` 之间的完整 tree diff，history 展示 Worktree 相对 base head 独有的 commit。
+在有效的 managed Worktree 基线加载后，Git 与变更 Tab 初始会选择**基线汇总**，而不是第一个 commit；切换基线 branch
+也会回到该汇总。需要更窄的查看范围时，再选择 commit 或**未提交的改动**。Main 跳过这个仅用于比较的汇总，但使用相同的已提交 history 与多选行为；Workspace 根目录有改动时也展示实时工作区目标。
+选择**未提交的改动**会比较当前 Workspace 根目录与 `HEAD`，不会创建基线或写入 Git 状态。
+
+所选 branch 每次读取都会重新解析。浏览器只能选择普通的本地 branch 名，不能直接选择 commit SHA 或
+任意 Git ref：完整 ref 路径、tag 或 remote-tracking ref 会被直接拒绝，而已选 branch 不复存在时会显示
+诚实的不可用状态，而不是泛化的 Git 失败。`baseCommit` 是不可变的获取元数据，永远不能由用户直接选择，
+并在没有可用已保存 branch 基线时作为隐式基线；创建恢复也绝不会改写它。当 managed Worktree 或 Main Workspace 根目录存在 staged、unstaged 或 untracked 文件时，列表顶部会加入**未提交的改动**；
+选择它会将对应的当前工作区与 `HEAD` 比较，并使用相同的变更文件和 Diff 视图。
+
+**基线汇总**是一个独立的目标，默认展示从所选 branch 与 Worktree `HEAD` 的共同先祖到本次请求
+捕获的 `HEAD` 的净已提交树差异（无共同先祖时改用两个 branch head）；不包含工作区未提交改动。
+打开 **包含工作区改动** 后，该目标会改为展示从同一比较边界到当前工作区的一次净差异，其中包含已提交、
+staged、unstaged、untracked、删除和重命名改动。这是按需读取的新鲜 projection，而不是简单拼接两段
+Diff。点击 commit 会展示该 commit 自己的 Diff；对于 managed Worktree 和 Main，打开提交栏标题中的**多选提交**开关后，可以同时选择
+多个已提交行，查看这些 commit 各自 first-parent delta 的精确并集。Main 不提供基线汇总或工作区包含开关；该开关默认关闭，关闭时会把已选
+集合收敛回当前聚焦的 commit。变更文件会记录贡献它的
+commit；每个所选 commit 会作为独立 Diff segment 展示，不会隐式扩展成范围，也不会包含未选择的
+commit。变更文件栏标题会展示当前目标（基线汇总、所选 commit 或未提交改动）对应的绿色 `+N` 和红色
+`-N` 总行数；仅包含 binary 时显示未知。未提交改动 entry 与已提交的多选互斥。汇总 Diff 工具栏中的
+**在侧栏打开**会使用当前 Session 在原生右侧栏中显示当前文件，但前提是该 Session 属于 Dashboard
+对应的 Worktree。空 Worktree 或无关的当前 Session 不会通过此操作打开文件。
+
+managed Worktree 和 Main history 都最多展示 200 个 commit，更多内容会标记为 truncated；超过 Git adapter 输出上限的变更文件列表
+也会显式标记为 truncated，而不是报泛化错误。commit 详情使用 first-parent 比较，root
+commit 与空 tree 比较，rename/copy 行保留两个路径；binary 或过大的 diff 会显示明确的安全状态。变更
+文件行会用绿色 `+N` 表示新增、红色 `-N` 表示删除；binary 文件不显示这些数量。文件名会用绿色表示新增、红色表示删除、蓝色表示其他变更，每一行的标题与无障碍标签也会写出对应状态。文件夹 icon 会直接表示文件夹当前是展开还是折叠。
+**未提交的改动**是按需读取的临时快照，不会持久化，也不会持续监视 Git；刷新后才能看到后续编辑。
+
+Git 与变更使用受页面 viewport 限制的固定尺寸布局。宽度足够时是两列：提交与变更文件上下排列在较窄
+的左列，中间是可拖动的分割线，Diff 占满右列高度。宽度不足时保持两行：第一行左右排布提交和变更
+文件，第二行展示汇总 Diff。两种布局下两条分割线都可以拖动：左右分割线调整两列的宽度，或在第一行
+内调整提交与变更文件的宽度；上下分割线调整提交与变更文件面板的高度，或调整第一行与 Diff 的高度。
+拖动分割线，或聚焦后按方向键即可移动，双击恢复默认比例。较长的 commit list 和变更文件 list 会在
+各自栏内滚动，不会继续撑大 Dashboard。变更文件栏在路径宽于栏位时也允许横向滚动，文件和文件夹
+名称不会被省略。变更文件按文件夹分组，文件夹默认展开，并且可以独立展开或折叠。Diff 内容也会在
+固定尺寸的 Diff 栏内滚动；只读选择和刷新行为保持不变。
+
+视图是只读的，不提供 commit 或 staging 控件。managed Worktree 会依据所选 branch 到 `HEAD` 的 projection 验证
+commit；Main 会依据有界的 HEAD history projection 验证 commit。插件随后依据最新状态重新读取和授权工作区 path，因此这些 endpoint 不是通用 Git object 或文件读取器。
+刷新会在替换数据加载期间保留 ready 内容；旧 commit 或文件选择的迟到响应会被忽略。
+
+### 添加 Worktree 或 Main 指令
+
+在 Dashboard 的指令卡片上使用 **Edit** 为选中的 Worktree 或 Main Workspace 保存或清空共享指引，长度上限为 32,000 个
+UTF-16 代码单元。下一次模型请求会通过 DSH pre-step hook 收到独立的 `<system-reminder>` 上下文条目，
+包括在 Main 中运行的未绑定 Session。
+
+指令保存在 plugin 自己的数据中，不会写入项目目录或 `AGENTS.md`。清空、解绑、清理或移出管理后，后续请求不再注入；
+归档会保留 active binding，因此 Worktree 指令仍然生效。指令消息仍可见时，不变的指令不会重复追加。
+
+### 归档或移除 Worktree
+
+- **Archive Worktree** 是非破坏性操作，会保留目录、binding、指令和运行时 Worktree 上下文。
+  Git 登记仍完整时，可以取消归档。
+- **Clean Up Disk** 是单独的操作，需要二次确认，并执行普通的非强制 `git worktree remove`。
+  插件不会检查 Session 或子代理是否仍在使用该目录；确认前请先停止这些任务。清理成功后
+  binding 会 detached，记录会保留到之后显式移出管理。
+- **Remove from Management** 只删除 plugin 的 Worktree 和 binding 记录，会保留磁盘文件和原生
+  DSH Session，也不要求检查 Session 活动状态。
+
+## 要求
+
+| 组件 | 要求 |
+| --- | --- |
+| DSH Client | `>=0.1.5-rc.1`，需要 Session/Workspace Controller 和 Client Store |
+| DSH Host | `>=0.1.5-rc.1`，需要 Typert Gateway `/api` connection 和 subprocess capability |
+| Git | `>=2.20.0`，必须已安装且可在 `PATH` 中使用 |
+| Node.js | `>=20.0.0`，用于 DSH host runtime |
+| Host filesystem | 支持使用普通 Windows 和 macOS 本地路径保存 sidecar 与 Git Worktree 数据；网络、特殊或别名路径较多的文件系统可能不支持持久化同步或身份校验。 |
+
+## 行为与限制
+
+- DSH 拥有 Workspace 身份与根目录、Session 身份与元数据、原生列表、消息、prompt、transcript
+  和历史。插件不会复制或改写这些数据。
+- 插件外部索引保存 Worktree 路径、branch、来源、生命周期状态、binding、排序、指令、获取事实
+  及相关元数据。对于受管理 Worktree，Dashboard Base fact 是持久化的 `baseBranch`；用户可以将其
+  替换为除当前 Worktree branch 之外的本地 branch，保存后的值会成为 Git Tab 选择器的默认值。
+  不可变的获取 `baseCommit` 与它分开保存，不会因该编辑被重写。索引位于 DSH host 的 plugin data
+  directory，不写入项目目录或 DSH raw data，也不保存 Session 内容或 Workspace 根目录副本。
+- runtime `cwd` 在每次执行时派生。无 binding、Main 或 detached binding 使用 Workspace root；
+  active Worktree binding 使用 Worktree path。cwd 不会持久化写回 DSH Session metadata。
+- 一个 Session 最多有一个 active Worktree binding，一个 Worktree 可以有多个 Session。移除或
+  清理 Worktree 不会删除 DSH Session。失效的 active binding 会显示 repair 状态，不会静默切换到
+  另一个 Worktree。
+- Git 会在相关刷新、相关菜单打开和进入 Git Dashboard 时读取，插件不会持续监视 Git。外部切换
+  branch 会显示 branch drift；清理磁盘前必须显式执行 **Adopt current branch**。Detached HEAD 和
+  recovery-needed 状态会保持可见并支持重试。
+- Worktree 健康状态通过 branch icon 的颜色显示：ready 使用 success（绿色）状态色，branch drift 使用警告色，repair/recovery-needed 使用错误色。即使 hover 时 icon 被 disclosure control 替换，本地化健康状态标签仍可供辅助技术读取。
+- 新创建或新导入的 Worktree 会插入所属 Workspace 的 Worktree 列表队头；已有 Worktree 顺序保持不变，Main 固定在第一位。
+- 将 Workspace、Main 和 Worktree 的展开选择保存到浏览器本地存储；Session 五行溢出展开保持临时状态，并在刷新或父级折叠后重置。**Collapse All** 会折叠其他无关节点并保留当前 Session 所在的 Workspace 与 Worktree 展开。
+- 当前 Session 不在可见树中时，会高亮匹配行并临时展开定位；如果行已在可见区域内，不会移动导航滚动位置，否则只移动足够显示它的位置。且不改变已保存的展开选择。
+- Git Dashboard 的读取由 Host 通过 DSH 现有 `/api` transport 执行。浏览器不会执行 Git、读取
+  sidecar 文件或 `.git`，也不会暴露修改 working tree 的控制项。文件 diff 会禁用外部 diff 与
+  文本转换，并限制显示范围以保障安全。
+- Dashboard 的在应用中打开入口只通过 DSH 官方相对 Host 路由完成应用探测、图标加载和启动；应用选择只保存在当前页面内，刷新后使用第一个可用应用，Host 返回空结果或失败时回退到编码后的 VS Code 协议链接。
+- Git Dashboard 只实现 commit history、只读的**基线汇总**（可选包含一次从基线到工作区的
+  新鲜 projection）、顶部的只读**未提交的改动**快照、changed files 和一次一个 unified diff。
+  按请求启用时，这些 projection 会合并 staged、unstaged 和 untracked 文件，但不会写回 Git。
+  Dashboard 不提供 commit、staging、reset、revert、cherry-pick、fetch、push、pull、pull request、
+  graph lanes、pagination 或 syntax highlighting。
+- Session 行使用 DSH 原生的状态和相对时间展示。折叠的 Workspace、Main 和 Worktree 分组会
+  从完整且符合原生空白/归档可见性条件的成员中选择一个聚合 `StateDot`：等待审批（以及其他 pending interaction warning）
+  优先于运行中，运行中优先于已完成。Idle Session 不会贡献分组 dot；Worktree 健康状态仍
+  使用独立的前置指示器。视觉上的 Session 排序初始按最新的 `updatedAt` 值排列并只保存在浏览器本地；Main 固定为首行，Worktree 拖拽只
+  更新这个本地排序投影，Main 拖拽只有在 DSH 接受后才更新原生 Workspace 顺序。
+- active Worktree Session 在明确确认后可以请求名为 `worktree-full-access` 的 preset。它将
+  DSH `danger-full-access` 与 `ask` 组合，保留审批提示，不改变 network 或 process policy。
+  不可用时尽可能回退到 `workspace-write + ask`，否则显示未验证且可重试的状态；它不能突破
+  DSH 宿主设置的 sandbox 上限。
+- Session 与 Worktree 绑定及权限检查在 Host 端基于物理文件系统身份（`stat`/`realpath`）进行比较，而非单纯依赖词法路径字符串。这确保了在 Windows 与 macOS 各种路径形态下的稳健兼容（包括盘符大小写、正反斜杠、UNC 路径以及 `\\?\\` 等长路径前缀）。在 Windows 平台上，sidecar 原子持久化采用可写文件句柄同步并对目录同步保持容错（best-effort），Git CLI 集成兼容 `NUL` 空设备路径与 CRLF 换行符。
+- Git 必须已安装且可在 PATH 中使用。Git 可执行文件缺失时显示安装提示且不显示命令块；插件
+  不会执行 setup 或安装命令。
+- 如果插件的外部索引不可用或损坏，原生 DSH Workspace 和 Session 视图保持完全可读，插件
+  进入降级只读状态，绝不会使用空索引覆盖原生数据。
 
-Workspace 名称、Session 标题、branch 名称、路径以及 DSH/Host 返回的原始错误信息保持不变，
-便于诊断和继续使用 DSH 原生数据。Main 分组在 English 中本地化为 `Local (branch)`，中文
-为 `本地（branch）`；没有返回当前 branch 时分别回退为 `Local`/`本地`。
+## 界面语言
 
-## 数据边界与当前限制
+Worktree 模式跟随 DSH 当前界面语言。入口、树、菜单、弹窗、状态、Dashboard 标签和重试提示
+提供英文和中文。Workspace 名称、Session 标题、branch、路径以及原始 DSH 或 Git 错误保留原值。
 
-DSH 管理原始 Project/Workspace 身份和根目录、Session 身份和元数据、原生 Project/Session
-列表、消息、prompt、transcript 和历史记录。插件不会复制或重写这些内容。插件的外部索引
-位于 DSH host 的 plugin data directory 或独立 sidecar 存储中，只能包含以下关系事实：
+## 开发
 
-- `projectId`、`worktreeId` 和 `sessionId` 映射关系；
-- 绝对 Worktree 路径、branch 和生命周期状态；
-- Worktree 来源（`plugin` 或 `external`）；
-- binding 状态和 schema version。
+架构、本地 DSH 联调、测试和贡献流程见：
 
-索引不会写入 Project 工作树或 DSH 原始数据目录，也不会保存 `projectRoot` 副本或任何
-Session 内容。如果 sidecar 不可用或损坏，原生 Project/Session 视角仍然可读，插件进入
-degraded/read-only 状态；不能用空索引覆盖 DSH 原生列表。
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- [docs/RELEASING.md](docs/RELEASING.md)
+- [AGENTS.md](AGENTS.md)
+- [src/client/README.md](src/client/README.md)
 
-Session 活动仅用于信息展示，不阻断磁盘清理或移出管理。确认磁盘清理前，请自行停止所有使用该目录的任务，插件不会核验任务是否已停止。
-原生活动变化或重新打开归档菜单会刷新所属 Workspace 并保留 ready 内容。
+常用的 package 检查命令：
 
-一个 Session 最多绑定一个 active Worktree，一个 Worktree 可以绑定多个 Session。Session
-重复绑定同一个 Worktree 是幂等的，绑定两个 active Worktree 会产生 conflict。没有 binding、
-使用 Main binding 或处于 detached binding 的 Session 使用 Project 根目录作为 cwd；active
-Worktree binding 使用对应的 Worktree 路径。cwd 在每次执行时派生，不会写回 DSH Session 元数据。
+```bash
+pnpm --filter @cerbur/clutch-dsh-worktree typecheck
+pnpm --filter @cerbur/clutch-dsh-worktree build
+pnpm --filter @cerbur/clutch-dsh-worktree test
+```
 
-创建 Worktree 时先创建 Git Worktree，再记录外部关系；sidecar 写入失败时会尽可能清理刚创建的
-Git Worktree。创建 Session 时先调用 DSH 原生 API，再写入 binding；binding 失败不会删除或修改
-已创建的 Session。
+中英文 README 的结构通过以下测试校验：
 
-Worktree Session 视图通过前端视图投影呈现绑定的 Worktree 上下文，不修改 DSH 原生 Workspace 持久化数据。
+```bash
+node --test test/readme-parity.test.mjs
+```
 
-权限变更只使用 DSH 公共的 per-Session 权限服务。插件不会写入消息、prompt、transcript、Workspace 数据或 Session
-metadata，也不能扩大运行 DSH 的宿主沙箱边界。
+## 卸载
 
-空白 Hero 上下文只用于展示。由于当前 upstream DSH source checkout 没有 additive Hero
-headline slot，它的位置依赖原生 DOM 锚点；锚点不可用时浮层会消失，未来有正式 DSH slot 时应迁移到该 slot。
+使用 DSH CLI：
 
-关于详细的领域模型、生命周期迁移、恢复保证与开发贡献流程，请参阅：
+```bash
+dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
+```
 
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 权威架构设计、生命周期与恢复不变量
-- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — 本地开发、测试验证与贡献指南
-- [docs/RELEASING.md](docs/RELEASING.md) — 发布参数与版本规则
-- [AGENTS.md](AGENTS.md) — Coding Agent 维护说明
-- [src/client/README.md](src/client/README.md) — 浏览器客户端集成与界面接缝
+如果使用 DeepSeek Harness checkout，可对同一个 package name 使用
+`pnpm dsh plugin --profile web remove`。
 
 ## 友情链接
 
-- [LINUX DO](https://linux.do/) — 新的理想型社区
+- [LINUX DO](https://linux.do/) — 新的理想型社区。