@minaim/openclaw-channel 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# Mina OpenClaw Channel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mina IM 的 OpenClaw 原生渠道插件，连接你自行部署和运行的 AI Agent。Mina 不提供默认模型或模型密钥。
+
+当前为公开预览版，支持助手所有者的文本、图片和文件私聊。群 Agent 调用尚未开放；真实云服务器、Mina 服务和手机的端到端验收尚未完成。
+
+## 安装
+
+发布到 npm 后，使用以下不带版本号的命令安装官方 registry 的最新发布版：
+
+```bash
+openclaw plugins install npm:@minaim/openclaw-channel
+openclaw channels add mina
+```
+
+安装时按 OpenClaw 提示审阅来源及能力。用户安装公开包不需要 npm 账号。一个 account 对应一个 Mina AI 助手，可配置多个 account。
+
+## 配置
+
+在 Mina App“我的 → AI 助手”创建助手，向导中输入 HTTPS 网关、AppID、助手 ID、所有者 ID、凭证版本和一次性 AppSecret。密钥通过隐藏输入保存至私有文件，不写入 OpenClaw 普通配置。宿主只保存配置路径；已有不同绑定不覆盖。
+
+启动或重启 Gateway 后在 App 检查连接。配置探测是本地被动检查，不表示已联网。Mina 长轮询只需出站 HTTPS。同一助手同时只允许一个有效消费者，插件不会自动抢占另一个实例。
+
+## 更新
+
+更新前停止当前 Gateway，再执行：
+
+```bash
+openclaw plugins update mina
+```
+
+完成后重新启动 Gateway。用户不需要填写版本号；npm 更新跟随 `latest` 发布标签，Gitee 的代码改动需重新发布 npm 才会进入该更新渠道。保留原来的私有配置、SQLite 和待提交文件，不通过删除状态库重试任务。活动执行的热升级与自动回滚尚未提供。
+
+## 环境
+
+- 已验证 OpenClaw 2026.10.5；Node >=24.16.0 <25 或 >=26.1.0。
+- Python >=3.9，使用标准库持久工作进程。npm 包已包含 Python 源码，但服务器仍需提供 Python 运行时。
+- Linux/macOS 本地磁盘；实际宿主测试在 Linux 完成。
+- 私有目录 0700、配置文件 0600；容器中保留整个宿主 state 持久卷。
+
+宿主版本与运行时检查不因更新到最新插件而取消。不要把本插件当作模型或 Agent 托管服务。
+
+## 图片和文档
+
+支持 PNG/JPEG/GIF，单张最大 8 MiB；文件最大 20 MiB；最终回复最多 5 个附件。TXT、PDF、Office 文档传实际字节，解析、OCR 和编辑取决于用户宿主的模型与工具。输出文件目录和远程域名需由部署者显式授权，不从聊天正文推导上传权限。不支持流式、语音、视频和主动发信。
+
+## 可靠性与许可
+
+消息先可靠接收，再申请执行许可；未知执行不自动重跑，已保存结果失败只补交。诊断输出固定错误码，不含密钥、对话正文或完整附件能力链接。
+
+维护与版本记录：[Mina Agent 插件仓库](https://gitee.com/Mina-IM/mina-agent-plugins)。当前仓库为私有测试仓库，查看源码与问题页需要授权；npm 包本身公开可下载。此包标记为 UNLICENSED，公开分发不授予开源许可证。

package/bridge.mjs

@@ -0,0 +1,92 @@
+import {spawn} from 'node:child_process';
+import {isAbsolute} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {localError,safeStatus} from './diagnostics.mjs';
+
+const limit=131072;
+const fail=()=>localError('worker_stopped');
+export class NativeWorker {
+  constructor({configFile,python='python3',signal,onReady,onStatus,execute}) {
+    if(!isAbsolute(configFile)||typeof python!=='string'||!python||python.includes('\0')) throw fail();
+    this.configFile=configFile; this.python=python; this.signal=signal;
+    this.onReady=onReady; this.onStatus=onStatus; this.execute=execute; this.child=null; this.stopping=false; this.controller=new AbortController();
+  }
+  stop() {
+    this.stopping=true;
+    this.controller.abort();
+    if(this.child && this.child.exitCode===null && this.child.signalCode===null) {
+      this.child.kill('SIGTERM');
+      const child=this.child;
+      this.killTimer=setTimeout(()=>{if(child.exitCode===null&&child.signalCode===null) child.kill('SIGKILL');},3000);
+      this.killTimer.unref();
+    }
+  }
+  async run() {
+    if(this.signal?.aborted) return;
+    const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>
+      ['PATH','HOME','SSL_CERT_FILE','SSL_CERT_DIR','HTTPS_PROXY','HTTP_PROXY','NO_PROXY'].includes(key)));
+    this.child=spawn(this.python,[fileURLToPath(new URL('./vendor/mina_native.py',import.meta.url)),
+      '--host','OpenClaw','--config',this.configFile],{stdio:['pipe','pipe','ignore'],env,shell:false});
+    const closed=new Promise(resolve=>{
+      this.child.once('error',error=>{this.failure=localError(error.code==='ENOENT'?'python_unavailable':'worker_stopped');this.controller.abort();resolve(false);});
+      this.child.once('close',code=>{this.controller.abort();resolve(code===0);});
+    });
+    // Avoid unhandled EPIPE if the lease worker exits while the host finishes a turn.
+    this.child.stdin.on('error',()=>this.stop());
+    this.signal?.addEventListener('abort',this.abort=()=>this.stop(),{once:true});
+    const readyTimer=setTimeout(()=>this.stop(),35000);
+    let ready=false, buffer=Buffer.alloc(0);
+    try {
+      for await (const chunk of this.child.stdout) {
+        buffer=Buffer.concat([buffer,chunk]);
+        let end;
+        while((end=buffer.indexOf(10))>=0) {
+          if(end+1>limit||this.stopping) throw fail();
+          const raw=buffer.subarray(0,end); buffer=buffer.subarray(end+1);
+          const frame=JSON.parse(raw.toString('utf8'));
+          if(frame?.type==='error'&&Object.keys(frame).sort().join(',')==='code,type')throw localError(frame.code);
+          if(ready&&frame?.type==='status'&&Object.keys(frame).sort().join(',')==='code,type'){await this.onStatus?.(safeStatus(frame.code));continue;}
+          if(!ready) {
+            if(frame.type!=='ready'||frame.protocol!==1||!/^bot_[a-f0-9]{32}$/.test(frame.bot_id)
+              ||!/^mina_[a-f0-9]{32}$/.test(frame.app_id)||!/^[A-Za-z0-9_-]{1,128}$/.test(frame.owner_id)
+              ||!Number.isSafeInteger(frame.credential_version)||frame.credential_version<1) throw fail();
+            ready=true; this.identity=Object.freeze(frame); clearTimeout(readyTimer);
+            await this.onReady?.(this.identity);
+          } else {
+            if(frame.type!=='execute'||Object.keys(frame).sort().join(',')!=='event,type') throw fail();
+            const signal=this.controller.signal;
+            let cancel;
+            const canceled=new Promise((_,reject)=>{
+              cancel=()=>reject(fail());
+              signal.addEventListener('abort',cancel,{once:true});
+              if(signal.aborted) cancel();
+            });
+            const deadline=setTimeout(()=>this.stop(),240000);
+            let content;
+            try {content=await Promise.race([Promise.resolve().then(()=>this.execute(frame.event,this.identity,signal)),canceled]);}
+            finally {clearTimeout(deadline);signal.removeEventListener('abort',cancel);}
+            if(this.stopping||this.signal?.aborted) throw fail();
+            const text=typeof content==='string'?content:content?.text;
+            const attachments=typeof content==='string'?[]:content?.attachments;
+            if(typeof text!=='string'||!Array.isArray(attachments)||attachments.length>5||(!text&&!attachments.length)||Buffer.byteLength(text)>32768) throw fail();
+            const response=JSON.stringify({type:'result',event_id:frame.event.event_id,content:text,...(attachments.length?{attachments}:{})})+'\n';
+            if(Buffer.byteLength(response)>limit)throw fail();
+            await new Promise((resolve,reject)=>this.child.stdin.write(response,error=>error?reject(fail()):resolve()));
+          }
+        }
+        if(buffer.length>limit) throw fail();
+      }
+      if(buffer.length||!ready) throw fail();
+      const ok=await closed;
+      if(!ok&&!this.signal?.aborted) throw fail();
+    } catch(error) {
+      throw this.failure??(error?.code?localError(error.code):fail());
+    } finally {
+      clearTimeout(readyTimer);
+      this.stop();
+      this.signal?.removeEventListener('abort',this.abort);
+      await closed;
+      clearTimeout(this.killTimer);
+    }
+  }
+}

