lightclawbot 0.0.2__tar.gz

lightclawbot-0.0.2/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include lightclawbot *.yaml

lightclawbot-0.0.2/PKG-INFO

@@ -0,0 +1,177 @@
+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

lightclawbot-0.0.2/README.md

@@ -0,0 +1,159 @@
+# 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

lightclawbot-0.0.2/lightclawbot/__init__.py

@@ -0,0 +1,88 @@
+"""
+lightclawbot — LightClaw platform plugin for Hermes Agent.
+
+Registers the LightClaw adapter via the Hermes plugin discovery system.
+No source-code modifications to lighthouse-hermes are required — the adapter
+is discovered automatically when this package is placed under
+``~/.hermes/plugins/lightclawbot/`` or installed via pip (entry_points).
+"""
+
+import os
+
+
+def _get_version() -> str:
+    """Return package version from importlib.metadata, with fallback."""
+    try:
+        from importlib.metadata import version
+
+        return version("lightclawbot")
+    except Exception:
+        return "0.0.0"
+
+
+__version__ = _get_version()
+
+
+def _load_platform_hint() -> str:
+    """Return the LightClaw-specific LLM capability hint.
+
+    Only contents that are *unique* to LightClaw belong here.  The generic
+    ``MEDIA:/absolute/path/to/file`` protocol, supported extensions and
+    text post-processing are owned by the framework
+    (``BasePlatformAdapter.extract_media`` + ``PLATFORM_HINTS`` in
+    ``agent/prompt_builder.py``) and are intentionally NOT re-stated here.
+    """
+    return (
+        "You are on LightClaw, a WebSocket-based messaging platform. "
+        "Markdown formatting is supported (code blocks, bold, italic, tables). "
+        "You can send files natively by including MEDIA:/absolute/path/to/file "
+        "in your reply; the file is delivered to the user as an on-demand "
+        "download link (no need to upload or build https URLs yourself). "
+        "For cron jobs / reminders / scheduled tasks, always set "
+        "deliver='lightclawbot:<chat_id>' so results reach the user instead of "
+        "being saved locally."
+    )
+
+
+def _validate_config(config) -> bool:
+    """Check whether the platform config has enough info to connect."""
+    extra = getattr(config, "extra", {}) or {}
+    return bool(extra.get("api_keys") or os.getenv("LIGHTCLAW_API_KEY", ""))
+
+
+def _is_connected(config) -> bool:
+    """Check whether the platform is sufficiently configured (for status display)."""
+    extra = getattr(config, "extra", {}) or {}
+    return bool(extra.get("api_keys"))
+
+
+def register(ctx):
+    """Called by the Hermes plugin discovery system.
+
+    Registers the LightClaw platform adapter so that:
+      - Platform("lightclawbot") resolves to a dynamic enum member
+      - The gateway creates and connects a LightClawAdapter at startup
+      - send_message routes to the adapter via _send_via_adapter()
+      - Cron delivery to "lightclawbot:<chat_id>" works automatically
+      - User authorization respects LIGHTCLAW_ALLOWED_USERS env var
+    """
+    from .src import LightClawAdapter, check_lightclaw_requirements
+
+    ctx.register_platform(
+        name="lightclawbot",
+        label="LightClawBot",
+        adapter_factory=lambda cfg: LightClawAdapter(cfg),
+        check_fn=check_lightclaw_requirements,
+        validate_config=_validate_config,
+        is_connected=_is_connected,
+        required_env=["LIGHTCLAW_API_KEY"],
+        install_hint="See https://pypi.org/project/lightclawbot/",
+        allowed_users_env="LIGHTCLAW_ALLOWED_USERS",
+        allow_all_env="LIGHTCLAW_ALLOW_ALL_USERS",
+        max_message_length=4096,
+        emoji="⚡",
+        platform_hint=_load_platform_hint(),
+    )
+
+
+__all__ = ["register", "__version__"]

lightclawbot-0.0.2/lightclawbot/plugin.yaml

@@ -0,0 +1,10 @@
+name: lightclawbot
+kind: platform
+version: 0.0.2
+description: >
+  LightClaw gateway adapter for Hermes Agent.
+  Connects to a LightClaw-compatible server via native WebSocket,
+  receiving user messages and sending AI responses back through the same protocol.
+author: lhanyun
+requires_env:
+  - LIGHTCLAW_API_KEY

lightclawbot-0.0.2/lightclawbot/src/__init__.py

@@ -0,0 +1,37 @@
+"""
+LightClaw platform adapter for Hermes Agent.
+
+Connects to a LightClaw-compatible server via native WebSocket,
+receiving user messages and sending AI responses back through the same protocol.
+
+Protocol (post socket-rewrite):
+- Auth:      POST /cgi/ticket  → { code:0, data:{ client:{ extra:'{"botId":"..."}' }, ticket:"..." } }
+- Transport: Native WebSocket  wss://<domain>/ws/agent?ticket=<ticket>&enableMultiLogin=false
+- Framing:   Raw JSON  { "event": "<name>", "data": {...} }
+- Handshake: server sends { "event": "__handshake__", "data": { "id": "<socket_id>" } }
+- ACK:       server sends { "event": "message:ack", "data": { "relatedMsgId": "<msgId>" } }
+- Events:    message:private (bidirectional), history/sessions request/response
+- Kinds:     text, typing_start, stream_chunk, stream_end, typing_stop
+
+Package layout (mirrors lightclaw/src/):
+    config.py                ← constants + utils           (config.ts)
+    socket/reliable_emitter.py ← ACK-based send            (socket/reliable-emitter.ts)
+    socket/native_socket.py  ← connection loop             (socket/native-socket.ts)
+    inbound.py               ← inbound handler + media     (inbound.ts + media.ts)
+    outbound.py              ← send API                    (outbound.ts)
+    adapter.py               ← LightClawAdapter + singleton (gateway.ts)
+"""
+
+# Public API — kept stable so existing callers need no changes:
+#   gateway/platforms/__init__.py  → from .lightclaw import LightClawAdapter
+#   gateway/run.py                 → from gateway.platforms.lightclaw import LightClawAdapter, check_lightclaw_requirements
+#   tools/send_message_tool.py     → from gateway.platforms.lightclaw import get_active_adapter
+
+from .adapter import LightClawAdapter, get_active_adapter
+from .config import check_lightclaw_requirements
+
+__all__ = [
+    "LightClawAdapter",
+    "check_lightclaw_requirements",
+    "get_active_adapter",
+]