tchMaterial-parser/AGENTS.md

Agent 指南

这是一个面向国家中小学智慧教育平台的桌面工具，用来解析并批量下载电子课本等资源。

编写代码时请参考贡献者指南，遵守其中的代码格式、文案等约定。

深度思考，积极搜索互联网，查阅最新开发文档与行业最佳实践。

若需要任何工具或依赖，请自行安装。

编写规则

1. 本工具支持的最低 Python 版本为 3.10，编写代码时请确保其能在 Python 3.10 中正常运行，例如在 f-string 嵌套字符串时应注意引号问题，使用类似于下述格式：

   f"文本 {data['item']}"
   

   而不是：

   f"文本 {data["item"]}"
   

2. 本工具在设计上支持 Windows、Linux、macOS 操作系统，编写代码时应确保跨平台兼容性。

3. 确保代码可维护性：

   • 实现新功能时应搜索已有实现，不要出现冗余代码；
   • 优先执行最小修复，避免回归，不要重构无关代码，不要为了修复一个小问题而引入一堆大改动；
   • 修复复杂问题时，应先分析项目整体结构再改动。

4. 修改代码后，应执行测试与检查。

5. 若用户要求修改工具的版本号，只需修改 pyproject.toml 与 version_info.txt 中的有关信息即可。

结构约定

1. 临时文件统一放在 .tmp/ 目录（该目录已加入 .gitignore，不存在时自行创建）。
2. 除非用户提到，否则默认无需阅读 .devfiles/ 下的文件，且禁止做任何修改。
3. 添加/修改大功能时，应同步添加/修改 tests/ 目录下的测试文件。
4. 未被 .gitignore 忽略的文件不得包含明文 Access Token 等敏感数据。

Git 操作

1. 除非用户要求，否则不要执行 commit 与 push。
2. 若被用户要求写 commit：
   • 请只生成遵循「Conventional Commit」的提交消息，内容应当描述为「最后一个 commit → 当前工作区」的整体 diff，而不应该提及本次实现过程中的尝试、报错、排查、返工或中间修正的迭代过程；
   • 若该 commit 能够关闭一个 issue，请在提交消息末尾加上 close #xxx 以确保 issue 关闭时能够与此 commit 关联，而不是使用 fix(#xxx): xxx 等格式。