用 Claude Code 做“可检查”的维护脚本：从 dry-run 开始的安全自动化教程

帮我写一个脚本清理旧文件和检查服务。

请帮我写一个 Python 维护检查脚本，要求：

目标：检查 home lab 目录状态，只读输出报告，默认不做任何修改。

边界：
- 只允许读取我传入的 --root 目录；
- 不允许删除、移动、重启服务或修改配置；
- 如果未来需要归档旧目录，也必须先实现 --dry-run，只打印计划动作；
- 排除目录 old-but-important；
- 所有函数必须有类型注解；
- 不使用 shell=True；
- 不引入第三方依赖。

检查项：
1. backups 目录是否存在；
2. logs/*.log 是否超过 1MB；
3. projects 下超过 30 天未修改的目录是否需要归档；
4. 输出清晰日志；
5. 有明确退出码：0=正常，1=参数或路径错误，2=发现告警。

请先输出代码，然后解释每个安全边界。

#!/usr/bin/env python3
from __future__ import annotations

import argparse
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class CheckResult:
    name: str
    status: str
    detail: str


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Safe home-lab maintenance checker")
    parser.add_argument("--root", required=True, help="Allowed root directory")
    parser.add_argument("--dry-run", action="store_true", help="Show planned actions only")
    parser.add_argument("--max-log-mb", type=int, default=1, help="Warn when log files exceed this size")
    parser.add_argument("--stale-days", type=int, default=30, help="Warn when project folders are older than this")
    return parser.parse_args()


def resolve_root(raw_root: str) -> Path:
    root = Path(raw_root).expanduser().resolve()
    if not root.exists() or not root.is_dir():
        raise ValueError(f"root is not a directory: {root}")
    return root


def ensure_inside_root(root: Path, candidate: Path) -> Path:
    resolved = candidate.resolve()
    if root not in [resolved, *resolved.parents]:
        raise ValueError(f"path escapes allowed root: {resolved}")
    return resolved


def check_backup_dir(root: Path) -> CheckResult:
    backup_dir = ensure_inside_root(root, root / "backups")
    if backup_dir.exists():
        return CheckResult("backup_dir", "OK", f"found {backup_dir}")
    return CheckResult("backup_dir", "WARN", f"missing {backup_dir}")


def check_large_logs(root: Path, max_log_mb: int) -> list[CheckResult]:
    log_dir = ensure_inside_root(root, root / "logs")
    if not log_dir.exists():
        return [CheckResult("large_logs", "WARN", f"missing {log_dir}")]
    limit_bytes = max_log_mb * 1024 * 1024
    results: list[CheckResult] = []
    for path in sorted(log_dir.glob("*.log")):
        size = path.stat().st_size
        if size > limit_bytes:
            results.append(CheckResult("large_logs", "WARN", f"{path.name} is {size} bytes"))
    if not results:
        results.append(CheckResult("large_logs", "OK", "no oversized log files"))
    return results


def check_stale_projects(root: Path, stale_days: int) -> list[CheckResult]:
    projects_dir = ensure_inside_root(root, root / "projects")
    if not projects_dir.exists():
        return [CheckResult("stale_projects", "WARN", f"missing {projects_dir}")]

    now = Path.cwd().stat().st_mtime
    threshold_seconds = stale_days * 24 * 60 * 60
    results: list[CheckResult] = []

    for path in sorted(projects_dir.iterdir()):
        if not path.is_dir():
            continue
        if path.name in {"old-but-important"}:
            results.append(CheckResult("stale_projects", "SKIP", f"excluded {path.name}"))
            continue
        age_seconds = now - path.stat().st_mtime
        if age_seconds > threshold_seconds:
            planned = f"would archive {path} to {root / 'archive' / path.name}"
            results.append(CheckResult("stale_projects", "DRY-RUN", planned))

    if not results:
        results.append(CheckResult("stale_projects", "OK", "no stale project folders"))
    return results


def print_results(results: list[CheckResult]) -> None:
    for item in results:
        print(f"[{item.status}] {item.name}: {item.detail}")


def main() -> int:
    args = parse_args()
    try:
        root = resolve_root(args.root)
        results = [check_backup_dir(root)]
        results.extend(check_large_logs(root, args.max_log_mb))
        results.extend(check_stale_projects(root, args.stale_days))
        print_results(results)
        if any(item.status == "WARN" for item in results):
            return 2
        return 0
    except ValueError as exc:
        print(f"[ERROR] validation: {exc}")
        return 1


if __name__ == "__main__":
    raise SystemExit(main())

mkdir -p /tmp/maint-ai-demo/sample_home_lab/{backups,projects/old-but-important,projects/tmp-old,logs,compose}
printf 'important\n' > /tmp/maint-ai-demo/sample_home_lab/projects/old-but-important/README.txt
printf 'scratch\n' > /tmp/maint-ai-demo/sample_home_lab/projects/tmp-old/notes.txt
printf 'version: "3"\nservices:\n  demo:\n    image: nginx:alpine\n' > /tmp/maint-ai-demo/sample_home_lab/compose/docker-compose.yml
truncate -s 2M /tmp/maint-ai-demo/sample_home_lab/logs/app.log
touch -d '45 days ago' /tmp/maint-ai-demo/sample_home_lab/projects/tmp-old /tmp/maint-ai-demo/sample_home_lab/projects/tmp-old/notes.txt

python3 maintenance_check.py \
  --root /tmp/maint-ai-demo/sample_home_lab \
  --dry-run \
  --max-log-mb 1 \
  --stale-days 30

[OK] backup_dir: found /tmp/maint-ai-demo/sample_home_lab/backups
[WARN] large_logs: app.log is 2097152 bytes
[SKIP] stale_projects: excluded old-but-important
[DRY-RUN] stale_projects: would archive /tmp/maint-ai-demo/sample_home_lab/projects/tmp-old to /tmp/maint-ai-demo/sample_home_lab/archive/tmp-old
exit=2

python3 maintenance_check.py --root /tmp/maint-ai-demo/missing --dry-run

[ERROR] validation: root is not a directory: /tmp/maint-ai-demo/missing
exit=1

请审查这个维护脚本，只关注安全边界，不新增功能。

检查项：
1. 是否有路径逃逸风险；
2. 是否存在 shell=True 或隐式 shell 执行；
3. 是否有真实删除、移动、重启服务、写配置动作；
4. dry-run 是否只是展示计划，不产生副作用；
5. 是否能通过退出码区分正常、告警和参数错误；
6. 哪些地方必须人工确认后才能进入执行模式。

请按 blocking / important / optional 分类输出。