@seamnet/client 0.12.4

package/lib/services/README.md

@@ -0,0 +1,93 @@
+# Services
+
+Guardian 的内部能力。对插件可见（`hub.service(name)`），不对 MCP 暴露。
+
+## 边界
+
+> **跨外部 = Plugin（外部通道适配器）；不跨外部 = Service（内部能力）**
+
+所有不直接跟外部世界连接、但能复用的能力都是 Service。
+
+## Service 契约
+
+```js
+function createXxxService(config) {
+  return {
+    name: 'xxx',
+    async init(hub) { /* 启动 */ },
+    async destroy() { /* 关闭 */ },
+    // + 具体能力方法（logger 的 info/warn/error; scheduler 的 every/at/cancel; ...）
+  };
+}
+module.exports = { createXxxService };
+```
+
+- Service **不声明 actions**（不对 MCP）
+- Service 生命周期由 guardian 统一管
+- Service 之间可以互相依赖（`hub.service('dep')`）
+
+## 目录结构
+
+每个 Service 一个目录，和 Plugin 对称：
+
+```
+lib/services/
+├── logger/          ✅ 实现
+│   ├── index.cjs
+│   └── README.md
+├── state/           ✅ 实现
+│   ├── index.cjs
+│   └── README.md
+├── event-bus/       ✅ 实现
+│   ├── index.cjs
+│   └── README.md
+├── message-buffer/  ✅ 实现
+│   ├── index.cjs
+│   └── README.md
+├── inbox/           ✅ 实现
+│   ├── index.cjs
+│   └── README.md
+├── scheduler/       ⏳ v1.5
+└── watcher/         ⏳ v1.5
+```
+
+## 当前状态
+
+| Service | 状态 | 作用 |
+|---|---|---|
+| `logger` | ✅ | 结构化 JSONL 日志 + 自动脱敏 |
+| `state` | ✅ | 统一状态持久化（`.seam/state.json`），namespace 隔离 |
+| `event-bus` | ✅ | 插件间事件总线（emit/on/once/off） |
+| `message-buffer` | ✅ | 消息合并（debounce），避免 AI 抽风 |
+| `inbox` | ✅ | 收到图片/文件的本地存储（`.seam/inbox/`） |
+| `inject` | ⚠️ 嵌在 hub 里 | tmux send-keys 到 CC session |
+| `run` | ⚠️ 嵌在 hub 里 | 错误隔离执行 |
+| `scheduler` | ⏳ v1.5 | 定时任务（cron / every / at） |
+| `watcher` | ⏳ v1.5 | 文件变化监听 |
+
+## 新增 Service 流程
+
+1. `lib/services/<name>/index.cjs` 按契约实现
+2. `lib/services/<name>/README.md` 说明：能力、API、依赖、错误码
+3. 在 `guardian-core.cjs` 的启动流程里 `hub.registerService(createXxxService(...))`
+4. 补单元测试 `test/unit/<name>.test.cjs`
+5. 在本文件的状态表里标 ✅
+
+## 使用示例
+
+插件里用 Service：
+
+```js
+async init(hub) {
+  // 快捷方式（shortcut，常用）
+  const log = hub.logger(this.name);
+  log.info('started');
+  
+  // 直接拿 service（v1.5 会用到）
+  const scheduler = hub.service('scheduler');
+  scheduler.every('5m', () => this.checkSomething());
+  
+  const state = hub.service('state');
+  await state.set(this.name, { active: true });
+}
+```

package/lib/services/event-bus/README.md

