Refactor/core cqrs parallel subsystems

[loning]

This pull request introduces significant architectural improvements, enforces stricter CI/CD validation, and updates documentation to reflect a modularized host structure. The main changes include the removal of legacy host projects, the addition of new subsystem hosts (Platform, Workflow, Maker), enhanced architecture guard checks in CI, and updates to project references and documentation for clarity and maintainability.

Architectural and Project Structure Changes:

• Removed legacy host projects (Aevatar.Host.Api and Aevatar.Host.Gateway) from the solution and replaced them with subsystem hosts: Aevatar.Platform.Host.Api, Aevatar.Workflow.Host.Api, and Aevatar.Maker.Host.Api. Updated the solution file (aevatar.slnx) to reflect these changes.
• Added new CQRS and platform-related projects to the solution, including Aevatar.CQRS.Core, Aevatar.CQRS.Runtime.Hosting, and related implementations, as well as Maker and Platform subsystems.
• Updated test project references to match the new host structure (e.g., replaced Aevatar.Host.Api.Tests with Aevatar.Workflow.Host.Api.Tests).

CI/CD and Architecture Guard Improvements:

• Enhanced .github/workflows/ci.yml to:
  • Forbid the presence and solution inclusion of legacy host projects.
  • Enforce that new host entry points use UseAevatarCqrsRuntime and AddAevatarCqrsRuntime.
  • Forbid direct usage of AddCqrsCore in hosts/infrastructure.
  • Restrict direct references to CQRS runtime implementations to the appropriate hosting projects only. [1] [2]

Documentation Updates:

• Updated README.md and AGENTS.md to:
  • Reflect the new subsystem host structure in all usage and architecture diagrams.
  • Standardize and document mermaid diagram settings for consistency across documentation. [1] [2] [3] [4] [5] [6] [7]
  • Remove references to legacy hosts and tests, replacing them with new subsystem hosts and related test projects.

Dependency and Package Management:

• Added WolverineFx as a new dependency in Directory.Packages.props to support CQRS runtime implementations. [1] [2]

Demo and Abstractions Refactoring:

• Refactored the CaseProjection demo and abstractions to align with new projection context and dispatcher patterns, removing outdated interfaces and simplifying dependency injection. [1] [2] [3] [4] [5] [6] [7]

These changes collectively modernize the project structure, enforce best practices, and improve maintainability and clarity for both developers and contributors.

[eanzhao]

PR6 Review Report (Re-run on Correct Branch)

Review Scope

• PR: #6 Refactor/core cqrs parallel subsystems
• Compare: refactor/core-cqrs-parallel-subsystems -> dev
• Diff Size: 337 files, +9211 / -2478
• Review Date: 2026-02-19

Findings (ordered by severity)

1) HIGH - Path Traversal in Platform command status store

• Files:
  • src/Aevatar.Platform.Host.Api/Endpoints/PlatformCommandEndpoints.cs
  • src/Aevatar.Platform.Application/Queries/PlatformCommandQueryApplicationService.cs
  • src/Aevatar.Platform.Infrastructure/Store/FileSystemPlatformCommandStateStore.cs
• Problem:
  • GET /api/commands/{commandId} 的 commandId 直接进入 Path.Combine(_statesPath, $"{commandId}.json")，没有做路径段净化。
• Risk:
  • 攻击者可构造 ../ 形式的 commandId 尝试读取工作目录外部文件（取决于运行账户权限）。
• Fix direction:
  • 对 commandId 做严格 allowlist（例如仅允许 [a-zA-Z0-9_-]）。
  • 或将外部 ID 映射为内部安全文件名（hash/escape），避免直接拼接路径。

2) HIGH - workflow_call flow regressed by single-active execution gate

• Files:
  • src/workflow/Aevatar.Workflow.Core/Modules/WorkflowCallModule.cs
  • src/workflow/Aevatar.Workflow.Core/Modules/WorkflowLoopModule.cs
