PiDeck AGENTS.md

AGENTS.md

项目简介

PiDeck 是一个面向本地开发工作的 Electron 桌面应用，用于在多个项目目录之间管理和运行 pi RPC Agent。应用提供多项目工作区、会话时间线、历史会话恢复、文件抽屉、Git 面板、模型选择、工具调用展示、内置浏览器、中文提示词精选、技能/扩展商店以及打包发布能力，目标是让用户可以在桌面端更稳定地管理多个 pi 编码助手会话。

技术栈：Electron 38 + React 19 + TypeScript + Vite。

核心边界（不可逾越）：

• pi 负责 Agent 行为、工具调用、会话读写、模型调用 —— pi 的事不要替它做。
• PiDeck 负责窗口管理、进程生命周期、会话浏览/导入、Git 面板、终端、设置 —— UI 框架的事 pi 也不要做。
• 两者通过 stdio JSON-RPC 通信，禁止引入第二条通信通道（如直接 HTTP 到 pi 内部）。

代码结构与跨层契约

本项目只维护项目根目录这一份 AGENTS.md；除非用户明确要求，不要再在子目录生成同名规则文件。docs/开发规范.md 中仍有历史架构表述，若与本文件或实际类型/API 冲突，以本文件和代码为准。

• src/shared/ 是跨进程纯契约层：共享类型按 shared/types/*.ts 拆分，shared/types.ts 仅做兼容导出；IPC 名称只定义在 shared/ipc.ts。
• src/main/ 是唯一可访问 Node/Electron 主进程能力的业务层。main/<domain>/ 拥有领域行为，main/ipc/*Ipc.ts 只做输入校验和适配，main/index.ts 只增装配，不新增业务。
• src/preload/index.ts 通过 contextBridge 暴露最小 PiDesktopApi；新增 IPC 必须同步共享通道、main handler、preload 方法三处，订阅 API 必须返回 unsubscribe。
• src/renderer/ 只通过 desktopApi/preload 调用桌面能力。跨组件状态使用 Jotai atom，副作用放 hook，视图放 component；不得直接 import Node/Electron 或新增第二种全局状态方案。
• SessionRecord.id 是跨重启的稳定会话身份，agentId 仅表示当前 pi 子进程。所有 runtime 命令和事件都必须带 sessionId + agentId + runtimeGeneration，拒绝旧 runtime 的迟到结果。
• pi 只通过 stdio JSON-RPC 与 PiDeck 通信；PiDeck 不复刻 pi 的 Agent/工具/会话行为，也不为访问 pi 引入第二条通信通道。
• 持久化结构、设置和 session catalog 变更必须兼容旧数据；listener、timer、子进程、terminal 和 watcher 必须在同一模块找到配对清理路径。

src/
├── main/              # Electron 主进程
│   ├── pi/            # pi RPC 进程管理、消息解析
│   ├── sessions/      # 会话扫描、导入、摘要缓存、SessionRuntimeCoordinator
│   ├── git/           # GitService（status/diff/commit/cherry-pick 等）
│   ├── prompts/       # PromptManager（本地模板）+ XuePromptManager（SQLite 中文精选）
│   ├── skills/        # SkillManager
│   ├── extensions/    # ExtensionManager
│   ├── settings/      # SettingsStore + DesktopProxy
│   ├── terminal/      # 终端会话管理（node-pty）
│   ├── pet/           # 桌面宠物
│   ├── feishu/        # 飞书集成（FeishuBridge + FeishuConnection）
│   ├── ipc/           # ★ IPC 域注册（sessionIpc/systemIpc/gitIpc/storeIpc/...）
│   └── web/           # Web 服务管理
├── preload/           # preload 脚本，经 contextBridge 暴露受限 IPC API
├── renderer/
│   └── src/
│       ├── atoms/         # Jotai 状态（session-first）
│       ├── components/
│       │   ├── ui-shadcn/  # 共享 UI 原语（button/dialog/input/select 等）
│       │   ├── session/   # 会话视图族（SessionView/Composer*/Timeline*）
│       │   ├── sidebar/   # 左侧栏
│       │   ├── workspace/ # 右侧抽屉（files/git/browser/editor）
│       │   └── app/       # 业务组件
│       ├── hooks/         # 渲染层 hooks（useWorkspacePanels/useSessionComposerController 等）
│       ├── i18n/          # 文案（zh-CN / en-US，rendererCopy.*.ts）
│       └── styles/        # 按域拆分的样式 + 语义 token
└── shared/            # 主/渲染共享类型（按域拆分）与 IPC 通道定义