koishi-plugin-mai-bridge 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# mai-bridge
+
+将 maibot 作为 Docker 托管的消息回复后端运行，使用 mai.ko 桥接 Koishi 与 maibot 的消息收发。
+
+mai-bridge 不重写 maibot 的对话链、记忆系统和插件机制。它负责在 Koishi 侧完成三件事：
+
+- 自动准备 MaiBot 源码，应用 Koishi 适配补丁。
+- 构建并启动 `maimai-ko` Docker 容器。
+- 把 Koishi 消息转发给 maibot，再把 maibot 回复发回原会话。
+
+## 安装
+
+在 Koishi 控制台打开插件市场，搜索并安装：
+
+```text
+mai-bridge
+```
+
+插件包名：
+
+```text
+koishi-plugin-mai-bridge
+```
+
+同时需要启用 Koishi 的 HTTP 服务：
+
+```text
+@koishijs/plugin-http
+```
+
+## 运行要求
+
+默认模式使用 Docker。
+
+Koishi 所在环境需要能执行 Docker 命令，并能访问 Docker socket：
+
+```text
+/var/run/docker.sock
+```
+
+如果 Koishi 本身也运行在 Docker 内，需要把 Docker socket 挂载进 Koishi 容器，并确保容器里有 `docker`、`git`、`patch` 命令。
+
+## 基础配置
+
+插件市场安装后，进入插件配置页。
+
+常用配置：
+
+```yaml
+processMode: docker
+autoPrepareMaibot: true
+acceptMaibotAgreements: true
+dockerContainerName: maimai-ko
+dockerImageName: maimai-ko:latest
+apiHost: maimai-ko
+apiPort: 8090
+webuiEnabled: true
+webuiHost: 0.0.0.0
+webuiPort: 8002
+messageMode: coexist
+```
+
+说明：
+
+- `processMode` 保持 `docker`，插件会自动拉取 MaiBot、打补丁、构建镜像并启动容器。
+- `acceptMaibotAgreements` 默认关闭。确认接受 MaiBot 的 EULA 和隐私条款后再开启。
+- `apiKey` 可以留空。插件会生成并复用运行期密钥。
+- `dockerNetwork` 按你的 Koishi Docker 网络填写。Koishi 需要能通过 `apiHost` 访问 `maimai-ko`。
+- `webuiPublicUrl` 可填写反代或宿主机映射后的 WebUI 地址，用于 Koishi 控制台显示入口。
+
+## 消息模式
+
+```yaml
+messageMode: coexist
+```
+
+可选值：
+
+- `coexist`：消息转发给 maibot 后，继续交给其他 Koishi 插件处理。
+- `exclusive`：消息转发给 maibot 后，不再交给后续插件。
+- `command`：只有命中指定前缀时才转发。
+
+## 常用命令
+
+```text
+mai.ko.status
+mai.ko.prepare
+mai.ko.docker.start
+mai.ko.docker.stop
+mai.ko.docker.restart
+mai.ko.reconnect
+```
+
+## 开发
+
+```bash
+npm install
+npm test -- --reporter dot
+npm run build
+```
+
+发布 npm 前检查打包内容：
+
+```bash
+npm pack --dry-run
+```
+
+## 许可证
+
+GPL-3.0-or-later

package/client/index.ts

@@ -0,0 +1,11 @@
+import { Context } from '@koishijs/client'
+import Page from './page.vue'
+
+export default (ctx: Context) => {
+  ctx.page({
+    name: 'mai.ko',
+    path: '/mai-ko',
+    authority: 3,
+    component: Page,
+  })
+}

package/client/page.vue

