CLI 参考

组合 Lenso 应用、启动已连接的本地环境与读取状态的当前公开命令。

lenso CLI 负责应用组合、本地 System 物化、Module 与 Service 脚手架，以及独立 Console 安装。公开应用生命周期是 Compose → Run locally → Connect → Status。

安装

安装任一提供 lenso 命令的包：

cargo install lenso-cli
# 或
npm install -g @lenso/cli

lenso --version
lenso --help

Compose（组合）

生成精确产品蓝图：

lenso app compose ./support-desk --blueprint support-desk --apply

--apply 是原子写入生成态 lenso.app.json 的 Flag，并非独立应用管理阶段。 Bare Support Desk Blueprint 只选择 auth、notification-worker 与 support-api。

为兼容性保留的 Blueprint 浏览命令已从公开 Help 隐藏。当前自动化与文档应通过 lenso app compose 的显式 --blueprint 输入选择 Blueprint。

产品验收使用仓库内的 Capability Pack。请从 lenso-examples 仓库根目录运行以下精确命令：

lenso app compose ./support-desk \
  --blueprint support-desk \
  --pack ./fixtures/acceptance/support-desk/capability \
  --implementation support-api=linked \
  --implementation notification-worker=linked \
  --implementation lenso/platform-story=linked \
  --apply

Capability Pack 提供 support/tickets Service Delivery 与 lenso/platform-story；Implementation Flag 明确本地 Binding。由于 support/tickets 是 Service-backed，验收 Runner 随后使用 lenso service workspace init --force 与 lenso service workspace add support-ticket 注册 Provider 的 lenso.service.json。缺少该 Workspace Entry 时不要启动 Pack-backed 组合；完整受支持路径请使用 pnpm acceptance:support-desk。

Run locally（本地运行）

从已组合 Host 目录启动生成的 Host、auto-start Provider Service 与已连接的本地 Console：

cd ./support-desk
lenso dev up --console-root ../lenso-console

首次运行会安全提示输入本地 Operator 密码。自动化可通过 --operator-password-file 使用私有普通文件。该命令启动并迁移 Host 与 Console Store，构建 Console，配置或复用持久 Operator，协调 Module-owned Artifact，连接精确拓扑，并保持前台运行。按 Ctrl-C 只停止本次调用启动的进程。

该命令已经发布，适用于已经组合的 Host 与现有 Console checkout。更广泛的空目录浏览器验收仍由 Lenso issue #540 跟踪。

只有明确需要更底层 System Sandbox 与 Local Control Adapter 时，才使用 lenso system dev：

lenso system dev --system-file ./support-desk/lenso.app.json --dry-run --json
lenso system dev --system-file ./support-desk/lenso.app.json
lenso system dev --system-file ./support-desk/lenso.app.json --cleanup

Sandbox 不会启动已组合的 Host 或 Console，也不会连接 Console。在 App Composition 模式下，它会在限定范围的 Sandbox Run 中启动所选的 Service-backed Provider Workload 与 Local Control Adapter。

Connect（连接）

lenso dev up --console-root 创建只限 loopback 的已签名 Enrollment Receipt 与 .lenso/console-connect.json，并在报告本地 System ready 前应用该 Bundle。

如需应用单独准备的本地 Bundle，公开幂等连接入口是：

LENSO_CONSOLE_TOKEN='<operator-session-token>' \
  lenso console connect \
  --console-url http://127.0.0.1:3030 \
  --bundle .lenso/console-connect.json

非交互运行请通过 --token-file 使用私有普通文件。 lenso.console-connect.v1 Bundle 包含已签名 Enrollment Receipt、可选的精确 Console Composition Artifact Effect，以及摘要绑定的 System Connection Request。本地 Enrollment Path 只接受 loopback HTTP Target。CLI 自有 Local Control Adapter 不使用业务 Enrollment；其余每个拓扑 Service 都需要 active signed Enrollment。

Status（状态）

通过 Console 或以下 API 读取已连接 System：

GET /api/console/v1/system
permission: console.system.read

System、Service、Module、Surface 与 Adapter Projection 报告 connected、unavailable、incompatible 或 unmanaged，并给出直接原因。 Workload Operational State 独立报告，例如 running、suspended 或 unknown。Adapter 不可用时，Workload Observation 为 unknown，变更会被拒绝且不会排队。

Module 创作

lenso module create billing --with-console-ui --dry-run
lenso module create billing --with-console-ui
lenso module dev --console-ui

脚手架接收 billing 这类非限定本地 slug。产品 Module 无论 Linked 到 Host 还是由 Service 交付，都保留其完全限定业务身份；Support Desk 验收中的身份是 support/tickets。Console UI 是同一 Module Release 中回执绑定的 console_ui_esm Artifact。业务操作始终是 typed Business API Operation，而非通用管理通道。

参见 Module 创作与 Module Console UI。

Provider Workspace

从 Host checkout 创建 TypeScript Provider 脚手架：

lenso service create billing-provider --lang ts --output-dir services --dry-run
lenso service create billing-provider --lang ts --output-dir services
lenso service workspace check --workspace-file lenso.workspace.json --json

除非传入 --no-workspace，创建命令还会把生成的 Service 注册到 lenso.workspace.json。生成的 TypeScript 项目公开当前精确 Provider Runtime：

cd services/billing-provider
pnpm install
pnpm check
pnpm module:release > lenso.module-release.json
pnpm start

在另一个终端中，通过 Provider Endpoint 把该精确 Module Release 安装到 Host Runtime Input：

lenso module install \
  ./services/billing-provider/lenso.module-release.json \
  --base-url http://127.0.0.1:4100/lenso/provider/v1 \
  --repo-root .

三个合约的职责不同：

lenso.service.v1 是 Service 打包、本地进程启动与旧 Discovery Consumer 使用的兼容性 Metadata。
lenso.module-release.v1 是精确 Module 安装目标，绑定 Manifest、Delivery、 Contract 与可选 Console Artifact Digest。
/lenso/provider/v1 上的 lenso.provider.v1 是锁定的 Descriptor，以及 Host-to-Provider Invocation、Recovery 与 Acknowledgement 边界。

激活 Provider Export 前，Host 会校验 Service Release、Module Release、Manifest、 Export 与 Contract Digest。Provider Runtime 仍由 Host 持有，支持 Rust 与 TypeScript。Autonomous Service 使用 Rust lenso.service.v2，持有自己的运行时与存储；参见 Service Capability Tiers。 TypeScript 尚未提供 Autonomous Service 能力对等。

Console Operator Bootstrap

已安装 Console 不含默认凭据。从外部安装权限引导首个 Operator：

lenso console operator bootstrap \
  --console-root ../lenso-console \
  --console-url http://127.0.0.1:3030 \
  --identifier admin@example.com

交互终端输入密码时不会回显。自动化必须使用 --password-stdin，或通过 --password-file 读取私有普通文件。

产品级验收

在已准备的 lenso-examples checkout 中运行：

pnpm acceptance:support-desk

这是产品级黑盒入口。同级 checkout、PostgreSQL 与浏览器前置条件参见示例。

所有权边界

lenso.app.json 是精确应用组合与锁。
lenso dev up 只持有本次已连接本地开发所启动的进程与连接记录；按 Ctrl-C 只停止本次调用启动的进程。
lenso system dev 只持有更底层的 Sandbox Run 与 Local Control Adapter。
Console 连接并报告精确拓扑；它不会创建或协调生产对象。
生产交付仍由 Repository、Platform 与 Operator 持有。