Frontend · AI Programming

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

By skiyee · Jul 13, 2026

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 conversation is light on debate. One person asks where to find the demo, and the author points to the repository. Two others offer brief endorsements: one confirms it works well in practice, the other plans to adopt it next time.

— Practical validation: at least one user has adopted the starter and reports it works well.

— Intent to adopt: another developer finds the starter polished enough to plan using it on an upcoming project.

— Demo availability: the online example is still in progress, but the source code is accessible on GitHub and Gitee for local preview.

Featured comments

百友 1 likes

Already using it, works great.

aloney 1 likes

Looks very complete, will try it on the next project. [like]

See top comments, translated →

Source: juejin.cn ↗ Google Translate ↗ Backup ↗