用混合同步保持 Topic 路由显式可审计

Topic 路由是 Agent 运行时里最容易失去审计性的地方之一。如果每个 Agent manifest 都能静默改写全局投递表，一个看似普通的订阅变更就可能扩大事件投递面。反过来，如果所有路由都只能手写，新增 Agent、改名和订阅变更又很容易漏同步。

Eva-CLI 应采用混合方案：生产运行时继续以 config/routes/topics.yaml 作为路由事实源，同时允许工具读取 config/agents/**/agent.yaml，生成建议路由、一致性报告和显式写回补丁。

两个文件承担不同职责

agent.yaml 仍然适合描述 Agent 自身：身份、父子管理意图、订阅、子路由提示和可发 Topic 权限。但这些声明不应自动变成 Scheduler 投递权力。Scheduler 应从经过校验的 config/routes/topics.yaml 构建 RouteTable。

文件	负责内容	运行时规则
config/agents/**/agent.yaml	Agent 身份、subscriptions、children、局部路由提示和 permissions.emit。	作为 discovery、policy 校验、mailbox 注册和路由建议生成的输入。
config/routes/topics.yaml	全局 Topic pattern 匹配、delivery 模式、目标 Agent 和匹配顺序。	Scheduler 投递的生产事实源。
.eva/generated/routes/topics.generated.yaml	从 Agent manifest 推导出的建议路由。	只作为诊断产物，不作为生产路由表。
.eva/reports/config/routes-diff.json	冲突、缺失路由、孤儿目标和建议修复。	作为 review、CI 和 IDE 诊断证据。

命令入口必须让写入显式化

更安全的体验是让每一次写入都可见。校验和 diff 生成可以在 CI 或 IDE 中自动运行；更新 topics.yaml 必须通过用户明确触发的命令或 quick-fix。

命令	行为	是否写文件
eva config validate	校验 schema、Agent 引用、Topic pattern、权限和路由一致性。	否
eva config routes sync --check	从 Agent manifest 生成建议，并与 topics.yaml 对比。	否
eva config routes preview	在改动源文件前展示合并后的路由表和冲突说明。	否
eva config routes sync --write	将安全、可解释、无冲突的建议写回 topics.yaml。	是
eva config routes dump-effective	展示 Scheduler 校验后实际使用的 RouteTable。	否

为什么不完全动态生成？

自动生成对简单 fanout 订阅很有吸引力，但生产路由不只是“谁订阅了这个字符串”。delivery 模式、优先级、通配符遮蔽、fallback 行为和 target override 都是全局运行时决策。这些决策应保留在可 review 的路由表中。

方案	擅长	薄弱点
完全手写路由	审计、回滚、复杂匹配规则和安全 review。	新增或重命名 Agent 时容易漏同步。
完全动态生成	快速 Agent 脚手架和简单订阅覆盖。	事实源不清晰，manifest 写错时可能不安全地扩大投递面。
混合同步	保留显式生产路由，同时用机器发现漂移。	需要良好的校验规则和谨慎的写回行为。

真正的产品是校验能力

混合方案成立的前提，是校验足够严格。一个有用的 validator 应发现不存在的路由目标、disabled Agent、delivery 冲突、永远收不到事件的订阅、投递给未声明订阅 Agent 的全局路由，以及超出 permissions.emit 的发射 Topic。

agent.yaml
  -> 扫描 manifest
  -> 构建建议路由
  -> 与 topics.yaml 对比
  -> 报告缺失、孤儿、冲突或不安全路由
  -> 只通过显式同步命令写回

这样可以让运行时启动路径保持简单：解析 topics.yaml，校验 schema 和 policy，然后构建新的 Scheduler RouteTable generation。启动时可以读取 Agent manifest 做交叉校验，但不得静默修改路由文件。

完整规格见 Topic 路由混合同步方案，相关配置背景见 项目配置方案。