PilotDeck 系统架构全景文档

最近 AI Agent 领域出现了一个值得关注的开源项目 ——PilotDeck。它不只是一个聊天界面或模型包装器，而是一套完整的Agent 操作系统运行时：从多通道接入、会话管理、模型路由、上下文压缩，到工具执行、插件扩展、定时任务、甚至后台自主执行（Always-On），覆盖了 Agent 工程化的几乎每一个环节。

项目技术栈选型也很有意思 —— TypeScript 全栈、Canonical 标准化消息格式贯穿全链路、Gateway 中心化的分层架构、decide/execute 分离的路由引擎设计。这些设计背后体现的工程思维，对于理解"如何构建一个生产级 Agent 系统"非常有参考价值。

本文是对 PilotDeck 从源码角度进行逐模块深度分析后，整理出的系统架构全景文档，从启动流程、分层架构、核心数据流到部署方案，共20 个维度，希望能给做 Agent 方向的同学提供一些参考。

项目定位与技术基座

PilotDeck 是一个Agent 操作系统运行时，其核心目标是提供一个统一的、可扩展的、多通道接入的 AI Agent 执行平台。系统以 TypeScript 实现，编译目标 ES2022，采用 NodeNext 模块解析，pnpm workspace 管理 monorepo 结构。

运行时架构以Gateway为中心节点，向上承接多通道用户输入，向下编排 Agent 执行流水线。整体设计遵循以下原则：

协议先行：所有模块间通过精确定义的 protocol 类型交互，核心数据结构以 Canonical（标准化）形态贯穿全链路。

依赖注入：关键模块通过工厂函数创建，外部依赖以参数注入，测试可通过替换依赖实现端到端模拟。

热重载：配置文件变更通过 PilotConfigStore 监听 → 分类 → 传播，无需重启进程即可生效。

全局架构分层

系统自上而下分为五个层次：

▲ PilotDeck 五层架构全景

启动流程与系统组装

3.1 CLI 入口

src/cli/pilotdeck.ts是系统入口，支持四个命令：

server：启动完整服务模式，初始化所有子系统

tui ：启动终端交互界面

cron：管理定时任务（list/create/delete/stop）

skills：迁移技能文件

3.2 服务模式组装

server 命令的组装过程：

1.加载配置：loadPilotConfig从~/.pilotdeck/pilotdeck.yaml读取并解析配置快照

2.初始化子系统：

buildAlwaysOn→createAlwaysOnManager：构建Always-On后台 Agent
buildCron→createCronRuntime：构建定时任务运行时

3.创建网关：createLocalGateway组装完整的运行时（详见 3.3）

4.绑定 Always-On：alwaysOn.bindGateway(gateway)

5.启动 HTTP 服务：startPilotDeckServer 绑定端口（默认 18789），挂载 WebSocket、静态资源、通道适配器

6.配置热重载订阅：监听 configStore.subscribe，当 alwaysOn.*或 cron.*变更时触发子系统重建

3.3 createLocalGateway 组装

src/cli/createLocalGateway.ts是系统最核心的组装文件（1158 行），职责是：

1.创建ProjectRuntimeRegistry：管理多项目运行时实例

2.创建SessionRouter：管理会话生命周期和空闲回收

3.创建InProcessGateway：作为 Gateway 协议的实现

4.创建SkillManager：管理技能文件 CRUD

5.创建PilotConfigStore：配置热重载

6.创建ExtensionWatchManager：监听插件文件变更

ProjectRuntimeRegistry为每个项目构建完整的运行时栈：

loadPilotConfig→ 配置快照
createModelRuntime→ 模型运行时
createRouterRuntime→ 路由运行时
PluginRuntime→ 插件运行时
createBuiltinRegistry→ 内置工具注册
BackgroundTaskRuntime→ 后台任务运行时
DefaultContextRuntime→ 上下文运行时
McpRuntime→ MCP 运行时（延迟初始化）
EdgeClawMemoryProvider→ 记忆系统（可选）

Gateway 网关层

4.1 Gateway 协议

Gateway接口定义了系统对外暴露的核心操作：

