Local Server 参考
使用文件系统驱动的 iPolloWork Server API 管理本地工作区、审批、扩展、产物和批量文件会话。
iPolloWork Server 是供远程桌面端和浏览器客户端调用的、本地文件系统驱动 API。它独立于 Electron 应用，不能与面向组织的 Den API 混为一谈。它的职责是暴露私有工作区运行时，而不是成为公开管理服务。
先建立服务端边界
服务把客户端映射到已配置的工作区，通过审批拦截写入，并只通过显式路由代理 OpenCode。
桌面端或已批准的远程客户端
在服务端边界识别普通本地客户端。
命名已配置工作区；不要根据展示名称推断。
文件系统驱动的运行时
负责配置、扩展、事件、导入导出、收件箱、产物和文件会话。
拦截工作区写入，而不是把网络可达性当作权限。
管理权限
使用 owner 范围 bearer token 或 host token 访问主机 API 与审批决策。
控制 host、port、工作区、CORS 来源和审批姿态。
写入前先发现
服务提供三层有用的只读发现能力：
| 路由 | 用于回答 | 不可据此推断 |
|---|---|---|
GET /health | 服务是否可达？ | 某个工作区是否已配置且就绪。 |
GET /status | 运行时报告了什么？ | 调用方是否能进行 owner 级变更。 |
GET /capabilities | 服务声明了哪些可选能力？ | 某项集成是否已经获准用于此任务。 |
GET /workspaces | 调用方可看到哪些工作区？ | 有权修改其中任意一个。 |
GET /whoami | 当前服务身份与范围是什么？ | Cloud 组织身份。 |
对一个工作区，应先读取 GET /workspace/:id/config、GET /workspace/:id/events、GET /workspace/:id/plugins、GET /workspace/:id/skills、GET /workspace/:id/mcp 或 GET /workspace/:id/commands，再进行对应写入。这样客户端会与当前服务状态保持一致，而不是依赖旧桌面缓存。
认证与审批是两次不同的检查
普通客户端使用 Authorization: Bearer <client-token> 认证。主机 API 接受 owner 范围 bearer token 或 X-iPolloWork-Host-Token。主机凭据授权管理边界；工作区写入仍受服务审批模式约束。
每次写入都要穿过授权与审批边界，然后检查产生的资源或事件。
- 01识别
解析服务健康状态、调用方范围、工作区 ID 与当前资源表示。
- 02请求
向匹配的工作区路由发送最小且明确的变更。
- 03审批
手动模式由 Host 允许或拒绝待处理操作；自动模式只用于有意识的开发环境。
- 04验证
重新读取资源、产物、配置或事件流，并呈现被拒绝状态。
路由族
| 路由族 | 读取 | 写入 | 运行职责 |
|---|---|---|---|
| 工作区配置 | /workspace/:id/config | PATCH /workspace/:id/config | 读取或修改已配置的工作区运行时形态。 |
| 扩展 | /plugins、/skills、/mcp、/commands | 对应 POST / DELETE | 增删具名扩展，而非把它们塞进一个不透明大配置。 |
| 产物与收件箱 | /artifacts、/inbox | 产物读取与 multipart 收件箱上传 | 让任务输入与产物经过明确的工作区边界。 |
| 导入 / 导出 | /export、/import/preview | /import | 导入前先检查；不要盲目覆盖工作区。 |
| 审批与 token | /approvals、/tokens | 审批回复与 token 生命周期路由 | 让主机所有者治理可见、可审计。 |
| OpenCode 代理 | /opencode/* 或 /w/:id/opencode/* | 对应受支持的代理方法 | 经由本地服务边界访问受支持的运行时 sidecar。 |
文件会话是短生命周期的批量工作通道
服务提供文件会话路由，使远程客户端能操作工作区而无需把文件系统当作长期挂载盘。创建文件会话、读取目录快照、批量读写、按需观察事件、仅在仍需使用时续期，最后显式关闭。
目录读取、批量操作和变更观察都绑定在一个明确的会话 ID 上。
- 01创建
以目标访问模式调用 `POST /workspace/:id/files/sessions`，保存返回的会话 ID。
- 02检查
读取目录快照，只请求当前任务需要的路径。
- 03变更
使用批量读取、写入或 ops 路由；不要让客户端进行无边界文件扫描。
- 04观察并关闭
需要时读取目录事件，然后显式续期或删除会话。
常用路由：POST /workspace/:id/files/sessions、POST /files/sessions/:sessionId/renew、GET /files/sessions/:sessionId/catalog/snapshot、GET /files/sessions/:sessionId/catalog/events、POST /files/sessions/:sessionId/read-batch、POST /files/sessions/:sessionId/write-batch、POST /files/sessions/:sessionId/ops 与 DELETE /files/sessions/:sessionId。
带着明确意图配置
默认配置文件是 ~/.config/ipollowork/server.json；可通过 IPOLLOWORK_SERVER_CONFIG 或 --config 修改路径。真实服务配置包括 host 与 port、审批模式与超时、工作区声明、CORS 来源、token 存储、inbox/outbox 行为、sandbox 广告和 OpenCode 连接设置。不要把宽松的开发配置复制到远程环境。
有关服务启动与生产所有权，请阅读 自托管拓扑。有关组织资源、API Key、托管 Worker 与共享连接器，请阅读 控制平面资源地图。