总体概述与技术选型

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

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

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

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

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

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

备注

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

参考文档

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

19 KiB Raw Blame History Unescape Escape