@@ -0,0 +1,76 @@
+# Event Bus Service
+
+插件间事件总线。
+
+## 为什么
+
+现在 IM 插件自己维护 `messageCallbacks[]` 给其他插件订阅——是 hack。将来多插件协作必须有通用事件机制。
+
+## API
+
+```js
+const bus = hub.service('event-bus');
+
+// 订阅
+const unsub = bus.on('im.message', async (msg) => {
+  // 处理...
+});
+
+// 一次性订阅
+bus.once('wechat.binding_active', (data) => { ... });
+
+// 发布（async，等所有 handler 完成）
+await bus.emit('im.message', { from, text, isGroup });
+
+// 取消订阅
+unsub();          // 或者
+bus.off('im.message', handler);
+```
+
+## 事件命名
+
+格式：`<plugin>.<event>`
+
+| 事件 | 谁 emit | Payload |
+|---|---|---|
+| `im.message` | IM 插件 | `{ from, text, isGroup, conversationType }` |
+| `wechat.message` | WeChat 插件 | `{ sender, text }` |
+| `wechat.binding_active` | WeChat 插件 | `{ ilink_user_id }` |
+
+新插件加事件：在自己的 README 里声明会 emit 哪些 event，格式就是 plugin 名为前缀。
+
+## 错误隔离
+
+- Handler 抛异常 **不影响** 其他 handler——内部 try-catch 后记日志继续
+- Handler 可以是 async——emit 等所有完成后返回（`Promise.all`）
+
+## 已知限制
+
+- 没有 wildcard（`im.*` 订阅不了）——v2 再说
+- 没有事件级别优先级
+- Payload 不校验——plugin 各自负责
+
+## 示例：IM 插件迁移
+
+**老方式**（插件里自己维护订阅者数组）：
+
+```js
+const messageCallbacks = [];
+function onMessage(cb) { messageCallbacks.push(cb); }
+// 收到消息时
+for (const cb of messageCallbacks) { try { cb(msg); } catch {} }
+```
+
+**新方式**：
+
+```js
+// 订阅方（wechat 插件 init）
+hub.service('event-bus').on('im.message', ({ from, text, isGroup }) => {
+  if (!isGroup && text.trim() === '绑定微信') startLogin(from);
+});
+
+// 发布方（im 插件收到消息）
+await hub.service('event-bus').emit('im.message', {
+  from: msg.from, text, isGroup, conversationType
+});
+```

package/lib/services/event-bus/index.cjs

@@ -0,0 +1,90 @@
+/**
+ * Event Bus Service — 插件间事件总线。
+ *
+ * 设计：
+ * - emit / on / once / off 四个核心 API
+ * - Handler 可以是 async——emit 等所有 handler 完成（Promise.all）
+ * - Handler 抛异常不影响其他 handler（内部 try-catch + 日志）
+ * - 事件名约定：`<plugin>.<event>`（例如 `im.message`, `wechat.binding_active`）
+ * - Wildcard 不做（v1 简单为主）
+ */
+
+function createEventBus() {
+  const listeners = new Map(); // event -> [handler, ...]
+  let log = null;
+
+  async function init(hub) {
+    log = hub.logger('event-bus');
+  }
+
+  async function destroy() {
+    listeners.clear();
+  }
+
+  function on(event, handler) {
+    if (typeof event !== 'string' || !event) {
+      throw new Error('event must be a non-empty string');
+    }
+    if (typeof handler !== 'function') {
+      throw new Error('handler must be a function');
+    }
+    if (!listeners.has(event)) listeners.set(event, []);
+    listeners.get(event).push(handler);
+    return () => off(event, handler);
+  }
+
+  function once(event, handler) {
+    const wrapped = async (...args) => {
+      off(event, wrapped);
+      return handler(...args);
+    };
+    return on(event, wrapped);
+  }
+
+  function off(event, handler) {
+    const arr = listeners.get(event);
+    if (!arr) return false;
+    const idx = arr.indexOf(handler);
+    if (idx < 0) return false;
+    arr.splice(idx, 1);
+    if (arr.length === 0) listeners.delete(event);
+    return true;
+  }
+
+  async function emit(event, ...args) {
+    const handlers = listeners.get(event);
+    if (!handlers || handlers.length === 0) return;
+    if (log) log.debug('emit', { event, listenerCount: handlers.length });
+    await Promise.all(
+      handlers.map(async (h) => {
+        try {
+          await h(...args);
+        } catch (e) {
+          if (log) log.error('handler_error', e, { event });
+        }
+      })
+    );
+  }
+
+  function listenerCount(event) {
+    return listeners.get(event)?.length || 0;
+  }
+
+  function events() {
+    return [...listeners.keys()];
+  }
+
+  return {
+    name: 'event-bus',
+    init,
+    destroy,
+    on,
+    once,
+    off,
+    emit,
+    listenerCount,
+    events,
+  };
+}
+
+module.exports = { createEventBus };

package/lib/services/inbox/README.md

