bb-sync 1.9.0__py3-none-any.whl

bb_sync/commands/doctor.py

@@ -0,0 +1,65 @@
+"""``bb-sync doctor`` —— 环境体检。
+
+本模块导出的是**扁平命令**（``bb-sync doctor [OPTIONS]``）：
+它在语义上没有下级子命令，多一层 ``doctor doctor`` 只是噪音。
+"""
+
+from __future__ import annotations
+
+import typer
+
+from bb_sync.context import Context
+from bb_sync.core import doctor
+from bb_sync.core.errors import EnvironmentError_
+
+#: 模块对应的子命令名（供 cli.LazyGroup 识别）
+SUBCOMMAND = "doctor"
+HELP = "体检：检查前置条件（git / Node / 浏览器 / 网络等）"
+
+#: 单命令 Typer app：借 Typer 从函数签名推导参数，随后由 cli 层取出那条命令平铺
+app = typer.Typer(help=HELP, add_completion=False)
+
+
+@app.command("doctor")
+def doctor_cmd(
+    ctx: typer.Context,
+    list_only: bool = typer.Option(False, "--list", help="只列出检查项，不实际执行"),
+    skip_network: bool = typer.Option(False, "--skip-network", help="跳过网络可达性检查"),
+) -> None:
+    """体检：检查前置条件（git / Node / 浏览器 / 网络等）。"""
+    app_ctx: Context = ctx.obj
+    console = app_ctx.console
+
+    if list_only:
+        names = [fn.__name__.removeprefix("check_") for fn in doctor.CHECKS]
+        console.table(["检查项"], [[n] for n in names], json_data={"checks": names})
+        return
+
+    results = doctor.run_doctor(console, skip_network=skip_network)
+
+    if app_ctx.json_mode:
+        console.emit(
+            {
+                "ok": not any(r.required and not r.ok for r in results),
+                "checks": [
+                    {
+                        "label": r.label,
+                        "ok": r.ok,
+                        "detail": r.detail,
+                        "hint": r.hint,
+                        "required": r.required,
+                    }
+                    for r in results
+                ],
+            }
+        )
+
+    missing = [r for r in results if r.required and not r.ok]
+    if missing:
+        raise EnvironmentError_(
+            f"环境体检未通过：{'、'.join(r.label for r in missing)} 缺失",
+            "按上方提示逐项修复后重试",
+        )
+
+
+__all__ = ["HELP", "SUBCOMMAND", "app", "doctor_cmd"]

bb_sync/commands/due.py

@@ -0,0 +1,66 @@
+"""``bb-sync due`` —— 整理全部课程的待办到 ``due.md``。"""
+
+from __future__ import annotations
+
+import typer
+
+from bb_sync import paths
+from bb_sync.context import Context
+from bb_sync.core import service
+from bb_sync.core.config import ensure_config_file
+from bb_sync.core.errors import ConfigError
+
+SUBCOMMAND = "due"
+HELP = """扫描课程主页 Due / To Do 与公告，生成按优先级排列的 due.md。
+
+公告里带日期的课堂测验与考试（quiz / exam）也会整理成待办，并在 due.md 中分别标记为
+【测验】【考试】。
+
+示例：
+  bb-sync due                         扫描全部课程并写入 <root>/due.md
+  bb-sync due --course CSC5010        只扫描指定课程（可重复）
+  bb-sync due --root ~/University     临时指定输出目录
+  bb-sync due --headed                有头模式（首次登录 / 需要人工过 MFA）
+  bb-sync --json due                  输出机器可读 JSON
+"""
+
+app = typer.Typer(help=HELP.splitlines()[0], add_completion=False)
+
+
+@app.command("due")
+def due(
+    ctx: typer.Context,
+    headed: bool = typer.Option(False, "--headed", help="有头模式（首次登录/MFA 用）"),
+    course: list[str] = typer.Option(
+        None, "--course", help="只扫描指定课程代码（可多次），如 --course CSC5010"
+    ),
+    root: str = typer.Option(None, "--root", help="本次 due.md 的输出目录（临时覆盖配置）"),
+) -> None:
+    """生成课程待办清单。"""
+    app_ctx: Context = ctx.obj
+    console = app_ctx.console
+
+    overrides = {"root": root, "include": course or None}
+    settings, config_path = app_ctx.load_settings(cli_overrides=overrides)
+
+    if not config_path.exists():
+        if app_ctx.config_file:
+            raise ConfigError(
+                f"未找到配置文件：{config_path}", "检查 --config 路径，或省略该参数用默认配置"
+            )
+        ensure_config_file(paths.BB_SYNC_HOME / "config.yaml")
+        settings, config_path = app_ctx.load_settings(cli_overrides=overrides)
+        console.log(f"[info] 已生成默认配置 {config_path}（可按需修改）")
+
+    options = service.DueOptions(
+        settings=settings,
+        root=service.plan_root(settings, config_path, root),
+        console=console,
+        headed=headed,
+        courses=course or None,
+    )
+    stats = service.run_due(options)
+    console.emit(stats.as_dict())
+
+
+__all__ = ["HELP", "SUBCOMMAND", "app", "due"]

