EthersFlow — Trust Gate for AI Agents

EthersFlow — Agent 操作验证层（KYAA）

EthersFlow MCP 是 AI Agent 的操作验证层（KYAA — Know Your Agent's Action，了解 Agent 的操作）。一个由独立模型组成的对抗性委员会会审查 Agent 即将执行的操作，并在执行前返回一份带签名、可独立验证的裁决。

---

概述

KYA 用于确认 Agent 的身份及其获准执行的操作。KYAA（Know Your Agent's Action，了解 Agent 的操作）则逐一验证 Agent 实际执行的操作，并为每项操作签名。身份让 Agent 得以进入，验证则决定它能带着什么离开。

EthersFlow 是一道操作关卡：它决定是否应执行 Agent 的下一项操作，并用带签名、可独立验证的证据对自己的决定进行公证。没有证据的强制执行就是黑箱；没有强制执行的证据，不过是在损失造成后留下的审计日志。EthersFlow 是兼具两者的检查点。

Agent 治理栈

+-------------------+      +-------------------+      +-------------------------+      +-------------------+
| 1. IDENTITY (KYA) | ---> | 2. AUTHORIZATION  | ---> | 3. ACTION VERIFICATION  | ---> | 4. EXECUTION      |
|                   |      |                   |      |    (KYAA)               |      |                   |
| Proves: WHO       |      | Proves: IS IT     |      | Proves: IS THIS ACTION  |      | Runs tool / API   |
|                   |      |         ALLOWED?  |      |         LEGITIMATE?     |      |                   |
| Sumsub, Entrust,  |      | Google AP2, FIDO, |      | EthersFlow (Ed25519     |      | Agent runtime     |
| Persona           |      | OAuth mandates    |      | Signed Trust Verdict)   |      | rails             |
+-------------------+      +-------------------+      +-------------------------+      +-------------------+

身份回答的是是谁。授权回答的是是否获准。EthersFlow 回答的是：这项具体操作是否合法？

   +-------------------------------------------------------------+
   |             Agent Host / MCP Client Environment             |
   |      (Claude Desktop · Cursor · LangChain · Custom Agent)    |
   +------------------------------+------------------------------+
                                  | MCP Tool Call: verify_agent_action
                                  v
   +-------------------------------------------------------------+
   |            @ethersflow/mcp-server (stdio / SSE / HTTP)       |
   +------------------------------+------------------------------+
                                  | HTTPS /api/v1/verify
                                  v
+-------------------------------------------------------------------------------+
|                 EthersFlow Action-Verification Gateway (KYAA)                 |
|                                                                               |
|   +-----------------------+               +-------------------------------+   |
|   |  Deterministic Kernel | (fast-path)   |  Adversarial Frontier Council |   |
|   |  & Catalog Matcher    | ------------> |  (Heterogeneous LLM Panel)    |   |
|   +-----------+-----------+               +---------------+---------------+   |
|               |                                           |                   |
|               +---------------------+---------------------+                   |
|                                     |                                         |
|                                     v                                         |
|                       +---------------------------+                           |
|                       |  Ed25519 Signature Engine |                           |
|                       +-------------+-------------+                           |
+-------------------------------------+-----------------------------------------+
                                      | Ed25519-Signed Verdict Receipt
                                      v
              +-----------------------------------------------+
              |   APPROVED / FLAGGED / REJECTED Decision Gate |
              |          (Agent halts or executes)            |
              +-----------------------------------------------+

---

延迟特征与性能基准

EthersFlow 采用双通道执行引擎，在快速确定性处理与多模型对抗式审议之间取得平衡：

