+
+ private urlTemplate: string
+ private method: 'GET' | 'POST'
+ private plugins: FetchPlugin[]
+ private subscribers = new Map , options?: { skipCache?: boolean }): Promise ,
+ callback: SubscribeCallback ): InferOutput ,
+ _options?: { enabled?: boolean }
+ ): { data: InferOutput ,
+
+ async fetch(params: InferOutput , fetchOptions?: { skipCache?: boolean }) {
+ // 从 source 获取数据
+ const sourceData = await source.fetch(params, fetchOptions)
+
+ // 构建完整的 middlewareContext（包含 superjson 工具）
+ const middlewareContext: import('./types').MiddlewareContext = {
+ name,
+ params: (params ?? {}) as import('./types').FetchParams,
+ skipCache: false,
+ // 直接暴露 superjson 库
+ superjson,
+ // 创建带 X-Superjson 头的 Response
+ createResponse: ,
+ callback: SubscribeCallback ) {
+ // 对于派生实例，getCached 需要同步执行插件链
+ // 这比较复杂，暂时返回 undefined
+ return undefined
+ },
+
+ useState(params?: InferOutput , options?: { enabled?: boolean }) {
+ // 使用 core.ts 中注入的 useState 实现
+ const impl = getUseStateImpl()
+ if (!impl) {
+ throw new Error(
+ `[key-fetch] useState() requires React. Import from '@biochain/key-fetch' to enable React support.`
+ )
+ }
+ return impl(derived as any, params as any, options)
+ },
+ }
+
+ return derived
+}
diff --git a/packages/key-fetch/src/index.ts b/packages/key-fetch/src/index.ts
new file mode 100644
index 000000000..6d71f56bf
--- /dev/null
+++ b/packages/key-fetch/src/index.ts
@@ -0,0 +1,195 @@
+/**
+ * @biochain/key-fetch
+ *
+ * Schema-first 插件化响应式 Fetch
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { keyFetch, interval, deps } from '@biochain/key-fetch'
+ *
+ * // 定义 Schema
+ * const LastBlockSchema = z.object({
+ * success: z.boolean(),
+ * result: z.object({
+ * height: z.number(),
+ * timestamp: z.number(),
+ * }),
+ * })
+ *
+ * // 创建 KeyFetch 实例（工厂模式）
+ * const lastBlockFetch = keyFetch.create({
+ * name: 'bfmeta.lastblock',
+ * schema: LastBlockSchema,
+ * url: 'https://api.bfmeta.info/wallet/:chainId/lastblock',
+ * use: [interval(15_000)],
+ * })
+ *
+ * // 请求（类型安全，已验证）
+ * const data = await lastBlockFetch.fetch({ chainId: 'bfmeta' })
+ *
+ * // 订阅
+ * const unsubscribe = lastBlockFetch.subscribe({ chainId: 'bfmeta' }, (data, event) => {
+ * console.log('区块更新:', data.result.height)
+ * })
+ *
+ * // React 中使用
+ * function BlockHeight() {
+ * const { data, isLoading } = lastBlockFetch.useState({ chainId: 'bfmeta' })
+ * if (isLoading) return ,
+
+ async fetch(): Promise ,
+ _callback: SubscribeCallback ,
+ _options?: UseKeyFetchOptions
+ ): UseKeyFetchResult , options?: { skipCache?: boolean }): Promise ,
+ callback: SubscribeCallback ): InferOutput ,
+ options?: UseKeyFetchOptions
+ ): UseKeyFetchResult (options?: {
+ /** 额外固定参数（合并到 params） */
+ defaults?: P
+ /** 转换函数（自定义 query params 格式） */
+ transform?: (params: P) => Record {
+ return {
+ name: 'params:searchParams',
+ onFetch: async (request, next, context) => {
+ const url = new URL(request.url)
+
+ // 合并默认参数并转换
+ const mergedParams = {
+ ...options?.defaults,
+ ...context.params,
+ }
+ if (options?.defaults) {
+ for (const key in mergedParams) {
+ if (mergedParams[key] == null && options?.defaults?.[key] != null) {
+ (mergedParams as any)[key] = options?.defaults?.[key]
+ }
+ }
+ }
+ const finalParams = options?.transform
+ ? options.transform(mergedParams)
+ : mergedParams
+
+ // 添加 params 到 URL search params
+ for (const [key, value] of Object.entries(finalParams)) {
+ if (value !== undefined) {
+ url.searchParams.set(key, String(value))
+ }
+ }
+
+ // 创建新请求（更新 URL）
+ const newRequest = new Request(url.toString(), {
+ method: request.method,
+ headers: request.headers,
+ body: request.body,
+ })
+
+ return next(newRequest)
+ },
+ }
+}
+
+/**
+ * PostBody 插件
+ *
+ * 将 params 设置为 POST 请求的 JSON body
+ *
+ * @example
+ * ```ts
+ * const fetcher = keyFetch.create({
+ * name: 'transactions',
+ * schema: TransactionsSchema,
+ * url: 'https://api.example.com/transactions/query',
+ * method: 'POST',
+ * use: [postBody()],
+ * })
+ *
+ * // fetch({ address: 'xxx', page: 1 }) 会请求:
+ * // POST https://api.example.com/transactions/query
+ * // Body: { "address": "xxx", "page": 1 }
+ * ```
+ */
+export function postBody(options?: {
+ /** 额外固定参数（合并到 params） */
+ defaults?: FetchParams
+ /** 转换函数（自定义 body 格式） */
+ transform?: (params: FetchParams) => unknown
+}): FetchPlugin {
+ return {
+ name: 'params:postBody',
+ onFetch: async (request, next, context) => {
+ // 合并默认参数
+ const mergedParams = {
+ ...options?.defaults,
+ ...context.params,
+ }
+
+ // 转换或直接使用
+ const body = options?.transform
+ ? options.transform(mergedParams)
+ : mergedParams
+
+ // 创建新请求（POST with JSON body）
+ const newRequest = new Request(request.url, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify(body),
+ })
+
+ return next(newRequest)
+ },
+ }
+}
+
+/**
+ * Path Params 插件
+ *
+ * 将 params 替换到 URL 路径中的 :param 占位符
+ *
+ * @example
+ * ```ts
+ * const fetcher = keyFetch.create({
+ * name: 'user',
+ * schema: UserSchema,
+ * url: 'https://api.example.com/users/:userId/profile',
+ * use: [pathParams()],
+ * })
+ *
+ * // fetch({ userId: '123' }) 会请求:
+ * // GET https://api.example.com/users/123/profile
+ * ```
+ */
+export function pathParams(): FetchPlugin {
+ return {
+ name: 'params:pathParams',
+ onFetch: async (request, next, context) => {
+ let url = request.url
+
+ // 替换 :param 占位符
+ for (const [key, value] of Object.entries(context.params)) {
+ if (value !== undefined) {
+ url = url.replace(`:${key}`, encodeURIComponent(String(value)))
+ }
+ }
+
+ // 创建新请求（更新 URL）
+ const newRequest = new Request(url, {
+ method: request.method,
+ headers: request.headers,
+ body: request.body,
+ })
+
+ return next(newRequest)
+ },
+ }
+}
diff --git a/packages/key-fetch/src/plugins/tag.ts b/packages/key-fetch/src/plugins/tag.ts
new file mode 100644
index 000000000..a103dfde6
--- /dev/null
+++ b/packages/key-fetch/src/plugins/tag.ts
@@ -0,0 +1,67 @@
+/**
+ * Tag Plugin
+ *
+ * 标签插件 - 用于批量失效（中间件模式）
+ */
+
+import type { FetchPlugin } from '../types'
+
+// 全局标签映射
+const tagToInstances = new Map = (
+ request: Request,
+ next: (request: Request) => Promise
+) => Promise {
+ /** KeyFetch 实例名称 */
+ name: string
+ /** 原始请求参数（强类型） */
+ params: P
+ /** 是否跳过缓存 */
+ skipCache: boolean
+
+ // ==================== SuperJSON 工具 (核心标准) ====================
+
+ /** SuperJSON 库实例（支持 BigInt、Date 等特殊类型的序列化） */
+ superjson: typeof import('superjson').default
+ /** 创建包含序列化数据的 Response 对象（自动添加 X-Superjson: true 头） */
+ createResponse: {
+ /** 插件名称（用于调试和错误追踪） */
+ name: string
+
+ /**
+ * 中间件函数
+ *
+ * 接收 Request 和 next 函数，返回 Response
+ * - 可以修改 request 后传给 next()
+ * - 可以修改 next() 返回的 response
+ * - 可以不调用 next() 直接返回缓存的 response
+ */
+ onFetch: FetchMiddleware
+
+ /**
+ * 订阅时调用（可选）
+ * 用于启动轮询等后台任务
+ * @returns 清理函数
+ */
+ onSubscribe?: (context: SubscribeContext ) => (() => void) | void
+}
+
+/** 订阅上下文 */
+export interface SubscribeContext {
+ /** KeyFetch 实例名称 */
+ name: string
+ /** 请求参数（强类型） */
+ params: P
+ /** 完整 URL */
+ url: string
+ /** 触发数据更新 */
+ refetch: () => Promise
+
+ /**
+ * 执行请求
+ * @param params 请求参数（强类型）
+ * @param options 额外选项
+ */
+ fetch(params: InferOutput , options?: { skipCache?: boolean }): Promise ,
+ callback: SubscribeCallback ): InferOutput ,
+ options?: UseKeyFetchOptions
+ ): UseKeyFetchResult
+
+ // 通知 registry 更新
+ globalRegistry.emitUpdate(this.name)
+
+ return result
+ } catch (err) {
+ // 包装 ZodError 为更可读的错误
+ if (err && typeof err === 'object' && 'issues' in err) {
+ const zodErr = err as { issues: Array<{ path: (string | number)[]; message: string }> }
+ const issuesSummary = zodErr.issues
+ .slice(0, 3)
+ .map(i => ` - ${i.path.join('.')}: ${i.message}`)
+ .join('\n')
+ throw new Error(
+ `[${this.name}] Schema 验证失败:\n${issuesSummary}` +
+ (zodErr.issues.length > 3 ? `\n ... 还有 ${zodErr.issues.length - 3} 个错误` : '') +
+ `\n\n原始数据预览: ${JSON.stringify(json).slice(0, 300)}...`
+ )
+ }
+ throw err
+ }
+ }
+
+ subscribe(
+ params: InferOutput | undefined {
+ const cacheKey = buildCacheKey(this.name, params as FetchParams)
+ const entry = globalCache.get): void {
+ const subs = this.subscribers.get(cacheKey)
+ if (subs) {
+ subs.forEach(cb => cb(data, 'update'))
+ }
+ }
+
+ /**
+ * React Hook - 由 react.ts 模块注入实现
+ * 如果直接调用而没有导入 react 模块，会抛出错误
+ */
+ useState(
+ _params?: InferOutput | undefined; isLoading: boolean; isFetching: boolean; error: Error | undefined; refetch: () => Promise(
+ kf: KeyFetchInstance,
+ params?: FetchParams,
+ options?: { enabled?: boolean }
+) => { data: InferOutput | undefined; isLoading: boolean; isFetching: boolean; error: Error | undefined; refetch: () => Promise(
+ options: KeyFetchDefineOptions(name: string): KeyFetchInstance | undefined {
+ return globalRegistry.get(name)
+}
+
+/** 按名称失效 */
+export function invalidate(name: string): void {
+ globalRegistry.invalidate(name)
+}
+
+/** 清理所有（用于测试） */
+export function clear(): void {
+ globalRegistry.clear()
+ globalCache.clear()
+}
diff --git a/packages/key-fetch/src/derive.ts b/packages/key-fetch/src/derive.ts
new file mode 100644
index 000000000..5ee41e889
--- /dev/null
+++ b/packages/key-fetch/src/derive.ts
@@ -0,0 +1,212 @@
+/**
+ * Derive - 从基础 KeyFetchInstance 派生新实例
+ *
+ * 设计模式：类似 KeyFetchDefineOptions，统一使用 `use` 插件系统
+ * 共享同一个数据源，通过插件应用转换逻辑
+ *
+ * @example
+ * ```ts
+ * // 基础 fetcher（获取原始数据）
+ * const #assetFetcher = keyFetch.create({
+ * name: 'biowallet.asset',
+ * schema: AssetResponseSchema,
+ * url: '/address/asset',
+ * })
+ *
+ * // 派生：Balance 视图（使用 transform 插件）
+ * const nativeBalance = keyFetch.derive({
+ * name: 'biowallet.balance',
+ * source: #assetFetcher,
+ * schema: BalanceOutputSchema,
+ * use: [
+ * transform((raw) => ({
+ * amount: Amount.fromRaw(raw.result.assets[0].balance, 8, 'BFM'),
+ * symbol: 'BFM'
+ * })),
+ * ],
+ * })
+ * ```
+ */
+
+import type {
+ KeyFetchInstance,
+ AnyZodSchema,
+ InferOutput,
+ SubscribeCallback,
+ FetchPlugin,
+} from './types'
+import { getUseStateImpl } from './core'
+import superjson from 'superjson'
+
+/** 派生选项 - 类似 KeyFetchDefineOptions */
+export interface KeyFetchDeriveOptions<
+ TSourceSchema extends AnyZodSchema,
+ TOutputSchema extends AnyZodSchema,
+ P extends AnyZodSchema = AnyZodSchema,
+> {
+ /** 唯一名称 */
+ name: string
+ /** 源 KeyFetchInstance */
+ source: KeyFetchInstance {
+ /** 合并后的名称 */
+ name: string
+ /** 源 fetcher 数组（可以是空数组） */
+ sources: KeyFetchInstance(
+ options: MergeOptions(
+ name: string,
+ handleEmpty: () => never
+): KeyFetchInstance,
+ _params: undefined as unknown as InferOutput | undefined {
+ return undefined
+ },
+
+ useState(
+ _params?: InferOutput(
+ name: string,
+ sources: KeyFetchInstance | undefined {
+ // 从第一个有缓存的 source 获取
+ for (const source of sources) {
+ const cached = source.getCached(params)
+ if (cached !== undefined) {
+ return cached
+ }
+ }
+ return undefined
+ },
+
+ useState(
+ params?: InferOutput(
+ kf: KeyFetchInstance,
+ params?: FetchParams,
+ options?: UseKeyFetchOptions
+): UseKeyFetchResult
+
+ const [data, setData] = useState(
+ kf: KeyFetchInstance,
+ params: FetchParams | undefined,
+ callback: (data: InferOutput, event: 'initial' | 'update') => void
+): void {
+ const callbackRef = useRef(callback)
+ callbackRef.current = callback
+
+ useEffect(() => {
+ const unsubscribe = kf.subscribe(params ?? {}, (data, event) => {
+ callbackRef.current(data, event)
+ })
+
+ return () => {
+ unsubscribe()
+ }
+ }, [kf, JSON.stringify(params)])
+}
+
+// ==================== 注入 useState 实现 ====================
+
+/**
+ * 内部 useState 实现
+ * 复用 useKeyFetch 逻辑，供 KeyFetchInstance.useState() 调用
+ */
+function useStateImpl(
+ kf: KeyFetchInstance,
+ params?: FetchParams,
+ options?: { enabled?: boolean }
+): UseKeyFetchResult(kf: KeyFetchInstance): void {
+ this.instances.set(kf.name, kf as KeyFetchInstance(name: string): KeyFetchInstance | undefined {
+ return this.instances.get(name) as KeyFetchInstance | undefined
+ }
+
+ invalidate(name: string): void {
+ const kf = this.instances.get(name)
+ if (kf) {
+ kf.invalidate()
+ }
+ }
+
+ onUpdate(name: string, callback: () => void): () => void {
+ let listeners = this.updateListeners.get(name)
+ if (!listeners) {
+ listeners = new Set()
+ this.updateListeners.set(name, listeners)
+ }
+ listeners.add(callback)
+
+ return () => {
+ listeners?.delete(callback)
+ }
+ }
+
+ emitUpdate(name: string): void {
+ // 通知自身的监听者
+ const listeners = this.updateListeners.get(name)
+ if (listeners) {
+ listeners.forEach(cb => cb())
+ }
+
+ // 通知依赖此实例的其他实例
+ const dependentNames = this.dependents.get(name)
+ if (dependentNames) {
+ dependentNames.forEach(depName => {
+ this.emitUpdate(depName)
+ })
+ }
+ }
+
+ addDependency(dependent: string, dependency: string): void {
+ // dependent 依赖 dependency
+ let deps = this.dependencies.get(dependent)
+ if (!deps) {
+ deps = new Set()
+ this.dependencies.set(dependent, deps)
+ }
+ deps.add(dependency)
+
+ // dependency 被 dependent 依赖
+ let dependentSet = this.dependents.get(dependency)
+ if (!dependentSet) {
+ dependentSet = new Set()
+ this.dependents.set(dependency, dependentSet)
+ }
+ dependentSet.add(dependent)
+ }
+
+ clear(): void {
+ this.instances.clear()
+ this.updateListeners.clear()
+ this.dependencies.clear()
+ this.dependents.clear()
+ }
+}
+
+/** 全局 Registry 单例 */
+export const globalRegistry = new KeyFetchRegistryImpl()
diff --git a/packages/key-fetch/src/types.ts b/packages/key-fetch/src/types.ts
new file mode 100644
index 000000000..238c602bb
--- /dev/null
+++ b/packages/key-fetch/src/types.ts
@@ -0,0 +1,252 @@
+/**
+ * Key-Fetch Types
+ *
+ * Schema-first 插件化响应式 Fetch 类型定义
+ */
+
+import type { z } from 'zod'
+
+// ==================== Schema Types ====================
+
+/** 任意 Zod Schema */
+export type AnyZodSchema = z.ZodType = z.infer
+
+// ==================== Cache Types ====================
+
+/** 缓存条目 */
+export interface CacheEntry
+ /** 参数类型（用于类型推断） */
+ readonly _params: InferOutput | undefined
+
+ /**
+ * React Hook - 响应式数据绑定
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = balanceFetcher.useState({ address })
+ * if (isLoading) return (kf: KeyFetchInstance): void
+ /** 获取实例 */
+ get(name: string): KeyFetchInstance | undefined
+ /** 按名称失效 */
+ invalidate(name: string): void
+ /** 监听实例更新 */
+ onUpdate(name: string, callback: () => void): () => void
+ /** 触发更新通知 */
+ emitUpdate(name: string): void
+ /** 添加依赖关系 */
+ addDependency(dependent: string, dependency: string): void
+ /** 清理所有 */
+ clear(): void
+}
+
+// ==================== React Types ====================
+
+/** useKeyFetch 返回值 */
+export interface UseKeyFetchResult