remnote-bridge 0.1.11 → 0.1.13

package/dist/cli/server/config-server.js

@@ -8,10 +8,13 @@
  * - POST /api/restart — 调用 onRestart() 回调 → 返回成功
  */
 import http from 'http';
-import { DEFAULT_CONFIG, DEFAULT_DEFAULTS, loadConfig, saveConfig, configFilePath } from '../config.js';
+import { DEFAULT_CONFIG, DEFAULT_DEFAULTS, loadConfig, saveConfig, configFilePath, loadAddonConfig, saveAddonConfig } from '../config.js';
 export class ConfigServer {
     server = null;
+    _actualPort = 0;
     options;
+    /** 实际监听的端口（可能与 options.port 不同，若原端口被占用则 OS 自动分配） */
+    get actualPort() { return this._actualPort; }
     constructor(options) {
         this.options = options;
     }
@@ -20,15 +23,30 @@ export class ConfigServer {
     }
     start() {
         return new Promise((resolve, reject) => {
-            this.server = http.createServer((req, res) => this.handleRequest(req, res));
-            this.server.on('error', (err) => {
-                this.log(`ConfigServer 错误: ${err.message}`, 'error');
-                reject(err);
-            });
-            this.server.listen(this.options.port, this.options.host ?? '127.0.0.1', () => {
-                this.log(`ConfigServer 监听 ${this.options.host ?? '127.0.0.1'}:${this.options.port}`);
-                resolve();
-            });
+            const host = this.options.host ?? '127.0.0.1';
+            const tryListen = (port) => {
+                this.server = http.createServer((req, res) => this.handleRequest(req, res));
+                this.server.on('error', (err) => {
+                    if (err.code === 'EADDRINUSE' && port !== 0) {
+                        this.log(`端口 ${port} 被占用，尝试自动分配...`, 'warn');
+                        this.server = null;
+                        tryListen(0);
+                    }
+                    else {
+                        this.log(`ConfigServer 错误: ${err.message}`, 'error');
+                        reject(err);
+                    }
+                });
+                this.server.listen(port, host, () => {
+                    this._actualPort = this.server.address().port;
+                    if (this._actualPort !== this.options.port) {
+                        this.log(`端口 ${this.options.port} 被占用，ConfigServer 自动分配到 ${this._actualPort}`, 'warn');
+                    }
+                    this.log(`ConfigServer 监听 ${host}:${this._actualPort}`);
+                    resolve();
+                });
+            };
+            tryListen(this.options.port);
         });
     }
     stop() {
@@ -46,6 +64,10 @@ export class ConfigServer {
     }
     async handleRequest(req, res) {
         const url = req.url ?? '/';
+        // 安全响应头
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('Cache-Control', 'no-store');
         try {
             if (req.method === 'GET' && url === '/') {
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -53,14 +75,29 @@ export class ConfigServer {
                 return;
             }
             if (req.method === 'GET' && url === '/api/config') {
-                const config = loadConfig(this.options.projectRoot);
+                const config = loadConfig();
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify(config));
                 return;
             }
             if (req.method === 'POST' && url === '/api/config') {
                 const body = await readBody(req);
-                const newConfig = JSON.parse(body);
+                let parsed;
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: '无效的 JSON' }));
+                    return;
+                }
+                const validation = validateConfigPayload(parsed);
+                if (!validation.ok) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: validation.error }));
+                    return;
+                }
+                const newConfig = validation.config;
                 // 端口冲突校验
                 const ports = [newConfig.wsPort, newConfig.devServerPort, newConfig.configPort];
                 if (new Set(ports).size !== ports.length) {
@@ -68,7 +105,7 @@ export class ConfigServer {
                     res.end(JSON.stringify({ ok: false, error: 'wsPort, devServerPort, configPort 不能重复' }));
                     return;
                 }
-                const filePath = configFilePath(this.options.projectRoot);
+                const filePath = configFilePath();
                 saveConfig(filePath, newConfig);
                 this.log('配置已保存');
                 res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -88,6 +125,44 @@ export class ConfigServer {
                 }
                 return;
             }
