架构概览

PilotDeck 采用分层模块化架构，每个模块职责清晰、接口明确。以下从上到下介绍整体架构。

系统全景

模块清单

PilotDeck 的 src/ 目录包含以下核心模块：

模块	目录	职责
Adapters	`src/adapters/`	Channel 适配器（CLI、TUI、Feishu）和 Web 静态资源挂载
Agent	`src/agent/`	AgentSession、TurnRunner、AgentLoop —— Agent 执行引擎
Always-On	`src/always-on/`	Discovery 主动发现运行时
CLI	`src/cli/`	命令行入口（server、tui、cron 子命令）
Context	`src/context/`	Prompt 组装、消息投影、Token 预算、Compaction、Memory
Cron	`src/cron/`	定时任务运行时
Extension	`src/extension/`	生命周期 Hooks、Plugins、贡献注册
Gateway	`src/gateway/`	In-Process / WebSocket Gateway 与 SessionRouter
Lifecycle	`src/lifecycle/`	生命周期运行时和 Hook 效果处理
MCP	`src/mcp/`	Model Context Protocol 客户端集成
Model	`src/model/`	标准模型协议、Provider 适配器、流式处理
Permission	`src/permission/`	权限策略和决策运行时
Pilot	`src/pilot/`	路径管理和配置加载
Router	`src/router/`	场景路由、Fallback、TokenSaver、自定义路由器
Session	`src/session/`	Transcript 读写、会话元数据、会话列表、恢复
Task	`src/task/`	后台任务管理
Tool	`src/tool/`	工具注册、运行时、内置工具、调度器
Web	`src/web/`	Web 静态资源服务

Agent 执行层

Agent 执行层是 PilotDeck 的核心引擎，负责处理每一轮对话。

AgentSession

AgentSession 是单个会话的运行时容器，管理：

对话历史 (Transcript)
上下文状态 (Context)
工具注册 (ToolRegistry)
模型路由 (Router)

TurnRunner

TurnRunner 管理单个 Turn 的完整生命周期：

用户输入
    │
    ▼
┌─────────────────┐
│ 上下文准备       │ ← PromptAssembler + MessageProjector + MemoryResolver
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 模型路由决策     │ ← Router.decide()
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 模型请求执行     │ ← Router.execute() → ModelRuntime.stream()
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 工具调用处理     │ ← ToolRuntime.execute() (可能循环多次)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 响应输出         │ ← 流式事件 → Gateway → Channel
└─────────────────┘

AgentLoop

AgentLoop 是 TurnRunner 内部的核心循环，处理模型的多轮工具调用：

发送请求到模型
接收模型响应（可能包含工具调用）
如果有工具调用，执行工具并将结果加入上下文
重复步骤 1-3，直到模型停止调用工具

上下文管理层

Context 模块管理 Agent 每次请求的完整上下文窗口：

┌─────────────────────────────────────┐
│            Context Runtime          │
├─────────────────────────────────────┤
│  PromptAssembler                    │
│  ├── 核心系统指令                     │
│  ├── 项目指令 (InstructionDiscovery) │
│  ├── 扩展贡献 (Skills / Commands)    │
│  ├── 长期记忆 (MemoryResolver)       │
│  └── 工具定义                         │
├─────────────────────────────────────┤
│  MessageProjector                   │
│  ├── 历史消息投影                     │
│  └── 上下文窗口裁剪                   │
├─────────────────────────────────────┤
│  TokenBudgetManager                 │
│  ├── Token 计数                      │
│  ├── 预算监控                         │
│  └── 预警                            │
├─────────────────────────────────────┤
│  CompactionEngine                   │
│  ├── AutoCompactionPolicy           │
│  ├── MicroCompaction                │
│  ├── SnipEngine                     │
│  └── ContextOverflowRecovery       │
└─────────────────────────────────────┘

模型抽象层

Model 模块提供统一的模型协议抽象，支持多种 Provider：

Canonical Protocol

所有 Provider 的请求和响应都被转换为 PilotDeck 的 Canonical Protocol：

CanonicalModelRequest - 统一请求格式
CanonicalModelEvent - 统一流式事件格式
CanonicalMessage - 统一消息格式
CanonicalUsage - 统一 Token 用量格式

支持的协议

协议	Provider 示例
`anthropic`	Anthropic API、兼容的代理
`openai`	OpenAI API、Azure OpenAI、DeepSeek、兼容的代理

工具系统

Tool 模块提供丰富的内置工具和扩展能力：

内置工具

工具	说明
`bash`	执行 Shell 命令
`read_file`	读取文件内容
`write_file`	写入文件
`edit_file`	编辑文件（查找替换）
`glob`	文件模式匹配
`grep`	正则搜索
`web_fetch`	抓取网页内容
`web_search`	搜索引擎查询
`agent`	创建子 Agent
`ask_user_question`	向用户提问
`structured_output`	结构化输出
`task_create/list/output/stop`	后台任务管理

工具调度

支持两种调度策略：

ConcurrentToolScheduler：并行执行多个工具调用
SequentialToolScheduler：顺序执行

MCP 工具

通过 MCP (Model Context Protocol) 集成外部工具服务器：

# 通过 mcporter.json 配置 MCP 服务器
{
  "mcpServers": {
    "browser-agent": {
      "command": "path/to/mcp-server"
    }
  }
}

扩展系统

Extension 模块提供插件和技能扩展机制：

Plugins：全局或项目级插件，可以注入生命周期 Hook
Skills：技能定义，提供额外的上下文和提示词
Contributions：扩展贡献的命令和 MCP 服务器指令

系统全景​

模块清单​

Agent 执行层​

AgentSession​

TurnRunner​

AgentLoop​

上下文管理层​

模型抽象层​

Canonical Protocol​

支持的协议​

工具系统​

内置工具​

工具调度​

MCP 工具​

扩展系统​