ZackEyes: Instructions file for Claude Code

CLAUDE.md

上下文分层

引用指令:

• 修改代码前必读 ARCHITECTURE.md — 组件边界、数据流、安全模型
• 开始任务前必读 AGENTS.md — 开发流程、反馈循环、变更检查清单

Build & Dev Commands

# 编译
swift build                  # Debug build (两个 target: ZackEyes + bridge)
make app                     # Build + 组装 .app bundle

# 运行
make run                     # Build + open .build/ZackEyes.app

# 测试
swift test                   # 全量测试 (SharedTests + BridgeLibTests + AppLibTests)
swift test --filter SharedTests      # 仅 Shared 模块
swift test --filter BridgeLibTests   # 仅 Bridge 模块
swift test --filter AppLibTests      # 仅 App 模块

# Bridge 手动测试 (模拟 Claude Code hook 调用)
echo '{"hook_event_name":"SessionStart","session_id":"test","cwd":"/tmp"}' | \
  $(swift build --show-bin-path)/bridge --event SessionStart --agent claude

# 模拟 Codex hook 调用
echo '{"hook_event_name":"Stop","session_id":"test","cwd":"/tmp","last_assistant_message":"done"}' | \
  $(swift build --show-bin-path)/bridge --event Stop --agent codex

# 清理
make clean

Mandatory Invariants

任何代码变更 MUST 遵守以下所有约束：

1. 用户配置零损坏 — Hook installer 操作用户配置文件时（~/.claude/settings.json for HookInstaller，~/.codex/hooks.json for CodexHookInstaller）：必须先备份（{file}.backup.{timestamp}）、只追加 hooks key 不动其他字段（Claude: permissions、enabledPlugins、defaultMode...；Codex: 用户已有的 hook 条目）、JSON 解析失败时不修改原文件。永远不读不写 ~/.codex/config.toml（codex [features].hooks 默认 true，碰它会引入 TOML 解析依赖 + 用户配置损坏风险）。
2. Bridge 永不污染 agent 终端 — Bridge 进程的任何受控失败路径必须以 exit(0) 退出且不写 stdout/stderr。Claude Code 新版把任何非 0 exit 显示成 hook error；Codex 同样宽容地处理 exit 0。Socket 连不上、超时、stdin 异常、未知 --agent 值 → 静默 exit(0)。永远不使用 exit(2)（阻塞错误）。PermissionRequest 失败时 exit 0 无 stdout → agent 回退到原生终端授权，行为正确。
3. NotchPanel 不抢焦点 — NSPanel 必须是 nonactivatingPanel。canBecomeMain 返回 false。Collapsed/Compact 状态下 ignoresMouseEvents = true，只有 Expanded 状态才接收交互。
4. Socket 连接不复用 — 每次 hook 调用创建新连接，用完即关。防止连接泄漏和状态混淆。
5. Hook 配置可识别 — 注入到 settings.json / hooks.json 的 hook entries，command 路径必须包含 zackeyes 字符串 + 显式 --agent claude|codex flag，用于安全移除时精确匹配。Bridge 缺 --agent 时默认 claude，保证老 hook entry 升级时不掉链。
6. 零第三方依赖 — MVP 阶段只使用 Foundation + AppKit + SwiftUI。不引入 Sentry、Sparkle、CocoaPods、SPM 外部包。
7. 存活判定必须按 agent 取各自的信号 — runLivenessSweep 和 LivenessFilter.filterLiveDetected 对两个 agent 分别取快照（runningClaudeCwds / runningClaudePidSet ↔ runningCodexCwds / runningCodexPidSet）。把一个 agent 的 session 喂进另一个 agent 的 map/PID set 会全部判死。另有三条不能破：
   • codex cwd == nil 的 session 保留 15 min idle 兜底剪枝 —— 它进不了 ps 路径，删掉这条兜底，codex TUI 退出后卡片永不消失。
   • 只有来自 hook _bridge_ppid 的 PID 有判活权（claudePidFromHook）。activateDetectedSessions 会按 cwd 猜一个同目录的 agent 进程填进 claudePid，那个猜测值只能用于终端跳转；拿它判活会让「猜错的兄弟进程退出」剪掉活会话（#217）。
   • 任一快照返回 nil（ps/lsof 失败）时一律保守留人 —— 尤其不能把有 PID 的 session 改判到 cwd 启发式上，那等于把 #217 放回来。下一个 tick 重试即可。