项目架构Copy Anchor Link

v7 架构建立在三个决策上：

1. 一个端点一份声明。 新接口写成一份 defineEndpoint 端点声明，参数类型、运行时校验、HTTP 路由、fetcher 方法与文档全部由它派生 —— 加一个接口从 v6 的「改 11–15 个文件」降到「改 1 个文件」。
2. 单向依赖。 代码按层组织，方向被 CI（dpdm 0 环）钉死。
3. 统一信封。 所有平台、所有调用返回同一个 AmagiResult<T>，成功与失败的字段名跨平台一致。

目录结构Copy Anchor Link

核心代码在 packages/core/src/，六个职责层（contracts / transport / platforms / runtime / client / server）加一个入口 index.ts，逐层职责见下面各小节。

下面这棵树不是手抄的：构建期用 glob 扫 packages/core/src/**/*.ts 现生成 （<auto-files>），点开即是磁盘上的真实结构。目录一改，这页跟着改，不存在抄漏或过期。

因此它也会如实显示：仓库当前仍处于 v6 → v7 过渡收尾，src/ 下还残留 model/、 validation/、types/、utils/ 等旧目录与 v6 低阶入口（transport/legacy.ts 等 @deprecated 保留点），正按阶段 6 的删除清单清理。v6 的平台实现已收进 platforms/legacy/（原先并列的 platform/ 单数目录已于 2026-09-14 合并掉）。 本文描述的是 v7 的目标结构：新增代码一律进上面六层，不在旧目录里落任何新东西。

contracts —— 零依赖叶子层Copy Anchor Link

谁都可以依赖它，它不依赖仓库内任何其他模块（外部只有 zod 的类型导入）。

transport —— 全仓唯一发请求的地方Copy Anchor Link

「全仓只有 transport 能发请求」是架构约束：端点要发请求（换 guest cookie、取 wbi key）只能通过 ctx.send，由 transport 注入 —— v6 里 wbi.ts 绕过 fetchData 直连 axios 的问题（缺陷 A5）在结构上不再可能发生。

platforms/<platform> —— 平台实现Copy Anchor Link

runtime —— 管线与横切能力Copy Anchor Link

client 与 serverCopy Anchor Link

依赖方向Copy Anchor Link

contracts 在最底层、server 在最顶层，箭头指向被依赖方：

即 transport 只能依赖 contracts；platforms 只能依赖 transport 与 contracts；越往上能依赖的层越多，任何反向或跨越依赖都是错误 —— CI 用 dpdm 检查，必须报 0 环（v6 的 36 处循环依赖是缺陷 1，直接促成这层设计）。

两个容易破环的难点是这样解决的：

• 端点钩子要发请求，但 contracts 不能依赖 transport。 EndpointCtx 在 contracts 里只声明 send 的形状，实现由 transport 在运行时注入（依赖倒置）。
• transport 要上报事件，但不能反向依赖 runtime/events。 事件总线交给 transport 的只是一个 emit(event, { trace }) 出口，meta 由 runtime 侧补上。

数据流Copy Anchor Link

一次 fetcher 调用在管线里的旅程。build 返回数组时 ③ 之后是多请求聚合 / 分段并发， judge 缺省取平台自己的那份：

图里那条虚线就是声明式翻页（paginate）：每页都完整走一遍 ③ → ⑦ 并重新签名， 最后由 paginate.merge 把跨页累积的条目收敛成一次结果（分页端点的收尾在这里，不在端点级 normalize）。整段调用从头到尾只有一个 requestId，实际发出几个请求看 meta.attempts。

端点声明Copy Anchor Link

新接口 = 一份端点声明。真实例子（packages/core/src/platforms/douyin/endpoints/videoWork.ts）：

import zod from 'zod'

import type { RequestSpec } from '../../../contracts/request'
import type { DouyinVideoWorkResponse } from '../../../types/generated'
import { createDouyinApiUrls } from '../api'
import { withDouyinReferer } from '../referer'
import { douyinBogus } from '../sign/steps'
import { DOUYIN_RISK_RETRY, defineDouyinEndpoint, type } from './define'

/**
 * 视频作品详情（新路径 `/fetch_video_work`，避免与其他作品类型共用路由）。
 *
 * 行为与旧版一致：`getWorkDetail` GET + a_bogus 签名。
 */
export const videoWork = defineDouyinEndpoint({
  name: 'douyin.videoWork',
  route: '/fetch_video_work',
  doc: {
    summary: '视频作品详细信息',
    description: '已知是视频作品时用这条；形态不确定时先用 `parseWork` 自动识别。'
  },
  params: zod.object({
    aweme_id: zod.string().min(1, { error: '作品ID不能为空' }).describe('作品 ID')
  }),
  build: (p, ctx): RequestSpec => ({
    method: 'GET',
    url: createDouyinApiUrls(ctx.userAgent).getWorkDetail(p),
    headers: withDouyinReferer(ctx, { kind: 'video', awemeId: p.aweme_id })
  }),
  sign: douyinBogus(184),
  retryOn: DOUYIN_RISK_RETRY,
  retryFresh: true,
  response: type<DouyinVideoWorkResponse>(),
  // 预留：跨平台语义视图接入时在此填 (raw) => CanonicalWork
  toCanonical: undefined
})

