bb-sync 2.0.0__tar.gz → 2.1.1__tar.gz

{bb_sync-2.0.0 → bb_sync-2.1.1}/AGENTS.md

@@ -69,6 +69,9 @@ uv run pyright
 ### 1. 输出通道：stdout 只放结果，stderr 只放诊断
 
 - 所有输出走 `core.output.Console`，**禁止直接 `print`**。
+- 诊断行需要强调时用 `console.line((文本, 样式), ...)` 并引用 `output.STYLE_*` 语义色板，
+  不要在调用点新造颜色名；**不要打开 Rich markup**——诊断里到处是 `[new]`、`[作业]`
+  这类方括号文本，会被当成标签。着色在非 TTY、`NO_COLOR`、`--json` 下自动关闭。
 - `--json` 时 stdout 有且仅有一个 JSON 文档；出错时 stdout 保持为空，错误走 stderr。
 - 新增命令或字段时，同步更新 `docs/scripting.md` 的 JSON 结构表与对应测试。
 

{bb_sync-2.0.0 → bb_sync-2.1.1}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.1.1] — 2026-10-31
+
+### 变更
+
+- `run` / `due` 不再逐课程打印「待办 xN，公告测验/考试 xM」：这几行与末尾的
+  「待办明细」定位重复，只有计数、看不到内容。待办结果统一在「待办明细」与
+  `due.md` 中呈现；抓取失败仍会即时告警。
+
+## [2.1.0] — 2026-10-31
+
+### 新增
+
+- `bb-sync run` 在「汇总」之后新增「新下载明细」，逐行列出本轮真正新落盘的文件
+  及其课程（相对课程目录的路径，作业带 `hwN/`），例如
+  `[new] CSC5010 | assignments/hw2/report.pdf`；没有新文件时不打印。`--json run`
+  同步增加 `files` 数组（`course` / `category` / `name` / `path`，其中 `path` 为
+  绝对路径），脚本可以直接取用。
+- 诊断输出改用语义色板：章节标题加粗、课程代码与 `[due]` / `[new]` 前缀青色、
+  新下载绿色、dry-run 与待办黄色、逾期红色、测验 / 考试徽标紫色、关键数字加粗，
+  正文从淡灰色恢复为终端默认前景色。颜色只在 `core/output.py` 定义一处；新增
+  `Console.line((文本, 样式), ...)` 按片段上色，不启用 Rich markup——诊断里的
+  方括号文本（`[new]`、`[作业]`）不会被误判成标签。
+- 着色随终端能力自动开关：输出被重定向、终端不支持颜色、设置 `NO_COLOR`
+  （任意非空值）或 `--json` 时都不输出转义序列，stdout 的 JSON 保持纯净。
+
 ## [2.0.0] — 2026-10-14
 
 ### 变更（破坏性）

