# 解决方案结构说明
> 关联文档：[总体概述](../总体概述与技术选型.md)
本文档描述 FreeCode .NET 解决方案的项目划分方式、各项目职责和相互依赖关系，帮助开发者快速定位代码归属和贡献边界。
---
## 1. FreeCode.sln 概览
解决方案包含 **17 个源码项目** 和 **9 个测试项目**，合计 26 个项目。整体采用垂直切分策略：每个项目对应一个关注点，通过接口而非直接引用来解耦。
```
FreeCode.sln
├── 源码项目 (17)
│ ├── FreeCode # 主可执行入口
│ ├── FreeCode.Core # 核心接口与模型
│ ├── FreeCode.Engine # 查询引擎
│ ├── FreeCode.Tools # 工具实现
│ ├── FreeCode.Commands # 命令实现
│ ├── FreeCode.ApiProviders # LLM API 适配
│ ├── FreeCode.Mcp # MCP 协议
│ ├── FreeCode.Lsp # LSP 集成
│ ├── FreeCode.Bridge # IDE 桥接
│ ├── FreeCode.Services # 业务服务
│ ├── FreeCode.Tasks # 后台任务
│ ├── FreeCode.Skills # 技能系统
│ ├── FreeCode.Plugins # 插件系统
│ ├── FreeCode.Features # 特性开关
│ ├── FreeCode.State # 状态管理
│ └── FreeCode.TerminalUI # 终端 UI 组件
└── 测试项目 (9)
├── FreeCode.Core.Tests
├── FreeCode.Engine.Tests
├── FreeCode.Tools.Tests
├── FreeCode.Commands.Tests
├── FreeCode.ApiProviders.Tests
├── FreeCode.Mcp.Tests
├── FreeCode.Services.Tests
├── FreeCode.Tasks.Tests
└── FreeCode.Integration.Tests
```
---
## 2. 各项目职责说明
| 项目名 | 职责 | 关键类型 | 依赖项目 |
|--------|------|----------|----------|
| **FreeCode** | 主可执行 Console App，入口点、DI 容器组装、命令行解析 | `Program`, `RootCommand`, `Startup` | 全部项目 |
| **FreeCode.Core** | 核心接口与模型，25+ 接口、20+ 模型，无外部依赖，是整个解决方案的契约层 | `ITool`, `ICommand`, `IApiProvider`, `ChatMessage`, `ToolResult`, `AppConfig` | 无 |
| **FreeCode.Engine** | QueryEngine 协调消息流与工具调用，PromptBuilder 构建系统提示词 | `QueryEngine`, `PromptBuilder`, `ToolDispatcher`, `ConversationHistory` | Core |
| **FreeCode.Tools** | 50+ 工具实现，按子目录分组：FileSystem、Shell、Agent、Web、Mcp、UserInteraction、PlanMode、Swarms、Worktree | `BashTool`, `ReadFileTool`, `GlobTool`, `GrepTool`, `AgentTool`, `BrowserTool`, `McpTool`, `PlanModeTool`, `WorktreeTool` | Core, Services, Mcp |
| **FreeCode.Commands** | 70+ 斜杠命令实现，每个命令对应一个类 | `ClearCommand`, `CompactCommand`, `ReviewWorkCommand`, `InitDeepCommand`, `RalphLoopCommand` | Core, Engine, State, Skills |
| **FreeCode.ApiProviders** | 5 个 LLM 提供商适配：Anthropic、OpenAI、Gemini、GitHub Copilot、Bedrock | `ClaudeProvider`, `OpenAiProvider`, `GeminiProvider`, `CopilotProvider`, `BedrockProvider` | Core |
| **FreeCode.Mcp** | MCP 协议客户端与服务端，传输层实现，工具适配器 | `McpClient`, `McpServer`, `StdioTransport`, `SseTransport`, `McpToolWrapper` | Core |
| **FreeCode.Lsp** | LSP 客户端集成，支持 goto-definition、find-references、diagnostics、rename | `LspClient`, `LspDiagnosticsProvider`, `LspWorkspaceManager` | Core |
| **FreeCode.Bridge** | IDE 桥接层，与 VS Code / JetBrains 等 IDE 扩展通信 | `BridgeServer`, `BridgeMessage`, `IdeEventHandler` | Core, Services |
| **FreeCode.Services** | 业务服务层：文件系统抽象、配置管理、权限管理、搜索服务 | `FileService`, `ConfigService`, `PermissionService`, `RipgrepService`, `AstGrepService` | Core |
| **FreeCode.Tasks** | 后台任务管理：任务队列、任务状态跟踪、MCP 监控任务、Workflow 任务 | `BackgroundTaskManager`, `TaskQueue`, `MonitorMcpTask`, `LocalWorkflowTask` | Core, Services |
| **FreeCode.Skills** | 技能系统：技能加载、索引、搜索和执行 | `SkillLoader`, `SkillIndex`, `SkillSearchService`, `SkillExecutor` | Core, Services |
| **FreeCode.Plugins** | 插件系统：通过 AssemblyLoadContext 动态加载插件，插件发现和生命周期管理 | `PluginLoader`, `PluginHost`, `PluginRegistry` | Core |
| **FreeCode.Features** | 特性开关系统，控制实验性功能的启用状态，支持编译期和运行期两种模式 | `FeatureFlags`, `FeatureRegistry`, `IFeatureFlag` | Core |
| **FreeCode.State** | 应用状态管理，线程安全的状态读写，状态订阅 | `AppStateStore`, `ConversationState`, `SessionState` | Core |
| **FreeCode.TerminalUI** | Terminal.Gui v2 组件封装，REPL 界面、输出渲染、进度显示 | `ReplView`, `OutputPane`, `StatusBar`, `ThemeManager` | Core, State |
---
## 3. 项目依赖关系图
```
┌─────────────────┐
│ FreeCode.Core │
│ (接口 + 模型) │
└────────┬────────┘
│ 被所有项目引用
┌─────────────────────┼──────────────────────────┐
│ │ │
┌──────▼──────┐ ┌─────────▼─────────┐ ┌──────────▼────────┐
│FreeCode. │ │FreeCode.ApiProviders│ │FreeCode.Services │
│Features │ │(LLM 适配层) │ │(文件/搜索/配置) │
└──────┬──────┘ └─────────┬─────────┘ └──────────┬────────┘
│ │ │
┌──────▼──────┐ ┌─────────▼─────────┐ ┌──────────▼────────┐
│FreeCode. │ │ FreeCode.Engine │ │ FreeCode.Mcp │
│State │ │ (QueryEngine) │ │ (MCP 协议) │
└──────┬──────┘ └─────────┬─────────┘ └──────────┬────────┘
│ │ │
┌──────▼─────────────────────▼──────────────────────────▼────────┐
│ FreeCode.Tools │
│ (50+ 工具, 依赖 Services + Mcp) │
└──────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌──────▼──────┐ ┌────────▼───────┐ ┌───────▼────────┐
│FreeCode. │ │FreeCode.Skills │ │FreeCode.Tasks │
│Commands │ │(技能系统) │ │(后台任务) │
└──────┬──────┘ └────────┬───────┘ └───────┬────────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌──────────▼─────────┐
│ FreeCode.TerminalUI│
│ (Terminal.Gui 组件)│
└──────────┬─────────┘
│
┌───────────────▼────────────────┐
│ FreeCode (主入口) │
│ DI 组装 + CLI + 程序生命周期 │
└────────────────────────────────┘
独立模块 (通过接口与主流程交互):
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│FreeCode.Lsp │ │FreeCode.Bridge│ │FreeCode.Plugins│
│(LSP 客户端) │ │(IDE 桥接) │ │(动态插件) │
└──────────────┘ └──────────────┘ └──────────────┘
```
---
## 4. Directory.Build.props 共享配置
所有项目共享一个根级别的 `Directory.Build.props`，统一配置编译选项，避免在每个 `.csproj` 中重复：
```xml
13.0
enable
enable
net10.0
false
false
true
true
CS1591
true
latest-recommended
0.1.0
0.1.0.0
true
false
```
主项目 `FreeCode.csproj` 在此基础上覆盖 AOT 相关设置：
```xml
Exe
true
true
true
true
```
---
## 5. 测试项目结构
9 个测试项目覆盖核心业务逻辑，遵循一对一映射原则（一个源码项目对应一个测试项目），加一个集成测试项目。
| 测试项目 | 对应源码项目 | 测试重点 |
|----------|-------------|----------|
| FreeCode.Core.Tests | FreeCode.Core | 模型验证、接口约定、序列化正确性 |
| FreeCode.Engine.Tests | FreeCode.Engine | QueryEngine 消息流、工具调度逻辑、PromptBuilder 输出 |
| FreeCode.Tools.Tests | FreeCode.Tools | 各工具的单元行为，沙箱文件系统，进程调用 mock |
| FreeCode.Commands.Tests | FreeCode.Commands | 命令解析、执行逻辑、输出格式 |
| FreeCode.ApiProviders.Tests | FreeCode.ApiProviders | 请求构建、响应解析、错误处理、流式解析 |
| FreeCode.Mcp.Tests | FreeCode.Mcp | JSON-RPC 消息编解码、传输层、客户端生命周期 |
| FreeCode.Services.Tests | FreeCode.Services | 文件服务、配置加载、权限检查、搜索结果解析 |
| FreeCode.Tasks.Tests | FreeCode.Tasks | 任务队列背压、取消、状态转换 |
| FreeCode.Integration.Tests | 全部项目 | 端到端命令执行，真实 API（可选，通过环境变量控制） |
测试框架统一使用 **xUnit 2.x** + **FluentAssertions 6.x** + **Moq 4.x**。集成测试通过 `[Trait("Category", "Integration")]` 标注，默认 CI 跳过，本地按需运行：
```bash
dotnet test --filter "Category!=Integration"
dotnet test --filter "Category=Integration" # 需要设置 ANTHROPIC_API_KEY
```