跪拜 Guibai
← All articles
Frontend · AI Programming

Swapping a Uni-App Starter's Base Made AI Agents Stop Breaking the Project

By skiyee ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

AI coding tools fail most often when a project's conventions are implicit and scattered. A starter that makes those conventions machine-readable through structured Skills files turns a black-box codebase into one an agent can navigate reliably, which directly reduces the edit-fix-edit loop that wastes developer time.

Summary

wot-starter bundles a uni-app project from scattered Vite plugins, each governing its own piece of routing, imports, and the app shell. oiyo-starter keeps the same Wot UI components and tooling but replaces that base with the Oiyo framework, which collapses configuration into a single oiyo.config.ts file, provides native layout and page primitives instead of a plugin-simulated root component, and unifies page registration through definePageMeta plus a scan convention.

The most practical shift is for AI coding agents. Instead of loose .cursor/rules files, the starter ships a Skills suite that encodes the framework's conventions and component usage. Agents that previously mangled auto-generated files or misplaced page metadata now follow the baked-in rules, cutting down manual rework.

Migration is designed to be low-friction: router, charts, and CI configurations carry over, and a single pnpm install generates types and routes automatically.

Takeaways
— oiyo-starter replaces vitese-uni-app and its plugin collection with the Oiyo framework, keeping Wot UI components and surrounding tooling intact.
— All project configuration—component scanning, API auto-imports, directory conventions—lives in a single oiyo.config.ts file instead of being split across vite.config and manifest.config.
— The app shell uses native OiyoLayout and OiyoPage components rather than the uni-ku-root plugin that simulates a root component in standard uni-app.
— Page metadata is declared with definePageMeta at the page level, and routes plus pages.json are generated automatically from that declaration.
— The built-in OiyoHttp request library replaces Alova, providing layered instance creation, automatic retries, lifecycle hooks, and request cancellation with zero extra configuration.
— A bundled Skills suite feeds the Oiyo framework's conventions and Wot UI usage patterns directly to AI agents, preventing them from editing auto-generated files or misplacing page definitions.
— Migration retains the existing router, uni-echarts, and CI setup; running pnpm install auto-generates types and routes via the prepare script.
Conclusions

The core claim is not that the framework is technically superior, but that explicitness is a feature for AI tooling. When every convention lives in a config file and a Skills document, the agent's failure mode shifts from guessing wrong to following a spec.

Centralizing configuration into a single file reduces the cognitive load for humans, but the AI benefit is larger: a single source of truth eliminates the ambiguity that causes agents to modify generated artifacts like pages.json.

Bundling AI instructions as a first-class project artifact—rather than an afterthought in a .cursor/rules file—treats agent readability as a build concern, similar to how TypeScript treats type safety.

Concepts & terms
definePageMeta
A compile-time macro in the Oiyo framework that declares page-level metadata (type, layout, navigation style, tab configuration) directly in a page component. The framework uses this to auto-generate routes and the uni-app pages.json manifest.
Oiyo scan convention
A configuration-driven mechanism where directories and glob patterns specified in oiyo.config.ts determine which components, APIs, and utilities are auto-imported across the project, replacing multiple Vite plugin configurations with a single declaration.
Skills (AI context)
Structured documentation files bundled with oiyo-starter that describe the framework's engineering conventions and component library usage in a format AI coding agents can ingest, so the agent follows project rules without needing to infer them from scattered source files.
From the discussion

The discussion centers on practical access to the starter project and its AI tooling. Interest splits between immediate availability of the demo and the release status of the promised AI skills. One user confirms the starter is already usable in production.

— The live demo referenced in the article is not yet online; source code is available on GitHub and Gitee for local preview.
— The integrated AI skills appear to be unreleased, raising a question about the completeness of the advertised AI support.
— At least one developer has adopted the starter and reports a positive experience.
Featured comments
aloney

Where can I see the example project shown in the video in the article?

skiyee

The live online example project is in progress. For now, you can pull the same project from the links below to preview it. Github: https://github.com/wot-ui/oiyo-starter Gitee: https://gitee.com/skiyee/oiyo-starter

aloney  → skiyee

Got it. One more question: the complete set of AI skills mentioned in the AI support section — are those also not released yet?

百友 1 likes

Already using it. Works great.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