7 篇文章带有标签 “architecture”

open-ai-eco 接入本地 Agent：ACP 协议开发实践与架构总结

本文记录 AI 生态工作台（open-ai-eco）通过 ACP（Agent Client Protocol） 接入本地 Agent 的完整实践：选型理由、架构设计、关键实现、踩坑经验与验证方法。

1. 背景与目标

工作台是组内的 Astro 站点，用于展示 AI 研究成果。日常工作中沉淀了一批 Agent 技能（Skill）：

  • 研究 AI 项目：给一个 GitHub 地址，自动研究并把结构化信息写入项目 Excel；
  • AI 周报：每周一生成结构化行业周报 Markdown；
  • 后续还会有更多同类技能。

这些技能原本只能在终端里通过 Claude Code / Kimi CLI 使用。目标是：在工作台网页里加一个交互入口，直接在页面上对话、调用技能、审批文件操作，把"打开终端敲命令"变成"打开网页点一下"。

约束条件：主要自用、部署在内网 Node 常驻服务上、本地同时装有 Claude Code 与 Kimi CLI 两个 Agent。

2. 为什么选 ACP

open-ai-ecoagentacpintegrationarchitectureskills

Agent 系统设计的核心思想

一套面向 Agent 应用设计者的系统化设计原则、架构模式与实战指南。

基于对 WorkBuddy（CodeBuddy Code）工作空间源码、系统提示词、文档与架构的深度分析提炼而成。

目录

  1. 概述：从 Chatbot 到 Agent 的范式跃迁
  2. 原则一：闭环执行架构
  3. 原则二：人格化身份体系
  4. 原则三：分层记忆系统
  5. 原则四：纵深防御安全模型
  6. 原则五：渐进式能力扩展
  7. 原则六：多模态工作模式
  8. 原则七：上下文精细管理
  9. 原则八：可组合的工具哲学
  10. 系统架构全景图
  11. 可复用的设计模式清单
  12. 设计决策框架
  13. 常见反模式

1. 概述：从 Chatbot 到 Agent 的范式跃迁

1.1 Chatbot 和 Agent 的本质区别

维度 Chatbot Agent
核心能力 理解并回答 理解、计划、执行、验证
与环境的交互 被动接收文本 主动感知文件系统、网络、工具
输出的性质 文本回答 实际行动（文件变更、API 调用、部署）
正确性保障 依赖训练数据 通过执行测试、编译、对比等方式自我验证
会话生命周期 一问一答，无持续性 跨多轮持久化，可中断恢复
用户角色 提问者 协作者/监督者

设计 Agent 系统，首先要完成这个认知跃迁：Agent 不是"更强的 Chatbot"，而是一种全新的交互范式。

1.2 Agent 设计的核心张力

在设计 Agent 系统时，始终面临以下四对核心张力：

workbuddyagentdesignarchitectureprinciples

WorkBuddy 核心设计架构

基于 /Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked 逆向分析 WorkBuddy Desktop v5.2.5 + CodeBuddy CLI v2.106.4 | 腾讯出品

一、整体架构概览