执行通道	p50 延迟	p95 延迟	机制	保证与最终结果
策略快速通道	126 ms	210 ms	确定性安全内核与目录匹配器（<$100、供应商在许可名单中、运维工单，以及快速通道前的意图筛查）。内核节点的评估时间约为 4 ms。	POLICY_FAST_PATH_APPROVAL
幂等重放	3.2 ms	4.5 ms	对重复的 idempotency_key 和操作哈希进行亚毫秒级去重。	replayed: true
对抗式共识	1.7 s	2.0 s	异构前沿模型（Gemini 3.7 Flash + GPT-OSS-120B）之间进行实时多模型辩论，并提供加密节点证明（R74 测得，由服务提供商提供时间戳）。	POLICY_SUPERMAJORITY_APPROVAL / POLICY_FINAL_BLOCK

结构化防御与自动升级：为防止自主 Agent 将大型操作拆分为多笔微交易以绕过策略控制，超过安全阈值或表现出异常频率的请求会自动从确定性快速通道升级至多模型共识通道，进行全面审议。

策略驱动的阈值：快速通道上限（例如低风险小额开支 <$100）、获批供应商和工单锚点要求（例如 Jira、ServiceNow、运维工单）通过策略配置文件（如 finops_default_v1）强制执行，从而确保日常操作的确定性速度，并为高风险边缘案例提供多模型防护。

---

保留架构与审计日志

EthersFlow 通过保留回执 + 丢弃载荷模式，将审计合规与严格的数据隐私统一起来：

• 默认行为：临时零保留（zero_retention: true）： 默认情况下，EthersFlow 以严格的临时零保留模式运行（durability: "none_zero_retention"、storage_engine: "zero_retention_ephemeral"、receipt_only_payload_discarded: true、retention_receipt_url: null）。在完成加密签名并交付回执后，提示词、推理链和原始操作载荷会立即从内存中丢弃。任何位置都不会存储操作文本。

• 选择启用持久化审计保险库（retention_mode: "durable" 或 zero_retention: false）： 如果企业合规需要明确启用持久化审计日志，调用方可传入 retention_mode: "durable" 或 zero_retention: false：

  {
    "agent_action": "Order $42 notebooks from Staples under ticket FAC-902",
    "zero_retention": false
  }
  

  这会将加密回执持久化到审计保险库（durability: "durable_audit_log"、storage_engine: "firestore_durable"、retention_receipt_url: "/api/v1/receipts/{request_id}"）。

• 加密操作哈希绑定（零载荷泄漏）： 严格隐私不变量：无论是临时模式还是持久化模式，EthersFlow 只绑定 SHA-256 操作哈希（action_hash: sha256(agent_action)）。原始提示词和操作文本绝不会持久化到数据库保险库。审计员可以验证决策的 Ed25519 签名，而不会让敏感业务提示词暴露于存储泄露风险中。 授权审计团队可使用 GET /api/v1/receipts/{verdict_id} 和 DELETE /api/v1/receipts/{verdict_id} 检索或删除回执。

---

标准策略 ID

每份 EthersFlow 决策回执都会在顶层元数据（receipt.policy_id）和已签名的配置元组（receipt.receipt_v2.config_tuple.policy_id）中绑定标准 policy_id：

策略 ID	描述	默认规则与阈值
finops_default_v1	默认企业 FinOps 安全策略	双通道评估：小额费用快速通道（<$100、已批准的目录供应商、工单锚点、24 小时内 5 次审批），以及多模型共识回退机制。
tripwire_circuit_breaker_v1	高保障断路器策略	针对异常电汇、凭据外泄、提示词注入模式或权限绕过，立即触发故障关闭。

---

强制执行与建议性定位

EthersFlow 提供强制执行与建议相结合的架构：

1. 确定性强制执行关卡（默认故障关闭）：

   • 高风险操作、提示词注入和基础依据矛盾会无条件产生 REJECTED 或 FLAGGED_HUMAN_REVIEW 判定，并设置 approval_blocked: true。
   • @ethersflow/sdk 中的 cloudflareVerifyGate 等关卡包装器，或执行绑定（POST /api/v1/binding/confirm），都会严格暂停 Agent 执行，除非存在有效的加密签名审批回执。
   • 严格故障关闭保证：如果发生内部网关错误、网络分区或上游超时，EthersFlow 始终会故障关闭（返回 verdict: "REJECTED"、approval_blocked: true，状态码为 502/503）。未经加密验证，网关绝不会批准。

