从“手机上写代码“的疯狂想法，到一套完整的AI编程平台架构——WebCode深度技术剖析

优质文章学习记录

11 Apr 2026 — 16 min read

说实话，当我第一次在地铁上用手机修复了一个线上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上实现起来简直是噩梦。

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

想象一下这个场景：

后端从CLI进程读取输出
通过SSE推送到前端
前端解析JSON
更新UI状态
触发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文章