Opsnook 项目文件导览与缺陷定位地图

本文供维护者查阅，基于 2026-06-28 的仓库实况整理，范围限于 git 跟踪的文件，不包含 .git/、.build/、Opsnook.xcodeproj/、.DS_Store 等生成文件或系统文件。

产品方向先看 docs/PRD.md；架构约束先看 docs/TECHNICAL_DESIGN.md；协作纪律先看根目录 AGENTS.md；当前仓库口径是 App Store 沙盒单渠道（原 Direct / 非沙盒渠道已移除）。

1. 先理解项目怎么跑

Opsnook 是一个 macOS 刘海区常驻 App。运行链路可以先记成这一条：

Agent 本地文件 / SQLite / hook 状态
  -> OpsnookAdapters 各 Agent 适配器解析成 SessionSnapshot
  -> OpsnookCore.SessionStore 统一 reduce 成 AgentSession + AgentEvent + AggregateSnapshot
  -> OpsnookUI.ViewModels 订阅 Store,变成 SwiftUI 可观察状态
  -> NotchCollapsedView / PanelView / ActivityView / UsageView / WorkspaceView 显示
  -> OpsnookIntegration 负责文件授权、回跳、通知、登录项、Git 命令、Claude hooks 等 OS 副作用
  -> App target 只负责生命周期、窗口、依赖装配和 App Store 沙盒授权入口

修改 bug 时最常用的判断：

刘海收起态显示错：先看 NotchCollapsedView.swift、NotchUIState.swift、AggregateBuilder.swift、NotchWindowController.swift。
展开面板会话行显示错：先看 PanelView.swift、PanelRow.swift、OpsnookViewModel.swift、SessionReducer.swift。
某个 Agent 状态不对：先看对应 *Adapter.swift 和 *SessionParser.swift，再看 SessionStore.swift。
活动页或消息预览错：先看 ActivityModel.swift、ActivityView.swift、TranscriptPeekModel.swift、TranscriptPeekView.swift、SessionTranscript.swift。
用量页错：先看 UsageReader.swift、UsageAggregator.swift、UsageModel.swift、UsageView.swift。
工作区 / Git 页错：先看 WorkspaceModel.swift、WorkspaceView.swift、GitWorkspaceService.swift、WorkspaceSnapshot.swift。
沙盒下读不到 Agent 文件：先看 DirectoryAccessModel.swift、AgentDirectoryAccess.swift、SecurityScopedBookmarkStore.swift、AppContainer.swift。
点击回跳不准：先看 TerminalFocuser.swift、ApplicationFocuser.swift、Capabilities.swift。
会话时间轴错（打不开/解析空/布局乱）：先看 SessionTimelineModel.swift（布局）、ClaudeTimelineParser.swift / CodexTimelineParser.swift（解析）、TimelineWindowController.swift（窗口）与 AppContainer.loadTimeline。

2. 文件树说明

下面是当前项目的文件地图。每个条目后面的注释说明它在项目里的用途。