graph TB
    subgraph "操作系统层"
        OS["macOS / Windows<br/>Darwin / Win32"]
        FSE["FSEvents API<br/>(macOS 文件监听)"]
        PTY["Pseudoterminal API<br/>(openpty / ConPTY)"]
        SQLITE["SQLite Engine<br/>(C++ 绑定)"]
    end

    subgraph "Electron 应用外壳 (WorkBuddy Desktop v5.2.5)"
        ELECTRON["Electron Main Process<br/>Node.js + Chromium"]
        RENDER["Renderer Process<br/>React/Vue UI + WebView"]
        DEVTOOLS["DevTools Panel<br/>Ghostty WASM Terminal"]
        PRELOAD["Preload Scripts<br/>IPC 安全桥接"]
    end

    subgraph "CLI 核心宿主 (CodeBuddy CLI v2.106.4)"
        CLI["cli/bin/codebuddy<br/>Node.js 启动器"]
        TUI["TUI Mode<br/>Ink + React 19<br/>~16MB Bundle"]
        DAEMON["Daemon Mode<br/>HTTP Server<br/>Port 51862+"]
        HEADLESS["Headless Mode<br/>-p / --print<br/>CI/CD 管道"]
        WEBUI["Web UI<br/>Workers / Logs / Metrics"]
    end

    subgraph "原生模块层 (app.asar.unpacked)"
        NATIVE_MOD["node_modules/"]
        BETTER_SQL["better-sqlite3<br/>v12.8.0 (MIT)"]
        NODE_PTY["node-pty<br/>v1.1.0 (Microsoft)"]
        LYDELL_PTY["@lydell/node-pty-darwin-arm64<br/>v1.2.0-beta.12"]
        DOCS_ENGINE["@tencent/docs-engine<br/>v0.0.1-beta.9"]
        FSE_MOD["fsevents<br/>(nunjucks 嵌套依赖)"]
    end

    subgraph "资源与扩展层 (resources/)"
        RES["resources/"]
        BUILT_PLUGINS["builtin-plugins/"]
        BUILT_SKILLS["builtin-skills/<br/>15 个内置技能"]
        BUILT_MCP["builtin-mcp-apps/"]
        TEMPLATES["templates/<br/>Nunjucks 提示词模板"]
        DEVTERM["devtools-terminal/<br/>Chrome Extension v3"]
        BRANDING["channel-branding/<br/>OEM 品牌资源"]
    end

    subgraph "AI 推理后端"
        BACKEND["copilot.tencent.com<br/>AI 推理集群"]
        MCP_PROXY["MCP Connector Proxy<br/>Port 61047"]
    end

    subgraph "用户数据层 (~/.workbuddy/)"
        USER_DATA["~/.workbuddy/"]
        DB["workbuddy.db<br/>(SQLite + WAL)"]
        SOUL["SOUL.md<br/>AI 灵魂"]
        IDENTITY["IDENTITY.md<br/>智能体身份"]
        MEMORY["memory/<br/>项目级记忆"]
        SESSIONS["sessions/<br/>会话 JSON"]
        TRACES["traces/<br/>运行追踪"]
    end

    OS --> ELECTRON
    ELECTRON --> RENDER
    ELECTRON --> PRELOAD
    RENDER --> DEVTOOLS

    ELECTRON -->|spawn| CLI
    CLI --> TUI
    CLI --> DAEMON
    CLI --> HEADLESS
    DAEMON --> WEBUI

    NATIVE_MOD --> BETTER_SQL
    NATIVE_MOD --> NODE_PTY
    NATIVE_MOD --> LYDELL_PTY
    NATIVE_MOD --> DOCS_ENGINE
    NATIVE_MOD --> FSE_MOD

    CLI --> NATIVE_MOD
    CLI --> RES

    RES --> BUILT_PLUGINS
    RES --> BUILT_SKILLS
    RES --> BUILT_MCP
    RES --> TEMPLATES
    RES --> DEVTERM
    RES --> BRANDING

    TUI -->|HTTP/WebSocket| BACKEND
    DAEMON -->|HTTP API| BACKEND
    HEADLESS -->|HTTP API| BACKEND
    BACKEND -->|MCP STDIO/SSE/HTTP| MCP_PROXY

    CLI -->|读写| USER_DATA
    DAEMON -->|读写| DB
    TUI -->|读取| SOUL
    TUI -->|读取| IDENTITY
    TUI -->|读取| MEMORY
    TUI -->|写入| SESSIONS
    TUI -->|写入| TRACES

    FSE -->|API 调用| FSE_MOD
    PTY -->|API 调用| NODE_PTY
    PTY -->|API 调用| LYDELL_PTY
    SQLITE -->|C++ 绑定| BETTER_SQL

    DOCS_ENGINE -->|"FFI 加载：libeditor_sdk_ffi.dylib (172 MB)"| EXT1
    DOCS_ENGINE -->|"HTTP Server：127.0.0.1:39099 本地文档预览"| EXT2
    DEVTERM -->|"WASM 执行：ghostty-vt.wasm 终端仿真"| EXT3
    EXT1 & EXT2 & EXT3:::dummy
    classDef dummy fill:none,stroke:none

    style ELECTRON fill:#e1f5fe
    style CLI fill:#fff3e0
    style BACKEND fill:#e8f5e9
    style USER_DATA fill:#fce4ec
    style NATIVE_MOD fill:#f3e5f5
    style RES fill:#e0f2f1

二、Electron 主进程与 CLI 双层架构

