tiny-vue: Instructions file for Codex

AGENTS.md

面向 AI 编码代理（Copilot、Cursor、Aider、Claude Code 等）的项目指南。 这是一份机器可读的文档，帮助 AI 助手理解本仓库的结构、规范和约束。

项目概述

TinyVue 是 OpenTiny 开源生态的核心组件库，具备以下特征：

• 同时支持 Vue 2.6 / Vue 2.7 / Vue 3（通过分包发布，一套源码跨框架复用）
• 支持 PC 端与移动端两种终端形态
• 采用 Renderless（无渲染层） 与 视图层分离架构：业务逻辑写在 packages/renderless，视图写在 packages/vue
• 支持主题切换：Aurora / SAAS 主题，样式代码在 packages/theme 与 packages/theme-saas
• Monorepo 结构，使用 pnpm Workspaces 管理

关键目录结构

tiny-vue/
├── packages/
│   ├── vue/              # Vue 组件视图层（.vue 文件）
│   ├── renderless/       # 无渲染逻辑层（纯 JS/TS，框架无关）
│   ├── vue-common/       # 跨框架公共适配层
│   ├── vue-hooks/        # 自定义 Vue Hooks
│   ├── vue-locale/       # 国际化
│   ├── vue-icon/         # 图标组件
│   ├── utils/            # 通用工具函数
│   ├── theme/            # Aurora 主题（Less）
│   └── theme-saas/       # SAAS 主题（Less）
├── examples/
│   ├── vue3/             # Vue 3 开发示例与单元/E2E 测试
│   ├── vue2/             # Vue 2 开发示例
│   └── sites/            # 官方文档站点
├── internals/
│   └── cli/              # 构建脚本与 CLI 工具
└── .github/              # CI/CD 工作流配置

环境要求

工具	版本要求
Node	>= 18
pnpm	>= 9.5（必须，禁止使用 npm 或 yarn）

核心命令

# 安装依赖（只能用 pnpm）
pnpm i

# 启动 Vue 3 开发示例（默认）
pnpm dev          # → http://127.0.0.1:7130/

# 启动 Vue 2 开发示例
pnpm dev2

# 运行单元测试
pnpm test:unit    # Vue 3
pnpm test:unit2   # Vue 2

# 运行 E2E 测试
pnpm test:e2e     # Vue 3（Chromium）
pnpm test:e2e2    # Vue 2（Chromium）

# 格式化代码
pnpm format

# ESLint 检查与修复
pnpm lint

# 构建组件库
pnpm build:ui

架构约定

Renderless 模式（重要）

TinyVue 使用 Renderless 无渲染架构。修改或新增组件时，必须遵守：

• 业务逻辑 → 写在 packages/renderless/<component-name>/index.ts，不依赖任何 UI 框架
• 视图模板 → 写在 packages/vue/<component-name>/index.vue，通过 setup 调用 renderless 层
• 不得在 .vue 文件中直接写业务逻辑（data 处理、状态计算等）

跨版本兼容

• 一份 renderless 逻辑同时服务 Vue 2 和 Vue 3
• 若需判断框架版本，使用 packages/vue-common 中的适配工具，不要直接写 if (vue3)
• 不得在 renderless 层导入任何 Vue 特定 API（ref、reactive 等）