从零到精通：PiDeck 终极全景深度指南

本文是一篇按使用阶段层层递进的系统性指南：从入门篇（概念心智与安装）、上手篇（基础操作与高频工作流）、进阶篇（底层机制、性能指标、安全与扩展），一路走向开发定制篇（自建插件与本地开发）与贡献篇（从 Issue 到 PR 规范）。无论你是零基础小白、重度效率开发者，还是希望参与 PiDeck 开源贡献的工程师，都可以按需阅读对应章节。

第一部分：入门篇 —— 核心认知与环境铺设
第二部分：上手篇 —— 核心操作与高频工作流
第三部分：进阶篇 —— 底层原理、指标度量与安全黑科技
第四部分：开发与定制篇 —— 扩展技能开发与工程架构
第五部分：开源贡献与 PR 落地指南

第一部分：入门篇 —— 核心认知与环境铺设

1.1 为什么需要 PiDeck？它与 pi、Cursor、Claude Code 有何不同？

在当下的 AI 辅助编程领域，开发者通常面临两个极端的体验：

纯终端命令行工具（如 pi 原生 CLI、Claude Code）：
- 优点：极轻量、极贴合开发者环境、底层工具执行能力极强。
- 痛点：多项目来回切目录繁琐、长输出翻滚困难、无法直观查看代码改动 Diff、历史会话查找困难、缺乏直观的文件树与可视化回滚。
重型专有 IDE（如 Cursor、Windsurf）：
- 优点：界面开箱即用、交互集成度高。
- 痛点：需要迁移整个开发工作区、编辑器本身较为笨重、底层 Agent 行为与 Prompt 通常是黑盒、高度绑定其专属服务与收费策略。

PiDeck 的定位是“轻量强大的桌面工作台”：

它不是另外造一个 IDE，也不是 pi 的修改分叉（Fork）。
它是一个纯粹面向本地项目工作区的管理中枢：让你在同一个桌面应用窗口中，同时组织管理十几个本地项目的 Agent，提供图形化的会话时间线、直观的 Git 改动查看、免污染的版本回滚、多模型可视化切换以及内置终端与浏览器。

1.2 核心心智模型：pi 与 PiDeck 的职责边界与配置共用

理解 PiDeck 的第一步，是建立清晰的系统边界心智。

┌────────────────────────────────────────────────────────┐
│                        PiDeck                          │
│   (桌面宿主 / 窗口管理 / 会话浏览 / Git / 终端 / 配置界面)      │
└──────────────────────────┬─────────────────────────────┘
                           │
             stdio JSON-RPC 标准输入输出通信
             (禁止引入 HTTP/第二条通信通道)
                           │
┌──────────────────────────▼─────────────────────────────┐
│                          pi                            │
│  (核心 Agent 引擎 / 工具调用 / LLM 交互 / JSONL 会话持久化)  │
└────────────────────────────────────────────────────────┘

