iPolloWork Docs

本地开发

在 macOS、Linux 或 Windows 上启动真实的 iPolloWork 开发工作流。

仓库启动器是本地开发的唯一准则。它会准备工作区依赖，并将开发状态与普通 OpenCode Profile 隔离。

开发归属通过 Launcher 组装本地开发运行时

Launcher 让 UI、Electron Shell、Server 包和受支持 Sidecar 处于同一个检出版本。它比单独启动某一层、再猜测其余状态更可靠。

01
工作区

仓库级依赖与命令边界

pnpm Workspace

Apps 和共享 Packages 的锁定依赖。

仓库 Launcher

`ipollowork` 命令定义受支持的本地工作流。

02
客户端运行时

你看到并操作的部分

Vite 应用

桌面、浏览器和无头工作流复用的 React 工作界面。

Electron 开发 Profile

原生客户端使用的隔离数据和运行时 Profile。

03
执行运行时

真正完成工作的一层

Orchestrator 与 OpenCode

由 Launcher 为开发准备的受支持 Sidecar。

本地 Server

基于文件系统的工作区 API 与运行时适配器边界。

从仓库根目录启动。不要复制其他 Checkout 或普通用户 Profile 中的 Sidecar 配置。

环境要求

  • Git
  • Node.js 22 或更高版本
  • 通过 Corepack 启用的 pnpm 11
  • Bun 1.3.10 或更高版本，用于本地 Orchestrator sidecar
  • 目标系统对应的 Electron 构建依赖

macOS 请使用 xcode-select --install 安装 Xcode Command Line Tools。Windows 请安装 Visual Studio 2022 Build Tools，并勾选 Desktop development with C++ 和 Windows SDK。

启动桌面端

macOS 和 Linux：

git clone https://github.com/Devin-AXIS/iPolloWork.git
cd iPolloWork
corepack enable
./ipollowork setup
./ipollowork dev

Windows PowerShell：

git clone https://github.com/Devin-AXIS/iPolloWork.git
Set-Location iPolloWork
corepack enable
.\ipollowork.cmd setup
.\ipollowork.cmd dev

选择开发界面

目标命令
桌面客户端./ipollowork dev
仅浏览器 UI./ipollowork dev:ui
无头 Web 工作流pnpm dev:headless-web
连接本地 Cloud./ipollowork dev:cloud http://localhost:3100
类型检查与桌面端测试./ipollowork check

Windows 将 ./ipollowork 替换为 .\ipollowork.cmd。

各个 Launcher 命令的作用

命令目标说明
setup安装锁定的工作区依赖克隆后或依赖发生变化后执行。
dev启动完整桌面开发流准备受支持 Sidecar，启动 UI，并以隔离开发 Profile 打开 Electron。
dev:ui启动浏览器 UI 界面适用于只涉及 React App 且无需原生 Shell 验证的窄范围改动。
dev:cloud [url]使用指定 Cloud Base URL 启动桌面开发默认 http://localhost:3100，规范化 URL 并在 .ipollowork-dev/cloud/ 写入独立启动记录。
build构建工作区产物打包前使用，或重现接近生产的构建问题时使用。
package:dir生成未打包的桌面产物不会推进发布版本，适合验证原生行为。
package生成原生安装包产物除非明确跳过，否则先运行严格发布审查与检查。它不会提交、打 Tag 或发布远程版本。

Cloud 开发隔离

dev:cloud 是一个刻意设计的开发模式。它将指定 Base URL 提供给 App，并使用隔离的 Electron User Data 与 Runtime 路径。因此测试 Cloud Session 不会覆盖正常桌面状态。生成的 Bootstrap 文件是环境状态，不是 Secret 共享方式，也不是生产配置文件。

稳定的日常开发闭环

开发闭环以最小改动证明正确边界

视觉改动应在真实工作界面中检查。Server 或运行时改动则应经由真正消费它的客户端路径检查。

  1. 01定位

    修改不熟悉的层前，阅读最近的 `AGENTS.md`、Package Scripts 和源码归属。

  2. 02运行一个界面

    使用 `dev`、`dev:ui` 或能覆盖目标运行时的相关 Package 命令。

  3. 03窄范围验证

    检查被改动的精确 UI、Server 响应、Package 测试或桌面行为。

  4. 04运行广泛门控

    在交给其他人或进入发布流程前，运行仓库检查与 Diff 校验。

验证改动

先运行最窄范围的相关测试。在更大范围交付前，运行：

./ipollowork check
git diff --check

./ipollowork check 会验证繁体中文 README 同步、应用类型检查、Electron 类型检查和桌面测试。它是仓库级门控，不替代对交互或变更 HTTP 路由的人工检查。

按归属排查问题

症状优先检查的边界不要假设
桌面已启动，但本地任务无法执行本地 Server、审批状态和受支持 Sidecar HealthCloud Session 可以修复本地 Sidecar 或工作区问题
浏览器 UI 正确，但原生行为错误Electron Shell 与 Desktop Bridgedev:ui 能证明原生生命周期行为
Cloud 登录指向错误环境.ipollowork-dev/cloud/ Bootstrap 状态与配置 Base URL可以手工编辑正常桌面 Profile
打包构建失败Package Script 输出、原生构建前置条件和目标 OSpackage 会自动发布远程版本

Server 配置和网络边界检查见 自托管拓扑。生产归属和恢复门控见 生产运维。

本页目录

环境要求启动桌面端选择开发界面各个 Launcher 命令的作用Cloud 开发隔离稳定的日常开发闭环验证改动按归属排查问题