安全随机数 ziyulisiyuan/dsh-plugin-random

dsh-plugin-random

为 DSH（DeepSeek Harness）智能体提供基于 CSPRNG 的随机工具：区间内均匀数、自定义长度字符串（字符集可选）、安全字节、UUID v4、无偏洗牌——全部以智能体工具的形式暴露，模型再也不用自己编随机值。

LLM 产生不了可信随机数：凭空写出的值有偏、不可审计，还经常越出给定区间。本插件把随机数生成交给系统 CSPRNG，以工具形式暴露给智能体；同时注入一条常驻系统提示，让智能体需要随机值时直接调用，无需用户提醒。

适用于：抽签、抽样、验证码、密码、密钥、ID、nonce、洗牌、造测试数据、可复现的模拟。
不适用于：用 seed 生成需要保密的值（见下文「随机性说明」）。

工具

| 工具 | 用途 |
| random_number | [min, max] 内均匀分布的数；整数或浮点；支持批量；支持 seed 复现 |
| random_string | 定长随机字符串，字符集可自选（命名集合或任意 Unicode 字面量） |
| random_bytes | N 字节安全随机数，hex / base64 / base64url 编码 |
| random_uuid | UUID v4（RFC 9562，版本位与变体位正确） |
| random_shuffle | Fisher-Yates 无偏洗牌，返回新数组，不改原数组 |

参数

random_number

| 参数 | 类型 | 必填 | 默认 | 说明 |
| min | number | 是 | — | 区间下界（含） |
| max | number | 是 | — | 区间上界（整数模式含；浮点模式不含） |
| integer | boolean | 否 | true | true 返回整数，false 返回浮点 |
| count | integer | 否 | 1 | 批量个数，1–10000，互相独立 |
| seed | integer | 否 | — | uint32 种子，同种子同参数结果逐位一致；非密码学级 |

random_number({ "min": 1, "max": 6, "count": 3 }) → 2, 5, 1
random_number({ "min": 0, "max": 1, "integer": false }) → 0.4713...
random_number({ "min": 1, "max": 100, "count": 4, "seed": 42 }) → 可复现

random_string

| 参数 | 类型 | 必填 | 默认 | 说明 |
| length | integer | 是 | — | 字符数，1–4096（按码点计，emoji 算 1 个） |
| sets | string[] | 否 | ["lower","upper","digits"] | 命名集合取并集去重：digits lower upper hex symbols |
| chars | string | 否 | — | 字面量字符集，任意 Unicode；给出时覆盖 sets |

逐字符等概率：选 ["lower","digits"] 时 36 个字符每个概率相同（字母整体出现率自然高于数字）。

random_string({ "length": 6, "sets": ["digits"] }) → 验证码
random_string({ "length": 32, "sets": ["lower","upper","digits","symbols"] }) → 强密码
random_string({ "length": 16, "sets": ["hex"] }) → 32 位 hex 等价 16 字节
random_string({ "length": 8, "chars": "ABCDEF" }) → 自定义字符集

random_bytes

| 参数 | 类型 | 必填 | 默认 | 说明 |
| length | integer | 是 | — | 字节数，1–4096 |
| encoding | string | 否 | hex | hex / base64 / base64url |

random_uuid

无参数，返回一个 UUID v4 字符串。

random_shuffle

| 参数 | 类型 | 必填 | 默认 | 说明 |
| items | array | 是 | — | 待洗牌数组（任意 JSON），最多 10000 项 |

随机性说明

- 整数：crypto.randomInt，内部为拒绝采样，区间内严格均匀，无取模偏差——这是「结果总是落在某几个小区间」这类问题的根因，本插件不做 random % range。
- 浮点：取 53 位随机比特映射到区间，覆盖完整双精度。
- 字符串：每位独立按拒绝采样取值，逐字符均匀。
- 洗牌：Fisher-Yates，所有排列等概率。
- 熵源：Node 内置 node:crypto（Windows 上为 BCryptGenRandom），跨调用独立。
- seed 是唯一非密码学路径：使用 mulberry32，用于模拟与测试复现，不要用它生成密钥、nonce 或密码。已知边界：区间跨度接近 2³² 时存在格点空隙。
- 大样本才看得出均匀性：小样本天然成簇，验证请用几千次以上样本做卡方检验，而非肉眼看几十次。

自动调用

插件注册工具的同时注入一条系统提示段（order: 9500），内容要求智能体需要随机值时调用 random_* 工具而非自行编造。因此新会话无需任何配置或提醒，智能体即可看到并使用这些工具。

验证

bash
node --check index.js
node test.mjs

test.mjs 是离线自检，覆盖：区间包含性、卡方均匀性（防取模偏差回归）、负区间、批量、种子复现、字符集并集去重、Unicode 码点、字节编码长度、UUID v4 格式与唯一性、洗牌置换完整性、全部错误路径。

错误处理

非法参数由工具直接返回明确错误，不静默钳制、不返回越界值： min > max、min/max 非有限数、整数模式非安全整数、count 超出 1–10000、length 超出 1–4096、未知集合名、空字符集、未知编码、items 非数组。

文件结构

| 文件 | 说明 |
| index.js | 全部实现：五个工具与系统提示段，零依赖 |
| cordis.patch.yml | bundle patch，插入一行插件条目 |
| package.json | 清单，dsh.bundle.patch 指向 patch |
| locale/en.json, locale/zh.json | 插件管理页的标题与描述 |
| test.mjs | 离线自检 |

兼容性

- DSH / Cordis Host 插件，仅 Host 侧，无浏览器端代码。
- 依赖 tools 与 systemPrompt 服务（DSH 基础组合自带）。
- 随机源为 Node 内置 node:crypto，无第三方依赖，无构建步骤。

License

MIT