• Problem:
  • WorkflowCallModule 在父流程执行中发布 StartWorkflowEvent。
  • WorkflowLoopModule 现改为 _executionActive 单布尔门控：流程执行中再次收到 StartWorkflowEvent 会直接返回 workflow is already running。
• Risk:
  • workflow_call/sub_workflow 语义被破坏，父流程内触发子流程会立即失败，属于功能回归。
• Fix direction:
  • 恢复可区分执行实例的运行上下文（例如 run/session key）；
  • 或为子流程调用设计独立执行通道，而非复用同一 active gate。

3) HIGH - /api/commands early-fault path returns unhandled exception

• File:
  • src/workflow/Aevatar.Workflow.Host.Api/Endpoints/ChatEndpoints.cs
• Problem:
  • HandleCommand 通过 Task.WhenAny(startSignal.Task, executionTask) 等待启动信号。
  • 若 executionTask 在 onStartedAsync 之前故障（例如投影初始化异常），会进入 await executionTask 直接抛出，缺少受控错误映射。
• Risk:
  • 返回不稳定 500，且错误语义不一致（与当前接口定义不匹配）。
• Fix direction:
  • 在 await executionTask 分支增加 try/catch，统一映射为结构化错误响应并记录日志。

4) MEDIUM - HTTP endpoints miss prompt validation parity with WS parser

• Files:
  • src/workflow/Aevatar.Workflow.Host.Api/Endpoints/ChatEndpoints.cs
  • src/workflow/Aevatar.Workflow.Host.Api/Endpoints/ChatWebSocketCommandParser.cs
• Problem:
  • WS 入口明确拒绝空 prompt，但 HTTP /api/chat 和 /api/commands 直接下发，不做等价校验。
• Risk:
  • 多入口行为不一致，容易产生不可预期失败路径和客户端兼容问题。
• Fix direction:
  • 在 HTTP 入口补齐 string.IsNullOrWhiteSpace(prompt) 校验并返回 400 结构化错误。

5) MEDIUM - FileSystem CQRS stores still build paths from raw IDs

• Files:
  • src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemCommandStateStore.cs
  • src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemInboxStore.cs
  • src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemOutboxStore.cs
  • src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemDeadLetterStore.cs
• Problem:
  • 多处 BuildPath() 直接将 commandId/messageId/deadLetterId 拼接为文件名。
• Risk:
  • 目前多数 ID 来自系统生成，现实风险低于平台查询接口；但这是明显的防御缺口，后续接入外部来源时会升级为可利用问题。
• Fix direction:
  • 统一引入路径段净化工具（与 SagaPathResolver.SanitizeSegment 同级策略），并在所有 Store 复用。

6) LOW - Broken XML doc comment in projection options

• File:
  • src/workflow/Aevatar.Workflow.Projection/Configuration/WorkflowExecutionProjectionOptions.cs
• Problem:
  • 存在未闭合、无内容的 /// <summary>。
• Risk:
  • 代码生成/文档警告噪音，影响质量门禁整洁度。
• Fix direction:
  • 删除该注释或补全注释块。

Test/Validation Performed

• dotnet test test/Aevatar.Workflow.Host.Api.Tests/Aevatar.Workflow.Host.Api.Tests.csproj --nologo ✅ (55 passed)
• dotnet test test/Aevatar.CQRS.Sagas.Core.Tests/Aevatar.CQRS.Sagas.Core.Tests.csproj --nologo ✅ (2 passed)

Residual Risks

• 当前测试覆盖未直接保护以下关键路径：
  • /api/commands 的 early-fault 异常分支；
  • workflow_call 在父流程执行中的行为；
  • 路径净化（path traversal）安全边界测试。

PR #6 Review Report

Branch: feature/execution-actor -> master
Scope: 469 files changed, +13,207 / -2,961 lines
Date: 2026-02-19

---

1. 总览

本 PR 是一次大规模的架构重构与功能演进，核心变更包括：

