chuan
79992680c9
- README 对齐当前 C# / Avalonia 架构与安装方式 - docs: architecture / sequences / hooks-and-cli / interop / build-and-install
138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# Claude Code Notify (.NET / Avalonia)
|
||
|
||
为 Claude Code 提供**原生 Windows 通知**:Claude 干完活或需要你输入时，在屏幕角落弹出 toast，**点击即可跳回原终端/编辑器窗口**（并能切回正确的 Windows Terminal 标签页）。
|
||
|
||
这是原版 Rust 项目的 **C# / .NET 10 + Avalonia 12** 重写版。整体是一个**瘦客户端 CLI + 常驻 Host** 的进程模型，由 Claude Code 的 hook 驱动。
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 原生 toast | 任务完成 / 需要输入时弹出，深色圆角、图标 + 标题 + 正文 + 关闭键 |
|
||
| 一键返回 | 左键点击 toast → 抢前台激活当初发起请求的窗口 |
|
||
| 标签页感知 | 目标是 Windows Terminal 时，激活后切回提问时所在的标签 |
|
||
| 调用方图标 | 沿进程树上溯识别 VSCode / Cursor / JetBrains / Windows Terminal 等，显示其图标 |
|
||
| 跨虚拟桌面 | 可选把通知钉到所有虚拟桌面（Win+Tab 切桌面也能看到） |
|
||
| 堆叠 / 排队 | 多条通知按方向堆叠，超出上限的排队 |
|
||
| 常驻 / 聚焦短显 | 输入类常驻不消失；完成类自动消失，且你正盯着目标窗口时只弹更短时间 |
|
||
| 工具窗口 | 不进任务栏、不进 Alt+Tab |
|
||
| 提示音 | 弹出时可选播放提示音（带防连环音） |
|
||
| 非阻塞投递 | 钩子毫秒级返回，**绝不拖慢 Claude Code** |
|
||
| 自由定位 | 水平(左/中/右) × 垂直(上/中/下) + 边缘留白，任意组合 |
|
||
|
||
---
|
||
|
||
## 架构一览
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
CC[Claude Code] -->|UserPromptSubmit| SAVE["notify save"]
|
||
CC -->|Stop| NOTIFY["notify notify"]
|
||
CC -->|Notification / PreToolUse| INPUT["notify input"]
|
||
CC -->|SessionEnd| CLEAN["notify cleanup"]
|
||
|
||
SAVE --> ST[(状态文件<br/>%TEMP%/claude-notify-id.json)]
|
||
CLEAN -.删除.-> ST
|
||
NOTIFY --> SP[(spool 队列<br/>%TEMP%/claude-notify-spool)]
|
||
INPUT --> SP
|
||
|
||
SP --> HOST
|
||
ST -.读取.-> NOTIFY
|
||
ST -.读取.-> INPUT
|
||
|
||
subgraph HOST["notify host (Avalonia 常驻)"]
|
||
W[FileSystemWatcher] --> T1[Toast]
|
||
W --> T2[Toast]
|
||
end
|
||
|
||
T1 -->|点击| ACT[激活窗口 + 切 WT 标签]
|
||
```
|
||
|
||
- **CLI 子命令**（`save/notify/input/cleanup`）：纯 Win32 互操作 + 落盘，**不加载 Avalonia**，做完即退。
|
||
- **Host**（无参 / `host`）：Avalonia 单例常驻，仅托盘存在，监视 spool 目录弹通知。
|
||
- 详细时序见 [docs/sequences.md](docs/sequences.md)。
|
||
|
||
---
|
||
|
||
## 安装与使用
|
||
|
||
> 当前用**框架依赖型**构建（依赖已安装的 .NET 10 运行时），AOT 单文件发布见 [docs/build-and-install.md](docs/build-and-install.md)。
|
||
|
||
### 1. 构建
|
||
|
||
```bash
|
||
cd Notify
|
||
dotnet build -c Release
|
||
# 产物: Notify/bin/Release/net10.0-windows/notify.exe （含同目录依赖 DLL）
|
||
```
|
||
|
||
### 2A. 直连 settings.json（推荐，最省事）
|
||
|
||
把 exe 所在文件夹加入 PATH 后，往 `~/.claude/settings.json` 的 `hooks` 里加：
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "notify save", "timeout": 5 }] }],
|
||
"Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "notify notify", "timeout": 10 }] }],
|
||
"Notification": [{ "matcher": "", "hooks": [{ "type": "command", "command": "notify input", "timeout": 10 }] }],
|
||
"PreToolUse": [{ "matcher": "AskUserQuestion|ExitPlanMode", "hooks": [{ "type": "command", "command": "notify input", "timeout": 10 }] }],
|
||
"SessionEnd": [{ "matcher": "", "hooks": [{ "type": "command", "command": "notify cleanup", "timeout": 5 }] }]
|
||
}
|
||
}
|
||
```
|
||
|
||
不加 PATH 就把 `notify` 换成 exe 的绝对路径（用正斜杠）。配完**重启 Claude Code**。
|
||
|
||
### 2B. 作为插件安装（marketplace）
|
||
|
||
仓库已含合规的 `.claude-plugin/` 与 `hooks/hooks.json`（命令指向 `${CLAUDE_PLUGIN_ROOT}/bin/notify.exe`）。把构建产物放进插件根的 `bin/` 后：
|
||
|
||
```bash
|
||
claude plugin marketplace add <仓库本地路径或 GitHub repo>
|
||
claude plugin install claude-code-notify@claude-code-notify
|
||
```
|
||
|
||
详见 [docs/build-and-install.md](docs/build-and-install.md)。
|
||
|
||
---
|
||
|
||
## 设置
|
||
|
||
- 托盘**左键单击** → 打开设置窗口；**右键** → 退出。
|
||
- 配置持久化到 `%APPDATA%\ClaudeCodeNotify\settings.json`。
|
||
|
||
| 项 | 默认 | 说明 |
|
||
|----|------|------|
|
||
| 停留时长（秒） | 4 | 完成类自动消失前的停留 |
|
||
| 聚焦时停留（秒） | 2 | 目标窗口已在前台时用更短的停留 |
|
||
| 水平方向 | Right | Left / Center / Right |
|
||
| 垂直方向 | Bottom | Top / Center / Bottom（决定堆叠方向） |
|
||
| 边缘留白（DIP） | 12 | 与屏幕边缘的距离 |
|
||
| 不透明度 | 0.96 | |
|
||
| 最多同时显示 | 5 | 超出排队 |
|
||
| 宽度（DIP） | 340 | |
|
||
| 淡入淡出（毫秒） | 300 | |
|
||
| 播放提示音 | 开 | |
|
||
| 跨所有桌面显示 | 开 | 未公开 API，失败自动退回单桌面 |
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [docs/architecture.md](docs/architecture.md) | 进程模型、组件、目录结构 |
|
||
| [docs/sequences.md](docs/sequences.md) | 各路径的调用时序图（save / 投递 / 点击激活 / 切标签） |
|
||
| [docs/hooks-and-cli.md](docs/hooks-and-cli.md) | hook 事件、子命令、stdin JSON、状态文件 |
|
||
| [docs/interop.md](docs/interop.md) | 原生互操作（激活 / UIAutomation / 跨桌面 / 图标）与 AOT 说明 |
|
||
| [docs/build-and-install.md](docs/build-and-install.md) | 构建、安装、AOT、排错 |
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
.NET 10 · Avalonia 12 · CommunityToolkit.Mvvm（`partial` 属性源生成）· Semi.Avalonia · Irihi.Ursa · System.Text.Json 源生成 · 全程 `LibraryImport` / 源生成 COM（面向 NativeAOT）。
|