from spendshield import SpendShield, UnknownAgent

guard = SpendShield(dry_run=False)
guard.register_agent("mcd_bot", budget=50, max_amount=30,
                     blacklist=["测试收款"], whitelist=["麦当劳"],
                     rate_limit={"window_s": 60, "max_calls": 3})

@guard.protect("下单", agent="mcd_bot")   # 或运行时传 agent=xx

def place_order(amount, to):
    return call_real_api(amount, to)

# 新收款方（从未交易过）→ 必须确认；没配审批通道 → 直接拒绝
# 金额 > approve_above → 必须确认
guard = SpendShield(approve_new_recipient=True, approve_above=1000)

python -c "from spendshield import KeyVault; print(KeyVault.generate_key())"  # 生成主密钥(仅此一次)
export SPENDGUARD_MASTER_KEY=<刚才的输出>   # 放环境变量, 别写进代码/仓库

from spendshield import SpendShield, KeyVault

vault = KeyVault("vault.json")              # 主密钥从环境变量读
vault.store("mcd_sk", "sk_live_xxxx")      # 加密落盘, 文件里只有密文

guard = SpendShield(key_vault=vault)
guard.register_agent("mcd_bot", whitelist=["mcd_sk"])
sk = guard.get_secret("mcd_sk", agent="mcd_bot")   # 过身份+意图闸门才能取

pip install spendshield   # 或直接 clone 用

from spendshield import SpendShield

guard = SpendShield(budget=200, dry_run=True, whitelist=["麦当劳"])   # 默认干跑 + 信任收款方

@guard.protect("下单")
def place_order(amount, to):
    return call_real_api(amount, to)            # 真实下单逻辑

# 干跑模式: 报错提示, 绝不真花
place_order(amount=99, to="麦当劳")
# => [SpendShield] dry_run: 下单 ¥99.0 -> 麦当劳 (未执行)
# => DryRunBlocked: 关掉 dry_run 才会真花

# 确认无误后放行, 预算闸门兜底
guard.dry_run = False
for i in range(4):
    place_order(amount=99, to="麦当劳")          # 第3单被 BudgetExceeded 拦住

python3 tests/test_guard.py   # 6 个测试全过

# 启动(stdio 模式, agent 配置里指向它)
python -m spendshield.mcp_server --policy spendshield.yaml
# 或安装后: spendshield-mcp --policy spendshield.yaml

// agent 调用示例
{"name": "spend_protect", "arguments": {"action": "下单", "amount": 99, "to": "麦当劳"}}
// => {"ok": false, "reason": "[干跑] 下单 ¥99.0 -> 麦当劳 (未执行...)", "spent": 0.0}