bb_sync/commands/run.py

@@ -0,0 +1,74 @@
+"""``bb-sync run`` —— 执行一次课程同步。
+
+本模块导出的是**扁平命令**（``bb-sync run [OPTIONS]``）。
+"""
+
+from __future__ import annotations
+
+import typer
+
+from bb_sync import paths
+from bb_sync.context import Context
+from bb_sync.core import service
+from bb_sync.core.config import ensure_config_file
+from bb_sync.core.errors import ConfigError
+
+#: 模块对应的子命令名
+SUBCOMMAND = "run"
+HELP = """执行一次课程同步并更新 due.md（下载目录取配置里的 root，可用 --root 临时覆盖）。
+
+示例：
+  bb-sync run                        增量同步全部课程并更新待办清单
+  bb-sync run --course CSC5010       只同步指定课程并更新对应待办（可重复）
+  bb-sync run --dry-run              预览下载和待办，不写文件
+  bb-sync run --headed               有头模式（首次登录 / 需要人工过 MFA）
+  bb-sync run --json                 输出机器可读 JSON，便于脚本消费
+"""
+
+#: 单命令 Typer app：借 Typer 从函数签名推导参数，随后由 cli 层取出那条命令平铺
+app = typer.Typer(help=HELP.splitlines()[0], add_completion=False)
+
+
+@app.command("run")
+def run(
+    ctx: typer.Context,
+    headed: bool = typer.Option(False, "--headed", help="有头模式（首次登录/MFA 用）"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="只列出文件，不下载"),
+    course: list[str] = typer.Option(
+        None, "--course", help="只同步指定课程代码（可多次），如 --course CSC5010"
+    ),
+    root: str = typer.Option(None, "--root", help="本次同步的下载目录（临时覆盖配置里的 root）"),
+) -> None:
+    """执行一次课程同步并更新待办清单。"""
+    app_ctx: Context = ctx.obj
+    console = app_ctx.console
+
+    overrides = {"root": root, "include": course or None}
+    settings, config_path = app_ctx.load_settings(cli_overrides=overrides)
+
+    # 配置文件缺失时：显式指定的直接报错，其余自动落一份默认配置
+    if not config_path.exists():
+        if app_ctx.config_file:
+            raise ConfigError(
+                f"未找到配置文件：{config_path}", "检查 --config 路径，或省略该参数用默认配置"
+            )
+        ensure_config_file(paths.BB_SYNC_HOME / "config.yaml")
+        settings, config_path = app_ctx.load_settings(cli_overrides=overrides)
+        console.log(f"[info] 已生成默认配置 {config_path}（可按需修改）")
+
+    options = service.SyncOptions(
+        settings=settings,
+        config_path=config_path,
+        root=service.plan_root(settings, config_path, root),
+        console=console,
+        headed=headed,
+        dry_run=dry_run,
+        courses=course or None,
+    )
+    stats = service.run_sync(options)
+
+    # 结果走 stdout：--json 时输出统计对象；人读模式下汇总已在 stderr 打印
+    console.emit(stats.as_dict())
+
+
+__all__ = ["HELP", "SUBCOMMAND", "app", "run"]

bb_sync/context.py

