说实话，当我第一次在地铁上用手机修复了一个线上Bug的时候，我整个人都是懵的。不是因为Bug有多难，而是因为——我TM居然真的在手机上写代码了？

一、那个让我失眠的需求

故事要从去年说起。

当时我们团队接到一个"看起来很简单"的需求：让开发者能够随时随地使用AI编程助手。产品经理信誓旦旦地说："不就是做个Web版的Claude Code吗？套个壳就行了。"

我当时就笑了。

你知道Claude Code CLI是怎么工作的吗？它是一个本地进程，需要读写文件系统，需要执行Shell命令，需要维护会话状态，需要解析流式JSON输出...把这玩意儿搬到Web上？还要支持手机？

那几天我躺在床上翻来覆去睡不着，脑子里全是问题：

• 浏览器怎么调用本地CLI工具？

• 流式输出怎么实时推送到前端？

• 多个用户同时使用，工作区怎么隔离？

• 手机上那个破键盘，怎么让人愉快地写代码？

• Claude Code和Codex的输出格式完全不一样，怎么统一处理？

后来我想明白了一件事：这不是一个"套壳"的活儿，这是要从零设计一套分布式AI编程平台的架构。

二、架构设计：我踩过的那些坑

2.1 第一个大坑：CLI工具的"性格"都不一样

你以为所有AI CLI工具的输出格式都一样？太天真了。

Claude Code输出的是stream-json格式，长这样：

{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"让我来帮你..."}]}}

而Codex输出的是JSONL格式，长这样：

{"type":"item.updated","item":{"type":"agent_message","text":"正在分析代码..."}}

更要命的是，它们的会话恢复机制也不一样。Claude Code用--resume session_id，Codex用resume session_id（注意，没有双横线）。

一开始我想的是：写一堆if-else判断不就完了？

// 千万别这么写，我已经替你踩过坑了 if (toolId == "claude-code") { // 处理Claude Code的逻辑 } else if (toolId == "codex") { // 处理Codex的逻辑 } else if (toolId == "copilot") { // 又来一个... }

这种代码写出来，三个月后你自己都不想维护。

最后我选择了适配器模式。每个CLI工具都有自己的适配器，实现统一的接口：