真实声明里用的是平台专属的 defineDouyinEndpoint（就是 defineEndpoint 绑定了抖音签名器名联合，把 sign 收窄成 'a-bogus' | 'x-bogus'、写错编译期即报错，见新增接口）；它和 defineEndpoint 运行时都是恒等函数，全部价值在类型推导：TParams 从 params 推出，TData 从 response / normalize / compute 推出。响应类型直接复用 v6 的 types/ReturnDataType 快照类型（映射键与端点短名一一对应），v6 快照自带顶层索引签名，平台加字段不算 breaking。

可选槽位（每种对应一种非常规端点形态）：

每个平台的 endpoints/index.ts 把全部声明汇总成 registry 对象。派生时有两条自动保证：fetcher 方法集合自动跟随 registry；路由唯一性在派生路由时校验，同平台内 route 重复会直接抛错（v6 抖音 5 个端点撞同一路由的 #47/#48/#54 就是这么修的）。

声明派生出什么Copy Anchor Link

fetcher 方法名默认按「fetch + 端点短名首字母大写」规则派生；只有不规则名（parseWork、searchContent、convertAvToBv 等 16 个）才需要动 client/method-names.ts。这张表是全仓唯一手写映射 —— 漏一个等于某个方法凭空消失，因此有测试拿四个平台的活 fetcher 对象逐个核对。

统一响应信封Copy Anchor Link

所有对外 API 返回同一个信封：

import type { AmagiResult } from '@ikenxuan/amagi'

declare const r: AmagiResult<{ id: string }>

if (r.success) {
  r.data // 收窄后是 { id: string }
} else {
  r.error // 收窄后是 AmagiError
}

三条硬约束：

1. 顶层没有 code。 v6 用同一个 code 混装 HTTP 状态码、平台业务码与内部码；v7 各归各位 —— HTTP 状态在 error.http.status，平台业务码在 error.platform.code，amagi 自己的错误码在 error.code。成功信封因此没有任何多余字段。
2. 成功分支没有 error 键，失败分支没有 data 键。 v6 用 undefined as never 声明占位、键却留在运行时对象里；v7 直接不声明。
3. success 是唯一判别键。 if (r.success) 之后 data 可用、else 之后 error 可用 —— v6 的成功分支代码零改动。

另有运行时保证：信封永不 reject。参数校验失败、平台业务错误、网络错误、内部异常全部映射为 success: false。注意这是行为变化：v6 里参数校验失败会 throw，v7 里不再进 catch。

失败分支的 error 形状：

成败判定收敛到一处：每个平台一份 judge.ts 纯函数，把原始响应映射为「成功 / 某个 kind」。v6 里 4 个 internal.ts 与 GlobalGetData 各自为政的判定逻辑（缺陷 A2）在 v7 里只剩这一个判定点。

事件总线与 metaCopy Anchor Link

v6 的事件系统有两个问题：总线是全局单例（一个 amagiEvents 全库共用），且事件负载里没有任何关联 id（缺陷 10）—— 多实例并发时监听器分不清事件来自谁。v7 的两个对应变化：

实例级总线。 每个 amagi() 实例自带一条总线：client.events / client.on / client.once，实例之间互不串扰。静态 fetcher（amagi.douyinFetcher.fetchXxx(...)，不经过 client 实例）不发事件 —— 它的签名是 v6 冻结的三参形式，没有装总线的位置，要观测就用 client 形态。

所有负载都带 meta。 15 个事件名（12 个与 v6 逐名对齐 + 3 个 v7 独占的 session:*）与各自的负载见事件系统，这里只列最常用的四个：

meta 挂在每个信封与每条事件负载上：

trace 里的每条请求还标注 reason：initial（首次）/ retry（重试）/ challenge（解出反爬挑战后的重放）/ page（翻页）/ segment（分段并发）/ prepare（前置请求）。一次「翻 3 页 + 1 次重试」的调用，attempts === 4、trace 里有 4 条记录 —— 重试叠乘（A4）与事件无法归因这两类问题从此有直接可观测的数字。

会话（登录）Copy Anchor Link

扫码登录这类多步有状态流程不是端点：四个平台的 client.<platform>.login 都提供 qrcode()（新建会话）与 resume()（从 serialize() 的产物恢复）；B站另有 refreshCredential 做 Cookie 续期。

引擎（runtime/session.ts）负责轮询循环、退避、超时、取消与 challenge 编排；平台策略（platforms/<platform>/session/qrcode.ts）只写协议细节。会话状态以 LoginState 的 phase 判别：pending（二维码就绪）→ scanned（已扫待确认）→ challenge（需应答短信 / 图形验证码）→ success（产出 credential）；终止态为 expired / rejected / risk / failed。

消费方式三种：watch() 回调（onQrcode / onScanned / onChallenge / onSuccess 等）、for await（AsyncIterable）、手动单步（start() + next()）。v6 抖音 passport 的 4 个顶层方法（requestPassportQrcode 等）作为 @deprecated 保留在静态 fetcher 上，新代码请走 login 会话。

术语Copy Anchor Link

最后更新于 2026-10-23