@wannanbigpig/dsh-sidebar

安装与使用

从 npm 安装预构建包（无需克隆宿主源码或本地构建），加入某个 DSH Profile：

dsh plugin --profile workbench add @wannanbigpig/dsh-sidebar
dsh --profile workbench --dump-config
dsh --profile workbench

安装后：

1. --dump-config 输出中出现 # == @wannanbigpig/dsh-sidebar 即注册成功；插件只插入自身服务行，不覆盖宿主既有配置。
2. 从宿主 Right Sidebar 的“文件”入口浏览项目；点击文件后会在原生资源标签中直接使用插件编辑器。
3. 宿主 + 打开的 Guide 会列出文件、Review 与 Terminal；选择内容后 Guide 被原位替换，不额外保留一套插件“开始”页。会话右上角的 Git 工具浮在当前会话列内，“更改”打开原生 Review；终端在输入框下方的宿主 Dock 打开。

使用须知与已知限制

文件与编辑

• 只允许读取和保存已存在的普通文件；不提供删除、重命名、创建文件，也不提供 git reset、git checkout -- 或强制切换分支。
• 未配置语言模式的文件回退为纯文本；文件大小默认上限 8,000,000 字节（可通过 maxFileBytes 配置），超过 400,000 字符时跳过语法解析以避免大文件卡顿。当前未接入语言服务补全、诊断或代码折叠。

Git 与 Worktree

• 审查的“分支”范围以工作树与所选基准（含未提交/未跟踪文件）对比，参数契约以当前核对的最新宿主为准。
• 新建 worktree 以 Git 主工作树为基准，在仓库同级创建持久目录和独立分支；插件不自动删除、prune 或清理它们。
• Session 的 cwd 是不可变元数据。切换工作树会打开目标路径已有 Session 或创建新 Session；未提交更改保留在原工作树，不会自动 stash 或搬运。
• Git 工具卡和分支菜单依赖宿主公开的 Git 状态接口；工作区不可读时会显示错误而不是空白。

终端与宿主打开方式

• PTY 使用宿主公开的持久终端原语；宿主不支持 resize 时终端仍可用，但依赖动态行列的全屏 TUI（如 vim、htop）可能无法正确重排。
• 终端跟随宿主明暗主题；插件无法读取 Terminal.app 或 iTerm 的私有主题配置，prompt 与输出中的 ANSI 颜色原样保留。
• 顶部 Open In 菜单由宿主统一提供并作用于 Session 工作区；插件不再提供直接用外部应用打开当前文件的第二套菜单。

宿主版本

• 当前代码只面向核对基线 c291e7961a515f6d7af9304e7fd1d257929aef26（0.1.5-rc.2）的最新宿主源码，不保留旧版宿主兼容分支，也不替换宿主 Right Sidebar 或 Files 组件。Git 浮层使用 Portal，并按当前会话区域重新计算锚点。
• 宿主 + 的公开契约固定新建 Guide，插件不拦截或重写该按钮；插件把 Review/Terminal 作为 Guide 条目注册，用户选中内容后再原位替换 Guide。
• 宿主已公开统一的 FileTypeIcon 并在 Files 内原生使用；插件直接复用该组件，不再通过 data-files-* 选择器隐藏或覆盖宿主图标。图片和 PDF 由宿主原生 document preview 呈现，插件只接管可编辑的文本/代码资源。
• 插件自带预构建 Typert 描述符；运行时仅使用宿主公开的 Right Sidebar、Slot、Session、Remote、fs、subprocess 与 Client Module API。宿主缺少这些必需服务时插件不会激活。