pi 负责什么？ 负责 Agent 的“大脑与双手”：提示词组装、模型调用、会话历史写入（.jsonl）、工具执行（read、edit、write、bash）以及扩展运行。
PiDeck 负责什么？ 负责桌面外壳与开发者体验：进程守护、多项目树展示、会话 Tab 多开与分屏、富文本输入框与语法高亮、Git 提交与分支切换、终端与浏览器内嵌。
配置与数据共用机制（不重复建轮子）：
- 全局配置目录：统一读取 ~/.pi/agent/ 下的 models.json（模型端点）、auth.json（API 密钥）、settings.json（CLI 行为）以及 skills/、extensions/。
- 项目级配置目录：特定项目根目录下的 .pi/ 目录。
- 会话持久化：所有的聊天记录均存储在 ~/.pi/agent/sessions/*.jsonl。你在终端用 pi 命令聊过的历史，在 PiDeck 侧栏打开立即可见；你在 PiDeck 里的会话，在终端随时可以 pi --resume 继续执行。两者是完全同源的同一个数据体。

1.3 安装准备与环境配置（Windows / macOS / Linux）

步骤一：安装底层引擎 pi

由于 PiDeck 的底层 Agent 运行依赖系统中的 pi 命令，请先确保已在系统中安装了 Node.js（推荐 Node 20+），并在终端中全局安装 pi：

bash

# 全局安装 pi coding agent
npm install -g @earendil-works/pi-coding-agent

# 验证安装是否成功（能输出版本号即表示就绪）
pi --version

步骤二：下载并运行 PiDeck 客户端

从 GitHub Releases 下载适合操作系统的安装包：

Windows：推荐下载 PiDeck-Setup-x.x.x.exe（支持自动静默检查更新）或绿色免安装便携版 PiDeck-x.x.x.zip。
macOS：
- Apple Silicon 芯片（M1/M2/M3/M4）：下载 PiDeck-x.x.x-arm64.dmg。
- Intel 芯片：下载 PiDeck-x.x.x-x64.dmg。
Linux：下载 PiDeck-x.x.x.AppImage（直接赋予执行权限运行）或 PiDeck-x.x.x.deb。

1.4 首次启动与环境自检

打开 PiDeck 后，应用会在几百毫秒内完成系统环境检测：

自动检测 pi 路径：
- 检查系统 PATH 环境变量中是否存在 pi。
- 如果系统未正确将 npm 全局目录加入 PATH，PiDeck 会在界面上方弹出黄色环境提醒。
手动指定 pi 路径：
- 点击左下角齿轮 ⚙️ 打开【设置】。
- 切换到【常用设置】→【运行环境】，在“自定义 pi 执行文件路径”中输入绝对路径，例如：
  - Windows：C:\Users\<你的用户名>\AppData\Roaming\npm\pi.cmd
  - macOS / Linux：/usr/local/bin/pi 或 ~/.nvm/versions/node/.../bin/pi
- 保存后点击旁边的“测试”，绿色对勾亮起即表示连接成功。
配置你的第一个模型：
- 进入【设置】→【Auth】页面，找到或新增你常用的供应商（如 DeepSeek、Anthropic、OpenAI、SiliconFlow、OpenRouter 或自定义中转站点）。
- 填入你的 API Key，随后在【Models】页面即可测试模型连通性。

第二部分：上手篇 —— 核心操作与高频工作流

2.1 项目工作区与多会话管理

进入 PiDeck 主界面后，左侧栏是你的工作区中枢：

┌──────────────────────────────────────┐
│  PiDeck  [+][🔍]                    │
├──────────────────────────────────────┤
│  [活动 (2)]  [聊天]  [项目 (5)]       │
├──────────────────────────────────────┤
│  ▼ 📁 my-web-app                     │
│    ├── 💬 重构登录鉴权模块 (黄点:运行中) │
│    ├── 💬 修复支付回调并发 bug         │
│    └── ➕ 新建会话                    │
│  ▶ 📁 backend-api                    │
└──────────────────────────────────────┘

添加本地项目：
- 点击左侧栏顶部的 + 按钮，或在项目空白处点击“添加项目”，选择本地磁盘中的 Git 或代码目录。
会话 Tab 预览与常驻体系（对齐现代编辑器直觉）：
- 单击会话：以**临时预览（Preview）**模式在中央区域打开（Tab 标题为斜体）。继续点其他会话会替换当前 Tab，不会让顶部堆满标签。
- 双击会话 或 在预览会话中发送新消息：自动将该 Tab 晋升为**常驻（Permanent）**固定状态。
创建分屏（Split Screen）：
- 想要一边看着接口设计文档的对话，一边在右侧让 Agent 修改前端页面？
- 按住会话 Tab 或侧栏会话行，拖拽到中央区域的右侧边缘或底部边缘，即可立即划分为左右或上下并排分屏！两栏会话完全独立，状态与更新互不干扰。

2.2 输入框（Composer）的高效使用指南

PiDeck 的输入框基于 TipTap 深度定制，不仅支持纯文本输入，还融合了多种上下文引用与交互捷径：

快捷输入方式	效果与使用时机	示例
`@` 文件引用	快速弹出项目文件模糊搜索列表，回车插入文件路径 Chip。Agent 收到后会自动优先读取此文件的精确上下文。	`@src/auth/jwt.ts`
`&` 历史消息引用	快速搜索并引用历史会话中的某条重要决策或代码块，自动提取关键引用上下文。	`&重构规范`
拖拽/粘贴图片	直接把设计稿截图、报错弹窗截图 Ctrl+V 粘贴进输入框。即使你使用的是无视觉能力的 DeepSeek 模型，内置的 Vision 扩展也会自动将其翻译为高保真技术细节描述给模型！	粘贴报错截图
粘贴超长代码/日志	粘贴超过 2KB 的巨大日志或文本时，系统会自动将其转化为临时文件 Chip 挂载在附件栏，避免几万行字符直接塞满输入框。	粘贴巨大日志
上下方向键历史轮巡	当光标在输入框首行按 `↑`，或末行按 `↓`，可快速循环调出你曾经发送过的历史 Prompt。	按 ↑ 找回上条指令

2.3 任务执行模式切换：普通、规划（Plan）、目标（Goal）与生图

在输入框左下角，有一个模式切换小药丸（默认显示为一个小扳手）：

普通模式（Normal Mode）：
- 默认模式。模型拥有完整的 read、edit、write、bash 权限，收到指令后直接边思考边写代码。
规划模式（Plan Mode - 推荐给重大重构）：
- 图标为勾选清单。
- 机制：内置扩展会暂时剥夺模型的写权限（禁用 edit / write，拦截修改类 bash 命令），强制模型只读审查代码并输出详细的 Plan: 分步执行规划清单。
- 生成后，桌面端会弹出一个批准面板：用户确认方案可行并点击【执行】后，才放行写操作并分步勾选代办执行，杜绝模型“上来就一顿乱改”。
目标模式（Goal Mode - 自动化持续推进）：
- 图标为靶心。
- 机制：用户给定一个终极目标（例如：“给项目补充所有缺失的单元测试直到覆盖率达到 85%”）。
- Agent 每跑完一轮工具调用，扩展会自动触发续轮，自我检查结果并继续执行下一步，直到最终输出 GOAL_COMPLETE 达成目标才停止，无需用户每轮手动按回车继续。
生图模式（ImageGen）：
- 图标为图片。用于针对视觉生图模型的专属交互界面。

2.4 Git 面板与分支工作区（Worktree）协同

在中央区域的右侧抽屉中，点击分支图标可展开 Git 工作台：

实时状态追踪：实时展示当前分支、未暂存改动（Unstaged）、已暂存改动（Staged）。
行级 Diff 审查：点击任意文件即可查看前后改动高亮，确认 AI 生成的每一行代码是否符合预期。
一键 AI Commit：输入框支持一键让大模型根据当前的 git diff 自动生成符合规范的语义化提交信息。
分支工作区（Worktree）并行开发：
- 当你在做主功能开发，线上突然来了紧急 Bug 需要基于 hotfix 分支修改时：
- 在左侧栏项目上右键选择【新建工作区】，输入分支名。PiDeck 会利用 Git Worktree 在本地拉出一个互不影响的独立文件夹副本。你可以在不 stash、不切分支、不中断当前 Agent 会话的情况下，同时在另一个窗口修复 Bug！

2.5 辅助效率武器：内置终端、内置浏览器与草稿本（ScratchPad）

底栏内置终端 Dock：
- 点击会话 Tab 栏右上角或按快捷键打开底部终端。
- 支持 PowerShell、CMD、Bash、Zsh、WSL。每个 Agent 或项目可绑定专属终端 Tab，切换会话自动联动，随时执行构建或启动本地服务。
右侧抽屉内置浏览器（Browser Panel）：
- 不需要频繁在 Chrome 和 PiDeck 之间来回 Alt+Tab。
- 右侧抽屉点击地球图标打开内置浏览器，输入 http://localhost:3000 实时查看前端开发效果。
- 支持切换设备预设（PC / iPhone / iPad），支持独立沙箱隔离，安全轻快。
临时草稿本（ScratchPad）：
- 按 Ctrl/Cmd+Shift+S 随时拉起右侧草稿本，用于随手暂存 API 格式、临时笔记或稍后要发给 AI 的灵感提示词。

第三部分：进阶篇 —— 底层原理、指标度量与安全黑科技

3.1 输入框各种性能指标与计算原理（谁算的？怎么算的？）

很多进阶用户非常关心：输入框下面的各种耗时、Tokens、TPS 是真实的吗？是 pi 算的还是 PiDeck 算的？

  ┌──────────────────────────────────────────────────────────────┐
  │ 8 轮 · 16 步 | LLM 12.4s · 工具 3.1s | 首字 450ms · 52 tps   │
  │ | 缓存 85% | 输入 24.5K · 输出 3.2K                          │
  └──────────────────────────────────────────────────────────────┘

指标来源与计算口径对比

界面指标项	计算公式 / 算法细节	数据归属（谁算的？）	业务工程意义
轮数 (Turns)	统计该会话中用户输入条目的总数（以发言周期为口径）。	PiDeck 统计 (pi 模式) DSH 投影 (DSH 模式)	衡量用户与 AI 针对该任务的往返交互深度。
步数 (Steps)	DSH 官方投影完成的原子执行步数（LLM 推理 + 单次工具调用）。	DSH 上报	真实反映 Agent 在底层拆解执行了多少个动作。
首字时延 (TTFT)	从发送消息到从模型流式通道接收到首个文本/思考 Token 的耗时（ms）。	模型与 pi 协同记录（存于 `runtimeState.ttftMs`）	衡量供应商网关响应延迟与大模型排队用时。低于 800ms 为优秀。
回合总耗时 (Total)	当前轮次从触发到彻底收尾（`agent_settled`）的累计墙钟总时间。	pi 上报 (`totalMs`)	了解复杂任务的执行总效率。
生成吞吐率 (TPS)	`TPS = outputTokens / (totalMs - ttftMs)`	PiDeck 计算	真实输出速率。剔除首字网络排队时间，纯粹衡量该模型每秒能生成多少 tokens。
缓存命中率 (Cache Hit %)	`cacheRead / (cacheRead + cacheWrite) * 100%`	pi 根据 API 响应统计	提示词缓存（Prompt Caching）的利用效率。命中率达到 80%+ 时，API 费用通常降低 70%~90%，且首字响应极快。
输入 / 输出 Tokens	对每轮 API 真实返回的 `prompt_tokens` 与 `completion_tokens` 累加。	模型 API 上报	紧凑格式化（<1K 直接显示数字，<1M 显示 12.4K，≥1M 显示 1.2M）。

3.2 上下文占用圆环与压缩（Compaction）深层机制

上下文圆环（ContextMeter）是如何工作的？

占用百分比：percent = contextTokens / contextWindow * 100%。
- contextTokens 来自模型每次交互后实际占用的 Token 总体积；contextWindow 来自 models.json 配置的模型窗口上限。
两段/三段图例解析：
- pi 模式（两段）：系统与工具指令占比（紫色） vs 实际对话历史占比（蓝色）。由于 pi 接口不细分 prompt 构成，PiDeck 在主进程按消息字符折算估算对话，准确率高达 95% 以上。
- DSH 模式（三段）：系统提示（蓝灰） + 工具定义（紫） + 会话对话（蓝）。

压缩（Compaction）背后的原子操作

当对话太长时，必须进行压缩：

进程所有权判定：优先向正在运行该会话的 pi 进程发送 session/compact 指令。
截断与折叠：pi 提取 firstKeptEntryId 之前的所有老会话内容，调用当前模型提炼一份自包含的任务执行进展摘要，老消息在传输上下文中被折叠，由一条 compaction 摘要替代。
零前缀破坏的 Todo 状态重注入：
- 传统压缩会把 AI 的 Todo 代办清单一起冲掉，导致压缩后 AI 忘记要做什么。
- PiDeck 的内置 pi-deck-todo 扩展具备专利级的零缓存破坏设计：压缩完成后，检测到最后代办点比压缩点老，会在新起点自动追加一条持久化的代办简报，既让 AI 完美找回任务上下文，又不破坏提示词的前缀缓存（Prompt Cache）！

3.3 Agent 运行状态机与空闲释放（Idle Releaser）

每个会话背后绑定的 Agent 进程具备严密的生命周期状态机：

   [unstarted]
        │
   (用户发送消息)
        ▼
   [starting] ──(启动失败)──► [error]
        │
    (连接就绪)
        ▼
 ┌──► [idle] (蓝色小圆点：就绪等待)
 │      │
 │  (收到指令)
 │      ▼
 └─── [running] (黄色呼吸点：思考/执行工具中)
        │
  (超时无操作且切至后台)
        ▼
   [detached] (资源回收休眠，切回时秒级自愈复苏)

空闲自动释放（Idle Agent Releaser）：
- 如果一个 Agent 闲置超过设定时长且用户窗口不在该会话上，系统自动向子进程下发优雅退出信号，释放占用的大量 V8 堆内存与句柄。
- 当你在左侧栏重新点开这个会话时，PiDeck 会在 300 毫秒内原地重新拉起进程并恢复历史，体验丝滑无感。

3.4 消息队列、忙碌投递与 BTW（顺便说一句）

当 Agent 正在执行长任务时，你敲下文字并点击发送，会发生什么？这取决于 设置 → 会话管理 → 忙碌时发送 的策略配置：

插入当前回合（Steer - 默认推荐）：
- 系统将该消息标记为 behavior: "steer"，通过标准输入实时注入当前 Agent 的执行流。
- Agent 会在下一个工具调用结束后立刻读取到你的输入：“用户发来了紧急修正，暂停刚才的操作，改用新的方案”。
排队等待（Queue / Follow-Up）：
- 消息进入输入框上方的独立卡片【排队消息面板】。
- 最大允许排队 10 条消息。
- 每一条排队消息你都可以随时点击：
  - 撤回：取回输入框重新修改。
  - 切换：就地从“排队”变更为“立即插话”。
  - 丢弃：直接取消。
- 当 Agent 当前回合彻底结算（agent_end）后，系统按顺序自动投递下一条。

3.5 零损坏检查点（Rewind Checkpoints）安全回滚体系

“AI 改乱了代码，改了哪些文件记不清了，怎么彻底还原？” PiDeck 内置了基于 Git 专有引用的轻量快照系统（移植自 pi-rewind）。

快照是怎么打的？

零分支污染：快照不产生任何用户可见的 git commit 或新分支，而是写在低层引用 refs/pi-checkpoints/<id> 中。
全状态打包：不仅保存已 commit 的 HEAD 树和暂存区 Index 树，还利用临时索引将**未跟踪的新建文件（Untracked Files）**一并封存进快照。
触发点：
- 每一轮对话开始前自动打点。
- 模型执行 write、edit 等可能破坏文件的工具前自动打点。
- 用户在点击“恢复”前的一瞬间，系统会自动生成一个 before-restore 快照（保证回滚本身也能后悔）。

安全恢复策略（Safe Clean）

在检查点面板点击回滚时：

分支守卫：检查当前工作区是否仍在打快照时的同一 Git 分支上，防止跨分支误回滚。
智能清理垃圾：仅删除“在快照之后由 AI 凭空新建的未跟踪文件”；快照前就已经存在的文件、被 .gitignore 忽略的文件、超过 10MB 的大文件都会受到严格保护，绝不误伤用户原有资产。

3.6 外部会话无缝导入：Cursor、Claude、OpenCode、Codex

在左侧栏项目右键点击【导入会话】，你可以把其他工具的历史资产一键平移到 PiDeck：

Cursor：从 VSCode 的 SQLite state.vscdb 数据库中提取聊天历史树。
Claude Code：解析 ~/.claude/sessions/ 下的 JSONL 文件。
OpenCode / Codex：解析对应的会话结构。

结构归一化器（Import Normalize）：由于各家工具记录工具调用（Tool Calls）的结构完全不同，PiDeck 的导入器会自动将 Cursor/Claude 的自定义参数解析为通用的 read / edit / bash 结构，并生成标准 JSONL 写入 ~/.pi/agent/sessions/，导入后可以直接在 PiDeck 里浏览富文本 Diff，甚至继续对话！

3.7 全链路网络代理架构：桌面端代理 vs 会话代理 vs DSH 代理

遇到国外大模型连接超时或需要内网穿透？PiDeck 将代理清晰地分为三层：

                ┌───────────────────────────────┐
                │          桌面端代理            │
                │ (影响渲染进程、内置浏览器、更新检测)│
                └──────────────┬────────────────┘
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│     pi 子进程代理      │             │       DSH 代理        │
│ (按环境变量注入子进程)  │             │ (注入 NODE_USE_ENV_   │
│ - 支持单个会话右键覆盖   │             │  PROXY 使 undici 生效) │
│ - 支持按模型白名单直连   │             └───────────────────────┘
└───────────────────────┘

桌面端代理（Desktop Proxy）：
- 仅负责桌面客户端本身发起的请求（如拉取版本更新、内置浏览器访问网页、测试模型联通）。
- 关键设计：关闭该代理时，PiDeck 绝不强制写死 direct，而是设置为 Chromium 的 system 模式（沿用用户操作系统的网络出口），防止关掉开关反而导致电脑原有网络断开。
pi 子进程代理（Pi Proxy）：
- 通过在启动 pi 子进程时注入 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 环境变量实现。
- 单会话覆盖：在会话右键菜单选择【会话代理】，可以单独指定某个会话必须直连（如访问本地部署的 Ollama）或必须走代理。
- 模型白名单：在设置中支持配置仅让指定的模型走代理，其余国内模型自动直连。
DSH 代理（NODE_USE_ENV_PROXY）：
- DSH 宿主运行在 Electron 的 utilityProcess 内，其 LLM 客户端使用 Node 内置的 undici。
- 默认情况下 Node 的 fetch 是不读取 HTTP_PROXY 环境变量的！PiDeck 在底层强制注入了 NODE_USE_ENV_PROXY=1，确保 DSH 会话的代理能够真实生效。

3.8 十三大内置官方扩展（插件）全景工作原理

随包分发的 13 个内置扩展（位于 resources/extensions/）在启动时通过 -e 注入 pi 进程，默默守护着你的开发体验：

pi-deck-ask-question.ts（结构化提问）：
- 当模型有选择题需要向你确认时，拦截交互并在桌面端弹出一个优雅的 Tab 选项卡（单选、多选、确认、自由输入、多行编辑）。用户点选后把结构化数据精准回传，告别在文字里反复确认。
pi-deck-todo.ts & pi-deck-todo-state.ts（任务持久化）：
- 维护一个分支级别的任务计划状态机。具有极佳的缓存友好度：代办变更作为工具结果追加，对模型的前缀缓存零打扰；压缩后自动补注简报。
pi-deck-plan-mode.ts（规划模式管控）：
- 在 Plan 模式下封锁 edit/write 工具和破坏性 bash，强制模型给出分步计划，待用户确认后放行。
pi-deck-goal-mode.ts（目标模式自动续轮）：
- 监听 agent_end 事件，只要未达成 GOAL_COMPLETE 或 GOAL_BLOCKED，自动发起 followUp 续轮执行。
pi-deck-security-gate.ts（安全防护网）：
- 拦截 rm -rf、chmod 777、git push 等高危命令，限制访问目录范围，保护 .env 与系统密钥。
pi-deck-trash-guard.ts（回收站守卫）：
- 安全气囊：不管模型执行了多么暴力的 rm -rf，本扩展在命令真正执行前，会悄悄调用操作系统原生能力（Windows PowerShell/macOS AppleScript/Linux gio）把将要删除的文件复制一份送进系统回收站/废纸篓！代码被误删也能一秒找回。
pi-deck-vision.ts（视觉桥）：
- 当使用不支持图片的代码模型（如 DeepSeek）时，在后台静默调用轻量视觉模型将图片转为高精度技术描述文字无缝注入，让纯文本模型也能看懂页面截图。
pi-deck-retry-no-body.ts（瞬态报错智能重试）：
- 中转网关偶发返回的 400 (no body) 或中文 模型服务暂时不可用 会被原生 pi 误认为不可重试。本扩展改写错误标识，触发 pi 内置的指数退避自动重试，防止任务夭折。
pi-deck-request-size-recovery.ts（413 超长请求救援）：
- 当会话太长撞上网关 413 Payload Too Large 导致连压缩请求都发不出去时，自动弹出救援框，引导临时切换到大窗口模型执行一次瘦身压缩。
pi-deck-session-title.ts（智能命名）：
- 首轮对话结束后，在后台异步启动最小上下文，根据你的第一条真实诉求生成精炼的中文会话标题（如“实现 JWT 登录中间件”）。
pi-deck-subagents.ts（子 Agent 桥接）：
- 监听所有子 Agent 的派发、运行、消耗 tokens、耗时与结果，推送到输入框上方的子任务卡片。
pi-deck-nul-redirect-fix.ts（Windows 设备名修复）：
- 将 Windows Git Bash 下会导致生成恶性残留文件的 > nul 底层改写为 > /dev/null。

3.9 跨端联动与桌面宠物：飞书机器人与局域网 Web 服务

飞书机器人集成（Feishu Bridge）：
- PiDeck 允许将本地 Agent 挂载到飞书自定义机器人上。
- 手机在路上用飞书给机器人发消息，请求会穿透到你电脑上的 PiDeck 本地执行改代码，并通过卡片实时流式把进度回传到手机。
- 当绑订飞书时，pi-deck-ask-question 插件会自动将界面弹框降级为文本回复，保证跨端交互不卡死。
局域网 Web 实时预览（Web Service）：
- 开启 Web 服务后，手机或同局域网平板扫描二维码，即可在手机浏览器中实时查看当前桌面的 Agent 执行时间线和代码生成。
桌面宠物（Desktop Pet）：
- 可在设置开启一只贴着屏幕边缘的萌宠，随着 Agent 的思考、工具调用、完成或报错呈现不同的生动动效。

第四部分：开发与定制篇 —— 扩展技能开发与工程架构

4.1 PiDeck 源码架构全景（Electron + React 19 + TypeScript + Jotai）

如果你是一名开发者，希望通读 PiDeck 源码或为它添砖加瓦，请牢记它的模块层级与跨层契约：

src/
├── shared/           # 跨进程纯契约层 (shared/types/*.ts 声明数据结构，shared/ipc.ts 声明通道)
├── main/             # Electron 主进程 (唯一可调用 Node/系统 API 的层)
│   ├── pi/           # pi RPC 进程守护、消息流解析
│   ├── sessions/     # 会话扫描、导入、增量缓存与协调器
│   ├── git/          # GitService (Diff/Commit/Worktree)
│   ├── settings/     # 桌面设置存储与代理应用
│   └── ipc/          # 域拆分的 IPC Handlers (sessionIpc, gitIpc, settingsIpc...)
├── preload/          # ContextBridge 最小安全通道暴露 (不写任何业务逻辑)
└── renderer/src/     # React 19 渲染层
    ├── atoms/        # 全局状态管理 (Jotai，按域拆分 atoms)
    ├── components/   # UI 原语 (ui-shadcn/) + 业务组件 (session/, workspace/)
    ├── hooks/        # 业务状态逻辑收敛 (useSessionComposerController 等)
    └── styles/       # Tailwind v4 + 语义设计 Token

架构红线

Session-First：所有状态流转优先围绕 sessionId 聚合，严禁在多会话并排时使用单一的全局当前会话状态。
单向依赖链：renderer → preload → main；三者仅共享 shared/ 契约；主进程 handler 必须校验入参；渲染层禁止直接 import Node/Electron 模块。
文件体量红线：单文件目标 ≤ 400 行，超过 600 行必须重构拆分；App.tsx 和 main/index.ts 只做装配，不写业务逻辑。

4.2 本地运行、调试与跨层 IPC 契约

快速启动本地源码

bash

# 克隆仓库
git clone https://github.com/ayuayue/PiDeck.git
cd pi-desktop

# 安装依赖
npm install

# 准备图标产物
npm run make-icon

# 启动本地开发模式 (Vite HMR + Electron 自动重启)
npm run dev

跨层 IPC 新增步骤（三处同步原则）

在 src/shared/ipc.ts 声明新的通道字符串常量（格式 domain:action）。
在 src/main/ipc/*Ipc.ts 中注册 ipcMain.handle 处理器，严格校验入参类型与路径合法性。
在 src/preload/index.ts 中向 desktopApi 添加对应的方法映射与 TypeScript 类型声明。

4.3 如何为 pi 开发自定义插件与 Skill

1. 自定义 Skill（技能）

Skill 是一套指导 Agent “在特定场景下如何思考与调用工具”的 Markdown 说明书。

全局生效：放在 ~/.pi/agent/skills/<skill-name>/SKILL.md。
项目生效：放在项目根目录 .pi/skills/<skill-name>/SKILL.md。

结构规范：

markdown

---
name: git-commit-helper
description: 当用户要求提交代码时使用此技能生成规范的 Conventional Commits
---
## When to Use
当用户输入 commit、提交代码时触发。

## Procedure
1. 运行 git status 查看暂存区文件。
2. 针对变更输出 type(scope): subject 结构的提交信息。

2. 自定义 Extension（扩展）

Extension 是基于 Node.js/TypeScript 编写的具备真实钩子能力的逻辑模块：

放置位置：~/.pi/agent/extensions/*.ts 或项目下 .pi/extensions/*.ts。

编写规范：

typescript

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function myExtension(pi: ExtensionAPI): void {
  // 监听工具调用
  pi.on("tool_call", async (event, ctx) => {
    if (event.tool === "bash" && event.params.command.includes("rm -rf")) {
      console.log("检测到危险操作！");
    }
  });

  // 注册自定义扩展工具供模型使用
  pi.registerTool({
    name: "query_database",
    description: "查询本地开发数据库",
    parameters: { /* JSON Schema */ },
    execute: async (args) => {
      return { result: "ok" };
    }
  });
}