• 项目结构重组：将 workflow 相关项目迁入 src/workflow/ 目录，拆分 AI 层为 Abstractions / Core / Providers，删除旧 Aevatar.Api 替换为 Aevatar.Host.Api
• 引入 WorkflowExecutionGAgent：实现 per-run 执行 Actor，隔离工作流执行生命周期
• 统一 CQRS Projection Pipeline：三层泛型投影框架（Abstractions → Core → Workflow.Projection），AGUI 与 ReadModel 共用同一管道
• 新增 Application 层：Workflow.Application 封装 ChatRun 编排逻辑，查询服务与报告
• 新增 14 个 Workflow Module：包括 ToolCallModule、WorkflowLoopModule、WhileModule 等
• 测试与文档：新增 ~144+ 测试用例，新增多篇架构文档

整体架构设计合理，分层清晰，依赖方向正确。以下为详细评审。

---

2. 架构与分层

2.1 分层合规性：通过

Host.Api (组合层)
  ├─> Workflow.Application (应用编排)
  ├─> Workflow.Infrastructure (基础设施)
  ├─> Workflow.Projection (CQRS 投影)
  └─> Workflow.Presentation.AGUIAdapter (展示适配)

Workflow.Application
  ├─> Workflow.Core (领域)
  └─> Application.Abstractions (端口)

Workflow.Core
  ├─> AI.Abstractions ✅ (非 AI.Core)
  ├─> Foundation.Abstractions
  └─> Foundation.Core

• 依赖反转正确，无循环依赖
• Workflow.Core 未依赖 AI.Core，符合 CI 守卫规则
• Host 层仅做组合，不承载业务逻辑

2.2 命名规范

• 项目名 = 命名空间一致
• 缩写全大写（LLM、CQRS、AGUI、MCP）符合规范
• 小问题：aevatar.slnx 中路径分隔符混用（41-43 行用 /，44-46 行用 \），建议统一

2.3 统一投影管道：通过

ActorStreamSubscriptionHub 维护每个 Actor 的唯一 stream 订阅，ProjectionCoordinator 按序分发到多个 Projector（AGUI + ReadModel），实现了"单入口、一对多分发"原则。

---

3. 严重问题（建议合并前修复）

3.1 [Critical] SSE 换行符 bug

ChatSseResponseWriter.cs 第 45 行：

        var bytes = Encoding.UTF8.GetBytes($"data: {payload}\\n\\n");

C# 中 \\n 输出字面量 \n（反斜杠+n），而非真正的换行符。SSE 协议要求 data: ...\n\n（真实换行）。当前实现会导致所有 SSE 客户端无法正确解析事件流。

修复：改为 $"data: {payload}\n\n"。

3.2 [High] WhileModule 两处硬编码 bug

Bug A：续行路径 max_iterations 硬编码为 10

            var maxIterations = 10; // 简化：从初始请求中获取

首次请求时正确解析了 max_iterations 参数（第 37 行），但 StepCompletedEvent 处理路径直接写死 10。工作流配置 max_iterations: 50 在续行时无效。

Bug B：续行路径 StepType 硬编码为 "llm_call"

                    StepType = "llm_call",

首次迭代从参数读取 step 类型（第 43 行 subStepType），但后续迭代硬编码 "llm_call"。一个 while 循环内嵌 tool_call 或 connector_call 步骤，第一次迭代后会静默切换为 llm_call。

修复：将 maxIterations 和 subStepType 与 _iterations 一同存入 per-step 状态。

3.3 [High] ToolTruncationHook 截断无效

ToolCallLoop.cs 第 73-78 行：

                var result = await _tools.ExecuteToolCallAsync(call, ct);
                messages.Add(result);

                toolCtx.ToolResult = result.Content;
                if (_hooks != null) await _hooks.RunToolExecuteEndAsync(toolCtx, ct);

messages.Add(result) 在 Hook 运行之前执行。ToolTruncationHook 修改 toolCtx.ToolResult 后，已加入 messages 列表的原始 result 不会被更新。截断对 LLM 实际看到的内容无效。

修复：将 Hook 运行移到 messages.Add 之前，或在 Hook 执行后用 toolCtx.ToolResult 更新 result.Content。

3.4 [High] WebSocket 消息无大小限制

