x402 多语言支付协议仓库贡献指南：从 AI 辅助开发到新增链与新 Scheme 的完整流程
【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402
导读
本文基于 x402 仓库根目录的 CONTRIBUTING.md，系统梳理这个互联网原生支付协议（"A payments protocol for the internet. Built on HTTP."）的完整贡献规范。你将掌握：AI 辅助开发时的输出约束与合规要求、TypeScript/Python/Go 三套 SDK 的测试与 Changelog 工具链、Paywall 跨语言模板的再生成流程，以及新增支付 Scheme 和新增链支持（含"三 PR 工作流"）的准入标准与实现路径，从而在真实资金转移场景下提交安全、可信、可合并的贡献。
一、贡献指南的定位与核心原则
x402 是一个面向互联网的开放支付协议：客户端（client）为某个资源（resource）付费，资源服务器（resource server）提供服务，facilitator 负责支付的验证与执行。由于协议处理的是真实的价值转移，其贡献指南的第一原则不是"如何写代码"，而是如何保证安全与可信：
- 合入贡献由 x402 Foundation 团队根据贡献的风险与实现质量自行裁量，而非机械执行；
- 任何关于支付、签名、结算的逻辑错误都可能造成真实资金损失；
- 贡献的形式不仅限于代码，还包括新的 scheme（资金移动方式）、中间件（middleware）、新链支持等。
这意味着贡献者在动手之前，必须先理解仓库的整体布局与各语言 SDK 的既有模式，再按规范提交。
二、AI 辅助贡献：可用，但有硬性红线
x402 明确允许使用 LLM 与代码助手参与贡献，同时设定了一套防止"低质量机器生成 PR 淹没维护者"的规则：
- 提交前必须人工审查 AI 输出：不得在未亲自验证生成代码的情况下打开非 Draft PR；
- 去除冗余与废话：AI 容易产出冗长的文档、注释、PR 描述与提交信息，应精简到"清晰、有用"为止；
- 去除重复代码与测试：显式与清晰是好的，重复与过度解释不是；
- 重点核对支付与签名逻辑：AI 会生成"看起来正确但细节错误"的代码——错误的签名流程、错误的链常量、与规范不符的伪造 header。贡献者必须在提交前自行拦截；
- 不要批量生成低质量 PR：AI 提升的是产出速度，应把速度用在"更少但更高质量"的贡献上；
- 显著 AI 使用需披露：若 PR 大部分由 AI 生成，请在 PR 描述中注明。这不是减分项，而是帮助审查者校准审查重点（如检查幻觉 API、伪造的测试断言）。
附带后果：明显未经人工审查的 AI 输出（泛泛的填充注释、幻觉、冗余样板、套模板的 PR 描述）可能不经详细审查直接关闭。
官方推荐的 Agent 系统提示词
文档给出了可直接放入CLAUDE.md、.cursorrules、codex-instructions.md等本地工作区配置（不提交到仓库）的完整提示词，核心内容如下：
You are contributing to x402, an open protocol for internet-native payments. x402 handles real value transfer — correctness is critical. Follow these rules for all code, documentation, and commit messages you produce: 1. CONCISE OUTPUT ONLY. Do not add filler comments, redundant docstrings, or verbose explanations. Every line of documentation or commentary must carry useful information. 2. NO REDUNDANCY. Do not generate duplicate or near-duplicate code, tests, or explanations. If logic already exists, use it — do not rewrite it. 3. VERIFY AGAINST THE SPEC. Before writing payment, signing, or settlement logic, read the relevant spec in specs/. Do not invent header names, payload fields, or signing flows. If unsure whether a field or constant exists, search the codebase — do not guess. 4. MATCH EXISTING PATTERNS. Read the surrounding code before generating new code. Match the style, naming conventions, error handling, and test patterns already in use for that SDK (TypeScript, Python, Go, or Java). 5. DO NOT ADD UNREQUESTED FEATURES. Implement exactly what was asked. 6. COMMIT MESSAGES. Use conventional commits (feat:, fix:, docs:, chore:). Keep the subject line under 72 characters. The body should explain why, not what — the diff shows what changed. 7. CHAIN AND TOKEN CONSTANTS. Never hardcode chain IDs, token addresses, or decimal values from memory. Always reference the constants defined in the codebase (e.g., mechanisms/evm/constants, mechanisms/svm/constants). 8. TEST CORRECTNESS. Generated tests must assert meaningful behavior, not just that "the function doesn't throw." Do not fabricate expected values — derive them from the spec or existing test fixtures.其中第 3 条与第 7 条在仓库中有直接印证：例如 Go SDK 的 go/mechanisms/evm/constants.go 集中定义了 Scheme 标识符、EIP-3009/Permit2 函数名、PERMIT2Address、MULTICALL3Address、X402ExactPermit2ProxyAddress（vanity 地址0x4020...0001）等常量；TypeScript 与 Python 侧同样有对应的mechanisms/evm/constants文件。凡涉及链 ID、代币地址、小数位，都必须引用这些既有常量，而不是凭记忆硬编码。
三、仓库结构与多语言 SDK 布局
贡献指南给出的顶层结构如下：
x402/ ├── typescript/ # TypeScript SDK (pnpm monorepo) ├── python/ # Python SDK ├── go/ # Go SDK ├── java/ # Java SDK ├── specs/ # Protocol specifications └── examples/ # Example implementations ├── typescript/ ├── python/ └── go/从当前仓库实际内容看，这一骨架得到了进一步扩展：specs/下按schemes/（exact、upto 及按链区分的实现）、transports-v1/、transports-v2/（HTTP、MCP、A2A）组织；docs/存放面向用户的 GitBook/Mintlify 文档源；contracts/为 EVM 智能合约（含 Permit2 代理与审计报告）；e2e/是跨 SDK 的端到端测试；go/mechanisms/evm/还包含 exact 与 upto 两套完整机制。
每个 SDK 都有一份语言专属的贡献指南，供不同技术栈的贡献者按图索骥：
| 指南 | 主要内容 |
|---|---|
| TypeScript 开发指南 | pnpm + Turborepo 工作区结构、Node ≥18/pnpm ≥10.7 前置要求、包依赖分层、lint/format 命令 |
| Python 开发指南 | uv 管理单包、Pydantic 类型与py.typed、Ruff 规范、pytest-asyncio 自动模式 |
| Go 开发指南 | Go 1.24+、golangci-lint、Makefile 命令体系、errors.go中的类型化错误 |
| 规范编写指南 | 规范类型（scheme/transport/core）、MUST/SHOULD/MAY 措辞、安全考量章节 |
从源码看三套 SDK 的实现分工
以 TypeScript 为例，typescript/CONTRIBUTING.md 给出了包依赖的分层结构：
@x402/core ↑ @x402/evm, @x402/svm ↑ @x402/express, @x402/hono, @x402/next, @x402/axios, @x402/fetch即：core提供与传输无关的协议原语，mechanisms包实现链相关逻辑，HTTP 包提供框架集成——这也是新增机制时必须遵循的分层边界：机制包依赖 core，HTTP 包依赖机制包，反之不得依赖。
四、标准贡献工作流
指南给出了六步标准流程：
1. 查找或创建 Issue
动手前先检查既有 issue；对于较大的功能，建议先发起 discussion 讨论方案。
2. Fork 并 Clone 仓库
Fork 仓库后克隆自己的 fork 到本地。
3. 创建分支
git checkout -b feature/your-feature-name4. 修改代码
- 遵循语言专属开发指南（见上文三张子指南）；
- 为新功能编写测试；
- 按需更新文档。
5. 测试
只运行你修改的包对应的测试：
# TypeScript cd typescript && pnpm test # Python cd python/x402 && uv run pytest # Go cd go && make test从仓库实际配置看，这些命令都有对应的底层实现支撑：typescript/package.json 通过 Turborepo 编排build/lint/format/test等脚本（test:integration定向跑@x402/core、@x402/evm等机制包）；go/Makefile 中make test实际执行go test -race -cover ./...，make verify则串联fmt + lint + test作为提交前的快速自检；Python 侧uv run pytest对应python/x402/下tests/unit与tests/integrations两个测试目录。
6. 提交 PR
- 完整填写 PR 模板；
- 关联相关 issue；
- 确保 CI 通过。
五、Changelog 工具链：三个 SDK 三种工具
对于影响用户可见行为的变更（行为变化、bug 修复、新功能、破坏性变更），必须为所修改的 SDK 添加 changelog fragment；纯文档修改和内部重构可跳过。
| SDK | 工具 | Fragment 位置 | 创建命令 |
|---|---|---|---|
| TypeScript | Changesets | typescript/.changeset/*.md | pnpm -C typescript changeset |
| Go | Changie | go/.changes/unreleased/* | make -C go changelog-new |
| Python（python/x402 v2） | Towncrier | python/x402/changelog.d/<PR>.<type>.md | cd python/x402 && uv run towncrier create --content "Fixed ..." 123.bugfix.md |
补充细节：
- TypeScript：
pnpm changeset为交互式命令，需要选择要发布的包、提供过去时态的变更摘要，并选择发布类型——patch（bug 修复、无 API 变更）、minor（向后兼容的新功能）、major（破坏性变更）。拿不准时，修复选 patch、非破坏性新功能选 minor，维护者会在审查和发布时调整版本号。 - Python：fragment 命名约定为
<PR>.<type>.md，允许的 type 为feature | bugfix | doc | removal | misc；维护者发布时用uv run towncrier build --yes --version=X.Y.Z合并 fragment。 - Go：维护者侧的批量合并流程为
make changelog-batch VERSION=v0.1.0再make changelog-merge（见 go/Makefile 中 changie 相关 target）。
六、提交签名：所有提交必须签名
所有提交必须使用 GPG/SSH 签名后再推送：
git config --global commit.gpgsign true提交签名应在提交前配置完成，未签名的提交无法通过合入流程。
七、Paywall 变更：一次修改、五处产物
paywall 是一个横跨 TypeScript、Go、Python 的浏览器端 UI 组件。修改 TypeScript 中的 paywall 源码后，需要重新生成各语言的模板文件：
cd typescript && pnpm --filter @x402/paywall build:paywall该命令会在以下位置生成模板文件（PR 中需一并提交）：
| 语言 | 生成文件 |
|---|---|
| TypeScript | typescript/packages/http/paywall/src/evm/gen/template.ts、typescript/packages/http/paywall/src/svm/gen/template.ts |
| Go | go/http/evm_paywall_template.go、go/http/svm_paywall_template.go |
| Python | python/x402/http/paywall/evm_paywall_template.py（svm 模板同目录） |
从仓库实际文件看，这些生成产物确实存在且一一对应，例如 go/http/evm_paywall_template.go 与 go/http/svm_paywall_template.go，TypeScript 侧则按链分别输出到src/evm/gen/template.ts与src/svm/gen/template.ts。规则是：修改 paywall 源码必须同步提交重新生成的模板，否则跨语言产物会不一致。
八、新增 Scheme：三步提案制
Scheme 定义了资金如何从 client 流向 server。不同的 scheme 具有不同的操作语义——例如exact（先付固定金额再访问资源，如"支付 $1 阅读一篇文章"）与upto（按请求实际消耗的资源付费，如按 token 生成量计费的 LLM）行为截然不同。
新增 scheme 需要经过 x402 Foundation 团队的严格审查，推荐流程为：
- 打开一个只含 spec 的 PR，把方案文档放入
specs/schemes/； - 在该 PR 中讨论架构与目的；
- spec 合入后，再进行实现。
spec 写作遵循 specs/CONTRIBUTING.md：使用scheme_template.md（方案总览）与scheme_impl_template.md（链实现）模板，必须包含 payload 结构、验证逻辑、结算逻辑三要素，并以 MUST/SHOULD/MAY 精确措辞。可参考已合入的规范范例 specs/schemes/exact/scheme_exact_evm.md（含PAYMENT-SIGNATUREheader payload 示例、验证五步、结算逻辑）以及仓库中已有的 scheme_exact_svm.md、scheme_upto_evm.md 等多链实现。
九、新增链支持：三 PR 工作流
x402 的目标是链无关（chain-agnostic）。由于不同链的最佳实践不同，同一 scheme 在不同链上的机制实现可能完全不同（例如在 Ethereum 与 Solana 上实现exact的方式截然不同）；如果方案机制偏离参考实现，x402 Foundation 会在接受前对该链上的方案重新审计。
9.1 快捷路径：仅为 EVM 链添加默认资产
如果只是为 EVM 兼容链添加美元定价（"$0.10"）所需的默认稳定币，不需要走下面的完整三 PR 流程，直接参考 DEFAULT_ASSETS.md：在 TypeScript、Go、Python 三个 SDK 的常量文件中同步添加 CAIP-2 键对应的代币信息（地址、EIP-712name/version、decimals、资产转移方式），三处必须使用相同参数。对应文件分别为typescript/packages/mechanisms/evm/src/shared/defaultAssets.ts、go/mechanisms/evm/constants.go（NetworkConfigsmap）与 Python 的python/x402/mechanisms/evm/constants.py（NETWORK_CONFIGSdict）。
9.2 完整流程：新增链族
PR 1：仅提交规范
为某一个支付 scheme 的实现提交 spec：
- 添加
specs/schemes/<scheme>/scheme_<scheme>_<chain>.md； - 遵循现有 spec 格式，参考 specs/schemes/exact/scheme_exact_evm.md；
- 必须包含：payload 结构、验证逻辑、结算逻辑，写作规范见 specs/CONTRIBUTING.md。
PR 2：参考实现
spec 获批后，先在一个 SDK（TypeScript、Python 或 Go 三选一）中实现：
- 包结构：TS 创建
<sdk>/packages/mechanisms/<chain>/，Py/Go 创建<sdk>/mechanisms/<chain>/；不得修改 core 包； - 必需接口（各 SDK 一一对应）：
| SDK | 接口 |
|---|---|
TypeScript（@x402/core） | SchemeNetworkClient、SchemeNetworkServer、SchemeNetworkFacilitator |
Go（github.com/x402-foundation/x402/go） | ClientScheme、ServerScheme、FacilitatorScheme |
Python（x402） | SchemeNetworkClient、SchemeNetworkServer、SchemeNetworkFacilitator |
- 必需测试（三个层级）：
| 类型 | 目的 | 参考位置 |
|---|---|---|
| 单元测试 | 隔离的组件测试 | typescript/packages/mechanisms/evm/test/unit/ |
| 集成测试 | client/server/facilitator 全流程 | typescript/packages/mechanisms/evm/test/integrations/ |
| 端到端测试 | 跨 SDK 全栈验证 | e2e/ |
- 示例：保持现有用户示例精简，将新链（按网络前缀字母序）添加到
examples/<sdk>/*/advanced/all_networks的 server、client、facilitator 三类示例中； - 后续步骤：按既有模式补充包发布工作流、为新增包编写 README（参考
typescript/packages/mechanisms/evm/README.md）；docs/中的 GitDocs 会由 Mintlify 自动更新。
PR 3：补充其他 SDK 实现
参考实现合入后，可跟进实现其余 SDK 的对应机制。
9.3 接口语义的源码印证
以 EVM 为例，go/mechanisms/evm/constants.go 揭示了机制包背后的实现细节：exact方案在 EVM 上通过 EIP-3009（transferWithAuthorization，推荐，真正无 gas）或 Permit2 代理（任意 ERC-20 的通用回退）完成转账，facilitator 只能作为交易广播者，无法篡改金额与收款方；upto方案则使用独立的X402UptoPermit2ProxyAddress（0x4020...0002）。这套常量体系正是上文 AI 提示词第 7 条"从代码库引用常量而非记忆硬编码"的直接依据。
十、HTTP 中间件与示例
- 中间件：新增 HTTP 框架集成（如 Echo、Chi 或新 TS/Python 框架）时，应遵循目标框架的最佳实践、包含测试、并沿用既有 x402 client/server 模式。Go 侧可参考 go/http/gin/middleware.go 的完整模式（通过
HTTPResourceServer.HandleRequest()处理PAYMENT-SIGNATUREheader 并返回 402 或放行）；TypeScript 侧可参考typescript/packages/http/express/src/adapter.ts的 adapter 模式。 - 示例：各语言示例位于 examples/，新增示例时遵循对应语言指南中的模式（Go 示例需提供引用本地 SDK 的
go.mod，通过replace指令指向仓库内的go模块）。
十一、获取帮助
- 搜索既有 issue，避免重复提问；
- 用新 issue 提出疑问；
- 查阅各语言专属贡献指南与角色文档（Go 侧还有 CLIENT.md、SERVER.md、FACILITATOR.md 供使用模式参考）。
结语：一份以"可信"为第一诉求的贡献规范
纵观整份指南，x402 的贡献流程始终围绕两个关键词展开：安全性（真实资金转移、签名与结算逻辑必须经过人工核验与跨 SDK 一致性检查）与可维护性（精简输出、复用既有常量与模式、强制 changelog fragment、paywall 五处产物同步）。无论是人类开发者还是 AI 编程 Agent，遵循这份规范的核心要义都在于：用更少、更高质量、更可验证的贡献，换取协议在更多网络与更多 scheme 上的可信扩展。
【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
