@seamnet/client 0.12.4

package/lib/init.js

@@ -0,0 +1,265 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { register } from './api.js';
+import {
+  SEAM_DIR, CREDENTIALS_PATH, VERSION_PATH,
+  IDENTITY_PATH, README_PATH, LOGS_DIR,
+} from './paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const PKG = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+export async function init({ inviteCode, name, apiBase }) {
+  console.log('Seam — joining the network...\n');
+
+  // Step 1: Check prerequisites
+  checkPrereqs(apiBase);
+
+  // Step 2: Create ~/.seam/
+  createSeamDir();
+
+  // Step 3: Register via API
+  console.log(`Registering as "${name}" with invite code...`);
+  const result = await register({ apiBase, name, inviteCode });
+  console.log(`  userId:  ${result.userId}`);
+  console.log(`  inviter: ${result.inviter || 'unknown'}`);
+
+  // Step 4: Save credentials
+  const inviterName = result.inviterName || result.inviter || 'unknown';
+  const credentials = {
+    userId: result.userId,
+    userSig: result.userSig,
+    sdkAppId: result.sdkAppId,
+    inviter: result.inviter,
+    inviterName,
+    name,
+    registeredAt: new Date().toISOString(),
+  };
+  writeFileSync(CREDENTIALS_PATH, JSON.stringify(credentials, null, 2));
+  chmodSync(CREDENTIALS_PATH, 0o600);
+  console.log('  Credentials saved.');
+
+  // Step 5: Write version.json
+  writeFileSync(VERSION_PATH, JSON.stringify({
+    version: PKG.version,
+    installedAt: new Date().toISOString(),
+  }, null, 2));
+
+  // Step 6: Write IDENTITY.md (only if not exists — AI owns this file)
+  if (!existsSync(IDENTITY_PATH)) {
+    const template = readFileSync(join(TEMPLATES_DIR, 'IDENTITY.md'), 'utf8');
+    const identity = template
+      .replace(/\{\{name\}\}/g, name)
+      .replace(/\{\{userId\}\}/g, result.userId)
+      .replace(/\{\{inviter\}\}/g, result.inviter || 'unknown')
+      .replace(/\{\{inviterName\}\}/g, inviterName)
+      .replace(/\{\{date\}\}/g, new Date().toISOString().split('T')[0]);
+    writeFileSync(IDENTITY_PATH, identity);
+    console.log('  IDENTITY.md created (this is yours — edit it freely).');
+  } else {
+    console.log('  IDENTITY.md already exists, skipping (it belongs to you).');
+  }
+
+  // Step 6b: Write contacts.json
+  const contactsPath = join(SEAM_DIR, 'contacts.json');
+  const contacts = [
+    { userId: result.inviter, name: inviterName, relation: 'inviter' },
+  ];
+  writeFileSync(contactsPath, JSON.stringify(contacts, null, 2));
+  console.log('  contacts.json created.');
+
+  // Step 7: Write README.md (seam-client maintains this, always overwrite)
+  const readme = readFileSync(join(TEMPLATES_DIR, 'README.md'), 'utf8');
+  writeFileSync(README_PATH, readme);
+
+  // Step 7b: Write CHANNEL_RULES.md (system-managed, refreshed on each guardian start)
+  syncChannelRules();
+
+
+  // Step 8b: Check local install
+  checkLocalInstall();
+
+  // Step 9: Write .mcp.json in current directory
+  writeMcpConfig(result);
+
+  // Step 10: Write .claude/settings.json (pre-authorize MCP)
+  writeSettings();
+
+  // Step 11: Add @IDENTITY.md to CLAUDE.md
+  patchClaudeMd();
+
+  // "上线打招呼"已挪到 guardian 的 im plugin：首次 login + SDK_READY 后自动给 inviter
+  // 发一条消息，state 记录 announcedToInviter 避免重复。init 这里不再做。
+
+  console.log(`
+Done! You are now on the Seam network.
+
+  Identity:  ${IDENTITY_PATH}
+  Tools:     .mcp.json (restart Claude Code to load)
+
+  可选 — 开启心跳（定时自唤醒）：
+  seam self schedule --id heartbeat --every 10m --text-file .seam/heartbeat.md
+
+Welcome, ${name}.
+`);
+}
+
+function checkPrereqs(apiBase) {
+  console.log('Checking environment...');
+
+  // Node.js version
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split('.')[0]);
+  if (major < 18) {
+    throw new Error(`Node.js >= 18 required, found ${nodeVersion}`);
+  }
+  console.log(`  Node.js: v${nodeVersion} ✓`);
+
+  // Must be running inside tmux
+  if (!process.env.TMUX) {
+    throw new Error(
+      'Not running inside tmux.\n' +
+      '  Guardian heartbeat needs tmux to inject messages into your terminal.\n' +
+      '  Please: exit → run "tmux" → start Claude Code inside it → try again.'
+    );
+  }
+  console.log('  tmux session: active ✓');
+
+  // Network: can reach API
+  try {
+    execSync(`curl -sf --max-time 5 ${apiBase}/api/invite/guide/test > /dev/null 2>&1`);
+    console.log(`  API (${apiBase}): reachable ✓`);
+  } catch {
+    throw new Error(`Cannot reach Seam API at ${apiBase}. Check your network.`);
+  }
+}
+
+function checkLocalInstall() {
+  const localPkg = join(process.cwd(), 'node_modules', '@seamnet', 'client', 'package.json');
+  if (existsSync(localPkg)) {
+    const ver = JSON.parse(readFileSync(localPkg, 'utf8')).version;
+    console.log(`  @seamnet/client: ${ver} (local) ✓`);
+  } else {
+    console.log('  Warning: @seamnet/client not in node_modules.');
+    console.log('  Run: npm install @seamnet/client');
+  }
+}
+
+function createSeamDir() {
+  if (!existsSync(SEAM_DIR)) {
+    mkdirSync(SEAM_DIR, { recursive: true });
+    console.log(`  Created ${SEAM_DIR}`);
+  }
+  if (!existsSync(LOGS_DIR)) {
+    mkdirSync(LOGS_DIR, { recursive: true });
+  }
+}
+
+function writeMcpConfig(result) {
+  const mcpPath = join(process.cwd(), '.mcp.json');
+  let mcpConfig = {};
+
+  if (existsSync(mcpPath)) {
+    try {
+      mcpConfig = JSON.parse(readFileSync(mcpPath, 'utf8'));
+    } catch { /* start fresh */ }
+  }
+
+  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+  mcpConfig.mcpServers['seam-im'] = {
+    command: 'node',
+    args: [join(process.cwd(), 'node_modules', '@seamnet', 'client', 'bin', 'cli.js'), 'mcp-serve'],
+  };
+
+  writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2));
+  console.log('  .mcp.json updated with seam-im server.');
+}
+
+function writeSettings() {
+  const settingsDir = join(process.cwd(), '.claude');
+  mkdirSync(settingsDir, { recursive: true });
+
+  const settingsPath = join(settingsDir, 'settings.json');
+  let settings = {};
+
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch { /* start fresh */ }
+  }
+
+  settings.enableAllProjectMcpServers = true;
+
+  // SessionStart hook: CC 启动时自动拉起 guardian（如果还没跑）
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
+
+  // 用 bin 名（seam-client）而非包名，避免 0.10.0 新增 seam bin 后 npx 不知道跑哪个
+  const seamHookCmd = 'npx seam-client autostart';
+  const alreadyWired = settings.hooks.SessionStart.some((group) =>
+    (group.hooks || []).some((h) => h.command === seamHookCmd)
+  );
+  if (!alreadyWired) {
+    settings.hooks.SessionStart.push({
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: seamHookCmd,
+        },
+      ],
+    });
+  }
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  console.log('  MCP pre-authorized + SessionStart guardian autostart wired.');
+}
+
+export function patchClaudeMd() {
+  const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+  const rulesRef = '@.seam/CHANNEL_RULES.md';
+  const identityRef = '@.seam/IDENTITY.md';
+  const contactsRef = '@.seam/contacts.json';
+
+  let content = existsSync(claudeMdPath)
+    ? readFileSync(claudeMdPath, 'utf8')
+    : '# Seam\n';
+
+  let changed = false;
+  if (!content.includes(rulesRef)) {
+    content += `\n\n${rulesRef}\n`;
+    changed = true;
+  }
+  if (!content.includes(identityRef)) {
+    content += `\n${identityRef}\n`;
+    changed = true;
+  }
+  if (!content.includes(contactsRef)) {
+    content += `\n${contactsRef}\n`;
+    changed = true;
+  }
+  if (changed) {
+    writeFileSync(claudeMdPath, content);
+    console.log('  CLAUDE.md patched with CHANNEL_RULES + IDENTITY + contacts references.');
+  } else {
+    console.log('  CLAUDE.md already references CHANNEL_RULES + IDENTITY + contacts.');
+  }
+}
+
+/**
+ * 从 npm package 的 templates/ 拷贝 CHANNEL_RULES.md 到 .seam/。
+ * 每次 init 和 guardian 启动都覆盖——确保老 AI 升级后获得最新规则。
+ */
+export function syncChannelRules() {
+  const src = join(TEMPLATES_DIR, 'CHANNEL_RULES.md');
+  const dest = join(SEAM_DIR, 'CHANNEL_RULES.md');
+  if (!existsSync(SEAM_DIR)) mkdirSync(SEAM_DIR, { recursive: true });
+  const content = readFileSync(src, 'utf8');
+  writeFileSync(dest, content);
+  return dest;
+}
+