flowchart LR
    subgraph "Electron 主进程"
        direction TB
        EP1["app-instance.ts<br/>多实例检测"]
        EP2["auth.ts<br/>腾讯云 OAuth"]
        EP3["daemon-app-server-*.ts<br/>守护进程服务"]
        EP4["desktop-monitor-service.ts<br/>桌面监控"]
        EP5["helpers.ts<br/>工具函数集"]
        EP6["file-authentication-storage.ts<br/>文件认证存储"]
    end

    subgraph "CLI 进程 (Node.js 子进程)"
        direction TB
        C1["bin/codebuddy<br/>入口启动器"]
        C2["V8 Compile Cache<br/>~37% 启动加速"]
        C3["Node >= 18.20.8<br/>版本检查"]
        C4["Headless 路由<br/>--print / daemon / -p"]
        C5["TUI Bundle<br/>codebuddy.js<br/>Ink + React 19<br/>~16MB"]
        C6["Headless Bundle<br/>codebuddy-headless.js"]
    end

    subgraph "通信层"
        COM1["stdio<br/>标准输入输出"]
        COM2["HTTP<br/>Web UI / API"]
        COM3["WebSocket<br/>实时消息"]
        COM4["IPC<br/>Electron 内部"]
    end

    EP1 -->|"spawn('node', ['bin/codebuddy'])"| C1
    EP3 -->|HTTP 端口| COM2

    C1 --> C2
    C1 --> C3
    C1 --> C4
    C4 -->|TUI 模式| C5
    C4 -->|无头模式| C6

    C5 -->|stdio| COM1
    C5 -->|WebSocket| COM3
    C6 -->|HTTP| COM2
    EP1 -->|IPC| COM4
    RENDER["Renderer Process<br/>(UI 渲染)"] -->|IPC| COM4

    style EP1 fill:#e3f2fd
    style EP2 fill:#e3f2fd
    style EP3 fill:#e3f2fd
    style C1 fill:#fff8e1
    style C5 fill:#fff8e1
    style C6 fill:#fff8e1

关键设计决策：

  • Desktop 与 CLI 版本分离：WorkBuddy Desktop v5.2.5 是 Electron 外壳，CodeBuddy CLI v2.106.4 是独立 Node.js 进程，两者版本独立演进
  • 双 Bundle 策略：TUI 模式用 ink + React 19 提供交互终端，Headless 模式剔除 UI 依赖，显著减小启动开销
  • V8 Compile Cache：通过 enableCompileCache() 将 ~16MB bundle 的加载时间从 ~400ms 降到 ~254ms
  • --version 快速路径：直接返回版本号，跳过 DI 容器初始化和网络请求

三、原生模块与资源分层

graph LR
    subgraph "app.asar.unpacked 目录"
        direction TB
        subgraph "cli/ 目录"
            CLI_DIR["cli/"]
            CLI_BIN["bin/codebuddy<br/>入口脚本"]
            CLI_DIST["dist/<br/>codebuddy.js / codebuddy-headless.js"]
            CLI_WASM["dist/wasm/<br/>tree-sitter.wasm<br/>tree-sitter-bash.wasm"]
            CLI_WEBUI["dist/web-ui/<br/>docs/ (200+ 篇)"]
            CLI_VENDOR["vendor/<br/>sandbox / ripgrep / genie-trash"]
            CLI_PKG["package.json<br/>@genie/agent-cli"]
        end
        
        subgraph "node_modules/ 目录"
            NODE_DIR["node_modules/"]
            BETTER["better-sqlite3<br/>v12.8.0<br/>SQLite 数据库绑定"]
            NODE_PTY["node-pty<br/>v1.1.0<br/>Microsoft 伪终端"]
            LYDELL["@lydell/<br/>node-pty-darwin-arm64<br/>v1.2.0-beta.12"]
            TENCENT["@tencent/<br/>docs-engine<br/>v0.0.1-beta.9"]
            NJ["nunjucks<br/>+ fsevents<br/>模板引擎"]
        end
        
        subgraph "resources/ 目录"
            RES_DIR["resources/"]
            PLUGINS["builtin-plugins/<br/>weixinpay (MCP)"]
            SKILLS["builtin-skills/<br/>15 个技能"]
            MCP_APPS["builtin-mcp-apps/<br/>Ardot / Agently"]
            TEMPLATES["templates/<br/>8 模板 + 7 风格"]
            DEVT["devtools-terminal/<br/>Ghostty WASM"]
            BRAND["channel-branding/<br/>OEM 品牌"]
            PRELOADS["*-preload.js<br/>IPC 预加载脚本"]
        end
    end

    CLI_DIR --> CLI_BIN
    CLI_DIR --> CLI_DIST
    CLI_DIR --> CLI_WASM
    CLI_DIR --> CLI_WEBUI
    CLI_DIR --> CLI_VENDOR
    CLI_DIR --> CLI_PKG

    NODE_DIR --> BETTER
    NODE_DIR --> NODE_PTY
    NODE_DIR --> LYDELL
    NODE_DIR --> TENCENT
    NODE_DIR --> NJ

    RES_DIR --> PLUGINS
    RES_DIR --> SKILLS
    RES_DIR --> MCP_APPS
    RES_DIR --> TEMPLATES
    RES_DIR --> DEVT
    RES_DIR --> BRAND
    RES_DIR --> PRELOADS

    style BETTER fill:#ffebee
    style NODE_PTY fill:#ffebee
    style LYDELL fill:#ffebee
    style TENCENT fill:#ffebee
    style PLUGINS fill:#e8f5e9
    style SKILLS fill:#e8f5e9
    style MCP_APPS fill:#e8f5e9