@@ -0,0 +1,148 @@
+<template>
+  <k-layout>
+    <k-card>
+      <template #header>
+        <span>mai.ko 托管状态</span>
+      </template>
+      <p>进程：{{ status?.process.state || 'unknown' }}</p>
+      <p>准备：{{ status?.prepare.state || 'unknown' }} / {{ status?.prepare.root || '-' }}</p>
+      <p>Docker：{{ status?.docker.state || 'unknown' }} / {{ status?.docker.containerName || '-' }}</p>
+      <p>Bridge：{{ status?.transport.state || 'unknown' }}</p>
+      <p v-if="status?.bridge">中转：Koishi 收 {{ status.bridge.koishiReceived }} / 发往 mai.ko {{ status.bridge.maimSent }} / 收到 mai.ko {{ status.bridge.maimReceived }} / 回发 Koishi {{ status.bridge.koishiSent }}</p>
+      <p v-if="status?.bridge">中转异常：路由失败 {{ status.bridge.routeMissed }} / 发送失败 {{ status.bridge.sendFailed }}</p>
+      <p>WebUI：{{ webuiText }}</p>
+      <p v-if="status?.webui.token?.value">WebUI Token：<code>{{ status.webui.token.value }}</code></p>
+      <p v-else-if="status?.webui.token?.lastError">WebUI Token：{{ status.webui.token.lastError }}</p>
+      <p>PID：{{ status?.process.pid || '-' }}</p>
+      <p v-if="status?.process.blockedReason">阻塞原因：{{ status.process.blockedReason }}</p>
+      <p v-if="status?.prepare.blockedReason">准备阻塞：{{ status.prepare.blockedReason }}</p>
+      <p v-if="status?.prepare.lastError">准备错误：{{ status.prepare.lastError }}</p>
+      <p v-if="status?.docker.lastError">Docker 错误：{{ status.docker.lastError }}</p>
+      <p v-if="status?.transport.lastError">Bridge 错误：{{ status.transport.lastError }}</p>
+      <p v-if="status?.bridge?.lastError">中转错误：{{ status.bridge.lastError }}</p>
+      <k-button @click="refresh">刷新</k-button>
+      <k-button @click="start">启动</k-button>
+      <k-button @click="stop">停止</k-button>
+      <k-button @click="restart">重启</k-button>
+      <k-button @click="reconnect">重连</k-button>
+      <k-button @click="prepare">准备</k-button>
+      <k-button @click="dockerStart">Docker 启动</k-button>
+      <k-button @click="dockerStop">Docker 停止</k-button>
+      <k-button @click="dockerRestart">Docker 重启</k-button>
+      <k-button v-if="status?.webui.enabled && status?.webui.url" @click="openWebui">打开 WebUI</k-button>
+      <p v-if="status?.logsHint">{{ status.logsHint }}</p>
+      <pre v-if="status?.logs.length">{{ status.logs.slice(-20).join('\n') }}</pre>
+    </k-card>
+  </k-layout>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { send } from '@koishijs/client'
+
+interface RuntimeStatus {
+  prepare: {
+    state: string
+    root: string
+    gitUrl: string
+    gitRef: string
+    patchApplied?: boolean
+    patchChecksum?: string
+    commit?: string
+    blockedReason?: string
+    lastError?: string
+    updatedAt?: number
+  }
+  docker: {
+    state: string
+    containerName: string
+    imageName: string
+    lastError?: string
+    updatedAt?: number
+  }
+  process: {
+    state: string
+    pid?: number
+    blockedReason?: string
+  }
+  transport: {
+    state: string
+    lastError?: string
+  }
+  bridge: {
+    koishiReceived: number
+    maimSent: number
+    maimReceived: number
+    koishiSent: number
+    routeMissed: number
+    sendFailed: number
+    lastError?: string
+  }
+  webui: {
+    enabled: boolean
+    host: string
+    port: number
+    url?: string
+    publicUrl?: string
+    token?: {
+      value?: string
+      source?: string
+      path?: string
+      lastError?: string
+      loggedAt?: number
+    }
+  }
+  logs: string[]
+  logsHint?: string
+}
+
+const status = ref<RuntimeStatus>()
+const webuiText = computed(() => {
+  if (!status.value) return 'unknown'
+  if (!status.value.webui.enabled) return 'disabled'
+  return status.value.webui.url || `${status.value.webui.host}:${status.value.webui.port}`
+})
+
+async function refresh() {
+  status.value = await send('mai-ko/status')
+}
+
+async function start() {
+  status.value = await send('mai-ko/start')
+}
+
+async function stop() {
+  status.value = await send('mai-ko/stop')
+}
+
+async function restart() {
+  status.value = await send('mai-ko/restart')
+}
+
+async function reconnect() {
+  status.value = await send('mai-ko/reconnect')
+}
+
+async function prepare() {
+  status.value = await send('mai-ko/prepare')
+}
+
+async function dockerStart() {
+  status.value = await send('mai-ko/docker-start')
+}
+
+async function dockerStop() {
+  status.value = await send('mai-ko/docker-stop')
+}
+
+async function dockerRestart() {
+  status.value = await send('mai-ko/docker-restart')
+}
+
+function openWebui() {
+  if (!status.value?.webui.url) return
+  window.open(status.value.webui.url, '_blank', 'noopener,noreferrer')
+}
+
+onMounted(refresh)
+</script>

