\r \r

text-file-writer — 跨平台文本文件写入技能\r

\r

⚠️ ABSOLUTE RULES — 每次执行前必须重读\r

\r

以下规则具有最高优先级，覆盖所有默认行为，任何理由不可豁免：\r \r 🔴 SKILL FIRST（技能优先）：当此技能可用时，任何文本文件写入都必须通过此技能的脚本执行，\r 不得绕过技能直接使用内置 write 工具写目标文件。\r 这是强制性规则，不受文件大小、内容复杂度、"快速修改"等场景影响。\r "内容简单"、"只有几行"、"纯 ASCII"、"没有中文"均不构成豁免理由。\r \r 🚫 MUST USE SCRIPT：所有文本文件的生成和写入，必须通过调用\r scripts/write_file.py 脚本执行，不得直接用 write 工具写目标文件。\r write 工具硬编码 utf-8 无 BOM，在 Windows Excel 打开 CSV 时 100% 乱码。\r \r 🚫 禁止的绕过方式（以下任何一种均构成违规）：\r

• 用 write 工具直接写最终目标文件（无论文件类型、大小、内容）\r
• 自行内联编写 Python/Node.js/Shell 代码绕过脚本写目标文件\r
• 用 write 写完目标文件后再用脚本"覆盖修正"——初次写入已违规\r
• 以任何理由声称"这种情况不需要脚本"\r \r ✅ 标准流程（四步）：\r

1. 平台探测：先执行 python3 "{SKILL_DIR}/scripts/write_file.py" --detect\r 获取当前平台，根据返回的 platform 字段决定后续参数\r
2. 写临时文件：用 write 工具把内容写入临时文件\r
   • macOS / Linux：/tmp/_tw_\x3Cname>.txt\r
   • Windows：$env:TEMP\_tw_\x3Cname>.txt（PowerShell）或 %TEMP%\_tw_\x3Cname>.txt（CMD）\r
3. 调脚本写入：按平台探测结果决定是否传 --platform\r
4. 清理临时文件\r \r ✅ --platform 决策规则（基于 --detect 返回结果）：\r

• platform == "mac" 或 "linux"，且用户没有说"给 Windows 用" → 不传 --platform\r
• platform == "mac" 或 "linux"，且用户明确说"给 Windows 用/供 Windows 打开/发给 Windows 用户" → 传 --platform windows\r
• platform == "windows" → 不传 --platform（脚本自动按 Windows 规则处理）\r \r 🚫 唯一豁免：纯二进制文件（图片、音频、视频、zip 等）不适用本技能。\r \r ---\r \r

技能概述\r

\r 替代 OpenClaw 内置 write 工具处理所有纯文本写入，提供：\r \r | 能力 | 说明 |\r |------|------|\r | BOM 自动推断 | Windows CSV/TSV/TXT 自动加 BOM；JSON/YAML/Shell 脚本等强制不加 |\r | 换行符自动适配 | Windows → \r\ ；macOS/Linux → \ ；支持 preserve 保留已有风格 |\r | GBK 支持 | Windows .bat/.cmd 含中文时使用 GBK，避免 cmd.exe 乱码 |\r | 跨平台目标指定 | --platform windows 在 macOS 上生成供 Windows 使用的文件 |\r | 追加模式 | --append 追加到已有文件末尾，不覆盖 |\r | 已有文件保留 | --preserve 自动保留已有文件的 BOM 状态和换行符风格 |\r \r ---\r \r

--platform 使用规则（重要）\r

\r --platform 表示"文件将被打开/使用的目标平台"，不是当前运行平台。\r \r | 情况 | 操作 |\r |------|------|\r | 用户在 macOS/Linux 上使用，文件也在本机使用 | 不传 --platform（脚本自动检测当前系统） |\r | 用户在 Windows 上使用，文件也在本机使用 | 不传 --platform（脚本自动检测当前系统） |\r | 用户在 macOS 上，但文件发给 Windows 用户（尤其是 CSV/Excel） | 传 --platform windows |\r | 用户在 Windows 上，但文件发给 macOS/Linux 用户 | 传 --platform mac |\r | 用户没有说明文件发给谁、在哪打开 | 不传 --platform（脚本自动检测，不要猜测） |\r \r

⚠️ 严禁在用户未明确说"给 Windows 用"时默认传 --platform windows。\r 错误地传 --platform windows 会在 mac 上生成带 CRLF 和不必要 BOM 的文件。\r \r ---\r \r

命令行接口\r

\r

