UnicodeEncodeError crash on Windows (GBK codepage) when tools print ✅/❌

Author: allenhangliu-designCreated Jul 19, 2026Updated Aug 14, 2026

Summary

Several scripts under tools/ crash with UnicodeEncodeError when run in a stock Windows terminal (PowerShell/cmd, non-UTF8 codepage), because they print / characters directly without ensuring UTF-8 output encoding.

Repro

> python tools\financial_rigor.py verify-market-cap --price 333.74 --shares 14.69e9 --reported 4.90e12 --currency USD
============================================================
市值验算 (Market Cap Verification)
============================================================
  股价 (Price):       333.74 USD
  总股本 (Shares):    14.69B
  计算市值:           4.90T USD
  报告市值:           4.90T USD
  偏差:               0.05%

Traceback (most recent call last):
  File "tools\financial_rigor.py", line 451, in <module>
    main()
  File "tools\financial_rigor.py", line 428, in main
    verify_market_cap(args.price, args.shares, args.reported, args.currency)
  File "tools\financial_rigor.py", line 90, in verify_market_cap
    print(f"  ✅ 验证通过, 偏差仅 {deviation:.2f}%")
UnicodeEncodeError: 'gbk' codec can't encode character '✅' in position 2: illegal multibyte sequence

The core computation actually completes correctly (you can see the verified numbers print before the crash) — it's purely an output-encoding failure, but it kills the process before the final ✅/❌ verdict line prints, which is often the most important line (pass/fail).

Affected files

All scripts under tools/ that print /:

  • tools/ashare_data.py
  • tools/financial_rigor.py
  • tools/momentum_backtest.py
  • tools/momentum_backtest_v2.py
  • tools/report_audit.py
  • tools/stock_screener.py
  • tools/twstock_data.py

Since several investment-research.md-style skill files instruct Claude Code / Codex to call these tools via Bash as a mandatory verification step ("必须调用 ... 禁止LLM心算"), this crash silently breaks the verification gate on any Windows machine with a non-UTF8 default codepage (common on non-English-locale Windows installs, but also plenty of English ones depending on system settings).

Workaround

Setting PYTHONIOENCODING=utf-8 before invoking Python avoids the crash. But this isn't discoverable from the skill instructions or README, so most users/agents hit the crash first.

Suggested fix

Add near the top of each affected script (or a shared import):

python
import sys
if sys.stdout.encoding != "utf-8":
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
    sys.stderr.reconfigure(encoding="utf-8", errors="replace")

(reconfigure is available on Python 3.7+, which the project already appears to target.) Happy to submit a PR with this fix if useful — flagging as an issue first since it touches 7 files.