方法	用途
`submitTurn`	提交一轮对话，返回 AsyncIterable<GatewayEvent> 事件流
`abortTurn`	中止当前轮次
`listSessions`	列出会话
`newSession`	创建新会话
`closeSession`	关闭会话
`respondElicitation`	响应用户交互请求
`permissionDecide`	响应权限决策
`cronCreate/cronList/cronDelete/cronStop`	定时任务管理
`readSessionMessages`	读取会话历史
`listProjects/describeProject`	项目管理
`reloadConfig`	热重载配置

4.2 InProcessGateway

InProcessGateway是 Gateway 协议的生产实现。核心机制：

事件泵：submitTurn内部启动后台协程将 Agent 事件推入AsyncQueue，消费者通过for await迭代读取

事件重放：维护activeTurnReplays缓冲区（最多 500 条事件 / 256KB），支持 Web UI 后连接时回放

Elicitation 总线：GatewayElicitationBus实现askUserQuestion

工具的双向通信

Permission 总线：GatewayPermissionBus实现 Web UI 权限交互

4.3 SessionRouter

SessionRouter管理会话实例的生命周期：

会话缓存：Map<sessionKey, SessionRecord>维护活跃会话

空闲回收：默认 30 分钟空闲后自动驱逐（可配置）

并发控制：inFlightTurns确保每个会话同时只有一个活跃轮次

脏标记重建：markAllDirty标记所有会话需要在下次访问时重建（配置变更后触发）

项目忙碌检测：hasActiveUserTurn检测项目中是否有用户发起的活跃轮次（排除 always-on/cron）

4.4 会话键命名规则

会话键格式为{channelKey}:project={projectKey}:{sessionId}，其中 channelKey 标识来源通道（cli、tui、feishu 等），sessionId 由 UUID 生成。

Agent 执行层

5.1 三层执行架构

AgentSession（会话生命周期管理）  └── TurnRunner（轮次输入处理 + 抄本写入）       └── AgentLoop（模型调用 + 工具执行循环）

AgentSession的职责：

管理会话状态（messages、usage、permissionDenials）

分发 Lifecycle 钩子（SessionStart、Setup、SessionEnd）

管理 AbortController

提供状态快照（用于运行时重建）

TurnRunner的职责：

处理用户输入（TurnInputProcessor.accept）

写入抄本（transcript.recordAcceptedInput）

分发UserPromptSubmit钩子

调用AgentLoop.run执行核心循环

记录轮次结果

AgentLoop的职责：

执行while(true)循环，每次迭代包含：

1.自动压缩评估（tryAutoCompact）

2.构建模型请求（createModelRequest）

3.路由决策（router.decide）

4.后路由压缩（当路由模型上下文窗口更小时）

5.执行模型调用（router.execute）

6.组装助手消息

7.收集工具调用

8.执行工具（executeToolsWithEventPump）

9.投影工具结果

10.检查终止条件

5.2 错误恢复机制

AgentLoop 内建多层错误恢复：

错误类型	恢复策略
`invalid_tool_arguments`	JSON 自纠重试（最多 3 次，需`jsonSelfCorrect`开启）
`prompt_too_long`	截断头部重试（单次），保持 keepRatio 比例的消息
`max_output_reached`	翻倍`maxOutputTokens`重试（单次，上限 64000）
多媒体处理错误	剥离所有图片块重试
所有工具调用输入无效（连续 3 轮）	熔断终止

5.3 子代理系统

SubAgentSession实现代理分叉机制：

从父代理继承配置（parentConfig），递增subagentDepth

默认最大深度为 1（只允许一级分叉）

构建分叉消息（buildForkedMessages），子代理仅看到指令文本

独立运行完整的 AgentLoop，返回 Markdown 报告

支持超时控制（composeAbortSignal组合父信号和超时信号）

抄本通过subagentTranscriptResolver写入独立的{subagentId}.jsonl文件

内置子代理类型通过builtinSubagentTypes.ts定义，包括多种预配置的代理模板。

5.4 权限模式

系统支持五种权限模式：

模式	行为
`default`	默认权限策略，危险操作需确认
`plan`	计划模式，仅允许读取和代理调用
`acceptEdits`	自动接受文件编辑
`bypassPermissions`	绕过所有权限检查
`dontAsk`	不弹出交互确认

