Imported from trueai-org/vue-template (AGENTS.md). Install upstream with npx skills add trueai-org/vue-template. Copyright stays with the author.

AGENTS.md

AI 辅助维护本仓库时的约束规则。所有规则与 README「原则与规则」一致，此处按可执行性重新组织。

项目定位

本仓库是一个自维护的 Vue 脚手架增量层，不替代 create-vite，而是在其产物之上用脚本可重现地注入自定义模块。核心闭环：manifest.mjs（单一事实来源）-> generate.mjs（生成快照）+ sync.mjs（同步上游）。

文件分类（来自 scripts/manifest.mjs，修改时改此处）

模块系统

模块层级（tier）

当前模块清单

同类框架选择组（CHOICE_GROUPS）

got / undici 是 Node.js 端 HTTP 库，不打浏览器包，故不作为 http 选项。

核心约束

1. 禁止手动编辑官方文件

以下文件由 generate.mjs 脚本注入，不可手动修改：

• src/main.ts / src/App.vue / src/style.css / vite.config.ts / index.html / .gitignore

这些文件可包含 @module / @option 标记块（见占位约定），标记块是注释，不破坏工作模板的可构建性。修改这些文件 = 修改 generate.mjs 的覆盖源。

以下文件为官方产物，不可修改：tsconfig*.json / public/ / src/components/ / src/assets/

2. 依赖管理通过 manifest 驱动

• 新增/移除依赖时，修改 scripts/manifest.mjs 的 MODULES 或 CHOICE_GROUPS，不手动编辑 package.json
• generate.mjs 从 MODULES + CHOICE_GROUPS 自动聚合 pnpm add 命令
• 工作模板 = 全模块 + 全选择组超集，须安装所有出现在共享文件 import 中的依赖
• 版本锁定原因须在 MODULES 注释中说明（如 pinia@^3 的兼容性约束）

3. 脚本驱动一切变更

• 新增自定义模块 -> 在 MODULES 中添加条目（deps / dirs / files / scripts / tier）
• 新增同类框架选择 -> 在 CHOICE_GROUPS 中添加条目
• 新增页面 -> 在 src/views/ 创建 + src/router/index.ts 注册路由
• 所有变更须保证 pnpm generate 能完整复现

4. 官方推荐接入最小化

遵循最小化、模块化、最新、官方推荐四原则：

• 最小化：自定义代码仅做接入（import + 注册），不添加非官方默认配置项。判断标准：官方文档快速开始 / 默认配置中没有的选项，不添加；需要自定义时在注释中说明原因
• 模块化：每个模块独立可移除（见规则 5），不与其他模块耦合
• 最新：依赖版本保持最新（除兼容性锁定外），使用官方当前推荐的 API 和配置方式（如 presetWind3 而非已弃用的 presetUno）
• 官方推荐接入：所有配置遵循官方文档的推荐做法，不引入个人偏好或非官方默认值（如 presetIcons({ scale: 1.2 }) 是个人偏好，应使用 presetIcons()）

同时遵守不过度封装：无 bootstrap / layout 组件、无 HTTP 响应解包拦截器封装、无 UI 组件库封装。

5. 模块独立可移除

每个自定义模块须满足：配置隔离、使用隔离、可追溯（README 标注）、可验证（移除后 pnpm build 通过）。

6. 占位约定（模块注入机制）

共享文件中的模块代码用标记注释包裹，generate.mjs 按选择裁剪：

// TS/JS：
// @module:<name>
模块代码...
// @end

// Vue 模板：
<!-- @module:<name> -->
模块代码...
<!-- @end -->

// 同类框架选择组：
// @option:<group>.<option>
选择组代码...
// @end

• 选中：保留内容，移除标记行 -> 干净代码
• 未选中：移除整块（含标记行）-> 不存在的代码
• 工作模板 = 全标记块保留的超集（始终可构建）
• 整文件差异用变体覆盖：scripts/variants/<group>.<option>/ 下的文件覆盖默认文件

7. 依赖兼容性

• vue / typescript / vue-tsc 等基础包版本由 create-vite 决定
• 新增依赖须兼容当前基础包版本，不盲目使用最新版
• 版本冲突时在 MODULES 中锁定并注释原因

禁止操作清单

变更检查清单

1. pnpm build 通过（类型检查 + 生产构建）
2. 如果修改了 manifest.mjs，确认 generate.mjs 和 sync.mjs 的引用一致
3. 如果新增了依赖，确认 MODULES / CHOICE_GROUPS 已更新且 package.json 与之一致
4. 如果新增了文件/目录，确认 MODULES 的 files / dirs 已更新
5. 如果修改了官方接入文件，确认变更是通过标记块/变体而非破坏文件结构
6. 如果新增了模块，确认共享文件中已用 @module 标记块包裹接入代码

常用命令