agent-node

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

English | 中文

这是什么

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

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

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

快速开始

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

在 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"。

源码运行

# 前置: 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（唯一接入方式，推荐）

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。

文档

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

前提条件

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

许可证

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