.
├─ .github/
│  ├─ workflows/
│  │  └─ ci.yml                                      # GitHub Actions:跑 OpsnookKit 单元测试,生成 Xcode 工程并构建 Opsnook-AppStore。
│  ├─ scripts/
│  │  └─ select-xcode.sh                             # CI 步骤:在 runner 已装的 Xcode 中选出满足 Swift 6 的最高版本,写入 DEVELOPER_DIR。
│  ├─ ISSUE_TEMPLATE/
│  │  ├─ bug_report.yml                              # 缺陷报告表单,含脱敏提示与环境字段。
│  │  ├─ agent_request.yml                           # 新 Agent 支持请求表单,重点问数据源与审批回传通道。
│  │  └─ config.yml                                  # issue 入口配置,把安全问题引流到私有报告。
│  └─ PULL_REQUEST_TEMPLATE.md                       # PR 模板,对应 AGENTS.md 第 8 节收工前清单。
├─ .gitignore                                        # 忽略 Xcode/SwiftPM/构建产物、本地签名配置等不入库文件。
├─ LICENSE                                           # GNU GPL v3 全文,本项目的许可证。
├─ LICENSE-EXCEPTION.md                              # 版权声明,以及依 GPL 第 7 节授予的 App Store 分发附加许可。
├─ README.md                                         # 面向使用者与贡献者的项目说明,英文。
├─ CONTRIBUTING.md                                   # 英文贡献指南,AGENTS.md 的对外入口,冲突时以 AGENTS.md 为准。
├─ SECURITY.md                                       # 漏洞私有报告流程,以及在范围与不在范围的界定。
├─ CHANGELOG.md                                      # 版本变更记录,Keep a Changelog 格式。
├─ AGENTS.md                                         # 本仓库协作规范,包含 App Store 单渠道、测试、文档与隐私约束。
├─ project.yml                                       # XcodeGen 工程定义:Opsnook-AppStore scheme、Debug/Release-AppStore 配置、OpsnookKit 包依赖。
├─ App/                                              # App target:生命周期、窗口、设置、依赖装配,不要把业务逻辑扩散进这里。
│  ├─ OpsnookApp.swift                                  # @main 入口和设置页正文。
│  ├─ AppDelegate.swift                              # App 启动、模型装配、刘海窗口、热键、Agent 扫描、授权回调。
│  ├─ Composition/
│  │  ├─ AppContainer.swift                          # App Store 能力、Store、Registry、Adapters、Git 服务、书签访问的依赖装配根。
│  │  └─ DirectoryAccessModel.swift                  # 设置页里“Agent 数据访问”的沙盒目录授权 UI 模型。
│  ├─ Config/
│  │  ├─ Base.xcconfig                               # App target 基础构建配置。
│  │  └─ AppStore.xcconfig                           # App Store 沙盒构建配置,签名/沙盒/严格并发等入口。
│  ├─ Entitlements/
│  │  └─ Opsnook.AppStore.entitlements                  # App Sandbox entitlement,上架和本地沙盒运行都依赖它。
│  ├─ Resources/
│  │  ├─ Info.plist                                  # App bundle 元信息、LSUIElement 等运行入口配置。
│  │  ├─ Localizable.xcstrings                       # App target 文案,主要用于设置页和系统设置回退窗口。
│  │  ├─ PrivacyInfo.xcprivacy                       # Apple privacy manifest,声明隐私/数据采集口径。
│  │  └─ Assets.xcassets/
│  │     ├─ Contents.json                            # Asset Catalog 根索引。
│  │     └─ AppIcon.appiconset/
│  │        ├─ Contents.json                         # App icon 集合索引。
│  │        ├─ icon_16.png                           # 16x16 App icon。
│  │        ├─ icon_32.png                           # 32x32 App icon。
│  │        ├─ icon_64.png                           # 64x64 App icon。
│  │        ├─ icon_128.png                          # 128x128 App icon。
│  │        ├─ icon_256.png                          # 256x256 App icon。
│  │        ├─ icon_512.png                          # 512x512 App icon。
│  │        └─ icon_1024.png                         # 1024x1024 App Store 大图标。
│  └─ Windows/
│     ├─ GlobalHotKey.swift                          # 注册全局快捷键,当前用于 Option-Command-H 展开/收起。
│     ├─ NotchWindowController.swift                 # NSPanel 刘海窗口控制器,处理 hover、展开动画、尺寸测量、回跳。
│     ├─ ScreenGeometry.swift                        # 屏幕 safe area、刘海宽度、菜单栏高度等几何计算。
│     └─ TimelineWindowController.swift              # 会话时间轴独立窗口管理:每会话一扇 NSWindow,复用前置。
├─ Packages/
│  └─ OpsnookKit/
│     ├─ Package.swift                               # Swift Package 定义:OpsnookCore/OpsnookAdapters/OpsnookIntegration/OpsnookUI 四个库和测试 target。
│     ├─ Sources/
│     │  ├─ OpsnookCore/                                # 纯模型、状态机、Store、计算逻辑。原则:不依赖 AppKit/SwiftUI/OS 副作用。
│     │  │  ├─ Opsnook.swift                            # Opsnook 版本等包级常量。
│     │  │  ├─ Capability/
│     │  │  │  └─ Capabilities.swift                 # App Store 能力开关,业务层只读它做降级。
│     │  │  ├─ Layout/
│     │  │  │  └─ NotchLayout.swift                  # 收起态刘海宽度/左右翼布局的纯计算。
│     │  │  ├─ Models/
│     │  │  │  ├─ AgentDescriptor.swift              # Agent 静态描述、发现结果、接入动作和反馈。
│     │  │  │  ├─ AgentEvent.swift                   # 活动页事件模型。
│     │  │  │  ├─ AgentKind.swift                    # Agent 类型、品牌、图标和颜色语义。
│     │  │  │  ├─ AgentSession.swift                 # UI 主数据单元:一个 Agent 会话的状态、项目、回跳、审批等。
│     │  │  │  ├─ AgentStatus.swift                  # 六种产品状态和面板分组规则。
│     │  │  │  ├─ AggregateSnapshot.swift            # 收起态聚合快照。
│     │  │  │  ├─ Approval.swift                     # L3 审批请求、决策、错误信息模型。
│     │  │  │  ├─ CapabilityLevel.swift              # L1/L2/L3 能力等级。
│     │  │  │  ├─ ModelPricing.swift                 # 用量页成本估算的模型单价表。
│     │  │  │  ├─ Question.swift                     # AskUserQuestion/等待输入问题卡模型。
│     │  │  │  ├─ SessionSnapshot.swift              # 适配器输入 Store 的会话快照和 emission。
│     │  │  │  ├─ SessionTimeline.swift              # 会话时间轴模型:事件卡/泳道/facts/原始 JSON 行。
│     │  │  │  ├─ SessionTranscript.swift            # 活动页消息预览的 transcript 数据模型。
│     │  │  │  ├─ TokenUsage.swift                   # token 用量计数字段。
│     │  │  │  ├─ UsageSnapshot.swift                # 用量页展示快照、配额、趋势、按 Agent 明细。
│     │  │  │  └─ WorkspaceSnapshot.swift            # 工作区/Git 页展示模型、文件、diff、commit、错误。
│     │  │  ├─ Settings/
│     │  │  │  └─ AppLanguageController.swift        # App 内语言选择和 locale 控制。
│     │  │  ├─ State/
│     │  │  │  ├─ AggregateBuilder.swift             # 从 sessions 计算收起态最高优先级、图标、计数。
│     │  │  │  ├─ EngineConfig.swift                 # 状态机时间窗口/衰减参数。
│     │  │  │  ├─ SessionReducer.swift               # 纯状态机:SessionSnapshot -> AgentSession + AgentEvent。
│     │  │  │  └─ UsageAggregator.swift              # 用量样本 -> 用量页聚合快照。
│     │  │  ├─ Store/
│     │  │  │  └─ SessionStore.swift                 # actor 唯一真相源,接收适配器 emission,发布 UI 状态与事件。
│     │  │  └─ Util/
│     │  │     ├─ ActivityText.swift                 # 活动页事件文案/消息摘要辅助。
│     │  │     └─ TimeSource.swift                   # 可注入时间源,避免可测逻辑直接 Date()。
│     │  ├─ OpsnookAdapters/                            # 各 Agent 数据解析与轮询,把外部世界翻译成 OpsnookCore emission。
│     │  │  ├─ AdapterLimits.swift                   # 任务标题等展示截断上限。
│     │  │  ├─ AdapterRegistry.swift                 # 注册、发现、启动所有 adapter,并转发到 SessionStore。
│     │  │  ├─ AgentAdapter.swift                    # 统一适配器协议和默认能力兜底。
│     │  │  ├─ AgentCatalog.swift                    # 所有 Agent/品牌 id 的单一来源。
│     │  │  ├─ GitHead.swift                         # 共享 helper:读取 Git HEAD 当前分支。
│     │  │  ├─ SessionFileFingerprint.swift          # 文件 mtime/size 指纹,避免每轮重复解析。
│     │  │  ├─ ShellCommandClassifier.swift          # 命令串行为分类(读取/检索/创建/修改/删除/git/依赖/构建测试/网络/执行),时间轴卡片分型用。
│     │  │  ├─ Usage/
│     │  │  │  └─ UsageReader.swift                  # 按需扫描 Claude/Codex/Gemini 会话文件,生成用量样本。
│     │  │  ├─ Antigravity/
│     │  │  │  ├─ AntigravityAdapter.swift           # Antigravity CLI/桌面 L2 adapter,扫描 brain transcript。
│     │  │  │  ├─ AntigravitySessionParser.swift     # Antigravity transcript 宽容解析器(含 INVOKE_SUBAGENT 派生登记)。
│     │  │  │  ├─ AntigravitySubagentMessages.swift   # 父目录 messages/*.json 解析:子代理名称/完成时间来源。
│     │  │  │  └─ AntigravityTimelineParser.swift     # Antigravity transcript → 会话时间轴(步骤分型、子会话分叉泳道)。
│     │  │  ├─ ClaudeCode/
│     │  │  │  ├─ ClaudeCodeAdapter.swift            # Claude Code L2/L3 adapter,扫描 JSONL 和 hook 请求,支持审批回传。
│     │  │  │  ├─ ClaudeHookRequestParser.swift      # Claude hook PermissionRequest/AskUserQuestion 文件解析。
│     │  │  │  ├─ ClaudeSessionParser.swift          # Claude projects JSONL 会话解析、消息/用量提取。
│     │  │  │  └─ ClaudeTimelineParser.swift         # Claude JSONL → 会话时间轴(工具配对、agent-*.jsonl 子泳道)。
│     │  │  ├─ Codex/
│     │  │  │  ├─ CodexAdapter.swift                 # Codex desktop/CLI L2 adapter,扫描 sessions JSONL 和 session_index。
│     │  │  │  ├─ CodexSessionParser.swift           # Codex rollout JSONL 解析、originator、消息和配额读取。
│     │  │  │  └─ CodexTimelineParser.swift          # Codex rollout → 会话时间轴(call_id 配对、spawn_agent 子泳道)。
│     │  │  ├─ Gemini/
│     │  │  │  ├─ GeminiAdapter.swift                # 历史 Gemini CLI adapter,当前 AppContainer 不注册。
│     │  │  │  └─ GeminiSessionParser.swift          # Gemini chat JSON 解析、用量样本读取。
│     │  │  ├─ Qoder/
│     │  │  │  ├─ QoderAdapter.swift                 # 阿里 Qoder L2 adapter,读 state.vscdb 的 Quest 快照。
│     │  │  │  ├─ QoderQuestStore.swift              # Qoder state.vscdb(SQLite)查询层。
│     │  │  │  ├─ QoderSessionParser.swift           # Quest 快照 JSON → 会话快照解析。
│     │  │  │  └─ QoderTimelineParser.swift          # Qoder 执行 JSONL → 会话时间轴 / transcript / subagent 摘要。
│     │  │  ├─ Trae/
│     │  │  │  ├─ TraeAdapter.swift                  # 字节 TRAE SOLO L2 adapter,读 memory 摘要 + 运行时探针。
│     │  │  │  ├─ TraeProjectPath.swift              # TRAE 编码 cwd 目录名还原。
│     │  │  │  ├─ TraeRuntimeProbe.swift             # 运行时目录 SessionUpdated 日志探针(实时运行态)。
│     │  │  │  └─ TraeSessionParser.swift            # TRAE session_memory JSONL 解析。
│     │  │  ├─ WorkBuddy/
│     │  │  │  ├─ WorkBuddyAdapter.swift             # 腾讯 CodeBuddy/WorkBuddy L2 adapter,扫描 projects 和心跳。
│     │  │  │  ├─ WorkBuddySessionParser.swift       # WorkBuddy Responses-API 风格 transcript 解析(含 subagent 摘要)。
│     │  │  │  └─ WorkBuddyTimelineParser.swift      # WorkBuddy JSONL → 会话时间轴(callId 配对、[Agent ID] 子泳道)。
│     │  │  └─ ZCode/
│     │  │     ├─ ZCodeAdapter.swift                 # ZCode L2 adapter,读取 ~/.zcode/cli/db/db.sqlite。
│     │  │     ├─ ZCodeSessionStore.swift            # ZCode SQLite 查询层。
│     │  │     └─ ZCodeStatusMap.swift               # ZCode 消息/finish_reason -> Opsnook 六状态映射。
│     │  ├─ OpsnookIntegration/                         # OS 副作用层:文件授权、回跳、通知、hooks、Git、登录项。
│     │  │  ├─ Integration.swift                     # OpsnookIntegration target 标记文件。
│     │  │  ├─ FileAccess/
│     │  │  │  ├─ AgentDirectoryAccess.swift         # Agent 数据目录 key、真实 home 解析、安全作用域书签访问入口。
│     │  │  │  └─ SecurityScopedBookmarkStore.swift  # App Store 沙盒安全作用域书签持久化和访问生命周期。
│     │  │  ├─ Focus/
│     │  │  │  ├─ ApplicationFocuser.swift           # 仅激活 App 的回跳降级路径。
│     │  │  │  └─ TerminalFocuser.swift              # 终端/应用回跳协调,按 capabilities 选择精确或降级。
│     │  │  ├─ Hooks/
│     │  │  │  └─ ClaudeHooksInstaller.swift         # 生成/安装 Claude hooks runtime,支持本地文件 IPC 审批。
│     │  │  ├─ LaunchAtLogin/
│     │  │  │  └─ LaunchAtLoginController.swift      # 登录项开关状态和 SMAppService 调用。
│     │  │  ├─ Notifications/
│     │  │  │  └─ NotificationCoordinator.swift      # 视觉通知 cue 和专注模式偏好。
│     │  │  └─ Workspace/
│     │  │     └─ GitWorkspaceService.swift          # 本地 Git 状态读取和显式 stage/commit/push/revert/move 操作。
│     │  └─ OpsnookUI/                                  # SwiftUI UI 层和可观察 ViewModel。
│     │     ├─ OpsnookUI.swift                          # OpsnookUI target 标记文件。
│     │     ├─ DesignSystem/
│     │     │  ├─ Formatting.swift                   # 状态、时间、金额、token、事件等展示格式化。
│     │     │  ├─ OpsnookColor.swift                    # UI 颜色 token 和 Agent 品牌色映射。
│     │     │  ├─ OpsnookMetrics.swift                  # UI 尺寸、动画、面板宽度等 token。
│     │     │  ├─ ScrollbarlessScrollView.swift      # macOS 无滚动条 NSScrollView 包装。
│     │     │  └─ Waveform.swift                     # 运行态波形和 pulse 动效。
│     │     ├─ Localization/
│     │     │  └─ OpsnookL10n.swift                     # OpsnookUI 文案读取与 format helper。
│     │     ├─ Notch/
│     │     │  ├─ AgentBrandIcon.swift               # Lobe/资源图标渲染和品牌资源映射。
│     │     │  ├─ AgentIconView.swift                # 圆形 Agent 头像 + 状态点。
│     │     │  ├─ NotchCollapsedView.swift           # 收起态刘海左右翼 UI。
│     │     │  └─ NotchRootView.swift                # 收起态/展开态切换根视图。
│     │     ├─ Panel/
│     │     │  ├─ ActivityView.swift                 # 活动 Tab 时间线。
│     │     │  ├─ PanelRow.swift                     # 会话 Tab 单行 Agent 会话。
│     │     │  ├─ PanelView.swift                    # 展开面板总容器、header、footer、tabs、审批卡。
│     │     │  ├─ QuestionCard.swift                 # AskUserQuestion 等待输入只读问题卡。
│     │     │  ├─ TranscriptPeekView.swift           # 活动页内嵌 transcript 消息预览。
│     │     │  ├─ UsageView.swift                    # 用量 Tab。
│     │     │  └─ WorkspaceView.swift                # 工作区 Tab,文件树和 Git 面板。
│     │     ├─ Timeline/                             # 会话时间轴查看器(右键会话行打开的独立窗口)。
│     │     │  ├─ SessionTimelineModel.swift         # 时间轴 ViewModel:布局(同类分组/堆叠/收起)、筛选、选中、缩放平移。
│     │     │  ├─ SessionTimelineView.swift          # 三栏根视图:工具栏 + 控制台侧栏 + 画布 + 详情。
│     │     │  ├─ TimelineCanvasView.swift           # 画布:泳道肘形连线、事件卡、分组虚线框、缩略图、手势。
│     │     │  ├─ TimelineDetailPanel.swift          # 事件详情:关键字段、完整 JSON、上下文窗口。
│     │     │  └─ TimelineStyle.swift                # 时间轴视觉 token:事件类别/状态配色、泳道调色板。
│     │     ├─ Resources/
│     │     │  ├─ Localizable.xcstrings              # OpsnookUI 文案源 catalog,Package 构建时排除,保留给人工维护。
│     │     │  ├─ en.lproj/Localizable.strings       # OpsnookUI 英文运行时文案。
│     │     │  ├─ zh-Hans.lproj/Localizable.strings  # OpsnookUI 简体中文运行时文案。
│     │     │  └─ BrandIcons/
│     │     │     ├─ LICENSE.lobe-icons.txt          # Lobe Icons 许可证。
│     │     │     ├─ lobe-claude.png                 # Claude 品牌图标 PNG。
│     │     │     ├─ lobe-claude.svg                 # Claude 品牌图标 SVG 源。
│     │     │     ├─ lobe-codebuddy.png              # CodeBuddy/WorkBuddy 品牌图标 PNG。
│     │     │     ├─ lobe-codebuddy.svg              # CodeBuddy/WorkBuddy 品牌图标 SVG 源。
│     │     │     ├─ lobe-gemini.png                 # Gemini/Antigravity 品牌图标 PNG。
│     │     │     ├─ lobe-gemini.svg                 # Gemini/Antigravity 品牌图标 SVG 源。
│     │     │     ├─ lobe-openai.png                 # OpenAI/Codex 品牌图标 PNG。
│     │     │     ├─ lobe-openai.svg                 # OpenAI/Codex 品牌图标 SVG 源。
│     │     │     ├─ lobe-zai.png                    # ZCode/Z.ai 品牌图标 PNG。
│     │     │     └─ lobe-zai.svg                    # ZCode/Z.ai 品牌图标 SVG 源。
│     │     └─ ViewModels/
│     │        ├─ ActivityModel.swift                # 活动事件订阅、保留期、Agent 筛选。
│     │        ├─ AgentDiscoveryModel.swift          # Agent 发现/接入向导状态。
│     │        ├─ OpsnookViewModel.swift                # 会话页主 ViewModel,订阅 SessionStore。
│     │        ├─ NotchUIState.swift                 # 刘海窗口 UI 状态:展开、固定、tab、宽高、cue。
│     │        ├─ TranscriptPeekModel.swift          # transcript 预览状态机。
│     │        ├─ UsageModel.swift                   # 用量页按需加载状态。
│     │        └─ WorkspaceModel.swift               # 工作区页状态、文件树、Git 操作和授权触发。
│     └─ Tests/                                      # Swift Testing 单元测试,按 target 分层。
│        ├─ OpsnookCoreTests/
│        │  ├─ AppLanguageControllerTests.swift      # 语言选择和 locale 测试。
│        │  ├─ CapabilitiesTests.swift               # App Store capabilities 测试。
│        │  ├─ OpsnookCoreTests.swift                   # OpsnookCore 基础 smoke test。
│        │  ├─ ModelTests.swift                      # 核心模型 Equatable/排序等测试。
│        │  ├─ NotchLayoutTests.swift                # 收起态刘海布局计算测试。
│        │  ├─ SessionStoreTests.swift               # Store 发布、事件、衰减、延迟测试。
│        │  ├─ SessionTranscriptTests.swift          # transcript anchor/定位测试。
│        │  ├─ TimelineEventCoalescingTests.swift    # 同文件连续事件合并测试。
│        │  ├─ StateMachineTests.swift               # reducer 和聚合排序测试。
│        │  └─ UsageTests.swift                      # 用量聚合和模型计价测试。
│        ├─ OpsnookAdaptersTests/
│        │  ├─ AntigravityAdapterTests.swift         # Antigravity parser/adapter 测试(含 subagent 折叠归位)。
│        │  ├─ AntigravityTimelineParserTests.swift  # Antigravity 时间轴解析测试(步骤分型/子泳道)。
│        │  ├─ ClaudeCodeAdapterTests.swift          # Claude adapter 扫描、审批、问题卡测试。
│        │  ├─ ClaudeHookRequestParserTests.swift    # Claude hook request 解析测试。
│        │  ├─ ClaudeSessionParserTests.swift        # Claude transcript 解析测试。
│        │  ├─ ClaudeTimelineParserTests.swift       # Claude 时间轴解析测试(配对/子泳道/标题链)。
│        │  ├─ CodexAdapterTests.swift               # Codex adapter 和 registry 测试。
│        │  ├─ CodexParserTests.swift                # Codex JSONL/parser 测试。
│        │  ├─ CodexTimelineParserTests.swift        # Codex 时间轴解析测试(exit code/patch/spawn 泳道)。
│        │  ├─ GeminiAdapterTests.swift              # Gemini adapter 测试。
│        │  ├─ GeminiSessionParserTests.swift        # Gemini parser 测试。
│        │  ├─ OpsnookAdaptersTests.swift               # OpsnookAdapters smoke test。
│        │  ├─ QoderAdapterTests.swift               # Qoder Quest 快照/adapter 测试。
│        │  ├─ QoderTimelineParserTests.swift        # Qoder 时间轴/subagent 摘要解析测试。
│        │  ├─ ShellCommandClassifierTests.swift     # shell 命令行为分类器测试。
│        │  ├─ TraeAdapterTests.swift                # TRAE 摘要解析/运行时探针测试。
│        │  ├─ UsageParserTests.swift                # 各 Agent 用量解析测试。
│        │  ├─ WorkBuddyAdapterTests.swift           # WorkBuddy parser/adapter 测试(含 subagent 轮次语义)。
│        │  ├─ WorkBuddyTimelineParserTests.swift    # WorkBuddy 时间轴解析测试(配对/子泳道)。
│        │  └─ ZCodeAdapterTests.swift               # ZCode SQLite/status map 测试。
│        ├─ OpsnookIntegrationTests/
│        │  ├─ AgentDirectoryAccessTests.swift       # Agent 目录授权解析测试。
│        │  ├─ ApplicationFocuserTests.swift         # App 级回跳降级测试。
│        │  ├─ ClaudeHooksInstallerTests.swift       # Claude hook runtime/install 测试。
│        │  ├─ GitWorkspaceServiceTests.swift        # GitWorkspaceService 的 git 操作测试。
│        │  ├─ LaunchAtLoginControllerTests.swift    # 登录项状态测试。
│        │  ├─ NotificationCoordinatorTests.swift    # 通知 cue/专注模式测试。
│        │  └─ TerminalFocuserTests.swift            # 终端回跳和 capability 降级测试。
│        └─ OpsnookUITests/
│           ├─ ActivityModelTests.swift              # 活动模型筛选/格式化测试。
│           ├─ LocalizationTests.swift               # 中英文文案 key 覆盖测试。
│           ├─ PanelLayoutTests.swift                # 面板高度、刘海宽度、图标资源等 UI 纯函数测试。
│           └─ WorkspaceModelTests.swift             # 工作区 ViewModel 操作和错误态测试。
├─ design/                                           # 高保真设计稿和官网/App icon 设计资源。
│  ├─ Opsnook-website.html                              # 官网/营销页设计稿或静态页面草稿。
│  ├─ appicon/
│  │  └─ OpsnookAppIcon.svg                             # App icon 矢量源。
│  ├─ index.html                                     # 设计入口页。
│  └─ mockups.html                                   # 主产品高保真稿:刘海、面板、活动、用量、设置等。
├─ docs/                                             # 产品、技术与接入调研文档。
│  ├─ PROJECT_FILE_GUIDE.md                          # 本文件:给维护者看的文件导览和缺陷定位地图。
│  ├─ AGENT_INTEGRATION_PLAN.md                      # Agent 接入规划与现状口径。
│  ├─ CODE_TO_FEATURE_MAP.md                         # 从界面元素到代码的对照表。
│  ├─ FEATURES.md                                    # 已实现功能总览、调试开关与代码导航。
│  ├─ PRD.md                                         # 产品需求文档。
│  ├─ SANDBOX.md                                     # App Sandbox 约束、能力降级与文件访问实现。
│  ├─ TECHNICAL_DESIGN.md                            # 技术设计文档。
│  └─ sessions_status_logic/
│     ├─ README.md                                    # 各 Agent 状态判定总览与共用引擎机制。
│     ├─ antigravity-cli.md                           # Antigravity CLI 与桌面端状态逻辑。
│     ├─ claude-code-cli.md                           # Claude Code CLI 状态逻辑。
│     ├─ claude-code-client.md                        # Claude Code 桌面端状态逻辑。
│     ├─ codex-cli.md                                 # Codex CLI 状态逻辑。
│     ├─ codex-client.md                              # Codex 桌面端状态逻辑。
│     ├─ qoder.md                                     # Qoder Quest 状态逻辑。
│     ├─ trae.md                                      # TRAE SOLO 状态逻辑。
│     ├─ workbuddy.md                                 # WorkBuddy 状态逻辑。
│     └─ zcode.md                                     # ZCode 状态逻辑。
├─ images/                                           # 文档使用的截图。README 的演示视频托管在 GitHub 附件 CDN,不入库。
│  └─ session-timeline.png                           # 会话时间轴窗口截图,用于 FEATURES.md 1.13 节。
└─ scripts/
   ├─ make-dmg.sh                                    # 将现有 Opsnook.app 打包为带 Applications 软链的 dist/Opsnook.dmg。
   └─ package-appstore.sh                            # 打包可运行的 .app 与 zip,供本机或他人机器自测。产物不是上传用的 .pkg。

