OpenCart 前端模板引擎 CurlyTag 的 Vite+ 统一工具链实战指南（AGENTS.md 深度解读）

• 电商
• 后端

导读

本指南以 upload/assets/curlytag/AGENTS.md 为核心骨架，面向在 OpenCart 仓库中开发 CurlyTag（OpenCart 官方 Twig 替代模板引擎）的开发者与 AI Agent，系统讲解 Vite+ 统一工具链的全局 CLIvp的完整使用方式：内置命令与 npm 脚本的区分、工具链版本管理、开发前检查清单，并结合 package.json、vite.config.ts 与测试目录结构给出可复现的落地实践。读完本文，你将能独立完成 CurlyTag 的安装、格式检查、测试运行、问题诊断与开发环境搭建。

一、背景：这份 AGENTS.md 服务的是谁

AGENTS.md 是放置在仓库中、专门供开发协作（尤其是 AI Agent）阅读的"项目工作约定"文件。本仓库中这份文件位于upload/assets/curlytag/目录下，服务对象是一个名为 CurlyTag 的浏览器端 JavaScript 模板引擎——它在 OpenCart 中的定位是服务端 Twig 模板引擎的替代方案，其语法基于 Django、Nunjucks、Twig，这一点在 curlytag.js 文件头注释中明确写明：

/* * CurlyTwig * * @description Template engine * * @author Daniel Kerr * * OpenCart Twig replacement. Based on Django, Nunjucks, Twig template syntax. */

从仓库结构可以推断，CurlyTag 作为独立 npm 包（@curlytag/curlytag，见 package.json）被内置到 OpenCart 的upload/assets/目录中，用于前端模板渲染场景，例如 playground/examples/category/template.html 中的商品详情模板：

{% if price %} <li><h2><span class="price-new"><x-currency code="{{ currency }}" amount="{{ price }}"></x-currency></span></h2></li> {% endif %} {% for discount in discounts %} <li>{{ discount.quantity }}{{ text_discount }} <x-currency code="{{ currency }}" amount="{{ discount.price }}"></x-currency></li> {% endfor %}

而这份 AGENTS.md 的职责非常聚焦：告诉开发者和 Agent 如何用 Vite+ 统一工具链来规范化地开发、检查、测试这个项目。它本身不含模板语法教学，而是完整的工程化工作流约定——这正是本文要展开的核心内容。

二、Vite+ 是什么：一套 CLI 收编全部前端工具

AGENTS.md 开门见山地定义了 Vite+ 的定位：

This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI calledvp.

即：Vite+ 是一个构建在 Vite、Rolldown、Vitest、tsdown、Oxlint、Oxfmt、Vite Task 之上的统一工具链，将运行时管理、包管理与前端工具全部收敛到唯一的全局 CLIvp之下。结合 package.json 的 devDependencies（vite-plus: ^0.2.9、@vitest/browser、@vitest/browser-playwright、eslint、playwright等）可以印证：

• Oxfmt负责格式化（配合 ESLint Stylistic 做 JS 风格检查）；
• Oxlint负责代码检查；
• Vitest + Playwright负责跨浏览器（Chromium、Firefox、WebKit）测试；
• Vite Task / vite.config.ts承载自定义任务。

关键区分点（AGENTS.md 原文强调）：Vite+ 不是 Vite。它通过vp dev和vp build间接调用 Vite，因此不要用裸vite命令代替。

文档位置

AGENTS.md 明确说明：Vite+ 的完整文档位于本地node_modules/vite-plus/docs目录，或在线文档站点。在日常开发中，优先查阅本地文档可以避免版本漂移问题。

三、命令总览：先看帮助，再动手

vp help # 打印全部可用命令列表 vp <command> --help # 查看某个具体命令的参数说明

AGENTS.md 建议在不确定命令行为时，先执行上述两条命令获取权威信息。以 package.json 中的实际脚本为参照，vp在本项目中最常用的子命令包括：

四、核心概念：内置命令 vs 脚本（Built-in Commands vs Scripts）

这是整份 AGENTS.md 中最容易踩坑、也最值得深挖的一条规则：

vp <name>runs a built-in command.vp run <name>runs apackage.jsonscript or avite.config.tstask. Scripts cannot overwrite built-ins, sovp devandvp run devmay do different things. Checkpackage.jsonandvite.config.tsfirst, and runvp run <name>when the project defines a script or task with that name.

拆解要点：

