核心模块设计 — 总览

所属项目: free-code .NET 10 重写配套文档: 总体概述与技术选型 | 基础设施设计 | 服务子系统设计 | 参考映射

概述

核心模块是整个 free-code .NET 10 重写的骨架，直接对应原始 TypeScript 项目中最关键的几个文件。本组文档覆盖从进程启动到 LLM 调用的完整主路径，包含五个相互协作的子系统。

原始 TypeScript 实现将大量逻辑集中在少数几个大文件里（cli.tsx、QueryEngine.ts、tools.ts、commands.ts）。.NET 重写将这些职责拆分为更清晰的接口、抽象类和注册表，并通过依赖注入在运行时组装。

架构概览

Program.cs (入口)
    │
    ├── QuickPathHandler          快速路径：零 DI 开销，直接处理 flag 参数
    │
    └── IAppRunner (REPL/OnShot)
            │
            └── IQueryEngine      消息处理主管道
                    │
                    ├── IApiProviderRouter    → 路由到 Anthropic / Bedrock / Vertex / Codex / Foundry
                    ├── IToolRegistry         → 核心工具 + MCP 工具去重组装
                    ├── ICommandRegistry      → 70+ 斜杠命令
                    └── IPromptBuilder        → 6 段式 System Prompt 构建

一次用户提交的消息从 IQueryEngine.SubmitMessageAsync 进入，经历以下流程：

构建 System Prompt（SystemPromptBuilder）
获取可用工具列表（ToolRegistry）
通过 ApiProviderRouter 选择活跃的 API 提供商并发起流式请求
在 while 循环中处理响应流，直到模型不再触发工具调用
后处理：记忆提取、上下文压缩检查、统计更新

子模块列表

CLI 启动与解析

覆盖 Program.cs 的四阶段启动流程、QuickPathHandler 快速路径处理，以及基于 System.CommandLine 的 CLI 命令定义。

原始来源: ../../src/entrypoints/cli.tsx, ../../src/screens/REPL.tsx

查询引擎 (QueryEngine)

覆盖 IQueryEngine 接口、QueryEngine 流式循环实现，以及 SystemPromptBuilder 的六段构建逻辑。

原始来源: ../../src/QueryEngine.ts

工具系统

覆盖 ITool / ITool<TInput,TOutput> 接口体系、ToolBase<TInput,TOutput> 抽象基类、BashTool 完整实现，以及 ToolRegistry 组装与 MCP 去重策略。

原始来源: ../../src/tools.ts, ../../src/tools/

多代理协调器 (Coordinator)

覆盖 coordinator mode 的模式切换、worker 启停与继续、团队消息路由、会话恢复匹配，以及 ../../src/assistant/ 的历史会话读取配套能力。

原始来源: ../../src/coordinator/, ../../src/assistant/

命令系统

覆盖 ICommand 接口、CommandRegistry 注册 70+ 斜杠命令，以及命令分类与可用性控制机制。

原始来源: ../../src/commands.ts, ../../src/commands/

API 多提供商路由

覆盖 ApiProviderRouter 的环境变量自动检测、AnthropicProvider SSE 流式解析实现，以及全部提供商枚举。

原始来源: ../../src/services/api/

关键设计决策

依赖注入替代全局单例

原始 TypeScript 代码广泛使用模块级全局变量共享状态。.NET 重写通过 IServiceProvider 和构造函数注入统一管理所有依赖，生命周期由 AddCoreServices() / AddEngine() 等扩展方法集中配置。

快速路径零开销

QuickPathHandler.TryHandle 在 DI 容器构建之前执行，确保 --version、--mcp-daemon 等场景不承担任何初始化开销。

工具池稳定排序

ToolRegistry 对基础工具列表按名称字典序排序，保证在相同 feature flag 组合下 System Prompt 中的工具顺序不变，从而最大化 Anthropic prompt cache 命中率。

MCP 工具去重策略

内置工具的名称集合作为 HashSet 优先占位，MCP 同名工具被静默丢弃，防止外部 MCP 服务器意外覆盖核心工具行为。

4.8 KiB Raw Permalink Blame History Unescape Escape