Metadata-Version: 2.4
Name: hamp
Version: 0.1.5
Summary: Human-Agent-Machine Platform
Author-email: nzturn <nzturn@gmail.com>
Keywords: agent,ai,iot,mqtt,feishu,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: crpc>=0.1.3
Requires-Dist: msgpack<2,>=1.0
Requires-Dist: paho-mqtt<2,>=1.6
Requires-Dist: websockets<16,>=15
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.26; extra == "mcp"
Provides-Extra: hub
Requires-Dist: cryptography<47,>=42; extra == "hub"
Requires-Dist: fastapi<1,>=0.119; extra == "hub"
Requires-Dist: httpx<1,>=0.27; extra == "hub"
Requires-Dist: mcp<2,>=1.26; extra == "hub"
Requires-Dist: uvicorn<1,>=0.37; extra == "hub"
Provides-Extra: feishu
Requires-Dist: cryptography<47,>=42; extra == "feishu"
Requires-Dist: fastapi<1,>=0.119; extra == "feishu"
Requires-Dist: httpx<1,>=0.27; extra == "feishu"
Requires-Dist: uvicorn<1,>=0.37; extra == "feishu"
Requires-Dist: lark-oapi<2,>=1.5; extra == "feishu"
Requires-Dist: loguru<1,>=0.7; extra == "feishu"
Requires-Dist: mcp<2,>=1.26; extra == "feishu"
Provides-Extra: all
Requires-Dist: cryptography<47,>=42; extra == "all"
Requires-Dist: fastapi<1,>=0.119; extra == "all"
Requires-Dist: httpx<1,>=0.27; extra == "all"
Requires-Dist: uvicorn<1,>=0.37; extra == "all"
Requires-Dist: lark-oapi<2,>=1.5; extra == "all"
Requires-Dist: loguru<1,>=0.7; extra == "all"
Requires-Dist: mcp<2,>=1.26; extra == "all"
Provides-Extra: dev
Requires-Dist: cryptography<47,>=42; extra == "dev"
Requires-Dist: fastapi<1,>=0.119; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: uvicorn<1,>=0.37; extra == "dev"
Requires-Dist: lark-oapi<2,>=1.5; extra == "dev"
Requires-Dist: loguru<1,>=0.7; extra == "dev"
Requires-Dist: mcp<2,>=1.26; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"

# HAMP

HAMP（Human-Agent-Machine Platform）连接人、AI Agent 与远端机器。用户可以通过 Web 或飞书向多个 Agent 分派任务；Agent 使用其原生文件、终端和开发工具完成工作，并可在审批后调用远端 Machine 暴露的结构化能力。

> HAMP 当前处于 Alpha 阶段，接口和配置可能在后续版本中调整。

## 特性

- 统一管理多个 Agent 和 Machine，支持在线状态、会话绑定和消息路由；
- 内置 Codex Agent 适配器，并允许扩展其他 AI Agent；
- Web/PWA 与飞书入口共享会话和执行状态；
- Agent 与 Machine 通过 WebSocket/WSS 主动连接 Hub；
- 使用 MessagePack 二进制帧传输，支持 CRPC `get`、`set` 和 `call`；
- Machine 可桥接站点内已有的 MQTT/CRPC 服务，也可暴露本地 Python 模块；
- 支持高风险 Machine 操作审批、超时控制、迟到结果和 SQLite 审计；
- 支持独立 Node token 的签发、过期和吊销；
- 可选 Hub 托管模型认证，使远端 Agent 无须保存上游模型密钥。

## 架构

```text
                   Web/PWA / Feishu
                           │
                           ▼
                          Hub
              conversations · routing · approval
                    ┌──────┴──────┐
                    │ WebSocket   │ WebSocket
                    ▼             ▼
               Agent Node     Machine Node
               Codex / AI      structured calls
                                      │
                                      ▼
                             local MQTT / CRPC
                                      │
                                      ▼
                                   Devices
```

Hub 不实现新的 Agent Loop。Agent 继续使用现有 AI 产品提供的文件编辑、终端、Git 和测试能力。Machine Node 不运行 AI，只负责执行明确的结构化调用。

