PilotDeck 采用分层架构，将交互入口、任务执行与基础能力解耦。桌面端、Web、CLI / TUI 和消息渠道共享同一套 Agent 运行时；会话、文件与项目记忆围绕 WorkSpace 组织，使任务能够在不同入口之间延续。

1. 系统全景

一次请求从交互入口进入 Gateway，由会话路由定位对应的 WorkSpace 和会话，再交给 Agent 执行。Agent 在运行过程中协调上下文、模型和工具，并将响应、状态与产物持续返回给界面。

2. 分层设计

3. 任务执行机制

Agent 将自然语言请求转化为持续的“理解—行动—反馈”循环。模型决定下一步行动，工具完成具体操作，执行结果再回到模型上下文中；当任务完成或执行被终止时，本轮请求结束。

3.1 会话与任务

会话保存持续工作的状态，包括历史消息、模型偏好、执行状态与用量。一次用户输入形成一个 Turn，负责组织本轮模型调用和工具执行。会话可以包含多个 Turn，因此用户能够基于前一轮结果继续追问、补充条件或调整目标。

3.2 单轮执行流程

文本、工具调用和状态以流式事件持续输出。持久化记录随执行过程写入，使界面既能显示实时进展，也能在之后读取本轮结果。

3.3 模型与工具协作

模型负责规划与判断，工具负责与实际环境交互。工具调用经参数校验和权限检查后执行，结果被加入后续模型请求。需要多步操作时，Agent 会继续迭代；取消、不可恢复的错误或循环限制则会结束执行。可恢复的请求错误按照运行策略重试。

4. 上下文管理

上下文是模型理解任务的依据。PilotDeck 将核心指令、项目指令、技能、历史消息、工具结果与相关长期记忆组织为本次请求的输入，并依据模型的上下文窗口分配预算。

随着对话增长，系统会处理较大的工具结果，并在必要时压缩历史上下文。大结果可保存到文件后保留读取引用；历史压缩生成摘要，同时保留继续执行所需的信息和工具调用关系。切换模型时，预算会按目标模型重新检查。

会话压缩用于延续当前任务，长期记忆用于跨会话复用知识。两者分别维护：压缩摘要不会直接等同于一条长期记忆，长期记忆通过 Recall、Index 和 Dream 独立形成与更新。

5. 多模型接入

PilotDeck 通过模型适配层统一不同服务的请求与响应。Agent 使用一致的消息和事件格式执行任务，适配层负责转换为目标服务的接口协议。模型选择、路由与回退因此可以在同一执行流程中完成。

5.1 统一消息与事件

统一协议描述文本、多模态内容、工具调用、流式响应和用量信息。上层会话无需为每个模型维护一套独立的执行流程，交互入口也可以用一致的方式呈现响应和工具状态。

5.2 接口协议

图片输入、思考参数和上下文窗口等能力由具体模型及其配置决定。协议适配提供统一的接入方式，运行时仍按照所选模型的能力组织请求。

6. 工具与权限

工具让 Agent 能够读取资料、修改文件、执行命令和访问外部服务。所有工具通过统一接口注册与调用，并在执行前检查参数、工作模式与权限。可用能力随运行环境和配置确定。

6.1 工具能力

6.2 执行与调度

并发调度根据工具声明的并发安全性安排调用：可安全并发的操作并行执行，其余操作顺序执行，结果按原调用顺序返回。运行时也支持顺序调度，以适配不同执行需求。

文件访问以工作目录和额外授权目录为依据，并结合当前权限模式判断。WorkSpace 提供项目上下文，具体操作范围由权限规则与工具执行方式共同决定。

6.3 外部工具接入

MCP 将外部服务转换为 Agent 可调用的工具。服务器连接建立后，其工具进入统一执行流程，模型能够像使用内置工具一样使用这些能力。全局配置位于 <PilotHome>/mcp.json，项目配置位于 <project-root>/.pilotdeck/mcp.json；同名服务器以项目配置为准。

7. 扩展机制

PilotDeck 通过 Skills、Plugins 和生命周期 Hook 扩展任务能力。Skills 描述特定任务的操作方法与知识；Plugins 提供工具、命令、MCP 服务器等能力；Hook 则在指定运行阶段参与处理。扩展可在全局复用，也可随项目加载，让通用运行时适配不同工作场景。