权限上下文通过PermissionContext传递，包含 allow/deny/ask 三类规则集。规则来源包括持久化配置、会话级别授权、工具动态注入。

模型路由层

6.1 ModelRuntime

ModelRuntime是模型调用的底层抽象，支持两种协议：

Anthropic：Anthropic Messages API

OpenAI：OpenAI Chat Completions API

核心方法：

stream(request)→AsyncIterable<CanonicalModelEvent>：流式调用
complete(request)→CanonicalModelResponse：同步调用
getCapabilities(provider, model)→ 模型能力查询
getMultimodal(provider, model)→ 多模态约束查询

6.2 Canonical 标准化

系统定义了一套与供应商无关的标准消息格式（Canonical），所有模块统一使用：

CanonicalMessage：消息（role + content blocks）
CanonicalToolCall：工具调用
CanonicalToolResultBlock：工具结果
CanonicalToolResultReferenceBloc：磁盘引用的工具结果（大文件优化）
CanonicalModelRequest：模型请求
CanonicalModelEvent：模型事件流（text_delta、thinking_delta、error 等）

6.3 RouterRuntime

RouterRuntime是模型调用的核心路由器，实现了decide/execute 分离：

decide 阶段：

1.CustomRouter：查询自定义路由扩展（插件提供的路由逻辑）

2.Scenario 匹配：根据会话类型匹配场景（default/explicit/subagent）

3.TokenSaver：调用 judge 模型对请求进行分级（simple/medium/complex/reasoning），选择对应层级的模型

4.Sticky 策略：同一会话内保持层级粘性，避免重复分级

5.AutoOrchestration：当分级为 complex 时，注入编排系统提示，限制工具白名单

6.Session 持久化：将路由决策写入SessionRouterStore

execute 阶段：

1.Fallback 链：按场景类型构建降级序列（planFallback）

2.Zero-Usage Retry：当模型返回零 token 使用时自动重试（最多 5 次）

3.Transient Retry：瞬时错误指数退避重试（最多 5 次，基延迟 1s，最大 30s）

4.子代理 Token 预算：当子代理消息超过subagentMaxTokens时提前终止

6.4 AutoOrchestration 编排

当 TokenSaver 将请求分级为complex（或配置的触发层级）时，RouterRuntime 自动启动编排模式：

替换系统提示为编排者角色提示

限制工具白名单为agent, read_file, grep, glob, read_skill

主代理仅负责规划和分派子任务

子代理继承完整工具权限执行具体操作

支持通过skillExtensionId加载技能模板

上下文管理

7.1 DefaultContextRuntime

DefaultContextRuntime是上下文管理的完整实现，组合以下子系统：

Prompt 组装（PromptAssembler）：

指令发现（InstructionDiscovery）：按层级发现 PILOTDECK.md 文件（全局 → 用户 → 项目 → 本地）

扩展指令（ExtensionResolver）：从插件中提取 MCP 指令

记忆附件（MemoryAttachmentBuilder）：从 EdgeClaw 记忆系统中检索相关上下文

消息投影（MessageProjector）：

将大型工具结果替换为磁盘引用

保持 tool_call/tool_result 的配对完整性

Token 预算管理（TokenBudgetManager）：

跟踪当前 token 使用量

提供预算快照（ratio、state、tokens、maxContextTokens）

7.2 压缩引擎

系统实现三级压缩策略：

层级	引擎	策略
微压缩	`MicroCompactionEngine`	截断旧工具结果的内容，保持结构
缓存微压缩	`CachedMicroCompactionEngine`	缓存压缩结果，避免重复处理
裁剪	`SnipEngine`	保留消息头部和尾部锚点，裁剪中间轮次
全量压缩	`CompactionEngine`	通过模型调用生成对话摘要

自动压缩策略（AutoCompactionPolicy）：

当 token 使用率达到 80% 时发出警告

当 token 使用率达到 95% 时触发压缩

优先使用微压缩，渐进升级到全量压缩

7.3 溢出恢复

ContextOverflowRecovery处理prompt_too_long错误：

首次截断：保持尾部 50% 消息

二次截断：保持尾部 25% 消息

每个轮次仅触发一次截断重试

工具系统

8.1 工具注册

ToolRegistry管理所有可用工具的注册和查找：

