LT CLI 参考
注意事项
lt fullstack init不带--noConfirm会导致 Claude Code 永久阻塞 — 交互式提示（项目名称、git init、模板选择）会等待标准输入的输入。Claude Code 无法响应它们，会话会卡在“正在展开…”状态且不消耗 token。从 Claude Code 调用 lt CLI 时，请传递--noConfirm+ 所有必需的标志（--name X --frontend nuxt --git false）。--api-link和--frontend-link创建的是符号链接，而非副本 — 对模板检出（nest-server-starter、nuxt-base-starter）所做的更改（无论它们在此机器上的哪个位置）会立即影响链接的项目。这是框架开发的一个功能，但会让期望副本的开发者感到意外。使用--api-link时，请在项目 README 中记录这一点。lt git reset具有破坏性且不可逆 — 它与安全的lt git get并排在 CLI 菜单中。reset会执行git reset --hard并强制拉取，无需确认即可销毁所有本地更改。切勿在包含未推送工作的分支上运行它。建议使用git stash+lt git get。lt server object X --controller生成 REST，而非 GraphQL — 默认为 REST。对于 GraphQL 项目，请使用--resolver。CLI 不会从现有项目模式中自动检测——您必须明确指定。lt fullstack convert-mode会重写源代码树 — 在npm和vendor模式之间切换会将框架代码移入或移出src/core/（API）或app/core/（App）。此操作是可逆的，但在运行过程中不幂等——始终在开始之前提交，以便可以通过git reset回滚失败的转换。--next是实验性的，与lt server module/object/addProp/test/permissions不兼容 — 当使用lt server create --next或lt fullstack init --next时，API 会从nest-base（Bun + Prisma 7 + Postgres + Better-Auth）克隆，而不是nest-server-starter。下游生成器针对经典的 nest-server 布局（Mongoose 模型、src/server/modules/ 等），无法在 nest-base 项目上工作。仅将其用于全新项目原型；对于生产工作，请使用默认模板。- macOS：过长的
$TMPDIR会导致lt dev up下的 Nuxt SSR 故障 — 在 macOS 上，$TMPDIR是一个较长的每个用户路径（/var/folders/…，通常超过 ~49 个字符）。Nuxt 4.4.7 的 vite-node 会在其下构建一个 Unix 域套接字路径，该路径超过操作系统 104 字符的限制 → SSR 崩溃并返回 500。解决办法：使用短 tmp 目录启动，TMPDIR=/tmp lt dev up。（Linux 的$TMPDIR=/tmp很短，因此此问题仅影响 macOS。） - macOS：HMR WebSocket 端口 24678 在并行的
lt dev项目之间冲突 — 同时运行的两个lt dev项目都尝试绑定 Vite 的 HMR WS 端口 24678。vite.server.hmr.port被 Nuxt 4.4.7 忽略，因此您无法在配置中重新分配它。这非致命——SSR 重新编译仍然有效；只有第二个项目上的实时 HMR 推送会受影响。重新加载页面以在那里获取更改。
技能边界
| 用户意图 | 正确技能 |
|---|---|
| "lt fullstack init" | 本技能 |
| "lt git get feature-branch" | 本技能 |
| "lt server create my-project" | 本技能 |
| "lt server module / object / addProp" | generating-nest-servers |
| "lt server permissions" | generating-nest-servers |
| "创建一个 NestJS 模块" | generating-nest-servers |
| "构建一个 Vue 组件" | developing-lt-frontend |
| "lt deployment create" | 本技能（请参阅 lt deployment create 命令） |
| "部署到 TurboOps / 上线 / turbo 部署 / 部署阶段" | deploying-to-turboops |
执行 lt fullstack init 后：
- 后端工作（projects/api/）→
generating-nest-servers - 前端工作（projects/app/）→
developing-lt-frontend
命令
lt git get — 检出/创建分支
lt git get <branch-name> # 别名：lt git g
- 分支本地存在 → 切换到它
- 分支在远程存在 → 检出并跟踪
- 两者都不存在 → 从当前分支创建新分支
lt git reset — 重置到远程
lt git reset
从远程获取最新内容，将当前分支重置为 origin/<branch>。具有破坏性 — 所有本地更改都会丢失。
lt fullstack init — 创建全栈工作区
# 非交互式
lt fullstack init --name <Name> --frontend <angular|nuxt> --git <true|false> --noConfirm \
[--git-link <URL>] [--api-link <path>] [--frontend-link <path>] [--next]
| 参数 | 必需 | 描述 |
|---|---|---|
--name | 是 | 工作区名称（帕斯卡命名法） |
--frontend | 是 | angular 或 nuxt |
--git | 是 | 初始化 git：true / false |
--noConfirm | 否 | 跳过确认提示 |
--git-link | 否 | Git 仓库 URL |
--api-branch | 否 | nest-server-starter 的分支 |
--frontend-branch | 否 | 前端启动模板的分支 |
--api-copy / --api-link | 否 | 本地 API 模板（复制 / 符号链接） |
--frontend-copy / --frontend-link | 否 | 本地前端模板（复制 / 符号链接） |
--next | 否 | 实验性 — 克隆 nest-base（Bun + Prisma 7 + Postgres + Better-Auth）用于 API。强制 apiMode = Rest、frameworkMode = npm，并跳过工作区安装（为 app 手动运行 pnpm install，为 api 手动运行 bun install）。下游的 lt server module/object/addProp/test 与生成的布局不兼容。 |
优先级： --*-link > --*-copy > --*-branch > 默认（GitHub 克隆）
创建的结构：
<workspace>/
├── projects/
│ ├── api/ ← nest-server-starter（或带 --next 的 nest-base）
│ └── app/ ← nuxt-base-starter（或 ng-base-starter）
├── package.json
└── .gitignore
创建后：
cd <workspace> && pnpm install
lt dev init # 幂等：环境变量补丁 + 注册；如果机器尚未设置，则会自动先运行 `lt dev install`
lt dev up # 在 Caddy 后面启动 API + App，地址为 https://<slug>.localhost
# 使用 --next：按子项目安装，无需工作区安装
cd <workspace>/projects/app && pnpm install
cd <workspace>/projects/api && bun install
（如果未使用 lt dev，则回退到在默认端口 3000/3001 上使用 pnpm -r --parallel run start。）
lt dev — 并行项目编排（Caddy + HTTPS）
通过 Caddy 将每个 lt 项目置于稳定的 HTTPS URL（<slug>.localhost、api.<slug>.localhost）下提供服务，以便多个项目可以并排运行而不会在 3000/3001 上冲突，也不会出现身份验证交叉问题。在每个 lt-monorepo 或独立的 API/App 项目中都使用此命令。
lt dev install # 每台机器一次：引导专用的 LaunchAgent/systemd 单元 + Caddyfile 存根 + CA 提醒
lt dev uninstall [--purge] # 移除 lt-dev 服务（--purge 还会删除 Caddyfile + 日志）
lt dev init # 每个项目一次（幂等）：环境变量补丁 + 注册
lt dev up # 在 Caddy 后面启动 API + App
lt dev down # 停止进程 + 移除 Caddy 块（也会拆除任何隔离的测试堆栈）
lt dev test # 隔离的 Playwright E2E：并行堆栈 + 专用的 `<slug>-test` 数据库，自动拆除
lt dev test --shard # 跨 2 个隔离堆栈分片（默认 — 稳定的最佳点）
lt dev test --shard 3 # 跨 N 个隔离堆栈分片（每个都有自己的端口/Caddy/数据库 `<slug>-test-<i>`）
lt dev test --shard auto # 根据此机器的 CPU + RAM 确定 N 的大小（保守）
lt dev test down # 拆除隔离的测试堆栈（无残留）
lt dev status # 显示此项目的 URL + PID + 实时上游状态（包括任何测试堆栈）
lt dev status --all # 列出每个已注册的项目 + 运行状态
lt dev doctor # 诊断 Caddy / CA / DNS / 端口问题
lt dev tunnel [--api] # 前台 Cloudflare 快速隧道：公共 *.trycloudflare.com URL
每个子命令的功能：
install— 每台机器一次。验证caddy是否在 PATH 中（如果缺少则建议brew install caddy），创建~/.lenneTech/Caddyfile存根，编写并引导专用的 LaunchAgent（macOS，~/Library/LaunchAgents/tech.lenne.lt-dev-caddy.plist）或 systemd-user 单元（Linux）。最多等待 8 秒让 Caddy 管理端点（:2019）响应，验证文件，并提醒您运行sudo -E HOME="$HOME" caddy trust（-E HOME="$HOME"是必需的——没有它，sudo 会将 HOME 切换到/var/root，CA 安装将静默失败）。不使用brew services start caddy— 其 plist 硬编码了--config /opt/homebrew/etc/Caddyfile并且会针对我们的 Caddyfile 位置崩溃循环。自动链接： 当在未初始化的 lt-dev 项目内运行时，会在此之后运行init（使用--skip-init选择退出）。uninstall—install的对称对应项。移除 LaunchAgent / systemd 单元，删除单元文件。使用--purge还会删除~/.lenneTech/Caddyfile和 caddy 日志。不会移除 caddy 二进制文件本身（如果需要，请使用brew uninstall caddy）。init（别名migrate）— 幂等。构建项目标识（slug =package.json"name"，来自 monorepo 布局的子域名），修补遗留的硬编码port: 3000/port: 3001/ Vite-proxy 目标 / Playwright URL 为环境感知变体（保留默认值），持久化到~/.lenneTech/projects.json，将“本地开发 (lt dev)”URL 块注入所有CLAUDE.md文件，将.lt-dev/添加到.gitignore。自动链接： 当机器尚未准备好时，会先运行install（使用--skip-install选择退出）。up— 分配内部上游端口（4000+，绝不是 3000/3001），创建或更新使用reverse_proxy 127.0.0.1:<port>的 Caddy 块 + 重新加载，导出PORT、HOST=127.0.0.1/NITRO_HOST=127.0.0.1（将开发服务器固定到 IPv4 以使上游明确）、BASE_URL、APP_URL、NUXT_API_URL、NUXT_PUBLIC_API_URL、NUXT_PUBLIC_SITE_URL、NUXT_PUBLIC_STORAGE_PREFIX、NUXT_PUBLIC_API_PROXY=false、API 的数据库（MongoDB：NSC__MONGOOSE__URI；PostgreSQL / MySQL / MariaDB，从 lt CLI 1.54.0 开始：NSC__DATABASE__URL和NSC__DATABASE__OWNER_URL，仅用于 API，位于其自己的堆栈数据库中，首次启动时会以拥有者角色创建该数据库，因此拥有者需要具有CREATEDB（对于 PostgreSQL）或CREATE+GRANT OPTION（对于 MySQL / MariaDB）；无凭据记录在~/.lenneTech/projects.json的dbUrls下）、NODE_EXTRA_CA_CERTS（Caddy 根 CA，以便 Nuxt SSR 获取信任的 HTTPS），以及用于早于NUXT_*约定的项目的旧别名API_URL/SITE_URL。然后分离地生成pnpm start（api）+pnpm dev（app）。预检检查会在 Caddy 缺失、Caddy 守护进程关闭、现有会话存活或内部端口已被绑定时拒绝启动。日志位于<root>/.lt-dev/{api,app}.log。down— 向已保存的进程组（负 PID）发送 SIGTERM，以便子进程（Vite、Nest 观察者等）也能接收到。移除项目的 Caddy 块 + 重新加载。还会为此项目拆除任何隔离的测试堆栈（lt dev test）。test— 隔离的 E2E。启动第二个并行堆栈（<slug>-test.localhost/api.<slug>-test.localhost，自己的端口 + Caddy 块 +.lt-dev/.env.test桥接），连接到专用的<slug>-test数据库（与开发用的<slug>-local和 API 测试用的<slug>-e2e分开），运行 Playwright 套件（全局设置会在第一个测试之前重置该数据库一次），然后自动无残留地拆除。与开发会话并行运行，且绝不干扰它。--keep使其保持运行；lt dev test down停止它；--api改为运行（已隔离的）API 测试；--debug= PWDEBUG+headed；-- <args>转发给 Playwright。--shard N在 N 个完全隔离的堆栈上并行运行拆分后的套件（每个都有自己的端口 + Caddy 块 + 数据库<slug>-test-<i>）+ N 个--shard=i/NPlaywright 进程——本地 CI 奇偶校验矩阵。裸的--shard默认为 2（稳定的最佳点：N≥3 会过度订阅典型开发机器上的性能核心 → 不稳定）；--shard auto根据 CPU+RAM 确定 N 的大小（保守）。本地分片共享一台机器（不同于 CI 的每个分片容器），因此 CLI 会为项目的 playwright.config 导出LT_DEV_TEST_SHARDS，以便仅在该负载下放宽超时（CI 保持快速）。lt dev test down回收所有分片。需要提供此隔离会话的 lt CLI 版本。status/status --all— 当前项目：子域名 → 上游端口、数据库 URI、会话 PID（存活/死亡）、实时的lsof上游状态。--all：每个注册的项目都带有一个●/○指示符。doctor— Caddy 是否在 PATH 中、lt-dev LaunchAgent / systemd 单元是否已加载、守护进程是否在运行、Caddyfile 是否有效、端口 80/443 是否空闲或被 Caddy 占用、*.localhost是否解析（IPv4 或 IPv6 回环）、注册表状态。tunnel— 前台 Cloudflare 快速隧道：cloudflared tunnel --url https://<slug>.localhost --http-host-header <slug>.localhost --no-tls-verify。打印一个公共的*.trycloudflare.comURL（5-10 秒）并运行直至按 Ctrl-C。默认暴露 App；--api切换目标。localhost 域上的身份验证 cookie 在隧道 URL 上无效——将隧道 URL 添加到 Better-Auth 的trustedOrigins以使登录流程成功。并行启动第二个lt dev tunnel --api以供完整的外部使用。
通过 LT_PNPM_BIN 覆盖生成二进制文件（例如，用于基于 bun 的项目的包装脚本）。
lt ticket — 并行票证开发环境
同时处理一个项目的多个票证/功能——每个都在其自己的 git worktree + 其自己隔离的 lt dev 堆栈（自己的 URL、端口、Caddy 块、空数据库）中——因此多个票证可以在没有交叉影响的情况下并行进行浏览器测试和 E2E 测试。
lt ticket start DEV-2200 # worktree（分支 feat/DEV-2200 来自 origin/dev）+ pnpm install + lt dev up
…
[为了翻译截断]