feat: complete OpenClaw plugin API bridge with async notification architecture

- simulator/main.js: All 30+ register* methods now send JSON-RPC notifications to Go instead of being silent no-ops. Each plugin capability registration (tool, provider, channel, hook, http_route, command, service, etc.) is forwarded to Go via the notify channel. - sidecar.go: Refactored to async reader goroutine. Single goroutine reads all stdout lines, routes responses to pending callers via channel by ID, and dispatches notifications (no-ID messages) to notifyCh for handling. - plugin.go: drainNotify() collects all capabilities registered during plugin init. handleNotify() logs each registered capability for visibility. - All 9 openclaw tests pass including simulator + full pipeline tests.
2026-09-21 17:38:10 +00:00 · 2026-07-04 14:08:42 +08:00
parent 4102c6b034
commit e273e746ea
3 changed files with 276 additions and 107 deletions
--- a/internal/plugins/openclaw/plugin.go
+++ b/internal/plugins/openclaw/plugin.go
@ -142,6 +142,9 @@ func (p *Plugin) loadOCPlugin(s *sdk.PluginSDK, dir, name string) error {
 		return nil
 	}

+	// 收集插件注册过程中模拟器推送的通知
+	p.drainNotify(sp, name)
+
 	tools, err := sp.ListTools()
 	if err != nil {
 		sp.Close()
@ -174,6 +177,37 @@ func (p *Plugin) loadOCPlugin(s *sdk.PluginSDK, dir, name string) error {
 	return nil
 }

+func (p *Plugin) drainNotify(sp *sidecarProcess, name string) {
+	for {
+		select {
+		case n := <-sp.NotifyChan():
+			p.handleNotify(n, name)
+		default:
+			return
+		}
+	}
+}
+
+func (p *Plugin) handleNotify(n OCNotification, name string) {
+	if n.Method != "register" {
+		log.Printf("[openclaw] ocplugin %s: unknown notify method: %s", name, n.Method)
+		return
+	}
+	var params struct {
+		Type string          `json:"type"`
+		Data json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal(n.Params, &params); err != nil {
+		log.Printf("[openclaw] ocplugin %s: bad notify params: %v", name, err)
+		return
+	}
+	dataStr := string(params.Data)
+	if len(dataStr) > 200 {
+		dataStr = dataStr[:200] + "..."
+	}
+	log.Printf("[openclaw] ocplugin %s: capability %s data=%s", name, params.Type, dataStr)
+}
+
 func (p *Plugin) loadSidecar(s *sdk.PluginSDK, dir, name string) error {
 	sp, err := launchSidecar(dir, name)
 	if err != nil {
--- a/internal/plugins/openclaw/sidecar.go
+++ b/internal/plugins/openclaw/sidecar.go
@ -4,6 +4,7 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	"io"
 	"log"
 	"os"
 	"os/exec"
@ -20,8 +21,8 @@ type sidecarRequest struct {
 }

 type sidecarResponse struct {
-	JSONRPC string          `json:"jsonrpc"`
-	ID      int             `json:"id"`
+	JSONRPC string           `json:"jsonrpc"`
+	ID      int              `json:"id"`
 	Result  *json.RawMessage `json:"result,omitempty"`
 	Error   *struct {
 		Code    int    `json:"code"`
@ -42,16 +43,111 @@ type OCCallResult struct {
 	} `json:"content"`
 }

+// OCNotification 是模拟器主动推送的通知
+type OCNotification struct {
+	JSONRPC string          `json:"jsonrpc"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params"`
+}
+
+// OCNamedParam 通知参数中至少包含 name 的结构
+type OCNamedParam struct {
+	Type string `json:"type"`
+	Data *struct {
+		Name string `json:"name,omitempty"`
+	} `json:"data"`
+}
+
 type sidecarProcess struct {
-	name   string
-	dir    string
-	cmd    *exec.Cmd
-	stdin  *bufio.Writer
-	stdout *bufio.Scanner
-	mu     sync.Mutex
-	nextID int
-	closed bool
+	name    string
+	dir     string
+	cmd     *exec.Cmd
+	stdin   *bufio.Writer
+	mu      sync.Mutex
+	nextID  int
+	closed  bool
 	stopped bool
+
+	// 异步 reader
+	pending     map[int]chan<- []byte
+	notifyCh    chan OCNotification
+	readerStop  chan struct{}
+	readerWg    sync.WaitGroup
+	readerReady chan struct{}
+}
+
+func newSidecarProcess(name, dir string, cmd *exec.Cmd, stdin *bufio.Writer, stdout io.Reader) *sidecarProcess {
+	sp := &sidecarProcess{
+		name:        name,
+		dir:         dir,
+		cmd:         cmd,
+		stdin:       stdin,
+		pending:     make(map[int]chan<- []byte),
+		notifyCh:    make(chan OCNotification, 1024),
+		readerStop:  make(chan struct{}),
+		readerReady: make(chan struct{}),
+	}
+	sp.readerWg.Add(1)
+	go sp.readLoop(stdout)
+	<-sp.readerReady
+	return sp
+}
+
+func (s *sidecarProcess) readLoop(r io.Reader) {
+	defer s.readerWg.Done()
+	scanner := bufio.NewScanner(bufio.NewReader(r))
+	// 加大 scanner buffer 防止长行截断
+	scanner.Buffer(make([]byte, 0, 1024*64), 1024*64)
+	close(s.readerReady)
+
+	for {
+		select {
+		case <-s.readerStop:
+			return
+		default:
+		}
+
+		if !scanner.Scan() {
+			if scanner.Err() != nil {
+				log.Printf("[openclaw] sidecar %s read error: %v", s.name, scanner.Err())
+			}
+			return
+		}
+		line := scanner.Text()
+
+		var base struct {
+			ID     *int             `json:"id"`
+			Method string           `json:"method,omitempty"`
+			Error  *json.RawMessage `json:"error,omitempty"`
+		}
+		if err := json.Unmarshal([]byte(line), &base); err != nil {
+			continue
+		}
+
+		if base.ID != nil {
+			s.mu.Lock()
+			ch, ok := s.pending[*base.ID]
+			delete(s.pending, *base.ID)
+			s.mu.Unlock()
+			if ok {
+				ch <- []byte(line)
+				close(ch)
+			}
+		} else if base.Method != "" {
+			var notif OCNotification
+			if err := json.Unmarshal([]byte(line), &notif); err == nil {
+				select {
+				case s.notifyCh <- notif:
+				default:
+					log.Printf("[openclaw] sidecar %s notify channel full, dropping: %s", s.name, notif.Method)
+				}
+			}
+		}
+	}
+}
+
+func (s *sidecarProcess) NotifyChan() <-chan OCNotification {
+	return s.notifyCh
 }

 func launchSidecar(dir, name string) (*sidecarProcess, error) {
@ -70,9 +166,6 @@ func launchProcess(bin, arg, dir, name string) (*sidecarProcess, error) {
 		}
 	}

-	// 将 dir（插件目录）作为最后一个参数传给 Node.js 进程
-	// 这样: node <script> <plugin-dir>
-	// echoplugin 的 main.js 忽略它, 模拟器用它加载真实插件
 	cmd := exec.Command(nodePath, arg, dir)
 	cmd.Dir = dir
 	cmd.Stderr = os.Stderr
@ -90,13 +183,7 @@ func launchProcess(bin, arg, dir, name string) (*sidecarProcess, error) {
 		return nil, fmt.Errorf("start %s: %w", name, err)
 	}

-	sp := &sidecarProcess{
-		name:   name,
-		dir:    dir,
-		cmd:    cmd,
-		stdin:  bufio.NewWriter(stdin),
-		stdout: bufio.NewScanner(bufio.NewReader(stdout)),
-	}
+	sp := newSidecarProcess(name, dir, cmd, bufio.NewWriter(stdin), stdout)

 	if err := sp.waitReady(); err != nil {
 		sp.Close()
@ -121,55 +208,68 @@ func (s *sidecarProcess) waitReady() error {
 }

 func (s *sidecarProcess) call(method string, params interface{}) ([]byte, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
+	ch := make(chan []byte, 1)

+	s.mu.Lock()
 	if s.closed || s.stopped {
+		s.mu.Unlock()
 		return nil, fmt.Errorf("sidecar %s closed", s.name)
 	}
 	s.nextID++
 	id := s.nextID
+	s.pending[id] = ch
+
 	req := sidecarRequest{
 		JSONRPC: "2.0",
 		ID:      id,
 		Method:  method,
 		Params:  params,
 	}
-
 	data, err := json.Marshal(req)
 	if err != nil {
+		delete(s.pending, id)
+		s.mu.Unlock()
 		return nil, err
 	}
-
 	if _, err := s.stdin.Write(data); err != nil {
+		delete(s.pending, id)
+		s.mu.Unlock()
 		return nil, err
 	}
 	if _, err := s.stdin.Write([]byte("\n")); err != nil {
+		delete(s.pending, id)
+		s.mu.Unlock()
 		return nil, err
 	}
 	if err := s.stdin.Flush(); err != nil {
+		delete(s.pending, id)
+		s.mu.Unlock()
 		return nil, err
 	}
+	s.mu.Unlock()

-	if !s.stdout.Scan() {
-		if s.stdout.Err() != nil {
-			return nil, fmt.Errorf("sidecar %s read: %w", s.name, s.stdout.Err())
+	select {
+	case raw := <-ch:
+		if raw == nil {
+			return nil, fmt.Errorf("sidecar %s error: nil response", s.name)
 		}
-		return nil, fmt.Errorf("sidecar %s closed unexpectedly", s.name)
+		var resp sidecarResponse
+		if err := json.Unmarshal(raw, &resp); err != nil {
+			return nil, fmt.Errorf("sidecar %s unmarshal: %w", s.name, err)
+		}
+		if resp.Error != nil {
+			return nil, fmt.Errorf("sidecar %s error: %s", s.name, resp.Error.Message)
+		}
+		if resp.Result == nil {
+			return nil, nil
+		}
+		return []byte(*resp.Result), nil
+	case <-time.After(30 * time.Second):
+		s.mu.Lock()
+		delete(s.pending, id)
+		s.mu.Unlock()
+		return nil, fmt.Errorf("sidecar %s call %s timeout", s.name, method)
 	}
-	line := s.stdout.Text()
-
-	var resp sidecarResponse
-	if err := json.Unmarshal([]byte(line), &resp); err != nil {
-		return nil, fmt.Errorf("sidecar %s unmarshal: %w", s.name, err)
-	}
-	if resp.Error != nil {
-		return nil, fmt.Errorf("sidecar %s error: %s", s.name, resp.Error.Message)
-	}
-	if resp.Result == nil {
-		return nil, nil
-	}
-	return []byte(*resp.Result), nil
 }

 func (s *sidecarProcess) ListTools() ([]OCPTool, error) {
@ -213,16 +313,41 @@ func (s *sidecarProcess) CallTool(name string, args map[string]interface{}) (str
 	return sb, nil
 }

+// DrainNotify 排空通知通道
+func (s *sidecarProcess) DrainNotify() {
+	for {
+		select {
+		case <-s.notifyCh:
+		default:
+			return
+		}
+	}
+}
+
 func (s *sidecarProcess) Close() {
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.closed || s.stopped {
+		s.mu.Unlock()
 		return
 	}
 	s.stopped = true
+	s.mu.Unlock()
+
+	// 先杀进程（关闭 stdout pipe），然后 reader 的 Scan() 会退出
 	if s.cmd != nil && s.cmd.Process != nil {
 		s.cmd.Process.Kill()
 		s.cmd.Wait()
 	}
+
+	// 等 reader 循环结束
+	s.readerWg.Wait()
+
+	s.mu.Lock()
+	for id, ch := range s.pending {
+		close(ch)
+		delete(s.pending, id)
+	}
+	s.mu.Unlock()
+
 	log.Printf("[openclaw] sidecar %s stopped", s.name)
 }
--- a/internal/plugins/openclaw/simulator/main.js
+++ b/internal/plugins/openclaw/simulator/main.js
@ -18,6 +18,10 @@ function readJSON(file) {
  }
 }

+function notify(method, params) {
+  writeJSON({ jsonrpc: '2.0', method, params });
+}
+
 // ---- 解析插件入口 ----
 const pluginDir = path.resolve(process.argv[2]);
 if (!pluginDir) {
@ -25,20 +29,16 @@ if (!pluginDir) {
  process.exit(1);
 }

-// 1. 先读 package.json 找 extensions
 const pkgPath = path.join(pluginDir, 'package.json');
 const pkg = readJSON(pkgPath);
 let entryPath = null;

 if (pkg && pkg.openclaw) {
-  // runtimeExtensions > extensions (安装包首选编译后的 JS)
  let raw = pkg.openclaw.runtimeExtensions || pkg.openclaw.extensions;
  if (typeof raw === 'string') raw = [raw];
  if (Array.isArray(raw) && raw.length > 0) {
-    // 优先选已编译的 JS 入口: .ts 映射到 .js, .js 直接用
    for (const ext of raw) {
      let ep = path.resolve(pluginDir, ext);
-      // .ts → 同级 .js
      if (ep.endsWith('.ts')) {
        const jsEp = ep.replace(/\.ts$/, '.js');
        if (fs.existsSync(jsEp)) { entryPath = jsEp; break; }
@ -48,7 +48,6 @@ if (pkg && pkg.openclaw) {
  }
 }

-// 2. 回退: openclaw.plugin.json 的 entry/main
 if (!entryPath) {
  const manifest = readJSON(path.join(pluginDir, 'openclaw.plugin.json'));
  if (manifest) {
@ -57,7 +56,6 @@ if (!entryPath) {
  }
 }

-// 3. 最后尝试 index.js
 if (!entryPath) {
  entryPath = path.join(pluginDir, 'index.js');
 }
@ -83,15 +81,11 @@ if (typeof entry !== 'object' || typeof entry.register !== 'function') {
  process.exit(1);
 }

-// ---- 构造完整的 PluginApi 模拟 ----
+// ---- 注册工具（本地存储，供 tools/list 和 tools/call 用） ----
 const registeredTools = [];

-// registerTool 支持两种签名:
-//   api.registerTool(toolDef, opts?)          — 对象形式
-//   api.registerTool(factory, opts?)           — 工厂函数形式
 function registerTool(defOrFactory, opts) {
  if (typeof defOrFactory === 'function') {
-    // 工厂形式: 传入 toolContext, 返回工具对象或数组
    const toolCtx = {
      id: 'simulator',
      cwd: pluginDir,
@ -103,18 +97,15 @@ function registerTool(defOrFactory, opts) {
    for (const t of tools) {
      if (t && typeof t.execute === 'function') {
        registeredTools.push(t);
+        notify('register', { type: 'tool', data: { name: t.name, description: t.description, parameters: t.parameters } });
      }
    }
    return;
  }

-  // 对象形式
  const def = defOrFactory;
  if (!def || !def.name) return;

-  // definePluginEntry 的 register 传给 api.registerTool 时是完整工具定义
-  // defineToolPlugin 包装后传给 api.registerTool 的也是完整工具定义
-  // 关键是工具必须要有 execute 函数（或 factory 在之前展开）
  registeredTools.push({
    name: def.name,
    label: def.label || def.name,
@ -122,9 +113,10 @@ function registerTool(defOrFactory, opts) {
    parameters: def.parameters || { type: 'object', properties: {} },
    execute: typeof def.execute === 'function' ? def.execute : undefined,
  });
+  notify('register', { type: 'tool', data: { name: def.name, label: def.label, description: def.description, parameters: def.parameters } });
 }

-// 完整的 OpenClawPluginApi 模拟
+// ---- 构造完整的 OpenClawPluginApi ----
 const api = {
  id: entry.id || 'unknown',
  name: entry.name || 'Unknown',
@ -143,72 +135,93 @@ const api = {
  },
  resolvePath: (p) => path.resolve(pluginDir, p),

-  // 工具注册
+  // ---- 工具注册 ----
  registerTool,

-  // 以下 api 方法留为 no-op，保证真实插件调用时不崩溃
-  registerProvider: () => {},
-  registerChannel: () => {},
-  registerEmbeddingProvider: () => {},
-  registerSpeechProvider: () => {},
-  registerRealtimeTranscriptionProvider: () => {},
-  registerRealtimeVoiceProvider: () => {},
-  registerMediaUnderstandingProvider: () => {},
-  registerImageGenerationProvider: () => {},
-  registerMusicGenerationProvider: () => {},
-  registerVideoGenerationProvider: () => {},
-  registerWebFetchProvider: () => {},
-  registerWebSearchProvider: () => {},
-  registerMemoryEmbeddingProvider: () => {},
-  registerAgentHarness: () => {},
-  registerCliBackend: () => {},
-  registerHook: () => {},
-  registerHttpRoute: () => {},
-  registerGatewayMethod: () => {},
-  registerGatewayDiscoveryService: () => {},
-  registerCli: () => {},
-  registerNodeCliFeature: () => {},
-  registerService: () => {},
-  registerCommand: () => {},
-  registerInteractiveHandler: () => {},
-  registerAgentToolResultMiddleware: () => {},
-  registerTrustedToolPolicy: () => {},
-  registerToolMetadata: () => {},
-  registerContextEngine: () => {},
-  registerMemoryCapability: () => {},
-  registerMemoryPromptSection: () => {},
-  registerMemoryFlushPlan: () => {},
-  registerMemoryRuntime: () => {},
-  registerMemoryPromptSupplement: () => {},
-  registerMemoryCorpusSupplement: () => {},
+  // ---- Provider 注册 ----
+  registerProvider: (provider) => notify('register', { type: 'provider', data: { name: provider.name, description: provider.description } }),
+  registerEmbeddingProvider: (p) => notify('register', { type: 'embedding_provider', data: { name: p.name } }),
+  registerSpeechProvider: (p) => notify('register', { type: 'speech_provider', data: { name: p.name } }),
+  registerRealtimeTranscriptionProvider: (p) => notify('register', { type: 'realtime_transcription_provider', data: { name: p.name } }),
+  registerRealtimeVoiceProvider: (p) => notify('register', { type: 'realtime_voice_provider', data: { name: p.name } }),
+  registerMediaUnderstandingProvider: (p) => notify('register', { type: 'media_understanding_provider', data: { name: p.name } }),
+  registerImageGenerationProvider: (p) => notify('register', { type: 'image_generation_provider', data: { name: p.name } }),
+  registerMusicGenerationProvider: (p) => notify('register', { type: 'music_generation_provider', data: { name: p.name } }),
+  registerVideoGenerationProvider: (p) => notify('register', { type: 'video_generation_provider', data: { name: p.name } }),
+  registerWebFetchProvider: (p) => notify('register', { type: 'web_fetch_provider', data: { name: p.name } }),
+  registerWebSearchProvider: (p) => notify('register', { type: 'web_search_provider', data: { name: p.name } }),
+  registerMemoryEmbeddingProvider: (p) => notify('register', { type: 'memory_embedding_provider', data: { name: p.name } }),

-  // 会话相关
-  on: () => {},
-  onConversationBindingResolved: () => {},
+  // ---- Channel 注册 ----
+  registerChannel: (ch) => notify('register', { type: 'channel', data: { name: ch.name, type: ch.type } }),
+
+  // ---- Hook / 生命周期 ----
+  registerHook: (hook) => notify('register', { type: 'hook', data: { name: hook.name, event: hook.event } }),
+  registerRuntimeLifecycle: (lc) => notify('register', { type: 'runtime_lifecycle', data: { name: lc.name } }),
+
+  // ---- HTTP 路由 ----
+  registerHttpRoute: (route) => notify('register', { type: 'http_route', data: { path: route.path, method: route.method } }),
+
+  // ---- CLI 命令 ----
+  registerCommand: (cmd) => notify('register', { type: 'command', data: { name: cmd.name, description: cmd.description } }),
+  registerCli: (cli) => notify('register', { type: 'cli', data: { name: cli.name } }),
+  registerCliBackend: (cb) => notify('register', { type: 'cli_backend', data: { name: cb.name } }),
+  registerNodeCliFeature: (f) => notify('register', { type: 'node_cli_feature', data: { name: f.name } }),
+
+  // ---- Service ----
+  registerService: (svc) => notify('register', { type: 'service', data: { name: svc.name } }),
+
+  // ---- Agent 相关 ----
+  registerAgentHarness: (h) => notify('register', { type: 'agent_harness', data: { name: h.name } }),
+  registerAgentToolResultMiddleware: (m) => notify('register', { type: 'agent_tool_result_middleware', data: {} }),
+  registerInteractiveHandler: (h) => notify('register', { type: 'interactive_handler', data: { name: h.name } }),
+
+  // ---- Gateway ----
+  registerGatewayMethod: (gm) => notify('register', { type: 'gateway_method', data: { name: gm.name } }),
+  registerGatewayDiscoveryService: (gs) => notify('register', { type: 'gateway_discovery_service', data: { name: gs.name } }),
+
+  // ---- Trust & Metadata ----
+  registerTrustedToolPolicy: (p) => notify('register', { type: 'trusted_tool_policy', data: { name: p.name } }),
+  registerToolMetadata: (m) => notify('register', { type: 'tool_metadata', data: { name: m.name } }),
+
+  // ---- Context Engine ----
+  registerContextEngine: (ce) => notify('register', { type: 'context_engine', data: { name: ce.name } }),
+
+  // ---- Memory 子系统 ----
+  registerMemoryCapability: (mc) => notify('register', { type: 'memory_capability', data: { name: mc.name } }),
+  registerMemoryPromptSection: (ps) => notify('register', { type: 'memory_prompt_section', data: { name: ps.name } }),
+  registerMemoryFlushPlan: (fp) => notify('register', { type: 'memory_flush_plan', data: { name: fp.name } }),
+  registerMemoryRuntime: (mr) => notify('register', { type: 'memory_runtime', data: { name: mr.name } }),
+  registerMemoryPromptSupplement: (ps) => notify('register', { type: 'memory_prompt_supplement', data: { name: ps.name } }),
+  registerMemoryCorpusSupplement: (cs) => notify('register', { type: 'memory_corpus_supplement', data: { name: cs.name } }),
+
+  // ---- 会话相关 ----
+  on: (event, handler) => notify('register', { type: 'session_event', data: { event } }),
+  onConversationBindingResolved: (handler) => notify('register', { type: 'conversation_binding_resolved', data: {} }),

  session: {
-    state: { registerSessionExtension: () => {} },
+    state: { registerSessionExtension: (se) => notify('register', { type: 'session_extension', data: { name: se.name } }) },
    workflow: {
      enqueueNextTurnInjection: () => {},
-      registerSessionSchedulerJob: () => {},
+      registerSessionSchedulerJob: (job) => notify('register', { type: 'session_scheduler_job', data: { name: job.name } }),
      sendSessionAttachment: () => {},
      scheduleSessionTurn: () => {},
      unscheduleSessionTurnsByTag: () => {},
    },
    controls: {
-      registerControlUiDescriptor: () => {},
-      registerSessionAction: () => {},
+      registerControlUiDescriptor: (d) => notify('register', { type: 'control_ui_descriptor', data: { name: d.name } }),
+      registerSessionAction: (a) => notify('register', { type: 'session_action', data: { name: a.name } }),
    },
  },

  agent: {
    events: {
-      registerAgentEventSubscription: () => {},
-      emitAgentEvent: () => {},
+      registerAgentEventSubscription: (sub) => notify('register', { type: 'agent_event_subscription', data: { event: sub.event } }),
+      emitAgentEvent: (event, data) => notify('agent_event', { event, data }),
    },
  },

-  lifecycle: { registerRuntimeLifecycle: () => {} },
+  lifecycle: { registerRuntimeLifecycle: (lc) => notify('register', { type: 'lifecycle', data: { name: lc.name } }) },

  runContext: {
    setRunContext: () => {},
@ -274,13 +287,10 @@ rl.on('line', async (line) => {
    }

    try {
-      // OpenClaw 工具 execute 签名: (toolCallId, params, signal, onUpdate) => AgentToolResult
      const result = await tool.execute('sim-call-1', args, undefined, undefined);
-      // 如果返回已经是 AgentToolResult 格式，直接转发
      if (result && typeof result === 'object' && Array.isArray(result.content)) {
        writeJSON({ jsonrpc: '2.0', id, result });
      } else {
-        // 否则包装为 text result
        const text = typeof result === 'string' ? result : JSON.stringify(result);
        writeJSON({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }] } });
      }