ChatWebSocketProtocol.ReceiveTextAsync 使用 8KB buffer 累积到 MemoryStream，无上限检查：

    public static async Task<string?> ReceiveTextAsync(WebSocket socket, CancellationToken ct)
    {
        var buffer = new byte[8192];
        using var ms = new MemoryStream();
        // ... 无大小检查的循环累积 ...
    }

恶意客户端可发送永不设置 EndOfMessage 的超大消息，导致 OOM。

修复：增加 maxMessageSize 参数（如 64KB），超限时中断连接。

---

4. 中等问题（建议近期修复）

4.1 [Medium] ConditionalModule 分支路由未实现

ConditionalModule 计算了 branchKey（"true"/"false"），但从未用于路由：

        var branchKey = input.Contains(condition, StringComparison.OrdinalIgnoreCase) ? "true" : "false";
        // branchKey 被丢弃，直接发 StepCompletedEvent
        await ctx.PublishAsync(new StepCompletedEvent { ... }, EventDirection.Self, ct);

StepDefinition.Branches 字典在 YAML 解析中有定义但从未被消费。条件分支功能形同虚设。

建议：实现真正的分支路由，或删除 ConditionalModule 和 StepDefinition.Branches 避免误导。

4.2 [Medium] ToolManager 异常信息泄露

        try { return ChatMessage.Tool(call.Id, await tool.ExecuteAsync(call.ArgumentsJson, ct)); }
        catch (Exception ex) { return ChatMessage.Tool(call.Id, $"{{\"error\":\"{ex.Message}\"}}"); }

两个问题：

1. ex.Message 可能包含敏感信息（文件路径、连接字符串、堆栈细节），直接暴露给 LLM 上下文
2. ex.Message 直接插入 JSON 字符串未转义，如果消息含引号或反斜杠会产生格式错误的 JSON

修复：返回通用错误信息，单独记录完整异常；用 JsonSerializer.Serialize 转义。

4.3 [Medium] 有状态 Module 未清理孤立条目

LLMCallModule._pending、ParallelFanOutModule._expected/_collected、ForEachModule._expected/_collected、WhileModule._iterations 均使用 Dictionary 存储 per-step 状态。如果子步骤超时或 Agent 崩溃，这些条目永远不会被清理。

建议：实现 CleanupRun(string runId) 方法或基于 TTL 的定期清扫。

4.4 [Medium] WorkflowExecutionGAgent._workflowAgentId 未持久化

private string _workflowAgentId = string.Empty;

此字段为内存状态，不在 protobuf WorkflowState 中。Actor 被反激活后重新激活时，_workflowAgentId 为空，ValidateBeforeRun 会拒绝所有请求。如果是设计为 per-run 短暂 Actor，需要文档说明。

4.5 [Medium] TopologyResolver 枚举全部 Actor

ActorRuntimeWorkflowExecutionTopologyResolver 调用 runtime.GetAllAsync() 遍历所有 Actor 来构建父子树。在有大量并发 Actor 的系统中，每次 run finalize 都执行此操作会成为瓶颈。

建议：考虑 GetDescendantsAsync(rootActorId) API 或在 run 期间缓存拓扑。

4.6 [Medium] Projection 投影链失败语义

ProjectionSubscriptionRegistry.DispatchAsync 中任一 Reducer/Projector 抛异常会将整个 run 标记为 Failed，无 "skip and continue" 策略。这是 fail-fast 设计选择，但应明确文档化。

4.7 [Medium] ProjectionService._contexts 无 TTL 清理

WorkflowExecutionProjectionService._contexts 是 Singleton 的 ConcurrentDictionary。如果 CompleteAsync 因故未被调用（进程崩溃、未处理异常跳过 Application 层 finally），context 条目永远不会被清理。

4.8 [Medium] CliConnectorBuilder 命令验证不足

        if (entry.Cli.Command.Contains("://", StringComparison.OrdinalIgnoreCase))
        {
            // ... reject URL ...
        }

仅阻止 URL 格式，不阻止路径遍历、任意二进制执行或 shell 元字符。如果 connector 配置来自不可信输入，存在注入风险。

