local-agent-core｜本地AI Agent安全控制与审批沙箱模块

这个项目解决什么问题

本地 AI 助手一旦能读写文件、调用命令行工具、占用显卡跑模型，就会出现三类现实麻烦：模型调用了不该调用的工具、改了没被批准的文件、把 GPU 或端口占住导致正在跑的出图/剪辑任务失败。本仓库把这些“闸门”单独抽成小模块，供自建 Agent 的人参考或移植，而不是一套装好即用的成品软件。

需要先说明：仓库自述包含两部分——src/local_agent_core/ 是重写后的独立安全模块（环境变量配置、合成测试数据），agent/ 是作者本人机器上运行的完整 Agent（Windows 优先，含其本机默认路径）。本文介绍以 README 描述为准，本站未部署、未运行测试。

适用行业与人群

• 在自己电脑上搭本地 AI 助手、需要给 Agent 加边界的个人开发者
• 想把“人工审批 + 白名单”模式引入内部自动化流程的小团队技术负责人
• 学习 Agent 安全控制写法的教学与安全研究场景（仅作参考实现，作者明确说明未经外部安全评审）

流程步骤（按 README 自述的模块职责整理）

1. 工具准入：tool_guard 用固定工具名与参数白名单，再加路径检查把文件访问限制在单一工作区内；README 强调仅有 JSON schema 不构成授权。
2. 工具执行：tool_loop 执行结构化工具调用，旧式文本回退同样经过白名单。
3. GPU 使用前：preflight 只做回环检查，确认 GPU 后端未被占用；gpu_gate 在加载模型前要求一次人工批准，默认模式为“询问”，一次批准只对应一个工作负载键、只够一次加载。
4. 文件修改：file_edit_gate 把批准绑定到 sha256(路径 + 精确新内容)，批准一次用一次，不能挪用到别的改动或别的文件。
5. 代码执行：sandbox_runner / sandbox_guard 在子解释器中运行 Python 片段，禁用网络、新进程、原生库加载，文件访问限于本次运行目录，基于 Python 审计钩子。
6. 下载处置：quarantine 按 sha256 存放并挂起文件，需具名人员批准后才可拷出，释放时重新校验哈希，每次状态变化追加日志。
7. 审计留痕：audit_log 为追加式 JSONL，参数只记名称、哈希与大小，路径、邮箱、疑似凭据会被脱敏。
8. 推送前自检：audit 模块扫描密钥与绝对路径。

所需工具与投入条件

• 运行环境：Python 3.11 或更高，src 部分只用标准库，无需额外依赖。
• 平台：agent/ 部分 Windows 优先；作者说明在 Linux 下约 70 项测试需要 Windows、其 GPU 或仅存在于其本机的文件（待核查具体清单）。
• 验证方式：README 给出设置 PYTHONPATH=src 后运行 python -m unittest discover -s tests -t . 与 python -m local_agent_core.audit --dir . 的自检命令；本站未执行，效果待核验。
• 第三方组件：MCP 客户端对接开源 comfyui-mcp 服务（npx 启动），仓库只包含客户端，服务端属第三方；本仓库的 MCP 测试用本地替身服务，不需要 Node.js 或 ComfyUI。
• 许可：MIT License，Copyright (c) 2026 local-agent-core contributors。再分发需保留版权与许可声明；商用与合规适用性请自行复核（待核查）。
• 费用：仓库未提及收费项；是否有隐性成本（如第三方服务）待核查。国内网络下的克隆与依赖获取情况待核查。

可核验成果与已知边界

作者给出、但本站未复现的自述结论：

• src 部分 89 项单元测试在任意操作系统通过；agent/ 在 Linux 下约 2000 项通过、约 70 项因环境依赖失败。
• “已测试”仅指其机器上单元测试通过，不含外部安全评审。

作者主动声明的限制，选型时必须读：

• 沙箱是进程内的，靠 Python 审计钩子拦截常规开文件、起进程、开套接字；一旦脚本让原生代码跑起来可能被绕过。私有环境中的 Windows 低完整性作业对象层未包含在本仓库。
• 审计日志的“追加”靠写入方式而非操作系统强制，有文件写权限者仍可修改。
• 各闸门状态存在本地 JSON 文件，能防 Agent 未经批准行动，不防同一用户下的其他程序改这些文件。
• 无静态加密、无备份恢复测试、除仅绑定回环外无传输安全。
• 电话桥与无线电 mesh 传输不在本仓库；作者称其为实验性或进行中。

落地建议

把它当作“控制层参考实现”而非开箱方案：先在隔离环境跑通 src 的测试，再按自己的工具清单改写白名单与审批键，最后接入自建 Agent 的主循环。上线前建议自行补一次安全评审与备份恢复演练。

来源与加工说明

来源：https://github.com/rhinerad/local-agent-core

许可证：MIT

依据 GitHub 原始资料由 AI 整理的中文待审核草稿，未经本站实测。原始版权与许可归原作者；未声明许可不代表允许转载或再分发。

来源类型：GitHub；授权范围待核验