平台陷阱实战手册

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install platform-pitfalls
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 platform-pitfalls。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Platform Pitfalls Playbook 是一份技术参考资料，用于诊断和预防那些常被绿色的 macOS 或 Linux 构建结果掩盖的故障。它聚焦于三个反复出现的问题领域：Python、子进程、文件 I/O、CMake、MSVC 和 Windows 控制台中的中文及非 ASCII 文本；PowerShell 5.1 编码问题；以及常见的 C++20 协程风险。
对于使用 Openclaw Skills 开发跨平台构建工具、CI、安装程序或异步 C++ 的开发者，这份手册将来之不易的工程经验转化为可复现的检查。其指导原则是在每个边界明确声明 UTF-8、在真实 Windows 环境中验证，并报告错误，而不是悄悄替换或屏蔽错误。

应用场景

诊断 Windows 上中文或非 ASCII 文本显示为乱码的问题，包括使用
charmap
gbk
编码时出现的
UnicodeEncodeError
。
在 Python 和跨平台构建工具中处理中文文件路径、测试名称、子进程输出及重定向日志。
修复在 Windows PowerShell 5.1 中运行异常的
.ps1
脚本或 Python CLI 输出。
调查 C++20 协程故障，例如优化时出现的悬垂生命周期、持有互斥锁时恢复执行，或 AddressSanitizer 报告的
container-overflow
。
针对中文 Windows 代码页 936/GBK，以及使用其他代码页的 Windows 运行器，验证构建工具、CI 作业和安装程序。
将新发现的平台问题添加到可复用的工程参考资料中，并记录症状、原因、修复方法和验证命令。

工作原理

将观察到的症状与相关参考资料对应起来：UTF-8 流程、PowerShell UTF-8 或 C++20 协程指南。
追踪故障到其平台边界，例如 Python 入口点、子进程、文件操作、CMake 命令、MSVC 配置、控制台代码页或协程生命周期。
应用相应的显式编码或协程安全指南，而不是依赖本地默认设置或悄悄屏蔽错误。
在受影响的 Windows 环境中复现并验证修复；适用时还要检查中文路径和内容、重定向日志，以及清晰可读的故障诊断信息。
将新确认的陷阱记录为可复现的工程事实，并按症状、原因、解决方案和验证命令进行整理。

配置指南

此技能是一份参考手册，而非命令行软件包。将其 SKILL.md 和 references/ 目录提供给你的 Openclaw Skills 环境，然后在处理跨平台构建、Windows 编码、PowerShell 5.1 或 C++20 协程时加载此技能。源文件未指定软件包安装或凭据。
使用症状索引打开对应的参考资料：
references/chinese-utf8-pipeline.md：Python、子进程、文件 I/O、CMake、MSVC 和 Windows 控制台中的编码问题。
references/windows-powershell-utf8.md：PowerShell 5.1 乱码及相关 Python 控制台输出问题。
references/cpp20-coroutines.md：C++20 协程陷阱检查清单。
此技能未指定安装命令或规定的 CI 命令；请根据项目和目标 Windows 环境运行适用的验证命令。

数据架构

此手册按技术领域和症状组织故障排查指南：
文件 范围
SKILL.md 技能元数据、使用触发条件、通用原则、维护指南和参考资料索引。
references/chinese-utf8-pipeline.md 覆盖 Python 入口点、子进程、文件 I/O、CMake、MSVC 和控制台的五层中文/非 ASCII 编码防护，并提供验证指南。
references/windows-powershell-utf8.md PowerShell 5.1 三层修复方案：UTF-8 BOM、chcp 65001 和字节数组；还涵盖相关的 Python 控制台行为。
references/cpp20-coroutines.md 11 个 C++20 协程陷阱，按症状、原因和修复方法组织，并附有集成验证说明。
添加已确认陷阱时，建议采用以下结构：症状 → 原因 → 解决方案 → 验证命令。当同一类问题反复出现，或形成独立的技术领域时，应新增章节。元数据将此技能标识为 platform-pitfalls，版本为 1.0.0，作者为 dqsjqian，显示名称为 “Platform Pitfalls Playbook”。

高级特性

提供从症状到参考资料的索引，便于快速查找编码、PowerShell 和协程问题。
涵盖五层 UTF-8 防护，涉及 Python 入口点、子进程、文件 I/O、CMake、MSVC 和 Windows 控制台行为。
记录适用于 PowerShell 5.1 的三层乱码修复方案，使用 UTF-8 BOM、
chcp 65001
和字节数组。
提供包含 11 项内容的 C++20 协程陷阱检查清单，涵盖 lambda 捕获、catch 处理程序中的
co_await
、互斥锁/恢复执行行为、句柄生命周期，以及 span 容器溢出问题。
强调在真实 Windows CI 上进行验证，而不是将 macOS/Linux 上的成功视为充分条件。
使用可重复的手册维护格式，将新近复现的平台故障转化为可复用的工程指南。

