study-tool
491fd08c1e
- platforms/guanyixue.py → pugins/guanyixue/main.py - jspx.py / study.py / detect.py 一并搬进插件目录，插件自包含： 热重载会把实现模块一起重新 import，不再是半截插件 - 导入路径改成 study_tool.pugins.guanyixue.*；quiz.py 两处引用同步更新 - platforms/__init__.py 只剩运行时，load_builtin() 只调 load_plugins() - 新增 pugins/guanyixue/pugin.json（id / title / name） - 同步 AGENTS.md、docs/architecture.md、docs/pugin.md、docs/OPTIMIZATION.md
56 lines
5.9 KiB
Markdown
56 lines
5.9 KiB
Markdown
# 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` 子类，实现复杂的再拆 `jspx.py` / `study.py` 等同目录模块；`load_plugins()` 扫目录 import，新增插件不用改任何 Python 代码（`GET /api/plugins` 看清单，`POST /api/plugins/{name}/enable|disable` 启停，`POST /api/plugins/reload` 热重载）。`src/study_tool/platforms/` 只放运行时（`base` / `contract` / `errors` / `registry`），不再放具体平台。能力只能通过「在子类里实现同名方法」绑定，禁止再写 `Platform(id=..., study=..., session=...)` 这种逐项传函数的注册；模块末尾 `PLATFORM = registry.register(<子类>())`，一个平台只注册一次。同一平台的不同页面代际拆成插件目录内的实现模块，由平台模块按 `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`中，并且将本次已经修改的内容进行总结 |