p-e relay (remote)

Agent 中继与裁决协议（v1.0-SPEC）

一套工业级、无领导者的多 Agent 同步与争议解决协议，专为自主大模型集群（Claude、GPT-4o、Gemini、Mistral 和人类架构师）设计。

该协议基于规范化的加密摘要（RFC 8785 / Proverbs 11:1）、因果单调性（混合逻辑时钟 / HLC）、原子无锁追加日志（POSIX O_CREAT | O_EXCL）和对抗性交叉质询（Proverbs 18:17 裁决法庭）构建。

---

🏛️ 核心架构不变量（SPEC MUST 1–8）

1. RFC 8785 JCS 规范化（MUST 1）：加密 SHA-256 摘要严格基于递归排序的 JSON 键、经过 IEEE 754 规范化的浮点数以及 UTF-8 编码的负载计算（“诡诈的天平为耶和华所憎恶，公平的法码为他所喜悦。”——箴言 11:1）。
2. 混合逻辑时钟（MUST 2）：每个信封都携带物理 UTC 时间，并结合单调递增的 Lamport 计数器（physical_ms:counter:node_id），确保异步节点之间的因果顺序，不受 NTP 时钟漂移故障影响。
3. 通过 O_CREAT | O_EXCL 原子分配槽位（MUST 3）：并发写入竞争在内核文件系统层解决。如果两个 Agent 尝试占用同一个序列槽位 seq: N，冲突将返回 EEXIST，迫使失败方单调递增 seq。
4. 对抗三方机制与裁决（MUST 4）：未经对抗性交叉质询，任何主张都不得获认可（“先诉情由的，似乎有理；但邻舍来到，就察出实情。”——箴言 18:17）。
5. 零隐式信任（MUST 5）：Agent 之间的信封必须能够离线验证，并可通过不同工具链（TypeScript、Python、Rust、Go）独立校验。
6. 保留已知缺失项（MUST 6）：当信封负载被清除、压缩或丢失时，日志会保留其序列槽位、定位符和 SHA-256 摘要，并将状态标记为 MISSING，以防止虚假地重复使用槽位。
7. 跨平台 Rosetta 兼容性（MUST 7）：确保 JSON、YAML、Protocol Buffers、FlatBuffers 和 MCP（模型上下文协议）之间精确的线路兼容性。
8. 实时 SSE 与文件总线流传输（MUST 8）：通过服务器发送事件（SSE）和 POSIX 文件监视器实现亚毫秒级响应式订阅。

---

🚀 快速开始

先决条件

• Node.js 20+（脚本在其上运行；托管容器使用的就是它）
• Bun 1.1+ 可选——用于安装和运行相同脚本的更快工具

安装与运行

# Clone the repository
git clone https://github.com/your-username/agent-relay.git
cd agent-relay

# Install dependencies — bun, because bun.lock is the lockfile here
bun install --frozen-lockfile

# Start development server (Port 3000)
bun run dev

# Build production bundle
bun run build
bun run start

打开 http://localhost:3000，即可访问完整的交互式工作台、实时中继日志和自主 Agent 聊天。

**上述命令使用 bun，而其运行的脚本特意保持与 Node 兼容。**这是一个 AI Studio 小程序（metadata.json），托管容器会在不含 bun 的 Node 镜像中调用 npm run build 和 npm start。因此，npm 并不是这里需要迁移掉的习惯——它是一个实际部署目标所使用的工具，而且 package.json 不要求任何一个运行时都不具备的二进制文件。CI 因此保留了一个 node 作业，也保留了一个 bun 作业，因为每个运行时都自行实现了 O_CREAT | O_EXCL。

本仓库控制的所有内容——deploy.sh、贡献者步骤和上述命令——都使用 bun；bun install --frozen-lockfile 是确定性安装方式：仓库只提交了 bun.lock 这一个锁文件，而 npm 会写入第二个可能与之不一致的锁文件。

环境

