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

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

## 安装

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

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

lenso --version
lenso --help
```

## Compose（组合）

生成精确产品蓝图：

```sh
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` 仓库根目录运行
以下精确命令：

```sh
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：

```sh
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](https://github.com/LioRael/lenso/issues/540)
跟踪。

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

```sh
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，公开幂等连接入口是：

```sh
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：

```text
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 创作

```sh
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 创作](/docs/zh/module-authoring)与
[Module Console UI](/docs/zh/console-packages)。

## Provider Workspace

从 Host checkout 创建 TypeScript Provider 脚手架：

```sh
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：

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

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

```sh
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](/docs/zh/autonomous-services)。
TypeScript 尚未提供 Autonomous Service 能力对等。

## Console Operator Bootstrap

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

```sh
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 中运行：

```sh
pnpm acceptance:support-desk
```

这是产品级黑盒入口。同级 checkout、PostgreSQL 与浏览器前置条件参见
[示例](/docs/zh/examples)。

## 所有权边界

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