CONTRIBUTING.md

贡献指南

感谢你愿意改进 BiliScriptor。这个项目优先保持本地优先、可排障、可二次处理和隐私友好。

本地开发

uv sync
uv run biliscriptor --help

常用开发命令：

uv run biliscriptor parse BV1QEVY6jEYv
uv run biliscriptor report output/BV1QEVY6jEYv
uv run biliscriptor login

真实网络解析只作为手动烟测，不应写入自动化测试：

uv run biliscriptor parse "https://www.bilibili.com/video/BV11kVt6sEWA?"

测试

提交前请至少运行：

uv run pytest
uv pip check

pytest 是唯一权威测试入口。测试应避免真实网络调用；涉及 Bilibili API 的逻辑请使用 mock、fake opener 或代表性 payload。涉及 ASR、OCR 或抽帧的测试应使用 mock provider、假帧或临时文件，不依赖真实 API key、真实媒体文件或外部服务可用性。核心测试覆盖 Python 3.10-3.14；PaddleOCR 可选依赖按其上游支持的 Python 3.10-3.13 单独做导入烟测。

修改打包或依赖时还应运行 uv lock --check 和 uv build，并在干净环境安装 wheel 后执行 uv pip check。自动抽帧与音频切片只调用用户通过系统包管理器安装、且位于 PATH 中的 FFmpeg；仓库不维护 FFmpeg 下载脚本或二进制。

修改 manifest、续跑或校验逻辑时，请覆盖包内相对 POSIX 路径、移动数据包、旧绝对路径重定位、嵌套文件引用以及包外路径拒绝。阶段只有部分来源或页面成功时应保留已成功数据并使用 partial。

日志与隐私

开发新功能或修改关键流程时，应同步补充结构化日志事件，方便定位阶段状态、耗时、计数、请求和文件写入问题。

日志可以记录：

• URL 路径和查询参数键
• 状态码、阶段状态、耗时、计数
• 文件路径、输出字节数、错误类型、规范化状态码和安全提示
• cookie 名称

日志不能记录：

• cookie 值、SESSDATA、bili_jct、DedeUserID
• qrcode_key、csrf、token、w_rid
• WBI 签名、api_key、DASHSCOPE_API_KEY、通用 *_API_KEY、完整响应体
• 日志、manifest 或文档示例中的字幕正文、评论正文、弹幕正文

report.md 可以保留有数量上限、经过 Markdown/HTML 上下文转义的少量正文预览；不得直接拼接站点 HTML、图片语法或表格控制字符。Cookie 加载和持久化失败只记录错误类型、状态码和安全提示，不回显损坏文件内容。外部工具的 Cookie 文件必须由用户通过 --cookie-file 显式提供，不得从 manifest 读取凭据路径。

日志、manifest、失败计划和聚合报告不得持久化 traceback、任意异常正文或第三方 SDK 的自由文本错误；需要新增错误信息时应映射到受控的错误类型、规范化状态码和安全提示。

Pull Request

PR 请说明：

• 修改目的和主要行为变化
• 受影响的 CLI 命令
• 测试结果
• 是否影响日志、manifest、report 或隐私承诺

不要提交 runtime/、logs/、output/、cookie 文件或真实解析产物。