什么是soul-guardian
soul-guardian 是一款专为智能体工作区设计的文件守护工具，核心功能是保护关键配置文件免受未经授权的修改。它通过建立文件基线、持续监控文件系统变化，并在检测到异常时自动恢复原始内容并发出安全告警。该工具特别适合需要维护系统一致性和安全性的开发环境，能够有效防止因误操作或恶意篡改导致的核心配置丢失。
工具默认保护 SOUL.md、AGENTS.md 等核心身份文件，支持自动回滚和人工审核双重机制。当检测到文件漂移时，soul-guardian 会立即触发告警流程，生成详细的差异报告，并将受影响的文件还原至已批准的版本。整个过程无需人工干预，确保关键配置始终处于受控状态。
其设计遵循最小权限原则，仅对指定文件生效，同时提供完整的审计日志记录，便于追溯变更历史。虽然无法完全确定变更来源（actor 信息为可选元数据），但结合外部监控系统可构建完整的安全防护链。建议将状态目录置于工作区之外以提升抗攻击能力。
核心功能特点
- 自动检测并恢复被篡改的核心配置文件（如 SOUL.md、AGENTS.md）
- 支持静默检查与实时告警双模式运行
- 生成带哈希校验的审计报告及变更差异补丁
- 内置防篡改机制，拒绝处理符号链接
- 提供交互式批准流程以应对合法更新需求
适用场景
适用于需要长期稳定运行的自动化智能体系统，尤其是那些依赖严格配置文件管理的场景。例如在多智能体协作框架中，每个代理的身份定义和行为规范必须保持一致，soul-guardian 可确保这些关键文档不被意外覆盖或恶意修改。对于采用心跳检测机制的运维系统而言，将其集成到 HEARTBEAT.md 可实现无人值守的安全巡检。
在持续集成/部署环境中，开发人员可能频繁更新代理能力描述文件，此时可通过 approve 命令手动授权合规变更，其余变动则会被拦截并通知管理员。这种灵活策略既保证了安全性又不失实用性。此外，watch 模式适合本地开发调试阶段，每30秒自动扫描一次，及时发现潜在风险点。
特别推荐用于开源项目贡献者管理——当社区成员提交 PR 修改代理说明文档时，主仓库可通过 soul-guardian 验证其是否符合既定模板格式，避免风格混乱影响用户体验。总之，任何涉及敏感配置文件的自动化流程都值得引入此类守护机制来增强鲁棒性。