WorkSpace 是 PilotDeck 组织项目工作的基本单位。它以工作目录为中心，将会话、文件操作、项目记忆与项目扩展联系起来。每个项目拥有自己的工作上下文，Agent 因此能够在连续的对话中理解项目，并在不同任务之间复用已有经验。

1. WorkSpace 概念

选择一个项目目录，即确定了 Agent 的执行位置和项目文件入口。文件操作以这一目录为基础，并按照权限规则访问项目和额外授权的路径。

WorkSpace 中可以创建多个会话：它们分别保存对话与执行状态，同时使用同一项目的文件和长期记忆。例如，功能开发与文档维护可以在不同会话中进行，并共享项目背景与已确认的约定。

2. 项目身份与工作目录

PilotDeck 使用项目的真实路径识别 WorkSpace，将界面显示名称与存储身份分开。目录名称便于展示，路径用于准确定位项目；同名目录会通过路径信息区分，避免历史会话被错误归入另一个项目。

执行目录负责定位文件与运行命令，数据目录负责保存会话和辅助记录。两者分开组织，使切换项目时能够同时切换任务上下文，并保留各自的历史。

3. 数据组织

项目文件保留在原工作目录中。会话记录与文件历史等运行数据由 PilotDeck 的数据目录管理；长期记忆按工作区组织，并在全局保留可跨项目复用的用户画像。

对话以 JSONL 形式持久保存，便于按执行顺序追加和恢复。项目存储中的目录标记记录真实路径，用于将历史数据关联回对应的工作目录。

4. 会话管理

会话是 WorkSpace 内持续推进任务的单位。新会话从项目上下文开始，历史会话则恢复已有消息和设置。关闭运行中的会话会释放运行时资源，已保存的对话记录仍可供后续打开。

4.1 会话生命周期

会话在等待输入时处于空闲状态；收到请求后进入运行状态，持续输出文本和工具进展。正常完成后回到空闲状态，取消或执行失败则记录相应结果。用户可以在同一会话中继续任务，也可以新建会话处理另一个目标。

4.2 会话恢复

打开历史会话时，系统从持久化记录中恢复消息、会话设置和控制边界。对于已经压缩过的历史，恢复使用最近的有效压缩快照，并接续其后的记录，让新的请求从可继续执行的上下文开始。

会话恢复保留任务历史；命令或文件操作是否已经生效，则以实际工作目录中的状态为准。后续任务仍通过工具读取当前环境并继续处理。

4.3 对话与执行记录

Transcript 按执行过程记录用户输入、模型消息、工具结果、任务状态、文件产物和最终结果。压缩边界与会话元数据也一同保存，使实时执行和历史恢复使用一致的记录基础。

较大的工具结果可以独立落盘，并在上下文中保存引用。这样既能保留可读取的原始信息，也能控制后续模型请求的输入规模。

5. 配置与项目扩展

模型、路由和 Memory 等运行参数由当前加载的 pilotdeck.yaml 管理。默认配置位于 <PilotHome>/pilotdeck.yaml，也可通过启动参数或 PILOTDECK_CONFIG_PATH 指定配置文件。

项目专属能力放在工作目录的 .pilotdeck/ 下，与全局能力共同加载：

<project-root>/.pilotdeck/
├── plugins/        # 项目插件
├── skills/         # 项目技能
└── mcp.json        # 项目 MCP 连接

项目级 MCP 的同名服务器覆盖全局设置。项目扩展随工作目录选择，运行参数则由选定的 YAML 配置统一提供。

6. 多项目与 General

Web 与桌面端通过项目和历史会话列表管理多个 WorkSpace。切换项目时，执行目录、会话与项目记忆按所选项目加载；跨项目通用的用户画像继续复用。

General 为不绑定具体项目的任务提供独立工作目录。Web 端默认使用 ~/general，也可通过 WORKSPACES_ROOT 调整。其执行目录与 PilotDeck 数据目录分别管理。

