200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 解决方案结构说明
|
||
|
||
> 关联文档：[总体概述](../总体概述与技术选型.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
|
||
<Project>
|
||
<PropertyGroup>
|
||
<!-- 语言版本 -->
|
||
<LangVersion>13.0</LangVersion>
|
||
<Nullable>enable</Nullable>
|
||
<ImplicitUsings>enable</ImplicitUsings>
|
||
|
||
<!-- 目标框架 -->
|
||
<TargetFramework>net10.0</TargetFramework>
|
||
|
||
<!-- AOT 编译 (仅主项目覆盖为 true) -->
|
||
<PublishAot>false</PublishAot>
|
||
<PublishTrimmed>false</PublishTrimmed>
|
||
<IsAotCompatible>true</IsAotCompatible>
|
||
|
||
<!-- 警告即错误 -->
|
||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||
<WarningsAsErrors />
|
||
<NoWarn>CS1591</NoWarn>
|
||
|
||
<!-- 分析器 -->
|
||
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
|
||
<AnalysisLevel>latest-recommended</AnalysisLevel>
|
||
|
||
<!-- 版本管理 -->
|
||
<Version>0.1.0</Version>
|
||
<AssemblyVersion>0.1.0.0</AssemblyVersion>
|
||
</PropertyGroup>
|
||
|
||
<!-- 测试项目特定设置 -->
|
||
<PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
|
||
<IsTestProject>true</IsTestProject>
|
||
<IsAotCompatible>false</IsAotCompatible>
|
||
</PropertyGroup>
|
||
</Project>
|
||
```
|
||
|
||
主项目 `FreeCode.csproj` 在此基础上覆盖 AOT 相关设置：
|
||
|
||
```xml
|
||
<PropertyGroup>
|
||
<OutputType>Exe</OutputType>
|
||
<PublishAot>true</PublishAot>
|
||
<PublishTrimmed>true</PublishTrimmed>
|
||
<InvariantGlobalization>true</InvariantGlobalization>
|
||
<StripSymbols>true</StripSymbols>
|
||
</PropertyGroup>
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
```
|