dsh-stash：DSH 链接外部资源库的钥匙串

前言¶

在多台机器上管理十几个数据库或接口，重复配置是常态。DSH 负责连接，但缺乏对“能不能取、用哪把钥匙、取了什么”的管理。dsh-stash 插件将外部资源登记、权限控制和取数台账集中管理，解决跨机器同步与访问控制问题。

核心定位¶

dsh-stash 是 DSH 链接外部资源库的钥匙串。它为模型提供 11 个工具，用于查询资源清单、执行取数、检查连通性以及管理凭据。维护者为 danieldu168，许可证为 MIT。

它主要回答三个问题：

能不能取？ 通过 access 声明，硬约束直接拒绝，不静默失败。
用哪把钥匙？ 钥匙台账与宿主凭据服务，值不进模型。
这次取了什么？ 取数台账仅记录指纹。

安装与启用¶

使用 pnpm 安装插件：

pnpm dsh plugin --profile web add "github:danieldu168/dsh-stash#v0.11.2"

安装后重启 Profile 并刷新浏览器。卸载命令：

pnpm dsh plugin --profile web remove dsh-stash

升级插件必须带上新的 tag 重装。DSH 的管理器不支持 update，且规格串不变会触发还原。

资源登记¶

注册表位于 ${DSH_HOME}/stash/sources.mjs，默认导出一个数组。修改后无需重启，调用时重读。

声明式配置示例：

export default [
  {
    id: 'myapi',
    name: '我的接口',
    kind: 'remote',
    handler: 'http',
    access: 'public-api',
    request: {
      url: 'https://api.example.com/search',
      query: { q: '{query}' },
      pick: 'data.items',
      limit: 50,
      required: ['query'],
    },
  },
]

关键点：
* {参数名} 传入参数，{?参数名} 为可选参数，缺参时键会被丢掉。
* 使用钥匙时填写 credentials: ['MY_API_KEY'] 引用名，不写值。
* 支持本机文件与内置处理器。

本机文件登记：

{ id: 'mydocs', kind: 'files', paths: ['D:/papers'] }

内置处理器：

{ handler: 'trade_stats' }

访问控制与凭据¶

access 字段定义权限，分为 public-api（公开）、official-api（官方）、export-import（拒绝）、unsupported（拒绝）。未声明则放行但提示。

钥匙值只存引用，不存储在 stash 中，也不返回给模型。值通过「设置 → stash」面板或 /stash import 填入，最终落在 $DSH_HOME/.env 或面板中。

台账与工具¶

提供了 11 个模型工具：catalog, fetch, doctor, lesson, source, credential 等。

取数台账记录 ledgerId 和 contentHash，不记录响应体。文件记录超过 2000 条时，旧记录会被裁剪。

迁移¶

使用命令行进行数据迁移：

# 导出（不带值，或带值/语料）
/stash export --out "D:\stash-export"
# 导入（值覆盖，条目并集）
/stash import "D:\stash-export"
# 清空（需校验码）
/stash wipe --confirm <校验码>

限制与不做什么¶

不做通用网页抓取，长期盯的页面走 corpus。
不做需登录数据库的 SSO 自动化。
不做值的存储与回读。
经验不自动写入，需人工决定。

生态背景¶

DSH 理念是「一切皆插件」。本插件通过声明式配置与集中式管理，为智能体开发提供稳定的外部数据访问层。