@@ -0,0 +1,69 @@
+"""全局运行上下文：把 Typer 的全局选项传给各子命令。
+
+Typer 的子命令之间不共享状态，所以全局开关（``--json`` / ``--quiet`` / ``--verbose``
+/ ``--config``）统一放在顶层回调里，存进 :class:`Context` 对象，由命令层按需取用。
+
+性能要点：本模块**不在顶层导入** pydantic（``core.config``）与 rich
+(``core.output``)，否则 ``bb-sync --version`` 也要为它们付出百毫秒级导入成本。
+两者都在真正被用到时才导入。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from bb_sync import paths
+
+if TYPE_CHECKING:  # 仅供类型检查，运行时不导入
+    from bb_sync.core.config import Settings
+    from bb_sync.core.output import Console
+
+#: 模块级缓存：Console 类在首次使用时才导入
+_CONSOLE_CLS: Any = None
+
+
+def _console_cls() -> Any:
+    global _CONSOLE_CLS
+    if _CONSOLE_CLS is None:
+        from bb_sync.core.output import Console
+
+        _CONSOLE_CLS = Console
+    return _CONSOLE_CLS
+
+
+@dataclass
+class Context:
+    """一次 CLI 调用的共享状态。"""
+
+    json_mode: bool = False
+    quiet: bool = False
+    verbose: bool = False
+    config_file: str | None = None
+    _console: Any = field(default=None, repr=False)
+
+    @property
+    def console(self) -> Console:
+        """惰性构造 Console（首次访问时才导入 rich）。"""
+        if self._console is None:
+            self._console = _console_cls()(
+                json_mode=self.json_mode, quiet=self.quiet, verbose=self.verbose
+            )
+        return self._console
+
+    @property
+    def home(self) -> Path:
+        return paths.BB_SYNC_HOME
+
+    def load_settings(self, *, cli_overrides: dict | None = None) -> tuple[Settings, Path]:
+        """按四层优先级加载配置（首次调用时才导入 pydantic）。"""
+        from bb_sync.core.config import load_settings
+
+        return load_settings(
+            Path(self.config_file).expanduser() if self.config_file else None,
+            cli_overrides=cli_overrides,
+        )
+
+
+__all__ = ["Context"]

bb_sync/core/__init__.py

@@ -0,0 +1,5 @@
+"""核心基础设施：异常、输出、配置、容器与常量。"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

bb_sync/core/config.py