普通 WorkSpace 的记忆检索围绕当前项目进行；General 可以根据任务，从已知工作区中选择相关项目记忆。这使项目知识既能在本项目内持续积累，也能在需要时为跨项目任务提供背景。

Router 省钱路由

Router 是 PilotDeck 的模型路由引擎。它根据任务复杂度自动选择最合适的模型，并在请求失败时尝试备用模型，减少不必要的模型开销。

router:
  tokenSaver:
    enabled: true
    judge: openai/gpt-4.1-mini
    defaultTier: medium
    subagent:
      policy: judge
    tiers:
      simple:
        model: openai/gpt-4.1-mini
      medium:
        model: openai/gpt-4.1-mini
      reasoning:
        model: openai/gpt-4.1
      complex:
        model: openai/gpt-4.1

router:
  fallback:
    default:
      - openai/gpt-4.1-mini
      - deepseek/deepseek-chat

router:
  zeroUsageRetry:
    enabled: true
    maxAttempts: 2

router:
  autoOrchestrate:
    enabled: true
    triggerTiers: [complex]

PilotDeck 的长期记忆由 Recall（回忆）、Index（索引）和 Dream（整理） 三个阶段组成。Recall 为当前任务取回相关知识，Index 将对话经验转化为持久记忆，Dream 对已有记忆进行整理与更新。三者共同形成持续学习与复用的闭环，让项目经验能够跨会话延续。

1. 核心能力

2. 三阶段工作机制

三个阶段具有不同的运行节奏：Recall 在准备模型请求时按需执行，Index 和 Dream 则通过后台维护或手动操作运行。它们围绕同一份长期记忆协作，而非要求每轮对话都同步完成全部阶段。

2.1 Recall：按需回忆

Recall 从当前用户请求和近期对话出发，判断是否需要长期记忆，以及应读取用户画像、项目知识或两者。对于项目知识，系统先查看记忆目录与条目描述，再选择相关文件读取正文，将结果整理为本次请求的背景信息。

普通 WorkSpace 以当前项目为检索范围；General 可从已知工作区中选择相关项目。没有相关内容时不注入记忆，避免无关知识占用上下文。

2.2 Index：经验入库

Index 将交互中形成的经验转化为可长期复用的知识。每轮对话结束后，系统先保存原始记录及其会话、时间和来源信息，再由索引过程处理待提炼内容。

索引结合对话语义提炼项目状态、决策与事实，记录用户反馈中的工作规则，并将稳定的用户信息归入身份笔记。结果以分类的文件记忆保存，供之后的 Recall 读取。原始对话捕获是这一阶段的输入准备；可检索知识在索引完成后形成。

2.3 Dream：记忆整理

随着对话积累，同一主题可能形成多条记忆，项目状态和用户偏好也会变化。Dream 面向已有记忆进行整体整理：识别内容重叠或存在冲突的主题，按关联关系组织和合并条目，修订项目元信息，并汇总用户身份笔记以更新画像。

整理前会先处理待索引内容。随后在暂存副本中生成修订结果，再提交到正式记忆库，并保存变更追踪与整理前的快照。经过整理的知识继续参与后续 Recall，让长期记忆随项目进展保持可用。

3. 记忆组织与存储

长期记忆按用途组织，而非仅按对话时间排列：

Markdown 文件保存可阅读和编辑的知识，记忆目录与项目元信息帮助 Recall 定位内容。SQLite 保存原始对话、处理状态和执行追踪，为 Index 与 Dream 提供运行依据。默认数据目录为 <PilotHome>/memory，每个工作区使用独立的路径标识组织项目数据。

4. 与上下文的协作

Memory 与会话上下文分别承担长期知识和当前任务信息。Recall 读取的相关知识由上下文系统封装，作为补充背景加入 System Prompt；用户当前请求和会话历史继续构成任务的主要输入。

当前请求中的明确指令优先于历史记忆。用户提出新的规则或修正后，这些交互会成为后续 Index 和 Dream 的输入，使记忆逐步更新。

4.1 请求中的记忆生命周期

后台维护按照配置间隔和待处理内容安排 Index 与 Dream。记忆检索超时或暂时失败时，任务可以继续使用已有会话上下文；诊断信息用于后续排查。

