dongchedi-cli

懂车帝（www.dongchedi.com）数据查询 CLI。免登录命令走 PC 站公开 JSON 接口；登录命令读取浏览器登录态，走 HTML 页面的 SSR 数据。无第三方依赖（纯标准库）。

安装

uv tool install dongchedi-cli    # 从 PyPI 安装；也可 pipx install dongchedi-cli 或 pip install dongchedi-cli

# 从源码安装（开发）
uv tool install --editable scripts/dongchedi-cli
# 免安装临时运行
PYTHONPATH=scripts/dongchedi-cli/src python3 -m dongchedi_cli.cli rank

用法

# ---- 免登录 ----
dcd rank                          # 销量总榜（默认前 20，全国零售量）
dcd rank -c 杭州 -n 50            # 指定城市与条数（注意：榜单仍是全国榜，仅指导价按城市变化）
dcd rank --local -c 杭州          # 杭州城市榜：本地新车上牌量（共 317 款车系）
dcd brands -f J                   # 品牌列表，按名称/首字母过滤
dcd series 858                    # 吉利银河下的全部车系（含指导价/经销商价/评分）
dcd filter --price 10,20 --fuel 纯电 --body 轿车   # 车型库筛选：10-20万纯电轿车
dcd filter --body 小型SUV         # 全部小型SUV（级别细分，如 紧凑型SUV/中大型车/中型MPV）
dcd filter --price 10, --fuel 新能源 --sort 销量高 -n 50   # 10万以上新能源，按销量排序
dcd cars 20154                    # 星愿的车型年款与价格（含停售/未上市）
dcd specs 20154 259371            # 车型参数配置表
dcd specs 20154 259371 259369 -s 电池   # 多车对比，只看"电池"章节
dcd reviews 20154 -p 1 -n 20      # 车主评论（含成交价/评分）
dcd search 秦plus                 # 搜车系
dcd dealer 259371                 # 某车型的经销商报价与优惠（默认杭州）
dcd dealer 259371 259369 -c 上海  # 多车型对比、指定城市

# ---- 需登录态（见下方「登录态」）----
dcd series-info 20154             # 车系主页 SSR：概览/评分/价格卡/经销商
dcd series-info 20154 -s dealers  # 只看经销商（overview/scores/price/dealers）
dcd series-info 20154 -c 北京     # 指定城市（覆盖登录态里的城市 Cookie）
dcd me                            # 当前登录账号信息

# 任意命令加 --json 输出原始数据

典型链条：dcd brands -f 吉利 → dcd series 858 → dcd cars 20154 → dcd specs 20154 <车型ID>。

表格结果输出到 stdout，进度/提示输出到 stderr，可安全重定向。

登录态

series-info / me 需要已登录懂车帝的 Cookie。获取流程（配合 playwright-cli）：

playwright-cli open https://www.dongchedi.com --persistent   # 登录（拼图滑块 + 短信验证码）
playwright-cli state-save scripts/dongchedi-cli/.auth/state.json
dcd auth-import scripts/dongchedi-cli/.auth/state.json       # 提取 Cookie 并当场校验
# → 写入 ~/.config/dcd/cookies.txt（chmod 600），文件含 sessionid，勿提交

Cookie 文件解析优先级：--cookie-file 参数 → DCD_COOKIE_FILE 环境变量 → ~/.config/dcd/cookies.txt。 登录态过期后（报错提示会话过期）重新登录并重跑 state-save + auth-import 即可。

已验证接口（2026-09 实测）

公共参数 aid=1839&app_name=auto_web_pc；请求头用桌面 Chrome UA。

注意事项

• HTML 路由（/auto/series/*、/auto/params-*）无登录一律 302 到 /login-required；只有带完整登录 Cookie 才能拿到 SSR 数据（仅有 ttwid/tt_webid 不够）。
• HTML 路由有 CDN 缓存且缓存键不含 Cookie，会串城市数据；CLI 已自动附加 ?_r=<毫秒时间戳> 破缓存。
• 城市由 city_name Cookie 控制且值为 percent-encoded（如 %E6%9D%AD%E5%B7%9E），URL 上的 city_name 参数会被页面逻辑忽略；CLI 的 -c 已按此处理。
• 登录态 Cookie 含中文值，urllib 请求头默认 latin-1 编码，发送前已转 UTF-8 裸字节（与浏览器线上行为一致）。
• 参数配置表字段：data.properties[] 为行定义（type 0/2 为章节标题，1 普通行，3 带子项，6 跳过），值在 data.car_info[].info[<key>].value；type 3 的值挂在 sub_list[].key 上。注意 type 字段时而为 int 时而为字符串，代码里已统一归一化。
• 车型库筛选中 series_type 与 outter_detail_type 互斥：同传时服务端会忽略后者（按大类返回）；CLI 的 --body 已自动只传其一（轿车/SUV 传 series_type，小型SUV 等细分传 outter_detail_type）。
• 接口可能随版本变化（版本参数当前为 version_code=476），失效时优先用 --json 排查原始返回。

开发与发布

开发与发布由 Makefile 管理（make help 查看全部目标）：

make lint            # ruff 检查
make smoke           # 走工作区源码对真实接口冒烟（覆盖全部免登录命令，需外网）
make bump part=minor # 升版本号（同步 pyproject.toml 与 __init__.py）
make check           # 离线校验：lint + 构建 + 版本一致性 + twine 元数据检查
make publish-test    # 发布到 TestPyPI 预演（token 放 ~/.config/dcd/testpypi-token）
make publish         # 发布到 PyPI（token 放 ~/.config/dcd/pypi-token）
make release         # 一键发布：check → smoke → bump → publish → tag

发布前在 pypi.org 生成 API token（Account settings → API tokens；首次发布 scope 只能选 "Entire account"，项目建好后可换成项目级）， 存到 ~/.config/dcd/pypi-token（chmod 600）即可，或临时 export UV_PUBLISH_TOKEN=pypi-xxx 覆盖。