庆祝 · Celebrate

为 Codex、Claude Code 和 OpenCode 打造的原生 macOS 全屏彩带特效插件

轻巧、优雅的会话完成仪式感 —— 基于客户端生命周期Hook事件，0 Token 消耗，0 模型调用，纯本地流畅绽放。

celebrate-github.mp4

📖 简介

庆祝 · Celebrate 是一个专为 Codex、Claude Code 和 OpenCode 打造的 macOS 原生彩带插件。

与常见的“AI 技能/Prompt 插件”不同，本项目集成客户端原生生命周期 Hook（Lifecycle Command Hooks）机制：

• ⚡️ 0 Token 消耗：纯事件生命周期信号驱动，绝不向大模型注入任何提示词或会话上下文。
• 🚫 0 模型调用：由 Codex、Claude Code 在主 Agent 停止回答（Stop）时直接调用本地脚本触发，无需等待模型推理。
• 🔒 无外部网络请求：庆祝逻辑纯本地运行，OpenCode 仅通过 Harness API 查询本机会话元数据，不读取会话正文，不向外发送任何网络数据。

每当主 Agent 触发 Stop，屏幕将自动绽放约 5 秒绚丽的多屏物理彩带粒子动画，为你每一次灵感落地送上轻量而愉悦的仪式感。

Tip

设计理念：关注节奏，而非评判

我们希望为你每一次与 AI 的协作交付，提供自然、及时的落幕反馈。

• 纯粹感知：关注 AI 回合生命周期的自然结束（Stop），不审查或揣测回答语义，不消耗 Token 判断任务“成功或失败”。
• 克制不扰：你手动中断或提前打断时保持静默；若多 Agent 协作继续推进，则在最终停笔时为你绽放。
• 无感陪伴：不抢焦点、穿透点击、0 推理等待，像一次轻快的击掌，让工作流充满呼吸感。

---

✨ 核心特性

• ⚡️ 纯 Hook 驱动 · 0 Token 消耗
  • 利用各 Harness 提供的生命周期机制（Stop Command Hook / session.idle），直接捕获事件信号。
  • 不占 Token、不加提示词、不调用 LLM，绝不给模型交互带来任何额外计费或延迟。
• 🎉 原生极致体验
  • 基于 AppKit 构建的多屏独立透明浮层。
  • 不抢占窗口焦点（Non-activating）、鼠标完全穿透（Click-through），绝不干扰你的敲键与阅读。
• 🎊 物理粒子动效
  • 解析式运动方程，脱离屏幕刷新率限制，粒子飞行平滑自然。
  • 每块屏幕多点位随机发射（顶部倾泻、两侧喷射），辅以随机扩散角与旋转自旋。
  • 精选五色清爽马卡龙色板（紫、粉、青绿、黄、浅蓝紫）。
  • 彩带绽放时同步播放宣传片同款短促音效，每次触发仅播放一次，多屏不叠加；音量跟随系统设置。
• 🛡️ 隐私至上与防打扰
  • 绝不窥探隐私：不读取任何会话文本、上下文或历史记录文件。
  • 精准触发规则：仅响应主 Agent 回合结束事件，自动忽略用户打断及子 Agent 内部事件，保持节奏干净利落。
  • 无障碍关怀：严格遵循 macOS 系统「减少动态效果」(Reduce Motion) 设置，开启时静默休眠。

---

🖥️ 环境要求

• 操作系统：macOS 14 (Sonoma) 或更高版本（需在图形桌面会话中运行）。
• 开发工具：Xcode Command Line Tools（包含 swiftc、xcrun），仅安装或更新编译时需要。
• 支持的 Agent Harness：支持插件/Hook 机制的 Codex、Claude Code 或 OpenCode。

---

🚀 安装指南

插件核心采用 Swift 编写，首次安装前需在本地编译原生 Helper。请选择你正在使用的 Agent Harness：

Codex 安装

1. 本地构建与添加插件

git clone https://github.com/ningzimu/codex-celebrate.git
cd codex-celebrate

# 编译原生 Helper 应用
bash plugins/codex-celebrate/scripts/build.sh

# 添加本地 Marketplace 并安装插件
codex plugin marketplace add .
codex plugin add codex-celebrate@codex-celebrate

提示：上述命令仅在当前客户端中注册本仓库为本地源，不会影响全局配置。你也可以在执行 marketplace add 后，进入 Codex 的 /plugins 界面搜索 “庆祝 · Celebrate” 手动点击安装。

2. 授权 Hook 生效

Important

Codex 默认不会自动执行未受信任的本地脚本 Hook，需手动授权一次（以下两种方法任选其一即可）：

方法一：从插件详情页授权

1. 在 Codex 左侧边栏点击 「插件」。
2. 搜索并进入 「庆祝 · Celebrate」 详情页。
3. 在 「钩子」 区域点击 「检查」 审阅 Stop Hook，确认无误后点击 「全部信任」。

方法二：从设置页授权

1. 打开 Codex 设置 ➔ 左侧 「编码」 ➔ 「钩子」。
2. 在 「来自插件」 中找到 「庆祝 · Celebrate」（未授权时显示「2 项待审核」）。
3. 点击进入详情完成信任授权即可。

完成授权后，发送一条消息等待回答结束，即可体验彩带效果（若未生效可尝试重启 Codex）。

3. 管理与维护

• 查看状态：codex plugin list --marketplace codex-celebrate

• 拉取更新：

  git pull
  bash plugins/codex-celebrate/scripts/build.sh
  codex plugin add codex-celebrate@codex-celebrate

  (注：若更新涉及启动命令变更，需在 Codex 中重新确认一次 Hook 信任)

