Feature/cqrs projection suite

[loning]

This pull request introduces a major reorganization and renaming of the project structure, updates documentation and configuration, and adds CI automation. The changes focus on standardizing naming conventions, improving clarity for new contributors, and enforcing architectural guidelines via CI. Below are the most important changes:

Project Structure and Naming Refactor:

• Renamed and reorganized core project folders and namespaces for clarity and consistency, e.g., Aevatar.Api is now Aevatar.Hosts.Api, Aevatar.Cognitive is now Aevatar.Workflows.Core, and similar changes across AI, Foundation, Configuration, and Gateway components. Test and demo projects were also renamed accordingly. (aevatar.slnx, aevatar.ai.slnf, aevatar.foundation.slnf, README.md, demos/Aevatar.Demos.Cli/*, [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]

• Updated all references in documentation, code comments, and project files to reflect the new structure and naming conventions. (README.md, [1] [2] [3] [4] [5] [6]

Continuous Integration and Coding Standards:

• Added a GitHub Actions workflow (ci.yml) to automate build, test, and architectural guard checks (e.g., preventing sync-over-async, string-based type matching, and forbidden project references). (.github/workflows/ci.yml, .github/workflows/ci.ymlR1-R46)

• Introduced a .editorconfig file to enforce C# code style, formatting, and import ordering across the codebase. (.editorconfig, .editorconfigR1-R21)

Documentation Improvements:

• Updated the main README.md and removed outdated CLI demo documentation to match the new structure, clarify entry points, and provide accurate guidance for contributors and users. (README.md, demos/Aevatar.Demo.Cli/README.md, [1] [2] [3] [4] [5] [6] [7]

These changes lay the groundwork for a more maintainable, scalable, and contributor-friendly project.

[eanzhao]

PR #2 Review: Feature/cqrs-projection-suite

分支: feature/cqrs-projection-suite
规模: 461 files, +12,142 / -2,744, 28 commits
日期: 2026-02-13

---

概要

这是一个大型架构重构 PR，核心做了三件事：

1. 引入通用 CQRS Projection 框架 — 基于 Abstractions / Core / Domain 三层分离的读侧投影管线
2. 将 Workflow 拆分为五层架构 — Core、Application、Infrastructure、Projection、Presentation.AGUIAdapter
3. 重组 AI 层依赖 — Aevatar.AI 拆为 AI.Abstractions + AI.Core，LLM/Tool Provider 只依赖 Abstractions

---

目录

• P0 — 必须修复
• P1 — 应该修复
• P2 — 设计改进建议
• P3 — 小问题 / Nice to Have
• 亮点
• 各模块详细评审
  • CQRS Projection 框架
  • Workflow 五层架构
  • AI 层重构
  • Bootstrap 与 API 层
  • 测试覆盖
  • Demos
  • 文档与 CI
• Action Items 汇总

---

P0 — 必须修复

1. WorkflowExecutionAGUIEventProjector 未注册到 DI

AddWorkflowExecutionAGUIAdapter() 注册了 mapper 和 6 个 mapping handler，但没有注册 projector 本身。宿主必须手动调用：

services.AddWorkflowExecutionProjectionProjector<WorkflowExecutionAGUIEventProjector>();

这在 README 中没有文档说明，非常容易遗漏。

建议: 在 AddWorkflowExecutionAGUIAdapter() 内部自动注册该 projector。

2. WorkflowGAgent._childAgentIds 未持久化

_childAgentIds 是内存中的 List<string>。Agent 被 deactivate 再 reactivate 后，列表为空，EnsureAgentTreeAsync() 会重新创建子 agent，而旧的 agent 可能仍存在于 runtime 中。

影响: 资源泄漏 + agent 重复创建。

建议: 将 _childAgentIds 持久化到 WorkflowState，或在 reactivation 时从 runtime 查询已有子 agent。

---

P1 — 应该修复

3. CI 架构守卫路径可能已过时

CI 中检查 Aevatar.Workflows.Core 的 rg 命令路径可能与实际目录 workflow/Aevatar.Workflow.Core/ 不匹配。如果路径不匹配，rg 无结果 = 成功 = 守卫静默通过，形成假阴性。

建议: 验证 CI 中所有 rg 命令的路径，确保与当前目录结构一致。

4. 多处 doc comment 残留旧名称 "chat"

位置	问题
WorkflowExecutionReadModelNotFoundException	错误消息: "Chat run read model not found"
WorkflowExecutionProjectionOptions	XML doc: "Feature flags for chat projection pipeline"
ServiceCollectionExtensions (Projection)	XML doc: "DI registration for chat CQRS projection pipeline"
InMemoryWorkflowExecutionReadModelStore	XML doc: "In-memory store for chat run read models"

建议: 全部替换为 "Workflow execution"。

5. InMemoryWorkflowExecutionReadModelStore 无限增长

没有 eviction、TTL 或最大容量限制。长时间运行的进程会不断在内存中积累 report。

建议: 增加 LRU eviction 或 TTL 机制；至少提供一个 MaxCapacity 配置项。

6. WorkflowExecutionProjectionService._contexts 可能泄漏

如果 StartAsync 之后调用方抛异常导致 CompleteAsync 永远不被调用，context 会永远留在 ConcurrentDictionary 中。

建议: 加 TTL 自动清理，或在 DisposeAsync 中回收所有活跃 context。

---

P2 — 设计改进建议

7. ActorRuntimeWorkflowExecutionTopologyResolver.GetAllAsync() 拉取全部 Actor

GetAllAsync() 获取系统中所有 actor，然后做 BFS 过滤。在大规模多 workflow 场景下，这是 O(N)。

建议: 给 IActorRuntime 添加 GetChildrenAsync(actorId) 方法，避免加载整个 actor 集合。

8. ResolveEventTimestamp 绕过了 IProjectionClock

WorkflowExecutionReadModelProjector 中的 fallback 直接用 DateTimeOffset.UtcNow，没走注入的 IProjectionClock，导致这部分时间戳在测试中不可控。

建议: 使用注入的 IProjectionClock 替代 DateTimeOffset.UtcNow。

9. Projection → Core 耦合

Projection 项目直接引用 Workflow.Core 来访问 protobuf 事件类型（如 StartWorkflowEvent）。如果 Core 的事件类型演进，Projection 必须同步更新。

建议: 抽取一个 Workflow.Events / Workflow.Contracts 薄层，只包含 protobuf 生成类型，让 Projection 和 Core 都依赖它。

10. 双重模型层级的维护负担

WorkflowExecutionReport（Projection 层）和 WorkflowRunReport（Application.Abstractions 层）结构几乎完全一样，WorkflowExecutionReadModelMapper 用约 120 行做逐属性映射。

建议: 考虑让 Projection read model 直接使用 Application Abstractions 的类型，或抽取共享 model 包。

11. WorkflowOutputFrame 扁平属性包丢失类型安全

12+ 种 event type 全映射到一个 record 上（大量 nullable 字段），消费方无法 pattern match。

建议: 使用 sealed hierarchy 或至少保留 Type discriminator + union type。

---

P3 — 小问题 / Nice to Have

12. WorkflowGAgent 硬编码中文错误消息

HandleChatRequest 返回 "工作流未编译或未配置"。建议统一用英文或使用 resource string。

13. CI 缺少 feature/** push 触发器

CI 在 main、dev、refactor/** 上触发 push，但此 PR 在 feature/cqrs-projection-suite 上。仅靠 PR event 触发可以工作，但 push 时不会自动运行。

14. CI 无 NuGet 缓存

每次运行都做完整 restore。对多项目 repo 来说增加了不必要的时间。建议加 actions/cache。

15. WorkflowExecutionProjectionSession 疑似死代码

这个类似乎没有被使用。Service 层用的是 Application Abstractions 的 WorkflowProjectionSession。建议删除或补充说明用途。

16. ActorStreamSubscriptionHub.DispatchAsync 日志级别过低

catch 中只记了 LogDebug。理论上这个 catch 不应触发（上游已 catch），但如果触发了，Debug 级别太安静。建议提升到 LogWarning。

17. _childAgentIds 线程安全

_childAgentIds 是普通 List<string>，HandleChatRequest（调 EnsureAgentTreeAsync）和 ConfigureWorkflow（调 _childAgentIds.Clear()）可能并发执行。虽然在 single-threaded actor 模型中风险较低，但 ConfigureWorkflow 是 public 方法。

18. ProjectionSubscriptionRegistry.UnregisterAsync 未使用 actorId 参数

参数存在于接口签名中，但实现完全忽略（只按 runId 查找）。如果无其他实现需要它，建议从接口中移除或添加文档注释说明原因。

---

亮点

CQRS Projection 框架设计优秀

Abstractions / Core / Domain 三层分离，interface 设计干净。IProjectionEventReducer / IProjectionProjector / IProjectionCoordinator 各司其职。泛型框架可复用于任意领域——CaseProjection demo 就是最好的证明。

CaseProjection Demo 质量非常高

4 个项目的结构是 OCP 的教科书级示范。Extensions.Sla 的 reducer 在独立程序集中，通过 AddCaseProjectionExtensionsFromAssembly() 零侵入加载。

测试覆盖强

WorkflowExecutionProjectionServiceTests 是全 PR 最好的测试文件——7 个测试覆盖完整生命周期、超时、失败快速返回、终端事件后忽略后续事件、多 run 共享 actor stream。全部使用真实 InMemoryStreamProvider，不 mock。

AI 层拆分干净

Aevatar.AI -> AI.Abstractions + AI.Core，LLM Provider 和 Tool Provider 只依赖 Abstractions，真正做到可替换。新增的 IAgentToolSource 接口提供了可扩展的 tool 发现机制。

Bootstrap 层清晰

Connector 从 switch 改为 Builder 模式（OCP），DI 组合根集中管理，feature flag 控制可选功能。旧的 Program.cs 中散落的注册逻辑被完全收敛。

文档自我审查诚实

ARCHITECTURE_REVIEW_SCORE_REPORT.md 给自己打 79/100 并列出具体不足和改进路线，这种做法值得认可。

---

各模块详细评审

1. CQRS Projection 框架

依赖图（无环 DAG）:

Aevatar.CQRS.Projection.Abstractions (纯接口，零实现)
        ↑
Aevatar.CQRS.Projection.Core (通用协调、流式分发、DI)
        ↑
Aevatar.Workflow.Projection (领域特定 reducer / projector / read model)

管线流程: LifecycleService.Start → Coordinator.Initialize + SubscriptionRegistry.Register → actor stream 事件分发 → Coordinator.Project（fan-out 到 projectors）→ LifecycleService.Complete → unregister + finalize

Abstractions 层:

• 接口设计干净，每个接口单一职责
• IProjectionClock 和 IProjectionRunIdGenerator 使系统可测试
• IProjectionEventReducer.Reduce 是同步的（纯状态变更），符合 CQRS pattern，但永久关闭了异步 enrichment 的可能性

Core 层:

• ProjectionCoordinator 按 Order 排序 projector，immutable 快照
• ProjectionSubscriptionRegistry 使用 Interlocked.CompareExchange + TaskCompletionSource<RunContinuationsAsynchronously> 做单次状态翻转，正确
• ActorStreamSubscriptionHub 正确实现 fan-out，disposal 彻底，AsyncDisposableHandle 用 CAS 实现幂等 dispose
• ProjectionAssemblyRegistration 的 GetLoadableTypes fallback 是好的防御性编程

潜在竞态: DispatchAsync 中终端检测 + 投影 + 标记非原子。如果事件并发分发，非终端事件可能在终端标记完成前通过 IsProjectionActive 检查。实践中无害（reducer 应幂等），但值得注释说明。

2. Workflow 五层架构

项目依赖图（无环）:

Application.Abstractions (纯端口，零引用)
   ↑  ↑  ↑
   |  |  └── Infrastructure
   |  └──── Application ←── Core
   └────── Projection ←── Core
                ↑
           AGUIAdapter ←── Core

Workflow.Core:

• WorkflowGAgent 生命周期清晰：OnActivateAsync 重编译 YAML + 重装 module
• Module 组装通过 IWorkflowModuleDependencyExpander + IWorkflowModuleConfigurator 实现 OCP
• WorkflowStepTypeModuleDependencyExpander 递归遍历 steps，处理隐式依赖（TargetRole → llm_call，foreach 无 sub_step_type → parallel）

Workflow.Application:

• WorkflowChatRunApplicationService 编排流程清晰：CreateRunContext → ProcessEnvelope → StreamOutput → Finalize
• finally 块正确处理 abort/rollback + timeout
• WorkflowDefinitionRegistry 用 ConcurrentDictionary + OrdinalIgnoreCase，线程安全

Workflow.Infrastructure:

• 只依赖 Application.Abstractions + Configuration，无 Core 依赖，干净
• FileSystemWorkflowExecutionReportArtifactSink 尊重 Enabled flag
• WorkflowDefinitionFileLoader.LoadInto 是同步 I/O（File.ReadAllText），大量 YAML 文件时可考虑异步

Workflow.Projection:

• Reducer 按事件类型特化，Order 值 (0, 10, 20, 30, 40) 留有插入空间
• TryMarkProcessed 用 ConcurrentDictionary.TryAdd 实现幂等
• InMemoryWorkflowExecutionReadModelStore 在读写时深拷贝，防止 aliasing bug
• Run ID 解析可扩展：IWorkflowExecutionRunIdResolver 有序解析链

3. AI 层重构

拆分质量:

• 旧 Aevatar.AI（26 文件）完全删除，内容迁移到两个新包
• AI.Abstractions 只有接口 / DTO / proto，依赖 Foundation.Abstractions
• AI.Core 包含实现（AIGAgentBase、RoleGAgent、ChatRuntime 等），依赖 Abstractions + Foundation.Core
• LLM Provider (MEAI / Tornado) 和 Tool Provider (MCP / Skills) 只依赖 AI.Abstractions

新接口:

• IRoleAgentTypeResolver — 策略接口，允许宿主替换自定义 role agent 类型
• IAgentToolSource — tool 发现插件接口，MCPAgentToolSource / SkillsAgentToolSource 各自实现
• ChatSessionKeys — 静态辅助类，格式 runId:stepId，有输入校验
• IAIGAgentExecutionHook — 从 IAgentHook 重命名，与 Foundation 层命名对齐

注意: AIAgentConfig（Core）和 RoleAgentConfig（Abstractions）字段几乎相同，存在手动映射。考虑是否合并。

4. Bootstrap 与 API 层

Bootstrap（新组合根）:

• AddAevatarBootstrap() 提供单一入口，整合 Runtime / Workflow / Config / MEAI / MCP / Skills / Connector
• LLM key 解析链：explicit option → env var → secrets store → config fallback
• Connector 从 switch 改为 Builder 模式：IConnectorBuilder 接口 + HttpConnectorBuilder / CliConnectorBuilder / MCPConnectorBuilder

API 层（Aevatar.Api 删除 → Host.Api 替代）:

删除的文件	替代
Program.cs (107L)	Host.Api/Program.cs — 精简，委托给 Bootstrap + Application
ConnectorRegistration.cs (94L)	Bootstrap/ConnectorRegistration.cs + Builder 模式
ChatEndpoints.cs (245L)	Host.Api/Endpoints/ — 拆分为多个文件
AgUiProjector.cs (171L)	AGUIAdapter/WorkflowExecutionAGUIEventProjector
ChatRunRecorder.cs (249L)	Projection pipeline (read model store + reducers)
WorkflowRegistry.cs (65L)	Workflow.Application + AddWorkflowDefinitionFileSource()

回归风险: 最高的是 ChatEndpoints——旧代码把 SSE 写入、投影、录制全部内联在一个方法里。现在拆到 3+ 层。架构更好，但集成 bug 面积增大。186 个通过的测试提供了一定信心，但端到端 chat SSE 测试会是最强保障。

5. 测试覆盖

总体评价: 高质量，行为驱动，无反模式

测试项目	关注点	质量
Aevatar.Host.Api.Tests	AGUI channel, Chat endpoints, SSE, WS, DI registration	强
Aevatar.Workflow.Application.Tests	App service error path, query service, topology resolver	足够（缺 happy path）
WorkflowExecutionProjectionServiceTests	完整投影生命周期, timeout, failure, 多 run 共享 stream	非常强
WorkflowExecutionReadModelProjectorTests	Read model 构建, 去重, 时间戳, store 排序	强
WorkflowExecutionReportWriterTests	HTML/JSON 生成, XSS, 空状态	充分
Aevatar.Integration.Tests	Connector config, MCP config, Secrets, Module composition	充分

测试风格优点:

• 全部是行为测试，验证输出（HTTP status、read model 内容、topology 边），不是方法调用计数
• 手写 Fakes 而非 mock 框架（FakeActorRuntime、SpyRunOrchestrator 等）
• 边界 case 覆盖好：空输入、null payload、容量溢出、超时、失败、去重
• WaitUntilAsync 轮询 helper 是测试异步投影的好模式

缺口:

• WorkflowChatRunApplicationService.ExecuteAsync 缺 happy path 单元测试（只有 error path）
• AI 层（AIGAgentBase、ChatRuntime、ToolCallLoop）在此 PR 中没有专属测试项目
• 并发分发压力测试缺失

6. Demos

CaseProjection（新） — 4 个项目，OCP 教科书示范：

• Abstractions: proto events, interfaces, read models
• Core: reducers, projectors, store, DI
• Extensions.Sla: 独立程序集中的 reducer，零侵入加载
• Host: 可运行的控制台 demo

注意: InMemoryCaseReadModelStore.Clone() 是约 30 行的手动深拷贝。添加新字段时必须同步更新，建议加注释提醒。

Maker（从 samples/ 迁移） — README 映射论文概念到代码，自定义 module 演示了工作流引擎扩展。

Cli（重命名） — Aevatar.Demo.Cli → Aevatar.Demos.Cli，命名统一。

7. 文档与 CI

文档:

• AGENTS.md — 贡献者指南质量高，架构规则、CI 守卫、Mermaid 引号规则都有涵盖
• ARCHITECTURE_REVIEW_SCORE_REPORT.md — 79/100 自评，证据引用具体文件路径和行号
• IDENTIFIER_RELATIONSHIPS.md — 填补了 RunId vs EventEnvelope.Id 的知识空白
• FOUNDATION.md / COGNITIVE.md — 更新准确，CQRS 管线描述清晰

CI:

• Build → Test → Architecture Guards 管线正确
• -m:1 -p:UseSharedCompilation=false 避免 CI 共享编译状态的 flakiness
• 缺少：feature/** push 触发、NuGet 缓存、code coverage 报告
• 风险：rg (ripgrep) 在 ubuntu-latest 上不一定预装

---

Action Items 汇总

优先级	编号	说明	工作量
P0	#1	AGUIAdapter projector 注册到 DI	小
P0	#2	_childAgentIds 持久化或 reactivation 查询	中
P1	#3	验证并修正 CI 架构守卫路径	小
P1	#4	替换残留 "chat" 命名（4 处）	小
P1	#5	ReadModelStore 增加容量限制	小
P1	#6	_contexts 泄漏防护	小
P2	#7	Topology resolver 避免全量加载	中
P2	#8	ResolveEventTimestamp 使用 IProjectionClock	小
P2	#9	抽取 Workflow.Events 薄层	中
P2	#10	评估合并双重模型层级	中
P2	#11	WorkflowOutputFrame 类型安全改进	中
P3	#12	错误消息国际化	小
P3	#13	CI 添加 feature/** 触发	小
P3	#14	CI 添加 NuGet 缓存	小
P3	#15	删除 WorkflowExecutionProjectionSession 死代码	小
P3	#16	Hub dispatch 日志级别提升	小
P3	#17	_childAgentIds 线程安全	小
P3	#18	UnregisterAsync actorId 参数清理	小

---

总结

架构设计质量高，分层合理，测试充分。CQRS Projection 框架是本 PR 最大亮点——通用性好、OCP 扩展点清晰、测试覆盖强。AI 层拆分和 Bootstrap 组合根也是实质性改进。

合并建议: 修复 2 个 P0 bug 后可合并。P1 问题建议在合并前或紧跟的 follow-up PR 中处理。P2/P3 问题可放入后续迭代。

[loning]

📊 codex 进展 meta-reflect-issue796-r2 (⏳ 进行中; 已跑 7 min)

+
+### r6 Implementation Framing
+
+- Delete `src/Aevatar.AI.ToolProviders.Skills/SkillRegistry.cs`.
+- Delete or replace `test/Aevatar.AI.ToolProviders.Ornn.Tests/SkillRegistryTtlTests.cs`.
+- Add `src/Aevatar.AI.ToolProviders.Skills/LocalSkillCatalog.cs`.
+- `LocalSkillCatalog` is concrete, local-only, and contains no `TimeProvider`, `FetchedAt`, TTL, `_lock`, remote-id fallback cache, or remote registration API.
+- Register `LocalSkillCatalog` instead of `SkillRegistry`.
+- Update `SkillsAgentToolSource`, `UseSkillTool`, `ConversationReplyGenerator`, and `NyxIdChatGAgent` to depend on `LocalSkillCatalog`.
+- `UseSkillTool` resolves local skills from `LocalSkillCatalog`; on local miss it calls `IRemoteSkillFetcher` using the current `AgentToolRequestContext.NyxIdAccessToken`; it never writes remote results to the catalog.
+- Prompt decoration may include only local deployed skills. Remote skill discovery remains `ornn_search_skills` plus explicit `use_skill`.
+- Update `src/Aevatar.AI.ToolProviders.Skills/README.md`, `agents/Aevatar.GAgents.NyxidChat/Skills/system-prompt.md`, and `docs/canon/daily-command-pipeline.md` to remove "local + remote registry" and "5 minute in-process cache" wording. The canon edit is factual sync only.
+- Add/update tests proving repeated remote calls invoke the fetcher again with the current token, remote fetch does not mutate local catalog, local skills do not require token, prompt decoration lists local skills only, and stale registry warning behavior is removed.
+- Run `bash tools/ci/test_stability_guards.sh` plus the affected test projects.
+
+META_RESOLVED:force-pick:local-skill-catalog:delete SkillRegistry and TTL tests; introduce local-only LocalSkillCatalog; fetch remote use_skill per current request token with factual docs sync only

tokens used
72,225
Done.

Wrote [meta-reflect-issue796-r2.md](/Users/auric/aevatar/.refactor-loop/runs/meta-reflect-issue796-r2.md) and posted the comment to issue #796:

`https://github.com/aevatarAI/aevatar/issues/796#issuecomment-4515685983`

自动更新每 10 分钟;edit-in-place 不堆评论;codex 完成后此 comment 自动删除(per Auric "完成后删掉就好了 否则太占空间")。
🤖 controller progress reporter