4.9 [Medium] HttpConnector 创建新 HttpClient

_client = client ?? new HttpClient();

未注入时每实例创建 HttpClient，长时间运行可能导致 socket 耗尽。应使用 IHttpClientFactory。

---

5. 低优先级问题

#	问题	说明
5.1	WorkflowCallModule 无递归深度限制	嵌套 workflow_call 可无限递归，RunId 拼接无限增长
5.2	WorkflowVariables 完整实现但未使用	支持点路径访问、插值、合并，但无 Module 引用
5.3	StepDefinition.Branches/Children 已解析但未消费	结构存在但功能缺失
5.4	WorkflowOutputFrame 15 个 nullable 属性的扁平 DTO	位于 Application.Abstractions，可下沉到 Presentation 层
5.5	四个平行的 CompletionStatus 枚举	维护成本高，新增状态需改 4 处枚举 + 3 处映射
5.6	AIGAgentExecutionHookContext.LLMRequest/LLMResponse 类型为 object?	丢失类型安全
5.7	RoleAgentConfig 与 AIAgentConfig 字段完全重复	手工映射维护负担
5.8	EnsureRuntime() 跳过 RegisterToolsFromSourcesAsync	如果在激活前调用 ChatAsync，工具可能缺失
5.9	ProjectionSubscriptionRegistry / ProjectionCoordinator 未 sealed	子类化可能破坏线程安全不变式
5.10	ListRuns 查询端点无分页游标	仅支持 take，无 skip/after
5.11	中英文日志消息混用	如 "工作流未编译或未配置" vs "workflow yaml is empty"
5.12	TransformModule 吞掉异常并以 Success = true 传递错误信息	错误字符串被作为正常数据传给下一步
5.13	ToolCallModule._toolIndexLock SemaphoreSlim 未 Dispose	轻微资源泄露
5.14	ActorStreamSubscriptionHub 顺序分发 handler	慢 handler 阻塞同 actor 的后续 handler
5.15	ChatInput.Prompt 无长度校验	超大 prompt 直接传给 LLM

---

6. 测试覆盖

6.1 覆盖概况

测试项目	文件数	用例数(约)	评价
Foundation.Abstractions.Tests	4	~12	充分
Foundation.Core.Tests	13	~40+	优秀（含 7 个 BDD）
Host.Api.Tests	13	~55+	良好
Workflow.Application.Tests	2	~12	良好
Integration.Tests	8	~25+	优秀
合计	42	~144+

6.2 核心关注：Module 行为测试缺失

14 个 Workflow Module 中，仅 ConnectorCallModule 有完整的行为集成测试（5 个用例）。其余 Module 仅通过 WorkflowIntegrationTests.Scenario7_AllCoreModules 验证了可被 factory 创建，无 HandleAsync 行为测试：

Module	行为测试	风险
ToolCallModule	无	工具解析、执行、失败路径未验证
WhileModule	无	迭代计数、max_iterations、DONE 终止未验证
ConditionalModule	无	分支路由（已确认非功能性）未验证
VoteConsensusModule	无	投票收集、共识判断未验证
TransformModule	无	转换逻辑、异常处理未验证
ForEachModule	无	列表展开、子步骤收集未验证
AssignModule	无	变量赋值未验证
WorkflowCallModule	无	嵌套工作流、递归场景未验证
RetrieveFactsModule	无	事实检索逻辑未验证
CheckpointModule	无	检查点行为未验证

建议：至少为 ToolCallModule、WhileModule、WorkflowLoopModule 补充行为单元测试，这三个是执行主路径上的关键模块。

6.3 测试质量：优秀

已有测试质量很高：

• 使用真实 in-memory 实现而非 mock，验证真实行为
• 错误路径覆盖充分（projection 失败、超时、disabled、owner binding 违规、connector 缺失）
• FluentAssertions 断言清晰
• WorkflowExecutionOwnerBindingTests 是最完善的集成测试，验证了 bind-once 语义、RunId 强制、元数据不匹配拒绝等

