AI导哈

版本协调工具

MemNexus平台的中央版本协调工具，用于管理OpenAPI规范、平台版本和组件兼容性，以及生成SDK、CLI和MCP服务器包。

  • by memnexus-ai
  • 本地部署
  • 更新于
在 GitHub 查看 memnexus-ai/mx-releases

使用说明

mx发布

MemNexus平台的中央发布协调

概述

此存储库用作 单一事实来源 用于：

  • ✅ OpenAPI规范
  • ✅ 平台版本控制和组件兼容性
  • ✅ 生成的包（SDK、CLI、MCP服务器）
  • ✅ 跨所有MemNexus组件的协调发布

关键原则： 所有面向客户端的包（SDK、CLI、MCP服务器）都是使用相同的OpenAPI规范生成的 Liblab 并共享相同的版本号，确保MemNexus API所有接口的一致性。

建筑

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────────────────────────────┐
│   mx-core-api   │     │  mx-api-gateway │     │              mx-releases                │
│                 │     │                 │     │                                         │
│ deploy-core-    │────▶│ deploy-         │────▶│  specs/openapi.yaml                     │
│ api.yml         │trig │ gateway.yml     │push │                                         │
│ (deploys +      │ger  │ (update routes) │spec │  packages/                              │
│  triggers gw)   │     │                 │     │    sdk/ (@memnexus-ai/sdk)              │
│                 │     │                 │     │    cli/ (@memnexus-ai/cli)              │
│                 │     │                 │     │    mcp/ (@memnexus-ai/mcp-server)       │
│                 │     │                 │     │                                         │
│                 │     │                 │     │  VERSION.yaml                           │
└─────────────────┘     └─────────────────┘     └─────────────────────────────────────────┘

存储库结构

mx-releases/
├── README.md                     # This file
├── VERSION.yaml                  # Single source of truth for versions
├── CHANGELOG.md                  # Platform-wide changelog
├── liblab.config.json            # liblab configuration for package generation
│
├── packages/
│   ├── sdk/                      # @memnexus-ai/sdk (generated by liblab)
│   │   ├── package.json
│   │   ├── src/                  # Generated TypeScript SDK
│   │   └── tests/
│   │
│   ├── cli/                      # @memnexus-ai/cli (generated by liblab)
│   │   ├── package.json
│   │   ├── src/                  # Generated CLI commands
│   │   ├── bin/
│   │   └── tests/
│   │
│   └── mcp/                      # @memnexus-ai/mcp-server (generated by liblab)
│       ├── package.json
│       ├── src/                  # Generated MCP server
│       ├── bin/
│       └── tests/
│
├── specs/
│   ├── openapi.yaml              # Current/latest OpenAPI spec
│   └── archive/                  # Historical specs for reference
│       ├── openapi-1.0.0.yaml
│       └── openapi-1.1.0.yaml
│
└── .github/
    └── workflows/
        ├── determine-version.yml          # Analyze spec changes, determine version
        ├── generate-publish-packages.yml  # Generate SDK/CLI/MCP, publish to npm
        ├── sync-postman.yml               # Sync to Postman
        ├── finalize-release.yml           # Create platform release
        ├── manual-release.yml             # Manual release trigger
        └── ci.yml                         # PR validation

已发布的软件包

所有包都发布到公共npm注册表(npmjs.com)并共享相同的版本号。

包 描述 npm
@memnexus ai/sdk 用于编程API访问的TypeScript SDK
@memnexus ai/cli 终端用户的命令行界面
@memnexus ai/mcp服务器 用于AI代理集成的MCP服务器

安装

# SDK for Node.js/TypeScript applications
npm install @memnexus-ai/sdk

# CLI for command-line usage
npm install -g @memnexus-ai/cli

# MCP Server for AI agents (Claude Desktop, etc.)
npm install @memnexus-ai/mcp-server

运作原理