python3 "{SKILL_DIR}/scripts/write_file.py" [参数]\r
\r
内容来源（必须二选一）:\r
  --content-file \x3Cfile>    从临时文件读取内容 【推荐】避免 shell 转义破坏内容\r
  --content \x3Cstring>       直接传内容字符串（适合单行、无特殊字符的简单内容）\r
\r
目标路径（必须）:\r
  --path \x3Cpath>            目标文件路径（相对或绝对，支持 ~ 展开）\r
\r
编码控制（可选，默认按文件类型 + 当前系统自动推断）:\r
  --encoding \x3Cenc>         强制指定编码: utf-8 | utf-8-sig | gbk | gb18030 | utf-16 | utf-16-le\r
  --platform \x3Cp>           目标平台: windows | mac | linux\r
                           【默认不传】脚本自动检测当前系统\r
                           【仅在跨平台场景下传】见上方"--platform 使用规则"\r
\r
换行符控制（可选，默认按 --platform/当前系统自动选择）:\r
  --newline \x3Cnl>           crlf | lf | preserve | auto（默认 auto）\r
                           preserve = 保留已有文件的换行符风格\r
\r
已有文件保留（可选）:\r
  --preserve               同时启用 --preserve-bom 和 --preserve-newline\r
  --preserve-bom           已有文件有 BOM 时保留，即使推断规则认为不需要\r
  --preserve-newline       等同于 --newline preserve\r
\r
写入模式（可选）:\r
  --append                 追加模式，内容追加到文件末尾（不覆盖）\r
\r
其他（可选）:\r
  --no-mkdir               禁止自动创建父目录（默认自动创建）\r