为方便直接搜索路径，这里再列一次完整相对路径清单：

.github/ISSUE_TEMPLATE/agent_request.yml
.github/ISSUE_TEMPLATE/bug_report.yml
.github/ISSUE_TEMPLATE/config.yml
.github/PULL_REQUEST_TEMPLATE.md
.github/scripts/select-xcode.sh
.github/workflows/ci.yml
.gitignore
AGENTS.md
App/AppDelegate.swift
App/Composition/AppContainer.swift
App/Composition/DirectoryAccessModel.swift
App/Config/AppStore.xcconfig
App/Config/Base.xcconfig
App/Entitlements/Opsnook.AppStore.entitlements
App/OpsnookApp.swift
App/Resources/Assets.xcassets/AppIcon.appiconset/Contents.json
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_1024.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_128.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_16.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_256.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_32.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_512.png
App/Resources/Assets.xcassets/AppIcon.appiconset/icon_64.png
App/Resources/Assets.xcassets/Contents.json
App/Resources/Info.plist
App/Resources/Localizable.xcstrings
App/Resources/PrivacyInfo.xcprivacy
App/Windows/GlobalHotKey.swift
App/Windows/NotchWindowController.swift
App/Windows/NotchWindowManager.swift
App/Windows/ScreenGeometry.swift
App/Windows/TimelineWindowController.swift
CHANGELOG.md
CONTRIBUTING.md
LICENSE
LICENSE-EXCEPTION.md
Packages/OpsnookKit/Package.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/AdapterLimits.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/AdapterRegistry.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/AgentAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/AgentCatalog.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravityAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravitySessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravitySubagentMessages.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravityTimelineParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeCodeAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeHookRequestParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeSessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeTimelineParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexSessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexTimelineParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Gemini/GeminiAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Gemini/GeminiSessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/GitHead.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderQuestStore.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderSessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderTimelineParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/SessionFileFingerprint.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ShellCommandClassifier.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeProjectPath.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeRuntimeProbe.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeSessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/Usage/UsageReader.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddyAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddySessionParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddyTimelineParser.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeAdapter.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeSessionStore.swift
Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeStatusMap.swift
Packages/OpsnookKit/Sources/OpsnookCore/Capability/Capabilities.swift
Packages/OpsnookKit/Sources/OpsnookCore/Layout/NotchLayout.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentDescriptor.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentEvent.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentKind.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentSession.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentStatus.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/AggregateSnapshot.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/Approval.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/CapabilityLevel.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/ModelDisplay.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/ModelPricing.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/Question.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionSnapshot.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionTimeline.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionTranscript.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/SubagentBrief.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/TokenUsage.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/UsageSnapshot.swift
Packages/OpsnookKit/Sources/OpsnookCore/Models/WorkspaceSnapshot.swift
Packages/OpsnookKit/Sources/OpsnookCore/Opsnook.swift
Packages/OpsnookKit/Sources/OpsnookCore/Settings/AppLanguageController.swift
Packages/OpsnookKit/Sources/OpsnookCore/State/AggregateBuilder.swift
Packages/OpsnookKit/Sources/OpsnookCore/State/EngineConfig.swift
Packages/OpsnookKit/Sources/OpsnookCore/State/SessionReducer.swift
Packages/OpsnookKit/Sources/OpsnookCore/State/UsageAggregator.swift
Packages/OpsnookKit/Sources/OpsnookCore/Store/SessionStore.swift
Packages/OpsnookKit/Sources/OpsnookCore/Util/ActivityText.swift
Packages/OpsnookKit/Sources/OpsnookCore/Util/TimeSource.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/FileAccess/AgentDirectoryAccess.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/FileAccess/SecurityScopedBookmarkStore.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Focus/ApplicationFocuser.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Focus/TerminalFocuser.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Hooks/ClaudeHooksInstaller.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Integration.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/LaunchAtLogin/LaunchAtLoginController.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Notifications/NotificationCoordinator.swift
Packages/OpsnookKit/Sources/OpsnookIntegration/Workspace/GitWorkspaceService.swift
Packages/OpsnookKit/Sources/OpsnookUI/Brand/OpsnookBrandMark.swift
Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/Formatting.swift
Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/OpsnookColor.swift
Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/OpsnookMetrics.swift
Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/ScrollbarlessScrollView.swift
Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/Waveform.swift
Packages/OpsnookKit/Sources/OpsnookUI/Localization/OpsnookL10n.swift
Packages/OpsnookKit/Sources/OpsnookUI/Notch/AgentBrandIcon.swift
Packages/OpsnookKit/Sources/OpsnookUI/Notch/AgentIconView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Notch/NotchCollapsedView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Notch/NotchRootView.swift
Packages/OpsnookKit/Sources/OpsnookUI/OpsnookUI.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/ActivityView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/PanelRow.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/PanelView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/QuestionCard.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/SubagentRow.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/TranscriptPeekView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/UsageView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Panel/WorkspaceView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/LICENSE.lobe-icons.txt
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-claude.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-claude.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-codebuddy.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-codebuddy.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-gemini.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-gemini.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-openai.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-openai.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-qoder.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-qoder.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-trae.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-trae.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-zai.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/lobe-zai.svg
Packages/OpsnookKit/Sources/OpsnookUI/Resources/BrandIcons/opsnook-brand.png
Packages/OpsnookKit/Sources/OpsnookUI/Resources/Localizable.xcstrings
Packages/OpsnookKit/Sources/OpsnookUI/Resources/en.lproj/Localizable.strings
Packages/OpsnookKit/Sources/OpsnookUI/Resources/zh-Hans.lproj/Localizable.strings
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/SessionTimelineModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/SessionTimelineView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineCanvasView.swift
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineDetailPanel.swift
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineImageExporter.swift
Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineStyle.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/ActivityModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/AgentDiscoveryModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/NotchUIState.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/OpsnookViewModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/TranscriptPeekModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/UsageModel.swift
Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/WorkspaceModel.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/AntigravityAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/AntigravityTimelineParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeCodeAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeHookRequestParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeSessionParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeTimelineParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/CodexAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/CodexParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/CodexTimelineParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/GeminiAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/GeminiSessionParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/OpsnookAdaptersTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/QoderAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/QoderTimelineParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ShellCommandClassifierTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/TraeAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/UsageParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/WorkBuddyAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/WorkBuddyTimelineParserTests.swift
Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ZCodeAdapterTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/AppLanguageControllerTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/CapabilitiesTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/ModelDisplayTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/ModelTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/NotchLayoutTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/OpsnookCoreTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/SessionStoreTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/SessionTranscriptTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/StateMachineTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/TimelineEventCoalescingTests.swift
Packages/OpsnookKit/Tests/OpsnookCoreTests/UsageTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/AgentDirectoryAccessTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/ApplicationFocuserTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/ClaudeHooksInstallerTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/GitWorkspaceServiceTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/LaunchAtLoginControllerTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/NotificationCoordinatorTests.swift
Packages/OpsnookKit/Tests/OpsnookIntegrationTests/TerminalFocuserTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/ActivityModelTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/FormattingTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/LocalizationTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/PanelLayoutTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/SessionTimelineModelTests.swift
Packages/OpsnookKit/Tests/OpsnookUITests/WorkspaceModelTests.swift
README.md
SECURITY.md
design/appicon/OpsnookAppIcon-1024-plated.png
design/appicon/OpsnookAppIcon-1024.png
design/appicon/makeicon.swift
design/index.html
design/mockups.html
docs/AGENT_INTEGRATION_PLAN.md
docs/CODE_TO_FEATURE_MAP.md
docs/FEATURES.md
docs/PRD.md
docs/PROJECT_FILE_GUIDE.md
docs/SANDBOX.md
docs/TECHNICAL_DESIGN.md
docs/sessions_status_logic/README.md
docs/sessions_status_logic/antigravity-cli.md
docs/sessions_status_logic/claude-code-cli.md
docs/sessions_status_logic/claude-code-client.md
docs/sessions_status_logic/codex-cli.md
docs/sessions_status_logic/codex-client.md
docs/sessions_status_logic/qoder.md
docs/sessions_status_logic/trae.md
docs/sessions_status_logic/workbuddy.md
docs/sessions_status_logic/zcode.md
images/session-timeline.png
project.yml
scripts/make-dmg.sh
scripts/package-appstore.sh