public interface ICliToolAdapter { // 这个工具支持哪些ID string[] SupportedToolIds { get; } // 是否支持流式解析 bool SupportsStreamParsing { get; } // 构建命令行参数（每个工具的参数格式都不一样） string BuildArguments(CliToolConfig tool, string prompt, CliSessionContext context); // 解析输出（每个工具的输出格式都不一样） CliOutputEvent? ParseOutputLine(string line); // 提取会话ID（用于会话恢复） string? ExtractSessionId(CliOutputEvent outputEvent); }

这样做的好处是什么？新增一个CLI工具，只需要写一个新的适配器，核心代码一行不用改。

举个例子，Claude Code的适配器是这样处理参数构建的：

public string BuildArguments(CliToolConfig tool, string prompt, CliSessionContext context) { var escapedPrompt = EscapeShellArgument(prompt); // 会话恢复参数 var sessionArg = string.Empty; if (context.IsResume && !string.IsNullOrEmpty(context.CliThreadId)) { sessionArg = $"--resume {context.CliThreadId}"; // Claude Code用双横线 } return $"-p --output-format=stream-json {sessionArg} \"{escapedPrompt}\""; }

而Codex的适配器是这样的：

public string BuildArguments(CliToolConfig tool, string prompt, CliSessionContext context) { var escapedPrompt = EscapeJsonString(prompt); var sessionArg = string.Empty; if (context.IsResume && !string.IsNullOrEmpty(context.CliThreadId)) { sessionArg = $"resume {context.CliThreadId}"; // Codex不用双横线 } return $"exec --json {sessionArg} \"{escapedPrompt}\""; }

看到没？差异被封装在适配器里，上层代码完全不用关心。

2.2 第二个大坑：流式输出的"时序地狱"

AI的回复是流式的，一个字一个字往外蹦。这在命令行里看着很酷，但在Web上实现起来简直是噩梦。

问题出在哪儿？异步读取 + 并发渲染 + 状态同步。

想象一下这个场景：

1. 后端从CLI进程读取输出

2. 通过SSE推送到前端

3. 前端解析JSON

4. 更新UI状态

5. 触发Blazor重新渲染

这五步里，任何一步出问题，用户看到的就是乱码或者卡顿。

我最初的实现是这样的：

// 错误示范：直接在读取循环里更新UI while ((line = await reader.ReadLineAsync()) != null) { var chunk = ParseJsonLine(line); _currentMessage += chunk.Content; StateHasChanged(); // 每读一行就刷新UI }

结果呢？**CPU直接飙到100%**，页面卡得像PPT。

为什么？因为StateHasChanged()会触发整个组件树的重新渲染，而AI输出的速度是每秒几十上百个字符，你让Blazor每秒渲染几十次，它不崩谁崩？

最后的解决方案是防抖 + 批量更新：

private System.Threading.Timer? _updateTimer; private readonly object _updateLock = new object(); private bool _hasPendingUpdate = false; private void QueueUIUpdate() { lock (_updateLock) { if (_hasPendingUpdate) return; _hasPendingUpdate = true; // 50ms内的更新合并成一次 _updateTimer?.Dispose(); _updateTimer = new Timer(_ => { _hasPendingUpdate = false; InvokeAsync(StateHasChanged); }, null, 50, Timeout.Infinite); } }

这样一来，不管AI输出多快，UI最多每50ms刷新一次，既保证了流畅度，又不会把浏览器搞崩。

2.3 第三个大坑：工作区隔离的"安全噩梦"

多用户场景下，每个人都有自己的工作区。听起来简单，做起来要命。

最直接的问题：用户A能不能访问用户B的文件？

如果你的回答是"不能"，那恭喜你，你需要考虑以下场景：

• 路径穿越攻击：../../etc/passwd

• 符号链接攻击：在工作区里创建一个指向系统目录的软链接

• 命令注入：用户输入里带;rm -rf /

我的解决方案是多层防护：

第一层：会话隔离

每个会话有独立的工作目录，目录名是随机生成的UUID：

public string GetOrCreateSessionWorkspace(string sessionId) { lock (_workspaceLock) { if (_sessionWorkspaces.TryGetValue(sessionId, out var existing)) return existing; var workspacePath = Path.Combine( GetEffectiveWorkspaceRoot(), sessionId // UUID，无法猜测 ); Directory.CreateDirectory(workspacePath); _sessionWorkspaces[sessionId] = workspacePath; return workspacePath; } }

第二层：路径验证

所有文件操作都要验证路径是否在工作区内：

private bool IsPathSafe(string workspacePath, string requestedPath) { var fullPath = Path.GetFullPath(Path.Combine(workspacePath, requestedPath)); var normalizedWorkspace = Path.GetFullPath(workspacePath); // 确保解析后的路径仍在工作区内 return fullPath.StartsWith(normalizedWorkspace, StringComparison.OrdinalIgnoreCase); }

第三层：命令白名单

CLI工具只能执行预定义的命令，用户输入会被转义：

private static string EscapeShellArgument(string argument) { // 转义所有可能导致命令注入的字符 return argument .Replace("\\", "\\\\") .Replace("\"", "\\\"") .Replace("$", "\\$") .Replace("`", "\\`"); }

三、上下文管理：AI的"记忆"问题

这是整个项目里我最得意的一块设计。

你有没有遇到过这种情况：跟AI聊了半天，它突然"失忆"了，之前说的话全忘了？

这是因为AI模型有上下文窗口限制。Claude的上下文窗口是100K tokens，听起来很大，但如果你在讨论一个大型项目，贴几个文件进去，分分钟就爆了。

传统的解决方案是"截断"——超过限制就把最早的消息删掉。但这样做的问题是：可能把关键信息删掉了。

我设计了一套智能上下文管理系统：

3.1 上下文项的优先级

不是所有信息都同等重要。用户的问题比AI的回复重要，错误信息比普通输出重要，最近的消息比很久以前的消息重要。

public class ContextItem { public ContextItemType Type { get; set; } public string Content { get; set; } public int EstimatedTokens { get; set; } public int Priority { get; set; } // 0-10，越高越重要 public bool IsIncluded { get; set; } = true; }

优先级的默认规则：

• 用户消息：7

• 错误信息：9（最高，因为通常是当前要解决的问题）

• AI回复：5

• 代码片段：6

• 文件引用：4

3.2 智能压缩策略

当上下文快满的时候，系统会自动触发压缩。但不是简单地删除，而是智能摘要：

private async Task CompressSmartSummaryAsync(...) { // 1. 高优先级项永远保留 var highPriorityItems = items.Where(i => i.Priority >= 7); // 2. 最近的用户消息保留 var recentUserMessages = items .Where(i => i.Type == ContextItemType.UserMessage) .OrderByDescending(i => i.CreatedAt) .Take(config.KeepRecentMessages); // 3. 其他内容生成摘要 foreach (var item in itemsToCompress) { if (item.Type == ContextItemType.CodeSnippet) { // 代码片段：保留函数签名，删除实现细节 item.Content = GenerateCodeSnippetSummary(item.Content); item.EstimatedTokens = TokenEstimator.EstimateTokens(item.Content); } } }

这样做的效果是：即使上下文被压缩了，AI仍然知道之前讨论过什么，只是细节没那么清楚了。

3.3 Token估算

准确估算Token数量是个技术活。不同语言的Token密度不一样：

public static int EstimateTokens(string text) { // 中文：约1.5字符/Token // 英文：约4字符/Token var chineseChars = text.Count(c => c >= 0x4E00 && c <= 0x9FFF); var otherChars = text.Length - chineseChars; return (int)Math.Ceiling(chineseChars / 1.5 + otherChars / 4.0); }

代码的Token密度更高（因为有很多符号和关键字），所以单独处理：

public static int EstimateCodeTokens(string code) { return (int)Math.Ceiling(code.Length / 3.5); }

四、移动端适配：那些让我抓狂的细节

"支持手机"这四个字，背后是无数个深夜的调试。

4.1 iOS Safari的100vh问题

你知道iOS Safari的100vh不是真正的视口高度吗？它包含了地址栏的高度，导致页面底部会被遮挡。

解决方案：

.container { height: 100vh; height: 100dvh; /* 动态视口高度，iOS 15+支持 */ height: -webkit-fill-available; /* 兼容旧版本 */ }

4.2 虚拟键盘弹出时的布局问题

手机上弹出键盘时，视口高度会变化，如果处理不好，输入框会被键盘遮挡。

我的解决方案是监听visualViewport的变化：

if (window.visualViewport) { window.visualViewport.addEventListener('resize', () => { const keyboardHeight = window.innerHeight - window.visualViewport.height; document.documentElement.style.setProperty('--keyboard-height', `${keyboardHeight}px`); }); }

然后在CSS里使用这个变量：

.input-area { padding-bottom: calc(env(safe-area-inset-bottom) + var(--keyboard-height, 0px)); }

4.3 触摸目标大小

苹果的人机界面指南建议触摸目标至少44x44像素。但很多开发者（包括以前的我）都忽略了这一点。

.touch-target { min-width: 44px; min-height: 44px; padding: 12px; /* 即使内容小，点击区域也要够大 */ }

五、性能优化：从"能用"到"好用"

5.1 文件树的虚拟滚动

工作区可能有成百上千个文件，如果全部渲染到DOM里，页面会卡死。

解决方案是懒加载 + 虚拟滚动：

private const int MaxVisibleNodes = 100; private int _currentVisibleNodes = MaxVisibleNodes; // 只渲染可见区域的节点 private List<WorkspaceFileNode> GetVisibleNodes() { return _workspaceFiles .Take(_currentVisibleNodes) .ToList(); } // 滚动到底部时加载更多 private void LoadMoreNodes() { _currentVisibleNodes += 50; StateHasChanged(); }

5.2 Markdown渲染缓存

AI的回复通常包含大量Markdown，每次渲染都要解析一遍很浪费。

private readonly Dictionary<string, MarkupString> _markdownCache = new(); private MarkupString RenderMarkdown(string? markdown) { if (_markdownCache.TryGetValue(markdown, out var cached)) return cached; var html = Markdown.ToHtml(markdown, _markdownPipeline); var result = new MarkupString(html); // 限制缓存大小 if (_markdownCache.Count > 100) _markdownCache.Clear(); _markdownCache[markdown] = result; return result; }

5.3 输出状态的防抖保存

用户的输出结果需要持久化，但不能每次更新都写数据库。

private void QueueSaveOutputState() { lock (_outputStateSaveLock) { if (_hasPendingOutputStateSave) return; _hasPendingOutputStateSave = true; _outputStateSaveTimer?.Dispose(); _outputStateSaveTimer = new Timer(async _ => { _hasPendingOutputStateSave = false; await SaveOutputStateAsync(); }, null, OutputStateSaveDebounceMs, Timeout.Infinite); } }

六、未来的坑（和机会）

这个项目还在持续迭代，有几个方向我特别想做：

6.1 多模型对比

同一个问题，让Claude和GPT同时回答，对比结果。这对于选择最佳方案很有帮助。

技术上的挑战是并行执行 + 结果同步：

public async Task<List<ModelResponse>> ExecuteParallelAsync( string prompt, List<string> toolIds) { var tasks = toolIds.Select(toolId => ExecuteSingleAsync(prompt, toolId)); return await Task.WhenAll(tasks); }

6.2 实时协作

多人同时编辑同一个工作区，像Google Docs那样。

这需要引入CRDT（无冲突复制数据类型）或者OT（操作转换）算法，复杂度直接上一个台阶。

6.3 插件系统

让用户可以自己添加新的CLI工具适配器，不需要改核心代码。

架构上已经预留了扩展点：

public interface IPluginService { void RegisterCliAdapter(ICliToolAdapter adapter); List<PluginUIComponent> GetPluginUIComponents(string location); }

七、写在最后

回头看这个项目，最大的收获不是代码本身，而是对复杂系统的理解。

一个"简单"的需求背后，可能涉及：

• 进程管理和IPC

• 流式数据处理

• 安全和隔离

• 跨平台兼容

• 性能优化

• 用户体验

每一个点展开都是一个深坑。

但这也是软件开发的魅力所在，不是吗？

你永远不知道下一个Bug会把你带到哪个知识领域。

如果你对这个项目感兴趣，欢迎来GitHub上看看：WebCodehttps://github.com/xuzeyu91/WebCode

有问题可以在评论区讨论，我会尽量回复。

最后，如果这篇文章对你有帮助，点个赞呗？写了一整天，手都酸了 😂

更多AIGC文章

RAG技术全解：从原理到实战的简明指南

更多VibeCoding文章