安全文件编辑器

安全文件编辑器，支持4眼原则预览确认，原子备份与回滚，避免误操作覆盖及注入风险，保障文件编辑安全可靠。

Security Scan

The skill's code and instructions match its stated purpose (safe file edits with dry-run, atomic backup, and rollback); no network or unrelated credentials are requested, though there are a few small implementation/documentation inconsistencies and privacy considerations to review before use.

Purpose & Capability

The name/description (safe file editing, dry-run, backups, rollback, two-person confirmation) align with the included code and SKILL.md. The skill only requires file read/write operations and logging which are appropriate for this purpose. Minor inconsistency: SKILL.md documents a BACKUP_DIR default of `tmp/file-backups/` but the code uses a fixed default under Path.home()/.openclaw/.../tmp/file-backups.

Instruction Scope

SKILL.md instructs the agent to only preview (dry_run) and require user confirmation before commit, which the code enforces via the dry_run flag. The code only reads/writes local files and logs; it does not access network or other unrelated system secrets. Notes: the produced 'diff' is a simple replace-summary (not a true line-by-line diff) which may underrepresent changes; logs record change snippets and filenames which could expose sensitive content if logs are not protected.

Install Mechanism

There is no install spec or external download; this is instruction-only with an included Python file. No external packages or network downloads are performed by the code.

Credentials

No environment variables or external credentials are requested. The skill writes backups and audit logs under the user's home directory (~/.openclaw/...), which is proportionate to its function but means backups and logs may contain sensitive data — users should ensure those files are stored and permissioned appropriately.

Persistence & Privilege

The skill is not always-enabled and does not request persistent platform-wide privileges. It creates and writes files in the user's home directory (backups and logs) which is expected behavior for this tool.

Assessment

This skill appears to implement what it claims: preview-only edits, atomic backup, commit, and rollback, with no network calls or credentials required. Before installing or using it: 1) Review or change the backup/log directory to a location you control (the code uses ~/.openclaw/... by default; SKILL.md documents a different default), and ensure those files have restricted permissions because logs and backups can contain sensitive content. 2) Test on non-production files to confirm behavior (the diff is a simple replacement summary, not a full diff). 3) Be aware the tool can modify any file the running agent/user has permission to write — grant access only where appropriate. 4) Consider fixing small robustness issues (e.g., potential undefined backup_path on certain exceptions) before trusting it in critical environments.

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

配置参数

参数	默认值	说明
BACKUP_DIR	tmp/file-backups/	备份文件目录
MAX_BACKUP_AGE	30天	备份保留期限
原子写入	temp.replace(target)	防止写入中断

日志审计

编辑日志 (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/
• 结果控制：skills/tool-result-size-controller/
• Claude Code安全设计：memory/learnings/claude-code-architecture-2026-04-03.md

版本

• v1.0.0 (2026-04-03): 初始实现，4眼原则+原子备份回滚