title: [ISSUE-0005] Edit 工具改含中文标点的旧代码反复失败 description: "cat > /tmp/new.txt << 'EOF'" tags: [issue, tooling] created: 2026-05-26 updated: 2026-05-26 type: issue status: fixed severity: minor

[ISSUE-0005] Edit 工具改含中文标点的旧代码反复失败¶

相关 rule：zh-punct-edit-fallback.md

现象（AI 视角）¶

Edit 工具返回 String to replace not found in file，但 old_string 看起来明明就是文件里的内容。

根因分析¶

Edit 工具不做全角/半角等价归一化。源码里：

字符	半角（ASCII）	全角（Unicode）
括号	`()`	`（）` U+FF08/FF09
冒号	`:`	`：` U+FF1A
逗号	`,`	`，` U+FF0C
句号	`.`	`。` U+3002
分号	`;`	`；` U+FF1B

中文写作环境（包括 helperText/comment）默认是全角，AI 凭感觉手写 ASCII → string-not-found。

修复方案¶

建立 docs/rules/zh-punct-edit-fallback.md — Python 切片标准代码：

# 大块替换的标准模式
cat > /tmp/new.txt << 'EOF'
... 新内容（任意标点都可，不影响）...
EOF

python3 << 'PYEOF'
from pathlib import Path
p = Path("src/path/to/file.tsx")
src = p.read_text(encoding='utf-8')
start = src.find("起始唯一锚点")  # 用注释 marker 或函数签名
end = src.find("结束唯一锚点", start)
new_block = Path("/tmp/new.txt").read_text(encoding='utf-8')
p.write_text(src[:start] + new_block + src[end:], encoding='utf-8')
PYEOF

验证方式¶

无需验证（这是 AI 工作流的修复，不是代码 bug）。但可以观察 v0.10.13 之后没再连续踩同样的坑。

如何避免再犯¶

Edit 失败 2 次后立即换 Python 切片，不要连续猜半角/全角
改含中文 helper/label/comment 时：先 awk 'NR==<行号>' 看清字节
CLAUDE.md 高频踩坑速查表里有这条 → AI 启动时就被提醒
大块替换用 Python，比手写 old_string 性价比高得多