1. vp <name>永远执行内置命令：例如vp dev启动的是 Vite+ 内置的 dev 服务器，行为由 Vite+ 内部定义；
2. vp run <name>执行项目自定义脚本/任务：优先查找package.json的scripts字段，其次是vite.config.ts中的任务定义；
3. 脚本不能覆盖内置命令：即使你在package.json里定义了名为dev的脚本，vp dev也不会去执行它——脚本与内置命令同名时，只有vp run dev才会命中你的脚本；
4. 因此vp dev与vp run dev可能是两回事。

以本仓库 package.json 为例，其scripts字段定义了：

"scripts": { "check": "vp check && vp run fmt:js:check", "lint": "vp lint", "fmt": "vp fmt && vp run fmt:js", "fmt:js": "vp exec eslint . --fix", "fmt:js:check": "vp exec eslint .", "test": "vp test", "prepare": "vp config", "release": "changelogen --release" }

注意脚本内部又嵌套了vp check、vp fmt、vp lint等内置命令——这正好体现了"内置命令 + 项目脚本"两层协作的模式：项目脚本负责组合编排，内置命令负责具体执行。

实操建议（原文强调）：在运行任何vp <name>之前，先检查package.json的scripts与vite.config.ts是否定义了同名脚本/任务；若定义了，使用vp run <name>以命中项目约定。

五、工具版本管理：vp toolchain与vp why

AGENTS.md 提供了两条版本诊断命令：

5.1vp toolchain—— 查看工具链版本关系

vp toolchain # 显示当前 Vite+ release 下所有工具的版本与相互关系 vp toolchain vite # 只显示 vite 在工具链图上的版本信息 vp toolchain --global # 忽略本地 vite-plus 包，使用全局安装版本

--global参数特别有用：当本地node_modules中的vite-plus未安装或版本异常时，可以回退查看全局工具链状态。

5.2vp why <package>—— 查看依赖来源

vp why <package> # 显示某个包在包管理器中的依赖图，帮助定位依赖来源

当遇到"某个依赖为什么被安装、被谁引入、为什么是这个版本"这类问题时，vp why比直接翻package-lock.json更直观。

六、Review Checklist：开发前后的标准动作

AGENTS.md 给出了四步强制检查清单，这是每个 PR 提交前必须走完的流程：