为什么需要 app.asar.unpacked？

workbuddyagentarchitecturedesignsecurity

elizaOS 多智能体架构设计分析

📋 概述

elizaOS 是一个开源的多智能体 AI 开发框架，用于构建、部署和管理自主 AI 智能体。采用现代化、可扩展的全功能平台设计。

核心特性

  • 🔌 丰富的连接器：内置 Discord、Telegram、Farcaster 等支持
  • 🧠 模型无关：支持 OpenAI、Gemini、Anthropic、Llama、Grok 等主流模型
  • 🖥️ 现代 Web UI：专业仪表板，实时管理智能体、群组和对话
  • 🤖 多智能体架构：从底层设计支持创建和编排专业智能体组
  • 📄 文档摄取：轻松摄取文档，支持 RAG 检索和问答
  • 🛠️ 高度可扩展：强大的插件系统构建自定义功能
  • 📦 开箱即用：无缝的设置和开发体验

🏗️ 系统架构概览

项目结构

elizaosmulti-agentagent-frameworkarchitectureplugin-systemragtypescriptsandbox

OpenClaw 架构设计

目录

  • 概览
  • 核心组件
  • 控制平面
  • 网关协议
  • 消息路由
  • 消息流程
  • 启动流程

概览

OpenClaw 是一个多渠道 AI 助手网关，设计用于在用户自己的设备上运行。它采用单一网关 + 多客户端/节点模型，支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage 等多种通信渠道。

核心结构

组件 描述
🌐 Gateway（网关） 长期运行的守护进程，管理所有消息平台连接和智能体通信
💻 Clients（客户端） 控制平面应用（macOS 应用、CLI、Web 界面）
📱 Nodes（节点） 设备节点，提供硬件能力（macOS/iOS/Android/无头设备）

整体架构

graph TB
    subgraph UserLayer["用户设备层"]
        MacApp["macOS 应用"]
        IOSApp["iOS 应用"]
        AndroidApp["Android 应用"]
        CLI["命令行界面"]
        WebUI["Web 界面"]
    end

    subgraph GatewayLayer["网关核心层"]
        Gateway["Gateway 网关服务"]
        WS["WebSocket 服务器"]
        HTTP["HTTP 服务器"]
        NodeReg["节点注册表"]
        ChannelMgr["渠道管理器"]
    end

    subgraph ChannelLayer["消息渠道层"]
        Telegram["Telegram"]
        Slack["Slack"]
        Discord["Discord"]
        WhatsApp["WhatsApp"]
        Signal["Signal"]
        GoogleChat["Google Chat"]
        OtherChannels["其他渠道..."]
    end

    subgraph AgentLayer["智能体层"]
        AgentSystem["智能体系统"]
        Skills["技能系统"]
        Memory["记忆系统"]
        Providers["AI 提供商"]
    end

    MacApp --> WS
    IOSApp --> WS
    AndroidApp --> WS
    CLI --> WS
    WebUI --> HTTP

    WS --> Gateway
    HTTP --> Gateway
    Gateway --> NodeReg
    Gateway --> ChannelMgr

    ChannelMgr --> Telegram
    ChannelMgr --> Slack
    ChannelMgr --> Discord
    ChannelMgr --> WhatsApp
    ChannelMgr --> Signal
    ChannelMgr --> GoogleChat
    ChannelMgr --> OtherChannels

    Gateway --> AgentSystem
    AgentSystem --> Skills
    AgentSystem --> Memory
    AgentSystem --> Providers

    style Gateway fill:#7c3aed,stroke:#5b21b6,color:#fff
    style WS fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style ChannelMgr fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style AgentSystem fill:#10b981,stroke:#059669,color:#fff

架构原则

  • 每台主机一个网关实例: 单一职责，避免会话冲突
  • 所有通信通过 WebSocket: 使用类型化 API，支持双向通信
  • 网关唯一管理平台连接: 避免重复登录，统一状态管理
  • 支持多种客户端节点: 通过相同的 WebSocket 协议通信

