Note
本 SDK 以 GNU GPLv3 协议发布。使用和再发布时请遵守该协议
SecRandom 集成 SDK 面向希望在自己的应用中使用名单和抽取能力,或通过本地 IPC 控制并接收 SecRandom 抽取结果的开发者。协议核心保持语言无关;C# 程序集继续面向 .NET 8,另提供 C++、Python 和 Rust 的薄适配层,使用 .NET 10 SDK 构建和测试
- 使用稳定 ID 管理学生名单、奖品名单及成员信息
- 将名单和历史记录保存为本地 JSON,并通过历史记录参与公平抽取
- 支持随机抽取与公平抽取;公平模式按成员权重和历史抽中次数计算权重
- 抽取支持性别、分组筛选和单轮不重复;本 SDK 暂不包含编排抽取
- 通过本机当前用户的 IPC 发现接收端,并接收 SecRandom 的抽取结果
- 在 SecRandom 中经用户批准后保存通知渠道;可申请浮窗联动租约,退出或释放租约后恢复浮窗
- SecRandom 的渠道管理扩展正在 PR #358 中,包括别名、结果发送与浮窗联动开关、在线状态和删除
- 通过同一套 v2 本地 IPC 发送
点名、闪抽、抽奖指令,支持可选名单、人数、性别和分组 - 可选在抽取前打开主页面;默认不改变窗口状态
- 可以通过 IPC 读取名单/奖池、名单成员、性别和小组选项,由接入方自己的 UI 让用户选择
- 未提供的参数不会被 SDK 补齐,SecRandom 会继续使用软件当前设置,因此 SDK 不会固定随机/公平模式或人数
- C# 复用
SecRandom.Integration.Client;C++、Python、Rust 适配器位于bindings/,协议说明见docs/automation-v2.md
| 包 | 用途 |
|---|---|
SecRandom.Integration.Abstractions |
协议、名单、历史与结果的数据契约 |
SecRandom.Integration.Client |
本地发现、通知接收与浮窗联动 IPC |
SecRandom.DrawKit |
名单和历史存储、随机与公平抽取 |
| 语言适配器 | 用途 |
|---|---|
bindings/cpp |
C++17 头文件,返回原始 JSON 响应 |
bindings/python |
Python 3.10+、标准库实现 |
bindings/rust/secrandom-integration |
同步 Rust crate |
| 版本 | 技术栈 | 阶段 |
|---|---|---|
| v1 | C# + .NET 8 | 首个公开 SDK,提供名单、历史、随机/公平抽取与本地 IPC 联动 |
| v2 | C# / C++ / Python / Rust | 共享 JSON IPC 契约;各语言只负责传输和参数适配,抽取策略继续由 SecRandom 管理 |
从 GitHub Releases 下载发行包并解压,包内包含三个 .nupkg、官方 proof,以及 bindings/ 下的 C++、Python、Rust 适配器。将解压目录作为本地 NuGet 源,按需添加 SecRandom.DrawKit 或 SecRandom.Integration.Client;其依赖的 SecRandom.Integration.Abstractions 也需要保留在该源中
例如,解压到 D:\packages\secrandom 后,在目标项目目录执行:
dotnet nuget add source D:\packages\secrandom --name SecRandomLocal
dotnet add package SecRandom.DrawKit --version 1.1.0
dotnet add package SecRandom.Integration.Client --version 1.1.0using SecRandom.Integration;
using SecRandom.Integration.Client;
var client = new AutomationClient();
var result = await client.DrawAsync(
DrawChannel.RollCall,
new DrawOptions(List: "一班", OpenMainWindow: true));List、Count、Gender 和 Group 都是可选的一次性覆盖;全部省略时,抽取名单、人数、随机/公平/编排模式和其他策略均由 SecRandom 当前设置决定。OpenMainWindow 默认关闭,不会因为 SDK 调用而改变窗口状态。需要修改软件的默认名单时才调用 ActivateRosterAsync。
用户选择所需的数据可以通过 GetRosterListsAsync、ReadRosterAsync 和
GetRosterSelectionOptionsAsync 获取;这些方法只读本体,不会切换默认名单。Python、Rust
和 C++ 适配器分别提供 roster_lists / read_roster,返回同一份 IPC JSON 数据。
using SecRandom.DrawKit;
using SecRandom.Integration;
var rosters = new JsonRosterStore("data/rosters");
var history = new JsonHistoryStore("data/history.json");
rosters.Save(new Roster("class-a", "一班", RosterKind.Students,
[
new RosterMember("student-1", "小明"),
new RosterMember("student-2", "小红")
]));
var draws = new IntegrationDrawService(rosters, history, new DrawEngine());
var result = draws.Draw(new DrawRequest("class-a", 1, DrawMode.Fair));
Console.WriteLine(result.Members[0].Name);IntegrationDrawService.Draw 在成功抽取后写入历史。SDK 的名单和历史存储由接入应用管理,不会自动读取或修改 SecRandom 本体的数据
using SecRandom.Integration.Client;
await using var receiver = new NotificationReceiver(new NotificationReceiverOptions(
AppId: "example.classroom.app",
DisplayName: "课堂应用",
SdkVersion: "1.1.0.0",
PublisherProofPath: "SecRandom.Integration.Client.official-proof.json"));
receiver.NotificationReceived += (result, cancellationToken) =>
{
Console.WriteLine(string.Join(", ", result.Members.Select(member => member.Name)));
return Task.FromResult(true);
};
await receiver.StartAsync();
// 保持接收器及应用进程运行;退出时释放 receiver将官方 proof 文件部署到示例中的路径,SdkVersion 须与 proof 中的程序集版本一致。SecRandom 检测到接收器后会请求用户批准;本体集成功能合并并发布后才能在正式版中使用。更多协议细节见 集成协议 v1
| 验证内容 | 作用与限制 |
|---|---|
| SDK 官方 proof | ECDSA P-256 签名绑定官方客户端程序集的版本和 SHA-256;修改或重编译的程序集不能复用该 proof |
| 进程和 IPC 对端 | 宿主发现时检查进程已加载与 proof 匹配的程序集,通信时检查 IPC 对端进程 |
| 用户批准 | 发现通过验证的接收器后,由用户决定是否保存通知渠道 |
| 应用身份 | proof 只证明 SDK 客户端程序集,不证明使用 SDK 的第三方应用是官方软件;app_id 和显示名称由接入应用提供 |
签名私钥仅保存在 SDK 仓库的 GitHub Actions Secret 与本地忽略的 .env 中;公钥作为 SECRANDOM_INTEGRATION_PUBLIC_KEY_SPKI_BASE64 变量注入 SDK 和本体构建
dotnet test SecRandom.Integration.slnx -c ReleaseSDK 主分支的受信任构建会生成 NuGet 包和官方 proof,作为 Actions 构建产物。发布包从 GitHub Releases 下载;使用 SDK 时请优先选择带有官方 proof 的同版本发行包
- SDK 使用 GNU GPLv3 协议发布
- 抽取结果取决于接入应用提供的名单、权重及历史记录,SDK 无法验证现实名单的真实性或完整性
感谢每一位为 SecRandom 集成 SDK 提交代码、报告问题、完善文档和提供反馈的贡献者
Copyright © 2025-2026 SECTL