leap-cn-mcp 0.1.0

package/README.md

@@ -0,0 +1,276 @@
+# Leapmotor CN SDK + CLI + HTML Demo
+
+本目录包含零跑中国 App 逆向出的核心链路实现：
+
+- 发送短信验证码
+- 验证码登录
+- 旧登录 token 换新网关 `accessToken/signKey`
+- 查询车辆列表、车辆路由、车况、电池、里程、门锁、车窗、位置、空调状态
+- 构造/发送控车命令和查询控车结果
+
+实现分三层：
+
+```text
+src/leapmotor-cn-sdk.js   SDK 核心，供 CLI、服务或后续 MCP 调用
+bin/leap-cn.js            CLI，默认 JSON 输出，适合 AI/脚本调用
+server.js + public/       原 HTML demo，保留给人工调试
+```
+
+## CLI
+
+```bash
+cd /Users/qian/project/lingpao/demo
+npm run cli -- session
+npm run cli -- vehicles
+npm run cli -- state
+npm run cli -- mileage
+npm run cli -- location
+npm run cli -- overview
+```
+
+登录：
+
+```bash
+npm run cli -- send-sms --phone <手机号>
+npm run cli -- login --phone <手机号> --code <验证码>
+```
+
+车辆选择：
+
+```bash
+npm run cli -- vehicles
+npm run cli -- select --vin <VIN> --car-type S01
+```
+
+远控预览，不会触发真实车辆动作：
+
+```bash
+npm run cli -- control-preview --command lock
+npm run cli -- control-preview --command window --value 0
+npm run cli -- control-preview --command acOn
+```
+
+真实远控需要同时给出两个安全开关：
+
+```bash
+npm run cli -- control-send --command lock --allow-write --confirm
+```
+
+如果命令需要操作密码，CLI 提供两个等价参数：
+
+```bash
+npm run cli -- control-send --command unlock --pin <操作密码> --allow-write --confirm
+npm run cli -- control-send --command unlock --operation-password <操作密码> --allow-write --confirm
+```
+
+查询控车结果：
+
+```bash
+npm run cli -- control-query --msgID <msgID>
+```
+
+支持的远控命令可查看：
+
+```bash
+npm run cli -- commands
+```
+
+常用命令名：
+
+```text
+lock, unlock, trunk, trunkOpen, trunkClose, frunkOpen, frunkClose,
+horn, batteryPreheat, batteryPreheatOff,
+window, windowClose, windowVent,
+sunshadeOpen, sunshadeClose, sunroofOpen, sunroofClose,
+ac, acOn, acOff, quickCool, quickHeat, windshieldDefrost, custom
+```
+
+`custom` 示例：
+
+```bash
+npm run cli -- control-preview \
+  --command custom \
+  --cmdid 170 \
+  --state-json '{"operate":"manual","temperature":"24","windlevel":"3","mode":"cold","circle":"in","wshld":"0","position":"all"}'
+```
+
+## SDK
+
+```js
+import { LeapmotorChinaClient } from './src/leapmotor-cn-sdk.js';
+
+const client = new LeapmotorChinaClient({
+  sessionFile: '/Users/qian/project/lingpao/demo/.leap-session.json'
+});
+
+await client.loadSession();
+const vehicles = await client.listVehicles();
+const status = await client.getVehicleState();
+const preview = await client.previewControl({ command: 'lock' });
+```
+
+真实远控默认禁用。SDK 层需要：
+
+```js
+const client = new LeapmotorChinaClient({ allowWrite: true });
+await client.sendControl({
+  command: 'unlock',
+  operationPassword: '<操作密码>',
+  confirm: true
+});
+```
+
+## MCP
+
+给 AI 调用时，推荐使用 MCP stdio 服务：
+
+```bash
+npx --yes --package leap-cn-mcp leap-cn-mcp
+```
+
+可执行文件：
+
+```text
+/Users/qian/project/lingpao/demo/bin/leap-cn-mcp.js
+```
+
+示例 MCP 配置：
+
+```json
+{
+  "mcpServers": {
+    "leapmotor-cn": {
+      "command": "npx",
+      "args": ["--yes", "--package", "leap-cn-mcp", "leap-cn-mcp"],
+      "env": {
+        "LEAP_SESSION_FILE": "/Users/qian/project/lingpao/demo/.leap-session.json"
+      }
+    }
+  }
+}
+```
+
+MCP tools：
+
+```text
+leap_session
+leap_send_sms
+leap_login_sms
+leap_vehicles
+leap_select_vehicle
+leap_route
+leap_state
+leap_mileage
+leap_location
+leap_overview
+leap_commands
+leap_control_preview
+leap_control_send
+leap_control_query
+```
+
+MCP 真实远控比 CLI 更保守，需要同时满足：
+
+```text
+1. 启动 MCP 服务时设置 LEAP_ALLOW_WRITE=1
+2. tool 参数 allowWrite=true
+3. tool 参数 confirm=true
+```
+
+不满足任一条件都会拒绝发送。`leap_control_preview` 永远只生成 dryRun 摘要。
+
+## Web Demo
+
+Web demo 现在也复用同一个 SDK 文件：
+
+```text
+server.js -> src/leapmotor-cn-sdk.js
+```
+
+页面里的操作密码输入框会透传为 SDK 的 `operationPassword`，由 SDK 加密成 `oppwd` 后发送。页面仍要求勾选确认后才会触发真实控车。
+
+## 运行
+
+```bash
+cd /Users/qian/project/lingpao/demo
+npm start
+```
+
+默认地址：
+
+```text
+http://localhost:8787
+```
+
+可选环境变量：
+
+```bash
+PORT=8787 LEAP_DEVICE_ID=<deviceId> LEAP_APP_VERSION=1.22.87 LEAP_SUB_VERSION=3.19.2-2 npm start
+```
+
+CLI 也支持：
+
+```bash
+LEAP_SESSION_FILE=/Users/qian/project/lingpao/demo/.leap-session.json npm run cli -- session
+LEAP_ALLOW_WRITE=1 npm run cli -- control-send --command lock --confirm
+```
+
+`deviceId` 注意事项：
+
+```text
+LEAP_DEVICE_ID 只应在首次登录/新 session 时指定。
+如果 session 文件已存在，SDK 会优先使用 session 内保存的 deviceId。
+不要把已有 session 里的 deviceId 手工替换成新值。
+```
+
+实测把现有 session 的 `deviceId` 改成随机值后：
+
+```text
+车辆列表/实时状态：仍返回 code/result=0
+旧 carownerservice 里程接口：返回 result=39 信息校验失败
+```
+
+远控也依赖旧签名链路，因此换 `deviceId` 后应重新短信登录，不要复用旧 session。
+
+## 安全说明
+
+- 短信验证码接口会在服务端按 App 规则将手机号 RSA 加密为 `phoneNo` 后发送，不落盘保存手机号。
+- token、signKey、车辆选择会保存到本地 `.leap-session.json`，用于重启后自动恢复登录态。
+- `.leap-session.json` 已加入 `.gitignore`，文件权限按 `600` 写入；不要提交或分享。
+- 页面上的“重置会话”会同时清空内存并删除 `.leap-session.json`。
+- 登录接口和调试输出不返回完整 token/signKey。
+- CLI 的 `control-preview` 不会触发真实车辆动作。
+- CLI 的 `control-send` 必须同时提供 `--allow-write` 和 `--confirm`。
+- SDK 的 `sendControl()` 必须 `allowWrite=true` 且 `confirm=true`。
+- Web demo 控车接口会触发真实车辆动作，页面要求勾选确认后才会发送。
+- 操作密码如填写，会按 App 规则使用旧 token 加密成 `oppwd` 后发送。
+
+## 验证结果
+
+当前 session 下已用 CLI 验证：
+
+```text
+npm run cli -- vehicles   -> code/result=0
+npm run cli -- state      -> code/result=0，summary 可读电池、门锁、车窗、空调、经纬度
+npm run cli -- mileage    -> code/result=0
+npm run cli -- location   -> code/result=0，当前响应 data=null；经纬度以 state summary 为准
+```
+
+真实远控没有执行。仅验证了：
+
+```text
+control-preview 只生成 dryRun 请求摘要
+control-send 缺少 --allow-write 会拒绝
+control-send 缺少 --confirm 会拒绝
+```
+
+## 主要源码
+
+```text
+src/leapmotor-cn-sdk.js
+bin/leap-cn.js
+server.js
+public/index.html
+public/app.js
+public/styles.css
+```

