PilotDeck：面向 macOS 的智能体操作系统架构

1. PilotDeck（Agent OS）架构设计：一个面向真实工作流的工程化智能体操作系统

PilotDeck 不是又一个玩具级 Agent 框架，也不是把 LLM API 封装三层再起个酷炫名字的 Demo 工具。它直指当前智能体落地最痛的三个断层：状态散、技能乱、项目混。你有没有试过同时跑三个 Agent 任务——一个在写周报，一个在整理会议纪要，一个在分析销售数据？不到半小时，记忆错乱、文件覆盖、提示词互相污染，最后不得不全盘重启。PilotDeck 的核心设计哲学就一句话：把 Agent 当成一个有工位、有抽屉、有日程表的数字员工来养，而不是当一个随时可能发疯的 API 调用器来用。它用 WorkSpace 作为第一公民，强制所有状态——文件、短期记忆、长期记忆、会话历史、已加载技能、运行时上下文——全部按项目维度隔离。这不是简单的命名空间隔离，而是从存储层、内存管理、执行沙箱到 UI 渲染的全栈隔离。你打开 PilotDeck，看到的不是一个空白聊天框，而是一个带项目看板、文件树、技能面板和实时状态监控的“数字工位”。这种设计直接对应了 macOS 用户最熟悉的范式：每个 App 有独立的沙盒、每个文档有独立的窗口、每个任务有独立的 Dock 图标。所以当网络上大量搜索“mac os x 系统下安装 hermes agent”时，背后的真实需求根本不是 Hermes 本身，而是 macOS 用户迫切需要一个能像 Finder 和 Notes 那样原生、稳定、可信赖的智能体工作环境。PilotDeck 的架构，就是为这个需求量身定制的操作系统级解决方案。它不追求在单个 CPU 周期内完成多少指令（那是单周期 RISC-V 架构的事），而是追求在一个工作日内，让工程师、产品经理、设计师能连续 8 小时不中断、不混淆、不丢状态地与多个智能体协同。这正是“Agent OS”这个称谓的分量所在——OS 不是形容词，是动词，是调度、是隔离、是持久化、是资源管理。

2. WorkSpace 为核心的设计逻辑与工程取舍

2.1 为什么 WorkSpace 是唯一正确的起点？

几乎所有失败的 Agent 项目，都始于一个错误的假设：Agent 的核心是“能力”或“模型”。于是大家疯狂堆砌工具调用、写复杂提示词、对接各种 API，结果做出来的东西像一个没有户口、没有住址、没有社保编号的“黑户智能体”，今天在 A 项目里表现神勇，明天一进 B 项目就彻底失忆、胡言乱语。PilotDeck 反其道而行之，把 WorkSpace 设计为整个系统的根节点和唯一入口。这背后是三个硬核的工程判断：

第一，状态一致性比功能丰富性更稀缺。一个能完美调用 50 个 API 的 Agent，如果每次对话都记不住上一句说了什么，它的价值归零。WorkSpace 强制将所有状态绑定到一个明确的、用户可感知、可操作的实体上。文件存哪里？在workspace/project-x/docs/。短期记忆存哪里？在workspace/project-x/memory/short-term/。连模型微调的 checkpoint 都默认存workspace/project-x/models/。这种路径即语义的设计，让状态管理从“靠人脑记住”变成“靠文件系统保证”。

第二，项目是人类认知的天然单元，不是技术妥协。我们不会说“我正在用 Python 处理数据”，而是说“我在做 XX 客户的 CRM 数据清洗项目”。PilotDeck 的 WorkSpace 直接映射这个现实。新建一个 WorkSpace，等同于在 Finder 里新建一个文件夹并双击打开——这是 macOS 用户肌肉记忆的一部分。这种设计消除了“我在哪个上下文里”的认知负担，把心智资源全部释放给真正的创造性工作。