```\r
\r
---\r
\r
## 输出格式（JSON，stdout）\r
\r
```json\r
// 成功\r
{\r
  "status": "ok",\r
  "path": "/absolute/path/to/file.csv",\r
  "encoding": "utf-8-sig",\r
  "bom": true,\r
  "newline": "crlf",\r
  "bytes": 1024,\r
  "bytes_written": 1024,\r
  "mode": "write",\r
  "preserved_bom": false,\r
  "preserved_newline": false\r
}\r
\r
// 失败\r
{"status": "error", "message": "写入文件失败: Permission denied"}\r
\r
// 编码错误（字符无法用指定编码表示）\r
{"status": "error", "message": "编码错误: 字符 '😀' (U+1F600) 无法用 gbk 编码表示。建议使用 --encoding utf-8 或 --encoding utf-8-sig"}\r
```\r
\r
---\r
\r
## 编码推断规则（`--encoding auto` 时）\r
\r
**不传 `--platform` = 脚本自动检测当前系统**（mac 上运行 → 按 macOS 列处理）\r
\r
### 基础编码表\r
\r
| 文件后缀 | macOS / Linux（默认/不传 platform） | Windows（`--platform windows` 或当前系统是 Windows） |\r
|---------|:-----------------------------------:|:----------------------------------------------------:|\r
| `.csv` `.tsv` | utf-8（**无 BOM**） | **utf-8-sig（有 BOM ✅）** |\r
| `.reg` | **utf-16（有 BOM）** | **utf-16（有 BOM ✅）** |\r
| `.inf` | utf-8（无 BOM） | **gbk（ANSI）** |\r
| `.ps1` | utf-8-sig（有 BOM） | utf-8-sig（有 BOM） |\r
| `.bat` `.cmd` (无中文) | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.bat` `.cmd` (有中文) | utf-8（无 BOM） | **gbk（自动检测 ✅）** |\r
| `.sh` `.bash` `.zsh` `.fish` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.json` `.jsonc` `.json5` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.yaml` `.yml` `.toml` `.ini` `.conf` `.env` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.html` `.htm` `.xml` `.svg` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.md` `.markdown` `.rst` `.txt` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.js` `.ts` `.jsx` `.tsx` `.vue` `.py` 等代码 | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.css` `.less` `.scss` `.sass` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.sql` `.graphql` `.proto` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| `.log` `.lock` | utf-8（无 BOM） | utf-8（无 BOM） |\r
| 无后缀文件 (Dockerfile, Makefile 等) | utf-8（无 BOM） | utf-8（无 BOM） |\r
| 其他 | utf-8（无 BOM） | utf-8（无 BOM） |\r
\r
### 覆盖的文件类型（完整列表）\r
\r
脚本已内置支持以下所有纯文本文件类型的编码推断：\r
\r
**编程语言**：`.js` `.ts` `.jsx` `.tsx` `.mjs` `.cjs` `.vue` `.svelte` `.py` `.pyi` `.go` `.rs` `.c` `.cpp` `.cc` `.h` `.hpp` `.java` `.kt` `.scala` `.groovy` `.swift` `.m` `.mm` `.rb` `.erb` `.php` `.dart` `.lua` `.r` `.R` `.pl` `.pm` `.ex` `.exs` `.erl` `.hrl` `.hs` `.fs` `.clj` `.cljs` `.elm` `.v` `.sv` `.vhd`\r
\r
**配置文件**：`.json` `.jsonc` `.json5` `.yaml` `.yml` `.toml` `.ini` `.cfg` `.conf` `.env` `.editorconfig` `.prettierrc` `.eslintrc` `.babelrc` `.nvmrc`\r
\r
**标记语言**：`.html` `.htm` `.xhtml` `.xml` `.svg` `.md` `.markdown` `.rst`\r
\r
**脚本文件**：`.sh` `.bash` `.zsh` `.fish` `.bat` `.cmd` `.ps1`\r
\r
**数据/查询**：`.sql` `.graphql` `.gql` `.proto`\r
\r
**其他**：`.css` `.less` `.scss` `.sass` `.styl` `.log` `.lock` `.tf` `.hcl` `.nix` `.prisma` `.plist`\r
\r
**无后缀文件**：`Dockerfile` `Makefile` `Gemfile` `Rakefile` `Procfile` `Vagrantfile` `Brewfile` `Podfile` `Jenkinsfile` `CODEOWNERS` `LICENSE` `README` `CHANGELOG` 等\r
\r
### 核心原则\r
\r
- mac 上不传 `--platform`，`.csv` 生成**无 BOM** 的 utf-8（适合本机使用）\r
- 只有明确要生成"给 Windows 用户用的 CSV"时，才传 `--platform windows`\r
- `.ps1` 是唯一在 mac 上也加 BOM 的类型（因为它本身就是在 Windows 上执行的脚本）\r
- `.bat`/`.cmd` 含中文时，**Windows 平台自动切换为 GBK**，无需手动传参\r
- `.reg` 注册表文件**必须是 UTF-16 with BOM**，脚本自动处理\r
- `.inf` 安装信息文件在 Windows 上使用 GBK（ANSI 编码）\r
\r
---\r
\r
## 标准执行流程\r
\r
### 第零步：平台探测（必须）\r
\r
```bash\r
python3 "{SKILL_DIR}/scripts/write_file.py" --detect\r
```\r
\r
返回示例（macOS）：\r
```json\r
{\r
  "platform": "mac",\r
  "system": "Darwin",\r
  "python": "3.11.0",\r
  "default_csv_encoding": "utf-8",\r
  "default_csv_bom": false,\r
  "needs_platform_windows_for_local_csv": false\r
}\r
```\r
\r
返回示例（Windows）：\r
```json\r
{\r
  "platform": "windows",\r
  "system": "Windows",\r
  "python": "3.11.0",\r
  "default_csv_encoding": "utf-8-sig",\r
  "default_csv_bom": true,\r
  "needs_platform_windows_for_local_csv": true\r
}\r
```\r
\r
**根据返回值决策 `--platform` 参数：**\r
\r
| `platform` 返回值 | 用户意图 | 是否传 `--platform` |\r
|------------------|---------|-------------------|\r
| `mac` / `linux` | 本机使用（未说明） | **不传** |\r
| `mac` / `linux` | 明确说"给 Windows 用" | 传 `--platform windows` |\r
| `windows` | 任何场景 | **不传**（脚本自动按 Windows 规则） |\r
\r
### 第一步：用 `write` 工具将内容写入临时文件\r
\r
```\r
# macOS / Linux\r
write(path="/tmp/_tw_\x3C目标文件名>.txt", content="\x3C文件完整内容>")\r
\r
# Windows（PowerShell）\r
write(path="$env:TEMP\_tw_\x3C目标文件名>.txt", content="\x3C文件完整内容>")\r
```\r
\r
> 临时文件命名建议用目标文件名做后缀（如目标是 `report.csv`，临时文件用\r
> `/tmp/_tw_report.csv.txt`），避免并发时路径冲突。\r
\r
### 第二步：调用脚本写入目标文件\r
\r
```bash\r
# macOS / Linux\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "\x3C目标文件路径>" \\r
  --content-file "/tmp/_tw_\x3C目标文件名>.txt" \\r
  [--platform windows|mac|linux] \\r
  [--encoding utf-8-sig|gbk|...] \\r
  [--preserve] \\r
  [--append]\r
