简体中文 · English

AI 乱删库？Duck 来相助。

什么是 Duck Guard？

Duck Guard 是基于本地 Git 快照的 AI Coding 工作区保护工具。
它会自动保存文件历史，让你查看、对比并恢复被 AI 误删或改坏的文件，所有数据只保存在本机。

工作流程：start → 初始快照 → watcher 持续保护 → history / diff / undo → stop → 7 天后清理

为什么要用 Duck Guard？

防止 AI Coding 时误删或改坏重要文件；启动后自动持续保护，
不需要手动 commit，也不需要手动管理版本节点。

为什么不用 Git？

Git 需要你自己 commit 和管理版本。
Duck Guard 会自动保存，并把历史放在项目目录外；即使项目和 .git 一起被删，
只要 ~/.duck-guard 还在，也能恢复。

⚠️ Duck Guard 默认不保护依赖与构建产物、二进制文件、超过 20MB 的文件，以及 .env、私钥、credentials 等常见敏感文件。

安装

需要 macOS 或 Linux、Python 3.11+ 和 Git。安装包名是 duck-guard-git，安装后的命令仍是 duck-guard：

# 方式一：uv（推荐）
uv tool install duck-guard-git

# 方式二：pipx
pipx install duck-guard-git

# 方式三：pip 用户级安装
python3 -m pip install --user duck-guard-git

5 分钟上手

# 1. 进入要保护的项目并启动
cd /path/to/project
duck-guard start

# 首次运行只完成配置；看到提示后再执行一次，才会开始保护
duck-guard start

# 2. 正常修改代码，watcher 自动保存快照；随时查看状态
duck-guard status

# 3. 需要找回文件时
duck-guard undo              # 先列出可恢复候选，不修改工作区
duck-guard undo app.py --version <commit> --yes # 恢复到指定版本

# 4. 任务结束
duck-guard stop              # 保存最终快照，历史保留 7 天后自动清理

start 必须在具体项目目录中执行：Duck Guard 会拒绝 Home、文件系统根目录等危险工作区。

全局配置可随时通过 duck-guard config 进入交互面板；config show/set 仍适合查看和脚本化修改。如果某个文件被默认规则排除但确实需要保护，可为当前项目增加精确路径例外：

交互面板使用 ↑/↓ 选择、Enter 修改；自定义配置完成后按 q 保存并退出，终端会用一行摘要列出本次修改。

duck-guard include .env --yes  # 显示敏感/大小/二进制提醒后明确保护
duck-guard exclude .env --yes  # 停止后续保护，既有历史仍保留

Agent Skill

Duck Guard 安装包已包含 skills/duck-guard。可以同时安装到 Codex 和 Claude Code，也可以只安装其中一个：

# 1. 安装 Skill（三选一）
duck-guard skill install all       # 同时安装到 Codex 和 Claude Code
duck-guard skill install codex     # 只安装到 Codex
duck-guard skill install claude    # 只安装到 Claude Code

# 2. 检查安装、冲突或断链
duck-guard skill status

# 3. 在 Agent 中明确调用 Skill
$duck-guard              # 启动或复用保护 Session
$duck-guard status       # 查看状态、容量和提醒
$duck-guard undo         # 只列出可恢复候选
$duck-guard undo app.py  # 安全恢复 app.py
$duck-guard stop         # 保存最终快照并结束 Session

# 4. 不再使用时卸载（也可将 all 换成 codex 或 claude）
duck-guard skill uninstall all

默认使用软链接：Codex 安装到 ~/.agents/skills/duck-guard，Claude Code 安装到 ~/.claude/skills/duck-guard。不支持软链接时给 install 加 --copy；已安装的 Duck Guard Skill 可在两种方式间直接切换，切换前会保留备份。已有其他同名内容时默认拒绝覆盖，只有 --force 才会先备份再替换。

Skill 不会隐式触发，只在用户明确调用 $duck-guard 时运行；正常操作不需要手工 Session ID。精确调用规则见 skills/duck-guard/SKILL.md。

默认策略与限额

所有保护数据只保存在本机，Duck Guard 不会上传文件、自动 Push 或配置 Git remote。

保护范围：代码、普通配置、文档和安全 dotfiles（如 .gitignore、.env.example）。自动排除依赖与构建产物、二进制文件、超限文件，以及 .env、私钥、credentials 等常见敏感文件。

容量使用十进制单位（1GB = 10⁹ 字节）。全局硬上限为所有项目 Session 共享的预算，多项目并发时会共同消耗，单个项目膨胀可能连带暂停其他项目的快照；接近上限（80%/90%）时 status 会提前提醒。全局硬上限修改即时生效；其余 config set 项只影响未来 Session，当前 Session 的文件策略与软提醒线在启动时已冻结。到期清理由 daemon 每 24 小时自动执行，cleanup 可立即触发；每次维护还会对每个 vault 执行 git gc，把同一文件的多个历史版本压缩成差异链，显著降低高频修改场景的磁盘占用。另可用 config set --include '*.py' --exclude 'build/**' 自定义未来 Session 的保护范围。

交互配置面板中的容量统一按 MB 输入，例如 25 或 25MB；config set 仍支持 B、KB、MB、GB，适合脚本化精确配置。

如确需保护敏感文件，必须显式选择本地明文保护，并自行确认系统备份与云盘不会同步该目录：

duck-guard config --non-interactive --protect-sensitive --force

命令速查

普通使用无需 --json；Skill 与自动化调用必须加 --json 读取稳定的 ok、code、data、warnings 字段。

恢复数据

duck-guard history app.py                       # 有哪些版本
duck-guard diff app.py --version <commit>       # 和当前差在哪
duck-guard show app.py --version <commit>       # 直接看历史内容
duck-guard undo app.py --yes                    # 恢复到上一个受保护状态
duck-guard undo app.py --version <commit> --yes # 恢复到指定版本

• undo 前后都会自动建立安全快照；恢复失败会回滚受管路径。
• 被覆盖的当前内容会备份为工作区内的 *.duckguard.bak.<时间戳> 文件，确认无误后可自行删除。
• 只有 CLI 明确提示类型切换风险且确认后，才应添加 --force-type-change。
• stop 之后的 7 天保留期内仍可继续 undo。
• 若全局容量不足导致最终快照无法保存，stop 仍会保留已有历史并结束 Session，同时警告当前未保存变化可能无法恢复。

排障

诊断工具：

• duck-guard verify：只读完整性审计，检查配置、registry、metadata、权限与全部 Git vault（git fsck --strict）；发现错误退出码为 1，不会自动修复或删除数据。
• 数据目录默认在 ~/.duck-guard/；测试或隔离运行可设置 DUCK_GUARD_HOME=/path/to/state。
• DUCK_GUARD_HEALTH_INTERVAL、DUCK_GUARD_MAINTENANCE_INTERVAL 仅用于测试与诊断（生产默认 60 秒 / 24 小时），通常不应修改。
• 旧版本遗留的危险 Session 仍可 status、stop、delete，但不再监听、恢复或保存快照，收尾时跳过最终快照。