CodeIsland - 完整学习教程

教程级别： 从零到一 预计学习时间： 2-3 小时（基础使用 30 分钟 + 进阶配置 1 小时 + 高级集成 1-1.5 小时） 前置知识： 基本的 macOS 操作能力；进阶部分需要了解终端使用（如 cmux、iTerm2）；高级部分需要了解 Claude Code Hook 机制和 Swift 基础 基于版本： v1.0.17（2026-04-09 发布）

环境搭建指南

系统要求

• 操作系统： macOS 14.0+（Sonoma）或更高版本
• 硬件： 带有 Notch 的 MacBook Pro 或 MacBook Air（无 Notch 机型功能受限）
• AI 编程工具： 至少安装以下一种：Claude Code、Codex、Gemini CLI、Cursor、GitHub Copilot CLI 等
• 终端： cmux、iTerm2、Ghostty 或 Terminal.app（推荐 cmux 以获得最佳体验）

安装步骤

方式一：通过 Homebrew 安装（推荐）

# 使用 Homebrew Cask 一键安装
brew install --cask codeisland

方式二：通过 DMG 安装

# 1. 从 GitHub Releases 下载最新 DMG
# 访问 https://github.com/wxtsky/CodeIsland/releases
# 下载 CodeIsland.dmg

# 2. 打开 DMG，将 CodeIsland 拖入 Applications 文件夹

# 3. 移除隔离标记（首次安装需要）
sudo xattr -rd com.apple.quarantine /Applications/CodeIsland.app

方式三：从源码构建（适合开发者）

# 1. 克隆仓库
git clone https://github.com/wxtsky/CodeIsland.git
cd CodeIsland

# 2. 使用 Xcode 打开项目
open CodeIsland.xcodeproj

# 3. 在 Xcode 中构建并运行（Cmd+R）

验证安装

# 启动 CodeIsland 应用
open /Applications/CodeIsland.app

# 验证应用正在运行
pgrep -x CodeIsland && echo "CodeIsland 正在运行" || echo "CodeIsland 未运行"

# 验证 Unix Domain Socket 已创建
uid=$(id -u)
ls -la /tmp/codeisland-${uid}.sock 2>/dev/null && echo "Socket 已创建" || echo "Socket 未找到"

预期结果：
- CodeIsland 正在运行
- Socket 已创建（显示 /tmp/codeisland-<uid>.sock 文件信息）
- MacBook Notch 区域出现微小状态指示器

练习题： 1. 使用 Homebrew 安装 CodeIsland，确认应用成功启动 2. 检查 Unix Domain Socket 文件是否存在，记录 socket 路径

第一部分：入门篇

1.1 Notch 面板基本交互

概念讲解：

CodeIsland 的 UI 完全嵌入 MacBook 的刘海（Notch）区域。这是你与 CodeIsland 交互的主要界面。理解 Notch 面板的行为模式是使用 CodeIsland 的基础。

Notch 面板有两种状态：

1. 收起状态 — 显示微小的状态指示器（小圆点或小图标），几乎不可见，不影响正常工作。状态点颜色表示不同状态：
2. Cyan（青色）：工作中（Working）
3. Amber（琥珀色）：需要审批（Needs Approval）
4. Green（绿色）：完成 / 等待输入（Done / Waiting）
5. Purple（紫色）：思考中（Thinking）
6. Red（红色）：错误或超过 60 秒未响应

7. Orange（橙色）：超过 30 秒未响应

8. 展开状态 — 点击或悬停 Notch 区域时，面板展开显示完整控制面板。包含：

9. 活跃会话列表（每个会话一张卡片）
10. 每张卡片显示：AI 工具图标、会话名称/路径、当前状态、运行时长
11. 子代理任务列表（如果有）
12. 使用量百分比（Claude 专用）
13. Buddy 信息

操作示例：

1. 启动 CodeIsland（如果未运行）
2. 在任意终端中启动一个 Claude Code 会话：claude
3. 观察 Notch 区域——应该出现一个绿色状态指示器
4. 将鼠标移动到 Notch 区域——面板展开
5. 观察会话卡片，确认显示正确
6. 将鼠标移开 Notch 区域——面板自动收起