\r
# Windows（PowerShell）\r
python3 "{SKILL_DIR}/scripts/write_file.py" `\r
  --path "\x3C目标文件路径>" `\r
  --content-file "$env:TEMP\_tw_\x3C目标文件名>.txt" `\r
  [--platform windows|mac|linux] `\r
  [--encoding utf-8-sig|gbk|...] `\r
  [--preserve] `\r
  [--append]\r
```\r
\r
### 第三步：检查输出结果\r
\r
- `status == "ok"` → 向用户展示文件路径、编码、是否含 BOM\r
- `status == "error"` → 说明错误原因，检查路径权限或磁盘空间\r
\r
### 第四步：清理临时文件\r
\r
```bash\r
# macOS / Linux\r
rm -f /tmp/_tw_\x3C目标文件名>.txt\r
\r
# Windows（PowerShell）\r
Remove-Item -Force "$env:TEMP\_tw_\x3C目标文件名>.txt"\r
\r
# Windows（CMD）\r
del "%TEMP%\_tw_\x3C目标文件名>.txt"\r
```\r
\r
---\r
\r
## 典型场景示例\r
\r
### 场景 1：用户说"写入 csv 文件"（未说明平台）\r
\r
```bash\r
# 第零步：探测平台\r
python3 "{SKILL_DIR}/scripts/write_file.py" --detect\r
# → {"platform": "mac", ...}  当前是 mac，不传 --platform\r
\r
# 第一步：写临时文件（macOS/Linux）\r
write(path="/tmp/_tw_poems.csv.txt", content="标题,作者,内容\
静夜思,李白,床前明月光")\r
# Windows：write(path="$env:TEMP\_tw_poems.csv.txt", ...)\r
\r
# 第二步：脚本写入，mac 上不传 --platform → utf-8 无 BOM（本地使用）\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "~/Desktop/poems.csv" \\r
  --content-file "/tmp/_tw_poems.csv.txt"\r
# Windows：--content-file "$env:TEMP\_tw_poems.csv.txt"\r
\r
# 第四步：清理（macOS/Linux）\r
rm -f /tmp/_tw_poems.csv.txt\r
# Windows：Remove-Item -Force "$env:TEMP\_tw_poems.csv.txt"\r
```\r
\r
### 场景 2：用户明确说"给 Windows 用户用的 CSV"\r
\r
```bash\r
# 第零步：探测平台\r
python3 "{SKILL_DIR}/scripts/write_file.py" --detect\r
# → {"platform": "mac", ...}  用户说给 Windows 用，传 --platform windows\r
\r
# 第二步：脚本写入，指定 Windows 平台 → utf-8-sig + CRLF\r
# macOS/Linux：\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "export.csv" \\r
  --content-file "/tmp/_tw_export.csv.txt" \\r
  --platform windows\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_export.csv.txt"\r
# → 自动使用 utf-8-sig + CRLF，Excel 双击直接正确显示中文\r
```\r
\r
### 场景 3：JSON / YAML 配置文件\r
\r
```bash\r
# 无需任何额外参数，自动 utf-8 无 BOM（无论任何平台）\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "config.json" \\r
  --content-file "/tmp/_tw_config.json.txt"\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_config.json.txt"\r
```\r
\r
### 场景 4：PowerShell 脚本（含中文注释）\r
\r
```bash\r
# .ps1 自动 utf-8-sig，无需额外参数（ps1 在 Windows 执行，始终需要 BOM）\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "deploy.ps1" \\r
  --content-file "/tmp/_tw_deploy.ps1.txt"\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_deploy.ps1.txt"\r
```\r
\r
### 场景 5：Windows 批处理脚本（含中文）\r
\r
```bash\r
# Windows 平台：.bat 含中文时脚本自动检测并使用 GBK 编码\r
# 无需手动传 --encoding gbk（脚本内置非 ASCII 字符检测）\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "run.bat" \\r
  --content-file "/tmp/_tw_run.bat.txt"\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_run.bat.txt"\r
# → Windows 上自动检测到中文，使用 gbk 编码\r
\r
# macOS/Linux 上编写 .bat 文件供 Windows 使用：\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "run.bat" \\r
  --content-file "/tmp/_tw_run.bat.txt" \\r
  --platform windows\r
