# 总体概述与技术选型

> **文档版本**: 1.0  
> **日期**: 2026-04-05  
> **所属部分**: 第一部分  
> **原始设计来源**: `DESIGN-NET10.md` 第一部分（第 1-4 节及附录）

---

## 目录

- [1. 项目概述](#1-项目概述)
- [2. 技术栈映射](#2-技术栈映射)
- [3. 顶层架构设计](#3-顶层架构设计)
- [4. 解决方案结构](#4-解决方案结构)
- [5. 关键设计决策](#5-关键设计决策)
- [模块覆盖对照表](#模块覆盖对照表)
- [参考文档](#参考文档)

---

## 1. 项目概述

free-code 是 Anthropic Claude Code CLI 的社区 fork，一个终端原生 AI 编码代理。本次重写目标是将整个项目从 TypeScript/Bun/React+Ink 技术栈完整迁移至 .NET 10，同时保持 100% 功能对等。

**原始版本规模**: v2.1.87，包含 200+ 个 TS/TSX 源文件、50+ 个 Agent 工具、70+ 个 Slash 命令、5 个 LLM 提供商接入。

### 核心功能清单

- **交互式 REPL**: 终端 AI 对话界面，流式响应、工具调用可视化、权限审批
- **50+ Agent 工具**: 文件读写编辑、Bash 执行、代码搜索、Web 访问、子代理生成
- **70+ Slash 命令**: 配置、会话管理、OAuth、插件、主题等
- **5 个 LLM 提供商**: Anthropic、OpenAI Codex、AWS Bedrock、Google Vertex AI、Anthropic Foundry
- **MCP/LSP 协议**: 外部工具集成 + 语言服务器
- **IDE 桥接**: VS Code/JetBrains 远程会话控制
- **技能/插件系统**: 可扩展 prompt 模板 + 功能包
- **后台任务、会话记忆、语音输入、远程会话、同伴系统**

### 重写目标

| 目标 | 描述 |
|------|------|
| 功能对等 | 100% 覆盖所有功能 |
| 性能提升 | .NET 10 AOT 编译，启动速度与内存双优化 |
| 类型安全 | C# 13 强类型替代 TypeScript 运行时校验 |
| 原生集成 | 更深度的 OS 集成（进程、文件系统、沙箱） |
| 可维护性 | 清晰模块边界、DI、接口驱动设计 |

> .NET 10 平台特性详见: [./reference/.NET-10-平台介绍.md](reference/.NET-10-平台介绍.md)

---

## 2. 技术栈映射

将 TypeScript 生态的每个技术点一一对应至 .NET 10 生态，选型原则是成熟度优先、官方方案优先、AOT 兼容性优先。

| 层级 | 原始 (TS/Bun) | .NET 10 替代 | 理由 |
|------|-------------|-------------|------|
| 运行时 | Bun >= 1.3.11 | .NET 10 + AOT | 单一二进制，跨平台 |
| 语言 | TypeScript 6 ESM | C# 13 | record types, pattern matching |
| 终端 UI | React 19 + Ink 6 | **Terminal.Gui v2** | 唯一成熟 .NET TUI，组件模型接近 React |
| 输出渲染 | Ink 内置 | **Spectre.Console** | 表格/面板/进度条/富文本 |
| CLI 解析 | Commander.js | **System.CommandLine v2** | 官方框架，子命令/选项/补全 |
| Schema 校验 | Zod v4 | **FluentValidation** + **JsonSchema.Net** | POCO 校验 + JSON Schema |
| 代码搜索 | ripgrep (bundled) | ripgrep via Process wrapper | 保持 ripgrep 性能 |
| LSP 客户端 | vscode-languageserver-protocol | **OmniSharp.Extensions.LanguageServer** | 最成熟 .NET LSP 库 |
| MCP 协议 | @modelcontextprotocol/sdk | **自研 MCP SDK** | 社区无成熟方案 |
| HTTP | Bun fetch | **HttpClient + Refit** | 强类型 REST，流式支持 |
| OAuth | 自定义 client | **MSAL.NET + IdentityModel.OidcClient** | 成熟 OAuth/OIDC |
| WebSocket | ws (npm) | **System.Net.WebSockets + SignalR** | 内建 + 高层抽象 |
| 进程管理 | Bun spawn | **System.Diagnostics.Process** | 内建跨平台 |
| JSON | JSON.parse/stringify | **System.Text.Json** | 高性能 AOT 友好 |
| 后台任务 | 自定义 | **BackgroundService + Channels** | .NET 标准模式 |
| 插件加载 | 动态 import() | **AssemblyLoadContext** | 运行时程序集隔离 |
| DI | 无 | **Microsoft.Extensions.DependencyInjection** | 标准 DI |
| 日志 | console | **Microsoft.Extensions.Logging** | 结构化日志 |

> 每个映射条目的详细说明，以及完整 NuGet 包版本清单，见: [./reference/技术栈映射说明.md](reference/技术栈映射说明.md)

---

## 3. 顶层架构设计

系统分五层，从下往上依次为基础层、基础设施层、核心服务层、应用层、表现层。

```
┌─────────────────────────────────────────────────────────────────┐
│                      Presentation Layer                         │
│  Terminal.Gui v2 (REPL)  │  System.CommandLine (CLI)           │
├─────────────────────────────────────────────────────────────────┤
│                      Application Layer                          │
│  REPL Controller  │  Command Dispatcher  │  QueryEngine         │
├─────────────────────────────────────────────────────────────────┤
│                    Core Services Layer                           │
│  ToolSystem(50+)  │  PermissionEngine  │  FeatureFlags          │
│  AgentSpawner     │  Memory/Context    │  PromptBuilder         │
├─────────────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                          │
│  ApiProviderRouter │  McpClientManager  │  LspClientManager     │
│  OAuthService      │  BackgroundTasks   │  IDE Bridge           │
│  SkillLoader       │  PluginLoader      │  RemoteSessions       │
│  RateLimitService  │  NotificationSvc   │  VoiceService         │
├─────────────────────────────────────────────────────────────────┤
│                     Foundation Layer                            │
│  AppState Store  │  Config System  │  Logging  │  DI Container  │
└─────────────────────────────────────────────────────────────────┘
```

**核心数据流**: 用户输入 → CLI/REPL → QueryEngine → PromptBuilder → ApiProvider → LLM 响应 → ToolUse 循环 → 渲染输出

每一层仅依赖其下层，不允许跨层向上依赖。基础设施层中的 MCP SDK 是自研实现，因为社区目前没有成熟的 .NET 方案，详见: [./reference/mcp-sdk-implement.md](reference/mcp-sdk-implement.md)

---

## 4. 解决方案结构

整个项目组织为一个 .sln 文件管理 17 个 C# 项目，加上 9 个测试项目。

```
FreeCode.sln
├── src/
│   ├── FreeCode/                    # 主可执行 (Console App, AOT)
│   ├── FreeCode.Core/               # 核心接口 + 模型 (25+ 接口, 20+ 模型)
│   ├── FreeCode.Engine/             # QueryEngine + PromptBuilder
│   ├── FreeCode.Tools/              # 50+ Agent 工具
│   │   ├── FileSystem/ (Read, Edit, Write, Glob, Grep, NotebookEdit)
│   │   ├── Shell/ (Bash, PowerShell)
│   │   ├── Agent/ (Agent, Skill, Task* tools)
│   │   ├── Web/ (WebFetch, WebSearch)
│   │   ├── Mcp/ (ListMcpResources, ReadMcpResource, ToolSearch)
│   │   ├── UserInteraction/ (AskUserQuestion, Brief)
│   │   ├── PlanMode/ (EnterPlan, ExitPlan)
│   │   ├── AgentSwarms/ (SendMessage, TeamCreate, TeamDelete)
│   │   └── Worktree/ (EnterWorktree, ExitWorktree)
│   ├── FreeCode.Commands/           # 70+ Slash 命令
│   ├── FreeCode.ApiProviders/       # 5 LLM 提供商
│   ├── FreeCode.Mcp/                # MCP 协议 (Transport + Protocol + ToolWrapper)
│   ├── FreeCode.Lsp/                # LSP 集成
│   ├── FreeCode.Bridge/             # IDE 桥接
│   ├── FreeCode.Services/           # 业务服务 (Auth/Memory/Voice/Remote/Notification/...)
│   ├── FreeCode.Tasks/              # 后台任务管理
│   ├── FreeCode.Skills/             # 技能系统
│   ├── FreeCode.Plugins/            # 插件系统 (AssemblyLoadContext)
│   ├── FreeCode.Features/           # 特性开关
│   ├── FreeCode.State/              # 状态管理 (AppState record)
│   └── FreeCode.TerminalUI/         # Terminal.Gui 组件 (REPL/Components/Theme/Keybindings)
├── tests/                           # 9 个测试项目
└── scripts/                         # build.ps1, build.sh, publish.sh
```

> 每个项目的职责边界、依赖关系图和 `Directory.Build.props` 共享配置，详见: [./reference/解决方案结构说明.md](reference/解决方案结构说明.md)

---

## 5. 关键设计决策

这些决策在整个设计方案中一以贯之，影响所有模块的实现方式。

| 决策点 | 选择 | 理由 |
|--------|------|------|
| 终端 UI 框架 | Terminal.Gui v2 | .NET 生态内唯一成熟的 TUI 方案 |
| CLI 解析框架 | System.CommandLine v2 | 官方库，v2 已稳定，子命令/选项/自动补全齐备 |
| MCP 协议客户端 | 自研 SDK | 社区目前没有成熟的 .NET 实现 |
| 插件隔离方式 | AssemblyLoadContext | .NET 原生支持，程序集可卸载 |
| 状态管理模式 | Record + Event | 不可变状态 + 事件驱动，类似 Redux/Elm |
| AOT 兼容策略 | Source Generator 优先 | 尽量避免反射，确保 AOT 编译不裁剪 |
| 代码搜索 | ripgrep 进程包装 | 保持原有 ripgrep 的搜索性能 |

---

## 模块覆盖对照表

> 说明：
> - ✅ 已覆盖：已有独立设计文档
> - ↗️ 归属：作为其他文档的小节或附属内容覆盖
> - 📋 空目录/stub：当前快照为空目录、占位文件或仅剩 stub，不单独出文档

| 原始 ../../src/ 目录 | 文件数 | docs/ 覆盖文档 | 状态 |
|------|------:|------|------|
| `entrypoints` | 11 | [核心模块设计 — CLI启动与解析](../核心模块设计/核心模块设计-CLI启动与解析.md) | ✅ 已覆盖 |
| `screens` | 3 | [核心模块设计 — CLI启动与解析](../核心模块设计/核心模块设计-CLI启动与解析.md) | ↗️ 归属 |
| `QueryEngine.ts` | 1 | [核心模块设计 — 查询引擎 (QueryEngine)](../核心模块设计/核心模块设计-查询引擎-QueryEngine.md) | ✅ 已覆盖 |
| `tools.ts`、`tools/` | 210 | [核心模块设计 — 工具系统](../核心模块设计/核心模块设计-工具系统.md) | ✅ 已覆盖 |
| `commands.ts`、`commands/` | 218 | [核心模块设计 — 命令系统](../核心模块设计/核心模块设计-命令系统.md) | ✅ 已覆盖 |
| `services/api/` | 39 | [核心模块设计 — API 多提供商路由](../核心模块设计/核心模块设计-API提供商路由.md) | ✅ 已覆盖 |
| `services/lsp/` | 7 | [基础设施设计 — LSP集成](../基础设施设计/基础设施设计-LSP集成.md) | ✅ 已覆盖 |
| `services/mcp/` | 22 | [基础设施设计 — MCP协议集成](../基础设施设计/基础设施设计-MCP协议集成.md) | ✅ 已覆盖 |
| `services/oauth/` | 7 | [服务子系统设计 — 认证与OAuth](../服务子系统设计/服务子系统设计-认证与OAuth.md) | ✅ 已覆盖 |
| `services/SessionMemory/` | 3 | [服务子系统设计 — 会话记忆与上下文](../服务子系统设计/服务子系统设计-会话记忆与上下文.md) | ✅ 已覆盖 |
| `services/contextCollapse/` | 3 | [服务子系统设计 — 会话记忆与上下文](../服务子系统设计/服务子系统设计-会话记忆与上下文.md) | ↗️ 归属 |
| `services/extractMemories/` | 2 | [服务子系统设计 — 会话记忆与上下文](../服务子系统设计/服务子系统设计-会话记忆与上下文.md) | ↗️ 归属 |
| `services/teamMemorySync/` | 5 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/autoDream/` | 4 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/plugins/` | 3 | [UI与扩展设计 — 插件系统](../UI与扩展设计/UI与扩展设计-插件系统.md) | ✅ 已覆盖 |
| `services/PromptSuggestion/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/policyLimits/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/tips/` | 3 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/analytics/` | 8 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/voice*` | 3 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/settingsSync/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `services/bootstrap/` | 1 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `bridge/` | 32 | [基础设施设计 — IDE桥接](../基础设施设计/基础设施设计-IDE桥接.md) | ✅ 已覆盖 |
| `tasks/` | 14 | [基础设施设计 — 后台任务管理](../基础设施设计/基础设施设计-后台任务管理.md) | ✅ 已覆盖 |
| `state/` | 6 | [基础设施设计 — 状态管理](../基础设施设计/基础设施设计-状态管理.md) | ✅ 已覆盖 |
| `skills/` | 50 | [UI与扩展设计 — 技能系统](../UI与扩展设计/UI与扩展设计-技能系统.md) | ✅ 已覆盖 |
| `plugins/` | 2 | [UI与扩展设计 — 插件系统](../UI与扩展设计/UI与扩展设计-插件系统.md) | ✅ 已覆盖 |
| `coordinator/` | 2 | [核心模块设计 — 多代理协调器 (Coordinator)](../核心模块设计/核心模块设计-多代理协调.md) | ✅ 已覆盖 |
| `assistant/` | 5 | [核心模块设计 — 多代理协调器 (Coordinator)](../核心模块设计/核心模块设计-多代理协调.md) | ↗️ 归属 |
| `context/` | 9 | [基础设施设计 — 状态管理](../基础设施设计/基础设施设计-状态管理.md) | ↗️ 归属 |
| `hooks/` | 104 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `components/` | 400 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `ink/` | 98 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `ink.ts` | 1 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `keybindings/` | 14 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `constants/` | 22 | [总体概述与技术选型](总体概述与技术选型.md) / 各子模块引用 | ↗️ 归属 |
| `utils/` | 577 | 各模块与基础设施文档的公共支撑 | ↗️ 归属 |
| `types/` | 12 | 各模块与基础设施文档的公共支撑 | ↗️ 归属 |
| `remote/` | 4 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `daemon/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `proactive/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | ↗️ 归属 |
| `server/` | 11 | [基础设施设计 — 其他基础设施子系统](reference/解决方案结构说明.md) | ↗️ 归属 |
| `vim/` | 5 | [UI与扩展设计 — Terminal-Gui 终端UI](../UI与扩展设计/UI与扩展设计-Terminal-Gui终端UI.md) | ↗️ 归属 |
| `memdir/` | 9 | [服务子系统设计 — 会话记忆与上下文](../服务子系统设计/服务子系统设计-会话记忆与上下文.md) | ↗️ 归属 |
| `migrations/` | 11 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `bootstrap/` | 1 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `buddy/` | 6 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `cli/` | 21 | [核心模块设计 — CLI启动与解析](../核心模块设计/核心模块设计-CLI启动与解析.md) | ↗️ 归属 |
| `query/` | 4 | [核心模块设计 — 查询引擎 (QueryEngine)](../核心模块设计/核心模块设计-查询引擎-QueryEngine.md) | ↗️ 归属 |
| `self-hosted-runner/` | 1 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `ssh/` | 1 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `native-ts/` | 4 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `upstreamproxy/` | 2 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `environment-runner/` | 1 | [服务子系统设计 — 其他服务子系统](../服务子系统设计/服务子系统设计-其他服务子系统.md) | 📋 空目录/stub |
| `jobs/` | 1 | [基础设施设计 — 后台任务管理](../基础设施设计/基础设施设计-后台任务管理.md) | ↗️ 归属 |
| `moreright/` | 1 | [UI与扩展设计 — 插件系统](../UI与扩展设计/UI与扩展设计-插件系统.md) | 📋 空目录/stub |

### 备注

- `services/*` 采用“核心子系统 + 其他服务子系统”组合覆盖，避免为每个轻量子目录单独出文档。
- `constants/`、`types/`、`utils/` 属于横切支撑层，通常作为被引用内容而非独立模块文档。
- `migrations/`、`bootstrap/`、`buddy/`、`daemon/`、`proactive/`、`remote/` 等目录在当前重写文档体系中主要作为其他模块的实现细节归属，不单独展开。

---

## 参考文档

| 文档 | 内容 |
|------|------|
| [.NET 10 平台介绍](reference/.NET-10-平台介绍.md) | AOT、C# 13、核心 API 特性 |
| [技术栈映射说明](reference/技术栈映射说明.md) | TS → .NET 完整映射 + NuGet 清单 |
| [解决方案结构说明](reference/解决方案结构说明.md) | 17 个项目职责与依赖关系 |
| [MCP SDK 实现](reference/mcp-sdk-implement.md) | 自研 MCP SDK 协议与传输层设计 |