核心组件

🎛️ Gateway Server（网关服务器）

网关的核心实现，负责协调所有子系统。 位置: src/gateway/server.impl.ts

  • 主要职责:
  • HTTP 和 WebSocket 服务
  • 节点管理和配对
  • 渠道生命周期管理
  • 智能体会话协调
  • 关键子系统:
  • 节点注册表
  • 渠道管理器
  • 会话管理器
  • 健康监控器
openclawai-agentarchitecturegatewaywebsocketchannel-adaptermessage-routingjson-rpccontrol-planepi-agent

Model Context Protocol (MCP) 的核心概念和能力

Introduction简介

Model Context Protocol (MCP) 入门

MCP 是一个开放协议，用于标准化应用程序向 LLM 提供上下文的方式。可以将 MCP 视为 AI 应用程序的 USB-C 端口。正如 USB-C 提供了一种将设备连接到各种外围设备和配件的标准化方式一样，MCP 提供了一种将 AI 模型连接到不同数据源和工具的标准化方式。

为什么选择 MCP？

MCP 帮助您在 LLM 之上构建代理和复杂的工作流程。LLM 经常需要与数据和工具集成，而 MCP 提供了：

  • 越来越多的预构建集成，您的 LLM 可以直接插入
  • 在 LLM 提供商和供应商之间切换的灵活性
  • 在您的基础设施中保护数据的最佳实践

一般架构

MCP 的核心遵循客户端-服务器架构，其中主机应用程序可以连接到多个服务器：

flowchart LR
    subgraph "您的计算机"
        Host["带有 MCP 客户端的主机<br>(Claude、IDE、工具)"]
        S1["MCP 服务器 A"]
        S2["MCP 服务器 B"]
        S3["MCP 服务器 C"]
        Host <-->|"MCP 协议"| S1
        Host <-->|"MCP 协议"| S2
        Host <-->|"MCP 协议"| S3
        S1 <--> D1[("本地<br>数据源 A")]
        S2 <--> D2[("本地<br>数据源 B")]
    end
    subgraph "互联网"
        S3 <-->|"Web APIs"| D3[("远程<br>服务 C")]
    end
  • MCP 主机：希望通过 MCP 访问数据的程序，如 Claude Desktop、IDE 或 AI 工具
  • MCP 客户端：维护与服务器 1:1 连接的协议客户端
  • MCP 服务器：轻量级程序，每个程序通过标准化的模型上下文协议公开特定的功能
  • 本地数据源：您的计算机的文件、数据库和服务，MCP 服务器可以安全地访问
  • 远程服务：通过互联网（例如，通过 API）可用的外部系统，MCP 服务器可以连接到

Core architecture（核心架构）

了解 MCP 如何连接客户端、服务器和 LLM

mcpllmresourceprompttooltransportsamplingrootjson-rpcarchitecture

模型上下文协议 (MCP) 全面解析：原理、应用与实现

这篇文章是使用 Google Gemini Deep Research 生成的。提示词：研究 Model Context Protocol

1. 模型上下文协议 (MCP) 导论

大型语言模型 (LLMs) 在理解和生成人类语言方面取得了显著的进步。然而，这些模型本质上是孤立的，它们的知识仅限于训练数据，并且缺乏与外部世界交互的能力 1。为了克服这些限制，将 LLMs 与外部数据源和工具集成变得至关重要 1。传统上，这种集成是通过为每个新的数据源或工具开发定制的连接器来实现的 1。这种方法导致了集成工作的重复，难以扩展，并且维护成本高昂，阻碍了上下文感知 AI 的广泛采用 1。

为了应对这一挑战，模型上下文协议 (MCP) 应运而生 1。MCP 是一种开放标准，旨在规范应用程序如何向 LLMs 提供上下文和工具 6。可以将 MCP 视为 AI 应用程序的通用连接器，类似于 USB-C 标准化了设备和外设之间的连接 6。通过提供一种标准化的方式将 AI 模型连接到各种数据源和工具，MCP 简化了集成，增强了互操作性，并促进了可扩展性 6。

本报告旨在对模型上下文协议 (MCP) 进行全面的解析，涵盖其基本原理、核心架构、通信机制、广泛的应用场景以及客户端和服务器端的创建方法。通过深入理解 MCP，开发者和组织可以更好地利用这一新兴标准，构建更智能、更具上下文感知能力的 AI 应用。

mcpmodel-context-protocolarchitecturejson-rpcsdksecurityinteroperabilityllmgeminideepresearch