fangyuanjian 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# fyj Extension
+
+`@openclaw/fyj` is a template extension to connect your own IM system to OpenClaw.
+
+## What To Replace For Your IM
+
+The two key integration points are:
+
+1. `src/send.ts`
+- Replace the outbound `fetch` URL, headers, and JSON body with your IM send-message API.
+
+2. `src/monitor.ts`
+- Replace websocket subscription URL, subscribe payload, and inbound payload mapping with your IM protocol.
+
+## 中文说明
+
+你需要重点替换两处与真实 IM 协议绑定的实现：
+
+1. `src/send.ts`
+- 把出站 `fetch` 的 URL、鉴权头、请求体字段改成你们 IM 的发送接口。
+
+2. `src/monitor.ts`
+- 把 websocket 连接地址、订阅请求体、入站消息字段映射改成你们 IM 的协议。
+
+## Example Config
+
+See `examples/config.example.jsonc`.
+
+Main fields:
+- `channels.fyj.baseUrl`: your IM HTTP API base URL
+- `channels.fyj.sendPath`: send endpoint path
+- `channels.fyj.botToken`: outbound + websocket auth token
+- `channels.fyj.wsUrl`: websocket subscription URL (preferred)
+- `channels.fyj.wsPath`: fallback path if wsUrl is not set
+- `channels.fyj.wsSubscribePayload`: initial subscribe message body
+- `channels.fyj.wsHeartbeatIntervalSec`: websocket heartbeat interval (seconds)
+
+## 示例配置字段（中文）
+
+主要字段含义：
+- `channels.fyj.baseUrl`：你们 IM 的 HTTP API 基础地址
+- `channels.fyj.sendPath`：发送接口路径
+- `channels.fyj.botToken`：出站 + websocket 鉴权 token
+- `channels.fyj.wsUrl`：websocket 订阅地址（优先使用）
+- `channels.fyj.wsPath`：未配置 wsUrl 时，使用 baseUrl + wsPath 推导
+- `channels.fyj.wsSubscribePayload`：建连后发送的订阅请求体
+- `channels.fyj.wsHeartbeatIntervalSec`：websocket 心跳间隔（秒）
+
+## Example Inbound Payload
+
+See `examples/inbound-payload.example.json`.
+
+Expected shape in this template:
+
+```json
+{
+  "messageId": "msg_123",
+  "conversationId": "conv_abc",
+  "chatType": "direct",
+  "senderId": "u_1001",
+  "senderName": "Alice",
+  "text": "hello",
+  "timestamp": 1742100000000
+}
+```
+
+## Example Outbound Request
+
+See `examples/outbound-request.example.json`.
+
+This template currently sends:
+- `Authorization: Bearer <botToken>`
+- body with `conversationId`, `text`, `replyToMessageId`, `mediaUrl`
+
+Update those fields to match your IM API.
+
+## 示例出站（中文）
+
+模板默认会发送：
+- `Authorization: Bearer <botToken>`
+- body 字段：`conversationId`、`text`、`replyToMessageId`、`mediaUrl`
+
+接入你们 IM 时，请按真实接口协议替换字段名。
+
+## File Logic Map
+
+- `index.ts`: plugin register entry, injects runtime, registers channel plugin.
+- `setup-entry.ts`: setup runtime entry export.
+- `src/channel.setup.ts`: setup plugin alias.
+- `src/runtime.ts`: plugin runtime store getter/setter.
+- `src/types.ts`: shared type contracts for config/account/websocket/send.
+- `src/config-schema.ts`: zod schema + dmPolicy/open validation.
+- `src/accounts.ts`: account merge + token source resolution + websocket URL resolution.
+- `src/normalize.ts`: target normalization and id detection.
+- `src/send.ts`: outbound HTTP sender mapping to your IM API.
+- `src/monitor.ts`: websocket connect/subscribe/heartbeat/reconnect/payload parse.
+- `src/inbound.ts`: policy checks, session routing, reply dispatch and outbound callback.
+- `src/channel.ts`: ChannelPlugin orchestration (config/security/outbound/status/gateway).
+- `examples/config.example.jsonc`: sample channel config.
+- `examples/inbound-payload.example.json`: sample inbound payload shape.
+- `examples/outbound-request.example.json`: sample outbound API payload.
+- `openclaw.plugin.json`: plugin manifest metadata.
+- `package.json`: extension package metadata and OpenClaw extension declaration.
+
+## 文件实现逻辑总览（中文）
+
+- `index.ts`：插件注册入口，保存 runtime 并注册 fyj 渠道。
+- `setup-entry.ts`：setup 模式入口导出。
+- `src/channel.setup.ts`：setup 插件别名。
+- `src/runtime.ts`：插件 runtime 存取器。
+- `src/types.ts`：配置、账号、websocket、发送结果等类型定义。
+- `src/config-schema.ts`：fyj 配置校验与策略联动校验。
+- `src/accounts.ts`：账号配置合并、botToken 来源解析与 websocket URL 推导。
+- `src/normalize.ts`：目标地址规范化与识别。
+- `src/send.ts`：出站发送 HTTP 映射到你们 IM 接口。
+- `src/monitor.ts`：websocket 建连、订阅、心跳、重连与入站分发。
+- `src/inbound.ts`：权限门禁、会话路由、回复调度与回发。
+- `src/channel.ts`：渠道能力、配置、安全、状态、gateway 生命周期总编排。
+- `examples/config.example.jsonc`：配置示例模板。
+- `examples/inbound-payload.example.json`：入站 payload 示例。
+- `examples/outbound-request.example.json`：出站请求示例。
+- `openclaw.plugin.json`：插件清单元信息。
+- `package.json`：扩展包元信息与 OpenClaw 扩展声明。
+
+Note: `*.json` files do not support comments in strict JSON syntax. Their implementation logic is documented here.
+
+<!-- 文件实现逻辑：
+1) 说明如何把模板映射替换为真实 IM 协议。
+2) 提供逐文件职责总览，方便后续维护。
+3) 为无法写注释的 JSON 文件集中提供逻辑说明。
+-->
+
+
+## Local End-to-End (With bot-event-service)
+
+1. Start Java service in `C:\Users\CFG\Desktop\fyj\bot-event-service`.
+2. Use `examples/config.example.jsonc` for fyj channel config.
+3. Call `POST /api/fyj/events/publish` to push inbound messages.
+4. Verify OpenClaw receives and processes fyj inbound events.