# 认证指南

本指南详细介绍 bdpan CLI 的登录认证流程。

---

## 登录方式

> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/login.sh
```

脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。用户主动发起登录时，新授权成功会展示场景化欢迎语；如果本地已经有有效登录态，会提示“你已登录百度网盘，无需重复授权”并展示同一组可直接使用的自然语言示例。此时不要把 `bdpan whoami` 的原始状态字段当作欢迎语。若登录只是某个文件任务的前置步骤，使用：

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/login.sh --continue-task
```

该模式登录成功后不输出欢迎语，调用方应立即继续原任务。

用户主动请求登录、但当前已经登录时，预期提示为：

```
你已登录百度网盘，无需重复授权。

现在可以直接说：
- 帮我找一份周末京津冀旅行攻略，整理好后存到网盘
- 把刚生成的简历和作品集上传到网盘
- 把朋友分享的照片转存到我的网盘
- 找出网盘里去年的体检报告
- 备份我的 Agent 记忆，方便以后恢复
```

只有用户明确要求查看登录状态时，才单独执行 `bdpan whoami` 并展示用户名或 Token 有效期。

---

## 验证登录状态

```bash
bdpan whoami
```

**已登录时输出：**
```
认证状态: 已登录
Token 有效期至: 2026-03-10 10:30:00
```

**未登录时输出：**
```
认证状态: 未登录
请执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh 进行登录
```

---

## 注销登录

```bash
bdpan logout
```

清除本地存储的认证信息（`~/.config/bdpan/config.json`）。

---

## 常见问题

### 登录后提示 Token 已过期

**症状：**
```
错误: Token 过期
Error: Token expired
```

**解决方案：**
```bash
bdpan logout
bash ${CLAUDE_SKILL_DIR}/scripts/login.sh
```

### 授权链接无效

**症状：** 浏览器打开链接后提示链接无效

**解决方案：**
1. 重新执行登录脚本获取新的授权链接
2. 确保在链接有效期内完成授权（通常 10 分钟）

### 授权码输入后报错

**症状：** 输入授权码后提示错误

**解决方案：**
1. 确保授权码复制完整，没有多余空格
2. 检查浏览器中显示的授权码是否与输入的一致
3. 如多次失败，重新执行登录脚本获取新授权码

### 登录失败时的处理顺序

无论是获取授权链接、提交授权码还是登录状态校验失败，先向用户展示 CLI 返回的实际失败原因（包括错误码或服务端消息，但不得展示授权码、Token 或配置内容），再给出手动授权入口：

```bash
bash ${CLAUDE_SKILL_DIR}/scripts/login.sh
```

不得只回复“登录失败，请重试”，也不要在未说明原因前直接要求用户重新授权。完成手动授权后，再重试原文件操作。

---

## 配置文件位置

```
~/.config/bdpan/config.json
```

**环境变量：**

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |

---

## 安全说明

- **OAuth 2.0**：使用授权码模式，不存储用户密码
- **Token 存储**：Token 加密存储在本地配置文件
- **自动续期**：Token 快过期时工具会自动刷新

---

## 自动登录失败场景

以下场景会自动切换到 OOB 模式：

| 场景 | 说明 |
|------|------|
| SSH 远程登录 | 无图形界面 |
| WSL 环境 | WebView 支持受限 |
| 桌面环境锁定 | WebView 无法弹出 |
| 浏览器未安装 | 无法打开 WebView |

切换到 OOB 模式时，先说明自动登录失败的实际原因，再提示用户按手动授权流程完成登录。若 OOB 登录由原文件任务触发，登录成功后继续原任务，不重复展示独立登录欢迎语。
