# ima-bot

**Repository Path**: oyuer/ima-bot

## Basic Information

- **Project Name**: ima-bot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImaBot - 腾讯 IMA 知识库批量下载工具

## 

```

```

## 原理

### IMA 应用架构

腾讯 IMA (ima.copilot) macOS 客户端本质上是一个 **魔改版 Chromium** (v138)，内置了 17 个 Chrome 扩展。知识库功能由扩展 `nkohmbngmopdajidckglcoehlaeepeoi` (IMA知识库 v4.15.9) 提供。

### 认证机制

IMA **不使用** 标准浏览器 Cookie 存储认证信息。认证流程如下：

1. 用户登录后，Token 存储在**原生层**（非浏览器 Cookie DB）
2. 扩展通过 `chrome.runtime.invokeWithPromise({action: "getAccountInfo"})` 从原生层获取认证信息
3. 扩展构造 `x-ima-cookie` 请求头，包含所有认证字段
4. 每个 API 请求携带 `x-ima-cookie` + `x-ima-bkn`（Token 的哈希校验值）

Cookie 格式：
```
PLATFORM=H5; CLIENT-TYPE=256020; WEB-VERSION=4.15.9;
IMA-GUID=...; IMA-Q36=...; IMA-IUA=...;
IMA-UID=<用户ID>; IMA-TOKEN=<认证Token>;
IMA-REFRESH-TOKEN=...; UID-TYPE=2; TOKEN-TYPE=14
```

### BKN 校验算法

```python
def calc_bkn(token):
    h = 5381
    for ch in token:
        h += (h << 5) + ord(ch)
        h &= 0xFFFFFFFF
    return h & 0x7FFFFFFF
```

### API 结构

- 基础 URL: `https://ima.qq.com/cgi-bin/{service}/{endpoint}`
- 方法: 全部 POST，JSON body
- 请求 body: snake_case
- 必要 Header: `Content-Type`, `x-ima-cookie`, `x-ima-bkn`, `from_browser_ima`, `extension_version`

关键端点：
| 端点 | 用途 |
|------|------|
| `knowledge_tab_reader/get_home_page_data` | 获取所有知识库分组列表 |
| `knowledge_tab_reader/get_knowledge_list` | 获取某个知识库的条目列表（分页） |
| `knowledge_tab_reader/get_knowledge` | 获取单条目详情，含签名下载 URL |

### Cookie 获取原理

由于认证信息在原生层，无法直接读取。本工具通过 **Chrome DevTools Protocol (CDP)** 捕获：

1. 以 `--remote-debugging-port=9222` 启动 IMA
2. 通过 WebSocket 连接到知识库扩展页面
3. 启用 `Network.enable` 监听网络请求
4. 触发 `Page.reload` 让扩展重新发起 API 调用
5. 从 `Network.requestWillBeSent` 事件中提取 `x-ima-cookie` 头

## 安装

```bash
pip3 install requests websocket-client
```

## 使用方法

### 第一步：获取 Cookie

**方法 A - 自动抓取（推荐）**

先启动 IMA（带调试端口）：
```bash
/Applications/ima.copilot.app/Contents/MacOS/ima.copilot \
  --remote-debugging-port=9222 --remote-allow-origins=*
```

等 IMA 完全启动并登录后，运行：
```bash
cd ~/WorkShop/ImaBot/Script
python3 grab_cookie.py
```

或者让脚本自动启动 IMA：
```bash
python3 grab_cookie.py --launch
```

**方法 B - 手动**

如果自动抓取失败，可以手动通过浏览器 DevTools：
1. 启动 IMA（带调试端口，同上）
2. 浏览器打开 `chrome://inspect` 或 `http://127.0.0.1:9222`
3. 在知识库页面的 Network 面板中找任意 `ima.qq.com` 请求
4. 复制 `x-ima-cookie` 请求头的值
5. 保存到 `Script/ima_cookie.txt`

### 第二步：下载知识库

**交互模式（推荐）** - 列出所有知识库，选择要下载的：
```bash
cd ~/WorkShop/ImaBot/Script
python3 ima_kb_download.py --cookie-file ima_cookie.txt
```

**按名称模糊匹配：**
```bash
python3 ima_kb_download.py --cookie-file ima_cookie.txt --name 火电
```

**按 ID 下载：**
```bash
python3 ima_kb_download.py --cookie-file ima_cookie.txt --kb-id 7322517261805609
```

**仅列出知识库（不下载）：**
```bash
python3 ima_kb_download.py --cookie-file ima_cookie.txt --list
```

**下载全部：**
```bash
python3 ima_kb_download.py --cookie-file ima_cookie.txt --all
```

### 参数说明

| 参数 | 说明 |
|------|------|
| `--cookie-file` | Cookie 文件路径（推荐） |
| `--cookie` | 直接传入 Cookie 字符串 |
| `--output` | 输出根目录，默认 `../ImaKnowledge` |
| `--list` | 仅列出所有知识库 |
| `--name` | 按名称模糊匹配下载 |
| `--kb-id` | 按 ID 下载指定知识库 |
| `--all` | 下载全部知识库 |

## 防重复下载机制

下载记录保存在 `ImaKnowledge/.ima_manifest.json` 中，记录每个已下载文件的：
- 知识库 ID + 条目 ID（唯一键）
- 文件大小
- 下载时间
- 本地路径

再次运行时，已下载的条目会自动跳过。即使 manifest 文件丢失，脚本也会检查本地文件大小来判断是否需要重新下载。

## 注意事项

1. **Cookie 有效期**：IMA Token 会过期，过期后需要重新抓取。如果下载时出现认证错误，重新运行 `grab_cookie.py` 即可。

2. **大文件知识库**：部分共享知识库非常大（如电网电力知识库 26GB、热能动力 30GB），下载前请确保磁盘空间充足。

3. **文件夹 (type_99)**：部分共享知识库包含文件夹结构，当前版本会列出文件夹但不会递归下载其中内容。

4. **加入的共享知识库上限**：首页接口最多返回 10 个「我加入的共享知识库」，如果你加入了超过 10 个，多出的暂时不会显示。

5. **网络限制**：请求之间有 0.2-0.3s 的间隔以避免触发限流。大文件下载超时设为 300s。

6. **安全提醒**：`ima_cookie.txt` 包含认证凭据，请勿提交到 git 或分享给他人。

## 文件类型对照

| media_type | 类型 | 默认扩展名 |
|-----------|------|-----------|
| 1 | PDF | .pdf |
| 2 | Word | .docx |
| 3 | Excel | .xlsx |
| 4 | PPT | .pptx |
| 5 | TXT | .txt |
| 6 | 图片 | .png |
| 7 | Markdown | .md |
| 8 | 音频 | .mp3 |
| 9 | 视频 | .mp4 |
| 10 | 网页 | .html |
| 11 | 笔记 | .md |
| 12 | AI问答 | .txt |
| 99 | 文件夹 | - |