内置工具（createBuiltinRegistry）：read_file、write_file、edit_file、bash、glob、grep、agent、web_fetch、web_search、ask_user_question、mcp_tool、plan_mode、todo_write 等 22 个

MCP 工具：通过createMcpToolDefinitionsFromRuntime从 MCP 运行时动态注册

Always-On 工具：discovery_plan、discovery_report、discovery_workspace

Cron 工具：task_create、task_list、task_output、task_stop

8.2 工具执行

ToolRuntime是工具执行的统一入口，执行流程：

工具查找：从 ToolRegistry 获取工具定义
输入校验：validateToolInput验证 JSON Schema
PreToolUse 钩子：分发生命周期钩子，检查权限决策
权限检查：PermissionRuntime.decide评估权限规则
执行工具：调用工具实现函数
PostToolUse 钩子：分发后置钩子
结果限制：applyResultSizeLimit截断超大结果

8.3 工具调度

支持两种调度策略：

ConcurrentToolScheduler：并发执行所有工具调用（默认）

SequentialToolScheduler：顺序执行工具调用

8.4 文件状态追踪

PilotDeckReadFileStateMap：追踪文件读取状态，检测文件变更
PilotDeckWriteSnapshotMap：记录写入快照，用于编辑冲突检测
FileHistoryStore：管理文件编辑历史，支持按轮次回滚

会话持久化

9.1 存储结构

~/.pilotdeck/├── pilotdeck.yaml              # 全局配置├── projects/│   └── {projectId}/│       ├── .cwd                # 项目根路径标记│       └── chats/│           ├── {sessionId}.jsonl   # 会话抄本│           ├── {sessionId}.lite    # 会话摘要│           └── subagents/│               └── {subagentId}.jsonl  # 子代理抄本├── plugins/                    # 全局插件├── skills/                     # 全局技能├── memory/                     # EdgeClaw 记忆数据├── router/│   ├── events.jsonl            # 路由事件日志│   └── stats.json              # Token 统计└── permissions.json            # 权限设置

9.2 抄本写入

JsonlTranscriptWriter按行写入 JSONL 文件，每条记录包含：

accepted_input：用户输入
durable_message：持久化消息（助手消息、工具结果）
turn_result：轮次结果
subagent_started/completed：子代理生命周期
control_boundary：压缩边界标记

9.3 会话恢复

resumeAgentSession通过以下步骤恢复会话：

读取 JSONL 抄本文件
通过TranscriptReplay回放条目重建消息列表
定位最后一个压缩边界（findLastCompactBoundaryIndex）
使用压缩后的消息 + 后续条目构建初始状态
创建新的 AgentSession 并注入恢复的状态

扩展系统

10.1 插件架构

PluginRuntime管理插件的生命周期：

1.发现：扫描全局和项目级插件目录

2.加载：解析manifest.json，提取贡献点

3.注册：将贡献点注册到PluginRegistry

插件可贡献：

贡献类型	用途
`HookContribution`	生命周期钩子
`McpContribution`	MCP 服务器配置
`ToolContribution`	自定义工具
`CommandContribution`	CLI 命令扩展
`PromptContribution`	系统提示注入
`PermissionRuleContribution`	权限规则
`RouterContribution`	自定义路由逻辑

10.2 钩子系统

HookRuntime管理钩子的匹配和执行：

支持五种钩子执行器：

CommandHookExecutor：执行外部命令

PromptHookExecutor：注入提示文本

HttpHookExecutor：调用 HTTP 端点

AgentHookExecutor：调用代理执行

CallbackHookExecutor：调用回调函数

钩子通过匹配器（matchHookMatcher）匹配特定事件，支持 glob 模式和条件匹配。

10.3 生命周期事件

系统定义以下生命周期钩子事件：

SessionStart/SessionEnd：会话开始和结束
Setup：初始化设置
UserPromptSubmit：用户提交输入
PreModelRequest：模型调用前
Stop：Agent 停止时
StopFailure：Agent 失败时
PreToolUse/PostToolUse：工具执行前后
SubagentStart/SubagentStop：子代理生命周期
ConfigChange：配置变更

10.4 MCP 集成

McpRuntime管理 MCP（Model Context Protocol）服务器：

项目级共享 MCP：所有会话共享，延迟初始化（ensureMcpReady）

