故障排除
诊断当前 Compose、Run locally、Connect 与 Status 生命周期。
请分开检查每个生命周期边界。有效组合不代表进程正在运行；进程正在运行也不 代表 Console 已连接对象。
首轮检查
test -f ./support-desk/lenso.app.json
cd ./support-desk
lenso system dev --system-file ./lenso.app.json --dry-run --json
curl -sS http://127.0.0.1:3030/api/console/v1/systemConsole 请求还需要具备 console.system.read 的已认证 Actor。
常见症状
| 症状 | 检查 | 处理 |
|---|---|---|
缺少 lenso.app.json |
Compose 输出目录与 Source Pack 路径 | 从持有该 Pack 的目录重新运行 Compose 命令。 |
| 已连接本地启动失败 | lenso dev up --console-root ... 报告的第一个失败阶段 |
修复对应的 Host、Provider、Store、Console、Artifact 或 Connection 阶段后再重试。 |
| 业务 Service 无法 Enrollment | .lenso/console-connect.json 中的 Signed Receipt、Allowlist Key 与 loopback baseUrl |
修正 Service 身份或合约；不得绕过 Signed Enrollment。 |
| Connect 拒绝业务 Service | Active Signed Enrollment 与发布的 Core Contract | 使用 lenso console connect 重新应用精确 Bundle；不要手工编辑 Receipt。 |
| Connect 拒绝拓扑 | Bundle 中的 Topology SHA-256 Digest 与 Management Binding | 从已组合应用重新生成 Bundle；不要在旧 Digest 下提交另一份拓扑。 |
| Local Control Adapter 看似未 Enrollment | Adapter ID 与 Binding | 使用 lenso-local-control-adapter 和 workload-control:<system>；该 CLI 自有 Adapter 不使用业务 Enrollment。 |
| 缺少 Module Surface | Module Release、UI Artifact、Contract 与 Surface Grant 摘要 | 重新连接回执已绑定所有身份的精确应用。 |
Adapter Connection 为 unavailable |
Local Control Adapter 进程与 Target-owned Status Endpoint | 重启本地运行；Workload Observation 保持 unknown，变更不会排队。 |
对象为 incompatible |
Reason 中的 Protocol、Schema、Capability 与 Artifact 细节 | 对齐声明的合约，并以相同身份重新连接。 |
对象为 unmanaged |
Observed 或 Enrolled 对象是否属于当前拓扑与 Management Binding | 将其放入有意的新组合，或保持在当前已连接 System 之外。 |
| 产品验收找不到仓库 | 同级 Checkout 名称或 Root Override 变量 | 提供 LENSO_FRAMEWORK_ROOT、LENSO_CLI_ROOT 与 LENSO_CONSOLE_ROOT。 |
| 产品验收无法启动 PostgreSQL | PATH 中的 initdb、postgres 与 pg_isready |
安装本地 PostgreSQL Binary，或提供数据库名包含 acceptance 的 disposable LENSO_ACCEPTANCE_DATABASE_URL。 |
| 浏览器验收无法启动 | Headless Chrome 兼容浏览器与已安装依赖 | 运行 pnpm install --frozen-lockfile，再重试显式验收命令。 |
Compose（组合）
Bare Support Desk Blueprint 包含 auth、notification-worker 与
support-api：
lenso app compose ./support-desk --blueprint support-desk --applySupport Ticket 与 Story Module 来自验收 Capability Pack，而非 Bare
Blueprint。完整产品命令必须从 lenso-examples 仓库根目录运行，参见
产品蓝图。
Source Pack 使用相对路径时，当前目录会影响 CLI 解析结果。--apply 原子写入
生成组合。请检查 support-desk/lenso.app.json，不要手工编辑。
Run locally（本地运行）
从已组合 Host 目录启动已连接本地路径：
cd ./support-desk
lenso dev up --console-root ../lenso-console该命令保持在前台，并报告失败的精确 Host、Provider、Store、Console、Artifact 或 Connection 阶段。Ctrl-C 只停止本次调用启动的进程。
只有需要把 Composition 与 Adapter 校验和已连接 Host、Provider、Console 路径 隔离时，才使用 System Sandbox Dry Run：
lenso system dev --system-file ./lenso.app.json --dry-run --json若上一次 Sandbox Run 仍持有 Adapter Socket 或进程，使用其限定范围的 Cleanup 入口：
lenso system dev --system-file ./lenso.app.json --cleanupCleanup 只针对该次本地运行记录的资源。
Connect（连接）
lenso dev up --console-root 会在报告 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 使用权限受限的普通文件。不要编辑 Bundle；
Identity、Release、Artifact、Topology 或 Binding 变化时，应从已组合应用重新生成。
CLI 先把每份 Signed Receipt 提交到底层 Enrollment Boundary，再应用由 Digest 绑定的 System Connection：
POST /api/console/v1/enrollment-receipts
POST /api/console/v1/system/connectConsole 使用 Server-only Allowlist 校验双方签名。本地 baseUrl 必须是
loopback HTTP。System Request 必须包含精确 lenso.system.v2 拓扑、其 SHA-256
摘要，以及同一 System 的 Management Binding；不存在可以替代该路径的无签名
Registry Write。
Status（状态）
GET /api/console/v1/systemConnection State 与 Workload Operational State 是不同维度：
| 维度 | 对象 | 值 |
|---|---|---|
| Connection Projection | System、Service、Module、Surface、Adapter | connected、unavailable、incompatible、unmanaged |
| Workload Operation | Workload Observation | Target-owned State，例如 running、suspended、stopped、unknown |
unmanaged 描述当前拓扑与 Management Binding 之外的 Observed 或 Enrolled
对象。拓扑已声明的业务 Service 若没有 Active Enrollment，就无法连接。
Local Control Adapter 不可用时，Workload Operational State 为 unknown。
Console 会立即拒绝 Control Request，不排队、不改道，也不根据进程状态推断结果。
Surface 可打开但业务数据失败
浏览器必须通过 Surface Gateway 调用生成客户端。确认已连接回执绑定了精确
Module Identity、Module Release Digest、console_ui_esm Artifact Digest、
Business API Contract Digest 与允许的 Operation ID。
Service Credential 留在 Console Service。不要把凭据放入浏览器，也不要让 Surface 直接调用业务 Service。
产品级验收
显式运行完整黑盒入口：
pnpm acceptance:support-deskRunner 默认把 lenso、lenso-cli 与 lenso-console 解析为同级 Checkout；
未提供 Acceptance Database URL 时会启动 disposable PostgreSQL，并清理临时
目录。全部前置条件与 Override 参见示例。