mirror of
https://gitee.com/newgateway/vtj.git
synced 2026-09-08 15:47:51 +08:00
5f3290faec
- 介绍 VTJ.PRO 项目结构及核心技术栈 - 规范跨包依赖管理和引用方式 - 明确环境配置及依赖安装流程 - 列出常用开发和构建命令及使用建议 - 规定代码风格和类型使用规范 - 说明测试策略和验收流程 - 强调生成物管理及高风险命令禁止范围 - 规范提交与发布流程，阐述提交信息规范与要求
88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件适用于整个仓库。若子目录以后增加了更具体的 `AGENTS.md`，以距离目标文件最近的说明为准。
|
||
|
||
## 项目概览
|
||
|
||
VTJ.PRO 是基于 Vue 3、TypeScript 和 Vite 的 AI 低代码引擎，核心能力包括 DSL 与 Vue SFC 双向转换、设计器、渲染器和多端应用输出。本仓库是 pnpm workspace，由 Nx 驱动 Lerna 处理包间依赖和批量任务。
|
||
|
||
- `packages/`：可发布的基础库、核心模型、解析/生成、渲染、设计器、UI 等 `@vtj/*` 包。
|
||
- `platforms/`：Web、H5、UniApp 及 PRO 平台集成包。
|
||
- `apps/`：应用、H5、UniApp、插件、物料等示例或交付工程。
|
||
- `dev/`：主要的本地联调入口。
|
||
- `create-vtj/`：项目脚手架及模板。
|
||
- `docs/`：VitePress 文档站和项目文档。
|
||
- `scripts/`：仓库维护、同步和发布辅助脚本。
|
||
|
||
优先在已有包和既有模式中完成修改，不新增重复工具、抽象层或依赖。跨包引用使用包名和已有公开导出，不要通过相对路径穿透其他包的 `src`。
|
||
|
||
## 环境与依赖
|
||
|
||
- Node.js 必须为 20 或更高版本。
|
||
- 使用仓库声明的 pnpm；不要生成或提交 `package-lock.json`、`yarn.lock`。
|
||
- 首次安装可运行 `pnpm run setup`；依赖已就绪时不要重复安装。
|
||
- 新增内部依赖使用 `workspace:~` 或目标包已有的 workspace 范围，并同步更新对应 `package.json`。
|
||
- 只有需求确实需要时才修改依赖；修改依赖后更新 `pnpm-lock.yaml`。
|
||
|
||
## 开发命令
|
||
|
||
从仓库根目录运行：
|
||
|
||
```sh
|
||
pnpm run dev # dev/ Web 联调环境
|
||
pnpm run dev:uni # dev/ UniApp 联调环境
|
||
pnpm run app:dev # apps/app
|
||
pnpm run docs:dev # 文档站
|
||
pnpm run build # 构建所有非 private 包，耗时较长
|
||
pnpm run test # 测试所有非 private 包
|
||
pnpm run test:all # 包含 private workspace 的完整测试
|
||
```
|
||
|
||
日常修改优先做定向验证，避免无必要地运行全仓任务：
|
||
|
||
```sh
|
||
pnpm --filter @vtj/core test
|
||
pnpm --filter @vtj/designer exec vitest run tests/useOpenApi.test.ts
|
||
pnpm --filter @vtj/parser build
|
||
pnpm --filter vtj-plugin test
|
||
```
|
||
|
||
包名以对应目录的 `package.json#name` 为准。根目录没有统一的 lint 脚本，不要声称执行过 lint；可使用现有 Prettier 配置检查或格式化本次改动文件。
|
||
|
||
## 代码约定
|
||
|
||
- 遵循 `.editorconfig` 和 `.prettierrc`：2 空格、单引号、分号、LF、80 列、无尾随逗号。
|
||
- TypeScript 保持类型明确，优先复用仓库已有类型；避免 `any`、无必要的类型断言和重复协议定义。
|
||
- Vue 组件沿用相邻文件结构和命名；当前代码通常使用 Vue 3 Composition API 与 TypeScript。
|
||
- 可复用公共能力放在所属包内，并从该包的 `src/index.ts` 或既有分层入口导出；不要为了单一调用创建公共抽象。
|
||
- 保持 workspace 依赖方向与对应 `package.json` 一致。新增跨包 import 时，确认已声明依赖。
|
||
- 用户可见文案保持现有语言和术语；不要顺手大范围改写无关文案或格式。
|
||
- 不做无关重构，不覆盖工作区中已有的用户修改。
|
||
|
||
## 测试与验收
|
||
|
||
- 测试使用 Vitest，通常位于各 workspace 的 `tests/` 下，文件名沿用 `.test.ts` 或 `.spec.ts`。
|
||
- 修改行为或修复缺陷时，在所属包添加或更新最小回归测试，优先覆盖根因和边界条件。
|
||
- Vue/DOM 测试沿用对应包的 Vitest 配置和现有 `tests/setup.ts`，不要另建测试框架。
|
||
- 至少运行受影响包的定向测试；涉及公开导出、类型、构建配置或跨包依赖时，再运行受影响包的 `build`。
|
||
- 跨多个基础包的改动应按需运行 `pnpm run test` 和 `pnpm run build`。若因耗时或环境限制未运行，交付时明确说明。
|
||
- 报告验证结果时列出实际执行的命令和失败原因，不把既有失败描述为本次修改已通过。
|
||
|
||
## 生成物与高风险命令
|
||
|
||
不要手工修改或提交构建/缓存产物，包括 `node_modules/`、`dist/`、`types/`、`temp/`、`coverage/`、`.nx/`、`docs/dist/` 及忽略规则中列出的生成目录。
|
||
|
||
`CHANGELOG.md`、各包 `src/version.ts` 和发布版本通常由 Lerna 发布流程维护；除非任务明确要求发布或改版本，否则不要修改。不要自行运行以下会清理、批量改写、提交、推送或发布的脚本：
|
||
|
||
- `clean`、`reset`、`update`、`sync`
|
||
- `ci`、`commit`
|
||
- `prerelease`、`patch`、`minor`、`publish`
|
||
|
||
不要提交密钥、令牌、私有服务地址或本地环境文件。涉及网络、文件写入、代码执行和 AI 工具调用时，保留现有校验、错误处理与审批边界。
|
||
|
||
## 提交与交付
|
||
|
||
- 除非用户明确要求，不创建提交、不推送、不发布。
|
||
- 提交信息遵循 Conventional Commits，例如 `fix(parser): 修复数据源解析`、`feat(agent): 支持附件预览`。
|
||
- 最终交付说明应包含：修改内容、影响范围、已执行的验证、未验证项或已知风险。
|