会话级隔离 MCP：标记perSession: true的服务器为每个会话创建独立实例

工具桥接：createMcpToolDefinitionsFromRuntime将 MCP 工具转换为ToolRegistry中的标准工具

资源暴露：list_mcp_resources和read_mcp_resource工具提供 MCP 资源访问

Unicode 清理：sanitizeUnicodeString清理 MCP 通信中的非法字符

指令注入：插件贡献的mcpServers.*.instructions注入到系统提示

10.5 技能系统

SkillManager管理存储在~/.pilotdeck/skills/中的技能文件：

支持 CRUD 操作（list/read/write/create/delete）

支持导入和验证（import/validate/scan）

技能文件为 Markdown 格式，通过read_skill工具在运行时被代理读取

Always-On 系统

11.1 架构概览

Always-On 是 PilotDeck 的后台自主执行系统，实现无人值守的代码变更和应用。

核心组件：

AlwaysOnManager：顶层管理器，绑定 Gateway，协调各子系统

DiscoveryScheduler：定时触发发现任务

SignalWatcher：监听文件系统变更信号

DiscoveryFire：执行发现-计划-执行-报告的完整工作流

ChannelLeaseRegistry：管理通道租约，避免冲突

11.2 工作流程

信号检测 → DiscoveryGates 评估 → DiscoveryFire                                        │                            ┌───────────┼───────────┐                            ▼           ▼           ▼DiscoveryWorkspaceExecution                        (发现变更)   (确定范围)   (执行变更)                            │           │           │                            └───────────┼───────────┘                                        ▼Report (生成报告)                                        │                                        ▼Apply (应用变更)

11.3 门控机制

evaluateAlwaysOnDiscoveryGates评估以下条件：

是否启用

是否有活跃的用户轮次（agent_busy门控）

距离上次执行的最小间隔

每日执行次数限制

11.4 工作空间隔离

支持两种工作空间策略：

GitWorktreeProvider：通过 Git worktree 创建隔离工作目录

SnapshotCopyProvider：通过文件快照创建工作副本

11.5 会话配置覆盖

SessionConfigOverrides允许 Always-On 会话使用与普通会话不同的配置（如不同的权限模式、工作目录等）。

Cron 定时任务系统

CronRuntime管理定时任务的生命周期：

调度器：computeNextCronRunAt支持 cron 表达式和一次性执行

存储：CronTaskStore持久化任务定义和执行历史

执行：CronFire通过 Gateway 创建会话并执行预设消息

管理工具：task_create、task_list、task_output、task_stop

通道适配器

系统通过统一的ChannelAdapter协议接入多种用户交互通道：

通道	类型	SessionMapper
CLI	命令行	固定 sessionKey
TUI	终端 UI	固定 sessionKey
Web UI	HTTP + WebSocket	动态 sessionKey
Feishu	HTTP 回调 / WebSocket	FeishuSessionMapper
Weixin	HTTP 回调	WeixinSessionMapper
Telegram	长轮询	TelegramSessionMapper
Discord	WebSocket	DiscordSessionMapper
Slack	WebSocket	SlackSessionMapper
Matrix	WebSocket	MatrixSessionMapper
Mattermost	WebSocket	MattermostSessionMapper
Signal	HTTP	SignalSessionMapper
WhatsApp	HTTP	WhatsAppSessionMapper
DingTalk	HTTP 回调	DingTalkSessionMapper
WeCom	HTTP 回调	WeComSessionMapper
Email	IMAP/SMTP	EmailSessionMapper
SMS	HTTP	SmsSessionMapper
QQ	HTTP	QQSessionMapper
HomeAssistant	WebSocket	HomeAssistantSessionMapper
ApiServer	HTTP	ApiServerSessionMapper
Webhook	HTTP	WebhookSessionMapper

每个通道包含：

Channel：管理连接生命周期和消息收发

SessionMapper：将外部用户/群组映射到 PilotDeck 会话键

Renderer：将 GatewayEvent 渲染为通道特定的展示格式

配置系统

14.1 配置层级

~/.pilotdeck/pilotdeck.yaml    # 全局配置{project}/.pilotdeck/pilotdeck.yaml  # 项目配置（覆盖全局）环境变量                        # 环境变量覆盖