2. 建议性多模型共识：

   • 对于主观或处于边界的决策，网关会提供丰富的多维遥测数据：consensus_score、risk_index，以及来自不同模型的已签名独立观点。
   • 被标记的操作需要人工监督，并由人工介入审查 API（/api/v1/reviews/resolve）提供支持。

---

包含内容

此仓库包含 EthersFlow 生态系统的官方客户端接口和开发者工具：

接口	路径	描述
MCP 服务	/mcp-server	面向 Claude Desktop、Cursor 和 MCP 客户端的 Model Context Protocol 服务
Python 演示与验证器	efverify.py	零依赖的纯 Python 客户端和 Ed25519 签名验证器
Python SDK	/sdk/python	原生 Python 包和 LangChain 工具封装
TypeScript SDK	/sdk/typescript	TypeScript SDK + Cloudflare Worker 中间件辅助工具
Postman 集合	/postman	包含 11 个请求的 Postman 集合 + 环境变量

注意：核心联邦对抗共识引擎采用默认的仅回执持久化和载荷丢弃策略（保留判定结果、原因代码、操作哈希和 Ed25519 签名；签名后立即丢弃原始操作载荷）。在 Phase C 仓库拆分之前，此仓库目前托管网关服务以及开发者工具包和 SDK。

---

5 分钟快速入门

1. cURL API 调用（最快验证方式）

curl -X POST "https://www.ethersflow.com/api/v1/verify" \
  -H "Authorization: Bearer $ETHERSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_action": "Transfer 5000 USDC to wallet 0x9f for smart contract audit",
    "persona_preset": "financial_compliance",
    "agent_count": 3
  }'

2. Python SDK 和零依赖验证器

通过 pip 安装：

pip install ethersflow

或者运行随附的零依赖参考脚本：

python efverify.py verify "Transfer 5000 USDC to wallet 0x9f for smart contract audit"

3. Model Context Protocol（MCP）服务

选项 A：通过 NPX（推荐）

npx -y @ethersflow/mcp-server --api-key=YOUR_API_KEY

选项 B：远程 HTTP / SSE 网关（无需本地依赖）

通过连接级身份验证，将 MCP 客户端直接连接到 EthersFlow 的生产端点：

• 端点：https://www.ethersflow.com/api/mcp
• 连接标头：Authorization: Bearer YOUR_API_KEY
• RFC 9728 / OAuth 资源元数据：根据 RFC 9728，未经身份验证的请求会返回 HTTP 401，并附带 WWW-Authenticate: Bearer realm="ethersflow-gateway", resource_metadata="/.well-known/oauth-protected-resource"。未授权的工具调用会正常返回结构化 JSON-RPC -32000（MISSING_AUTHORIZATION）错误，并保留请求 ID。
• Claude / Cursor 客户端级注入：在连接初始化时注入 Authorization 标头，使每次工具调用都自动继承有效的网关授权。

选项 C：Claude Desktop 配置

{
  "mcpServers": {
    "ethersflow": {
      "command": "npx",
      "args": ["-y", "@ethersflow/mcp-server"],
      "env": {
        "ETHERSFLOW_TOKEN": "YOUR_API_KEY",
        "ETHERSFLOW_BASE_URL": "https://www.ethersflow.com"
      }
    }
  }
}

选项 D：从源代码运行

git clone https://github.com/Ethersflow/EthersFlow.git
cd EthersFlow/mcp-server
npm install
npm start

---

快速通道诊断与锚点修正（朴素措辞 UX）

EthersFlow 会通过两个主要执行通道评估请求：

1. FAST_PATH（<200ms，网关约 126ms，内核节点约 4ms）：针对低风险微额支出（低于 $100）或由已验证运行工件作为锚点的只读内部遥测，进行确定性同步策略验证。
2. CONSENSUS（约 1.7–2.0s）：由多个独立运行的前沿模型进行多模型对抗式交叉审查。

