@archipelagolab/lobi 1.0.0

package/docs/FORK_SDK_GUIDE.md

@@ -0,0 +1,279 @@
+# Fork matrix-js-sdk 完整指南
+
+## 概述
+
+将 Matrix 插件的 API 路径从 `/_matrix/` 修改为 `/_lobi/`，需要 Fork 官方的 matrix-js-sdk 并修改内部路径。
+
+## 步骤 1: Fork 官方仓库
+
+```bash
+# 在你的 GitHub/GitLab 上 Fork 官方仓库
+# 官方仓库: https://github.com/matrix-org/matrix-js-sdk
+
+git clone https://github.com/YOUR_ORG/matrix-js-sdk.git lobi-js-sdk
+cd lobi-js-sdk
+git checkout v41.3.0  # 检出与当前插件兼容的版本
+git checkout -b lobi-fork
+```
+
+## 步骤 2: 修改 SDK 内部路径
+
+### 2.1 关键文件清单
+
+matrix-js-sdk v41.3.0 中需要修改的文件：
+
+| 文件路径 | 路径数量 | 说明 |
+|---------|---------|------|
+| `src/client.ts` | ~150+ | MatrixClient 主类，包含 sync, login, register 等 |
+| `src/http-api.ts` | ~20+ | HTTP 请求底层实现 |
+| `src/sync.ts` | ~30+ | 同步相关 API |
+| `src/definitions/*.ts` | ~50+ | API 端点定义（Client-Server API）|
+| `src/crypto/backup.ts` | ~20+ | 密钥备份 API |
+| `src/crypto/index.ts` | ~30+ | 加密相关 API |
+| `src/embedded.ts` | ~10+ | Embedded 模式 API |
+| `src/feature.ts` | ~5+ | 特性检测 API |
+| `src/rust-crypto/*.ts` | ~40+ | Rust 加密实现 |
+
+### 2.2 自动替换脚本
+
+在 fork 的仓库根目录创建并执行：
+
+```bash
+#!/bin/bash
+# sdk-replace-paths.sh
+
+echo "开始替换 _matrix 为 _lobi..."
+
+# 替换 src 目录下所有 TypeScript 文件
+find src -type f \( -name "*.ts" -o -name "*.js" \) -exec sed -i '' 's/\/_matrix\//\/_lobi\//g' {} +
+
+# 替换 lib 目录（如果存在已编译的文件）
+find lib -type f \( -name "*.ts" -o -name "*.js" -o -name "*.d.ts" \) -exec sed -i '' 's/\/_matrix\//\/_lobi\//g' {} + 2>/dev/null || true
+
+# 替换 dist 目录（如果存在）
+find dist -type f \( -name "*.ts" -o -name "*.js" -o -name "*.d.ts" \) -exec sed -i '' 's/\/_matrix\//\/_lobi\//g' {} + 2>/dev/null || true
+
+echo "替换完成！"
+echo ""
+echo "验证替换结果:"
+grep -r "\/_matrix\/" src --include="*.ts" | head -5 || echo "无残留的 _matrix 路径"
+```
+
+### 2.3 手动检查关键路径
+
+执行自动替换后，手动检查以下关键 API 路径是否正确替换：
+
+```bash
+# 检查登录相关
+grep -n "client/v3/login" src/client.ts
+
+# 检查同步相关
+grep -n "client/v3/sync" src/client.ts src/sync.ts
+
+# 检查密钥相关
+grep -n "client/v3/keys" src/crypto/*.ts
+
+# 检查房间相关
+grep -n "client/v3/rooms" src/client.ts
+
+# 检查媒体相关
+grep -n "media/v3" src/client.ts src/http-api.ts
+```
+
+## 步骤 3: 修改包名并发布
+
+### 3.1 修改 package.json
+
+```json
+{
+  "name": "@your-org/lobi-js-sdk",
+  "version": "41.3.0-lobi.1",
+  "description": "Lobi SDK - Forked from matrix-js-sdk with modified API paths",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_ORG/lobi-js-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+### 3.2 构建并发布
+
+```bash
+# 安装依赖
+yarn install
+
+# 构建 SDK
+yarn build
+
+# 运行测试（根据需要）
+yarn test
+
+# 发布到 npm
+npm publish --access public
+
+# 或使用私有 registry
+npm publish --registry https://your-private-registry.com
+```
+
+## 步骤 4: 修改 Matrix 插件
+
+### 4.1 修改 package.json
+
+```json
+{
+  "dependencies": {
+    "@your-org/lobi-js-sdk": "41.3.0-lobi.1",
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "@matrix-org/matrix-sdk-crypto-wasm": "18.0.0"
+  }
+}
+```
+
+### 4.2 修改所有导入语句
+
+需要修改的文件列表：
+- `src/matrix/sdk.ts`
+- `src/matrix/client/logging.ts`
+- `src/matrix/client/file-sync-store.ts`
+- `src/matrix/sdk/decrypt-bridge.ts`
+- `src/matrix/sdk/verification-manager.ts`
+- `src/matrix/sdk/crypto-bootstrap.ts`
+- `src/matrix/sdk/recovery-key-store.ts`
+- `src/matrix/sdk/event-helpers.ts`
+- `src/matrix/sdk/crypto-facade.ts`
+
+将：
+```typescript
+import { ... } from "matrix-js-sdk/lib/...";
+```
+
+改为：
+```typescript
+import { ... } from "@your-org/lobi-js-sdk/lib/...";
+```
+
+### 4.3 修改硬编码路径
+
+即使使用 fork 的 SDK，插件中直接调用 HTTP 的端点仍需修改：
+
+```typescript
+// src/matrix/client/config.ts
+// 修改前
+return (await tempClient.doRequest("GET", "/_matrix/client/v3/account/whoami")) as { ... };
+
+// 修改后
+return (await tempClient.doRequest("GET", "/_lobi/client/v3/account/whoami")) as { ... };
+```
+
+完整文件列表见 [MIGRATION_CHECKLIST.md](./MIGRATION_CHECKLIST.md)
+
+## 步骤 5: 测试验证
+
+### 5.1 安装依赖
+
+```bash
+cd extensions/matrix
+pnpm install
+```
+
+### 5.2 运行测试
+
+```bash
+# 运行单元测试
+pnpm test
+
+# 运行 Matrix 特定测试
+pnpm test src/matrix
+```
+
+### 5.3 手动验证
+
+1. 配置 Lobi 服务器地址
+2. 测试登录流程
+3. 测试消息收发
+4. 测试加密功能（如果支持）
+
+## 常见问题
+
+### Q: 为什么需要 Fork SDK 而不是在插件层拦截请求？
+
+A: matrix-js-sdk 内部有大量硬编码的 `/_matrix/` 路径，分布在 50+ 个文件中。在插件层拦截需要重写 SDK 的 HTTP 层，复杂度与 Fork 相当。
+
+### Q: 如何同步上游更新？
+
+A: 在 fork 的仓库中添加 upstream 远程：
+
+```bash
+git remote add upstream https://github.com/matrix-org/matrix-js-sdk.git
+
+# 同步更新
+git fetch upstream
+git checkout lobi-fork
+git merge upstream/main
+
+# 重新执行替换脚本
+./sdk-replace-paths.sh
+
+# 发布新版本
+npm version patch  # 或 minor/major
+npm publish
+```
+
+### Q: Lobi 协议与 Matrix 协议有何不同？
+
+A: 除了 API 路径前缀从 `/_matrix/` 改为 `/_lobi/` 外，还需要确认：
+- 认证方式是否相同（m.login.password）
+- 同步协议是否相同（/sync）
+- 加密协议是否兼容（E2E encryption）
+- 媒体下载端点是否相同（/media/v3/download）
+
+### Q: 如何处理加密模块？
+
+A: 加密模块 `@matrix-org/matrix-sdk-crypto-nodejs` 和 `@matrix-org/matrix-sdk-crypto-wasm` 也需要检查：
+- 如果这些模块内部也调用 Matrix API，需要 Fork 并修改
+- 如果仅处理加密逻辑而不直接调用 API，则无需修改
+
+```bash
+# 检查加密模块是否包含硬编码路径
+grep -r "_matrix" node_modules/@matrix-org/matrix-sdk-crypto-nodejs/ 2>/dev/null || echo "未找到 _matrix 路径"
+```
+
+## 替代方案
+
+如果 Fork SDK 维护成本过高，可以考虑：
+
+### 方案 B: 请求拦截器（部分实现）
+
+在 `src/matrix/sdk/transport.ts` 中添加路径重写：
+
+```typescript
+function rewriteMatrixToLobi(endpoint: string): string {
+  return endpoint.replace(/^\/_matrix\//, '/_lobi/');
+}
+
+// 在 performMatrixRequest 中调用
+const endpoint = rewriteMatrixToLobi(params.endpoint);
+```
+
+但此方法无法处理 SDK 内部直接构造的 URL。
+
+### 方案 C: 反向代理
+
+在 Lobi 服务器前部署反向代理，将 `/_matrix/` 路径重写为 `/_lobi/`：
+
+```nginx
+server {
+    listen 443;
+    server_name lobi.example.com;
+    
+    location /_matrix/ {
+        rewrite ^/_matrix/(.*)$ /_lobi/$1 break;
+        proxy_pass http://lobi-backend/;
+    }
+}
+```
+
+此方案无需修改代码，但需要额外的运维成本。

package/helper-api.ts

@@ -0,0 +1,3 @@
+export * from "./src/account-selection.js";
+export * from "./src/env-vars.js";
+export * from "./src/storage-paths.js";

package/index.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+import { createTestPluginApi } from "../../test/helpers/plugins/plugin-api.js";
+import { registerMatrixCliMetadata } from "./cli-metadata.js";
+import entry from "./index.js";
+
+const cliMocks = vi.hoisted(() => ({
+  registerMatrixCli: vi.fn(),
+}));
+
+vi.mock("./src/cli.js", async () => {
+  const actual = await vi.importActual<typeof import("./src/cli.js")>("./src/cli.js");
+  return {
+    ...actual,
+    registerMatrixCli: cliMocks.registerMatrixCli,
+  };
+});
+
+describe("lobi plugin", () => {
+  it("registers lobi CLI through a descriptor-backed lazy registrar", async () => {
+    const registerCli = vi.fn();
+    const registerGatewayMethod = vi.fn();
+    const api = createTestPluginApi({
+      id: "lobi",
+      name: "Lobi",
+      source: "test",
+      config: {},
+      runtime: {} as never,
+      registrationMode: "cli-metadata",
+      registerCli,
+      registerGatewayMethod,
+    });
+
+    registerMatrixCliMetadata(api);
+
+    const registrar = registerCli.mock.calls[0]?.[0];
+    expect(registerCli).toHaveBeenCalledWith(expect.any(Function), {
+      descriptors: [
+        {
+          name: "lobi",
+          description: "Manage Lobi accounts, verification, devices, and profile state",
+          hasSubcommands: true,
+        },
+      ],
+    });
+    expect(typeof registrar).toBe("function");
+    expect(cliMocks.registerMatrixCli).not.toHaveBeenCalled();
+
+    const program = { command: vi.fn() };
+    const result = registrar?.({ program } as never);
+
+    await result;
+    expect(cliMocks.registerMatrixCli).toHaveBeenCalledWith({ program });
+    expect(registerGatewayMethod).not.toHaveBeenCalled();
+  });
+
+  it("keeps runtime bootstrap and CLI metadata out of setup-only registration", () => {
+    expect(entry.kind).toBe("bundled-channel-entry");
+    expect(entry.id).toBe("lobi");
+    expect(entry.name).toBe("Lobi");
+  });
+});

package/index.ts

@@ -0,0 +1,65 @@
+import { defineBundledChannelEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { registerMatrixCliMetadata } from "./cli-metadata.js";
+
+export default defineBundledChannelEntry({
+  id: "lobi",
+  name: "Lobi",
+  description: "Lobi - The official A2A (Agent-to-Agent) messaging platform by Lobisland. Designed from the ground up for AI-driven communication, enabling seamless interactions between intelligent agents.",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "matrixPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setMatrixRuntime",
+  },
+  registerCliMetadata: registerMatrixCliMetadata,
+  registerFull(api) {
+    // Initialize default Lobi configuration if not exists
+    const config = api.config.loadConfig();
+    if (!config.channels?.lobi) {
+      api.config.updateConfig({
+        channels: {
+          ...config.channels,
+          lobi: {
+            homeserver: "https://lobi.lobisland.com/",
+          },
+        },
+      });
+      api.logger.info?.("[lobi] Initialized default configuration with Lobisland homeserver.");
+    }
+
+    void import("./plugin-entry.handlers.runtime.js")
+      .then(({ ensureMatrixCryptoRuntime }) =>
+        ensureMatrixCryptoRuntime({ log: api.logger.info }).catch((err: unknown) => {
+          const message = formatErrorMessage(err);
+          api.logger.warn?.(`matrix: crypto runtime bootstrap failed: ${message}`);
+        }),
+      )
+      .catch((err: unknown) => {
+        const message = formatErrorMessage(err);
+        api.logger.warn?.(`matrix: failed loading crypto bootstrap runtime: ${message}`);
+      });
+
+    api.registerGatewayMethod("lobi.verify.recoveryKey", async (ctx) => {
+      const { handleVerifyRecoveryKey } = await import("./plugin-entry.handlers.runtime.js");
+      await handleVerifyRecoveryKey(ctx);
+    });
+
+    api.registerGatewayMethod("lobi.verify.bootstrap", async (ctx) => {
+      const { handleVerificationBootstrap } = await import("./plugin-entry.handlers.runtime.js");
+      await handleVerificationBootstrap(ctx);
+    });
+
+    api.registerGatewayMethod("lobi.verify.status", async (ctx) => {
+      const { handleVerificationStatus } = await import("./plugin-entry.handlers.runtime.js");
+      await handleVerificationStatus(ctx);
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "lobi",
+  "channels": ["lobi"],
+  "channelEnvVars": {
+    "lobi": [
+      "LOBI_HOMESERVER",
+      "LOBI_USER_ID",
+      "LOBI_ACCESS_TOKEN",
+      "LOBI_PASSWORD",
+      "LOBI_DEVICE_ID",
+      "LOBI_DEVICE_NAME",
+      "LOBI_OPS_HOMESERVER",
+      "LOBI_OPS_ACCESS_TOKEN",
+      "LOBI_OPS_DEVICE_ID",
+      "LOBI_OPS_DEVICE_NAME"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@archipelagolab/lobi",
+  "version": "1.0.0",
+  "description": "Lobi - The official A2A (Agent-to-Agent) messaging platform by Lobisland. Built for AI, enabling seamless communication between intelligent agents.",
+  "type": "module",
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "@matrix-org/matrix-sdk-crypto-wasm": "18.0.0",
+    "fake-indexeddb": "^6.2.5",
+    "markdown-it": "14.1.1",
+    "@archipelagolab/lobi-js-sdk": "1.0.2",
+    "music-metadata": "^11.12.3"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "*",
+    "openclaw": ">=2026.3.13"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.13"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "lobi",
+      "label": "Lobi",
+      "selectionLabel": "Lobi",
+      "docsPath": "/channels/lobi",
+      "docsLabel": "lobi",
+      "blurb": "Lobi - Lobisland's official A2A messaging platform designed for AI agents. Install to enable intelligent agent communication.",
+      "order": 70,
+      "quickstartAllowFrom": true,
+      "persistedAuthState": {
+        "specifier": "./auth-presence",
+        "exportName": "hasAnyLobiAuth"
+      }
+    },
+    "install": {
+      "npmSpec": "@archipelagolab/lobi",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.13",
+      "allowInvalidConfigRecovery": true
+    }
+  }
+}

package/plugin-entry.handlers.runtime.ts

@@ -0,0 +1 @@
+export * from "./src/plugin-entry.runtime.ts";

package/runtime-api.ts

@@ -0,0 +1,54 @@
+// Keep the external runtime API light so Jiti callers can resolve Matrix config
+// helpers without traversing the full plugin-sdk/runtime graph or bootstrapping
+// matrix-js-sdk during plain runtime-api import.
+export * from "./src/auth-precedence.js";
+export {
+  requiresExplicitMatrixDefaultAccount,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "./src/account-selection.js";
+export * from "./src/account-selection.js";
+export * from "./src/env-vars.js";
+export * from "./src/storage-paths.js";
+export { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./src/matrix/deps.js";
+export {
+  assertHttpUrlTargetsPrivateNetwork,
+  closeDispatcher,
+  createPinnedDispatcher,
+  resolvePinnedHostnameWithPolicy,
+  ssrfPolicyFromDangerouslyAllowPrivateNetwork,
+  ssrfPolicyFromAllowPrivateNetwork,
+  type LookupFn,
+  type SsrFPolicy,
+} from "openclaw/plugin-sdk/ssrf-runtime";
+export {
+  setMatrixThreadBindingIdleTimeoutBySessionKey,
+  setMatrixThreadBindingMaxAgeBySessionKey,
+} from "./src/matrix/thread-bindings-shared.js";
+export { setMatrixRuntime } from "./src/runtime.js";
+export { writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
+export type {
+  ChannelDirectoryEntry,
+  ChannelMessageActionContext,
+  OpenClawConfig,
+  PluginRuntime,
+  RuntimeLogger,
+  RuntimeEnv,
+  WizardPrompter,
+} from "openclaw/plugin-sdk/matrix-runtime-shared";
+export { formatZonedTimestamp } from "openclaw/plugin-sdk/matrix-runtime-shared";
+
+export function chunkTextForOutbound(text: string, limit: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+  while (remaining.length > limit) {
+    const window = remaining.slice(0, limit);
+    const splitAt = Math.max(window.lastIndexOf("\n"), window.lastIndexOf(" "));
+    const breakAt = splitAt > 0 ? splitAt : limit;
+    chunks.push(remaining.slice(0, breakAt).trimEnd());
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+  if (remaining.length > 0 || text.length === 0) {
+    chunks.push(remaining);
+  }
+  return chunks;
+}

package/runtime-heavy-api.ts

@@ -0,0 +1 @@
+export * from "./src/matrix-migration.runtime.js";

package/scripts/migrate-to-lobi.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# migrate-to-lobi.sh
+# 将 Matrix 插件从 _matrix 路径迁移到 _lobi 路径
+
+set -e
+
+echo "=== Matrix to Lobi 迁移脚本 ==="
+echo ""
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# 检查是否在正确的目录
+if [ ! -f "package.json" ] || [ ! -d "src" ]; then
+    echo -e "${RED}错误: 请在 extensions/matrix 目录下运行此脚本${NC}"
+    exit 1
+fi
+
+echo -e "${YELLOW}步骤 1: 修改 package.json 使用 Fork 的 SDK${NC}"
+# 备份原文件
+cp package.json package.json.backup
+# 替换依赖名称
+sed -i '' 's/"matrix-js-sdk": "41.3.0"/"@your-org\/lobi-js-sdk": "41.3.0-lobi.1"/' package.json
+echo -e "${GREEN}✓ package.json 已修改${NC}"
+
+echo ""
+echo -e "${YELLOW}步骤 2: 替换源码中的导入路径${NC}"
+# 替换所有 matrix-js-sdk 导入为 @your-org/lobi-js-sdk
+find src -type f -name "*.ts" ! -name "*.test.ts" -exec sed -i '' 's/from "matrix-js-sdk/from "@your-org\/lobi-js-sdk/g' {} +
+find src -type f -name "*.ts" ! -name "*.test.ts" -exec sed -i '' "s/from 'matrix-js-sdk/from '@your-org\/lobi-js-sdk/g" {} +
+echo -e "${GREEN}✓ 导入路径已替换${NC}"
+
+echo ""
+echo -e "${YELLOW}步骤 3: 替换硬编码的 _matrix API 路径${NC}"
+# 替换所有硬编码的 _matrix 路径为 _lobi
+find src -type f -name "*.ts" ! -name "*.test.ts" -exec sed -i '' 's/\/_matrix\//\/_lobi\//g' {} +
+echo -e "${GREEN}✓ API 路径已替换${NC}"
+
+echo ""
+echo -e "${YELLOW}步骤 4: 验证修改${NC}"
+echo "检查是否还有残留的 matrix-js-sdk 引用:"
+REMAINING=$(grep -r "matrix-js-sdk" src --include="*.ts" ! --include="*.test.ts" | wc -l)
+if [ "$REMAINING" -gt 0 ]; then
+    echo -e "${YELLOW}警告: 发现 $REMAINING 处残留的 matrix-js-sdk 引用:${NC}"
+    grep -r "matrix-js-sdk" src --include="*.ts" ! --include="*.test.ts"
+else
+    echo -e "${GREEN}✓ 无残留的 matrix-js-sdk 引用${NC}"
+fi
+
+echo ""
+echo "检查是否还有残留的 _matrix 路径:"
+REMAINING_MATRIX=$(grep -r "\/_matrix\/" src --include="*.ts" ! --include="*.test.ts" | wc -l)
+if [ "$REMAINING_MATRIX" -gt 0 ]; then
+    echo -e "${YELLOW}警告: 发现 $REMAINING_MATRIX 处残留的 _matrix 路径:${NC}"
+    grep -r "\/_matrix\/" src --include="*.ts" ! --include="*.test.ts"
+else
+    echo -e "${GREEN}✓ 无残留的 _matrix 路径${NC}"
+fi
+
+echo ""
+echo -e "${GREEN}=== 迁移完成！===${NC}"
+echo ""
+echo "下一步操作:"
+echo "1. 确保已发布 @your-org/lobi-js-sdk 到 npm"
+echo "2. 运行 pnpm install 安装新依赖"
+echo "3. 运行 pnpm build 构建插件"
+echo "4. 运行测试验证功能"
+echo ""
+echo "如需恢复，请执行: mv package.json.backup package.json"

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "matrixPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});