# mp-uni-app

**Repository Path**: sliver-ring_admin/mp-uni-app

## Basic Information

- **Project Name**: mp-uni-app
- **Description**: 小程序快速启动架构
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uni-app 小程序快速启动模板

这是一个给无技术背景用户准备的 uni-app Vue3 快速启动模板。

它的目标不是提前塞满业务功能，而是先把一套稳定的开发规矩立好：设计 token、uview-plus 组件库、目录归属、请求封装、多语言、主题、日夜间模式、Pinia 状态管理、AI 开发纪律都已经接好。你后续只需要把项目想法交给 AI，AI 必须先按模板规则初始化，再开始长出真正的页面和业务。

## 适合谁

- 想用 HBuilderX 快速启动小程序的人。
- 不会写代码，但希望把项目交给 AI 开发的人。
- 不想每个页面都被 AI 写成不同风格的人。
- 想后期保留 H5、App 或其他小程序平台扩展可能的人。

## 这个模板已经包含什么

- uni-app Vue3 项目基础结构。
- uview-plus 组件库接入，项目代码统一使用 `up-*` 组件前缀。
- 唯一设计 token 真源：`styles/tokens.scss`。
- 设计规范和开发规则：`dev-docs/设计规范.md`、`dev-docs/开发规则.md`。
- AI 宪法：`AGENTS.md`。
- 首次初始化向导：`AI_TEMPLATE_INIT.md`。
- 生产级请求底座：`api/request.js`，复用 uview-plus 内置 HTTP 能力。
- 多语言入口：`i18n/`。
- 多主题和日夜间模式入口：`theme/`。
- Pinia 状态管理入口：`stores/`。
- 模板门禁脚本：`scripts/check-template-guardrails.mjs`。

## 当前状态

当前模板还没有完成具体项目初始化。

判断方式很简单：只要根目录里还存在 `AI_TEMPLATE_INIT.md`，就说明这个模板还处在“首次初始化阶段”。在这个阶段，AI 不允许直接开始写业务页面、接口、组件或工具函数，必须先问清楚项目类型、首发平台、多端策略、视觉风格、主色、语言、主题和 Pinia 状态边界。

初始化完成后，AI 必须把最终选择写入 `dev-docs/设计规范.md`，必要时更新 `AGENTS.md`，最后删除 `AI_TEMPLATE_INIT.md`。

## 第一次怎么用

1. 用 HBuilderX 打开整个项目文件夹。
2. 确认项目里有 `uni_modules/uview-plus`。
3. 如果项目里没有 `node_modules/`，让 AI 或懂技术的人执行一次：

```sh
npm install
```

4. 在 HBuilderX 里选择运行到浏览器、微信开发者工具或其他目标平台。
5. 如果看到模板首页，说明基础骨架已经接通。

注意：能运行只代表技术骨架可用，不代表项目已经初始化完成。只要 `AI_TEMPLATE_INIT.md` 还在，就必须先初始化。

## 推荐安装 AI 项目治理 skill

如果你使用的是支持 Codex skills 的 AI，建议额外安装 `sliver-vibe-coding`。它不是小程序源码，也不是 HBuilderX 运行依赖，而是让 AI 在立项、拆阶段、加功能、验收、发布时更懂怎么治理项目。

安装位置必须是用户全局 skills 目录，不要放进当前项目：

```sh
git clone https://gitee.com/sliver-ring_admin/sliver-vibe-coding.git ~/.codex/skills/sliver-vibe-coding
```

如果你不会执行命令，可以把这句话交给 AI：

```text
如果当前环境支持 Codex skills，请先评估 sliver-vibe-coding 是否适合这个项目；如果适合，请帮我安装到 ~/.codex/skills/sliver-vibe-coding。不要把它安装进当前 uni-app 项目目录。安装后如果它和本项目 AGENTS.md 或 dev-docs/ 冲突，以本项目规则为准。
```

## 加入交流群

遇到模板初始化、HBuilderX 运行、AI 开发规则或 `sliver-vibe-coding` 安装问题，可以扫码加入交流群。

![甲壳虫 Agent-vibe coding 交流 2 群二维码](./static/community/wechat-group-qr.jpg)

当前二维码有效期至 2026 年 7 月 20 日；过期后请回到项目发布页或联系维护者获取最新二维码。

## 交给 AI 时复制这段话

把整个项目文件夹交给 AI 后，先复制下面这段：

```text
请先阅读 AGENTS.md、dev-docs/设计规范.md、dev-docs/开发规则.md 和 styles/tokens.scss。

如果根目录存在 AI_TEMPLATE_INIT.md，说明这是首次拿到模板。请先按 AI_TEMPLATE_INIT.md 一步步问我完成初始化：项目类型、目标用户、首发平台、多端策略、整体风格、主色调、参考案例、字号、圆角、间距、uview-plus 主题、多语言、日夜间模式、Pinia 状态边界。

如果当前环境支持 Codex skills，请评估是否建议安装 sliver-vibe-coding。它只能安装到 ~/.codex/skills/sliver-vibe-coding，不能放进当前项目目录；如果它和本项目 AGENTS.md 或 dev-docs/ 冲突，以本项目规则为准。

初始化完成前，不要开始写业务页面、接口、组件、工具函数或业务代码。每完成一项就勾选一项。最后把初始化总结写入 dev-docs/设计规范.md，必要时更新 AGENTS.md，然后删除 AI_TEMPLATE_INIT.md。
```