第三，隔离是可靠性的基石，而隔离必须是默认且无感的。很多框架提供“会话 ID”来模拟隔离，但这要求开发者在每一行代码里手动传递 ID，极易出错。PilotDeck 的 WorkSpace 隔离是进程级的。当你切换 WorkSpace，底层会启动一个全新的执行环境（可以是轻量级容器、独立的 Node.js 进程，或基于 Web Worker 的沙箱），内存、文件句柄、网络连接全部重置。这就像你在 macOS 上同时打开两个 Safari 窗口，一个登录公司邮箱，一个登录个人 Gmail，它们之间天然隔离，你甚至不需要知道“隔离”这个词。

提示：WorkSpace 的隔离粒度是可配置的。对于轻量级任务（如快速查文档），可以启用“内存快照模式”，仅隔离内存和变量；对于高安全要求任务（如处理客户 PII 数据），则强制启用“全沙箱模式”，包括独立的临时文件目录和网络代理策略。这种灵活性避免了“一刀切”带来的性能损耗。

2.2 WorkSpace 内部状态的四维建模

一个 WorkSpace 不是一个扁平的文件夹，而是一个精心设计的四维状态空间，每个维度解决一类关键问题：

• 文件维度（File Space）：这是最直观的。它不只是存储上传的 PDF 或 Excel，而是构建了一个轻量级的、面向 Agent 的文件系统。每个文件都有元数据标签（#type=report,#source=meeting-transcript,#status=draft），支持全文索引和向量嵌入。更重要的是，它内置了“文件生命周期钩子”：当一个.csv文件被放入data/raw/目录时，系统自动触发一个预设的“数据清洗 Agent”；当一个report.md文件被标记为#status=final时，自动调用“报告分发 Agent”发送邮件。这把被动的“调用 Agent”变成了主动的“事件驱动”。

• 记忆维度（Memory Space）：分为三层。瞬时记忆（Working Memory）存在内存中，只存活于单次会话，用于临时计算。项目记忆（Project Memory）是核心，它是一个结构化的知识图谱，节点是实体（人、产品、日期），边是关系（“张三负责XX项目”、“XX项目截止于2024-10-15”）。这个图谱由 Agent 在交互中自动构建和更新，用户可以用自然语言查询：“这个项目里谁负责前端？” 系统直接返回图谱中的关系，而非模糊的文本匹配。全局记忆（Global Memory）则是跨 WorkSpace 的共享知识库，比如公司通用术语表、常用模板，它通过权限控制确保敏感信息不越界。

• 会话维度（Session Space）：这是用户与 Agent 交互的“时间线”。它不是简单的消息列表，而是带有意图标记的交互流。每条消息会被自动标注类型：[question]、[command]、[confirmation]、[error-recovery]。当用户说“把刚才生成的图表加到报告里”，系统能精准定位“刚才”指的是哪一轮会话，并提取其中的图表对象。这种结构化会话，是实现复杂多步任务（如“分析数据→生成图表→撰写解读→插入报告→发送给老板”）的底层保障。

• 技能维度（Skill Space）：这是最容易被误解的部分。PilotDeck 不把“技能”当作一堆函数，而是当作可插拔、可组合、有状态的“微服务”。一个“邮件发送技能”不仅包含 SMTP 配置，还包含收件人白名单、附件大小限制、失败重试策略等状态。这些状态都绑定在 WorkSpace 上。你在 A 项目里配置了 Gmail，B 项目里配置了 Outlook，互不影响。更关键的是，技能可以“继承”：B 项目可以声明“继承 A 项目的邮件技能，但替换发件人地址”，这极大减少了重复配置。

2.3 架构选型背后的硬核权衡：为什么不是微服务，也不是单体？

面对“多租户架构设计”、“上位机架构设计”这些热词，PilotDeck 的架构师团队做了大量基准测试。他们对比了三种主流方案：

