Tapcart Project 是针对 Tapcart CLI 项目的项目级操作技能。所有命令都在 Tapcart 项目目录的根目录下运行，除非另有说明，由 agent 直接执行全部命令。
首次设置 按顺序走完以下步骤，帮助用户从零到拥有可用的本地环境。
第 1 步——检查 Node.js 运行 node --version。要求 Node 23 或更高版本。若缺失或版本过低，告知用户从 https://nodejs.org 安装（最新 LTS，≥ 23）。Node.js 是一次性的系统前置条件，等待用户确认已安装后再继续。
第 2 步——全局安装 Tapcart CLI npm install -g @tapcart/tapcart-cli 验证安装：tapcart --version
第 3 步——获取 App ID 向用户索取 Tapcart App ID，可在 https://app.tapcart.com/settings 的 Tapcart CLI API Key 区域找到。
第 4 步——创建项目（若已存在则跳过） 检查当前目录是否已有 tapcart.config.json。若有，跳到第 5 步。若无，创建项目： npm init @tapcart/tapcart-app@latest -- -a <app-id> -f <folder-name> cd <folder-name> npm install
第 5 步——认证 运行 tapcart auth login，该命令会自动打开浏览器窗口，并阻塞直到用户完成 OAuth 登录。命令退出即表示认证完成，继续下一步。
第 6 步——拉取已有的 blocks 和 components tapcart block pull -a tapcart component pull -a 至此项目准备就绪。
认证 登录：tapcart auth login（自动打开浏览器，阻塞直到完成）；登出：tapcart auth logout。凭据存储在本地，跨会话保留。
依赖 依赖是可在 blocks 内导入的 npm 包。依赖必须先添加到本地并推送到远程应用配置，才能在仪表盘或移动应用中使用。命令包括：tapcart dependency add lodash 4.17.21（添加）、tapcart dependency remove lodash（移除）、tapcart dependency list（列出本地依赖）、tapcart dependency pull（从远程应用配置拉取）、tapcart dependency push（将本地依赖列表推送到远程应用配置）。添加依赖后，提醒用户把包名加入相关 block 的 config.json 中的 "dependencies": []，然后运行 tapcart dependency push。
Lint 运行 lint 并向用户展示输出：tapcart lint --all（检查所有 blocks 和 components）、tapcart lint -b MyBlock -b AnotherBlock（指定 blocks）、tapcart lint -c ProductCard（指定 components）、tapcart lint --all --fix 或 tapcart lint -b MyBlock --fix（自动修复并写入磁盘）。展示 lint 输出，并在使用 --fix 前获得确认。
日志 tapcart log
布局开发服务器 在后台运行布局开发服务器并告知用户它正在运行，保持运行直到用户要求停止。命令形式包括：tapcart layout dev（若未提供布局类型会交互式询问）、tapcart layout dev -l home（指定布局类型）、tapcart layout dev -l home -v <layoutId>（指定布局类型和特定布局 ID）、tapcart layout dev -l home -b MyBlock -b AnotherBlock（用本地版本覆盖指定 blocks）、tapcart layout dev -l home -a（用本地版本覆盖所有 blocks）、tapcart layout dev -l home -p 4995（自定义端口，默认 4995）。默认情况下，开发服务器使用仪表盘线上版本渲染 blocks；用 -b <BlockFolderName> 改用本地 block，或用 -a 使用全部本地 block。用户要求停止时终止该进程。