Wagmi Tempo 文档规范Actions 与 Hooks 模板体系与源码级实现解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文以 Wagmi 仓库中面向 AI Agent 与文档作者的编写指引 site/AGENTS.md 为主体系统讲解 Wagmi 文档站 Tempo 模块的文档组织规则与六大文档模板Query/Mutation/Watch Actions、Query/Mutation/Watch Hooks并结合 packages/core/src/tempo 与 packages/react/src/tempo 的实际源码说明“文档必须基于对应 Action 编写”这一原则背后的调用链与类型体系读完后可按规范独立完成一篇 Tempo Action/Hook 文档并保证与实现一致。指南定位与编写风格约束site/AGENTS.md 是 Wagmi 文档站site/目录的 Agent 行为指引其开头即给出两条全局约束沟通风格要求“简短、精炼、信息密度最大化、token 最小化允许在不歧义的情况下使用不完整句删除填充词优先清晰而非语法”——这是对文档生成过程的效率约束Tempo 文档归属所有 Tempo 文档必须添加在/tempo侧边栏条目之下对应仓库中的 site/tempo/ 目录。文档主体分为两大板块Wagmi Actions 文档规范与Wagmi Hooks 文档规范每个板块给出该板块的三条硬规则 若干 Markdown 模板。核心原则文档必须基于对应的 Wagmi Action指南在“Wagmi Actions”一节明确要求所有文档必须基于其对应的 Wagmi Actions这些 Action 位于wagmi/core/tempo入口源码目录为 packages/core/src/tempo/新增 Action 时必须同步更新总览表 site/tempo/actions/index.md。“从源码结构看”这一约束有清晰的落点packages/core/src/tempo/actions/ 下按命名空间组织为amm.ts、dex.ts、faucet.ts、fee.ts、nonce.ts、policy.ts、reward.ts、token.ts、wallet.ts、zone.ts十个 Action 模块外加index.ts与utils.ts每个模块均配有*.test.ts与*.test-d.ts行为测试 类型测试。总览表 site/tempo/actions/index.md 也据此按 AMM、Faucet、Fee、Nonce、Policy、Reward、Stablecoin DEX、Token、Wallet、Zone 十个分组列出约 90 个 Action例如Action描述摘自总览表amm.burnBurns liquidity tokens and receives the underlying token pairdex.placePlaces a limit order on the orderbooktoken.transferTransfers TIP-20 tokens from the caller to a recipientzone.waitForTempoBlockWaits for a zone to import a Tempo block也就是说文档站中每一个namespace.action页面都不是自由撰写的而是对源码中同名导出函数的“类型化镜像”。源码层面的印证Action 如何委托给 viem以 packages/core/src/tempo/actions/amm.ts 中的getPool为例Wagmi Action 的签名与实现模式高度一致export function getPoolconfig extends Config( config: config, parameters: getPool.Parametersconfig, ): PromisegetPool.ReturnValue { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.amm.getPool(client, rest) }即接收 Wagmi 的Config按chainId取出 client再委托给 viem 的Actions.amm.getPool。这正是指南模板中每个 Action 页都带一节“Viem”链接指向 viem Tempo Actions 对应条目的原因——Wagmi 层是 viem Action 之上加了Config参数与chainId解析的薄封装文档描述参数与返回值时必须与该封装的类型保持一致。Query Action 文档模板指南给出的 Query Action 模板site/AGENTS.md 第 16–77 行要求每篇文档包含以下固定小节缺一不可# namespace.action description ## Usage ::: code-group ts twoslash [example.ts] // filename: config.ts // errors: 2322 import type { Config } from wagmi import { tempoTestnet } from wagmi/chains export const config {} as Configreadonly [typeof tempoTestnet] // filename: example.ts // ---cut--- import { Actions } from wagmi/tempo import { config } from ./config const result await Actions.amm.action(config, { foo: 0x..., bar: 123n, }) console.log(Result:, result) // log: Result: 10500000000000000000n /snippets/react/config-tempo.ts{ts} [config.ts] :::Return TypebigintdescriptionParametersfooType:Addressdescriptionbar (optional)Type:HexdescriptionViem[namespace.action]模板要点逐项拆解 1. **::: code-group 双栏结构**左栏是可交互的 ts twoslash 示例带 // filename、// ---cut---、// log: 等 twoslash 指令// log: 用于断言运行时输出右栏通过 /snippets/react/config-tempo.ts{ts} 引入共享的 config.ts 代码片段。该片段在仓库中真实存在即 [site/snippets/react/config-tempo.ts](https://link.gitcode.com/i/a0b731d55beb0e02a1fa3061e974d467) ts import { createConfig, http } from wagmi import { tempo } from wagmi/chains import { tempoWallet } from wagmi/tempo export const config createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })共享 config 片段保证所有 Tempo 文档示例使用同一套tempoWallet连接器 tempo链 http()传输的配置读者看到的示例彼此一致、可复制运行。参数小节固定格式每个参数以### 参数名 (optional)起头紧跟- **Type:** \类型再接一句话描述可选参数必须在标题标注(optional)。## Viem节必须链接到 viem 侧对应 Action 页明确 Wagmi Action 的底层来源。Mutation Action 文档模板*Sync变体与异步用法Mutation写链Action 模板site/AGENTS.md 第 79–163 行在 Query 模板基础上增加了三处关键内容这也是 Tempo 文档区别于一般 wagmi 文档的特色默认示例使用*Sync变体——即等待交易被打包进区块后才返回示例中调用的是Actions.namespace.actionSync并通过// log:断言同步返回值### Asynchronous Usage小节——面向性能优化的手动等待路径import { Actions as viem_Actions } from viem/tempo import { Actions } from wagmi/tempo import { waitForTransactionReceipt } from wagmi/actions const hash await Actions.namespace.action(config, { foo: 0x..., bar: 123n, }) const receipt await waitForTransactionReceipt(config, { hash }) const { args: { baz } } viem_Actions.namespace.action.extractEvent(receipt.logs)注意异步路径中引入了viem/tempo的同名extractEvent非 sync Action 只返回交易 hash事件参数需要从 receipt logs 中解析而解析工具恰好在 viem 侧提供。这一细节在仓库的真实文档 site/tempo/actions/amm.burn.md 中被完整执行amm.burnSync示例返回{ amountUserToken, amountValidatorToken, receipt }等字段异步示例则用viem_Actions.amm.burn.extractEvent(receipt.logs)提取amountUserToken/amountValidatorToken。 3.共享写参包含模板末尾的!--include: shared/tempo-write-parameters.md--指令引入通用交易参数如 account、chainId 等写操作共有参数该共享文件位于 site/shared/tempo-write-parameters.md避免每篇 mutation 文档重复罗列。Watch Action 文档模板五个固定参数Watch Action 模板site/AGENTS.md 第 165–254 行规定监听型文档的参数小节必须覆盖以下五个参数返回类型固定为() void返回一个取消订阅函数参数类型说明onActionfunction回调(args, log) voidArgs结构体需逐字段给出 JSDoc 式描述fromBlock(optional)bigint开始监听的区块onError(optional)function获取新区块出错时的回调(error: Error) voidpoll(optional)true启用轮询模式pollingInterval(optional)number轮询频率ms默认取 Client 的pollingInterval配置Usage 示例的骨架为调用Actions.namespace.watchAction(config, { onAction(args, log) { ... } })得到unwatch函数并在“Later, stop watching”注释后调用unwatch()演示取消订阅的完整生命周期。Wagmi Hooks 文档规范三大 Hook 模板指南的“Wagmi Hooks”一节site/AGENTS.md 第 256 行起规定了与 Actions 完全镜像的三条规则所有文档必须基于对应的 Wagmi Hooks位于wagmi/tempo入口源码目录为 packages/react/src/tempo/新增 Hook 时必须更新总览表 site/tempo/hooks/index.md一个完整的生成式 hook 集示例可在 site/tempo/hooks/amm.useLiquidityBalance.md 找到其源码实现集中在 packages/react/src/tempo/hooks/amm.ts。Query Hook 模板Usage 示例为Hooks.namespace.useHook({ ... })并解构dataReturn Type 直接引用 TanStack Query 的useQuery文档语义data字段则锚定回对应 Action 文档的#return-type章节如/tempo/actions/namespace.action#return-typeParameters 章节复用 Action 的参数说明额外补充query参数指向 TanStack Query 查询参数语义文末## Action节反向链接回 Action 文档形成 Action ↔ Hook 双向引用。Mutation Hook 模板Usage 默认演示useHookSync()变体actionNameSync.mutate({ ... })后读取actionNameSync.data?.baz### Asynchronous Usage与 Action 侧对称非 sync Hook 配合useWaitForTransactionReceipt拿到receipt后再extractEvent参数小节固定包含config类型Config | undefined说明为“替代从最近WagmiProvider获取的 Config”与mutation指向 TanStack Query mutation 参数语义两项。Watch Hook 模板Usage 示例直接内联回调Hooks.amm.useWatchHook({ onAction(args, log) { ... } })Parameters 复用对应namespace.watchAction的参数说明再补充config参数## Action节同时链接namespace.action与namespace.watchAction两个 Action 文档。模板与源码的一致性以usePool为例模板中的 Hook 写法并非虚构而是与 packages/react/src/tempo/hooks/amm.ts 的实现逐字段对应export function usePool config extends Config ResolvedRegister[config], selectData Actions.amm.getPool.ReturnValue, (parameters: usePool.Parametersconfig, selectData {}, ): usePool.ReturnValueselectData { const config useConfig(parameters) const chainId useChainId({ config }) const options Actions.amm.getPool.queryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, } as never) return useQuery(options) as never }可以看到模板要求“返回类型见 TanStack Query useQuery 文档、data 见 Action 返回类型”正是类型体系的直接反映ReturnValue就是UseQueryReturnTypeselectData, ErrorselectData默认值即Actions.amm.getPool.ReturnValue。同时 Action 侧见上文 amm.ts 中getPool命名空间还导出了queryKey与queryOptions——Hook 内部正是复用 Action 的queryOptions来构造查询并自动注入useConfig/useChainId解析出的config与chainId。这解释了为什么指南坚持“Hook 文档的参数与返回类型必须引用 Action 文档”两者的类型在源码层面本来就是同一个定义独立描述必然漂移。按规范撰写 Tempo 文档的实操清单综合 site/AGENTS.md 与上述源码证据在文档站新增一个 Tempo Action/Hook 页面时先读源码在 packages/core/src/tempo/actions/Action或 packages/react/src/tempo/hooks/Hook中确认函数名、Parameters/ReturnValue类型与可选性参数描述以 JSDoc 与类型签名为准选对模板读链用 Query 模板写链用 Mutation 模板示例必须含*Sync Asynchronous Usage 双段并以include引入 site/shared/tempo-write-parameters.md监听用 Watch 模板参数必须覆盖onAction/fromBlock/onError/poll/pollingInterval五项统一示例骨架Usage 一律code-group示例代码使用wagmi/tempo的Actions/Hooks导入并引用共享片段 site/snippets/react/config-tempo.ts更新总览表把新条目加入 site/tempo/actions/index.md 或 site/tempo/hooks/index.md 对应分组双向链接Action 文档末尾链向 viem 对应 ActionHook 文档末尾## Action节链回对应 Action 页含#return-type、#parameters锚点保证 Action ↔ Hook 双向可达落位侧边栏文件必须放在 site/tempo/ 下归属/tempo侧边栏条目。遵循这套模板体系后新增 Tempo 文档既能保持与 site/tempo/actions/amm.burn.md 等既有条目一致的风格又能通过“参数/返回类型引用源码同名类型”这一约束让文档随 packages/core/src/tempo 与 packages/react/src/tempo 的实现演进而自然保持准确。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考