116 lines
7.7 KiB
Markdown
116 lines
7.7 KiB
Markdown
# 原始代码映射 — 核心模块
|
||
|
||
> 所属项目: free-code .NET 10 重写
|
||
> 文档类型: 参考映射表
|
||
> 上级文档: [核心模块设计总览](../核心模块设计.md)
|
||
|
||
---
|
||
|
||
## 说明
|
||
|
||
本文档建立 .NET 10 类型与原始 TypeScript 源文件之间的映射关系。每一行说明对应 .NET 类型重写了哪个 TS 文件的哪部分逻辑，以及重写时做出的关键设计决策。
|
||
|
||
---
|
||
|
||
## 核心模块映射表
|
||
|
||
### 启动与 CLI 解析
|
||
|
||
| .NET 类型 | 原始 TS 文件 | 对应逻辑 | 设计变化 |
|
||
|-----------|-------------|---------|---------|
|
||
| `Program` | `../../../src/entrypoints/cli.tsx` | 模块顶层的入口逻辑和条件分支 | 拆分为四阶段，引入 `IHostBuilder` 管理生命周期 |
|
||
| `QuickPathHandler` | `../../../src/entrypoints/cli.tsx` | 文件顶部散布的 `process.argv.includes()` 快速路径检查 | 集中到静态类，Phase 1 执行，无 DI 开销 |
|
||
| `CliCommandBuilder` | `../../../src/entrypoints/cli.tsx` | Commander.js 的 `program.option(...).action(...)` 配置 | 映射到 `System.CommandLine` 的 `RootCommand` + `Option<T>` |
|
||
| `OneShotMode` | `../../../src/entrypoints/cli.tsx` | `-p` 参数触发的非交互式执行路径 | 独立类，与 REPL 模式分离 |
|
||
| `REPLMode` | `../../../src/screens/REPL.tsx` | React/Ink 交互式 UI 主循环 | 替换为基于 Spectre.Console 或原生终端 API 的 .NET UI |
|
||
|
||
---
|
||
|
||
### 查询引擎
|
||
|
||
| .NET 类型 | 原始 TS 文件 | 对应逻辑 | 设计变化 |
|
||
|-----------|-------------|---------|---------|
|
||
| `IQueryEngine` | `../../../src/QueryEngine.ts` | 隐式的模块导出函数签名 | 显式接口，便于测试替换 |
|
||
| `QueryEngine` | `../../../src/QueryEngine.ts` | 核心消息循环（约 800 行）| 提取 System Prompt 构建为独立类；`IAsyncEnumerable` 替换回调式流 |
|
||
| `SubmitMessageOptions` | `../../../src/QueryEngine.ts` | `query()` 函数的参数对象 | `record` 类型，不可变，编译期类型安全 |
|
||
| `SystemPromptBuilder` | `../../../src/QueryEngine.ts` | 内联的 `getSystemPrompt()` 函数（约 200 行）| 提取为独立接口 `IPromptBuilder`，支持 DI 替换 |
|
||
| `SDKMessage`（联合类型）| `../../../src/types/message.ts` | `SDKMessage` TypeScript 联合类型 | C# discriminated union 通过继承体系实现 |
|
||
| `TokenUsage` | `../../../src/QueryEngine.ts` | 内联的 token 统计逻辑 | 独立 record，从 API 响应头提取 |
|
||
|
||
---
|
||
|
||
### 工具系统
|
||
|
||
| .NET 类型 | 原始 TS 文件 | 对应逻辑 | 设计变化 |
|
||
|-----------|-------------|---------|---------|
|
||
| `ITool` | `../../../src/Tool.ts` | 工具基础接口定义（约 40 行）| 拆分为非泛型 `ITool` 和泛型 `ITool<TInput,TOutput>` 两层 |
|
||
| `ITool<TInput,TOutput>` | `../../../src/Tool.ts` | 工具执行方法签名 | 泛型化，输入/输出类型在编译期检查 |
|
||
| `ToolBase<TInput,TOutput>` | `../../../src/Tool.ts` | 工具基类的默认实现 | 抽象类，集成 FluentValidation 验证点 |
|
||
| `ToolExecutionContext` | `../../../src/Tool.ts` | 工具执行时接收的上下文对象 | `record` 类型，不可变，避免工具意外修改上下文 |
|
||
| `ToolCategory` | `../../../src/Tool.ts` | 工具分类枚举 | 直接映射，枚举成员一一对应 |
|
||
| `BashTool` | `../../../src/tools/BashTool.tsx` | Bash 工具完整实现 | `child_process.spawn` → `Process`；`Promise.race` → `.WaitAsync(timeout)` |
|
||
| `BashToolInput` | `../../../src/tools/BashTool.tsx` | Bash 工具输入类型 | TypeScript 接口 → C# `record`，不可变 |
|
||
| `BashToolOutput` | `../../../src/tools/BashTool.tsx` | Bash 工具输出类型 | 同上 |
|
||
| `ToolRegistry` | `../../../src/tools.ts` | `getTools()` 函数和工具数组 | 注册表类，懒加载缓存，稳定排序保证 prompt cache |
|
||
| `CommandClassifier` | `../../../src/tools/BashTool.tsx` | 命令只读性判断逻辑 | 提取为独立工具类 |
|
||
|
||
---
|
||
|
||
### 命令系统
|
||
|
||
| .NET 类型 | 原始 TS 文件 | 对应逻辑 | 设计变化 |
|
||
|-----------|-------------|---------|---------|
|
||
| `ICommand` | `../../../src/commands.ts` | 命令对象的隐式接口约定 | 显式接口，`CommandCategory` 和 `CommandAvailability` 枚举化 |
|
||
| `CommandContext` | `../../../src/commands.ts` | 命令执行时传入的上下文 | 独立 record，包含会话状态和 UI 接口 |
|
||
| `CommandResult` | `../../../src/commands.ts` | 命令执行返回值 | `record(bool Success, string? Output)` |
|
||
| `CommandRegistry` | `../../../src/commands.ts` | `COMMAND_LIST` 数组及导出函数 | 注册表类，按认证状态和 feature flag 动态过滤 |
|
||
| `CommandCategory` | `../../../src/commands.ts` | `type: 'prompt' \| 'local' \| 'local-jsx'` | C# `enum`，JSX 对话框模式映射为 `LocalDialog` |
|
||
| `CommandAvailability` | `../../../src/commands.ts` | `availability: string` 字段 | C# `enum`，强类型替换字符串约定 |
|
||
| 各具体命令类 | `../../../src/commands/` | 各 `*Command.ts` 文件 | 一一对应，每个文件对应一个实现类 |
|
||
|
||
---
|
||
|
||
### API 多提供商路由
|
||
|
||
| .NET 类型 | 原始 TS 文件 | 对应逻辑 | 设计变化 |
|
||
|-----------|-------------|---------|---------|
|
||
| `IApiProvider` | `../../../src/services/api/` | 各提供商模块的导出函数签名 | 统一抽象接口，所有提供商实现同一接口 |
|
||
| `ApiProviderRouter` | `../../../src/services/api/` | `process.env` 条件判断选择客户端 | 路由器类，构造时确定提供商，运行时不再判断 |
|
||
| `ApiProviderType` | `../../../src/services/api/` | 字符串常量区分提供商 | C# `enum`，编译期安全 |
|
||
| `ApiRequest` | `../../../src/services/api/` | API 调用参数对象 | `record`，不可变 |
|
||
| `AnthropicProvider` | `../../../src/services/api/claude.ts` | Anthropic SDK 流式调用（约 2000 行）| 移除 SDK 依赖，直接 `HttpClient` + 手动 SSE 解析 |
|
||
| `CodexProvider` | `../../../src/services/api/` | OpenAI Codex 客户端 | 对应原始 Codex fetch adapter |
|
||
| `BedrockProvider` | `../../../src/services/api/` | AWS Bedrock 客户端 | 使用 AWS SDK for .NET |
|
||
| `VertexProvider` | `../../../src/services/api/` | Google Vertex 客户端 | 使用 Google Cloud SDK for .NET |
|
||
| `FoundryProvider` | `../../../src/services/api/` | Anthropic Foundry 客户端 | 基于 `AnthropicProvider` 适配自定义端点 |
|
||
|
||
---
|
||
|
||
## 未直接映射的原始文件
|
||
|
||
以下 `../../../src/` 文件的逻辑分散到了基础设施设计或服务子系统文档中：
|
||
|
||
| 原始文件 | 重写位置 |
|
||
|----------|---------|
|
||
| `../../../src/state/` | [基础设施设计 — 状态管理](../../基础设施设计/基础设施设计-状态管理.md) |
|
||
| `../../../src/services/mcp*` | [基础设施设计 — MCP 协议集成](../../基础设施设计/基础设施设计-MCP协议集成.md) |
|
||
| `../../../src/services/oauth/` | [服务子系统设计 — 认证](../../服务子系统设计/) |
|
||
| `../../../src/skills/` | [服务子系统设计 — 技能系统](../../服务子系统设计/) |
|
||
| `../../../src/plugins/` | [服务子系统设计 — 插件系统](../../服务子系统设计/) |
|
||
| `../../../src/bridge/` | [服务子系统设计 — IDE 桥接](../../服务子系统设计/) |
|
||
| `../../../src/tasks/` | [服务子系统设计 — 后台任务](../../服务子系统设计/) |
|
||
| `../../../src/voice/` | [服务子系统设计 — 语音输入](../../服务子系统设计/) |
|
||
| `../../../src/components/` | [UI 与扩展设计](../../UI与扩展设计/) |
|
||
| `../../../src/hooks/` | [UI 与扩展设计](../../UI与扩展设计/) |
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
- [核心模块设计总览](../核心模块设计.md)
|
||
- [CLI 启动与解析](../核心模块设计-CLI启动与解析.md)
|
||
- [查询引擎 (QueryEngine)](../核心模块设计-查询引擎-QueryEngine.md)
|
||
- [工具系统](../核心模块设计-工具系统.md)
|
||
- [命令系统](../核心模块设计-命令系统.md)
|
||
- [API 多提供商路由](../核心模块设计-API提供商路由.md)
|