企业官网建设流程全解析

pinchtab state是 PinchTab 中负责浏览器会话状态的核心命令族：它既能实时查看某个标签页（Tab）的完整浏览器状态，也能把 cookies、localStorage、sessionStorage等会话数据以命名文件的形式持久化到磁盘，在后续会话中按名或按前缀一键恢复。本文以 docs/reference/state.md 为骨架，结合 state 命令定义、HTTP 处理器 与 状态持久化实现 等源码，完整覆盖 CLI 子命令、HTTP API、能力门控配置、加密存储格式与底层捕获/恢复原理，帮助你用 PinchTab 实现「登录态存档、会话迁移、多标签页状态管理」等自动化场景。

两种 State 视图：完整浏览器状态与实时标签页状态

PinchTab 的「状态」分两个层次，用途完全不同，使用前务必区分：

GET /tabs/{id}/state返回的实时视图不包含 cookies 与持久化存储，而是返回页面运行时信号。从 state_tab.go 的实现看，其响应体包含readyState（loading/interactive/complete）、navigationInProgress、networkIdle、dialogPresent、actionability（ready/caution/blocked）等字段：loading或interactive时 actionability 降级为caution，存在待处理对话框时置为blocked。因此该端点适合作为动作执行前的低成本探针，而需要完整会话快照时应使用GET /state。

完整浏览器状态的组成（由 state_capture.go 的响应结构 定义）：

• tabId、url、title等标签页基本信息；
• cookies列表；
• storage：按 origin 组织的localStorage与sessionStorage键值对；
• metadata：origin、user agent 等附加元数据。

前置条件：security.allowStateExport与加密密钥

所有完整/保存状态操作（含/storage系列路由）都要求配置开启security.allowStateExport=true，否则请求会被拒绝。这一门控在路由层和能力层都有体现：

• 路由表中将stateExport能力映射到配置项security.allowStateExport，拒绝时返回错误码state_export_disabled，见 internal/routes/routes.go；
• 每个 handler 入口调用ensureStateExportEnabled统一拦截，见 internal/handlers/state.go 与 storage.go；
• 测试用例 capability_refusal_test.go 明确断言/storage在未开启时返回stateExport/security.allowStateExport/state_export_disabled三元组。

配置方式（示例片段）：

{ "server": { "stateDir": "/path/to/state" }, "security": { "allowStateExport": true } }

• server.stateDir：状态目录根路径，见 config_types.go 的 ServerConfig。保存的状态文件实际存放在{stateDir}/sessions/子目录下（state.go 的 SessionsDir）；
• security.allowStateExport：总开关，见 SecurityConfig；
• security.stateEncryptionKey：加密密钥配置项（SecurityConfig.StateEncryptionKey）。服务端在实际加密/解密时通过环境变量PINCHTAB_STATE_KEY读取该密钥（state.go handler），密钥为空时加密保存直接返回 400（state.go）。

仓库 e2e 配置可以佐证该开关的两种形态：常规配置如 tests/e2e/config/pinchtab.json 中allowStateExport: true，而 tests/e2e/config/pinchtab-secure.json 明确设为false，用于验证拒绝路径。

CLI 命令总览

state命令及其子命令定义于 cmd_cli_state.go，CLI 到 HTTP API 的调用映射在 internal/cli/actions/actions_state.go。

pinchtab state [--tab <id>] pinchtab state list pinchtab state save [--name <name>] [--encrypt] [--tab <id>] pinchtab state load --name <name-or-prefix> [--tab <id>] pinchtab state show --name <name> pinchtab state delete --name <name> pinchtab state clean [--older-than <hours>]

各子命令的 flags 要点（来自 cmd_cli_state.go 的 init）：

• state与state save、state load均支持--tab <id>指定目标标签页；省略时作用于当前/活动标签页；
• state save --name省略时自动生成名称（格式为state-<unix时间戳>，见 state.go 的 Save）；
• state save --encrypt开启加密，需要配置加密密钥（见上文）；
• state load、state show、state delete的--name为必填；
• state clean --older-than默认值为24（小时）。

查看当前浏览器状态

pinchtab state # 活动标签页的完整浏览器状态 pinchtab state --tab <tabId> # 指定标签页

返回内容即上文「完整浏览器状态」的全部字段：cookies、当前源存储、tabId/URL/title，以及 origin、user agent 等元数据。底层由HandleStateCurrent调用captureBrowserState完成捕获（state_capture.go）。

需要轻量化的运行/就绪视图时，改用GET /tabs/{id}/state；两种视图的分工在 endpoints.md 中有明确说明。

保存当前浏览器状态

pinchtab state save # 自动命名 pinchtab state save --name work-login # 指定名称 pinchtab state save --name checkout --tab <tabId> # 保存指定标签页 pinchtab state save --name work-login --encrypt # 加密保存

要点：

• 省略--name时 PinchTab 自动生成state-<时间戳>名称；
• --tab <id>从指定标签页捕获状态而非活动标签页；
• --encrypt要求配置security.stateEncryptionKey（服务端以PINCHTAB_STATE_KEY环境变量读取），密钥缺失时请求被拒绝；
• 捕获过程通过桥接层读取 cookies（GetRawCookies）并在页面上下文执行脚本枚举localStorage/sessionStorage，同时采集 URL、title、origin、user agent 写入元数据（captureBrowserState）；
• 保存响应包含name、path、cookies（数量）、origins、encrypted等字段（state.go）。

加载已保存的状态

pinchtab state load --name work-login # 精确名称 pinchtab state load --name work-log # 前缀匹配，取最新 pinchtab state load --name checkout --tab <tabId>

要点：

