前言¶

在 DSH 里跑智能体或本地脚本时，经常需要一块可读写、可持久化的「状态」：例如当前步骤、计数器、开关或一段 JSON 配置。若只靠对话上下文或临时文件，外部程序很难统一接入，也很难在修改后立刻通知界面或其它监听方。

dsh-vars 是 DeepSeek Harness（DSH）社区插件，维护者为 juntaoqian，归类为「记忆」。它在 DSH 进程内提供带类型与初始值的变量，通过本机 HTTP GET / POST 读写，并支持 WebSocket 变化订阅、可选 Bearer token，以及在设置页展示本机 IP 与端口。数据落在用户目录下的 variables.json，零 npm 运行时依赖、无构建步骤。当前版本为 0.2.0，许可证 MIT。

这是什么¶

一句话：在 DSH 里新建 string / number / boolean / json 四类变量，用本机 API 与设置页管理，其它程序可通过 HTTP 或 WebSocket 同步读写与监听变更。

插件挂载在 DSH 提供的本机端口上，API 前缀为 /dsh-vars/api。变量接口仅接受 loopback（127.0.0.1 / ::1），面向本机脚本与浏览器设置页，不对外网暴露。

核心功能¶

类型化变量与存储¶

• 变量类型：string、number、boolean、json。
• 持久化路径：~/.dsh/plugins/dsh-vars/variables.json，权限 0600，临时文件加 rename 原子写入。
• 变量名：字母或下划线开头，可含字母、数字、_、.、-，长度 ≤64；最多 200 个变量。
• 损坏文件会自动备份为 variables.json.corrupt-<时间> 并以空表启动。

各类型的默认值、合法输入与错误码见 README 中的类型规则表；非法值返回 400 invalid-value，重名 409 conflict，不存在 404 not-found。

设置页「设置 → 变量」¶

安装并重启 DSH 后，在设置中打开「变量」：

1. 顶部显示 DSH 端口、本机地址、局域网地址、API 令牌状态、实时同步状态。
2. 新建变量：名称、类型、初始值，点「创建变量」。
3. 列表按名称 / 类型 / 值 / 更新时间 / 操作对齐；支持修改值、删除、刷新。
4. 其它程序通过 API 修改变量时，页面经 WebSocket 自动刷新；失败时可手动点刷新。

HTTP API¶

DSH 端口见设置页顶部或 DSH 窗口地址。下文基址为 http://127.0.0.1:<DSH_PORT>/dsh-vars/api。

响应统一为：

{ "ok": true, "value": ... }
{ "ok": false, "error": { "code": "...", "message": "..." } }

常用路由：

WebSocket 变化订阅¶

实时事件地址：

ws://127.0.0.1:<DSH_PORT>/dsh-vars/api/events

消息类型包括 ready（含 count、tokenRequired）与 change（created / updated / deleted 及变量名、时间戳）。服务端每 25 秒 ping；普通 HTTP GET 该路径返回 426 upgrade-required。

可选 Bearer token¶

三选一启用（优先级从上到下）：插件配置行里的 token、环境变量 DSH_VARS_TOKEN、~/.dsh/plugins/dsh-vars/config.json 中的 token 字段。

启用后，除 /health、/info 外，数据接口需 Authorization: Bearer <token>；WebSocket 可用查询参数 ?token=<token>。设置页「API 令牌」填入同一 token（仅存浏览器 localStorage），页面请求会自动带上。

安装与启用¶

安装或更新后需要完全退出并重新打开 DSH（host 侧代码在进程启动时加载）。

package.json 要求 Node >=22.19.0、DSH >=0.2.1-rc.2。

一句话让 AI 协助安装¶

可将下面说明交给 DSH 内的 AI：

安装 DSH 插件：https://github.com/juntaoqian/dsh-vars，进目录执行 `node scripts/install.mjs --profile desktop`，然后完全退出并重开 DeepSeek Harness，确认「设置 → 变量」出现，并告诉我怎么用 curl 修改变量。

手动安装（Windows PowerShell 示例）¶

git clone https://github.com/juntaoqian/dsh-vars.git
cd dsh-vars
node scripts/install.mjs --profile desktop
# 完全退出并重新打开 DeepSeek Harness

验证安装（README 提供的 desktop 配置校验）：

$env:ELECTRON_RUN_AS_NODE = '1'
& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\DeepSeek Harness.exe" scripts/validate-profile.mjs --profile desktop

典型用法¶

下面示例将 <DSH_PORT> 替换为设置页或 /info 返回的实际端口。

PowerShell 调用 API¶

$base = 'http://127.0.0.1:<DSH_PORT>/dsh-vars/api'

# 新建
Invoke-RestMethod "$base/variables" -Method Post -ContentType 'application/json' `
  -Body (@{ name='demo'; type='number'; initialValue=1 } | ConvertTo-Json)

# 获取全部变量
Invoke-RestMethod "$base/all"

# GET 修改
Invoke-RestMethod "$base/set?name=demo&value=42"

# POST 修改
Invoke-RestMethod "$base/variables/demo" -Method Post -ContentType 'application/json' `
  -Body (@{ value=7 } | ConvertTo-Json)

# 读取 / 删除
Invoke-RestMethod "$base/variables/demo"
Invoke-RestMethod "$base/variables/demo" -Method Delete

浏览器也可直接访问 GET 改值：

http://127.0.0.1:<DSH_PORT>/dsh-vars/api/set?name=demo&value=42

启用 token 后的请求¶

$base = 'http://127.0.0.1:<DSH_PORT>/dsh-vars/api'
$headers = @{ Authorization = 'Bearer your-token' }
Invoke-RestMethod "$base/all" -Headers $headers
Invoke-RestMethod "$base/set?name=demo&value=42" -Headers $headers

WebSocket 监听（Node / 浏览器）¶

const ws = new WebSocket('ws://127.0.0.1:<DSH_PORT>/dsh-vars/api/events')
ws.onmessage = (event) => {
  const message = JSON.parse(event.data)
  // { type: 'ready', count, tokenRequired }
  // { type: 'change', event: { type: 'created'|'updated'|'deleted', name }, at }
  console.log(message)
}

启用 token 时：ws://127.0.0.1:<DSH_PORT>/dsh-vars/api/events?token=<token>。

适用场景与注意¶

适合谁：需要在 DSH 与本机脚本、小工具之间共享少量结构化状态的场景——例如流水线步骤号、功能开关、轻量 JSON 配置，并希望在设置页与其它消费者之间实时同步。

运行与安全：插件以当前 DSH 进程权限运行；安装前应自行查阅源码与 MIT 许可证。变量 API 仅监听 loopback；token 不写日志，但若未启用 token，本机任意进程均可读写变量，敏感信息应加密或勿存入插件。

并发：同一 DSH 实例内写入已串行化；多进程并发写同一 variables.json 无跨进程锁，需由调用方自行协调。

卸载：

node scripts/install.mjs --profile desktop --uninstall
Remove-Item "$env:USERPROFILE\.dsh\plugins\dsh-vars" -Recurse -Force   # 可选：删数据

结尾¶

dsh-vars 把「记忆」落到可类型的持久化变量上，用统一的 HTTP 与 WebSocket 接口供 DSH 设置页和本机程序共用。目录与源码链接如下：

• 社区目录页：https://www.skillhub.cn/plugins/juntaoqian/dsh-vars
• GitHub：https://github.com/juntaoqian/dsh-vars
• 问题反馈：https://github.com/juntaoqian/dsh-vars/issues