name: platform-pitfalls slug: platform-pitfalls
version: 1.0.0
author: dqsjqian
display_name: 平台疑难杂症速查手册
display_name_en: Platform Pitfalls Playbook
description: > Cross-platform engineering pitfalls playbook: Chinese/non-ASCII encoding
defense (Python entrypoints, child processes, file IO, CMake
execute_process ENCODING, MSVC /utf-8 vs VSLANG, Windows console code
pages, doctest/CTest discovery), PowerShell 5.1 mojibake three-layer fix
(UTF-8 BOM + chcp + byte arrays), and 11 C++20 coroutine pitfalls (lambda
captures, catch co_await, mutex resume, handle lifetimes,
container-overflow spans). Load when authoring or debugging cross-platform
build tooling, CI, installers or async C++ — especially anything that must
run on Chinese Windows (cp936/GBK) or Windows runners (cp1252). Triggers:
中文乱码, mojibake, UnicodeEncodeError charmap, doctest CTest Chinese test
names, PYTHONIOENCODING, VSLANG, code page 936, 璇峰鎻朵, coroutine UAF,
ASan container-overflow.
description_zh: >
跨平台工程疑难杂症速查：中文编码五层防线（Python 入口/子进程/文件 IO/CMake
ENCODING/MSVC）、PowerShell 5.1 中文乱码三层修复（UTF-8 BOM + chcp +
字节数组）、C++20 协程 11 个高频坑（lambda 捕获、catch co_await、mutex
resume、handle 生命周期、span container-overflow）。写跨平台构建工具、
CI、安装器或异步 C++ 时加载，尤其是要在中文 Windows（cp936/GBK）或
Windows runner（cp1252）上运行的东西。
description_en: >
Cross-platform pitfalls playbook: a five-layer Chinese/non-ASCII encoding
defense, the PowerShell 5.1 mojibake three-layer fix, and 11 C++20
coroutine pitfalls. Load when authoring cross-platform build tooling, CI,
installers or async C++.

Platform Pitfalls Playbook

疑难杂症不是玄学：每一条都是「本机全绿、目标平台爆炸」的事故换来的。 本手册把三类高频平台坑收敛成可执行的防御清单。

When to use

遇到以下任一情况，读对应章节（references/ 下）：

症状 读哪章
Windows 上中文变 璇峰•鎻•朵 / UnicodeEncodeError: 'charmap'/'gbk' codec @references/chinese-utf8-pipeline.md
跨平台脚本/构建工具要处理中文路径、中文测试名、重定向日志 @references/chinese-utf8-pipeline.md
.ps1 脚本在中文 Windows PowerShell 5.1 上乱码 @references/windows-powershell-utf8.md

Python CLI 在 Windows 控制台 print 中文/emoji 炸 @references/windows-powershell-utf8.md

C++20 协程 -O3 悬空、mutex 内 resume 崩、ASan container-overflow @references/cpp20-coroutines.md
核心原则（全章通用）
任何一层默认编码都不可信。每个边界显式声明 UTF-8。
本机 macOS/Linux 全绿不算数——默认 UTF-8 locale 掩盖一切， 中文 Windows 和 Windows runner 才是考场。
写完必须推真实 Windows CI 验收，含中文路径、中文内容、 重定向日志与失败诊断的可读性。
不静默吞错。errors='replace'、空 except、降级跳过都是把 事故变成更晚更难的排查。
沉淀新坑（本手册的维护方式）

踩到新平台坑并修复后，按「症状 → 原因 → 解法 → 验收命令」四段式追加进 对应章节；开新章节的标准：同类坑第二次出现、或独立成一个技术域。 不要记「某次会话里 AI 说了什么」，记可复现的工程事实。

章节索引
references/chinese-utf8-pipeline.md — 中文编码五层防线 （Python 入口 / 子进程 / 文件 IO / CMake / MSVC + 控制台）+ 验收 标准 + 常见误区（含 MSYS2/MinGW 关系澄清）
references/windows-powershell-utf8.md — PowerShell 5.1 三层修复 （UTF-8 BOM + chcp 65001 + 关键字符串字节数组）+ Python 控制台姊妹问题
references/cpp20-coroutines.md — C++20 协程 11 坑速查 （症状→原因→解法）+ TaskScope/事件循环/TLS 异步集成验收补充
发票数据提取
万方论文查重