# Agent 指南

这是一个面向[国家中小学智慧教育平台](https://basic.smartedu.cn/)的桌面工具，用来解析并批量下载电子课本等资源。

编写代码时请参考[**贡献者指南**](./CONTRIBUTING.md)，遵守其中的代码格式、文案等约定。

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

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

## 编写规则

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

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

   而不是：

   ```python
   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` 等格式。