# Eva-CLI 方案设计风险评审 更新日期：2026-06-12 ## 1. 文档定位 本文整理当前 Eva-CLI 架构方案在纯设计层面的主要缺陷和风险点。 本文不讨论实施步骤，也不拆解开发任务。重点是评估当前方案是否已经形成稳定、可验证、可演进的架构语义闭环。 相关文档： - `总体架构方案.md` - `Rust与Lua事件总线智能体调度架构方案.md` - `Lua调用外部Agent动态Adapter架构方案.md` - `Lua承载Skill-MCP-Tool热更新架构方案.md` - `Agent扫描与发现架构方案.md` - `项目配置方案.md` - `进程级停机升级架构方案.md` - `外接硬件接入与热插拔架构方案.md` ## 2. 总体判断 当前方案的方向成立，边界意识较强，尤其是 Rust 管权限和系统能力、Lua 管业务逻辑、Discovery 不等于授权、Adapter 作为受控能力单元这些原则是合理的。 主要缺陷不是某个单点模块设计错误，而是： - 平台能力定义多于 Bot 行为定义。 - 模块边界定义多于跨模块语义定义。 - 目标架构完整性高，但早期核心闭环被复杂平台能力稀释。 - 状态、一致性、权限、版本、错误恢复和对话行为还没有完全闭合。 ## 3. 风险点 ### 3.1 目标范围过大，主线不够聚焦 当前方案同时覆盖 Bot、Agent 调度、Lua 热更新、Adapter、MCP、Skill、硬件、Supervisor、高可用升级和恢复。 作为平台蓝图，这个范围可以接受。但作为实现 Bot agent 的方案，主路径被稀释：用户输入如何变成稳定回复、上下文如何维护、工具如何选择、失败如何反馈，反而不是最强定义。 风险： - 架构工作优先级压过 Bot 产品闭环。 - 早期实现容易先做平台骨架，却无法证明 Bot 体验可用。 - 每个模块都合理，但组合后复杂度高于当前目标所需。 ### 3.2 Bot 本身的产品语义缺失 方案定义了 Agent 运行时，却没有充分定义 Bot 的行为模型。 缺失点包括： - 多轮对话如何建模。 - session 如何识别、恢复和隔离。 - conversation memory 如何裁剪和持久化。 - Bot 何时直接回答，何时调用工具，何时澄清。 - 流式回复如何表达。 - 用户取消如何传递到 Agent、Adapter 和外部 provider。 - 工具失败后如何降级为用户可理解的回复。 风险： - 最终可能实现出一个可调度 Agent 的系统，但不是一个稳定好用的 Bot。 - Bot 逻辑可能散落在 Lua 脚本、Adapter、Topic 约定和 CLI 层中。 ### 3.3 事件一致性语义还不够硬 方案提到 best-effort、至少一次投递、WAL、watermark、dead letter 和幂等，但还没有统一到每类 Topic 的语义。 需要被设计明确的问题： - 哪些 Topic 必须持久化。 - 哪些 Topic 可以丢弃。 - 哪些 Topic 必须有序。 - 哪些 Topic 可以重复投递。 - 哪些 Topic 携带非幂等副作用。 - 哪些事件在返回 `accepted` 前必须落盘。 典型高风险 Topic： - `/input/user` - `/adapter/invoke` - `/adapter/completed` - `/agent/reply` - `/tool/started` - `/tool/completed` - 硬件命令类 Topic - workspace 写入类 Topic 风险： - 崩溃恢复时重复调用外部 provider。 - 重放事件导致重复写 workspace、重复发硬件命令或重复提交外部副作用。 - 纯内存模式、可恢复模式、外部队列模式之间语义不一致。 ### 3.4 状态边界仍然偏抽象 方案说 Agent 局部状态归 Agent，全局状态显式建模，但 Bot 系统里的状态类型仍需更细。 当前未充分闭合的状态包括： - 会话状态。 - 对话历史。 - 模型上下文窗口。 - 工具调用状态。 - 长任务状态。 - 用户授权状态。 - Agent 局部状态。 - Adapter inflight 状态。 - Runtime generation 状态。 风险： - 状态可能在 Lua State、StateStore、EventBus、AdapterRegistry、Snapshot Store 之间分裂。 - 热更新或 Runtime 切流后，会话语义不稳定。 - Bot 对话恢复、工具恢复和任务恢复之间缺少统一口径。 ### 3.5 Topic 路由可能演化成隐式协议地狱 Topic 路由灵活，但灵活本身也是风险。 当前有 `/sys/**`、`/task/**`、`/adapter/**`、`/mcp/**`、`/agent/**` 等方向，但还缺少强约束的 Topic catalog、payload schema 和版本策略。 风险： - Agent 之间通过隐式字符串约定协作。 - payload 结构随脚本演化而漂移。 - 新旧 Agent 混跑时协议不兼容。 - trace 能看到事件链，但无法判断 payload 是否符合语义。 ### 3.6 Adapter 抽象过宽 方案用统一 Adapter 模型承载 CLI、HTTP API、MCP、Skill、本地模型、内部 Agent 和硬件。 统一入口有价值，但这些能力的差异非常大： - CLI 偏进程生命周期和 stdout/stderr 协议。 - HTTP API 偏认证、rate limit 和响应 schema。 - MCP 偏 tool/resource/prompt protocol。 - Skill 偏本地 workflow runtime gate。 - 内部 Agent 偏 EventBus 路由和状态。 - 硬件偏设备 lease、热插拔、命令队列和物理副作用。 风险： - `AgentInvokeRequest` 可能变成过宽的万能协议。 - 各 transport 的取消、流式、幂等和审计语义被过度拉平。 - Router 很难在统一 capability 下做准确的 provider 选择。 ### 3.7 Capability 命名会成为冲突点 方案已经识别 capability 注册表缺失。更深层问题是 capability 名称不能只是字符串标签。 例如： - `chat.reply` - `task.plan` - `repo.analyze` - `code.review` - `workflow.code_review` - `mcp.tool.call` 这些名称需要同时绑定： - 输入 schema。 - 输出 schema。 - 副作用等级。 - 默认 provider。 - 可替代 provider。 - 质量要求。 - 权限要求。 - 版本兼容策略。 风险： - 不同 Adapter 使用同名 capability，但语义不同。 - Agent 以为调用的是业务能力，实际调用到 provider 私有语义。 - 后续新增 provider 时出现同名不同义和输出不兼容。 ### 3.8 权限模型缺少形式化闭包 方案强调最终权限只能收紧，不能放宽，这个方向正确。但权限合并模型还需要更严格的设计表达。 涉及的权限来源包括： - 系统默认 policy。 - workspace policy。 - Agent manifest。 - Adapter manifest。 - MCP tool policy。 - Skill runtime gate。 - Lua sandbox policy。 - 用户或 session policy。 风险： - 每层都做一点校验，但没有唯一的最终判定模型。 - 权限冲突时缺少稳定优先级。 - `permissions.tools`、`permissions.adapters`、`permissions.emit`、MCP allowlist 和 workspace policy 之间可能出现解释差异。 - 审计时无法解释“为什么允许或拒绝这次调用”。 ### 3.9 LLM 特有安全问题没有单独建模 当前安全重点主要是文件、shell、网络、硬件、MCP 和权限边界。 Bot/Agent 系统还需要单独建模 LLM 特有风险： - prompt injection。 - tool injection。 - 恶意仓库内容诱导越权。 - 外部网页、MCP resource 或 tool output 中的不可信指令。 - 模型输出诱导调用高权限 Adapter。 - 上下文污染导致跨会话信息泄露。 风险： - 普通 policy 只能限制最终工具权限，不能描述不可信内容如何传播。 - Agent 可能把外部内容当作系统指令。 - 工具结果进入后续 prompt 后，间接影响更高权限调用。 ### 3.10 热更新和版本兼容仍有语义缺口 generation swap、drain 和 rollback 已经有设计，但热更新还需要覆盖请求、状态、schema 和审计的完整语义。 未闭合问题： - 旧事件由旧代码还是新代码处理。 - 长任务跨 generation 时归属哪一代。 - schema 变化如何兼容旧事件和旧状态。 - StateStore migration 失败时如何处理。 - 新旧 capability 同时存在时 Router 如何稳定选择。 - 审计记录中是否强制绑定 generation、schema version 和 digest。 风险： - 热更新后旧事件被新逻辑处理，导致语义漂移。 - 回滚代码成功，但状态已经迁移到旧版本无法理解的格式。 - 长任务输出与发起时 capability 版本不一致。 ### 3.11 MCP 双向集成风险偏高 方案同时支持内部 Agent 调用外部 MCP server，以及外部 MCP client 调用内部 Agent。 这两个方向风险不同： - 内部调用外部 MCP：重点是外部 tool/resource/prompt 不可信。 - 外部 MCP client 调用内部 Agent：重点是身份认证、会话隔离、rate limit 和 capability 暴露边界。 风险： - 外部 MCP client 可能成为绕过 CLI/API 权限边界的入口。 - MCP tool 暴露粒度过粗时，会把内部 Agent 变成通用代理。 - per-client policy 和 session isolation 不明确时，审计和限流都不可靠。 ### 3.12 高可用和 Supervisor 设计可能过早复杂化 进程级恢复、Runtime 双活切流、WAL、Snapshot、State Store、SupervisorRecoveryGuard 都比较完整。 风险不在于这些设计错误，而在于它们可能过早压到核心 Bot 方案上： - 每个模块都需要考虑 generation、snapshot、drain 和恢复。 - MVP 的 Bot 行为尚未闭合时，高可用设计会放大实现和验证成本。 - 复杂恢复模型可能掩盖基础语义尚未稳定的问题。 ### 3.13 审计模型还不够面向决策 当前方案提到 trace、audit、correlation_id、causation_id、touched paths 和 diff summary。 但 Agent 系统需要的不只是日志，还需要决策解释链： - capability 如何解析。 - provider 为什么被选中。 - policy 为什么允许或拒绝。 - schema 为什么通过或失败。 - fallback 为什么触发。 - output schema 失败后如何降级。 风险： - 出问题时只能看到事件链，看不到系统决策依据。 - 安全审计无法证明权限合并和路由选择正确。 - 用户很难理解 Bot 为什么不能执行某项操作。 ### 3.14 错误模型偏技术层，缺少用户层语义 `AdapterErrorKind` 已经覆盖 NotFound、Unhealthy、PermissionDenied、Timeout、Cancelled、ProtocolError、ProviderError、OutputSchemaInvalid、RateLimited 和 ConcurrencyLimited。 但 Bot 需要进一步知道： - 是否自动重试。 - 是否切换 provider。 - 是否请求用户授权。 - 是否降级回答。 - 是否写入死信。 - 是否需要人工恢复。 - 是否可以把部分结果返回给用户。 风险： - 技术错误能被记录，但无法稳定转换成用户可理解的行为。 - 不同 Agent 对相同错误采取不同恢复策略。 - 外部 provider 失败时 Bot 表现不一致。 ### 3.15 验证矩阵有，但缺少设计级不变量 `Agent扫描与发现架构方案.md` 已有验证矩阵，但更高层的不变量仍需明确。 建议被视为设计级不变量的规则包括： - Lua 永远不能扩大权限。 - Discovery 永远不等于授权。 - 授权永远不等于执行。 - 注册失败不能破坏旧 registry。 - 已确认事件必须可恢复。 - 非幂等外部副作用不能被重复执行。 - 权限扩大不能无缝热加载。 - 旧 generation 的 inflight 请求必须绑定旧 generation。 - 外部不可信内容不能升级为系统指令。 - capability 同名必须同义，或必须显式版本化。 风险： - 测试覆盖具体场景，但系统关键安全和一致性原则没有被统一验证。 - 后续新增模块时容易局部正确、全局破坏。 ## 4. 需要重点补强的设计面 以下是需要补强的设计主题，不是实施步骤： - Bot 行为语义：对话、记忆、流式、取消、澄清、失败回复。 - 事件语义：按 Topic 固化持久化、有序性、幂等性、可丢弃性和副作用等级。 - 状态语义：会话、任务、工具调用、上下文、Agent 局部状态和全局状态的归属。 - Topic catalog：每个 Topic 的 payload schema、版本、生产者、消费者和可靠性语义。 - Capability registry：名称、schema、副作用、权限、provider、版本和兼容策略。 - 权限闭包：多来源 policy 的合并、冲突处理、最终判定和解释链。 - LLM 安全模型：不可信内容传播、prompt injection、tool injection 和上下文隔离。 - 热更新兼容：generation、schema version、StateStore migration、旧事件和长任务归属。 - MCP 暴露边界：双向 MCP 的认证、会话隔离、rate limit 和 per-tool policy。 - 审计决策链：允许、拒绝、路由、降级、回滚和 fallback 的可解释记录。 ## 5. 结论 当前方案适合作为 Eva-CLI 的目标平台架构，但还不适合作为一个可直接实现的 Bot agent 完整规格。 下一轮设计应优先让核心语义闭合，而不是继续扩展模块数量。尤其需要围绕 Bot 行为、事件一致性、状态归属、权限闭包、capability 语义和错误恢复建立稳定契约。