端点注册表Copy Anchor Link

amagi v7 的全部设计压力都集中在一件事上：一个平台接口只写一次。

v6 的做法是同一个接口在 11–15 个文件里各写一份（参数类型、校验 schema、URL 构造、fetcher 方法、路由、返回类型、文档），任意两份之间的不一致都能独立发生。v7 把它收成一份 defineEndpoint 声明，其余一切派生。

这一页讲清派生链路的每一环：声明里有什么、谁在读它、读出来变成什么。

声明本体Copy Anchor Link

契约在 contracts/endpoint.ts：EndpointDef 是形状，defineEndpoint 是构造器（运行时是恒等函数，全部价值在类型推导），type<T>() 是只承载类型的响应令牌（运行时返回空对象）。

必填四项 —— name / route / params，以及类型上可选但 CI 强制的 doc。最朴素的一个端点长这样：

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
})

字段全貌用源码渲染，避免与实现漂移：

可选槽位与它们的真实使用量Copy Anchor Link

每个可选槽位对应一种非常规端点形态。下表的「用它的端点数」是当前仓库的实际统计 —— 它同时告诉你哪些槽位是主干、哪些是个别特例：

toCanonical 是留给后续阶段的空槽位，v7 里类型恒为 undefined。

注册表Copy Anchor Link

四个平台各一份 endpoints/index.ts，把声明组装成对象字面量，键是端点短名：

export const douyinRegistry = {
  parseWork,
  videoWork,
  imageAlbumWork,
  slidesWork,
  textWork,
  comments,
  commentReplies,
  userProfile,
  userVideoList,
  userFavoriteList,
  userRecommendList,
  search,
  suggestWords,
  shortUrl,
  musicInfo,
  musicAwemeList,
  mixAweme,
  liveRoomInfo,
  loginQrcode,
  emojiList,
  dynamicEmojiList,
  danmakuList,
  guestUserInfo,
  guestMusicInfo,
  guestMusicAwemeList,
  emojiResourceMeta
} as const satisfies Registry

Registry = Record<string, AnyEndpointDef>。平台清单是 contracts/platform.ts 的 PLATFORMS，Platform 联合类型由它推导。

当前规模 —— 抖音 26、B站 27、快手 14、小红书 13，合计 80。这个数字在多处被断言，改了端点数就得同步（见新增接口）。

派生出什么Copy Anchor Link

fetcher 是 Proxy，不是预生成对象Copy Anchor Link

createFetcherFromRegistry 返回一个 Proxy：get / ownKeys / has / getOwnPropertyDescriptor 全部按当前 registry 现算，命中后造闭包并缓存。所以方法集合自动跟随注册表，Object.keys(client.douyin.fetcher) 与 'fetchVideoWork' in ... 都同步 —— 不存在「加了端点但方法没出现」这种状态。

绑定形态的方法签名是 (options, requestConfig?)；静态形态是 v6 冻结的三参 (options, cookie?, requestConfig?)。

方法名是唯一的手写映射Copy Anchor Link

client/method-names.ts 有 80 条 '<平台>.<短名>' → v6 方法名 的映射。它存在是因为有 16 处不规则命名，拼不出来：

其余 64 条按 fetch + 短名首字母大写的规则派生，运行时与类型层都有同款兜底。快手弹幕的短名刻意取 danmakuList 而不是 danmaku，就为了让规则名拼出 fetchDanmakuList、与抖音对齐、不必登记成不规则。

OpenAPI 的派生规则Copy Anchor Link

buildOpenApiSpec() 遍历四个 registry：

• paths = `/api/${platform}${def.route}`，重复即抛
• 方法只有 get
• parameters = zod.toJSONSchema(def.params, { io: 'input' })，全部落在 query
• operationId = `${platform}_${short}`；tags = [platform]
• summary 缺失即抛
• responses 只有 200 与 401；data 不展开（v6 的 ReturnDataType 有两万多行，展开会让规范爆炸）

序列化只有一种形式：2 空格缩进 + 末尾换行。pnpm openapi:check 把已提交的 openapi.json 归一化换行后逐字节比对，不一致即非 0 退出 —— 这是 CI 的必需检查之一。同一份 buildOpenApiSpec 还被单测拿来跟产物比对，所以 pnpm test 也能抓到「忘了重新生成」。