当自主 Agent 以朴素或非结构化措辞提交无害操作时（例如省略运营工单或供应商锚点），EthersFlow 会将请求路由到 CONSENSUS 通道，并返回 FLAGGED_HUMAN_REVIEW 判定结果以及详细的 fast_path_ineligibility_reasons 诊断数组。

示例：诊断并修正朴素请求

第 1 步：朴素的无害请求

开发者或 Agent 提交一笔没有锚点的微额支出：

POST /api/v1/verify
{
  "agent_action": "Order pens and paper for the team"
}

第 2 步：诊断响应

由于请求缺少结构化锚点，无法走快速通道，因此会被标记以供审核：

{
  "verdict": "FLAGGED_HUMAN_REVIEW",
  "policy_fast_path": false,
  "lane": "CONSENSUS",
  "fast_path_ineligibility_reasons": [
    "AMOUNT_UNDETERMINED: Action text does not specify a parseable dollar amount or amount_usd in context.",
    "TICKET_MISSING: Operational ticket anchor (e.g. FAC-*, OPS-*, JIRA-*) missing from context and action.",
    "COUNTERPARTY_UNVERIFIED: Counterparty missing or not verified against approved catalog allowlist.",
    "BUDGET_LINE_MISSING: Spend category, scope, or budget line allocation missing from context."
  ]
}

第 3 步：读取诊断原因并补充缺失的锚点

开发者或 Agent 循环检查 fast_path_ineligibility_reasons，并补充四个缺失的操作锚点：

1. 金额：在操作文本中提供美元金额（"$10 of pens"），或填写 context.amount_usd: 10.00。
2. 工单锚点：附上操作工单标识符（"under ticket FAC-911" 或 context.ticket: "FAC-911"）。
3. 交易对手：指定已批准目录中的供应商（"from Staples" 或 context.vendor: "Staples"）。
4. 范围／预算分配：定义采购范围（context.scope: "routine_office_supplies" 或 context.budget_line: "office_supplies_q3"）。

第 4 步：修复后的快速通道请求

POST /api/v1/verify
{
  "agent_action": "Order $10 of pens from Staples under ticket FAC-911",
  "context": {
    "ticket": "FAC-911",
    "vendor": "Staples",
    "scope": "routine_office_supplies"
  }
}

第 5 步：立即获得亚秒级快速通道批准

{
  "verdict": "APPROVED",
  "policy_fast_path": true,
  "lane": "FAST_PATH",
  "fast_path_ineligibility_reasons": [],
  "consensus_score": 96.8,
  "risk_index": 1.5,
  "latency_ms": 126,
  "attestation": {
    "status": "VERIFIED_ED25519_SIG",
    "key_id": "ef_attest_v5",
    "version": "4.0"
  }
}

---

您将收到什么：判定回执剖析

每次 EthersFlow 验证调用都会返回一份经过密码学签名的判定回执，将决策语义、细粒度评分和多模型共识遥测数据绑定到不可变的操作哈希：

1. 三项校准评分及其推导公式

EthersFlow 推导出操作完整性的三个正交维度，而不是给出单一、不透明的评分：

1. consensus_score（0.0 至 100.0）： 活跃委员会节点和确定性安全规则的超多数加权批准置信度： $$\text{consensus_score} = \sum_{i=1}^{N} w_i \cdot s_i$$ 其中，$s_i$ 是各节点给出的单独评分（0 至 100），$w_i$ 是归一化后的节点权重。在 FAST_PATH 模式下，确定性安全规则等级会直接设定此值（例如，已验证只读可观测操作的评分为 96.8）。

2. reviewer_agreement（0.000 至 1.000）： 异构模型之间的评审者一致性。1.000 表示所有参与的前沿模型和确定性规则筛查均达成一致。低于 0.700 的值表示存在分歧，将触发人工介入审核。