4.4 内置扩展热更新机制（userData 覆盖层）

内置扩展出了 Bug，难道必须等重新发版发安装包吗？ PiDeck 实现了优雅的热更新机制：

主进程通过 AtomGit / GitHub API 读取最新清单 extensions-manifest.json。
逐文件比对 SHA-256 哈希值。
当检测到更新时，将新文件原子写入 <userData>/builtin-extensions/ 覆盖层，并自动携带打包好的 node_modules 运行时依赖。
下次启动或重启会话时，PiDeck 会优先加载覆盖层扩展，实现零版本发布的秒级 Bug 修复！

第五部分：开源贡献与 PR 落地指南

我们热烈欢迎每一位热爱开源、热爱 AI 工具的开发者参与贡献！为了保持工程质量与协作顺畅，请遵循以下约定。

5.1 参与贡献原则与代码风格规范

测试先行与门禁（日常针对跑，严禁放宽断言）：
- 修复 Bug：先在 tests/ 编写一个能稳定复现的失败单测（红），再修改代码直至变绿。
- 每次代码提交前，必须通过 TypeScript 类型检查：
  bash
```
npm run typecheck
```
- 运行本次改动相关的针对性单测：
  bash
```
node --test tests/你的单测.test.mjs
```
代码风格与规范：
- 全面启用 TypeScript strict。严禁随意新增 any 或使用 as 强转绕过类型检查。
- 跨组件状态一律使用 Jotai atom，严禁再开第二套状态方案。
- 所有用户可见文案必须录入国际化字典：rendererCopy.zh-CN.ts 与 rendererCopy.en-US.ts，禁止在 JSX 中硬编码中英文文本。
- 新增 UI 优先复用 components/ui-shadcn/ 基础原语与 Tailwind utility，不新增手写 CSS 类名。

