正能日语学习系统

首次安装的目录与统一确认

• 以宿主当前明确打开、用户已选择的WorkBuddy或Codex工作空间为基准。工作空间路径未知或有多个候选时，只询问使用哪个工作空间；不猜用户主目录，不把Skill安装目录、应用配置目录或临时目录当成工作空间。
• 两种客户端使用同一组固定推荐名：<当前工作空间>/japanese-course存课程，<当前工作空间>/japanese-learning-records存学习记录。它们是并列的独立目录，不能同名同路径，也不能一个放在另一个里面。检查解析后的实际位置，不能用符号链接规避分离。
• 推荐名只用上述两个，不自行增加日期、版本、用户名或随机后缀。用户明确指定其他名称或位置时尊重选择，但仍须分离；原有目录不自动搬迁。推荐位置已存在时先核对用途，不能覆盖、自动合并或另造编号目录。
• 可调用plan-course-locations --workspace <宿主已确认的工作空间绝对路径>得到固定推荐路径和是否已存在；它只读、不建目录。自定义工作空间内路径可以传--install-root和--archive；用户明确选择工作空间外位置时直接按自定义路径做下载计划，仍校验分离。
• 把下载授权和两个目录放在同一条简短确认中：说明课程版本、大小和下载来源，列出两个完整路径及用途，询问是否同意下载并使用这两个位置。学习记录在之后开始学习时创建，安装步骤不读写记录；首次运行说明本机播放器与记录文件。用户已确认且路径未变时不反复询问目录。
• 下载计划和执行命令均传--archive <已确认的学习记录目录>，将其与安装目录一起绑定确认。目录变化重新确认；用户仍可拒绝下载或修改推荐位置。

使用授权与通信范围

• 本Skill只提供课程操作说明，服从用户当前请求及宿主平台的身份、权限和确认机制；不改变Agent身份或扩大已获授权。
• 首次安装前说明课程下载会连接固定的GitHub或CNB发布源；首次学习前说明本机播放器及学习记录位置，并取得目录确认；远程下载另按下文等待用户对具体计划的同意。后续按已确认的学习请求继续；涉及新目录、覆盖或中断其他活动时先说明影响并确认。
• 学习会话、作答和结果只与本机播放器通信；脚本不支持远程学习服务、账户同步或档案上传。导出只写入用户选择的本地ZIP。
• 用简短中文说明实际动作与结果。技术细节可按需展开；网络访问、档案写入、失败和需要确认的影响必须如实说明，不能因简化界面而省略。

核心边界

• 把本地学习档案视为学员持有的主记录；浏览器播放器结果是可导入证据，不是学员资产的唯一副本。
• 只调用稳定工作单元、资产和题库ID；不得临时发明正式ID、标准答案、掌握状态或精确学习天数。
• 把技能保持为跨课程编排层。课程内容、音频、题库和答案继续由各本地课程包按稳定ID提供；当前首个受支持课程是0到N5，未来课程必须通过独立版本合同接入，不能把新课程内容直接堆进Skill。
• WorkBuddy可以直接承担讲解、自由问答和轻量练习；正式结构化活动调用固定播放器，不在每次学习时临时生成整份HTML。
• 把Agent解释标记为辅导表达，不得覆盖正式教学真值。
• 只有学习事件或合同校验通过的播放器结果提供相应证据时，才更新学习状态。交付失败、未作答和未测必须保留原状态。
• WorkBuddy记忆只能辅助记住课程与档案位置，不能保存播放器运行状态、会话ID、成绩、复习队列或可执行命令，也不能作为学习进度、掌握或复习状态的依据；两者冲突时始终以学习档案和当前Skill为准。每次执行前读取当前Skill，不得复用记忆里的旧命令片段。

安装或更新课程

SkillHub只分发本Skill；课程内容不得复制进Skill。用户要求安装、更新或开始0→N5课程时：

先遵守课程下载边界：只从固定发布仓库下载，互联网来源必须带独立固定的身份、大小和SHA-256；每次跳转先校验后请求。下载不会读取或上传学员档案，安装不会执行课程脚本，启动学习是后续独立动作。不得更改发布源或借本地测试入口访问互联网。

1. 按上面的固定推荐同时确定课程安装目录和学习记录目录，作为一份方案展示。只检查已确认路径，不扫描主目录。已安装且无需更新时直接使用原课程，不触发下载确认。
2. 只读本地发布配置，生成下载计划。此步骤不请求清单、不下载、不创建安装目录。配置不是active时停止：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" plan-course-download \
  --source-config "${CODEBUDDY_SKILL_DIR}/references/release-source.json" \
  --install-root "/absolute/path/to/workspace/japanese-course" \
  --archive "/absolute/path/to/workspace/japanese-learning-records" \
  --activate