package/client/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "rootDir": ".",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "types": [
+      "@koishijs/client/global"
+    ]
+  },
+  "include": ["."]
+}

package/deploy/Dockerfile.maimai-koishi

@@ -0,0 +1,35 @@
+FROM python:3.13-slim
+
+WORKDIR /MaiMBot
+
+ENV MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED=1
+ENV PATH="/MaiMBot/.venv/bin:${PATH}"
+ENV UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
+ENV UV_LINK_MODE=copy
+ENV PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
+
+COPY pyproject.toml uv.lock ./
+
+RUN sed -i \
+      -e 's|http://deb.debian.org/debian|http://mirrors.tuna.tsinghua.edu.cn/debian|g' \
+      -e 's|http://security.debian.org/debian-security|http://mirrors.tuna.tsinghua.edu.cn/debian-security|g' \
+      /etc/apt/sources.list.d/debian.sources
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv
+
+RUN uv sync --frozen --no-dev --no-install-project
+
+RUN python -m playwright install-deps chromium \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY . .
+
+RUN chmod +x docker-entrypoint.sh
+
+EXPOSE 8000 8001 8090
+
+ENTRYPOINT [ "./docker-entrypoint.sh" ]

package/dist/index.js

@@ -0,0 +1,2 @@
+import{defineComponent as Z,ref as ee,computed as te,onMounted as oe,resolveComponent as p,openBlock as a,createBlock as F,withCtx as r,createVNode as s,createElementVNode as d,toDisplayString as o,createElementBlock as n,createCommentVNode as u,createTextVNode as l}from"vue";import{send as k}from"@koishijs/client";const ae={key:0},re={key:1},ne={key:2},ue={key:3},le={key:4},ie={key:5},se={key:6},ke={key:7},de={key:8},ve={key:9},pe={key:11},ce={key:12},fe=Z({__name:"page",setup(c){const e=ee(),P=te(()=>e.value?e.value.webui.enabled?e.value.webui.url||`${e.value.webui.host}:${e.value.webui.port}`:"disabled":"unknown");async function f(){e.value=await k("mai-ko/status")}async function h(){e.value=await k("mai-ko/start")}async function q(){e.value=await k("mai-ko/stop")}async function z(){e.value=await k("mai-ko/restart")}async function A(){e.value=await k("mai-ko/reconnect")}async function G(){e.value=await k("mai-ko/prepare")}async function J(){e.value=await k("mai-ko/docker-start")}async function L(){e.value=await k("mai-ko/docker-stop")}async function O(){e.value=await k("mai-ko/docker-restart")}function Q(){var v;(v=e.value)!=null&&v.webui.url&&window.open(e.value.webui.url,"_blank","noopener,noreferrer")}return oe(f),(v,t)=>{const i=p("k-button"),X=p("k-card"),Y=p("k-layout");return a(),F(Y,null,{default:r(()=>[s(X,null,{header:r(()=>[...t[0]||(t[0]=[d("span",null,"mai.ko 托管状态",-1)])]),default:r(()=>{var b,m,w,_,y,g,C,E,D,R,x,B,I,N,S,W,T,U,V,H,K,M,$,j;return[d("p",null,"进程："+o(((b=e.value)==null?void 0:b.process.state)||"unknown"),1),d("p",null,"准备："+o(((m=e.value)==null?void 0:m.prepare.state)||"unknown")+" / "+o(((w=e.value)==null?void 0:w.prepare.root)||"-"),1),d("p",null,"Docker："+o(((_=e.value)==null?void 0:_.docker.state)||"unknown")+" / "+o(((y=e.value)==null?void 0:y.docker.containerName)||"-"),1),d("p",null,"Bridge："+o(((g=e.value)==null?void 0:g.transport.state)||"unknown"),1),(C=e.value)!=null&&C.bridge?(a(),n("p",ae,"中转：Koishi 收 "+o(e.value.bridge.koishiReceived)+" / 发往 mai.ko "+o(e.value.bridge.maimSent)+" / 收到 mai.ko "+o(e.value.bridge.maimReceived)+" / 回发 Koishi "+o(e.value.bridge.koishiSent),1)):u("v-if",true),(E=e.value)!=null&&E.bridge?(a(),n("p",re,"中转异常：路由失败 "+o(e.value.bridge.routeMissed)+" / 发送失败 "+o(e.value.bridge.sendFailed),1)):u("v-if",true),d("p",null,"WebUI："+o(P.value),1),(R=(D=e.value)==null?void 0:D.webui.token)!=null&&R.value?(a(),n("p",ne,[t[1]||(t[1]=l("WebUI Token：",-1)),d("code",null,o(e.value.webui.token.value),1)])):(B=(x=e.value)==null?void 0:x.webui.token)!=null&&B.lastError?(a(),n("p",ue,"WebUI Token："+o(e.value.webui.token.lastError),1)):u("v-if",true),d("p",null,"PID："+o(((I=e.value)==null?void 0:I.process.pid)||"-"),1),(N=e.value)!=null&&N.process.blockedReason?(a(),n("p",le,"阻塞原因："+o(e.value.process.blockedReason),1)):u("v-if",true),(S=e.value)!=null&&S.prepare.blockedReason?(a(),n("p",ie,"准备阻塞："+o(e.value.prepare.blockedReason),1)):u("v-if",true),(W=e.value)!=null&&W.prepare.lastError?(a(),n("p",se,"准备错误："+o(e.value.prepare.lastError),1)):u("v-if",true),(T=e.value)!=null&&T.docker.lastError?(a(),n("p",ke,"Docker 错误："+o(e.value.docker.lastError),1)):u("v-if",true),(U=e.value)!=null&&U.transport.lastError?(a(),n("p",de,"Bridge 错误："+o(e.value.transport.lastError),1)):u("v-if",true),(H=(V=e.value)==null?void 0:V.bridge)!=null&&H.lastError?(a(),n("p",ve,"中转错误："+o(e.value.bridge.lastError),1)):u("v-if",true),s(i,{onClick:f},{default:r(()=>[...t[2]||(t[2]=[l("刷新",-1)])]),_:1}),s(i,{onClick:h},{default:r(()=>[...t[3]||(t[3]=[l("启动",-1)])]),_:1}),s(i,{onClick:q},{default:r(()=>[...t[4]||(t[4]=[l("停止",-1)])]),_:1}),s(i,{onClick:z},{default:r(()=>[...t[5]||(t[5]=[l("重启",-1)])]),_:1}),s(i,{onClick:A},{default:r(()=>[...t[6]||(t[6]=[l("重连",-1)])]),_:1}),s(i,{onClick:G},{default:r(()=>[...t[7]||(t[7]=[l("准备",-1)])]),_:1}),s(i,{onClick:J},{default:r(()=>[...t[8]||(t[8]=[l("Docker 启动",-1)])]),_:1}),s(i,{onClick:L},{default:r(()=>[...t[9]||(t[9]=[l("Docker 停止",-1)])]),_:1}),s(i,{onClick:O},{default:r(()=>[...t[10]||(t[10]=[l("Docker 重启",-1)])]),_:1}),(K=e.value)!=null&&K.webui.enabled&&((M=e.value)!=null&&M.webui.url)?(a(),F(i,{key:10,onClick:Q},{default:r(()=>[...t[11]||(t[11]=[l("打开 WebUI",-1)])]),_:1})):u("v-if",true),($=e.value)!=null&&$.logsHint?(a(),n("p",pe,o(e.value.logsHint),1)):u("v-if",true),(j=e.value)!=null&&j.logs.length?(a(),n("pre",ce,o(e.value.logs.slice(-20).join(`
+`)),1)):u("v-if",true)]}),_:1})]),_:1})}}}),we=c=>{c.page({name:"mai.ko",path:"/mai-ko",authority:3,component:fe})};export{we as default};

