python-text-replace
为什么存在
PowerShell 在传递包含 \n、"、$、θ、&、|、> 等特殊字符的字符串时，转义规则与 CMD/Python 不同，极易导致命令解析失败（例如 &/| 被当作管道、> 被当作重定向）。
改用 Python 脚本执行替换，可以完全绕开 shell 转义层，从根本上解决这个问题。
使用流程
-
提取关键信息：从用户指令中提取三个关键信息：
- 文件路径：目标文件的绝对路径
- 旧文本：要被替换的字符串（可能包含特殊字符）
- 新文本：替换后的字符串（可能包含特殊字符）
- 如果用户未明确提供，主动询问确认。 -
构造请求：用 Write 工具把替换参数写入一个 JSON 请求文件（推荐，彻底避免 shell 转义，也支持批量）；简单场景可直接用脚本的
--file/--old/--new参数形式。 -
执行脚本：通过 exec 调用本目录下的
replace.py。 -
报告结果：向用户报告：
- 替换成功/失败状态
- 替换了多少处
- 备份文件路径 -
清理（可选）：删除临时 JSON 请求文件，避免残留。
请求格式（推荐）
{
"file": "C:/project/transcribe.py",
"replacements": [
["<|AUDIO|>", "<PAD>"],
["θ", "theta"]
]
}
执行方式
# 方式一：JSON 请求文件（推荐，支持批量、无转义问题）
python <技能目录>/replace.py request.json
# 方式二：命令行参数（简单场景）
python <技能目录>/replace.py --file "C:/project/model.py" --old "θ" --new "theta"
脚本行为
- 自动创建带时间戳的备份：
<文件>.bak.YYYYMMDD_HHMMSS - 读取编码自动回退：UTF-8 → GBK → GB18030
- 写入失败时自动从备份恢复原文件（仅在失败时恢复）
- 未找到旧文本时提示"无需替换"，不创建备份
- 只使用 Python 标准库，无第三方依赖
使用示例
示例 1：普通文本替换
用户指令："将 transcribe.py 文件中的所有 <|AUDIO|> 替换为 <PAD>"
执行方式：写请求 JSON 后运行 python replace.py request.json。
示例 2：修复特殊字符
用户指令："修复代码中的 θ 字符问题"
执行方式：python replace.py --file "C:/project/model.py" --old "θ" --new "theta"。
示例 3：批量多模式替换
在请求 JSON 的 replacements 数组中放多组 [旧文本, 新文本]，依次执行。
安全规范
- 先读后写：必须先用 Read 工具读取并展示文件内容或变更计划，等待用户确认后再执行替换。
- 使用绝对路径：脚本中使用文件的绝对路径，避免因工作目录不同导致找不到文件。
- 自动创建备份：替换前必须创建带时间戳的备份文件（
.bak.YYYYMMDD_HHMMSS）。 - 错误回滚：写入失败时从备份恢复原文件。
- 编码兼容：优先 UTF-8，失败时回退 GBK → GB18030。
故障排除
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| ModuleNotFoundError | Python 环境缺少模块 | 脚本只用标准库，无需第三方依赖 |
| PermissionError | 文件被占用或权限不足 | 检查文件是否被其他程序打开 |
| 替换后代码报错 | 过度替换（替换了不该替换的部分） | 使用更精确的匹配方式，或先用备份恢复 |
| 中文乱码 | 编码不匹配 | 脚本自动尝试 UTF-8 → GBK → GB18030 回退 |
与其他工具的比较
| 工具/方法 | 优点 | 缺点 | 推荐度 |
|---|---|---|---|
| 本 Python 技能 | 绕开转义、支持特殊字符、自动备份回滚 | 需要 Python 环境 | ⭐⭐⭐⭐⭐ |
| OpenClaw 内置 edit/apply_patch | 原生可用、精确匹配 | 批量/特殊字符场景不如脚本灵活 | ⭐⭐⭐⭐ |
| sed (Git Bash) | 简洁强大 | Windows 下需额外安装 | ⭐⭐⭐ |
| PowerShell | 原生可用 | 转义规则复杂，易失败 | ⭐⭐ |
| CMD findstr/replace | 轻量 | 功能弱，不支持复杂替换 | ⭐ |
安装
技能目录：~/.openclaw-autoclaw/skills/python-text-replace/，包含 SKILL.md 与 replace.py 两个文件。