@@ -0,0 +1,205 @@
+"""配置模型与加载：Pydantic 校验 + 四层优先级。
+
+优先级（高 → 低），对齐成熟 CLI 的惯例::
+
+    1. CLI 参数      bb-sync run --root ~/University/courses
+    2. 环境变量      BB_SYNC_ROOT=~/University/courses
+    3. 配置文件      ~/.bb-sync/config.yaml
+    4. 内置默认值    DEFAULT_CONFIG 同源
+
+配置文件位置解析：``--config`` 显式指定 > 当前目录 config.yaml > ``~/.bb-sync/config.yaml``。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from bb_sync import paths
+from bb_sync.core.errors import ConfigError
+
+#: 环境变量前缀，如 ``BB_SYNC_ROOT``、``BB_SYNC_MAX_DEPTH``
+ENV_PREFIX = "BB_SYNC_"
+
+DEFAULT_KEYWORDS: dict[str, list[str]] = {
+    "assignments": ["assignment", "homework", "作业", "hw"],
+    "tutorials": ["tutorial", "lab", "实验", "指导", "recitation"],
+    "lectures": ["lecture", "课件", "讲义", "slides", "notes", "note"],
+}
+
+
+class Settings(BaseModel):
+    """bb-sync 全部可配置项。"""
+
+    root: str = "~/courses"
+    """课程资源根目录，支持 ``~`` 与相对路径（相对路径以配置文件所在目录为基准）。"""
+
+    include: Literal["all"] | list[str] = "all"
+    """同步哪些课程：``all`` 或课程代码列表。"""
+
+    course_dirs: dict[str, str] = Field(default_factory=dict)
+    """课程代码 → 本地文件夹名的显式映射。"""
+
+    keywords: dict[str, list[str]] = Field(default_factory=lambda: dict(DEFAULT_KEYWORDS))
+    """内容归类关键词。"""
+
+    announcements: bool = True
+    """是否同步公告到 ``announcements.md``。"""
+
+    max_depth: int = Field(default=3, ge=1, le=10)
+    """内容子文件夹递归最大深度。"""
+
+    model_config = {"extra": "ignore"}
+
+    @field_validator("include", mode="before")
+    @classmethod
+    def _normalize_include(cls, v: Any) -> Any:
+        """允许 ``include: CSC5010`` 这类单个标量写法。"""
+        if v is None:
+            return "all"
+        if isinstance(v, str) and v.lower() != "all":
+            return [v]
+        return v
+
+    @field_validator("course_dirs", mode="before")
+    @classmethod
+    def _normalize_course_dirs(cls, v: Any) -> Any:
+        """``course_dirs:`` 写成空值时归一为 ``{}``。"""
+        return v or {}
+
+    def resolve_root(self, config_path: Path | None = None) -> Path:
+        """把 ``root`` 解析为绝对路径（支持 ``~`` 与相对路径）。"""
+        raw = Path(self.root).expanduser()
+        if raw.is_absolute():
+            return raw
+        base = config_path.parent if config_path else Path.cwd()
+        return (base / raw).resolve()
+
+
+def config_target(explicit: str | None = None) -> Path:
+    """配置文件位置：``--config`` > 当前目录 config.yaml > ``~/.bb-sync/``。"""
+    if explicit:
+        return Path(explicit).expanduser()
+    cwd_candidate = Path.cwd() / paths.CONFIG_NAME
+    if cwd_candidate.exists():
+        return cwd_candidate
+    return paths.BB_SYNC_HOME / paths.CONFIG_NAME
+
+
+#: 首次运行自动生成的默认配置（带注释，供用户手改）
+DEFAULT_CONFIG_TEXT = """\
+# bb-sync 配置（首次运行自动生成，可按需修改）
+# 也可用命令修改：bb-sync config set root <目录>
+
+# 课程资源根目录（支持 ~ 和相对路径）
+root: ~/courses
+
+# 同步哪些课程：all = 全部，或列表如 [CSC5010, DDA5002]
+include: all
+
+# 课程代码 -> 本地文件夹名 的显式映射（未列出的自动命名）
+course_dirs: {}
+
+# 内容归类关键词：先匹配 assignments，再 tutorials，其余归 lectures
+keywords:
+  assignments: ["assignment", "homework", "作业", "hw"]
+  tutorials: ["tutorial", "lab", "实验", "指导", "recitation"]
+  lectures: ["lecture", "课件", "讲义", "slides", "notes", "note"]
+
+# 公告是否同步（写入课程目录 announcements.md）
+announcements: true
+
+# 内容子文件夹递归深度（1 = 只下内容区第一层）
+max_depth: 3
+"""
+
+
+def ensure_config_file(path: Path) -> bool:
+    """配置文件不存在时落一份默认配置；返回是否新建。"""
+    if path.exists():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(DEFAULT_CONFIG_TEXT, encoding="utf-8")
+    return True
+
+
+def read_raw(path: Path) -> dict[str, Any]:
+    """读取 YAML 原文；文件缺失或语法错误抛 :class:`ConfigError`。"""
+    if not path.exists():
+        raise ConfigError(f"配置文件不存在：{path}", "运行 bb-sync config init 生成默认配置")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"配置文件格式错误：{path}", str(exc)) from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"配置文件顶层必须是映射：{path}")
+    return data
+
+
+def _env_overrides() -> dict[str, Any]:
+    """收集 ``BB_SYNC_*`` 环境变量（键名小写，下划线保留）。"""
+    out: dict[str, Any] = {}
+    for key, raw in os.environ.items():
+        if not key.startswith(ENV_PREFIX):
+            continue
+        name = key[len(ENV_PREFIX) :].lower()
+        if name in Settings.model_fields:
+            out[name] = raw
+    return out
+
+
+def load_settings(
+    path: Path | None = None,
+    *,
+    cli_overrides: dict[str, Any] | None = None,
+) -> tuple[Settings, Path]:
+    """按四层优先级加载配置，返回 ``(Settings, 实际配置文件路径)``。
+
+    ``cli_overrides`` 里的 ``None`` 值会被忽略，方便直接传 argparse/Typer 的可选参数。
+    """
+    path = path or config_target()
+    layers: dict[str, Any] = {}
+    if path.exists():
+        layers.update(read_raw(path))
+    layers.update(_env_overrides())
+    if cli_overrides:
+        layers.update({k: v for k, v in cli_overrides.items() if v is not None})
+
+    try:
+        settings = Settings.model_validate(layers)
+    except ValidationError as exc:
+        raise ConfigError(f"配置项校验失败：{path}", _format_validation_error(exc)) from exc
+    return settings, path
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    """把 Pydantic 报错压成人类可读的单行提示。"""
+    parts = []
+    for err in exc.errors():
+        loc = ".".join(str(x) for x in err["loc"]) or "(顶层)"
+        parts.append(f"{loc}: {err['msg']}")
+    return "; ".join(parts)
+
+
+def dump_settings(settings: Settings) -> dict[str, Any]:
+    """导出为可 JSON/YAML 序列化的普通字典。"""
+    return settings.model_dump(mode="json")
+
+
+__all__ = [
+    "DEFAULT_CONFIG_TEXT",
+    "DEFAULT_KEYWORDS",
+    "ENV_PREFIX",
+    "Settings",
+    "config_target",
+    "dump_settings",
+    "ensure_config_file",
+    "load_settings",
+    "read_raw",
+]

bb_sync/core/config_store.py

@@ -0,0 +1,190 @@
+"""配置文件的行级编辑器：修改值但保留原有注释与排版。
+
+直接 ``yaml.safe_dump`` 会丢掉用户写的注释，所以 ``config set/unset`` 走这套
+逐行正则操作。仅处理顶层标量键与「顶层映射下的一级子键」两种形态，
+覆盖面与配置结构（root / include / course_dirs.X）一致。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from bb_sync.core.errors import ConfigError, NotFoundError
+
+# ---------------------------------------------------------------- 读取辅助
+
+
+def _split_inline(line: str) -> str:
+    """键行冒号后的值部分（去注释、去空白）；无冒号返回空串。"""
+    return line.split(":", 1)[1].split("#", 1)[0].strip() if ":" in line else ""
+
+
+def _block_end(lines: list[str], start: int) -> int:
+    """顶层键所在映射块的结束行号（不含）：空行/注释/缩进行属于块内。"""
+    j = start + 1
+    while j < len(lines):
+        stripped = lines[j].strip()
+        if not stripped or stripped.startswith("#") or lines[j][0] in " \t":
+            j += 1
+            continue
+        break
+    return j
+
+
+def _find_block(lines: list[str], parent: str) -> tuple[int, int] | None:
+    """定位顶层键的 ``(起始行, 块结束行)``。"""
+    pat = re.compile(rf"^{re.escape(parent)}\s*:")
+    for i, line in enumerate(lines):
+        if pat.match(line):
+            return i, _block_end(lines, i)
+    return None
+
+
+def _child_indent(lines: list[str], start: int, end: int) -> str:
+    """取块内已有子键的缩进；没有则默认两个空格。"""
+    for k in range(start + 1, end):
+        s = lines[k]
+        if s.strip() and not s.strip().startswith("#") and s[0] in " \t":
+            return s[: len(s) - len(s.lstrip())]
+    return "  "
+
+
+# ---------------------------------------------------------------- 写操作
+
+
+def set_top_level(lines: list[str], key: str, raw: str) -> None:
+    """替换顶层标量键的值（独占整行的注释不受影响）；键不存在则追加。"""
+    pat = re.compile(rf"^(\s*){re.escape(key)}(\s*:\s*).*$")
+    for i, line in enumerate(lines):
+        m = pat.match(line)
+        if m:
+            lines[i] = f"{m.group(1)}{key}: {raw}"
+            return
+    if lines and lines[-1].strip():
+        lines.append("")
+    lines.append(f"{key}: {raw}")
+
+
+def set_nested(lines: list[str], parent: str, child: str, raw: str) -> None:
+    """在 parent 映射下写入/更新 child 子键，保留原有注释与缩进。"""
+    blk = _find_block(lines, parent)
+    if blk is None:  # 整个键不存在：追加到文件末尾
+        if lines and lines[-1].strip():
+            lines.append("")
+        lines.append(f"{parent}:")
+        lines.append(f"  {child}: {raw}")
+        return
+    start, end = blk
+    inline = _split_inline(lines[start])
+    if inline:
+        if inline[0] in "{[":  # 流式空映射（如 course_dirs: {}）→ 展开为块式
+            lines[start] = lines[start].split(":", 1)[0] + ":"
+            lines.insert(start + 1, f"  {child}: {raw}")
+            return
+        raise ConfigError(f"{parent} 的值不是映射，无法设置子键 {child}")
+    pat = re.compile(rf"^(\s+){re.escape(child)}(\s*:\s*).*$")
+    for k in range(start + 1, end):
+        m = pat.match(lines[k])
+        if m:
+            lines[k] = f"{m.group(1)}{child}: {raw}"
+            return
+    indent = _child_indent(lines, start, end)
+    last_content = start
+    for k in range(start + 1, end):
+        s = lines[k].strip()
+        if s and not s.startswith("#"):
+            last_content = k
+    lines.insert(last_content + 1, f"{indent}{child}: {raw}")
+
+
+def unset_top_level(lines: list[str], key: str) -> None:
+    """删除顶层键：标量整行删除；映射（含流式 ``{}``）重置为 ``{}``。"""
+    blk = _find_block(lines, key)
+    if blk is None:
+        raise NotFoundError(f"配置里没有：{key}")
+    start, end = blk
+    inline = _split_inline(lines[start])
+    has_children = any(
+        lines[k].strip() and not lines[k].strip().startswith("#") and lines[k][0] in " \t"
+        for k in range(start + 1, end)
+    )
+    if (inline and inline[0] in "{[") or (not inline and has_children):
+        lines[start] = lines[start].split(":", 1)[0] + ": {}"
+        if not inline:  # 只删内容行，保留归属下个键的注释
+            for k in range(end - 1, start, -1):
+                s = lines[k].strip()
+                if s and not s.startswith("#"):
+                    del lines[k]
+        return
+    del lines[start]
+
+
+def unset_nested(lines: list[str], parent: str, child: str) -> None:
+    """删除 ``parent.child`` 子键。"""
+    blk = _find_block(lines, parent)
+    if blk is None or _split_inline(lines[blk[0]]):
+        raise NotFoundError(f"配置里没有：{parent}.{child}")
+    start, end = blk
+    for k in range(start + 1, end):
+        if re.match(rf"^\s+{re.escape(child)}\s*:", lines[k]):
+            del lines[k]
+            return
+    raise NotFoundError(f"配置里没有：{parent}.{child}")
+
+
+# ---------------------------------------------------------------- 对外接口
+
+
+def parse_value(raw: str) -> object:
+    """把命令行传入的字符串按 YAML 标量解析，并拒绝映射（引导用点号写法）。"""
+    try:
+        parsed = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"值不是合法的 YAML：{raw}", str(exc)) from exc
+    if isinstance(parsed, dict):
+        raise ConfigError(
+            "set 不支持映射值；嵌套键请用点号写法",
+            "例如：bb-sync config set course_dirs.CSC5010 CSC5010_AI",
+        )
+    return parsed
+
+
+def apply_to_file(path: Path, key: str, raw: str | None) -> str:
+    """在文件上执行 set（``raw`` 非空）或 unset（``raw`` 为 None）。
+
+    返回人类可读的操作描述。文件必须已存在。
+    """
+    if not path.exists():
+        raise ConfigError(f"配置文件不存在：{path}", "运行 bb-sync config init 生成默认配置")
+    lines = path.read_text(encoding="utf-8").splitlines()
+
+    if raw is None:
+        if "." in key:
+            parent, child = key.split(".", 1)
+            unset_nested(lines, parent, child)
+        else:
+            unset_top_level(lines, key)
+        action = f"已移除 {key}"
+    else:
+        if "." in key:
+            parent, child = key.split(".", 1)
+            set_nested(lines, parent, child, raw)
+        else:
+            set_top_level(lines, key, raw)
+        action = f"{key} = {raw}"
+
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return action
+
+
+__all__ = [
+    "apply_to_file",
+    "parse_value",
+    "set_nested",
+    "set_top_level",
+    "unset_nested",
+    "unset_top_level",
+]