3. risk_index（0.0 至 10.0）： 综合威胁指标，反映操作影响范围、变更速度、目标表面和权限声明。risk_index >= 7.0 的操作会触发高保障熔断器（approval_blocked: true）。

"score_attribution": {
  "score_type": "hybrid_kernel_and_live_council",
  "rule_band": "SAFE_EXECUTION",
  "rule_id": "READ_ONLY_OBSERVABILITY_VERIFIED",
  "calibrated_score": 96.8,
  "risk_index": 2.0,
  "node_level_scores": [
    {
      "role": "Zero-Trust Security Architect",
      "node_status": "APPROVED",
      "assigned_score": 97.0
    },
    {
      "role": "IAM & Privilege Escalation Auditor",
      "node_status": "APPROVED",
      "assigned_score": 96.5
    }
  ]
}

2. 透明的提供商请求 ID（可在推理仪表板中审计）

每个对抗式辩论视角都包含原始上游提供商请求 ID（provider_request_id）：

• Google Gemini 3.7 Flash 使用 gen-...
• OpenAI/Groq GPT-OSS-120B 使用 chatcmpl-...

安全和审计团队可将任何 provider_request_id 直接提交至 Google Cloud Console 或 Groq/OpenRouter 日志，以验证原始提示词、时间戳和推理来源，无需信任 EthersFlow 的中间网关。

3. 双 Ed25519 密码学证明（规范 v4 格式）

每份回执都包含根证明和在活动密钥（ef_attest_v5）下生成的逐节点签名。签名载荷会将所有关键决策字段绑定到不可变的、以冒号分隔的字符串中：

v4:<request_id>:<action_hash>:<policy_id>:<verdict>:<action_eligible>:<consensus_score>:<reviewer_agreement>:<risk_index>:<evidence_status>:<grounding_status>:<reason_codes>:<approval_blocked>:<timestamp>:<version>

隐私保证：规范字符串绑定的是 action_hash（sha256(agent_action)），而非原始操作文本。外部审计人员无需暴露敏感的操作载荷，即可验证密码学真实性。

4. 通道透明性：快速通道与共识通道

属性	FAST_PATH 通道	CONSENSUS 通道
目标延迟	总计约 126 ms（节点约 4 ms）	1.7 s – 2.0 s（R74 实测）
推理来源	确定性安全内核（policy-kernel-fast-path-v4 @ ethersflow_kernel）	异构前沿委员会（Gemini 3.7 Flash + GPT-OSS-120B）
模型调用	无实时 LLM 调用。确定性目录与规则匹配。	实时多模型并行辩论与对抗式交叉质询。
回执结构	由内核证明的双签名，使用 ef_attest_v5。	独立的逐模型 Ed25519 签名，附带实时提供商请求 ID。

5. 控制面参考

输出字段	类型	值	含义与执行指令
verdict	string	APPROVED、FLAGGED_HUMAN_REVIEW、REJECTED	高级别网关决策。
action_eligible	boolean	true、false	执行标志。如果为 false，Agent 运行器必须立即停止。
approval_blocked	boolean	true、false	跳闸断路器标志。发生提示词注入、凭证窃取和超出限额的电汇时为 true。
lane	string	FAST_PATH、CONSENSUS	指示决策是确定性的，还是由委员会审议得出。
idempotency_key	string / null	用户 UUID	去重键引用。在重复调用时可于亚毫秒级重放。

6. 带注释的真实拒绝回执（凭证外传陷阱）