• 卸载插件：codex plugin remove codex-celebrate@codex-celebrate

---

Claude Code 安装

在仓库根目录下执行编译与本地安装：

bash plugins/codex-celebrate/scripts/build.sh
claude plugin marketplace add .
claude plugin install codex-celebrate@codex-celebrate

重启 Claude Code，即可在会话结束时自动触发（可在会话中输入 /hooks 检查已加载的 Stop Hook）。Claude Code 与 Codex 共享同一套原生核心与音效资源。

开发者调试：可运行 claude plugin validate . 与 claude plugin validate ./plugins/codex-celebrate 验证清单格式。

---

OpenCode 安装

OpenCode 通过 JavaScript 插件入口桥接原生 Swift 动效核心。在仓库根目录下运行：

bash plugins/codex-celebrate/scripts/build.sh
bash plugins/codex-celebrate/scripts/install-opencode.sh

运行机制与说明：

• 重启 OpenCode 即刻生效。脚本会将插件注册至 ~/.config/opencode/plugins/codex-celebrate.js，并将原生二进制同步至对应目录，不侵入修改全局 opencode.json，安装后移动源码目录亦不影响运行。
• 基于 OpenCode 官方插件规范：监听 session.idle 并结合 message.updated 的最终状态，智能过滤用户主动中断、报错、工具调用及压缩摘要，且自动忽略子会话。
• 零第三方 npm 依赖，开箱即用。

单元测试（需 Node.js 环境）：

node --test plugins/codex-celebrate/Tests/OpenCodeTests.mjs

卸载方式：删除 ~/.config/opencode/plugins/codex-celebrate.js 和对应 celebrate/ 资源目录并重启 OpenCode 即可。

🕹️ 本地快速预览

无需等待 Agent 回答完成，即可在终端直接预览完整的物理彩带与音效：

bash plugins/codex-celebrate/scripts/build.sh
bash plugins/codex-celebrate/scripts/preview.sh

• 编译产物：构建后将在 plugins/codex-celebrate/bin/ 下生成原生应用 SessionConfetti.app 与轻量触发器 celebrate-trigger。构建脚本会自动适配当前 Mac 架构并完成本地签名。
• 工具链要求：编译需系统具备 Command Line Tools。若终端未配置编译环境，可先运行 xcode-select --install 完成安装。日常使用时仅运行编译好的二进制，极速响应且无额外开销。

---

🧪 自动化测试

构建后运行 Swift 测试，验证各端一致的触发逻辑和异常容错：

bash plugins/codex-celebrate/scripts/build.sh
bash plugins/codex-celebrate/scripts/test.sh

测试覆盖各端 Stop 输入、忽略中断与子 Agent、失败重试及启动超时处理。

---

📂 项目结构

codex-celebrate/
├── .claude-plugin/marketplace.json # Claude Code 本地市场
├── .agents/plugins/
│   └── marketplace.json        # 本地插件市场元数据
├── plugins/codex-celebrate/
│   ├── .claude-plugin/plugin.json # Claude Code 插件清单
│   ├── .codex-plugin/
│   │   └── plugin.json         # 插件信息与界面定义
│   ├── hooks/
│   │   └── hooks.json          # 客户端生命周期 Stop 钩子声明
│   ├── Sources/
│   │   ├── main.swift          # AppKit 粒子系统与多屏窗口渲染核心
│   │   ├── Trigger.swift       # 事件过滤、限时启动
│   │   └── TriggerMain.swift   # Hook JSON 输入输出入口
│   ├── Tests/
│   │   └── TriggerTests.swift  # Swift 回归与并发测试
│   ├── scripts/
│   │   ├── build.sh            # Swift 原生编译脚本
│   │   ├── preview.sh          # 本地动效预览入口
│   │   ├── trigger.sh          # 定位并运行编译好的触发器
│   │   ├── toolchain.sh        # 构建与测试共用的工具链检查
│   │   └── test.sh             # Swift 测试入口
│   ├── assets/
│   │   ├── confetti-pop.wav    # 宣传片同款彩带音效
│   │   ├── celebrate-icon.png  # 插件图标
│   │   └── icon-prompt.md      # 图标设计 Prompt
│   └── Info.plist              # macOS App 属性配置
├── LICENSE                     # MIT 许可证
└── README.md

---

🔍 原理与工作流程

主 Agent 结束回合（Stop / Idle）
       │
       ▼ (由 Harness 生命周期直接触发，0 Token / 0 推理)
[Harness Hook / 插件监听]
       │
       ▼
[Swift 触发器 / 插件过滤]
  ├── ① 过滤子 Agent、工具调用或中断报错
  └── ② 校验通过 ──> 唤起 SessionConfetti.app
                            │
                            ▼
               [AppKit 原生粒子渲染引擎]
               (约 5 秒物理模拟，完成后自动静默退出)

• 纯事件驱动，0 Token 开销：Agent Harness 仅在生命周期节点通知本地逻辑，不传递会话正文，不回传上下文，无需二次模型推理。
• 生命周期机制：“结束”仅表示当前回合的停止信号（Stop / Idle）。若后续其他插件或自动化流程继续追加任务，彩带动画会按生命周期自然响应。
• 环境隔离：运行在 Agent Harness 所在机器的图形桌面会话中。若通过 SSH/容器连接远程无 GUI 环境，动画无法在本地屏幕弹出。
• 隐私与轻量：仅依据事件元数据筛选触发，不读取或落盘任何会话文本，无常驻后台守护进程。

---

📄 许可证

本项目基于 MIT 许可证 开源。

💡 致谢与灵感

• CodexBar overlay - 多屏全屏粒子覆盖思路灵感来源。
• Codex Hooks Documentation