+            // Addon 配置读取
+            if (req.method === 'GET' && url.startsWith('/api/addon-config')) {
+                const params = new URL(url, 'http://localhost').searchParams;
+                const name = params.get('name');
+                if (!name) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: '缺少 name 参数' }));
+                    return;
+                }
+                const addonConfig = loadAddonConfig(name);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, name, config: addonConfig ?? {} }));
+                return;
+            }
+            // Addon 配置保存
+            if (req.method === 'POST' && url === '/api/addon-config') {
+                const body = await readBody(req);
+                let parsed;
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: '无效的 JSON' }));
+                    return;
+                }
+                const payload = parsed;
+                if (!payload.name || typeof payload.name !== 'string' || typeof payload.config !== 'object' || !payload.config) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: '需要 name (string) 和 config (object) 字段' }));
+                    return;
+                }
+                saveAddonConfig(payload.name, payload.config);
+                this.log(`addon ${payload.name} 配置已保存`);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+                return;
+            }
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Not found' }));
         }
@@ -232,6 +307,77 @@ export class ConfigServer {
     <button class="primary" onclick="saveConfig()">保存配置</button>
     <button onclick="resetDefaults()">恢复默认值</button>
   </div>
+
+  <h1 style="margin-top:40px;">增强项目配置</h1>
+  <p class="subtitle">配置存储于 ~/.remnote-bridge/addons/&lt;name&gt;/config.json</p>
+
+  <div class="card">
+    <h2>remnote-rag（语义搜索增强）</h2>
+    <h3 style="font-size:14px;margin-bottom:12px;color:#555;">Embedding 配置</h3>
+    <div class="field">
+      <label>API Key</label>
+      <input type="password" id="rag-embedding-api-key">
+    </div>
+    <div class="field">
+      <label>API Key 环境变量名</label>
+      <input type="text" id="rag-embedding-api-key-env" placeholder="留空则使用上方 api_key">
+    </div>
+    <div class="field">
+      <label>Base URL</label>
+      <input type="text" id="rag-embedding-base-url">
+    </div>
+    <div class="field">
+      <label>Model</label>
+      <input type="text" id="rag-embedding-model">
+    </div>
+    <div class="field">
+      <label>Dimensions</label>
+      <input type="number" id="rag-embedding-dimensions" min="1">
+    </div>
+
+    <h3 style="font-size:14px;margin:16px 0 12px;color:#555;">Reranker 配置</h3>
+    <div class="field">
+      <label>启用 Reranker</label>
+      <select id="rag-reranker-enabled">
+        <option value="true">是</option>
+        <option value="false">否</option>
+      </select>
+    </div>
+    <div class="field">
+      <label>API Key</label>
+      <input type="password" id="rag-reranker-api-key">
+    </div>
+    <div class="field">
+      <label>API Key 环境变量名</label>
+      <input type="text" id="rag-reranker-api-key-env" placeholder="留空则使用 Embedding API Key">
+    </div>
+    <div class="field">
+      <label>Base URL</label>
+      <input type="text" id="rag-reranker-base-url">
+    </div>
+    <div class="field">
+      <label>Model</label>
+      <input type="text" id="rag-reranker-model">
+    </div>
+    <div class="field">
+      <label>Top-K 倍数</label>
+      <input type="number" id="rag-reranker-top-k-multiplier" min="1">
+    </div>
+
+    <h3 style="font-size:14px;margin:16px 0 12px;color:#555;">通用配置</h3>
+    <div class="field">
+      <label>最小文本长度 (min_text_length)</label>
+      <input type="number" id="rag-min-text-length" min="1">
+    </div>
+    <div class="field">
+      <label>批量大小 (batch_size)</label>
+      <input type="number" id="rag-batch-size" min="1">
+    </div>
+
+    <div class="actions" style="margin-top:16px;">
+      <button class="primary" onclick="saveAddonConfigUI()">保存 addon 配置</button>
+    </div>
+  </div>
 </div>
 
 <div class="toast" id="toast"></div>
@@ -347,17 +493,137 @@ function resetDefaults() {
   }
 }
 