14.2 配置结构

PilotConfig包含以下顶级字段：

字段	类型	用途
`agent`	`PilotAgentConfig`	Agent 配置（模型选择、上下文窗口）
`model`	`ModelConfig`	模型供应商和模型定义
`extension`	`PilotExtensionConfig`	插件和钩子配置
`memory`	`PilotMemoryConfig`	EdgeClaw 记忆系统配置
`gateway`	`PilotGatewayConfig`	网关配置（端口、超时）
`adapters`	`PilotAdaptersConfig`	通道适配器配置
`router`	`RouterConfig`	路由器配置（场景、降级、TokenSaver、编排）
`alwaysOn`	`AlwaysOnConfig`	Always-On 配置
`cron`	`CronConfig`	定时任务配置
`tools`	`PilotToolsConfig`	工具配置（web_search 等）

14.3 配置热重载

PilotConfigStore通过文件系统监听实现热重载：

1.文件变更检测：轮询或 fs.watch 检测 yaml 文件变更

2.变更分类：classifyChanges将变更分为：

runtime-live：立即生效（如 apiKey）
next-request：下一请求生效（如模型参数）
next-runtime：需重建运行时（如路由配置）
restart-required：需重启进程

3.传播：通过subscribe通知所有订阅者

4.运行时失效：registry.invalidate()+router.markAllDirty()

记忆系统

15.1 EdgeClaw 集成

系统通过EdgeClawMemoryProvider集成 EdgeClaw 记忆引擎：

捕获：captureTurn在每轮结束时将对话快照写入 EdgeClaw

检索：retrieve在prepareForModel阶段根据当前上下文检索相关记忆

维护：scheduleMemoryMaintenance在轮次完成后触发后台维护

15.2 记忆配置

PilotMemoryConfig支持：

captureStrategy：捕获策略（last_turn / full_session）
includeAssistant：是否包含助手消息
retrievalTimeoutMs：检索超时
schedule：自动索引和自动 Dream 的调度配置

前端 UI

16.1 技术栈

框架：React 19 + TypeScript

构建：Vite

样式：Tailwind CSS

包管理：pnpm workspace（ui/ 子项目）

16.2 服务端

ui/server/提供独立的 Express 服务，负责：

静态资源托管

WebSocket 代理到 Gateway

API 路由桥接

部署架构

17.1 Docker 部署

Dockerfile 采用多阶段构建：

Builder 阶段：安装依赖、编译 edgeclaw-memory-core、构建 TypeScript、构建 UI

Runtime 阶段：仅包含运行时依赖，启动 Gateway + UI 服务

docker-entrypoint.sh职责：

创建目录结构
从环境变量生成配置文件（若未挂载）
配置代理
通过concurrently启动 Gateway 和 UI 服务

17.2 运行模式

系统支持三种运行模式：

模式	入口	场景
Server	`pilotdeck server`	服务模式，支持所有通道
TUI	`pilotdeck tui`	终端交互模式
CLI	`pilotdeck <message>`	单次命令模式

核心数据流

18.1 完整请求链路

用户消息  → ChannelAdapter.start()    → Gateway.submitTurn(input)      → InProcessGateway        → refreshConfigBeforeTurn()        → SessionRouter.beginTurn()        → SessionRouter.getOrCreate()          → ProjectRuntimeRegistry.createSession()            → createAgentSessionWithStorage()              → ToolRuntime + ToolRegistry + Scheduler              → AgentLoop(config, dependencies)              → TurnRunner(loop, transcript)              → AgentSession(turnRunner)        → AgentSession.submit(input)          → TurnRunner.run()            → TurnInputProcessor.accept()            → TranscriptWriter.recordAcceptedInput()            → Lifecycle.dispatch("UserPromptSubmit")            → AgentLoop.run()              → ContextRuntime.tryAutoCompact()              → createModelRequest()                → ContextRuntime.prepareForModel()                  → InstructionDiscovery → PromptAssembler                  → MemoryResolver → MemoryAttachmentBuilder                  → MessageProjector → ToolResultBudget              → RouterRuntime.decide()                → CustomRouter → Scenario → TokenSaver → Orchestration              → RouterRuntime.execute()                → Fallback → ZeroUsageRetry → TransientRetry                → ModelRuntime.stream()                  → ProviderAdapter → HTTP → Stream normalization              → assembleAssistantMessage()              → collectToolCalls()              → executeToolsWithEventPump()                → ToolRuntime.execute() [per tool]                  → validateToolInput()                  → Lifecycle.dispatch("PreToolUse")                  → PermissionRuntime.decide()                  → Tool implementation                  → Lifecycle.dispatch("PostToolUse")              → projectToolResults()              → ContextRuntime.applyToolResults()              → check termination / continue loop          → Lifecycle.dispatch("SessionEnd")        → mapAgentEvent() → GatewayEvent        → AsyncQueue → yield to consumer  → ChannelAdapter renders event

