# 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`）

## 构建与安装

```bash
./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>`。

## 插件协议（不要改 selector）

`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 → MioIsland 事件桥（会话状态上岛）

- 桥接脚本：`~/.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 配置后只对新会话生效。

## MioIsland 设置

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

## 安全注意

- `~/.config/token-bar/config.json` 含 API Key，不要打印/外发。
- 插件在宿主进程内运行，无沙箱——谨慎引入外部依赖，保持零依赖纯 Swift/SwiftUI。