添加 skills/mj-api-skill/SKILL.md

2026-03-19 22:34:33 +08:00
parent 36e497df51
commit 70851c6fa0
1 changed files with 239 additions and 0 deletions
--- a/skills/mj-api-skill/SKILL.md
+++ b/skills/mj-api-skill/SKILL.md
@@ -0,0 +1,239 @@
+---
+name: mj-api-skill
+description: Help AI integrate with Mujian OpenAPI - an OpenAI-compatible API for accessing LLM capabilities within the Mujian platform.
+---
+
+# Mujian OpenAPI Integration Skill
+
+Help developers integrate with the Mujian (幕间) OpenAPI, which follows OpenAI API specifications to provide LLM access within the Mujian platform.
+
+## When to use
+
+Use this skill when the user:
+
+- Wants to integrate Mujian OpenAPI into their project
+- Asks about calling Mujian's LLM API (chat completions, model list)
+- Needs help with Mujian JS-SDK initialization
+- Wants to implement streaming or non-streaming chat with Mujian
+- Mentions "幕间" or "mujian" in the context of API integration
+
+## Platform Overview
+
+Mujian OpenAPI uses OpenAI-standard protocols to access online LLM capabilities. It is restricted to:
+- Creator local debugging
+- Works shared within the Mujian platform (third-party platform uploads cannot access it)
+
+## SDK Setup
+
+### Browser (UMD)
+
+Add the SDK script in `<head>` (place it early to ensure loading before dependent code):
+
+```html
+<script
+  src="https://cdn.jsdmirror.com/npm/@mujian/js-sdk@latest/dist/umd/lite.js"
+  type="text/javascript"
+></script>
+```
+
+Initialize and retrieve API config:
+
+```javascript
+window.$mujian_lite.init().then(() => {
+  console.log('API Base URL:', window.$mujian_lite.openapi.baseURL);
+  console.log('API Key:', window.$mujian_lite.openapi.apiKey);
+}).catch((err) => {
+  console.error('SDK initialization failed:', err);
+});
+```
+
+### NPM Package (React, Vue, etc.)
+
+```bash
+npm install @mujian/js-sdk
+```
+
+```javascript
+import '@mujian/js-sdk/lite';
+
+window.$mujian_lite.init().then(() => {
+  console.log('API Base URL:', window.$mujian_lite.openapi.baseURL);
+  console.log('API Key:', window.$mujian_lite.openapi.apiKey);
+}).catch((err) => {
+  console.error('SDK initialization failed:', err);
+});
+```
+
+### SDK API Reference
+
+| Name | Type | Description |
+|------|------|-------------|
+| `init()` | `Promise<void>` | Initialize SDK and retrieve config. Must be called first. Idempotent (safe to call multiple times). |
+| `openapi` | `{ baseURL: string; apiKey: string } \| undefined` | Available after `init()` resolves. Contains API endpoint and user-specific key. `undefined` before init completes. |
+
+`window.$mujian_lite` is a global singleton, no manual instantiation needed.
+
+## Authentication
+
+All requests require an Authorization header:
+
+```
+Authorization: Bearer <apiKey>
+```
+
+- In production (within Mujian platform): get `apiKey` from `window.$mujian_lite.openapi.apiKey` after SDK init
+- In local development: manually copy API Key from Mujian "My" section
+
+## Base URL
+
+| Environment | URL |
+|-------------|-----|
+| Production | `https://openapi.mujian.ai/v1` |
+| Preview | `https://openapi-preview.mujian.ai/v1` |
+
+In production, use `window.$mujian_lite.openapi.baseURL` instead of hardcoding.
+
+## API Endpoints
+
+### GET /models
+
+Returns available model IDs (OpenAI API compatible).
+
+**Supported models:** `deepseek-v3.2`
+
+```javascript
+const { baseURL, apiKey } = window.$mujian_lite.openapi;
+
+fetch(`${baseURL}/models`, {
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+  },
+})
+  .then((res) => res.json())
+  .then((data) => console.log(data));
+```
+
+### POST /chat/completions
+
+OpenAI-compatible chat completion endpoint. Supports both streaming and non-streaming.
+
+#### Non-streaming
+
+```javascript
+const { baseURL, apiKey } = window.$mujian_lite.openapi;
+
+fetch(`${baseURL}/chat/completions`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  },
+  body: JSON.stringify({
+    model: 'deepseek-v3.2',
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Hello' },
+    ],
+  }),
+})
+  .then((res) => res.json())
+  .then((data) => console.log(data));
+```
+
+#### Streaming
+
+```javascript
+const { baseURL, apiKey } = window.$mujian_lite.openapi;
+
+fetch(`${baseURL}/chat/completions`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  },
+  body: JSON.stringify({
+    model: 'deepseek-v3.2',
+    stream: true,
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Hello' },
+    ],
+  }),
+})
+  .then((res) => {
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    function read() {
+      reader.read().then(({ done, value }) => {
+        if (done) return;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+
+        for (const line of lines) {
+          if (line.startsWith('data: ')) {
+            const data = line.slice(6);
+            if (data === '[DONE]') return;
+            try {
+              const json = JSON.parse(data);
+              const content = json.choices?.[0]?.delta?.content;
+              if (content) process.stdout.write(content);
+            } catch (e) {}
+          }
+        }
+        read();
+      });
+    }
+    read();
+  });
+```
+
+## Local Development
+
+For local debugging (outside the Mujian platform):
+
+1. Go to Mujian → "My" section → click "Copy" to get your API Key
+2. Use `https://openapi.mujian.ai/v1` as BaseURL (or preview URL for preview env)
+3. Hardcode the API Key and BaseURL in your code
+4. After local development is complete, switch to SDK-based method (`window.$mujian_lite.openapi`) for production
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <script>
+      fetch('https://openapi.mujian.ai/v1/models', {
+        headers: {
+          Authorization: 'Bearer YOUR_API_KEY_HERE',
+        },
+      })
+        .then((res) => res.json())
+        .then((data) => console.log(data));
+    </script>
+  </head>
+  <body></body>
+</html>
+```
+
+## Official Documentation
+
+If the information in this skill is outdated or you encounter issues, refer to the latest official docs:
+
+- Introduction & SDK Setup: https://docs.mujian.ai/creator/openapi/introduction.md
+- API Endpoints: https://docs.mujian.ai/creator/openapi/endpoints.md
+- Local Development: https://docs.mujian.ai/creator/openapi/local-dev.md
+
+## Instructions for AI
+
+When helping users integrate Mujian OpenAPI:
+
+1. Determine the environment: local debugging or production (within Mujian platform)
+2. For local dev: guide them to manually get API Key and use hardcoded BaseURL
+3. For production: use the JS-SDK to initialize and get `baseURL` and `apiKey` from `window.$mujian_lite.openapi`
+4. Choose UMD (script tag) or NPM based on their project setup
+5. Implement the needed endpoint (models list or chat completions)
+6. For chat: ask if they need streaming or non-streaming, then provide the appropriate example
+7. Remind users that `openapi` is `undefined` before `init()` completes — always await initialization
+8. Remind users that Mujian OpenAPI only works for creator local debugging or works shared within the Mujian platform