+// ── Addon 配置 ──
+
+const RAG_FIELD_MAP = {
+  'rag-embedding-api-key': ['embedding', 'api_key'],
+  'rag-embedding-api-key-env': ['embedding', 'api_key_env'],
+  'rag-embedding-base-url': ['embedding', 'base_url'],
+  'rag-embedding-model': ['embedding', 'model'],
+  'rag-embedding-dimensions': ['embedding', 'dimensions'],
+  'rag-reranker-enabled': ['reranker', 'enabled'],
+  'rag-reranker-api-key': ['reranker', 'api_key'],
+  'rag-reranker-api-key-env': ['reranker', 'api_key_env'],
+  'rag-reranker-base-url': ['reranker', 'base_url'],
+  'rag-reranker-model': ['reranker', 'model'],
+  'rag-reranker-top-k-multiplier': ['reranker', 'top_k_multiplier'],
+  'rag-min-text-length': [null, 'min_text_length'],
+  'rag-batch-size': [null, 'batch_size'],
+};
+
+function fillAddonForm(config) {
+  for (const [elId, path] of Object.entries(RAG_FIELD_MAP)) {
+    const el = document.getElementById(elId);
+    if (!el) continue;
+    const val = path[0] ? (config[path[0]] || {})[path[1]] : config[path[1]];
+    if (val !== undefined && val !== null) {
+      el.value = el.tagName === 'SELECT' ? String(val) : val;
+    }
+  }
+}
+
+function readAddonForm() {
+  const config = { embedding: {}, reranker: {} };
+  for (const [elId, path] of Object.entries(RAG_FIELD_MAP)) {
+    const el = document.getElementById(elId);
+    if (!el) continue;
+    let val = el.value;
+    if (elId.includes('dimensions') || elId.includes('multiplier') || elId.includes('text-length') || elId.includes('batch-size')) {
+      val = Number(val);
+    } else if (elId.includes('enabled')) {
+      val = val === 'true';
+    }
+    if (path[0]) {
+      config[path[0]][path[1]] = val;
+    } else {
+      config[path[1]] = val;
+    }
+  }
+  return config;
+}
+
+async function loadAddonConfigUI() {
+  try {
+    const res = await fetch('/api/addon-config?name=remnote-rag');
+    const data = await res.json();
+    if (data.ok) fillAddonForm(data.config);
+  } catch (e) { /* addon 可能未配置 */ }
+}
+
+async function saveAddonConfigUI() {
+  const config = readAddonForm();
+  try {
+    const res = await fetch('/api/addon-config', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'remnote-rag', config }),
+    });
+    const result = await res.json();
+    if (result.ok) showToast('addon 配置已保存', 'success');
+    else showToast('保存失败: ' + result.error, 'error');
+  } catch (e) {
+    showToast('保存请求失败: ' + e, 'error');
+  }
+}
+
 loadConfig();
