dsh-sidebar-panel

<img width="3084" height="1670" alt="image" src="https://github.com/user-attachments/assets/a8c1651d-6477-4b8a-8614-be53e062cf69" /># dsh-sidebar-panel

DSH（DeepSeek Harness，Web profile）的右侧面板插件：在会话头部右上角新增一个面板折叠按钮（样式与左侧折叠按钮一致），点击展开/收起右侧 details 列；面板常驻并保持打开——默认打开，切换会话/新建会话不会自动收起，直到用户自己点击收起按钮（收起状态会被记住）。面板包含四个页签：

• 概览：
• DeepSeek 账户卡片——官方余额（经 GET https://api.deepseek.com/user/balance 实时查询，15 秒刷新）与 充值按钮（跳转 https://platform.deepseek.com/usage）；
• 下方为上下文窗口（已用/总量/百分比/距压缩）、本轮上下文预算（提示词/输出预算/物理剩余空间/上限来源）、会话指标（命中率/本次会话费用/运行时间/请求数/累计 tokens）、用量分析（按来源/按类型，含输入输出、命中未命中明细）。服务端数据每 5 秒自动刷新（右上角显示"更新于 HH:MM:SS"），投影数据（token/上下文）实时响应。
• 文件：当前会话工作区的文件树。单击文件预览（md/txt/代码等文本内联显示，PDF 与图片内嵌预览，大文件截断提示）；右键菜单：在文件管理器中显示、添加文件引用 / 添加文件内容（文件）、添加文件夹引用（文件夹）、复制绝对路径 / 复制相对路径。插入内容会写入对话输入框。
• 改动：本次会话中写文件类工具（write/edit/str-replace-editor 等）触碰过的文件列表。
• 工具：本窗口内的工具调用列表与参数/结果详情（自建渲染）。

> 兼容性：仅支持 DSH 的 Web profile（HTTP 同源路由）；desktop（Electron）形态下自定义 HTTP 路由不可用。

目录结构

dsh-sidebar-panel/
├── package.json          # DSH bundle 清单 + client 注入声明
├── cordis.patch.yml      # 把插件插入 DSH 组合层
├── src/index.js          # 服务端：同源 HTTP API + 会话事件折叠（用量/费用/改动）+ 文件浏览 + reveal
├── client/client.js      # 客户端：右上角折叠按钮 + details 列面板（常驻、自动重开、blank 期 DOM 保活）+ 四页签 + 右键菜单
├── test/unit.test.mjs    # 服务端单元测试（mock ctx，无需 DSH 实例，不依赖具体路径）
└── README.md / README_EN.md

> 依赖：服务端依赖 @deepseek-ai/schemastery（配置 schema）与 @deepseek-ai/dsh-credentials（读取 DEEPSEEK_API_KEY 凭据），二者由 DSH 运行时提供。pnpm pack 产物不含 node_modules；以源码方式开发时，在插件目录执行 pnpm install 即可解析依赖。

安装

在 DSH 运行的终端中执行（Web profile）：

# 方式一：GitHub 安装（推荐）
dsh plugin --profile web add github:kee0012/dsh-sidebar-panel

# 方式二：npm 安装（暂未发布到 npm registry，不建议使用）
dsh plugin --profile web add dsh-sidebar-panel

安装后重启 DSH，并刷新浏览器（Ctrl+Shift+R）。验证配置层生效：

服务端 API（同源，供客户端面板使用）

配置（cordis.yml / 插件配置）

在 DSH 组合配置中给该插件加 config 即可（未提供时全部使用默认值）：

- id: dsh-sidebar-panel
  name: dsh-sidebar-panel
  config:
    fileBrowser:
      maxEntries: 500
      maxContentChars: 40000
      includeHidden: false
    reference:
      file: '@<path>'
      folder: '@<path>/'
    changes:
      writeTools: ['write', 'edit', 'str-replace-editor', 'patch', 'run_code']
    pricing:
      enabled: true
      currency: CNY
      offPeakStartHour: 0.5      # 北京时间 00:30 起为低谷
      offPeakEndHour: 8.5        # 08:30 止
      offPeakMultiplier: 0.5
      models:
        deepseek-chat: { inputPerM: 2, cacheHitPerM: 0.5, cacheWritePerM: 2, outputPerM: 8 }
        deepseek-reasoner: { inputPerM: 4, cacheHitPerM: 1, cacheWritePerM: 4, outputPerM: 16 }