3. Swift 文件职责与 UI 对应

3.0 Package 清单

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Package.swift`	SwiftPM manifest：定义 OpsnookCore/OpsnookAdapters/OpsnookIntegration/OpsnookUI 四个库、测试 target、资源处理和 sqlite3 链接。	不直接渲染 UI，但决定所有模块、资源和测试能否编译。

3.1 App target

Swift 文件	具体功能	对应/影响 UI
`App/OpsnookApp.swift`	App 入口；声明 LSUIElement 型 Settings 场景；实现 `OpsnookSettingsContent` 和系统设置回退窗口。	设置页：面板齿轮内嵌页和 Command-, 系统设置窗口。
`App/AppDelegate.swift`	启动 AppContainer、Store、ViewModels、NotchWindowController；注册快捷键；协调 Agent 扫描、Claude 审批回传、工作区授权、设置页注入。	整个 App 的运行入口；刘海、面板、设置、工作区授权都经这里接线。
`App/Composition/AppContainer.swift`	固定 `.appStore` capabilities；创建 SessionStore/AdapterRegistry；按已授权目录注册 Claude/Codex/Antigravity/ZCode/WorkBuddy；转发用量、工作区、transcript、审批、授权操作。	不直接渲染 UI，但决定哪些 Agent 出现在会话页、用量页、活动页和工作区页。
`App/Composition/DirectoryAccessModel.swift`	设置页 Agent 目录授权模型；弹 NSOpenPanel 让用户授权 `.claude`、`.codex`、`.gemini`、`.zcode`、`.workbuddy`。	设置页“Agent 数据访问”列表、授权按钮、错误提示。
`App/Windows/GlobalHotKey.swift`	注册/释放全局热键，回调给窗口控制器。	Option-Command-H 展开/收起刘海面板。
`App/Windows/NotchWindowController.swift`	创建可覆盖菜单栏的 NSPanel；控制收起/展开 frame 动画、hover、固定、tab 切换测高、专注模式、回跳、transcript 预览。	刘海收起态、展开面板、所有 tab 的窗口尺寸和动画。
`App/Windows/ScreenGeometry.swift`	计算屏幕可视区域、safe area、菜单栏高度、刘海宽度和窗口定位。	刘海贴合菜单栏、外接屏/无刘海屏定位、面板不偏移。
`App/Windows/TimelineWindowController.swift`	会话时间轴独立窗口管理：每会话一扇 NSWindow、重复打开前置复用、暗色外观。	右键会话行「查看会话时间轴」打开的窗口。

3.2 OpsnookCore：纯逻辑层

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Sources/OpsnookCore/Opsnook.swift`	包级常量，例如版本号。	启动日志/关于信息等需要版本时使用。
`Packages/OpsnookKit/Sources/OpsnookCore/Capability/Capabilities.swift`	App Store capabilities 单一来源：文件访问、hooks、focus、workspace 等能力开关。	所有降级 UI：设置授权、工作区不可用、回跳只激活 App 等。
`Packages/OpsnookKit/Sources/OpsnookCore/Layout/NotchLayout.swift`	收起态窗口宽度、左右翼内容宽度预算等纯计算。	收起态 pill 长短、图标是否被挤压、状态徽标是否裁切。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentDescriptor.swift`	Agent 能力、检测方式、发现结果、接入动作、接入反馈。	设置/接入向导里的 Agent 列表、能力显示和安装/复制配置反馈。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentEvent.swift`	活动时间线事件，包括开始、完成、出错、审批、用户操作。	活动 Tab 每一条时间线记录。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentKind.swift`	Agent id、展示名、品牌色和图标资产名。	所有 Agent 图标、名称、品牌色显示。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentSession.swift`	会话主模型：状态、任务标题、项目、分支、审批、问题、错误、回跳目标、资源路径。	会话页行、收起态聚合、活动页回跳、工作区 Agent 关联。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AgentStatus.swift`	六种状态、排序权重、状态分组。	会话页分组顺序、状态颜色、收起态最高优先级。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/AggregateSnapshot.swift`	收起态需要的一次聚合快照。	刘海左右翼图标、运行数、审批/等待/错误计数。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/Approval.swift`	审批请求和 allow/deny 决策模型，以及错误信息。	会话页审批卡片和错误状态行。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/CapabilityLevel.swift`	Agent L1/L2/L3 能力等级。	接入状态和能力降级文案。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/ModelPricing.swift`	已知模型单价表和成本计算。	用量页成本估算卡片和“估算”说明。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/Question.swift`	等待输入问题、选项、提示。	`QuestionCard` 只读问题卡。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionSnapshot.swift`	适配器上报给 Store 的输入模型；包含 `AdapterEmission` 和 health。	所有 UI 状态变化的入口，不直接显示但决定最终会话状态。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionTimeline.swift`	会话时间轴模型：事件卡（7 类/5 态/facts/原始 JSON 行）与泳道（spawn/merge 链接）。	会话时间轴窗口的全部数据。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/SessionTranscript.swift`	transcript 消息、角色、anchor 定位。	活动页消息预览滚到对应用户消息。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/TokenUsage.swift`	输入/输出/cache token 计数。	用量页 token 统计。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/UsageSnapshot.swift`	用量页完整展示数据：配额、今日/7日、趋势、按 Agent。	用量 Tab。
`Packages/OpsnookKit/Sources/OpsnookCore/Models/WorkspaceSnapshot.swift`	工作区页所有模型：仓库、Agent 上下文、文件改动、diff、commit、目录树、错误。	工作区 Tab 的文件树、Git 面板、commit timeline、错误/授权态。
`Packages/OpsnookKit/Sources/OpsnookCore/Settings/AppLanguageController.swift`	语言选择、UserDefaults 保存、locale 计算。	设置页语言选择；所有 OpsnookUI/App 文案 locale。
`Packages/OpsnookKit/Sources/OpsnookCore/State/AggregateBuilder.swift`	从会话数组构造收起态聚合，并控制显示排序。	刘海左翼图标、右翼状态徽标、计数。
`Packages/OpsnookKit/Sources/OpsnookCore/State/EngineConfig.swift`	done 衰减、active 窗口等状态引擎参数。	完成态显示多久、历史完成是否衰减到 idle 等。
`Packages/OpsnookKit/Sources/OpsnookCore/State/SessionReducer.swift`	纯状态机：合并新快照，派生事件，处理 done->idle 衰减、首次历史完成等边界。	会话行状态、活动事件是否出现、启动时是否闪“完成”。
`Packages/OpsnookKit/Sources/OpsnookCore/State/UsageAggregator.swift`	把用量样本和配额聚合成 UsageSnapshot。	用量页所有数字和 7 日趋势。
`Packages/OpsnookKit/Sources/OpsnookCore/Store/SessionStore.swift`	actor 唯一真相源；串行 ingest；发布 `publications()` 给 UI，发布 `events()` 给活动页。	所有实时 UI 的数据源。
`Packages/OpsnookKit/Sources/OpsnookCore/Util/ActivityText.swift`	活动事件显示文本辅助。	活动页主行文案/消息摘要。
`Packages/OpsnookKit/Sources/OpsnookCore/Util/TimeSource.swift`	可注入时间源。	间接影响所有计时/衰减/测试稳定性。

3.3 OpsnookAdapters：Agent 数据解析层

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Sources/OpsnookAdapters/AdapterLimits.swift`	任务标题、摘要等截断上限。	会话行标题、活动页消息不超长。
`Packages/OpsnookKit/Sources/OpsnookAdapters/AdapterRegistry.swift`	管理 adapter 注册、并发 detect、启动流、transcript 分发。	Agent 是否被发现、会话是否进入 UI、活动页能否预览 transcript。
`Packages/OpsnookKit/Sources/OpsnookAdapters/AgentAdapter.swift`	adapter 协议：detect/start/respond/terminate/focus/loadTranscript/prepareIntegration。	所有 Agent 接入能力的统一接口。
`Packages/OpsnookKit/Sources/OpsnookAdapters/AgentCatalog.swift`	Agent id/brand/id/icon 的单一来源。	UI 名称、图标、颜色和 adapter 分支判断。
`Packages/OpsnookKit/Sources/OpsnookAdapters/GitHead.swift`	从 `.git/HEAD` 和 worktree gitdir 读取分支。	会话行副标题、工作区 Agent 上下文中的分支。
`Packages/OpsnookKit/Sources/OpsnookAdapters/SessionFileFingerprint.swift`	读取文件大小/mtime 指纹。	减少重复解析，避免 UI 每 1.5s 无意义刷新。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ShellCommandClassifier.swift`	shell 命令行为分类：切段 → 剥包装(sudo/env/xargs) → 可执行文件定族 → 子命令/参数细分（sed -n/-i、swift build/run、npm ci/run、eslint --fix）→ 重定向副作用（`>` 创建 `>>` 追加）→ 混合段取「最重」行为，未知一律 run。	时间轴卡片按行为分色：读取/检索/创建/修改/删除/Git/依赖/构建测试/网络/命令执行。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Usage/UsageReader.swift`	按需扫描近期 Claude/Codex/Gemini 会话文件，提取 UsageSample 和 Codex 配额。	用量 Tab 首次打开/刷新时的数据。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravityAdapter.swift`	扫描 Antigravity CLI 和桌面 brain 目录；输出 L2 会话；支持 transcript 读取。	会话页 Antigravity 行、活动页 Antigravity 预览。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravitySessionParser.swift`	解析 Antigravity transcript，宽容提取状态、标题、cwd、消息；INVOKE_SUBAGENT 派生登记。	Antigravity 状态/标题/项目显示是否正确；子会话折叠归位。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravitySubagentMessages.swift`	解析父目录 messages/*.json（子代理站内信）：sender → 展示名/完成时间。	面板 subagent 芯片的名称与完成时间；时间轴子泳道名。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Antigravity/AntigravityTimelineParser.swift`	Antigravity transcript → 会话时间轴：步骤按 type 分型，INVOKE_SUBAGENT → 子会话分叉泳道。	Antigravity 会话的时间轴窗口。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeCodeAdapter.swift`	扫描 Claude projects JSONL、sessions JSON、hook requests；处理审批/问题卡/错误/保活；写决策文件。	Claude 会话行、审批卡、问题卡、活动页预览和回传。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeHookRequestParser.swift`	解析 Claude hook request 文件，区分 PermissionRequest 和 AskUserQuestion。	审批卡 vs 问题卡是否正确出现。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeSessionParser.swift`	解析 Claude JSONL：状态、标题、错误、messages、usage、desktop/CLI。	Claude 会话标题、状态、活动消息、用量页。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ClaudeCode/ClaudeTimelineParser.swift`	Claude JSONL → 全过程时间轴：tool_use 分型、tool_result 按 id 配对、同目录 `agent-*.jsonl` 子泳道。	会话时间轴窗口（Claude 会话）。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexTimelineParser.swift`	Codex rollout → 全过程时间轴：call_id 配对、apply_patch 文件卡、spawn/close_agent 子泳道（独立 rollout 文件）。	会话时间轴窗口（Codex 会话）。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexAdapter.swift`	扫描 Codex sessions JSONL 和 session_index；区分 desktop/CLI；读取 transcript。	Codex/Codex CLI 会话行、活动页预览、用量页配额。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Codex/CodexSessionParser.swift`	解析 Codex rollout JSONL：session id、originator、状态、消息、rate_limits。	Codex 状态、标题、desktop/CLI 来源、用量配额。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Gemini/GeminiAdapter.swift`	历史 Gemini CLI adapter，当前 `AppContainer` 不注册。	当前一般不影响 UI；如恢复 Gemini 支持再看它。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Gemini/GeminiSessionParser.swift`	解析 Gemini chat JSON 和 usage。	主要影响用量页历史 Gemini 统计；若恢复 Gemini 会影响会话页。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderAdapter.swift`	读 state.vscdb 的 questTaskListSnapshot（权威 Quest 列表），进程存活作活跃闸门；执行 JSONL 按指纹缓存提取 subagent 摘要。	Qoder 会话行、状态、面板 subagent 芯片。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderQuestStore.swift`	Qoder state.vscdb(SQLite)查询层。	Qoder 数据是否读得到。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderSessionParser.swift`	Quest 快照 JSON → 会话状态/标题/工作目录。	Qoder 状态、标题、项目显示。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Qoder/QoderTimelineParser.swift`	Qoder 执行 JSONL → 会话时间轴 / transcript 消息 / subagent 摘要（Agent tool_call 按 tool_use_id 配对）。	Qoder 会话的时间轴窗口、消息预览、subagent 状态。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeAdapter.swift`	读 TRAE memory 摘要 + 可选运行时目录探针，输出 L2 会话。	TRAE SOLO 会话行、实时运行态。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeProjectPath.swift`	TRAE 编码 cwd 目录名还原（贪心路径回溯）。	TRAE 会话的项目名/分支。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeRuntimeProbe.swift`	运行时目录 SessionUpdated 日志探针(Running/Waiting/Finished)。	TRAE 实时运行/等待状态。
`Packages/OpsnookKit/Sources/OpsnookAdapters/Trae/TraeSessionParser.swift`	TRAE session_memory JSONL 摘要解析。	TRAE 标题与末态。
`Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddyAdapter.swift`	扫描 WorkBuddy projects transcript 和 sessions 心跳，输出 L2 会话。	WorkBuddy 会话行、保活、活动页预览。
`Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddySessionParser.swift`	解析 WorkBuddy Responses-API 风格 transcript；Agent 调用 → subagent 摘要（已结束的保留到下一批派生）。	WorkBuddy 状态、标题、项目、消息预览、面板 subagent 芯片。
`Packages/OpsnookKit/Sources/OpsnookAdapters/WorkBuddy/WorkBuddyTimelineParser.swift`	WorkBuddy JSONL → 会话时间轴：callId 配对、复用 Claude 工具分型、[Agent ID] 关联子泳道。	WorkBuddy 会话的时间轴窗口。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeAdapter.swift`	读取 ZCode `cli/db/db.sqlite`；状态由最新消息推导；回跳 App。	ZCode 会话行、等待问题、活动页预览。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeSessionStore.swift`	ZCode SQLite 表查询，生成 session row 和 transcript messages。	ZCode 数据是否读得到。
`Packages/OpsnookKit/Sources/OpsnookAdapters/ZCode/ZCodeStatusMap.swift`	ZCode 最新 role/finish_reason/时间 -> Opsnook 状态。	ZCode 运行、完成、等待、错误状态。

