# cookie-injection-plugin

**Repository Path**: MaoSuyu_admin/cookie-injection-plugin

## Basic Information

- **Project Name**: cookie-injection-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cookie Studio

一个面向当前网站的 Chrome Cookie 图形化工具。可以一键读取并查看当前站点的 Cookie（含 HttpOnly），复制全部 Cookie 请求头文本或导出 TXT 文件；也可以粘贴原来的 Cookie 脚本、数组或请求头，核对名称和值后写入并刷新页面，无需打开开发者工具。

开发者入口：[工程文档索引](docs/index.md) · [架构地图](ARCHITECTURE.md) · [API 与数据契约](docs/api.md) · [开发与验证](docs/development.md)

本项目参考 [OpenAI Harness Engineering](https://openai.com/zh-Hans-CN/index/harness-engineering/)，
将工程知识、历史决策与可执行检查保存在仓库中；对应实践与取舍见 [工程实践映射](docs/engineering-practices.md)。

## 界面预览

截图中的网站及 Cookie 均为虚构测试数据。

**读取并查看当前站点 Cookie：**点击「显示值」查看内容，展开每项属性可查看域名、路径、HttpOnly 等详情。

![Cookie Studio 示例：读取当前站点 Cookie 并查看属性](docs/images/cookie-studio-read.png)

**编辑与注入：**核对列表和注入设置后写入，成功结果逐项显示。

![Cookie Studio 示例：编辑 Cookie、设置属性并查看注入结果](docs/images/cookie-studio-example.png)

## 安装

需要 Chrome 109 或更新版本。

1. 如果拿到的是 ZIP 压缩包，先将它解压到一个固定文件夹。不能直接选择 ZIP 安装。
2. 在 Chrome 地址栏打开 `chrome://extensions`。
3. 打开右上角的「开发者模式」。
4. 点击「加载已解压的扩展程序」，选择**包含 `manifest.json` 的文件夹**。如果直接使用本项目，选择当前项目文件夹即可。
5. 在浏览器右上角的扩展程序菜单中，固定 **Cookie Studio**，方便之后点击图标使用。

安装和使用不需要运行 npm，也不需要启动服务器。更新文件后，在扩展程序管理页点击本扩展的刷新按钮即可。

## 查看当前站点 Cookie

1. 打开目标网站，点击 Cookie Studio 图标。
2. 点击顶部的「读取当前站点 Cookie」。首次读取时，在 Chrome 提示中允许访问当前主机及其站点父域，例如 `www.instagram.com` 和 `instagram.com`。这是 Chrome 读取父域 Cookie 所需的权限。
3. 读取结果会替换「编辑列表」，值默认隐藏；点击「显示值」查看完整值。展开每项下方的属性可查看 Domain、Path、Secure、HttpOnly、SameSite 和有效期等信息。
4. 普通 Cookie 可以修改名称和值，再点击「注入 Cookie」写回。读取时会自动开启「优先使用导入数据的属性」，保留其原域名、路径和有效期；需要统一使用右侧设置时可取消勾选。
5. 点击「复制所有 Cookie」将当前列表的请求头文本复制到剪贴板，或点击「导出 Cookie」下载 `.txt` 文件。两者都包含当前列表中的全部条目，包括未勾选项和只读分区项；已从列表删除的条目不会包含在内。

读取本身不会写入 Cookie 或刷新网页。列表中的删除按钮只移除本次编辑条目，不会删除浏览器中已有的 Cookie。再次读取会替换当前列表；读取失败或权限被拒绝时保留原列表，成功读取到空结果时清空列表。

**读取范围：**按当前标签页的完整 URL 匹配，包含适用于该 URL 的当前主机、父域和 HttpOnly Cookie；路径不匹配的 Cookie 不会显示。例如 Path 为 `/account` 的 Cookie 需要在 `/account` 或其子路径页面读取。读取使用当前标签页的 Cookie 存储区，支持已允许扩展运行的无痕窗口。

分区 Cookie 会按当前页面的顶层站点分区读取，可以查看其值和分区属性，标记为「仅查看」，不会参与全选或注入；不会读取其他顶层站点的分区 Cookie。旧版 Chrome 如果缺少分区读取接口，插件会提示仅显示普通 Cookie。关闭弹窗后，本次读取的数据也会清空。

## 复制与导出

读取成功后，在「编辑列表」中使用「复制所有 Cookie」或「导出 Cookie」。导入或手动添加的列表也可以使用这两个按钮；列表为空或正在执行操作时不可用。

复制和导出使用相同的单行 Cookie 请求头值，例如：

```text
demo_session=synthetic%3Avalue; theme=light; demo_padding=a=b==
```

输出按当前列表顺序，用 `; ` 连接 `名称=值`，不去重同名条目，不添加 `Cookie:` 前缀、引号、结尾分号或换行。名称和值反映当前编辑结果，百分号编码、下划线和值中的等号原样保留；空值输出为 `名称=`。**即使界面仍隐藏值，复制内容和文件也包含完整 Cookie 值**。名称无效或值含分号、控制字符时，会提示修正对应条目后再操作。

这是请求头文本，不包含 Domain、Path、Secure、HttpOnly、SameSite、有效期、存储区或分区属性。重新粘贴导入只能恢复名称和值，无法识别原来的分区 Cookie，也不能作为属性备份；写入时需要核对注入设置。导入仍受 300 条、1 MB 等现有校验限制，复制和导出不采用这两个容量限制。

复制与导出只处理当前列表，不会重新读取、写入 Cookie 或刷新网页，右侧注入设置也不会改变输出。复制失败会保留列表并允许重试，也可以使用「导出 Cookie」。

插件不会自动保存草稿或上传数据。主动复制后，数据由系统剪贴板管理；主动导出的 TXT 文件由浏览器下载到本机，关闭弹窗不会删除这些内容。

## 导入和注入

1. 打开需要写入 Cookie 的目标网站，例如 `https://www.instagram.com/`。
2. 点击 Cookie Studio 图标，确认顶部显示的是目标网站。
3. 在「粘贴导入」中粘贴原来的**整段脚本**，或其他支持的格式。
4. 点击「解析 Cookie」。在「编辑列表」中核对、修改名称和值；可以添加、删除条目，或取消勾选不需要写入的条目。值默认隐藏，可点击「显示值」查看。
5. 核对右侧「注入设置」，点击「注入 Cookie」。首次写入该网站时，在 Chrome 提示中允许访问当前网站。
6. 查看写入结果。默认勾选「全部成功后刷新页面」，只有所选条目全部写入成功才会自动刷新；也可以取消勾选。

**复现原来 `.instagram.com` 的写法：**在 Instagram 网页打开插件，将 Domain 改为 `.instagram.com`，Path 保持 `/`，开启 Secure，SameSite 选择 Lax，HttpOnly 保持关闭，有效期选择「当前会话」。

插件只从脚本中读取 `cookies` 数组，**不会执行后面的 `document.cookie`、`forEach` 或 `location.reload()`**。脚本里的 `domain`、`path`、`Secure`、`SameSite` 等设置也不会自动继承，请在右侧填写。百分号编码的值会原样保留，不会解码或再次编码。

## 注入设置

| 设置 | 默认值与作用 |
| --- | --- |
| Domain | 默认当前网页的主机名。可填写当前主机或其父域，例如在 `www.instagram.com` 填写 `.instagram.com`。留空表示仅当前主机。不能填写其他网站、协议或路径。 |
| Path | 默认 `/`，适用于站点全部路径。 |
| SameSite | 默认 Lax；可选 Strict、None 或未指定。None 需要同时启用 Secure。 |
| Secure | HTTPS 页面默认开启，HTTP 页面默认关闭。开启后只能在 HTTPS 页面写入。 |
| HttpOnly | 默认关闭。开启后，网页 JavaScript 不能通过 `document.cookie` 读取该 Cookie。 |
| 有效期 | 默认当前会话，也可选择 1 天、7 天、30 天或 1 年（365 天）。浏览器会话恢复功能可能保留会话 Cookie。 |
| 优先使用导入数据的属性 | 默认开启。导入对象中的属性优先，缺少的属性使用右侧设置。关闭后，统一使用右侧设置。 |

导入对象支持 `domain`、`path`、`secure`、`httpOnly`、`sameSite`、`expirationDate`、`hostOnly` 和 `session`。其中 `expirationDate` 是 Unix 时间戳，单位为秒；导入的过期时间必须在未来。`session: true` 表示会话 Cookie，会忽略该条的过期时间。保留 `hostOnly: true` 时，只能写入原始主机。

## 支持的输入格式

以下都是虚构示例；插件没有内置任何真实账号或会话值。

**原来的完整脚本：**

```javascript
const cookies = [
  ["demo_session", "synthetic%3Avalue"],
  ["demo_csrf", "synthetic_csrf_value"]
];
cookies.forEach(([k, v]) => {
  document.cookie = `${k}=${v}; path=/; domain=.instagram.com; Secure; SameSite=Lax`;
});
location.reload();
```

支持 `const`、`let` 或 `var cookies = [...]`，也支持首部注释、单双引号和常见 JavaScript 字符串转义。数组必须直接包含数据，不能用函数调用、变量引用或其他表达式生成。

**二维数组：**

```json
[
  ["demo_session", "synthetic%3Avalue"],
  ["theme", "light"]
]
```

**Cookie 请求头：**

```text
Cookie: demo_session=synthetic%3Avalue; theme=light; demo_padding=a=b==
```

`Cookie:` 前缀可以省略。每项在第一个等号处分开，所以值中的等号会保留。这里接收的是请求头 `Cookie`，不是带 `Path`、`Domain` 等属性的响应头 `Set-Cookie`。

**常见导出对象数组：**

```json
[
  {
    "name": "demo_session",
    "value": "synthetic_value",
    "domain": ".instagram.com",
    "path": "/",
    "secure": true,
    "httpOnly": true,
    "sameSite": "Lax",
    "session": true,
    "hostOnly": false
  }
]
```

一次最多导入 300 条，输入上限为 1 MB。格式错误会提示具体条目，不会跳过错误条目继续导入。名称、域名和路径相同的重复项会给出提醒，并按列表顺序写入，后面的值覆盖前面的值。

当前版本支持查看分区 Cookie，但不支持导入或注入分区 Cookie：导入对象带非空 `partitionKey` 或 `partitioned: true` 时会明确报错。复制和 TXT 导出只输出名称和值，没有分区标记；重新导入该文本时无法恢复分区身份。其他不支持的导入字段（如 `id`、`storeId`）不会用于写入；实际使用的是当前标签页对应的 Cookie 存储区。

## 数据与权限

- 读取、输入、解析和编辑都在扩展弹窗内本地完成，没有上传接口，也不自动持久化保存 Cookie 内容；仅在你点击复制或导出时写入系统剪贴板或下载本地 TXT 文件。
- 关闭弹窗后，本次粘贴内容和编辑列表会清空。**已经写入网站的 Cookie 不会随弹窗关闭而删除**，它们由 Chrome 按有效期管理。
- 点击读取或注入时才会请求网站访问权限。读取会申请当前主机及其可设置 Cookie 的站点父域，例如 `www.instagram.com` 和 `instagram.com`，仍仅查询适用于当前 URL 的 Cookie；不会申请所有网站或通配子域权限。Chrome 会记住已授予的权限，可以在扩展程序管理页调整。
- HTTPS 页面的读取权限会同时包含上述主机的 HTTP 和 HTTPS，以便 Chrome 返回 Secure 和非 Secure Cookie；HTTP 页面只申请 HTTP 权限。
- 在隐身窗口使用时，需要先进入扩展程序「详情」，打开「在无痕模式下启用」。插件会使用当前隐身标签页对应的 Cookie 存储区。

## 常见问题

**读取时报 `Only permissions specified in the manifest may be requested.`。** 这是 1.1.0 的首次权限申请兼容问题：清单分别声明 HTTP 和 HTTPS，但读取使用了合并的 `*://` 模式。1.1.1 已改为分别申请两种协议。更新扩展文件后，在 `chrome://extensions` 点击本扩展的刷新按钮，重新打开插件再读取。

**在新标签页或 `chrome://` 页面无法使用。** 先打开目标网站的 HTTP 或 HTTPS 页面。浏览器内部页面、扩展页面和本地文件不支持注入。

**读取的 Cookie 比开发者工具中少。** 插件按当前 URL 的主机、路径和协议匹配 Cookie。开发者工具可能同时显示该站点其他路径的 Cookie；请打开对应路径后重新读取。

**提示 Domain 不匹配。** 确认当前网页和 Cookie 所属网站一致。Domain 只能是当前主机或其父域；例如在 Instagram 页面不能写入其他网站的 Cookie。

**提示 SameSite 或 Secure 设置不兼容。** `SameSite=None` 必须开启 Secure，并在 HTTPS 页面操作。以 `__Host-` 开头的 Cookie 还要求 Domain 留空、Path 为 `/`。

**导入对象的属性覆盖了右侧设置。** 取消勾选「优先使用导入数据的属性」后重新注入。例如，可以借此重新设置已过期的导入时间，但这不会让服务器上已经失效的会话恢复有效。

**部分写入失败。** 先按结果提示修正。写入前的整批校验失败时不会写入任何条目；如果是 Chrome 在实际写入时拒绝某项，其他条目可能已经成功写入，此时不会自动刷新。

**显示写入成功，但仍然没有登录。** 写入成功只代表 Chrome 接受了 Cookie。服务器可能已使会话失效，或要求其他登录数据、设备验证、风控检查。扩展只能写入 Cookie，不能保证恢复登录状态。

## 开发验证

开发工具需要 Node.js 22 或更新版本。在项目文件夹运行：

```sh
npm run validate
npm run package:release
```

项目没有第三方运行依赖，不需要执行 `npm install`。`validate` 汇总语法、结构/文档、PSL 生成物和单元测试检查。
`package:release` 输出 `dist/Cookie-Studio-v<版本>.zip`，包含带注释的源码及文档。安装插件本身不需要 Node.js。

另附可选的真实浏览器测试 `tests/browser-smoke.mjs`，需要 Playwright 和 Chrome 152 或更新版本（测试使用新版 Chrome 的扩展调试接口；插件本身最低支持 Chrome 109）：

```sh
npm run test:browser
npm run test:permissions
```

测试会创建并删除临时 Chrome 配置，用虚构域名和拦截的本地页面验证真实 Cookie API，不读取已有浏览器配置。可通过 `CHROME_PATH` 指定 Chrome 可执行文件、`PLAYWRIGHT_MODULE` 指定现有 Playwright 模块。

浏览器集成检查覆盖加载和当前站点识别、整段脚本安全解析、父域/编码/Secure/HttpOnly 写入与刷新、读取 Secure 与非 Secure Cookie、URL 路径匹配、分区 Cookie 仅查看、空结果和读取错误处理、错误域名整批拦截、编辑与选中项写入、运行时部分失败、失败重导入清空、权限拒绝、重新打开清空。

独立的首次权限申请检查使用未修改的正式清单和全新 Chrome 配置，不预先授予网站权限，验证点击读取后能通过 Chrome 的清单校验并进入等待原生授权的状态。

浏览器自动化中的临时扩展副本预先授权了虚构测试子域及其父域；权限拒绝和读取 API 错误分支使用模拟返回，普通 Cookie 的读写、当前页面分区 Cookie 的读取及只读保护使用真实 Chrome 数据。正式安装包仍在点击读取或注入时由 Chrome 请求网站授权。真实账号登录效果取决于站点和会话状态。

## 域名规则数据

为准确识别站点父域，项目内置 [Public Suffix List](https://publicsuffix.org/list/) 的 ICANN 和 PRIVATE 规则，避免将 `co.uk`、`github.io` 等公共后缀当作可申请的站点父域。原始文件为 `vendor/public_suffix_list.dat`，保留 MPL-2.0 许可证说明；浏览器使用预先生成的本地规则，运行时不下载数据。

更新原始列表后运行 `npm run generate:suffix-rules`，再运行单元测试和浏览器检查。

模块接口、命令选择、调试方式、CI 范围与发布步骤见 [开发文档](docs/development.md)，
当前验证证据与待办见 [质量记录](docs/quality.md)。