文档站的两批生成物Copy Anchor Link

packages/docs/scripts/generate-docs.ts 在 next build / next dev / typecheck 之前跑（docs:api），先 rm 再生成：

• HTTP 80 页 —— fumadocs-openapi 的 generateFiles，输入是 openapi.json，per: 'operation' + groupBy: 'tag'。beforeWrite 钩子补中文标题、平台图标，并追加一份自拼的索引页。
• SDK 4 页 —— 遍历 registry，方法名取 methodNamesOf，参数表从 buildOpenApiSpec() 的 JSON Schema 生成（与 HTTP 侧同一个函数，所以两边的参数表不可能互相矛盾），doc.summary 进首句，doc.deprecated 变 Callout，paginate 变翻页说明，compute 变「纯本地计算」。手写散文只有一份 content/partials/sdk-prose.mdx，按区段 <include> 进来。

示例代码里的取值是唯一写死的东西（生成器里一张 SAMPLES 表），且取值与 schema 类型不符时直接抛 —— 参数改了型，示例会让构建红。

platforms/ 一层，与它底下的 legacy/ 一角Copy Anchor Link

packages/core/src/platforms/ 是唯一的平台实现目录（2026-09-14 之前这里并列着 platform/ 单数与 platforms/ 复数两个目录，读仓库极易走错；合并后 platform/ 这个名字不再存在）。它内部分成两片：

<平台>/utils.ts 是公开面，routes.ts 是唯一的路由挂载路径Copy Anchor Link

四个 createXxxRoutes(cookie, requestConfig?) 住在 platforms/<平台>/routes.ts，是唯一的路由挂载 路径（门面 startServer 只认它们），内部完全走 v7：createRoutes(platform, registry, makeClientCtx(...))。

utils.ts 是每平台的公开工具面。它把三类东西凑到一起，不复制任何实现：

• createXxxRoutes —— 同目录的 ./routes
• v7 实现（av2bv / parseDmSegMobileReply / douyinPassport）—— 直接引同平台的 v7 模块
• v6 实现（wbi_sign / qtparam / xxxSign）—— 引 ../legacy/<平台>/

v6 的 xxxApiUrls 不经 utils —— 它由 src/index.ts 从 legacy/<平台>/API.ts 显式点名导出， 这样 v7 门面上只有 v7 自己的构造器（client.<平台>.apiUrls），两份同名不同义的东西不坐在同一个对象上。

src/index.ts 不写 export * from './platforms'：那是实现层，整体 star 出去会把签名器、判定、 端点声明这些内部构件一并泄漏到公开面。改成四个 export * from './platforms/<平台>/utils' 逐个点名 —— 公开什么，看 utils.ts 一个文件就知道。

legacy 与 v7 是两份代码，不是一份的两个入口Copy Anchor Link

包顶层导出的 douyinApiUrls 这类 v6 构造器（legacy/<平台>/API.ts），与 SDK 内部实际发请求用的 URL 构造器（<平台>/api.ts，挂上门面的是 client.<平台>.apiUrls）是两份代码，两边行数不同。 要改 URL 行为时必须确认自己改的是哪一份。

签名同理：legacy/douyin/sign、legacy/kuaishou/sign、legacy/xiaohongshu/sign 与 v7 的同名模块是 分叉的两份。只有算法叶子（a_bogus / x_bogus / he / hudr / primitives / bv2av / danmaku / config）在合并时去重成了一份 —— 它们当时逐字节相同，v6 侧改为直接引 v7，少了 8 个副本。

分叉的那几个要留神：test/platforms/<平台>/sign.test.ts 一类用例拿 v6 那份当 oracle，对同一入参 断言 v7 输出与 v6 完全相等。这层对照依赖两份代码同时存在，动任何一侧前先读那些用例。

doc 字段为什么被测试而不是类型强制Copy Anchor Link

doc 在 EndpointDef 上是可选的，这样已有端点一个不改也能编译。真正的强制在 test/contracts/endpoint-doc.test.ts：拿四个注册表逐个断言 doc.summary 非空、≤40 字、不以句号结尾、同平台内不重复。

这是这个仓库反复使用的一种手法 —— 能用类型表达的用类型，不能的用测试钉住，两者都不做的约定等于不存在。

最后更新于 2026-10-23