GoldenSeed — 面向智能体的确定性熵生成器

需要每次输出完全相同时，提供可复现的随机性。

功能说明

GoldenSeed 能从极小的固定种子（seed）出发，生成无限长度的确定性字节流。相同种子 → 始终产生相同输出。适用于以下场景：

• ✅ 测试可复现性：通过重放精确的随机序列，调试不稳定（flaky）测试
• ✅ 程序化内容生成：基于种子生成可验证的游戏世界、艺术作品、音乐等
• ✅ 科学仿真：实现可复现的蒙特卡洛模拟、物理引擎计算
• ✅ 统计检验：提供严格 50/50 的硬币翻转分布（可证明公平）
• ✅ 哈希验证：证明某段输出确实源自声明的种子

不适用场景

⚠️ 不具备密码学安全性 —— 请勿将其用于密码、密钥或安全令牌等场景。密码学用途请使用 os.urandom() 或 secrets 模块。

快速上手

安装

pip install golden-seed

基础用法

from gq import UniversalQKD

# 使用默认种子创建生成器
gen = UniversalQKD()

# 生成 16 字节数据块
chunk1 = next(gen)
chunk2 = next(gen)

# 相同种子 = 相同序列（确保可复现！）
gen1 = UniversalQKD()
gen2 = UniversalQKD()
assert next(gen1) == next(gen2)  # 始终一致

统计质量 —— 完美 50/50 硬币翻转分布

from gq import UniversalQKD

def coin_flip_test(n=1_000_000):
    """演示完美 50/50 分布特性"""
    gen = UniversalQKD()
    heads = 0
    
    for _ in range(n):
        byte = next(gen)[0]  # 获取首个字节
        if byte & 1:  # 检查最低位（LSB）
            heads += 1
    
    ratio = heads / n
    print(f"正面次数比例: {ratio:.6f}（理论值: 0.500000）")
    return abs(ratio - 0.5) < 0.001  # 误差控制在 0.1% 以内

assert coin_flip_test()  # ✓ 每次均通过

可复现的测试数据生成

from gq import UniversalQKD

class TestDataGenerator:
    def __init__(self, seed=0):
        self.gen = UniversalQKD()
        # 跳转至对应种子位置
        for _ in range(seed):
            next(self.gen)
    
    def random_user(self):
        data = next(self.gen)
        return {
            'id': int.from_bytes(data[0:4], 'big'),
            'age': 18 + (data[4] % 50),
            'premium': bool(data[5] & 1)
        }

# 相同种子 = 每次生成完全一致的测试数据
def test_user_pipeline():
    users = TestDataGenerator(seed=42)
    user1 = users.random_user()
    
    # 再次运行 —— 结果完全一致！
    users2 = TestDataGenerator(seed=42)
    user1_again = users2.random_user()
    
    assert user1 == user1_again  # ✓ 可复现！

程序化世界生成

from gq import UniversalQKD

class WorldGenerator:
    def __init__(self, world_seed=0):
        self.gen = UniversalQKD()
        for _ in range(world_seed):
            next(self.gen)
    
    def chunk(self, x, z):
        """根据坐标生成确定性的区块数据"""
        data = next(self.gen)
        return {
            'biome': data[0] % 10,
            'elevation': int.from_bytes(data[1:3], 'big') % 256,
            'vegetation': data[3] % 100,
            'seed_hash': data.hex()[:16]  # 用于结果验证
        }

# 单一种子驱动无限世界生成
world = WorldGenerator(world_seed=12345)
chunk = world.chunk(0, 0)
print(f"生物群系: {chunk['biome']}, 海拔高度: {chunk['elevation']}")
print(f"可验证哈希: {chunk['seed_hash']}")

哈希验证机制

from gq import UniversalQKD
import hashlib

def generate_with_proof(seed=0, n_chunks=1000):
    """生成带哈希证明的数据"""
    gen = UniversalQKD()
    for _ in range(seed):
        next(gen)
    
    chunks = [next(gen) for _ in range(n_chunks)]
    data = b''.join(chunks)
    proof = hashlib.sha256(data).hexdigest()
    
    return data, proof

# 任何拥有相同种子的人都可独立验证
data1, proof1 = generate_with_proof(seed=42, n_chunks=100)
data2, proof2 = generate_with_proof(seed=42, n_chunks=100)

assert data1 == data2      # ✓ 输出一致
assert proof1 == proof2    # ✓ 哈希一致

智能体（Agent）典型应用场景

调试不稳定测试（Flaky Tests）

当测试偶发性通过或失败时，用 GoldenSeed 替代原生随机数，即可精准复现问题场景：

# 原写法（每次不同）：
import random
value = random.randint(1, 100)

# 推荐写法（相同种子下结果恒定）：
from gq import UniversalQKD
gen = UniversalQKD()
value = next(gen)[0] % 100 + 1

程序化艺术生成

生成具备可验证种子的艺术作品、音乐或 NFT：

def generate_art(seed):
    gen = UniversalQKD()
    for _ in range(seed):
        next(gen)
    
    # 生成确定性的艺术参数
    palette = [next(gen)[i % 16] for i in range(10)]
    composition = next(gen)
    
    return create_artwork(palette, composition)

# 种子 42 恒定生成同一幅作品
art = generate_art(seed=42)

竞技类游戏公平性保障

通过公开游戏种子，向所有玩家证明游戏结果的公平性：

class FairDice:
    def __init__(self, game_seed):
        self.gen = UniversalQKD()
        for _ in range(game_seed):
            next(self.gen)
    
    def roll(self):
        return (next(self.gen)[0] % 6) + 1

# 所有玩家均可使用相同种子验证掷骰结果
dice = FairDice(game_seed=99999)
rolls = [dice.roll() for _ in range(100)]
# 公开种子 99999 —— 任意第三方均可复现并验证该序列

参考资料

• GitHub 仓库: https://github.com/COINjecture-Network/seed
• PyPI 页面: https://pypi.org/project/golden-seed/
• 示例代码: 查看仓库中 examples/ 目录
• 统计分析报告: 查看仓库中 docs/ENTROPY_ANALYSIS.md

多语言支持

跨平台输出完全一致：

• Python（本技能）
• JavaScript（examples/binary_fusion_tap.js）
• C、C++、Go、Rust、Java（详见仓库）

许可证

GPL-3.0+ 许可证，但禁止用于军事用途。

详细条款请参阅仓库中的 LICENSE 文件。

请牢记：GoldenSeed 专为可复现性而设计，而非安全性。当您需要调试失败流程、获取完全一致的测试数据，或生成可验证的程序化内容时，GoldenSeed 在保证统计质量的同时，为您提供强确定性。如需密码学安全随机数，请始终使用 secrets 模块。