Safe File Editor

模擬預覽+4眼原則+原子備份回滾 參考Claude Code SedEdit安全設計

背景問題

檔案編輯類工具的常見風險： - 誤操作覆蓋：模型匹配文本錯誤，導致檔案損壞 - 無預覽：直接寫入，無法反悔 - 無備份：修改後原檔案丟失 - 注入風險：_simulatedSedEdit欄位可被模型構造

根因：Claude Code原生的SedEdit雖有安全措施，但未完整遷移到OpenClaw

解決方案

4眼原則（Two-Person Rule）

第1眼（AI預覽）：生成diff，不實際修改
第2眼（使用者確認）：確認diff正確後執行

原子寫入流程

1. 讀取原始內容
      ↓
2. 生成diff預覽（dry_run=True）
      ↓
3. 使用者確認
      ↓
4. 建立備份（原子）
      ↓
5. 寫入臨時檔案
      ↓
6. 重新命名替換（原子操作）
      ↓
7. 成功/失敗回滾

安全設計

參考Claude Code的_simulatedSedEdit欄位omit策略：

# 該欄位在inputSchema中被omit，模型無法自行設定
_simulatedSedEdit: Optional[SedEditRequest] = Field(
    default=None,
    json_schema_extra={"omit": True}  # 關鍵：omit防止注入
)

使用方式

Python API

from safe_file_editor import safe_edit, rollback

# 第一步：預覽（dry_run=True，預設）
result = safe_edit(
    file_path="config.json",
    old_text='"timeout": 300',
    new_text='"timeout": 600',
    dry_run=True
)
print(result.changes)  # 檢視變更預覽

# 第二步：確認後執行（dry_run=False）
if result.success:
    result = safe_edit(
        file_path="config.json",
        old_text='"timeout": 300',
        new_text='"timeout": 600',
        dry_run=False
    )
    print(f"備份: {result.backup_path}")

# 第三步：如需回滾
rollback("config.json", result.backup_path)

EditResult結構

@dataclass
class EditResult:
    success: bool          # 是否成功
    file_path: str         # 目標檔案
    backup_path: str       # 備份路徑（失敗時用於回滾）
    changes: str           # 變更描述（diff）
    hash_before: str       # 修改前hash
    hash_after: str        # 修改後hash
    dry_run: bool          # 是否為預覽模式
    message: str           # 狀態訊息

Skill整合

在SKILL.md中宣告：

whenToUse: |
  任何需要修改檔案的操作
  必須使用dry_run預覽，使用者確認後再執行
permissions:
  - file:read (讀取原檔案)
  - file:write (寫入臨時+重新命名)
  - file:backup (建立.bak備份)
steps:
  1: dry_run預覽變更
  2: 展示diff給使用者確認
  3: dry_run=False執行
  4: 返回backup_path

配置引數

日誌審計

編輯日誌 (logs/safe-file-editor.log)

[2026-04-03 15:30:00] DRY_RUN: config.json | a1b2c3d4->e5f6a7b8 | - "timeout": 300
+ "timeout": 600
[2026-04-03 15:30:05] COMMITTED: config.json | a1b2c3d4->e5f6a7b8 | changes | backup: tmp/...
[2026-04-03 15:30:10] FAILED: config.json | - | Permission denied
[2026-04-03 15:35:00] ROLLBACK: config.json | - | Restored from tmp/...

最佳實踐

1. always dry_run first — 任何編輯先預覽
2. show complete diff — 展示完整變更給使用者
3. unique old_text — old_text必須足夠唯一，避免誤匹配
4. backup before commit — 自動備份，支援回滾
5. log everything — 所有操作記錄審計日誌

關聯

• 併發安全：skills/agent-concurrency-controller/

  小蔥技能7w4.net持續更新中。

• 結果控制：skills/tool-result-size-controller/
• Claude Code安全設計：memory/learnings/claude-code-architecture-2026-04-03.md

版本

• v1.0.0 (2026-04-03): 初始實現，4眼原則+原子備份回滾

這個Skill質量不錯，設計思路安全可靠。最大優點是支援編輯預覽+二次確認，不用擔心誤操作弄壞檔案；自動備份和回滾機制也很實用。文件寫得很清楚，程式碼結構簡單易讀。主要不足是缺少Agent整合介面，備份檔案久了不會自動清理，部分邊界情況處理不夠完善。總體來說是個設計良好但還需要打磨的工具，適合需要謹慎修改檔案的場景使用。