@@ -0,0 +1,52 @@
+# Inbox Service
+
+本地存储收到的图片/文件。AI 用 `Read` 读本地路径看图。
+
+## 目录
+
+`.seam/inbox/` — 权限 0700，文件权限 0600
+
+## 命名
+
+`<ts>_<src>_<shortId>.<ext>`
+- `ts`：ISO 时间戳 `20260418T123045`
+- `src`：来源（wechat / im）
+- `shortId`：6 字符随机 hex，避免同秒冲突
+- `ext`：扩展名
+
+## API
+
+```js
+const inbox = hub.service('inbox');
+const filePath = inbox.save(buf, { ext: 'jpg', src: 'wechat' });
+// → /path/.seam/inbox/20260418T123045_wechat_a1b2c3.jpg
+```
+
+- `save(buf, { ext, src }) → localPath`
+- `list() → [{name, path, size, mtimeMs}]`
+- `cleanup() → {removed}` 按策略清理
+- `remove(filePath) → bool`（只能删 inbox 内文件）
+- `.dir` 当前 inbox 目录
+
+## 清理策略
+
+- 7 天未访问 → 删
+- 总大小超 500 MB → 按 FIFO 删老的
+
+配置：
+```js
+createInboxService({ maxAgeMs, maxTotalBytes })
+```
+
+## 典型使用（插件）
+
+```js
+// WeChat 收图
+const key = Buffer.from(imageItem.aeskey, 'hex');
+const resp = await fetch(imageItem.media.full_url);
+const encrypted = Buffer.from(await resp.arrayBuffer());
+const dec = crypto.createDecipheriv('aes-128-ecb', key, null);
+const decrypted = Buffer.concat([dec.update(encrypted), dec.final()]);
+const filePath = inbox.save(decrypted, { ext: 'jpg', src: 'wechat' });
+hub.inject(`📱 [微信图片 ${ts}] ${sender} → ${filePath}`);
+```

package/lib/services/inbox/index.cjs