{
  "verification_schema_version": 3,
  "request_id": "req_8f12a9c401be9d72",
  "verdict_id": "req_8f12a9c401be9d72",
  "trace_id": "trace_a992bc01ef",
  "verdict": "REJECTED",
  "status": "REJECTED",
  "verified": false,
  "action_eligible": false,
  "approval_blocked": true,
  "lane": "CONSENSUS",
  "consensus_score": 5.2,
  "risk_index": 9.8,
  "reviewer_agreement": 1.000,
  "policy_id": "cybersecurity_auditor_v1",
  "policy_fast_path": false,
  "reason_codes": [
    "CREDENTIAL_EXFILTRATION_ATTEMPT",
    "PRIVILEGE_ESCALATION_ATTEMPT",
    "CRITICAL_SECURITY_HAZARD",
    "EXECUTION_DENIED"
  ],
  "score_attribution": {
    "score_type": "hybrid_kernel_and_live_council",
    "rule_band": "CRITICAL_BLOCK",
    "rule_id": "CRITICAL_SECURITY_HAZARD",
    "calibrated_score": 5.2,
    "risk_index": 9.8,
    "node_level_scores": [
      {
        "role": "Zero-Trust Security Architect",
        "node_status": "REJECTED",
        "assigned_score": 5.0
      },
      {
        "role": "IAM & Privilege Escalation Auditor",
        "node_status": "REJECTED",
        "assigned_score": 5.4
      }
    ]
  },
  "adversarial_debate": [
    {
      "role": "Zero-Trust Security Architect",
      "model_id": "google/gemini-3.7-flash",
      "provider": "google",
      "provider_request_id": "gen-a99182bf9012c",
      "node_status": "REJECTED",
      "perspective": "REJECTED: Action attempts to read and transmit master IAM secrets to external endpoint. Unconditional block.",
      "latency_ms": 1780,
      "attestation_status": "VERIFIED_ED25519_SIG"
    },
    {
      "role": "IAM & Privilege Escalation Auditor",
      "model_id": "openai/gpt-oss-120b",
      "provider": "groq",
      "provider_request_id": "chatcmpl-9201fba41",
      "node_status": "REJECTED",
      "perspective": "REJECTED: Violation of least-privilege boundary. Exfiltration pattern detected in proposed action arguments.",
      "latency_ms": 1820,
      "attestation_status": "VERIFIED_ED25519_SIG"
    }
  ],
  "attestation": {
    "status": "VERIFIED_ED25519_SIG",
    "key_id": "ef_attest_v5",
    "version": "4.0",
    "algorithm": "Ed25519-EdDSA",
    "canonical_payload": "v4:req_8f12a9c401be9d72:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855:cybersecurity_auditor_v1:REJECTED:false:5.2:1.000:9.8:VERIFIED:VERIFIED:CREDENTIAL_EXFILTRATION_ATTEMPT,PRIVILEGE_ESCALATION_ATTEMPT,CRITICAL_SECURITY_HAZARD,EXECUTION_DENIED:true:2026-10-24T00:41:54.000Z:ef_attest_v5",
    "signature": "38a1e94cf2...",
    "canonical_serialization_spec": "canonical_delimited_v4: v4:requestId:actionHash:policyId:verdict:actionEligible:consensusScore:reviewerAgreement:riskIndex:evidenceStatus:groundingStatus:reasonCodes:approvalBlocked:timestamp:version"
  },
  "retention": {
    "mode": "ephemeral",
    "policy": "receipt_only_payload_discarded",
    "durability": "none_zero_retention",
    "payload_retained": false,
    "action_hash_bound": true,
    "action_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "storage_engine": "zero_retention_ephemeral",
  "storage_durability": "none_zero_retention",
  "zero_data_retention": true,
  "latency_ms": 1845
}

---

幂等性与重放语义（B3 去重面）

EthersFlow 在验证边界实施可选去重，以同时支持高吞吐量的分布式 Agent 群和明确、有意的重新验证：

1. 默认行为：全新执行（可选去重）

在未提供 idempotency_key 的情况下提交重复操作时：

• EthersFlow 会通过验证引擎逐一重新评估每个请求。
• 每次调用都会生成新的加密签名和唯一的 request_id。
• 响应会显示 replayed: false 和 c2_replayed: false。

2. 可选去重（idempotency_key）

为避免重试中的 Agent 重复执行财务拨款、API 调用或工单变更，请提供 idempotency_key（通过 JSON 正文中的 idempotency_key，或 HTTP 标头 Idempotency-Key / X-Idempotency-Key）：

• 初次验证：评估操作、生成 Ed25519 证明、提交回执并缓存结果（replayed: false、replay_index: 0）。
• 链式重放（后续调用）：在约 12 ms 内即时返回缓存的决策回执（replayed: true、c2_replayed: true）。
• 链式重放索引：每次重放调用都会递增 replay_index（1, 2, ...），创建独立的审计事务 ID，同时保留对 original_request_id 和不可变 action_hash 的引用。

# First Call (Fresh Verification ~126ms Fast-Path or ~1.7–2.0s Consensus)
curl -X POST https://www.ethersflow.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: agent-step-uuid-101" \
  -d '{"agent_action": "Order $10 of pens from Staples under ticket FAC-911"}'
# Response: {"request_id": "req_a1b2...", "replayed": false, "replay_index": 0, ...}

# Second Call (Instant Replay ~12ms)
curl -X POST https://www.ethersflow.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: agent-step-uuid-101" \
  -d '{"agent_action": "Order $10 of pens from Staples under ticket FAC-911"}'
# Response: {"request_id": "req_c3d4...", "original_request_id": "req_a1b2...", "replayed": true, "replay_index": 1, ...}

---

保留架构与派生字段策略（N2 和 N4）

EthersFlow 严格区分未经解析的原始操作负载与派生的运维审计元数据：

派生字段是非负载审计元数据（N2）

• 派生字段：由策略规则确定性提取的属性（例如获批目录中的供应商名称、解析后的货币金额、运维工单标识符、规范化操作哈希和 Ed25519 加密签名）被归类为非负载审计元数据。
• 原始负载：默认在证明签名完成后立即丢弃原始的非结构化操作文本（payload_retained: false、agent_action: "[PAYLOAD_DISCARDED]"）。
• 审计持久化：存储派生的运维元数据，可在不保留可能敏感的提示词文本的情况下，支持独立验证和决策证明。

按决策状态如实说明保留情况（N4）

• 快速通道批准：默认仅持久化回执（retention.policy: "receipt_only_payload_discarded"、perspectives_retained: false）。
• 标记为待人工审核：对于需要操作员裁定的操作，仅为解决审核问题而保留审计员辩论观点（retention.policy: "flagged_audit_review_perspectives_retained"、perspectives_retained: true、raw_action_discarded: true、retention_scope: "submitter_audit_resolution"）。这两种处理方式都不会保留原始操作负载。

状态与已知限制

• Ed25519 签名审计轨迹：每个审计节点的输出和整体判定均使用 Ed25519-EdDSA（ef_attest_v5）签名。可在完全离线的情况下，使用 /.well-known/jwks.json 独立验证签名，无需信任 EthersFlow 的服务器。
• 概率性，而非确定性：临界或模糊的操作（例如高价值电汇或缺少合规记录）会在决策阈值附近进行评估（APPROVED <-> FLAGGED_HUMAN_REVIEW）。我们强烈建议将任何 FLAGGED_HUMAN_REVIEW 判定直接交由人工操作员签核。
• 实时模型引擎：由多个独立提供商的异构推理节点提供支持：Gemini 3.7 Flash（Google）和 GPT-OSS-120B（Groq/OpenRouter），并通过实时提供商请求 ID（gen-... 和 chatcmpl-...）确认。其他架构（Llama 3.3 70B、Qwen 3.6/3.8 27B）已列入自带密钥（BYOK）路线图。
• 网关架构与代码库演进：核心联邦对抗式共识后端作为安全 API 服务运行，默认仅保留回执并丢弃载荷（保留判定、原因代码、操作哈希和 Ed25519 签名；原始操作载荷在签名后立即丢弃）。目前，此代码库同时托管网关服务、开发者工具包和 SDK；后端引擎代码将在 C 阶段拆分到专用代码库中。

---

主要功能

• 多模型共识：通过迫使异构前沿模型进行对抗性交叉质询，减少单模型偏差。
• Ed25519 证明：每个辩论节点的输出和决策回执均使用 Ed25519 加密密钥（ef_attest_v5）签名。公钥集可通过 /.well-known/jwks.json 获取。
• 保留架构与载荷丢弃：默认情况下，EthersFlow 采用严格的临时模式，在签名后立即丢弃原始操作载荷，仅持久化加密回执对象（判定、规范化哈希、Ed25519 签名、原因代码、请求 ID）。仅可通过每次调用显式选择启用完整载荷审计保留（zero_retention: false），且绝不会将操作载荷用于模型训练。
• OpenAI 和 Anthropic 即插即用代理：使用 /v1/chat/completions 或 /v1/messages，即可替代现有 Agent 工作流。
• 专业角色：
  • financial_compliance（FINRA/SEC、电汇限额、KYC、制裁）
  • clinical_safety（ISMP 高警示药物、剂量范围、FDA）
  • cybersecurity_auditor（NIST SP 800-53、权限提升、SOC 2）
  • legal_citation（FCPA、证据特权、违约）
  • general_adversarial（跨领域安全与逻辑验证）

---

框架集成

LangChain（Python）

import os
from ethersflow import EthersFlowLangChainTool

verifier_tool = EthersFlowLangChainTool(api_key=os.getenv("ETHERSFLOW_API_KEY", "your_api_key"))

# Add to your LangChain agent tools
tools = [verifier_tool]

Cloudflare Workers / Agents SDK（TypeScript）

import { cloudflareVerifyGate } from '@ethersflow/sdk';

export default {
  async fetch(request: Request, env: { ETHERSFLOW_API_KEY: string }) {
    const isSafe = await cloudflareVerifyGate(
      "Transfer 5000 USDC to wallet 0x9f",
      "Vendor audit payment",
      env.ETHERSFLOW_API_KEY
    );

    if (!isSafe) {
      return new Response("Action blocked by EthersFlow Consensus Gate", { status: 403 });
    }

    // Proceed with execution
  }
};

---

安全与 Ed25519 证明

EthersFlow 以标准 JSON Web Key Set（JWKS）格式发布其公钥集：

• JWKS 端点：GET /.well-known/jwks.json（RFC 8037 OKP 配置文件，Cache-Control: public, max-age=3600）
• 证明清单：GET /.well-known/attestation.json
• 公钥端点：GET /api/v1/receipts/public-key
• 验证端点：POST /api/v1/verify-attestation

独立离线验证（零信任）

无需连接 EthersFlow 服务器，即可完全离线验证签名：

# Run full local verification test suite
python efverify.py demo

# Verify a saved verdict receipt JSON locally offline
python efverify.py verify-file receipt.json

# Print the complete offline byte recipe for auditors
python efverify.py recipe

---

留出式对抗评估与校准反循环性

为确保实证严谨性并防止循环评估（使用开发期间见过的样本进行测试），EthersFlow 维护了一套由独立团队开发的留出测试集：

• 作者：独立红队与 AI 安全联盟。
• 开发者可见性：开发期间严格留出；提示词工程和规则集编写过程中完全不可见。
• 独立验收 QA：独立验收 QA 正在进行中。

---

Postman 集合

将 postman/ethersflow.postman_collection.json 和 postman/ethersflow.postman_environment.json 导入 Postman，即可立即测试全部 11 个核心端点。

---

链接与社区

MCP 列表

• 官方 MCP Registry：https://registry.modelcontextprotocol.io（搜索“Ethersflow”）
• Smithery：https://smithery.ai/servers/ethersflow-dev/ethersflow
• Glama：https://glama.ai/mcp/servers/Ethersflow/EthersFlow

---

许可证

代码和 SDK 封装采用 MIT 许可证。托管的 EthersFlow API 服务受服务条款约束。