ppxans-harness 2.4.0

package/src/mcp/client.js

@@ -0,0 +1,375 @@
+// src/mcp/client.js - MCP (Model Context Protocol) 客户端 (零依赖)
+// 传输可插拔: stdio (本机 npx/uvx 服务器) + HTTP (Streamable HTTP, 远程托管服务器)。
+// 协议: JSON-RPC 2.0 (换行分隔 JSON / HTTP body)。协议版本 2024-11-05 (stdio) / 2025-03-26 (HTTP)。
+// 能力: initialize 握手 / tools/list / tools/call / resources/list / resources/read。
+// 可靠性: 请求超时 + 断连时拒绝所有 pending 请求 (不再永久挂起)。
+import { spawn, spawnSync } from "node:child_process";
+import { warn } from "../utils/logger.js";
+
+const PROTOCOL_VERSION = "2024-11-05";      // stdio 本地服务器广泛兼容的版本
+const HTTP_PROTOCOL_VERSION = "2025-03-26"; // Streamable HTTP 传输对应的协议版本
+const DEFAULT_TIMEOUT = 60000;              // 单请求默认超时 (ms)
+const MAX_STDIO_BUF = 1024 * 1024;          // stdout 缓冲上限: 防恶意/异常服务器发超长行耗尽内存 (v1.0.8)
+
+// ---- SSE (Server-Sent Events) 解析 ----
+// Streamable HTTP 服务器可用 text/event-stream 响应。抽 event -> data 里的 JSON-RPC 消息。
+export function parseSSE(text) {
+  const out = [];
+  const events = String(text).split(/\r?\n\r?\n/);
+  for (const ev of events) {
+    let name = "message";
+    const data = [];
+    for (const line of ev.split(/\r?\n/)) {
+      if (!line || line.startsWith(":")) continue;
+      if (line.startsWith("event:")) name = line.slice(6).trim();
+      else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
+    }
+    if (!data.length) continue;
+    if (name !== "message" && name !== "endpoint") continue;
+    const payload = data.join("\n").trim();
+    if (!payload) continue;
+    try {
+      const j = JSON.parse(payload);
+      if (Array.isArray(j)) out.push(...j);
+      else out.push(j);
+    } catch { /* 忽略非 JSON 负载 */ }
+  }
+  return out;
+}
+
+// 解析 HTTP 响应体 -> JSON-RPC 消息数组 (SSE 或 JSON 单条/批量)
+function parseHttpBody(text, contentType) {
+  const ct = (contentType || "").split(";")[0].trim().toLowerCase();
+  const trimmed = text.trim();
+  if (ct === "text/event-stream" || /^(event|data):/m.test(trimmed)) {
+    return parseSSE(trimmed);
+  }
+  try {
+    const j = JSON.parse(trimmed);
+    return Array.isArray(j) ? j : [j];
+  } catch { return []; }
+}
+
+// ---- stdio 传输 ----
+// 启动本地服务器子进程, 从 stdout 读换行分隔 JSON, 请求写 stdin。
+class StdioTransport {
+  constructor({ command, args = [], env = {}, cwd = null }) {
+    this.command = command;
+    this.args = args;
+    this.env = env;
+    this.cwd = cwd;
+    this.proc = null;
+    this._buf = "";
+    this._spawned = false;
+  }
+
+  start() {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(this.command, this.args, {
+        cwd: this.cwd || undefined,
+        env: { ...process.env, ...this.env },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      this.proc = proc;
+      proc.stdout.setEncoding("utf8");
+      proc.stdout.on("data", (chunk) => this._onData(chunk));
+      proc.stderr.on("data", (d) => warn(`[mcp] ${this.command} stderr: ${String(d).slice(0, 300)}`));
+      // v1.0.8: stdin error 监听 (子进程退出后 write 触发 EPIPE 会 unhandled 崩溃)
+      if (proc.stdin) proc.stdin.on("error", (e) => warn(`[mcp] ${this.command} stdin: ${e.message}`));
+      proc.once("spawn", () => { this._spawned = true; resolve(); });
+      proc.once("error", (e) => {
+        if (!this._spawned) reject(new Error(`无法启动 MCP 服务器 ${this.command}: ${e.message}`));
+        else this.onClose?.(e);
+      });
+      proc.on("exit", (code) => {
+        if (this._spawned) this.onClose?.(new Error(`MCP 服务器进程退出 (code ${code})`));
+      });
+    });
+  }
+
+  send(msg) {
+    if (!this.proc || !this.proc.stdin || this.proc.killed) {
+      throw new Error("MCP 服务器未连接");
+    }
+    try {
+      this.proc.stdin.write(JSON.stringify(msg) + "\n");
+    } catch (e) {
+      throw new Error(`MCP 写入失败: ${e.message}`);
+    }
+  }
+
+  close() {
+    if (this.proc) {
+      const pid = this.proc.pid;
+      // v1.0.8: 杀进程树 (npx/uvx 会派生子进程, 只 kill 直接子进程会泄漏)
+      if (process.platform === "win32") {
+        try { spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", timeout: 5000 }); } catch {}
+      } else {
+        try { process.kill(-pid, "SIGTERM"); } catch {} // 负 pid = 整个进程组
+      }
+      try { this.proc.kill(); } catch {}
+    }
+    this.proc = null;
+  }
+
+  _onData(chunk) {
+    this._buf += chunk;
+    // v1.0.8: 缓冲上限保护 (防内存耗尽)
+    if (this._buf.length > MAX_STDIO_BUF) {
+      warn(`[mcp] ${this.command} stdout 缓冲超限 (${MAX_STDIO_BUF}), 丢弃多余数据`);
+      this._buf = this._buf.slice(-4096);
+    }
+    let idx;
+    while ((idx = this._buf.indexOf("\n")) !== -1) {
+      const line = this._buf.slice(0, idx).trim();
+      this._buf = this._buf.slice(idx + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      this.onMessage?.(msg);
+    }
+  }
+}
+
+// ---- HTTP 传输 (Streamable HTTP) ----
+// 每次请求 POST 到 url, 响应可为 JSON 或 SSE; 维护 Mcp-Session-Id 会话头。
+class HttpTransport {
+  constructor({ url, headers = {}, timeout = DEFAULT_TIMEOUT }) {
+    this.url = url;
+    this.headers = headers;
+    this.timeout = timeout;
+    this.sessionId = null;
+    this.closed = false;
+  }
+
+  async start() { /* 单次 POST 流即可, 无需预开连接 */ }
+
+  async send(msg) {
+    const headers = {
+      "content-type": "application/json",
+      "accept": "application/json, text/event-stream",
+      ...this.headers,
+    };
+    if (this.sessionId) headers["mcp-session-id"] = this.sessionId;
+
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeout);
+    timer.unref?.(); // 不阻塞事件循环退出
+
+    let res;
+    try {
+      res = await fetch(this.url, { method: "POST", headers, body: JSON.stringify(msg), signal: ctrl.signal });
+    } catch (e) {
+      const err = e.name === "AbortError"
+        ? new Error(`MCP HTTP 请求超时 (${this.timeout}ms)`)
+        : new Error(`MCP HTTP 请求失败: ${e.message}`);
+      this._error(msg, err);
+      return;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const sid = res.headers.get("mcp-session-id");
+    if (sid) this.sessionId = sid;
+
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      this._error(msg, new Error(`MCP HTTP ${res.status}: ${t.slice(0, 200)}`));
+      return;
+    }
+    const text = await res.text();
+    if (!text) return; // 202/204 空响应 (通知), 无需分发
+    for (const m of parseHttpBody(text, res.headers.get("content-type") || "")) {
+      this.onMessage?.(m);
+    }
+  }
+
+  _error(msg, e) {
+    if (msg && msg.id != null) {
+      this.onMessage?.({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: e.message } });
+    } else {
+      warn(`[mcp] HTTP 通知失败: ${e.message}`);
+    }
+  }
+
+  close() { this.closed = true; }
+}
+
+// ---- MCP 客户端核心 (传输无关) ----
+export class McpClient {
+  constructor(config = {}) {
+    this.config = config;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    const isHttp = Boolean(config.url) || config.transport === "http";
+    if (isHttp) {
+      if (!config.url) throw new Error("HTTP MCP 服务器需 url");
+      this.transport = new HttpTransport(config);
+      this.protocolVersion = config.protocolVersion || HTTP_PROTOCOL_VERSION;
+    } else {
+      if (!config.command) throw new Error("stdio MCP 服务器需 command");
+      this.transport = new StdioTransport(config);
+      this.protocolVersion = config.protocolVersion || PROTOCOL_VERSION;
+    }
+    this._pending = new Map(); // id -> { resolve, reject, timer }
+    this._nextId = 0;
+    this._dead = false;
+    this.capabilities = {}; // initialize 握手后填充
+    this.transport.onMessage = (m) => this._onMessage(m);
+    this.transport.onClose = (e) => this._failAll(e || new Error("MCP 连接已断开"));
+  }
+
+  // 启动 + initialize 握手 + initialized 通知
+  async connect() {
+    await this.transport.start();
+    const init = await this._request("initialize", {
+      protocolVersion: this.protocolVersion,
+      capabilities: {},
+      clientInfo: { name: "ppx-agent", version: "0.1.0" },
+    });
+    if (init && init.protocolVersion) this.protocolVersion = init.protocolVersion;
+    this.capabilities = (init && init.capabilities) || {};
+    await this._notify("notifications/initialized", {});
+    return this;
+  }
+
+  async listTools() {
+    const r = await this._request("tools/list", {});
+    return (r && r.tools) || [];
+  }
+
+  // 调用工具 -> 提取纯文本结果 (向后兼容)
+  async callTool(name, args = {}) {
+    return extractToolText(await this.callToolRaw(name, args));
+  }
+
+  // 调用工具 -> 返回原始 result (含 content/isError, 供上层判断)
+  async callToolRaw(name, args = {}) {
+    return this._request("tools/call", { name, arguments: args });
+  }
+
+  async listResources() {
+    const r = await this._request("resources/list", {});
+    return (r && r.resources) || [];
+  }
+
+  async readResource(uri) {
+    return this._request("resources/read", { uri });
+  }
+
+  async listPrompts() {
+    const r = await this._request("prompts/list", {});
+    return (r && r.prompts) || [];
+  }
+
+  // 获取提示模板并填充参数 -> 返回消息数组 [{ role, content }]
+  async getPrompt(name, args = {}) {
+    const r = await this._request("prompts/get", { name, arguments: args });
+    return (r && r.messages) || [];
+  }
+
+  close() {
+    if (this._dead) return;
+    this._dead = true;
+    this.transport.close?.();
+    this._failAll(new Error("MCP 连接已关闭"));
+  }
+
+  // ---- 内部 ----
+  _request(method, params = {}) {
+    if (this._dead) return Promise.reject(new Error("MCP 连接已关闭"));
+    const id = ++this._nextId;
+    const msg = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new Error(`MCP 请求超时 (${this.timeout}ms): ${method}`));
+      }, this.timeout);
+      this._pending.set(id, { resolve, reject, timer });
+      Promise.resolve()
+        .then(() => this.transport.send(msg))
+        .catch((e) => this._settle(id, null, e));
+    });
+  }
+
+  _notify(method, params = {}) {
+    if (this._dead) return Promise.resolve();
+    return Promise.resolve()
+      .then(() => this.transport.send({ jsonrpc: "2.0", method, params }))
+      .catch((e) => warn(`[mcp] 通知发送失败 ${method}: ${e.message}`));
+  }
+
+  _onMessage(msg) {
+    if (!msg || msg.id == null) return; // 忽略服务器通知/无 id 消息
+    const p = this._pending.get(msg.id);
+    if (!p) return;
+    if (msg.error) this._settle(msg.id, null, new Error(msg.error.message || "MCP 调用失败"));
+    else this._settle(msg.id, msg.result, null);
+  }
+
+  _settle(id, result, err) {
+    const p = this._pending.get(id);
+    if (!p) return;
+    this._pending.delete(id);
+    clearTimeout(p.timer);
+    err ? p.reject(err) : p.resolve(result);
+  }
+
+  _failAll(err) {
+    for (const [id, p] of [...this._pending]) {
+      clearTimeout(p.timer);
+      this._pending.delete(id);
+      p.reject(err);
+    }
+  }
+}
+
+// 提取 tools/call 结果的文本 (MCP 返回 content 数组, 每项 type=text 含 text)
+export function extractToolText(result) {
+  if (result == null) return "";
+  const content = result.content;
+  if (Array.isArray(content)) {
+    const texts = content
+      .filter((c) => c && c.type === "text" && typeof c.text === "string")
+      .map((c) => c.text);
+    if (texts.length) return texts.join("\n");
+    // 非文本内容 (image/resource) 回退为 JSON
+    return JSON.stringify(content);
+  }
+  if (typeof result === "string") return result;
+  return JSON.stringify(result);
+}
+
+// 提取 tools/call 结果的 { text, isError } (识别 MCP 工具级报错, 供自愈重试)
+export function extractToolResult(result) {  if (result == null) return { text: "", isError: false };
+  const content = result.content;
+  let isError = Boolean(result.isError);
+  if (Array.isArray(content)) {
+    const texts = [];
+    for (const c of content) {
+      if (!c) continue;
+      if (c.isError) isError = true;
+      if (c.type === "text" && typeof c.text === "string") texts.push(c.text);
+      else if (c.type === "image" || c.type === "resource" || c.type === "audio") {
+        texts.push(`[${c.type}: ${c.mimeType || c.uri || ""}]`);
+      }
+    }
+    if (texts.length) return { text: texts.join("\n"), isError };
+    return { text: JSON.stringify(content), isError };
+  }
+  if (typeof result === "string") return { text: result, isError };
+  return { text: JSON.stringify(result), isError };
+}
+
+// 提取 resources/read 结果的文本 (MCP 返回 { contents: [{ uri, mimeType, text }] })
+export function extractResourceText(result) {
+  if (result == null) return "";
+  const contents = result.contents;
+  if (Array.isArray(contents)) {
+    const texts = contents
+      .filter((c) => c && typeof c.text === "string")
+      .map((c) => `[${c.uri || "resource"}]\n${c.text}`);
+    return texts.join("\n\n") || JSON.stringify(contents);
+  }
+  if (typeof result === "string") return result;
+  return JSON.stringify(result);
+}

