Agent 核心文件完整性守护专家

专业级 Agent 工作空间完整性守护工具，支持自动漂移检测、基线恢复与实时告警，零依赖纯 Python 实现。

基本信息

• 技能名称?soul-guardian
• 中文名称?Agent 核心文件完整性守护专家
• 作者?davida-ps
• 分类?专业技能
• 版本?0.0.5
• 标签?file-integrity, drift-detection, baseline-protection, audit-logging, zero-dependency, agent-security, local-only, heartbeat-monitoring

使用方法

使用说明
核心用法
Soul Guardian 是一款专为 AI Agent 工作空间设计的文件完整性保护工具，通过三重机制保障核心配置文件安全：

1. 基线管理
   运行 init 命令为 SOUL.md、AGENTS.md 等关键文件建立 SHA-256 哈希基线，所有后续变更均以此为准进行比对。
2. 漂移检测与响应
   check 模式：单次扫描，静默无输出表示安全，发现漂移则生成结构化告警
   watch 模式：持续监控（默认30秒间隔），适合长期运行的 Agent 环境
   双级策略：SOUL.md/AGENTS.md 自动恢复至基线；其余文件仅告警不恢复

3. 审计与合规

   采用哈希链式审计日志，支持 verify-audit 验证日志完整性，所有操作记录 actor、时间戳与变更备注，满足可追溯要求。

   显著优点
   | 维度 | 表现 | |------|------| | 安全架构 | 原子写入防数据损坏、拒绝符号链接防劫持、防篡改审计日志 | | 零依赖 | 纯 Python 标准库，无供应链攻击面，部署极简 | | Agent 原生 | 专为 AGENT.md/SOUL.md 等 AI 工作区设计，语义贴合 | | 告警友好 | --output-format alert 输出可直接嵌入 TUI/聊天界面 | | 心跳集成 | 推荐写入 HEARTBEAT.md，实现自动化安全监控 | ---
   潜在局限
   身份归因弱 ：actor 字段为手动标注，无法技术层面证明变更主体
   状态目录风险 ：若攻击者同时控制工作区与状态目录，基线可被同步篡改
   非备份替代 ：仅恢复至最近一次批准的基线，不支持历史版本回滚

   macOS 依赖 ：自动调度需 launchctl ，跨平台脚本需自行适配

   适合人群
   运行长期自主 Agent 的开发者（AutoGPT、OpenClaw 等框架用户）
   对提示词注入、配置漂移有安全顾虑的 AI 应用团队

   需要合规审计追踪的企业级 Agent 部署场景

   常规风险
   | 风险场景 | 缓释建议 | |----------|----------| | 误自动恢复覆盖合法变更 | 开发阶段改用 alert 模式，生产环境配合代码评审流程 | | 状态目录与workspace同盘 | 使用 --state-dir 指定外部路径，物理隔离 | | 心跳监控遗漏告警 | 确保 HEARTBEAT.md 解析逻辑正确识别非空输出 | | 长期运行日志膨胀 | 定期归档或配置日志轮转策略 |