feat(miniprogram): add WeChat mini program plugin

2026-06-04 13:30:32 +08:00 · 2026-04-27 16:08:22 +08:00
parent d55b52652c
commit d06111e5f7
27 changed files with 705 additions and 6 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -52,4 +52,7 @@ Claude.md

 # 本地测试脚本
 configure-ollama.sh
-fix-docker.sh
+fix-docker.sh
+
+# WeChat Mini Program local/private configuration
+miniprogram/project.private.config.json
--- a/README.md
+++ b/README.md
@@ -237,7 +237,7 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
 | Capability | Details |
 |------------|---------|
 | Deployment | Local / Docker / Kubernetes (Helm) with private and offline support |
-| UI | Web UI / RESTful API / Chrome Extension |
+| UI | Web UI / RESTful API / Chrome Extension / WeChat Mini Program |
 | Observability | Integrated Langfuse for ReAct loops, token tracking, tool calls, and pipeline tracing |
 | Task Management | MQ async tasks, automatic database migration on version upgrade |
 | Model Management | Centralized config, per-knowledge-base model selection, multi-tenant built-in model sharing, WeKnora Cloud hosted models and parsing |
@@ -247,6 +247,11 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
 [**WeKnora Chrome Extension**](https://chromewebstore.google.com/detail/jpemjbopikggjlmikmclgbmkhhopjdgd) lets you capture web content directly into your WeKnora knowledge base. Select text, images, or entire pages in the browser and save them as knowledge entries with one click — no copy-paste or file upload needed.


+## 📱 WeChat Mini Program
+
+The [WeKnora Mini Program](./miniprogram/README.md) provides a lightweight mobile client for configuring WeKnora API access, selecting knowledge bases, importing URLs, and asking knowledge chat from WeChat.
+
+
 ## 🦞 ClawHub Skill

 [**WeKnora ClawHub Skill**](https://clawhub.ai/lyingbug/weknora) is a WeKnora skill published on the ClawHub platform. Once installed, it enables document import (file / URL / Markdown), hybrid search (vector + keyword) across knowledge bases, and knowledge entry management — all through the WeKnora REST API.
@@ -255,7 +260,6 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
 - **Hybrid Search** — Search within or across knowledge bases with vector + keyword retrieval
 - **Knowledge Management** — List, browse, edit, and delete knowledge entries programmatically

-
 ## 🚀 Getting Started

 ### 🛠 Prerequisites
--- a/README_CN.md
+++ b/README_CN.md
@@ -235,7 +235,7 @@
 | 能力 | 详情 |
 |------|------|
 | 部署 | 本地 / Docker / Kubernetes (Helm)，支持私有化离线部署 |
-| 界面 | Web UI / RESTful API / Chrome Extension|
+| 界面 | Web UI / RESTful API / Chrome Extension / 微信小程序 |
 | 可观测性 | 集成 Langfuse 以追踪 ReAct 循环、Token 消耗、工具调用和任务流水线 |
 | 任务管理 | MQ 异步任务，版本升级自动数据库迁移 |
 | 模型管理 | 集中配置，知识库级别模型选择，多租户共享内置模型，WeKnora Cloud 托管模型与文档解析 |
@@ -245,6 +245,11 @@
 [**WeKnora Chrome 插件**](https://chromewebstore.google.com/detail/jpemjbopikggjlmikmclgbmkhhopjdgd)支持在浏览器中直接将网页内容采集到 WeKnora 知识库。选中文本、图片或整个页面，一键保存为知识条目，无需复制粘贴或手动上传文件。


+## 📱 微信小程序
+
+[**WeKnora 微信小程序**](./miniprogram/README.md) 提供轻量移动端客户端，支持配置 WeKnora API、选择知识库、导入 URL，并在微信内向知识库提问。
+
+
 ## 🦞 ClawHub Skill

 [**WeKnora ClawHub Skill**](https://clawhub.ai/lyingbug/weknora) 是 WeKnora 发布在 ClawHub 平台上的技能。安装后，可通过 WeKnora REST API 上传文档（文件 / URL / Markdown）、执行混合检索（向量 + 关键词）以及管理知识条目。
@@ -253,7 +258,6 @@
 - **混合检索** — 在单个或多个知识库中进行向量 + 关键词混合搜索
 - **知识管理** — 以编程方式浏览、编辑和删除知识条目

-
 ## 🚀 快速开始

 ### 🛠 环境要求
@@ -405,4 +409,3 @@ WeKnora/
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Tencent/WeKnora&type=date&legend=top-left" />
 </picture>
 </a>
-
--- a/miniprogram/README.md
+++ b/miniprogram/README.md
@@ -0,0 +1,31 @@
+# WeKnora Mini Program
+
+This directory contains a WeChat Mini Program plugin for WeKnora. It gives mobile users a lightweight entry point to:
+
+- configure a WeKnora API endpoint and tenant API key;
+- list available knowledge bases;
+- import a URL into a selected knowledge base;
+- ask a selected knowledge base through WeKnora knowledge chat.
+
+## Getting started
+
+1. Open `miniprogram/` in WeChat DevTools.
+2. Copy `project.private.config.json.example` to `project.private.config.json` and set your real Mini Program AppID. The shared `project.config.json` intentionally does not include an AppID to avoid forcing maintainers into a placeholder project.
+3. Open the **Settings** tab and fill in:
+   - API Base URL, for example `https://weknora.example.com`;
+   - API Key from the WeKnora tenant settings page.
+4. Open the **Knowledge** tab, refresh knowledge bases, and select the target knowledge base.
+5. Import a URL or switch to **Chat** to ask questions.
+
+## Local development notes
+
+- WeChat DevTools may block `localhost` requests when URL validation is enabled. For local testing, either disable domain validation in DevTools or expose WeKnora through a HTTPS development domain.
+- In production Mini Programs, add the WeKnora API domain to the Mini Program request domain allowlist.
+- The chat endpoint returns Server-Sent Events. The Mini Program client parses completed SSE text responses and displays accumulated `answer` chunks.
+
+## Test
+
+```bash
+cd miniprogram
+npm test
+```
--- a/miniprogram/app.js
+++ b/miniprogram/app.js
@@ -0,0 +1,12 @@
+App({
+  onLaunch() {
+    const settings = wx.getStorageSync("weknora_settings");
+    if (!settings) {
+      wx.setStorageSync("weknora_settings", {
+        baseUrl: "http://localhost:8080",
+        apiKey: "",
+        selectedKnowledgeBaseId: ""
+      });
+    }
+  }
+});
--- a/miniprogram/app.json
+++ b/miniprogram/app.json
@@ -0,0 +1,33 @@
+{
+  "pages": [
+    "pages/index/index",
+    "pages/chat/chat",
+    "pages/settings/settings"
+  ],
+  "window": {
+    "navigationBarTitleText": "WeKnora",
+    "navigationBarBackgroundColor": "#102a43",
+    "navigationBarTextStyle": "white",
+    "backgroundColor": "#f4f7fb"
+  },
+  "tabBar": {
+    "color": "#667085",
+    "selectedColor": "#1264a3",
+    "backgroundColor": "#ffffff",
+    "borderStyle": "white",
+    "list": [
+      {
+        "pagePath": "pages/index/index",
+        "text": "Knowledge"
+      },
+      {
+        "pagePath": "pages/chat/chat",
+        "text": "Chat"
+      },
+      {
+        "pagePath": "pages/settings/settings",
+        "text": "Settings"
+      }
+    ]
+  }
+}
--- a/miniprogram/app.wxss
+++ b/miniprogram/app.wxss
@@ -0,0 +1,71 @@
+page {
+  min-height: 100%;
+  background: #f4f7fb;
+  color: #102a43;
+  font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", sans-serif;
+}
+
+.page {
+  min-height: 100vh;
+  box-sizing: border-box;
+  padding: 32rpx;
+}
+
+.card {
+  padding: 28rpx;
+  border-radius: 24rpx;
+  background: #ffffff;
+  box-shadow: 0 12rpx 36rpx rgba(16, 42, 67, 0.08);
+}
+
+.title {
+  font-size: 40rpx;
+  font-weight: 700;
+  margin-bottom: 12rpx;
+}
+
+.muted {
+  color: #667085;
+  font-size: 26rpx;
+}
+
+.field {
+  margin-top: 24rpx;
+}
+
+.label {
+  display: block;
+  margin-bottom: 12rpx;
+  color: #344054;
+  font-size: 26rpx;
+  font-weight: 600;
+}
+
+input,
+textarea,
+picker {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 88rpx;
+  padding: 20rpx 24rpx;
+  border: 1rpx solid #d0d5dd;
+  border-radius: 18rpx;
+  background: #ffffff;
+  font-size: 28rpx;
+}
+
+textarea {
+  min-height: 180rpx;
+}
+
+button {
+  margin-top: 24rpx;
+  border-radius: 18rpx;
+  background: #1264a3;
+  color: #ffffff;
+  font-weight: 700;
+}
+
+button[disabled] {
+  background: #98a2b3;
+}
--- a/miniprogram/package.json
+++ b/miniprogram/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "weknora-miniprogram",
+  "version": "0.1.0",
+  "private": true,
+  "description": "WeChat Mini Program plugin for WeKnora",
+  "scripts": {
+    "test": "node --test ../tests/miniprogram/*.test.js"
+  }
+}
--- a/miniprogram/pages/chat/chat.js
+++ b/miniprogram/pages/chat/chat.js
@@ -0,0 +1,54 @@
+const { getSettings } = require("../../utils/config");
+const { createSession, knowledgeChat } = require("../../utils/request");
+const { collectAnswerFromSSE } = require("../../utils/sse");
+
+Page({
+  data: {
+    answer: "",
+    loading: false,
+    query: "",
+    rawResponse: "",
+    sessionId: ""
+  },
+
+  onQueryInput(event) {
+    this.setData({ query: event.detail.value });
+  },
+
+  async ensureSession() {
+    if (this.data.sessionId) {
+      return this.data.sessionId;
+    }
+
+    const settings = getSettings();
+    const response = await createSession(settings.selectedKnowledgeBaseId);
+    const sessionId = response.data?.id;
+    if (!sessionId) {
+      throw new Error("The session API did not return a session id.");
+    }
+    this.setData({ sessionId });
+    return sessionId;
+  },
+
+  async ask() {
+    this.setData({ answer: "", rawResponse: "", loading: true });
+    try {
+      const sessionId = await this.ensureSession();
+      const response = await knowledgeChat(sessionId, this.data.query.trim());
+      const rawResponse = typeof response === "string" ? response : JSON.stringify(response);
+      const answer = collectAnswerFromSSE(rawResponse);
+      this.setData({
+        answer,
+        rawResponse: answer ? "" : rawResponse
+      });
+    } catch (error) {
+      wx.showModal({
+        title: "Chat failed",
+        content: error.message,
+        showCancel: false
+      });
+    } finally {
+      this.setData({ loading: false });
+    }
+  }
+});
--- a/miniprogram/pages/chat/chat.json
+++ b/miniprogram/pages/chat/chat.json
@@ -0,0 +1,3 @@
+{
+  "navigationBarTitleText": "Chat"
+}
--- a/miniprogram/pages/chat/chat.wxml
+++ b/miniprogram/pages/chat/chat.wxml
@@ -0,0 +1,18 @@
+<view class="page">
+  <view class="card">
+    <view class="title">Knowledge Chat</view>
+    <view class="muted">Ask the selected WeKnora knowledge base.</view>
+
+    <view class="field">
+      <text class="label">Question</text>
+      <textarea value="{{query}}" placeholder="Ask something..." bindinput="onQueryInput" />
+    </view>
+
+    <button bindtap="ask" loading="{{loading}}" disabled="{{!query}}">Ask WeKnora</button>
+  </view>
+
+  <view class="card answer-card" wx:if="{{answer || rawResponse}}">
+    <view class="label">Answer</view>
+    <view class="answer">{{answer || rawResponse}}</view>
+  </view>
+</view>
--- a/miniprogram/pages/chat/chat.wxss
+++ b/miniprogram/pages/chat/chat.wxss
@@ -0,0 +1,10 @@
+.answer-card {
+  margin-top: 28rpx;
+}
+
+.answer {
+  white-space: pre-wrap;
+  line-height: 1.7;
+  color: #102a43;
+  font-size: 28rpx;
+}
--- a/miniprogram/pages/index/index.js
+++ b/miniprogram/pages/index/index.js
@@ -0,0 +1,87 @@
+const { saveSettings, getSettings } = require("../../utils/config");
+const { createKnowledgeFromURL, listKnowledgeBases } = require("../../utils/request");
+
+Page({
+  data: {
+    importing: false,
+    knowledgeBases: [],
+    loading: false,
+    selectedIndex: 0,
+    selectedKnowledgeBaseId: "",
+    selectedKnowledgeBaseName: "",
+    url: ""
+  },
+
+  onShow() {
+    const settings = getSettings();
+    if (settings.selectedKnowledgeBaseId) {
+      this.setData({ selectedKnowledgeBaseId: settings.selectedKnowledgeBaseId });
+    }
+    this.loadKnowledgeBases();
+  },
+
+  onUrlInput(event) {
+    this.setData({ url: event.detail.value });
+  },
+
+  onKnowledgeBaseChange(event) {
+    const selectedIndex = Number(event.detail.value);
+    const selected = this.data.knowledgeBases[selectedIndex];
+    if (!selected) return;
+
+    saveSettings({ selectedKnowledgeBaseId: selected.id });
+    this.setData({
+      selectedIndex,
+      selectedKnowledgeBaseId: selected.id,
+      selectedKnowledgeBaseName: selected.name
+    });
+  },
+
+  async loadKnowledgeBases() {
+    this.setData({ loading: true });
+    try {
+      const response = await listKnowledgeBases();
+      const knowledgeBases = response.data || [];
+      const settings = getSettings();
+      const selectedIndex = Math.max(
+        0,
+        knowledgeBases.findIndex((item) => item.id === settings.selectedKnowledgeBaseId)
+      );
+      const selected = knowledgeBases[selectedIndex];
+      this.setData({
+        knowledgeBases,
+        selectedIndex,
+        selectedKnowledgeBaseId: selected?.id || "",
+        selectedKnowledgeBaseName: selected?.name || ""
+      });
+      if (selected?.id) {
+        saveSettings({ selectedKnowledgeBaseId: selected.id });
+      }
+    } catch (error) {
+      wx.showModal({
+        title: "Load failed",
+        content: error.message,
+        showCancel: false
+      });
+    } finally {
+      this.setData({ loading: false });
+    }
+  },
+
+  async importURL() {
+    this.setData({ importing: true });
+    try {
+      await createKnowledgeFromURL(this.data.selectedKnowledgeBaseId, this.data.url.trim(), false);
+      this.setData({ url: "" });
+      wx.showToast({ title: "Imported", icon: "success" });
+    } catch (error) {
+      wx.showModal({
+        title: "Import failed",
+        content: error.message,
+        showCancel: false
+      });
+    } finally {
+      this.setData({ importing: false });
+    }
+  }
+});
--- a/miniprogram/pages/index/index.json
+++ b/miniprogram/pages/index/index.json
@@ -0,0 +1,3 @@
+{
+  "navigationBarTitleText": "Knowledge"
+}
--- a/miniprogram/pages/index/index.wxml
+++ b/miniprogram/pages/index/index.wxml
@@ -0,0 +1,26 @@
+<view class="page">
+  <view class="card hero">
+    <view class="title">WeKnora Knowledge</view>
+    <view class="muted">Import a web page into a selected knowledge base from WeChat.</view>
+  </view>
+
+  <view class="card section">
+    <view class="field">
+      <text class="label">Knowledge Base</text>
+      <picker range="{{knowledgeBases}}" range-key="name" value="{{selectedIndex}}" bindchange="onKnowledgeBaseChange">
+        <view class="picker-value">{{selectedKnowledgeBaseName || "Tap to select"}}</view>
+      </picker>
+    </view>
+
+    <button bindtap="loadKnowledgeBases" loading="{{loading}}">Refresh knowledge bases</button>
+  </view>
+
+  <view class="card section">
+    <view class="field">
+      <text class="label">URL</text>
+      <input value="{{url}}" placeholder="https://github.com/Tencent/WeKnora" bindinput="onUrlInput" />
+    </view>
+
+    <button bindtap="importURL" loading="{{importing}}" disabled="{{!selectedKnowledgeBaseId || !url}}">Import URL</button>
+  </view>
+</view>
--- a/miniprogram/pages/index/index.wxss
+++ b/miniprogram/pages/index/index.wxss
@@ -0,0 +1,16 @@
+.hero {
+  background: linear-gradient(135deg, #102a43 0%, #1264a3 100%);
+  color: #ffffff;
+}
+
+.hero .muted {
+  color: rgba(255, 255, 255, 0.78);
+}
+
+.section {
+  margin-top: 28rpx;
+}
+
+.picker-value {
+  color: #102a43;
+}
--- a/miniprogram/pages/settings/settings.js
+++ b/miniprogram/pages/settings/settings.js
@@ -0,0 +1,32 @@
+const { getSettings, saveSettings } = require("../../utils/config");
+
+Page({
+  data: {
+    baseUrl: "",
+    apiKey: ""
+  },
+
+  onShow() {
+    const settings = getSettings();
+    this.setData({
+      baseUrl: settings.baseUrl,
+      apiKey: settings.apiKey
+    });
+  },
+
+  onBaseUrlInput(event) {
+    this.setData({ baseUrl: event.detail.value });
+  },
+
+  onApiKeyInput(event) {
+    this.setData({ apiKey: event.detail.value });
+  },
+
+  save() {
+    saveSettings({
+      baseUrl: this.data.baseUrl,
+      apiKey: this.data.apiKey
+    });
+    wx.showToast({ title: "Saved", icon: "success" });
+  }
+});
--- a/miniprogram/pages/settings/settings.json
+++ b/miniprogram/pages/settings/settings.json
@@ -0,0 +1,3 @@
+{
+  "navigationBarTitleText": "Settings"
+}
--- a/miniprogram/pages/settings/settings.wxml
+++ b/miniprogram/pages/settings/settings.wxml
@@ -0,0 +1,18 @@
+<view class="page">
+  <view class="card">
+    <view class="title">Connect WeKnora</view>
+    <view class="muted">Use your WeKnora API endpoint and tenant API key.</view>
+
+    <view class="field">
+      <text class="label">API Base URL</text>
+      <input value="{{baseUrl}}" placeholder="https://your-weknora.example.com" bindinput="onBaseUrlInput" />
+    </view>
+
+    <view class="field">
+      <text class="label">API Key</text>
+      <input value="{{apiKey}}" password placeholder="sk-..." bindinput="onApiKeyInput" />
+    </view>
+
+    <button bindtap="save">Save settings</button>
+  </view>
+</view>
--- a/miniprogram/pages/settings/settings.wxss
+++ b/miniprogram/pages/settings/settings.wxss
@@ -0,0 +1,3 @@
+.card {
+  margin-top: 40rpx;
+}
--- a/miniprogram/project.config.json
+++ b/miniprogram/project.config.json
@@ -0,0 +1,14 @@
+{
+  "description": "WeKnora Mini Program plugin",
+  "setting": {
+    "urlCheck": true,
+    "es6": true,
+    "enhance": true,
+    "postcss": true,
+    "minified": true
+  },
+  "compileType": "miniprogram",
+  "libVersion": "latest",
+  "projectname": "WeKnora Mini Program",
+  "condition": {}
+}
--- a/miniprogram/project.private.config.json.example
+++ b/miniprogram/project.private.config.json.example
@@ -0,0 +1,3 @@
+{
+  "appid": "your-wechat-mini-program-appid"
+}
--- a/miniprogram/sitemap.json
+++ b/miniprogram/sitemap.json
@@ -0,0 +1,8 @@
+{
+  "rules": [
+    {
+      "action": "allow",
+      "page": "*"
+    }
+  ]
+}
--- a/miniprogram/utils/config.js
+++ b/miniprogram/utils/config.js
@@ -0,0 +1,36 @@
+const STORAGE_KEY = "weknora_settings";
+
+function normalizeBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== "string") {
+    return "";
+  }
+
+  return baseUrl.trim().replace(/\/+$/, "");
+}
+
+function getSettings() {
+  const stored = wx.getStorageSync(STORAGE_KEY) || {};
+  return {
+    baseUrl: normalizeBaseUrl(stored.baseUrl || ""),
+    apiKey: stored.apiKey || "",
+    selectedKnowledgeBaseId: stored.selectedKnowledgeBaseId || ""
+  };
+}
+
+function saveSettings(settings) {
+  const current = getSettings();
+  const next = {
+    ...current,
+    ...settings,
+    baseUrl: normalizeBaseUrl(settings.baseUrl ?? current.baseUrl)
+  };
+  wx.setStorageSync(STORAGE_KEY, next);
+  return next;
+}
+
+module.exports = {
+  STORAGE_KEY,
+  getSettings,
+  normalizeBaseUrl,
+  saveSettings
+};
--- a/miniprogram/utils/request.js
+++ b/miniprogram/utils/request.js
@@ -0,0 +1,71 @@
+const { getSettings } = require("./config");
+
+function request(path, options = {}) {
+  const settings = getSettings();
+  if (!settings.baseUrl) {
+    return Promise.reject(new Error("Please configure the WeKnora API base URL first."));
+  }
+  if (!settings.apiKey) {
+    return Promise.reject(new Error("Please configure the WeKnora API key first."));
+  }
+
+  return new Promise((resolve, reject) => {
+    wx.request({
+      url: `${settings.baseUrl}${path}`,
+      method: options.method || "GET",
+      data: options.data,
+      header: {
+        "Content-Type": "application/json",
+        "X-API-Key": settings.apiKey,
+        "X-Request-ID": `mp-${Date.now()}-${Math.random().toString(16).slice(2)}`
+      },
+      success(response) {
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          resolve(response.data);
+          return;
+        }
+        const message = response.data?.error?.message || response.data?.message || `HTTP ${response.statusCode}`;
+        reject(new Error(message));
+      },
+      fail(error) {
+        reject(new Error(error.errMsg || "Network request failed."));
+      }
+    });
+  });
+}
+
+function listKnowledgeBases() {
+  return request("/api/v1/knowledge-bases");
+}
+
+function createKnowledgeFromURL(knowledgeBaseId, url, enableMultimodel = false) {
+  return request(`/api/v1/knowledge-bases/${knowledgeBaseId}/knowledge/url`, {
+    method: "POST",
+    data: {
+      url,
+      enable_multimodel: enableMultimodel
+    }
+  });
+}
+
+function createSession(knowledgeBaseId) {
+  return request("/api/v1/sessions", {
+    method: "POST",
+    data: knowledgeBaseId ? { knowledge_base_id: knowledgeBaseId } : {}
+  });
+}
+
+function knowledgeChat(sessionId, query) {
+  return request(`/api/v1/knowledge-chat/${sessionId}`, {
+    method: "POST",
+    data: { query }
+  });
+}
+
+module.exports = {
+  createKnowledgeFromURL,
+  createSession,
+  knowledgeChat,
+  listKnowledgeBases,
+  request
+};
--- a/miniprogram/utils/sse.js
+++ b/miniprogram/utils/sse.js
@@ -0,0 +1,42 @@
+function parseSSE(raw) {
+  if (!raw || typeof raw !== "string") {
+    return [];
+  }
+
+  return raw
+    .split(/\n\n+/)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .map((block) => {
+      const event = { event: "message", data: "" };
+      block.split(/\n/).forEach((line) => {
+        if (line.startsWith("event:")) {
+          event.event = line.slice(6).trim();
+        }
+        if (line.startsWith("data:")) {
+          event.data += line.slice(5).trim();
+        }
+      });
+      return event;
+    })
+    .filter((event) => event.data);
+}
+
+function collectAnswerFromSSE(raw) {
+  return parseSSE(raw).reduce((answer, event) => {
+    try {
+      const payload = JSON.parse(event.data);
+      if (payload.response_type === "answer" && payload.content) {
+        return answer + payload.content;
+      }
+    } catch (error) {
+      return answer;
+    }
+    return answer;
+  }, "");
+}
+
+module.exports = {
+  collectAnswerFromSSE,
+  parseSSE
+};
--- a/tests/miniprogram/miniprogram.test.js
+++ b/tests/miniprogram/miniprogram.test.js
@@ -0,0 +1,86 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { createKnowledgeFromURL, listKnowledgeBases } = require("../../miniprogram/utils/request");
+const { collectAnswerFromSSE, parseSSE } = require("../../miniprogram/utils/sse");
+const { normalizeBaseUrl } = require("../../miniprogram/utils/config");
+
+test("parseSSE extracts event payloads", () => {
+  const events = parseSSE('event: message\ndata: {"content":"hi"}\n\n');
+
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event, "message");
+  assert.equal(events[0].data, '{"content":"hi"}');
+});
+
+test("collectAnswerFromSSE joins answer chunks and skips references", () => {
+  const raw = [
+    'event: message\ndata: {"response_type":"references","content":"skip","done":false}',
+    'event: message\ndata: {"response_type":"answer","content":"Hel","done":false}',
+    'event: message\ndata: {"response_type":"answer","content":"lo","done":true}'
+  ].join("\n\n");
+
+  assert.equal(collectAnswerFromSSE(raw), "Hello");
+});
+
+test("normalizeBaseUrl trims trailing slashes", () => {
+  assert.equal(normalizeBaseUrl(" https://example.com/// "), "https://example.com");
+});
+
+test("API helpers send WeKnora auth headers", async () => {
+  let capturedRequest;
+  global.wx = {
+    getStorageSync() {
+      return {
+        apiKey: "sk-test",
+        baseUrl: "https://weknora.example.com/",
+        selectedKnowledgeBaseId: "kb-1"
+      };
+    },
+    request(options) {
+      capturedRequest = options;
+      options.success({
+        statusCode: 200,
+        data: {
+          data: []
+        }
+      });
+    }
+  };
+
+  await listKnowledgeBases();
+
+  assert.equal(capturedRequest.url, "https://weknora.example.com/api/v1/knowledge-bases");
+  assert.equal(capturedRequest.header["X-API-Key"], "sk-test");
+  assert.match(capturedRequest.header["X-Request-ID"], /^mp-/);
+});
+
+test("URL import helper posts the selected URL payload", async () => {
+  let capturedRequest;
+  global.wx = {
+    getStorageSync() {
+      return {
+        apiKey: "sk-test",
+        baseUrl: "https://weknora.example.com",
+        selectedKnowledgeBaseId: "kb-1"
+      };
+    },
+    request(options) {
+      capturedRequest = options;
+      options.success({
+        statusCode: 201,
+        data: {
+          success: true
+        }
+      });
+    }
+  };
+
+  await createKnowledgeFromURL("kb-1", "https://github.com/Tencent/WeKnora", true);
+
+  assert.equal(capturedRequest.method, "POST");
+  assert.equal(capturedRequest.url, "https://weknora.example.com/api/v1/knowledge-bases/kb-1/knowledge/url");
+  assert.deepEqual(capturedRequest.data, {
+    url: "https://github.com/Tencent/WeKnora",
+    enable_multimodel: true
+  });
+});