@bolloon/bolloon-agent 0.4.11 → 0.4.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yuanjie liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -98,11 +98,17 @@ npm start
 | `OPENAI_API_KEY` | OpenAI 提供商（可选） |
 | `DEEPSEEK_API_KEY` | DeepSeek 提供商（可选） |
 | `ANTHROPIC_API_KEY` | Anthropic 提供商（可选） |
-| `BOLLOON_LLM_PROVIDER` | 指定 LLM 提供商 |
-
----
-
-<a name="english"></a>
+| `BOLLOON_LLM_PROVIDER` | 指定 LLM 提供商 |
+
+---
+
+## 开源协议
+
+本项目基于 [MIT 开源协议](./LICENSE) 发布。你可以自由使用、修改、分发本项目，但需保留版权声明和许可声明。详见 [LICENSE](./LICENSE) 文件。
+
+---
+
+<a name="english"></a>
 
 ## English
 
@@ -130,6 +136,6 @@ bolloon --help     # All commands
 
 Requires Node.js ≥ 18 and an LLM API key (`OPENAI_API_KEY` or `DEEPSEEK_API_KEY`).
 
-### License
-
-MIT
+### License
+
+This project is released under the [MIT License](./LICENSE). You are free to use, modify, and distribute this project, provided that you retain the copyright and permission notices. See the [LICENSE](./LICENSE) file for details.

package/dist/agents/agent-registry.js

