# 名单与套件制作指南

`lookup_groups.py` 的两个输入：群组**名单**（`--names`）和鉴权**套件**（`--bundles` / `--save-bundles`）。本指南说明怎么组织。

## 1. 群组名单（`--names`）

### 1.1 文件格式

- **json**：三种结构都支持。
  - 纯数组：`["名字1", "名字2"]`
  - 带表头的二维数组：`[["GROUP_NAME"], ["名字1"], ["名字2"]]`
  - 对象：`{"names": ["名字1", "名字2"]}`（也认 `group_names` / `groups` / `group_name`）
- **txt**：每行一个名字，空行自动忽略。
- **csv / xlsx**：读首个工作表，自动识别名字列（去空白转小写比对）。

### 1.2 自动识别的列名（别名）

`群组名称` / `群组` / `group_name` / `groupname` / `名称` / `name` / `实体名称` / `group name`。

- 有表头：首行表头命别名列，取该列后续所有行；首行不是表头且**单列**时整列当名字。
- 多列且首行无别名列：脚本报错「无法识别名字列」，改用别名列名或改成单列文件。
- 空值 / `nan` / `none` 自动跳过，名字按顺序去重。

### 1.3 示例

```csv
群组名称,备注
X 漫剧-1,
X 漫剧-2,重点
靓舟桃,
```

### 1.4 核对清单

- [ ] 明确要查的群组名，含必要的同名区分（如品牌名 + 序号）。
- [ ] 名字与页面上的 displayName 完全一致，否则只能进变体候选。
- [ ] csv/xlsx 用了别名列名或为单列文件。

## 2. 鉴权套件（`--bundles` / `--save-bundles`）

一个内容所有者对应一个**套件**，`bundles.json` 是套件数组。在线捕获（`--url` + `--save-bundles`）自动生成；也可手工维护。

### 2.1 结构

```json
[
  {
    "ownerId": "bqSUnNpU67xJ51TxH4PKpQ",
    "ownerDisplay": "FUTURE TV Co,Ltd",
    "url": "https://studio.youtube.com/youtubei/v1/yta_web/search_groups?alt=json",
    "headers": {
      "Authorization": "SAPISIDHASH ...",
      "Cookie": "...",
      "X-YouTube-Delegation-Context": "...",
      "...": "..."
    },
    "bodyTemplate": { "...": "...", "query": "" }
  }
]
```

### 2.2 关键字段

- `ownerId`：内容管理器的 id（约 18 字符 base62）。
- `headers`：约 12+ 个；**必须原样回放**，缺失任一（尤其 `Authorization`、`Cookie`、`X-YouTube-Delegation-Context`）都会 401。不要重造。
  - 回放时脚本会剥离长度/传输类头（`content-length`、`host`、`connection`、`transfer-encoding`、`accept-encoding` 等），由 requests 自算。
- `bodyTemplate`：请求体模板，含 `context.user.delegationContext.externalOwnerId`（锁定查询在哪个所有者名下）与 `serializedDelegationContext`。**回放只改 `query`**，其余一律不动。

### 2.3 多所有者

- 逐个所有者页面各捕获一份套件，合并进同一个 `bundles.json`。
- 同名 ownerId 以最新捕获为准（`--save-bundles` 会与 `--bundles` 读入的合并后写盘）。
- 查询时按 `bundles.json` 中的顺序逐个所有者尝试，**首个精确命中即停**。

### 2.4 核对清单

- [ ] `headers` 含 Authorization / Cookie / X-YouTube-Delegation-Context。
- [ ] `bodyTemplate` 的 `externalOwnerId` 与 URL ownerId 一致（不一致以请求体为准，脚本会打警告）。
- [ ] 每个所有者都有独立套件，不混用。
- [ ] 套件有效期：鉴权头是页面逐请求计算的，过期需重新 `--url` 捕获。

## 3. 产物核对

- 结果列：`group_name / ownerid / owner_display / groupid / 备注`。
- `groupid` 非空 = 精确命中；其 `ownerid + owner_display` 即归属所有者。
- `groupid` 为空时看「备注」：候选（`名=ID`）或各所有者线索（HTTP/网络错/无结果）。
- 行数应与名单一致（含重复项已去重后的名字数）。