dsh-file-extras
DSH Web GUI 日常操作增强：工作区文件树行内显示大小与修改日期，右键下载 / 上传 / @ 到对话 / 复制路径 / 删除（走回收站，跨平台）；另有 ~/.dsh/commands/*.md 驱动的斜杠命令与输入框 ↑/↓ 历史指令回填。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-file-extras@0.3.0File Extras 以 dsh-file-extras 发布，当前版本为 0.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
DSH Web GUI 的日常操作增强插件。主体是在官方「文件」页（@deepseek-ai/dsh-client-ui-sidebar-files）上补右键菜单、行内元数据、多选与删除；另外收了两件与文件树无关、但同样天天要用的能力：文件驱动的斜杠命令与输入框 ↑/↓ 历史指令回填。
| 需求 | 现在的行为 |
|---|---|
| 覆盖默认浏览器右键菜单 | 在文件树内右键弹出自己的菜单（树外一律不接管，浏览器默认菜单照旧） |
| 文件右键 | 下载 / @ 到对话 / 复制路径 / 删除 |
| 文件夹右键 | 上传文件到此处… / @ 到对话 / 复制路径 / 删除 |
| 空白处右键 | 上传文件到此处… / 复制路径 / 刷新大小与日期 / 全选可见项（有选择时再加 清除选择 与 删除 N 项） |
| 文件大小 + 修改日期 | 行尾显示 1.2 KB · 2026-03-04 13:06:07，按字节自动选单位（B/KB/MB/GB/TB/PB，1024 进制） |
| 文件夹大小 + 修改日期 | 行尾显示 3 项 · 2026-03-04 13:06:07；只数第一级子级（readdir 一层，不递归） |
| 删除（文件夹 / 单文件 / 多文件） | 走 二次确认框（列出每一项是什么、多大、文件夹含多少内容）；默认移到回收站（可还原），「永久删除」藏在默认不勾的复选框后面 |
| @ 到对话（文件 / 文件夹） | 直接在当前对话的输入框里插一枚 @ 引用芯片，和用户自己敲 @ 选出来的是同一种东西 |
| 斜杠快速命令 | ~/.dsh/commands/*.md 一个文件一条 /命令，正文可带 $ARGUMENTS 占位符；改文件立即生效 |
| ↑/↓ 快速切换历史指令 | 输入框里按 ↑/↓ 像终端一样翻出本会话自己敲过的指令，Esc 退出 |
~/.dsh/commands/<名字>.md 一个文件一条全局斜杠命令，命令名就是去掉 .md 的文件名
（文法与注册表逐字一致：/^[a-z][a-z0-9_-]*$/）。
---
description: 审查当前工作区的代码改动
input-hint: 可选的补充说明
---
请审查当前工作区的代码改动，重点关注潜在 bug 和安全问题。
$ARGUMENTS
| 行为 | 说明 |
|---|---|
| frontmatter |
读 description（发现界面里的说明）与 input-hint（输入提示），其余键忽略但容忍 |
$ARGUMENTS | 换成用户敲在命令名后面的原始参数；没有这个占位符时正文原样发出 |
| 改文件立即生效 | 正文是每次调用时重新读盘的，不用重启 |
| 新增 / 删除文件 | 需要重启 dsh web 才反映（注册是启动时扫一遍目录） |
| 执行结果 | 正文作为一条普通用户消息交给 agent —— 与用户自己把这段话敲进输入框等价，不是系统注入 |
用的是官方 ctx.commands.register()（@deepseek-ai/dsh-commands），所以发现、补全、
command/run / command/done 生命周期事件全归官方。与 app 级命令（/goal 之类）重名时
只跳过这一条并告警，不会把其余命令一起带走。
这条能力移植自 dsh-command-md（同一作者，MIT）。
在输入框里按 ↑ 翻出本会话里自己敲过的指令，再按 ↑ 往更早走，↓ 往新的走。
第一次 ↑ 时当前草稿会存起来，一路 ↓ 翻回最新一条之后再按 ↓（或按 Esc）就原样还回来。
穿梭时输入框上方有一条 历史指令 … ↑↓ 3/12 · Esc 退出 的提示条。
| 键 | 接管条件 | 行为 |
|---|---|---|
↑ | 光标已贴在草稿最开头（或草稿为空） | 进入穿梭 / 往更早一条 |
↓ | 只在穿梭模式里 | 往新一条；已是最新时还回原草稿并退出 |
Esc | 只在穿梭模式里 | 还回原草稿并退出 |
| 任何真实输入 | 只在穿梭模式里 | 立即退出穿梭（beforeinput：打字 / 退格 / 粘贴 / 拖入 / 输入法） |
/、@ 候选菜单开着时 | —— | 一律不抢键（那里 ↑/↓ 是选候选） |
数据不是从聊天视图里抠的（那里只有已加载的一窗），而是走 host 半区的 RPC history：
它读 ctx.sessionQuery.readSession() 的完整事件日志，只挑 source.kind === 'user' 的真实用户指令
—— 所以「更早」那些也在，而 AGENTS.md、技能目录、定时提醒这类 agent.inject() 塞进去的系统上下文不在。
（实测一个真实会话：38 条 user/message 里只有 11 条 kind 是 user，其余 27 条是
time-context / runtime-context / skill-catalog / agent-instructions / compact-checkpoint / user-approval。）
回填用官方 inputActions.setDraft() 整条替换草稿：不碰编辑器内部，不自己实现输入框。
host 通道取不到历史时 ↑/↓ 完全不接管 —— 宁可这个功能静默失效，也不能让用户觉得键盘坏了。
这条能力移植自 dsh-message-jump 的 「输入框 ↑/↓ 历史消息穿梭」（同一作者，MIT）；该插件另一半的悬浮指令导航条没有收进来。
右键文件或文件夹 → @ 到对话，该路径就以引用芯片的形式进入当前对话的输入框（多选时一次插一批）。 只插入、不发送 —— 后面还要接着写字，替你按发送键是越权。
这里没有重新实现「对话里 @ 文件」：
ctx.conversation.input.for(actx).addFiles(...)，
和把文件拖进输入框走的是同一条路），所以序列化（模型看到的文本）、点击芯片在右侧栏预览、
草稿持久化、发送时展开，全部沿用官方行为；@ 补全的语法（@deepseek-ai/dsh-file-reference 的 formatFileMention）：
@src/index.ts、目录 @src/、含空格 @"my notes.txt"、含空格的目录 @"my docs/（引号故意不闭合，官方语法如此）；「当前对话」取 ctx.sidebarRight.mounted —— 官方对「主栏正在显示哪个会话」唯一的公开可观察量，
文件树本身也是按这个会话渲染的。拿不到会话、会话没被 retain、输入框正忙（正在提交）时都明确报错，不静默失败。
官方那棵树没有多选，本插件自己实现了一套，规矩和资源管理器一致：
| 操作 | 效果 |
|---|---|
| 普通单击 | 清空选择（并放行官方行为：文件打开、目录展开） |
Ctrl / ⌘ + 单击 | 切换这一行的选中态（拦下官方行为，不会顺手打开文件或展开目录） |
Shift + 单击 | 从锚点行到这一行整段选中（按可见行的 DOM 顺序） |
| 空白处单击 | 清空选择 |
| 空白处右键 → 全选可见项 | 一次选中当前树里所有可见行 |
Esc | 分层收：确认框 → 右键菜单 → 选择 |
选中态是填色 + 一圈内描边（只填色会跟 :hover 撞成一样）。右键落在已选中的行上时，菜单作用整个选择
（标题变成 已选 N 项，删除项变成 删除 N 项，多选时不再提供只能作用于单项的下载/上传）；
右键落在没选中的行上则把选择换成那一行 —— 不会出现「看着选中了 5 个，结果只删了右键的那一个」。
官方文件树的数据来自 workspaceFiles Remote 命名空间，它的类型面里只有 size，没有修改时间
（WorkspaceDirectoryListing.entries[].size / WorkspaceFileStat.bytes；version 是不透明令牌，
契约上明令 never parsed）。所以 mtime 只能由插件自己从 host 侧取。
host 半区在 ctx.webServer 上挂一条前缀路由 /dsh-file-extras：
POST /dsh-file-extras/stat —— Connection RPC 信封，批量取 大小 / mtime / 一级子项数量；POST /dsh-file-extras/history —— 某个会话里真实用户指令的全文列表（↑/↓ 回填的数据源）；GET /dsh-file-extras/download?root=&path= —— 流式回文件字节 + Content-Disposition；POST /dsh-file-extras/upload?root=&dir=&name= —— 请求体即原始字节，写进目标目录；POST /dsh-file-extras/remove —— 删除（RPC 信封），默认移入回收站，逐条独立结算。浏览器的右键菜单注册进 shell.overlay（框架级浮层，本来就在每一列之上、滚动容器之外），
历史回填提示条注册进 conversation.input.dock（输入框卡片上方那条整宽座位）。
斜杠命令与这两者都无关，走官方 ctx.commands.register()，不经过本插件的通道。
| 文件 | 作用 |
|---|---|
| index.js | host 半区：/dsh-file-extras 前缀路由（RPC stat / history / remove、GET download、POST upload）+ 扫描 ~/.dsh/commands/*.md 注册斜杠命令 |
| lib/commands-md.js | 命令文件的纯解析层：frontmatter、$ARGUMENTS、目录扫描（零依赖，可脱离 DSH 单测） |
| lib/trash.js | 跨平台「移入回收站」：Windows / Linux / macOS 三套后端；平台与家目录可注入，所以三套逻辑能在任意一台机器上实测 |
| lib/client.js | 浏览器半区：行内元数据 + 多选 + 右键菜单 + 删除确认框 + @ 到对话（shell.overlay）+ ↑/↓ 历史回填（conversation.input.dock） |
| cordis.patch.yml | loader 行（inject: [webServer, connection]） |
| package.json | dsh.bundle + dsh.client |
| scripts/selftest.mjs / scripts/dom-probe.mjs / scripts/trash-bin.mjs | 两层自检 + 回收站测试清理助手 |
dsh plugin --profile web add dsh-file-extras
或在会话里让 Agent 用 plugin_manager 的 install_bundle 指向本目录。
装完刷新一次页面（客户端 bundle 在插件激活时读入并缓存，改代码后需要重新激活才生效）。
无（无 Config 字段、无运行时开关）。可调参数都在源码顶部的常量里，每个都带注释。
connection.requestRejection()：Host/Origin 检查 + 浏览器签名 cookie 认证，
非本机页面与未认证请求拿不到任何数据；root 必须是绝对路径、存在、且不是盘符/文件系统根（否则「声明 root=C:\ 就能读全盘」）；..\..\x 会被压成 x），重名一律自动加序号 name (1).ext，从不覆盖已有文件；.part-<uuid> 再原子 rename，中途失败/超限不会在工作区留下半个「看起来正常」的文件；content-length 明显失控（>4 GiB）时提前挡掉。SHFileOperation（PowerShell 5.1 + Microsoft.VisualBasic），
Linux 走 freedesktop Trash 规范（~/.local/share/Trash/{files,info}），macOS 走 ~/.Trash。
回收站不可用时报错，绝不静默降级成永久删除 —— 用户自己勾「永久删除」才走 fs.rm。checkEntry 按目录项判定包含关系）。
Windows 上软链接不进回收站（DeleteDirectory 会顺着联接点递归），直接 fs.rm；
POSIX 上 rename 只搬链接本身，所以照常进回收站。data-fx-meta 属性，
文本靠 CSS ::after { content: attr(data-fx-meta) } 渲染。React 只 diff 它 props 里出现过的属性，
不认识的属性既不写也不删，所以标记不会被 reconciliation 抹掉。ResizeObserver 给树根打上
data-fx-narrow，时间戳换到名字下面一行 —— 宁可换行也不截断时间戳。
属性写入放在 requestAnimationFrame 里：换行会让行变高，直接在观察回调里改会触发
ResizeObserver loop completed with undelivered notifications。200 + 错误信封（rpc.call 把非 2xx 当传输失败，
读不到信封里的错误码）；download / upload 是字节通道，失败回真正的 4xx。fetch + response.blob()：那个写法要等整个文件
传完、并在页面里拼出一份完整副本之后 promise 才 resolve，大文件于是「点下去很久没反应」，
还要吃掉同等内存、最后再从内存写一遍盘。现在改成 stat 预检（毫秒级，失败能说清原因）+
<a download> 原生导航（字节由 host 直接流到磁盘，立即开始、内存零拷贝、无大小上限）。
上传同理：进度提示在传输开始前就弹出来，host 侧边收边写。ctx.conversation.input.for(actx).addFiles(refs, [])），本插件只做两件事：
从文件树里认出用户点了哪个路径、拼出和官方 @ 补全逐字一致的提及文本。
提及语法（引号规则、目录尾斜杠）是 formatFileMention 的复刻 —— 改它之前先对照
@deepseek-ai/dsh-file-reference 的 grammar，一个字都不能差：差一个引号，模型就会把带空格的路径拆成两段。history 只认 source.kind === 'user'。事件日志里 user 角色的消息有两大类：人工输入 /
steering，以及 agent.inject() 塞进去的系统上下文。后者的 source.kind 各自不同
—— 实测一个真实会话（38 条 user/message）里出现过 time-context / runtime-context /
skill-catalog / agent-instructions / compact-checkpoint / user-approval，
只有人工输入的 kind 恰好是 'user'（11 条）。判断写的是「等于 user」而不是「不等于某某」，
所以上游再加新的注入类型也漏不进来。
斜杠命令的 handler 也正因此才用 createUserMessage({ source: { kind: 'user' } }) 而不是
agent.inject() —— 那样它才会被当成「用户敲的指令」进历史。↑/↓ 只在能安全接管时才接管。编辑器是 Lexical 的 contenteditable（不是 textarea），
所以 ↑ 只在光标贴最开头时抢，↓ 只在穿梭模式里抢，候选菜单开着时一律不抢；
事件监听挂在 document 的捕获阶段 + stopImmediatePropagation()，才能先于 Lexical 的
root 监听和 React 的委托监听。退出穿梭靠原生 beforeinput（Lexical 的程序化 setDraft
不触发它，所以回填本身不会被误判成用户编辑）。@deepseek-ai/dsh-llm 是动态 import。这个包只在 DSH 自己的
node_modules 里，从第三方插件目录不一定解析得到；拿不到就只让这一条命令回 error，
不自己拼一个假的 UserMessage（那会绕过官方的 id / 冻结 / source 约定）。
同理，命令目录优先走官方的 @deepseek-ai/dsh-home-paths（认 $DSH_HOME），拿不到时按同一套优先级自己算。fs.rm / unlink / rmdir 落到内核的删除原语，
删掉就是删掉；真正「移入回收站」的在 Windows 上是 SHFileOperation（要在
<卷>:\$Recycle.Bin\<SID>\ 下写一对 $I（元数据）+ $R（数据）文件并登记进用户回收站索引，
手工挪文件进去没用 —— 没有 $I 边车，资源管理器列不出来也还原不了），在 Linux 上是
freedesktop Trash 规范，在 macOS 上就是 ~/.Trash。三套机制 Node 一个都不提供，
所以 lib/trash.js 自己实现：Windows 外包给 PowerShell 5.1 的
Microsoft.VisualBasic.FileIO.FileSystem（内部就是 SHFileOperation），
Linux / macOS 直接按协议搬目录、写 .trashinfo。node scripts/selftest.mjs # host 半区：假 ctx/req/res 驱动路由，47 个用例（真文件系统 + 三套回收站后端 + 命令文件解析）
node scripts/dom-probe.mjs # 浏览器半区：headless Chrome 里跑真实 lib/client.js，83 条断言
node scripts/dom-probe.mjs --shot out/ # 同上，另存浅色（多选+菜单）与深色（删除确认框）两张截图
selftest.mjs 里 Linux / macOS 两条回收站后端是注入平台与家目录后真跑的（不是 mock）：
在 Windows 上把文件搬进一个假的 ~/.local/share/Trash，再逐字校验 files/ 落盘、
info/*.trashinfo 的 Path= 能还原原路径、DeletionDate 格式、以及同名让位成 <名字>.2。
测试往真回收站扔的东西由 scripts/trash-bin.mjs 按快照差集清干净。
dom-probe.mjs 会把完整结果写到 .npm-cache/domprobe/last-result.json，断言消息只留 300 字摘要。
复选框那几步走的是 CDP 的真实鼠标事件（合成事件驱动不了 checkbox 的激活行为，详见脚本内注释）。
selftest.mjs里「handler 把正文当用户消息交给 agent」那一条需要解析到@deepseek-ai/dsh-llm（只有装到 profile 之后才在 node_modules 链上）。 工作区里解析不到时会打印一行提示并只断言降级行为 —— 想在本地跑全，把 DSH 的@deepseek-ai挂到工作区的node_modules/下即可（该目录已 gitignore）。
dom-probe.mjs 需要 react/react-dom 的 UMD 构建：
npm install --prefix .npm-cache/domprobe --cache .npm-cache --registry=https://registry.npmjs.org react@18.3.1 react-dom@18.3.1
沙箱会禁掉命名管道导致 Chrome 渲染进程 FATAL platform_channel，dom-probe.mjs 需要在
放宽权限（danger-full-access）下运行。
注意：
dom-probe.mjs测的是照抄官方 DOM 契约的静态夹具页，用来钉住本插件的 DOM 逻辑与几何， 它不是对运行中 DSH 页面的验证。真机效果需要在 DSH Web GUI 里刷新页面后目视确认。
data-files-state / data-files-root / data-files-entry /
data-files-path / data-files-body / data-files-reload）。这些属性是官方组件有意暴露的钩子，
但如果上游改名，本插件会静默失效（找不到树就什么都不做，不会报错也不会弄坏页面）。conversation / sessions / sidebarRight），
而这三个没有声明在 dsh.client.inject 里 —— 刻意如此：它们是点击那一刻才去 ctx.get() 的，
缺一个只会让这一项报错，不会让整个插件（元数据、菜单、删除）起不来。
上游若改了 input.for() / addFiles() 的形状，这里也会明确报错而不是静默插入失败。data-files-reload），不自己维护目录状态。data-fx-selected 属性是唯一真相），每次同步按 DOM 里实际还在的行剪枝：
折叠、刷新、删掉的行会自动掉出选择。~/.Trash 不会写 Finder 的「放回原处」元数据
（那在 .DS_Store 里，只有 Finder 自己写），所以文件能还原、但「放回原处」不可用。
Linux 跨卷时会用该卷根下的 .Trash/<uid> 或 .Trash-<uid>（规范要求）。
回收站被系统关掉、或条目超过回收站配额时，Windows / macOS 自己会改成永久删除 —— 那是系统的行为，插件无法区分。file-extras/trash-unavailable，
确认框里勾「永久删除」仍可继续。.md 文件要重启 dsh web 才反映。history 依赖 ctx.sessionQuery（dsh-base 里的 session-query-sqlite 提供）。
缺席时该端点回 file-extras/history-unavailable，浏览器侧 ↑/↓ 完全不接管，
文件树那部分功能不受任何影响。history 只回最近 300 条、单条截 20000 字符：回填到输入框用，不做无上限搬运。conversation / sessions / sidebarRight / commands / sessionQuery 全部
懒取（ctx.get(...)）而不是写进 inject：任何一项缺席都只让对应功能降级或报错，
不会把整个插件挡在门外。