From 9000eeeaa785dd955ed16febd4cee67149451796 Mon Sep 17 00:00:00 2001
From: laily <i@laily.net>
Date: Tue, 2 Jun 2026 14:37:40 +0800
Subject: [PATCH] docs: deprecate inbox and document remote dashboard

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                 | 47 +++++++++++++++++----------------------
 cmd/agent-notify/inbox.go |  1 +
 cmd/agent-notify/main.go  | 14 ++++++++++++
 internal/config/config.go |  2 ++
 4 files changed, 38 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 9263ada..3511f6c 100644
--- a/README.md
+++ b/README.md
@@ -50,12 +50,13 @@ title_template = "{agent} — {context}"  # context = 工作目录名
 body_stop = "等待输入"
 
 [inbox]
+enabled = false
+
+[remote]
 enabled = true
-socket = "/run/user/1000/agent-notify.sock"
-remote_socket = "/tmp/agent-notify-longbin.sock"
-addr = "127.0.0.1:17777"
-fallback_local = true
-timeout_ms = 500
+url = "http://your-server:8080"
+token = "shared-secret"
+timeout_ms = 2000
 ```
 
 ## 命令
@@ -64,44 +65,38 @@ timeout_ms = 500
 agent-notify send --event stop
 agent-notify hook cursor stop    # Cursor CLI stop hook
 agent-notify hook claude stop    # Claude Stop hook（输出 terminalSequence JSON）
-agent-notify inbox serve         # 本地接收远程通知记录
-agent-notify inbox list          # 列出未处理通知
-agent-notify inbox show <id>
-agent-notify inbox done <id>
-agent-notify inbox tui           # Bubble Tea TUI
-agent-notify inbox ssh-config install  # 自动写 ~/.ssh/config RemoteForward
+agent-notify server --listen :8080   # 远程汇总服务（见下方 Remote Dashboard）
+agent-notify inbox serve         # 已弃用：见下方 Inbox（deprecated）
 agent-notify test cursor [-v]
 agent-notify test claude [--apply]
 agent-notify doctor
 agent-notify install --all [--force]
 ```
 
-## 本地汇总 Inbox
+## Remote Dashboard
 
-在本地 Ghostty 所在机器启动接收服务：
+在可访问的机器上启动汇总服务（需设置与客户端相同的 token）：
 
 ```bash
-agent-notify inbox serve
+AGENT_NOTIFY_TOKEN=secret agent-notify server --listen :8080
 ```
 
-让命令自动写 SSH `RemoteForward` 配置：
+在 `~/.config/agent-notify/config.toml` 中启用远程上报（`agent-notify install` 会生成带 `[remote]` 的默认配置）：
 
-```bash
-agent-notify inbox ssh-config install
+```toml
+[remote]
+enabled = true
+url = "http://your-server:8080"
+token = "shared-secret"
 ```
 
-命令会在 `~/.ssh/config` 写入一个托管块，并把写入内容打印出来。已有 SSH 连接需要重连后才会生效。
+远程 Agent hook 在 `stop` 等事件时会向该服务 POST 状态；浏览器打开服务根路径即可查看 Web UI（输入 token 后加载会话列表）。
 
-默认写入的转发形式是：远程创建 `/tmp/agent-notify-$USER.sock`，转发到本地 `$XDG_RUNTIME_DIR/agent-notify.sock`。远程 hook 会尝试通过这个 SSH 反向转发把记录写回本地 inbox；如果本地接收服务不可用，会 fallback 写到远程机器自己的 `~/.local/state/agent-notify/inbox.jsonl`，避免丢记录。
+## 本地汇总 Inbox（已弃用）
 
-查看和处理：
+> **Deprecated：** 请改用上方的 Remote Dashboard（`agent-notify server` + `[remote]`）。`agent-notify inbox` 子命令仍会打印弃用警告并继续工作，便于过渡。
 
-```bash
-agent-notify inbox list
-agent-notify inbox show <id>
-agent-notify inbox done <id>
-agent-notify inbox tui
-```
+旧流程：在本地 Ghostty 机器运行 `agent-notify inbox serve`，用 `agent-notify inbox ssh-config install` 配置 SSH `RemoteForward`，通过 Unix socket 把远程通知写回本地 `inbox.jsonl`，并用 `inbox list` / `tui` 等处理。
 
 ## Hook 配置位置
 
diff --git a/cmd/agent-notify/inbox.go b/cmd/agent-notify/inbox.go
index 51ef935..959b2fd 100644
--- a/cmd/agent-notify/inbox.go
+++ b/cmd/agent-notify/inbox.go
@@ -17,6 +17,7 @@ import (
 )
 
 func cmdInbox(args []string, stdout, stderr io.Writer) error {
+	fmt.Fprintln(stderr, "warning: inbox is deprecated; use agent-notify server and [remote] config")
 	if len(args) == 0 {
 		return fmt.Errorf("usage: agent-notify inbox <list|show|done|rm|clear|serve|ssh-config>")
 	}
diff --git a/cmd/agent-notify/main.go b/cmd/agent-notify/main.go
index 133659e..597f2a6 100644
--- a/cmd/agent-notify/main.go
+++ b/cmd/agent-notify/main.go
@@ -192,6 +192,20 @@ func cmdDoctor() error {
 	}
 	cfgPath := config.DefaultPath()
 	fmt.Printf("  config=%s\n", cfgPath)
+	cfg, err := config.LoadDefault()
+	if err != nil {
+		fmt.Printf("✗ config load failed: %v\n", err)
+	} else if cfg.Remote.Enabled {
+		if cfg.Remote.URL == "" {
+			fmt.Println("✗ remote.enabled but remote.url is empty — set url to your agent-notify server (e.g. http://host:8080)")
+		}
+		if cfg.Remote.Token == "" {
+			fmt.Println("✗ remote.enabled but remote.token is empty — must match AGENT_NOTIFY_TOKEN on agent-notify server")
+		}
+		if cfg.Remote.URL != "" && cfg.Remote.Token != "" {
+			fmt.Printf("✓ remote dashboard configured (%s)\n", cfg.Remote.URL)
+		}
+	}
 	fmt.Printf("  hook_log=%s\n", logx.Path())
 	return nil
 }
diff --git a/internal/config/config.go b/internal/config/config.go
index a153a94..a10a32f 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -66,6 +66,8 @@ func Default() Config {
 		},
 		Remote: Remote{
 			Enabled:   false,
+			URL:       "",
+			Token:     "",
 			TimeoutMS: 2000,
 		},
 	}