3.4 OpsnookIntegration：系统副作用层

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Sources/OpsnookIntegration/Integration.swift`	target 标记文件。	无直接 UI。
`Packages/OpsnookKit/Sources/OpsnookIntegration/FileAccess/AgentDirectoryAccess.swift`	定义 Agent 目录 key；通过书签返回用户真实目录；沙盒下 `homeDirectoryForCurrentUser` 不可信。	设置页授权状态、Agent 是否能被注册。
`Packages/OpsnookKit/Sources/OpsnookIntegration/FileAccess/SecurityScopedBookmarkStore.swift`	保存/解析安全作用域书签，长期持有访问态。	App 重启后是否还能读 Agent/工作区目录。
`Packages/OpsnookKit/Sources/OpsnookIntegration/Focus/ApplicationFocuser.swift`	通过 bundle id 激活 App。	App Store 降级回跳：只能激活 Terminal/Codex/ZCode 等 App。
`Packages/OpsnookKit/Sources/OpsnookIntegration/Focus/TerminalFocuser.swift`	根据 FocusTarget 和 capabilities 聚焦终端/App，并暴露 accessibilityState。	点击会话行、活动行、工作区 Agent 行后的回跳。
`Packages/OpsnookKit/Sources/OpsnookIntegration/Hooks/ClaudeHooksInstaller.swift`	准备 Claude hook runtime；生成阻塞脚本；修改或提供 Claude settings 配置。	设置/接入向导中的 Claude 接入；Claude 审批卡能否回传。
`Packages/OpsnookKit/Sources/OpsnookIntegration/LaunchAtLogin/LaunchAtLoginController.swift`	登录项开关、状态刷新、错误保存。	设置页“开机自启” toggle。
`Packages/OpsnookKit/Sources/OpsnookIntegration/Notifications/NotificationCoordinator.swift`	根据 Store 事件生成视觉通知 cue；维护专注模式偏好。	刘海审批/等待 pulse、完成闪烁、专注模式。
`Packages/OpsnookKit/Sources/OpsnookIntegration/Workspace/GitWorkspaceService.swift`	调用 `/usr/bin/git` 读取仓库状态、diff、commit log，并执行 stage/unstage/commit/push/revert；还支持目录列表和文件移动。	工作区 Tab 文件树、Git 面板、提交/推送/回滚/打开文件。

3.5 OpsnookUI：视图和 ViewModel

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Sources/OpsnookUI/OpsnookUI.swift`	target 标记文件。	无直接 UI。
`Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/Formatting.swift`	时间、状态、事件、金钱、token、字幕等格式化。	会话页副标题/计时、活动页、用量页。
`Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/OpsnookColor.swift`	颜色 token，状态色，品牌色，hex helper。	全部 SwiftUI 颜色。
`Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/OpsnookMetrics.swift`	面板宽度/高度/动画/间距/收起态宽度等 token。	所有布局尺寸，尤其刘海和面板。
`Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/ScrollbarlessScrollView.swift`	无滚动条 NSScrollView 包装，避免系统滚动条占位。	设置页 Agent 列表、工作区文件树/Git 内容。
`Packages/OpsnookKit/Sources/OpsnookUI/DesignSystem/Waveform.swift`	Core Animation 波形和 pulse modifier。	运行态绿色波形、审批/等待 pulse。
`Packages/OpsnookKit/Sources/OpsnookUI/Localization/OpsnookL10n.swift`	从 Bundle/module 读取本地化字符串并格式化。	OpsnookUI 所有可见文案。
`Packages/OpsnookKit/Sources/OpsnookUI/Notch/AgentBrandIcon.swift`	根据 `AgentBrand.iconAsset` 渲染 Lobe PNG/SVG 或 SF Symbol fallback。	收起态 mini icon、会话行头像、用量/活动/设置图标。
`Packages/OpsnookKit/Sources/OpsnookUI/Notch/AgentIconView.swift`	圆形头像底色、图标、状态点。	会话行、活动行、用量行、工作区 Agent 行。
`Packages/OpsnookKit/Sources/OpsnookUI/Notch/NotchCollapsedView.swift`	收起态左右翼，显示 Agent mini icons、运行波形、审批/等待/错误/完成/空闲。	顶部刘海常驻 UI。
`Packages/OpsnookKit/Sources/OpsnookUI/Notch/NotchRootView.swift`	根据 `NotchUIState.contentExpanded` 切换收起态和展开面板，并注入 tab 回调。	整个刘海窗口的 SwiftUI 根。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/ActivityView.swift`	活动 Tab 时间线，分今天/昨天/更早，支持 hover 和点击。	展开面板“活动”页。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/PanelRow.swift`	单个 Agent 会话行：头像、标题、副标题、状态、计时。	展开面板“会话”页列表。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/PanelView.swift`	展开面板总容器：header、内容区、底部 tabs、设置页、活动过滤、审批卡、空态、滚动高度。	展开面板所有页面的外框和 tab 切换。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/QuestionCard.swift`	显示 AskUserQuestion 的问题和选项，只读不回传 allow/deny。	会话页等待输入卡片。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/TranscriptPeekView.swift`	transcript 消息列表，定位 anchor，返回活动页/跳回终端。	活动页点击事件后的内嵌消息预览。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/UsageView.swift`	用量页 UI：配额、成本/token 卡片、7 日趋势、按 Agent 明细、空/加载态。	展开面板“用量”页。
`Packages/OpsnookKit/Sources/OpsnookUI/Panel/WorkspaceView.swift`	工作区 UI：仓库选择、文件树、拖拽移动、Git 改动、diff、commit、push、错误和授权态。	展开面板“工作区”页。
`Packages/OpsnookKit/Sources/OpsnookUI/Timeline/SessionTimelineModel.swift`	时间轴 ViewModel：布局算法（同类连续分组堆叠、堆叠方向、两级收起、分叉/汇入点轴钉）、筛选/搜索/选中/缩放平移。	会话时间轴窗口全部交互。
`Packages/OpsnookKit/Sources/OpsnookUI/Timeline/SessionTimelineView.swift`	时间轴三栏根视图：工具栏（横竖版切换、错误/工具跳转、分组框开关、缩放）、控制台侧栏、详情开合；语言直读 `AppLanguageController`。	会话时间轴窗口骨架。
`Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineCanvasView.swift`	画布：泳道线与肘形分叉/汇入、事件卡（泳道配色）、分组虚线框、缩略图、平移缩放手势。	时间轴画布与卡片。
`Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineDetailPanel.swift`	事件详情面板：关键字段、完整 JSON（美化）、复制、上下文前后 5 事件。	时间轴右侧详情。
`Packages/OpsnookKit/Sources/OpsnookUI/Timeline/TimelineStyle.swift`	时间轴视觉 token：事件类别/状态配色与图标、泳道调色板、时长格式。	时间轴配色一致性。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/ActivityModel.swift`	订阅 Store 事件，倒序保留 7 天，支持按 Agent 过滤。	活动 Tab 的数据和漏斗筛选。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/AgentDiscoveryModel.swift`	保存发现/扫描/接入中的 Agent 状态和反馈。	空态/接入向导/设置页中的 Agent 发现提示。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/OpsnookViewModel.swift`	订阅 Store publications，提供 sessions、aggregate、分组和计数。	会话页、收起态、header 计数。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/NotchUIState.swift`	保存 UI 状态：是否展开、固定、专注模式、tab、尺寸、完成 cue。	刘海窗口行为和当前 tab。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/TranscriptPeekModel.swift`	活动页点击事件后加载 transcript；没有 transcript 时降级回跳。	transcript 预览页的 loading/loaded/hidden 状态。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/UsageModel.swift`	按需调用 loader 拉取 UsageSnapshot，防止重复扫描。	用量 Tab loading/refresh。
`Packages/OpsnookKit/Sources/OpsnookUI/ViewModels/WorkspaceModel.swift`	工作区状态机：刷新仓库、选择仓库、过滤 Agent、stage/commit/push/revert、文件树展开、拖拽移动、沙盒授权。	工作区 Tab 的所有交互。