18.2 配置变更传播链路

pilotdeck.yaml 文件变更  → fs.watch / polling    → PilotConfigStore.reload()      → parseYaml + classifyChanges()        → subscribe callback          → registry.invalidate() → 销毁旧运行时          → router.markAllDirty("config_changed")          → AlwaysOnManager/CronRuntime 重建（如涉及）          → broadcastNotification("config_changed")

模块依赖关系

pilotdeck.ts (CLI入口)  ├── adapters/ (通道适配器)  │     └── gateway (通过 Gateway 协议)  ├── cli/createLocalGateway.ts (组装核心)  │     ├── pilot/config (配置加载)  │     ├── gateway/ (网关层)  │     │     └── SessionRouter  │     ├── agent/ (Agent 执行)  │     │     ├── AgentSession  │     │     ├── TurnRunner  │     │     └── AgentLoop  │     │           ├── router/ (路由层)  │     │           │     └── RouterRuntime  │     │           │           └── model/ (模型层)  │     │           │                 └── ModelRuntime  │     │           ├── tool/ (工具层)  │     │           │     ├── ToolRuntime  │     │           │     ├── ToolRegistry  │     │           │     └── ToolScheduler  │     │           ├── context/ (上下文管理)  │     │           │     └── DefaultContextRuntime  │     │           ├── lifecycle/ (生命周期钩子)  │     │           │     └── LifecycleRuntime  │     │           │           └── HookRuntime  │     │           └── permission/ (权限系统)  │     │                 └── PermissionRuntime  │     ├── extension/ (扩展系统)  │     │     ├── PluginRuntime  │     │     └── SkillManager  │     ├── mcp/ (MCP 集成)  │     │     └── McpRuntime  │     ├── session/ (会话持久化)  │     │     └── ProjectSessionStorage  │     ├── task/ (后台任务)  │     │     └── BackgroundTaskRuntime  │     ├── always-on/ (Always-On)  │     │     └── AlwaysOnManager  │     └── cron/ (定时任务)  │           └── CronRuntime  └── cli/pilotdeckServer.ts (HTTP 服务)

设计总结

PilotDeck 的架构设计体现了以下核心理念：

Gateway 中心化：所有外部交互通过 Gateway 协议统一入口，实现了通道无关性和执行解耦。

三层执行模型：AgentSession（状态）/ TurnRunner（转录）/ AgentLoop（推理），每层职责单一，边界清晰。

decide/execute 分离：路由器将决策和执行分为两步，允许在决策后插入后处理（如针对小窗口模型的二次压缩）。

Canonical 统一格式：全链路使用标准化的消息格式，模型适配器负责协议转换，上层模块无需感知供应商差异。

渐进式压缩：微压缩 → 裁剪 → 全量摘要的三级压缩策略，兼顾性能和质量。

插件化扩展：通过 PluginRuntime 的贡献点机制，插件可以注入钩子、工具、MCP 服务器、权限规则和路由逻辑。

热重载友好：配置变更通过分类传播机制实现最小化重建，脏标记机制确保会话在下次访问时重建。

子代理隔离：通过深度限制、超时控制和独立抄本，实现安全可控的代理分叉。

Always-On 自主执行：通过门控机制和工作空间隔离，实现安全的后台自主代码变更。

多通道统一：20+ 通道适配器通过统一的 ChannelAdapter 协议和 SessionMapper 映射，实现一致的 Agent 体验。

本文基于PilotDeck 开源项目源码分析整理

希望对你构建生产级 Agent 系统有所启发