• 纯微服务架构：将 WorkSpace 管理、记忆服务、文件服务、技能调度全部拆成独立服务。好处是弹性伸缩好，坏处是延迟爆炸。一次简单的“读取项目记忆+查询文件+调用技能”操作，需要跨越 4 次网络调用，在本地开发环境下平均耗时 320ms，用户感知明显卡顿。对于追求即时反馈的桌面应用，这是不可接受的。

• 传统单体架构：所有逻辑打包进一个大进程。好处是零延迟，坏处是隔离性差。一个 WorkSpace 的内存泄漏会拖垮所有项目，一个技能的 Bug 会导致整个应用崩溃。这违背了“OS”的基本可靠性要求。

• PilotDeck 的混合架构（Hybrid Runtime）：这是最终选择，也是其核心创新点。它采用“主进程 + 工作区沙箱进程”的两级结构。主进程（Main Process）只负责 UI 渲染、WorkSpace 生命周期管理、全局事件总线和资源调度。每个 WorkSpace 运行在一个独立的、受主进程严格管控的沙箱进程中（Sandbox Process）。沙箱进程拥有自己的 V8 引擎实例、独立的内存堆、受限的文件系统访问权限（只能访问本 WorkSpace 目录）和网络策略。主进程与沙箱进程通过高性能 IPC（基于共享内存的 Ring Buffer）通信，延迟控制在 2ms 以内。这种设计，既获得了单体的低延迟，又拥有了微服务的强隔离。你可以把它理解为 macOS 的 App Sandbox 机制在智能体领域的深度复刻——每个 App（WorkSpace）都是独立的、受保护的，但又共享同一个操作系统（PilotDeck 主进程）提供的统一服务。

注意：沙箱进程的资源配额是动态的。主进程会持续监控每个沙箱的 CPU 使用率、内存占用和 I/O 等待时间。当检测到某个 WorkSpace 的 Agent 正在执行一个计算密集型任务（如向量相似度搜索），主进程会自动为其分配更多 CPU 时间片，并临时放宽内存限制；当该任务完成后，资源会立即回收。这种细粒度的资源调度，是普通 Electron 应用无法做到的。

3. 核心模块解析与实操实现细节

3.1 WorkSpace 生命周期管理器（WSLM）

这是 PilotDeck 的“心脏起搏器”，负责 WorkSpace 的创建、激活、挂起、恢复和销毁。它的实现远比mkdir+cd复杂。

创建（Create）：当用户点击“新建项目”时，WSLM 执行以下原子操作：

1. 在用户指定路径（如~/PilotDeck/Projects/）下生成唯一 UUID 命名的文件夹。
2. 初始化标准目录结构：/docs,/data,/memory,/skills,/logs。
3. 生成workspace.config.json，其中包含：

{ "id": "ws-7a3b9c1d", "name": "Q3营销分析", "created_at": "2024-06-15T10:23:45Z", "default_model": "gpt-4-turbo", "memory_strategy": "graph+vector", "sandbox_mode": "full" }

4. 启动一个沙箱进程，并传入该配置。沙箱进程启动后，会加载skills/下所有技能定义，并初始化memory/graph.db（一个嵌入式的 Neo4j Lite 实例）。

激活（Activate）：用户点击某个 WorkSpace 图标时，WSLM 并非简单地“聚焦”窗口。它执行：

• 向目标沙箱进程发送ACTIVATE信号。
• 沙箱进程收到信号后，从磁盘加载memory/short-term/的最新快照到内存。
• 主进程 UI 层切换到该 WorkSpace 的专属视图，包括渲染其docs/目录树和skills/面板。
• 关键一步：WSLM 会检查该 WorkSpace 的skills/目录是否有更新（例如，用户在 Finder 里手动修改了一个技能的 YAML 文件），如有，则触发“热重载”，无需重启沙箱进程。

挂起（Suspend）：当用户长时间未操作某个 WorkSpace，或系统内存紧张时，WSLM 会：

