架构

本文页说明 xopc 的整体结构与主要模块之间的关系。

Skills、Extensions 与社区贡献——秒级安装，通常无需重启。Skills 用 SKILL.md 教知识；Extensions 以 npm 包扩展全功能；UI Extensions 在 Web 控制台嵌入自定义面板。

系统架构

┌─────────────────────────────────────────────────────────────┐
│                      xopc                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    CLI Layer                         │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │   │
│  │  │ setup   │ │ onboard │ │ agent   │ │ gateway │   │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                     Core                             │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │              AgentService                    │   │   │
│  │  │  ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │   │
│  │  │  │ Prompt  │ │ Memory  │ │ Skills  │       │   │   │
│  │  │  │ Builder │ │ Search  │ │         │       │   │   │
│  │  │  └─────────┘ └─────────┘ └─────────┘       │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   Providers                          │   │
│  │            @earendil-works/pi-ai (20+ providers)      │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
└────────────────────────────┼────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
  ┌──────────────┐     ┌──────────┐        ┌──────────┐
  │ 内置聊天机器人 │     │   Cron   │        │ Gateway  │
  │（多频道接入） │     │ Scheduler│        │   API    │
  └──────────────┘     └──────────┘        └──────────┘

主要组件

模块	作用
CLI	`agent`、`tui`、`gateway`、`config`、`onboard`、扩展管理等命令行入口。
Agent	运行模型、工具、记忆、技能与单次对话的会话逻辑。
Gateway	HTTP 服务与静态 Web 控制台（聊天、设置、日志、频道、cron 等）。
Channels	内置机器人（Telegram、微信、飞书/Lark）与网关网页对话共用一套出站管道。
Extensions	可选增强（工具、钩子、频道、控制台面板），来自工作区、`~/.xopc/extensions/` 或与安装包捆绑。
Config	单一 JSON（默认 `~/.xopc/xopc.json`）与环境变量中的密钥。

磁盘上的状态目录与工作空间

运行时数据（配置、凭据、按智能体划分的会话、作为工具 cwd 与用户内容的 Markdown 工作空间，以及 agents/<id>/profile/ 下的 profile Markdown）位于仓库之外的 状态目录（默认 ~/.xopc）。路径总览（profile Markdown、智能体主目录、Markdown 工作区）见磁盘与目录布局。初始化、环境变量与默认路径说明见状态目录与工作空间布局。

智能体与 Prompt

AgentService 负责：

接收来自通道或 Web 控制台的用户消息。
从各智能体 agents/<id>/profile/ 下的 profile Markdown（SOUL.md、USER.md、AGENTS.md、TOOLS.md 等）与可选记忆片段组装系统 Prompt。
持久化会话 transcript，并在配置开启时做压缩。
执行 内置与扩展工具，对耗时步骤给出进度反馈。

Prompt 区块（概念上）包括身份、工具风格、安全、工作区路径、技能、消息、心跳与运行时提示等，详见工作空间与模板。

内置工具（概览）

工具	用途
`read_file` / `write_file` / `edit_file`	工作区文件读写
`list_dir`、`grep`、`find`	浏览与搜索工作区
`shell`	执行 Shell（有时长限制）
`web_search`、`web_fetch`	联网搜索与抓取（需配置）
`send_message`	在当前通道发送出站消息
`memory_search`、`memory_get`	搜索/读取工作区内 `memory/*.md`
`curated_memory`	在启用时编辑智能体主目录 `memories/` 中的受控条目
`session_search`	在会话存储可用时检索其它会话

具体是否注册取决于配置参考与扩展。

进度反馈

长时间运行的工具会产生简短状态（读取、搜索、Shell 等），便于界面在最终回复前展示进度。

记忆与会话

会话 — 按智能体存放的对话历史（与 Markdown「工作空间」项目目录不是同一套路径）。
托管记忆 — 可选的 memories/ 与相关工具，由 agents.defaults.memory 控制。
压缩 — 上下文窗口管理，由 agents.defaults.compaction / pruning 等配置。

通道与扩展

Telegram、微信、网页聊天及扩展提供的通道，共用进入智能体的消息总线。在配置文件的 channels.* 下填写各通道选项，见通道配置。扩展可增加工具、钩子、可选通道插件与可选 Web 控制台界面，见扩展系统。

数据流

对话流程

用户 (Telegram/Gateway/CLI)
        │
        ▼
┌─────────────────────┐
│   通道处理器        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   AgentService      │
│  ┌───────────────┐  │
│  │ 加载 profile  │  │ ← `agents/<id>/profile/`（SOUL.md, USER.md, TOOLS.md, AGENTS.md）
│  └───────┬───────┘  │
│          ▼          │
│  ┌───────────────┐  │
│  │ 构建 Prompt   │  │ ← profile Markdown、托管快照、memory_search / memory_get 等
│  └───────┬───────┘  │
│          ▼          │
│  ┌───────────────┐  │
│  │ LLM (pi-ai)   │  │
│  └───────┬───────┘  │
│          ▼          │
│  ┌───────────────┐  │
│  │ 执行工具      │  │ ← 工具 + 扩展
│  │ + 进度反馈    │  │ ← 进度反馈
│  └───────┬───────┘  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   响应              │
└──────────┬──────────┘
           │
           ▼
用户回复 / 通道响应

技术栈

层级	技术
运行时	Node.js 22+
语言	TypeScript 5.x
LLM SDK	@earendil-works/pi-ai
智能体框架（pi-agent-core）	@earendil-works/pi-agent-core
CLI	Commander.js
验证	Zod (配置) + TypeBox (工具)
日志	Pino
Cron	node-cron
HTTP 服务器	Hono
Web UI	React + Vite + Tailwind v4（网关控制台）
测试	Vitest

修改 xopc 本体

若要为核心增加工具、通道或 CLI 命令，请在 xopc 源码仓库中开发，并遵循仓库内的贡献说明 AGENTS.md。在不 fork 的前提下定制行为，推荐使用扩展系统。

架构 ​

系统架构 ​

主要组件 ​

磁盘上的状态目录与工作空间 ​

智能体与 Prompt ​

内置工具（概览） ​

进度反馈 ​

记忆与会话 ​

通道与扩展 ​

数据流 ​

对话流程 ​

技术栈 ​

修改 xopc 本体 ​

架构