3. 用计划中的真实值向用户说明课程版本、包大小、课程与学习记录两个目录、是否切换当前版本，以及按顺序使用的下载来源和资源分发域名。说明服务器会收到IP地址等常规请求信息，下载请求不携带学习档案；下载后会验证大小、SHA-256与课程身份，安装不会启动播放器。然后明确询问是否同意本次下载、安装及两个目录的安排，并等待用户回复。未回复、拒绝、只说“开始学习”或只确认目录，都不构成本次下载授权。版本或大小未知时不进行面向用户的远程安装。
4. 只有用户同意上述具体范围后，才传入该计划的confirmation_id执行下载；不能把生成计划、得到了确认编号或工具自身可调用当作用户同意。不得由Agent自行代答，也不得把两条命令连续执行来跳过对话确认：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" install-course-release \
  --source-config "${CODEBUDDY_SKILL_DIR}/references/release-source.json" \
  --install-root "/absolute/path/to/workspace/japanese-course" \
  --archive "/absolute/path/to/workspace/japanese-learning-records" \
  --activate \
  --download-confirmation "<用户明确同意的计划confirmation_id>"

5. 同一次已同意的下载中，保持相同范围的重试和已披露的CNB→GitHub备用切换可以继续，无需重复确认。CNB清单5秒无响应或课程包连续10秒无数据时可切换；用户撤回同意则停止。版本、哈希、大小、来源、目录或激活选项改变时重新展示计划并确认，不复用旧编号，也不保存永久自动批准。不得通过自写下载命令、浏览器另取ZIP或本机测试入口绕过确认。
6. 校验和安装完成后，告知所用来源、安装位置与结果，再使用返回的course_root。发生备用切换如实说明。首次启动本机播放器和保存学习记录按下一节处理，不把下载确认扩大为任意代码执行或学员档案访问。
7. 已安装版本通过list-course-versions查看；切换旧版本使用activate-course-version，显式回滚使用rollback-course-version。这些动作不得接收或改写学习档案路径。

开始一次学习

1. 使用install-course-release返回的课程目录及此前已确认的学习记录目录；路径未变时不重复询问。不得扫描用户主目录寻找课程，也不得把档案藏在技能安装目录或课程包内部。
2. 课程包根目录必须包含course-package.json。先检查播放器：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" player-service-status \
  --course-root "/absolute/path/to/course-package"

3. 第一次使用时，向学员说明将创建archive.json、state.json、events.jsonl、exchange/和播放器运行记录。只有学员确认两个目录后，使用一个受限命令完成初始化、启动播放器和创建首个会话；不得要求学员手动打开终端，也不得申请通用文件写入权限：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" begin-first-session \
  --course-root "/absolute/path/to/course-package" \
  --archive "/absolute/path/to/archive" \
  --archive-id "stable-anonymous-archive-id" \
  --learner-id "stable-anonymous-learner-id" \
  --session-id "unique-session-id"

4. 后续继续学习时先读取学习档案；只有调度结果要求创建播放器会话时才启动播放器：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" status --archive "/absolute/path/to/archive"

5. 不得直接根据due_review_ids或聊天记忆选择内容。调用确定性调度器：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" plan-next-session \
  --course-root "/absolute/path/to/course-package" \
  --archive "/absolute/path/to/archive"

6. 先检查should_create_player_session和execution_status。ready时才按session_mode执行：new_learning学习下一个激活单元；delayed_review只做最多6项先测后教的短复习；mixed先短复习再进入新单元。end_without_session不启动播放器、不重复旧单元，只简短说明今天没有到期复习或新的体验内容。blocked_missing_player_mode表示调度正确但当前课程包尚无对应播放器，必须停止并说明该活动尚未开放；不得退回完整单元、对话临时出题或其他会改变证据合同的替代流程。若档案不存在，先向学员说明将创建哪些本地文件，再运行init。
7. 会话请求必须写入调度器返回的session_mode、review_target_ids和new_work_unit_id，不得临时猜测工作单元、复习轮次或题目ID。只把当前真实动作写成事件。事件格式见本地档案与浏览器播放器交接合同。
8. 首次打开后用一句普通中文告诉学员：以后重新打开WorkBuddy，只需说“继续学习”。不要要求学员记住“网页”“本地播放器”、端口、URL或会话名称。

生成日历学习块

诊断交接完成后，只有available_minutes_by_weekday已经按星期填写，且学员为每个可学习日提供通常开始时间和具体不可学习时段，才运行：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" plan-calendar-blocks \
  --course-root "/absolute/path/to/course-package" \
  --archive "/absolute/path/to/archive" \
  --constraints-file "/absolute/path/to/calendar-constraints.json"

• 日历块只分配学员声明的可用容量；allocated_minutes不是工作单元基准时长，也不能用于推断课程完成日期。
• 不可学习时段从对应候选窗口中扣除；一个工作单元可以拆成多个块并在以后续接，不改写课程内容。
• 输出保存在档案planning/区域，不追加学习完成事件。只有实际学习和合同校验后的播放器结果才能更新学习状态。
• 缺少每周各日分钟时返回clarification_required；缺少某个可学习日的开始时间时停止并补问，不得自行选择时间。
• forecast在个人真实数据校准前保持pending_personal_calibration，各完成天数字段保持空值，guaranteed_pass始终为false。

继续学习或页面丢失

用户说“继续学习”“接着学”“打开日语课程”“刚才的学习页面不见了”时，不追问网页叫什么，也不让用户寻找旧链接。