package/out/bridge/agreements.d.ts

@@ -0,0 +1,12 @@
+export interface AgreementOptions {
+    accept: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export type AgreementResult = {
+    ok: true;
+    env: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function prepareAgreementEnv(root: string, options: AgreementOptions): AgreementResult;

package/out/bridge/agreements.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareAgreementEnv = prepareAgreementEnv;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+function prepareAgreementEnv(root, options) {
+    const eula = (0, path_1.join)(root, 'EULA.md');
+    const privacy = (0, path_1.join)(root, 'PRIVACY.md');
+    if (!(0, fs_1.existsSync)(eula) || !(0, fs_1.existsSync)(privacy)) {
+        return {
+            ok: false,
+            reason: 'mai.ko EULA/Privacy files are missing. Check maibotRoot or finish MaiBot preparation first.',
+        };
+    }
+    const eulaHash = md5(eula);
+    const privacyHash = md5(privacy);
+    const currentEnv = options.env || process.env;
+    const eulaConfirmed = isAgreementConfirmed(root, 'eula.confirmed', 'EULA_AGREE', eulaHash, currentEnv);
+    const privacyConfirmed = isAgreementConfirmed(root, 'privacy.confirmed', 'PRIVACY_AGREE', privacyHash, currentEnv);
+    if (eulaConfirmed && privacyConfirmed)
+        return { ok: true, env: {} };
+    if (!options.accept) {
+        return {
+            ok: false,
+            reason: 'mai.ko EULA/Privacy is not confirmed. Run mai.ko once manually or set acceptMaibotAgreements=true.',
+        };
+    }
+    return {
+        ok: true,
+        env: {
+            EULA_AGREE: eulaHash,
+            PRIVACY_AGREE: privacyHash,
+        },
+    };
+}
+function isAgreementConfirmed(root, fileName, envName, expected, env) {
+    if (env[envName] === expected)
+        return true;
+    const path = (0, path_1.join)(root, fileName);
+    if (!(0, fs_1.existsSync)(path))
+        return false;
+    return (0, fs_1.readFileSync)(path, 'utf8').trim() === expected;
+}
+function md5(path) {
+    return (0, crypto_1.createHash)('md5').update((0, fs_1.readFileSync)(path)).digest('hex');
+}

package/out/bridge/convert.d.ts

@@ -0,0 +1,25 @@
+import { type Awaitable, type Fragment, type Session } from 'koishi';
+import type { Config } from '../config';
+import type { KoishiRoute, MaimApiMessage } from '../types';
+export interface SessionToMaimOptions {
+    resolveImage?: (source: string) => Awaitable<string | undefined>;
+    replyContext?: ReplyContext;
+}
+export interface ReplyContext {
+    targetMessageId: string;
+    targetMessageContent?: string;
+    targetMessageSenderId?: string;
+    targetMessageSenderNickname?: string;
+    targetMessageSenderCardname?: string;
+    contextCount?: number;
+}
+export declare function sessionToMaimMessage(session: Session, route: KoishiRoute, apiKey: string, options?: SessionToMaimOptions): Promise<MaimApiMessage>;
+export declare function maimMessageToFragment(message: MaimApiMessage): Fragment;
+export declare function getRouteIdFromMaim(message: MaimApiMessage): string | undefined;
+export declare function getFallbackRouteHints(message: MaimApiMessage): {
+    channelId: string | undefined;
+    userId: string | undefined;
+    selfId: string | undefined;
+    isDirect: boolean;
+};
+export declare function shouldForwardSession(session: Session, config: Config): boolean;