AGENTS.md — MioIsland 插件开发指南

本目录是一个 MioIsland（刘海岛）插件项目。动手前请先读完本文件。

背景

MioIsland（/Applications/Mio Island.app，开源：github.com/MioMioOS/MioIsland）把 MacBook 刘海变成"灵动岛"。插件以 .bundle 形式在运行时被宿主加载。
本机有三个自研插件项目（结构相同，本文件会同步到各自目录）：
- ~/mio-deepseek-balance — DeepSeek 余额（id: deepseek-balance）
- ~/mio-runcat — CPU 小猫跑速（id: runcat）
- ~/mio-agent-status — Kimi Code / TRAE 状态点（id: agent-status）

./build.sh install    # 编译 + ad-hoc 签名 + 装入 ~/.config/codeisland/plugins/
# 然后重启 MioIsland（pkill -f "Mio Island" && open -a "Mio Island"）

只编译 arm64（Apple Silicon）。
id（kebab-case）必须与 Info.plist 的 CFBundleIdentifier 后缀（com.mioisland.plugin.<id>）、build.sh 的 PLUGIN_NAME、输出 bundle 文件名完全一致。
NSPrincipalClass 格式：<ModuleName>.<ClassName>。

Sources/MioPlugin.swift 是宿主协议的逐字拷贝，宿主通过 responds(to:) + perform(_:) 匹配，改任何 selector 都会导致静默加载失败：

必备：id / name / icon(SF Symbol) / version / activate() / deactivate() / makeView() -> NSView
可选：viewForSlot("header", context:) -> NSView? —— 返回刘海头部常驻小视图（约 20×20 起，宽度可自适应），这是"常驻显示"的关键入口
视图一律用 NSHostingView(rootView:) 包 SwiftUI

DeepSeek 余额：读 ~/.config/token-bar/status.json（由 ~/token-bar/token_bar.py 每 30 分钟抓取写入）。DeepSeek 没有公开账单 API（billing/transactions/usage 均 404），充值/消耗明细用 ~/.config/token-bar/balance_history.json 快照差分推算（余额上涨 >¥1 记为充值）。
RunCat：猫帧渲染器与速度曲线来自 ~/CodeM/playgrounds/default/RunCat/（CatArt.swift + Theme.swift + Metrics.swift 拷贝进插件 Sources）。速度 = 0.4 + 3.6×(CPU/100)^0.6 循环/秒，EMA α=0.3，相位驱动。
Agent 状态：Kimi Code 用 ~/.kimi-code/sessions/**/wire.jsonl 最新 mtime 判定；TRAE 用 ps 统计 TRAE SOLO CN 进程 CPU。

桥接脚本：~/.kimi-code/hooks/mio-island.py，把 Kimi Code hook 事件翻译成 MioIsland 原生协议（与 Claude Code 的 codeisland-state.py 同格式），发 Unix socket /tmp/codeisland.sock。
已在 ~/.kimi-code/config.toml 注册 15 个 [[hooks]]（UserPromptSubmit/PreToolUse/PostToolUse/Stop/SessionEnd 等）。
限制：Kimi 的 PermissionRequest 是只读事件，岛上只能显示"等待审批"，不能代替终端批准。改 hook 配置后只对新会话生效。

偏好：~/Library/Preferences/com.codeisland.app.plist 的 notchCustomization.v1（JSON 字符串），含 defaultGeometry.notchHeight（岛的下探高度，当前 48）、horizontalOffset、maxWidth。改完需重启 MioIsland。
已 pin 的插件列表在同 plist 的 PinnedPluginIds。