Metadata-Version: 2.4
Name: duck-guard-git
Version: 1.0.0
Summary: Local protection and recovery for AI coding sessions
Author: Psyduck2887
License-Expression: MIT
Project-URL: Homepage, https://github.com/Psyduck2887/duck-guard
Project-URL: Repository, https://github.com/Psyduck2887/duck-guard
Project-URL: Issues, https://github.com/Psyduck2887/duck-guard/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog<7,>=4.0
Dynamic: license-file

<p align="center">
  <img src="docs/assets/duck-guard-banner.png" alt="Duck Guard" width="100%">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-21a8a8" alt="Version 1.0.0">
  <img src="https://img.shields.io/badge/Python-3.11%2B-0b1426" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-0b1426" alt="macOS and Linux">
  <img src="https://img.shields.io/badge/storage-local--only-f5a623" alt="Local-only storage">
</p>

<p align="center">
  <strong>简体中文</strong> · <a href="README_EN.md">English</a>
</p>

<h1 align="center">AI 乱删库？Duck 来相助。</h1>

## 什么是 Duck Guard？

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

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

## 为什么要用 Duck Guard？

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

## 为什么不用 Git？

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

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

## 安装

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

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

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

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

## 5 分钟上手

```bash
# 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` 保存并退出，终端会用一行摘要列出本次修改。

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

## Agent Skill

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

```bash
# 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](skills/duck-guard/SKILL.md)。

## 默认策略与限额

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

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

| 配置 | 默认值 | 行为与修改方式 |
| --- | ---: | --- |
| 全局硬上限 | `2GB` | **所有项目 Session 共享**的预算；达到后暂停新增快照，不删已有历史；`config set --global-limit 4GB` |
| Session 软提醒线 | `500MB` | 超过仅提醒；`config set --session-limit 750MB` 或 `config session-limit` |
| 单文件上限 | `20MB` | 超过不进入保护；`config set --max-file 50MB` |
| active 空闲期限 | `7 天` | 到期先检查变化，有变化续期，无变化才清理；`config set --retention-days 14` |
| stop 后保留期 | `7 天` | 从停止时间起固定保留，随后自动清理；同样由 `--retention-days` 控制（作用于未来 Session） |

容量使用十进制单位（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`，适合脚本化精确配置。

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

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

## 命令速查

| 命令 | 用途 |
| --- | --- |
| `start` | 启动或复用保护 Session；首次只完成配置，需重新执行一次才开始保护 |
| `status` | 查看保护状态、容量、daemon 和待处理提醒 |
| `stop` | 保存最终快照并结束 Session，历史保留 7 天 |
| `history [path]` | 列出路径的受保护历史版本 |
| `diff <path>` | 对比当前内容与历史版本 |
| `show <path>` | 查看历史版本的内容 |
| `undo [path]` | 恢复文件；省略路径时只列候选 |
| `snapshot` | 立即保存一次显式快照（日常无需手动） |
| `skill install` / `status` / `uninstall` | 管理 Codex 与 Claude Code 的 Duck Guard Skill |
| `config` / `config show` / `config set` | 交互配置，或查看和精确修改全局默认值 |
| `config session-limit <size>` | 调整当前 Session 的软提醒线 |
| `include <path>` / `exclude <path>` | 为当前项目明确保护或排除一个精确文件路径 |
| `reminders list` / `ack` / `snooze` | 查看和处理容量提醒 |
| `delete` | 立即永久删除当前工作区的本地历史（需 `--yes` 确认） |
| `cleanup` | 立即执行生命周期维护和过期清理 |
| `daemon start` / `stop` / `status` / `reload` | 管理本地 watcher daemon |
| `verify` | 只读完整性审计（配置、metadata、全部 vault） |
| `version` | 显示版本与 schema |

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

## 恢复数据

```bash
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，同时警告当前未保存变化可能无法恢复。

## 排障

| 错误码 / 现象 | 处理方式 |
| --- | --- |
| `configuration_required` | 运行 `duck-guard config --non-interactive` 后重试 `start`，或在终端执行 `start` 完成配置后再执行一次 |
| `config_version_unsupported` | 运行 `duck-guard config --force` 重新生成配置；非交互环境增加 `--non-interactive` |
| `project_include_confirmation_required` / `project_exclude_confirmation_required` | 查看 `data.reasons` 后确认，再加 `--yes` |
| `workspace_scope_unsafe` | 进入具体项目目录后重新执行 `start` |
| `daemon_not_running` / `daemon_not_ready` | 查看 `daemon status`，必要时 `daemon start` |
| `protection_paused_global_limit` / `global_capacity_exceeded` | 清理过期 Session（`cleanup` / `delete`），或提高全局硬上限（即时生效） |
| `recovery_confirmation_required` | 确认路径和版本后加 `--yes` |
| `recovery_type_change_confirmation_required` | 确认备份提示后再决定是否 `--force-type-change` |
| `verify_failed` | 保留现场并检查 `data.findings`，不要直接删除 vault |

诊断工具：

- `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`，但不再监听、恢复或保存快照，收尾时跳过最终快照。
