核心用法
Soul Guardian 是一款面向 AI Agent 工作区的文件完整性监控工具，通过为关键配置文件（SOUL.md、AGENTS.md 等）建立 SHA256 基线哈希，实现漂移检测与自动修复。
主要功能：
- 基线管理：
init命令创建受保护文件的初始哈希快照 - 持续监控：
watch模式定时扫描，check命令用于心跳集成 - 自动恢复：对 SOUL.md/AGENTS.md 等核心文件，检测到漂移后自动还原至基线
- 审计追踪：tamper-evident 审计日志，采用哈希链设计防止事后篡改
- 用户告警：
--output-format alert生成结构化告警文本，便于 TUI/聊天界面直接展示
工作流程：
1. 初始化基线 → 2. 启用监控 → 3. 集成至 HEARTBEAT.md → 自动检测与响应
显著优点
- 零网络依赖：纯本地操作，无外部连接风险
- 原子化恢复：文件还原使用原子写入，避免中间状态损坏
- 安全加固：拒绝处理符号链接，防止目录遍历攻击
- 可验证发布：提供完整的发布签名验证流程（manifest + checksums + OpenSSL 签名）
- 灵活策略：支持 restore/alert/ignore 三级响应模式，可按文件配置
- 开放可审计：Python3 脚本实现，逻辑透明可审查
潜在局限
- 身份归因有限：
--actor参数依赖调用方自声明，无法密码学证明操作者身份 - 状态目录风险：若攻击者同时控制工作区与状态目录，可伪造基线与审计日志
- 非备份方案：仅维护最新基线，不保留历史版本，无法恢复至任意时间点
- 依赖文件系统：需 Python3 运行时，对极简容器环境可能过重
- 手动审批流程：有意变更需显式执行
approve，高频迭代场景可能增加摩擦
适合人群
- 运行长期存活 AI Agent 的开发者，担心提示词/配置被会话污染
- 多用户/多进程共享工作区的团队环境
- 对 Agent 行为一致性有合规要求的场景
- 希望为关键文件建立"最后一次已知良好状态"防护的用户
常规风险
| 风险场景 | 缓解措施 |
|---------|---------|
| 状态目录被篡改 | 建议将状态目录置于工作区外独立路径 |
| 误报恢复合法变更 | 变更后需显式 `approve`，建议配合版本控制使用 |
| 审计日志无限增长 | 当前文档未提及轮转策略，需手动管理 |
| 签名验证被跳过 | 用户可能忽略发布验证流程，需强化安全意识 |
综合评估
Soul Guardian 填补了 Agent 工作区在"配置漂移防护"领域的工具空白，其设计理念借鉴了传统主机的 HIDS（主机入侵检测系统）与配置管理策略。对于将提示词视为"代码"、将 SOUL.md 视为"系统配置"的严肃 Agent 部署场景，该工具提供了必要的完整性基线。然而，其安全模型的上限受限于调用环境的可信度——它假定 Python 解释器、状态目录及调度机制本身未被攻陷。建议与高权限隔离（如只读根文件系统、独立用户命名空间）结合使用，以逼近 S 级安全水准。