235 lines
8.2 KiB
Markdown
235 lines
8.2 KiB
Markdown
# 迁移路线图
|
||
|
||
> 所属项目: free-code .NET 10 重写
|
||
> 文档类型: 规划设计
|
||
> 来源章节: DESIGN-NET10-PART3.md § 24
|
||
> 上级文档: [测试与构建总览](测试与构建.md)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
从 TypeScript/Bun 到 .NET 10 的完整重写分 12 个阶段、35 个工作周推进，设置 8 个里程碑节点作为质量检查点。第 36-37 周为缓冲期和文档收尾，实际总工期约 37 周。
|
||
|
||
路线图遵循"先主路径、后完整功能、最后质量和发布"的顺序，确保每个里程碑都有可运行的产物，而不是等到全部完成才能验证。
|
||
|
||
---
|
||
|
||
## 24.1 35 周详细规划
|
||
|
||
### Phase 1: 基础框架（Week 1-4）
|
||
|
||
```
|
||
Phase 1: 基础框架 (Week 1-4)
|
||
├── Week 1: 解决方案结构 + Directory.Build.props + 所有 17 个项目创建
|
||
├── Week 2: DI 容器 + 核心接口 (ITool, ICommand, IApiProvider, IQueryEngine)
|
||
├── Week 3: System.CommandLine CLI 解析 + QuickPathHandler
|
||
├── Week 4: AppState record + AppStateStore + FeatureFlags
|
||
└── 里程碑 M1: dotnet run 输出版本号
|
||
```
|
||
|
||
**目标**: 建立可编译的解决方案骨架，所有接口定义就位，最基础的 CLI 入口可以运行。
|
||
|
||
---
|
||
|
||
### Phase 2: 核心引擎（Week 5-8）
|
||
|
||
```
|
||
Phase 2: 核心引擎 (Week 5-8)
|
||
├── Week 5: QueryEngine 流式循环 + Message 类型
|
||
├── Week 6: SystemPromptBuilder (6段构建)
|
||
├── Week 7: ToolBase<TInput,TOutput> + FluentValidation
|
||
├── Week 8: ToolRegistry + CommandRegistry 注册
|
||
└── 里程碑 M2: 一次性 prompt 模式工作 (-p)
|
||
```
|
||
|
||
**目标**: 一次性模式（`-p "prompt"`）可以向 API 发送请求并接收流式响应，不需要完整 UI。
|
||
|
||
---
|
||
|
||
### Phase 3: API 提供商（Week 9-11）
|
||
|
||
```
|
||
Phase 3: API 提供商 (Week 9-11)
|
||
├── Week 9: AnthropicProvider SSE 解析
|
||
├── Week 10: CodexProvider 消息格式适配
|
||
├── Week 11: BedrockProvider + VertexProvider + FoundryProvider
|
||
└── 里程碑: 所有 5 个提供商路由工作
|
||
```
|
||
|
||
**目标**: 环境变量切换任意一个提供商都能正常处理流式响应。
|
||
|
||
---
|
||
|
||
### Phase 4: 核心工具（Week 12-15）
|
||
|
||
```
|
||
Phase 4: 核心工具 (Week 12-15)
|
||
├── Week 12: FileReadTool + FileEditTool + FileWriteTool
|
||
├── Week 13: BashTool + GlobTool + GrepTool
|
||
├── Week 14: AgentTool + SkillTool
|
||
├── Week 15: WebFetch + WebSearch + TodoWrite + AskUser + 其他
|
||
└── 里程碑 M3: Bash/Read/Edit 工具链可用
|
||
```
|
||
|
||
**目标**: 模型可以调用文件操作和 Shell 命令工具，完成基本编码任务。
|
||
|
||
---
|
||
|
||
### Phase 5: 命令实现（Week 16-18）
|
||
|
||
```
|
||
Phase 5: 命令实现 (Week 16-18)
|
||
├── Week 16: 核心 30 个命令 (help, exit, clear, config, model, login...)
|
||
├── Week 17: 功能命令 25 个 (mcp, plugins, skills, tasks...)
|
||
├── Week 18: 条件 + 内部命令 15 个
|
||
└── 里程碑: 所有 70+ 命令注册
|
||
```
|
||
|
||
**目标**: 全部斜杠命令可以被解析和分发，核心命令（`/help`、`/model`、`/login`）有完整实现。
|
||
|
||
---
|
||
|
||
### Phase 6: 终端 UI（Week 19-22）
|
||
|
||
```
|
||
Phase 6: 终端 UI (Week 19-22)
|
||
├── Week 19: Terminal.Gui App + REPLScreen 基本布局
|
||
├── Week 20: PromptInput + MessageList + 流式渲染
|
||
├── Week 21: PermissionDialog + ToolUseDisplay + StatusBar
|
||
├── Week 22: Theme + Keybindings + CompanionSprite
|
||
└── 里程碑 M4: 交互式 REPL 可用
|
||
```
|
||
|
||
**目标**: 用户可以在终端中交互式输入 prompt 并看到流式输出，工具调用有权限确认界面。
|
||
|
||
---
|
||
|
||
### Phase 7: 基础设施（Week 23-25）
|
||
|
||
```
|
||
Phase 7: 基础设施 (Week 23-25)
|
||
├── Week 23: MCP SDK (传输层 + 客户端 + McpClientManager)
|
||
├── Week 24: LSP (LspClientManager + LspServerInstance)
|
||
├── Week 25: OAuth + Bridge + BackgroundTasks + RateLimit
|
||
└── 里程碑 M5: 功能对等原始项目
|
||
```
|
||
|
||
**目标**: MCP 服务器可以连接并提供工具，LSP 集成工作，Bridge 模式可以与 IDE 通信，这是与原始 TypeScript 项目功能对等的节点。
|
||
|
||
---
|
||
|
||
### Phase 8: 高级服务（Week 26-28）
|
||
|
||
```
|
||
Phase 8: 高级服务 (Week 26-28)
|
||
├── Week 26: SessionMemory + AutoDream
|
||
├── Week 27: TeamMemorySync + RemoteSessions
|
||
├── Week 28: Voice + Notifications + Companion
|
||
└── 里程碑: 所有高级功能工作
|
||
```
|
||
|
||
**目标**: 会话记忆、团队记忆同步、语音输入、Companion 精灵等扩展功能全部就位。
|
||
|
||
---
|
||
|
||
### Phase 9: 扩展系统（Week 29-30）
|
||
|
||
```
|
||
Phase 9: 扩展系统 (Week 29-30)
|
||
├── Week 29: SkillLoader + frontmatter 解析
|
||
├── Week 30: PluginManager + AssemblyLoadContext + Marketplace
|
||
└── 里程碑 M6: 可加载外部技能和插件
|
||
```
|
||
|
||
**目标**: 外部 `.md` 技能文件和 `.dll` 插件可以在运行时动态加载，插件市场接口就位。
|
||
|
||
---
|
||
|
||
### Phase 10: 测试（Week 31-33）
|
||
|
||
```
|
||
Phase 10: 测试 (Week 31-33)
|
||
├── Week 31: 120 单元测试 (工具/引擎/提供商/服务)
|
||
├── Week 32: 60 集成测试 (MCP/LSP/Bridge/管道)
|
||
├── Week 33: 20 E2E 测试 + 性能基准
|
||
└── 里程碑 M7: 核心路径 80%+ 覆盖率
|
||
```
|
||
|
||
**目标**: 三层测试套件全部通过，覆盖率报告显示核心路径 80% 以上，性能基准记录在案。
|
||
|
||
---
|
||
|
||
### Phase 11: 构建发布（Week 34-35）
|
||
|
||
```
|
||
Phase 11: 构建发布 (Week 34-35)
|
||
├── Week 34: AOT 优化 + Source Generator + 5 平台构建
|
||
├── Week 35: 安装脚本 + CI/CD + 文档
|
||
└── 里程碑 M8: 一键安装脚本工作
|
||
```
|
||
|
||
**目标**: `install.sh` 可以在 macOS 和 Linux 上一键安装，CI/CD 管道自动构建和发布。
|
||
|
||
---
|
||
|
||
### Phase 12: 文档（Week 36-37，缓冲期）
|
||
|
||
```
|
||
Phase 12: 文档 (Week 36-37, buffer)
|
||
├── README + 架构文档 + API 文档
|
||
└── 最终验收
|
||
```
|
||
|
||
**目标**: 文档完整，所有设计文档更新为最终实现，项目可以公开发布。
|
||
|
||
---
|
||
|
||
## 24.2 里程碑表
|
||
|
||
| 里程碑 | 完成周 | 验收标准 | 依赖 |
|
||
|--------|--------|---------|------|
|
||
| M1 | Week 4 | `dotnet run` 输出版本号，无运行时错误 | Phase 1 完成 |
|
||
| M2 | Week 8 | `-p "hello"` 返回 API 响应，流式输出到终端 | Phase 2 完成 |
|
||
| M3 | Week 15 | 模型成功调用 Bash/Read/Edit 工具完成简单任务 | Phase 4 完成 |
|
||
| M4 | Week 22 | 交互式 REPL 可用，权限确认 UI 正常 | Phase 6 完成 |
|
||
| M5 | Week 25 | 功能对等原始 TypeScript 项目，MCP/LSP/Bridge 工作 | Phase 7 完成 |
|
||
| M6 | Week 30 | 可加载外部技能文件和插件 dll | Phase 9 完成 |
|
||
| M7 | Week 33 | 测试覆盖率 >= 80%，全部测试通过 | Phase 10 完成 |
|
||
| M8 | Week 35 | 一键安装脚本在 macOS/Linux 工作，CI 绿灯 | Phase 11 完成 |
|
||
|
||
---
|
||
|
||
## 24.3 风险评估
|
||
|
||
| 风险 | 概率 | 影响 | 缓解策略 |
|
||
|------|------|------|---------|
|
||
| MCP SDK 无成熟 .NET 库 | 高 | 高 | Phase 7 前期自研传输层，参考官方 TypeScript SDK 实现 |
|
||
| Terminal.Gui v2 组件不足 | 中 | 中 | Spectre.Console 补充缺失组件，必要时自定义 View |
|
||
| AOT 反射限制 | 中 | 高 | Source Generator 生成序列化代码，启用 `EnableAotAnalyzer` 提前暴露问题 |
|
||
| 插件 ALC 卸载内存泄漏 | 低 | 中 | 定期监控内存，提供强制 GC 入口，文档说明已知限制 |
|
||
| LSP OmniSharp 库兼容性 | 中 | 中 | StreamJsonRpc 作为备选，最坏情况自实现 JSON-RPC 层 |
|
||
| StreamJsonRpc AOT 兼容 | 中 | 中 | 评估期间同时准备自定义 JSON-RPC 实现，Phase 7 初期决策 |
|
||
|
||
---
|
||
|
||
## 24.4 并行开发策略
|
||
|
||
各阶段内部的周可以部分并行推进。具体来说:
|
||
|
||
- Phase 3 的三家次要提供商（Bedrock、Vertex、Foundry）可以分配给不同开发者同时实现
|
||
- Phase 4 中文件操作工具（Week 12）和 Shell 工具（Week 13）无依赖关系，可并行
|
||
- Phase 10 的单元测试可以在 Phase 7-9 期间随功能完成同步编写，不必等到 Phase 10 才开始
|
||
|
||
单人开发时按串行顺序执行，团队协作时按上述拆分并行。
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
- [测试与构建总览](测试与构建.md)
|
||
- [测试方案设计](测试与构建-测试方案设计.md)
|
||
- [构建与部署](测试与构建-构建与部署.md)
|
||
- [原始代码映射 — 测试与构建](reference/原始代码映射-测试与构建.md)
|
||
- [总体概述与技术选型](../总体概述与技术选型/总体概述与技术选型.md)
|