jiayan-xu/agent-core

# Agent-Core ## 为什么选择 Agent-Core？ ### 企业级痛点 大多数 AI agent 框架试图包揽一切。它们内置了网页抓取、代码执行、图像生成等工具——简直是大杂烩。这在企业环境中是**危险**的。 财务人员不需要网页编码工具。HR 专家不应拥有数据库写权限。运维人员不应能够执行 shell 命令。 **全能型 agent 是安全隐患，而非生产力助推器。** ### 我们的方法 Agent-Core 采取了相反的方法——它**只提供基础的 agent 能力**： - 与 LLM 交互 - 调用 MCP 工具 - 执行安全边界 - 管理 session 和记忆 其他一切都来自于管理员分发的 **skills**。agent 初始为空白。它只会扩展用户所需的能力。 ``` Company MCP (enterprise-wide skills: auth, HR policies, org data) └─ Department MCP (domain skills: finance, HR, operations) └─ Project MCP (project-specific tools) └─ User Role (assigned skills) ``` **Agent-Core 的使命不是取代人类。它是成为一个真正的 AI 助手——在其职责范围内能力出众，且绝不越界。** ## 架构 ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Desktop App │────▶│ Agent-Core │────▶│ Memoria │ │ (any MCP │ │ (:9753) │ │ (:9003) │ │ client) │ │ │ │ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ ┌───────▼───────┐ │ MCP Sources │ │ ┌─────────┐ │ │ │ Company │ │ (enterprise-wide) │ ├─────────┤ │ │ │Dept/HR │ │ (department-level) │ ├─────────┤ │ │ │ Project │ │ (project-specific) │ └─────────┘ │ └───────────────┘ ``` **Desktop App** 是桌面壳 **Jan / PFAiX**（官方壳，基于 Tauri）——只做壳，不直接连内网 Memoria，所有请求经 agent-core 转发。任何 MCP 兼容客户端亦可接入。壳与引擎的边界与序列图见 [`docs/SHELL_ENGINE_BOUNDARY.md`](docs/SHELL_ENGINE_BOUNDARY.md)。 **Agent-Core** 负责处理推理、工具路由、安全和 skill 管理。 **Memoria** 提供持久化记忆和跨 agent 的知识共享。 **MCP Sources** 定义了每个用户/角色可以做什么——不多也不少。 ## 设计理念 ### 极简核心，极致扩展 Agent-Core 不附带任何特定领域的 skill。它是一块白板。skill 从 skill 市场安装或由管理员针对不同角色进行配置。这使得核心保持小巧、安全且可审计。 ### 默认安全 **默认本机、默认鉴权、默认拒绝。** - **仅本机监听**：默认 `127.0.0.1`，不暴露公网；公开部署请走反向代理 + TLS。 - **统一鉴权**：所有 API 需经 `auth_middleware`；桌面壳（Jan / PFAiX）通过 `x-user-tag` 自动注册身份并向 Memoria 反查命名空间授权。 - **危险工具硬闸门**：`delete_*` 等红线工具无审批人时直接硬拒绝，不进入 LLM 下一轮、不调用 MCP。 - **外发收敛**：`export_/send_/upload_/webhook_/exfil/share_` 等前缀动作走确认 / 审批。 - **Kill switch**：`POST /api/admin/killswitch` 可全局拒绝工具、仅留状态查询（受统一鉴权保护）。 - **降级收缩**：某 MCP 源连续失败 → 标记 unhealthy 剔除并审计；全部业务 MCP 不可用 → 仅 Memoria 只读 + 纯聊天；LLM 主备皆失败 → 返回可重试错误。状态见 `GET /api/admin/degrade`。 在运行时强制执行 7 条红线：权限衰减、代码隔离、治理不可变性、防范数据外发、kill switch、唯一身份和供应链审查。每次工具调用都会针对这 7 条线进行检查。 ### 三级 MCP - **Company MCP**：企业级工具（认证、组织数据、合规） - **Department MCP**：特定领域工具（财务、HR、运维、研发） - **Project MCP**：项目级工具（代码仓库、CI/CD、监控） ### 故障安全降级 当出现问题时，Agent-Core 会**收缩权限**而不是崩溃：MCP 宕机 → 仅提供基本查询工具；LLM 超时 → 切换至备用提供商；锁中毒 → 优雅恢复。 ### Skill 蒸馏 (Harness) 您使用得越多，它在您的领域中就越智能。执行日志会被蒸馏成可复用的 skill 模板。重复性任务将完全跳过 LLM——直接匹配到已知的解决方案。 ## 功能特性 - **LLM 集成** — 多提供商支持并带有自动故障转移 - **MCP 协议** — 原生支持 Company/Department/Project 级 MCP 来源的客户端 - **Skill 市场** — 按用户角色安装 skill，受白名单控制 - **7 条红线安全** — 权限链、沙箱、治理、防范数据外发、kill switch、身份、供应链 - **任务确认闸门** — 在执行危险操作前采用 SAD 式重述确认 - **Skill 蒸馏** — 从执行日志中自动学习 - **Session 管理** — 基于 LRU 的对话历史记录并带有命名空间隔离 - **审计日志** — 结构化审计追踪，并对敏感密钥进行脱敏处理 - **内嵌 Web UI** — 内置聊天界面，地址为 `http://localhost:9753` ## 快速开始 ### 构建与运行 ``` cargo build --release cp agent.toml.example agent.toml # 编辑 agent.toml；密钥请用环境变量注入（见下），不要写明文 # 默认即无窗服务（监听 127.0.0.1:9753）；勿裸启 GUI，「AI 助手」窗需显式 --gui ./target/release/agent-core # 等价：./target/release/agent-core --service # Windows: target\release\agent-core.exe # 调试桌面窗（一般不要）：target\release\agent-core.exe --gui ``` ### 密钥不落盘（P2-6） `agent.toml` 中**不要写明文密钥**。两种注入方式： 1. 配置文件用 `${ENV_VAR}` 占位符，运行时展开： api_key = "${AGENT_API_KEY}" memoria_admin_key = "${MEMORIA_ADMIN_KEY}" [[mcp_source]] name = "finance-dept" token = "${FINANCE_MCP_TOKEN}" 2. 或直接在环境变量中提供 `AGENT_API_KEY` / `MEMORIA_ADMIN_KEY`（优先级最高，覆盖配置文件）。 ### 配置 | 字段 | 默认值 | 描述 | |-------|---------|-------------| | `agent_id` | `default` | Agent 标识符 | | `api_key` | — | LLM API key | | `server` | `http://127.0.0.1:9003` | Memoria 服务器 | | `port` | `9753` | HTTP 端口 | | `memoria_admin_key` | — | Memoria 管理员密钥 | | `[[mcp_source]]` | — | MCP 源（公司/部门/项目） | ### 多级 MCP 示例 ``` # Company MCP [[mcp_source]] name = "company-hr" url = "http://company-mcp.internal/hr" token = "${COMPANY_MCP_TOKEN}" # Department MCP [[mcp_source]] name = "finance" url = "http://dept-mcp.internal/finance" token = "${DEPT_MCP_TOKEN}" # Project MCP [[mcp_source]] name = "project-data" url = "http://localhost:8000/mcp" ``` ## 项目结构 ``` src/ ├── main.rs — HTTP server, routes, config, auth middleware ├── agent.rs — Core agent loop, confirmation state machine, MCP routing ├── llm.rs — LLM client with failover (chat + streaming) ├── mcp_client.rs — MCP protocol client (HTTP + stdio) ├── boundary.rs — 7 red lines safety, namespace gating, exfiltration guard ├── checkpoint.rs — P1-1 Checkpoint 控制面（与数据面分离的续跑状态机） ├── degrade.rs — P1-5 降级收缩状态机 (Normal/PartialDegraded/MemoriaReadonlyChat/KillSwitch) ├── composer.rs — Multi-step task decomposition (HITL 预览) ├── approval.rs — Human-in-the-loop approval ├── audit.rs — Audit logging (敏感字段脱敏) ├── session.rs — Session state and LRU history ├── namespace.rs — Multi-tenant namespace isolation ├── harness.rs — Skill distillation engine └── chat.html — Embedded web chat UI ``` ## 对比 | 系统 | 对比 Agent-Core | |--------|--------------| | **全能型 Agent** | 自带所有功能，难以按角色保障安全 | | **LangChain Agent** | 锁定框架、仅支持 Python，无内置安全机制 | | **AutoGPT** | 无安全边界，无 skill 蒸馏 | | **Agent-Core** | **极简核心 + 基于角色的 skill，7 条安全防线，MCP 原生支持** | ## AI 协作说明 ## 示例与设计记录 - **示例技能（空核心 + 赋权的活示范）**：[`examples/skills/`](./examples/skills) — 含 `echo` / `calculator` 两个零机密 stdio MCP 服务，可直接接线验证链路。 - **架构决策记录（ADR）**：[`docs/decisions/`](./docs/decisions) - ADR-002 组合式 Skill 路由 - ADR-003 统一鉴权与本机默认（P0-1） - ADR-004 Checkpoint 控制面落盘（P1-1） - ADR-005 Tracing 可观测底盘（P0-3） - **优化路线图**：[`docs/OPTIMIZATION_PLAN_2026-07-11.md`](./docs/OPTIMIZATION_PLAN_2026-07-11.md) — W1(P0 安全) / W2(P1 可运营) / W3(P2 可开源示范) 全量条目与进度。 ## 许可证 MIT ## 相关项目 - [Memoria](https://github.com/jiayan-xu/memoria) — 持久化记忆与知识共享

标签：AI智能体, DLL 劫持, MCP协议, Python安全, Rust, 企业级应用, 可视化界面, 大语言模型, 权限控制, 网络流量审计, 轻量级框架