package/src/mcp/index.js

@@ -0,0 +1,116 @@
+// src/mcp/index.js - MCP 工具注册 (接入 MCP 工具生态)
+// 把 MCP 服务器的工具转换为皮皮虾 ToolCatalog 工具, 与内置工具同权。
+// servers: [
+//   { command, args, env, prefix }                         // stdio (本机)
+//   { url, headers, prefix, timeout }                      // HTTP Streamable (远程)
+// ]
+import { McpClient, extractToolResult, extractResourceText } from "./client.js";
+import { TOOL_ERROR_PREFIX } from "../tools/catalog.js";
+import { warn, info } from "../utils/logger.js";
+
+// v1.0.8: MCP 工具名清洗 (只留 \w.-, 截断) — 防恶意服务器注册非法工具名/注入
+export function sanitizeMcpName(name) {
+  return String(name || "").replace(/[^\w.-]/g, "_").slice(0, 64);
+}
+
+// P1⑦ (2026-09-15): MCP 命名空间隔离 —— 防工具名碰撞 (Hermes 生产数据: 51 工具服务器上
+//   幻觉工具名命中真实工具; cron job 本想调 kanban_list 结果执行了 list_goals)。
+//   强制 serverName__toolName 前缀 + 精确匹配短路。
+export function serverLabel(s) {
+  // 取服务器可读标识: 配置 name > 包名 (args 里 @scope/pkg 或 *.py) > command 首段 > url host
+  if (s && s.name) return sanitizeMcpName(s.name);
+  const fromArgs = (s && s.args || []).find((a) => /(?:^|\/)[@\w.-]+(?:@[\w.]+)?$/.test(a) && !a.startsWith("-"));
+  if (fromArgs) return sanitizeMcpName(fromArgs.split("/").pop());
+  if (s && s.command) return sanitizeMcpName(String(s.command).split(/[\\/\s]/).filter(Boolean).pop() || "mcp");
+  if (s && s.url) {
+    try {
+      const host = new URL(s.url).hostname.split(".").filter(Boolean);
+      // 取二级域: mcp.example.com → example; www.google.com → google
+      return sanitizeMcpName(host.length >= 2 ? host[host.length - 2] : host[0] || "mcp");
+    } catch {}
+  }
+  return "mcp";
+}
+
+export function namespacedMcpName(label, raw) {
+  const clean = sanitizeMcpName(raw);
+  return clean ? `${label}__${clean}` : label;
+}
+
+// v1.0.8: MCP 工具描述清洗 (单行化 + 截断) — 服务器描述直接进 LLM prompt, 防换行/长文本注入指令
+// P1⑦: 额外剔除危险 flag (--system/--dangerously 等命令行注入惯用手法)
+export function sanitizeMcpDescription(desc, name) {
+  let s = String(desc || "").replace(/\s+/g, " ").trim();
+  // 危险 flag 清洗: 描述里出现命令行注入惯用 flag 视为可疑, 剔除该片段
+  s = s.replace(/--(?:system|dangerously[-\w]*|yes|force|no[-\w]+|y)\b/g, "[flag]");
+  return s.slice(0, 200) || `MCP 工具: ${name}`;
+}
+
+// 连接所有 MCP 服务器, 列出工具并注册到 catalog。
+// 除 tools 外, 服务器声明 resources/prompts 能力时, 额外注册对应读写工具 (P2⑥)。
+// 返回 { count, clients, close } — close() 关闭全部连接 (调用方负责生命周期)
+export async function registerMcpTools(catalog, servers = []) {
+  const clients = [];
+  let count = 0;
+  for (const s of servers) {
+    if (!s) { warn("[mcp] 跳过无效服务器配置"); continue; }
+    if (!s.command && !s.url) { warn("[mcp] 跳过无效服务器配置 (缺 command/url)"); continue; }
+    const client = new McpClient(s);
+    try {
+      await client.connect();
+      const tools = await client.listTools();
+      // P1⑦: 命名空间强制前缀 (serverLabel) —— 默认开启, 可显式 prefix 覆盖/关闭
+      const label = serverLabel(s);
+      const ns = s.prefix != null ? s.prefix : `${label}__`;
+      for (const t of tools) {
+        if (!t || !t.name) continue;
+        const name = ns + sanitizeMcpName(t.name);
+        // P1⑦: 精确匹配短路 —— 注册时登记原始名 (供幻觉工具名防御: 无前缀名永不执行)
+        catalog.register({
+          name,
+          description: sanitizeMcpDescription(t.description, t.name),
+          parameters: t.inputSchema || { type: "object", properties: {} },
+          category: "mcp",
+          // isError 时加错误前缀, 让皮皮虾的自愈重试语义对 MCP 工具同样生效
+          execute: async (args) => {
+            const raw = await client.callToolRaw(t.name, args || {});
+            const { text, isError } = extractToolResult(raw);
+            return isError ? `${TOOL_ERROR_PREFIX} MCP 工具 ${t.name}: ${text}` : text;
+          },
+        });
+        count += 1;
+      }
+      count += registerResourceTools(catalog, client, s, ns);
+      clients.push(client);
+    } catch (e) {
+      warn(`[mcp] 服务器 ${s.command || s.url} 连接失败: ${e.message}`);
+      client.close();
+    }
+  }
+  if (count) info(`[mcp] 已注册 ${count} 个 MCP 工具`);
+  return { count, clients, close: () => clients.forEach((c) => c.close()) };
+}
+
+// 服务器声明 resources 能力时, 注册 list_resources / read_resource 两个工具 (让 LLM 可读远程资源)
+function registerResourceTools(catalog, client, s, ns = "") {
+  if (!client.capabilities?.resources) return 0;
+  const label = s.command || s.url || "MCP";
+  catalog.register({
+    name: ns + "list_resources",
+    description: `列出 MCP 服务器 ${label} 提供的资源 (URI 列表)`,
+    parameters: { type: "object", properties: {}, required: [] },
+    category: "mcp",
+    execute: async () => {
+      const res = await client.listResources();
+      return res.map((r) => `${r.uri || "?"}${r.name ? ` — ${r.name}` : ""}`).join("\n") || "(无资源)";
+    },
+  });
+  catalog.register({
+    name: ns + "read_resource",
+    description: `读取 MCP 服务器 ${label} 的资源内容 (按 uri)`,
+    parameters: { type: "object", properties: { uri: { type: "string", description: "资源 URI" } }, required: ["uri"] },
+    category: "mcp",
+    execute: async (args) => extractResourceText(await client.readResource((args || {}).uri)),
+  });
+  return 2;
+}

