bili-rs 开发规范

Bilibili-cli 的 Rust 重写版本。单二进制可执行文件，无运行时依赖。功能与原始 Python 版本完全一致。

架构（严格分层）

cli/（仅 clap 结构体）  →  commands/（业务逻辑）  →  client/（HTTP 异步函数）
                                      ↓
                               payloads/（将原始 JSON 归一化为结构体）
                                      ↓
                               formatter.rs（JSON / YAML / Rich 格式输出）

约束规则：

• cli/ — 仅包含通过 clap derive 定义的结构体，不得包含任何业务逻辑
• commands/ — 只调用 client/，禁止直接构造 HTTP 请求
• client/ — 禁止导入 clap 或 formatter 相关模块

新增命令流程

1. 在 src/cli/.rs 中添加 clap 结构体
2. 在 src/commands/.rs 中添加处理函数
3. 在 src/client/.rs 中添加 API 调用逻辑
4. 如需，于 src/payloads/.rs 中添加 payload 归一化逻辑
5. 在 src/main.rs 的 run() 函数 match 分支中接入新命令

关键模式

错误处理

// client/ 层：始终映射 API 错误
let code = body["code"].as_i64().unwrap_or(-1);
if code != 0 {
    return Err(map_api_error(code, body["message"].as_str().unwrap_or("unknown")));
}

// commands/ 层
match result {
    Ok(data) => formatter::output(data, format),
    Err(e) => { emit_error(&e, format); std::process::exit(1); }
}

输出信封（字段名严禁变更）

SuccessEnvelope { ok: true, schema_version: "1", data: T }
ErrorEnvelope   { ok: false, schema_version: "1", error: ErrorBody }

输出格式判定优先级

--json > --yaml > $OUTPUT 环境变量 > TTY→Rich / 非 TTY→YAML

认证等级

• Optional — 若存在已保存凭据则加载，缺失时不报错
• Read — 必须提供 SESSDATA
• Write — 必须同时提供 SESSDATA 和 bili_jct

凭据文件路径：~/.bilibili-cli/credential.json（权限 0o600，有效期 7 天）

WBI 签名

部分 Bilibili 接口需 WBI 请求签名（一种按请求生成的类 HMAC 参数）。请使用 src/client/wbi.rs：

let (img_key, sub_key) = fetch_wbi_keys(cred).await?;
let params = sign_params(vec![("bvid".to_string(), bvid)], &img_key, &sub_key);
req = req.query(¶ms);

已知需 WBI 签名的接口：/x/web-interface/view/conclusion/get

输出与终端

• 状态信息 / 错误 → 使用 console::style 输出至 stderr
• 数据内容 → 以表格（comfy-table）、JSON 或 YAML 格式输出至 stdout
• 数值 ≥ 10000 时 → 使用 "X.X万" 格式（例如 12345 → "1.2万"）

质量门禁（每次提交前必须执行）

cargo build && cargo clippy -- -D warnings && cargo fmt --check && cargo test

参考文档

• 全部 CLI 命令与选项：参见 references/commands.md
• API 接口与 payload 结构：参见 references/api.md
• 完整项目需求说明：PRD.md（位于项目根目录）
• 实现约定规范：CLAUDE.md（位于项目根目录）