Metadata-Version: 2.4
Name: lightclawbot
Version: 0.0.2
Summary: LightClaw platform plugin for Hermes Agent — connects via native WebSocket to LightClaw server
Author: lhanyun
License-Expression: MIT
Keywords: hermes,hermes-agent,lightclaw,plugin,websocket,chatbot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# lightclawbot

LightClaw 平台适配器插件，为 Hermes Agent 提供通过 WebSocket 接入 LightClaw 服务端的能力，使 Hermes Agent 能与 LightClaw 用户进行实时对话、收发文件附件、发送打字指示符，以及通过 cron 定时推送消息。

```
用户(前端) ←→ LightClaw Server ←→ lightclawbot ←→ Hermes AIAgent
              (WebSocket)        (本插件，非侵入)
```

---

## 工作原理

lightclawbot 采用 Hermes Agent 的**插件注册机制**集成，**不修改主仓库任何源码**。

Hermes Agent 启动时会：
1. 通过 `config.yaml` 的 `plugins.enabled` 列表加载启用的插件；
2. 在 `~/.hermes/plugins/lightclawbot/` 下查找 `__init__.py` + `plugin.yaml`；
3. 调用插件的 `register(ctx)` 函数注册 adapter。

注册后自动获得：

- `Platform("lightclawbot")` 动态枚举成员
- gateway 启动时创建并连接 `LightClawAdapter`
- `send_message` tool 通过 `_send_via_adapter()` 路由
- cron delivery 到 `lightclawbot:<chat_id>` 自动生效
- 用户授权遵循 `LIGHTCLAW_ALLOWED_USERS` 环境变量

---

## 前置条件

| 要求 | 最低版本 |
|---|---|
| Python | 3.11+ |
| Hermes Agent | 已安装 |
| aiohttp | 3.9+（由宿主 Hermes Agent 提供） |

> 本插件不直接声明 `aiohttp` 依赖；它由宿主 Hermes Agent 环境提供。

---

## 环境变量配置

在 `~/.hermes/.env` 中设置以下变量：

| 变量 | 必填 | 说明 |
|---|---|---|
| `LIGHTCLAW_API_KEY` | **是** | Bearer Token |
| `LIGHTCLAW_ALLOW_ALL_USERS` | 否 | 设为 `true` 接受所有用户消息 |

**最简配置示例：**

```dotenv
LIGHTCLAW_API_KEY=your-secret-api-key
LIGHTCLAW_ALLOW_ALL_USERS=true
```

---

## 启动网关

完成配置后正常启动 Hermes 网关：

```bash
hermes gateway start
```

只要 `LIGHTCLAW_API_KEY` 已设置，LightClaw 适配器就会自动建立连接。日志中应出现：

```
[lightclawbot] Bot clientId: xxxx, 1 key(s) mapped
[lightclawbot] Connected (sid=xxxx)
```

---

## Cron 定时投递

在 Hermes Agent 内创建定时任务时，指定 `deliver` 参数即可将结果推送到 LightClaw：

```
deliver=lightclawbot:<chat_id>
```

**示例（在 Hermes Agent 对话中）：**

```
每天早上 9 点发送新闻摘要。deliver=lightclawbot:123456
```

也可以设置全局默认投递目标：

```dotenv
LIGHTCLAW_HOME_CHANNEL=123456
```

---

## 项目结构

```
lightclawbot/
├── __init__.py             register(ctx) 插件入口
├── plugin.yaml             插件元数据（kind: platform）
└── src/                    adapter 实现
    ├── __init__.py         公开 API
    ├── adapter.py          主类 + 生命周期
    ├── config.py           常量 + 工具函数
    ├── inbound.py          入站消息处理
    ├── outbound.py         出站消息发送
    ├── history.py          历史记录/会话列表响应
    ├── media.py            媒体类型探测与格式化
    ├── file_storage.py     文件上传/下载 REST API
    ├── download_handler.py 客户端下载请求处理
    ├── tenancy.py          多租户 API key 映射
    └── socket/
        ├── native_socket.py    WebSocket 连接循环
        └── reliable_emitter.py ACK 重试发送
```

---

## 常见问题排查

### Bot 未上线 / 收不到消息

1. 确认 `LIGHTCLAW_API_KEY` 已设置且非空（`cat ~/.hermes/.env | grep LIGHTCLAW`）
2. 确认 `config.yaml` 中 `plugins.enabled` 包含 `lightclawbot`
3. 检查网关日志中是否出现 `[lightclawbot] Connected`；若无，WebSocket 握手失败

### `aiohttp not installed`

```bash
# 在 hermes 的 venv 里安装
~/.hermes/hermes-agent/venv/bin/pip install "aiohttp>=3.9,<4"
```

### 插件未被发现

确认以下两点：

```bash
# 1. 插件目录存在且结构正确
ls ~/.hermes/plugins/lightclawbot/
# 应当看到 __init__.py 和 plugin.yaml

# 2. config.yaml 已启用
grep -A2 plugins ~/.hermes/config.yaml
# plugins:
#   enabled:
#     - lightclawbot
```

---

## License

MIT
