ylib-syim 0.0.1

package/README.md

@@ -0,0 +1,376 @@
+# @ylib/syim
+
+多 IM（钉钉、飞书等）/ 多 Agent 的会话路由与上下文管理，支持 `/new`、`/reset` 重开上下文。可作为库接入现有项目，或配合 OpenClaw 使用。
+
+本仓库为**独立项目**（已从 OpenClaw monorepo 拆出），依赖用 **npm** 管理。
+
+## 钉钉桥接（连接远程 yuce-gpt Gateway）
+
+本地调试：
+
+```bash
+npm install
+npx tsx scripts/dingtalk-stdio-bridge.ts
+```
+
+**打包成单文件 JS（仍需本机 Node，分发更方便）**：
+
+```bash
+npm run build:bridge
+node dist/dingtalk-stdio-bridge.cjs
+```
+
+`build:bridge` 外置上述重型依赖并 **默认压缩**，产物约 **200KB+**（未压缩调试用 `npm run build:bridge:debug`）。运行前项目根 **`npm install`**；仅拷贝 cjs 见 `scripts/bridge-runtime-package.json`。全量单文件：`npm run build:bridge:all`。体积构成与继续缩小思路见 **[docs/packaging-二进制与分发.md](./docs/packaging-二进制与分发.md)**（文内「主库还能再缩小吗」）。
+
+说明与「真·无 Node 二进制」的可行性见 **[docs/packaging-二进制与分发.md](./docs/packaging-二进制与分发.md)**。
+
+一键安装配置 + 后台服务 + `im-agent-hub-ctl` 管理命令：见 **[scripts/install/README.md](./scripts/install/README.md)**。日常升级代码与依赖可执行 **`im-agent-hub-ctl update`**（或 `update-help` / `version` 查看说明与当前状态）。若使用 bundle，`update` 后请再执行 **`npm run build:bridge`**。
+
+仓库内默认 **`openclaw.json` 可为精简结构**：仅包含 `channels.dingtalk-connector`（钉钉插件 / `@dingtalk-real-ai/dingtalk-connector` 所需字段）。安装脚本只合并该通道，不会自动写入 `bindings` 等其它顶级键。
+
+## 直接使用方式
+
+im-agent-hub 是**库**：在你的代码里创建 Hub、配置 Router、Agents、Adapters，然后把收到的 IM 消息转成 `InboundMessage` 调用 `hub.handleInbound(input)`，回复会通过对应 adapter 发回 IM。
+
+```ts
+import {
+  createHub,
+  createDingTalkAdapter,
+  createRuleBasedRouter,
+  createInMemorySessionStore,
+  createLangChainLikeAgent,
+} from "@ylib/syim";
+
+const hub = createHub({
+  router: createRuleBasedRouter({ defaultAgentId: "main" }),
+  agents: [
+    createLangChainLikeAgent({
+      id: "main",
+      systemPrompt: "你是助手。",
+      runnable: async ({ messages }) => {
+        const last = messages[messages.length - 1];
+        return { content: `回复：${last?.content ?? ""}` };
+      },
+    }),
+  ],
+  adapters: [
+    createDingTalkAdapter({
+      config: { clientId: "钉钉 AppKey", clientSecret: "钉钉 AppSecret" },
+    }),
+  ],
+  sessions: createInMemorySessionStore(),
+});
+
+// 当从钉钉收到消息时，把事件转成 InboundMessage 再调用：
+await hub.handleInbound({
+  provider: "dingtalk",
+  peer: { kind: "direct", id: "用户 staffId" },  // 或 kind: "group", id: "群 openConversationId"
+  sender: { id: "用户 id", name: "用户名" },
+  messageId: "消息 id",
+  timestamp: Date.now(),
+  text: "用户发的文字",
+});
+```
+
+## 多 Agent 与 Bindings（与主项目一致）
+
+主项目通过 `agents.list` + `bindings` 配置多个 agent，并按 channel/accountId/peer 匹配路由。im-agent-hub 提供相同语义：
+
+- **agents**：多个 `Agent`（每个有 `id`、`run`，可选 `meta` 做 per-agent 配置）。
+- **bindings**：`AgentRouteBinding[]`，每项为 `{ agentId, match }`。`match` 支持：`channel`、`accountId?`、`peer?`、`guildId?`（Discord）、`teamId?`（Slack）、`roles?`（角色列表）。
+- **匹配顺序**（与主项目一致）：**peer 精确** → **guildId + roles** → **guildId** → **teamId** → **account** → **channel** → **defaultAgentId**。
+
+**方式一：用 createRouterFromBindings 自己组 Hub**
+
+```ts
+import {
+  createHub,
+  createRouterFromBindings,
+  createDingTalkAdapter,
+  createInMemorySessionStore,
+  createLangChainLikeAgent,
+} from "@ylib/syim";
+
+const agents = [
+  createLangChainLikeAgent({ id: "main", runnable: async ({ messages }) => ({ content: "主助手回复" }) }),
+  createLangChainLikeAgent({ id: "support", runnable: async ({ messages }) => ({ content: "客服回复" }) }),
+];
+
+const hub = createHub({
+  router: createRouterFromBindings({
+    defaultAgentId: "main",
+    bindings: [
+      { agentId: "support", match: { channel: "dingtalk", peer: { kind: "group", id: "群openConversationId" } } },
+      { agentId: "main", match: { channel: "dingtalk" } },
+    ],
+  }),
+  agents,
+  adapters: [createDingTalkAdapter({ config: { clientId: "...", clientSecret: "..." } })],
+  sessions: createInMemorySessionStore(),
+});
+```
+
+**方式二：用 createHubFromConfig 一次传入配置**
+
+```ts
+import { createHubFromConfig, createDingTalkAdapter, createInMemorySessionStore, createLangChainLikeAgent } from "@ylib/syim";
+
+const hub = createHubFromConfig({
+  defaultAgentId: "main",
+  agents: [
+    createLangChainLikeAgent({ id: "main", runnable: async ({ messages }) => ({ content: "主助手" }) }),
+    createLangChainLikeAgent({ id: "support", runnable: async ({ messages }) => ({ content: "客服" }) }),
+  ],
+  adapters: [createDingTalkAdapter({ config: { clientId: "...", clientSecret: "..." } })],
+  bindings: [
+    { agentId: "support", match: { channel: "dingtalk", peer: { kind: "group", id: "某群ID" } } },
+    { agentId: "main", match: { channel: "dingtalk" } },
+  ],
+  sessions: createInMemorySessionStore(),
+});
+```
+
+同一钉钉账号下：该群消息走 `support`，其他单聊/群走 `main`。
+
+## Session 持久化与 HTTP 入口（与主项目能力对齐）
+
+- **Session 持久化**：`createFileSessionStore({ dir? })` 将会话落盘（默认 `~/.openclaw/im-agent-hub/sessions`），pm2 重启后会话可恢复。`pnpm run dev` 时设置 `PERSIST_SESSIONS=1` 或 `SESSION_DIR=/path` 即可启用。
+- **HTTP 入口**：`createInboundServer({ hub, healthPath?, auth? })` / `startInboundServer({ hub, port })` 提供 `GET /health`、`POST /inbound`；可选 `auth: { type: 'bearer' | 'api-key', token }`。
+
+## 媒体、记忆与工具（与主项目能力对齐）
+
+- **入站附件**：`downloadInboundAttachments(input, { dir?, timeoutMs? })` 将 `input.attachments` 中带 `url` 的项下载到本地并填回 `path`，再交 `hub.handleInbound`。
+- **出站附件**：`OutboundMessage.attachments` 可带 `{ path, contentType?, fileName? }`，钉钉 adapter 会上传后发文件消息。
+- **记忆**：`HubConfig.memory` 传入 `MemoryStore`（如 `createInMemoryMemoryStore()`），hub 会注入到 `agent.run({ memory })`。
+- **工具**：`HubConfig.tools` 为 `Record<string, (args) => Promise<string>>`；agent 返回 `toolCalls` 时 hub 执行并拼入回复。
+- **白名单**：`HubConfig.allowFrom?: (input: InboundMessage) => boolean`，仅当返回 true 时处理消息。
+
+## 如何测试（单 agent 收所有 IM）
+
+用「一个简单 agent 接收所有 IM 消息」来验证 Hub 与路由是否正常。
+
+### 1. 启动示例服务
+
+在 `packages/im-agent-hub` 下执行：
+
+```bash
+cd packages/im-agent-hub
+pnpm install
+# 可选：配置钉钉后回复会真实发到钉钉；不配置则仅 HTTP 测试，回复在控制台打印
+DINGTALK_CLIENT_ID=你的AppKey DINGTALK_CLIENT_SECRET=你的AppSecret pnpm run example:single-agent
+```
+
+服务监听 `http://localhost:3100`（可用 `PORT=3000` 改端口）。
+
+### 2. 用 curl 模拟一条 IM 消息
+
+任意一条「入站消息」都会路由到同一个 agent（`main`），并得到回复 `[测试 agent] 收到：xxx`。
+
+单聊示例（把 `YOUR_STAFF_ID` 换成你的钉钉 userId）：
+
+```bash
+curl -X POST http://localhost:3100/inbound -H "Content-Type: application/json" -d '{
+  "provider": "dingtalk",
+  "peer": { "kind": "direct", "id": "YOUR_STAFF_ID" },
+  "sender": { "id": "YOUR_STAFF_ID", "name": "测试" },
+  "messageId": "test-1",
+  "timestamp": 1700000000000,
+  "text": "你好"
+}'
+```
+
+成功时返回 `{"ok":true,"text":"你好","agentId":"main"}`。若已配置钉钉，钉钉端会收到 `[测试 agent] 收到：你好`。
+
+### 3. 测试 /new、/reset
+
+再发一条，内容为 `/new` 或 `/reset`：
+
+```bash
+curl -X POST http://localhost:3100/inbound -H "Content-Type: application/json" -d '{"provider":"dingtalk","peer":{"kind":"direct","id":"YOUR_STAFF_ID"},"sender":{"id":"YOUR_STAFF_ID","name":"测试"},"messageId":"test-2","timestamp":1700000000000,"text":"/new"}'
+```
+
+会返回成功，且若配置了钉钉会收到「已开启新的上下文。」。
+
+### 4. 用真实钉钉收消息
+
+若要让「钉钉里发消息 → 同一 agent 回复」，可再开一个终端跑 Stream 收消息（与上面示例共用同一套 agent 逻辑）：
+
+```bash
+DINGTALK_CLIENT_ID=xxx DINGTALK_CLIENT_SECRET=yyy pnpm run start:dingtalk
+```
+
+钉钉里给机器人发消息，会由 `start:dingtalk` 里的 Hub 处理并回发（该脚本内也是单 agent，逻辑与 example-single-agent 一致）。
+
+## 使用 iflow 接口作为 Agent
+
+若后端是 **iflow（OpenAI 兼容）** 接口，可用内置的 `createIflowAgent`，让所有 IM 消息对接该 agent。
+
+### 环境变量
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `IFLOW_API_KEY` | 是 | API Key，**请勿写入代码**，仅通过环境变量传入 |
+| `IFLOW_BASE_URL` | 否 | 默认 `http://92.113.117.22:10068/proxy/iflow` |
+
+### 一键跑示例（HTTP + 可选钉钉回发）
+
+```bash
+cd packages/im-agent-hub
+export IFLOW_API_KEY=sk-你的key
+# 可选：钉钉回发
+export DINGTALK_CLIENT_ID=xxx
+export DINGTALK_CLIENT_SECRET=yyy
+pnpm run example:iflow-agent
+```
+
+然后 `curl -X POST http://localhost:3100/inbound ...` 或钉钉内发消息，回复由 iflow 接口生成。
+
+### 在代码中使用
+
+```ts
+import { createHubFromConfig, createIflowAgent, createDingTalkAdapter, createInMemorySessionStore } from "@ylib/syim";
+
+const hub = createHubFromConfig({
+  defaultAgentId: "main",
+  agents: [
+    createIflowAgent({
+      id: "main",
+      systemPrompt: "你是助手。",
+      historyLimit: 20,
+      // baseUrl / apiKey 不传则从环境变量 IFLOW_BASE_URL、IFLOW_API_KEY 读取
+    }),
+  ],
+  adapters: [createDingTalkAdapter({ config: { clientId: "...", clientSecret: "..." } })],
+  bindings: [{ agentId: "main", match: { channel: "dingtalk" } }],
+  sessions: createInMemorySessionStore(),
+});
+```
+
+## 本地测试钉钉 IM
+
+不跑完整 OpenClaw 和钉钉 connector 时，可以用包里的**开发服务器**只测「Hub + 钉钉发送」是否正常。
+
+### 1. 安装依赖
+
+在 openclaw 仓库根目录执行：
+
+```bash
+pnpm install
+```
+
+### 2. 配置钉钉应用
+
+- 在 [钉钉开放平台](https://open.dingtalk.com/) 创建企业内部应用，拿到 **AppKey**（clientId）和 **AppSecret**（clientSecret）。
+- 开通机器人能力、单聊/群聊发送权限（与 [dingtalk-openclaw-connector](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector) 文档一致）。
+
+### 3. 启动开发服务器
+
+在 `packages/im-agent-hub` 下执行（需先 `pnpm install` 以安装 tsx）：
+
+```bash
+cd packages/im-agent-hub
+DINGTALK_CLIENT_ID=你的AppKey DINGTALK_CLIENT_SECRET=你的AppSecret pnpm run dev
+```
+
+或先导出环境变量再启动：
+
+```bash
+export DINGTALK_CLIENT_ID=你的AppKey
+export DINGTALK_CLIENT_SECRET=你的AppSecret
+pnpm run dev
+```
+
+服务会在 `http://localhost:3100` 启动（可通过 `PORT=3000 pnpm run dev` 改端口）。
+
+### 4. 发送测试消息
+
+- **单聊**：`peer.id` 填你的钉钉 **staffId**（或 unionId，视应用权限而定）。
+- **群聊**：`peer` 填 `{ "kind": "group", "id": "群的 openConversationId" }`。
+
+示例（单聊，把 `YOUR_STAFF_ID` 换成真实 userId）：
+
+```bash
+curl -X POST http://localhost:3100/inbound \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "dingtalk",
+    "peer": { "kind": "direct", "id": "YOUR_STAFF_ID" },
+    "sender": { "id": "YOUR_STAFF_ID", "name": "测试" },
+    "messageId": "test-1",
+    "timestamp": 1700000000000,
+    "text": "你好"
+  }'
+```
+
+成功时接口返回 `{"ok":true,"text":"你好"}`，钉钉端会收到机器人回复（当前 dev-server 为 echo 风格：「收到：你好」）。
+
+### 5. 测试 /new、/reset
+
+对同一 peer 再发一条：
+
+```bash
+curl -X POST http://localhost:3100/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"dingtalk","peer":{"kind":"direct","id":"YOUR_STAFF_ID"},"sender":{"id":"YOUR_STAFF_ID","name":"测试"},"messageId":"test-2","timestamp":1700000000000,"text":"/new"}'
+```
+
+钉钉会收到「已开启新的上下文。」，后续消息会使用新的会话上下文。
+
+## 钉钉完整收发流程（Stream 收消息 + Hub 回发）
+
+在**不启动 OpenClaw** 的情况下，用与官方 [dingtalk-openclaw-connector](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector) 相同的 **Stream 模式**收钉钉消息，由 im-agent-hub 处理并回发。
+
+### 1. 钉钉应用配置
+
+- 在 [钉钉开放平台](https://open.dingtalk.com/) 创建**企业内部应用**，开启机器人能力。
+- 消息接收方式选择 **Stream 模式**（与官方 connector 一致），并保存 **AppKey**、**AppSecret**。
+- 为应用开通「机器人发送消息到群聊」「机器人发送单聊消息」等权限。
+
+### 2. 启动 Stream 收消息服务
+
+在 `packages/im-agent-hub` 下执行：
+
+```bash
+cd packages/im-agent-hub
+pnpm install
+DINGTALK_CLIENT_ID=你的AppKey DINGTALK_CLIENT_SECRET=你的AppSecret pnpm run start:dingtalk
+```
+
+可选：`DEBUG=1` 可打开 dingtalk-stream 调试日志。
+
+### 3. 在钉钉里发消息
+
+- **单聊**：在钉钉里找到你的机器人，发「你好」等文字，机器人会经 Hub 回复（当前为 echo：「收到：你好」）。
+- **群聊**：把机器人拉进群，在群里 @机器人 或发消息（视钉钉机器人设置），同样会走 Hub 回发。
+- 发送 **/new** 或 **/reset** 可重开会话上下文。
+
+### 4. 自定义 Agent（如接 LLM）
+
+当前 `scripts/dingtalk-stream-server.ts` 里使用的是内置 echo 风格 agent。要接真实 LLM，可复制该脚本到自己的项目，或修改脚本中的 `createLangChainLikeAgent` 的 `runnable`，改为调用你的 LangChain / OpenAI 等接口。
+
+## Connector 模式（多账号、项目配置）
+
+`pnpm run start:connector` 使用官方 dingtalk-openclaw-connector，支持多企业钉钉部署。配置读取优先级：
+
+1. **项目目录** `openclaw.json`（与 package.json 同目录）
+2. `~/.openclaw/openclaw.json`
+3. 环境变量 `DINGTALK_CLIENT_ID` / `DINGTALK_CLIENT_SECRET`（单账号）
+
+在项目根目录创建或复制 `openclaw.json`：至少配置 `channels.dingtalk-connector`。**`dingtalk-stdio-bridge`** 与精简 `openclaw.json`（仅 `channels`）即可工作；若使用 **`start:connector`** 且需多 Agent 路由，再按需增加 `bindings` 等键。
+
+## 将 /v1/chat/completions 代理到 yuce-gpt（可选）
+
+若希望 **对话能力由 yuce-gpt 提供**（复用其 Agent、技能、记忆等），可将 im-agent-hub 的 `POST /v1/chat/completions` 配置为**反向代理**到 yuce-gpt：
+
+- **yuce-gpt 端点**：`POST https://<yuce-gpt-host>/api/v1/yucegpt/v1/chat/completions`
+- **鉴权**：在代理请求头中增加 `Authorization: Bearer <OPENCLAW_GATEWAY_API_KEY>`（yuce-gpt 侧需配置同名环境变量 `OPENCLAW_GATEWAY_API_KEY` 及 `OPENCLAW_GATEWAY_TENANT_ID` / `USER_ID` / `USER_NAME`）。
+- **透传**：将 `X-OpenClaw-Agent-Id`、`X-OpenClaw-Session-Key` 及 body 原样转发。
+
+实现方式：在 `createInboundServer` 中若启用 `enableChatCompletions`，可改为不调用本地 `createChatCompletionsHandler({ hub })`，而是将请求 proxy 到上述 yuce-gpt URL（需自行用 fetch/axios 或 nginx 做反向代理）。详见 yuce-gpt 仓库文档：`doc/OpenClaw与ACP会话形式对接说明.md`。
+
+## 与 OpenClaw / 钉钉 connector 的关系
+
+- **im-agent-hub**：提供「会话路由 + 上下文 + 多 adapter 发送」；钉钉发送逻辑复制自官方 connector 的 OpenAPI。
+- **完整收发**可选两种方式：
+  1. **本包内置**：`pnpm run start:dingtalk` 使用 dingtalk-stream 收消息，交给 hub 处理并用本包钉钉 adapter 回发（无需 OpenClaw）。
+  2. **Connector 模式**：`pnpm run start:connector` 加载 dingtalk-openclaw-connector，支持多账号，配置从项目 `openclaw.json` 读取。

package/bin/syim.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const major = Number.parseInt(process.versions.node.split(".")[0] || "0", 10);
+if (major < 22) {
+  console.error(`[syim] Node.js >= 22 is required, current: v${process.versions.node}`);
+  console.error("[syim] please run: nvm use 22");
+  process.exit(1);
+}
+
+const thisFile = fileURLToPath(import.meta.url);
+const pkgRoot = path.resolve(path.dirname(thisFile), "..");
+const entry = path.join(pkgRoot, "bridges", "main.ts");
+const require = createRequire(import.meta.url);
+const tsxPkgJson = require.resolve("tsx/package.json", { paths: [pkgRoot] });
+const tsxCli = path.join(path.dirname(tsxPkgJson), "dist", "cli.mjs");
+
+const child = spawn(process.execPath, [tsxCli, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+

package/bridges/dingtalk-stdio-bridge.ts

@@ -0,0 +1,10 @@
+/**
+ * 主目录入口：钉钉 stdio bridge。
+ * 真实实现暂保留在 scripts，避免一次性迁移带来路径风险。
+ */
+import { setupBridgeLogger } from "./logger.ts";
+
+const logFilePath = setupBridgeLogger("dingtalk-bridge");
+console.error("[dingtalk-bridge] log file:", logFilePath);
+
+import "../scripts/dingtalk-stdio-bridge.ts";

package/bridges/lark-stdio-bridge.ts

@@ -0,0 +1,10 @@
+/**
+ * 主目录入口：飞书 stdio bridge。
+ * 真实实现暂保留在 scripts，避免一次性迁移带来路径风险。
+ */
+import { setupBridgeLogger } from "./logger.ts";
+
+const logFilePath = setupBridgeLogger("lark-bridge");
+console.error("[lark-bridge] log file:", logFilePath);
+
+import "../scripts/lark-stdio-bridge.ts";

package/bridges/logger.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+import { format } from "node:util";
+
+type ConsoleMethod = (...args: unknown[]) => void;
+
+type BridgeLoggerState = {
+  enabled: boolean;
+  logFilePath: string;
+};
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __imAgentHubBridgeLogger: BridgeLoggerState | undefined;
+}
+
+function buildLogFilePath(prefix: string): string {
+  const logsDir = path.join(process.cwd(), "logs");
+  fs.mkdirSync(logsDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(logsDir, `${prefix}-${stamp}-${process.pid}.log`);
+}
+
+function patchConsole(writeLine: (line: string) => void): void {
+  const methods: Array<keyof Console> = ["log", "info", "warn", "error", "debug"];
+  for (const method of methods) {
+    const original = console[method] as ConsoleMethod;
+    console[method] = (...args: unknown[]) => {
+      const line = format(...args);
+      writeLine(`[${new Date().toISOString()}] [${method}] ${line}`);
+      original(...args);
+    };
+  }
+}
+
+export function setupBridgeLogger(prefix: string): string {
+  const exists = globalThis.__imAgentHubBridgeLogger;
+  if (exists?.enabled) return exists.logFilePath;
+
+  const logFilePath = buildLogFilePath(prefix);
+  const stream = fs.createWriteStream(logFilePath, { flags: "a" });
+  stream.write(`[${new Date().toISOString()}] [system] bridge logger started\n`);
+
+  patchConsole((line) => stream.write(`${line}\n`));
+  globalThis.__imAgentHubBridgeLogger = { enabled: true, logFilePath };
+  return logFilePath;
+}

package/bridges/main.ts

@@ -0,0 +1,126 @@
+import { setupBridgeLogger } from "./logger.ts";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bridgeDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(bridgeDir, "..");
+
+/**
+ * 统一桥接入口。
+ *
+ * 默认同时启动钉钉和飞书两个 bridge。
+ * 可通过参数控制：
+ *   --only=dingtalk
+ *   --only=lark
+ *   --only=all
+ */
+function parseOnlyArg(): "all" | "dingtalk" | "lark" {
+  const onlyArg = process.argv.find((arg) => arg.startsWith("--only="));
+  const onlyValue = (onlyArg?.slice("--only=".length) || "all").toLowerCase();
+  if (onlyValue === "dingtalk" || onlyValue === "lark" || onlyValue === "all") {
+    return onlyValue;
+  }
+  console.warn(`[bridges/main] unknown --only value "${onlyValue}", fallback to "all"`);
+  return "all";
+}
+
+function loadOpenClawConfig(): { configPath: string; config: Record<string, unknown> } | null {
+  const configPaths = [path.join(process.cwd(), "syim.json"), path.join(os.homedir(), ".syim", "syim.json")];
+  for (const configPath of configPaths) {
+    if (!fs.existsSync(configPath)) continue;
+    try {
+      const content = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content) as Record<string, unknown>;
+      return { configPath, config };
+    } catch (err) {
+      console.error("[bridges/main] found config but failed to parse:", configPath, (err as Error).message);
+      process.exit(1);
+    }
+  }
+  return null;
+}
+
+function printConfigBootstrapGuide(): void {
+  const homeOpenClawDir = path.join(os.homedir(), ".syim");
+  const homeConfigPath = path.join(homeOpenClawDir, "syim.json");
+  const templatePath = path.join(packageRoot, "syim.json.bak");
+  const template = fs.existsSync(templatePath)
+    ? fs.readFileSync(templatePath, "utf-8")
+    : "{\n  \"error\": \"syim.json.bak not found\"\n}";
+
+  console.error("\n[syim] 未检测到配置文件。");
+  console.error("[syim] 已检查路径：");
+  console.error(`  - ${path.join(process.cwd(), "syim.json")}`);
+  console.error(`  - ${homeConfigPath}`);
+
+  console.error("\n[syim] 请执行以下命令在 Home 目录创建配置：");
+  console.error(`  mkdir -p "${homeOpenClawDir}"`);
+  console.error(`  cp "${templatePath}" "${homeConfigPath}"`);
+
+  console.error("\n[syim] 打开配置文件进行编辑（macOS）：");
+  console.error(`  open -a TextEdit "${homeConfigPath}"`);
+  console.error("\n[syim] 或使用命令行编辑器：");
+  console.error(`  nano "${homeConfigPath}"`);
+  console.error("\n[syim] 或使用 VS Code：");
+  console.error(`  code "${homeConfigPath}"`);
+
+  console.error("\n[syim] 配置模板（来自 syim.json.bak）：\n");
+  console.error(template);
+
+  console.error("\n[syim] 字段说明：");
+  console.error("- channels: 渠道配置集合。");
+  console.error("- channels.feishu.enabled: 是否启用飞书渠道。");
+  console.error("- channels.feishu.accounts.<id>.appId/appSecret: 飞书应用凭据。");
+  console.error("- channels.feishu.accounts.<id>.gatewayBaseUrl: 网关地址。");
+  console.error("- channels.feishu.accounts.<id>.gatewayToken: 网关鉴权 token。");
+  console.error("- channels.feishu.accounts.<id>.dmPolicy/allowFrom: 私聊与来源策略。");
+  console.error("- channels.feishu.accounts.<id>.separateSessionByConversation/groupSessionScope: 会话隔离策略。");
+  console.error("- channels.feishu.accounts.<id>.streaming: 是否流式回复。");
+  console.error("- channels.feishu.accounts.<id>.uploadHost: 上传服务地址。");
+  console.error("- channels.dingtalk-connector.enabled: 是否启用钉钉渠道。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.clientId/clientSecret: 钉钉应用凭据。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.gatewayBaseUrl/gatewayToken: 网关地址与鉴权。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.modelName: 模型标识。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.asyncMode: 是否异步模式。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.gatewayPort: 本地网关端口（部分模式使用）。");
+  console.error("- channels.dingtalk-connector.accounts.<id>.uploadHost: 上传服务地址。");
+  console.error("- bindings: 渠道路由规则。");
+  console.error("- bindings[].agentId: 目标 Agent ID。");
+  console.error("- bindings[].match.channel: 命中的渠道。");
+}
+
+async function main(): Promise<void> {
+  const logFilePath = setupBridgeLogger("bridges-main");
+  console.error("[bridges/main] log file:", logFilePath);
+
+  const loaded = loadOpenClawConfig();
+  if (!loaded) {
+    printConfigBootstrapGuide();
+    process.exit(1);
+  }
+  console.error("[bridges/main] config loaded:", loaded.configPath);
+
+  const only = parseOnlyArg();
+  const tasks: Array<Promise<unknown>> = [];
+
+  if (only === "all" || only === "dingtalk") {
+    console.error("[bridges/main] starting dingtalk bridge...");
+    tasks.push(import("./dingtalk-stdio-bridge.ts"));
+  }
+
+  if (only === "all" || only === "lark") {
+    console.error("[bridges/main] starting lark bridge...");
+    tasks.push(import("./lark-stdio-bridge.ts"));
+  }
+
+  // 两个模块内部都以长驻服务运行；这里仅确保入口导入完成。
+  await Promise.all(tasks);
+  console.error(`[bridges/main] started: ${only}`);
+}
+
+main().catch((err) => {
+  console.error("[bridges/main]", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "ylib-syim",
+  "version": "0.0.1",
+  "description": "多 IM / 多 Agent 的会话路由与上下文管理（支持 /new）",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "syim": "./bin/syim.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "bridges",
+    "scripts",
+    "README.md",
+    "syim.json.bak"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "tsx scripts/dev-server.ts",
+    "start": "tsx src/cli.ts start",
+    "start:dingtalk": "tsx scripts/dingtalk-stream-server.ts",
+    "example:single-agent": "tsx scripts/example-single-agent.ts",
+    "example:iflow-agent": "tsx scripts/example-iflow-agent.ts",
+    "example:feishu-webhook": "tsx scripts/example-feishu-webhook.ts",
+    "start:connector": "tsx src/connector-host.ts",
+    "start:stdio-bridge": "tsx bridges/dingtalk-stdio-bridge.ts",
+    "start:lark-bridge": "tsx bridges/lark-stdio-bridge.ts",
+    "start:bridges": "tsx bridges/main.ts",
+    "start:feishu-bridge": "tsx scripts/feishu-yuce-bridge.ts",
+    "build:bridge": "node scripts/build-bridge.mjs",
+    "build:bridge:all": "node scripts/build-bridge.mjs --all",
+    "build:bridge:debug": "node scripts/build-bridge.mjs --no-minify",
+    "start:stdio-bridge:bundle": "node dist/dingtalk-stdio-bridge.cjs"
+  },
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "ylib-dingtalk-connector": "0.7.10-beata.1",
+    "ylib-openclaw-lark": "2026.3.17-beata.1",
+    "axios": "^1.6.0",
+    "dingtalk-stream": "^2.1.4",
+    "fluent-ffmpeg": "^2.1.3",
+    "form-data": "^4.0.0",
+    "mammoth": "^1.8.0",
+    "openclaw": "2026.2.26",
+    "pdf-parse": "^1.1.1",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.4"
+  }
+}

package/scripts/bridge-runtime-package.json

@@ -0,0 +1,14 @@
+{
+  "name": "im-agent-hub-dingtalk-bridge-runtime",
+  "private": true,
+  "description": "仅拷贝 dist/dingtalk-stdio-bridge.cjs 部署时：与本文件同目录 npm install，提供 build:bridge 未打入的运行时依赖（与 im-agent-hub package.json 保持一致）",
+  "dependencies": {
+    "@dingtalk-real-ai/dingtalk-connector": "^0.7.10",
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "axios": "^1.6.0",
+    "dingtalk-stream": "^2.1.4",
+    "fluent-ffmpeg": "^2.1.3",
+    "mammoth": "^1.8.0",
+    "pdf-parse": "^1.1.1"
+  }
+}