5.2 提交 Commit 守则与长期重构纪律

AI 助手与开发者的 Commit 约束：
- 不要自以为是地自动提交代码。只有明确要求提交或完成整套功能自检绿灯后，再执行 git commit。
- 一个独立功能或 Bug 修复对应一个 Commit，避免产生几十个散落的“fix typo”微小提交。
Commit 信息规范：
- feat: 增加会话历史来源筛选器
- fix: 修复中转站 413 请求体超限时的压缩恢复逻辑
- docs: 更新原理解析与开发指南
- chore: release v0.7.7

5.3 从 Issue 到 PR 的完整标准流程

在 GitHub 上 Fork 仓库：
- 将 https://github.com/ayuayue/PiDeck Fork 到你的个人账号。
检出开发分支：
- 基于主仓库的 main（或进行中的开发分支）拉出你的功能分支：
  bash
```
git checkout -b feat/your-feature-name
```
本地开发与测试自检：
- 完成功能编写与针对性单测补充。
- 运行 npm run typecheck 确认通过。
- 如改动涉及构建脚本，运行 npm run build 或 npm run pack 进行基本构建冒烟测试。
发起 Pull Request (PR)：
- 推送分支到你的 GitHub 远端仓库。
- 在 GitHub 上向 PiDeck 的主仓库提交 PR。
- 在 PR 描述中清晰写明：
  - 改动原因：解决了什么问题或满足了什么需求（如 Closes #123）。
  - 核心变动摘要：修改了哪些模块与跨层契约。
  - 验证方式：你运行了哪些自动化测试或进行了哪些手动操作验证。