package/bin/leap-cn-mcp.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { createClientFromEnv, commandPresets } from '../src/leapmotor-cn-sdk.js';
+
+const client = createClientFromEnv({
+  sessionFile: process.env.LEAP_SESSION_FILE || new URL('../.leap-session.json', import.meta.url).pathname,
+  allowWrite: process.env.LEAP_ALLOW_WRITE === '1'
+});
+
+const tools = [
+  tool('leap_session', 'Read current Leapmotor session summary.', {}),
+  tool('leap_send_sms', 'Send SMS login code. Phone is RSA encrypted before sending.', {
+    phone: stringSchema('Phone number')
+  }, ['phone']),
+  tool('leap_login_sms', 'Verify SMS code and exchange gateway token.', {
+    phone: stringSchema('Phone number'),
+    smsCode: stringSchema('SMS verification code')
+  }, ['phone', 'smsCode']),
+  tool('leap_vehicles', 'List vehicles bound to the account.', {}),
+  tool('leap_select_vehicle', 'Select active vehicle for subsequent calls.', {
+    vin: stringSchema('Vehicle VIN'),
+    carType: stringSchema('Optional car type')
+  }, ['vin']),
+  tool('leap_route', 'Fetch selected vehicle route.', {}),
+  tool('leap_state', 'Fetch selected vehicle realtime state and normalized summary.', {}),
+  tool('leap_mileage', 'Fetch selected vehicle mileage and energy detail.', {}),
+  tool('leap_location', 'Fetch old chassis/location endpoint. Realtime state may have better coordinates.', {}),
+  tool('leap_overview', 'Fetch route, realtime state, mileage, and location together.', {}),
+  tool('leap_commands', 'List supported remote-control command presets.', {}),
+  tool('leap_control_preview', 'Build a remote-control request without sending it.', {
+    command: stringSchema('Command preset name'),
+    value: stringSchema('Value for value-based commands such as window'),
+    cmdid: stringSchema('Custom command id'),
+    stateJson: stringSchema('Custom state JSON'),
+    operationPassword: stringSchema('Operation password/PIN; encrypted into oppwd')
+  }, ['command']),
+  tool('leap_control_send', 'Send a real remote-control command. Requires LEAP_ALLOW_WRITE=1, allowWrite=true, and confirm=true.', {
+    command: stringSchema('Command preset name'),
+    value: stringSchema('Value for value-based commands such as window'),
+    cmdid: stringSchema('Custom command id'),
+    stateJson: stringSchema('Custom state JSON'),
+    operationPassword: stringSchema('Operation password/PIN; encrypted into oppwd'),
+    allowWrite: booleanSchema('Must be true'),
+    confirm: booleanSchema('Must be true')
+  }, ['command', 'allowWrite', 'confirm']),
+  tool('leap_control_query', 'Query remote-control result by msgID/eventId.', {
+    msgID: stringSchema('Control msgID/eventId')
+  }, ['msgID'])
+];
+
+const toolMap = new Map(tools.map((item) => [item.name, item]));
+
+await client.loadSession();
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  let request;
+  try {
+    request = JSON.parse(line);
+    const response = await handleRequest(request);
+    if (response) write(response);
+  } catch (error) {
+    write({
+      jsonrpc: '2.0',
+      id: request?.id ?? null,
+      error: { code: -32000, message: error.message }
+    });
+  }
+});
+
+async function handleRequest(request) {
+  const { id, method, params = {} } = request;
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: params.protocolVersion || '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'leapmotor-cn-mcp', version: '0.1.0' }
+      }
+    };
+  }
+  if (method === 'notifications/initialized') return null;
+  if (method === 'tools/list') {
+    return { jsonrpc: '2.0', id, result: { tools } };
+  }
+  if (method === 'tools/call') {
+    const result = await callTool(params.name, params.arguments || {});
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+      }
+    };
+  }
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` }
+  };
+}
+
+async function callTool(name, args) {
+  if (!toolMap.has(name)) throw new Error(`Unknown tool: ${name}`);
+  switch (name) {
+    case 'leap_session':
+      return { session: client.sessionSummary(), auth: client.authDebugSummary() };
+    case 'leap_send_sms':
+      return { response: await client.sendSms(required(args.phone, 'phone')) };
+    case 'leap_login_sms':
+      return await client.loginWithSms({
+        phone: required(args.phone, 'phone'),
+        smsCode: required(args.smsCode, 'smsCode')
+      });
+    case 'leap_vehicles':
+      return await client.listVehicles();
+    case 'leap_select_vehicle':
+      return { session: await client.selectVehicle(required(args.vin, 'vin'), args.carType || '') };
+    case 'leap_route':
+      return await client.getVehicleRoute();
+    case 'leap_state':
+      return await client.getVehicleState();
+    case 'leap_mileage':
+      return await client.getMileageEnergy();
+    case 'leap_location':
+      return await client.getLocation();
+    case 'leap_overview':
+      return await client.getOverview();
+    case 'leap_commands':
+      return { commands: commandPresets };
+    case 'leap_control_preview':
+      return await client.previewControl(controlArgs(args));
+    case 'leap_control_send':
+      if (process.env.LEAP_ALLOW_WRITE !== '1') {
+        throw new Error('真实控车需要 MCP 服务启动时设置 LEAP_ALLOW_WRITE=1');
+      }
+      if (args.allowWrite !== true || args.confirm !== true) {
+        throw new Error('真实控车需要 allowWrite=true 且 confirm=true');
+      }
+      return await client.sendControl({ ...controlArgs(args), allowWrite: true, confirm: true });
+    case 'leap_control_query':
+      return await client.queryControlResult(required(args.msgID, 'msgID'));
+    default:
+      throw new Error(`Unhandled tool: ${name}`);
+  }
+}
+
+function controlArgs(args) {
+  return {
+    command: required(args.command, 'command'),
+    value: args.value,
+    cmdid: args.cmdid,
+    stateJson: args.stateJson,
+    operationPassword: args.operationPassword || ''
+  };
+}
+
+function tool(name, description, properties, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      required,
+      additionalProperties: false
+    }
+  };
+}
+
+function stringSchema(description) {
+  return { type: 'string', description };
+}
+
+function booleanSchema(description) {
+  return { type: 'boolean', description };
+}
+
+function required(value, name) {
+  if (value === undefined || value === null || value === '') throw new Error(`Missing required argument: ${name}`);
+  return value;
+}
+
+function write(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "leap-cn-mcp",
+  "version": "0.1.0",
+  "description": "MCP stdio server for Leapmotor China app APIs.",
+  "type": "module",
+  "bin": {
+    "leap-cn-mcp": "bin/leap-cn-mcp.js"
+  },
+  "files": [
+    "README.md",
+    "bin/leap-cn-mcp.js",
+    "src/leapmotor-cn-sdk.js"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "cli": "node bin/leap-cn.js",
+    "mcp": "node bin/leap-cn-mcp.js",
+    "check": "node --check src/leapmotor-cn-sdk.js && node --check bin/leap-cn.js && node --check bin/leap-cn-mcp.js && node --check server.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/leapmotor-cn-sdk.js

@@ -0,0 +1,900 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const DEFAULT_APP_VERSION = '1.22.87';
+export const DEFAULT_SUB_VERSION = '3.19.2-2';
+export const DEFAULT_SESSION_FILE = path.resolve(process.cwd(), '.leap-session.json');
+
+const DEFAULT_PUBLIC_KEY =
+  'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHUIQKhkwNqJFTZPe98mC1lmpbY9r/+7PEWZg8ebqYXT3sumKRaQ0zcoTx42x0iybmCRXy4CcZrgGAbwKzwqwNw0rFquJ6c7mgQA6k3lZU3p96qBlzK7DSkoFR6mO9pjcd2hlJ8wH+IwI5b8IWWZhwVN/4cM7npG0S0zeRn3soEwIDAQAB';
+
+const HOSTS = {
+  appUser: 'https://appuser.leapmotor.cn',
+  global: 'https://app-gw-global-master.leapmotor.com'
+};
+
+export const appointmentCmdIds = new Set(['161', '171', '361', '392']);
+
+export const commandPresets = {
+  lock: { label: '上锁', cmdid: '110', state: { value: 'lock' }, acceptsOperationPassword: true },
+  unlock: { label: '解锁', cmdid: '110', state: { value: 'unlock' }, acceptsOperationPassword: true },
+  trunk: { label: '后备箱/尾门触发', cmdid: '130', state: { value: 'true' }, acceptsOperationPassword: true },
+  trunkOpen: { label: '后备箱/尾门打开', cmdid: '130', state: { value: 'true' }, acceptsOperationPassword: true },
+  trunkClose: { label: '后备箱/尾门关闭', cmdid: '130', state: { value: 'false' }, acceptsOperationPassword: true },
+  frunkOpen: { label: '前备箱打开', cmdid: '131', state: { value: '100' }, acceptsOperationPassword: true },
+  frunkClose: { label: '前备箱关闭', cmdid: '131', state: { value: '0' }, acceptsOperationPassword: true },
+  horn: { label: '鸣笛寻车', cmdid: '120', state: { value: 'true' }, acceptsOperationPassword: true },
+  batteryPreheat: { label: '电池/座舱预热开启', cmdid: '160', state: { value: 'ptcon' }, acceptsOperationPassword: true },
+  batteryPreheatOff: { label: '电池/座舱预热关闭', cmdid: '160', state: { value: 'ptcoff' }, acceptsOperationPassword: true },
+  window: { label: '车窗控制', cmdid: '230', stateFromValue: true, acceptsOperationPassword: true },
+  windowClose: { label: '车窗关闭', cmdid: '230', state: { value: '0' }, acceptsOperationPassword: true },
+  windowVent: { label: '车窗通风', cmdid: '230', state: { value: '2' }, acceptsOperationPassword: true },
+  sunshadeOpen: { label: '天幕/遮阳帘打开', cmdid: '240', state: { value: '10' }, acceptsOperationPassword: true },
+  sunshadeClose: { label: '天幕/遮阳帘关闭', cmdid: '240', state: { value: '0' }, acceptsOperationPassword: true },
+  sunroofOpen: { label: '天窗/车顶打开', cmdid: '300', state: { value: '1' }, acceptsOperationPassword: true },
+  sunroofClose: { label: '天窗/车顶关闭', cmdid: '300', state: { value: '0' }, acceptsOperationPassword: true },
+  ac: { label: '空调自定义', cmdid: '170', rawState: true, acceptsOperationPassword: true },
+  acOn: {
+    label: '空调开启',
+    cmdid: '170',
+    state: {
+      operate: 'manual',
+      temperature: '24',
+      windlevel: '3',
+      mode: 'cold',
+      circle: 'in',
+      wshld: '0',
+      position: 'all'
+    },
+    acceptsOperationPassword: true
+  },
+  acOff: {
+    label: '空调关闭',
+    cmdid: '170',
+    state: {
+      operate: 'off',
+      temperature: '24',
+      windlevel: '3',
+      mode: 'nohotcold',
+      circle: 'out',
+      wshld: '0',
+      position: 'all'
+    },
+    acceptsOperationPassword: true
+  },
+  quickCool: {
+    label: '极速降温',
+    cmdid: '170',
+    state: {
+      operate: 'manual',
+      temperature: '18',
+      windlevel: '7',
+      mode: 'cold',
+      circle: 'in',
+      wshld: '0',
+      position: 'all'
+    },
+    acceptsOperationPassword: true
+  },
+  quickHeat: {
+    label: '极速升温',
+    cmdid: '170',
+    state: {
+      operate: 'manual',
+      temperature: '32',
+      windlevel: '7',
+      mode: 'hot',
+      circle: 'in',
+      wshld: '0',
+      position: 'all'
+    },
+    acceptsOperationPassword: true
+  },
+  windshieldDefrost: {
+    label: '前挡除雾',
+    cmdid: '170',
+    state: {
+      operate: 'manual',
+      temperature: '32',
+      windlevel: '7',
+      mode: 'hot',
+      circle: 'in',
+      wshld: '1',
+      position: 'all'
+    },
+    acceptsOperationPassword: true
+  },
+  custom: { label: '自定义命令', custom: true, acceptsOperationPassword: true }
+};
+
+export class LeapmotorChinaClient {
+  constructor(options = {}) {
+    this.sessionFile = options.sessionFile || DEFAULT_SESSION_FILE;
+    this.hosts = { ...HOSTS, ...(options.hosts || {}) };
+    this.allowWrite = Boolean(options.allowWrite);
+    this.state = {
+      deviceId: options.deviceId || crypto.randomUUID().replace(/-/g, ''),
+      appVersion: options.appVersion || DEFAULT_APP_VERSION,
+      subVersion: options.subVersion || DEFAULT_SUB_VERSION,
+      oldAuth: null,
+      newAuth: null,
+      vehicles: [],
+      selectedVin: '',
+      selectedCarType: '',
+      route: null
+    };
+  }
+
+  async loadSession() {
+    try {
+      const saved = JSON.parse(await readFile(this.sessionFile, 'utf8'));
+      if (saved.deviceId) this.state.deviceId = saved.deviceId;
+      if (saved.appVersion) this.state.appVersion = saved.appVersion;
+      if (saved.subVersion) this.state.subVersion = saved.subVersion;
+      this.state.oldAuth = saved.oldAuth || null;
+      this.state.newAuth = saved.newAuth
+        ? { ...saved.newAuth, signKey: Buffer.from(saved.newAuth.signKey || '', 'base64') }
+        : null;
+      this.state.vehicles = Array.isArray(saved.vehicles) ? saved.vehicles : [];
+      this.state.selectedVin = saved.selectedVin || '';
+      this.state.selectedCarType = saved.selectedCarType || '';
+      this.state.route = saved.route || null;
+      return { loaded: true, session: this.sessionSummary() };
+    } catch (error) {
+      if (error.code === 'ENOENT') return { loaded: false, session: this.sessionSummary() };
+      throw error;
+    }
+  }
+
+  async saveSession() {
+    await mkdir(path.dirname(this.sessionFile), { recursive: true });
+    await writeFile(this.sessionFile, JSON.stringify(this.serializeSession(), null, 2), { mode: 0o600 });
+    return this.sessionSummary();
+  }
+
+  async resetSession() {
+    this.state.oldAuth = null;
+    this.state.newAuth = null;
+    this.state.vehicles = [];
+    this.state.selectedVin = '';
+    this.state.selectedCarType = '';
+    this.state.route = null;
+    try {
+      await unlink(this.sessionFile);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    return this.sessionSummary();
+  }
+
+  serializeSession() {
+    return {
+      deviceId: this.state.deviceId,
+      appVersion: this.state.appVersion,
+      subVersion: this.state.subVersion,
+      oldAuth: this.state.oldAuth,
+      newAuth: this.state.newAuth
+        ? { ...this.state.newAuth, signKey: this.state.newAuth.signKey.toString('base64') }
+        : null,
+      vehicles: this.state.vehicles,
+      selectedVin: this.state.selectedVin,
+      selectedCarType: this.state.selectedCarType,
+      route: this.state.route,
+      savedAt: new Date().toISOString()
+    };
+  }
+
+  sessionSummary() {
+    return {
+      deviceId: this.state.deviceId,
+      oldLogin: Boolean(this.state.oldAuth?.token),
+      newLogin: Boolean(this.state.newAuth?.accessToken),
+      accountIdMasked: maskValue(this.state.newAuth?.accountId || this.state.oldAuth?.accountId || ''),
+      selectedVin: this.state.selectedVin,
+      selectedVinMasked: maskValue(this.state.selectedVin),
+      selectedCarType: this.state.selectedCarType,
+      vehicleCount: this.state.vehicles.length,
+      appRegion: this.state.route?.appRegion || '',
+      appCenter: this.state.route?.appCenter || '',
+      sessionFile: this.sessionFile
+    };
+  }
+
+  authDebugSummary() {
+    const auth = this.state.newAuth;
+    return {
+      oldTokenPresent: Boolean(this.state.oldAuth?.token),
+      newTokenPresent: Boolean(auth?.accessToken),
+      oldAccountIdMasked: maskValue(this.state.oldAuth?.accountId || ''),
+      newAccountIdMasked: maskValue(auth?.accountId || ''),
+      gatewayAccountIdMasked: maskValue(auth?.gatewayAccountId || ''),
+      signKeyBytes: auth?.signKey?.length || 0,
+      signKeySha256Prefix: auth?.signKey ? sha256(auth.signKey).slice(0, 12) : '',
+      tokenPayload: jwtPayloadSummary(auth?.accessToken || '', this.state)
+    };
+  }
+
+  async sendSms(phone) {
+    if (!phone) throw new Error('phone 不能为空');
+    const url = `${this.hosts.appUser}/app-user/applogin/compliance/sendmessagecode`;
+    return fetchJson(url, {
+      method: 'GET',
+      headers: this.oldAppHeaders(),
+      query: { phoneNo: phoneNoCiphertext(phone) }
+    });
+  }
+
+  async loginWithSms(options = {}) {
+    if (!options.phone || !options.smsCode) throw new Error('phone 和 smsCode 不能为空');
+    const url = `${this.hosts.appUser}/app-user/applogin/check_login_with_phone`;
+    const params = {
+      phoneNoCiphertext: phoneNoCiphertext(options.phone),
+      smsCode: options.smsCode,
+      deviceID: this.state.deviceId,
+      smDeviceId: options.smDeviceId || this.state.deviceId,
+      os: 'android',
+      pageUrl: options.pageUrl || ''
+    };
+    for (const key of ['oaid', 'referrer', 'captchaOutput', 'genTime', 'lotNumber', 'passToken', 'requestId']) {
+      if (options[key]) params[key] = options[key];
+    }
+    if (options.captchaPhone) params.phone = options.captchaPhone;
+
+    const loginResponse = await fetchJson(url, {
+      method: 'POST',
+      headers: this.oldAppHeaders(),
+      query: params,
+      queryPost: true
+    });
+    this.state.oldAuth = extractOldAuth(loginResponse);
+    const exchangeResponse = await this.exchangeNewGateway();
+    await this.saveSession();
+    return {
+      login: sanitizeLoginResponse(loginResponse),
+      exchanged: Boolean(this.state.newAuth?.accessToken),
+      exchangeCode: exchangeResponse?.result ?? exchangeResponse?.code ?? null,
+      signKeyBytes: this.state.newAuth?.signKey?.length || 0,
+      session: this.sessionSummary()
+    };
+  }
+
+  async exchangeNewGateway() {
+    this.requireOldAuth();
+    const url = `${this.hosts.global}/base/base-user/account/v1/login`;
+    const body = {
+      identifier: this.state.oldAuth.accountId,
+      identifierType: '1',
+      security: this.state.oldAuth.token
+    };
+    const response = await fetchJson(url, {
+      method: 'POST',
+      headers: this.newGatewayHeaders(body, false),
+      jsonBody: body
+    });
+    this.state.newAuth = extractNewAuth(response, this.state.oldAuth);
+    return response;
+  }
+
+  async refreshToken() {
+    this.requireNewAuth();
+    const url = `${this.hosts.global}/base/base-user/token/v1/refresh`;
+    const body = { refreshToken: this.state.newAuth.refreshToken };
+    const response = await fetchJson(url, {
+      method: 'POST',
+      headers: this.newGatewayHeaders(body, true),
+      jsonBody: body
+    });
+    this.state.newAuth = extractNewAuth(response, this.state.oldAuth);
+    await this.saveSession();
+    return { refreshed: true, session: this.sessionSummary() };
+  }
+
+  async listVehicles() {
+    this.requireNewAuth();
+    const url = `${this.hosts.global}/app/app-global-service/v1/vehicle/list`;
+    const response = await fetchJson(url, {
+      method: 'GET',
+      headers: this.newGatewayHeaders({}, true)
+    });
+    this.state.vehicles = vehicleListFromResponse(response);
+    if (!this.state.selectedVin && this.state.vehicles[0]?.vin) {
+      this.state.selectedVin = this.state.vehicles[0].vin;
+      this.state.selectedCarType = this.state.vehicles[0].carType || this.state.vehicles[0].cartype || '';
+      this.state.route = null;
+    }
+    await this.saveSession();
+    return { vehicles: this.state.vehicles, raw: response, session: this.sessionSummary() };
+  }
+
+  async selectVehicle(vin, carType = '') {
+    if (!vin) throw new Error('vin 不能为空');
+    this.state.selectedVin = String(vin);
+    const vehicle = this.state.vehicles.find((item) => item.vin === this.state.selectedVin);
+    this.state.selectedCarType = String(carType || vehicle?.carType || vehicle?.cartype || '');
+    this.state.route = null;
+    await this.saveSession();
+    return this.sessionSummary();
+  }
+
+  async getVehicleRoute() {
+    this.requireVin();
+    const url = `${this.hosts.global}/app/app-global-service/v1/vehicle/getCarRoute`;
+    const params = { vin: this.state.selectedVin };
+    const response = await fetchJson(url, {
+      method: 'GET',
+      headers: this.newGatewayHeaders(params, true),
+      query: params
+    });
+    this.state.route = routeFromResponse(response);
+    await this.saveSession();
+    return { route: this.state.route, raw: response, session: this.sessionSummary() };
+  }
+
+  async ensureRoute() {
+    this.requireVin();
+    if (this.state.route?.appRegion) return this.state.route;
+    await this.getVehicleRoute();
+    if (!this.state.route?.appRegion) throw new Error('车辆路由缺少 appRegion，无法继续');
+    return this.state.route;
+  }
+
+  async getVehicleState() {
+    const route = await this.ensureRoute();
+    const url = `${pickHost(route.appRegion)}/app/app-signal-service/signal/info/query`;
+    const body = { vin: this.state.selectedVin };
+    const raw = await fetchJson(url, {
+      method: 'POST',
+      headers: this.newGatewayHeaders(body, true),
+      jsonBody: body
+    });
+    return { raw, summary: vehicleStateSummary(raw), session: this.sessionSummary() };
+  }
+
+  async getMileageEnergy() {
+    this.requireVin();
+    const raw = await fetchFirstJson(await this.oldServiceCandidates(
+      '/carownerservice/v3/api/drivingrecord/mileage/energy/detail',
+      { vin: this.state.selectedVin }
+    ));
+    return { raw, session: this.sessionSummary() };
+  }
+
+  async getLocation() {
+    this.requireVin();
+    const raw = await fetchFirstJson(await this.oldServiceCandidates(
+      '/carownerservice/v3/api/chassis/query',
+      { vin: this.state.selectedVin }
+    ));
+    return { raw, session: this.sessionSummary() };
+  }
+
+  async getOverview() {
+    await this.ensureRoute();
+    const [route, carState, mileage, location] = await Promise.allSettled([
+      this.getVehicleRoute(),
+      this.getVehicleState(),
+      this.getMileageEnergy(),
+      this.getLocation()
+    ]);
+    return { route, carState, mileage, location, session: this.sessionSummary() };
+  }
+
+  buildCommand(input = {}) {
+    const preset = commandPresets[input.command || ''];
+    if (!preset) throw new Error(`未知控车命令: ${input.command}`);
+    let cmdid = preset.cmdid;
+    let stateJson;
+
+    if (preset.custom) {
+      cmdid = String(input.cmdid || '').trim();
+      if (!cmdid) throw new Error('自定义命令需要 cmdid');
+      stateJson = normalizeStateJson(input.stateJson);
+    } else if (preset.rawState) {
+      stateJson = normalizeStateJson(input.stateJson);
+    } else if (preset.stateFromValue) {
+      stateJson = JSON.stringify({ value: asString(input.value || '0') });
+    } else {
+      stateJson = JSON.stringify(preset.state);
+    }
+    return {
+      cmdid: String(cmdid),
+      state: stateJson,
+      label: preset.label,
+      acceptsOperationPassword: preset.acceptsOperationPassword === true
+    };
+  }
+
+  async previewControl(input = {}) {
+    const route = await this.ensureRoute();
+    const command = this.buildCommand(input);
+    const params = {
+      cmdid: command.cmdid,
+      state: command.state,
+      carvin: this.state.selectedVin
+    };
+    if (input.operationPassword) params.oppwd = encryptOperationPassword(input.operationPassword, this.state.oldAuth);
+    const signed = this.oldSignedParams(params);
+    const appointment = appointmentCmdIds.has(command.cmdid);
+    const host = appointment ? pickHost(route.appCenter || route.appRegion) : pickHost(route.appRegion);
+    const url = appointment
+      ? `${host}/carownerservice/v3/api/appremotectl/appointment`
+      : `${host}/app/app-control-service/v3/api/appremotectl`;
+    return {
+      dryRun: true,
+      appointment,
+      method: 'POST',
+      url,
+      command,
+      body: redactControlBody(signed),
+      session: this.sessionSummary()
+    };
+  }
+
+  async sendControl(input = {}) {
+    if (!this.allowWrite && input.allowWrite !== true) {
+      throw new Error('真实控车默认禁用：需要 SDK allowWrite=true 或参数 allowWrite=true');
+    }
+    if (input.confirm !== true) throw new Error('真实控车需要 confirm=true');
+    const preview = await this.previewControl(input);
+    const raw = await fetchJson(preview.url, {
+      method: 'POST',
+      headers: this.oldAppHeaders(),
+      formBody: this.oldSignedParams({
+        cmdid: preview.command.cmdid,
+        state: preview.command.state,
+        carvin: this.state.selectedVin,
+        ...(input.operationPassword
+          ? { oppwd: encryptOperationPassword(input.operationPassword, this.state.oldAuth) }
+          : {})
+      })
+    });
+    return { dryRun: false, command: preview.command, raw, session: this.sessionSummary() };
+  }
+
+  async queryControlResult(msgID) {
+    if (!msgID) throw new Error('msgID 不能为空');
+    const route = await this.ensureRoute();
+    const url = `${pickHost(route.appRegion)}/app/app-control-service/v3/api/appremotectl/query`;
+    const raw = await fetchJson(url, {
+      method: 'GET',
+      headers: this.oldAppHeaders(),
+      query: this.oldSignedParams({ msgID })
+    });
+    return { raw, session: this.sessionSummary() };
+  }
+
+  async oldServiceCandidates(pathname, params) {
+    const route = await this.ensureRoute();
+    const hosts = [this.hosts.global, pickHost(route.appRegion), pickHost(route.appCenter)].filter(Boolean);
+    return [...new Set(hosts)].map((host) => ({
+      label: host,
+      url: `${host}${pathname}`,
+      options: {
+        method: 'GET',
+        headers: this.oldAppHeaders(),
+        query: this.oldSignedParams(params)
+      }
+    }));
+  }
+
+  oldAppHeaders() {
+    const headers = {
+      APPPlatform: 'Android',
+      APPVersion: this.state.appVersion,
+      APPImei: this.state.deviceId,
+      'C-VERSIONS': 'APP',
+      'XFX-CDN-VRS': 'v4'
+    };
+    if (this.state.oldAuth?.token) headers['XFX-CDN-CROSS-NODE'] = this.state.oldAuth.token;
+    return headers;
+  }
+
+  newGatewayHeaders(params = {}, needLogin = true) {
+    const nonce = randomNonce();
+    const timestamp = String(Date.now());
+    const headers = {
+      source: 'leapmotor',
+      channel: '1',
+      acceptLanguage: 'zh-CN',
+      'x-region': 'CN',
+      'x-api-signature-version': '2.0',
+      digest: '',
+      version: this.state.appVersion,
+      deviceType: 'android',
+      nonce,
+      timestamp,
+      deviceId: this.state.deviceId,
+      userId: this.state.newAuth?.accountId || this.state.oldAuth?.accountId || '',
+      carvin: this.state.selectedVin || '',
+      cartype: this.state.selectedCarType || '',
+      'x-subversion': this.state.subVersion
+    };
+    const signHeaders = {
+      acceptLanguage: headers.acceptLanguage,
+      channel: headers.channel,
+      deviceId: headers.deviceId,
+      deviceType: headers.deviceType,
+      nonce: headers.nonce,
+      source: headers.source,
+      timestamp: headers.timestamp,
+      version: headers.version
+    };
+    const signBase = sortAndConcatValues(signHeaders, params);
+    if (needLogin) {
+      this.requireNewAuth();
+      headers.token = this.state.newAuth.accessToken;
+      headers.userId = this.state.newAuth.accountId || headers.userId;
+      headers.sign = crypto.createHmac('sha256', this.state.newAuth.signKey).update(signBase, 'utf8').digest('hex');
+    } else {
+      headers.sign = sha256(signBase);
+    }
+    return headers;
+  }
+
+  oldSignedParams(params = {}) {
+    this.requireOldAuth();
+    const map = {
+      timespan: String(Date.now()),
+      nonce: randomNonce(),
+      deviceID: this.state.deviceId,
+      token: this.state.oldAuth.token,
+      ...Object.fromEntries(Object.entries(params).map(([key, value]) => [key, asString(value)]))
+    };
+    const signStr = shortMd5(sortAndConcatValues(map));
+    delete map.token;
+    map.signStr = signStr;
+    return map;
+  }
+
+  requireOldAuth() {
+    if (!this.state.oldAuth?.token || !this.state.oldAuth?.accountId) {
+      throw new Error('还没有完成验证码登录，缺少旧 token/accountId');
+    }
+  }
+
+  requireNewAuth() {
+    if (!this.state.newAuth?.accessToken || !this.state.newAuth?.signKey || this.state.newAuth.signKey.length === 0) {
+      throw new Error('还没有完成新网关 token 交换，缺少 accessToken/signKey');
+    }
+  }
+
+  requireVin() {
+    if (!this.state.selectedVin) throw new Error('还没有选择车辆 VIN');
+  }
+}
+
+export function createClientFromEnv(options = {}) {
+  return new LeapmotorChinaClient({
+    sessionFile: process.env.LEAP_SESSION_FILE || options.sessionFile || path.resolve(process.cwd(), '.leap-session.json'),
+    deviceId: process.env.LEAP_DEVICE_ID || options.deviceId,
+    appVersion: process.env.LEAP_APP_VERSION || options.appVersion,
+    subVersion: process.env.LEAP_SUB_VERSION || options.subVersion,
+    allowWrite: process.env.LEAP_ALLOW_WRITE === '1' || options.allowWrite
+  });
+}
+
+export function vehicleStateSummary(raw) {
+  const signalMap = extractSignalMap(raw);
+  const pick = (...keys) => {
+    for (const key of keys) {
+      if (signalMap?.[key] !== undefined && signalMap?.[key] !== null) return signalMap[key];
+    }
+    return null;
+  };
+  return {
+    battery: {
+      soc: pick('soc'),
+      expectedMileage: pick('expectedMileage'),
+      batteryCurrent: pick('batteryCurrent'),
+      batteryVoltage: pick('batteryVoltage'),
+      chargeState: pick('chargeState'),
+      chargeRemainTime: pick('chargeRemainTime'),
+      dcInputFastCharge: pick('dcInputFastCharge'),
+      chargesocSetting: pick('chargesocSetting')
+    },
+    locks: {
+      driverDoorLockStatus: pick('driverDoorLockStatus'),
+      bcmDoorCtrlAllow: pick('bcmDoorCtrlAllow')
+    },
+    doors: {
+      driverDoor: pick('lbcmDriverDoorStatus'),
+      passengerDoor: pick('rbcmDriverDoorStatus'),
+      leftRearDoor: pick('lbcmLeftRearDoorStatus'),
+      rightRearDoor: pick('rbcmRightRearDoorStatus'),
+      trunk: pick('bbcmBackDoorStatus')
+    },
+    windows: {
+      isSupportWindowsRemoteControl: pick('isSupportWindowsRemoteControl'),
+      leftFrontWindowPercent: pick('leftFrontWindowPercent'),
+      leftRearWindowPercent: pick('leftRearWindowPercent'),
+      rightFrontWindowPercent: pick('rightFrontWindowPercent'),
+      rightRearWindowPercent: pick('rightRearWindowPercent')
+    },
+    climate: {
+      acSwitch: pick('acSwitch'),
+      acSetting: pick('acSetting'),
+      acAirVolume: pick('acAirVolume'),
+      acAirVolumeSetting: pick('acAirVolumeSetting'),
+      acWindDirection: pick('acWindDirection'),
+      acCircleMode: pick('acCircleMode'),
+      acCoolingAndHeating: pick('acCoolingAndHeating'),
+      acTempMode: pick('acTempMode'),
+      indoorTemp: pick('indoorTemp'),
+      ptcState: pick('ptcState'),
+      ptcPowerSettingValue: pick('ptcPowerSettingValue'),
+      minSingleTemp: pick('minSingleTemp')
+    },
+    location: {
+      latitude: pick('latitude'),
+      longitude: pick('longitude'),
+      privacyGPS: pick('privacyGPS'),
+      privacyData: pick('privacyData')
+    }
+  };
+}
+
+export function extractSignalMap(raw) {
+  return findObject(raw, (obj) => obj.signalMap && typeof obj.signalMap === 'object')?.signalMap
+    || raw?.data?.signalMap
+    || raw?.signalMap
+    || {};
+}
+
+function randomNonce() {
+  return String(Math.floor(Math.random() * 10_000_000) + 10_000);
+}
+
+function asString(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  return String(value);
+}
+
+function sortAndConcatValues(...maps) {
+  const merged = {};
+  for (const map of maps) {
+    if (!map) continue;
+    for (const [key, value] of Object.entries(map)) {
+      if (value !== null && value !== undefined) merged[key] = asString(value);
+    }
+  }
+  return Object.keys(merged).sort().map((key) => merged[key]).join('');
+}
+
+function shortMd5(input) {
+  return crypto.createHash('md5').update(input, 'utf8').digest('hex').slice(8, 24);
+}
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
+}
+
+function base64UrlNoPadding(buffer) {
+  return Buffer.from(buffer).toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '');
+}
+
+function base64UrlDecode(input) {
+  const normalized = input.replaceAll('-', '+').replaceAll('_', '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded, 'base64');
+}
+
+function phoneNoCiphertext(phone) {
+  const pem = ['-----BEGIN PUBLIC KEY-----', DEFAULT_PUBLIC_KEY, '-----END PUBLIC KEY-----'].join('\n');
+  const encrypted = crypto.publicEncrypt(
+    { key: pem, padding: crypto.constants.RSA_PKCS1_PADDING },
+    Buffer.from(phone, 'utf8')
+  );
+  return base64UrlNoPadding(encrypted);
+}
+
+function deriveSignKey(accessToken, r2, r3) {
+  const parts = String(accessToken || '').split('.');
+  if (parts.length !== 3) throw new Error('accessToken 不是三段式 token，无法计算 signKey');
+  const tokenTail = base64UrlDecode(parts[2]);
+  const r2Buf = Buffer.from(r2 || '', 'base64');
+  const r3Buf = Buffer.from(r3 || '', 'base64');
+  const len = Math.min(tokenTail.length, r2Buf.length, r3Buf.length);
+  const out = Buffer.alloc(len);
+  for (let i = 0; i < len; i += 1) out[i] = tokenTail[i] ^ r2Buf[i] ^ r3Buf[i];
+  return out;
+}
+
+function jwtPayloadSummary(token, state) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3) return { validJwtShape: false };
+  try {
+    const payload = JSON.parse(base64UrlDecode(parts[1]).toString('utf8'));
+    const userName = String(payload.user_name || payload.username || '');
+    const summary = {
+      validJwtShape: true,
+      keys: Object.keys(payload).sort(),
+      exp: payload.exp || null,
+      iat: payload.iat || null,
+      client_id: payload.client_id || '',
+      scope: payload.scope || '',
+      userNameContainsDeviceId: state.deviceId ? userName.includes(state.deviceId) : false,
+      userNameContainsOldAccountId: state.oldAuth?.accountId ? userName.includes(String(state.oldAuth.accountId)) : false,
+      userNameContainsNewAccountId: state.newAuth?.accountId ? userName.includes(String(state.newAuth.accountId)) : false
+    };
+    for (const key of ['accountId', 'account_id', 'sub', 'user_name', 'username']) {
+      if (payload[key] !== undefined && payload[key] !== null) summary[key] = maskValue(payload[key]);
+    }
+    return summary;
+  } catch {
+    return { validJwtShape: true, payloadParseError: true };
+  }
+}
+
+async function fetchJson(url, options = {}) {
+  const { method = 'GET', headers = {}, query, jsonBody, formBody, queryPost = false } = options;
+  const target = new URL(url);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) target.searchParams.set(key, asString(value));
+    }
+  }
+  const requestHeaders = { ...headers };
+  let body;
+  if (jsonBody !== undefined) {
+    requestHeaders['content-type'] = 'application/json; charset=utf-8';
+    body = JSON.stringify(jsonBody);
+  } else if (formBody !== undefined) {
+    requestHeaders['content-type'] = 'application/x-www-form-urlencoded; charset=utf-8';
+    body = queryString(formBody);
+  } else if (queryPost) {
+    body = '';
+  }
+  const response = await fetch(target, { method, headers: requestHeaders, body });
+  const text = await response.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+  if (!response.ok) {
+    const err = new Error(`HTTP ${response.status} ${response.statusText}`);
+    err.response = data;
+    throw err;
+  }
+  return data;
+}
+
+async function fetchFirstJson(candidates) {
+  const errors = [];
+  for (const candidate of candidates) {
+    try {
+      return await fetchJson(candidate.url, candidate.options);
+    } catch (error) {
+      errors.push(`${candidate.label || candidate.url}: ${error.message}`);
+    }
+  }
+  const err = new Error(errors.join(' | ') || '没有可尝试的请求地址');
+  err.attempts = errors;
+  throw err;
+}
+
+function queryString(params = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) search.set(key, asString(value));
+  }
+  return search.toString();
+}
+
+function extractOldAuth(loginResponse) {
+  const direct = loginResponse?.data?.appLoginVO || loginResponse?.data?.appOneLoginVO;
+  const auth = direct || findObject(loginResponse, (obj) => obj.accountId && obj.token);
+  if (!auth?.accountId || !auth?.token) throw new Error('验证码登录响应中没有找到 accountId/token');
+  return {
+    accountId: String(auth.accountId),
+    token: String(auth.token),
+    refreshToken: auth.refreshToken ? String(auth.refreshToken) : '',
+    nickname: auth.nickname || '',
+    tokenExpired: auth.tokenExpired || ''
+  };
+}
+
+function extractNewAuth(exchangeResponse, oldAuth) {
+  const data = exchangeResponse?.data || findObject(exchangeResponse, (obj) => obj.accessToken && obj.signParam);
+  if (!data?.accessToken || !data?.signParam?.r2 || !data?.signParam?.r3) {
+    throw new Error('新网关登录响应中没有找到 accessToken/signParam.r2/r3');
+  }
+  return {
+    accountId: String(oldAuth?.accountId || data.accountId || ''),
+    gatewayAccountId: data.accountId ? String(data.accountId) : '',
+    accessToken: String(data.accessToken),
+    refreshToken: data.refreshToken ? String(data.refreshToken) : '',
+    tokenExpireTime: data.tokenExpireTime || '',
+    nickname: data.nickname || '',
+    signParam: data.signParam,
+    encryptParam: data.encryptParam || null,
+    signKey: deriveSignKey(data.accessToken, data.signParam.r2, data.signParam.r3)
+  };
+}
+
+function sanitizeLoginResponse(raw) {
+  return {
+    code: raw?.code ?? raw?.result ?? raw?.status ?? null,
+    success: raw?.success ?? raw?.result === 0,
+    msg: raw?.msg || raw?.message || '',
+    risk_type: raw?.data?.risk_type || raw?.risk_type || '',
+    requestId: raw?.data?.requestId || raw?.requestId || '',
+    hasAppLoginVO: Boolean(raw?.data?.appLoginVO || raw?.data?.appOneLoginVO)
+  };
+}
+
+function vehicleListFromResponse(response) {
+  const vehicles = collectObjects(response, (obj) => typeof obj.vin === 'string' && obj.vin.length >= 8);
+  const byVin = new Map();
+  for (const vehicle of vehicles) {
+    if (!byVin.has(vehicle.vin)) byVin.set(vehicle.vin, vehicle);
+  }
+  return [...byVin.values()];
+}
+
+function routeFromResponse(response) {
+  return response?.data || findObject(response, (obj) => obj.appRegion || obj.appCenter) || null;
+}
+
+function encryptOperationPassword(password, oldAuth) {
+  if (!password) return '';
+  if (!oldAuth?.token || oldAuth.token.length < 64) {
+    throw new Error('旧 token 长度不足，无法按 App 规则加密操作密码');
+  }
+  const key = Buffer.from(shortMd5(oldAuth.token.slice(0, 32)), 'utf8');
+  const iv = Buffer.from(shortMd5(oldAuth.token.slice(32, 64)), 'utf8');
+  const cipher = crypto.createCipheriv('aes-128-cbc', key, iv);
+  return Buffer.concat([cipher.update(password, 'utf8'), cipher.final()]).toString('base64');
+}
+
+function normalizeStateJson(value) {
+  if (typeof value === 'object' && value !== null) return JSON.stringify(value);
+  const text = String(value || '').trim();
+  if (!text) throw new Error('state JSON 不能为空');
+  JSON.parse(text);
+  return text;
+}
+
+function redactControlBody(body) {
+  const out = { ...body };
+  if (out.oppwd) out.oppwd = `${String(out.oppwd).slice(0, 4)}...`;
+  if (out.signStr) out.signStr = `${String(out.signStr).slice(0, 6)}...`;
+  if (out.carvin) out.carvin = maskValue(out.carvin);
+  return out;
+}
+
+function pickHost(value) {
+  if (!value) return '';
+  return String(value).replace(/\/+$/g, '');
+}
+
+function findObject(root, predicate, seen = new Set()) {
+  if (!root || typeof root !== 'object' || seen.has(root)) return null;
+  seen.add(root);
+  if (predicate(root)) return root;
+  const values = Array.isArray(root) ? root : Object.values(root);
+  for (const value of values) {
+    const found = findObject(value, predicate, seen);
+    if (found) return found;
+  }
+  return null;
+}
+
+function collectObjects(root, predicate, seen = new Set(), out = []) {
+  if (!root || typeof root !== 'object' || seen.has(root)) return out;
+  seen.add(root);
+  if (predicate(root)) out.push(root);
+  const values = Array.isArray(root) ? root : Object.values(root);
+  for (const value of values) collectObjects(value, predicate, seen, out);
+  return out;
+}
+
+function maskValue(value) {
+  const str = String(value || '');
+  if (!str) return '';
+  if (str.length <= 8) return `${str.slice(0, 2)}***`;
+  return `${str.slice(0, 4)}...${str.slice(-4)}`;
+}