跨网络的 Hub/Node 通信使用 WebSocket；MQTT 仅用于 Machine 所在站点的本地 CRPC 域，不应直接暴露到公网。

## 安装

HAMP 需要 Python 3.10 或更高版本。

```bash
# Agent 和 Machine Node
python -m pip install hamp

# Agent 调用 Machine 的 MCP 支持
python -m pip install "hamp[mcp]"

# Hub 与 Web 界面
python -m pip install "hamp[hub]"

# Hub、Web 与飞书适配器
python -m pip install "hamp[feishu]"

# 所有可选运行依赖
python -m pip install "hamp[all]"
```

使用 Codex Agent 时，还需单独安装 Codex CLI。HAMP 会自动发现 Codex
原生可执行文件；Windows 上即使 `PATH` 指向 npm 的 `codex.cmd`，也会自动定位
npm 全局安装目录或 VS Code Codex 扩展内的 `codex.exe`，无需传入可执行文件路径。

## 快速开始

### 单机演示

已登录 Codex CLI 的电脑可以直接启动 Hub、Web 界面和本地 Agent：

```bash
hamp --open
```

浏览器访问 <http://127.0.0.1:8765/web/>。

恢复指定 Codex 会话：

```bash
hamp --session <session-id> --open
```

### 分别启动 Hub 和 Agent

配置仅供 Human Adapter 和 Web 管理面使用的 control token，然后启动 Hub：

```bash
export HAMP_CONTROL_TOKEN=<random-control-token>
hamp-hub --web 0.0.0.0:8765
```

`--web` 使用 `HOST:PORT` 格式；默认值为 `127.0.0.1:8765`。

Owner 先通过飞书添加 Node 并取得一次性邀请：

```text
/add agent-a
```

然后在 Agent 所在电脑启动 Node，并附上机器人返回的邀请：

```bash
hamp-agent \
  --id agent-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --dir /path/to/project \
  --key <one-time-key>
```

邀请不设置有效期，但只能使用一次。Node 首次连接时在本地生成并保存自己的私有凭据；Hub 验证邀请后登记该凭据，邀请随即失效。私有凭据不会经过飞书。Windows PowerShell 可将行尾的 `\` 改为反引号，或将命令写在一行。

### 连接 Machine

桥接站点内已有的 MQTT/CRPC service：

```bash
hamp-machine \
  --node-id machine-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --backend crpc \
  --service controller
```

直接将本地 Python 模块作为 peval service 暴露：

```bash
hamp-machine \
  --node-id machine-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --backend local \
  --module device_adapters
```

模块中的公开对象、属性和方法分别通过相同的 `get`、`set`、`call` 语义访问，无须修改 HAMP 源码注册。

## 飞书接入

安装 `hamp[feishu]`，配置飞书应用凭据后启动：

```bash
export FEISHU_APP_ID=<app-id>
export FEISHU_APP_SECRET=<app-secret>
hamp --feishu --open
```

Windows PowerShell 使用 `$env:FEISHU_APP_ID = "..."` 和 `$env:FEISHU_APP_SECRET = "..."`。

支持的主要命令：

```text
/help
/status
/agents
/use <agent-id>
/cancel
/approve <operation-id>
/reject <operation-id>
/allow @成员
/deny @成员
/add <node-id>
/del <node-id>
```

已授权成员使用 `/status` 查看当前会话绑定的 Agent；只有 Owner 可以使用 `/agents` 查看全部 Agent。飞书支持向 Agent 发送文件：先发送一个或多个文件，再发送处理指令，文件会交给该指令所使用的 Agent。

不同私聊或群聊可分别绑定 Agent。默认只有应用创建者能够操作机器人；创建者在群聊中使用 `/allow @成员` 时，权限仅对当前群聊和该群当前绑定的 Agent 生效，并可在同一群聊使用 `/deny @成员` 回收。普通成员不能使用 `/use` 切换 Agent，也不能通过 `@agent-id` 操作其他 Agent；只有 Owner 能选择或临时指定 Agent。群成员单独私聊机器人时仍无权调用 Agent。Owner 权限全局有效，授权记录持久保存在 Hub 运行目录中。未获授权的成员即使 @机器人也不会触发 Agent。

飞书消息撤回会同步到 Hub：尚未处理的文件或排队中的命令会被取消，正在运行的命令会请求停止且不再发送最终回复；已经完成的操作不会回滚。撤回后的消息正文会从 Hub 消息记录中清除，仅保留不含原文的审计信息。

## 多 Agent

同一台电脑可以运行多个 Agent，但每个进程必须使用不同的 `node_id`、工作目录和 AI session：

```bash
hamp-agent --id agent-a --dir /work/project-a \
  --hub ws://127.0.0.1:8765/ws/node --session <session-a>