# Windows：--content-file "$env:TEMP\_tw_run.bat.txt"\r
# → 自动检测到中文，使用 gbk 编码\r
```\r
\r
### 场景 6：Shell 脚本\r
\r
```bash\r
# .sh 自动 utf-8 无 BOM + LF，无需额外参数\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "setup.sh" \\r
  --content-file "/tmp/_tw_setup.sh.txt"\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_setup.sh.txt"\r
```\r
\r
### 场景 7：追加内容到已有日志文件\r
\r
```bash\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "app.log" \\r
  --content-file "/tmp/_tw_new_lines.txt" \\r
  --append --preserve\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_new_lines.txt"\r
# --preserve 保留已有文件的编码和换行符风格\r
```\r
\r
### 场景 8：更新已有 CSV（保留原有 BOM 和换行符）\r
\r
```bash\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "data.csv" \\r
  --content-file "/tmp/_tw_data.csv.txt" \\r
  --preserve\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_data.csv.txt"\r
# 若原文件有 BOM，新文件保留；若原文件 CRLF，新文件保留 CRLF\r
```\r
\r
### 场景 9：Windows 注册表文件（.reg）\r
\r
```bash\r
# .reg 文件必须是 UTF-16 with BOM，脚本自动处理\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "settings.reg" \\r
  --content-file "/tmp/_tw_settings.reg.txt"\r
# Windows：将 --content-file 改为 "$env:TEMP\_tw_settings.reg.txt"\r
# → 自动使用 utf-16 编码（含 BOM），regedit 可正常导入\r
```\r
\r
### 场景 10：Windows 安装信息文件（.inf）\r
\r
```bash\r
# Windows 上 .inf 文件自动使用 GBK (ANSI) 编码\r
python3 "{SKILL_DIR}/scripts/write_file.py" \\r
  --path "driver.inf" \\r
  --content-file "$env:TEMP\_tw_driver.inf.txt" \\r
  --platform windows\r
# macOS/Linux：将 --content-file 改为 "/tmp/_tw_driver.inf.txt"\r
# → Windows 设备管理器可正常识别\r
```\r
\r
---\r
\r
## 常见陷阱\r
\r
| 陷阱 | 说明 |\r
|------|------|\r
| **绕过 skill、直接用 `write` 工具写目标文件** | **严禁。此技能可用时，write 工具只允许写临时文件，不得写最终目标文件** |\r
| **"内容简单/只有几行/纯英文"就用 write 直接写** | **严禁。简单内容同样必须走脚本，规则无大小豁免** |\r
| **"快速改一下"就绕过脚本** | **严禁。没有"快速修改豁免"，任何目标文件写入都必须走脚本** |\r
| **先用 write 写目标文件，再用脚本覆盖** | **严禁。初次 write 写目标文件已违规，必须直接从临时文件走脚本** |\r
| 用 `write` 工具直接写 CSV | `write` 工具 utf-8 无 BOM，Windows Excel 必然乱码 |\r
| **在 mac 上默认传 `--platform windows`** | **用户没说"给 Windows 用"时绝不传此参数，否则 mac 本机文件会有多余 BOM 和 CRLF** |\r
| 忘记传 `--platform windows` | 明确要生成"给 Windows 用户的 CSV"时不传，结果是无 BOM，Windows 乱码 |\r
| 对所有文件无脑加 BOM | HTML/JSON/YAML/`.sh` 加 BOM 会导致解析错误或语法报错 |\r
| 用 GBK 写含 emoji 的文件 | GBK 无法表示 emoji，脚本会报编码错误，改用 utf-8 |\r
| `.reg` 文件不用 UTF-16 | Windows 注册表文件必须是 UTF-16 LE with BOM，否则 regedit 无法导入 |\r
| 临时文件名冲突 | 并发写多个文件时，临时文件名要包含目标文件名加以区分 |\r
| Python 不可用 | 脚本依赖 `python3`（Python 3.6+），若不可用提示用户安装 |\r
\r
---\r
\r
## 注意事项\r
\r
- `{SKILL_DIR}` 在实际执行时替换为此技能的**实际安装路径**\r
- 脚本**零外部依赖**，仅使用 Python 标准库（`pathlib` `json` `argparse` `platform`）\r
- 支持 Python 3.6+，兼容 Windows / macOS / Linux\r
- 父目录不存在时默认自动创建（`--no-mkdir` 可禁止）\r
- `--content` 直接传字符串适合内容简单的场景；内容含引号、`$`、换行符等特殊字符时\r
  必须用 `--content-file` 方式，否则 shell 转义可能破坏内容\r