预期结果：
- Claude Code 启动后，Notch 区域出现绿色小圆点
- 悬停展开后，显示一个会话卡片，包含 Claude Code 图标和当前状态
- 移开鼠标后，面板平滑收起

注意事项： - 如果 Notch 区域没有出现状态指示器，可能是 Hook 未正确安装。检查下方的 Hook 配置章节。 - 某些全屏应用可能遮挡 Notch 区域。CodeIsland 的 Notch 面板在全屏模式下也应该可见。

练习题： 1. 启动 CodeIsland，确认 Notch 区域出现状态指示器 2. 启动一个 Claude Code 会话，观察 Notch 面板的变化 3. 悬停展开面板，确认会话信息正确显示

1.2 Hook 自动安装机制

概念讲解：

CodeIsland 通过 Hook 机制与 AI 编程工具通信。Hook 是一种事件回调——当 AI 工具执行关键操作时，自动调用 CodeIsland 的 bridge 二进制，将事件信息传递给主应用。

关键概念： codeisland-bridge 是一个约 86KB 的轻量级命令行工具，作为 hook 命令被 AI 工具调用。它的唯一职责是将事件数据通过 Unix Domain Socket 转发给 CodeIsland 主应用。

CodeIsland 在首次启动时自动检测已安装的 AI 工具，并在对应的 hook 配置中注册 bridge。支持的 AI 工具及其 hook 配置位置：

操作示例：

