@cerbur/clutch-dsh-worktree 0.1.10 → 0.1.13

package/README.zh.md

@@ -1,501 +1,300 @@
+[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 元数据、原生列表和会话历史的唯一事实来源。插件只保存 Worktree/Session 的外部
-关系元数据。
-
-## 界面截图
-
-![中文 Worktree 侧边栏和新会话空白 Hero](assets/screenshots/screenshots-zh.png)
-
-中文截图展示了侧边栏中的 Worktree 模式、包含 Main 和 Worktree 行的 Workspace 树，以及
-新会话空白 Hero 中的只读上下文。
-
-![英文 Worktree 创建/导入弹窗](assets/screenshots/screenshots-import.png)
-
-导入截图展示了现有 Workspace `+` 弹窗：默认选中创建，旁边是导入 Tab，并在普通下拉框中
-使用安全的示例 branch 和路径值。
-
-## 能力
-
-- 从 DSH Sidebar footer 进入 Worktree 模式，按 Workspace → Worktree → Session 浏览会话。
-- 搜索 Workspace，并从已有 local branch 创建 Git Worktree 和 branch。
-- 在同一个弹窗中选择导入，发现与当前 Workspace repository 关联、尚未由 sidecar 管理且绑定 branch 的 Git Worktree。第一版不展示 repository root 和 detached HEAD 条目。
-- 导入只登记已有 Worktree，不移动、复制或编辑其目录；记录使用 `source: external`，之后与 plugin 创建的记录共享 Session、binding、health、排序、cwd、projection、刷新和恢复流程。
-- 非破坏性归档 Worktree（`status: removed`），保留磁盘文件、活动 binding 与运行时 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 或打开菜单时，右侧位置让位给已有的操作菜单。
-- 使用 DSH 原生 Session hover 详情卡片展示完整标题、相对时间和当前状态；打开 Session 操作
-  菜单或拖拽行时，详情卡片让位。
-- 补齐原生的等待审批、计划待审、等待回答、已完成、空闲和运行中子代理状态；插件不会复制
-  原生动画实现。
-- 当折叠的 Workspace、Main 或 Worktree 中存在任一未归档的活动 Session 时，在其右侧显示
-  一个原生运行指示器；展开后恢复普通操作栏。
-- 用户在 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，再在 binding
-  refresh 完成后加入浏览器本地 Workspace membership projection；child 仍然是普通 DSH Session。
-  这一时序避免 child 短暂出现在 Main/Local。sidecar 失败时 child 会保留，并显示可重试的
-  binding 恢复操作。
-- 查看 ready、repair、active 和 detached Worktree 状态，包括可重试的操作错误。
-- 通过 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径；Main 和 detached 行只显示“复制路径”，
-  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 或历史记录。
-- Worktree fork 的 membership 不会写入 DSH 持久化的 `Workspace.sessionIds`。plugin 加载期间，
-  浏览器可以通过本地 projection 显示 child；不加载 plugin 时，child 仍在 DSH 全局 Session 管理中，
-  但不会被持久化挂到 native Workspace root membership 下。
-
-### 兼容性与前置条件
-
-兼容性事实表如下：
-
-| 组件 / Component | 最低版本 / Min Version | 说明 / Notes |
-| --- | --- | --- |
-| DSH Client | `>=0.1.2-rc.1` | 依赖 Session/Workspace Controller 及 Client Store |
-| DSH Host | `>=0.1.2-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 指令。对于受管理的
+Worktree，插件还提供可选择本地 branch 基线的只读 Git 与变更 Dashboard；不会复制 transcript
+或改写 DSH Session。
 
-普通用户安装请使用 npm package。开发或验证本地源码时使用仓库 checkout；从市场条目安装
-源码 package 时使用 GitHub source path。
+> **预览：** Worktree Dashboard 是仅 plugin 提供的早期 MVP 预览版。Worktree 导航、生命周期
+> 操作、Session 操作、指令和受管理 Worktree 的 Git 与变更视图已经连接。派生 Worktree、设置和
+> 其他未完成操作仍标记为**即将推出**。
 
-### 从 npm 安装（推荐）
+## 安装
 
-在已经安装 DSH CLI 的环境中执行：
+### 从 npm 安装
+
+在已安装 DSH CLI 的环境中：
 
 ```bash
 dsh plugin --profile web add @cerbur/clutch-dsh-worktree
 dsh web
 ```
 
-如果使用 `deepseek-harness` 源码 checkout、系统没有独立的 `dsh` 命令，使用等价的转发
-形式：
-
-```bash
-cd /path/to/deepseek-harness
-pnpm dsh plugin --profile web add @cerbur/clutch-dsh-worktree
-pnpm dsh web
-```
-
-可以通过官方 registry 查看当前发布版本：
-
-```bash
-npm view @cerbur/clutch-dsh-worktree version --registry=https://registry.npmjs.org/
-```
-
-### 准备当前 upstream DSH checkout
+如果使用 DeepSeek Harness 源码 checkout 且没有独立的 `dsh` 命令，可使用等价的
+`pnpm dsh` 形式。
 
-进行源码开发或验证时，先准备 upstream checkout。当前 upstream 默认分支是 `master`；如果仓库
-未来切换默认分支，应跟随仓库的当前默认分支。最小 rc.1 兼容性验证路径切换到
-`dsh-v0.1.2-rc.1`：
+### 从本地 checkout 安装
 
-```bash
-git clone https://github.com/deepseek-ai/deepseek-harness.git
-cd deepseek-harness
-git fetch origin
-git checkout dsh-v0.1.2-rc.1
-pnpm install
-pnpm run build
-```
-
-### 从仓库 checkout 安装
-
-先从 `clutch-dsh` checkout 构建 package，再把绝对路径安装到 DSH profile：
+先构建本 package 和 DSH 源码 checkout，再用绝对路径添加 package：
 
 ```bash
-cd /path/to/clutch-dsh
+cd /absolute/path/to/clutch-dsh
 pnpm install
 pnpm --filter @cerbur/clutch-dsh-worktree build
 
-cd /path/to/deepseek-harness
+cd /absolute/path/to/deepseek-harness
 pnpm install
 pnpm run build
-pnpm dsh plugin --profile web add /path/to/clutch-dsh/packages/clutch-dsh-worktree
-pnpm dsh web --dump-config
-pnpm dsh web
-```
-
-`--dump-config` 输出中应包含该 plugin 的 bundle layer。如果 profile 中仍有旧的 unscoped
-安装，先移除：
-
-```bash
-pnpm dsh plugin --profile web remove clutch-dsh-worktree
-```
-
-更新本地 checkout 时，重新构建 package 并重启 DSH：
-
-```bash
-cd /path/to/clutch-dsh
-pnpm --filter @cerbur/clutch-dsh-worktree build
-cd /path/to/deepseek-harness
+pnpm dsh plugin --profile web add /absolute/path/to/clutch-dsh/packages/clutch-dsh-worktree
 pnpm dsh web
 ```
 
-修改 `package.json`、`cordis.patch.yml` 或 profile bundle 成员后，需要再次执行 plugin add
-命令。
+DSH Web profile 必须已经能够正常启动。修改 `package.json` 或 `cordis.patch.yml` 后，需要重新
+执行绝对路径安装命令。
 
-### 从 GitHub 源码安装
+### 从 GitHub 源码安装（可选）
 
-`awesome-dsh-plugin` 生成的源码路径为：
+DSH plugin market 使用的源码依赖形式也可以直接安装：
 
 ```bash
 dsh plugin --profile web add "github:Cerbur/clutch-dsh#path:/packages/clutch-dsh-worktree"
 ```
 
-这是源码 Git 依赖，不是预构建的 npm package。它的 `prepare` 生命周期会生成 `lib/`。当前
-DSH profile 使用 pnpm 11 的 `allowBuilds`：首次执行 Git 安装时，pnpm 会故意拒绝构建，并
-在错误信息中打印包含包名、Git URL、解析后的 commit 和子目录 path 的完整 key。将完整
-key 复制到 profile 的 `pnpm-workspace.yaml`，例如：
-
-```yaml
-allowBuilds:
-  '@cerbur/clutch-dsh-worktree@git+https://github.com/Cerbur/clutch-dsh#<resolved-commit>&path:/packages/clutch-dsh-worktree': true
-```
+该方式会在安装时构建 package。pnpm 构建脚本授权和本地开发细节见
+[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
 
-必须使用 pnpm 错误提示中打印的完整包 key：`<resolved-commit>`、Git URL 和 path 都必须与
-错误输出一致。对于直接 Git 依赖，只写包名不够；当前 pnpm 11 的 Git prepare 流程也不使用
-`onlyBuiltDependencies` 这一配置。保存授权后重新执行原安装命令；commit 变化后需要为新
-commit 增加对应的 key。该 allowlist 属于信任此 Git commit 的 profile 维护者，不要写入
-plugin package。
+## 功能
 
-授权后，Git prepare 会在 checkout 的 monorepo 中执行 `pnpm install`，再执行
-`pnpm run build`，因此 profile 必须能访问其配置的 registry。授权之后出现 registry DNS、
-镜像或 lockfile 错误，属于安装环境问题，不是 `allowBuilds` 拒绝。若要避免源码构建授权，
-请使用上面的 npm 安装方式。
-
-### 卸载
-
-```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 的只读 Git 与变更视图。派生 Worktree、设置和其他未完成卡片仍标记为**即将推出**。 |
 
-## 使用说明
+## 使用
 
 ### 打开 Worktree 模式
 
-1. 启动 DSH Web UI，在 Sidebar footer 选择 Worktree。Worktree 模式是附加界面，不会添加
-   独立的 Workspace/Worktree Tab。
-2. 使用 Workspace 树搜索、展开并选择 Main 或 Worktree 视角。每组默认显示五行，更多内容
-   使用 Expand more/Collapse。
-
-![使用 Worktree 模式时的侧边栏和新会话空白 Hero](assets/screenshots/screenshots-zh.png)
-
-上图展示了侧边栏入口以及新会话空白 Hero 中显示的视觉上下文。界面语言跟随 DSH 当前的
-语言设置。
+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
 
-新目录使用 `$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 或安装命令或编辑
-   业务文件。
+1. 打开 Local/Main 或 active Worktree 的选项菜单，选择 **Create Worktree**。
+2. 选择本地 base branch，也可以填写新的 branch 名称。
+3. 确认弹窗。插件会创建 Git Worktree，记录获取事实；从该 Worktree 打开 Session 时继续执行
+   正常的 Session 和 binding 流程。
+
+Git repository、本地 branch 和 initial commit 必须可用。如果仓库尚未准备好，DSH 会显示对应
+的 readiness 提示和可复制的 setup 指引。
 
 ### 导入已有 Worktree
 
-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` 流程；新建 Session 不会在 binding 刷新前投影到原生
-   Workspace membership。
-4. 同一 Workspace、同一物理路径的 active external 导入是幂等的。已经由 plugin 管理的路径
-   返回 `WORKTREE_ALREADY_MANAGED`；无效或过期候选项返回 `WORKTREE_IMPORT_INVALID`，修复
-   repository 状态后可以重试。
-
-### 创建 Main 和 Worktree Session
-
-- 使用 Main 的 `+`，在 Project 根目录视角中创建普通 DSH Session。
-- 使用 Worktree 的 `+`，创建或复用 runtime cwd 指向该 Worktree 的 Session。插件通过 DSH
-  Session Controller 调用 `ctx.sessions.create({ cwd: worktreePath })`，随后保存外部 binding
-  并打开该 Session。当前浏览器内的 `{ workspaceId, sessionId }` membership projection 会在
-  之后刷新，因此新建 Session 不会短暂出现在 Main 中。
-- 如果存在目标 cwd 完全匹配的未归档 blank Session，连接器会优先复用它。已绑定的 Session
-  会直接打开；未绑定的候选会先 binding，再 projection 和打开。否则执行
-  新建路径执行 `create → bind → open → refresh`，同一个 Worktree 的并发点击会合并。
-- 如果 DSH 创建 Session 后 binding 失败，Session ID 仍会保留，可用于 Retry 或 Open 恢复。
-  插件不会删除或修改该 DSH Session。
-- 打开 active Worktree Session 前，插件会在 DSH 风格的页面内弹窗中说明关联 Git 元数据为什么
-  可能需要访问 Session 目录之外的内容。弹窗要求明确勾选风险确认；取消会保留 Session 和
-  binding，不改变权限，并留下可重试的待处理状态。需要切换到其他权限模式时，继续使用 DSH
-  原生 Access 选择器。
-- provisional blank Session 遵循 DSH 原生显示规则：只在当前选中的视角中显示，使用本地化
-  的 `New Session` 文案，不显示生成的 ID，也没有 Rename、Fork 或 Archive 菜单。接受第一条
-  prompt 后，它会变为普通 Session 行；隐藏 blank 行不会删除 Session 或 Worktree binding。
-
-### 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 入口：Session list 中的 tab、Worktree Session 菜单或
-  Conversation fork 操作。插件包装共享的 DSH `sessions.fork` service，因此原生的 fork cut、
-  标题递增和 child lineage 语义保持不变。
-- DSH 创建 child 后，插件读取 parent 的 active sidecar binding，通过现有 `/api` Manager 写入
-  child binding。随后 Worktree view 先刷新 binding，再重放浏览器本地 Workspace membership
-  projection，因此 child 不会短暂出现在 Main/Local；刷新期间保留 ready 内容。
-- 如果 child 已创建但 sidecar 查询或 binding 失败，DSH 仍保留 child，plugin 显示 Retry Binding/
-  Open Created Session 恢复操作。后续 plugin 初始化也会根据原生 Session lineage summary 重试可恢复
-  的 fork child；不会自动绑定无关的 subagent。
-- 这一流程不会把 child 持久化写入 DSH `Workspace.sessionIds`。native DSH Workspace view 只有在
-  plugin 加载期间才能看到临时浏览器 projection；native Workspace 持久化数据保持不变。
-
-### 排序与管理 Worktree
-
-- 在所属 Workspace 内拖动 Worktree。排序持久化在 plugin sidecar 的有序 `worktrees` 数组中；
-  Main 是固定的第一行，Worktree 不能跨 Workspace 移动。
+1. 选择 Workspace，打开它的 `+` 操作，然后切换到 **Import**。
+2. 从 branch 和 path 列表中选择候选项。
+3. 选择 **Import Worktree**。插件会原地登记已有目录，不移动、复制或修改其中的文件，随后
+   使用与新建 Worktree 相同的 Session 流程。
+
+第一版只列出尚未被插件管理、状态 ready、绑定 branch 且不是 repository root 的 Git Worktree。
+Detached、bare、prunable、缺失或无效条目会被省略。导入的 Worktree 仍可在选择本地基线 branch 后
+使用 Git 与变更。
+
+### 创建并打开 Session
+
+- 在 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 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
+必须安装在浏览器所在机器上且能够访问记录的路径；链接不会验证应用是否成功启动。
+
+### 使用 Git 与变更
+
+从受管理 Worktree 的 Dashboard 打开 **Git 与变更** Tab。对于持久化 `baseBranch` 存在且不同于当前
+branch，或带有作为隐式基线的获取 commit 的 managed Worktree，Overview 会通过现有 `/api` Connection
+做一次轻量、按需的 Git 状态读取，分别展示 ahead/behind commit 数量、已提交（基线到 HEAD）和未提交
+（当前工作区）的文件行数。这是临时 projection，不是 watcher，也不会写入 Worktree 记录。Main、不可用
+或未选择基线时会诚实显示 **待接入**。
+打开 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。
+在有效基线加载后，Git 与变更 Tab 初始会选择**基线汇总**，而不是第一个 commit；切换基线 branch
+也会回到该汇总。需要更窄的查看范围时，再选择 commit 或**未提交的改动**。
+
+所选 branch 每次读取都会重新解析。浏览器只能选择普通的本地 branch 名，不能直接选择 commit SHA 或
+任意 Git ref：完整 ref 路径、tag 或 remote-tracking ref 会被直接拒绝，而已选 branch 不复存在时会显示
+诚实的不可用状态，而不是泛化的 Git 失败。`baseCommit` 是不可变的获取元数据，永远不能由用户直接选择，
+并在没有可用已保存 branch 基线时作为隐式基线；创建恢复也绝不会改写它。当 Worktree 存在 staged、
+unstaged 或 untracked 文件时，列表顶部会加入**未提交的改动**；选择它会将当前工作区与 `HEAD` 比较，
+并使用相同的变更文件和 Diff 视图。
+
+**基线汇总**是一个独立的目标，默认展示从所选 branch 与 Worktree `HEAD` 的共同先祖到本次请求
+捕获的 `HEAD` 的净已提交树差异（无共同先祖时改用两个 branch head）；不包含工作区未提交改动。
+打开 **包含工作区改动** 后，该目标会改为展示从同一比较边界到当前工作区的一次净差异，其中包含已提交、
+staged、unstaged、untracked、删除和重命名改动。这是按需读取的新鲜 projection，而不是简单拼接两段
+Diff。点击 commit 会展示该 commit 自己的 Diff；打开提交栏标题中的**多选提交**开关后，可以同时选择
+多个已提交行，查看这些 commit 各自 first-parent delta 的精确并集。该开关默认关闭，关闭时会把已选
+集合收敛回当前聚焦的 commit。变更文件会记录贡献它的
+commit；每个所选 commit 会作为独立 Diff segment 展示，不会隐式扩展成范围，也不会包含未选择的
+commit。变更文件栏标题会展示当前目标（基线汇总、所选 commit 或未提交改动）对应的绿色 `+N` 和红色
+`-N` 总行数；仅包含 binary 时显示未知。未提交改动 entry 与已提交的多选互斥。汇总 Diff 工具栏中的
+**在侧栏打开**会使用当前 Session 在原生右侧栏中显示当前文件，但前提是该 Session 属于 Dashboard
+对应的 Worktree。空 Worktree 或无关的当前 Session 不会通过此操作打开文件。
+
+历史最多展示 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 控件。插件会依据所选 branch 到 `HEAD` 的 projection 验证
+commit，并依据最新状态重新读取和授权工作区 path，因此这些 endpoint 不是通用 Git object 或文件读取器。
+刷新会在替换数据加载期间保留 ready 内容；旧 commit 或文件选择的迟到响应会被忽略。
+
+### 添加 Worktree 指令
+
+在 Dashboard 的指令卡片上使用 **Edit** 保存或清空共享指引，长度上限为 32,000 个 UTF-16 代码
+单元。存在 active binding 时，下一次模型请求会通过 DSH pre-step hook 收到独立的
+`<system-reminder>` 上下文条目。
+
+指令保存在 plugin 自己的数据中，不会写入项目目录或 `AGENTS.md`。清空、解绑、归档、清理或移出
+管理后，后续请求不再注入；指令消息仍可见时，不变的指令不会重复追加。
+
+### 归档或移除 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 |
+
+## 行为与限制
+
+- 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 固定在第一位。
-- 打开 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径。active Worktree 提供“复制路径”与
-  “归档 Worktree”。归档 active Worktree 属于内部归档操作：将其标记为 `status: removed`，完整保留
-  磁盘目录、关联 binding 与运行时 cwd，并将该 Worktree 沉底移动到工作区底部的“已归档”（Archived）分组中。
-- 工作区底部在存在已归档 Worktree 时渲染“已归档”分组，默认处于折叠状态；标题显示已归档 Worktree 总数，收起时仍然显示。每个 Workspace 维护独立的折叠状态。
-- `health: repair` 的 active Worktree 也提供“归档 Worktree”，仅归档记录，保留磁盘文件和 binding。`recovery-needed` 状态仍须先处理恢复问题，不能归档。
-- 对于未清理磁盘的已归档 Worktree，选项菜单提供：
-  1. “取消归档”（Unarchive Worktree）：对于仅元数据标记归档且磁盘未清理的 Worktree，可直接在菜单中点击取消归档，无需二次确认弹窗，立即恢复为活跃状态。
-  2. “清理磁盘”（Clean Up Disk）：弹出二次确认弹窗（明确提示工作树路径与破坏性删除不可逆），告知插件不核验 Session/子代理活动，
-     请用户自行确认使用该目录的任务均已停止，否则删除可能导致任务失败或数据丢失；执行真正的非强制 `git worktree remove`，
-     成功后记录 `diskCleanup: completed`，运行时健康状态投影为 `cleaned`，关联 binding 转为 detached，并将完全访问权限
-     归一化为 `workspace-write + ask`。磁盘清理提交与权限后续解耦：清理成功即确认提交、关闭对话框并将状态转为 `cleaned`；
-     权限归一化失败或刷新异常提供独立恢复，不重复执行磁盘删除。
-     点击权限提示中的“重试”（Retry），仅重试该已清理 Worktree 的权限归一化。
-     如果 Worktree 目录或其 `.git` 入口已在外部删除，确认清理只将插件记录标记为完成并将 binding 转为 detached，
-     不再执行 Git 删除，也不清理残留 Git registration。剩余目录和文件完整保留，完成状态显示
-     “Worktree 已移除”，不代表剩余文件已被删除。普通刷新仍显示 `repair`，直到用户显式确认清理。
-  3. “移出管理”（Remove from Management）：弹出确认弹窗，删除该 Worktree 的 sidecar 记录与全部关联 binding，完整保留
-     磁盘文件与 DSH 原生 Session；同时定向淘汰该 Worktree 的未决 fork 恢复、投影与权限提示。不需要校验 Session 活动。
-- 对于已清理磁盘的 Worktree（`health: cleaned`），选项菜单提供“移出管理”以从 sidecar 中彻底移除该记录。
-- 删除 Workspace 只会删除 DSH 的 Workspace registration；其目录、Session、Git Worktree 和 plugin sidecar 会保留。
-- DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单继续可用。Session 拖动排序
-  限定在当前视觉 Main 或 Worktree 分组中。
-- Main 分组显示当前 local branch：有分支时为 `本地（branch）`，DSH 没有返回当前分支时
-  回退为 `本地`。如果导入的 Workspace 是 Git 仓库中的子目录，会先解析 Git 根目录，再
-  复用与 Git 根目录相同的 branch/worktree 信息。branch 名称、路径、Workspace 名称、Session
-  标题以及原始 DSH/Git 错误信息保持原值。
-- 已有 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 内容。
-旧版非事务分支观察标记会自动淘汰，普通 checkout 漂移不需要手工编辑 sidecar JSON。
-
-### 理解状态与恢复提示
-
-- 操作、权限、绑定和刷新失败统一使用 DSH 原生 toast，逐条显示；相同错误不会随每次渲染重复提示。
-  toast 消失后，完整信息及原有重试/打开操作仍保留在可展开的“提示详情与恢复操作”入口。
-  表单校验和 Workspace Git 初始化指引保留在对应输入附近。
-- 悬停或聚焦 active Worktree 行可查看状态、路径以及目录/Git 登记缺失、分支漂移/分离 HEAD、
-  恢复未完成的处理指引。打开菜单或拖动时不显示 hover 卡片。归档确认明确说明插件创建及外部
-  Worktree 都保留目录、Session 绑定和 cwd；“清理磁盘”仍是独立操作。
-
-- 没有未完成 Git 事务时，目录缺失的 active 或 archived Worktree 保持 `repair`，可归档，
-  不会阻断健康 Worktree 的 Session 绑定。指向现有且未清理记录的旧版无事务
-  `WORKTREE_RECOVERY_REQUIRED` 观察标记在 sidecar 锁内淘汰；未完成事务、未知记录和身份变化问题仍然阻断操作。
-
-- `ready` 表示 Worktree 可用。`cleaned` 表示磁盘清理已完成且保留 sidecar 归档条目。
-  `repair` 表示 Worktree、Session、binding 或 cwd 缺失/无效。`recovery-needed` 表示 Git/sidecar
-  操作或身份校验尚未解决，破坏性操作会被阻止。`detached` 表示 Git Worktree 已被移除，但关系仍然保留。active binding 指向缺失
-  Worktree 时会显示明确的 repair 警告或错误，不会静默切换到其他 Worktree。
-- Worktree health 是 Git 的运行时 projection，不写入 sidecar。Git 前置条件失败按
-  Workspace 显示提示：Git 可执行文件缺失时显示安装提示且不显示命令块，缺少 repository、
-  初始 commit 或本地 branch 时显示可复制的 setup 命令。Connection、Gateway 和未预期的
-  Worktree domain 错误会保留为可重试错误，不会伪装为空列表。
-- 已经 ready 的视角刷新时会保留当前 projection，直到替换数据可用。同一个 Session 的
-  snapshot 更新不会清空上下文，也不会触发重复读取；没有缓存视角时，首次进入和显式 Retry
-  可以显示 loading 状态。
-- 权限状态会明确显示为完全访问、回退到 `workspace-write`、保留用户限制、能力未验证、
-  等待确认或可重试的设置失败，不会静默折叠为空列表或伪造成功。
+- 将 Workspace、Main 和 Worktree 的展开选择保存到浏览器本地存储；Session 五行溢出展开保持临时状态，并在刷新或父级折叠后重置。**Collapse All** 会折叠其他无关节点并保留当前 Session 所在的 Workspace 与 Worktree 展开。
+- 当前 Session 不在可见树中时，会高亮匹配行并临时展开定位；如果行已在可见区域内，不会移动导航滚动位置，否则只移动足够显示它的位置。且不改变已保存的展开选择。
+- Git Dashboard 的读取由 Host 通过 DSH 现有 `/api` transport 执行。浏览器不会执行 Git、读取
+- 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 上限。
+- Git 必须已安装且可在 PATH 中使用。Git 可执行文件缺失时显示安装提示且不显示命令块；插件
+  不会执行 setup 或安装命令。
 
 ## 界面语言
 
-Worktree 模式跟随 DSH 当前界面语言。语言偏好由 DSH 管理；插件不增加独立的语言设置。
-Worktree 入口、Workspace → Worktree → Session 树、菜单、弹窗、状态和重试提示均提供中文
-和 English 文案。
-
-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 活动仅用于信息展示，不阻断磁盘清理或移出管理；默认 Host 仍可能显示 `unknown`。
-确认磁盘清理前，请自行停止所有使用该目录的任务，插件不会核验任务是否已停止。
-原生活动变化或重新打开归档菜单会刷新所属 Workspace 并保留 ready 内容。
-
-sidecar 兼容读取 v1、v2 和 v3 snapshot。旧记录会先在内存中归一化，第一次成功 mutation 会
-以原子方式将 shard 升级为 v4。旧 removed 记录归一化为 `diskCleanup: completed`，保留 v3 revision。
-新的 v4 snapshot 使用 revision、不可逆向还原的 repository
-fingerprint，以及为 Git create/remove 保存的 durable pending-operation metadata。早期 v3
-实现可能写入的 raw repository 字段也可以读取，并会在下一次稳定写入时清理。无效 JSON、
-未知 schema version 和关系不变量错误都会报告为 corruption，不会静默重置为空索引。
-
-一个 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 元数据。
-
-创建 Worktree 时先创建 Git Worktree，再记录外部关系。Git create/remove mutation 会按
-Workspace 和 repository 串行化跨 Host 进程执行，写入 durable pending operation，并在确认
-实际 Git 结果后才发布稳定 sidecar 状态。如果 create 无法对账，或 path/repository identity
-发生变化，操作会明确保留为可恢复状态；插件不会使用 force remove，也不会删除未知目录。
-sidecar 写入失败时会尽可能清理刚创建的 Git Worktree。删除 Worktree 失败时不会静默改变
-关系，因此关系仍可重试，或会标记为 `recovery-needed`。创建 Session 时先调用 DSH 原生
-API，再写入 binding；binding 失败不会删除或修改已创建的 Session。
-
-Host 启动时，插件会针对已知 DSH Workspace 执行一次尽力而为的安全恢复。只有在 Git path
-和 repository identity 都能确认时，才会完成 pending create/remove；否则保留 marker，并
-显示 `WORKTREE_RECOVERY_REQUIRED` 或 `WORKTREE_IDENTITY_CHANGED`。它不会猜测性清理破坏性
-状态。破坏性操作还可以携带最新 Worktree projection 生成的 opaque mutation token，避免
-过期 UI 对已变化的记录执行操作。
-
-Worktree Session 流程将独立的 Worktree cwd 交给 DSH Session Controller，并将
-`{ workspaceId, sessionId }` 保持为浏览器本地 membership projection，而不是持久化的 DSH
-attach。它不会修改 DSH 源码、Session metadata 或原生 Workspace 存储。native list 刷新后会
-重放 projection；binding 消失或 Client dispose 时会移除 projection。
-
-权限变更只使用 DSH 公共的 per-Session 权限服务及其 `permission/preset`、`sandbox/mode`、
-`approval/policy` 记录。插件不会写入消息、prompt、transcript、Workspace 数据或 Session
-metadata，也不能扩大运行 DSH 的宿主沙箱边界。
-
-空白 Hero 上下文只用于展示。由于当前 upstream DSH source checkout 没有 additive Hero
-headline slot，它的位置依赖原生 `[data-phase="hero"]` 和标题锚点；锚点不可用时浮层会消失，
-未来有正式 DSH slot 时应迁移到该 slot。
-
-## 开发与验证
-
-从 workspace 根目录执行：
+常用的 package 检查命令：
 
 ```bash
-cd /path/to/clutch-dsh
-pnpm install
-pnpm run check:workspace
-pnpm run check:patches
 pnpm --filter @cerbur/clutch-dsh-worktree typecheck
 pnpm --filter @cerbur/clutch-dsh-worktree build
 pnpm --filter @cerbur/clutch-dsh-worktree test
 ```
 
-验证双语 README contract 和格式：
+中英文 README 的结构通过以下测试校验：
 
 ```bash
-cd /path/to/clutch-dsh/packages/clutch-dsh-worktree
 node --test test/readme-parity.test.mjs
-pnpm exec prettier --check README.md README.zh.md test/readme-parity.test.mjs
 ```
 
-完整 workspace 检查为：
+## 卸载
+
+使用 DSH CLI：
 
 ```bash
-cd /path/to/clutch-dsh
-pnpm run check
+dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 ```
 
-不要提交生成的 `lib/`、coverage、sidecar 数据或本地凭据。数据边界和生命周期规则见
-[AGENTS.md](AGENTS.md)，版本与安装来源见 [docs/RELEASING.md](docs/RELEASING.md)，浏览器
-Consumer 边界见 [src/client/README.md](src/client/README.md)。
+如果使用 DeepSeek Harness checkout，可对同一个 package name 使用
+`pnpm dsh plugin --profile web remove`。
 
-## 插件市场描述
-
-向 `awesome-dsh-plugin` 投稿时使用 `git` 分类，并保持描述与 package 一致：
-
-```yaml
-category: git
-description:
-  en: Adds a Worktree view to DSH Web UI that groups Sessions by Git worktree while keeping DSH as the source of truth.
-  zh: 为 DSH Web UI 增加按 Git Worktree 组织 Session 的视角，同时继续由 DSH 管理原始 Project/Workspace 和 Session 数据。
-```
+## 友情链接
 
-市场投稿还需要在外部确认 `dsh-plugin` topic、仓库年龄和提交数等信息；这些外部属性无法
-由 package README 设置。
+- [LINUX DO](https://linux.do/) — 新的理想型社区。