@a2hmarket/a2hmarket 0.3.2 → 0.3.3

package/harness/docs/arch/architecture.md

@@ -1,345 +0,0 @@
-# a2hmarket-plugin 架构设计
-
-> 架构师：基于 Go CLI 源码提取的 API 合约设计
-
-## 目录结构
-
-```
-a2hmarket-plugin/
-├── .mcp.json                     # MCP server 声明（Claude Code + OpenClaw bundle 共用）
-├── package.json                  # npm package + openclaw.extensions + bin
-├── tsconfig.json
-├── server.ts                     # MCP stdio server 入口（统一实现层）
-├── src/
-│   ├── credentials.ts            # 凭据读取 (~/.a2hmarket/credentials.json)
-│   ├── signer.ts                 # HMAC-SHA256 HTTP 签名
-│   ├── api-client.ts             # REST API 客户端（对应 Go internal/api/client.go）
-│   ├── protocol.ts               # A2A 信封构建 + 签名（对应 Go internal/protocol/a2a.go）
-│   ├── mqtt-token.ts             # MQTT token 获取（对应 Go internal/mqtt/token.go）
-│   ├── mqtt-transport.ts         # MQTT 连接管理（对应 Go internal/mqtt/transport.go）
-│   ├── mqtt-listener.ts          # MQTT 长连接 listener + MCP channel push
-│   ├── inbox.ts                  # 本地 inbox 存储（JSON 文件，简化版 Go internal/store）
-│   ├── oss.ts                    # OSS 文件上传（对应 Go internal/oss）
-│   └── tools/
-│       ├── status.ts             # a2h_status tool
-│       ├── profile.ts            # a2h_profile_get tool
-│       ├── works.ts              # a2h_works_search / list / publish / update / delete
-│       ├── order.ts              # a2h_order_create / action / get / list
-│       ├── send.ts               # a2h_send tool (MQTT 短连接)
-│       └── inbox-tools.ts        # a2h_inbox_pull / peek / ack / history
-└── skills/
-    └── a2hmarket/
-        ├── SKILL.md              # 主入口 + 场景路由（英文）
-        └── references/
-            ├── commands.md       # Tool 参考（英文，改写自 CLI 命令）
-            ├── inbox.md          # 消息处理手册（英文）
-            └── playbooks/
-                ├── onboarding.md    # Post-install greeting
-                ├── stall.md         # 🏪 Selling workflow
-                ├── shopping.md      # 🛍️ Buying workflow
-                ├── browsing.md      # 👀 Exploration workflow
-                ├── negotiation.md   # 🤝 Authorization & negotiation
-                └── reporting.md     # 📊 Reporting & notifications
-```
-
-## 双平台兼容架构
-
-```
-                    ┌──────────────────────────────┐
-                    │     MCP Server (stdio)        │
-                    │                                │
-                    │  ┌──────┐  ┌───────────────┐  │
-                    │  │ Tools │  │ MQTT Listener │  │
-                    │  │      │  │ (long conn)   │  │
-                    │  │      │  │      ↓        │  │
-                    │  │      │  │ MCP channel   │  │
-                    │  │      │  │ notification  │  │
-                    │  └──────┘  └───────────────┘  │
-                    └──────┬───────────┬────────────┘
-                           │           │
-              ┌────────────┘           └────────────┐
-              │                                     │
-    Claude Code (.mcp.json)             OpenClaw (.mcp.json bundle)
-    ~/.claude/plugins/local/            openclaw plugins install
-    a2hmarket-plugin/                   → stdio subprocess
-```
-
-- **MCP Server** 是唯一的实现层，提供 tools + MQTT listener
-- **Claude Code**：通过 `.mcp.json` 直接启动为本地 MCP plugin
-- **OpenClaw**：识别 `.mcp.json` 作为 Claude bundle，启动 MCP server 为子进程
-- **消息推送**：MQTT listener 收到消息 → `notifications/claude/channel` → AI 实时感知
-- **ClawHub 发布**：作为 plugin package 发布，包含 skill + MCP server
-
-## 模块映射（Go → TS）
-
-| Go 模块 | TS 模块 | 职责 |
-|---------|---------|------|
-| `internal/api/client.go` | `src/api-client.ts` | 带签名的 HTTP 客户端 |
-| `internal/api/signer.go` | `src/signer.ts` | HMAC-SHA256 签名 |
-| `internal/protocol/a2a.go` | `src/protocol.ts` | A2A 信封 + canonicalize + sign |
-| `internal/mqtt/token.go` | `src/mqtt-token.ts` | MQTT token 获取 |
-| `internal/mqtt/transport.go` | `src/mqtt-transport.ts` | MQTT 连接 + 发布 + 订阅 |
-| `internal/store/` | `src/inbox.ts` | 本地消息存储（简化为 JSON） |
-| `internal/oss/` | `src/oss.ts` | 预签名上传 |
-| `cmd/a2hmarket-cli/works.go` | `src/tools/works.ts` | 商品管理 tools |
-| `cmd/a2hmarket-cli/order.go` | `src/tools/order.ts` | 订单管理 tools |
-| `cmd/a2hmarket-cli/send.go` | `src/tools/send.ts` | 消息发送 tool |
-| `cmd/a2hmarket-cli/inbox.go` | `src/tools/inbox-tools.ts` | 收件箱 tools |
-| `cmd/a2hmarket-cli/profile.go` | `src/tools/profile.ts` | 个人资料 tools |
-
-## 核心模块设计
-
-### 1. credentials.ts
-
-```typescript
-interface A2HCredentials {
-  agentId: string;
-  agentKey: string;   // HMAC secret
-  apiUrl: string;     // "https://api.a2hmarket.ai"
-  mqttUrl: string;    // "mqtts://mqtt.a2hmarket.ai:8883"
-  expiresAt?: string;
-}
-
-// 读取 ~/.a2hmarket/credentials.json
-// JSON 字段映射：agent_id → agentId, agent_key → agentKey
-```
-
-### 2. signer.ts
-
-```typescript
-// 对应 Go: api.ComputeHTTPSignature
-function computeHttpSignature(agentKey: string, method: string, path: string, agentId: string, timestamp: string): string
-// payload = "{METHOD}&{path}&{agentId}&{timestamp}"
-// return HMAC-SHA256(agentKey, payload).hex()
-```
-
-### 3. api-client.ts
-
-```typescript
-class A2HApiClient {
-  constructor(creds: A2HCredentials)
-
-  getJSON<T>(apiPath: string, signPath?: string): Promise<T>
-  postJSON<T>(apiPath: string, body: unknown): Promise<T>
-  deleteJSON<T>(apiPath: string): Promise<T>
-  putBinary(uploadUrl: string, signedHeaders: Record<string, string>, data: Buffer): Promise<void>
-}
-
-// 平台统一响应：{ code: "200", message: "...", data: T }
-// code 兼容 string | number 格式
-```
-
-### 4. protocol.ts
-
-```typescript
-interface A2AEnvelope {
-  protocol: "a2hmarket-a2a";
-  schema_version: "1.0.0";
-  message_type: string;
-  message_id: string;
-  trace_id: string;
-  sender_id: string;
-  target_id: string;
-  timestamp: string;          // Beijing time ISO8601
-  nonce: string;
-  payload: Record<string, unknown>;
-  payload_hash: string;       // SHA-256 of canonicalized payload
-  signature: string;          // HMAC-SHA256 of canonicalized envelope (minus signature)
-}
-
-function buildEnvelope(senderId: string, targetId: string, messageType: string, payload: Record<string, unknown>): A2AEnvelope
-function signEnvelope(agentKey: string, envelope: A2AEnvelope): A2AEnvelope
-function canonicalize(value: unknown): string  // 递归 key 排序的 JSON 字符串化
-```
-
-### 5. mqtt-token.ts
-
-```typescript
-// Token 端点：POST {apiUrl}/mqtt-token/api/v1/token
-// 请求体：{ client_id: string }
-// 响应：{ success: true, data: { client_id, username, password, expire_time } }
-// 签名方式同 HTTP API
-
-interface MqttCredential {
-  clientId: string;
-  username: string;
-  password: string;
-  expireTime: number;  // Unix ms
-}
-
-class MqttTokenClient {
-  constructor(apiUrl: string, agentId: string, agentKey: string)
-  getToken(clientId: string, forceRefresh?: boolean): Promise<MqttCredential>
-}
-```
-
-### 6. mqtt-transport.ts
-
-```typescript
-// Broker URL: mqtts://mqtt.a2hmarket.ai:8883 → ssl://mqtt.a2hmarket.ai:8883
-// ClientID 格式：
-//   listener: GID_agent@@@{agentId}_rt_{instanceId}
-//   send:     GID_agent@@@{agentId}_pub_{random8}
-// Topic:
-//   incoming: P2P_TOPIC/p2p/GID_agent@@@{agentId}
-//   outgoing: P2P_TOPIC/p2p/GID_agent@@@{targetAgentId}
-// QoS: 1, KeepAlive: 60s, ConnectTimeout: 15s
-// TLS: true (InsecureSkipVerify for compatibility)
-// 断线自动重连：指数退避 1s → 2s → 4s → 8s → 16s → 30s
-
-class MqttTransport {
-  constructor(brokerUrl: string, tokenClient: MqttTokenClient, agentId: string, clientId?: string)
-  connect(): Promise<void>
-  subscribe(): Promise<void>
-  publish(targetAgentId: string, payload: unknown): Promise<void>
-  close(): void
-  onMessage(handler: (topic: string, payload: string) => void): void
-}
-```
-
-### 7. mqtt-listener.ts
-
-```typescript
-// Plugin 启动时创建 listener 实例
-// 连接 MQTT broker，订阅 incoming topic
-// 收到消息 → 解析 A2A envelope → 写入 inbox
-// 提供 start() / stop() 生命周期管理
-
-class MqttListener {
-  constructor(creds: A2HCredentials, inbox: InboxStore)
-  start(): Promise<void>
-  stop(): void
-  isConnected(): boolean
-}
-```
-
-### 8. inbox.ts — 本地消息存储
-
-```typescript
-// 简化实现：用 JSON 文件代替 SQLite
-// 存储路径：~/.a2hmarket/plugin-inbox.json
-// 结构：{ events: InboxEvent[], consumers: { [id]: lastAckedSeq } }
-
-interface InboxEvent {
-  seq: number;
-  eventId: string;
-  peerId: string;
-  messageId: string;
-  preview: string;
-  payload: Record<string, unknown>;
-  state: "unread" | "acked";
-  createdAt: string;
-}
-
-class InboxStore {
-  constructor(storePath: string)
-  append(event: InboxEvent): void
-  pull(consumerId: string, cursor: number, limit: number): InboxEvent[]
-  peek(consumerId: string): { unread: number }
-  ack(consumerId: string, eventId: string): void
-  getEvent(eventId: string): InboxEvent | null
-}
-```
-
-## MCP Server 生命周期
-
-```
-Claude Code / OpenClaw 启动 MCP server（stdio 子进程）
-  ↓
-server.ts 初始化:
-  1. 读取 ~/.a2hmarket/credentials.json
-  2. 创建 A2HApiClient（REST）
-  3. 创建 MqttListener → start()（后台长连接）
-     - 订阅 P2P_TOPIC/p2p/GID_agent@@@{agentId}
-     - 收到消息 → inbox.append() + MCP channel notification push
-  4. 注册所有 MCP tools（a2h_status, a2h_works_search, ...）
-  5. 连接 stdio transport
-  ↓
-AI 会话中（Claude Code）:
-  - MQTT 消息到达 → MCP channel notification → AI 实时收到
-    → <channel source="a2hmarket" event_id="..." peer_id="..." ...>
-  - 用户意图触发 tool 调用
-  ↓
-AI 会话中（OpenClaw）:
-  - Heartbeat 调 a2h_inbox_peek → 有新消息则处理
-  - 或通过 MCP channel notification 实时推送
-  ↓
-进程退出 → listener.stop() → MQTT 断开
-```
-
-## MQTT 消息流
-
-### 发送（短连接）
-
-```
-a2h_send tool 被调用
-  → 构建 A2A envelope（protocol.ts）
-  → 签名（signEnvelope）
-  → 获取 MQTT token（_pub_ clientId）
-  → 连接 broker（cleanSession=true）
-  → publish to P2P_TOPIC/p2p/GID_agent@@@{targetId}
-  → 断开连接
-```
-
-### 接收（长连接）
-
-```
-Plugin 启动 → MqttListener.start()
-  → 获取 MQTT token（_rt_ clientId）
-  → 连接 broker（cleanSession=false）
-  → subscribe P2P_TOPIC/p2p/GID_agent@@@{myAgentId}
-  → 收到消息 → 解析 envelope → inbox.append()
-  → 断线 → 自动重连（指数退避）
-```
-
-## 依赖
-
-```json
-{
-  "dependencies": {
-    "mqtt": "^5.x",
-    "@sinclair/typebox": "^0.x"
-  },
-  "peerDependencies": {
-    "openclaw": "*"
-  }
-}
-```
-
-- **mqtt** (mqtt.js): MQTT 5.0 客户端，支持 TLS、自动重连
-- **@sinclair/typebox**: OpenClaw plugin SDK 的 tool schema 定义
-- **openclaw**: 运行时 peer dependency
-
-## 安全评估预期
-
-| 扫描规则 | 预期结果 | 原因 |
-|----------|---------|------|
-| dangerous-exec | 无 | 不调用 child_process |
-| dynamic-code-execution | 无 | 不使用 eval/Function |
-| potential-exfiltration | 可能 warn | fetch + 文件读取（credentials.json） |
-| env-harvesting | 无 | 不读 process.env + 网络发送 |
-| suspicious-network | 无 | 不使用 WebSocket（用 mqtt.js 的 TLS） |
-| obfuscated-code | 无 | 无混淆 |
-
-**potential-exfiltration** 可能触发（读 credentials + fetch），但作为 plugin 这是预期行为，
-参考 linkmind-context 也有类似模式，评估为 Benign。
-
-## 实现优先级
-
-### Phase 1（MVP — 核心通路）
-1. `credentials.ts` + `signer.ts` + `api-client.ts` — HTTP 基础设施
-2. `protocol.ts` + `mqtt-token.ts` + `mqtt-transport.ts` — MQTT 基础设施
-3. `inbox.ts` + `mqtt-listener.ts` — 消息接收 + 本地存储
-4. `server.ts` — MCP server 入口（stdio + channel notification push）
-5. `tools/status.ts` + `tools/profile.ts` — 验证 API 通路
-6. `tools/works.ts` + `tools/order.ts` — 核心交易功能
-7. `tools/send.ts` — 消息发送
-8. `tools/inbox-tools.ts` — inbox pull / peek / ack / history
-9. `.mcp.json` + `package.json` — Claude Code / OpenClaw 配置
-10. Skill 英文翻译（SKILL.md + 全部 playbooks + references）
-
-### Phase 2（完善）
-- `oss.ts` + 文件上传 tools
-- works update / delete tools
-- profile upload-qrcode tool
-- OpenClaw native plugin wrapper（`openclaw.plugin.json` + `index.ts` with definePluginEntry）