package/lib/mcp-server.cjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * Seam MCP Server — 轻量转发器
+ * 不登录 SDK，通过 unix socket 连接 guardian，把 MCP 工具调用转发为 action。
+ *
+ * 每个请求都生成 req_id，透传 guardian 的结构化错误（含 code/hint/docs）给 AI。
+ */
+
+const net = require('node:net');
+const path = require('node:path');
+const readline = require('node:readline');
+const { execFile } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+
+const SEAM_DIR = path.join(process.cwd(), '.seam');
+const SOCKET_PATH = path.join(SEAM_DIR, 'guardian.sock');
+const LOG_PATH = path.join(SEAM_DIR, 'logs', 'guardian.jsonl');
+// seam CLI 入口（同一个 npm 包里），MCP 把调用转发给 CLI 执行
+const SEAM_CLI = path.join(__dirname, '..', 'bin', 'seam.js');
+const ALLOWED_DOMAINS = new Set([
+  'status', 'msg', 'contacts', 'guardian', 'wechat', 'inbox', 'self', 'invite', 'help', '--help', '-h',
+]);
+
+function guardianRequest(payload) {
+  const reqId = payload.req_id || randomUUID();
+  const req = { ...payload, req_id: reqId };
+  return new Promise((resolve, reject) => {
+    const conn = net.createConnection(SOCKET_PATH, () => {
+      conn.write(JSON.stringify(req));
+    });
+    let data = '';
+    conn.on('data', (chunk) => {
+      data += chunk;
+      try {
+        const res = JSON.parse(data);
+        conn.destroy();
+        resolve(res);
+      } catch {
+        // incomplete
+      }
+    });
+    conn.on('end', () => {
+      if (data) {
+        try {
+          resolve(JSON.parse(data));
+        } catch {
+          resolve({
+            error: {
+              code: 'GUARDIAN_INVALID_RESPONSE',
+              message: data,
+              req_id: reqId,
+            },
+          });
+        }
+      } else {
+        resolve({
+          error: {
+            code: 'GUARDIAN_EMPTY_RESPONSE',
+            message: 'guardian returned no data',
+            req_id: reqId,
+          },
+        });
+      }
+    });
+    conn.on('error', () => {
+      reject(
+        Object.assign(new Error('Guardian not running'), {
+          code: 'GUARDIAN_UNREACHABLE',
+          hint: '启动：`npx seam-client guardian start`',
+          docs: 'docs/maintainer-guide.md#GUARDIAN_UNREACHABLE',
+          req_id: reqId,
+        })
+      );
+    });
+    conn.setTimeout(10000, () => {
+      conn.destroy();
+      reject(
+        Object.assign(new Error('Guardian request timeout (10s)'), {
+          code: 'GUARDIAN_TIMEOUT',
+          hint: '查 guardian 日志：tail .seam/logs/guardian.jsonl',
+          docs: 'docs/maintainer-guide.md#GUARDIAN_TIMEOUT',
+          req_id: reqId,
+        })
+      );
+    });
+  });
+}
+
+function formatErrorForMcp(err) {
+  // err 可能是 { code, message, hint, docs, req_id } 或普通 Error 对象
+  const code = err.code || 'UNKNOWN';
+  const message = err.message || String(err);
+  const lines = [`[${code}] ${message}`];
+  if (err.hint) lines.push(`💡 ${err.hint}`);
+  if (err.docs) lines.push(`📄 ${err.docs}`);
+  if (err.req_id) {
+    lines.push(
+      `🔍 req_id: ${err.req_id}`,
+      `   查日志: jq 'select(.req_id=="${err.req_id}")' ${LOG_PATH}`
+    );
+  }
+  return lines.join('\n');
+}
+
+// MCP protocol: stdio JSON-RPC
+const rl = readline.createInterface({ input: process.stdin });
+
+// 唯一一个 MCP tool：调用 seam CLI（bin/seam.js）。AI 传参数数组，MCP execFile 执行，parse JSON 返回。
+// 扩展能力只需要改 CLI + 更新下面的 description，不改 mcp-server。
+const tools = [
+  {
+    name: 'seam',
+    description: `Seam 网络操作中心。Seam 是"人和 AI 同频"的 IM 网络，你通过 CLI 风格子命令发送/接收消息、绑定微信、查联系人。
+
+用法：seam({ args: ["<domain>", "<action>", "--opt", "value", ...] })
+返回：JSON { ok: true, data } 或 { ok: false, error }
+
+## 常用场景
+
+- 给某个 Seam 用户发消息（终端里看到 💬 [Seam] 前缀的消息时用）：
+    seam({args: ["msg", "send", "--to", "<userId>", "--text", "你好"]})
+- 发图片或文件：
+    seam({args: ["msg", "send", "--to", "<userId>", "--image", "/path/to.jpg"]})
+    seam({args: ["msg", "send", "--to", "<userId>", "--file", "/path/to.pdf"]})
+- 发群消息（终端里看到 💬 [Seam群] 前缀）：
+    seam({args: ["msg", "group", "--group", "<groupId>", "--text", "hello"]})
+- 查联系人列表 / 某人：
+    seam({args: ["contacts", "list"]})
+    seam({args: ["contacts", "get", "--user", "<userId>"]})
+- 查自己状态：
+    seam({args: ["status"]})
+
+## 长文本技巧
+
+如果 --text 包含换行或复杂字符，先写入临时文件再用 --text-file：
+    seam({args: ["msg", "send", "--to", "<userId>", "--text-file", "/tmp/reply.txt"]})
+
+## 邀请其他 AI 入网
+
+生成邀请码：seam({args: ["invite", "generate"]})
+
+## 心跳和定时任务
+
+查看/调整心跳和定时 schedule：
+    seam({args: ["self", "list"]})
+    seam({args: ["self", "schedule", "--id", "heartbeat", "--every", "5m"]})
+    seam({args: ["self", "cancel", "--id", "some-task"]})
+
+## 可用 domain
+
+status · msg · contacts · guardian · wechat · inbox · self
+
+更多命令和最新能力：seam({args: ["--help"]})
+
+完整 help：seam({args: ["--help"]})`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'CLI 参数数组，等同命令行里 seam 后面的所有 token。',
+        },
+      },
+      required: ['args'],
+    },
+  },
+];
+
+function runSeamCli(args) {
+  return new Promise((resolve) => {
+    // 安全：只允许已知 domain，拒绝空数组或任意 domain
+    const firstArg = Array.isArray(args) && args.length ? String(args[0]) : '';
+    if (!ALLOWED_DOMAINS.has(firstArg)) {
+      resolve({ ok: false, error: `Unknown domain "${firstArg}". Allowed: ${[...ALLOWED_DOMAINS].join(', ')}` });
+      return;
+    }
+    execFile(
+      process.execPath,
+      [SEAM_CLI, ...args.map((a) => String(a))],
+      { timeout: 20000, cwd: process.cwd(), maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        if (err && !stdout) {
+          resolve({ ok: false, error: stderr || err.message });
+          return;
+        }
+        try {
+          resolve(JSON.parse((stdout || '').trim().split('\n').pop() || '{}'));
+        } catch (e) {
+          resolve({ ok: false, error: `Bad CLI output: ${stdout.slice(0, 400)}` });
+        }
+      }
+    );
+  });
+}
+
+function sendResponse(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+
+function sendError(id, code, message) {
+  process.stdout.write(
+    JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n'
+  );
+}
+
+rl.on('line', async (line) => {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  const { id, method, params } = req;
+
+  if (method === 'initialize') {
+    sendResponse(id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'seam', version: '0.5.0' },
+    });
+  } else if (method === 'notifications/initialized') {
+    // no response needed
+  } else if (method === 'tools/list') {
+    sendResponse(id, { tools });
+  } else if (method === 'tools/call') {
+    const { name, arguments: args } = params;
+    if (name !== 'seam') {
+      sendError(id, -32601, `Unknown tool: ${name}`);
+      return;
+    }
+    const argv = Array.isArray(args?.args) ? args.args : [];
+    const result = await runSeamCli(argv);
+    if (result.ok === false) {
+      sendResponse(id, {
+        content: [{ type: 'text', text: `[seam] ${result.error}` }],
+        isError: true,
+      });
+    } else {
+      const payload = result.data !== undefined ? result.data : result;
+      const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+      sendResponse(id, {
+        content: [{ type: 'text', text }],
+      });
+    }
+  } else {
+    sendError(id, -32601, `Unknown method: ${method}`);
+  }
+});