CR 评审与合并：
- 核心维护者会对 PR 进行代码审查与自动化 CI 门禁检查，通过后将被正式合并进主干并在下一个版本中打包发布，你的名字也会自动收录进贡献者光荣榜！

从零到精通：PiDeck 终极全景深度指南 ​

目录 ​

第一部分：入门篇 —— 核心认知与环境铺设 ​

1.1 为什么需要 PiDeck？它与 pi、Cursor、Claude Code 有何不同？ ​

1.2 核心心智模型：pi 与 PiDeck 的职责边界与配置共用 ​

1.3 安装准备与环境配置（Windows / macOS / Linux） ​

步骤一：安装底层引擎 pi ​

步骤二：下载并运行 PiDeck 客户端 ​

1.4 首次启动与环境自检 ​

第二部分：上手篇 —— 核心操作与高频工作流 ​

2.1 项目工作区与多会话管理 ​

2.2 输入框（Composer）的高效使用指南 ​

2.3 任务执行模式切换：普通、规划（Plan）、目标（Goal）与生图 ​

2.4 Git 面板与分支工作区（Worktree）协同 ​

2.5 辅助效率武器：内置终端、内置浏览器与草稿本（ScratchPad） ​

第三部分：进阶篇 —— 底层原理、指标度量与安全黑科技 ​

