系统架构
理解本地工作运行时、可选控制平面，以及连接二者的两类 API。
iPolloWork 采用 local-first 架构。桌面客户端、本地服务器、工作区文件和 Agent Sidecar 可以在没有组织 Cloud 部署的情况下完成日常工作。只有当团队需要统一身份、共享能力、连接器管理或托管 Worker 时，控制平面才补充这些能力，而不会替换本地 Work 路径。
这种拆分是刻意的。它让本地文件与实时创作始终贴近实际工作的人，同时让组织策略与可复用配置留在应当拥有它们的系统中。
每一层拥有不同类型的状态。客户端应调用这层对应的接口，而不是绕过边界。
面向人且可直接编辑
渲染会话、文件、浏览器输出、Design 和 Video 工作界面。
负责原生生命周期、本地权限与桌面集成。
工作区执行边界
提供工作区状态、审批门控、产物与运行时适配器。
通过受支持的 Server 适配器接入的外部 Agent 运行时。
本地事实来源
可直接编辑的项目素材与工作输出。
工作区的上下文、工具轨迹、审批与导出活动。
组织级状态
身份、组织、能力、连接器与 Worker 生命周期。
仅在需要远程运行时创建的受管工作节点。
执行路径
一次 Agent 工作是带有明确审阅点的闭环。运行时不应静默切到无关客户端，本地私有 API 不应变成公开管理 API，最终输出也必须在生成它的界面中保持可编辑。
同一个会话可以跨越代码、Design、浏览器与 Video，但所有执行都经由可观察的本地 Server 边界。
- 01目标
用户提供目标、约束、文件、仓库或 URL。
- 02会话上下文
客户端保存任务上下文，并选择需要的工作界面。
- 03审批与工具
本地 Server 协调工具执行，并按策略请求审批。
- 04可编辑产物
文件、可视化画布、浏览器状态或 Video 场景均可检查和修改。
两类 API 界面
项目暴露两种不同的集成平面。选择正确的平面，可避免本地工作区与组织管理发生错误耦合。
| API 界面 | 归属方 | 常见地址 | 适合处理 | 不适合处理 |
|---|---|---|---|---|
| 本地 iPolloWork Server | 使用者或工作区宿主 | 默认 http://127.0.0.1:8787 | 工作区文件、会话、本地审批、产物、服务状态，以及受支持的 OpenCode 代理 | 组织成员、共享 Cloud 配置或托管 Worker 创建 |
| Den 控制平面 | 组织 | 已配置的 iPolloWork Cloud 基地址 | 身份、组织范围、配置资源、连接器、插件、Skills 与托管 Worker | 直接访问任意本地文件系统，或绕过工作区审批策略 |
本地 Server 文档涵盖 /health、/status、/capabilities、/whoami、工作区、审计与 /opencode/* 代理边界。控制平面的 API 契约维护在 packages/docs/openapi.json，详见 API 参考。
没有 Cloud 时，本地工作仍然完整
Cloud 为组织能力提供增量，不是本地项目、本地 Server 或桌面工作闭环的前提。
- 01打开工作区
针对本地项目启动桌面或浏览器工作界面。
- 02运行本地 Server
让工作区状态、审批策略、产物与运行时适配器保持在本地路径。
- 03使用受支持 Sidecar
通过仓库 Launcher 准备 OpenCode 与 Orchestrator。
- 04按需接入 Cloud
仅在需要团队身份、共享能力或托管 Worker 时再连接。
集成设计准则
- 让 Server 负责工作区操作。 客户端应调用本地 Server API，而不要另建一条本地执行路径。
- 把 OpenCode 保持在受支持的适配器之后。 它是外部 Sidecar，不是供业务代码直接改写的 API 平面。
- 远程工作必须显式发生。 托管 Worker 由 Worker 生命周期请求创建，而不是因为出现了本地任务就被静默创建。
- 密钥留在所属边界。 本地 Server Token、Cloud Session Token、模型凭据和连接器凭据不应被复制到产物或日志中。
- 保留可逆的审阅闭环。 输出应持续以文件、可编辑视觉结构或已记录的运行时状态存在。
要查看组件级包结构与准确命令，继续阅读 本地开发。要查看路由形态与认证方式，继续阅读 OpenAPI 与集成。