dsh-at-sider

dsh plugin --profile web add dsh-at-sider

dsh-at-sider

简体中文 | [English](README_EN.md)



给原生侧边栏文件树补上六件事：@ 引用 · 文件大小 · 文件修改时间 · 排序 · 快速搜索定位 · 侧边栏底部 git commit 信息。

不换标签页、不改入口、不重绘图标——右侧栏的 文件 标签页还是原生那一个（同一 Mod+P、同一引导页胶囊、同一套图标与打开方式）：

- 每一行：紧跟文件名的 @文件 引用按钮 + 行尾的 大小 / 修改时间 两列（宽度自适应，永不裁切）；

- 页头：全工作区快速搜索（递归整个工作区，结果可 @、可跳转）+ 排序（名称/修改时间/大小/类型循环，偏好记忆）；

- 底部 git 栏：分支、领先/落后与最近提交摘要，点击向上展开最近 20 条提交；多仓库工作区可切换仓库，文件按状态着色（未跟踪/未暂存/已暂存）；

- 文件预览页签右键：一键 @文件 插引用、在文件树中定位（展开祖先并高亮该行）；

- 需要对照原生时，右键「文件」页签即可切回原生树（无需卸载，随时切回）——全键盘可操作。

---

目录

• [🚀 安装（2 分钟上手）](#-安装2-分钟上手)
• [功能](#功能)
• [交互与效果](#交互与效果)
• [键盘与无障碍](#键盘与无障碍)
• [和原生一致的部分](#和原生一致的部分)
• [实现要点](#实现要点)
• [已知限制](#已知限制)
• [安装与卸载（完整）](#安装与卸载完整)
• [开发与测试](#开发与测试)
• [版本历史](#版本历史)
• [要求](#要求)
• [License](#license)

---

🚀 安装（2 分钟上手）

前置：先装 Node.js ≥ 20，再全局安装 DSH CLI（推荐，装完直接用 dsh 命令）：

npm install -g @deepseek-ai/dsh
dsh web        # 启动 DSH web 环境（未全局安装也可临时用 npx @deepseek-ai/dsh web）

启动后，一条命令安装本插件：

# 一条命令安装（官方 CLI，推荐）
dsh plugin --profile web add dsh-at-sider@latest
# 或从 GitHub：dsh plugin --profile web add github:aiyacharley/dsh-at-sider
# 或本机源码：dsh plugin --profile web add /path/to/dsh-at-sider

装完重启 DSH（dsh web），打开右侧栏的 文件 标签页（或按 Mod+P）。自检三步：

1. 鼠标移到任意一行上 → 文件名右侧出现 @文件（目录为 @文件夹）；

2. 每行最右侧显示 2026-01-02 11:04 这样的修改时间，悬停可见完整本地时间；

3. 点 @文件 → 输入框里出现该文件的 @引用（按住 Alt/⌥ 点击则改为复制引用文本）。

零配置即可用；更多安装方式（Agent 代装、手动 patch、卸载）见文末[安装与卸载（完整）](#安装与卸载完整)。

---

功能

行内元素 · 行为

@文件 按钮（目录为 @文件夹） · 把 @路径（含空格时 @"路径"，目录为 @目录/）作为原子文件引用插入当前会话输入框 —— 与内置 @ 补全、内置拖入文件生成的引用完全一致。输入框不可达时自动降级为复制该引用文本。平时只在该行悬停/聚焦时出现。

@文件 + Alt/⌥ 单击 · 始终复制引用文本到剪贴板。

修改时间列 · 本地时间 YYYY-MM-DD HH:mm；悬停显示完整本地时间。stat 失败的条目该列留空。

大小列 · 常规文件显示人性化大小（870 B、1.5 KB、1.2 MB）；时间 tooltip 一并给出，大小列悬停显示精确字节数。

排序 · 页头按钮循环 按名称 → 按修改时间 → 按大小 → 按类型；目录始终在前，缺字段的条目沉底，偏好会记住（localStorage，尽力而为）。

自适应列 · 树体自测宽度分三档：≥380px 全列；300–379px 隐藏大小列；<300px 收起为 @ + MM-DD HH:mm——窄侧栏不再出现内容被裁切。

运行时回退原生（R10） · 右键「文件」页签 → 「回退原生文件树」：立刻切回原生树（不需要卸载插件）；同一条目变为「启用增强版文件树」，点它切回增强版。注意：Harness 页签没有 ⋯ 按钮，入口就是右键菜单；回退期间增强树的展开状态不保留，重启后默认增强态。

在文件树中定位（R16） · 右键文件预览页签 → 「在文件树中定位」：自动聚焦文件树、逐层展开祖先目录、滚动到该行并短暂高亮（与键盘选中框同款描边）。

预览页签一键 @文件（R16） · 右键文件预览页签 → 「@文件」：把当前预览文件的引用直接插入输入框——与在文件区点行内 @文件 完全同效，不用回文件树找该行。

菜单出现位置 · 上述两个条目都只在文件预览类页签的右键菜单出现；「文件」页签与其他页签的右键菜单没有。Harness 页签没有 ⋯ 按钮，所以入口统一是右键菜单。

Git 状态着色（R40a） · 文件行名字后有状态色点：未跟踪（绿）/ 有未暂存修改（琥珀）/ 已暂存（蓝），悬停说明；侧栏底部新增 git 状态栏：⎇ 分支 ↑ahead ↓behind · 最近提交摘要（相对时间），点击向上展开提交列表（最近 20 条，最底下是最新提交并带 ● 标记）。多仓库：工作区本身无 git、而一级/二级子目录是独立仓库时，状态栏会出现仓库下拉选择器——选哪个仓库就显示哪个的分支/提交与文件色点。无效仓库（.git 损坏/不完整）在选择器中显示为禁用项，状态栏提示「不是有效的 Git 仓库」而不消失。不在 git 仓库（或没有 git 命令）时零元素；状态随列表读取并缓存 30 秒。

图标 · 沿用宿主原生图标，未做改动：FileTypeIcon + classifyFileType（按文件类型着色）、线性风文件夹图标、引导页胶囊的 GuideArtworkFiles —— 与原生树绘制所用组件完全一致。仅当这些导出不可用时，才回退到插件自带的简单字形。

页头 · 工作区根路径（悬停见全路径）、自动刷新开关、重新读取按钮。

行序 · 目录优先，其后按名称自然序（大小写不敏感）—— 与原生树一致。

自动刷新复用 Harness 自带的 workspaceFiles.changes 目录监听：工作区内保存文件即刷新已展开层级，不做轮询。

---

交互与效果

📁 src          @文件夹   2026-01-02 11:04
📄 README.md      @文件    2026-01-01 09:12

• @文件 / @文件夹 平时隐藏，悬停或键盘聚焦时出现；单击插入引用，Alt/⌥ 单击复制；

插入/复制后短暂显示 已引用 / 已复制 / 失败（1.4 s），随后回到名词标签。

• 修改时间用定宽 YYYY-MM-DD HH:mm（不随 locale 抖动），tooltip 给出完整本地时间。
• 目录可逐层展开；重新打开会重新读取该层；展开状态与滚动位置按页签记忆——打开文件预览再回来、或运行时切回原生再切回，都保持原样（页面重载后从头开始）。

---

键盘与无障碍

先鼠标点任意一行让焦点进入树，之后全程键盘操作：

按键 · 行为

↑ / ↓ · 焦点在可见行之间逐行移动（跨层级连续）

→ · 目录未展开 → 展开；已展开 → 焦点进入第一个子行

← · 目录已展开 → 折叠；文件/子行 → 回到父目录行

Home / End · 第一个 / 最后一个可见行

Enter / Space · 目录 = 展开/折叠；文件 = 在侧栏打开

@ · 该行引用插入输入框

Tab · 一次即离开整棵树（roving tabindex，不会逐行走）

无障碍语义：根列表 role="tree"、行 role="treeitem"（带 aria-level / aria-expanded）、嵌套层 role="group"；搜索结果数量经 aria-live 播报。在文件树中定位时的高亮与键盘焦点框同款。

---

和原生一致的部分

• 标签页身份不变：仍是 files 类型 —— Mod+P 快捷键、引导页「工作区文件」胶囊、标签标题都来自同一处注册；
• 图标沿用原生：文件按类型着色的 FileTypeIcon、目录的原生线性风文件夹图标、引导页胶囊的 GuideArtworkFiles，全部在运行时读取宿主自己的组件，没有自绘复制；
• 打开方式不变：点行仍通过 dsh-resource://file/session/... 把文件开进侧栏；
• 行序不变：目录优先，其后按名称自然序（大小写不敏感），与原生树同一套排序。

---

实现要点

原生文件树没有 per-row 扩展点（行组件是模块私有的，该包也没有声明任何行内 slot），想要更丰富的行只能自己提供 body：以 extension 优先级注册一个同 kind（files）的 tab 类型即可接管 builtin，其 body/title 按定义自身的 id 分派，因此不存在 key 冲突。

修改时间在任何 Client 侧数据源里都不存在：workspaceFiles 的目录条目只有 { name, type, size? }，文件 version 令牌按契约不可解析。因此 Host 半自己提供两条受鉴权保护的路由：

POST /api/dsh-at-sider/list     { sessionId, path }
  -> { ok: true, value: { path, root, entries: [{ name, type, mtimeMs, size? }], truncated } }

POST /api/dsh-at-sider/search   { sessionId, query }
  -> { ok: true, value: { query, matches: [{ name, path, dir, type, mtimeMs, size? }], truncated } }

两条路由都被限制在会话工作区根内（请求路径先对根解析，越界即拒绝），只做只读访问（绝不读取文件内容）。列表每层最多 2000 条、stat 并发上限 32；搜索递归整个工作区，跳过 node_modules/.git、不进入符号链接目录、深度上限 12、结果上限 200，且只对命中项取 mtimeMs。

页面侧的另外三处机制：动作菜单（sidebar.right.tab.menu.item 列表 seat，条目拿到自己所在的 tab 与 dismiss）承载「回退原生」「在文件树中定位」「@文件」；运行时回退靠注销/重注册 tab 类型定义实现（注销后 builtin 立即恢复）；定位通过 openTab('files', { params: { reveal } }) 把目标路径交给文件树，body 依 tab.navigation.params 展开祖先链并高亮该行。完整的取舍记录与被否决的替代方案见 [docs/DESIGN.md](docs/DESIGN.md)。

---

已知限制

• 内置 files body 是被遮蔽而非组合：本插件加载期间原生树不渲染；卸载后原样恢复，或随时右键「文件」页签用「回退原生文件树」即时切回（本插件不修改任何原生代码）。
• 展开状态与滚动位置按页签记忆（模块级），预览往返与运行时切换都不丢；但层级数据不缓存（回到已展开层会重新读取）且页面重载后两者从头开始——完整迁移到 slot store 见 ROADMAP R30。
• Git 状态来自 Host 半的 git status/git log 子进程（30 秒缓存、单次调用去重、超时与输出上限）；不在 git 仓库时零元素。工作区是仓库子目录时按 --show-prefix 前缀映射；重命名记录以新路径为准。.git 存在但无效（如缺 HEAD）的目录在选择器中显示为禁用项并提示，不会让状态栏消失。
• 修改时间与搜索都依赖 node:fs（ctx.fs 不

…(truncated)