3.6 测试 Swift 文件

Swift 文件	具体功能	对应/影响 UI
`Packages/OpsnookKit/Tests/OpsnookCoreTests/AppLanguageControllerTests.swift`	验证语言选择、系统语言 fallback、locale。	防止设置页语言切换和本地化环境坏掉。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/CapabilitiesTests.swift`	验证 App Store capabilities。	防止误开非沙盒能力或降级路径错。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/OpsnookCoreTests.swift`	OpsnookCore 基础 smoke test。	无直接 UI，保证 target 可用。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/ModelTests.swift`	验证状态排序、聚合模型等基础模型行为。	防止会话排序/状态显示异常。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/NotchLayoutTests.swift`	验证收起态宽度、刘海 gap 等布局计算。	防止收起态 pill 过长/过短/裁切。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/SessionStoreTests.swift`	验证 Store ingest、发布、事件、衰减、延迟预算。	防止所有实时 UI 不刷新或事件漏发。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/SessionTranscriptTests.swift`	验证 transcript anchor 定位。	防止活动页消息预览跳错消息。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/StateMachineTests.swift`	验证 reducer 状态跃迁、事件派生、AggregateBuilder。	防止会话页/收起态状态语义回归。
`Packages/OpsnookKit/Tests/OpsnookCoreTests/UsageTests.swift`	验证 UsageAggregator 和 ModelPricing。	防止用量页数字/成本错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/AntigravityAdapterTests.swift`	验证 Antigravity parser、adapter 扫描、来源区分。	防止 Antigravity 行不显示或状态错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeCodeAdapterTests.swift`	验证 Claude adapter 扫描、审批、问题卡、错误、transcript。	防止 Claude 核心 L3 体验回归。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeHookRequestParserTests.swift`	验证 hook request JSON 解析。	防止审批卡/问题卡误判。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ClaudeSessionParserTests.swift`	验证 Claude JSONL parser。	防止 Claude 标题、状态、用量、消息预览错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/CodexAdapterTests.swift`	验证 Codex adapter、desktop/CLI 区分、registry。	防止 Codex/Codex CLI 会话显示和 transcript 预览错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/CodexParserTests.swift`	验证 Codex parser 和 rate_limits。	防止 Codex 用量配额/状态/标题错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/GeminiAdapterTests.swift`	验证历史 Gemini adapter。	主要保护未来恢复 Gemini 支持。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/GeminiSessionParserTests.swift`	验证 Gemini parser。	保护用量页 Gemini 样本和未来 Gemini UI。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/OpsnookAdaptersTests.swift`	OpsnookAdapters target smoke test。	无直接 UI。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/UsageParserTests.swift`	验证各 Agent usage parser。	防止用量页各 Agent 统计错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/WorkBuddyAdapterTests.swift`	验证 WorkBuddy parser、心跳、adapter。	防止 WorkBuddy 会话/保活/消息预览错。
`Packages/OpsnookKit/Tests/OpsnookAdaptersTests/ZCodeAdapterTests.swift`	验证 ZCode SQLite store、状态映射、adapter。	防止 ZCode 会话/问题/状态错。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/AgentDirectoryAccessTests.swift`	验证 Agent 目录书签和真实 home 解析。	防止设置页授权后仍读不到目录。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/ApplicationFocuserTests.swift`	验证 App 级回跳。	防止 App Store 降级回跳失效。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/ClaudeHooksInstallerTests.swift`	验证 Claude hooks runtime/install/manual snippet。	防止 Claude 审批通道不可用。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/GitWorkspaceServiceTests.swift`	验证 GitWorkspaceService 读取和操作。	防止工作区 Git 页坏掉。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/LaunchAtLoginControllerTests.swift`	验证登录项控制器。	防止设置页开机自启状态错。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/NotificationCoordinatorTests.swift`	验证视觉通知 cue 和专注模式。	防止刘海 pulse/完成闪烁/静默错。
`Packages/OpsnookKit/Tests/OpsnookIntegrationTests/TerminalFocuserTests.swift`	验证终端回跳和 capability 降级。	防止点击会话不能回到正确 App/终端。
`Packages/OpsnookKit/Tests/OpsnookUITests/ActivityModelTests.swift`	验证活动模型、筛选、事件文案。	防止活动 Tab 顺序/过滤/文案错。
`Packages/OpsnookKit/Tests/OpsnookUITests/LocalizationTests.swift`	验证 OpsnookUI 中英文 key 覆盖。	防止新增文案漏翻译。
`Packages/OpsnookKit/Tests/OpsnookUITests/PanelLayoutTests.swift`	验证面板高度、收起态宽度与图标资源。	防止面板跳动、裁切或图标缺失。
`Packages/OpsnookKit/Tests/OpsnookUITests/WorkspaceModelTests.swift`	验证工作区 ViewModel 选择、操作、错误态和文件树。	防止工作区交互回归。