package/diagnostics.mjs

@@ -0,0 +1,47 @@
+import {spawn} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {dirname,join,isAbsolute} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const codes=new Set(['configuration_valid','configuration_missing','configuration_invalid','host_version_unsupported',
+ 'python_unsupported','platform_unsupported','python_unavailable','state_locked','worker_stopped','protocol_error',
+ 'connected','invalid_agent_credentials','authorization_revoked','lease_held','stale_lease','network_unavailable',
+ 'transport_unavailable','media_unavailable','rate_limited','storage_unavailable']);
+export const safeStatus=code=>codes.has(code)?code:'worker_stopped';
+export function localError(code){const error=new Error(`Mina: ${safeStatus(code)}`);error.code=safeStatus(code);return error;}
+export function hostVersion(){
+ try{let path=dirname(fileURLToPath(import.meta.resolve('openclaw/plugin-sdk/channel-core')));
+  for(let n=0;n<8;n++,path=dirname(path)){try{const pkg=JSON.parse(readFileSync(join(path,'package.json'),'utf8'));if(pkg.name==='openclaw')return pkg.version;}catch{}}
+ }catch{}return '';
+}
+function supportedNode(){const [major,minor]=process.versions.node.split('.').map(Number);return (major===24&&minor>=16)||(major===26&&minor>=1)||major>26;}
+export function runLocalTool(args,{python='python3',input}={}){
+ return new Promise((resolve,reject)=>{
+  if(!['linux','darwin'].includes(process.platform))return reject(localError('platform_unsupported'));
+  if(!supportedNode()||hostVersion()!=='2026.10.5')return reject(localError('host_version_unsupported'));
+  if(typeof python!=='string'||!python||python.includes('\0'))return reject(localError('python_unavailable'));
+  const env=Object.fromEntries(Object.entries(process.env).filter(([key])=>['PATH','HOME','LANG'].includes(key)));
+  const child=spawn(python,[fileURLToPath(new URL('./vendor/mina_setup.py',import.meta.url)),...args],{stdio:['pipe','pipe','ignore'],env,shell:false});
+  let data=Buffer.alloc(0),oversized=false;
+  const timer=setTimeout(()=>{child.kill('SIGKILL');reject(localError('worker_stopped'));},10000);
+  child.on('error',error=>{clearTimeout(timer);reject(localError(error.code==='ENOENT'?'python_unavailable':'worker_stopped'));});
+  child.stdout.on('data',chunk=>{if(data.length+chunk.length>32768){oversized=true;child.kill('SIGKILL');return;}data=Buffer.concat([data,chunk]);});
+  child.stdin.on('error',()=>{});
+  child.on('close',()=>{clearTimeout(timer);try{if(oversized)throw new Error();const value=JSON.parse(data.toString('utf8'));if(!value||typeof value!=='object'||Array.isArray(value))throw new Error();resolve(value);}catch{reject(localError('worker_stopped'));}});
+  child.stdin.end(input?JSON.stringify(input):undefined);
+ });
+}
+export async function createConfiguration(directory,values,python){
+ const result=await runLocalTool(['configure','--directory',directory],{input:values,python});
+ if(result.config_file!==join(directory,'assistant.json')||result.state_file!==join(directory,`state-v${values.credential_version}.sqlite`))throw localError(result.code??'configuration_invalid');
+ return {configFile:result.config_file,python:python??'python3',enabled:true};
+}
+export async function probeConfiguration(account){
+ let code='configuration_missing',configured=false;
+ try{
+  if(typeof account?.configFile!=='string'||!isAbsolute(account.configFile))return {ok:false,code,configured,connected:null,network_checked:false};
+  const report=await runLocalTool(['doctor','--config',account.configFile,'--host','OpenClaw','--host-version',hostVersion()],{python:account.python??'python3'});
+  code=safeStatus(report.code);configured=report.configured===true;
+ }catch(error){code=safeStatus(error.code);}
+ return {ok:code==='configuration_valid',code,configured,connected:null,network_checked:false};
+}

