dsh-at-sider

简体中文 | English

给原生侧边栏文件树补上「@ 引用 + 修改时间」：不换标签页、不改入口、不重绘图标—— 右侧栏的文件标签页还是原生那一个（同一 Mod+P、同一引导页胶囊、同一套图标与打开方式），只是每一行多了一个紧跟文件名的 @文件 引用按钮，和行尾固定的 修改时间。

🚀 安装（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）。自检三步：

鼠标移到任意一行上 → 文件名右侧出现 @文件（目录为 @文件夹）；
每行最右侧显示 2026-01-02 11:04 这样的修改时间，悬停可见完整本地时间；
点 @文件 → 输入框里出现该文件的 @引用（按住 Alt/⌥ 点击则改为复制引用文本）。

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

功能

行内元素	行为
`@文件` 按钮（目录为 `@文件夹`）	把 `@路径`（含空格时 `@"路径"`，目录为 `@目录/`）作为原子文件引用插入当前会话输入框 —— 与内置 `@` 补全、内置拖入文件生成的引用完全一致。输入框不可达时自动降级为复制该引用文本。平时只在该行悬停/聚焦时出现。
`@文件` + Alt/⌥ 单击	始终复制引用文本到剪贴板。
修改时间列	本地时间 `YYYY-MM-DD HH:mm`；悬停显示完整本地时间。stat 失败的条目该列留空。
大小列	常规文件显示人性化大小（`870 B`、`1.5 KB`、`1.2 MB`）；时间 tooltip 一并给出，大小列悬停显示精确字节数。
排序	页头按钮循环按名称 → 按修改时间 → 按大小 → 按类型；目录始终在前，缺字段的条目沉底，偏好会记住（localStorage，尽力而为）。
自适应列	树体自测宽度分三档：≥380px 全列；300–379px 隐藏大小列； { ok: true, value: { path, root, entries: [{ name, type, mtimeMs, size? }], truncated } }


列表被限制在会话工作区根内（请求路径先对根解析，越界即拒绝），每层最多 2000 条，`stat` 并发上限 32，且只做只读列表（绝不读取文件内容）。完整的取舍记录与被否决的替代方案见 [docs/DESIGN.md](https://github.com/aiyacharley/dsh-at-sider/blob/0eedb4c722cc872369dd4b12cb9e4e0e62535935/docs/DESIGN.md)。

---

## 已知限制

- 内置 `files` body 是被**遮蔽**而非组合：本插件加载期间原生树不渲染；卸载后**原样恢复**（本插件不修改任何原生代码）。
- 修改时间来自 `node:fs`（`ctx.fs` 不暴露时间字段），位于其策略缝之外；该路由因此自带工作区包含性校验。
- Client 半镜像了原生树的少量私有细节（行序、`dsh-resource://` 地址文法、输入框引用插入调用）。每处都有降级路径（输入框不可达则退化为复制；watch 不可用则退回手动刷新）；构建与测试所依据的版本写在 `package.json` 的 `dsh.compatibility`。
- 插件自带的简单字形只在宿主图标不可用时兜底，正常环境下不会出现。

---

## 安装与卸载（完整）

### 安装

**1. 一条命令（官方 CLI，推荐）**

```bash
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

2. 复制粘贴给 Agent 自动安装：

【请帮我持久化安装 dsh-at-sider（重启后所有会话可用）】
1) 确认 DSH profile 名称（如 web；不确定就先问）。
2) 运行 dsh plugin --profile  add dsh-at-sider@latest。
3) 提示用户重启 DSH web（Host 半的列表路由需要重启才注册）。
4) 重启后自检：右侧栏「文件」标签页悬停任意行应出现 @文件，行尾应显示修改时间。

3. 手动（可选）

profile 的 bundle 层：在 ~/.dsh/profiles//package.json 的 dependencies 加 "dsh-at-sider": "link:/path/to/dsh-at-sider"，并把 "dsh-at-sider" 加进 dsh.profile.bundles，再 pnpm install → 重启；
或直接把 cordis.patch.yml 的 insert 行并入自己的 patch 层 → 重启。

更新

dsh plugin --profile web update dsh-at-sider@latest     # 或 @0.0.2 指定版本

更新后重启 DSH 生效。

卸载

一条命令：dsh plugin --profile web remove dsh-at-sider → 重启；
本地 link 安装：从 profile 的 package.json 删掉依赖与 dsh.profile.bundles 里的条目，再 pnpm install → 重启；
卸载后原生文件树原样恢复。

排查（装了却没变化、时间列为空等）见 docs/INSTALL.md。

开发与测试

npm test          # node --test，65 个用例，全离线（无网络、无浏览器）

本插件无依赖、无构建：client.js 就是浏览器模块加载器格式的最终产物，index.js 就是 Host 端入口；
测试按模块系统的实际加载方式载入 client.js（在 new Function 中注入 window、navigator、fetch），并用极小的 React shim 驱动真实组件：包含性校验、每层列表与 mtimeMs、路由契约、接管定义、@路径 文法与资源地址、输入框插入与剪贴板降级、按钮标签、宿主图标路径与其兜底、行盒模型，以及整棵树的渲染冒烟；
变更说明见 CHANGELOG.md，设计取舍见 docs/DESIGN.md，发布流程见 PUBLISH.md。

版本历史

v0.1.0 — 首个功能版本：运行时回退原生（右键「文件」页签，在增强树与原生树之间切换，无需卸载）；快速过滤/定位（页头搜索框全工作区递归搜索——跳过 node_modules/.git、上限 200，结果带 @ chip，点文件打开、点目录回树展开）；在文件树中定位（右键文件预览页签，自动展开祖先并高亮该行）；预览页签一键 @文件（右键文件预览页签直接插引用）；键盘导航与 a11y（↑↓/←→/Home/End/@、roving tabindex、role=tree 语义）；65 个离线测试。
v0.0.4 — 修复重启后恢复的文件 tab 显示"没有工作区目录"需手动重读（Host 冷会话经 sessionPersistence 兜底解析根目录；失败层级自动重试自愈，最多 2 次）；大小列布局细化（右对齐定宽 + 与日期两格间距，整组右钉）；52 个离线测试。
v0.0.3 — 新增大小列（人性化字节 + 精确 tooltip）、排序（名称/修改时间/大小/类型循环，目录恒在前，偏好记忆）、宽度自适应列（≥380px 全列 / 300–379px 隐大小 / 逐版提交细节见 git tags；设计文档见 docs/DESIGN.md；路线图（已完成/计划/里程碑）见 docs/ROADMAP.md。

要求

DSH 0.1.7-rc.2（web profile），已在 version 上实测（package.json 的 dsh.compatibility 声明）
Node.js ≥ 20（Host 半使用 node:fs/promises）

License

MIT，见 LICENSE。

文件类型判定与图标（FileTypeIcon、classifyFileType、IconFolder*Regular、GuideArtworkFiles）来自 DSH 自带的 @deepseek-ai/dsh-client-ui-primitives，运行时读取、不做复制；插件自带的简单字形仅在其不可用时兜底。
tab 接管、@路径 引用、修改时间列表与 /api 列表路由为本插件原创实现。

安装

说明文档

dsh-at-sider

目录

🚀 安装（2 分钟上手）

功能

更新

卸载

开发与测试

版本历史

要求

License