4. 常见 bug 的定位路线

4.1 Agent 明明在跑，会话页没有显示

AppContainer.registerAdaptersIfNeeded() 是否注册了对应 adapter。
沙盒目录是否授权：DirectoryAccessModel -> AgentDirectoryAccess -> SecurityScopedBookmarkStore。
对应 adapter 的 detect() 和 scanOnce() 是否发现文件。
parser 是否能从真实文件里生成 SessionSnapshot。
SessionStore.ingest(_:) 是否收到 .sessionUpserted。
OpsnookViewModel.sessions 是否更新。

4.2 状态颜色/排序/分组不对

单个状态来源：对应 *SessionParser.swift 或 *Adapter.swift。
状态跃迁：SessionReducer.swift。
分组和排序：AgentStatus.swift、AggregateBuilder.swift、Array.sortedForDisplay()。
UI 颜色和文案：OpsnookColor.swift、Formatting.swift、OpsnookL10n.swift。

4.3 刘海 pill 长度、位置、动画不对

纯计算：NotchLayout.swift、OpsnookMetrics.swift。
SwiftUI 内容：NotchCollapsedView.swift、NotchRootView.swift。
窗口 frame/动画：NotchWindowController.swift、ScreenGeometry.swift。
相关测试：NotchLayoutTests.swift、PanelLayoutTests.swift。

