Imported from Orangedog0415/BiliCourseDigest (AGENTS.md). Install upstream with npx skills add Orangedog0415/BiliCourseDigest. Copyright stays with the author.

AGENTS.md — 给 Claude Code / Codex 等编码 Agent 的工作说明

本仓库 BiliCourseDigest 把 Bilibili 系列网课转成本地 Transcript。 Agent 在这里通常承担两类工作：

1. 总结课程（最常见）：用户说“总结 work/course1”之类的话；
2. 维护代码：修改 bili_course_digest/ 下的 Python 代码。

一、目录约定（每门课一个目录，例如 work/course1/）

时间戳跳转：B 站链接后加 ?t=秒数（链接里已有 ?p=2 时用 &t=秒数）， 例如 [00:24:18] → https://www.bilibili.com/video/BVxxxx?t=1458。

二、当用户说“总结 work/course1”时

第 0 步：准备

python -m bili_course_digest.cli status --out .\work\course1   # 查看进度并与磁盘对账
python -m bili_course_digest.cli index  --out .\work\course1   # 刷新 TRANSCRIPT_INDEX.md

（未激活 .venv 时，用 uv run bili-digest status --out .\work\course1 这种写法。）

• 若大量集未转写，先告诉用户，并询问是等待转写完成、还是只基于已有文稿总结。
• 已存在的 summaries/*.md、COURSE_OVERVIEW.md 默认不要覆盖；用户明确要求“重写 / 更新”时才覆盖。
• 同时参考 prompts/single_video_summary.md 与 prompts/course_summary.md 中的格式与规则（与本文件一致，更详细）。

第一阶段：课程地图（先建全局，再深入）

读取：manifest.md、manifest.json（标题、时长、所属列表）、TRANSCRIPT_INDEX.md， 以及必要时各集 Transcript 的开头 / 结尾（老师通常在开头说目标、在结尾总结或预告）。

先在心里（或 work/course1/_course_map.md 草稿中）建立：

• 整套课程的目标；
• 模块划分；
• 视频与模块的对应关系；
• 知识的前置依赖；
• 课程学习路线。

课程很长时，把这张地图作为后续逐集总结的上下文，保持术语一致。

第二阶段：逐集总结 → work/course1/summaries/<与 transcript 同名>.md

对每一集完整阅读 Transcript（不要只看预览），按以下结构输出：

# 001 本集标题
> 原视频：URL ｜ 时长：HH:MM:SS

## 本集目标
## 核心概念
## 详细知识点
## 方法 / 推导 / 步骤
## 案例
## 老师强调内容
## 易错点
## 关键结论          ← 每条尽量附 [HH:MM:SS]
## 识别存疑 / 待核对
## 与其它集的关联

规则：

• 忠实原文，不许凭空补知识；必要的补充解释用「（补充）」标出。
• 去口语化、去重复，但不删除定义、公式、步骤、条件、例子、数字。
• 公式用 LaTeX；口述公式无法确定时标「⚠️ 口述公式，需核对」。
• Whisper 可能把专业术语识别错：写成 正确术语 ⚠️ 原文识别为“xxx”，不要悄悄改掉。
• 关键结论、定义、例题附时间戳 [HH:MM:SS]，取自 Transcript 对应段落。
• 某小节确实没有内容就写“本集未涉及”，不要凑。
• 集数很多时可分批进行（例如每次 5 集），每写完一集就保存文件，便于中断后继续。

第三阶段：整课总结 → work/course1/COURSE_OVERVIEW.md

必须是跨视频的综合，而不是把各集 summary 拼起来。 至少包含：

• 课程总体目标
• 课程模块
• 模块对应视频
• 知识依赖图（可用 Mermaid）
• 老师反复强调的核心概念（注明出现于哪些集）
• 必须看的视频
• 适合倍速的视频
• 可按需跳过的视频
• 快速了解路线
• 系统学习路线
• 课程知识树

核查原则（重要）

• 不要完全相信已有 Summary（包括你自己之前写的）。整课总结里的重要结论、 “必须看 / 可跳过”的判断，如果不确定，回到对应 Transcript 查证。
• 引用时注明来源：（第 003 集 [00:24:18]）。
• Transcript 是语音识别结果，存在错误；上下文明显矛盾时以常识判断并标注存疑。

收尾

python -m bili_course_digest.cli status --out .\work\course1   # 自动把新写的 summaries 登记到 manifest
python -m bili_course_digest.cli index  --out .\work\course1

最后向用户汇报：生成了哪些文件、哪些集因未转写而跳过、有哪些存疑点需要人工回看视频。

三、维护代码时

• 入口：python -m bili_course_digest.cli；模块职责：
  • scanner.py URL 展开（全部交给 yt-dlp，不要逆向 B 站私有 API）
  • downloader.py 音频下载（默认 bestaudio/best，不转码）
  • transcriber.py faster-whisper 转写与 Markdown / SRT 渲染
  • manifest.py 状态读写（加锁 + 原子写，支持 download 与 transcribe 并行）
  • indexer.py / summarizer.py / providers/ 索引与可选 API 总结
  • utils.py 无依赖的纯函数（文件名、时间、范围解析、URL）
  • control.py 跨进程“完成当前集后停止”请求（.cache/stop_request）
  • gui/ Tkinter 图形界面：只通过子进程调用 CLI，不直接执行耗时任务；非界面逻辑放在 settings.py / commands.py / runner.py 并有测试
• API Key 只能通过环境变量传给子进程，不能出现在命令行参数或日志中。
• 环境用 uv 管理（pyproject.toml + uv.lock + .python-version）：uv sync / uv sync --extra api；新增依赖用 uv add， 并同步更新 requirements*.txt（给 pip 用户）。
• 修改后运行：uv run pytest（或 python -m pytest -q；测试不访问网络）。
• 新增 / 修改命令行参数时，同步更新 docs/COMMANDS.md（涉及 GPU / 服务器的还有 docs/SERVER.md）。
• 禁止：DRM / 付费内容 / 权限 / 登录限制的绕过；把 API Key 写进源码；自动删除音频；默认覆盖用户的 Transcript / Summary。
• Cookie 只通过 --cookies-from-browser 读取用户自己已登录的浏览器，不要求导出明文 Cookie 文件。