- [ ] Run `vp install` after pulling remote changes and before getting started. - [ ] Run `vp check` and `vp test` to format, lint, type check and test changes. - [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`. - [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.

第 1 步：vp install

拉取远端变更后、开始工作前，先执行vp install同步依赖。这与 Vite+ 统一"运行时管理 + 包管理"的定位一致，确保本地环境与锁文件（本仓库使用 npm，packageManager: "npm@11.13.0"）保持一致。

第 2 步：vp check与vp test

• vp check：一键执行格式化检查、lint、类型检查。在本项目中，它对应 package.json 的check脚本编排：vp check && vp run fmt:js:check，即内置检查通过后再用 ESLint Stylistic 校验 JS 风格；
• vp test：运行 Vitest 测试套件。CurlyTag 的测试通过 vite.config.ts 配置为浏览器项目，测试目标覆盖三个内核：

test: { projects: [ { test: { name: 'browser', include: ['../tests/**/*.test.js'], browser: { enabled: true, headless: true, provider: playwright(), instances: [ { browser: 'chromium' }, { browser: 'firefox' }, { browser: 'webkit' }, ], }, }, }, ], },

从tests/目录结构可以看出测试的覆盖面：tests/tags/（if、for、case、capture、cycle、raw 等标签行为）、tests/filters/（数组、字符串、数学、HTML、URL 过滤器）、tests/output/（纯文本与{{ }}变量渲染），以及集成级的 render.test.js 与 add-filter.test.js。

第 3 步：校验脚本/任务

检查是否存在vite.config.ts任务或package.json脚本需要执行，统一用vp run <script>运行。结合第二节的内置命令 vs 脚本规则，这一步是防止"漏跑项目自定义校验"的关键。

第 4 步：vp env doctor

当 setup、运行时或包管理器行为异常时，运行vp env doctor，并把它的输出附在求助信息中。这条约定对 AI Agent 尤为重要——诊断输出是定位环境问题的第一手证据，避免来回猜测。

七、把清单落进真实项目：脚本与配置的逐项对照

为了让上面的清单"可执行"，这里将 AGENTS.md 的规则映射到 CurlyTag 的实际配置上：

7.1 格式化配置（vite.config.ts）

fmt: { tabWidth: 4, singleQuote: true, ignorePatterns: [ '**/*.js', '**/*.md', '**/*.yml', '**/*.yaml', '**/*.json', 'playground/examples/**/template.html', 'tests/fixtures/storefront/format.html', 'docs/.vitepress/cache/**', ], },

• 缩进 4 空格、单引号，与 eslint.config.js 中indent: 4, quotes: 'single'保持一致；
• JS、MD、JSON 等文件被明确排除在 Oxfmt 之外，交给 ESLint Stylistic 处理（对应fmt:js脚本：vp exec eslint . --fix）；
• 示例模板与格式测试夹具被排除，避免格式化破坏教学示例或测试预期输出。

7.2 Lint 规则微调（eslint.config.js）

rules: { eqeqeq: 'off', 'no-with': 'off', },

eqeqeq: 'off'（允许==）与no-with: 'off'（允许with）是模板引擎特有的放宽——模板解析场景需要宽松的比较与作用域处理，这类豁免体现了"工具链服务于项目语义"的取舍。

7.3 提交钩子（staged 任务）

staged: { '*': 'vp check --fix', '**/*.js': 'vp exec eslint --fix', },

vp config（对应prepare脚本）会安装提交钩子，暂存区文件在提交前自动跑vp check --fix，JS 文件再额外过一遍 ESLint 自动修复——这就是 AGENTS.md 强调的"格式化、lint、类型检查、测试"在提交链路中的落地。

八、测试布局与 Playground：开发时的两条主线

8.1 测试组织约定（README 与目录结构双重印证）

README.md 与tests/目录共同确认了测试布局原则——按功能拆分到小文件，禁止膨胀成单体大测试文件：

• tests/output/：纯输出与{{ }}变量渲染测试；
• tests/filters/：过滤器测试，数组过滤器在tests/filters/array/下（compact、groupby、map、uniq、slice、sum 等）；
• tests/tags/：标签行为测试（if、for、case、capture、raw、whitespace-control 等）；
• 顶层render.test.js、add-filter.test.js承担跨功能集成行为测试。

新增过滤器或标签时，应新建/扩展对应目录下的聚焦文件，而不是把用例堆进一个curlytag.test.js。从 for.test.js 可以看到典型用例风格：

test('loop.index starts at 1', () => { expect( curlytag.parse('{% for x in items %}{{ loop.index }}{% endfor %}', { items: ['a', 'b'], }) ).toBe('12'); });

8.2 Playground：交互式开发入口

vp dev

Vite 依据 vite.config.ts 的root: 'playground'从playground/目录伺服页面，其中预置了 category、conditions、filters、loop、nested 等带template.html+data.json配对的示例，方便在编辑器中即时验证模板渲染结果。

8.3 看板模式与测试 UI

vp test --project browser --watch # 文件变更自动重跑 vp test --project browser --ui --watch # 浏览器 UI 交互式探索

注意：--ui必须与--watch搭配使用，否则测试跑完 UI 服务器随即退出（README 明确提示）。

九、完整命令速查表

十、给 Agent 与开发者的三条关键提醒

1. 先查脚本再跑命令：同名的vp dev与vp run dev行为可能不同，脚本永远无法覆盖内置命令——先看package.json与vite.config.ts；
2. 环境问题先自诊：setup、运行时或包管理器行为异常时，先跑vp env doctor，把输出附在提问中，能显著提升问题定位效率；
3. 检查清单是硬性门槛：vp install → vp check + vp test → 校验项目脚本 → vp env doctor四步是每次变更进入提交前的标准动作，直接决定了 CI（对应仓库中的 CI 工作流）能否顺利通过。

附：相关文件索引

• 本文主文档：upload/assets/curlytag/AGENTS.md
• 项目脚本与依赖：upload/assets/curlytag/package.json
• Vite+ 配置（构建/测试/格式化/提交钩子）：upload/assets/curlytag/vite.config.ts
• ESLint Stylistic 风格规则：upload/assets/curlytag/eslint.config.js
• 项目 README（开发工作流与测试布局）：upload/assets/curlytag/README.md
• 模板引擎核心实现（OpenCart Twig 替代）：upload/assets/curlytag/curlytag.js
• 商品详情模板示例：upload/assets/curlytag/playground/examples/category/template.html
• 测试入口（三浏览器矩阵配置见vite.config.ts）：upload/assets/curlytag/tests/tags/for.test.js、upload/assets/curlytag/tests/render.test.js

• 电商
• 后端