diff --git a/skills/mj-api-skill/SKILL.md b/skills/mj-api-skill/SKILL.md new file mode 100644 index 0000000..1bc62c7 --- /dev/null +++ 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 `` (place it early to ensure loading before dependent code): + +```html + +``` + +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` | 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 +``` + +- 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 + + + + + + + +``` + +## 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