 snowy-yang
|
52004571c8
|
docs: 记录工程化改造（uv + ruff + pyright）的决策与踩过的坑
日志补记下半场：三件套的落地细节、行宽为何定 100、PTH 为何不开、pyright 两个关键开关；新增三条可复用环境坑（write_text 会把 LF 变 CRLF、同文件多次 Edit 互相覆盖、git status 与 git diff 不一致的判别）。
项目长期约定同步更新：运行方式改为 uv 单一可信来源，新增代码风格约定与质量门禁命令。
|
2026-09-18 21:28:20 +08:00 |
|
|
snowy-yang
|
c414db4217
|
fix: 用户可见的操作提示统一为 uv run 前缀
项目由 uv 管理，依赖装在 .venv。此前各处的提示语仍写作 `python main.py ...`，用户若在未激活虚拟环境时照抄，会因缺少 fastapi 而失败——这是正确性问题，不只是措辞。
涉及：main.py（12 行，含 prog 与各条 hint）、ai_player.py（5 行）、farm/client.py、farm/server/__main__.py（3 行，含 prog）、farm/server/__init__.py、farm/server/daemon.py、README（4 处示例与目录树注释）。
刻意保留 main.py:26 与 README:49 的「没装 uv？」兜底说明，那里 `python main.py` 是正确写法。
验收：ruff 全通过 / format 26 文件无改动 / pyright 0 错误 / 97 项测试通过。
|
2026-09-18 21:25:52 +08:00 |
|
|
snowy-yang
|
d7a7107b0a
|
chore: 引入 pyright 类型检查清零 + README 工程化章节
pyright（basic 模式）从 15 errors / 10 warnings 降到 0/0：
- pyproject: pythonPlatform="All"（termios/msvcrt 双平台分支不再误报），
reportUnsupportedDunderAll=false（__init__ 惰性导出属正常写法）
- keys.py: 捕获 sys.stdin 局部变量 + 提前返回，消除 fileno() 的 None 收窄告警
- server/app.py: lifespan 改用 @asynccontextmanager 并标注 AsyncIterator[None]
- server/actions.py: 显式标注 result: dict[str, Any]，消除 isinstance 冗余报错
- server/__main__.py: 用 importlib.util.find_spec 探测 websockets
- tests/test_server.py: 同上，uvicorn 探测改为 find_spec
- tools/preview_tui.py: TYPE_CHECKING 下引入 RemoteFarm，修正返回类型标注
- farm/tui.py: 取消未使用变量，统一 round/取整写法
其他：
- README: 新增第 11 节「工程化：uv + ruff + pyright」，快速开始全部改用
uv sync / uv run；原第 11 节起顺延为 12
- requirements.txt: 由 uv export --no-dev --no-hashes 重新生成（锁定版本）
- 清理临时日志文件
验收：ruff check 全通过 / ruff format 26 文件无改动 / pyright 0 错误 /
unittest 97 项全部通过
|
2026-09-18 21:24:30 +08:00 |
|
|
snowy-yang
|
fcd4cb4649
|
style: 引入 ruff，474 项告警清零
配置见 pyproject.toml：
- line-length=100：贴着现有代码定。若用默认的 88 会重排 122 行，
噪音淹没真正有价值的修复。
- 启用 E/W/F/I/UP/B/C4/SIM/RET/PERF/RUF；**不**启用 PTH。因为本项目的路径
多是"字符串身份"——要塞进 subprocess 命令行、写进 JSON 存档、打印给用户，
全换 pathlib 只是包一层再拆一层，换来 70 处纯风格改动。
- 忽略 RUF001/002/003：中文全角标点是正确写法，不是"歧义字符"。
- 忽略 PERF203：剩下两处都是"逐项容错"语义（逐个牧场存档要立刻上报失败、
收获全部要跳过失败地块）。把 try 提到循环外会毁掉"一项失败不影响其它项"
这个行为，是错的优化。
自动修复 358 项：Dict/List/Optional 换成 PEP 585/604 写法、导入排序、
失效的 noqa、空占位 f-string 等。
手工修复的（这些是真问题，不是风格偏好）：
- B904 x9：except 中 raise 补异常链。刻意区分——网络/IO 失败用 from exc 保留
根因；参数解析失败用 from None，因为底层 ValueError 对玩家只是噪音。
- RUF012 x2：StateView 的 plots/animals 原本是**类级共享可变列表**，
改成在 __init__ 里初始化（apply({}) 会提前返回，所以必须显式摆好）。
- F841：TUI 里一个赋值后再没用过的死变量。
- SIM105 x11：try/except/pass 统一改成 contextlib.suppress。
- SIM115：日志句柄改用 with。Popen 已把 fd 复制给子进程，父进程可安全关闭。
- E501 x7：拆超长行；main.py 那处顺手提取变量，避免超长嵌套表达式。
- E741：把 l/r 改成 left_line/right_line。
- 其余：RUF046 / PERF401 / RET504 / RUF005 / UP031 / B007。
ruff format 重排 24 个文件。
验证：97 项测试全绿。
|
2026-09-18 21:18:22 +08:00 |
|
|
snowy-yang
|
c7c8a6308a
|
chore: 统一行尾为 LF，清理临时文件
新增 .gitattributes 把文本文件钉死为 LF：否则 git 在 Windows 的 autocrlf
会把仓库的 LF 转成工作区 CRLF，与 ruff format 的 line-ending=auto 互相打架，
每次格式化都在改行尾。
|
2026-09-18 21:13:01 +08:00 |
|
|
snowy-yang
|
a7725f8812
|
chore: 工程化改造前的基线快照
在引入 uv 依赖管理、ruff 静态检查与格式化、pyright 类型检查之前，
先把当前可正常运行的状态固定下来，作为后续大规模自动改动的回滚点。
此时状态：97 项测试全绿，HTTP + WebSocket 多牧场服务器可用。
|
2026-09-18 21:12:40 +08:00 |
|