119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# 核心模块设计 — 总览
|
||
|
||
> 所属项目: 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)
|