• 向沙箱进程发送SUSPEND信号。
• 沙箱进程立即将当前内存中的瞬时记忆和未保存的会话状态序列化，写入memory/short-term/snapshot.bin。
• 沙箱进程释放大部分内存，进入休眠状态，仅保留一个极小的监听线程等待RESUME信号。
• 主进程 UI 层将该 WorkSpace 图标置灰，并显示“已挂起”。

恢复（Resume）：用户再次点击挂起的 WorkSpace 时，WSLM 发送RESUME信号，沙箱进程从snapshot.bin快速恢复状态，整个过程 < 100ms，用户感觉不到中断。

销毁（Destroy）：这是最危险的操作。WSLM 会弹出一个带复选框的确认对话框：

• [x] 删除项目文件（docs/,data/）
• [ ] 删除项目记忆（memory/）—— 默认不勾选，因为记忆图谱可能包含跨项目通用知识
• [ ] 删除已安装技能（skills/）—— 默认不勾选，因为技能是可复用的资产 用户必须手动勾选“删除项目文件”才能继续。这借鉴了 macOS 的“废纸篓”机制，防止误删。

3.2 记忆图谱引擎（Memory Graph Engine）

这是 PilotDeck 区别于其他 Agent 工具的“大脑”。它不是一个简单的向量数据库，而是一个融合了符号逻辑与神经嵌入的混合知识库。

数据模型：图谱中的节点（Node）有严格 Schema：