package/index.mjs

@@ -0,0 +1,128 @@
+import {createHash} from 'node:crypto';
+import {createChatChannelPlugin,defineChannelPluginEntry} from 'openclaw/plugin-sdk/channel-core';
+import {buildChannelInboundEventContext,dispatchChannelInboundTurn} from 'openclaw/plugin-sdk/channel-inbound';
+import {resolveAgentRoute} from 'openclaw/plugin-sdk/routing';
+import {NativeWorker} from './bridge.mjs';
+import {minaSetupWizard,minaSetupAdapter} from './setup.mjs';
+import {probeConfiguration,safeStatus,localError} from './diagnostics.mjs';
+
+function validate(event,identity) {
+  for(const [key,value] of Object.entries({schema_version:'1',event_type:'message.created',bot_id:identity.bot_id,
+    sender_id:identity.owner_id,conversation_id:identity.owner_id,conversation_type:'private',
+    credential_version:identity.credential_version})) {
+    if(event?.[key]!==value) throw new Error('Mina private event scope mismatch');
+  }
+  for(const [key,pattern] of [['event_id',/^evt_[a-f0-9]{32}$/],['session_key',/^mina:private:[a-f0-9]{64}$/],
+    ['message_id',/^[A-Za-z0-9_-]{1,128}$/]]) {
+    if(typeof event[key]!=='string'||!pattern.test(event[key])) throw new Error('Invalid Mina event metadata');
+  }
+  for(const key of ['timestamp_ms','expires_at_ms','context_epoch'])
+    if(!Number.isSafeInteger(event[key])||event[key]<1) throw new Error('Invalid Mina event lifecycle');
+  const items=event.attachments??[];
+  if(!['text','image','file'].includes(event.message_type)||!Array.isArray(items)||(event.message_type==='text'?items.length!==0:items.length!==1)) throw new Error('Invalid Mina attachment event');
+  for(const a of items)if(a.kind!==event.message_type||typeof a.path!=='string'||!a.path.startsWith('/')||a.path.includes('\0')||!/^att_[a-f0-9]{32}$/.test(a.attachment_id)||!Number.isSafeInteger(a.size)||a.size<1||a.size>(a.kind==='image'?8388608:20971520)||!/^[a-f0-9]{64}$/.test(a.sha256)) throw new Error('Invalid verified Mina attachment');
+  if(event.expires_at_ms<=event.timestamp_ms||typeof event.content!=='string'||(!event.content&&!items.length)||Buffer.byteLength(event.content)>8192)
+    throw new Error('Unsupported Mina text event');
+}
+
+export function buildTurn({event,identity,cfg,accountId}) {
+  validate(event,identity);
+  const resolved=resolveAgentRoute({cfg,channel:'mina',accountId,peer:{kind:'direct',id:event.session_key}});
+  // Force a private server-issued context even when the host defaults dmScope to main.
+  // Context/cv also fence a native session if an upstream key is accidentally reused.
+  const key=createHash('sha256').update(JSON.stringify([identity.app_id,event.session_key,
+    event.context_epoch,event.credential_version])).digest('hex');
+  const route={agentId:resolved.agentId,sessionKey:`agent:${resolved.agentId}:mina:${key}`};
+  const ctxPayload=buildChannelInboundEventContext({
+    channel:'mina',accountId,provider:'mina',surface:'mina',messageId:event.message_id,
+    timestamp:event.timestamp_ms,from:`mina:${event.sender_id}`,
+    sender:{id:event.sender_id},conversation:{kind:'direct',id:event.session_key,routePeer:{kind:'direct',id:event.session_key}},
+    route:{agentId:route.agentId,accountId,routeSessionKey:route.sessionKey,dispatchSessionKey:route.sessionKey},
+    reply:{to:`mina:${event.sender_id}`,originatingTo:`mina:${event.sender_id}`},
+    message:{body:event.content,bodyForAgent:event.content,rawBody:event.content,commandBody:''},
+    media:(event.attachments??[]).map(a=>({path:a.path,contentType:a.mime_type,kind:a.kind==='image'?'image':'document',fileName:a.name,sizeBytes:a.size,width:a.width,height:a.height})),
+    access:{commands:{authorized:false}},channelIngress:'unsupported',
+  });
+  return {route,ctxPayload};
+}
+
+export function createFinalCollector() {
+  const texts=[],attachments=[]; let invalid=false;
+  return {
+    async deliver(payload,info) {
+      if(info.kind!=='final'||payload.isReasoning||payload.isCommentary) return;
+      if(payload.isError||payload.presentation||payload.interactive||payload.location) {
+        invalid=true; return;
+      }
+      if(typeof payload.text==='string'&&payload.text.trim()) texts.push(payload.text);
+      for(const source of payload.mediaUrls??(payload.mediaUrl?[payload.mediaUrl]:[])){
+        if(typeof source!=='string'||attachments.length>=5){invalid=true;continue;}
+        let path=source;
+        try{
+          if(source.startsWith('file://')){const url=new URL(source);if(url.hostname||url.search||url.hash)throw new Error();path=decodeURIComponent(url.pathname);}
+          if(!path.startsWith('/')&&!path.startsWith('https://'))throw new Error();
+          const name=path.startsWith('https://')?decodeURIComponent(new URL(path).pathname.split('/').pop())||'attachment.bin':path.split('/').pop();
+          const kind=/\.(png|jpe?g|gif)$/i.test(name)?'image':'file';
+          if(!attachments.some(a=>a.path===path))attachments.push({path,kind,name});
+        }catch{invalid=true;}
+      }
+    },
+    error(){invalid=true;},
+    result(){
+      const content=texts.join('\n\n');
+      if(invalid||(!content&&!attachments.length)||Buffer.byteLength(content)>32768) throw new Error('Mina requires a complete text reply');
+      return attachments.length?{text:content,attachments}:content;
+    },
+  };
+}
+
+export async function executeTurn({event,identity,cfg,accountId,signal}, replyResolver) {
+  if(signal?.aborted) throw new Error('Mina execution canceled');
+  const {route,ctxPayload}=buildTurn({event,identity,cfg,accountId});
+  const collector=createFinalCollector();
+  await dispatchChannelInboundTurn({cfg,channel:'mina',accountId,route,ctxPayload,
+    record:{onRecordError:()=>{throw new Error('Mina session recording failed');}},
+    replyOptions:{disableBlockStreaming:true,abortSignal:signal},
+    delivery:{durable:false,deliver:collector.deliver,onError:()=>collector.error()},
+    ...(replyResolver?{replyResolver}:{}),
+  });
+  if(signal?.aborted) throw new Error('Mina execution canceled');
+  return collector.result();
+}
+
+const section=cfg=>cfg.channels?.mina??{};
+const accounts=cfg=>section(cfg).accounts??{};
+const resolveAccount=(cfg,accountId='default')=>({...accounts(cfg)[accountId],accountId,
+  enabled:section(cfg).enabled!==false&&accounts(cfg)[accountId]?.enabled!==false});
+const blocked=async()=>{throw new Error('Mina only supports a bound final reply to an authorized inbound event');};
+export const minaChannel=createChatChannelPlugin({base:{
+  id:'mina',meta:{id:'mina',label:'Mina AI 助手',selectionLabel:'Mina',docsPath:'/channels/mina',
+    blurb:'Connect a self-hosted Agent to Mina private chats.'},
+  capabilities:{chatTypes:['direct'],nativeCommands:false,blockStreaming:false,media:true,reply:true},
+  setupWizard:minaSetupWizard,setup:minaSetupAdapter,
+  status:{
+    defaultRuntime:{accountId:'default',running:false,connected:false},
+    probeAccount:({account})=>probeConfiguration(account),
+    buildAccountSnapshot:({account,runtime={},probe})=>({accountId:account.accountId,enabled:account.enabled!==false,configured:!!account.configFile,running:runtime.running===true,connected:runtime.connected===true,mediaReady:runtime.mediaReady===true,lastError:runtime.lastError?safeStatus(runtime.lastError):null,probe}),
+    collectStatusIssues:accounts=>accounts.filter(a=>a.enabled!==false&&(!a.configured||a.lastError)).map(a=>({channel:'mina',accountId:a.accountId,kind:!a.configured?'config':'runtime',message:a.lastError?safeStatus(a.lastError):'configuration_missing'})),
+  },
+  config:{
+    listAccountIds:cfg=>Object.keys(accounts(cfg)),resolveAccount,
+    isEnabled:account=>account.enabled!==false,
+    isConfigured:account=>typeof account.configFile==='string'&&account.configFile.startsWith('/'),
+    inspectAccount:(cfg,id)=>({enabled:resolveAccount(cfg,id).enabled!==false,configured:!!resolveAccount(cfg,id).configFile}),
+  },
+  gateway:{apiVersion:1,async startAccount(ctx) {
+    try {
+    const report=await probeConfiguration(ctx.account);
+    if(!report.ok)throw localError(report.code);
+    const worker=new NativeWorker({configFile:ctx.account.configFile,python:ctx.account.python??'python3',
+      signal:ctx.abortSignal,onReady:identity=>ctx.setStatus({accountId:ctx.accountId,connected:true,running:true,mediaReady:identity.media_enabled===true,lastError:null,lastStartAt:Date.now()}),
+      onStatus:code=>ctx.setStatus({accountId:ctx.accountId,connected:code==='connected',running:true,lastError:code==='connected'?null:safeStatus(code)}),
+      execute:(event,identity,signal)=>executeTurn({event,identity,cfg:ctx.cfg,accountId:ctx.accountId,signal})});
+    await worker.run();}
+    catch(error){ctx.setStatus({accountId:ctx.accountId,lastError:safeStatus(error.code)});throw error;}
+    finally {ctx.setStatus({accountId:ctx.accountId,connected:false,running:false,mediaReady:false,lastStopAt:Date.now()});}
+  }},
+},outbound:{deliveryMode:'direct',textChunkLimit:32768,sendText:blocked,sendMedia:blocked}});
+export default defineChannelPluginEntry({id:'mina',name:'Mina AI 助手',description:'Durable private Mina channel',plugin:minaChannel});

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "mina",
+  "channels": ["mina"],
+  "name": "Mina AI 助手",
+  "description": "Private Mina channel with durable polling and execution permits.",
+  "configSchema": {"type": "object", "additionalProperties": false, "properties": {}},
+  "channelConfigs": {
+    "mina": {
+      "schema": {
+        "type": "object", "additionalProperties": false,
+        "properties": {
+          "enabled": {"type": "boolean"},
+          "accounts": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object", "additionalProperties": false,
+              "required": ["configFile"],
+              "properties": {"enabled": {"type": "boolean"}, "configFile": {"type": "string"}, "python": {"type": "string"}}
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@minaim/openclaw-channel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "files": [
+    "index.mjs",
+    "bridge.mjs",
+    "openclaw.plugin.json",
+    "vendor",
+    "setup.mjs",
+    "diagnostics.mjs"
+  ],
+  "engines": {
+    "node": ">=24.16.0 <25 || >=26.1.0"
+  },
+  "peerDependencies": {
+    "openclaw": "2026.10.5"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.mjs"
+    ],
+    "channel": {
+      "id": "mina",
+      "label": "Mina AI 助手",
+      "blurb": "Connect your own Agent to Mina private chats."
+    }
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "description": "Mina IM channel for self-hosted OpenClaw agents with private chat, images and documents.",
+  "license": "UNLICENSED",
+  "author": "Mina IM",
+  "keywords": [
+    "openclaw",
+    "mina",
+    "im",
+    "agent",
+    "channel"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/Mina-IM/mina-agent-plugins.git",
+    "directory": "openclaw"
+  },
+  "bugs": {
+    "url": "https://gitee.com/Mina-IM/mina-agent-plugins/issues"
+  },
+  "homepage": "https://gitee.com/Mina-IM/mina-agent-plugins",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/setup.mjs

@@ -0,0 +1,37 @@
+import {resolveStateDir} from 'openclaw/plugin-sdk/state-paths';
+import {join,isAbsolute} from 'node:path';
+import {createConfiguration,probeConfiguration,localError} from './diagnostics.mjs';
+const account=(cfg,id)=>cfg.channels?.mina?.accounts?.[id]??{};
+const keep=({cfg,accountId})=>Boolean(account(cfg,accountId).configFile);
+const field=(inputKey,message,extra={})=>({inputKey,message,required:true,shouldPrompt:p=>!keep(p),applySet:({cfg})=>cfg,...extra});
+const identity=(prefix)=>({value})=>new RegExp(`^${prefix}_[a-f0-9]{32}$`).test(value)?undefined:'请从 Mina 助手接入页复制有效标识';
+export const minaSetupAdapter={
+ applyAccountConfig:({cfg,input})=>{if(input?.token||input?.privateKey)throw localError('configuration_invalid');return cfg;},
+};
+export const minaSetupWizard={
+ channel:'mina',
+ status:{configuredLabel:'Mina 配置已填写',unconfiguredLabel:'Mina 尚未配置',configuredHint:'运行状态需另行检查',unconfiguredHint:'连接你自己的 Agent',resolveConfigured:keep},
+ introNote:{title:'连接 Mina AI 助手',lines:['插件需要 Python 3.9+。从 Mina App 的 AI 助手接入页复制信息。','密钥通过隐藏输入保存到私有文件，不写入 OpenClaw 配置。已有账号配置保留；更换身份请新建 account。']},
+ credentials:[],
+ textInputs:[
+  field('gateway','Mina HTTPS 网关（含部署路径）',{validate:({value})=>{try{const url=new URL(value);return url.protocol==='https:'&&!url.username&&!url.password&&!url.search&&!url.hash?undefined:'需要有效 HTTPS 网关';}catch{return '需要有效 HTTPS 网关';}}}),
+  field('app_id','Mina AppID',{validate:identity('mina')}),field('bot_id','Mina 助手 ID',{validate:identity('bot')}),
+  field('owner_id','Mina 所有者 ID',{validate:({value})=>/^[A-Za-z0-9_-]{1,128}$/.test(value)?undefined:'所有者 ID 无效'}),
+  field('credential_version','凭证版本',{initialValue:()=> '1',validate:({value})=>/^[1-9][0-9]{0,15}$/.test(value)?undefined:'请输入正整数版本'}),
+  field('app_secret','Mina AppSecret（隐藏输入）',{sensitive:true,validate:({value})=>/^[A-Za-z0-9_-]{32,128}$/.test(value)?undefined:'密钥格式无效'}),
+  field('python','Python 可执行文件',{initialValue:()=> 'python3'}),
+  field('media_roots','允许回传文件的目录，逗号分隔；留空仅接收文件',{required:false}),
+  field('media_hosts','允许获取远程输出文件的 HTTPS 域名，逗号分隔；默认不允许',{required:false}),
+ ],
+ async finalize({cfg,accountId,credentialValues}){
+  if(!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(accountId))throw localError('configuration_invalid');
+  if(keep({cfg,accountId})){const report=await probeConfiguration(account(cfg,accountId));if(!report.ok)throw localError(report.code);return {cfg};}
+  const v=credentialValues;const values={gateway:v.gateway,app_id:v.app_id,bot_id:v.bot_id,owner_id:v.owner_id,app_secret:v.app_secret,credential_version:Number(v.credential_version)};
+  for(const name of ['media_roots','media_hosts'])if(v[name])values[name]=v[name].split(',').map(x=>x.trim()).filter(Boolean);
+  const base=resolveStateDir();if(!isAbsolute(base))throw localError('configuration_invalid');
+  const created=await createConfiguration(join(base,'mina',accountId),values,v.python||'python3');
+  const current=cfg.channels?.mina??{};
+  return {cfg:{...cfg,channels:{...cfg.channels,mina:{...current,enabled:current.enabled??true,accounts:{...current.accounts,[accountId]:created}}}}};
+ },
+ completionNote:{title:'Mina 配置已保存',lines:['启动或重启 Gateway 后，在 Mina App 检查连接状态。','配置检查不等于联网认证。群调用未开放；文档读取依赖 Agent 工具。']},
+};

package/vendor/compatibility.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "plugin_version": "0.2.0",
+  "platforms": ["linux", "darwin"],
+  "OpenClaw": {"host_versions": ["2026.10.5"], "python_min": [3, 9], "node": ">=24.16.0 <25 || >=26.1.0"},
+  "Hermes": {"host_versions": ["0.21.3"], "python_min": [3, 11], "python_max_exclusive": [3, 14]}
+}