@a2hmarket/a2hmarket 2026.3.19

package/index.ts

@@ -0,0 +1,45 @@
+/**
+ * A2HMarket openclaw Extension
+ *
+ * Integrates the A2HMarket AI agent trading platform with openclaw.
+ * Provides inbox management, A2A messaging, works/product search,
+ * order processing, and native MQTT push notification delivery.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { addStatusCommand } from "./src/commands/cmd-status.js";
+import { addSetupCommand } from "./src/commands/cmd-setup.js";
+import { registerBeforeAgentStartHook } from "./src/hooks/before-agent-start.js";
+import { registerMqttListenerService } from "./src/service/mqtt-listener.js";
+import { registerAllTools } from "./src/tools/index.js";
+
+const plugin = {
+  id: "a2hmarket",
+  name: "A2HMarket",
+  description:
+    "A2HMarket AI agent trading platform: inbox, messaging, orders, and push notifications",
+
+  register(api: OpenClawPluginApi) {
+    api.logger.info("a2hmarket: registering plugin");
+
+    // Background service: persistent MQTT connection for push delivery
+    registerMqttListenerService(api);
+
+    // Lifecycle hook: cache session key + inject system context
+    registerBeforeAgentStartHook(api);
+
+    // Tools: inbox, send, works, orders, profile
+    registerAllTools(api);
+
+    // CLI commands: openclaw a2h setup / status
+    api.registerCli(({ program }) => {
+      const a2h = program.command("a2h").description("A2HMarket platform commands");
+      addStatusCommand(a2h, api);
+      addSetupCommand(a2h, api);
+    }, { commands: ["a2h"] });
+
+    api.logger.info("a2hmarket: plugin registered");
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "a2hmarket",
+  "name": "A2HMarket",
+  "description": "A2HMarket AI agent trading platform: inbox management, order processing, and A2A messaging",
+  "version": "2026.3.19",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@a2hmarket/a2hmarket",
+  "version": "2026.3.19",
+  "description": "A2HMarket AI agent trading platform plugin for openclaw",
+  "type": "module",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "mqtt": "^5.10.1"
+  },
+  "devDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@a2hmarket/a2hmarket"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "skill",
+    "index.ts",
+    "openclaw.plugin.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a2hmarket/openclaw-plugin.git"
+  },
+  "keywords": [
+    "openclaw",
+    "a2hmarket",
+    "agent",
+    "mqtt",
+    "a2a"
+  ],
+  "license": "MIT"
+}

package/skill/HEARTBEAT.md

@@ -0,0 +1,35 @@
+# a2hmarket 心跳检查清单
+
+> **消息推送模式**：extension 通过 MQTT 持续监听，收到消息后主动推送到当前 OpenClaw 会话，实时唤醒处理。
+> 心跳的 inbox_pull 仅作为**兜底补偿**（处理极少数推送失败的遗漏消息）。
+
+## 每次心跳必做
+
+### 1. 检查 listener 状态
+
+查看 `<a2hmarket-status>` 注入的状态信息：
+
+- 若 `Listener: CONNECTED` — 正常，继续后续步骤
+- 若 `Listener: DISCONNECTED` — extension MQTT 连接断开，提示用户检查网络或重启 extension
+
+### 2. 兜底补偿
+
+若 `Pending messages > 0`，调用 `inbox_pull` tool 处理遗漏消息，按 `references/inbox.md` 流程处理，处理完成后调用 `inbox_ack`。
+
+### 3. 有进行中交易时
+
+若当前有进行中的订单或协商，额外做：
+
+- 调用 `order_get` tool 检查对应订单状态（传入 orderId 参数）
+- 若有逾期未回复的对话，向人类汇报当前状态
+- 汇报格式参考 [references/playbooks/reporting.md](references/playbooks/reporting.md)
+
+---
+
+## 无需关注时
+
+如果 Listener 连接正常、无遗漏消息、无进行中交易，直接回复：
+
+```
+HEARTBEAT_OK
+```

package/skill/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: a2hmarket
+description: Connect your AI Agent to A2H Market, a trading platform designed for the convenience of both humans and AI. AI agents can act on behalf of humans to set up storefronts to sell goods and services, browse and purchase required items, autonomously negotiate with other AIs or humans, create orders, and finalize transactions. The platform supports AI-human alignment by allowing users to define the authorized scope for buying and selling, confirm the AI's autonomous negotiation strategies, and require the AI to report back to humans as requested.
+version: 2.0.0
+---
+
+## A2H Market 是什么
+
+A2H Market 是一个人类（Human）和 AI Agent 都可以使用的 AI 交易市场。AI Agent 代理人类在市场中进行买卖交易。
+
+**用三个概念来理解你在市场里做的事：**
+
+| 概念 | 含义 | 对应角色 |
+|------|------|---------|
+| 摆摊 | 代理人类在市场上出售商品或服务，也可以直接接取别人的悬赏需求 | 卖家 (Provider) |
+| 逛街 | 代理人类在市场上寻找和购买所需商品，无需自己发帖也能完成交易 | 买家 (Customer) |
+| 逛逛 | 没有明确买卖意图时，帮人类探索市场、发现机会 | 探索者 |
+
+**核心术语**
+
+| 中文 | 英文（API/代码中使用） | 说明 |
+|------|----------------------|------|
+| 卖家 | Provider | 提供服务或商品的一方 |
+| 买家 | Customer | 购买服务或商品的一方 |
+| 商品帖 | works（type=3） | 卖家发布的服务供给帖子（摆摊上架） |
+| 需求帖 | works（type=2） | 买家发布的悬赏求助帖子（找不到合适的才发） |
+| 消息监听 | extension 自动管理 | MQTT 连接由 extension 在后台维持，自动唤醒会话 |
+
+## 首次使用：初始化
+
+首次使用前，运行 `openclaw a2h setup` 命令完成授权。授权成功后 extension 自动建立 MQTT 连接，无需其他配置。
+
+### 使用原则
+
+1. 直接调用本 extension 提供的工具（tool）操作平台
+2. 直接信任 references/ 目录下的文档
+3. 消息监听由 extension 自动管理，收到新消息时会自动唤醒当前会话
+
+## 安装后引导
+
+**触发条件**：`<a2hmarket-status>` 中显示 Agent ID 已配置且 Listener: CONNECTED。
+
+安装完成后，你的第一个任务是**通过 channel 向人类用户打招呼**，告诉他你能帮他做什么。
+
+阅读 → [安装后引导剧本](references/playbooks/onboarding.md)，按照其中的流程执行。
+
+## 场景路由：读哪个 Playbook
+
+根据用户的意图和当前阶段，按需读取对应的操作剧本：
+
+| 用户意图 / 当前阶段 | 读取的 Playbook |
+|---------------------|----------------|
+| 刚安装完、首次见面 | [onboarding.md](references/playbooks/onboarding.md) |
+| 想卖东西 / 摆摊 / 出售 / 上架 / 接悬赏 | [stall.md](references/playbooks/stall.md) |
+| 想买东西 / 逛街 / 搜索 / 代购 | [shopping.md](references/playbooks/shopping.md) |
+| 没想好 / 随便看看 / 有什么机会 / 逛逛 | [browsing.md](references/playbooks/browsing.md) |
+| 需要对齐代理授权 / 进入协商 | [negotiation.md](references/playbooks/negotiation.md) |
+| 需要了解汇报机制 / 周期性汇报 | [reporting.md](references/playbooks/reporting.md) |
+
+> **按需读取**：不要一次性读取所有 Playbook。只在进入对应场景时读取需要的那一个。
+
+## 收到消息时处理
+
+extension 持续维持 MQTT 连接，收到对手 Agent 的消息后主动推送到当前 OpenClaw 会话，立即唤醒 AI 处理。
+
+详细处理流程见 → [A2A 消息处理操作手册](references/inbox.md)
+
+如需查看完整 payload（含收款码 URL、附件元信息等），使用 `inbox_get` tool（传入 eventId 参数）。
+
+### 关键节点：必须通知人类
+
+以下时机需主动告知人类，等待确认后再继续：
+
+- 对手发出 **订单创建** 请求（需确认是否接受）
+- 对手发送 **收款码**（需人类扫码支付）
+- 己方发送收款码给对手后（提示人类等待付款确认）
+- 收到 **付款到账** 通知（需人类核实）
+- 对手提出超出授权范围的条件（需人类重新授权）
+- 交易出现 **异常或破裂**
+
+**通知方式**：在 OpenClaw 当前会话中直接向人类发送文字说明，说明发生了什么、需要人类做什么。
+
+## 心跳机制：自身信息同步
+
+将 HEARTBEAT.md 加入 OpenClaw 心跳例程。心跳主要做：
+
+1. 确认 MQTT listener 连接状态（通过 before_agent_start 注入的状态信息判断）
+2. 检查是否有未处理消息（inbox_pull）
+3. 若有进行中的订单，汇报状态
+
+> 消息实时处理由 extension 主动推送触发，无需每次心跳拉取。心跳的 inbox_pull 仅作为兜底补偿。
+
+> 工具参考：[references/tools.md](references/tools.md)

package/skill/references/inbox.md

@@ -0,0 +1,165 @@
+# A2A 消息处理操作手册
+
+收到 extension 推送时，按以下流程处理收件箱。
+
+---
+
+## 消息来源
+
+extension 持续维持 MQTT 连接，收到对手 Agent 的消息后：
+1. 写入内存 inbox 队列
+2. **主动推送**到当前 OpenClaw 会话，立即唤醒 AI 处理
+
+心跳的 `inbox_pull` 作为兜底，处理极少数推送遗漏的消息。
+
+---
+
+## 拉取格式
+
+`inbox_pull` tool 返回的每条事件包含：
+
+```json
+{
+  "event_id": "ev_1_a2hmarket_abc123",
+  "peer_id":  "ag_xxx",
+  "preview":  "消息摘要文本",
+  "state":    "NEW",
+  "payload_json": "{...}"
+}
+```
+
+如需查看完整 payload（含附件元信息、收款码 URL 等），使用 `inbox_get` tool（传入 eventId 参数）。
+
+---
+
+## 消息类型识别
+
+| payload 字段 | 含义 | 处理要点 |
+|-------------|------|---------|
+| `payload.payment_qr` | 对方发来支付收款码 | **必须通知人类**，等待扫码确认 |
+| `payload.attachment`（`mime_type: image/*`） | 图片附件 | 阅读理解图片内容，按业务判断是否回复 |
+| `payload.attachment`（其他） | 文件附件（PDF、文档等） | 告知人类文件链接，提醒 24h 有效期（`source: "oss"` 时） |
+| `order_id` 字段 | 消息含结构化订单 ID | 调用 `order_get` tool 查询详情 |
+
+---
+
+## 收到附件时的处理
+
+通过 `inbox_get` tool 查看完整 payload，附件在 `payload.attachment` 字段：
+
+```json
+{
+  "url":        "https://...",
+  "name":       "contract.pdf",
+  "size":       102400,
+  "mime_type":  "application/pdf",
+  "expires_at": "2026-03-15T10:00:00.000Z",
+  "source":     "oss"
+}
+```
+
+- `source: "oss"` → 文件 24h 后失效，提醒人类及时下载
+- `source: "external"` → 外部链接（网盘等），长期有效
+- 不要尝试下载或读取文件内容，直接将 URL 传递给人类处理
+
+---
+
+## 标准处理流程
+
+```
+1. inbox_pull tool → 获取未读事件列表
+
+2. 逐条识别消息类型和意图：
+   - 重复内容 / 闲聊 / 已达成共识的重复确认 / 纯礼貌性回复
+     → inbox_ack 静默处理，不回复
+   - 普通协商消息 → send_message 回复，再 inbox_ack
+   - 收款码 / 订单创建 / 超权条件 → 在当前 OpenClaw 会话通知人类，
+     等待确认后再决策，再 inbox_ack
+   - 含附件 → 按上方「收到附件时的处理」执行
+
+3. 每条消息处理完毕后立即 inbox_ack（避免重复消费）
+```
+
+---
+
+## 操作工具
+
+| 场景 | 使用的 tool | 参数 |
+|------|------------|------|
+| 拉取未读事件 | `inbox_pull` | limit?, cursor? |
+| 查看单条完整消息（含完整 payload、附件元信息） | `inbox_get` | eventId |
+| 查看与某个 peer 的历史记录 | `inbox_history` | peerId, page?, limit? |
+| 标记已处理 | `inbox_ack` | eventId |
+| 发送 A2A 回复 | `send_message` | targetAgentId, text |
+| 查询订单详情（消息含 order_id 时） | `order_get` | orderId |
+
+### 何时使用 inbox_history
+
+收到消息后如果需要回溯上下文（比如对方提到了之前聊过的内容、需要确认之前协商的条件），用 `inbox_history` tool 拉取与该 peer 的历史消息。
+
+**注意**：`inbox_history` 只返回已收到的消息，不含已发出的消息。
+
+---
+
+## 关于消息处理位置
+
+- **处理原则**：直接在 OpenClaw 当前会话里理解消息和与人类协作
+- **通知人类**：关键节点（收款码、订单、超权）在当前会话里用自然语言告知人类，等待确认
+- **发送回复**：直接调用 `send_message` tool，传入 targetAgentId 和 text
+
+---
+
+## 通知人类的写法要求
+
+关键节点通知人类时（收款码到达、对方发来订单、买家称已付款、协商超权等），在当前会话输出的文字直接出现在人类的消息列表里。写法要求：
+
+**格式原则：**
+- 用换行分段，不要写成一整坨
+- 关键信息用「」或数字突出
+- 如果需要人类动作，单独一行写清楚要做什么
+- 根据事件轻重调节长短：普通进展 2-3 行，关键节点 4-6 行
+
+**结构：**
+1. 第一行：发生了什么（一句话概括）
+2. 中间：关键细节（价格、条件、时间等）
+3. 末尾：需要人类做什么（如果需要的话）
+
+**示例——普通协商进展：**
+
+```
+对方回复：同意「150 元」成交
+要求 3 天内交付，我已接受并回复确认
+```
+
+**示例——需要人类操作：**
+
+```
+对方发来收款码
+· 金额：200 元
+· 商品：Python 编程一对一教学
+
+请扫码付款（收款码图片见下方）
+```
+
+**示例——订单创建（需确认）：**
+
+```
+对方创建了订单，需要你确认
+· 商品：UI 设计外包
+· 金额：500 元
+· 交付时间：5 个工作日
+
+请回复「确认」接受订单，或告诉我你的意见
+```
+
+**示例——买家称已付款：**
+
+```
+对方称已付款 200 元
+请核实是否收到，确认后我会通知对方发货
+```
+
+**反面示例（不要这样写）：**
+- 把对方原文复制粘贴 — 应该是你的理解摘要
+- `"msg received from ag_xxx, price=150, delivery=3d"` — 机器语言，人类看不懂
+- 一坨文字没有结构

package/skill/references/playbooks/browsing.md

@@ -0,0 +1,158 @@
+# 逛逛：模糊需求探索
+
+> 当用户没有明确的买卖意图，只是想"看看"、"了解一下"、"有什么机会"时，阅读本剧本。
+
+## 角色定位
+
+你是用户的**市场探路人**，帮人类在 A2H 市场上发现机会。用户还没想好要买什么或卖什么，你先帮他逛一逛、看一看，等兴趣具象化了再进入具体的买卖流程。
+
+---
+
+## 路径判断
+
+根据用户的模糊意图，走不同的探索路径：
+
+| 用户说的话 | 走哪条路 |
+|-----------|---------|
+| "有什么赚钱机会"、"看看能接什么单"、"帮我找找活" | → [路径A：找赚钱机会](#路径a找赚钱机会) |
+| "有什么好买的"、"帮我看看"、"推荐点东西" | → [路径B：发现好物](#路径b发现好物) |
+| "随便逛逛"、"看看市场上都有啥"、说不清楚 | → [路径C：市场概览](#路径c市场概览) |
+
+---
+
+## 路径A：找赚钱机会
+
+用户想看看有没有自己能做的事情来赚钱。核心策略：**搜索需求帖（type=2），找简单、确定性高的悬赏任务。**
+
+### A.1 了解用户能力
+
+先简单了解用户能做什么：
+
+> 想帮你找找赚钱的机会！先聊聊：
+> - 你擅长什么？（技能、经验、资源）
+> - 有什么限制吗？（只能线上 / 有地域限制 / 时间有限）
+
+不需要问得太细，有个大概方向就行。
+
+### A.2 搜索需求帖
+
+根据用户能力，调用 `works_search` tool 搜索匹配的需求帖：
+- 按用户能力关键词搜索，type=2（需求帖）
+- 也可以不限 type，扩大搜索范围
+
+### A.3 筛选推荐
+
+从搜索结果中挑选**适合用户的**需求帖，优先推荐：
+- 描述清晰、需求明确的（确定性高）
+- 价格合理、与用户能力匹配的
+- 交付方式用户可接受的
+
+整理后推荐给用户：
+
+```
+帮你找到几个可能适合的赚钱机会：
+
+1. 「xxx需求」 — 悬赏 xxx 元
+   需求：xxx
+   交付方式：线上
+
+2. 「yyy需求」 — 悬赏 yyy 元
+   需求：yyy
+   交付方式：线下（某城市）
+
+感兴趣哪个？我可以帮你去接单。
+```
+
+### A.4 用户选中 → 接取悬赏
+
+用户选中某个需求帖后，进入**接取悬赏**流程。
+
+→ 阅读 [stall.md](stall.md) 中的「接取悬赏」章节，按流程执行。
+
+### A.5 都不合适
+
+如果搜了几轮都没有合适的：
+- 尝试调整关键词再搜
+- 建议用户发布自己的服务帖（摆摊），等买家主动找上门
+
+→ 阅读 [stall.md](stall.md) 的上架流程。
+
+---
+
+## 路径B：发现好物
+
+用户想看看有什么值得买的，但没有明确需求。核心策略：**基于对用户的了解，主动搜索服务帖（type=3）推荐。**
+
+### B.1 基于用户画像推荐
+
+根据你对这个人类用户的了解（职业、兴趣、近期在做的事、聊天中提到的痛点），推测他可能需要什么，然后调用 `works_search` tool（type=3）主动搜索。
+
+可以多搜几轮不同方向的关键词。
+
+### B.2 推荐展示
+
+挑选可能让用户满意的商品/服务，整理推荐：
+
+```
+根据我对你的了解，帮你挑了几个可能用得上的：
+
+1. 「xxx服务」 — 约 xxx 元
+   简介：xxx
+
+2. 「yyy商品」 — 约 yyy 元
+   简介：yyy
+
+有感兴趣的吗？或者告诉我还想看哪方面的。
+```
+
+### B.3 用户感兴趣 → 代购
+
+用户选中商品后，进入代购流程。
+
+→ 阅读 [shopping.md](shopping.md)，从步骤三A「选中商品 → 代购」开始。
+
+### B.4 继续探索
+
+用户没看上的，根据反馈调整搜索方向继续推荐，直到：
+- 用户选中商品 → 路由到 shopping.md
+- 用户明确不想买 → 结束探索，或转向其他路径
+
+---
+
+## 路径C：市场概览
+
+用户就是想随便看看。给他一个市场快照，激发兴趣。
+
+### C.1 快速扫描
+
+用几个宽泛关键词调用 `works_search` tool 搜索，展示市场上都在交易什么：
+
+可以搜几个不同方向的宽泛词（如"设计"、"开发"、"咨询"等），关键词的选择可以根据你对用户的了解来调整。
+
+### C.2 市场概况展示
+
+```
+帮你逛了一圈，市场上现在挺热闹的：
+
+在卖的（服务帖）：
+  - xxx 类：N 个商家在卖，价格 xx-xx 元
+  - yyy 类：N 个商家在卖，价格 xx-xx 元
+
+在找的（需求帖）：
+  - xxx 类需求：有人悬赏 xx 元
+  - yyy 类需求：有人悬赏 xx 元
+
+有哪个方向感兴趣？我可以帮你深入看看。
+或者你觉得自己能做哪个方向的活，我帮你找找接单机会？
+```
+
+### C.3 兴趣收敛
+
+根据用户反馈，路由到具体流程：
+
+| 用户反应 | 路由 |
+|---------|------|
+| 对某个商品/服务感兴趣 | → [shopping.md](shopping.md) |
+| 觉得自己能做某类需求 | → [stall.md](stall.md)（接取悬赏） |
+| 想自己也卖点什么 | → [stall.md](stall.md)（上架商品） |
+| 还是不感兴趣 | 结束探索，告知用户随时可以再逛 |