interface EntityNode { id: string; // e.g., "ent-person-001" type: "person" | "project" | "document" | "metric"; name: string; properties: Record<string, any>; // e.g., { "email": "[e-mail]", "role": "frontend-dev" } embeddings: number[]; // 由 LLM 生成的 1536 维向量 }

边（Edge）则表示关系：

interface RelationEdge { from: string; // source node id to: string; // target node id type: "owns" | "responsible_for" | "derived_from" | "mentions"; confidence: number; // 0.0 - 1.0, 由 Agent 推理时给出 }

构建流程：图谱不是静态导入的，而是动态演化的。

• 初始构建：当用户首次将一份会议纪要（docs/meeting-20240615.txt）拖入 WorkSpace，系统会：
  1. 调用一个专用的“实体识别 Agent”，扫描文本，识别出人名、项目名、日期、指标等。
  2. 为每个识别出的实体创建EntityNode，并计算其embeddings。
  3. 分析句子结构，推断关系。例如，“张三负责前端开发” → 创建边("ent-person-001", "ent-project-001", "responsible_for")。
• 增量更新：后续每次用户与 Agent 交互，只要涉及新信息，图谱就会更新。例如，用户问：“张三最近在忙什么？”，Agent 查询图谱发现他“responsible_for”项目 A，然后去docs/中查找项目 A 的最新状态报告，并将报告中的关键结论（如“项目A延期一周”）作为新的RelationEdge添加到图谱中，形成("ent-person-001", "ent-metric-001", "impacted_by")。

查询接口：提供两种查询方式，满足不同场景：

• 自然语言查询（NLQ）："谁负责Q3营销分析项目？"→ 系统将其解析为 Cypher 查询：MATCH (p:person)-[r:responsible_for]->(pr:project {name: "Q3营销分析"}) RETURN p.name。
• 向量语义查询："找所有和‘用户增长’相关的文档"→ 系统将“用户增长”向量化，然后在所有Document节点的embeddings中进行近邻搜索，返回相似度最高的前 5 个docs/文件。

性能优化：为支撑毫秒级响应，引擎采用了多级缓存：

• L1：内存缓存（LRU），缓存最近 1000 个查询结果。
• L2：SSD 缓存，使用 RocksDB 存储图谱的索引结构（节点 ID 到磁盘偏移量的映射）。
• L3：冷数据归档，超过 90 天未访问的RelationEdge会被压缩并移至memory/archive/，查询时需解压，但概率极低。

3.3 技能编排与执行沙箱（Skill Orchestrator）

PilotDeck 的“技能”不是函数，而是遵循 Open Skill Protocol (OSP) 的标准化组件。一个 OSP 技能包是一个 ZIP 文件，解压后必须包含：

• skill.yaml：元数据描述（名称、版本、作者、所需权限）。
• manifest.json：定义输入/输出 Schema、触发条件（文件类型、关键词、定时）。
• code/：实际执行代码（支持 JavaScript, Python, Rust WASM）。
• ui/：可选的自定义配置界面（React 组件）。

执行沙箱的关键约束：

• 文件系统沙箱：技能代码只能通过 PilotDeck 提供的pilot.fsAPI 访问文件，且路径被严格限制在本 WorkSpace 内。尝试访问../../etc/passwd会直接抛出PermissionDeniedError。
• 网络沙箱：所有网络请求必须通过pilot.netAPI 发出。该 API 内置了企业级防火墙规则：
  • 默认禁止所有外网请求。
  • 允许的域名必须在workspace.config.json的allowed_domains列表中显式声明。
  • 对于api.openai.com这类 LLM API，会自动注入 API Key，并记录详细的调用日志（用于审计和成本分摊）。
• 计算沙箱：JavaScript 技能运行在 V8 的Context中，有严格的 CPU 时间限制（默认 5s，可配置）。Python 技能则运行在subprocess中，通过cgroups限制内存（默认 512MB）和 CPU 核心数（默认 1）。

编排逻辑：当一个复杂任务（如“生成月度销售报告”）被触发时，Skill Orchestrator 会：

1. 解析任务描述，生成一个有向无环图（DAG），节点是技能，边是数据流。
2. 为 DAG 中的每个节点分配一个唯一的execution_id。
3. 按拓扑序依次执行技能。前一个技能的输出（JSON 对象）会作为下一个技能的输入。
4. 如果某个技能失败，Orchestrator 会根据其manifest.json中定义的retry_policy（如{"max_attempts": 3, "backoff": "exponential"}）进行重试。
5. 整个 DAG 的执行状态（成功/失败/耗时/输入输出摘要）会被记录在logs/execution-<id>.json中，供用户审计。

实操心得：我在部署一个“自动抓取竞品官网新闻”的 Python 技能时，发现它在沙箱里总是超时。排查后发现，是 DNS 解析被沙箱的网络策略阻塞了。解决方案不是开放所有 DNS，而是将manifest.json中的network权限从"restricted"改为"dns-only"，并指定可信的 DNS 服务器（如1.1.1.1）。这体现了 PilotDeck 的设计哲学：安全不是靠“堵”，而是靠“精确定义”。

4. 从 macOS 用户视角看 PilotDeck 的落地实践

4.1 在 macOS 上的安装与首启体验

网络上大量搜索“mac os 安装 hermes agent”，反映出用户对 macOS 原生体验的强烈渴望。PilotDeck 的 macOS 版本，就是为终结这种碎片化搜索而生。

安装包：提供.dmg格式安装包，双击挂载后，将PilotDeck.app拖入Applications文件夹。整个过程与安装任何 macOS App 完全一致，无需命令行、无需 Homebrew、无需 Xcode 命令行工具。安装包内嵌了所有依赖（Node.js 运行时、Python 3.11 运行时、Rust WASM runtime），体积约 1.2GB，但换来的是开箱即用。

首次启动：

• 启动后，主进程会检查系统是否满足最低要求（macOS 12+，8GB RAM）。
• 自动创建~/Library/Application Support/PilotDeck/作为全局配置和缓存目录。
• 弹出“欢迎向导”，引导用户设置：
  1. 默认 WorkSpace 位置：建议设为~/PilotDeck/Projects/，这样所有项目都集中管理，符合 macOS 用户习惯。
  2. 默认 LLM 提供商：提供 OpenAI、Anthropic、Ollama（本地）三个选项。选择 Ollama 时，向导会自动检测本机是否已安装，并推荐llama3:70b模型。
  3. 隐私偏好：明确告知哪些数据会上传（仅错误日志和匿名的性能指标），并提供一键关闭选项。

与 macOS 深度集成：

• Spotlight 搜索：安装后，PilotDeck 会注册一个 Spotlight 插件。用户可以直接在 Spotlight（Cmd+Space）中输入pilot report Q3，即可快速打开名为 “Q3营销分析” 的 WorkSpace。
• Quick Look 预览：对docs/目录下的.md,.pdf,.csv文件，支持空格键预览，内容会自动被索引到记忆图谱中。
• Share Sheet 分享扩展：在 Safari 或 Notes 中，选中一段文字，点击分享按钮，选择 “Send to PilotDeck”，这段文字会自动创建为一个新 WorkSpace 的docs/scratch.md，并激活该 WorkSpace。这是 macOS 用户最顺手的工作流。

4.2 一个真实工作流：为新产品发布会准备媒体通稿

让我们用一个具体案例，展示 PilotDeck 如何将“智能智慧平台架构设计的主流技术路线”从概念落地为日常生产力。

场景：市场部同事需要在 48 小时内，为一款新硬件产品（代号“Nexus”）撰写一份面向科技媒体的英文通稿。

步骤 1：创建 WorkSpace

• 在 PilotDeck 主界面点击+ New Project，命名为 “Nexus Launch Media Kit”。
• WSLM 自动创建目录，并启动沙箱进程。

步骤 2：注入初始知识

• 将产品 PRD 文档、竞品分析报告、公司品牌指南 PDF 拖入docs/。
• PilotDeck 的文件处理器自动识别文档类型，调用 OCR（如果是扫描件），并触发“知识抽取 Agent”，将关键信息（产品规格、核心卖点、目标用户）注入记忆图谱。

步骤 3：启动多技能协同

• 在 WorkSpace 的命令栏输入：/draft press release for tech media。
• Skill Orchestrator 解析此命令，生成 DAG：
  • skill:extract-keypoints（从 PRD 中提取 5 个核心卖点）→ 输出 JSON 数组。
  • skill:generate-headlines（基于卖点生成 10 个标题）→ 输入为上一步输出。
  • skill:write-draft（用选定标题和卖点，撰写 800 字英文草稿）→ 输入为上两步输出。
• 整个 DAG 在后台静默执行，耗时 42 秒。完成后，docs/draft-press-release.md自动生成。

步骤 4：迭代与润色

• 用户打开draft-press-release.md，选中一段文字，右键选择Ask PilotDeck: Make this more concise。
• PilotDeck 的会话维度自动捕获上下文（当前文件、当前段落、当前 WorkSpace 的记忆图谱），调用一个专门的“文案精炼 Agent”，返回改写结果。
• 用户还可以问：“竞品 X 在类似发布中强调了哪些技术点？” —— 系统查询记忆图谱中关于竞品 X 的节点，找到其历史发布文档，并提取技术关键词，直接在当前编辑器侧边栏显示。

步骤 5：分发与归档

• 草稿定稿后，用户输入/send to marketing-team。
• skill:email-distribute被触发，它从记忆图谱中查找marketing-team的成员邮箱，并将docs/draft-press-release.md作为附件发送。
• 同时，skill:archive-final将最终版复制到docs/final/，并更新记忆图谱中Nexus Launch项目的status属性为published。

整个过程，用户没有离开 PilotDeck 界面，没有切换 App，没有手动复制粘贴，所有状态都在一个 WorkSpace 内无缝流转。这正是“上位机架构设计”和“多租户架构设计”在桌面端的终极体现：一个统一的、可编程的、状态完备的上位控制中心，管理着多个独立、安全、可审计的“租户”（即 WorkSpace）。

4.3 与“单周期 RISC-V 架构的 CPU 设计”等硬核技术的隐喻关联

虽然 PilotDeck 是软件，但其架构思想与顶尖硬件设计有着惊人的同源性。理解这种关联，能让你一眼看穿其设计的精妙。

• 单周期 vs. 多周期：单周期 RISC-V CPU 的目标是“在一个时钟周期内完成一条指令”，极致追求单次操作的确定性与时效性。PilotDeck 的沙箱进程 IPC 通信（2ms 延迟）、记忆图谱的 L1 缓存（亚毫秒响应）、技能执行的 CPU 时间限制（5s 硬上限），都是在软件层面追求“单周期”级别的确定性。它不承诺“永远快”，但承诺“永远可预期”。这与那些动辄几十秒响应、时快时慢的 Web Agent 形成鲜明对比。

• MCU+SoC 系统架构：一个典型的 MCU（微控制器）负责实时、确定性的底层控制（如读取传感器），而 SoC（系统级芯片）则运行复杂的操作系统和应用。PilotDeck 的主进程（Main Process）就是那个强大的 SoC，它管理 UI、调度、全局服务；而每个沙箱进程（Sandbox Process）就是一个专用的 MCU，只做一件事：运行一个 WorkSpace 的所有逻辑。它们通过高速总线（IPC）连接，分工明确，各司其职。这种异构计算架构，是处理复杂、多任务智能体工作流的最优解。

• NorFlash 存储特性：NorFlash 的特点是“随机读取快，写入慢，但擦除可靠”。PilotDeck 的memory/graph.db（图谱数据库）设计就借鉴了这一点。它对“读取”（查询关系）做了极致优化（B+Tree 索引 + 内存映射），确保毫秒响应；而对“写入”（添加新关系）则采用 WAL（Write-Ahead Logging）日志，先写日志再更新主库，保证即使在崩溃时，数据也不会丢失。这种“读优写稳”的设计，完美匹配了智能体工作流中“查询远多于写入”的真实负载特征。

5. 常见问题与实战排障指南

5.1 WorkSpace 启动失败：沙箱进程崩溃的 5 种原因与对策

沙箱进程崩溃是 macOS 用户最常见的问题，因为它直接导致 WorkSpace 无法打开。以下是基于上千次用户日志分析总结的 Top 5 原因及解决方案：

问题现象	根本原因	诊断方法	解决方案	个人经验
启动时立即崩溃，日志显示Segmentation fault	沙箱进程尝试加载了不兼容的二进制插件（如旧版 Python C 扩展）	查看~/Library/Logs/PilotDeck/sandbox-<ws-id>.log，末尾有SIGSEGV错误	进入~/PilotDeck/Projects/<ws-name>/skills/，删除所有.so或.dylib文件，或升级到支持 arm64 的新版	我曾因此浪费 3 小时，后来写了个脚本pilot-sandbox-check，一键扫描并报告所有可疑的二进制文件
启动卡在“Loading skills...”，10 分钟无响应	某个技能的manifest.json中定义了错误的init_timeout（如设为 300s），且其初始化代码存在死循环	日志中会反复出现Waiting for skill 'xxx' to initialize...	临时重命名skills/下的可疑技能文件夹，重启 WorkSpace。确认后，编辑其manifest.json，将init_timeout改为30	PilotDeck 未来版本会加入“技能健康检查”功能，在安装时就验证其初始化逻辑
WorkSpace 能打开，但所有技能都显示“Not Available”	workspace.config.json中的sandbox_mode设置为"full"，但用户禁用了 macOS 的“完全磁盘访问”权限	系统设置 > 隐私与安全性 > 完全磁盘访问，检查PilotDeck.app是否被勾选	勾选PilotDeck.app，然后重启 PilotDeck 主应用	这是 macOS 13+ 的新限制，很多老用户不知道，PilotDeck 的安装向导现在会主动提醒并跳转到该设置页
首次打开某个 WorkSpace 时，文件树为空，但docs/目录里明明有文件	文件系统权限问题：docs/目录的所有者是root，而 PilotDeck 以当前用户运行	在终端执行ls -la ~/PilotDeck/Projects/<ws-name>/docs/，查看所有者	sudo chown -R $USER ~/PilotDeck/Projects/<ws-name>/	这通常发生在用户用sudo命令手动创建了项目目录后，PilotDeck 无法绕过系统权限
WorkSpace 启动后，UI 显示正常，但所有 AI 交互都返回Model not found	默认模型配置错误：workspace.config.json中的default_model值（如"gpt-4-turbo"）在当前环境下不可用（如选择了 Ollama，但本地没拉取该模型）	查看主进程日志~/Library/Logs/PilotDeck/main.log，搜索model not found	打开 WorkSpace 设置，将default_model改为ollama/llama3，或在终端执行ollama pull gpt-4-turbo（如果使用 Ollama）	PilotDeck 的模型管理器现在支持“模型可用性预检”，在 WorkSpace 激活前就验证模型是否存在

5.2 记忆图谱“失忆”：为什么我的 Agent 总是记不住上周的事？

这是一个高频困惑，根源在于对“记忆”层级的误解。

• 瞬时记忆（Working Memory）：这是最易丢失的。它只存在于单次会话中，关闭聊天窗口或刷新页面就清空。这是设计使然，不是 Bug。如果你需要长期记住某件事，必须让它进入“项目记忆”。

• 项目记忆（Project Memory）：这才是你应该依赖的。但它的构建需要“触发”。仅仅把一份文档拖进去，系统只会提取实体，不会自动建立深层关系。你需要主动“教”它。例如，在文档里写一句：“这份 PRD 是 Nexus 产品的官方技术规范”，这句话里的“是...规范”关系，会被实体识别 Agent 捕捉，并在图谱中创建(PRD-node)-[is_specification_of]->(Nexus-node)边。之后，你问“Nexus 的技术规范是什么？”，就能得到准确答案。

• 全局记忆（Global Memory）：这是跨项目的“常识库”。如果你发现不同 WorkSpace 的 Agent 对同一个概念（如“公司使命”）回答不一致，说明这个概念没有被录入全局记忆。解决方案是：在任意一个 WorkSpace 中，创建一个docs/company-mission.md文件，内容为公司使命宣言，然后在命令栏输入/add-to-global-memory，系统会将其作为ent-company节点及其属性，同步到所有 WorkSpace 的全局记忆中。

实操心得：我给自己定了一个铁律——任何需要被记住超过 5 分钟的信息，必须用自然语言写成一句话，并明确包含主语、谓语、宾语，然后提交给 PilotDeck。例如，不说“记得联系张三”，而说“张三负责 Nexus 项目的前端开发，联系方式是 [e-mail]”。前者是模糊指令，后者是可被图谱解析的结构化事实。坚持两周，你的 Agent 就会变得无比靠谱。

5.3 技能执行超时：如何优雅地处理一个需要 10 分钟的长任务？

PilotDeck 的默认 5 秒超时，是为了保证 UI 的流畅性。但对于数据清洗、大模型微调、视频转录等长任务，需要特殊处理。

正确做法：使用异步任务队列（Async Task Queue）。

1. 在manifest.json中，将技能的execution_mode设为"async"。
2. 技能代码中，不再直接返回结果，而是调用pilot.task.queue()，传入一个任务描述对象：

{ "type": "video_transcribe", "input_file": "/docs/meeting.mp4", "output_format": "srt" }

3. PilotDeck 的主进程会将此任务加入一个持久化的 SQLite 任务队列，并立即返回一个task_id给用户。
4. 用户可以在 UI 的“任务中心”看到该