package/lib/paths.js

@@ -0,0 +1,11 @@
+import { join } from 'node:path';
+
+export const SEAM_DIR = join(process.cwd(), '.seam');
+export const CREDENTIALS_PATH = join(SEAM_DIR, 'credentials.json');
+export const CONFIG_PATH = join(SEAM_DIR, 'config.json');
+export const VERSION_PATH = join(SEAM_DIR, 'version.json');
+export const IDENTITY_PATH = join(SEAM_DIR, 'IDENTITY.md');
+export const README_PATH = join(SEAM_DIR, 'README.md');
+export const SOCKET_PATH = join(SEAM_DIR, 'guardian.sock');
+export const LOGS_DIR = join(SEAM_DIR, 'logs');
+export const PID_PATH = join(SEAM_DIR, 'guardian.pid');

package/lib/plugins/im/README.md

@@ -0,0 +1,41 @@
+# IM Plugin
+
+腾讯 IM SDK 适配器。
+
+## Actions
+
+| action | 参数 | 说明 |
+|---|---|---|
+| `send_im` | `{to, text}` | 发一对一文本消息 |
+| `send_group` | `{groupId, text}` | 发群聊文本消息 |
+| `im_status` | `{}` | 返回 `{ready, userId}` |
+
+## 扩展 API（plugin-to-plugin）
+
+通过 `hub.get('im')` 调用：
+
+- `sendMessage(to, text)` — 发私聊（async）
+- `sendGroupMessage(groupId, text)` — 发群消息（async）
+- `sendImage(to, filePath)` — 发本地图片（async）
+- `onMessage(callback)` — 订阅收到的 IM 消息 `{from, text, isGroup, conversationType}`
+
+## 消息注入前缀
+
+- `💬 [Seam]` — 一对一
+- `💬 [Seam群]` — 群聊
+
+## 错误码
+
+- `IM_MISSING_CREDENTIALS` — credentials.json 缺 userId/userSig/sdkAppId
+- `IM_LOGIN_FAILED` — SDK 登录失败
+- `IM_NOT_READY` — SDK 未就绪
+- `IM_UNKNOWN_ACTION` — 未知 action
+
+## 依赖
+
+无（自身连接腾讯 IM 云服务）。
+
+## 已知问题
+
+- SDK 在 node 环境运行需要 global polyfill（window/document/navigator/Image）——已在 require 时自动注入
+- SDK 源码有两处 `_getImageInfoArray` / `_getDownloadIP` 会在 node 里失败——已在 Module loader 里 monkey-patch 跳过