# LLMs.txt (https://ikenxuan.github.io/amagi/docs/v6/ai/llms-txt)

> 让 AI 助手理解 Amagi 文档



> 让 Claude、Cursor、Windsurf 等 AI 助手能够理解和使用 Amagi 文档

我们提供 [LLMs.txt](https://llmstxt.org/) 文件，让 AI 编码助手能够访问 Amagi 文档。

## 可用文件 [#可用文件]

**核心文档：**

* [/llms.txt](/llms.txt) — 快速参考索引
* [/llms-full.txt](/llms-full.txt) — 完整的 Amagi 文档

## 集成方式 [#集成方式]

### Cursor [#cursor]

使用 `@Docs` 功能：

```
@Docs https://ikenxuan.github.io/amagi/llms-full.txt
```

或在聊天中直接引用：

```
使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

[了解更多](https://docs.cursor.com/context/@-symbols/@-docs)

### Cline (VS Code) [#cline-vs-code]

在提示中直接引用：

```
参考 Amagi 文档：https://ikenxuan.github.io/amagi/llms-full.txt
```

[了解更多](https://cline.bot)

### Continue (VS Code) [#continue-vs-code]

在 Continue 配置中添加自定义文档：

1. 打开配置：`Ctrl+Shift+P` → "Continue: Add new custom docs"
2. 添加 URL：`https://ikenxuan.github.io/amagi/llms.txt`
3. 在聊天中使用 `@docs` 并选择 amagi

或直接在提示中引用文档 URL。

[了解更多](https://continue.dev/docs)

### Claude Code [#claude-code]

告诉 Claude 引用文档：

```
使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

或添加到项目的 `.claude` 文件以自动加载。

### Windsurf [#windsurf]

添加到 `.windsurfrules` 文件：

```
#docs https://ikenxuan.github.io/amagi/llms-full.txt
```

[了解更多](https://docs.codeium.com/windsurf/memories#memories-and-rules)

### JetBrains AI Assistant [#jetbrains-ai-assistant]

JetBrains IDE（IntelliJ IDEA、PyCharm、WebStorm 等）可以通过 AI Assistant 使用文档：

1. 在 AI Assistant 聊天中直接引用：

   ```
   参考文档：https://ikenxuan.github.io/amagi/llms-full.txt
   ```

[了解更多](https://www.jetbrains.com/help/ai-assistant/)

### GitHub Copilot (VS Code) [#github-copilot-vs-code]

在 Copilot Chat 中引用文档：

```
@workspace 使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

### 其他 AI 工具 [#其他-ai-工具]

大多数 AI 助手都可以通过 URL 引用文档。只需提供：

```
https://ikenxuan.github.io/amagi/llms.txt
```

<Callout type="info">
  对于完整文档内容，使用 

  `/llms-full.txt`
</Callout>

## 使用示例 [#使用示例]

配置完成后，你可以向 AI 助手提问：

* "如何使用 Amagi SDK 获取 Bilibili 视频信息？"
* "Amagi 支持哪些平台的 API？"
* "如何配置 HTTP Server 模式？"
* "事件系统如何使用？"
* "如何处理 Douyin 的评论数据？"

AI 助手会基于 LLMs.txt 文件中的文档内容给出准确的回答。

## 获取单个页面的 Markdown [#获取单个页面的-markdown]

你可以通过在任何文档页面 URL 后添加 `.mdx` 来获取该页面的 Markdown 内容：

```
https://ikenxuan.github.io/amagi/docs/v6/usage/getting-started.mdx
https://ikenxuan.github.io/amagi/docs/v6/usage/guide/sdk.mdx
https://ikenxuan.github.io/amagi/docs/v6/usage/api/bilibili.mdx
```

这对于需要特定页面内容的 AI 工具特别有用。

## 内容协商 [#内容协商]

某些 AI 工具会发送 `Accept: text/markdown` 请求头。我们的文档站点会自动识别并返回 Markdown 格式的内容，而不是 HTML 页面。

## 贡献 [#贡献]

发现 AI 生成的代码有问题？帮助我们改进 LLMs.txt 文件，请访问 [GitHub](https://github.com/ikenxuan/amagi)。

## 相关链接 [#相关链接]

* [LLMs.txt 规范](https://llmstxt.org/)
* [GitHub 仓库](https://github.com/ikenxuan/amagi)


# v6.1.3 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.1.3)

> 2025-05-10 发布的重要变更



# v6.1.3 变更日志 [#v613-变更日志]

## B站 [#b站]

### `fetchDynamicCard` 接口停用 [#fetchdynamiccard-接口停用]

**影响接口**: `fetchDynamicCard` / `dynamicCard`

B站官方已删除 `dynamic_svr/v1/dynamic_svr/get_dynamic_detail` 接口（原获取动态卡片信息接口）。

自 v6.1.3 起，调用 `fetchDynamicCard` 将直接返回错误信息，不再转调其他接口做兼容：

```typescript
{
  code: -404,
  message: '接口已停用：B站官方已删除 dynamic_svr 接口，请使用 dynamicDetail 替代',
  ttl: 1,
  data: null
}
```

**迁移方式**: 使用 `fetchDynamicDetail` 替代。

```typescript
// 之前
const result = await fetchDynamicCard({ dynamic_id: '123456789' }, cookie)

// 之后
const result = await fetchDynamicDetail({ dynamic_id: '123456789' }, cookie)
```

该接口计划于 **v7.0.0** 从代码中彻底移除。


# v6.2.0 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.2.0)

> 2025-06-30 发布的重要变更



# v6.2.0 变更日志 [#v620-变更日志]

## 小红书 [#小红书]

### 新增游客 Cookie 生成能力 [#新增游客-cookie-生成能力]

新增小红书 Web 端游客 Cookie 生成工具接口，可在未持有用户 Cookie 的场景下，按照 Web 端首次访问的初始化流程（生成 a1/webId，依次完成 scripting、webprofile、activate 三个会话请求）生成一份包含 `web_session` 的游客 Cookie。

```typescript
import { xiaohongshuSign } from '@ikenxuan/amagi'

// 生成游客 Cookie
const guestCookie = await xiaohongshuSign.createGuestCookie()

// 可透传传输参数（代理、超时等）
const guestCookie = await xiaohongshuSign.createGuestCookie({
  proxy: { host: '127.0.0.1', port: 7890 },
  timeout: 10000
})
```

<Callout type="warn">
  游客 Cookie 仅提供工具能力，**不保证所有接口都能使用该游客 Cookie 请求成功**。部分接口对登录态有强校验，使用游客 Cookie 仍可能返回受限或失败的结果，请按需自行验证。
</Callout>


# v6.3.0 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.3.0)

> 2026-07-30 发布的重要变更



# v6.3.0 变更日志 [#v630-变更日志]

## B站 [#b站]

### 新增按用户 UID 查询直播状态接口 [#新增按用户-uid-查询直播状态接口]

新增 `fetchUserLiveStatus`，可直接通过用户 UID 查询直播间是否开通、当前是否正在直播以及直播间 ID 等基础状态。

该接口不依赖用户空间动态中的直播推荐卡片，适合开播提醒、定时轮询等需要尽快感知直播状态的场景。

```typescript
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: '',
    douyin: '',
    kuaishou: '',
    xiaohongshu: ''
  }
})

const result = await client.bilibili.fetcher.fetchUserLiveStatus({
  host_mid: 2,
  typeMode: 'strict'
})

if (result.success && result.data.data.liveStatus === 1) {
  console.log(`正在直播，直播间 ID：${result.data.data.roomid}`)
}
```

#### 参数 [#参数]

| 参数         | 类型                    | 必填 | 说明                    |
| ---------- | --------------------- | -- | --------------------- |
| `host_mid` | `number`              | 是  | B站用户 UID              |
| `typeMode` | `'strict' \| 'loose'` | 否  | 返回类型模式，默认值为 `'loose'` |

#### 主要返回字段 [#主要返回字段]

| 字段           | 说明                       |
| ------------ | ------------------------ |
| `roomStatus` | `1` 表示用户已开通直播间，`0` 表示未开通 |
| `liveStatus` | `1` 表示正在直播，`0` 表示当前未开播   |
| `roomid`     | 直播间 ID；未开通直播间时为 `0`      |
| `title`      | 直播间标题                    |
| `cover`      | 直播封面                     |
| `url`        | 直播间地址                    |

如需直播分区、开播时间等完整直播间信息，可将 `roomid` 传给现有的 `fetchLiveRoomInfo`：

```typescript
const liveStatus = await client.bilibili.fetcher.fetchUserLiveStatus({
  host_mid: 2,
  typeMode: 'strict'
})

if (liveStatus.success && liveStatus.data.data.liveStatus === 1) {
  const liveRoom = await client.bilibili.fetcher.fetchLiveRoomInfo({
    room_id: String(liveStatus.data.data.roomid),
    typeMode: 'strict'
  })
}
```

### HTTP 接口 [#http-接口]

HTTP 服务同步提供以下路由：

```http
GET /api/bilibili/fetch_user_live_status?host_mid=2
```

响应字段与 Fetcher 返回的B站原始响应类型一致。


# v6.4.0 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.4.0)

> 2026-07-30 发布的重要变更



# v6.4.0 变更日志 [#v640-变更日志]

## Fetcher [#fetcher]

### 四个平台统一支持单次请求配置覆盖 [#四个平台统一支持单次请求配置覆盖]

通过 Amagi Client 或 `createBound*Fetcher` 创建的 B站、抖音、快手和小红书绑定 Fetcher，现在都会读取方法的第二个 `requestConfig` 参数，并将它与实例级请求配置合并。

单次配置拥有更高优先级，请求头会单独合并，因此可以只覆盖当前请求的 Cookie，同时保留实例配置的代理、超时和 User-Agent：

```typescript
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'SESSDATA=example',
    douyin: '',
    kuaishou: '',
    xiaohongshu: ''
  },
  request: {
    timeout: 10_000
  }
})

const result = await client.bilibili.fetcher.fetchComments(
  {
    oid: '170001',
    type: 1,
    number: 20,
    typeMode: 'strict'
  },
  {
    headers: {
      Cookie: ''
    }
  }
)
```

该覆盖只影响当前调用，不会修改 Client 或绑定 Fetcher 保存的配置，也不会影响同一实例上的后续请求。显式提供大写 `headers.Cookie` 时，该值还会同步成为底层 Fetcher 当前调用的 cookie 参数，确保平台签名、前置请求和最终请求处于同一身份状态。

直接导出的裸 Fetcher 也支持单次请求配置，调用签名为 `fetcher.method(options, cookie?, requestConfig?)`：

```typescript
import { bilibiliFetcher } from '@ikenxuan/amagi'

const result = await bilibiliFetcher.fetchComments(
  {
    oid: '170001',
    type: 1
  },
  '',
  {
    headers: {
      Cookie: ''
    }
  }
)
```

裸 Fetcher 会在类型层关联参数二与参数三的 `headers.Cookie`：只要显式传入 `Cookie` 请求头，参数二就必须是相同的字符串字面量。因此匿名请求必须同时传入空字符串，不能保留登录 Cookie。请求头字段严格使用大写 `Cookie`，小写 `cookie` 会导致类型检查失败。

该调用形式同样适用于 `douyinFetcher`、`kuaishouFetcher`、`xiaohongshuFetcher` 以及默认导出上的同名静态属性。

## B站 [#b站]

### 匿名获取评论 [#匿名获取评论]

B站登录态会影响评论区热度池，不同账号可能得到不同的评论排序。需要稳定获取匿名评论结果时，可以通过上述单次请求配置清空 Cookie，无需创建第二个 Amagi Client。

评论请求仍由原 Client 实例发起，因此会继续经过同一套事件、日志和错误处理链路。


# v6.5.0 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.5.0)

> 2026-08-04 发布的重要变更



# v6.5.0 变更日志 [#v650-变更日志]

## 破坏性变更 [#破坏性变更]

### 移除全部已废弃的 API [#移除全部已废弃的-api]

v6.0 发布时标记为废弃（调用会抛出 `DeprecatedApiError`）的兼容 API，以及后续版本标记废弃的接口，自本版本起全部彻底移除，不再提供导入与类型导出。

**`getXxxData` 系列**

`getDouyinData`、`getBilibiliData`、`getKuaishouData`、`getXiaohongshuData` 已从包导出、Amagi Client 实例和默认导出的静态属性中移除。请改用对应平台的 Fetcher：

```typescript
import { bilibiliFetcher } from '@ikenxuan/amagi'

const result = await bilibiliFetcher.fetchVideoInfo({ bvid: 'BV123' }, cookie)
```

**平台旧版 `api` 命名空间**

`douyin` / `bilibili` / `kuaishou` / `xiaohongshu` 四个旧版 API 存根对象及其绑定工厂（`createBoundDouyinApi` 等）已移除，Amagi Client 实例上的 `client.平台.api` 属性同步移除。请统一使用 `client.平台.fetcher`。

**日志兼容模块**

`logger`、`httpLogger`、`initLogger`、`logMiddleware` 已移除。v6 已改用事件驱动架构，请通过事件系统实现日志：

```typescript
import { amagiEvents } from '@ikenxuan/amagi'

amagiEvents.on('log:info', (data) => console.log(data.message))
amagiEvents.on('http:response', (data) => console.log(data.statusCode, data.url))
```

**其他移除项**

* `amagiClient` 别名：请使用 `createAmagiClient` 或默认导出
* `fetchDynamicCard` 及配套内容：B站官方已删除 `dynamic_svr` 接口，本次移除 Fetcher 方法、HTTP 路由 `GET /fetch_dynamic_card`、`bilibiliApiUrls.getDynamicCard`、返回类型 `BiliDynamicCard` 及相关的参数校验与方法名映射
* `ApiResponse<T>` 类型别名：请使用 `Result<T>`
* 内部废弃管理模块（`utils/deprecation`）随上述 API 一并移除

完整的迁移方式请参考 [v6 迁移指南](/docs/v6/usage/migration-v6)。

## 文档 [#文档]

### 文档站更新至 v6 正式版 [#文档站更新至-v6-正式版]

移除了文档中残留的 v6 Alpha / 测试版标识与 `@beta` 安装提示，安装、快速开始与迁移指南均以 v6 正式版为准。


# v6.6.0 (https://ikenxuan.github.io/amagi/docs/v6/changelog/6.6.0)

> 2026-09-01 发布的实验性抖音 Passport 扫码登录功能



# v6.6.0 变更日志 [#v660-变更日志]

<Callout type="warn">
  抖音 Passport 扫码登录是 **实验性功能**，不保证稳定性。它依赖抖音 Web 端的内部登录接口、签名参数和风控策略，服务端行为变化可能随时导致功能失效。后续版本可能调整、重命名或移除相关方法、参数、返回值和底层实现，请不要在对稳定性有要求的生产登录链路中依赖当前 API。
</Callout>

## 新增：抖音 Passport 扫码登录 [#新增抖音-passport-扫码登录]

本版本新增一套基于 `login.douyin.com` Passport 体系的抖音扫码登录流程，支持：

* 获取 Passport 登录二维码；
* 轮询二维码状态；
* 处理扫码确认后的 SSO 跳转；
* 处理部分账号触发的短信二次验证；
* 提交短信验证码并获取登录 Cookie；
* 在调用之间传递会话 Cookie 和 `bd-ticket-guard` 设备票据状态。

这套流程与原有的 `requestLoginQrcode` 不同。后者是旧的登录二维码接口；Passport 登录提供的是一套从取码到获取登录态的完整流程。

## 重要限制：目前独立于 Amagi Client 架构 [#重要限制目前独立于-amagi-client-架构]

Passport 登录当前是独立接入的实验性模块，**尚未完整纳入 Amagi Client 的实例级架构**。它与现有通过 `client.douyin.fetcher` 使用的稳定数据接口不是同一套内部实现：

* 当前推荐使用导出的 Passport 方法或 `douyinFetcher`；
* 不支持通过 `client.douyin.fetcher` 的实例 Cookie 状态自动维护登录会话；
* 不支持通过 `createBoundDouyinFetcher` 绑定并自动维护这套登录流程；
* 登录过程中的会话状态必须由调用方保存每次返回的 `cookie`，并在下一次调用时传回；
* 轮询循环也需要由调用方自行维护。

后续可能会将这套能力重构并接入统一的客户端、Fetcher 或会话管理架构。&#x2A;*因此当前方法的调用方式和类型不能视为长期兼容的稳定 API。**

## 当前 API [#当前-api]

可以从包根路径导入以下方法：

```ts
import {
  checkPassportQrcode,
  requestPassportQrcode,
  sendPassportVerifyCode,
  validatePassportVerifyCode
} from '@ikenxuan/amagi'
```

也可以通过 `douyinFetcher` 使用这些方法：

```ts
import { douyinFetcher } from '@ikenxuan/amagi'

const qrcode = await douyinFetcher.requestPassportQrcode()
```

### 获取二维码 [#获取二维码]

```ts
const result = await requestPassportQrcode()

if (!result.success) {
  throw new Error(result.message)
}

console.log(result.data.content)
console.log(result.data.expires_in)

// 必须保存，用于后续轮询；其中可能包含 Passport 会话状态和实验性模块的内部状态
const cookie = result.data.cookie
const token = result.data.token
```

返回数据包括：

| 字段            | 说明                     |
| ------------- | ---------------------- |
| `token`       | 轮询二维码状态时使用的令牌          |
| `content`     | 二维码内容，可交给二维码生成器渲染      |
| `expire_time` | 服务端返回的绝对 Unix 时间戳，单位为秒 |
| `expires_in`  | 获取二维码时计算出的剩余秒数，是一个时间快照 |
| `cookie`      | 后续调用必须继续传递的会话 Cookie   |

### 轮询二维码状态 [#轮询二维码状态]

```ts
const status = await checkPassportQrcode({ token }, cookie)

if (!status.success) {
  throw new Error(status.message)
}

switch (status.data.status) {
  case 'new':
  case 'scanned':
  case 'busy':
    // 根据 status.data.interval 等待后继续轮询
    cookie = status.data.cookie
    break
  case 'verify':
    // 使用 status.data.verify 进入短信二次验证流程
    cookie = status.data.cookie
    break
  case 'confirmed':
    cookie = status.data.cookie
    console.log('登录完成:', status.data.logged_in)
    break
  case 'expired':
  case 'risk':
  case 'unknown':
    console.log(status.data.message)
    break
}
```

每次调用后都应使用响应中最新的 `cookie`。二维码状态可能包括：

* `new`：尚未扫码；
* `scanned`：已扫码，等待手机端确认；
* `confirmed`：已确认并尝试完成登录；
* `verify`：需要进行二次验证；
* `expired`：二维码已过期；
* `busy`：轮询过于频繁，按 `interval` 退避后重试；
* `risk`：触发风控；
* `unknown`：服务端返回了暂未适配的状态。

### 短信二次验证 [#短信二次验证]

当轮询结果为 `verify` 时，可以把返回的验证上下文传给发码接口：

```ts
const sendCode = await sendPassportVerifyCode(
  {
    verify: status.data.verify
  },
  status.data.cookie
)

if (!sendCode.success || !sendCode.data.ok) {
  throw new Error(sendCode.success ? sendCode.data.message : sendCode.message)
}

const validateCode = await validatePassportVerifyCode(
  {
    verify: status.data.verify,
    code: '123456',
    biz_trace_id: sendCode.data.biz_trace_id,
    verify_way: sendCode.data.verify_way
  },
  sendCode.data.cookie
)

if (!validateCode.success || !validateCode.data.ok) {
  throw new Error(validateCode.success ? validateCode.data.message : validateCode.message)
}

cookie = validateCode.data.cookie
```

`verify_way` 应优先使用服务端返回的实际值。不同账号可能返回不同的验证方式，例如 `mobile_sms_verify` 或 `assist_mobile_sms_verify`。`biz_trace_id` 也应在发送验证码和提交验证码时保持一致。

## 兼容性与稳定性说明 [#兼容性与稳定性说明]

当前实现包含 Passport 专用的签名、`a_bogus`、环境指纹、Cookie 管理和 `bd-ticket-guard` 票据处理逻辑。这些内容不属于 Amagi 面向稳定数据接口的公共抽象，抖音也没有为这些 Web 内部接口提供稳定的第三方 API 契约。

使用时请注意：

* 抖音可能修改接口地址、请求字段、签名算法、Cookie 语义或风控规则；
* 同一账号、设备、网络环境下的可用验证方式可能不同；
* 获取二维码成功不代表后续轮询或登录一定成功；
* `confirmed`、`ok` 和 `logged_in` 等字段应结合实际返回结果判断，不应只根据 HTTP 或外层 `code` 判断；
* 请妥善保管返回的登录 Cookie，不要写入日志、提交到代码仓库或暴露给不可信的第三方；
* 发生异常时可以启用 debug 日志辅助排查，但仍应避免记录完整 Cookie 或验证码。

如果需要稳定的抖音数据访问能力，请继续使用现有的抖音 Fetcher API。Passport 登录仅建议用于实验、开发验证和能够接受接口变化的场景。


# 变更日志 (https://ikenxuan.github.io/amagi/docs/v6/changelog)

> amagi v6 各版本的行为变化



v6 系列的版本更新记录。每个版本的破坏性变更、新接口与缺陷修复
逐版列出：

* [v6.6.0](/docs/v6/changelog/6.6.0)
* [v6.5.0](/docs/v6/changelog/6.5.0)
* [v6.4.0](/docs/v6/changelog/6.4.0)
* [v6.3.0](/docs/v6/changelog/6.3.0)
* [v6.2.0](/docs/v6/changelog/6.2.0)
* [v6.1.3](/docs/v6/changelog/6.1.3)


# 新增接口 (https://ikenxuan.github.io/amagi/docs/v6/dev/add-api)

> 学习如何为平台新增数据接口



# 新增接口 [#新增接口]

本文档以 B站为例，演示如何新增一个平台接口。

## 需要修改的文件 [#需要修改的文件]

新增一个接口需要修改以下文件：

| 序号 | 文件                                       | 作用                 |
| -- | ---------------------------------------- | ------------------ |
| 1  | `types/BilibiliAPIParams.ts`             | 定义参数类型             |
| 2  | `validation/bilibili.ts`                 | 参数验证 Schema + 路由映射 |
| 3  | `platform/bilibili/API.ts`               | URL 拼接             |
| 4  | `platform/bilibili/getdata.ts`           | 数据获取逻辑             |
| 5  | `types/ReturnDataType/Bilibili/index.ts` | 返回类型（可选）           |
| 6  | `model/fetchers/bilibili/types.ts`       | Fetcher 类型         |
| 7  | `model/fetchers/bilibili/*.ts`           | Fetcher 实现         |
| 8  | `model/fetchers/bilibili/index.ts`       | 导出                 |

## 完整示例：新增「获取视频标签」接口 [#完整示例新增获取视频标签接口]

<Accordions>
  <Accordion title="第 1 步：定义参数类型">
    `types/BilibiliAPIParams.ts`:

    在 `BilibiliMethodOptionsMap` 接口中添加新的参数类型：

    ```ts
    /** B站 API 方法参数映射接口 */
    export interface BilibiliMethodOptionsMap {
      /** 获取单个视频信息 */
      VideoInfoParams: {
        methodType: 'videoInfo'
        /** 稿件BVID */
        bvid: string
      }

      // 新增：获取视频标签
      /** 获取视频标签 */
      VideoTagsParams: {
        methodType: 'videoTags'
        /** 稿件 AVID */
        avid: number
      }
    }

    /** B站方法类型到参数的映射 */
    export type BilibiliMethodOptMap = {
      videoInfo: BilibiliMethodOptionsMap['VideoInfoParams']
      videoTags: BilibiliMethodOptionsMap['VideoTagsParams'] // 新增
    }
    ```
  </Accordion>

  <Accordion title="第 2 步：定义参数验证">
    `validation/bilibili.ts`:

    ```ts
    import { z } from 'zod'

    // 定义参数类型（与 types 中保持一致）
    interface VideoTagsParams {
      methodType: 'videoTags'
      avid: number
    }

    // 新增 Schema
    export const BilibiliVideoTagsParamsSchema: z.ZodType<VideoTagsParams> = z.object({
      methodType: z.literal('videoTags'),
      avid: z.coerce.number().int().positive()
    })

    // 在 BilibiliValidationSchemas 中注册
    export const BilibiliValidationSchemas = {
      videoTags: BilibiliVideoTagsParamsSchema
    } as const

    // 在 BilibiliMethodRoutes 中添加路由
    export const BilibiliMethodRoutes = {
      videoTags: '/fetch_video_tags'
    } as const
    ```
  </Accordion>

  <Accordion title="第 3 步：实现 URL 拼接">
    `platform/bilibili/API.ts`:

    ```ts
    class BilibiliAPI {
      /** 获取视频标签 */
      getVideoTags(data: { avid: number }): string {
        return `https://api.bilibili.com/x/tag/archive/tags?aid=${data.avid}`
      }
    }

    // 使用示例
    const api = new BilibiliAPI()
    const url = api.getVideoTags({ avid: 170001 })
    ```
  </Accordion>

  <Accordion title="第 4 步：实现数据获取">
    `platform/bilibili/getdata.ts`:

    ```ts
    // 模拟类型定义
    interface RequestConfig {
      url: string
      method?: string
      headers?: Record<string, string>
    }

    interface BilibiliAPI {
      getVideoTags(data: { avid: number }): string
    }

    declare const bilibiliApiUrls: BilibiliAPI
    declare const baseRequestConfig: RequestConfig
    declare function GlobalGetData(methodType: string, config: RequestConfig): Promise<any>

    // 在 switch 语句中添加 case
    async function handleMethod(data: { methodType: string; avid?: number }) {
      switch (data.methodType) {
        case 'videoTags': {
          const result = await GlobalGetData(data.methodType, {
            ...baseRequestConfig,
            url: bilibiliApiUrls.getVideoTags({ avid: data.avid! })
          })
          return result
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="第 5 步：定义 Fetcher 类型">
    `model/fetchers/bilibili/types.ts`:

    ```ts
    // 基础类型定义
    type TypeMode = 'strict' | 'loose'

    type Result<T> =
      | { success: true; code: number; message: string; data: T }
      | { success: false; code: number; message: string; error: unknown }

    interface BaseRequestOptions {
      typeMode?: TypeMode
    }

    /** B站视频标签请求参数 */
    export interface BilibiliVideoTagsOptions extends BaseRequestOptions {
      /** 视频 AV 号 */
      avid: number
    }

    /** B站 Fetcher 接口 */
    export interface IBilibiliFetcher {
      /** 获取视频标签 */
      fetchVideoTags: <M extends TypeMode = 'loose'>(
        options: BilibiliVideoTagsOptions,
        cookie?: string
      ) => Promise<Result<M extends 'strict' ? VideoTagsResponse : any>>
    }

    /** 视频标签响应类型 */
    interface VideoTagsResponse {
      tags: Array<{
        tag_id: number
        tag_name: string
      }>
    }
    ```
  </Accordion>

  <Accordion title="第 6 步：实现 Fetcher 方法">
    `model/fetchers/bilibili/video.ts`:

    ```ts
    // 类型定义
    interface BilibiliVideoTagsOptions {
      avid: number
      typeMode?: 'strict' | 'loose'
    }

    type Result<T> =
      | { success: true; code: number; message: string; data: T }
      | { success: false; code: number; message: string; error: unknown }

    declare function fetchBilibiliInternal(methodType: string, params: Record<string, any>, options: { cookie?: string }): Promise<Result<any>>

    /**
     * 获取视频标签
     * @param options - 请求参数
     * @param cookie - B站 Cookie
     */
    export async function fetchVideoTags(options: BilibiliVideoTagsOptions, cookie?: string): Promise<Result<any>> {
      return fetchBilibiliInternal('videoTags', { avid: options.avid }, { cookie })
    }
    ```
  </Accordion>

  <Accordion title="第 7 步：导出">
    `model/fetchers/bilibili/index.ts`:

    ```ts
    // 模拟实现
    const fetchVideoTags = async (options: { avid: number }, cookie?: string) => ({
      success: true as const,
      code: 200,
      message: 'ok',
      data: { tags: [] }
    })

    // 导出函数
    export { fetchVideoTags }

    // 导出 fetcher 对象
    export const bilibiliFetcher = {
      fetchVideoTags
    }

    // 类型检查
    const result = bilibiliFetcher.fetchVideoTags({ avid: 170001 })
    ```
  </Accordion>
</Accordions>

## 特殊情况处理 [#特殊情况处理]

<Accordions>
  <Accordion title="需要 WBI 签名的接口（B站）">
    B站部分接口需要 WBI 签名：

    ```ts
    // 类型定义
    interface RequestConfig {
      url: string
      method?: string
    }

    interface BilibiliAPI {
      yourMethod(data: { param: string }): string
    }

    declare const bilibiliApiUrls: BilibiliAPI
    declare const baseRequestConfig: RequestConfig
    declare function GlobalGetData(methodType: string, config: RequestConfig): Promise<any>
    declare function wbi_sign(url: string, cookie: string): Promise<string>

    async function handleWbiMethod(data: { methodType: string; param: string }, cookie: string) {
      const baseUrl = bilibiliApiUrls.yourMethod({ param: data.param })
      // 生成 WBI 签名查询参数
      const wbiSignQuery = await wbi_sign(baseUrl, cookie)

      const result = await GlobalGetData(data.methodType, {
        ...baseRequestConfig,
        url: baseUrl + wbiSignQuery
      })
      return result
    }
    ```
  </Accordion>

  <Accordion title="POST 请求">
    `API.ts` 返回 URL 和 Body：

    ```ts
    class BilibiliAPI {
      yourPostMethod(data: { param1: string }) {
        return {
          Url: 'https://api.bilibili.com/xxx',
          Body: { param1: data.param1 }
        }
      }
    }

    const api = new BilibiliAPI()
    const { Url, Body } = api.yourPostMethod({ param1: 'test' })
    ```

    `getdata.ts` 使用 POST：

    ```ts
    // 类型定义
    interface RequestConfig {
      url: string
      method?: string
      data?: Record<string, any>
    }

    interface BilibiliAPI {
      yourPostMethod(data: { param1: string }): { Url: string; Body: Record<string, any> }
    }

    declare const bilibiliApiUrls: BilibiliAPI
    declare const baseRequestConfig: RequestConfig
    declare function GlobalGetData(methodType: string, config: RequestConfig): Promise<any>

    async function handlePostMethod(data: { methodType: string; param1: string }) {
      const { Url, Body } = bilibiliApiUrls.yourPostMethod({ param1: data.param1 })

      const result = await GlobalGetData(data.methodType, {
        ...baseRequestConfig,
        method: 'POST',
        url: Url,
        data: Body
      })
      return result
    }
    ```
  </Accordion>

  <Accordion title="特殊响应格式（Protobuf）">
    B站弹幕接口返回 Protobuf 格式：

    ```ts
    // 类型定义
    interface RequestConfig {
      url: string
      responseType?: 'arraybuffer' | 'json'
    }

    interface DanmakuItem {
      id: number
      content: string
      time: number
    }

    declare const baseRequestConfig: RequestConfig
    declare function fetchData(config: RequestConfig): Promise<ArrayBuffer>
    declare function parseDmSegMobileReply(buffer: ArrayBuffer): DanmakuItem[]
    declare function createSuccessResponse<T>(data: T): { success: true; data: T }

    async function handleDanmaku(url: string) {
      const response = await fetchData({
        ...baseRequestConfig,
        url,
        responseType: 'arraybuffer'
      })

      // 解析 protobuf
      const parsed = parseDmSegMobileReply(response)

      return createSuccessResponse(parsed)
    }
    ```
  </Accordion>

  <Accordion title="抖音签名">
    抖音接口需要 `a_bogus` 签名：

    ```ts
    // 类型定义
    interface RequestConfig {
      url: string
    }

    interface DouyinSign {
      AB(url: string, userAgent: string): string
    }

    declare const douyinSign: DouyinSign
    declare const baseRequestConfig: RequestConfig
    declare function GlobalGetData(methodType: string, config: RequestConfig): Promise<any>

    async function handleDouyinMethod(baseUrl: string, userAgent: string, methodType: string) {
      // 生成 a_bogus 签名
      const aBogus = douyinSign.AB(baseUrl, userAgent)
      const signedUrl = `${baseUrl}&a_bogus=${aBogus}`

      const result = await GlobalGetData(methodType, {
        ...baseRequestConfig,
        url: signedUrl
      })
      return result
    }
    ```
  </Accordion>

  <Accordion title="小红书签名">
    小红书接口需要 `X-S` 签名：

    ```ts
    // 类型定义
    interface RequestConfig {
      url: string
      headers?: Record<string, string>
    }

    interface XiaohongshuSign {
      generateXSGet(path: string, a1Cookie: string): string
      generateXT(): string
    }

    declare const xiaohongshuSign: XiaohongshuSign
    declare const baseRequestConfig: RequestConfig
    declare function GlobalGetData(methodType: string, config: RequestConfig): Promise<any>

    async function handleXiaohongshuMethod(path: string, a1Cookie: string, methodType: string) {
      const xs = xiaohongshuSign.generateXSGet(path, a1Cookie)
      const xt = xiaohongshuSign.generateXT()

      const result = await GlobalGetData(methodType, {
        ...baseRequestConfig,
        url: `https://edith.xiaohongshu.com${path}`,
        headers: {
          'X-S': xs,
          'X-T': xt
        }
      })
      return result
    }
    ```
  </Accordion>
</Accordions>

## 验证修改 [#验证修改]

在提交前，请确保：

```bash
# 1. 类型检查通过
pnpm typecheck

# 2. 构建成功
pnpm build

# 3. 功能测试
pnpm dev
# 然后手动测试新增的接口
```


# 项目架构 (https://ikenxuan.github.io/amagi/docs/v6/dev/architecture)

> 了解 amagi 的项目结构和核心概念



# 项目架构 [#项目架构]

## 目录结构 [#目录结构]

```
amagi/
├── packages/
│   ├── core/                    # @ikenxuan/amagi 核心包
│   │   └── src/
│   │       ├── model/
│   │       │   └── fetchers/    # Fetcher API 实现
│   │       │       ├── bilibili/
│   │       │       ├── douyin/
│   │       │       ├── kuaishou/
│   │       │       └── xiaohongshu/
│   │       ├── platform/        # 平台实现
│   │       │   ├── bilibili/
│   │       │   │   ├── API.ts       # URL 拼接
│   │       │   │   ├── getdata.ts   # 数据获取
│   │       │   │   ├── routes.ts    # HTTP 路由
│   │       │   │   └── sign/        # 签名算法
│   │       │   ├── douyin/
│   │       │   ├── kuaishou/
│   │       │   └── xiaohongshu/
│   │       ├── types/           # 类型定义
│   │       ├── validation/      # 参数验证 (Zod)
│   │       ├── server/          # HTTP 服务
│   │       └── index.ts         # 主入口
│   └── docs/                    # 文档站点 (Fumadocs)
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json
```

## 数据流 [#数据流]

```
用户调用 Fetcher
       ↓
  参数验证 (Zod)
       ↓
  getdata.ts 处理
       ↓
  API.ts 拼接 URL
       ↓
  签名处理 (如需要)
       ↓
  发起 HTTP 请求
       ↓
  统一格式返回
```

## 核心模块 [#核心模块]

### Fetcher (`model/fetchers/`) [#fetcher-modelfetchers]

对外暴露的 API 层，负责：

* 定义方法签名和类型
* 处理 `typeMode` 参数
* 调用内部实现

```ts
// 类型定义
type TypeMode = 'strict' | 'loose'
type Result<T> = { success: true; data: T } | { success: false; error: unknown }

interface BilibiliVideoInfoOptions {
  bvid: string
  typeMode?: TypeMode
}

declare function fetchBilibiliInternal(methodType: string, params: Record<string, any>, options: { cookie?: string }): Promise<Result<any>>

// model/fetchers/bilibili/video.ts
export async function fetchVideoInfo(options: BilibiliVideoInfoOptions, cookie?: string): Promise<Result<any>> {
  return fetchBilibiliInternal('videoInfo', { bvid: options.bvid }, { cookie })
}
```

### Platform (`platform/`) [#platform-platform]

各平台的具体实现：

| 文件           | 职责             |
| ------------ | -------------- |
| `API.ts`     | URL 拼接，不发请求    |
| `getdata.ts` | 实际发起请求，处理签名、响应 |
| `routes.ts`  | HTTP 路由注册      |
| `sign/`      | 签名算法实现         |

### Validation (`validation/`) [#validation-validation]

基于 Zod 的参数验证：

```ts
import { z } from 'zod'

// 定义参数类型
interface VideoInfoParams {
  methodType: 'videoInfo'
  bvid: string
}

// 创建验证 Schema
export const VideoInfoParamsSchema: z.ZodType<VideoInfoParams> = z.object({
  methodType: z.literal('videoInfo'),
  bvid: z.string().startsWith('BV')
})

// 验证示例
const result = VideoInfoParamsSchema.safeParse({
  methodType: 'videoInfo',
  bvid: 'BV1xx411c7mD'
})
```

### Types (`types/`) [#types-types]

TypeScript 类型定义：

* `*APIParams.ts` - 各平台的参数类型
* `ReturnDataType/` - 响应数据类型

## 统一响应格式 [#统一响应格式]

所有 API 返回 `Result<T>` 类型：

```ts
type SuccessResult<T> = {
  success: true
  code: number
  message: string
  data: T
}

type ErrorResult = {
  success: false
  code: number
  message: string
  error: unknown
}

type Result<T> = SuccessResult<T> | ErrorResult
```


# 贡献指南 (https://ikenxuan.github.io/amagi/docs/v6/dev/contributing)

> 提交规范和 PR 流程



# 贡献指南 [#贡献指南]

感谢你对 amagi 的贡献！本文档介绍提交规范和 PR 流程。

## 提交规范 [#提交规范]

使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

| 类型         | 说明     | 示例                                  |
| ---------- | ------ | ----------------------------------- |
| `feat`     | 新功能    | `feat: add fetchVideoTags API`      |
| `fix`      | Bug 修复 | `fix: correct parameter validation` |
| `docs`     | 文档更新   | `docs: update installation guide`   |
| `refactor` | 重构     | `refactor: simplify fetcher logic`  |
| `perf`     | 性能优化   | `perf: cache wbi keys`              |
| `chore`    | 构建/工具  | `chore: update dependencies`        |
| `test`     | 测试     | `test: add unit tests for sign`     |

### 提交信息格式 [#提交信息格式]

```
<type>(<scope>): <subject>

<body>

<footer>
```

示例：

```
feat(bilibili): add fetchVideoTags API

- Add VideoTagsParams type
- Add validation schema
- Implement fetcher method

Closes #123
```

## 发起 PR [#发起-pr]

<Steps>
  <Step>
    ### 同步上游 [#同步上游]

    确保你的 Fork 是最新的：

    ```bash
    # 添加上游仓库（只需一次）
    git remote add upstream https://github.com/ikenxuan/amagi.git

    # 同步上游
    git fetch upstream
    git checkout main
    git merge upstream/main
    ```
  </Step>

  <Step>
    ### 创建分支 [#创建分支]

    从最新的 `main` 分支创建功能分支：

    ```bash
    git checkout -b feat/your-feature
    ```

    分支命名规范：

    * `feat/xxx` - 新功能
    * `fix/xxx` - Bug 修复
    * `docs/xxx` - 文档更新
    * `refactor/xxx` - 重构
  </Step>

  <Step>
    ### 开发与提交 [#开发与提交]

    ```bash
    # 开发...

    # 提交
    git add .
    git commit -m "feat: your feature description"
    ```
  </Step>

  <Step>
    ### 推送到你的仓库 [#推送到你的仓库]

    ```bash
    git push origin feat/your-feature
    ```
  </Step>

  <Step>
    ### 创建 Pull Request [#创建-pull-request]

    1. 在 GitHub 上打开你的 Fork 仓库
    2. 点击 "Compare & pull request"
    3. 填写 PR 描述：
       * 说明改动内容
       * 关联相关 Issue（如有）
       * 列出测试情况
    4. 提交 PR 到 `ikenxuan/amagi` 的 `main` 分支
  </Step>
</Steps>

## 代码风格 [#代码风格]

### 基本规范 [#基本规范]

* 使用 TypeScript 严格模式
* 使用 Oxlint 进行代码检查
* 运行 `pnpm fix` 自动修复格式问题

### 导入顺序 [#导入顺序]

```ts
// 1. 外部依赖
import { z } from 'zod'
import axios from 'axios'

// 2. 内部模块
import { createSuccessResponse } from '../utils'
import { bilibiliApiUrls } from './API'

// 3. 类型导入
import type { BilibiliVideoInfoOptions } from './types'
```

### 注释规范 [#注释规范]

函数和接口需要 JSDoc 注释：

```ts
/**
 * 获取视频标签
 * @param options - 请求参数
 * @param options.avid - 视频 AV 号
 * @param cookie - B站 Cookie
 * @returns 视频标签列表
 */
export async function fetchVideoTags(options: { avid: number }, cookie?: string) {
  // ...
}
```

## PR 检查清单 [#pr-检查清单]

提交 PR 前，请确认：

* [ ] 代码通过类型检查 (`pnpm typecheck`)
* [ ] 代码通过 lint 检查 (`pnpm lint`)
* [ ] 构建成功 (`pnpm build`)
* [ ] 已手动测试新功能
* [ ] 提交信息符合规范
* [ ] PR 描述清晰完整

## 问题反馈 [#问题反馈]

* 发现 Bug：[GitHub Issues](https://github.com/ikenxuan/amagi/issues)
* 功能建议：[GitHub Discussions](https://github.com/ikenxuan/amagi/discussions)
* 安全问题：请私信联系维护者


# 开始开发 (https://ikenxuan.github.io/amagi/docs/v6/dev)

> 贡献者快速入门



# 开始开发 [#开始开发]

本文档面向贡献者，介绍如何参与 amagi 的开发。

## 环境要求 [#环境要求]

* Node.js >= 22
* pnpm >= 9

## 快速开始 [#快速开始]

<Steps>
  <Step>
    ### Fork 仓库 [#fork-仓库]

    在 GitHub 上 Fork [ikenxuan/amagi](https://github.com/ikenxuan/amagi) 到你的账号下。
  </Step>

  <Step>
    ### 克隆你的仓库 [#克隆你的仓库]

    ```bash
    git clone https://github.com/你的用户名/amagi.git
    cd amagi
    ```
  </Step>

  <Step>
    ### 安装依赖 [#安装依赖]

    ```bash
    pnpm install
    ```
  </Step>

  <Step>
    ### 开发模式 [#开发模式]

    <Tabs items="['核心包', '文档站']">
      <Tab value="核心包">
        ```bash
        pnpm dev
        ```

        在 `packages/core` 下启动开发模式，监听文件变化。
      </Tab>

      <Tab value="文档站">
        ```bash
        pnpm docs:dev
        ```

        访问 [http://localhost:3000](http://localhost:3000) 预览文档。
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### 构建 [#构建]

    ```bash
    pnpm build
    ```
  </Step>
</Steps>

## 常用命令 [#常用命令]

| 命令                | 说明       |
| ----------------- | -------- |
| `pnpm install`    | 安装依赖     |
| `pnpm dev`        | 核心包开发模式  |
| `pnpm build`      | 构建所有包    |
| `pnpm typecheck`  | 类型检查     |
| `pnpm lint`       | 代码检查     |
| `pnpm fix`        | 自动修复代码风格 |
| `pnpm docs:dev`   | 文档站开发模式  |
| `pnpm docs:build` | 构建文档站    |

## 下一步 [#下一步]

* [项目架构](/docs/v6/dev/architecture) - 了解项目结构和核心概念
* [新增接口](/docs/v6/dev/add-api) - 学习如何新增平台接口
* [贡献指南](/docs/v6/dev/contributing) - 提交规范和 PR 流程


# B站 API (https://ikenxuan.github.io/amagi/docs/v6/usage/api/bilibili)

> B站平台 API 参考文档



# B站 API [#b站-api]

B站平台的所有 API 方法参考。

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 中的绑定 Fetcher 使用 `client.bilibili.fetcher.method(options, requestConfig?)`。第二个参数只作用于当前调用，并与 Client 的实例级请求配置合并；单次配置优先，`headers` 会单独合并。显式提供大写 `headers.Cookie` 时，它也会替换本次底层调用的 cookie 参数。

直接导出的裸 Fetcher 使用 `bilibiliFetcher.method(options, cookie?, requestConfig?)`。这里没有实例级配置，第三个参数会直接透传到当前请求。`amagi.bilibiliFetcher` 与该命名导出是同一个裸 Fetcher。

当第三个参数显式设置 `headers.Cookie` 时，第二个参数必须传入完全相同的字符串字面量；接口支持匿名时，请写作 `method(options, '', { headers: { Cookie: '' } })`。字段名严格区分大小写，请使用 `Cookie`，不要使用 `cookie`。

## Fetcher 方法 [#fetcher-方法]

### fetchVideoInfo [#fetchvideoinfo]

获取单个视频作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD',
  typeMode: 'strict'
})
```

| 参数         | 类型                    | 必填 | 说明      |
| ---------- | --------------------- | -- | ------- |
| `bvid`     | `string`              | 是  | 视频 BV 号 |
| `typeMode` | `'strict' \| 'loose'` | 否  | 类型模式    |

***

### fetchVideoStreamUrl [#fetchvideostreamurl]

获取视频下载信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchVideoStreamUrl({
  avid: 170001,
  cid: 279786
})
```

| 参数     | 类型       | 必填 | 说明      |
| ------ | -------- | -- | ------- |
| `avid` | `number` | 是  | 视频 AV 号 |
| `cid`  | `number` | 是  | 视频 CID  |

***

### fetchVideoDanmaku [#fetchvideodanmaku]

获取视频实时弹幕。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchVideoDanmaku({
  cid: 279786,
  segment_index: 1
})
```

| 参数              | 类型       | 必填 | 说明        |
| --------------- | -------- | -- | --------- |
| `cid`           | `number` | 是  | 视频 CID    |
| `segment_index` | `number` | 否  | 分段索引，默认 1 |

***

### fetchComments [#fetchcomments]

获取评论数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchComments({
  oid: '170001',
  type: 1,
  number: 20
})
```

| 参数       | 类型       | 必填 | 说明    |
| -------- | -------- | -- | ----- |
| `oid`    | `string` | 是  | 目标 ID |
| `type`   | `number` | 是  | 评论区类型 |
| `number` | `number` | 否  | 每页数量  |

**评论区类型**: 1=视频, 11=图文动态, 12=专栏, 14=音频, 17=文字动态

绑定 Fetcher 的第二个参数是当前调用专用的 `requestConfig`。它会与 Client 的实例级请求配置合并，单次配置优先，请求头也会单独合并。

例如，只让本次评论请求不携带 Client 中配置的 B站 Cookie：

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=example', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchComments(
  {
    oid: '170001',
    type: 1,
    number: 20,
    typeMode: 'strict'
  },
  {
    headers: {
      Cookie: ''
    }
  }
)
```

该配置只影响当前请求，不会修改 Client 实例，也不会影响同一实例发起的后续请求。

***

### fetchCommentReplies [#fetchcommentreplies]

获取指定评论的回复。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchCommentReplies({
  oid: '170001',
  type: 1,
  root: '123456789'
})
```

| 参数     | 类型       | 必填 | 说明     |
| ------ | -------- | -- | ------ |
| `oid`  | `string` | 是  | 目标 ID  |
| `type` | `number` | 是  | 评论区类型  |
| `root` | `string` | 是  | 根评论 ID |

需要匿名获取评论回复时，同样可以通过第二个 `requestConfig` 参数传入 `{ headers: { Cookie: '' } }`。

***

### fetchUserCard [#fetchusercard]

获取用户主页数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchUserCard({
  host_mid: 123456
})
```

| 参数         | 类型       | 必填 | 说明     |
| ---------- | -------- | -- | ------ |
| `host_mid` | `number` | 是  | 用户 UID |

***

### fetchUserDynamicList [#fetchuserdynamiclist]

获取用户主页动态列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchUserDynamicList({
  host_mid: 123456
})
```

***

### fetchUserLiveStatus [#fetchuserlivestatus]

按用户 UID 查询直播状态和直播间基础信息。该接口直接读取直播状态，不依赖用户空间动态中的直播推荐卡片，适合轮询开播状态。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchUserLiveStatus({
  host_mid: 123456,
  typeMode: 'strict'
})

if (result.success && result.data.data.liveStatus === 1) {
  console.log(result.data.data.roomid)
}
```

| 参数         | 类型                    | 必填 | 说明     |
| ---------- | --------------------- | -- | ------ |
| `host_mid` | `number`              | 是  | 用户 UID |
| `typeMode` | `'strict' \| 'loose'` | 否  | 类型模式   |

主要状态字段：

| 字段           | 说明                       |
| ------------ | ------------------------ |
| `roomStatus` | `1` 表示用户已开通直播间，`0` 表示未开通 |
| `liveStatus` | `1` 表示正在直播，`0` 表示当前未开播   |
| `roomid`     | 直播间 ID；未开通直播间时为 `0`      |
| `title`      | 直播间标题                    |
| `cover`      | 直播封面                     |

HTTP 服务也会注册 `GET /api/bilibili/fetch_user_live_status?host_mid=123456`。

***

### fetchUserSpaceInfo [#fetchuserspaceinfo]

获取用户空间详细信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchUserSpaceInfo({
  host_mid: 123456
})
```

***

### fetchUploaderTotalViews [#fetchuploadertotalviews]

获取 UP 主总播放量。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchUploaderTotalViews({
  host_mid: 123456
})
```

***

### fetchDynamicDetail [#fetchdynamicdetail]

获取动态详情。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchDynamicDetail({
  dynamic_id: '123456789'
})
```

***

### fetchBangumiInfo [#fetchbangumiinfo]

获取番剧基本信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// 通过 ep_id
const result = await client.bilibili.fetcher.fetchBangumiInfo({
  ep_id: '123456'
})

// 或通过 season_id
const result2 = await client.bilibili.fetcher.fetchBangumiInfo({
  season_id: '123456'
})
```

| 参数          | 类型       | 必填  | 说明    |
| ----------- | -------- | --- | ----- |
| `ep_id`     | `string` | 二选一 | 剧集 ID |
| `season_id` | `string` | 二选一 | 季度 ID |

***

### fetchBangumiStreamUrl [#fetchbangumistreamurl]

获取番剧下载信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchBangumiStreamUrl({
  cid: 279786,
  ep_id: '123456'
})
```

***

### fetchLiveRoomInfo [#fetchliveroominfo]

获取直播间信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchLiveRoomInfo({
  room_id: '123456'
})
```

***

### fetchLiveRoomInitInfo [#fetchliveroominitinfo]

获取直播间初始化信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchLiveRoomInitInfo({
  room_id: '123456'
})
```

***

### fetchArticleContent [#fetcharticlecontent]

获取专栏正文内容。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchArticleContent({
  id: '123456'
})
```

***

### fetchArticleCards [#fetcharticlecards]

获取专栏显示卡片信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchArticleCards({
  ids: ['123456', '789012']
})
```

***

### fetchLoginStatus [#fetchloginstatus]

获取登录基本信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchLoginStatus({})
```

***

### requestLoginQrcode [#requestloginqrcode]

申请登录二维码。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.requestLoginQrcode({})
```

***

### checkQrcodeStatus [#checkqrcodestatus]

检查二维码状态。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.checkQrcodeStatus({
  qrcode_key: 'xxx'
})
```

***

### convertAvToBv [#convertavtobv]

AV 号转 BV 号。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.convertAvToBv({
  avid: 170001
})
```

***

### convertBvToAv [#convertbvtoav]

BV 号转 AV 号。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.convertBvToAv({
  bvid: 'BV1xx411c7mD'
})
```

***

### fetchEmojiList [#fetchemojilist]

获取 Emoji 列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchEmojiList({})
```


# 抖音 API (https://ikenxuan.github.io/amagi/docs/v6/usage/api/douyin)

> 抖音平台 API 参考文档



# 抖音 API [#抖音-api]

抖音平台的所有 API 方法参考。

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 中的绑定 Fetcher 使用 `client.douyin.fetcher.method(options, requestConfig?)`。第二个参数只作用于当前调用，并与 Client 的实例级请求配置合并；单次配置优先，`headers` 会单独合并。显式提供大写 `headers.Cookie` 时，它也会替换本次底层调用的 cookie 参数。

直接导出的裸 Fetcher 使用 `douyinFetcher.method(options, cookie?, requestConfig?)`。这里没有实例级配置，第三个参数会直接透传到当前请求。`amagi.douyinFetcher` 与该命名导出是同一个裸 Fetcher。

当第三个参数显式设置 `headers.Cookie` 时，第二个参数必须传入完全相同的字符串字面量；接口支持匿名时，请写作 `method(options, '', { headers: { Cookie: '' } })`。字段名严格区分大小写，请使用 `Cookie`，不要使用 `cookie`。

## Fetcher 方法 [#fetcher-方法]

### fetchVideoWork [#fetchvideowork]

获取视频作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchVideoWork({
  aweme_id: '1234567890123456789',
  typeMode: 'strict'
})
```

| 参数         | 类型                    | 必填 | 说明    |
| ---------- | --------------------- | -- | ----- |
| `aweme_id` | `string`              | 是  | 作品 ID |
| `typeMode` | `'strict' \| 'loose'` | 否  | 类型模式  |

***

### fetchImageAlbumWork [#fetchimagealbumwork]

获取图集作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchImageAlbumWork({
  aweme_id: '1234567890123456789'
})
```

***

### fetchSlidesWork [#fetchslideswork]

获取合辑作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchSlidesWork({
  aweme_id: '1234567890123456789'
})
```

***

### fetchTextWork [#fetchtextwork]

获取文字作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchTextWork({
  aweme_id: '1234567890123456789'
})
```

***

### parseWork [#parsework]

聚合解析作品（自动识别视频/图集/合辑）。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.parseWork({
  aweme_id: '1234567890123456789'
})
```

<Callout type="info">
  推荐使用 

  `parseWork`

   方法，它会自动识别作品类型并返回相应数据。
</Callout>

***

### fetchWorkComments [#fetchworkcomments]

获取作品评论数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchWorkComments({
  aweme_id: '1234567890123456789',
  number: 20,
  cursor: 0
})
```

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |
| `number`   | `number` | 否  | 获取数量  |
| `cursor`   | `number` | 否  | 分页游标  |

***

### fetchCommentReplies [#fetchcommentreplies]

获取指定评论的回复数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchCommentReplies({
  aweme_id: '1234567890123456789',
  comment_id: '7123456789012345678',
  number: 20,
  cursor: 0
})
```

| 参数           | 类型       | 必填 | 说明    |
| ------------ | -------- | -- | ----- |
| `aweme_id`   | `string` | 是  | 作品 ID |
| `comment_id` | `string` | 是  | 评论 ID |
| `number`     | `number` | 否  | 获取数量  |
| `cursor`     | `number` | 否  | 分页游标  |

***

### fetchUserProfile [#fetchuserprofile]

获取用户主页数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchUserProfile({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})
```

***

### fetchUserVideoList [#fetchuservideolist]

获取用户主页视频列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchUserVideoList({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})
```

| 参数        | 类型       | 必填 | 说明          |
| --------- | -------- | -- | ----------- |
| `sec_uid` | `string` | 是  | 用户 sec\_uid |

***

### searchContent [#searchcontent]

搜索内容。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// 综合搜索
const result = await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'general',
  number: 20
})

// 用户搜索
const userResult = await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'user'
})

// 视频搜索
const videoResult = await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'video'
})
```

| 参数          | 类型                               | 必填 | 说明         |
| ----------- | -------------------------------- | -- | ---------- |
| `query`     | `string`                         | 是  | 搜索关键词      |
| `type`      | `'general' \| 'user' \| 'video'` | 否  | 搜索类型       |
| `number`    | `number`                         | 否  | 获取数量       |
| `search_id` | `string`                         | 否  | 搜索 ID（分页用） |

***

### fetchSuggestWords [#fetchsuggestwords]

获取热点词/搜索建议。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchSuggestWords({
  query: '关键词'
})
```

| 参数      | 类型       | 必填 | 说明    |
| ------- | -------- | -- | ----- |
| `query` | `string` | 是  | 搜索关键词 |

***

### fetchMusicInfo [#fetchmusicinfo]

获取音乐数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchMusicInfo({
  music_id: '7123456789012345678'
})
```

***

### fetchLiveRoomInfo [#fetchliveroominfo]

获取直播间信息。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchLiveRoomInfo({
  room_id: '7123456789',
  web_rid: 'xxx'
})
```

| 参数        | 类型       | 必填 | 说明       |
| --------- | -------- | -- | -------- |
| `room_id` | `string` | 是  | 直播间 ID   |
| `web_rid` | `string` | 是  | 直播间真实房间号 |

***

### fetchDanmakuList [#fetchdanmakulist]

获取弹幕数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchDanmakuList({
  aweme_id: '1234567890123456789',
  duration: 60000,
  start_time: 0,
  end_time: 60000
})
```

| 参数           | 类型       | 必填 | 说明       |
| ------------ | -------- | -- | -------- |
| `aweme_id`   | `string` | 是  | 作品 ID    |
| `duration`   | `number` | 是  | 视频时长（毫秒） |
| `start_time` | `number` | 否  | 开始时间（毫秒） |
| `end_time`   | `number` | 否  | 结束时间（毫秒） |

***

### requestLoginQrcode [#requestloginqrcode]

申请登录二维码。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.requestLoginQrcode({
  verify_fp: 'verify_xxx'
})
```

| 参数          | 类型       | 必填 | 说明    |
| ----------- | -------- | -- | ----- |
| `verify_fp` | `string` | 是  | fp 指纹 |

***

### fetchEmojiList [#fetchemojilist]

获取 Emoji 列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchEmojiList({})
```

***

### fetchDynamicEmojiList [#fetchdynamicemojilist]

获取动态表情列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.douyin.fetcher.fetchDynamicEmojiList({})
```


# 快手 API (https://ikenxuan.github.io/amagi/docs/v6/usage/api/kuaishou)

> 快手平台 API 参考文档



# 快手 API [#快手-api]

快手平台的所有 API 方法参考。

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 中的绑定 Fetcher 使用 `client.kuaishou.fetcher.method(options, requestConfig?)`。第二个参数只作用于当前调用，并与 Client 的实例级请求配置合并；单次配置优先，`headers` 会单独合并。显式提供大写 `headers.Cookie` 时，它也会替换本次底层调用的 cookie 参数。

直接导出的裸 Fetcher 使用 `kuaishouFetcher.method(options, cookie?, requestConfig?)`。这里没有实例级配置，第三个参数会直接透传到当前请求。`amagi.kuaishouFetcher` 与该命名导出是同一个裸 Fetcher。

当第三个参数显式设置 `headers.Cookie` 时，第二个参数必须传入完全相同的字符串字面量；接口支持匿名时，请写作 `method(options, '', { headers: { Cookie: '' } })`。字段名严格区分大小写，请使用 `Cookie`，不要使用 `cookie`。

## Fetcher 方法 [#fetcher-方法]

### fetchVideoWork [#fetchvideowork]

获取单个视频作品数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchVideoWork({
  photoId: '3xqxxxxxx',
  typeMode: 'strict'
})
```

| 参数         | 类型                    | 必填 | 说明    |
| ---------- | --------------------- | -- | ----- |
| `photoId`  | `string`              | 是  | 作品 ID |
| `typeMode` | `'strict' \| 'loose'` | 否  | 类型模式  |

***

### fetchWorkComments [#fetchworkcomments]

获取作品评论数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchWorkComments({
  photoId: '3xqxxxxxx'
})
```

| 参数        | 类型       | 必填 | 说明    |
| --------- | -------- | -- | ----- |
| `photoId` | `string` | 是  | 作品 ID |

***

### fetchUserProfile [#fetchuserprofile]

获取用户主页聚合数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchUserProfile({
  principalId: 'KPL704668133',
  typeMode: 'strict'
})
```

| 参数            | 类型                    | 必填 | 说明                 |
| ------------- | --------------------- | -- | ------------------ |
| `principalId` | `string`              | 是  | 用户主页 `principalId` |
| `typeMode`    | `'strict' \| 'loose'` | 否  | 类型模式               |

***

### fetchUserWorkList [#fetchuserworklist]

获取用户公开视频列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchUserWorkList({
  principalId: 'KPL704668133',
  count: 12,
  pcursor: '',
  typeMode: 'strict'
})
```

| 参数            | 类型                    | 必填 | 说明                 |
| ------------- | --------------------- | -- | ------------------ |
| `principalId` | `string`              | 是  | 用户主页 `principalId` |
| `count`       | `number`              | 否  | 每页数量，默认 `12`       |
| `pcursor`     | `string`              | 否  | 分页游标，首屏可传空串        |
| `typeMode`    | `'strict' \| 'loose'` | 否  | 类型模式               |

***

### fetchLiveRoomInfo [#fetchliveroominfo]

获取直播间聚合数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchLiveRoomInfo({
  principalId: 'KPL704668133',
  typeMode: 'strict'
})
```

| 参数            | 类型                    | 必填 | 说明                |
| ------------- | --------------------- | -- | ----------------- |
| `principalId` | `string`              | 是  | 直播间 `principalId` |
| `typeMode`    | `'strict' \| 'loose'` | 否  | 类型模式              |

***

### fetchEmojiList [#fetchemojilist]

获取 Emoji 列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.kuaishou.fetcher.fetchEmojiList({})
```

## 使用示例 [#使用示例]

### 获取视频信息 [#获取视频信息]

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({
  cookies: {
    bilibili: '',
    douyin: '',
    kuaishou: 'did=xxx; ...',
    xiaohongshu: ''
  }
})

const result = await client.kuaishou.fetcher.fetchVideoWork({
  photoId: '3xqxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

## 工具集 [#工具集]

### URL 拼接器 [#url-拼接器]

```ts
import { kuaishouUtils } from '@ikenxuan/amagi'

// 获取结构化请求描述对象
const request = kuaishouUtils.kuaishouApiUrls.videoWork({
  photoId: '3xqxxxxxx'
})
```

### `live_api` 签名 [#live_api-签名]

```ts
import { kuaishouUtils } from '@ikenxuan/amagi'

const request = kuaishouUtils.kuaishouApiUrls.userInfoById({
  principalId: 'KPL704668133'
})

const signed = kuaishouUtils.sign.signLiveApiRequest(request, 'kwfv1=your_cookie_value')
```

## 注意事项 [#注意事项]

<Callout type="warning">
  快手接口需要有效的 Cookie，部分接口可能需要登录状态才能获取完整数据。
</Callout>

* 快手的 `photoId` 可以从分享链接中提取
* 快手的 `principalId` 可以从用户主页或直播间 URL 末段提取
* 评论数据可能需要登录 Cookie 才能获取
* 建议设置合理的请求间隔，避免触发风控


# 小红书 API (https://ikenxuan.github.io/amagi/docs/v6/usage/api/xiaohongshu)

> 小红书平台 API 参考文档



# 小红书 API [#小红书-api]

小红书平台的所有 API 方法参考。

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 中的绑定 Fetcher 使用 `client.xiaohongshu.fetcher.method(options, requestConfig?)`。第二个参数只作用于当前调用，并与 Client 的实例级请求配置合并；单次配置优先，`headers` 会单独合并。显式提供大写 `headers.Cookie` 时，它也会替换本次底层调用的 cookie 参数。

直接导出的裸 Fetcher 使用 `xiaohongshuFetcher.method(options, cookie?, requestConfig?)`。这里没有实例级配置，第三个参数会直接透传到当前请求。`amagi.xiaohongshuFetcher` 与该命名导出是同一个裸 Fetcher。

当第三个参数显式设置 `headers.Cookie` 时，第二个参数必须传入完全相同的字符串字面量。字段名严格区分大小写，请使用 `Cookie`，不要使用 `cookie`。

小红书接口签名通常需要从 cookie 参数读取 `a1`，因此不要把需要签名的请求强行改为空 Cookie；如需覆盖 Cookie，两处应传入同一个包含有效 `a1` 的字符串。

## Fetcher 方法 [#fetcher-方法]

### fetchHomeFeed [#fetchhomefeed]

获取首页推荐数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchHomeFeed({
  cursor_score: '',
  num: 20,
  refresh_type: 1,
  note_index: 0
})
```

| 参数             | 类型       | 必填 | 说明                   |
| -------------- | -------- | -- | -------------------- |
| `cursor_score` | `string` | 否  | 分页游标                 |
| `num`          | `number` | 否  | 获取数量                 |
| `refresh_type` | `number` | 否  | 刷新类型: 1=下拉刷新, 3=上拉加载 |
| `note_index`   | `number` | 否  | 笔记索引                 |

***

### fetchNoteDetail [#fetchnotedetail]

获取单个笔记数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchNoteDetail({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx',
  typeMode: 'strict'
})
```

| 参数           | 类型                    | 必填 | 说明    |
| ------------ | --------------------- | -- | ----- |
| `note_id`    | `string`              | 是  | 笔记 ID |
| `xsec_token` | `string`              | 是  | 安全令牌  |
| `typeMode`   | `'strict' \| 'loose'` | 否  | 类型模式  |

<Callout type="info">
  `xsec_token`

   可以从笔记分享链接中获取，格式通常为 

  `xsec_xxx`

  。
</Callout>

***

### fetchNoteComments [#fetchnotecomments]

获取笔记评论数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchNoteComments({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx',
  cursor: ''
})
```

| 参数           | 类型       | 必填 | 说明    |
| ------------ | -------- | -- | ----- |
| `note_id`    | `string` | 是  | 笔记 ID |
| `xsec_token` | `string` | 是  | 安全令牌  |
| `cursor`     | `string` | 否  | 分页游标  |

***

### fetchUserProfile [#fetchuserprofile]

获取用户数据。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchUserProfile({
  user_id: '5xxxxxxxxx'
})
```

***

### fetchUserNoteList [#fetchusernotelist]

获取用户笔记列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchUserNoteList({
  user_id: '5xxxxxxxxx',
  cursor: '',
  num: 20
})
```

| 参数        | 类型       | 必填 | 说明    |
| --------- | -------- | -- | ----- |
| `user_id` | `string` | 是  | 用户 ID |
| `cursor`  | `string` | 否  | 分页游标  |
| `num`     | `number` | 否  | 获取数量  |

***

### searchNotes [#searchnotes]

搜索笔记。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.searchNotes({
  keyword: '关键词',
  page: 1,
  page_size: 20,
  sort: 'general',
  note_type: 0
})
```

| 参数          | 类型       | 必填 | 说明    |
| ----------- | -------- | -- | ----- |
| `keyword`   | `string` | 是  | 搜索关键词 |
| `page`      | `number` | 否  | 页码    |
| `page_size` | `number` | 否  | 每页数量  |
| `sort`      | `string` | 否  | 排序方式  |
| `note_type` | `number` | 否  | 笔记类型  |

**排序方式**: `general`=综合排序, `time_descending`=最新发布, `popularity_descending`=最多点赞

***

### fetchEmojiList [#fetchemojilist]

获取表情列表。

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.xiaohongshu.fetcher.fetchEmojiList({})
```

## 工具集 [#工具集]

### 签名算法 [#签名算法]

```ts
import { xiaohongshuUtils } from '@ikenxuan/amagi'

// 从 Cookie 中提取 a1
const a1 = xiaohongshuUtils.sign.extractA1FromCookie('a1=xxx; webId=yyy; ...')

// 生成搜索 ID
const searchId = xiaohongshuUtils.sign.getSearchId()

// 生成 X-T 时间戳
const xt = xiaohongshuUtils.sign.generateXT()
```

## 注意事项 [#注意事项]

<Callout type="warning">
  小红书接口对签名和 Cookie 要求较高，请确保： 1. Cookie 中包含有效的 `a1` 值 2. 正确传递 `xsec_token` 参数 3. 设置合理的请求间隔
</Callout>

* `note_id` 和 `xsec_token` 可以从笔记分享链接中提取
* 部分接口需要登录状态才能获取完整数据
* 小红书的反爬机制较为严格，建议控制请求频率


# 快速上手 (https://ikenxuan.github.io/amagi/docs/v6/usage/getting-started)

> 快速开始使用 @ikenxuan/amagi



# 快速上手 [#快速上手]

本指南将帮助你快速了解 amagi 的基本用法。

## 基本用法 [#基本用法]

### 1. 创建客户端实例 [#1-创建客户端实例]

```ts
import amagi from '@ikenxuan/amagi'

// 创建客户端实例，绑定各平台 Cookie
const client = amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; bili_jct=yyy; ...',
    douyin: 'ttwid=...; ...',
    kuaishou: 'did=...; ...',
    xiaohongshu: 'a1=...; ...'
  },
  request: {
    // 可选：自定义请求配置
    headers: { 'User-Agent': 'Mozilla/5.0 ...' }
  }
})
```

### 2. 获取数据 [#2-获取数据]

使用 `fetcher` API 获取数据（推荐）：

<Tabs items="['B站', '抖音', '快手', '小红书']">
  <Tab value="B站">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 获取视频信息
    const video = await client.bilibili.fetcher.fetchVideoInfo({ 
      bvid: 'BV1xx411c7mD' 
    })

    if (video.success) {
    console.log(video.data)
    }

    // 获取评论
    const comments = await client.bilibili.fetcher.fetchComments({
    oid: '170001',
    type: 1,
    number: 20
    })

    ```
  </Tab>

  <Tab value="抖音">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 获取作品数据
    const work = await client.douyin.fetcher.fetchVideoWork({
      aweme_id: '1234567890123456789'
    })

    // 聚合解析（自动识别类型）
    const parsed = await client.douyin.fetcher.parseWork({
      aweme_id: '1234567890123456789'
    })

    // 获取评论
    const comments = await client.douyin.fetcher.fetchWorkComments({
      aweme_id: '1234567890123456789',
      number: 20
    })
    ```
  </Tab>

  <Tab value="快手">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 获取作品信息
    const work = await client.kuaishou.fetcher.fetchVideoWork({ 
      photoId: '3xqxxxxxx' 
    })

    // 获取评论
    const comments = await client.kuaishou.fetcher.fetchWorkComments({
    photoId: '3xqxxxxxx'
    })

    ```
  </Tab>

  <Tab value="小红书">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 获取笔记数据
    const note = await client.xiaohongshu.fetcher.fetchNoteDetail({
      note_id: '64xxxxxxxx',
      xsec_token: 'xsec_xxx'
    })

    // 获取评论
    const comments = await client.xiaohongshu.fetcher.fetchNoteComments({
      note_id: '64xxxxxxxx',
      xsec_token: 'xsec_xxx'
    })
    ```
  </Tab>
</Tabs>

### 3. 启动 HTTP 服务 [#3-启动-http-服务]

一行代码启动本地 HTTP 服务：

```ts
import amagi from '@ikenxuan/amagi'

amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; ...',
    douyin: 'ttwid=...; ...',
    kuaishou: 'did=...; ...',
    xiaohongshu: 'a1=...; ...'
  }
}).startServer(4567)

// 访问 http://localhost:4567/
// API 文档：https://amagi.apifox.cn
```

## 静态方法调用 [#静态方法调用]

如果不想创建实例，也可以直接使用静态方法：

```ts
import amagi from '@ikenxuan/amagi'

// 需要手动传递 cookie
const result = await amagi.bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }, 'SESSDATA=...')
```

## 类型模式 [#类型模式]

amagi 支持两种类型模式：

<Tabs items="['宽松模式', '严格模式']">
  <Tab value="宽松模式">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 宽松模式 (默认) - 返回 any 类型
    const result = await client.bilibili.fetcher.fetchVideoInfo({ 
      bvid: 'BV1xx411c7mD' 
    })

    result.data

    ```
  </Tab>

  <Tab value="严格模式">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // 严格模式 - 返回完整类型定义
    const result = await client.bilibili.fetcher.fetchVideoInfo({
      bvid: 'BV1xx411c7mD',
      typeMode: 'strict'
    })

    result.data
    ```
  </Tab>
</Tabs>

## 事件监听 [#事件监听]

amagi v6 采用事件驱动架构，你可以监听各种事件：

```ts
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })

// 监听 API 成功事件
client.events.on('api:success', (data) => {
  console.log(`[${data.platform}] ${data.methodType} 成功，耗时 ${data.duration}ms`)
})

// 监听 API 错误事件
client.events.on('api:error', (data) => {
  console.error(`[${data.platform}] ${data.methodType} 失败: ${data.errorMessage}`)
})

// 监听日志事件
client.events.on('log:info', (data) => {
  console.log(data.message)
})
```

## 下一步 [#下一步]

* [SDK 使用指南](/docs/v6/usage/guide/sdk) - 详细了解 SDK 的使用方法
* [HTTP 服务](/docs/v6/usage/guide/http-server) - 了解如何使用 HTTP 服务
* [API 参考](/docs/v6/usage/api/bilibili) - 查看各平台的 API 文档


# 事件系统 (https://ikenxuan.github.io/amagi/docs/v6/usage/guide/events)

> 使用 amagi 的事件驱动架构



# 事件系统 [#事件系统]

amagi v6 采用事件驱动架构，移除了对 log4js 的依赖，通过事件系统提供日志、监控等功能。

## 基本用法 [#基本用法]

```ts
import amagi, { amagiEvents } from '@ikenxuan/amagi'

// 方式 1：通过客户端实例
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
client.events.on('api:success', (data) => {
  console.log(`[${data.platform}] ${data.methodType} 成功`)
})

// 方式 2：通过全局事件对象
amagiEvents.on('log:info', (data) => {
  console.log(data.message)
})

// 方式 3：通过静态方法
amagi.on('api:error', (data) => {
  console.error(`API 错误: ${data.errorMessage}`)
})
```

## 事件类型 [#事件类型]

### 日志事件 [#日志事件]

| 事件名         | 说明   | 数据类型           |
| ----------- | ---- | -------------- |
| `log:info`  | 信息日志 | `LogEventData` |
| `log:warn`  | 警告日志 | `LogEventData` |
| `log:error` | 错误日志 | `LogEventData` |
| `log:debug` | 调试日志 | `LogEventData` |
| `log:mark`  | 标记日志 | `LogEventData` |

```ts
interface LogEventData {
  level: 'info' | 'warn' | 'error' | 'debug' | 'mark'
  message: string
  args?: unknown[]
  timestamp: Date
}
```

### HTTP 事件 [#http-事件]

| 事件名             | 说明        | 数据类型                    |
| --------------- | --------- | ----------------------- |
| `http:request`  | HTTP 请求发起 | `HttpRequestEventData`  |
| `http:response` | HTTP 响应接收 | `HttpResponseEventData` |
| `http:error`    | HTTP 错误   | `NetworkErrorEventData` |

```ts
interface HttpRequestEventData {
  method: string
  url: string
  headers?: Record<string, string>
  timestamp: Date
}

interface HttpResponseEventData {
  method: string
  url: string
  statusCode: number
  responseTime: number
  clientIP?: string
  requestSize?: string
  responseSize?: string
  timestamp: Date
}
```

### 网络事件 [#网络事件]

| 事件名             | 说明   | 数据类型                    |
| --------------- | ---- | ----------------------- |
| `network:retry` | 网络重试 | `NetworkRetryEventData` |
| `network:error` | 网络错误 | `NetworkErrorEventData` |

```ts
interface NetworkRetryEventData {
  errorCode: string
  attempt: number
  maxRetries: number
  delayMs: number
  url?: string
  timestamp: Date
}

interface NetworkErrorEventData {
  errorCode: string
  message: string
  retries: number
  url?: string
  timestamp: Date
}
```

### API 事件 [#api-事件]

| 事件名           | 说明       | 数据类型                  |
| ------------- | -------- | --------------------- |
| `api:success` | API 调用成功 | `ApiSuccessEventData` |
| `api:error`   | API 调用失败 | `ApiErrorEventData`   |

```ts
interface ApiSuccessEventData {
  platform: 'douyin' | 'bilibili' | 'kuaishou' | 'xiaohongshu'
  methodType: string
  response: unknown
  statusCode: number
  duration: number
  timestamp: Date
}

interface ApiErrorEventData {
  platform: 'douyin' | 'bilibili' | 'kuaishou' | 'xiaohongshu'
  methodType: string
  errorCode?: string | number
  errorMessage: string
  url?: string
  duration?: number
  timestamp: Date
}
```

## 实现自定义日志 [#实现自定义日志]

### 使用 console [#使用-console]

```ts
import { amagiEvents } from '@ikenxuan/amagi'

amagiEvents.on('log:info', (data) => console.log(`[INFO] ${data.message}`))
amagiEvents.on('log:warn', (data) => console.warn(`[WARN] ${data.message}`))
amagiEvents.on('log:error', (data) => console.error(`[ERROR] ${data.message}`))
amagiEvents.on('log:debug', (data) => console.debug(`[DEBUG] ${data.message}`))
```

### 使用 pino [#使用-pino]

```ts
import { amagiEvents } from '@ikenxuan/amagi'
import pino from 'pino'

const logger = pino()

amagiEvents.on('log:info', (data) => logger.info(data.message))
amagiEvents.on('log:warn', (data) => logger.warn(data.message))
amagiEvents.on('log:error', (data) => logger.error(data.message))
amagiEvents.on('log:debug', (data) => logger.debug(data.message))
```

### 使用 winston [#使用-winston]

```ts
import { amagiEvents } from '@ikenxuan/amagi'
import winston from 'winston'

const logger = winston.createLogger({
  transports: [new winston.transports.Console()]
})

amagiEvents.on('log:info', (data) => logger.info(data.message))
amagiEvents.on('log:error', (data) => logger.error(data.message))
```

## API 监控示例 [#api-监控示例]

```ts
import { amagiEvents } from '@ikenxuan/amagi'

// 统计 API 调用
const stats = {
  success: 0,
  error: 0,
  totalDuration: 0
}

amagiEvents.on('api:success', (data) => {
  stats.success++
  stats.totalDuration += data.duration
  console.log(`✓ [${data.platform}] ${data.methodType} - ${data.duration}ms`)
})

amagiEvents.on('api:error', (data) => {
  stats.error++
  console.error(`✗ [${data.platform}] ${data.methodType} - ${data.errorMessage}`)
})

// 定期输出统计
setInterval(() => {
  const avgDuration = stats.success > 0 ? stats.totalDuration / stats.success : 0
  console.log(`统计: 成功 ${stats.success}, 失败 ${stats.error}, 平均耗时 ${avgDuration.toFixed(2)}ms`)
}, 60000)
```

## 一次性监听 [#一次性监听]

使用 `once` 方法注册只触发一次的监听器：

```ts
import { amagiEvents } from '@ikenxuan/amagi'
amagiEvents.once('api:success', (data) => {
  console.log('首次 API 调用成功')
})
```

## 移除监听器 [#移除监听器]

```ts
import { amagiEvents } from '@ikenxuan/amagi'
const handler = (data: { message: string }) => console.log(data.message)

// 注册
amagiEvents.on('log:info', handler)

// 移除
amagiEvents.off('log:info', handler)
```


# HTTP 服务 (https://ikenxuan.github.io/amagi/docs/v6/usage/guide/http-server)

> 使用 amagi 启动本地 HTTP 服务



# HTTP 服务 [#http-服务]

amagi 内置了 Express 服务器，可以一键启动本地 HTTP 服务。

## 启动服务 [#启动服务]

```ts
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; bili_jct=yyy',
    douyin: 'ttwid=...',
    kuaishou: 'did=...',
    xiaohongshu: 'a1=...'
  }
})

// 启动服务，默认端口 4567
client.startServer(4567)
```

启动后访问：

* 根路径 `/` 会重定向到 API 文档
* API 文档：[https://amagi.apifox.cn](https://amagi.apifox.cn)

## 路由结构 [#路由结构]

所有 API 路由挂载在 `/api/<platform>` 下：

* `/api/douyin/*` - 抖音相关接口
* `/api/bilibili/*` - B站相关接口
* `/api/kuaishou/*` - 快手相关接口
* `/api/xiaohongshu/*` - 小红书相关接口

## 平台路由 [#平台路由]

<Tabs items="['抖音', 'B站', '快手', '小红书']">
  <Tab value="抖音">
    \| 路由 | 说明 | 参数 | |------|------|------| | `GET /fetch_one_work` | 聚合解析 | `aweme_id` | | `GET /fetch_work_comments` | 评论数据
    \| `aweme_id`, `number?`, `cursor?` | | `GET /fetch_user_info` | 用户主页数据 | `sec_uid` | | `GET /fetch_user_post_videos` |
    用户视频列表 | `sec_uid` | | `GET /fetch_search_info` | 搜索数据 | `query`, `number?`, `search_id?` | | `GET /fetch_suggest_words` |
    热点词数据 | `query`, `number?` | | `GET /fetch_music_work` | 音乐数据 | `music_id` | | `GET /fetch_emoji_list` | Emoji 列表 | - | |
    `GET /fetch_emoji_pro_list` | 动态表情列表 | - | | `GET /fetch_user_live_videos` | 直播间信息 | `sec_uid` | | `GET
        /fetch_video_comment_replies` | 评论回复 | `aweme_id`, `comment_id`, `number?`, `cursor?` | | `GET /fetch_work_danmaku` | 弹幕数据 |
    `aweme_id`, `duration`, `start_time?`, `end_time?` |
  </Tab>

  <Tab value="B站">
    \| 路由 | 说明 | 参数 | |------|------|------| | `GET /fetch_one_video` | 视频数据 | `bvid` | | `GET /fetch_video_playurl` | 视频下载信息
    \| `avid`, `cid` | | `GET /fetch_work_comments` | 评论数据 | `oid`, `type`, `pn?`, `number?` | | `GET /fetch_user_profile` | 用户主页数据
    \| `host_mid` | | `GET /fetch_user_dynamic` | 用户动态列表 | `host_mid` | | `GET /fetch_emoji_list` | Emoji 列表 | - | | `GET
        /fetch_bangumi_video_info` | 番剧信息 | `ep_id` 或 `season_id` | | `GET /fetch_bangumi_video_playurl` | 番剧下载信息 | `cid`, `ep_id` |
    \| `GET /fetch_dynamic_info` | 动态详情 | `dynamic_id` | | `GET
        /fetch_live_room_detail` | 直播间信息 | `room_id` | | `GET /fetch_liveroom_def` | 直播间初始化 | `room_id` | | `GET /login_basic_info` |
    登录信息 | - | | `GET /new_login_qrcode` | 申请二维码 | - | | `GET /check_qrcode` | 二维码状态 | `qrcode_key` | | `GET
        /fetch_user_full_view` | UP主总播放量 | `host_mid` | | `GET /av_to_bv` | AV 转 BV | `avid` | | `GET /bv_to_av` | BV 转 AV | `bvid` |
  </Tab>

  <Tab value="快手">
    \| 路由 | 说明 | 参数 | |------|------|------| | `GET /fetch_one_work` | 视频数据 | `photoId` | | `GET /fetch_work_comments` | 评论数据 |
    `photoId` | | `GET /fetch_user_profile` | 用户主页数据 | `principalId` | | `GET /fetch_user_work_list` | 用户作品列表 | `principalId`,
    `pcursor?`, `count?` | | `GET /fetch_live_room_info` | 直播间信息 | `principalId` | | `GET /fetch_emoji_list` | Emoji 列表 | - |
  </Tab>

  <Tab value="小红书">
    \| 路由 | 说明 | 参数 | |------|------|------| | `GET /fetch_home_feed` | 首页推荐 | `cursor_score?`, `num?`, `refresh_type?`,
    `note_index?`, `category?`, `search_key?` | | `GET /fetch_one_note` | 笔记数据 | `note_id`, `xsec_token` | | `GET /fetch_note_comments`
    \| 评论数据 | `note_id`, `xsec_token`, `cursor?` | | `GET /fetch_user_profile` | 用户数据 | `user_id` | | `GET /fetch_user_notes` |
    用户笔记 | `user_id`, `cursor?`, `num?` | | `GET /fetch_emoji_list` | 表情列表 | - | | `GET /fetch_search_notes` | 搜索笔记 | `keyword`,
    `page?`, `page_size?`, `sort?`, `note_type?` |
  </Tab>
</Tabs>

## 响应格式 [#响应格式]

所有接口返回统一的 JSON 格式：

<Tabs items="['成功响应', '错误响应']">
  <Tab value="成功响应">
    ```json
    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": { ... },
      "requestPath": "/api/bilibili/fetch_one_video?bvid=BV1xx411c7mD"
    }
    ```
  </Tab>

  <Tab value="错误响应">
    ```json
    {
      "success": false,
      "code": 400,
      "message": "参数错误",
      "error": { 
        "name": "ZodError", 
        "details": [ ... ] 
      },
      "requestPath": "/api/douyin/fetch_work_comments?aweme_id=..."
    }
    ```
  </Tab>
</Tabs>

## 自定义路由 [#自定义路由]

你也可以单独注册平台路由到自己的 Express 应用：

```ts
import express from '@ikenxuan/amagi/express'
import { registerBilibiliRoutes, registerDouyinRoutes } from '@ikenxuan/amagi'

const app = express()

// 注册路由
app.use('/api/bilibili', registerBilibiliRoutes('your_cookie', {}))
app.use('/api/douyin', registerDouyinRoutes('your_cookie', {}))

app.listen(3000)
```


# SDK 使用指南 (https://ikenxuan.github.io/amagi/docs/v6/usage/guide/sdk)

> 详细了解如何使用 amagi SDK



# SDK 使用指南 [#sdk-使用指南]

amagi 提供了灵活的 SDK 调用方式，支持多种使用模式。

## 客户端实例模式（推荐） [#客户端实例模式推荐]

创建客户端实例后，可以直接调用各平台的 fetcher API，无需重复传递 cookie。

```ts
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'your_bilibili_cookie',
    douyin: 'your_douyin_cookie',
    kuaishou: 'your_kuaishou_cookie',
    xiaohongshu: 'your_xiaohongshu_cookie'
  }
})

// 使用 fetcher API
const video = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
const work = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '123456789' })
```

## 静态 Fetcher 模式 [#静态-fetcher-模式]

如果不想创建实例，可以使用静态 fetcher，但需要手动传递 cookie：

```ts
import amagi from '@ikenxuan/amagi'

const result = await amagi.bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }, 'SESSDATA=xxx; bili_jct=yyy')
```

## 工厂函数模式 [#工厂函数模式]

使用 `createBound*Fetcher` 工厂函数创建绑定 cookie 的 fetcher：

```ts
import amagi from '@ikenxuan/amagi'

// 创建绑定 cookie 的 fetcher
const bilibiliFetcher = amagi.createBoundBilibiliFetcher('your_cookie')
const douyinFetcher = amagi.createBoundDouyinFetcher('your_cookie')

// 调用时无需传递 cookie
const video = await bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
```

## 统一响应格式 [#统一响应格式]

所有 API 返回统一的 `Result<T>` 结构：

```ts
type SuccessResult<T> = {
  success: true
  code: number
  message: string
  data: T
}

type ErrorResult = {
  success: false
  code: number
  message: string
  error: any
}

type Result<T> = SuccessResult<T> | ErrorResult
```

### 使用示例 [#使用示例]

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

if (result.success) {
  // 成功处理
  console.log(result.data)
} else {
  // 错误处理
  console.error(result.message, result.error)
}
```

## 请求配置 [#请求配置]

可以在创建客户端时传递自定义请求配置：

```ts
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'your_cookie',
    douyin: 'your_cookie',
    kuaishou: 'your_cookie',
    xiaohongshu: 'your_cookie'
  },
  request: {
    headers: {
      'User-Agent': 'Mozilla/5.0 ...'
    },
    timeout: 10000,
    proxy: {
      host: '127.0.0.1',
      port: 7890
    }
  }
})
```

## 平台模块结构 [#平台模块结构]

每个平台模块包含以下内容：

<Tabs items="['B站', '抖音', '快手', '小红书']">
  <Tab value="B站">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // fetcher - 数据获取器
    client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx' })
    client.bilibili.fetcher.fetchComments({ oid: '123', type: 1 })
    client.bilibili.fetcher.fetchUserCard({ host_mid: 123456 })

    // sign - 签名算法
    client.bilibili.sign.av2bv(170001)
    client.bilibili.sign.bv2av('BV1xx411c7mD')

    // danmaku - 弹幕解析
    // client.bilibili.danmaku.parseDmSegMobileReply(buffer)

    ```
  </Tab>

  <Tab value="抖音">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // fetcher - 数据获取器
    client.douyin.fetcher.fetchVideoWork({ aweme_id: '123' })
    client.douyin.fetcher.parseWork({ aweme_id: '123' })
    client.douyin.fetcher.fetchWorkComments({ aweme_id: '123' })

    // sign - 签名算法
    client.douyin.sign.Mstoken(128)
    // client.douyin.sign.AB(url, ua)
    // client.douyin.sign.XB(url, ua)
    ```
  </Tab>

  <Tab value="快手">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // fetcher - 数据获取器
    client.kuaishou.fetcher.fetchVideoWork({ photoId: '3xq123' })
    client.kuaishou.fetcher.fetchWorkComments({ photoId: '3xq123' })
    client.kuaishou.fetcher.fetchUserProfile({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchUserWorkList({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchLiveRoomInfo({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchEmojiList({})

    // sign - 签名算法
    // client.kuaishou.sign.signLiveApiRequest(request, cookie)

    ```
  </Tab>

  <Tab value="小红书">
    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // fetcher - 数据获取器
    client.xiaohongshu.fetcher.fetchNoteDetail({ note_id: '123', xsec_token: 'xxx' })
    client.xiaohongshu.fetcher.fetchNoteComments({ note_id: '123', xsec_token: 'xxx' })
    client.xiaohongshu.fetcher.fetchUserProfile({ user_id: '123' })

    // sign - 签名算法
    // client.xiaohongshu.sign.generateXSGet(path, a1Cookie)
    ```
  </Tab>
</Tabs>


# 类型模式 (https://ikenxuan.github.io/amagi/docs/v6/usage/guide/type-mode)

> 了解 amagi 的类型模式系统



# 类型模式 [#类型模式]

amagi 提供了两种类型模式，让你可以在类型安全和灵活性之间做出选择。

## 类型模式说明 [#类型模式说明]

<Tabs items="['loose 模式 (默认)', 'strict 模式']">
  <Tab value="loose 模式 (默认)">
    返回 `any` 类型，容错性更强，适合快速开发或处理未知响应结构。

    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    const result = await client.bilibili.fetcher.fetchVideoInfo({
      bvid: 'BV1xx411c7mD'
    })

    result.data
    ```
  </Tab>

  <Tab value="strict 模式">
    返回严格类型定义，提供完整的类型提示和编译时检查。

    ```ts
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    const result = await client.bilibili.fetcher.fetchVideoInfo({
      bvid: 'BV1xx411c7mD',
      typeMode: 'strict'
    })

    result.data
    ```
  </Tab>
</Tabs>

## 使用场景 [#使用场景]

### 推荐使用 strict 模式 [#推荐使用-strict-模式]

* 需要完整的 IDE 类型提示
* 进行类型安全的数据处理
* 编写生产级代码
* 需要编译时类型检查

### 推荐使用 loose 模式 [#推荐使用-loose-模式]

* 快速原型开发
* 处理可能变化的 API 响应
* 需要访问未在类型定义中声明的字段
* 调试和探索 API

<Callout type="info">
  类型定义时间：2025-02-02

  严格类型基于接口响应定义，随时间推移可能缺少平台新增的字段。如果需要访问新字段，可以使用 loose 模式或进行类型断言。
</Callout>

## 示例 [#示例]

### B站视频信息 [#b站视频信息]

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const video = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD',
  typeMode: 'strict'
})

if (video.success) {
  // 完整类型提示
  console.log(video.data.data.desc)
  console.log(video.data.data.owner.name)
  console.log(video.data.data.stat.view)
}
```

### 抖音搜索 [#抖音搜索]

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// 搜索用户
const userSearch = await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'user',
  typeMode: 'strict'
})

// 搜索视频
const videoSearch = await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'video',
  typeMode: 'strict'
})
```

## 类型断言 [#类型断言]

如果需要在 strict 模式下访问未定义的字段：

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
const result = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD',
  typeMode: 'strict'
})

if (result.success) {
  // 使用类型断言访问未定义字段
  const newField = (result.data as any).newField
}
```


# 工具集 (https://ikenxuan.github.io/amagi/docs/v6/usage/guide/utilities)

> amagi 提供的各平台工具函数



# 工具集 [#工具集]

amagi 为各平台提供了丰富的工具函数，包括签名算法、URL 拼接器、格式转换等。

## 平台工具集 [#平台工具集]

<Tabs items="['B站', '抖音', '快手', '小红书']">
  <Tab value="B站">
    ```ts
    import { bilibiliUtils } from '@ikenxuan/amagi'

    // AV/BV 转换
    const bv = bilibiliUtils.sign.av2bv(170001)
    const av = bilibiliUtils.sign.bv2av('BV17x411w7KC')
    ```

    ### 签名算法 [#签名算法]

    ```ts
    import { bilibiliUtils } from '@ikenxuan/amagi'
    // WBI 签名
    const signedUrl = await bilibiliUtils.sign.wbi_sign(
      'https://api.bilibili.com/x/web-interface/view?bvid=BV1xx',
      'your_cookie'
    )
    ```

    ### 弹幕解析 [#弹幕解析]

    ```ts
    import { bilibiliUtils } from '@ikenxuan/amagi'
    // 解析 protobuf 格式的弹幕数据
    const danmakuList = bilibiliUtils.danmaku.parseDmSegMobileReply(buffer)
    ```
  </Tab>

  <Tab value="抖音">
    ```ts
    import { douyinUtils } from '@ikenxuan/amagi'

    // 生成 msToken
    const msToken = douyinUtils.sign.Mstoken(128)
    ```

    ### 签名算法 [#签名算法-1]

    ```ts
    import { douyinUtils } from '@ikenxuan/amagi'
    // 生成 a_bogus 签名
    const aBogus = douyinUtils.sign.AB(url, userAgent)

    // 生成 X-Bogus 签名
    const xBogus = douyinUtils.sign.XB(url, userAgent)

    // 验证指纹管理器
    const verifyFp = douyinUtils.sign.VerifyFpManager()
    ```
  </Tab>

  <Tab value="快手">
    ```ts
    import { kuaishouUtils } from '@ikenxuan/amagi'

    // 获取结构化请求描述对象
    const request = kuaishouUtils.kuaishouApiUrls.videoWork({
    photoId: '3xqxxxxxx'
    })
    ```

    ### 签名算法 [#签名算法-2]

    ```ts
    import { kuaishouUtils } from '@ikenxuan/amagi'

    const request = kuaishouUtils.kuaishouApiUrls.userInfoById({
      principalId: 'KPL704668133'
    })

    const signed = kuaishouUtils.sign.signLiveApiRequest(
      request,
      'kwfv1=your_cookie_value'
    )
    ```
  </Tab>

  <Tab value="小红书">
    ```ts
    import { xiaohongshuUtils } from '@ikenxuan/amagi'

    // 生成 X-T 时间戳
    const xt = xiaohongshuUtils.sign.generateXT()

    // 生成 X-B3-Traceid
    const traceid = xiaohongshuUtils.sign.generateXB3Traceid()

    // 从 Cookie 中提取 a1
    const a1 = xiaohongshuUtils.sign.extractA1FromCookie('a1=xxx; webId=yyy')

    // 生成搜索 ID
    const searchId = xiaohongshuUtils.sign.getSearchId()
    ```

    ### X-S 签名 [#x-s-签名]

    ```ts
    import { xiaohongshuUtils } from '@ikenxuan/amagi'
    // 生成 X-S 签名 (GET 请求)
    const xs = xiaohongshuUtils.sign.generateXSGet(path, a1Cookie, clientType, params)

    // 生成 X-S 签名 (POST 请求)
    const xs = xiaohongshuUtils.sign.generateXSPost(path, a1Cookie, clientType, body)

    // 通用 X-S 签名生成
    const xs = xiaohongshuUtils.sign.generateXS(url, body, ua, method, a1Cookie)

    // 生成 X-S-Common
    const xsCommon = xiaohongshuUtils.sign.generateXSCommon(length)
    ```
  </Tab>
</Tabs>


# 快速开始 (https://ikenxuan.github.io/amagi/docs/v6/usage)

> 抖音、B站、快手、小红书 Web 端相关数据接口的 Node.js 封装与服务



<Callout type="info">
  本文档适用于 v6 正式版。如需查看旧版文档，请参考 [v5 文档](https://github.com/ikenxuan/amagi/tree/e82440b04d599089fb743c418455a281ae57884b)
</Callout>

<Callout>
  **本项目专为 [karin-plugin-kkk](https://github.com/ikenxuan/karin-plugin-kkk) 服务**

  amagi 作为 karin-plugin-kkk 的核心数据层，以 Git 子模块方式提供多平台数据获取能力。功能迭代主要围绕 karin-plugin-kkk 的业务需求进行。

  如需其他接口支持，请参考[开发文档](/docs/v6/dev)自行封装，或提交 Pull Request 贡献代码。
</Callout>

<Accordions>
  <Accordion title="致谢">
    反爬参数部分参考了以下项目的实现： - [SocialSisterYi/bilibili-API-collect](https://github.com/SocialSisterYi/bilibili-API-collect) -
    [NearHuiwen/TiktokDouyinCrawler](https://github.com/NearHuiwen/TiktokDouyinCrawler) -
    [Evil0ctal/Douyin\_TikTok\_Download\_API](https://github.com/Evil0ctal/Douyin_TikTok_Download_API) -
    [Johnserf-Seed/f2](https://github.com/Johnserf-Seed/f2) - [ikenxuan/xhshow-ts](https://github.com/ikenxuan/xhshow-ts)
  </Accordion>
</Accordions>

## 特性 [#特性]

* **多平台支持**：抖音、B站、快手、小红书的主流数据接口
* **两种使用姿势**：
  * 直接调用：通过 SDK 获取数据，支持绑定 Cookie
  * 本地服务：一键启动 Express 服务，REST 风格路由
* **参数校验**：基于 Zod，按方法类型校验必填与可选参数
* **统一响应**：约定化 `Result<T>` 返回结构，含 `success`/`code`/`message`/`data`
* **类型模式**：`strict` 与 `loose` 可选，开发友好与容错可控
* **工具集齐全**：签名算法、URL 拼接器、AV/BV 转换等常用工具
* **双模块输出**：同时支持 ESM 与 CJS 引入

## 快速开始 [#快速开始]

<Cards>
  <Card title="安装" href="/docs/v6/usage/installation" />

  <Card title="快速上手" href="/docs/v6/usage/getting-started" />

  <Card title="使用指南" href="/docs/v6/usage/guide/sdk" />

  <Card title="API 参考" href="/docs/v6/usage/api/bilibili" />
</Cards>

## 相关链接 [#相关链接]

* [GitHub 仓库](https://github.com/ikenxuan/amagi)
* [API 文档 (Apifox)](https://amagi.apifox.cn)
* [类型参考（Typescript API）](/docs/v7/usage/api/types)
* [NPM 包](https://www.npmjs.com/package/@ikenxuan/amagi)

<Callout type="info">
  本文档由 AI 辅助生成，可能存在描述不准确、示例代码过时或遗漏关键信息等问题。如发现错误或疑问，请以实际代码实现为准，或提交
  [Issue](https://github.com/ikenxuan/amagi/issues) 反馈。
</Callout>


# 安装 (https://ikenxuan.github.io/amagi/docs/v6/usage/installation)

> 安装 @ikenxuan/amagi



# 安装 [#安装]

## 使用包管理器安装 [#使用包管理器安装]

<Tabs items="['pnpm', 'npm', 'yarn', 'bun']">
  <Tab value="pnpm">
    `bash pnpm add @ikenxuan/amagi `
  </Tab>

  <Tab value="npm">
    `bash npm install @ikenxuan/amagi `
  </Tab>

  <Tab value="yarn">
    `bash yarn add @ikenxuan/amagi `
  </Tab>

  <Tab value="bun">
    `bash bun add @ikenxuan/amagi `
  </Tab>
</Tabs>

## 系统要求 [#系统要求]

* Node.js >= 18.0.0
* 支持 ESM 和 CJS 两种模块系统

## 模块导入 [#模块导入]

<Tabs items="['ESM (推荐)', 'CommonJS']">
  <Tab value="ESM (推荐)">
    `ts import amagi from '@ikenxuan/amagi' // 或使用别名 import Client from '@ikenxuan/amagi' `
  </Tab>

  <Tab value="CommonJS">
    `js const amagi = require('@ikenxuan/amagi').default `
  </Tab>
</Tabs>

## 子路径导出 [#子路径导出]

除了主入口，amagi 还提供了一些子路径导出：

```ts
// Express 相关
import express from '@ikenxuan/amagi/express'

// Axios 实例
import axios from '@ikenxuan/amagi/axios'

// Chalk 终端颜色
import chalk from '@ikenxuan/amagi/chalk'
```

<Callout type="info">
  v6 版本已移除对 log4js 的依赖，改用事件驱动架构。你可以通过监听事件来实现自定义日志。
</Callout>


# v6 迁移指南 (https://ikenxuan.github.io/amagi/docs/v6/usage/migration-v6)

> 从 v5.x 升级到 v6.x 的迁移指南



# v6 迁移指南 [#v6-迁移指南]

本文档帮助你从 amagi v5.x 升级到 v6.x。

<Callout type="info">
  v6 正式版已发布。自 v6.5.0 起，v6.0 中标记为废弃的兼容 API 已彻底移除。
</Callout>

## 核心变更 [#核心变更]

v6 是一次重大重构，主要变更：

1. **移除 `getXxxData` API** - 所有 `getDouyinData`、`getBilibiliData` 等方法已删除（v6.0 \~ v6.4 调用会抛出错误，v6.5.0 起彻底移除）
2. **统一使用 Fetcher API** - 通过 `client.平台.fetcher.方法名()` 调用
3. **日志系统重构** - 移除 `log4js`，改用事件驱动架构
4. **方法名英文化** - 所有 API 方法名改为英文

## 安装 [#安装]

```bash
npm install @ikenxuan/amagi
```

## API 调用方式迁移 [#api-调用方式迁移]

### v5 用法 (已移除) [#v5-用法-已移除]

```ts
// ❌ v6 中这些 API 已移除，无法导入
import { getDouyinData, getBilibiliData } from '@ikenxuan/amagi'

await getDouyinData('视频作品数据', { aweme_id: '123' }, cookie)
await getBilibiliData('单个视频作品数据', { bvid: 'BV1xx' }, cookie)
```

### v6 用法 [#v6-用法]

<Tabs items="['客户端实例 (推荐)', '静态 Fetcher', 'createBound 工厂']">
  <Tab value="客户端实例 (推荐)">
    ```ts
    import amagi from '@ikenxuan/amagi'

    const client = amagi({
    cookies: {
    bilibili: 'SESSDATA=xxx; ...',
    douyin: 'ttwid=...; ...',
    kuaishou: 'did=...; ...',
    xiaohongshu: 'a1=...; ...',
    }
    })

    // 无需再传递 cookie
    const video = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
    const work = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '123' })

    ```
  </Tab>

  <Tab value="静态 Fetcher">
    ```ts
    import amagi from '@ikenxuan/amagi'

    // 需要手动传递 cookie
    const result = await amagi.bilibiliFetcher.fetchVideoInfo(
      { bvid: 'BV1xx411c7mD' },
      'SESSDATA=xxx; ...'
    )
    ```
  </Tab>

  <Tab value="createBound 工厂">
    ```ts
    import amagi from '@ikenxuan/amagi'

    // 创建绑定 cookie 的 fetcher
    const fetcher = amagi.createBoundBilibiliFetcher('SESSDATA=xxx; ...')
    const result = await fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

    ```
  </Tab>
</Tabs>

## 日志系统迁移 [#日志系统迁移]

### v5 用法 (已移除) [#v5-用法-已移除-1]

```ts
// ❌ v6 中已移除
import { logger, initLogger } from '@ikenxuan/amagi'
initLogger()
logger.info('消息')
```

### v6 用法 [#v6-用法-1]

```ts
import { amagiEvents } from '@ikenxuan/amagi'

// 监听日志事件
amagiEvents.on('log:info', (data) => console.log(data.message))
amagiEvents.on('log:error', (data) => console.error(data.message))

// 监听 API 事件
amagiEvents.on('api:success', (data) => {
  console.log(`[${data.platform}] ${data.methodType} 成功`)
})
```

详见 [事件系统](/docs/v6/usage/guide/events)。

## 方法名对照表 [#方法名对照表]

<Accordions>
  <Accordion title="B站">
    \| v5 中文方法名 | v6 Fetcher 方法 | |--------------|-----------------| | `单个视频作品数据` | `fetchVideoInfo` | |
    `单个视频下载信息数据` | `fetchVideoStreamUrl` | | `实时弹幕` | `fetchVideoDanmaku` | | `评论数据` | `fetchComments` | |
    `指定评论的回复` | `fetchCommentReplies` | | `用户主页数据` | `fetchUserCard` | | `用户主页动态列表数据` | `fetchUserDynamicList` | |
    `用户空间详细信息` | `fetchUserSpaceInfo` | | `获取UP主总播放量` | `fetchUploaderTotalViews` | | `动态详情数据` | `fetchDynamicDetail` |
    \| `番剧基本信息数据` | `fetchBangumiInfo` | | `番剧下载信息数据` | `fetchBangumiStreamUrl` | |
    `直播间信息` | `fetchLiveRoomInfo` | | `直播间初始化信息` | `fetchLiveRoomInitInfo` | | `登录基本信息` | `fetchLoginStatus` | |
    `申请二维码` | `requestLoginQrcode` | | `二维码状态` | `checkQrcodeStatus` | | `AV转BV` | `convertAvToBv` | | `BV转AV` | `convertBvToAv`
    \| | `Emoji数据` | `fetchEmojiList` |
  </Accordion>

  <Accordion title="抖音">
    \| v5 中文方法名 | v6 Fetcher 方法 | |--------------|-----------------| | `视频作品数据` | `fetchVideoWork` | | `图集作品数据` |
    `fetchImageAlbumWork` | | `合辑作品数据` | `fetchSlidesWork` | | `文字作品数据` | `fetchTextWork` | | `聚合解析` | `parseWork` | |
    `评论数据` | `fetchWorkComments` | | `指定评论回复数据` | `fetchCommentReplies` | | `用户主页数据` | `fetchUserProfile` | |
    `用户主页视频列表数据` | `fetchUserVideoList` | | `搜索数据` | `searchContent` | | `热点词数据` | `fetchSuggestWords` | | `音乐数据` |
    `fetchMusicInfo` | | `直播间信息数据` | `fetchLiveRoomInfo` | | `弹幕数据` | `fetchDanmakuList` | | `Emoji数据` | `fetchEmojiList` | |
    `动态表情数据` | `fetchDynamicEmojiList` |
  </Accordion>

  <Accordion title="快手">
    \| v5 中文方法名 | v6 Fetcher 方法 | |--------------|-----------------| | `单个视频作品数据` | `fetchVideoWork` | | `评论数据` |
    `fetchWorkComments` | | `用户主页数据` | `fetchUserProfile` | | `用户作品列表数据` | `fetchUserWorkList` | | `直播间信息数据` |
    `fetchLiveRoomInfo` | | `Emoji数据` | `fetchEmojiList` |
  </Accordion>

  <Accordion title="小红书">
    \| v5 中文方法名 | v6 Fetcher 方法 | |--------------|-----------------| | `首页推荐数据` | `fetchHomeFeed` | | `单个笔记数据` |
    `fetchNoteDetail` | | `评论数据` | `fetchNoteComments` | | `用户数据` | `fetchUserProfile` | | `用户笔记数据` | `fetchUserNoteList` | |
    `搜索笔记` | `searchNotes` | | `表情列表` | `fetchEmojiList` |
  </Accordion>
</Accordions>

## 参数变更 [#参数变更]

### 抖音搜索类型 [#抖音搜索类型]

`type` 参数从中文改为英文：

```ts
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// v5: type: '用户' | '视频' | '综合'
// v6: type: 'user' | 'video' | 'general'

await client.douyin.fetcher.searchContent({
  query: '关键词',
  type: 'user' // 而不是 '用户'
})
```

## 迁移示例 [#迁移示例]

### 获取视频信息 [#获取视频信息]

```ts
import amagi from '@ikenxuan/amagi'

// v5 ❌
// const data = await getBilibiliData('单个视频作品数据', { bvid: 'BV1xx' }, cookie)

// v6 ✅
const client = amagi({ cookies: { bilibili: 'SESSDATA=xxx', douyin: '', kuaishou: '', xiaohongshu: '' } })
const data = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
```

### 获取评论 [#获取评论]

```ts
import amagi from '@ikenxuan/amagi'

// v5 ❌
// const data = await getDouyinData('评论数据', { aweme_id: '123', number: 20 }, cookie)

// v6 ✅
const client = amagi({ cookies: { bilibili: '', douyin: 'ttwid=xxx', kuaishou: '', xiaohongshu: '' } })
const data = await client.douyin.fetcher.fetchWorkComments({
  aweme_id: '123',
  number: 20
})
```

### 自定义日志 [#自定义日志]

```ts
import { amagiEvents } from '@ikenxuan/amagi'
import pino from 'pino'

const logger = pino()

// 将 amagi 日志转发到 pino
amagiEvents.on('log:info', (data) => logger.info(data.message))
amagiEvents.on('log:warn', (data) => logger.warn(data.message))
amagiEvents.on('log:error', (data) => logger.error(data.message))
```

## 常见问题 [#常见问题]

### Q: 调用 getXxxData 报错怎么办？ [#q-调用-getxxxdata-报错怎么办]

这些方法已完全移除。请按照上面的对照表，将调用改为对应的 fetcher 方法。

### Q: 如何监控 API 调用性能？ [#q-如何监控-api-调用性能]

```ts
import { amagiEvents } from '@ikenxuan/amagi'

amagiEvents.on('api:success', (data) => {
  console.log(`[${data.platform}] ${data.methodType} 耗时 ${data.duration}ms`)
})

amagiEvents.on('api:error', (data) => {
  console.error(`[${data.platform}] ${data.methodType} 失败: ${data.errorMessage}`)
})
```

### Q: client.平台.api 和 client.平台.fetcher 有什么区别？ [#q-client平台api-和-client平台fetcher-有什么区别]

`api` 已在 v6.5.0 中移除，请统一使用 `fetcher`。`fetcher` 是 v6 的调用方式。


# Agent Skills (https://ikenxuan.github.io/amagi/docs/v7/ai)

> 让 AI 编码助手直接读取 amagi 文档与调用接口



> 让 AI 编码助手读得懂 amagi 的 v7 文档，写出来的代码不用你回头改。

amagi 为 Claude Code、Cursor、Cline 等 AI 编码助手提供两条接入通路：一条是把文档喂给它，
另一条是把「查文档」这件事交给它。两条可以同时用。

<DocsCategory />

## Agent Skills [#agent-skills]

技能包给助手一份「amagi v7 该怎么用」的知识，以及一个能随时取回最新文档的能力。
装一次，之后正常提问就行 —— 助手会自己判断什么时候该去查、该查哪一页。

### 安装 [#安装]

```bash
npx skills add ikenxuan/amagi
```

支持 Claude Code、Cursor、OpenCode 等。

### 使用方法 [#使用方法]

装完即生效，助手会自动发现这两个技能。也可以直接点名触发：

```
/amagi
/migration-to-v7
```

几个典型的问法：

* 用 amagi 写一个抖音作品解析的脚本
* `AmagiResult` 的失败分支怎么读？`error.kind` 有哪些值？
* 我想给 amagi 加一个 B 站的新接口，要改哪些文件？
* 帮我看看这段代码里的 amagi 用法对不对
* 把 `/migration-to-v7` 用在这个项目上，从 v6 升到 v7

问的时候不用提「文档」或「查资料」—— 助手会自己判断要不要去取原文。

### 包含的内容 [#包含的内容]

| 技能                | 覆盖                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `amagi`           | v7 的安装与建实例、按 `AmagiResult` 信封读返回值、四个平台的 SDK 方法、HTTP 端点参考、`startServer` 本地服务、实例级事件总线、各平台工具函数；给贡献者的分层架构、新增接口流程、提交与 PR 规范 |
| `migration-to-v7` | v6 → v7 的完整迁移矩阵、四处必改、`/compat` 兼容层怎么用，以及事件系统与响应类型这两处最容易漏的变化                                                            |

### 结构 [#结构]

```
skills/
├── amagi/
│   ├── SKILL.md          技能说明，助手读这个决定何时启用
│   └── scripts/          取文档的脚本（零依赖，Node 18+）
└── migration-to-v7/
    ├── SKILL.md
    └── scripts/
```

<Callout type="info">
  技能里**不存放文档副本**，每次都现取站上的 Markdown 源文件。所以你不会遇到「技能里的说法
  比文档站旧一个版本」这种事。
</Callout>

### 相关文档 [#相关文档]

* [Agent Skills 规范](https://agentskills.io) —— 技能包的格式定义


# LLMs.txt (https://ikenxuan.github.io/amagi/docs/v7/ai/llms-txt)

> 让 AI 助手理解 Amagi 文档



> 让 Claude、Cursor、Windsurf 等 AI 助手能够理解和使用 Amagi 文档

我们提供 [LLMs.txt](https://llmstxt.org/) 文件，让 AI 编码助手能够访问 Amagi 文档。

## 可用文件 [#可用文件]

**核心文档：**

* [/llms.txt](/llms.txt) — 快速参考索引
* [/llms-full.txt](/llms-full.txt) — 完整的 Amagi 文档

## 集成方式 [#集成方式]

### Cursor [#cursor]

使用 `@Docs` 功能：

```
@Docs https://ikenxuan.github.io/amagi/llms-full.txt
```

或在聊天中直接引用：

```
使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

[了解更多](https://docs.cursor.com/context/@-symbols/@-docs)

### Cline (VS Code) [#cline-vs-code]

在提示中直接引用：

```
参考 Amagi 文档：https://ikenxuan.github.io/amagi/llms-full.txt
```

[了解更多](https://cline.bot)

### Continue (VS Code) [#continue-vs-code]

在 Continue 配置中添加自定义文档：

1. 打开配置：`Ctrl+Shift+P` → "Continue: Add new custom docs"
2. 添加 URL：`https://ikenxuan.github.io/amagi/llms.txt`
3. 在聊天中使用 `@docs` 并选择 amagi

或直接在提示中引用文档 URL。

[了解更多](https://continue.dev/docs)

### Claude Code [#claude-code]

告诉 Claude 引用文档：

```
使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

或添加到项目的 `.claude` 文件以自动加载。

### Windsurf [#windsurf]

添加到 `.windsurfrules` 文件：

```
#docs https://ikenxuan.github.io/amagi/llms-full.txt
```

[了解更多](https://docs.codeium.com/windsurf/memories#memories-and-rules)

### JetBrains AI Assistant [#jetbrains-ai-assistant]

JetBrains IDE（IntelliJ IDEA、PyCharm、WebStorm 等）可以通过 AI Assistant 使用文档：

1. 在 AI Assistant 聊天中直接引用：

   ```
   参考文档：https://ikenxuan.github.io/amagi/llms-full.txt
   ```

[了解更多](https://www.jetbrains.com/help/ai-assistant/)

### GitHub Copilot (VS Code) [#github-copilot-vs-code]

在 Copilot Chat 中引用文档：

```
@workspace 使用 Amagi 文档：https://ikenxuan.github.io/amagi/llms.txt
```

### 其他 AI 工具 [#其他-ai-工具]

大多数 AI 助手都可以通过 URL 引用文档。只需提供：

```
https://ikenxuan.github.io/amagi/llms.txt
```

<Callout type="info">
  对于完整文档内容，使用 

  `/llms-full.txt`
</Callout>

## 使用示例 [#使用示例]

配置完成后，你可以向 AI 助手提问：

* "如何使用 Amagi SDK 获取 Bilibili 视频信息？"
* "Amagi 支持哪些平台的 API？"
* "如何配置 HTTP Server 模式？"
* "事件系统如何使用？"
* "如何处理 Douyin 的评论数据？"

AI 助手会基于 LLMs.txt 文件中的文档内容给出准确的回答。

## 获取单个页面的 Markdown [#获取单个页面的-markdown]

你可以通过在任何文档页面 URL 后添加 `.mdx` 来获取该页面的 Markdown 内容：

```
https://ikenxuan.github.io/amagi/docs/v7/usage/getting-started.mdx
https://ikenxuan.github.io/amagi/docs/v7/usage/guide/sdk.mdx
https://ikenxuan.github.io/amagi/docs/v7/usage/api/sdk/bilibili.mdx
```

这对于需要特定页面内容的 AI 工具特别有用。

## 内容协商 [#内容协商]

某些 AI 工具会发送 `Accept: text/markdown` 请求头。我们的文档站点会自动识别并返回 Markdown 格式的内容，而不是 HTML 页面。

## 贡献 [#贡献]

发现 AI 生成的代码有问题？帮助我们改进 LLMs.txt 文件，请访问 [GitHub](https://github.com/ikenxuan/amagi)。

## 相关链接 [#相关链接]

* [LLMs.txt 规范](https://llmstxt.org/)
* [GitHub 仓库](https://github.com/ikenxuan/amagi)


# v7.0.0-beta.1 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.1)

> 2026-09-17 发布的 v7 首个公开版本 —— 端点注册表驱动的重构



v7 不是一次接口增补，而是一次**内部重构**：把「一个接口」从散落在 fetcher、路由、
参数校验、类型四处的写法，收成**一份声明**。所以下面先列必须改的，再列这套结构换来了什么。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 仍是 6.x 稳定线 —— 不带标签装到的还是 6.6.0。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 破坏性变更 [#破坏性变更]

四条必改，逐条的前后对照与真实编译错误见[迁移指南](/docs/v7/usage/migration-v7)：

| 改什么     | v6                             | v7                                                  |
| ------- | ------------------------------ | --------------------------------------------------- |
| 默认导出的门面 | `amagi()` 返回 v6 client         | 返回 v7 门面；`createAmagiClient` 降级成它的 `@deprecated` 别名 |
| 事件总线    | 全局单例，负载是平铺字段                   | 实例级 `client.on` / `once` / `events`，负载恒带 `meta`     |
| 错误分支    | 顶层 `code` + `error.amagiError` | `AmagiResult<T>` 判别联合，`success` 是唯一判别键              |
| 类型模式    | `typeMode` 三档                  | 已删，始终是端点声明的具体类型                                     |

**成功分支零改动**：`if (r.success) use(r.data)` 在 v6 / v7 都成立。一处都不想改的，
把 import 换成 `@ikenxuan/amagi/compat` 即可整体切回 v6 语义（含顶层 `code`）。

## 结构性变化 [#结构性变化]

* **端点注册表**：一个接口一份 `defineEndpoint` 声明，参数类型、运行时校验、HTTP 路由、
  fetcher 方法与文档页全部由它派生 —— 加接口从「改四处」变成「加一个文件」。
* **事件总线改为实例级**：负载里的 `meta` 带 `requestId` / `clientId` / 耗时 / 重试与翻页账本，
  多实例并发时事件终于能归因。
* **参数校验不再抛**：校验失败返回失败信封，调用方的错误分支只需写一处。
* **响应类型由真实样本派生**：字段级精确，平台新增字段不算破坏性变更。
* **签名工具独立入口**：`@ikenxuan/amagi/signing` 是纯函数，浏览器里也能跑，
  用来确认签名实现没有过期。
* **双模块输出**：ESM 与 CJS 同时可用。

## 接口变更 [#接口变更]

以下来自 v6.6.0 之后合入的抖音改动，与重构一起发在这一版。

### 新增：四条免鉴权接口 [#新增四条免鉴权接口]

不需要 cookie、不算签名、不参与风控策略，走的仍是同一条请求链路，因此事件、超时与错误信封
与其它接口一致：

| methodType            | 说明                              |
| --------------------- | ------------------------------- |
| `guestUserInfo`       | 抖音号转 `sec_uid`，目前**唯一免签名**的途径   |
| `guestMusicInfo`      | 音乐信息                            |
| `guestMusicAwemeList` | 该音乐下的作品列表                       |
| `emojiResourceMeta`   | 表情资源包（带 `need_all` 时含限时 / 联名表情） |

### 修复：`webid` 与会话对不上导致的静默空响应 [#修复webid-与会话对不上导致的静默空响应]

此前各个 URL 里写死了 13 处 `webid`、6 个不同值。抖音拿 `webid` 与 cookie 的会话交叉校验，
**对不上就回 HTTP 200 + 空 body** —— 不是 403、不是业务码，于是排查方向被带偏到 cookie 上，
而 cookie 其实是好的。现在改为读响应头下发、按 `ttwid` 分键缓存；冷启动没有缓存时**不传**
（不传安全，传错致命）。

### 修复：`x-secsdk-web-signature` 未实现 [#修复x-secsdk-web-signature-未实现]

`music/detail` 此前完全打不通，缺的就是这个由页面内 secsdk JS 现算的签名。
`douyinSign.SecSdk()` 已在 Node 侧纯算出来：它**改写整条 URL**而不是回一个参数值，
且只对策略表内的 path 生效，其余原样返回。

### 修复：抖音分支的失败信封恒为 `500` [#修复抖音分支的失败信封恒为-500]

风控拦截、cookie 失效、网络错误、内容过滤此前全变成同一个 `500`，不带任何信息。
现在带上真实的 `status_code` 与文案。

## 新增：自定义请求模块 [#新增自定义请求模块]

四个平台各多了一个 `client.<平台>.request`：一个**真的 axios 实例**，但请求交给 amagi 已有的执行管线 ——
签名、实例 ck、judge、退避重试、事件与 trace 全都自动附加，因此用它请求 amagi 尚未收录的接口，这些处理也不会缺席。

* **两条轨**：`request.<动词>` 返回 `AmagiResult` 信封且不抛；`request.axios.<动词>` 返回 `AxiosResponse`，
  失败时 reject `AxiosError`（失败信封在 `err.response.data` 上）。两条轨共用同一实例与同一份
  `defaults` / `interceptors`。
* **调用约定与 axios 原生不同**：五个动词统一是 `(url, config)`，&#x2A;*请求体放 `config.data`** ——
  即 `request.post(url, { data: { a: 1 } })`，而不是 `request.post(url, { a: 1 })`。axios 那套三参写法
  在这里会把载荷当成配置，静默丢掉业务字段。
* **单次选项走 `amagi` 子对象**：`{ sign, cookie, signPath, dropHeaders }`。能用 axios 键表达的
  （`timeout` / `params` / `headers` / `signal` / `proxy` …）一律不加，直接用 axios 自己的键。
* **v7 的 URL 构造器另挂为 `client.<平台>.apiUrls`**；v6 那份从 v7 门面上撤下 ——
  包顶层 `import { douyinApiUrls } from '@ikenxuan/amagi'` 照旧可用，
  `@ikenxuan/amagi/compat` 的 `client.<平台>.<平台>ApiUrls` 以原名保留。
  两份的返回形态逐平台不同，见指南。
* 主入口新增 4 个类型导出（`AmagiRequest` / `AmagiRequestMethod` / `AmagiRequestConfig` / `AmagiAxiosTrack`），
  **运行时导出面不变**。

用法、逐平台的 `apiUrls` 返回形态与已知边界见[自定义请求](/docs/v7/usage/advanced/custom-request)。

## 已知边界 [#已知边界]

beta 期间下面这些东西还会动，先按当前实现写：

* **9 个接口的响应类型仍是宽松类型**（登录、验证码与几个受风控影响的接口），
  这一批拿到的 `data` 需要自己收窄。
* 签名实现里 **`a_bogus` 有真实抓包可对照**；`X-Bogus` 与 `ttwid` 相关参数没有对照物，
  只能靠调用结果反推。
* 抖音的参数与风控策略随时在变，任何接口都可能在某天开始需要新的反爬参数。

## 升级 [#升级]

安装命令见页首。从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)；不想改代码的用
`@ikenxuan/amagi/compat`。遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.10 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.10)

> 2026-10-24 发布的 v7 第十个 beta —— 抖音风控挑战自动处理与验证页、扫码登录补齐四个平台、B站 Cookie 续期、15 个新端点



这一版把三件此前只能自己做或干脆没有的能力补上了：抖音的**纯工作量证明挑战**在管线内自动解并立即重放，滑块则连同验证页地址一起交给人；扫码登录从抖音 / B站扩到**四个平台**；B站有了官方协议的 **Cookie 续期**。另新增 15 个端点（抖音 3、快手 6、小红书 6），端点总数到 80。

主要工作来自 [@OduckO](https://github.com/OduckO)（yaya）的 [PR #203](https://github.com/ikenxuan/amagi/pull/203)（squash 合并为 [`37fe6582`](https://github.com/ikenxuan/amagi/commit/37fe658268432222190e4259c2ed42b24520850b)）：风控挑战自动处理、快手 / 小红书扫码登录、B站 Cookie 续期与 14 个新端点都在其中；抖音分享短链端点来自 [`094238d5`](https://github.com/ikenxuan/amagi/commit/094238d5d5f8c20abba5c3e5c7d03741190e2ab1)。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 新增：抖音风控挑战自动处理 [#新增抖音风控挑战自动处理]

管线现在区分两类挑战，分界线是**有没有人机判定**：

* **纯工作量证明在管线内解掉并立即重放。** 抖音的 WAF（`_wafchallengeid` 的 sha256 碰撞）与 VMP 挑战由管线内的解算钩子解出 cookie，runtime 立刻用新 cookie 重放本次请求，不发退避等待。trace 里这类重放的 `reason&#x60; 是 &#x2A;*`challenge`**，与业务重试的 `retry` 分开，所以「解了几次挑战」和「退避重试了几次」不再混在同一个数字里。
* **滑块永远交给真人。** 判 `CAPTCHA_REQUIRED`、不进重试名单（此前会被退避重发 3 次，每次重新签名，白发且放大风控）。失败信封的 `error.challenge` 带人能直接打开的验证页地址；抖音还带 `jsSdkUrl` / `verifyData`，可以自建验证页。

`error.challenge` 现在**不受 `debug` 管**：client、HTTP 路由、静态 fetcher 三个入口都拿得到。自建验证页有现成的 `renderVerifyPage(challenge, { platform })`，返回一张自包含 HTML。处理流程仍是三步：把地址交给真人 → 等过完 → 用同一份 cookie 重发原请求。amagi 不识别、不模拟轨迹、不自动过滑块。

配套的两处实现变化：

* **`__ac_signature` 改成纯算**（从 JSVMP 字节码 lift 出来），游客凭据链不再在 `node:vm` 里执行挑战页脚本；`mint` 的第一发只读 `Set-Cookie` 的 `__ac_nonce`，不解析页面。
* **`__ac_nonce` 按 cookie 身份缓存 45 秒**：解出的 nonce 跨调用复用、签名按当刻时钟重算，裸打抖音页面从每次 2 发降到 1 发。缓存只存 nonce，不存合并后的 cookie。

细节与实测记录见[传输与反爬](/docs/v7/dev/internals/transport)与[响应类型](/docs/v7/usage/guide/type-mode)的「失败分支里的 `error.challenge`」。

## 新增：扫码登录补齐四个平台 [#新增扫码登录补齐四个平台]

`client.<平台>.login` 此前只有抖音与 B站，这一版补上**快手**与**小红书**。四个平台统一提供 `qrcode()`（新建）与 `resume(blob)`（从 `serialize()` 的产物恢复），消费方式仍是三种：`watch()` 回调、`for await`、`start()` + `next()` 手动单步。

* 快手：`start()` 本地生成 `did`，不依赖传入 cookie；确认后校验 `passToken` / `serviceToken`。
* 小红书：`start()` 自带游客冷启动，同样不依赖传入 cookie。
* 状态机与各平台协议差异见[翻页与会话](/docs/v7/dev/internals/session)，用法见 [SDK 参考的「扫码登录」](/docs/v7/usage/guide/sdk#扫码登录)。

抖音侧另补了 `credentials` 工具命名空间（Cookie 规范化、登录态探测、游客凭据申请），见[工具集](/docs/v7/usage/guide/utilities)。

## 新增：B站 Cookie 续期 [#新增b站-cookie-续期]

`client.bilibili.refreshCredential({ cookie, refreshToken })` 走 B站**官方**的四步续期协议：校验登录态 → 取 `refresh_csrf` → 换新 cookie 与新 token → 确认并作废旧 token。四平台里只有 B站有这条正规续期通道，不涉及风控对抗。

拿到的 `{ cookie, refreshToken }` **必须整组持久化替换旧值**：旧 token 在第 4 步已作废，再用会报 `86095`。`cookie` 至少要含 `SESSDATA` 与 `bili_jct`。顶层也导出了 `refreshBilibiliCredential` 与 `getBilibiliCorrespondPath`，自组装 transport 时可用。

## 新增：15 个端点 [#新增15-个端点]

| 平台  | 端点                        | 说明                                                              |
| --- | ------------------------- | --------------------------------------------------------------- |
| 抖音  | `fetchShortUrl`           | 分享链接转 `v.douyin.com` 短链；**不需要 cookie，但必须签名**，`belong=aweme` 是前提 |
| 抖音  | `fetchMusicAwemeList`     | 某条原声下的作品列表；原声缺 `play_url` 时从这里取 mp3                             |
| 抖音  | `fetchMixAweme`           | 合集作品列表，按 `mix_id` 取作品                                           |
| 快手  | `fetchCommentReplies`     | 评论回复，声明式翻页                                                      |
| 快手  | `fetchEmotionPackageList` | 表情包列表                                                           |
| 快手  | `fetchSlideFeed`          | 作品相关推荐                                                          |
| 快手  | `fetchSearchUser`         | PC 用户搜索，游客会话可用；翻页间隔 10 秒                                        |
| 快手  | `fetchSearchWorkList`     | PC 作品搜索，游客会话可用；翻页间隔 10 秒                                        |
| 快手  | `fetchLoginUserProfile`   | 当前登录账号资料，仍需登录身份                                                 |
| 小红书 | `fetchSearchUser`         | 用户搜索                                                            |
| 小红书 | `fetchSearchHotList`      | 搜索热榜                                                            |
| 小红书 | `fetchSubComments`        | 子评论，`number` 自动翻页                                               |
| 小红书 | `fetchLiveRoom`           | 直播间信息                                                           |
| 小红书 | `fetchLiveStatus`         | 直播状态                                                            |
| 小红书 | `fetchLiveSquare`         | 直播广场                                                            |

抖音 `fetchShortUrl` 的成功与失败都是 HTTP 200 + `code: 0`，端点自带 judge 按 `reason` 区分：`check failed` 是签名被拒（`SIGNATURE_REFUSED`，换 cookie 无用），`not allowed to shorten` 是 `belong` 不对。同一个 `target` 返回稳定短码，不是一次性令牌。

## 行为变更 [#行为变更]

* **滑块从 `ANTIBOT_PAGE` 改判 `CAPTCHA_REQUIRED`**：`ANTIBOT_PAGE` 在抖音是可重试码，滑块中间页此前会被退避重发；现在两条识别通道（验证头与 HTML 中间页）给同一个码，且 `retryable: false`。
* **解完挑战就收口**：一次调用里解算成功后，不再因为重放结果仍被判 `ANTIBOT_PAGE` 而继续退避重试。实测零 cookie 裸打抖音首页从 5 发降到 2 发；信封仍带 `retryable: true`，调用方自己重试照旧有效。
* **声明 `responseType: 'text'` 时能拿回 HTML**：此前文本响应被当成非 JSON 判失败；现在 `text` 模式下对字符串不发表意见，只有平台自己的挑战判据仍然生效。小红书 / 快手 / B站没有 HTML 挑战页锚点，它们的 WAF 页在 `text` 模式下会被当成成功——这是显式声明 `text` 的取舍，见[自定义请求](/docs/v7/usage/advanced/custom-request)。
* **UA 原样发出**：不再剥掉 ` Edg/x`，签名用的 UA 与实际发出的 UA 一致。
* **大整数安全解析**：超出安全整数范围的裸整数转为字符串，不再丢精度。

## 致谢 [#致谢]

感谢 [@OduckO](https://github.com/OduckO)（yaya）贡献 [PR #203](https://github.com/ikenxuan/amagi/pull/203)（[`37fe6582`](https://github.com/ikenxuan/amagi/commit/37fe658268432222190e4259c2ed42b24520850b)）：这一版的风控挑战自动处理、快手 / 小红书扫码登录、B站 Cookie 续期与 14 个新端点都出自这份 PR。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：新增能力都是可选的，已有调用点不需要改。需要留意三处行为变化：
  1. 抖音滑块现在报 `CAPTCHA_REQUIRED`（原 `ANTIBOT_PAGE`）且不可重试——按错误码分流的代码需要检查；
  2. 声明 `responseType: 'text'` 的调用现在会成功拿回 HTML；
  3. 抖音 `mintDouyinGuestCookie` 返回 `null` 的条件收窄为「什么都没拿到」——只拿到 `ttwid` 时不再整次算失败，返回值里会带上设备标识 cookie。
* **登录调用方**：`client.kuaishou.login` 与 `client.xiaohongshu.login` 现在可用，不再是编译错误。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.2 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.2)

> 2026-09-20 发布的 v7 第二个 beta —— 抖音搜索翻页修复与小红书签名适配



接着 [beta.1](/docs/v7/changelog/7.0.0-beta.1) 走，这一版没有新的破坏性重构，
主要是两块跟着平台风控走的修复：抖音搜索翻页，与小红书自 2026-03 起收紧的签名要求。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 破坏性变更 [#破坏性变更]

只有一条，且只影响小红书用户笔记列表：

| 改什么                           | beta.1       | beta.2                                |
| ----------------------------- | ------------ | ------------------------------------- |
| `xiaohongshu.userNoteList` 参数 | 只需 `user_id` | **新增必填 `xsec_token`**（反爬令牌，随笔记分享链接下发） |

没传 `xsec_token` 会在参数校验阶段返回失败信封，`success` 为 `false`。
其余接口签名一致，成功分支写法不变。

## 修复 [#修复]

### 抖音搜索翻页会拿到重复结果（#192） [#抖音搜索翻页会拿到重复结果192]

此前搜索每页的 `offset` 恒为 `0`，翻页只推进 `search_id` 而不推进 `offset` ——
于是每一页都从头取同一批，多页调用拿到的是重复内容。

现在 `offset` 参与翻页：声明式翻页从响应的 `cursor` 取下一页偏移，取不到时按已累计条数推进。
同时开放了可选参数 `offset`（`douyin.search`，一般不用传，翻页由端点自动完成）。
配套补齐了 OpenAPI 产物里的 `offset` 字段。见[抖音搜索](/docs/v7/usage/api/http/douyin/search)。

### 小红书签名适配 2026-03 后的新风控 [#小红书签名适配-2026-03-后的新风控]

平台自 2026-03 起对数据获取类接口收紧校验，旧签名会被 HTTP 406 拒绝。这一版按抓包实证分接口对齐：

* **`homeFeed` / `noteDetail` / `searchNotes`**：POST 请求增加 `x-rap-param` 校验头
  （新签名档 `xhs-post-rap`）。缺这个头会被判非法请求。
* **`userNoteList`**：改用 `XYW_` 开头的签名（`xhs-get-xyw-trace`，GET + `x-b3-traceid`）——
  传统 `XYS_` 签名在这类接口上已被 406 拒绝。同时新增必填 `xsec_token`（见上）。
* **`noteComments`**：GET 的 `x-s` 改为覆盖 query（`signParams` 透传给签名器，只签路径会 406），
  翻页游标 `cursor` 收进声明式翻页、不再暴露为自由参数，并补上了从真实响应派生的具名响应类型
  （此前是宽松类型）。见[笔记评论](/docs/v7/usage/api/http/xiaohongshu/noteComments)。

### 翻页非空游标被静默返回空 data [#翻页非空游标被静默返回空-data]

小红书签名依赖的 `@ikenxuan/xhshow-ts` 升到 `1.1.0`，签名模板的 `x0` 从 `4.3.5` 校正为 `4.4.3`。
旧值会让评论等接口在翻页（非空 `cursor`）时被服务器静默返回空 `data` —— 不报错、只是没数据。

## 已知边界 [#已知边界]

除 [beta.1 列出的](/docs/v7/changelog/7.0.0-beta.1#已知边界)之外，这一版额外注意：

* 小红书的 `XYW_` 签名与 `x-rap-param` 生成没有独立抓包对照物，只能靠调用结果反推；
  平台风控随时在变，某天可能又要新的反爬参数。
* 带响应类型的接口增至 57 个，小红书 `noteComments` 从宽松类型转为具名类型；
  仍有 8 个受风控影响的接口保持宽松类型，`data` 需自行收窄。

## 升级 [#升级]

安装命令见页首。从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。遇到问题请提
[Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.3 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.3)

> 2026-09-21 发布的 v7 第三个 beta —— 发版链路从 release-please 换成自研脚本



**库使用者无需改动**：这一版没有接口、类型或运行时行为的变化，`packages/core/src` 一行没动。
改的全是发版链路与 CI 门禁 —— 前两个 beta 每次发版都栽在同一道门上，这一版把根挖掉。
贡献者需要知道发版方式变了。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 发版链路：release-please → 自研脚本 [#发版链路release-please--自研脚本]

发版从 release-please 换成 tag 触发的自研脚本。维护者本地跑 `pnpm run release`
（`scripts/release.ts`，bumpp 交互式选版本 → 提交 → 打 `v*` tag → 推送），
tag 推送触发 `release.yml` 完成发布。

为什么换掉 release-please：

* 它开的 release PR 由 `GITHUB_TOKEN` 创建，GitHub 的递归保护让这些 PR 上的 CI 永远不跑 ——
  门禁形同虚设，只能盲点合并。
* 同一版本并存两个 release PR 时，第二次合并在建 Release 那步炸
  `already_exists, field: tag_name`（beta.2 实测）。
* 它生成的 `CHANGELOG.md` 风格与 oxfmt 互不相让，每发一版 `format:check` 必红。

tag 触发没有这些问题：tag 是人推的、不经过 PR。发布链路也不再跑 lint / test 门禁 ——
那些归 `ci.yml` 管，代码合并进 main 前就验过了，发布永远不被 CI 拦住。

配套变化：

* **提交类型校验内嵌进 `.husky/husky-tasks.ts`**（当前九种），`commit-msg` 钩子按这份内嵌名单校验，
  不再依赖 release-please 的配置。
* 门禁与发布分家：新增 `ci.yml`（push / PR 触发的门禁），`release.yml` 只认 `v*` tag。
* `packages/core/CHANGELOG.md` 冻结为 release-please 时代的产物；新版本的变更记录由
  changelogithub 直接写成 GitHub Release，不再落文件。

发版流程与提交规范详见[贡献指南](/docs/v7/dev/contributing)与[仓库与工程](/docs/v7/dev/internals/repo)。

## 修复：openapi.json 每次发版 / 合并必红 [#修复openapijson-每次发版--合并必红]

`openapi.json` 是数据产物（文档站与 Apifox 的输入），却被逐字节一致性门警察「是否等于此刻生成的内容」。
它的 `info.version` 盖自 `package.json`，而 release-please 只 bump 版本、不重跑生成器，
经 API 的提交也不触发 pre-commit —— 于是每次发版这道门必红；合并 PR 也红，
因为 git 的文本合并不等于重新生成。beta.1 / beta.2 两次发版都栽在这。

改法：把 `openapi.json` 移出一致性门，改由消费处现生成 —— 文档站 `docs:api` 在构建前
`pnpm openapi` 生成，本地编辑仍由 pre-commit 自动重生成。openapi 的结构正确性改由
`spec.test.ts` 一组当场在内存生成再断言的语义测试守着（paths / 参数 ↔ zod / 响应信封），
永不因版本、合并或格式误报。`response-schemas.generated.ts` 是编译进发布包的源码、无版本位，
仍留在逐字节 `--check` 里把关。

同一条线上，Apifox 同步也改成同步前先 `pnpm openapi` 现生成再推，触发器从只盯
`openapi.json` 改成盯真源（`core/src` + `response-types/src` + 生成器脚本）——
committed 快照可能滞后，拿它当信号会漏同步。

## 升级 [#升级]

安装命令见页首。库使用者从 beta.2 升上来无需改代码。从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。
遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.4 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.4)

> 2026-09-21 发布的 v7 第四个 beta —— 修复发版脚本的幻影暂存



又是一版只动发版链路、**库使用者无需改动**的补丁，和 [beta.3](/docs/v7/changelog/7.0.0-beta.3) 同日发出。
beta.3 换上的自研发版脚本首次实跑就暴露一个 git 状态问题，这一版把它修掉。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 修复：发版脚本的幻影暂存 [#修复发版脚本的幻影暂存]

beta.3 的 `pnpm run release` 把 git 操作交给了 bumpp。bumpp 的提交是「带路径提交」
（`git commit -- <文件>`），git 对这种 partial commit 会把钩子放进一个临时索引里跑 ——
pre-commit 钩子改写的 timestamp 进了提交，但真实暂存区停留在提交前的快照，
worktree 与 index 就此脱节（beta.3 发版后出现的 `MM package.json` 幻影状态）。

改法：bumpp 只用来交互式选版本和改文件（`commit` / `tag` / `push` 全关），
git 步骤在 `scripts/release.ts` 里手工编排 —— 全量 `add` → 普通提交 → 打 tag → 推送分支与 tag。
顺带把版本取消时的早退也补上（bumpp 未写文件就直接退出）。

## 修复：openapi 产物版本号跟随发版 [#修复openapi-产物版本号跟随发版]

`openapi.json` 的 `info.version` 读 `package.json`，但 beta.3 发版时没重新生成，
tag 里的 `openapi.json` 因此比 `package.json` 落后一个版本号。这一版把 openapi 重生成
收进发版脚本：bump 版本后 `pnpm openapi` 现生成，与 `package.json`、
`response-schemas.generated.ts` 一起进同一个 release 提交，产物版本号不再漂移。

## 升级 [#升级]

安装命令见页首。库使用者从 beta.3 升上来无需改代码。从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。
遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.5 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.5)

> 2026-09-25 发布的 v7 第五个 beta —— 移除 chalk 子路径导出，端点契约新增 aggregate 钩子与签名器名收窄



这一版有一个面向库使用者的**破坏性变更** —— 移除 `./chalk` 子路径导出；其余改动集中在端点契约层的类型收窄，影响的是**新增端点的贡献者**，日常调用 fetcher 的代码无需改动。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 破坏性变更：移除 `./chalk` 子路径导出 [#破坏性变更移除-chalk-子路径导出]

`import chalk from '@ikenxuan/amagi/chalk'` 这个子路径，连同 core 对 `chalk` 的依赖一起被移除了。它本来只是 `export * from 'chalk'` 的透传，既没转发 default（`import chalk` 拿不到东西、只能具名导入），也没有任何测试覆盖 —— 是这一版清理未用依赖时一并摘掉的。

**迁移**：需要终端颜色请自己装 —— `pnpm add chalk`，从 `chalk` 包直接导入。amagi 本身不依赖任何日志 / 颜色库：日志通过[事件系统](/docs/v7/usage/advanced/events)暴露，监听器自己决定怎么上色。

其余透传入口不动：`./axios` 与 `./express` 保留（core 自身就依赖它们），抖音签名与验证工具在 `./signing`（自 beta.1 起）。当前公开导出面详见[公开 API 表面](/docs/v7/dev/internals/surface)。

## 端点契约：`sign` 收窄到平台签名器名（#196） [#端点契约sign-收窄到平台签名器名196]

端点声明的 `sign` 字段从宽 `string` 收窄到**本平台签名器表推导出的名字联合** —— 抖音是 `'a-bogus' | 'x-bogus'`、B站 `'wbi' | 'qtparam'`、快手 `'hxfalcon'`、小红书是 `xhs-*` 那七个。名字写错（如 `'a-bogas'`）**编译期即报错**，不必等运行时查表抛「未注册的签名器」。

实现方式是每个平台一个专属的 `defineDouyinEndpoint` / `defineBilibiliEndpoint` 等，运行时仍是恒等函数、其余行为与通用 `defineEndpoint` 完全一致。**对库使用者无感**，只影响写端点声明的人。

## 端点契约：分页收尾迁到 `paginate.merge`（#197） [#端点契约分页收尾迁到-paginatemerge197]

分页端点的收尾整形从端点级 `normalize` 迁到了 `paginate.merge`。`merge` 拿到的第一参是收窄好的 `PaginatedValue`（`lastPage` 恒有值），去掉了此前那圈「把字段变可选、再靠 `as` 断言补回来」的写法 —— 分页端点的整形代码因此**零类型断言**，返回类型也从翻页过程自动收窄，不再手写第二遍。

## 端点契约：新增 `aggregate` 钩子（同构分段并发） [#端点契约新增-aggregate-钩子同构分段并发]

新增第三个整形钩子 `aggregate`，与 `paginate.merge` 平行，专门收敛「同构分段并发」的结果 —— 弹幕这类按时间区间切成多段、并发抓取再拼接的端点。它的入参 `AggregatedValue` 里 `head`（第一段成功段）恒有值，端点可以直接展开、无需断言；抖音与快手的弹幕端点从 `normalize` 迁过来后同样是**零断言**。

`aggregate` 与 `normalize` **互斥**：同一个端点同时声明两者会**编译期报错**（execute 只认 `aggregate`、`normalize` 会被静默忽略，所以在声明处就用类型挡住）。三个整形钩子 `normalize` / `aggregate` / `paginate.merge` 现在是**三选一**。细节见[端点注册表](/docs/v7/dev/internals/registry)与[契约与信封](/docs/v7/dev/internals/contracts)。

## 依赖与文档站 [#依赖与文档站]

* **依赖清理与升级**：各包依赖统一升级，摘除未用依赖（`chalk` 即此批一起移除）。
* **文档站移除 twoslash**：代码块的类型标注基础设施 twoslash 撤掉，整站构建的内存占用大幅下降（此前是构建内存的绝对大头）。
* **字体本地化**：文档站字体改为本地自托管，构建不再联网抓 Google 字体，离线也能跑完整站构建。

这些都不进 npm 包，对库使用者零影响。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：除非你用到了 `./chalk`（改为自己安装 `chalk`），否则从 beta.4 升上来**无需改代码**。
* **新增端点的贡献者**：`sign` 现在要填平台签名器表里的名字；分页端点收尾用 `paginate.merge`、同构分段并发用 `aggregate`（与 `normalize` 三选一），见[新增接口](/docs/v7/dev/add-api)。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.6 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.6)

> 2026-09-29 发布的 v7 第六个 beta —— 开放 sign-steps 子入口精细控制反爬参数，修抖音裸请求丢 msToken，收敛 fetcher 类型打印



这一版**没有破坏性变更**。主线是开放一个新的公开子入口 `@ikenxuan/amagi/sign-steps`，让 `client.<平台>.request` 这条裸请求路能自己拼签名；顺带修掉抖音裸请求丢 `msToken` 的 bug，并把 `client.<平台>.fetcher` 与 `amagi({})` 实例的类型打印大幅收敛。日常调用 fetcher 的代码无需改动。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 新增：`@ikenxuan/amagi/sign-steps` 子入口（精细控制反爬参数，#198） [#新增ikenxuanamagisign-steps-子入口精细控制反爬参数198]

`client.<平台>.request` 这条裸请求路，过去 `sign` 只能选一个注册名（`sign: 'a-bogus'`）或干脆不签（`sign: false`）——想「要 a\_bogus 但换个 `msToken` 长度」「只签 x\_bogus 不要 secsdk 收尾」都没有出口。这一版把四平台的**原子 step 工厂**从新子入口 `@ikenxuan/amagi/sign-steps` 放出来，配合 `amagi.sign` 放宽到 `SignDecl`（收 `SignStep[]` 与自定义 `SignFn`），可以自己列清单：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: 'ttwid=xxx' } })
declare const url: string
// ---cut---
import { douyin } from '@ikenxuan/amagi/sign-steps'

// 用 200 长度的 msToken，且不加 secsdk 收尾
await client.douyin.request.get(url, {
  amagi: { sign: [douyin.msToken(200), douyin.aBogus()] }
})
```

step 工厂按平台归入四个命名空间对象（`douyin` / `bilibili` / `kuaishou` / `xiaohongshu`）。runtime 按 `phase`（`prepare` → `token` → `sign` → `finalize`）稳定排序后依次执行，所以数组顺序写反也不翻车。手挑的 step 与注册名、平台默认签名在内部是**同一批实现**、同一个签名器实例、同一份缓存，签出来必然一致。用法详见[精细控制反爬参数](/docs/v7/usage/advanced/custom-request#精细控制反爬参数)。

## 修复：抖音裸请求丢 `msToken`（#198） [#修复抖音裸请求丢-mstoken198]

把签名统一到 step 清单时一并修掉一个 bug：`client.douyin.request` 配注册名 `'a-bogus'` / `'x-bogus'` 时，签名链里不含 `msToken`。现在这两个注册名也走含 `msToken()` 的清单，裸请求签出来的参数与端点内部走的那条完全一致——用 `client.douyin.request` 打抖音接口不再因缺 `msToken` 被风控。

## 类型：fetcher 与 client 返回类型改名义接口（#199） [#类型fetcher-与-client-返回类型改名义接口199]

`client.<平台>.fetcher` 与 `amagi({})` 实例的类型此前会把整个端点注册表内联展开——`client.douyin.fetcher` 悬停打印十万字符量级，IDE 补全、`.d.ts`、文档站的类型标注全被拖累。这一版把这些返回类型从泛型别名改成**名义接口**：容器处只打印类型名，钻进具体方法时签名依旧完整。

**类型完全等价，只是显示收敛**——`amagi({})` 从 107,713 字符降到个位数、`client.douyin.fetcher` 从 107,364 降到两位数。库使用者无感，受益的是 IDE 悬停与类型提示的响应速度。

## 文档站：twoslash 逐页恢复 [#文档站twoslash-逐页恢复]

[beta.5](/docs/v7/changelog/7.0.0-beta.5) 为避开 CI 构建 OOM 整套移除的 twoslash 类型标注，这一版起按页恢复，CI 的内存上限同步调高。这不进 npm 包，对库使用者零影响。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：从 beta.5 升上来**无需改代码**。用 `client.douyin.request` + `sign: 'a-bogus'` 发抖音裸请求的，这一版会自动带上此前缺失的 `msToken`。
* **想精细控制反爬参数的**：从 `@ikenxuan/amagi/sign-steps` 引入 step 工厂，拼一份 `SignStep[]` 交给 `sign`，见[精细控制反爬参数](/docs/v7/usage/advanced/custom-request#精细控制反爬参数)。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.7 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.7)

> 2026-10-02 发布的 v7 第七个 beta —— SDK 参数类型语义化：数字参数告别 unknown、B站评论枚举收窄、内部翻页参数退场；抖音弹幕加 7 天保险丝与分片限流



这一版**没有运行时破坏性变更**，但在**类型层面收紧了两处**：翻页游标参数退出公开签名、抖音 `search` 删掉了从未生效的 `keyword` 字段——手动传过这两处的代码升级后会类型报错，删掉即可（见文末「升级」）。主线是 SDK 参数类型的语义化：数字参数的悬停从 `unknown` 变回 `number`，B站评论的 `type` / `mode` 收窄成带对照表的字面量联合。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 类型：SDK 方法参数从 `unknown` 收口为 `number` [#类型sdk-方法参数从-unknown-收口为-number]

fetcher 与静态 fetcher 的 options 此前取 zod 的输入类型，而数字参数的 schema 都是 `coerce`——输入侧是 `unknown`，于是&#x2A;*所有数字参数的悬停都显示 `unknown`**，与文档标注的 `number` 自相矛盾。这一版改取解析后的类型，数字参数回到 `number`；非法值运行时报错的行为不变。

## 类型：B站评论 `type` / `mode` 收窄到字面量联合 [#类型b站评论-type--mode-收窄到字面量联合]

`client.bilibili.comments` / `client.bilibili.commentReplies` 的参数进一步收窄：

* `type` 从裸 `number` 收成 `CommentType`（`1 | 2 | … | 33`，评论区类型代码），类型上带完整对照表 JSDoc，悬停即见每个代码对应什么评论区；联合类型进了根导出面，可以直接 `import type { CommentType }` 引用。
* `mode` 收成 `0 | 1 | 2 | 3`，JSDoc 标注各值对应的排序语义（0 和 3 仅热度，1 按热度+按时间，2 仅时间）。

非法代码在运行时报「无效的评论区类型」；OpenAPI schema 同步产出这两个语义类型，文档参数表自动跟随。

```ts twoslash
import amagi, { type CommentType } from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=xxx' } })
// ---cut---
// type 悬停即见 1|2|…|33 与完整对照表
const type: CommentType = 17 // 评论区类型代码，17 = 动态
await client.bilibili.fetcher.fetchComments({ oid: '170001', type, mode: 3 })
```

## 内部参数退出公开签名与文档 [#内部参数退出公开签名与文档]

翻页游标这一类参数（`pagination_str` / `max_cursor` / `cursor` / `search_id` + `offset` / `room_id`，共 10 处）原先公开在 fetcher 签名与 OpenAPI 文档里，describe 写着「不用传」但类型系统拦不住。这一版引入 `internalParam()` 标记：

* 公开签名里挖掉这些参数——翻页由端点机器接管，调用方不再可能手传；
* OpenAPI 文档与文档站参数表同步隐藏（HTTP 运行时照常接受，直连行为不变）；
* 对象字面量里硬传会被 excess property check 直接拒绝。

升级影响见文末。

## 修复：抖音弹幕的 duration 保险丝与分片限流 [#修复抖音弹幕的-duration-保险丝与分片限流]

* `danmaku` 的 `duration` 此前无上限，天文数字入参会在同步切段循环里卡死进程——现在加上限 **7 天**，超限直接报参数错误。
* 弹幕分片此前经全量 `Promise.allSettled` 同时发出，没有并发闸——现在改为 `SEGMENT_CONCURRENCY = 10` 的限额池，完成一个补一个；这项限流对**所有分段派发类端点**统一生效。
* v6 兼容门面的平行校验 schema 同步收紧（常量自端点导出，两处不会漂移）。

## 内部：URL 构造器参数类型回归端点治理 [#内部url-构造器参数类型回归端点治理]

36 个手写 `XxxParams` interface 的二次声明退役，构造器参数类型改为从端点注册的 schema 直接派生；会成环的结构靠 build 显式标注返回类型断开。纯内部治理：OpenAPI 产物逐字节零漂移，使用者的 API 面没有任何变化。顺手修正两处历史漂移：

* 抖音 `search` 删掉了实现从未读取的 `keyword` 字段（实现读的是 `query`，旧测试传 `keyword` 时新旧两端各自产出 `keyword=undefined`，错位一致）；
* 小红书 `noteComments` 的翻页游标补进 schema，穿上 `internalParam` 马甲。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：从 beta.6 升上来，绝大多数场景**无需改代码**。需要留意的只有类型层面的三处收紧：
  1. 之前手动传翻页游标（`pagination_str` 等）的，删掉——端点机器自己管；
  2. 抖音 `search` 传过 `keyword` 的，改传 `query`——`keyword` 从未生效过；
  3. B站评论 `type` / `mode` 写过字符串或非法数字的，改成合法代码——联合类型现在编译期就拦。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.8 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.8)

> 2026-10-05 发布的 v7 第八个 beta —— 签名验证扩成全平台入口；抖音 403 根因修复与访客 id 自动铸造（SIGNATURE_REFUSED 归因、verify_center 判人机验证、缺访客 id 自动铸造并合并）



这一版一条新功能线、一条修复线：**签名验证**扩成独立入口与全平台文档板块；**抖音 403**（`Blocked by ArgusSecurityPlugin Uifid Not Found`）查到了根因并修掉。没有运行时破坏性变更，类型面只有加法；但抖音有两处**错误分类**变了（详见「修复」与文末「升级」）——按错误码分流的调用方需要补分支。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 新增：签名验证入口 `@ikenxuan/amagi/signing` [#新增签名验证入口-ikenxuanamagisigning]

这个入口是给「**确认签名实现还是对的**」这件事用的，不是给日常取数用的——日常取数走主入口，签名由 runtime 自动挂上。

它要解决的问题是验证领域的死结：平台对签名普遍是**抽样校验**的，签名用错了常量，请求大部分时候照样成功，只是被判高风险的概率上升。于是「请求成功」证明不了任何事，而自证型的测试（拿自己生成的快照跟自己比）结构上**不可能**发现常量过期——amagi 的数据接口就带着一个 2024 年的旧盐值活了两年。唯一的出路是拿外部锚点：一份真实浏览器产出的签名，把它拆开看。这一版提供的能力：

* **抖音**：`a_bogus` 整段拆解（结构指纹 + 可还原时钟 + 摘要链候选校验）、`diagnoseSalt` 反推用的哪个盐值、`X-Bogus` 拆解、从已签名 URL 恢复被签名的 query；`verify_fp` 骨架拆解与时钟读回。
* **B站**：`w_rid` 重算比对、`av` ↔ `bv` 互转——纯函数，钉住输入逐字符比。
* **快手**：`$HE_` 段拆解（双层 LRC + 布局常量 + 时钟/计数器原样读回）；HUDR 段整段是密文，底下没有明文，这是诚实而不是缺口。
* **小红书**：算法本体在 `@ikenxuan/xhshow-ts`（依赖 `node:crypto` / `node:zlib`），进不了浏览器，这里只有头部形状检查。

整条依赖链（除小红书算法本体）不引用任何 Node 内置模块——MD5 换成纯 TS 实现，浏览器里能直接跑。文档站的「签名验证」板块同步重构成**总览 + 四平台各一页**，页顶即交互验证器，验证器与库实现共用同一份代码，不会漂移。

## 修复：抖音 403「Uifid Not Found」的根因与归因 [#修复抖音-403uifid-not-found的根因与归因]

**现象**：扫码登录拿到新 cookie 之后，请求受 secsdk 保护的端点（`/aweme/v1/web/music/detail/` 等 14 条 GET）稳定回 `403 Blocked by ArgusSecurityPlugin Uifid Not Found`，还被判成可重试的 `ANTIBOT_PAGE`，白打 4 次请求外加 1s/2s/4s 退避。

**根因有两层**。第一层：`UIFID` 不是登录下发的——它由 secsdk 在**真实浏览器里**向铸造接口申请，扫码登录拿回来的是身份 cookie（`sessionid` 一族），里面没有访客 id。第二层才是 bug：amagi 在访客 id 取不到时**仍然计算签名**，明文里 uifid 的位置是空串——等于给平台递了一份「给不存在的访客签的名」，必被拒。两层叠起来，就是「刚登录完反而被拦」。

修复：

* **取不到访客 id 时，整条 secsdk 加签跳过**。不加签，表外端点照常可用；表内端点仍然失败，但平台会自己点名 `uifid`，比签一个空访客有信息量。这与 `webid` 的既有结论同一条纪律：**不传安全，传错致命**。
* **cookie 识别扩成六种拼写**（`uifid` / `uifid_temp` / `uifidtemp` 及三个大写变体，取首个非空）。抖音铸造流程落下来的是 `UIFID_TEMP`，此前只认 `UIFID=` 一种拼写，恰好漏掉最常见的那种——不少「明明有访客 id 却被拦」的场景就此消除。
* **新增错误码 `SIGNATURE_REFUSED`**（第 23 个码，`kind` 仍是 `risk`，不可重试）：Argus 拦截文本点名签名时（`uifid not found` / `signature not found` / `sign invalid` / `sign expired` 四个片段），与一般风控**分开归因**——前者是 amagi 侧的签名问题，换一万次 cookie 也没用；后者才是账号被风控。两者处置方式完全相反，混在一个码里，排查方向就会跑偏。它也不进 `retryOn` 名单：重签换的是 `msToken` / `a_bogus`，补不出缺失的访客 id，命中即失败，不再进退避循环。
* **人机验证页有了名字**：响应带 `verify_center_decision_conf`（风控页判据字段，实物 `status_code: 10000`）时判 `risk` / `CAPTCHA_REQUIRED`，而不是落进 `unknown` / `PLATFORM_ERROR` 的「平台返回了错误」。按字段名判、不扫全文——简介里恰好提到验证码的正常作品不会误判。**只定性，不产出地址**：目前掌握的这类响应里没有可跳转的验证页 URL，所以也不装提取器（`error.challenge` 仍为空），等有线上样本再接。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: 'ttwid=xxx' } })
// ---cut---
const result = await client.douyin.fetcher.fetchMusicInfo({ music_id: '7261552078909191295' })
if (!result.success) {
  if (result.error.code === 'SIGNATURE_REFUSED') {
    // amagi 侧的签名问题：换 cookie 无用，检查 cookie 里有没有 UIFID / UIFID_TEMP
  } else if (result.error.code === 'CAPTCHA_REQUIRED') {
    // 平台要求人机验证
  }
}
```

## 新增：访客 id 自动铸造（cookie 审计） [#新增访客-id-自动铸造cookie-审计]

上一条修复让「签名被拒」说得清了，这一条让它**自己好**：`PLATFORM_RUNTIME.douyin` 新增第五个槽位 `ensureCookie`，每次请求在 prepare 之后、build/sign 之前审计 cookie——缺访客 id 就**纯 HTTP 铸造**一个并合并，扫码登录完成时也审计一遍。

铸造链路（线上实测）：首访拿到 `__ac_nonce` 与一份挑战页，页面内联的 byted\_acrawler 能在 Node 里离线算出 `__ac_signature`（`sign("", nonce)`），带 pair 再请求一次，服务端一次性铸出 `ttwid` + `web_sign_token` + `UIFID_TEMP`（约 500 天有效）。三个实测结论：服务端真验签（垃圾签名被拒）、签名对可跨客户端移植（无 TLS 门槛）、铸出的访客 id 过 Argus（受保护端点全部到达业务层，零登录解析作品成功）。

三个设计要点：**acrawler 本体不进仓库**——每次铸造从挑战页现取现执行，抖音更新算法自动跟随；**审计永不为调用增加失败**——铸造失败原样返回，该 `SIGNATURE_REFUSED` 还是它；**只补缺失的名字**——已有 `ttwid` 的登录态只追加 `UIFID_TEMP`。对使用方意味着：全新部署零配置（cookie 都不填），第一个请求就可用；扫码登录的 CK 天然带上访客 id；测试环境（vitest）下默认出口不出网，铸造行为可用注入的 HTTP 出口单测。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：从 beta.7 升上来，**无需改代码即可编译**——类型面只有加法（新错误码进了 `AmagiErrorCode` 联合）。需要留意两处**运行时分类变化**：
  1. Argus 点名签名的 403 现在 `error.code` 是 `SIGNATURE_REFUSED`（原来报 `ANTIBOT_PAGE`），且**不再自动重试**——按 `ANTIBOT_PAGE` 写了 `switch` 的补一个分支；没写 `default` 的穷尽 `switch` 会编译报错，那正是提醒你来处理新码；
  2. 人机验证页现在报 `CAPTCHA_REQUIRED`（原来落进 `PLATFORM_ERROR`）。
  3. cookie 里只有 `UIFID_TEMP` 的现在能被认出来；两种拼写都没有时，cookie 审计会先自动铸造（见上一节）——铸造失败才原样发请求；
* **出网提示**：自动铸造会向 `www.douyin.com` 发两次文档请求（仅发生在 cookie 缺访客 id 且进程首次命中时，之后走进程级缓存）。出口网络受限的环境请放行该域；**不想要这个行为**的设 `AMAGI_DISABLE_DOUYIN_MINT=1` 关闭（cookie 保持原样），或关注 `SIGNATURE_REFUSED` 的归因提示。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# v7.0.0-beta.9 (https://ikenxuan.github.io/amagi/docs/v7/changelog/7.0.0-beta.9)

> 2026-10-12 发布的 v7 第九个 beta —— 小红书签名算法内联（@ikenxuan/xhshow-ts 依赖退役）、游客 CK 自动铸造、全端点打通、HTTP 461 归为 RISK_CONTROL、翻页中途失败返回部分结果



这一版改动集中在**小红书**，全部出自 PR [#202](https://github.com/ikenxuan/amagi/pull/202)（squash 合并为 [`98653496`](https://github.com/ikenxuan/amagi/commit/9865349633607fe74db121bf675740be3c13dfc3)）：`@ikenxuan/xhshow-ts` 的签名算法整体内联（依赖退役）、游客 CK 降级上移到平台级、签名世代对齐 2026-10-12 真机抓包，并同步上游把 b1 编码修复带进来。

运行时有**两处行为变更**：小红书 HTTP 461 从 `unknown` / `PLATFORM_ERROR` 归为 `risk` / `RISK_CONTROL`；翻页中途被平台拒绝时返回**部分结果**而不是整体失败（首屏失败仍是整体失败，这一条四个平台的分页端点都生效）。另有一处类型收紧和一件被真机推翻的旧结论（`userNoteList` 签名回归 `XYS_`），需要留意的地方见文末「升级」。

## 安装 [#安装]

升级到最新的测试版本：

<Callout type="info">
  这一版仍发到 npm 的 &#x2A;*`beta`** 标签：`pnpm add @ikenxuan/amagi@beta`。
  `latest` 依旧是 6.x 稳定线。beta 期间 API 仍可能调整。
</Callout>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi@beta
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与这一版的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 新增：签名算法内联，`@ikenxuan/xhshow-ts` 依赖退役 [#新增签名算法内联ikenxuanxhshow-ts-依赖退役]

`@ikenxuan/xhshow-ts` v1.1.0 的源码副本整体迁入 `packages/core/src/platforms/xiaohongshu/sign/xhshow/`（25 文件 / 2852 行），同日随上游刷到 v1.2.0（29 个源文件）。上游以 MIT 发布（© 2024 Cloxl），版权与许可声明按 MIT 条款随副本保留（同目录 `LICENSE`，与 amagi 的 GPL-3.0-only 兼容）。同时维护两个库这件事到此结束，amagi 的依赖树也少一个包。

上游**零测试**，所以内联前先录了特征化基线：实测只需钉死 `Math.random` 与 `Date.now`，上游全部 API 即确定化；16 条签名向量存进 `test/fixtures/xhshow-vectors.json`，由 `xhshow-vectors.test.ts` 逐字节守住，生成器是 `gen:xhshow-vectors`。上游 v1.2.0 起有了自己的 `tests/`，42 条已全部移植成 vitest 用例（零 skip）——下次同步时连同 `tests/` 一起对照。

浏览器边界一字未变：`sign/shape.ts` 与 `@ikenxuan/amagi/signing` 仍**不 import 算法本体**（那条链依赖 `node:crypto` / `node:zlib`），`signing` 子入口在浏览器里依旧只能做形状检查。

## 新增：游客 CK 自动铸造上移到平台级，全端点打通 [#新增游客-ck-自动铸造上移到平台级全端点打通]

游客降级此前只在 `homeFeed` 一处声明，现在由 `defineXiaohongshuEndpoint` **横切注入**：cookie 里没有 `a1`（未配置或不是有效用户 CK）就自动铸造一份游客 CK 顶上——七个端点一致生效，将来新增的端点也不会漏配。端点若自带 `prepare`，在降级之后运行、其结果优先。

三个实现要点：

* 铸造走 `ctx.send`：scripting → webprofile → activate 三个会话请求与主请求**同一出口**（代理 / 超时 / 出口 IP 一致）——游客会话与出口 IP、指纹绑定，换出口就失配；
* 结果按 UA 做**进程级缓存**（上限 32 条）并对并发去重：同一进程同一 UA 只铸一次，首调成功后不再有额外请求；
* `a1` 生成改用内联算法的 `generateA1` / `generateWebId`：旧手搓版常量段写的是 `5000`，真机是 `50000`（少一个 0），内部 crc 是对错误结构算的——虽也换得到 `web_session`，但疑被风控降权。

对使用方意味着：**全新部署连 cookie 都不用填**，游客身份开箱可用；已有用户 CK 的调用跳过铸造（有 `a1` 直接放行），登录态的其余变化见下文签名与参数两节。游客侧依然无解的是 `searchNotes`——平台强制登录，报 `PLATFORM_ERROR`，本轮真机回归把它作为预期结果保留。

## 修复：签名世代对齐真机，同步上游 b1 编码修复 [#修复签名世代对齐真机同步上游-b1-编码修复]

签名世代此前有一处自相矛盾：`x0` 已抬到真机的 `4.4.3`，`x1` 却被显式钉在 `4.3.5`——同一请求的两个信封各报一个版本。这一版按 2026-10-12 真机抓包统一：x-s 的 `x0`、x-s-common 的 `x1`、webprofile 的 `sdkVersion` 都是 `4.4.3`；`x4` 与 `webBuild` cookie 都是 `6.57.2`（站点构建号随发版递增，比上游 2026-09-25 记录的值新）。

同日同步上游两笔提交——[`eb02ad9`](https://github.com/ikenxuan/xhshow-ts/commit/eb02ad985d7ce58766855f9788af47ab4a7c7c42)（v1.2.0：x-s-common 平台字段派生、XYS 的 `x4`\~`x7`、webSsk）与 [`b138a4b`](https://github.com/ikenxuan/xhshow-ts/commit/b138a4bf195cdc8f0902022f3043e070157951f4)（b1 按浏览器格式编码）——这两笔里，b1 修复的正是本仓量到过的问题；同步时也顺手退役了一批手工补丁：

* **b1 编码**：旧实现把 RC4 密文又 `JSON.stringify` 了一次再编码，产出的是浏览器从不发的「数字数组文本」——真机 1592 字符、本地 1844 的差异就出自这里；修复后 1596，与真机同量级。
* **模板 override 退役**：`x1` / `x4` 上游已自行对齐真机，手工覆盖成了冗余；更要紧的是 `SIGNATURE_XSCOMMON_TEMPLATE.x12` 是个 **getter**（`${Date.now()};<会话起点>`），用对象字面量整个替换会把它求值成固定字符串——请求时间就不再滚动。现在只保留 `DATA_WEB_BUILD` / `DATA_SDK_VERSION` 两处更新值，模板交回库默认；上游的 `forUserAgent()` 也没有启用（无 UA 时它会退回 `'PC'`，而真机发的是 `"Windows"`）。

基线随之重录（9 条向量漂移），重录前先跑真机回归：游客 / 用户 CK 全端点 9/9 符合预期（含「游客无解」场景的预期失败）。

## 行为变更：HTTP 461 归为 `RISK_CONTROL` [#行为变更http-461-归为-risk_control]

461 是小红书专属的风控码，此前落进通用状态码兜底，被报成 `kind: 'unknown'` / `code: 'PLATFORM_ERROR'` / `retryable: false`——把一个明确的风控说成「未知平台错误」，可重试性也与同为风控的 403 相左。现在在 `xiaohongshuJudge` 里先于通用 helper 拦下：`kind: 'risk'` / `code: 'RISK_CONTROL'` / `retryable: true`，与 403 完全一致；业务码已给出失败结论时仍以业务码为准，判定顺序不变。

461 的典型面目是**伪装成成功的空壳**：HTTP 461 配 `{"code":0,"success":true,"msg":"成功","data":{}}`——只看响应体像是成功了，只有状态码能暴露它。它不进传输层自动退避（那条路只认 429 与 ≥500），重试由调用方按 `retryable` 与分钟级的恢复窗口自行决定。

## 行为变更：翻页中途失败返回部分结果 [#行为变更翻页中途失败返回部分结果]

声明式翻页此前是「中间任何一页失败 → 整体失败」；现在只要**首屏已成功取到过页**，后续某页被平台拒绝就返回**部分结果**：已取到的条目一条不丢、不额外标注——调用方看到的就是一次正常成功。首屏就失败仍是整体失败（没有部分可言）。`hasMore` 为假、本页为空、某一页被拒都会提前收尾。

这条规则影响**四个平台所有分页端点*&#x2A;，它意味着 &#x2A;*`success: true` 不再等于「取满了目标条数」**：需要精确数量的调用方，拿 `data` 里的条目数与目标比对，别只看信封。小红书游客评论就是典型场景——首页 10 条正常返回、第二页必撞 461 硬门，现在端点交出那 10 条，而不是整个调用失败。这是 v7 对 v6 的有意偏离。

## 端点与文档：`xsec_token` 会话绑定、`userNoteList` 签名回归 `XYS_`、`noteComments` 限流实测 [#端点与文档xsec_token-会话绑定usernotelist-签名回归-xys_notecomments-限流实测]

* **`xsec_token` 与会话绑定**：实测它同时绑定「笔记 / 用户」与「发放它的会话」，游客下跨会话必 461。`noteDetail`、`noteComments`、`userNoteList`、`userProfile` 四个端点的参数文档已写明：须同会话现取，或带上原游客 CK。
* **`userNoteList` / `userProfile` 补 `xsec_token`**：游客必传、有效登录 CK 可省。`userNoteList` 的该参数从必填放宽为可选，`userProfile` 新增可选参数；缺 token 时 `userProfile` 只会拿到未水合的空壳页（HTTP 200 但 `userPageData={}`），`userNoteList` 直接被风控软拒。不传时 URL / query 与 v6 逐字节一致——已登录用户的既有请求不变。
* **`userNoteList` 签名改回 `XYS_`**：真机复核（2026-10-11）显示，同一游客 cookie 下 `user_posted` 用 `XYS_` 拿 200 + 真数据、用 `XYW_` 回 461 空 data；beta.2 以来「数据接口自 2026-03 拒收 XYS\_、必须换 XYW\_」的结论**未经线上验证、已被推翻**。改回后七个端点全部走 `XYS_`；`XYW_` 的实现与形状检查保留，但当前无端点引用——照「必须用 XYW\_」写会踩 461。文档站的[小红书签名验证](/docs/v7/dev/sign-verify/xiaohongshu)页、验证器与内部页（`prepare` 计数、签名组织）已同步更新。
* **`userNoteList` 响应类型收紧**：从 `any` 换成样本派生的具名类型 `XiaohongshuUserNoteListResponse`（response-types 产物同步生成）。
* **`noteComments` 限流实测**：`/comment/page` 的预算比 `/v1/feed` 紧得多——同一会话、同一时刻，`noteDetail` 能过而评论端点回 461，这正是「详情解析成功、评论却失败」的主因。超限与游客翻页硬门的表现在错误码上**分不开**（都是 461 + 伪装成功的空壳），都只能报 `RISK_CONTROL`。限流是滑动窗口、退避要到分钟级：实测 1.5 秒间隔连打 8 次，第 3 次起连续失败；窗口空闲时同一会话能连过 7 次。详见[笔记评论](/docs/v7/usage/api/http/xiaohongshu/noteComments)。
* **`number` 的文档说法修正**：不传时按单页上限**翻页取满**，而不是「默认一页」；`noteComments` 额外标明不传会多烧一次请求（游客下这第二次请求必被拒），传具体小值可把请求数降到 1。快手 `comments` 的同类描述一并修正。

## 内部：测试串行与仓库卫生 [#内部测试串行与仓库卫生]

* `vitest` 的 `fileParallelism` 从 `true` 改回 `false`：注释写的是「必须串行」，配置却一直是并行——代价是 CPU 争抢让毫秒时钟跨边界，抖音 mint 的「同一 nonce 两次签名一致」间歇性红；改回后全量连跑稳定。
* 新增 `corpus/xiaohongshu/userNoteList.requests.json` 请求集合（人可读、可重放，凭证不入库）；`work/` 与 `artifacts/` 进 `.gitignore`——逆向 case 产物与抓包落盘含实际流量与会话衍生字段，与 `.reverse-uifid/` 同一性质。

## 升级 [#升级]

安装命令见页首。

* **库使用者**：从 beta.8 升上来，**类型面只有一处收紧**——`userNoteList` 的响应从 `any` 换成具名类型（生成类型带索引签名，大多数写法不受影响；依赖 `any` 的断言可能需要调整）。需要留意的两处**运行时行为**：
  1. 小红书 461 现在报 `risk` / `RISK_CONTROL`（原 `unknown` / `PLATFORM_ERROR`），`retryable` 从 `false` 变 `true`——按错误码或 `retryable` 分流的代码需要检查；
  2. 分页端点中途失败现在返回部分结果（四个平台都生效）——需要精确条数的调用方，改为拿 `data` 里的条目数与目标比对，别只看 `success`。
* **小红书调用方**：`userNoteList` 的 `xsec_token` 从必填放宽为可选（游客仍须传，已传的代码不受影响）；游客调用 `noteComments` 最多拿到首页 10 条，且该端点限流更紧——需要完整评论请配有效登录 CK，重试按分钟级退避。
* **依赖变化**：`@ikenxuan/xhshow-ts` 不再出现在 amagi 的依赖树里（算法已内联）；使用方无需任何操作。
* 从 v6 升上来的必读[迁移指南](/docs/v7/usage/migration-v7)。

遇到问题请提 [Issue](https://github.com/ikenxuan/amagi/issues)。


# 所有版本 (https://ikenxuan.github.io/amagi/docs/v7/changelog)

> amagi v7 全部版本的发布说明 —— 新功能、修复与破坏性变更



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

<Callout type="tip" title="正在使用 AI 进行开发？">
  对 Cursor、Claude Code 这类 AI 编程助手说一句「帮我把 `@ikenxuan/amagi` 升级到最新版」，
  它会自动比对你当前的版本与目标版本的差异，并把必要的改动应用到代码里。
  了解更多请参阅[Agent Skills](/docs/v7/ai)。
</Callout>

## 7.0.0-beta.10 [#700-beta10]

2026-10-24 发布的 v7 第十个 beta —— 抖音风控挑战自动处理与验证页、扫码登录补齐四个平台、B站 Cookie 续期、15 个新端点

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.10)

***

## 7.0.0-beta.9 [#700-beta9]

2026-10-12 发布的 v7 第九个 beta —— 小红书签名算法内联（@ikenxuan/xhshow-ts 依赖退役）、游客 CK 自动铸造、全端点打通、HTTP 461 归为 RISK\_CONTROL、翻页中途失败返回部分结果

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.9)

***

## 7.0.0-beta.8 [#700-beta8]

2026-10-05 发布的 v7 第八个 beta —— 签名验证扩成全平台入口；抖音 403 根因修复与访客 id 自动铸造（SIGNATURE\_REFUSED 归因、verify\_center 判人机验证、缺访客 id 自动铸造并合并）

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.8)

***

## 7.0.0-beta.7 [#700-beta7]

2026-10-02 发布的 v7 第七个 beta —— SDK 参数类型语义化：数字参数告别 unknown、B站评论枚举收窄、内部翻页参数退场；抖音弹幕加 7 天保险丝与分片限流

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.7)

***

## 7.0.0-beta.6 [#700-beta6]

2026-09-29 发布的 v7 第六个 beta —— 开放 sign-steps 子入口精细控制反爬参数，修抖音裸请求丢 msToken，收敛 fetcher 类型打印

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.6)

***

## 7.0.0-beta.5 [#700-beta5]

2026-09-25 发布的 v7 第五个 beta —— 移除 chalk 子路径导出，端点契约新增 aggregate 钩子与签名器名收窄

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.5)

***

## 7.0.0-beta.4 [#700-beta4]

2026-09-21 发布的 v7 第四个 beta —— 修复发版脚本的幻影暂存

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.4)

***

## 7.0.0-beta.3 [#700-beta3]

2026-09-21 发布的 v7 第三个 beta —— 发版链路从 release-please 换成自研脚本

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.3)

***

## 7.0.0-beta.2 [#700-beta2]

2026-09-20 发布的 v7 第二个 beta —— 抖音搜索翻页修复与小红书签名适配

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.2)

***

## 7.0.0-beta.1 [#700-beta1]

2026-09-17 发布的 v7 首个公开版本 —— 端点注册表驱动的重构

[阅读完整发布说明 →](/docs/v7/changelog/7.0.0-beta.1)


# 新增接口 (https://ikenxuan.github.io/amagi/docs/v7/dev/add-api)

> v7 中新增一个平台接口只需一份端点声明



# 新增接口 [#新增接口]

v7 起，给平台加一个数据接口只剩一个**实质步骤**：在 `endpoints/` 下新建一份端点声明（用该平台的 `defineXxxEndpoint`，如抖音 `defineDouyinEndpoint`）。参数类型、运行时校验、请求构造、签名、HTTP 路由、fetcher 方法、返回类型全部由声明派生 —— 不再有 v6 那种「改 8 步、动 11–15 个文件」的流程。

实现之前建议先读两处真实代码，建立直观认识：

* 端点声明模板：`packages/core/src/platforms/douyin/endpoints/videoWork.ts`
* 注册表汇总：`packages/core/src/platforms/douyin/endpoints/index.ts`

## 第 1 步：新建端点声明文件 [#第-1-步新建端点声明文件]

在 `packages/core/src/platforms/<平台>/endpoints/` 下新建 `<短名>.ts`，用该平台的 `defineXxxEndpoint` 声明端点 —— 它和 `type` 都从同目录 `./define` 里取。抖音 `videoWork` 的真实声明长这样：

```ts title="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
})

```

<Callout type="info">
  **为什么是 `defineDouyinEndpoint` 而不是通用 `defineEndpoint`？** 平台专属的这层只做一件事：把
  `sign` 的字符串分支从宽 `string` 收窄到**本平台签名器表推导出的名字联合** —— 抖音是
  `'a-bogus' | 'x-bogus'`、B站 `'wbi' | 'qtparam'`、快手 `'hxfalcon'`、小红书是 `xhs-*` 那七个。
  名字写错（如 `'a-bogas'`）**编译期即报错**，不必等运行时查表抛 `未注册的签名器`。运行时它仍是恒等
  函数，其余行为与 `defineEndpoint` 完全一致 —— 但直接 import 通用 `defineEndpoint` 会绕过这道收窄，
  所以端点文件从同目录 `./define` 一次性取 `defineXxxEndpoint` 与 `type`。
</Callout>

换成你的接口时，逐个替换这些字段（`name` / `route` / `doc` / `params` 四个是**必填**，缺一个编译或 CI 就会拦下来）：

| 声明字段     | 做什么                                                 | 取值来源                                                                                                                                     |
| -------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | 端点全名 `<平台>.<短名>`                                    | 该平台已有声明的命名习惯                                                                                                                             |
| `route`  | HTTP 路由路径，**同平台内唯一**                                | v6 的路径风格（snake\_case）保持不变                                                                                                                |
| `doc`    | 文档元数据：OpenAPI 的 `summary` / `description` 的**唯一出处** | `summary` 必写：**中文名词短语、不带句号、≤40 字**（如 `'视频作品详细信息'`）；一句话讲不完的约束才补可选的 `description`。&#x2A;*不要写 `tags`** —— 声明里根本没这个键，tag 由生成器从 `name` 的平台段派生 |
| `params` | zod schema                                          | 参数类型和校验的**唯一出处**，不再手写第二遍                                                                                                                 |
| `build`  | 按参数构造请求描述                                           | URL 构造放在同目录 `api.ts` 的纯函数里                                                                                                               |
| `sign`   | 签名声明                                                | 平台签名器表里的名字（`defineXxxEndpoint` 已把它收窄到本平台签名器名联合，写错名字编译期即报错）；不签名的接口写 `false`                                                               |

还有一处登记：在 `packages/core/test/types/response-mapping.test-d.ts` 里加一行 —— 补样本 + `pnpm gen:types` 之后，`packages/core/test/contracts/response-source.test.ts` 会红，并直接告诉你这一行该换成什么。

`doc` 在类型上是可选的（已有端点一个不改也能编译），但**新增端点必写**：`packages/core/test/contracts/endpoint-doc.test.ts` 拿四个注册表逐个断言 `doc.summary` 非空、≤40 字、不以句号结尾、同平台内不重复 —— 漏一个 CI 直接红。

### 响应类型：**在 Web 控制台录一份样本** [#响应类型在-web-控制台录一份样本]

历史做法是「抓一次响应 → 贴进第三方 JSON→TS 在线工具 → 把结果拷回仓库 → **把 JSON 扔掉**」。转换那一步本来就只占十分钟，真正贵的是「重新取得证据」和「确认没漏变体」—— 而证据每次都被扔掉了。后果是：改一个字段要重新抓一遍；想知道某个字段为什么是可选的，没人答得上来；发现新变体全靠碰巧遇到。

现在这件事有工具：**本地 Web 控制台**（`packages/web`，Vite + React + Tailwind + HeroUI）。一条命令起两侧：

```bash
pnpm console   # Node 侧（默认只监听 127.0.0.1:7345）+ 浏览器侧（Vite 把 /api/* 代理过去）
```

要分两个终端跑就 `pnpm console:server` 与 `pnpm console:web` —— **两个都得起**，只起浏览器侧时每个请求都会失败。

cookie 从环境变量读（`AMAGI_COOKIE_DOUYIN` / `AMAGI_COOKIE_BILIBILI` / `AMAGI_COOKIE_KUAISHOU` / `AMAGI_COOKIE_XIAOHONGSHU`），页面上一个字都不回显。

界面上一趟走完：左栏搜到你的新端点 → 填参（表单由端点的 zod schema 派生，一个都不手写）→ 点「发送」，或者「批量 N 组」按参数矩阵录一轮 → **同屏看响应体与它的类型声明**（三栏并排：请求 / 响应 / 类型；「类型」栏还有「已提交」「diff」「对比」三页）→ 「留下 / 丢掉」 → 「生成类型」。产物落在 `packages/response-types/src/generated/`（独立包，core 当 devDep 装、透给下游），全量重新生成仍然是 `pnpm gen:types`；生成完**重建一次那个包**（`pnpm --filter @ikenxuan/amagi-response-types build`），core 的类型解析指到它的 `dist/`。

**中间那个「人看一眼」不是形式。** 录制与入库分开两步，因为「这份该不该留」无法自动判断：错误页与风控页都是合法 JSON，混进去会让业务字段全变成可选可 null，而**没有任何测试会红**；两份同形样本对类型的贡献又是零 —— 那两份 B站 `comments` 只差一个 `number` 参数，2.57 MB 换来零收益。

<Callout type="info">
  **样本留在本地，不进 git**（`.gitignore` 掉了 `corpus/**/*.json`，例外只有人写的
  `seeds.json` 与 `*.doc.json`）。它是重新生成类型的输入，不是可提交的证据 ——
  三条理由、代价，以及产物文件头那个**溯源块**（几份样本、参数哈希、录制日期、amagi 版本）
  见[贡献指南](/docs/v7/dev/contributing)的「响应样本留在本地，不进 git」一节。

  脱敏由 `packages/typegen` 的 `scrubSample` 自动做，但**脱敏清单要人看**：`suspects`
  是「像密钥但没有规则匹配上」的路径。批量录制 `pnpm record:corpus` 还在，降级成辅助 ——
  它录出来的东西还是得一份一份在控制台里过。命令全貌见[贡献指南的「corpus 工作流」](/docs/v7/dev/contributing#corpus-工作流)。
</Callout>

<Callout type="warn">
  样本**目前只覆盖 62 / 80 个端点**，而且大多只有一份：不透明 ID（`aweme_id` / `sec_uid` /
  `bvid`）没法生成、只能来自 `corpus/seeds.json` 或依赖图，而多数平台的种子还没填。
  所以新增端点时 `response` 槽位**照旧写手写类型令牌**（上面那张表的最后一行）——
  生成树与手写树是**并存**的两棵，前缀刻意不同名（生成 `BilibiliEmojiList_V0` /
  手写 `BiliEmojiList`），调用处一眼可辨读的是哪棵。

  录样本不是替代手写类型，是让下一次改这个类型的人有据可查。
</Callout>

一份端点声明的字段大致按「调一次接口」的流程往下写（`①`–`⑧` 对应[项目架构](/docs/v7/dev/architecture)的管线图）—— 除必填四项外都可选、按需添：

<Steps>
  <Step>
    ### 必填骨架 [#必填骨架]

    `name` / `route` / `params` / `doc`（见上表），其余全部可选。
  </Step>

  <Step>
    ### ② `prepare`（可选） [#-prepare可选]

    发请求前换游客 cookie、取密钥；多数端点不写。
  </Step>

  <Step>
    ### ③ `build` → ④ `sign` [#-build---sign]

    `build` 按参数拼请求（**返回数组 = 多个请求并发**）；`sign` 写签名器名 / `false`（不签）/ 一次性函数。
  </Step>

  <Step>
    ### ⑥ `decode` → ⑦ `judge`（可选） [#-decode---judge可选]

    ⑤ 是框架发请求。非 JSON 响应（protobuf / 多段 JSON / HTML）在 `decode` 解；`judge` 覆盖平台默认判定。
  </Step>

  <Step>
    ### ⑧ 收尾整形（可选，三选一） [#-收尾整形可选三选一]

    `normalize`（通用兜底）/ `aggregate`（同构分段并发）/ `paginate.merge`（翻页），最多写一个 —— `aggregate` 与 `normalize` 同时写会**编译报错**。
  </Step>

  <Step>
    ### `response` [#response]

    响应类型令牌 `type<T>()`，**data 的类型只从这里来**。
  </Step>
</Steps>

完整字段清单、每个槽位的实际使用量与设计取舍，见[项目架构](/docs/v7/dev/architecture)的「端点声明」一节与[端点注册表](/docs/v7/dev/internals/registry)。

## 第 2 步：登记进 registry [#第-2-步登记进-registry]

在平台注册表汇总文件（`endpoints/index.ts`）里把新声明登记进去：

```ts title="packages/core/src/platforms/douyin/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
```

登记后还有三件机械事：

1. **把声明与响应类型加进该文件尾部的 re-export 列表**（照抄现有行）。
2. **去 `client/method-names.ts` 加一条映射。** 这是必需的，不只对不规则名 —— 见下面「方法名」那条。
3. **同步被锁死的计数判据。** 当前总数是 **80**（抖音 26、B站 27、快手 14、小红书 13），它在这些地方被写死，逐一改到位：

   | 文件                                                         | 要改什么                                                       |
   | ---------------------------------------------------------- | ---------------------------------------------------------- |
   | `test/contracts/endpoint-doc.test.ts`                      | 逐平台数 + 合计 80                                               |
   | `test/client/method-names.test.ts`                         | 映射表条数、逐平台数，以及「不规则 N 条 / 其余 N 条是规则映射」两条 —— 你的新方法名落在哪一边决定改哪个 |
   | `test/openapi/spec.test.ts`                                | `paths` 条数，以及「N 个端点带响应类型」                                  |
   | `test/server/openapi-route.test.ts`                        | `paths` 条数（三处）                                             |
   | `test/platforms/<平台>/endpoints.test.ts`                    | 该平台 registry 的端点数 + **路由清单**                               |
   | `test/types/response-mapping.test-d.ts`                    | 该平台的 `describe` 标题与新增一行类型断言                                |
   | `test/contract/__snapshots__/fetcher-surface.test.ts.snap` | 四组方法名快照，跑 `vitest -u` 更新                                   |
   | `test/contracts/endpoint-paginate.test.ts`                 | **声明了 `paginate` 才要改** —— 分页端点总数（当前 15）                    |
   | `test/openapi/response-schemas.test.ts`                    | **新端点的响应类型进了生成树才要改** —— `it.each` 的抽样验收清单                  |

   文档站里也写着这些数字：`content/docs/v7/dev/internals/registry.mdx`（规模、派生物表、可选槽位使用量）与本页。

## 这一步之后：全部自动派生 [#这一步之后全部自动派生]

登记完成即接口可用，以下东西**不需要你维护**：

* **fetcher 方法。** `client.douyin.fetcher.fetchXxx` 与静态 `douyinFetcher.fetchXxx` 都从 registry 派生（Proxy 懒加载，方法集合自动跟随注册表），参数与返回类型由声明推导，自动走 v7 信封。
* **校验。** 参数 schema 即校验，校验失败返回 `success: false` 信封（不再 `throw`）。
* **HTTP 路由。** `route` 由服务端自动注册成 `/api/<平台>/<route>`，不再手写路由文件。
* **返回类型。** `response` / `normalize` / `compute` 推导出精确类型；声明过的字段有补全，平台新加的字段读出来不算编译错误。
* **文档与测试清单。** 方法与路由清单由注册表推出，不再有手写的第二份事实。

### 方法名：规则名也要登记 [#方法名规则名也要登记]

fetcher 方法名默认按「`fetch` + 端点短名首字母大写」派生，只有 16 个不规则名（`parseWork`、`searchContent`、`convertAvToBv` 等）**需要**那张映射表才能拼出来。

但**每个新端点都必须在 `client/method-names.ts` 里登记一行**，规则名也一样。兜底规则救不了你，因为有两处会红：

* `packages/docs/scripts/generate-docs.ts` 在映射表里查不到短名时直接抛，于是 `pnpm build:docs` 失败 —— 而它是 CI 必需检查；
* `test/client/method-names.test.ts` 把映射表的方法名集合与**活 fetcher 的键**逐条比对，活 fetcher 多一个方法即失败。

### 常见形态的写法 [#常见形态的写法]

| 你想做的事       | 写法                                                                                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 无参接口        | `params: zod.object({})`，fetcher 方法可以省略 options（见抖音 `emojiList`）                                                                                    |
| 数字参数（可传字符串） | `zod.coerce.number()`（快手的 `count` 就是这么强转的）                                                                                                          |
| 必填与文案       | `zod.string().min(1, { error: '中文提示' })`，文案直接写在 schema 上                                                                                            |
| 声明式翻页       | `paginate` 槽位声明 `maxPageSize` / `items` / `hasMore` / `nextParams` / `merge`（收尾），一页与最终返回不同形时加 `page` 令牌覆盖（见 `userFavoriteList` / 快手 `userWorkList`） |
| 签名的接口       | `sign` 给原子反爬参数清单，如 `[msToken(184), aBogus(), secsdk()]`，按 phase 排序执行（见抖音 `videoWork`）                                                               |
| 不签名的接口      | `sign: false`（见抖音 `guestUserInfo` / `emojiResourceMeta`）                                                                                            |

## 验证 [#验证]

```bash
pnpm typecheck     # 类型检查（含文档站的三道静态门）
pnpm lint          # 代码检查
pnpm format:check  # 格式检查（oxfmt 只读版）
pnpm test          # vitest：端点用例 + fetcher 表面快照 + registry 结构锁 + doc.summary 钉子
pnpm openapi       # 重新生成 openapi.json（**必须提交**）
pnpm openapi:check # 已提交的 openapi.json 与四个 registry 逐字节一致
pnpm deps:check    # dpdm：必须报 0 环
pnpm build:docs    # 文档站整站构建，含 80 页端点文档的重新生成
```

这份清单之外的 `openapi:check` 与 `build:docs` 也是 CI 的必需检查 —— 只跑前四条**发现不了**「忘了重新生成 `openapi.json`」和「忘了登记方法名」。

用你的新接口跑一次端到端：`client.<platform>.fetcher.fetchXxx(...)` 成功返回信封后，任务就完成了。

## 想知道派生链路的全貌 [#想知道派生链路的全貌]

这一页只讲「怎么做」。声明里每个字段被谁读取、派生出哪些产物、注册表如何到达 client 与 server，见[端点注册表](/docs/v7/dev/internals/registry)。


# 项目架构 (https://ikenxuan.github.io/amagi/docs/v7/dev/architecture)

> amagi v7 的目录布局、依赖方向与核心概念



# 项目架构 [#项目架构]

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

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

<Callout type="info">
  本页是**总览**：每一层做什么、依赖方向怎么定、端点声明长什么样。
  逐子系统的机制细节（管线九个阶段、签名器装配、事件三根线、翻页收敛条件、导出面全貌）
  在[内部机制](/docs/v7/dev/internals)那一组里 —— 那几页写给 AI 代理与要改内部结构的人。
</Callout>

## 目录结构 [#目录结构]

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

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

<Files>
  <Folder name="src">
    <File name="index.ts" />

    <Folder name="client">
      <File name="createClient.ts" />

      <File name="fetcher.ts" />

      <File name="method-names.ts" />

      <File name="runtime.ts" />

      <File name="static.ts" />

      <Folder name="request">
        <File name="adapter.ts" />

        <File name="index.ts" />

        <File name="profile.ts" />
      </Folder>
    </Folder>

    <Folder name="exports">
      <File name="axios.ts" />

      <File name="compat.ts" />

      <File name="express.ts" />

      <File name="sign-steps.ts" />

      <File name="signing.ts" />
    </Folder>

    <Folder name="contracts">
      <File name="cookie.ts" />

      <File name="endpoint.ts" />

      <File name="error.ts" />

      <File name="meta.ts" />

      <File name="platform.ts" />

      <File name="request-options.ts" />

      <File name="request.ts" />

      <File name="response-schema.ts" />

      <File name="result.ts" />

      <File name="session.ts" />

      <File name="ua.ts" />
    </Folder>

    <Folder name="model">
      <File name="events.ts" />

      <File name="index.ts" />

      <Folder name="fetchers">
        <File name="index.ts" />

        <Folder name="bilibili">
          <File name="index.ts" />
        </Folder>

        <Folder name="kuaishou">
          <File name="index.ts" />
        </Folder>

        <Folder name="douyin">
          <File name="auth.ts" />

          <File name="index.ts" />
        </Folder>

        <Folder name="xiaohongshu">
          <File name="index.ts" />
        </Folder>
      </Folder>
    </Folder>

    <Folder name="runtime">
      <File name="events.ts" />

      <File name="execute.ts" />

      <File name="paginate.ts" />

      <File name="session.ts" />
    </Folder>

    <Folder name="server">
      <File name="auth.ts" />

      <File name="index.ts" />

      <File name="openapi.ts" />

      <File name="response-schemas.generated.ts" />

      <File name="routes.ts" />
    </Folder>

    <Folder name="transport">
      <File name="axiosJson.ts" />

      <File name="client.ts" />

      <File name="legacy.ts" />

      <File name="retry.ts" />

      <File name="safeJson.ts" />

      <File name="trace.ts" />
    </Folder>

    <Folder name="types">
      <File name="BilibiliAPIParams.ts" />

      <File name="DouyinAPIParams.ts" />

      <File name="KuaishouAPIParams.ts" />

      <File name="NetworksConfigType.ts" />

      <File name="XiaohongshuAPIParams.ts" />

      <File name="generated.ts" />

      <File name="index.ts" />

      <Folder name="ReturnDataType">
        <File name="index.ts" />

        <Folder name="Bilibili">
          <File name="DynamicType.ts" />

          <File name="index.ts" />

          <Folder name="AV2BV">
            <File name="AV2BV_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="ArticleCard">
            <File name="ArticleCard_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="ArticleContent">
            <File name="ArticleContent_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="ArticleInfo">
            <File name="ArticleInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="BV2AV">
            <File name="BV2AV_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="BangumiVideoInfo">
            <File name="BangumiVideoInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="BangumiVideoPlayurlIsLogin">
            <File name="BangumiVideoPlayurlIsLogin_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="BangumiVideoPlayurlNoLogin">
            <File name="BangumiVideoPlayurlNoLogin_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="BiliCommentReply">
            <File name="BiliCommentReply_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="Captcha">
            <File name="index.ts" />

            <Folder name="ApplyCaptcha">
              <File name="ApplyCaptcha_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="ValidateCaptcha">
              <File name="ValidateCaptcha_V0.ts" />

              <File name="index.ts" />
            </Folder>
          </Folder>

          <Folder name="ColumnInfo">
            <File name="ColumnInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="Dynamic">
            <File name="index.ts" />

            <Folder name="DYNAMIC_TYPE_ARTICLE">
              <File name="DYNAMIC_TYPE_ARTICLE_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="DYNAMIC_TYPE_AV">
              <File name="DYNAMIC_TYPE_AV_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="DYNAMIC_TYPE_DRAW">
              <File name="DYNAMIC_TYPE_DRAW_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="DYNAMIC_TYPE_FORWARD">
              <File name="index.ts" />

              <Folder name="Forward">
                <File name="index.ts" />

                <Folder name="DYNAMIC_TYPE_AV">
                  <File name="DYNAMIC_TYPE_AV_V0.ts" />

                  <File name="index.ts" />
                </Folder>

                <Folder name="DYNAMIC_TYPE_LIVE_RCMD">
                  <File name="DYNAMIC_TYPE_LIVE_RCMD_V0.ts" />

                  <File name="index.ts" />
                </Folder>

                <Folder name="DYNAMIC_TYPE_WORD">
                  <File name="DYNAMIC_TYPE_WORD_V0.ts" />

                  <File name="index.ts" />
                </Folder>

                <Folder name="DYNAMIC_TYPE_DRAW">
                  <File name="DYNAMIC_TYPE_DRAW_V0.ts" />

                  <File name="index.ts" />
                </Folder>
              </Folder>
            </Folder>

            <Folder name="DYNAMIC_TYPE_LIVE_RCMD">
              <File name="DYNAMIC_TYPE_LIVE_RCMD_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="DYNAMIC_TYPE_WORD">
              <File name="DYNAMIC_TYPE_WORD_V0.ts" />

              <File name="index.ts" />
            </Folder>
          </Folder>

          <Folder name="DynamicInfo">
            <File name="index.ts" />
          </Folder>

          <Folder name="EmojiList">
            <File name="EmojiList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="LiveRoomDef">
            <File name="LiveRoomDef_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="LiveRoomDetail">
            <File name="LiveRoomDetail_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="Login">
            <File name="index.ts" />

            <Folder name="CheckQrcode">
              <File name="CheckQrcode_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="LoginStatus">
              <File name="LoginStatus_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="NewLoginQrcode">
              <File name="NewLoginQrcode_V0.ts" />

              <File name="index.ts" />
            </Folder>
          </Folder>

          <Folder name="OneWork">
            <File name="OneWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="ProtobufDanmaku">
            <File name="ProtobufDanmaku_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserDynamic">
            <File name="index.ts" />
          </Folder>

          <Folder name="UserFullView">
            <File name="UserFullView_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserLiveStatus">
            <File name="UserLiveStatus_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserProfile">
            <File name="UserProfile_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserSpaceInfo">
            <File name="UserSpaceInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="VideoPlayurlIsLogin">
            <File name="VideoPlayurlIsLogin_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="VideoPlayurlNoLogin">
            <File name="VideoPlayurlNoLogin_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="WorkComments">
            <File name="WorkComments_V0.ts" />

            <File name="index.ts" />
          </Folder>
        </Folder>

        <Folder name="Douyin">
          <File name="index.ts" />

          <Folder name="ArticleWork">
            <File name="ArticleWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="CommentReply">
            <File name="CommentReply_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="DyDanmakuList">
            <File name="DyDanmakuList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="EmojiList">
            <File name="EmojiList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="EmojiProList">
            <File name="EmojiProList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="EmojiResourceMeta">
            <File name="EmojiResourceMeta_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="GuestMusicAwemeList">
            <File name="GuestMusicAwemeList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="GuestMusicInfo">
            <File name="GuestMusicInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="GuestUserInfo">
            <File name="GuestUserInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="ImageAlbumWork">
            <File name="ImageAlbumWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="LoginQrcode">
            <File name="LoginQrcode_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="MusicWork">
            <File name="MusicWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="PassportLogin">
            <File name="PassportLogin.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="SearchInfo">
            <File name="index.ts" />

            <Folder name="SearchInfoUser">
              <File name="SearchInfoUser_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="SearchInfoVideo">
              <File name="SearchInfoVideo_V0.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="SearchInfoGeneral">
              <File name="SearchInfoGeneral_V0.ts" />

              <File name="index.ts" />
            </Folder>
          </Folder>

          <Folder name="SlidesWork">
            <File name="SlidesWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="SuggestWords">
            <File name="SuggestWords_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserFavoriteList">
            <File name="UserFavoriteList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserInfo">
            <File name="UserInfo_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserLiveVideos">
            <File name="UserLiveVideos_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserPostVideos">
            <File name="UserPostVideos_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserRecommendList">
            <File name="UserRecommendList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="VideoWork">
            <File name="VideoWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="WorkComments">
            <File name="WorkComments_V0.ts" />

            <File name="index.ts" />
          </Folder>
        </Folder>

        <Folder name="Xiaohongshu">
          <File name="index.ts" />

          <Folder name="HomeFeed">
            <File name="HomeFeed_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="NoteComments">
            <File name="NoteComments_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="OneNote">
            <File name="OneNote_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="SearchNotes">
            <File name="SearchNotes_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="XiaohongshuEmojiList">
            <File name="XiaohongshuEmojiList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="XiaohongshuUserNoteList">
            <File name="XiaohongshuUserNoteList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="XiaohongshuUserProfile">
            <File name="XiaohongshuUserProfile_V0.ts" />

            <File name="index.ts" />
          </Folder>
        </Folder>

        <Folder name="Kuaishou">
          <File name="index.ts" />

          <Folder name="Danmaku">
            <File name="Danmaku_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="EmojiList">
            <File name="EmojiList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="LiveRoomDetail">
            <File name="LiveRoomDetail_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="OneWork">
            <File name="OneWork_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserCommon">
            <File name="UserCommon_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserHomeDetail">
            <File name="UserHomeDetail_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserProfile">
            <File name="UserProfile_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="UserWorkList">
            <File name="UserWorkList_V0.ts" />

            <File name="index.ts" />
          </Folder>

          <Folder name="WorkComments">
            <File name="WorkComments_V0.ts" />

            <File name="index.ts" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>

    <Folder name="utils">
      <File name="errors.ts" />

      <File name="md5.ts" />
    </Folder>

    <Folder name="validation">
      <File name="bilibili.ts" />

      <File name="douyin.ts" />

      <File name="index.ts" />

      <File name="kuaishou.ts" />

      <File name="legacy.ts" />

      <File name="utils.ts" />

      <File name="xiaohongshu.ts" />
    </Folder>

    <Folder name="verify">
      <File name="data.ts" />

      <File name="index.ts" />

      <File name="page.generated.ts" />
    </Folder>

    <Folder name="platforms">
      <Folder name="bilibili">
        <File name="api.ts" />

        <File name="config.ts" />

        <File name="cookieRefresh.ts" />

        <File name="judge.ts" />

        <File name="routes.ts" />

        <File name="utils.ts" />

        <Folder name="decode">
          <File name="danmaku.ts" />
        </Folder>

        <Folder name="session">
          <File name="qrcode.ts" />
        </Folder>

        <Folder name="sign">
          <File name="bv2av.ts" />

          <File name="qtparam.ts" />

          <File name="signers.ts" />

          <File name="steps.ts" />

          <File name="wbi.ts" />
        </Folder>

        <Folder name="endpoints">
          <File name="articleCards.ts" />

          <File name="articleContent.ts" />

          <File name="articleInfo.ts" />

          <File name="articleListInfo.ts" />

          <File name="avToBv.ts" />

          <File name="bangumiInfo.ts" />

          <File name="bangumiStream.ts" />

          <File name="bvToAv.ts" />

          <File name="captchaFromVoucher.ts" />

          <File name="commentReplies.ts" />

          <File name="comments.ts" />

          <File name="define.ts" />

          <File name="dynamicDetail.ts" />

          <File name="emojiList.ts" />

          <File name="index.ts" />

          <File name="liveRoomInfo.ts" />

          <File name="liveRoomInit.ts" />

          <File name="loginQrcode.ts" />

          <File name="loginStatus.ts" />

          <File name="qrcodeStatus.ts" />

          <File name="uploaderTotalViews.ts" />

          <File name="userCard.ts" />

          <File name="userDynamicList.ts" />

          <File name="userLiveStatus.ts" />

          <File name="userSpaceInfo.ts" />

          <File name="validateCaptcha.ts" />

          <File name="videoDanmaku.ts" />

          <File name="videoInfo.ts" />

          <File name="videoStream.ts" />
        </Folder>
      </Folder>

      <Folder name="douyin">
        <File name="api.ts" />

        <File name="captcha.ts" />

        <File name="config.ts" />

        <File name="cookie.ts" />

        <File name="credential.ts" />

        <File name="credentialRequest.ts" />

        <File name="deviceFp.ts" />

        <File name="guestChallenge.ts" />

        <File name="guestCredential.ts" />

        <File name="judge.ts" />

        <File name="loginState.ts" />

        <File name="mint.ts" />

        <File name="referer.ts" />

        <File name="routes.ts" />

        <File name="ttwid.ts" />

        <File name="utils.ts" />

        <File name="webParams.ts" />

        <File name="webid.ts" />

        <Folder name="anticrawler">
          <File name="acNonce.ts" />

          <File name="captcha.ts" />

          <File name="detect.ts" />

          <File name="index.ts" />

          <File name="solver.ts" />

          <File name="waf.ts" />
        </Folder>

        <Folder name="decode">
          <File name="multiJson.ts" />
        </Folder>

        <Folder name="endpoints">
          <File name="commentReplies.ts" />

          <File name="comments.ts" />

          <File name="danmakuList.ts" />

          <File name="define.ts" />

          <File name="dynamicEmojiList.ts" />

          <File name="emojiList.ts" />

          <File name="emojiResourceMeta.ts" />

          <File name="guestMusicAwemeList.ts" />

          <File name="guestMusicInfo.ts" />

          <File name="guestUserInfo.ts" />

          <File name="imageAlbumWork.ts" />

          <File name="index.ts" />

          <File name="liveRoomInfo.ts" />

          <File name="loginQrcode.ts" />

          <File name="mixAweme.ts" />

          <File name="musicAwemeList.ts" />

          <File name="musicInfo.ts" />

          <File name="parseWork.ts" />

          <File name="search.ts" />

          <File name="shortUrl.ts" />

          <File name="slidesWork.ts" />

          <File name="suggestWords.ts" />

          <File name="textWork.ts" />

          <File name="userFavoriteList.ts" />

          <File name="userProfile.ts" />

          <File name="userRecommendList.ts" />

          <File name="userVideoList.ts" />

          <File name="videoWork.ts" />
        </Folder>

        <Folder name="passport">
          <File name="aBogus.ts" />

          <File name="client.ts" />

          <File name="cookieJar.ts" />

          <File name="index.ts" />

          <File name="params.ts" />

          <File name="parser.ts" />

          <File name="sm3.ts" />

          <File name="ticketGuard.ts" />

          <File name="types.ts" />

          <File name="verify.ts" />
        </Folder>

        <Folder name="session">
          <File name="qrcode.ts" />
        </Folder>

        <Folder name="sign">
          <File name="a_bogus.ts" />

          <File name="acSignature.ts" />

          <File name="decode.ts" />

          <File name="index.ts" />

          <File name="secsdkWebSign.ts" />

          <File name="signers.ts" />

          <File name="sm3.ts" />

          <File name="steps.ts" />

          <File name="tokens.ts" />

          <File name="x_bogus.ts" />
        </Folder>
      </Folder>

      <Folder name="kuaishou">
        <File name="api.ts" />

        <File name="captcha.ts" />

        <File name="config.ts" />

        <File name="did.ts" />

        <File name="judge.ts" />

        <File name="qrcodeLogin.ts" />

        <File name="routes.ts" />

        <File name="utils.ts" />

        <Folder name="endpoints">
          <File name="commentReplies.ts" />

          <File name="comments.ts" />

          <File name="danmakuList.ts" />

          <File name="define.ts" />

          <File name="emojiList.ts" />

          <File name="emotionPackageList.ts" />

          <File name="index.ts" />

          <File name="liveRoomInfo.ts" />

          <File name="loginUserProfile.ts" />

          <File name="searchUser.ts" />

          <File name="searchWorkList.ts" />

          <File name="slideFeed.ts" />

          <File name="userProfile.ts" />

          <File name="userWorkList.ts" />

          <File name="videoWork.ts" />

          <File name="videoWorkFull.ts" />
        </Folder>

        <Folder name="sign">
          <File name="he.ts" />

          <File name="helpers.ts" />

          <File name="hudr.ts" />

          <File name="index.ts" />

          <File name="primitives.ts" />

          <File name="signers.ts" />

          <File name="state.ts" />

          <File name="steps.ts" />
        </Folder>

        <Folder name="assemble">
          <File name="index.ts" />
        </Folder>
      </Folder>

      <Folder name="xiaohongshu">
        <File name="api.ts" />

        <File name="captcha.ts" />

        <File name="config.ts" />

        <File name="judge.ts" />

        <File name="qrcodeLogin.ts" />

        <File name="routes.ts" />

        <File name="session.ts" />

        <File name="utils.ts" />

        <Folder name="endpoints">
          <File name="define.ts" />

          <File name="emojiList.ts" />

          <File name="homeFeed.ts" />

          <File name="index.ts" />

          <File name="liveRoom.ts" />

          <File name="liveSquare.ts" />

          <File name="liveStatus.ts" />

          <File name="noteComments.ts" />

          <File name="noteDetail.ts" />

          <File name="searchHotList.ts" />

          <File name="searchNotes.ts" />

          <File name="searchUser.ts" />

          <File name="subComments.ts" />

          <File name="userNoteList.ts" />

          <File name="userProfile.ts" />
        </Folder>

        <Folder name="sign">
          <File name="config.ts" />

          <File name="guestCookie.ts" />

          <File name="index.ts" />

          <File name="shape.ts" />

          <File name="signers.ts" />

          <File name="steps.ts" />

          <Folder name="xhshow">
            <File name="client.ts" />

            <File name="index.ts" />

            <File name="session.ts" />

            <File name="validators.ts" />

            <Folder name="core">
              <File name="commonSign.ts" />

              <File name="crc32.ts" />

              <File name="crypto.ts" />

              <File name="index.ts" />

              <File name="ssk.ts" />

              <File name="xrap.ts" />

              <File name="xywCrypto.ts" />
            </Folder>

            <Folder name="config">
              <File name="config.ts" />

              <File name="index.ts" />

              <File name="platform.ts" />
            </Folder>

            <Folder name="generators">
              <File name="fingerprint.ts" />

              <File name="fingerprintHelpers.ts" />

              <File name="index.ts" />
            </Folder>

            <Folder name="utils">
              <File name="b1.ts" />

              <File name="bitOps.ts" />

              <File name="bws.ts" />

              <File name="encoder.ts" />

              <File name="hash.ts" />

              <File name="hexUtils.ts" />

              <File name="index.ts" />

              <File name="randomGen.ts" />

              <File name="sharding.ts" />

              <File name="urlUtils.ts" />
            </Folder>

            <Folder name="data">
              <File name="fingerprintData.ts" />

              <File name="index.ts" />
            </Folder>
          </Folder>
        </Folder>
      </Folder>

      <Folder name="legacy">
        <Folder name="bilibili">
          <File name="API.ts" />

          <File name="qtparam.ts" />

          <Folder name="sign">
            <File name="wbi.ts" />
          </Folder>
        </Folder>

        <Folder name="douyin">
          <File name="API.ts" />

          <Folder name="sign">
            <File name="index.ts" />
          </Folder>
        </Folder>

        <Folder name="kuaishou">
          <File name="API.ts" />

          <Folder name="sign">
            <File name="helpers.ts" />

            <File name="index.ts" />

            <File name="state.ts" />
          </Folder>
        </Folder>

        <Folder name="xiaohongshu">
          <File name="API.ts" />

          <File name="searchTypes.ts" />

          <Folder name="sign">
            <File name="guestCookie.ts" />

            <File name="index.ts" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

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

### contracts —— 零依赖叶子层 [#contracts--零依赖叶子层]

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

| 文件            | 内容                                                                       |
| ------------- | ------------------------------------------------------------------------ |
| `result.ts`   | `AmagiResult<T>` / `AmagiSuccess<T>` / `AmagiFailure`                    |
| `error.ts`    | `AmagiError` / `ErrorKind`（12 个大类）/ `AmagiErrorCode` / `Judge`           |
| `meta.ts`     | `AmagiMeta` / `RequestTrace` / `TraceReason`                             |
| `request.ts`  | `RequestSpec` / `RawResponse` / `RequestConfig` / 大小写不敏感的 `AmagiHeaders` |
| `cookie.ts`   | cookie 解析与序列化（全仓唯一实现）                                                    |
| `platform.ts` | `Platform` 联合类型                                                          |
| `endpoint.ts` | `EndpointDef` / `defineEndpoint` / `Registry`                            |
| `session.ts`  | 会话契约：`LoginState` / `LoginSession` / `QrcodeLoginStrategy`               |
| `ua.ts`       | 浏览器指纹基线（UA / Sec-Ch-Ua，四个平台的版本号集中一处）                                     |

### transport —— 全仓唯一发请求的地方 [#transport--全仓唯一发请求的地方]

| 文件          | 内容                                                        |
| ----------- | --------------------------------------------------------- |
| `client.ts` | `HttpClient.send(spec) → RawResponse`，收发都在这里              |
| `retry.ts`  | 重试与退避策略                                                   |
| `trace.ts`  | `RequestTrace` 收集                                         |
| `legacy.ts` | v6 低层网络入口（`fetchData` / `fetchResponse` 等，@deprecated 保留） |

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

### platforms/\<platform> —— 平台实现 [#platformsplatform--平台实现]

| 路径                   | 内容                                                    |
| -------------------- | ----------------------------------------------------- |
| `api.ts`             | URL 构造（纯函数，不发请求）                                      |
| `sign/`              | 签名算法（从 v6 原样搬迁，不改逻辑，有逐字节快照测试保护）                       |
| `judge.ts`           | 平台响应判定 → 成功 / `ErrorKind`                             |
| `config.ts`          | 默认请求头基线                                               |
| `decode/`            | protobuf / multi-JSON / HTML 等特殊解码（douyin / bilibili） |
| `assemble/`          | 多请求聚合的归一化（仅 kuaishou）                                 |
| `session/`           | 登录会话策略（仅 douyin / bilibili）                           |
| `endpoints/*.ts`     | 每端点一份 `defineEndpoint` 声明                             |
| `endpoints/index.ts` | 汇总成平台 registry                                        |

### runtime —— 管线与横切能力 [#runtime--管线与横切能力]

| 文件            | 内容                                    |
| ------------- | ------------------------------------- |
| `execute.ts`  | 端点执行管线                                |
| `paginate.ts` | 声明式翻页                                 |
| `events.ts`   | 事件总线（实例级）                             |
| `session.ts`  | 登录会话引擎（轮询循环 / 退避 / 超时 / challenge 编排） |

### client 与 server [#client-与-server]

| 路径                       | 内容                                                                                                                                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client/createClient.ts` | 门面 `createClient(options)` —— 默认导出 `amagi(options)` 与 `@deprecated` 的 `createAmagiClient` 都是它，返回 `{ events, on, once, startServer, douyin, bilibili, kuaishou, xiaohongshu }`，四个平台都带 `login`，B站另带 `refreshCredential` |
| `client/fetcher.ts`      | 从 registry 派生**绑定** fetcher（cookie 绑在 ctx，方法签名 `(options, requestConfig?)`）                                                                                                                                           |
| `client/static.ts`       | 从 registry 派生**静态** fetcher（`douyinFetcher` / `amagi.douyinFetcher` 形态，cookie 按次传）                                                                                                                                    |
| `client/method-names.ts` | 端点名 → v6 方法名（**全仓唯一手写映射**）                                                                                                                                                                                            |
| `server/routes.ts`       | 从 registry 派生 HTTP 路由                                                                                                                                                                                                 |
| `server/auth.ts`         | 可选 token 鉴权                                                                                                                                                                                                           |

## 依赖方向 [#依赖方向]

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

<Mermaid
  chart="flowchart TD
  server[&#x22;server<br/>HTTP 路由 / 可选 token 鉴权&#x22;]
  client[&#x22;client<br/>门面 + registry 派生的 fetcher&#x22;]
  runtime[&#x22;runtime<br/>执行管线 / 翻页 / 事件 / 会话&#x22;]
  platforms[&#x22;platforms<br/>端点声明 / 签名 / judge&#x22;]
  transport[&#x22;transport<br/>全仓唯一发请求的地方&#x22;]
  contracts[&#x22;contracts<br/>契约与纯类型（零依赖叶子层）&#x22;]
  server --> client --> runtime --> platforms --> transport --> contracts"
/>

即 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 侧补上。

## 数据流 [#数据流]

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

<Mermaid
  chart="flowchart TD
  F[&#x22;fetcher 方法调用<br/>client.douyin.fetcher.fetchVideoWork&#x22;]
  P1[&#x22;① 校验 params<br/>zod&#x22;]
  P2[&#x22;② prepare（可选）<br/>换 guest cookie / 取 wbi key&#x22;]
  P3[&#x22;③ build<br/>构造请求描述&#x22;]
  P4[&#x22;④ sign<br/>a_bogus / wbi / x-s / hxfalcon&#x22;]
  P5[&#x22;⑤ send<br/>transport，全仓唯一出口&#x22;]
  P6[&#x22;⑥ decode<br/>缺省按 JSON&#x22;]
  P7[&#x22;⑦ judge<br/>成功 / ErrorKind&#x22;]
  P8[&#x22;⑧ normalize / aggregate / paginate.merge（可选）<br/>整形为声明的返回类型&#x22;]
  R[&#x22;AmagiResult 信封&#x22;]
  F --> P1
  P1 -->|校验失败，不发请求| R
  P1 -->|通过| P2
  P2 --> P3 --> P4 --> P5 --> P6 --> P7
  P7 --> P8 --> R
  P7 -.->|paginate：下一页回到 ③ 重新签名| P3"
/>

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

## 端点声明 [#端点声明]

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

```ts title="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'`、写错编译期即报错，见[新增接口](/docs/v7/dev/add-api)）；它和 `defineEndpoint` 运行时都是恒等函数，全部价值在类型推导：`TParams` 从 `params` 推出，`TData` 从 `response` / `normalize` / `compute` 推出。响应类型**直接复用 v6 的 `types/ReturnDataType` 快照类型**（映射键与端点短名一一对应），v6 快照自带顶层索引签名，平台加字段不算 breaking。

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

| 槽位           | 什么时候用                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `doc`        | 文档元数据：OpenAPI `summary` / `description` 的唯一出处（类型上可选，**新增端点必写**；`tags` 不在声明里 —— 平台就是 tag，由 `name` 的平台段派生） |
| `prepare`    | 前置请求：换 guest cookie、取 wbi key、bootstrap 指纹                                                               |
| `build`      | 构造请求描述；返回数组 = 多请求聚合 / 分段并发                                                                               |
| `sign`       | 签名器名（平台专属 `defineXxxEndpoint` 把它收窄到本平台签名器名联合，写错编译期即报错）/ `false`（显式不签名）/ 一次性函数                            |
| `decode`     | 响应不是普通 JSON：protobuf / multi-JSON / HTML                                                                 |
| `paginate`   | 声明式翻页：`maxPageSize` / `items` / `hasMore` / `nextParams` / `merge`（收尾）；一页与最终返回不同形时用 `page` 令牌覆盖          |
| `partial`    | 多请求部分失败语义：`'tolerate'`（缺失部分留空）/ `'fail'`                                                                 |
| `judge`      | 覆盖平台默认判定                                                                                                 |
| `normalize`  | 把响应裁剪 / 整形为最终 `data`（**非分页、非同构分段**；分页收尾用 `paginate.merge`、同构分段收尾用 `aggregate`）                           |
| `aggregate`  | 同构分段并发（`build` 返回同形数组）的带类型收尾，取代 `normalize`；与 `normalize` **互斥** —— 同时写编译报错，另有测试门兜底                      |
| `compute`    | 纯本地计算，不发请求                                                                                               |
| `response`   | 响应类型令牌 `type<Foo>()`                                                                                     |
| `retryOn`    | 命中这些错误码时重试（如 B站 `-412` → `RISK_CONTROL`、抖音 Argus → `ANTIBOT_PAGE`）                                       |
| `retryFresh` | 重试时重新 build + 重新签名，而不是重放同一个请求（抖音换 msToken / a\_bogus 过 Argus）                                            |

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

### 声明派生出什么 [#声明派生出什么]

| 派生物                            | 来源                                                      |
| ------------------------------ | ------------------------------------------------------- |
| fetcher 方法（client 绑定形态 + 静态形态） | 声明 + `client/method-names.ts`                           |
| 参数类型与运行时校验                     | `params` schema 推导（参数类型不再手写第二遍）                         |
| HTTP 路由                        | `route` → `server/routes.ts` 注册                         |
| 响应类型                           | `response` / `normalize` / `aggregate` / `compute` 推导   |
| registry 结构测试                  | `test/platforms/<platform>/endpoints.test.ts` 锁注册表规模与路由 |

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

## 统一响应信封 [#统一响应信封]

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

```ts twoslash
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` 形状：

<TypeTable
  id="type-table-error.ts-AmagiError"
  type="{
  &#x22;id&#x22;: &#x22;error.ts-AmagiError&#x22;,
  &#x22;name&#x22;: &#x22;AmagiError&#x22;,
  &#x22;description&#x22;: &#x22;失败信封里唯一的错误载体，永不为 `undefined`&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;kind&#x22;,
      &#x22;description&#x22;: &#x22;判别键，跨平台统一的错误大类&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;code&#x22;,
      &#x22;description&#x22;: &#x22;稳定的字符串错误码，可用于 switch 与埋点&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的说明，取平台原文优先&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;retryable&#x22;,
      &#x22;description&#x22;: &#x22;是否值得重试。调用方据此决定退避还是放弃&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台原始错误码与文案，一个字都不丢&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ code: string | number; message?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;http&#x22;,
      &#x22;description&#x22;: &#x22;真实发生的 HTTP 状态（有请求才有）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ status: number; statusText?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;issues&#x22;,
      &#x22;description&#x22;: &#x22;`kind === 'validation'` 时的字段级错误&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ValidationIssue[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;raw&#x22;,
      &#x22;description&#x22;: &#x22;原始响应体。默认**连键都没有**，`createClient({ debug: true })` 且这次\n确实**拿到了响应**时才填（网络中断 / 超时那类失败没有响应体可放）。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;challenge&#x22;,
      &#x22;description&#x22;: &#x22;风控挑战（验证页地址 + 票据）。`kind === 'risk'` 且平台认得出这份响应时才有。\n\n**不受 `debug` 开关影响** —— 它是「怎么过去」这条必要信息，见\nRiskChallenge。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RiskChallenge | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;cause&#x22;,
      &#x22;description&#x22;: &#x22;底层 Error 对象，仅用于日志&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

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

## 事件总线与 meta [#事件总线与-meta]

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:*`）与各自的负载见[事件系统](/docs/v7/usage/advanced/events)，这里只列最常用的四个：

| 事件              | 时机         | 负载                |
| --------------- | ---------- | ----------------- |
| `api:success`   | 一次逻辑调用成功返回 | `{ meta, data }`  |
| `api:error`     | 一次逻辑调用失败返回 | `{ meta, error }` |
| `http:request`  | 一次底层请求即将发出 | `{ meta, trace }` |
| `http:response` | 一次底层请求已经结束 | `{ meta, trace }` |

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

<TypeTable
  id="type-table-meta.ts-AmagiMeta"
  type="{
  &#x22;id&#x22;: &#x22;meta.ts-AmagiMeta&#x22;,
  &#x22;name&#x22;: &#x22;AmagiMeta&#x22;,
  &#x22;description&#x22;: &#x22;挂在每个信封上的元信息&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;requestId&#x22;,
      &#x22;description&#x22;: &#x22;每次逻辑调用一个 id，贯穿事件、日志、trace&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;clientId&#x22;,
      &#x22;description&#x22;: &#x22;发起调用的 client 实例 id；静态 fetcher 用 `'static'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;bilibili\&#x22; | \&#x22;douyin\&#x22; | \&#x22;kuaishou\&#x22; | \&#x22;xiaohongshu\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;endpoint&#x22;,
      &#x22;description&#x22;: &#x22;端点全名，如 `'douyin.videoWork'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;durationMs&#x22;,
      &#x22;description&#x22;: &#x22;从进入 fetcher 到返回信封的总耗时&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;attempts&#x22;,
      &#x22;description&#x22;: &#x22;实际发出的 HTTP 请求数，含重试与分页。分页 3 页 + 1 次重试 = 4&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;trace&#x22;,
      &#x22;description&#x22;: &#x22;每次底层请求的明细，按发出顺序。\n\n默认不带：`createClient({ debug: true })` 时才填（同一个开关也给失败信封\n填 `error.raw`，没有单独的 trace 开关）。不开时信封上**没有 `trace`\n这个键**，而 `attempts` 照样准确 —— 计数始终发生，只有明细受开关控制。\n\n静态 fetcher（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。\n要不受开关影响地逐条观测请求，监听 `http:request` / `http:response`\n事件：它们的负载恒带 `trace`。URL 含签名参数，别在生产里无条件打印。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestTrace[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;incomplete&#x22;,
      &#x22;description&#x22;: &#x22;结果不完整时的原因：翻页端点声明了 `partial: 'tolerate'`、中途某页失败，\n信封仍是成功、`data` 里是已取到的那几页，这里是那个失败页的错误。\n\n完整结果上**没有这个键**。只看 `success` 的调用方会拿到截断的数据 ——\n在意条数的，检查这个键。没声明 `tolerate` 的翻页端点中途失败也返回部分结果，\n但**不**挂这个键，只能拿条目数与目标比对。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ kind: ErrorKind; code: AmagiErrorCode; message: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

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

## 会话（登录） [#会话登录]

扫码登录这类**多步有状态流程不是端点**：四个平台的 `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 会话。

## 术语 [#术语]

| 术语             | 含义                                                 |
| -------------- | -------------------------------------------------- |
| 端点（endpoint）   | 一个可调用的平台接口，如 `douyin.videoWork`。v6 里叫 `methodType` |
| 注册表（registry）  | 一个平台全部端点声明的汇总对象                                    |
| 信封（envelope）   | `AmagiResult<T>`，包裹 data 或 error 的统一外层结构           |
| 判定（judge）      | 把平台原始响应映射为「成功 / 某种 `ErrorKind`」的纯函数                |
| 规范化（normalize） | 把平台原始响应裁剪 / 整形为端点声明的返回类型                           |
| 会话（session）    | 多步有状态流程（如扫码登录），与单次请求的端点区分开                         |
| 凭证（credential） | 会话成功后产出的登录态，统一为 `{ cookie, expiresAt?, raw }`      |


# 贡献指南 (https://ikenxuan.github.io/amagi/docs/v7/dev/contributing)

> 提交规范和 PR 流程



# 贡献指南 [#贡献指南]

感谢你对 amagi 的贡献！本文档介绍提交规范和 PR 流程。

## 提交规范 [#提交规范]

使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。&#x2A;*允许的类型内嵌在 `.husky/husky-tasks.ts`**，`commit-msg` 钩子按它校验 —— 类型写错提交会被直接拒掉。当前十一种：

| 类型         | 说明     | 示例                                   |
| ---------- | ------ | ------------------------------------ |
| `feat`     | 新功能    | `feat: add fetchVideoTags API`       |
| `fix`      | Bug 修复 | `fix: correct parameter validation`  |
| `perf`     | 性能优化   | `perf: cache wbi keys`               |
| `revert`   | 回滚     | `revert: feat: add fetchVideoTags`   |
| `docs`     | 文档更新   | `docs: update installation guide`    |
| `style`    | 代码风格   | `style: reformat sign helpers`       |
| `chore`    | 杂项维护   | `chore: update dependencies`         |
| `refactor` | 重构     | `refactor: simplify fetcher logic`   |
| `test`     | 测试     | `test: add unit tests for sign`      |
| `ci`       | CI 配置  | `ci: tighten release changelog gate` |
| `build`    | 构建系统   | `build: bump tsdown to 0.22`         |

<Callout type="warn">
  钩子的校验正则是 `^(类型)(\(域\))?:`，&#x2A;*不接受 breaking 标记 `!`** —— `feat!:` 与 `feat(scope)!:`
  都会被拒。破坏性变更请把 `BREAKING CHANGE:` 写在提交信息的 body 里。
</Callout>

Merge / Revert / Initial commit 这类 Git 自动生成的信息在豁免名单里，不受类型校验约束。

**发版**由维护者本地跑 `pnpm run release` 完成（bumpp 交互式选版本 → 提交 → 打 `v*` tag → 推送），tag 推送触发 `.github/workflows/release.yml`：changelogithub 按上面这套类型归出 GitHub Release，然后发 npm 与 GitHub Packages。所以类型写对不只是规矩，直接决定 Release 页的分组。（2026-09-21 之前用 release-please，已退役。）

### 提交信息格式 [#提交信息格式]

```
<type>(<scope>): <subject>

<body>

<footer>
```

示例：

```
feat(bilibili): add fetchVideoTags API

- Add VideoTagsParams type
- Add validation schema
- Implement fetcher method

Closes #123
```

## 发起 PR [#发起-pr]

<Steps>
  <Step>
    ### 同步上游 [#同步上游]

    确保你的 Fork 是最新的：

    ```bash
    # 添加上游仓库（只需一次）
    git remote add upstream https://github.com/ikenxuan/amagi.git

    # 同步上游
    git fetch upstream
    git checkout main
    git merge upstream/main
    ```
  </Step>

  <Step>
    ### 创建分支 [#创建分支]

    从最新的 `main` 分支创建功能分支：

    ```bash
    git checkout -b feat/your-feature
    ```

    分支命名规范：

    * `feat/xxx` - 新功能
    * `fix/xxx` - Bug 修复
    * `docs/xxx` - 文档更新
    * `refactor/xxx` - 重构
  </Step>

  <Step>
    ### 开发与提交 [#开发与提交]

    ```bash
    # 开发...

    # 提交
    git add .
    git commit -m "feat: your feature description"
    ```
  </Step>

  <Step>
    ### 推送到你的仓库 [#推送到你的仓库]

    ```bash
    git push origin feat/your-feature
    ```
  </Step>

  <Step>
    ### 创建 Pull Request [#创建-pull-request]

    1. 在 GitHub 上打开你的 Fork 仓库
    2. 点击 "Compare & pull request"
    3. 填写 PR 描述：
       * 说明改动内容
       * 关联相关 Issue（如有）
       * 列出测试情况
    4. 提交 PR 到 `ikenxuan/amagi` 的 `main` 分支
  </Step>
</Steps>

## 代码风格 [#代码风格]

### 基本规范 [#基本规范]

* 使用 TypeScript 严格模式
* 使用 Oxlint 进行代码检查
* 运行 `pnpm fix` 自动修复格式问题；`pnpm format:check` 是它的只读版本，**CI 上跑的是这一条**

### 导入顺序 [#导入顺序]

导入顺序**不用手排**：`pnpm fix` 会跑 oxfmt，`sortImports`（`oxfmt.config.ts`）
按两组整理 —— 先是裸包名（外部依赖），空一行，然后是相对路径，各组内按路径字典序。
`import type` **不单独成组**，它按自己的路径排进相对路径那一组：

```ts title="packages/core/src/platforms/bilibili/endpoints/comments.ts"
import zod from 'zod'

import type { RequestSpec } from '../../../contracts/request'
import type { BilibiliCommentsResponse } from '../../../types/generated'
import { bilibiliApiUrls, commentModeSchema, commentTypeSchema } from '../api'
import { wbi } from '../sign/steps'
import { defineBilibiliEndpoint, internalParam, type } from './define'
```

（这段不是抄的，是 `packages/core/src/platforms/bilibili/endpoints/comments.ts` 的开头
本身 —— 之前那份手抄版本就烂过一次：它停在三条 import，而真文件的 import 一直在动
（`bilibiliApiUrls` 后面多了 `type CommentType`、`defineBilibiliEndpoint` 后面带上了 `type`、
响应类型改从 `types/generated` 取、分页收尾搬进 `paginate.merge` 后连 `PaginatedValue` 那条
import 都不再需要）。所以别写「外部 / 内部 / 类型」三组 —— 排出来不是那个样子，提交前跑一次
`pnpm fix` 就会被改回去。看第二组三行：那条 `import type` 里的 `BilibiliCommentsResponse`
（`../../../types/generated`）没有被拎出来单独成组，而是按自己的路径字典序排在最前 ——
`../../../*` 整体排在 `../api`、`./define` 前面。）

### 注释规范 [#注释规范]

函数和接口需要 JSDoc 注释：

```ts
/**
 * 获取视频标签
 * @param options - 请求参数
 * @param options.avid - 视频 AV 号
 * @param cookie - B站 Cookie
 * @returns 视频标签列表
 */
export async function fetchVideoTags(options: { avid: number }, cookie?: string) {
  // ...
}
```

## 响应样本留在本地，不进 git [#响应样本留在本地不进-git]

录到的样本落在 `corpus/<平台>/<端点>/<参数哈希>.json`，**整棵树被 `.gitignore` 掉**：
规则是 `corpus/**/*.json`，两条例外是人写的 `corpus/seeds.json` 与 `corpus/**/*.doc.json`。
进 git 的是**产物** —— `packages/response-types/src/generated/` 那棵生成出来的类型树。

这条结论是 2026-09-04 翻过来的 —— 原先写的是「提交脱敏后的精简代表」，而那两条理由
都不成立：

* **「不提交就等于放弃 `--check`」是个伪命题。** `--check` 要验的是「产物与证据一致」，
  而证据（样本）在 CI 上根本不存在。把样本提交进去只是把这个矛盾往后推一层，
  代价是每份真实响应都进了公开仓库的**永久历史**。
* **体积估错了一个数量级。** 原估「61 个端点约 1\~2 MB」，实测 12 个端点 14 份样本就
  **3.2 MB**，按这个密度铺满约 **16 MB**。而且其中 2.57 MB 是两份 B站 `comments` ——
  它们是**同一页评论**（只差一个 `number` 参数），对类型的贡献为零。
* **脱敏这道防线一直在漏。** 最近几轮连着修：残留子串、值的形状要优先于键名、
  字符串里套着的 JSON、`caption` 这个字段名没覆盖、以及「像人写的话」（长度 ≥ 4 且含
  CJK / 假名 / 谚文 / 西里尔 —— 用户写的中文文案不长、不是 URL、没有连续 ASCII 串，
  按凭证形状写的那六条判据一条都碰不到它）。往公开仓库提交真实响应，
  每多一份就多一次泄漏机会 —— 而那种泄漏是撤不回来的。

  2026-09-05 又撞上第六条，而它**不属于「按键名追不完」那一族**：前面那些防线一条都没坏，
  是**白名单自己把整块负载放过去了**。默认白名单里有一条按键名匹配
  `type|kind|code|status|result`（保判别字段用的），而命中就整棵子树都不进 ——
  B站搜索的 `data.result` 正是这个键名，而它是整块结果列表。现在默认白名单**只保标量**，
  命中容器时让路继续往下钻；「整块别动」这个能力只留给调用方显式传的 `keep`。

`packages/core/test/fixtures/kuaishou/` 那 6 份是 corpus 之前的第一批样本，仍然提交在
仓库里、被 `test/platforms/kuaishou/fixtures.test.ts` 用着。那是历史遗留，新样本不要往那儿放。

### 本地那份是「重新生成」的输入 [#本地那份是重新生成的输入]

样本不是跑完就能删的中间产物。**生成器是「N 份样本一次性进去」，没有 TS → 形状树的
反解析** —— 本地 `corpus/` 清了、换了台机器，那个端点的类型就只能重录一遍才动得了。
这是「不进 git」的直接代价，认下来了。

代价的另一半本来是「样本过期而无人知」（过期与否只有录它的那台机器知道），
所以每个生成文件的文件头带**溯源块**，让证据从产物本身读得出来：

```ts title="packages/response-types/src/generated/bilibili/CommentReplies/CommentReplies_V0.ts"
// 证据：2 份样本（amagi 6.6.0）。样本不进 git，在本地 corpus/ 里
//   92ce465b3012  2026-09-04  number / oid / root / type
//   cf888abd7b45  2026-09-04  oid / root / type
```

几份样本、各自的参数哈希与录制日期、参数键名、amagi 版本 —— 「这个类型的证据有多旧」
不用再去问人。两条刻意的约束：

* **只写绝对信息，绝不写「距今多少天」。** 相对量依赖 `now`，会让同一批样本隔天生成出
  不同的文件、`--check` 隔天就红（有一条测试专门钉这个：`now` 差四个月，产物必须逐字节
  相同）。「过期了没有」是生成时打印的告警，属于运行时，不进产物。
* **参数只写键名，不写值。** 值虽然脱敏过，但写进产物会让它跟着脱敏实现的每次调整刷 diff。

<Callout type="warn">
  **脱敏的要求一条都没降级**，只是理由换了：不再是「要提交进公开仓库」，而是
  **字段名会进产物**（脱敏只换值，键名原样喂给生成器），以及「开发机上的本地文件
  不是保险箱」。

  脱敏也不是「把值改乱」。两条规则省了样本就没用甚至有害：**同一真值换成同一假值**
  （不然分组、引用这类关系会被打散，断言反而假绿）、**位数与字符集与真值同形**
  （位数变了会顺手改掉「大整数超 `MAX_SAFE_INTEGER` 会掉精度」这类形状，
  而那正是类型要描述的东西）。结构与字段名一字不改，只换值。

  这两条现在有实现：`packages/typegen` 的 `scrubSample`。假值一律从原值哈希派生
  （同一份响应重录一遍产出逐字节相同的文件），超界整数换完仍然超界，而替换清单
  （落在样本的 `metadata.scrub` 里）**连原值的哈希都不留** —— 短值的截断哈希是可以
  爆破的。清单里的 `suspects` 是「像密钥但没有规则匹配上」的路径，要人逐条看过再决定
  加规则还是放行。做法与踩过的点见 `packages/typegen/src/scrub.ts` 的文件头。
</Callout>

## corpus 工作流 [#corpus-工作流]

响应类型是 `corpus/` 里那些样本的**纯函数**。日常入口是**本地 Web 控制台**
（`packages/web`，Vite + React + Tailwind + HeroUI），命令行留给批量与全量重建：

| 命令                                         | 做什么                                                                                                              | 什么时候用                              |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `pnpm console`                             | 控制台：一条命令起两侧 —— Node 侧（发请求 → 脱敏 → 算类型 diff → 写盘，默认只监听 `127.0.0.1:7345`）与浏览器侧（Vite，把 `/api/*` 代理过去）；任一侧退出会把另一侧一起收掉 | 平常都从这里开始                           |
| `pnpm console:server` / `pnpm console:web` | 同样那两侧，想分两个终端跑时用                                                                                                  | 需要分开看日志时                           |
| `pnpm record:corpus`                       | 遍历注册表 → 展开参数矩阵 → 发请求 → 截断 → 脱敏 → 落盘                                                                              | 要一次铺很多端点；**辅助手段**，录出来的还得一份一份在控制台里过 |
| `pnpm gen:types`                           | 从 `corpus/` 全量重新生成到 `packages/response-types/src/generated/`                                                     | 生成器改了，或者要重建整棵树                     |
| `pnpm types:check`                         | 拿手上的样本重生成一遍，与已提交产物逐字节比对，不一致退出码 1；**零样本时改成验 barrel 与产物树是否一致**                                                     | 本地有样本时验「产物与证据一致」；CI 上验「树自洽」        |

两侧**少起一个就会失败，而且失败的样子会骗人**：只起浏览器侧的话界面能打开，但每个请求都会
失败 —— Vite 的代理打到一个空端口时报 `Failed to fetch`，打到**另一个在监听的服务**上时
（比如 core 的 `pnpm dev` 默认占着 4567）会回那个服务的 404 HTML。控制台前端专门有一层判断
认出「这是 HTML 不是 server 的响应」并告诉你去起后端。`pnpm console` 就是为这件事存在的：
一条命令起两侧、`build:core` 只跑一遍、任一侧挂掉把另一侧也收掉。

cookie 在控制台右上角的抽屉里配，保存后写进仓库根的 `.env` 并立刻生效（不用重启）。
`.env.example` 是模板、进 git；`.env` 本身被 gitignore 挡着，而控制台**写之前会先确认
这一点**——`.gitignore` 里没有一条光秃秃的 `.env` 时它拒绝写，因为往一个会被提交的文件里
写 cookie 是不可撤销的。

也可以直接写 `.env` 或用 shell 环境变量：`AMAGI_COOKIE_DOUYIN` /
`AMAGI_COOKIE_BILIBILI` / `AMAGI_COOKIE_KUAISHOU` / `AMAGI_COOKIE_XIAOHONGSHU`。
&#x2A;*进程环境变量压过 `.env`**，所以 shell 里 export 过之后在界面上改那一项不会生效 ——
抽屉里会标出「来自进程环境变量」。

页面上一个字的 cookie 值都不回显：接口只回「有没有、多长、从哪来」。
控制台默认只绑回环地址；要绑别的地址必须同时给 `--token`（至少 8 位），否则**拒绝启动** ——
它能拿本机 cookie 发请求，暴露在局域网上等于把账号借出去。

几条一开始容易踩的：

* **产物是生成的，手改没有意义**。`pnpm gen:types` 先清空整棵 `generated/` 树再写，
  所以那底下不能放手写文件。`types:check` 还会认出「多出来的残留文件」——端点删掉之后
  旧产物留在树里会被下游 import，然后描述一个已经不存在的响应，而只比对文件内容
  永远发现不了这一类。
* **CI 上 `types:check` 验不了「产物与样本一致」，但验得了「树自洽」**。样本不在仓库里，
  逐字节比对就没有可比的证据；此时脚本明说「跳过比对」，**不假装通过**（早先那句
  「0 个文件一致」是个假绿灯：产物树里明明躺着几十个文件时它也会那么说）。
  它**没有**跳过的是「barrel 与产物树是否一致」（2026-09-10 补）：两层 barrel 是树的派生物，
  「树里有什么就发布什么」这件事不需要任何样本，而它正是「提交了一棵引用不出去的树」
  （根 barrel 停在零样本状态、包对外导出 0 个类型）唯一能现形的地方。真正的
  「产物与证据一致」比对仍只发生在录样本的那台机器上。
* **录制器不重试、不并发、不猜参数**。风控与限流由入库判定拒掉并打印理由，
  自动重试只会把 IP 级冷却拖成分钟级封锁。必填参数没种子就整个端点跳过——
  编一个假 ID 只会换回错误页，而错误页混进 corpus 是**静默**的：
  生成的类型会把业务字段全变成可选可 null，没有任何测试会红。
* **不透明 ID 只能来自 `corpus/seeds.json` 或依赖图**。种子放链条起点（公开账号的 UID、
  搜索关键词），其余 ID 靠依赖图从上游响应里长出来（`videoInfo` 的 `data.aid` 喂
  `comments` 的 `oid` 这种）。依赖图**手工声明**，每条边都要写 `note` 说清为什么这么走。
* **两类端点结构上录不了**，报出来就是正常的：`compute` 端点（`bvToAv` / `avToBv`
  本地算完就返回，一个网络请求都不发），以及响应体是二进制的（弹幕 protobuf——
  `{"0":31,"1":8,…}` 那种字节字典当类型证据毫无意义）。
* **会签发凭证的端点整类不录**（登录、二维码、验证码）。它们的响应里带当场有效的
  `qrcode_key`，而脱敏按键名匹配撞不上这种名字。

生成之后想知道「拿它替掉手写类型行不行」，用
`pnpm types:diff <生成产物> <手写类型>`：它按**路径**而不是类型名比
（两边名字根本对不上），差异分四类，需要人决策的只有「手写有、生成没有」那一类——
是这轮样本没覆盖到，还是平台已经删了？

## `.doc.json`：注释与形状分开存 [#docjson注释与形状分开存]

生成的响应类型是**样本的纯函数**，所以往产物里手写注释等于白写 —— 下次
`pnpm gen:types` 就冲掉了。语义要写在 sidecar 里：

```json title="corpus/bilibili/userDynamicList.doc.json"
{
  "$comment": "JSON 没有注释，说明写这里。paths 的键是字段路径，值是要生成的 JSDoc",
  "discriminantPath": "data.item.type",
  "declaredValues": ["DYNAMIC_TYPE_AV", "DYNAMIC_TYPE_DRAW", "DYNAMIC_TYPE_WORD"],
  "paths": {
    "": "一条动态。按 `data.item.type` 分成六支，收窄请用 `guards.ts` 里的 `is*`",
    "data.item.type": "动态类型（判别式）。它决定 `modules` 下有哪些键",
    "data.item.modules.module_author.mid": "作者 UID。与 `params.uid` 是同一个人"
  }
}
```

三条要点：

* **路径写法**与仓库其它地方一致：根是空串，对象键用 `.` 连，跨数组加 `[]`
  （`data.items[].id`）。空串那条注释挂在根类型上。
* **孤立 pointer 会被报出来**。指向已经不存在的路径，意味着那个字段被删了或改名了 ——
  而那正是注释开始说谎的时刻，所以它是告警而不是静默忽略。
* **共用类型上只能挂一份注释**。结构等价的子树共用一个类型（不然加一条注释就多出一份
  重复类型，人就不敢写注释了），所以两条不同的注释指向同一个位置时，第二条挂不上去并
  报 `conflict`。要么把两处写成同一句，要么让形状真的不一样。

`discriminantPath` 是可选的逃生口：欠采样时自动发现可能挑错判别式（每个变体只有一份样本时，
`id_str` 这种字段与真判别式完全同分），补样本是正解，但在补齐之前可以在这里把结论钉死。
填 `false` 表示这个端点不要判别联合。

`declaredValues` 是判别式**已声明**的全部取值，用来跟样本实测到的取值比对。它解决一个
具体的病：B站动态那两个手写 enum 声明了 27 个成员（`MajorType` 17 + `AdditionalType` 10），
而只有 6 个 `DYNAMIC_TYPE_*` 真的建了模型 —— **声明的枚举空间远大于已建模的变体，
而缺口有多大没人知道**。把清单写进来，生成时就会报两个方向的漂移：

* **声明了却从未出现** → 要么补样本，要么这些成员该删
* **样本里出现但没声明** → 平台加了新取值而手写枚举没跟上。这条更急：下游按枚举分支的
  代码会漏掉整整一支，而且不报错

两条都进 `warnings` 而不是 `summary` —— 它们要人做决定，而 summary 是告知性的。

<Callout type="info">
  `declaredValues` 只在有判别式时有意义（单类型端点没有判别式可比）。清单里写错一个取值时，
  **其余的仍然参与比对，而错的那个会被指名** —— 「整条静默失效」是这类校验最难查的失败方式。
</Callout>

## 有判别式的端点：控制台里别点「单独建新形状」 [#有判别式的端点控制台里别点单独建新形状]

录制新样本时，控制台会让人在「合并进现有类型」与「单独建新形状（`_V<n>`）」之间选一次
（新样本默认是前者）。&#x2A;*端点一旦有判别式（`.doc.json` 里钉了 `discriminantPath`），
正确答案永远是「合并」** —— 新形态会按判别字段自动成为判别联合的一支，不需要人再标什么。

点「单独建新形状」的后果（在 B站 `dynamicDetail` 上实测过）：产物里多出一个平行文件
（`DynamicDetail_V1.ts`），端点 barrel 变成 `DynamicDetailUnion | DynamicDetail_V1` ——
两套机制混在一棵树里，而那个取值本来该在的支**从判别联合里消失**，
`declaredValues` 紧接着报「声明了却从未出现」。

判断依据是 `plan.ts` 里 `shapeIndex` 的原意：&#x2A;*形态差异由响应自己说出来的（有个字段写着是哪种），
就该合并；只有「同一个端点另有完全不同的响应」才该 `_V<n>`**。

## 工具链：TypeScript 7（原生版） [#工具链typescript-7原生版]

全仓的 `typescript` 是 **7.x** —— Go 重写的原生编译器，包名与 bin 仍是 `typescript` / `tsc`，
`tsc --version` 报 `7.0.2`。**没有例外包**：连文档站也在 7 上（2026-09-15 之前它钉在 6.x）。

同一份 `tsconfig` 下 core 从 2.3 s 掉到 0.19 s，但快不是这次迁移的主要收益 ——
主要收益是**不必再为一个包留一整份 JS 编译器**。

### 怎么判断一个工具能不能上 TS7 [#怎么判断一个工具能不能上-ts7]

看它**怎么消费** TypeScript，而不是看它写没写 `typescript` 依赖：

* **spawn `tsc` 二进制**的随便 —— vitest 的 `--typecheck`、Next 的 `useTypeScriptCli` 都走这条；
* **`import ts from 'typescript'` 吃编译器 API** 的，要么自带一份 TS 副本（普通依赖而非 peer，
  像 `dpdm` 与 `ts-json-schema-generator` 那样，它俩锁的是 5.9.3，完全不受影响），
  要么就得钉 6.x。

TS7 的包入口只剩 `lib/version.cjs`（只有 `version` 与 `versionMajorMinor`，`createProgram`
之类全是 `undefined`）。**判断失误的代价是静默的**：拿到一个只有版本号的模块，
报错点离真正原因很远。新接口是 `typescript/unstable/sync` 与 `typescript/unstable/ast`。

### 文档站那两处是怎么过的 [#文档站那两处是怎么过的]

原先卡住文档站的是两个**跑在构建之外的脚本**，不是 `next build` 本身：

* **`scripts/api-extractor.ts`**（新增）—— 取代 TypeDoc 抽 `packages/core` 的公开导出面。
  TypeDoc 没有支持 TS7 的版本，在 TS7 下连 `import` 都会炸，所以是**替换**不是升级。
  它产出仍然沿用 TypeDoc 的 JSON 形状（`kind` 数值、`flags` 键名都照旧），
  于是 `generate-api-types.ts` 那 700 行渲染代码一行没动。与 TypeDoc 对齐的几条判据
  （变量还是函数、类型专用的类导出按接口出、成员按名字排序）都写在该文件头注释里，
  每一条都是对着 413 个符号的产物实测出来的。

顺带清掉的两处死依赖：仓库根与 `packages/core` 里各有一条**从未被引用**的 `typedoc`，
它们唯一的实际作用就是在新版本下顶出一条 peer 警告。

## PR 检查清单 [#pr-检查清单]

提交 PR 前，请确认：

* [ ] 类型检查通过（`pnpm typecheck`）
* [ ] lint 通过（`pnpm lint`）
* [ ] 格式检查通过（`pnpm format:check`）—— oxfmt 只检查不写盘；本地漏跑它是 CI 红得最多的一条，`pnpm fix` 一键修
* [ ] 单元测试通过（`pnpm test`）
* [ ] **类型测试通过（`pnpm test:types`）** —— `tsconfig` 的 `exclude` 不检查 `**/*.test.ts`，测试文件里的类型错误只有它能抓到
* [ ] OpenAPI 产物一致（`pnpm openapi:check`）—— 改了端点就要跑 `pnpm openapi` 重新生成并提交，&#x2A;*不要手改 `openapi.json`**
* [ ] 无循环依赖（`pnpm deps:check`）
* [ ] 构建成功（`pnpm build`）
* [ ] 改了响应类型的话，产物重新生成并提交了（`pnpm gen:types`），本地 `pnpm types:check` 是绿的 —— &#x2A;*CI 上它验不了「产物与证据一致」**（样本不进 git），但&#x2A;*验得了「barrel 与产物树一致」**，所以树被改坏时它会红；「产物与证据一致」只能在本地有样本的那台机器上验
* [ ] 已手动测试新功能
* [ ] 提交信息符合规范
* [ ] PR 描述清晰完整

<Callout type="info">
  这份清单与 CI 的质量门禁 job 是同一套检查（`.github/workflows/release.yml`）。
  本地全绿基本等于 CI 全绿 —— 唯一的例外是文档站整站构建（`pnpm build:docs`），
  它最容易被本地环境挡住。
</Callout>

## 问题反馈 [#问题反馈]

* 发现 Bug：[GitHub Issues](https://github.com/ikenxuan/amagi/issues)
* 功能建议：[GitHub Discussions](https://github.com/ikenxuan/amagi/discussions)
* 安全问题：请私信联系维护者


# 开始开发 (https://ikenxuan.github.io/amagi/docs/v7/dev)

> 环境、仓库地图、开发闭环与该跑哪几道门，以及「我要做 X 该读哪一页」



# 开始开发 [#开始开发]

本页做三件事：把环境跑起来、交代改完代码该跑什么、指路。逐子系统的机制不在这里 ——
那在[内部机制](/docs/v7/dev/internals)。

<Callout type="tip" title="建议把改动交给 Claude Code 或 Codex">
  这个仓库是**按 AI 代理能直接上手**的方式组织的：安装一次技能包
  `npx skills add ikenxuan/amagi`，Claude Code、Codex 这类工具便能了解端点声明怎么写、
  该跑哪几道门、提交信息的格式 —— 无需先补充大量上下文。
  「加一个平台接口」「补一条响应样本」「重新生成类型」这类工作尤其适合交给它们完成，
  你只需在收尾时自己跑一遍[合并前那条命令](#开发闭环)。
</Callout>

## 环境 [#环境]

| 要求      | 版本   |
| ------- | ---- |
| Node.js | ≥ 22 |
| pnpm    | ≥ 9  |

```bash
git clone https://github.com/ikenxuan/amagi.git
cd amagi
pnpm install
```

安装期间 `@ikenxuan/amagi-response-types` 会跑自己的 `prepare` 完成构建 —— core 的类型解析
指到那个包的 `dist/index.d.ts`（`packages/core/tsconfig.json` 的 `paths`），它没构建过时
core 的类型检查会报一串「模块没有导出成员」，而不是指向真正的原因。

## 仓库地图 [#仓库地图]

pnpm workspace，六个包：

<Files>
  <Folder name="amagi">
    <Folder name="packages">
      <File name="core            # @ikenxuan/amagi —— 唯一发布物（六层，见下）" />

      <File name="web             # 控制台（Vite + React + HeroUI）：录样本、生成类型的主入口" />

      <File name="typegen         # 响应类型生成器：本地样本 → 形状树 → TS 源码" />

      <File name="response-types  # 生成出来的响应类型，core 当 devDep 装、透给下游" />

      <File name="codemod         # v6 → v7 消费方改写工具（仓库内私有）" />

      <File name="docs            # 本文档站（Fumadocs + Next）" />
    </Folder>

    <File name="corpus              # 录到的响应样本：只留本地、不进 git（seeds.json 与 *.doc.json 例外）" />

    <File name="skills              # 给 AI 代理的技能包" />

    <File name=".github/workflows   # CI：质量门禁与发版（release.yml）、文档站部署（pages.yml）" />
  </Folder>
</Files>

`packages/core/src/` 按职责分六层，依赖方向单向、由 CI 的 `dpdm` 钉住 0 环：

<Mermaid
  chart="flowchart LR
  contracts[&#x22;contracts<br/>零依赖叶子层&#x22;]
  transport[&#x22;transport<br/>唯一发请求处&#x22;]
  platforms[&#x22;platforms<br/>端点声明&#x22;]
  runtime[&#x22;runtime<br/>执行管线&#x22;]
  client[&#x22;client<br/>门面&#x22;]
  server[&#x22;server<br/>HTTP&#x22;]
  server --> client --> runtime --> platforms --> transport --> contracts"
/>

<Callout type="info">
  `platforms/` 是唯一的平台目录。它底下的 `platforms/legacy/` 是 **v6 保留实现**
  （公开工具集的实现来自那里），v7 的新代码一律进 `platforms/<平台>/`。
  详见[端点注册表](/docs/v7/dev/internals/registry)。
</Callout>

## 开发闭环 [#开发闭环]

日常就是一个循环：**改一处 → 跑对应的门 → 提交**。门禁不止 `tsc` 一条 —— 这个仓库偏爱
「编译绿但产物是空壳」，每道门各自接住别的门碰不到的一类。

| 你改了什么                          | 至少跑                                                        | 为什么                                                                 |
| ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| `packages/core/src/` 任意源码      | `pnpm typecheck` `pnpm lint` `pnpm test` `pnpm deps:check` | 依赖方向由 dpdm 钉死（必须 0 环），调用行为由 vitest 钉死                               |
| 端点声明（新增 / 改 `route` / 改 `doc`） | 上一行 + `pnpm openapi` 并提交产物                                 | `openapi.json` 是四个注册表的派生物，CI 与它逐字节比对                                |
| 录了新响应样本                        | `pnpm gen:types` → &#x2A;*重建 `response-types`** → 提交生成树    | core 的类型解析指到那个包的 `dist/`，不重建就还在读旧类型                                 |
| 测试或类型测试（`*.test-d.ts`）         | `pnpm test` / `pnpm test:types`                            | `tsconfig` 的 `exclude` 不检查 `*.test.ts`，测试文件里的类型错只有 `test:types` 抓得到 |
| 文档站（`packages/docs/`）          | `pnpm --filter=docs run typecheck`                         | 它串了 `<include>` 区段与侧边栏两道静态门，都在整站构建之前                                |
| 控制台（`packages/web/`）           | `pnpm --filter @ikenxuan/amagi-web run build`              | 体积预算按产物量，三条线都写在 CI 那一步里                                             |

提交前全跑一遍 —— 与 CI 的质量门禁是同一套：

```bash
pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm test:types \
  && pnpm openapi:check && pnpm deps:check && pnpm types:check
```

**`format:check` 是最常漏的一条**：它是 oxfmt，不是 oxlint，长期没有门禁、2026-09 才补上；
漏跑的表现是本地全绿而 CI 单独一步红。三条命令的分工是：`lint` 查、`format:check` 只检查、
`fix` 才改文件。

### 几条「红了，但不是你改坏了」 [#几条红了但不是你改坏了]

| 现象                             | 真相                                                                          |
| ------------------------------ | --------------------------------------------------------------------------- |
| `deps:check` 报十几条 dpdm warning | 恒定的第三方入口解析告警；**只有循环依赖才置非零**，目标 0 环                                          |
| `types:check` 在 CI 上「跳过比对」     | 样本不进 git，CI 上只验得了「barrel 与产物树一致」；「产物与证据一致」只有本地有 `corpus/` 时验得了，脚本明说跳过、不假装通过 |
| `test` 偶发两条 `bad port`         | 内核给测试服务分到了一个 fetch 封禁端口，隔离重跑即绿，与改动无关                                        |

## 控制台：日常改接口的地方 [#控制台日常改接口的地方]

`packages/web` 不只是录样本的工具 —— 想知道一个接口真实返回什么、有哪些变体，它是最快的路。

```bash
pnpm console     # 一条命令起 Node 侧 + 浏览器侧；任一侧退出会把另一侧一起收掉
```

左栏搜端点 → 填参（表单由端点声明的 zod schema 派生）→ 发送 → **三栏并排**看请求 / 响应 / 类型
→ 「留下 / 丢掉」→ 生成类型。cookie 在右上角抽屉里配，保存后写进仓库根的 `.env` 并立刻生效；
页面上一个字都不回显。`--host` / `--port` / `--token` 由 `pnpm console` 原样透传给 server 侧。

需要分两个终端时用 `pnpm console:server`（Node 侧）与 `pnpm console:web`（浏览器侧，Vite 把
`/api/*` 代理过去）—— **少起 Node 侧时每个请求都会失败，而且失败的样子会骗人**，见
[贡献指南的「corpus 工作流」](/docs/v7/dev/contributing#corpus-工作流)。

## 常用命令 [#常用命令]

从仓库根跑：

| 命令                                             | 做什么                                                                                    |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `pnpm console`                                 | 控制台开发模式（上一节），日常改接口从这里开始                                                                |
| `pnpm dev`                                     | 核心包开发模式（`tsx watch`，`LOG_LEVEL=debug`）                                                 |
| `pnpm docs:dev`                                | 文档站开发模式：先建 core、再生成端点页，然后 `next dev`，访问 [http://localhost:3000](http://localhost:3000) |
| `pnpm build`                                   | 构建所有包 —— **含文档站整站构建**，本机不一定跑得动（见下）                                                     |
| `pnpm typecheck`                               | 六个包的类型检查（docs 那份还串了三道静态门）                                                              |
| `pnpm lint` / `pnpm fix` / `pnpm format:check` | oxlint 检查 / oxfmt 自动修复 / 格式只检查不写盘                                                      |
| `pnpm test` / `pnpm test:types`                | vitest 运行时用例 / 类型用例（`*.test-d.ts`）                                                     |
| `pnpm openapi` / `pnpm openapi:check`          | 重新生成 / 校验 `openapi.json`                                                               |
| `pnpm gen:types` / `pnpm types:check`          | 从本地 `corpus/` 生成响应类型 / 校验那棵生成树                                                         |
| `pnpm types:diff <生成产物> <手写类型>`                | 手工工具：按**路径**比两棵树，不是门禁                                                                  |
| `pnpm deps:check`                              | dpdm 循环依赖检查，必须 0 环                                                                     |
| `pnpm build:docs`                              | 文档站整站构建（含死链检查）                                                                         |

`build:docs` 是整站构建，CI 那台 4 vCPU / 16 GiB 的 runner 上跑（`next.config.mjs` 把 `cpus` 压到 2）。
**本机跑不动就交给 CI** —— 上面表里那条 `pnpm --filter=docs run typecheck` 已经把最常坏的
`<include>` 区段被改名挡在前面了，它只要有 TypeScript 就能跑，不需要 Next 的 bundler。

## 我要做 X，该读哪一页 [#我要做-x该读哪一页]

| 你要做的事                   | 去哪                                                            |
| ----------------------- | ------------------------------------------------------------- |
| 给某个平台加一个数据接口            | [新增接口](/docs/v7/dev/add-api)                                  |
| 先理解整体分层与依赖方向            | [项目架构](/docs/v7/dev/architecture)                             |
| 写 / 改测试，或看不懂某条快照        | 仓库内 `packages/core/test/README.md`（布局、快照纪律、`KNOWN-DEFECT` 约定） |
| 改执行管线、重试、错误归因           | [请求生命周期](/docs/v7/dev/internals/lifecycle)                    |
| 改签名、header、cookie、重试策略  | [传输与签名](/docs/v7/dev/internals/transport)                     |
| 加事件、查「为什么收不到事件」         | [事件与可观测性](/docs/v7/dev/internals/events)                      |
| 改翻页或扫码登录                | [翻页与会话](/docs/v7/dev/internals/session)                       |
| 改对外导出、`/compat`、HTTP 服务 | [公开 API 表面](/docs/v7/dev/internals/surface)                   |
| 改类型、信封、错误码              | [契约与信封](/docs/v7/dev/internals/contracts)                     |
| 验一份签名实现到底对不对            | [签名验证](/docs/v7/dev/sign-verify)                              |
| 提 PR、写提交信息              | [贡献指南](/docs/v7/dev/contributing)                             |

## 本节内容 [#本节内容]

<DocsCategory />

<Callout type="info">
  「内部机制」那一组是**写给 AI 代理和深度贡献者**的：逐子系统讲清特点与机制，比这几页详细得多。
  直接让 AI 代理读[内部机制](/docs/v7/dev/internals)比让它猜源码结构快得多 ——
  三条取用通路见 [AI 代理](/docs/v7/ai)。
</Callout>


# 契约与信封 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/contracts)

> contracts 是全仓的词汇表 —— AmagiResult、AmagiError、EndpointDef 的确切形状与三条硬约束



# 契约与信封 [#契约与信封]

`packages/core/src/contracts/` 是**零依赖叶子层**：谁都可以依赖它，它不依赖仓库内任何其他模块（外部只有 zod 与 axios 的类型导入）。九个文件、约 1300 行，是全仓的词汇表。

读这一层的收益最高 —— 上层几乎所有行为都由这里的形状决定。

## 九个文件 [#九个文件]

| 文件            | 内容                                                                                                                                                                |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result.ts`   | `AmagiResult<T>` / `AmagiSuccess<T>` / `AmagiFailure` / `isSuccess` / `isFailure` / `unwrap` / `AmagiThrownError`                                                 |
| `error.ts`    | `AmagiError` / `ErrorKind`（12 个大类）/ `AmagiErrorCode` / `Judge`                                                                                                    |
| `meta.ts`     | `AmagiMeta` / `RequestTrace` / `TraceReason` / `STATIC_CLIENT_ID`                                                                                                 |
| `endpoint.ts` | `EndpointDef` / `defineEndpoint` / `SignDecl<TSign>` / `type<T>()` / `PaginateDef` / `PaginatedValue` / `AggregatedValue` / `PageOf` / `EndpointCtx` / `Registry` |
| `request.ts`  | `RequestSpec` / `RawResponse` / `RequestConfig` / `AmagiHeaders`                                                                                                  |
| `cookie.ts`   | cookie 解析与序列化 —— **全仓唯一实现**                                                                                                                                       |
| `platform.ts` | `PLATFORMS` 常量与 `Platform` 联合类型                                                                                                                                   |
| `session.ts`  | 会话契约：`LoginState` / `LoginSession` / `QrcodeLoginStrategy`                                                                                                        |
| `ua.ts`       | 浏览器指纹基线（UA / Sec-Ch-Ua），四个平台的版本号集中一处                                                                                                                              |

## 信封 [#信封]

所有对外 API 返回同一个 `AmagiResult<T>`：

<TypeTable
  id="type-table-result.ts-AmagiSuccess"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiSuccess&#x22;,
  &#x22;name&#x22;: &#x22;AmagiSuccess&#x22;,
  &#x22;description&#x22;: &#x22;成功信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;true&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;true&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;端点声明的返回类型&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;T&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;T&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n成功信封**运行时没有这个键**，所以类型只能是 `undefined`。存在的唯一理由是\n让未收窄的 AmagiResult 上 `r.error` 可读（类型 `AmagiError | undefined`），\n而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的简短说明，成功时固定为 SUCCESS_MESSAGE。\n\n注意 **`success: true` 不等于「取满了目标条数」**：声明式翻页在\n`hasMore` 为假、本页为空、或某一页被平台拒绝时都会提前收尾，返回已取到的部分。\n需要精确判断的调用方拿 `data` 里的条目数与目标比对，别靠信封。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

<TypeTable
  id="type-table-result.ts-AmagiFailure"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiFailure&#x22;,
  &#x22;name&#x22;: &#x22;AmagiFailure&#x22;,
  &#x22;description&#x22;: &#x22;失败信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;false&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;false&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;唯一的错误载体，永不为 `undefined`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiError&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n失败信封**运行时没有这个键**，所以类型只能是 `undefined`。有了它，未收窄的\n`r.data` 是 `T | undefined`，而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;等价于 `error.message`，为兼容 v6 的 `result.message` 读法保留&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### 三条硬约束 [#三条硬约束]

1. **顶层没有 `code`。** v6 用同一个 `code` 混装 HTTP 状态码、平台业务码与内部码，读的人无法判断拿到的是哪一种。v7 各归各位 —— HTTP 状态在 `error.http.status`，平台业务码在 `error.platform.code`，amagi 自己的错误码在 `error.code`。
2. **成功分支运行时没有 `error` 键，失败分支没有 `data` 键。** 类型上各留一个 `?: undefined` 占位以便未收窄时也能读，但**运行时对象里那个键不存在**。v6 是 `undefined as never` 声明占位、键却留在对象里。
3. **`success` 是唯一判别键。** `if (r.success)` 之后 `data` 可用，`else` 之后 `error` 可用。

### 永不 reject [#永不-reject]

参数校验失败、平台业务错误、网络错误、内部异常**全部**映射为 `success: false`。这条由 `runtime/execute.ts` 的单一 catch 实现，并被源码级测试钉住（断言 `catch` 子句恰好一处）。

<Callout type="warn">
  这是相对 v6 的行为变化：v6 里参数校验失败会 `throw`。依赖 `try/catch` 的 v6 代码在 v7 下会
  静默走进 `else` 分支。需要恢复抛出语义用 [`/compat`](/docs/v7/dev/internals/surface)。
</Callout>

### 四种读法 [#四种读法]

```ts twoslash
import amagi, { isSuccess, unwrap } from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
const r = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

// ① 收窄
if (r.success) {
  r.data
} else {
  r.error.kind
}

// ② 类型守卫（适合 filter）
const many = [r].filter(isSuccess).map((x) => x.data)

// ③ unwrap：失败时抛 AmagiThrownError
const data = unwrap(r)

// ④ 不收窄直接读（类型是 T | undefined）
const maybe = r.data
```

`AmagiThrownError` 把 `AmagiError` 的全字段平铺成 `readonly` 实例属性，并把原对象挂在 `.error` 上（引用相等）。它只在 `error` 自带 `cause` 时才传 `Error` 的 `cause` —— 不凭空造键。

## 错误 [#错误]

<TypeTable
  id="type-table-error.ts-AmagiError"
  type="{
  &#x22;id&#x22;: &#x22;error.ts-AmagiError&#x22;,
  &#x22;name&#x22;: &#x22;AmagiError&#x22;,
  &#x22;description&#x22;: &#x22;失败信封里唯一的错误载体，永不为 `undefined`&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;kind&#x22;,
      &#x22;description&#x22;: &#x22;判别键，跨平台统一的错误大类&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;code&#x22;,
      &#x22;description&#x22;: &#x22;稳定的字符串错误码，可用于 switch 与埋点&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的说明，取平台原文优先&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;retryable&#x22;,
      &#x22;description&#x22;: &#x22;是否值得重试。调用方据此决定退避还是放弃&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台原始错误码与文案，一个字都不丢&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ code: string | number; message?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;http&#x22;,
      &#x22;description&#x22;: &#x22;真实发生的 HTTP 状态（有请求才有）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ status: number; statusText?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;issues&#x22;,
      &#x22;description&#x22;: &#x22;`kind === 'validation'` 时的字段级错误&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ValidationIssue[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;raw&#x22;,
      &#x22;description&#x22;: &#x22;原始响应体。默认**连键都没有**，`createClient({ debug: true })` 且这次\n确实**拿到了响应**时才填（网络中断 / 超时那类失败没有响应体可放）。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;challenge&#x22;,
      &#x22;description&#x22;: &#x22;风控挑战（验证页地址 + 票据）。`kind === 'risk'` 且平台认得出这份响应时才有。\n\n**不受 `debug` 开关影响** —— 它是「怎么过去」这条必要信息，见\nRiskChallenge。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RiskChallenge | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;cause&#x22;,
      &#x22;description&#x22;: &#x22;底层 Error 对象，仅用于日志&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

`ErrorKind` 12 个大类（按声明顺序）：`validation` / `auth` / `rate_limit` / `risk` / `not_found` / `forbidden` / `unavailable` / `network` / `timeout` / `parse` / `internal` / `unknown`。

`AmagiErrorCode` 23 个具体码，按类分组：参数（`PARAM_INVALID` / `PARAM_MISSING`）、身份（`COOKIE_MISSING` / `COOKIE_EXPIRED` / `LOGIN_REQUIRED`）、风控（`RATE_LIMITED` / `RISK_CONTROL` / `CAPTCHA_REQUIRED` / `SIGNATURE_REFUSED`）、可见性（`NOT_FOUND` / `DELETED` / `PRIVATE` / `GEO_RESTRICTED` / `PAID_CONTENT`）、网络（`PLATFORM_ERROR` / `PLATFORM_UNAVAILABLE` / `NETWORK_ERROR` / `TIMEOUT`）、解析（`EMPTY_RESPONSE` / `DECODE_FAILED` / `ANTIBOT_PAGE`）、兜底（`INTERNAL_ERROR` / `UNKNOWN_ERROR`）。

刻意&#x2A;*不用 `enum`** —— 用 `as const` 数组 + 联合类型，理由写在源码注释里（v6 的两处 enum 缺陷）。

### 哪些字段什么时候有 [#哪些字段什么时候有]

| 字段                                        | 何时填                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| `kind` / `code` / `message` / `retryable` | 恒有                                                                                      |
| `platform`                                | 平台给了业务码时。**由 runtime 统一从原始响应提取**（依次试 `code` / `status_code` / `statusCode`），不是 judge 填的 |
| `http`                                    | 有请求才有                                                                                   |
| `issues`                                  | 仅 `kind === 'validation'`                                                               |
| `raw`                                     | **仅 `debug: true` 且这次确实拿到了响应。默认连键都没有**                                                  |
| `cause`                                   | 底层 Error，仅用于日志                                                                          |

`retryable` 默认按 `kind` 推（`rate_limit` / `risk` / `unavailable` / `network` / `timeout` 为真，其余 7 类为假），端点的 judge 可以覆盖。

### Judge：全仓唯一判定成败的地方 [#judge全仓唯一判定成败的地方]

```ts
type Judge = (raw: unknown, http: { status: number; headers?: JudgeHeaders }) => JudgeVerdict
```

每平台一份纯函数。v6 里四个平台各自为政的判定逻辑在 v7 只剩这一个判定点。端点声明的 `judge` 优先于平台默认；两者都没有时走 `execute` 的兜底「HTTP 2xx 即成功」。

`http.headers` 是本次响应的头（`JudgeHeaders` 只要求一个大小写不敏感的 `get`，`AmagiHeaders` 满足它）。`execute` 总会传；手写调用 judge 时可以省略，省略就等于「没有任何头」。
它存在的理由是抖音：验证中心弹滑块 / 文字验证时 **HTTP 是 200**，验证指令只在
`bdturing-verify` / `x-vc-bdturing-parameters` 头上，body 可能是空串也可能看着完全正常 ——
只看 `raw` 与 `status` 的 judge 必然漏判。所以抖音的 judge 把「2xx + 验证头」排在所有 body 判据之前，
判成 `risk` / `CAPTCHA_REQUIRED`（`subtype` 为 `nocaptcha_collect` 的无感采集除外）。

## 请求与响应描述 [#请求与响应描述]

`RequestSpec` 是端点 `build` 的产物：`method` / `url`（完整含 query）必填，其余 `headers` / `body` / `responseType` / `signPath` / `tag` / `extra` 可选。

`RawResponse` 是 transport 的产物：`status` / `headers` / `body` / `durationMs` / `url` 必填，`statusText` / `setCookie` 可选。

<Callout type="info">
  `setCookie` 单独保留**原始数组**，因为 `headers` 里的 `set-cookie` 是用 `'; '` join 成一条的字符串，
  join 之后无法还原 —— 而游客 cookie 换身份与 B站会话登录都要逐条处理。
</Callout>

`AmagiHeaders` 是一个大小写不敏感的 header 容器：内部一个 Map，key 是小写化的名字，value 保留最后一次写入的原始大小写与值。

| 成员                              | 行为                                                            |
| ------------------------------- | ------------------------------------------------------------- |
| `get` / `has` / `delete`        | 大小写不敏感                                                        |
| `set(name, value)`              | `undefined` / `null` 视为「不写这个 header」；否则**值与显示大小写一起被最后一次写入覆盖** |
| `merge(input)`                  | 逐条 `set`，后来者覆盖                                                |
| `keys` / `toEntries` / `toJSON` | 保留最后一次写入的大小写                                                  |
| `clone()`                       | `new AmagiHeaders(this)`，防下游改写上游                              |

所以不可能出现两条同名 header。

## 端点契约 [#端点契约]

`EndpointDef` 的字段清单与派生关系见[端点注册表](/docs/v7/dev/internals/registry)，这里只补两个类型层的坑：

**`type<T>()` 是幻影令牌。** 它的唯一字段是 `readonly __type?: T`，运行时返回空对象，零开销。`TData` 就从它推。

**只有 `compute` 参与 `TData` 推导、可能覆盖 `response`。** `compute` 端点常只写 `compute` 不写 `response`，类型从返回值推出就够；与 `response` 并存时要显式标注返回类型，否则 `data&#x60; 退化成宽松推导。**`normalize` / `aggregate` / `paginate.merge` 的返回都包 `NoInfer<TData>`：只被检查、不参与推导** —— 所以 `TData` 恒由 `response` 令牌定，钩子返回错形状直接编译报错而不是静默变宽。

**三个整形钩子二选一，`aggregate` 与 `normalize` 类型层互斥。** 收尾三选一：`normalize`（通用兜底）/ `aggregate`（同构分段并发）/ `paginate.merge`（翻页），一个端点最多用一个。同时写 `aggregate` 与 `normalize` 会被 `defineXxxEndpoint` 入参上的 `ExclusiveShaping`（类型是 `{ aggregate?: undefined } | { normalize?: undefined }`）**编译报错** —— 因为 execute 只认 `aggregate`、`normalize` 会被静默忽略，所以在声明处就用类型挡住；`test/contracts/endpoint-paginate.test.ts` 另有一道同名门给中文提示兜底（能用类型表达的用类型、不能的用测试钉住，这里两者都用）。

`AnyEndpointDef` 用的是 `any` 而不是 `unknown`，这是必须的 —— `TParams`（`build` 等的形参）与 `TPage` / `TItem`（`paginate.items` 的形参）都在逆变位置，`unknown` 会让具体端点不可赋值；`ParsedOf` / `DataOf` 等 helper 的 `extends` 模式、以及 `execute` 的 `def` 形参同理，在这些位都填 `any`。

三个类型提取器：`ParsedOf`（校验后的形状）、`ParamsSchemaOf`、`DataOf`。SDK fetcher 的参数签名使用 `ParsedOf`，避免 `zod.coerce` 的 input 类型 `unknown` 把数字参数放宽；HTTP 入口仍接收未校验的输入并经 schema coerce，数字字符串仍可转换。

## 响应类型的来源（2026-09-11 换过一次） [#响应类型的来源2026-09-11-换过一次]

端点的 `response&#x60; 现在引用 **`@ikenxuan/amagi-response-types` 的生成类型**（`BilibiliCommentsResponse` /
`DouyinVideoWorkResponse` 这一族），由 `packages/typegen` 从**录到的真实响应**派生，名字带完整平台名前缀。

80 个端点里 66 个有生成类型（含 B站 AV↔BV 两条 `compute` 的本地声明）；&#x2A;*14 个没有录制样本，
一律 `any`**（在 `response-mapping.test-d.ts` 里逐条 `toBeAny()` 断言登记，补样本 + `pnpm gen:types`
后 `test/contracts/response-source.test.ts` 会红着提醒换掉）。&#x2A;*类型只有两个来源：生成树，或者
`any`** —— 手写协议类型不在这条链上。唯一例外是 `xiaohongshu/userProfile`：生成树里那份描述的
是已弃用的 HTML 形状，端点保持 `any`，等重录样本后由生成树接替。

v6 的实测快照树 `src/types/ReturnDataType/`（168 文件）**仍在导出、仍是 v6 兼容面**，但**不再是端点声明的来源**。

关键机制：**每个响应类型的顶层都带索引签名**（`[property: string]: any`），嵌套层也带 —— 生成树与 v6 快照树**两边都是**。所以读平台新增的未声明字段不会产生编译错误，「平台加字段」不算 breaking change。这条承诺由类型测试逐平台钉住。

<Callout type="warn">
  索引签名的类型是 `any`，不是 `unknown` —— 类型测试里直接断言了 `toBeAny()`。
  所以读未声明字段不会有任何类型保护，写的时候自己当心。
</Callout>

### 文件名里的 `_V<n>` 不是 API 版本号 [#文件名里的-_vn-不是-api-版本号]

目录约定是 `<Endpoint>/<Endpoint>_V0.ts` 加一个 `index.ts` barrel（barrel 里
`export type KsOneWork = KsOneWork_V0`，所以对外名字不带 `_V0`）。这个后缀长期没有
任何注释解释，而它看起来的含义和它实际的含义**不一样**：

* 它**不是**平台 API 的版本，也不是 amagi 的版本。
* 它的语义是「**同一判别式取值下仍然存在无法合并的形状差异**」时的形状序号。

**现状里一个 `_V1` 都没有了。** 曾经有两个（转发动态的 `DYNAMIC_TYPE_AV` 与
`DYNAMIC_TYPE_DRAW`），但逐字段比对确认它们**不是真变体，是抓包漂移** ——
同一个接口两次抓包赶上的数据不一样（一份有 `editable`，另一份有 `decoration_card`，
`topic` 一份是对象一份是 `null`），被当成了两个类型。
2026-09-04 把它们各自合成了一个带可选字段的类型，手写树少了约 990 行。
`packages/typegen` 的第一个测试用例就是把这两份反推成样本喂进合并器，验证它塌成一个。

所以看到 `_V1` 时先怀疑它是不是该被合并掉，而不是照着再加一个 `_V2`。
两个合并后的文件头里各有一张差异表，说明「为什么这些字段是可选的」——
那是给下一个人看的：不写清，他会以为平台契约本来就这么松。

<Callout type="warn">
  新增响应类型时**不要**用 `_V<n>` 表达「接口改版了」。接口真的改了就直接改 `_V0`
  的内容 —— 那正是「实测快照」该有的行为，旧形状留在 git 历史里。
</Callout>

放宽响应类型的三条逃生舱（索引签名 / 显式泛型 / 类型断言）见[响应类型](/docs/v7/usage/guide/type-mode)那一页，那里有可编译的示例。

## validation/ 是并存的第二套 schema，不在请求路径上 [#validation-是并存的第二套-schema不在请求路径上]

`src/validation/` 有 7 个文件、约 1000 行 zod schema，键是 v6 的 `methodType` 而**不是**端点短名。它与端点声明的 `params` 是**两套不通的 schema**。

* 请求路径用的是&#x2A;*端点声明自己的 `params`**（`execute` 的 `validate` 阶段）。`validation/` 里那套在整条请求路径上是**死路** —— `src/` 里没有任何调用点。
* 但它的 8 个函数（4 个 `validateXxxParams` + 4 个 `assertValidXxxParams`）仍在**公开导出面**上，前者返回 `{ ok, value } | { ok, issues }`，后者保留 v6 的抛出行为。
* 新增端点**不需要**动它。

<Callout type="info">
  两套 schema 的键集合当前恰好一一对应（douyin 19 / bilibili 27 / kuaishou 6 / xiaohongshu 7），
  但**没有任何测试断言这一点** —— 将来加端点只改一侧不会被 CI 发现。
</Callout>

## 依赖倒置的两处 [#依赖倒置的两处]

contracts 是叶子层，但有两件事必须让上层做，于是在契约里只声明形状：

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

这两处是 `dpdm` 报 0 环的关键。


# 事件与可观测性 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/events)

> 15 个事件、它们的触发点、meta 如何被补上，以及两套并存的事件系统如何区分



# 事件与可观测性 [#事件与可观测性]

v6 的事件系统有两个结构性问题：总线是**全局单例**（一个进程共用一条），事件负载里**没有任何关联 id**（多实例并发时监听器分不清事件来自谁）。v7 的对应变化就是这一页的主题。

但有个坑必须先说：**仓库里现在有两套事件系统并存**，名字相近、都在公开导出面上。

## 先分清两套总线 [#先分清两套总线]

|           | v7 实例级                                        | v6 全局单例                                                       |
| --------- | --------------------------------------------- | ------------------------------------------------------------- |
| 实现        | `runtime/events.ts` 的 `EventBus`              | `model/events.ts` 的 `TypedEventEmitter`                       |
| 拿到它       | `client.events` / `client.on` / `client.once` | `amagi.events` / `amagi.on` / `amagi.once`，或导出的 `amagiEvents` |
| 作用域       | 每个 `createClient()` 一条，实例间互不串扰                | 整个进程一条                                                        |
| 负载带关联 id？ | **带**（`meta.requestId` / `clientId`）          | **不带**（只有 `timestamp`）                                        |
| 事件名       | 15 个                                          | 12 个                                                          |
| 谁在写它      | v7 管线（execute / transport / session）          | `transport/legacy.ts`、抖音 passport、`/compat` 的迁移提示             |

<Callout type="warn">
  `amagi.events` 与 `client.events` **不是同一个对象**。`amagi.events === amagiEvents`（v6 单例），
  而 `createClient().events` 是新建的实例级总线。想收 v7 管线的事件必须用后者 ——
  监听 `amagi.on(...)` 收不到任何 v7 事件。有测试专门断言 `first.events !== second.events`。
</Callout>

v6 那套的现状被三条 KNOWN-DEFECT 用例钉住（负载无关联 id、`http:*` 声明了却从不触发、自由函数写全局单例），并进了快照。它仍是公开导出，所以不能悄悄删。

## 实例级总线怎么接起来的 [#实例级总线怎么接起来的]

`createClient` 里 `createEventBus('client')` 造一条，然后同时做三件事：

1. 作为 `client.events` 暴露，`on` / `once` 是它的绑定方法；
2. 逐平台传进 `makeClientCtx` 的 `assembly.bus` → `ctx.bus` 让 `execute` 能发 `api:*`；
3. `ctx.scope` 在每次调用时把 `createTransportEmitter(bus, meta)` 装进那一次的 `HttpClient` → `http:*` / `network:*` / `log:warn` / `log:error` 才真的发出去。

**三根线缺一根就等于没接。** 这曾经是一个真实缺陷：槽位定义在一头、装配方在另一头，中间没人对得上，于是 `client.events` 收不到任何东西。现在装配收成一个具名的 `CtxAssembly` 对象而不是继续加位置参数，就是为了让「有槽位没人装」这件事看得见。

只有 `createClient` 传 `assembly`。静态 fetcher、bound fetcher、HTTP 路由都不传 —— 那三条路径一个事件都不发。

## 15 个事件 [#15-个事件]

事件名常量分两组：12 个与 v6 逐名对齐，3 个是 v7 独占的 `session:*`。

| 事件                | 负载                                                                     | 触发点                                          |
| ----------------- | ---------------------------------------------------------------------- | -------------------------------------------- |
| `http:request`    | `meta` + `trace`                                                       | transport 登记 trace 之后立刻                      |
| `http:response`   | `meta` + `trace`                                                       | 拿到响应 / 决定重试 / 彻底失败，**三处都发**                  |
| `http:error`      | + `status`                                                             | 仅当 `status` 存在且非 2xx                         |
| `network:retry`   | + `code` / `errno?` / `status?` / `attempt` / `maxRetries` / `delayMs` | transport 决定重试时                              |
| `network:error`   | + `code` / `errno?` / `message` / `attempts`                           | transport 彻底失败时                              |
| `log:warn`        | `LogEvent`                                                             | 随 `network:retry` 顺带发一条人话                    |
| `log:error`       | `LogEvent`                                                             | 随 `network:error` 顺带                         |
| `log:mark`        | `LogEvent`                                                             | `startServer` 开始监听时（注入了自定义 `listen` 时**不发**） |
| `api:success`     | `meta` + `data`                                                        | `execute` 返回成功信封前                            |
| `api:error`       | `meta` + `error`                                                       | `execute` 返回失败信封前                            |
| `session:state`   | `SessionStateEvent`                                                    | 会话取到码、每次轮询有结果、超时那条                           |
| `session:error`   | `SessionErrorEvent`                                                    | 轮询失败 / 应答失败 / abort / 无 `onChallenge` / 终态   |
| `session:success` | `SessionSuccessEvent`                                                  | `watch` 拿到 credential                        |
| `log:info`        | `LogEvent`                                                             | **实例总线上没有 emit 点**                           |
| `log:debug`       | `LogEvent`                                                             | **实例总线上没有 emit 点**（v6 单例上还有）                 |

最后两个不是漏了写文档 —— 仓库里有一个 `UNEMITTED_BUS_EVENT_NAMES` 常量把它们列出来，并有测试钉住「这两个事件名可订阅但当前无触发点」。想加 emit 点得先改那个常量，否则测试会红。

`network:retry` 顺带发的那条 `log:warn` 文案与 v6 遗留路径的**逐字一致**：

```
网络请求失败 [<errno 或 HTTP xxx>]，<delayMs>ms 后进行第 <attempt> 次重试...
```

## meta 是在出口惰性补上的 [#meta-是在出口惰性补上的]

transport 层**不能**反向依赖 runtime（依赖方向是 `contracts ← transport ← runtime`），所以它发出的负载里没有 `meta`。补 `meta` 发生在 `createTransportEmitter` 这个出口函数里：

<Mermaid
  chart="flowchart LR
  T[&#x22;transport<br/>emit(event, { trace })&#x22;]
  E[&#x22;createTransportEmitter(bus, meta)<br/>const current = meta()&#x22;]
  B[&#x22;EventBus<br/>emit(event, { meta: current, ...payload })&#x22;]
  T --> E --> B"
/>

`meta()` 是闭包，每次调用现算 `durationMs` 与 `attempts`。所以两条 `http:request` 事件上的 `attempts` 依次是 `1`、`2` —— 有测试直接断言这个序列，它同时证明了惰性求值和「一次调用共享一个 `requestId`」。

## debug 不影响事件发射 [#debug-不影响事件发射]

这是最容易弄错的一处。`ClientOptions.debug` 只做两件事，都不涉及事件：

1. 失败信封多一个 `error.raw`（原始响应）；
2. 信封的 `meta.trace` 带每次底层请求的明细。

**trace 的计数与 `http:*` 负载里的 `trace` 与这个开关无关** —— 登记与计数始终发生，`debug` 只决定明细是否随信封带出。也没有独立的 trace 开关：`trace` 与 `error.raw` 是同一个开关，这是刻意的（此前「开 debug 才填 raw / 开 trace 才填明细」是两句空话，因为没人设过它们）。

关闭时这两个键**根本不存在**，不是 `undefined` —— 与信封「运行时形状与声明一致」是同一条纪律。

## 会话事件用的是另一套 id 空间 [#会话事件用的是另一套-id-空间]

会话引擎自己造 `session-<base36>-<rand>` 形式的 id，`clientId` 固定 `'session'`，而且 `durationMs` 与 `attempts` **恒为 0**。它与 fetcher 的 `requestId` 空间不相交，也没有 `trace`。

会话期间的底层请求**不发** `http:*` / `network:*`：会话用的 HttpClient 虽然建了 trace 收集器，但没有注入 `emit` 出口。想观测扫码登录的网络细节，目前只能靠 `session:*` 三个事件。

## 还有一条零消费者的全局总线 [#还有一条零消费者的全局总线]

`runtime/events.ts` 里另有一个 `defaultEventBus = createEventBus('global')`，源码注释自己写着「生产代码零消费者」。它既不是 v6 那个 `amagiEvents`，也没有人订阅 —— 读代码时看到它不用找它的用途。

## 实际用法 [#实际用法]

面向下游的订阅示例与完整负载类型见[事件系统](/docs/v7/usage/advanced/events)。这里只给一条本页的结论性提醒：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { bilibili: '' }, debug: true })

// 对：实例级总线，收 v7 管线的 15 个事件
client.on('api:error', ({ meta, error }) => {
  console.log(meta.requestId, meta.attempts, error.kind)
})

// 错：这是 v6 全局单例，收不到 v7 管线的事件
amagi.on('api:error', () => {})
```


# 内部机制 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals)

> 面向 AI 代理与深度贡献者的逐子系统机制说明，讲清每一层做什么、为什么这么做



# 内部机制 [#内部机制]

这一分区与前面四页**读者不同**。

「开始开发 / 项目架构 / 新增接口 / 贡献指南」是给人扫读的：结论在前，细节能省就省，目标是十分钟内能动手。这一分区反过来 —— 它假设读者是 **AI 编码代理**，或是要改动 amagi 内部结构的贡献者：每一层的机制、每个字段的作用、每条约束背后的原因，都尽量写全，宁可长也不留缺口。

如果你在人肉找一个具体做法，先看[项目架构](/docs/v7/dev/architecture)与[新增接口](/docs/v7/dev/add-api)；那两页解决不了的问题再进来。

## 给 AI 代理的取用方式 [#给-ai-代理的取用方式]

三条通路都能拿到本分区的全文，选哪条取决于用途：

| 通路         | 适合     | 怎么用                                                                                                       |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------- |
| **技能包**    | 长期、反复读 | `npx skills add ikenxuan/amagi`，装完用 `fetch_docs.mjs` 按主题取，见 [AI 代理](/docs/v7/ai)                          |
| **纯 HTTP** | 不想装东西  | 任意页面地址后加 `.mdx` 即得该页 Markdown 源文件；全站清单在 [`/llms.txt`](/llms.txt)，全文合并在 [`/llms-full.txt`](/llms-full.txt) |

## 阅读顺序 [#阅读顺序]

本分区按**依赖方向从下往上**排，与代码分层一致。第一次读建议顺着来，因为上层的行为几乎都由下层的契约决定：

<Steps>
  <Step>
    ### 契约层 [#契约层]

    [契约与信封](/docs/v7/dev/internals/contracts) —— `AmagiResult` / `AmagiError` / `EndpointDef` 的确切形状。这是全仓的词汇表，读不懂它后面每一页都会卡。
  </Step>

  <Step>
    ### 声明与派生 [#声明与派生]

    [端点注册表](/docs/v7/dev/internals/registry) —— 一份端点声明如何派生出方法、路由、类型、OpenAPI 与文档。amagi 最核心的设计就在这一页。
  </Step>

  <Step>
    ### 运行时 [#运行时]

    [请求生命周期](/docs/v7/dev/internals/lifecycle) → [传输与签名](/docs/v7/dev/internals/transport) → [事件与可观测性](/docs/v7/dev/internals/events) → [翻页与会话](/docs/v7/dev/internals/session)。一次调用从入参到信封，中间发生的每件事。
  </Step>

  <Step>
    ### 对外表面 [#对外表面]

    [公开 API 表面](/docs/v7/dev/internals/surface) —— 导出映射、门面、`/compat`、HTTP 服务。下游能碰到的全部东西。
  </Step>

  <Step>
    ### 工程面 [#工程面]

    [仓库工程](/docs/v7/dev/internals/repo) —— 构建、测试、CI 门禁、代码约定。改代码之前需要知道什么会红。
  </Step>
</Steps>

## 本分区的写法约定 [#本分区的写法约定]

三条，都是为了让这些页面不随代码漂移：

1. **类型表不手抄。** 凡是「某个类型有哪些字段」，一律用 `<auto-type-table>` 在构建期从 `packages/core` 的 TypeScript 源码现渲染 —— 注释即文案，源码一改这里跟着改。
2. **代码片段不复制。** 展示真实实现时用 `<include>` 引源文件（或其中一个区段），而不是抄一份进 MDX。区段被改名或删除时 `pnpm check:includes` 会红。
3. **其余细节给坐标。** 讲不完的地方直接写 `文件:行`，让读者（或代理）自己去读源码。行号会随提交漂移，所以正文里的坐标只精确到文件与函数名，具体行号只在需要指认某一处判断时才写。

<Callout type="warn">
  本分区描述的是 **v7** 的实现。仓库仍在收尾 v6 → v7 的迁移，`packages/core/src/` 下还残留
  v6 时期的目录（详见[项目架构](/docs/v7/dev/architecture)里那棵现扫的目录树）。看到某个目录
  在本分区里没有出现，大概率就是它属于待删清单 —— **不要在那些目录里落新代码**。
</Callout>


# 请求生命周期 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/lifecycle)

> 一次调用从入参到信封，中间的九个阶段、唯一一处 catch，以及 attempts 到底数的是什么



# 请求生命周期 [#请求生命周期]

四个入口，**一条管线**。理解了这一页，四个入口的差异就只剩「装了哪些可选能力」。

## 四个入口收敛到一处 [#四个入口收敛到一处]

| 入口                                                               | `meta.clientId` | 事件总线  | `debug` |
| ---------------------------------------------------------------- | --------------- | ----- | ------- |
| `createClient({...}).<平台>.fetcher.<方法>(options, requestConfig?)` | `client-1`      | **有** | **可开**  |
| `amagi.<平台>Fetcher.<方法>(options, cookie?, requestConfig?)`（静态）   | `static-<平台>`   | 无     | 无       |
| `createBound<平台>Fetcher(cookie, requestConfig?)`                 | `bound-<平台>`    | 无     | 无       |
| `startServer()` 挂的 `/api/<平台>/*`                                 | `routes-<平台>`   | 无     | 无       |

四者都进 `client/fetcher.ts` 的 `callEndpoint` → `runtime/execute.ts` 的 `execute`。差异全部来自 `makeClientCtx` 的第五个参数 `assembly`：只有 `createClient` 传了 `{ bus, debug }`，其余三个入口不传，于是 `ctx.bus` 是 `undefined`，整条链路一个事件都不发、失败信封没有 `error.raw`、`meta` 没有 `trace`。

<Callout type="info">
  这不是遗漏而是取舍：静态 fetcher 的签名是 v6 冻结的三参形式，没有装总线的位置。
  &#x2A;*要观测就用 client 形态。**
</Callout>

## 九个阶段 [#九个阶段]

`ExecuteStage` 共 9 个取值，它同时是异常归因的依据 —— 任何一处抛出都会被标上当时的阶段名。

<Mermaid
  chart="flowchart TD
  A[&#x22;callEndpoint<br/>解析 cookie / UA / requestId&#x22;]
  V[&#x22;① validate<br/>def.params.safeParse&#x22;]
  C{&#x22;声明了 compute？&#x22;}
  CP[&#x22;compute<br/>纯本地计算，不发请求&#x22;]
  P[&#x22;② prepare（可选）<br/>换 guest cookie / 取 wbi key&#x22;]
  PG{&#x22;声明了 paginate？&#x22;}
  B[&#x22;③ build<br/>构造 RequestSpec&#x22;]
  S[&#x22;④ sign<br/>a_bogus / wbi / x-s&#x22;]
  SD[&#x22;⑤ send<br/>attachCookie → transport&#x22;]
  DC[&#x22;⑥ decode<br/>缺省按 JSON&#x22;]
  JG[&#x22;⑦ judge<br/>成功 / ErrorKind&#x22;]
  RT{&#x22;命中 retryOn？&#x22;}
  NM[&#x22;⑧ normalize / paginate.merge（可选）&#x22;]
  OK[&#x22;succeed → api:success&#x22;]
  ER[&#x22;failWith → api:error&#x22;]
  A --> V
  V -->|失败，attempts 恒为 0| ER
  V --> C
  C -->|是| CP --> OK
  C -->|否| P --> PG
  PG -->|是| B
  PG -->|否| B
  B --> S --> SD --> DC --> JG
  JG -->|失败| RT
  RT -->|是，退避后重来| B
  RT -->|否| ER
  JG -->|成功| NM --> OK"
/>

逐阶段的关键事实：

1. **`validate`** —— `def.params.safeParse(input)`。失败即 `kind: 'validation'` / `code: 'PARAM_INVALID'`，`message` 取第一条 issue 的文案，`issues&#x60; 全带。此时 &#x2A;*`attempts === 0`**，一个请求都没发出去。
2. **`compute` 短路** —— 声明了 `compute` 就直接返回成功信封，跳过 prepare / build / sign / send。全仓仅 B站 AV↔BV 两个端点。
3. **`prepare`** —— 返回值浅并进 ctx，因此它可以换掉 `ctx.cookie`。它内部的请求经 `ctx.send(..., 'prepare')`，在 trace 里以 `reason: 'prepare'` 出现。
4. **翻页分支排在首次 build / sign 之前** —— 顺序是刻意的：反过来会白签一次名。
5. **`build`** —— 返回数组即多请求；空数组直接抛。
6. **`sign`** —— 签名器解析在此之前完成：字符串查平台签名器表，**查不到就抛**（`未注册的签名器：'x'`，归因为 `internal`）。
7. **`send`** —— `attachCookie` 在这里把 `ctx.cookie` 写进 `Cookie` 头：cookie 非空、且 spec 尚未自带 cookie 头时才写。取的是**当刻**的值，所以 prepare 换过就发换完的。
8. **`decode`** —— `def.decode(res.body, res)`，缺省直接用 `res.body`。
9. **`judge`** —— `judge(decoded, { status })`，缺省是「HTTP 2xx 即成功」。判定失败时 `kind` / `code` 来自 judge，而 `platform.code` 与 `message` 由 runtime 统一从原始响应里提取（依次试 `code` / `status_code` / `statusCode`，`message` / `status_msg` / `msg`）。
10. **`normalize` / `paginate.merge`** —— 把响应裁剪 / 整形为声明的返回类型。非分页端点用 `normalize`（多分片时它收到的是数组）；分页端点用 `paginate.merge`，它收到收窄好的 `PaginatedValue`（`lastPage` 加跨页累积并截断的 `items`）。

## 永不 reject：唯一一处 catch [#永不-reject唯一一处-catch]

`execute` 全函数只有**一个** `catch` 子句，它把任何抛出物按当时的 `stage` 归类：

* `TransportError` → 用它自带的 `kind` / `code` / `errno`
* `stage === 'decode'` → `kind: 'parse'` / `code: 'DECODE_FAILED'`
* 其余 → `kind: 'internal'` / `code: 'INTERNAL_ERROR'`，message 带阶段名，`cause` 原样保留

于是对外承诺成立：**参数校验失败、平台业务错误、网络错误、内部异常全部映射为 `success: false`，管线永不 reject**。

这条约束是被源码级测试钉住的 —— 用例直接断言 `execute.ts` 里 `catch` 子句恰好一处、且没有 `.catch(`。想加第二处 catch 会让测试红。

<Callout type="warn">
  这是相对 v6 的**行为变化**：v6 里参数校验失败会 `throw`，v7 不再进 `catch`。
  依赖 `try/catch` 捕获校验错误的 v6 代码在 v7 下会静默走进成功分支的 `else`。
  需要恢复抛出语义时用 [`/compat`](/docs/v7/dev/internals/surface)。
</Callout>

## meta：一次调用的可观测账本 [#meta一次调用的可观测账本]

每个信封与每条事件负载都带 `meta`：

<TypeTable
  id="type-table-meta.ts-AmagiMeta"
  type="{
  &#x22;id&#x22;: &#x22;meta.ts-AmagiMeta&#x22;,
  &#x22;name&#x22;: &#x22;AmagiMeta&#x22;,
  &#x22;description&#x22;: &#x22;挂在每个信封上的元信息&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;requestId&#x22;,
      &#x22;description&#x22;: &#x22;每次逻辑调用一个 id，贯穿事件、日志、trace&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;clientId&#x22;,
      &#x22;description&#x22;: &#x22;发起调用的 client 实例 id；静态 fetcher 用 `'static'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;bilibili\&#x22; | \&#x22;douyin\&#x22; | \&#x22;kuaishou\&#x22; | \&#x22;xiaohongshu\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;endpoint&#x22;,
      &#x22;description&#x22;: &#x22;端点全名，如 `'douyin.videoWork'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;durationMs&#x22;,
      &#x22;description&#x22;: &#x22;从进入 fetcher 到返回信封的总耗时&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;attempts&#x22;,
      &#x22;description&#x22;: &#x22;实际发出的 HTTP 请求数，含重试与分页。分页 3 页 + 1 次重试 = 4&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;trace&#x22;,
      &#x22;description&#x22;: &#x22;每次底层请求的明细，按发出顺序。\n\n默认不带：`createClient({ debug: true })` 时才填（同一个开关也给失败信封\n填 `error.raw`，没有单独的 trace 开关）。不开时信封上**没有 `trace`\n这个键**，而 `attempts` 照样准确 —— 计数始终发生，只有明细受开关控制。\n\n静态 fetcher（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。\n要不受开关影响地逐条观测请求，监听 `http:request` / `http:response`\n事件：它们的负载恒带 `trace`。URL 含签名参数，别在生产里无条件打印。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestTrace[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;incomplete&#x22;,
      &#x22;description&#x22;: &#x22;结果不完整时的原因：翻页端点声明了 `partial: 'tolerate'`、中途某页失败，\n信封仍是成功、`data` 里是已取到的那几页，这里是那个失败页的错误。\n\n完整结果上**没有这个键**。只看 `success` 的调用方会拿到截断的数据 ——\n在意条数的，检查这个键。没声明 `tolerate` 的翻页端点中途失败也返回部分结果，\n但**不**挂这个键，只能拿条目数与目标比对。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ kind: ErrorKind; code: AmagiErrorCode; message: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

三个容易误解的点：

**`requestId` 一次调用只有一个。** 它在 `callEndpoint` 最开始生成，随 `metaOf` 闭包一路带到 transport 的事件出口。所以一次「翻 3 页 + 重试 1 次」的调用里，4 条 `http:request` 事件与最后那条 `api:success` &#x2A;*共享同一个 `requestId`**。

**`attempts` 数的是底层请求数，不是重试数。** 它恒等于 trace 登记的条数，而登记发生在每次 `HttpClient.send` 之前 —— 与 `debug` 无关。所以：单请求成功 = 1；翻 3 页 = 3；翻 3 页其中一页重试一次 = 4；校验失败 = 0。

**`durationMs` 与 `attempts` 是惰性算的。** `metaOf()` 每次调用都用 `now() - startedAt` 与 `tracer.attempts` 现算，所以事件负载里看到的是**那一刻**的值。有测试断言两条 `http:request` 事件上的 `attempts` 依次是 `[1, 2]`，正是这个惰性的证据。

`trace` 只在 `debug: true` 时才有键（不是 `undefined`，是**键不存在**）。每条 trace 记录带 `reason`，六个取值：`initial`（首次）/ `retry` / `challenge`（解出反爬挑战后的重放）/ `page`（翻页）/ `segment`（分段并发）/ `prepare`（前置请求）。

## 两层重试是串联的 [#两层重试是串联的]

这一点直接决定最坏情况的请求数，容易低估：

| 层                 | 触发条件                                 | 次数       | 退避                             |
| ----------------- | ------------------------------------ | -------- | ------------------------------ |
| **transport 层**   | 可恢复 errno（9 个白名单）、HTTP 429、HTTP ≥500 | 最多 3 次重试 | 1s / 2s / 4s（`base × 2^(n-1)`） |
| **端点层 `retryOn`** | judge 判定的 `error.code` 在声明的列表里       | 最多 3 次重试 | 同一套退避函数                        |

两层独立叠加，理论上一次调用最多 `4 × 4 = 16` 个底层请求。`meta.attempts` 会如实反映 —— 这正是设计意图：v6 的重试叠乘问题不可见，v7 把它变成一个能读的数字。

### `retryFresh`：重试时换一整套参数 [#retryfresh重试时换一整套参数]

端点层重试**默认是原样重放**同一个 `RequestSpec`。B站的 `-412` 只需要等一会儿再发同一个请求，重放就够了。

抖音不行：Argus 是**按单次请求的 token 组判定、不锁账号**的，同一个 `msToken` + 同一个 `a_bogus` 重发三次结果必然相同。所以 `EndpointDef` 上有 `retryFresh?: boolean` —— 打开之后重试会&#x2A;*重新 `build` + 重新 `sign`**，`msToken` 与 `a_bogus` 都由签名 step 现签（`msToken` 是 `token` phase 的一步，每签一次重抽一个）。17 个签名类抖音端点声明了 `retryOn: ['ANTIBOT_PAGE'] + retryFresh: true`。

按**原来的分片下标**取重建后的那一条，所以多请求聚合 / 分段并发的端点也能用：失败的那一段单独换参重来，不影响其他段。

<Callout type="warn">
  **`retryFresh` 刻意是 opt-in 而不是默认。** 快手那类带可变状态的签名器会因为多签一次
  被推进一格 —— 同一条理由让翻页分支必须把 build 排在首次签名之前。
</Callout>

## `observe`：从响应头回收平台状态 [#observe从响应头回收平台状态]

`send` 拿到响应之后、`decode` 之前，管线会调一次平台级的 `observe(res, ctx)`。它**只读、不影响判定**，与 `challenge` 一样挂在 `PLATFORM_RUNTIME` 上，三个入口（client fetcher / 静态 fetcher / HTTP 路由）都有。

目前只有抖音装了它，用来回收 `webid`：那个值是服务端按 `ttwid` 算好、通过每个响应的 `cookie_ttwidinfo_webid` 头下发的，**客户端算不出来**。抖音会拿 query 里的 `webid` 与 cookie 会话交叉校验，对不上就静默回 HTTP 200 + 0 字节（不给 403、不给业务码）—— 所以缓存按 `ttwid` 分键，冷启动第一次不带（不带是安全的，传错才致命）。注入发生在签名管线的第一步：`webid → a_bogus / x_bogus → secsdk`。

<Callout type="warn">
  `observe` 的实现方必须**自己吞异常**。它抛出来会被管线唯一那处 catch 归因成
  `kind: 'internal'`，把一个本来成功的调用变成失败 —— 旁观者不该有这个权力。
</Callout>

<Callout type="info">
  客户端侧**没有**令牌桶、并发闸或 QPS 限制。限频只表现为「429 进退避重试并发出
  `network:retry` 事件（`code: 'RATE_LIMITED'`）」。多请求聚合（快手用户主页 12 并发、
  抖音弹幕按 32 秒切段）是无节流的 `Promise.all` / `allSettled`。
</Callout>

## 多请求与部分失败 [#多请求与部分失败]

`build` 返回数组时，`signed.length > 1` 即进入多分片模式，trace 上的 `reason` 变成 `segment`：

* **`partial: 'tolerate'`** —— 用 `Promise.allSettled`，个别分片失败时缺失部分留空。注意**全部分片失败仍然返回失败信封**。选 `allSettled` 而不是 try/catch 是为了不引入第二处 catch。
* **缺省 `'fail'`** —— 用 `Promise.all`，任一分片失败即整体失败。

翻页分支里 `partial: 'tolerate'` 的含义不同：第 2 页起某页失败时停下、带着已取数据返回成功，这一条**所有**翻页端点都生效（首页失败仍整体失败）；`tolerate` 额外把失败原因落到 `meta.incomplete`。详见[翻页与会话](/docs/v7/dev/internals/session)。

## 阶段与异常的对应关系有测试逐个覆盖 [#阶段与异常的对应关系有测试逐个覆盖]

`test/runtime/execute.test.ts` 在每个环节各抛一次，验证「永不 reject」；另有专项用例验证 `TransportError` 归 `network` 而非 `internal`、未注册的签名器名归 `internal`。改动管线时这些用例是第一道防线。

## 下一步 [#下一步]

* 请求真正发出去之后的事：[传输与签名](/docs/v7/dev/internals/transport)
* 这一路发了哪些事件：[事件与可观测性](/docs/v7/dev/internals/events)
* 翻页那条虚线的细节：[翻页与会话](/docs/v7/dev/internals/session)


# 端点注册表 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/registry)

> 一份端点声明如何派生出方法、路由、类型、OpenAPI 与文档 —— amagi v7 最核心的设计



# 端点注册表 [#端点注册表]

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

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

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

## 声明本体 [#声明本体]

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

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

```ts title="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
})

```

| 字段            | 类型                                              | 它导致什么                                                                                                                           |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `` `${Platform}.${string}` ``                   | `meta.endpoint`；OpenAPI 的 `operationId`（`平台_短名`）与 `tags`（取平台段）。**声明里没有 `tags` 字段** —— 平台就是 tag                                  |
| `route`       | `string`                                        | HTTP 路径，**同平台内必须唯一**（注册期同步校验，重复直接抛）                                                                                             |
| `params`      | zod schema                                      | 参数 TS 类型（`ParsedOf`）、运行时校验、OpenAPI 的 query parameters、文档参数表 —— 四样东西的**唯一出处**                                                    |
| `doc.summary` | `string`                                        | OpenAPI `summary`、SDK 方法页的首句。类型可选，测试强制（见下）                                                                                      |
| `build`       | `(params, ctx) => RequestSpec \| RequestSpec[]` | 构造请求描述。返回数组即多请求聚合 / 分段并发                                                                                                        |
| `sign`        | `TSign \| false \| SignFn`                      | 字符串查平台签名器表（`TSign` 默认宽 `string`，平台的 `defineXxxEndpoint` 把它收窄到签名器名联合、写错编译期即报错）；`false` 显式不签；函数即一次性签名器                            |
| `response`    | `type<T>()`                                     | `TData` 的**唯一**来源。`normalize` / `paginate.merge` 的返回包 `NoInfer<TData>`、只被检查不参与推导；只有 `compute` 参与推导（可只写 `compute` 不写 `response`） |

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

<TypeTable
  id="type-table-endpoint.ts-PaginateDef"
  type="{
  &#x22;id&#x22;: &#x22;endpoint.ts-PaginateDef&#x22;,
  &#x22;name&#x22;: &#x22;PaginateDef&#x22;,
  &#x22;description&#x22;: &#x22;声明式翻页：一页页往后翻，每页都走 ③build→④sign→⑤send→⑥decode→⑦judge，最后 `merge` 收尾。\n页类型 `TPage` 缺省取 `PageOf<TData>`（一页与返回同形），所以 `items` / `hasMore` / `nextParams`\n自动拿到 `response` 的形状、不必断言。详细机制见开发文档「翻页与会话」。&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;maxPageSize&#x22;,
      &#x22;description&#x22;: &#x22;单页最多取多少条，用来把目标条数切成几次请求&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;limitParam&#x22;,
      &#x22;description&#x22;: &#x22;目标条数取自哪个参数，默认 `'number'`；该参数为 0 时一个请求都不发&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;(keyof TParams & string) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string & keyof TParams&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;countParam&#x22;,
      &#x22;description&#x22;: &#x22;每页条数写回哪个参数，默认与 `limitParam` 相同&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;(keyof TParams & string) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string & keyof TParams&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;page&#x22;,
      &#x22;description&#x22;: &#x22;页形状与最终返回不同形时才写（覆盖 `TPage`）；缺省取 `PageOf<TData>`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;TypeToken<TPage> | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;items&#x22;,
      &#x22;description&#x22;: &#x22;从一页里取出本页条目（`page` 已是 `TPage`）；返回空数组表示到底了&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;(page: TPage) => TItem[]&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;hasMore&#x22;,
      &#x22;description&#x22;: &#x22;还有没有下一页；返回 `false` 立刻停&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;(page: TPage) => boolean&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;nextParams&#x22;,
      &#x22;description&#x22;: &#x22;根据这一页产出下一次请求的参数（游标怎么带端点自己定）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;(params: TParams, page: TPage) => TParams&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;keepPages&#x22;,
      &#x22;description&#x22;: &#x22;把每一页的完整体也留给 `merge`（默认 `false`，只留最后一页）。\n\n代价是内存：页体通常比条目大得多，全留着在翻几十页时是实打实的峰值。\n所以它**只为「条目之外还有跨页旁路数据」的端点存在** —— 快手评论就是这样：\n子评论不在根评论里，而在与 `rootComments` 平级的 `subCommentsMap` 上按根评论\nID 分组，只拿最后一页会把前面几页的回复串整批丢掉。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;pageIntervalMs&#x22;,
      &#x22;description&#x22;: &#x22;翻页间隔（毫秒）：第 2 页起、每页发出前先等这么久。默认 0（不等）。\n\n翻页本来就是串行的，所以这不是并发问题，是礼貌 / 风控问题 —— 快手这类按 IP\n做分钟级冷却（`result=2`）的平台，连续秒级翻页很容易撞上。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;merge&#x22;,
      &#x22;description&#x22;: &#x22;把跨页累积的条目收成最终 data（可选）：`value.lastPage` 恒有值、`value.items` 是累积条目&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;((value: PaginatedValue<TPage, TItem>, params: TParams) => NoInfer<TData>) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;function&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### 可选槽位与它们的真实使用量 [#可选槽位与它们的真实使用量]

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

| 槽位            | 端点数                      | 做什么                                                                                                                                                                                                                                             |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `retryOn`     | 46（24 在 B站、20 在抖音、2 在快手） | 命中这些错误码时端点级重试。B站的 `-412` → `RISK_CONTROL`；快手弹幕约 13% 概率的 `result: 11` → `PLATFORM_UNAVAILABLE`；抖音的一般 Argus 拦截 → `ANTIBOT_PAGE`（点名签名的 `SIGNATURE_REFUSED` 不在名单 —— 重签补不出缺失的访客 id）                                                                  |
| `retryFresh`  | 20（全在抖音）                 | 重试时重新 build + 重新签名而不是原样重放。Argus 按单次请求的 token 组判定，重放同一个 `msToken` + `a_bogus` 必然同样被拦；`msToken` 由签名 step 现签，重签即换新                                                                                                                                 |
| `paginate`    | 15（抖音 7、快手 5、小红书 2、B站 1） | 声明式翻页，见[翻页与会话](/docs/v7/dev/internals/session)                                                                                                                                                                                                  |
| `prepare`     | 42（抖音 26、小红书 13、快手 3）    | 前置请求或前置注入。抖音的 26 条由 `defineDouyinEndpoint` **横切注入** Cookie 文本规范化（签名与发送用同一份凭据）；小红书 13 个端点经 `defineXiaohongshuEndpoint` **横切注入**游客会话降级（cookie 里没有 `a1` 就先换游客 cookie + SSK，将来新增端点自动覆盖，端点声明里不逐个写）；快手两条 H5 端点注入 `did`，另一条 PC 端点用 `kuaishouPcPrepare` |
| `decode`      | 2                        | 响应不是普通 JSON：protobuf（B站弹幕）、multi-JSON（抖音搜索）                                                                                                                                                                                                     |
| `judge`       | 8（抖音 2、快手 4、B站 1、小红书 1）  | 覆盖平台默认判定                                                                                                                                                                                                                                        |
| `partial`     | 18（抖音 8、快手 7、小红书 2、B站 1） | 多请求部分失败语义：`'tolerate'` / `'fail'`（缺省）                                                                                                                                                                                                           |
| `aggregate`   | 2                        | 「同构分段并发」的带类型收尾（弹幕按时间区间切段并发），取代这类端点的 `normalize`；与 `normalize` **互斥**（同时写编译报错，见[契约与信封](/docs/v7/dev/internals/contracts)）。抖音 / 快手弹幕                                                                                                              |
| `normalize`   | 1                        | 把响应整理成最终 data 的**通用兜底**（第一参 `unknown`）。分页用 `paginate.merge`、同构分段用 `aggregate`，剩下的才用它。当前仅快手 `userProfile`（异构聚合）                                                                                                                                  |
| `compute`     | 2                        | 纯本地计算，不发请求（B站 AV/BV 互转）                                                                                                                                                                                                                         |
| `sign: false` | 4                        | 显式不签名（抖音四条免鉴权端点）。签名端点改用 `SignStep` 清单，如 `[msToken(184), aBogus(), secsdk()]`，按 phase 排序执行（见 `sign/steps.ts`）                                                                                                                                    |

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

## 注册表 [#注册表]

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

```ts title="packages/core/src/platforms/douyin/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**。这个数字在多处被断言，改了端点数就得同步（见[新增接口](/docs/v7/dev/add-api)）。

<Callout type="info">
  注册表**不在包的公开导出面上**：`src/index.ts` 没有 `export * from './platforms'`，`package.json`
  的 `exports` 也没有 `./platforms` 子路径。它只以派生物的形态对外 —— 下游拿到的是 fetcher 方法、
  HTTP 路由与类型，碰不到 registry 本身。
</Callout>

## 派生出什么 [#派生出什么]

<Mermaid
  chart="flowchart LR
  D[&#x22;endpoints/*.ts<br/>80 份 defineEndpoint 声明&#x22;]
  R[&#x22;platforms/&lt;p&gt;/endpoints/index.ts<br/>4 个 registry&#x22;]
  F[&#x22;client/fetcher.ts · static.ts<br/>Proxy 派生 fetcher&#x22;]
  S[&#x22;server/routes.ts<br/>Express Router&#x22;]
  O[&#x22;server/openapi.ts<br/>buildOpenApiSpec()&#x22;]
  J[&#x22;openapi.json<br/>（提交进 git）&#x22;]
  H[&#x22;80 个 HTTP 端点页<br/>（gitignore）&#x22;]
  K[&#x22;4 个 SDK 方法页<br/>（gitignore）&#x22;]
  D --> R
  R --> F
  R --> S
  R --> O
  O --> J
  J --> H
  R --> K
  O --> K"
/>

| 派生物                 | 生成器                                             | 输入                                 | 产物进 git？                                       |
| ------------------- | ----------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
| fetcher 方法集合        | `client/fetcher.ts`、`client/static.ts`          | registry                           | 运行时 Proxy，无产物                                  |
| 参数校验                | `runtime/execute.ts` 的 `validate` 阶段            | `def.params`                       | 无                                              |
| HTTP 路由             | `server/routes.ts` 的 `createRoutes`             | registry                           | 无                                              |
| OpenAPI 规范          | `server/openapi.ts` → `scripts/gen-openapi.mts` | 四个 registry                        | **提交**（`packages/core/openapi.json`，80 条 path） |
| 自托管 `/openapi.json` | `server/auth.ts` 的 `mountOpenApiSpec`           | 同上，**现算**                          | 无                                              |
| 80 个 HTTP 端点页       | `packages/docs/scripts/generate-docs.ts`        | `openapi.json`                     | gitignore                                      |
| 4 个 SDK 方法页         | 同上                                              | registry 本体 + `buildOpenApiSpec()` | gitignore                                      |
| SDK 方法名             | **手写表** `client/method-names.ts`                | —                                  | 提交                                             |

### fetcher 是 Proxy，不是预生成对象 [#fetcher-是-proxy不是预生成对象]

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

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

### 方法名是唯一的手写映射 [#方法名是唯一的手写映射]

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

| 端点短名               | v6 方法名                       |
| ------------------ | ---------------------------- |
| `parseWork`        | `parseWork`（没有 `fetch` 前缀）   |
| `comments`         | `fetchWorkComments`          |
| `search`           | `searchContent`              |
| `avToBv`           | `convertAvToBv`              |
| `videoStream`      | `fetchVideoStreamUrl`        |
| `searchNotes`（小红书） | `searchNotes`（没有 `fetch` 前缀） |

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

<Callout type="warn">
  兜底规则的存在**不代表**新端点可以不登记。两处会红：`generate-docs.ts` 在
  `methodNamesOf(platform)[short]` 为 `undefined` 时直接抛（于是 `pnpm build:docs` 失败，
  而它是 CI 必需检查）；`method-names.test.ts` 把映射表的方法名集合与**活 fetcher 的键**
  逐条比对，多一个就失败。所以规则名也必须登记。
</Callout>

### OpenAPI 的派生规则 [#openapi-的派生规则]

`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` 也能抓到「忘了重新生成」。

### 文档站的两批生成物 [#文档站的两批生成物]

`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/` 一角 [#platforms-一层与它底下的-legacy-一角]

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

|          | `platforms/<平台>/`                                                                                                                                                | `platforms/legacy/`                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 规模       | 208 文件 / 24713 行                                                                                                                                                 | 13 文件 / 2622 行                                                                                                               |
| 是什么      | **v7 实现层**                                                                                                                                                       | **v6 保留实现**（公开面照旧，行为逐字不动）                                                                                                    |
| 内容       | `endpoints/`（80 份声明 + registry）、`api.ts`（URL 构造纯函数）、`config.ts`、`judge.ts`、`sign/`、`session/`、`decode/`、`assemble/`、`passport/`（仅 douyin）、`routes.ts`、`utils.ts` | 四个 v6 版 `API.ts`、v6 的 `wbi.ts` / `qtparam.ts` / `douyin/sign`、`kuaishou/sign`（分叉的 3 个文件）、`xiaohongshu/sign`、`searchTypes.ts` |
| 在公开导出面上？ | `routes.ts` 与 `utils.ts` 在，其余不在                                                                                                                                  | 在（签名器经 `utils.ts` 转出；`xxxApiUrls` 由 `src/index.ts` 显式点名导出）                                                                   |
| 新增端点要碰吗  | 要                                                                                                                                                                | 不要                                                                                                                           |

### `<平台>/utils.ts` 是公开面，`routes.ts` 是唯一的路由挂载路径 [#平台utilsts-是公开面routests-是唯一的路由挂载路径]

四个 `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 是两份代码，不是一份的两个入口 [#legacy-与-v7-是两份代码不是一份的两个入口]

包顶层导出的 `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 完全相等。这层对照依赖两份代码同时存在，动任何一侧前先读那些用例。

<Callout type="info">
  `platforms/` 一层共 170 个 `.ts`。从 `src/index.ts` 递归跟随 import 有 **169 个可达**；剩下的
  `platforms/douyin/sign/decode.ts` 只从 `exports/signing.ts` 进来 —— 那是 `./signing` 子入口，
  按设计不挂在主入口上。把六个包入口（`.` / `./express` / `./axios` / `./compat` / `./signing` /
  `./sign-steps`）一起算，**170 个全部可达**。

  这里曾经有 7 个不可达文件（`platforms/kuaishou/judge.ts` 与 `platforms/kuaishou/sign/` 下 6 个），
  成因是 `PLATFORM_RUNTIME` 里 `kuaishou: {}` —— 既没装签名器也没装默认 judge，写好的代码没人调用。
  两项都补上之后它们全部可达，那也正是快手请求终于带上 `__NS_hxfalcon` 的同一件事，
  见[传输与签名](/docs/v7/dev/internals/transport)。

  这个数字值得偶尔重算一遍：&#x2A;*「文件存在」不等于「被调用」**，而这个仓库已经因此踩过两次
  （judge 与 signers 各一次，都是既不报编译错误也不挂测试的静默漏项）。新加的
  `platforms/kuaishou/captcha.ts` 就是靠这次重算才发现忘了从顶层导出 —— 那会让「把滑块地址
  交给调用方」变成一句空话。重算时**别只从 `src/index.ts` 出发**：子入口独占的文件会被误判成孤儿。
</Callout>

## `doc` 字段为什么被测试而不是类型强制 [#doc-字段为什么被测试而不是类型强制]

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

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


# 仓库工程 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/repo)

> 构建、测试、CI 门禁与代码约定 —— 改代码之前需要知道什么会红



# 仓库工程 [#仓库工程]

这一页回答一个问题：&#x2A;*我改了东西，什么会红，为什么。**

## 仓库地图 [#仓库地图]

pnpm workspace，glob 只有 `packages/*`：

| 包                                | 路径                        | 可见性      | 用途                                                             |
| -------------------------------- | ------------------------- | -------- | -------------------------------------------------------------- |
| `@ikenxuan/amagi`                | `packages/core`           | **公开发布** | 唯一发布物                                                          |
| `@ikenxuan/amagi-web`            | `packages/web`            | private  | 控制台（Vite + React + HeroUI）：填参 → 发请求 → 同屏看响应体与它的类型声明 → 就地生成响应类型 |
| `@ikenxuan/amagi-typegen`        | `packages/typegen`        | private  | 响应类型生成器：本地样本 → 形状树 → TS 源码                                     |
| `@ikenxuan/amagi-response-types` | `packages/response-types` | private  | 生成出来的响应类型本体，整棵 `src/generated/` 由 typegen 派生，手改无意义             |
| `@ikenxuan/amagi-codemod`        | `packages/codemod`        | private  | v6 → v7 消费方改写工具                                                |
| `docs`                           | `packages/docs`           | private  | 本文档站                                                           |

依赖方向：`docs → core`、`web → core` + `web → typegen`（都 `workspace:*`），以及 `core → response-types` + `core → typegen`。文档站的生成脚本与 `packages/web/server/` 都**直接按相对路径 import core 的源码**（`../../core/src/...`，绕过包边界，因为它们要读端点注册表本身）。`codemod` / `typegen` / `response-types` 不依赖任何工作区包。

core 那两条挂在 &#x2A;*`devDependencies`** 上是刻意的，不是漏写：tsdown 只外部化 `dependencies` / `peerDependencies`，挂到那两处，`dist/*.d.ts` 里就会留下一个裸 `import '@ikenxuan/amagi-response-types'` —— 而这个包不发布，下游解析不到。挂 devDep 才会被内联进声明产物。

看起来像包但不在 workspace 里的顶层目录：`docs/`（v7 的设计文档与执行清单）、`skills/`（给 AI 代理的技能包）。两者都没有 `package.json`。

## 构建 [#构建]

`packages/core` 用 **tsdown**（底层 rolldown），配置在 `packages/core/tsdown.config.ts`：

* **6 个入口**：`default/index` ← `src/index.ts`，以及 glob `exports/*` ← `src/exports/*.ts`（axios / compat / express / sign-steps / signing）
* **双格式**：ESM（`.mjs`）+ CJS（`.cjs`），扩展名由 `outExtensions` 指定
* **`.d.ts` 逐入口生成，且只随 ESM 生成一份**（CJS 的 dts 关掉了）；共享类型抽成一个独立 chunk
* **`define`**：`__VERSION__` ← `package.json` 的 `version`，被 `src/index.ts` 与 `server/openapi.ts` 消费
* 无 sourcemap、无 banner、无显式 externals（走 tsdown 默认：dependencies 与 peerDependencies 不打包）

6 个入口与 `package.json` 的 6 个 `exports` 子路径一一对应。`files` 只发 4 项：`dist/*`、LICENSE、`package.json&#x60;、README —— **`openapi.json` 不进 npm 包**，它只服务生成器与文档站。

## 命令 [#命令]

<Callout type="warn">
  **文档站这一侧的检查都编译真实的 `dist/*.d.ts`，不是 core 的源码。** `examples/**/*.ts`
  按包名 `@ikenxuan/amagi` import，包名经 `exports.types` 解析到 `dist`。
  所以 docs 的 `typecheck` / `build` / `dev` 都自带 `build:core` 前置 —— 少了它本地看不出来
  （开发机上 `dist` 早就在那儿），只有 fresh clone 的 CI 会红，报 `TS2307`。
</Callout>

从仓库根：

| 命令                                | 展开                                                                                                                        | 需要先 build:core |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `pnpm build`                      | 递归各包 build（docs 那条自含 build:core）                                                                                          | 自含             |
| `pnpm build:core`                 | core 的 `tsdown`                                                                                                           | —              |
| `pnpm typecheck`                  | 递归六个包的 typecheck                                                                                                          | docs 那条自含      |
| `pnpm lint` / `pnpm fix`          | 递归 `oxlint .` / `oxfmt`                                                                                                   | 否              |
| `pnpm test`                       | 根 `vitest run`                                                                                                            | 否（走源码别名）       |
| `pnpm test:types`                 | `vitest run --typecheck.enabled`                                                                                          | 否              |
| `pnpm openapi` / `openapi:check`  | core 的 `tsx scripts/gen-openapi.mts [--check]`                                                                            | 否              |
| `pnpm deps:check`                 | `dpdm --exit-code circular:1` 加**四个入口**：core / typegen / response-types 的 `src/index.ts` 与 `packages/web/server/index.ts` | 否              |
| `pnpm console` / `console:server` | web 的 `vite` / `tsx watch server/index.ts`，两条都自含 build:core                                                               | 自含             |
| `pnpm gen:types`                  | typegen 的 `tsx scripts/gen-types.mts`：读本地 `corpus/`，写 `packages/response-types/src/generated/`                            | 否              |
| `pnpm types:check`                | 同一个脚本加 `--check`：有样本时逐字节比对产物与证据；**零样本时验 barrel 与产物树是否一致**                                                                 | 否              |
| `pnpm build:docs`                 | docs 的 build 全链，六步                                                                                                        | 自含             |
| `pnpm docs:dev`                   | docs 的 dev（自含 build:core + docs:api）                                                                                      | 自含             |

`packages/docs` 的 `build` 是六步串联，顺序有讲究：

```
build:core → docs:api → check:includes → check:sidebar → next build → check:links
```

两道静态门排在 `next build` **之前**：区段或侧边栏的问题十几秒就红，不用等几分钟的整站构建。

<Callout type="info">
  `pnpm fix` / `pnpm lint` / `pnpm sort` 都用 `--filter=./packages/*`，所以**根级的
  `.ts` 文件永远不被检查或格式化**（`vitest.config.ts`、`oxlint.config.ts`、`.husky/husky-tasks.ts`）。
  `packages/codemod` 也没有定义 `fix`。
</Callout>

## 测试 [#测试]

配置在根 `vitest.config.ts`，`include` 四条：`core` / `codemod` / `typegen` / `web` 各自的 `test/**/*.test.ts`。`codemod` 与 `typegen` 包内还各有一份 `vitest.config.ts` 供单跑，但**必需检查跑的是根脚本** —— 不收进这条 `include` 等于那些用例在 CI 里不存在。

关键别名：`/^amagi\/(.*)$/` → `packages/core/src/$1`。**core 的用例因此走源码，`pnpm test` 不需要 dist** —— 与文档站那一侧相反。

### 布局 [#布局]

| `core/test/` 下的目录                                | `.test.ts`    | `.test-d.ts` | 快照            | 覆盖什么                                                   |
| ------------------------------------------------ | ------------- | ------------ | ------------- | ------------------------------------------------------ |
| `platforms/`（含 `legacy/`）                        | 75            | 1            | 5             | 四平台端点行为、签名、judge、配置；`legacy/` 是 v6 保留实现的签名与 URL（公开面基线） |
| `contracts/`                                     | 11            | 1            | —             | 契约层                                                    |
| `validation/`                                    | 6             | —            | 2             | zod schema 与路由表                                        |
| `model/` / `runtime/` / `server/` / `transport/` | 4 / 4 / 5 / 6 | —            | 1 / — / 1 / — | 事件、管线、路由、传输                                            |
| `contract/`                                      | 4             | —            | 4             | **公开面、请求面与 known-defects 快照**                          |
| `client/`                                        | 10            | 1            | —             | 门面、fetcher、login 类型                                    |
| `types/`                                         | 1             | 13           | —             | 响应类型与索引签名                                              |
| 其余（compat / errors / openapi / utils / verify）   | 6             | —            | —             | compat、errors、openapi、utils、verify                     |
| **合计**                                           | **132**       | **16**       | **13**        |                                                        |

`helpers/` 下 4 个文件不是测试，是共用工具（adapter 注入、熵源冻结、fixtures、监听端口）。另外三个包的 `test/` 小得多：`typegen` 15 个、`web` 24 个、`codemod` 1 个。

### `test` 与 `test:types` 的分工 [#test-与-testtypes-的分工]

`pnpm test` 只跑 172 个 `*.test.ts`、3,824 个用例（`typecheck.enabled` 默认关）。`pnpm test:types` 把 16 个 `*.test-d.ts` 也加进来，共 188 个文件、3,941 个用例，用 `packages/core/tsconfig.test.json` 做类型检查。数字都由这两条命令末尾的 `Test Files` / `Tests` 行量。

**两个都必需**，因为 `packages/core/tsconfig.json` 的 `exclude` 排除了 `**/*.test.ts` 与 `**/*.test-d.ts` —— `pnpm typecheck` 抓不到测试文件里的类型错误，只有 `test:types` 能。

### 快照锁的是什么 [#快照锁的是什么]

13 个快照文件全在 `test/**/__snapshots__/`：

| 快照                                                                    | 锁住                                                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `contract/public-surface`                                             | 主入口 94 个名字（93 个具名导出 + `default`）、每个导出的运行时类型、client 顶层与四平台子对象的键集合、构造函数静态属性 |
| `contract/fetcher-surface`                                            | 四平台 static + bound 两种形态的方法名列表，以及工具集的键集合                                   |
| `contract/request-surface`                                            | `client.<平台>.request` 的手挑签名步骤面                                            |
| `contract/known-defects`                                              | 全套用例里 `KNOWN-DEFECT:` 标题的清单                                               |
| `platforms/legacy/api-urls`                                           | 若干端点的完整 URL 字符串（易变字段替换为占位）                                                |
| `platforms/legacy/sign-douyin` / `sign-kuaishou` / `sign-xiaohongshu` | 冻结熵源后签名算法的确定输出                                                            |
| `platforms/legacy/default-configs`                                    | v6 保留实现的默认配置                                                              |
| `validation/contract`                                                 | 四平台的 methodType 列表、路由表、每个 methodType 的接受键与默认值                             |
| `validation/xiaohongshu`                                              | 小红书校验表                                                                    |
| `model/events`                                                        | 12 个事件名与四种负载结构                                                            |
| `server/routes`                                                       | HTTP 成功响应的键集合                                                             |

<Callout type="warn">
  **签名快照发生变化 = 线上功能损坏**，而类型检查与 lint 都发现不了。任何情况下都不要用
  `vitest -u` 更新签名快照 —— 快照变了先假设是自己搬错了。这是这个仓库最硬的一条规矩。
</Callout>

### known-defects [#known-defects]

一种把「已知错误行为」显式记账的机制：用例标题以 `KNOWN-DEFECT: ` 开头，一个专门的用例递归扫 `test/` 收集全部这类标题、快照化，并断言清单非空、每条标题够长。

含义是「v6 行为错误但已钉死」，构成修复清单。**修掉一条 → 对应用例必然失败 → 必须显式改写或删除那个用例**，不允许注释掉或加 `.skip`。这个数字只应下降。

## CI 门禁 [#ci-门禁]

门禁在 `ci.yml`（push/PR 触发），发布在 `release.yml`（`v*` tag 触发，维护者本地 `pnpm run release` 推出来）—— 两者分家，发布永远不被门禁拦。核心是 `ci.yml` 的 `quality` job —— 它**恒跑**（连只改文档的提交也跑），且是构建/预览链路的前置，任一步失败整条流水线红。

| 步骤                   | 什么让它红                                                                                                                                                                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pnpm typecheck`     | 任一包类型错误；docs 那条还串了三道静态门                                                                                                                                                                                                                                                                    |
| `pnpm lint`          | oxlint 非 0（实际只有 `no-unused-vars` 是 error 级）                                                                                                                                                                                                                                                |
| `pnpm test`          | 172 个文件 / 3,824 个用例任一失败，含全部快照                                                                                                                                                                                                                                                              |
| `pnpm test:types`    | 16 个 `*.test-d.ts` 的类型错误                                                                                                                                                                                                                                                                   |
| `pnpm openapi:check` | 已提交的 `openapi.json` 与四个 registry 现算结果不逐字节一致                                                                                                                                                                                                                                                |
| `pnpm deps:check`    | dpdm 发现任何循环依赖（必须 0 环）                                                                                                                                                                                                                                                                      |
| `pnpm types:check`   | 落盘那一层自己跑不通，或 **barrel 与产物树不一致**（这条零样本也验，2026-09-10 补）。&#x2A;*它验不了「产物与样本一致」** —— 样本不进 git，没有样本时脚本明说跳过比对，不假装通过；残留文件检测也在零样本时短路掉。一致性只在本地有样本的机器上验                                                                                                                                               |
| `pnpm build:docs`    | 整站构建失败，或站内出现死链                                                                                                                                                                                                                                                                             |
| 控制台前端构建              | `pnpm --filter @ikenxuan/amagi-web run build` 失败 —— 缺 `index.html`、Tailwind 插件没配、CSS 里 `@import` 的包解析不开这类 `tsc --noEmit` 碰不到的事；或 JS 产物超预算（**两个预算**：首屏 640 KB、产物合计 840 KB，2026-09-06 实测 635 KB / 784 KB），那通常是 Node-only 的东西被写成了值 import 漏进浏览器包。**判据是体积不是 grep 关键字** —— minify 之后那些标识符一个都搜不到 |

`changes` job 先算一次「这次改的是不是全在**不发版的包**里」（判据是变更清单里有没有 `^packages/(docs|web)/` 之外的文件；`docs` 与 `web` 都 `private: true`，全仓只有 `packages/core` 会发布），用来决定跳不跳发版链路 —— 但**质量门禁不跳**，文档站与控制台的构建照跑。output 名字仍叫 `docs_only`，那是为了不动下游那个 `if:`。历史上这里踩过坑：用触发器的 `paths-ignore` 把文档站整条流水线关掉，代价是文档站的回归永远进不了 CI。

### 文档站的三道门 [#文档站的三道门]

三个脚本都带「零产物即 exit 1」的自毁开关 —— 空输入下「没问题」是平凡真，必须主动拒绝。

| 脚本                   | 断言                                                                  |
| -------------------- | ------------------------------------------------------------------- |
| `check-includes.mjs` | `<include>` 引用的代码区段还存在                                              |
| `check-sidebar.mjs`  | 每个侧边栏条目有图标、图标名是 `lucide-react` 的真实导出、分区分隔符只有一层、折叠目录只许出现在 OpenAPI 子树 |
| `check-links.mjs`    | 扫 `.next/server/app` 的预渲染 HTML，内部 `/docs` 链接都指向真实页面                 |

`check-includes` 同时挂在 `typecheck` 与 `build:docs` 上，**这不是冗余**：整站构建是最容易被环境挡住的一步（Turbopack 起不了子进程、`next/font` 取不到 Google Fonts 都能让它失败），而「`<include>` 区段在不在」不该被那一步绑住。

## 代码约定 [#代码约定]

### 提交信息 [#提交信息]

`commit-msg` 钩子校验类型，&#x2A;*允许列表内嵌在 `.husky/husky-tasks.ts`**（九种，见[贡献指南](/docs/v7/dev/contributing)）。

<Callout type="warn">
  `pre-commit` 钩子目前**空转**：它的第一行 `. "$(dirname -- "$0")/_/h"` 是 husky v8 的写法，
  而 v9 的调用链是「shim 先 source 那个文件、再执行本文件」，于是这一行会二次进入 shim，
  算出一个不存在的路径后 `exit 0`，永远走不到更新 `packages/core/package.json` 的 `timestamp` 那段。
  证据：那个 `timestamp` 已经几个月没变过。删掉钩子开头那两行即可修复。
</Callout>

### lint 与格式化 [#lint-与格式化]

偏离工具默认值的设置（三份同名配置分别在根、`packages/core`、`packages/docs`，**内容逐字相同**）：

| 项                               | 值                           | 默认    |
| ------------------------------- | --------------------------- | ----- |
| `semi`                          | `false`                     | 加分号   |
| `singleQuote`                   | `true`                      | 双引号   |
| `printWidth`                    | `140`                       | 80    |
| `trailingComma`                 | `'none'`                    | 视工具而定 |
| `sortImports.newlinesBetween`   | `true`                      | —     |
| oxfmt `ignorePatterns`          | `**/*.html`、`**/*.mdx`      | —     |
| oxlint `categories.correctness` | `'warn'`（**降级**）            | error |
| oxlint 唯一 error 级规则             | `no-unused-vars`（`^_` 前缀豁免） | —     |

<Callout type="info">
  仓库里的 `.md` 文件**不交给 oxfmt** —— 现存的 README、设计文档在 oxfmt 眼里全是「未格式化」的。
  写 Markdown 时不要为了让 `oxfmt --check` 变绿去格式化它们。
</Callout>

### 注释语言 [#注释语言]

代码注释与 JSDoc **一律中文**，且倾向于写「为什么」而不是「做什么」：解释取舍、记录踩过的坑、指出容易误解之处。这不是风格偏好 —— 这个仓库的很多约束（依赖方向、快照纪律、装配点）只有靠注释才能传递。写新代码时保持这个密度。

### 生成物 vs 提交物 [#生成物-vs-提交物]

| 路径                                                                       | 状态                  | 由什么重新生成                                                                                                                                                           |
| ------------------------------------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/core/dist/`                                                    | gitignore           | `pnpm build:core`                                                                                                                                                 |
| `packages/docs/.source/`                                                 | gitignore           | `fumadocs-mdx`（docs 的 postinstall）                                                                                                                                |
| `packages/docs/content/docs/v7/usage/api/http/`                          | gitignore           | `pnpm docs:api`（80 个端点页 + 索引）                                                                                                                                     |
| `packages/docs/content/docs/v7/usage/api/sdk/`                           | gitignore           | `pnpm docs:api`（4 个平台页）                                                                                                                                           |
| `packages/docs/content/docs/v7/usage/api/types/`                         | gitignore           | `pnpm docs:api`（8 页，TypeDoc 抽 JSON 后的渲染产物）                                                                                                                        |
| `corpus/`（仓库根，**不在 `packages/core/` 下**）                                 | gitignore（三类例外见下一行） | 控制台录制（`pnpm console`）或 `pnpm record:corpus`。响应体（`*.responses.json`）是运行时内容，只留本地                                                                                    |
| `corpus/seeds.json`、`corpus/**/*.doc.json` 与 `corpus/**/*.requests.json` | **提交**              | 手写的根种子与注释 sidecar，加上请求集合（只含公开作品 / 账号 / 关键词的真值，凭证走 `.env`，别人拿它就能重放）—— 这是 `corpus/**/*.json` 那条 gitignore 刻意留的三个例外。当前 66 份、54 KB，覆盖 62 个端点（B站 23、抖音 22、快手 4、小红书 13） |
| **`packages/response-types/src/generated/`**                             | **提交**              | `pnpm gen:types` —— **两层 barrel（根与 `<平台>/index.ts`）只有全量生成会写**，控制台的单端点「就地生成」按设计不碰它们。当前 155 个文件，覆盖 65 个端点（B站 23、抖音 25、小红书 13、快手 4）                                  |
| **`packages/core/openapi.json`**                                         | **提交**              | `pnpm openapi`，CI 用 `--check` 逐字节守住                                                                                                                               |
| `packages/core/CHANGELOG.md`                                             | 提交                  | 已冻结 —— release-please 时代的产物；新 changelog 由 changelogithub 直接写成 GitHub Release，不落文件                                                                                 |
| 13 个 `*.snap`                                                            | 提交                  | vitest（&#x2A;*不要随手 `-u`**）                                                                                                                                        |

有两处生成物要你手动同步：改了端点声明重跑 `pnpm openapi`，录了新样本重跑 `pnpm gen:types`，两次都得把产物一起提交。**漏跑会不会红，两边的答案不一样**：`openapi.json` CI 逐字节守得住；生成的响应类型只在**树不自洽**时红（`pnpm types:check` 零样本时验「barrel 与产物树一致」，2026-09-10 补），而「产物与手上样本一致」在 CI 上没有证据，只有本地跑才验得了。其余提交物（`*.snap`）由 vitest 自己写回，不用手动重跑。

## codemod [#codemod]

`packages/codemod` 是 v6 → v7 的**消费方**代码改写工具，仓库内私有、不发布。纯文本启发式改写，不解析 AST。

九条规则：

| 规则                       | 做什么                                                                            |
| ------------------------ | ------------------------------------------------------------------------------ |
| `typeMode-strict`        | 删掉 `typeMode: 'strict'`（已是默认）                                                  |
| `typeMode-loose`         | 删掉 `typeMode: 'loose'` 并注入 TODO                                                |
| `error-amagiError`       | `r.error.amagiError.errorDescription` → `r.error.message`                      |
| `error-errorDescription` | `r.error.errorDescription` → `r.error.message`                                 |
| `register-routes`        | `registerXxxRoutes(` → `createXxxRoutes(`                                      |
| `api-routes-import`      | 从 import 里删 `XxxApiRoutes` 并注入 TODO                                            |
| `r-code-read`            | 检测 `.code` 读法，**只标不改**                                                         |
| `validation-catch`       | catch 块里出现 ZodError / `.issues` 时注入 TODO                                       |
| `events-payload-meta`    | 实例总线监听器的负载读法进 `meta`（`d.platform` → `d.meta.platform` 等）；顶层 `amagiEvents` 一字不动 |

调用方式：

```bash
pnpm exec tsx packages/codemod/src/cli.ts v6-to-v7 <目录或文件>
```

**改动就地写回**，跑之前先备份或先对副本运行。它是幂等的 —— 已有的 `// TODO(amagi-v7):` 行在跑规则前会被换成哨符、跑完原位放回，所以连跑两次不会翻倍。


# 翻页与会话 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/session)

> 声明式翻页的收敛条件与聚合方式，扫码登录的状态机，以及实现与设计文档不一致的几处



# 翻页与会话 [#翻页与会话]

两种「一次调用对应多次网络往返」的机制。翻页是**无状态的**，写在端点声明里；会话是**有状态的**，不是端点。

## 声明式翻页 [#声明式翻页]

端点声明里的 `paginate` 槽位。执行在 `runtime/paginate.ts`，它**不 catch 任何异常**（唯一的 catch 在 `execute`）。

### 算法 [#算法]

```
limitKey = limitParam ?? 'number'          // 读「想要多少条」的参数名
countKey = countParam ?? limitKey          // 写「本页要多少条」的参数名
target   = resolveTarget(params[limitKey], maxPageSize)   // 循环外算一次

while (collected.length < target):
    pageSize = min(target - collected.length, maxPageSize)   // 逐页收窄
    pageParams[countKey] = pageSize
    非首页且 pageIntervalMs > 0 → sleep(pageIntervalMs)
    page = runPage(pageParams, isFirst ? 'initial' : 'page')
    失败 → 首页：立刻返回该错误；否则 break 返回部分结果（tolerate 时再记进 interrupted）
    items(page) 非空数组 → 累积
    !hasMore(page) → break
    本页 items 非数组或为空 → break
    pageParams = nextParams(pageParams, page)

return { lastPage, pages, items: collected.slice(0, target), interrupted? }
```

五个容易忽略的细节：

* **`resolveTarget`** 对非有限数回退到 `maxPageSize`，负数归 0，其余 `Math.trunc`。`number: 0` 意味着**一个请求都不发** —— 结果落 `PaginateOutcome` 的 `empty: true` 判别支，没有 `lastPage` 可言。
* **page-size clamping 包含第一页** —— `pageSize` 写回 `countKey` 是在循环内每轮都做，不是只在后续页做。
* **停止条件顺序固定**：先 `hasMore`，再「本页 items 为空」。
* **没有最大页数上限**，只靠上面两个条件收敛。目标条数是唯一的硬边界。
* **翻页间隔 `pageIntervalMs` 只加在页与页之间**：首页前、末页后都不等。等待走 `execute` 的可注入 `sleep`，测试不必真等。

`execute` 侧：翻页分支排在首次 build / sign **之前**，每页回调里重新 `build` 并&#x2A;*重新 `sign`**，再走 send / decode / judge / `retryOn`。所以 `meta.attempts` = 页数 + 各页重试数，第 2 页起 trace 的 `reason` 是 `page`。

### 15 个端点的共同约定 [#15-个端点的共同约定]

当前 15 个用 `paginate` 的端点有四条一致的做法，读任何一个都能推到其余：

1. **全部省略 `limitParam` / `countParam`** —— 读写都用 `number`。
2. **收尾全部写在 `paginate.merge` 里，解构 `{ lastPage, items }`** —— `merge` 的第一参是收窄好的 `PaginatedValue<TPage, TItem>`：`lastPage` 恒有值（空跑由 `empty` 判别支单独承载），`items` 是跨页累积并截断到目标条数的条目。`PaginatedValue` &#x2A;*不带 `pages`**（旧结构留每页完整解码体、没人读，纯内存滞留，已删）。
3. **全部声明了 `partial: 'tolerate'`** —— 中途某页失败时保留已取数据，见下文「中途失败」。
4. **快手 5 个翻页端点都声明了 `pageIntervalMs`**：评论 / 评论回复 / 用户作品 `1200`（取 ksp 参考实现的间隔），两个搜索端点 `10_000`（搜索接口对连续翻页更敏感）；其余平台不设间隔。

`merge` 的产出形状统一是「最后一页的浅拷贝 + 跨页聚合后的 items 塞回列表字段」（`...lastPage` 直接展开，因 `lastPage` 恒有值、字段保持必填，不必再 `?? {}` 兜底又断言回去）。所以**调用方看到的不是分页结构，而是平台原始形状**：

| 平台端点           | maxPageSize | items 字段                                  | hasMore 判据                                                |
| -------------- | ----------- | ----------------------------------------- | --------------------------------------------------------- |
| 抖音 评论 / 评论回复   | 50 / 3      | `comments`                                | `has_more === 1`                                          |
| 抖音 三个列表类       | 18          | `aweme_list`                              | `has_more === 1`，但 `userRecommendList` 是**布尔** `=== true` |
| 抖音 合集作品        | 20          | `aweme_list`                              | `has_more === 1`                                          |
| 抖音 搜索          | 15          | `user_list` 或 `data`                      | `has_more !== 0`（`undefined` 也算有更多）                       |
| B站 评论          | 100         | `data.replies`                            | `cursor.is_end !== true`                                  |
| 快手 评论 / 用户作品   | 50 / 12     | 嵌套三层                                      | `pcursor` 非空串                                             |
| 快手 评论回复        | 50          | `data.visionSubCommentList.subCommentsV2` | `pcursorV2` 非空串&#x2A;*且不是 `'no_more'`**                   |
| 快手 搜索用户 / 搜索作品 | 30 / 20     | `users` / `feeds`                         | `pcursor` 非空串&#x2A;*且不是 `'no_more'`**（复用 `hasNextCursor`） |
| 小红书 笔记评论 / 子评论 | 50 / 10     | `data.comments`                           | `data.has_more === true`                                  |

B站评论是唯一带**去重 + 二次截断**的（按 `rpid` 去重后再按 `params.number` 截断）。快手用户作品是唯一不做「最后一页浅拷贝」而是重建扁平结构的。

快手那两条走 PC GraphQL 的「到底了」有两种写法 —— 空串与字面量 `'no_more'`，所以判据走 `endpoints/define.ts` 的 `hasNextCursor`（两者都算到底）。只判空串的话最后会多打一次空页请求。

没有「共几页」「是否还有更多」之类的分页元信息透出给调用方 —— 想知道实际发了几个请求看 `meta.attempts`。

### 中途失败：返回部分结果，`partial: 'tolerate'` 再标出截断 [#中途失败返回部分结果partial-tolerate-再标出截断]

* **首页失败**：没有可保留的，整体失败。
* **第 2 页起失败**：停在这一页，带着已取条目照常 `merge`，信封是**成功**（v7 有意偏离 v6 的「任一页失败即整体失败」）。`lastPage` 是最后一个**成功**的页。
* **端点声明了 `tolerate`**（现在 15 个翻页端点都声明了）：失败页的错误额外进 `PaginatedValue.interrupted`，同时落到信封的 `meta.incomplete`（`{ kind, code, message }`）。没声明的端点不额外标注，部分结果与正常收尾同形。

对声明了 `tolerate` 的端点，截断不是静默的：完整结果的 `meta` 上**没有** `incomplete` 这个键，在意条数的调用方检查它就够。

<Callout type="info">
  **快手翻页游标**：评论的 `pcursor` 由 `api.ts` 写进 GraphQL variables；`userWorkList` 的 `build`
  以前用字面量对象丢掉了 `pcursor`、每页都请求首屏，已修（`endpoints.test.ts` 断言第二页 URL 带上第一页的游标）。
</Callout>

## 会话（扫码登录） [#会话扫码登录]

多步有状态流程**不是端点**。四个平台的 `client.<平台>.login` 都提供 `qrcode()`（新建）与 `resume(blob)`（从 `serialize()` 的产物恢复）；B站另有 `refreshCredential` 做 Cookie 续期。

分工：引擎（`runtime/session.ts`）负责轮询循环、退避、超时、取消与 challenge 编排；平台策略（`platforms/<平台>/session/qrcode.ts`）只写协议细节，平台码 → phase 的映射不外泄。

### 状态机 [#状态机]

<Mermaid
  chart="stateDiagram-v2
  [*] --> pending: qrcode() 取到码
  pending --> scanned: 已扫，待确认
  scanned --> challenge: 需应答短信/图形验证码
  challenge --> success: answer() 通过
  scanned --> success: 直接确认
  pending --> expired: 二维码过期
  pending --> rejected: 用户拒绝
  challenge --> risk: 风控
  success --> [*]: 产出 credential
  expired --> [*]
  rejected --> [*]
  risk --> [*]
  pending --> failed: 其它失败
  failed --> [*]"
/>

`LoginState` 是按 `phase` 判别的联合类型，8 个取值。终止态是 `success` / `expired` / `rejected` / `risk` / `failed`。

`Credential` 统一为 `{ cookie, expiresAt?, raw }`。&#x2A;*当前四个平台的登录策略都只填 `cookie` 与 `raw`，不填 `expiresAt`** —— 平台响应里没有可靠的会话过期时刻。别把 `Qrcode.expiresAt`（二维码本身的过期时间，B站策略里取码后 3 分钟）误当成凭证过期时间。

### 三种消费方式 [#三种消费方式]

```ts twoslash
// login 在四个平台上都有；此处演示三种消费形态的写法差异
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
const session = client.bilibili.login.qrcode()

// ① watch 回调
const outcome = await session.watch({
  onQrcode: (qr) => console.log(qr.content),
  onScanned: () => console.log('已扫码')
})
if (outcome.ok) console.log(outcome.credential.cookie)

// ② for await
for await (const state of session) {
  console.log(state.phase)
}

// ③ 手动单步
const first = await session.start()
const next = await session.next()
```

<Callout type="warn">
  **`watch()` 返回的不是 `AmagiResult`。** 它是 `{ ok: true, credential } | { ok: false, error }` ——
  没有 `success` / `data` / `message` / `meta`。早期设计稿里写的
  `result.data.cookie` 是早期草稿，实际要写 `outcome.credential.cookie`。同样从信封收窄成裸
  `{ ok }` 联合的还有 `SmsChallenge.sendCode()` 与策略的三个方法。
</Callout>

### 实现与设计文档的其余差异 [#实现与设计文档的其余差异]

设计文档比实现旧，以下几条会直接影响你写出来的代码：

| 设计文档说                               | 实际实现                                                                                                 |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
| abort 的错误码是 `ABORTED`               | 是 `INTERNAL_ERROR`（`ABORTED` 根本不在 `AmagiErrorCode` 联合里）；且只在**每轮循环开头**检查 `signal.aborted`，飞行中的请求不会被中断 |
| 每次轮询进 trace、`attempts` 累加           | 会话 `meta` 恒 `durationMs: 0` / `attempts: 0`，没有 `trace`，也不发 `http:*` / `network:*`                    |
| `busy` 退避加倍在引擎里                     | 在抖音策略里，且**没有任何测试断言它**                                                                                |
| `biz_trace_id` / `verify_way` 由引擎维护 | 两个 ctx key 只有读取点、**没有写入点**；发码闭包自己另生成一个，于是发码与验码用的是两个不同的 `biz_trace_id`                                |
| 平台码在 `state.raw` 里                  | `LoginState` 各分支都没有 `raw` 字段，原始响应只在失败分支的 `error.raw` 里                                               |

另外两条实现事实，文档里没写但影响很大：

* **抖音会话完全不走 v7 transport。** 策略每步新建 `DouyinPassportClient`，它走 `transport/legacy.ts` 的 v6 路径（`validateStatus: () => true`），且只挑走 `requestConfig` 的 `timeout` / `proxy` / `adapter` 三项，其余（`httpsAgent`、自定义 header 等）被丢弃。B站策略相反，规范地用 `ctx.send`。
* **`resume(blob)` 的 cookie 取自实例，不是 blob。** 反序列化保留了 blob 里的 `cookie` / `token` / `qrcode`，但 `send` 用的是 `makeSessionCtx(platform, 实例cookie).send`。而且 `login.resume` 从未被运行时测试走过。

### 会话请求不带 Cookie 头 [#会话请求不带-cookie-头]

会话用的 HttpClient 建 config 后同样 `headers.delete('cookie')`，但会话路径上**没有 `attachCookie` 的等价物**。所以 `ctx.cookie` 只用作 B站策略里 `mergeSetCookie` 的基底，不会真的作为请求头发出去。

### v6 的登录方法仍在 [#v6-的登录方法仍在]

抖音 4 个 passport 方法（发码 / 验码那套）作为 `@deprecated` 保留在**静态** `douyinFetcher` 上，bound 形态有意不含它们，也不在方法名映射表里。B站的 3 个登录方法是普通端点。新代码走 login 会话。

## 下一步 [#下一步]

* 这些机制暴露给下游的形态：[公开 API 表面](/docs/v7/dev/internals/surface)
* 事件与 meta 的完整规则：[事件与可观测性](/docs/v7/dev/internals/events)


# 签名与反爬 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/signing)

> 签名的两层结构（steps 单一实现、signers 薄壳）、SignPhase 四阶段排序、端点声明与裸请求两条路径如何汇入同一份实现，以及有状态签名器为何进程内共享



# 签名与反爬 [#签名与反爬]

四个平台的反爬参数（抖音 `a_bogus` / `msToken`、B站 `wbi`、快手 `__NS_hxfalcon`、小红书 `x-s` 一组）最终都汇入同一套机制。本页讲解这套机制如何分层、执行顺序由谁保证、两条调用路径如何汇合，以及有状态的签名器为何必须进程内共享。

相关代码位于各平台的 `src/platforms/<平台>/sign/` 目录下，以及机制层的 `contracts/endpoint.ts`。

<Callout type="info">
  本页讲的是签名**如何组织**。签名是否正确是另一回事 —— 抖音采用抽样校验，签名出错时大部分请求仍会成功，因此「请求成功」并不能证明「签名正确」。签名的验证方法见[签名验证](/docs/v7/dev/sign-verify)。
</Callout>

## 两层：steps 是实现，signers 是薄壳 [#两层steps-是实现signers-是薄壳]

每个平台的 `sign/` 目录都是同样两个文件，分工严格：

* **`steps.ts` 是唯一的实现。** 它导出一批**原子 step 工厂**（`msToken()` / `aBogus()` / `wbi()` / `hxfalcon()` …），每个工厂返回一个 `SignStep` —— 一个反爬参数如何计算、写入 query 还是 header、是否重写整条 URL，都在这里。有状态的签名器（下文详述）也位于这一层。
* **`signers.ts` 是薄壳。** 它只把「注册名」映射到「一份 step 清单」，再用 `stepsToSigner` 压成一个签名函数。以抖音为例，`createDouyinSigners()` 即 `{ 'a-bogus': stepsToSigner(douyinBogus(184)), 'x-bogus': stepsToSigner(douyinXBogus(184)) }`，一行对应一个名称，别无其他逻辑。

依赖是单向的：&#x2A;*`signers.ts` 依赖 `steps.ts`，不可反向。** signers 中不应包含任何签名逻辑，所需内容一律从 steps 取用。

<Callout type="warn">
  这套分层是有代价换来的。早先端点声明走 step 清单，而 `client.<平台>.request` 走字符串查表，两者是**各自独立实现的两份签名逻辑**。而签名属于抽样校验、出错不即时报错的场景，两份实现一旦产生分歧，几乎无法通过测试发现。因此现在的原则是：签名只保留一份实现（steps），其余皆为薄壳。修改签名逻辑，只改 `steps.ts`。
</Callout>

## SignPhase：执行顺序由机制层保证 [#signphase执行顺序由机制层保证]

一次签名往往包含多个步骤，且有先后之分。抖音的 `msToken` 必须先写入 URL，`a_bogus` 才能将其一并签入；`secsdk` 则需等主签名完成后再重写整条 query。这个顺序若交由每个端点作者手写，早晚会有人写反。

因此，顺序被收拢到机制层的 `SignPhase`（`contracts/endpoint.ts`），共四个阶段：

| 阶段         | 作用                  | 示例                                                 |
| ---------- | ------------------- | -------------------------------------------------- |
| `prepare`  | 主签名前的补参             | 按 cookie 补 `webid`                                 |
| `token`    | 本地随机令牌，必须先于主签名进 URL | 抖音 `msToken`                                       |
| `sign`     | 主签名                 | `a_bogus` / `x_bogus` / `wbi` / `x-s` / `hxfalcon` |
| `finalize` | 收尾                  | 抖音 `secsdk` 重写整条 URL、小红书追加 `x-b3-traceid`          |

`stepsToSigner(steps)` 将一串 step 压成一个签名函数：先按 `phase` **稳定排序**（`prepare` → `token` → `sign` → `finalize`），同一 phase 内保留数组的出现顺序，再依次 `apply`。稳定排序是关键 —— 它意味着 `[aBogus(), msToken()]` 与 `[msToken(), aBogus()]` 的执行结果完全一致，因为 `token` 阶段恒排在 `sign` 之前。即便端点作者写错顺序也不会出错。

```ts
// contracts/endpoint.ts —— 两条路共用这一个函数
export const stepsToSigner = (steps: readonly SignStep[]): SignFn => {
  const ordered = steps
    .map((step, index) => ({ step, index }))
    .sort((a, b) => PHASE_ORDER[a.step.phase] - PHASE_ORDER[b.step.phase] || a.index - b.index)
    .map((entry) => entry.step)
  return async (spec, ctx) => {
    let current = spec
    for (const step of ordered) current = await step.apply(current, ctx)
    return current
  }
}
```

## 两条路径汇入同一处 [#两条路径汇入同一处]

签名有两个入口，过去各自独立，如今都汇入 `stepsToSigner`：

* **端点声明**（`fetcher` 走这条）：端点的 `sign` 字段直接写 `SignStep[]`，例如 `sign: [msToken(184), aBogus(), secsdk()]`。runtime 解析 `SignDecl` 时用 `stepsToSigner` 压成签名函数。
* **裸请求**（`client.<平台>.request` 走这条）：`amagi.sign` 接收 `SignDecl`，可以是注册名字符串（`'a-bogus'`，经 `signers.ts` 这层薄壳查表，其内部仍是 `stepsToSigner`）、`false`（不签），或调用方自行列出的 `SignStep[]`（从 `@ikenxuan/amagi/sign-steps` 引入工厂，见使用文档[自定义请求](/docs/v7/usage/advanced/custom-request#精细控制反爬参数)一节）。

无论从哪条进入，最终排序、执行的都是同一个 `stepsToSigner`，使用的也都是 `steps.ts` 里那批工厂。因此手动指定的 `[wbi()]` 与默认的 `'wbi'` 不可能产生两种签名结果。

<Callout type="info">
  `SignDecl` 还保留了字符串形态（注册名）与一次性函数形态，与 step 清单渐进共存。字符串形态便于端点声明处引用平台预设，函数形态用于一次性的自定义签名 —— 但它们背后都是同一套 step 实现。
</Callout>

## 有状态的签名器是进程内共享的 [#有状态的签名器是进程内共享的]

不是所有签名都是纯函数。有两个平台的签名器带状态，而且这个状态是**进程级、跨实例共享**的，不是每个 `amagi()` 实例一份：

* **B站 `wbi`**：`wts` / `w_rid` 需要用一对从 `/nav` 接口取得的 key（`img_key` / `sub_key`）。这对 key 带 TTL 缓存（`WBI_TTL_MS = 30 * 60 * 1000`，即半小时），由模块级的 `sharedWbi = createWbiSigner()` 持有。多个 client 实例共用这一份缓存，不会各自去请求 `/nav`。
* **快手 `hxfalcon`**：`__NS_hxfalcon` 的计算带有调用计数、启动随机数与匿名 kww 缓存，由模块级的 `sharedKuaishouSigner = createKuaishouSigner()` 持有。`count` 每签一次递增，`startupRandom` 在签名器创建时随机一次，此后整个进程复用同一个值。

<Callout type="warn">
  容易误解的一点是：这些状态是**进程内共享**的，而非按实例隔离。`sharedWbi` / `sharedKuaishouSigner` 都是模块顶层的常量，`import` 一次即固定。因此两个 client 实例签同一个接口，用的是同一份 `/nav` 缓存、同一个 hxfalcon 计数。测试中若要隔离状态，需调用 `resetSharedWbiCache()` / `resetKuaishouSignerState()` 显式重置，不能依赖「新建一个 client」——新建的 client 得到的仍是这两个共享实例。
</Callout>

这样设计是因为这些状态本就属于进程级：`/nav` 的 key 是与账号无关的全局值，重复请求只是浪费；hxfalcon 的计数模拟的是「同一浏览器会话累计发出的请求数」，进程内连续才符合平台预期。

## 一句话记住分层 [#一句话记住分层]

修改签名逻辑，改 `steps.ts`；新增注册名，改 `signers.ts`（其中不应有任何逻辑）；调整执行顺序，改 step 的 `phase`，不要在端点声明处手动排列数组。想验证签名是否正确，见[签名验证](/docs/v7/dev/sign-verify)，不要以「请求成功」作为证据。


# 公开 API 表面 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/surface)

> 六个导出子路径、默认导入的真实形状、/compat 做了什么、HTTP 服务的两个 startServer



# 公开 API 表面 [#公开-api-表面]

下游能碰到的全部东西。这一页也顺便回答一个反复被问的问题：&#x2A;*为什么有些函数在源码里能看到，装了包却导不出来。**

## 六个导出子路径 [#六个导出子路径]

| 子路径            | 导出什么                                                                                 | 为什么独立                                        |
| -------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| `.`            | 主入口：93 个运行时名 + 公开类型（构建期从 `src/index.ts` 抽成类型参考）                                      | —                                            |
| `./express`    | `express` 的 default + 18 个类型                                                         | core 自身依赖 express，下游自组装应用时不必再装一份             |
| `./axios`      | `axios` 的全部具名 + default                                                              | 同上                                           |
| `./signing`    | 四个平台的签名算法 + 验证工具（全具名、无 default；小红书只有形状检查）                                            | 纯函数、不碰网络与 cookie，浏览器里也能跑；给「验证签名实现是否还对」用      |
| `./sign-steps` | 四个平台的反爬 step 工厂（按平台分命名空间：`douyin` / `bilibili` / `kuaishou` / `xiaohongshu`）+ 四个签名类型 | 给 `client.<平台>.request` 手挑 / 调参签名步骤用；与默认签名同源 |
| `./compat`     | v6 兼容门面                                                                              | 见下文                                          |

顶层 `main` / `module` / `types` 指向 `dist/default/*`。CJS 不产 `.d.ts`，`types` 条件同时服务 `import` 与 `require`。

<Callout type="warn">
  `./signing` **全是具名导出，没有 default** —— 用 `import { decodeUrl, diagnoseSalt } from '@ikenxuan/amagi/signing'`
  这样按名字取。它整条依赖链不碰 Node 内置模块、网络与 cookie，浏览器里能直接跑；文档站的[签名验证器](/docs/v7/dev/sign-verify)
  用的就是这份代码，与 oracle 测试同源、不会漂移。
</Callout>

主入口的运行时导出面被两道闸门锁住：一份 94 个名字的快照（93 个具名导出 + `default`）+ 一条「导出数 > 50」的兜底断言。加删导出会让快照红，这是刻意的。

### 源码里有、装包后够不到的东西 [#源码里有装包后够不到的东西]

`src/index.ts` 没有导出 `./client` 与 `./server` 的实现层，`package.json` 也没有对应子路径。于是下面这些对装包的人**不可达**：

`startServer`（全选项版）、`StartServerOptions`、`authMiddleware`、`hostWarningMessage`、`mountOpenApiSpec`、`buildOpenApiSpec`、`createRoutes`、`createStaticFetcher`、`createFetcherFromRegistry`、`callEndpoint`、`makeClientCtx`、`createEventBus`、`createLoginSession`。

仓内测试靠 vitest 别名直接 import 内部路径，**那不代表公开面**。写文档或写示例时以 `package.json` 的 `exports` 为准。

反过来也有错位：`isSuccess` / `isFailure` / `unwrap` / `AmagiThrownError` / `AMAGI_BUS_EVENT_NAMES` 是公开导出，但包 README 里一次都没出现。

## 默认导入是什么 [#默认导入是什么]

一个**函数对象**，既可以 `new` 也可以直接调用，两种方式返回等价形状；不传参也能创建。它还挂了 16 个静态属性。

```ts twoslash
import amagi from '@ikenxuan/amagi'

const a = amagi({ cookies: { bilibili: '' } })
const b = new amagi({ cookies: { bilibili: '' } })

amagi.version            // 只读、可枚举、不可配置
amagi.douyinFetcher      // 静态 fetcher（三参签名）
amagi.douyin             // 平台工具集，不含 fetcher / login
```

<Callout type="warn">
  **`amagi.version` 跟随 `packages/core/package.json` 的 `version`，现在在 `7.0.0-beta.*` 预发布线上**
  （`openapi.json` 的 `info.version` 同源）。版本字符串由构建期注入（tsdown 的 `define`），
  运行时读不到 `package.json` 时回落 `0.0.0`。**没有任何逻辑分支读版本号**，它纯粹是对外信息。
</Callout>

### 构造选项 [#构造选项]

<TypeTable
  id="type-table-createClient.ts-ClientOptions"
  type="{
  &#x22;id&#x22;: &#x22;createClient.ts-ClientOptions&#x22;,
  &#x22;name&#x22;: &#x22;ClientOptions&#x22;,
  &#x22;description&#x22;: &#x22;客户端构造选项&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;cookies&#x22;,
      &#x22;description&#x22;: &#x22;Cookie 配置&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ douyin?: string; bilibili?: string; kuaishou?: string; xiaohongshu?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;xiaohongshuSession&#x22;,
      &#x22;description&#x22;: &#x22;与 Cookie 配对的小红书会话材料；旧 cookies 配置仍可单独使用。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;XiaohongshuSessionInput | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;request&#x22;,
      &#x22;description&#x22;: &#x22;请求配置&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestConfig | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;RequestConfig&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;debug&#x22;,
      &#x22;description&#x22;: &#x22;排障开关。打开后两样东西同时出现：失败信封的 `error.raw` 带平台原始响应体，\n每个信封的 `meta.trace` 带这次调用发出的每一条底层请求（URL / 方法 /\n状态码 / 耗时 / 发出原因）。用于排查协议变更、风控页、业务码含义不明，\n以及「这一次调用到底打了几个请求」。\n\n默认 `false`，此时失败信封上**没有** `raw` 这个键、`meta` 上也**没有**\n`trace` 这个键（不是 `undefined` 占位）。`meta.attempts` 与本开关无关，\n一直是准的 —— 计数始终发生，只有明细受开关控制。\n\n`debug` 一个开关同时管 `error.raw` 与 `meta.trace` 两样：两者都只服务排障，\n分成两个名字等于让人多记一个。要**不受开关影响**地逐条观测请求，监听\n`http:request` / `http:response` 事件 —— 它们的负载恒带 `trace`。\n\n原始响应可能很大、也可能带敏感字段，`trace` 里的 URL 含签名参数，\n别在生产里无条件打印。只作用于 client 实例上的 fetcher：静态 fetcher\n（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

`debug` 一个开关管两件事：失败信封多 `error.raw`、信封多 `meta.trace`。关闭时这两个键**根本不存在**。它只作用于 client 形态 —— 静态 fetcher 与 HTTP 路由没有这个开关。

v6 的 `Options` 类型是 `ClientOptions` 去掉 `debug` 的子集，赋值互通。

### 实例形状 [#实例形状]

顶层 8 个键：`startServer` / `events` / `on` / `once` / `douyin` / `bilibili` / `kuaishou` / `xiaohongshu`。

平台命名空间是 `{ ...平台工具集, apiUrls, fetcher, request, login }`，B站另有 `refreshCredential`：

| 命名空间                 | 键                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------- |
| `client.douyin`      | `sign` / `passport` / `credentials` / `apiUrls` / `fetcher` / `request` / `login`      |
| `client.bilibili`    | `sign` / `danmaku` / `apiUrls` / `fetcher` / `request` / `login` / `refreshCredential` |
| `client.kuaishou`    | `sign` / `apiUrls` / `fetcher` / `request` / `login`                                   |
| `client.xiaohongshu` | `sign` / `apiUrls` / `fetcher` / `request` / `login`                                   |

取值链就是文档写的 `client.<平台>.fetcher.<方法>`。`login` 四个平台都有。

`apiUrls` 是 **v7 那份** URL 构造器（`platforms/<平台>/api.ts`），端点自己在用的就是它。
v6 那份（`platforms/legacy/<平台>/API.ts` 的 `douyinApiUrls` 等四个）**不在 v7 门面上** ——
它从两个地方到达：包顶层（`import { douyinApiUrls } from '@ikenxuan/amagi'` 照旧可用），
以及 `@ikenxuan/amagi/compat` 的 `client.<平台>.<平台>ApiUrls`（原名保留）。
两份同名不同义的构造器因此从不在同一个对象上相邻，靠键名分辨的时代结束了。

`request` 是请求模块（`client.<平台>.request`）：打任意 URL，自动过签名 / judge / 重试 / 事件，
返回 `AmagiResult` 信封；`request.axios.*` 是同一实例的原生 axios 语义那一轨。详见
[自定义请求](/docs/v7/usage/advanced/custom-request)。

<Callout type="info">
  `client.events` 是**实例级**总线，`amagi.events` 是 v6 全局单例 —— 两个不同的对象。
  详见[事件与可观测性](/docs/v7/dev/internals/events)。
</Callout>

### 三套等价的 fetcher 入口 [#三套等价的-fetcher-入口]

| 形态 | 拿到它                                              | 签名                                   | 事件 / debug |
| -- | ------------------------------------------------ | ------------------------------------ | ---------- |
| 实例 | `client.<平台>.fetcher`                            | `(options, requestConfig?)`          | 有          |
| 静态 | `amagi.<平台>Fetcher`                              | `(options, cookie?, requestConfig?)` | 无          |
| 绑定 | `createBound<平台>Fetcher(cookie, requestConfig?)` | `(options, requestConfig?)`          | 无          |

唯一的不对称：静态 `douyinFetcher` 额外并入 4 个 v6 passport 方法，bound 形态有意不含。

`request` 与 `apiUrls` **没有静态形态** —— `amagi.douyin.request` / `amagi.douyin.apiUrls` 都不存在。
静态面是「平台工具集 + 静态 fetcher」，而这两样要有实例的 ck 与运行期上下文才有意义。
v6 的 URL 构造器也不在静态工具集上（`amagi.douyin.douyinApiUrls` 不存在）—— 它们的静态形态就是包顶层那份同名导出。

## `/compat` [#compat]

一行改导入就能把 v7 信封回填成 v6 形状，并恢复「参数校验失败抛出」的行为：

```ts twoslash
import amagi from '@ikenxuan/amagi/compat'
```

它是**薄包装 shim，不是第二条代码路径** —— `export * from '../index'` 之后用 9 个同名导出遮蔽原名。

### 逐机制 [#逐机制]

**信封回填**（纯函数，不抛）：

* 成功 → `{ success: true, code: 200, message, data, error: undefined }`
* 失败 → 顶层 `code` 按 `kind` 映射（validation 400 / auth 401 / forbidden·risk 403 / not\_found 404 / rate\_limit 429 / network·internal·unknown 500 / parse 502 / unavailable 503 / timeout 504），`error.code` 取平台业务码或回落顶层码，`error.data` 取 `raw ?? null`，并补回 v6 的 `error.amagiError.errorDescription` 与 `requestType`

**v6 信封上没有 `meta`。**

**抛出行为恢复**：`error.kind === 'validation'` 时抛 `ValidationError('参数验证失败', issues)`；其余走回填。顶层已带 `code` 的响应（passport 那 4 个方法）直接透传，不二次转换。

**一次性迁移提示**：模块求值时向 v6 全局单例发一条 `log:warn`。那个单例**没有默认监听器**，所以不主动订阅就看不到这条提示，也没有测试锁它的文案。

### 爆炸半径 [#爆炸半径]

| 变了                                                                  | 没变                                                                        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 默认导出 / `createAmagiClient` 产出的 client 上四个平台的 `fetcher` 方法返回值        | client 顶层键集合与 v7 完全一致                                                     |
| 四个平台命名空间各多一个 `<平台>ApiUrls` 键（v6 那份 URL 构造器，以原名摊回；v7 的 `apiUrls` 也在） | `client.events` 仍是 v7 **实例级**总线；compat 的静态平台命名空间跟随主入口（同样不带 `<平台>ApiUrls`） |
| 4 个静态 fetcher、4 个 bound 工厂；上述方法在校验失败时改为抛出                           | `startServer` 原样透传 → **HTTP 路由仍返回 v7 信封**                                 |

<Callout type="warn">
  三个名字**没有被遮蔽**：`amagi` / `CreateApp` / `createClient`。也就是说
  `import { amagi } from '@ikenxuan/amagi/compat'` 拿到的是未包装的 v7 门面，返回 v7 信封。
  `login` 命名空间的返回值同样不过回填。想要 v6 形状请用**默认导入**。
</Callout>

`/compat` 在 v7 全程保留，v8 移除。

## HTTP 服务 [#http-服务]

仓库里有**两个** `startServer`，共用同一套挂载零件，但只有一个对外可达。

### 门面版（`client.startServer`） [#门面版clientstartserver]

```
startServer(port = 4567, serverOptions: FacadeServerOptions = {}) => express.Application
```

`FacadeServerOptions` 只有 `openapi?: boolean`（默认 false）与一个测试注入用的 `listen`。&#x2A;*没有 `host`、没有 `token`、没有 `routers`** —— host 固定 `'::'`。

挂载顺序：`json` → `urlencoded` → `GET /`（301 到 apifox）→ `GET /docs`（开了 openapi 就 302 到在线端点参考，否则 301 到 apifox）→ 可选 `GET /openapi.json` → 四个平台路由挂在 `/api/<平台>`。

开始监听时发一条 `log:mark` 事件（**不打 console**）。门面版**不打 host 警告，也没有任何鉴权**。

<Callout type="warn">
  门面版用**实例的 cookie** 挂路由。任何能连上端口的人都在用运营者的 cookie 取数，
  而 host 默认 `'::'`（公网双栈）。这是一个已知的、被 KNOWN-DEFECT 用例记录下来的现状。
</Callout>

### 全选项版（未导出） [#全选项版未导出]

`StartServerOptions` 有 `port` / `host` / `token` / `openapi` / `routers` / `listen`。它在包内部，下游拿不到 —— 文档站上那张全选项表描述的就是这个函数，用不了。

鉴权逻辑：不传 `token` 直通（v6 行为不变）；传了则要求 `Authorization: Bearer <token>`，缺失 / 非 Bearer / 不等值都返 401，body 是精简形状而非完整信封。`GET /openapi.json` 挂在鉴权**之后**，所以设了 token 连规范也要鉴权。

host 警告文案（默认 `'::'` 时经 `console.warn` 打印一次）：

```
[amagi] ⚠️ startServer 默认监听 '::'（公网 IPv4/IPv6 双栈），请显式传 host: '127.0.0.1' 或 'localhost' 限制访问范围（v8 将改默认值）。
```

单测只断言它包含 `'::'`、`'v8'`、`'127.0.0.1'` 三个子串，不是逐字比对 —— 改文案只要保留这三处不会让测试红。

### 路由响应 = 信封 + 一个键 [#路由响应--信封--一个键]

路由与 fetcher 走同一条执行路径（`callEndpoint`），HTTP 侧&#x2A;*只多一个 `requestPath`**。成功响应的键集合被快照锁死：`data` / `message` / `meta` / `requestPath` / `success` —— 没有 v6 的顶层 `code`。

其余行为：全部是 `GET`；query 多值取最后一个；业务失败与校验失败同样 **HTTP 200**，靠 `success` 判别；未注册路径 404；401 只可能来自全选项版 + token。

四个 `createXxxRoutes(cookie, requestConfig?)` **是**公开导出，可以自己挂到别的 Express 应用上。注意它们建 ctx 时不传 `assembly` —— 所以走 HTTP 的调用不发事件、没有 `error.raw`、没有 `meta.trace`。

## 运行时告警清单 [#运行时告警清单]

包在运行时只会发出这几条：

| 触发                            | 出口                             | 内容                               |
| ----------------------------- | ------------------------------ | -------------------------------- |
| 导入 `/compat`                  | v6 单例的 `log:warn`（默认无监听器 → 静默） | 兼容入口提示，v8 将移除                    |
| 全选项版 `startServer` 且 host 取默认 | `console.warn`                 | 见上文                              |
| 网络重试                          | 实例总线 `log:warn`                | `网络请求失败 [...]，Nms 后进行第 N 次重试...` |
| 网络彻底失败                        | 实例总线 `log:error`               | `网络请求失败:`                        |

**所有 `@deprecated` 都只是 JSDoc 标记，运行时零输出** —— `createAmagiClient`（与 `createClient` 是同一个函数对象）、`fetchData` / `fetchResponse`、抖音 4 个 passport 方法、B站 7 个登录方法都不打印任何东西。


# 传输与签名 (https://ikenxuan.github.io/amagi/docs/v7/dev/internals/transport)

> 全仓唯一发请求的地方：header 合并顺序、重试策略、四个平台的签名机制，以及快手那条没接上的线



# 传输与签名 [#传输与签名]

**全仓只有 `transport/` 能发请求。** 这是一条架构约束，不是习惯 —— 端点需要发请求（换游客 cookie、取 wbi key）只能通过 `ctx.send`，由 transport 注入。v6 里签名模块绕过统一入口直连 axios 的问题，在 v7 的结构下不再可能发生。

## HttpClient.send 做的事 [#httpclientsend-做的事]

一次 `send` 的内部顺序：

1. **构造 axios 配置** —— header 合并顺序是 &#x2A;*平台基线 → 实例 `requestConfig.headers` → 单次 `perCall.headers` → `spec.headers`**，每次都从输入重建 `AmagiHeaders`（大小写不敏感）。合并完再按 `spec.dropHeaders` 删头（见下）。UA 原样发出、不改写：a\_bogus 的 UA 摘要、`sec-ch-ua` 品牌、抖音 `browser_name` 与小红书 webprofile 指纹都按同一个 UA 计算（2026-10-07 前这里会剥掉 `Edg/x.y`，签名用的却是原 UA）。
2. **登记 trace 并计数** —— `tracer.begin(...)`，`meta.attempts` 恒等于登记条数。这一步与 `debug` 无关。
3. **发 `http:request` 事件**（装了总线时）。
4. **`axios(config)`**。
5. **成功** → 发 `http:response`，非 2xx 再补一条 `http:error`，返回 `RawResponse`。

`RawResponse` 带 `status` / `statusText` / `headers`（`AmagiHeaders`）/ `setCookie`（**原始数组**）/ `body` / `durationMs` / `url`。

<Callout type="info">
  **刻意不设 `validateStatus`。** 于是非 2xx 走 axios 的失败分支，由 transport 自己决定是不是重试。
  这与 v6 的 `transport/legacy.ts` 相反 —— 那里是 `validateStatus: () => true`，什么状态码都算成功。
</Callout>

## `client.<平台>.request`：第二个入口，同一条管线 [#client平台request第二个入口同一条管线]

`client.<平台>.request`（[自定义请求](/docs/v7/usage/advanced/custom-request)）是 fetcher 之外的第二个发请求入口，但它**不新开执行路径**：axios 归一化后的配置被翻成 `RequestSpec`，现场合成一个一次性的 `EndpointDef`（`client/request/adapter.ts` 的 `makeRequestDef`），再交给同一个 `callEndpoint`。于是下面这些一样都不用重写：

| 管线提供的东西      | 在 request 这条路上的形态                                                   |
| ------------ | ------------------------------------------------------------------- |
| judge        | 平台默认判定表（合成声明不带端点级 judge）                                            |
| 信封           | 同一套 `AmagiResult`，成功 / 失败两支的字段一致                                    |
| 退避重试         | 平台档案的 `retryOn`；抖音另开 `retryFresh`，重试时重新签名生成新的 `msToken` + `a_bogus` |
| observe      | 抖音回收 `webid` 的钩子照跑 —— adapter 只包一层，不替换                              |
| ensureCookie | 抖音的 cookie 审计照跑 —— 缺访客 id 时先铸造再发主请求                                 |
| 事件 / trace   | 与端点同一条线（`http:*` / `network:*` / `api:*`）                           |

代价是它继承了「端点」这个形状：`params` 是空对象（没有参数校验）、没有 `decode` / `normalize` / `paginate`。

两处「axios 语义 → amagi 语义」的转换都在 adapter 里：

* **`toRequestConfig`** 把配置翻给 transport，其中十三个键**不往下传**（`NOT_FORWARDED_KEYS`）：`url` / `method` / `data` 已经进了 `RequestSpec`；`params` / `paramsSerializer` / `baseURL` 已经被 `instance.getUri(config)` 拼进 URL，再传一遍会被内层 axios 拼第二次（`?a=1?a=1`、`baseURL` 双前缀）；`headers` 改从 `requestConfig.headers` 走（签名读的就是它 —— 抖音的 `a_bogus` 用 `ctx.userAgent`）；`adapter` 传下去会在**内层**覆盖掉签名与信封；`transformRequest` / `transformResponse` 漏下去会让 body 永远不序列化；`validateStatus` 下去会与 judge 打架；`responseType` 进 `spec.responseType`，`amagi` 是给 adapter 自己看的。
* **`toAxiosResponse`** 把信封包成 `AxiosResponse`。这个 adapter **恒 resolve** —— axios 的 `settle` 只在内置 adapter 里，自定义函数 adapter 的返回值不经状态校验。所以「失败抛不抛」是 `client/request/index.ts` 按**信封**决定的，与 HTTP 状态码无关；没拿到响应时 `status` 是哨兵 `0`，`AxiosError.response` 留空而不是编一个假的。

自己直接调 `HttpClient.send` 会把上面这一整列**全部**丢掉，且与端点行为分叉 —— 这就是 adapter 存在的理由。

## 抖音的 cookie 审计：缺访客 id 时自动铸造 [#抖音的-cookie-审计缺访客-id-时自动铸造]

受 secsdk 保护的端点（`/aweme/v1/web/music/detail/` 等 14 条 GET）要求 cookie 里带访客 id（`UIFID` 家族），而它**不由登录颁发**——passport 扫码链路只发身份 cookie。缺了它，这些端点稳定回 `403 Blocked by ArgusSecurityPlugin Uifid Not Found`（判 `SIGNATURE_REFUSED`）。

`PLATFORM_RUNTIME.douyin.ensureCookie` 让这件事自愈：每次调用在 prepare 之后、build/sign 之前审计一次 cookie，缺访客 id 就**纯 HTTP 铸造**一个并合并。铸造链路（线上实测）：

1. `GET www.douyin.com`（无 cookie）→ 服务端在 Set-Cookie 里发 `__ac_nonce`。响应体是一份 VMP 挑战页，**不读**；
2. 用 `sign/acSignature.ts` 的 `computeAcSignature` **纯算**出 `__ac_signature`（47 字符，`_02B4Z6wo00f01` 开头）—— 四则运算加字符串拼接，不执行挑战页里的任何脚本；
3. 带 `__ac_nonce + __ac_signature` 再 GET 一次 → 服务端一次性 Set-Cookie：`ttwid` + `enter_pc_once` + `web_sign_token` + `UIFID_TEMP`。`UIFID_TEMP` 的有效期没测过；同一 IP + UA 重复铸造每次拿到的值都不同（2026-10-11 实测）。

三个设计要点：

* **挑战页不解析、不执行**——签名算法已从 JSVMP 字节码里 lift 出来写成纯函数，`MintDeps.getHome` 的返回类型只有 `{ setCookies }`，于是「解析挑战页」在类型上就做不到。代价是抖音换算法不再自动跟随：换版的表现是服务端不认签名、第二发拿不到 `ttwid` / `UIFID_TEMP`，按铸造失败走 ttwid 回落，**没有 vm 回落**。
* **审计永不为调用增加失败**——网络失败、形状变化、签名被拒，一律原样返回，请求按既有路径走（该 `SIGNATURE_REFUSED` 还是它）；实现里不抛错，execute 也不包一层。
* **只补缺失的名字**——已有 `ttwid` 的登录态只追加 `UIFID_TEMP`，不动调用方的设备标识；进程级缓存（key = cookie + UA）让同一 cookie 只铸一次，不设过期，只有铸造成功的结果进缓存（ttwid 回落刻意不进）。

登录完成时（`session/qrcode.ts`）也审计一遍，扫码登录直接产出带访客 id 的凭证。零配置（cookie 都没配）时审计会铸造完整访客 cookie——全新部署的第一次请求就是可用的。测试环境（vitest）默认出口**不出网**，要测铸造就注入 `MintDeps.getHome`（`mint.test.ts` 全部走注入，喂的是 Set-Cookie 行数组——签名纯算之后铸造链路不碰响应体，用不上挑战页 fixture；纯算实现本身由 `ac-signature.test.ts` 拿真实挑战页做 oracle 比对）。 铸造是 amagi 自主发起的出网请求，**有权拒绝**：设 `AMAGI_DISABLE_DOUYIN_MINT=1` 关闭（cookie 保持原样，受保护端点按 `SIGNATURE_REFUSED` 归因失败）。

## `spec.dropHeaders`：端点也能删基线头 [#specdropheaders端点也能删基线头]

`spec.headers` 只能**覆盖**同名头，给不出「这个端点不该发某个基线头」。快手 H5 端点撞上了这个缺口：平台基线是照桌面 Chrome 攒的（`origin` / `sec-ch-ua*` / `sec-fetch-*`），而 H5 端点用移动 UA —— 拼在一起发出去的请求自我矛盾（UA 说 iPhone Safari，客户端提示说 Chrome 142 / Windows，而 Safari 根本不发 `sec-ch-ua`）。

`dropHeaders` 在所有 merge 之后执行，所以**同时出现在 `headers` 与 `dropHeaders` 里的头会被删掉** —— 端点自己要发的头别写进清单。快手那份清单是 `platforms/kuaishou/config.ts` 的 `KUAISHOU_H5_DROP_HEADERS`。

<Callout type="warn">
  如实记账：这条能力不是为了修某个风控。`photo/info` 的 `2001` 在剥到只剩 6 个头之后仍然复现 —— 改它的理由只是「发出去的请求不该自我矛盾」。
</Callout>

## 失败分支的三条路 [#失败分支的三条路]

拿到 `AxiosError` 后先问 `decideRetry`：

| 判定  | 有响应？ | 行为                                                                                    |
| --- | ---- | ------------------------------------------------------------------------------------- |
| 不重试 | 有    | 走正常返回路径，状态码原样带出（交给 judge 去判）                                                          |
| 不重试 | 无    | 发 `http:response` + `network:error`，&#x2A;*抛 `TransportError`**                       |
| 重试  | —    | 发 `http:response`（+ 非 2xx 时 `http:error`）+ `network:retry`，`await sleep(delayMs)` 后继续 |

非 `AxiosError` 的抛出物原样上抛，由 `execute` 的唯一 catch 归到 `internal`。

## 重试策略 [#重试策略]

策略是纯函数模块，可以单独读、单独测：

| 常量 / 函数                   | 值 / 行为                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| 可恢复 errno 白名单             | 9 个（`ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` 等）                                                         |
| `DEFAULT_MAX_RETRIES`     | 3                                                                                                       |
| `RETRY_DELAY_BASE_MS`     | 1000                                                                                                    |
| `backoffDelayMs(attempt)` | `base × 2^(attempt-1)` → 1s / 2s / 4s                                                                   |
| `isRetryableStatus`       | **429 与 ≥500**                                                                                          |
| `retryReasonCode`         | `ETIMEDOUT` → `TIMEOUT`；其他可恢复 errno → `NETWORK_ERROR`；429 → `RATE_LIMITED`；5xx → `PLATFORM_UNAVAILABLE` |

超时没有 transport 自己的实现，靠 axios 的 `timeout`。四个平台的 `config.ts` 给的默认值是 10000ms，调用方的 `request.timeout` 可以覆盖。超时归因看 errno：`ETIMEDOUT` / `ECONNABORTED` → `kind: 'timeout'` / `code: 'TIMEOUT'`。

代理、adapter 与其余 axios 字段原样透传 —— `RequestConfig` 就是 `Omit<AxiosRequestConfig, 'url' | 'method' | 'data'>`，非 headers 字段在构造配置时展开（实例级在前，单次调用在后）。

## 四个平台的签名机制 [#四个平台的签名机制]

签名器表与默认 judge 在 `client/runtime.ts` 的 `PLATFORM_RUNTIME` 里一次性装配，四个入口共用同一张表。这张表也是签名器名的事实源：每个平台用 `keyof` 从它推出名字联合（如抖音 `'a-bogus' | 'x-bogus'`），`defineXxxEndpoint` 拿来把端点 `sign` 的字符串分支收窄，写错名字编译期即报错 —— 与下面各签名器运行时查表（查不到抛 `未注册的签名器`）是同一份名字的两端。

### 抖音 [#抖音]

两个签名器，都先做前置校验再签，且**都以一步 secsdk 收尾**：

* **`a-bogus`**（19 个端点用：17 条声明 `douyinBogus(n)`，外加 `loginQrcode` 的 `[aBogus(), secsdk()]` 与 `mixAweme` 的 `sign: 'a-bogus'`）—— 先校验是绝对 URL，再用 `douyinSign.AB(...)` 签「tail 重排后、a\_bogus 之前」的那段 query，结果写进 query 的 `a_bogus`。
* **`x-bogus`**（1 个端点用，`commentReplies`）—— 先校验 pathname 至少 3 段且带 query，再写 query 的 `X-Bogus`。
* **`x-secsdk-web-signature`** —— 不是第三个签名器名，而是复合进上面两个的收尾一步。它与 AB / XB 有三点不同：**改写整条 URL**（签名算的是规范化后的 query，服务端也按收到的 query 校验，所以必须发它返回的那条 URL）、**只对 SDK 策略表里的 path 生效**（14 个 GET / 6 个 POST，表外原样返回）、**必须最后执行**（顺序是 a\_bogus / x\_bogus → 本签名，前者往 query 里加参数）。`uifid` 从 `ctx.cookie` 的 `UIFID` 取。

<Callout>
  **为什么不注册成第三个签名器名**：`sign` 是单槽位，而 secsdk 对策略表外是无操作 ——
  无条件套用是安全的。另起一个名字只会逼出 `'a-bogus+secsdk'` 这种复合命名。
  影响面上，`music/detail`（`musicInfo`）在策略表内，补上它之前实测 15/15 被
  `Blocked by ArgusSecurityPlugin Uifid Not Found` 拦死；作品详情、用户作品、
  喜欢列表也都在表内。`sign: false` 的端点不经过签名器，它们的 path 也都不在表里。
</Callout>

**签名读的 UA 是 `ctx.userAgent`**，它来自平台基线，且能被调用方的 `headers['user-agent']` 覆盖。这条链断掉的后果很难查：用空 UA 签名，服务端必然拒绝。

另有一个 Referer 注入 helper（`douyin/referer.ts` 的 `withDouyinReferer`），7 个端点的 `build` 调它；调用方已经传了 `referer`（大小写不敏感）时不注入。

### B站 [#b站]

`wbi` 与 `qtparam` 两个签名器共享一个 `WbiSigner`：

* **`wbi`*&#x2A; —— 需要先取 nav 接口拿 key。取 nav 走的是 &#x2A;*`ctx.send(..., 'prepare')`**（不是直连 axios），带 30 分钟 TTL 缓存。签名用 `mixinKeyEncTab` 重排 + md5，产出 `&wts=..&w_rid=..`。
* **`qtparam`** —— cookie 为空时只加 `&platform=html5`；否则复用同一个 nav 结果读 `vipStatus`，VIP 加 `&fnval=4048&fourk=1`，非 VIP 加 `&qn=64&fnval=16`。签名基于**未加 fnval 的原始 URL**。

<Callout type="warn">
  **wbi key 缓存是进程级共享的，不是每实例一份。** `PLATFORM_RUNTIME` 是模块级 `const`，
  `createBilibiliSigners()` 在模块求值时只调用一次，所有 client 实例、静态 fetcher、HTTP 路由
  拿到的是同一个 `WbiSigner`；`sign/steps.ts` 的模块级 `sharedWbi` 也是它，所以端点声明的
  `wbi()` 与 request 层的 `sign: 'wbi'` 共用同一份 key 缓存。这也意味着：两个用不同 cookie 的
  实例会共用同一份 wbi key。
</Callout>

### 小红书 [#小红书]

三个签名器（`xhs-post` / `xhs-get` / `xhs-get-trace`）统一注入 `x-s` / `x-s-common` / `x-t`，带 trace 的那个再加 `x-b3-traceid`。签名路径取 `spec.signPath`，缺省取 URL 的 pathname。

`a1` 从 cookie 里**按名精确匹配**取（不是子串匹配 —— 子串匹配曾经是一个真实缺陷）。算法委托同仓内联实现（`sign/xhshow/`）的模块级单例。

`prepare` 用得最多的地方也在这里：小红书**全部 13 个端点**都在 cookie 缺 `a1` 时先打三个请求换游客会话（cookie + SSK）—— 降级由 `defineXiaohongshuEndpoint` 横切注入，端点声明里不逐个写。快手两条 H5 端点也用 `prepare`（did 是纯本地生成的、不出网），另有一条 PC 端点用 `kuaishouPcPrepare`。

### 快手 [#快手]

一个签名器（`hxfalcon`），`live_api`（`/rest/k/*`）与 H5（`/rest/wd/*`）共用 —— 快手两套命名空间的签名算法是同一套，区别只在喂什么料。

签名的三份料全部从 spec 上取：

| 料     | 来源              | 说明                                                                 |
| ----- | --------------- | ------------------------------------------------------------------ |
| query | `spec.url` 解析   | 必须含 `caver`（它参与 sign input）。缺了就按签名器自己的 `catVersion` 补，补的值与最终发出的一致  |
| 签名路径  | `spec.signPath` | 与 `url` 的 pathname 不同（`userProfile` 的 12 个分片各有各的 `/rest/k/*` 规范路径） |
| 请求体   | `spec.body`     | POST 端点必须参与签名                                                      |

产物写回 URL（`__NS_hxfalcon` + `caver`）与请求头（`kww`）。`kww` 有匿名兜底，**签名从不读 cookie** —— cookie 只影响 `kww` 走登录分支还是匿名分支。

<Callout type="info">
  这里曾经是整个 transport 层最大的断链，两处**同时**漏在 `PLATFORM_RUNTIME.kuaishou`
  上：`signers` 没装（`KuaishouSigner` 写好了却零调用点，于是每个快手请求都不带签名，
  只能拿 cookie 当替代凭证）、`judge` 没装（`kuaishouJudge` 同样零调用点，业务失败全被
  兜底判成成功）。两者都不报编译错误、都不挂测试。现在 `test/client/runtime.test.ts`
  按平台遍历断言「signers 与 judge 都得有，且表里每项都是函数」，把这一类静默漏项钉住。
</Callout>

<Callout type="warn">
  **签名接上了，但 `photo/info` 现在不是快手单个作品的主通道。** 2026-09-05 实测：
  那条接口对 amagi 与对照项目一视同仁地回 `2001 antispam need captcha`，七个变量
  （签名 / 请求头 / did / cookie / 分享页预热 / 真 share 参数 / 数字 photoId）逐个排除
  后都是 2001；而快手自己的 H5 分享页 SSR 用的是**免签的** `ugH5App/photo/simple/info`。
  所以 `kuaishou.videoWork`（`/fetch_one_work`）走的是那条免签接口 —— 它&#x2A;*不声明 `sign`**，
  签名的完整版在 `kuaishou.videoWorkFull`（`/fetch_one_work_full`）。
  验签名到底有没有接上，要拿 `videoWorkFull` 或任一 `live_api` 端点验，别拿 `videoWork`。
</Callout>

### 风控挑战：`PLATFORM_RUNTIME.<平台>.challenge` [#风控挑战platform_runtime平台challenge]

`signers` / `judge` 之外的**可选**第三项，四个平台里装了三个：

| 平台  | 提取器                       | 信号在哪                                                                                                                                                                                          |
| --- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 快手  | `parseKuaishouCaptcha`    | 响应体                                                                                                                                                                                           |
| 小红书 | `parseXiaohongshuCaptcha` | **只在响应头**（`verifyuuid` / `verifytype`，461 = antiSpider）                                                                                                                                       |
| 抖音  | `parseDouyinCaptcha`      | **两条通道，响应头优先**：响应头（`bdturing-verify` / `x-vc-bdturing-parameters`，只认 2xx，body 常为空串）拼不出地址时**兜底读响应体**（滑块中间页 HTML 里的 `verify_data`，**刻意不设状态码闸**）；`jsSdkUrl` / `session` / `verifyData` 只有响应体那条会填 |
| B站  | 无                         | —                                                                                                                                                                                             |

`ChallengeExtractor` 的签名是 `(raw, http?)` 而不是 `(raw)`，但两个平台的理由并不相同：小红书的信号**一个字都不在 body 里**（提取器第一个参数就写作 `_raw`，整个函数用不上它）；抖音则是**响应头那条通道优先**，而且要 `http.status` 把那条通道的闸设在 2xx 上 —— 它的 body 里另有一条兜底通道。快手两样都不要，只看 body，不接第二参数也照样装得上。

### 自动解算：`PLATFORM_RUNTIME.<平台>.solveChallenge` [#自动解算platform_runtime平台solvechallenge]

与提取器互补的**可选第六项**，目前只有抖音装了。分界线是**有没有人机判定**：

* **纯工作量证明在管线内解掉并重放。** 抖音 WAF 的 `_wafchallengeid`（sha256 碰撞数）与 VMP 的 `__ac_signature` 由 solver 纯算，返回合并好的完整 cookie 串；`execute` 更新 `ctx.cookie` 并**立即重放**同一请求，`trace.reason` 记 `challenge`（不退避、与业务重试分开）。
* **真人滑块永远返回 `undefined`。** 这类挑战走 `error.challenge` 交给真人；自动重试滑块毫无意义，还会放大风控。

重放有上限（`SOLVE_ROUNDS = 4`）。一次调用里解算成功后 `execute` 会**收口**：不再因为重放结果仍被判可重试而继续退避重试。解不出就把失败信封原样交出去，不吞错。抖音解出的 `__ac_nonce` 还会按 cookie 身份缓存 45 秒，下次裸打页面时直接复用（只存 nonce，签名按当刻时钟重算）。

`runtime/execute.ts` 在 judge 判出 `kind: 'risk'` 时调用**提取器**，结果进失败信封的
`error.challenge`（`{ url, jsSdkUrl?, session?, bizName?, type?, configUrl?, result }`）。
`url` 一律是人能直接打开的验证页：H5 给的是配置接口，会被拼成 `iframe/index.html?…&configUrl=…`
（不用 `mobile/h5/redirect/index.html`，那个跳转壳读的是原字段名 `url` 而不是 `configUrl`，滑块图出不来）。

<Callout type="warn">
  **抖音的地址是照验证中心 SDK 的拼法拼的，头里没有现成的。** 验证头里只有验证参数，没有 URL；
  页面上的渲染层把它们平铺进 query、挂 iframe 到
  `https://rmc.bytedance.com/verifycenter/captcha/v2`，`parseDouyinCaptcha` 照这个拼法交出顶层
  可开的地址。URL 恰好 4 个 query 键（`aid` / `fp` / `host` / `verify_data`）；参数缺 `fp` 或
  `aid` 时不给地址；响应体那条通道（`verify_center_decision_conf`）只有决策信息，也不给。
</Callout>

<Callout type="warn">
  **上一条原先还带着一组「实测形状」，出处记错了，2026-10-11 订正。** 原文是「2026-10-08 实测
  （游客身份，`search type=user` 必触发）」—— **端点与触发条件都记错了**，按仓库里的实测记录订正如下。

  **响应头通道有线上命中，但不在 `search` 上。** 仓库里唯一两条实测记录是 2026-09-26 的游客
  `aweme/favorite/`（`subtype: slide`）与 `comment/list/reply/`（登录态 / 游客，文字点选），
  形状都是 HTTP 200 + body 0 字节 + 验证头，`code` 是**数字** `10000`。而且**触发条件不是
  游客身份**，是 `a_bogus` 的 `DETECT_FLAGS` 当时错写成登录页的 14 —— 同一条 query 只改这一个
  字节，14 稳定吃验证、8 稳定正常（对照表在 `sign/a_bogus.ts` 的 `DETECT_FLAGS` 上）。那个字节
  在 2026-10-08 04:05 就已订正回 8（`76db04a5`，原作 2026-09-29），比上面那句「实测」早 11 小时，
  所以这两条端点在写下那句话时也已经不触发了。

  **`verify_data` 恰好 18 个键、`subtype` 为 `slide`、`aid` 回 `0`、`code` 回字符串 `"10000"`
  这组数字来自响应体通道的滑块中间页 fixture**（`slider_captcha.html`，每一个值都逐一对得上），
  不是响应头通道的观测：两条通道的 `code` 类型本来就不同 —— 头上是数字、中间页是字符串
  （`captcha.ts` 里记着，提取器的 `textOf` 两种都吃）。而那份 fixture 取自移植参考实现所带的
  抓包，**amagi 自己没有线上命中记录**，与下面「撞不到真挑战」一条一致。原文「平台回显的 `fp`
  与 amagi 发出的一致」同样靠不住：第三方抓包里的 `fp` 只是**合形状**
  （`verify_` 加 36 进制时间戳加尾巴），不可能与 amagi 发出的那个相同。

  **`search` 至今没有验证挑战的线上命中记录。** 2026-10-10 的游客实测里 `search` 回的是
  「登录状态已失效」（`auth` / `COOKIE_EXPIRED`），不是验证挑战。这条判定本身有歧义，别反向误读：
  滑块中间页两个数组都没有，在 `searchJudge` 把验证页那条排到 `user_list` / `data` 之前以前也会
  落进 `COOKIE_EXPIRED` —— 所以那次「登录状态已失效」**既不能证明撞到过验证页、也不能证明没撞到**，
  只能说响应头上没有验证头。本次订正**没有发真网复测**，纯靠仓库记录与提交历史判定。
</Callout>

**验证页不靠 cookie 认人，所以在哪儿打开都行。** 2026-10-08 在一个零 cookie 的全新浏览器上下文里，
`captcha/get` 回 HTTP 200 加一个真实滑块（真图、`mode: slide`），请求**不带 `Cookie` 头** —— 响应的
`access-control-allow-origin: *` 配 `access-control-allow-credentials: true`，这组合浏览器本就不许
带凭据。身份完全走 URL 里的 `detail` 票据加 `fp`。这就是 `parseDouyinCaptcha` 只交 4 个参数够用的
依据：换台机器、换个浏览器、没登录，照样渲染出那个滑块。

<Callout type="warn">
  如实记账：&#x2A;*「过完验证后同 cookie 重发会放行」至今没实测确认。** SDK 过完验证只是原样重发原请求、
  不加任何新头（源码确认），渲染层会把 `fp` 写回 `s_v_web_id` cookie，据此推断放行按 `fp` 关联、
  不需要回填票据 —— 但三次人工滑动全部停在 `captcha/verify`，没走到重发那一步。服务端两种形状都是
  HTTP 200：`{"code":500,"data":{"msg":"NotFoundChallengeId"}}` 与 `{"code":502,"message":"…[5014]"}`
  （页面上的 `[5014][502]` 是 `[errCode][body.code]` 拼的，不是 HTTP 状态）。后者打的是 4 秒前才
  签发的新挑战，所以不只是过期。`aid` 已排除（改成页面里的值，报错不变），所以 `captcha.ts` 不动。
  嫌疑剩在 `captcha/verify` 的环境签名：SDK 声明 `bdms.js` 要签 `/captcha/verify` 与 `/captcha/get`
  两条路径，而观测环境里 `window.bdms` 是 `undefined`、query 还带 `webdriver=true`，同一个
  `[5014][502]` 在**完全没拖滑块**时就会出现 —— 观测环境不是普通浏览器的干净替身，这个错不能直接
  归因到那一次滑动。
</Callout>

**2026-10-11 复查，上面那条仍然成立，另外补三件实测。** 这次走的是**响应体通道**
（滑块中间页 fixture `slider_captcha.html`），过一遍 `parseDouyinCaptcha` 拿到 `RiskChallenge`
再在真浏览器里打开：

1. **验证页真的能开，而且渲染出真滑块。** 页面标题「验证码」，文案「请完成下列验证后继续 /
   按住左边按钮拖动完成上方拼图」，一个 `canvas` 加两张 `p9-catpcha.byteimg.com` 的图
   （拼图底图与缺口块），底下是 `刷新` / `反馈` 和回显的 `log_id`。真正的渲染器是
   `rc-verifycenter/rmc-captcha/1.0.0.922/captcha.js` 配 `index.wasm`。全程只看、没拖。
2. **`aid` 为 0 不妨碍取题 —— 旧的推断被否掉了。** 托管页带着 `aid=0` 打
   `verify.zijieapi.com/captcha/get`，回 200 带题，控制台除了 `favicon.ico` 的 404 没有任何报错。
   所以源码里曾写的「托管验证页靠 `aid` 取题，0 大概取不出来」是错的，已订正。
   这与上面「身份完全走 `detail` 票据加 `fp`」是一致的。顺带一条：fixture 那张票据签发于
   2026-10-05，六天后照样渲染得出题。
3. **`jsSdkUrl` 是活的，但它只是个 loader。** 实测 HTTP 200、17167 字节、
   `application/javascript`。内容是 UMD 包，挂出全局 `TTGCaptcha`，`init()` 负责动态拉真正的
   JS SDK（失败回 `{type:'loadJSSDK'}`），`render(o)` 则是
   `o.captchaOptions.challenge_code ? renderCaptcha({...initOptions, ...o}) : autoRender(o)`。
   中间页只传 `{ verify_data }`、没有 `challenge_code`，所以走的是 `autoRender` 那一支。

<Callout type="warn">
  **自建验证页还缺一个常量，它不在 `verify_data` 里。** 中间页真正的宿主 `aid` 写在
  `TTGCaptcha.init()` 的 `commonOptions` 上 —— fixture 里是 `339757`（另有 `iid` / `did`
  两个 `'0'`），而 `verify_data.aid` 是 `0`。`captchaOptions` 那半边也一样来自页面而非平台响应：
  `{ ele: 'root', hideCloseBtn: true, showMode: 'mask', successCb }`。
  这些是中间页的**常量**、不随会话变，所以 `RiskChallenge` 不收它们（提取一个常量只会把它
  伪装成实测值），改为记在这里：想照原样自建一张，`verifyData` + `jsSdkUrl` 之外把上面这组
  写死即可。真正随会话变的东西（`detail` 票据、`fp`）都已经在 `verifyData` 里。
</Callout>

**还差哪一环，以及为什么这次也没补上。** 「真人过完滑块 → 同 cookie 重发 → 服务端放行」这个闭环
仍然没有端到端实测，卡在两个结构性障碍上，都不是写代码能绕的：

* **撞不到真挑战。** 零凭证的游客流量实测 240 发跨 5 条端点（2026-10-10，`suggestWords` /
  `comments` / `emojiList` / `userProfile` / `userVideoList`，混参数、无间隔），一次没触发验证挑战，
  响应头里 `x-vc-bdturing-parameters` / `bdturing-verify` 从不出现。**作用域照实说**：这 5 条里
  **不含** `search`，也不含 2026-09-26 唯一撞出过验证头的 `aweme/favorite/` 与 `comment/list/reply/`
  —— 但那次撞出来是 `DETECT_FLAGS` 错成 14 造成的（见上），字节订正回 8 之后它们也不触发了，
  所以「游客量级下撞不到」这个结论不因端点集不全而松动。要稳定撞上得有登录态 cookie，而我们没有。
  所以只能拿 fixture 的挑战做复现。

  **付费内容也不额外触发（2026-10-11 实测，用户提供两条真实付费链接）。** 付费单视频与付费会员
  视频合集的分享短链，跟完整条重定向链（`v.douyin.com` → `www.iesdouyin.com/share/video/<id>`
  → `www.douyin.com/video/<id>`）落到内容页时弹的是 **VMP 挑战**（72914 字节、`detect=vmp`、
  Set-Cookie 两条同名 `__ac_nonce`），也就是零 cookie 打任何页面地址都会弹的那一种 —— 管线内
  能自动解，不是滑块。拿两条作品的 `aweme_id` 与作者 `sec_uid` 打 `videoWork` / `userFavoriteList`
  （= 2026-09-26 唯一撞出过滑块的 `aweme/favorite/`）/ `userVideoList` 共 6 发，**全部
  `attempts: 1` 一次成功**，验证头一次没出现。这反过来印证了上面那条：那次滑块确实是坏字节
  造成的，不是端点或内容类型的属性。**付费内容在读取层面与普通内容同权**；真正的风控大概在
  「购买 / 权限校验」那个动作上，而那是登录态才能走的路。
* **过滑块必须真人拖，而自动化浏览器过不了。** CDP 控制的实例 `navigator.webdriver` 恒为 `true`，
  那是启动参数级的硬信号；上面那次 `[5014][502]` 在完全没拖滑块时就会出现，正是这个原因。
  amagi 的红线也在这里：**滑块不做识别、不做轨迹模拟、不自动解、不自动重放**，所以这一步只能交给真人；纯工作量证明（WAF / VMP）是另一条路，由 `solveChallenge` 在管线内解掉并重放。

**所以调用方要自己做三件事**：把 `error.challenge.url` 交给真人打开（或拿 `verifyData` +
`jsSdkUrl` 自建一张）；等真人过完；用**同一份 cookie** 重发原请求。第三步的放行行为按
`fp` 关联是**推断**（依据见上面两条：SDK 不加新头、`successCb` 只 reload），不是实测结论。

第一步有现成的：`renderVerifyPage(error.challenge, { platform })` 返回一张自包含 HTML，调用方
自己起个路由返回即可。三个平台都能内嵌 `url` 托管；抖音带齐 `jsSdkUrl` + `verifyData` 时默认
在页内渲染官方滑块，上面那组宿主常量已经写死在里面。页面源码是 `packages/core/verify-page/`
（React），由 `pnpm gen:verify-page` 打成单文件烘焙进 `src/verify/page.generated.ts`。

滑块人能过，但**票据不是哪条接口都认**：快手 H5 前端只给 `ugH5App/photo/simple/info`、
`user/profile`、`feed/profile`、`live/byUser` 这 4 条路径回填 `captchaToken`。
`videoWorkFull`（`photo/info`）虽然有 `captchaToken` 参数，2026-09-27 实测带真票据重发不放行，
反而转成 `result=2`。

关键一点：**它不受 `debug` 管**。以前地址只能从 `error.raw` 里自己捞，而 `raw` 只有
`createClient({ debug: true })` 才有、`createXxxRoutes` 又不接 `debug` —— 于是最需要
滑块地址的入口（HTTP 服务）恰好是唯一结构上产不出它的入口。现在 client / HTTP 路由 /
静态 fetcher 三个入口都拿得到。

<Callout type="info">
  **只中转不绕过。** amagi 把验证页地址原样交给调用方，不引入任何识别、轨迹模拟或
  自动过验证的代码。取不出可信地址时返回 `undefined`，宁可不给也不把来路不明的 URL
  当验证页交出去。
</Callout>

### 其余三个平台的 judge [#其余三个平台的-judge]

| 平台  | 判定要点                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 抖音  | **最先**看 2xx 响应上的验证头 `bdturing-verify` / `x-vc-bdturing-parameters` → `risk` / `CAPTCHA_REQUIRED`（弹滑块 / 文字验证时 HTTP 是 200、body 常为空串，无感采集 `nocaptcha_collect` 除外），验证页地址由 `parseDouyinCaptcha` 从同一份头拼出；body 里的 `verify_center_decision_conf` 同样判 `CAPTCHA_REQUIRED`；`status_code` 缺失视为成功，非 0 一律 `unknown` / `PLATFORM_ERROR`（**刻意不按码分类** —— 抖音没有公开业务码表，同一个码在不同接口含义不同，真实码在 `error.platform.code`）；`filter_detail.filter_reason` → `forbidden` / `PRIVATE`；空响应体 → `auth` / `EMPTY_RESPONSE`；Argus 拦截文本 → `risk` / `ANTIBOT_PAGE`（可重试），其中点名签名的（`uifid not found` 等四种）→ `risk` / `SIGNATURE_REFUSED`（**不可**重试 —— 是 amagi 侧签名/访客 id 的问题，不是账号被风控，换 cookie 无用；cookie 审计会先尝试自动铸造访客 id，走到这个码说明铸造也没能救回来） |
| B站  | `code` 缺失或 0 成功；`-412` → `risk` / `RISK_CONTROL`；`-101` → `auth`；`-404` → `not_found`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 小红书 | 响应含 `<html>` → `risk` / `ANTIBOT_PAGE`，且标 `retryable`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

端点自带的 `judge` 优先于平台默认。

## cookie 的完整穿线 [#cookie-的完整穿线]

<Mermaid
  chart="flowchart LR
  O[&#x22;ClientOptions.cookies.&lt;平台&gt;&#x22;]
  M[&#x22;makeClientCtx<br/>ctx.cookie&#x22;]
  B[&#x22;平台基线<br/>headers.delete('cookie')&#x22;]
  R[&#x22;resolveBoundRequest<br/>单次 headers 里的 cookie 覆盖&#x22;]
  P[&#x22;prepare（可选）<br/>换游客 cookie&#x22;]
  A[&#x22;attachCookie<br/>写 Cookie 头&#x22;]
  O --> M --> R --> P --> A
  M -.->|刻意不放 cookie| B"
/>

六个要点：

1. **来源**：实例是 `ClientOptions.cookies.<平台>`；静态形态是方法第二参；bound 形态是工厂第一参。
2. **基线里刻意不放 cookie**：`makeClientCtx` 拿到平台 config 后立刻 `headers.delete('cookie')`。否则单次调用的 cookie 覆盖会被实例头里的旧值遮蔽。
3. **单次覆盖**：从合并后的 headers 里大小写不敏感地取 `cookie`，取到就替换本次的 `ctx.cookie`。
4. **注入只在一处**：`execute` 的 `attachCookie`，send 之前。
5. **执行期可换**：`prepare` 返回的 `cookie` 会覆盖 ctx，换完的值经 `attachCookie` 生效。
6. **响应侧不回写**：`RawResponse.setCookie` 保留原始数组，但**不会**被写回 `ctx.cookie`。主管线里没有 cookie 自动刷新或轮转 —— 唯一的例外是抖音 passport 自带的 cookie jar 与小红书游客 cookie 的一次性生成。

cookie 解析全仓只有一份实现（`contracts/cookie.ts`）：大小写敏感、以第一个 `=` 分割、不做 URL 解码。

## 两个写了但没人读的字段 [#两个写了但没人读的字段]

`RequestSpec` 上有两个字段，契约注释描述了用途，但通路不存在：

| 字段      | 注释说               | 实际                                                                 |
| ------- | ----------------- | ------------------------------------------------------------------ |
| `tag`   | 会进 trace          | trace 的类型里没有 `tag`。唯一写入点是抖音弹幕端点，无读取点                               |
| `extra` | 透传给 sign / decode | `decode(raw, res)` 的签名拿不到 spec。唯一写入点是 B站 `qtparam` 写的 `isvip`，无读取点 |

写代码时不要依赖这两个字段传值。

## v6 的传输入口仍在 [#v6-的传输入口仍在]

`transport/legacy.ts` 的 `fetchData` / `fetchResponse` / `getHeadersAndData` 保持 v6 语义并标了 `@deprecated`：`validateStatus: () => true`、只认大写 `User-Agent` 的 UA 清理、事件写 v6 的全局单例。

**抖音登录会话与 4 个 passport 方法仍走这条路** —— 详见[翻页与会话](/docs/v7/dev/internals/session)。


# B站 (https://ikenxuan.github.io/amagi/docs/v7/dev/sign-verify/bilibili)

> w_rid 重算比对与 av/bv 互转 —— 两个完全可验的纯函数签名



# B站签名验证 [#b站签名验证]

B站的签名没有抖音那些常量陷阱：`w_rid` 是一次带混淆密钥的 MD5，av ↔ bv 是纯 BigInt 位移 —— 两个**完全可验**的纯函数。验证器跑的就是 `@ikenxuan/amagi/signing` 那份代码。

<SignVerifier platform="bilibili" />

## wbi（`w_rid` + `wts`） [#wbiw_rid--wts]

算法本身简单：

1. 从 `/nav` 回包的 `wbi_img.img_url` / `sub_url` 取两个 key（URL 末尾的文件名，去扩展名）；
2. 按 64 位混淆表 `mixinKeyEncTab` 把 `img_key + sub_key` 重排、截前 32 位，得到 mixin key；
3. 参数按 key 排序、value 滤掉 `!'()*`、`wts` 一起参与排序，拼成规范化 query；
4. `w_rid = md5(规范化 query + mixin key)`。

所以验证只需&#x2A;*同一组 keys + 同一个 `wts`** 重算一遍。两个容易翻车的点：

<Callout type="warn" title="keys 必须取自同一次 /nav">
  keys 随 session 滚动。拿今天缓存里的 keys 去验昨天抓的 URL，`w_rid` 必然对不上 ——
  这不代表签名错了，代表 inputs 变了。验证器没法替你判断 keys 的新鲜度。
</Callout>

<Callout type="warn" title="参与签名的是规范化后的 query">
  value 里的 `!'()*` 会先被滤掉再 `encodeURIComponent`；`wts` 本身参与排序。
  所以「我发的 URL 长这样」和「参与哈希的 query 长那样」可以不同 —— 验证器把规范化
  query 折叠展示了出来，对不上的时候先看它。
</Callout>

amagi 侧的实现（`WbiSigner`）把 keys 缓存在实例上（TTL 30 分钟），`sign: 'wbi'` 与 `sign: 'qtparam'` 共用同一次 `/nav`。签名走 transport（`reason: 'prepare'` 进 trace），这与验证无关，但意味着 `/nav` 请求本身在 trace 里可见。

## qtparam：不做离线验证的原因 [#qtparam不做离线验证的原因]

视频流的 `qtparam` 前置会按登录态打 `/nav` 取 `vipStatus`，再决定追加 `fnval=4048&fourk=1`（VIP）还是 `qn=64&fnval=16`（非 VIP），最后叠一次 wbi 签名。它不是一个独立的签名算法，而是**登录态分支 + wbi**——离线验证它就得连 `/nav` 一起验，那不再是纯函数的事。要看它对不对，直接发请求看回的清晰度档位。

## av ↔ bv [#av--bv]

纯 BigInt 位移与 58 进制查表，双向互逆。验证器做双向转换加往返自检 —— 往返对不上只有一个可能：号码抄错了。

```ts twoslash
import { av2bv, bv2av } from '@ikenxuan/amagi/signing'

console.log(av2bv(2)) // 'BV1xx411c7mD'
console.log(bv2av('BV1GJ411x7h7')) // 80433022
```

## 下一步 [#下一步]

<DocsCategory group="签名验证" />


# 抖音 (https://ikenxuan.github.io/amagi/docs/v7/dev/sign-verify/douyin)

> a_bogus / X-Bogus / secsdk / 访客令牌 —— 四个验证器，以及各自的常量表与边界



# 抖音签名验证 [#抖音签名验证]

下面这个验证器跑的就是 `@ikenxuan/amagi/signing` **本身** —— 与 oracle 测试、与线上签名同一份代码。它有意的没有自带一份解码逻辑：这个页面存在的意义是证明**实现**还是对的，如果页面自己实现一遍，它证明的只是页面自己。

<SignVerifier platform="douyin" />

四个标签页对应抖音主站的四层签名，每一层「能验到什么」在表格里都标得直白：

| 签名                                | 出现位置              | 算法                  | 验证方式          |
| --------------------------------- | ----------------- | ------------------- | ------------- |
| `a_bogus`                         | 几乎所有 web 数据接口     | SM3 三链 + RC4，含内部校验和 | 拆开验：结构、盐值、摘要链 |
| `X-Bogus`                         | 老接口 / 部分兜底链路      | MD5 三链 + RC4        | 拆开验：常量指纹、时钟   |
| `x-secsdk-web-signature`          | 点赞、收藏等敏感操作        | 确定性 MD5             | 重算比对          |
| `verify_fp` / `msToken` / `ttwid` | cookie 与 query 附参 | 随机骨架 / 平台签发         | 骨架校验；真伪辨不了    |

## a\_bogus：盐值判定的故事 [#a_bogus盐值判定的故事]

`a_bogus` 的签名算法里藏着盐值等常量，它们会随抖音更新 `bdms.js` 而变。`packages/core` 里数据接口那份 `a_bogus` 曾经用盐值 `cus`，而真实值是 `dhzx` —— 它来自 2024-08 一份公开流传的片段，此后再没被算法层面的改动碰过。同一个仓库里 2026-09 新写的 passport 版本用的却是 `dhzx`：&#x2A;*正确的值一直就在旁边，但没有任何测试能把这件事暴露出来。**

它是被这样发现的：拿一份真实浏览器产出的 `a_bogus`，把两个候选盐值分别代进摘要，看哪个能重现签名里封住的三个字节。

```
query       observed=(19, 103, 137)   dhzx_predicted=(19, 103, 137)   MATCH
query       observed=(19, 103, 137)   cus_predicted=(105, 123, 88)    MISMATCH
```

这就是验证器「盐值」那一行做的事 —— 不需要网络、不需要 cookie、不依赖抖音是否接受了你的请求。

### 两个把验证工具自己坑到的假设 [#两个把验证工具自己坑到的假设]

这两个都是拿线上真实捕获验出来的，而且都不在算法里，在验证侧的假设里：

<Callout type="warn" title="一、UA 链的密钥来自签名自己报的 detect_flags">
  UA 链的 RC4 密钥是三字节，其中一字节是 `detect_flags`。这个值**随页面（bdms bundle）变**——
  提交的 fixture 里是 `14`，主站页面自己签的是 `8`，一次线上捕获里是 `4`。拿模块常量去校验
  别的值，这条链必然报「对不上」，而签名本身完全正确。所以 `decodeABogus` 现在按**签名里解出的**环境值重算。
  上游那份 Python 实现同样写死了常量，这是移植时补的。
</Callout>

<Callout type="warn" title="二、签名覆盖了哪些参数，随管线而异">
  线上捕获里 `uifid` 在 `a_bogus` **之前**，因而被签名覆盖；而 amagi 的管线是
  `webid → a_bogus → secsdk`，`uifid` 由 secsdk 在**之后**补上、没被覆盖。
  同一个参数名，两边结论相反——`msToken` / `verifyFp` / `fp` 同理。
  所以别猜：`recoverSignedQuery()` 把 2⁴ 种组合全试一遍，报出命中的那一种，
  并把**它保留了哪些参数**一并告诉你。
</Callout>

### 常量表 [#常量表]

| 常量                | 值                     | 怎么被确认的                                                                                                                                                         |
| ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SALT`            | `dhzx`                | 真实捕获反推三条摘要链，全部命中；`cus` 两条对不上                                                                                                                                   |
| `HEADER_MAGIC`    | `[3, 82]`             | 从真实签名解出，且**不是解码器的输入**                                                                                                                                          |
| `SDK_VERSION`     | `[1, 0, 1, 0]`        | 同上                                                                                                                                                             |
| `PAGE_ID` / `AID` | `6241` / `6383`       | 同上；passport 登录页的 `page_id` 是另一个值 `7571`                                                                                                                        |
| `ENV_FLAGS`       | `1`                   | 真实捕获实测                                                                                                                                                         |
| `DETECT_FLAGS`    | `8`（**随页面 bundle 变**） | 主站 www 的 bdms bundle 是 8，登录页是 14（passport 显式传 14），还见过 4。fixture 里是 14。**这个值会影响风控**：数据接口用 14 时，评论回复稳定吃文字验证、游客的喜欢列表稳定吃滑块，改成 8 后全部正常（2026-09-26 实测）。校验时要读签名自己报的那个 |
| `TRIPWIRE_LOCKED` | `3`                   | 同上                                                                                                                                                             |
| `CALL_BUCKET`     | `6`                   | 同上                                                                                                                                                             |
| `L38`（`NR_FLAGS`） | `0x21` = `33`         | 真实捕获实测为 33；passport 那份曾写 129，是错的                                                                                                                               |
| `PAYLOAD_KEY`     | `0xD3`                | 单字节，且密码**不是**教科书 RC4（有个测试专门钉住这件事）                                                                                                                              |

<Callout type="info" title="刻意不检查 a_bogus 的长度">
  签名长度跟着屏幕几何串走，两个都对但屏幕不同的浏览器就是会不一样。
  检查长度会把正确的实现判成错的。X-Bogus 恰好相反：它恒为 28 字符，长度就是指纹的一部分。
</Callout>

### oracle 测试与刷新 [#oracle-测试与刷新]

`packages/core/test/platforms/douyin/abogus-oracle.test.ts` 把「拿真实捕获反推」固化成断言。它读一份**不随被测代码变化**的 fixture（`packages/core/test/fixtures/douyin/abogus_browser.json`，bdms `1.0.1.19-fix.01`，2026-09-09），做三件事：结构检查、解出解码器没有作为输入拿到的那些常量、用浏览器自己的输入重签后五十个标量全等。

<Callout type="warn" title="fixture 的局限，别夸大它">
  三个样本**共用同一组输入**（同一条 query、同一个 UA、同一块屏幕、相邻毫秒），
  只有噪声不同。换 query、换屏幕、换 SDK 版本的覆盖只能靠重新捕获：在真实页面里签一次，
  把输入和输出一起记下来 —— 少任何一项，oracle 测试都跑不起来。
  `a_bogus` 不携带任何会话值，所以 fixture 里不该、也不会出现凭据。
</Callout>

<Callout type="info" title="换 fixture 之后先跑什么">
  先跑 `npx vitest run packages/core/test/platforms/douyin/abogus-oracle.test.ts`。
  如果摘要链开始报「对不上」，先怀疑常量过期（这正是它要抓的），
  再怀疑 fixture 记错了输入。结构检查会先告诉你是不是后者。
</Callout>

## X-Bogus：老签名的指纹 [#x-bogus老签名的指纹]

X-Bogus 是站点上一代签名，载荷里封着三条 **MD5** 摘要链（各留 2 个字节，16 位证据）、秒级时间戳、和一个 canvas 常量。它比 `a_bogus` 弱 —— 证据位少、也没有 `a_bogus` 那个覆盖五十个标量的校验和 —— 但常量指纹依然够用：

* 载荷前四格恒为 `64, 0, 1, 12`（第三格在站点源码里写的是 `1/256`，编码前被截断成 `0` —— 不能顺手改写成 `0`，截断的时机是算法的一部分）；
* empty 摘要链的两个字节是常量，出现在每一份 X-Bogus 里；
* canvas 常量 `536919696` 占四格；
* 最后一个字节是前 18 格的逐格异或。

时间戳是 X-Bogus 唯一能**原样读回**的载荷 —— 验证器会把它解出来给你看。移植史上有两个坑都会产出「看着像模像样」的错签名（字节顺序还原、十六进制半字节补零），详见 `packages/core/src/platforms/douyin/sign/x_bogus.ts` 的文件头。

## secsdk：确定性 MD5，重算即比对 [#secsdk确定性-md5重算即比对]

`x-secsdk-web-signature` 是最简单的一层：明文 `{uifid}_{ts}_{盐}_{规范化 query + &timestamp}` 的 MD5，盐写死在 secsdk VM 常量池里，与账号会话无关。确定性算法没有「拆开」可言 —— 验证就是**重算**：

* query 按管线规则规范化（顺序不排序、value 重编码、key 只解码、裸参数补 `k=`）；
* `uifid` 参与明文：query 里没有时，SDK 会从 `UIFID` cookie 取值追加（注意别被 `UIFID_TEMP` 骗到）；
* 签名算的是**规范化后**的 query —— 所以必须发送管线返回的 URL，不能拿原始 URL 直接发。

## tokens：哪些能验，哪些是「说了就是答案」 [#tokens哪些能验哪些是说了就是答案]

抖音的访客令牌一族，验证强度差别极大：

* **`verify_fp` / `s_v_web_id`**：`verify_<36 进制毫秒>_<36 位 UUID v4 骨架>`。分隔符、版本位、变体位是骨架指纹，时钟能原样读回 —— 「这个值什么时候生成的」是可判定的。真假辨不了：本地生成的假值形状目标就是与真值一致。
* **`msToken`**：只能验形状（长度 120/128、字符表）。形状一致的假 token 本地就能生成，而平台对一部分端点认它、另一部分不认 —— 这是行为问题，不是形状问题。
* **`ttwid`**：字节跳动签发的不透明令牌，签名算法只负责携带。对这类值，说出「底下没有明文」就是答案。

## API [#api]

签名与验证都在 `@ikenxuan/amagi/signing` 这个入口下，整条依赖链不引用任何 Node 内置模块，浏览器、Worker、Deno 里都能直接跑，全程不碰网络。

```ts twoslash
declare const signedUrl: string
declare const userAgent: string
declare const signature: string
declare const aBogusValue: string
declare const query: string
declare const xBogusValue: string
// ---cut---
import { decodeUrl, decodeXBogus, diagnoseSalt, recoverSignedQuery, structureError, xBogusStructureError } from '@ikenxuan/amagi/signing'

// a_bogus：从一条已签名的 URL 里把签名读回明文
const [decoded] = decodeUrl(signedUrl, { userAgent })
console.log(decoded.fields, decoded.checks, decoded.notes)

// a_bogus：反推盐值 / 覆盖的 query
console.log(diagnoseSalt(aBogusValue, query).salt)
console.log(recoverSignedQuery(signature, signedUrl)?.kept)

// X-Bogus：结构检查 + 拆解 + 候选链校验
console.log(xBogusStructureError(xBogusValue))
console.log(decodeXBogus(xBogusValue, { query: '/aweme/v1/web/aweme/detail/?aid=6383', userAgent }).checks)

// 只想问「这串东西是不是 a_bogus」
console.log(structureError(aBogusValue)) // null 表示通过
```

## 下一步 [#下一步]

<DocsCategory group="签名验证" />


# 为什么签名需要被验证 (https://ikenxuan.github.io/amagi/docs/v7/dev/sign-verify)

> 平台对签名是抽样校验的，「请求成功」证明不了任何事；四个平台的验证器与它们各自的验证强度



# 为什么签名需要被验证 [#为什么签名需要被验证]

抖音对签名是**抽样校验**的：签名用错了常量，请求大部分时候照样成功，只是被判定为高风险的概率上升。它不报错、不返回空、不给你任何可分辨的信封 —— 表现为「偶尔不稳」，而不是「坏了」。所以把「接口能通」当作签名正确的证据，是无效推理。

麻烦在于，签名算法里藏着若干个**常量**（抖音的盐值、`page_id`、SDK 版本块；快手的布局魔数；小红书的模板版本……）。它们随平台改自己的前端代码而变，而变的时候**没有任何通知**。

## 自证模型的三个空转 [#自证模型的三个空转]

在这套约束下，常见的测试写法一个都发现不了常量过期：

| 写法                 | 为什么无效                                                   |
| ------------------ | ------------------------------------------------------- |
| 自生成快照              | 首次运行时由**被测代码自己**写入。常量改了，快照跟着改，测试永远绿                     |
| 与被测对象比自身           | `expect(v7).toBe(v6)` —— 但两个符号 import 的是同一个模块，等于把函数和自己比 |
| 「输出长度 > 100」这类形状断言 | 错的常量产出的签名与对的**形状完全一致**，只是字节不同                           |

一句话：&#x2A;*没有任何自证型断言能证伪一个常量。** 这不是写得不够好，是模型的问题 —— 缺少一个不随被测代码变化的外部锚点。amagi 的数据接口就带着一个 2024 年的旧盐值活了两年（故事在[抖音](/docs/v7/dev/sign-verify/douyin)那页）。

## 四个平台，各能验到什么程度 [#四个平台各能验到什么程度]

唯一能证伪一个常量的办法，是拿平台自己的输出拆开看。每个平台的验证器都在自己那页的页顶，跑的就是 `@ikenxuan/amagi/signing` **本身** —— 与 oracle 测试、与线上签名同一份代码。但各平台的可验证面**不一样宽**，这是诚实而不是缺口：

| 平台  | 可验证的签名                            | 能验到什么                                        | 验证强度                    |
| --- | --------------------------------- | -------------------------------------------- | ----------------------- |
| 抖音  | `a_bogus`                         | 结构指纹、盐值判定、query / UA 摘要链（24 位/条）、可还原时钟与五十个标量 | ●●● 整段可拆，有真实捕获做 oracle  |
| 抖音  | `X-Bogus`                         | 常量指纹、可还原时钟、16 位摘要链                           | ●●○ 可拆；暂无浏览器捕获          |
| 抖音  | `x-secsdk-web-signature`          | 确定性 MD5，重算逐字符比对                              | ●●● 完全可验                |
| 抖音  | `verify_fp` / `msToken` / `ttwid` | 骨架与时钟；msToken / ttwid 底下没有明文                 | ●○○ 部分是「说了就是答案」         |
| B站  | `w_rid`（wbi）                      | 同一组 keys、同一个 `wts` 重算，逐字符比对                  | ●●● 完全可验                |
| B站  | av ↔ bv                           | 双向互转，往返自洽                                    | ●●● 完全可验                |
| 快手  | `$HE_` 段                          | 布局常量、双层 LRC、可还原时钟与计数器                        | ●●○ 可拆；暂无浏览器捕获          |
| 小红书 | `x-s` 等头部                         | 前缀、长度、字符集（XYW 信封可拆一层 JSON）                   | ●○○ 算法本体在 Node 侧，进不了浏览器 |

「验证强度」低一档的都不藏：[快手](/docs/v7/dev/sign-verify/kuaishou)那页解释了 HUDR 段为什么拆不开，[小红书](/docs/v7/dev/sign-verify/xiaohongshu)那页解释了算法本体为什么进不了浏览器。

## 「解码」诚实地指三件事 [#解码诚实地指三件事]

把这三件事混为一谈，是这类工具开始撒谎的方式：

1. **可还原** —— 值就在载荷里，能原样取回：时钟、`aid`、计数器。没有任何推断。
2. **被绑定但不可还原** —— 载荷里带着某个输入的摘要。输入无法从摘要倒推，工具**从不假装能**；它做的是校验：给候选值，回答是不是签名封住的那一个，并标注证据位数。
3. **根本没被计算** —— `msToken`、ttwid、HUDR 密文由平台签发或整体加密，底下没有明文可找。说出这一点就是答案，而不是「没能给出答案」。

## 下一步 [#下一步]

<DocsCategory group="签名验证" />


# 快手 (https://ikenxuan.github.io/amagi/docs/v7/dev/sign-verify/kuaishou)

> $HE_ 段可整段拆开（时钟与计数器原样读回）；HUDR 段拆不开，说了就是答案



# 快手签名验证 [#快手签名验证]

快手的 `__NS_hxfalcon` 签名由两段拼成：`HUDR_<base64url 密文>` + `$HE_<hex>&#x60;。两段的可验证面完全不同 —— &#x2A;*`$HE_` 段布局固定、可整段拆开；HUDR 段整段是 ChaCha 密文，底下没有明文可找。**

<SignVerifier platform="kuaishou" />

## `$HE_` 段：能拆到什么 [#he_-段能拆到什么]

最终输出是 45 字节 hex，最后一个字节是**异或键** —— 它本身是前 44 字节的 LRC 校验，同时把那 44 字节逐个异或成密文。所以解码顺序固定为「拆键 → 还原 → 逐段校验 → 读字段」：

| 字段            | 位置（还原后） | 能验 / 能读                            |
| ------------- | ------- | ---------------------------------- |
| header 魔数     | 0–1     | 恒为 `4B54`                          |
| 版本块           | 2–3     | 恒为 `cda9`                          |
| 启动标记          | 4       | 恒为 `ab`                            |
| startupRandom | 5–10    | 原样读回（页面加载时的一次性随机数）                 |
| random        | 11–16   | 原样读回（本条签名自己的 48 位随机数）              |
| 固定体           | 17–21   | 恒为 `0100000001`                    |
| count         | 22–25   | 异或掩码已解掉，原样读回                       |
| hash field    | 26–29   | 读得出；**重算**需要 signInput + HUDR body |
| 时钟            | 30–35   | 异或掩码已解掉，原样读回（毫秒）                   |
| 尾段            | 36–42   | 恒为 `9b563eda7b563e`                |
| 两层 LRC        | 43 / 44 | 信封 LRC 覆盖全部 44 字节，尾段 LRC 只覆盖尾段     |

能同时通过两层校验与四个布局常量的值，必然是这套装配顺序产出的 —— 这就是「结构指纹」，与 a\_bogus 的校验和同理。

<Callout type="info" title="hash field 为什么不自动重算">
  它绑的是 `signInput + HUDR body`：前者由请求 URL 与载荷推导，后者是随实例状态滚动的
  密文。捕获签名时这两样通常不在手边 —— 输入凑不齐就别猜，凑齐了可以用
  `deriveKuaishouHeHashFieldHex` 自行比对。
</Callout>

## HUDR 段：拆不开，说了就是答案 [#hudr-段拆不开说了就是答案]

HUDR 段的载荷经过掩码与 ChaCha 加密（密钥写死在前端代码里，amagi 与之对齐），内容对验证器而言是不可还原的。能验的只有外壳：`HUDR_` 前缀与 base64url 字符集。这不是缺口 —— 它的**作用**就是让外部无法拼装签名，能拆开反而是坏事。

## 诚实的局限：没有外部 oracle [#诚实的局限没有外部-oracle]

`$HE_` 的结构断言全部来自本仓库实现与前端代码的对齐，仓库里**没有**一份浏览器产出的快手签名捕获（不像抖音的 a\_bogus 有 oracle fixture）。所以「结构良好」证明的是装配顺序对齐，不能证明常量全部新鲜。快手前端若改了布局常量（header、版本块、尾段），验证器会开始报「对不上」—— 那时该重新对一遍前端代码。

<Callout type="warn" title="签名状态随实例走">
  `count` 随每次签名递增、`startupRandom` 按实例生成、匿名 `kww` 按实例缓存 ——
  同进程两个 client 的签名互不干扰。对比两份签名时，别把 count 或随机数的不同
  当成「有一个是错的」。
</Callout>

## 下一步 [#下一步]

<DocsCategory group="签名验证" />


# 小红书 (https://ikenxuan.github.io/amagi/docs/v7/dev/sign-verify/xiaohongshu)

> x-s 的算法本体进不了浏览器 —— 这里只有形状检查；XYW 信封能拆一层 JSON



# 小红书签名验证 [#小红书签名验证]

小红书要验的东西是**一组头部**：`x-s`、`x-s-common`、`x-t`、`x-xray-traceid`，部分接口再加 `x-b3-traceid`。验证器对每个头做形状检查，`x-s` 是 XYW\_ 格式时还能拆开信封的一层 JSON。

<SignVerifier platform="xiaohongshu" />

## 先说实话：这个平台的验证强度是四家里最弱的 [#先说实话这个平台的验证强度是四家里最弱的]

`x-s` 的算法本体是 `@ikenxuan/xhshow-ts` 的**内联副本**（在同仓 `platforms/xiaohongshu/sign/xhshow/`），那条依赖链用了 Node 的 `crypto` 与 `zlib`，进不了浏览器 —— 而文档站的验证器必须跑纯代码。所以这一页&#x2A;*证明不了「算法对」，只能证明「形状对」**。全量校验在 Node 侧跑它的测试（v6 对照快照一字不变）。

形状本身仍有鉴别力：前缀区分两套协议、`x-t` 的时钟范围能暴露「拿秒当毫秒」这类错、traceid 的长度与字符集是硬约束。

## 两套 x-s 格式 [#两套-x-s-格式]

<Callout type="warn" title="端点当前一律用 XYS_">
  曾按「`user_posted`、`user/otherinfo` 等数据接口自 2026-03 起以 HTTP 406 拒收 XYS\_、
  必须换 XYW\_」实现 —— 该说法**未经线上验证、且已被真机实测推翻**：2026-10-11 同一游客
  cookie 下，`user_posted` 用 **XYW\_ 回 HTTP 461 空 data**、用 **XYS\_ 回 200 + 真数据**。
  全部 13 个端点现在都走 XYS\_；XYW\_ 信封仍能被验证器识别与拆解，但**照「必须用 XYW\_」写会踩 461**。
</Callout>

XYW\_ 的信封是标准 base64 包着的一层 JSON，浏览器里就能拆：

```json
{
  "signSvn": "56",
  "signType": "x2",
  "appId": "xhs-pc-web",
  "signVersion": "1",
  "payload": "<真正的签名载荷，不可还原>"
}
```

信封字段是签名器**自己报告**的元数据（算法版本、平台标识），payload 才是加密载荷。信封对不上口径（比如 `appId` 不是 `xhs-pc-web`）是能被形状检查抓到的错；payload 内部对不对，只有 Node 侧的测试知道。

## 各头部验什么 [#各头部验什么]

| 头部               | 形状约束                    | 备注                   |
| ---------------- | ----------------------- | -------------------- |
| `x-s`            | `XYS_` / `XYW_` 前缀 + 非空 | XYW 信封可拆一层 JSON      |
| `x-s-common`     | 非空                      | 压缩+编码的不透明串，底下没有明文可找  |
| `x-t`            | 13 位毫秒时间戳               | 能暴露「拿秒当毫秒」           |
| `x-xray-traceid` | 32 位十六进制                | 追踪头；缺失会让部分接口 406     |
| `x-b3-traceid`   | 16 位十六进制                | `userNoteList` 等接口专用 |

## amagi 侧怎么组织 [#amagi-侧怎么组织]

九个签名器注册名（`xhs-post` / `xhs-get` / `xhs-get-trace` / `xhs-post-rap` / `xhs-get-rap` / `xhs-live-get` / `xhs-get-xyw` / `xhs-post-xyw` / `xhs-get-xyw-trace`）只做「注册名 → step 清单」的映射，算法唯一实现在 `platforms/xiaohongshu/sign/steps.ts`，依赖方向单向。签名路径取 `signPath`（接口路径，与完整 URL 无关）；`x-rap-param` 例外，要 host + path。机制细节见[签名如何组织](/docs/v7/dev/internals/signing)。

## 下一步 [#下一步]

<DocsCategory group="签名验证" />


# 自定义请求 (https://ikenxuan.github.io/amagi/docs/v7/usage/advanced/custom-request)

> 用 client.<平台>.request 请求 amagi 尚未收录的接口，含双轨语义、amagi 子对象、反爬参数精调，以及 apiUrls 的返回形态



# 自定义请求 [#自定义请求]

`client.<平台>.request` 是一个真正的 axios 实例，`create`、`defaults`、`interceptors`、`params` 序列化都是 axios 原生行为。区别只有一点，它把请求交给 amagi 的执行管线，签名、cookie、judge、退避重试、事件与 trace 全部自动附加。所以请求 amagi 尚未收录的接口时，这些处理不会缺席。

四个平台都有 `request`。静态面没有，`amagi.douyin.request` 不存在，因为静态面没有可绑定的实例 cookie。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '', bilibili: '', kuaishou: '', xiaohongshu: '' } })
client.douyin.request
client.bilibili.request
client.kuaishou.request
client.xiaohongshu.request
```

## 两条轨 [#两条轨]

`request` 上挂着两条轨，结构相同，唯一的区别是失败时抛不抛异常。

|          | `request.<动词>`                        | `request.axios.<动词>`            |
| -------- | ------------------------------------- | ------------------------------- |
| 返回       | `AmagiResult<T>` 信封                   | `AxiosResponse<AmagiResult<T>>` |
| 失败       | 返回失败信封，**不抛**                         | reject `AxiosError`             |
| 失败时错误在哪  | `result.error`                        | `err.response?.data.error`      |
| 一次响应都没拿到 | 失败信封（`kind: 'network'` / `'timeout'`） | `err.response` 是 `undefined`    |

抛不抛只看信封，跟 axios 的状态校验无关，`validateStatus` 在这条路上不起作用。`AxiosError` 的 `code` 也来自 amagi 的错误码（比如 `RISK_CONTROL`），不是 axios 的 errno。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
const url = 'https://api.bilibili.com/x/web-interface/view?bvid=BV1xx411c7mD'

// 信封轨：失败也是返回值
const r = await client.bilibili.request.get(url)
if (!r.success) console.error(r.error.kind, r.error.message)

// axios 轨：失败是异常，失败信封在 err.response.data 上
try {
  const res = await client.bilibili.request.axios.get(url)
  console.log(res.status)
} catch (err) {
  console.error(err)
}
```

两条轨各有六个入口，五个动词 `get` / `delete` / `post` / `put` / `patch`，再加一个 `request`。动词是 `(url, config?)`，地址单独传，其余写在 `config` 里；`request(config)` 把 `method` / `url` / `data` 一次给齐，适合摊开 `apiUrls` 返回的描述对象。两条轨共用同一个实例、`defaults` 和 `interceptors`。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })

// 动词形态：地址 + 配置
await client.bilibili.request.get('https://api.bilibili.com/x/web-interface/view?bvid=BV1xx411c7mD')

// 配置对象形态：方法、地址、参数一次给齐
await client.bilibili.request.request({
  method: 'GET',
  url: 'https://api.bilibili.com/x/web-interface/view',
  params: { bvid: 'BV1xx411c7mD' }
})
```

### 用泛型标注返回类型 [#用泛型标注返回类型]

`request` 打的是裸接口，不跑 `normalize`，返回平台原始载荷，返回类型默认是 `unknown`。用泛型参数标上，收窄后的 `data` 就是它，两条轨都能用。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })

interface VideoView {
  bvid: string
  title: string
}

const r = await client.bilibili.request.get<VideoView>(
  'https://api.bilibili.com/x/web-interface/view?bvid=BV1xx411c7mD'
)
if (r.success) {
  r.data.title // 类型是 VideoView
}
```

### 请求体放进 `config.data` [#请求体放进-configdata]

五个动词统一是 `(url, config)`，请求体走 `config.data`，这不是 axios 原生的 `post(url, data, config)`。这样五个动词长得一样，也跟 `request({ url, method, data })` 一致。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
declare const url: string
// 请求体在 config.data 里；其余选项照旧用 axios 自己的键
const result = await client.kuaishou.request.post(url, {
  data: { photoId: '3xqxxxx' },
  timeout: 8000,
  amagi: { signPath: '/rest/wd/photo/info' }
})
```

<Callout type="warn">
  第二参**永远**被当成配置。把业务字段直接当第二参传，字段不会进入请求体，请求照发、body 却是空的，返回往往是「成功加空结果」。顺手写进去的 `params`、`timeout` 这类同名键还会按配置生效，更难被发现。

  纯 JavaScript 完全静默。TypeScript 能挡下大多数写法，但只要载荷里有一个键和配置同名就放行，下面这段就能编译通过。
</Callout>

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
declare const url: string
// 看着像「发这个 body」，实际是「拿它当配置」：photoId 丢掉，timeout 生效
const payload = { photoId: '3xqxxxx', timeout: 8000 }
await client.kuaishou.request.post(url, payload)
```

## 用 `amagi` 子对象做单次控制 [#用-amagi-子对象做单次控制]

能用 axios 键表达的（`timeout`、`responseType`、`params`、`headers`、`signal`、`proxy`、`baseURL` 等）一律用 axios 自己的键。`amagi` 里只装 axios 装不下的四样。

| 字段            | 类型                  | 作用                                                                                       |
| ------------- | ------------------- | ---------------------------------------------------------------------------------------- |
| `sign`        | `SignDecl`          | 本次怎么签。注册器名（`string`）、`false`（不签），或一份 `SignStep[]` 反爬参数清单（见[精细控制反爬参数](#精细控制反爬参数)）。不给按平台默认 |
| `cookie`      | `false`             | 本次**不带** cookie                                                                          |
| `signPath`    | `string`            | 签名用的接口路径。不给时从 URL 反推 pathname                                                            |
| `dropHeaders` | `readonly string[]` | 从平台基线里**删掉**的头（大小写不敏感），逃生舱                                                               |

`sign` 不给时按平台默认。给注册名时写错，管线会抛 `未注册的签名器` 并收成失败信封，不是裸抛。

| 平台  | `sign` 不给时                                        | 说明                                                             |
| --- | ------------------------------------------------- | -------------------------------------------------------------- |
| 抖音  | `'a-bogus'`                                       | 另一个可选项是 `'x-bogus'`；两者都会自动走 `x-secsdk-web-signature` 那一步，不用自己选 |
| B站  | `false`（不签）                                       | 27 条端点里只有 5 条签名。默认签会大面积**静默**签错，要签就显式给                         |
| 快手  | `'hxfalcon'`                                      | `live_api` 与 H5 两套接口共用同一个签名器                                   |
| 小红书 | 按 method 现算，`POST` 给 `'xhs-post'`，其余给 `'xhs-get'` | `'xhs-get-trace'`（多一个 `x-b3-traceid`）推不出来，要用的显式传               |

裸请求的重试策略也按平台预置，语义和端点声明的 `retryOn` 一样。抖音是 `ANTIBOT_PAGE`（会重新签名换一套新令牌，重放同一套必被拦），B站是 `RISK_CONTROL`，快手是 `PLATFORM_UNAVAILABLE`，小红书没有默认重试。

### cookie 与删头 [#cookie-与删头]

实例上绑的 ck（`createClient({ cookies: { <平台>: '...' } })`）会自动带上。想「就这一次匿名」用 `amagi.cookie: false`。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=example' } })
// B站评论区会按账号改变热度池排序：这一次要的是未登录看到的那个顺序
const r = await client.bilibili.request.get('https://api.bilibili.com/x/v2/reply?type=1&oid=170001', {
  amagi: { cookie: false }
})
```

`cookie: false` 等价于 `dropHeaders: ['cookie']`，删头发生在所有 header 合并之后，你自己在 `headers` 里写的 `Cookie` 也会一并删掉。删头范围比 cookie 更大时才需要写 `dropHeaders`。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
declare const url: string
// ---cut---
await client.kuaishou.request.get(url, { amagi: { dropHeaders: ['origin', 'sec-fetch-site'] } })
```

### `signPath` 何时要自己传 [#signpath-何时要自己传]

`signPath` 指定签名用的接口路径。不传时从 URL 反推 pathname，多数接口够用。签名路径和公开 URL 不一致时必须自己传，有两种。

* **小红书**有些接口的公开 URL 是 HTML 页地址（如 `userProfile` 的 `https://www.xiaohongshu.com/user/profile/<user_id>`），要签的是另一条 API 路径。
* **快手**如 `userInfoById`，URL 走 `/rest/w` 前缀，签名路径却是 `/rest/k/user/info`。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
declare const url: string
await client.kuaishou.request.post(url, {
  data: { photoId: '3xqxxxx' },
  amagi: { signPath: '/rest/wd/photo/info' }
})
```

用 `apiUrls` 时它已经把 `signPath` 一起给出来了（小红书叫 `apiPath`，快手叫 `signPath`），照着填即可。

## 精细控制反爬参数 [#精细控制反爬参数]

指定注册名（`sign: 'a-bogus'`）就是选一套配好的签名，多数时候够用。需要换 `msToken` 长度、去掉某个收尾步骤、只签其中一项，或凑一套注册名没覆盖的组合时，从 `@ikenxuan/amagi/sign-steps` 引入原子 step 工厂，拼成一份清单交给 `sign`。step 工厂按平台分成四个命名空间对象（`douyin`、`bilibili`、`kuaishou`、`xiaohongshu`）。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
declare const url: string
// ---cut---
import { douyin } from '@ikenxuan/amagi/sign-steps'

// 要 a_bogus，但把 msToken 换成 200 长度，且不追加 secsdk 收尾
await client.douyin.request.get(url, { amagi: { sign: [douyin.msToken(200), douyin.aBogus()] } })
```

清单里每个 step 对应一个反爬参数，自己知道怎么算、写进 query 还是 header。你只管挑哪些、传什么参数。step 不按你写的先后执行，runtime 先按 `phase` 稳定排序（`prepare` → `token` → `sign` → `finalize`）再依次跑，所以顺序写反也不会错。

| 命名空间          | step                   | phase      | 作用                                                                       |
| ------------- | ---------------------- | ---------- | ------------------------------------------------------------------------ |
| `douyin`      | `msToken(len)`         | `token`    | 本地随机令牌，写进 URL 的 `msToken`，`len` 是随机段长度                                   |
| `douyin`      | `aBogus()`             | `sign`     | `a_bogus` 主签名，内部先补 `webid`、把 `verifyFp` / `fp` 对齐到 cookie 的 `s_v_web_id` |
| `douyin`      | `xBogus()`             | `sign`     | `X-Bogus` 主签名，内部先补 `webid`、把 `verifyFp` / `fp` 对齐到 cookie 的 `s_v_web_id` |
| `douyin`      | `secsdk()`             | `finalize` | `x-secsdk-web-signature`，改写整条 URL，仅对策略表内的 path 生效                        |
| `douyin`      | `douyinBogus(len)`     | 组合         | 预设 `[msToken(len), aBogus(), secsdk()]`，主流接口用                            |
| `douyin`      | `douyinXBogus(len)`    | 组合         | 预设 `[msToken(len), xBogus(), secsdk()]`，需要 `X-Bogus` 的接口用                |
| `xiaohongshu` | `xs(method, protocol)` | `sign`     | 一次注入 `x-s` / `x-s-common` / `x-t` / `x-xray-traceid` 四个头                 |
| `xiaohongshu` | `traceId()`            | `finalize` | 补一个 `x-b3-traceid` 头                                                     |
| `xiaohongshu` | `rap()`                | `finalize` | 补一个 `x-rap-param` 头                                                      |
| `bilibili`    | `wbi()`                | `sign`     | URL 追加 `wts` / `w_rid`                                                   |
| `bilibili`    | `qtparam()`            | `sign`     | 视频流专属的整套签名                                                               |
| `kuaishou`    | `hxfalcon()`           | `sign`     | `__NS_hxfalcon`，`live_api` 与 H5 两套接口通用                                   |

默认的 `'a-bogus'` 其实就是 `douyin.douyinBogus(184)`。184 是抖音作品详情类接口的 `msToken` 长度，其余接口用 116。手挑的 step 和注册名、平台默认签名内部是同一批实现，签出来必然一致。两层结构的内部组织见开发文档的[签名与反爬](/docs/v7/dev/internals/signing)。

各平台挑 step 时要注意的点如下。

**抖音**这条链的顺序是 `msToken` → `a_bogus` / `x_bogus` → `secsdk`，`msToken()` 会覆盖 URL 里已有的 `msToken`（`retryFresh` 重试靠它换新令牌）。`secsdk()` 只对策略表内的 path 生效（`musicInfo`、作品详情等需要，`emojiList` / `search` 加了也是空操作）。三个 step 都要求**绝对 URL**，`xBogus()` 更严，pathname 至少 3 段且带查询串；不满足会得到 `kind: 'internal'` 的失败信封（一个请求都没发）。

<Callout type="warn">
  想自己掌控 `msToken`（比如复用固定值），就不要把 `douyin.msToken()` 放进清单，只给 `[douyin.aBogus(), douyin.secsdk()]`，URL 里自己拼的 `msToken` 会原样保留，代价是 `retryFresh` 重试时不换新令牌。
</Callout>

**小红书**的 `xs(method, protocol)` 一步注入四个头，`method` 选 `'get'` 签 query、`'post'` 签 body；`protocol` 传 `'xys'` —— 内置的 13 条端点全部用它，包括所有数据获取类接口。`'xyw'` 是另一套 AES-128-CBC 格式，目前没有端点在用、也没验证过能用，别照着猜选。签名只认路径，要通过 `amagi.signPath` 给。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
import { xiaohongshu } from '@ikenxuan/amagi/sign-steps'

await client.xiaohongshu.request.request({
  method: 'POST',
  url: 'https://edith.xiaohongshu.com/api/sns/web/v1/feed',
  data: { source_note_id: 'note-id' },
  amagi: { sign: [xiaohongshu.xs('post', 'xys')], signPath: '/api/sns/web/v1/feed' }
})
```

<Callout type="warn">
  **小红书 GET 用 step 手挑时，query 签不进去。** GET 的 `x-s` 要把 query 一起签进去，而这份参数只有接口声明在 `build` 时才产出，裸请求路径产不出。所以小红书的 GET 数据接口优先走 `fetcher`，或用注册名 `sign: 'xhs-get'`（带 `x-b3-traceid` 的用 `'xhs-get-trace'`）；手挑清单适合 POST。`traceId()` / `rap()` 这两个只补头的 step 不受影响。
</Callout>

**B站**的 `wbi()` 给 URL 追加 `wts` / `w_rid`，`qtparam()` 是视频流专属，把登录判断、fnval 清晰度、wbi 签名整套封在一起，不能拆开自己拼。两者共用同一个签名器实例和 `/nav` 的 key 缓存，手挑和默认注册名不会多打一次 `/nav`。

**快手**的 `live_api`（`/rest/k/*`）和 H5（`/rest/wd/*`）共用 `hxfalcon()` 一个 step。它签名要 query、`signPath` 和 POST 的 body，其中 body **必须是普通对象**（签名和 transport 各做一次 `JSON.stringify`，两边逐字一致才算签对）。先序列化成字符串再传会直接抛错，不会闷头签个错的。

## 可观测性 [#可观测性]

`request` 走的是和 `fetcher` 同一条执行管线，可观测性有两处。

* 返回的信封带 `meta`，有 `requestId`（一次调用一个）、`attempts`（实际发出的底层请求数，含重试）、`durationMs` 等，和 `fetcher` 的信封同形。
* 调用过程发到实例事件总线，`api:success` / `api:error`、`http:request` / `http:response` 等，和 `fetcher` 发的是同一批事件，挂在同一条 `client.events` 上。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })

client.on('http:request', (d) => {
  console.log(d.meta.requestId, d.trace.reason, d.trace.url)
})

const r = await client.douyin.request.get('https://www.douyin.com/aweme/v1/web/...')
if (r.success) {
  console.log(r.meta.requestId, r.meta.attempts) // 与上面事件里的 requestId 一致
}
```

完整的事件清单和 `meta` 字段表见[事件系统](/docs/v7/usage/advanced/events)。

## 派生、默认值与拦截器 [#派生默认值与拦截器]

`create` / `defaults` / `interceptors` 就是底层那个 axios 实例的，按 axios 的习惯用。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: 'ttwid=xxx' } })
// 派生一份带默认值的模块（axios 的 create）
const anonymous = client.douyin.request.create({ timeout: 8000, amagi: { cookie: false } })

// 拦截器两条轨共用
client.douyin.request.interceptors.request.use((config) => {
  config.headers.set('X-Trace', '1')
  return config
})

// defaults 可以就地改
client.douyin.request.defaults.timeout = 8000
```

<Callout type="info">
  `create` 里的 `amagi` 是**按字段分别合并**的，从 `create({ amagi: { cookie: false } })` 派生的模块再写 `amagi: { sign: false }` 不会把 `cookie: false` 冲掉。但 axios 的 `create` **不继承拦截器**，原模块上 `use` 过的在派生模块上一个都没有，得重新 `use`。默认值继承、拦截器不继承，这个不对称是 axios 自己的语义。
</Callout>

## 与 fetcher 的分工 [#与-fetcher-的分工]

|                         | `client.<平台>.fetcher.<方法>`         | `client.<平台>.request.<动词>` |
| ----------------------- | ---------------------------------- | -------------------------- |
| 请求哪类接口                  | 注册表里声明过的端点                         | 任何 URL                     |
| 参数                      | 端点声明的类型 + 运行时校验                    | 自己拼                        |
| 返回                      | 端点声明的响应类型，已 `decode` / `normalize` | 平台**原始载荷**                 |
| 翻页 / 多请求聚合              | 端点声明负责                             | 一次一个请求，不管翻页                |
| judge / 重试 / 事件 / trace | 同一套                                | 同一套                        |

接口已经收录就用 fetcher，多-JSON（`{"a":1}{"b":2}` 这种拼接响应）和 protobuf 都由端点的 `decode` 处理，`request` 给的是未解码的原始载荷。请求尚未收录的接口时，`request` 是唯一入口。

## 已知边界 [#已知边界]

* **不替你拼业务参数。** 签名器只补签名那一组，业务参数尽量从 `client.<平台>.apiUrls` 拿（抖音 21 个构造器里有 16 个带 `verifyFp`）。`verifyFp` / `fp` 的值不用操心：URL 上带了这两个参数时，`aBogus()` / `xBogus()` 会在签名前把它们改成 cookie 里的 `s_v_web_id`（浏览器里三者本就是同一个值），cookie 没有或形状不对就原样保留；但参数本身要不要带由你决定，签名器不会替你加。构造器盖不到的才自己拼（`getGuestUserInfo` 等四条免鉴权接口两者都没有）。抖音的签名器还会在命中 ttwid 缓存时注入 `webid`，冷启动时不动（不传安全、传错致命）。
* **`signal` 取消不走信封。** 取消时两条轨都 reject `CanceledError`，这是「信封轨永不 reject」的例外，取消要自己 `try` 一次。
* **相对 URL 会在签名前置校验处失败。** 抖音的 `a-bogus` 要求绝对地址，传相对路径会得到 `kind: 'internal'` 的失败信封（一个请求都没发）。
* **`adapter` 传不了。** 类型上被 `Omit` 掉，运行期还会再兜一次，传它等于绕开签名和信封。
* **`responseType` 只有 `'json'` / `'text'` / `'arraybuffer'`。** `'blob'` / `'stream'` / `'document'` 解析出来的东西装不进 amagi 的 `RawResponse.body`。
* **要拿 HTML 必须写 `responseType: 'text'`。** 不写时，非空字符串响应体一律判 `ANTIBOT_PAGE` —— 那条公共判据的前提是「打的是 JSON 接口，一张 HTML 回来必然出了事」，对打页面的用法不成立。写了 `'text'` 之后它对字符串不再发表意见，但**平台自己的判据仍然先判**：抖音的滑块中间页、VMP / WAF 挑战页、Argus 拦截文本，小红书的验证头，在 `'text'` 下照旧是失败信封。
* **`'text'` 模式下小红书 / 快手 / B站的 WAF 页会被当成 success。** 这三家没有 HTML 挑战页的锚点判据（抖音有：滑块认 `TTGCaptcha` / `验证码中间页`，VMP 认 `_$jsvmprt`，WAF 认 `_wafchallengeid` / `WAFJS`），所以它们的拦截页在 `'text'` 下与一张正常页面分不开。这是显式声明 `'text'` 时接受的取舍，自己按内容再判一次。
* **抖音打页面地址每次调用要发 2 个请求。** 零 cookie 或缺挑战 cookie 时打 `https://www.douyin.com/` 这类页面地址，第 1 发必定拿到 VMP 挑战页，管线纯算出 `__ac_signature` 并立即重放，第 2 发才是真页（2026-10-11 实测）。解出的挑战 cookie **只在本次调用内有效**，不回写实例身份，所以下一次调用还是 2 发。
* **`validateStatus` 不生效。** 失败判据只有信封。
* **请求体不会被提前序列化。** 你给对象就是对象，快手那种「body 参与签名」的接口签的和发的不会是两份东西。调用方显式给的 `transformRequest` 仍然生效。

## 与 `client.<平台>.apiUrls` 配对 [#与-client平台apiurls-配对]

`client.<平台>.apiUrls` 是 **v7 的 URL 构造器**，只构造，不发请求。v6 那份不在 v7 门面上，要它从包顶层拿（`import { douyinApiUrls } from '@ikenxuan/amagi'`），或走 [`@ikenxuan/amagi/compat`](/docs/v7/usage/migration-v7)。

返回形态每个平台不一样，别照抄。

| 平台  | 构造器的返回                                                                               |
| --- | ------------------------------------------------------------------------------------ |
| 抖音  | URL 字符串（21 个构造器全部如此，query 已拼好）                                                       |
| B站  | 以字符串为主（26 个里的 24 个）；`getCaptchaFromVoucher` / `validateCaptcha` 返回 `{ Url, Body }`   |
| 快手  | 请求描述对象，共三种，`KuaishouH5Request` / `KuaishouLiveApiRequest` / `KuaishouGraphqlRequest` |
| 小红书 | `XhsRequestDescription`，含 `Url` / `Body?` / `apiPath`                                |

字符串那份直接就是请求地址。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
const r = await client.douyin.request.get(client.douyin.apiUrls.getWorkDetail({ aweme_id: '1234567890123456789' }))
```

B站那两条验证码接口返回 `{ Url, Body }`，`Body` 是普通对象，按 JSON 发就行，别自己加表单编码头。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=example' } })
declare const vVoucher: string
const d = client.bilibili.apiUrls.getCaptchaFromVoucher({ v_voucher: vVoucher })
const r = await client.bilibili.request.post(d.Url, { data: d.Body })
```

### 小红书的 `Url` / `Body` / `apiPath` [#小红书的-url--body--apipath]

三个大写键分别对应 `url`、`config.data`、`amagi.signPath`。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
const d = client.xiaohongshu.apiUrls.noteDetail({ note_id: 'note-id', xsec_token: 'xsec_xxx' })
const r = await client.xiaohongshu.request.request({
  method: 'POST',
  url: d.Url,
  data: d.Body,
  amagi: { signPath: d.apiPath }
})
```

GET 那几条（`noteComments` / `userProfile` / `userNoteList` / `emojiList`）没有 `Body`。`userProfile` 的 `Url` 是 HTML 页地址，要签的 `apiPath` 是另一条路径。`userNoteList` 还得显式给 `sign: 'xhs-get-trace'`，四个 GET 里只有它走那个签名器。

### 快手的三种描述对象 [#快手的三种描述对象]

| 返回类型                     | 谁                                                                | 携带什么                                                                   |
| ------------------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `KuaishouH5Request`      | `videoWork` / `videoWorkFull` / `comments`                       | `method`（恒 `'POST'`）/ `body` / `signPath` / `referer` / `requiresSign` |
| `KuaishouLiveApiRequest` | `live_api` 那批（`userInfoById` / `profilePublic` / `liveDetail` …） | `method`（缺省 `'GET'`）/ `body?` / `signPath?` / `requiresSign?`          |
| `KuaishouGraphqlRequest` | `emojiList` / `danmaku`                                          | 只有 `type` / `url` / `body`，&#x2A;*没有 `method`**                        |

**H5 那份**几乎能直接摊进去，`method` 恒为 `'POST'`，`requiresSign` 是必填布尔，`referer` 也在这份上。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
const d = client.kuaishou.apiUrls.videoWork({ photoId: '3xqxxxx' })

const r = await client.kuaishou.request.request({
  method: d.method,
  url: d.url,
  data: d.body,
  // H5 接口按分享页来源校验 Referer，这份要自己带上
  headers: { Referer: d.referer },
  amagi: {
    // requiresSign 是必填布尔：`ugH5App/*` 那几条为 false
    sign: d.requiresSign ? 'hxfalcon' : false,
    signPath: d.signPath
  }
})
```

<Callout type="warn">
  **`live_api` 那份不能照抄上面这段。** 它的 `requiresSign` 是可选的，缺席不等于免签，端点层和执行管线**都不读它**，真正决定签不签的是端点声明里的 `sign`。这批端点声明里给的恰恰是 `sign: 'hxfalcon'`，连 `requiresSign: false` 的 `liveDetail` 也照签。所以别拿 `requiresSign` 反推，`live_api` 要么不给 `sign`（走平台默认），要么显式写 `'hxfalcon'`。它也没有 `referer` 字段，Referer 要按接口自己给。
</Callout>

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
const d = client.kuaishou.apiUrls.userInfoById({ principalId: 'KPL704668133' })

const r = await client.kuaishou.request.request({
  method: d.method, // 'GET'，query 已经拼在 url 里
  url: d.url,
  // 不指定 sign 即平台默认的 'hxfalcon'
  amagi: { signPath: d.signPath }
})
```

GraphQL 那份要自己写 `method: 'POST'`，body 交给 `config.data`。它完全免鉴权，`amagi: { sign: false }` 就够。


# 事件系统 (https://ikenxuan.github.io/amagi/docs/v7/usage/advanced/events)

> 实例级事件总线的 15 个事件、带 meta 的负载，以及 v6 全局单例的去处



# 事件系统 [#事件系统]

amagi 把日志、每一条底层请求、每一次调用的结果和扫码登录会话都以事件形式暴露 —— 包本身不依赖任何日志库，落地方式由你决定。

## 先分清两条总线 [#先分清两条总线]

事件名两边**完全一样**，负载不一样。判断依据是**总线的来源**，而非事件名：

| 总线           | 怎么拿                                                  | 事件名  | 负载                                    | 状态         |
| ------------ | ---------------------------------------------------- | ---- | ------------------------------------- | ---------- |
| **实例总线**（v7） | `client.events` / `client.on` / `client.once`        | 15 个 | 都带 `meta`，没有 `timestamp`              | v7 起用这一条   |
| v6 全局单例      | `amagiEvents`（命名导出）、`amagi.events` / `amagi.on`（静态面） | 12 个 | v6 的 `*EventData`，带 `timestamp: Date` | 形状冻结、v8 移除 |

`amagi(options)` 返回的每个实例**自带一条总线**，实例之间互不串扰 —— 这是 v6「一个 `amagiEvents` 全库共用」修掉的地方（多实例并发时监听器分不清事件来自谁）。

<Callout type="warn">
  **v7 的执行管线一条事件都不往全局单例发。** 还在写全局单例的只有两处 `@deprecated`
  的 v6 路径：低层入口 `fetchData` / `fetchResponse`（`network:*` / `log:warn` /
  `log:error`）与抖音 passport 四方法（`api:*` / `log:debug`）。`client.<平台>.fetcher.*`
  的调用只发实例总线；裸 Fetcher（`douyinFetcher.*`）**一条都不发** —— 它的三参签名
  是 v6 冻结的，没有挂总线的位置。要观测就用 client 形态，监听器挂在 `client.events` 上。
</Callout>

## 基本用法 [#基本用法]

`client.events` 是总线本体，`client.on` / `client.once` 是它的快捷方式（同一条总线）：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: 'ttwid=...' } })

// 一次逻辑调用成功：data 是信封里的 data，其余信息全在 meta 上
client.events.on('api:success', (d) => {
  console.log(`[${d.meta.platform}] ${d.meta.endpoint} 成功，耗时 ${d.meta.durationMs}ms`)
})

// 失败：error 是标准 AmagiError（kind / code / message / platform 原文码）
client.on('api:error', (d) => {
  console.error(`[${d.meta.platform}] ${d.meta.endpoint} 失败：${d.error.kind} ${d.error.message}`)
})

// once 只触发一次
client.once('log:mark', (d) => console.log(d.message))
```

`meta.endpoint` 是**端点全名**（`douyin.videoWork`），不是 v6 的 `methodType`（`videoWork`）。

## 15 个事件 [#15-个事件]

| 事件名                      | 什么时候发                                 | 负载                                                                     |
| ------------------------ | ------------------------------------- | ---------------------------------------------------------------------- |
| `api:success`            | 一次逻辑调用成功返回（覆盖全部 80 个端点）               | `{ meta, data }`                                                       |
| `api:error`              | 一次逻辑调用失败返回（含参数校验失败，此时 `attempts` 为 0） | `{ meta, error }`                                                      |
| `http:request`           | 每发出一条底层请求                             | `{ meta, trace }`                                                      |
| `http:response`          | 每条底层请求结束（含非 2xx 与传输失败）                | `{ meta, trace }`                                                      |
| `http:error`             | 拿到了响应但状态码非 2xx，紧跟在 `http:response` 之后 | `{ meta, trace, status }`                                              |
| `network:retry`          | 一次失败即将退避重试                            | `{ meta, trace, code, errno?, status?, attempt, maxRetries, delayMs }` |
| `network:error`          | 请求始终没拿到响应、退避已用尽                       | `{ meta, trace, code, errno?, message, attempts }`                     |
| `log:warn`               | 每次退避重试一条（文案与 v6 逐字一致）                 | `{ level, message, args?, meta? }`                                     |
| `log:error`              | 传输层放弃时一条（文案与 v6 逐字一致）                 | 同上                                                                     |
| `log:mark`               | `startServer` 开始监听时                   | 同上                                                                     |
| `log:info` / `log:debug` | **没有 emit 点**，见下方「声明了但不发的两个」          | 同上                                                                     |
| `session:state`          | 扫码登录会话推进一步                            | `{ meta, state }`                                                      |
| `session:error`          | 会话终止于失败                               | `{ meta, error }`                                                      |
| `session:success`        | 会话拿到登录凭证                              | `{ meta, credential }`                                                 |

前 12 个名字与 v6 `AmagiEventType` **逐名对齐**（一个都没少，监听写法从全局单例搬到实例总线时不会有事件名静默消失）；`session:*` 三个是 v7 新增，v6 没有。

事件名列表本身也是导出的，写工具时可以直接遍历：

```ts twoslash
import amagi, { AMAGI_BUS_EVENT_NAMES } from '@ikenxuan/amagi'

const client = amagi({})

// 15 个名字的只读元组，类型是 AmagiBusEventName
for (const name of AMAGI_BUS_EVENT_NAMES) {
  client.events.on(name, (payload) => {
    console.log(name, payload.meta?.requestId)
  })
}
```

### 声明了但不发的两个 [#声明了但不发的两个]

`log:info` 与 `log:debug` 的名字在类型里（`on` 能编译），但 v7 核心链路没有 emit 点：v7 新管线没有 info 级日志；v6 的 debug 日志在 v7 里由 `partial: 'tolerate'` + `meta.trace` 表达，另一处是已 `@deprecated` 的 passport 路径（它写的是全局单例）。这两个名字留着是因为它们是 `log:*` 五个级别里的一员，缺一个反而更奇怪。

## meta：事件之间怎么关联 [#meta事件之间怎么关联]

一次逻辑调用从头到尾只有一个 `requestId`，这次调用产生的每条事件都带着它 —— 于是「哪几条 HTTP 请求属于同一次调用」是可算的，不必靠时间戳猜：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { bilibili: '' } })
const byRequest = new Map<string, number>()

client.events.on('http:request', (d) => {
  byRequest.set(d.meta.requestId, (byRequest.get(d.meta.requestId) ?? 0) + 1)
  console.log(d.trace.reason, d.trace.method, d.trace.url)
})

client.events.on('api:success', (d) => {
  // 这两个数一定相等：meta.attempts 就是这次调用发出的请求数
  console.log(d.meta.requestId, d.meta.attempts, byRequest.get(d.meta.requestId))
})
```

`trace.reason` 说明这一条请求为什么会发出：`initial`（首次）/ `retry`（重试）/ `challenge`（解出反爬挑战后的重放，不退避、立即重发）/ `page`（翻页）/ `segment`（分段并发）/ `prepare`（前置请求，如换 guest cookie、取 wbi key）。

`meta` 的完整字段表见[响应类型](/docs/v7/usage/guide/type-mode#amagimeta)；`http:*` 负载里那一条请求明细是：

<TypeTable
  id="type-table-meta.ts-RequestTrace"
  type="{
  &#x22;id&#x22;: &#x22;meta.ts-RequestTrace&#x22;,
  &#x22;name&#x22;: &#x22;RequestTrace&#x22;,
  &#x22;description&#x22;: &#x22;单次底层 HTTP 请求的明细&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;url&#x22;,
      &#x22;description&#x22;: &#x22;实际请求的 URL（含签名参数）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;method&#x22;,
      &#x22;description&#x22;: &#x22;HTTP 方法&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;status&#x22;,
      &#x22;description&#x22;: &#x22;平台返回的状态码，请求未发出（如 DNS 失败）时缺失&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;durationMs&#x22;,
      &#x22;description&#x22;: &#x22;这一次请求本身的耗时&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;reason&#x22;,
      &#x22;description&#x22;: &#x22;这次请求为什么会发出&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;TraceReason&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;TraceReason&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;retryOf&#x22;,
      &#x22;description&#x22;: &#x22;`reason === 'retry'` 时，被重试的那次失败的错误码&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiErrorCode | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

<Callout type="info">
  `http:request` / `http:response` 的负载&#x2A;*恒带 `trace`**，不受 `debug` 开关影响 ——
  想逐条观测请求就监听这两个事件。`createClient({ debug: true })` 只影响
  **信封**上的 `meta.trace` 快照与失败信封的 `error.raw`。`meta.attempts` 与开关无关，
  一直是准的。
</Callout>

## 日志落地 [#日志落地]

`log:warn` / `log:error` 的文案与 v6 逐字一致，所以 v6 里靠它们看重试的监听器搬到实例总线上行为不变。事件负载只给文本，不带颜色（颜色是展示层的事，自己加）：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({})

client.events.on('log:warn', (d) => console.warn(`[WARN] ${d.message}`, ...(d.args ?? [])))
client.events.on('log:error', (d) => console.error(`[ERROR] ${d.message}`, ...(d.args ?? [])))
client.events.on('log:mark', (d) => console.log(`[MARK] ${d.message}`))
```

`log:*` 的负载形状：

<TypeTable
  id="type-table-events.ts-LogEvent"
  type="{
  &#x22;id&#x22;: &#x22;events.ts-LogEvent&#x22;,
  &#x22;name&#x22;: &#x22;LogEvent&#x22;,
  &#x22;description&#x22;: &#x22;`log:*` 事件负载（5 个级别共用）。\n\n与 v6 `LogEventData` 的差别：`timestamp: Date` 换成可选的 `meta`\n—— 日志属于哪一次调用比它发生在哪一毫秒更有用，而不属于任何调用的日志\n（如服务启动）本来就没有 `meta`。&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;level&#x22;,
      &#x22;description&#x22;: &#x22;日志级别，与事件名的后半段一致&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;debug\&#x22; | \&#x22;error\&#x22; | \&#x22;info\&#x22; | \&#x22;mark\&#x22; | \&#x22;warn\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;日志消息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;args&#x22;,
      &#x22;description&#x22;: &#x22;附加参数&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息；不属于任何一次调用的日志没有这一项&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

`meta` 在 `log:*` 上是**可选的** —— 不属于任何一次调用的日志（服务启动那条 `log:mark`）本来就没有 `meta`。

### 接给日志库 [#接给日志库]

总线的类型是 `EventBus`（只导出类型，不导出构造器 —— 总线从 `client.events` 拿，不用自己造），所以接线函数可以写下来：

```ts twoslash
import amagi, { type EventBus } from '@ikenxuan/amagi'
import pino from 'pino'

const logger = pino()

const attachPino = (bus: EventBus): void => {
  bus.on('log:warn', (d) => logger.warn({ endpoint: d.meta?.endpoint }, d.message))
  bus.on('log:error', (d) => logger.error({ requestId: d.meta?.requestId }, d.message))
  bus.on('api:error', (d) => logger.error({ ...d.meta, kind: d.error.kind }, d.error.message))
}

attachPino(amagi({}).events)
```

winston 同理：

```ts twoslash
import amagi from '@ikenxuan/amagi'
import winston from 'winston'

const logger = winston.createLogger({
  transports: [new winston.transports.Console()]
})

const client = amagi({})
client.events.on('log:warn', (d) => logger.warn(d.message))
client.events.on('log:error', (d) => logger.error(d.message))
client.events.on('api:error', (d) => logger.error(`${d.meta.endpoint}: ${d.error.message}`))
```

## 重试与网络失败 [#重试与网络失败]

`network:retry` 在每次退避之前发一条，`network:error` 在彻底放弃时发一条；`http:error` 是「回来了但状态码不对」，两者的分界是**有没有状态码**：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })

client.events.on('network:retry', (d) => {
  console.warn(`第 ${d.attempt}/${d.maxRetries} 次重试，${d.delayMs}ms 后重发：${d.code} ${d.errno ?? d.status}`)
})

client.events.on('network:error', (d) => {
  console.error(`放弃：${d.message}（共发了 ${d.attempts} 次，最后一条 ${d.trace.url}）`)
})

client.events.on('http:error', (d) => {
  console.error(`HTTP ${d.status}：${d.trace.url}`)
})
```

<TypeTable
  id="type-table-events.ts-NetworkRetryEvent"
  type="{
  &#x22;id&#x22;: &#x22;events.ts-NetworkRetryEvent&#x22;,
  &#x22;name&#x22;: &#x22;NetworkRetryEvent&#x22;,
  &#x22;description&#x22;: &#x22;`network:retry` 事件负载：一次失败即将退避重试&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;trace&#x22;,
      &#x22;description&#x22;: &#x22;刚刚失败的那条请求的明细&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestTrace&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;code&#x22;,
      &#x22;description&#x22;: &#x22;归因错误码（`NETWORK_ERROR` / `TIMEOUT` / `RATE_LIMITED` / `PLATFORM_UNAVAILABLE`）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;errno&#x22;,
      &#x22;description&#x22;: &#x22;传输层 errno（`ECONNRESET` 这类）；拿到了响应就没有&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;status&#x22;,
      &#x22;description&#x22;: &#x22;平台返回的状态码；请求根本没发出就没有&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;attempt&#x22;,
      &#x22;description&#x22;: &#x22;这是第几次重试（`1` = 第一次重试），与 v6 `NetworkRetryEventData.attempt` 同义&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;maxRetries&#x22;,
      &#x22;description&#x22;: &#x22;允许的最大重试次数&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;delayMs&#x22;,
      &#x22;description&#x22;: &#x22;这次退避要等的毫秒数&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

<TypeTable
  id="type-table-events.ts-NetworkErrorEvent"
  type="{
  &#x22;id&#x22;: &#x22;events.ts-NetworkErrorEvent&#x22;,
  &#x22;name&#x22;: &#x22;NetworkErrorEvent&#x22;,
  &#x22;description&#x22;: &#x22;`network:error` 事件负载：请求始终没拿到响应，退避已用尽&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;trace&#x22;,
      &#x22;description&#x22;: &#x22;最后一条请求的明细&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestTrace&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;code&#x22;,
      &#x22;description&#x22;: &#x22;归因错误码&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;NETWORK_ERROR\&#x22; | \&#x22;TIMEOUT\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;errno&#x22;,
      &#x22;description&#x22;: &#x22;传输层 errno&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;失败文案&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;attempts&#x22;,
      &#x22;description&#x22;: &#x22;这次调用一共发了几次请求&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

v6 的 `errorCode` 在 v7 里拆成两个字段：`code` 是归因错误码（`RATE_LIMITED` / `TIMEOUT` 这类），`errno` 是传输层原样的 errno（`ECONNRESET`，拿到了响应就没有）。请求 URL 去 `trace.url` 读。

## 登录会话事件 [#登录会话事件]

`client.<平台>.login`（四个平台都有）的扫码会话把每一步都发到同一条总线上（一个会话一个 `requestId`，`meta.endpoint` 形如 `bilibili.login`）：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { bilibili: '' } })

// state.phase：pending → scanned → challenge → success，终止态 expired / rejected / risk / failed
client.events.on('session:state', (d) => console.log(d.meta.endpoint, d.state.phase))
client.events.on('session:success', (d) => console.log(d.credential.cookie))
client.events.on('session:error', (d) => console.error(d.error.code, d.error.message))
```

事件是**旁路观测**，不是消费会话的方式 —— 获取凭证请用 `watch()` 回调、`for await` 或手动单步，见[项目架构](/docs/v7/dev/architecture)的「会话（登录）」一节。

## 移除监听器 [#移除监听器]

`EventBus` 的方法集与 `EventEmitter` 同名，但事件名与负载是类型安全的。监听器类型可以用 `AmagiBusEventMap` 的索引访问写下来（15 个负载类型不逐个占公开名）：

```ts twoslash
import amagi, { type AmagiBusEventMap } from '@ikenxuan/amagi'

const client = amagi({})

const onSuccess = (d: AmagiBusEventMap['api:success']): void => {
  console.log(d.meta.endpoint)
}

client.events.on('api:success', onSuccess)
console.log(client.events.listenerCount('api:success'))

client.events.off('api:success', onSuccess)
client.events.removeAllListeners('api:success')
```

不传事件名的 `removeAllListeners()` 清空这条总线上的全部监听器 —— 因为总线是实例级的，这不会影响别的 client 实例。

## 监控示例 [#监控示例]

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
const stats = { success: 0, error: 0, totalMs: 0 }

client.events.on('api:success', (d) => {
  stats.success++
  stats.totalMs += d.meta.durationMs
})

client.events.on('api:error', (d) => {
  stats.error++
  console.error(`✗ [${d.meta.platform}] ${d.meta.endpoint} - ${d.error.message}`)
})

setInterval(() => {
  const avg = stats.success > 0 ? stats.totalMs / stats.success : 0
  console.log(`成功 ${stats.success}，失败 ${stats.error}，平均耗时 ${avg.toFixed(2)}ms`)
}, 60000)
```

## v6 全局单例 `amagiEvents` [#v6-全局单例-amagievents]

它**一个字都没改**：12 个事件名、`*EventData` 负载、`timestamp: Date` 全在，12 个 `emit*` 自由函数也全在。因此只有两种情况需要用到它：仍有未迁移完的 v6 监听代码，或你自己在用 `emitLog*` 向它发送事件。

```ts twoslash
import amagi, { amagiEvents } from '@ikenxuan/amagi'

// v6 负载：顶层平铺 + timestamp，没有 meta
amagiEvents.on('network:retry', (data) => {
  console.warn(data.errorCode, data.attempt, data.timestamp.toISOString())
})

// 构造函数上的静态面就是这条总线（不是实例总线）
amagi.on('log:warn', (data) => console.warn(data.message, data.timestamp))
```

<Callout type="warn">
  别把这条总线上的读法照搬到 `client.events` 上（也别反过来）：两边事件名一样，
  但 v6 负载是顶层平铺的 `platform` / `methodType` / `duration` / `timestamp`，
  实例总线是 `meta` + `error` / `data` / `trace`。TS 会当场报错，JS 只会读到
  `undefined`。
</Callout>

## 从 v6 迁移：读法对照 [#从-v6-迁移读法对照]

把监听器从全局单例搬到 `client.events` 时，改的只是**读法**：

| v6 读法（全局单例）                  | v7 读法（实例总线）                                                  |
| ---------------------------- | ------------------------------------------------------------ |
| `d.platform`                 | `d.meta.platform`                                            |
| `d.methodType`               | `d.meta.endpoint`（**值也变了**：`videoWork` → `douyin.videoWork`） |
| `d.duration`                 | `d.meta.durationMs`                                          |
| `d.statusCode`               | `d.trace.status`（`http:*`）/ `d.status`（`http:error`）         |
| `d.errorMessage`             | `d.error.message`（`d.error` 是完整的 `AmagiError`）               |
| `d.errorCode`（`api:*`）       | `d.error.platform?.code ?? d.error.code`                     |
| `d.errorCode`（`network:*`）   | `d.code` + `d.errno` 两个字段                                    |
| `d.retries`（`network:error`） | `d.attempts`（语义是「一共发了几次」）                                    |
| `d.url`                      | `d.trace.url`                                                |
| `d.response`（`api:success`）  | `d.data`                                                     |
| `d.timestamp`                | **没有对应键** —— 归因改用 `meta.requestId`（一次逻辑调用一个），要时间自己取时钟        |

迁移时可参考迁移页的[读法对照表](/docs/v7/usage/migration-v7#负载形状监听器搬家要改读法)（只改实例总线上的监听器；`amagiEvents` 上的一行都不用动 —— 那条总线的负载确实一字未变，改了才是把对的改坏）。`d.timestamp` 没有对应键，删掉或改用自己的时钟，两者按需选。

完整的形状对照与破坏性分级（TS 用户是 B 档、JS 用户是 A 档）见[迁移指南](/docs/v7/usage/migration-v7)。


# HTTP 服务 (https://ikenxuan.github.io/amagi/docs/v7/usage/advanced/http-server)

> 使用 amagi 启动本地 HTTP 服务



# HTTP 服务 [#http-服务]

amagi 内置了 Express 服务器，可以一键启动本地 HTTP 服务。

## 启动服务 [#启动服务]

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; bili_jct=yyy',
    douyin: 'ttwid=...',
    kuaishou: 'did=...',
    xiaohongshu: 'a1=...'
  }
})

// 启动服务，默认端口 4567
client.startServer(4567)
```

启动后：

* 平台路由挂在 `/api/<platform>` 下，见下方「路由结构」
* 根路径 `/` 与 `/docs` 会 301 跳到站外的 Apifox 文档（兼容旧入口）；v7 的接口清单在本站，见下方「接口清单」

## 路由结构 [#路由结构]

所有 API 路由挂载在 `/api/<platform>` 下：

* `/api/douyin/*` - 抖音相关接口
* `/api/bilibili/*` - B站相关接口
* `/api/kuaishou/*` - 快手相关接口
* `/api/xiaohongshu/*` - 小红书相关接口

所有端点都是 `GET`，参数都写在 query 里。

## 接口清单 [#接口清单]

具体有哪些端点、每个端点收哪些参数、返回什么，都在本站的 **HTTP 端点参考**里 —— 侧边栏「API 参考 → HTTP 端点参考」，按平台分组、一个端点一页，例如 [B站 · 视频作品详细信息](/docs/v7/usage/api/http/bilibili/videoInfo)。

端点清单由注册表生成，增删改名会直接反映到这里。

<Callout type="warn">
  参考页自带的 playground **直连你本地启动的 amagi 服务**（默认 `http://127.0.0.1:4567`），需要先自行启动服务才能发起请求。

  playground 直连本机，跨域被拦是预期行为；如需联调，可用 curl / Postman 直接请求本机端口，或按下方「自定义路由」自己加 CORS 中间件。
</Callout>

## 响应格式 [#响应格式]

所有接口返回统一的 JSON 信封，**HTTP 状态码恒为 200，失败也是 200**，成败靠信封里的 `success` 判别，顶层没有 `code`。

<CodeBlockTabs defaultValue="成功响应">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="成功响应">
      成功响应
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="失败响应">
      失败响应
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="成功响应">
    ```json
    {
      "success": true,
      "data": { ... },
      "message": "获取成功",
      "meta": {
        "requestId": "m0k8r3q1-7f3ab29c",
        "clientId": "routes-bilibili",
        "platform": "bilibili",
        "endpoint": "bilibili.videoInfo",
        "durationMs": 218,
        "attempts": 1
      },
      "requestPath": "/api/bilibili/<路由>?bvid=BV1xx411c7mD"
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="失败响应">
    ```json
    {
      "success": false,
      "error": {
        "kind": "validation",
        "code": "PARAM_INVALID",
        "message": "Invalid input: expected string, received undefined",
        "retryable": false,
        "issues": [{ "path": "sec_uid", "message": "Invalid input: expected string, received undefined" }]
      },
      "message": "Invalid input: expected string, received undefined",
      "meta": {
        "requestId": "m0k8r3s4-1b9e0c77",
        "clientId": "routes-douyin",
        "platform": "douyin",
        "endpoint": "douyin.userProfile",
        "durationMs": 0,
        "attempts": 0
      },
      "requestPath": "/api/douyin/<路由>"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

几个字段的读法：

* `success` 是唯一判别键：`true` 时有 `data`、不带 `error` 键；`false` 时有 `error`、不带 `data` 键。
* `error` 永不为空，形状固定：`kind`（跨平台统一的错误大类，调用方 switch 它）、`code`（稳定的字符串错误码）、`message`、`retryable`；可选的还有 `platform`（平台原始业务码与文案）、`http`（真实发生的 HTTP 状态）、`issues`（`kind` 为 `validation` 时的字段级错误）。
* 顶层 `message` 等价于 `error.message`，为兼容 v6 的 `result.message` 读法保留。
* `meta` 成功失败都有，`attempts` 是实际发出的底层请求数（含重试与翻页，参数校验没通过时是 `0`）。
* `requestPath` 只有 HTTP 侧有，把本次请求的原始路径（含 query）原样回填；示例里的 `<路由>` 是占位符，真实路径见「接口清单」。

## 鉴权与监听地址 [#鉴权与监听地址]

<Callout type="warn">
  `client.startServer(port)` 沿用 v6 行为：**没有任何鉴权**，且监听在 `'::'`（公网 IPv4/IPv6 双栈）。服务端拿着你的四平台 cookie，任何能连到这个端口的人都能用你的身份取数据 —— 不要暴露到公网。
</Callout>

门面的第二个参数是可选的：`client.startServer(4567, { openapi: true })` 会额外挂上 `GET /openapi.json`（现算现返本机这个版本的规范），并把 `/docs` 改成跳本站的端点参考。不传时行为与 v6 一字不变。

`server/auth.ts` 里另有一个全选项版的 `startServer(options)`：

| 选项        | 默认值     | 说明                                                           |
| --------- | ------- | ------------------------------------------------------------ |
| `port`    | `4567`  | 监听端口                                                         |
| `host`    | `'::'`  | 监听地址。取默认值时启动后打印一次警告（`::` 暴露公网双栈，v8 才改默认值）                    |
| `token`   | 无       | 传了则要求 `Authorization: Bearer <token>`，缺失或不匹配直接返回 **401**     |
| `openapi` | `false` | 传 `true` 时 `GET /openapi.json` 现算现返本机版本的规范，`/docs` 改跳生成的端点参考 |
| `routers` | 无       | `{ path, router }` 列表，把自己的路由挂进来                              |

传了 `token` 时，未带凭证的请求返回：

```json
{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "token 无效或缺失" }
}
```

它**不是完整信封**（没有 `kind` / `retryable` / `meta`）。除这个 401 与未注册路径的 404，`/api/**` 的响应都是 200。

<Callout type="info">
  全选项版的 `startServer` 还在包内部（`server/auth.ts`），未从包入口导出 —— 门面只透出 `openapi` 这一项。要 `token` 或限制监听地址，按下面的「自定义路由」自己组装 Express 应用。
</Callout>

## 自定义路由 [#自定义路由]

四个平台的路由工厂是公开导出的，可以只挑需要的挂到自己的 Express 应用上 —— `client.startServer` 内部做的也是这件事：

```ts twoslash
import express from '@ikenxuan/amagi/express'
import { createBilibiliRoutes, createDouyinRoutes } from '@ikenxuan/amagi'

const app = express()

// 需要鉴权、CORS 或访问日志，就在这里加自己的中间件
app.use('/api/bilibili', createBilibiliRoutes('SESSDATA=xxx; bili_jct=yyy'))
app.use('/api/douyin', createDouyinRoutes('ttwid=...'))

// 只监听本机，别用默认的 '::'
app.listen(3000, '127.0.0.1')
```

四个工厂分别是 `createDouyinRoutes` / `createBilibiliRoutes` / `createKuaishouRoutes` / `createXiaohongshuRoutes`，签名都是 `(cookie: string, requestConfig?: RequestConfig) => Router`，路由与 `startServer` 挂的是同一批（都从端点注册表派生）。第二个参数不传时，运行期会装配该平台的默认请求基线（UA、超时、必需 header），一般不用传。


# 专栏显示卡片信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/articleCards)

> 一次可批量查询多条，支持视频、专栏、直播间的 ID 混传，结果按 ID 分组返回。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/articleCards（规范源：packages/core/openapi.json）

一次可批量查询多条，支持视频、专栏、直播间的 ID 混传，结果按 ID 分组返回。

# 专栏正文内容 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/articleContent)

> 取专栏正文；标题、作者、阅读统计等元信息用 `articleInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/articleContent（规范源：packages/core/openapi.json）

取专栏正文；标题、作者、阅读统计等元信息用 `articleInfo`。

# 专栏文章基本信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/articleInfo)

> 取文章页元信息（标题、头图、作者、阅读/点赞）；正文用 `articleContent`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/articleInfo（规范源：packages/core/openapi.json）

取文章页元信息（标题、头图、作者、阅读/点赞）；正文用 `articleContent`。

# 文集基本信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/articleListInfo)

> 取文集（`rlid`）本体与其中的文章清单；单篇专栏用 `articleInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/articleListInfo（规范源：packages/core/openapi.json）

取文集（`rlid`）本体与其中的文章清单；单篇专栏用 `articleInfo`。

# AV 号转换得到的 BV 号 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/avToBv)

> 把稿件 AV 号换算成 BV 号，本地计算不发请求，返回 `{ bvid }`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/avToBv（规范源：packages/core/openapi.json）

把稿件 AV 号换算成 BV 号，本地计算不发请求，返回 `{ bvid }`。

# 番剧基本信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/bangumiInfo)

> 取番剧季度或单集的基本信息；两个 ID 至少传一个，都传时以 `ep_id` 为准。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/bangumiInfo（规范源：packages/core/openapi.json）

取番剧季度或单集的基本信息；两个 ID 至少传一个，都传时以 `ep_id` 为准。

# 番剧下载流信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/bangumiStream)

> 取番剧剧集的播放与下载流地址；高清档位需要带登录凭证。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/bangumiStream（规范源：packages/core/openapi.json）

取番剧剧集的播放与下载流地址；高清档位需要带登录凭证。

# BV 号转换得到的 AV 号 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/bvToAv)

> 把稿件 BV 号换算成 AV 号，本地计算不发请求，返回 `{ aid }`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/bvToAv（规范源：packages/core/openapi.json）

把稿件 BV 号换算成 AV 号，本地计算不发请求，返回 `{ aid }`。

# 由 v_voucher 申请的验证码信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/captchaFromVoucher)

> 人机校验第一步：用 `v_voucher` 换取验证码与校验参数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/captchaFromVoucher（规范源：packages/core/openapi.json）

人机校验第一步：用 `v_voucher` 换取验证码与校验参数。

# 指定评论的回复列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/commentReplies)

> 取单条根评论下的楼中楼回复；整个评论区的列表用 `comments`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/commentReplies（规范源：packages/core/openapi.json）

取单条根评论下的楼中楼回复；整个评论区的列表用 `comments`。

# 作品评论列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/comments)

> 取作品评论列表，按 `number` 自动翻页并去重；楼中楼用 `commentReplies`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/comments（规范源：packages/core/openapi.json）

取作品评论列表，按 `number` 自动翻页并去重；楼中楼用 `commentReplies`。

# 动态详情 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/dynamicDetail)

> 按动态 ID 取详情，返回结构随动态类型（图文 / 转发 / 视频等）而变。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/dynamicDetail（规范源：packages/core/openapi.json）

按动态 ID 取详情，返回结构随动态类型（图文 / 转发 / 视频等）而变。

# 表情列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/emojiList)

> 取评论区表情面板里的全部表情，无参数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/emojiList（规范源：packages/core/openapi.json）

取评论区表情面板里的全部表情，无参数。

# 直播间信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/liveRoomInfo)

> 取直播间的展示信息（标题、封面、分区等）；房间标识与开播状态用 `liveRoomInit`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/liveRoomInfo（规范源：packages/core/openapi.json）

取直播间的展示信息（标题、封面、分区等）；房间标识与开播状态用 `liveRoomInit`。

# 直播间初始化信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/liveRoomInit)

> 取房间的标识与开播状态；标题、封面等展示信息用 `liveRoomInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/liveRoomInit（规范源：packages/core/openapi.json）

取房间的标识与开播状态；标题、封面等展示信息用 `liveRoomInfo`。

# 登录二维码 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/loginQrcode)

> 扫码登录第一步：返回二维码内容与轮询凭据 `qrcode_key`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/loginQrcode（规范源：packages/core/openapi.json）

扫码登录第一步：返回二维码内容与轮询凭据 `qrcode_key`。

# 登录基本信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/loginStatus)

> 取当前账号的登录信息，可用来判断登录凭证是否还有效。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/loginStatus（规范源：packages/core/openapi.json）

取当前账号的登录信息，可用来判断登录凭证是否还有效。

# 二维码扫码状态 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/qrcodeStatus)

> 轮询扫码进度；登录成功时新登录态只在响应头，本接口不透出响应头。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/qrcodeStatus（规范源：packages/core/openapi.json）

轮询扫码进度；登录成功时新登录态只在响应头，本接口不透出响应头。

# UP 主总播放量 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/uploaderTotalViews)

> 取 UP 主的播放与获赞统计；等级、VIP 等完整资料用 `userSpaceInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/uploaderTotalViews（规范源：packages/core/openapi.json）

取 UP 主的播放与获赞统计；等级、VIP 等完整资料用 `userSpaceInfo`。

# 用户名片信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/userCard)

> 取用户名片（昵称、头像、个性签名、等级、认证）与粉丝、投稿数统计。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/userCard（规范源：packages/core/openapi.json）

取用户名片（昵称、头像、个性签名、等级、认证）与粉丝、投稿数统计。

# 用户空间动态列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/userDynamicList)

> 取用户空间的第一页动态列表；本接口不支持翻页。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/userDynamicList（规范源：packages/core/openapi.json）

取用户空间的第一页动态列表；本接口不支持翻页。

# 用户直播状态与直播间基础信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/userLiveStatus)

> 按 UID 查用户的直播状态与直播间信息；已有房间号时用 `liveRoomInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/userLiveStatus（规范源：packages/core/openapi.json）

按 UID 查用户的直播状态与直播间信息；已有房间号时用 `liveRoomInfo`。

# 用户空间详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/userSpaceInfo)

> 取用户空间完整资料（等级、硬币、VIP、粉丝勋章等）；名片类信息用 `userCard`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/userSpaceInfo（规范源：packages/core/openapi.json）

取用户空间完整资料（等级、硬币、VIP、粉丝勋章等）；名片类信息用 `userCard`。

# 验证码校验结果 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/validateCaptcha)

> 人机校验第二步：提交 `challenge` / `token` 与用户过完验证的结果。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/validateCaptcha（规范源：packages/core/openapi.json）

人机校验第二步：提交 `challenge` / `token` 与用户过完验证的结果。

# 视频实时弹幕列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/videoDanmaku)

> 取视频某一段的实时弹幕；每段 6 分钟，按 `segment_index` 分段取全量。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/videoDanmaku（规范源：packages/core/openapi.json）

取视频某一段的实时弹幕；每段 6 分钟，按 `segment_index` 分段取全量。

# 视频作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/videoInfo)

> 取稿件详情（标题、封面、UP 主、统计、分 P 列表）；返回的 `cid` 供取流与弹幕使用。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/videoInfo（规范源：packages/core/openapi.json）

取稿件详情（标题、封面、UP 主、统计、分 P 列表）；返回的 `cid` 供取流与弹幕使用。

# 视频下载流信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/bilibili/videoStream)

> 取稿件的播放与下载流地址；高清档位需要带登录凭证，`cid` 来自 `videoInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/bilibili/videoStream（规范源：packages/core/openapi.json）

取稿件的播放与下载流地址；高清档位需要带登录凭证，`cid` 来自 `videoInfo`。

# 指定评论的回复列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/commentReplies)

> 某条根评论下的回复列表，单页仅 3 条；整个评论区用 `comments`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/commentReplies（规范源：packages/core/openapi.json）

某条根评论下的回复列表，单页仅 3 条；整个评论区用 `comments`。

# 作品评论列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/comments)

> 作品的一级评论列表；某条评论下的回复用 `commentReplies`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/comments（规范源：packages/core/openapi.json）

作品的一级评论列表；某条评论下的回复用 `commentReplies`。

# 作品弹幕列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/danmakuList)

> 取作品在给定时间区间内的弹幕；不给区间即全片，返回按时间排序。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/danmakuList（规范源：packages/core/openapi.json）

取作品在给定时间区间内的弹幕；不给区间即全片，返回按时间排序。

# 动态表情列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/dynamicEmojiList)

> 返回动态表情资源；常规表情列表用 `emojiList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/dynamicEmojiList（规范源：packages/core/openapi.json）

返回动态表情资源；常规表情列表用 `emojiList`。

# 表情列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/emojiList)

> 返回常规与限时/联名表情的清单；动态表情用 `dynamicEmojiList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/emojiList（规范源：packages/core/openapi.json）

返回常规与限时/联名表情的清单；动态表情用 `dynamicEmojiList`。

# 表情资源包元信息（免鉴权） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/emojiResourceMeta)

> 返回表情资源包的版本与下载地址；下载与解包由调用方处理。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/emojiResourceMeta（规范源：packages/core/openapi.json）

返回表情资源包的版本与下载地址；下载与解包由调用方处理。

# 某条原声下的作品列表（免鉴权） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/guestMusicAwemeList)

> 某条原声下的作品列表，只取一页；只有 `aweme_id` 可用，详情走 `parseWork`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/guestMusicAwemeList（规范源：packages/core/openapi.json）

某条原声下的作品列表，只取一页；只有 `aweme_id` 可用，详情走 `parseWork`。

# 原声本体（免鉴权） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/guestMusicInfo)

> 按原声 ID 返回原声详情；这条没有 mp3 播放地址，需要时用 `musicInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/guestMusicInfo（规范源：packages/core/openapi.json）

按原声 ID 返回原声详情；这条没有 mp3 播放地址，需要时用 `musicInfo`。

# 抖音号转用户信息（免鉴权） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/guestUserInfo)

> 用抖音号精确换 `sec_uid`；抖音号不存在时返回失败。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/guestUserInfo（规范源：packages/core/openapi.json）

用抖音号精确换 `sec_uid`；抖音号不存在时返回失败。

# 图集作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/imageAlbumWork)

> 已知是图集作品时用这条；形态不确定时先用 `parseWork` 自动识别。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/imageAlbumWork（规范源：packages/core/openapi.json）

已知是图集作品时用这条；形态不确定时先用 `parseWork` 自动识别。

# 直播间信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/liveRoomInfo)

> 按直播间短号返回开播状态、标题与主播信息。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/liveRoomInfo（规范源：packages/core/openapi.json）

按直播间短号返回开播状态、标题与主播信息。

# 登录二维码 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/loginQrcode)

> 创建登录二维码，返回二维码内容与票据；扫码后的登录状态不在这条。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/loginQrcode（规范源：packages/core/openapi.json）

创建登录二维码，返回二维码内容与票据；扫码后的登录状态不在这条。

# 合集作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/mixAweme)

> 按 mix_id 获取合集内的作品；mix_id 取自作品详情 mix_info.mix_id，number 为目标条数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/mixAweme（规范源：packages/core/openapi.json）

按 mix_id 获取合集内的作品；mix_id 取自作品详情 mix_info.mix_id，number 为目标条数。

# 某条原声下的作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/musicAwemeList)

> 某条原声下的作品列表，只取一页；每条作品的 `music` 带 mp3 播放地址，`musicInfo` 没有时从这里取。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/musicAwemeList（规范源：packages/core/openapi.json）

某条原声下的作品列表，只取一页；每条作品的 `music` 带 mp3 播放地址，`musicInfo` 没有时从这里取。

# 音乐作品信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/musicInfo)

> 带 mp3 播放地址与使用量的音乐详情，个别原声不回播放地址时用 `musicAwemeList`；免鉴权版本用 `guestMusicInfo`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/musicInfo（规范源：packages/core/openapi.json）

带 mp3 播放地址与使用量的音乐详情，个别原声不回播放地址时用 `musicAwemeList`；免鉴权版本用 `guestMusicInfo`。

# 聚合解析作品数据（自动识别类型） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/parseWork)

> 同一个作品 ID 可能是视频、图集、合辑、文字或文章，这条自动识别形态并返回对应结构。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/parseWork（规范源：packages/core/openapi.json）

同一个作品 ID 可能是视频、图集、合辑、文字或文章，这条自动识别形态并返回对应结构。

# 搜索结果列表（综合/用户/视频） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/search)

> 搜索结果的形态由 `type` 决定；响应里 `__search_type` 标出实际形态。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/search（规范源：packages/core/openapi.json）

搜索结果的形态由 `type` 决定；响应里 `__search_type` 标出实际形态。

# 分享链接转短链接 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/shortUrl)

> 把抖音作品分享链接转换成 `v.douyin.com` 短链；`belong=aweme` 是能缩短的前提。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/shortUrl（规范源：packages/core/openapi.json）

把抖音作品分享链接转换成 `v.douyin.com` 短链；`belong=aweme` 是能缩短的前提。

# 合辑作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/slidesWork)

> 已知是合辑（幻灯片/图文）时用这条；形态不确定时先用 `parseWork`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/slidesWork（规范源：packages/core/openapi.json）

已知是合辑（幻灯片/图文）时用这条；形态不确定时先用 `parseWork`。

# 搜索联想词与热点词列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/suggestWords)

> 按输入前缀返回候选词与热点词；不返回搜索结果，搜索用 `search`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/suggestWords（规范源：packages/core/openapi.json）

按输入前缀返回候选词与热点词；不返回搜索结果，搜索用 `search`。

# 文字作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/textWork)

> 已知是文字作品时用这条；形态不确定时先用 `parseWork` 自动识别。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/textWork（规范源：packages/core/openapi.json）

已知是文字作品时用这条；形态不确定时先用 `parseWork` 自动识别。

# 用户主页点赞作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/userFavoriteList)

> 该用户点赞过的作品列表；其发布的作品用 `userVideoList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/userFavoriteList（规范源：packages/core/openapi.json）

该用户点赞过的作品列表；其发布的作品用 `userVideoList`。

# 用户主页信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/userProfile)

> 只认 `sec_uid`；手里只有抖音号时先用 `guestUserInfo` 换。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/userProfile（规范源：packages/core/openapi.json）

只认 `sec_uid`；手里只有抖音号时先用 `guestUserInfo` 换。

# 用户主页推荐作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/userRecommendList)

> 主页的推荐流作品，不保证是该用户发布的；自己的作品用 `userVideoList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/userRecommendList（规范源：packages/core/openapi.json）

主页的推荐流作品，不保证是该用户发布的；自己的作品用 `userVideoList`。

# 用户主页作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/userVideoList)

> 该用户发布的作品列表；喜欢列表用 `userFavoriteList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/userVideoList（规范源：packages/core/openapi.json）

该用户发布的作品列表；喜欢列表用 `userFavoriteList`。

# 视频作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/douyin/videoWork)

> 已知是视频作品时用这条；形态不确定时先用 `parseWork` 自动识别。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/douyin/videoWork（规范源：packages/core/openapi.json）

已知是视频作品时用这条；形态不确定时先用 `parseWork` 自动识别。

# HTTP 端点参考 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http)

> 80 个 HTTP 端点，由端点注册表派生的 OpenAPI 规范生成



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

四个平台共 80 个 HTTP 端点。本节每一页都由端点注册表生成的 OpenAPI 规范派生，
所以这里的路径、参数与响应形状不会与代码脱节。

SDK 侧的方法参考在[各平台 SDK 方法页](/docs/v7/usage/api/sdk/douyin)，两者是同一批端点的两种形态。

<Callout type="warn">
  每页的 playground **直连你本机启动的 amagi 服务**（默认 `http://127.0.0.1:4567`），
  需要先自行启动该服务。浏览器可能因跨域（CORS）拦下请求，这是预期行为。
</Callout>

## 抖音（26） [#抖音26]

<Cards>
  <Card title="指定评论的回复列表" href="/docs/v7/usage/api/http/douyin/commentReplies" />

  <Card title="作品评论列表" href="/docs/v7/usage/api/http/douyin/comments" />

  <Card title="作品弹幕列表" href="/docs/v7/usage/api/http/douyin/danmakuList" />

  <Card title="动态表情列表" href="/docs/v7/usage/api/http/douyin/dynamicEmojiList" />

  <Card title="表情列表" href="/docs/v7/usage/api/http/douyin/emojiList" />

  <Card title="表情资源包元信息（免鉴权）" href="/docs/v7/usage/api/http/douyin/emojiResourceMeta" />

  <Card title="某条原声下的作品列表（免鉴权）" href="/docs/v7/usage/api/http/douyin/guestMusicAwemeList" />

  <Card title="原声本体（免鉴权）" href="/docs/v7/usage/api/http/douyin/guestMusicInfo" />

  <Card title="抖音号转用户信息（免鉴权）" href="/docs/v7/usage/api/http/douyin/guestUserInfo" />

  <Card title="图集作品详细信息" href="/docs/v7/usage/api/http/douyin/imageAlbumWork" />

  <Card title="直播间信息" href="/docs/v7/usage/api/http/douyin/liveRoomInfo" />

  <Card title="登录二维码" href="/docs/v7/usage/api/http/douyin/loginQrcode" />

  <Card title="合集作品列表" href="/docs/v7/usage/api/http/douyin/mixAweme" />

  <Card title="某条原声下的作品列表" href="/docs/v7/usage/api/http/douyin/musicAwemeList" />

  <Card title="音乐作品信息" href="/docs/v7/usage/api/http/douyin/musicInfo" />

  <Card title="聚合解析作品数据（自动识别类型）" href="/docs/v7/usage/api/http/douyin/parseWork" />

  <Card title="搜索结果列表（综合/用户/视频）" href="/docs/v7/usage/api/http/douyin/search" />

  <Card title="分享链接转短链接" href="/docs/v7/usage/api/http/douyin/shortUrl" />

  <Card title="合辑作品详细信息" href="/docs/v7/usage/api/http/douyin/slidesWork" />

  <Card title="搜索联想词与热点词列表" href="/docs/v7/usage/api/http/douyin/suggestWords" />

  <Card title="文字作品详细信息" href="/docs/v7/usage/api/http/douyin/textWork" />

  <Card title="用户主页点赞作品列表" href="/docs/v7/usage/api/http/douyin/userFavoriteList" />

  <Card title="用户主页信息" href="/docs/v7/usage/api/http/douyin/userProfile" />

  <Card title="用户主页推荐作品列表" href="/docs/v7/usage/api/http/douyin/userRecommendList" />

  <Card title="用户主页作品列表" href="/docs/v7/usage/api/http/douyin/userVideoList" />

  <Card title="视频作品详细信息" href="/docs/v7/usage/api/http/douyin/videoWork" />
</Cards>

## B站（27） [#b站27]

<Cards>
  <Card title="专栏显示卡片信息" href="/docs/v7/usage/api/http/bilibili/articleCards" />

  <Card title="专栏正文内容" href="/docs/v7/usage/api/http/bilibili/articleContent" />

  <Card title="专栏文章基本信息" href="/docs/v7/usage/api/http/bilibili/articleInfo" />

  <Card title="文集基本信息" href="/docs/v7/usage/api/http/bilibili/articleListInfo" />

  <Card title="AV 号转换得到的 BV 号" href="/docs/v7/usage/api/http/bilibili/avToBv" />

  <Card title="番剧基本信息" href="/docs/v7/usage/api/http/bilibili/bangumiInfo" />

  <Card title="番剧下载流信息" href="/docs/v7/usage/api/http/bilibili/bangumiStream" />

  <Card title="BV 号转换得到的 AV 号" href="/docs/v7/usage/api/http/bilibili/bvToAv" />

  <Card title="由 v_voucher 申请的验证码信息" href="/docs/v7/usage/api/http/bilibili/captchaFromVoucher" />

  <Card title="指定评论的回复列表" href="/docs/v7/usage/api/http/bilibili/commentReplies" />

  <Card title="作品评论列表" href="/docs/v7/usage/api/http/bilibili/comments" />

  <Card title="动态详情" href="/docs/v7/usage/api/http/bilibili/dynamicDetail" />

  <Card title="表情列表" href="/docs/v7/usage/api/http/bilibili/emojiList" />

  <Card title="直播间信息" href="/docs/v7/usage/api/http/bilibili/liveRoomInfo" />

  <Card title="直播间初始化信息" href="/docs/v7/usage/api/http/bilibili/liveRoomInit" />

  <Card title="登录二维码" href="/docs/v7/usage/api/http/bilibili/loginQrcode" />

  <Card title="登录基本信息" href="/docs/v7/usage/api/http/bilibili/loginStatus" />

  <Card title="二维码扫码状态" href="/docs/v7/usage/api/http/bilibili/qrcodeStatus" />

  <Card title="UP 主总播放量" href="/docs/v7/usage/api/http/bilibili/uploaderTotalViews" />

  <Card title="用户名片信息" href="/docs/v7/usage/api/http/bilibili/userCard" />

  <Card title="用户空间动态列表" href="/docs/v7/usage/api/http/bilibili/userDynamicList" />

  <Card title="用户直播状态与直播间基础信息" href="/docs/v7/usage/api/http/bilibili/userLiveStatus" />

  <Card title="用户空间详细信息" href="/docs/v7/usage/api/http/bilibili/userSpaceInfo" />

  <Card title="验证码校验结果" href="/docs/v7/usage/api/http/bilibili/validateCaptcha" />

  <Card title="视频实时弹幕列表" href="/docs/v7/usage/api/http/bilibili/videoDanmaku" />

  <Card title="视频作品详细信息" href="/docs/v7/usage/api/http/bilibili/videoInfo" />

  <Card title="视频下载流信息" href="/docs/v7/usage/api/http/bilibili/videoStream" />
</Cards>

## 快手（14） [#快手14]

<Cards>
  <Card title="评论回复列表" href="/docs/v7/usage/api/http/kuaishou/commentReplies" />

  <Card title="作品评论列表" href="/docs/v7/usage/api/http/kuaishou/comments" />

  <Card title="作品弹幕列表" href="/docs/v7/usage/api/http/kuaishou/danmakuList" />

  <Card title="表情列表" href="/docs/v7/usage/api/http/kuaishou/emojiList" />

  <Card title="表情包列表" href="/docs/v7/usage/api/http/kuaishou/emotionPackageList" />

  <Card title="直播间聚合信息" href="/docs/v7/usage/api/http/kuaishou/liveRoomInfo" />

  <Card title="当前登录账号资料" href="/docs/v7/usage/api/http/kuaishou/loginUserProfile" />

  <Card title="搜索用户" href="/docs/v7/usage/api/http/kuaishou/searchUser" />

  <Card title="搜索作品" href="/docs/v7/usage/api/http/kuaishou/searchWorkList" />

  <Card title="作品相关推荐" href="/docs/v7/usage/api/http/kuaishou/slideFeed" />

  <Card title="用户主页聚合信息" href="/docs/v7/usage/api/http/kuaishou/userProfile" />

  <Card title="用户公开作品列表" href="/docs/v7/usage/api/http/kuaishou/userWorkList" />

  <Card title="单个作品详细信息" href="/docs/v7/usage/api/http/kuaishou/videoWork" />

  <Card title="单个作品详细信息（完整版，当前稳定撞风控）" href="/docs/v7/usage/api/http/kuaishou/videoWorkFull" />
</Cards>

## 小红书（13） [#小红书13]

<Cards>
  <Card title="表情列表" href="/docs/v7/usage/api/http/xiaohongshu/emojiList" />

  <Card title="首页推荐笔记列表" href="/docs/v7/usage/api/http/xiaohongshu/homeFeed" />

  <Card title="直播间信息" href="/docs/v7/usage/api/http/xiaohongshu/liveRoom" />

  <Card title="直播广场" href="/docs/v7/usage/api/http/xiaohongshu/liveSquare" />

  <Card title="直播状态" href="/docs/v7/usage/api/http/xiaohongshu/liveStatus" />

  <Card title="笔记评论列表" href="/docs/v7/usage/api/http/xiaohongshu/noteComments" />

  <Card title="笔记详细信息" href="/docs/v7/usage/api/http/xiaohongshu/noteDetail" />

  <Card title="搜索热榜" href="/docs/v7/usage/api/http/xiaohongshu/searchHotList" />

  <Card title="笔记搜索结果列表" href="/docs/v7/usage/api/http/xiaohongshu/searchNotes" />

  <Card title="搜索用户结果列表" href="/docs/v7/usage/api/http/xiaohongshu/searchUser" />

  <Card title="子评论（楼中楼）列表" href="/docs/v7/usage/api/http/xiaohongshu/subComments" />

  <Card title="用户笔记列表" href="/docs/v7/usage/api/http/xiaohongshu/userNoteList" />

  <Card title="用户主页信息" href="/docs/v7/usage/api/http/xiaohongshu/userProfile" />
</Cards>


# 评论回复列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/commentReplies)

> 取一条根评论下的回复。`rootCommentId` 取评论列表里 `hasSubComments` 为真的那条评论 ID。走 PC GraphQL，自带 PC 上下文 cookie 并对首发风控自动重试；有浏览器里的真实 `did` 时经 `cookies.kuaishou` 传入更稳。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/commentReplies（规范源：packages/core/openapi.json）

取一条根评论下的回复。`rootCommentId` 取评论列表里 `hasSubComments` 为真的那条评论 ID。走 PC GraphQL，自带 PC 上下文 cookie 并对首发风控自动重试；有浏览器里的真实 `did` 时经 `cookies.kuaishou` 传入更稳。

# 作品评论列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/comments)

> 取作品评论列表，子评论按根评论 ID 分组返回。`number` 指定目标条数，翻页自动完成。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/comments（规范源：packages/core/openapi.json）

取作品评论列表，子评论按根评论 ID 分组返回。`number` 指定目标条数，翻页自动完成。

# 作品弹幕列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/danmakuList)

> 取作品弹幕列表。可按时间段取（`from` / `to`），不传时间段就取全量。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/danmakuList（规范源：packages/core/openapi.json）

取作品弹幕列表。可按时间段取（`from` / `to`），不传时间段就取全量。

# 表情列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/emojiList)

> 取快手内置表情列表，无参数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/emojiList（规范源：packages/core/openapi.json）

取快手内置表情列表，无参数。

# 表情包列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/emotionPackageList)

> 取快手表情包列表（含包元数据与包内每条表情），无参数。只要表情图标地址时用 `emojiList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/emotionPackageList（规范源：packages/core/openapi.json）

取快手表情包列表（含包元数据与包内每条表情），无参数。只要表情图标地址时用 `emojiList`。

# 直播间聚合信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/liveRoomInfo)

> 取直播间聚合信息（直播流、主播、公告等）；只看直播间时比 `userProfile` 轻。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/liveRoomInfo（规范源：packages/core/openapi.json）

取直播间聚合信息（直播流、主播、公告等）；只看直播间时比 `userProfile` 轻。

# 当前登录账号资料 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/loginUserProfile)

> 取当前 cookie 所属账号的资料，不接参数。需要登录态 cookie。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/loginUserProfile（规范源：packages/core/openapi.json）

取当前 cookie 所属账号的资料，不接参数。需要登录态 cookie。

# 搜索用户 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/searchUser)

> 按关键词搜索用户，自动翻页。需要浏览器注册后的 cookie，支持游客。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/searchUser（规范源：packages/core/openapi.json）

按关键词搜索用户，自动翻页。需要浏览器注册后的 cookie，支持游客。

# 搜索作品 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/searchWorkList)

> 按关键词搜索作品，自动翻页。需要浏览器注册后的 cookie，支持游客。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/searchWorkList（规范源：packages/core/openapi.json）

按关键词搜索作品，自动翻页。需要浏览器注册后的 cookie，支持游客。

# 作品相关推荐 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/slideFeed)

> 取某个作品的相关推荐列表。`authorId` 传作者的数字 ID（`videoWork` 响应里的 `photo.userId`）。返回的列表混有推荐卡片，读作品字段前需先判别。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/slideFeed（规范源：packages/core/openapi.json）

取某个作品的相关推荐列表。`authorId` 传作者的数字 ID（`videoWork` 响应里的 `photo.userId`）。返回的列表混有推荐卡片，读作品字段前需先判别。

# 用户主页聚合信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/userProfile)

> 取用户主页聚合信息（资料、作品列表、直播间等）。部分数据取不到时留空，不整体失败。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/userProfile（规范源：packages/core/openapi.json）

取用户主页聚合信息（资料、作品列表、直播间等）。部分数据取不到时留空，不整体失败。

# 用户公开作品列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/userWorkList)

> 取用户公开作品列表。`number` 指定目标条数，翻页由端点自动完成，不用传游标。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/userWorkList（规范源：packages/core/openapi.json）

取用户公开作品列表。`number` 指定目标条数，翻页由端点自动完成，不用传游标。

# 单个作品详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/videoWork)

> 取快手作品详情。要图集预渲染地址等完整版字段时用 `videoWorkFull`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/videoWork（规范源：packages/core/openapi.json）

取快手作品详情。要图集预渲染地址等完整版字段时用 `videoWorkFull`。

# 单个作品详细信息（完整版，当前稳定撞风控） (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/kuaishou/videoWorkFull)

> 日常取作品信息请用 `videoWork`；这条是唯一可能返回图集预渲染地址与同类推荐的通道。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/kuaishou/videoWorkFull（规范源：packages/core/openapi.json）

日常取作品信息请用 `videoWork`；这条是唯一可能返回图集预渲染地址与同类推荐的通道。

# 表情列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/emojiList)

> 取小红书表情列表，无参数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/emojiList（规范源：packages/core/openapi.json）

取小红书表情列表，无参数。

# 首页推荐笔记列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/homeFeed)

> 取首页推荐流笔记。翻页要手动：把上一页响应的 `cursor_score` 传回来。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/homeFeed（规范源：packages/core/openapi.json）

取首页推荐流笔记。翻页要手动：把上一页响应的 `cursor_score` 传回来。

# 直播间信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/liveRoom)

> 取指定直播间的当前信息。variant=h5 走 h5 接口，否则走 web；web 端请提供 request_user_id 或含 userId 的 Cookie。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/liveRoom（规范源：packages/core/openapi.json）

取指定直播间的当前信息。variant=h5 走 h5 接口，否则走 web；web 端请提供 request_user_id 或含 userId 的 Cookie。

# 直播广场 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/liveSquare)

> 取直播广场推荐列表，参数均可选。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/liveSquare（规范源：packages/core/openapi.json）

取直播广场推荐列表，参数均可选。

# 直播状态 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/liveStatus)

> 轮询指定直播间是否在播，返回体极小。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/liveStatus（规范源：packages/core/openapi.json）

轮询指定直播间是否在播，返回体极小。

# 笔记评论列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/noteComments)

> 取笔记评论列表。`number` 指定目标条数，翻页由端点自动完成。**游客身份下平台对本接口限流较紧**：超限回 HTTP 461（伪装成成功的空壳），退避需分钟级、秒级无效；而且**不传 `number` 会触发翻页、多烧一次请求** —— 传具体小值可把请求数降到 1。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/noteComments（规范源：packages/core/openapi.json）

取笔记评论列表。`number` 指定目标条数，翻页由端点自动完成。**游客身份下平台对本接口限流较紧**：超限回 HTTP 461（伪装成成功的空壳），退避需分钟级、秒级无效；而且**不传 `number` 会触发翻页、多烧一次请求** —— 传具体小值可把请求数降到 1。

# 笔记详细信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/noteDetail)

> 取笔记正文与互动数据。要评论区用 `noteComments`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/noteDetail（规范源：packages/core/openapi.json）

取笔记正文与互动数据。要评论区用 `noteComments`。

# 搜索热榜 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/searchHotList)

> 取小红书当前搜索热榜，无参数。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/searchHotList（规范源：packages/core/openapi.json）

取小红书当前搜索热榜，无参数。

# 笔记搜索结果列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/searchNotes)

> 按关键词搜笔记。翻页手动传 `page`，并复用相同的 `search_id` / `session_id`；可指定排序和笔记类型。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/searchNotes（规范源：packages/core/openapi.json）

按关键词搜笔记。翻页手动传 `page`，并复用相同的 `search_id` / `session_id`；可指定排序和笔记类型。

# 搜索用户结果列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/searchUser)

> 按关键词或小红书号搜用户，返回 user_id 等。翻页手动传 `page`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/searchUser（规范源：packages/core/openapi.json）

按关键词或小红书号搜用户，返回 user_id 等。翻页手动传 `page`。

# 子评论（楼中楼）列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/subComments)

> 展开某条一级评论下的回复。`number` 指定目标条数，翻页自动完成。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/subComments（规范源：packages/core/openapi.json）

展开某条一级评论下的回复。`number` 指定目标条数，翻页自动完成。

# 用户笔记列表 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/userNoteList)

> 取用户的笔记列表。翻页要手动：`cursor` 传上一页最后一条的 ID。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/userNoteList（规范源：packages/core/openapi.json）

取用户的笔记列表。翻页要手动：`cursor` 传上一页最后一条的 ID。

# 用户主页信息 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/http/xiaohongshu/userProfile)

> 取用户主页的资料与统计。笔记列表见 `userNoteList`。

GET HTTP 端点。参数、响应与在线调用见 /docs/v7/usage/api/http/xiaohongshu/userProfile（规范源：packages/core/openapi.json）

取用户主页的资料与统计。笔记列表见 `userNoteList`。

# B站 SDK 方法 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/sdk/bilibili)

> B站平台的 27 个 SDK 方法，由端点注册表派生



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

<Callout type="info">
  本页 27 个方法由端点注册表生成：参数表、摘要与废弃标记都取自
  端点声明。同一批端点的 **HTTP 形态**（路径、query 参数、响应信封、在线调用）见
  [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 上的**绑定 Fetcher** 是 `client.<平台>.fetcher.<方法>(options, requestConfig?)`：cookie 已随 Client 绑好，第二个参数只作用于当前这一次调用，并与 Client 的实例级请求配置合并 —— 单次配置优先，`headers` 单独合并。

直接导出的**裸 Fetcher** 是 `<平台>Fetcher.<方法>(options, cookie?, requestConfig?)`：没有实例级配置，cookie 按次传，第三个参数直接作用于当前请求。`amagi.<平台>Fetcher` 与同名的命名导出（`import { bilibiliFetcher } from '@ikenxuan/amagi'`）是同一个对象。

两种形态都由端点注册表派生、走同一条执行管线、返回同一种信封，所以本页列出的方法名与参数对两者都成立。

### 用 `Cookie` 头覆盖单次调用的 cookie [#用-cookie-头覆盖单次调用的-cookie]

`requestConfig.headers` 里**任意大小写**的 `Cookie`（`Cookie` / `cookie` / `COOKIE`）都会替换本次调用实际使用的 cookie：绑定形态覆盖 Client 上绑定的那份，裸 Fetcher 形态覆盖第二个参数。这次调用用哪份 Cookie，只写这一处就够。

匿名调一次：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=xxx' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchComments(
  { oid: '170001', type: 1, number: 20 },
  { headers: { Cookie: '' } }
)
```

它只影响这一次请求，不改 Client 实例，也不影响同一实例后续的调用。

<Callout type="info">
  v7 的 `Cookie` 头按大小写不敏感匹配，覆盖只写在 `headers` 一处即可。
</Callout>

## 读取返回值：取 `data` [#读取返回值取-data]

方法永不抛异常，返回的是信封：成功支有 `data`，失败支有 `error`，两支都有 `message` 与 `meta`，顶层没有 `code`。本页所有示例统一用 `if (result.success)` 收窄之后再读 `result.data` —— 四种读法里只有它既不必额外 import，收窄后的 `data` 又不带 `| undefined`：

| 读法                       | 拿到的 `data`                  |
| ------------------------ | --------------------------- |
| `if (result.success)`    | `T`（本页示例统一用这种）              |
| 直接读 `result.data`（不收窄）   | `T \| undefined`            |
| `list.filter(isSuccess)` | `T`（数组回调里没有 `if` 可用）        |
| `unwrap(result)`         | `T`，失败时抛 `AmagiThrownError` |

四种读法的完整说明、失败分支的字段与三条逃生舱见[响应类型](/docs/v7/usage/guide/type-mode)。

### 大整数 ID 与响应类型 [#大整数-id-与响应类型]

默认 JSON 解析会把超出 JavaScript 安全整数范围的裸整数保留为十进制字符串，防止直播间、作品等 ID 被四舍五入。普通安全整数、浮点数和指数写法保持原样；显式文本响应和自定义 `transformResponse` 仍由调用方控制。响应 ID 的类型因此可能是 `string | number`，需要统一存储时可用 `String(id)`；不要先调用 `Number()` 再拼接请求。

新增端点只声明已有证据支持的响应字段；缺少完整成功响应样本的字段使用 `unknown`，使用前应检查对象、数组或字符串等实际结构。

## 本页之外：自定义请求 [#本页之外自定义请求-1]

本页是已收录的端点方法。要请求 amagi 尚未收录的 B站接口，用 `client.bilibili.request`。它的默认签名器是**不签**（27 条端点里只有 5 条签名，默认签会大面积签错），要签就显式给 `sign: 'wbi'` 或 `'qtparam'`。URL 由 `client.bilibili.apiUrls` 构造 —— 那份**以 URL 字符串为主**（只有两个验证码接口返回 `{ Url, Body }`）：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: 'SESSDATA=xxx' } })
// ---cut---
const url = client.bilibili.apiUrls.getVideoInfo({ bvid: 'BV1xx411c7mD' })
const r = await client.bilibili.request.get(url)
```

详见[自定义请求](/docs/v7/usage/advanced/custom-request)。

## Fetcher 方法 [#fetcher-方法]

### fetchVideoInfo [#fetchvideoinfo]

视频作品详细信息。端点 `bilibili.videoInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/videoInfo)。

取稿件详情（标题、封面、UP 主、统计、分 P 列表）；返回的 `cid` 供取流与弹幕使用。

| 参数     | 类型       | 必填 | 说明                       |
| ------ | -------- | -- | ------------------------ |
| `bvid` | `string` | 是  | 稿件 BV 号，如 `BV1xx411c7mD` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchVideoStreamUrl [#fetchvideostreamurl]

视频下载流信息。端点 `bilibili.videoStream`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/videoStream)。

取稿件的播放与下载流地址；高清档位需要带登录凭证，`cid` 来自 `videoInfo`。

| 参数     | 类型       | 必填 | 说明                    |
| ------ | -------- | -- | --------------------- |
| `avid` | `number` | 是  | 稿件 AV 号，纯数字不带 `av` 前缀 |
| `cid`  | `number` | 是  | 稿件 cid（分 P 的视频流 ID）   |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoStreamUrl({
  avid: 170001,
  cid: 279786
})

if (result.success) {
  console.log(result.data)
}
```

### fetchVideoDanmaku [#fetchvideodanmaku]

视频实时弹幕列表。端点 `bilibili.videoDanmaku`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/videoDanmaku)。

取视频某一段的实时弹幕；每段 6 分钟，按 `segment_index` 分段取全量。

| 参数              | 类型       | 必填 | 默认值 | 说明                   |
| --------------- | -------- | -- | --- | -------------------- |
| `cid`           | `number` | 是  | —   | 稿件 cid               |
| `segment_index` | `number` | 否  | `1` | 弹幕分段序号，每 6 分钟一段，默认 1 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoDanmaku({
  cid: 279786
})

if (result.success) {
  console.log(result.data)
}
```

### fetchComments [#fetchcomments]

作品评论列表。端点 `bilibili.comments`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/comments)。

取作品评论列表，按 `number` 自动翻页并去重；楼中楼用 `commentReplies`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 100 条，游标的带入与停止条件由端点声明处理。

| 参数             | 类型       | 必填 | 默认值  | 说明                                                                                                                       |
| -------------- | -------- | -- | ---- | ------------------------------------------------------------------------------------------------------------------------ |
| `oid`          | `string` | 是  | —    | 目标对象 ID，视频稿件填 avid                                                                                                       |
| `type`         | `number` | 是  | —    | 评论区类型代码：1 视频稿件（oid=avid）、2 话题、11 相簿/图片动态、12 专栏（cvid）、14 音频（auid）、17 动态、33 课程（epid）等；完整对照表见 bilibili-API-collect「评论区类型代码」 |
| `number`       | `number` | 否  | `20` | 目标条数，自动翻页合并后去重，默认 20                                                                                                     |
| `mode`         | `number` | 否  | —    | 排序方式：0 和 3 仅热度，1 按热度+按时间，2 仅时间；默认 3                                                                                      |
| `plat`         | `number` | 否  | —    | 平台类型，默认 1                                                                                                                |
| `seek_rpid`    | `string` | 否  | —    | 定位到某条评论，默认空                                                                                                              |
| `web_location` | `string` | 否  | —    | web 位置参数，默认 1315875                                                                                                      |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchComments({
  oid: '170001',
  type: 1
})

if (result.success) {
  console.log(result.data)
}
```

`type` 是评论区类型：1=视频、11=图文动态、12=专栏、14=音频、17=文字动态；端点声明只接受 v6 的那批取值（1、2、4–22、33），其余直接判参数校验失败。

### fetchCommentReplies [#fetchcommentreplies]

指定评论的回复列表。端点 `bilibili.commentReplies`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/commentReplies)。

取单条根评论下的楼中楼回复；整个评论区的列表用 `comments`。

| 参数       | 类型       | 必填 | 默认值  | 说明                                                                                          |
| -------- | -------- | -- | ---- | ------------------------------------------------------------------------------------------- |
| `oid`    | `string` | 是  | —    | 目标对象 ID，视频稿件填 avid                                                                          |
| `type`   | `number` | 是  | —    | 评论区类型代码：1 视频稿件（oid=avid）、11 相簿/图片动态、12 专栏（cvid）、17 动态等；完整对照表见 bilibili-API-collect「评论区类型代码」 |
| `root`   | `string` | 是  | —    | 根评论 ID，即要展开的一级评论                                                                            |
| `number` | `number` | 否  | `20` | 该根评论下的回复条数，不翻页，默认 20                                                                        |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchCommentReplies({
  oid: '170001',
  type: 1,
  root: '123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserCard [#fetchusercard]

用户名片信息。端点 `bilibili.userCard`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/userCard)。

取用户名片（昵称、头像、个性签名、等级、认证）与粉丝、投稿数统计。

| 参数         | 类型       | 必填 | 说明       |
| ---------- | -------- | -- | -------- |
| `host_mid` | `number` | 是  | UP 主 UID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchUserCard({
  host_mid: 123456
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserDynamicList [#fetchuserdynamiclist]

用户空间动态列表。端点 `bilibili.userDynamicList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/userDynamicList)。

取用户空间的第一页动态列表；本接口不支持翻页。

| 参数         | 类型       | 必填 | 说明       |
| ---------- | -------- | -- | -------- |
| `host_mid` | `number` | 是  | UP 主 UID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchUserDynamicList({
  host_mid: 123456
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserLiveStatus [#fetchuserlivestatus]

用户直播状态与直播间基础信息。端点 `bilibili.userLiveStatus`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/userLiveStatus)。

按 UID 查用户的直播状态与直播间信息；已有房间号时用 `liveRoomInfo`。

| 参数         | 类型       | 必填 | 说明       |
| ---------- | -------- | -- | -------- |
| `host_mid` | `number` | 是  | UP 主 UID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchUserLiveStatus({
  host_mid: 123456
})

if (result.success) {
  console.log(result.data)
}
```

直接读直播状态，不依赖用户空间动态里的直播推荐卡片，适合轮询开播状态。返回里主要看这几个字段：

| 字段           | 说明                  |
| ------------ | ------------------- |
| `roomStatus` | `1` 已开通直播间，`0` 未开通  |
| `liveStatus` | `1` 正在直播，`0` 当前未开播  |
| `roomid`     | 直播间 ID；未开通直播间时为 `0` |
| `title`      | 直播间标题               |
| `cover`      | 直播封面                |

### fetchUserSpaceInfo [#fetchuserspaceinfo]

用户空间详细信息。端点 `bilibili.userSpaceInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/userSpaceInfo)。

取用户空间完整资料（等级、硬币、VIP、粉丝勋章等）；名片类信息用 `userCard`。

| 参数         | 类型       | 必填 | 说明       |
| ---------- | -------- | -- | -------- |
| `host_mid` | `number` | 是  | UP 主 UID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchUserSpaceInfo({
  host_mid: 123456
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUploaderTotalViews [#fetchuploadertotalviews]

UP 主总播放量。端点 `bilibili.uploaderTotalViews`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/uploaderTotalViews)。

取 UP 主的播放与获赞统计；等级、VIP 等完整资料用 `userSpaceInfo`。

| 参数         | 类型       | 必填 | 说明       |
| ---------- | -------- | -- | -------- |
| `host_mid` | `number` | 是  | UP 主 UID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchUploaderTotalViews({
  host_mid: 123456
})

if (result.success) {
  console.log(result.data)
}
```

### fetchDynamicDetail [#fetchdynamicdetail]

动态详情。端点 `bilibili.dynamicDetail`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/dynamicDetail)。

按动态 ID 取详情，返回结构随动态类型（图文 / 转发 / 视频等）而变。

| 参数           | 类型       | 必填 | 说明         |
| ------------ | -------- | -- | ---------- |
| `dynamic_id` | `string` | 是  | 动态 ID，纯数字串 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchDynamicDetail({
  dynamic_id: '123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchBangumiInfo [#fetchbangumiinfo]

番剧基本信息。端点 `bilibili.bangumiInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/bangumiInfo)。

取番剧季度或单集的基本信息；两个 ID 至少传一个，都传时以 `ep_id` 为准。

| 参数          | 类型       | 必填 | 说明                     |
| ----------- | -------- | -- | ---------------------- |
| `ep_id`     | `string` | 否  | 剧集 EP ID，如 `ep330798`  |
| `season_id` | `string` | 否  | 番剧季度 SS ID，如 `ss33802` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchBangumiInfo({
  ep_id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

`ep_id` 与 `season_id` **二选一**：两个都是可选参数，但端点声明的 `refine` 要求至少给一个（都不给会以参数校验失败返回）。ID 带不带 `ep` / `ss` 前缀都行，`build` 会削掉。

### fetchBangumiStreamUrl [#fetchbangumistreamurl]

番剧下载流信息。端点 `bilibili.bangumiStream`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/bangumiStream)。

取番剧剧集的播放与下载流地址；高清档位需要带登录凭证。

| 参数      | 类型       | 必填 | 说明                    |
| ------- | -------- | -- | --------------------- |
| `cid`   | `number` | 是  | 剧集分集的 cid             |
| `ep_id` | `string` | 是  | 剧集 EP ID，如 `ep330798` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchBangumiStreamUrl({
  cid: 279786,
  ep_id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchLiveRoomInfo [#fetchliveroominfo]

直播间信息。端点 `bilibili.liveRoomInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/liveRoomInfo)。

取直播间的展示信息（标题、封面、分区等）；房间标识与开播状态用 `liveRoomInit`。

| 参数        | 类型       | 必填 | 说明     |
| --------- | -------- | -- | ------ |
| `room_id` | `string` | 是  | 直播间 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchLiveRoomInfo({
  room_id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchLiveRoomInitInfo [#fetchliveroominitinfo]

直播间初始化信息。端点 `bilibili.liveRoomInit`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/liveRoomInit)。

取房间的标识与开播状态；标题、封面等展示信息用 `liveRoomInfo`。

| 参数        | 类型       | 必填 | 说明     |
| --------- | -------- | -- | ------ |
| `room_id` | `string` | 是  | 直播间 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchLiveRoomInitInfo({
  room_id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchArticleContent [#fetcharticlecontent]

专栏正文内容。端点 `bilibili.articleContent`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/articleContent)。

取专栏正文；标题、作者、阅读统计等元信息用 `articleInfo`。

| 参数   | 类型       | 必填 | 说明           |
| ---- | -------- | -- | ------------ |
| `id` | `string` | 是  | 专栏 ID，取自专栏链接 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchArticleContent({
  id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchArticleCards [#fetcharticlecards]

专栏显示卡片信息。端点 `bilibili.articleCards`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/articleCards)。

一次可批量查询多条，支持视频、专栏、直播间的 ID 混传，结果按 ID 分组返回。

| 参数    | 类型                   | 必填 | 说明                 |
| ----- | -------------------- | -- | ------------------ |
| `ids` | `string[] \| string` | 是  | ID 列表，可混传视频、专栏、直播间 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchArticleCards({
  ids: ['123456', '789012']
})

if (result.success) {
  console.log(result.data)
}
```

### fetchArticleInfo [#fetcharticleinfo]

专栏文章基本信息。端点 `bilibili.articleInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/articleInfo)。

取文章页元信息（标题、头图、作者、阅读/点赞）；正文用 `articleContent`。

| 参数   | 类型       | 必填 | 说明           |
| ---- | -------- | -- | ------------ |
| `id` | `string` | 是  | 专栏 ID，取自专栏链接 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchArticleInfo({
  id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchArticleListInfo [#fetcharticlelistinfo]

文集基本信息。端点 `bilibili.articleListInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/articleListInfo)。

取文集（`rlid`）本体与其中的文章清单；单篇专栏用 `articleInfo`。

| 参数   | 类型       | 必填 | 说明                   |
| ---- | -------- | -- | -------------------- |
| `id` | `string` | 是  | 文集 ID（`rlid`），取自文集链接 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchArticleListInfo({
  id: '123456'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchLoginStatus [#fetchloginstatus]

登录基本信息。端点 `bilibili.loginStatus`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/loginStatus)。

取当前账号的登录信息，可用来判断登录凭证是否还有效。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchLoginStatus({})

if (result.success) {
  console.log(result.data)
}
```

### requestLoginQrcode [#requestloginqrcode]

登录二维码。端点 `bilibili.loginQrcode`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/loginQrcode)。

扫码登录第一步：返回二维码内容与轮询凭据 `qrcode_key`。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.requestLoginQrcode({})

if (result.success) {
  console.log(result.data)
}
```

### checkQrcodeStatus [#checkqrcodestatus]

二维码扫码状态。端点 `bilibili.qrcodeStatus`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/qrcodeStatus)。

轮询扫码进度；登录成功时新登录态只在响应头，本接口不透出响应头。

| 参数           | 类型       | 必填 | 说明                       |
| ------------ | -------- | -- | ------------------------ |
| `qrcode_key` | `string` | 是  | 二维码 key，取自 `loginQrcode` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.checkQrcodeStatus({
  qrcode_key: 'xxx'
})

if (result.success) {
  console.log(result.data)
}
```

### requestCaptchaFromVoucher [#requestcaptchafromvoucher]

由 v\_voucher 申请的验证码信息。端点 `bilibili.captchaFromVoucher`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/captchaFromVoucher)。

人机校验第一步：用 `v_voucher` 换取验证码与校验参数。

| 参数          | 类型       | 必填 | 说明                       |
| ----------- | -------- | -- | ------------------------ |
| `csrf`      | `string` | 否  | CSRF Token，取 `bili_jct`  |
| `v_voucher` | `string` | 是  | 风控下发的凭证，形如 `voucher_xxx` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.requestCaptchaFromVoucher({
  v_voucher: 'voucher_xxx'
})

if (result.success) {
  console.log(result.data)
}
```

### validateCaptchaResult [#validatecaptcharesult]

验证码校验结果。端点 `bilibili.validateCaptcha`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/validateCaptcha)。

人机校验第二步：提交 `challenge` / `token` 与用户过完验证的结果。

| 参数          | 类型       | 必填 | 说明                      |
| ----------- | -------- | -- | ----------------------- |
| `csrf`      | `string` | 否  | CSRF Token，取 `bili_jct` |
| `challenge` | `string` | 是  | 极验 challenge，第一步返回      |
| `token`     | `string` | 是  | 极验 token，第一步返回          |
| `validate`  | `string` | 是  | 人机验证通过后回填               |
| `seccode`   | `string` | 是  | 人机验证通过后回填的校验串           |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.validateCaptchaResult({
  challenge: 'challenge_xxx',
  token: 'token_xxx',
  validate: 'validate_xxx',
  seccode: 'validate_xxx|jordan'
})

if (result.success) {
  console.log(result.data)
}
```

### convertAvToBv [#convertavtobv]

AV 号转换得到的 BV 号。端点 `bilibili.avToBv`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/avToBv)。

把稿件 AV 号换算成 BV 号，本地计算不发请求，返回 `{ bvid }`。

纯本地计算，不发请求。

| 参数     | 类型       | 必填 | 说明                    |
| ------ | -------- | -- | --------------------- |
| `avid` | `number` | 是  | 稿件 AV 号，纯数字不带 `av` 前缀 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.convertAvToBv({
  avid: 170001
})

if (result.success) {
  console.log(result.data)
}
```

### convertBvToAv [#convertbvtoav]

BV 号转换得到的 AV 号。端点 `bilibili.bvToAv`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/bvToAv)。

把稿件 BV 号换算成 AV 号，本地计算不发请求，返回 `{ aid }`。

纯本地计算，不发请求。

| 参数     | 类型       | 必填 | 说明                       |
| ------ | -------- | -- | ------------------------ |
| `bvid` | `string` | 是  | 稿件 BV 号，如 `BV1xx411c7mD` |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.convertBvToAv({
  bvid: 'BV1xx411c7mD'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchEmojiList [#fetchemojilist]

表情列表。端点 `bilibili.emojiList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/bilibili/emojiList)。

取评论区表情面板里的全部表情，无参数。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchEmojiList({})

if (result.success) {
  console.log(result.data)
}
```


# 抖音 SDK 方法 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/sdk/douyin)

> 抖音平台的 26 个 SDK 方法，由端点注册表派生



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

<Callout type="info">
  本页 26 个方法由端点注册表生成：参数表、摘要与废弃标记都取自
  端点声明。同一批端点的 **HTTP 形态**（路径、query 参数、响应信封、在线调用）见
  [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 上的**绑定 Fetcher** 是 `client.<平台>.fetcher.<方法>(options, requestConfig?)`：cookie 已随 Client 绑好，第二个参数只作用于当前这一次调用，并与 Client 的实例级请求配置合并 —— 单次配置优先，`headers` 单独合并。

直接导出的**裸 Fetcher** 是 `<平台>Fetcher.<方法>(options, cookie?, requestConfig?)`：没有实例级配置，cookie 按次传，第三个参数直接作用于当前请求。`amagi.<平台>Fetcher` 与同名的命名导出（`import { bilibiliFetcher } from '@ikenxuan/amagi'`）是同一个对象。

两种形态都由端点注册表派生、走同一条执行管线、返回同一种信封，所以本页列出的方法名与参数对两者都成立。

### 用 `Cookie` 头覆盖单次调用的 cookie [#用-cookie-头覆盖单次调用的-cookie]

`requestConfig.headers` 里**任意大小写**的 `Cookie`（`Cookie` / `cookie` / `COOKIE`）都会替换本次调用实际使用的 cookie：绑定形态覆盖 Client 上绑定的那份，裸 Fetcher 形态覆盖第二个参数。这次调用用哪份 Cookie，只写这一处就够。

匿名调一次：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: 'ttwid=xxx' } })
// ---cut---
const result = await client.douyin.fetcher.fetchVideoWork(
  { aweme_id: '7123456789' },
  { headers: { Cookie: '' } }
)
```

它只影响这一次请求，不改 Client 实例，也不影响同一实例后续的调用。

<Callout type="info">
  v7 的 `Cookie` 头按大小写不敏感匹配，覆盖只写在 `headers` 一处即可。
</Callout>

## 读取返回值：取 `data` [#读取返回值取-data]

方法永不抛异常，返回的是信封：成功支有 `data`，失败支有 `error`，两支都有 `message` 与 `meta`，顶层没有 `code`。本页所有示例统一用 `if (result.success)` 收窄之后再读 `result.data` —— 四种读法里只有它既不必额外 import，收窄后的 `data` 又不带 `| undefined`：

| 读法                       | 拿到的 `data`                  |
| ------------------------ | --------------------------- |
| `if (result.success)`    | `T`（本页示例统一用这种）              |
| 直接读 `result.data`（不收窄）   | `T \| undefined`            |
| `list.filter(isSuccess)` | `T`（数组回调里没有 `if` 可用）        |
| `unwrap(result)`         | `T`，失败时抛 `AmagiThrownError` |

四种读法的完整说明、失败分支的字段与三条逃生舱见[响应类型](/docs/v7/usage/guide/type-mode)。

### 大整数 ID 与响应类型 [#大整数-id-与响应类型]

默认 JSON 解析会把超出 JavaScript 安全整数范围的裸整数保留为十进制字符串，防止直播间、作品等 ID 被四舍五入。普通安全整数、浮点数和指数写法保持原样；显式文本响应和自定义 `transformResponse` 仍由调用方控制。响应 ID 的类型因此可能是 `string | number`，需要统一存储时可用 `String(id)`；不要先调用 `Number()` 再拼接请求。

新增端点只声明已有证据支持的响应字段；缺少完整成功响应样本的字段使用 `unknown`，使用前应检查对象、数组或字符串等实际结构。

普通 Fetcher 只自动规范化 Cookie。登录态探测与游客凭据申请通过显式的 `douyinUtils.credentials` 工具调用；不会在普通请求中静默切换账号。工具参数、缓存和游客握手说明见[工具集](/docs/v7/usage/guide/utilities)。

## 本页之外：自定义请求 [#本页之外自定义请求-2]

本页是已收录的端点方法。要请求 amagi 尚未收录的抖音接口，用 `client.douyin.request`（默认签名器 `a-bogus`，自动带上实例 ck 并走同一套 judge / 重试 / 事件）。URL 由 `client.douyin.apiUrls` 构造 —— 抖音那份**全部返回 URL 字符串**：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: 'ttwid=xxx' } })
// ---cut---
const url = client.douyin.apiUrls.getWorkDetail({ aweme_id: '1234567890123456789' })
const r = await client.douyin.request.get(url)
```

详见[自定义请求](/docs/v7/usage/advanced/custom-request)。

## Fetcher 方法 [#fetcher-方法]

### parseWork [#parsework]

聚合解析作品数据（自动识别类型）。端点 `douyin.parseWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/parseWork)。

同一个作品 ID 可能是视频、图集、合辑、文字或文章，这条自动识别形态并返回对应结构。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.parseWork({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

推荐用 `parseWork`：它自动识别作品类型（视频 / 图集 / 合辑）并返回对应数据，不必先猜类型再挑方法。

### fetchVideoWork [#fetchvideowork]

视频作品详细信息。端点 `douyin.videoWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/videoWork)。

已知是视频作品时用这条；形态不确定时先用 `parseWork` 自动识别。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchVideoWork({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchImageAlbumWork [#fetchimagealbumwork]

图集作品详细信息。端点 `douyin.imageAlbumWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/imageAlbumWork)。

已知是图集作品时用这条；形态不确定时先用 `parseWork` 自动识别。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchImageAlbumWork({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchSlidesWork [#fetchslideswork]

合辑作品详细信息。端点 `douyin.slidesWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/slidesWork)。

已知是合辑（幻灯片/图文）时用这条；形态不确定时先用 `parseWork`。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchSlidesWork({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchTextWork [#fetchtextwork]

文字作品详细信息。端点 `douyin.textWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/textWork)。

已知是文字作品时用这条；形态不确定时先用 `parseWork` 自动识别。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `aweme_id` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchTextWork({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchWorkComments [#fetchworkcomments]

作品评论列表。端点 `douyin.comments`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/comments)。

作品的一级评论列表；某条评论下的回复用 `commentReplies`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 50 条，游标的带入与停止条件由端点声明处理。

| 参数         | 类型       | 必填 | 说明         |
| ---------- | -------- | -- | ---------- |
| `aweme_id` | `string` | 是  | 作品 ID      |
| `number`   | `number` | 否  | 目标条数，默认 50 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchWorkComments({
  aweme_id: '1234567890123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchCommentReplies [#fetchcommentreplies]

指定评论的回复列表。端点 `douyin.commentReplies`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/commentReplies)。

某条根评论下的回复列表，单页仅 3 条；整个评论区用 `comments`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 3 条，游标的带入与停止条件由端点声明处理。

| 参数           | 类型       | 必填 | 说明         |
| ------------ | -------- | -- | ---------- |
| `aweme_id`   | `string` | 是  | 作品 ID      |
| `comment_id` | `string` | 是  | 要取回复的评论 ID |
| `number`     | `number` | 否  | 目标条数，默认 3  |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchCommentReplies({
  aweme_id: '1234567890123456789',
  comment_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserProfile [#fetchuserprofile]

用户主页信息。端点 `douyin.userProfile`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/userProfile)。

只认 `sec_uid`；手里只有抖音号时先用 `guestUserInfo` 换。

| 参数        | 类型       | 必填 | 说明                  |
| --------- | -------- | -- | ------------------- |
| `sec_uid` | `string` | 是  | 用户 sec\_uid，主页链接里那段 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchUserProfile({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserVideoList [#fetchuservideolist]

用户主页作品列表。端点 `douyin.userVideoList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/userVideoList)。

该用户发布的作品列表；喜欢列表用 `userFavoriteList`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 18 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明                  |
| --------- | -------- | -- | ------------------- |
| `sec_uid` | `string` | 是  | 用户 sec\_uid，主页链接里那段 |
| `number`  | `number` | 否  | 目标条数，默认 18          |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchUserVideoList({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserFavoriteList [#fetchuserfavoritelist]

用户主页点赞作品列表。端点 `douyin.userFavoriteList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/userFavoriteList)。

该用户点赞过的作品列表；其发布的作品用 `userVideoList`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 18 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明                  |
| --------- | -------- | -- | ------------------- |
| `sec_uid` | `string` | 是  | 用户 sec\_uid，主页链接里那段 |
| `number`  | `number` | 否  | 目标条数，默认 18          |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchUserFavoriteList({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserRecommendList [#fetchuserrecommendlist]

用户主页推荐作品列表。端点 `douyin.userRecommendList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/userRecommendList)。

主页的推荐流作品，不保证是该用户发布的；自己的作品用 `userVideoList`。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 18 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明                  |
| --------- | -------- | -- | ------------------- |
| `sec_uid` | `string` | 是  | 用户 sec\_uid，主页链接里那段 |
| `number`  | `number` | 否  | 目标条数，默认 18          |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchUserRecommendList({
  sec_uid: 'MS4wLjABAAAAxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### searchContent [#searchcontent]

搜索结果列表（综合/用户/视频）。端点 `douyin.search`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/search)。

搜索结果的形态由 `type` 决定；响应里 `__search_type` 标出实际形态。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 15 条，游标的带入与停止条件由端点声明处理。

| 参数       | 类型                               | 必填 | 默认值         | 说明          |
| -------- | -------------------------------- | -- | ----------- | ----------- |
| `query`  | `string`                         | 是  | —           | 搜索关键词       |
| `type`   | `'general' \| 'user' \| 'video'` | 否  | `'general'` | 搜索类型，默认综合搜索 |
| `number` | `number`                         | 否  | —           | 目标条数，默认 15  |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.searchContent({
  query: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchSuggestWords [#fetchsuggestwords]

搜索联想词与热点词列表。端点 `douyin.suggestWords`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/suggestWords)。

按输入前缀返回候选词与热点词；不返回搜索结果，搜索用 `search`。

| 参数      | 类型       | 必填 | 说明          |
| ------- | -------- | -- | ----------- |
| `query` | `string` | 是  | 搜索关键词（输入前缀） |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchSuggestWords({
  query: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchShortUrl [#fetchshorturl]

分享链接转短链接。端点 `douyin.shortUrl`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/shortUrl)。

把抖音作品分享链接转换成 `v.douyin.com` 短链；`belong=aweme` 是能缩短的前提。

| 参数       | 类型       | 必填 | 默认值       | 说明                            |
| -------- | -------- | -- | --------- | ----------------------------- |
| `target` | `string` | 是  | —         | 需要缩短的分享链接                     |
| `belong` | `string` | 否  | `'aweme'` | 短链归属类型，抖音作品固定为 aweme，默认 aweme |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchShortUrl({
  target: 'https://v.douyin.com/xxxxxxx/'
})

if (result.success) {
  console.log(result.data)
}
```

`target` 是要缩短的分享链接，`belong` 默认 `aweme`（作品固定用它，缺失会被平台拒绝）。这条**不需要 cookie，但必须带签名** —— 与四条免鉴权端点不同，它没有免签退路。成功与失败都回 HTTP 200 + `code: 0`，所以要看 `reason`：`check failed` 表示签名没带或不对（`SIGNATURE_REFUSED`，换 cookie 无用），`not allowed to shorten` 表示 `belong` 不对。同一个 `target` 多次调用返回同一个短码，不是一次性令牌。

### fetchMusicInfo [#fetchmusicinfo]

音乐作品信息。端点 `douyin.musicInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/musicInfo)。

带 mp3 播放地址与使用量的音乐详情，个别原声不回播放地址时用 `musicAwemeList`；免鉴权版本用 `guestMusicInfo`。

| 参数         | 类型       | 必填 | 说明         |
| ---------- | -------- | -- | ---------- |
| `music_id` | `string` | 是  | 音乐 ID（mid） |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchMusicInfo({
  music_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchMusicAwemeList [#fetchmusicawemelist]

某条原声下的作品列表。端点 `douyin.musicAwemeList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/musicAwemeList)。

某条原声下的作品列表，只取一页；每条作品的 `music` 带 mp3 播放地址，`musicInfo` 没有时从这里取。

| 参数         | 类型       | 必填 | 说明         |
| ---------- | -------- | -- | ---------- |
| `music_id` | `string` | 是  | 原声 ID      |
| `number`   | `number` | 否  | 本页条数，默认 10 |
| `cursor`   | `number` | 否  | 翻页游标，默认 0  |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchMusicAwemeList({
  music_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchMixAweme [#fetchmixaweme]

合集作品列表。端点 `douyin.mixAweme`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/mixAweme)。

按 mix\_id 获取合集内的作品；mix\_id 取自作品详情 mix\_info.mix\_id，number 为目标条数。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 20 条，游标的带入与停止条件由端点声明处理。

| 参数       | 类型       | 必填 | 说明                             |
| -------- | -------- | -- | ------------------------------ |
| `mix_id` | `string` | 是  | 合集 ID，取自作品详情 mix\_info.mix\_id |
| `number` | `number` | 否  | 目标条数，默认 20                     |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchMixAweme({
  mix_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

`mix_id` 是合集 ID，不是单条作品的 `aweme_id`。v7 用 `number` 表示目标条数，内部每页最多请求 20 条，并按上游 `cursor` 自动翻页（游标由端点接管，不在调用方签名里）。聚合后的 `aweme_list` 包含本次收集到的作品，游标与其他元数据取最后一页。

### fetchLiveRoomInfo [#fetchliveroominfo]

直播间信息。端点 `douyin.liveRoomInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/liveRoomInfo)。

按直播间短号返回开播状态、标题与主播信息。

| 参数        | 类型       | 必填 | 说明           |
| --------- | -------- | -- | ------------ |
| `web_rid` | `string` | 是  | 直播间短号（链接里那段） |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchLiveRoomInfo({
  web_rid: '123456789'
})

if (result.success) {
  console.log(result.data)
}
```

### requestLoginQrcode [#requestloginqrcode]

登录二维码。端点 `douyin.loginQrcode`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/loginQrcode)。

创建登录二维码，返回二维码内容与票据；扫码后的登录状态不在这条。

| 参数          | 类型       | 必填 | 说明     |
| ----------- | -------- | -- | ------ |
| `verify_fp` | `string` | 是  | 设备验证指纹 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.requestLoginQrcode({
  verify_fp: 'verify_xxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchEmojiList [#fetchemojilist]

表情列表。端点 `douyin.emojiList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/emojiList)。

返回常规与限时/联名表情的清单；动态表情用 `dynamicEmojiList`。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchEmojiList({})

if (result.success) {
  console.log(result.data)
}
```

### fetchDynamicEmojiList [#fetchdynamicemojilist]

动态表情列表。端点 `douyin.dynamicEmojiList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/dynamicEmojiList)。

返回动态表情资源；常规表情列表用 `emojiList`。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchDynamicEmojiList({})

if (result.success) {
  console.log(result.data)
}
```

### fetchDanmakuList [#fetchdanmakulist]

作品弹幕列表。端点 `douyin.danmakuList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/danmakuList)。

取作品在给定时间区间内的弹幕；不给区间即全片，返回按时间排序。

| 参数           | 类型       | 必填 | 说明               |
| ------------ | -------- | -- | ---------------- |
| `aweme_id`   | `string` | 是  | 作品 ID            |
| `start_time` | `number` | 否  | 区间起点（毫秒），默认 0    |
| `end_time`   | `number` | 否  | 区间终点（毫秒），默认取总时长  |
| `duration`   | `number` | 是  | 作品总时长（毫秒），也是默认终点 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchDanmakuList({
  aweme_id: '1234567890123456789',
  duration: 60000
})

if (result.success) {
  console.log(result.data)
}
```

### fetchGuestUserInfo [#fetchguestuserinfo]

抖音号转用户信息（免鉴权）。端点 `douyin.guestUserInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/guestUserInfo)。

用抖音号精确换 `sec_uid`；抖音号不存在时返回失败。

| 参数          | 类型       | 必填 | 说明  |
| ----------- | -------- | -- | --- |
| `unique_id` | `string` | 是  | 抖音号 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchGuestUserInfo({
  unique_id: ''
})

if (result.success) {
  console.log(result.data)
}
```

### fetchGuestMusicInfo [#fetchguestmusicinfo]

原声本体（免鉴权）。端点 `douyin.guestMusicInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/guestMusicInfo)。

按原声 ID 返回原声详情；这条没有 mp3 播放地址，需要时用 `musicInfo`。

| 参数         | 类型       | 必填 | 说明    |
| ---------- | -------- | -- | ----- |
| `music_id` | `string` | 是  | 原声 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchGuestMusicInfo({
  music_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchGuestMusicAwemeList [#fetchguestmusicawemelist]

某条原声下的作品列表（免鉴权）。端点 `douyin.guestMusicAwemeList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/guestMusicAwemeList)。

某条原声下的作品列表，只取一页；只有 `aweme_id` 可用，详情走 `parseWork`。

| 参数         | 类型       | 必填 | 说明         |
| ---------- | -------- | -- | ---------- |
| `music_id` | `string` | 是  | 原声 ID      |
| `number`   | `number` | 否  | 本页条数，默认 10 |
| `cursor`   | `number` | 否  | 翻页游标，默认 0  |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchGuestMusicAwemeList({
  music_id: '7123456789012345678'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchEmojiResourceMeta [#fetchemojiresourcemeta]

表情资源包元信息（免鉴权）。端点 `douyin.emojiResourceMeta`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/douyin/emojiResourceMeta)。

返回表情资源包的版本与下载地址；下载与解包由调用方处理。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const result = await client.douyin.fetcher.fetchEmojiResourceMeta({})

if (result.success) {
  console.log(result.data)
}
```

## v6 的 passport 四方法 [#v6-的-passport-四方法]

`requestPassportQrcode` / `checkPassportQrcode` / `sendPassportVerifyCode` / `validatePassportVerifyCode` 仍在裸 Fetcher（`douyinFetcher`）上，且都标了 `@deprecated`。它们是**会话**而不是端点 —— 不在端点注册表里，也不在 `client.douyin.fetcher` 上，所以本页（由注册表派生）不列它们。

新代码请走 v7 的登录会话：`client.douyin.login.qrcode()` 新建一次扫码会话，`client.douyin.login.resume(blob)` 从 `serialize()` 的产物恢复；轮询、退避、超时、二次验证编排都由引擎负责，不用自己拼 passport 的取码与轮询。会话的每一步还会发到实例总线上（`session:state` / `session:success` / `session:error`），见[事件系统](/docs/v7/usage/advanced/events)与[项目架构](/docs/v7/dev/architecture)的「会话（登录）」一节。

<Callout type="warn">
  两条路径的事件总线不是同一条：passport 四方法写的是 **v6 全局单例**
  `amagiEvents`（`api:*` / `log:debug`），`client.douyin.login` 写的是**实例总线**
  `client.events`（`session:*`）。
</Callout>


# 快手 SDK 方法 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/sdk/kuaishou)

> 快手平台的 14 个 SDK 方法，由端点注册表派生



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

<Callout type="info">
  本页 14 个方法由端点注册表生成：参数表、摘要与废弃标记都取自
  端点声明。同一批端点的 **HTTP 形态**（路径、query 参数、响应信封、在线调用）见
  [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 上的**绑定 Fetcher** 是 `client.<平台>.fetcher.<方法>(options, requestConfig?)`：cookie 已随 Client 绑好，第二个参数只作用于当前这一次调用，并与 Client 的实例级请求配置合并 —— 单次配置优先，`headers` 单独合并。

直接导出的**裸 Fetcher** 是 `<平台>Fetcher.<方法>(options, cookie?, requestConfig?)`：没有实例级配置，cookie 按次传，第三个参数直接作用于当前请求。`amagi.<平台>Fetcher` 与同名的命名导出（`import { bilibiliFetcher } from '@ikenxuan/amagi'`）是同一个对象。

两种形态都由端点注册表派生、走同一条执行管线、返回同一种信封，所以本页列出的方法名与参数对两者都成立。

### 用 `Cookie` 头覆盖单次调用的 cookie [#用-cookie-头覆盖单次调用的-cookie]

`requestConfig.headers` 里**任意大小写**的 `Cookie`（`Cookie` / `cookie` / `COOKIE`）都会替换本次调用实际使用的 cookie：绑定形态覆盖 Client 上绑定的那份，裸 Fetcher 形态覆盖第二个参数。这次调用用哪份 Cookie，只写这一处就够。

匿名调一次：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: 'did=xxx' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchVideoWork(
  { photoId: '3x123456789' },
  { headers: { Cookie: '' } }
)
```

它只影响这一次请求，不改 Client 实例，也不影响同一实例后续的调用。

<Callout type="info">
  v7 的 `Cookie` 头按大小写不敏感匹配，覆盖只写在 `headers` 一处即可。
</Callout>

## 读取返回值：取 `data` [#读取返回值取-data]

方法永不抛异常，返回的是信封：成功支有 `data`，失败支有 `error`，两支都有 `message` 与 `meta`，顶层没有 `code`。本页所有示例统一用 `if (result.success)` 收窄之后再读 `result.data` —— 四种读法里只有它既不必额外 import，收窄后的 `data` 又不带 `| undefined`：

| 读法                       | 拿到的 `data`                  |
| ------------------------ | --------------------------- |
| `if (result.success)`    | `T`（本页示例统一用这种）              |
| 直接读 `result.data`（不收窄）   | `T \| undefined`            |
| `list.filter(isSuccess)` | `T`（数组回调里没有 `if` 可用）        |
| `unwrap(result)`         | `T`，失败时抛 `AmagiThrownError` |

四种读法的完整说明、失败分支的字段与三条逃生舱见[响应类型](/docs/v7/usage/guide/type-mode)。

### 大整数 ID 与响应类型 [#大整数-id-与响应类型]

默认 JSON 解析会把超出 JavaScript 安全整数范围的裸整数保留为十进制字符串，防止直播间、作品等 ID 被四舍五入。普通安全整数、浮点数和指数写法保持原样；显式文本响应和自定义 `transformResponse` 仍由调用方控制。响应 ID 的类型因此可能是 `string | number`，需要统一存储时可用 `String(id)`；不要先调用 `Number()` 再拼接请求。

新增端点只声明已有证据支持的响应字段；缺少完整成功响应样本的字段使用 `unknown`，使用前应检查对象、数组或字符串等实际结构。

## 本页之外：自定义请求 [#本页之外自定义请求-3]

本页是已收录的端点方法。要请求 amagi 尚未收录的快手接口，用 `client.kuaishou.request`（默认签名器 `hxfalcon`）。快手那份 `apiUrls` **返回的不是 URL 字符串**，而是请求描述对象，对应关系是 `url` → 第一参、`body` → `config.data`、`signPath` → `amagi.signPath`：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: 'did=xxx' } })
// ---cut---
// H5 那份（videoWork / videoWorkFull / comments）：requiresSign 是必填布尔
const d = client.kuaishou.apiUrls.videoWork({ photoId: '3xqxxxx' })
const r = await client.kuaishou.request.request({
  method: d.method,
  url: d.url,
  data: d.body,
  headers: { Referer: d.referer },
  amagi: { sign: d.requiresSign ? 'hxfalcon' : false, signPath: d.signPath }
})
```

**`live_api` 那批不能照抄这段**：它们的 `requiresSign` 是**可选**的（缺席不代表免签），也没有 `referer` 字段。要签就&#x2A;*不给 `sign`**（走平台默认 `'hxfalcon'`）或显式写 `'hxfalcon'`：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: 'did=xxx' } })
// ---cut---
const d = client.kuaishou.apiUrls.userInfoById({ principalId: 'KPL704668133' })
const r = await client.kuaishou.request.request({
  method: d.method,
  url: d.url,
  amagi: { signPath: d.signPath }
})
```

详见[自定义请求](/docs/v7/usage/advanced/custom-request)。

## Fetcher 方法 [#fetcher-方法]

### fetchVideoWork [#fetchvideowork]

单个作品详细信息。端点 `kuaishou.videoWork`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/videoWork)。

取快手作品详情。要图集预渲染地址等完整版字段时用 `videoWorkFull`。

| 参数        | 类型       | 必填 | 说明    |
| --------- | -------- | -- | ----- |
| `photoId` | `string` | 是  | 作品 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchVideoWork({
  photoId: '3xqxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchVideoWorkFull [#fetchvideoworkfull]

单个作品详细信息（完整版，当前稳定撞风控）。端点 `kuaishou.videoWorkFull`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/videoWorkFull)。

日常取作品信息请用 `videoWork`；这条是唯一可能返回图集预渲染地址与同类推荐的通道。

| 参数             | 类型       | 必填 | 说明                                                                            |
| -------------- | -------- | -- | ----------------------------------------------------------------------------- |
| `photoId`      | `string` | 是  | 作品 ID                                                                         |
| `captchaToken` | `string` | 否  | 滑块票据，进 query 参与签名；不给即空串。**过风控不需要它**：人过一次滑块整个 did 就解，原样重发即可。留它只为 query 形状与前端一致 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchVideoWorkFull({
  photoId: '3xqxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchWorkComments [#fetchworkcomments]

作品评论列表。端点 `kuaishou.comments`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/comments)。

取作品评论列表，子评论按根评论 ID 分组返回。`number` 指定目标条数，翻页自动完成。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 50 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明                        |
| --------- | -------- | -- | ------------------------- |
| `photoId` | `string` | 是  | 作品 ID                     |
| `number`  | `number` | 否  | 目标条数；不传时按单页上限翻页取满，而不是只取一页 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchWorkComments({
  photoId: '3xqxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchCommentReplies [#fetchcommentreplies]

评论回复列表。端点 `kuaishou.commentReplies`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/commentReplies)。

取一条根评论下的回复。`rootCommentId` 取评论列表里 `hasSubComments` 为真的那条评论 ID。走 PC GraphQL，自带 PC 上下文 cookie 并对首发风控自动重试；有浏览器里的真实 `did` 时经 `cookies.kuaishou` 传入更稳。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 50 条，游标的带入与停止条件由端点声明处理。

| 参数              | 类型       | 必填 | 说明        |
| --------------- | -------- | -- | --------- |
| `photoId`       | `string` | 是  | 作品 ID     |
| `rootCommentId` | `string` | 是  | 根评论 ID    |
| `number`        | `number` | 否  | 目标条数，默认一页 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchCommentReplies({
  photoId: '3xqxxxxxx',
  rootCommentId: ''
})

if (result.success) {
  console.log(result.data)
}
```

### fetchDanmakuList [#fetchdanmakulist]

作品弹幕列表。端点 `kuaishou.danmakuList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/danmakuList)。

取作品弹幕列表。可按时间段取（`from` / `to`），不传时间段就取全量。

| 参数         | 类型       | 必填 | 说明                       |
| ---------- | -------- | -- | ------------------------ |
| `photoId`  | `string` | 是  | 作品 ID                    |
| `from`     | `number` | 否  | 起始位置（毫秒），默认 0            |
| `to`       | `number` | 否  | 结束位置（毫秒）；不传则用 `duration` |
| `duration` | `number` | 否  | 作品时长（毫秒），取全量用            |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchDanmakuList({
  photoId: '3xqxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserProfile [#fetchuserprofile]

用户主页聚合信息。端点 `kuaishou.userProfile`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/userProfile)。

取用户主页聚合信息（资料、作品列表、直播间等）。部分数据取不到时留空，不整体失败。

| 参数            | 类型       | 必填 | 说明    |
| ------------- | -------- | -- | ----- |
| `principalId` | `string` | 是  | 用户 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchUserProfile({
  principalId: 'KPL704668133'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchUserWorkList [#fetchuserworklist]

用户公开作品列表。端点 `kuaishou.userWorkList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/userWorkList)。

取用户公开作品列表。`number` 指定目标条数，翻页由端点自动完成，不用传游标。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 12 条，游标的带入与停止条件由端点声明处理。

| 参数            | 类型       | 必填 | 说明         |
| ------------- | -------- | -- | ---------- |
| `principalId` | `string` | 是  | 用户 ID      |
| `number`      | `number` | 否  | 目标条数，默认 12 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchUserWorkList({
  principalId: 'KPL704668133'
})

if (result.success) {
  console.log(result.data)
}
```

v6 的 `count` / `pcursor` 已被 `number` + 声明式翻页取代：调用方只说明要多少条，`pcursor` 游标的带入与停止条件由端点声明的 `paginate` 处理。

### fetchLiveRoomInfo [#fetchliveroominfo]

直播间聚合信息。端点 `kuaishou.liveRoomInfo`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/liveRoomInfo)。

取直播间聚合信息（直播流、主播、公告等）；只看直播间时比 `userProfile` 轻。

| 参数            | 类型       | 必填 | 说明    |
| ------------- | -------- | -- | ----- |
| `principalId` | `string` | 是  | 用户 ID |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchLiveRoomInfo({
  principalId: 'KPL704668133'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchEmojiList [#fetchemojilist]

表情列表。端点 `kuaishou.emojiList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/emojiList)。

取快手内置表情列表，无参数。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchEmojiList({})

if (result.success) {
  console.log(result.data)
}
```

### fetchEmotionPackageList [#fetchemotionpackagelist]

表情包列表。端点 `kuaishou.emotionPackageList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/emotionPackageList)。

取快手表情包列表（含包元数据与包内每条表情），无参数。只要表情图标地址时用 `emojiList`。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchEmotionPackageList({})

if (result.success) {
  console.log(result.data)
}
```

### fetchSlideFeed [#fetchslidefeed]

作品相关推荐。端点 `kuaishou.slideFeed`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/slideFeed)。

取某个作品的相关推荐列表。`authorId` 传作者的数字 ID（`videoWork` 响应里的 `photo.userId`）。返回的列表混有推荐卡片，读作品字段前需先判别。

| 参数         | 类型                 | 必填 | 说明                           |
| ---------- | ------------------ | -- | ---------------------------- |
| `photoId`  | `string`           | 是  | 作品 ID                        |
| `authorId` | `number \| string` | 是  | 作者数字 ID，取自作品响应的 photo.userId |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchSlideFeed({
  photoId: '3xqxxxxxx',
  authorId: 0
})

if (result.success) {
  console.log(result.data)
}
```

### fetchSearchUser [#fetchsearchuser]

搜索用户。端点 `kuaishou.searchUser`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/searchUser)。

按关键词搜索用户，自动翻页。需要浏览器注册后的 cookie，支持游客。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 30 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明         |
| --------- | -------- | -- | ---------- |
| `keyword` | `string` | 是  | 搜索关键词      |
| `number`  | `number` | 否  | 目标条数，默认 30 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchSearchUser({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchSearchWorkList [#fetchsearchworklist]

搜索作品。端点 `kuaishou.searchWorkList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/searchWorkList)。

按关键词搜索作品，自动翻页。需要浏览器注册后的 cookie，支持游客。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 20 条，游标的带入与停止条件由端点声明处理。

| 参数        | 类型       | 必填 | 说明         |
| --------- | -------- | -- | ---------- |
| `keyword` | `string` | 是  | 搜索关键词      |
| `number`  | `number` | 否  | 目标条数，默认 20 |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchSearchWorkList({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

### fetchLoginUserProfile [#fetchloginuserprofile]

当前登录账号资料。端点 `kuaishou.loginUserProfile`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/kuaishou/loginUserProfile)。

取当前 cookie 所属账号的资料，不接参数。需要登录态 cookie。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { kuaishou: '' } })
// ---cut---
const result = await client.kuaishou.fetcher.fetchLoginUserProfile({})

if (result.success) {
  console.log(result.data)
}
```

## 注意事项 [#注意事项]

<Callout type="warn">
  快手接口需要有效的 Cookie，部分接口要登录状态才能拿到完整数据。
</Callout>

* `photoId` 可以从分享链接里提取
* `principalId` 可以从用户主页或直播间 URL 的末段提取
* 评论数据可能需要登录 Cookie 才能取到
* 建议设置合理的请求间隔，避免触发风控

快手的 URL 拼接器与 `live_api` 签名（`kuaishouUtils`）见[工具集](/docs/v7/usage/guide/utilities)。


# 小红书 SDK 方法 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/sdk/xiaohongshu)

> 小红书平台的 13 个 SDK 方法，由端点注册表派生



{/* This file was generated by scripts/generate-docs.ts. Do not edit it directly. */}

<Callout type="info">
  本页 13 个方法由端点注册表生成：参数表、摘要与废弃标记都取自
  端点声明。同一批端点的 **HTTP 形态**（路径、query 参数、响应信封、在线调用）见
  [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

## 调用形式与单次请求配置 [#调用形式与单次请求配置]

Client 上的**绑定 Fetcher** 是 `client.<平台>.fetcher.<方法>(options, requestConfig?)`：cookie 已随 Client 绑好，第二个参数只作用于当前这一次调用，并与 Client 的实例级请求配置合并 —— 单次配置优先，`headers` 单独合并。

直接导出的**裸 Fetcher** 是 `<平台>Fetcher.<方法>(options, cookie?, requestConfig?)`：没有实例级配置，cookie 按次传，第三个参数直接作用于当前请求。`amagi.<平台>Fetcher` 与同名的命名导出（`import { bilibiliFetcher } from '@ikenxuan/amagi'`）是同一个对象。

两种形态都由端点注册表派生、走同一条执行管线、返回同一种信封，所以本页列出的方法名与参数对两者都成立。

### 用 `Cookie` 头覆盖单次调用的 cookie [#用-cookie-头覆盖单次调用的-cookie]

`requestConfig.headers` 里**任意大小写**的 `Cookie`（`Cookie` / `cookie` / `COOKIE`）都会替换本次调用实际使用的 cookie：绑定形态覆盖 Client 上绑定的那份，裸 Fetcher 形态覆盖第二个参数。这次调用用哪份 Cookie，只写这一处就够。

小红书的签名要从 Cookie 里读 `a1`，覆盖成空串会落到游客会话（只拿得到上游允许匿名读取的内容）；要换成另一份登录态，就覆盖成仍含 `a1` 的那一份：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=xxx; web_session=xxx' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchNoteDetail(
  { note_id: 'n1', xsec_token: 'tk' },
  { headers: { Cookie: 'a1=xxx; web_session=xxx' } }
)
```

它只影响这一次请求，不改 Client 实例，也不影响同一实例后续的调用。

<Callout type="info">
  v7 的 `Cookie` 头按大小写不敏感匹配，覆盖只写在 `headers` 一处即可。
</Callout>

## 读取返回值：取 `data` [#读取返回值取-data]

方法永不抛异常，返回的是信封：成功支有 `data`，失败支有 `error`，两支都有 `message` 与 `meta`，顶层没有 `code`。本页所有示例统一用 `if (result.success)` 收窄之后再读 `result.data` —— 四种读法里只有它既不必额外 import，收窄后的 `data` 又不带 `| undefined`：

| 读法                       | 拿到的 `data`                  |
| ------------------------ | --------------------------- |
| `if (result.success)`    | `T`（本页示例统一用这种）              |
| 直接读 `result.data`（不收窄）   | `T \| undefined`            |
| `list.filter(isSuccess)` | `T`（数组回调里没有 `if` 可用）        |
| `unwrap(result)`         | `T`，失败时抛 `AmagiThrownError` |

四种读法的完整说明、失败分支的字段与三条逃生舱见[响应类型](/docs/v7/usage/guide/type-mode)。

### 大整数 ID 与响应类型 [#大整数-id-与响应类型]

默认 JSON 解析会把超出 JavaScript 安全整数范围的裸整数保留为十进制字符串，防止直播间、作品等 ID 被四舍五入。普通安全整数、浮点数和指数写法保持原样；显式文本响应和自定义 `transformResponse` 仍由调用方控制。响应 ID 的类型因此可能是 `string | number`，需要统一存储时可用 `String(id)`；不要先调用 `Number()` 再拼接请求。

新增端点只声明已有证据支持的响应字段；缺少完整成功响应样本的字段使用 `unknown`，使用前应检查对象、数组或字符串等实际结构。

已收录的端点在未提供 Cookie 时会初始化游客会话，并沿用当前请求的 User-Agent 和传输配置。同一客户端、UA 和请求配置下复用五分钟，并合并并发初始化；初始化失败后，下一次调用可以重试。不同客户端、代理、请求头或适配器等配置分别缓存；裸 Fetcher 也按其请求配置隔离。游客会话只能访问上游允许匿名读取的数据，需要登录的内容仍须传入有效登录 Cookie。

显式传入 `web_session` 或 `userId` 时，请保留与它配套的 `a1`。缺少 `a1` 会返回 `error.kind: 'auth'`、`error.code: 'COOKIE_MISSING'`，并且不发送请求。`client.xiaohongshu.request` 自定义请求不执行端点的游客初始化，调用方仍需提供有效的 `a1`。

## 本页之外：自定义请求 [#本页之外自定义请求]

本页是已收录的端点方法。要请求 amagi 尚未收录的接口，用 `client.xiaohongshu.request`（默认签名器按 method 选择：`POST` → `xhs-post`，其余 → `xhs-get`）。小红书那份 `apiUrls` 返回的是 `{ Url, Body, apiPath }` 三段，三个键对应 `url` / `config.data` / `amagi.signPath`：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=xxx; web_session=xxx' } })
// ---cut---
const d = client.xiaohongshu.apiUrls.noteDetail({ note_id: 'note-id', xsec_token: 'xsec_xxx' })
const r = await client.xiaohongshu.request.request({
  method: 'POST',
  url: d.Url,
  data: d.Body,
  amagi: { signPath: d.apiPath }
})
```

详见[自定义请求](/docs/v7/usage/advanced/custom-request)。

## Fetcher 方法 [#fetcher-方法]

### fetchHomeFeed [#fetchhomefeed]

首页推荐笔记列表。端点 `xiaohongshu.homeFeed`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/homeFeed)。

取首页推荐流笔记。翻页要手动：把上一页响应的 `cursor_score` 传回来。

| 参数                     | 类型                  | 必填 | 说明                 |
| ---------------------- | ------------------- | -- | ------------------ |
| `cursor_score`         | `string`            | 否  | 翻页游标；首页不传，续页传上一页的值 |
| `num`                  | `number`            | 否  | 单次请求的笔记条数，默认 27    |
| `refresh_type`         | `number`            | 否  | 刷新类型，默认 1          |
| `note_index`           | `number`            | 否  | 笔记索引，默认 0          |
| `category`             | `string`            | 否  | 内容分类，默认首页推荐流       |
| `search_key`           | `string`            | 否  | 搜索关键词，默认空字符串       |
| `unread_begin_note_id` | `string`            | 否  | 未读区间起点笔记 ID        |
| `unread_end_note_id`   | `string`            | 否  | 未读区间终点笔记 ID        |
| `unread_note_count`    | `number`            | 否  | 未读笔记数，默认 0         |
| `need_num`             | `number`            | 否  | 需要的笔记数量，默认 8       |
| `need_filter_image`    | `string \| boolean` | 否  | 是否过滤图片，默认 false    |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchHomeFeed({
  num: 20
})

if (result.success) {
  console.log(result.data)
}
```

### fetchNoteDetail [#fetchnotedetail]

笔记详细信息。端点 `xiaohongshu.noteDetail`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/noteDetail)。

取笔记正文与互动数据。要评论区用 `noteComments`。

| 参数           | 类型       | 必填 | 说明                                                          |
| ------------ | -------- | -- | ----------------------------------------------------------- |
| `note_id`    | `string` | 是  | 笔记 ID；从笔记分享链接里取                                             |
| `xsec_token` | `string` | 是  | 反爬令牌，随笔记分享链接下发；**与发放它的会话绑定** —— 游客下换会话即 461，须同会话现取或带上原游客 CK |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchNoteDetail({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}
```

`xsec_token` 可以从笔记的分享链接里取，形如 `xsec_xxx`。

### fetchNoteComments [#fetchnotecomments]

笔记评论列表。端点 `xiaohongshu.noteComments`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/noteComments)。

取笔记评论列表。`number` 指定目标条数，翻页由端点自动完成。**游客身份下平台对本接口限流较紧**：超限回 HTTP 461（伪装成成功的空壳），退避需分钟级、秒级无效；而且**不传 `number` 会触发翻页、多烧一次请求** —— 传具体小值可把请求数降到 1。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 50 条，游标的带入与停止条件由端点声明处理。

| 参数           | 类型       | 必填 | 说明                                                          |
| ------------ | -------- | -- | ----------------------------------------------------------- |
| `note_id`    | `string` | 是  | 笔记 ID；从笔记分享链接里取                                             |
| `xsec_token` | `string` | 是  | 反爬令牌，随笔记分享链接下发；**与发放它的会话绑定** —— 游客下换会话即 461，须同会话现取或带上原游客 CK |
| `number`     | `number` | 否  | 目标条数；不传时按单页上限翻页取满，而不是只取一页 —— 游客下翻页必被拒且多烧一次请求，传具体小值可降到 1 次   |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchNoteComments({
  note_id: '64xxxxxxxx',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}
```

v6 的 `cursor` 参数已由声明式翻页接管（小红书的 string 游标与抖音的 number 游标，语义差异收敛在端点声明里），调用方只说明要多少条。

### fetchUserProfile [#fetchuserprofile]

用户主页信息。端点 `xiaohongshu.userProfile`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/userProfile)。

取用户主页的资料与统计。笔记列表见 `userNoteList`。

| 参数            | 类型       | 必填 | 说明                                                          |
| ------------- | -------- | -- | ----------------------------------------------------------- |
| `user_id`     | `string` | 是  | 用户 ID，从主页地址里取                                               |
| `xsec_token`  | `string` | 否  | 反爬令牌，随用户主页分享链接下发；游客必传、有效登录 CK 可省；**与发放它的会话绑定**（游客下换会话即 461） |
| `xsec_source` | `string` | 否  | 反爬来源，默认 pc\_feed；仅在带 xsec\_token 时发出                        |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchUserProfile({
  user_id: '5xxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

用户资料改用 JSON 接口，平台响应包含 `data.basic_info`、`data.interactions` 与 `data.tab_public`。SDK 的 `result.data` 是这份原始响应，所以资料位于 `result.data.data`。读取旧主页 HTML 初始状态路径的调用方需相应调整。

```ts verify
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=...' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchUserProfile({ user_id: 'user-id' })
if (result.success) {
  const profile = result.data.data
  const nickname = profile?.basic_info?.nickname
  if (typeof nickname === 'string') console.log(nickname)
  console.log(profile?.interactions, profile?.tab_public)
}
```

这些字段目前是可选协议字段，未确认的内部结构保持 `unknown`；应像上例一样检查后再使用。

### fetchUserNoteList [#fetchusernotelist]

用户笔记列表。端点 `xiaohongshu.userNoteList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/userNoteList)。

取用户的笔记列表。翻页要手动：`cursor` 传上一页最后一条的 ID。

| 参数            | 类型       | 必填 | 说明                                                          |
| ------------- | -------- | -- | ----------------------------------------------------------- |
| `user_id`     | `string` | 是  | 用户 ID                                                       |
| `xsec_token`  | `string` | 否  | 反爬令牌，随用户主页分享链接下发；游客必传、有效登录 CK 可省；**与发放它的会话绑定**（游客下换会话即 461） |
| `xsec_source` | `string` | 否  | 反爬来源，默认 pc\_feed                                            |
| `cursor`      | `string` | 否  | 翻页游标；传上一页最后一条的 ID，首页不传                                      |
| `num`         | `number` | 否  | 单次请求的笔记条数，默认 30                                             |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchUserNoteList({
  user_id: '5xxxxxxxxx'
})

if (result.success) {
  console.log(result.data)
}
```

用户主页签发的 `xsec_token` 仍为必填，并与 `xsec_source` 一起传给上游。不要将笔记详情的 token 当作用户主页 token 使用。

### fetchEmojiList [#fetchemojilist]

表情列表。端点 `xiaohongshu.emojiList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/emojiList)。

取小红书表情列表，无参数。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchEmojiList({})

if (result.success) {
  console.log(result.data)
}
```

### searchNotes [#searchnotes]

笔记搜索结果列表。端点 `xiaohongshu.searchNotes`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/searchNotes)。

按关键词搜笔记。翻页手动传 `page`，并复用相同的 `search_id` / `session_id`；可指定排序和笔记类型。

| 参数           | 类型                                                          | 必填 | 说明                  |
| ------------ | ----------------------------------------------------------- | -- | ------------------- |
| `keyword`    | `string`                                                    | 是  | 搜索关键词               |
| `page`       | `number`                                                    | 否  | 页码，从 1 开始，默认 1      |
| `page_size`  | `number`                                                    | 否  | 每页条数，默认 20          |
| `sort`       | `'general' \| 'popularity_descending' \| 'time_descending'` | 否  | 排序，默认综合             |
| `note_type`  | `number`                                                    | 否  | 笔记类型：0 全部，1 视频，2 图文 |
| `search_id`  | `string`                                                    | 否  | 搜索标识；翻页时复用          |
| `session_id` | `string`                                                    | 否  | 搜索会话标识；翻页时复用        |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.searchNotes({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

可传 `sort`（`general` / `popularity_descending` / `time_descending`）与 `note_type`（0 全部、1 视频、2 图文）。接口使用手动页码 `page`；同一轮搜索翻页时，复用 `search_id` 与 `session_id`，每页的请求标识由 SDK 自动生成。

```ts verify
import amagi, { xiaohongshuUtils } from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: 'a1=...' } })
const search = {
  keyword: '旅行',
  search_id: xiaohongshuUtils.sign.getSearchId(),
  session_id: xiaohongshuUtils.sign.getSearchSessionId()
}
const firstPage = await client.xiaohongshu.fetcher.searchNotes({ ...search, page: 1 })
const secondPage = await client.xiaohongshu.fetcher.searchNotes({ ...search, page: 2 })
```

### searchUser [#searchuser]

搜索用户结果列表。端点 `xiaohongshu.searchUser`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/searchUser)。

按关键词或小红书号搜用户，返回 user\_id 等。翻页手动传 `page`。

| 参数          | 类型       | 必填 | 说明             |
| ----------- | -------- | -- | -------------- |
| `keyword`   | `string` | 是  | 搜索关键词或小红书号     |
| `page`      | `number` | 否  | 页码，从 1 开始，默认 1 |
| `page_size` | `number` | 否  | 每页条数，默认 15     |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.searchUser({
  keyword: '关键词'
})

if (result.success) {
  console.log(result.data)
}
```

公开方法名是 `searchUser`，与 `searchNotes` 一致。支持关键词或小红书号查询，手动传 `page` / `page_size` 翻页。该接口的 `code: 1000` 只有同时出现 `success: true` 时才作为成功处理，其他接口沿用各自的业务码判定。

### fetchSearchHotList [#fetchsearchhotlist]

搜索热榜。端点 `xiaohongshu.searchHotList`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/searchHotList)。

取小红书当前搜索热榜，无参数。

无参数。

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchSearchHotList({})

if (result.success) {
  console.log(result.data)
}
```

无业务参数，可调用 `client.xiaohongshu.fetcher.fetchSearchHotList()`。返回上游当前热榜；没有完整录制证据的条目字段保留为 `unknown`，使用前应自行收窄。

### fetchSubComments [#fetchsubcomments]

子评论（楼中楼）列表。端点 `xiaohongshu.subComments`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/subComments)。

展开某条一级评论下的回复。`number` 指定目标条数，翻页自动完成。

支持声明式翻页：用 `number` 指定需要的条数，单页上限 10 条，游标的带入与停止条件由端点声明处理。

| 参数                | 类型       | 必填 | 说明             |
| ----------------- | -------- | -- | -------------- |
| `note_id`         | `string` | 是  | 笔记 ID          |
| `root_comment_id` | `string` | 是  | 要展开的一级评论 ID    |
| `xsec_token`      | `string` | 是  | 反爬令牌，随笔记分享链接下发 |
| `number`          | `number` | 否  | 目标条数，默认一页      |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchSubComments({
  note_id: '64xxxxxxxx',
  root_comment_id: '',
  xsec_token: 'xsec_xxx'
})

if (result.success) {
  console.log(result.data)
}
```

`root_comment_id` 是要展开的一级评论 ID，`note_id` 与 `xsec_token` 来自同一篇笔记。传入 `number` 指定目标回复数，SDK 每页最多请求 10 条并自动推进游标。无需传 v6 补丁里的 `num` 或 `cursor`。

### fetchLiveRoom [#fetchliveroom]

直播间信息。端点 `xiaohongshu.liveRoom`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/liveRoom)。

取指定直播间的当前信息。variant=h5 走 h5 接口，否则走 web；web 端请提供 request\_user\_id 或含 userId 的 Cookie。

| 参数                | 类型              | 必填 | 说明                                         |
| ----------------- | --------------- | -- | ------------------------------------------ |
| `room_id`         | `string`        | 是  | 直播间 ID                                     |
| `variant`         | `'h5' \| 'web'` | 否  | 端类型，默认 web                                 |
| `request_user_id` | `string`        | 否  | 请求方用户 ID；web 默认从 Cookie 的 userId 读取，h5 不使用 |
| `source`          | `string`        | 否  | 来源标识，默认按端类型取（web=web\_live）                |
| `client_type`     | `number`        | 否  | 客户端类型，web 端默认 1                            |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchLiveRoom({
  room_id: ''
})

if (result.success) {
  console.log(result.data)
}
```

`room_id` 使用字符串，避免 JavaScript 大整数精度丢失。默认 `variant: 'web'`，`request_user_id` 可显式传入，也可从 Cookie 的 `userId` 读取；`variant: 'h5'` 不使用这个参数。两种接口的返回字段可能不同，协议类型只声明已有证据支持的共同字段。

### fetchLiveStatus [#fetchlivestatus]

直播状态。端点 `xiaohongshu.liveStatus`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/liveStatus)。

轮询指定直播间是否在播，返回体极小。

| 参数        | 类型       | 必填 | 说明                          |
| --------- | -------- | -- | --------------------------- |
| `room_id` | `string` | 是  | 直播间 ID                      |
| `scene`   | `string` | 否  | 场景标识，默认 share\_out\_of\_app |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchLiveStatus({
  room_id: ''
})

if (result.success) {
  console.log(result.data)
}
```

传入字符串 `room_id` 查询直播状态，默认 `scene: 'share_out_of_app'`。是否在播需读取上游返回的状态字段；HTTP 请求成功本身不代表直播正在进行。

### fetchLiveSquare [#fetchlivesquare]

直播广场。端点 `xiaohongshu.liveSquare`，同一端点的 [HTTP 形态](/docs/v7/usage/api/http/xiaohongshu/liveSquare)。

取直播广场推荐列表，参数均可选。

| 参数             | 类型                  | 必填 | 说明                                                                       |
| -------------- | ------------------- | -- | ------------------------------------------------------------------------ |
| `source`       | `number`            | 否  | 来源标识，默认 13                                                               |
| `category`     | `string`            | 否  | 分类，默认 0（全部）                                                              |
| `pre_source`   | `string`            | 否  | 前置来源，真机首屏为空                                                              |
| `size`         | `number`            | 否  | 每页数量，默认 27                                                               |
| `extra_info`   | `unknown \| string` | 否  | 附加信息；HTTP query 可传 JSON 字符串，默认 `{"image_formats":["jpg","webp","avif"]}` |
| `cursor_score` | `string`            | 否  | 分页游标分数，翻页时才带                                                             |

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { xiaohongshu: '' } })
// ---cut---
const result = await client.xiaohongshu.fetcher.fetchLiveSquare({
  source: 0
})

if (result.success) {
  console.log(result.data)
}
```

无必填参数，默认获取 27 条推荐直播间。需要翻页时手动传入上游返回的 `cursor_score`；它不是 v7 的 `number` 自动分页端点。`extra_info` 在 SDK 中可传对象，通过 HTTP query 调用时可传 URL 编码后的 JSON 对象字符串。

## 注意事项 [#注意事项-1]

<Callout type="warn">
  小红书对签名与 Cookie 的要求较高：登录 Cookie 要保留有效的 `a1`、`xsec_token` 要传对、
  请求间隔别太密。
</Callout>

* `note_id` 与 `xsec_token` 都可以从笔记的分享链接里提取
* 部分接口需要登录状态才能拿到完整数据
* 反爬较严格，建议控制请求频率

小红书的签名工具（`xiaohongshuUtils.sign` 的 `extractA1FromCookie` / `getSearchId` / `generateXT` 等）见[工具集](/docs/v7/usage/guide/utilities)。


# 类、枚举与变量 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/classes)

> 33 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 33 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### AdditionalType [#AdditionalType]

相关内容卡片类型枚举
用于标识动态中附加的相关内容卡片的类型

<TypeTable
  type="{
  &#x22;COMMON&#x22;: { type: '&#x22;ADDITIONAL_TYPE_COMMON&#x22;', description: '一般类型', default: '\'ADDITIONAL_TYPE_COMMON\'' },
  &#x22;GOODS&#x22;: { type: '&#x22;ADDITIONAL_TYPE_GOODS&#x22;', description: '商品信息', default: '\'ADDITIONAL_TYPE_GOODS\'' },
  &#x22;MATCH&#x22;: { type: '&#x22;ADDITIONAL_TYPE_MATCH&#x22;', description: '比赛信息', default: '\'ADDITIONAL_TYPE_MATCH\'' },
  &#x22;NONE&#x22;: { type: '&#x22;ADDITIONAL_TYPE_NONE&#x22;', description: '无相关内容', default: '\'ADDITIONAL_TYPE_NONE\'' },
  &#x22;PGC&#x22;: { type: '&#x22;ADDITIONAL_TYPE_PGC&#x22;', description: '剧集相关', default: '\'ADDITIONAL_TYPE_PGC\'' },
  &#x22;RESERVE&#x22;: { type: '&#x22;ADDITIONAL_TYPE_RESERVE&#x22;', description: '直播预约', default: '\'ADDITIONAL_TYPE_RESERVE\'' },
  &#x22;UGC&#x22;: { type: '&#x22;ADDITIONAL_TYPE_UGC&#x22;', description: '视频跳转', default: '\'ADDITIONAL_TYPE_UGC\'' },
  &#x22;UP_RCMD&#x22;: { type: '&#x22;ADDITIONAL_TYPE_UP_RCMD&#x22;', description: 'UP主推荐', default: '\'ADDITIONAL_TYPE_UP_RCMD\'' },
  &#x22;UPOWER_LOTTERY&#x22;: { type: '&#x22;ADDITIONAL_TYPE_UPOWER_LOTTERY&#x22;', description: '充电专属抽奖', default: '\'ADDITIONAL_TYPE_UPOWER_LOTTERY\'' },
  &#x22;VOTE&#x22;: { type: '&#x22;ADDITIONAL_TYPE_VOTE&#x22;', description: '投票', default: '\'ADDITIONAL_TYPE_VOTE\'' }
}"
/>

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/index.ts#L52)

### amagi [#amagi]

```ts
const amagi: typeof Client
```

源码：[`src/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/index.ts#L313)

### AMAGI\_BUS\_EVENT\_NAMES [#AMAGI_BUS_EVENT_NAMES]

全部事件名（12 个与 v6 对齐 + 3 个会话事件），用于遍历与穷尽性校验。

与 [`AmagiBusEventMap`](/docs/v7/usage/api/types/interfaces#AmagiBusEventMap) 由 `satisfies` 挂钩：表里多一个键而这里没跟上
就编译不过，所以「全部」不是靠人记着的。

```ts
const AMAGI_BUS_EVENT_NAMES: readonly ["log:info", "log:warn", "log:error", "log:debug", "log:mark", "http:request", "http:response", "http:error", "network:retry", "network:error", "api:success", "api:error", "session:state", "session:error", "session:success"]
```

源码：[`src/runtime/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/runtime/events.ts#L266)

### amagiEvents [#amagiEvents]

Amagi 全局事件发射器实例

```ts
const amagiEvents: TypedEventEmitter
```

**示例**

```ts twoslash
import { amagiEvents } from '@ikenxuan/amagi'

// 监听 API 成功事件
amagiEvents.on('api:success', (data) => {
  console.log(`[${data.platform}] ${data.methodType} 耗时 ${data.duration}ms`)
})
```

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L250)

### AmagiThrownError [#AmagiThrownError]

[`unwrap`](/docs/v7/usage/api/types/functions#unwrap) 失败时抛出的 Error 子类。

为什么不直接 `throw result.error`：[`AmagiError`](/docs/v7/usage/api/types/interfaces#AmagiError) 是**纯数据契约**，
抛非 Error 对象会丢栈、`e instanceof Error` 为假，Node 的 `unhandledRejection`
打印与各家日志 / 监控（Sentry 归为 “Non-Error exception captured”）都处理不好。

`AmagiError` 的字段**全部平铺在实例上**（`kind` / `code` / `message` /
`retryable`，以及 `platform` / `http` / `issues` / `raw`），所以
`catch (e) { (e as AmagiError).kind }` 直接可用；原始对象在 `error`，
`error.cause` 原样进 `Error.cause`（**不吞**）。

```ts
class AmagiThrownError
```

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L130)

#### [#AmagiThrownError-]

```ts
let "": unknown
```

#### code [#AmagiThrownError-code]

稳定的字符串错误码

```ts
let readonly code?: AmagiError["code"]
```

#### error [#AmagiThrownError-error]

失败信封里那个错误对象，原样保留（引用相等）

```ts
let readonly error?: AmagiError
```

#### http [#AmagiThrownError-http]

真实发生的 HTTP 状态

```ts
let readonly http?: AmagiError["http"]
```

#### issues [#AmagiThrownError-issues]

`kind === 'validation'` 时的字段级错误

```ts
let readonly issues?: AmagiError["issues"]
```

#### kind [#AmagiThrownError-kind]

判别键，跨平台统一的错误大类

```ts
let readonly kind?: AmagiError["kind"]
```

#### platform [#AmagiThrownError-platform]

平台原始错误码与文案

```ts
let readonly platform?: AmagiError["platform"]
```

#### raw [#AmagiThrownError-raw]

原始响应体（`createClient({ debug: true })` 时才有）

```ts
let readonly raw?: unknown
```

#### retryable [#AmagiThrownError-retryable]

是否值得重试

```ts
let readonly retryable?: boolean
```

### ApiError [#ApiError]

API错误类

```ts
class ApiError
```

源码：[`src/utils/errors.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/utils/errors.ts#L6)

#### [#ApiError-]

构造API错误

```ts
let "": unknown
```

#### code [#ApiError-code]

```ts
let readonly code?: number
```

#### platform [#ApiError-platform]

```ts
let readonly platform?: string
```

### BILIBILI\_CORRESPOND\_PUBKEY [#BILIBILI_CORRESPOND_PUBKEY]

B站 correspondPath 的 RSA 公钥（1024bit）。

删库前官方文档公开的明文公钥，多来源字节一致。correspondPath = 用它 RSA-OAEP-SHA256
加密 `refresh_{timestamp}` 再 hex。公钥内置是**对的** —— 它本就是前端公开常量
（laputa 主包运行时从 CDN 的 wasm 里拿的也是它），不是密钥。

```ts
const BILIBILI_CORRESPOND_PUBKEY: "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDLgd2OAkcGVtoE3ThUREbio0Eg\nUc/prcajMKXvkCKFCWhJYJcLkcM2DKKcSeFpD/j6Boy538YXnR6VhcuUJOhH2x71\nnzPjfdTcqMz7djHum0qSZA0AyCBDABUqCrfNgCiJ00Ra7GmRj+YCK1NJEuewlb40\nJNrRuoEUXpabUzGB8QIDAQAB\n-----END PUBLIC KEY-----"
```

源码：[`src/platforms/bilibili/cookieRefresh.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/cookieRefresh.ts#L48)

### bilibiliApiUrls [#bilibiliApiUrls]

B站 URL 构造器（v6 实现）。v7 门面（`client.bilibili`）上的是 `apiUrls`（v7
那份，在 `platforms/bilibili/api.ts`）；这一份只在包顶层
（`import { bilibiliApiUrls } from '@ikenxuan/amagi'`）与 `@ikenxuan/amagi/compat` 可达。

端点用的是 `platforms/bilibili/api.ts` 里的同名构造器，两份**当前输出一致**：
26 个方法逐个比对，请求主机与路径逐字相同，唯一差别是 v7 的 `getComments`
把 `plat` / `seek_rpid` / `web_location` 三个本来写死的值改成可由入参覆盖，
缺省值与这里相同。但仍是两份实现、不保证继续一致。

返回形态：方法给 URL 字符串（`getXxx(): string`），只有
`getCaptchaFromVoucher` / `validateCaptcha` 两个给 `{ Url, Body }`。

新代码请用 `client.bilibili.apiUrls`（v7 那份）；这一份的调用方按原样保留。

```ts
const bilibiliApiUrls: BilibiliAPI
```

源码：[`src/platforms/legacy/bilibili/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/bilibili/API.ts#L228)

### bilibiliFetcher [#bilibiliFetcher]

B站数据获取器（静态）。
包含所有 B站 API 方法，调用时需要传递 cookie

```ts
const bilibiliFetcher: BilibiliFetcher
```

**示例**

```ts twoslash
import { bilibiliFetcher } from '@ikenxuan/amagi'

const cookie = 'SESSDATA=xxx; bili_jct=yyy'
const result = await bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }, cookie)
```

源码：[`src/model/fetchers/bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/bilibili/index.ts#L43)

### bilibiliUtils [#bilibiliUtils]

B站相关功能模块 (工具集)

```ts
const bilibiliUtils: bilibiliUtilsModel
```

源码：[`src/platforms/bilibili/utils.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/utils.ts#L46)

### createAmagiClient [#createAmagiClient]

创建Amagi客户端实例

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：请改用 

  `createClient`

   或默认导出。这是同一个函数对象的别名，
  返回值就是 

  [`createClient`](/docs/v7/usage/api/types/functions#createClient)

   的结果：

  `douyin`

   / 

  `bilibili`

   上带 

  `login`


  命名空间（扫码登录会话），

  `events`

   是实例级总线（负载带 

  `meta`

  ）。
</Callout>

```ts
const createAmagiClient: typeof createClient
```

**返回值**：包含数据获取方法、服务器启动方法、绑定Cookie的平台工具集和API对象的对象

源码：[`src/server/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/server/index.ts#L59)

### CreateApp [#CreateApp]

After instantiation, it can interact with the specified platform API to quickly obtain data.

```ts
const CreateApp: AmagiConstructor
```

源码：[`src/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/index.ts#L309)

### default [#default]

After instantiation, it can interact with the specified platform API to quickly obtain data.

```ts
const default: typeof CreateApp
```

源码：[`src/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/index.ts#L312)

### douyinApiUrls [#douyinApiUrls]

抖音 URL 构造器（v6 实现）。v7 门面（`client.douyin`）上的是 `apiUrls`（v7
那份，在 `platforms/douyin/api.ts`）；这一份只在包顶层
（`import { douyinApiUrls } from '@ikenxuan/amagi'`）与 `@ikenxuan/amagi/compat` 可达。

端点用的是 `platforms/douyin/api.ts` 里的同名构造器，两份**已经漂移**：
这里的 `getWorkDetail` 打 `www.douyin.com` 且不带 `request_source` /
`origin_type`，而 v7 那份打 `www-hj.douyin.com` 并带那两个参数 ——
v7 侧注释记着实测：前者 9/18 被 Argus 拦、后者 18/18 通过。
逐字比对下来这是两份 URL 上唯一的差异（其余方法的主机与查询串相同），
但两份实现各自演进，不保证继续一致。

新代码请用 `client.douyin.apiUrls`（v7 那份）；这一份的调用方按原样保留。

默认实例，使用默认浏览器版本 125.0.0.0。

```ts
const douyinApiUrls: DouyinAPI
```

源码：[`src/platforms/legacy/douyin/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/douyin/API.ts#L638)

### douyinFetcher [#douyinFetcher]

抖音数据获取器（静态）。
包含所有抖音 API 方法，调用时需要传递 cookie

```ts
const douyinFetcher: DouyinFetcher
```

**示例**

```ts twoslash
import { douyinFetcher } from '@ikenxuan/amagi'

const cookie = 'ttwid=xxx'
const result = await douyinFetcher.fetchVideoWork({ aweme_id: '7123456789' }, cookie)
```

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L57)

### douyinPassport [#douyinPassport]

抖音 passport 扫码登录协议实现

login.douyin.com 的接口与 [www.douyin.com](http://www.douyin.com) 的数据接口是两套体系：

* query 需要 `p_no` / `sign` / `qs` 三重签名，外加 `x-tt-passport-aid-sign` 请求头
* a\_bogus 用的是 bdms `1.0.1.19` 形态（盐值 `dhzx`、pageId 7571），
  与 `../sign/a_bogus.ts` 里数据接口用的旧版（盐值 `cus`、pageId 6241）互不通用
* `request_host` 在 URL 里是双重编码，参与 sign 计算时只编码一次

因此这里单独实现一套，而不是复用 `douyinSign`。

## 参考来源 [#参考来源]

以下项目公开了本模块所需的协议细节。实现均按本仓库风格重写，未复制其代码：

* [https://github.com/ylcangel/douyin\_sign](https://github.com/ylcangel/douyin_sign) — a\_bogus `1.0.1.19-fix.01` 的
  去混淆结论（盐值、pageId、版本基准时间戳，以及 SDK 里两处 `Math.random`
  漏调用导致取值恒定的行为）。Apache-2.0。
* [https://github.com/cv-cat/DouYin\_Spider](https://github.com/cv-cat/DouYin_Spider) — bd-ticket-guard 的密钥签发流程：
  客户端自行生成 EC 密钥对并通过 cookie 交给服务端，由服务端签发票据，
  无需从浏览器导出任何材料。
* [https://github.com/dmmdekkd/DouyinDataAPI](https://github.com/dmmdekkd/DouyinDataAPI) — passport 四重签名、
  二次验证表单形态与 `x-tt-passport-aid-sign` 的派生方式。

SM3（GM/T 0004-2012）与 MurmurHash3 为公开标准算法。

源码：[`src/platforms/douyin/passport/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/index.ts#L29)

#### aBogus [#douyinPassport-aBogus]

生成 a\_bogus

**返回值**：a\_bogus 参数值（未做 URL 编码）

源码：[`src/platforms/douyin/passport/aBogus.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/aBogus.ts#L82)

#### BDMS\_SDK\_VERSION [#douyinPassport-BDMS_SDK_VERSION]

bdms SDK 版本号，同时也是 passport 通用参数里的 p\_bd

```ts
let BDMS_SDK_VERSION: unknown
```

源码：[`src/platforms/douyin/passport/aBogus.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/aBogus.ts#L49)

#### DouyinPassportClient [#douyinPassport-DouyinPassportClient]

```ts
class DouyinPassportClient
```

源码：[`src/platforms/douyin/passport/client.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/client.ts#L82)

#### PASSPORT\_USER\_AGENT [#douyinPassport-PASSPORT_USER_AGENT]

与签名里的浏览器环境保持一致的 UA

```ts
let PASSPORT_USER_AGENT: unknown
```

源码：[`src/platforms/douyin/passport/client.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/client.ts#L24)

#### PassportPayload [#douyinPassport-PassportPayload]

passport 接口的通用响应形状

源码：[`src/platforms/douyin/passport/client.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/client.ts#L41)

#### PassportResponse [#douyinPassport-PassportResponse]

源码：[`src/platforms/douyin/passport/client.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/client.ts#L48)

#### CookieJar [#douyinPassport-CookieJar]

```ts
class CookieJar
```

源码：[`src/platforms/douyin/passport/cookieJar.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/cookieJar.ts#L46)

#### INTERNAL\_PREFIX [#douyinPassport-INTERNAL_PREFIX]

本地会话状态的 cookie 名前缀，这些条目永远不会发给服务端

```ts
let INTERNAL_PREFIX: unknown
```

源码：[`src/platforms/douyin/passport/cookieJar.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/cookieJar.ts#L18)

#### makeAidSign [#douyinPassport-makeAidSign]

计算 `x-tt-passport-aid-sign` 请求头

源码：[`src/platforms/douyin/passport/params.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/params.ts#L149)

#### makeSignAndQs [#douyinPassport-makeSignAndQs]

计算 sign 与 qs

源码：[`src/platforms/douyin/passport/params.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/params.ts#L96)

#### randomHex [#douyinPassport-randomHex]

随机十六进制串，用于 biz\_trace\_id 一类的追踪 ID

源码：[`src/platforms/douyin/passport/params.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/params.ts#L64)

#### utcNoonTimestamp [#douyinPassport-utcNoonTimestamp]

当日 UTC 12:00 的秒级时间戳，aid-sign 以此为密钥基准

源码：[`src/platforms/douyin/passport/params.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/params.ts#L74)

#### xor5Hex [#douyinPassport-xor5Hex]

逐字节异或 5 后转十六进制，SDK 用它编码参数名列表、验证码与密码

源码：[`src/platforms/douyin/passport/params.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/params.ts#L60)

#### parsePollResult [#douyinPassport-parsePollResult]

解析 `check_qrconnect` 响应为状态机可消费的结果

源码：[`src/platforms/douyin/passport/parser.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/parser.ts#L115)

#### parseQrcode [#douyinPassport-parseQrcode]

解析 `get_qrcode` 响应

**返回值**：二维码信息，缺少 token 时返回 null

源码：[`src/platforms/douyin/passport/parser.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/parser.ts#L65)

#### parseSendCodeResult [#douyinPassport-parseSendCodeResult]

解析 `send_code` 响应

源码：[`src/platforms/douyin/passport/parser.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/parser.ts#L160)

#### parseValidateCodeResult [#douyinPassport-parseValidateCodeResult]

解析 `validate_code` 响应

源码：[`src/platforms/douyin/passport/parser.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/parser.ts#L185)

#### sm3 [#douyinPassport-sm3]

计算 SM3 摘要

**返回值**：32 字节摘要

源码：[`src/platforms/douyin/passport/sm3.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/sm3.ts#L102)

#### sm3Hex [#douyinPassport-sm3Hex]

十六进制摘要，仅用于测试与排查

源码：[`src/platforms/douyin/passport/sm3.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/sm3.ts#L130)

#### sm3Twice [#douyinPassport-sm3Twice]

连续两次 SM3（bdms 对 URL 与盐值的处理方式）

**返回值**：32 字节摘要

源码：[`src/platforms/douyin/passport/sm3.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/sm3.ts#L124)

#### TicketGuard [#douyinPassport-TicketGuard]

bd-ticket-guard 会话

状态全部读写自传入的 CookieJar，因此与 passport 的无状态调用形态天然兼容。

```ts
class TicketGuard
```

源码：[`src/platforms/douyin/passport/ticketGuard.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/ticketGuard.ts#L90)

#### TicketGuardState [#douyinPassport-TicketGuardState]

一次登录会话持有的 ticket-guard 状态

源码：[`src/platforms/douyin/passport/ticketGuard.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/ticketGuard.ts#L76)

#### PollResult [#douyinPassport-PollResult]

一次轮询的结果

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L36)

#### QrcodeInfo [#douyinPassport-QrcodeInfo]

二维码信息，`get_qrcode` 的解析结果

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L16)

#### SendCodeResult [#douyinPassport-SendCodeResult]

发送短信验证码的结果

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L39)

#### ValidateCodeResult [#douyinPassport-ValidateCodeResult]

提交短信验证码的结果

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L42)

#### VerifyContext [#douyinPassport-VerifyContext]

二次验证上下文

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L30)

#### VerifyWay [#douyinPassport-VerifyWay]

单个验证方式

源码：[`src/platforms/douyin/passport/types.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/types.ts#L33)

#### buildVerifyBody [#douyinPassport-buildVerifyBody]

发码与验码共用的表单字段。

字段顺序与「空值也要占位」的行为对齐官方验证页 SDK 的抓包形态：
`verify_ticket` / `new_verify_flow` / `std_verify_flow_id` / `std_verify_token`
即使为空也必须出现，缺字段会被判为伪造请求。

**返回值**：可直接交给 `client.liteRequest` 的表单

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L68)

#### isSmsCodeVerifyWay [#douyinPassport-isSmsCodeVerifyWay]

判断某个验证方式能否用短信验证码流程完成。

**返回值**：能走短信收码流程时为 `true`

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L39)

#### resolveVerifyWay [#douyinPassport-resolveVerifyWay]

选出本次要用的 `std_verify_way`。

优先用调用方指定的；否则从服务端给出的可选方式里挑一个能收码的；都没有才回退到
默认值。&#x2A;*不能写死 `mobile_sms_verify`** —— 遇到辅助验证的账号会因为 way 对不上
而失败，也不能取 `verifyWays[0]`，那一项未必是短信方式。

**返回值**：本次使用的 `std_verify_way`

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L51)

#### SMS\_ACT\_TYPE [#douyinPassport-SMS_ACT_TYPE]

短信验证码的 act\_type

```ts
let SMS_ACT_TYPE: unknown
```

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L22)

#### SMS\_CODE\_WAY\_PATTERN [#douyinPassport-SMS_CODE_WAY_PATTERN]

可以用「收 6 位验证码」这套流程走完的验证方式。

除官方常见的 `mobile_sms_verify`，账号被判定需要辅助验证时会给出
`assist_mobile_sms_verify`，两者都是下行短信收码，走同一对
`send_code` / `validate_code` 接口，区别只在 `std_verify_way` 的取值。
上行短信（`*_up_sms_verify`）要求用户从手机发短信出去，是另一套接口，不在此列。

```ts
let SMS_CODE_WAY_PATTERN: unknown
```

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L32)

#### SMS\_VERIFY\_WAY [#douyinPassport-SMS_VERIFY_WAY]

短信验证码的验证方式标识，服务端未给出可用方式时的兜底值

```ts
let SMS_VERIFY_WAY: unknown
```

源码：[`src/platforms/douyin/passport/verify.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/passport/verify.ts#L19)

### douyinSign [#douyinSign]

```ts
class douyinSign
```

源码：[`src/platforms/legacy/douyin/sign/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/douyin/sign/index.ts#L17)

#### AB [#douyinSign-AB]

a\_bogus 签名算法

```ts
AB(url: string, userAgent?: string): string
```

<TypeTable
  type="{
  &#x22;url&#x22;: { type: 'string', description: '需要签名的地址', required: true },
  &#x22;userAgent&#x22;: { type: 'string' }
}"
/>

**返回值**：对此地址签名后的URL查询参数

#### AcSignature [#douyinSign-AcSignature]

`__ac_signature` 反爬签名算法（纯算，不执行挑战页脚本）

与 `AB` / `XB` 不同，它签的不是 URL 而是&#x2A;*服务端下发的 `__ac_nonce`**：零 cookie 打
抖音页面会拿到一份 VMP 挑战页 + Set-Cookie 里的 `__ac_nonce`，带着
`__ac_nonce + __ac_signature` 再请求一次才放行（访客 cookie 就是这么铸出来的）。

签名体带一个**整秒时间戳**，所以同一 nonce 在同一秒内结果一致、跨秒就变；
`atMs` 可显式传入以复现某一刻的结果。

```ts
AcSignature(nonce: string, userAgent?: string, atMs?: number): string
```

<TypeTable
  type="{
  &#x22;nonce&#x22;: { type: 'string', description: '服务端下发的__ac_nonce，非空', required: true },
  &#x22;userAgent&#x22;: { type: 'string', description: '参与签名的 UA；按仓库约定与后续请求发出的那串对齐（首页挑战那条路上\n  实测服务端不校验一致性，见platforms/douyin/mint.ts的mintInflight）' },
  &#x22;atMs&#x22;: { type: 'number', description: '签名时刻（毫秒），默认当前时间' }
}"
/>

**返回值**：47 字符的 `__ac_signature`

#### Mstoken [#douyinSign-Mstoken]

生成一个指定长度的随机字符串

```ts
Mstoken(length: number): string
```

<TypeTable
  type="{
  &#x22;length&#x22;: { type: 'number', description: '字符串长度，默认为116', required: true }
}"
/>

#### SecSdk [#douyinSign-SecSdk]

`x-secsdk-web-signature` 签名算法

与 `AB` / `XB` 不同，它改写整条 URL 而不是返回一个参数值：签名算的是规范化后的 query，
服务端也按收到的 query 校验，所以必须发送返回的这条 URL。只对 SDK 策略表内的 path 生效，
其余原样返回，因此可以无条件套用。必须是最后一步（webid → a\_bogus → 本签名）。

```ts
SecSdk(url: string, options: ApplySecsdkOptions): string
```

<TypeTable
  type="{
  &#x22;url&#x22;: { type: 'string', description: '已拼好全部参数（含 a_bogus）的完整地址', required: true },
  &#x22;options&#x22;: { type: 'ApplySecsdkOptions', description: 'uifid（query 缺失时从 cookie 取）、cookie、method、ts', default: '{}', required: true }
}"
/>

**返回值**：需要加签时返回带签名的完整 URL，否则原样返回

#### VerifyFpManager [#douyinSign-VerifyFpManager]

生成一个唯一的验证字符串

```ts
VerifyFpManager(): string
```

#### XB [#douyinSign-XB]

X-Bogus 签名算法

```ts
XB(url: string, userAgent?: string): string
```

<TypeTable
  type="{
  &#x22;url&#x22;: { type: 'string', description: '需要签名的地址', required: true },
  &#x22;userAgent&#x22;: { type: 'string' }
}"
/>

**返回值**：对此地址签名后的URL查询参数

### douyinUtils [#douyinUtils]

抖音相关功能模块 (工具集)

```ts
const douyinUtils: douyinUtilsModel
```

源码：[`src/platforms/douyin/utils.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/utils.ts#L78)

### DynamicType [#DynamicType]

动态类型枚举

独立成叶子模块：Dynamic 子树各叶子类型文件都要用它做判别字段，
若定义在 `DynamicInfo/index.ts` 会形成叶子反向导入 barrel 的环。

它是**运行时 enum**，不是任何端点响应的形状映射，所以没有「形状序号 `_V<n>`」，
也不必按响应类型的目录约定包一层。

<TypeTable
  type="{
  &#x22;ARTICLE&#x22;: { type: '&#x22;DYNAMIC_TYPE_ARTICLE&#x22;', default: '\'DYNAMIC_TYPE_ARTICLE\'' },
  &#x22;AV&#x22;: { type: '&#x22;DYNAMIC_TYPE_AV&#x22;', default: '\'DYNAMIC_TYPE_AV\'' },
  &#x22;DRAW&#x22;: { type: '&#x22;DYNAMIC_TYPE_DRAW&#x22;', default: '\'DYNAMIC_TYPE_DRAW\'' },
  &#x22;FORWARD&#x22;: { type: '&#x22;DYNAMIC_TYPE_FORWARD&#x22;', default: '\'DYNAMIC_TYPE_FORWARD\'' },
  &#x22;LIVE_RCMD&#x22;: { type: '&#x22;DYNAMIC_TYPE_LIVE_RCMD&#x22;', default: '\'DYNAMIC_TYPE_LIVE_RCMD\'' },
  &#x22;WORD&#x22;: { type: '&#x22;DYNAMIC_TYPE_WORD&#x22;', default: '\'DYNAMIC_TYPE_WORD\'' }
}"
/>

源码：[`src/types/ReturnDataType/Bilibili/DynamicType.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/DynamicType.ts#L10)

### KUAISHOU\_H5\_CAPTCHA\_RESULT [#KUAISHOU_H5_CAPTCHA_RESULT]

H5 REST 的风控业务码

```ts
const KUAISHOU_H5_CAPTCHA_RESULT: 2001
```

源码：[`src/platforms/kuaishou/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/captcha.ts#L50)

### KUAISHOU\_PC\_CAPTCHA\_RESULT [#KUAISHOU_PC_CAPTCHA_RESULT]

PC GraphQL 的风控业务码

```ts
const KUAISHOU_PC_CAPTCHA_RESULT: 400002
```

源码：[`src/platforms/kuaishou/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/captcha.ts#L47)

### kuaishouApiUrls [#kuaishouApiUrls]

快手 URL 构造器（v6 实现）。v7 门面（`client.kuaishou`）上的是 `apiUrls`（v7
那份，在 `platforms/kuaishou/api.ts`）；这一份只在包顶层
（`import { kuaishouApiUrls } from '@ikenxuan/amagi'`）与 `@ikenxuan/amagi/compat` 可达。

该对象只负责返回请求描述，不直接发起网络请求。

端点用的是 `platforms/kuaishou/api.ts` 里的同名构造器，两份**已经漂移**：
这里的 `videoWork` / `comments` 打 `www.kuaishou.com/graphql`（GraphQL 的
`visionVideoDetail` / `commentListQuery`），v7 那份换成了 H5 分享页接口
`c.kuaishou.com` —— `videoWork` 是**免签**的
`POST /rest/wd/ugH5App/photo/simple/info`（实测是主通道：分享页 SSR 的
`INIT_STATE` 就是这条填的），`comments` 是 `POST /rest/wd/photo/comment/list`；
v7 还多出 `videoWorkFull`（签名的 `POST /rest/wd/photo/info`，实测稳定撞
`2001` 风控）与 `danmaku` 两个方法。

返回形态**不是 URL 字符串**：这一份给 `KuaishouLiveApiRequest`（live\_api，带
`method` / `body` / `signPath` / `requiresSign`）或 `KuaishouGraphqlRequest`；
v7 那份给 `KuaishouH5Request`（`method` / `body` / `signPath` / `referer` /
`requiresSign`）或 `KuaishouGraphqlRequest`。

新代码请用 `client.kuaishou.apiUrls`（v7 那份）；这一份的调用方按原样保留。

```ts
const kuaishouApiUrls: API
```

源码：[`src/platforms/legacy/kuaishou/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/kuaishou/API.ts#L544)

### kuaishouFetcher [#kuaishouFetcher]

快手数据获取器（静态）。
包含所有快手 API 方法，调用时需要传递 cookie

```ts
const kuaishouFetcher: KuaishouFetcher
```

**示例**

```ts twoslash
import { kuaishouFetcher } from '@ikenxuan/amagi'

const cookie = 'did=xxx'
const result = await kuaishouFetcher.fetchVideoWork({ photoId: '3x123456789' }, cookie)
```

源码：[`src/model/fetchers/kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/kuaishou/index.ts#L37)

### kuaishouSign [#kuaishouSign]

快手签名工具集。

负责将请求描述对象转换为带 `__NS_hxfalcon` / `kww` 的最终请求材料。

```ts
class kuaishouSign
```

源码：[`src/platforms/legacy/kuaishou/sign/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/kuaishou/sign/index.ts#L34)

#### generateHxfalconFromPayload [#kuaishouSign-generateHxfalconFromPayload]

根据结构化签名载荷生成 `__NS_hxfalcon`。

```ts
generateHxfalconFromPayload(payload: KuaishouHxfalconPayload): Pick<KuaishouLiveApiSignature, "signResult" | "signInput" | "catVersion">
```

<TypeTable
  type="{
  &#x22;payload&#x22;: { type: 'KuaishouHxfalconPayload', description: '已标准化的快手签名载荷', required: true }
}"
/>

**返回值**：包含最终签名串、sign input 与 `caver` 的结果

#### generateKww [#kuaishouSign-generateKww]

生成快手请求头中的 `kww` 值。

```ts
generateKww(cookie?: string): string
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '原始 Cookie 字符串' }
}"
/>

**返回值**：`kww` 请求头值

#### getCatVersion [#kuaishouSign-getCatVersion]

获取当前纯算法运行时使用的 `caver`。

```ts
getCatVersion(): string
```

**返回值**：快手 `caver` 值

#### signLiveApiRequest [#kuaishouSign-signLiveApiRequest]

为结构化的快手 `live_api` 请求描述对象签名。

这是项目层更推荐使用的入口，因为它能显式保留 `signPath` 元数据。

```ts
signLiveApiRequest(request: KuaishouLiveApiRequest, cookie?: string): KuaishouLiveApiSignature
```

<TypeTable
  type="{
  &#x22;request&#x22;: { type: 'KuaishouLiveApiRequest', description: '快手live_api请求描述对象', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '原始 Cookie 字符串' }
}"
/>

**返回值**：带签名 URL、附加请求头和调试信息

#### signLiveApiUrl [#kuaishouSign-signLiveApiUrl]

为快手 `live_api` URL 签名。

```ts
signLiveApiUrl(url: string, cookie?: string, signPath?: string): KuaishouLiveApiSignature
```

<TypeTable
  type="{
  &#x22;url&#x22;: { type: 'string', description: '实际请求 URL', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '原始 Cookie 字符串' },
  &#x22;signPath&#x22;: { type: 'string', description: '可选的规范签名路径' }
}"
/>

**返回值**：带签名 URL、附加请求头和调试信息

### kuaishouUtils [#kuaishouUtils]

快手相关功能模块 (工具集)

```ts
const kuaishouUtils: kuaishouUtilsModel
```

源码：[`src/platforms/kuaishou/utils.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/utils.ts#L31)

### MajorType [#MajorType]

转发动态种子动态主体类型枚举

<TypeTable
  type="{
  &#x22;APPLET&#x22;: { type: '&#x22;MAJOR_TYPE_APPLET&#x22;', description: '小程序', default: '\'MAJOR_TYPE_APPLET\'' },
  &#x22;ARCHIVE&#x22;: { type: '&#x22;MAJOR_TYPE_ARCHIVE&#x22;', description: '视频', default: '\'MAJOR_TYPE_ARCHIVE\'' },
  &#x22;ARTICLE&#x22;: { type: '&#x22;MAJOR_TYPE_ARTICLE&#x22;', description: '文章', default: '\'MAJOR_TYPE_ARTICLE\'' },
  &#x22;COMMON&#x22;: { type: '&#x22;MAJOR_TYPE_COMMON&#x22;', description: '一般类型', default: '\'MAJOR_TYPE_COMMON\'' },
  &#x22;COURSES&#x22;: { type: '&#x22;MAJOR_TYPE_COURSES&#x22;', description: '课程', default: '\'MAJOR_TYPE_COURSES\'' },
  &#x22;DRAW&#x22;: { type: '&#x22;MAJOR_TYPE_DRAW&#x22;', description: '带图动态', default: '\'MAJOR_TYPE_DRAW\'' },
  &#x22;LIVE&#x22;: { type: '&#x22;MAJOR_TYPE_LIVE&#x22;', description: '直播间分享', default: '\'MAJOR_TYPE_LIVE\'' },
  &#x22;LIVE_RCMD&#x22;: { type: '&#x22;MAJOR_TYPE_LIVE_RCMD&#x22;', description: '直播状态', default: '\'MAJOR_TYPE_LIVE_RCMD\'' },
  &#x22;MEDIALIST&#x22;: { type: '&#x22;MAJOR_TYPE_MEDIALIST&#x22;', description: '媒体列表', default: '\'MAJOR_TYPE_MEDIALIST\'' },
  &#x22;MUSIC&#x22;: { type: '&#x22;MAJOR_TYPE_MUSIC&#x22;', description: '音频更新', default: '\'MAJOR_TYPE_MUSIC\'' },
  &#x22;NONE&#x22;: { type: '&#x22;MAJOR_TYPE_NONE&#x22;', description: '动态失效', default: '\'MAJOR_TYPE_NONE\'' },
  &#x22;OPUS&#x22;: { type: '&#x22;MAJOR_TYPE_OPUS&#x22;', description: '图文动态', default: '\'MAJOR_TYPE_OPUS\'' },
  &#x22;PGC&#x22;: { type: '&#x22;MAJOR_TYPE_PGC&#x22;', description: '剧集更新', default: '\'MAJOR_TYPE_PGC\'' },
  &#x22;SUBSCRIPTION&#x22;: { type: '&#x22;MAJOR_TYPE_SUBSCRIPTION&#x22;', description: '订阅', default: '\'MAJOR_TYPE_SUBSCRIPTION\'' },
  &#x22;SUBSCRIPTION_NEW&#x22;: { type: '&#x22;MAJOR_TYPE_SUBSCRIPTION_NEW&#x22;', description: '新订阅', default: '\'MAJOR_TYPE_SUBSCRIPTION_NEW\'' },
  &#x22;UGC_SEASON&#x22;: { type: '&#x22;MAJOR_TYPE_UGC_SEASON&#x22;', description: '合集更新', default: '\'MAJOR_TYPE_UGC_SEASON\'' },
  &#x22;UPOWER_COMMON&#x22;: { type: '&#x22;MAJOR_TYPE_UPOWER_COMMON&#x22;', description: '充电相关', default: '\'MAJOR_TYPE_UPOWER_COMMON\'' }
}"
/>

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/index.ts#L11)

### ValidationError [#ValidationError]

参数验证错误类

```ts
class ValidationError
```

源码：[`src/utils/errors.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/utils/errors.ts#L27)

#### [#ValidationError-]

构造参数验证错误

```ts
let "": unknown
```

#### errors [#ValidationError-errors]

```ts
let readonly errors?: Array<{ field: string; message: string }>
```

#### fromZodError [#ValidationError-fromZodError]

从Zod错误创建验证错误

```ts
fromZodError(zodError: zod.ZodError<any>, requestPath?: string): ValidationError
```

<TypeTable
  type="{
  &#x22;zodError&#x22;: { type: 'zod.ZodError<any>', description: 'Zod验证错误', required: true },
  &#x22;requestPath&#x22;: { type: 'string', description: 'HTTP请求路径' }
}"
/>

**返回值**：验证错误实例

#### requestPath [#ValidationError-requestPath]

```ts
let readonly requestPath?: string
```

### XIAOHONGSHU\_ANTI\_SPAM\_STATUS [#XIAOHONGSHU_ANTI_SPAM_STATUS]

反垃圾状态码。平台 redcaptcha SDK 里的名字是 `antiSpam`

```ts
const XIAOHONGSHU_ANTI_SPAM_STATUS: 471
```

源码：[`src/platforms/xiaohongshu/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/xiaohongshu/captcha.ts#L59)

### XIAOHONGSHU\_ANTI\_SPIDER\_STATUS [#XIAOHONGSHU_ANTI_SPIDER_STATUS]

反爬状态码。平台 redcaptcha SDK 里的名字是 `antiSpider`

```ts
const XIAOHONGSHU_ANTI_SPIDER_STATUS: 461
```

源码：[`src/platforms/xiaohongshu/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/xiaohongshu/captcha.ts#L56)

### xiaohongshuApiUrls [#xiaohongshuApiUrls]

小红书 URL 构造器（v6 实现）。v7 门面（`client.xiaohongshu`）上的是 `apiUrls`（v7
那份，在 `platforms/xiaohongshu/api.ts`）；这一份只在包顶层
（`import { xiaohongshuApiUrls } from '@ikenxuan/amagi'`）与 `@ikenxuan/amagi/compat` 可达。

端点用的是 `platforms/xiaohongshu/api.ts` 里的同名构造器，两份**当前输出一致**
（七个方法的主机、路径与 body 逐个比对相同），但方法签名有两点差别：
这里的 `searchNotes` 自己调 `xiaohongshuSign.getSearchId()` 生成 `search_id`，
v7 那份要调用方把 `searchId` 显式传进来（模块因此保持纯函数、可复现）；
`emojiList` 这里收一个被忽略的参数，v7 那份不收参数。仍是两份实现、
不保证继续一致。

返回形态**不是 URL 字符串**：两份都给 `{ Url, Body, apiPath }` 三段（v7 那份
的类型名是 `XhsRequestDescription`）—— `x-s` 签名只吃 pathname、POST 的 body
又要参与签名，一个字符串装不下这三样。

新代码请用 `client.xiaohongshu.apiUrls`（v7 那份）；这一份的调用方按原样保留。

```ts
const xiaohongshuApiUrls: { homeFeed(data?: Omit<{ methodType: "homeFeed"; cursor_score?: string | undefined; num?: number | undefined; refresh_type?: number | undefined; note_index?: number | undefined; category?: string | undefined; search_key?: string | undefined; }, "methodType">): { ...; }; ... 5 more ...; searchNotes(data: Omit<...>): ...
```

源码：[`src/platforms/legacy/xiaohongshu/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/xiaohongshu/API.ts#L45)

### xiaohongshuFetcher [#xiaohongshuFetcher]

小红书数据获取器（静态）。
包含所有小红书 API 方法，调用时需要传递 cookie

```ts
const xiaohongshuFetcher: XiaohongshuFetcher
```

**示例**

```ts twoslash
import { xiaohongshuFetcher } from '@ikenxuan/amagi'

const cookie = 'a1=xxx; web_session=xxx'
const result = await xiaohongshuFetcher.fetchNoteDetail({ note_id: 'n1', xsec_token: 'tk' }, cookie)
```

源码：[`src/model/fetchers/xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/xiaohongshu/index.ts#L39)

### xiaohongshuSign [#xiaohongshuSign]

小红书签名算法类

```ts
class xiaohongshuSign
```

源码：[`src/platforms/legacy/xiaohongshu/sign/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/xiaohongshu/sign/index.ts#L13)

#### client [#xiaohongshuSign-client]

```ts
let client: unknown
```

#### createGuestCookie [#xiaohongshuSign-createGuestCookie]

创建包含 web\_session 的小红书 Web 端游客 Cookie。

`requestConfig` 会透传到游客会话初始化请求，可用于配置代理、超时等传输参数。

```ts
createGuestCookie(requestConfig?: AxiosRequestConfig): Promise<string>
```

<TypeTable
  type="{
  &#x22;requestConfig&#x22;: { type: 'AxiosRequestConfig' }
}"
/>

#### extractA1FromCookie [#xiaohongshuSign-extractA1FromCookie]

从cookie字符串中提取a1值

按名精确匹配（`contracts/cookie.ts` 的 `getCookieValue`）—— 正则匹配会在
`xa1=WRONG; a1=RIGHT` 这类输入上取错值。未命中返回空串（`getCookieValue`
返回 `undefined`，这里用 `?? ''` 承接）。

```ts
extractA1FromCookie(cookieString: string): string
```

<TypeTable
  type="{
  &#x22;cookieString&#x22;: { type: 'string', description: '完整的cookie字符串', required: true }
}"
/>

**返回值**：a1 cookie值

#### generateXB3Traceid [#xiaohongshuSign-generateXB3Traceid]

生成X-B3-Traceid

```ts
generateXB3Traceid(): string
```

**返回值**：16位随机字符串

#### generateXSCommon [#xiaohongshuSign-generateXSCommon]

生成X-S-Common参数

```ts
generateXSCommon(cookies: string): string
```

<TypeTable
  type="{
  &#x22;cookies&#x22;: { type: 'string', description: 'cookie字符串', required: true }
}"
/>

**返回值**：Base64编码的随机字符串

#### generateXSGet [#xiaohongshuSign-generateXSGet]

生成GET请求的X-S签名

```ts
generateXSGet(path: string, a1Cookie: string, clientType: string, params: Record<string, any>): string
```

<TypeTable
  type="{
  &#x22;path&#x22;: { type: 'string', description: 'API路径', required: true },
  &#x22;a1Cookie&#x22;: { type: 'string', description: 'a1 cookie值', required: true },
  &#x22;clientType&#x22;: { type: 'string', description: '客户端类型，默认为 \'xhs-pc-web\'', default: '\'xhs-pc-web\'', required: true },
  &#x22;params&#x22;: { type: 'Record<string, any>', description: '查询参数对象', default: '{}', required: true }
}"
/>

**返回值**：X-S签名

#### generateXSPost [#xiaohongshuSign-generateXSPost]

生成POST请求的X-S签名

```ts
generateXSPost(path: string, a1Cookie: string, clientType: string, body: Record<string, any>): string
```

<TypeTable
  type="{
  &#x22;path&#x22;: { type: 'string', description: 'API路径', required: true },
  &#x22;a1Cookie&#x22;: { type: 'string', description: 'a1 cookie值', required: true },
  &#x22;clientType&#x22;: { type: 'string', description: '客户端类型，默认为 \'xhs-pc-web\'', default: '\'xhs-pc-web\'', required: true },
  &#x22;body&#x22;: { type: 'Record<string, any>', description: '请求体对象', default: '{}', required: true }
}"
/>

**返回值**：X-S签名

#### generateXT [#xiaohongshuSign-generateXT]

生成X-T时间戳

```ts
generateXT(): number
```

**返回值**：当前时间戳字符串

#### getSearchId [#xiaohongshuSign-getSearchId]

生成搜索ID

```ts
let getSearchId: unknown
```

**返回值**：搜索ID字符串

### xiaohongshuUtils [#xiaohongshuUtils]

小红书相关功能模块 (工具集)

```ts
const xiaohongshuUtils: xiaohongshuUtilsModel
```

源码：[`src/platforms/xiaohongshu/utils.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/xiaohongshu/utils.ts#L27)


# 函数 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/functions)

> 60 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 60 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### assertValidBilibiliParams [#assertValidBilibiliParams]

验证哔哩哔哩参数，失败抛 `ValidationError`

```ts
assertValidBilibiliParams<T>(methodType: T, params: unknown): zod.infer<typeof BilibiliValidationSchemas[T]>
```

类型参数：`T extends BilibiliMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '哔哩哔哩方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：校验通过后的参数

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L122)

### assertValidDouyinParams [#assertValidDouyinParams]

验证抖音参数，失败抛 `ValidationError`（不产出失败结果）

```ts
assertValidDouyinParams<T>(methodType: T, params: unknown): zod.infer<typeof DouyinValidationSchemas[T]>
```

类型参数：`T extends DouyinMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '抖音方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：校验通过后的参数

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L111)

### assertValidKuaishouParams [#assertValidKuaishouParams]

验证快手参数，失败抛 `ValidationError`

```ts
assertValidKuaishouParams<T>(methodType: T, params: unknown): zod.infer<typeof KuaishouValidationSchemas[T]>
```

类型参数：`T extends KuaishouMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '快手方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：校验通过后的参数

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L133)

### assertValidXiaohongshuParams [#assertValidXiaohongshuParams]

验证小红书参数，失败抛 `ValidationError`

```ts
assertValidXiaohongshuParams<T>(methodType: T, params: unknown): zod.infer<typeof XiaohongshuValidationSchemas[T]>
```

类型参数：`T extends XiaohongshuMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '小红书方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：校验通过后的参数

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L144)

### av2bv [#av2bv]

av号转bv号

```ts
av2bv(aid: number): `BV1${string}`
```

<TypeTable
  type="{
  &#x22;aid&#x22;: { type: 'number', description: 'av号', required: true }
}"
/>

源码：[`src/platforms/bilibili/sign/bv2av.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/sign/bv2av.ts#L13)

### bv2av [#bv2av]

bv号转av号

```ts
bv2av(bvid: string): number
```

<TypeTable
  type="{
  &#x22;bvid&#x22;: { type: 'string', description: 'bv号', required: true }
}"
/>

源码：[`src/platforms/bilibili/sign/bv2av.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/sign/bv2av.ts#L32)

### checkDouyinLoginState [#checkDouyinLoginState]

`unknown` 表示探测失败，而非登录失效；因此刻意不缓存。

```ts
checkDouyinLoginState(cookie?: string | null, options: CheckDouyinLoginStateOptions): Promise<DouyinLoginCheck>
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string | null' },
  &#x22;options&#x22;: { type: 'CheckDouyinLoginStateOptions', default: '{}', required: true }
}"
/>

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L53)

### checkPassportQrcode [#checkPassportQrcode]

查询抖音扫码登录二维码的状态

状态为 `confirmed` 时会自动跟随 SSO 跳转领取登录凭证，返回的 `cookie` 即完整登录态。

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：请用 

  `client.douyin.login.qrcode()`

  （状态归一化为


  `LoginState.phase`

  ，轮询循环在引擎里）。
</Callout>

```ts
checkPassportQrcode(options: DouyinPassportQrcodeStatusOptions, cookie?: string, requestConfig?: RequestConfig): Promise<Result<DouyinReturnTypeMap["passportQrcodeStatus"]>>
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'DouyinPassportQrcodeStatusOptions', description: '二维码状态参数', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '会话 Cookie，必须是申请二维码时返回的那一份' },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '请求配置 (可选)' }
}"
/>

**返回值**：扫码状态与最新会话 cookie

**示例**

```ts
const status = await checkPassportQrcode({ token }, cookie)
// new 未扫码 / scanned 已扫待确认 / verify 需二次验证 / confirmed 登录成功 / expired 已过期
console.log(status.data.status)
```

源码：[`src/model/fetchers/douyin/auth.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/auth.ts#L189)

### clearDouyinLoginStateCache [#clearDouyinLoginStateCache]

清空时也会让进行中的探测失效，避免旧结果回填缓存。

```ts
clearDouyinLoginStateCache(): void
```

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L105)

### configureDouyinGuestCache [#configureDouyinGuestCache]

可选的磁盘缓存。每个网络身份使用一个私有文件；传 null 则 token 只保存在内存中。
自定义 transport 只使用各自作用域内的内存缓存，避免不同代理之间复用磁盘缓存。

```ts
configureDouyinGuestCache(filePath: string | null): void
```

<TypeTable
  type="{
  &#x22;filePath&#x22;: { type: 'string | null', required: true }
}"
/>

源码：[`src/platforms/douyin/guestCredential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/guestCredential.ts#L37)

### createBilibiliRoutes [#createBilibiliRoutes]

创建B站路由

```ts
createBilibiliRoutes(cookie: string, requestConfig?: RequestConfig): Router
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: 'B站Cookie', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '可选的请求配置（缺省时由运行期装配平台默认基线，见 client/runtime.ts）' }
}"
/>

**返回值**：Express路由器

源码：[`src/platforms/bilibili/routes.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/routes.ts#L25)

### createBoundBilibiliFetcher [#createBoundBilibiliFetcher]

```ts
createBoundBilibiliFetcher(cookie: string, requestConfig?: RequestConfig): BoundBilibiliFetcher
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig' }
}"
/>

源码：[`src/model/fetchers/bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/bilibili/index.ts#L67)

### createBoundDouyinFetcher [#createBoundDouyinFetcher]

创建绑定了 Cookie 和请求配置的抖音 Fetcher

```ts
createBoundDouyinFetcher(cookie: string, requestConfig?: RequestConfig): BoundDouyinFetcher
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '抖音 Cookie', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '请求配置 (可选)' }
}"
/>

**返回值**：绑定了 Cookie 的 Fetcher 对象，调用时无需传递 cookie

**示例**

```ts twoslash
import { createBoundDouyinFetcher } from '@ikenxuan/amagi'

const fetcher = createBoundDouyinFetcher('your_cookie')
const result = await fetcher.fetchVideoWork({ aweme_id: '7123456789' })
```

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L80)

### createBoundKuaishouFetcher [#createBoundKuaishouFetcher]

```ts
createBoundKuaishouFetcher(cookie: string, requestConfig?: RequestConfig): BoundKuaishouFetcher
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig' }
}"
/>

源码：[`src/model/fetchers/kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/kuaishou/index.ts#L61)

### createBoundXiaohongshuFetcher [#createBoundXiaohongshuFetcher]

```ts
createBoundXiaohongshuFetcher(cookie: string | XiaohongshuSessionInput, requestConfig?: RequestConfig): BoundXiaohongshuFetcher
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string | XiaohongshuSessionInput', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig' }
}"
/>

源码：[`src/model/fetchers/xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/xiaohongshu/index.ts#L63)

### createClient [#createClient]

创建 Amagi 客户端（门面）。

顶层 `startServer / events / on / once` + 四个平台模块
（`{ ...utils, fetcher }`）：fetcher 方法集合由各平台的端点注册表派生，
统一返回 `AmagiResult` 信封。

`startServer` 挂的平台路由同样从 registry 派生（token / host 选项见
`server/auth.ts`）。第二参 `{ openapi }` 不传时保持默认行为。

```ts
createClient(options: ClientOptions): { bilibili: { apiUrls: …; danmaku: …; fetcher: …; login: …; refreshCredential: …; request: …; …其余 1 个成员 }; douyin: { apiUrls: …; credentials: …; fetcher: …; login: …; passport: …; request: …; …其余 1 个成员 }; events: EventBus; kuaishou: { apiUrls: …; fetcher: …; login: …; request: …; sign: … }; on: __type<K>(event: …, listener: …): …; once: __type<K>(event: …, listener: …): …; …其余 2 个成员 }
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'ClientOptions', default: '{}', required: true }
}"
/>

源码：[`src/client/createClient.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/createClient.ts#L130)

### createDouyinRoutes [#createDouyinRoutes]

创建抖音路由

```ts
createDouyinRoutes(cookie: string, requestConfig?: RequestConfig): Router
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '抖音Cookie', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '可选的请求配置（缺省时由运行期装配平台默认基线，见 client/runtime.ts）' }
}"
/>

**返回值**：Express路由器

源码：[`src/platforms/douyin/routes.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/routes.ts#L29)

### createErrorResponse [#createErrorResponse]

创建失败信封

一般用不到 —— 主路径的失败信封由执行管线构造（错误归因、cause 保留
都在管线内）。需要手工组装 `AmagiResult` 时用它：`createErrorResponse(error, meta)`。

```ts
createErrorResponse(error: AmagiError, meta: AmagiMeta): AmagiFailure
```

<TypeTable
  type="{
  &#x22;error&#x22;: { type: 'AmagiError', description: '唯一错误载体（AmagiError，非空）', required: true },
  &#x22;meta&#x22;: { type: 'AmagiMeta', description: '请求元信息', required: true }
}"
/>

**返回值**：失败信封（`message` 等价于 `error.message`）

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L177)

### createKuaishouRoutes [#createKuaishouRoutes]

创建快手路由

```ts
createKuaishouRoutes(cookie: string, requestConfig?: RequestConfig): Router
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '快手Cookie', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '可选的请求配置（缺省时由运行期装配平台默认基线，见 client/runtime.ts）' }
}"
/>

**返回值**：Express路由器

源码：[`src/platforms/kuaishou/routes.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/routes.ts#L25)

### createSuccessResponse [#createSuccessResponse]

创建成功信封

一般用不到 —— 主路径的成功信封由执行管线构造。需要手工组装
`AmagiResult` 时用它：`createSuccessResponse(data, meta)`。

```ts
createSuccessResponse<T>(data: T, meta: AmagiMeta, message: string): AmagiSuccess<T>
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'T', description: '端点声明的返回数据', required: true },
  &#x22;meta&#x22;: { type: 'AmagiMeta', description: '请求元信息（与管线的AmagiMeta同形）', required: true },
  &#x22;message&#x22;: { type: 'string', description: '覆盖默认的SUCCESS_MESSAGE', default: 'SUCCESS_MESSAGE', required: true }
}"
/>

**返回值**：成功信封

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L159)

### createXiaohongshuRoutes [#createXiaohongshuRoutes]

创建小红书路由

```ts
createXiaohongshuRoutes(cookie: string | XiaohongshuSessionInput, requestConfig?: RequestConfig): Router
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string | XiaohongshuSessionInput', description: '小红书Cookie', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '可选的请求配置（缺省时由运行期装配平台默认基线，见 client/runtime.ts）' }
}"
/>

**返回值**：Express路由器

源码：[`src/platforms/xiaohongshu/routes.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/xiaohongshu/routes.ts#L26)

### emitApiError [#emitApiError]

发射 API 错误事件

```ts
emitApiError(data: Omit<ApiErrorEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<ApiErrorEventData, &#x22;timestamp&#x22;>', description: '错误数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L315)

### emitApiSuccess [#emitApiSuccess]

发射 API 成功事件

```ts
emitApiSuccess(data: Omit<ApiSuccessEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<ApiSuccessEventData, &#x22;timestamp&#x22;>', description: '成功数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L307)

### emitHttpRequest [#emitHttpRequest]

发射 HTTP 请求事件

```ts
emitHttpRequest(data: Omit<HttpRequestEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<HttpRequestEventData, &#x22;timestamp&#x22;>', description: '请求数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L275)

### emitHttpResponse [#emitHttpResponse]

发射 HTTP 响应事件

```ts
emitHttpResponse(data: Omit<HttpResponseEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<HttpResponseEventData, &#x22;timestamp&#x22;>', description: '响应数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L283)

### emitLog [#emitLog]

发射日志事件

```ts
emitLog(level: LogEventData["level"], message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;level&#x22;: { type: 'LogEventData[&#x22;level&#x22;]', description: '日志级别', required: true },
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L262)

### emitLogDebug [#emitLogDebug]

发射 debug 级别日志

```ts
emitLogDebug(message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L355)

### emitLogError [#emitLogError]

发射 error 级别日志

```ts
emitLogError(message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L346)

### emitLogInfo [#emitLogInfo]

发射 info 级别日志

```ts
emitLogInfo(message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L328)

### emitLogMark [#emitLogMark]

发射 mark 级别日志 (用于重要标记)

```ts
emitLogMark(message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L364)

### emitLogWarn [#emitLogWarn]

发射 warn 级别日志

```ts
emitLogWarn(message: string, ...args: unknown[]): void
```

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L337)

### emitNetworkError [#emitNetworkError]

发射网络错误事件

```ts
emitNetworkError(data: Omit<NetworkErrorEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<NetworkErrorEventData, &#x22;timestamp&#x22;>', description: '错误数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L299)

### emitNetworkRetry [#emitNetworkRetry]

发射网络重试事件

```ts
emitNetworkRetry(data: Omit<NetworkRetryEventData, "timestamp">): void
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'Omit<NetworkRetryEventData, &#x22;timestamp&#x22;>', description: '重试数据 (不含 timestamp)', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L291)

### fetchData [#fetchData]

执行网络请求并返回数据（带自动重试）

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：用 client fetcher / 

  `HttpClient`

  。返回的是 

  `ErrorResult`

  ，
  不是 

  `AmagiResult`

   信封
</Callout>

```ts
fetchData<T>(config: AxiosRequestConfig<T>, maxRetries: number): Promise<T | ErrorResult>
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;config&#x22;: { type: 'AxiosRequestConfig<T>', description: 'axios请求配置', required: true },
  &#x22;maxRetries&#x22;: { type: 'number', description: '最大重试次数，默认3次', default: 'DEFAULT_MAX_RETRIES', required: true }
}"
/>

**返回值**：响应数据或错误结果

源码：[`src/transport/legacy.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/transport/legacy.ts#L99)

### fetchResponse [#fetchResponse]

执行网络请求并返回完整响应（带自动重试）

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：用 client fetcher / 

  `HttpClient`

  。返回的是 

  `ErrorResult`

  ，
  不是 

  `AmagiResult`

   信封
</Callout>

```ts
fetchResponse<T>(config: AxiosRequestConfig, maxRetries: number): Promise<AxiosResponse<T> | ErrorResult>
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;config&#x22;: { type: 'AxiosRequestConfig', description: 'axios请求配置', required: true },
  &#x22;maxRetries&#x22;: { type: 'number', description: '最大重试次数，默认3次', default: 'DEFAULT_MAX_RETRIES', required: true }
}"
/>

**返回值**：完整响应或错误结果

源码：[`src/transport/legacy.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/transport/legacy.ts#L160)

### getBilibiliCorrespondPath [#getBilibiliCorrespondPath]

生成 correspondPath。

`hex(RSA-OAEP-SHA256("refresh_" + ts))`。注意 node 的 `publicEncrypt` 默认 OAEP 摘要是
**sha1**，这里必须显式 `oaepHash: 'sha256'`，否则服务端解不出。OAEP 带随机 seed，所以
同一个 ts 每次输出都不同 —— 正常，服务端只校验能否解出 `refresh_{ts}` 且 ts 新鲜。

```ts
getBilibiliCorrespondPath(ts: number): string
```

<TypeTable
  type="{
  &#x22;ts&#x22;: { type: 'number', description: '毫秒时间戳，优先传cookie/info返回的服务器时间，缺省用Date.now()', default: 'Date.now()', required: true }
}"
/>

**返回值**：256 位小写 hex 字符串

源码：[`src/platforms/bilibili/cookieRefresh.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/cookieRefresh.ts#L74)

### handleError [#handleError]

处理错误并返回统一格式

```ts
handleError(error: unknown, requestPath?: string): { code: number; data: null; errors: Array<{ field: string; message: string }>; message: string; platform: string; requestPath: string }
```

<TypeTable
  type="{
  &#x22;error&#x22;: { type: 'unknown', description: '错误对象', required: true },
  &#x22;requestPath&#x22;: { type: 'string', description: 'HTTP请求路径（可选）' }
}"
/>

**返回值**：统一的错误响应格式

源码：[`src/utils/errors.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/utils/errors.ts#L66)

### isDouyinCookieUsable [#isDouyinCookieUsable]

```ts
isDouyinCookieUsable(cookie?: string | null, options: CheckDouyinLoginStateOptions): Promise<boolean>
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string | null' },
  &#x22;options&#x22;: { type: 'CheckDouyinLoginStateOptions', default: '{}', required: true }
}"
/>

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L99)

### isFailure [#isFailure]

失败信封的类型守卫。

与 [`isSuccess`](/docs/v7/usage/api/types/functions#isSuccess) 对称，`list.filter(isFailure)` 之后 `r.error` 是
`AmagiError`（不带 `| undefined`），可以直接按 `kind` 分流。

```ts
isFailure<T>(result: AmagiResult<T>): result is AmagiFailure
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;result&#x22;: { type: 'AmagiResult<T>', description: '任意信封', required: true }
}"
/>

**返回值**：是失败信封时为 `true`，并把类型收窄到 [`AmagiFailure`](/docs/v7/usage/api/types/interfaces#AmagiFailure)

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L116)

### isNetworkErrorResult [#isNetworkErrorResult]

判断结果是否为网络错误响应

```ts
isNetworkErrorResult(result: unknown): result is ErrorResult
```

<TypeTable
  type="{
  &#x22;result&#x22;: { type: 'unknown', description: '请求结果', required: true }
}"
/>

**返回值**：是否为网络错误

识别两种形状：`success: false` 且 `error.amagiError` 存在（本模块返回的
`ErrorResult`），或 `error.kind === 'network'`（v7 失败信封），两代结果都能判。

源码：[`src/transport/legacy.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/transport/legacy.ts#L217)

### isSuccess [#isSuccess]

成功信封的类型守卫。

`?: undefined` 让「不收窄直接读」不再报错，但&#x2A;*收窄不到 `T`**（还是
`T | undefined`）。数组回调里没有 `if` 可用，`filter` 又只认类型谓词
—— 这就是必须有守卫的场景：

```ts twoslash
import { isSuccess, type AmagiResult } from '@ikenxuan/amagi'

declare const ids: string[]
declare const fetchOne: (id: string) => Promise<AmagiResult<Work>>
interface Work {
  id: string
}

const list: AmagiResult<Work>[] = await Promise.all(ids.map(fetchOne))
const works = list.filter(isSuccess).map((r) => r.data)   // Work[]
```

```ts
isSuccess<T>(result: AmagiResult<T>): result is AmagiSuccess<T>
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;result&#x22;: { type: 'AmagiResult<T>', description: '任意信封', required: true }
}"
/>

**返回值**：是成功信封时为 `true`，并把类型收窄到 [`AmagiSuccess`](/docs/v7/usage/api/types/interfaces#AmagiSuccess)

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L106)

### mintDouyinGuestCookie [#mintDouyinGuestCookie]

显式获取服务端签发的游客凭据，缓存未命中时请求抖音首页。

是 `mintDouyinGuestHandshake` 的**串形态**，公开出口（经 `./utils.ts` 导出）。
返回类型没变（`string | null`），但**返回 `null` 的判据变了**：以前是「没拿到访客 id」，
现在是「这一发什么都没拿到」。服务端只发了 `ttwid` 而扣下 `UIFID_TEMP` 时，这里交出
`ttwid=…` —— 调用方要分「拿到游客凭据」与「只拿到设备标识」请用结构化那一支
（`./credential.ts` 就是那么做的）。

挑战页不解析、不执行。普通数据端点不会自动触发这条握手，必须由宿主主动调用。

```ts
mintDouyinGuestCookie(options: MintDouyinGuestCookieOptions): Promise<string | null>
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'MintDouyinGuestCookieOptions', description: '传输与 UA 选项', default: '{}', required: true }
}"
/>

**返回值**：到手的凭据串；失败或一无所得时 `null`

源码：[`src/platforms/douyin/guestCredential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/guestCredential.ts#L233)

### normalizeDouyinCookie [#normalizeDouyinCookie]

修复粘贴进来的 cookie 文本，解析与序列化仍交给共享的 contract。

```ts
normalizeDouyinCookie(raw?: string | null): NormalizedDouyinCookie
```

<TypeTable
  type="{
  &#x22;raw&#x22;: { type: 'string | null' }
}"
/>

源码：[`src/platforms/douyin/cookie.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/cookie.ts#L20)

### parseDmSegMobileReply [#parseDmSegMobileReply]

解析弹幕分段响应

```ts
parseDmSegMobileReply(data: ArrayBuffer | Uint8Array): BiliProtobufDanmaku["data"]["elems"][number]
```

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'ArrayBuffer | Uint8Array', description: '二进制 protobuf 数据', required: true }
}"
/>

**返回值**：解析后的弹幕数据

源码：[`src/platforms/bilibili/decode/danmaku.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/decode/danmaku.ts#L87)

### parseDouyinCaptcha [#parseDouyinCaptcha]

从抖音响应里识别验证码挑战并拼出验证页地址。

装在 `client/runtime.ts` 的 `PLATFORM_RUNTIME.douyin.challenge` 上，
`runtime/execute.ts` 在 judge 判出 `kind: 'risk'` 时调用，结果进 `error.challenge`
—— **不受 `debug` 开关影响**。

两条通道，响应头优先（取舍见模块注释）：

1. **响应头**：只认 2xx，与 SDK、与 judge 的响应头通道一致。
2. **响应体**：滑块中间页 HTML。**不按 2xx 设闸** —— 这一支的挑战就是响应体本身，
   不是 SDK 的指令，服务器拿什么状态码回这张页都算数。

头上拼不出地址时**继续往下试响应体**，而不是直接放弃：两条通道互补，有一条能给出
可打开的地址就不该空手而归。

**滑块只中转不绕过**：这里只把地址与票据交出去，不含任何识别或轨迹模拟代码；
它也永远不进自动重放（见 `anticrawler/solver.ts`）。

```ts
parseDouyinCaptcha(raw: unknown, http?: { headers: JudgeHeaders; status: number }): RiskChallenge | undefined
```

<TypeTable
  type="{
  &#x22;raw&#x22;: { type: 'unknown', description: 'decode 之后的响应体。响应头通道用不到它，响应体通道认的就是它', required: true },
  &#x22;http&#x22;: { type: '{ headers: JudgeHeaders; status: number }', description: '本次响应的 HTTP 状态与响应头' }
}"
/>

**返回值**：风控挑战；两条通道都不认时 undefined

源码：[`src/platforms/douyin/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/captcha.ts#L161)

### parseKuaishouCaptcha [#parseKuaishouCaptcha]

从快手响应里识别风控并取出滑块地址。

PC 与 H5 两种格式都认，归一成同一个结果 —— 地址一律是**人能直接打开的验证页**，
H5 那条会把配置接口地址拼进 `VERIFY_PAGE_ENTRY`。

装在 `PLATFORM_RUNTIME.kuaishou.challenge` 上由管线自动调用，所以正常路径下
调用方直接读失败信封的 `error.challenge` 就够，不必自己调这个函数。

```ts
parseKuaishouCaptcha(raw: unknown): KuaishouCaptchaChallenge | undefined
```

<TypeTable
  type="{
  &#x22;raw&#x22;: { type: 'unknown', description: 'decode 之后的原始响应体', required: true }
}"
/>

**返回值**：风控挑战；没命中风控返回 undefined

源码：[`src/platforms/kuaishou/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/captcha.ts#L230)

### parseXiaohongshuCaptcha [#parseXiaohongshuCaptcha]

从小红书响应头里识别验证码挑战并拼出验证页地址。

装在 `client/runtime.ts` 的 `PLATFORM_RUNTIME.xiaohongshu.challenge` 上，
`runtime/execute.ts` 在 judge 判出 `kind: 'risk'` 时调用，结果进 `error.challenge`
—— **不受 `debug` 开关影响**（若只从 `error.raw` 取，HTTP 路由那一面结构上拿不到，
理由见 `contracts/error.ts` 的 `RiskChallenge`）。所以正常路径下调用方直接读失败
信封的 `error.challenge` 就够，不必自己调这个函数。

**没有 `verifyuuid` 就什么都不给**：没票据的验证页打开只是一个空壳，
宁可不给，也不交出一个过不去的地址。

```ts
parseXiaohongshuCaptcha(_raw: unknown, http?: { headers: JudgeHeaders; status: number }): RiskChallenge | undefined
```

<TypeTable
  type="{
  &#x22;_raw&#x22;: { type: 'unknown', description: 'decode 之后的响应体。小红书的信号全在响应头上，这里用不到', required: true },
  &#x22;http&#x22;: { type: '{ headers: JudgeHeaders; status: number }', description: '本次响应的 HTTP 状态与响应头' }
}"
/>

**返回值**：风控挑战；响应头里没有验证票据时 undefined

源码：[`src/platforms/xiaohongshu/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/xiaohongshu/captcha.ts#L114)

### qtparam [#qtparam]

生成B站视频流请求参数

```ts
qtparam(BASEURL: string, cookie: string): Promise<{ isvip: undefined; QUERY: string; STATUS: string } | { isvip: true; QUERY: string; STATUS: string } | { isvip: false; QUERY: string; STATUS: string }>
```

<TypeTable
  type="{
  &#x22;BASEURL&#x22;: { type: 'string', description: '基础请求URL', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '用户Cookie', required: true }
}"
/>

**返回值**：包含查询参数、登录状态和VIP状态的对象

源码：[`src/platforms/legacy/bilibili/qtparam.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/bilibili/qtparam.ts#L11)

### refreshBilibiliCredential [#refreshBilibiliCredential]

B站 Web 端 Cookie 刷新（登录态续期，官方四步协议）。

只中转不绕过 —— 走的是平台正规续期通道，不涉及任何风控对抗。调用方拿到新的
`{ cookie, refreshToken }` 后**必须整组持久化替换旧值**：下次刷新从新状态开始，
旧 token 已在第 4 步作废，再用旧 token 刷会 `86095`。

```ts
refreshBilibiliCredential(input: BilibiliRefreshInput, deps: BilibiliRefreshDeps, _options?: RequestConfig): Promise<{ credential: BilibiliRefreshOutput; ok: true } | { error: AmagiError; ok: false }>
```

<TypeTable
  type="{
  &#x22;input&#x22;: { type: 'BilibiliRefreshInput', description: '旧 cookie + 旧 refresh_token', required: true },
  &#x22;deps&#x22;: { type: 'BilibiliRefreshDeps', description: '发请求的send（由 client 用 transport 注入）', required: true },
  &#x22;_options&#x22;: { type: 'RequestConfig', description: '预留请求配置位（当前未用；代理/超时由注入的 send 承载）' }
}"
/>

**返回值**：成功给新凭证；失败给 AmagiError

源码：[`src/platforms/bilibili/cookieRefresh.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/cookieRefresh.ts#L138)

### renderVerifyPage [#renderVerifyPage]

把风控 challenge 渲染成自包含的验证页 HTML，调用方自己起 HTTP 服务返回给真人即可。

抖音 challenge 带 `jsSdkUrl` + `verifyData` 时默认页内渲染官方滑块，可切到托管模式；
其余情况（快手、小红书、抖音只有 `url`）只有托管模式。非 http(s) 的地址一律丢弃。

```ts
renderVerifyPage(challenge: RiskChallenge, options: VerifyPageOptions): string
```

<TypeTable
  type="{
  &#x22;challenge&#x22;: { type: 'RiskChallenge', description: '失败信封里的error.challenge', required: true },
  &#x22;options&#x22;: { type: 'VerifyPageOptions', description: '平台与标题', required: true }
}"
/>

**返回值**：完整 HTML 文本

源码：[`src/verify/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/verify/index.ts#L64)

### requestPassportQrcode [#requestPassportQrcode]

申请抖音扫码登录二维码

首次调用会自动完成环境指纹初始化（`__ac_nonce` + `ttwid`），无需额外准备。

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：请用 

  `client.douyin.login.qrcode()`

  （会话抽象：
  取码 / 轮询 / challenge 由引擎编排，

  `expire_time`

   秒转 

  `expiresAt`

   毫秒）。
</Callout>

```ts
requestPassportQrcode(options?: undefined, cookie?: string, requestConfig?: RequestConfig): Promise<Result<DouyinReturnTypeMap["passportQrcode"]>>
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'undefined', description: '请求选项 (可选)' },
  &#x22;cookie&#x22;: { type: 'string', description: '已有的会话 Cookie (可选，续用同一会话时传入)' },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '请求配置 (可选)' }
}"
/>

**返回值**：二维码令牌、内容与会话 cookie

**示例**

```ts
const qrcode = await requestPassportQrcode()
console.log(qrcode.data.content) // 拿去生成二维码图片
```

源码：[`src/model/fetchers/douyin/auth.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/auth.ts#L136)

### resolveDouyinCredential [#resolveDouyinCredential]

显式解析凭据。没有账号会话时，可通过游客握手补齐缺失的设备标识。

握手会向抖音首页发两次请求（签名纯算，不执行页面脚本）。只想在本地规范化请用
`normalizeDouyinCookie`，或传 `noGuestFallback: true` 关闭握手。
`needLogin: true` 会探测登录态，并始终保留账号凭据，不会用游客凭据替换。

```ts
resolveDouyinCredential(cookie?: string | null, options: ResolveOptions): Promise<ResolvedDouyinCredential>
```

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string | null' },
  &#x22;options&#x22;: { type: 'ResolveOptions', default: '{}', required: true }
}"
/>

源码：[`src/platforms/douyin/credential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/credential.ts#L34)

### sendPassportVerifyCode [#sendPassportVerifyCode]

向账号绑定手机发送二次验证短信验证码

用于轮询返回 `status: 'verify'`（即 `error_code=2046` / `account_flow=verify`）的场景。

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：请用 

  `client.douyin.login.qrcode()`

   的 

  `onChallenge`

   回调
  （

  `challenge.sendCode()`

  ，

  `biz_trace_id`

   / 

  `verify_way`

   由引擎维护）。
</Callout>

```ts
sendPassportVerifyCode(options: DouyinPassportSendCodeOptions, cookie?: string, requestConfig?: RequestConfig): Promise<Result<DouyinReturnTypeMap["passportSendCode"]>>
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'DouyinPassportSendCodeOptions', description: '发码参数', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '会话 Cookie' },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '请求配置 (可选)' }
}"
/>

**返回值**：脱敏手机号、重发等待秒数与追踪 ID

源码：[`src/model/fetchers/douyin/auth.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/auth.ts#L236)

### unwrap [#unwrap]

取成功信封的 `data`，失败就抛。

返回类型是 `T`，不是 `T | undefined` —— 这是它与「不收窄直接读 `r.data`」的
全部区别：愿意让失败沿调用栈往上冒的人用它，不愿意的人继续写 `if (r.success)`。
管线本身永不 reject（硬约束），`unwrap` 是调用方**显式**把失败转成异常。

与 `@ikenxuan/amagi/compat` 不重叠：`unwrap` 是单点显式选择（想抛就抛，
一处一处地写）；compat 是 v6 语义的**整体回填**（把整个 fetcher 的返回值换回
v6 信封，含顶层 `code`）。要 v6 行为用 compat，要 v7 信封加异常用 `unwrap`。

```ts
unwrap<T>(result: AmagiResult<T>): T
```

类型参数：`T`

<TypeTable
  type="{
  &#x22;result&#x22;: { type: 'AmagiResult<T>', description: '任意信封', required: true }
}"
/>

**返回值**：成功信封的 `data`

**可能抛出**：\{AmagiThrownError} 失败信封时抛出：`AmagiError` 全字段平铺，`cause` 不丢

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L180)

### validateBilibiliParams [#validateBilibiliParams]

验证哔哩哔哩参数（不抛错）

```ts
validateBilibiliParams<T>(methodType: T, params: unknown): ValidateOutcome<zod.infer<typeof …[T]>>
```

类型参数：`T extends BilibiliMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '哔哩哔哩方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：`ValidateOutcome`：成功带 value，失败带字段级 issues

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L63)

### validateDouyinParams [#validateDouyinParams]

验证抖音参数（不抛错）

```ts
validateDouyinParams<T>(methodType: T, params: unknown): ValidateOutcome<zod.infer<typeof …[T]>>
```

类型参数：`T extends DouyinMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '抖音方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：`ValidateOutcome`：成功带 value，失败带字段级 issues

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L47)

### validateKuaishouParams [#validateKuaishouParams]

验证快手参数（不抛错）

```ts
validateKuaishouParams<T>(methodType: T, params: unknown): ValidateOutcome<zod.infer<typeof …[T]>>
```

类型参数：`T extends KuaishouMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '快手方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：`ValidateOutcome`：成功带 value，失败带字段级 issues

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L79)

### validatePassportVerifyCode [#validatePassportVerifyCode]

提交二次验证的短信验证码

<Callout type="warn">
  **已废弃（`@deprecated`）**

  ：请用 

  `client.douyin.login.qrcode()`

   的 

  `onChallenge`

   回调
  （返回 

  `{ code }`

   即可，

  `biz_trace_id`

   / 

  `verify_way`

   由引擎维护）。
</Callout>

```ts
validatePassportVerifyCode(options: DouyinPassportValidateCodeOptions, cookie?: string, requestConfig?: RequestConfig): Promise<Result<DouyinReturnTypeMap["passportValidateCode"]>>
```

<TypeTable
  type="{
  &#x22;options&#x22;: { type: 'DouyinPassportValidateCodeOptions', description: '验码参数', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '会话 Cookie' },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '请求配置 (可选)' }
}"
/>

**返回值**：验证结果；`wrongCode` 为 true 表示验证码填错，可以让用户重试

源码：[`src/model/fetchers/douyin/auth.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/auth.ts#L274)

### validateXiaohongshuParams [#validateXiaohongshuParams]

验证小红书参数（不抛错）

```ts
validateXiaohongshuParams<T>(methodType: T, params: unknown): ValidateOutcome<zod.infer<typeof …[T]>>
```

类型参数：`T extends XiaohongshuMethodType`

<TypeTable
  type="{
  &#x22;methodType&#x22;: { type: 'T', description: '小红书方法类型', required: true },
  &#x22;params&#x22;: { type: 'unknown', description: '待验证的参数', required: true }
}"
/>

**返回值**：`ValidateOutcome`：成功带 value，失败带字段级 issues

源码：[`src/validation/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/index.ts#L95)

### wbi\_sign [#wbi_sign]

对请求链接进行 WBI 签名

```ts
wbi_sign(BASEURL: string | URL, cookie: string): Promise<string>
```

<TypeTable
  type="{
  &#x22;BASEURL&#x22;: { type: 'string | URL', description: '完整的请求地址，可以是字符串或 URL 对象', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '有效的用户 Cookie 字符串', required: true }
}"
/>

**返回值**：返回包含 WBI 签名的查询字符串

**可能抛出**：当获取 WBI 密钥失败或 URL 解析失败时抛出错误

源码：[`src/platforms/legacy/bilibili/sign/wbi.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/bilibili/sign/wbi.ts#L115)


# 类型索引 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types)

> 481 个公开导出的总索引，按页面分组



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页索引 481 个符号，覆盖 `@ikenxuan/amagi` 的**全部公开导出**（`src/index.ts`
  的导出面）。每个符号的签名、参数表与源码位置在它自己那一页；同一批能力的
  **HTTP 形态**见 [HTTP 端点参考](/docs/v7/usage/api/http)，**SDK 形态**见
  [各平台 SDK 方法页](/docs/v7/usage/api/sdk/douyin)。
</Callout>

## 函数 [#函数]

| 符号                                                                                                  | 种类 | 说明 |
| --------------------------------------------------------------------------------------------------- | -- | -- |
| [`assertValidBilibiliParams`](/docs/v7/usage/api/types/functions#assertValidBilibiliParams)         | 函数 |    |
| [`assertValidDouyinParams`](/docs/v7/usage/api/types/functions#assertValidDouyinParams)             | 函数 |    |
| [`assertValidKuaishouParams`](/docs/v7/usage/api/types/functions#assertValidKuaishouParams)         | 函数 |    |
| [`assertValidXiaohongshuParams`](/docs/v7/usage/api/types/functions#assertValidXiaohongshuParams)   | 函数 |    |
| [`av2bv`](/docs/v7/usage/api/types/functions#av2bv)                                                 | 函数 |    |
| [`bv2av`](/docs/v7/usage/api/types/functions#bv2av)                                                 | 函数 |    |
| [`checkDouyinLoginState`](/docs/v7/usage/api/types/functions#checkDouyinLoginState)                 | 函数 |    |
| [`checkPassportQrcode`](/docs/v7/usage/api/types/functions#checkPassportQrcode)                     | 函数 |    |
| [`clearDouyinLoginStateCache`](/docs/v7/usage/api/types/functions#clearDouyinLoginStateCache)       | 函数 |    |
| [`configureDouyinGuestCache`](/docs/v7/usage/api/types/functions#configureDouyinGuestCache)         | 函数 |    |
| [`createBilibiliRoutes`](/docs/v7/usage/api/types/functions#createBilibiliRoutes)                   | 函数 |    |
| [`createBoundBilibiliFetcher`](/docs/v7/usage/api/types/functions#createBoundBilibiliFetcher)       | 函数 |    |
| [`createBoundDouyinFetcher`](/docs/v7/usage/api/types/functions#createBoundDouyinFetcher)           | 函数 |    |
| [`createBoundKuaishouFetcher`](/docs/v7/usage/api/types/functions#createBoundKuaishouFetcher)       | 函数 |    |
| [`createBoundXiaohongshuFetcher`](/docs/v7/usage/api/types/functions#createBoundXiaohongshuFetcher) | 函数 |    |
| [`createClient`](/docs/v7/usage/api/types/functions#createClient)                                   | 函数 |    |
| [`createDouyinRoutes`](/docs/v7/usage/api/types/functions#createDouyinRoutes)                       | 函数 |    |
| [`createErrorResponse`](/docs/v7/usage/api/types/functions#createErrorResponse)                     | 函数 |    |
| [`createKuaishouRoutes`](/docs/v7/usage/api/types/functions#createKuaishouRoutes)                   | 函数 |    |
| [`createSuccessResponse`](/docs/v7/usage/api/types/functions#createSuccessResponse)                 | 函数 |    |
| [`createXiaohongshuRoutes`](/docs/v7/usage/api/types/functions#createXiaohongshuRoutes)             | 函数 |    |
| [`emitApiError`](/docs/v7/usage/api/types/functions#emitApiError)                                   | 函数 |    |
| [`emitApiSuccess`](/docs/v7/usage/api/types/functions#emitApiSuccess)                               | 函数 |    |
| [`emitHttpRequest`](/docs/v7/usage/api/types/functions#emitHttpRequest)                             | 函数 |    |
| [`emitHttpResponse`](/docs/v7/usage/api/types/functions#emitHttpResponse)                           | 函数 |    |
| [`emitLog`](/docs/v7/usage/api/types/functions#emitLog)                                             | 函数 |    |
| [`emitLogDebug`](/docs/v7/usage/api/types/functions#emitLogDebug)                                   | 函数 |    |
| [`emitLogError`](/docs/v7/usage/api/types/functions#emitLogError)                                   | 函数 |    |
| [`emitLogInfo`](/docs/v7/usage/api/types/functions#emitLogInfo)                                     | 函数 |    |
| [`emitLogMark`](/docs/v7/usage/api/types/functions#emitLogMark)                                     | 函数 |    |
| [`emitLogWarn`](/docs/v7/usage/api/types/functions#emitLogWarn)                                     | 函数 |    |
| [`emitNetworkError`](/docs/v7/usage/api/types/functions#emitNetworkError)                           | 函数 |    |
| [`emitNetworkRetry`](/docs/v7/usage/api/types/functions#emitNetworkRetry)                           | 函数 |    |
| [`fetchData`](/docs/v7/usage/api/types/functions#fetchData)                                         | 函数 |    |
| [`fetchResponse`](/docs/v7/usage/api/types/functions#fetchResponse)                                 | 函数 |    |
| [`getBilibiliCorrespondPath`](/docs/v7/usage/api/types/functions#getBilibiliCorrespondPath)         | 函数 |    |
| [`handleError`](/docs/v7/usage/api/types/functions#handleError)                                     | 函数 |    |
| [`isDouyinCookieUsable`](/docs/v7/usage/api/types/functions#isDouyinCookieUsable)                   | 函数 |    |
| [`isFailure`](/docs/v7/usage/api/types/functions#isFailure)                                         | 函数 |    |
| [`isNetworkErrorResult`](/docs/v7/usage/api/types/functions#isNetworkErrorResult)                   | 函数 |    |
| [`isSuccess`](/docs/v7/usage/api/types/functions#isSuccess)                                         | 函数 |    |
| [`mintDouyinGuestCookie`](/docs/v7/usage/api/types/functions#mintDouyinGuestCookie)                 | 函数 |    |
| [`normalizeDouyinCookie`](/docs/v7/usage/api/types/functions#normalizeDouyinCookie)                 | 函数 |    |
| [`parseDmSegMobileReply`](/docs/v7/usage/api/types/functions#parseDmSegMobileReply)                 | 函数 |    |
| [`parseDouyinCaptcha`](/docs/v7/usage/api/types/functions#parseDouyinCaptcha)                       | 函数 |    |
| [`parseKuaishouCaptcha`](/docs/v7/usage/api/types/functions#parseKuaishouCaptcha)                   | 函数 |    |
| [`parseXiaohongshuCaptcha`](/docs/v7/usage/api/types/functions#parseXiaohongshuCaptcha)             | 函数 |    |
| [`qtparam`](/docs/v7/usage/api/types/functions#qtparam)                                             | 函数 |    |
| [`refreshBilibiliCredential`](/docs/v7/usage/api/types/functions#refreshBilibiliCredential)         | 函数 |    |
| [`renderVerifyPage`](/docs/v7/usage/api/types/functions#renderVerifyPage)                           | 函数 |    |
| [`requestPassportQrcode`](/docs/v7/usage/api/types/functions#requestPassportQrcode)                 | 函数 |    |
| [`resolveDouyinCredential`](/docs/v7/usage/api/types/functions#resolveDouyinCredential)             | 函数 |    |
| [`sendPassportVerifyCode`](/docs/v7/usage/api/types/functions#sendPassportVerifyCode)               | 函数 |    |
| [`unwrap`](/docs/v7/usage/api/types/functions#unwrap)                                               | 函数 |    |
| [`validateBilibiliParams`](/docs/v7/usage/api/types/functions#validateBilibiliParams)               | 函数 |    |
| [`validateDouyinParams`](/docs/v7/usage/api/types/functions#validateDouyinParams)                   | 函数 |    |
| [`validateKuaishouParams`](/docs/v7/usage/api/types/functions#validateKuaishouParams)               | 函数 |    |
| [`validatePassportVerifyCode`](/docs/v7/usage/api/types/functions#validatePassportVerifyCode)       | 函数 |    |
| [`validateXiaohongshuParams`](/docs/v7/usage/api/types/functions#validateXiaohongshuParams)         | 函数 |    |
| [`wbi_sign`](/docs/v7/usage/api/types/functions#wbi_sign)                                           | 函数 |    |

## 类、枚举与变量 [#类枚举与变量]

| 符号                                                                                                  | 种类   | 说明                                                                                                                   |
| --------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------- |
| [`AdditionalType`](/docs/v7/usage/api/types/classes#AdditionalType)                                 | 枚举   | 相关内容卡片类型枚举 用于标识动态中附加的相关内容卡片的类型                                                                                       |
| [`amagi`](/docs/v7/usage/api/types/classes#amagi)                                                   | 变量   |                                                                                                                      |
| [`AMAGI_BUS_EVENT_NAMES`](/docs/v7/usage/api/types/classes#AMAGI_BUS_EVENT_NAMES)                   | 变量   | 全部事件名（12 个与 v6 对齐 + 3 个会话事件），用于遍历与穷尽性校验。  与 \[`AmagiBusEventMap`]\(/docs/v7/usage/api/types/…                        |
| [`amagiEvents`](/docs/v7/usage/api/types/classes#amagiEvents)                                       | 变量   | Amagi 全局事件发射器实例                                                                                                      |
| [`AmagiThrownError`](/docs/v7/usage/api/types/classes#AmagiThrownError)                             | 类    | [`unwrap`](/docs/v7/usage/api/types/functions#unwrap) 失败时抛出的 Error 子类。  为什么不直接 …                                     |
| [`ApiError`](/docs/v7/usage/api/types/classes#ApiError)                                             | 类    | API错误类                                                                                                               |
| [`BILIBILI_CORRESPOND_PUBKEY`](/docs/v7/usage/api/types/classes#BILIBILI_CORRESPOND_PUBKEY)         | 变量   | B站 correspondPath 的 RSA 公钥（1024bit）。  删库前官方文档公开的明文公钥，多来源字节一致。correspondPath = 用它 RSA-OAEP-…                          |
| [`bilibiliApiUrls`](/docs/v7/usage/api/types/classes#bilibiliApiUrls)                               | 变量   | B站 URL 构造器（v6 实现）。v7 门面（`client.bilibili`）上的是 `apiUrls`（v7 那份，在 …                                                    |
| [`bilibiliFetcher`](/docs/v7/usage/api/types/classes#bilibiliFetcher)                               | 变量   | B站数据获取器（静态）。 包含所有 B站 API 方法，调用时需要传递 cookie                                                                           |
| [`bilibiliUtils`](/docs/v7/usage/api/types/classes#bilibiliUtils)                                   | 变量   | B站相关功能模块 (工具集)                                                                                                       |
| [`createAmagiClient`](/docs/v7/usage/api/types/classes#createAmagiClient)                           | 变量   | 创建Amagi客户端实例                                                                                                         |
| [`CreateApp`](/docs/v7/usage/api/types/classes#CreateApp)                                           | 变量   | After instantiation, it can interact with the specified platform API to quickly obtain dat…                          |
| [`default`](/docs/v7/usage/api/types/classes#default)                                               | 变量   | After instantiation, it can interact with the specified platform API to quickly obtain dat…                          |
| [`douyinApiUrls`](/docs/v7/usage/api/types/classes#douyinApiUrls)                                   | 变量   | 抖音 URL 构造器（v6 实现）。v7 门面（`client.douyin`）上的是 `apiUrls`（v7 那份，在 `platforms/douyin/api.ts`）；这…                          |
| [`douyinFetcher`](/docs/v7/usage/api/types/classes#douyinFetcher)                                   | 变量   | 抖音数据获取器（静态）。 包含所有抖音 API 方法，调用时需要传递 cookie                                                                            |
| [`douyinPassport`](/docs/v7/usage/api/types/classes#douyinPassport)                                 | 命名空间 | 抖音 passport 扫码登录协议实现  login.douyin.com 的接口与 [www.douyin.com](http://www.douyin.com) 的数据接口是两套体系： - query 需要 `p_no` /… |
| [`douyinSign`](/docs/v7/usage/api/types/classes#douyinSign)                                         | 类    |                                                                                                                      |
| [`douyinUtils`](/docs/v7/usage/api/types/classes#douyinUtils)                                       | 变量   | 抖音相关功能模块 (工具集)                                                                                                       |
| [`DynamicType`](/docs/v7/usage/api/types/classes#DynamicType)                                       | 枚举   | 动态类型枚举  独立成叶子模块：Dynamic 子树各叶子类型文件都要用它做判别字段， 若定义在 `DynamicInfo/index.ts` 会形成叶子反向导入 barrel 的…                          |
| [`KUAISHOU_H5_CAPTCHA_RESULT`](/docs/v7/usage/api/types/classes#KUAISHOU_H5_CAPTCHA_RESULT)         | 变量   | H5 REST 的风控业务码                                                                                                       |
| [`KUAISHOU_PC_CAPTCHA_RESULT`](/docs/v7/usage/api/types/classes#KUAISHOU_PC_CAPTCHA_RESULT)         | 变量   | PC GraphQL 的风控业务码                                                                                                    |
| [`kuaishouApiUrls`](/docs/v7/usage/api/types/classes#kuaishouApiUrls)                               | 变量   | 快手 URL 构造器（v6 实现）。v7 门面（`client.kuaishou`）上的是 `apiUrls`（v7 那份，在 …                                                    |
| [`kuaishouFetcher`](/docs/v7/usage/api/types/classes#kuaishouFetcher)                               | 变量   | 快手数据获取器（静态）。 包含所有快手 API 方法，调用时需要传递 cookie                                                                            |
| [`kuaishouSign`](/docs/v7/usage/api/types/classes#kuaishouSign)                                     | 类    | 快手签名工具集。  负责将请求描述对象转换为带 `__NS_hxfalcon` / `kww` 的最终请求材料。                                                             |
| [`kuaishouUtils`](/docs/v7/usage/api/types/classes#kuaishouUtils)                                   | 变量   | 快手相关功能模块 (工具集)                                                                                                       |
| [`MajorType`](/docs/v7/usage/api/types/classes#MajorType)                                           | 枚举   | 转发动态种子动态主体类型枚举                                                                                                       |
| [`ValidationError`](/docs/v7/usage/api/types/classes#ValidationError)                               | 类    | 参数验证错误类                                                                                                              |
| [`XIAOHONGSHU_ANTI_SPAM_STATUS`](/docs/v7/usage/api/types/classes#XIAOHONGSHU_ANTI_SPAM_STATUS)     | 变量   | 反垃圾状态码。平台 redcaptcha SDK 里的名字是 `antiSpam`                                                                            |
| [`XIAOHONGSHU_ANTI_SPIDER_STATUS`](/docs/v7/usage/api/types/classes#XIAOHONGSHU_ANTI_SPIDER_STATUS) | 变量   | 反爬状态码。平台 redcaptcha SDK 里的名字是 `antiSpider`                                                                           |
| [`xiaohongshuApiUrls`](/docs/v7/usage/api/types/classes#xiaohongshuApiUrls)                         | 变量   | 小红书 URL 构造器（v6 实现）。v7 门面（`client.xiaohongshu`）上的是 `apiUrls`（v7 那份，在 …                                                |
| [`xiaohongshuFetcher`](/docs/v7/usage/api/types/classes#xiaohongshuFetcher)                         | 变量   | 小红书数据获取器（静态）。 包含所有小红书 API 方法，调用时需要传递 cookie                                                                          |
| [`xiaohongshuSign`](/docs/v7/usage/api/types/classes#xiaohongshuSign)                               | 类    | 小红书签名算法类                                                                                                             |
| [`xiaohongshuUtils`](/docs/v7/usage/api/types/classes#xiaohongshuUtils)                             | 变量   | 小红书相关功能模块 (工具集)                                                                                                      |

## 接口 [#接口]

| 符号                                                                                                     | 种类 | 说明                                                                                               |
| ------------------------------------------------------------------------------------------------------ | -- | ------------------------------------------------------------------------------------------------ |
| [`AmagiAxiosTrack`](/docs/v7/usage/api/types/interfaces#AmagiAxiosTrack)                               | 接口 | axios 轨。  与信封轨共用同一个实例、同一套 `defaults` / `interceptors` —— 差别只有一处： 失败的判据是「信封是不是失败信封」时，这里\*\*抛\*…   |
| [`AmagiBusEventMap`](/docs/v7/usage/api/types/interfaces#AmagiBusEventMap)                             | 接口 | 事件名 → 负载的映射（**实例级总线**用；顶层导出的 `AmagiEventMap` 描述的是 全局单例 `amagiEvents`，是另一张表）。  名字不与 …             |
| [`AmagiError`](/docs/v7/usage/api/types/interfaces#AmagiError)                                         | 接口 | 失败信封里唯一的错误载体，永不为 `undefined`                                                                     |
| [`AmagiEventMap`](/docs/v7/usage/api/types/interfaces#AmagiEventMap)                                   | 接口 | 事件类型到数据的映射                                                                                       |
| [`AmagiFailure`](/docs/v7/usage/api/types/interfaces#AmagiFailure)                                     | 接口 | 失败信封                                                                                             |
| [`AmagiMeta`](/docs/v7/usage/api/types/interfaces#AmagiMeta)                                           | 接口 | 挂在每个信封上的元信息                                                                                      |
| [`AmagiRequest`](/docs/v7/usage/api/types/interfaces#AmagiRequest)                                     | 接口 | 平台的请求模块。  打的是**任何 URL**（包括 amagi 还没收录的接口），自动带上实例 ck 与平台签名， 走与 fetcher 同一条 `execute` 管线与同一套…      |
| [`AmagiRequestConfig`](/docs/v7/usage/api/types/interfaces#AmagiRequestConfig)                         | 接口 | `client.<平台>.request` 的入参。  在 axios 配置之上做两处**收窄**，都是为了让「不可能发生的事」编译不过： - 去掉 `adapter` —— 传它…      |
| [`AmagiRequestOptions`](/docs/v7/usage/api/types/interfaces#AmagiRequestOptions)                       | 接口 | 单次请求的 amagi 专属选项。  挂在 axios 配置的 `amagi` 键下（…                                                     |
| [`AmagiSuccess`](/docs/v7/usage/api/types/interfaces#AmagiSuccess)                                     | 接口 | 成功信封                                                                                             |
| [`ApiErrorEventData`](/docs/v7/usage/api/types/interfaces#ApiErrorEventData)                           | 接口 | API 错误事件数据                                                                                       |
| [`ApiSuccessEventData`](/docs/v7/usage/api/types/interfaces#ApiSuccessEventData)                       | 接口 | API 成功事件数据                                                                                       |
| [`BilibiliFetcher`](/docs/v7/usage/api/types/interfaces#BilibiliFetcher)                               | 接口 | B站 Fetcher 类型（静态形态：三参签名）。  写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名， 打印器（IDE … |
| [`BilibiliMethodOptionsMap`](/docs/v7/usage/api/types/interfaces#BilibiliMethodOptionsMap)             | 接口 | B站 API 方法参数映射接口  每个键对应一种 API 方法，值为该方法所需的参数接口                                                     |
| [`BilibiliRefreshInput`](/docs/v7/usage/api/types/interfaces#BilibiliRefreshInput)                     | 接口 | 刷新入参                                                                                             |
| [`BilibiliRefreshOutput`](/docs/v7/usage/api/types/interfaces#BilibiliRefreshOutput)                   | 接口 | 刷新产物                                                                                             |
| [`BilibiliReturnTypeMap`](/docs/v7/usage/api/types/interfaces#BilibiliReturnTypeMap)                   | 接口 | B站返回类型映射  将 methodType 映射到对应的返回数据类型                                                              |
| [`BoundBilibiliFetcher`](/docs/v7/usage/api/types/interfaces#BoundBilibiliFetcher)                     | 接口 | 绑定 Cookie 的B站 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。  名义接口，理由同 \[…               |
| [`BoundDouyinFetcher`](/docs/v7/usage/api/types/interfaces#BoundDouyinFetcher)                         | 接口 | 绑定 Cookie 的抖音 Fetcher 类型（形状 = `FetcherOf`，两参签名）。  名义接口，理由同 \[`DouyinStaticFetcher`]\(/docs/v…    |
| [`BoundKuaishouFetcher`](/docs/v7/usage/api/types/interfaces#BoundKuaishouFetcher)                     | 接口 | 绑定 Cookie 的快手 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。  名义接口，理由同 \[…               |
| [`BoundXiaohongshuFetcher`](/docs/v7/usage/api/types/interfaces#BoundXiaohongshuFetcher)               | 接口 | 绑定 Cookie 的小红书 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。  名义接口，理由同 \[…              |
| [`CaptchaChallenge`](/docs/v7/usage/api/types/interfaces#CaptchaChallenge)                             | 接口 | 图形验证码 challenge                                                                                  |
| [`CheckDouyinLoginStateOptions`](/docs/v7/usage/api/types/interfaces#CheckDouyinLoginStateOptions)     | 接口 |                                                                                                  |
| [`ClientOptions`](/docs/v7/usage/api/types/interfaces#ClientOptions)                                   | 接口 | 客户端构造选项                                                                                          |
| [`Credential`](/docs/v7/usage/api/types/interfaces#Credential)                                         | 接口 | 跨平台统一的登录凭证                                                                                       |
| [`DouyinCredentialRequestOptions`](/docs/v7/usage/api/types/interfaces#DouyinCredentialRequestOptions) | 接口 | 凭据请求与 API 请求走同一套 transport/代理/adapter。                                                           |
| [`DouyinFetcher`](/docs/v7/usage/api/types/interfaces#DouyinFetcher)                                   | 接口 | 抖音 Fetcher 类型（静态形态：三参签名 + 4 个 passport 方法）。  名义接口，理由同 \[`DouyinStaticFetcher`]\(/docs/v7/usa…    |
| [`DouyinLoginCheck`](/docs/v7/usage/api/types/interfaces#DouyinLoginCheck)                             | 接口 |                                                                                                  |
| [`DouyinMethodOptionsMap`](/docs/v7/usage/api/types/interfaces#DouyinMethodOptionsMap)                 | 接口 | 抖音 API 方法参数映射接口  每个键对应一种 API 方法，值为该方法所需的参数接口                                                     |
| [`DouyinReturnTypeMap`](/docs/v7/usage/api/types/interfaces#DouyinReturnTypeMap)                       | 接口 | 抖音返回类型映射  将 methodType 映射到对应的返回数据类型                                                              |
| [`DouyinStaticFetcher`](/docs/v7/usage/api/types/interfaces#DouyinStaticFetcher)                       | 接口 | 抖音静态 fetcher 的类型（不含 passport，纯 registry 派生形态）。  写成 &#x2A;*`interface … extends`** 而不是 …          |
| [`DyPassportQrcode`](/docs/v7/usage/api/types/interfaces#DyPassportQrcode)                             | 接口 | 登录二维码                                                                                            |
| [`DyPassportSendCodeResult`](/docs/v7/usage/api/types/interfaces#DyPassportSendCodeResult)             | 接口 | 发码接口归一化后的结果，不含会话字段                                                                               |
| [`DyPassportValidateCodeResult`](/docs/v7/usage/api/types/interfaces#DyPassportValidateCodeResult)     | 接口 | 验码接口归一化后的结果，不含会话字段                                                                               |
| [`DyPassportVerifyContext`](/docs/v7/usage/api/types/interfaces#DyPassportVerifyContext)               | 接口 | 二次验证上下文  字段全部来自轮询响应，需原样透传给发码与验码接口，缺字段会被判为伪造请求。                                                   |
| [`DyPassportVerifyWay`](/docs/v7/usage/api/types/interfaces#DyPassportVerifyWay)                       | 接口 | 二次验证的一种可选方式                                                                                      |
| [`EventBus`](/docs/v7/usage/api/types/interfaces#EventBus)                                             | 接口 | 类型安全的事件总线。  一个 client 实例一条。构造两条就是两条，彼此不共享监听器。                                                    |
| [`FacadeServerOptions`](/docs/v7/usage/api/types/interfaces#FacadeServerOptions)                       | 接口 | 门面版 `startServer` 的第二参。  只透出 `openapi` 一项；`port` / `host` / `token` / `routers` 这些全选项留给 …        |
| [`HttpRequestEventData`](/docs/v7/usage/api/types/interfaces#HttpRequestEventData)                     | 接口 | HTTP 请求事件数据                                                                                      |
| [`HttpResponseEventData`](/docs/v7/usage/api/types/interfaces#HttpResponseEventData)                   | 接口 | HTTP 响应事件数据                                                                                      |
| [`KuaishouCaptchaChallenge`](/docs/v7/usage/api/types/interfaces#KuaishouCaptchaChallenge)             | 接口 | 交给调用方的风控挑战                                                                                       |
| [`KuaishouFetcher`](/docs/v7/usage/api/types/interfaces#KuaishouFetcher)                               | 接口 | 快手 Fetcher 类型（静态形态：三参签名）。  写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名， 打印器（IDE … |
| [`KuaishouMethodOptionsMap`](/docs/v7/usage/api/types/interfaces#KuaishouMethodOptionsMap)             | 接口 | 快手 API 方法参数映射                                                                                    |
| [`KuaishouReturnTypeMap`](/docs/v7/usage/api/types/interfaces#KuaishouReturnTypeMap)                   | 接口 | 快手返回类型映射                                                                                         |
| [`LogEventData`](/docs/v7/usage/api/types/interfaces#LogEventData)                                     | 接口 | 日志事件数据                                                                                           |
| [`LoginNamespace`](/docs/v7/usage/api/types/interfaces#LoginNamespace)                                 | 接口 | 登录命名空间：qrcode() 创建会话，resume() 从 opaque string 恢复                                                 |
| [`LoginSession`](/docs/v7/usage/api/types/interfaces#LoginSession)                                     | 接口 | 登录会话：三种消费方式（回调 / AsyncIterable / 手动单步）。  返回终态时永不 reject（除调用方回调自己抛出）。                             |
| [`MintDouyinGuestCookieOptions`](/docs/v7/usage/api/types/interfaces#MintDouyinGuestCookieOptions)     | 接口 |                                                                                                  |
| [`NetworkErrorEventData`](/docs/v7/usage/api/types/interfaces#NetworkErrorEventData)                   | 接口 | 网络错误事件数据                                                                                         |
| [`NetworkRetryEventData`](/docs/v7/usage/api/types/interfaces#NetworkRetryEventData)                   | 接口 | 网络重试事件数据                                                                                         |
| [`NormalizedDouyinCookie`](/docs/v7/usage/api/types/interfaces#NormalizedDouyinCookie)                 | 接口 |                                                                                                  |
| [`Qrcode`](/docs/v7/usage/api/types/interfaces#Qrcode)                                                 | 接口 | 二维码                                                                                              |
| [`QrcodeLoginStrategy`](/docs/v7/usage/api/types/interfaces#QrcodeLoginStrategy)                       | 接口 | 平台扫码登录策略。  轮询循环 / 超时 / 退避 / 取消全在引擎里，策略只写协议细节。                                                    |
| [`RequestTrace`](/docs/v7/usage/api/types/interfaces#RequestTrace)                                     | 接口 | 单次底层 HTTP 请求的明细                                                                                  |
| [`ResolvedDouyinCredential`](/docs/v7/usage/api/types/interfaces#ResolvedDouyinCredential)             | 接口 |                                                                                                  |
| [`ResolveDouyinCredentialOptions`](/docs/v7/usage/api/types/interfaces#ResolveDouyinCredentialOptions) | 接口 |                                                                                                  |
| [`RiskChallenge`](/docs/v7/usage/api/types/interfaces#RiskChallenge)                                   | 接口 | 风控挑战：撞验证页时交给调用方的「怎么过去」。  为什么不塞进 `JudgeVerdict`：judge 只管**分类**，四个槽位装不下一个 URL。但 …                  |
| [`SessionCtx`](/docs/v7/usage/api/types/interfaces#SessionCtx)                                         | 接口 | 平台会话上下文。  由引擎创建并逐次轮询更新；平台私有字段（biz\_trace\_id / verify\_way / verifyTicket / encryptUid / stdP…   |
| [`SmsChallenge`](/docs/v7/usage/api/types/interfaces#SmsChallenge)                                     | 接口 | 短信验证码 challenge                                                                                  |
| [`SuccessBilibiliFetcher`](/docs/v7/usage/api/types/interfaces#SuccessBilibiliFetcher)                 | 接口 | 只保留成功分支的B站 fetcher 类型。  给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成 这个类型，`.data` 就是 `T` …      |
| [`SuccessDouyinFetcher`](/docs/v7/usage/api/types/interfaces#SuccessDouyinFetcher)                     | 接口 | 只保留成功分支的抖音 fetcher 类型。  给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成 这个类型，`.data` 就是 `T` …      |
| [`SuccessKuaishouFetcher`](/docs/v7/usage/api/types/interfaces#SuccessKuaishouFetcher)                 | 接口 | 只保留成功分支的快手 fetcher 类型。  给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成 这个类型，`.data` 就是 `T` …      |
| [`SuccessXiaohongshuFetcher`](/docs/v7/usage/api/types/interfaces#SuccessXiaohongshuFetcher)           | 接口 | 只保留成功分支的小红书 fetcher 类型。  给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成 这个类型，`.data` 就是 `T`…      |
| [`ValidationIssue`](/docs/v7/usage/api/types/interfaces#ValidationIssue)                               | 接口 | `kind === 'validation'` 时的字段级错误                                                                  |
| [`VerifyPageOptions`](/docs/v7/usage/api/types/interfaces#VerifyPageOptions)                           | 接口 | [`renderVerifyPage`](/docs/v7/usage/api/types/functions#renderVerifyPage) 的选项                    |
| [`WatchHandlers`](/docs/v7/usage/api/types/interfaces#WatchHandlers)                                   | 接口 | 会话回调（watch 出口）                                                                                   |
| [`WatchOptions`](/docs/v7/usage/api/types/interfaces#WatchOptions)                                     | 接口 | 会话 watch 选项                                                                                      |
| [`XiaohongshuFetcher`](/docs/v7/usage/api/types/interfaces#XiaohongshuFetcher)                         | 接口 | 小红书 Fetcher 类型（静态形态：三参签名）。  写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名， 打印器（IDE… |
| [`XiaohongshuMethodOptionsMap`](/docs/v7/usage/api/types/interfaces#XiaohongshuMethodOptionsMap)       | 接口 | 小红书 API 方法参数映射                                                                                   |
| [`XiaohongshuReturnTypeMap`](/docs/v7/usage/api/types/interfaces#XiaohongshuReturnTypeMap)             | 接口 | 小红书返回类型映射                                                                                        |
| [`XiaohongshuSessionInput`](/docs/v7/usage/api/types/interfaces#XiaohongshuSessionInput)               | 接口 | 小红书同一会话的 Cookie 与可选签名材料；不属于 HTTP 请求配置。                                                           |

## 核心类型 [#核心类型]

| 符号                                                                                | 种类   | 说明                                                                                            |
| --------------------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------- |
| [`AmagiBusEventName`](/docs/v7/usage/api/types/types#AmagiBusEventName)           | 类型别名 | 事件名                                                                                           |
| [`AmagiErrorCode`](/docs/v7/usage/api/types/types#AmagiErrorCode)                 | 类型别名 | 稳定的字符串错误码，可用于 `switch` 与埋点。  用字符串字面量联合而不是 `enum`：`enum` 的 `Object.values()` 会带出反向映射键， 且拿平台…   |
| [`AmagiEventType`](/docs/v7/usage/api/types/types#AmagiEventType)                 | 类型别名 | Amagi 支持的事件类型                                                                                 |
| [`AmagiRequestMethod`](/docs/v7/usage/api/types/types#AmagiRequestMethod)         | 类型别名 | 单次调用（信封轨）                                                                                     |
| [`AmagiResult`](/docs/v7/usage/api/types/types#AmagiResult)                       | 类型别名 | 所有对外 API 的唯一返回类型                                                                              |
| [`BilibiliMethodType`](/docs/v7/usage/api/types/types#BilibiliMethodType)         | 类型别名 | B站方法类型                                                                                        |
| [`ChallengeAnswer`](/docs/v7/usage/api/types/types#ChallengeAnswer)               | 类型别名 | 按 challenge 的 kind 决定应答的形状。  条件类型是「回调返回错字段编译期报错」的落点： `c.kind === 'sms'` 收窄后 `C` 推断为 …         |
| [`CommentType`](/docs/v7/usage/api/types/types#CommentType)                       | 类型别名 | B站评论区类型代码（`comments` / `commentReplies` 的 `type` 参数）。  完整对照表（部分 oid 含义官方未明确，转写自 bilibili-A…   |
| [`CookieConfig`](/docs/v7/usage/api/types/types#CookieConfig)                     | 类型别名 | Cookie配置选项接口                                                                                  |
| [`DouyinCredentialOrigin`](/docs/v7/usage/api/types/types#DouyinCredentialOrigin) | 类型别名 | 这份凭据是怎么来的。  `guest-minted` 与 `guest-device` 的分界是**有没有拿到访客 id**，不是「握手有没有出货」： 服务端把「挑战过没过」与「发…   |
| [`DouyinLoginState`](/docs/v7/usage/api/types/types#DouyinLoginState)             | 类型别名 |                                                                                               |
| [`DouyinMethodType`](/docs/v7/usage/api/types/types#DouyinMethodType)             | 类型别名 | 抖音方法类型                                                                                        |
| [`DouyinUifidSource`](/docs/v7/usage/api/types/types#DouyinUifidSource)           | 类型别名 |                                                                                               |
| [`ErrorKind`](/docs/v7/usage/api/types/types#ErrorKind)                           | 类型别名 | 跨平台统一的错误大类，也是调用方唯一需要 `switch` 的判别键。  粗粒度归因用 `kind`，细粒度归因用 \[`AmagiErrorCode`]\(/docs/v7/usag… |
| [`KuaishouGraphqlRequest`](/docs/v7/usage/api/types/types#KuaishouGraphqlRequest) | 类型别名 | 快手 GraphQL 请求描述对象。  该结构只负责描述请求，不负责执行网络请求。                                                     |
| [`KuaishouLiveApiRequest`](/docs/v7/usage/api/types/types#KuaishouLiveApiRequest) | 类型别名 | 快手 `live_api` 请求描述对象。  除了最终请求地址外，还可以携带 `signPath`，用于声明 `__NS_hxfalcon` 实际参与签名的规范路径。           |
| [`KuaishouMethodType`](/docs/v7/usage/api/types/types#KuaishouMethodType)         | 类型别名 |                                                                                               |
| [`LoginChallenge`](/docs/v7/usage/api/types/types#LoginChallenge)                 | 类型别名 | 二次验证 challenge                                                                                |
| [`LoginState`](/docs/v7/usage/api/types/types#LoginState)                         | 类型别名 | 登录会话的状态。判别键是 phase                                                                            |
| [`Options`](/docs/v7/usage/api/types/types#Options)                               | 类型别名 | 客户端配置选项接口  形状冻结不动。`ClientOptions` 是它的超集（多一个 `debug`）， 两者赋值互通，所以 …                             |
| [`Platform`](/docs/v7/usage/api/types/types#Platform)                             | 类型别名 | amagi 支持的平台                                                                                   |
| [`RequestConfig`](/docs/v7/usage/api/types/types#RequestConfig)                   | 类型别名 | 请求配置选项接口  与 `contracts/request.ts` 的同名类型逐字相同（顶层导出的就是 contracts 那一份）。新代码请用 contracts 的。        |
| [`TraceReason`](/docs/v7/usage/api/types/types#TraceReason)                       | 类型别名 | 一次底层请求的发起原因。  区分「端点内重试」与「传输层重试」、「翻页」与「分段并发」， 是排查请求数叠乘的入口。                                     |
| [`VerifyPlatform`](/docs/v7/usage/api/types/types#VerifyPlatform)                 | 类型别名 | 有风控 challenge 的平台（B 站没有 challenge 提取器）                                                        |

## B站响应类型 [#b站响应类型]

| 符号                                                                                                                               | 种类   | 说明 |
| -------------------------------------------------------------------------------------------------------------------------------- | ---- | -- |
| [`ArticleCard`](/docs/v7/usage/api/types/types-bilibili#ArticleCard)                                                             | 类型别名 |    |
| [`ArticleContent`](/docs/v7/usage/api/types/types-bilibili#ArticleContent)                                                       | 类型别名 |    |
| [`ArticleInfo`](/docs/v7/usage/api/types/types-bilibili#ArticleInfo)                                                             | 类型别名 |    |
| [`BiliAv2Bv`](/docs/v7/usage/api/types/types-bilibili#BiliAv2Bv)                                                                 | 类型别名 |    |
| [`BiliBangumiVideoInfo`](/docs/v7/usage/api/types/types-bilibili#BiliBangumiVideoInfo)                                           | 类型别名 |    |
| [`BiliBangumiVideoPlayurlIsLogin`](/docs/v7/usage/api/types/types-bilibili#BiliBangumiVideoPlayurlIsLogin)                       | 类型别名 |    |
| [`BiliBangumiVideoPlayurlNoLogin`](/docs/v7/usage/api/types/types-bilibili#BiliBangumiVideoPlayurlNoLogin)                       | 类型别名 |    |
| [`BilibiliArticleCardsResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleCardsResponse)                           | 类型别名 |    |
| [`BilibiliArticleCardsResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleCardsResponseError)                 | 类型别名 |    |
| [`BilibiliArticleCardsResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleCardsResponseSuccess)             | 类型别名 |    |
| [`BilibiliArticleContentResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleContentResponse)                       | 类型别名 |    |
| [`BilibiliArticleContentResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleContentResponseError)             | 类型别名 |    |
| [`BilibiliArticleContentResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleContentResponseSuccess)         | 类型别名 |    |
| [`BilibiliArticleInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleInfoResponse)                             | 类型别名 |    |
| [`BilibiliArticleInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleInfoResponseError)                   | 类型别名 |    |
| [`BilibiliArticleInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleInfoResponseSuccess)               | 类型别名 |    |
| [`BilibiliArticleListInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleListInfoResponse)                     | 类型别名 |    |
| [`BilibiliArticleListInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleListInfoResponseError)           | 类型别名 |    |
| [`BilibiliArticleListInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliArticleListInfoResponseSuccess)       | 类型别名 |    |
| [`BilibiliBangumiInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiInfoResponse)                             | 类型别名 |    |
| [`BilibiliBangumiInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiInfoResponseError)                   | 类型别名 |    |
| [`BilibiliBangumiInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiInfoResponseSuccess)               | 类型别名 |    |
| [`BilibiliBangumiStreamResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiStreamResponse)                         | 类型别名 |    |
| [`BilibiliBangumiStreamResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiStreamResponseError)               | 类型别名 |    |
| [`BilibiliBangumiStreamResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliBangumiStreamResponseSuccess)           | 类型别名 |    |
| [`BilibiliCommentRepliesResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentRepliesResponse)                       | 类型别名 |    |
| [`BilibiliCommentRepliesResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentRepliesResponseError)             | 类型别名 |    |
| [`BilibiliCommentRepliesResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentRepliesResponseSuccess)         | 类型别名 |    |
| [`BilibiliCommentsResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentsResponse)                                   | 类型别名 |    |
| [`BilibiliCommentsResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentsResponseError)                         | 类型别名 |    |
| [`BilibiliCommentsResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliCommentsResponseSuccess)                     | 类型别名 |    |
| [`BilibiliDynamicDetailResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliDynamicDetailResponse)                         | 类型别名 |    |
| [`BilibiliDynamicDetailResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliDynamicDetailResponseError)               | 类型别名 |    |
| [`BilibiliDynamicDetailResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliDynamicDetailResponseSuccess)           | 类型别名 |    |
| [`BilibiliEmojiListResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliEmojiListResponse)                                 | 类型别名 |    |
| [`BilibiliEmojiListResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliEmojiListResponseError)                       | 类型别名 |    |
| [`BilibiliEmojiListResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliEmojiListResponseSuccess)                   | 类型别名 |    |
| [`BilibiliLiveRoomInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInfoResponse)                           | 类型别名 |    |
| [`BilibiliLiveRoomInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInfoResponseError)                 | 类型别名 |    |
| [`BilibiliLiveRoomInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInfoResponseSuccess)             | 类型别名 |    |
| [`BilibiliLiveRoomInitResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInitResponse)                           | 类型别名 |    |
| [`BilibiliLiveRoomInitResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInitResponseError)                 | 类型别名 |    |
| [`BilibiliLiveRoomInitResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliLiveRoomInitResponseSuccess)             | 类型别名 |    |
| [`BilibiliLoginQrcodeResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginQrcodeResponse)                             | 类型别名 |    |
| [`BilibiliLoginQrcodeResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginQrcodeResponseError)                   | 类型别名 |    |
| [`BilibiliLoginQrcodeResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginQrcodeResponseSuccess)               | 类型别名 |    |
| [`BilibiliLoginStatusResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginStatusResponse)                             | 类型别名 |    |
| [`BilibiliLoginStatusResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginStatusResponseError)                   | 类型别名 |    |
| [`BilibiliLoginStatusResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliLoginStatusResponseSuccess)               | 类型别名 |    |
| [`BilibiliQrcodeStatusResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliQrcodeStatusResponse)                           | 类型别名 |    |
| [`BilibiliQrcodeStatusResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliQrcodeStatusResponseError)                 | 类型别名 |    |
| [`BilibiliQrcodeStatusResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliQrcodeStatusResponseSuccess)             | 类型别名 |    |
| [`BilibiliUploaderTotalViewsResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliUploaderTotalViewsResponse)               | 类型别名 |    |
| [`BilibiliUploaderTotalViewsResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliUploaderTotalViewsResponseError)     | 类型别名 |    |
| [`BilibiliUploaderTotalViewsResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliUploaderTotalViewsResponseSuccess) | 类型别名 |    |
| [`BilibiliUserCardResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserCardResponse)                                   | 类型别名 |    |
| [`BilibiliUserCardResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserCardResponseError)                         | 类型别名 |    |
| [`BilibiliUserCardResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserCardResponseSuccess)                     | 类型别名 |    |
| [`BilibiliUserDynamicListResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserDynamicListResponse)                     | 类型别名 |    |
| [`BilibiliUserDynamicListResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserDynamicListResponseError)           | 类型别名 |    |
| [`BilibiliUserDynamicListResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserDynamicListResponseSuccess)       | 类型别名 |    |
| [`BilibiliUserLiveStatusResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserLiveStatusResponse)                       | 类型别名 |    |
| [`BilibiliUserLiveStatusResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserLiveStatusResponseError)             | 类型别名 |    |
| [`BilibiliUserLiveStatusResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserLiveStatusResponseSuccess)         | 类型别名 |    |
| [`BilibiliUserSpaceInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserSpaceInfoResponse)                         | 类型别名 |    |
| [`BilibiliUserSpaceInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserSpaceInfoResponseError)               | 类型别名 |    |
| [`BilibiliUserSpaceInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliUserSpaceInfoResponseSuccess)           | 类型别名 |    |
| [`BilibiliVideoDanmakuResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoDanmakuResponse)                           | 类型别名 |    |
| [`BilibiliVideoDanmakuResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoDanmakuResponseError)                 | 类型别名 |    |
| [`BilibiliVideoDanmakuResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoDanmakuResponseSuccess)             | 类型别名 |    |
| [`BilibiliVideoInfoResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoInfoResponse)                                 | 类型别名 |    |
| [`BilibiliVideoInfoResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoInfoResponseError)                       | 类型别名 |    |
| [`BilibiliVideoInfoResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoInfoResponseSuccess)                   | 类型别名 |    |
| [`BiliBiliVideoPlayurlNoLogin`](/docs/v7/usage/api/types/types-bilibili#BiliBiliVideoPlayurlNoLogin)                             | 类型别名 |    |
| [`BilibiliVideoStreamResponse`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoStreamResponse)                             | 类型别名 |    |
| [`BilibiliVideoStreamResponseError`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoStreamResponseError)                   | 类型别名 |    |
| [`BilibiliVideoStreamResponseSuccess`](/docs/v7/usage/api/types/types-bilibili#BilibiliVideoStreamResponseSuccess)               | 类型别名 |    |
| [`BiliBv2AV`](/docs/v7/usage/api/types/types-bilibili#BiliBv2AV)                                                                 | 类型别名 |    |
| [`BiliCheckQrcode`](/docs/v7/usage/api/types/types-bilibili#BiliCheckQrcode)                                                     | 类型别名 |    |
| [`BiliCommentReply`](/docs/v7/usage/api/types/types-bilibili#BiliCommentReply)                                                   | 类型别名 |    |
| [`BiliDynamicInfo`](/docs/v7/usage/api/types/types-bilibili#BiliDynamicInfo)                                                     | 类型别名 |    |
| [`BiliDynamicInfoUnion`](/docs/v7/usage/api/types/types-bilibili#BiliDynamicInfoUnion)                                           | 类型别名 |    |
| [`BiliEmojiList`](/docs/v7/usage/api/types/types-bilibili#BiliEmojiList)                                                         | 类型别名 |    |
| [`BiliLiveRoomDef`](/docs/v7/usage/api/types/types-bilibili#BiliLiveRoomDef)                                                     | 类型别名 |    |
| [`BiliLiveRoomDetail`](/docs/v7/usage/api/types/types-bilibili#BiliLiveRoomDetail)                                               | 类型别名 |    |
| [`BiliLoginStatus`](/docs/v7/usage/api/types/types-bilibili#BiliLoginStatus)                                                     | 类型别名 |    |
| [`BiliNewLoginQrcode`](/docs/v7/usage/api/types/types-bilibili#BiliNewLoginQrcode)                                               | 类型别名 |    |
| [`BiliOneWork`](/docs/v7/usage/api/types/types-bilibili#BiliOneWork)                                                             | 类型别名 |    |
| [`BiliProtobufDanmaku`](/docs/v7/usage/api/types/types-bilibili#BiliProtobufDanmaku)                                             | 类型别名 |    |
| [`BiliUserDynamic`](/docs/v7/usage/api/types/types-bilibili#BiliUserDynamic)                                                     | 类型别名 |    |
| [`BiliUserFullView`](/docs/v7/usage/api/types/types-bilibili#BiliUserFullView)                                                   | 类型别名 |    |
| [`BiliUserLiveStatus`](/docs/v7/usage/api/types/types-bilibili#BiliUserLiveStatus)                                               | 类型别名 |    |
| [`BiliUserProfile`](/docs/v7/usage/api/types/types-bilibili#BiliUserProfile)                                                     | 类型别名 |    |
| [`BiliVideoPlayurlIsLogin`](/docs/v7/usage/api/types/types-bilibili#BiliVideoPlayurlIsLogin)                                     | 类型别名 |    |
| [`BiliWorkComments`](/docs/v7/usage/api/types/types-bilibili#BiliWorkComments)                                                   | 类型别名 |    |
| [`ColumnInfo`](/docs/v7/usage/api/types/types-bilibili#ColumnInfo)                                                               | 类型别名 |    |
| [`DynamicTypeArticle`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeArticle)                                               | 类型别名 |    |
| [`DynamicTypeAV`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeAV)                                                         | 类型别名 |    |
| [`DynamicTypeDraw`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeDraw)                                                     | 类型别名 |    |
| [`DynamicTypeForward`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeForward)                                               | 类型别名 |    |
| [`DynamicTypeForwardUnion`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeForwardUnion)                                     | 类型别名 |    |
| [`DynamicTypeLiveRcmd`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeLiveRcmd)                                             | 类型别名 |    |
| [`DynamicTypeWord`](/docs/v7/usage/api/types/types-bilibili#DynamicTypeWord)                                                     | 类型别名 |    |

## 抖音响应类型 [#抖音响应类型]

| 符号                                                                                                                           | 种类   | 说明            |
| ---------------------------------------------------------------------------------------------------------------------------- | ---- | ------------- |
| [`ArticleWork`](/docs/v7/usage/api/types/types-douyin#ArticleWork)                                                           | 类型别名 |               |
| [`CommentReply`](/docs/v7/usage/api/types/types-douyin#CommentReply)                                                         | 类型别名 |               |
| [`DouyinCommentRepliesResponse`](/docs/v7/usage/api/types/types-douyin#DouyinCommentRepliesResponse)                         | 类型别名 |               |
| [`DouyinCommentRepliesResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinCommentRepliesResponseError)               | 类型别名 |               |
| [`DouyinCommentRepliesResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinCommentRepliesResponseSuccess)           | 类型别名 |               |
| [`DouyinCommentsResponse`](/docs/v7/usage/api/types/types-douyin#DouyinCommentsResponse)                                     | 类型别名 |               |
| [`DouyinCommentsResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinCommentsResponseError)                           | 类型别名 |               |
| [`DouyinCommentsResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinCommentsResponseSuccess)                       | 类型别名 |               |
| [`DouyinDanmakuListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinDanmakuListResponse)                               | 类型别名 |               |
| [`DouyinDanmakuListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinDanmakuListResponseError)                     | 类型别名 |               |
| [`DouyinDanmakuListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinDanmakuListResponseSuccess)                 | 类型别名 |               |
| [`DouyinDynamicEmojiListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinDynamicEmojiListResponse)                     | 类型别名 |               |
| [`DouyinDynamicEmojiListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinDynamicEmojiListResponseError)           | 类型别名 |               |
| [`DouyinDynamicEmojiListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinDynamicEmojiListResponseSuccess)       | 类型别名 |               |
| [`DouyinEmojiListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiListResponse)                                   | 类型别名 |               |
| [`DouyinEmojiListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiListResponseError)                         | 类型别名 |               |
| [`DouyinEmojiListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiListResponseSuccess)                     | 类型别名 |               |
| [`DouyinEmojiResourceMetaResponse`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiResourceMetaResponse)                   | 类型别名 |               |
| [`DouyinEmojiResourceMetaResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiResourceMetaResponseError)         | 类型别名 |               |
| [`DouyinEmojiResourceMetaResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinEmojiResourceMetaResponseSuccess)     | 类型别名 |               |
| [`DouyinGuestMusicAwemeListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicAwemeListResponse)               | 类型别名 |               |
| [`DouyinGuestMusicAwemeListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicAwemeListResponseError)     | 类型别名 |               |
| [`DouyinGuestMusicAwemeListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicAwemeListResponseSuccess) | 类型别名 |               |
| [`DouyinGuestMusicInfoResponse`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicInfoResponse)                         | 类型别名 |               |
| [`DouyinGuestMusicInfoResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicInfoResponseError)               | 类型别名 |               |
| [`DouyinGuestMusicInfoResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinGuestMusicInfoResponseSuccess)           | 类型别名 |               |
| [`DouyinGuestUserInfoResponse`](/docs/v7/usage/api/types/types-douyin#DouyinGuestUserInfoResponse)                           | 类型别名 |               |
| [`DouyinGuestUserInfoResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinGuestUserInfoResponseError)                 | 类型别名 |               |
| [`DouyinGuestUserInfoResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinGuestUserInfoResponseSuccess)             | 类型别名 |               |
| [`DouyinImageAlbumWorkResponse`](/docs/v7/usage/api/types/types-douyin#DouyinImageAlbumWorkResponse)                         | 类型别名 |               |
| [`DouyinImageAlbumWorkResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinImageAlbumWorkResponseError)               | 类型别名 |               |
| [`DouyinImageAlbumWorkResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinImageAlbumWorkResponseSuccess)           | 类型别名 |               |
| [`DouyinLiveRoomInfoResponse`](/docs/v7/usage/api/types/types-douyin#DouyinLiveRoomInfoResponse)                             | 类型别名 |               |
| [`DouyinLiveRoomInfoResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinLiveRoomInfoResponseError)                   | 类型别名 |               |
| [`DouyinLiveRoomInfoResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinLiveRoomInfoResponseSuccess)               | 类型别名 |               |
| [`DouyinMixAwemeResponse`](/docs/v7/usage/api/types/types-douyin#DouyinMixAwemeResponse)                                     | 类型别名 |               |
| [`DouyinMixAwemeResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinMixAwemeResponseError)                           | 类型别名 |               |
| [`DouyinMixAwemeResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinMixAwemeResponseSuccess)                       | 类型别名 |               |
| [`DouyinMusicAwemeListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinMusicAwemeListResponse)                         | 类型别名 |               |
| [`DouyinMusicAwemeListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinMusicAwemeListResponseError)               | 类型别名 |               |
| [`DouyinMusicAwemeListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinMusicAwemeListResponseSuccess)           | 类型别名 |               |
| [`DouyinMusicInfoResponse`](/docs/v7/usage/api/types/types-douyin#DouyinMusicInfoResponse)                                   | 类型别名 |               |
| [`DouyinMusicInfoResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinMusicInfoResponseError)                         | 类型别名 |               |
| [`DouyinMusicInfoResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinMusicInfoResponseSuccess)                     | 类型别名 |               |
| [`DouyinParseWorkResponse`](/docs/v7/usage/api/types/types-douyin#DouyinParseWorkResponse)                                   | 类型别名 |               |
| [`DouyinParseWorkResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinParseWorkResponseError)                         | 类型别名 |               |
| [`DouyinParseWorkResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinParseWorkResponseSuccess)                     | 类型别名 |               |
| [`DouyinSearchResponse`](/docs/v7/usage/api/types/types-douyin#DouyinSearchResponse)                                         | 类型别名 |               |
| [`DouyinSearchResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinSearchResponseError)                               | 类型别名 |               |
| [`DouyinSearchResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinSearchResponseSuccess)                           | 类型别名 |               |
| [`DouyinShortUrlResponse`](/docs/v7/usage/api/types/types-douyin#DouyinShortUrlResponse)                                     | 类型别名 |               |
| [`DouyinShortUrlResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinShortUrlResponseError)                           | 类型别名 |               |
| [`DouyinShortUrlResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinShortUrlResponseSuccess)                       | 类型别名 |               |
| [`DouyinSlidesWorkResponse`](/docs/v7/usage/api/types/types-douyin#DouyinSlidesWorkResponse)                                 | 类型别名 |               |
| [`DouyinSlidesWorkResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinSlidesWorkResponseError)                       | 类型别名 |               |
| [`DouyinSlidesWorkResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinSlidesWorkResponseSuccess)                   | 类型别名 |               |
| [`DouyinSuggestWordsResponse`](/docs/v7/usage/api/types/types-douyin#DouyinSuggestWordsResponse)                             | 类型别名 |               |
| [`DouyinSuggestWordsResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinSuggestWordsResponseError)                   | 类型别名 |               |
| [`DouyinSuggestWordsResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinSuggestWordsResponseSuccess)               | 类型别名 |               |
| [`DouyinTextWorkResponse`](/docs/v7/usage/api/types/types-douyin#DouyinTextWorkResponse)                                     | 类型别名 |               |
| [`DouyinTextWorkResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinTextWorkResponseError)                           | 类型别名 |               |
| [`DouyinTextWorkResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinTextWorkResponseSuccess)                       | 类型别名 |               |
| [`DouyinUserFavoriteListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinUserFavoriteListResponse)                     | 类型别名 |               |
| [`DouyinUserFavoriteListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinUserFavoriteListResponseError)           | 类型别名 |               |
| [`DouyinUserFavoriteListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinUserFavoriteListResponseSuccess)       | 类型别名 |               |
| [`DouyinUserProfileResponse`](/docs/v7/usage/api/types/types-douyin#DouyinUserProfileResponse)                               | 类型别名 |               |
| [`DouyinUserProfileResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinUserProfileResponseError)                     | 类型别名 |               |
| [`DouyinUserProfileResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinUserProfileResponseSuccess)                 | 类型别名 |               |
| [`DouyinUserRecommendListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinUserRecommendListResponse)                   | 类型别名 |               |
| [`DouyinUserRecommendListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinUserRecommendListResponseError)         | 类型别名 |               |
| [`DouyinUserRecommendListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinUserRecommendListResponseSuccess)     | 类型别名 |               |
| [`DouyinUserVideoListResponse`](/docs/v7/usage/api/types/types-douyin#DouyinUserVideoListResponse)                           | 类型别名 |               |
| [`DouyinUserVideoListResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinUserVideoListResponseError)                 | 类型别名 |               |
| [`DouyinUserVideoListResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinUserVideoListResponseSuccess)             | 类型别名 |               |
| [`DouyinVideoWorkResponse`](/docs/v7/usage/api/types/types-douyin#DouyinVideoWorkResponse)                                   | 类型别名 |               |
| [`DouyinVideoWorkResponseError`](/docs/v7/usage/api/types/types-douyin#DouyinVideoWorkResponseError)                         | 类型别名 |               |
| [`DouyinVideoWorkResponseSuccess`](/docs/v7/usage/api/types/types-douyin#DouyinVideoWorkResponseSuccess)                     | 类型别名 |               |
| [`DyDanmakuList`](/docs/v7/usage/api/types/types-douyin#DyDanmakuList)                                                       | 类型别名 |               |
| [`DyEmojiList`](/docs/v7/usage/api/types/types-douyin#DyEmojiList)                                                           | 类型别名 |               |
| [`DyEmojiProList`](/docs/v7/usage/api/types/types-douyin#DyEmojiProList)                                                     | 类型别名 |               |
| [`DyEmojiResourceMeta`](/docs/v7/usage/api/types/types-douyin#DyEmojiResourceMeta)                                           | 类型别名 |               |
| [`DyGuestMusicAwemeList`](/docs/v7/usage/api/types/types-douyin#DyGuestMusicAwemeList)                                       | 类型别名 |               |
| [`DyGuestMusicInfo`](/docs/v7/usage/api/types/types-douyin#DyGuestMusicInfo)                                                 | 类型别名 |               |
| [`DyGuestUserInfo`](/docs/v7/usage/api/types/types-douyin#DyGuestUserInfo)                                                   | 类型别名 |               |
| [`DyImageAlbumWork`](/docs/v7/usage/api/types/types-douyin#DyImageAlbumWork)                                                 | 类型别名 |               |
| [`DyLoginQrcode`](/docs/v7/usage/api/types/types-douyin#DyLoginQrcode)                                                       | 类型别名 |               |
| [`DyMusicWork`](/docs/v7/usage/api/types/types-douyin#DyMusicWork)                                                           | 类型别名 |               |
| [`DyPassportPollResult`](/docs/v7/usage/api/types/types-douyin#DyPassportPollResult)                                         | 类型别名 | 一次二维码轮询的归一化结果 |
| [`DyPassportQrcodeStatus`](/docs/v7/usage/api/types/types-douyin#DyPassportQrcodeStatus)                                     | 类型别名 | 二维码状态         |
| [`DyPassportSendCode`](/docs/v7/usage/api/types/types-douyin#DyPassportSendCode)                                             | 类型别名 | 发送短信验证码的结果    |
| [`DyPassportValidateCode`](/docs/v7/usage/api/types/types-douyin#DyPassportValidateCode)                                     | 类型别名 | 提交短信验证码的结果    |
| [`DySearchInfo`](/docs/v7/usage/api/types/types-douyin#DySearchInfo)                                                         | 类型别名 |               |
| [`DySlidesWork`](/docs/v7/usage/api/types/types-douyin#DySlidesWork)                                                         | 类型别名 |               |
| [`DySuggestWords`](/docs/v7/usage/api/types/types-douyin#DySuggestWords)                                                     | 类型别名 |               |
| [`DyUserInfo`](/docs/v7/usage/api/types/types-douyin#DyUserInfo)                                                             | 类型别名 |               |
| [`DyUserLiveVideos`](/docs/v7/usage/api/types/types-douyin#DyUserLiveVideos)                                                 | 类型别名 |               |
| [`DyUserPostVideos`](/docs/v7/usage/api/types/types-douyin#DyUserPostVideos)                                                 | 类型别名 |               |
| [`DyVideoWork`](/docs/v7/usage/api/types/types-douyin#DyVideoWork)                                                           | 类型别名 |               |
| [`DyWorkComments`](/docs/v7/usage/api/types/types-douyin#DyWorkComments)                                                     | 类型别名 |               |
| [`SearchInfoGeneralData`](/docs/v7/usage/api/types/types-douyin#SearchInfoGeneralData)                                       | 类型别名 |               |
| [`SearchInfoUser`](/docs/v7/usage/api/types/types-douyin#SearchInfoUser)                                                     | 类型别名 |               |
| [`SearchInfoVideo`](/docs/v7/usage/api/types/types-douyin#SearchInfoVideo)                                                   | 类型别名 |               |

## 快手 / 小红书 / 通用响应类型 [#快手--小红书--通用响应类型]

| 符号                                                                                                                       | 种类   | 说明                                            |
| ------------------------------------------------------------------------------------------------------------------------ | ---- | --------------------------------------------- |
| [`APIErrorType`](/docs/v7/usage/api/types/types-rest#APIErrorType)                                                       | 类型别名 | API请求错误类型 该类型是方法 `getXXXData` 封装后请求遇到错误时的返回类型 |
| [`BilibiliDataOptions`](/docs/v7/usage/api/types/types-rest#BilibiliDataOptions)                                         | 类型别名 |                                               |
| [`BilibiliDataOptionsMap`](/docs/v7/usage/api/types/types-rest#BilibiliDataOptionsMap)                                   | 类型别名 |                                               |
| [`BilibiliMethodOptMap`](/docs/v7/usage/api/types/types-rest#BilibiliMethodOptMap)                                       | 类型别名 | B站方法类型到参数的映射  用于根据 methodType 字符串获取对应的参数类型    |
| [`DouyinDataOptions`](/docs/v7/usage/api/types/types-rest#DouyinDataOptions)                                             | 类型别名 |                                               |
| [`DouyinDataOptionsMap`](/docs/v7/usage/api/types/types-rest#DouyinDataOptionsMap)                                       | 类型别名 |                                               |
| [`DouyinMethodOptMap`](/docs/v7/usage/api/types/types-rest#DouyinMethodOptMap)                                           | 类型别名 | 抖音方法类型到参数的映射  用于根据 methodType 字符串获取对应的参数类型    |
| [`HomeFeed`](/docs/v7/usage/api/types/types-rest#HomeFeed)                                                               | 类型别名 |                                               |
| [`KsBannedStatus`](/docs/v7/usage/api/types/types-rest#KsBannedStatus)                                                   | 类型别名 |                                               |
| [`KsDanmaku`](/docs/v7/usage/api/types/types-rest#KsDanmaku)                                                             | 类型别名 |                                               |
| [`KsEmojiList`](/docs/v7/usage/api/types/types-rest#KsEmojiList)                                                         | 类型别名 |                                               |
| [`KsLiveRoomInfo`](/docs/v7/usage/api/types/types-rest#KsLiveRoomInfo)                                                   | 类型别名 |                                               |
| [`KsOneWork`](/docs/v7/usage/api/types/types-rest#KsOneWork)                                                             | 类型别名 |                                               |
| [`KsUserHomeWork`](/docs/v7/usage/api/types/types-rest#KsUserHomeWork)                                                   | 类型别名 |                                               |
| [`KsUserProfile`](/docs/v7/usage/api/types/types-rest#KsUserProfile)                                                     | 类型别名 |                                               |
| [`KsUserProfileCounts`](/docs/v7/usage/api/types/types-rest#KsUserProfileCounts)                                         | 类型别名 |                                               |
| [`KsUserProfileGameInfo`](/docs/v7/usage/api/types/types-rest#KsUserProfileGameInfo)                                     | 类型别名 |                                               |
| [`KsUserProfileLiveInfo`](/docs/v7/usage/api/types/types-rest#KsUserProfileLiveInfo)                                     | 类型别名 |                                               |
| [`KsUserProfileSensitiveInfo`](/docs/v7/usage/api/types/types-rest#KsUserProfileSensitiveInfo)                           | 类型别名 |                                               |
| [`KsUserProfileUserInfo`](/docs/v7/usage/api/types/types-rest#KsUserProfileUserInfo)                                     | 类型别名 |                                               |
| [`KsUserWorkList`](/docs/v7/usage/api/types/types-rest#KsUserWorkList)                                                   | 类型别名 |                                               |
| [`KsVerifiedStatus`](/docs/v7/usage/api/types/types-rest#KsVerifiedStatus)                                               | 类型别名 |                                               |
| [`KsWorkComments`](/docs/v7/usage/api/types/types-rest#KsWorkComments)                                                   | 类型别名 |                                               |
| [`KuaishouCommentsResponse`](/docs/v7/usage/api/types/types-rest#KuaishouCommentsResponse)                               | 类型别名 |                                               |
| [`KuaishouCommentsResponseError`](/docs/v7/usage/api/types/types-rest#KuaishouCommentsResponseError)                     | 类型别名 |                                               |
| [`KuaishouCommentsResponseSuccess`](/docs/v7/usage/api/types/types-rest#KuaishouCommentsResponseSuccess)                 | 类型别名 |                                               |
| [`KuaishouDanmakuListResponse`](/docs/v7/usage/api/types/types-rest#KuaishouDanmakuListResponse)                         | 类型别名 |                                               |
| [`KuaishouDanmakuListResponseError`](/docs/v7/usage/api/types/types-rest#KuaishouDanmakuListResponseError)               | 类型别名 |                                               |
| [`KuaishouDanmakuListResponseSuccess`](/docs/v7/usage/api/types/types-rest#KuaishouDanmakuListResponseSuccess)           | 类型别名 |                                               |
| [`KuaishouDataOptions`](/docs/v7/usage/api/types/types-rest#KuaishouDataOptions)                                         | 类型别名 |                                               |
| [`KuaishouDataOptionsMap`](/docs/v7/usage/api/types/types-rest#KuaishouDataOptionsMap)                                   | 类型别名 |                                               |
| [`KuaishouEmojiListResponse`](/docs/v7/usage/api/types/types-rest#KuaishouEmojiListResponse)                             | 类型别名 |                                               |
| [`KuaishouEmojiListResponseError`](/docs/v7/usage/api/types/types-rest#KuaishouEmojiListResponseError)                   | 类型别名 |                                               |
| [`KuaishouEmojiListResponseSuccess`](/docs/v7/usage/api/types/types-rest#KuaishouEmojiListResponseSuccess)               | 类型别名 |                                               |
| [`KuaishouMethodOptMap`](/docs/v7/usage/api/types/types-rest#KuaishouMethodOptMap)                                       | 类型别名 | 快手方法类型到参数的映射                                  |
| [`KuaishouVideoWorkResponse`](/docs/v7/usage/api/types/types-rest#KuaishouVideoWorkResponse)                             | 类型别名 |                                               |
| [`KuaishouVideoWorkResponseError`](/docs/v7/usage/api/types/types-rest#KuaishouVideoWorkResponseError)                   | 类型别名 |                                               |
| [`KuaishouVideoWorkResponseSuccess`](/docs/v7/usage/api/types/types-rest#KuaishouVideoWorkResponseSuccess)               | 类型别名 |                                               |
| [`NetworksConfigType`](/docs/v7/usage/api/types/types-rest#NetworksConfigType)                                           | 类型别名 |                                               |
| [`NoteComments`](/docs/v7/usage/api/types/types-rest#NoteComments)                                                       | 类型别名 |                                               |
| [`OmitMethodType`](/docs/v7/usage/api/types/types-rest#OmitMethodType)                                                   | 类型别名 | 移除methodType字段的工具类型                           |
| [`OneNote`](/docs/v7/usage/api/types/types-rest#OneNote)                                                                 | 类型别名 |                                               |
| [`SearchNotes`](/docs/v7/usage/api/types/types-rest#SearchNotes)                                                         | 类型别名 |                                               |
| [`XiaohongshuDataOptions`](/docs/v7/usage/api/types/types-rest#XiaohongshuDataOptions)                                   | 类型别名 |                                               |
| [`XiaohongshuDataOptionsMap`](/docs/v7/usage/api/types/types-rest#XiaohongshuDataOptionsMap)                             | 类型别名 |                                               |
| [`XiaohongshuEmojiList`](/docs/v7/usage/api/types/types-rest#XiaohongshuEmojiList)                                       | 类型别名 |                                               |
| [`XiaohongshuEmojiListResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuEmojiListResponse)                       | 类型别名 |                                               |
| [`XiaohongshuEmojiListResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuEmojiListResponseError)             | 类型别名 |                                               |
| [`XiaohongshuEmojiListResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuEmojiListResponseSuccess)         | 类型别名 |                                               |
| [`XiaohongshuHomeFeedResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuHomeFeedResponse)                         | 类型别名 |                                               |
| [`XiaohongshuHomeFeedResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuHomeFeedResponseError)               | 类型别名 |                                               |
| [`XiaohongshuHomeFeedResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuHomeFeedResponseSuccess)           | 类型别名 |                                               |
| [`XiaohongshuLiveRoomResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveRoomResponse)                         | 类型别名 |                                               |
| [`XiaohongshuLiveRoomResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveRoomResponseError)               | 类型别名 |                                               |
| [`XiaohongshuLiveRoomResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveRoomResponseSuccess)           | 类型别名 |                                               |
| [`XiaohongshuLiveSquareResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveSquareResponse)                     | 类型别名 |                                               |
| [`XiaohongshuLiveSquareResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveSquareResponseError)           | 类型别名 |                                               |
| [`XiaohongshuLiveSquareResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveSquareResponseSuccess)       | 类型别名 |                                               |
| [`XiaohongshuLiveStatusResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveStatusResponse)                     | 类型别名 |                                               |
| [`XiaohongshuLiveStatusResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveStatusResponseError)           | 类型别名 |                                               |
| [`XiaohongshuLiveStatusResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuLiveStatusResponseSuccess)       | 类型别名 |                                               |
| [`XiaohongshuMethodOptMap`](/docs/v7/usage/api/types/types-rest#XiaohongshuMethodOptMap)                                 | 类型别名 | 小红书方法类型到参数的映射                                 |
| [`XiaohongshuNoteCommentsResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteCommentsResponse)                 | 类型别名 |                                               |
| [`XiaohongshuNoteCommentsResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteCommentsResponseError)       | 类型别名 |                                               |
| [`XiaohongshuNoteCommentsResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteCommentsResponseSuccess)   | 类型别名 |                                               |
| [`XiaohongshuNoteDetailResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteDetailResponse)                     | 类型别名 |                                               |
| [`XiaohongshuNoteDetailResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteDetailResponseError)           | 类型别名 |                                               |
| [`XiaohongshuNoteDetailResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuNoteDetailResponseSuccess)       | 类型别名 |                                               |
| [`XiaohongshuSearchHotListResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchHotListResponse)               | 类型别名 |                                               |
| [`XiaohongshuSearchHotListResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchHotListResponseError)     | 类型别名 |                                               |
| [`XiaohongshuSearchHotListResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchHotListResponseSuccess) | 类型别名 |                                               |
| [`XiaohongshuSearchNotesResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchNotesResponse)                   | 类型别名 |                                               |
| [`XiaohongshuSearchNotesResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchNotesResponseError)         | 类型别名 |                                               |
| [`XiaohongshuSearchNotesResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchNotesResponseSuccess)     | 类型别名 |                                               |
| [`XiaohongshuSearchUserResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchUserResponse)                     | 类型别名 |                                               |
| [`XiaohongshuSearchUserResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchUserResponseError)           | 类型别名 |                                               |
| [`XiaohongshuSearchUserResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuSearchUserResponseSuccess)       | 类型别名 |                                               |
| [`XiaohongshuSubCommentsResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuSubCommentsResponse)                   | 类型别名 |                                               |
| [`XiaohongshuSubCommentsResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuSubCommentsResponseError)         | 类型别名 |                                               |
| [`XiaohongshuSubCommentsResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuSubCommentsResponseSuccess)     | 类型别名 |                                               |
| [`XiaohongshuUserNoteList`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserNoteList)                                 | 类型别名 |                                               |
| [`XiaohongshuUserNoteListResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserNoteListResponse)                 | 类型别名 |                                               |
| [`XiaohongshuUserNoteListResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserNoteListResponseError)       | 类型别名 |                                               |
| [`XiaohongshuUserNoteListResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserNoteListResponseSuccess)   | 类型别名 |                                               |
| [`XiaohongshuUserProfile`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserProfile)                                   | 类型别名 |                                               |
| [`XiaohongshuUserProfileResponse`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserProfileResponse)                   | 类型别名 |                                               |
| [`XiaohongshuUserProfileResponseError`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserProfileResponseError)         | 类型别名 |                                               |
| [`XiaohongshuUserProfileResponseSuccess`](/docs/v7/usage/api/types/types-rest#XiaohongshuUserProfileResponseSuccess)     | 类型别名 |                                               |


# 接口 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/interfaces)

> 71 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 71 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### AmagiAxiosTrack [#AmagiAxiosTrack]

axios 轨。

与信封轨共用同一个实例、同一套 `defaults` / `interceptors` —— 差别只有一处：
失败的判据是「信封是不是失败信封」时，这里**抛**而不是返回。
`data` 的类型是 `AmagiResult<T>` 而不是平台载荷：信封是这次调用真正的产物。

<TypeTable
  type="{
  &#x22;delete&#x22;: { type: 'unknown', required: true },
  &#x22;get&#x22;: { type: 'unknown', required: true },
  &#x22;patch&#x22;: { type: 'unknown', required: true },
  &#x22;post&#x22;: { type: 'unknown', required: true },
  &#x22;put&#x22;: { type: 'unknown', required: true },
  &#x22;request&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/client/request/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/request/index.ts#L40)

### AmagiBusEventMap [#AmagiBusEventMap]

事件名 → 负载的映射（**实例级总线**用；顶层导出的 `AmagiEventMap` 描述的是
全局单例 `amagiEvents`，是另一张表）。

名字不与 `AmagiEventMap` 重名：两个同名 interface 一起进 dts 会被打包器给
其中一个加上 `$1` 后缀，公开面上就出现一个谁都不认识的名字。

谁在发：

| 事件名                                                   | emit 点                                         |
| ----------------------------------------------------- | ---------------------------------------------- |
| `http:request` / `http:response`                      | `transport/client.ts` 每发一次请求                   |
| `http:error`                                          | `transport/client.ts`，响应回来了但状态码非 2xx           |
| `network:retry`                                       | `transport/client.ts`，一次失败即将退避重试               |
| `network:error`                                       | `transport/client.ts`，请求始终没拿到响应且退避用尽           |
| `log:warn` / `log:error`                              | `createTransportEmitter`，上面两条的日志行              |
| `log:mark`                                            | `client/createClient.ts` 的 `startServer` 开始监听时 |
| `api:success` / `api:error`                           | `runtime/execute.ts` 收尾信封时                     |
| `session:state` / `session:error` / `session:success` | `runtime/session.ts` 的会话引擎（扫码登录）               |
| `log:info` / `log:debug`                              | **无 emit 点**，见 `UNEMITTED_BUS_EVENT_NAMES`     |

<TypeTable
  type="{
  &#x22;api:error&#x22;: { type: 'ApiErrorEvent', description: '一次逻辑调用失败返回', required: true },
  &#x22;api:success&#x22;: { type: 'ApiSuccessEvent', description: '一次逻辑调用成功返回', required: true },
  &#x22;http:error&#x22;: { type: 'HttpErrorEvent', description: '一次底层请求拿到了非 2xx 响应', required: true },
  &#x22;http:request&#x22;: { type: 'HttpRequestEvent', description: '一次底层请求即将发出', required: true },
  &#x22;http:response&#x22;: { type: 'HttpResponseEvent', description: '一次底层请求已经结束（含非 2xx 与传输失败）', required: true },
  &#x22;log:debug&#x22;: { type: 'LogEvent', description: '一条日志（debug 级）', required: true },
  &#x22;log:error&#x22;: { type: 'LogEvent', description: '一条日志（error 级）', required: true },
  &#x22;log:info&#x22;: { type: 'LogEvent', description: '一条日志（info 级）', required: true },
  &#x22;log:mark&#x22;: { type: 'LogEvent', description: '一条日志（mark 级，重要标记）', required: true },
  &#x22;log:warn&#x22;: { type: 'LogEvent', description: '一条日志（warn 级）', required: true },
  &#x22;network:error&#x22;: { type: 'NetworkErrorEvent', description: '请求始终没拿到响应，退避已用尽', required: true },
  &#x22;network:retry&#x22;: { type: 'NetworkRetryEvent', description: '一次失败即将退避重试', required: true },
  &#x22;session:error&#x22;: { type: 'SessionErrorEvent', description: '扫码登录会话终止于失败', required: true },
  &#x22;session:state&#x22;: { type: 'SessionStateEvent', description: '扫码登录会话推进了一步', required: true },
  &#x22;session:success&#x22;: { type: 'SessionSuccessEvent', description: '扫码登录会话拿到了凭证', required: true }
}"
/>

源码：[`src/runtime/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/runtime/events.ts#L194)

### AmagiError [#AmagiError]

失败信封里唯一的错误载体，永不为 `undefined`

<TypeTable
  type="{
  &#x22;cause&#x22;: { type: 'unknown', description: '底层 Error 对象，仅用于日志', required: true },
  &#x22;challenge&#x22;: { type: 'RiskChallenge', description: '风控挑战（验证页地址 + 票据）。kind === \'risk\'且平台认得出这份响应时才有。\n\n**不受debug开关影响** —— 它是「怎么过去」这条必要信息，见RiskChallenge。', required: true },
  &#x22;code&#x22;: { type: 'AmagiErrorCode', description: '稳定的字符串错误码，可用于 switch 与埋点', required: true },
  &#x22;http&#x22;: { type: '{ status: number; statusText: string }', description: '真实发生的 HTTP 状态（有请求才有）', required: true },
  &#x22;issues&#x22;: { type: 'ValidationIssue[]', description: 'kind === \'validation\'时的字段级错误', required: true },
  &#x22;kind&#x22;: { type: 'ErrorKind', description: '判别键，跨平台统一的错误大类', required: true },
  &#x22;message&#x22;: { type: 'string', description: '面向人的说明，取平台原文优先', required: true },
  &#x22;platform&#x22;: { type: '{ code: string | number; message: string }', description: '平台原始错误码与文案，一个字都不丢', required: true },
  &#x22;raw&#x22;: { type: 'unknown', description: '原始响应体。默认**连键都没有**，createClient({ debug: true })且这次\n确实**拿到了响应**时才填（网络中断 / 超时那类失败没有响应体可放）。', required: true },
  &#x22;retryable&#x22;: { type: 'boolean', description: '是否值得重试。调用方据此决定退避还是放弃', required: true }
}"
/>

源码：[`src/contracts/error.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/error.ts#L90)

### AmagiEventMap [#AmagiEventMap]

事件类型到数据的映射

<TypeTable
  type="{
  &#x22;api:error&#x22;: { type: 'ApiErrorEventData', required: true },
  &#x22;api:success&#x22;: { type: 'ApiSuccessEventData', required: true },
  &#x22;http:error&#x22;: { type: 'NetworkErrorEventData', required: true },
  &#x22;http:request&#x22;: { type: 'HttpRequestEventData', required: true },
  &#x22;http:response&#x22;: { type: 'HttpResponseEventData', required: true },
  &#x22;log:debug&#x22;: { type: 'LogEventData', required: true },
  &#x22;log:error&#x22;: { type: 'LogEventData', required: true },
  &#x22;log:info&#x22;: { type: 'LogEventData', required: true },
  &#x22;log:mark&#x22;: { type: 'LogEventData', required: true },
  &#x22;log:warn&#x22;: { type: 'LogEventData', required: true },
  &#x22;network:error&#x22;: { type: 'NetworkErrorEventData', required: true },
  &#x22;network:retry&#x22;: { type: 'NetworkRetryEventData', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L172)

### AmagiFailure [#AmagiFailure]

失败信封

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'undefined', description: '对侧键的占位声明。\n\n失败信封**运行时没有这个键**，所以类型只能是undefined。有了它，未收窄的r.data是T | undefined，而不是 TS2339。', required: true },
  &#x22;error&#x22;: { type: 'AmagiError', description: '唯一的错误载体，永不为undefined', required: true },
  &#x22;message&#x22;: { type: 'string', description: '等价于error.message，为兼容 v6 的result.message读法保留', required: true },
  &#x22;meta&#x22;: { type: 'AmagiMeta', description: '元信息', required: true },
  &#x22;success&#x22;: { type: 'false', description: '判别键', required: true }
}"
/>

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L63)

### AmagiMeta [#AmagiMeta]

挂在每个信封上的元信息

<TypeTable
  type="{
  &#x22;attempts&#x22;: { type: 'number', description: '实际发出的 HTTP 请求数，含重试与分页。分页 3 页 + 1 次重试 = 4', required: true },
  &#x22;clientId&#x22;: { type: 'string', description: '发起调用的 client 实例 id；静态 fetcher 用\'static\'', required: true },
  &#x22;durationMs&#x22;: { type: 'number', description: '从进入 fetcher 到返回信封的总耗时', required: true },
  &#x22;endpoint&#x22;: { type: 'string', description: '端点全名，如\'douyin.videoWork\'', required: true },
  &#x22;incomplete&#x22;: { type: '{ code: AmagiErrorCode; kind: ErrorKind; message: string }', description: '结果不完整时的原因：翻页端点声明了partial: \'tolerate\'、中途某页失败，\n信封仍是成功、data里是已取到的那几页，这里是那个失败页的错误。\n\n完整结果上**没有这个键**。只看success的调用方会拿到截断的数据 ——\n在意条数的，检查这个键。没声明tolerate的翻页端点中途失败也返回部分结果，\n但**不**挂这个键，只能拿条目数与目标比对。', required: true },
  &#x22;platform&#x22;: { type: 'Platform', description: '平台', required: true },
  &#x22;requestId&#x22;: { type: 'string', description: '每次逻辑调用一个 id，贯穿事件、日志、trace', required: true },
  &#x22;trace&#x22;: { type: 'RequestTrace[]', description: '每次底层请求的明细，按发出顺序。\n\n默认不带：createClient({ debug: true })时才填（同一个开关也给失败信封\n填error.raw，没有单独的 trace 开关）。不开时信封上**没有trace这个键**，而attempts照样准确 —— 计数始终发生，只有明细受开关控制。\n\n静态 fetcher（amagi.douyinFetcher.*）与 HTTP 服务的平台路由没有这个开关。\n要不受开关影响地逐条观测请求，监听http:request/http:response事件：它们的负载恒带trace。URL 含签名参数，别在生产里无条件打印。', required: true }
}"
/>

源码：[`src/contracts/meta.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/meta.ts#L63)

### AmagiRequest [#AmagiRequest]

平台的请求模块。

打的是**任何 URL**（包括 amagi 还没收录的接口），自动带上实例 ck 与平台签名，
走与 fetcher 同一条 `execute` 管线与同一套 judge。与 fetcher 的分工：
fetcher 打已声明的端点（有参数校验 / 翻页 / decode / normalize），
request 打裸请求（给原始载荷，不跑 decode）。

<TypeTable
  type="{
  &#x22;axios&#x22;: { type: 'AmagiAxiosTrack', description: '原生 axios 语义的那一轨', required: true },
  &#x22;create&#x22;: { type: 'unknown', required: true },
  &#x22;defaults&#x22;: { type: 'AxiosInstance[&#x22;defaults&#x22;]', description: '底层 axios 实例的默认值，可按 axios 的习惯就地改', required: true },
  &#x22;delete&#x22;: { type: 'AmagiRequestMethod', description: 'DELETE，返回信封', required: true },
  &#x22;get&#x22;: { type: 'AmagiRequestMethod', description: 'GET，返回信封', required: true },
  &#x22;interceptors&#x22;: { type: 'AxiosInstance[&#x22;interceptors&#x22;]', description: '底层 axios 实例的拦截器。两条轨共用同一份', required: true },
  &#x22;patch&#x22;: { type: 'AmagiRequestMethod', description: 'PATCH，返回信封', required: true },
  &#x22;post&#x22;: { type: 'AmagiRequestMethod', description: 'POST，返回信封', required: true },
  &#x22;put&#x22;: { type: 'AmagiRequestMethod', description: 'PUT，返回信封', required: true },
  &#x22;request&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/client/request/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/request/index.ts#L63)

### AmagiRequestConfig [#AmagiRequestConfig]

`client.<平台>.request` 的入参。

在 axios 配置之上做两处**收窄**，都是为了让「不可能发生的事」编译不过：

* 去掉 `adapter` —— 传它就会绕过签名与信封，直达网络。
* `responseType` 收成 transport 支持的三种。axios 还认 `'blob'` / `'stream'` /
  `'document'`，但那几种解析出来的东西装不进 `RawResponse.body`。

<TypeTable
  type="{
  &#x22;amagi&#x22;: { type: 'AmagiRequestOptions', description: 'amagi 专属的单次选项', required: true },
  &#x22;responseType&#x22;: { type: '&#x22;json&#x22; | &#x22;text&#x22; | &#x22;arraybuffer&#x22;', description: 'transport 支持的响应形态', required: true }
}"
/>

源码：[`src/client/request/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/request/index.ts#L23)

### AmagiRequestOptions [#AmagiRequestOptions]

单次请求的 amagi 专属选项。

挂在 axios 配置的 `amagi` 键下（`client.douyin.request.get(url, { amagi: { cookie: false } })`）。
**只装 axios 装不下的东西** —— `timeout` / `responseType` / `params` / `headers` /
`signal` / `proxy` 这些一律直接用 axios 自己的键，不经这里转手。

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'false', description: '本次**不带** cookie。\n\n类型上只能填false——true本来就是默认值，写成联合类型只会多一种\n没人会用的写法。落地的语义与端点声明里的dropHeaders: [\'cookie\']完全一样：\n在所有 header 合并**之后**删，所以调用方自己从headers塞进来的 ck 也一起删掉。\n\n存在的理由：有些接口带 ck 反而拿不到数据（B站评论区会按账号改变热度池排序）。', required: true },
  &#x22;dropHeaders&#x22;: { type: 'readonly string[]', description: '从平台基线里**删掉**的头（大小写不敏感）。\n\n逃生舱：快手 H5 端点用移动 UA，而基线是照桌面 Chrome 攒的，两者拼在一起\n自相矛盾。cookie: false是dropHeaders: [\'cookie\']的糖。', required: true },
  &#x22;sign&#x22;: { type: 'SignDecl', description: '本次怎么签名。取值同端点声明的sign（SignDecl）：\n\n- 不给：按平台默认（见client/request/profile.ts的档案表）——抖音走[msToken(184), aBogus(), secsdk()]、快手[hxfalcon()]、小红书按 method\n  推 GET / POST、B站默认**不签**（27 条端点里只有 5 条签名，默认签会大面积签错）。\n- 字符串：平台签名器表里注册过的名字（\'a-bogus\'/\'hxfalcon\'/\'xhs-get\'…）；\n  写错名字管线抛未注册的签名器。\n-false：本次不签。\n-SignStep/SignStep[]：**精细控制**——从@ikenxuan/amagi/sign-stepsimport 平台命名空间（douyin/bilibili/kuaishou/xiaohongshu），自己列\n  要哪些反爬参数，如[douyin.msToken(200), douyin.aBogus()]。runtime 按 phase 排序\n  执行，与端点声明里的清单同一套机制。\n-SignFn：一次性的自定义签名函数。\n\n放宽到全量SignDecl是有意的：SignStep.apply本身就是SignFn，暴露 step 工厂\n已等于把SignFn/EndpointCtx/RequestSpec带上公开面，再切一个窄联合只是徒增限制。', required: true },
  &#x22;signPath&#x22;: { type: 'string', description: '签名用的接口路径。不给时从 URL 反推 pathname。\n\n小红书x-s只吃 pathname；快手有 4 条路径与公开 URL 不一致\n（如userInfoById的 URL 是/rest/w前缀、签名路径是/rest/k/user/info）。', required: true }
}"
/>

源码：[`src/contracts/request-options.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/request-options.ts#L22)

### AmagiSuccess [#AmagiSuccess]

成功信封

<TypeTable
  type="{
  &#x22;data&#x22;: { type: 'T', description: '端点声明的返回类型', required: true },
  &#x22;error&#x22;: { type: 'undefined', description: '对侧键的占位声明。\n\n成功信封**运行时没有这个键**，所以类型只能是undefined。存在的唯一理由是\n让未收窄的AmagiResult上r.error可读（类型AmagiError | undefined），\n而不是 TS2339。', required: true },
  &#x22;message&#x22;: { type: 'string', description: '面向人的简短说明，成功时固定为SUCCESS_MESSAGE。\n\n注意 **success: true不等于「取满了目标条数」**：声明式翻页在hasMore为假、本页为空、或某一页被平台拒绝时都会提前收尾，返回已取到的部分。\n需要精确判断的调用方拿data里的条目数与目标比对，别靠信封。', required: true },
  &#x22;meta&#x22;: { type: 'AmagiMeta', description: '元信息', required: true },
  &#x22;success&#x22;: { type: 'true', description: '判别键', required: true }
}"
/>

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L37)

### ApiErrorEventData [#ApiErrorEventData]

API 错误事件数据

<TypeTable
  type="{
  &#x22;duration&#x22;: { type: 'number', description: '请求耗时 (毫秒)', required: true },
  &#x22;errorCode&#x22;: { type: 'string | number', description: '错误代码', required: true },
  &#x22;errorMessage&#x22;: { type: 'string', description: '错误消息', required: true },
  &#x22;methodType&#x22;: { type: 'string', description: '调用的 API 方法', required: true },
  &#x22;platform&#x22;: { type: '&#x22;douyin&#x22; | &#x22;bilibili&#x22; | &#x22;kuaishou&#x22; | &#x22;xiaohongshu&#x22;', description: '请求平台', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true },
  &#x22;url&#x22;: { type: 'string', description: '请求 URL', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L151)

### ApiSuccessEventData [#ApiSuccessEventData]

API 成功事件数据

<TypeTable
  type="{
  &#x22;duration&#x22;: { type: 'number', description: '请求耗时 (毫秒)', required: true },
  &#x22;methodType&#x22;: { type: 'string', description: '调用的 API 方法', required: true },
  &#x22;platform&#x22;: { type: '&#x22;douyin&#x22; | &#x22;bilibili&#x22; | &#x22;kuaishou&#x22; | &#x22;xiaohongshu&#x22;', description: '请求平台', required: true },
  &#x22;response&#x22;: { type: 'unknown', description: 'API 响应数据 (Result 结构)', required: true },
  &#x22;statusCode&#x22;: { type: 'number', description: 'HTTP 状态码', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L132)

### BilibiliFetcher [#BilibiliFetcher]

B站 Fetcher 类型（静态形态：三参签名）。

写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名，
打印器（IDE 悬停 / twoslash / `.d.ts`）会把 `typeof bilibiliRegistry` 那 27 个
`EndpointDef` 连 zod schema 一起整个内联展开（实测单个 fetcher 就上万字符）。
接口是**名义类型**：容器处只打印这个名字，`BilibiliFetcher['fetchVideoInfo']`
这样钻进去时方法签名依旧完整 —— 类型不变，只是显示收敛。

源码：[`src/model/fetchers/bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/bilibili/index.ts#L30)

### BilibiliMethodOptionsMap [#BilibiliMethodOptionsMap]

B站 API 方法参数映射接口

每个键对应一种 API 方法，值为该方法所需的参数接口

<TypeTable
  type="{
  &#x22;ApplyVoucherCaptchaParams&#x22;: { type: '{ csrf: string; methodType: &#x22;captchaFromVoucher&#x22;; v_voucher: string }', description: '从 v_voucher 申请验证码', required: true },
  &#x22;ArticleCardParams&#x22;: { type: '{ ids: string[] | string; methodType: &#x22;articleCards&#x22; }', description: '获取专栏显示卡片信息', required: true },
  &#x22;ArticleInfoParams&#x22;: { type: '{ id: string; methodType: &#x22;articleInfo&#x22; }', description: '获取专栏文章基本信息', required: true },
  &#x22;ArticleParams&#x22;: { type: '{ id: string; methodType: &#x22;articleContent&#x22; }', description: '获取专栏正文内容', required: true },
  &#x22;Av2BvParams&#x22;: { type: '{ avid: number; methodType: &#x22;avToBv&#x22; }', description: 'AV号转BV号', required: true },
  &#x22;BangumiInfoParams&#x22;: { type: '{ ep_id: string; methodType: &#x22;bangumiInfo&#x22;; season_id: string }', description: '获取番剧基本信息', required: true },
  &#x22;BangumiStreamParams&#x22;: { type: '{ cid: number; ep_id: string; methodType: &#x22;bangumiStream&#x22; }', description: '获取番剧视频流信息', required: true },
  &#x22;Bv2AvParams&#x22;: { type: '{ bvid: string; methodType: &#x22;bvToAv&#x22; }', description: 'BV号转AV号', required: true },
  &#x22;ColumnInfoParams&#x22;: { type: '{ id: string; methodType: &#x22;articleListInfo&#x22; }', description: '获取文集基本信息', required: true },
  &#x22;CommentParams&#x22;: { type: '{ methodType: &#x22;comments&#x22;; mode: &#x22;0&#x22; | &#x22;1&#x22; | &#x22;2&#x22; | &#x22;3&#x22;; number: number; oid: string; pagination_str: string; plat: number; …其余 3 个成员 }', description: '获取评论数据', required: true },
  &#x22;CommentReplyParams&#x22;: { type: '{ methodType: &#x22;commentReplies&#x22;; number: number; oid: string; root: string; type: CommentType }', description: '获取指定评论的回复', required: true },
  &#x22;DanmakuParams&#x22;: { type: '{ cid: number; methodType: &#x22;videoDanmaku&#x22;; segment_index: number }', description: '获取实时弹幕', required: true },
  &#x22;DynamicParams&#x22;: { type: '{ dynamic_id: string; methodType: &#x22;dynamicDetail&#x22; }', description: '获取动态数据', required: true },
  &#x22;EmojiParams&#x22;: { type: '{ methodType: &#x22;emojiList&#x22; }', description: '获取表情列表', required: true },
  &#x22;GetQrcodeParams&#x22;: { type: '{ methodType: &#x22;loginQrcode&#x22; }', description: '申请登录二维码', required: true },
  &#x22;LiveRoomParams&#x22;: { type: '{ methodType: &#x22;liveRoomInfo&#x22; | &#x22;liveRoomInit&#x22;; room_id: string }', description: '获取直播间信息', required: true },
  &#x22;LoginBaseInfoParams&#x22;: { type: '{ methodType: &#x22;loginStatus&#x22; }', description: '获取登录基本信息', required: true },
  &#x22;QrcodeParams&#x22;: { type: '{ methodType: &#x22;qrcodeStatus&#x22;; qrcode_key: string }', description: '查询二维码状态', required: true },
  &#x22;UserParams&#x22;: { type: '{ host_mid: number; methodType: &#x22;userCard&#x22; | &#x22;userDynamicList&#x22; | &#x22;userLiveStatus&#x22; | &#x22;uploaderTotalViews&#x22; | &#x22;userSpaceInfo&#x22; }', description: '获取用户相关数据', required: true },
  &#x22;ValidateCaptchaParams&#x22;: { type: '{ challenge: string; csrf: string; methodType: &#x22;validateCaptcha&#x22;; seccode: string; token: string; validate: string }', description: '验证验证码结果', required: true },
  &#x22;VideoInfoParams&#x22;: { type: '{ bvid: string; methodType: &#x22;videoInfo&#x22; }', description: '获取单个视频信息', required: true },
  &#x22;VideoStreamParams&#x22;: { type: '{ avid: number; cid: number; methodType: &#x22;videoStream&#x22; }', description: '获取视频流下载信息', required: true }
}"
/>

源码：[`src/types/BilibiliAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/BilibiliAPIParams.ts#L14)

### BilibiliRefreshInput [#BilibiliRefreshInput]

刷新入参

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '当前登录态 cookie 串（至少含SESSDATA+bili_jct）', required: true },
  &#x22;refreshToken&#x22;: { type: 'string', description: '持久化的 refresh_token（登录时下发，官方 Web 存于localStorage.ac_time_value）', required: true }
}"
/>

源码：[`src/platforms/bilibili/cookieRefresh.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/cookieRefresh.ts#L81)

### BilibiliRefreshOutput [#BilibiliRefreshOutput]

刷新产物

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '刷新后的新 cookie 串（SESSDATA/bili_jct/DedeUserID/DedeUserID__ckMd5/sid已更新）', required: true },
  &#x22;refreshToken&#x22;: { type: 'string', description: '新的 refresh_token，务必持久化替换旧值（下次刷新要用）', required: true }
}"
/>

源码：[`src/platforms/bilibili/cookieRefresh.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/cookieRefresh.ts#L89)

### BilibiliReturnTypeMap [#BilibiliReturnTypeMap]

B站返回类型映射

将 methodType 映射到对应的返回数据类型

<TypeTable
  type="{
  &#x22;articleCards&#x22;: { type: 'ArticleCard', required: true },
  &#x22;articleContent&#x22;: { type: 'ArticleContent', required: true },
  &#x22;articleInfo&#x22;: { type: 'ArticleInfo', required: true },
  &#x22;articleListInfo&#x22;: { type: 'ColumnInfo', required: true },
  &#x22;avToBv&#x22;: { type: 'BiliAv2Bv', required: true },
  &#x22;bangumiInfo&#x22;: { type: 'BiliBangumiVideoInfo', required: true },
  &#x22;bangumiStream&#x22;: { type: 'BiliBangumiVideoPlayurlIsLogin | BiliBangumiVideoPlayurlNoLogin', required: true },
  &#x22;bvToAv&#x22;: { type: 'BiliBv2AV', required: true },
  &#x22;captchaFromVoucher&#x22;: { type: 'ApplyCaptcha', required: true },
  &#x22;commentReplies&#x22;: { type: 'BiliCommentReply', required: true },
  &#x22;comments&#x22;: { type: 'BiliWorkComments', required: true },
  &#x22;dynamicDetail&#x22;: { type: 'BiliDynamicInfoUnion', required: true },
  &#x22;emojiList&#x22;: { type: 'BiliEmojiList', required: true },
  &#x22;liveRoomInfo&#x22;: { type: 'BiliLiveRoomDetail', required: true },
  &#x22;liveRoomInit&#x22;: { type: 'BiliLiveRoomDef', required: true },
  &#x22;loginQrcode&#x22;: { type: 'BiliNewLoginQrcode', required: true },
  &#x22;loginStatus&#x22;: { type: 'BiliLoginStatus', required: true },
  &#x22;qrcodeStatus&#x22;: { type: 'BiliCheckQrcode', required: true },
  &#x22;uploaderTotalViews&#x22;: { type: 'BiliUserFullView', required: true },
  &#x22;userCard&#x22;: { type: 'BiliUserProfile', required: true },
  &#x22;userDynamicList&#x22;: { type: 'BiliUserDynamic', required: true },
  &#x22;userLiveStatus&#x22;: { type: 'BiliUserLiveStatus', required: true },
  &#x22;userSpaceInfo&#x22;: { type: 'UserSpaceInfo', required: true },
  &#x22;validateCaptcha&#x22;: { type: 'ValidateCaptcha', required: true },
  &#x22;videoDanmaku&#x22;: { type: 'BiliProtobufDanmaku', required: true },
  &#x22;videoInfo&#x22;: { type: 'BiliOneWork', required: true },
  &#x22;videoStream&#x22;: { type: 'BiliVideoPlayurlIsLogin | BiliBiliVideoPlayurlNoLogin', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/index.ts#L59)

### BoundBilibiliFetcher [#BoundBilibiliFetcher]

绑定 Cookie 的B站 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。

名义接口，理由同 [`BilibiliFetcher`](/docs/v7/usage/api/types/interfaces#BilibiliFetcher)：`FetcherOf<…>` 是泛型别名，直接用会把整个
registry 内联展开。改成 `interface … extends` 后 `client.bilibili.fetcher` /
`createBoundBilibiliFetcher(...)` 的悬停只显示这个名字，方法签名钻进去仍完整。

源码：[`src/model/fetchers/bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/bilibili/index.ts#L65)

### BoundDouyinFetcher [#BoundDouyinFetcher]

绑定 Cookie 的抖音 Fetcher 类型（形状 = `FetcherOf`，两参签名）。

名义接口，理由同 [`DouyinStaticFetcher`](/docs/v7/usage/api/types/interfaces#DouyinStaticFetcher)：写成 `type … = FetcherOf<…>` 会在
悬停 / `.d.ts` 里把整个 registry 展开，`interface … extends` 则只打印这个名字。

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L89)

### BoundKuaishouFetcher [#BoundKuaishouFetcher]

绑定 Cookie 的快手 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。

名义接口，理由同 [`KuaishouFetcher`](/docs/v7/usage/api/types/interfaces#KuaishouFetcher)：`FetcherOf<…>` 是泛型别名，直接用会把整个
registry 内联展开。改成 `interface … extends` 后 `client.kuaishou.fetcher` /
`createBoundKuaishouFetcher(...)` 的悬停只显示这个名字，方法签名钻进去仍完整。

源码：[`src/model/fetchers/kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/kuaishou/index.ts#L59)

### BoundXiaohongshuFetcher [#BoundXiaohongshuFetcher]

绑定 Cookie 的小红书 Fetcher 类型（两参签名：cookie 已绑，只剩 options / requestConfig）。

名义接口，理由同 [`XiaohongshuFetcher`](/docs/v7/usage/api/types/interfaces#XiaohongshuFetcher)：`FetcherOf<…>` 是泛型别名，直接用会把整个
registry 内联展开。改成 `interface … extends` 后 `client.xiaohongshu.fetcher` /
`createBoundXiaohongshuFetcher(...)` 的悬停只显示这个名字，方法签名钻进去仍完整。

源码：[`src/model/fetchers/xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/xiaohongshu/index.ts#L61)

### CaptchaChallenge [#CaptchaChallenge]

图形验证码 challenge

<TypeTable
  type="{
  &#x22;imageUrl&#x22;: { type: 'string', required: true },
  &#x22;kind&#x22;: { type: '&#x22;captcha&#x22;', required: true },
  &#x22;payload&#x22;: { type: 'Record<string, unknown>', description: '极验/腾讯验证码等的初始化参数', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L70)

### CheckDouyinLoginStateOptions [#CheckDouyinLoginStateOptions]

<TypeTable
  type="{
  &#x22;force&#x22;: { type: 'boolean', required: true }
}"
/>

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L14)

### ClientOptions [#ClientOptions]

客户端构造选项

<TypeTable
  type="{
  &#x22;cookies&#x22;: { type: '{ bilibili: string; douyin: string; kuaishou: string; xiaohongshu: string }', description: 'Cookie 配置', required: true },
  &#x22;debug&#x22;: { type: 'boolean', description: '排障开关。打开后两样东西同时出现：失败信封的error.raw带平台原始响应体，\n每个信封的meta.trace带这次调用发出的每一条底层请求（URL / 方法 /\n状态码 / 耗时 / 发出原因）。用于排查协议变更、风控页、业务码含义不明，\n以及「这一次调用到底打了几个请求」。\n\n默认false，此时失败信封上**没有**raw这个键、meta上也**没有**trace这个键（不是undefined占位）。meta.attempts与本开关无关，\n一直是准的 —— 计数始终发生，只有明细受开关控制。debug一个开关同时管error.raw与meta.trace两样：两者都只服务排障，\n分成两个名字等于让人多记一个。要**不受开关影响**地逐条观测请求，监听http:request/http:response事件 —— 它们的负载恒带trace。\n\n原始响应可能很大、也可能带敏感字段，trace里的 URL 含签名参数，\n别在生产里无条件打印。只作用于 client 实例上的 fetcher：静态 fetcher\n（amagi.douyinFetcher.*）与 HTTP 服务的平台路由没有这个开关。', required: true },
  &#x22;request&#x22;: { type: 'RequestConfig', description: '请求配置', required: true },
  &#x22;xiaohongshuSession&#x22;: { type: 'XiaohongshuSessionInput', description: '与 Cookie 配对的小红书会话材料；旧 cookies 配置仍可单独使用。', required: true }
}"
/>

源码：[`src/client/createClient.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/createClient.ts#L60)

### Credential [#Credential]

跨平台统一的登录凭证

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '完整登录态 cookie 串，可直接传给 fetcher', required: true },
  &#x22;expiresAt&#x22;: { type: 'number', description: '凭证过期时刻，能从 cookie 里解析出来时才有', required: true },
  &#x22;raw&#x22;: { type: 'unknown', description: '平台原始产物（抖音的 sso 响应、B站的 Set-Cookie 数组等）', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L49)

### DouyinCredentialRequestOptions [#DouyinCredentialRequestOptions]

凭据请求与 API 请求走同一套 transport/代理/adapter。

<TypeTable
  type="{
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', required: true },
  &#x22;send&#x22;: { type: 'EndpointCtx[&#x22;send&#x22;]', required: true },
  &#x22;timeoutMs&#x22;: { type: 'number', required: true },
  &#x22;userAgent&#x22;: { type: 'string', required: true }
}"
/>

源码：[`src/platforms/douyin/credentialRequest.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/credentialRequest.ts#L7)

### DouyinFetcher [#DouyinFetcher]

抖音 Fetcher 类型（静态形态：三参签名 + 4 个 passport 方法）。

名义接口，理由同 [`DouyinStaticFetcher`](/docs/v7/usage/api/types/interfaces#DouyinStaticFetcher)。在 registry 派生的方法之上补 4 个
passport 方法（它们不是端点，见下方 `douyinFetcher` 的构造）。

<TypeTable
  type="{
  &#x22;checkPassportQrcode&#x22;: { type: 'typeof checkPassportQrcode', required: true },
  &#x22;requestPassportQrcode&#x22;: { type: 'typeof requestPassportQrcode', required: true },
  &#x22;sendPassportVerifyCode&#x22;: { type: 'typeof sendPassportVerifyCode', required: true },
  &#x22;validatePassportVerifyCode&#x22;: { type: 'typeof validatePassportVerifyCode', required: true }
}"
/>

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L39)

### DouyinLoginCheck [#DouyinLoginCheck]

<TypeTable
  type="{
  &#x22;cached&#x22;: { type: 'boolean', required: true },
  &#x22;description&#x22;: { type: 'string', required: true },
  &#x22;errorCode&#x22;: { type: 'number', required: true },
  &#x22;state&#x22;: { type: 'DouyinLoginState', required: true }
}"
/>

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L7)

### DouyinMethodOptionsMap [#DouyinMethodOptionsMap]

抖音 API 方法参数映射接口

每个键对应一种 API 方法，值为该方法所需的参数接口

<TypeTable
  type="{
  &#x22;CommentParams&#x22;: { type: '{ aweme_id: string; cursor: number; methodType: &#x22;comments&#x22;; number: number }', description: '获取评论数据', required: true },
  &#x22;CommentReplyParams&#x22;: { type: '{ aweme_id: string; comment_id: string; cursor: number; methodType: &#x22;commentReplies&#x22;; number: number }', description: '获取指定评论的回复', required: true },
  &#x22;DanmakuParams&#x22;: { type: '{ aweme_id: string; duration: number; end_time: number; methodType: &#x22;danmakuList&#x22;; start_time: number }', description: '获取弹幕数据', required: true },
  &#x22;EmojiListParams&#x22;: { type: '{ methodType: &#x22;emojiList&#x22; }', description: '获取表情列表', required: true },
  &#x22;EmojiProParams&#x22;: { type: '{ methodType: &#x22;dynamicEmojiList&#x22; }', description: '获取动态表情数据', required: true },
  &#x22;EmojiResourceParams&#x22;: { type: '{ methodType: &#x22;emojiResourceMeta&#x22; }', description: '获取表情资源包元信息（App 接口，免鉴权）', required: true },
  &#x22;GuestMusicListParams&#x22;: { type: '{ cursor: number; methodType: &#x22;guestMusicAwemeList&#x22;; music_id: string; number: number }', description: '获取使用某原声的作品列表（iesdouyin v2，免鉴权）', required: true },
  &#x22;GuestMusicParams&#x22;: { type: '{ methodType: &#x22;guestMusicInfo&#x22;; music_id: string }', description: '获取游客原声信息（iesdouyin v2，免鉴权）', required: true },
  &#x22;GuestUserParams&#x22;: { type: '{ methodType: &#x22;guestUserInfo&#x22;; unique_id: string }', description: '获取游客用户信息（iesdouyin v2，免鉴权）', required: true },
  &#x22;HotWordsParams&#x22;: { type: '{ methodType: &#x22;suggestWords&#x22;; query: string }', description: '获取热点词数据', required: true },
  &#x22;ImageAlbumWorkParams&#x22;: { type: '{ aweme_id: string; methodType: &#x22;imageAlbumWork&#x22; }', description: '获取图集作品数据', required: true },
  &#x22;LiveRoomParams&#x22;: { type: '{ methodType: &#x22;liveRoomInfo&#x22;; room_id: string; web_rid: string }', description: '获取直播间信息', required: true },
  &#x22;MusicParams&#x22;: { type: '{ methodType: &#x22;musicInfo&#x22;; music_id: string }', description: '获取音乐数据', required: true },
  &#x22;QrcodeParams&#x22;: { type: '{ methodType: &#x22;loginQrcode&#x22;; verify_fp: string }', description: '申请登录二维码', required: true },
  &#x22;SearchParams&#x22;: { type: '{ methodType: &#x22;search&#x22;; number: number; query: string; search_id: string; type: &#x22;general&#x22; | &#x22;user&#x22; | &#x22;video&#x22; }', description: '搜索数据', required: true },
  &#x22;SlidesWorkParams&#x22;: { type: '{ aweme_id: string; methodType: &#x22;slidesWork&#x22; }', description: '获取合辑作品数据', required: true },
  &#x22;UserListParams&#x22;: { type: '{ max_cursor: string; methodType: &#x22;userVideoList&#x22; | &#x22;userFavoriteList&#x22; | &#x22;userRecommendList&#x22;; number: number; sec_uid: string }', description: '获取用户列表数据（视频列表、喜欢列表、推荐列表）', required: true },
  &#x22;UserParams&#x22;: { type: '{ methodType: &#x22;userProfile&#x22;; sec_uid: string }', description: '获取用户相关数据', required: true },
  &#x22;VideoWorkParams&#x22;: { type: '{ aweme_id: string; methodType: &#x22;videoWork&#x22; }', description: '获取视频作品数据', required: true },
  &#x22;WorkParams&#x22;: { type: '{ aweme_id: string; methodType: &#x22;videoWork&#x22; | &#x22;imageAlbumWork&#x22; | &#x22;slidesWork&#x22; | &#x22;parseWork&#x22; | &#x22;textWork&#x22; }', description: '获取作品数据', required: true }
}"
/>

源码：[`src/types/DouyinAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/DouyinAPIParams.ts#L14)

### DouyinReturnTypeMap [#DouyinReturnTypeMap]

抖音返回类型映射

将 methodType 映射到对应的返回数据类型

<TypeTable
  type="{
  &#x22;commentReplies&#x22;: { type: 'CommentReply', required: true },
  &#x22;comments&#x22;: { type: 'DyWorkComments', required: true },
  &#x22;danmakuList&#x22;: { type: 'DyDanmakuList', required: true },
  &#x22;dynamicEmojiList&#x22;: { type: 'DyEmojiProList', required: true },
  &#x22;emojiList&#x22;: { type: 'DyEmojiList', required: true },
  &#x22;emojiResourceMeta&#x22;: { type: 'DyEmojiResourceMeta', description: 'App 资源包元信息原样响应', required: true },
  &#x22;guestMusicAwemeList&#x22;: { type: 'DyGuestMusicAwemeList', description: 'iesdouyin v2 原样响应，字段怎么读由调用方决定', required: true },
  &#x22;guestMusicInfo&#x22;: { type: 'DyGuestMusicInfo', description: 'iesdouyin v2 原样响应，字段怎么读由调用方决定', required: true },
  &#x22;guestUserInfo&#x22;: { type: 'DyGuestUserInfo', description: 'iesdouyin v2 原样响应，字段怎么读由调用方决定', required: true },
  &#x22;imageAlbumWork&#x22;: { type: 'DyImageAlbumWork', required: true },
  &#x22;liveRoomInfo&#x22;: { type: 'DyUserLiveVideos', required: true },
  &#x22;loginQrcode&#x22;: { type: 'DyLoginQrcode', required: true },
  &#x22;musicInfo&#x22;: { type: 'DyMusicWork', required: true },
  &#x22;parseWork&#x22;: { type: 'DyVideoWork | DyImageAlbumWork | DySlidesWork | DyImageAlbumWork & ArticleWork', required: true },
  &#x22;passportQrcode&#x22;: { type: 'DyPassportQrcode', required: true },
  &#x22;passportQrcodeStatus&#x22;: { type: 'DyPassportQrcodeStatus', required: true },
  &#x22;passportSendCode&#x22;: { type: 'DyPassportSendCode', required: true },
  &#x22;passportValidateCode&#x22;: { type: 'DyPassportValidateCode', required: true },
  &#x22;search&#x22;: { type: 'DySearchInfo', required: true },
  &#x22;slidesWork&#x22;: { type: 'DySlidesWork', required: true },
  &#x22;suggestWords&#x22;: { type: 'DySuggestWords', required: true },
  &#x22;textWork&#x22;: { type: 'ArticleWork', required: true },
  &#x22;userFavoriteList&#x22;: { type: 'DyUserFavoriteList', required: true },
  &#x22;userProfile&#x22;: { type: 'DyUserInfo', required: true },
  &#x22;userRecommendList&#x22;: { type: 'UserRecommendList', required: true },
  &#x22;userVideoList&#x22;: { type: 'DyUserPostVideos', required: true },
  &#x22;videoWork&#x22;: { type: 'DyVideoWork', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/index.ts#L55)

### DouyinStaticFetcher [#DouyinStaticFetcher]

抖音静态 fetcher 的类型（不含 passport，纯 registry 派生形态）。

写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名，
打印器（IDE 悬停 / twoslash / `.d.ts`）会把 `typeof douyinRegistry` 那些
`EndpointDef` 连 zod schema 一起整个内联展开（实测单个 fetcher 就上十万字符）。
接口是**名义类型**：容器处只打印这个名字，`DouyinStaticFetcher['fetchVideoWork']`
这样钻进去时方法签名依旧完整 —— 类型不变，只是显示收敛。

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L31)

### DyPassportQrcode [#DyPassportQrcode]

登录二维码

<TypeTable
  type="{
  &#x22;content&#x22;: { type: 'string', description: '二维码承载的内容，直接拿去生成图片', required: true },
  &#x22;cookie&#x22;: { type: 'string', description: '本次会话 cookie，后续调用需原样传回', required: true },
  &#x22;expire_time&#x22;: { type: 'number', description: '二维码过期时间，服务端原值，是**绝对 Unix 时间戳（秒）**而非时长\n\n想要剩余秒数请直接用expires_in。', required: true },
  &#x22;expires_in&#x22;: { type: 'number', description: '距离二维码过期还剩多少秒，取二维码时算出，实测约 60 秒', required: true },
  &#x22;token&#x22;: { type: 'string', description: '轮询用的二维码令牌', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L66)

### DyPassportSendCodeResult [#DyPassportSendCodeResult]

发码接口归一化后的结果，不含会话字段

<TypeTable
  type="{
  &#x22;errorCode&#x22;: { type: 'number', description: '失败时的错误码', required: true },
  &#x22;message&#x22;: { type: 'string', description: '失败时的描述', required: true },
  &#x22;mobile&#x22;: { type: 'string', description: '服务端返回的脱敏手机号', required: true },
  &#x22;ok&#x22;: { type: 'boolean', description: '是否发送成功', required: true },
  &#x22;retryAfter&#x22;: { type: 'number', description: '允许重新发送的等待秒数', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L92)

### DyPassportValidateCodeResult [#DyPassportValidateCodeResult]

验码接口归一化后的结果，不含会话字段

<TypeTable
  type="{
  &#x22;errorCode&#x22;: { type: 'number', description: '错误码', required: true },
  &#x22;message&#x22;: { type: 'string', description: '描述', required: true },
  &#x22;ok&#x22;: { type: 'boolean', description: '验证是否通过', required: true },
  &#x22;wrongCode&#x22;: { type: 'boolean', description: '验证码是否填错（可以让用户重试）', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L116)

### DyPassportVerifyContext [#DyPassportVerifyContext]

二次验证上下文

字段全部来自轮询响应，需原样透传给发码与验码接口，缺字段会被判为伪造请求。

<TypeTable
  type="{
  &#x22;copywritingKey&#x22;: { type: 'string', description: '文案场景，扫码登录固定为qr_connect', required: true },
  &#x22;diversionTag&#x22;: { type: 'string', description: '风控分流标记', required: true },
  &#x22;encryptUid&#x22;: { type: 'string', description: '加密后的用户 ID', required: true },
  &#x22;newVerifyFlow&#x22;: { type: 'string', description: '新版验证流标识', required: true },
  &#x22;stdParams&#x22;: { type: 'Record<string, string>', description: '验证会话票据', required: true },
  &#x22;verifyTicket&#x22;: { type: 'string', description: '验证票据', required: true },
  &#x22;verifyWays&#x22;: { type: 'DyPassportVerifyWay[]', description: '服务端给出的可选验证方式', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L29)

### DyPassportVerifyWay [#DyPassportVerifyWay]

二次验证的一种可选方式

<TypeTable
  type="{
  &#x22;mobile&#x22;: { type: 'string', description: '该方式关联的手机号（已脱敏）', required: true },
  &#x22;verifyWay&#x22;: { type: 'string', description: '方式标识，如mobile_sms_verify', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L17)

### EventBus [#EventBus]

类型安全的事件总线。

一个 client 实例一条。构造两条就是两条，彼此不共享监听器。

<TypeTable
  type="{
  &#x22;&#x22;: { type: 'unknown', required: true },
  &#x22;emit&#x22;: { type: 'unknown', required: true },
  &#x22;emitter&#x22;: { type: 'unknown', required: true },
  &#x22;listenerCount&#x22;: { type: 'unknown', required: true },
  &#x22;off&#x22;: { type: 'unknown', required: true },
  &#x22;on&#x22;: { type: 'unknown', required: true },
  &#x22;once&#x22;: { type: 'unknown', required: true },
  &#x22;removeAllListeners&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/runtime/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/runtime/events.ts#L287)

### FacadeServerOptions [#FacadeServerOptions]

门面版 `startServer` 的第二参。

只透出 `openapi` 一项；`port` / `host` / `token` / `routers` 这些全选项留给
`server/auth.ts` 的选项版 `startServer`。

<TypeTable
  type="{
  &#x22;listen&#x22;: { type: '__type(app: express.Application, port: number, host: string): void', description: '自定义监听实现，替代真实的app.listen。startServer不回传 server 句柄，所以需要自己控制端口、时机或关闭服务时\n用它。注入后log:mark不发（那句话在默认实现的回调里）。', required: true },
  &#x22;openapi&#x22;: { type: 'boolean', description: '自托管 OpenAPI 规范。默认false（不挂）。\n\n传true后：GET /openapi.json返回从端点注册表**现算**的规范（与调用方\n装的这个版本同源，不会像外挂文档那样脱节）；GET /docs不再 301 到 apifox，\n改 302 跳文档站的生成式端点参考。', required: true }
}"
/>

源码：[`src/client/createClient.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/createClient.ts#L99)

### HttpRequestEventData [#HttpRequestEventData]

HTTP 请求事件数据

<TypeTable
  type="{
  &#x22;headers&#x22;: { type: 'Record<string, string>', description: '请求头', required: true },
  &#x22;method&#x22;: { type: 'string', description: '请求方法 (GET, POST, etc.)', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true },
  &#x22;url&#x22;: { type: 'string', description: '请求 URL', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L58)

### HttpResponseEventData [#HttpResponseEventData]

HTTP 响应事件数据

<TypeTable
  type="{
  &#x22;clientIP&#x22;: { type: 'string', description: '客户端 IP', required: true },
  &#x22;method&#x22;: { type: 'string', description: '请求方法', required: true },
  &#x22;requestSize&#x22;: { type: 'string', description: '请求体大小', required: true },
  &#x22;responseSize&#x22;: { type: 'string', description: '响应体大小', required: true },
  &#x22;responseTime&#x22;: { type: 'number', description: '响应耗时 (毫秒)', required: true },
  &#x22;statusCode&#x22;: { type: 'number', description: 'HTTP 状态码', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true },
  &#x22;url&#x22;: { type: 'string', description: '请求 URL', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L73)

### KuaishouCaptchaChallenge [#KuaishouCaptchaChallenge]

交给调用方的风控挑战

<TypeTable
  type="{
  &#x22;bizName&#x22;: { type: 'string', description: '风控业务名，如ANTICRAWL_DEFAULT/ANTICRAWL_COMMON', required: true },
  &#x22;configUrl&#x22;: { type: 'string', description: '验证配置接口地址（…/rest/zt/captcha/sliding/config），自建验证页时要它', required: true },
  &#x22;jsSdkUrl&#x22;: { type: 'string', description: '前端验证 SDK 地址（已补协议），自建验证页时要它', required: true },
  &#x22;result&#x22;: { type: 'number', description: '命中的业务码：400002（PC）或2001（H5）', required: true },
  &#x22;session&#x22;: { type: 'string', description: '验证会话票据', required: true },
  &#x22;type&#x22;: { type: 'string | number', description: '验证类型，1是滑动拼图。回填时作identity-verification-type头', required: true },
  &#x22;url&#x22;: { type: 'string', description: '滑块页地址（已补协议，可直接给人打开）', required: true }
}"
/>

源码：[`src/platforms/kuaishou/captcha.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/kuaishou/captcha.ts#L77)

### KuaishouFetcher [#KuaishouFetcher]

快手 Fetcher 类型（静态形态：三参签名）。

写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名，
打印器（IDE 悬停 / twoslash / `.d.ts`）会把 `typeof kuaishouRegistry` 那些
`EndpointDef` 连 zod schema 一起整个内联展开。接口是**名义类型**：容器处只
打印这个名字，`KuaishouFetcher['fetchVideoWork']` 这样钻进去时方法签名依旧
完整 —— 类型不变，只是显示收敛。

源码：[`src/model/fetchers/kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/kuaishou/index.ts#L24)

### KuaishouMethodOptionsMap [#KuaishouMethodOptionsMap]

快手 API 方法参数映射

<TypeTable
  type="{
  &#x22;CommentParams&#x22;: { type: '{ methodType: &#x22;comments&#x22;; photoId: string }', required: true },
  &#x22;EmojiListParams&#x22;: { type: '{ methodType: &#x22;emojiList&#x22; }', required: true },
  &#x22;LiveRoomInfoParams&#x22;: { type: '{ methodType: &#x22;liveRoomInfo&#x22;; principalId: string }', required: true },
  &#x22;UserProfileParams&#x22;: { type: '{ methodType: &#x22;userProfile&#x22;; principalId: string }', required: true },
  &#x22;UserWorkListParams&#x22;: { type: '{ count: number; methodType: &#x22;userWorkList&#x22;; pcursor: string; principalId: string }', required: true },
  &#x22;VideoInfoParams&#x22;: { type: '{ methodType: &#x22;videoWork&#x22;; photoId: string }', required: true }
}"
/>

源码：[`src/types/KuaishouAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/KuaishouAPIParams.ts#L4)

### KuaishouReturnTypeMap [#KuaishouReturnTypeMap]

快手返回类型映射

<TypeTable
  type="{
  &#x22;comments&#x22;: { type: 'KsWorkComments', required: true },
  &#x22;danmakuList&#x22;: { type: 'KsDanmaku', required: true },
  &#x22;emojiList&#x22;: { type: 'KsEmojiList', required: true },
  &#x22;liveRoomInfo&#x22;: { type: 'KsLiveRoomInfo', required: true },
  &#x22;userProfile&#x22;: { type: 'KsUserProfile', required: true },
  &#x22;userWorkList&#x22;: { type: 'KsUserWorkList', required: true },
  &#x22;videoWork&#x22;: { type: 'KsOneWork', required: true },
  &#x22;videoWorkFull&#x22;: { type: 'KsOneWork', description: '完整版与免签主通道**共用**一份类型。\n\n不是偷懒：KsOneWork里那几个只有完整版才有的键（mp4Url/photos/comments）本来就声明成可选的，正是为了同时描述两种响应。给其中一条单开\n一份类型只会多一处会漂移的重复。\n\n另一层现实：那三个键在两个仓库共 15 份响应样本里出现 **0 次**，corpus 也\n录不到（完整版稳定撞2001）—— 所以「完整版类型更宽」目前只体现在声明上。', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/index.ts#L20)

### LogEventData [#LogEventData]

日志事件数据

<TypeTable
  type="{
  &#x22;args&#x22;: { type: 'unknown[]', description: '附加参数', required: true },
  &#x22;level&#x22;: { type: '&#x22;info&#x22; | &#x22;warn&#x22; | &#x22;error&#x22; | &#x22;debug&#x22; | &#x22;mark&#x22;', description: '日志级别', required: true },
  &#x22;message&#x22;: { type: 'string', description: '日志消息', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L43)

### LoginNamespace [#LoginNamespace]

登录命名空间：qrcode() 创建会话，resume() 从 opaque string 恢复

<TypeTable
  type="{
  &#x22;qrcode&#x22;: { type: 'unknown', required: true },
  &#x22;resume&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L172)

### LoginSession [#LoginSession]

登录会话：三种消费方式（回调 / AsyncIterable / 手动单步）。

返回终态时永不 reject（除调用方回调自己抛出）。

<TypeTable
  type="{
  &#x22;[Symbol.asyncIterator]&#x22;: { type: 'unknown', required: true },
  &#x22;answer&#x22;: { type: 'unknown', required: true },
  &#x22;next&#x22;: { type: 'unknown', required: true },
  &#x22;serialize&#x22;: { type: 'unknown', required: true },
  &#x22;start&#x22;: { type: 'unknown', required: true },
  &#x22;watch&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L184)

### MintDouyinGuestCookieOptions [#MintDouyinGuestCookieOptions]

<TypeTable
  type="{
  &#x22;force&#x22;: { type: 'boolean', required: true },
  &#x22;scriptTimeoutMs&#x22;: { type: 'number', required: true }
}"
/>

源码：[`src/platforms/douyin/guestCredential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/guestCredential.ts#L18)

### NetworkErrorEventData [#NetworkErrorEventData]

网络错误事件数据

<TypeTable
  type="{
  &#x22;errorCode&#x22;: { type: 'string', description: '错误代码', required: true },
  &#x22;message&#x22;: { type: 'string', description: '错误消息', required: true },
  &#x22;retries&#x22;: { type: 'number', description: '已重试次数', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true },
  &#x22;url&#x22;: { type: 'string', description: '请求 URL', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L115)

### NetworkRetryEventData [#NetworkRetryEventData]

网络重试事件数据

<TypeTable
  type="{
  &#x22;attempt&#x22;: { type: 'number', description: '当前重试次数', required: true },
  &#x22;delayMs&#x22;: { type: 'number', description: '重试延迟 (毫秒)', required: true },
  &#x22;errorCode&#x22;: { type: 'string', description: '错误代码', required: true },
  &#x22;maxRetries&#x22;: { type: 'number', description: '最大重试次数', required: true },
  &#x22;timestamp&#x22;: { type: 'Date', description: '事件时间戳', required: true },
  &#x22;url&#x22;: { type: 'string', description: '请求 URL', required: true }
}"
/>

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L96)

### NormalizedDouyinCookie [#NormalizedDouyinCookie]

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', required: true },
  &#x22;uifidSource&#x22;: { type: 'UifidSource', required: true }
}"
/>

源码：[`src/platforms/douyin/cookie.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/cookie.ts#L5)

### Qrcode [#Qrcode]

二维码

<TypeTable
  type="{
  &#x22;content&#x22;: { type: 'string', description: '二维码承载的内容，直接拿去生成图片', required: true },
  &#x22;expiresAt&#x22;: { type: 'number', description: '绝对过期时刻，Unix 毫秒', required: true },
  &#x22;expiresInSec&#x22;: { type: 'number', description: '剩余秒数，取码时算出', required: true },
  &#x22;token&#x22;: { type: 'string', description: '轮询令牌。B站是 qrcode_key，抖音是 token', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L37)

### QrcodeLoginStrategy [#QrcodeLoginStrategy]

平台扫码登录策略。

轮询循环 / 超时 / 退避 / 取消全在引擎里，策略只写协议细节。

<TypeTable
  type="{
  &#x22;answer&#x22;: { type: 'unknown', required: true },
  &#x22;deserialize&#x22;: { type: 'unknown', required: true },
  &#x22;platform&#x22;: { type: 'Platform', required: true },
  &#x22;poll&#x22;: { type: 'unknown', required: true },
  &#x22;serialize&#x22;: { type: 'unknown', required: true },
  &#x22;start&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L153)

### RequestTrace [#RequestTrace]

单次底层 HTTP 请求的明细

<TypeTable
  type="{
  &#x22;durationMs&#x22;: { type: 'number', description: '这一次请求本身的耗时', required: true },
  &#x22;method&#x22;: { type: 'string', description: 'HTTP 方法', required: true },
  &#x22;reason&#x22;: { type: 'TraceReason', description: '这次请求为什么会发出', required: true },
  &#x22;retryOf&#x22;: { type: 'AmagiErrorCode', description: 'reason === \'retry\'时，被重试的那次失败的错误码', required: true },
  &#x22;status&#x22;: { type: 'number', description: '平台返回的状态码，请求未发出（如 DNS 失败）时缺失', required: true },
  &#x22;url&#x22;: { type: 'string', description: '实际请求的 URL（含签名参数）', required: true }
}"
/>

源码：[`src/contracts/meta.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/meta.ts#L47)

### ResolvedDouyinCredential [#ResolvedDouyinCredential]

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', required: true },
  &#x22;loginState&#x22;: { type: 'DouyinLoginState', required: true },
  &#x22;origin&#x22;: { type: 'CredentialOrigin', required: true },
  &#x22;uifidSource&#x22;: { type: 'UifidSource', required: true }
}"
/>

源码：[`src/platforms/douyin/credential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/credential.ts#L16)

### ResolveDouyinCredentialOptions [#ResolveDouyinCredentialOptions]

<TypeTable
  type="{
  &#x22;needLogin&#x22;: { type: 'boolean', required: true },
  &#x22;noGuestFallback&#x22;: { type: 'boolean', required: true }
}"
/>

源码：[`src/platforms/douyin/credential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/credential.ts#L22)

### RiskChallenge [#RiskChallenge]

风控挑战：撞验证页时交给调用方的「怎么过去」。

为什么不塞进 `JudgeVerdict`：judge 只管**分类**，四个槽位装不下一个
URL。但 `kind: 'risk'` 光有分类是条死路 —— `CAPTCHA_REQUIRED` 只告诉调用方
「你被拦了」，不给出路。以前地址只能从 `error.raw` 里自己捞，而 `raw` 只在
`createClient({ debug: true })` 时才有、HTTP 路由那一面**结构上拿不到**
（`createXxxRoutes` 不接 `debug`）——最需要滑块地址的入口恰好是唯一产不出它的
入口。所以这一份**不受 `debug` 管**，只要 judge 判成 `risk` 就填。

只放地址与票据，不放原始响应体：它是「必要信息」而不是「排障明细」，
也没有大对象与凭证字段的顾虑。

**只做中转，不做绕过** —— amagi 不引入任何识别、轨迹模拟或自动过验证的代码。

<TypeTable
  type="{
  &#x22;bizName&#x22;: { type: 'string', description: '风控业务名', required: true },
  &#x22;configUrl&#x22;: { type: 'string', description: '验证配置接口地址，自建验证页时要它。\n\n快手给它是因为它 H5 那一面返回的地址**就是这个配置接口**\n（…/rest/zt/captcha/sliding/config，浏览器打开只有 JSON），所以url是\n平台的 redirect 页拼出来的、配置接口另放这里，两者都不丢。\n小红书给的是…/api/redcaptcha/v2/getconfig（验证页自己也打它取配置）。', required: true },
  &#x22;jsSdkUrl&#x22;: { type: 'string', description: '前端验证 SDK 地址（已补协议），自建验证页时要它', required: true },
  &#x22;result&#x22;: { type: 'string | number', description: '平台命中的业务码。\n\n小红书放的是 HTTP 状态（461/471）—— 它撞验证码时响应体的code是 0，\n真正的判据就是状态码本身。抖音放验证参数里的code（实测10000），\nHTTP 状态是 200、没有信息。', required: true },
  &#x22;session&#x22;: { type: 'string', description: '验证会话票据', required: true },
  &#x22;type&#x22;: { type: 'string | number', description: '验证类型。快手的1是滑动拼图，过验证后回填时作identity-verification-type头；\n小红书的取值来自verifytype响应头（实测给过301）；抖音放验证参数里的subtype（实测给过slide/text）。\n平台自己的取值，amagi 不翻译 —— 包括平台给出自家 SDK 枚举里都没有的值。', required: true },
  &#x22;url&#x22;: { type: 'string', description: '验证页地址（已补协议，可直接给人打开）', required: true },
  &#x22;verifyData&#x22;: { type: 'Record<string, unknown>', description: '完整的验证配置对象（平台侧的verify_data等），**自建验证页时原样交给前端\nSDK 的 render 调用**，不必自己拼。\n\n存在的理由是「有的平台只给url/session凑不出一张能用的验证页」：抖音滑块\n中间页要自建一张，形态就是照页面原样TTGCaptcha.init(options)之后TTGCaptcha.render({ verify_data })—— 整个对象必须交出去，拆不开。\n\n此前这里写的理由是「中间页实测verify_data.aid是 0，托管验证页靠 aid 取题，\n拿 0 大概取不出来」。那个推断**被实测否掉了**：2026-10-11 把 fixture 过一遍抖音的\n提取器，拿到的托管验证页地址在真浏览器里渲染出了真实滑块（captcha/get回 200，\n拼图背景图与缺口图都出来了）——aid=0不妨碍取题（n=1，**无负向对照**：没试过\n改坏detail或换aid看会不会被拒，所以不能据此说 aid 完全不参与）。\n准确说法见platforms/douyin/anticrawler/captcha.ts与platforms/douyin/captcha.ts。', required: true }
}"
/>

源码：[`src/contracts/error.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/error.ts#L277)

### SessionCtx [#SessionCtx]

平台会话上下文。

由引擎创建并逐次轮询更新；平台私有字段（biz\_trace\_id / verify\_way /
verifyTicket / encryptUid / stdParams / newVerifyFlow / diversionTag…）
放在 `data` 里由策略自己读写，引擎原样携带。

<TypeTable
  type="{
  &#x22;cookie&#x22;: { type: 'string', description: '会话 cookie（申请二维码时的那一份）', required: true },
  &#x22;data&#x22;: { type: 'Record<string, unknown>', description: '平台私有状态，策略自读写', required: true },
  &#x22;platform&#x22;: { type: 'Platform', description: '平台', required: true },
  &#x22;qrcode&#x22;: { type: 'Qrcode', description: '二维码（start 之后一直带着）', required: true },
  &#x22;requestConfig&#x22;: { type: 'RequestConfig', description: '调用方请求配置（代理、超时、额外请求头）', required: true },
  &#x22;send&#x22;: { type: '__type(spec: RequestSpec, reason?: TraceReason): Promise<RawResponse>', description: 'transport 的 send，策略用它发请求（修 A5：不直连 axios）。reason直接用TraceReason，不手抄一份联合 —— 这里曾经把五个取值抄了\n一遍，于是新增\'challenge\'时两处会分叉（抄的那份少一个取值，而meta.ts与endpoint.ts都用的是真类型）。meta.ts不反向引用本文件，无环。', required: true },
  &#x22;token&#x22;: { type: 'string', description: '轮询令牌（抖音 token / B站 qrcode_key）', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L125)

### SmsChallenge [#SmsChallenge]

短信验证码 challenge

<TypeTable
  type="{
  &#x22;availableWays&#x22;: { type: 'string[]', description: '平台给出的可选验证方式，原样保留供排查', required: true },
  &#x22;kind&#x22;: { type: '&#x22;sms&#x22;', required: true },
  &#x22;maskedMobile&#x22;: { type: 'string', description: '脱敏手机号，如 \'138****8000\'', required: true },
  &#x22;sendCode&#x22;: { type: 'unknown', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L59)

### SuccessBilibiliFetcher [#SuccessBilibiliFetcher]

只保留成功分支的B站 fetcher 类型。

给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成
这个类型，`.data` 就是 `T` 而不是 `T | undefined`。名义接口，理由同 [`BilibiliFetcher`](/docs/v7/usage/api/types/interfaces#BilibiliFetcher)。

源码：[`src/model/fetchers/bilibili/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/bilibili/index.ts#L76)

### SuccessDouyinFetcher [#SuccessDouyinFetcher]

只保留成功分支的抖音 fetcher 类型。

给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成
这个类型，`.data` 就是 `T` 而不是 `T | undefined`。名义接口，理由同上。

源码：[`src/model/fetchers/douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/douyin/index.ts#L97)

### SuccessKuaishouFetcher [#SuccessKuaishouFetcher]

只保留成功分支的快手 fetcher 类型。

给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成
这个类型，`.data` 就是 `T` 而不是 `T | undefined`。名义接口，理由同 [`KuaishouFetcher`](/docs/v7/usage/api/types/interfaces#KuaishouFetcher)。

源码：[`src/model/fetchers/kuaishou/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/kuaishou/index.ts#L70)

### SuccessXiaohongshuFetcher [#SuccessXiaohongshuFetcher]

只保留成功分支的小红书 fetcher 类型。

给「用一层 Proxy 把失败信封转成异常」的下游封装用：包装后的 fetcher 声明成
这个类型，`.data` 就是 `T` 而不是 `T | undefined`。名义接口，理由同 [`XiaohongshuFetcher`](/docs/v7/usage/api/types/interfaces#XiaohongshuFetcher)。

源码：[`src/model/fetchers/xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/xiaohongshu/index.ts#L75)

### ValidationIssue [#ValidationIssue]

`kind === 'validation'` 时的字段级错误

<TypeTable
  type="{
  &#x22;message&#x22;: { type: 'string', description: '面向人的说明', required: true },
  &#x22;path&#x22;: { type: 'string', description: '点号路径，如\'verify.stdParams.token\'', required: true },
  &#x22;received&#x22;: { type: 'unknown', description: '收到的值，用于排查', required: true }
}"
/>

源码：[`src/contracts/error.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/error.ts#L80)

### VerifyPageOptions [#VerifyPageOptions]

[`renderVerifyPage`](/docs/v7/usage/api/types/functions#renderVerifyPage) 的选项

<TypeTable
  type="{
  &#x22;platform&#x22;: { type: 'VerifyPlatform', description: 'challenge 来自哪个平台：决定默认标题、成功信号识别，以及能否用自建模式（仅抖音）', required: true },
  &#x22;title&#x22;: { type: 'string', description: '页面标题，默认「<平台>验证」；会做 HTML 转义', required: true }
}"
/>

源码：[`src/verify/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/verify/index.ts#L32)

### WatchHandlers [#WatchHandlers]

会话回调（watch 出口）

<TypeTable
  type="{
  &#x22;onChallenge&#x22;: { type: '__type<C>(challenge: C): ChallengeAnswer<C> | Promise<ChallengeAnswer<…>>', description: '需要二次验证。返回值驱动状态机前进', required: true },
  &#x22;onError&#x22;: { type: '__type(error: AmagiError, state: LoginState): void | Promise<void>', description: '终止性失败（expired / rejected / risk / failed）', required: true },
  &#x22;onQrcode&#x22;: { type: '__type(qrcode: Qrcode): void | Promise<void>', description: '二维码就绪。同一个会话里只会调用一次', required: true },
  &#x22;onScanned&#x22;: { type: '__type(): void | Promise<void>', description: '已扫码待确认', required: true },
  &#x22;onState&#x22;: { type: '__type(state: LoginState): void', description: '每次状态变化都会调用，用于日志', required: true },
  &#x22;onSuccess&#x22;: { type: '__type(credential: Credential): void | Promise<void>', description: '登录成功', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L94)

### WatchOptions [#WatchOptions]

会话 watch 选项

<TypeTable
  type="{
  &#x22;minIntervalMs&#x22;: { type: 'number', description: '轮询间隔的下限，防止服务端给出过小的 interval。默认 1000', required: true },
  &#x22;signal&#x22;: { type: 'AbortSignal', required: true },
  &#x22;timeoutMs&#x22;: { type: 'number', description: '整个会话的超时。默认取二维码的 expiresAt', required: true }
}"
/>

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L110)

### XiaohongshuFetcher [#XiaohongshuFetcher]

小红书 Fetcher 类型（静态形态：三参签名）。

写成 &#x2A;*`interface … extends`** 而不是 `type … =`：后者是泛型类型别名，
打印器（IDE 悬停 / twoslash / `.d.ts`）会把 `typeof xiaohongshuRegistry` 那些
`EndpointDef` 连 zod schema 一起整个内联展开。接口是**名义类型**：容器处只
打印这个名字，`XiaohongshuFetcher['fetchNoteDetail']` 这样钻进去时方法签名依旧
完整 —— 类型不变，只是显示收敛。

源码：[`src/model/fetchers/xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/fetchers/xiaohongshu/index.ts#L26)

### XiaohongshuMethodOptionsMap [#XiaohongshuMethodOptionsMap]

小红书 API 方法参数映射

<TypeTable
  type="{
  &#x22;CommentParams&#x22;: { type: '{ cursor: string; methodType: &#x22;noteComments&#x22;; note_id: string; xsec_token: string }', required: true },
  &#x22;EmojiListParams&#x22;: { type: '{ methodType: &#x22;emojiList&#x22; }', required: true },
  &#x22;HomeFeedParams&#x22;: { type: '{ category: string; cursor_score: string; methodType: &#x22;homeFeed&#x22;; note_index: number; num: number; refresh_type: number; …其余 1 个成员 }', required: true },
  &#x22;NoteParams&#x22;: { type: '{ methodType: &#x22;noteDetail&#x22;; note_id: string; xsec_token: string }', required: true },
  &#x22;SearchNoteParams&#x22;: { type: '{ keyword: string; methodType: &#x22;searchNotes&#x22;; note_type: SearchNoteType; page: number; page_size: number; sort: SearchSortType }', required: true },
  &#x22;UserNoteParams&#x22;: { type: '{ cursor: string; methodType: &#x22;userNoteList&#x22;; num: number; user_id: string }', required: true },
  &#x22;UserParams&#x22;: { type: '{ methodType: &#x22;userProfile&#x22;; user_id: string }', required: true }
}"
/>

源码：[`src/types/XiaohongshuAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/XiaohongshuAPIParams.ts#L6)

### XiaohongshuReturnTypeMap [#XiaohongshuReturnTypeMap]

小红书返回类型映射

<TypeTable
  type="{
  &#x22;emojiList&#x22;: { type: 'XiaohongshuEmojiList', required: true },
  &#x22;homeFeed&#x22;: { type: 'HomeFeed', required: true },
  &#x22;noteComments&#x22;: { type: 'NoteComments', required: true },
  &#x22;noteDetail&#x22;: { type: 'OneNote', required: true },
  &#x22;searchNotes&#x22;: { type: 'SearchNotes', required: true },
  &#x22;userNoteList&#x22;: { type: 'XiaohongshuUserNoteList', required: true },
  &#x22;userProfile&#x22;: { type: 'XiaohongshuUserProfile', required: true }
}"
/>

源码：[`src/types/ReturnDataType/Xiaohongshu/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/index.ts#L20)

### XiaohongshuSessionInput [#XiaohongshuSessionInput]

小红书同一会话的 Cookie 与可选签名材料；不属于 HTTP 请求配置。

<TypeTable
  type="{
  &#x22;b1&#x22;: { type: 'string', description: '同一会话已有的 localStorage.b1；不从 Cookie 推导。', required: true },
  &#x22;cookie&#x22;: { type: 'string', required: true },
  &#x22;userId&#x22;: { type: 'string', description: '当前会话用户（包括游客）的 ID，用于 xy-direction；不是笔记作者 ID。', required: true },
  &#x22;webSsk&#x22;: { type: 'string | Readonly<Record<string, string>>', description: 'localStorage.webSsk 的 JSON 或 appId → 标准 Base64 密钥映射。', required: true }
}"
/>

源码：[`src/contracts/cookie.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/cookie.ts#L11)


# B站响应类型 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/types-bilibili)

> 103 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 103 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### ArticleCard [#ArticleCard]

```ts
type ArticleCard = ArticleCard_V0
```

源码：[`src/types/ReturnDataType/Bilibili/ArticleCard/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/ArticleCard/index.ts#L3)

### ArticleContent [#ArticleContent]

```ts
type ArticleContent = ArticleContent_V0
```

源码：[`src/types/ReturnDataType/Bilibili/ArticleContent/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/ArticleContent/index.ts#L6)

### ArticleInfo [#ArticleInfo]

```ts
type ArticleInfo = ArticleInfo_V0
```

源码：[`src/types/ReturnDataType/Bilibili/ArticleInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/ArticleInfo/index.ts#L3)

### BiliAv2Bv [#BiliAv2Bv]

```ts
type BiliAv2Bv = BiliAv2Bv_V0
```

源码：[`src/types/ReturnDataType/Bilibili/AV2BV/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/AV2BV/index.ts#L3)

### BiliBangumiVideoInfo [#BiliBangumiVideoInfo]

```ts
type BiliBangumiVideoInfo = BiliBangumiVideoInfo_V0
```

源码：[`src/types/ReturnDataType/Bilibili/BangumiVideoInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/BangumiVideoInfo/index.ts#L3)

### BiliBangumiVideoPlayurlIsLogin [#BiliBangumiVideoPlayurlIsLogin]

```ts
type BiliBangumiVideoPlayurlIsLogin = BiliBangumiVideoPlayurlIsLogin_V0
```

源码：[`src/types/ReturnDataType/Bilibili/BangumiVideoPlayurlIsLogin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/BangumiVideoPlayurlIsLogin/index.ts#L3)

### BiliBangumiVideoPlayurlNoLogin [#BiliBangumiVideoPlayurlNoLogin]

```ts
type BiliBangumiVideoPlayurlNoLogin = BiliBangumiVideoPlayurlNoLogin_V0
```

源码：[`src/types/ReturnDataType/Bilibili/BangumiVideoPlayurlNoLogin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/BangumiVideoPlayurlNoLogin/index.ts#L3)

### BilibiliArticleCardsResponse [#BilibiliArticleCardsResponse]

```ts
type BilibiliArticleCardsResponse = ArticleCardsSuccess | ArticleCardsError
```

源码：`../response-types/dist/generated/bilibili/ArticleCards/index.d.ts`（无链接）

### BilibiliArticleCardsResponseError [#BilibiliArticleCardsResponseError]

```ts
type BilibiliArticleCardsResponseError = never
```

源码：`../response-types/dist/generated/bilibili/ArticleCards/index.d.ts`（无链接）

### BilibiliArticleCardsResponseSuccess [#BilibiliArticleCardsResponseSuccess]

```ts
type BilibiliArticleCardsResponseSuccess = ArticleCards_V0
```

源码：`../response-types/dist/generated/bilibili/ArticleCards/index.d.ts`（无链接）

### BilibiliArticleContentResponse [#BilibiliArticleContentResponse]

```ts
type BilibiliArticleContentResponse = ArticleContentSuccess | ArticleContentError
```

源码：`../response-types/dist/generated/bilibili/ArticleContent/index.d.ts`（无链接）

### BilibiliArticleContentResponseError [#BilibiliArticleContentResponseError]

```ts
type BilibiliArticleContentResponseError = never
```

源码：`../response-types/dist/generated/bilibili/ArticleContent/index.d.ts`（无链接）

### BilibiliArticleContentResponseSuccess [#BilibiliArticleContentResponseSuccess]

```ts
type BilibiliArticleContentResponseSuccess = ArticleContent_V0
```

源码：`../response-types/dist/generated/bilibili/ArticleContent/index.d.ts`（无链接）

### BilibiliArticleInfoResponse [#BilibiliArticleInfoResponse]

```ts
type BilibiliArticleInfoResponse = ArticleInfoSuccess | ArticleInfoError
```

源码：`../response-types/dist/generated/bilibili/ArticleInfo/index.d.ts`（无链接）

### BilibiliArticleInfoResponseError [#BilibiliArticleInfoResponseError]

```ts
type BilibiliArticleInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/ArticleInfo/index.d.ts`（无链接）

### BilibiliArticleInfoResponseSuccess [#BilibiliArticleInfoResponseSuccess]

```ts
type BilibiliArticleInfoResponseSuccess = ArticleInfo_V0
```

源码：`../response-types/dist/generated/bilibili/ArticleInfo/index.d.ts`（无链接）

### BilibiliArticleListInfoResponse [#BilibiliArticleListInfoResponse]

```ts
type BilibiliArticleListInfoResponse = ArticleListInfoSuccess | ArticleListInfoError
```

源码：`../response-types/dist/generated/bilibili/ArticleListInfo/index.d.ts`（无链接）

### BilibiliArticleListInfoResponseError [#BilibiliArticleListInfoResponseError]

```ts
type BilibiliArticleListInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/ArticleListInfo/index.d.ts`（无链接）

### BilibiliArticleListInfoResponseSuccess [#BilibiliArticleListInfoResponseSuccess]

```ts
type BilibiliArticleListInfoResponseSuccess = ArticleListInfo_V0
```

源码：`../response-types/dist/generated/bilibili/ArticleListInfo/index.d.ts`（无链接）

### BilibiliBangumiInfoResponse [#BilibiliBangumiInfoResponse]

```ts
type BilibiliBangumiInfoResponse = BangumiInfoSuccess | BangumiInfoError
```

源码：`../response-types/dist/generated/bilibili/BangumiInfo/index.d.ts`（无链接）

### BilibiliBangumiInfoResponseError [#BilibiliBangumiInfoResponseError]

```ts
type BilibiliBangumiInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/BangumiInfo/index.d.ts`（无链接）

### BilibiliBangumiInfoResponseSuccess [#BilibiliBangumiInfoResponseSuccess]

```ts
type BilibiliBangumiInfoResponseSuccess = BangumiInfo_V0
```

源码：`../response-types/dist/generated/bilibili/BangumiInfo/index.d.ts`（无链接）

### BilibiliBangumiStreamResponse [#BilibiliBangumiStreamResponse]

```ts
type BilibiliBangumiStreamResponse = BangumiStreamSuccess | BangumiStreamError
```

源码：`../response-types/dist/generated/bilibili/BangumiStream/index.d.ts`（无链接）

### BilibiliBangumiStreamResponseError [#BilibiliBangumiStreamResponseError]

```ts
type BilibiliBangumiStreamResponseError = never
```

源码：`../response-types/dist/generated/bilibili/BangumiStream/index.d.ts`（无链接）

### BilibiliBangumiStreamResponseSuccess [#BilibiliBangumiStreamResponseSuccess]

```ts
type BilibiliBangumiStreamResponseSuccess = BangumiStream_V0
```

源码：`../response-types/dist/generated/bilibili/BangumiStream/index.d.ts`（无链接）

### BilibiliCommentRepliesResponse [#BilibiliCommentRepliesResponse]

```ts
type BilibiliCommentRepliesResponse = CommentRepliesSuccess | CommentRepliesError
```

源码：`../response-types/dist/generated/bilibili/CommentReplies/index.d.ts`（无链接）

### BilibiliCommentRepliesResponseError [#BilibiliCommentRepliesResponseError]

```ts
type BilibiliCommentRepliesResponseError = never
```

源码：`../response-types/dist/generated/bilibili/CommentReplies/index.d.ts`（无链接）

### BilibiliCommentRepliesResponseSuccess [#BilibiliCommentRepliesResponseSuccess]

```ts
type BilibiliCommentRepliesResponseSuccess = CommentReplies_V0
```

源码：`../response-types/dist/generated/bilibili/CommentReplies/index.d.ts`（无链接）

### BilibiliCommentsResponse [#BilibiliCommentsResponse]

```ts
type BilibiliCommentsResponse = CommentsSuccess | CommentsError
```

源码：`../response-types/dist/generated/bilibili/Comments/index.d.ts`（无链接）

### BilibiliCommentsResponseError [#BilibiliCommentsResponseError]

```ts
type BilibiliCommentsResponseError = never
```

源码：`../response-types/dist/generated/bilibili/Comments/index.d.ts`（无链接）

### BilibiliCommentsResponseSuccess [#BilibiliCommentsResponseSuccess]

```ts
type BilibiliCommentsResponseSuccess = Comments_V0
```

源码：`../response-types/dist/generated/bilibili/Comments/index.d.ts`（无链接）

### BilibiliDynamicDetailResponse [#BilibiliDynamicDetailResponse]

```ts
type BilibiliDynamicDetailResponse = DynamicDetailSuccess | DynamicDetailError
```

源码：`../response-types/dist/generated/bilibili/DynamicDetail/index.d.ts`（无链接）

### BilibiliDynamicDetailResponseError [#BilibiliDynamicDetailResponseError]

```ts
type BilibiliDynamicDetailResponseError = never
```

源码：`../response-types/dist/generated/bilibili/DynamicDetail/index.d.ts`（无链接）

### BilibiliDynamicDetailResponseSuccess [#BilibiliDynamicDetailResponseSuccess]

```ts
type BilibiliDynamicDetailResponseSuccess = DynamicDetailUnion
```

源码：`../response-types/dist/generated/bilibili/DynamicDetail/index.d.ts`（无链接）

### BilibiliEmojiListResponse [#BilibiliEmojiListResponse]

```ts
type BilibiliEmojiListResponse = EmojiListSuccess | EmojiListError
```

源码：`../response-types/dist/generated/bilibili/EmojiList/index.d.ts`（无链接）

### BilibiliEmojiListResponseError [#BilibiliEmojiListResponseError]

```ts
type BilibiliEmojiListResponseError = never
```

源码：`../response-types/dist/generated/bilibili/EmojiList/index.d.ts`（无链接）

### BilibiliEmojiListResponseSuccess [#BilibiliEmojiListResponseSuccess]

```ts
type BilibiliEmojiListResponseSuccess = EmojiList_V0
```

源码：`../response-types/dist/generated/bilibili/EmojiList/index.d.ts`（无链接）

### BilibiliLiveRoomInfoResponse [#BilibiliLiveRoomInfoResponse]

```ts
type BilibiliLiveRoomInfoResponse = LiveRoomInfoSuccess | LiveRoomInfoError
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInfo/index.d.ts`（无链接）

### BilibiliLiveRoomInfoResponseError [#BilibiliLiveRoomInfoResponseError]

```ts
type BilibiliLiveRoomInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInfo/index.d.ts`（无链接）

### BilibiliLiveRoomInfoResponseSuccess [#BilibiliLiveRoomInfoResponseSuccess]

```ts
type BilibiliLiveRoomInfoResponseSuccess = LiveRoomInfo_V0
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInfo/index.d.ts`（无链接）

### BilibiliLiveRoomInitResponse [#BilibiliLiveRoomInitResponse]

```ts
type BilibiliLiveRoomInitResponse = LiveRoomInitSuccess | LiveRoomInitError
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInit/index.d.ts`（无链接）

### BilibiliLiveRoomInitResponseError [#BilibiliLiveRoomInitResponseError]

```ts
type BilibiliLiveRoomInitResponseError = never
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInit/index.d.ts`（无链接）

### BilibiliLiveRoomInitResponseSuccess [#BilibiliLiveRoomInitResponseSuccess]

```ts
type BilibiliLiveRoomInitResponseSuccess = LiveRoomInit_V0
```

源码：`../response-types/dist/generated/bilibili/LiveRoomInit/index.d.ts`（无链接）

### BilibiliLoginQrcodeResponse [#BilibiliLoginQrcodeResponse]

```ts
type BilibiliLoginQrcodeResponse = LoginQrcodeSuccess | LoginQrcodeError
```

源码：`../response-types/dist/generated/bilibili/LoginQrcode/index.d.ts`（无链接）

### BilibiliLoginQrcodeResponseError [#BilibiliLoginQrcodeResponseError]

```ts
type BilibiliLoginQrcodeResponseError = never
```

源码：`../response-types/dist/generated/bilibili/LoginQrcode/index.d.ts`（无链接）

### BilibiliLoginQrcodeResponseSuccess [#BilibiliLoginQrcodeResponseSuccess]

```ts
type BilibiliLoginQrcodeResponseSuccess = LoginQrcode_V0
```

源码：`../response-types/dist/generated/bilibili/LoginQrcode/index.d.ts`（无链接）

### BilibiliLoginStatusResponse [#BilibiliLoginStatusResponse]

```ts
type BilibiliLoginStatusResponse = LoginStatusSuccess | LoginStatusError
```

源码：`../response-types/dist/generated/bilibili/LoginStatus/index.d.ts`（无链接）

### BilibiliLoginStatusResponseError [#BilibiliLoginStatusResponseError]

```ts
type BilibiliLoginStatusResponseError = never
```

源码：`../response-types/dist/generated/bilibili/LoginStatus/index.d.ts`（无链接）

### BilibiliLoginStatusResponseSuccess [#BilibiliLoginStatusResponseSuccess]

```ts
type BilibiliLoginStatusResponseSuccess = LoginStatus_V0
```

源码：`../response-types/dist/generated/bilibili/LoginStatus/index.d.ts`（无链接）

### BilibiliQrcodeStatusResponse [#BilibiliQrcodeStatusResponse]

```ts
type BilibiliQrcodeStatusResponse = QrcodeStatusSuccess | QrcodeStatusError
```

源码：`../response-types/dist/generated/bilibili/QrcodeStatus/index.d.ts`（无链接）

### BilibiliQrcodeStatusResponseError [#BilibiliQrcodeStatusResponseError]

```ts
type BilibiliQrcodeStatusResponseError = never
```

源码：`../response-types/dist/generated/bilibili/QrcodeStatus/index.d.ts`（无链接）

### BilibiliQrcodeStatusResponseSuccess [#BilibiliQrcodeStatusResponseSuccess]

```ts
type BilibiliQrcodeStatusResponseSuccess = QrcodeStatus_V0
```

源码：`../response-types/dist/generated/bilibili/QrcodeStatus/index.d.ts`（无链接）

### BilibiliUploaderTotalViewsResponse [#BilibiliUploaderTotalViewsResponse]

```ts
type BilibiliUploaderTotalViewsResponse = UploaderTotalViewsSuccess | UploaderTotalViewsError
```

源码：`../response-types/dist/generated/bilibili/UploaderTotalViews/index.d.ts`（无链接）

### BilibiliUploaderTotalViewsResponseError [#BilibiliUploaderTotalViewsResponseError]

```ts
type BilibiliUploaderTotalViewsResponseError = never
```

源码：`../response-types/dist/generated/bilibili/UploaderTotalViews/index.d.ts`（无链接）

### BilibiliUploaderTotalViewsResponseSuccess [#BilibiliUploaderTotalViewsResponseSuccess]

```ts
type BilibiliUploaderTotalViewsResponseSuccess = UploaderTotalViews_V0
```

源码：`../response-types/dist/generated/bilibili/UploaderTotalViews/index.d.ts`（无链接）

### BilibiliUserCardResponse [#BilibiliUserCardResponse]

```ts
type BilibiliUserCardResponse = UserCardSuccess | UserCardError
```

源码：`../response-types/dist/generated/bilibili/UserCard/index.d.ts`（无链接）

### BilibiliUserCardResponseError [#BilibiliUserCardResponseError]

```ts
type BilibiliUserCardResponseError = never
```

源码：`../response-types/dist/generated/bilibili/UserCard/index.d.ts`（无链接）

### BilibiliUserCardResponseSuccess [#BilibiliUserCardResponseSuccess]

```ts
type BilibiliUserCardResponseSuccess = UserCard_V0
```

源码：`../response-types/dist/generated/bilibili/UserCard/index.d.ts`（无链接）

### BilibiliUserDynamicListResponse [#BilibiliUserDynamicListResponse]

```ts
type BilibiliUserDynamicListResponse = UserDynamicListSuccess | UserDynamicListError
```

源码：`../response-types/dist/generated/bilibili/UserDynamicList/index.d.ts`（无链接）

### BilibiliUserDynamicListResponseError [#BilibiliUserDynamicListResponseError]

```ts
type BilibiliUserDynamicListResponseError = never
```

源码：`../response-types/dist/generated/bilibili/UserDynamicList/index.d.ts`（无链接）

### BilibiliUserDynamicListResponseSuccess [#BilibiliUserDynamicListResponseSuccess]

```ts
type BilibiliUserDynamicListResponseSuccess = UserDynamicList_V0
```

源码：`../response-types/dist/generated/bilibili/UserDynamicList/index.d.ts`（无链接）

### BilibiliUserLiveStatusResponse [#BilibiliUserLiveStatusResponse]

```ts
type BilibiliUserLiveStatusResponse = UserLiveStatusSuccess | UserLiveStatusError
```

源码：`../response-types/dist/generated/bilibili/UserLiveStatus/index.d.ts`（无链接）

### BilibiliUserLiveStatusResponseError [#BilibiliUserLiveStatusResponseError]

```ts
type BilibiliUserLiveStatusResponseError = never
```

源码：`../response-types/dist/generated/bilibili/UserLiveStatus/index.d.ts`（无链接）

### BilibiliUserLiveStatusResponseSuccess [#BilibiliUserLiveStatusResponseSuccess]

```ts
type BilibiliUserLiveStatusResponseSuccess = UserLiveStatus_V0
```

源码：`../response-types/dist/generated/bilibili/UserLiveStatus/index.d.ts`（无链接）

### BilibiliUserSpaceInfoResponse [#BilibiliUserSpaceInfoResponse]

```ts
type BilibiliUserSpaceInfoResponse = UserSpaceInfoSuccess | UserSpaceInfoError
```

源码：`../response-types/dist/generated/bilibili/UserSpaceInfo/index.d.ts`（无链接）

### BilibiliUserSpaceInfoResponseError [#BilibiliUserSpaceInfoResponseError]

```ts
type BilibiliUserSpaceInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/UserSpaceInfo/index.d.ts`（无链接）

### BilibiliUserSpaceInfoResponseSuccess [#BilibiliUserSpaceInfoResponseSuccess]

```ts
type BilibiliUserSpaceInfoResponseSuccess = UserSpaceInfo_V0
```

源码：`../response-types/dist/generated/bilibili/UserSpaceInfo/index.d.ts`（无链接）

### BilibiliVideoDanmakuResponse [#BilibiliVideoDanmakuResponse]

```ts
type BilibiliVideoDanmakuResponse = VideoDanmakuSuccess | VideoDanmakuError
```

源码：`../response-types/dist/generated/bilibili/VideoDanmaku/index.d.ts`（无链接）

### BilibiliVideoDanmakuResponseError [#BilibiliVideoDanmakuResponseError]

```ts
type BilibiliVideoDanmakuResponseError = never
```

源码：`../response-types/dist/generated/bilibili/VideoDanmaku/index.d.ts`（无链接）

### BilibiliVideoDanmakuResponseSuccess [#BilibiliVideoDanmakuResponseSuccess]

```ts
type BilibiliVideoDanmakuResponseSuccess = VideoDanmaku_V0
```

源码：`../response-types/dist/generated/bilibili/VideoDanmaku/index.d.ts`（无链接）

### BilibiliVideoInfoResponse [#BilibiliVideoInfoResponse]

```ts
type BilibiliVideoInfoResponse = VideoInfoSuccess | VideoInfoError
```

源码：`../response-types/dist/generated/bilibili/VideoInfo/index.d.ts`（无链接）

### BilibiliVideoInfoResponseError [#BilibiliVideoInfoResponseError]

```ts
type BilibiliVideoInfoResponseError = never
```

源码：`../response-types/dist/generated/bilibili/VideoInfo/index.d.ts`（无链接）

### BilibiliVideoInfoResponseSuccess [#BilibiliVideoInfoResponseSuccess]

```ts
type BilibiliVideoInfoResponseSuccess = VideoInfo_V0
```

源码：`../response-types/dist/generated/bilibili/VideoInfo/index.d.ts`（无链接）

### BiliBiliVideoPlayurlNoLogin [#BiliBiliVideoPlayurlNoLogin]

```ts
type BiliBiliVideoPlayurlNoLogin = BiliBiliVideoPlayurlNoLogin_V0
```

源码：[`src/types/ReturnDataType/Bilibili/VideoPlayurlNoLogin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/VideoPlayurlNoLogin/index.ts#L3)

### BilibiliVideoStreamResponse [#BilibiliVideoStreamResponse]

```ts
type BilibiliVideoStreamResponse = VideoStreamSuccess | VideoStreamError
```

源码：`../response-types/dist/generated/bilibili/VideoStream/index.d.ts`（无链接）

### BilibiliVideoStreamResponseError [#BilibiliVideoStreamResponseError]

```ts
type BilibiliVideoStreamResponseError = never
```

源码：`../response-types/dist/generated/bilibili/VideoStream/index.d.ts`（无链接）

### BilibiliVideoStreamResponseSuccess [#BilibiliVideoStreamResponseSuccess]

```ts
type BilibiliVideoStreamResponseSuccess = VideoStream_V0
```

源码：`../response-types/dist/generated/bilibili/VideoStream/index.d.ts`（无链接）

### BiliBv2AV [#BiliBv2AV]

```ts
type BiliBv2AV = BiliBv2AV_V0
```

源码：[`src/types/ReturnDataType/Bilibili/BV2AV/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/BV2AV/index.ts#L3)

### BiliCheckQrcode [#BiliCheckQrcode]

```ts
type BiliCheckQrcode = BiliCheckQrcode_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Login/CheckQrcode/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Login/CheckQrcode/index.ts#L3)

### BiliCommentReply [#BiliCommentReply]

```ts
type BiliCommentReply = BiliCommentReply_V0
```

源码：[`src/types/ReturnDataType/Bilibili/BiliCommentReply/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/BiliCommentReply/index.ts#L3)

### BiliDynamicInfo [#BiliDynamicInfo]

```ts
type BiliDynamicInfo<T extends DynamicType> = { code: number; data: DataData<T>; message: string; ttl: number }
```

源码：[`src/types/ReturnDataType/Bilibili/DynamicInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/DynamicInfo/index.ts#L34)

### BiliDynamicInfoUnion [#BiliDynamicInfoUnion]

```ts
type BiliDynamicInfoUnion = DynamicTypeAV | DynamicTypeDraw | DynamicTypeWord | DynamicTypeLiveRcmd | DynamicTypeForwardUnion | DynamicTypeArticle
```

源码：[`src/types/ReturnDataType/Bilibili/DynamicInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/DynamicInfo/index.ts#L13)

### BiliEmojiList [#BiliEmojiList]

```ts
type BiliEmojiList = BiliEmojiList_V0
```

源码：[`src/types/ReturnDataType/Bilibili/EmojiList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/EmojiList/index.ts#L3)

### BiliLiveRoomDef [#BiliLiveRoomDef]

```ts
type BiliLiveRoomDef = BiliLiveRoomDef_V0
```

源码：[`src/types/ReturnDataType/Bilibili/LiveRoomDef/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/LiveRoomDef/index.ts#L3)

### BiliLiveRoomDetail [#BiliLiveRoomDetail]

```ts
type BiliLiveRoomDetail = BiliLiveRoomDetail_V0
```

源码：[`src/types/ReturnDataType/Bilibili/LiveRoomDetail/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/LiveRoomDetail/index.ts#L3)

### BiliLoginStatus [#BiliLoginStatus]

```ts
type BiliLoginStatus = BiliLoginStatus_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Login/LoginStatus/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Login/LoginStatus/index.ts#L3)

### BiliNewLoginQrcode [#BiliNewLoginQrcode]

```ts
type BiliNewLoginQrcode = BiliNewLoginQrcode_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Login/NewLoginQrcode/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Login/NewLoginQrcode/index.ts#L6)

### BiliOneWork [#BiliOneWork]

```ts
type BiliOneWork = BiliOneWork_V0
```

源码：[`src/types/ReturnDataType/Bilibili/OneWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/OneWork/index.ts#L3)

### BiliProtobufDanmaku [#BiliProtobufDanmaku]

```ts
type BiliProtobufDanmaku = BiliProtobufDanmaku_V0
```

源码：[`src/types/ReturnDataType/Bilibili/ProtobufDanmaku/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/ProtobufDanmaku/index.ts#L3)

### BiliUserDynamic [#BiliUserDynamic]

```ts
type BiliUserDynamic = { code: number; data: DataData; message: string; ttl: number }
```

源码：[`src/types/ReturnDataType/Bilibili/UserDynamic/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/UserDynamic/index.ts#L11)

### BiliUserFullView [#BiliUserFullView]

```ts
type BiliUserFullView = BiliUserFullView_V0
```

源码：[`src/types/ReturnDataType/Bilibili/UserFullView/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/UserFullView/index.ts#L3)

### BiliUserLiveStatus [#BiliUserLiveStatus]

```ts
type BiliUserLiveStatus = BiliUserLiveStatus_V0
```

源码：[`src/types/ReturnDataType/Bilibili/UserLiveStatus/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/UserLiveStatus/index.ts#L3)

### BiliUserProfile [#BiliUserProfile]

```ts
type BiliUserProfile = BiliUserProfile_V0
```

源码：[`src/types/ReturnDataType/Bilibili/UserProfile/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/UserProfile/index.ts#L3)

### BiliVideoPlayurlIsLogin [#BiliVideoPlayurlIsLogin]

```ts
type BiliVideoPlayurlIsLogin = BiliVideoPlayurlIsLogin_V0
```

源码：[`src/types/ReturnDataType/Bilibili/VideoPlayurlIsLogin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/VideoPlayurlIsLogin/index.ts#L3)

### BiliWorkComments [#BiliWorkComments]

```ts
type BiliWorkComments = BiliWorkComments_V0
```

源码：[`src/types/ReturnDataType/Bilibili/WorkComments/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/WorkComments/index.ts#L3)

### ColumnInfo [#ColumnInfo]

```ts
type ColumnInfo = ColumnInfo_V0
```

源码：[`src/types/ReturnDataType/Bilibili/ColumnInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/ColumnInfo/index.ts#L3)

### DynamicTypeArticle [#DynamicTypeArticle]

```ts
type DynamicTypeArticle = DynamicTypeArticle_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_ARTICLE/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_ARTICLE/index.ts#L3)

### DynamicTypeAV [#DynamicTypeAV]

```ts
type DynamicTypeAV = DynamicTypeAV_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_AV/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_AV/index.ts#L3)

### DynamicTypeDraw [#DynamicTypeDraw]

```ts
type DynamicTypeDraw = DynamicTypeDraw_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_DRAW/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_DRAW/index.ts#L3)

### DynamicTypeForward [#DynamicTypeForward]

```ts
type DynamicTypeForward<T extends keyof OriginalDynamicItemMap> = { code: number; data: DataData<T>; message: string; ttl: number }
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_FORWARD/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_FORWARD/index.ts#L39)

### DynamicTypeForwardUnion [#DynamicTypeForwardUnion]

```ts
type DynamicTypeForwardUnion = DynamicTypeForward<DynamicType.AV> | DynamicTypeForward<DynamicType.DRAW> | DynamicTypeForward<DynamicType.WORD> | DynamicTypeForward<DynamicType.LIVE_RCMD>
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_FORWARD/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_FORWARD/index.ts#L47)

### DynamicTypeLiveRcmd [#DynamicTypeLiveRcmd]

```ts
type DynamicTypeLiveRcmd = DynamicTypeLiveRcmd_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_LIVE_RCMD/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_LIVE_RCMD/index.ts#L3)

### DynamicTypeWord [#DynamicTypeWord]

```ts
type DynamicTypeWord = DynamicTypeWord_V0
```

源码：[`src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_WORD/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Bilibili/Dynamic/DYNAMIC_TYPE_WORD/index.ts#L3)


# 抖音响应类型 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/types-douyin)

> 102 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 102 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### ArticleWork [#ArticleWork]

```ts
type ArticleWork = ArticleWork_V0
```

源码：[`src/types/ReturnDataType/Douyin/ArticleWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/ArticleWork/index.ts#L3)

### CommentReply [#CommentReply]

```ts
type CommentReply = CommentReply_V0
```

源码：[`src/types/ReturnDataType/Douyin/CommentReply/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/CommentReply/index.ts#L3)

### DouyinCommentRepliesResponse [#DouyinCommentRepliesResponse]

```ts
type DouyinCommentRepliesResponse = CommentRepliesSuccess | CommentRepliesError
```

源码：`../response-types/dist/generated/douyin/CommentReplies/index.d.ts`（无链接）

### DouyinCommentRepliesResponseError [#DouyinCommentRepliesResponseError]

```ts
type DouyinCommentRepliesResponseError = never
```

源码：`../response-types/dist/generated/douyin/CommentReplies/index.d.ts`（无链接）

### DouyinCommentRepliesResponseSuccess [#DouyinCommentRepliesResponseSuccess]

```ts
type DouyinCommentRepliesResponseSuccess = CommentReplies_V0
```

源码：`../response-types/dist/generated/douyin/CommentReplies/index.d.ts`（无链接）

### DouyinCommentsResponse [#DouyinCommentsResponse]

```ts
type DouyinCommentsResponse = CommentsSuccess | CommentsError
```

源码：`../response-types/dist/generated/douyin/Comments/index.d.ts`（无链接）

### DouyinCommentsResponseError [#DouyinCommentsResponseError]

```ts
type DouyinCommentsResponseError = never
```

源码：`../response-types/dist/generated/douyin/Comments/index.d.ts`（无链接）

### DouyinCommentsResponseSuccess [#DouyinCommentsResponseSuccess]

```ts
type DouyinCommentsResponseSuccess = Comments_V0
```

源码：`../response-types/dist/generated/douyin/Comments/index.d.ts`（无链接）

### DouyinDanmakuListResponse [#DouyinDanmakuListResponse]

```ts
type DouyinDanmakuListResponse = DanmakuListSuccess | DanmakuListError
```

源码：`../response-types/dist/generated/douyin/DanmakuList/index.d.ts`（无链接）

### DouyinDanmakuListResponseError [#DouyinDanmakuListResponseError]

```ts
type DouyinDanmakuListResponseError = never
```

源码：`../response-types/dist/generated/douyin/DanmakuList/index.d.ts`（无链接）

### DouyinDanmakuListResponseSuccess [#DouyinDanmakuListResponseSuccess]

```ts
type DouyinDanmakuListResponseSuccess = DanmakuList_V0
```

源码：`../response-types/dist/generated/douyin/DanmakuList/index.d.ts`（无链接）

### DouyinDynamicEmojiListResponse [#DouyinDynamicEmojiListResponse]

```ts
type DouyinDynamicEmojiListResponse = DynamicEmojiListSuccess | DynamicEmojiListError
```

源码：`../response-types/dist/generated/douyin/DynamicEmojiList/index.d.ts`（无链接）

### DouyinDynamicEmojiListResponseError [#DouyinDynamicEmojiListResponseError]

```ts
type DouyinDynamicEmojiListResponseError = never
```

源码：`../response-types/dist/generated/douyin/DynamicEmojiList/index.d.ts`（无链接）

### DouyinDynamicEmojiListResponseSuccess [#DouyinDynamicEmojiListResponseSuccess]

```ts
type DouyinDynamicEmojiListResponseSuccess = DynamicEmojiList_V0
```

源码：`../response-types/dist/generated/douyin/DynamicEmojiList/index.d.ts`（无链接）

### DouyinEmojiListResponse [#DouyinEmojiListResponse]

```ts
type DouyinEmojiListResponse = EmojiListSuccess | EmojiListError
```

源码：`../response-types/dist/generated/douyin/EmojiList/index.d.ts`（无链接）

### DouyinEmojiListResponseError [#DouyinEmojiListResponseError]

```ts
type DouyinEmojiListResponseError = never
```

源码：`../response-types/dist/generated/douyin/EmojiList/index.d.ts`（无链接）

### DouyinEmojiListResponseSuccess [#DouyinEmojiListResponseSuccess]

```ts
type DouyinEmojiListResponseSuccess = EmojiList_V0
```

源码：`../response-types/dist/generated/douyin/EmojiList/index.d.ts`（无链接）

### DouyinEmojiResourceMetaResponse [#DouyinEmojiResourceMetaResponse]

```ts
type DouyinEmojiResourceMetaResponse = EmojiResourceMetaSuccess | EmojiResourceMetaError
```

源码：`../response-types/dist/generated/douyin/EmojiResourceMeta/index.d.ts`（无链接）

### DouyinEmojiResourceMetaResponseError [#DouyinEmojiResourceMetaResponseError]

```ts
type DouyinEmojiResourceMetaResponseError = never
```

源码：`../response-types/dist/generated/douyin/EmojiResourceMeta/index.d.ts`（无链接）

### DouyinEmojiResourceMetaResponseSuccess [#DouyinEmojiResourceMetaResponseSuccess]

```ts
type DouyinEmojiResourceMetaResponseSuccess = EmojiResourceMeta_V0
```

源码：`../response-types/dist/generated/douyin/EmojiResourceMeta/index.d.ts`（无链接）

### DouyinGuestMusicAwemeListResponse [#DouyinGuestMusicAwemeListResponse]

```ts
type DouyinGuestMusicAwemeListResponse = GuestMusicAwemeListSuccess | GuestMusicAwemeListError
```

源码：`../response-types/dist/generated/douyin/GuestMusicAwemeList/index.d.ts`（无链接）

### DouyinGuestMusicAwemeListResponseError [#DouyinGuestMusicAwemeListResponseError]

```ts
type DouyinGuestMusicAwemeListResponseError = never
```

源码：`../response-types/dist/generated/douyin/GuestMusicAwemeList/index.d.ts`（无链接）

### DouyinGuestMusicAwemeListResponseSuccess [#DouyinGuestMusicAwemeListResponseSuccess]

```ts
type DouyinGuestMusicAwemeListResponseSuccess = GuestMusicAwemeList_V0
```

源码：`../response-types/dist/generated/douyin/GuestMusicAwemeList/index.d.ts`（无链接）

### DouyinGuestMusicInfoResponse [#DouyinGuestMusicInfoResponse]

```ts
type DouyinGuestMusicInfoResponse = GuestMusicInfoSuccess | GuestMusicInfoError
```

源码：`../response-types/dist/generated/douyin/GuestMusicInfo/index.d.ts`（无链接）

### DouyinGuestMusicInfoResponseError [#DouyinGuestMusicInfoResponseError]

```ts
type DouyinGuestMusicInfoResponseError = never
```

源码：`../response-types/dist/generated/douyin/GuestMusicInfo/index.d.ts`（无链接）

### DouyinGuestMusicInfoResponseSuccess [#DouyinGuestMusicInfoResponseSuccess]

```ts
type DouyinGuestMusicInfoResponseSuccess = GuestMusicInfo_V0
```

源码：`../response-types/dist/generated/douyin/GuestMusicInfo/index.d.ts`（无链接）

### DouyinGuestUserInfoResponse [#DouyinGuestUserInfoResponse]

```ts
type DouyinGuestUserInfoResponse = GuestUserInfoSuccess | GuestUserInfoError
```

源码：`../response-types/dist/generated/douyin/GuestUserInfo/index.d.ts`（无链接）

### DouyinGuestUserInfoResponseError [#DouyinGuestUserInfoResponseError]

```ts
type DouyinGuestUserInfoResponseError = never
```

源码：`../response-types/dist/generated/douyin/GuestUserInfo/index.d.ts`（无链接）

### DouyinGuestUserInfoResponseSuccess [#DouyinGuestUserInfoResponseSuccess]

```ts
type DouyinGuestUserInfoResponseSuccess = GuestUserInfo_V0
```

源码：`../response-types/dist/generated/douyin/GuestUserInfo/index.d.ts`（无链接）

### DouyinImageAlbumWorkResponse [#DouyinImageAlbumWorkResponse]

```ts
type DouyinImageAlbumWorkResponse = ImageAlbumWorkSuccess | ImageAlbumWorkError
```

源码：`../response-types/dist/generated/douyin/ImageAlbumWork/index.d.ts`（无链接）

### DouyinImageAlbumWorkResponseError [#DouyinImageAlbumWorkResponseError]

```ts
type DouyinImageAlbumWorkResponseError = ImageAlbumWork_Error_V0
```

源码：`../response-types/dist/generated/douyin/ImageAlbumWork/index.d.ts`（无链接）

### DouyinImageAlbumWorkResponseSuccess [#DouyinImageAlbumWorkResponseSuccess]

```ts
type DouyinImageAlbumWorkResponseSuccess = ImageAlbumWork_V0
```

源码：`../response-types/dist/generated/douyin/ImageAlbumWork/index.d.ts`（无链接）

### DouyinLiveRoomInfoResponse [#DouyinLiveRoomInfoResponse]

```ts
type DouyinLiveRoomInfoResponse = LiveRoomInfoSuccess | LiveRoomInfoError
```

源码：`../response-types/dist/generated/douyin/LiveRoomInfo/index.d.ts`（无链接）

### DouyinLiveRoomInfoResponseError [#DouyinLiveRoomInfoResponseError]

```ts
type DouyinLiveRoomInfoResponseError = never
```

源码：`../response-types/dist/generated/douyin/LiveRoomInfo/index.d.ts`（无链接）

### DouyinLiveRoomInfoResponseSuccess [#DouyinLiveRoomInfoResponseSuccess]

```ts
type DouyinLiveRoomInfoResponseSuccess = LiveRoomInfo_V0
```

源码：`../response-types/dist/generated/douyin/LiveRoomInfo/index.d.ts`（无链接）

### DouyinMixAwemeResponse [#DouyinMixAwemeResponse]

```ts
type DouyinMixAwemeResponse = MixAwemeSuccess | MixAwemeError
```

源码：`../response-types/dist/generated/douyin/MixAweme/index.d.ts`（无链接）

### DouyinMixAwemeResponseError [#DouyinMixAwemeResponseError]

```ts
type DouyinMixAwemeResponseError = never
```

源码：`../response-types/dist/generated/douyin/MixAweme/index.d.ts`（无链接）

### DouyinMixAwemeResponseSuccess [#DouyinMixAwemeResponseSuccess]

```ts
type DouyinMixAwemeResponseSuccess = MixAweme_V0
```

源码：`../response-types/dist/generated/douyin/MixAweme/index.d.ts`（无链接）

### DouyinMusicAwemeListResponse [#DouyinMusicAwemeListResponse]

```ts
type DouyinMusicAwemeListResponse = MusicAwemeListSuccess | MusicAwemeListError
```

源码：`../response-types/dist/generated/douyin/MusicAwemeList/index.d.ts`（无链接）

### DouyinMusicAwemeListResponseError [#DouyinMusicAwemeListResponseError]

```ts
type DouyinMusicAwemeListResponseError = never
```

源码：`../response-types/dist/generated/douyin/MusicAwemeList/index.d.ts`（无链接）

### DouyinMusicAwemeListResponseSuccess [#DouyinMusicAwemeListResponseSuccess]

```ts
type DouyinMusicAwemeListResponseSuccess = MusicAwemeList_V0
```

源码：`../response-types/dist/generated/douyin/MusicAwemeList/index.d.ts`（无链接）

### DouyinMusicInfoResponse [#DouyinMusicInfoResponse]

```ts
type DouyinMusicInfoResponse = MusicInfoSuccess | MusicInfoError
```

源码：`../response-types/dist/generated/douyin/MusicInfo/index.d.ts`（无链接）

### DouyinMusicInfoResponseError [#DouyinMusicInfoResponseError]

```ts
type DouyinMusicInfoResponseError = never
```

源码：`../response-types/dist/generated/douyin/MusicInfo/index.d.ts`（无链接）

### DouyinMusicInfoResponseSuccess [#DouyinMusicInfoResponseSuccess]

```ts
type DouyinMusicInfoResponseSuccess = MusicInfo_V0
```

源码：`../response-types/dist/generated/douyin/MusicInfo/index.d.ts`（无链接）

### DouyinParseWorkResponse [#DouyinParseWorkResponse]

```ts
type DouyinParseWorkResponse = ParseWorkSuccess | ParseWorkError
```

源码：`../response-types/dist/generated/douyin/ParseWork/index.d.ts`（无链接）

### DouyinParseWorkResponseError [#DouyinParseWorkResponseError]

```ts
type DouyinParseWorkResponseError = ParseWork_Error_V0
```

源码：`../response-types/dist/generated/douyin/ParseWork/index.d.ts`（无链接）

### DouyinParseWorkResponseSuccess [#DouyinParseWorkResponseSuccess]

```ts
type DouyinParseWorkResponseSuccess = ParseWork_V0
```

源码：`../response-types/dist/generated/douyin/ParseWork/index.d.ts`（无链接）

### DouyinSearchResponse [#DouyinSearchResponse]

```ts
type DouyinSearchResponse = SearchSuccess | SearchError
```

源码：`../response-types/dist/generated/douyin/Search/index.d.ts`（无链接）

### DouyinSearchResponseError [#DouyinSearchResponseError]

```ts
type DouyinSearchResponseError = never
```

源码：`../response-types/dist/generated/douyin/Search/index.d.ts`（无链接）

### DouyinSearchResponseSuccess [#DouyinSearchResponseSuccess]

```ts
type DouyinSearchResponseSuccess = SearchUnion
```

源码：`../response-types/dist/generated/douyin/Search/index.d.ts`（无链接）

### DouyinShortUrlResponse [#DouyinShortUrlResponse]

```ts
type DouyinShortUrlResponse = ShortUrlSuccess | ShortUrlError
```

源码：`../response-types/dist/generated/douyin/ShortUrl/index.d.ts`（无链接）

### DouyinShortUrlResponseError [#DouyinShortUrlResponseError]

```ts
type DouyinShortUrlResponseError = ShortUrl_Error_V0
```

源码：`../response-types/dist/generated/douyin/ShortUrl/index.d.ts`（无链接）

### DouyinShortUrlResponseSuccess [#DouyinShortUrlResponseSuccess]

```ts
type DouyinShortUrlResponseSuccess = ShortUrl_V0
```

源码：`../response-types/dist/generated/douyin/ShortUrl/index.d.ts`（无链接）

### DouyinSlidesWorkResponse [#DouyinSlidesWorkResponse]

```ts
type DouyinSlidesWorkResponse = SlidesWorkSuccess | SlidesWorkError
```

源码：`../response-types/dist/generated/douyin/SlidesWork/index.d.ts`（无链接）

### DouyinSlidesWorkResponseError [#DouyinSlidesWorkResponseError]

```ts
type DouyinSlidesWorkResponseError = SlidesWork_Error_V0
```

源码：`../response-types/dist/generated/douyin/SlidesWork/index.d.ts`（无链接）

### DouyinSlidesWorkResponseSuccess [#DouyinSlidesWorkResponseSuccess]

```ts
type DouyinSlidesWorkResponseSuccess = SlidesWork_V0 | SlidesWork_V1
```

源码：`../response-types/dist/generated/douyin/SlidesWork/index.d.ts`（无链接）

### DouyinSuggestWordsResponse [#DouyinSuggestWordsResponse]

```ts
type DouyinSuggestWordsResponse = SuggestWordsSuccess | SuggestWordsError
```

源码：`../response-types/dist/generated/douyin/SuggestWords/index.d.ts`（无链接）

### DouyinSuggestWordsResponseError [#DouyinSuggestWordsResponseError]

```ts
type DouyinSuggestWordsResponseError = never
```

源码：`../response-types/dist/generated/douyin/SuggestWords/index.d.ts`（无链接）

### DouyinSuggestWordsResponseSuccess [#DouyinSuggestWordsResponseSuccess]

```ts
type DouyinSuggestWordsResponseSuccess = SuggestWords_V0
```

源码：`../response-types/dist/generated/douyin/SuggestWords/index.d.ts`（无链接）

### DouyinTextWorkResponse [#DouyinTextWorkResponse]

```ts
type DouyinTextWorkResponse = TextWorkSuccess | TextWorkError
```

源码：`../response-types/dist/generated/douyin/TextWork/index.d.ts`（无链接）

### DouyinTextWorkResponseError [#DouyinTextWorkResponseError]

```ts
type DouyinTextWorkResponseError = never
```

源码：`../response-types/dist/generated/douyin/TextWork/index.d.ts`（无链接）

### DouyinTextWorkResponseSuccess [#DouyinTextWorkResponseSuccess]

```ts
type DouyinTextWorkResponseSuccess = TextWork_V0
```

源码：`../response-types/dist/generated/douyin/TextWork/index.d.ts`（无链接）

### DouyinUserFavoriteListResponse [#DouyinUserFavoriteListResponse]

```ts
type DouyinUserFavoriteListResponse = UserFavoriteListSuccess | UserFavoriteListError
```

源码：`../response-types/dist/generated/douyin/UserFavoriteList/index.d.ts`（无链接）

### DouyinUserFavoriteListResponseError [#DouyinUserFavoriteListResponseError]

```ts
type DouyinUserFavoriteListResponseError = never
```

源码：`../response-types/dist/generated/douyin/UserFavoriteList/index.d.ts`（无链接）

### DouyinUserFavoriteListResponseSuccess [#DouyinUserFavoriteListResponseSuccess]

```ts
type DouyinUserFavoriteListResponseSuccess = UserFavoriteList_V0
```

源码：`../response-types/dist/generated/douyin/UserFavoriteList/index.d.ts`（无链接）

### DouyinUserProfileResponse [#DouyinUserProfileResponse]

```ts
type DouyinUserProfileResponse = UserProfileSuccess | UserProfileError
```

源码：`../response-types/dist/generated/douyin/UserProfile/index.d.ts`（无链接）

### DouyinUserProfileResponseError [#DouyinUserProfileResponseError]

```ts
type DouyinUserProfileResponseError = never
```

源码：`../response-types/dist/generated/douyin/UserProfile/index.d.ts`（无链接）

### DouyinUserProfileResponseSuccess [#DouyinUserProfileResponseSuccess]

```ts
type DouyinUserProfileResponseSuccess = UserProfile_V0
```

源码：`../response-types/dist/generated/douyin/UserProfile/index.d.ts`（无链接）

### DouyinUserRecommendListResponse [#DouyinUserRecommendListResponse]

```ts
type DouyinUserRecommendListResponse = UserRecommendListSuccess | UserRecommendListError
```

源码：`../response-types/dist/generated/douyin/UserRecommendList/index.d.ts`（无链接）

### DouyinUserRecommendListResponseError [#DouyinUserRecommendListResponseError]

```ts
type DouyinUserRecommendListResponseError = never
```

源码：`../response-types/dist/generated/douyin/UserRecommendList/index.d.ts`（无链接）

### DouyinUserRecommendListResponseSuccess [#DouyinUserRecommendListResponseSuccess]

```ts
type DouyinUserRecommendListResponseSuccess = UserRecommendList_V0
```

源码：`../response-types/dist/generated/douyin/UserRecommendList/index.d.ts`（无链接）

### DouyinUserVideoListResponse [#DouyinUserVideoListResponse]

```ts
type DouyinUserVideoListResponse = UserVideoListSuccess | UserVideoListError
```

源码：`../response-types/dist/generated/douyin/UserVideoList/index.d.ts`（无链接）

### DouyinUserVideoListResponseError [#DouyinUserVideoListResponseError]

```ts
type DouyinUserVideoListResponseError = never
```

源码：`../response-types/dist/generated/douyin/UserVideoList/index.d.ts`（无链接）

### DouyinUserVideoListResponseSuccess [#DouyinUserVideoListResponseSuccess]

```ts
type DouyinUserVideoListResponseSuccess = UserVideoList_V0
```

源码：`../response-types/dist/generated/douyin/UserVideoList/index.d.ts`（无链接）

### DouyinVideoWorkResponse [#DouyinVideoWorkResponse]

```ts
type DouyinVideoWorkResponse = VideoWorkSuccess | VideoWorkError
```

源码：`../response-types/dist/generated/douyin/VideoWork/index.d.ts`（无链接）

### DouyinVideoWorkResponseError [#DouyinVideoWorkResponseError]

```ts
type DouyinVideoWorkResponseError = VideoWork_Error_V0
```

源码：`../response-types/dist/generated/douyin/VideoWork/index.d.ts`（无链接）

### DouyinVideoWorkResponseSuccess [#DouyinVideoWorkResponseSuccess]

```ts
type DouyinVideoWorkResponseSuccess = VideoWork_V0
```

源码：`../response-types/dist/generated/douyin/VideoWork/index.d.ts`（无链接）

### DyDanmakuList [#DyDanmakuList]

```ts
type DyDanmakuList = DyDanmakuList_V0
```

源码：[`src/types/ReturnDataType/Douyin/DyDanmakuList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/DyDanmakuList/index.ts#L3)

### DyEmojiList [#DyEmojiList]

```ts
type DyEmojiList = DyEmojiList_V0
```

源码：[`src/types/ReturnDataType/Douyin/EmojiList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/EmojiList/index.ts#L3)

### DyEmojiProList [#DyEmojiProList]

```ts
type DyEmojiProList = DyEmojiProList_V0
```

源码：[`src/types/ReturnDataType/Douyin/EmojiProList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/EmojiProList/index.ts#L3)

### DyEmojiResourceMeta [#DyEmojiResourceMeta]

```ts
type DyEmojiResourceMeta = DyEmojiResourceMeta_V0
```

源码：[`src/types/ReturnDataType/Douyin/EmojiResourceMeta/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/EmojiResourceMeta/index.ts#L3)

### DyGuestMusicAwemeList [#DyGuestMusicAwemeList]

```ts
type DyGuestMusicAwemeList = DyGuestMusicAwemeList_V0
```

源码：[`src/types/ReturnDataType/Douyin/GuestMusicAwemeList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/GuestMusicAwemeList/index.ts#L3)

### DyGuestMusicInfo [#DyGuestMusicInfo]

```ts
type DyGuestMusicInfo = DyGuestMusicInfo_V0
```

源码：[`src/types/ReturnDataType/Douyin/GuestMusicInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/GuestMusicInfo/index.ts#L3)

### DyGuestUserInfo [#DyGuestUserInfo]

```ts
type DyGuestUserInfo = DyGuestUserInfo_V0
```

源码：[`src/types/ReturnDataType/Douyin/GuestUserInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/GuestUserInfo/index.ts#L3)

### DyImageAlbumWork [#DyImageAlbumWork]

```ts
type DyImageAlbumWork = DyImageAlbumWork_V0
```

源码：[`src/types/ReturnDataType/Douyin/ImageAlbumWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/ImageAlbumWork/index.ts#L3)

### DyLoginQrcode [#DyLoginQrcode]

```ts
type DyLoginQrcode = DyLoginQrcode_V0
```

源码：[`src/types/ReturnDataType/Douyin/LoginQrcode/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/LoginQrcode/index.ts#L3)

### DyMusicWork [#DyMusicWork]

```ts
type DyMusicWork = DyMusicWork_V0
```

源码：[`src/types/ReturnDataType/Douyin/MusicWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/MusicWork/index.ts#L3)

### DyPassportPollResult [#DyPassportPollResult]

一次二维码轮询的归一化结果

```ts
type DyPassportPollResult = { interval: number; status: "new" } | { interval: number; status: "scanned" } | { interval: number; redirectUrl: string; status: "confirmed" } | { interval: number; status: "expired" } | { interval: number; status: "verify"; verify: DyPassportVerifyContext } | { interval: number; message: string; status: "risk" } | { interval: number; message: string; status: "busy" } | { interval: number; message: string; status: "unknown" }
```

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L47)

### DyPassportQrcodeStatus [#DyPassportQrcodeStatus]

二维码状态

```ts
type DyPassportQrcodeStatus = DyPassportPollResult & { cookie: string; logged_in: boolean }
```

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L84)

### DyPassportSendCode [#DyPassportSendCode]

发送短信验证码的结果

```ts
type DyPassportSendCode = DyPassportSendCodeResult & { biz_trace_id: string; cookie: string; verify_way: string }
```

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L106)

### DyPassportValidateCode [#DyPassportValidateCode]

提交短信验证码的结果

```ts
type DyPassportValidateCode = DyPassportValidateCodeResult & { cookie: string }
```

源码：[`src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/PassportLogin/PassportLogin.ts#L128)

### DySearchInfo [#DySearchInfo]

```ts
type DySearchInfo = SearchInfoGeneralData | SearchInfoUser | SearchInfoVideo
```

源码：[`src/types/ReturnDataType/Douyin/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/index.ts#L26)

### DySlidesWork [#DySlidesWork]

```ts
type DySlidesWork = DySlidesWork_V0
```

源码：[`src/types/ReturnDataType/Douyin/SlidesWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/SlidesWork/index.ts#L3)

### DySuggestWords [#DySuggestWords]

```ts
type DySuggestWords = DySuggestWords_V0
```

源码：[`src/types/ReturnDataType/Douyin/SuggestWords/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/SuggestWords/index.ts#L3)

### DyUserInfo [#DyUserInfo]

```ts
type DyUserInfo = DyUserInfo_V0
```

源码：[`src/types/ReturnDataType/Douyin/UserInfo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/UserInfo/index.ts#L3)

### DyUserLiveVideos [#DyUserLiveVideos]

```ts
type DyUserLiveVideos = DyUserLiveVideos_V0
```

源码：[`src/types/ReturnDataType/Douyin/UserLiveVideos/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/UserLiveVideos/index.ts#L3)

### DyUserPostVideos [#DyUserPostVideos]

```ts
type DyUserPostVideos = DyUserPostVideos_V0
```

源码：[`src/types/ReturnDataType/Douyin/UserPostVideos/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/UserPostVideos/index.ts#L3)

### DyVideoWork [#DyVideoWork]

```ts
type DyVideoWork = DyVideoWWork_V0
```

源码：[`src/types/ReturnDataType/Douyin/VideoWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/VideoWork/index.ts#L3)

### DyWorkComments [#DyWorkComments]

```ts
type DyWorkComments = DyWorkComments_V0
```

源码：[`src/types/ReturnDataType/Douyin/WorkComments/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/WorkComments/index.ts#L3)

### SearchInfoGeneralData [#SearchInfoGeneralData]

```ts
type SearchInfoGeneralData = SearchInfoGeneralData_V0
```

源码：[`src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoGeneral/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoGeneral/index.ts#L3)

### SearchInfoUser [#SearchInfoUser]

```ts
type SearchInfoUser = SearchInfoUser_V0
```

源码：[`src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoUser/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoUser/index.ts#L3)

### SearchInfoVideo [#SearchInfoVideo]

```ts
type SearchInfoVideo = SearchInfoVideo_V0
```

源码：[`src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoVideo/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Douyin/SearchInfo/SearchInfoVideo/index.ts#L3)


# 快手 / 小红书 / 通用响应类型 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/types-rest)

> 88 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 88 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### APIErrorType [#APIErrorType]

API请求错误类型
该类型是方法 `getXXXData` 封装后请求遇到错误时的返回类型

```ts
type APIErrorType = { amagiError: ErrorDetail; amagiMessage: string; code: number | string; data: any }
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L75)

### BilibiliDataOptions [#BilibiliDataOptions]

```ts
type BilibiliDataOptions<T extends keyof BilibiliDataOptionsMap> = OmitMethodType<BilibiliDataOptionsMap[T]["opt"]>
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L68)

### BilibiliDataOptionsMap [#BilibiliDataOptionsMap]

```ts
type BilibiliDataOptionsMap = { [K in BilibiliMethodType]: { data: BilibiliReturnTypeMap[K]; opt: BilibiliMethodOptMap[K] } }
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L29)

### BilibiliMethodOptMap [#BilibiliMethodOptMap]

B站方法类型到参数的映射

用于根据 methodType 字符串获取对应的参数类型

```ts
type BilibiliMethodOptMap = { articleCards: BilibiliMethodOptionsMap["ArticleCardParams"]; articleContent: BilibiliMethodOptionsMap["ArticleParams"]; articleInfo: BilibiliMethodOptionsMap["ArticleInfoParams"]; articleListInfo: BilibiliMethodOptionsMap["ColumnInfoParams"]; avToBv: BilibiliMethodOptionsMap["Av2BvParams"]; bangumiInfo: BilibiliMethodOptionsMap["BangumiInfoParams"]; …其余 21 个成员 }
```

源码：[`src/types/BilibiliAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/BilibiliAPIParams.ts#L307)

### DouyinDataOptions [#DouyinDataOptions]

```ts
type DouyinDataOptions<T extends DouyinMethodType> = OmitMethodType<zod.infer<typeof DouyinValidationSchemas[T]>>
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L67)

### DouyinDataOptionsMap [#DouyinDataOptionsMap]

```ts
type DouyinDataOptionsMap = { [K in DouyinMethodType]: { data: DouyinReturnTypeMap[K]; opt: DouyinMethodOptMap[K] } }
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L22)

### DouyinMethodOptMap [#DouyinMethodOptMap]

抖音方法类型到参数的映射

用于根据 methodType 字符串获取对应的参数类型

```ts
type DouyinMethodOptMap = { commentReplies: DouyinMethodOptionsMap["CommentReplyParams"]; comments: DouyinMethodOptionsMap["CommentParams"]; danmakuList: DouyinMethodOptionsMap["DanmakuParams"]; dynamicEmojiList: DouyinMethodOptionsMap["EmojiProParams"]; emojiList: DouyinMethodOptionsMap["EmojiListParams"]; emojiResourceMeta: DouyinMethodOptionsMap["EmojiResourceParams"]; …其余 17 个成员 }
```

源码：[`src/types/DouyinAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/DouyinAPIParams.ts#L225)

### HomeFeed [#HomeFeed]

```ts
type HomeFeed = HomeFeed_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/HomeFeed/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/HomeFeed/index.ts#L3)

### KsBannedStatus [#KsBannedStatus]

```ts
type KsBannedStatus = { banned: boolean; defriend: boolean; isolate: boolean; socialBanned: boolean }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L30)

### KsDanmaku [#KsDanmaku]

```ts
type KsDanmaku = KsDanmaku_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/Danmaku/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/Danmaku/index.ts#L3)

### KsEmojiList [#KsEmojiList]

```ts
type KsEmojiList = KsEmojiList_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/EmojiList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/EmojiList/index.ts#L3)

### KsLiveRoomInfo [#KsLiveRoomInfo]

```ts
type KsLiveRoomInfo = KsLiveRoomInfo_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/LiveRoomDetail/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/LiveRoomDetail/index.ts#L3)

### KsOneWork [#KsOneWork]

```ts
type KsOneWork = KsOneWork_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/OneWork/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/OneWork/index.ts#L3)

### KsUserHomeWork [#KsUserHomeWork]

```ts
type KsUserHomeWork = { author: Record<string, any>; counts: Record<string, any>; expTag: string; height: number; id: string; imgSizes: any[]; …其余 9 个成员 }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserHomeDetail/UserHomeDetail_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserHomeDetail/UserHomeDetail_V0.ts#L48)

### KsUserProfile [#KsUserProfile]

```ts
type KsUserProfile = KsUserProfile_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/UserProfile/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserProfile/index.ts#L5)

### KsUserProfileCounts [#KsUserProfileCounts]

```ts
type KsUserProfileCounts = { fan: string; follow: string; open: number; photo: number; playback: number; review: number }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L79)

### KsUserProfileGameInfo [#KsUserProfileGameInfo]

```ts
type KsUserProfileGameInfo = { category: string; coverUrl: string; gameId: number; name: string; type: number }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L70)

### KsUserProfileLiveInfo [#KsUserProfileLiveInfo]

```ts
type KsUserProfileLiveInfo = { author: KsUserProfileUserInfo; caption: string; expTag: string; followed: boolean; gameInfo: KsUserProfileGameInfo; hasBet: boolean; …其余 13 个成员 }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L47)

### KsUserProfileSensitiveInfo [#KsUserProfileSensitiveInfo]

```ts
type KsUserProfileSensitiveInfo = { cityName: string; constellation: string; counts: KsUserProfileCounts; kwaiId: string; originUserId: number }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L38)

### KsUserProfileUserInfo [#KsUserProfileUserInfo]

```ts
type KsUserProfileUserInfo = { avatar: string; bannedStatus: KsBannedStatus; cityName: string; constellation: string; counts: Record<string, any>; description: string; …其余 10 个成员 }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L1)

### KsUserWorkList [#KsUserWorkList]

```ts
type KsUserWorkList = KsUserWorkList_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/UserWorkList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserWorkList/index.ts#L5)

### KsVerifiedStatus [#KsVerifiedStatus]

```ts
type KsVerifiedStatus = { description: string; iconUrl: string; new: boolean; type: number; verified: boolean }
```

源码：[`src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/UserCommon/UserCommon_V0.ts#L21)

### KsWorkComments [#KsWorkComments]

```ts
type KsWorkComments = KsWorkComments_V0
```

源码：[`src/types/ReturnDataType/Kuaishou/WorkComments/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Kuaishou/WorkComments/index.ts#L3)

### KuaishouCommentsResponse [#KuaishouCommentsResponse]

```ts
type KuaishouCommentsResponse = CommentsSuccess | CommentsError
```

源码：`../response-types/dist/generated/kuaishou/Comments/index.d.ts`（无链接）

### KuaishouCommentsResponseError [#KuaishouCommentsResponseError]

```ts
type KuaishouCommentsResponseError = never
```

源码：`../response-types/dist/generated/kuaishou/Comments/index.d.ts`（无链接）

### KuaishouCommentsResponseSuccess [#KuaishouCommentsResponseSuccess]

```ts
type KuaishouCommentsResponseSuccess = Comments_V0
```

源码：`../response-types/dist/generated/kuaishou/Comments/index.d.ts`（无链接）

### KuaishouDanmakuListResponse [#KuaishouDanmakuListResponse]

```ts
type KuaishouDanmakuListResponse = DanmakuListSuccess | DanmakuListError
```

源码：`../response-types/dist/generated/kuaishou/DanmakuList/index.d.ts`（无链接）

### KuaishouDanmakuListResponseError [#KuaishouDanmakuListResponseError]

```ts
type KuaishouDanmakuListResponseError = never
```

源码：`../response-types/dist/generated/kuaishou/DanmakuList/index.d.ts`（无链接）

### KuaishouDanmakuListResponseSuccess [#KuaishouDanmakuListResponseSuccess]

```ts
type KuaishouDanmakuListResponseSuccess = DanmakuList_V0
```

源码：`../response-types/dist/generated/kuaishou/DanmakuList/index.d.ts`（无链接）

### KuaishouDataOptions [#KuaishouDataOptions]

```ts
type KuaishouDataOptions<T extends keyof KuaishouDataOptionsMap> = OmitMethodType<KuaishouDataOptionsMap[T]["opt"]>
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L69)

### KuaishouDataOptionsMap [#KuaishouDataOptionsMap]

```ts
type KuaishouDataOptionsMap = { [K in KuaishouMethodType]: { data: KuaishouReturnTypeMap[K]; opt: KuaishouMethodOptMap[K] } }
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L36)

### KuaishouEmojiListResponse [#KuaishouEmojiListResponse]

```ts
type KuaishouEmojiListResponse = EmojiListSuccess | EmojiListError
```

源码：`../response-types/dist/generated/kuaishou/EmojiList/index.d.ts`（无链接）

### KuaishouEmojiListResponseError [#KuaishouEmojiListResponseError]

```ts
type KuaishouEmojiListResponseError = never
```

源码：`../response-types/dist/generated/kuaishou/EmojiList/index.d.ts`（无链接）

### KuaishouEmojiListResponseSuccess [#KuaishouEmojiListResponseSuccess]

```ts
type KuaishouEmojiListResponseSuccess = EmojiList_V0
```

源码：`../response-types/dist/generated/kuaishou/EmojiList/index.d.ts`（无链接）

### KuaishouMethodOptMap [#KuaishouMethodOptMap]

快手方法类型到参数的映射

```ts
type KuaishouMethodOptMap = { comments: KuaishouMethodOptionsMap["CommentParams"]; emojiList: KuaishouMethodOptionsMap["EmojiListParams"]; liveRoomInfo: KuaishouMethodOptionsMap["LiveRoomInfoParams"]; userProfile: KuaishouMethodOptionsMap["UserProfileParams"]; userWorkList: KuaishouMethodOptionsMap["UserWorkListParams"]; videoWork: KuaishouMethodOptionsMap["VideoInfoParams"] }
```

源码：[`src/types/KuaishouAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/KuaishouAPIParams.ts#L42)

### KuaishouVideoWorkResponse [#KuaishouVideoWorkResponse]

```ts
type KuaishouVideoWorkResponse = VideoWorkSuccess | VideoWorkError
```

源码：`../response-types/dist/generated/kuaishou/VideoWork/index.d.ts`（无链接）

### KuaishouVideoWorkResponseError [#KuaishouVideoWorkResponseError]

```ts
type KuaishouVideoWorkResponseError = never
```

源码：`../response-types/dist/generated/kuaishou/VideoWork/index.d.ts`（无链接）

### KuaishouVideoWorkResponseSuccess [#KuaishouVideoWorkResponseSuccess]

```ts
type KuaishouVideoWorkResponseSuccess = VideoWork_V0
```

源码：`../response-types/dist/generated/kuaishou/VideoWork/index.d.ts`（无链接）

### NetworksConfigType [#NetworksConfigType]

```ts
type NetworksConfigType = { body: object | string; headers: any; method: string; methodType: string; redirect: RequestRedirect; responseType: string; …其余 2 个成员 }
```

源码：[`src/types/NetworksConfigType.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/NetworksConfigType.ts#L1)

### NoteComments [#NoteComments]

```ts
type NoteComments = NoteComments_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/NoteComments/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/NoteComments/index.ts#L3)

### OmitMethodType [#OmitMethodType]

移除methodType字段的工具类型

```ts
type OmitMethodType<T> = Omit<T, "methodType">
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L20)

### OneNote [#OneNote]

```ts
type OneNote = OneNote_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/OneNote/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/OneNote/index.ts#L3)

### SearchNotes [#SearchNotes]

```ts
type SearchNotes = SearchNotes_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/SearchNotes/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/SearchNotes/index.ts#L3)

### XiaohongshuDataOptions [#XiaohongshuDataOptions]

```ts
type XiaohongshuDataOptions<T extends keyof XiaohongshuDataOptionsMap> = OmitMethodType<XiaohongshuDataOptionsMap[T]["opt"]>
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L66)

### XiaohongshuDataOptionsMap [#XiaohongshuDataOptionsMap]

```ts
type XiaohongshuDataOptionsMap = { [K in XiaohongshuMethodType]: { data: XiaohongshuReturnTypeMap[K]; opt: XiaohongshuMethodOptMap[K] } }
```

源码：[`src/types/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/index.ts#L43)

### XiaohongshuEmojiList [#XiaohongshuEmojiList]

```ts
type XiaohongshuEmojiList = XiaohongshuEmojiList_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/XiaohongshuEmojiList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/XiaohongshuEmojiList/index.ts#L3)

### XiaohongshuEmojiListResponse [#XiaohongshuEmojiListResponse]

```ts
type XiaohongshuEmojiListResponse = EmojiListSuccess | EmojiListError
```

源码：`../response-types/dist/generated/xiaohongshu/EmojiList/index.d.ts`（无链接）

### XiaohongshuEmojiListResponseError [#XiaohongshuEmojiListResponseError]

```ts
type XiaohongshuEmojiListResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/EmojiList/index.d.ts`（无链接）

### XiaohongshuEmojiListResponseSuccess [#XiaohongshuEmojiListResponseSuccess]

```ts
type XiaohongshuEmojiListResponseSuccess = EmojiList_V0
```

源码：`../response-types/dist/generated/xiaohongshu/EmojiList/index.d.ts`（无链接）

### XiaohongshuHomeFeedResponse [#XiaohongshuHomeFeedResponse]

```ts
type XiaohongshuHomeFeedResponse = HomeFeedSuccess | HomeFeedError
```

源码：`../response-types/dist/generated/xiaohongshu/HomeFeed/index.d.ts`（无链接）

### XiaohongshuHomeFeedResponseError [#XiaohongshuHomeFeedResponseError]

```ts
type XiaohongshuHomeFeedResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/HomeFeed/index.d.ts`（无链接）

### XiaohongshuHomeFeedResponseSuccess [#XiaohongshuHomeFeedResponseSuccess]

```ts
type XiaohongshuHomeFeedResponseSuccess = HomeFeed_V0
```

源码：`../response-types/dist/generated/xiaohongshu/HomeFeed/index.d.ts`（无链接）

### XiaohongshuLiveRoomResponse [#XiaohongshuLiveRoomResponse]

```ts
type XiaohongshuLiveRoomResponse = LiveRoomSuccess | LiveRoomError
```

源码：`../response-types/dist/generated/xiaohongshu/LiveRoom/index.d.ts`（无链接）

### XiaohongshuLiveRoomResponseError [#XiaohongshuLiveRoomResponseError]

```ts
type XiaohongshuLiveRoomResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/LiveRoom/index.d.ts`（无链接）

### XiaohongshuLiveRoomResponseSuccess [#XiaohongshuLiveRoomResponseSuccess]

```ts
type XiaohongshuLiveRoomResponseSuccess = LiveRoom_V0
```

源码：`../response-types/dist/generated/xiaohongshu/LiveRoom/index.d.ts`（无链接）

### XiaohongshuLiveSquareResponse [#XiaohongshuLiveSquareResponse]

```ts
type XiaohongshuLiveSquareResponse = LiveSquareSuccess | LiveSquareError
```

源码：`../response-types/dist/generated/xiaohongshu/LiveSquare/index.d.ts`（无链接）

### XiaohongshuLiveSquareResponseError [#XiaohongshuLiveSquareResponseError]

```ts
type XiaohongshuLiveSquareResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/LiveSquare/index.d.ts`（无链接）

### XiaohongshuLiveSquareResponseSuccess [#XiaohongshuLiveSquareResponseSuccess]

```ts
type XiaohongshuLiveSquareResponseSuccess = LiveSquare_V0
```

源码：`../response-types/dist/generated/xiaohongshu/LiveSquare/index.d.ts`（无链接）

### XiaohongshuLiveStatusResponse [#XiaohongshuLiveStatusResponse]

```ts
type XiaohongshuLiveStatusResponse = LiveStatusSuccess | LiveStatusError
```

源码：`../response-types/dist/generated/xiaohongshu/LiveStatus/index.d.ts`（无链接）

### XiaohongshuLiveStatusResponseError [#XiaohongshuLiveStatusResponseError]

```ts
type XiaohongshuLiveStatusResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/LiveStatus/index.d.ts`（无链接）

### XiaohongshuLiveStatusResponseSuccess [#XiaohongshuLiveStatusResponseSuccess]

```ts
type XiaohongshuLiveStatusResponseSuccess = LiveStatus_V0
```

源码：`../response-types/dist/generated/xiaohongshu/LiveStatus/index.d.ts`（无链接）

### XiaohongshuMethodOptMap [#XiaohongshuMethodOptMap]

小红书方法类型到参数的映射

```ts
type XiaohongshuMethodOptMap = { emojiList: XiaohongshuMethodOptionsMap["EmojiListParams"]; homeFeed: XiaohongshuMethodOptionsMap["HomeFeedParams"]; noteComments: XiaohongshuMethodOptionsMap["CommentParams"]; noteDetail: XiaohongshuMethodOptionsMap["NoteParams"]; searchNotes: XiaohongshuMethodOptionsMap["SearchNoteParams"]; userNoteList: XiaohongshuMethodOptionsMap["UserNoteParams"]; …其余 1 个成员 }
```

源码：[`src/types/XiaohongshuAPIParams.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/XiaohongshuAPIParams.ts#L76)

### XiaohongshuNoteCommentsResponse [#XiaohongshuNoteCommentsResponse]

```ts
type XiaohongshuNoteCommentsResponse = NoteCommentsSuccess | NoteCommentsError
```

源码：`../response-types/dist/generated/xiaohongshu/NoteComments/index.d.ts`（无链接）

### XiaohongshuNoteCommentsResponseError [#XiaohongshuNoteCommentsResponseError]

```ts
type XiaohongshuNoteCommentsResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/NoteComments/index.d.ts`（无链接）

### XiaohongshuNoteCommentsResponseSuccess [#XiaohongshuNoteCommentsResponseSuccess]

```ts
type XiaohongshuNoteCommentsResponseSuccess = NoteComments_V0
```

源码：`../response-types/dist/generated/xiaohongshu/NoteComments/index.d.ts`（无链接）

### XiaohongshuNoteDetailResponse [#XiaohongshuNoteDetailResponse]

```ts
type XiaohongshuNoteDetailResponse = NoteDetailSuccess | NoteDetailError
```

源码：`../response-types/dist/generated/xiaohongshu/NoteDetail/index.d.ts`（无链接）

### XiaohongshuNoteDetailResponseError [#XiaohongshuNoteDetailResponseError]

```ts
type XiaohongshuNoteDetailResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/NoteDetail/index.d.ts`（无链接）

### XiaohongshuNoteDetailResponseSuccess [#XiaohongshuNoteDetailResponseSuccess]

```ts
type XiaohongshuNoteDetailResponseSuccess = NoteDetail_V0
```

源码：`../response-types/dist/generated/xiaohongshu/NoteDetail/index.d.ts`（无链接）

### XiaohongshuSearchHotListResponse [#XiaohongshuSearchHotListResponse]

```ts
type XiaohongshuSearchHotListResponse = SearchHotListSuccess | SearchHotListError
```

源码：`../response-types/dist/generated/xiaohongshu/SearchHotList/index.d.ts`（无链接）

### XiaohongshuSearchHotListResponseError [#XiaohongshuSearchHotListResponseError]

```ts
type XiaohongshuSearchHotListResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/SearchHotList/index.d.ts`（无链接）

### XiaohongshuSearchHotListResponseSuccess [#XiaohongshuSearchHotListResponseSuccess]

```ts
type XiaohongshuSearchHotListResponseSuccess = SearchHotList_V0
```

源码：`../response-types/dist/generated/xiaohongshu/SearchHotList/index.d.ts`（无链接）

### XiaohongshuSearchNotesResponse [#XiaohongshuSearchNotesResponse]

```ts
type XiaohongshuSearchNotesResponse = SearchNotesSuccess | SearchNotesError
```

源码：`../response-types/dist/generated/xiaohongshu/SearchNotes/index.d.ts`（无链接）

### XiaohongshuSearchNotesResponseError [#XiaohongshuSearchNotesResponseError]

```ts
type XiaohongshuSearchNotesResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/SearchNotes/index.d.ts`（无链接）

### XiaohongshuSearchNotesResponseSuccess [#XiaohongshuSearchNotesResponseSuccess]

```ts
type XiaohongshuSearchNotesResponseSuccess = SearchNotes_V0
```

源码：`../response-types/dist/generated/xiaohongshu/SearchNotes/index.d.ts`（无链接）

### XiaohongshuSearchUserResponse [#XiaohongshuSearchUserResponse]

```ts
type XiaohongshuSearchUserResponse = SearchUserSuccess | SearchUserError
```

源码：`../response-types/dist/generated/xiaohongshu/SearchUser/index.d.ts`（无链接）

### XiaohongshuSearchUserResponseError [#XiaohongshuSearchUserResponseError]

```ts
type XiaohongshuSearchUserResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/SearchUser/index.d.ts`（无链接）

### XiaohongshuSearchUserResponseSuccess [#XiaohongshuSearchUserResponseSuccess]

```ts
type XiaohongshuSearchUserResponseSuccess = SearchUser_V0
```

源码：`../response-types/dist/generated/xiaohongshu/SearchUser/index.d.ts`（无链接）

### XiaohongshuSubCommentsResponse [#XiaohongshuSubCommentsResponse]

```ts
type XiaohongshuSubCommentsResponse = SubCommentsSuccess | SubCommentsError
```

源码：`../response-types/dist/generated/xiaohongshu/SubComments/index.d.ts`（无链接）

### XiaohongshuSubCommentsResponseError [#XiaohongshuSubCommentsResponseError]

```ts
type XiaohongshuSubCommentsResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/SubComments/index.d.ts`（无链接）

### XiaohongshuSubCommentsResponseSuccess [#XiaohongshuSubCommentsResponseSuccess]

```ts
type XiaohongshuSubCommentsResponseSuccess = SubComments_V0
```

源码：`../response-types/dist/generated/xiaohongshu/SubComments/index.d.ts`（无链接）

### XiaohongshuUserNoteList [#XiaohongshuUserNoteList]

```ts
type XiaohongshuUserNoteList = XiaohongshuUserNoteList_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/XiaohongshuUserNoteList/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/XiaohongshuUserNoteList/index.ts#L6)

### XiaohongshuUserNoteListResponse [#XiaohongshuUserNoteListResponse]

```ts
type XiaohongshuUserNoteListResponse = UserNoteListSuccess | UserNoteListError
```

源码：`../response-types/dist/generated/xiaohongshu/UserNoteList/index.d.ts`（无链接）

### XiaohongshuUserNoteListResponseError [#XiaohongshuUserNoteListResponseError]

```ts
type XiaohongshuUserNoteListResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/UserNoteList/index.d.ts`（无链接）

### XiaohongshuUserNoteListResponseSuccess [#XiaohongshuUserNoteListResponseSuccess]

```ts
type XiaohongshuUserNoteListResponseSuccess = UserNoteList_V0
```

源码：`../response-types/dist/generated/xiaohongshu/UserNoteList/index.d.ts`（无链接）

### XiaohongshuUserProfile [#XiaohongshuUserProfile]

```ts
type XiaohongshuUserProfile = XiaohongshuUserProfile_V0
```

源码：[`src/types/ReturnDataType/Xiaohongshu/XiaohongshuUserProfile/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/types/ReturnDataType/Xiaohongshu/XiaohongshuUserProfile/index.ts#L3)

### XiaohongshuUserProfileResponse [#XiaohongshuUserProfileResponse]

```ts
type XiaohongshuUserProfileResponse = UserProfileSuccess | UserProfileError
```

源码：`../response-types/dist/generated/xiaohongshu/UserProfile/index.d.ts`（无链接）

### XiaohongshuUserProfileResponseError [#XiaohongshuUserProfileResponseError]

```ts
type XiaohongshuUserProfileResponseError = never
```

源码：`../response-types/dist/generated/xiaohongshu/UserProfile/index.d.ts`（无链接）

### XiaohongshuUserProfileResponseSuccess [#XiaohongshuUserProfileResponseSuccess]

```ts
type XiaohongshuUserProfileResponseSuccess = UserProfile_V0
```

源码：`../response-types/dist/generated/xiaohongshu/UserProfile/index.d.ts`（无链接）


# 核心类型 (https://ikenxuan.github.io/amagi/docs/v7/usage/api/types/types)

> 24 个符号，由 scripts/api-extractor.ts 从 packages/core/src/index.ts 抽取



{/* 本页由 scripts/generate-api-types.ts 在构建期生成，不要手改。 */}

<Callout type="info">
  本页 24 个符号由 `packages/core/src/index.ts` 的导出面在构建期生成，
  签名、参数表与源码位置都取自 TypeScript 编译器对源码的解析。全部导出的索引见
  [类型索引](/docs/v7/usage/api/types)，同一批能力的 SDK 与 HTTP 形态见
  [SDK 方法页](/docs/v7/usage/api/sdk/douyin) 与 [HTTP 端点参考](/docs/v7/usage/api/http)。
</Callout>

### AmagiBusEventName [#AmagiBusEventName]

事件名

```ts
type AmagiBusEventName = keyof AmagiBusEventMap
```

源码：[`src/runtime/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/runtime/events.ts#L228)

### AmagiErrorCode [#AmagiErrorCode]

稳定的字符串错误码，可用于 `switch` 与埋点。

用字符串字面量联合而不是 `enum`：`enum` 的 `Object.values()` 会带出反向映射键，
且拿平台返回的数字码去比时容易出现 `'-101'` 与 `-101` 对不上的静默错配。

```ts
type AmagiErrorCode = "PARAM_INVALID" | "PARAM_MISSING" | "COOKIE_MISSING" | "COOKIE_EXPIRED" | "LOGIN_REQUIRED" | "RATE_LIMITED" | "RISK_CONTROL" | "CAPTCHA_REQUIRED" | "SIGNATURE_REFUSED" | "NOT_FOUND" | "DELETED" | "PRIVATE" | "GEO_RESTRICTED" | "PAID_CONTENT" | "PLATFORM_ERROR" | "PLATFORM_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "EMPTY_RESPONSE" | "DECODE_FAILED" | "ANTIBOT_PAGE" | "INTERNAL_ERROR" | "UNKNOWN_ERROR"
```

源码：[`src/contracts/error.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/error.ts#L47)

### AmagiEventType [#AmagiEventType]

Amagi 支持的事件类型

```ts
type AmagiEventType = "log:info" | "log:warn" | "log:error" | "log:debug" | "log:mark" | "http:request" | "http:response" | "http:error" | "network:retry" | "network:error" | "api:success" | "api:error"
```

源码：[`src/model/events.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/model/events.ts#L21)

### AmagiRequestMethod [#AmagiRequestMethod]

单次调用（信封轨）

```ts
type AmagiRequestMethod = __type<T>(url: string, config?: AmagiRequestConfig): Promise<AmagiResult<T>>
```

源码：[`src/client/request/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/client/request/index.ts#L31)

### AmagiResult [#AmagiResult]

所有对外 API 的唯一返回类型

```ts
type AmagiResult<T> = AmagiSuccess<T> | AmagiFailure
```

源码：[`src/contracts/result.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/result.ts#L82)

### BilibiliMethodType [#BilibiliMethodType]

B站方法类型

```ts
type BilibiliMethodType = keyof typeof BilibiliValidationSchemas
```

源码：[`src/validation/bilibili.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/bilibili.ts#L267)

### ChallengeAnswer [#ChallengeAnswer]

按 challenge 的 kind 决定应答的形状。

条件类型是「回调返回错字段编译期报错」的落点：
`c.kind === 'sms'` 收窄后 `C` 推断为 `SmsChallenge`，
`ChallengeAnswer<SmsChallenge>` 求值为 `{ code: string }`。

```ts
type ChallengeAnswer<C extends LoginChallenge> = C extends SmsChallenge ? { code: string } : C extends CaptchaChallenge ? { randstr: string; ticket: string } : never
```

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L87)

### CommentType [#CommentType]

B站评论区类型代码（`comments` / `commentReplies` 的 `type` 参数）。

完整对照表（部分 oid 含义官方未明确，转写自 bilibili-API-collect）：

| 代码 | 评论区类型        | oid 的意义 |
| -- | ------------ | ------- |
| 1  | 视频稿件         | 稿件 avid |
| 2  | 话题           | 话题 id   |
| 4  | 活动           | 活动 id   |
| 5  | 小视频          | 小视频 id  |
| 6  | 小黑屋封禁信息      | 封禁公示 id |
| 7  | 公告信息         | 公告 id   |
| 8  | 直播活动         | 直播间 id  |
| 9  | 活动稿件         | (?)     |
| 10 | 直播公告         | (?)     |
| 11 | 相簿（图片动态）     | 相簿 id   |
| 12 | 专栏           | 专栏 cvid |
| 13 | 票务           | (?)     |
| 14 | 音频           | 音频 auid |
| 15 | 风纪委员会        | 众裁项目 id |
| 16 | 点评           | (?)     |
| 17 | 动态（纯文字动态&分享） | 动态 id   |
| 18 | 播单           | (?)     |
| 19 | 音乐播单         | (?)     |
| 20 | 漫画           | (?)     |
| 21 | 漫画           | (?)     |
| 22 | 漫画           | 漫画 mcid |
| 33 | 课程           | 课程 epid |

```ts
type CommentType = zod.infer<typeof commentTypeUnion>
```

**另见**：[https://github.com/SocialSisterYi/bilibili-API-collect/blob/master/docs/comment/readme.md#%E8%AF%84%E8%AE%BA%E5%8C%BA%E7%B1%BB%E5%9E%8B%E4%BB%A3%E7%A0%81](https://github.com/SocialSisterYi/bilibili-API-collect/blob/master/docs/comment/readme.md#%E8%AF%84%E8%AE%BA%E5%8C%BA%E7%B1%BB%E5%9E%8B%E4%BB%A3%E7%A0%81)

源码：[`src/platforms/bilibili/api.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/bilibili/api.ts#L126)

### CookieConfig [#CookieConfig]

Cookie配置选项接口

```ts
type CookieConfig = { bilibili: string; douyin: string; kuaishou: string; xiaohongshu: string }
```

源码：[`src/server/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/server/index.ts#L26)

### DouyinCredentialOrigin [#DouyinCredentialOrigin]

这份凭据是怎么来的。

`guest-minted` 与 `guest-device` 的分界是**有没有拿到访客 id**，不是「握手有没有出货」：
服务端把「挑战过没过」与「发不发访客 id」分开决定，只发了 `ttwid` 的那种结局也算
一次成功的握手，但**不是**一份游客凭据 —— 它没有访客 id，受 secsdk 保护的端点照样
回 `403 Uifid Not Found`。所以两种结局各有一个 origin，谁也不冒充谁。

```ts
type DouyinCredentialOrigin = "as-is" | "normalized" | "uifid-temp" | "guest-minted" | "guest-device" | "unresolved"
```

源码：[`src/platforms/douyin/credential.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/credential.ts#L15)

### DouyinLoginState [#DouyinLoginState]

```ts
type DouyinLoginState = "login" | "guest" | "expired" | "unusable" | "unknown"
```

源码：[`src/platforms/douyin/loginState.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/loginState.ts#L6)

### DouyinMethodType [#DouyinMethodType]

抖音方法类型

```ts
type DouyinMethodType = keyof typeof DouyinValidationSchemas
```

源码：[`src/validation/douyin.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/douyin.ts#L254)

### DouyinUifidSource [#DouyinUifidSource]

```ts
type DouyinUifidSource = "UIFID" | "UIFID_TEMP" | "missing"
```

源码：[`src/platforms/douyin/cookie.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/douyin/cookie.ts#L3)

### ErrorKind [#ErrorKind]

跨平台统一的错误大类，也是调用方唯一需要 `switch` 的判别键。

粗粒度归因用 `kind`，细粒度归因用 [`AmagiErrorCode`](/docs/v7/usage/api/types/types#AmagiErrorCode)。

```ts
type ErrorKind = "validation" | "auth" | "rate_limit" | "risk" | "not_found" | "forbidden" | "unavailable" | "network" | "timeout" | "parse" | "internal" | "unknown"
```

源码：[`src/contracts/error.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/error.ts#L15)

### KuaishouGraphqlRequest [#KuaishouGraphqlRequest]

快手 GraphQL 请求描述对象。

该结构只负责描述请求，不负责执行网络请求。

```ts
type KuaishouGraphqlRequest = KuaishouBaseApiRequest & { body: { operationName: string; query: string; variables: Record<string, unknown> } }
```

源码：[`src/platforms/legacy/kuaishou/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/kuaishou/API.ts#L39)

### KuaishouLiveApiRequest [#KuaishouLiveApiRequest]

快手 `live_api` 请求描述对象。

除了最终请求地址外，还可以携带 `signPath`，用于声明
`__NS_hxfalcon` 实际参与签名的规范路径。

```ts
type KuaishouLiveApiRequest = KuaishouBaseApiRequest & { body: Record<string, unknown>; method: "GET" | "POST"; requiresSign: boolean; signPath: string }
```

源码：[`src/platforms/legacy/kuaishou/API.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/platforms/legacy/kuaishou/API.ts#L27)

### KuaishouMethodType [#KuaishouMethodType]

```ts
type KuaishouMethodType = keyof typeof KuaishouValidationSchemas
```

源码：[`src/validation/kuaishou.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/validation/kuaishou.ts#L83)

### LoginChallenge [#LoginChallenge]

二次验证 challenge

```ts
type LoginChallenge = SmsChallenge | CaptchaChallenge
```

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L78)

### LoginState [#LoginState]

登录会话的状态。判别键是 phase

```ts
type LoginState = { phase: "pending"; qrcode: Qrcode } | { phase: "scanned"; qrcode: Qrcode } | { challenge: LoginChallenge; phase: "challenge" } | { credential: Credential; phase: "success" } | { phase: "expired" } | { phase: "rejected" } | { phase: "risk"; reason: string } | { error: AmagiError; phase: "failed" }
```

源码：[`src/contracts/session.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/session.ts#L18)

### Options [#Options]

客户端配置选项接口

形状冻结不动。`ClientOptions` 是它的超集（多一个 `debug`），
两者赋值互通，所以 `createAmagiClient(o: Options)` 的调用点零改动。

```ts
type Options = { cookies: CookieConfig; request: Omit<AxiosRequestConfig, "url" | "method" | "data"> }
```

源码：[`src/server/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/server/index.ts#L43)

### Platform [#Platform]

amagi 支持的平台

```ts
type Platform = typeof PLATFORMS[number]
```

源码：[`src/contracts/platform.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/platform.ts#L17)

### RequestConfig [#RequestConfig]

请求配置选项接口

与 `contracts/request.ts` 的同名类型逐字相同（顶层导出的就是 contracts
那一份）。新代码请用 contracts 的。

```ts
type RequestConfig = Omit<AxiosRequestConfig, "url" | "method" | "data">
```

源码：[`src/server/index.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/server/index.ts#L21)

### TraceReason [#TraceReason]

一次底层请求的发起原因。

区分「端点内重试」与「传输层重试」、「翻页」与「分段并发」，
是排查请求数叠乘的入口。

```ts
type TraceReason = "initial" | "retry" | "challenge" | "page" | "segment" | "prepare"
```

源码：[`src/contracts/meta.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/contracts/meta.ts#L20)

### VerifyPlatform [#VerifyPlatform]

有风控 challenge 的平台（B 站没有 challenge 提取器）

```ts
type VerifyPlatform = Exclude<Platform, "bilibili">
```

源码：[`src/verify/data.ts`](https://github.com/ikenxuan/amagi/blob/main/packages/core/src/verify/data.ts#L10)


# 快速上手 (https://ikenxuan.github.io/amagi/docs/v7/usage/getting-started)

> 三步上手：创建客户端、获取数据、按 success 读取返回值



# 快速上手 [#快速上手]

安装完成后，从创建客户端到获取第一条数据，大致分三步，下面逐步说明。

## 第一步：创建客户端 [#第一步创建客户端]

`amagi()` 接收各平台的 Cookie，返回一个客户端实例。此后的所有请求都通过它发起，无需重复传入 Cookie：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; bili_jct=yyy; ...',
    douyin: 'ttwid=...; ...',
    kuaishou: 'did=...; ...',
    xiaohongshu: 'a1=...; ...'
  },
  request: {
    // 如需自定义请求头、超时、代理，在此配置（可选）
    headers: { 'User-Agent': 'Mozilla/5.0 ...' }
  }
})
```

关于 Cookie 的获取：登录对应平台的网页版，在浏览器开发者工具中完整复制请求头里的 `Cookie`。用不到的平台留空字符串即可，无需四个平台全部填写。

## 第二步：获取数据 [#第二步获取数据]

通过 `client.<平台>.fetcher` 调用对应的方法。下面四个平台各举一例，均为获取一条作品或视频的详情：

<CodeBlockTabs defaultValue="B站" groupId="platform">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="B站">
      B站
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="抖音">
      抖音
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="快手">
      快手
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="小红书">
      小红书
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="B站">
    ```ts  
    // 获取视频信息
    const video = await client.bilibili.fetcher.fetchVideoInfo({
      bvid: 'BV1xx411c7mD'
    })

    if (video.success) {
      console.log(video.data)
    }

    // 获取评论
    const comments = await client.bilibili.fetcher.fetchComments({
      oid: '170001',
      type: 1,
      number: 20
    })
    ```
  </CodeBlockTab>

  <CodeBlockTab value="抖音">
    ```ts
    // 获取作品数据
    const work = await client.douyin.fetcher.fetchVideoWork({
      aweme_id: '1234567890123456789'
    })

    // 聚合解析（自动识别类型）
    const parsed = await client.douyin.fetcher.parseWork({
      aweme_id: '1234567890123456789'
    })

    // 获取评论
    const comments = await client.douyin.fetcher.fetchWorkComments({
      aweme_id: '1234567890123456789',
      number: 20
    })

    // 获取合集中的作品，自动按游标翻页
    const mix = await client.douyin.fetcher.fetchMixAweme({
      mix_id: '7419965435527974176',
      number: 40
    })
    ```
  </CodeBlockTab>

  <CodeBlockTab value="快手">
    ```ts
    // 获取作品信息
    const work = await client.kuaishou.fetcher.fetchVideoWork({
      photoId: '3xqxxxxxx'
    })

    // 获取评论
    const comments = await client.kuaishou.fetcher.fetchWorkComments({
      photoId: '3xqxxxxxx'
    })
    ```
  </CodeBlockTab>

  <CodeBlockTab value="小红书">
    ```ts
    // 获取笔记数据
    const note = await client.xiaohongshu.fetcher.fetchNoteDetail({
      note_id: '64xxxxxxxx',
      xsec_token: 'xsec_xxx'
    })

    // 获取一级评论
    const comments = await client.xiaohongshu.fetcher.fetchNoteComments({
      note_id: '64xxxxxxxx',
      xsec_token: 'xsec_xxx'
    })

    // 展开一级评论下的回复，按目标数量自动翻页
    const replies = await client.xiaohongshu.fetcher.fetchSubComments({
      note_id: '64xxxxxxxx',
      root_comment_id: 'comment-id',
      xsec_token: 'xsec_xxx',
      number: 20
    })

    // 搜索用户；直播 ID 使用字符串保存
    const users = await client.xiaohongshu.fetcher.searchUser({ keyword: '旅行', page: 1 })
    const live = await client.xiaohongshu.fetcher.fetchLiveStatus({ room_id: '570461472695232183' })
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 第三步（可选）：启动 HTTP 服务 [#第三步可选启动-http-服务]

如果不想在代码中直接调用，而是希望通过 HTTP 请求获取数据（例如供其他语言或进程使用），在客户端上调用 `startServer`，即可将其启动为本地服务：

```ts twoslash
import amagi from '@ikenxuan/amagi'

amagi({
  cookies: {
    bilibili: 'SESSDATA=xxx; ...',
    douyin: 'ttwid=...; ...',
    kuaishou: 'did=...; ...',
    xiaohongshu: 'a1=...; ...'
  }
}).startServer(4567)

// 在浏览器中打开 http://localhost:4567/ 查看接口列表
// 在线调试：https://amagi.apifox.cn
```

<Callout type="warn">
  该服务默认不带鉴权，任何能访问此端口的人都可以使用你的 Cookie 发起请求。请仅在本机使用，或在其前自行添加一层访问控制，不要直接暴露到公网。
</Callout>

## 不创建客户端的调用方式 [#不创建客户端的调用方式]

如果只是临时调用少数几个接口，不想先创建客户端，可以直接使用静态方法，代价是每次都要手动传入 Cookie：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const result = await amagi.bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }, 'SESSDATA=...')
```

## 如何读取返回值 [#如何读取返回值]

每个方法都返回同一种结构。先判断 `result.success`：为 `true` 时，`result.data` 即为数据；为 `false` 时，`result.error` 是错误详情。在 TypeScript 中，只有先判断过 `success` 才能访问 `data`，因此这个 `if` 判断不可省略：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD'
})

if (result.success) {
  result.data
  //     ^?
} else {
  // 失败分支没有 data，只有 error（kind / code / message 等）
  console.error(result.error.kind, result.error.message)
}
```

类型是根据真实响应逐一编写的，偶尔会滞后于平台新增的字段。即使遇到类型中未声明的字段，同样可以读取（读取结果为 `unknown`，需自行判断后再使用），也可以用泛型将返回类型替换为自定义类型。这几种写法在[响应类型](/docs/v7/usage/guide/type-mode)中有详细说明。

## 记录请求日志 [#记录请求日志]

如果想知道每次请求发往何处、耗时多少、是否发生重试，可以通过客户端的事件总线订阅，调用 `client.on` 即可。每条事件都带有 `meta`，上述信息都在其中：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// ---cut---
// 一次调用成功
client.on('api:success', (d) => {
  console.log(`[${d.meta.platform}] ${d.meta.endpoint} 成功，耗时 ${d.meta.durationMs}ms`)
})

// 一次调用失败：error 中包含错误的类型与原因
client.on('api:error', (d) => {
  console.error(`[${d.meta.platform}] ${d.meta.endpoint} 失败: ${d.error.message}`)
})

// 底层每发出一条 HTTP 请求都会触发一次
client.on('http:request', (d) => {
  console.log(d.trace.reason, d.trace.method, d.trace.url)
})
```

<Callout type="info">
  包顶层还导出了一个 `amagiEvents`，那是为 v6 旧代码保留的另一条总线，接收不到 `client.on` 上的事件，请勿将两者混淆。完整的事件名与两条总线的分工见[事件系统](/docs/v7/usage/advanced/events)。
</Callout>

## 下一步 [#下一步]

<DocsCategory group="使用指南" />


# SDK 使用指南 (https://ikenxuan.github.io/amagi/docs/v7/usage/guide/sdk)

> 详细了解如何使用 amagi SDK



# SDK 使用指南 [#sdk-使用指南]

调用 amagi 有三种写法，区别只在于如何传入 Cookie。日常使用第一种即可，另两种用于特定场景。

## 创建实例（推荐） [#创建实例推荐]

将 Cookie 传入 `amagi()`，得到客户端实例，之后即可直接调用各平台的方法，无需再关心 Cookie：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'your_bilibili_cookie',
    douyin: 'your_douyin_cookie',
    kuaishou: 'your_kuaishou_cookie',
    xiaohongshu: 'your_xiaohongshu_cookie'
  }
})

// 通过 client.<平台>.fetcher 调用方法
const video = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
const work = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '123456789' })
```

## 不创建实例，每次传入 Cookie [#不创建实例每次传入-cookie]

如果只需调用少数几个接口，不想为此创建客户端，可以使用静态 fetcher。方法名与用法相同，只是 Cookie 改为第二个参数，且每次都要传入：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const result = await amagi.bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }, 'SESSDATA=xxx; bili_jct=yyy')
```

## 绑定 Cookie 后重复调用 [#绑定-cookie-后重复调用]

如果既想要静态 fetcher 无需创建实例的简便，又不想每次重复传入 Cookie，可以用 `createBound*Fetcher` 预先绑定 Cookie，之后调用只需传入业务参数：

```ts twoslash
import amagi from '@ikenxuan/amagi'

// 预先将 Cookie 绑定到 fetcher
const bilibiliFetcher = amagi.createBoundBilibiliFetcher('your_cookie')
const douyinFetcher = amagi.createBoundDouyinFetcher('your_cookie')

// 后续调用无需再传入 Cookie
const video = await bilibiliFetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
```

## 返回值：统一封装在「信封」中 [#返回值统一封装在信封中]

无论调用哪个方法，返回的都不是数据本身，而是一层统一的外层结构，称为「信封」（`AmagiResult<T>`）。信封中要么是数据，要么是错误。先判断 `success` 字段：为 `true` 时读取 `data`，为 `false` 时读取 `error`。顶层没有 `code`，请求失败时也不会抛出异常，失败同样以返回值的形式给出。

<Callout type="warn">
  v7 的信封与 v6 的 `Result<T>` 不同：**顶层 `code` 已删除**，`error` 也不再是 `any`。
  v6 用同一个 `code` 混装 HTTP 状态码、平台业务码与内部码，v7 把它们各归各位 ——
  HTTP 状态在 `error.http.status`、平台原始码在 `error.platform.code`、amagi
  自己的错误码在 `error.code`。要整体切回 v6 语义（含顶层 `code`）用
  `@ikenxuan/amagi/compat`，一行改导入即可。
</Callout>

下面两张表由 `packages/core` 的 TypeScript 源码在构建期生成，字段名、类型、说明
全部取自源码注释：

### 成功信封 [#成功信封]

<TypeTable
  id="type-table-result.ts-AmagiSuccess"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiSuccess&#x22;,
  &#x22;name&#x22;: &#x22;AmagiSuccess&#x22;,
  &#x22;description&#x22;: &#x22;成功信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;true&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;true&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;端点声明的返回类型&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;T&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;T&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n成功信封**运行时没有这个键**，所以类型只能是 `undefined`。存在的唯一理由是\n让未收窄的 AmagiResult 上 `r.error` 可读（类型 `AmagiError | undefined`），\n而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的简短说明，成功时固定为 SUCCESS_MESSAGE。\n\n注意 **`success: true` 不等于「取满了目标条数」**：声明式翻页在\n`hasMore` 为假、本页为空、或某一页被平台拒绝时都会提前收尾，返回已取到的部分。\n需要精确判断的调用方拿 `data` 里的条目数与目标比对，别靠信封。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### 失败信封 [#失败信封]

<TypeTable
  id="type-table-result.ts-AmagiFailure"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiFailure&#x22;,
  &#x22;name&#x22;: &#x22;AmagiFailure&#x22;,
  &#x22;description&#x22;: &#x22;失败信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;false&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;false&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;唯一的错误载体，永不为 `undefined`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiError&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n失败信封**运行时没有这个键**，所以类型只能是 `undefined`。有了它，未收窄的\n`r.data` 是 `T | undefined`，而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;等价于 `error.message`，为兼容 v6 的 `result.message` 读法保留&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

`error` 的完整字段（`kind` / `code` / `retryable` / `platform` / `http` / `issues` /
`raw`）与 `meta` 的字段见[响应类型](/docs/v7/usage/guide/type-mode#字段表)那一页，
连同**四种读法**（直接读 / `if` 收窄 / `filter(isSuccess)` / `unwrap`）。

### 使用示例 [#使用示例]

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

if (result.success) {
  console.log(result.data)
} else {
  console.error(result.message, result.error)
}
```

## 自定义请求头、超时与代理 [#自定义请求头超时与代理]

创建实例时写在 `request` 中，该客户端此后发出的每一条请求都会带上这些配置：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({
  cookies: {
    bilibili: 'your_cookie',
    douyin: 'your_cookie',
    kuaishou: 'your_cookie',
    xiaohongshu: 'your_cookie'
  },
  request: {
    headers: {
      'User-Agent': 'Mozilla/5.0 ...'
    },
    timeout: 10000,
    proxy: {
      host: '127.0.0.1',
      port: 7890
    }
  }
})
```

## 平台模块结构 [#平台模块结构]

每个平台模块包含以下内容（`request` 与 `apiUrls` 是 v7 新增的两个键：前者用于请求任意接口，见[自定义请求](/docs/v7/usage/advanced/custom-request)；后者是 v7 那份 URL 构造器。v6 那份（`douyinApiUrls` 等带平台名的四个）**不在平台模块上** —— 它从包顶层与 `@ikenxuan/amagi/compat` 到达）。四个平台都带 `login`（扫码登录会话），B站另带 `refreshCredential`（Cookie 续期），抖音另带 `credentials`（Cookie / 登录态 / 游客凭据工具，见[工具集](/docs/v7/usage/guide/utilities)）：

<CodeBlockTabs defaultValue="B站" groupId="platform">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="B站">
      B站
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="抖音">
      抖音
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="快手">
      快手
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="小红书">
      小红书
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="B站">
    ```ts twoslash  
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // ---cut---
    // fetcher - 数据获取器
    client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx' })
    client.bilibili.fetcher.fetchComments({ oid: '123', type: 1 })
    client.bilibili.fetcher.fetchUserCard({ host_mid: 123456 })

    // sign - 签名算法
    client.bilibili.sign.av2bv(170001)
    client.bilibili.sign.bv2av('BV1xx411c7mD')

    // danmaku - 弹幕解析
    // client.bilibili.danmaku.parseDmSegMobileReply(buffer)

    // login - 扫码登录；refreshCredential - Cookie 续期
    // client.bilibili.login.qrcode()
    // client.bilibili.refreshCredential({ cookie, refreshToken })
    ```
  </CodeBlockTab>

  <CodeBlockTab value="抖音">
    ```ts twoslash 
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // ---cut---
    // fetcher - 数据获取器
    client.douyin.fetcher.fetchVideoWork({ aweme_id: '123' })
    client.douyin.fetcher.parseWork({ aweme_id: '123' })
    client.douyin.fetcher.fetchWorkComments({ aweme_id: '123' })

    // sign - 签名算法
    client.douyin.sign.Mstoken(128)
    // client.douyin.sign.AB(url, ua)
    // client.douyin.sign.XB(url, ua)

    // login - 扫码登录
    // client.douyin.login.qrcode()
    ```
  </CodeBlockTab>

  <CodeBlockTab value="快手">
    ```ts twoslash 
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // ---cut---
    // fetcher - 数据获取器
    client.kuaishou.fetcher.fetchVideoWork({ photoId: '3xq123' })
    client.kuaishou.fetcher.fetchWorkComments({ photoId: '3xq123' })
    client.kuaishou.fetcher.fetchUserProfile({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchUserWorkList({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchLiveRoomInfo({ principalId: 'KPL704668133' })
    client.kuaishou.fetcher.fetchEmojiList({})

    // sign - 签名算法
    // client.kuaishou.sign.signLiveApiRequest(request, cookie)

    // login - 扫码登录
    // client.kuaishou.login.qrcode()
    ```
  </CodeBlockTab>

  <CodeBlockTab value="小红书">
    ```ts twoslash 
    import amagi from '@ikenxuan/amagi'
    const client = amagi({ cookies: { bilibili: '', douyin: '', kuaishou: '', xiaohongshu: '' } })
    // ---cut---
    // fetcher - 数据获取器
    client.xiaohongshu.fetcher.fetchNoteDetail({ note_id: '123', xsec_token: 'xxx' })
    client.xiaohongshu.fetcher.fetchNoteComments({ note_id: '123', xsec_token: 'xxx' })
    client.xiaohongshu.fetcher.fetchUserProfile({ user_id: '123' })

    // sign - 签名算法
    // client.xiaohongshu.sign.generateXSGet(path, a1Cookie)

    // login - 扫码登录
    // client.xiaohongshu.login.qrcode()
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 扫码登录 [#扫码登录]

四个平台都提供 `client.<平台>.login`。它是一次**有状态会话**，不是端点：`qrcode()` 新建、`resume(blob)` 从 `serialize()` 的产物恢复，轮询 / 退避 / 超时 / 二次验证编排都在引擎里。

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({})

const outcome = await client.bilibili.login.qrcode().watch({
  onQrcode: (qr) => console.log(qr.content), // 拿去生成二维码图片
  onScanned: () => console.log('已扫码')
})

if (outcome.ok) {
  console.log(outcome.credential.cookie) // 直接传给 fetcher，或下次创建 client 时使用
}
```

`watch()` 返回的是 `{ ok, credential } | { ok, error }`，**不是** `AmagiResult`。同一会话还有两种消费方式：`for await (const state of session)` 逐状态消费，或 `start()` + `next()` 手动单步（`challenge` 阶段用 `answer()` 应答）。想把会话存下来跨进程继续，用 `session.serialize()`，再用 `client.<平台>.login.resume(blob)` 恢复。

`LoginState.phase` 的完整状态机、各平台协议差异与已知限制见[翻页与会话](/docs/v7/dev/internals/session)。会话每一步还会发到实例总线（`session:state` / `session:success` / `session:error`），见[事件系统](/docs/v7/usage/advanced/events)。

## B站 Cookie 续期 [#b站-cookie-续期]

B站有一套官方续期协议：登录时下发的 `refresh_token`（Web 端存在 `localStorage.ac_time_value`）可以在不重新扫码的情况下换一份新 Cookie。四平台里只有 B站有这条协议：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({})

declare const cookie: string
declare const refreshToken: string

const refreshed = await client.bilibili.refreshCredential({ cookie, refreshToken })

if (refreshed.ok) {
  // 两个值都要持久化替换旧值：旧 refresh_token 已在协议第 4 步作废
  console.log(refreshed.credential.cookie)
  console.log(refreshed.credential.refreshToken)
} else {
  console.error(refreshed.error.code, refreshed.error.message)
}
```

`cookie` 至少要含 `SESSDATA` 与 `bili_jct`。这是平台正规续期通道，不涉及风控对抗；失败时不会自动重试，按 `refreshed.error` 处理即可。


# 响应类型 (https://ikenxuan.github.io/amagi/docs/v7/usage/guide/type-mode)

> v7 的响应类型模型与三条逃生舱（typeMode 已移除）



# 响应类型 [#响应类型]

<Callout type="warn">
  **v7 移除了 `typeMode`。** v6 的 `typeMode: 'strict' | 'loose'` 是一个「写了
  两万六千行类型、默认却返回 `any`」的中间态。v7 只有一种模式：响应类型始终是
  端点声明里的具体类型，不需要任何参数开关。v6 代码里的 `typeMode` 参数可以直接
  删除。
</Callout>

## 一种模式：具体类型 + 判别联合 [#一种模式具体类型--判别联合]

`success` 是唯一判别键。收窄之后 `data` 才可读；失败分支没有 `data`，只有 `error`：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const video = await client.bilibili.fetcher.fetchVideoInfo({
  bvid: 'BV1xx411c7mD'
})

if (video.success) {
  video.data
  //    ^?
} else {
  // 失败分支：kind / code / message / platform 原文码都在 error 上
  console.error(video.error.kind, video.error.message)
}
```

## 四种读法 [#四种读法]

`success` 是唯一判别键，但「先判断再读」不是唯一写法。四种读法的区别只有一处：
&#x2A;*得到的 `data` 是 `T` 还是 `T | undefined`**。

### 1. 直接读（不收窄） [#1-直接读不收窄]

未收窄的信封上 `data` 与 `error` 都可读，类型各带 `| undefined`。这就是 v6 的读法，
而且比 v6 诚实 —— v6 两支都声明 `data: T`，掩盖了「这次可能是失败」：

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const r = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

// 类型是 BiliOneWork_V0 | undefined
const maybe = r.data
console.log(maybe?.View)
```

代价是访问其属性前需先处理 `undefined`，否则无法通过编译（页面上这段报的就是真实错误）：

```ts twoslash
// @errors: 18048
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
const r = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })
// ---cut---
r.data.View
```

### 2. `if (r.success)` 收窄 [#2-if-rsuccess-收窄]

上一节那段就是这种写法：收窄之后 `data` 是 `T`（不带 `| undefined`），
`else` 分支里 `error` 是 `AmagiError`。日常首选。

### 3. `filter(isSuccess)` [#3-filterissuccess]

数组回调里没有 `if` 可用 —— 这是 `?: undefined` 解决不了的场景，
所以顶层导出了两个类型守卫：

```ts twoslash
import amagi, { isSuccess } from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const results = await Promise.all([
  client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }),
  client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1yy411c7mE' })
])

// BiliOneWork_V0[]，不是 (BiliOneWork_V0 | undefined)[]
const works = results.filter(isSuccess).map((r) => r.data)
console.log(works.length)
```

`isFailure` 与它对称，收窄之后可以直接按 `error.kind` 分流。

### 4. `unwrap`：失败即抛 [#4-unwrap失败即抛]

愿意让失败沿调用栈往上冒的人用它 —— 返回类型是 `T`，不是 `T | undefined`：

```ts twoslash
import amagi, { unwrap } from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const work = unwrap(await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' }))
console.log(work.View)
```

抛出的是 `AmagiThrownError`（`Error` 子类）：`kind` / `code` / `message` / `retryable`
等字段全部平铺在实例上，`catch (e) { (e as AmagiError).kind }` 直接可用，
原始 `error` 对象在 `e.error` 上，`error.cause` 原样进 `Error.cause`。

<Callout type="info">
  管线本身**永不 reject**（参数校验失败、平台业务错误、网络错误、内部异常都映射为
  `success: false`）。`unwrap` 是调用方**显式**把失败转成异常，不是管线行为变了。
  要整体回到 v6 的语义（含顶层 `code`）请用 [`@ikenxuan/amagi/compat`](/docs/v7/usage/guide/sdk)，
  两者不重叠。
</Callout>

## 失败分支里的 `error.challenge` [#失败分支里的-errorchallenge]

失败信封的 `error` 上还有一个可选字段 `challenge`。平台判出 `kind: 'risk'` 且拿到验证信号时，它是 `{ url, ... }`：`url` 是人能直接打开的验证页（已补协议）；抖音从响应体通道识别时还带 `jsSdkUrl` / `verifyData`，可以自建验证页。

```ts twoslash
import amagi, { renderVerifyPage } from '@ikenxuan/amagi'
const client = amagi({ cookies: { douyin: '' } })

const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '7419965435527974176' })
if (!r.success && r.error.challenge) {
  const html = renderVerifyPage(r.error.challenge, { platform: 'douyin' })
  console.log(html.length)
}
```

处理三步：把 `url` 交给真人打开（或把 `renderVerifyPage` 返回的 HTML 自己起路由返回）；等真人过完；用**同一份 cookie** 重发原请求。amagi 不识别、不模拟轨迹、不自动过滑块。

覆盖范围：抖音 / 快手 / 小红书装了提取器，B站没有（`error.challenge` 恒为 `undefined`）。抖音的 WAF / VMP 这类纯工作量证明在管线内自动解掉并立即重放（`trace.reason === 'challenge'`，不退避）；滑块必须真人拖，判 `CAPTCHA_REQUIRED` 且不进重试名单。`error.challenge` 不受 `debug` 影响 —— client、HTTP 路由、静态 fetcher 三个入口都拿得到。

## 字段表 [#字段表]

以下五张表由 `packages/core` 的 TypeScript 源码在构建期生成（`<auto-type-table>`），
字段名、类型、说明全部取自源码的 TSDoc。

### AmagiSuccess [#amagisuccess]

<TypeTable
  id="type-table-result.ts-AmagiSuccess"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiSuccess&#x22;,
  &#x22;name&#x22;: &#x22;AmagiSuccess&#x22;,
  &#x22;description&#x22;: &#x22;成功信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;true&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;true&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;端点声明的返回类型&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;T&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;T&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n成功信封**运行时没有这个键**，所以类型只能是 `undefined`。存在的唯一理由是\n让未收窄的 AmagiResult 上 `r.error` 可读（类型 `AmagiError | undefined`），\n而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的简短说明，成功时固定为 SUCCESS_MESSAGE。\n\n注意 **`success: true` 不等于「取满了目标条数」**：声明式翻页在\n`hasMore` 为假、本页为空、或某一页被平台拒绝时都会提前收尾，返回已取到的部分。\n需要精确判断的调用方拿 `data` 里的条目数与目标比对，别靠信封。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### AmagiFailure [#amagifailure]

<TypeTable
  id="type-table-result.ts-AmagiFailure"
  type="{
  &#x22;id&#x22;: &#x22;result.ts-AmagiFailure&#x22;,
  &#x22;name&#x22;: &#x22;AmagiFailure&#x22;,
  &#x22;description&#x22;: &#x22;失败信封&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;success&#x22;,
      &#x22;description&#x22;: &#x22;判别键&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;false&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;false&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;error&#x22;,
      &#x22;description&#x22;: &#x22;唯一的错误载体，永不为 `undefined`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiError&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;data&#x22;,
      &#x22;description&#x22;: &#x22;对侧键的占位声明。\n\n失败信封**运行时没有这个键**，所以类型只能是 `undefined`。有了它，未收窄的\n`r.data` 是 `T | undefined`，而不是 TS2339。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;等价于 `error.message`，为兼容 v6 的 `result.message` 读法保留&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;meta&#x22;,
      &#x22;description&#x22;: &#x22;元信息&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiMeta&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### AmagiError [#amagierror]

<TypeTable
  id="type-table-error.ts-AmagiError"
  type="{
  &#x22;id&#x22;: &#x22;error.ts-AmagiError&#x22;,
  &#x22;name&#x22;: &#x22;AmagiError&#x22;,
  &#x22;description&#x22;: &#x22;失败信封里唯一的错误载体，永不为 `undefined`&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;kind&#x22;,
      &#x22;description&#x22;: &#x22;判别键，跨平台统一的错误大类&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;ErrorKind&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;code&#x22;,
      &#x22;description&#x22;: &#x22;稳定的字符串错误码，可用于 switch 与埋点&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;AmagiErrorCode&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;message&#x22;,
      &#x22;description&#x22;: &#x22;面向人的说明，取平台原文优先&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;retryable&#x22;,
      &#x22;description&#x22;: &#x22;是否值得重试。调用方据此决定退避还是放弃&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台原始错误码与文案，一个字都不丢&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ code: string | number; message?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;http&#x22;,
      &#x22;description&#x22;: &#x22;真实发生的 HTTP 状态（有请求才有）&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ status: number; statusText?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;issues&#x22;,
      &#x22;description&#x22;: &#x22;`kind === 'validation'` 时的字段级错误&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ValidationIssue[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;raw&#x22;,
      &#x22;description&#x22;: &#x22;原始响应体。默认**连键都没有**，`createClient({ debug: true })` 且这次\n确实**拿到了响应**时才填（网络中断 / 超时那类失败没有响应体可放）。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;challenge&#x22;,
      &#x22;description&#x22;: &#x22;风控挑战（验证页地址 + 票据）。`kind === 'risk'` 且平台认得出这份响应时才有。\n\n**不受 `debug` 开关影响** —— 它是「怎么过去」这条必要信息，见\nRiskChallenge。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RiskChallenge | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;cause&#x22;,
      &#x22;description&#x22;: &#x22;底层 Error 对象，仅用于日志&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;unknown&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;unknown&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### AmagiMeta [#amagimeta]

<TypeTable
  id="type-table-meta.ts-AmagiMeta"
  type="{
  &#x22;id&#x22;: &#x22;meta.ts-AmagiMeta&#x22;,
  &#x22;name&#x22;: &#x22;AmagiMeta&#x22;,
  &#x22;description&#x22;: &#x22;挂在每个信封上的元信息&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;requestId&#x22;,
      &#x22;description&#x22;: &#x22;每次逻辑调用一个 id，贯穿事件、日志、trace&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;clientId&#x22;,
      &#x22;description&#x22;: &#x22;发起调用的 client 实例 id；静态 fetcher 用 `'static'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;platform&#x22;,
      &#x22;description&#x22;: &#x22;平台&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;bilibili\&#x22; | \&#x22;douyin\&#x22; | \&#x22;kuaishou\&#x22; | \&#x22;xiaohongshu\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;endpoint&#x22;,
      &#x22;description&#x22;: &#x22;端点全名，如 `'douyin.videoWork'`&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;durationMs&#x22;,
      &#x22;description&#x22;: &#x22;从进入 fetcher 到返回信封的总耗时&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;attempts&#x22;,
      &#x22;description&#x22;: &#x22;实际发出的 HTTP 请求数，含重试与分页。分页 3 页 + 1 次重试 = 4&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;number&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;number&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;trace&#x22;,
      &#x22;description&#x22;: &#x22;每次底层请求的明细，按发出顺序。\n\n默认不带：`createClient({ debug: true })` 时才填（同一个开关也给失败信封\n填 `error.raw`，没有单独的 trace 开关）。不开时信封上**没有 `trace`\n这个键**，而 `attempts` 照样准确 —— 计数始终发生，只有明细受开关控制。\n\n静态 fetcher（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。\n要不受开关影响地逐条观测请求，监听 `http:request` / `http:response`\n事件：它们的负载恒带 `trace`。URL 含签名参数，别在生产里无条件打印。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestTrace[] | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;array&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;incomplete&#x22;,
      &#x22;description&#x22;: &#x22;结果不完整时的原因：翻页端点声明了 `partial: 'tolerate'`、中途某页失败，\n信封仍是成功、`data` 里是已取到的那几页，这里是那个失败页的错误。\n\n完整结果上**没有这个键**。只看 `success` 的调用方会拿到截断的数据 ——\n在意条数的，检查这个键。没声明 `tolerate` 的翻页端点中途失败也返回部分结果，\n但**不**挂这个键，只能拿条目数与目标比对。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ kind: ErrorKind; code: AmagiErrorCode; message: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### ClientOptions [#clientoptions]

<TypeTable
  id="type-table-createClient.ts-ClientOptions"
  type="{
  &#x22;id&#x22;: &#x22;createClient.ts-ClientOptions&#x22;,
  &#x22;name&#x22;: &#x22;ClientOptions&#x22;,
  &#x22;description&#x22;: &#x22;客户端构造选项&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;cookies&#x22;,
      &#x22;description&#x22;: &#x22;Cookie 配置&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;{ douyin?: string; bilibili?: string; kuaishou?: string; xiaohongshu?: string; } | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;xiaohongshuSession&#x22;,
      &#x22;description&#x22;: &#x22;与 Cookie 配对的小红书会话材料；旧 cookies 配置仍可单独使用。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;XiaohongshuSessionInput | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;request&#x22;,
      &#x22;description&#x22;: &#x22;请求配置&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;RequestConfig | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;RequestConfig&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;debug&#x22;,
      &#x22;description&#x22;: &#x22;排障开关。打开后两样东西同时出现：失败信封的 `error.raw` 带平台原始响应体，\n每个信封的 `meta.trace` 带这次调用发出的每一条底层请求（URL / 方法 /\n状态码 / 耗时 / 发出原因）。用于排查协议变更、风控页、业务码含义不明，\n以及「这一次调用到底打了几个请求」。\n\n默认 `false`，此时失败信封上**没有** `raw` 这个键、`meta` 上也**没有**\n`trace` 这个键（不是 `undefined` 占位）。`meta.attempts` 与本开关无关，\n一直是准的 —— 计数始终发生，只有明细受开关控制。\n\n`debug` 一个开关同时管 `error.raw` 与 `meta.trace` 两样：两者都只服务排障，\n分成两个名字等于让人多记一个。要**不受开关影响**地逐条观测请求，监听\n`http:request` / `http:response` 事件 —— 它们的负载恒带 `trace`。\n\n原始响应可能很大、也可能带敏感字段，`trace` 里的 URL 含签名参数，\n别在生产里无条件打印。只作用于 client 实例上的 fetcher：静态 fetcher\n（`amagi.douyinFetcher.*`）与 HTTP 服务的平台路由没有这个开关。&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;boolean | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

## 稳定性承诺 [#稳定性承诺]

响应类型是**实测快照** —— 按真实响应写下来的形状，不是平台的契约。因此：

* 平台**新增**字段不算破坏性变更（类型可能一时没有它）
* 平台**删除/ 改名**字段时，类型会随修复版本更新
* 每个响应类型都带顶层索引签名，读未声明字段返回 `unknown` 而不是编译错误

## 三条逃生舱 [#三条逃生舱]

当类型与真实响应不一致时，按代价从低到高选：

### 1. 索引签名（读未声明字段） [#1-索引签名读未声明字段]

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

if (result.success) {
  // 未声明字段：类型是 unknown，自己收窄
  const extra = result.data['newFieldFromPlatform']
  if (typeof extra === 'string') console.log(extra.toUpperCase())
}
```

### 2. 显式泛型覆盖返回类型 [#2-显式泛型覆盖返回类型]

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
interface MyShape {
  data: { bvid: string; newField: number }
}

const result = await client.bilibili.fetcher.fetchVideoInfo<MyShape>({
  bvid: 'BV1xx411c7mD'
})

if (result.success) {
  result.data.data.newField
  //                ^?
}
```

### 3. 类型断言（最后手段） [#3-类型断言最后手段]

```ts twoslash
import amagi from '@ikenxuan/amagi'
const client = amagi({ cookies: { bilibili: '' } })
// ---cut---
const result = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

if (result.success) {
  const newField = (result.data as Record<string, unknown>).newField
  void newField
}
```

## 从 v6 迁移 [#从-v6-迁移]

| v6 写法                                 | v7 写法                                                    |
| ------------------------------------- | -------------------------------------------------------- |
| `fetchX({ ..., typeMode: 'strict' })` | `fetchX({ ... })`（删参数，类型本就具体）                            |
| `fetchX({ ..., typeMode: 'loose' })`  | `fetchX({ ... })` + 需要时用上面的逃生舱                           |
| `result.data`（未收窄）                    | `if (result.success) result.data`                        |
| `result.code`                         | `result.error.platform?.code ?? result.error.code`（失败分支） |


# 工具集 (https://ikenxuan.github.io/amagi/docs/v7/usage/guide/utilities)

> amagi 提供的各平台工具函数



# 工具集 [#工具集]

除了成套的接口方法，amagi 还单独提供了各平台的一些底层工具：签名计算、URL 拼接、AV/BV 号互转、弹幕解析。这些平时用不到，只有在需要自行拼接接口、或单独使用其中某个算法时才会用到。

## 各平台的工具 [#各平台的工具]

<Tabs items="['B站', '抖音', '快手', '小红书']">
  <Tab value="B站">
    ```ts twoslash
    import { bilibiliUtils } from '@ikenxuan/amagi'

    // AV/BV 转换
    const bv = bilibiliUtils.sign.av2bv(170001)
    const av = bilibiliUtils.sign.bv2av('BV17x411w7KC')
    ```

    ### 签名算法 [#签名算法]

    ```ts twoslash
    import { bilibiliUtils } from '@ikenxuan/amagi'
    // WBI 签名
    const signedUrl = await bilibiliUtils.sign.wbi_sign(
      'https://api.bilibili.com/x/web-interface/view?bvid=BV1xx',
      'your_cookie'
    )
    ```

    ### 弹幕解析 [#弹幕解析]

    ```ts twoslash
    import { bilibiliUtils } from '@ikenxuan/amagi'

    // `buffer` 是 `/x/v2/dm/web/seg.so` 的响应体（protobuf 二进制）
    declare const buffer: Uint8Array
    // 解析 protobuf 格式的弹幕数据
    const danmakuList = bilibiliUtils.danmaku.parseDmSegMobileReply(buffer)
    ```

    ### Cookie 续期 [#cookie-续期]

    B站还支持官方协议的 Cookie 续期：`client.bilibili.refreshCredential({ cookie, refreshToken })`；顶层等价物是 `refreshBilibiliCredential`（需要自己注入 `send`）。用法与注意事项见 [SDK 参考的「B站 Cookie 续期」](/docs/v7/usage/guide/sdk#b站-cookie-续期)。
  </Tab>

  <Tab value="抖音">
    ```ts twoslash
    import { douyinUtils } from '@ikenxuan/amagi'

    // 生成 msToken
    const msToken = douyinUtils.sign.Mstoken(128)
    ```

    ### 签名算法 [#签名算法-1]

    ```ts twoslash
    import { douyinUtils } from '@ikenxuan/amagi'

    // 待签名的完整 URL（含 query），以及可选的 UA —— 不传时用内置的 Chrome 125 UA
    declare const url: string
    declare const userAgent: string
    // 生成 a_bogus 签名
    const aBogus = douyinUtils.sign.AB(url, userAgent)

    // 生成 X-Bogus 签名
    const xBogus = douyinUtils.sign.XB(url, userAgent)

    // 验证指纹管理器
    const verifyFp = douyinUtils.sign.VerifyFpManager()
    ```

    ### Cookie 与凭据 [#cookie-与凭据]

    普通 Fetcher 会规范化 Cookie 的空白、引号和 `UIFID_TEMP` 回退，但不会自动检测登录态或申请游客身份。下面的工具需要显式调用：

    ```ts verify
    import {
      normalizeDouyinCookie,
      resolveDouyinCredential,
      checkDouyinLoginState
    } from '@ikenxuan/amagi'

    declare const cookie: string
    // ---cut---
    const normalized = normalizeDouyinCookie(cookie)
    const credential = await resolveDouyinCredential(normalized.cookie, {
      noGuestFallback: true
    })
    const login = await checkDouyinLoginState(credential.cookie, { timeoutMs: 8000 })
    if (login.state === 'login') {
      console.log('已确认登录')
    }
    ```

    这些函数也在 `douyinUtils.credentials`、`amagi.douyin.credentials` 与 `client.douyin.credentials` 上提供短名称。它们是同一组工具，**实例上的工具也不自动绑定该 Client 的 Cookie、代理或 transport**；请显式传入 Cookie，以及需要的 `requestConfig`、`userAgent` 或 `send`。

    | 顶层导出                         | `credentials` 方法       | 用途                                                        |
    | ---------------------------- | ---------------------- | --------------------------------------------------------- |
    | `normalizeDouyinCookie`      | `normalizeCookie`      | 纯本地规范化，返回 Cookie 与 UIFID 来源                               |
    | `resolveDouyinCredential`    | `resolve`              | 解析凭据；`needLogin` 要求检测登录态，`noGuestFallback` 禁用游客握手         |
    | `checkDouyinLoginState`      | `checkLoginState`      | 返回 `login` / `guest` / `expired` / `unusable` / `unknown` |
    | `isDouyinCookieUsable`       | `isCookieUsable`       | 宽松可用性判断，`unknown` 也可能返回 `true`，不能替代登录确认                   |
    | `clearDouyinLoginStateCache` | `clearLoginStateCache` | 清空登录态检查缓存                                                 |
    | `mintDouyinGuestCookie`      | `mintGuestCookie`      | 显式申请游客 Cookie，失败返回 `null`                                 |
    | `configureDouyinGuestCache`  | `configureGuestCache`  | 显式指定持久化缓存文件；传 `null` 恢复内存模式并清缓存                           |

    `resolve` 的 `needLogin: true` 会探测登录态并将结果放入 `loginState`，不会在检测失败时自动变成游客。需要已登录身份的业务应显式检查 `loginState === 'login'`。

    游客握手会向抖音首页发两次请求：第一次拿服务端下发的 `__ac_nonce`，`__ac_signature` 在本地纯算（不下载、不执行页面脚本），第二次带上这一对换游客 Cookie。只有显式调用 `mintGuestCookie`，或允许 `resolve` 的游客回退时才进入这条路径。游客缓存默认仅在内存中，自定义请求配置和传输不会复用共享磁盘凭据。
  </Tab>

  <Tab value="快手">
    ```ts twoslash
    // v6 的 URL 构造器不在 utils 上 —— 从包顶层直接拿
    import { kuaishouApiUrls } from '@ikenxuan/amagi'

    // 获取结构化请求描述对象
    const request = kuaishouApiUrls.videoWork({
      photoId: '3xqxxxxxx'
    })
    ```

    ### 签名算法 [#签名算法-2]

    ```ts twoslash
    import { kuaishouApiUrls, kuaishouUtils } from '@ikenxuan/amagi'

    const request = kuaishouApiUrls.userInfoById({
      principalId: 'KPL704668133'
    })

    const signed = kuaishouUtils.sign.signLiveApiRequest(
      request,
      'kwfv1=your_cookie_value'
    )
    ```

    ### PC 搜索 [#pc-搜索]

    用户搜索与作品搜索可以使用有效的 PC 游客会话。只有本地生成的 `did` 或首页基础 Cookie，
    并不能保证搜索可用；请求的 Cookie 与 User-Agent 应配对配置。游客会话也不等于登录身份。

    * `fetchSearchUser`：默认目标 30 条。
    * `fetchSearchWorkList`：默认目标 20 条，实际每页数量由平台决定。
    * 两条搜索均接受 `keyword` 与可选的 `number`（1–500），自动翻页间隔为 10 秒。
    * 后续页业务失败时，已有结果保留在成功信封中，`meta.incomplete` 说明中断；若缺少分页会话，返回协议错误而不重新搜索。
    * `fetchLoginUserProfile({})` 获取当前账号资料，仍需登录，游客注册不会产生账号身份。
  </Tab>

  <Tab value="小红书">
    ```ts twoslash
    import { xiaohongshuUtils } from '@ikenxuan/amagi'

    // 生成 X-T 时间戳
    const xt = xiaohongshuUtils.sign.generateXT()

    // 生成 X-B3-Traceid
    const traceid = xiaohongshuUtils.sign.generateXB3Traceid()

    // 从 Cookie 中提取 a1
    const a1 = xiaohongshuUtils.sign.extractA1FromCookie('a1=xxx; webId=yyy')

    // 生成搜索 ID
    const searchId = xiaohongshuUtils.sign.getSearchId()
    ```

    ### X-S 签名 [#x-s-签名]

    ```ts twoslash
    import { xiaohongshuUtils } from '@ikenxuan/amagi'

    // 接口路径（不含域名）、cookie 里的 a1 值、完整 cookie 串
    declare const path: string
    declare const a1Cookie: string
    declare const cookies: string
    // 生成 X-S 签名 (GET 请求)：clientType 与 params 都可省略
    const xsGet = xiaohongshuUtils.sign.generateXSGet(path, a1Cookie, 'xhs-pc-web', { num: 30 })

    // 生成 X-S 签名 (POST 请求)：第四个参数是请求体
    const xsPost = xiaohongshuUtils.sign.generateXSPost(path, a1Cookie, 'xhs-pc-web', { note_id: '64xxxxxxxx' })

    // 生成 X-S-Common：入参是**完整 cookie 串**，不是长度
    const xsCommon = xiaohongshuUtils.sign.generateXSCommon(cookies)
    ```
  </Tab>
</Tabs>


# 快速开始 (https://ikenxuan.github.io/amagi/docs/v7/usage)

> 抖音、B站、快手、小红书 Web 端相关数据接口的 Node.js 封装与服务



<Callout type="info">
  本文档适用于 v7（发布状态见页顶横幅）。v6 正式版文档见 [v6 文档](/docs/v6/usage)，更早的 v5 文档见
  [仓库历史快照](https://github.com/ikenxuan/amagi/tree/e82440b04d599089fb743c418455a281ae57884b)。
</Callout>

<Callout>
  **本项目专为 [karin-plugin-kkk](https://github.com/ikenxuan/karin-plugin-kkk) 服务**

  amagi 作为 karin-plugin-kkk 的核心数据层，以 Git 子模块方式提供多平台数据获取能力。功能迭代主要围绕 karin-plugin-kkk 的业务需求进行。

  如需其他接口支持，请参考[开发文档](/docs/v7/dev)自行封装，或提交 Pull Request 贡献代码。
</Callout>

<Accordions>
  <Accordion title="致谢">
    反爬参数部分参考了以下项目的实现： - [SocialSisterYi/bilibili-API-collect](https://github.com/SocialSisterYi/bilibili-API-collect) -
    [NearHuiwen/TiktokDouyinCrawler](https://github.com/NearHuiwen/TiktokDouyinCrawler) -
    [Evil0ctal/Douyin\_TikTok\_Download\_API](https://github.com/Evil0ctal/Douyin_TikTok_Download_API) -
    [Johnserf-Seed/f2](https://github.com/Johnserf-Seed/f2) - [ikenxuan/xhshow-ts](https://github.com/ikenxuan/xhshow-ts)
  </Accordion>
</Accordions>

## 它能做什么 [#它能做什么]

* **覆盖四个平台**：抖音、B站、快手、小红书，收录了各平台主流的数据接口
* **两种用法**：在代码中直接调用方法，或用一行代码启动为本地 HTTP 服务
* **参数即时校验**：每个接口的参数都经 Zod 校验，漏填或填错会在请求发出前被指出
* **返回值格式统一**：无论哪个平台、哪个接口，返回的都是同一种结构。先判断 `success`，成功读取 `data`，失败读取 `error`
* **类型随接口而定**：返回值的类型即接口本身的类型，无需手动声明，也没有开关需要设置
* **内置常用工具**：签名算法、URL 拼接、AV/BV 号互转等
* **同时支持 ESM 与 CJS**

## 本节内容 [#本节内容]

<DocsCategory />

## 相关链接 [#相关链接]

* [GitHub 仓库](https://github.com/ikenxuan/amagi)
* [API 文档 (Apifox)](https://amagi.apifox.cn)
* [类型参考（Typescript API）](/docs/v7/usage/api/types)
* [NPM 包](https://www.npmjs.com/package/@ikenxuan/amagi)

<Callout type="info">
  本文档由 AI 辅助生成，可能存在描述不准确、示例代码过时或遗漏关键信息等问题。如发现错误或疑问，请以实际代码实现为准，或提交
  [Issue](https://github.com/ikenxuan/amagi/issues) 反馈。
</Callout>


# 安装 (https://ikenxuan.github.io/amagi/docs/v7/usage/installation)

> 安装 @ikenxuan/amagi



# 安装 [#安装]

## 使用包管理器安装 [#使用包管理器安装]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @ikenxuan/amagi
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @ikenxuan/amagi
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @ikenxuan/amagi
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @ikenxuan/amagi
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 系统要求 [#系统要求]

* Node.js >= 18.0.0
* 支持 ESM 和 CJS 两种模块系统

## 模块导入 [#模块导入]

<CodeBlockTabs defaultValue="ESM">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ESM">
      ESM
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="CommonJS">
      CommonJS
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ESM">
    ```ts twoslash 
    import amagi from '@ikenxuan/amagi'

    const client = amagi({ cookies: { bilibili: '' } })
    const video = await client.bilibili.fetcher.fetchVideoInfo({ bvid: 'BV1xx411c7mD' })

    if (video.success) console.log(video.data)
    ```
  </CodeBlockTab>

  <CodeBlockTab value="CommonJS">
    ```js
    // 双入口打包，CJS 侧的默认导出挂在 .default 上
    const amagi = require('@ikenxuan/amagi').default

    const client = amagi({ cookies: { bilibili: '' } })
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 子路径导出 [#子路径导出]

除了主入口，amagi 还提供了一些子路径导出：

```ts twoslash
// Express 相关
import express from '@ikenxuan/amagi/express'

// Axios 实例
import axios from '@ikenxuan/amagi/axios'

// 抖音签名与验证工具（纯函数，浏览器可跑）
import { decodeUrl, diagnoseSalt } from '@ikenxuan/amagi/signing'

// 反爬参数 step 工厂，按平台分命名空间（精细控制 client.<平台>.request 的签名）
import { douyin } from '@ikenxuan/amagi/sign-steps'
```

<Callout type="info">
  amagi 不依赖任何日志库：日志通过

  [事件系统](/docs/v7/usage/advanced/events)

  暴露，接一个监听器就能按自己的格式落地。
</Callout>


# 从 v6 迁移 (https://ikenxuan.github.io/amagi/docs/v7/usage/migration-v7)

> v6 → v7 的四处必改、一行切回 v6 语义的 /compat，以及完整迁移矩阵



# 从 v6 迁移 [#从-v6-迁移]

<Callout type="info">
  **成功与失败仍用 `r.success` 区分。** v7 需要调整错误分支、事件负载的读法，
  并删除 `typeMode`。需要保留旧错误信封时，可使用
  [`@ikenxuan/amagi/compat`](#四compat一行切回-v6-语义)。
  上游接口返回字段的变化仍需适配，见下方的小红书用户资料说明。
</Callout>

下面按「四处必改」逐条对照，完整矩阵在页尾。

## 一句话总结 [#一句话总结]

**成功分支的代码零改动，错误分支需要改读法。** 除此之外的破坏性变更都能靠
编译错误发现，且有兼容层兜底。

```ts
// 这段代码 v6 / v7 都成立
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id })
if (r.success) console.log(r.data)
```

***

## v7 接口补齐的兼容说明 [#v7-接口补齐的兼容说明]

本次增加抖音 `fetchMixAweme`，以及小红书 `searchUser`、`fetchSearchHotList`、`fetchSubComments`、`fetchLiveRoom`、`fetchLiveStatus`、`fetchLiveSquare`。裸 Fetcher、绑定 Fetcher 与 HTTP 路由均从同一注册表派生；旧方法保留。小红书用户搜索的公开名称为 `searchUser`，不是旧补丁中可能出现的 `fetchSearchUser`。

小红书 `fetchUserProfile` 改为 JSON 用户资料，平台原始响应的字段为 `data.basic_info`、`data.interactions`、`data.tab_public`。SDK 成功信封的 `result.data` 才是这份平台响应，因此应从 `result.data.data` 读取资料，并检查可选字段；原来的主页 HTML 初始状态路径不再适用。`fetchUserNoteList` 补全响应类型，主页 `xsec_token` 仍为必填。`fetchSubComments` 使用 `number` 自动分页；笔记搜索支持排序与类型筛选，手动翻页时复用搜索会话标识。详细参数见[小红书 SDK 参考](/docs/v7/usage/api/sdk/xiaohongshu)。

默认 JSON 解析会将超出安全整数范围的裸整数转为字符串，普通安全整数仍是数字，因此响应 ID 的类型可能为 `string | number`。大整数 ID 应按字符串传递，不要先用 `Number()` 转换。显式文本响应和自定义 `transformResponse` 由调用方控制；缺少完整响应样本的字段保留为 `unknown`，使用前应检查其结构。

小红书已收录端点在未提供 Cookie 时可自动初始化游客身份，并按客户端和请求配置缓存五分钟、合并并发初始化。显式传入 `web_session` 或 `userId` 却缺少 `a1` 时，会返回 `auth / COOKIE_MISSING`，请补充同一会话的完整 Cookie。

抖音新增 `credentials` 工具命名空间及对应顶层导出，用于显式处理 Cookie、探测登录态和申请游客凭据。实例上的该命名空间仍需显式传入 Cookie 与请求配置。现有 `login` 扫码会话入口不变，详见[工具集](/docs/v7/usage/guide/utilities)。

## 四处必改：前后对照 [#四处必改前后对照]

下面每一处都是「v6 写法 + 它在 v7 下报的真实编译错误」对上「v7 写法」——
「前」的报错是真实编译诊断，可以直接按错误码搜自己的代码。

### 一、默认导入的门面换成 v7 门面 [#一默认导入的门面换成-v7-门面]

`import amagi from '@ikenxuan/amagi'` 之后 `amagi(options)` 返回的**是 v7 门面**了
（`createAmagiClient` 变成它的 `@deprecated` 别名，而且是同一个函数对象）。
导出名一个没变、client 顶层的 8 个键一个没变，变的是 `events` / `on` / `once`
这条线：从 v6 的**全局单例**换成**实例级总线**，负载里的平铺字段全部搬进 `meta`。

TS 用户在这里是编译错误（B 档），JS 用户读到 `undefined`（A 档，没人拦）：

```ts twoslash
// @errors: 2339
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
client.on('api:success', (d) => {
  console.log(d.platform, d.methodType, d.duration)
})
```

v7 的读法 —— 三个字段各有归宿，另外 `meta` 带 `requestId` / `clientId`，
多实例并发时事件终于能归因（v6 的负载里没有任何关联 id）：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
client.on('api:success', (d) => {
  // methodType → endpoint，值也变了：videoWork → douyin.videoWork
  console.log(d.meta.platform, d.meta.endpoint, d.meta.durationMs)
  console.log(d.meta.requestId, d.meta.clientId)
})
```

换门面顺带带来一处纯新增：四个平台的实例上都有 `login` 命名空间（扫码登录会话），
B站另有 `refreshCredential`（Cookie 续期）：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const session = client.douyin.login.qrcode()
//    ^?

client.bilibili.login.qrcode()
client.kuaishou.login.qrcode()
client.xiaohongshu.login.qrcode()
```

### 保留但形状变化：默认导出的 client 换成 v7 门面（B 档） [#保留但形状变化默认导出的-client-换成-v7-门面b-档]

`import amagi from '@ikenxuan/amagi'` 之后 `amagi(options)` 拿到的**是 v7 门面**：
`createAmagiClient` 变成 `createClient` 的 `@deprecated` 别名，而且是**同一个函数对象**。

导出名一个都没变，变的是**返回值的形状**：

| 返回值上的东西                    | v6 门面                                        | v7 门面                                                                                                                                                                    | 破坏性                                              |
| -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| 顶层键                        | `startServer` `events` `on` `once` + 四个平台    | **一字不变**（同样 8 个键）                                                                                                                                                        | 无                                                |
| 四个平台                       | `{ ...utils, fetcher }`                      | 多一个 `login`（`qrcode()` / `resume()`），B站另多一个 `refreshCredential`；少一个键，见下行                                                                                                 | 新增无破坏；减少见下行                                      |
| 四个平台上的 v6 URL 构造器          | `client.<平台>.<平台>ApiUrls`（摊在 utils 里的 v6 那份） | **撤下**：v7 门面只摊 v7 那份（`client.<平台>.apiUrls`）。v6 那份仍可达：包顶层 `import { douyinApiUrls } from '@ikenxuan/amagi'` 照旧，`@ikenxuan/amagi/compat` 的 `client.<平台>.<平台>ApiUrls` 以原名保留 | **B 档**（TS 编译错误）/ **A 档**（JS 读到 `undefined`）     |
| `events` / `on` / `once`   | 全局单例 `amagiEvents`（12 个名字、v6 负载）             | **实例级** `EventBus`（15 个名字、负载带 `meta`）                                                                                                                                    | **B 档**（TS 编译错误）/ **A 档**（JS 读到 `undefined`）     |
| `startServer(port, opts)`  | 第二参 `{ openapi? }`                           | 第二参 `FacadeServerOptions`（`{ openapi?, listen? }`）                                                                                                                       | 无（放宽；`openapi` 行为一字不变）                           |
| `startServer` 的 `log:mark` | 发到**全局单例**，文案带 chalk 颜色                      | 发到**实例总线**，文案不带颜色                                                                                                                                                        | **A 档**，见下方                                      |
| 入参                         | `Options`（`{ cookies?, request? }`）          | `ClientOptions`（多一个 `debug?`）                                                                                                                                            | 无（放宽：`Options` 与 `ClientOptions` 赋值互通，v6 调用点零改动） |

入参这条顺带补上一个可达性缺口：`ClientOptions.debug` 此前只能经具名的
`createClient` 传，默认导入的人够不到。现在 `amagi({ debug: true })` 直接可用。
`Options` 本身**形状冻结不动**，仍在顶层导出面上。

**`log:mark` 是这次唯一的 A 档静默变化，单独记一笔。** v6 靠
`amagiEvents.on('log:mark', …)` 感知「服务起来了」的代码，换门面之后收不到了 ——
那条事件现在发在 `client.events` 上。迁移动作：把监听器挂到 `client.events` 上，
或者 `startServer` 之后自己打一行日志。

compat 入口（`@ikenxuan/amagi/compat`）跟着一起走：`compatCreateAmagiClient` 包的
仍是 `createAmagiClient`（也就是 `createClient`），**信封回填与「校验失败恢复抛出」
一字未改**，但它的 `client.events` 也跟着变成实例总线 —— compat 的职责是信封与
抛出语义，不含冻结整个 v6 门面；而全局单例上早已没有 `api:*` 的 emit 点
（只剩 `@deprecated` 的抖音 passport），继续指向它等于把一条死总线交给使用者。

### 二、信封读法：顶层 `code` 与 `error.amagiError` 都没了 [#二信封读法顶层-code-与-erroramagierror-都没了]

`AmagiResult<T>` 是判别联合，`success` 是**唯一**判别键。v6 那套
「顶层 `code` + `error.amagiError.errorDescription`」两个键在 v7 都不存在 ——
HTTP 状态在 `error.http.status`，平台业务码在 `error.platform.code`，
amagi 自己的错误码在 `error.code`：

```ts twoslash
// @errors: 2339
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '7419965435527974176' })
// ---cut---
if (!r.success) {
  console.error(r.code, r.error.amagiError.errorDescription)
}
```

v7 的读法：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '7419965435527974176' })
// ---cut---
if (r.success) {
  r.data // 收窄后是具体类型，不带 | undefined
} else {
  // kind 是 12 个大类之一，platform?.code 才是平台原文码
  console.error(r.error.kind, r.error.code, r.error.message, r.error.platform?.code)
}
```

不想写 `if` 也可以：**v7 的两支各带一个 `?: undefined` 对侧键**，所以不收窄直接读
`r.data` 是合法的（这就是 v6 的读法），代价是类型带 `| undefined`，访问其属性前需先处理：

```ts twoslash
// @errors: 18048
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '7419965435527974176' })

r.data.aweme_detail
```

数组回调里没有 `if` 可用，用顶层新增的 `isSuccess` / `isFailure` / `unwrap`；
四种读法的完整对比在[响应类型](/docs/v7/usage/guide/type-mode)。

<Callout type="warn">
  **信封永不 reject。** 参数校验失败在 v6 会 `throw`，v7 映射为 `success: false`
  —— v6 代码里的 `try/catch` 在 v7 下不进 catch，而是静默走到 else 分支。
  这是最容易踩的一条，需要人判断怎么处理失败分支。
</Callout>

### 放宽（1 条，非破坏）：信封两支各加一个 `?: undefined` 对侧键 [#放宽1-条非破坏信封两支各加一个--undefined-对侧键]

这个变更的方向是**编译错误变合法**，反向不成立 —— 原先能编译的代码照旧编译，
所以它不构成破坏性变更，但形状确实动了。

| 名字                                                             | 之前                                       | 之后                        | 破坏性                                                   |
| -------------------------------------------------------------- | ---------------------------------------- | ------------------------- | ----------------------------------------------------- |
| `AmagiSuccess<T>`                                              | `success` / `data` / `message` / `meta`  | 多一个 `error?: undefined`   | 无（放宽：`r.error` 从 TS2339 变成 `AmagiError \| undefined`） |
| `AmagiFailure`                                                 | `success` / `error` / `message` / `meta` | 多一个 `data?: undefined`    | 无（放宽：`r.data` 从 TS2339 变成 `T \| undefined`，即 v6 的读法）  |
| `isSuccess` / `isFailure`                                      | 不存在                                      | 顶层新增，类型守卫                 | 无（纯新增）                                                |
| `unwrap` / `AmagiThrownError`                                  | 不存在                                      | 顶层新增：失败即抛 + 抛出物的 Error 子类 | 无（纯新增）                                                |
| `AmagiResult` / `AmagiSuccess` / `AmagiFailure` / `AmagiError` | 顶层取不到                                    | 顶层类型导出                    | 无（纯新增，不进运行时公开面）                                       |

**运行时形状一个字节都没变**，这是与 v6 的分界线。v6 的错在**说谎**：
`SuccessResult` / `ErrorResult` 两支都声明 `data`（一支 `T`、一支 `never`），
声明成 `never` 却在运行时塞真值。v7 的对侧键运行时**根本不存在**，声明与
事实一致。

收窄能力没退化：`success` 仍是唯一判别键，`if (r.success)` 之后 `data` 是 `T`、
`else` 之后 `error` 是 `AmagiError`，都不带 `| undefined`。四种读法
（不收窄读 `data` / `if` 收窄 / `filter(isSuccess)` / `unwrap`）全部成立。

`unwrap` 与 `@ikenxuan/amagi/compat` 不重叠：`unwrap` 是 v7 的**单点显式选择**
（这一处调用想让失败抛就抛，返回类型是 `T`，抛的是带 `AmagiError` 全字段、
`cause` 不吞的 `AmagiThrownError`）；compat 是 v6 语义的**整体回填**（把返回值
换回带顶层 `code` 的 v6 信封）。要哪种语义选哪个，混用没有意义。

\{/\* 本小节未被任何页面 include，是贡献者向记录。 \*/}

### 需要人判断（C 档） [#需要人判断c-档]

只有两条，都提供兼容层：

**① 参数校验失败不再抛出**

```ts
// v6：校验失败走 catch
try {
  await client.douyin.fetcher.fetchVideoWork({ aweme_id: '' })
} catch (e) {
  console.error(e.message) // '抖音数据获取失败: ...'
}

// v7：校验失败走 else 分支，且带字段路径
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '' })
if (!r.success && r.error.kind === 'validation') {
  for (const i of r.error.issues!) console.error(i.path, i.message)
}
```

这是**最容易踩的一条**，因为 v6 代码里的 `try/catch` 在 v7 下不会进 catch，
而是静默走到 `if (r.success)` 的 else 分支 —— 如果那里没写处理就变成静默失败。
所以它属于 C 档且必须有兼容层。

**② 小红书风控 HTML 不再当成功**

v6 拿到 `<html>` 反爬页时 `return response`（成功透出）；
v7 判为 `kind: 'risk'` / `code: 'ANTIBOT_PAGE'`，原始 HTML 在 `error.raw`。

***

\{/\* 本小节未被任何页面 include，是贡献者向记录。 \*/}

### 三、`typeMode` 已删 [#三typemode-已删]

v6 的 `typeMode: 'strict' | 'loose'` 是「写了两万六千行类型、默认却返回 `any`」的
中间态。v7 只有一种类型模式，响应类型**始终**是端点声明里的具体类型，
参数因此多余 —— 传了是编译错误（对象字面量的多余属性检查）：

```ts twoslash
// @errors: 2353
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const r = await client.douyin.fetcher.fetchVideoWork({
  aweme_id: '7419965435527974176',
  typeMode: 'strict'
})
```

删掉参数即可，类型本来就是具体的：

```ts twoslash
import amagi from '@ikenxuan/amagi'

const client = amagi({ cookies: { douyin: '' } })
// ---cut---
const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '7419965435527974176' })

if (r.success) {
  r.data
  //^?
}
```

`TypeMode` / `TypeControl` / `ConditionalReturnType` / `ExtractTypeMode` 四个类型
一并删除（它们只在子路径导出，不在顶层）。原来靠 `typeMode: 'loose'` 拿 `any`
的地方改用三条逃生舱，见[响应类型](/docs/v7/usage/guide/type-mode)。

### 四、`/compat`：一行切回 v6 语义 [#四compat一行切回-v6-语义]

不想现在改的，把 import 换成 `@ikenxuan/amagi/compat` —— **只改这一行**，
信封回填成带顶层 `code` 的 v6 形状，参数校验失败恢复抛出。同一段 v6 代码，
默认入口下报两个 `2339`：

```ts twoslash
// @errors: 2339
import amagi from '@ikenxuan/amagi'
// ---cut---
const client = amagi({ cookies: { douyin: '' } })

try {
  const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '' })
  if (r.success) console.log(r.data)
  else console.error(r.code, r.error.amagiError.errorDescription)
} catch (e) {
  console.error('校验失败仍走这里', e)
}
```

换成 compat 入口之后，**函数体一个字符没动**，编译通过：

```ts twoslash
import amagi from '@ikenxuan/amagi/compat'
// ---cut---
const client = amagi({ cookies: { douyin: '' } })

try {
  const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '' })
  if (r.success) console.log(r.data)
  else console.error(r.code, r.error.amagiError.errorDescription)
} catch (e) {
  console.error('校验失败仍走这里', e)
}
```

<Callout type="warn">
  compat 覆盖的是**信封与抛出语义**，不含冻结整个 v6 门面：它的 `client.events`
  跟着换成了实例总线，所以上面第一条（事件负载读法）**在 compat 下也要改**。
  生命周期是 v7 全程保留、v8 移除。
</Callout>

## 兼容层：`@ikenxuan/amagi/compat` [#兼容层ikenxuanamagicompat]

一行切换，把 v7 信封回填成 v6 形状并恢复抛出行为：

```ts
// v6 写法完全不用改
import amagi from '@ikenxuan/amagi/compat'

const client = amagi({ cookies: { douyin: ck } })
try {
  const r = await client.douyin.fetcher.fetchVideoWork({ aweme_id: '' })
  if (r.success) use(r.data)
  else console.error(r.code, r.message, r.error.amagiError.errorDescription)
} catch (e) {
  /* 校验失败仍走这里 */
}
```

实现方式是一层薄包装，不复制业务逻辑。生命周期：&#x2A;*v7 全程保留，v8 移除。**
compat 入口在导入时打一次 `log:warn` 事件提示迁移，不刷屏。

> 兼容层刻意做成**单向、只读、无状态**的转换函数集合 ——
> 它不参与请求流程，只在返回前套一层。这样它不会成为第二套实现，
> 也不会因为忘了同步而与主路径漂移。

***

\{/\* 本小节未被任何页面 include，是贡献者向记录。 \*/}

## 迁移矩阵 [#迁移矩阵]

## 四种调用形态全部保留 [#四种调用形态全部保留]

| 形态              | v6                                                                 | v7 |
| --------------- | ------------------------------------------------------------------ | -- |
| client 实例       | `amagi({cookies,request}).douyin.fetcher.fetchVideoWork(o)`        | 不变 |
| 静态 fetcher      | `amagi.douyinFetcher.fetchVideoWork(o, ck, cfg)`                   | 不变 |
| 工厂              | `amagi.createBoundDouyinFetcher(ck).fetchVideoWork(o)`             | 不变 |
| HTTP / 事件 / 工具集 | `client.startServer(4567)` / `amagi.on(...)` / `amagi.douyin.sign` | 不变 |

新增（不影响旧写法）：`client.call('douyin.videoWork', params)`、
`client.endpoints(platform)`、`client.<platform>.login`。

***

## 新增 HTTP 路径 [#新增-http-路径]

v6 抖音 5 个作品 methodType（`parseWork` / `videoWork` / `imageAlbumWork` /
`slidesWork` / `textWork`）共用 `/fetch_one_work` 一条路由。
v7 拆成 5 条独立路由，**新增以下 4 条**：

| 新路径                       | 端点                      | 说明                 |
| ------------------------- | ----------------------- | ------------------ |
| `/fetch_video_work`       | `douyin.videoWork`      | 原 `videoWork`      |
| `/fetch_image_album_work` | `douyin.imageAlbumWork` | 原 `imageAlbumWork` |
| `/fetch_slides_work`      | `douyin.slidesWork`     | 原 `slidesWork`     |
| `/fetch_text_work`        | `douyin.textWork`       | 原 `textWork`       |

`parseWork` 保留原路径 `/fetch_one_work`，因此**旧 URL 依然可用**；其余四个
端点原来打的 `/fetch_one_work` 需要换成上表的新路径。同平台内路由唯一，
重复注册会在启动期直接抛错。

***

### 保留且形状不变（59 个） [#保留且形状不变59-个]

| 类别               | 导出                                                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 入口               | `default` `amagi` `CreateApp` `createAmagiClient`（名字全保留；**返回的 client 形状变了**，见下方「默认导出的 client 换成 v7 门面」）                |
| 静态 fetcher       | `douyinFetcher` `bilibiliFetcher` `kuaishouFetcher` `xiaohongshuFetcher`                                               |
| bound fetcher 工厂 | `createBound{Douyin,Bilibili,Kuaishou,Xiaohongshu}Fetcher`                                                             |
| 平台工具集            | `douyinUtils` `bilibiliUtils` `kuaishouUtils` `xiaohongshuUtils`                                                       |
| 路由工厂             | `create{Douyin,Bilibili,Kuaishou,Xiaohongshu}Routes`                                                                   |
| 签名               | `douyinSign` `kuaishouSign` `xiaohongshuSign` `wbi_sign` `qtparam` `av2bv` `bv2av` `parseDmSegMobileReply`             |
| URL 构造器          | `{douyin,bilibili,kuaishou,xiaohongshu}ApiUrls`（顶层导出本身一字不变；但**不再摊在 `client.<平台>` 与静态工具集上**，见「默认导出的 client 换成 v7 门面」一节） |
| passport         | `douyinPassport` `requestPassportQrcode` `checkPassportQrcode` `sendPassportVerifyCode` `validatePassportVerifyCode`   |
| 事件               | `amagiEvents` 与 12 个 `emit*`                                                                                           |
| 传输               | `fetchData` `fetchResponse`                                                                                            |
| 错误               | `ApiError` `ValidationError` `handleError`                                                                             |
| 平台常量类型           | `CommentType` `DynamicType` `MajorType` `AdditionalType`                                                               |

> **注意**：单个 fetcher 方法（`fetchVideoInfo` 等 80 个）**不在顶层导出**里
> —— 它们只能通过 fetcher 对象访问（`amagi.douyinFetcher.fetchVideoWork`）。
> 唯一例外是 4 个 passport 方法，v6 在入口里显式具名导出了它们；v7 沿用这
> 四个导出以免破坏。

全局单例 `amagiEvents` 与 12 个 `emit*` 自由函数**一个都没删、形状一字未改**。
但 v7 的 `client.events` 是**另一条总线**（实例级），名字对齐、负载换形，
逐条见下方「事件系统」一节。

### 保留但形状变化（8 个，B 档） [#保留但形状变化8-个b-档]

| 导出                                                                                                   | v6                                    | v7                              | 迁移动作                         |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------- | ---------------------------- |
| `validateDouyinParams` `validateBilibiliParams` `validateKuaishouParams` `validateXiaohongshuParams` | 抛 `ZodError`                          | 返回 `ValidateOutcome`，不抛         | 想保留抛出行为用 `assertValidParams` |
| `createSuccessResponse`                                                                              | `(data, message, code)`               | `(data, meta, message?)`        | 主要内部使用                       |
| `createErrorResponse`                                                                                | `(error, message, code, data)`        | `(error: AmagiError, meta)`     | 同上                           |
| `isNetworkErrorResult`                                                                               | 判 `{success:false, error.amagiError}` | 改判 `r.error.kind === 'network'` | 保留同名 deprecated 转发           |
| `getHeadersAndData`                                                                                  | 顶层导出，业务层直接用                           | 移入 transport，不再对外               | 需要响应头改用 `meta.trace`         |

以及类型层面的 `Result` / `SuccessResult` / `ErrorResult`
—— 顶层 `code` 删除、`error` 形状重做。

### 事件系统：实例总线的 12 个事件名与负载形状（A 档 / B 档） [#事件系统实例总线的-12-个事件名与负载形状a-档--b-档]

**两条总线并存，别当成一条**：

| 总线      | 怎么拿                               | 事件名                         | 负载                                      | 生命周期                 |
| ------- | --------------------------------- | --------------------------- | --------------------------------------- | -------------------- |
| v6 全局单例 | `amagiEvents`、`amagi.on(...)`（静态） | 12 个（`AmagiEventType`）      | v6 `*EventData`，带 `timestamp: Date`     | v7 全程保留、形状一字不改，v8 移除 |
| v7 实例总线 | `client.events`、`client.on(...)`  | 同样 12 个（`AmagiBusEventMap`） | v7 形状：带 `meta` / `trace`，没有 `timestamp` | v7 起就是这一条            |

实例总线的 12 个事件名都能 `on`，其中 10 个真的会发：`log:info` / `log:debug`
两个名字可以监听，但 v7 核心链路不产生它们（v6 唯一那处 info 日志在 v7 是
分页的正常终止条件，debug 日志则由 `partial: 'tolerate'` + `meta.trace` 取代）。

#### 负载形状：监听器搬家要改读法 [#负载形状监听器搬家要改读法]

| 事件名                            | v6 负载（全局单例，不变）                                                                                 | v7 实例总线负载                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `log:*` ×5                     | `{ level, message, args?, timestamp }`                                                         | `{ level, message, args?, meta? }`                                     |
| `http:request` `http:response` | `{ method, url, statusCode, responseTime, clientIP?, requestSize?, responseSize?, timestamp }` | `{ meta, trace }`                                                      |
| `http:error`                   | `NetworkErrorEventData`                                                                        | `{ meta, trace, status }`                                              |
| `network:retry`                | `{ errorCode, attempt, maxRetries, delayMs, url?, timestamp }`                                 | `{ meta, trace, code, errno?, status?, attempt, maxRetries, delayMs }` |
| `network:error`                | `{ errorCode, message, retries, url?, timestamp }`                                             | `{ meta, trace, code, errno?, message, attempts }`                     |
| `api:success`                  | `{ platform, methodType, response, statusCode, duration, timestamp }`                          | `{ meta, data }`                                                       |
| `api:error`                    | `{ platform, methodType, errorCode?, errorMessage, url?, duration?, timestamp }`               | `{ meta, error }`                                                      |

三处容易踩的差别：

1. **`platform` / `methodType` / `duration` / `statusCode` 都进了 `meta`**
   （`meta.platform` / `meta.endpoint`（全名，如 `douyin.videoWork`）/
   `meta.durationMs` / `trace[].status`），顶层读不到了。
2. **`timestamp: Date` 没有了。** 归因改用 `meta.requestId` / `meta.clientId`
   —— v6 的负载里没有任何关联 id，多实例并发时分不清事件是谁发的。
   与调用无关的日志（`log:mark`）本来就没有 `meta`。
3. **`network:*` 的 `errorCode` 拆成两个字段。** v6 的 `errorCode` 装的是传输层
   errno（`ECONNRESET`），v7 分成 `code`（`AmagiErrorCode`，如 `RATE_LIMITED`）
   与 `errno`（原样的 errno，拿到响应时没有）；`url` 去 `trace.url` 读。
   `network:error` 的 `retries`（重试了几次）换成 `attempts`（一共发了几次）。

破坏性分级：**TS 用户是 B 档**（负载类型变了，`d.platform` 直接编译错误），
**JS 用户是 A 档**（读到 `undefined`，没人拦）。两条总线的名字完全一样，
所以**判断依据是从哪儿拿的总线**，不是事件名。

类型名是 `AmagiBusEventMap` / `AmagiBusEventName` / `AMAGI_BUS_EVENT_NAMES`，
**不叫** `AmagiEventMap`：顶层已经有 v6 的同名类型，两个同名 interface 一起进
dts 会被打包器给其中一个加后缀。三个名字都已进公开面：前两个是 `export type`，
`AMAGI_BUS_EVENT_NAMES` 是运行时导出。11 个负载 interface 本身不逐个导出，
用 `AmagiBusEventMap['api:success']` 这样的索引访问取。

### 删除（79 个，B 档） [#删除79-个b-档]

| 导出                                                                                                                     | 数量 | 删除理由                                              |
| ---------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------------- |
| 逐个导出的 `*ParamsSchema`                                                                                                  | 41 | schema 归端点声明持有，不再逐个对外。需要时用 `client.endpoints()` 取 |
| `method-keys.ts`（4×3 组 `*InternalMethods` / `*FetcherMethods` / `*MethodToFetcher` + `MethodMaps` + `toFetcherMethod`） | 14 | 内部零引用                                             |
| `api-spec.ts`（4 个 `*ApiRoutes` + 4 个 `*MethodMapping` + `getApiRoute` + `getEnglishMethodName`）                        | 10 | 内部零引用；导出的路由表与真实服务完全不符，曾是一份错误的公开文档                 |
| `*MethodRoutes`                                                                                                        | 4  | 路由由端点声明持有                                         |
| `*ValidationSchemas`                                                                                                   | 4  | 同上                                                |
| `registerXxxRoutes`                                                                                                    | 4  | 与 `createXxxRoutes` 是同一函数的别名                      |
| `bilibiliErrorCodeMap` `isSmsCodeVerifyWay`                                                                            | 2  | 前者合并进 `bilibiliJudge`，后者收进会话引擎                    |

另外这些不在顶层导出、但在子路径导出的也一并删除：

* 4 个 `*APIErrorCode` 枚举（约 180 行）。`bilibiliAPIErrorCode` 是字符串枚举
  却用来比数字码（实测 `Object.values(...).includes(-101)` 为 `false`），
  `xiaohongshuAPIErrorCode` 是混合枚举导致 `Object.values()` 泄漏反向映射键。
  替代物是 `AmagiErrorCode` 字符串联合 + `error.platform.code`。
* `TypeMode` / `TypeControl` / `ConditionalReturnType` / `ExtractTypeMode`
* `overload-types.ts` 的 6 个重载类型别名（约 130 行）
* `platform/bilibili/sign/CorrespondPath.ts` / `dm_img.ts` /
  `types/ReturnDataType/Kuaishou/WorkComments.ts`（三个从未被导入的文件）

## 发布节奏 [#发布节奏]

| 版本           | 内容                                             | 破坏性       |
| ------------ | ---------------------------------------------- | --------- |
| 6.7.0        | 切环 + 契约下沉 + `wbi` 走 transport                  | 无         |
| 7.0.0-beta.x | 统一信封 + 会话抽象 + 删死码                              | 有，附本文档    |
| 7.0.0        | 稳定 + `compat` 子路径                              | 同上        |
| 7.1.0        | 端点注册表迁移完成（若选方案 A 混搭路径）                         | 无（对外形态不变） |
| 8.0.0        | 移除 `compat`；`startServer` 默认绑 `127.0.0.1`；语义视图 | 有         |