# 1. 查看 Claude Code 的 hook 配置
cat ~/.claude/hooks/*.json

# 2. 确认 CodeIsland bridge 已注册
# 配置中应包含 codeisland-bridge 命令调用
grep -r "codeisland-bridge" ~/.claude/hooks/ && echo "Hook 已安装" || echo "Hook 未安装"

# 3. 手动验证 bridge 二进制
which codeisland-bridge 2>/dev/null && echo "bridge 已安装" || echo "bridge 未找到"
ls -la /Applications/CodeIsland.app/Contents/MacOS/codeisland-bridge

预期结果：
- hook 配置文件中包含 codeisland-bridge 命令调用
- bridge 二进制位于 /Applications/CodeIsland.app/Contents/MacOS/ 目录下
- bridge 文件大小约 86KB

注意事项： - 如果你在安装 CodeIsland 之前已经安装了 Claude Code，CodeIsland 会自动检测并安装 hook。如果 CodeIsland 在 Claude Code 之后安装，hook 也会自动配置。 - 如果 hook 配置文件中有其他自定义 hook，CodeIsland 不会覆盖它们，而是追加自己的 hook 条目。 - 如果升级 CodeIsland 后 hook 似乎不工作，尝试重启 CodeIsland 应用，它会重新检查和安装 hook。

练习题： 1. 查看 Claude Code 的 hook 配置，确认 CodeIsland bridge 已注册 2. 手动运行 bridge 二进制测试 socket 连接（不会影响正在运行的会话） 3. 如果同时安装了 Codex，检查 Codex 的 hook 配置是否也已注册

1.3 会话状态监控

概念讲解：

在 1.1 节中我们学习了 Notch 面板的基本交互。本节深入理解会话状态监控——CodeIsland 最核心的功能。

每个 AI 编程会话在 CodeIsland 中对应一张会话卡片。卡片上的信息来自 hook 捕获的事件，通过 bridge → Unix Socket → 主应用的链路实时更新。

会话状态类型：

操作示例：

1. 启动两个 Claude Code 会话（在两个不同的终端标签页中）
2. 在会话 1 中让 Claude Code 执行一个需要 Bash 权限的任务
3. 在会话 2 中让 Claude Code 执行一个简单的代码搜索
4. 展开 Notch 面板，观察两张会话卡片
5. 注意每张卡片上的状态差异

预期结果：
- Notch 面板显示两张会话卡片
- 会话 1 卡片显示"等待权限"状态（黄色指示器）
- 会话 2 卡片显示"运行中"状态（绿色指示器）
- 卡片上显示会话的工作目录或任务描述

练习题： 1. 启动两个 Claude Code 会话，分别执行不同任务，观察 Notch 面板中的状态变化 2. 在某个会话中触发权限请求，观察指示器颜色是否变为黄色

第二部分：进阶篇

2.1 权限审批与问题回答

概念讲解：

在入门篇中我们了解了会话状态监控。本节学习 CodeIsland 的核心交互功能——在 Notch 面板中直接审批权限和回答问题。

权限审批（Permission Approval）： 当 Claude Code 等工具请求执行需要用户确认的操作（如运行 Bash 命令、写入文件）时，CodeIsland 在 Notch 面板中弹出审批通知。用户可以点击"允许"或"拒绝"按钮，无需切换到对应终端。

问题回答（AskUserQuestion）： 当 Claude Code 通过 AskUserQuestion 机制提出多选问题时，选项直接以按钮形式显示在 Notch 面板中。点击按钮后，CodeIsland 通过 cmux send（或 AppleScript）将答案发送到对应终端。

操作示例：

1. 在终端标签页 A 中启动 Claude Code
2. 让 Claude Code 执行一个需要 Bash 权限的命令，例如： 请运行 ls -la /tmp 命令
3. 切换到终端标签页 B（确保标签页 A 不在焦点）
4. 观察 Notch 面板——应该弹出权限请求通知
5. 点击"允许"按钮
6. 切换回终端标签页 A，确认命令已执行

预期结果：
- Claude Code 请求权限后，Notch 面板弹出通知
- 通知中显示请求的操作类型（如 "Bash: ls -la /tmp"）
- 点击"允许"后，通知消失，对应终端自动执行命令

注意事项： - 权限审批和问题回答仅在会话不在当前焦点时弹出通知（智能弹窗抑制）。如果会话就在当前终端标签页中，CodeIsland 不会弹出通知，因为用户可以直接在终端中操作。 - 对于 cmux 用户，弹窗抑制精确到工作区级别。对于 iTerm2 用户，精确到会话级别。 - 某些权限类型可能有安全风险（如删除文件的 Bash 命令），建议在点击"允许"前仔细阅读通知中的操作描述。

练习题： 1. 在后台 Claude Code 会话中触发一个权限请求，使用 Notch 面板审批 2. 让 Claude Code 提出一个多选问题（AskUserQuestion），使用 Notch 面板回答

2.2 智能弹窗抑制

概念讲解：

智能弹窗抑制（Smart Popup Suppression）是 CodeIsland 最重要的 UX 特性之一。在 2.1 节中我们体验到"只在后台会话时弹出通知"的行为——这就是智能弹窗抑制在工作。

核心逻辑： CodeIsland 检测用户当前正在查看的终端标签页。当事件到达时： - 如果事件来自当前焦点的终端标签页 → 静默更新状态，不弹出通知 - 如果事件来自非焦点的终端标签页 → 弹出通知

终端检测粒度：

操作示例：

1. 使用 cmux 创建两个工作区：workspace-A 和 workspace-B
2. 在 workspace-A 中启动 Claude Code 会话 1
3. 在 workspace-B 中启动 Claude Code 会话 2
4. 确保当前焦点在 workspace-A
5. 在会话 2 中触发一个权限请求（可以让另一个会话请求）
6. 观察 Notch 面板——因为 workspace-B 不在焦点，应该弹出通知
7. 切换到 workspace-B，再让会话 1 产生一个事件
8. 观察 Notch 面板——因为 workspace-A 不在焦点，应该弹出会话 1 的通知

预期结果：
- 焦点在 workspace-A 时，workspace-B 的事件弹出通知
- 焦点在 workspace-B 时，workspace-A 的事件弹出通知
- 当前焦点工作区的事件仅静默更新状态

注意事项： - 智能弹窗抑制依赖终端的 AppleScript 接口或内部状态。如果终端不支持 AppleScript（或 AppleScript 权限未授予），CodeIsland 可能无法检测焦点状态，此时可能对所有事件弹出通知。 - Warp 和 VS Code 集成终端的检测粒度可能不如 cmux 和 iTerm2 精确。 - 如果弹窗抑制不工作，检查"系统设置 → 隐私与安全性 → 自动化"中 CodeIsland 是否被授予了控制终端应用的权限。

练习题： 1. 使用 cmux 创建两个工作区，分别在两个工作区中启动 Claude Code，测试弹窗抑制是否按预期工作 2. 测试 iTerm2 中的弹窗抑制（如果使用 iTerm2）

2.3 一键终端跳转

概念讲解：

一键终端跳转是与会话监控配套的重要功能。当 Notch 面板显示多个会话时，你可能需要快速跳转到某个特定会话的终端标签页。

每个会话卡片旁有一个绿色终端按钮。点击后，CodeIsland 自动定位到对应的终端标签页并前置显示——无需手动搜索和切换。

操作示例：

1. 启动 3 个 Claude Code 会话，分别在 3 个不同的终端标签页中
2. 展开 Notch 面板，确认显示 3 张会话卡片
3. 当前焦点在标签页 1，点击标签页 3 会话卡片上的绿色终端按钮
4. 观察终端自动切换到标签页 3

预期结果：
- 点击绿色终端按钮后，终端自动切换到对应标签页
- 目标标签页获得焦点，窗口前置显示
- Notch 面板保持展开状态，方便继续操作

注意事项： - 终端跳转使用 AppleScript 控制终端应用。确保 CodeIsland 被授予了自动化权限。 - 对于 cmux，跳转使用 cmux switch 命令。对于 iTerm2，使用 AppleScript 选择对应标签页。 - 如果跳转不工作，检查系统设置中的自动化权限。

练习题： 1. 在 3 个标签页中各启动一个 Claude Code 会话，使用 Notch 面板的终端按钮在它们之间快速跳转 2. 测试跳转后 Notch 面板的状态更新是否及时

2.4 Claude 使用量监控

概念讲解：

CodeIsland 通过 Anthropic OAuth API 直接读取 Claude 的使用量数据。这是唯一涉及外部网络请求的功能。

工作原理： 1. CodeIsland 从 macOS Keychain 读取 Claude 的 OAuth 令牌（不经过 CodeIsland 处理） 2. 使用该令牌调用 Anthropic API 查询使用量 3. 显示 5 小时和 7 天的使用百分比

操作示例：

1. 确保已通过 claude login 登录 Claude
2. 展开 Notch 面板
3. 查看会话卡片上的使用量百分比显示
4. 或查看 Notch 面板中的使用量汇总区域

预期结果：
- 会话卡片上显示类似 "5h: 45% | 7d: 12%" 的使用量数据
- 数据实时更新（每次查询 Anthropic API 后刷新）

注意事项： - 使用量监控需要已登录 Claude（OAuth 令牌存在于 macOS Keychain 中）。如果未登录，使用量数据将不显示。 - API 调用频率有限制，CodeIsland 不会每次展开面板时都查询 API。 - 认证令牌仅用于 API 调用，CodeIsland 不会存储或转发令牌。

练习题： 1. 登录 Claude Code（claude login），确认 Notch 面板显示使用量数据 2. 记录当前 5 小时和 7 天使用百分比

第三部分：高级篇

3.1 Hook 配置深度定制

概念讲解：

在 1.2 节中我们了解了 Hook 的自动安装。本节深入理解 Hook 的配置结构和定制选项。

Claude Code 的 Hook 配置使用 JSON 格式，支持多种事件类型：

Hook 配置结构：

以下为 Claude Code hook 配置的概念性示例（基于 Claude Code hook 机制的通用格式，非 CodeIsland 实际安装的精确配置）：

// Claude Code hooks 配置详解
// 来源：基于 GitHub README 和 dev.to 文章
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",           // 匹配特定工具名，空字符串匹配所有
        "hooks": [
          {
            "type": "command",
            "command": "codeisland-bridge --event pre-tool-use --tool Bash --session $CLAUDE_SESSION_ID"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "codeisland-bridge --event post-tool-use --session $CLAUDE_SESSION_ID"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "codeisland-bridge --event stop --session $CLAUDE_SESSION_ID"
          }
        ]
      }
    ]
  }
}

注意事项： - matcher 字段控制 hook 的触发范围。空字符串 "" 匹配所有工具。指定工具名（如 "Bash"、"Read"）仅匹配该工具。 - 如果你有其他自定义 hook，CodeIsland 的 hook 不会覆盖它们。但建议定期检查 hook 配置，确保多个 hook 之间没有冲突。 - 环境变量 $CLAUDE_SESSION_ID 由 Claude Code 自动设置，用于标识当前会话。

练习题： 1. 查看 Claude Code 的完整 hook 配置，理解每个事件类型的用途 2. 尝试为特定工具（如 Bash）添加自定义 hook，观察触发行为

3.2 多工具并发管理

概念讲解：

CodeIsland 最大的优势是同时监控多种不同的 AI 编程工具。本节学习如何高效管理多工具并发。

支持的 9 种 AI 工具：

1. Claude Code（Anthropic）
2. Codex（OpenAI）
3. Gemini CLI（Google）
4. Cursor
5. Qoder
6. Factory
7. CodeBuddy
8. OpenCode
9. GitHub Copilot CLI

每种工具在 Notch 面板中以不同的图标区分。根据 Notch 面板截图观察到的工具图标颜色： - Claude Code → 橙色 - Codex → 浅蓝色 - Gemini CLI → 紫色 - 其他工具各有图标区分

此外，会话状态通过状态点颜色标识（与会话状态相关，而非工具类型）： - Cyan（青色）= 工作中 - Amber（琥珀色）= 需要审批 - Green（绿色）= 完成 / 等待输入 - Purple（紫色）= 思考中 - Red（红色）= 错误或超过 60 秒未响应 - Orange（橙色）= 超过 30 秒未响应

操作示例：

1. 在终端标签页 1 中启动 Claude Code：claude
2. 在终端标签页 2 中启动 Codex：codex
3. 展开 Notch 面板，确认显示两张不同颜色的会话卡片
4. 让两个工具分别执行任务
5. 观察 Notch 面板中两个会话的状态独立更新

预期结果：
- 两张会话卡片显示不同颜色标识
- 每个会话的状态独立更新
- 权限请求和问题分别显示在各自的卡片中

注意事项： - 不同 AI 工具的 Hook 机制可能不同。CodeIsland 为每种工具适配了不同的 hook 安装逻辑。 - 某些工具可能不支持所有事件类型。例如，某些工具可能只支持状态更新，不支持权限审批。

练习题： 1. 同时启动 Claude Code 和另一个 AI 编程工具（如 Codex 或 Gemini CLI），观察多工具监控效果 2. 测试两个工具同时请求权限时 Notch 面板的行为

3.3 最佳实践

1. 使用 cmux 获得最佳体验。 cmux 是目前与 CodeIsland 集成最紧密的终端工具。工作区级别的弹窗抑制和终端跳转在 cmux 中最为精确。如果你日常使用多个 AI 编程会话，强烈建议切换到 cmux。

2. 合理管理并发会话数量。 建议同时运行的 AI 编程会话不超过 5-7 个。虽然 CodeIsland 可以监控更多会话，但过多的并发会话会降低 Notch 面板的可读性，且频繁的权限审批可能导致注意力分散。

3. 定期检查使用量。 利用 CodeIsland 的使用量监控功能，养成在启动新会话前查看使用百分比的习惯。避免在 5 小时窗口即将用尽时启动长时间运行的任务。

4. 保持 CodeIsland 更新。 项目迭代迅速，新版本经常添加对新 AI 工具的支持和 Bug 修复。建议定期运行 brew upgrade --cask codeisland 更新。

5. 遇到问题先检查 Hook 配置。 如果某个 AI 工具的状态不显示在 Notch 面板中，首先检查该工具的 hook 配置是否包含 codeisland-bridge。其次检查 bridge 二进制是否存在且可执行。

第四部分：实战项目

项目需求

项目名称： AI 编程助手多会话管理工作流

需求描述： 配置一个完整的多 AI 编程助手并发工作环境，使用 cmux + CodeIsland 管理 3 个并发的 Claude Code 会话，分别处理不同类型的编程任务。

综合运用知识点： - Notch 面板基本交互（1.1 节） - Hook 自动安装机制（1.2 节） - 权限审批与问题回答（2.1 节） - 智能弹窗抑制（2.2 节） - 一键终端跳转（2.3 节）

项目设计

环境配置：
cmux 工作区布局：
├── workspace-frontend  → Claude Code 会话 1（前端 Bug 修复）
├── workspace-backend   → Claude Code 会话 2（后端 API 开发）
└── workspace-tests     → Claude Code 会话 3（测试编写）

CodeIsland 配置：
├── Hook 自动安装（3 个 Claude Code 会话）
├── 智能弹窗抑制（cmux 工作区级别）
└── 使用量监控（5 小时 / 7 天）

完整实现步骤

# ===== 步骤 1：安装和配置 =====

# 1.1 确保 CodeIsland 已安装并运行
brew install --cask codeisland
open /Applications/CodeIsland.app

# 1.2 验证 Hook 已自动安装
grep -r "codeisland-bridge" ~/.claude/hooks/ && echo "Hook 已安装" || echo "Hook 未安装"

# 1.3 确保 Claude Code 已登录（使用量监控需要）
claude login

# ===== 步骤 2：配置 cmux 工作区 =====

# 2.1 创建 3 个 cmux 工作区
# cmux 的具体配置取决于你的 cmux 版本和偏好
# 以下为概念性命令
cmux new-session -s frontend -n "Frontend Bug Fix"
cmux new-session -s backend -n "Backend API"
cmux new-session -s tests -n "Test Suite"

# ===== 步骤 3：在各个工作区中启动 Claude Code =====

# 3.1 在 frontend 工作区中启动 Claude Code（处理前端任务）
cmux send -t frontend 'claude' Enter

# 3.2 在 backend 工作区中启动 Claude Code（处理后端任务）
cmux send -t backend 'claude' Enter

# 3.3 在 tests 工作区中启动 Claude Code（处理测试任务）
cmux send -t tests 'claude' Enter

# ===== 步骤 4：验证 CodeIsland 监控 =====

# 4.1 展开 Notch 面板，确认显示 3 张会话卡片
# 预期：3 张绿色状态的 Claude Code 会话卡片

# 4.2 切换到 frontend 工作区
cmux switch -t frontend

# 4.3 在 backend 工作区中触发一个需要权限的操作
# 在另一个终端窗口中手动触发，或等待 Claude Code 自然请求
cmux send -t backend '请运行 echo "test command"' Enter

# 4.4 观察 Notch 面板
# 预期：因为当前焦点在 frontend，backend 的权限请求应弹出通知

# ===== 步骤 5：使用 Notch 面板审批权限 =====

# 5.1 点击 Notch 面板中 backend 会话的"允许"按钮
# 预期：权限被自动发送到 backend 工作区

# 5.2 使用一键跳转切换到 backend 确认操作已完成
# 点击 Notch 面板中 backend 卡片的绿色终端按钮
# 预期：自动切换到 backend 工作区

# ===== 步骤 6：监控使用量 =====

# 6.1 查看 Notch 面板中的使用量百分比
# 预期：显示类似 "5h: 35% | 7d: 8%" 的数据

# 6.2 根据使用量决定是否启动更多会话

代码解析

1. Hook 自动安装（1.2 节知识点）：步骤 1.2 验证了 CodeIsland 在首次启动时自动在 Claude Code 的 hook 配置中注册了 bridge。这是后续所有监控功能的基础。

2. Notch 面板基本交互（1.1 节知识点）：步骤 4.1 验证了 Notch 面板正确显示 3 个会话卡片，每个卡片包含状态指示器和会话信息。

3. 智能弹窗抑制（2.2 节知识点）：步骤 4.3-4.4 利用了 cmux 的工作区级别弹窗抑制。因为当前焦点在 frontend 工作区，backend 工作区的事件触发了通知弹出。

4. 权限审批（2.1 节知识点）：步骤 5.1 演示了在 Notch 面板中直接审批权限，CodeIsland 通过 cmux send 将审批结果发送到对应工作区。

5. 一键终端跳转（2.3 节知识点）：步骤 5.2 使用 Notch 面板的绿色终端按钮实现快速跳转，无需手动搜索工作区。

扩展挑战

1. 添加 Codex 会话：在环境中添加第 4 个 cmux 工作区，运行 OpenAI Codex。验证 CodeIsland 能同时监控 Claude Code 和 Codex，且颜色编码正确区分。

2. 自定义 Hook 通知：修改 Claude Code 的 hook 配置，添加一个自定义 hook 在每次 AI 使用 Write 工具时发送桌面通知（使用 osascript -e 'display notification ...'）。

3. 使用量预算管理：编写一个 shell 脚本，定期读取 CodeIsland 的使用量显示（或通过 Anthropic API 直接查询），当使用量超过 80% 时发送桌面警告通知。

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

1. 检查 Unix Domain Socket 状态。 CodeIsland 的所有 IPC 都通过 Unix Socket 进行。如果状态更新异常，首先检查 socket 文件是否存在：

```bash # 检查 socket 文件 uid=$(id -u) ls -la /tmp/codeisland-${uid}.sock

# 测试 socket 是否可连接 nc -U /tmp/codeisland-${uid}.sock <<< "test" 2>&1 | head -1 ```

如果 socket 文件不存在，说明 CodeIsland 主应用未运行或未成功创建 socket。尝试重启应用。

1. 检查 Hook 配置内容。 如果某个 AI 工具的状态不显示，检查该工具的 hook 配置是否正确包含 codeisland-bridge：

```bash # 检查 Claude Code hooks cat ~/.claude/hooks/*.json | python3 -m json.tool

# 手动测试 bridge（不会影响正在运行的会话） /Applications/CodeIsland.app/Contents/MacOS/codeisland-bridge --event test --session test-id 2>&1 ```

1. 检查系统日志。 CodeIsland 的错误信息可能记录在 macOS 系统日志中：

```bash # 查看 CodeIsland 相关的系统日志 log show --predicate 'process == "CodeIsland"' --last 5m --style compact

# 查看 bridge 相关的系统日志 log show --predicate 'process == "codeisland-bridge"' --last 5m --style compact ```

第六部分：学习路线推荐

官方文档推荐阅读顺序

推荐进阶资源

1. Claude Code Hook 文档 — 理解 Claude Code 的 Hook 机制是深度定制 CodeIsland 的基础。了解 Hook 的事件类型、匹配器和命令格式，可以帮助你创建自定义的工作流集成。

2. macOS 原生开发（Swift/SwiftUI） — 如果你想参与 CodeIsland 的源码贡献或开发类似工具，推荐学习 Swift/SwiftUI 和 macOS 原生应用开发。重点关注：Notch/Dynamic Island API、Unix Domain Socket、AppleScript 自动化、macOS Keychain 访问。

3. Unix Domain Socket 编程 — CodeIsland 的 IPC 机制基于 Unix Domain Socket。深入学习 Socket 编程有助于理解 CodeIsland 的架构设计，也可以开发与 CodeIsland 兼容的工具。推荐阅读 BSD Socket 编程教程。

术语对照表

教程信息来源： - 基于 CodeIsland v1.0.17（2026-04-09 发版） - GitHub README - dev.to — I Turned My MacBook's Notch Into a Control Center for AI Coding Agents - dev.to — My Claude Code Buddy Moved Into My MacBook's Notch - GitHub Releases - 信息获取日期：2026-04-10