# Profiles

## 配置文件列表

`GET /profiles`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "配置文件列表",
  "description": "返回永久配置文件（临时文件隐藏），按从新到旧排序，\n已置顶的排在最前。每条记录附带当前运行状态。\n",
  "responses": {
    "200": {
      "description": "配置文件列表。",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfileListItem"
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 创建配置文件

`POST /profiles`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "创建配置文件",
  "description": "将客户端传入的 `fingerprint` 对象**原样**保存为配置文件\n（不进行重新随机化; 唯一化已在 `/fingerprint/new` 完成）。\n使用 `folder` 将配置文件放入文件夹；通过存储中的 `proxy_id`\n或内联的 `proxy`（字符串，**不**保存到代理存储）绑定代理。\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已创建配置文件的元数据。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        }
      }
    },
    "400": {
      "description": "缺少 `fingerprint` 或其不是对象，或代理字符串无法解析。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 创建临时配置文件

`POST /profiles/temporary`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "创建临时配置文件",
  "description": "从库中随机（或指定）指纹创建配置文件，唯一化方式与\n`/fingerprint/new` 相同，原样保存，带 `temporary` 标志：\n在列表和界面中隐藏，浏览器关闭后**自动删除**（含数据文件夹，\n或在崩溃后下次启动时删除）。\n配合 `POST /profiles/{id}/start` 使用。\n",
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TempProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已创建的临时配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "fingerprint_id": {
                "type": "string",
                "description": "生成该配置文件所基于的库条目。"
              },
              "temporary": {
                "type": "boolean",
                "example": true
              },
              "proxy_inline": {
                "type": "boolean",
                "description": "是否附加了内联代理。"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "无法解析的代理字符串，或未知的噪声向量。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "未找到匹配指纹 / 库为空。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 获取配置文件

`GET /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "获取配置文件",
  "description": "返回完整的已保存配置文件：`_meta` 包装层加上\n展开的 FingerprintConfig。若配置文件正在运行; \n附带 `running` 和 `cdp`。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "已保存的配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StoredProfile"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "未找到配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 删除配置文件

`DELETE /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "删除配置文件",
  "description": "将配置文件移入回收站，可在 7 天内恢复，过期后自动清理。归档内容包括账户数据、cookies、登录信息、网页数据、偏好设置、Local Storage 和 IndexedDB，不包括缓存，因此归档仅占用户数据目录的一部分。创建归档后，原始配置和用户数据目录会被删除。\n\n临时配置文件在浏览器关闭时由进程跟踪器删除，不会进入回收站。",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "配置文件已移至回收站。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "deleted": {
                "type": "boolean",
                "example": true
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "trashed": {
                "type": "boolean",
                "example": true,
                "description": "可在 7 天内从回收站恢复。"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "删除时出错。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 编辑配置文件

`PATCH /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "编辑配置文件",
  "description": "仅更新传入的字段。若传入 `fingerprint`; 它将**原样替换**\n已保存的指纹（不重新随机化）。\n`folder: \"\"` 将配置文件移出文件夹；`proxy_id: \"\"` 解绑代理；\n代理 `proxy` 字符串保存（去重）+ 完整测试，然后绑定。\n返回更新后的配置文件。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EditProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "更新后的已保存配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StoredProfile"
          }
        }
      }
    },
    "400": {
      "description": "无效的 fingerprint（非对象）或无法解析的代理。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "未找到配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 启动配置文件（含 CDP）

`POST /profiles/{id}/start`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "启动配置文件（含 CDP）",
  "description": "为配置文件启动启用了 remote-debugging 的 ShardX 浏览器，\n通过绑定代理填充 `auto` 字段（时区/语言/地理位置），\n并在 Chrome 写入 DevToolsActivePort 后返回 CDP 端点。\nCDP **仅**在通过 API 启动时启用（通过界面启动不开放调试端口; \n反检测能力不受影响）。\n若在超时内无法读取端点，`cdp` 返回 `null`。\n适用于普通配置文件和临时配置文件。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": false,
    "description": "可选。空请求体以图形界面模式启动。",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "headless": {
              "type": "boolean",
              "default": false,
              "description": "以 headless 模式启动（--headless=new）。"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已启动。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "profile_id": {
                "type": "string"
              },
              "pid": {
                "type": "integer",
                "format": "int64",
                "description": "操作系统进程 PID。"
              },
              "headless": {
                "type": "boolean"
              },
              "cdp": {
                "nullable": true,
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CdpInfo"
                  }
                ]
              },
              "cdp_error": {
                "type": "string",
                "nullable": true,
                "description": "为什么 `cdp` 为空，当它是时。否则缺席。"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "未配置二进制文件 / 无法启动进程。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 停止配置文件

`POST /profiles/{id}/stop`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "停止配置文件",
  "description": "向浏览器发送 graceful shutdown 信号（Unix 上为 SIGTERM；等待 5 秒，\n然后发送 SIGKILL）。临时配置文件在关闭过程中被删除。\n若配置文件未运行，`stopped` 返回 `false`。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "已发送停止命令。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "profile_id": {
                "type": "string"
              },
              "stopped": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## 导出 cookies

`GET /profiles/{id}/cookies`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "导出 cookies",
  "description": "读取配置文件的 Chromium cookie 存储，以**解密形式**返回所有 cookies。\n对正在运行和已停止的配置文件均有效。\n若配置文件从未启动过，返回空数组。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "Cookies。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "cookies": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Cookie"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "读取或解密 cookie 数据库时出错。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 导入 cookies

`POST /profiles/{id}/cookies`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "导入 cookies",
  "description": "将 cookies 写入配置文件存储（按 Chromium v10 方案重新加密）。\n配置文件**必须已停止**; 运行中的浏览器在退出时会覆盖存储，\n导致导入内容丢失。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "cookies"
          ],
          "properties": {
            "cookies": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Cookie"
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "已导入。",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "imported": {
                "type": "integer",
                "description": "已写入的 cookie 数量。"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "409": {
      "description": "配置文件正在运行; 请先停止它。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "写入 cookie 数据库时出错。",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## 正在运行的配置文件列表

`GET /running`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "正在运行的配置文件列表",
  "description": "拥有活跃浏览器进程的配置文件，通过 API 启动时包含 CDP 端点。",
  "responses": {
    "200": {
      "description": "正在运行的配置文件。",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RunningProfile"
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```