# 核心模块设计 — 总览

> 所属项目: free-code .NET 10 重写
> 配套文档: [总体概述与技术选型](../总体概述与技术选型/总体概述与技术选型.md) | [基础设施设计](../基础设施设计/) | [服务子系统设计](../服务子系统设计/) | [参考映射](reference/原始代码映射-核心模块.md)

---

## 概述

核心模块是整个 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` 进入，经历以下流程：

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

---

## 子模块列表

### [CLI 启动与解析](核心模块设计-CLI启动与解析.md)

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

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

---

### [查询引擎 (QueryEngine)](核心模块设计-查询引擎-QueryEngine.md)

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

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

---

### [工具系统](核心模块设计-工具系统.md)

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

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

---

### [多代理协调器 (Coordinator)](核心模块设计-多代理协调.md)

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

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

---

### [命令系统](核心模块设计-命令系统.md)

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

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

---

### [API 多提供商路由](核心模块设计-API提供商路由.md)

覆盖 `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 服务器意外覆盖核心工具行为。

---

## 参考资料

- [原始代码映射 — 核心模块](reference/原始代码映射-核心模块.md)
- [总体概述与技术选型](../总体概述与技术选型/总体概述与技术选型.md)
- [基础设施设计 — 状态管理](../基础设施设计/基础设施设计-状态管理.md)
- [基础设施设计 — MCP 协议集成](../基础设施设计/基础设施设计-MCP协议集成.md)