# 保持登录状态

接入需要登录的现有系统时，选择重新登录、复用浏览器登录状态或复用设备登录状态。

大部分现有系统只能在登录后访问。接入前需要先确定登录状态由谁持有、保存在哪里，以及失效后由谁恢复。百积木不会绕过验证码、多因素认证、单点登录或目标系统的安全策略，也不应把账号密码、Cookie、Authorization 或一次性验证码写进提示词、项目文件、模块定义和日志。

如果目标系统提供稳定的开放 API、OAuth、服务账号或应用授权，应优先使用官方接口。只有必须操作网页、桌面程序或仅在指定终端可访问的系统，才需要复用交互式登录状态。

## 选择登录方式

| 方式        | 登录状态所在位置        | 适用场景                              | 用户何时参与                    |
| --------- | --------------- | --------------------------------- | ------------------------- |
| 让用户重新登录   | 本次浏览器或应用会话      | 首次接入、临时任务、状态已失效或高风险操作             | 每次需要认证时完成登录、扫码、验证码或 MFA   |
| 使用浏览器登录状态 | 百积木浏览器 Profile  | 同一工作区长期访问 Web 系统，任务需要在托管浏览器中连续执行  | 首次登录及状态失效时通过浏览器 viewer 处理 |
| 使用设备登录状态  | 已授权设备上的浏览器或桌面应用 | 系统只能在内网、本机或指定设备访问，或者登录状态已保存在用户设备上 | 在设备上登录，并在敏感操作时确认          |

这三种方式不能相互冒充。托管浏览器的 Profile 不等于用户设备上的浏览器 Profile，设备上的登录状态也不会自动同步到百积木浏览器。先确定任务实际运行的位置，再选择对应方式。

## 方式一：让用户重新登录

首次接入、一次性任务、共享设备或目标系统要求频繁重新认证时，让用户在真实登录页面完成登录最稳妥。

1. 打开目标系统的正式地址，确认域名和证书正确。
2. 将可交互页面交给用户，由用户输入密码、扫码或完成验证码、MFA 和企业 SSO。
3. 登录完成后只检查页面是否进入预期账号和租户，不读取或回传密码、Cookie、验证码。
4. 执行一个只读操作，确认当前账号确实拥有任务需要的权限。
5. 会话结束或用户要求退出时，按目标系统的退出流程清理本次登录状态。

登录页面不得嵌入不可信页面，也不要让用户把密码、验证码或 Cookie 发送给智能体。遇到异常登录提醒、账号锁定或租户不符时应停止操作，由用户确认账号安全后再继续。

## 方式二：使用浏览器登录状态

需要多次访问同一个 Web 系统时，可以让任务使用固定的百积木浏览器 Profile。用户通过 viewer 完成一次登录后，后续浏览器会话复用该 Profile 中由网站写入的登录状态。

1. 为目标系统和使用范围选择专用浏览器 Profile，不要多人共用个人账号的 Profile。
2. 创建或复用绑定该 Profile 的浏览器会话，打开目标系统正式地址。
3. 如果页面要求登录，把 viewer 交给用户完成登录、扫码、验证码或 MFA。
4. 登录后关闭登录页面中的敏感信息，执行一次只读查询验证账号、租户和权限。
5. 后续任务继续使用同一个 Profile；不要把 Cookie 或 Authorization 导出到项目文件、聊天或日志中。

浏览器 Profile 只能延续目标系统允许延续的会话，不能保证永久在线。网站主动退出、密码变更、管理员撤销、Cookie 过期、MFA 策略更新或风险控制都会使状态失效。检测到登录页、`401`、`403`、账号或租户变化时，应暂停业务操作并让用户重新登录，不能通过无限重试或伪造凭据绕过认证。

需要把一次浏览器操作进一步固化为工作区能力时，可参考[浏览器录制生成个性化 Bundle](/development/bundle-development/advanced/browser-recording-to-bundle/)。录制得到的 Cookie、CSRF、一次性 token 和个人数据不能固化进 Bundle。

## 方式三：使用设备登录状态

目标系统只能访问企业内网、本机浏览器、桌面客户端，或者用户已经在指定设备上登录时，应让任务在该设备上执行。登录状态继续保存在设备原有的浏览器 Profile 或桌面应用中，不复制到平台服务端。

1. 在工作区中绑定归属明确的设备，并确认设备在线、工作区正确、所需服务能力已经授权。
2. 由用户在该设备的目标浏览器或桌面应用中完成登录。
3. 选择与实际登录状态对应的设备能力和浏览器 Profile；不要默认使用其他系统账号或其他用户的窗口。
4. 先执行只读操作，确认当前账号、租户、数据范围和设备网络均正确。
5. 对提交、付款、删除、发布和权限变更等高风险操作保留人工确认，并在工作区和设备侧保留审计记录。

设备离线、客户端退出、浏览器 Profile 被清理或本地应用退出登录时，平台无法继续复用该状态。先恢复设备在线，再由用户在设备上重新登录；不要把本地认证文件、浏览器用户目录或 Cookie 复制到其他设备。设备的绑定、能力检查和审计方式见[设备接入与 SSH 审计](/features/device-ssh-audit/)和[设备](/concepts/devices/)。

## 失效检测与恢复

接入实现必须把“未登录”和“业务失败”分开处理：

| 现象               | 判断                     | 处理                        |
| ---------------- | ---------------------- | ------------------------- |
| 跳转到登录页、出现扫码或 MFA | 登录状态不存在或已经失效           | 暂停任务，把登录界面交给用户            |
| 返回 `401`         | 当前请求没有有效认证             | 重新登录或刷新官方授权，不盲目重试         |
| 返回 `403`         | 已登录但账号、租户或权限不满足        | 核对当前身份和授权范围，不切换成未知账号      |
| 页面显示的账号或租户发生变化   | 复用了错误的 Profile、窗口或设备状态 | 停止写操作，重新选择正确的 Profile 或设备 |
| 设备离线或本地应用未运行     | 执行环境不可用，不是登录问题         | 恢复设备和本地能力后再检查登录状态         |

恢复后重新执行只读验证，再继续原任务。对于可能重复提交的写操作，必须先查询目标系统中的实际结果并使用幂等标识或业务唯一键，不能在重新登录后直接重放。

## 上线前检查

- 已明确登录状态属于哪个用户、工作区、目标系统账号和租户。
- 已确定状态保存在本次会话、百积木浏览器 Profile，还是用户设备中。
- 密码、Cookie、token、验证码和认证文件没有进入代码、配置、Bundle、日志或聊天。
- 已验证登录失效、设备离线、权限不足和账号切换时会停止业务操作。
- 写操作有人工确认、幂等保护和审计记录。
- 已验证退出登录、撤销设备或删除 Profile 后，旧状态不能继续使用。