版本 v1.1 · 初版 2026-06-13，开源化修订 2026-08-20 本文档与
design/mockups.html中的高保真界面图配套阅读。
Opsnook 是常驻 macOS 刘海区的 AI Agent 指挥中心。开发者同时运行多个 AI 编程 Agent 时，无需切换窗口即可在刘海纵览所有 Agent 的实时状态，并在 Agent 需要人工介入（审批、提问、出错）时获得提醒并一键跳回。
目标用户的工作流已经演变为多 Agent 并行：
- 一个开发者会同时在多个终端与多个项目里运行 Claude Code、Codex、Antigravity 等 Agent；
- Agent 任务耗时从几十秒到几十分钟不等，用户在等待期间会切走做别的事；
- 核心问题是：Agent 卡在等待权限审批或等待用户回答的状态上，而用户没有感知，由此浪费十几分钟。各家 Agent 的通知彼此割裂，形式包括终端响铃、系统通知，或者没有任何通知，缺少统一入口。
刘海是屏幕上始终可见但通常未被利用的区域，适合承担这一职责。
- 零打扰、高信噪：不需要用户介入时完全隐形，需要介入时确保被看见。
- 一眼可读：收起态 1 秒读懂全局，展开态 3 秒定位到需要处理的 Agent。
- 快于切换窗口：从刘海提醒到回到对应终端只需一次点击。
- 不替代 Agent，只调度注意力：Opsnook 管理的是用户的注意力，而不是又一个 AI 工具。
| 画像 | 描述 |
|---|---|
| 重度 Agent 用户（核心） | 日常并行使用两个及以上 AI 编程 Agent 的专业开发者与独立开发者 |
| AI 早期尝鲜者 | 订阅了 Claude Max 或 ChatGPT Plus，关注配额与成本 |
| 技术管理者（远期） | 关注团队 Agent 使用量与产出 |
按优先级排列：
- S1 审批拦截。Claude Code 请求执行
npm install，被权限门拦住。刘海泛起琥珀色脉冲并显示待办数，用户悬停展开后直接在面板里点击允许，无需切换窗口。 - S2 全局速览。用户在写文档，余光瞥见刘海有 3 个绿色波形在跳动，说明三个 Agent 都在正常工作，可以继续写文档。
- S3 完成或出错回跳。Codex 任务完成或某个 Agent 报错时，对应行显示完成或错误标记。点击该行，Opsnook 把对应的终端窗口或 App 调到前台并聚焦。
- S4 配额管理。用户打开用量页，发现 Codex 的周配额已用 84%，于是把剩余任务分给 Claude Code。
- S5 接入新 Agent。用户安装了新的 Agent，Opsnook 检测到并在设置页提示可以接入。
- S6 工作区收口。多个 Agent 在同一个仓库里改代码，用户打开工作区页，在不离开刘海面板的情况下查看当前 Git 改动、展开 diff、按需暂存、提交并推送。
| 竞品 | 形态 | 差距 |
|---|---|---|
| 各 Agent 自带通知 | 系统通知或终端响铃 | 割裂，易被淹没，无全局视图 |
| 菜单栏单 Agent 监控工具 | 菜单栏图标 | 仅支持单个 Agent，无审批直达，信息密度低 |
| 多 Agent 编排器 | 完整 App 或工作区 | 较重，要求改变工作流。Opsnook 不接管工作流，只做状态层 |
| 通用刘海工具 | 媒体与文件类刘海工具 | 不理解 Agent，无状态语义 |
差异化定位是跨 Agent、零工作流侵入、常驻刘海的注意力调度层。
下表中的能力等级为当前实现的实际值。初版 PRD 曾预期 Codex 可达 L3，实测其审批为 TUI 内交互、无程序回传通道，据实修订为 L2。
| Agent | 品牌色 | 检测与接入方式 | 能力等级 |
|---|---|---|---|
| Claude Code | 珊瑚 #D97757 |
~/.claude/projects JSONL 加 hooks |
L3：状态、任务标题、审批直达 |
| Claude Code CLI | 珊瑚 #D97757 |
同上，按 entrypoint 区分来源 |
L3 |
| Codex | 白 #E8E8E8 |
~/.codex/sessions JSONL |
L2 |
| Codex CLI | 白 #E8E8E8 |
同上，按 originator 区分来源 |
L2 |
| Antigravity | 青 #1FB8A6 |
~/.gemini/antigravity-cli/brain transcript |
L2 |
| ZCode | 见 AgentCatalog |
~/.zcode/cli/db/db.sqlite |
L2 |
| WorkBuddy | 见 AgentCatalog |
~/.workbuddy/projects JSONL 加心跳文件 |
L2 |
| TRAE SOLO | 见 AgentCatalog |
~/.trae-cn/memory/projects 回合摘要 |
L2 |
| Qoder | 见 AgentCatalog |
Qoder 容器内 state.vscdb |
L2 |
| Cursor | 银 #C8CDD4 |
进程与窗口检测 | L1，沙盒下不可行，暂不接入 |
| GitHub Copilot CLI | 紫 #B392F0 |
进程检测与 PTY 包装器 | L1，沙盒下不可行，暂不接入 |
| Aider | 绿 #2BB673 |
项目内 .aider 日志 |
L2，计划中 |
| Gemini CLI | 蓝 #4796E3 |
~/.gemini/tmp 会话日志 |
已下线，角色由 Antigravity 接管 |
命名约定：同一厂商的客户端与 CLI 共用同一图标与品牌色，仅以名称区分，例如 Codex 与 Codex CLI，不加「客户端」字样。
能力等级定义：L1 仅区分运行与空闲；L2 增加任务标题、项目、分支、完成与出错；L3 增加审批请求内容与面板内批准或拒绝。完整判定规则见 AGENT_INTEGRATION_PLAN.md。
按可用性逐级降级：
- 原生集成，首选。利用 Agent 官方扩展点，例如 Claude Code 的 hooks，信息最全，可支持 L3。
- 日志监听。监听各 Agent 的会话 JSONL 或数据库目录，解析出状态与任务摘要，支持 L2。
- 通用包装器，兜底。以 PTY 包装任意 CLI Agent，通过输出停顿与提示符模式推断状态，支持 L1。该路径在沙盒下不可用，当前未提供。
新增 Agent 以适配器形式定义，即一个声明检测方式与解析规则的模块，以保证后续扩展成本可控。
三层渐进披露，与界面图编号对应：
第 1 层 收起态(常驻) 刘海左右翼、聚合状态、零交互成本
│ 鼠标悬停、点击或 ⌥⌘H
▼
第 2 层 主面板(展开) 420pt 下拉面板、按状态分组的会话列表、审批直达
│ 点击某行
▼
第 3 层 跳转(离开 Opsnook) 聚焦对应终端窗口或 App
- 面板支持固定。钉住后不随鼠标移开而收起。
- 面板底部 Tab 依次为会话（默认）、活动、用量、工作区，设置入口在底部齿轮。
- 全局快捷键 ⌥⌘H 切换展开与收起。无刘海的外接屏上，Opsnook 吸附在菜单栏中央的相同位置。
每个 Agent 会话归一化为以下 6 种状态。这是整个产品的语义基础，所有 UI 颜色、排序与通知都由它驱动。
| 状态 | 色值 | 收起态表现 | 通知策略 | 排序权重 |
|---|---|---|---|---|
需要审批 needs_approval |
琥珀 #FFB340 |
琥珀脉冲点加计数徽标 | 刘海脉冲，纯视觉，无声音 | 1，最高 |
等待输入 waiting_input |
天蓝 #64D2FF |
蓝点加计数 | 刘海脉冲 | 2 |
出错 error |
红 #FF5F57 |
红点 | 静态红点 | 3 |
运行中 running |
绿 #30D158 |
绿色波形动效 | 无 | 4 |
已完成 done |
灰绿对勾 | 短暂绿色闪烁后归于平静 | 一次性视觉轻提示，可关闭 | 5 |
空闲 idle |
灰 #5A5A5E |
暗点 | 无 | 6 |
Opsnook 全程不发出声音。Agent 自身运行完成时通常已有提示音，本产品的价值在于不占用听觉通道，只用刘海视觉传递状态。
聚合规则：收起态右翼显示全局最高优先级状态；左翼显示活跃 Agent 的微缩图标，最多 4 个，按权重排序，超出部分折叠为 +N。
| 编号 | 需求 | 验收要点 |
|---|---|---|
| F1 | 多 Agent 状态归一化引擎 | 6 种状态；Claude Code 达 L3，其余已接入 Agent 达 L2 |
| F2 | 收起态聚合显示 | 左翼微缩图标不超过 4 个并折叠余量；右翼按聚合规则展示；状态变化在 2 秒内反映到刘海 |
| F3 | 主面板，按状态分组列表 | 分组顺序为需要处理、运行中、最近完成、空闲（可折叠）；每行含 Agent 图标、任务标题、项目与分支与 git 状态、状态与计时 |
| F4 | 审批直达 | Claude Code 的权限请求在面板内显示命令详情，可允许或拒绝，操作回传不超过 1 秒 |
| F5 | 一键回跳 | 点击行聚焦对应终端窗口或 App；沙盒下为 App 级激活 |
| F6 | 通知策略 | 按状态表执行；提供专注模式一键全静默 |
| F7 | Agent 自动发现与接入向导 | 检测已安装 Agent；Claude Code 提供 hooks 配置片段；提供空态引导 |
| F8 | 固定面板、开机自启、⌥⌘H 快捷键 | 三项均可在设置页控制 |
| F9 | 中英双语本地化 | 仅简体中文与英文；默认跟随系统语言，设置页可手动切换；全部 UI 文案、通知与接入向导双语覆盖 |
- F10 用量页。各订阅的配额窗口、今日与本周成本、token 统计、7 日趋势。
- F11 行内快捷操作。悬停时提供跳转、复制会话路径、终止会话。
- F12 多显示器。无刘海屏幕上的菜单栏吸附形态。
- F13 活动 Tab，历史时间线。与会话页同源数据的两种视角：会话页呈现现在，活动页呈现历史。记录会话开始、完成、出错，以及用户的批准、拒绝、终止等动作，按今天与昨天分组。点击条目可跳回对应终端，顶部支持按 Agent 与事件类型筛选并搜索。事件仅本地留存，默认保留 7 天。
- F14 工作区页。从当前与近期 Agent 会话的
projectPath发现本地 Git 仓库，展示分支、upstream、ahead 与 behind、冲突、staged 与 unstaged 与 untracked 文件、文件级 diff 与最近 commit；支持显式点击后的 stage 与 unstage、commit、push、文件回滚二次确认、跳回终端、在本机默认编辑器打开。它是 Opsnook 的本地协作状态视图，不是完整 Git 客户端。无 Agent 仓库时展示空态，不提供手动添加仓库。为达到 Git 工作台所需的信息密度，工作区 Tab 使用 582pt 专用展开宽度，其他 Tab 仍保持 420pt。 - F18 会话时间轴查看器。2026-07 据实增补，已实现。从会话行打开独立窗口，把 Claude Code 与 Codex 会话全过程可视化为泳道时间轴，包含人工输入、工具调用、文件修改、命令执行、subagent、错误、状态共 7 类事件卡，调用与结果配对回填状态与耗时；同泳道连续同类事件聚合堆叠，支持组与轮两级收起；subagent 成为分叉泳道并在结束处汇回主轴。仅本地解析，不产生任何新数据。功能细节见 FEATURES.md 1.13 节。
- F15 通用 PTY 包装器，收编任意 CLI。沙盒下不可行。
- F16 团队版：团队 Agent 使用看板与配额池。
- F17 远程会话接入，例如 SSH 或容器内的 Agent。
- 不做 Agent 编排与任务分发；
- 不做聊天界面，不转发 prompt；
- 不做完整 Git 客户端或仓库管理器。工作区页只覆盖与当前 Agent 会话相关的本地 Git 状态与显式操作；
- v1 不做 Windows 与 Linux。
与 design/mockups.html 配套，整体延续纯黑面板、极细分隔线与单色高亮的视觉语言。
| Token | 值 | 用途 |
|---|---|---|
bg/panel |
#0A0A0B |
面板底色 |
bg/elevated |
#161618 |
审批卡片与嵌套卡片 |
bg/hover |
rgba(255,255,255,0.05) |
行悬停 |
border/hair |
rgba(255,255,255,0.07) |
分隔线与面板描边 |
text/primary |
rgba(255,255,255,0.92) |
任务标题 |
text/secondary |
rgba(255,255,255,0.55) |
项目与分支行 |
text/tertiary |
rgba(255,255,255,0.35) |
时间与提示 |
| 状态色 | 见第 6 节状态表 | 状态点、波形、徽标 |
| 品牌色 | 见 4.1 节表格 | 图标描边与底色 |
实现时以 OpsnookUI/DesignSystem/OpsnookColor 为唯一真相源，本表为设计侧记录。
- 字体使用 SF Pro Text。任务标题 13px medium，次行 11px regular，分组标签 11px semibold 大写，等宽命令文本使用 SF Mono 11px。
- 面板宽 420pt，顶部与刘海无缝衔接，底部圆角 26pt，1px hairline 描边。
- 行高：会话行 56pt。图标为 28pt 圆形，品牌色描边 1.5pt，右下角覆盖 8pt 状态点。
- 收起态高度与系统菜单栏完全一致。在刘海机型上等于 hardware safe area 高度，任何状态下都不得超出菜单栏底边，以免遮挡下方窗口内容。刘海两翼各扩展不超过 90pt，微缩图标 18pt，重叠间距 −6pt。只有用户主动触发的展开面板才允许越过菜单栏底边。
- 动效：面板展开 260ms spring；波形为 4 柱 0.8s 循环；琥珀脉冲 1.6s 呼吸。全部动效尊重系统的减弱动态效果设置。
- 状态不只依靠颜色区分：审批为填充徽标，运行为波形，出错为叉号，完成为对勾。
- 全键盘操作：上下方向键选行，回车跳转，A 与 D 分别对应允许与拒绝。VoiceOver 朗读内容形如「Claude Code，等待审批，1 分 32 秒」。该项尚未实现，见 FEATURES.md 第 3 节。
Opsnook 以开源项目形式维护，源码可自行构建。二进制分发渠道为 Mac App Store 沙盒版。
- 全部功能对所有用户开放，不设功能分级，不限制可接入的 Agent 数量。
- 无账号、无注册、无授权校验，应用不发起任何网络请求。
- 初版 PRD 曾规划 14 天试用加单 Agent 免费版的商业化方案（定价 1 美元每月或 6 美元买断），该方案已随开源化取消。
OpsnookIntegration/Licensing目录未建立，相关任务从计划中移除。
- Swift 与 AppKit。刘海层为
NSPanel，位于.statusBar层级并忽略鼠标穿透区域，面板为附着窗口，内容由 SwiftUI 渲染。 - 状态引擎：每个适配器一个 actor，事件经归一化状态机后发布，UI 只订阅归一化模型。
- 回跳：沙盒下经
NSWorkspace做 App 级激活。初版 PRD 曾规划使用辅助功能 API 与 AppleScript 精确定位窗口，因 App Review Guideline 2.4.5 禁止将辅助功能 API 用于非无障碍用途，该路径已放弃。 - 审批回传：Claude Code 经
PermissionRequesthook 的阻塞式决策协议完成。 - 本地化：使用 Xcode String Catalog，仅
zh-Hans与en两个 locale。任务标题等 Agent 产生的内容不翻译，原样展示。 - 隐私：所有解析在本地完成，零数据上传。
- 分发与沙盒：唯一二进制渠道为 App Store 沙盒版，原 Direct 非沙盒渠道已移除。读取
~/.claude、~/.codex等目录经用户授权的 security-scoped bookmark。写入 hooks 与精确窗口回跳等受沙盒限制的能力按Capabilities（预设.appStore）在运行期降级。不以编译开关区分版本。
| 阶段 | 范围 | 周期 |
|---|---|---|
| M1 重构 | 状态引擎与适配器框架；Codex 迁移为第一个适配器 | 2 周 |
| M2 多 Agent | Claude Code 达 L3，新增收起态与面板 UI（F1 至 F5） | 3 周 |
| M3 Beta | F6 至 F9、接入向导、中英双语、公开 Beta | 2 周 |
| M4 v1.1 | 用量页、活动流、工作区页、更多适配器 | 4 周 |
- 激活：安装后 10 分钟内接入至少 1 个 Agent 的比例不低于 70%。
- 价值：审批请求从产生到被处理的中位时长小于 30 秒。作为对照，没有 Opsnook 时该时长通常为分钟级。
- 留存：第 4 周的周活跃留存不低于 40%。
- 本地化：中文区与英文区各自的激活率单独跟踪，差距小于 30%。差距超出该范围说明某一语言版本的体验需要打磨。