HOST	要绑定的接口。默认为 127.0.0.1。此进程不进行任何身份验证，因此绑定到更广泛的接口是有意为之，并且应置于会进行身份验证的反向代理之后。
PORT	默认为 3000。
NODE_ENV	production 会从 dist/ 提供构建后的客户端。其他任何值都会启动 Vite 开发服务器，该服务器不适合面向网络。bun run start 会设置此变量。
PE_STORE_ROOT	读取现有的 p-e 中继存储，而不是本项目自己的存储。只读：声明 write、delete 和 reset 不可用，并以 405 拒绝。
ALLOW_SERVER_MODEL_CALLS	设置为 1 时，会启用以下三个使用此进程持有的 API 密钥运行模型的路由：/api/relay/adjudicate、/api/relay/step-triad、/api/relay/agent-exec。这些路由本身均不进行身份验证。默认关闭。ALLOW_AGENT_EXEC 作为旧名称仍受支持。

---

📦 项目结构

.
├── src/
│   ├── components/
│   │   ├── AgentChatInterface.tsx    # Multi-agent chat with 1-click Triad & Court
│   │   ├── LiveRelayConsole.tsx      # Real-time ledger, sequencer & SSE observer
│   │   ├── AdjudicationWorkbench.tsx # Court state machine (Proverbs 18:17)
│   │   ├── RosettaMatrix.tsx         # Cross-language wire serializers
│   │   ├── EnvelopeStudio.tsx        # RFC 8785 canonizer & digest generator
│   │   ├── FailureSandbox.tsx        # Chaos injection & invariant stress tests
│   │   ├── BridgeExporter.tsx        # MCP & Tool definitions export
│   │   └── Navbar.tsx                # Responsive top navigation
│   ├── App.tsx                       # Root React 19 application
│   ├── main.tsx                      # Vite React mount point
│   └── index.css                     # Tailwind CSS & theme tokens
├── server.ts                         # Express + Atomic POSIX Store + SSE Hub
├── docs/                             # Architecture specs & Engineering Backlog
│   ├── ARCHITECTURE.md               # In-depth architectural blueprint
│   └── BACKLOG_AND_DEBT.md           # Engineering insights, debt & roadmap
├── metadata.json                     # AI Studio runtime metadata
├── AGENTS.md                         # Context & rules for autonomous AI coding agents
├── CONTRIBUTING.md                   # Contribution guidelines
├── LICENSE                           # MIT License
└── package.json                      # Build scripts & dependency declarations

---

🛠️ API 与线缆协议

信封规范

{
  "seq": 42,
  "locator": "agent:claude/42@2026-09-01T16:45:00.000Z",
  "from": "agent:claude-code",
  "to": "agent:chatgpt-adversary",
  "type": "claim",
  "title": "HLC Monotonic Invariant Proposal",
  "parent_locator": "agent:human/41@2026-09-01T16:44:00.000Z",
  "hlc": "1788281100000:0001:claude",
  "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "payload": {
    "body": "Proposed RFC 8785 canonical digest validator."
  }
}

核心 HTTP 端点

• POST /api/relay/deposit — 使用 O_CREAT | O_EXCL 原子性地存入一个信封
• GET /api/relay/records — 获取当前序列账本和信封状态
• GET /api/relay/events — 实时服务器发送事件（SSE）流
• POST /api/relay/adjudicate — 通过 Gemini 执行《箴言》18:17 裁决
• POST /api/relay/agent-exec — 自主 Agent 推理与响应分发器

---

📜 圣经与数学基础

• 《箴言》11:1：“诡诈的天平为耶和华所憎恶；公平的法码为他所喜悦。” — 位精确 JSON 规范化（RFC 8785）的基本规则。
• 《箴言》18:17：“先诉情由的，似乎有理；但邻舍来到，就察出实情。” — 协议要求在账本批准之前进行对抗性交叉质询。

---

📄 许可证

MIT License。可免费用于开源研究和企业级分布式 Agent 部署。