# agent-node

去中心化局域网多智能体协作节点 —— AI 可控的增强版 LocalSend。

[English](./README.en.md) | [中文](./README.md)

## 这是什么

`agent-node` 让局域网内的一台台电脑互相成为彼此的能力。每台电脑运行一个节点，
节点间**自动发现**、**点对点直连**（无中心服务器、无账号、纯局域网明文）。任何接入
节点的 AI 智能体可以获得：

1. **调用其他电脑上的 AI 智能体** —— 执行器（CodeBuddy CLI/TUI、WorkBuddy，可扩展插件）
2. **跨机文件传输** —— 推送/拉取/浏览任意目录，带文件选择器与收件历史
3. **跨机聊天与远程命令** —— LocalSend 式聊天 + 受开关管辖的远程 shell

> 设计原则：最小拓扑、全放开、明文、纯点对点。不设中心、不依赖公网。

## 快速开始

### 方式零：一行命令安装（Windows，无 Node，推荐）

在 PowerShell 里粘贴这一行并回车即可：

```powershell
irm https://raw.githubusercontent.com/weifeng-work/agent-node/main/scripts/install.ps1 | iex
```

**不需要 Node / npm / git**。脚本自动检测系统 Python（≥3.10，缺失用 winget 装一次）→
下载源码 zip → 在 `%LOCALAPPDATA%\agent-node` 建 venv 装依赖 → 确保 `data\`
（已存在则保留，**重装/更新不丢身份与配置**）→ 安装全局命令 `agent-node`（纯 PowerShell，
加入用户 PATH）→ **创建桌面快捷方式** → **自动启动节点并打开面板**。

日常控制：双击桌面 `agent-node`，或任意终端 `agent-node start|stop|status|restart|update`。
失败会输出清晰提示。可选：`irm ... | iex -Args "-SkipShortcut -SkipStart"`。

### 源码运行

```bash
# 前置: Python ≥ 3.10, Windows 10/11
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m node.main --data-dir data
```

## 命令行

| 命令 | 说明 |
|---|---|
| `agent-node` | 启动节点（已运行则打开面板） |
| `agent-node start` | 启动节点 |
| `agent-node stop` | 停止节点 |
| `agent-node status` | 查看状态 |
| `agent-node restart` | 重启节点（保持驻留） |
| `agent-node update` | 更新节点代码与依赖 |
| `agent-node help` | 帮助 |
| `agent-node --help` | cli.py 完整子命令列表 |
| `agent-node <子命令>` | 调用 AI 能力（info/list/executors/task/...） |

> **被 AP 隔离时自动自愈**：默认互不发现的节点，自动做「出站扫描」——凡连上的节点即
> 自动建立常驻连接（出站流量不被隔离规则拦截）。扫描优先拨**固定通告端口（每 IP 1 端口，
> 默认 49700）**拿对方真实对等端口再连，免盲扫 20 口对等段；通告不可达才回落段扫
> （49710–49729）。**无需任何人工配置，启动节点即生效**。也可用
> `python -m tools.cli anchor add <host> <对方对等TCP端口>`（或面板"锚点"卡）手动指定
> 锚点作为补充；`anchor list` / `anchor remove <host>` 管理。已有连接时也会**周期轻扫**，
> 捕捉后加入的孤立节点。
>
> > 前提：各节点默认对等端口在约定段（49710–49729）内自动分配，故扫描方能猜中并连上。
> > 显式配置的 `peer_tcp_port` 仍优先。发现信道为 UDP 广播 + 组播（`239.255.42.47`）四路送达。

## 让 AI 使用本节点

统一通过 `agent-node` 全局命令接入。AI 能执行 shell 命令即可使用全部能力。

### 方式 A：MCP（已废弃，不再推荐）

> MCP 接入方式已废弃，不再维护。保留 mcp/server.py 源码但不更新。
> 请使用方式 B（CLI 命令）替代，功能完全等价且无需客户端配置。

### 方式 B：CLI（唯一接入方式，推荐）

```bash
agent-node register                    # 首次注册身份（只需一次）
agent-node list                        # 列出在线节点
agent-node info                        # 本机节点概览
agent-node task --target <node_id> --executor workbuddy --prompt "要 WorkBuddy 做的任务"
agent-node mailbox                     # 取异步回执
agent-node --help                      # 完整子命令列表
```

### 让任何 AI 驾驶本节点

把下面这段话发给智能体，它会自取说明书、自安装、自动使用：

> 请先读取 agent-node 节点的 skill 说明书后告诉我：本机有哪些可用执行器？怎么调用远程智能体？
> 说明书获取方式（任选）：
> · 在线直接读：https://raw.githubusercontent.com/weifeng-work/agent-node/main/skill/SKILL.md
> · 本机已装（Windows 一键安装）：`%LOCALAPPDATA%\agent-node\app\skill\SKILL.md`
> · 源码形态：本地仓库根 `skill\SKILL.md`

## MCP 之后如何使用更多功能

- **自动发现**：局域网内所有 agent-node 实例自动互见，无需配置
- **调用远程智能体**：跨机提交任务（sync 同步 / async 异步 / trigger 触发）
- **文件推送/拉取**：节点选择 + 文件/文件夹选择器 + 历史
- **文件夹同步**：Syncthing 驱动，auto 局域网配对，面板看每节点同步完成度
- **聊天 / 远程 shell**：LocalSend 式聊天 + 受开关管辖的 shell

## 架构

```
每节点（自用局域网，明文，全放开）：
┌──────────────────────────────────────────────┐
│ 节点核心 NodeCore（UDP beacon + TCP mesh）   │
│ 执行器注册表（CodeBuddy/WorkBuddy/...插件）  │
│ 文件控制 · 聊天 · shell · Syncthing 托管     │
│ Web 面板（FastAPI）+ CLI（agent-node 全局命令）   │
└──────────────────────────────────────────────┘
```

无中心、无代理、纯点对点。详细设计与协议见 [docs/重构设计方案.md](docs/重构设计方案.md)。

## 文档

| 文档 | 说明 |
|---|---|
| [skill/SKILL.md](skill/SKILL.md) | AI 智能体使用节点的官方说明书（不需要双语，大模型通晓主流语言） |
| [docs/重构设计方案.md](docs/重构设计方案.md) | 施工方案、需求树、附录 A 线级协议 |
| [docs/协议与架构.md](docs/协议与架构.md) | 深文档（门控，线级协议与架构完整规范） |
| [docs/执行器开发指南.md](docs/执行器开发指南.md) | 开发者编写执行器插件的接口与功能实现指南 |
| [docs/executor-dev-guide.md](docs/executor-dev-guide.md) | Executor development guide (English) |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
| [VERSIONS.md](VERSIONS.md) | 依赖与二进制版本锁定清单 |

## 前提条件

- **Python** ≥ 3.10（节点本体）
- **Windows** 10/11（代码含 Linux 路径，未在 Linux 实测）

## 许可证

MIT。随包分发的 Syncthing（MPL-2.0）与 psmux/tmux 以独立可执行文件分发，
不构成衍生作品，许可证见 [VERSIONS.md](VERSIONS.md)。