可观测性与恢复
使用明确的健康信号、有限范围的日志、发布证据与保持工作区所有权的恢复路径运行 iPolloWork。
好的运维不从 dashboard 开始，而是先区分真正不健康的层：桌面应用、iPolloWork Server、OpenCode sidecar、某个具体工作区、可选控制平面资源，还是外部连接器。每层的证据和恢复负责人都不同。
进程显示绿色并不足够。信号必须回答用户路径、已配置工作区和所需能力是否可用。
用户实际可以使用什么
可见 UI 能打开目标工作区并呈现真实任务状态。
一个真实的小动作能够在目标界面中完成。
什么执行本地工作
证明可达性与实际解析出的运行时状态。
证明所需能力和工作区专属活动都可用。
什么运行智能体任务
以配对系统的方式检查 iPolloWork Server 与 OpenCode。
稳定 run ID 关联 Host 与 sidecar 证据，同时不暴露凭据。
什么增加共享组织能力
Worker、connector event、grant 与 provider 状态都按 ID 重新读取。
特权组织动作应通过控制平面记录评估，而不是只看本地日志。
健康是分层探针，不是一个布尔值
| 问题 | 第一个信号 | 后续信号 |
|---|---|---|
| 客户端能否到达本地运行时？ | GET /health | GET /status 与 GET /capabilities |
| 当前调用方能否访问工作区？ | GET /whoami 与 GET /workspaces | 工作区专属 config 或 event 路由 |
| 智能体任务能否运行？ | ipollowork status | 通过真实客户端路径完成一个小型端到端任务 |
| 远程操作是否完成？ | 请求返回的资源 ID | 当前 Worker、connector target、discovery 或 sync event 表示 |
| 导入或文件动作是否可见？ | 明确的 artifact 或 file-session 读取 | 目标操作后的 event/catalog 重新读取 |
对于自托管运行时，不应只发布 HTTP 可达性检查。只有正确范围的调用方可以到达已配置工作区并使用所需能力时，部署才真正可用。
关联日志但不泄露凭据
Orchestrator 可以从 OpenCode 与 iPolloWork Server 输出统一日志流。日志进入支持结构化字段的系统时，使用 JSON：
IPOLLOWORK_LOG_FORMAT=json \
ipollowork start --workspace /path/to/workspace --run-id release-2026-07-15
本地服务会记录请求 method、path、status 和 duration。Host 启动 OpenCode 时可通过 --opencode-log-level <DEBUG|INFO|WARN|ERROR> 传递日志级别。不要把 client token、host token、provider key 或原始配对凭据放进 run ID、shell history、复制的日志或支持工单。
每次恢复都要以最小的、原本失败的真实任务作为结束。
- 01收集
记录精确用户路径、工作区 ID、请求时间、状态信号和已脱敏的运行关联值。
- 02分类
识别归属边界：UI、本地服务、sidecar、工作区配置、控制平面或外部连接器。
- 03小范围修复
只修改失败归属：配置、sidecar 来源、过期凭据或远程资源状态。
- 04重新证明
重复原路径，并重新读取能证明成功的 health、status、event、artifact 或资源状态。
发布门禁：证明的不只是编译
使用分阶段发布门禁。具体命令因交付目标而异，但证据应保持可比较：
- 静态正确性 — 为变更边界运行最窄的 type、test 或 build 检查。
- 产物正确性 — 解包 Electron 应用足以验证桌面流程时使用
package:dir；验证安装包时再使用原生 package。 - 运行时正确性 — 启动真实本地服务或 Orchestrator 路径，并检查 health 和 capabilities。
- 用户路径正确性 — 在 UI 或远程客户端完成一次使用变更功能的聚焦任务。
- 回滚准备 — 变更远程部署前，明确上一个产物、配置版本和负责的 owner。
仓库中的 ./ipollowork check 是验证命令，不是部署机制。package:dir 创建本地验证产物；package 创建当前宿主机的原生安装包。两者都不会自行发布、修改 GitHub tag 或更新托管控制平面。
恢复手册
Server 可达但工作区无法使用
读取 GET /whoami、GET /workspaces，再读取目标工作区 config 与 events。检查工作区声明、token scope、审批姿态和 CORS origin 是否与真实客户端匹配。在保留错误与解析配置证据后，仅重启拥有该边界的 Server 进程。
Host 更新后 sidecar 失败
使用 ipollowork status，开启 --verbose，并在改变任何其他项前确认解析出来的 sidecar 策略。downloaded、bundled 和显式 external 二进制是不同的发布输入。先修正来源选择，再运行一个小型端到端任务。
异步 Cloud 操作看似卡住
使用返回的资源 ID 读取 Worker、connector target、discovery 或 sync event。不要因为最初请求只是 accepted 就创建重复 account 或 Worker。只在理解当前状态后重试明确可重试的资源。
破坏性或权限敏感请求待处理
通过 approval 或 owner 流程审核。不要用生产环境全局 auto 设置绕过手动审批。若访问不正确，修复 token 或 grant 边界，再用最小合适范围重复请求。
运行时的准确组装方式请继续阅读 Orchestrator 与 Sandbox；私有网络与服务配置请继续阅读 自托管拓扑。