> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 桌面端架构

> 本地优先的桌面客户端——执行在本机，资产在云端

袋袋桌面端不是「网页套壳」那么简单：它把 AI 的**执行平面**完整搬到了你的电脑上，同时把账号、技能库、专家内容这些**资产**留在云端统一管理。这种切分让桌面端既能操作你的本地文件、浏览器和屏幕，又能与 Web 端、移动端共享同一套技能与专家生态。

## 双平面模型

理解桌面端只需要记住一条线：**数据归属跟着消费场景走**。

| 平面      | 位置   | 包含内容                              |
| ------- | ---- | --------------------------------- |
| 执行平面    | 你的电脑 | Agent 循环、工具执行、沙盒隔离、会话历史、插件偏好、录制数据 |
| 资产与结算平面 | 云端   | 账号认证、技能库、专家内容、记忆图谱、计费与权益、市场分发     |

<CardGroup cols={2}>
  <Card title="执行在本机" icon="laptop">
    Agent 循环直接跑在你的电脑上，通过系统级沙盒（macOS Seatbelt）隔离执行。操作本地文件、控制浏览器、录制屏幕都不需要经过云端中转。
  </Card>

  <Card title="资产在云端" icon="cloud">
    技能、专家、记忆的唯一真相源在云端——这保证了你在 Web 端创建的技能，桌面端立刻可用；桌面端沉淀的技能，其他设备同样可见。
  </Card>
</CardGroup>

## 双进程架构

桌面应用由两个进程协作构成：

```mermaid theme={null}
graph LR
    subgraph 你的电脑
        R[渲染层<br/>Web 界面] <-->|IPC| E[Electron 主进程]
        E <-->|stdio JSON-RPC| S[Python Sidecar<br/>Agent 循环]
        E --> B[浏览器控制 CDP]
        E --> C[屏幕操作 CUA]
        S --> L[(本地状态<br/>~/.profy)]
    end
    S -->|prepare / finalize| Core[云端 Core API]
    S -->|模型推理| LLM[模型网关]
```

* **Electron 主进程**：负责窗口、浏览器自动化（CDP）、屏幕操作、录制覆盖层等系统能力
* **Python Sidecar**：运行完整的 Agent 循环，与云端只保留两类通信——会话开始时的权益校验（prepare）和结束时的结算回传（finalize）

## 本地优先的会话状态

桌面端的会话历史以追加式 JSONL 文件存储在本机 `~/.profy/` 下，这是会话的**唯一真相源**：

<Steps>
  <Step title="每轮对话即时落盘">
    对话的每一轮（用户消息、AI 回复、工具调用）同步写入本地 rollout 文件，跨轮上下文由本地历史重建——即使云端抖动，对话上下文也不会断。
  </Step>

  <Step title="云端投影异步补偿">
    会话结束后向云端回传一份「投影」用于 Web 端可见性与计费结算。回传失败不丢弃：进入本地重试队列，指数退避直至最终一致。
  </Step>

  <Step title="界面直接读本地">
    会话列表、历史消息在桌面端直接从本地磁盘读取，离线也能浏览全部历史；云端会话合并显示，同一会话以本地版本优先。
  </Step>
</Steps>

插件启用状态同样本地持久化：激活过的插件写入本地配置文件，跨会话、跨重启保持生效，无需每次重新选择。

## 认证：Access + Refresh 双凭证

桌面端的后台进程不使用服务端密钥（服务端密钥永不离开机房），而是采用与业界桌面客户端一致的双凭证模型：

```mermaid theme={null}
sequenceDiagram
    participant D as 桌面 Sidecar
    participant Core as 云端 Core
    D->>Core: 用会话令牌（refresh 凭证）请求铸造
    Core-->>D: 签发短语义 JWT（access 凭证）
    D->>Core: 业务调用统一 Authorization: Bearer
    Note over D: 过期前自动重铸，无感续期
```

* **会话令牌 = refresh 凭证**：登录后捕获，服务端可随时撤销，只接触铸造端点
* **JWT = access 凭证**：无状态、可验签，跑在所有业务调用热路径上

## 录制 → 技能 → 回放闭环

桌面端独有的能力闭环：

<Steps>
  <Step title="录制">
    点击录制后，系统级事件捕获记录你的操作流（点击、输入、导航），录制数据只存本地。
  </Step>

  <Step title="沉淀为技能">
    停止录制自动触发 AI 分析：解析操作流、提炼意图、生成结构化技能并保存到你的云端技能库——此后所有设备可用。
  </Step>

  <Step title="回放">
    新会话中激活该技能，AI 通过浏览器自动化（可信输入事件）与屏幕操作能力复现整个流程，每一步执行后验证结果。
  </Step>
</Steps>

## 计费门禁

本地执行不等于绕过计费：每次对话开始前，Sidecar 必须通过云端的权益校验（prepare）——校验失败则对话被阻断。这与 Codex 的设计一致：**线程在本地，推理由云端计费门禁守护**。桌面模式下云端不会创建云沙盒（执行已在本机），不产生多余的资源成本。

## 与业界产品的对照

| 能力   | 袋袋桌面端         | Codex (ChatGPT.app)    | 说明                  |
| ---- | ------------- | ---------------------- | ------------------- |
| 会话历史 | 本地 JSONL      | 本地 JSONL               | 一致：本地优先             |
| 技能存储 | 云端（多端共享）      | 本地文件夹                  | 有意差异：袋袋技能需进市场、跨设备同步 |
| 认证   | 会话令牌 + JWT    | OAuth access + refresh | 同构：用户凭证，无服务端密钥      |
| 执行   | 本机 + 系统沙盒     | 本机 + 系统沙盒              | 一致                  |
| 计费   | 云端 prepare 门禁 | 云端推理网关                 | 一致：本地执行、云端结算        |