自动发布管道（7个阶段）

  1. 第一阶段：测试与部署 （mx核心api）

    • 开发人员将更改推送到mx-core api
    • 测试运行、Docker镜像构建、部署到开发环境
    • 成功后发送到mx-api网关

  2. 第2阶段：更新网关路由 （mx-api网关）

    • 接收来自核心api的调度
    • 更新Kong网关配置
    • 验证路线是否正常工作

  3. 第三阶段：同步OpenAPI规范 （mx-api网关→ mx发布）

    • 从部署的核心API获取规范(/api-docs-json)
    • 验证规范（openapi生成器、频谱）
    • 将经过验证的规范推送到 mx-releases/specs/openapi.yaml

  4. 第四阶段：确定版本 （mx版本）

    • 分析与以前版本相比的规范更改
    • 确定版本凹凸（主/次/补丁）
    • 用途 openapi-diff 用于检测突变

  5. 第5阶段：生成和发布 （mx版本）

    • 运行liblab以生成SDK、CLI和MCP服务器
    • 在一次操作中生成的所有三个包
    • 测试所有包装（单元+E2E）
    • 以相同版本将所有内容发布到npmjs.com

  6. 第六阶段：同步邮递员 （mx版本）

    • 更新邮递员规范中心
    • 更新邮差收藏

  7. 第7阶段：最终发布 （mx版本）

    • 更新版本.yaml
    • 更新CHANGELOG.md
    • 在GitHub上创建平台版本

统一版本控制

所有生成的包（SDK、CLI、MCP）共享相同的版本号，因为：

  • 它们都是由 相同的OpenAPI规范
  • 它们是在一个 单次liblab操作
  • 他们代表 相同的API表面
  • 他们被释放了 原子性地 （全部或无）

这确保了完美的兼容性，消除了版本混淆。

版本.yaml

这 VERSION.yaml file是所有组件版本的唯一真实来源：

platform: 1.0.0                    # Overall platform version

generated:
  version: 1.0.0                   # Shared version for SDK, CLI, MCP
  spec_version: 1.0.0              # OpenAPI spec version

components:
  core-api:
    version: 1.0.0
  gateway:
    version: 1.0.0

开发流程

API变更

  1. 更新核心API -使用OpenAPI装饰器添加/修改端点
  2. 推到main -触发部署和完整管道
  3. 等待管道 -自动化流程运行（通常<30分钟）
  4. 验证包 -查看npmjs.com以获取新发布的版本
  5. 更新消费者 -应用程序可以升级到新的SDK/CLI/MCP

对于手动发布

需要时使用手动发布工作流：

  • 强制指定特定版本号
  • 在不更改API的情况下重新发布
  • 测试释放管道
# Trigger via GitHub Actions UI
# Go to Actions → Manual Release → Run workflow
# Specify version and publish options

组件存储库

存储库 描述 版本
mx核心api 核心API服务
mx-api网关 香港API网关
mx发布 发布协调（此仓库）

从旧包迁移

@memnexus ai/合同→ @memnexus ai/sdk

旧的 @memnexus-ai/contracts 包装已被替换为 @memnexus-ai/sdk.

之前：

import { MemNexusClient } from '@memnexus-ai/contracts';

之后：

import { MemNexusClient } from '@memnexus-ai/sdk';

迁移步骤：

  1. 替换 @memnexus-ai/contracts 和 @memnexus-ai/sdk 在package.json中
  2. 更新代码中的导入
  3. 测试您的应用程序
  4. API完全相同-只更改了程序包名称

发布版本控制策略

我们跟随 语义版本控制2.0.0:

  • 重大 （X.0.0）-突破性更改

    • 已删除端点
    • 更改了必填字段
    • 重命名路径
    • API更改不兼容

  • 次要的 （0.X.0）-新功能（向后兼容）

    • 新端点
    • 新的可选字段
    • 性能改进

  • 补丁 （0.0.X）-错误修复（向后兼容）

    • 错误修正
    • 文档更新
    • 非功能性变更

版本颠簸是 自动确定 通过分析OpenAPI规范的变化 openapi-diff，但如果需要，可以手动覆盖。

贡献

报告问题

  • SDK/CLI/MCP问题：在此存储库中打开
  • API功能问题：打开 mx核心api
  • 网关/路由问题：打开 mx-api网关

拉取请求

这个存储库主要是自动化的。手动PR通常只需要用于：

  • 文档更新
  • 工作流程改进
  • liblab配置更改

支持

许可证

版权所有©2025 MemNexus AI

状态: 🚀 积极发展

详细实施计划见 mx-api网关问题#16

相关 MCP