study-tool/AGENTS.md

AGENTS.md

本文档用于约束本项目中的 AI / 自动化开发行为。开发时优先遵循本文件，其次遵循用户当前消息。

基本原则

• 先读现有代码，再动手修改，优先沿用项目已有结构和写法。
• 写代码保持最少行数，能简单实现就不要引入复杂抽象。
• 标准格式、协议、解析、压缩、加密、日期等通用能力优先使用成熟稳定的库，不要手写底层实现，除非用户明确要求或项目已有实现必须沿用。
• 不要为了“兼容更多场景”写大量分支，只实现当前明确需要的功能。
• 项目尚未上线，不需要兼容旧数据；表结构或字段调整时直接按新设计修改，不写旧字段兼容、数据迁移兜底或删除旧表的清理逻辑，除非用户明确要求。
• 每次写完代码，不需要检查语法，不需要执行构建，用户会自己做。
• 不要改无关文件，不要顺手重构。
• 任何文件编辑、改动、删除或格式化前，必须先询问用户是否允许；只有得到明确同意后才能修改。
• 如果工作区已有用户改动，不要回滚，不要覆盖；只在必要范围内追加修改。

反复提醒沉淀

• 如果开发过程中总是遇到某个问题，或者用户反复提醒同一个注意事项，需要把该注意事项补充到本文件。
• 补充时写成明确、可执行的规则，避免只写模糊描述。
• 新规则应放到最相关的章节；找不到合适章节时放到“项目注意事项”。

日志规范

• 所有日志只走 runtime.log(key, msg, level="info")：它统一写控制台、内存（/api/log）和 SQLite（/api/log/history），三处内容必须一致。
• 禁止在新代码里自己 print() 写业务日志，也不要直接调 store.run_log_add()；模块只负责组织 msg。
• key 约定：账号相关用账号 id（页面卡片「课程日志」直接显示）；全局 / 系统事件用 "system"（右上角「系统日志」弹窗显示）。
• 时间戳、级别、格式都由 runtime.log 统一拼（时间 [级别] 内容），模块里不要自己加时间前缀。
• 前端读日志统一用 /api/log?key=&since=（实时）+ /api/log/history?key=&tail=（历史兜底），不要另起一套日志接口。

代码结构 / 平台插件

• 业务代码都在 src/study_tool/ 包里；根目录只放启动壳 app.py、pyproject.toml、static/、data/、script/ 这类运行时资源。散落的 JS 脚本统一收进 script/，不参与运行的参考脚本放 script/reference/。
• 平台代码有两个落点：插件式平台放 src/study_tool/pugins/<名字>/（pugin.json 只放 id / title / name 注册信息，main.py 放 Platform 子类，load_plugins() 扫目录 import，新增插件不用改任何 Python 代码；GET /api/plugins 看清单，POST /api/plugins/{name}/enable|disable 启停，POST /api/plugins/reload 热重载）；跟共享实现模块关系紧密的平台放 src/study_tool/platforms/<名字>.py 并在 load_builtin() 里 import。能力只能通过「在子类里实现同名方法」绑定，禁止再写 Platform(id=..., study=..., session=...) 这种逐项传函数的注册；模块末尾 PLATFORM = registry.register(<子类>())，一个平台只注册一次。同一平台的不同页面代际可以拆成实现模块（如莞易学的 jspx.py / study.py），由平台模块按 course["generation"] 分发。
• 新增平台的标准步骤：建 pugins/<名字>/，写 pugin.json（id / title / name）和 main.py（class X(Platform)，声明 id / label / entries，实现 study(self, key, s, d, **opts)，需要登录 / 课程列表 / 发现时再实现 session / dump_cookies / login / list_courses / discover / renew_session / profile 对应方法，没有的阶段不写，末尾 PLATFORM = registry.register(X())）→ 启动即可，不用改 load_builtin()、engine.py、routes/、前端。
• 引擎、路由、前端都不允许直接 import 某个具体平台模块；需要平台能力时用 registry.get(course["platform"])；账号级操作（登录 / 刷新课程 / 发现课程 / 会话）按 accounts.platform 用 registry.get() 取 Platform 上的 session / dump_cookies / login / list_courses / discover / renew_session / profile；「添加账号」的平台下拉来自 GET /api/platforms。
• 前端源码在 web/（React + TypeScript + Vite + Tailwind CSS），构建产物输出到 static/ 并提交进仓库；改完前端必须执行 cd web && pnpm build，不要直接改 static/ 里的产物。
• 新代码的 import 一律显式（如 from study_tool.config import JSPX），不要再新增 from xxx import *；历史遗留的 star import 只保留在拆分前就存在的模块里。
• docs/architecture.md 维护分层与插件契约，改动结构时同步更新。

文档规范

• README 保持简洁，只放项目介绍、核心功能、快速开始和文档入口。
• 后续待办写到 docs/progress/todo.md。
• 已实现但还需要用户测试确认的事项写到 OPTIMIZATION.md。
• 每次任务完成前，都要根据实际变更检查并更新 OPTIMIZATION.md 和 OPTIMIZATION.md；如果功能或待办没有变化，也要确认无需修改。
• 文档不要写过期日期；除非用户明确要求记录具体时间。

发版本流程

• 发版本时，先把 CHANGELOG.md 的 Unreleased 变更整理成新的版本记录，并保留空的 Unreleased 标题。
• 每次提交必须将当前版本号进行提升，更新 metadata.yaml里面的version中的版本号。
• 将当前未提交的代码全部提交到 Git。
• 提交完成后，给当前提交打最新版本号对应的 tag，例如 v0.0.5。
• 发版本流程中不要执行编译、测试或构建，除非用户明确要求。
• 如果触发重要的决策，你需要将代码提交到git中，并且将本次已经修改的内容进行总结