253 lines
19 KiB
Markdown
253 lines
19 KiB
Markdown
# 总体概述与技术选型
|
||
|
||
> **文档版本**: 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 协议与传输层设计 |
|