Aakash-a18/mesherra

# Mesherra [](LICENSE) [](#status--honest-expectations) ## 事物的形态 Google 的 Agent2Agent (A2A) 协议为 AI agent 提供了一种相互发现和交流的方式。它**没有**提供： 1. 一种确认对方真实身份的方法（除了自声明的身份卡） 2. 对跨越边界的数据的控制权（网络传输的是发送方包含的任何内容） 3. 对达成共识的可验证记录（除了基本日志外，没有签名的来源） 用 A2A 自己的话说，它是“通信，而非安全”。这个空白是明确且有意为之的。 **Mesherra 填补了这一空白。** | 部分 | 功能 | |---|---| | **身份验证** | 确认 agent 是其声称的身份，超越了自我声明。由经过验证的主体目录提供支持。 | | **范围披露** | 强制执行有关哪些数据可以跨越边界的用户策略。默认值：保留。共享是一种深思熟虑的、已签名的行为。 | | **来源 / 证明** | 每次交互的防篡改签名记录。双方都持有匹配的、可验证的条目。 | 再加上一个第零部分 —— **策略捕获** —— 将用户意图转化为 runtime 可以验证的结构化规则。 ## 为什么这很重要 Agentic web 正在形成。拥有其信任原语的公司在回首这一刻时，就像 Plaid、Stripe 和 DocuSign 回首早期商业网络一样：它们是无聊的基础设施，却捕获了巨大的价值，因为一切都必须通过它进行路由。 Mesherra 就是这些原语之一。它位于任何 AI agent 和 A2A 网络之间 —— 对最终用户不可见，但对于任何 agent 需要处理重大事务的人来说却至关重要。 ## 起源的隐喻 在古罗马时期，达成长期协议的双方会将一块 *tessera* —— 一种由粘土或骨头制成的小方块 —— 折断成两半。双方各执一半。几个世纪后，从未谋面的后人可以相遇，将两半拼在一起，并通过拼合的精确度来证明最初的契约。 Mesherra 就是数字时代的 tessera。信任的建立不需要任何人提前信任对方 —— 这两半要么契合，要么不契合。 ## 你应该阅读什么 按照“从何处开始”的顺序： - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 完整的系统规范。14 个部分涵盖了核心概念（Agent、Object、Layer、Promotion、Handshake、Policy、Residue）、Object 数据流、这三个部分、基于 schema 的消息传递、威胁模型以及 11 个组件的清单。 - [`docs/DIAGRAMS.md`](docs/DIAGRAMS.md) — 可视化参考。6 个 ASCII 图表：layer 堆栈、双用户镜像堆栈、完整协商流程、内部架构、出站/入站消息路径。 - [`docs/STRATEGY.md`](docs/STRATEGY.md) — 更长远的战略方向。从 Application 到 Delegation 的范式转变；三产品框架（Mesherra / Butler / 首个 Delegation）；通过 Delegation Registry 实现的 marketplace 路径；开放性战略问题。 - [`demos/phase_1/SPEC.md`](demos/phase_1/SPEC.md) — Phase 1 演示规范。锁定了 proposal schema、residue entry schema、规范化承诺（JCS / SHA-256 / Ed25519）以及 14 个终态断言。 - [`CLAUDE.md`](CLAUDE.md) — 为任何进入此代码库的 AI 编程会话提供指引。包括词汇表、构建纪律、构建顺序。 ## 首个 Delegation Mesherra 是基础底座。**Delegation** 是 agent 时代的应用等价物 —— 它是使用 Mesherra 原语为特定领域提供最终用户体验的已发布包。 **[MeshyCal](https://github.com/Aakash-a18/meshycal)** 是首个 Delegation。两个用户的 AI agent 在不暴露任何一方日历的情况下协商会议时间，并生成带有签名的已验证记录。 MeshyCal 是我们的**测试平台** —— 它在最小可能的协商中证明了 Mesherra 在所有三个部分上都能在机制上正常运行。它**不是我们的市场**。Mesherra 的市场是合同、交易和受监管的 B2B 协作 —— 这些领域容不得半点差错，且信任具有实质性的价值。日程安排锻炼了该 layer；高风险的商业活动则证明了其价值。 ## 从 Application 到 Delegation 的范式 在前 agent 时代的 web 中，基本单位是 **Application** —— 这是一个庞然大物，将数据、逻辑、UI 和集成捆绑在一个固定的界面背后，用户需要*导航至*该界面并对其进行*操作*。 在 agentic web 中，基本单位是 **Delegation** —— 这是一个已发布的包，用户针对其生活中的某个领域*授予其权限*，然后它通过用户的 butler agent 代表用户执行操作。 一个 Delegation 打包了四样东西： 1. **Object 类定义** — 注册到 Schema Registry 中的 schema 2. **Agent 代码** — 在用户 butler 下运行的领域 agent 3. **Policy 模板** — 合并到用户已签名 policy 中的合理默认值 4. **渲染器/UI** — 面向用户的界面（可选，随着环境/语音/AR 界面的出现可被丢弃） 这四个组件的形态就是 Delegation 集成契约。MeshyCal 是第一个；相同的托管机制无需修改即可接受第二、第三乃至第 N 个 Delegation。 ## 项目结构 ``` mesherra/ ├── docs/ │ ├── ARCHITECTURE.md # System spec (14 sections) │ ├── DIAGRAMS.md # 6 ASCII visual references │ └── STRATEGY.md # Longer-arc strategic direction ├── demos/ │ └── phase_1/ │ └── SPEC.md # Provenance round-trip demo spec ├── src/mesherra/ # 11 component modules — all NotImplementedError today │ ├── sdk.py # 13.1 Public API surface │ ├── gateways/ # 13.2, 13.3 Outbound + inbound airlock │ ├── policy/ # 13.4, 13.6 Engine + signed user policy store │ ├── identity/ # 13.5, 13.7 Verified directory + backing store │ ├── provenance/ # 13.8 Append-only signed ledger │ ├── crypto/ # 13.9 Signing, verification, canonicalization │ ├── a2a_adapter/ # 13.10 The only module that imports a2a-sdk │ ├── schemas/ # 13.11 Schema Registry │ └── models/ # Agent, Object, Layer, Promotion, etc. ├── tests/ │ ├── unit/ # Pure logic, no I/O │ ├── integration/ # Real crypto + SQLite round-trips │ └── e2e/ # Two-agent localhost demos ├── pyproject.toml # Python 3.11+, a2a-sdk + cryptography + pydantic + fastapi + jcs ├── .env.example # Required configuration (no hardcoded values anywhere) ├── LICENSE # Apache-2.0 └── CLAUDE.md # AI coding session orientation ``` ## 路线图 | 阶段 | 交付内容 | 状态 | |---|---|---| | **Phase 1** | 来源的垂直切片：签名条目、哈希链账本、带有 14 个终态断言的双进程 localhost 演示 | 步骤 1–5 已实现（来源账本、加密、A2A adapter、签名 SendClaim 网关）；演示流程 + MeshyCal 集成正在进行中 | | **Phase 1.5** | 访客主体生命周期（由 MeshyCal 邀请流程驱动） | 开放性问题 | | **Phase 2** | 身份验证：已验证的目录、已签名的 AgentCard 解析 | 架构已完成 | | **Phase 3** | 范围披露：字段级策略执行，Schema Registry | 架构已完成 | | **未来规划** | 去中心化目录迁移；Delegation Authoring SDK；Class Registry → marketplace | 开放性战略问题 | 构建顺序由纪律（`CLAUDE.md`）强制执行：首先是来源（记录的侵入性最小），其次是身份（现成的 PKI），最后是范围披露（最困难、最具差异化的部分）。每个阶段都独立交付并可演示。 ## 构建纪律（我们不可打破的规则） 1. 信任层绝不能从任何消费者（Delegation）导入。绝对不能。 2. 特定领域的逻辑存在于消费者 Delegation 中，而不是 Mesherra 中。 3. 渲染器是一次性的；主体模型才是唯一事实来源。 4. 依托 A2A SDK。不要重新实现传输、发现或任务生命周期。 5. 严格的区域分离；气闸室是唯一的边界关卡。 6. 首先使用集中式身份目录，同时保持随时可去中心化的 schema。以后无需重写即可迁移。 7. 通过环境进行配置，绝不硬编码。缺少必需变量时快速失败。 8. 代码库中永远不得包含真实用户数据。仅限合成数据。Git 历史是永恒的。 9. 不要过早抽象 MeshyCal。Delegation Authoring SDK 是从第 2 个 Delegation 中衍生出来的，而不是在第 1 个内部的猜测中产生的。 ## 设置 ``` git clone https://github.com/Aakash-a18/mesherra.git cd mesherra cp .env.example .env # 使用你的本地值编辑 .env pip install -e ".[dev]" ``` 所有配置都基于环境。如果缺少必需的环境变量，应用程序在启动时会快速失败 —— 不会有任何假装正常但在生产环境中随后出错的静默默认值。 ## 状态与客观期望 这是 **pre-alpha** 版本，但信任层的核心已经实现并经过了测试。该代码库包含： - 全面的文档（架构、策略、图表） - Phase 1 的步骤 1–5 已实现并经过测试（134 个通过的测试）：哈希链来源账本、Ed25519 签名/验证原语、A2A 网络 adapter，以及生成带有 `operation` 绑定的已签名 `SendClaim` 记录的入站/出站网关 - 一份 Phase 1 演示规范，双进程 MeshyCal 演示（步骤 6）仍待完成连接 **尚未**构建的内容：端到端的双进程演示（Phase 1 步骤 6）、身份验证/已签名的 AgentCard 解析（Phase 2）以及范围披露/字段级策略执行（Phase 3）。如果你现在就想要一个完成的信任层，目前这里还没有。如果你想要严谨的基础设施思维、连贯的架构、明确的威胁模型、清晰的构建路径以及已经到位的可验证核心，那你来对地方了。 ## 贡献 Pre-alpha 阶段。架构正在公开构建中；预计会有快速的迭代。贡献指南将在 Phase 1 发布后推出。目前：欢迎提问和提 issue；在信任层真正成型之前提交 PR 可能还为时过早。 ## 许可证 Apache License 2.0 — 见 [`LICENSE`](LICENSE)。 版权所有 © 2026 Aakash Agrawal。

标签：A2A协议, AI代理, Streamlit, 可信计算, 数据溯源, 访问控制, 逆向工具