3.1 输入框各种性能指标与计算原理（谁算的？怎么算的？） ​

指标来源与计算口径对比 ​

3.2 上下文占用圆环与压缩（Compaction）深层机制 ​

上下文圆环（ContextMeter）是如何工作的？ ​

压缩（Compaction）背后的原子操作 ​

3.3 Agent 运行状态机与空闲释放（Idle Releaser） ​

3.4 消息队列、忙碌投递与 BTW（顺便说一句） ​

3.5 零损坏检查点（Rewind Checkpoints）安全回滚体系 ​

快照是怎么打的？ ​

安全恢复策略（Safe Clean） ​

3.6 外部会话无缝导入：Cursor、Claude、OpenCode、Codex ​

3.7 全链路网络代理架构：桌面端代理 vs 会话代理 vs DSH 代理 ​

3.8 十三大内置官方扩展（插件）全景工作原理 ​

3.9 跨端联动与桌面宠物：飞书机器人与局域网 Web 服务 ​

第四部分：开发与定制篇 —— 扩展技能开发与工程架构 ​

4.1 PiDeck 源码架构全景（Electron + React 19 + TypeScript + Jotai） ​

架构红线 ​

4.2 本地运行、调试与跨层 IPC 契约 ​

快速启动本地源码 ​

跨层 IPC 新增步骤（三处同步原则） ​

4.3 如何为 pi 开发自定义插件与 Skill ​

1. 自定义 Skill（技能） ​

2. 自定义 Extension（扩展） ​

4.4 内置扩展热更新机制（userData 覆盖层） ​

第五部分：开源贡献与 PR 落地指南 ​

5.1 参与贡献原则与代码风格规范 ​

5.2 提交 Commit 守则与长期重构纪律 ​

5.3 从 Issue 到 PR 的完整标准流程 ​