## 初始化时 AI 会问什么

AI 会按顺序问你这些问题：

- 这个小程序主要做什么，用户是谁？
- 确定只做微信小程序，还是以后可能扩到支付宝、抖音、H5 或 App？
- 想要什么整体视觉风格？
- 主色有没有偏好？
- 有没有喜欢或不喜欢的参考产品、截图、链接？
- 字号要紧凑、标准，还是偏大一点？
- 圆角要硬朗、标准，还是更圆润？
- 页面信息密度要紧凑、标准，还是留白多一点？
- 首版只做中文，还是要预留多语言？
- 要不要日夜间模式，是否预留多主题？
- 哪些状态真的需要跨页面共享，应该进入 Pinia？
- 当前 AI 是否支持并建议安装 `sliver-vibe-coding` 项目治理 skill？

你不需要回答技术细节。你只需要用普通话描述业务和喜好，AI 会把答案翻译成模板规则。

## 初始化完成后怎么继续开发

初始化完成后，再让 AI 做具体功能。推荐这样说：

```text
请先阅读 AGENTS.md、dev-docs/设计规范.md、dev-docs/开发规则.md 和 styles/tokens.scss，然后根据当前规则实现这个功能：……
```

如果是做页面，最好同时给 AI：

- 页面要解决什么问题。
- 用户进来后第一步做什么。
- 页面里必须有哪些信息。
- 有没有参考截图或竞品链接。
- 哪些东西第一版先不要做。

AI 写完后，应运行模板门禁：

```sh
node scripts/check-template-guardrails.mjs
```

这个命令用于检查 AI 有没有绕开模板规则，例如硬写样式、混入第二套组件库、绕开请求封装、跳过 i18n、跳过 Pinia owner 等。

## 重要文件说明

- `README.md`：给用户看的入口说明，不是规则真源。
- `AGENTS.md`：AI 必须遵守的项目宪法。
- `AI_TEMPLATE_INIT.md`：首次初始化向导，存在时不能直接做业务开发。
- `dev-docs/设计规范.md`：视觉风格、token、主题、多语言、日夜间模式规则。
- `dev-docs/开发规则.md`：目录归属、组件封装、请求、工具函数、Pinia、平台 API 规则。
- `styles/tokens.scss`：唯一设计 token 真源。
- `uni.scss`：只做 SCSS 变量和 uview-plus 主题桥接。
- `App.vue`：引入 uview-plus 全局样式、全局样式和主题 CSS 变量。
- `api/request.js`：唯一 HTTP 请求底座。
- `i18n/`：可见文案和语言切换入口。
- `theme/`：主题偏好、日夜间模式入口。
- `stores/`：Pinia 状态管理入口。
- `platform/`：确实需要平台专有能力时的隔离区。
- `utils/`：通用、低副作用工具函数。
- `components/base/`：通用基础组件。
- `components/biz/`：业务组件。

如果 README 和 `AGENTS.md` 或 `dev-docs/` 冲突，以 `AGENTS.md` 和 `dev-docs/` 为准。

## 不要这样用

- 不要在 `AI_TEMPLATE_INIT.md` 还存在时让 AI 直接做业务页面。
- 不要让 AI “随便照着截图做”，必须先落回 token 和设计规范。
- 不要混入第二套 UI 组件库。
- 不要在页面里直接硬写颜色、字号、圆角、间距。
- 不要绕过 `api/request.js` 直接写请求。
- 不要把页面临时状态塞进 Pinia。
- 不要把 HBuilderX 优先模板改成复杂 CLI 脚手架。

## 常见问题

### 我不会技术，能用吗？

能。你只需要用 HBuilderX 打开项目，然后把项目交给 AI，并复制上面的启动提示。AI 会按初始化向导问你问题。

### 为什么不能直接开始写页面？

因为这个模板是“设计优先、架构优先”。如果不先确定风格、主色、平台、多语言、主题和状态边界，AI 很容易每个页面写一套规则，后期会越来越乱。

### 这个模板有没有后端？

没有预置后端。模板只提供前端请求底座 `api/request.js`。后端地址、登录鉴权、业务错误码、上传、支付等，必须等具体项目确认后再配置。

### 只做中文，还需要 i18n 吗？

需要。首版可以只有中文，但文案统一放进 `i18n/`，后期加英文或其他语言时不用回头重构页面。

### 只做一种主题，还需要主题规范吗？

需要。首版可以只开放浅色主题，但 token 和主题入口必须规范化，后期增加暗色模式或品牌换肤时不会推倒重来。

### 怎么知道 AI 有没有乱写？

让 AI 每次改完后运行：

```sh
node scripts/check-template-guardrails.mjs
```

如果门禁不通过，先修规则违规，再继续做功能。