PyPI - spendshield - Versions diffs - 0.6.0__py3-none-any.whl - Mend

spendshield 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

spendshield/__init__.py +32 -0
spendshield/dashboard.py +119 -0
spendshield/guard.py +503 -0
spendshield/mcp_server.py +185 -0
spendshield/vault.py +75 -0
spendshield-0.6.0.dist-info/METADATA +178 -0
spendshield-0.6.0.dist-info/RECORD +10 -0
spendshield-0.6.0.dist-info/WHEEL +5 -0
spendshield-0.6.0.dist-info/entry_points.txt +2 -0
spendshield-0.6.0.dist-info/top_level.txt +1 -0

spendshield/__init__.py ADDED Viewed

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""
+SpendShield — AI Agent 付款安全层
+给 AI Agent 的「花钱动作」加上四道闸门:
+  1. dry_run    干跑模式(默认开): 只预览, 不真花
+  2. budget     预算上限: 超了直接拒绝
+  3. approval   人工确认: 花钱前必须人点头
+  4. audit      全量审计: 每次尝试都留痕
+血泪背景: 2026-08-09, 我让自动化系统测试下单, 因为 dry 参数没生效,
+4 单 99 元真实出码扣款。这个库就是那次事故的产物——
+AI 时代, 别让 Agent 替你花钱之前没有闸门。
+用法:
+    from spendshield import SpendShield
+    guard = SpendShield(budget=100, dry_run=True, approval="console")
+    @guard.protect("下单", max_amount=50)
+    def place_order(order_id, amount, to):
+        # ... 真实下单逻辑
+        return {"ok": True}
+"""
+from .guard import SpendShield, GuardedError, BudgetExceeded, NeedsApproval, DryRunBlocked, UnknownAgent, AuditRecord
+from .vault import KeyVault
+__version__ = "0.6.0"
+__all__ = [
+    "SpendShield", "GuardedError", "BudgetExceeded",
+    "NeedsApproval", "DryRunBlocked", "UnknownAgent", "AuditRecord", "KeyVault",
+]

spendshield/dashboard.py ADDED Viewed

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""SpendShield 审计 Dashboard — 可视化审计记录
+用法:
+  1. 程序里导出审计: guard.export_audit("audit.json")
+  2. 启动看板:      python -m spendshield.dashboard --file audit.json --port 8775
+  3. 打开 http://localhost:8775
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse
+PAGE = """<!DOCTYPE html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>SpendShield 审计 Dashboard</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;background:radial-gradient(900px 500px at 20% -10%,#1b1633 0%,#0b0e14 55%);color:#e6e8ee;padding:28px;min-height:100vh}
+h1{font-size:20px;font-weight:800;margin-bottom:4px}h1 span{color:#a78bfa}
+.sub{color:#7d8590;font-size:13px;margin-bottom:20px}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:20px}
+.stat{background:#141b26;border:1px solid #21262d;border-radius:10px;padding:12px 14px}
+.stat .v{font-size:24px;font-weight:800;line-height:1.2}
+.stat .k{font-size:12px;color:#7d8590;margin-top:2px}
+.stat .v.green{color:#3fb950}.stat .v.red{color:#f85149}.stat .v.purple{color:#a78bfa}.stat .v.yellow{color:#d29922}
+table{width:100%;border-collapse:collapse;font-size:13px}
+th,td{padding:9px 12px;text-align:left;border-bottom:1px solid #21262d}
+th{color:#7d8590;font-weight:600;font-size:12px}
+.blocked{color:#f85149}.executed{color:#3fb950}.dry{color:#d29922}
+</style></head><body>
+<h1>💰 SpendShield <span>审计 Dashboard</span></h1>
+<div class="sub" id="meta">加载中...</div>
+<div class="stats" id="stats"></div>
+<table id="tbl"><thead><tr>
+<th>时间</th><th>操作</th><th>金额</th><th>收款方</th><th>决策</th><th>原因</th><th>累计已花</th>
+</tr></thead><tbody></tbody></table>
+<script>
+async function load(){
+  const r=await fetch('/api/audit');const d=await r.json();
+  const recs=d.records||[];
+  document.getElementById('meta').textContent=`${recs.length} 条记录 · 更新于 ${new Date().toLocaleTimeString()} · 30s 自动刷新`;
+  const executed=recs.filter(x=>x.decision==='executed');
+  const blocked=recs.filter(x=>x.decision.startsWith('blocked')||x.decision==='dry_run');
+  const spent=executed.reduce((s,x)=>s+(x.amount||0),0);
+  const maxAmt=Math.max(...recs.map(x=>x.amount||0),0);
+  document.getElementById('stats').innerHTML=
+   `<div class="stat"><div class="v purple">${recs.length}</div><div class="k">总尝试</div></div>
+    <div class="stat"><div class="v green">${executed.length}</div><div class="k">已放行</div></div>
+    <div class="stat"><div class="v red">${blocked.length}</div><div class="k">被拦截</div></div>
+    <div class="stat"><div class="v">¥${spent.toFixed(2)}</div><div class="k">累计已花</div></div>
+    <div class="stat"><div class="v yellow">¥${maxAmt.toFixed(2)}</div><div class="k">最大单笔</div></div>`;
+  const tb=document.querySelector('#tbl tbody');tb.innerHTML='';
+  for(const r of recs){
+    const cls=r.decision==='executed'?'executed':(r.decision==='dry_run'?'dry':'blocked');
+    const t=new Date(r.ts*1000).toLocaleString('zh-CN',{month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',second:'2-digit'});
+    tb.insertAdjacentHTML('beforeend',
+      `<tr><td>${t}</td><td>${r.action}</td><td>¥${(r.amount||0).toFixed(2)}</td><td>${r.to}</td>
+       <td class="${cls}">${r.decision}</td><td style="color:#9da7b3">${r.reason||''}</td><td>¥${(r.spent_after||0).toFixed(2)}</td></tr>`);
+  }
+}
+load();setInterval(load,30000);
+</script></body></html>
+"""
+class Handler(BaseHTTPRequestHandler):
+    file = "audit.json"
+    def _json(self, obj):
+        body = json.dumps(obj, ensure_ascii=False).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+    def do_GET(self):
+        u = urlparse(self.path)
+        if u.path in ("/", "/index.html"):
+            body = PAGE.encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+        elif u.path == "/api/audit":
+            try:
+                with open(self.file, encoding="utf-8") as f:
+                    records = json.load(f)
+            except Exception:
+                records = []
+            self._json({"records": records})
+        else:
+            self._json({"error": "not found"})
+    def log_message(self, *a):
+        pass
+def main():
+    ap = argparse.ArgumentParser(prog="spendshield-dashboard")
+    ap.add_argument("--file", default="audit.json", help="审计 JSON 文件")
+    ap.add_argument("--port", type=int, default=8775)
+    args = ap.parse_args()
+    Handler.file = args.file
+    srv = ThreadingHTTPServer(("0.0.0.0", args.port), Handler)
+    print(f"SpendShield 审计看板: http://localhost:{args.port}  (file={args.file})")
+    srv.serve_forever()
+if __name__ == "__main__":
+    main()

spendshield/guard.py ADDED Viewed

@@ -0,0 +1,503 @@
+# -*- coding: utf-8 -*-
+"""
+SpendShield 核心: 四道闸门实现
+"""
+from __future__ import annotations
+import functools
+import inspect
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from typing import Any, Callable, Optional
+class GuardedError(Exception):
+    """SpendShield 拦截的基础异常"""
+class DryRunBlocked(GuardedError):
+    """干跑模式: 动作被预览拦截, 未执行"""
+class BudgetExceeded(GuardedError):
+    """预算超限: 本次花费会导致总预算超支"""
+class NeedsApproval(GuardedError):
+    """需要人工确认: 未获批准, 动作未执行"""
+class UnknownAgent(GuardedError):
+    """未注册的 Agent 身份: 默认拒绝(安全默认)"""
+@dataclass
+class AuditRecord:
+    """一次被闸门处理的记录"""
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    ts: float = field(default_factory=time.time)
+    action: str = ""
+    amount: float = 0.0
+    to: str = ""
+    agent: str = ""           # 调用方 Agent 身份(KYA 最小实现)
+    decision: str = ""       # preview / blocked_budget / blocked_approval / executed / dry_run
+    reason: str = ""
+    spent_after: float = 0.0
+    def to_dict(self) -> dict:
+        return asdict(self)
+class SpendShield:
+    """
+    给花钱函数加闸门。
+    参数:
+        budget: 总预算(0 = 不限)
+        dry_run: 干跑模式, 默认 True。只预览不执行。
+        approval: 人工确认模式。None=不需要, "console"=终端输入, 或 callable(record)->bool
+        on_block: 拦截回调, 可选
+        log: 审计日志回调, 可选(默认打印)
+    """
+    def __init__(
+        self,
+        budget: float = 0.0,
+        dry_run: bool = True,
+        approval: Optional[Any] = None,
+        on_block: Optional[Callable[[AuditRecord], None]] = None,
+        log: Optional[Callable[[AuditRecord], None]] = None,
+        blacklist: Optional[list] = None,      # 收款方黑名单: 直接拒绝
+        whitelist: Optional[list] = None,      # 收款方白名单: 跳过人工确认
+        rate_limit: Optional[dict] = None,     # {"window_s": 60, "max_calls": 3} 频率限制
+        policy: Optional[str] = None,          # 策略文件路径(spendshield.yaml)
+        tg_token: str = "",                    # 远程审批: TG bot token
+        tg_chat: str = "",                     # 远程审批: TG chat id
+        webhook_url: str = "",                 # 远程审批: Webhook URL
+        agents: Optional[dict] = None,         # Agent 身份层: {agent_id: {budget/max_amount/blacklist/...}}
+        allow_unknown: bool = False,           # 未注册 agent 是否回落全局策略(安全默认拒绝)
+        approve_new_recipient: bool = True,    # 意图一致性: 新收款方首次交易强制审批(防提示注入); 未配置审批通道则默认拒绝
+        approve_above: float = 0.0,            # 意图一致性: 超过该金额的转账强制审批(0 = 不限)
+        key_vault: Optional[Any] = None,       # 密钥保险库(KeyVault 实例): get_secret 过闸门才能取
+    ):
+        self.budget = budget
+        self.dry_run = dry_run
+        self.approval = approval
+        self.on_block = on_block
+        self.log = log or (lambda rec: print(f"[SpendShield] {rec.decision}: {rec.action} ¥{rec.amount} -> {rec.to}"))
+        self.blacklist = [str(x).lower() for x in (blacklist or [])]
+        self.whitelist = [str(x).lower() for x in (whitelist or [])]
+        self.rate_limit = rate_limit or {}
+        self.tg_token = tg_token
+        self.tg_chat = tg_chat
+        self.webhook_url = webhook_url
+        self._tg_offset = 0
+        self.default_max_amount = 0.0
+        self._rate_hits: list[tuple] = []      # (ts, agent, to)
+        self._spent = 0.0
+        self.records: list[AuditRecord] = []
+        self._agents: dict[str, dict] = {}
+        self._agent_spent: dict[str, float] = {}
+        self.allow_unknown = allow_unknown
+        self.approve_new_recipient = approve_new_recipient
+        self.approve_above = approve_above
+        self.vault = key_vault
+        self._known_recipients: set[str] = set()   # 成功交易过的收款方(意图一致性记忆)
+        for aid, aconf in (agents or {}).items():
+            self.register_agent(aid, **{k: v for k, v in aconf.items()
+                                        if k in ("budget", "max_amount", "blacklist",
+                                                 "whitelist", "rate_limit", "approval")})
+        if policy:
+            self.load_policy(policy)
+    @property
+    def spent(self) -> float:
+        return self._spent
+    def _record(self, **kw) -> AuditRecord:
+        rec = AuditRecord(**kw)
+        self.records.append(rec)
+        return rec
+    def _check(self, action: str, amount: float, to: str, agent: str = "") -> AuditRecord:
+        """四道闸门, 返回通过的记录(未执行), 抛异常则被拦。
+        agent: 调用方身份(Agent ID, KYA 最小实现)。未注册默认拒绝, allow_unknown=True 回落全局策略。"""
+        try:
+            ap = self._agent_policy(agent)
+        except UnknownAgent:
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="blocked_unknown_agent", reason="未注册的 Agent 身份, 默认拒绝",
+                               spent_after=self._spent)
+            self.log(rec)
+            if self.on_block:
+                self.on_block(rec)
+            raise
+        # 合并生效策略: agent 级覆盖全局
+        bl = self.blacklist + list(ap.get("blacklist", []))
+        wl = self.whitelist + list(ap.get("whitelist", []))
+        rl = ap.get("rate_limit") or self.rate_limit
+        ab = float(ap.get("budget", 0) or 0)
+        appr = ap.get("approval") if "approval" in ap else self.approval
+        agent_spent = self._agent_spent.get(agent, 0.0) if agent else self._spent
+        # 1. dry_run 干跑
+        if self.dry_run:
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="dry_run", reason="dry_run=True 干跑模式, 未执行",
+                               spent_after=self._spent)
+            self.log(rec)
+            raise DryRunBlocked(f"[干跑] {action} ¥{amount} -> {to} (未执行, 关掉 dry_run 才会真花)")
+        # 1.5 黑名单: 直接拒绝
+        to_l = str(to).lower()
+        if any(b in to_l for b in bl):
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="blocked_blacklist", reason=f"收款方在黑名单: {to}",
+                               spent_after=self._spent)
+            self.log(rec)
+            if self.on_block:
+                self.on_block(rec)
+            raise BudgetExceeded(f"[黑名单] {action} ¥{amount} -> {to} 被拒绝(黑名单收款方)")
+        # 1.6 频率限制: 同一 agent+收款方 window 内 max_calls 次
+        if rl:
+            now = time.time()
+            window = rl.get("window_s", 60)
+            max_calls = rl.get("max_calls", 3)
+            self._rate_hits = [(t, a, r) for t, a, r in self._rate_hits if now - t < window]
+            hits = sum(1 for _, a, r in self._rate_hits if r == to_l and a == agent)
+            if hits >= max_calls:
+                rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                                   decision="blocked_rate", reason=f"收款方 {to} {window}s 内超过 {max_calls} 次",
+                                   spent_after=self._spent)
+                self.log(rec)
+                if self.on_block:
+                    self.on_block(rec)
+                raise BudgetExceeded(f"[频率] {action} ¥{amount} -> {to} 触发频率限制({window}s/{max_calls}次)")
+            self._rate_hits.append((now, agent, to_l))
+        # 2. 预算: agent 级分闸优先, 全局总闸兜底
+        if ab > 0 and agent_spent + amount > ab:
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="blocked_budget",
+                               reason=f"Agent[{agent}] 已花 ¥{agent_spent:.2f} + ¥{amount:.2f} > 预算 ¥{ab:.2f}",
+                               spent_after=self._spent)
+            self.log(rec)
+            if self.on_block:
+                self.on_block(rec)
+            raise BudgetExceeded(f"[预算] {action} ¥{amount} 超支: Agent[{agent}] 已花 ¥{agent_spent:.2f}, 预算 ¥{ab:.2f}")
+        if self.budget > 0 and self._spent + amount > self.budget:
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="blocked_budget",
+                               reason=f"已花 ¥{self._spent:.2f} + ¥{amount:.2f} > 总预算 ¥{self.budget:.2f}",
+                               spent_after=self._spent)
+            self.log(rec)
+            if self.on_block:
+                self.on_block(rec)
+            raise BudgetExceeded(f"[预算] {action} ¥{amount} 超支: 已花 ¥{self._spent:.2f}, 总预算 ¥{self.budget:.2f}")
+        # 2.5/3 审批: 白名单跳过; 否则:
+        #   - 意图一致性(防提示注入): 敏感操作(新收款方/大额)强制审批; 未配置审批通道 → 直接拒绝(安全默认)
+        #   - 全局 approval 配置: 每笔都问(强模式)
+        if not any(w in to_l for w in wl):
+            sensitive = False
+            sensitive_reason = ""
+            if self.approve_new_recipient and to_l not in self._known_recipients:
+                sensitive, sensitive_reason = True, f"新收款方需确认: {to}"
+            elif self.approve_above > 0 and amount > self.approve_above:
+                sensitive, sensitive_reason = True, f"金额 ¥{amount:.2f} > 敏感阈值 ¥{self.approve_above:.2f}, 需确认"
+            if sensitive:
+                if appr is None:
+                    rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                                       decision="blocked_approval",
+                                       reason=sensitive_reason + ", 未配置审批通道, 安全默认拒绝",
+                                       spent_after=self._spent)
+                    self.log(rec)
+                    if self.on_block:
+                        self.on_block(rec)
+                    raise NeedsApproval(f"[确认] {action} ¥{amount} -> {to} 未获批准({sensitive_reason}, 未配置审批通道)")
+                ok = self._ask(action, amount, to, agent)
+                if not ok:
+                    rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                                       decision="blocked_approval", reason=sensitive_reason + ", 审批被拒",
+                                       spent_after=self._spent)
+                    self.log(rec)
+                    if self.on_block:
+                        self.on_block(rec)
+                    raise NeedsApproval(f"[确认] {action} ¥{amount} -> {to} 未获批准({sensitive_reason})")
+            elif appr is not None:
+                ok = self._ask(action, amount, to, agent)
+                if not ok:
+                    rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                                       decision="blocked_approval", reason="人工确认被拒",
+                                       spent_after=self._spent)
+                    self.log(rec)
+                    if self.on_block:
+                        self.on_block(rec)
+                    raise NeedsApproval(f"[确认] {action} ¥{amount} -> {to} 未获批准")
+        return self._record(action=action, amount=amount, to=to, agent=agent,
+                            decision="executed", reason="", spent_after=self._spent)
+    def _ask(self, action: str, amount: float, to: str, agent: str = "") -> bool:
+        who = f"[{agent}] " if agent else ""
+        if callable(self.approval):
+            return bool(self.approval({"action": action, "amount": amount, "to": to, "agent": agent}))
+        if self.approval == "console":
+            try:
+                ans = input(f"\n⚠️  {who}{action} ¥{amount:.2f} -> {to}\n   确认执行? [y/N] ").strip().lower()
+                return ans in ("y", "yes")
+            except EOFError:
+                return False
+        if self.approval == "tg":
+            return self._ask_tg(action, amount, to, agent=agent)
+        if self.approval == "webhook":
+            return self._ask_webhook(action, amount, to, agent=agent)
+        return False  # 未知模式 = 拒绝(安全默认)
+    def _ask_tg(self, action: str, amount: float, to: str, timeout_s: int = 60, agent: str = "") -> bool:
+        """TG 远程审批: 发消息等回复 y/n"""
+        import urllib.request
+        if not self.tg_token or not self.tg_chat:
+            return False
+        try:
+            who = f"[{agent}] " if agent else ""
+            text = f"⚠️  SpendShield 审批\n{who}{action} ¥{amount:.2f} -> {to}\n回复 y 确认 / n 拒绝"
+            url = f"https://api.telegram.org/bot{self.tg_token}/sendMessage"
+            body = json.dumps({"chat_id": self.tg_chat, "text": text}).encode()
+            req = urllib.request.Request(url, data=body, headers={"Content-Type": "application/json"})
+            urllib.request.urlopen(req, timeout=10).read()
+            # 轮询等回复
+            deadline = time.time() + timeout_s
+            while time.time() < deadline:
+                up_url = f"https://api.telegram.org/bot{self.tg_token}/getUpdates?timeout=10&offset={self._tg_offset}"
+                try:
+                    with urllib.request.urlopen(up_url, timeout=15) as r:
+                        updates = json.loads(r.read()).get("result", [])
+                except Exception:
+                    updates = []
+                for u in updates:
+                    self._tg_offset = u["update_id"] + 1
+                    msg_text = ((u.get("message") or {}).get("text") or "").strip().lower()
+                    if msg_text in ("y", "yes", "确认", "同意"):
+                        return True
+                    if msg_text in ("n", "no", "拒绝", "取消"):
+                        return False
+                time.sleep(1)
+            return False
+        except Exception:
+            return False
+    def _ask_webhook(self, action: str, amount: float, to: str, timeout_s: int = 15, agent: str = "") -> bool:
+        """Webhook 远程审批: POST 到审核服务, 等 {approved: bool}"""
+        import urllib.request
+        if not self.webhook_url:
+            return False
+        try:
+            body = json.dumps({"action": action, "amount": amount, "to": to, "agent": agent}).encode()
+            req = urllib.request.Request(self.webhook_url, data=body,
+                                         headers={"Content-Type": "application/json"})
+            with urllib.request.urlopen(req, timeout=timeout_s) as r:
+                resp = json.loads(r.read().decode("utf-8", "replace"))
+            return bool(resp.get("approved"))
+        except Exception:
+            return False
+    def protect(self, action: str, max_amount: float = 0.0, agent: str = ""):
+        """
+        装饰器: 给花钱函数加闸门。
+        max_amount: 单次上限(0 = 不限)
+        agent: Agent 身份 ID(建议必填, 未注册默认拒绝)。也可运行时传 kwargs agent=xx
+        函数签名需能取出金额和收款方: 参数名 amount/price/cost + to/recipient/target,
+        或显式传 amount=xx / to=xx(支持位置传参)
+        """
+        def deco(fn: Callable) -> Callable:
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                ag = kwargs.get("agent") or agent or ""
+                amount = self._extract_amount(fn, args, kwargs)
+                to = self._extract_to(fn, args, kwargs)
+                if "agent" in kwargs and "agent" not in inspect.signature(fn).parameters:
+                    kwargs.pop("agent")   # 不透传给业务函数
+                if max_amount > 0 and amount > max_amount:
+                    rec = self._record(action=action, amount=amount, to=to, agent=ag,
+                                       decision="blocked_budget",
+                                       reason=f"单次 ¥{amount:.2f} > 上限 ¥{max_amount:.2f}",
+                                       spent_after=self._spent)
+                    self.log(rec)
+                    if self.on_block:
+                        self.on_block(rec)
+                    raise BudgetExceeded(f"[单次上限] {action} ¥{amount} 超过 ¥{max_amount}")
+                # 通过闸门(执行前记录, 执行后更新已花)
+                rec = self._check(action, amount, to, agent=ag)
+                try:
+                    result = fn(*args, **kwargs)
+                except Exception as e:
+                    rec.decision = "failed"
+                    rec.reason = str(e)[:120]
+                    self.log(rec)
+                    raise
+                self._spent += amount
+                if ag:
+                    self._agent_spent[ag] = self._agent_spent.get(ag, 0.0) + amount
+                self._known_recipients.add(to.lower())   # 交易成功 → 记为已知收款方
+                rec.spent_after = self._spent
+                self.log(rec)
+                return result
+            return wrapper
+        return deco
+    @staticmethod
+    def _extract_amount(fn: Callable, args: tuple, kwargs: dict) -> float:
+        """从参数里找金额: 优先显式 amount=, 其次参数名含 amount/price/cost/价"""
+        if "amount" in kwargs:
+            return float(kwargs["amount"])
+        sig = inspect.signature(fn)
+        names = list(sig.parameters.keys())
+        for i, nm in enumerate(names):
+            if any(k in nm.lower() for k in ("amount", "price", "cost")):
+                if i < len(args):
+                    return float(args[i])
+                if nm in kwargs:
+                    return float(kwargs[nm])
+        return 0.0
+    def get_secret(self, name: str, *, action: str = "取密钥", agent: str = "", to: str = "") -> str:
+        """密钥保险库取用: 必须先过闸门(身份 + 意图审批), 取用留审计。
+        name: 密钥名(视为收款方, 可加白名单免问); 未配置审批通道时新密钥名默认拒绝。"""
+        if self.vault is None:
+            raise ValueError("未配置 KeyVault: SpendShield(key_vault=KeyVault(...))")
+        self._check(action, 0.0, to or name, agent=agent)   # 走身份 + 敏感审批闸门
+        secret = self.vault.retrieve(name)
+        rec = self._record(action=action, amount=0.0, to=to or name, agent=agent,
+                           decision="secret_access", reason=f"密钥 {name} 已取用",
+                           spent_after=self._spent)
+        self.log(rec)
+        return secret
+    def register_agent(self, agent_id: str, *, budget: float = 0.0, max_amount: float = 0.0,
+                       blacklist: Optional[list] = None, whitelist: Optional[list] = None,
+                       rate_limit: Optional[dict] = None, approval: Optional[Any] = None) -> None:
+        """注册 Agent 身份及其专属策略(KYA 最小实现)。未注册的 agent 调用默认被拒。"""
+        if not agent_id:
+            raise ValueError("agent_id 不能为空")
+        self._agents[agent_id] = {
+            "budget": float(budget or 0),
+            "max_amount": float(max_amount or 0),
+            "blacklist": [str(x).lower() for x in (blacklist or [])],
+            "whitelist": [str(x).lower() for x in (whitelist or [])],
+            "rate_limit": rate_limit or {},
+            "approval": approval,
+        }
+    def _agent_policy(self, agent_id: str) -> dict:
+        """解析 Agent 身份: 未注册默认拒绝(安全默认), allow_unknown=True 回落全局策略"""
+        if not agent_id:
+            return {}
+        if agent_id not in self._agents:
+            if self.allow_unknown:
+                return {}
+            raise UnknownAgent(f"未注册的 Agent 身份: {agent_id!r}(先 register_agent 或 allow_unknown=True)")
+        return self._agents[agent_id]
+    @staticmethod
+    def _extract_to(fn: Callable, args: tuple, kwargs: dict) -> str:
+        """从参数里提取收款方: 优先显式 to=, 其次参数名 to/recipient/target(支持位置传参)"""
+        if "to" in kwargs:
+            return str(kwargs["to"])
+        sig = inspect.signature(fn)
+        names = list(sig.parameters.keys())
+        for i, nm in enumerate(names):
+            if nm in ("to", "recipient", "target"):
+                if i < len(args):
+                    return str(args[i])
+                if nm in kwargs:
+                    return str(kwargs[nm])
+        return "(unknown)"
+    def load_policy(self, path: str):
+        """从 YAML 策略文件加载配置(策略即代码)"""
+        import yaml
+        with open(path, encoding="utf-8") as f:
+            cfg = yaml.safe_load(f) or {}
+        for k in ("budget", "dry_run", "approval"):
+            if k in cfg:
+                setattr(self, k, cfg[k])
+        if "max_amount" in cfg:
+            self.default_max_amount = cfg["max_amount"]
+        if cfg.get("blacklist"):
+            self.blacklist = [str(x).lower() for x in cfg["blacklist"]]
+        if cfg.get("whitelist"):
+            self.whitelist = [str(x).lower() for x in cfg["whitelist"]]
+        if cfg.get("rate_limit"):
+            self.rate_limit = cfg["rate_limit"]
+        if cfg.get("tg"):
+            self.tg_token = cfg["tg"].get("token", self.tg_token)
+            self.tg_chat = cfg["tg"].get("chat", self.tg_chat)
+        if cfg.get("webhook_url"):
+            self.webhook_url = cfg["webhook_url"]
+        if cfg.get("allow_unknown") is not None:
+            self.allow_unknown = bool(cfg["allow_unknown"])
+        if cfg.get("approve_new_recipient") is not None:
+            self.approve_new_recipient = bool(cfg["approve_new_recipient"])
+        if cfg.get("approve_above") is not None:
+            self.approve_above = float(cfg["approve_above"])
+        if cfg.get("vault"):
+            from .vault import KeyVault
+            vpath = cfg["vault"].get("path", "spendshield_vault.json")
+            venv = cfg["vault"].get("master_key_env", "SPENDGUARD_MASTER_KEY")
+            mk = os.environ.get(venv) if venv else None
+            if mk:
+                self.vault = KeyVault(vpath, master_key=mk)
+        for aid, aconf in (cfg.get("agents") or {}).items():
+            self.register_agent(aid, **{k: v for k, v in aconf.items()
+                                        if k in ("budget", "max_amount", "blacklist",
+                                                 "whitelist", "rate_limit", "approval")})
+        return self
+    def _authorize(self, action: str, amount: float, to: str, agent: str = "") -> bool:
+        """MCP/程序化调用入口: 走全部闸门, 通过返回 True, 被拦抛异常"""
+        ap = self._agent_policy(agent)
+        amax = float(ap.get("max_amount", 0) or 0) or self.default_max_amount
+        if amax > 0 and amount > amax:
+            rec = self._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="blocked_budget",
+                               reason=f"单次 ¥{amount:.2f} > 上限 ¥{amax:.2f}",
+                               spent_after=self._spent)
+            self.log(rec)
+            raise BudgetExceeded(f"[单次上限] {action} ¥{amount} 超过 ¥{amax}")
+        self._check(action, amount, to, agent=agent)
+        return True
+    def summary(self) -> dict:
+        agents = {
+            k: {
+                "budget": v.get("budget", 0),
+                "spent": round(self._agent_spent.get(k, 0.0), 2),
+                "blocked": sum(1 for r in self.records
+                               if r.agent == k and (r.decision.startswith("blocked") or r.decision == "dry_run")),
+            }
+            for k in self._agents
+        }
+        return {
+            "dry_run": self.dry_run,
+            "budget": self.budget,
+            "spent": round(self._spent, 2),
+            "remaining": round(max(self.budget - self._spent, 0), 2) if self.budget > 0 else None,
+            "records": len(self.records),
+            "blocked": sum(1 for r in self.records if r.decision.startswith("blocked") or r.decision == "dry_run"),
+            "executed": sum(1 for r in self.records if r.decision == "executed"),
+            "known_recipients": len(self._known_recipients),
+            "agents": agents,
+        }
+    def export_audit(self, path: str = "spendshield_audit.json") -> str:
+        """导出审计日志(自动创建父目录)"""
+        d = os.path.dirname(os.path.abspath(path))
+        if d:
+            os.makedirs(d, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump([r.to_dict() for r in self.records], f, ensure_ascii=False, indent=2)
+        return path

spendshield/mcp_server.py ADDED Viewed

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+"""SpendShield MCP Server — AI Agent 直接调用付款护栏
+让 Claude Code / OpenClaw / 任何 MCP 兼容 agent 通过工具调用过 SpendShield 闸门。
+协议: MCP stdio transport (newline-delimited JSON-RPC 2.0)
+工具:
+  - spend_protect: 保护一次花钱操作(走全部闸门)
+  - spend_status:  查询预算/已花/策略状态
+  - spend_audit:   最近审计记录
+  - spend_reset:   重置会话已花金额
+用法:
+  python -m spendshield.mcp                 # 默认无策略
+  python -m spendshield.mcp --policy xx.yaml
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+from .guard import SpendShield, DryRunBlocked, BudgetExceeded, NeedsApproval, UnknownAgent
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_NAME = "spendshield"
+SERVER_VERSION = "0.2.0"
+def _tool_schema(name: str, desc: str, props: dict, required: list) -> dict:
+    return {"name": name, "description": desc,
+            "inputSchema": {"type": "object", "properties": props, "required": required}}
+TOOLS = [
+    _tool_schema("spend_protect", "保护一次花钱操作。走干跑/预算/黑名单/白名单/频率/单次上限闸门。"
+                 "通过返回 ok=true; 被拦返回 ok=false + reason",
+                 {"action": {"type": "string", "description": "操作名, 如 下单/转账/充值"},
+                  "amount": {"type": "number", "description": "金额(元)"},
+                  "to": {"type": "string", "description": "收款方, 如 麦当劳/xxx@example.com"},
+                  "agent": {"type": "string", "description": "调用方 Agent 身份 ID(未注册默认拒绝, 建议必填)"}},
+                 ["action", "amount", "to"]),
+    _tool_schema("spend_status", "查询当前护栏状态: 预算/已花/剩余/拦截统计", {}, []),
+    _tool_schema("spend_audit", "最近审计记录(最多 N 条)",
+                 {"limit": {"type": "integer", "description": "条数, 默认 10"}}, []),
+    _tool_schema("spend_reset", "重置本次会话已花金额(新会话/换预算时用)", {}, []),
+    _tool_schema("secret_get", "从密钥保险库取密钥(过身份+审批闸门, 留审计)。密钥名视为收款方, 可加白名单免问",
+                 {"name": {"type": "string", "description": "密钥名(如 mcd_sk)"},
+                  "agent": {"type": "string", "description": "调用方 Agent 身份 ID"}},
+                 ["name", "agent"]),
+]
+class SpendShieldMCP:
+    def __init__(self, guard: SpendShield):
+        self.guard = guard
+    # ---------- MCP 方法 ----------
+    def initialize(self, params: dict) -> dict:
+        return {"protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION}}
+    def tools_list(self) -> dict:
+        return {"tools": TOOLS}
+    def tools_call(self, name: str, arguments: dict) -> dict:
+        try:
+            result = self._dispatch(name, arguments or {})
+            return {"content": [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}],
+                    "isError": False}
+        except Exception as e:
+            return {"content": [{"type": "text", "text": f"error: {str(e)[:200]}"}],
+                    "isError": True}
+    def _dispatch(self, name: str, args: dict):
+        if name == "spend_protect":
+            return self._protect(args)
+        if name == "spend_status":
+            return self.guard.summary()
+        if name == "spend_audit":
+            limit = int(args.get("limit", 10))
+            return {"records": [r.to_dict() for r in self.guard.records[-limit:]]}
+        if name == "spend_reset":
+            self.guard._spent = 0.0
+            return {"ok": True, "message": "已花金额已重置"}
+        if name == "secret_get":
+            return self._secret_get(args)
+        raise ValueError(f"未知工具: {name}")
+    def _protect(self, args: dict) -> dict:
+        action = args.get("action", "?")
+        amount = float(args.get("amount", 0))
+        to = args.get("to", "?")
+        agent = args.get("agent", "")
+        try:
+            # 手动走闸门(不依赖装饰器): dry_run/黑名单/频率/预算/确认
+            ok = self.guard._authorize(action, amount, to, agent)
+            if not ok:
+                return {"ok": False, "reason": "审批被拒",
+                        "spent": self.guard.spent}
+            self.guard._spent += amount
+            if agent:
+                self.guard._agent_spent[agent] = self.guard._agent_spent.get(agent, 0.0) + amount
+            self.guard._known_recipients.add(to.lower())
+            self.guard._record(action=action, amount=amount, to=to, agent=agent,
+                               decision="executed", reason="mcp 调用通过",
+                               spent_after=self.guard.spent)
+            return {"ok": True, "approved": True, "amount": amount, "to": to,
+                    "spent": self.guard.spent,
+                    "note": "已放行。请在真实支付前调用你的支付接口"}
+        except (DryRunBlocked, BudgetExceeded, NeedsApproval, UnknownAgent) as e:
+            return {"ok": False, "reason": str(e), "spent": self.guard.spent}
+    def _secret_get(self, args: dict) -> dict:
+        name = args.get("name", "")
+        agent = args.get("agent", "")
+        if self.guard.vault is None:
+            return {"ok": False, "reason": "未配置 KeyVault(需设置 SPENDGUARD_MASTER_KEY + vault 路径)"}
+        try:
+            secret = self.guard.get_secret(name, agent=agent)
+            return {"ok": True, "name": name, "secret": secret}
+        except (DryRunBlocked, BudgetExceeded, NeedsApproval, UnknownAgent, KeyError) as e:
+            return {"ok": False, "reason": str(e)}
+    # ---------- JSON-RPC 分发 ----------
+    def handle(self, line: str) -> str | None:
+        """处理一行 JSON-RPC, 返回响应行(通知/错误返回 None)"""
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            return None
+        msg_id = msg.get("id")
+        method = msg.get("method")
+        params = msg.get("params") or {}
+        if method == "initialize":
+            result = self.initialize(params)
+        elif method == "tools/list":
+            result = self.tools_list()
+        elif method == "tools/call":
+            result = self.tools_call(params.get("name", ""), params.get("arguments") or {})
+        elif method == "notifications/initialized":
+            return None
+        elif method == "ping":
+            result = {}
+        else:
+            # 未知方法: 返回错误
+            if msg_id is not None:
+                return json.dumps({"jsonrpc": "2.0", "id": msg_id,
+                                   "error": {"code": -32601, "message": f"method not found: {method}"}})
+            return None
+        if msg_id is None:
+            return None
+        return json.dumps({"jsonrpc": "2.0", "id": msg_id, "result": result}, ensure_ascii=False)
+def main():
+    ap = argparse.ArgumentParser(prog="spendshield-mcp")
+    ap.add_argument("--policy", default=os.environ.get("SPENDGUARD_POLICY", ""),
+                    help="策略文件路径(spendshield.yaml)")
+    ap.add_argument("--budget", type=float, default=0.0)
+    ap.add_argument("--dry-run", action="store_true", default=True, help="干跑模式(默认开)")
+    ap.add_argument("--no-dry-run", action="store_true", help="关闭干跑")
+    args = ap.parse_args()
+    guard = SpendShield(budget=args.budget, dry_run=not args.no_dry_run,
+                       log=lambda rec: print(f"[SpendShield] {rec.decision}: {rec.action} \u00a5{rec.amount} -> {rec.to}", file=sys.stderr))
+    if args.policy:
+        guard.load_policy(args.policy)
+    mcp = SpendShieldMCP(guard)
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        resp = mcp.handle(line)
+        if resp:
+            sys.stdout.write(resp + "\n")
+            sys.stdout.flush()
+if __name__ == "__main__":
+    main()

spendshield/vault.py ADDED Viewed

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""
+SpendShield KeyVault — 密钥保险库(Fireblocks 最小版)
+私钥/令牌加密落盘, 主密钥不落盘(环境变量持有)。
+取密钥必须经过 SpendShield 闸门(身份 + 意图审批), 每次取用留审计。
+用法:
+    from spendshield import SpendShield, KeyVault
+    # 首次: 生成主密钥, 放进环境变量 SPENDGUARD_MASTER_KEY(别落盘!)
+    #   python -c "from spendshield import KeyVault; print(KeyVault.generate_key())"
+    vault = KeyVault("vault.json", master_key=os.environ["SPENDGUARD_MASTER_KEY"])
+    vault.store("mcd_sk", "sk_live_xxxx")          # 加密落盘, 文件里无明文
+    guard = SpendShield(key_vault=vault, approval="console")
+    guard.register_agent("mcd_bot", whitelist=["mcd_sk"])   # 密钥名加白名单免问
+    sk = guard.get_secret("mcd_sk", agent="mcd_bot")        # 过闸门才能取
+"""
+from __future__ import annotations
+import json
+import os
+from typing import Optional
+from cryptography.fernet import Fernet
+class KeyVault:
+    """加密密钥保险库: AES128-CBC + HMAC(Fernet), 主密钥不落盘"""
+    def __init__(self, path: str = "spendshield_vault.json", master_key: Optional[str] = None):
+        self.path = path
+        if master_key is None:
+            master_key = os.environ.get("SPENDGUARD_MASTER_KEY")
+        if not master_key:
+            raise ValueError(
+                "需要主密钥: 传入 master_key 或设置环境变量 SPENDGUARD_MASTER_KEY "
+                "(用 KeyVault.generate_key() 生成)"
+            )
+        if isinstance(master_key, str):
+            master_key = master_key.encode()
+        self._fernet = Fernet(master_key)
+        self._data = self._load()
+    @staticmethod
+    def generate_key() -> str:
+        """生成主密钥(仅打印一次, 放进环境变量, 别落盘)"""
+        return Fernet.generate_key().decode()
+    def store(self, name: str, value: str) -> None:
+        """加密存储密钥(落盘文件里只有密文)"""
+        if not name or not value:
+            raise ValueError("name/value 不能为空")
+        self._data[name] = self._fernet.encrypt(value.encode()).decode()
+        self._save()
+    def retrieve(self, name: str) -> str:
+        """解密取回密钥(调用方负责先过 SpendShield 闸门)"""
+        if name not in self._data:
+            raise KeyError(f"密钥不存在: {name}")
+        return self._fernet.decrypt(self._data[name].encode()).decode()
+    def names(self) -> list:
+        return sorted(self._data.keys())
+    def _load(self) -> dict:
+        if os.path.exists(self.path):
+            with open(self.path, encoding="utf-8") as f:
+                return json.load(f)
+        return {}
+    def _save(self) -> None:
+        with open(self.path, "w", encoding="utf-8") as f:
+            json.dump(self._data, f, indent=2)

spendshield-0.6.0.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: spendshield
+Version: 0.6.0
+Summary: AI Agent 付款安全层: 干跑/预算/人工确认/审计 四道闸门
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41
+# 💰 SpendShield — AI Agent 付款安全层
+> **AI 替你花钱之前，先过 SpendShield 这关。**
+让 AI Agent 下单、转账、调付费 API 之前，自动过四道闸门：
+**干跑预览 → 预算上限 → 人工确认 → 全量审计。**
+## 🩸 为什么会有这个项目（真实事故）
+2026 年 8 月 9 日，我的自动化系统测试下单。
+我传了 `dry: true`，以为只是试算价格。但服务器只认 `?dry=1` —— **4 单 99 元真实出码扣款，当天全部打水漂。**
+这不是我一个人的坑。AI Agent 时代正在到来：Agent 替你订餐、替你充值、替你调付费 API——**当 AI 开始花真钱，谁给它上闸门？**
+我把我踩过的坑，做成了一个库。
+## ✨ 四道闸门
+| 闸门 | 默认 | 作用 |
+|------|------|------|
+| 🧪 **dry_run** 干跑 | ✅ 开 | 只预览不执行——`dry` 参数失效也无所谓，库层面兜底 |
+| 💰 **budget** 预算 | 不限 | 总预算超支直接拒绝，绝不超花 |
+| 🚧 **max_amount** 单次上限 | 不限 | 单笔超限拦截（防"转 9999 给陌生人"） |
+| 🙋 **approval** 人工确认 | 关 | 花钱前必须人点头（console / 回调） |
+| 📜 **audit** 审计 | ✅ 开 | 每次尝试全留痕，导出 JSON 对账 |
+## 🔑 身份层（KYA 最小实现，v0.4）
+AI 没有法律人格，但必须有“数字身份”。每个 agent 注册专属策略，**未注册默认拒绝**：
+```python
+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)
+```
+- 未注册的 agent 调用 → 直接拒绝（`UnknownAgent`），审计留痕 `blocked_unknown_agent`
+- `allow_unknown: true` 可回落全局策略（不推荐）
+- 每条审计记录带 `agent` 字段：**谁在花、花给谁、用户知不知道**
+- 策略即代码支持 `agents:` 段（YAML），预算/黑名单/频率/审批按 agent 隔离
+## 🎯 意图一致性（防提示注入，v0.5）
+AI 可能被劫持：提示注入、返利诱惑……闸门只知道“花多少、给谁”，不知道“这是用户要的吗”。
+解法：**敏感操作强制人工确认**——即使没配全局审批，新收款方/大额也默认拦下：
+```python
+# 新收款方（从未交易过）→ 必须确认；没配审批通道 → 直接拒绝
+# 金额 > approve_above → 必须确认
+guard = SpendShield(approve_new_recipient=True, approve_above=1000)
+```
+- 交易成功的收款方自动进入记忆，之后不再反复烦你
+- 白名单收款方永远跳过
+- 未配置审批通道时，敏感操作**直接拒绝**（宁可拦死，不放行）
+- 拦截记录 `blocked_approval` 带原因：新收款方 / 超阈值 / 未配置通道
+## 🔐 密钥保险库（v0.6）
+私钥不落地是 AI 支付的命门——**一次泄露，钱包被掏空**。密钥加密落盘，主密钥放环境变量，取用必须过闸门：
+```bash
+python -c "from spendshield import KeyVault; print(KeyVault.generate_key())"  # 生成主密钥(仅此一次)
+export SPENDGUARD_MASTER_KEY=<刚才的输出>   # 放环境变量, 别写进代码/仓库
+```
+```python
+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")   # 过身份+意图闸门才能取
+```
+- 落盘文件无明文（AES128-CBC + HMAC）；主密钥不落盘
+- 取密钥 = 敏感操作：未注册 agent 拒绝；新密钥名无审批通道默认拒绝（防提示注入偷密钥）
+- 每次取用留审计 `secret_access`：谁、何时、取了哪个密钥
+## 🚀 快速开始
+```bash
+pip install spendshield   # 或直接 clone 用
+```
+```python
+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 拦住
+```
+> 💡 新收款方默认需人工确认(意图一致性, 防提示注入)——把常用收款方加白名单或注册 Agent 身份可免。
+## 🎯 谁需要它
+- **AI Agent 框架用户**：给你的 Agent 工具加装饰器，一行接入
+- **自动化系统运维**：批量任务/定时下单，防误操作真扣款
+- **MCP / Function Call 开发者**：LLM 生成的工具调用，过闸门再执行
+- **所有被"测试单变真单"坑过的人** 🩸
+## 🗺 Roadmap
+- [x] v0.1 四道闸门 + 审计 + 装饰器接入
+- [ ] 收款方黑名单/白名单（陌生收款方强制确认）
+- [ ] 频率限制（同一收款方短时间 N 次）
+- [ ] MCP server 版（Agent 工具调用直接过闸）
+- [ ] 远程审批（企业微信/Telegram 确认）
+- [ ] 多策略插件（风控规则引擎）
+## 🧪 测试
+```bash
+python3 tests/test_guard.py   # 6 个测试全过
+```
+## 📄 License
+MIT — 拿去用。愿 AI 时代，没人再被"测试单"坑第二次。
+---
+**⭐ 如果这个项目对你有用，点个 star，让更多被坑过的人看到。**
+## 🤖 MCP Server（AI Agent 直接调用）
+让 Claude Code / OpenClaw 等 MCP 兼容 agent 直接通过工具调用过闸门：
+```bash
+# 启动(stdio 模式, agent 配置里指向它)
+python -m spendshield.mcp_server --policy spendshield.yaml
+# 或安装后: spendshield-mcp --policy spendshield.yaml
+```
+**工具**：
+- `spend_protect(action, amount, to)` — 保护一次花钱操作（走全部闸门）
+- `spend_status()` — 预算/已花/拦截统计
+- `spend_audit(limit)` — 最近审计记录
+- `spend_reset()` — 重置会话已花
+```json
+// agent 调用示例
+{"name": "spend_protect", "arguments": {"action": "下单", "amount": 99, "to": "麦当劳"}}
+// => {"ok": false, "reason": "[干跑] 下单 ¥99.0 -> 麦当劳 (未执行...)", "spent": 0.0}
+```

spendshield-0.6.0.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,10 @@
+spendshield/__init__.py,sha256=78FpUvPzqGfpLMTJmlXwVWwD606QE5ghSfJpH_IV6B8,1156
+spendshield/dashboard.py,sha256=Tse5yuvCTV96wTqJKelAumr0fLZEcrTHjQ64qw_J9jY,5399
+spendshield/guard.py,sha256=ByfgB7Ya-_DtsErt82fg22ah6KS_U6sXlfBN87sJR2U,25047
+spendshield/mcp_server.py,sha256=058Yqebq9oS0Wt1KUhcry4OL3EDaHvhF-qvMnJPZOfQ,8091
+spendshield/vault.py,sha256=hiQXrA-WlLsPM7efTaxQtdVu4z_-xSqo6AqugSsc0Ek,2850
+spendshield-0.6.0.dist-info/METADATA,sha256=l26HOIB-t7FQ56IwYOluck5s9rb8Rwvs8Qapd1XWfZ0,6948
+spendshield-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+spendshield-0.6.0.dist-info/entry_points.txt,sha256=NSq5hGFyI-jUBxyJ7oEeewi4MrdtCHVbSHxbSGyxrco,64
+spendshield-0.6.0.dist-info/top_level.txt,sha256=kQijlfLgo8JstfcO06W2qk_XeQpj3S5utRGfafE_e_w,12
+spendshield-0.6.0.dist-info/RECORD,,

spendshield-0.6.0.dist-info/WHEEL ADDED Viewed

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

spendshield-0.6.0.dist-info/entry_points.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [console_scripts]
2	+ spendshield-mcp = spendshield.mcp_server:main

spendshield-0.6.0.dist-info/top_level.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+ spendshield