hamp-agent --id agent-b --dir /work/project-b \
  --hub ws://127.0.0.1:8765/ws/node --session <session-b>
```

不要让多个进程同时写入同一个 Codex session。

## TLS 与安全

默认配置使用 HTTP/WS，适用于可信内网和本机测试。不要把默认端口直接暴露到公网。

启用 HTTPS/WSS：

```bash
hamp-hub --tls
```

若未指定证书，Hub 会在 `.hamp/tls/` 生成自签名证书。正式部署应使用受信任证书，并通过以下环境变量指定：

```text
HAMP_TLS_CERTFILE=/path/to/fullchain.pem
HAMP_TLS_KEYFILE=/path/to/private.key
```

安全部署还应遵循以下原则：

- 每个 Agent 和 Machine 使用独立、随机生成的 Node token；
- 将 token 通过环境变量或受保护的配置文件传入；
- 使用 WSS 或受保护的私有网络承载跨网络通信；
- 仅向 Machine 暴露必要的 service，并配置 payload 大小和执行超时；
- 对具有副作用的 Machine 操作启用人工审批；
- 将站点 MQTT broker 保留在可信局域网内，并自行配置认证和 ACL。

当前 Node 客户端允许使用 Hub 自动生成的自签名证书，因此不会验证其证书链与主机名。此模式便于测试，但不能抵御中间人攻击；公网部署应在受保护网络中使用，或等待客户端 CA 校验能力完善后再直接开放。

## 托管模型认证

Hub 可以提供 OpenAI-compatible 模型网关，使远端 Agent 不保存上游 API key：

Hub 默认使用 `--provider auto`：配置了 `HAMP_PROVIDER_API_KEY` 时选择
OpenAI API，否则使用 `~/.codex/auth.json` 中的 Codex OAuth 登录。也可以
显式指定 `--provider openai` 或 `--provider codex`。

```bash
export HAMP_PROVIDER_TYPE=openai
export HAMP_PROVIDER_URL=https://api.openai.com/v1
export HAMP_PROVIDER_API_KEY=<provider-api-key>
hamp-hub --provider openai
```

使用当前用户的 Codex OAuth 时：

```bash
hamp --feishu \
  --provider codex \
  --proxy http://127.0.0.1:7897
```

`--data` 默认使用 `~/.hamp`，`--auth` 默认使用 `~/.codex/auth.json`；仅在需要更换位置时指定。`hamp` 和 `hamp-hub` 均支持 `--provider`、`--proxy`、`--data` 和 `--auth`。

Agent 使用自动配对的 Node 凭据访问网关，并且必须已通过 `/use` 激活：

```bash
hamp-agent \
  --id agent-a \
  --hub wss://hub.example/ws/node
```

Agent 默认使用 Hub 托管的模型认证，并从 `--hub` 自动推导模型网关；只有
反向代理将两者发布在不同地址时才需要额外指定 `--gateway`。使用 Agent
电脑自己的 Codex 账号时添加 `--own`。

`/del agent-a` 会回收 managed-auth、吊销 Node 凭据并断开 Node。重新接入需要再次执行 `/add agent-a`。

## 命令行工具

| 命令 | 用途 |
| --- | --- |
| `hamp` | 启动本地演示环境 |
| `hamp-hub` | 启动 Hub 和 Web 界面 |
| `hamp-agent` | 启动 Agent Node |
| `hamp-machine` | 启动 Machine Node |
| `hamp-feishu` | 单独启动飞书适配器 |
| `hamp-mcp` | 启动供 AI 使用的 HAMP MCP 工具 |

运行 `<command> --help` 查看完整参数。