6.4 其他测试缺口

• WebSocket 端点无测试（仅 HTTP 有）
• WorkflowChatRunApplicationService.ExecuteAsync 缺少 happy path 测试
• WorkflowExecutionGAgent 销毁竞态无回归测试（DESTROY_RACE_MEMO.md 中已提出但未实现）
• CancellationToken 传播未在 module pipeline 中测试

---

7. CI 与文档

7.1 CI 守卫

三项架构守卫有效：

1. 禁止 GetAwaiter().GetResult() 同步阻塞
2. 禁止 TypeUrl.Contains 字符串路由
3. 禁止 Workflow.Core 依赖 AI.Core

问题：CI push 触发器配置为 main/dev/refactor/**，但本 PR 目标分支为 master。合并到 master 的 push 不会触发 CI。pull_request 触发器可覆盖，但 push-based 守卫存在盲区。

建议：将 master 加入 push.branches 列表，或统一默认分支名。

7.2 文档质量

文档	评价
WORKFLOW_RUN_LIFECYCLE.md	优秀。清晰区分 WorkflowGAgent（长生命周期）与 WorkflowExecutionGAgent（per-run），序列图与代码一致
IDENTIFIER_RELATIONSHIPS.md	良好。EventEnvelope.Id / RunId / MessageId / ActorId 职责清晰
WORKFLOW_EXECUTION_DESTROY_RACE_MEMO.md	优秀。诚实的工程备忘，明确问题范围、现有缓解、三种方案比较
README.md	良好。面向目标读者（"略懂技术"），快速开始 3 步、架构图、步骤类型参考表

---

8. 亮点

值得肯定的设计：

1. CQRS Projection Pipeline 的泛型三层设计：Abstractions → Core → Workflow.Projection，真正可复用（demos 中的 CaseProjection 验证了这一点）
2. ActiveRunState 并发原语：Interlocked.CompareExchange 单次状态转换、TaskCompletionSource + RunContinuationsAsynchronously 避免重入、per-run CancellationTokenSource
3. ConnectorCallModule 的健壮性：retry、timeout、on_error/on_missing 策略、域名/方法/路径白名单
4. WorkflowExecutionOwnerBindingTests：bind-once 语义、幂等重绑定、未绑定快速失败、RunId 强制、元数据不匹配拒绝——集成测试标杆
5. Endpoint 拆分：6 个聚焦文件各司其职，Host 层零业务逻辑
6. Hook Pipeline 最佳实践：优先级排序、best-effort 执行、默认方法减少实现负担
7. DESTROY_RACE_MEMO.md：诚实记录已知低概率问题，而非掩盖

---

9. 修复优先级总结

合并前必须修复

#	问题	严重度
3.1	SSE \\n\\n 字面量 bug	Critical
3.2	WhileModule 两处硬编码	High
3.3	ToolTruncationHook 截断无效	High
3.4	WebSocket 消息无大小限制	High

合并后尽快修复

#	问题	严重度
4.1	ConditionalModule 分支路由未实现	Medium
4.2	ToolManager 异常信息泄露 + JSON 未转义	Medium
4.3	有状态 Module 孤立条目未清理	Medium
4.9	HttpConnector new HttpClient()	Medium

跟踪 backlog

#	问题	严重度
6.2	Module 行为测试补充	Medium
7.1	CI push 触发器加入 master	Medium
4.4-4.8	持久化、拓扑性能、projection 语义等	Medium
5.x	低优先级改善项	Low

---

10. 结论

本 PR 的架构设计水平较高，分层严谨，CQRS 投影管道的泛型抽象是值得学习的工程范例。已有测试质量优秀，文档完整诚实。

主要风险集中在 4 个必须修复的 bug（SSE 换行、WhileModule 硬编码、Hook 截断无效、WebSocket OOM）和 Module 行为测试的系统性缺失。修复这些问题后，PR 可以合并。

[eanzhao]

针对 PR #6 Refactor/core cqrs parallel subsystems（分支 refactor/core-cqrs-parallel-subsystems -> dev）的 Review 发现进行了二次验证，确认了 5 个有效问题并完成修复，降级了 1 个为设计说明。

变更统计：9 个文件，+127 / -14 行

---

验证与定性结果

#	问题	严重度	结论
1	文件系统 Store 路径遍历漏洞	HIGH	确认并修复
2	workflow_call 子流程被单执行门控拒绝	—	降级为设计说明（dev 上已有缺陷）
3	/api/commands 早期故障未捕获异常	HIGH	确认并修复
4	HTTP 端点缺少 prompt 空值校验	MEDIUM	确认并修复
5	CQRS FileSystem stores 路径拼接	MEDIUM	确认并修复（防御纵深）
6	XML 文档注释未闭合	LOW	确认并修复

---

修复详情

修复 1：路径遍历防护（HIGH）

问题描述

FileSystemPlatformCommandStateStore.BuildPath 直接将来自 HTTP 路由参数 {commandId} 的值拼接到文件路径中：

private string BuildPath(string commandId) => Path.Combine(_statesPath, $"{commandId}.json");

攻击者可构造 GET /api/commands/../../etc/passwd 形式的请求，通过 ../ 读取工作目录外的任意文件。同样的问题存在于 4 个 CQRS 内部 Store 中。

修复方案

使用 Path.GetFullPath 解析后检查结果路径是否仍在容器目录内。两种策略：

• Platform Store（外部输入）：返回 null，上层映射为 404，不暴露内部信息
• CQRS Stores（内部 ID）：抛出 ArgumentException，作为防御纵深

private string? SafeBuildPath(string id)
{
    var fullPath = Path.GetFullPath(Path.Combine(_statesPath, $"{id}.json"));
    var normalizedBase = Path.GetFullPath(_statesPath + Path.DirectorySeparatorChar);
    return fullPath.StartsWith(normalizedBase, StringComparison.OrdinalIgnoreCase) ? fullPath : null;
}

影响文件

文件	策略
src/Aevatar.Platform.Infrastructure/Store/FileSystemPlatformCommandStateStore.cs	返回 null
src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemCommandStateStore.cs	抛出异常
src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemInboxStore.cs	抛出异常
src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemOutboxStore.cs	抛出异常
src/Aevatar.CQRS.Runtime.FileSystem/Stores/FileSystemDeadLetterStore.cs	抛出异常

新增测试（7 个用例）

文件：test/Aevatar.Integration.Tests/FileSystemPlatformCommandStateStoreTests.cs

用例	验证内容
GetAsync_WithPathTraversal_ShouldReturnNull (x4)	../../etc/passwd、../secret、..\\windows\\...、sub/../../../escape 均返回 null
UpsertAsync_ThenGetAsync_ShouldRoundTrip	正常写入+读取往返正确
GetAsync_WithValidGuid_WhenNotStored_ShouldReturnNull	不存在的合法 ID 返回 null
ListAsync_ShouldReturnStoredItems	列表查询包含已写入条目

辅助变更：

• src/Aevatar.Platform.Infrastructure/Properties/InternalsVisibleTo.cs：暴露 internal 类型给测试项目
• test/Aevatar.Integration.Tests/Aevatar.Integration.Tests.csproj：添加 Aevatar.Platform.Infrastructure 项目引用

---

修复 2：HandleCommand 早期故障异常捕获（HIGH）

问题描述

ChatEndpoints.HandleCommand 使用 Task.WhenAny(startSignal.Task, executionTask) 等待启动信号。当 executionTask 在触发 onStartedAsync 回调之前就抛出异常（例如投影初始化失败），代码会进入 fallback 分支直接 await executionTask，异常未捕获，导致 ASP.NET Core 返回无结构的 500 响应。

修复方案

在 fallback 分支的 await executionTask 外层增加 try/catch：

CommandExecutionResult<...> result;
try
{
    result = await executionTask;
}
catch (Exception ex)
{
    logger.LogError(ex, "Workflow command execution failed before start signal");
    return Results.Json(
        new { code = "EXECUTION_FAILED", message = "Command execution failed." },
        statusCode: StatusCodes.Status500InternalServerError);
}

影响文件

• src/workflow/Aevatar.Workflow.Host.Api/Endpoints/ChatEndpoints.cs

新增测试（1 个用例）

文件：test/Aevatar.Workflow.Host.Api.Tests/ChatEndpointsInternalTests.cs

用例	验证内容
HandleCommand_WhenExecutionThrows_ShouldReturn500WithStructuredBody	服务抛出异常时返回 500 + JSON {code: "EXECUTION_FAILED"}

---

修复 3：HTTP 端点 prompt 校验对齐（MEDIUM）

问题描述

WebSocket 入口 ChatWebSocketCommandParser.TryParse 对空 prompt 有明确校验并返回 INVALID_PROMPT 错误码。但 HTTP 端点 HandleChat 和 HandleCommand 未做等价检查，空 prompt 会直接传入业务层，导致多入口行为不一致。

修复方案

在两个 HTTP handler 入口处增加校验：

if (string.IsNullOrWhiteSpace(input.Prompt))
{
    // HandleChat: 直接设置 400 状态码
    // HandleCommand: 返回 Results.BadRequest(new { code = "INVALID_PROMPT", ... })
}

影响文件

• src/workflow/Aevatar.Workflow.Host.Api/Endpoints/ChatEndpoints.cs

新增测试（2 个用例）

文件：test/Aevatar.Workflow.Host.Api.Tests/ChatEndpointsInternalTests.cs

用例	验证内容
HandleChat_WithEmptyPrompt_ShouldReturn400	空 prompt SSE 端点返回 400
HandleCommand_WithEmptyPrompt_ShouldReturn400WithCode	空 prompt Command 端点返回 400 + INVALID_PROMPT

---

修复 4：XML 文档注释修复（LOW）

问题描述

WorkflowExecutionProjectionOptions.cs 末尾存在一个未闭合的 /// <summary> 标签，无内容，会产生编译器文档警告。

修复方案

直接删除该孤立注释行。

影响文件

• src/workflow/Aevatar.Workflow.Projection/Configuration/WorkflowExecutionProjectionOptions.cs

---

降级说明：workflow_call 子流程执行

原始发现

PR 将 WorkflowLoopModule._activeRunIds（HashSet<string>）替换为 _executionActive（bool），同时从 proto 中移除了 RunId 字段。这导致 WorkflowCallModule 发布的子流程 StartWorkflowEvent 会被立即拒绝。

验证结果

通过 git diff dev...HEAD 比对发现，workflow_call 在 dev 分支上已存在功能缺陷：

1. 子流程的 WorkflowCompletedEvent 没有对应的 StepCompletedEvent 桥接回父流程
2. 父流程会在 workflow_call 步骤永远挂起，等待一个永远不会到来的完成事件

本 PR 将失败模式从"静默挂起"改为"立即拒绝并返回错误"，属于行为变更而非新增回归。彻底修复需要架构级改动（为子流程创建独立执行 Actor，或实现完成事件桥接），不在本次修复范围内。

---

排除的发现（dev 分支上已存在，非本 PR 引入）

问题	排除原因
SSE \\n\\n 字面量	重构后的 ChatSseResponseWriter.cs 已使用正确的 \n\n
WhileModule maxIterations=10 / StepType="llm_call" 硬编码	dev 上已存在；本 PR 仅移除了 RunId 字段
ToolTruncationHook 在 hook 执行前已加入 messages	dev 上已存在；本 PR 仅修改了 tool call 构造方式
WebSocket 无最大消息长度限制	dev 上已存在（文件仅做了重命名迁移）

---

测试验证

dotnet test test/Aevatar.Workflow.Host.Api.Tests/   → 58 passed (55 existing + 3 new)
dotnet test test/Aevatar.Integration.Tests/ --filter FileSystemPlatformCommandStateStore → 7 passed (all new)
dotnet build aevatar.slnx                            → 0 errors, 110 warnings (all pre-existing NU1507)

新增测试总计：10 个用例，覆盖所有修复的 bug 及其边界条件。