介绍

Oiyo 以融合AI协作，提升开发体验，降低心智成本为三大理念

oiyo 是基于 UniApp 的增强型工程框架。你负责业务，它负责其余：自动路由、智能布局、根上下文、路由中间件、甄选依赖、工程约定与一站式团队服务。

以「融合AI协作 · 提升开发体验 · 降低心智成本」为三大理念，支持个人、公司、企业免费商用，让每一位开发者都能最大程度地平权体验、开发、发布！

符合 AI 时代的约定式框架

用约定替代记忆，用生成替代手动，让你只写业务代码。

自动路由

基于文件系统，页面文件即路由。pages.json 由扫描自动生成，跳转 API 还带类型提示。

~~困扰：pages.json 手动维护，页面越加越多，遗漏、重复、路径写错~~

src/pages.json

// 由 oiyo 管理并自动生成的 pages.json
{
  "pages": [
    { "path": "pages/home/index" }, 
    { "path": "pages/my/index" }
  ],
  "subPackages": [
    {
      "root": "packages/order",
      "pages": [
        { "path": "pages/list/index" }
      ]
    }
  ]
}

页面元信息

definePageMeta() 让导航栏样式、首页声明、TabBar 配置与页面代码同处维护。

~~困扰：页面配置集中堆在 pages.json，离页面代码越来越远~~

src/pages/home/index.vue

<script setup>
definePageMeta({
  type: "home",
  layout: "tabbar",
  style: { navigationBarTitleText: "首页" },
  tab: { index: 0, text: "首页" },
});
</script>

<template>
  <view>Home Page</view>
</template>

布局系统

相同的页面布局只需在 src/layouts 定义，并在页面通过一行 layout 声明即可套用，实现业务与容器彻底解耦。

~~困扰：TabBar布局、全屏布局等页面布局在几十个页面里重复声明使用~~

src/pages/home/index.vue

<script setup>
definePageMeta({
  layout: "tabbar",
});
</script>

根上下文

defineRootContext() + useRootContext()：自定义的全局弹窗、全局开关只需在 App.vue 定义，随时使用。

~~困扰：全局弹窗没有统一管理，只能分开管理并且层层传递~~

src/App.vue

<script setup lang="ts">
const { user, token, logout, toast } = defineRootContext(() => {
  const user = ref<{ name: string } | null>(null);
  const token = ref("");

  function logout() {
    user.value = null;
    token.value = "";
  }

  const toast = ref(false)

  return { user, token, logout, toast };
});
</script>

<template>
  <OiyoLayout>
    <OiyoPage />
  </OiyoLayout>

  <CustomToast v-if="toast" />
</template>

跳转守卫

具名与全局中间件，异步拦截、goTo() 重定向、abortNavigation() 中止，路由守卫人性化配置。

~~困扰：路由拦截无法清晰定义，使用拦截器心智模型较高~~

src/middlewares/auth.global.ts

const WHITE_LIST = ["/pages/index/index", "/pages/login/login"];

export default defineRouteMiddleware((to, from) => {
  if (WHITE_LIST.includes(to.path)) {
    return;
  }

  if (!uni.getStorageSync("token")) {
    return goTo("/pages/login/login", { replace: true });
  }
});

自动导入

API 与 Component 自动扫描免主动 import，内置常见路径，类型提示完整。

~~困扰：每次都要写一长串 import，改个目录就要全局搜替换~~

oiyo.config.ts

import { defineOiyoConfig } from "@skiyee/oiyo/config";

export default defineOiyoConfig({
  scan: {
    apis: ["utils/*.ts"],
    components: ["ui/**/*.vue"],
  },
});

数据请求

http 开箱即用，实例派生分层、生命周期钩子、自动重试、请求中断，一应俱全。

~~困扰：请求封装各写各的，token 注入和错误提示散落各处~~

src/utils/api.ts

// 公共实例
const api = createHttp({
  baseURL: "https://api.example.com",
  onBeforeRequest({ url, options }) {
    console.log("发起请求", url);
  },
});

// 派生带鉴权的实例
export const authApi = api.create({
  headers: { Authorization: "Bearer xxx" },
});

工程约定

固定目录 + 三层配置文件，结构稳定可预期，人、团队、AI 都能清晰理解。

~~困扰：目录结构无规定式约定，新成员和 AI 都要摸索半天~~

oiyo.config.ts

import { defineOiyoConfig } from "@skiyee/oiyo/config";

// 固定目录约定：components / composables / layouts / middlewares / pages / packages
export default defineOiyoConfig({
  // 自动打开小程序工具 IDE
  ide: {
    open: true
  }
});

三大理念

理念不是口号，而是每一个设计决策的取舍依据：

融合AI协作 — 目录即文档、约定即语境。固定的工程结构、LLMs.txt 与 Skills 让 AI 和人读的是同一套约定，AI 生成的代码天然贴合项目结构。
提升开发体验 — 重复劳动交给框架：路由注册、页面配置、模块导入、骨架复用全部自动化，且类型提示贯穿始终，写错路径在编译期就会暴露。
降低心智成本 — 不需要记住「什么放哪里」，只需要遵守「哪里放什么」。新成员从一周上手缩短到一天，页面越多，这套约定省下的心智越多。

契合 AI

目录约定天然利于 AI 理解，同时提供专项支持：

LLMs.txt：让任意 AI 工具快速掌握 Oiyo 的用法与最佳实践
Skills：pnpx skills add skiyee/skills --skill oiyo-starter，引导 AI 按工程约定开发

适合谁

正在使用 UniApp 的中小团队
希望降低协作成本的多人项目
不想把心智花在工程维护上，只想专注业务的团队
需要专业团队陪跑接入、迁移与排障的项目

安装

通过在线模板导入快速接入体验