架构总览

Peri 采用分层架构：前端层（TUI/ACP）→ Agent 核心（ReAct 循环）→ 中间件层（功能实现）→ 外部系统。

分层结构

┌─────────────────────────────────────┐
│  peri-tui / peri-acp（前端层）       │  TUI 全屏界面 / ACP stdin/stdout
├─────────────────────────────────────┤
│  peri-agent（Agent 框架核心）        │  ReAct 循环、中间件链、LLM 接口
├─────────────────────────────────────┤
`peri-middlewares`（功能实现）         │  18 个内置中间件
├─────────────────────────────────────┤
│  外部系统                            │  文件系统、终端、Web、MCP、LSP
└─────────────────────────────────────┘

前端层通过 mpsc channel（TUI）或 stdio（ACP）与 Agent 核心通信，共享同一 Agent 后端。

Crate 职责

Crate	职责
peri-agent	ReAct 循环、中间件链、LLM 接口、Thread 持久化、消息系统、Compact 压缩
peri-middlewares	18 个内置中间件：文件系统、终端、Web、子 Agent、Tool Search、HITL、Hooks、MCP、Plugins、Cron、Skills、LSP、Compact、@提及、Git 归属
peri-tui	Ratatui 终端 UI、CLI 入口（clap）、事件处理、Markdown 渲染
peri-acp	ACP 服务层：SessionManager、Transport 抽象、系统提示词构建、Langfuse 追踪
peri-widgets	TUI 可复用组件库
peri-lsp	LSP 客户端集成
langfuse-client	Langfuse LLM 可观测性客户端

数据流

用户输入
  ↓
TUI（Ratatui） / ACP（stdio JSON-RPC）
  ↓ mpsc / StdioTransport
AcpServer → SessionManager
  ↓
ReActAgent（peri-agent）
  ↓
MiddlewareChain
  ├── before_agent   → 注入 CLAUDE.md、Skills
  ├── before_model   → Compact 检查
  ├── LLM 调用       → OpenAI / Anthropic API
  ├── after_model    → Token 统计
  ├── before_tool    → HITL 权限检查
  ├── 工具执行       → 文件读写、命令执行
  └── after_tool     → 日志记录
  ↓
AgentOutput → 用户

ReAct Agent 执行流程

1. 添加 human 消息到 state
2. 从所有中间件收集工具（collect_tools）
3. chain.run_before_agent(state)
4. prepend system_prompt
5. for step in 0..max_iterations:
   a. chain.run_before_model(state)    ← Compact 检查点
   b. call_llm(messages, tools) → Reasoning
   c. chain.run_after_model(state)
   d. if needs_tool_call:
      - chain.run_before_tool()        ← 权限检查
      - 工具执行
      - chain.run_after_tool()
   e. else:
      - 返回 AgentOutput
6. chain.run_after_agent(state)

关键设计决策

决策	理由
Rust 实现	内存安全 + 高性能，~50MB 内存占用，单一二进制分发
中间件驱动	所有功能通过 Middleware trait 注入，可插拔、可测试
上下文优化	系统提示词缓存边界 + Tool Search 延迟加载 + Compact 自动压缩
.claude/ 兼容	直接复用 Claude Code 的目录结构，零迁移成本
多前端	TUI（mpsc）和 IDE（stdio/ACP）共享同一 Agent 后端
ThreadStore 抽象	可插拔存储后端（SQLite/Redis/文件系统），支持会话恢复

延伸阅读

• 中间件协议参考 — Middleware trait 的完整 API
• ThreadStore API 参考 — 线程存储的完整接口