## 功能概述

实现 `chat.history` 接口，直接返回网关的原始响应数据，便于你先查看实际的数据结构。

## 接口契约

- 请求方式：WebSocket RPC
- 方法名：`chat.history`
- 请求帧示例：

```json
{
  "type": "req",
  "id": "<uuid>",
  "method": "chat.history",
  "params": {
    "sessionKey": "agent:main:main",
    "limit": 200,
    "offset": 0
  }
}
```

- 参数说明：
  - sessionKey（必填）：会话唯一标识；默认使用配置中的 `AdapterSettings.session_key`
  - limit（必填）：返回的最大条数；必须为正整数；默认 200
  - offset（可选）：分页偏移；必须为非负整数；默认 0

- 当前返回策略：
  - 暂时返回 `null`（Python 返回 `None`），以便先确认网关实际返回的历史数据结构
  - 同时以 JSON Pretty 格式打印原始 `payload` 到控制台日志，支持中文字符

## 代码集成点

```python
# ws_adapter.py 中新增方法（返回 None，打印原始响应）
def get_chat_history(
    self,
    session_key: Optional[str] = None,
    limit: int = 200,
    offset: int = 0,
    timeout_s: float = 15.0,
) -> None:
    """
    获取指定会话的历史聊天数据（打印响应到控制台，返回 None）。

    参数校验：
    - session_key 为 None 或非空字符串
    - limit > 0（正整数）
    - offset >= 0（非负整数）
    """
```

**实现要点**：

* 直接调用现有的 `request()` 方法发送 RPC 请求

* 不进行数据格式转换；当前返回 `None`，仅打印原始 `payload`

* 输出原始响应到控制台（JSON pretty，支持中文）

* 参数验证：limit > 0, offset >= 0, session\_key 非空

代码位置参考：
- 适配器类： [ws_adapter.py](file:///f:/aaa_desktop_file/openclaw-webchat-adapter/src/openclaw_webchat_adapter/ws_adapter.py)
- 配置项： [config.py](file:///f:/aaa_desktop_file/openclaw-webchat-adapter/src/openclaw_webchat_adapter/config.py)

## 错误与异常

- 超时：`RequestTimeoutError`（RPC 超时）
- 失败：`RequestFailedError`（网关返回 ok=false）
- 参数：`ValueError`（非法参数）
- 连接：`GatewayClosedError`（连接关闭）

异常类型定义： [exceptions.py](file:///f:/aaa_desktop_file/openclaw-webchat-adapter/src/openclaw_webchat_adapter/exceptions.py)

## 安全与校验

- 输入校验：对 `session_key/limit/offset` 做类型与范围校验
- 权限控制：沿用现有握手与鉴权机制（token/password），不在接口层泄漏敏感信息
- 日志内容：打印为业务数据（payload），不包含密钥与凭证

## 配置项

- 使用现有 `AdapterSettings.session_key` 作为默认会话键
- 可通过环境变量覆盖：
  - `OPENCLAW_SESSION_KEY`：默认会话键
  - 其余握手与鉴权项（沿用现有配置）

配置载入参考： [config.py:AdapterSettings.from_env](file:///f:/aaa_desktop_file/openclaw-webchat-adapter/src/openclaw_webchat_adapter/config.py#L108-L166)

## 测试计划

- 测试文件： [tests/test_chat_history.py](file:///f:/aaa_desktop_file/openclaw-webchat-adapter/tests/test_chat_history.py)
- 覆盖场景：
  - 成功返回并打印原始响应
  - 自定义 `session_key/limit/offset` 参数传递正确
  - 默认参数行为（使用配置的 `session_key`）
  - 参数非法抛出 `ValueError`
  - `RequestTimeoutError` 与 `RequestFailedError` 场景
  - 大数据集分页输出（仅打印，不转换）
- 运行方式：
  - `python -m unittest tests.test_chat_history -v`
  - 或整套测试：`python -m unittest -v`

## 后续迭代

- 与前端确认历史记录的展示数据结构（messages 字段的 shape）
- 决定是否在适配器层进行规范化转换与分页游标支持
- 如需持久化，评估存储方案与查询策略（可选）

## 交付物

- [x] `ws_adapter.py` - 新增 `get_chat_history()` 方法（返回 `None`）
- [x] `tests/test_chat_history.py` - 单元测试（打印验证与参数校验）
- [ ] 前端数据结构确认（待定）
- [ ] 若需转换，再增加统一返回结构与测试

