解决方案结构说明

关联文档：总体概述

本文档描述 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 中重复：

<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 相关设置：

<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 跳过，本地按需运行：

dotnet test --filter "Category!=Integration"
dotnet test --filter "Category=Integration"  # 需要设置 ANTHROPIC_API_KEY

12 KiB Raw Blame History Unescape Escape