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

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

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

想象一下这个场景：

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

我最初的实现是这样的：

// 错误示范：直接在读取循环里更新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 触摸目标大小

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

.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文章