From 32633f7eec6f6cb9277a222153edd5306b786a05 Mon Sep 17 00:00:00 2001
From: JOJO <1498581755@qq.com>
Date: Sat, 1 Aug 2026 10:45:53 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E4=BF=AE=E6=AD=A3=E5=86=92?=
 =?UTF-8?q?=E7=83=9F=E6=B5=8B=E8=AF=95=E5=91=BD=E4=BB=A4=EF=BC=8CWindows?=
 =?UTF-8?q?=20=E4=B8=8A=20stdlib=20test=20=E5=8C=85=E9=81=AE=E8=94=BD?=
 =?UTF-8?q?=E6=9C=AC=E5=9C=B0=20test=20=E7=9B=AE=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9e52d86a..90c65fc4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -131,15 +131,17 @@
 ## 3) 测试现状（不要再写过时命令）
 
 - 当前仓库内可见自动化冒烟：`test/test_server_refactor_smoke.py`（`unittest`）
-  - 运行方式：`python -m unittest test.test_server_refactor_smoke`
+  - 运行方式：`python -m pytest test/test_server_refactor_smoke.py -q`
+  - 注意（2026-08-01 实测）：`python -m unittest test.test_server_refactor_smoke` 在标准 Windows Python 上失败——stdlib 自带常规包 `test` 遮蔽本地 `test/` 目录（无 `__init__.py` 的命名空间包优先级更低），报 `No module named 'test.test_server_refactor_smoke'`。无 pytest 时可用：
+    `python -c "import sys; sys.path.insert(0, '.'); import unittest; suite = unittest.TestLoader().discover('test', pattern='test_server_refactor_smoke.py'); r = unittest.TextTestRunner().run(suite); sys.exit(0 if r.wasSuccessful() else 1)"`
 - `test_system_message.py` 依赖外部 `MOONSHOT_API_KEY` 与网络，不属于离线稳定 CI 用例。
-- 当前仓库未发现 `pytest.ini`/`pyproject.toml`/`tox.ini`；不要默认要求 `pytest` 作为唯一入口。
+- 当前仓库未发现 `pytest.ini`/`pyproject.toml`/`tox.ini`；不要默认要求 `pytest` 作为唯一入口（仅作为冒烟测试的便捷运行器）。
 - CLI 当前最小可复现验证：
   - `npm --prefix cli run typecheck`
   - `npm --prefix cli run build`
 - 若改动 `server/chat/`、`server/status/`、`server/tasks/` 等后端接口适配，补充：
   - `python3 -m py_compile server/chat/*.py server/status/*.py server/tasks/*.py`
-  - `python -m unittest test.test_server_refactor_smoke`
+  - `python -m pytest test/test_server_refactor_smoke.py -q`
 
 ## 4) 代码修改约定（实用版）