内容
# helios
一台守护进程中的两个功能：
1. **运行并广播到终端会话。** 通过后台守护进程运行 `helios run claude`（或任何命令），列出正在运行的会话，从另一个终端向一个或所有会话广播消息。
2. **与其他代理发送消息。** 独立的代理控制（Claude Code、Codex、Gemini CLI、OpenCode、Aider 等）与同一个守护进程注册，并相互发送消息 — 默认通过 CLI，或如果代理需要，则使用 MCP/A2A。
它有两个二进制文件：
- **`heliosd`** — 后台守护进程：拥有 PTY 会话，并运行邮箱
- **`helios`** — 您实际输入的 CLI
## 要求
- Go 1.26 或更新版本
- 会话运行（`run`/`list`/`broadcast`/`ui`）需要 macOS 或 Linux（Unix 域套接字，PTY）
- 邮箱（`register`/`send`/`inbox`/`who`）适用于任何操作系统 — 它是一个单独的 TCP 回环监听器，不绑定到上面的 Unix 套接字
## 构建
从仓库根目录：
```sh
go build -o heliosd ./cmd/heliosd
go build -o helios ./cmd/helios
```
如果您想从任何地方运行 `helios`，请将两者放在您的 `PATH` 中。
或者，一条命令来构建两者并在后台启动守护进程：
```sh
make daemon # 构建，启动 heliosd，日志记录到 /tmp/heliosd.log
make stop # 终止它
```
## 会话：运行，列出，广播
**1. 启动守护进程** （在自己的终端中，运行它）：
```sh
./heliosd
```
监听 `/tmp/helios.sock` 以获取会话，并监听 `127.0.0.1:47530` 以获取邮箱（使用 `HELIOS_MAILBOX_ADDR` 重写）。`make daemon` 为您执行此步骤。
**2. 启动会话** （在新终端中）：
```sh
./helios run claude
```
在托管的伪终端中启动 `claude`，并将您的终端连接到它。启动时打印会话 ID：
```
helios: 会话 "claude-492" （使用：helios broadcast "claude-492" "<msg>"）
```
给它您自己的 ID 而不是自动生成的 ID：
```sh
./helios run my-session zsh
```
退出会话（例如 `Ctrl+D`）以结束它。
**3. 列出和广播**，从任何其他终端在会话运行时：
```sh
./helios list
./helios broadcast "my-session" "hello" # 一个会话
./helios broadcast "hello everyone" # 所有活动会话
./helios ui # 只读检查器 TUI
```
## 邮箱：消息其他代理
不需要守护进程管理的会话 — 任何代理（您的或另一个控制器的）都可以注册并按名称向另一个代理发送消息。
```sh
./helios register alice
./helios register bob
./helios send alice bob "你能检查一下 auth 模块吗？"
./helios inbox bob
# [15:04:05] alice: 你能检查一下 auth 模块吗？
./helios who
# ["alice", "bob"]
./helios send alice "*" "注意，5 分钟后部署" # 发送给除发送者之外的所有人
```
代理通过与任何其他工具相同的方式发现 CLI 的存在 — `CLAUDE.md`/`AGENTS.md` 中的一行：
```
运行 `helios who` 以查看其他活动代理，运行 `helios send <name> "msg"` 以向一个代理发送消息。
```
### MCP 和 A2A — 可选，仅当控制器需要它们时
默认使用 CLI，因为每个控制器都已经具有 shell 访问权限，并且不会产生任何上下文 — MCP 工具的模式会为每个会话消耗实际令牌，无论是否使用。仅当控制器在没有 shell 的情况下被沙箱化时，才使用 MCP：
```sh
./helios mcp # 标准输入输出 MCP 服务器，暴露 helios_register/send/inbox/who
```
```json
{"mcpServers": {"helios": {"command": "helios", "args": ["mcp"]}}}
```
`heliosd` 还携带一个 A2A 代理卡（`cmd/heliosd/a2a.go`），用于真正的外部 A2A 原生代理 — 不是五个目标控制器，它们都通过 CLI 或 MCP 访问邮箱。目前仅为样板；完整的请求处理程序在实际需要时才会连接起来。
## 命令参考
```
helios run <命令> 使用自动生成的会话 ID 运行命令
helios run <会话 ID> <命令> 使用自定义会话 ID 运行命令
helios list 列出所有活动会话
helios broadcast "<消息>" 向每个活动会话发送消息
helios broadcast <会话 ID> "<消息>" 向一个会话发送消息
helios ui 打开只读检查器 TUI
helios register <名称> 将此代理注册到邮箱
helios send <发件人> <收件人> <消息> 消息一个代理，或 "*" 发送给所有人
helios inbox <名称> 读取并清除待处理的消息
helios who 列出最近 30 分钟内看到的代理
helios mcp 启动（可选的）MCP 服务器
```
## 清理
```sh
pkill -f heliosd # 终止守护进程
pkill -f 'helios run' # 终止任何正在运行的会话
pkill -f helios # 或者一次性终止所有进程
```
## 备注
- 会话 ID 必须唯一 — 重用仍在运行的 ID 将被拒绝。
- 广播作为原始按键发送到目标会话的终端，后跟 Enter — 无论会话是 shell 还是交互式程序，都可以正常工作。
- 邮箱是内存中的 — 当 `heliosd` 重新启动时，它会重置，与今天的会话一样。
- 邮箱 `send` 如果目标未注册则失败；广播（`to = "*"`) 跳过发送者，这会阻止明显的自回复循环，但不会阻止通过两个不同代理的更长的链路。