@@ -0,0 +1,151 @@
+/**
+ * agent-registry.ts — Agent 服务注册表 (2026-08-13, Phase E1)
+ *
+ * Agent Economic Network 的 Discovery 层: Agent 注册服务 (定价/能力声明/钱包),
+ * 其他 Agent 发现并调用.
+ *
+ * 存储: OrbitDB keyvalue 主存储 (去中心化, 跨设备同步) + 本地 JSON fallback.
+ *   复用 task-store 模式 (getCIDDatabase.openStore).
+ * 设计: registry 存整个服务列表到单键 'services' (兼容简单).
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { getCIDDatabase } from '../orbitdb/cid-database.js';
+const home = () => process.env.HOME || os.homedir() || '/tmp';
+export const REGISTRY_ORBIT_KEY = 'services';
+/** OrbitDB store 名 (按 did 短名确定性) */
+export function registryStoreName(did) {
+    const short = String(did || 'local').replace(/[^a-zA-Z0-9-]/g, '_').slice(0, 40) || 'local';
+    return `bolloon-agent-registry-${short}`;
+}
+/** 真实实现 (OrbitDB + 本地 fallback). 单例: 共享 CID 数据库单例. */
+export class OrbitDBAgentRegistry {
+    did;
+    db;
+    localFile;
+    _store = null;
+    ready = false;
+    storeName;
+    storeAddress = '';
+    constructor(did, db = getCIDDatabase(), localFile = path.join(home(), '.bolloon', 'agent-registry.json')) {
+        this.did = did;
+        this.db = db;
+        this.localFile = localFile;
+        this.storeName = registryStoreName(did);
+    }
+    async warm() {
+        if (this.ready && this._store)
+            return true;
+        try {
+            this._store = await this.db.openStore(this.storeName, 'keyvalue');
+            this.storeAddress = this._store.address;
+            this.ready = true;
+            return true;
+        }
+        catch {
+            this.ready = false;
+            return false;
+        }
+    }
+    async loadLocalFromDisk() {
+        try {
+            const { readFile } = await import('fs/promises');
+            const parsed = JSON.parse(await readFile(this.localFile, 'utf-8'));
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveLocalToDisk(list) {
+        try {
+            const { mkdir, writeFile } = await import('fs/promises');
+            await mkdir(path.dirname(this.localFile), { recursive: true });
+            await writeFile(this.localFile, JSON.stringify(list, null, 2), 'utf-8');
+        }
+        catch { /* 本地写失败静默 */ }
+    }
+    async loadLocal() {
+        return this.loadLocalFromDisk();
+    }
+    /** OrbitDB 读全部服务 (失败 → null) */
+    async orbitList() {
+        if (!this.ready || !this._store)
+            return null;
+        try {
+            const v = await this._store.get(REGISTRY_ORBIT_KEY);
+            if (Array.isArray(v))
+                return v;
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async register(service) {
+        if (!service || !service.agentId || !service.service?.name) {
+            return { ok: false, error: 'agentId 和 service.name 必填' };
+        }
+        // 本地双写 (fallback 源)
+        const local = await this.loadLocalFromDisk();
+        const idx = local.findIndex((s) => s.agentId === service.agentId);
+        const now = new Date().toISOString();
+        const entry = { ...service, updatedAt: now, registeredAt: service.registeredAt || now };
+        if (idx >= 0)
+            local[idx] = entry;
+        else
+            local.push(entry);
+        await this.saveLocalToDisk(local);
+        // OrbitDB 写穿 (尽力而为)
+        if (this.ready && this._store) {
+            try {
+                const orbit = (await this.orbitList()) ?? [];
+                const oi = orbit.findIndex((s) => s.agentId === service.agentId);
+                if (oi >= 0)
+                    orbit[oi] = entry;
+                else
+                    orbit.push(entry);
+                await this._store.put(REGISTRY_ORBIT_KEY, orbit);
+            }
+            catch { /* orbit 写失败静默 */ }
+        }
+        return { ok: true };
+    }
+    async list() {
+        // OrbitDB 优先
+        const orbit = await this.orbitList();
+        if (orbit !== null)
+            return orbit;
+        return this.loadLocalFromDisk();
+    }
+    async discover(query) {
+        const all = await this.list();
+        const q = String(query || '').trim().toLowerCase();
+        if (!q)
+            return all;
+        return all.filter((s) => s.service?.name?.toLowerCase().includes(q) ||
+            s.service?.description?.toLowerCase().includes(q) ||
+            s.name?.toLowerCase().includes(q) ||
+            s.capabilities?.some((c) => c.toLowerCase().includes(q)));
+    }
+}
+let _instance = null;
+let _warmPromise = null;
+/** 获取 Agent Registry 单例 (首次调用 warm). */
+export function getAgentRegistry(did = '') {
+    if (!_instance)
+        _instance = new OrbitDBAgentRegistry(did || 'local');
+    return _instance;
+}
+/** 预热 Registry (server 启动调用). */
+export function warmAgentRegistry(did = '') {
+    if (!_warmPromise) {
+        _warmPromise = getAgentRegistry(did).warm().then((ok) => ok).catch(() => false);
+    }
+    return _warmPromise;
+}
+/** 重置单例 (测试用) */
+export function resetAgentRegistry() {
+    _instance = null;
+    _warmPromise = null;
+}

package/dist/agents/agent-reputation.js

@@ -0,0 +1,54 @@
+/**
+ * agent-reputation.ts — Agent 信誉系统 (2026-08-13, Phase M4)
+ *
+ * Agent Economic Protocol §7 Reputation: "Should I trust you?"
+ * 每次服务结算后更新: tasks++ / success++ | failed++ | disputed++,
+ * score = success / tasks. 存 Registry 的 service.reputation.
+ *
+ * 使用: provider 完成服务后调 recordOutcome(agentId, serviceName, outcome),
+ *       buyer 调用前可查询 (registry 已带 reputation).
+ */
+import { getAgentRegistry } from './agent-registry.js';
+/**
+ * 记录一次服务结果, 更新 provider 信誉.
+ * 找不到服务 → 错误 (需先 registry_register).
+ */
+export async function recordServiceOutcome(agentId, serviceName, outcome, registry) {
+    const reg = registry ?? getAgentRegistry();
+    const services = await reg.list();
+    const idx = services.findIndex((s) => s.agentId === agentId && s.service?.name === serviceName);
+    if (idx < 0) {
+        return { ok: false, error: `服务未注册: ${agentId}/${serviceName} (先 registry_register)` };
+    }
+    const svc = services[idx];
+    const rep = svc.reputation ?? { tasks: 0, success: 0, failed: 0, disputed: 0, score: 0 };
+    rep.tasks += 1;
+    if (outcome === 'success')
+        rep.success += 1;
+    else if (outcome === 'failed')
+        rep.failed += 1;
+    else
+        rep.disputed += 1;
+    rep.score = rep.tasks > 0 ? Math.round((rep.success / rep.tasks) * 100) / 100 : 0;
+    svc.reputation = rep;
+    const r = await reg.register(svc);
+    if (!r.ok)
+        return { ok: false, error: r.error };
+    return { ok: true, reputation: rep };
+}
+/** 查询 Agent 信誉 (Registry 读取) */
+export async function queryReputation(agentId, serviceName, registry) {
+    const reg = registry ?? getAgentRegistry();
+    const services = await reg.list();
+    const entries = services
+        .filter((s) => s.agentId === agentId && (!serviceName || s.service?.name === serviceName))
+        .map((s) => ({
+        service: s.service?.name || '?',
+        reputation: s.reputation ?? { tasks: 0, success: 0, failed: 0, disputed: 0, score: 0 },
+    }));
+    return { ok: entries.length > 0, entries, error: entries.length === 0 ? `agent ${agentId} 无服务记录` : undefined };
+}
+/** 格式化信誉 (agent 工具输出用) */
+export function formatReputation(rep) {
+    return `✅ ${rep.success} / ${rep.tasks} 任务 (score=${rep.score})${rep.failed ? `, ❌ failed=${rep.failed}` : ''}${rep.disputed ? `, ⚠️ disputed=${rep.disputed}` : ''}`;
+}

package/dist/agents/agent-service-client.js

@@ -0,0 +1,147 @@
+/**
+ * agent-service-client.ts — Agent 服务调用闭环 (2026-08-13, Phase E2)
+ *
+ * Agent Economic Network 的 Execution+Payment 层:
+ *   buyer: 从 Registry 发现服务 → 调服务端点 → 收到 402 → x402 自动支付 → 拿结果
+ *   provider: 基于 Registry 价格生成 402 响应 → 收钱 → 提供服务
+ *
+ * 复用: x402Pay.ts 的 x402Fetch (自动 402→支付→重试) + x402RequestPayment (生成 402).
+ * MVP: 闭环逻辑可测 (mock fetch), 真实链上支付需 funded wallet.
+ */
+import { getAgentRegistry } from './agent-registry.js';
+/**
+ * buyer 侧: 调用 Agent 服务 (402 自动支付).
+ * 流程: registry 发现 → x402Fetch(url) → 402 → 自动签名支付 → 服务结果
+ */
+export async function serviceCall(opts) {
+    const { serviceName, args, privateKey, url, maxPaymentAmount, registry } = opts;
+    // 1. 从 Registry 发现服务
+    const reg = registry ?? getAgentRegistry();
+    const services = await reg.discover(serviceName);
+    if (services.length === 0) {
+        return { success: false, error: `注册表未找到服务: ${serviceName}` };
+    }
+    const service = services[0];
+    // 2. 确定端点
+    const endpoint = url || service.endpoint;
+    if (!endpoint) {
+        return { success: false, error: `服务 ${serviceName} 无端点 (endpoint), 无法调用`, service };
+    }
+    // 3. 调服务 (x402 自动支付: 402 → 签名 → 重试)
+    try {
+        const { x402Fetch } = await import('./x402/x402Pay.js');
+        // 2026-08-13: YAML 验证门 (不全部交给 AI) — 支付前先过 payment-policy.yaml 规则链
+        const { getPaymentGate } = await import('./payment-gate.js');
+        const gate = getPaymentGate();
+        const amount = parseFloat(service.service?.price?.amount || '0');
+        const gateVerdict = gate.evaluate({ service: service.service?.name, amount, recipient: service.wallet });
+        if (gateVerdict.decision === 'deny') {
+            return { success: false, error: `[payment-gate] ${gateVerdict.reason}`, service };
+        }
+        if (gateVerdict.decision === 'confirm') {
+            // 2026-08-13: 人工审批 — 创建 pending 审批请求 (不自动执行), UI/CLI 批准后重试
+            const { getApprovalStore } = await import('./payment-approval.js');
+            const store = getApprovalStore();
+            const approval = await store.create({
+                service: service.service?.name || serviceName,
+                amount,
+                recipient: service.wallet,
+                reason: gateVerdict.reason,
+                retryPayload: { serviceName, args, privateKey, maxPaymentAmount: maxPaymentAmount || service.service?.price?.amount },
+            });
+            return {
+                success: false,
+                error: `[payment-gate] 需人工确认: ${gateVerdict.reason} (approval=${approval.id}, 批准后自动执行)`,
+                service,
+                requiresApproval: true,
+                approvalId: approval.id,
+            };
+        }
+        // Phase E3: Policy Engine 授权 (预算/白名单) — 通过才允许自动支付
+        let effectiveKey = privateKey;
+        if (privateKey) {
+            const { getEconomicPolicy } = await import('./economic-policy.js');
+            const policy = getEconomicPolicy();
+            const decision = await policy.check({
+                payTo: service.wallet,
+                amount,
+                currency: service.service?.price?.currency,
+                service: service.service?.name,
+                timestamp: Date.now(),
+            });
+            if (!decision.allowed) {
+                return { success: false, error: `[policy] ${decision.reason}`, service };
+            }
+            effectiveKey = privateKey; // policy 通过 → 允许签名支付
+            // 记录花费 (结算后) — 预记, 实际结算在链上
+            await policy.recordSpend(amount).catch(() => { });
+        }
+        const result = await x402Fetch({
+            url: endpoint,
+            method: 'POST',
+            body: JSON.stringify(args || {}),
+            headers: { 'Content-Type': 'application/json' },
+            privateKey: effectiveKey,
+            maxPaymentAmount: maxPaymentAmount || service.service?.price?.amount,
+        });
+        if (!result.success) {
+            return { success: false, error: result.error || 'x402 调用失败', service };
+        }
+        // 有 paymentInfo 说明经过了 402 支付; data 是服务结果
+        const paid = !!result.paymentInfo || (result.status ?? 0) >= 200;
+        return {
+            success: true,
+            service,
+            paid,
+            output: typeof result.data === 'string' ? result.data : JSON.stringify(result.data ?? ''),
+        };
+    }
+    catch (e) {
+        return { success: false, error: `服务调用异常: ${e?.message}`, service };
+    }
+}
+/**
+ * provider 侧: 生成 x402 402 响应 (基于 Registry 价格).
+ * 返回 402 响应对象 (含 PaymentRequired header 语义), 供服务端点使用.
+ */
+export async function serviceRequestPayment(agentId, serviceName, registry) {
+    const reg = registry ?? getAgentRegistry();
+    const services = await reg.list();
+    const service = services.find((s) => s.agentId === agentId && s.service?.name === serviceName);
+    if (!service) {
+        return { error: `agent ${agentId} 未注册服务 ${serviceName}` };
+    }
+    const price = parseFloat(service.service.price.amount || '0');
+    const currency = service.service.price.currency || 'USDC';
+    const payTo = service.wallet;
+    if (!payTo)
+        return { error: '服务无收款钱包' };
+    return {
+        price,
+        currency,
+        payTo,
+        resourceDescription: `${serviceName} service by ${service.name}`,
+    };
+}
+/**
+ * provider 侧: 基于 Registry 价格生成 402 PaymentRequired 响应体.
+ * 复用 x402RequestPayment.
+ */
+export async function buildPaymentRequiredResponse(agentId, serviceName, registry) {
+    const info = await serviceRequestPayment(agentId, serviceName, registry);
+    if ('error' in info) {
+        return { status: 500, headers: {}, body: JSON.stringify({ error: info.error }) };
+    }
+    const { x402RequestPayment } = await import('./x402/x402Pay.js');
+    const r = x402RequestPayment({
+        price: info.price,
+        currency: info.currency,
+        payTo: info.payTo,
+        resourceDescription: info.resourceDescription,
+    });
+    return {
+        status: r.statusCode,
+        headers: r.headers,
+        body: r.body,
+    };
+}

package/dist/agents/economic-policy.js

@@ -0,0 +1,132 @@
+/**
+ * economic-policy.ts — Policy Engine (2026-08-13, Phase E3)
+ *
+ * Agent 支付授权安全核心 (参考 arXiv:2605.30998 free-riding 防护):
+ *   LLM 只见 Payment Intent, 不见私钥; Policy Engine 是唯一签名入口.
+ *
+ * 规则:
+ *   - amount < per_transaction_limit
+ *   - recipient (payTo) in allowed
+ *   - service in allowed
+ *   - daily budget not exceeded (冻结)
+ *   - 速率限制 (rate limit)
+ *
+ * 预算持久化: ~/.bolloon/economic-policy.json (daily spend 滚动).
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+const home = () => process.env.HOME || os.homedir() || '/tmp';
+/** 默认策略 (保守) */
+const DEFAULT_CONFIG = {
+    perTransactionLimit: 1, // 单笔 ≤ $1
+    dailyLimit: 10, // 每日 ≤ $10
+    allowedRecipients: [],
+    allowedServices: [],
+    rateLimitPerMinute: 5,
+};
+export class LocalEconomicPolicy {
+    cfg = { ...DEFAULT_CONFIG };
+    file;
+    /** 支付时间戳窗口 (速率限制) */
+    payTimestamps = [];
+    /** 今日花费 */
+    _dailySpent = 0;
+    _dayKey = '';
+    constructor(file = path.join(home(), '.bolloon', 'economic-policy.json')) {
+        this.file = file;
+    }
+    config() { return { ...this.cfg }; }
+    updateConfig(patch) {
+        this.cfg = { ...this.cfg, ...patch };
+    }
+    /** 加载持久化 (daily spend 跨重启) */
+    async load() {
+        try {
+            const raw = JSON.parse(await fs.readFile(this.file, 'utf-8'));
+            if (raw.dailySpent !== undefined)
+                this._dailySpent = Number(raw.dailySpent) || 0;
+            if (raw.dayKey)
+                this._dayKey = raw.dayKey;
+            if (raw.config)
+                this.cfg = { ...DEFAULT_CONFIG, ...raw.config };
+            await this.resetIfNewDay();
+        }
+        catch { /* 无持久化, 用默认 */ }
+    }
+    async persist() {
+        try {
+            await fs.mkdir(path.dirname(this.file), { recursive: true });
+            await fs.writeFile(this.file, JSON.stringify({
+                dailySpent: this._dailySpent,
+                dayKey: this._dayKey,
+                config: this.cfg,
+            }, null, 2), 'utf-8');
+        }
+        catch { /* 持久化失败静默 */ }
+    }
+    async dailySpent() {
+        await this.resetIfNewDay();
+        return this._dailySpent;
+    }
+    async resetIfNewDay() {
+        const today = new Date().toISOString().slice(0, 10);
+        if (this._dayKey !== today) {
+            this._dayKey = today;
+            this._dailySpent = 0;
+            this.payTimestamps = [];
+            await this.persist();
+        }
+    }
+    async check(intent) {
+        await this.resetIfNewDay();
+        const amount = Number(intent.amount) || 0;
+        const payTo = String(intent.payTo || '').toLowerCase();
+        const service = String(intent.service || '').toLowerCase();
+        // 1. 单笔上限
+        if (amount > this.cfg.perTransactionLimit) {
+            return { allowed: false, reason: `单笔超限: ${amount} > ${this.cfg.perTransactionLimit}`, dailySpent: this._dailySpent };
+        }
+        // 2. 收款方白名单
+        if (this.cfg.allowedRecipients.length > 0 &&
+            !this.cfg.allowedRecipients.some((r) => r.toLowerCase() === payTo)) {
+            return { allowed: false, reason: `收款方不在白名单: ${payTo}`, dailySpent: this._dailySpent };
+        }
+        // 3. 服务白名单
+        if (service && this.cfg.allowedServices.length > 0 &&
+            !this.cfg.allowedServices.some((s) => s.toLowerCase() === service)) {
+            return { allowed: false, reason: `服务不在白名单: ${service}`, dailySpent: this._dailySpent };
+        }
+        // 4. 每日预算
+        if (this._dailySpent + amount > this.cfg.dailyLimit) {
+            return { allowed: false, reason: `日预算超限: ${this._dailySpent} + ${amount} > ${this.cfg.dailyLimit}`, dailySpent: this._dailySpent };
+        }
+        // 5. 速率限制
+        const now = Date.now();
+        this.payTimestamps = this.payTimestamps.filter((t) => now - t < 60_000);
+        if (this.payTimestamps.length >= this.cfg.rateLimitPerMinute) {
+            return { allowed: false, reason: `速率超限 (${this.cfg.rateLimitPerMinute}/min)`, dailySpent: this._dailySpent };
+        }
+        return { allowed: true, dailySpent: this._dailySpent };
+    }
+    async recordSpend(amount) {
+        await this.resetIfNewDay();
+        this._dailySpent += Number(amount) || 0;
+        this.payTimestamps.push(Date.now());
+        await this.persist();
+    }
+}
+let _instance = null;
+/** 获取 Policy Engine 单例 */
+export function getEconomicPolicy() {
+    if (!_instance) {
+        const p = new LocalEconomicPolicy();
+        void p.load();
+        _instance = p;
+    }
+    return _instance;
+}
+/** 重置单例 (测试用) */
+export function resetEconomicPolicy() {
+    _instance = null;
+}

package/dist/agents/payment-approval.js

@@ -0,0 +1,142 @@
+/**
+ * payment-approval.ts — 人工支付审批 (2026-08-13)
+ *
+ * YAML 支付验证门 (payment-gate) 判定 confirm 的支付请求 → 进入人工审批流程:
+ *   - createApproval: 创建 pending 审批请求 (持久化)
+ *   - approve(id): 人工批准 → 自动重试支付 (executor)
+ *   - reject(id): 人工拒绝
+ *   - list/pending: 查询
+ *
+ * 持久化: ~/.bolloon/payment-approvals.json
+ * 审批后执行: 注入 executor (serviceCall 重试 / 链上支付), 由调用方提供.
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const home = () => process.env.HOME || os.homedir() || '/tmp';
+let _executor = null;
+/** 注入批准后执行器 (serviceCall 重试 / 链上支付) */
+export function setApprovalExecutor(fn) {
+    _executor = fn;
+}
+export class PaymentApprovalStore {
+    file;
+    approvals = [];
+    constructor(file = path.join(home(), '.bolloon', 'payment-approvals.json')) {
+        this.file = file;
+    }
+    async load() {
+        try {
+            const raw = JSON.parse(await fs.readFile(this.file, 'utf-8'));
+            if (Array.isArray(raw))
+                this.approvals = raw;
+        }
+        catch {
+            this.approvals = [];
+        }
+    }
+    async persist() {
+        try {
+            await fs.mkdir(path.dirname(this.file), { recursive: true });
+            await fs.writeFile(this.file, JSON.stringify(this.approvals, null, 2), 'utf-8');
+        }
+        catch { /* 静默 */ }
+    }
+    /** 创建审批请求 (pending) */
+    async create(req) {
+        await this.load();
+        const approval = {
+            id: `pay-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+            service: req.service,
+            amount: req.amount,
+            recipient: req.recipient,
+            reason: req.reason,
+            status: 'pending',
+            createdAt: Date.now(),
+            retryPayload: req.retryPayload,
+        };
+        this.approvals.push(approval);
+        await this.persist();
+        return approval;
+    }
+    /** 待审批列表 */
+    async pending() {
+        await this.load();
+        return this.approvals.filter((a) => a.status === 'pending');
+    }
+    /** 全部 (含历史) */
+    async list() {
+        await this.load();
+        return [...this.approvals].reverse();
+    }
+    async get(id) {
+        await this.load();
+        return this.approvals.find((a) => a.id === id) ?? null;
+    }
+    /**
+     * 人工批准 → 执行支付 (executor) → executed/failed.
+     * 未注入 executor 时直接标记 approved (调用方自行处理).
+     */
+    async approve(id, approver = 'user') {
+        await this.load();
+        const a = this.approvals.find((x) => x.id === id);
+        if (!a)
+            return { ok: false, error: `审批 ${id} 不存在` };
+        if (a.status !== 'pending')
+            return { ok: false, error: `审批 ${id} 状态 ${a.status}, 不可批准` };
+        a.status = 'approved';
+        a.decidedAt = Date.now();
+        await this.persist();
+        // 批准后执行支付
+        if (_executor) {
+            const r = await _executor(a);
+            a.status = r.ok ? 'executed' : 'failed';
+            a.result = r.ok ? r.result : r.error;
+            await this.persist();
+            if (!r.ok)
+                return { ok: false, approval: a, error: r.error };
+        }
+        return { ok: true, approval: a };
+    }
+    /** 人工拒绝 */
+    async reject(id, approver = 'user') {
+        await this.load();
+        const a = this.approvals.find((x) => x.id === id);
+        if (!a)
+            return { ok: false, error: `审批 ${id} 不存在` };
+        if (a.status !== 'pending')
+            return { ok: false, error: `审批 ${id} 状态 ${a.status}, 不可拒绝` };
+        a.status = 'rejected';
+        a.decidedAt = Date.now();
+        await this.persist();
+        return { ok: true, approval: a };
+    }
+    /** 清理过期 pending (超时自动标记 rejected) */
+    async expireStale(timeoutMs = 60 * 60 * 1000) {
+        await this.load();
+        const now = Date.now();
+        let expired = 0;
+        for (const a of this.approvals) {
+            if (a.status === 'pending' && now - a.createdAt > timeoutMs) {
+                a.status = 'rejected';
+                a.decidedAt = now;
+                a.result = '审批超时自动拒绝';
+                expired++;
+            }
+        }
+        if (expired > 0)
+            await this.persist();
+        return expired;
+    }
+}
+let _store = null;
+/** 单例 */
+export function getApprovalStore() {
+    if (!_store)
+        _store = new PaymentApprovalStore();
+    return _store;
+}
+export function resetApprovalStore() {
+    _store = null;
+    _executor = null;
+}