• --name既可精确匹配，也接受前缀；
• 前缀匹配解析为最近保存的匹配项：HandleStateLoad先尝试精确路径，不存在时调用FindByPrefix取最新一条（state_capture.go），而 FindByPrefix / List 返回的结果按SavedAt降序（最新在前）；
• 加载会向目标标签页恢复 cookies 与当前源存储：cookies 逐条通过SetRawCookie写入，存储通过单次Evaluate批量注入（见下文「恢复原理」）；
• 响应包含name、cookiesRestored、storageItemsRestored、origins（state_capture.go）。

查看、删除与清理已保存状态

pinchtab state list # 列出所有保存的状态文件 pinchtab state show --name work-login # 显示完整记录（含元数据与存储载荷） pinchtab state delete --name work-login # 从磁盘删除 pinchtab state clean # 清理默认 24 小时前的文件 pinchtab state clean --older-than 72 # 清理 72 小时前的文件

细节说明：

• list返回每个文件的name、savedAt、origins、encrypted、sizeBytes摘要（StateEntry）。加密文件（.json.enc）由于 payload 是密文，列表无法解析元数据，savedAt/origins为空但encrypted标记正确（List 实现）；
• show展示完整状态文件内容，需要密钥才能读取加密文件（HandleStateShow）；
• delete先尝试删除.json.enc，再尝试.json（Delete）；
• clean默认阈值 24 小时（CLI flag 默认值与 handler 兜底逻辑均为 24，见 cmd_cli_state.go 与 state.go），按文件修改时间判定并同时处理两种扩展名（Clean），返回removed数量与olderThanHours。

HTTP API 全览

GET /state GET /state/list GET /state/show POST /state/save POST /state/load DELETE /state POST /state/clean

参数契约（详细说明见 endpoints.md）：

所有端点均受security.allowStateExport门控（endpoints.md）。

存储格式与安全细节

状态持久化由 internal/state/state.go 独立实现，关键设计如下：

文件布局与权限

• 保存目录为{stateDir}/sessions/，目录权限0700，文件权限0600（EnsureSessionsDir、Save）；
• 明文文件使用.json扩展名，加密文件使用.json.enc（fileExtension）。

StateFile 结构（版本 1）

{ "version": 1, "name": "work-login", "savedAt": "2026-09-24T02:33:01Z", "origins": ["https://example.com"], "cookies": [], "storage": { "https://example.com": { "local": {}, "session": {} } }, "metadata": {}, "encrypted": false }

对应 StateFile 定义 与 Cookie（镜像 CDP network cookie 的name、value、domain、path、secure、httpOnly、sameSite、expires字段）。

加密机制

• 采用 AES-256-GCM，密钥由口令经 PBKDF2 派生：100,000 次迭代、16 字节随机盐，输出格式为salt(16B) || nonce || ciphertext（Encrypt）；
• 解密时先尝试 PBKDF2 派生密钥，失败则回退到旧版 SHA-256 派生态，兼容历史文件（Decrypt）；
• 加载时以文件扩展名（.json.enc）为准判断是否加密，避免「配置了密钥但文件其实是明文」的误判；同时用json.Valid兜底识别旧版未使用.enc扩展名的加密文件（Load）。

写入安全

• 采用「写临时文件 + 原子重命名」的方式防撕裂写：加密载荷一旦截断，GCM 认证必然失败，等于整体丢失会话，因此原子写至关重要（Save 的注释与实现）；
• 文件名经过sanitizeFilename净化（去路径分隔符、..穿越、非法字符替换为_），且保存/删除/解析路径均校验「解析后的路径不得逃逸 sessions 目录」，防止路径穿越（sanitizeFilename、Save、Delete）。

底层原理：状态捕获与恢复

捕获流程（captureBrowserState）：

1. 通过桥接层GetRawCookies读取全部 cookies，转换为state.Cookie；
2. 在页面上下文执行一段脚本，遍历localStorage与sessionStorage的全部键值，并同时返回url、title、origin、navigator.userAgent；
3. 脚本异常时仍返回部分数据并在metadata.storageError中记录错误信息；
4. 组装StateFile（savedAt、origins、cookies、storage、metadata）。

整个捕获/加载过程包在 30 秒超时上下文中，标签页解析走统一的guardedTabContext（加载时额外带 handoff 暂停防护，见 state_capture.go）。

恢复流程（HandleStateLoad）：

1. 解析状态文件（精确名优先，前缀回退取最新）；
2. 逐条恢复 cookies：SetRawCookie按name、domain、path、secure、httpOnly、sameSite还原；
3. 按 origin 恢复存储：每个 origin 只发起一次Evaluate，脚本内循环调用localStorage.setItem/sessionStorage.setItem，避免每个键一次 CDP 往返（restoreOriginStorage）；
4. 返回cookiesRestored与storageItemsRestored计数。

TestHandleStateLoadBatchesStorage专门验证了这种批量恢复行为，见 internal/handlers/state_test.go。

测试与验证路径

• e2e 冒烟测试：tests/e2e/scenarios/infra/state-basic.sh 覆盖了GET /state/list、POST /state/save、GET /state/show、POST /state/load（含前缀匹配）、DELETE /state（含不存在名称的拒绝）、POST /state/clean、自动命名保存等完整链路，运行前提即security.allowStateExport=true；
• 能力门控测试：capability_refusal_test.go 验证存储路由在能力未开启时返回state_export_disabled；
• 单元测试：internal/state/state_test.go 与 load_test.go 覆盖持久化、加密、前缀查找等底层逻辑。

相关文档

• Tabs：实时标签页操作与--tab <id>用法（含cookies clear后可用state load恢复的提示）；
• Sessions：Agent/会话认证；
• Config：server.stateDir与 security 开关；
• Endpoints：/state路由索引与参数契约；
• 数据存储指南：状态目录与其他持久化数据的布局说明。