5. 启用与调度

在 pilotdeck.yaml 中启用 Memory，并设置索引与整理的运行间隔。下面的间隔为配置示例，可根据对话量和模型成本调整：

memory:
  enabled: true
  provider: edgeclaw
  captureStrategy: last_turn
  includeAssistant: true
  maxMessageChars: 6000
  retrievalTimeoutMs: 30000
  schedule:
    autoIndexIntervalMinutes: 30
    autoDreamIntervalMinutes: 240

captureStrategy 可选择 last_turn 或 full_session，控制原始对话的捕获范围。retrievalTimeoutMs 控制请求等待记忆检索的时间。两个维护间隔分别控制自动索引与自动整理；实际执行还取决于是否存在待处理内容。

Memory 可通过 model 指定模型池中的 provider/model，未指定时使用 Agent 默认模型。未配置 Memory 或设置 enabled: false 时，内置记忆服务关闭。

6. 可观测与管理

记忆管理界面提供文件查看与编辑、弃用与恢复、手动索引与整理，以及导入导出。Recall、Index 和 Dream 的追踪记录分别展示知识如何被读取、如何形成以及如何被修订，便于检查记忆与实际项目是否一致。

新对话尚未反映在记忆中时，可以查看待索引记录并执行手动索引；已有记忆出现重复或需要重新组织时，可以执行 Dream 并检查其变更结果。原始记录、文件记忆和阶段追踪共同提供从对话到知识的可检查过程。

PilotDeck 提供两种后台自动化能力：Always-On（自主 Agent）和Cron（定时任务）。前者由 Agent 自行判断该做什么，后者按设定的时间表执行指定的任务。

1. Always-On

Always-On 是 PilotDeck 的后台自主 Agent 功能。启用后，它会在 PilotDeck 空闲时，自动浏览工作区中的文件和近期对话，自主判断有价值的任务，并在一个独立的副本中完成操作、生成报告。用户只需读取报告，决定是否采纳即可。

1.1 工作流程

Always-On 每一轮自动运行以下流程：

（1）发现

Agent 浏览工作区中的文件，同时参考近期的聊天记录，自主判断有什么事情值得去做，写成一份 Plan（包含标题、概述和理由）。

• 每轮最多产出 1 个 plan
• 之前已经产出过的相同任务不会重复
• 如果没有发现值得做的事，本轮结束，Agent 进入休眠

（2）准备工作副本

Agent 会先复制一份工作区的内容，在这个副本中操作——不会直接动原始文件。同一个工作区同时只有一个副本，后续 plan 会复用已有的副本。

（3）执行

Agent 在副本中按照 plan 进行操作。这一步有严格的安全限制：所有改动只发生在副本中，原始文件不受影响；Agent 也无法将内容推送到远程。

（4）报告

执行完成后，Agent 写一份报告，说明做了什么、为什么这么做、以及改动概要。

（5）应用

1–4 步完全自动，最后一步需要手动操作：在常驻面板中查看 plan 和报告后，点击"应用"，副本中的改动才会写入工作区。

1.2 运行约束

Always-On 不会无节制地运行。每次开始前会检查以下条件：

默认每 5 分钟检查一次上述条件。

1.3 休眠与唤醒

如果 Agent 扫描一圈后觉得"没什么可做"，它不会反复空跑，而是进入休眠。休眠期间它会留意工作区里的文件变化。一旦检测到有文件被修改或新增，就退出休眠，回到正常的定期检查流程。

1.4 配置说明

只需指定工作区路径并打开 enabled，其余参数都有默认值，不需要额外调整。

2. Cron

定时任务用于预先指定一段指令和执行时间，PilotDeck 会在到达时间后自动启动 Agent 来执行。与 Always-On 不同，定时任务不需要 Agent 自己去"发现"该做什么，而是由用户定义做什么、什么时候做，它按时完成。

2.1 两种定时方式

2.2 执行过程

到达预定时间后：

1. PilotDeck 自动启动一个 Agent 来执行设定的指令
2. Agent 在后台完成操作，无需人工干预
3. 执行结果会发送到创建任务时所在的聊天渠道

2.3 配置说明