@@ -0,0 +1,168 @@
+/**
+ * Inbox Service — 接收图片/文件的本地存储。
+ *
+ * 设计：
+ * - 目录：<seamDir>/inbox/
+ * - 文件名：<ts>_<src>_<shortId>.<ext>
+ * - 权限 0700
+ * - 清理策略：启动时 + 定期清超过 maxAgeMs 或总大小超过 maxTotalBytes 的文件（FIFO）
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const DEFAULT_MAX_TOTAL_BYTES = 500 * 1024 * 1024; // 500 MB
+
+function createInboxService(opts = {}) {
+  const {
+    maxAgeMs = DEFAULT_MAX_AGE_MS,
+    maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES,
+  } = opts;
+  let hub = null;
+  let log = null;
+  let dir = null;
+
+  function ensureDir() {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      try {
+        fs.chmodSync(dir, 0o700);
+      } catch {}
+    }
+  }
+
+  async function init(h) {
+    hub = h;
+    log = hub.logger('inbox');
+    dir = path.join(hub.seamDir, 'inbox');
+    ensureDir();
+    cleanup().catch(() => {});
+    log.info('inbox_ready', { dir });
+  }
+
+  async function destroy() {}
+
+  function sanitizeExt(ext) {
+    if (!ext) return '';
+    const cleaned = String(ext).replace(/[^a-zA-Z0-9]/g, '').slice(0, 8);
+    return cleaned ? `.${cleaned}` : '';
+  }
+
+  function sanitizeSrc(src) {
+    if (!src) return 'msg';
+    return String(src).replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 16) || 'msg';
+  }
+
+  /**
+   * 保存一段 buffer 到 inbox。
+   * @param {Buffer} buf
+   * @param {Object} opts
+   * @param {string} [opts.ext]   文件扩展名（不含点）
+   * @param {string} [opts.src]   来源标识（如 'wechat', 'im'）
+   * @returns {string} 本地绝对路径
+   */
+  function save(buf, opts = {}) {
+    ensureDir();
+    const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15); // 20260418T123045
+    const srcTag = sanitizeSrc(opts.src);
+    const shortId = crypto.randomBytes(3).toString('hex');
+    const ext = sanitizeExt(opts.ext);
+    const filename = `${ts}_${srcTag}_${shortId}${ext}`;
+    const filePath = path.join(dir, filename);
+    fs.writeFileSync(filePath, buf);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {}
+    if (log) {
+      log.info('saved', {
+        path: filePath,
+        bytes: buf.length,
+        src: srcTag,
+      });
+    }
+    return filePath;
+  }
+
+  function list() {
+    ensureDir();
+    const entries = fs.readdirSync(dir);
+    return entries.map((name) => {
+      const full = path.join(dir, name);
+      const st = fs.statSync(full);
+      return { name, path: full, size: st.size, mtimeMs: st.mtimeMs };
+    });
+  }
+
+  /**
+   * 清理策略：
+   * 1. 删除 age 超过 maxAgeMs 的文件
+   * 2. 若剩余总 size 仍超过 maxTotalBytes，按 mtime 升序（旧在前）删到合规
+   */
+  async function cleanup() {
+    ensureDir();
+    const now = Date.now();
+    let removed = 0;
+    let items = list();
+
+    for (const item of items) {
+      if (now - item.mtimeMs > maxAgeMs) {
+        try {
+          fs.unlinkSync(item.path);
+          removed++;
+        } catch {}
+      }
+    }
+
+    items = list();
+    const totalBytes = items.reduce((a, b) => a + b.size, 0);
+    if (totalBytes > maxTotalBytes) {
+      items.sort((a, b) => a.mtimeMs - b.mtimeMs);
+      let current = totalBytes;
+      for (const item of items) {
+        if (current <= maxTotalBytes) break;
+        try {
+          fs.unlinkSync(item.path);
+          current -= item.size;
+          removed++;
+        } catch {}
+      }
+    }
+
+    if (log && removed > 0) {
+      log.info('cleanup_done', { removed, maxAgeMs, maxTotalBytes });
+    }
+    return { removed };
+  }
+
+  function remove(filePath) {
+    try {
+      const resolved = path.resolve(filePath);
+      // 安全：只允许删 inbox 目录下的文件
+      if (!resolved.startsWith(dir + path.sep)) {
+        throw new Error('path not in inbox dir');
+      }
+      fs.unlinkSync(resolved);
+      return true;
+    } catch (e) {
+      if (log) log.warn('remove_failed', { filePath, message: e.message });
+      return false;
+    }
+  }
+
+  return {
+    name: 'inbox',
+    init,
+    destroy,
+    save,
+    list,
+    cleanup,
+    remove,
+    get dir() {
+      return dir;
+    },
+  };
+}
+
+module.exports = { createInboxService };

package/lib/services/logger/README.md

@@ -0,0 +1,81 @@
+# Logger Service
+
+JSONL 结构化日志，写到 `.seam/logs/guardian.jsonl`。
+
+## 特性
+
+- **每行一个 JSON 对象**，`jq` 友好
+- **自动脱敏**：`userSig` / `bot_token` / `password` 等字段值替换为 `<redacted>`
+- **child logger**：派生带插件名和请求 id 的子 logger
+- **永不抛**：日志写入失败静默吞掉，不影响主流程
+
+## API
+
+```js
+const { createLogger } = require('./services/logger/index.cjs');
+const logger = createLogger({ logPath: '/path/.seam/logs/guardian.jsonl' });
+
+logger.info('event_name', { data });              // level: info
+logger.warn('event_name', { data });              // level: warn
+logger.error('event_name', errorObj, { data });   // level: error
+logger.debug('event_name', { data });             // level: debug
+
+// Child logger 带插件名和 reqId
+const imLog = logger.child({ plugin: 'im', reqId: 'abc' });
+imLog.info('sdk_ready');  // → {ts, level:'info', plugin:'im', req_id:'abc', event:'sdk_ready'}
+```
+
+在插件里通常用 hub 的快捷方式：
+
+```js
+const log = hub.logger(this.name);
+log.info('started');
+```
+
+## 日志格式
+
+```json
+{"ts":"2026-04-18T10:00:00.000Z","level":"info","plugin":"im","req_id":"abc-123","event":"sdk_ready","data":{"userId":"u1"}}
+```
+
+字段：
+- `ts` — ISO 时间戳
+- `level` — info / warn / error / debug
+- `plugin` — 插件名（可选）
+- `req_id` — 请求 id（可选，经 child logger 传入）
+- `event` — 事件名（snake_case）
+- `data` — 自由结构（会被脱敏）
+- `error` — 错误对象（含 message/stack/code）
+
+## 脱敏字段
+
+`SENSITIVE_KEYS` 数组（大小写不敏感包含匹配）：
+
+- `userSig`
+- `secretKey`
+- `bot_token` / `botToken`
+- `password`
+- `authorization`
+- `token`
+- `context_token` / `contextToken`
+
+添加新字段：直接改 `lib/services/logger/index.cjs` 里的 `SENSITIVE_KEYS` 数组。
+
+## 查日志
+
+```bash
+# 按 req_id 查完整轨迹
+jq 'select(.req_id=="<id>")' .seam/logs/guardian.jsonl
+
+# 按插件+级别过滤
+jq 'select(.plugin=="wechat" and .level=="error")' .seam/logs/guardian.jsonl
+
+# 最近 N 条错误
+tail -n 200 .seam/logs/guardian.jsonl | jq 'select(.level=="error")'
+```
+
+## 已知限制
+
+- 写入是 sync（`appendFileSync`）——高并发下有轻微阻塞，当前量级（<100 req/s）无问题
+- 无 log rotation——未来跨天要补（v1.5）
+- 递归深度上限 5（防循环引用）

