feat: add CONTRIBUTING.md, improve AGENTS.md

Signed-off-by: 晨叶梦春 <wuziqian211@126.com>

AGENTS.md

@@ -1,19 +1,42 @@
-这是一个面向 [国家中小学智慧教育平台](https://basic.smartedu.cn/) 的桌面工具，用来解析并批量下载电子课本。
+# Agent 指南
 
-深度思考，积极搜索互联网查阅最新开发文档与行业最佳实践。
-确保代码可维护性，确保跨平台兼容性，避免回归，拒绝代码冗余与「屎山」堆积。
-命名及时重构，新变量命名需语义清晰，同时更新相关的旧变量名。
-代码意图不明确时，主动编写清晰准确的中文注释。
-涉及到 UI 的调整需同时兼顾浅色与深色模式。
-需要任何工具或依赖，请自行安装。
-临时文件统一放在 `.tmp/` 目录（该目录已加入 `.gitignore`，不存在时自行创建）。
-未被 `.gitignore` 忽略的文件不得包含敏感数据。
+这是一个面向[国家中小学智慧教育平台](https://basic.smartedu.cn/)的桌面工具，用来解析并批量下载电子课本等资源。
 
-不要为那些不可能发生的场景添加错误处理、回退逻辑或校验。应当信任内部代码以及框架提供的保证。只在系统边界处进行校验，例如用户输入、外部 API 等，防止过度工程化编程。
-UI 界面上所有文案必须是站在使用者角度、可直接交付的最终产品语言，不得出现描述需求/规则/适用条件本身的元语言。
+编写代码时请参考[**贡献者指南**](./CONTRIBUTING.md)，遵守其中的代码格式、文案等约定。
 
-被要求写 commit 时，只撰写 conventional commit 文案，不要执行 commit 和 push（除非用户提到），
-内容应当描述最后一个「最后一个 commit → 当前工作区」的整体 diff，
-而不应该提及本次实现过程中的尝试、报错、排查、返工或中间修正的迭代过程。
+**深度思考，积极搜索互联网，查阅最新开发文档与行业最佳实践。**
 
-默认无需阅读 `.devfiles/` 下的文件（除非提到），且禁止做任何修改。
+若需要任何工具或依赖，请自行安装。
+
+## 编写规则
+
+1. 本工具支持的最低 Python 版本为 **3.10**，编写代码时请确保其能在 Python 3.10 中正常运行，例如在 f-string 嵌套字符串时应注意**引号问题**，使用类似于下述格式：
+
+    ```python
+    f"文本 {data['item']}"
+    ```
+
+    而不是：
+
+    ```python
+    f"文本 {data["item"]}"
+    ```
+
+2. 本工具在设计上支持 Windows、Linux、macOS 操作系统，编写代码时应确保**跨平台兼容性**。
+3. 确保代码**可维护性**：
+    - 实现新功能时应搜索已有实现，不要出现冗余代码；
+    - 优先执行**最小修复**，避免回归，不要重构无关代码，不要为了修复一个小问题而引入一堆大改动；
+    - 修复复杂问题时，应先**分析项目整体结构**再改动。
+4. 修改代码后，应执行**测试与检查**。
+
+## 结构约定
+
+1. 临时文件统一放在 `.tmp/` 目录（该目录已加入 `.gitignore`，不存在时自行创建）。
+2. 除非用户提到，否则默认无需阅读 `.devfiles/` 下的文件，且禁止做任何修改。
+3. 添加/修改大功能时，应同步添加/修改 `tests/` 目录下的测试文件。
+4. 未被 `.gitignore` 忽略的文件**不得包含明文 Access Token 等敏感数据**。
+
+## Git 操作
+
+1. 除非用户要求，否则不要执行 commit 与 push。
+2. 若被用户要求写 commit，只生成遵循「**Conventional Commit**」的提交消息，内容应当描述为「最后一个 commit → 当前工作区」的**整体 diff**，而不应该提及本次实现过程中的尝试、报错、排查、返工或中间修正的迭代过程。

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# 贡献者指南
+
+感谢您愿意帮助改进本项目。这个项目面向**真实用户**，请尽量让每一次提交都保持清晰、可验证，并尊重国家中小学智慧教育平台及相关权利人的资源版权。
+
+## 开始之前
+
+- 提交问题前请**搜索**已有 [Issue](../../issues) 和 [Pull Request](../../pulls)，避免重复讨论。
+- 发现程序无法运行、下载失败或界面异常时，请提交 [**🐛 Bug 报告**](../../issues/new?template=bug_report.yml)，并按模板补全相关信息，最好**附上错误信息截图**，以方便定位问题。
+- 有新功能或改进建议时，请提交[**✨ 功能建议**](../../issues/new?template=feature_request.yml)，先说明您遇到的实际问题，再描述期望做法，这样更容易判断改动是否适合放进本项目。
+- **不要**在 Issue、Pull Request、提交信息或代码等地方公开 Access Token。
+
+## 本地开发
+
+本项目使用 **Python 3.10 或更高版本**（`X | Y` 形式的类型注解仅在该版本及以后的版本可用）。
+
+```sh
+# 克隆项目
+git clone https://github.com/happycola233/tchMaterial-parser.git
+cd tchMaterial-parser
+
+# 安装依赖
+python -m pip install .
+
+# 启动应用
+python ./src/main.py
+```
+
+> [!NOTE]
+> 本工具使用 **Tkinter** 构建图形界面。Windows 与 macOS 的官方 Python 通常已自带，而部分 Linux 发行版需要单独安装，例如在 Debian/Ubuntu 上执行 `sudo apt install python3-tk`。
+>
+> 此外，精简安装的 Linux 系统可能缺少中文字体与 Emoji 字体，此时界面上可能会出现方框等异常现象。可按需安装，例如在 Debian/Ubuntu 上执行 `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`。
+
+## 测试与检查
+
+提交 Pull Request 前，请进行测试与检查：
+
+```sh
+# 安装开发用依赖
+python -m pip install pytest flake8
+
+# 运行测试与检查
+python -m pytest
+python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+```
+
+当前 CI 的静态检查只拦截语法错误、未定义变量等确定性问题，不把代码风格与中文注释行长等作为强制门槛。
+
+格式化时请遵循仓库现有风格，如使用 **4 空格**缩进、**`snake_case`** 命名约定、字符串默认使用**双引号 `"`**、**不出现尾随空格**等。
+
+## 打包验证
+
+修改打包配置、资源文件或程序入口时，请额外验证 PyInstaller 构建：
+
+```sh
+python -m pip install pyinstaller
+pyinstaller ./tchMaterial-parser.spec
+```
+
+构建产物位于 `dist` 目录。
+
+## 代码与文案约定
+
+- 本工具在设计上支持 Windows、Linux、macOS 操作系统，编写代码时应确保**跨平台兼容性**。
+- 命名要**准确表达意图**；重命名变量、函数或模块时，请**同步更新**相关引用。
+- 意图不明显的业务逻辑可以添加**简洁中文注释**；能从代码本身读懂的内容一般不需要注释。
+- 不要为了理论上不可能发生的内部状态添加复杂兜底逻辑，校验应主要放在用户输入、文件系统、网络请求、外部 API 等**系统边界**。
+- 涉及 UI 的改动，需要同时检查**浅色模式与深色模式**。
+- 界面文案应直接面向**用户**，避免出现描述需求、规则或适用条件本身的元语言。
+- 修改代码后，确保代码中**未出现明文 Access Token 等敏感信息**，且已执行**必要的测试与检查**。

README.md

@@ -98,27 +98,7 @@ yay -S tchmaterial-parser
 
 ### 从源码运行
 
-若您想体验最新的改动，或是希望参与开发，可以直接从源码运行本工具，需要 **Python 3.10 或更高版本**（`X | Y` 形式的类型注解仅在该版本及以后的版本可用）。
-
-```sh
-git clone https://github.com/happycola233/tchMaterial-parser.git
-cd tchMaterial-parser
-pip install .
-python ./src/main.py
-```
-
-> [!NOTE]
-> 本工具使用 Tkinter 构建图形界面。Windows 与 macOS 的官方 Python 通常已自带，而部分 Linux 发行版需要单独安装，例如在 Debian/Ubuntu 上执行 `sudo apt install python3-tk`。
->
-> 此外，精简安装的 Linux 系统可能缺少中文字体与 Emoji 字体，此时界面上可能会出现方框等异常现象。可按需安装，例如在 Debian/Ubuntu 上执行 `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`。
-
-若您想自行打包为可执行文件，可以在安装 `pyinstaller` 后执行：
-
-```sh
-pyinstaller ./tchMaterial-parser.spec
-```
-
-编译后的程序位于 `dist` 目录中。
+若您想体验最新的改动，或是希望参与开发，可以直接从源码运行本工具，详见[贡献者指南](./CONTRIBUTING.md#本地开发)。
 
 ## 🛠️ 使用方法
 
@@ -174,7 +154,7 @@ https://basic.smartedu.cn/tchMaterial/detail?contentType=assets_document&content
    })();
    ```
 
-4. 复制控制台输出的 **整段 JSON**，然后在本工具中点击 “**设置 Token**” 按钮，粘贴并保存。
+4. 复制控制台输出的**整段 JSON**，然后在本工具中点击 “**设置 Token**” 按钮，粘贴并保存。
 
 > [!NOTE]
 > Access Token 可能会过期，若下载失败，请重新获取并设置新的 Token。
@@ -241,10 +221,12 @@ https://basic.smartedu.cn/tchMaterial/detail?contentType=assets_document&content
 </a>
 </div>
 
-## 🤝 贡献指南
+## 🤝 参与贡献
 
 如果您发现 Bug 或有改进建议，欢迎提交 **[Issue](../../issues)** 或 **[Pull Request](../../pulls)**，让我们一起完善本工具！
 
+参与开发前，建议先阅读[贡献者指南](./CONTRIBUTING.md)，了解本地开发、测试检查、Pull Request 与合规边界说明。
+
 感谢所有为本项目做出贡献的朋友：
 
 <div align="center">