修改第一个 App

初始化一个准确 Host Workspace，加入 Plugin Bundle，检查 Derived App，运行并移除改动。

Quickstart证明了一个隔离 Plugin。这个指南完成下一层边界：让该 Bundle 成为一个真实 App 的显式差异。

你需要从 Product Host Owner 获取两个 Artifact：

Host Executable；
由这个准确 Host Build 生成的 host-catalog.json。

通用 CLI 无法自行发明 Host 的 Root Slot、Embedded Plugin、Replacement Policy、 Runtime Driver 或 Execution Adapter。

1. 初始化 App Workspace

始终让 Host 与匹配的 Catalog 成对出现：

lenso app init \
  --host ./host \
  --host-catalog ./host-catalog.json \
  --root ./my-app

该命令创建 App Owner 唯一可见的两个 Root：

my-app/
├── .lenso/
│   ├── host
│   └── host-catalog.json
└── plugins/

.lenso/host-catalog.json 是 Host Build 生成的只读 Authority。plugins/ 只包含 App 相对 Host Default 的差异。

2. 检查 Host Default

lenso plugins list --root ./my-app
lenso app show --root ./my-app
lenso app check --root ./my-app

plugins list 显示每个 Derived Plugin Instance 及其来源；app show 继续显示准确 Capability Binding 与 Plan Key；app check 给出 Derived App 最短的 Pass/Fail 验证。

3. 加入 Bundle

使用 Quickstart 生成的 Bundle：

lenso plugins add \
  ./example.echo/dist/example.echo-0.1.0.lenso-plugin \
  --root ./my-app

在向 plugins/ 提交字节前，CLI 会验证 Archive、根据 Host Catalog 解析完整 Candidate，并拒绝未知 Plugin、非法 Replacement、缺失 Capability、歧义 Binding 或无效配置。

检查已接纳结果，不要仅凭新增目录推断成功：

lenso app show --root ./my-app
lenso app check --root ./my-app

新 Instance 必须带预期来源与 Capability Binding。如果 Host Catalog 没有把该 Plugin 提供给兼容 Slot，就应停止：App 配置不能扩大 Host Policy。

4. 运行当前 Host

lenso doctor --root ./my-app
lenso run --root ./my-app

doctor 检查 Host Catalog、可选 Host Executable、Derived App，以及 Execution Class 选择的外部 Runtime。run 使用当前 Plugin Root 直接派生 App，再启动复制的 Host。 App Owner 不需要生成或手工修改 Plan File。

接下来如何调用 example.echo 取决于 Host 的产品 Surface。Agent Host 可以把它暴露为 Tool；其他 Host 可以把同一个 Plugin Role 绑定到不同 Surface。

5. 证明替换与移除

先在不删除配置的情况下禁用 Instance、检查结果，再启用：

lenso plugins disable example.echo default --root ./my-app
lenso app show --root ./my-app
lenso plugins enable example.echo default --root ./my-app

最后移除整个 App-owned Plugin 目录：

lenso plugins remove example.echo --root ./my-app
lenso app check --root ./my-app

整个 Plugin 的移除会使用可恢复的 .lenso/trash/ 路径。传入 Instance Key 只会删除该 Instance Difference，并可能重新显示匹配的 Host Default；两种操作后都应检查 Derived App。

当 Add、Run、Disable、Enable 与 Remove 都产生预期的可观察行为时，这个闭环才算完成。设置或解析结果与本指南不一致时，继续阅读检查与排障 App。