package/src/memory/asset-hub.js

@@ -0,0 +1,131 @@
+// src/memory/asset-hub.js - 记忆资产中枢 (P3⑩)
+// 吸收 TencentDB-Agent-Memory 的"记忆资产 (Memory Asset) / 装备 (Loadout)"设计思想 (仅思想, 无源码复制):
+//   - 资产: 可管理的知识单元 (文档库 / 技能 / 经验), 有 owner / visibility / 版本 / 用途计数
+//   - 装备 (loadout): 绑定到某 agent 的资产集合, 检索时只注入已装备的资产
+//   - 检索隔离: 私有资产仅 owner 可检索; 团队资产共享 (简化: 全局可见)
+// 皮皮虾自研实现, 构建在现有 facts (带 scope) 之上: 资产 = 一组带 scope 的 facts + 元数据登记。
+// 纯代码可测, 无 LLM。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir, writeText, readText } from "../utils/store.js";
+
+export const VISIBILITY = { PRIVATE: "private", TEAM: "team" };
+
+// 规范化可见性输入: "team"/"TEAM"/VISIBILITY.TEAM 都归一到 "team"; 其余默认 private
+function normalizeVisibility(v) {
+  const s = String(v || "").toLowerCase();
+  return s === VISIBILITY.TEAM ? VISIBILITY.TEAM : VISIBILITY.PRIVATE;
+}
+
+export class AssetHub {
+  constructor(dataDir) {
+    this.dir = path.join(dataDir, "memory", "assets");
+    ensureDir(this.dir);
+    this.file = path.join(this.dir, "registry.json");
+    this._assets = this._load();
+  }
+
+  _load() {
+    try {
+      if (fs.existsSync(this.file)) {
+        const d = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        if (Array.isArray(d)) return d;
+      }
+    } catch {}
+    return [];
+  }
+
+  _save() { writeText(this.file, JSON.stringify(this._assets, null, 2)); }
+
+  // 登记一个资产 (关联到 facts scope)
+  // { name, kind: 'document'|'skill'|'experience', scope, owner, visibility, source, description }
+  register(asset) {
+    if (!asset || !asset.name) throw new Error("资产需 name");
+    const id = "as" + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+    const a = {
+      id,
+      name: asset.name,
+      kind: asset.kind || "document",
+      scope: asset.scope || null,
+      owner: asset.owner || "local",
+      // 规范化可见性: 接受 team/private 或 TEAM/PRIVATE
+      visibility: normalizeVisibility(asset.visibility),
+      source: asset.source || null,
+      description: String(asset.description || "").slice(0, 200),
+      version: 1,
+      uses: 0,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    this._assets.push(a);
+    this._save();
+    return a;
+  }
+
+  // 删除资产 (软删: 标记 deleted, 数据保留可恢复)
+  remove(id) {
+    const a = this._assets.find((x) => x.id === id);
+    if (!a) return false;
+    a.deleted = true;
+    a.deletedAt = Date.now();
+    this._save();
+    return true;
+  }
+
+  restore(id) {
+    const a = this._assets.find((x) => x.id === id && x.deleted);
+    if (!a) return false;
+    a.deleted = false;
+    delete a.deletedAt;
+    this._save();
+    return true;
+  }
+
+  // 装备: 把资产绑定到 agent (recorded in uses), 返回可用资产列表
+  equip(id, { by = "local" } = {}) {
+    const a = this._assets.find((x) => x.id === id && !x.deleted);
+    if (!a) return null;
+    a.uses++;
+    a.updatedAt = Date.now();
+    this._save();
+    return a;
+  }
+
+  // 列出资产 (按可见性过滤; deleted 默认隐藏)
+  list({ includeDeleted = false, kind = null, visibility = null } = {}) {
+    return this._assets.filter((a) => {
+      if (!includeDeleted && a.deleted) return false;
+      if (kind && a.kind !== kind) return false;
+      if (visibility && a.visibility !== visibility) return false;
+      return true;
+    });
+  }
+
+  get(id) { return this._assets.find((x) => x.id === id) || null; }
+
+  // 检索某 agent 可用的资产 (装备过的 + 团队可见), 供注入上下文
+  availableFor({ owner = "local" } = {}) {
+    return this._assets.filter((a) => !a.deleted && (a.owner === owner || a.visibility === VISIBILITY.TEAM));
+  }
+
+  // 统计
+  stats() {
+    const active = this._assets.filter((a) => !a.deleted);
+    return {
+      total: this._assets.length,
+      active: active.length,
+      byKind: active.reduce((m, a) => { m[a.kind] = (m[a.kind] || 0) + 1; return m; }, {}),
+      byVisibility: active.reduce((m, a) => { m[a.visibility] = (m[a.visibility] || 0) + 1; return m; }, {}),
+      totalUses: active.reduce((s, a) => s + a.uses, 0),
+    };
+  }
+
+  // 渲染资产清单 (注入上下文用, 空则空串)
+  renderAvailable({ owner = "local" } = {}) {
+    const list = this.availableFor({ owner });
+    if (!list.length) return "";
+    return `\n# 记忆资产 (可装备)\n` + list.map((a) => `- [${a.kind}] ${a.name}${a.description ? ` — ${a.description}` : ""} (${a.scope ? "scope:" + a.scope : "无scope"})`).join("\n") + "\n";
+  }
+}
+
+export default AssetHub;