{bb_sync-2.0.0 → bb_sync-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bb-sync
-Version: 2.0.0
+Version: 2.1.1
 Summary: 港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办
 Project-URL: Homepage, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync
 Project-URL: Repository, https://github.com/asdukw/cuhk-shenzhen-blackboard-sync

{bb_sync-2.0.0 → bb_sync-2.1.1}/docs/scripting.md

@@ -12,6 +12,10 @@ bb-sync 按 Unix CLI 惯例严格分流输出：**结果走 stdout，诊断走 s
 
 > 自动更新检查的提示也走 stderr，不会污染 stdout；`--quiet` 下会跳过检查。
 
+彩色只在交互式终端里启用：stdout 被重定向、终端不支持颜色、设置了 `NO_COLOR`
+（任意非空值）或加了 `--json` 时都会自动关闭。所以 `bb-sync run 2>&1 | tee log.txt`
+这类管道里拿到的是纯文本，stdout 的 JSON 更是永远不含转义序列。
+
 ## `--json`：机器可读输出
 
 `--json` 是**全局选项**，位置在子命令之前：
@@ -35,7 +39,7 @@ bb-sync --json doctor       | jq '.ok'
 | 命令 | stdout 的 JSON |
 | --- | --- |
 | `course list` | 数组：`[{"id","code","title","folder"}, ...]` |
-| `run` | 对象：`{"downloaded","exists","would_download","empty","failed","courses"}` |
+| `run` | 对象：`{"downloaded","exists","would_download","empty","failed","courses","files"}`；`files` 是本次**真正新落盘**的文件（dry-run 时为空），元素为 `{"course","category","name","path"}`——`name` 相对课程目录、`path` 为绝对路径 |
 | `due` | 对象：`{"path","total","failed","announcement_failed","courses","items"}`；`items` 含课程、标题、类型（`task` / `quiz` / `exam`）与 ISO 日期 |
 | `doctor` | 对象：`{"ok": bool, "checks": [{"label","ok","detail","hint","required"}]}` |
 | `doctor --list` | 对象：`{"checks": ["python","git", ...]}` |

{bb_sync-2.0.0 → bb_sync-2.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bb-sync"
-version = "2.0.0"
+version = "2.1.1"
 description = "港中深（CUHK-Shenzhen）Blackboard 课件下载与课程资源自动同步：登录 ADFS SSO，增量下载课件/作业/指导、公告与待办"
 readme = "README.md"
 license = { file = "LICENSE" }

{bb_sync-2.0.0 → bb_sync-2.1.1}/src/bb_sync/blackboard/downloader.py

@@ -192,8 +192,11 @@ def _content_length(headers) -> int | None:
         return None
 
 
-def _category_dir(course_dir: Path, item: FileItem) -> Path:
-    """条目落盘目录；作业按 hwN 归档，对齐已有目录习惯。"""
+def category_dir(course_dir: Path, item: FileItem) -> Path:
+    """条目落盘目录；作业按 hwN 归档，对齐已有目录习惯。
+
+    对外的唯一含义是「这个条目会写到哪里」，汇总明细与真实写入共用它。
+    """
     cat_dir = course_dir / item.category
     if item.category == "assignments" and item.name:
         m = HW_NUM.search(item.name)
@@ -202,7 +205,7 @@ def _category_dir(course_dir: Path, item: FileItem) -> Path:
     return cat_dir
 
 
-def _relpath(path: Path, course_dir: Path) -> str:
+def relative_path(path: Path, course_dir: Path) -> str:
     """相对课程目录的展示路径；跨盘等取不到相对路径时退回文件名。"""
     try:
         return str(path.relative_to(course_dir)).replace("\\", "/")
@@ -262,12 +265,12 @@ class DownloadSession:
 
         状态取值：``downloaded`` / ``exists`` / ``would-download`` / ``empty``。
         """
-        cat_dir = _category_dir(course_dir, item)
+        cat_dir = category_dir(course_dir, item)
         name, size = self.probe(item)
 
         already = _index_match(index, name, size)
         if already is not None:
-            return ("exists", _relpath(already, course_dir))
+            return ("exists", relative_path(already, course_dir))
         target = cat_dir / name
         if target.exists():
             return ("exists", target.name)
@@ -344,5 +347,7 @@ __all__ = [
     "SIZE_DEDUP_THRESHOLD",
     "SNIFF_BYTES",
     "build_index",
+    "category_dir",
+    "relative_path",
     "sniff_ext",
 ]

{bb_sync-2.0.0 → bb_sync-2.1.1}/src/bb_sync/blackboard/models.py

@@ -76,6 +76,24 @@ class DueItem:
         }
 
 
+@dataclass(frozen=True)
+class SavedFile:
+    """本次同步新落盘的一个文件。"""
+
+    course: str  # 课程代码；没有代码时退回课程标题
+    category: str  # lectures / assignments / tutorials / other
+    name: str  # 相对课程目录的路径，如 assignments/hw2/report.pdf
+    path: str = ""  # 绝对路径，便于脚本直接取用
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "course": self.course,
+            "category": self.category,
+            "name": self.name,
+            "path": self.path,
+        }
+
+
 @dataclass
 class SyncStats:
     """一次同步的统计结果。"""
@@ -86,6 +104,8 @@ class SyncStats:
     empty: int = 0
     failed: int = 0
     courses: list[str] = field(default_factory=list)
+    #: 本次真正新落盘的文件（不含已存在 / dry-run），供末尾明细与 --json 使用
+    files: list[SavedFile] = field(default_factory=list)
 
     def bump(self, status: str) -> None:
         key = status.replace("-", "_")
@@ -100,6 +120,7 @@ class SyncStats:
             "empty": self.empty,
             "failed": self.failed,
             "courses": self.courses,
+            "files": [saved.as_dict() for saved in self.files],
         }
 
 
@@ -139,5 +160,6 @@ __all__ = [
     "DueItem",
     "DueStats",
     "FileItem",
+    "SavedFile",
     "SyncStats",
 ]

{bb_sync-2.0.0 → bb_sync-2.1.1}/src/bb_sync/core/output.py

@@ -14,8 +14,13 @@ stderr                  日志 / 进度 / 警告 / 错误    人读，或 ``2>/d
 1. **结果输出**（``result`` / ``table`` / ``emit``）—— 支持「人读」与「JSON」双模式。
    机器模式（``--json``）下，只有 ``emit`` 会往 stdout 吐**一个** JSON 文档，
    Rich 表格与人类可读文本全部被抑制，保证 stdout 是干净可解析的。
-2. **诊断输出**（``log`` / ``warn`` / ``error`` / ``success`` / ``hint``）—— 一律走 stderr，
-   且随 ``--quiet`` 降级。
+2. **诊断输出**（``log`` / ``line`` / ``warn`` / ``error`` / ``success`` / ``hint``）——
+   一律走 stderr，且随 ``--quiet`` 降级。
+
+**颜色**：诊断用下面 :data:`STYLE_*` 这套语义色板——16 色 ANSI 基本色，浅色 / 深色
+主题都交给终端映射；颜色只做强调，状态同时用符号和文字表达，重定向或色觉差异下
+依然分得清。着色由 Rich 按终端能力自动开关：非 TTY、设置 ``NO_COLOR`` 或 ``--json``
+时都不会输出转义序列，stdout 永远保持干净。
 """
 
 from __future__ import annotations
@@ -27,8 +32,21 @@ from typing import Any
 
 from rich.console import Console as RichConsole
 from rich.table import Table
-
-_NO_COLOR_ENV = "NO_COLOR"
+from rich.text import Text
+
+# ---------------------------------------------------------------- 语义色板
+#
+# 只用 16 色 ANSI 基本色，不写死 256 色 / 真彩色代码：浅色和深色主题都由终端
+# 映射到合适的对比度，不会出现「白底上看不清的亮黄」。命令里只引用这些名字，
+# 不在调用点随手挑颜色，保证整条输出看起来是一套设计。
+STYLE_TEXT = ""  # 正文：空样式 = 终端默认前景色，不多发一条转义序列
+STYLE_MUTED = "dim"  # 次要信息：路径、计数单位、分隔符
+STYLE_ACCENT = "cyan"  # 标识符：课程代码、命令名
+STYLE_SUCCESS = "green"  # 成功 / 新下载
+STYLE_WARN = "yellow"  # 警告 / 待办
+STYLE_ERROR = "bold red"  # 失败 / 逾期
+STYLE_BADGE = "magenta"  # 类型徽标：测验 / 考试
+STYLE_HEADING = "bold"  # 强调的正文、关键数字
 
 
 class Console:
@@ -55,12 +73,31 @@ class Console:
 
     # ------------------------------------------------------------ 诊断（stderr）
     def log(self, message: str = "", *, level: str = "info") -> None:
-        """常规日志 → stderr。``--quiet`` 时不显示。"""
+        """常规日志 → stderr。``--quiet`` 时不显示。
+
+        正文用终端默认前景色；``level="muted"`` 才是淡色次要信息。
+        """
         if self.quiet:
             return
-        style = {"info": "dim", "step": "cyan"}.get(level, "dim")
+        style = {"info": STYLE_TEXT, "muted": STYLE_MUTED, "step": STYLE_ACCENT}.get(
+            level, STYLE_TEXT
+        )
         self._err.print(message, style=style, markup=False, highlight=False)
 
+    def line(self, *segments: tuple[str, str]) -> None:
+        """按 ``(文本, 样式)`` 片段输出一行诊断到 stderr，``--quiet`` 时不显示。
+
+        为什么不用 Rich 的 markup：诊断里到处都是 ``[new]``、``[作业]`` 这类方括号
+        文本，全局打开标签解析会被误判成样式甚至报错。片段式拼接只给需要强调的部分
+        上色，其余保持原样。
+        """
+        if self.quiet:
+            return
+        text = Text()
+        for chunk, style in segments:
+            text.append(chunk, style=style)
+        self._err.print(text, markup=False, highlight=False)
+
     def step(self, message: str) -> None:
         """阶段性标题 → stderr，如 ``[scan] 获取课程列表 ...``。"""
         if self.quiet:
@@ -91,9 +128,9 @@ class Console:
             self._err.print(f"[debug] {message}", style="dim", markup=False, highlight=False)
 
     def rule(self, title: str = "") -> None:
-        """分隔线 → stderr。"""
+        """分隔线 → stderr：标题加粗，线条淡色（装饰性，不与内容抢注意力）。"""
         if not self.quiet:
-            self._err.rule(title, style="dim")
+            self._err.rule(Text(title, style=STYLE_HEADING) if title else "", style=STYLE_MUTED)
 
     # ------------------------------------------------------------ 结果（stdout）
     def emit(self, data: Any) -> None:
@@ -148,4 +185,14 @@ class Console:
         self._out.print(text, markup=False, highlight=False, soft_wrap=True)
 
 
-__all__ = ["Console"]
+__all__ = [
+    "STYLE_ACCENT",
+    "STYLE_BADGE",
+    "STYLE_ERROR",
+    "STYLE_HEADING",
+    "STYLE_MUTED",
+    "STYLE_SUCCESS",
+    "STYLE_TEXT",
+    "STYLE_WARN",
+    "Console",
+]

{bb_sync-2.0.0 → bb_sync-2.1.1}/src/bb_sync/core/service.py

@@ -19,12 +19,29 @@ from playwright.sync_api import sync_playwright
 
 from bb_sync.blackboard import downloader, scraper
 from bb_sync.blackboard.login import ensure_login
-from bb_sync.blackboard.models import Course, DueItem, DueStats, FileItem, SyncStats
+from bb_sync.blackboard.models import (
+    Course,
+    DueItem,
+    DueStats,
+    FileItem,
+    SavedFile,
+    SyncStats,
+)
 from bb_sync.browser import launcher
 from bb_sync.core import due
 from bb_sync.core.config import Settings
 from bb_sync.core.errors import ConfigError, NetworkError, NotFoundError
-from bb_sync.core.output import Console
+from bb_sync.core.output import (
+    STYLE_ACCENT,
+    STYLE_BADGE,
+    STYLE_ERROR,
+    STYLE_HEADING,
+    STYLE_MUTED,
+    STYLE_SUCCESS,
+    STYLE_TEXT,
+    STYLE_WARN,
+    Console,
+)
 
 
 @dataclass
@@ -149,7 +166,15 @@ def sync_course(
     settings = options.settings
     keywords = settings.keywords
 
-    console.step(f"=== {course.code or '?'} | {course.title} → {course_dir} ===")
+    console.line(
+        ("=== ", STYLE_MUTED),
+        (course.code or "?", f"{STYLE_ACCENT} {STYLE_HEADING}"),
+        (" | ", STYLE_MUTED),
+        (course.title, STYLE_HEADING),
+        (" → ", STYLE_MUTED),
+        (str(course_dir), STYLE_MUTED),
+        (" ===", STYLE_MUTED),
+    )
     if not options.dry_run:
         course_dir.mkdir(parents=True, exist_ok=True)
 
@@ -159,7 +184,8 @@ def sync_course(
     all_items: list[FileItem] = []
     visited: set[str] = set()
     menu = scraper.collect_menu_links(page, course)
-    console.log("    内容区: " + (", ".join(n for _, n in menu) or "(无)"))
+    areas = ", ".join(n for _, n in menu) or "(无)"
+    console.line(("    内容区: ", STYLE_MUTED), (areas, STYLE_TEXT))
     for area_url, area_name in menu:
         all_items += scraper.find_files(
             page, area_url, area_name, 1, settings.max_depth, keywords, visited
@@ -169,9 +195,14 @@ def sync_course(
     uniq: dict[str, FileItem] = {}
     for item in all_items:
         uniq.setdefault(item.url, item)
-    console.log(f"    发现 {len(uniq)} 个文件")
+    console.line(
+        ("    发现 ", STYLE_MUTED),
+        (str(len(uniq)), STYLE_HEADING),
+        (" 个文件", STYLE_MUTED),
+    )
 
     index = downloader.build_index(course_dir)
+    label = course.code or course.title
     for item in uniq.values():
         try:
             status, name = downloads.download_item(item, course_dir, options.dry_run, index)
@@ -180,17 +211,43 @@ def sync_course(
             console.warn(f"    [{item.category}] 下载失败: {exc}")
             continue
         stats.bump(status)
+        if status == "downloaded":
+            _record_saved(stats, label, course_dir, item, name)
         _log_item(console, status, item.category, name)
 
 
+def _record_saved(
+    stats: SyncStats, course_label: str, course_dir: Path, item: FileItem, name: str
+) -> None:
+    """把本次新落盘的文件记入明细，供末尾汇总与 ``--json`` 使用。
+
+    落盘位置直接复用 :func:`bb_sync.blackboard.downloader.category_dir`，
+    与真实写入保持同一套目录规则（作业会落到 ``assignments/hwN/``）。
+    """
+    target = downloader.category_dir(course_dir, item) / name
+    stats.files.append(
+        SavedFile(
+            course=course_label,
+            category=item.category,
+            name=downloader.relative_path(target, course_dir),
+            path=str(target),
+        )
+    )
+
+
 def _log_item(console: Console, status: str, category: str, name: str) -> None:
-    """按状态打印单条下载结果（全部走 stderr）。"""
+    """按状态打印单条下载结果（全部走 stderr）。
+
+    状态用符号 + 颜色双重表达（``↓`` 绿 = 新下载、``=`` 淡 = 已存在、
+    ``?`` 黄 = dry-run），丢掉颜色后依然一眼分得清。
+    """
+    badge = (f"[{category}] ", STYLE_MUTED)
     if status == "downloaded":
-        console.log(f"    ↓ [{category}] {name}")
+        console.line(("    ↓ ", STYLE_SUCCESS), badge, (name, STYLE_TEXT))
     elif status == "would-download":
-        console.log(f"    ? [{category}] {name} (dry-run)")
+        console.line(("    ? ", STYLE_WARN), badge, (f"{name} (dry-run)", STYLE_TEXT))
     elif status == "exists":
-        console.log(f"    = [{category}] {name} (已存在，跳过)")
+        console.line(("    = ", STYLE_MUTED), badge, (f"{name} (已存在，跳过)", STYLE_MUTED))
     elif status == "empty":
         console.warn(f"    [{category}] {name} 内容为空，跳过")
 
@@ -201,12 +258,22 @@ def _print_plan(console: Console, courses: list[Course], root: Path, dry_run: bo
     每个课程目录都显示为**绝对路径**——相对路径容易让人误判落盘位置。
     """
     console.rule("同步计划")
-    console.log(f"根目录: {root}")
-    console.log("课程目录:")
+    console.line(("根目录: ", STYLE_MUTED), (str(root), STYLE_TEXT))
+    console.log("课程目录:", level="muted")
     for course in courses:
         label = course.code or course.title
-        console.log(f"  {label:<10} → {root / course.slug}")
-    console.log(f"合计 {len(courses)} 门课程" + ("（dry-run，不会写入）" if dry_run else ""))
+        console.line(
+            ("  ", STYLE_TEXT),
+            (f"{label:<10}", STYLE_ACCENT),
+            (" → ", STYLE_MUTED),
+            (str(root / course.slug), STYLE_MUTED),
+        )
+    console.line(
+        ("合计 ", STYLE_MUTED),
+        (str(len(courses)), STYLE_HEADING),
+        (" 门课程", STYLE_MUTED),
+        ("（dry-run，不会写入）" if dry_run else "", STYLE_WARN),
+    )
     console.log("")
 
 
@@ -236,12 +303,6 @@ def _scan_due_items(page, courses: list[Course], console: Console) -> DueScan:
             scan.both_failed += 1
         scan.items.extend(todo_items)
         scan.items.extend(announcement_items)
-        parts = []
-        if todo_ok:
-            parts.append(f"待办 x{len(todo_items)}")
-        if announcement_items:
-            parts.append(f"公告测验/考试 x{len(announcement_items)}")
-        console.log(f"    {label}: {'，'.join(parts) if parts else '未读取到内容'}")
     scan.items = due.sort_due_items(scan.items)
     return scan
 
@@ -296,20 +357,30 @@ def run_sync(options: SyncOptions) -> SyncStats:
                 message = "Congratulations! 没有待办"
             else:
                 message = f"待办 {len(due_items)} 项"
-            console.log(f"[due] {message}（dry-run，未写入 due.md）")
+            console.line(
+                ("[due] ", STYLE_ACCENT),
+                (f"{message}（dry-run，未写入 due.md）", STYLE_MUTED),
+            )
         elif scan.both_failed == len(courses):
             console.warn("[due] 所有课程待办抓取失败，保留现有 due.md")
         else:
             due.write_due_markdown(due_path, courses, due_items, failed=scan.incomplete)
             if due_items:
-                console.log(f"[due] {len(due_items)} 项 → due.md")
+                console.line(
+                    ("[due] ", STYLE_ACCENT), (f"{len(due_items)} 项 → due.md", STYLE_TEXT)
+                )
             elif scan.incomplete:
-                console.log("[due] 未读取到待办（部分课程失败）→ due.md")
+                console.line(
+                    ("[due] ", STYLE_ACCENT), ("未读取到待办（部分课程失败）→ due.md", STYLE_MUTED)
+                )
             else:
-                console.log("[due] Congratulations! 没有待办 → due.md")
+                console.line(
+                    ("[due] ", STYLE_ACCENT), ("Congratulations! 没有待办 → due.md", STYLE_SUCCESS)
+                )
 
     # 浏览器由 browser_session 收尾：默认已关闭（--keep-open 则留在后台）
     _print_summary(console, stats, options.dry_run)
+    _print_saved_files(console, stats.files)
     if scan.both_failed < len(courses):
         _print_due_details(console, due_items, scan.incomplete)
     return stats
@@ -319,11 +390,44 @@ def _print_summary(console: Console, stats: SyncStats, dry_run: bool) -> None:
     """汇总输出（stderr，人读）。"""
     console.rule("汇总")
     if dry_run:
-        console.log(f"待下载: {stats.would_download} 个文件（未实际下载）")
+        console.line(
+            ("待下载: ", STYLE_TEXT),
+            (str(stats.would_download), f"{STYLE_HEADING} {STYLE_WARN}"),
+            (" 个文件（未实际下载）", STYLE_MUTED),
+        )
     else:
-        console.log(f"新下载 {stats.downloaded} 个，已存在跳过 {stats.exists} 个")
+        console.line(
+            ("新下载 ", STYLE_TEXT),
+            (str(stats.downloaded), f"{STYLE_HEADING} {STYLE_SUCCESS}"),
+            (" 个，已存在跳过 ", STYLE_MUTED),
+            (str(stats.exists), STYLE_HEADING),
+            (" 个", STYLE_MUTED),
+        )
     if stats.failed:
-        console.warn(f"失败 {stats.failed} 个")
+        console.line(
+            ("! 失败 ", STYLE_WARN),
+            (str(stats.failed), f"{STYLE_HEADING} {STYLE_WARN}"),
+            (" 个", STYLE_WARN),
+        )
+
+
+def _print_saved_files(console: Console, files: list[SavedFile]) -> None:
+    """在 ``run`` 最后逐行列出本次新下载的文件（stderr）。
+
+    行格式 ``[new] 课程 | 相对路径``——路径本身以类别目录开头（``lectures/``、
+    ``assignments/hw2/``），不必再单独标一次类别。逐文件日志负责「跑的时候看进度」，
+    这里负责「跑完了看这一轮到底多了什么」。没有新文件时不打印标题，避免空区块。
+    """
+    if not files:
+        return
+    console.rule("新下载明细")
+    for saved in files:
+        console.line(
+            ("[new] ", STYLE_SUCCESS),
+            (saved.course, STYLE_ACCENT),
+            (" | ", STYLE_MUTED),
+            (saved.name, STYLE_TEXT),
+        )
 
 
 def _print_due_details(
@@ -344,11 +448,23 @@ def _print_due_details(
     console.rule("待办明细")
     for item in items:
         due_date = item.due_date.isoformat() if item.due_date else "日期未知"
+        date_style = STYLE_TEXT if item.due_date is not None else STYLE_MUTED
         if item.due_date is not None and item.due_date < day:
             due_date = f"{due_date}（{due.relative_due(item, day)}）"
+            date_style = STYLE_ERROR  # 逾期 / 已考过：唯一需要马上去看的
+        elif item.due_date == day:
+            date_style = STYLE_WARN
         label = due.kind_label(item.kind)
         badge = f"【{label}】" if label else ""
-        console.log(f"[due] {due_date} | {item.course_label} | {badge}{item.title}")
+        console.line(
+            ("[due] ", STYLE_ACCENT),
+            (due_date, date_style),
+            (" | ", STYLE_MUTED),
+            (item.course_label, STYLE_ACCENT),
+            (" | ", STYLE_MUTED),
+            (badge, STYLE_BADGE),
+            (item.title, STYLE_TEXT),
+        )
 
 
 def list_courses(options: SyncOptions) -> list[Course]:
@@ -408,7 +524,12 @@ def run_due(options: DueOptions) -> DueStats:
         )
 
     console.rule("待办汇总")
-    console.log(f"发现 {stats.total} 项待办，已写入 {stats.path}")
+    console.line(
+        ("发现 ", STYLE_TEXT),
+        (str(stats.total), f"{STYLE_HEADING} {STYLE_WARN if stats.total else STYLE_SUCCESS}"),
+        (" 项待办，已写入 ", STYLE_TEXT),
+        (stats.path, STYLE_MUTED),
+    )
     problems = []
     if stats.failed:
         problems.append(f"{stats.failed} 门课程 To Do 抓取失败")

{bb_sync-2.0.0 → bb_sync-2.1.1}/tests/test_cli_e2e.py

@@ -310,6 +310,32 @@ def test_run_keep_open_flag_reaches_service(cli, config_file: Path, monkeypatch)
     assert seen == [False, True]
 
 
+def test_run_json_lists_new_files(cli, config_file: Path, monkeypatch) -> None:
+    """``--json run`` 要带上本次新落盘的文件，脚本才知道多了哪些。"""
+    from bb_sync.blackboard.models import SavedFile, SyncStats
+    from bb_sync.core import service
+
+    config_file.write_text("root: ~/courses\ninclude: all\n", encoding="utf-8")
+    saved = SavedFile(
+        "CSC5010", "lectures", "lectures/Lec 1.pdf", "C:/courses/CSC5010/lectures/Lec 1.pdf"
+    )
+
+    monkeypatch.setattr(service, "run_sync", lambda options: SyncStats(downloaded=1, files=[saved]))
+    result = cli(["--json", "run"])
+
+    assert result.exit_code == 0
+    payload = json.loads(result.stdout)
+    assert payload["downloaded"] == 1
+    assert payload["files"] == [
+        {
+            "course": "CSC5010",
+            "category": "lectures",
+            "name": "lectures/Lec 1.pdf",
+            "path": "C:/courses/CSC5010/lectures/Lec 1.pdf",
+        }
+    ]
+
+
 def test_keep_open_documented_in_help(cli) -> None:
     """跑完自动关是默认行为，保留浏览器必须有显式开关且出现在帮助里。"""
     for args in (["run", "--help"], ["due", "--help"], ["course", "list", "--help"]):

{bb_sync-2.0.0 → bb_sync-2.1.1}/tests/test_units.py

@@ -1426,6 +1426,23 @@ def test_scan_due_items_merges_quiz_and_tracks_failures(monkeypatch) -> None:
     assert scan.incomplete == 2
 
 
+class _RecordingConsole:
+    """记录诊断输出的假 Console：``line`` 的片段按文本拼回整行。"""
+
+    def __init__(self) -> None:
+        self.messages: list[str] = []
+        self.rules: list[str] = []
+
+    def log(self, message: str = "", **kwargs: object) -> None:
+        self.messages.append(message)
+
+    def line(self, *segments: tuple[str, str]) -> None:
+        self.messages.append("".join(chunk for chunk, _style in segments))
+
+    def rule(self, title: str = "") -> None:
+        self.rules.append(title)
+
+
 def test_print_due_details_one_item_per_line() -> None:
     from datetime import date
     from typing import cast
@@ -1434,18 +1451,7 @@ def test_print_due_details_one_item_per_line() -> None:
     from bb_sync.core import service
     from bb_sync.core.output import Console
 
-    class FakeConsole:
-        def __init__(self) -> None:
-            self.messages: list[str] = []
-            self.rules: list[str] = []
-
-        def log(self, message: str) -> None:
-            self.messages.append(message)
-
-        def rule(self, title: str = "") -> None:
-            self.rules.append(title)
-
-    fake = FakeConsole()
+    fake = _RecordingConsole()
     console = cast(Console, fake)
     service._print_due_details(
         console,
@@ -1468,24 +1474,169 @@ def test_print_due_details_one_item_per_line() -> None:
     ]
 
 
-def test_print_due_details_empty_writes_congratulations() -> None:
+def test_sync_course_records_new_files_with_course_and_category(
+    monkeypatch, tmp_path: Path
+) -> None:
+    """新落盘的文件要连同课程、类别、相对路径一起记入明细。"""
+    from bb_sync.blackboard.models import Course, FileItem, SyncStats
+    from bb_sync.core import service
+    from bb_sync.core.config import Settings
+    from bb_sync.core.output import Console
+
+    course = Course(bb_id="_1_1", title="CSC5010: Artificial Intelligence")
+    course.slug = "CSC5010_AI"
+    item = FileItem(name="Homework 1", url="https://bb/bbcswebdav/hw1", category="assignments")
+
+    monkeypatch.setattr(
+        service.scraper, "collect_menu_links", lambda page, course: [("https://bb/area", "内容")]
+    )
+    monkeypatch.setattr(service.scraper, "find_files", lambda *args, **kwargs: [item])
+
+    class FakeDownloads:
+        def download_item(self, item, course_dir, dry_run, index):
+            return ("downloaded", "Homework 1.pdf")
+
+    stats = SyncStats()
+    options = service.SyncOptions(
+        settings=Settings(root=str(tmp_path), announcements=False),
+        config_path=tmp_path / "config.yaml",
+        root=tmp_path,
+        console=Console(quiet=True),
+    )
+    course_dir = tmp_path / "CSC5010_AI"
+    service.sync_course(None, course, course_dir, options, stats, FakeDownloads())  # type: ignore[arg-type]
+
+    assert stats.downloaded == 1
+    saved = stats.files[0]
+    assert saved.course == "CSC5010"
+    assert saved.category == "assignments"
+    # 作业按 hwN 归档，明细里给的是相对课程目录的路径
+    assert saved.name == "assignments/hw1/Homework 1.pdf"
+    assert Path(saved.path) == course_dir / "assignments" / "hw1" / "Homework 1.pdf"
+
+
+def test_saved_files_are_not_recorded_when_skipped(monkeypatch, tmp_path: Path) -> None:
+    """已存在 / dry-run 的文件不算「新下载」，不进明细。"""
+    from bb_sync.blackboard.models import Course, FileItem, SyncStats
+    from bb_sync.core import service
+    from bb_sync.core.config import Settings
+    from bb_sync.core.output import Console
+
+    course = Course(bb_id="_1_1", title="CSC5010: Artificial Intelligence")
+    item = FileItem(name="Lec 1.pdf", url="https://bb/bbcswebdav/lec1", category="lectures")
+    monkeypatch.setattr(
+        service.scraper, "collect_menu_links", lambda page, course: [("https://bb/area", "内容")]
+    )
+    monkeypatch.setattr(service.scraper, "find_files", lambda *args, **kwargs: [item])
+
+    class FakeDownloads:
+        def download_item(self, item, course_dir, dry_run, index):
+            return ("exists", "lectures/Lec 1.pdf")
+
+    stats = SyncStats()
+    options = service.SyncOptions(
+        settings=Settings(root=str(tmp_path), announcements=False),
+        config_path=tmp_path / "config.yaml",
+        root=tmp_path,
+        console=Console(quiet=True),
+    )
+    service.sync_course(None, course, tmp_path / "c", options, stats, FakeDownloads())  # type: ignore[arg-type]
+
+    assert stats.exists == 1
+    assert stats.files == []
+
+
+def test_print_saved_files_one_item_per_line() -> None:
+    from typing import cast
+
+    from bb_sync.blackboard.models import SavedFile
+    from bb_sync.core import service
+    from bb_sync.core.output import Console
+
+    fake = _RecordingConsole()
+    console = cast(Console, fake)
+    service._print_saved_files(
+        console,
+        [
+            SavedFile(
+                "CSC5010", "lectures", "lectures/Lec 5.pdf", "C:/courses/CSC5010/lectures/Lec 5.pdf"
+            ),
+            SavedFile(
+                "MDS5020",
+                "assignments",
+                "assignments/hw2/report.pdf",
+                "C:/courses/MDS5020/assignments/hw2/report.pdf",
+            ),
+        ],
+    )
+
+    assert fake.rules == ["新下载明细"]
+    assert fake.messages == [
+        "[new] CSC5010 | lectures/Lec 5.pdf",
+        "[new] MDS5020 | assignments/hw2/report.pdf",
+    ]
+
+
+def test_print_saved_files_skips_empty_section() -> None:
     from typing import cast
 
     from bb_sync.core import service
     from bb_sync.core.output import Console
 
-    class FakeConsole:
-        def __init__(self) -> None:
-            self.messages: list[str] = []
-            self.rules: list[str] = []
+    fake = _RecordingConsole()
+    console = cast(Console, fake)
+    service._print_saved_files(console, [])
 
-        def log(self, message: str) -> None:
-            self.messages.append(message)
+    # 没有新文件时不打标题，避免空区块
+    assert fake.rules == []
+    assert fake.messages == []
 
-        def rule(self, title: str = "") -> None:
-            self.rules.append(title)
 
-    fake = FakeConsole()
+def test_sync_stats_as_dict_carries_new_files() -> None:
+    from bb_sync.blackboard.models import SavedFile, SyncStats
+
+    stats = SyncStats(downloaded=1)
+    stats.files.append(
+        SavedFile(
+            "CSC5010", "lectures", "lectures/Lec 1.pdf", "C:/courses/CSC5010/lectures/Lec 1.pdf"
+        )
+    )
+
+    payload = stats.as_dict()
+
+    assert payload["downloaded"] == 1
+    assert payload["files"] == [
+        {
+            "course": "CSC5010",
+            "category": "lectures",
+            "name": "lectures/Lec 1.pdf",
+            "path": "C:/courses/CSC5010/lectures/Lec 1.pdf",
+        }
+    ]
+
+
+def test_console_line_writes_to_stderr_without_ansi_when_not_tty(capsys) -> None:
+    """带样式的诊断行只走 stderr；非 TTY（测试 / 管道）下不发转义序列。"""
+    from bb_sync.core.output import Console
+
+    Console().line(("课程 ", ""), ("CSC5010", "cyan"))
+    out, err = capsys.readouterr()
+    assert out == ""
+    assert "课程 CSC5010" in err
+    assert "" not in err
+
+    Console(quiet=True).line(("课程 ", ""), ("CSC5010", "cyan"))
+    out, err = capsys.readouterr()
+    assert (out, err) == ("", "")
+
+
+def test_print_due_details_empty_writes_congratulations() -> None:
+    from typing import cast
+
+    from bb_sync.core import service
+    from bb_sync.core.output import Console
+
+    fake = _RecordingConsole()
     console = cast(Console, fake)
     service._print_due_details(console, [])
 

{bb_sync-2.0.0 → bb_sync-2.1.1}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.11"
 
 [[package]]
@@ -31,7 +31,7 @@ wheels = [
 
 [[package]]
 name = "bb-sync"
-version = "2.0.0"
+version = "2.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },