ErisPulse-WebhookAdapter 4.0.0__tar.gz

erispulse_webhookadapter-4.0.0/ErisPulse_WebhookAdapter.egg-info/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ErisPulse-WebhookAdapter
+Version: 4.0.0
+Summary: ErisPulse的Webhook通用桥接适配模块
+Author: ErisPulse
+License: MIT
+Project-URL: homepage, https://github.com/ErisPulse/ErisPulse-WebhookAdapter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ErisPulse-WebhookAdapter
+
+ErisPulse 的 **Webhook 通用桥接适配器**（低代码万能桥）。它是一个双向桥接适配器：把任意外部系统的消息通过 HTTP 接入 ErisPulse，同时把 ErisPulse 模块发出的消息通过 HTTP 转发给任意目标系统。
+
+## 适配器定位
+
+每个「账户」即一个独立的 **webhook 桥接配置**：
+
+| 方向 | 说明 |
+|------|------|
+| **入站（外部 → ErisPulse）** | 外部系统通过 HTTP POST 把事件发到适配器注册的 webhook 路由，适配器转换为 OneBot12 标准事件并分发 |
+| **出站（ErisPulse → 外部）** | 模块调用 `adapter.Send.To(...).Text(...)` 时，适配器把消息 POST 到账户配置的 `outgoing_url`（即"用户订阅 webhook 到其他系统，提供发送 api"） |
+
+一个账户 = 一个入站路径 + 一个出站 URL + 一个鉴权密钥。
+
+## 安装
+
+```bash
+epsdk install WebhookAdapter
+```
+
+## 配置
+
+配置位于 `config.toml` 的 `[WebhookAdapter]` 段，或通过Dashboard的`适配器配置进行配置`：
+
+```toml
+[WebhookAdapter.accounts.default]
+bot_id = "webhook_bot"
+callback_path = "/webhook/default"
+outgoing_url = "https://example.com/api/receive"   # 模块发消息会 POST 到这里
+secret = "my-secret-key"                            # 鉴权密钥（留空则不校验）
+detail_type = "private"                             # 默认会话类型
+enabled = true
+
+# 可以配置多个桥接账户
+[WebhookAdapter.accounts.discord_bridge]
+bot_id = "discord_bot_123"
+callback_path = "/webhook/discord"
+outgoing_url = "https://my-discord-relay.example.com/send"
+secret = "another-secret"
+detail_type = "group"
+enabled = true
+```
+
+### 字段说明
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `bot_id` | `webhook_bot` | 该桥接代表的机器人身份 ID（写入事件的 `self.user_id`） |
+| `callback_path` | `/webhook/{account}` | 入站路径，支持 `{account}` 占位符（自动替换为账户名） |
+| `outgoing_url` | `""` | 出站目标 URL，留空则仅入站不发送 |
+| `secret` | `""` | 鉴权密钥，留空则不校验入站请求 |
+| `detail_type` | `private` | 默认会话类型，入站 body 未指定 `detail_type` 时使用 |
+
+## 入站协议（外部 → ErisPulse）
+
+### HTTP 请求
+
+外部系统 POST 到 `{callback_path}/{account}`，body 为 JSON：
+
+```json
+{
+  "user_id": "xxx",
+  "user_nickname": "用户名",
+  "group_id": "可选，群组/频道ID",
+  "detail_type": "private 或 group",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "raw": {}
+}
+```
+
+- `detail_type` 未提供时使用账户配置的默认值
+- `group_id` 仅在群组会话时提供
+- `message` 为 OneBot12 标准消息段数组
+- `raw` 可选，原样存入 `webhook_raw.raw`
+
+### 鉴权
+
+如果账户配置了 `secret`，入站请求需携带密钥（二选一）：
+
+- Header：`X-Webhook-Secret: {secret}`
+- Query：`?secret={secret}`
+
+`secret` 留空时不校验。
+
+### 健康检查（GET）
+
+收到 GET 请求时返回 `{"status":"ok","account":"账户名"}`，可用于健康检查。
+
+### 入站示例
+
+```bash
+curl -X POST http://localhost:8000/webhook/default \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Secret: my-secret-key" \
+  -d '{
+    "user_id": "u123",
+    "user_nickname": "测试用户",
+    "detail_type": "private",
+    "message": [{"type": "text", "data": {"text": "你好"}}]
+  }'
+```
+
+响应：
+
+```json
+{"status": "ok"}
+```
+
+### 转换后的 OneBot12 事件
+
+```json
+{
+  "id": "自动生成",
+  "time": 1700000000,
+  "type": "message",
+  "detail_type": "private",
+  "platform": "webhook",
+  "self": {"platform": "webhook", "user_id": "webhook_bot"},
+  "user_id": "u123",
+  "user_nickname": "测试用户",
+  "message": [{"type": "text", "data": {"text": "你好"}}],
+  "webhook_raw": {},
+  "webhook_account": "default",
+  "webhook_raw_type": "message"
+}
+```
+
+## 出站协议（ErisPulse → 外部）
+
+模块调用 `Send` 时，适配器把消息 POST 到账户的 `outgoing_url`：
+
+```json
+{
+  "target_type": "private|group|user",
+  "target_id": "xxx",
+  "account": "账户名",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "timestamp": 1234567890
+}
+```
+
+请求头（若配置了 `secret`）：
+
+```
+X-Webhook-Secret: {secret}
+```
+
+适配器会把出站目标返回的响应标准化为标准响应格式：从响应 JSON 中提取 `message_id` 字段。
+
+### 发送示例
+
+```python
+from ErisPulse import sdk
+
+# 发送文本（使用默认账户）
+await sdk.adapter.webhook.Send.To("user", "target_user_id").Text("你好")
+
+# 指定账户发送
+await sdk.adapter.webhook.Send.To("group", "group_123").Using("discord_bridge").Text("群消息")
+
+# 原始 JSON 透传
+await sdk.adapter.webhook.Send.To("user", "u1").Json({"custom": "data"})
+
+# OneBot12 原始消息段
+await sdk.adapter.webhook.Send.To("user", "u1").Raw_ob12([
+    {"type": "text", "data": {"text": "hello"}}
+])
+```
+
+## 使用场景
+
+### 场景一：接入自有系统
+
+你的业务系统通过 webhook 把用户消息推给 ErisPulse 处理，处理后再回传：
+
+1. 配置一个账户，`callback_path` 指向你的入站路径，`outgoing_url` 指向你的接收 API
+2. 业务系统把用户消息 POST 到 `callback_path`
+3. ErisPulse 模块处理后，回复消息会 POST 到 `outgoing_url`
+
+### 场景二：桥接非原生支持的平台
+
+通过中间转发脚本，把其他平台（如自建 IM、企业内部系统）接入 ErisPulse，无需开发完整适配器。
+
+### 场景三：Webhook 中继
+
+作为消息中继，把多个 webhook 源汇聚到 ErisPulse 统一处理，再分发给多个目标。
+
+## 文档
+
+- [平台特性说明](platform-features.md) — 入站/出站协议详解与字段映射
+
+## 许可证
+
+MIT

erispulse_webhookadapter-4.0.0/ErisPulse_WebhookAdapter.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+ErisPulse_WebhookAdapter.egg-info/PKG-INFO
+ErisPulse_WebhookAdapter.egg-info/SOURCES.txt
+ErisPulse_WebhookAdapter.egg-info/dependency_links.txt
+ErisPulse_WebhookAdapter.egg-info/entry_points.txt
+ErisPulse_WebhookAdapter.egg-info/top_level.txt
+WebhookAdapter/Converter.py
+WebhookAdapter/Core.py
+WebhookAdapter/__init__.py

erispulse_webhookadapter-4.0.0/ErisPulse_WebhookAdapter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

erispulse_webhookadapter-4.0.0/ErisPulse_WebhookAdapter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[erispulse.adapter]
+webhook = WebhookAdapter:WebhookAdapter

erispulse_webhookadapter-4.0.0/ErisPulse_WebhookAdapter.egg-info/top_level.txt

@@ -0,0 +1 @@
+WebhookAdapter

erispulse_webhookadapter-4.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ErisPulse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erispulse_webhookadapter-4.0.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: ErisPulse-WebhookAdapter
+Version: 4.0.0
+Summary: ErisPulse的Webhook通用桥接适配模块
+Author: ErisPulse
+License: MIT
+Project-URL: homepage, https://github.com/ErisPulse/ErisPulse-WebhookAdapter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ErisPulse-WebhookAdapter
+
+ErisPulse 的 **Webhook 通用桥接适配器**（低代码万能桥）。它是一个双向桥接适配器：把任意外部系统的消息通过 HTTP 接入 ErisPulse，同时把 ErisPulse 模块发出的消息通过 HTTP 转发给任意目标系统。
+
+## 适配器定位
+
+每个「账户」即一个独立的 **webhook 桥接配置**：
+
+| 方向 | 说明 |
+|------|------|
+| **入站（外部 → ErisPulse）** | 外部系统通过 HTTP POST 把事件发到适配器注册的 webhook 路由，适配器转换为 OneBot12 标准事件并分发 |
+| **出站（ErisPulse → 外部）** | 模块调用 `adapter.Send.To(...).Text(...)` 时，适配器把消息 POST 到账户配置的 `outgoing_url`（即"用户订阅 webhook 到其他系统，提供发送 api"） |
+
+一个账户 = 一个入站路径 + 一个出站 URL + 一个鉴权密钥。
+
+## 安装
+
+```bash
+epsdk install WebhookAdapter
+```
+
+## 配置
+
+配置位于 `config.toml` 的 `[WebhookAdapter]` 段，或通过Dashboard的`适配器配置进行配置`：
+
+```toml
+[WebhookAdapter.accounts.default]
+bot_id = "webhook_bot"
+callback_path = "/webhook/default"
+outgoing_url = "https://example.com/api/receive"   # 模块发消息会 POST 到这里
+secret = "my-secret-key"                            # 鉴权密钥（留空则不校验）
+detail_type = "private"                             # 默认会话类型
+enabled = true
+
+# 可以配置多个桥接账户
+[WebhookAdapter.accounts.discord_bridge]
+bot_id = "discord_bot_123"
+callback_path = "/webhook/discord"
+outgoing_url = "https://my-discord-relay.example.com/send"
+secret = "another-secret"
+detail_type = "group"
+enabled = true
+```
+
+### 字段说明
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `bot_id` | `webhook_bot` | 该桥接代表的机器人身份 ID（写入事件的 `self.user_id`） |
+| `callback_path` | `/webhook/{account}` | 入站路径，支持 `{account}` 占位符（自动替换为账户名） |
+| `outgoing_url` | `""` | 出站目标 URL，留空则仅入站不发送 |
+| `secret` | `""` | 鉴权密钥，留空则不校验入站请求 |
+| `detail_type` | `private` | 默认会话类型，入站 body 未指定 `detail_type` 时使用 |
+
+## 入站协议（外部 → ErisPulse）
+
+### HTTP 请求
+
+外部系统 POST 到 `{callback_path}/{account}`，body 为 JSON：
+
+```json
+{
+  "user_id": "xxx",
+  "user_nickname": "用户名",
+  "group_id": "可选，群组/频道ID",
+  "detail_type": "private 或 group",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "raw": {}
+}
+```
+
+- `detail_type` 未提供时使用账户配置的默认值
+- `group_id` 仅在群组会话时提供
+- `message` 为 OneBot12 标准消息段数组
+- `raw` 可选，原样存入 `webhook_raw.raw`
+
+### 鉴权
+
+如果账户配置了 `secret`，入站请求需携带密钥（二选一）：
+
+- Header：`X-Webhook-Secret: {secret}`
+- Query：`?secret={secret}`
+
+`secret` 留空时不校验。
+
+### 健康检查（GET）
+
+收到 GET 请求时返回 `{"status":"ok","account":"账户名"}`，可用于健康检查。
+
+### 入站示例
+
+```bash
+curl -X POST http://localhost:8000/webhook/default \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Secret: my-secret-key" \
+  -d '{
+    "user_id": "u123",
+    "user_nickname": "测试用户",
+    "detail_type": "private",
+    "message": [{"type": "text", "data": {"text": "你好"}}]
+  }'
+```
+
+响应：
+
+```json
+{"status": "ok"}
+```
+
+### 转换后的 OneBot12 事件
+
+```json
+{
+  "id": "自动生成",
+  "time": 1700000000,
+  "type": "message",
+  "detail_type": "private",
+  "platform": "webhook",
+  "self": {"platform": "webhook", "user_id": "webhook_bot"},
+  "user_id": "u123",
+  "user_nickname": "测试用户",
+  "message": [{"type": "text", "data": {"text": "你好"}}],
+  "webhook_raw": {},
+  "webhook_account": "default",
+  "webhook_raw_type": "message"
+}
+```
+
+## 出站协议（ErisPulse → 外部）
+
+模块调用 `Send` 时，适配器把消息 POST 到账户的 `outgoing_url`：
+
+```json
+{
+  "target_type": "private|group|user",
+  "target_id": "xxx",
+  "account": "账户名",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "timestamp": 1234567890
+}
+```
+
+请求头（若配置了 `secret`）：
+
+```
+X-Webhook-Secret: {secret}
+```
+
+适配器会把出站目标返回的响应标准化为标准响应格式：从响应 JSON 中提取 `message_id` 字段。
+
+### 发送示例
+
+```python
+from ErisPulse import sdk
+
+# 发送文本（使用默认账户）
+await sdk.adapter.webhook.Send.To("user", "target_user_id").Text("你好")
+
+# 指定账户发送
+await sdk.adapter.webhook.Send.To("group", "group_123").Using("discord_bridge").Text("群消息")
+
+# 原始 JSON 透传
+await sdk.adapter.webhook.Send.To("user", "u1").Json({"custom": "data"})
+
+# OneBot12 原始消息段
+await sdk.adapter.webhook.Send.To("user", "u1").Raw_ob12([
+    {"type": "text", "data": {"text": "hello"}}
+])
+```
+
+## 使用场景
+
+### 场景一：接入自有系统
+
+你的业务系统通过 webhook 把用户消息推给 ErisPulse 处理，处理后再回传：
+
+1. 配置一个账户，`callback_path` 指向你的入站路径，`outgoing_url` 指向你的接收 API
+2. 业务系统把用户消息 POST 到 `callback_path`
+3. ErisPulse 模块处理后，回复消息会 POST 到 `outgoing_url`
+
+### 场景二：桥接非原生支持的平台
+
+通过中间转发脚本，把其他平台（如自建 IM、企业内部系统）接入 ErisPulse，无需开发完整适配器。
+
+### 场景三：Webhook 中继
+
+作为消息中继，把多个 webhook 源汇聚到 ErisPulse 统一处理，再分发给多个目标。
+
+## 文档
+
+- [平台特性说明](platform-features.md) — 入站/出站协议详解与字段映射
+
+## 许可证
+
+MIT

erispulse_webhookadapter-4.0.0/README.md

@@ -0,0 +1,195 @@
+# ErisPulse-WebhookAdapter
+
+ErisPulse 的 **Webhook 通用桥接适配器**（低代码万能桥）。它是一个双向桥接适配器：把任意外部系统的消息通过 HTTP 接入 ErisPulse，同时把 ErisPulse 模块发出的消息通过 HTTP 转发给任意目标系统。
+
+## 适配器定位
+
+每个「账户」即一个独立的 **webhook 桥接配置**：
+
+| 方向 | 说明 |
+|------|------|
+| **入站（外部 → ErisPulse）** | 外部系统通过 HTTP POST 把事件发到适配器注册的 webhook 路由，适配器转换为 OneBot12 标准事件并分发 |
+| **出站（ErisPulse → 外部）** | 模块调用 `adapter.Send.To(...).Text(...)` 时，适配器把消息 POST 到账户配置的 `outgoing_url`（即"用户订阅 webhook 到其他系统，提供发送 api"） |
+
+一个账户 = 一个入站路径 + 一个出站 URL + 一个鉴权密钥。
+
+## 安装
+
+```bash
+epsdk install WebhookAdapter
+```
+
+## 配置
+
+配置位于 `config.toml` 的 `[WebhookAdapter]` 段，或通过Dashboard的`适配器配置进行配置`：
+
+```toml
+[WebhookAdapter.accounts.default]
+bot_id = "webhook_bot"
+callback_path = "/webhook/default"
+outgoing_url = "https://example.com/api/receive"   # 模块发消息会 POST 到这里
+secret = "my-secret-key"                            # 鉴权密钥（留空则不校验）
+detail_type = "private"                             # 默认会话类型
+enabled = true
+
+# 可以配置多个桥接账户
+[WebhookAdapter.accounts.discord_bridge]
+bot_id = "discord_bot_123"
+callback_path = "/webhook/discord"
+outgoing_url = "https://my-discord-relay.example.com/send"
+secret = "another-secret"
+detail_type = "group"
+enabled = true
+```
+
+### 字段说明
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `bot_id` | `webhook_bot` | 该桥接代表的机器人身份 ID（写入事件的 `self.user_id`） |
+| `callback_path` | `/webhook/{account}` | 入站路径，支持 `{account}` 占位符（自动替换为账户名） |
+| `outgoing_url` | `""` | 出站目标 URL，留空则仅入站不发送 |
+| `secret` | `""` | 鉴权密钥，留空则不校验入站请求 |
+| `detail_type` | `private` | 默认会话类型，入站 body 未指定 `detail_type` 时使用 |
+
+## 入站协议（外部 → ErisPulse）
+
+### HTTP 请求
+
+外部系统 POST 到 `{callback_path}/{account}`，body 为 JSON：
+
+```json
+{
+  "user_id": "xxx",
+  "user_nickname": "用户名",
+  "group_id": "可选，群组/频道ID",
+  "detail_type": "private 或 group",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "raw": {}
+}
+```
+
+- `detail_type` 未提供时使用账户配置的默认值
+- `group_id` 仅在群组会话时提供
+- `message` 为 OneBot12 标准消息段数组
+- `raw` 可选，原样存入 `webhook_raw.raw`
+
+### 鉴权
+
+如果账户配置了 `secret`，入站请求需携带密钥（二选一）：
+
+- Header：`X-Webhook-Secret: {secret}`
+- Query：`?secret={secret}`
+
+`secret` 留空时不校验。
+
+### 健康检查（GET）
+
+收到 GET 请求时返回 `{"status":"ok","account":"账户名"}`，可用于健康检查。
+
+### 入站示例
+
+```bash
+curl -X POST http://localhost:8000/webhook/default \
+  -H "Content-Type: application/json" \
+  -H "X-Webhook-Secret: my-secret-key" \
+  -d '{
+    "user_id": "u123",
+    "user_nickname": "测试用户",
+    "detail_type": "private",
+    "message": [{"type": "text", "data": {"text": "你好"}}]
+  }'
+```
+
+响应：
+
+```json
+{"status": "ok"}
+```
+
+### 转换后的 OneBot12 事件
+
+```json
+{
+  "id": "自动生成",
+  "time": 1700000000,
+  "type": "message",
+  "detail_type": "private",
+  "platform": "webhook",
+  "self": {"platform": "webhook", "user_id": "webhook_bot"},
+  "user_id": "u123",
+  "user_nickname": "测试用户",
+  "message": [{"type": "text", "data": {"text": "你好"}}],
+  "webhook_raw": {},
+  "webhook_account": "default",
+  "webhook_raw_type": "message"
+}
+```
+
+## 出站协议（ErisPulse → 外部）
+
+模块调用 `Send` 时，适配器把消息 POST 到账户的 `outgoing_url`：
+
+```json
+{
+  "target_type": "private|group|user",
+  "target_id": "xxx",
+  "account": "账户名",
+  "message": [{"type": "text", "data": {"text": "内容"}}],
+  "timestamp": 1234567890
+}
+```
+
+请求头（若配置了 `secret`）：
+
+```
+X-Webhook-Secret: {secret}
+```
+
+适配器会把出站目标返回的响应标准化为标准响应格式：从响应 JSON 中提取 `message_id` 字段。
+
+### 发送示例
+
+```python
+from ErisPulse import sdk
+
+# 发送文本（使用默认账户）
+await sdk.adapter.webhook.Send.To("user", "target_user_id").Text("你好")
+
+# 指定账户发送
+await sdk.adapter.webhook.Send.To("group", "group_123").Using("discord_bridge").Text("群消息")
+
+# 原始 JSON 透传
+await sdk.adapter.webhook.Send.To("user", "u1").Json({"custom": "data"})
+
+# OneBot12 原始消息段
+await sdk.adapter.webhook.Send.To("user", "u1").Raw_ob12([
+    {"type": "text", "data": {"text": "hello"}}
+])
+```
+
+## 使用场景
+
+### 场景一：接入自有系统
+
+你的业务系统通过 webhook 把用户消息推给 ErisPulse 处理，处理后再回传：
+
+1. 配置一个账户，`callback_path` 指向你的入站路径，`outgoing_url` 指向你的接收 API
+2. 业务系统把用户消息 POST 到 `callback_path`
+3. ErisPulse 模块处理后，回复消息会 POST 到 `outgoing_url`
+
+### 场景二：桥接非原生支持的平台
+
+通过中间转发脚本，把其他平台（如自建 IM、企业内部系统）接入 ErisPulse，无需开发完整适配器。
+
+### 场景三：Webhook 中继
+
+作为消息中继，把多个 webhook 源汇聚到 ErisPulse 统一处理，再分发给多个目标。
+
+## 文档
+
+- [平台特性说明](platform-features.md) — 入站/出站协议详解与字段映射
+
+## 许可证
+
+MIT

erispulse_webhookadapter-4.0.0/WebhookAdapter/Converter.py

@@ -0,0 +1,75 @@
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+
+class WebhookConverter:
+    """
+    Webhook 事件转换器
+
+    将外部系统通过 HTTP POST 提交的 JSON 转换为 OneBot12 标准事件。
+
+    核心原则：
+    1. 严格兼容：所有标准字段完全遵循 OneBot12 规范
+    2. 明确扩展：桥接特有信息使用 webhook_ 前缀
+    3. 数据完整：原始请求 body 完整保留在 webhook_raw 字段中
+    4. 时间统一：所有时间戳为 10 位 Unix 时间戳（秒级）
+    """
+
+    def __init__(self, bot_id: str = "webhook_bot"):
+        self.bot_id = bot_id
+
+    def convert(
+        self,
+        raw_body: Dict[str, Any],
+        account_name: str = "",
+        detail_type_default: str = "private",
+    ) -> Optional[Dict[str, Any]]:
+        """
+        将入站 JSON body 转换为 OneBot12 标准事件
+
+        :param raw_body: 外部系统 POST 的 JSON（已解析为 dict）
+        :param account_name: 所属账户名（写入 webhook_account）
+        :param detail_type_default: 账户默认会话类型（body 未指定时使用）
+        :return: OneBot12 标准事件 dict，无效输入返回 None
+        """
+        if not isinstance(raw_body, dict):
+            return None
+
+        detail_type = raw_body.get("detail_type") or detail_type_default or "private"
+        group_id = raw_body.get("group_id")
+
+        message: List[dict] = raw_body.get("message", [])
+        if not isinstance(message, list):
+            message = []
+
+        event: Dict[str, Any] = {
+            "id": str(uuid.uuid4().int)[:16],
+            "time": int(time.time()),
+            "type": "message",
+            "detail_type": detail_type,
+            "platform": "webhook",
+            "self": {
+                "platform": "webhook",
+                "user_id": self.bot_id,
+            },
+            "user_id": str(raw_body.get("user_id", "")),
+            "message": message,
+            "webhook_raw": raw_body,
+            "webhook_account": account_name,
+            "webhook_raw_type": raw_body.get("type", "message"),
+        }
+
+        user_nickname = raw_body.get("user_nickname")
+        if user_nickname:
+            event["user_nickname"] = str(user_nickname)
+
+        if group_id:
+            event["group_id"] = str(group_id)
+
+        # alt_message：若 body 显式提供则透传
+        alt_message = raw_body.get("alt_message")
+        if alt_message:
+            event["alt_message"] = str(alt_message)
+
+        return event

erispulse_webhookadapter-4.0.0/WebhookAdapter/Core.py

@@ -0,0 +1,395 @@
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from ErisPulse.Core import client, router
+from ErisPulse.Core.Bases.adapter import BaseAdapter
+from ErisPulse.Core.config import config as config_mgr
+from ErisPulse.Core.Event import register_event_mixin, unregister_platform_event_methods
+from ErisPulse.runtime.config_schema import BotAccountConfig, dict_to_dataclass
+
+from .Converter import WebhookConverter
+
+
+@dataclass
+class WebhookAccountConfig(BotAccountConfig):
+    """Webhook 桥接账户配置：一个账户 = 一个入站路径 + 一个出站 URL + 鉴权密钥"""
+
+    bot_id: str = field(
+        default="webhook_bot",
+        metadata={
+            "description": "该桥接代表的机器人身份ID",
+            "required": False,
+            "webui": {"widget": "text", "group": "basic", "order": 1},
+        },
+    )
+    callback_path: str = field(
+        default="/webhook/{account}",
+        metadata={
+            "description": "入站回调路径（支持 {account} 占位符）",
+            "required": False,
+            "webui": {"widget": "text", "group": "connection", "order": 2},
+        },
+    )
+    outgoing_url: str = field(
+        default="",
+        metadata={
+            "description": "出站目标 URL（订阅到其他系统，模块发送消息时 POST 到此地址）",
+            "required": False,
+            "webui": {"widget": "text", "group": "connection", "order": 3},
+        },
+    )
+    secret: str = field(
+        default="",
+        metadata={
+            "description": "鉴权密钥（留空则不校验）",
+            "required": False,
+            "secret": True,
+            "webui": {"widget": "password", "group": "basic", "order": 4},
+        },
+    )
+    detail_type: str = field(
+        default="private",
+        metadata={
+            "description": "默认会话类型（body 未指定 detail_type 时使用）",
+            "required": False,
+            "webui": {"widget": "text", "group": "basic", "order": 5},
+        },
+    )
+
+
+class WebhookEventMixin:
+    """Webhook 事件扩展方法"""
+
+    def get_raw_data(self) -> dict:
+        """获取原始请求 body"""
+        return self.get("webhook_raw", {}) or {}
+
+    def get_detail_type(self) -> str:
+        """获取会话类型（private/group 等）"""
+        return self.get("detail_type", "private")
+
+    def get_webhook_account(self) -> str:
+        """获取产生该事件的账户名"""
+        return self.get("webhook_account", "")
+
+
+register_event_mixin("webhook", WebhookEventMixin)
+
+
+class WebhookAdapter(BaseAdapter):
+    """
+    Webhook 通用桥接适配器
+
+    双向桥接：
+    - 入站：外部系统 POST 到 {callback_path}，转换为 OneBot12 事件分发
+    - 出站：模块 Send 时，POST 消息到账户的 outgoing_url
+    """
+
+    _platform = "webhook"
+    AccountConfigClass = WebhookAccountConfig
+
+    class Send(BaseAdapter.Send):
+        def Text(self, text: str):
+            return self.Raw_ob12([{"type": "text", "data": {"text": text}}])
+
+        def Image(self, file):
+            return self.Raw_ob12([{"type": "image", "data": {"file": file}}])
+
+        def Raw_ob12(self, message: list, **kwargs):
+            async def _do_send():
+                segments = self._apply_modifiers(message)
+                ctx = self.send_context
+                return await self._adapter.call_api(
+                    endpoint="send_message",
+                    _account_id=ctx.get("account_id"),
+                    target_type=ctx.get("target_type"),
+                    target_id=ctx.get("target_id"),
+                    message=segments,
+                    **kwargs,
+                )
+
+            return asyncio.create_task(_do_send())
+
+        def Json(self, data):
+            """
+            原始 JSON 透传：将任意 JSON 数据作为消息段发送
+            """
+            return self.Raw_ob12([{"type": "json", "data": {"raw": data}}])
+
+    def __init__(self, sdk_ref=None):
+        super().__init__(sdk_ref)
+        self._converters: Dict[str, WebhookConverter] = {}
+        self._running = False
+        self._registered_routes: List[str] = []
+
+    def _get_config_key(self) -> str:
+        return "WebhookAdapter"
+
+    def _load_accounts(self) -> dict:
+        key = "WebhookAdapter.accounts"
+        data = config_mgr.getConfig(key)
+
+        if not data:
+            old_config = config_mgr.getConfig("WebhookAdapter")
+            if old_config and (
+                "callback_path" in old_config or "outgoing_url" in old_config
+            ):
+                self.logger.warning("检测到旧格式配置，建议迁移到多账户格式")
+                self.logger.warning(
+                    "迁移方法：将现有配置移动到 WebhookAdapter.accounts.default 下"
+                )
+                data = {
+                    "default": {
+                        "bot_id": old_config.get("bot_id", "webhook_bot"),
+                        "callback_path": old_config.get(
+                            "callback_path", "/webhook/{account}"
+                        ),
+                        "outgoing_url": old_config.get("outgoing_url", ""),
+                        "secret": old_config.get("secret", ""),
+                        "detail_type": old_config.get("detail_type", "private"),
+                        "enabled": True,
+                    }
+                }
+                self.logger.warning(
+                    "已临时加载旧配置为默认账户，请尽快迁移到多账户格式"
+                )
+            else:
+                self.logger.info("未找到配置文件，创建默认桥接账户配置")
+                data = {
+                    "default": {
+                        "bot_id": "webhook_bot",
+                        "callback_path": "/webhook/{account}",
+                        "outgoing_url": "",
+                        "secret": "",
+                        "detail_type": "private",
+                        "enabled": True,
+                    }
+                }
+                try:
+                    config_mgr.setConfig(key, data)
+                except Exception as e:
+                    self.logger.error(f"保存默认桥接账户配置失败: {str(e)}")
+
+        accounts = {}
+        for name, account_data in data.items():
+            if not isinstance(account_data, dict):
+                continue
+
+            instance = dict_to_dataclass(WebhookAccountConfig, account_data)
+            instance.name = name
+            accounts[name] = instance
+
+        self.logger.info(f"Webhook适配器初始化完成，共加载 {len(accounts)} 个桥接账户")
+        return accounts
+
+    def _get_converter(self, account_name: str) -> WebhookConverter:
+        """获取指定账户的转换器（懒加载）"""
+        if account_name not in self._converters:
+            account = self.accounts.get(account_name)
+            bot_id = account.bot_id if account else "webhook_bot"
+            self._converters[account_name] = WebhookConverter(bot_id)
+        return self._converters[account_name]
+
+    def _resolve_callback_path(self, account_name: str, account) -> str:
+        """解析账户的实际回调路径，替换 {account} 占位符"""
+        path = account.callback_path or "/webhook/{account}"
+        return path.replace("{account}", account_name)
+
+    def _make_health_handler(self, account_name: str):
+        async def health_check(request):
+            return {"status": "ok", "account": account_name}
+
+        return health_check
+
+    def _make_webhook_handler(self, account_name: str):
+        async def webhook_receiver(request):
+            account = self.accounts.get(account_name)
+            if not account:
+                return self._json_error("未知账户", 404)
+
+            # 鉴权
+            if account.secret:
+                provided = (
+                    request.headers.get("X-Webhook-Secret")
+                    or request.query_params.get("secret")
+                    or ""
+                )
+                if provided != account.secret:
+                    self.logger.warning(f"账户 {account_name} webhook 鉴权失败")
+                    return self._json_error("鉴权失败", 401)
+
+            # 解析 body
+            try:
+                body = await request.json()
+            except Exception as e:
+                self.logger.warning(f"账户 {account_name} 收到无效JSON: {e}")
+                return self._json_error("无效的JSON body", 400)
+
+            if not isinstance(body, dict):
+                return self._json_error("body 必须是 JSON 对象", 400)
+
+            converter = self._get_converter(account_name)
+            event = converter.convert(
+                body,
+                account_name=account_name,
+                detail_type_default=account.detail_type,
+            )
+
+            if event:
+                try:
+                    from ErisPulse.Core import adapter as adapter_mgr
+
+                    await adapter_mgr.emit(event)
+                except Exception as e:
+                    self.logger.error(f"账户 {account_name} 分发事件失败: {e}")
+                    return self._json_error("事件分发失败", 500)
+
+            return {"status": "ok"}
+
+        return webhook_receiver
+
+    @staticmethod
+    def _json_error(message: str, status: int):
+        from fastapi.responses import JSONResponse
+
+        return JSONResponse(
+            status_code=status,
+            content={"status": "error", "message": message},
+        )
+
+    async def call_api(self, endpoint: str, _account_id: str = None, **params):
+        account_name, account = self._resolve_account(_account_id)
+
+        if endpoint in ("send_message", "send_msg"):
+            if not account:
+                return self.make_error(retcode=10002, message="无法解析账户")
+
+            if not account.outgoing_url:
+                self.logger.error(
+                    f"账户 {account_name} 未配置 outgoing_url，无法发送消息"
+                )
+                return self.make_error(
+                    retcode=10002,
+                    message="未配置 outgoing_url，无法发送出站消息",
+                )
+
+            target_type = params.get("target_type") or account.detail_type or "private"
+            target_id = params.get("target_id", "")
+            message = params.get("message", [])
+
+            payload = {
+                "target_type": target_type,
+                "target_id": target_id,
+                "account": account_name,
+                "message": message,
+                "timestamp": int(time.time()),
+            }
+
+            headers = {}
+            if account.secret:
+                headers["X-Webhook-Secret"] = account.secret
+
+            try:
+                self.logger.debug(
+                    f"Webhook出站: 账户={account_name} -> {account.outgoing_url}"
+                )
+                resp = await client.post(
+                    account.outgoing_url, json=payload, headers=headers
+                )
+                try:
+                    raw = await resp.json()
+                except Exception:
+                    raw = {}
+
+                message_id = ""
+                if isinstance(raw, dict):
+                    message_id = str(raw.get("message_id", ""))
+
+                return self.make_response(
+                    data=raw if isinstance(raw, dict) else None,
+                    message_id=message_id,
+                    raw=raw,
+                )
+            except Exception as e:
+                self.logger.error(f"Webhook出站请求失败({account_name}): {e}")
+                return self.make_error(
+                    retcode=33001,
+                    message=f"出站请求失败: {str(e)}",
+                    raw=None,
+                )
+
+        return self.make_error(
+            retcode=10002,
+            message=f"不支持的API端点: {endpoint}",
+        )
+
+    async def start(self):
+        self._running = True
+        self._registered_routes = []
+
+        if not self.enabled_accounts:
+            self.logger.warning("Webhook适配器没有已启用的账户")
+            return
+
+        for account_name, account in self.enabled_accounts.items():
+            path = self._resolve_callback_path(account_name, account)
+
+            health_handler = self._make_health_handler(account_name)
+            receive_handler = self._make_webhook_handler(account_name)
+
+            try:
+                router.register_http_route(
+                    "webhook", path, health_handler, methods=["GET"]
+                )
+                router.register_http_route(
+                    "webhook", path, receive_handler, methods=["POST"]
+                )
+            except Exception as e:
+                self.logger.error(f"账户 {account_name} 注册路由 {path} 失败: {e}")
+                continue
+
+            self._registered_routes.append(path)
+
+            try:
+                await self.emit_meta(
+                    "connect",
+                    account.bot_id,
+                    user_name="WebhookBot",
+                    nickname=f"Webhook({account_name})",
+                )
+            except Exception as e:
+                self.logger.warning(f"账户 {account_name} emit connect 失败: {e}")
+
+            outgoing = account.outgoing_url or "(未配置，仅入站)"
+            self.logger.info(
+                f"Webhook账户 {account_name} 已启动: GET/POST {path} | 出站 {outgoing}"
+            )
+
+        self.logger.info(
+            f"Webhook适配器启动完成，共 {len(self._registered_routes)} 个桥接账户"
+        )
+
+    async def shutdown(self):
+        self._running = False
+
+        for path in self._registered_routes:
+            try:
+                router.unregister_http_route("webhook", path)
+            except Exception as e:
+                self.logger.debug(f"注销路由 {path} 失败: {e}")
+        self._registered_routes.clear()
+
+        for account_name, account in self.enabled_accounts.items():
+            try:
+                await self.emit_meta("disconnect", account.bot_id)
+            except Exception:
+                pass
+
+        try:
+            unregister_platform_event_methods("webhook")
+        except Exception:
+            pass
+
+        self.logger.info("Webhook适配器已关闭")

erispulse_webhookadapter-4.0.0/WebhookAdapter/__init__.py

@@ -0,0 +1 @@
+from .Core import WebhookAdapter

erispulse_webhookadapter-4.0.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "ErisPulse-WebhookAdapter"
+version = "4.0.0"
+description = "ErisPulse的Webhook通用桥接适配模块"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [ { name = "ErisPulse" } ]
+dependencies = []
+
+[project.urls]
+"homepage" = "https://github.com/ErisPulse/ErisPulse-WebhookAdapter"
+
+[project.entry-points."erispulse.adapter"]
+webhook = "WebhookAdapter:WebhookAdapter"
+
+[tool.setuptools.packages.find]
+include = [ "WebhookAdapter" ]

erispulse_webhookadapter-4.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+