内容
# Navi 🧚
> 你好！听我说！
一个为 AI 代理设计的桌面通知工具，灵感来自 *塞尔达传说：时之笛* 中的精灵。Navi 会浮动在你的屏幕上；当一个代理（Claude Code 或任何 MCP 客户端）调用她的 `notify` 工具时，她会响起，改变颜色，并以对话框的形式显示消息 —— 这样你就可以知道代理何时需要你的注意，而无需一直盯着终端。
| 类型 | 含义 | 颜色 | 铃声音量 |
|-----------|----------------------------|-----------|--------------|
| `紧急` | 代理需要你的批准 | 🔴 红色 | 100% |
| `警告` | 需要引起注意 | 🟡 黄色 | 60% |
| `成功` | 任务完成 | 🟢 绿色 | 35% |
当空闲时，她会发出柔和的蓝色光芒，轻轻摇晃，挥动翅膀，撒出火花，并在屏幕的角落中缓慢飘动。你可以通过她的身体拖动她到任意位置。
## 工作原理
一个 Electron 应用程序同时托管两个功能：
- **MCP 服务器**（可流式传输的 HTTP，无状态），监听 `0.0.0.0:8641`，暴露一个工具：
```javascript
notify(类型: "紧急" | "警告" | "成功", 消息: 字符串, 标题: 字符串)
```
- **精灵叠加层** — 一个透明的，无边框的，始终在最顶层的窗口。
系统托盘图标提供每种类型的测试通知，“复制 MCP 添加命令”快捷方式和退出功能。
## 要求
- Windows 10/11 及 Node.js LTS（该应用程序仅支持 Windows：透明叠加层 + 音频）。
- 代理可以运行在可以访问端口 8641 的任何地方，包括 WSL2。
## 从源代码运行
```powershell
npm install
npm start
```
在第一次启动时允许 Windows 防火墙提示（如果你的代理从 WSL2 连接，请勾选 **公共** — WSL 虚拟适配器通常被归类为公共）。
## 构建 exe
```powershell
npm run package
```
输出：`release/navi-win32-x64/navi.exe`。启动它会自动启动 MCP 服务器；启动时，Navi 的对话框会显示注册她与 Claude Code 的确切命令。
## 连接代理
从 Windows：
```
claude mcp add --transport http navi http://localhost:8641/mcp
```
从 WSL2（NAT 模式 — 默认），使用 Windows 主机 IP 地址：
```sh
HOST=$(ip route show default | awk '{print $3}')
claude mcp add --transport http navi http://$HOST:8641/mcp
```
NAT IP 地址可能会在重启后更改 — 如果调用停止连接，请重新运行命令，或在 `.wslconfig` 中启用 `networkingMode=mirrored`，使 `localhost` 在 WSL 中也可用。系统托盘的 **复制 MCP 添加命令** 始终具有当前 URL。
然后只需让你的代理使用它，或添加一个固定指令，如：
> 当你完成任务、需要我的批准或遇到问题时，请调用 `notify` 工具（类型：成功 / 紧急 / 警告）。
## 铃声
在 `assets/hey_listen.mp3` 处放置你自己的声音（gitignored — 自带；任天堂的音频不能与此仓库一起分发）。如果没有该文件，Navi 会使用 WebAudio 合成一个两音符的精灵铃声。
## 开发笔记
- 没有捆绑工具：两个 `tsc` 项目（`tsconfig.json` 用于主/预加载，`tsconfig.renderer.json` 用于浏览器全局渲染器脚本）。
- `npm run build` 编译两者；有关完整的开发日志和环境注意事项，请参见 `CLAUDE.md`。
## 已知限制
- 服务器监听 `0.0.0.0`，因此任何局域网主机都可以触发通知。对于家庭设置来说，这没问题；如果这让你感到烦恼，请对端口进行防火墙隔离。
- 始终在最顶层的功能不适用于独占全屏游戏。
