Eva-CLI 命令行工具功能设计

Eva-CLI 的架构刻意把权力边界放在 Rust：校验、权限、进程生命周期、审计和副作用都由 Runtime 托管，Lua Agent 只表达可热更新业务行为。命令行工具要把这套架构暴露给用户，但不能让脚本绕过这些边界。到了 V1.5 源码发布检查点，这个表面已经可以执行诊断、发布门禁和 plan-first 运维操作。

目标 eva 命令应该入口足够小，自动化语义足够稳定。新用户需要版本、doctor、校验、inspect 和第一条运行路径；CI 需要 JSON、确定性 exit code、dry-run 计划和 trace ID；运维场景需要能产出证据的恢复与发布命令，而不是隐藏变更。

先统一命令形态

命令模型应该保持可预测：

eva <command> [subcommand] [flags]

--workspace、--profile、--output json、--dry-run、--yes、--locale 和 --trace 这类全局参数应在命令组之间保持一致。早期实现中，这种一致性比添加大量窄捷径更重要。

命令分组

第一版可用 CLI 不需要覆盖所有未来能力。V1.5 已经证明 Runtime 闭环、配置边界、外部能力诊断、恢复证据和发布加固门禁，同时把真实 provider 执行和破坏性 apply 路径留给后续版本。

命令组	示例命令	V1.5 状态
Workspace	version、doctor、config validate、inspect；目标命令 init	诊断面已实现；workspace 创建仍是目标命令。
任务执行	run --example basic、task status、task logs、task cancel	已实现于 in-memory basic loop 和本地 task report。
Agent Runtime	agent list、agent inspect、agent reload	目标控制面；V1.5 通过 config 与 inspect 诊断暴露 Agent 信息。
扩展能力	adapter list/probe、mcp list/probe、skill list/run、discovery scan	已实现为受控 envelope 和无副作用诊断。
硬件	hardware list、hardware probe、hardware bind	已实现为不打开 raw I/O 的 plan-first 诊断。
运维恢复	backup create、snapshot create、restore plan、upgrade check、release check/security/perf/migration	已实现为非破坏性证据和发布门禁。

变更前先生成计划

可能修改运行时状态的命令必须先生成 execution plan。计划应在任何变更发生前解析 workspace、profile、runtime generation、manifest、schema 和 policy 合并结果。文本模式下，用户看到变更范围和确认提示；JSON 模式下，自动化拿到 plan 对象和明确的 requires_confirmation 字段。

这条规则尤其适用于 restore、upgrade、snapshot promote、hardware binding，以及任何具备写权限的 Adapter 调用。CLI 可以方便，但不能成为静默扩大权限的路径。

输出也是产品契约

Eva-CLI 应把输出格式当成 API 设计。人类输出可以包含表格和恢复建议；机器输出要足够稳定，能被 CI 和本地自动化消费。

结果	含义	自动化字段
ok	命令已完成。	status、data、trace_id
planned	未产生变更，计划已生成。	status、plan、requires_confirmation
accepted	长任务已进入 Runtime。	status、task_id、trace_id
blocked	policy 或前置条件阻止执行。	status、error、missing

实现路径

风险最低的路径是分层交付 CLI。Eva-CLI 到 V1.5 已经按这个路径推进：先有校验和 inspect，再有 basic runtime loop，然后是外部能力诊断、记忆上下文、硬件计划、备份与生命周期检查，最后补齐发布加固门禁。下一层不是继续扩大不受控命令面，而是签名 artifact、durable state、真实 provider supervision，以及高风险操作的显式 apply gate。

完整技术方案见 Eva-CLI 命令行工具功能设计文档。