+loadAddonConfigUI();
 </script>
 </body>
 </html>`;
     }
 }
+const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on('data', (chunk) => chunks.push(chunk));
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                req.destroy();
+                reject(new Error('请求体超过大小限制 (1 MB)'));
+                return;
+            }
+            chunks.push(chunk);
+        });
         req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
         req.on('error', reject);
     });
 }
+function isValidPort(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 65535;
+}
+function validateConfigPayload(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { ok: false, error: '配置必须是对象' };
+    }
+    const obj = raw;
+    if (!isValidPort(obj.wsPort))
+        return { ok: false, error: 'wsPort 必须为有效端口号 (1-65535)' };
+    if (!isValidPort(obj.devServerPort))
+        return { ok: false, error: 'devServerPort 必须为有效端口号 (1-65535)' };
+    if (!isValidPort(obj.configPort))
+        return { ok: false, error: 'configPort 必须为有效端口号 (1-65535)' };
+    if (typeof obj.daemonTimeoutMinutes !== 'number' || obj.daemonTimeoutMinutes <= 0) {
+        return { ok: false, error: 'daemonTimeoutMinutes 必须为正数' };
+    }
+    if (obj.defaults !== undefined) {
+        if (typeof obj.defaults !== 'object' || obj.defaults === null || Array.isArray(obj.defaults)) {
+            return { ok: false, error: 'defaults 必须是对象' };
+        }
+    }
+    return {
+        ok: true,
+        config: {
+            wsPort: obj.wsPort,
+            devServerPort: obj.devServerPort,
+            configPort: obj.configPort,
+            daemonTimeoutMinutes: obj.daemonTimeoutMinutes,
+            defaults: obj.defaults
+                ? { ...DEFAULT_DEFAULTS, ...obj.defaults }
+                : { ...DEFAULT_DEFAULTS },
+            addons: obj.addons, // 仅保留 enabled 状态
+        },
+    };
+}

package/dist/cli/server/ws-server.js

@@ -10,7 +10,7 @@
  * 业务编排逻辑在 handlers/ 中，本文件只做连接管理和请求分发。
  */
 import { WebSocketServer, WebSocket } from 'ws';
-import { isHelloMessage, isPongMessage, isBridgeRequest, isBridgeResponse } from '../protocol.js';
+import { isHelloMessage, isPongMessage, isBridgeRequest, isBridgeResponse, WS_CLOSE_OTHER_CONNECTED, WS_CLOSE_PONG_TIMEOUT, WS_CLOSE_PREEMPTED, WS_CLOSE_TWIN_EXISTS, } from '../protocol.js';
 import { DEFAULT_DEFAULTS } from '../config.js';
 import { RemCache } from '../handlers/rem-cache.js';
 import { ReadHandler } from '../handlers/read-handler.js';
@@ -23,9 +23,12 @@ import crypto from 'crypto';
 const PLUGIN_REQUEST_TIMEOUT_MS = 15_000;
 export class BridgeServer {
     wss = null;
+    _actualPort = 0;
     pluginSocket = null;
     pluginVersion = null;
     pluginSdkReady = false;
+    pluginIsTwin = false;
+    slotIndex;
     pingTimer = null;
     pongTimer = null;
     startTime = Date.now();
@@ -39,9 +42,12 @@ export class BridgeServer {
     contextReadHandler;
     defaults;
     config;
+    /** 实际监听的端口（可能与 config.port 不同，若原端口被占用则 OS 自动分配） */
+    get actualPort() { return this._actualPort; }
     /** 每当收到 CLI 命令请求时触发（用于刷新守护进程超时计时器） */
     onCliRequest;
     constructor(config) {
+        this.slotIndex = config.slotIndex;
         this.config = {
             port: config.port,
             host: config.host ?? '127.0.0.1',
@@ -73,23 +79,36 @@ export class BridgeServer {
     start() {
         return new Promise((resolve, reject) => {
             this.startTime = Date.now();
-            this.wss = new WebSocketServer({
-                port: this.config.port,
-                host: this.config.host,
-                maxPayload: 1 * 1024 * 1024, // 1MB，足够所有 JSON 消息
-            });
-            this.wss.on('listening', () => {
-                this.log(`WS Server 监听 ${this.config.host}:${this.config.port}`);
-                this.startPingInterval();
-                resolve();
-            });
-            this.wss.on('error', (err) => {
-                this.log(`WS Server 错误: ${err.message}`, 'error');
-                reject(err);
-            });
-            this.wss.on('connection', (ws) => {
-                this.handleConnection(ws);
-            });
+            const tryListen = (port) => {
+                this.wss = new WebSocketServer({
+                    port,
+                    host: this.config.host,
+                    maxPayload: 1 * 1024 * 1024, // 1MB，足够所有 JSON 消息
+                });
+                this.wss.on('listening', () => {
+                    this._actualPort = this.wss.address().port;
+                    if (this._actualPort !== this.config.port) {
+                        this.log(`端口 ${this.config.port} 被占用，WS Server 自动分配到 ${this._actualPort}`, 'warn');
+                    }
+                    this.log(`WS Server 监听 ${this.config.host}:${this._actualPort}`);
+                    this.startPingInterval();
+                    resolve();
+                });
+                this.wss.on('error', (err) => {
+                    if (err.code === 'EADDRINUSE' && port !== 0) {
+                        this.log(`端口 ${port} 被占用，尝试自动分配...`, 'warn');
+                        tryListen(0);
+                    }
+                    else {
+                        this.log(`WS Server 错误: ${err.message}`, 'error');
+                        reject(err);
+                    }
+                });
+                this.wss.on('connection', (ws) => {
+                    this.handleConnection(ws);
+                });
+            };
+            tryListen(this.config.port);
         });
     }
     /**
@@ -161,37 +180,69 @@ export class BridgeServer {
         ws.on('close', () => {
             if (ws === this.pluginSocket) {
                 this.log('Plugin 已断开', 'warn');
-                this.pluginSocket = null;
-                this.pluginVersion = null;
-                this.pluginSdkReady = false;
-                // 清理可能残留的 pong 超时定时器
-                if (this.pongTimer) {
-                    clearTimeout(this.pongTimer);
-                    this.pongTimer = null;
-                }
-                // 拒绝所有等待中的 Plugin 子请求
-                for (const [id, pending] of this.pendingPluginRequests) {
-                    clearTimeout(pending.timer);
-                    pending.reject(new Error('Plugin 已断开'));
-                    this.pendingPluginRequests.delete(id);
-                }
+                this.clearPluginState();
             }
         });
         ws.on('error', (err) => {
             this.log(`连接错误: ${err.message}`, 'error');
         });
     }
+    /** 重置 Plugin 连接状态（onclose 和 pong 超时共用） */
+    clearPluginState() {
+        this.pluginSocket = null;
+        this.pluginVersion = null;
+        this.pluginSdkReady = false;
+        this.pluginIsTwin = false;
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        for (const [id, pending] of this.pendingPluginRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Plugin 已断开'));
+            this.pendingPluginRequests.delete(id);
+        }
+    }
     handlePluginHello(ws, hello) {
-        if (this.pluginSocket && this.pluginSocket.readyState === WebSocket.OPEN) {
-            // 已有 Plugin 连接，拒绝新连接
-            this.log(`拒绝 Plugin 连接（已有连接）`, 'warn');
-            ws.close(4000, 'Another plugin is already connected');
+        const isTwin = (hello.twinSlotIndex === this.slotIndex);
+        if (!this.pluginSocket || this.pluginSocket.readyState !== WebSocket.OPEN) {
+            // 无现有连接 → 接受
+            this.pluginSocket = ws;
+            this.pluginVersion = hello.version;
+            this.pluginSdkReady = hello.sdkReady ?? false;
+            this.pluginIsTwin = isTwin;
+            this.log(`Plugin 已连接 (v${hello.version}, SDK: ${this.pluginSdkReady ? '就绪' : '未就绪'}, ${isTwin ? '孪生' : '非孪生'})`);
             return;
         }
-        this.pluginSocket = ws;
-        this.pluginVersion = hello.version;
-        this.pluginSdkReady = hello.sdkReady ?? false;
-        this.log(`Plugin 已连接 (v${hello.version}, SDK: ${this.pluginSdkReady ? '就绪' : '未就绪'})`);
+        // 有现有连接且存活
+        if (isTwin) {
+            // 孪生来了 → 抢占现有非孪生连接
+            this.log(`孪生 Plugin 连接，抢占当前${this.pluginIsTwin ? '孪生' : '非孪生'}连接`, 'warn');
+            const preempted = { type: 'preempted', reason: 'twin_plugin_connected' };
+            try {
+                this.pluginSocket.send(JSON.stringify(preempted));
+            }
+            catch { /* 发送失败无碍 */ }
+            this.pluginSocket.close(WS_CLOSE_PREEMPTED, 'Preempted by twin plugin');
+            // 接受新孪生连接
+            this.pluginSocket = ws;
+            this.pluginVersion = hello.version;
+            this.pluginSdkReady = hello.sdkReady ?? false;
+            this.pluginIsTwin = true;
+            this.log(`孪生 Plugin 已接管 (v${hello.version})`);
+            return;
+        }
+        // 非孪生来了
+        if (this.pluginIsTwin) {
+            // 已有孪生 → 拒绝
+            this.log(`拒绝非孪生 Plugin 连接（孪生 Plugin 已连接）`, 'warn');
+            ws.close(WS_CLOSE_TWIN_EXISTS, 'Twin plugin is connected');
+        }
+        else {
+            // 已有非孪生 → 拒绝
+            this.log(`拒绝 Plugin 连接（已有连接）`, 'warn');
+            ws.close(WS_CLOSE_OTHER_CONNECTED, 'Another plugin is already connected');
+        }
     }
     async handleCliRequest(ws, request) {
         // 通知守护进程刷新超时计时器
@@ -361,10 +412,8 @@ export class BridgeServer {
                 this.pluginSocket.send(JSON.stringify({ type: 'ping' }));
                 this.pongTimer = setTimeout(() => {
                     this.log('Plugin 心跳超时，断开连接', 'warn');
-                    this.pluginSocket?.close(4001, 'Pong timeout');
-                    this.pluginSocket = null;
-                    this.pluginVersion = null;
-                    this.pluginSdkReady = false;
+                    this.pluginSocket?.close(WS_CLOSE_PONG_TIMEOUT, 'Pong timeout');
+                    this.clearPluginState();
                 }, this.config.pongTimeoutMs);
             }
         }, this.config.pingIntervalMs);

package/dist/cli/utils/output.js

@@ -3,6 +3,7 @@
  *
  * 统一 JSON 输出格式，自动注入 timestamp 字段。
  */
+import { DaemonNotRunningError, DaemonUnreachableError } from '../daemon/send-request.js';
 /**
  * 输出 JSON 到 stdout，自动追加 ISO 8601 时间戳。
  *
@@ -11,3 +12,31 @@
 export function jsonOutput(data) {
     console.log(JSON.stringify({ ...data, timestamp: new Date().toISOString() }));
 }
+/**
+ * 命令层统一错误处理。
+ *
+ * - DaemonNotRunningError / DaemonUnreachableError → exitCode 2
+ * - 其他错误 → exitCode 1
+ *
+ * 返回 void，调用方在 catch 中直接 `handleCommandError(err, cmd, json); return;` 即可。
+ */
+export function handleCommandError(err, command, json) {
+    if (err instanceof DaemonNotRunningError || err instanceof DaemonUnreachableError) {
+        if (json) {
+            jsonOutput({ ok: false, command, error: err.message });
+        }
+        else {
+            console.error(`错误: ${err.message}`);
+        }
+        process.exitCode = 2;
+        return;
+    }
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    if (json) {
+        jsonOutput({ ok: false, command, error: errorMsg });
+    }
+    else {
+        console.error(`错误: ${errorMsg}`);
+    }
+    process.exitCode = 1;
+}

package/dist/mcp/format.js

@@ -0,0 +1,43 @@
+/**
+ * MCP 返回值格式化工具
+ *
+ * 两种模式：
+ * - formatFrontmatter：YAML frontmatter + body（read 类工具）
+ * - formatDataJson：剥离 wrapper 的 JSON（action/infra 工具）
+ */
+// ---------------------------------------------------------------------------
+// 模式 A：Frontmatter + Body
+// ---------------------------------------------------------------------------
+/**
+ * 将元数据序列化为 YAML frontmatter，拼接 body 内容。
+ *
+ * - null/undefined 的值自动跳过
+ * - 数字/布尔：裸值（`nodeCount: 42`）
+ * - 字符串：JSON 引号（`mode: "focus"`）
+ * - 数组/对象：JSON 内联（`ancestors: [{"id":"x"}]`）
+ * - 无元数据时省略 `---` 分隔符，直接返回 body
+ */
+export function formatFrontmatter(meta, body) {
+    const entries = Object.entries(meta).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0)
+        return body;
+    const lines = entries.map(([k, v]) => {
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return `${k}: ${v}`;
+        return `${k}: ${JSON.stringify(v)}`;
+    });
+    return `---\n${lines.join('\n')}\n---\n\n${body}`;
+}
+// ---------------------------------------------------------------------------
+// 模式 B：Data JSON（剥离 ok/command/timestamp wrapper）
+// ---------------------------------------------------------------------------
+/**
+ * 从 CLI 响应中剥离 ok/command/timestamp，返回剩余字段的 JSON。
+ *
+ * 用于 action/infra 工具——AI 不需要看到冗余的 wrapper 字段。
+ * callCli 已在 ok===false 时抛出 CliError，成功路径 ok 始终为 true。
+ */
+export function formatDataJson(response) {
+    const { ok: _ok, command: _cmd, timestamp: _ts, ...rest } = response;
+    return JSON.stringify(rest, null, 2);
+}