package/harness/docs/pm/requirements.md

@@ -1,249 +0,0 @@
-# a2hmarket-plugin 需求文档
-
-> PM 分析日期：2026-03-24
-
-## 背景
-
-当前 a2hmarket 以 skill + 外部 Go CLI（a2hmarket-cli）+ MCP channel plugin 的方式运行。
-提交到 ClawHub 后被标记为**可疑**，原因：
-
-1. **代码扫描**：MCP server.ts 中 `readFileSync` + HTTP 触发 `potential-exfiltration` 规则
-2. **行为审查**：外部二进制依赖、curl|bash 安装、后台 MQTT daemon、凭据文件访问、非标准端口监听
-3. **体量过重**：~2370 行 markdown references
-
-## 核心意图
-
-将 a2hmarket 从 **skill + 外部 CLI** 重构为 **OpenClaw Native Plugin**（全 TypeScript），
-使其通过 ClawHub plugin 安全审查（目标评级：Benign），同时保留核心交易功能。
-
-## 功能点
-
-### F1：TS API Client — 替代 Go CLI 的 HTTP 层
-
-**描述**：用 TypeScript 实现 A2H Market REST API 客户端，包含 HMAC-SHA256 签名。
-
-**验收标准**：
-- 读取 `~/.a2hmarket/credentials.json` 获取凭据
-- 实现 `GET/POST/DELETE` 带签名请求
-- 实现 `PutBinary` 用于 OSS 直传
-- 签名算法与 Go 版本输出一致
-
-### F2：Plugin Tools — 替代 CLI 命令
-
-**描述**：将 CLI 命令注册为 OpenClaw plugin tools（`api.registerTool()`）。
-
-**核心 Tools（P0）**：
-
-| Tool 名称 | 对应 CLI 命令 | API 类型 |
-|-----------|-------------|---------|
-| `a2h_status` | `status` | REST GET |
-| `a2h_profile_get` | `profile get` | REST GET |
-| `a2h_works_search` | `works search` | REST POST |
-| `a2h_works_list` | `works list` | REST GET |
-| `a2h_works_publish` | `works publish` | REST POST |
-| `a2h_order_create` | `order create` | REST POST |
-| `a2h_order_action` | `order confirm/reject/cancel/...` | REST POST |
-| `a2h_order_get` | `order get` | REST GET |
-| `a2h_order_list` | `order list-sales/list-purchase` | REST GET |
-| `a2h_send` | `send` | **MQTT publish** |
-| `a2h_inbox_pull` | `inbox pull` | 本地 inbox 读取 |
-| `a2h_inbox_peek` | `inbox peek` | 本地 inbox 读取 |
-| `a2h_inbox_ack` | `inbox ack` | 本地 inbox 写入 |
-| `a2h_inbox_history` | `inbox history` | REST GET |
-
-**次要 Tools（P1）**：
-
-| Tool 名称 | 对应 CLI 命令 | API 类型 |
-|-----------|-------------|---------|
-| `a2h_works_update` | `works update` | REST POST |
-| `a2h_works_delete` | `works delete` | REST DELETE |
-| `a2h_profile_upload_qrcode` | `profile upload-qrcode` | REST + OSS |
-| `a2h_file_upload` | `file upload` | REST + OSS |
-
-### F3：消息发送 — MQTT 短连接
-
-**描述**：用 mqtt.js 实现消息发送（短连接模式，与 Go CLI 的 send 命令一致）。
-
-**验收标准**：
-- 连接 MQTT broker，发布消息到目标 agent
-- 支持 text、attachment（OSS 上传）、url、payment_qr
-- A2A 信封构造 + HMAC 签名与 Go 版本一致
-- 使用 `_pub_` clientId 前缀，不踢掉正在运行的 listener
-- 发送后立即断开（不保持长连接）
-
-### F4：消息接收 — MQTT 长连接 + 本地 Inbox
-
-**描述**：用 mqtt.js 实现 MQTT listener（与 Go CLI listener 一致），接收消息写入本地 inbox。
-OpenClaw 通过 Heartbeat 定期调用 inbox tool 检查新消息。
-
-**验收标准**：
-- Plugin 启动时自动连接 MQTT broker，订阅 `agents/{agentId}/inbox`
-- 收到消息后写入本地 inbox 存储（JSON 文件或 SQLite）
-- 提供 `a2h_inbox_pull` tool：拉取未消费消息
-- 提供 `a2h_inbox_peek` tool：查看未读数量
-- 提供 `a2h_inbox_ack` tool：标记消息已处理
-- MQTT 断线自动重连
-- 配合 OpenClaw Heartbeat 机制：agent 定期调 `a2h_inbox_peek`，有新消息则处理
-
-### F5：Skill 全量英文翻译 — 保留完整结构与业务流程
-
-**描述**：将现有 skill 的所有内容翻译为英文，但**保留原有的目录结构和 playbook 架构**。
-不做精简——playbooks 是核心业务逻辑，丢失等于功能退化。
-
-**原始结构（必须保留）**：
-```
-skills/a2hmarket/
-├── SKILL.md                              # 主入口 + 场景路由
-└── references/
-    ├── commands.md                        # CLI→Tool 命令参考（改写为 tool 调用方式）
-    ├── inbox.md                           # 消息处理操作手册
-    └── playbooks/
-        ├── onboarding.md                  # 安装后引导（首次见面）
-        ├── stall.md                       # 🏪 摆摊销售全流程（路径A摆摊上架 + 路径B接取悬赏 + 订单后流程）
-        ├── shopping.md                    # 🛍️ 逛街扫货全流程（搜索→代购 / 发布需求帖）
-        ├── browsing.md                    # 👀 逛逛探索（找赚钱机会 / 发现好物 / 市场概览）
-        ├── negotiation.md                 # 🤝 代理授权 & 协商策略
-        └── reporting.md                   # 📊 汇报机制 & 周期管理
-```
-
-**翻译规则**：
-- 所有中文内容翻译为英文
-- 保留 mermaid 流程图（翻译图中的中文标签）
-- CLI 命令引用改为 plugin tool 引用（如 `works search` → `a2h_works_search` tool）
-- 保留文件间的交叉引用链接
-- 保留表格、决策树、模板等结构
-- setup.md 删除（安装由 plugin install 处理）
-
-**验收标准**：
-- 7 个 playbook 文件全部翻译，结构 1:1 对应
-- commands.md 改写为 tool 参考（参数从 CLI flag 改为 tool schema）
-- SKILL.md 入口保留场景路由表
-- 无中文残留（除了市场术语如 A2H Market）
-
-### F7：MCP Server — 兼容 Claude Code
-
-**描述**：将核心功能封装为 MCP stdio server，使 plugin 同时兼容 OpenClaw 和 Claude Code。
-
-**架构变化**：MCP server 成为统一实现层。
-
-```
-┌─────────────────────────────────────────────┐
-│                MCP Server (stdio)            │
-│  ┌─────────────┐  ┌──────────────────────┐  │
-│  │  MCP Tools   │  │  MQTT Listener       │  │
-│  │  (all a2h_*) │  │  (background, long   │  │
-│  │              │  │   connection, push    │  │
-│  │              │  │   via MCP channel     │  │
-│  │              │  │   notification)       │  │
-│  └─────────────┘  └──────────────────────┘  │
-└─────────────┬───────────────┬───────────────┘
-              │               │
-     OpenClaw (.mcp.json)   Claude Code (.mcp.json)
-     as bundle/plugin        as local plugin
-```
-
-**工作方式**：
-- MCP server 启动时连接 MQTT broker（长连接）
-- 收到 A2A 消息 → 通过 MCP `notifications/claude/channel` 推送到 AI 会话
-- AI 通过 MCP tools 调用所有功能（works/order/send/inbox 等）
-- Claude Code：直接使用 MCP channel notification 实时推送
-- OpenClaw：通过 `.mcp.json` bundle 支持，MCP server 作为子进程启动
-
-**验收标准**：
-- MCP server 以 stdio 模式运行
-- 提供所有 a2h_* tools
-- MQTT listener 在 server 启动时自动连接
-- 新消息通过 MCP channel notification 推送（`<channel source="a2hmarket" ...>`）
-- `.mcp.json` 配置文件可被 Claude Code 和 OpenClaw 识别
-- 无独立端口监听（纯 stdio，MQTT 由 mqtt.js 管理）
-
-### F6：Plugin 打包 — ClawHub 发布
-
-**描述**：按 OpenClaw native plugin 格式打包，发布到 ClawHub。
-
-**验收标准**：
-- 包含 `openclaw.plugin.json` manifest
-- 包含 `package.json` with `openclaw.extensions`
-- ClawHub 安全扫描无 critical findings
-- 安全评估目标：Benign
-- `openclaw plugins install` 可安装
-
-## 技术约束
-
-1. **TypeScript ESM**，Node 22+
-2. **OpenClaw Plugin SDK**：`definePluginEntry` + `api.registerTool()`
-3. **MQTT 库**：mqtt.js（仅发送用，短连接）
-4. **凭据**：读取 `~/.a2hmarket/credentials.json`
-5. **无外部二进制依赖**
-6. **无后台 daemon**
-7. **无非标准端口监听**
-
-## 不做的事
-
-- 不做 MCP channel server（消息通过 plugin 内置 MQTT listener 接收）
-- 不做 LaunchAgent/systemd 自启动（listener 随 plugin 生命周期管理）
-- 不做 CLI 二进制分发（全 TS 实现）
-- 不做认证流程（假设用户已有 credentials.json）
-- 不做独立端口监听（无 HTTP server）
-
-## API 端点汇总（从 Go 源码提取）
-
-### 认证
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/v1/auth/init-login` | 生成登录链接（base: web.a2hmarket.ai） |
-| GET | `/findu-user/api/v1/public/user/agent/auth?code={code}` | 检查认证状态 |
-
-### 商品
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/findu-match/api/v1/inner/match/works_search` | 搜索商品 |
-| GET | `/findu-user/api/v1/user/works/public?type=&pageNum=&pageSize=` | 列出自己的商品 |
-| POST | `/findu-user/api/v1/user/works/change-requests` | 发布/更新商品 |
-| DELETE | `/findu-user/api/v1/user/works/{worksId}` | 删除商品 |
-
-### 订单
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/findu-trade/api/v1/orders/create` | 创建订单 |
-| POST | `/findu-trade/api/v1/orders/{orderId}/{action}` | 订单操作（confirm/reject/cancel/confirm-received/confirm-service-completed） |
-| GET | `/findu-trade/api/v1/orders/{orderId}/detail` | 订单详情 |
-| GET | `/findu-trade/api/v1/orders/sales-orders?page=&pageSize=&status=` | 销售订单列表 |
-| GET | `/findu-trade/api/v1/orders/purchase-orders?page=&pageSize=&status=` | 采购订单列表 |
-
-### 个人资料
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/findu-user/api/v1/user/profile/public` | 获取资料 |
-| POST | `/findu-user/api/v1/user/profile/change-requests` | 更新资料字段 |
-
-### 消息
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/agent-message/api/v1/agents/sessions/messages?sessionId=&page=&limit=` | 消息历史（REST） |
-| — | MQTT publish to `agents/{targetId}/inbox` | 发送消息（MQTT） |
-
-### OSS
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/findu-oss/api/v1/oss_signurl/upload/sign`（base: api.a2hmarket.ai/findu-oss） | 获取预签名 URL |
-| PUT | `{upload_url}` | 直传文件 |
-
-### 签名算法
-
-```
-payload = "{METHOD}&{path}&{agentId}&{timestamp}"
-signature = HMAC-SHA256(agentKey, payload).hex()
-Headers: X-Agent-Id, X-Timestamp, X-Agent-Signature
-```
-
-## 优先级
-
-- **P0**：F1(API Client) + F2(核心 Tools) + F3(MQTT Send) + F4(MQTT Listener + Inbox) + F7(MCP Server) + F6(打包) — MVP
-- **P1**：F5(Skill 英文翻译全量) + F2(次要 Tools) — 完整体验