# free-code .NET 10 迁移 — 代码审查与架构分析报告

> **审查版本**: 0.1.0 (初始迁移)  
> **审查日期**: 2026-04-06  
> **审查范围**: `src/` 目录下全部 16 个项目、~200 个 .cs 文件  
> **对照基准**: 原始 TypeScript 项目 v2.1.87 (512,834 行代码)  
> **审查人角色**: 多语言编码架构师，以 .NET 平台最佳实践为评审标准

---

## 目录

- [一、总体评估](#一总体评估)
- [二、架构设计分析](#二架构设计分析)
- [三、关键设计问题 (Critical/High)](#三关键设计问题-criticalhigh)
- [四、实现细节问题 (Medium/Low)](#四实现细节问题-mediumlow)
- [五、性能优化建议](#五性能优化建议)
- [六、.NET 惯用法改进](#六net-惯用法改进)
- [七、功能对等性分析](#七功能对等性分析)
- [八、优化路线图](#八优化路线图)
- [九、总结](#九总结)

---

## 一、总体评估

### 综合评分：6.5 / 10

| 维度 | 评分 | 说明 |
|------|------|------|
| **架构分层** | 7/10 | 五层架构清晰，但项目拆分过细 |
| **接口设计** | 5/10 | 接口驱动思路正确，但存在弱类型(`object`)和过度抽象 |
| **DI 实践** | 7/10 | 构造函数注入完整，但注册分散、顺序敏感 |
| **异步模式** | 7/10 | IAsyncEnumerable + CancellationToken 使用得当 |
| **.NET 惯用法** | 5/10 | 未充分利用 C# 13/.NET 10 特性，部分代码像"翻译的 TypeScript" |
| **性能考量** | 4/10 | JSON 处理冗余分配、HttpClient 管理缺失、进程创建频繁 |
| **测试覆盖** | 6/10 | 9 个测试项目结构完整，但需验证实际覆盖率 |
| **功能对等** | 5/10 | 骨架代码完整，但核心特性（compact、PKCE、prompt-cache）缺失 |

### 总体判断

迁移工作完成了 **架构骨架搭建**：16 个项目的分层、核心接口定义、DI 注册管道、查询引擎主循环均已实现。但在以下方面存在显著不足：

1. **设计问题**: ToolRegistry 的 switch 分发、AppStateStore 弱类型、QueryEngine 神类
2. **性能问题**: JSON 序列化的 write→parse→clone 反模式、HttpClient 未池化
3. **功能缺失**: 上下文压缩、OAuth PKCE、prompt-cache 优化、Terminal.Gui 完整 REPL
4. **.NET 化不足**: 大量 `lock(object)` 同步、Console.Error 替代 ILogger、同步方法包装为异步

---

## 二、架构设计分析

### 2.1 当前架构分层

```
┌─────────────────────────────────────────────────────────┐
│                   FreeCode.TerminalUI                    │
│          Terminal.Gui v2 (REPL/Components/Theme)         │
├─────────────────────────────────────────────────────────┤
│  FreeCode (入口)                                         │
│  Program.cs → QuickPathHandler → Host → IAppRunner       │
├─────────────────────────────────────────────────────────┤
│  FreeCode.Engine         │  FreeCode.Commands            │
│  QueryEngine (423行)      │  95+ Command 类               │
│  SystemPromptBuilder      │                               │
├─────────────────────────────────────────────────────────┤
│  FreeCode.Tools           │  FreeCode.Services            │
│  45+ Tool 类               │  Auth/Memory/Voice/...       │
│  ToolRegistry (365行)      │                               │
├─────────────────────────────────────────────────────────┤
│  FreeCode.ApiProviders    │  FreeCode.Mcp  │  FreeCode.Lsp│
│  5 个 LLM Provider         │  自研 MCP SDK  │  LSP Client │
├─────────────────────────────────────────────────────────┤
│  FreeCode.Core (28 接口 / 19 模型 / 18 枚举)             │
│  FreeCode.State (AppState record)                        │
│  FreeCode.Features (FeatureFlags)                        │
│  FreeCode.Skills / FreeCode.Plugins / FreeCode.Tasks     │
│  FreeCode.Bridge                                         │
└─────────────────────────────────────────────────────────┘
```

### 2.2 项目依赖关系（实际）

```
FreeCode.Core ←── 所有项目
    ↑
    ├── FreeCode.Engine (引用 Core)
    ├── FreeCode.ApiProviders (引用 Core)
    ├── FreeCode.Services (引用 Core)
    ├── FreeCode.State (引用 Core)
    ├── FreeCode.Features (引用 Core)
    ├── FreeCode.Tools (引用 Core + Services + Mcp)
    ├── FreeCode.Commands (引用 Core + Engine + State + Skills)
    ├── FreeCode.Mcp (引用 Core)
    ├── FreeCode.Lsp (引用 Core)
    ├── FreeCode.Bridge (引用 Core)
    ├── FreeCode.Skills (引用 Core + Services)
    ├── FreeCode.Plugins (引用 Core)
    ├── FreeCode.Tasks (引用 Core + Services)
    ├── FreeCode.TerminalUI (引用 Core + State)
    └── FreeCode (引用全部 15 个项目)
```

### 2.3 数据流

```
用户输入
  → Program.Main() / QuickPathHandler
  → IAppRunner.RunAsync()
  → IQueryEngine.SubmitMessageAsync(content)
      → IPromptBuilder.BuildAsync()         // 构建 System Prompt
      → IToolRegistry.GetToolsAsync()        // 获取可用工具列表
      → IApiProviderRouter.GetActiveProvider() // 路由到 API 提供商
      → IApiProvider.StreamAsync()           // 流式 LLM 响应
      → while (shouldContinue) { ... }       // 工具调用循环
          → ExecuteToolAsync()               // 执行工具
          → AppendMessage()                  // 追加消息到历史
  → TerminalUI 渲染输出
```

---

## 三、关键设计问题 (Critical/High)

### 问题 3.1 [Critical] ToolRegistry 巨型 switch 分发

**位置**: `src/FreeCode.Tools/ToolRegistry.cs:162-213`

**问题描述**:
`ExecuteToolAsync` 方法包含一个 48 个 case 的 switch 表达式，每添加一个新工具需要同时修改三处：注册列表（GetBaseTools）、switch 表达式、Input/Output DTO 类。这是典型的 Open-Closed 原则违反。

```csharp
// 当前实现 — 每增加一个工具就要改这里
return tool.Name switch
{
    "Agent" => await ExecuteAsync<AgentToolInput, AgentToolOutput>(...),
    "Bash" => await ExecuteAsync<BashToolInput, BashToolOutput>(...),
    "Read" => await ExecuteAsync<FileReadToolInput, string>(...),
    // ... 48 个 case
    _ => ($"Unsupported tool execution for {tool.Name}", true, false)
};
```

**根因**: `ToolBase` 缺少统一的 `ExecuteAsync(JsonElement, ToolExecutionContext, CancellationToken)` 方法，导致 ToolRegistry 必须知道每个工具的具体类型才能调用泛型 `ExecuteAsync<TInput, TOutput>`。

**建议方案**: 在 `ToolBase` 中添加基于 `JsonElement` 的统一执行入口：

```csharp
// 建议方案：ToolBase 添加通用执行方法
public abstract class ToolBase : ITool
{
    // 新增：统一的 JSON 执行入口
    public abstract Task<(string Output, bool IsAllowed, bool ShouldContinue)> ExecuteFromJsonAsync(
        JsonElement input, ToolExecutionContext context, CancellationToken ct);
    
    // 子类实现
    public override Task<(string, bool, bool)> ExecuteFromJsonAsync(
        JsonElement input, ToolExecutionContext context, CancellationToken ct)
    {
        var typedInput = JsonSerializer.Deserialize<BashToolInput>(input.GetRawText())!;
        // ... execute logic
    }
}

// ToolRegistry 简化为：
if (tool is ToolBase toolBase)
{
    return await toolBase.ExecuteFromJsonAsync(input, executionContext, ct);
}
```

---

### 问题 3.2 [Critical] IAppStateStore 弱类型 `object` 接口

**位置**: `src/FreeCode.Core/Interfaces/IAppStateStore.cs` (全部 11 行)

**问题描述**:
核心状态接口使用 `object` 作为状态类型，迫使所有消费者进行强制类型转换。这完全违背了 C# 强类型系统的设计理念。

```csharp
// 当前 — 弱类型
public interface IAppStateStore
{
    object GetState();                                    // 返回 object
    void Update(Func<object, object> updater);             // Func<object, object>
    IDisposable Subscribe(Action<object> listener);        // Action<object>
    event EventHandler<StateChangedEventArgs>? StateChanged;
}
```

**连锁影响**:
- `AppStateStore.cs:33` — 需要 `as AppState ?? throw new InvalidCastException()`
- `ToolRegistry.cs:288-295` — `ResolvePermissionMode` 使用反射 `GetProperty("PermissionMode")`
- 所有状态消费者都需要 `(AppState)store.GetState()` 强转

**建议方案**: 使用泛型接口或直接暴露 AppState：

```csharp
// 方案A：泛型接口
public interface IStateStore<TState> where TState : notnull
{
    TState GetState();
    void Update(Func<TState, TState> updater);
    IDisposable Subscribe(Action<TState> listener);
    event EventHandler<StateChangedEventArgs<TState>>? StateChanged;
}

// 方案B：直接强类型（更简单，推荐）
public interface IAppStateStore
{
    AppState GetState();
    void Update(Func<AppState, AppState> updater);
    IDisposable Subscribe(Action<AppState> listener);
    event EventHandler<StateChangedEventArgs>? StateChanged;
}
```

---

### 问题 3.3 [Critical] QueryEngine 神类 + 构造函数注入 Func 委托

**位置**: `src/FreeCode.Engine/QueryEngine.cs` (全文 423 行)

**问题描述**:
1. **构造函数接收 9 个参数**（第 12-20 行），其中 `toolExecutor` 是一个复杂的 `Func<...>` 委托，实际上是 `ToolRegistry.ExecuteToolAsync` 方法的引用。这破坏了依赖注入的原则——应该注入接口而非具体方法的委托。
2. 单一类承担了：流式响应处理、工具执行调度、消息历史管理、JSON 序列化、Token 估算、CancellationToken 生命周期管理。

```csharp
// QueryEngine 构造函数（第 12-20 行）
public sealed class QueryEngine(
    IApiProviderRouter apiProviderRouter,
    IToolRegistry toolRegistry,
    IPermissionEngine permissionEngine,
    IPromptBuilder promptBuilder,
    ISessionMemoryService sessionMemoryService,
    IFeatureFlagService featureFlagService,
    Func<string, JsonElement, IPermissionEngine, ToolPermissionContext?, CancellationToken, 
         Task<(string Output, bool IsAllowed, bool ShouldContinue)>>? toolExecutor,  // ← 这是什么？
    ILogger<QueryEngine> logger) : IQueryEngine
```

**建议方案**: 将职责拆分为：

```csharp
// 1. IToolExecutor — 工具执行职责
public interface IToolExecutor
{
    Task<(string Output, bool IsAllowed, bool ShouldContinue)> ExecuteAsync(
        string toolName, JsonElement input, ToolPermissionContext? context, CancellationToken ct);
}

// 2. IMessageStore — 消息管理职责
public interface IMessageStore
{
    void Append(Message message);
    IReadOnlyList<Message> GetAll();
}

// 3. IJsonSerializer — JSON 序列化职责（可选）
public interface IApiRequestSerializer
{
    JsonElement SerializeMessages(IReadOnlyList<Message> messages);
    JsonElement SerializeTools(IReadOnlyList<ITool> tools);
}
```

---

### 问题 3.4 [High] AppState 巨型 Record — 单体状态

**位置**: `src/FreeCode.State/AppState.cs` (49 个属性)

**问题描述**:
单个 `AppState` record 包含 49 个属性，涵盖配置、权限、任务、MCP、插件、远程、UI、Agent 等所有领域。任何属性变更都会触发整个 record 的 `with {}` 重建，所有订阅者都会收到通知，即使它们只关心某个特定属性。

```csharp
public sealed record AppState
{
    public SettingsJson Settings { get; init; }          // 配置
    public PermissionMode PermissionMode { get; init; }  // 权限
    public IReadOnlyDictionary<string, BackgroundTask> Tasks { get; init; } // 任务
    public McpState Mcp { get; init; }                    // MCP
    public PluginState Plugins { get; init; }             // 插件
    public RemoteConnectionStatus RemoteConnectionStatus { get; init; } // 远程
    public Companion? Companion { get; init; }            // 同伴
    public NotificationState Notifications { get; init; } // 通知
    // ... 41 more properties
}
```

**建议方案**: 分片状态管理

```csharp
// 按领域拆分状态切片
public sealed record AppState
{
    public ConversationState Conversation { get; init; } = new();
    public McpState Mcp { get; init; } = McpState.Empty;
    public TaskState Tasks { get; init; } = new();
    public UiState Ui { get; init; } = new();
    public PluginState Plugins { get; init; } = PluginState.Empty;
}

// 支持选择性订阅
public interface IStateSlice<T>
{
    T Value { get; }
    IObservable<T> Observe();
}
```

---

### 问题 3.5 [High] PermissionEngine 从 IServiceProvider 获取工具实例

**位置**: `src/FreeCode.Services/PermissionEngine.cs:13`

```csharp
public Task<PermissionResult> CheckAsync(string toolName, object input, ToolExecutionContext context)
{
    var tool = context.Services.GetService(typeof(ITool)) as ITool;
    var isReadOnly = tool?.IsReadOnly(input) ?? false;
    // ...
}
```

**问题**:
1. `context.Services` 是 `ToolRegistry.ToolExecutionServiceProvider`（第 297-301 行），一个自定义 IServiceProvider，其唯一目的是返回当前工具实例。这个设计极其不直观。
2. `ITool` 是一个通用接口，`GetService(typeof(ITool))` 语义上应该返回任意工具实例，但实际返回的是"当前正在执行的工具"。
3. 如果 `ToolExecutionServiceProvider` 未正确设置，会静默返回 null 并 fallback 到 `isReadOnly = false`。

**建议**: 直接在 `ToolExecutionContext` 中携带 `IsReadOnly` 信息：

```csharp
public record ToolExecutionContext(
    string WorkingDirectory,
    PermissionMode PermissionMode,
    bool IsToolReadOnly,  // ← 直接传入
    // ...
)
```

---

### 问题 3.6 [High] ToolBase 静态 JsonDocument 内存泄漏

**位置**: `src/FreeCode.Tools/ToolBase.cs:9`

```csharp
public abstract class ToolBase : ITool
{
    private static readonly JsonElement EmptySchema = JsonDocument.Parse("{}").RootElement.Clone();
    // ...
    public virtual JsonElement GetInputSchema() => EmptySchema;
}
```

**问题**: `JsonDocument.Parse("{}")` 创建的 `JsonDocument` 永远不会被 Dispose（因为只保留了 `RootElement.Clone()` 的引用）。虽然在这个特定场景下影响很小（只有一个 `"{}"` 对象），但这违反了 `JsonDocument` 的使用规范——应该保持 `JsonDocument` 存活直到 `JsonElement` 不再使用。

**建议方案**:

```csharp
public abstract class ToolBase : ITool
{
    private static readonly JsonObject EmptySchemaNode = new JsonObject();
    
    // 方案A：使用 ImmutableByteArray
    private static readonly byte[] EmptySchemaBytes = "{}"u8.ToArray();
    public virtual JsonElement GetInputSchema()
    {
        using var doc = JsonDocument.Parse(EmptySchemaBytes);
        return doc.RootElement.Clone();
    }
    
    // 方案B（更好）：改用 JsonNode API (.NET 10 推荐)
    public virtual JsonNode? GetInputSchema() => null;
}
```

---

## 四、实现细节问题 (Medium/Low)

### 问题 4.1 [Medium] JSON "write → parse → clone" 反模式

**位置**:
- `src/FreeCode.Engine/QueryEngine.cs:263-285` (BuildApiToolsJsonAsync)
- `src/FreeCode.Engine/QueryEngine.cs:287-339` (BuildApiMessagesJson)
- `src/FreeCode.Engine/QueryEngine.cs:361-397` (BuildAssistantContent)

**问题描述**:
三个方法都使用相同模式：`ArrayBufferWriter → Utf8JsonWriter → JsonDocument.Parse(自己写的内容) → RootElement.Clone()`。这相当于把数据序列化为 JSON 字节后，再反序列化回来，最后再克隆一次。

```csharp
// 当前：write → parse → clone（3次内存分配）
var buffer = new ArrayBufferWriter<byte>(4096);
using (var writer = new Utf8JsonWriter(buffer)) { /* write */ writer.Flush(); }
using var doc = JsonDocument.Parse(buffer.WrittenMemory);  // 分配1：parse
return doc.RootElement.Clone();                             // 分配2：clone
```

**建议**: 既然最终结果是 `JsonElement`（不可变），可以直接保留 `ArrayBufferWriter` 的字节并从中创建 `JsonElement`，或改用 `JsonNode` API 避免 Clone：

```csharp
// 优化：直接返回写入的字节
private static JsonElement BuildApiToolsJson(IReadOnlyList<ITool> tools)
{
    var buffer = new ArrayBufferWriter<byte>(4096);
    using (var writer = new Utf8JsonWriter(buffer))
    {
        // ... write
        writer.Flush();
    }
    // 使用 JsonDocument 但不 Clone — 让 JsonDocument 持有 buffer 的副本
    var doc = JsonDocument.Parse(buffer.WrittenSpan);
    return doc.RootElement; // JsonDocument 本身持有数据
}
```

---

### 问题 4.2 [Medium] EstimateTokens 重复实现

**位置**:
- `src/FreeCode.Engine/QueryEngine.cs:415-422`
- `src/FreeCode.Services/SessionMemoryService.cs:148-155`

```csharp
// QueryEngine.cs:415
private static int EstimateTokens(object? content)
    => content switch
    {
        null => 0,
        string text => Math.Max(1, text.Length / 4),
        JsonElement jsonElement => Math.Max(1, jsonElement.ToString().Length / 4),
        _ => Math.Max(1, (content.ToString()?.Length ?? 0) / 4),
    };

// SessionMemoryService.cs:148 — 几乎完全相同
private static int EstimateTokens(object? content)
    => content switch
    {
        null => 0,
        string text => Math.Max(1, text.Length / 4),
        JsonElement element => Math.Max(1, element.ToString().Length / 4),
        _ => Math.Max(1, (content.ToString()?.Length ?? 0) / 4),
    };
```

**建议**: 提取到 `FreeCode.Core` 中的静态工具类：

```csharp
// src/FreeCode.Core/Utilities/TokenEstimator.cs
public static class TokenEstimator
{
    public static int Estimate(object? content) => content switch
    {
        null => 0,
        string text => Math.Max(1, text.Length / 4),
        JsonElement json => Math.Max(1, json.ToString().Length / 4),
        _ => Math.Max(1, (content.ToString()?.Length ?? 0) / 4),
    };
    
    public static int EstimateTotal(IReadOnlyList<Message> messages)
    {
        var tokens = 0;
        foreach (var msg in messages)
        {
            tokens += Estimate(msg.Content);
            tokens += string.IsNullOrWhiteSpace(msg.ToolUseId) ? 0 : 8;
            tokens += string.IsNullOrWhiteSpace(msg.ToolName) ? 0 : 4;
        }
        return tokens;
    }
}
```

---

### 问题 4.3 [Medium] AnthropicProvider HttpClient 未通过 DI 管理

**位置**: `src/FreeCode.ApiProviders/AnthropicProvider.cs:18-25`

```csharp
public AnthropicProvider(HttpClient? httpClient = null)
{
    _httpClient = httpClient ?? new HttpClient();  // 可能每次 new
    _baseUrl = Environment.GetEnvironmentVariable("ANTHROPIC_BASE_URL") ?? "https://api.anthropic.com";
    _apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") ?? ...;
}
```

同样的问题存在于 `BedrockProvider`、`CodexProvider`、`FoundryProvider`、`VertexProvider` 以及 `AuthService.ExchangeCodeForTokenAsync` 中的 `new HttpClient()`（第130行）。

**建议**: 使用 `IHttpClientFactory`：

```csharp
// ServiceCollectionExtensions.cs
services.AddHttpClient<AnthropicProvider>(client =>
{
    client.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");
});

// AnthropicProvider.cs
public AnthropicProvider(HttpClient httpClient)  // DI 注入，不可为 null
{
    _httpClient = httpClient;
}
```

---

### 问题 4.4 [Medium] SystemPromptBuilder 每次构建启动 2 个 git 进程

**位置**: `src/FreeCode.Engine/SystemPromptBuilder.cs:82-139`

```csharp
private async Task<string> BuildContextInfoAsync(...)
{
    var branch = await RunGitCommandAsync("rev-parse --abbrev-ref HEAD").ConfigureAwait(false);
    var status = await RunGitCommandAsync("status --porcelain").ConfigureAwait(false);
    // ...
}

private async Task<string> RunGitCommandAsync(string arguments)
{
    using var process = new Process { /* ... */ };  // 每次创建新进程
    process.Start();
    // ...
}
```

**问题**: 每次 `BuildAsync` 调用都会启动 2 个 `git` 子进程。在快速对话场景下，这可能导致明显的延迟。

**建议**: 缓存 git 信息，仅在检测到文件系统变更时刷新：

```csharp
public sealed class GitInfoProvider
{
    private string? _cachedBranch;
    private string? _cachedStatus;
    private DateTime _lastRefresh;
    private readonly TimeSpan _cacheDuration = TimeSpan.FromSeconds(2);
    
    public async Task<(string Branch, string Status)> GetInfoAsync()
    {
        if (DateTime.UtcNow - _lastRefresh < _cacheDuration && _cachedBranch is not null)
            return (_cachedBranch, _cachedStatus!);
        
        // 并行执行两个 git 命令
        var branchTask = RunGitCommandAsync("rev-parse --abbrev-ref HEAD");
        var statusTask = RunGitCommandAsync("status --porcelain");
        await Task.WhenAll(branchTask, statusTask).ConfigureAwait(false);
        
        _cachedBranch = branchTask.Result;
        _cachedStatus = statusTask.Result;
        _lastRefresh = DateTime.UtcNow;
        return (_cachedBranch, _cachedStatus);
    }
}
```

---

### 问题 4.5 [Medium] BashTool.IsReadOnly 简单前缀匹配

**位置**: `src/FreeCode.Tools/BashTool.cs:44-55`

```csharp
public override bool IsReadOnly(object input)
{
    var command = input is BashToolInput toolInput ? toolInput.Command : input as string;
    var trimmed = command.TrimStart();
    var readOnlyPrefixes = new[] { "ls", "cat", "grep", "find", "pwd", ... };
    return readOnlyPrefixes.Any(prefix => trimmed.StartsWith(prefix, StringComparison.Ordinal));
}
```

**问题**:
1. 每次调用创建新数组（可改为 `static readonly`）
2. `lsblk`、`lsof`、`catdoc` 等命令会被错误匹配为 `ls`、`cat`
3. `git status --short && rm -rf /` 这样的复合命令会通过检测

**建议**: 使用单词边界匹配 + 管道/链式检测：

```csharp
private static readonly string[] ReadOnlyCommands = ["ls", "cat", "grep", "find", "pwd", "head", "tail", "stat", "wc", "du", "which", "whoami", "git"];

public override bool IsReadOnly(object input)
{
    var command = input is BashToolInput t ? t.Command : input as string;
    if (string.IsNullOrWhiteSpace(command)) return false;
    
    // 检测管道/链式命令
    if (command.Contains('|') || command.Contains(';') || command.Contains("&&") || command.Contains("||"))
        return false;
    
    var firstWord = command.TrimStart().Split(' ', 2)[0];
    var baseCommand = firstWord.Split('/', StringSplitOptions.RemoveEmptyEntries).LastOrDefault() ?? firstWord;
    
    return ReadOnlyCommands.Contains(baseCommand, StringComparer.Ordinal)
        || (baseCommand == "git" && command.TrimStart().StartsWith("git status", StringComparison.Ordinal));
}
```

---

### 问题 4.6 [Medium] 硬编码配置值

| 位置 | 硬编码值 | 说明 |
|------|----------|------|
| `AnthropicProvider.cs:31` | `"2023-06-01"` | Anthropic API 版本号 |
| `AnthropicProvider.cs:145` | `4096` | max_tokens 限制 |
| `BashTool.cs:128` | `"/bin/zsh"` | 默认 shell 路径 |
| `AuthService.cs:95` | `38465` | OAuth 回调端口 |
| `SessionMemoryService.cs:10-11` | `4000`, `8` | Token/ToolCall 阈值 |
| `SystemPromptBuilder.cs:157-166` | BaseInstructions | 基础系统提示词 |

**建议**: 移至 `appsettings.json` 和 Options pattern：

```csharp
// appsettings.json
{
    "Anthropic": {
        "ApiVersion": "2023-06-01",
        "MaxTokens": 4096,
        "BaseUrl": "https://api.anthropic.com"
    },
    "Shell": {
        "DefaultPath": "/bin/zsh",
        "Timeout": 120000
    },
    "Memory": {
        "TokenThreshold": 4000,
        "ToolCallThreshold": 8
    }
}

// 使用 IOptions<T>
public sealed class AnthropicProvider(HttpClient httpClient, IOptions<AnthropicOptions> options)
```

---

### 问题 4.7 [Medium] Console.Error.WriteLine 替代结构化日志

**位置**:
- `src/FreeCode.Services/SessionMemoryService.cs:221`
- `src/FreeCode.Services/AuthService.cs:210`
- `src/FreeCode.Services/KeychainTokenStorage.cs` (多处)
- `src/FreeCode/Program.cs:73`

```csharp
// 当前 — 非结构化输出
Console.Error.WriteLine($"Warning: MCP connection failed: {ex.Message}");
Console.Error.WriteLine($"Failed to open browser: {ex.Message}");
Console.Error.WriteLine($"Failed to save memory entry '{entry.Id}': {ex.Message}");
```

**建议**: 统一使用 `ILogger<T>`：

```csharp
public sealed class SessionMemoryService(ILogger<SessionMemoryService> logger)
{
    private void SaveEntry(MemoryEntry entry)
    {
        try { /* ... */ }
        catch (Exception ex)
        {
            logger.LogWarning(ex, "Failed to save memory entry {EntryId}", entry.Id);
        }
    }
}
```

---

### 问题 4.8 [Low] 同步方法包装为 Task 返回

**位置**:
- `src/FreeCode.Services/SessionMemoryService.cs` — 所有公开方法返回 `Task` 但内部完全同步
- `src/FreeCode.Services/PermissionEngine.cs:9` — `CheckAsync` 内部无异步操作

```csharp
// SessionMemoryService — 完全同步却返回 Task
public Task<IReadOnlyList<MemoryEntry>> SearchMemoryAsync(string keyword, CancellationToken ct = default)
{
    // 完全同步操作
    lock (_gate) { return Task.FromResult<IReadOnlyList<MemoryEntry>>(results); }
}
```

**建议**: 对确定同步的方法提供同步 API，或使用 `ValueTask` 减少分配：

```csharp
// 方案A：提供同步 API
public IReadOnlyList<MemoryEntry> SearchMemory(string keyword) { /* sync */ }

// 方案B：使用 ValueTask（减少 Task 分配）
public ValueTask<IReadOnlyList<MemoryEntry>> SearchMemoryAsync(string keyword, CancellationToken ct = default)
{
    ct.ThrowIfCancellationRequested();
    lock (_gate) { return new(results); }
}
```

---

### 问题 4.9 [Low] 全局 `using System.Linq` 但大部分查询简单

**位置**: `src/FreeCode/Program.cs:12`

```csharp
using System.Linq;
```

Program.cs 仅在一处使用 Linq（`args.Any(...)`），其余所有 `using` 都通过 `ImplicitUsings` 自动引入。

---

## 五、性能优化建议

### 5.1 JSON 处理优化

| 问题 | 位置 | 优化方案 | 预期收益 |
|------|------|----------|----------|
| write→parse→clone | QueryEngine.cs:263-397 | 直接返回 JsonDocument 不 Clone | 减少 3 次内存分配/调用 |
| McpClient.ParseMessage Clone | McpClient.cs:170-204 | 使用 `ReadOnlySpan<byte>` + 流式解析 | 减少 GC 压力 |
| ToolBase EmptySchema | ToolBase.cs:9 | 使用 `JsonNode` 或缓存 `byte[]` | 消除泄漏 |
| SessionMemoryService 反序列化 | SessionMemoryService.cs:195 | 使用 Source Generator | AOT 兼容 + 减少反射 |

### 5.2 网络连接优化

| 问题 | 位置 | 优化方案 | 预期收益 |
|------|------|----------|----------|
| HttpClient 未池化 | 所有 Provider + AuthService | IHttpClientFactory | 连接复用 |
| git 进程频繁创建 | SystemPromptBuilder.cs:107 | 缓存 + FileSystemWatcher | 减少进程创建 |
| SSE 流缓冲区 | AnthropicProvider.cs:156 | 可配置 bufferSize | 大消息场景 |

### 5.3 内存优化

| 问题 | 位置 | 优化方案 | 预期收益 |
|------|------|----------|----------|
| Message.Content 是 `object?` | Message.cs:9 | 改为 `OneOf<string, JsonElement>` 或 tagged union | 避免 boxing |
| AppState 全量更新 | AppStateStore.cs:29-35 | 分片状态 + 选择性通知 | 减少 GC 压力 |
| ToolRegistry 缓存永不失效 | ToolRegistry.cs:56-136 | Feature flag 变更时清缓存 | 功能正确性 |

---

## 六、.NET 惯用法改进

### 6.1 使用 file-scoped namespace

当前所有文件使用 block-scoped namespace：

```csharp
namespace FreeCode.Engine
{
    public sealed class QueryEngine ...
}
```

建议改为 C# 10+ 的 file-scoped namespace：

```csharp
namespace FreeCode.Engine;

public sealed class QueryEngine ...
```

### 6.2 替换 `lock(object)` 为更现代的同步原语

当前至少 6 个类使用 `private readonly object _gate = new(); lock(_gate)` 模式：
- AppStateStore, QueryEngine, SessionMemoryService, RateLimitService, ToolRegistry, CoordinatorService

建议按场景替换：
- **读多写少**: `ReaderWriterLockSlim` 或 `ImmutableInterlocked`
- **生产者-消费者**: `Channel<T>`（McpClient 已经用了）
- **信号量**: `SemaphoreSlim`（RemoteSessionManager 已经用了）

### 6.3 使用 `System.Text.Json` Source Generator

`SessionMemoryService.cs:195` 和 `ToolRegistry.cs:303-313` 中使用了 `JsonSerializer.Deserialize<T>` 的反射路径。虽然 `FreeCode.Services/SourceGenerationContext.cs` 已经定义了 Source Generation Context，但未在所有序列化点使用。

### 6.4 使用 `required` + `init` 替代构造函数验证

当前 `Message` record 使用 `required` 属性（正确），但 `AppState` 不使用 `required`——所有属性都有默认值，这意味着可能创建出无效的状态实例。

### 6.5 使用 `primary constructors` 统一风格

`QueryEngine` 和 `SystemPromptBuilder` 使用了 C# 12 primary constructors（良好），但 `AppStateStore`、`SessionMemoryService` 等使用传统构造函数。建议统一。

---

## 七、功能对等性分析

### 7.1 已实现核心功能 ✅

| 功能 | 实现位置 | 对等程度 |
|------|----------|----------|
| 查询引擎主循环 | FreeCode.Engine/QueryEngine.cs | ~80% — 缺少 turn limit / budget enforcement |
| 工具注册与执行 | FreeCode.Tools/ToolRegistry.cs | ~70% — 缺少延迟加载、工具预设 |
| 命令系统 | FreeCode.Commands/ (95+ files) | ~40% — 大量命令可能是空壳 |
| 5 个 API 提供商 | FreeCode.ApiProviders/ | ~75% — SSE 解析基本完成 |
| MCP 协议 | FreeCode.Mcp/ | ~70% — 4 种传输层已实现 |
| OAuth 认证 | FreeCode.Services/AuthService.cs | ~60% — 缺少 PKCE |
| 状态管理 | FreeCode.State/ | ~70% — 基本功能完整 |
| 特性开关 | FreeCode.Features/ | ~60% — 运行时 flag，缺少编译时 flag |
| 插件系统 | FreeCode.Plugins/ | ~50% — AssemblyLoadContext 骨架 |
| 技能系统 | FreeCode.Skills/ | ~30% — 基本加载 |

### 7.2 缺失关键功能 ❌

| 功能 | 原始实现 | 影响 | 优先级 |
|------|----------|------|--------|
| **上下文压缩 (compact)** | src/services/compact/ | 长会话无法管理 token 窗口 | P0 |
| **OAuth PKCE** | src/services/oauth/crypto.ts | 安全漏洞 | P0 |
| **Prompt Cache 优化** | cache_control 注解 + 稳定排序 | API 成本倍增 | P1 |
| **System.CommandLine 集成** | 文档声称使用，实际手动解析 | 子命令、自动补全缺失 | P1 |
| **Terminal.Gui 完整 REPL** | 原始 REPL.tsx 5000+ 行 | UI 体验不完整 | P1 |
| **工具延迟加载** | ToolSearch tool + 按需 schema | Context window 浪费 | P2 |
| **Swarm/Team Agent** | src/assistant/, coordinator/ | 多 Agent 协作不完整 | P2 |
| **Voice 输入** | src/voice/ | 功能缺失但 flag 存在 | P3 |
| **IDE Bridge 完整协议** | src/bridge/ (32 files) | 远程 IDE 控制不完整 | P2 |

### 7.3 命令系统完成度分析

基于探索代理的报告，95+ 个命令文件中绝大部分被标记为 "CommandBase 子类，ExecuteAsync，Standard 质量，无问题"。这种高度一致的评价暗示：

1. 大部分命令可能只实现了骨架代码（调用 `CommandResult.Success("...")`）
2. 缺少与原项目对照的实际功能验证
3. 建议逐个验证关键命令（`/login`, `/config`, `/compact`, `/session`, `/model`）的实际功能

---

## 八、优化路线图

### Phase 1: 关键修复 (1 周)

| # | 任务 | 影响范围 | 工作量 | 收益 |
|---|------|----------|--------|------|
| 1 | IAppStateStore 强类型化 | Core + State + Tools + Engine | 0.5天 | 消除反射、强类型安全 |
| 2 | ToolRegistry 消除 switch | Tools | 1天 | OCP 合规、新增工具零改动 |
| 3 | QueryEngine 拆分（提取 IToolExecutor, IMessageStore） | Engine + Tools | 1天 | SRP、可测试性 |
| 4 | HttpClient 池化 | ApiProviders + Services | 0.5天 | 连接复用、性能 |
| 5 | 添加 OAuth PKCE | Services/AuthService | 0.5天 | 安全性 |

### Phase 2: 架构优化 (2 周)

| # | 任务 | 影响范围 | 工作量 | 收益 |
|---|------|----------|--------|------|
| 6 | AppState 分片 | State + 所有消费者 | 2天 | 性能、选择性更新 |
| 7 | JSON 序列化优化（消除 write→parse→clone） | Engine + Mcp | 2天 | 减少内存分配 |
| 8 | System.CommandLine 集成 | FreeCode (入口) | 1天 | 子命令、自动补全 |
| 9 | 结构化日志（消除 Console.Error） | Services + Engine | 0.5天 | 可观测性 |
| 10 | 实现 IOptions pattern | 全局 | 1天 | 配置管理 |
| 11 | 上下文压缩 (compact) | 新增 Engine 功能 | 3天 | Token 窗口管理 |

### Phase 3: 深度优化 (持续)

| # | 任务 | 影响范围 | 工作量 | 收益 |
|---|------|----------|--------|------|
| 12 | 项目合并（16→8~10） | 解决方案级 | 1天 | 构建速度 |
| 13 | 工具延迟加载 | Tools | 2天 | Context window 优化 |
| 14 | Prompt Cache 优化 | Engine | 1天 | API 成本 |
| 15 | Terminal.Gui 完整 REPL | TerminalUI | 5天 | UI 功能对等 |
| 16 | 命令功能逐个验证与完善 | Commands | 5天+ | 功能对等 |
| 17 | 集成测试完善 | Tests | 持续 | 可靠性 |

---

## 九、总结

### 优点

1. **分层架构清晰**: 五层架构（基础→基础设施→核心→应用→表现）边界明确
2. **接口驱动设计**: 28 个核心接口定义了完整的契约层
3. **DI 覆盖完整**: 所有服务通过构造函数注入，16 个模块独立注册
4. **异步管道正确**: `IAsyncEnumerable<SDKMessage>` 流式响应、CancellationToken 贯穿全链路
5. **不可变状态**: AppState 使用 record + init 属性，避免意外修改
6. **JSON 高级 API 使用**: Utf8JsonWriter + ArrayBufferWriter 优于手动字符串拼接
7. **工具池稳定排序**: 按名称字典序排序，最大化 prompt cache 命中潜力

### 核心不足

1. **ToolRegistry switch 分发** — 最严重的设计问题，每增加工具需改 3 处
2. **IAppStateStore 弱类型** — `object` 类型贯穿状态管理全链路
3. **QueryEngine 神类** — 423 行承担 6+ 职责，构造函数注入 Func 委托
4. **JSON 冗余分配** — write→parse→clone 反模式出现 3 次
5. **功能缺失** — compact、PKCE、prompt-cache 三项关键功能未实现
6. **HttpClient 未管理** — 5 个 Provider + AuthService 各自 new HttpClient()

### 一句话总结

> 架构骨架搭建完成度约 70%，但存在多个 **Critical 级设计问题** 需要在功能开发前解决，否则技术债将随代码增长而指数级放大。建议按 Phase 1→2→3 路线图推进，优先解决类型安全、OCP 合规、连接管理三大基础问题。

---

*报告生成日期：2026-04-06*  
*审查范围：src/ 目录下 16 个项目全部 .cs 文件*