diff --git a/AGENTS.md b/AGENTS.md
index 47baf64..68a6b87 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,8 +62,8 @@ Rules:
 - Do not add mock/fallback rows. If MySQL is unavailable, surface the error.
 - `is_low_power` is stored as a string and normalized to boolean in `src/domain/battery.ts`.
 - `power_status` is normalized to `0 | 1 | 2`.
-- Without `mac`, battery list queries return the latest record per `mac`.
-- With `mac`, battery list queries return history ordered by `create_time DESC, id DESC`, limited to 500 rows.
+- `battery.batteries` returns paginated latest records per `mac`; supported filters are `pageSize`, `cursor`, `search`, `lowPower`, `powerStatus`, and `sort`.
+- `battery.history` takes `mac` and returns history ordered by `create_time DESC, id DESC`, limited to 500 rows.
 - Dashboard may call the external prediction API when `SOH_PREDICTION_API_BASE_URL` is configured. Prediction results are cached in memory by `mac` and latest history record.
 
 ## Layout
@@ -91,6 +91,7 @@ src/
 - Current business API:
   - `battery.dashboard`
   - `battery.batteries`
+  - `battery.history`
 
 ## CLI And Deploy
 
diff --git a/README.md b/README.md
index 6c8ffdb..e18418f 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,8 @@ src/
 接口保持模板里的 ORPC 模式：
 
 - `battery.dashboard`：读取每个 `mac` 的最新记录并生成看板聚合数据
-- `battery.batteries`：无 `mac` 时返回每台设备最新记录；带 `mac` 时返回该设备历史记录，按 `create_time desc` 限制 500 条
+- `battery.batteries`：分页返回每台设备最新记录，支持 `pageSize`、`cursor`、`search`、`lowPower`、`powerStatus`、`sort` 筛选/排序
+- `battery.history`：按 `mac` 返回该设备历史记录，按 `create_time desc` 限制 500 条
 
 所有业务查询都是 `SELECT`，没有 mutation，也没有 mock/fallback 数据。