1. 优先使用当前工作空间里已确认的课程目录和学习档案。若当前对话没有路径，只允许在当前工作空间内查找唯一的course-package.json和archive.json；不得扫描用户主目录。找到多个候选时再让学员选择。
2. 运行一个受限命令恢复最近的未完成会话：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" resume-learning \
  --course-root "/absolute/path/to/course-package" \
  --archive "/absolute/path/to/archive"

3. 返回status=ready时，直接打开practice_url并简短说明“已恢复上次的学习”。用简短中文说明恢复结果；需要联网、写入记录、处理失败或改变权限时，如实说明影响。
4. 返回completed_result_recovered时，说明上次学习已经完成并按档案安排下一步；不得重复创建同一练习。
5. 恢复命令会优先采用拥有真实页内进度的持久化会话，并忽略被新版会话替代的旧凭据。返回no_pending_session时必须调用plan-next-session，不得把永久列表里的全部目标直接重放。只有确实存在多个拥有独立页内进度的会话时，才会返回session_selection_required；此时只用课程名称或时间让学员选择，不展示内部会话ID。
6. progress_restored=false仅用于兼容没有页内持久化的旧体验包，应明确说明旧页面的位置没有保存；不得谎称恢复到原步骤。当前正式包必须返回progress_restored=true。

记录学习事件

先生成一个临时JSON事件文件，再运行：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" record-event \
  --archive "/absolute/path/to/archive" \
  --event-file "/absolute/path/to/event.json"

• 使用稳定且唯一的event_id；重复导入同一ID必须得到duplicate_ignored，不得重复累计。
• 区分agent_explanation_shown、teaching_exposure、independent_practice、review_scheduled和practice_result_imported。
• 不得仅凭学员说“看懂了”写入confirmed_strength；把这类信息放入learner_reported证据。

调用本地浏览器播放器

1. 按合同准备会话请求，至少包含稳定session_id、work_unit_id、practice_asset_ids和requested_at。
2. 创建播放器会话；电脑端首发默认使用播放器返回的本机地址：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" create-player-session \
  --archive "/absolute/path/to/archive" \
  --request-file "/absolute/path/to/session-request.json" \
  --player-base-url "http://127.0.0.1:8802"

3. 把命令返回的practice_url展示给学员并说明即将打开本地课程播放器。由WorkBuddy调用自身的浏览器能力打开；脚本本身不强制启动浏览器。播放器地址以已安装课程的course-package.json中player.base_url为准；上例对应绑定的rc.2。仅支持本机播放器，不连接远程学习服务。
4. 学员完成后回收结果：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" fetch-player-result \
  --course-root "/absolute/path/to/course-package" \
  --archive "/absolute/path/to/archive" \
  --session-id "session-id"

5. 只有播放器结果为completed且合同校验通过时，桥接脚本才返回recorded或duplicate_ignored。新结果返回recorded后才算完成首次导入；结果成功回收后由桥接脚本停止播放器，下次学习再按需启动。播放器未启动或结果不可达时保留会话待回收，不写成完成。

面向学员的完成反馈

• 默认只说明：本单元或短复习已完成、本次小测表现、一次结果不等于掌握，以及plan-next-session实际返回的下一步。控制在普通学员一眼能看懂的长度。
• 除非学员主动询问，不展示session_id、result_id、内部字段名、事件类型、端口、进程、文件清单或完整路径；也不复述检查和检索过程。
• due_review_ids只是按当前日期计算的兼容字段；必须以逐目标复习状态和plan-next-session结果判断是否现在到期。不得把“未来已安排”说成“现在就该复习”。
• 学员跳过讲解但在小测中答对，只能说“本次答对，后续仍会复习”，不得把“跳过”单独解释成薄弱或错误。

本地备份与导出

• 当前版本不提供账户同步、远程学习或档案上传。
• 导出只交付学员自己的档案和公开课程引用，不导出答案密钥、内部评分逻辑或其他用户数据。

学员要求备份、迁移或导出时，让学员明确选择课程档案之外的.zip目标路径，然后运行：

python3 "${CODEBUDDY_SKILL_DIR}/scripts/learning_bridge.py" export-archive \
  --archive "/absolute/path/to/archive" \
  --output "/absolute/path/to/learner-owned-export.zip"

不得直接压缩整个档案目录。安全导出采用严格允许清单，排除runtime/、exchange/、答案、内部评分实现、隔离结果和未识别文件；目标已存在时必须停止，不能覆盖。解压后的n5-learner-archive/可直接用status检查或用migrate-archive迁移。

失败处理

• 路径不存在：停止并让学员确认目标，不创建多个平行档案。
• 课程包缺少course-package.json、文件哈希不一致或包状态不受支持：停止，不运行其中的脚本。
• 合同校验失败：原文件不改写，报告具体缺失字段。
• 播放器未启动、超时或失败：保留outbox会话凭据，稍后重试。
• 本地写入失败：不得用对话记忆代替持久记录。
• 播放器结果与本地工作单元不一致：隔离到quarantine，等待人工确认。

参考

• 需要字段、证据等级、目录布局和播放器接口时，读取本地档案与浏览器播放器交接合同。