4.4 Claude 审批卡不出现或按钮无效

hook runtime 是否生成：ClaudeHooksInstaller.swift。
hook request 是否解析：ClaudeHookRequestParser.swift。
adapter 是否把 request 变成 pendingApproval：ClaudeCodeAdapter.swift。
UI 是否显示卡片：PanelView.ApprovalCard。
点击是否回传：AppDelegate.onApprovalDecision -> AppContainer.respond -> ClaudeCodeAdapter.respond。
相关测试：ClaudeHookRequestParserTests.swift、ClaudeCodeAdapterTests.swift、ClaudeHooksInstallerTests.swift。

4.5 活动页点击后没有消息预览

Store 是否派生了 AgentEvent: SessionReducer.swift、SessionStore.swift。
ActivityModel 是否收到事件。
TranscriptPeekModel.present 是否拿到当前会话。
AdapterRegistry.loadTranscript 是否按 brand 找到 adapter。
对应 adapter 的 loadTranscript(for:) 是否能定位历史文件。
SessionTranscript.anchorMessageID 是否能定位消息。

4.6 用量页数字不对

用量页打开时 UsageModel.refresh() 是否触发。
AppContainer.usageReport() 是否传入了正确授权目录。
UsageReader.report() 是否扫到对应文件。
对应 parser 的 usageSamples / usageReport 是否识别新 schema。
UsageAggregator.aggregate 是否按日期、Agent、价格正确聚合。

4.7 工作区页不可用或 Git 操作失败

App Store 沙盒下是否授权工作区根目录。
WorkspaceModel.refresh(sessions:) 是否拿到带 projectPath 的会话。
GitWorkspaceService.snapshot(for:) 是否发现仓库。
/usr/bin/git 命令失败时看 WorkspaceFailure。
UI 禁用态在 WorkspaceView 和 WorkspaceModel.canCommit 等属性里。

4.8 会话时间轴打不开、解析为空或布局异常

右键菜单不出现：SessionTimelineSupport.canOpen 只放行 Claude/Codex 品牌且 sessionResourceURL 为 .jsonl 的会话。
打开后显示「没有可解析的事件」：老 Claude 会话主文件可能只剩 summary 行（正文缺失），属正常空态；否则看对应 *TimelineParser 是否识别该 schema。
subagent 泳道缺失：Claude 看同目录 agent-*.jsonl 首行 sessionId 是否匹配；Codex 看 spawn_agent output 的 agent_id 与同月目录 rollout-*-<agent_id>.jsonl 是否存在。
卡片位置/分组/收起异常：布局唯一入口是 SessionTimelineModel.layout（同类连续才入组、分叉/汇入点钉轴、收起事件不占槽）。
文案语言不跟随设置：时间轴窗口不经过 NotchRootView，根视图必须直读 AppLanguageController.shared.locale（勿改回 @Environment，见 SessionTimelineView 注释）。

5. 修改前后的最小检查

代码改动后通常跑：

cd Packages/OpsnookKit && swift test

触及 App/、project.yml、entitlements、resources 或窗口行为时，还应跑 App 构建：

xcodegen generate
xcodebuild -project Opsnook.xcodeproj -scheme Opsnook-AppStore -configuration Debug-AppStore -derivedDataPath /tmp/OpsnookBuild build

触及 UI 或系统集成时，自动化测试不足以覆盖，还需真机运行，并在 PR 说明中记录验证方式与结果。

FilesExpand file tree

PROJECT_FILE_GUIDE.md

Latest commit

History