package/lib/services/logger/index.cjs

@@ -0,0 +1,109 @@
+/**
+ * Seam Logger — JSONL 结构化日志。
+ *
+ * 设计：
+ * - 每行一个 JSON 对象，写到 .seam/logs/guardian.jsonl
+ * - 自动脱敏 SENSITIVE_KEYS（userSig / bot_token / password 等）
+ * - child({plugin, reqId}) 派生带插件名和请求 id 的子 logger
+ * - 不抛异常——日志失败不应该影响主流程
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SENSITIVE_KEYS = [
+  'userSig',
+  'secretKey',
+  'bot_token',
+  'botToken',
+  'password',
+  'authorization',
+  'token',
+  'context_token',
+  'contextToken',
+];
+
+function shouldRedact(key) {
+  const lower = String(key).toLowerCase();
+  return SENSITIVE_KEYS.some((s) => lower.includes(s.toLowerCase()));
+}
+
+function redact(value, depth = 0) {
+  if (depth > 5) return '[deep]';
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redact(v, depth + 1));
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (shouldRedact(k)) {
+      out[k] = '<redacted>';
+    } else {
+      out[k] = redact(v, depth + 1);
+    }
+  }
+  return out;
+}
+
+class Logger {
+  constructor({ logPath, plugin, reqId }) {
+    this.logPath = logPath;
+    this.plugin = plugin;
+    this.reqId = reqId;
+  }
+
+  _write(level, event, data, error) {
+    const line = {
+      ts: new Date().toISOString(),
+      level,
+      ...(this.plugin && { plugin: this.plugin }),
+      ...(this.reqId && { req_id: this.reqId }),
+      event,
+    };
+    if (data !== undefined) line.data = redact(data);
+    if (error !== undefined) line.error = redact(error);
+    try {
+      if (this.logPath) {
+        const dir = path.dirname(this.logPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(this.logPath, JSON.stringify(line) + '\n');
+      }
+    } catch {
+      // logger never throws
+    }
+    return line;
+  }
+
+  info(event, data) {
+    return this._write('info', event, data);
+  }
+
+  warn(event, data) {
+    return this._write('warn', event, data);
+  }
+
+  error(event, error, data) {
+    const errObj =
+      error instanceof Error
+        ? { message: error.message, stack: error.stack, ...(error.code && { code: error.code }) }
+        : error;
+    return this._write('error', event, data, errObj);
+  }
+
+  debug(event, data) {
+    return this._write('debug', event, data);
+  }
+
+  child({ plugin, reqId } = {}) {
+    return new Logger({
+      logPath: this.logPath,
+      plugin: plugin || this.plugin,
+      reqId: reqId || this.reqId,
+    });
+  }
+}
+
+function createLogger({ logPath }) {
+  return new Logger({ logPath });
+}
+
+module.exports = { createLogger, Logger, redact, SENSITIVE_KEYS };