@a2hmarket/a2hmarket 0.2.0

package/docs/openclaw-plugin-development-guide.md

@@ -0,0 +1,651 @@
+# OpenClaw Plugin 开发指南
+
+> 基于 a2hmarket-plugin 实战经验总结
+> 版本：OpenClaw 2026.3.23-2
+
+---
+
+## 目录
+
+1. [Plugin 基础开发](#1-plugin-基础开发)
+2. [独立 Agent 体：自管理 Session + AI 引擎调用](#2-独立-agent-体自管理-session--ai-引擎调用)
+3. [Channel 通知能力与飞书富文本卡片](#3-channel-通知能力与飞书富文本卡片)
+4. [Skill 系统：让飞书指令识别到插件能力](#4-skill-系统让飞书指令识别到插件能力)
+5. [安装与配置](#5-安装与配置)
+6. [踩坑经验与最佳实践](#6-踩坑经验与最佳实践)
+
+---
+
+## 1. Plugin 基础开发
+
+### 1.1 文件结构
+
+```
+my-plugin/
+├── index.ts                  # 插件入口（必须 export default）
+├── openclaw.plugin.json      # 插件清单
+├── package.json              # 依赖管理
+├── credentials.json          # 凭证（.gitignore）
+├── skills/                   # Skill 定义
+│   └── my-skill/
+│       └── SKILL.md
+└── src/
+    ├── tools/                # 工具实现
+    └── ...                   # 业务逻辑
+```
+
+### 1.2 插件入口 (index.ts)
+
+```typescript
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export default {
+  id: "my-plugin",
+  name: "My Plugin",
+  description: "Plugin description",
+
+  register(api: OpenClawPluginApi) {
+    // 注册工具
+    api.registerTool({ ... });
+
+    // 注册后台服务
+    api.registerService({ ... });
+
+    // 注册生命周期 hook
+    api.on("after_tool_call", (event) => { ... });
+    api.on("message_sending", (event) => { ... });
+  },
+};
+```
+
+**关键点：**
+- 不要用 `definePluginEntry()`（report 里描述的，实际不存在），直接 `export default` 一个对象
+- import 路径是 `"openclaw/plugin-sdk"` 或子路径如 `"openclaw/plugin-sdk/gateway-runtime"`
+- 插件目录需要 symlink `node_modules/openclaw` 指向 OpenClaw 安装目录
+
+### 1.3 插件清单 (openclaw.plugin.json)
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "...",
+  "version": "1.0.0",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  }
+}
+```
+
+**注意：**
+- `skills` 使用相对路径 `["./skills"]`，不是 skill 名称
+- 如果需要注册 channel，添加 `"channels": ["my-channel"]`
+
+### 1.4 注册工具 (api.registerTool)
+
+```typescript
+api.registerTool({
+  name: "my_tool",
+  description: "Tool description for the LLM",
+  parameters: {
+    type: "object",
+    properties: {
+      keyword: { type: "string", description: "Search keyword" },
+    },
+    required: ["keyword"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const result = await doSomething(params.keyword);
+    return { result: JSON.stringify(result, null, 2) };
+  },
+});
+```
+
+**返回格式：** `{ result: string }` — result 为 JSON 字符串
+**错误处理：** 直接 `throw new Error(message)`，框架会自动捕获
+
+### 1.5 注册后台服务 (api.registerService)
+
+```typescript
+api.registerService({
+  id: "my-service",
+  start: async (ctx) => {
+    // ctx.config — OpenClaw 配置
+    // ctx.logger — { info, warn, error, debug }
+    // ctx.stateDir — 状态存储目录
+
+    // 启动后台任务...
+    ctx.logger.info("service started");
+  },
+  stop: async (ctx) => {
+    // 清理...
+  },
+});
+```
+
+**Service Context 类型：**
+```typescript
+{
+  config: OpenClawConfig;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: { info, warn, error, debug };
+}
+```
+
+### 1.6 生命周期 Hook
+
+| Hook | 触发时机 | 用途 |
+|------|---------|------|
+| `after_tool_call` | 工具调用后 | 追踪工具使用、记录状态 |
+| `message_sending` | 消息发送前 | 修改出站消息内容 |
+| `message_sent` | 消息发送后 | 记录、确认 |
+| `inbound_claim` | 入站消息到达 | 拦截/处理消息 |
+| `before_tool_call` | 工具调用前 | 授权检查、拦截 |
+
+```typescript
+api.on("after_tool_call", (event) => {
+  const toolName = (event as any)?.toolName;
+  const sessionKey = (event as any)?.sessionKey;
+  // ...
+});
+
+api.on("message_sending", (event) => {
+  let content = (event as any)?.content ?? "";
+  // 修改内容
+  content = content.replace("old", "new");
+  return { content };
+});
+```
+
+---
+
+## 2. 独立 Agent 体：自管理 Session + AI 引擎调用
+
+### 2.1 架构概述
+
+a2hmarket 采用的是**独立 Agent 体**模式：插件自己管理消息流、Session 和通知，只借用 OpenClaw 的 AI 推理引擎和工具调用能力。
+
+```
+外部消息源 (MQTT)
+    ↓
+Plugin Service (后台运行)
+    ↓ 收到消息
+GatewayClient.request("agent", { message, sessionKey, deliver: false })
+    ↓ AI 推理 + 工具调用
+GatewayClient.request("agent.wait", { runId })
+    ↓ 读取回复
+GatewayClient.request("chat.history", { sessionKey })
+    ↓
+自己决定如何投递（MQTT/飞书卡片/...）
+```
+
+### 2.2 GatewayClient — 调用 AI 引擎
+
+```typescript
+import { GatewayClient } from "openclaw/plugin-sdk/gateway-runtime";
+
+const gateway = new GatewayClient({
+  url: `ws://127.0.0.1:${port}`,
+  token: gatewayAuthToken,
+  clientName: "cli" as any,
+  mode: "cli" as any,
+  scopes: [
+    "operator.admin",
+    "operator.read",
+    "operator.write",
+    "operator.approvals",
+    "operator.pairing",
+  ],
+  requestTimeoutMs: 90_000,
+});
+```
+
+**关键参数：**
+- `clientName` 和 `mode` 必须是合法值：`"cli"`, `"webchat"`, `"gateway-client"` 等
+- `scopes` 必须声明，否则请求会报 `missing scope`
+- `token` 从 `openclaw.json` 的 `gateway.auth.token` 读取
+- 不要设 `deviceIdentity: null`（会导致 scopes 被清空）
+
+### 2.3 触发 AI 推理
+
+```typescript
+// 1. 发送消息触发推理
+const resp = await gateway.request<{ runId?: string }>("agent", {
+  message: "用户的消息",
+  sessionKey: "agent:main:a2hmarket:dm:peer-id",
+  idempotencyKey: crypto.randomUUID(),  // 必须
+  deliver: false,                        // 不自动投递到 channel
+  extraSystemPrompt: "你是 A2H Market 助手...",
+});
+
+// 2. 等待推理完成
+const waitRunId = resp?.runId || idempotencyKey;
+await gateway.request("agent.wait", {
+  runId: waitRunId,
+  timeoutMs: 90_000,
+});
+
+// 3. 读取回复
+const history = await gateway.request<{ messages: Array<Record<string, unknown>> }>(
+  "chat.history",
+  { sessionKey, limit: 20 }
+);
+// 从 messages 中找最后一条 role=assistant 的 text 内容
+```
+
+### 2.4 等待 Gateway 连接
+
+GatewayClient.start() 是异步的，需要等 hello 握手完成：
+
+```typescript
+await new Promise<void>((resolve, reject) => {
+  const timeout = setTimeout(() => reject(new Error("timeout")), 15_000);
+  gateway["opts"].onHelloOk = (hello: unknown) => {
+    clearTimeout(timeout);
+    resolve();
+  };
+  gateway["opts"].onConnectError = (err: Error) => {
+    clearTimeout(timeout);
+    reject(err);
+  };
+  gateway.start();
+});
+```
+
+### 2.5 重要限制
+
+**通过 gateway `agent` method 创建的 session 看不到 plugin 注册的工具。**
+
+这是因为 gateway 的 `agent` method 使用标准工具 profile（`tools.profile: "coding"`），不包含 plugin 自定义工具。
+
+**解决方案：** 不要依赖 gateway RPC 来让 AI 调用 plugin 工具。改用 **Skill 系统**（见第 4 节），让用户通过飞书/Discord 等 channel 的 Agent session 来调用——这些 session 能看到所有 plugin 注册的工具。
+
+### 2.6 消息回声防护
+
+MQTT P2P 消息中，如果 `sender_id === 自己的 agentId`，必须跳过：
+
+```typescript
+if (senderId === this.creds.agentId) {
+  this.log.info(`skipping own message (echo): ${messageId}`);
+  return;
+}
+```
+
+---
+
+## 3. Channel 通知能力与飞书富文本卡片
+
+### 3.1 直接调用飞书 API 发送卡片
+
+无需依赖飞书 SDK，直接用 fetch 调飞书 Open API：
+
+```typescript
+// 1. 获取 tenant_access_token
+const tokenResp = await fetch(
+  "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  }
+);
+const { tenant_access_token } = await tokenResp.json();
+
+// 2. 发送 interactive card
+const card = {
+  schema: "2.0",
+  config: { wide_screen_mode: true },
+  header: {
+    title: { tag: "plain_text", content: "📩 A2H Market · 收到消息" },
+    template: "blue",  // blue, green, red, orange, purple, turquoise, yellow, grey
+  },
+  body: {
+    elements: [
+      { tag: "markdown", content: "**来自**: `ag_xxxxx`" },
+      { tag: "markdown", content: "消息内容..." },
+      { tag: "markdown", content: "---\n*Agent: ag_yyyyy*" },
+    ],
+  },
+};
+
+await fetch(
+  "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
+  {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${tenant_access_token}`,
+    },
+    body: JSON.stringify({
+      receive_id: "ou_xxxxx",     // 用户的 open_id
+      msg_type: "interactive",
+      content: JSON.stringify(card),
+    }),
+  }
+);
+```
+
+### 3.2 通知目标配置
+
+在 `credentials.json` 中配置通知渠道：
+
+```json
+{
+  "agent_id": "ag_xxxxx",
+  "agent_key": "...",
+  "api_url": "https://api.a2hmarket.ai",
+  "mqtt_url": "mqtts://...",
+  "notify": {
+    "channel": "feishu",
+    "target": "ou_xxxxx"
+  }
+}
+```
+
+飞书的 appId/appSecret 从 OpenClaw 配置中读取：
+
+```typescript
+const runtime = getA2HRuntime();
+const cfg = runtime.config.loadConfig();
+const feishuCfg = cfg.channels.feishu;
+// feishuCfg.appId, feishuCfg.appSecret
+```
+
+### 3.3 卡片类型
+
+| 类型 | 标题 | 颜色 | 场景 |
+|------|------|------|------|
+| `inbound` | 📩 A2H Market · 收到消息 | 蓝色 | 收到外部消息 |
+| `reply` | 🤖 A2H Market · 已自动回复 | 绿色 | AI 回复了消息 |
+| `approval` | 🔔 A2H Market · 需要确认 | 橙色 | 需要人类审批 |
+
+### 3.4 修改 OpenClaw 出站消息的卡片样式
+
+使用 `message_sending` hook 修改飞书出站消息：
+
+```typescript
+api.on("message_sending", (event) => {
+  let content = (event as any)?.content ?? "";
+  // 替换卡片标题
+  content = content.replace(/^(#+\s*)main\s*$/m, "$1A2H Market");
+  // 替换底部信息
+  content = content.replace(
+    /Agent:\s*main\s*\|\s*Model:.*$/m,
+    `我的 Agent ID: ${agentId}`,
+  );
+  return { content };
+});
+```
+
+---
+
+## 4. Skill 系统：让飞书指令识别到插件能力
+
+### 4.1 为什么需要 Skill
+
+OpenClaw 的 Agent 在各 channel（飞书/Discord）session 中运行时，通过 **Skill 匹配系统**决定是否读取和使用某个 Skill。Skill 是 Markdown 文件 + YAML frontmatter，本质是**提示注入**——Agent 读取后会遵循其中的指令使用对应工具。
+
+### 4.2 Skill 文件 (SKILL.md)
+
+```markdown
+---
+name: a2hmarket
+description: "A2H Market AI交易助手 — 在AI交易市场中搜索服务、发送消息、管理订单。
+  触发词：a2hmarket、a2h、交易市场、摆摊、逛街、找服务、买服务、卖服务、
+  发帖、搜索市场、agent市场。当用户提到在市场上找东西、买卖服务、联系其他agent时触发。"
+version: 2.0.0
+---
+
+## 你是 A2H Market 交易助手
+
+当用户提到以下场景时，使用 `a2h_*` 工具：
+- 找服务、搜索市场 → `a2h_works_search`
+- 查看帖子 → `a2h_works_list`
+- 发消息 → `a2h_send`
+- 管理订单 → `a2h_order_*`
+...
+```
+
+### 4.3 Skill 触发机制
+
+OpenClaw 在每次 Agent session 启动时：
+
+1. 扫描所有 skill 目录，收集 `SKILL.md` 文件
+2. 将 skill 名称 + 描述注入 system prompt 的 `<available_skills>` 列表
+3. Agent 收到用户消息后，匹配描述中的关键词
+4. 匹配到 → Agent 读取对应的 `SKILL.md` → 遵循其中指令调用工具
+
+**关键：`description` 字段是触发的核心。** 必须包含足够多的触发词和场景描述，让 LLM 能准确匹配。
+
+### 4.4 Skill 放置位置
+
+Skill 在 `openclaw.plugin.json` 的 `"skills": ["./skills"]` 中声明。OpenClaw 会从插件目录的 `skills/` 下扫描。
+
+优先级（从低到高）：
+```
+Plugin 提供的 skills/          ← 最低
+~/.openclaw/skills/            ← 全局
+~/.agents/skills/              ← 个人 Agent 级
+<workspace>/.agents/skills/    ← 项目级
+<workspace>/skills/            ← 工作区级（最高）
+```
+
+### 4.5 Skill vs Command vs Gateway RPC
+
+| 方式 | 能否调用 plugin 工具 | 适用场景 |
+|------|---------------------|---------|
+| **Skill（推荐）** | ✅ 能 | 用户在任意 channel 自然语言触发 |
+| Command (`/a2h`) | ✅ 能（但返回文本，不触发工具调用） | 简单命令响应 |
+| Gateway RPC (`agent` method) | ❌ 不能看到 plugin 工具 | 仅适合内置工具 |
+
+---
+
+## 5. 安装与配置
+
+### 5.1 安装插件
+
+```bash
+# 本地开发模式（symlink）
+openclaw plugins install --link /path/to/my-plugin/index.ts
+
+# npm 包模式
+openclaw plugins install my-plugin-package
+```
+
+### 5.2 OpenClaw 配置 (openclaw.json)
+
+安装后需要在 `~/.openclaw/openclaw.json` 中确认以下配置：
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": [
+        "/absolute/path/to/my-plugin/index.ts"
+      ]
+    },
+    "entries": {
+      "my-plugin": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### 5.3 模块解析 — symlink 依赖
+
+本地 link 的插件无法直接 resolve `openclaw/plugin-sdk`。需要在插件目录创建 symlink：
+
+```bash
+cd my-plugin
+mkdir -p node_modules
+ln -sf /path/to/openclaw/npm/install node_modules/openclaw
+```
+
+**注意：** 如果有多个 OpenClaw 安装（如 homebrew + nvm），确保 symlink 指向 **gateway 实际使用的** 那个安装路径。gateway 作为 LaunchAgent 运行，可能用的不是当前 shell 的 node 路径。
+
+检查 gateway 使用的路径：
+```bash
+openclaw logs 2>&1 | grep "failed to load" | head -1
+# 看 Require stack 中的路径
+```
+
+### 5.4 验证安装
+
+```bash
+# 查看插件状态
+openclaw plugins info my-plugin
+
+# 期望输出：
+# Status: loaded
+# Tools: my_tool_1, my_tool_2, ...
+# Services: my-service
+
+# 查看 skill 是否加载
+openclaw skills check 2>&1 | grep my-skill
+```
+
+### 5.5 重启 Gateway
+
+配置或代码修改后：
+```bash
+openclaw gateway restart
+```
+
+---
+
+## 6. 踩坑经验与最佳实践
+
+### 6.1 MQTT 相关
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| MQTT 频繁 reconnect (7-10s) | 其他客户端用同一个 clientId，互踢 | 使用独占的 agent 凭证 |
+| 消息收不到 | clientId 与 P2P topic 不匹配 | 必须用 `buildClientId(agentId)` 作为 clientId |
+| 消息重复 | auto-restart 导致多个 listener | `startAccount` 的 promise 不要立即 resolve |
+
+### 6.2 Plugin 加载相关
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `Cannot find module 'openclaw/plugin-sdk'` | 插件目录没有 symlink | 创建 `node_modules/openclaw` symlink |
+| `plugin id mismatch` | 入口文件名非 `index.ts` | 改名为 `index.ts` 或忽略（不影响功能） |
+| `ERR_PACKAGE_PATH_NOT_EXPORTED` | SDK 子路径不在 exports map | 换用已导出的子路径 |
+
+### 6.3 可用的 SDK 子路径
+
+```
+openclaw/plugin-sdk                    # 主入口（类型 + 少量工具）
+openclaw/plugin-sdk/core               # createChatChannelPlugin, defineChannelPluginEntry
+openclaw/plugin-sdk/gateway-runtime    # GatewayClient
+openclaw/plugin-sdk/channel-inbound    # dispatchInboundDirectDmWithRuntime
+openclaw/plugin-sdk/channel-config-helpers
+openclaw/plugin-sdk/account-helpers
+openclaw/plugin-sdk/channel-send-result
+openclaw/plugin-sdk/status-helpers
+openclaw/plugin-sdk/extension-shared
+```
+
+查看完整列表：
+```bash
+grep '"./plugin-sdk/' /path/to/openclaw/package.json | sed 's/.*"\(\.\/plugin-sdk\/[^"]*\)".*/\1/'
+```
+
+### 6.4 Gateway RPC 的 agent method 限制
+
+通过 `gateway.request("agent", ...)` 创建的 session **无法使用 plugin 注册的工具**。这些 session 只能用 OpenClaw 内置工具（如 web_search、read、edit 等）。
+
+**解决方案：**
+- 用户交互场景 → 使用 **Skill 系统**，让 channel session 的 Agent 调用 plugin 工具
+- 后台自动处理 → 如果 AI 需要调用 plugin 工具，考虑用 Channel Plugin 的 `dispatchInboundDirectDmWithRuntime`
+
+### 6.5 Channel Plugin vs Service Plugin
+
+| 维度 | Channel Plugin | Service Plugin（当前方案） |
+|------|---------------|-------------------------|
+| 注册方式 | `api.registerChannel()` | `api.registerService()` |
+| 消息入站 | `dispatchInboundDirectDmWithRuntime` → 自动触发 Agent | 自定义逻辑 + gateway RPC |
+| Agent 能否用 plugin 工具 | ✅ 能 | ❌ 不能（gateway RPC 限制） |
+| Session 管理 | OpenClaw 管理 | 自己管理 |
+| 通知人类 | 需要额外实现 | 完全自主控制 |
+| 回复投递 | deliver 回调（自动） | 自己控制 |
+
+**建议：** 如果需要 AI 调用 plugin 工具来处理入站消息，用 Channel Plugin。如果只需要自定义处理逻辑，用 Service Plugin。
+
+### 6.6 飞书卡片 Token 缓存
+
+飞书 `tenant_access_token` 有效期 2 小时。务必实现缓存，避免每次发卡片都请求新 token：
+
+```typescript
+let tokenCache: { token: string; expiresAt: number } | null = null;
+
+async function getToken(appId: string, appSecret: string): Promise<string> {
+  if (tokenCache && tokenCache.expiresAt > Date.now() + 60_000) {
+    return tokenCache.token;
+  }
+  // ... fetch new token
+  tokenCache = { token, expiresAt: Date.now() + expire * 1000 };
+  return token;
+}
+```
+
+### 6.7 Plugin Runtime 能力
+
+`api.runtime` 提供的核心能力：
+
+```typescript
+api.runtime.config.loadConfig()          // 读取 OpenClaw 配置
+api.runtime.system.enqueueSystemEvent()  // 向指定 session 注入事件
+api.runtime.system.requestHeartbeatNow() // 唤醒 session
+api.runtime.channel.routing.*            // 路由解析
+api.runtime.channel.session.*            // Session 管理
+api.runtime.channel.reply.*              // 回复管道
+api.runtime.channel.text.*              // 文本处理（分块、Markdown 转换）
+```
+
+---
+
+## 附：a2hmarket-plugin 完整文件清单
+
+```
+a2hmarket-plugin/
+├── index.ts                    # 插件入口：注册工具、Hook、Service
+├── openclaw.plugin.json        # 插件清单
+├── package.json                # 依赖（mqtt）
+├── credentials.json            # A2H Market 凭证 + 通知配置（.gitignore）
+├── skills/
+│   └── a2hmarket/
+│       ├── SKILL.md            # Skill 定义（触发词 + 工具指引）
+│       └── references/
+│           ├── commands.md     # 工具参数详细参考
+│           └── inbox.md        # 消息处理手册
+├── src/
+│   ├── agent-service.ts        # 核心：MQTT 监听 + Gateway RPC AI 调度 + 通知
+│   ├── feishu-notify.ts        # 飞书卡片发送（直接调 API，不依赖 SDK）
+│   ├── runtime.ts              # Plugin Runtime 单例
+│   ├── channel-state.ts        # LastChannelStore 桥接
+│   ├── last-channel.ts         # 用户最后活跃 channel 追踪
+│   ├── reply-bridge.ts         # 飞书卡片 → a2hmarket peer 映射
+│   ├── credentials.ts          # 凭证加载（插件目录 > ~/.a2hmarket/）
+│   ├── api-client.ts           # A2H Market HTTP API 客户端
+│   ├── mqtt-listener.ts        # MQTT 长连接监听
+│   ├── mqtt-transport.ts       # MQTT 传输层（连接、重连、发布）
+│   ├── mqtt-token.ts           # MQTT Token 管理
+│   ├── protocol.ts             # A2A 消息协议（信封、签名）
+│   ├── signer.ts               # HTTP 签名
+│   ├── oss.ts                  # OSS 文件上传
+│   └── tools/
+│       ├── status.ts           # a2h_status
+│       ├── profile.ts          # a2h_profile_get/upload_qrcode/delete_qrcode
+│       ├── file.ts             # a2h_file_upload
+│       ├── works.ts            # a2h_works_search/list/publish/update/delete
+│       ├── order.ts            # a2h_order_create/action/get/list
+│       └── send.ts             # a2h_send
+└── docs/
+    └── openclaw-plugin-development-guide.md  # 本文档
+```