小鹅通课程本地处理 Skill

这是一个面向多 Agent 的本地优先 Skill：将使用者已获授权的小鹅通回放，或使用者提供的 本地媒体/官方导出，在本机处理为逐字稿和课程笔记，并写入指定的 Obsidian 笔记库。

推荐通过 Codex 使用；其他具备 Skill 加载、文件读写和本地工具能力的 Agent 也可接入。 浏览器采集是可选能力：只有已授权的可见回放页与浏览器契约都能验证时，才会使用浏览器 路线；否则直接使用本地媒体或官方导出。技能不会假定任意设备的路径、端口、浏览器 profile 或登录状态；条件缺失时会明确说明降级或阻塞原因，不做猜测。

使用方式与能力要求

使用方式	所需能力	内容输入	可交付结果
Codex（推荐）	文件读写和本地 shell；Codex Browser 为可选能力	已授权的可见回放页，或本地媒体/官方导出	本地逐字稿、课程笔记及已确认的 Obsidian 写入
其他原生 Skill Agent	自己的 Skill loader、文件读写和所需本地工具	本机浏览器契约通过后使用可见回放页；否则使用本地媒体/官方导出	同上，并记录路径、工具和目标目录的验证结果
仅支持离线处理的 Agent	本地文件读写和转写工具	本地媒体或官方导出	离线处理结果；缺少合法输入时报告 information missing 或 MEDIA_ACQUISITION_BLOCKED

具体的兼容性字段、降级状态和可复制 onboarding prompt 见 docs/AGENT_COMPATIBILITY.md。安装前请阅读 docs/INSTALLATION.md，并只使用当前主机已发现并确认的 skill root。

包结构

下面两个目录都是可独立安装的技能包。每个包都含有 SKILL.md、平台说明、 references，以及它所调用的 portable Python/Node runtime 的完整副本。

macos/xiaoeskill/   # 在 macOS 选择此包
windows/xiaoeskill/ # 在 Windows 选择此包（Windows-first 安装示例见 docs）
shared/             # canonical runtime/references 与 parity checker，不作为第三包安装
docs/               # Agent 兼容性契约与按主机安装/验证流程

包内 runtime 是有意复制的，因此复制任一平台目录时不依赖仓库相对路径。shared/ 是审阅与一致性检查副本，不要把它作为第三个技能包安装。

安装与首轮验证（Windows 优先）

先让本机 Agent 从自己的配置发现并报告 skill root，再由使用者确认路径；没有 确认就停止，不要猜测。PowerShell、平台选择、工具检查、browser-HLS 降级状态和 首次 smoke check 都在 docs/INSTALLATION.md。完整的本地 数据/工具/浏览器/音频/Obsidian 选择在 CUSTOMIZATION.md。

仓库级检查（在仓库根目录）：

py -3 shared/checks/verify_package.py
py -3 -m py_compile (Get-ChildItem windows/xiaoeskill/runtime/*.py)

macOS 使用 python3 运行同名命令即可。安装成功只证明包结构和本地检查通过，不 代表账户登录、课程授权、媒体获取或 Obsidian 发布已经完成。

Codex Browser 优先，但必须满足契约

Codex Browser 只能读取一个已登录、已获准的可见回放页：标题、日期、正文、回放 ID 和小范围 video 状态。page-asset inventory 只是候选证据，不能单独证明媒体导出。 浏览器 HLS 还要求在同一会话中新观察到一个 clear、VOD、获准的 manifest，并 取得本次个人离线备份确认；不得读取 Cookie、localStorage、sessionStorage、隐藏 Token、播放器内部数据或 DRM。

如果浏览器工具、明确 CDP endpoint、登录态、manifest 或安全交接无法验证，记录 BROWSER_HLS_UNAVAILABLE，按本地文件 → 可见官方导出 → page-asset → 官方 API → 获准系统音频的顺序降级。前五项不可用且没有合法音频输入时，记录 MEDIA_ACQUISITION_BLOCKED；“浏览器降级”不是成功，也不允许绕过登录、购买、反爬 或 DRM。

可移植配置

只有在没有提供环境变量时，runtime 才会根据当前主机用户目录推导默认值。为了让 安装可复现，请由本机 Agent 发现并由使用者确认以下变量；值只留在本机：

变量	用途
XIAOESKILL_DATA_DIR	每用户数据根目录
XIAOESKILL_JOBS_DIR	数据根目录下的任务根目录
XIAOESKILL_WHISPER_MODEL	本地 Whisper 模型路径
XIAOESKILL_WHISPER_CLI	本地 Whisper 可执行文件
XIAOESKILL_FFMPEG / XIAOESKILL_FFPROBE	媒体工具
XIAOESKILL_CHUNKER	可选的分块器覆盖路径
XIAOESKILL_PYTHON	Node bridge 使用的 Python 命令
XIAOESKILL_BROWSER_CDP_URL	使用浏览器时的明确 CDP endpoint
XIAOESKILL_OBSIDIAN_VAULT	使用者选择的主库
XIAOESKILL_OBSIDIAN_MIRROR	使用者选择的可选镜像库

这些路径只是示例/占位符。若目标 Agent 无法发现或验证某项，必须写 information missing，不能编造个人目录。

授权、隐私与安全边界

技能只处理使用者已经能够访问且获准处理的回放，不是登录、爬虫、绕过付费墙、恢复 凭据或解除 DRM 的工具。媒体获取按离线优先顺序执行；如果前五条路径都不可用， 必须记录 MEDIA_ACQUISITION_BLOCKED，不能猜测 URL 或伪造课程内容。

不得读取或导出 Cookie、localStorage、sessionStorage、历史记录、凭据、隐藏 Token、 播放器内部数据或 DRM 材料；不得把媒体、逐字稿、签名 URL、密钥、许可证或浏览器 存储上传到外部服务。HLS 下载器会拒绝加密/密钥请求、非 VOD、私有或保留地址、不安全 跳转和媒体时长不匹配，并只写入脱敏状态、哈希、计数与时长。

处理结果、浏览器数据和任务文件默认留在本机；不要把完整逐字稿或详细日志粘贴到 Agent 上下文或公开 issue。技能不会创建 cron、服务、启动钩子、watchdog 或后台 worker。详见平台包中的 references/，以及安装后必须完成的 CUSTOMIZATION.md。

检查与许可证

仓库内的 focused checker 会验证双平台包结构与 parity、路径解析、文档链接、 私有绝对路径/secret 缺失、Windows 平台边界，以及多 Agent/浏览器契约/安装发现文档 是否完整。发布前请从仓库根目录运行：

python3 shared/checks/verify_package.py
python3 -m py_compile shared/runtime/*.py macos/xiaoeskill/runtime/*.py windows/xiaoeskill/runtime/*.py

本项目使用 MIT License，详见 LICENSE。