> 费用为估算：按每次请求的 usage × 每百万 tokens 单价（缓存命中按低价），并按请求时刻的北京时间峰/谷时段加权。你的模型若不在表中则用 pricing.defaultModel（默认与 deepseek-chat 相同）。如需精确匹配实际账单，请按你的模型实际价格调整 pricing.models。

开发与测试

# 语法检查
node --check src/index.js && node --check client/client.js

# 服务端单元测试（mock ctx，覆盖路由/跨域/文件树/越界锁定/概览折叠/峰谷计价/改动追踪）
node test/unit.test.mjs

# API 冒烟测试（GET 无需 Origin 头，浏览器同源 GET 本就不带 Origin；POST 冒烟请带 Origin）
curl "http://127.0.0.1:3080/dsh-sidebar-panel/api/config"
curl -H "Origin: http://127.0.0.1:3080" -H "Content-Type: application/json" -X POST \
  -d '{"root":"<你的工作区>","path":"dsh-sidebar-panel/package.json"}' \
  "http://127.0.0.1:3080/dsh-sidebar-panel/api/file-content"

已知限制

• details 列替换：插件以 priority: -1 顶替内置 DetailsPanel（单槽位只能有一个渲染者）。内置面板的"工具详情"座（conversation.details.tool）属于其自身声明，插件无法复用，故"工具"页签为自建详情视图；聊天里的 Inspect 按钮仍会打开右侧列，但不会自动选中工具。
• 开合偏好（常驻）：面板开合状态存于浏览器 localStorage（dshSidebarPanel:details-open），默认 open。切会话/新建会话不会自动收起：宿主框架在切换会话（及 blank 会话首次发言 engage）时会调用 closeDetails() 收起 details 列，插件检测到会话/blank 变化后会自动重开，直到用户主动点击收起/关闭（记为 closed，此后所有切换都保持收起，直到再次点击打开）。
• blank（新建会话 hero）期间面板也常驻：宿主布局在 blank 状态下会把 details 列宽强制为 0、并隐藏整个会话 header（右上角按钮随之消失）。插件只注入一条声明式 CSS 规则（!important，三列：<侧栏>px | 聊天区 minmax(0,1fr) | 面板 360px）在 blank 且偏好为打开时生效——不触碰宿主内联样式、不与 React 渲染竞争，宿主任何重渲染都无法覆盖；三列是真实 grid 单元格，面板结构性固定在右侧固定宽度，不可能全屏或遮挡聊天区。同时在右上角原位渲染同款固定折叠按钮（仅 blank 期间显示，点击真实开合并同步布局状态）；会话正式启用后规则移除、宿主恢复正常接管，固定按钮自动隐藏、右上角 header 按钮回归。
• 费用匹配：费用是估算值，取决于定价表配置；金额保留 6 位小数传输、按大小自适应显示精度。
• 改动追踪：只覆盖写文件类工具调用；bash/pwsh 内部的文件改动无法可靠捕获。
• 概览请求数/费用/运行时间：由服务端从会话事件日志折叠（request/header、assistant/message 的 usage），插件安装前的历史会话在首次访问时会一次性补算；运行时间 = 自首次请求至今（含空闲）。
• 账户数据口径：余额来自 DeepSeek 官方接口（需在 DSH 凭据/环境变量中配置 DEEPSEEK_API_KEY，否则显示"未配置"提示）。官方仅提供余额查询接口，无公开的累计消费/请求次数接口，故账户卡片不再展示这两项；官方精确账单可通过"充值"按钮进入 https://platform.deepseek.com/usage 查看。
• 跨域防护：GET 请求不做 Origin 校验（同源 GET 本就不带 Origin 头）；POST 依赖"不响应 CORS 预检 + 仅接受 JSON"防线（与 DSH 宿主 API 同策略）。

反馈与贡献

• 遇到问题请到 Issues 反馈，附上 DSH 版本、profile、复现步骤与日志。
• 欢迎提交 Pull Request。

License

[MIT](./LICENSE) © dsh-sidebar-panel contributors