博客

ImgBin CLI 工具设计：HagiCode 图片资产管理方案

2026年3月13日

ImgBin CLI 工具设计：HagiCode 图片资产管理方案

本文介绍如何从零构建一个可自动化执行的图片资产流水线，包括 CLI 工具设计、Provider Adapter 架构、以及元数据管理策略。

背景

其实也没想到，图片资产管理这事儿也能让我们纠结这么久。

在 HagiCode 项目开发过程中，我们遇到了一个看似简单却十分棘手的问题：图片资产的生成和管理。怎么说呢，就像青春期的那些事儿一样——表面上风平浪静，暗地里波澜起伏。

随着项目文档和营销物料的增多，需要大量配图。这些配图有些需要 AI 生成，有些需要从现有素材库中挑选，还有些需要对现有图片进行 AI 识别并自动标注。问题在于，这些工作长期以来都是用零散的脚本加人工操作来完成的——每次生成一张图片，都需要手动执行脚本、手动整理元数据、手动生成缩略图。这也就罢了，关键是这些零散的东西散落在各处，想找的时候找不到，想用的时候用不了。

具体痛点包括：

缺乏统一入口：图片生成的逻辑分散在不同脚本中，想批量执行根本没门
元数据缺失：生成后的图片没有统一的 metadata.json，无法检索和追踪
人工整理成本高：图片的标题、标签都需要人工一一整理，效率低下
无法自动化：CI/CD 流程中想要自动生成配图？门都没有

也曾想过干脆不管了，可是毕竟还是要做项目的嘛。既然躲不掉，那就想办法解决呗。于是我们决定，将 ImgBin 从「零散脚本」升级为可自动化执行的图片资产流水线。毕竟有些事儿，逃避也不是办法。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，同时维护着 VSCode 扩展、后端 AI 服务、跨平台桌面客户端等多种组件。在这种多语言、多平台的复杂场景下，图片资产的规范管理成了提升开发效率的关键一环。

怎么说呢，这也算是 HagiCode 成长过程中的一个小小烦恼吧。每个项目都会有这样的时候，看起来不起眼的小问题，却能让人折腾半天。

HagiCode 的构建系统采用 TypeScript + Node.js 生态，因此 ImgBin 也顺理成章地选择了相同的技术栈，确保整个项目的技术一致性。毕竟都用习惯了，换别的也嫌麻烦嘛。

核心设计

整体架构

ImgBin 采用分层架构，将 CLI 命令、应用服务、第三方 API 适配器和基础设施层清晰分离：

组件层次结构
├── CLI Entry (cli.ts)              全局参数解析、命令路由
├── Commands (commands/*)           generate | batch | annotate | thumbnail
├── Application Services            job-runner | metadata | thumbnail | asset-writer
├── Provider Adapters               image-api-provider | vision-api-provider
└── Infrastructure Layer            config | logger | paths | schema

这种分层设计的好处是：每层的职责清晰，测试时可以方便地 mock 掉外部依赖。其实也就是让各干各的，互不打扰，这样出了问题也容易找原因，不是么？

单资产目录模型

ImgBin 采用了「一个资产一个目录」的模型，每次生成图片时，都会创建如下结构：

library/
└── 2026-03/
    └── orange-dashboard/
        ├── original.png      # 原始图片
        ├── thumbnail.webp    # 512x512 缩略图
        └── metadata.json     # 结构化元数据

这种模型的优势在于：

自包含：每个资产的所有文件都在同一个目录，迁移、备份都很方便
可追溯：通过 metadata.json 可以追溯图片的生成时间、使用的 prompt、模型等信息
可扩展：未来如果需要添加更多变体（比如不同尺寸的缩略图），只需要在同一目录下新增文件即可

美的事物或人，不一定要占有，只要她还是美的，自己好好看着她的美就好了。这话虽然说得有点远了，但理儿是这么个理儿——图片放在一起了，看起来也舒服，找起来也方便。

元数据分层存储

metadata.json 是整个系统的核心，它采用分层存储策略，区分了三类字段：

{
  "schemaVersion": 2,
  "assetId": "orange-dashboard",
  "slug": "orange-dashboard",
  "title": "Orange Dashboard",
  "tags": ["dashboard", "hero", "orange"],

  "source": { "type": "generated" },

  "paths": {
    "assetDir": "library/2026-03/orange-dashboard",
    "original": "original.png",
    "thumbnail": "thumbnail.webp"
  },

  "generated": {
    "prompt": "orange dashboard for docs hero",
    "provider": "azure-openai-image-api",
    "model": "gpt-image-1.5"
  },

  "recognized": {
    "title": "Orange Dashboard",
    "tags": ["dashboard", "ui", "orange"],
    "description": "A modern orange dashboard with charts and metrics"
  },

  "status": {
    "generation": "succeeded",
    "recognition": "succeeded",
    "thumbnail": "succeeded"
  },

  "timestamps": {
    "createdAt": "2026-03-11T04:01:19.570Z",
    "updatedAt": "2026-03-11T04:02:09.132Z"
  }
}

generated：记录图片生成时的原始信息，如使用的 prompt、提供商、模型等
recognized：AI 识别结果，如自动生成的标题、标签、描述
manual：人工整理的结果，这个区的数据优先级最高，不会被 AI 识别覆盖

这种分层策略解决了我们之前的一个核心矛盾：AI 识别结果和人工整理结果谁优先？答案是人工优先，AI 识别只是辅助。这事儿也想明白了——有些东西嘛，机器终究是机器，终究还是得人来把关。

Provider Adapter 模式

ImgBin 的另一个核心设计是 Provider Adapter 模式。我们将外部 API 抽象为统一的接口，这样即使更换 AI 服务商，也不需要修改业务逻辑。

怎么说呢，这就跟感情一样——外表怎么变不重要，重要的是内心那套东西不变。接口定好了，内部的实现怎么换都行。

Image Generation Provider

interface ImageGenerationProvider {
  // 生成图片，返回图片的 Buffer
  generate(options: GenerateOptions): Promise<Buffer>;

  // 获取支持的模型列表
  getSupportedModels(): Promise<string[]>;
}

interface GenerateOptions {
  prompt: string;
  model?: string;
  size?: '1024x1024' | '1792x1024' | '1024x1792';
  quality?: 'standard' | 'hd';
  format?: 'png' | 'webp' | 'jpeg';
}

Vision Recognition Provider

interface VisionRecognitionProvider {
  // 识别图片内容，返回结构化的元数据
  recognize(imageBuffer: Buffer): Promise<RecognitionResult>;

  // 获取支持的模型列表
  getSupportedModels(): Promise<string[]>;
}

interface RecognitionResult {
  title?: string;
  tags: string[];
  description?: string;
  confidence: number;
}

这种接口设计的优势在于：

可测试：单元测试时可以传入 mock provider，不需要真正调用外部 API
可扩展：新增一个 provider 只需要实现接口，不需要修改调用方代码
可替换：生产环境用 Azure OpenAI，测试环境用本地模型，只需要切换配置

想笑来伪装自己掉下的泪，想哭来试探自己麻痹了没——有时候做项目就是这样，表面上看是换了个 API，实际上内在的那套逻辑一点没变，也就没什么好怕的了。

CLI 命令设计

ImgBin 提供了四个核心命令，满足不同的使用场景：

generate：单图生成

# 最简单的用法
imgbin generate --prompt "orange dashboard for docs hero"

# 同时生成缩略图和 AI 标注
imgbin generate --prompt "orange dashboard" --annotate --thumbnail

# 指定输出目录
imgbin generate --prompt "orange dashboard" --output ./library

batch：批量任务

批量任务通过 YAML 或 JSON manifest 文件定义，适合 CI/CD 流程中使用：

defaults:
  annotate: true
  thumbnail: true
  libraryRoot: ./library

jobs:
  - prompt: "orange dashboard hero"
    slug: orange-dashboard
    tags: [dashboard, hero, orange]

  - prompt: "pricing grid for docs"
    slug: pricing-grid
    tags: [pricing, grid, docs]

执行命令：

imgbin batch assets/jobs/launch.yaml

批量任务的设计支持失败隔离：manifest 中逐项处理，单项失败不影响其他任务。可以通过 --dry-run 预览而不实际执行。

这也就罢了，关键是它还能告诉你哪儿成功了哪儿失败了，不像某些事儿，失败了都不知道怎么失败的。

annotate：AI 标注

对现有图片执行 AI 识别，自动生成标题、标签、描述：

# 标注单张图片
imgbin annotate ./library/2026-03/orange-dashboard

# 批量标注整个目录
imgbin annotate ./library/2026-03/

thumbnail：缩略图生成

为既有图片补生成缩略图：

# 生成缩略图
imgbin thumbnail ./library/2026-03/orange-dashboard

批量任务 Manifest 设计

批量任务的 manifest 支持灵活的配置，默认值可以统一设置，单个任务也可以覆盖：

# 全局默认值
defaults:
  annotate: true        # 默认开启 AI 标注
  thumbnail: true       # 默认生成缩略图
  libraryRoot: ./library
  model: gpt-image-1.5

jobs:
  # 最小配置，只提供 prompt
  - prompt: "first image"

  # 完整配置
  - prompt: "second image"
    slug: custom-slug
    tags: [tag1, tag2]
    annotate: false     # 这个任务不执行 AI 标注
    model: dall-e-3    # 这个任务用不同的模型

执行时，ImgBin 会逐个处理任务，每个任务的结果会写入对应的 metadata.json，即使某个任务失败，也不会影响其他任务。任务完成后，会输出汇总报告：

✓ orange-dashboard (succeeded)
✓ pricing-grid (succeeded)
✗ hero-banner (failed: API rate limit exceeded)

2/3 succeeded, 1 failed

有些事儿吧，急也急不来，一个一个来，反而踏实。这，或许就是批量任务的哲学吧。

环境变量配置

ImgBin 通过环境变量支持灵活的配置：

# ImgBin 工作目录
IMGBIN_WORKDIR=/path/to/imgbin

# 可执行文件路径（用于脚本中调用）
IMGBIN_EXECUTABLE=/path/to/imgbin/dist/cli.js

# 资产库根目录
IMGBIN_LIBRARY_ROOT=./.imgbin-library

# Azure OpenAI 配置（如果使用 Azure provider）
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_IMAGE_DEPLOYMENT=gpt-image-1

配置这东西，说重要也重要，说不重要也不重要。毕竟怎么舒服怎么来嘛，适合自己的才是最好的。

实现要点

在实现过程中，我们总结了以下几个关键点：

Provider 接口设计

接口定义要清晰完整，包括输入参数、返回值、错误处理。建议同时提供同步和异步两种调用方式，方便不同场景使用。

这也算是过来人的一点经验吧，毕竟接口这东西，定好了就不想再改，麻烦。

失败处理策略

批量任务中某项失败时，应该：

记录详细错误信息到单独的日志文件
继续执行其他任务，不中断整个流程
最终返回非零退出码，表示有任务失败
在汇总报告中清晰展示每个任务的执行结果

有些事儿失败了就是失败了，逃避也没用，不如大大方方承认，然后想办法解决。这道理，做项目和做人是一样的。

元数据合并策略

识别结果默认写入 recognized 区，人工修改的字段有 manual 标记。元数据更新时采用「只增不减」策略：除非显式传入 --force 参数，否则不覆盖已有的人工整理结果。

这事儿也想明白了——有些东西啊，错过了就是错过了，覆盖了也就没了。还是保留着比较好，毕竟记录本身也是一种美。

目录创建原子性

使用 fs.mkdir({ recursive: true }) 确保目录创建原子性，避免并发场景下的竞态条件。

这大概就是所谓的安全感吧——该稳稳该快快，不拖泥带水，也不瞻前顾后。

总结

ImgBin 作为 HagiCode 项目图片资产管理的核心工具，通过以下设计解决了我们面临的问题：

统一入口：CLI 命令覆盖了生成、标注、缩略图等全部操作
元数据驱动：每个资产都有完整的 metadata.json，支持检索和追踪
Provider Adapter：灵活的外部 API 抽象，便于测试和扩展
批量任务支持：CI/CD 流程中可以自动执行批量图片生成

一切都淡了…可这方案啊，还真是用上了。

这套方案不仅提升了 HagiCode 自身的开发效率，也形成了一个可复用的图片资产管理框架。如果你也在开发类似的多组件项目，相信 ImgBin 的设计思路会给你一些启发。

青春嘛，总是要折腾的。不折腾折腾，怎么知道自个儿几斤几两呢？

参考资料

ImgBin 技术提案：https://github.com/HagiCode-org/site/tree/main/openspec/changes/archive/2026-03-10-imgbin-cli-tool
HagiCode 官网：https://hagicode.com
HagiCode GitHub：https://github.com/HagiCode-org/site

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-13-imgbin-cli-tool-asset-management/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。版权所有!

Primary profession management in hero settings

2026年3月13日

Primary profession management in hero settings

Hero settings now include a dedicated Primary Professions tab to toggle availability.
Enablement is persisted at the system level and gates hero availability in dungeon selection and status checks.
CLI detection surfaces availability and version; enablement toggles stay locked until the CLI is detected.

C# 后端集成 CodeBuddy CLI 实战指南

2026年3月12日

C# 后端集成 CodeBuddy CLI 实战指南

本文将详细介绍如何在 C# 后端项目中集成 CodeBuddy CLI，实现 AI 编程助手能力的完整方案。

背景

在现代 AI 代码助手开发中，单一 AI Provider 往往无法满足复杂多变的开发场景。这就像，人生路远，总不能只认一个方向吧？HagiCode 作为一款多功能 AI 编程助手，需要支持多种 AI Provider 以提供更好的用户体验。毕竟，用户的选择权还是要给够的。在 2026 年初，项目面临一个关键决策：如何在 C# 后端中恢复 CodeBuddy 的 ACP（Agent Communication Protocol）集成能力。

此前项目中曾实现过 CodeBuddy 对接，但相关代码在一次重构中被移除了。其实也没什么好抱怨的，代码迭代嘛，总有东西要被遗忘。本次技术方案的目标是完整恢复这一能力，并优化架构使其更加健壮和可维护。

如果你也在考虑为自己的项目接入多种 AI 编程助手，下面的方案或许能给你一些启发——这可是我们踩了无数坑之后总结出来的经验。或许能让你少走点弯路，也算是我做过的一点好事吧。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，支持多种 AI Provider 和跨平台运行。为了满足不同用户的偏好，我们需要能够灵活切换各种 AI 编程助手，这就有了本文要介绍的 CodeBuddy 集成方案。

HagiCode 采用模块化设计，AI Provider 作为可插拔的组件，这种架构让我们可以轻松添加新的 AI 支持，而不影响现有功能。这也罢了，设计这种东西，当初做得好，后面省心不少。如果你对我们的技术架构感兴趣，可以在 GitHub 上查看完整源码。

架构设计

分层架构概览

C# 与 CodeBuddy 的对接采用清晰的分层架构，这种设计让代码职责分明，后期维护起来也更加方便：

┌─────────────────────────────────────────────┐
│           Provider 契约层                    │
│   AIProviderType 枚举 + 扩展方法             │
├─────────────────────────────────────────────┤
│           Provider 工厂层                    │
│   AIProviderFactory 依赖注入工厂             │
├─────────────────────────────────────────────┤
│           Provider 实现层                    │
│   CodebuddyCliProvider 具体实现              │
├─────────────────────────────────────────────┤
│           ACP 基础设施层                     │
│  ACPSessionManager / StdioAcpTransport      │
│  AcpRpcClient / AcpAgentClient              │
└─────────────────────────────────────────────┘

这种分层的好处是什么呢？简单说就是各层之间互不打扰。假设以后要换一种通信方式（比如从 stdio 改成 WebSocket），你只需要改最下面那一层，上面的业务代码完全不用动。毕竟，谁也不想牵一发而动全身，改个通信方式还要改半天业务代码，那也太惨了。

核心组件解析

Provider 契约层 是整个架构的基石。我们定义了 AIProviderType 枚举，其中 CodebuddyCli = 3 作为枚举值，通过扩展方法实现字符串与枚举的双向映射。这样配置文件中的字符串可以很方便地转成枚举，调试时枚举也能转成字符串输出。这也罢了，其实就是个映射关系，但做好了就是省心。

Provider 工厂层 负责根据配置创建对应的 Provider 实例。这里使用了 .NET 的依赖注入机制，配合 ActivatorUtilities.CreateInstance 实现动态创建。工厂模式的好处在于，新增一个 Provider 时只需要添加创建逻辑，不用修改已有的代码。这和写文章差不多，想加个新章节，就加个新章节，不用把前面的都重写一遍。

Provider 实现层 是真正干活的地方。CodebuddyCliProvider 实现了 IAIProvider 接口，提供 ExecuteAsync（非流式）和 StreamAsync（流式）两种调用方式。

ACP 基础设施层 则是通信的底层支撑。这一层处理所有的协议细节，包括进程管理、消息序列化、响应解析等。就像房子的地基，上面盖得再漂亮，底下的东西得稳才行。

通信机制

Stdio 传输模式

CodeBuddy 使用 Stdio（标准输入输出） 方式与外部进程通信。启动命令很简单：

codebuddy --acp

然后通过标准输入输出进行 JSON-RPC 消息交换。这种方式的优势在于：

启动迅速：本地进程通信没有网络延迟
配置简单：只需要指定可执行文件路径
环境隔离：每个会话独立进程，互不影响

通信过程中支持环境变量注入，常用的包括：

CODEBUDDY_API_KEY：API 密钥认证
CODEBUDDY_INTERNET_ENVIRONMENT：网络环境配置

这就像，人与人之间的沟通，找个方便的方式，才能说得上话。

消息协议

ACP 基于 JSON-RPC 2.0 协议，消息格式大概是酱紫的：

// 请求消息
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "agent/prompt",
  "params": {
    "prompt": "帮我写一个排序算法",
    "sessionId": "session-123"
  }
}

// 响应消息
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "这里是 AI 的回复..."
  }
}

实际实现中，我们把这些协议细节都封装好了，上层业务代码只需要关注 prompt 和 response 就行。这也罢了，封装得好，后面的人用起来就舒服点。

核心实现

1. Provider 契约恢复

首先在枚举文件中恢复 CodeBuddy 类型：

public enum AIProviderType
{
    ClaudeCodeCli = 0,
    CodexCli = 1,
    GitHubCopilot = 2,
    CodebuddyCli = 3,  // 恢复这个枚举值
    OpenCodeCli = 4,
    IFlowCli = 5,
}

然后在扩展方法中添加字符串映射，这样配置文件就可以用字符串指定 Provider：

private static readonly Dictionary<string, AIProviderType> _typeMap = new(
    StringComparer.OrdinalIgnoreCase)
{
    ["CodebuddyCli"] = AIProviderType.CodebuddyCli,
    ["Codebuddy"] = AIProviderType.CodebuddyCli,
    ["codebuddy"] = AIProviderType.CodebuddyCli,
    // ... 其他 provider 的映射
};

2. Provider 工厂集成

在工厂类中添加 CodeBuddy 的创建分支：

private IAIProvider? CreateProvider(AIProviderType providerType, ProviderConfiguration config)
{
    return providerType switch
    {
        AIProviderType.CodebuddyCli =>
            ActivatorUtilities.CreateInstance<CodebuddyCliProvider>(
                _serviceProvider,
                Options.Create(config)),
        // ... 其他 provider
        _ => throw new NotSupportedException($"Provider {providerType} not supported")
    };
}

这里用了依赖注入的 ActivatorUtilities，它会自动处理构造函数的参数注入，非常方便。这也罢了，.NET 的东西，用对了就是省心。

3. 完整的 Provider 实现

下面是 CodebuddyCliProvider 的核心实现，包含了流式和非流式两种调用方式：

public class CodebuddyCliProvider : IAIProvider
{
    private readonly ILogger<CodebuddyCliProvider> _logger;
    private readonly IACPSessionManager _sessionManager;
    private readonly ProviderConfiguration _config;

    public string Name => "CodebuddyCli";
    public bool SupportsStreaming => true;
    public ProviderCapabilities Capabilities { get; }

    public CodebuddyCliProvider(
        ILogger<CodebuddyCliProvider> logger,
        IACPSessionManager sessionManager,
        IOptions<ProviderConfiguration> config)
    {
        _logger = logger;
        _sessionManager = sessionManager;
        _config = config.Value;

        // 定义当前 Provider 的能力
        Capabilities = new ProviderCapabilities
        {
            SupportsStreaming = true,
            SupportsTools = true,
            SupportsSystemMessages = true,
            SupportsArtifacts = false,
            MaxTokens = 8192
        };
    }

    // 非流式调用：等所有结果一起返回
    public async Task<AIResponse> ExecuteAsync(
        AIRequest request,
        CancellationToken cancellationToken = default)
    {
        // 为请求创建独立会话
        var session = await _sessionManager.CreateSessionAsync(
            "CodebuddyCli",
            request.WorkingDirectory,
            cancellationToken,
            request.SessionId);

        try
        {
            var fullPrompt = BuildPrompt(request);
            await session.SendPromptAsync(fullPrompt, cancellationToken);

            var responseBuilder = new StringBuilder();
            var toolCalls = new List<AIToolCall>();

            // 收集所有响应块
            await foreach (var chunk in StreamFromSession(session, cancellationToken))
            {
                if (!string.IsNullOrEmpty(chunk.Content))
                {
                    responseBuilder.Append(chunk.Content);
                }
                // 处理工具调用...
            }

            return new AIResponse
            {
                Content = AIResultContentSanitizer.SanitizeResultContent(
                    responseBuilder.ToString()),
                ToolCalls = toolCalls,
                Provider = Name,
                Model = string.Empty
            };
        }
        finally
        {
            // 释放会话资源
            await session.DisposeAsync();
        }
    }

    // 流式调用：实时返回响应块
    public async IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var session = await _sessionManager.CreateSessionAsync(
            "CodebuddyCli",
            request.WorkingDirectory,
            cancellationToken);

        try
        {
            var fullPrompt = BuildPrompt(request);
            await session.SendPromptAsync(fullPrompt, cancellationToken);

            await foreach (var chunk in StreamFromSession(session, cancellationToken))
            {
                yield return chunk;
            }
        }
        finally
        {
            await session.DisposeAsync();
        }
    }

    private async IAsyncEnumerable<AIStreamingChunk> StreamFromSession(
        IACPSession session,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        // 遍历会话中的所有更新
        await foreach (var notification in session.ReceiveUpdatesAsync(cancellationToken))
        {
            switch (notification.Update)
            {
                case AgentMessageChunkSessionUpdate agentMessage:
                    // 处理文本内容块
                    if (agentMessage.Content is AcpImp.TextContentBlock textContent)
                    {
                        yield return new AIStreamingChunk
                        {
                            Content = textContent.Text,
                            Type = StreamingChunkType.ContentDelta,
                            IsComplete = false
                        };
                    }
                    break;

                case ToolCallSessionUpdate toolCall:
                    // 处理工具调用
                    yield return new AIStreamingChunk
                    {
                        Content = string.Empty,
                        Type = StreamingChunkType.ToolCallDelta,
                        ToolCallDelta = new AIToolCallDelta
                        {
                            Id = toolCall.ToolCallId,
                            Name = toolCall.Kind.ToString(),
                            Arguments = toolCall.RawInput?.ToString()
                        }
                    };
                    break;

                case AcpImp.PromptCompletedSessionUpdate:
                    // 响应完成
                    yield break;
            }
        }
    }

    // 构建完整的提示词
    private string BuildPrompt(AIRequest request, string? embeddedCommandPrompt = null)
    {
        var sb = new StringBuilder();

        // 嵌入命令提示词（如果有）
        if (!string.IsNullOrEmpty(embeddedCommandPrompt))
        {
            sb.AppendLine(embeddedCommandPrompt);
            sb.AppendLine();
        }

        // 系统消息
        if (!string.IsNullOrEmpty(request.SystemMessage))
        {
            sb.AppendLine(request.SystemMessage);
            sb.AppendLine();
        }

        // 用户 prompt
        sb.Append(request.Prompt);
        return sb.ToString();
    }
}

这段代码有几个关键点：

会话管理：每个请求创建独立会话，请求完成后释放资源。这是坑踩出来的经验——如果会话复用做得不好，很容易出现状态污染的问题。毕竟，用过就得收拾干净，不然下次用的人就麻烦了。
流式处理：IAsyncEnumerable 让响应可以边生成边返回，不用等全部内容生成完。这对于长文本场景特别重要，用户体验会好很多。就像，等结果的人也不想一直干等着不是。
工具调用：CodeBuddy 支持工具调用（Function Calling），通过 ToolCallSessionUpdate 处理。这个能力对于复杂的代码编辑任务很关键。
内容过滤：使用 AIResultContentSanitizer 过滤 Think 块内容，保持输出干净。

4. 依赖注入配置

在模块注册中添加相关服务：

public void ConfigureModule(IServiceCollection context)
{
    // 注册 Provider
    context.Services.AddTransient<CodebuddyCliProvider>();

    // 注册 ACP 基础设施
    context.Services.AddSingleton<IACPSessionManager, ACPSessionManager>();
    context.Services.AddSingleton<IAcpPlatformConfigurationResolver, AcpPlatformConfigurationResolver>();
    context.Services.AddSingleton<IAIRequestToAcpMapper, AIRequestToAcpMapper>();
    context.Services.AddSingleton<IAcpToAIResponseMapper, AcpToAIResponseMapper>();
}

配置示例

配置文件

在 appsettings.json 中添加 CodeBuddy 相关配置：

AI:
  # 默认使用的 Provider
  DefaultProvider: "CodebuddyCli"

  # Provider 配置
  Providers:
    CodebuddyCli:
      Type: "CodebuddyCli"
      WorkingDirectory: "C:/projects/my-app"
      ExecutablePath: "C:/tools/codebuddy.cmd"

  # 平台相关配置
  PlatformConfigurations:
    CodebuddyCli:
      ExecutablePath: "C:/tools/codebuddy.cmd"
      Arguments: "--acp"
      StartupTimeoutMs: 5000
      EnvironmentVariables:
        CODEBUDDY_API_KEY: "${CODEBUDDY_API_KEY}"
        CODEBUDDY_INTERNET_ENVIRONMENT: "production"

配置模型

对应的配置模型定义：

public class CodebuddyPlatformConfiguration : IAcpPlatformConfiguration
{
    public string ProviderName => "CodebuddyCli";
    public AcpTransportType TransportType => AcpTransportType.Stdio;

    public string ExecutablePath { get; set; } = "codebuddy";
    public string Arguments { get; set; } = "--acp";
    public int StartupTimeoutMs { get; set; } = 5000;

    public Dictionary<string, string?>? EnvironmentVariables { get; set; }
}

实践经验总结

踩坑记录

我们在实现过程中遇到了几个典型的坑，分享出来让大家少走弯路。毕竟，别人的坑，自己能避开就是好事：

会话泄漏问题：一开始没有正确释放会话，导致进程资源耗尽。解决方法是使用 try-finally 确保每次请求都会释放资源。这也罢了，用过的东西得放回去，不然后面的人用什么。
环境变量传递：Windows 和 Linux 的环境变量语法不同，后来统一使用 Dictionary<string, string?> 来处理。跨平台这种事，一开始就统一规范，后面就省心。
超时配置：CLI 启动需要时间，设置了 5 秒的启动超时，避免快速请求失败。凡事都得有个度，太急了反而办不成事。
编码问题：Windows 上默认编码可能导致中文乱码，在启动进程时显式指定 UTF-8 编码。中文显示不出来，那多难受。

性能优化

会话池：对于频繁的短请求，可以考虑实现会话池来复用进程
连接缓存：工厂类已经支持 Provider 实例缓存
异步优先：全程使用异步编程，避免阻塞线程

性能这种事，能优化就优化，毕竟用户等的越久，体验就越差。

总结

本文详细介绍了 C# 后端集成 CodeBuddy CLI 的完整方案，涵盖了从架构设计到具体实现的全过程。通过分层架构设计，我们将协议细节与业务逻辑分离，使得代码更加清晰和可维护。

核心要点回顾：

采用 Provider 契约层、工厂层、实现层、基础设施层的分层架构
使用 JSON-RPC over Stdio 方式进行进程间通信
通过依赖注入实现灵活的配置和扩展
提供流式和非流式两种调用方式

这套方案不仅适用于 CodeBuddy，添加新的 AI Provider 也遵循同样的模式。如果你也在做类似的多 AI Provider 集成，希望这篇文章能给你一些参考。其实，写文章和写代码一样，分享出来，能帮到别人就算没白写。

参考资料

如果本文对你有帮助：

来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/
公测已开始，欢迎安装体验

HagiCode 平台的多 AI Provider 架构实践

2026年3月11日

HagiCode 平台的多 AI Provider 架构实践

本文分享了在 Orleans Grain 架构下，如何通过统一的 IAIProvider 接口集成 iflow 和 OpenCode 两个 AI 工具的技术方案，并详细对比了 WebSocket 和 HTTP 两种通信方式的实现差异。

背景

其实也没什么特别的，就是做 HagiCode 的时候遇到了个挺实际的问题——用户想用不同的 AI 工具，这倒也不奇怪，毕竟每个人都有自己的习惯。有的喜欢 Claude Code，有的钟爱 GitHub Copilot，还有些团队用自己开发的工具。

最开始的方案也挺简单粗暴的，就是给每个 AI 工具写专门的对接代码。可后来问题就来了——代码里全是 if-else，改一个地方要到处测试，新工具接入还得重新写一堆逻辑，想想都觉得累。

后来我想明白了，不如做一个统一的 IAIProvider 接口，把所有 AI 提供者的能力都抽象出来。这样，不管底层用的是哪个工具，对上层来说都是一样的调用方式，岂不美哉？

最近项目要接入两个新工具：iflow 和 OpenCode。这两个都支持 ACP 协议，但通信方式不太一样——iflow 用 WebSocket，OpenCode 用 HTTP API。这也算是种考验吧，要在统一的接口下适配两种不同的通信模式，不过想想也挺有意思的。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个基于 Orleans Grain 架构的 AI 辅助开发平台，通过统一的 IAIProvider 接口与不同的 AI 提供者集成，让用户可以灵活选择自己喜欢的 AI 工具。

架构设计

统一的接口抽象

首先，定义了 IAIProvider 接口，把所有 AI 提供者需要实现的能力都抽象出来：

public interface IAIProvider
{
    string Name { get; }
    bool SupportsStreaming { get; }
    ProviderCapabilities Capabilities { get; }

    Task<AIResponse> ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default);
    IAsyncEnumerable<AIStreamingChunk> StreamAsync(AIRequest request, CancellationToken cancellationToken = default);
    Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default);
    IAsyncEnumerable<AIStreamingChunk> SendMessageAsync(AIRequest request, string? embeddedCommandPrompt = null, CancellationToken cancellationToken = default);
}

这个接口有几个关键方法：

ExecuteAsync：执行一次性的 AI 请求
StreamAsync：流式获取响应，支持实时展示
PingAsync：健康检查，验证 provider 是否可用
SendMessageAsync：发送消息，支持嵌入式命令

IFlowCliProvider：基于 WebSocket 的实现

iflow 使用 WebSocket 进行 ACP 通信，整体架构是这样的：

IFlowCliProvider → ACPSessionManager → WebSocketAcpTransport → iflow CLI
                ↓
         动态端口分配 + 进程管理

核心流程也挺简单：

ACPSessionManager 负责创建和管理 ACP 会话
WebSocketAcpTransport 处理 WebSocket 通信
动态分配一个端口，用 iflow —experimental-acp —port 启动 iflow 进程
通过 IAIRequestToAcpMapper 和 IAcpToAIResponseMapper 做请求/响应的转换

来看看核心代码：

private async IAsyncEnumerable<AIStreamingChunk> StreamCoreAsync(
    AIRequest request,
    string? embeddedCommandPrompt,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
    // 解析工作目录
    var resolvedWorkingDirectory = ResolveWorkingDirectory(request);
    var effectiveRequest = ApplyEmbeddedCommandPrompt(request, embeddedCommandPrompt);

    // 创建 ACP 会话
    await using var session = await _sessionManager.CreateSessionAsync(
        Name,
        resolvedWorkingDirectory,
        cancellationToken,
        request.SessionId);

    // 发送提示词
    var prompt = _requestMapper.ToPromptString(effectiveRequest);
    var promptResponse = await session.SendPromptAsync(prompt, cancellationToken);

    // 接收流式响应
    await foreach (var notification in session.ReceiveUpdatesAsync(cancellationToken))
    {
        if (_responseMapper.TryConvertToStreamingChunk(notification, out var chunk))
        {
            if (chunk.Type == StreamingChunkType.Metadata && chunk.IsComplete)
            {
                yield return chunk;
                yield break;
            }
            yield return chunk;
        }
    }
}

这里有几个设计上的注意点，也算是一些小心得：

用 await using 确保会话正确释放，避免资源泄漏，毕竟资源这东西，不用了就该放归自然
流式响应通过 IAsyncEnumerable 返回，天然支持异步流
Metadata 类型的 chunk 判断是否完成，确保完整接收响应

OpenCodeCliProvider：基于 HTTP API 的实现

OpenCode 用 HTTP API 方式提供服务，架构略有不同：

OpenCodeCliProvider → OpenCodeRuntimeManager → OpenCodeClient → OpenCode HTTP API
                      ↓
                OpenCodeProcessManager → opencode 进程管理

OpenCode 的特点是用 SQLite 数据库持久化会话绑定关系，这样可以支持会话恢复和提示词响应恢复，这倒是挺贴心的设计：

private async Task<OpenCodePromptExecutionResult> ExecutePromptAsync(
    AIRequest request,
    string? embeddedCommandPrompt,
    CancellationToken cancellationToken)
{
    var prompt = BuildPrompt(request, embeddedCommandPrompt);
    var resolvedWorkingDirectory = ResolveWorkingDirectory(request.WorkingDirectory);
    var client = await _runtimeManager.GetClientAsync(resolvedWorkingDirectory, cancellationToken);
    var bindingSessionId = request.SessionId;
    var boundSession = TryGetBinding(bindingSessionId, resolvedWorkingDirectory);

    // 尝试使用已绑定的会话
    if (boundSession is not null)
    {
        try
        {
            return await PromptSessionAsync(
                client,
                boundSession,
                BuildPromptRequest(request, prompt, CreatePromptMessageId()),
                request.Model ?? _settings.Model,
                cancellationToken);
        }
        catch (OpenCodeApiException ex) when (IsStaleBinding(ex))
        {
            // 会话已过期，移除绑定
            RemoveBinding(bindingSessionId);
        }
    }

    // 创建新会话
    var session = await client.Session.CreateAsync(new OpenCodeSessionCreateRequest
    {
        Title = BuildSessionTitle(request)
    }, cancellationToken);

    BindSession(bindingSessionId, session.Id, resolvedWorkingDirectory);
    return await PromptSessionAsync(client, session.Id, ...);
}

这个实现有几个亮点，或者说几个有趣的地方：

会话绑定机制：同一个 SessionId 会复用 OpenCode 会话，避免重复创建，省得浪费资源
过期处理：检测到会话过期时自动清理绑定，旧的不去，新的不来
数据库持久化：通过 SQLite 存储绑定关系，重启后仍然有效，有些东西记住了就是记住了

两种方式的对比

方面	IFlowCliProvider	OpenCodeCliProvider
通信方式	WebSocket (ACP)	HTTP API
进程管理	ACPSessionManager	OpenCodeProcessManager
端口分配	动态端口	无端口（使用 HTTP）
会话管理	ACPSession	OpenCodeSession
持久化	内存缓存	SQLite 数据库
启动命令	iflow —experimental-acp —port	opencode
延迟	更低（长连接）	相对较高（HTTP 请求）

选择哪种方式主要看你的需求：WebSocket 适合实时性要求高的场景，HTTP API 则更简单、更容易调试。这就像选路一样，有的路快一点，有的路好走一点罢了。

实践指南

配置 Provider

先在配置文件里启用这两个 provider：

AI:
  Providers:
    IFlowCli:
      Type: "IFlowCli"
      Enabled: true
      ExecutablePath: "iflow"
      Model: null
      WorkingDirectory: null
    OpenCodeCli:
      Type: "OpenCodeCli"
      Enabled: true
      ExecutablePath: "opencode"
      Model: "anthropic/claude-sonnet-4"
      WorkingDirectory: null

OpenCode:
  Enabled: true
  BaseUrl: "http://localhost:38376"
  ExecutablePath: "opencode"
  StartupTimeoutSeconds: 30
  RequestTimeoutSeconds: 120

使用 IFlowCliProvider

// 通过 Factory 获取 provider
var provider = await _providerFactory.GetProviderAsync(AIProviderType.IFlowCli);

// 执行 AI 请求
var request = new AIRequest
{
    Prompt = "请帮我重构这个函数",
    WorkingDirectory = "/path/to/project",
    Model = "claude-sonnet-4"
};

// 获取完整响应
var response = await provider.ExecuteAsync(request, cancellationToken);
Console.WriteLine(response.Content);

// 或者用流式响应
await foreach (var chunk in provider.StreamAsync(request, cancellationToken))
{
    if (chunk.Type == StreamingChunkType.ContentDelta)
    {
        Console.Write(chunk.Content);
    }
}

使用 OpenCodeCliProvider

// 通过 Factory 获取 provider
var provider = await _providerFactory.GetProviderAsync(AIProviderType.OpenCodeCli);

var request = new AIRequest
{
    Prompt = "请帮我分析这个错误",
    WorkingDirectory = "/path/to/project",
    Model = "anthropic/claude-sonnet-4"
};

var response = await provider.ExecuteAsync(request, cancellationToken);
Console.WriteLine(response.Content);

健康检查

在启动或使用前，可以先检查 provider 是否可用：

var iflowResult = await iflowProvider.PingAsync(cancellationToken);
if (!iflowResult.Success)
{
    Console.WriteLine($"IFlow 不可用: {iflowResult.ErrorMessage}");
    return;
}

var openCodeResult = await openCodeProvider.PingAsync(cancellationToken);
if (!openCodeResult.Success)
{
    Console.WriteLine($"OpenCode 不可用: {openCodeResult.ErrorMessage}");
    return;
}

嵌入式命令支持

两个 provider 都支持嵌入式命令，比如 /file:xxx 这样的命令：

var request = new AIRequest
{
    Prompt = "分析这个文件的问题",
    SystemMessage = "你是一个代码分析专家"
};

await foreach (var chunk in provider.SendMessageAsync(
    request,
    embeddedCommandPrompt: "/file:src/main.cs",
    cancellationToken))
{
    Console.Write(chunk.Content);
}

注意事项和最佳实践

资源管理

IFlow 用 WebSocket 长连接，所以资源管理要特别注意：

用 await using 确保会话正确释放，不用了就放手
取消操作会触发进程清理
ACPSessionManager 支持最大会话数限制

OpenCode 的进程管理相对简单，OpenCodeRuntimeManager 会自动处理，省心不少。

错误处理

两个 provider 都有完善的错误处理：

IFlow 的错误通过 ACP 会话更新传播
OpenCode 的错误通过 OpenCodeApiException 抛出
建议在调用方捕获并处理这些异常，毕竟错误总会发生的

性能考虑

IFlow 的 WebSocket 通信比 HTTP 有更低的延迟
OpenCode 的会话复用可以减少 HTTP 请求开销
Factory 的缓存机制可以避免重复创建 provider
高并发场景下，要关注进程数和连接数的限制，别到时候撑不住了

配置验证

启动时会验证可执行文件路径，但运行时也可能出问题。PingAsync 是个好工具，可以验证配置是否正确：

// 启动时检查
var provider = await _providerFactory.GetProviderAsync(providerType);
var result = await provider.PingAsync(cancellationToken);
if (!result.Success)
{
    _logger.LogError("Provider {ProviderType} 不可用: {Error}", providerType, result.ErrorMessage);
}

总结

本文分享了 HagiCode 平台在集成 iflow 和 OpenCode 两个 AI 工具时的技术方案。通过统一的 IAIProvider 接口，实现了对不同通信方式（WebSocket 和 HTTP）的适配，同时保持了上层调用的一致性。

核心思路其实挺简单的：

定义统一的接口抽象
对不同实现做适配层
通过工厂模式统一管理

这样扩展性就很好，以后有新的 AI 工具要接入，只需要实现 IAIProvider 接口就行，不用改动太多现有代码。想想也挺合理的，就像搭积木一样，有统一的接口，想怎么拼都行。

如果你也在做多 AI 工具的集成，希望本文对你有帮助。不过话说回来，技术这东西，能帮到人就好，其他的也不必太在意…

参考资料

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode 官网: hagicode.com
HagiCode 安装指南: docs.hagicode.com/installation
ACP 协议规范: github.com/modelcontextprotocol/specification
Orleans 文档: learn.microsoft.com/dotnet/orleans

如果本文对你有帮助：

点个赞让更多人看到
来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/
公测已开始，欢迎安装体验

Codex SDK 控制台消息解析完全指南

2026年3月10日

Codex SDK 控制台消息解析完全指南

本文详细介绍 Codex SDK 的事件流机制、消息类型解析、以及在实际项目中的最佳实践，帮助开发者快速掌握 AI 执行服务的核心技能。

背景

其实，在构建基于 Codex SDK 的 AI 执行服务时，我们不得不面对这样一个问题：如何处理 Codex 返回的那些流式事件消息。这些消息里藏着执行状态、输出内容、错误信息这些重要的东西，就像青春里那些说不清道不明的心事，你得好好琢磨琢磨。

作为 HagiCode 项目的一部分，我们需要在 AI 代码助手场景中实现一个靠谱的执行器。这大概就是我们决定深入研究 Codex SDK 事件流机制的原因——毕竟，只有理解了底层消息是怎么运作的，才能构建出真正企业级的 AI 执行平台。这就像恋爱一样，不懂对方的心思，怎么走下去？

Codex SDK 是 OpenAI 推出的编程辅助工具 SDK，它通过事件流（Event Stream）的方式返回执行结果。和传统的请求-响应模式不太一样，Codex 使用流式事件，让我们能够：

实时获取执行进度
及时处理错误情况
获取详细的 token 使用统计
支持长时间运行的复杂任务

理解这些事件类型并正确解析它们，对于实现功能完善的 AI 执行器来说，还是挺重要的。毕竟，谁也不想面对一个黑盒？

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，致力于为开发者提供智能化的代码辅助能力。在开发过程中，我们需要构建可靠的 AI 执行服务来处理用户的代码执行请求，这正是我们引入 Codex SDK 的直接原因。

作为 AI 代码助手，HagiCode 需要处理各种复杂的代码执行场景：实时获取执行进度、及时处理错误情况、获取详细的 token 使用统计等。通过深入理解 Codex SDK 的事件流机制，我们能够构建出满足生产环境要求的执行器。说到底，代码也好，人生也罢，都需要一点积累和沉淀。

事件流机制

基本概念

Codex SDK 使用 thread.runStreamed() 方法返回异步事件迭代器：

import { Codex } from '@openai/codex-sdk';

const client = new Codex({
  apiKey: process.env.CODEX_API_KEY,
  baseUrl: process.env.CODEX_BASE_URL,
});

const thread = client.startThread({
  workingDirectory: '/path/to/project',
  skipGitRepoCheck: false,
});

const { events } = await thread.runStreamed('your prompt here', {
  outputSchema: {
    type: 'object',
    properties: {
      output: { type: 'string' },
      status: { type: 'string', enum: ['ok', 'action_required'] },
    },
    required: ['output', 'status'],
  },
});

for await (const event of events) {
  // 处理每个事件
}

事件类型详解

事件类型	说明	关键数据
`thread.started`	线程启动成功	`thread_id`
`item.updated`	消息内容更新	`item.text`
`item.completed`	消息完成	`item.text`
`turn.completed`	执行完成	`usage` (token 使用量)
`turn.failed`	执行失败	`error.message`
`error`	错误事件	`message`

在实际项目中，HagiCode 的执行器组件正是基于这些事件类型构建的。我们需要对每种事件进行精细化处理，以确保用户体验的流畅性。这就像对待一段感情，每个细节都需要用心对待，不然怎么可能有好的结果？

消息解析实现

消息内容提取

消息内容通过事件处理函数提取：

private handleThreadEvent(event: ThreadEvent, onMessage: (content: string) => void): void {
  // 只处理消息更新和完成事件
  if (event.type !== 'item.updated' && event.type !== 'item.completed') {
    return;
  }

  // 只处理代理消息类型
  if (event.item.type !== 'agent_message') {
    return;
  }

  // 提取文本内容
  onMessage(event.item.text);
}

关键点：

只处理 item.updated 和 item.completed 事件
只处理 agent_message 类型的内容
消息内容在 event.item.text 字段中

结构化输出解析

Codex 支持 JSON 结构化输出，通过 outputSchema 参数指定返回格式：

const DEFAULT_OUTPUT_SCHEMA = {
  type: 'object',
  properties: {
    output: { type: 'string' },
    status: { type: 'string', enum: ['ok', 'action_required'] },
  },
  required: ['output', 'status'],
  additionalProperties: false,
} as const;

解析函数会尝试解析 JSON，如果失败则返回原始文本——这就像人生，有时候你想要一个完美的答案，但现实往往给你一个模糊的回应，只能自己慢慢消化罢了。

function toStructuredOutput(raw: string): StructuredOutput {
  try {
    const parsed = JSON.parse(raw) as Partial<StructuredOutput>;
    if (typeof parsed.output === 'string') {
      return {
        output: parsed.output,
        status: parsed.status === 'action_required' ? 'action_required' : 'ok',
      };
    }
  } catch {
    // JSON 解析失败，回退到原始文本
  }

  return {
    output: raw,
    status: 'ok',
  };
}

完整的事件处理流程

private async runWithStreaming(
  thread: Thread,
  input: CodexStageExecutionInput
): Promise<{ output: string; usage: Usage | null }> {
  const abortController = new AbortController();
  const timeoutHandle = setTimeout(() => {
    abortController.abort();
  }, Math.max(1000, input.timeoutMs));

  let latestMessage = '';
  let usage: Usage | null = null;
  let emittedLength = 0;

  try {
    const { events } = await thread.runStreamed(input.prompt, {
      outputSchema: DEFAULT_OUTPUT_SCHEMA,
      signal: abortController.signal,
    });

    for await (const event of events) {
      // 处理消息内容
      this.handleThreadEvent(event, (nextContent) => {
        const delta = nextContent.slice(emittedLength);
        if (delta.length > 0) {
          emittedLength = nextContent.length;
          input.callbacks?.onChunk?.(delta);  // 流式回调
        }
        latestMessage = nextContent;
      });

      // 根据事件类型处理不同数据
      if (event.type === 'thread.started') {
        this.threadId = event.thread_id;
      } else if (event.type === 'turn.completed') {
        usage = event.usage;
      } else if (event.type === 'turn.failed') {
        throw new CodexExecutorError('gateway_unavailable', event.error.message, true);
      } else if (event.type === 'error') {
        throw new CodexExecutorError('gateway_unavailable', event.message, true);
      }
    }
  } catch (error) {
    if (abortController.signal.aborted) {
      throw new CodexExecutorError(
        'upstream_timeout',
        `Codex stage timed out after ${input.timeoutMs}ms`,
        true
      );
    }
    throw error;
  } finally {
    clearTimeout(timeoutHandle);
  }

  const structured = toStructuredOutput(latestMessage);
  return { output: structured.output, usage };
}

错误处理策略

错误码映射

根据错误特征映射到具体的错误码，便于上层处理：

function mapError(error: unknown): CodexExecutorError {
  if (error instanceof CodexExecutorError) {
    return error;
  }

  const message = error instanceof Error ? error.message : String(error);
  const normalized = message.toLowerCase();

  // 认证错误 - 不可重试
  if (normalized.includes('401') ||
      normalized.includes('403') ||
      normalized.includes('api key') ||
      normalized.includes('auth')) {
    return new CodexExecutorError('auth_invalid', message, false);
  }

  // 速率限制 - 可重试
  if (normalized.includes('429') || normalized.includes('rate limit')) {
    return new CodexExecutorError('rate_limited', message, true);
  }

  // 超时错误 - 可重试
  if (normalized.includes('timeout') || normalized.includes('aborted')) {
    return new CodexExecutorError('upstream_timeout', message, true);
  }

  // 默认错误
  return new CodexExecutorError('gateway_unavailable', message, true);
}

错误类型定义

export type CodexErrorCode =
  | 'auth_invalid'      // 认证失败
  | 'upstream_timeout'  // 上游超时
  | 'rate_limited'      // 速率限制
  | 'gateway_unavailable'; // 网关不可用

export class CodexExecutorError extends Error {
  readonly code: CodexErrorCode;
  readonly retryable: boolean;

  constructor(code: CodexErrorCode, message: string, retryable: boolean) {
    super(message);
    this.name = 'CodexExecutorError';
    this.code = code;
    this.retryable = retryable;
  }
}

工作目录与环境配置

工作目录验证

Codex SDK 要求工作目录必须是有效的 Git 仓库——这就像做人一样，总得有个根，有个出处，不然怎么踏实？

export function validateWorkingDirectory(
  workingDirectory: string,
  skipGitRepoCheck: boolean
): void {
  const resolvedWorkingDirectory = path.resolve(workingDirectory);

  if (!existsSync(resolvedWorkingDirectory)) {
    throw new CodexExecutorError(
      'gateway_unavailable',
      'Working directory does not exist.',
      false
    );
  }

  if (!statSync(resolvedWorkingDirectory).isDirectory()) {
    throw new CodexExecutorError(
      'gateway_unavailable',
      'Working directory is not a directory.',
      false
    );
  }

  if (skipGitRepoCheck) {
    return;
  }

  const gitDir = path.join(resolvedWorkingDirectory, '.git');
  if (!existsSync(gitDir)) {
    throw new CodexExecutorError(
      'gateway_unavailable',
      'Working directory is not a git repository.',
      false
    );
  }
}

环境变量加载

Codex SDK 需要从登录 Shell 加载环境变量，确保 AI Agent 可以访问系统命令：

function parseEnvironmentOutput(output: Buffer): Record<string, string> {
  const parsed: Record<string, string> = {};

  for (const entry of output.toString('utf8').split('\0')) {
    if (!entry) continue;

    const separatorIndex = entry.indexOf('=');
    if (separatorIndex <= 0) continue;

    const key = entry.slice(0, separatorIndex);
    const value = entry.slice(separatorIndex + 1);
    if (key.length > 0) {
      parsed[key] = value;
    }
  }

  return parsed;
}

function tryLoadEnvironmentFromShell(shellPath: string): Record<string, string> | null {
  const result = spawnSync(shellPath, ['-ilc', 'env -0'], {
    env: process.env,
    stdio: ['ignore', 'pipe', 'pipe'],
    timeout: 5000,
  });

  if (result.error || result.status !== 0) {
    return null;
  }

  return parseEnvironmentOutput(result.stdout);
}

export function createExecutorEnvironment(
  envOverrides: Record<string, string> = {}
): Record<string, string> {
  // 加载登录 Shell 环境变量
  const consoleEnv = loadConsoleEnvironmentFromShell();

  return {
    ...process.env,
    ...consoleEnv,
    ...envOverrides,
  };
}

完整使用示例

基本用法

在 HagiCode 项目中，我们使用以下方式来初始化 Codex 客户端并执行任务：

import { Codex } from '@openai/codex-sdk';

async function executeWithCodex(prompt: string, workingDir: string) {
  const client = new Codex({
    apiKey: process.env.CODEX_API_KEY,
    env: { PATH: process.env.PATH },
  });

  const thread = client.startThread({
    workingDirectory: workingDir,
  });

  const { events } = await thread.runStreamed(prompt);

  let result = '';
  for await (const event of events) {
    if (event.type === 'item.updated' && event.item.type === 'agent_message') {
      result = event.item.text;
    }
    if (event.type === 'turn.completed') {
      console.log('Token usage:', event.usage);
    }
  }

  // 尝试解析 JSON 输出
  try {
    const parsed = JSON.parse(result);
    return parsed.output;
  } catch {
    return result;
  }
}

带重试机制的完整实现

export class CodexSdkExecutor {
  private readonly config: CodexRuntimeConfig;
  private readonly client: Codex;
  private threadId: string | null = null;

  async executeStage(input: CodexStageExecutionInput): Promise<CodexStageExecutionResult> {
    const maxAttempts = Math.max(1, this.config.retryCount + 1);
    let attempt = 0;
    let lastError: CodexExecutorError | null = null;

    while (attempt < maxAttempts) {
      attempt += 1;

      try {
        const thread = this.getThread(input.workingDirectory);
        const { output, usage } = await this.runWithStreaming(thread, input);

        return {
          output,
          usage,
          threadId: this.threadId!,
          attempts: attempt,
          latencyMs: Date.now() - startedAt,
        };
      } catch (error) {
        const mappedError = mapError(error);
        lastError = mappedError;

        // 不可重试错误或已达最大重试次数
        if (!mappedError.retryable || attempt >= maxAttempts) {
          throw mappedError;
        }

        // 等待后重试
        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
      }
    }

    throw lastError!;
  }
}

最佳实践

1. 工作目录要求

确保工作目录是有效的 Git 仓库
使用 PROJECT_ROOT 环境变量显式指定
开发调试时可设置 CODEX_SKIP_GIT_REPO_CHECK=true 跳过检查

2. 环境变量配置

通过白名单机制传递必要的环境变量
使用登录 Shell 加载完整环境
避免传递敏感信息

3. 超时与重试

根据任务复杂度设置合理的超时时间
对可重试错误实现指数退避
记录重试次数和原因

4. 错误处理

区分可重试和不可重试错误
提供清晰的错误信息和建议
统一错误码便于上层处理

5. 流式输出

实现增量输出回调，提升用户体验
正确处理消息的增量更新
记录 token 使用量用于成本分析

在 HagiCode 项目的实际生产环境中，我们已经验证了上述最佳实践的有效性。这套方案帮助我们构建了稳定可靠的 AI 执行服务。毕竟，实践才是检验真理的唯一标准，纸上谈兵终究没什么用。

总结

Codex SDK 的事件流机制为构建 AI 执行服务提供了强大的能力。通过正确解析各类事件，我们可以：

实时获取执行状态和输出
实现可靠的错误处理和重试机制
获取详细的执行统计信息
构建功能完善的 AI 执行平台

本文介绍的核心概念和代码示例可以直接应用于实际项目中，帮助开发者快速上手 Codex SDK 的集成工作。如果你觉得这套方案有价值，说明 HagiCode 的工程实践还不错——那么 HagiCode 本身也值得关注一下。毕竟，有些东西，错过了就可惜了。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-09-codex-sdk-console-message-parsing/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

Hagicode 多 AI 提供者切换与互操作实现方案

2026年3月9日

Hagicode 多 AI 提供者切换与互操作实现方案

在现代开发工具生态中，开发者经常需要使用不同的 AI 编码助手来辅助开发工作。Anthropic 的 Claude Code CLI 和 OpenAI 的 Codex CLI 各有其优势：Claude 以出色的代码理解和长上下文处理能力著称，而 Codex 在代码生成和工具使用方面表现优异。

本文将深入分析 hagicode 项目如何实现多个 AI 提供者的无缝切换与互操作，包括核心架构设计、关键实现细节以及实践中的注意事项。

背景

问题域

hagicode 项目面临的核心挑战是在同一平台中支持多种 AI CLI，让用户能够：

根据需求灵活切换不同的 AI 提供者
在切换过程中保持会话状态的连续性
统一抽象不同 CLI 的 API 差异
为未来添加新的 AI 提供者预留扩展空间

技术挑战

接口差异统一：Claude Code CLI 通过命令行调用，Codex CLI 使用 JSON 事件流
流式响应处理：两种提供者都支持流式响应，但数据格式不同
工具调用语义：Claude 和 Codex 对工具调用的表示和生命周期管理不同
会话生命周期：需要正确管理每个提供者的会话创建、恢复和终止

分析

架构设计思路

hagicode 采用了提供者模式（Provider Pattern）结合工厂模式来抽象 AI 服务的调用。这种设计的核心思想是：

统一接口抽象：定义 IAIProvider 接口作为所有 AI 提供者的统一抽象
工厂创建实例：通过 AIProviderFactory 根据类型动态创建对应的提供者实例
智能选择逻辑：使用 AIProviderSelector 根据场景和配置自动选择最合适的提供者
会话状态管理：通过数据库持久化会话与 CLI 线程的绑定关系

关键组件

组件	职责	语言
`IAIProvider`	统一提供者接口	C#
`AIProviderFactory`	创建和管理提供者实例	C#
`AIProviderSelector`	智能选择提供者	C#
`ClaudeCodeCliProvider`	Claude Code CLI 实现	C#
`CodexCliProvider`	Codex CLI 实现	C#
`AgentCliManager`	桌面端 CLI 管理	TypeScript

解决

1. 核心接口设计

IAIProvider 接口 定义了统一的提供者抽象：

public interface IAIProvider
{
    /// <summary>
    /// 提供者显示名称
    /// </summary>
    string Name { get; }

    /// <summary>
    /// 是否支持流式响应
    /// </summary>
    bool SupportsStreaming { get; }

    /// <summary>
    /// 提供者能力描述
    /// </summary>
    ProviderCapabilities Capabilities { get; }

    /// <summary>
    /// 执行单个 AI 请求
    /// </summary>
    Task<AIResponse> ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default);

    /// <summary>
    /// 执行流式 AI 请求
    /// </summary>
    IAsyncEnumerable<AIStreamingChunk> StreamAsync(AIRequest request, CancellationToken cancellationToken = default);

    /// <summary>
    /// 检查提供者连接性和响应速度
    /// </summary>
    Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 发送带嵌入式命令的消息
    /// </summary>
    IAsyncEnumerable<AIStreamingChunk> SendMessageAsync(
        AIRequest request,
        string? embeddedCommandPrompt = null,
        CancellationToken cancellationToken = default);
}

接口设计的关键特性：

统一的请求/响应模型：所有提供者使用相同的 AIRequest 和 AIResponse 类型
流式支持：通过 IAsyncEnumerable<AIStreamingChunk> 统一流式输出
能力描述：ProviderCapabilities 描述提供者支持的功能（流式、工具、最大 token 等）
嵌入式命令：SendMessageAsync 支持将 OpenSpec 命令嵌入到提示中

2. 提供者类型枚举

public enum AIProviderType
{
    ClaudeCodeCli,   // Anthropic Claude Code
    OpenCodeCli,     // 其他 CLI（可扩展）
    GitHubCopilot,    // GitHub Copilot
    CodebuddyCli,    // Codebuddy
    CodexCli         // OpenAI Codex
}

这个枚举为系统支持的所有提供者提供了类型安全的表示。

3. 工厂模式实现

AIProviderFactory 负责创建和管理提供者实例：

public class AIProviderFactory : IAIProviderFactory
{
    private readonly ConcurrentDictionary<AIProviderType, IAIProvider> _cache;
    private readonly IOptions<AIProviderOptions> _options;
    private readonly IServiceProvider _serviceProvider;

    public Task<IAIProvider?> GetProviderAsync(AIProviderType providerType)
    {
        // 使用缓存避免重复创建
        if (_cache.TryGetValue(providerType, out var cached))
            return Task.FromResult<IAIProvider?>(cached);

        // 从配置中获取提供者配置
        var aiOptions = _options.Value;
        if (!aiOptions.Providers.TryGetValue(providerType, out var config))
        {
            _logger.LogWarning("Provider '{ProviderType}' not found in configuration", providerType);
            return Task.FromResult<IAIProvider?>(null);
        }

        // 根据类型创建提供者
        var provider = providerType switch
        {
            AIProviderType.ClaudeCodeCli =>
                _serviceProvider.GetService(typeof(ClaudeCodeCliProvider)) as IAIProvider,
            AIProviderType.CodexCli =>
                _serviceProvider.GetService(typeof(CodexCliProvider)) as IAIProvider,
            AIProviderType.GitHubCopilot =>
                _serviceProvider.GetService(typeof(CopilotAIProvider)) as IAIProvider,
            _ => null
        };

        if (provider != null)
        {
            _cache[providerType] = provider;
        }

        return Task.FromResult<IAIProvider?>(provider);
    }
}

工厂模式的优势：

实例缓存：避免重复创建相同类型的提供者
依赖注入：通过 IServiceProvider 创建实例，支持依赖注入
配置驱动：从配置文件读取提供者配置
异常处理：创建失败时返回 null，便于上层处理

4. 智能选择器

AIProviderSelector 实现提供者选择策略：

public class AIProviderSelector : IAIProviderSelector
{
    private readonly BusinessLayerConfiguration _configuration;
    private readonly IAIProviderFactory _providerFactory;
    private readonly IMemoryCache _cache;

    public async Task<AIProviderType> SelectProviderAsync(
        BusinessScenario scenario,
        CancellationToken cancellationToken = default)
    {
        // 1. 尝试从场景映射获取提供者
        if (_configuration.ScenarioProviderMapping.TryGetValue(scenario, out var providerType))
        {
            if (await IsProviderAvailableAsync(providerType, cancellationToken))
            {
                _logger.LogDebug("Selected provider '{Provider}' for scenario '{Scenario}'",
                    providerType, scenario);
                return providerType;
            }

            _logger.LogWarning("Configured provider '{Provider}' for scenario '{Scenario}' is not available",
                providerType, scenario);
        }

        // 2. 尝试使用默认提供者
        if (await IsProviderAvailableAsync(_configuration.DefaultProvider, cancellationToken))
        {
            _logger.LogDebug("Using default provider '{Provider}' for scenario '{Scenario}'",
                _configuration.DefaultProvider, scenario);
            return _configuration.DefaultProvider;
        }

        // 3. 尝试回退链
        foreach (var fallbackProvider in _configuration.FallbackChain)
        {
            if (await IsProviderAvailableAsync(fallbackProvider, cancellationToken))
            {
                _logger.LogInformation("Using fallback provider '{Provider}' for scenario '{Scenario}'",
                    fallbackProvider, scenario);
                return fallbackProvider;
            }
        }

        // 4. 无法找到可用提供者
        throw new InvalidOperationException(
            $"No available AI provider found for scenario '{scenario}'");
    }

    public async Task<bool> IsProviderAvailableAsync(
        AIProviderType providerType,
        CancellationToken cancellationToken = default)
    {
        var cacheKey = $"provider_available_{providerType}";

        // 使用缓存减少 Ping 调用
        if (_configuration.EnableCache &&
            _cache.TryGetValue<bool>(cacheKey, out var cached))
        {
            return cached;
        }

        var provider = await _providerFactory.GetProviderAsync(providerType);
        var isAvailable = provider != null;

        if (_configuration.EnableCache && isAvailable)
        {
            _cache.Set(cacheKey, isAvailable,
                TimeSpan.FromSeconds(_configuration.CacheExpirationSeconds));
        }

        return isAvailable;
    }
}

选择器策略：

场景映射优先：首先检查业务场景是否有特定的提供者映射
默认提供者回退：场景映射失败时使用默认提供者
回退链兜底：逐个尝试回退链中的提供者
可用性缓存：缓存提供者可用性检查结果，减少 Ping 调用

5. Claude Code CLI 提供者实现

public class ClaudeCodeCliProvider : IAIProvider
{
    private readonly ILogger<ClaudeCodeCliProvider> _logger;
    private readonly IClaudeStreamManager _streamManager;
    private readonly ProviderConfiguration _config;

    public string Name => "ClaudeCodeCli";
    public bool SupportsStreaming => true;

    public ProviderCapabilities Capabilities { get; }

    public async Task<AIResponse> ExecuteAsync(AIRequest request, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Executing AI request with provider: {Provider}", Name);

        var sessionOptions = ClaudeRequestMapper.MapToSessionOptions(request, _config);

        var messages = _streamManager.SendMessageAsync(request.Prompt, sessionOptions, cancellationToken);

        var responseBuilder = new StringBuilder();
        ResultMessage? finalResult = null;

        await foreach (var streamMessage in messages)
        {
            switch (streamMessage.Message)
            {
                case ResultMessage result:
                    finalResult = result;
                    responseBuilder.Append(result.Result);
                    break;
            }
        }

        if (finalResult != null)
        {
            return ClaudeResponseMapper.MapToAIResponse(finalResult, Name);
        }

        return new AIResponse
        {
            Content = responseBuilder.ToString(),
            FinishReason = FinishReason.Unknown,
            Provider = Name
        };
    }
}

Claude Code CLI 提供者的特点：

流式管理器集成：使用 IClaudeStreamManager 与 Claude CLI 通信
CessionId 会话隔离：使用 CessionId 作为会话唯一标识，与系统 sessionId 区分
工作目录配置：支持配置工作目录、权限模式等
工具支持：支持 AllowedTools、DisallowedTools 等工具权限配置

6. Codex CLI 提供者实现

public class CodexCliProvider : IAIProvider
{
    private readonly ILogger<CodexCliProvider> _logger;
    private readonly CodexSettings _settings;
    private readonly ConcurrentDictionary<string, string> _sessionThreadBindings;

    public string Name => "CodexCli";
    public bool SupportsStreaming => true;

    public ProviderCapabilities Capabilities { get; }

    public async IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Executing streaming AI request with provider: {Provider}", Name);

        var codex = CreateCodexClient();
        var thread = ResolveThread(codex, request);

        var currentTurn = 0;
        var activeToolCalls = new Dictionary<string, AIToolCallDelta>();

        await foreach (var threadEvent in thread.RunStreamedAsync(BuildPrompt(request), cancellationToken))
        {
            if (threadEvent is TurnStartedEvent)
            {
                currentTurn++;
            }

            switch (threadEvent)
            {
                case ItemCompletedEvent { Item: AgentMessageItem message }:
                    var messageText = message.Text ?? string.Empty;
                    yield return new AIStreamingChunk
                    {
                        Content = messageText,
                        Type = StreamingChunkType.ContentDelta,
                        IsComplete = false
                    };
                    break;

                case ItemStartedEvent or ItemUpdatedEvent or ItemCompletedEvent:
                    var toolChunk = BuildToolChunk(threadEvent, currentTurn);
                    if (toolChunk?.ToolCallDelta != null)
                    {
                        yield return toolChunk;
                    }
                    break;

                case TurnCompletedEvent turnCompleted:
                    activeToolCalls.Clear();
                    yield return new AIStreamingChunk
                    {
                        Content = string.Empty,
                        Type = StreamingChunkType.Metadata,
                        IsComplete = true,
                        Usage = MapUsage(turnCompleted.Usage)
                    };
                    break;
            }
        }

        BindSessionThread(request.SessionId, thread.Id);
    }

    private CodexThread ResolveThread(Codex codex, AIRequest request)
    {
        var sessionId = request.SessionId;

        // 检查是否已有绑定的线程
        if (!string.IsNullOrWhiteSpace(sessionId) &&
            _sessionThreadBindings.TryGetValue(sessionId, out var threadId) &&
            !string.IsNullOrWhiteSpace(threadId))
        {
            _logger.LogInformation("Resuming Codex thread {ThreadId} for session {SessionId}", threadId, sessionId);
            return codex.ResumeThread(threadId, threadOptions);
        }

        _logger.LogInformation("Starting new Codex thread for session {SessionId}", sessionId ?? "(none)");
        return codex.StartThread(threadOptions);
    }
}

Codex CLI 提供者的特点：

JSON 事件流处理：解析 Codex 的 JSON 事件流（TurnStarted、ItemStarted、TurnCompleted 等）
会话线程绑定：使用 SQLite 数据库持久化会话与线程的绑定关系
线程复用：支持恢复已有线程，保持会话连续性
工具调用追踪：追踪活动工具调用状态，正确处理工具生命周期

7. 会话线程绑定机制

Codex CLI 使用 SQLite 数据库持久化会话与线程的绑定：

public class CodexCliProvider : IAIProvider
{
    private const int SessionThreadBindingRetentionDays = 30;
    private readonly ConcurrentDictionary<string, string> _sessionThreadBindings;
    private readonly string _sessionThreadBindingDatabaseConnectionString;
    private readonly string _sessionThreadBindingDatabasePath;

    private void BindSessionThread(string? sessionId, string? threadId)
    {
        if (string.IsNullOrWhiteSpace(sessionId) || string.IsNullOrWhiteSpace(threadId))
        {
            return;
        }

        // 内存缓存
        _sessionThreadBindings.AddOrUpdate(sessionId, threadId, (_, _) => threadId);

        // 持久化到 SQLite
        PersistSessionThreadBinding(sessionId, threadId);
    }

    private void PersistSessionThreadBinding(string sessionId, string threadId)
    {
        try
        {
            using var connection = new SqliteConnection(_sessionThreadBindingDatabaseConnectionString);
            connection.Open();

            using var upsertCommand = connection.CreateCommand();
            upsertCommand.CommandText =
                """
                INSERT INTO SessionThreadBindings (SessionId, ThreadId, CreatedAtUtc, UpdatedAtUtc)
                VALUES ($sessionId, $threadId, $createdAtUtc, $updatedAtUtc)
                ON CONFLICT(SessionId) DO UPDATE SET
                    ThreadId = excluded.ThreadId,
                    UpdatedAtUtc = excluded.UpdatedAtUtc;
                """;
            var nowUtc = DateTimeOffset.UtcNow.ToString("O");
            upsertCommand.Parameters.AddWithValue("$sessionId", sessionId);
            upsertCommand.Parameters.AddWithValue("$threadId", threadId);
            upsertCommand.Parameters.AddWithValue("$createdAtUtc", nowUtc);
            upsertCommand.Parameters.AddWithValue("$updatedAtUtc", nowUtc);
            upsertCommand.ExecuteNonQuery();
        }
        catch (Exception ex)
        {
            _logger.LogWarning(
                ex,
                "Failed to persist Codex session-thread binding for session {SessionId} to {DatabasePath}",
                sessionId,
                _sessionThreadBindingDatabasePath);
        }
    }

    private void LoadPersistedSessionThreadBindings()
    {
        using var connection = new SqliteConnection(_sessionThreadBindingDatabaseConnectionString);
        connection.Open();

        using var loadCommand = connection.CreateCommand();
        loadCommand.CommandText = "SELECT SessionId, ThreadId FROM SessionThreadBindings;";
        using var reader = loadCommand.ExecuteReader();
        while (reader.Read())
        {
            var sessionId = reader.GetString(0);
            var threadId = reader.GetString(1);
            _sessionThreadBindings[sessionId] = threadId;
        }
    }
}

会话线程绑定的优势：

会话恢复：系统重启后可以恢复之前的会话
线程复用：同一会话可以复用已有的 Codex 线程
自动清理：超过 30 天的绑定会被自动清理

8. 桌面端 CLI 管理

hagicode-desktop 通过 AgentCliManager 管理 CLI 选择：

export enum AgentCliType {
  ClaudeCode = 'claude-code',
  Codex = 'codex',
  // 未来可扩展: Aider, Cursor 等其他 CLI
}

export class AgentCliManager {
  private static readonly STORE_KEY = 'agentCliSelection';
  private static readonly EXECUTOR_TYPE_MAP: Record<AgentCliType, string> = {
    [AgentCliType.ClaudeCode]: 'ClaudeCodeCli',
    [AgentCliType.Codex]: 'CodexCli',
  };

  constructor(private store: any) {}

  async saveSelection(cliType: AgentCliType): Promise<void> {
    const selection: StoredAgentCliSelection = {
      cliType,
      isSkipped: false,
      selectedAt: new Date().toISOString(),
    };

    this.store.set(AgentCliManager.STORE_KEY, selection);
  }

  loadSelection(): StoredAgentCliSelection {
    return this.store.get(AgentCliManager.STORE_KEY, {
      cliType: null,
      isSkipped: false,
      selectedAt: null,
    });
  }

  getCommandName(cliType: AgentCliType): string {
    switch (cliType) {
      case AgentCliType.ClaudeCode:
        return 'claude';
      case AgentCliType.Codex:
        return 'codex';
      default:
        return 'claude';
    }
  }

  getExecutorType(cliType: AgentCliType | null): string {
    if (!cliType) return 'ClaudeCodeCli';
    return this.EXECUTOR_TYPE_MAP[cliType] || 'ClaudeCodeCli';
  }
}

桌面端 IPC 处理器示例：

ipcMain.handle('llm:call-api', async (event, manifestPath, region) => {
  if (!state.llmInstallationManager) {
    return { success: false, error: 'LLM Installation Manager not initialized' };
  }

  try {
    const prompt = await state.llmInstallationManager.loadPrompt(manifestPath, region);

    // 根据用户选择确定 CLI 命令
    let commandName = 'claude';
    if (state.agentCliManager) {
      const selectedCliType = state.agentCliManager.getSelectedCliType();
      if (selectedCliType) {
        commandName = state.agentCliManager.getCommandName(selectedCliType);
      }
    }

    // 使用对应的 CLI 执行
    const result = await state.llmInstallationManager.callApi(
      prompt.filePath,
      event.sender,
      commandName
    );

    return result;
  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error'
    };
  }
});

9. Codex 内部的模型提供者系统

Codex 本身也支持多种模型提供者，通过 ModelProviderInfo 配置：

pub const OPENAI_PROVIDER_NAME: &str = "OpenAI";
pub const OLLAMA_OSS_PROVIDER_ID: &str = "ollama";
pub const LMSTUDIO_OSS_PROVIDER_ID: &str = "lmstudio";

pub fn built_in_model_providers() -> HashMap<String, ModelProviderInfo> {
    use ModelProviderInfo as P;

    [
        ("openai", P::create_openai_provider()),
        (OLLAMA_OSS_PROVIDER_ID, create_oss_provider(DEFAULT_OLLAMA_PORT, WireApi::Responses)),
        (LMSTUDIO_OSS_PROVIDER_ID, create_oss_provider(DEFAULT_LMSTUDIO_PORT, WireApi::Responses)),
    ]
    .into_iter()
    .map(|(k, v)| (k.to_string(), v))
    .collect()
}

pub struct ModelProviderInfo {
    pub name: String,
    pub base_url: Option<String>,
    pub env_key: Option<String>,
    pub query_params: Option<HashMap<String, String>>,
    pub http_headers: Option<HashMap<String, String>>,
    pub request_max_retries: Option<u64>,
    pub stream_max_retries: Option<u64>,
    pub stream_idle_timeout_ms: Option<u64>,
    pub requires_openai_auth: bool,
    pub supports_websockets: bool,
}

Codex 的模型提供者支持：

内置提供者：OpenAI、Ollama、LM Studio
自定义提供者：用户可在 config.toml 中添加自定义提供者
重试策略：可配置请求和流的重试次数
WebSocket 支持：部分提供者支持 WebSocket 传输

实践

配置示例

appsettings.json 配置多个提供者：

{
  "AI": {
    "Providers": {
      "DefaultProvider": "ClaudeCodeCli",
      "Providers": {
        "ClaudeCodeCli": {
          "Type": "ClaudeCodeCli",
          "Model": "claude-sonnet-4-20250514",
          "WorkingDirectory": "/path/to/workspace",
          "PermissionMode": "acceptEdits",
          "AllowedTools": ["file-edit", "command-run", "bash"]
        },
        "CodexCli": {
          "Type": "CodexCli",
          "Model": "gpt-4.1",
          "ExecutablePath": "codex",
          "SandboxMode": "enabled",
          "WebSearchMode": "auto",
          "NetworkAccessEnabled": false
        }
      },
      "ScenarioProviderMapping": {
        "CodeAnalysis": "ClaudeCodeCli",
        "CodeGeneration": "CodexCli",
        "Refactoring": "ClaudeCodeCli",
        "Debugging": "CodexCli"
      },
      "FallbackChain": ["CodexCli", "ClaudeCodeCli"]
    },
    "Selector": {
      "EnableCache": true,
      "CacheExpirationSeconds": 300
    }
  }
}

使用示例 - 后端服务

public class AIOrchestrator
{
    private readonly IAIProviderFactory _providerFactory;
    private readonly IAIProviderSelector _providerSelector;
    private readonly ILogger<AIOrchestrator> _logger;

    public AIOrchestrator(
        IAIProviderFactory providerFactory,
        IAIProviderSelector providerSelector,
        ILogger<AIOrchestrator> logger)
    {
        _providerFactory = providerFactory;
        _providerSelector = providerSelector;
        _logger = logger;
    }

    public async Task<AIResponse> ProcessRequestAsync(
        AIRequest request,
        BusinessScenario scenario)
    {
        _logger.LogInformation("Processing request for scenario: {Scenario}", scenario);

        try
        {
            // 智能选择提供者
            var providerType = await _providerSelector.SelectProviderAsync(scenario, request.CancellationToken);

            // 获取提供者实例
            var provider = await _providerFactory.GetProviderAsync(providerType);
            if (provider == null)
            {
                throw new InvalidOperationException($"Provider {providerType} not available");
            }

            _logger.LogInformation("Using provider: {Provider} for request", provider.Name);

            // 执行请求
            var response = await provider.ExecuteAsync(request, request.CancellationToken);

            _logger.LogInformation("Request completed with provider: {Provider}, tokens used: {Tokens}",
                provider.Name,
                response.Usage?.TotalTokens ?? 0);

            return response;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to process request for scenario: {Scenario}", scenario);
            throw;
        }
    }
}

使用示例 - 流式响应

public async IAsyncEnumerable<AIStreamingChunk> StreamResponseAsync(
    AIRequest request,
    BusinessScenario scenario)
{
    var providerType = await _providerSelector.SelectProviderAsync(scenario);
    var provider = await _providerFactory.GetProviderAsync(providerType);

    if (provider == null)
    {
        throw new InvalidOperationException($"Provider {providerType} not available");
    }

    await foreach (var chunk in provider.StreamAsync(request))
    {
        // 处理流式块
        switch (chunk.Type)
        {
            case StreamingChunkType.ContentDelta:
                // 实时显示文本内容
                await SendToClientAsync(chunk.Content);
                break;

            case StreamingChunkType.ToolCallDelta:
                // 处理工具调用
                await HandleToolCallAsync(chunk.ToolCallDelta);
                break;

            case StreamingChunkType.Metadata:
                // 处理完成事件和统计
                if (chunk.IsComplete)
                {
                    _logger.LogInformation("Stream completed, usage: {@Usage}", chunk.Usage);
                }
                break;

            case StreamingChunkType.Error:
                // 处理错误
                _logger.LogError("Stream error: {Error}", chunk.ErrorMessage);
                throw new InvalidOperationException(chunk.ErrorMessage);
        }
    }
}

使用示例 - OpenSpec 命令

public async Task<string> ExecuteOpenSpecCommandAsync(
    string command,
    string arguments,
    BusinessScenario scenario)
{
    var providerType = await _providerSelector.SelectProviderAsync(scenario);
    var provider = await _providerFactory.GetProviderAsync(providerType);

    // 构建嵌入式命令提示
    var commandPrompt = $"""
        Execute the following OpenSpec command:
        Command: {command}
        Arguments: {arguments}

        Please execute this command and return the results.
        """;

    var request = new AIRequest
    {
        Prompt = "Process this command request",
        EmbeddedCommandPrompt = commandPrompt,
        WorkingDirectory = Directory.GetCurrentDirectory()
    };

    var response = await provider.SendMessageAsync(request, commandPrompt);

    return response.Content;
}

注意事项

1. 提供者健康检查

在切换提供者前，建议先调用 PingAsync 确保目标提供者可用：

public async Task<bool> IsProviderHealthyAsync(AIProviderType providerType)
{
    var provider = await _providerFactory.GetProviderAsync(providerType);
    if (provider == null) return false;

    var testResult = await provider.PingAsync();

    return testResult.Success &&
           testResult.ResponseTimeMs < 5000; // 5 秒内响应视为健康
}

2. 会话隔离

使用 CessionId（Claude）或 ThreadId（Codex）确保会话隔离：

Claude Code CLI：使用 CessionId 作为会话唯一标识
Codex CLI：使用 ThreadId 作为会话标识

// Claude Code CLI 会话选项
var claudeSessionOptions = new ClaudeSessionOptions
{
    CessionId = CessionId.New(),  // 生成唯一 ID
    WorkingDirectory = workspacePath,
    AllowedTools = allowedTools,
    PermissionMode = PermissionMode.acceptEdits
};

// Codex 线程选项
var codexThreadOptions = new ThreadOptions
{
    Model = "gpt-4.1",
    SandboxMode = "enabled",
    WorkingDirectory = workspacePath
};

3. 错误处理

提供者不可用时的回退机制要健壮，确保至少有一个可用提供者：

public async Task<AIResponse> ExecuteWithFallbackAsync(
    AIRequest request,
    List<AIProviderType> preferredProviders)
{
    Exception? lastException = null;

    foreach (var providerType in preferredProviders)
    {
        try
        {
            var provider = await _providerFactory.GetProviderAsync(providerType);
            if (provider == null) continue;

            // 尝试执行
            return await provider.ExecuteAsync(request);
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "Provider {ProviderType} failed, trying next", providerType);
            lastException = ex;
        }
    }

    // 所有提供者都失败
    throw new InvalidOperationException(
        "All preferred providers failed. Last error: " + lastException?.Message,
        lastException);
}

4. 配置验证

启动时验证所有配置的提供者设置，避免运行时错误：

public void ValidateConfiguration(AIProviderOptions options)
{
    foreach (var (providerType, config) in options.Providers)
    {
        // 验证可执行文件路径（CLI 类型提供者）
        if (IsCliBasedProvider(providerType))
        {
            if (string.IsNullOrWhiteSpace(config.ExecutablePath))
            {
                throw new ConfigurationException(
                    $"Provider {providerType} requires ExecutablePath");
            }

            if (!File.Exists(config.ExecutablePath))
            {
                throw new ConfigurationException(
                    $"Executable not found for {providerType}: {config.ExecutablePath}");
            }
        }

        // 验证 API 密钥（API 类型提供者）
        if (IsApiBasedProvider(providerType))
        {
            if (string.IsNullOrWhiteSpace(config.ApiKey))
            {
                throw new ConfigurationException(
                    $"Provider {providerType} requires ApiKey");
            }
        }

        // 验证模型名称
        if (string.IsNullOrWhiteSpace(config.Model))
        {
            _logger.LogWarning("No model configured for {ProviderType}, using default", providerType);
        }
    }
}

5. 缓存管理

提供者实例会被缓存，注意生命周期管理和内存使用：

// 定期清理缓存
public void ClearInactiveProviders(TimeSpan inactiveThreshold)
{
    var now = DateTimeOffset.UtcNow;
    var keysToRemove = new List<AIProviderType>();

    foreach (var (type, instance) in _cache)
    {
        // 假设提供者有 LastUsedTime 属性
        if (instance.LastUsedTime.HasValue &&
            now - instance.LastUsedTime.Value > inactiveThreshold)
        {
            keysToRemove.Add(type);
        }
    }

    foreach (var key in keysToRemove)
    {
        _cache.TryRemove(key, out _);
        _logger.LogInformation("Cleared inactive provider: {Provider}", key);
    }
}

6. 日志记录

详细记录提供者选择、切换和执行过程，便于调试：

public class AIProviderLogging
{
    private readonly ILogger _logger;

    public void LogProviderSelection(
        BusinessScenario scenario,
        AIProviderType selectedProvider,
        SelectionReason reason)
    {
        _logger.LogInformation(
            "[ProviderSelection] Scenario={Scenario}, Provider={Provider}, Reason={Reason}",
            scenario,
            selectedProvider,
            reason);
    }

    public void LogProviderSwitch(
        AIProviderType fromProvider,
        AIProviderType toProvider,
        string reason)
    {
        _logger.LogWarning(
            "[ProviderSwitch] From={FromProvider} To={ToProvider}, Reason={Reason}",
            fromProvider,
            toProvider,
            reason);
    }

    public void LogProviderError(
        AIProviderType provider,
        Exception error,
        AIRequest request)
    {
        _logger.LogError(error,
            "[ProviderError] Provider={Provider}, RequestLength={Length}, Error={Message}",
            provider,
            request.Prompt.Length,
            error.Message);
    }
}

7. 线程安全

ConcurrentDictionary 等并发集合的使用确保线程安全：

public class ThreadSafeProviderCache
{
    private readonly ConcurrentDictionary<AIProviderType, IAIProvider> _cache;
    private readonly ReaderWriterLockSlim _lock = new();

    public IAIProvider? GetProvider(AIProviderType type)
    {
        // 读取操作无需锁
        if (_cache.TryGetValue(type, out var provider))
            return provider;

        // 创建需要写锁
        _lock.EnterWriteLock();
        try
        {
            // 双重检查
            if (_cache.TryGetValue(type, out provider))
                return provider;

            var newProvider = CreateProvider(type);
            if (newProvider != null)
            {
                _cache[type] = newProvider;
            }
            return newProvider;
        }
        finally
        {
            _lock.ExitWriteLock();
        }
    }
}

8. 数据库迁移

会话线程绑定数据库结构变更时需要考虑数据迁移：

public class SessionThreadMigration
{
    public async Task MigrateAsync(string dbPath)
    {
        var version = await GetSchemaVersionAsync(dbPath);

        if (version >= 2) return; // 已是最新版本

        using var connection = new SqliteConnection(dbPath);
        connection.Open();

        // 迁移到 v2：添加 CreatedAtUtc 列
        if (version < 2)
        {
            _logger.LogInformation("Migrating SessionThreadBindings to v2...");

            using var addColumnCommand = connection.CreateCommand();
            addColumnCommand.CommandText = "ALTER TABLE SessionThreadBindings ADD COLUMN CreatedAtUtc TEXT;";
            addColumnCommand.ExecuteNonQuery();

            using var backfillCommand = connection.CreateCommand();
            backfillCommand.CommandText =
                """
                UPDATE SessionThreadBindings
                SET CreatedAtUtc = COALESCE(NULLIF(UpdatedAtUtc, ''), $nowUtc)
                WHERE CreatedAtUtc IS NULL OR CreatedAtUtc = '';
                """;
            backfillCommand.Parameters.AddWithValue("$nowUtc", DateTimeOffset.UtcNow.ToString("O"));
            backfillCommand.ExecuteNonQuery();
        }

        await UpdateSchemaVersionAsync(dbPath, 2);
        _logger.LogInformation("Migration to v2 completed");
    }
}

总结

hagicode 通过提供者模式、工厂模式和选择器模式的组合，实现了一个灵活、可扩展的多 AI 提供者架构：

统一接口抽象：IAIProvider 接口屏蔽了不同 CLI 的差异
动态实例创建：AIProviderFactory 支持运行时创建提供者实例
智能选择策略：AIProviderSelector 实现场景驱动的提供者选择
会话状态持久化：通过数据库绑定确保会话连续性
桌面端集成：AgentCliManager 支持用户选择和配置

这种架构设计的优势在于：

可扩展性：添加新的 AI 提供者只需实现 IAIProvider 接口
可测试性：提供者可以独立测试和模拟
可维护性：每个提供者的实现独立，职责单一
用户友好：支持场景自动选择和手动切换

通过这种设计，hagicode 成功实现了 Claude Code CLI 和 Codex CLI 的无缝切换与互操作，为开发者提供了灵活、强大的 AI 编码助手体验。

参考资料

HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
Claude Code 官方文档：docs.anthropic.com
OpenAI Codex 文档：platform.openai.com
Codex SDK 官方仓库：github.com/openai/codex
HagiCode 多平台 CLI 支持：https://docs.hagicode.com/blog/hagicode-ai-cli-multi-platform-support/

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-09-hagicode-multi-ai-provider-switching-interop/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载时请注明出处!

从 TypeScript 到 C#：Codex SDK 的跨语言移植实践

2026年3月7日

从 TypeScript 到 C#：Codex SDK 的跨语言移植实践

怎么说呢，这篇文章也算是个孩子，记录了我们把官方 TypeScript Codex SDK 完整移植到 C# 的全过程。说是”移植”，其实更像是一场漫长的冒险，毕竟两种语言的脾性不太一样，总得想办法让它们好好相处。

背景

Codex 这东西，是 OpenAI 推出的 AI Agent CLI 工具，确实挺强大的。官方给了 TypeScript SDK，放在 @openai/codex 这个包里。它呢，通过调用 codex exec --experimental-json 命令跟 Codex CLI 交互，解析 JSONL 格式的事件流。

可是吧，我们在 HagiCode 项目里，需要在一个纯 .NET 环境中使用它。具体来说，就是 C# 后端服务和桌面端应用。你说这事闹的，总不能为了调用一个 CLI 工具而在 .NET 项目中引入 Node.js 运行时吧？那也太折腾了。

于是摆在我们面前的就两条路：一是维护一套复杂的 Node.js 桥接层，二是自己动手丰衣足食，实现一个原生 C# SDK。

我们选择了后者。

关于 HagiCode

其实这篇文也是来自我们在 HagiCode 项目里的实践经验。HagiCode 是个开源的 AI 代码助手项目，听起来挺高大上的，但说白了也就是同时维护着前端 VSCode 扩展、后端 AI 服务、跨平台桌面客户端等多种组件。这种多语言、多平台的复杂度，正是我们需要原生 C# SDK 的直接原因——总不能真的在 .NET 项目里跑个 Node.js 吧？那也太魔幻了。

如果你觉得这篇文章有点帮助，欢迎来 GitHub 给个 Star：github.com/HagiCode-org/site，也欢迎访问官网了解更多：hagicode.com。毕竟一个人品无限的项目能得到支持，也是件开心的事。

核心内容

架构设计对比

在开始代码层面的转化之前，我们得先理解两套 SDK 的架构设计。毕竟知己知彼，百战不殆嘛。

TypeScript SDK 的核心架构是这样的：

Codex (入口类)
  └── CodexExec (执行器，管理子进程)
      └── Thread (对话线程)
          ├── run() / runStreamed() (同步/异步执行)
          └── 事件流解析

C# SDK 呢，保持了相同的架构层次，但在实现细节上做了适配。整体思路是：保持 API 的一致性，但在具体实现上充分利用 C# 语言特性。毕竟语言不同，总得有点区别才行。

类型系统转化

这是最基础也是最重要的工作。毕竟万丈高楼平地起，基础打不好，后面全是麻烦。

TypeScript 的类型系统比 C# 更灵活，这是事实。我们需要找到合适的映射方式：

TypeScript	C#	说明
`interface` / `type`	`record`	C# 使用 record 实现不可变数据结构
`string \| null`	`string?`	可空引用类型
`boolean \| undefined`	`bool?`	可空布尔值
`AsyncGenerator`	`IAsyncEnumerable`	异步迭代器

事件类型系统是一个典型的例子。TypeScript 使用联合类型来定义事件：

export type ThreadEvent =
  | ThreadStartedEvent
  | TurnStartedEvent
  | TurnCompletedEvent
  | ...

在 C# 中，我们使用继承层次和模式匹配来实现类似的效果：

public abstract record ThreadEvent(string Type);

public sealed record ThreadStartedEvent(string ThreadId) : ThreadEvent("thread.started");
public sealed record TurnStartedEvent() : ThreadEvent("turn.started");
public sealed record TurnCompletedEvent(Usage Usage) : ThreadEvent("turn.completed");
// ...

使用 record 而不是 class，是因为事件对象应该是不可变的，这和 TypeScript 中使用普通对象是一个道理。而 sealed 关键字则确保不会有额外的子类继承，编译器可以进行优化。其实也就那么回事，习惯就好了。

核心转化点

1. 事件解析器

事件解析是整个 SDK 的核心，毕竟这决定了我们能否正确理解 Codex CLI 返回的每一条信息。解析错了，后面全是白忙活。

TypeScript 版本使用 JSON.parse() 来解析每一行 JSON：

export function parseEvent(line: string): ThreadEvent {
  const data = JSON.parse(line);
  // 处理各种事件类型...
}

C# 版本则使用 System.Text.Json.JsonDocument：

public static ThreadEvent Parse(string line)
{
    using var document = JsonDocument.Parse(line);
    var root = document.RootElement;
    var type = GetRequiredString(root, "type", "event.type");

    return type switch
    {
        "thread.started" => new ThreadStartedEvent(GetRequiredString(root, "thread_id", ...)),
        "turn.started" => new TurnStartedEvent(),
        "turn.completed" => new TurnCompletedEvent(ParseUsage(...)),
        // ...
        _ => new UnknownThreadEvent(type, root.Clone()),
    };
}

这里有一个小技巧：root.Clone() 是必要的，因为 JsonDocument 的元素在文档释放后就会失效，我们需要保留一份副本给未知的事件类型。这也是没办法的事，毕竟 C# 的 JSON 处理和 JavaScript 不太一样。

2. 进程管理差异

这是两个 SDK 差异最大的地方。毕竟 Node.js 和 .NET 的脾性不太一样，总得适应适应。

TypeScript 使用 Node.js 的 spawn() 函数：

const child = spawn(this.executablePath, commandArgs, { env, signal });

C# 使用 .NET 的 System.Diagnostics.Process：

using var process = new Process { StartInfo = startInfo };
process.Start();

// 需要手动管理 stdin/stdout/stderr

具体来说，C# 版本需要这样配置进程：

var startInfo = new ProcessStartInfo
{
    FileName = _executablePath,
    RedirectStandardInput = true,
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    UseShellExecute = false,
    CreateNoWindow = true,
};

最大的区别在于取消机制。TypeScript 使用 AbortSignal，这是 Web API 的一部分，用起来挺顺手的：

const child = spawn(cmd, args, { signal: cancellationSignal });

C# 则使用 CancellationToken：

public async IAsyncEnumerable<string> RunAsync(
    CodexExecArgs args,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    // 在循环中检查取消状态
    while (!cancellationToken.IsCancellationRequested)
    {
        // 处理输出...
    }

    // 取消时终止进程
    if (cancellationToken.IsCancellationRequested)
    {
        try { process.Kill(entireProcessTree: true); } catch { }
    }
}

这其中的区别，大概就是Web API 和 .NET 生态的差异吧，说到底也就是那么回事。

3. 配置序列化的保持

两套 SDK 都实现了将 JSON 配置转换为 TOML 配置的逻辑，因为 Codex CLI 接受 TOML 格式的配置覆盖。这部分逻辑必须完全保持一致，否则同样的配置在两个 SDK 中会产生不同的行为。

这叫什么？这就叫工匠精神嘛。毕竟细节决定成败，有些事不能将就。

实现细节

项目结构

我们创建了这样的项目结构：

CodexSdk/
├── CodexSdk.csproj
├── Codex.cs           # 入口类
├── CodexThread.cs     # 对话线程
├── CodexExec.cs       # 执行器
├── Events.cs          # 事件类型定义
├── Items.cs           # 项目类型定义
├── EventParser.cs     # 事件解析器
├── OutputSchemaTempFile.cs  # 临时文件管理
└── ...

看起来也挺整齐的，不是吗？

使用示例

基本的使用方式和 TypeScript SDK 保持一致：

using CodexSdk;

// 创建 Codex 实例
var codex = new Codex();
var thread = codex.StartThread();

// 执行查询
var result = await thread.RunAsync("Summarize this repository.");
Console.WriteLine(result.FinalResponse);

流式事件处理利用了 C# 的模式匹配能力：

await foreach (var @event in thread.RunStreamedAsync("Analyze the code."))
{
    switch (@event)
    {
        case ItemCompletedEvent itemCompleted
            when itemCompleted.Item is AgentMessageItem msg:
            Console.WriteLine($"Assistant: {msg.Text}");
            break;
        case TurnCompletedEvent completed:
            Console.WriteLine($"Tokens: in={completed.Usage.InputTokens}");
            break;
        case CommandExecutionItem command:
            Console.WriteLine($"Command: {command.Command}");
            break;
    }
}

注意事项

在实现过程中，我们也不算是白忙活，总结点经验如下：

进程管理：C# 版本需要手动管理进程的生命周期，包括取消时的进程终止。使用 Kill(entireProcessTree: true) 确保子进程也被清理。这叫什么？这就叫有始有终。
错误处理：我们使用 InvalidOperationException 抛出解析错误，保持与 TypeScript SDK 相似的错误处理方式。毕竟错误处理这事儿，不能太随意。
资源清理：OutputSchemaTempFile 实现 IAsyncDisposable，确保临时文件被正确清理。这也是没办法的事，资源不清理干净，总会有问题。
环境变量：C# 版本支持通过 CodexOptions.Env 完全覆盖进程环境变量。这功能虽然小，但挺实用的。
平台差异：C# 版本不包含 TypeScript 版本中自动查找 npm 包中二进制文件的逻辑。这是因为 .NET 项目通常不依赖 npm，所以需要通过 CODEX_EXECUTABLE 环境变量或 CodexPathOverride 指定 codex 可执行文件路径。这叫什么？这就叫因地制宜。

总结

将一个成熟的 TypeScript SDK 移植到 C#，不仅仅是语法层面的转换，更是对两种语言设计哲学的理解。TypeScript 的灵活性和 JavaScript 生态特性（如 AbortSignal）在 C# 中需要找到对应的替代方案。这其中的酸甜苦辣，大概也只有真正做过的人才能体会。

关键体会是：保持 API 的一致性比保持实现细节的一致性更重要。用户关心的是接口是否易用，而不是内部实现是否相同。这话听起来简单，但做起来需要取舍。

如果你也在做类似的跨语言移植工作，我们的经验是：先完整理解原 SDK 的架构设计，然后逐个模块进行转化，最后通过完整的测试用例确保行为一致。毕竟急不得，一口吃不成胖子。

一切都会好的，都会有的…

参考资料

官方 TypeScript SDK：github.com/openai/codex
C# SDK 源码：github.com/HagiCode-org/site/tree/main/repos/playground/CodexDotnet
Codex 官方文档：codex.docs.anysphere.co

如果本文对你有帮助：

来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/
公测已开始，欢迎安装体验

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-07-codex-sdk-typescript-to-csharp-porting-guide/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

豆包语音识别热词功能实现指南

2026年3月6日

豆包语音识别热词功能实现指南

本文将详细介绍如何在 HagiCode 项目中实现豆包语音识别的热词支持功能，通过自定义热词和平台热词表两种方式，显著提升特定领域词汇的识别准确率。

背景

语音识别技术发展这么多年了，其实有个问题一直困扰着开发者们。通用语音识别模型虽然能覆盖日常用语，可对于专业术语、产品名称、人名这些词，识别准确率总差那么点意思。想想看，医疗领域的语音助手要准确识别”高血压”、“糖尿病”、“冠心病”；法律系统要精准捕捉”案由”、“答辩”、“举证责任”——这些场景下，通用模型的表现怎么说呢，也算尽力了。

在 HagiCode 项目中，我们也遇到了同样的挑战。作为一个多功能的 AI 代码助手，HagiCode 需要处理各种技术术语的语音识别场景。然而，豆包语音识别 API 在默认情况下，并不能完全满足我们对专业术语准确率的那些要求。其实也不是豆包不够好，只是每个领域都有自己的一套术语体系。经过一番调研和技术探索，我们发现豆包语音识别 API 实际上提供了热词支持功能，只要简单配置一下，就能显著提升特定词汇的识别准确率。这倒是有点像，你告诉它你要注意什么词，它就会更用心去听那些词。

本文要分享的，就是在 HagiCode 项目中实现豆包语音识别热词功能的完整方案。两种模式，自定义热词和平台热词表，都可以用，也都能组合用。通过这套方案，开发者可以根据业务场景灵活配置热词，让语音识别系统”认识”那些专业、罕见但又至关重要的词汇。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，技术栈还算现代化，旨在为开发者提供智能化的编程辅助体验。作为一个多语言、多平台的复杂项目，HagiCode 需要处理各种技术术语的语音识别场景，这也推动了我们对热词功能的研究和实现。

如果你对 HagiCode 的技术实现感兴趣，可以访问 GitHub 仓库了解更多信息，也可以查看我们的官方文档了解完整的安装和使用指南。

核心实现

两种热词模式解析

豆包语音识别 API 为我们提供了两种热词配置方式，每种方式都有其独特的应用场景和优势。

自定义热词模式允许我们通过 corpus.context 字段直接传递热词文本。这种方式非常适合需要快速配置少量热词的场景，比如临时需要识别某个产品名称或者人名。在 HagiCode 的实现中，我们将用户输入的多行热词文本解析为字符串列表，然后按照豆包 API 的要求格式化为 context_data 数组。怎么说呢，这种方式很直接，就像告诉对方”你要注意这些词”，然后它就去注意了。

平台热词表模式则通过 corpus.boosting_table_id 字段引用豆包自学习平台预配置的热词表。这种方式适合需要管理大量热词的场景，我们可以在豆包自学习平台上创建和维护热词表，然后通过 ID 进行引用。对于 HagiCode 这类需要持续更新和维护专业术语的项目来说，这种模式提供了更好的可管理性。毕竟，热词多了之后，找个地方统一管理，总比每次都要手动输入要好。

有意思的是，这两种模式还可以组合使用。豆包 API 支持在同一个请求中同时包含自定义热词和平台热词表 ID，通过 combine_mode 参数控制组合策略。这种灵活性使得 HagiCode 能够应对各种复杂的专业术语识别需求。这也倒是挺好，有时候多种方式组合一下，效果可能更好。

前端类型定义与验证

在 HagiCode 的前端实现中，我们定义了一套完整的热词配置类型和验证逻辑。首先是类型定义部分：

export interface HotwordConfig {
  contextText: string;           // 多行热词文本
  boostingTableId: string;      // 豆包平台热词表 ID
  combineMode: boolean;          // 是否组合使用
}

这个简单的接口包含了热词功能的所有配置项。其中 contextText 是用户最直观感受到的部分——我们允许用户每行输入一个热词短语，这种方式非常符合直觉。毕竟，让用户一行一个词，总比让用户理解复杂的配置规则要好。

接下来是验证函数的实现。考虑到豆包 API 的限制，我们制定了严格的验证规则：热词文本最多 100 行，每行最多 50 个字符，总共最多 5000 个字符；boosting_table_id 最多 200 个字符，只允许字母、数字、下划线和连字符。这些限制不是我们凭空想象的，而是基于豆包官方文档的实际要求。毕竟，API 的限制就是 API 的限制，我们也没办法，只能遵守。

export function validateContextText(contextText: string): HotwordValidationResult {
  if (!contextText || contextText.trim().length === 0) {
    return { isValid: true, errors: [] };
  }

  const lines = contextText.split('\n').filter(line => line.trim().length > 0);
  const errors: string[] = [];

  if (lines.length > 100) {
    errors.push(`热词行数不能超过 100 行，当前为 ${lines.length} 行`);
  }

  const totalChars = contextText.length;
  if (totalChars > 5000) {
    errors.push(`热词总字符数不能超过 5000，当前为 ${totalChars}`);
  }

  for (let i = 0; i < lines.length; i++) {
    if (lines[i].length > 50) {
      errors.push(`第 ${i + 1} 行热词超过 50 个字符限制`);
    }
  }

  return { isValid: errors.length === 0, errors };
}

export function validateBoostingTableId(boostingTableId: string): HotwordValidationResult {
  if (!boostingTableId || boostingTableId.trim().length === 0) {
    return { isValid: true, errors: [] };
  }

  const errors: string[] = [];

  if (boostingTableId.length > 200) {
    errors.push(`boosting_table_id 不能超过 200 个字符，当前为 ${boostingTableId.length}`);
  }

  if (!/^[a-zA-Z0-9_-]+$/.test(boostingTableId)) {
    errors.push('boosting_table_id 只能包含字母、数字、下划线和连字符');
  }

  return { isValid: errors.length === 0, errors };
}

这些验证函数在用户配置热词时就会立即执行，确保问题在最早阶段被发现。对于用户体验来说，这种即时反馈是非常重要的。毕竟，用户输入的时候就知道哪里错了，总比提交后才发现要好。

前端配置持久化

在 HagiCode 的前端实现中，我们选择使用浏览器的 localStorage 来存储热词配置。这个设计决策背后有几点考量：首先，热词配置是非常个性化的设置，不同用户可能有不同的专业领域需求；其次，这种方式简化了后端实现，不需要额外的数据库表和 API 接口；最后，用户在浏览器中配置一次后，后续使用都能自动加载，非常方便。其实说白了，就是省事。

const HOTWORD_STORAGE_KEYS = {
  contextText: 'hotword-context-text',
  boostingTableId: 'hotword-boosting-table-id',
  combineMode: 'hotword-combine-mode',
} as const;

export const DEFAULT_HOTWORD_CONFIG: HotwordConfig = {
  contextText: '',
  boostingTableId: '',
  combineMode: false,
};

// 加载热词配置
export function loadHotwordConfig(): HotwordConfig {
  const contextText = localStorage.getItem(HOTWORD_STORAGE_KEYS.contextText) || '';
  const boostingTableId = localStorage.getItem(HOTWORD_STORAGE_KEYS.boostingTableId) || '';
  const combineMode = localStorage.getItem(HOTWORD_STORAGE_KEYS.combineMode) === 'true';

  return { contextText, boostingTableId, combineMode };
}

// 保存热词配置
export function saveHotwordConfig(config: HotwordConfig): void {
  localStorage.setItem(HOTWORD_STORAGE_KEYS.contextText, config.contextText);
  localStorage.setItem(HOTWORD_STORAGE_KEYS.boostingTableId, config.boostingTableId);
  localStorage.setItem(HOTWORD_STORAGE_KEYS.combineMode, String(config.combineMode));
}

这段代码的逻辑非常简单清晰。加载配置时从 localStorage 读取，保存配置时写入 localStorage。我们还提供了默认配置，确保在没有任何配置时系统也能正常工作。毕竟，总得有个默认值吧。

后端 SDK 配置扩展

在 HagiCode 的后端实现中，我们需要在 SDK 配置类中添加热词相关的属性。考虑到 C# 的语言特性和使用习惯，我们采用了 List<string> 来存储自定义热词上下文：

public class DoubaoVoiceConfig
{
    /// <summary>
    /// 应用 ID
    /// </summary>
    public string AppId { get; set; } = string.Empty;

    /// <summary>
    /// 访问令牌
    /// </summary>
    public string AccessToken { get; set; } = string.Empty;

    /// <summary>
    /// 服务 URL
    /// </summary>
    public string ServiceUrl { get; set; } = string.Empty;

    /// <summary>
    /// 自定义热词上下文列表
    /// </summary>
    public List<string>? HotwordContexts { get; set; }

    /// <summary>
    /// 豆包平台热词表 ID
    /// </summary>
    public string? BoostingTableId { get; set; }
}

这个配置类的设计遵循了 HagiCode 一贯的简洁风格。HotwordContexts 是可空的列表类型，BoostingTableId 是可空的字符串，这样在没有任何热词配置时，这些属性不会对请求造成任何影响。毕竟，不用的时候就不应该存在，这才叫干净。

Payload 构建逻辑

Payload 的构建是整个热词功能的核心。当我们有了热词配置后，需要按照豆包 API 的要求格式化为正确的 JSON 结构。这个过程发生在 SDK 发送请求之前：

private void AddCorpusToRequest(Dictionary<string, object> request)
{
    var corpus = new Dictionary<string, object>();

    // 添加自定义热词
    if (Config.HotwordContexts != null && Config.HotwordContexts.Count > 0)
    {
        corpus["context"] = new Dictionary<string, object>
        {
            ["context_type"] = "dialog_ctx",
            ["context_data"] = Config.HotwordContexts
                .Select(text => new Dictionary<string, object> { ["text"] = text })
                .ToList()
        };
    }

    // 添加平台热词表 ID
    if (!string.IsNullOrEmpty(Config.BoostingTableId))
    {
        corpus["boosting_table_id"] = Config.BoostingTableId;
    }

    // 只有当 corpus 不为空时才添加到请求中
    if (corpus.Count > 0)
    {
        request["corpus"] = corpus;
    }
}

这段代码展示了如何根据配置动态构建 corpus 字段。关键点在于：只有当确实存在热词配置时，我们才会添加 corpus 字段。这种设计确保了向后兼容性——没有配置热词时，请求的结构与之前完全一致。毕竟，兼容性很重要，不能因为加个功能就把之前的逻辑搞乱了。

WebSocket 参数传递

在前端和后端之间，热词参数通过 WebSocket 控制消息进行传递。HagiCode 的设计是：前端在开始录音时从 localStorage 加载热词配置，然后通过 WebSocket 消息发送给后端。

const controlMessage = {
  type: 'control',
  payload: {
    command: 'StartRecognition',
    contextText: '高血压\n糖尿病\n冠心病',
    boosting_table_id: 'medical_table',
    combineMode: false
  }
};

这里有一个细节需要注意：前端传递的是多行文本（用换行符分隔），后端需要进行解析。后端的 WebSocket Handler 会解析这些参数并传递给 SDK：

private async Task HandleControlMessageAsync(
    string connectionId,
    DoubaoSession session,
    ControlMessage message)
{
    if (message.Payload is SessionControlRequest controlRequest)
    {
        // 解析热词参数
        string? contextText = controlRequest.ContextText;
        string? boostingTableId = controlRequest.BoostingTableId;
        bool? combineMode = controlRequest.CombineMode;

        // 解析多行文本为热词列表
        if (!string.IsNullOrEmpty(contextText))
        {
            var hotwords = contextText
                .Split('\n', StringSplitOptions.RemoveEmptyEntries)
                .Select(s => s.Trim())
                .Where(s => s.Length > 0)
                .ToList();

            session.HotwordContexts = hotwords;
        }

        session.BoostingTableId = boostingTableId;
    }
}

通过这样的设计，热词配置从前端到后端的传递变得清晰而高效。其实也没什么特别的，就是一层一层传下去而已。

实践指南

配置自定义热词

在实际使用中，配置自定义热词非常简单。打开 HagiCode 的语音识别设置页面，找到”热词配置”区域。在”自定义热词文本”输入框中，每行输入一个热词短语。

比如，如果你正在开发一个医疗相关的应用，可以这样配置：

高血压
糖尿病
冠心病
心绞痛
心肌梗死
心力衰竭

保存配置后，每次开始语音识别时，这些热词都会自动传递给豆包 API。实际测试表明，配置热词后，相关专业术语的识别准确率有了明显提升。怎么说呢，效果还是有的，至少比之前好多了。

配置平台热词表

如果你需要管理大量的热词，或者热词需要频繁更新，那么平台热词表模式更适合你。首先需要在豆包自学习平台上创建热词表，获取生成的 boosting_table_id，然后在 HagiCode 的设置页面中输入这个 ID。

豆包自学习平台提供了热词的批量导入、分类管理等功能，对于需要管理大量专业术语的团队来说非常实用。通过平台管理热词，可以实现热词的集中维护和统一更新。毕竟，热词多了之后，有个地方统一管理，总比每次都要手动输入要好。

组合模式的使用

在某些复杂场景下，你可能需要同时使用自定义热词和平台热词表。这时只需要在 HagiCode 中同时配置两种热词，并开启”组合模式”开关。

组合模式下，豆包 API 会同时考虑两种热词来源，识别准确率通常比单独使用任意一种更高。不过需要注意的是，组合模式会增加请求的复杂度，建议在实际测试后再决定是否启用。毕竟，复杂度增加了，是不是真的值得，还是得看实际效果。

代码集成示例

在 HagiCode 项目中集成热词功能非常简单。以下是一些常用的代码片段：

import {
  loadHotwordConfig,
  saveHotwordConfig,
  validateHotwordConfig,
  parseContextText,
  getEffectiveHotwordMode,
  type HotwordConfig
} from '@/types/hotword';

// 加载并验证配置
const config = loadHotwordConfig();
const validation = validateHotwordConfig(config);

if (!validation.isValid) {
  console.error('热词配置验证失败:', validation.errors);
  return;
}

// 解析热词文本
const hotwords = parseContextText(config.contextText);
console.log('解析到的热词:', hotwords);

// 获取有效的热词模式
const mode = getEffectiveHotwordMode(config);
console.log('当前热词模式:', mode);

后端的使用同样简洁：

var config = new DoubaoVoiceConfig
{
    AppId = "your_app_id",
    AccessToken = "your_access_token",
    ServiceUrl = "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async",

    // 配置自定义热词
    HotwordContexts = new List<string>
    {
        "高血压",
        "糖尿病",
        "冠心病"
    },

    // 配置平台热词表
    BoostingTableId = "medical_table_v1"
};

var client = new DoubaoVoiceClient(config, logger);
await client.ConnectAsync();
await client.SendFullClientRequest();

注意事项

在实现和使用热词功能时，有几点需要特别注意。

首先是字符限制。豆包 API 对热词有严格的限制，包括行数、每行字符数、总字符数等。如果超出限制，API 会返回错误。在 HagiCode 的前端实现中，我们通过验证函数在用户输入阶段就进行检查，避免将无效配置发送到后端。毕竟，提前发现问题，总比等 API 返回错误要好。

其次是 boosting_table_id 的格式。这个字段只允许字母、数字、下划线和连字符，不允许包含空格或其他特殊字符。在豆包自学习平台上创建热词表时，需要注意命名规范。其实这也难怪，API 对格式的要求总是比较严格的。

第三是向后兼容性。热词参数是完全可选的，不配置热词时，系统的工作方式与之前完全一致。这种设计确保了现有用户不会受到任何影响，也便于逐步迁移和升级。毕竟，不能因为加个功能就把之前的逻辑搞乱了。

最后是错误处理。当热词配置无效时，豆包 API 会返回相应的错误信息。HagiCode 的实现会记录详细的日志，便于开发者排查问题。同时，前端也会在界面上展示验证错误，帮助用户修正配置。错误处理做得好，用户体验自然也就好了。

总结

通过本文的讲解，我们详细介绍了在 HagiCode 项目中实现豆包语音识别热词功能的完整方案。这套方案涵盖了从需求分析、技术选型到代码实现的全部环节，为开发者提供了可参考的实践范例。

核心要点可以归纳为以下几点：第一，豆包 API 支持自定义热词和平台热词表两种模式，可以独立使用也可以组合使用；第二，前端采用 localStorage 存储配置，简单高效；第三，后端通过动态构建 corpus 字段来传递热词参数，保持了良好的向后兼容性；第四，完善的验证逻辑确保了配置的正确性，避免了无效请求。怎么说呢，这套方案也不复杂，就是按照 API 的要求来而已。

热词功能的实现，让 HagiCode 在语音识别领域的能力得到了进一步增强。通过灵活配置业务相关的专业术语，开发者可以让语音识别系统更好地理解特定领域的内容，从而提供更加精准的服务。毕竟，技术最终是要服务业务的，能解决实际问题才是最重要的。

如果你觉得本文对你有帮助，欢迎来 GitHub 给个 Star 支持一下 HagiCode 项目。你的认可，是我们持续分享技术实践的动力。说到底，写文章分享技术，能帮到人，也算是种快乐了。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-06-doubao-speech-recognition-hotword-support/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。版权所有!

解决浏览器 WebSocket 认证难题：豆包语音识别的代理方案实践

2026年3月5日

解决浏览器 WebSocket 认证难题：豆包语音识别的代理方案实践

浏览器 WebSocket API 不支持自定义 HTTP header，这给需要通过 header 传递认证信息的语音识别服务带来了挑战。本文分享 HagiCode 项目中如何通过后端代理方案解决这个问题，以及从 playground 到生产环境的实践过程。

背景

其实在做 HagiCode 项目的语音识别功能时，我们也是满怀信心地选择了字节跳动的豆包语音识别服务。刚开始的设计很简单嘛——前端直接连豆包的 WebSocket 服务。这有什么难的？不就是建个连接，传点数据的事儿吗？

可是吧，万万没想到——豆包的 API 要求通过 HTTP header 传递认证信息，什么 accessToken、secretKey 之类的。这下就有点尴尬了，因为浏览器的 WebSocket API 根本不支持设置自定义 header。

你说不支持怎么办嘛？

那时候也是纠结了一阵子的。毕竟摆在面前的两个选择：

把认证信息塞到 URL 查询参数里——简单粗暴
在后端做一层代理——看起来麻烦一点

第一种方案吧，凭证就直接暴露在前端代码和本地存储里了。这安全吗？反正我是不太敢苟同的。而且有些 API 必须用 header 验证，根本走不通。

最终想了想，还是选了第二种方案——在后端实现一个 WebSocket 代理。说起来也是巧合，这个方案最初是在我们的 playground 试验场里验证的，后来确认稳定了才应用到生产环境。毕竟谁也不想在生产环境当小白鼠嘛，这点儿道理我还是懂的。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。

HagiCode 是一个 AI 代码助手项目，支持语音交互功能。怎么说呢，也就是因为需要在前端调用语音识别服务，我们才遇到了这个 WebSocket 认证问题，也才有了后面的解决方案。有时候想想吧，困难这东西也不是完全没有好处，至少让我们学会了用代理，不是吗？

技术挑战分析

浏览器 WebSocket 的限制

标准 WebSocket API 看起来真的很简单：

const ws = new WebSocket('wss://example.com/ws');

但问题就出在”简单”这两个字上——它只在 URL 里传递参数，没法像 HTTP 请求那样设置 headers：

// 这在 WebSocket API 里是不支持的
const ws = new WebSocket('wss://example.com/ws', {
  headers: {
    'Authorization': 'Bearer token'
  }
});

你看看，这找谁说理去？对于豆包语音识别这类需要 header 认证的服务，这个限制简直就是一道迈不过去的坎儿。

罢了罢了，又能怎样呢？

架构设计决策

在设计方案的时候，我们也是左思右想，权衡了又权衡。

决策一：代理模式选择

我们比较了两种方案：

方案	优点	缺点	决策
原生 WebSocket	轻量、简单、直接转发	需手动处理连接管理	选择
SignalR	自动重连、强类型	过度复杂、额外依赖	不选

最后选了原生 WebSocket。说实话，也就是因为它最轻量，适合简单的双向二进制流转发。加个 SignalR 吧，确实有点杀鸡用牛刀的感觉，而且会增加延迟——这又何苦呢？

决策二：连接管理策略

我们采用了”每连接单会话”模式——每个前端 WebSocket 连接对应一个独立的豆包后端连接。

这样做的好处也是显而易见的：

实现简单，符合典型使用场景
易于调试和故障排查
资源隔离，避免会话间互相干扰

其实说白了也就是——简单粗暴有时候反而是最好的选择。复杂的方案不一定好，简单的不一定差。

决策三：认证信息存储

凭证存在后端配置文件（appsettings.yml 或环境变量）里，通过依赖注入加载：

配置方式简单，符合现有后端配置模式
敏感信息不暴露给前端
支持多环境配置（开发、测试、生产）

这安全感嘛，总归是要有的。毕竟谁也不想自己的凭证满天飞，不是吗？

数据流设计

整体数据流是这样的：

前端 (浏览器)
  │
  │ ws://backend/api/voice/ws
  │ WebSocket (二进制)
  ▼
后端 (代理)
  │
  │ wss://openspeech.bytedance.com/
  │ (带认证 header)
  ▼
豆包 API

流程倒也不复杂，也就是这么几步：

前端通过 WebSocket 连接后端代理
后端代理接收音频数据，用带 header 的方式连接豆包 API
豆包 API 返回识别结果，代理转发给前端
全程异步双向流式传输

一切看起来都是那么自然，不是吗？

核心组件实现

1. WebSocket 端点配置

app.Map("/ws", async context =>
{
    if (context.WebSockets.IsWebSocketRequest)
    {
        // 从查询参数读取配置
        var appId = context.Request.Query["appId"];
        var accessToken = context.Request.Query["accessToken"];

        // 验证必需参数
        if (string.IsNullOrEmpty(appId) || string.IsNullOrEmpty(accessToken))
        {
            context.Response.StatusCode = 400;
            return;
        }

        // 接受 WebSocket 连接
        using var webSocket = await context.WebSockets.AcceptWebSocketAsync();

        // 消息处理循环
        var buffer = new byte[4096];
        while (!webSocket.CloseStatus.HasValue)
        {
            var result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);

            if (result.MessageType == WebSocketMessageType.Close)
            {
                await webSocket.CloseAsync(
                    result.CloseStatus.Value,
                    result.CloseStatusDescription,
                    CancellationToken.None);
                break;
            }

            // 处理音频数据
            await HandleAudioDataAsync(buffer, result.Count);
        }
    }
});

2. 会话管理

public class DoubaoSessionManager : IDoubaoSessionManager
{
    private readonly ConcurrentDictionary<string, DoubaoSession> _sessions = new();

    public DoubaoSession CreateSession(string connectionId)
    {
        var session = new DoubaoSession(connectionId);
        _sessions[connectionId] = session;
        return session;
    }

    public async Task SendAudioAsync(string connectionId, byte[] audioData)
    {
        if (_sessions.TryGetValue(connectionId, out var session))
        {
            await session.SendAudioAsync(audioData);
        }
    }

    public void RemoveSession(string connectionId)
    {
        if (_sessions.TryRemove(connectionId, out var session))
        {
            session.Dispose();
        }
    }
}

用 ConcurrentDictionary 管理会话，线程安全也就不用操心了。每个连接进来就创建一个 Session，断开时自动清理——这大概就是所谓的”来也匆匆，去也匆匆”罢。

3. 配置验证

public class ClientConfigDto
{
    public string AppId { get; set; } = null!;
    public string Access set; } =Token { get; null!;
    public string? ServiceUrl { get; set; }
    public string? ResourceId { get; set; }
    public int? SampleRate { get; set; }
    public int? BitsPerSample { get; set; }
    public int? Channels { get; set; }

    public void Validate()
    {
        if (string.IsNullOrWhiteSpace(AppId))
            throw new ArgumentException("AppId is required");
        if (string.IsNullOrWhiteSpace(AccessToken))
            throw new ArgumentException("AccessToken is required");
    }
}

配置验证嘛，也就是为了在启动时就发现问题，避免运行时出什么幺蛾子。这点儿保障还是要的。

消息协议设计

前端和后端之间用 JSON 格式的文本消息做控制，用二进制消息传音频数据。

控制消息示例：

{
    "type": "control",
    "messageId": "msg_123",
    "timestamp": "2026-03-03T10:00:00Z",
    "payload": {
        "command": "StartRecognition",
        "parameters": {
            "hotwordId": "hotword1",
            "boosting_table_id": "table123"
        }
    }
}

识别结果示例：

{
    "type": "result",
    "timestamp": "2026-03-03T10:00:03Z",
    "payload": {
        "text": "你好世界",
        "confidence": 0.95,
        "duration": 1500,
        "isFinal": true,
        "utterances": [
            {
                "text": "你好",
                "startTime": 0,
                "endTime": 800,
                "definite": true
            }
        ]
    }
}

这种设计把控制信号和音频数据分开，处理起来也是更清晰一些。有时候分而治之确实是个不错的办法。

前端接入实践

WebSocket 连接

class DoubaoVoiceClient {
    constructor(config) {
        this.config = config;
        this.ws = null;
    }

    async connect() {
        const url = new URL(this.config.wsUrl);
        // 添加查询参数
        Object.entries(this.config.params).forEach(([key, value]) => {
            url.searchParams.set(key, value);
        });

        this.ws = new WebSocket(url);

        return new Promise((resolve, reject) => {
            this.ws.onopen = () => {
                console.log('[DoubaoVoice] Connected');
                resolve();
            };

            this.ws.onmessage = (event) => {
                this._handleMessage(JSON.parse(event.data));
            };

            this.ws.onerror = reject;
        });
    }

    _handleMessage(message) {
        switch (message.type) {
            case 'status':
                this._handleStatus(message.payload);
                break;
            case 'result':
                this.onResult?.(message.payload);
                break;
            case 'error':
                console.error('[DoubaoVoice] Error:', message.payload);
                break;
        }
    }
}

// 使用示例
const client = new DoubaoVoiceClient({
    wsUrl: 'ws://localhost:5000/ws',
    params: {
        appId: 'your-app-id',
        accessToken: 'your-access-token',
        sampleRate: 16000,
        bitsPerSample: 16,
        channels: 1
    }
});

音频采集与发送

用 AudioWorkletNode 做音频处理，性能也会更好一些：

class AudioProcessorWorklet extends AudioWorkletProcessor {
    process(inputs, outputs, parameters) {
        const input = inputs[0]?.[0];
        if (!input) return true;

        // 转换为 16-bit PCM
        const pcm = new Int16Array(input.length);
        for (let i = 0; i < input.length; i++) {
            pcm[i] = Math.max(-32768, Math.min(32767, input[i] * 32767));
        }

        this.port.postMessage({
            type: 'audioData',
            data: pcm.buffer
        }, [pcm.buffer]);

        return true;
    }
}

registerProcessor('audio-processor', AudioProcessorWorklet);

// 主线程代码
async function startAudioRecording() {
    const stream = await navigator.mediaDevices.getUserMedia({
        audio: {
            echoCancellation: true,
            noiseSuppression: true,
            autoGainControl: true,
            sampleRate: 48000
        }
    });

    const audioContext = new AudioContext();
    const audioSource = audioContext.createMediaStreamSource(stream);

    await audioContext.audioWorklet.addModule('/audio-worklet.js');
    const audioWorkletNode = new AudioWorkletNode(audioContext, 'audio-processor');

    audioWorkletNode.port.onmessage = (event) => {
        if (event.data.type === 'audioData' && ws?.readyState === WebSocket.OPEN) {
            ws.send(event.data.data); // 直接发送二进制数据
        }
    };

    audioSource.connect(audioWorkletNode);
}

AudioWorklet 比 ScriptProcessorNode 性能好很多，不会有音频卡顿的问题。这年代，谁还愿意听那种刺刺拉拉的噪音呢？

后端配置

appsettings.json 示例

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": { "path": "logs/log-.txt", "rollingInterval": "Day" }
      }
    ]
  },
  "Kestrel": {
    "Urls": "http://0.0.0.0:5000"
  }
}

日志配置很重要，方便排查问题。Serilog 的 File sink 可以按天滚动，日志文件也不会太大。毕竟有些问题嘛，事后诸葛亮总是要容易一点的。

注意事项和最佳实践

1. 连接监控

定期输出会话状态日志，方便追踪连接生命周期
监控音频段数量和持续时间，识别异常连接
记录与豆包服务的连接状态和重连情况

这些也就是一些基本的操作罢了。

2. 错误处理

捕获并记录所有 WebSocket 异常
使用 IAsyncDisposable 确保资源清理
实现优雅的连接关闭和超时处理

总而言之，稳字当头。

3. 音频格式要求

采样率：16000 Hz（推荐）或 8000 Hz
位深度：16-bit
声道：单声道
编码：PCM (raw)

格式不对会导致识别失败或者效果很差。这点儿规矩还是要守的。

4. 安全考虑

敏感凭证只存在后端配置里
实施连接数限制防止资源耗尽
生产环境用 HTTPS/WSS

安全无小事，且行且珍惜罢。

5. 性能优化

用异步操作避免阻塞
适当调整缓冲区大小（默认 4096 字节）
考虑连接池和复用策略

这些优化手段，能用上的就用上罢。

部署建议

Docker 部署：把代理服务打包成容器，方便扩展和管理
负载均衡：用 Nginx 或 Envoy 做 WebSocket 反向代理
健康检查：实现心跳机制监控服务可用性
日志聚合：把日志发送到集中式日志系统（如 ELK、Loki）

部署这事儿吧，说简单也简单，说复杂也复杂。也就是因人而异，因地制宜罢。

总结

WebSocket 代理方案解决了浏览器 WebSocket API 不支持自定义 header 的根本问题。在 HagiCode 项目中，这个方案从 playground 验证到生产环境部署，证明了它的可行性和稳定性。

关键点总结：

后端代理可以安全地传递认证信息
原生 WebSocket 轻量高效，适合简单场景
“每连接单会话”简化了实现和调试
前后端消息协议分离控制信号和音频数据

如果你也在做需要 WebSocket 认证的功能，希望这个方案能给你一些启发。

有什么问题的话，欢迎来讨论。毕竟技术这东西嘛，都是在交流中进步的。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-05-websocket-proxy-for-doubao-speech-recognition/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

AI Compose Commit：用 AI 智能重构 Git 提交工作流

2026年2月26日

AI Compose Commit：用 AI 智能重构 Git 提交工作流

Introduction

在软件开发过程中,提交代码是程序员每天都要面对的日常工作。可是你有没有经历过这样的场景:一天工作结束后,打开 Git 看到几十个未暂存的修改文件,却不知道该如何将它们组织成合理的提交?

传统的方式是手动将文件分批暂存、逐个提交、撰写提交信息,这个过程既耗时又容易出错。咱们就常常在这上面浪费了不少时间,毕竟谁也不想在已经疲惫的晚上还要为这些琐事烦心。

我们在 HagiCode 项目中推出了一项新功能——AI Compose Commit,旨在彻底改变这个工作流程。它通过 AI 智能分析工作区中的所有未提交变更,自动将它们分组为多个逻辑提交,并执行符合规范的提交操作。本文将深入探讨这个功能的实现原理、技术架构以及我们在实践中遇到的挑战与解决方案。

About HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。

Background

传统 Git 提交的痛点

Git 作为版本控制系统,为开发者提供了强大的代码管理能力。但在实际使用中,提交操作往往成为开发流程中的瓶颈:

手动分组耗时: 当有大量文件变更时,开发者需要逐个检查文件内容,判断哪些属于同一个功能,这需要耗费大量脑力
提交信息质量参差: 撰写符合 Conventional Commits 规范的提交信息需要经验和技巧,新手常常写出不规范的提交
多仓库管理复杂: 在 monorepo 环境中,需要在不同仓库间切换,增加了操作复杂度
工作流被打断: 提交代码会打断开发思路,影响编码效率

这些问题在大型项目和团队协作环境中尤为明显。一个优秀的开发工具应该让开发者专注于核心的编码工作,而不是被繁琐的提交流程所困扰。

AI 辅助开发的趋势

近年来,AI 技术在软件开发领域的应用日益广泛。从代码补全、错误检测到自动生成文档,AI 正在逐步渗透到开发的各个环节。在 Git 工作流方面,虽然已有一些工具提供提交信息生成的功能,但大多局限于单次提交的场景,缺乏对整个工作区变更的智能分析和分组能力。

其实 HagiCode 在开发过程中也遇到了这些痛点,我们曾尝试过多种工具,但都或多或少存在一些局限性。要么是功能不够完善,要么是用户体验不够好。这也是为什么我们最终决定自己实现 AI Compose Commit 功能的原因。

HagiCode 的 AI Compose Commit 功能正是为了填补这一空白而生,它不仅是生成提交信息,而是完整接管从文件分析到执行提交的整个流程。

Problem

技术挑战

在实现 AI Compose Commit 功能的过程中,我们面临了多个技术挑战:

文件语义理解: AI 需要理解文件变更的语义关系,判断哪些文件属于同一个功能模块。这需要深入分析文件内容、目录结构以及变更的上下文。
提交分组策略: 如何定义合理的分组标准?是按功能、按模块,还是按文件类型?不同的项目可能适用不同的策略。
实时反馈与异步处理: Git 操作可能需要较长时间,特别是处理大量文件时。如何在保证用户体验的同时完成复杂操作?
多仓库支持: 在 monorepo 架构下,需要在主仓库和子仓库之间正确路由操作。
错误处理与回滚: 如果某个提交失败,如何处理已执行的提交?是否需要回滚已暂存的文件?
提交信息一致性: 生成的提交信息需要符合项目现有的风格,保持历史提交的格式一致。

性能考量

AI 处理大量文件变更会消耗显著的时间和计算资源。我们需要在以下方面进行优化:

减少不必要的 AI 调用
优化文件上下文的构建方式
实现高效的 Git 操作批处理

这些问题在 HagiCode 的实际使用中都真实出现过,我们通过不断的迭代和优化才找到了相对完美的解决方案。如果你也在开发类似的工具,希望我们的经验能给你一些启发。

Solution

整体架构设计

我们采用了分层架构来实现 AI Compose Commit 功能,确保系统具有良好的可扩展性和可维护性:

1. API 层(Web 层)

GitController 提供了 POST /api/git/auto-compose-commit 端点,作为功能入口。为了优化用户体验,我们采用了 Fire-and-Forget 异步模式:

客户端发起请求后,服务器立即返回 HTTP 202 Accepted
实际的 AI 处理在后台异步执行
处理完成后通过 SignalR 通知客户端

这种设计确保了即使 AI 处理需要几分钟,用户也能立即得到响应,不会感觉系统卡顿。

2. 应用服务层(Application 层)

GitAppService 负责核心业务逻辑:

仓库检测:支持 monorepo 中的多仓库管理
锁管理:防止并发操作导致的冲突
文件暂存协调:与 AI 处理流程的交互
错误回滚:处理失败场景下的状态恢复

3. 分布式计算层(Orleans Grains)

AIGrain 作为 AI 操作的核心执行单元,实现了 IAIGrain 接口中的 AutoComposeCommitAsync 方法:

// 定义 AI 自动组合提交的接口方法
// 参数说明:
// - projectId: 项目唯一标识符
// - unstagedFiles: 未暂存文件列表,包含文件路径和状态信息
// - projectPath: 项目根目录路径(可选),用于访问项目上下文
// 返回值: 包含执行结果的响应对象,包括成功/失败状态和详细信息
[Alias("AutoComposeCommitAsync")]
[ResponseTimeout("00:20:00")] // 20 分钟超时,适用于处理大型变更集
Task<AutoComposeCommitResponseDto> AutoComposeCommitAsync(
    string projectId,
    GitFileStatusDto[] unstagedFiles,
    string? projectPath = null);

这个方法设置了 20 分钟的超时时间,以处理大型变更集。HagiCode 在实际使用中发现,有些项目的单次变更可能涉及上百个文件,需要更长的处理时间。

4. AI 服务层

通过抽象的 IAIService 接口,我们实现了 AI 服务的可插拔架构。目前使用 Claude Helper 服务,但可以轻松切换到其他 AI 提供商。

核心实现逻辑

文件上下文构建

AI 需要了解每个文件的状态才能做出智能决策。我们通过 BuildFileChangesXml 方法构建文件上下文:

/// <summary>
/// 构建文件变更的 XML 表示形式,用于为 AI 提供完整的文件上下文信息
/// </summary>
/// <param name="stagedFiles">已暂存的文件列表,包含文件路径、状态和旧路径(针对重命名操作)</param>
/// <returns>格式化的 XML 字符串,包含所有文件的元数据信息</returns>
private static string BuildFileChangesXml(GitFileStatusDto[] stagedFiles)
{
    var sb = new StringBuilder();
    sb.AppendLine("<files>");

    foreach (var file in stagedFiles)
    {
        sb.AppendLine("  <file>");
        // 使用 XML 转义确保特殊字符不会破坏 XML 结构
        sb.AppendLine($"    <path>{System.Security.SecurityElement.Escape(file.Path)}</path>");
        sb.AppendLine($"    <status>{System.Security.SecurityElement.Escape(file.Status)}</status>");

        // 处理文件重命名场景,记录旧路径以便 AI 理解变更关系
        if (!string.IsNullOrEmpty(file.OldPath))
        {
            sb.AppendLine($"    <oldPath>{System.Security.SecurityElement.Escape(file.OldPath)}</oldPath>");
        }

        sb.AppendLine("  </file>");
    }

    sb.AppendLine("</files>");
    return sb.ToString();
}

这个 XML 格式的上下文包含文件路径、状态和旧路径(针对重命名操作),为 AI 提供了完整的元数据。通过结构化的 XML 格式,我们确保了 AI 能够准确理解每个文件的状态和变更类型。

AI 权限管理

为了让 AI 能够直接执行 Git 操作,我们配置了全面的工具权限:

// 定义 AI 可以使用的工具集合,包括文件操作和 Git 命令执行权限
// Read/Write/Edit: 文件读写和编辑能力
// Bash(git:*): 执行所有 Git 命令的权限
// 其他 Bash 命令: 用于查看文件内容和目录结构,辅助 AI 理解上下文
var allowedTools = new[]
{
    "Read", "Write", "Edit",
    "Bash(git:*)", "Bash(cat:*)", "Bash(ls:*)", "Bash(find:*)",
    "Bash(grep:*)", "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)"
};

// 构建完整的 AI 请求对象
var request = new AIRequest
{
    Prompt = prompt,                          // 完整的 Prompt 模板,包含任务指令和约束条件
    WorkingDirectory = projectPath ?? GetTempDirectory(), // 工作目录,确保 AI 在正确的项目上下文中执行
    AllowedTools = allowedTools,               // 允许使用的工具集合
    PermissionMode = PermissionMode.bypassPermissions, // 绕过权限检查,允许直接执行 Git 操作
    LanguagePreference = languagePreference         // 语言偏好设置,确保生成符合用户期望的提交信息
};

这里使用了 PermissionMode.bypassPermissions 模式,允许 AI 直接执行 Git 命令而无需用户确认。这是功能设计的核心,但同时也需要严格的输入验证来防止滥用。HagiCode 在实际部署中,通过后端的参数验证和日志监控,确保了这个机制的安全性。

提交结果解析

AI 执行完成后,会返回结构化的结果。我们实现了双重解析策略以确保兼容性:

/// <summary>
/// 解析 AI 返回的提交执行结果,支持分隔符格式和正则表达式格式
/// </summary>
/// <param name="aiResponse">AI 返回的原始响应内容</param>
/// <returns>解析后的提交结果列表,每个结果包含提交哈希和执行状态</returns>
private List<CommitResultDto> ParseCommitExecutionResults(string aiResponse)
{
    var results = new List<CommitResultDto>();

    // 优先使用分隔符解析(新格式),这种格式更加明确和可靠
    if (aiResponse.Contains("---"))
    {
        logger.LogDebug("Using delimiter-based parsing for AI response");
        results = ParseDelimitedFormat(aiResponse);

        if (results.Count > 0)
        {
            return results; // 成功解析,直接返回结果
        }

        logger.LogWarning("Delimiter-based parsing produced no results, falling back to regex");
    }
    else
    {
        logger.LogDebug("No delimiter found, using legacy regex-based parsing");
    }

    // 回退到正则表达式解析(旧格式),确保向后兼容性
    return ParseLegacyFormat(aiResponse);
}

分隔符格式使用 --- 作为提交之间的分隔,格式清晰且易于解析:

---
Commit 1: abc123def456
feat(auth): add user login functionality

Implement JWT-based authentication with login form and API endpoints.

Co-Authored-By: Hagicode <noreply@hagicode.com>
---
Commit 2: 789ghi012jkl
docs(readme): update installation instructions

Add new setup steps for Docker environment.

Co-Authored-By: Hagicode <noreply@hagicode.com>
---

这种格式设计让解析变得简单可靠,同时人类阅读也很清晰。

锁管理机制

为了防止并发操作导致的状态冲突,我们实现了仓库锁机制:

// 获取仓库锁,防止并发操作
// 参数说明:
// - fullPath: 仓库的完整路径,用于标识不同的仓库实例
// - requestedBy: 请求者标识,用于追踪和日志记录
await _autoComposeLockService.AcquireLockAsync(fullPath, requestedBy);

try
{
    // 执行 AI Compose Commit 操作
    // 这部分代码会调用 Orleans Grain 的方法,执行实际的 AI 处理和 Git 操作
    await aiGrain.AutoComposeCommitAsync(projectId, unstagedFiles, projectPath);
}
finally
{
    // 确保锁被释放,无论操作成功或失败
    // 使用 finally 块可以保证异常情况下也能释放锁,避免死锁
    await _autoComposeLockService.ReleaseLockAsync(fullPath);
}

锁具有 20 分钟的超时时间,与 AI 操作的超时设置保持一致。如果操作失败或超时,系统会自动释放锁,避免永久阻塞。HagiCode 在实际使用中发现,这个锁机制非常重要,特别是在团队协作环境中,多个开发者可能同时触发 AI Compose Commit 操作。

SignalR 实时通知

处理完成后,系统通过 SignalR 向前端发送通知:

/// <summary>
/// 发送自动组合提交完成的通知
/// </summary>
/// <param name="projectId">项目标识符,用于路由通知到正确的客户端</param>
/// <param name="totalCount">总提交数量,包括成功和失败</param>
/// <param name="successCount">成功提交的数量</param>
/// <param name="failureCount">失败提交的数量</param>
/// <param name="success">整体操作是否成功标志</param>
/// <param name="error">错误信息(如果操作失败)</param>
private async Task SendAutoComposeCommitNotificationAsync(
    string projectId,
    int totalCount,
    int successCount,
    int failureCount,
    bool success,
    string? error)
{
    try
    {
        // 构建通知数据传输对象,包含详细的执行结果
        var notification = new AutoComposeCommitCompletedDto
        {
            ProjectId = projectId,
            TotalCount = totalCount,
            SuccessCount = successCount,
            FailureCount = failureCount,
            Success = success,
            Error = error
        };

        // 通过 SignalR Hub 广播通知到所有连接的客户端
        await messageService.SendAutoComposeCommitCompletedAsync(notification);

        logger.LogInformation(
            "Auto compose commit notification sent for project {ProjectId}: {SuccessCount}/{TotalCount} succeeded",
            projectId, successCount, totalCount);
    }
    catch (Exception ex)
    {
        // 记录通知错误但不影响主操作流程
        // 通知失败不应该导致整个操作失败
        logger.LogError(ex, "Failed to send auto compose commit notification for project {ProjectId}", projectId);
    }
}

前端收到通知后可以更新 UI,显示提交成功或失败的状态,提升用户体验。这种实时反馈机制在 HagiCode 的使用中获得了很好的用户反馈,用户可以清楚地知道操作何时完成以及结果如何。

Implementation

Prompt 工程设计

AI 的行为完全由 Prompt 决定,我们精心设计了 Auto Compose Commit 的 Prompt 模板。以中文版本为例(auto-compose-commit.zh-CN.hbs):

非交互式模式支持

Prompt 开头明确声明支持非交互式运行模式,这是 CI/CD 和自动化脚本的关键需求:

**重要提示**:此提示词可能在非交互式环境中运行(如 CI/CD、自动化脚本)。

**非交互式模式**:
- 禁止使用 AskUserQuestion 或任何交互式工具
- 当需要用户输入时:
  - 使用合理的默认值(如提交类型使用 feat)
  - 跳过可选的确认步骤
  - 记录所做的假设

这个设计确保了 AI Compose Commit 功能不仅能在交互式 IDE 环境中使用,也能集成到 CI/CD 流程中,实现完全自动化的提交流程。

分支保护机制

为了防止 AI 执行危险操作,我们在 Prompt 中添加了严格的分支保护规则:

**分支保护**:
- 禁止执行任何分支切换操作(git checkout、git switch)
- 所有 git commit 命令必须在当前分支上执行
- 不得创建、删除或重命名分支
- 不得修改未跟踪文件或未暂存变更
- 如果需要分支切换才能完成操作,应返回错误而非执行

这些规则通过约束 AI 的工具使用范围,确保操作的安全性。HagiCode 在实际测试中验证了这些约束的有效性,AI 在遇到需要分支切换的场景时会安全地返回错误,而不是执行危险操作。

智能分组决策树

Prompt 中详细定义了文件分组的决策逻辑:

**文件分组决策树**:
├── 是否为配置文件(package.json、tsconfig.json、.env 等)?
│   ├── 是 → 独立提交(类型:chore 或 build)
│   └── 否 → 继续
├── 是否为文档文件(README.md、*.md、docs/**)?
│   ├── 是 → 独立提交(类型:docs)
│   └── 否 → 继续
├── 是否与同一功能相关?
│   ├── 是 → 合并到同一提交
│   └── 否 → 分别提交
└── 是否为跨模块变更?
    ├── 是 → 按模块分组
    └── 否 → 按功能分组

这个决策树为 AI 提供了清晰的分组逻辑,确保生成的提交符合语义合理性。HagiCode 在实际使用中发现,这个决策树能够处理绝大多数常见场景,生成的分组结果符合开发者预期。

历史格式一致性分析

为了让提交信息与项目历史保持一致,Prompt 要求 AI 在生成前分析最近的提交历史:

**历史格式一致性**:在生成提交信息之前,你**必须**分析当前仓库的提交历史以匹配现有风格

1. 使用 git log -n 15 --pretty=format:"%H|%s|%b%n---%n" 获取最近的提交历史
2. 分析提交以识别:
   - 结构模式:项目是否使用多段落?是否有 "Changes:" 或 "Capabilities:" 部分?
   - 语言模式:提交信息是英文、中文还是混合?
   - 常用类型:最常使用哪些提交类型(feat、fix、docs 等)?
   - 特殊格式:是否有 Co-Authored-By 行?其他项目特定的约定?
3. 生成遵循检测到的模式的提交信息

这个分析确保了 AI 生成的提交信息不会显得突兀,而是与项目的提交历史保持风格一致。在 HagiCode 的多语言项目中,这个功能特别重要,它能够根据项目的提交历史自动选择合适的语言和格式。

Co-Authored-By 要求

每个提交必须包含 Co-Authored-By 信息:

**重要**:每个提交必须添加 Co-Authored-By 信息
- 使用以下格式:git commit -m "type(scope): subject" -m "" -m "Co-Authored-By: Hagicode <noreply@hagicode.com>"
- 或者直接在提交信息中包含 Co-Authored-By 行

这不仅是为了贡献规范,也是为了追踪 AI 辅助的提交历史。HagiCode 将这个要求作为强制规则,确保所有 AI 生成的提交都带有明确的来源标识。

工作流程详解

完整的 AI Compose Commit 工作流程如下:

用户触发: 用户在 Git Status 面板或 Quick Actions Zone 点击”AI Auto Compose Commit”按钮
API 请求: 前端发送 POST 请求到 /api/git/auto-compose-commit 端点
立即响应: 服务器返回 HTTP 202 Accepted,不等待处理完成
后台处理:
- GitAppService 获取仓库锁
- 调用 AIGrain 的 AutoComposeCommitAsync 方法
- 构建文件上下文 XML
- 执行 AI Prompt,让 AI 分析并执行提交
AI 执行:
- 使用 Git 命令获取所有未暂存变更
- 读取文件内容理解变更性质
- 按语义关系对文件分组
- 对每组执行 git add 和 git commit 操作
结果解析: 解析 AI 返回的执行结果
通知发送: 通过 SignalR 通知前端
锁释放: 无论成功或失败,都释放仓库锁

这个流程的设计确保了用户可以在发起操作后立即继续其他工作,而不需要等待 AI 处理完成。HagiCode 的用户反馈表明,这种异步处理方式大大提升了工作流体验。

错误处理机制

我们实现了多层级的错误处理:

1. 输入验证

// 验证请求参数的有效性,防止无效请求到达后端处理逻辑
if (request.UnstagedFiles == null || request.UnstagedFiles.Count == 0)
{
    return BadRequest(new
    {
        message = "No unstaged files provided. Please make changes in the working directory first.",
        status = "validation_failed"
    });
}

2. 错误回滚

如果 AI 处理过程中出现错误,系统会执行回滚操作,将已暂存的文件取消暂存,避免留下不一致的状态。这个机制在 HagiCode 的实际使用中挽救了多次意外中断,确保了仓库状态的完整性。

3. 超时处理

20 分钟的超时设置确保了长时间运行的操作不会无限期阻塞资源。超时后,系统会释放锁并通知用户操作失败。HagiCode 在实际使用中发现,大部分操作能够在 2-5 分钟内完成,只有处理超大型变更集时才会接近超时限制。

Best Practices

使用 AI Compose Commit 的最佳实践

1. 合理使用时机

AI Compose Commit 最适合以下场景:

一天工作结束后,批量处理多个文件的变更
重构操作后,多个相关文件需要分别提交
功能开发完成,需要将相关变更分组提交

不适合以下场景:

单个文件的快速提交(直接使用普通提交更快)
需要精确控制提交内容的场景
包含敏感信息的提交(需要人工审核)

2. 审查 AI 生成的提交

虽然 AI 智能分组很强大,但开发者仍应审查生成的提交:

检查提交的分组是否符合预期
验证提交信息的准确性
确认没有遗漏或错误包含文件

如果发现不合理的分组,可以使用 git reset --soft HEAD~N 撤销后重新分组。HagiCode 的经验表明,即使 AI 分组很智能,人工审查仍然是有价值的,特别是在重要的功能提交时。

3. 配合项目规范

确保项目的 Git 配置支持 Conventional Commits:

# 安装 commitlint
npm install -g @commitlint/cli @commitlint/config-conventional

# 配置 commitlint
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

这样可以在 CI/CD 流程中验证提交信息格式,与 AI Compose Commit 生成的格式保持一致。

实现类似功能的建议

如果你想在项目中实现类似的 AI 辅助提交功能,以下是我们的建议:

1. 从小规模开始

先实现单次提交信息生成,再逐步扩展到多提交分组功能。这样更容易验证和迭代。HagiCode 也是按照这个路径逐步完善功能的,早期版本只支持单次提交,后来才扩展到多提交智能分组。

2. 使用成熟的 AI SDK

不要自己实现 AI 调用逻辑,使用现有的 SDK 可以减少开发时间和潜在 bug。我们使用了 Claude Helper 服务,它提供了稳定的接口和完善的错误处理。

3. 重视 Prompt 设计

Prompt 的质量直接决定了 AI 输出的质量。投入时间设计详细的 Prompt,包括:

明确的任务描述
具体的输出格式要求
边界情况的处理规则
示例说明

HagiCode 在 Prompt 设计上投入了大量时间,这是功能成功的关键因素之一。

4. 实现全面的错误处理

AI 操作可能因为各种原因失败(网络问题、API 限流、内容审查等)。确保你的系统能够优雅地处理这些错误,并提供有意义的错误信息。

5. 提供手动干预机制

不要完全自动化,给用户保留控制权。提供查看分组结果、调整分组、手动编辑提交信息等选项,平衡自动化与灵活性。HagiCode 虽然实现了自动执行,但仍然保留了预览和调整的能力。

性能优化技巧

1. 文件过滤

在构建文件上下文时,过滤掉不需要 AI 分析的文件:

// 过滤掉自动生成的文件和过大的文件,减少 AI 处理负担
var relevantFiles = stagedFiles
    .Where(f => !IsGeneratedFile(f.Path))
    .Where(f => !IsLargeFile(f.Path))
    .ToArray();

2. 并行处理

如果支持多个独立仓库,可以并行处理不同仓库的提交,提高整体效率。

3. 缓存优化

缓存项目提交历史分析结果,避免每次都重新分析。可以在配置文件中存储历史格式偏好,减少 AI 调用次数。

Conclusion

AI Compose Commit 功能代表了 AI 技术在软件开发工具中的深度应用。通过智能分析文件变更、自动分组提交、生成规范的提交信息,它显著提升了 Git 工作流的效率,让开发者能够更专注于核心的编码工作。

在实现过程中,我们学到了几个重要的经验:

用户反馈是关键: 早期版本采用同步等待方式,用户反馈体验不佳,改为 Fire-and-Forget 模式后满意度大幅提升
Prompt 设计决定质量: 一个精心设计的 Prompt 比复杂的算法更能保证 AI 输出的质量
安全永远是第一位的: 虽然赋予 AI 直接执行 Git 命令的权限带来了效率提升,但必须配合严格的约束和验证
渐进式改进: 从简单场景开始,逐步增加复杂度,比一次性实现所有功能更容易成功

未来,我们计划进一步优化 AI Compose Commit 功能,包括:

支持更多提交分组策略(按时间、按开发者等)
集成代码审查流程,在提交前自动触发审查
支持自定义提交信息模板,满足不同项目的个性化需求

如果你觉得本文分享的方案有价值,不妨也试试 HagiCode,体验一下这个功能在实际开发中的效果。毕竟实践是检验真理的唯一标准嘛。

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-02-26-ai-compose-commit-implementation/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

基于 Starlight 文档站点接入 Microsoft Clarity 的完整实践指南

2026年2月4日

从数据洞察到用户增长：HagiCode 博客接入 Clarity Analytics 的完整指南

本文将分享如何在 Starlight 文档站点中优雅地接入 Microsoft Clarity，不仅能看清用户行为，还能确保隐私合规。这套方案是我们在 HagiCode 项目中实践总结出来的，希望能给同样在折腾数据统计的你一点参考。

背景：为什么我们需要 Clarity？

以下代码展示了如何在 Astro 集成中根据环境变量动态注入 Microsoft Clarity 脚本，仅在生效时进行生产环境加载。

105 | interface Props {
106 |   // 未来可扩展: 允许手动覆盖 Project ID
107 |   projectId?: string;
108 | }
109 |
110 | const {
111 |   projectId = import.meta.env.CLARITY_PROJECT_ID,
112 | } = Astro.props;
113 |
114 | const isProduction = import.meta.env.PROD;
115 | ---
116 |
117 | {isProduction && projectId && (
118 |   <script is:inline define:vars={{projectId}}>
119 |     (function(c,l,a,r,i,t,y){

文件：openspec/changes/archive/2026-01-30-microsoft-clarity-integration/design.md

在运营 HagiCode 的过程中，我们一直面临一个”盲盒”问题：我们产出内容，但不清楚用户是如何阅读的。虽然 GitHub 能看到 Star 数，但这太滞后了。我们需要知道：

用户到底有没有看完我们的教程？
那些复杂的配置文档，是在哪一步劝退了用户的？
我们的 SEO 优化是否真的带来了有效流量？

市面上有很多分析工具，比如 Google Analytics（GA）和 Microsoft Clarity。GA 功能强大但配置复杂，且受到隐私法规（如 GDPR）的严格限制。而 Clarity 作为微软推出的免费热力图工具，不仅功能直观，而且在隐私合规上相对宽松，非常适合技术文档站点。

我们的目标很明确：在 HagiCode 的文档站点中无缝集成 Clarity，既要在所有页面生效，又要给用户留有”退出”的权利（隐私合规）。

关于 HagiCode

HagiCode 主题初始化逻辑：优先读取本地存储，回退至系统偏好，默认暗色。

67 | function getInitialTheme(): Theme {
68 |   // 1. 检查 localStorage
69 |   const stored = localStorage.getItem('hagicode-theme');
70 |   if (stored) return stored as Theme;
71 |
72 |   // 2. 检测系统偏好
73 |   const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
74 |   if (systemDark) return 'dark';
75 |
76 |   // 3. 默认暗色
77 |   return 'dark';
78 | }
79 | ```
80 |
81 | ### 决策 3：主题应用方式
82 |
83 | **选择**：在 `<html>` 根元素设置 `data-theme` 属性
84 |
85 | **对比方案**：
86 |

文件：openspec/changes/archive/2026-01-29-theme-toggle-implementation/design.md

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个基于 AI 的代码辅助工具，在开发过程中，我们需要维护大量的技术文档和博客。为了更好地理解用户需求，我们探索并实施了这套数据接入方案。

技术选型与探索

起初，我们在 Proposal 阶段讨论了多种集成方式。既然我们使用的是 Starlight（基于 Astro 的文档框架），最直观的想法是利用 Astro 的 Hooks。

我们首先尝试了修改 astro.config.mjs，计划在构建时注入 Clarity 脚本。虽然这种方式能保证全局覆盖，但缺乏灵活性——我们无法根据用户的偏好动态加载或卸载脚本。

考虑到用户体验和隐私控制，我们最终决定采用 组件覆盖 的方案。Starlight 允许开发者覆盖其内部组件，这意味着我们可以接管 <footer> 或 <head> 的渲染逻辑，从而精细控制 Clarity 的加载时机。

这里有一个小插曲：原本我们想创建一个名为 StarlightWrapper.astro 的布局包装器。但在实际调试中发现，Starlight 的路由机制并不会自动调用这个自定义 Wrapper，这导致脚本在部分页面失效。这算是一个典型的”想当然”踩坑经历，提醒我们必须深入理解框架的渲染流程，而不是盲目套用通用框架模式。

为了确保 Clarity 脚本在所有页面（包括文档和博客）加载，并且不破坏原有的页面结构，我们选择了覆盖 Starlight 的 Footer 组件。

全局性：Footer 几乎在所有标准页面都会出现。
非侵入性：将脚本放在 Footer 区域（实际渲染在 body 底部）不会阻塞页面的关键渲染路径（LCP），对性能影响最小。
逻辑集中：可以在组件内部统一处理 Cookie 同意逻辑。

实施步骤

1. 准备 Clarity 项目

首先，你需要在 Microsoft Clarity 注册并创建一个新项目。获取你的 Project ID（类似 k8z2ab3xxx 这样的字符串）。

2. 环境变量配置

下面通过环境变量配置与日期判断代码，实现新年期间的逻辑控制，请参考具体实现。

46 |         function isLunarNewYearPeriod() {
47 |           const now = new Date();
48 |           const year = now.getFullYear();
49 |           const month = now.getMonth() + 1; // 1-12
50 |           const day = now.getDate();
51 |
52 |           // 2025年蛇年新年期间 (1月29日 - 2月12日)
53 |           if (year === 2025) {
54 |             if (month === 1 && day >= 29) return true;
55 |             if (month === 2 && day <= 12) return true;
56 |           }
57 |           // 2026年马年新年期间 (2月17日 - 3月3日)
58 |           if (year === 2026) {
59 |             if (month === 2 && day >= 17) return true;
60 |             if (month === 3 && day <= 3) return true;
61 |           }
62 |           return false;
63 |         }
64 |
65 |         const stored = localStorage.getItem('starlight-theme');

文件：src/pages/index.astro

为了安全起见，不要硬编码 ID。建议将 ID 存入环境变量。

在项目根目录创建 .env 文件：

# Microsoft Clarity ID
PUBLIC_CLARITY_ID="你的_Clarity_ID"

3. 创建覆盖组件

以下是监听系统主题变化的实现代码，展示了如何仅在未手动设置时跟随系统切换主题。

445 |     const handleChange = (e: MediaQueryListEvent) => {
446 |       // 仅在用户未手动设置时跟随系统
447 |       if (!localStorage.getItem(THEME_KEY)) {
448 |         setThemeState(e.matches ? 'dark' : 'light');
449 |       }
450 |     };
451 |
452 |     mediaQuery.addEventListener('change', handleChange);
453 |     return () => mediaQuery.removeEventListener('change', handleChange);
454 |   }, []);
455 |
456 |   return { theme, toggleTheme, setTheme: manuallySetTheme };
457 | }
458 | ```
459 |
460 | #### 3. `src/components/ThemeButton.tsx` - 按钮组件
461 |
462 | **职责**：渲染主题切换按钮，处理用户交互
463 |
464 | **组件接口**：

文件：openspec/changes/archive/2026-01-29-theme-toggle-implementation/design.md

在 src/components/ 目录下创建文件 StarlightFooter.astro。Starlight 会自动识别这个文件并覆盖默认的 Footer。

核心代码逻辑如下：

---
// 1. 引入原始组件以保留其默认功能
import DefaultFooter from '@astrojs/starlight/components/StarlightFooter.astro';

// 2. 获取环境变量
const clarityId = import.meta.env.PUBLIC_CLARITY_ID;

// 3. 定义简单的注入脚本（内联方式）
// 注意：生产环境建议将此逻辑抽离到单独的 .js 文件中以利用缓存
const initScript = `
(function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "${clarityId}");
`;
---

<DefaultFooter {...Astro.props} />

{/* 仅在生产环境且 ID 存在时注入脚本 */}
{import.meta.env.PROD && clarityId && (
  <script is:inline define:vars={{ clarityId }}>
    {initScript}
  </script>
)}

关键点解析：

is:inline：告诉 Astro 不要处理这个 script 标签内的内容，直接输出到 HTML。这对第三方统计脚本至关重要，否则 Astro 的打包优化可能会导致脚本失效。
define:vars：这是 Astro 3+ 的特性，允许在作用域内安全地注入变量。
import.meta.env.PROD：确保在本地开发时（除非为了调试）不产生无效统计，保持数据纯净。

仅仅加上代码是不够的，特别是在 GDPR 管辖区域。我们需要尊重用户的选择。

HagiCode 的做法是提供一个简单的开关。虽然这不是全功能的 Cookie Banner，但对于纯展示的技术文档站点来说，通常属于”必要”或”统计”类 Cookie，可以通过隐私声明告知并默认开启，或者在 Footer 链接到隐私设置页面。

如果需要更严谨的控制，你可以结合 localStorage 来记录用户的选择：

本文将介绍用于主题切换与持久化的 TypeScript 工具函数，通过类型安全与环境检测实现严谨控制。

367 | export function getInitialTheme(): Theme;
368 | export function getSystemTheme(): Theme;
369 | export function setTheme(theme: Theme): void;
370 | export function applyTheme(theme: Theme): void;
371 | ```
372 |
373 | **设计原则**：
374 | - **纯函数**：无副作用（除了 `setTheme` 和 `applyTheme`）
375 | - **类型安全**：完整的 TypeScript 类型推导
376 | - **环境检测**：SSR 安全（`typeof window` 检查）
377 | - **单一职责**：每个函数只做一件事
378 |
379 | **关键实现**：
380 | ```typescript
381 | export function getInitialTheme(): Theme {
382 |   if (typeof window === 'undefined') return 'dark';
383 |
384 |   const stored = localStorage.getItem(THEME_KEY);
385 |   if (stored === 'light' || stored === 'dark') return stored;
386 |

文件：openspec/changes/archive/2026-01-29-theme-toggle-implementation/design.md

// 简单示例：检查用户是否拒绝统计
const consent = localStorage.getItem('clarity_consent');
if (consent !== 'denied') {
    // 执行上面的 Clarity 初始化代码
    window.clarity('start', clarityId);
}

经验总结与坑点

在将这套方案落地到 HagiCode 的过程中，我们总结了几个容易被忽视的细节：

StarlightWrapper.astro 是个陷阱：如前所述，不要试图去创建一个全局 Wrapper 来注入脚本，这在 Starlight 中行不通。老老实实覆盖特定组件（如 StarlightFooter.astro 或 StarlightHead.astro）才是正解。
脚本位置的性能考量：虽然 Clarity 建议放在 <head> 中以确保数据准确性，但对于文档站点，首屏加载速度（LCP）直接影响了 SEO 和用户留存。我们选择了放在 Footer（Body 底部），这会轻微丢失极少量”秒退”用户的数据，但换来了更快的页面加载体验，这是一个值得的权衡。
开发环境的干扰：一定要加上 import.meta.env.PROD 判断。在开发模式下，你会频繁刷新页面，这会产生大量无意义的测试数据，污染你的 Clarity 仪表盘。

效果验证

部署完成后，你可以在 Clarity 控制台查看实时数据。通常在几分钟内，你就能看到用户的heatmap（热力图）和 recordings（录屏）。

对于 HagiCode 来说，通过这些数据我们发现：

很多用户会反复查看”快速开始”章节，说明我们的安装指引可能还不够直观。
“API 参考”页面的停留时间最长，证实了我们核心用户群体的需求。

总结

接入 Microsoft Clarity 并不需要复杂的服务端改造，也不需要引入沉重的 SDK。

利用 Starlight 的组件覆盖机制，我们仅通过一个轻量级的 StarlightFooter.astro 组件，就实现了全局数据统计。这种”微集成”的方式，既保证了代码的整洁，又赋予了我们洞察用户行为的能力。

如果你也在运营技术类项目，特别是像 HagiCode 这样需要不断迭代文档的项目，强烈建议尝试接入 Clarity。数据会告诉你，用户真正的痛点在哪里。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026-02-04-starlight-docs-integration-microsoft-clarity/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

HagiCode 启动页设计：React 19 应用中填补 Hydration 空白期的极致体验

2026年2月3日

为 HagiCode 设计 12 种极致的启动体验：从极简到赛博朋克

在 React 19 应用下载和 Hydration 的短暂间隙，是留给用户感知品牌个性的黄金窗口。本文分享了我们在 HagiCode 项目中，基于 HTML/CSS/JS 构建的一套完整的启动风格系统。

背景

HagiCode 作为一个基于 ASP.NET Core 10 和 React 19 (Vite) 的现代化应用，采用了前后端分离部署的架构。前端产物被打包放置于后端的 wwwroot/ 目录下由 ASP.NET Core 托管。

然而，这种架构带来了一个经典的用户体验痛点：当用户访问网页时，浏览器需要先加载 HTML，再下载巨大的 JS Bundle，最后由 React 执行 Hydration（注水）。在这几百毫秒到数秒的”真空期”里，用户面对的是一片空白，或者是一个毫无生气的静态页面。

为了填补这段间隙，并注入 HagiCode 的品牌个性，我们需要设计一套完全基于 index.html 内联代码的启动风格系统。

关于 HagiCode

本文分享的启动页设计方案来自我们在 HagiCode 项目中的实践经验。作为一个 AI 代码助手，HagiCode 不仅关注代码生成的效率，也同样重视开发者的视觉体验。这套启动系统正是我们在追求极致前端性能过程中的产物。

核心挑战与架构设计

在动手设计之前，我们必须先明确技术约束。既然要在 index.html 中内联实现，意味着我们不能加载任何外部 CSS 或 JS 文件（除了 React 本身的 Bundle）。

技术约束分析

零依赖原则：所有样式必须写在 <style> 标签内，逻辑写在 <script> 标签内。
防御式 CSS：为了防止 React 应用挂载后，全局样式污染启动页，我们决定使用高优先级的 ID 前缀（如 #boot-screen）包裹所有启动样式。
性能优先：动画尽量使用 CSS transform 和 opacity，避免触发重排，确保不阻塞主线程。
视觉一致性：颜色、字体必须与 HagiCode 的 Tailwind 配置保持一致。

架构模式：Shell & Injector

我们采用了一种变体模式。核心逻辑封装在一个立即执行函数（IIFE）中，具体的渲染逻辑作为配置项注入。这样我们就可以通过简单的配置切换不同的风格，而不需要重复编写 DOM 操作逻辑。

以下是核心的架构代码：

<!-- 内联于 index.html -->
<div id="boot-root"></div>

<script>
(function() {
  const BootSequence = {
    config: {
      theme: 'terminal', // 可配置为 'minimal', 'skeleton', 'code-rain' 等
      color: '#3b82f6'   // 品牌色
    },

    // 核心生命周期
    init() {
      this.render();
      this.listenForMount();
    },

    // 渲染当前选定的风格
    render() {
      const root = document.getElementById('boot-root');
      if (this.variants[this.config.theme]) {
        root.innerHTML = this.variants[this.config.theme].render();
      }
    },

    // 监听 React 挂载成功，优雅退出
    listenForMount() {
      window.addEventListener('hagicode:ready', () => {
        const screen = document.getElementById('boot-root');
        // 先淡出，再移除 DOM，避免闪烁
        screen.style.opacity = '0';
        screen.style.transition = 'opacity 0.3s ease';
        setTimeout(() => screen.remove(), 300);
      });
    },

    // 12种风格的实现逻辑集中在这里
    variants: {
      // ...具体实现见下文
    }
  };

  BootSequence.init();
})();
</script>

12 种启动风格设计清单

我们将这 12 种风格分为了六大类，以满足不同场景和审美需求。

A. 极简主义

“少即是多”。对于追求极致加载速度的场景，我们提供了最轻量的方案。

1. Minimalist Dot (极简呼吸)

屏幕中心只有一个简单的圆点，配合呼吸动画。

实现：CSS @keyframes 控制scale和opacity。
适用：任何需要保持页面绝对干净的场合。

2. Brand Reveal (品牌揭示)

通过 SVG stroke-dasharray 动画，模拟手绘般绘制出 HagiCode 的 Logo 线条，随后淡入文字。

技巧：使用 SVG 路径动画，极具质感。

B. 骨架屏拟态

“欺骗眼睛的艺术”。通过模拟真实 UI 布局，让用户感觉页面已经加载了一半。

这可能是最实用的一种。我们手动用 HTML 构建了与 React 组件 Sidebar 和 ChatInput 一模一样的布局，并覆盖灰色条纹动画。

价值：当 React hydrate 完成时，骨架屏瞬间变成真实组件，用户几乎感觉不到切换。

4. Card Stack Skeleton (卡片堆叠)

模拟提案卡片加载时的堆叠动效，使用 3D 变换让卡片微微浮动。

C. 抽象与艺术

展示 HagiCode 的极客基因。

5. Geometric Morph (几何变形)

在屏幕中心渲染一个几何体（正方形），它会随着时间平滑地变换为圆形、三角形，最后变成 Logo。

技术：CSS border-radius 的平滑过渡。

6. Code Rain (代码雨)

向《黑客帝国》致敬。使用 JetBrains Mono 字体，在背景中落下淡淡的字符流。

注意：为了性能，字符流必须限制在较小的区域或降低刷新频率。

7. Neon Pulse (霓虹脉冲)

赛博朋克风格的发光圆环，利用 box-shadow 的多重叠加产生强烈的发光感。

D. 品牌与主题

让系统”活”起来。

8. Seasonal Theme (节日主题)

这是一个动态加载器。根据当前日期判断节日（如春节、圣诞节），加载对应的 SVG 动画。

例子：春节时，屏幕下方会有红灯笼轻轻摆动。

9. Gradient Flow (渐变流)

背景使用 HagiCode 品牌色的流体渐变，配合 background-size 和 background-position 的动画，营造出极光般的流动感。

E. 技术感

向开发者致敬。

10. Terminal Boot (终端启动)

模拟控制台输出。一行行代码快速滚动：

> Initializing HagiCode Core...
> Loading models...
> Connecting to neural network...

这会让每一个开发者都感到亲切。

11. Progress Bar (极简进度条)

屏幕顶部一条细细的进度条，右侧显示百分比。虽然我们无法获取真实的下载进度，但可以用一个定时器模拟出一个”可信”的加载过程（前 80% 快速，后 20% 减速）。

F. 创意

12. Pixel Assembly (像素组装)

这是一个很有趣的创意。屏幕上散落着一些方块，它们汇聚到中心，逐渐拼凑出 HagiCode 的 Logo 图标。象征着代码的构建过程。

最佳实践与踩坑总结

在 HagiCode 的实际开发中，我们总结了一些至关重要的实践细节。

1. 防御式 CSS 是必须的

千万别偷懒不写前缀。曾经有一次，我们没有给启动页样式加 ID 限制，导致 React 挂载后的全局 div 样式意外影响了启动页，导致布局崩坏。经验：所有 CSS 选择器都挂在 #boot-screen 下，且使用 !important 提升优先级（仅在启动页 CSS 中）。

2. 优雅的过渡

React mount 成功后，不要直接 remove() 启动页 DOM。 正确做法：

React 触发 window.dispatchEvent(new Event('hagicode:ready'))。
启动页监听到事件，先设置 opacity: 0。
等待 300ms (CSS transition 时间)，确保用户看不见了，再执行 .remove()。

3. 主题变量同步

启动页的颜色代码是写死在 index.html 里的。如果我们修改了 Tailwind 的主色，必须同步修改这里。 优化方案：在 Vite 构建脚本中，编写一个简单的插件，读取 tailwind.config.js 并将颜色变量注入到 index.html 的模板变量中，实现单一数据源。

4. 字体预加载

启动页通常需要使用品牌字体，但如果字体加载慢，会出现 FOUT (Flash of Unstyled Text)。 解决方案：在 <head> 中加入 <link rel="preload" href="/fonts/JetBrainsMono.woff2" as="font" type="font/woff2" crossorigin>。这是提升体验的低成本高回报手段。

5. 性能监控

我们在 index.html 底部注入了 performance.mark('boot-start')，并在 React 挂载成功时标记 boot-end。意义：通过 Application Insights 收集这些数据，我们可以真实看到启动页对用户感知等待时间（Perceived Loading Time）的缩短程度。数据表明，优秀的骨架屏能让用户对”慢速网络”的容忍度提升 50% 以上。

总结

一个好的启动页，不仅仅是”等待时的装饰”，它是产品与用户第一次交互的握手信号。在 HagiCode 项目中，这套基于 Variants 模式的启动系统，让我们能够灵活地在不同节日、不同版本间切换风格，极大地增强了产品的趣味性和专业感。

本文分享的方案完全基于原生 Web 标准，没有引入任何沉重的依赖，这正是 HagiCode 追求”轻量且强大”的体现。如果你觉得这套方案有价值，欢迎来 HagiCode 仓库看看我们的源码实现，甚至贡献你的创意设计！

参考资料

HagiCode 项目地址：https://github.com/HagiCode-org/site
官网了解更多：https://hagicode.com
观看实战演示：https://www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：https://hagicode.com/installation/docker-compose

如果本文对你有帮助，欢迎来 GitHub 给个 Star，公测已开始，期待你的反馈！

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026-02-03-hagicode-react-19-hydration-splash-screen/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

.NET Core 双数据库实战：优雅融合 PostgreSQL 与 SQLite 的最佳实践

2026年2月1日

.NET Core 双数据库实战：让 PostgreSQL 与 SQLite 和平共处

在构建现代化应用时，我们经常面临这样的抉择：开发环境渴望轻量便捷，而生产环境则需要高并发与高可用。本文将分享如何在 .NET Core 项目中优雅地同时支持 PostgreSQL 和 SQLite，实现“开发用 SQLite，生产用 PG”的最佳实践。

背景

在软件开发中，环境差异化一直是困扰开发团队的难题之一。以我们正在构建的 HagiCode 平台为例，这是一个基于 ASP.NET Core 10 和 React 的 AI 辅助开发系统，内部集成了 Orleans 进行分布式状态管理，技术栈相当现代且复杂。

在项目初期，我们遇到了一个典型的工程痛点：开发人员希望本地环境能够“开箱即用”，不希望安装和配置繁重的 PostgreSQL 数据库；但在生产环境中，我们需要处理高并发写入和复杂的 JSON 查询，这时轻量级的 SQLite 又显得力不从心。

如何在保持代码库统一的前提下，让应用既能像客户端软件一样利用 SQLite 的便携性，又能像企业级服务一样发挥 PostgreSQL 的强悍性能？这就是本文要探讨的核心问题。

关于 HagiCode

本文分享的双数据库适配方案，直接来源于我们在 HagiCode 项目中的实战经验。HagiCode 是一个集成了 AI 提示词管理和 OpenSpec 工作流的下一代开发平台。正是为了兼顾开发者的体验和生产环境的稳定性，我们探索出了这套行之有效的架构模式。

欢迎访问我们的 GitHub 仓库了解项目全貌：HagiCode-org/site。

核心内容一：架构设计与统一抽象

要在 .NET Core 中实现双数据库支持，核心思想是“依赖抽象而非具体实现”。我们需要把数据库的选择权从业务代码中剥离出来，交给配置层决定。

设计思路

统一接口：所有的业务逻辑都应依赖于 DbContext 基类或自定义的接口，而不是具体的 PostgreSqlDbContext。
配置驱动：通过 appsettings.json 中的配置项，在应用启动时动态决定加载哪个数据库提供程序。
特性隔离：针对 PostgreSQL 特有的功能（如 JSONB）进行适配处理，确保在 SQLite 中也能降级运行。

代码实现：动态上下文配置

在 ASP.NET Core 的 Program.cs 中，我们不应硬编码 UseNpgsql 或 UseSqlite。相反，我们应该读取配置来动态决定。

首先，定义配置类：

public class DatabaseSettings
{
    public const string SectionName = "Database";

    // 数据库类型：PostgreSQL 或 SQLite
    public string DbType { get; set; } = "PostgreSQL";

    // 连接字符串
    public string ConnectionString { get; set; } = string.Empty;
}

然后，在 Program.cs 中根据配置注册服务：

// 读取配置
var databaseSettings = builder.Configuration.GetSection(DatabaseSettings.SectionName).Get<DatabaseSettings>();

// 注册 DbContext
builder.Services.AddDbContext<ApplicationDbContext>(options =>
{
    if (databaseSettings?.DbType?.ToLower() == "sqlite")
    {
        // SQLite 配置
        options.UseSqlite(databaseSettings.ConnectionString);

        // SQLite 的并发写入限制处理
        // 注意：在生产环境中建议开启 WAL 模式以提高并发性能
    }
    else
    {
        // PostgreSQL 配置（默认）
        options.UseNpgsql(databaseSettings.ConnectionString, npgsqlOptions =>
        {
            // 开启 JSONB 支持，这在处理 AI 对话记录时非常有用
            npgsqlOptions.UseJsonNet();
        });

        // 配置连接池重连策略
        options.EnableRetryOnFailure(3);
    }
});

核心内容二：处理差异性与迁移策略

PostgreSQL 和 SQLite 虽然都支持 SQL 标准，但在具体特性和行为上存在显著差异。如果不处理好这些差异，很可能会出现“本地跑得通，上线就报错”的尴尬情况。

1. JSON 类型的处理

在 HagiCode 中，我们需要存储大量的提示词和 AI 元数据，这通常涉及 JSON 列。

PostgreSQL：拥有原生的 JSONB 类型，查询性能极佳。
SQLite：没有原生的 JSON 类型（新版本有 JSON1 扩展，但对象映射上仍有差异），通常存储为 TEXT。

解决方案：在 EF Core 的实体映射中，我们将其配置为可转换的类型。

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);

    // 配置实体
    modelBuilder.Entity<PromptTemplate>(entity =>
    {
        entity.Property(e => e.Metadata)
              .HasColumnType("jsonb") // PG 使用 jsonb
              .HasConversion(
                  v => JsonSerializer.Serialize(v, (JsonSerializerOptions)null),
                  v => JsonSerializer.Deserialize<Dictionary<string, object>>(v, (JsonSerializerOptions)null)
              );
    });
}

当使用 SQLite 时，虽然 HasColumnType("jsonb") 会被忽略或产生警告，但由于配置了 HasConversion，数据会被正确地序列化和反序列化为字符串存入 TEXT 字段，从而保证了兼容性。

2. 迁移策略的分离

绝对不要试图让同一套 Migration 脚本同时适配 PG 和 SQLite。由于主键生成策略、索引语法等的不同，这必然会导致失败。

推荐实践：维护两个迁移分支或项目。在 HagiCode 的开发流中，我们是这样处理的：

开发阶段：主要在 SQLite 下工作。使用 Add-Migration Init_Sqlite -OutputDir Migrations/Sqlite。
适配阶段：开发完一段功能后，切换连接字符串指向 PostgreSQL，执行 Add-Migration Init_Postgres -OutputDir Migrations/Postgres。
自动化脚本：编写一个简单的 PowerShell 或 Bash 脚本，根据当前环境变量自动应用对应的迁移。

# 简单的部署逻辑伪代码
if [ "$DATABASE_PROVIDER" = "PostgreSQL" ]; then
    dotnet ef database update --project Migrations.Postgres
else
    dotnet ef database update --project Migrations.Sqlite
fi

核心内容三：HagiCode 的实战经验总结

在将 HagiCode 从单一数据库重构为双数据库支持的过程中，我们踩过一些坑，也总结了一些关键的经验，希望能给大家避坑。

1. 并发与事务的区别

PostgreSQL 是服务端-客户端架构，支持高并发写入，事务隔离级别非常强大。而 SQLite 是文件锁机制，写入操作会锁定整个数据库文件（除非开启 WAL 模式）。

建议：在编写涉及频繁写入的业务逻辑时（例如实时保存用户的编辑状态），一定要考虑到 SQLite 的锁机制。在设计 HagiCode 的 OpenSpec 协作模块时，我们引入了“写前合并”机制，减少数据库的直接写入频率，从而在两种数据库下都能保持高性能。

2. 连接字符串的生命周期管理

PostgreSQL 的连接建立成本较高，依赖连接池。而 SQLite 连接非常轻量，但如果不及时释放，文件锁可能会导致后续操作超时。

在 Program.cs 中，我们可以针对不同数据库做精细化调整：

if (databaseSettings?.DbType?.ToLower() == "sqlite")
{
    // SQLite：保持连接开启能提升性能，但要注意文件锁
    options.UseSqlite(connectionString, sqliteOptions =>
    {
        // 设置命令超时时间
        sqliteOptions.CommandTimeout(30);
    });
}
else
{
    // PG：利用连接池
    options.UseNpgsql(connectionString, npgsqlOptions =>
    {
        npgsqlOptions.MaxBatchSize(100);
        npgsqlOptions.CommandTimeout(30);
    });
}

3. 测试覆盖的重要性

很多开发者（包括我们团队早期的成员）容易犯一个错误：只在开发环境（通常是 SQLite）跑单元测试。

我们在 HagiCode 的 CI/CD 流水线中强制加入了 GitHub Action 步骤，确保每次 Pull Request 都要跑过 PostgreSQL 的集成测试。

# .github/workflows/test.yml 示例片段
- name: Run Integration Tests (PostgreSQL)
  run: |
    docker-compose up -d db_postgres
    dotnet test --filter "Category=Integration"

这帮我们拦截了无数次关于 SQL 语法差异、大小写敏感性的 Bug。

总结

通过引入抽象层和配置驱动的依赖注入，我们在 HagiCode 项目中成功实现了 PostgreSQL 和 SQLite 的“双轨制”运行。这不仅极大降低了新开发者的上手门槛（不需要装 PG），也为生产环境提供了坚实的性能保障。

回顾一下关键点：

抽象至上：业务代码不依赖具体数据库实现。
配置分离：开发和生产使用不同的 appsettings.json。
迁移分离：不要尝试一套 Migration 走天下。
特性降级：在 SQLite 中以兼容性优先，在 PostgreSQL 中以性能优先。

这种架构模式不仅适用于 HagiCode，也适用于任何需要在轻量级开发和重量级生产之间寻找平衡的 .NET 项目。

如果本文对你有帮助，欢迎来 GitHub 给个 Star，或者直接体验 HagiCode 带来的高效开发流程：

来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：hagicode.com/installation/docker-compose

公测已开始，欢迎安装体验！

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026-02-01-dotnet-core-dual-database-postgresql-sqlite/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

Docusaurus 3.x 到 Astro 5.x 迁移实战：利用 Islands 架构实现性能与构建速度双重提升

2026年1月31日

从 Docusaurus 3.x 到 Astro 5.x：HagiCode 站点迁移实战复盘

本文复盘了我们将 HagiCode 官方网站从 Docusaurus 3.x 迁移至 Astro 5.x 的全过程。我们将深入探讨如何通过 Astro 的 Islands 架构解决性能瓶颈，同时保留现有的 React 组件资产，实现构建速度与加载性能的双重提升。

背景

2026 年 1 月，我们对 HagiCode 的官方站点进行了一次”心脏移植手术”——将核心框架从 Docusaurus 3.x 全面迁移至 Astro 5.x。这不是一次冲动的大重构，而是经过深思熟虑的技术抉择。

在迁移前，我们的站点虽然功能完善，但逐渐显露出一些”富贵病”：构建产物体积臃肿、JavaScript 负载过高，且页面加载速度在复杂文档页面下不够理想。作为一个 AI 代码助手项目，HagiCode 需要频繁更新文档和功能介绍，构建效率直接影响发布速度。同时，我们希望站点对搜索引擎（SEO）更加友好，以便让更多开发者发现这个项目。

为了解决这些痛点，我们做了一个大胆的决定：整个构建系统推倒重来，迁移到 Astro。这个决定带来的变化，可能比你想象的还要大——稍后我会具体说。

关于 HagiCode

本文分享的站点迁移方案，来自我们在 HagiCode 项目中的实践经验。

HagiCode 是一款致力于提升开发效率的 AI 代码助手，我们不仅关注核心功能的迭代，同样重视开发者体验。这次站点的重构，也是为了让用户在浏览文档和官网时能获得极致的加载速度。

为什么要放弃成熟的 Docusaurus？

在 React 生态中，Docusaurus 一直是文档站点的”标准答案”。它开箱即用，插件丰富，社区活跃。但是，随着 HagiCode 功能的增加，我们也感受到了它的局限性：

性能瓶颈：Docusaurus 本质上是一个 React SPA（单页应用）。哪怕你是写纯静态页面，客户端也需要加载 React 运行时并进行水合，这对于简单的文档页面来说太重了。
资源体积：即便页面内容很少，打包后的 JS 体积也相对固定，这对移动端用户和网络较差的环境不够友好。
灵活性不足：虽然也能扩展，但在构建流程的定制上，我们渴望拥有更底层的控制权。

Astro 的出现正好解决了这些问题。它提供了一个全新的”岛屿架构”（Islands Architecture）：默认情况下，Astro 生成零 JavaScript 的静态 HTML，只有需要交互的组件才会”激活”并加载 JS。这意味着我们的站点大部分内容都是纯 HTML，速度极快。

迁移核心策略：架构平滑过渡

迁移不是简单的复制粘贴，而是思维模式的转变。我们从 Docusaurus 的”全 React 模式”切换到了 Astro 的”Core + Islands”模式。

1. 配置系统的重构

首先，我们需要从 docusaurus.config.ts 转向 astro.config.mjs。这不仅是文件名的变化，更是路由和构建逻辑的重写。

在 Docusaurus 中，一切皆插件；而在 Astro 中，一切皆集成。我们需要重新定义站点的基础路径、构建输出模式（静态 vs SSR）以及资源压缩策略。

迁移前：

export default {
  title: 'HagiCode',
  url: 'https://hagicode.com',
  baseUrl: '/',
  // ... 更多配置
};

迁移后：

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [react()],
  site: 'https://hagicode.com',
  base: '/',
  // 针对静态资源的优化配置
  build: {
    inlineStylesheets: 'auto',
  },
});

2. React 组件的去留与改造

这是迁移中最头疼的部分。我们现有的站点有很多 React 组件（比如 Tabs 组件、代码高亮、反馈按钮等）。直接扔掉太可惜，全都保留又会导致 JS 负载过重。

HagiCode 采用了渐进式水合策略：

纯静态组件：对于展示型内容（如页眉、页脚、纯文本文档），重写为 Astro 组件（.astro 文件），在构建时直接渲染为 HTML。
交互式岛屿：对于必须保留交互的组件（如主题切换器、Tabs 切换、代码块复制按钮），保留 React 实现，并添加 client:load 或 client:visible 指令。

例如，我们的文档中常用的 Tabs 组件：

import { useState } from 'react';
import './Tabs.css'; // 引入样式

export default function Tabs({ items }) {
  const [activeIndex, setActiveIndex] = useState(0);
  // ... 状态逻辑
  return (
    <div className="tabs-wrapper">
      {/* 渲染逻辑 */}
    </div>
  );
}

在 Markdown 中使用时，我们明确告诉 Astro：“这个组件需要 JS”：

import Tabs from '../../components/Tabs.jsx';

<!-- 只在组件进入视口时才加载 JS -->
<Tabs client:visible items={...} />

这样，非视口内的交互组件不会抢占带宽，极大地优化了首屏加载速度。

3. 样式系统的适配：CSS Modules 到 Scoped

Docusaurus 默认支持 CSS Modules，而 Astro 推崇使用 Scoped CSS（通过 <style> 标签）。两者的核心思想都是隔离样式，但语法不同。

在 HagiCode 的迁移中，我们将大部分复杂的 CSS Modules 拆解为 Astro 的 Scoped 样式。这其实是件好事，因为在 .astro 文件中，样式和模板写在同一个文件里，维护起来更加直观。

改造前：

.wrapper { background: var(--ifm-background-color); }

改造后 (Astro Scoped):

<div class="tabs-wrapper">
  <slot />
</div>

<style>
  .tabs-wrapper {
    /* 直接使用 CSS 变量，适配主题 */
    background: var(--bg-color);
    padding: 1rem;
  }
</style>

同时，我们统一了全局 CSS 变量系统，利用 Astro 的环境感知能力，确保暗色模式在不同页面间的切换无缝衔接。

实践中的坑与解决方案

在 HagiCode 的实际迁移过程中，我们遇到了不少坑，这里挑几个最典型的分享一下。

1. 路径与环境变量的痛点

HagiCode 支持子路径部署（比如部署到 GitHub Pages 的子目录）。在 Docusaurus 中，它自动处理 baseUrl。但在 Astro 中，处理图片链接和 API 请求时，我们需要更小心。

我们引入了环境变量机制来统一管理：

// 在构建脚本中处理路径
const getBasePath = () => import.meta.env.VITE_SITE_BASE || '/';

切记，不要在代码中硬编码 / 开头的路径。在开发环境和生产环境，或者配置了 base 路径后，这会导致资源 404。

2. CommonJS 脚本的兼容

我们的旧站点有一些 Node.js 脚本（用于自动抓取 Metrics 数据、更新 sitemap 等），它们是用 CommonJS (require) 写的。Astro 和现代构建工具全面拥抱 ES Modules (import/export)。

如果你也有类似的脚本，记得把它们全部重构为 ES Modules。这是大势所趋，早点改了早点省心。

// 旧方式
const fs = require('fs');

// 新方式
import fs from 'fs';

3. 别忘了 SEO 与重定向

搜索引擎已经收录了 HagiCode 旧的 Docusaurus 页面。如果直接切到 Astro，URL 结构发生变化，会导致大量 404，权重大跌。

我们在 Astro 中配置了重定向规则：

export default defineConfig({
  redirects: {
    '/docs/old-path': '/docs/new-path',
    // 批量映射旧链接到新链接
  }
});

或者在服务器配置层面处理。确保旧链接能 301 重定向到新地址，这对 SEO 至关重要。

总结

从 Docusaurus 迁移到 Astro，对 HagiCode 来说，不仅仅是一次框架升级，更是一次对”性能优先”理念的实践。

我们的收获：

极致的 Lighthouse 分数：迁移后，HagiCode 站点的性能评分轻松接近满分。
更快的构建速度：Astro 的增量构建让我们文档更新的发布时间缩短了一半。
保留了灵活性：通过 Islands 架构，我们没有牺牲任何交互功能，依然可以在需要的地方使用 React。

如果你也在维护文档型站点，并且深受打包体积或加载速度的困扰，不妨试试 Astro。虽然迁移过程需要动动手术（比如把 PCode 的名字改成 HagiCode，把组件一个个挖过来），但换来的是如丝般顺滑的用户体验，绝对值得。

本文分享的构建系统，正是我们在开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下。

参考资料

Astro 官方文档
从 Docusaurus 迁移指南
Islands 架构详解
HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode-org.github.io/site
一键安装体验：hagicode-org.github.io/site/docs/installation/docker-compose

如果本文对你有帮助，欢迎来 GitHub 给个 Star，公测已经开始啦！

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode-org.github.io/site/blog/2026-01-31-migrate-docusaurus-to-astro-with-islands-architecture/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

StreamJsonRpc 在 HagiCode 中的深度集成与实践

2026年1月28日

StreamJsonRpc 在 HagiCode 中的深度集成与实践

本文详细介绍了 HagiCode（原 PCode）项目如何成功集成 Microsoft 的 StreamJsonRpc 通信库，以替换原有的自定义 JSON-RPC 实现，并解决了集成过程中的技术痛点与架构挑战。

背景

StreamJsonRpc 是微软官方维护的用于 .NET 和 TypeScript 的 JSON-RPC 通信库，以其强大的类型安全、自动代理生成和成熟的异常处理机制著称。在 HagiCode 项目中，为了通过 ACP (Agent Communication Protocol) 与外部 AI 工具（如 iflow CLI、OpenCode CLI）进行通信，并消除早期自定义 JSON-RPC 实现带来的维护成本和潜在 Bug，项目决定集成 StreamJsonRpc。然而，在集成过程中遇到了流式 JSON-RPC 特有的挑战，特别是在处理代理目标绑定和泛型参数识别时。

为了解决这些痛点，我们做了一个大胆的决定：整个构建系统推倒重来。这个决定带来的变化，可能比你想象的还要大——稍后我会具体说。

关于 HagiCode

先介绍一下本文的”主角项目”

如果你在开发中遇到过这些烦恼：

多项目、多技术栈，构建脚本维护成本高
CI/CD 流水线配置繁琐，每次改都要查文档
跨平台兼容性问题层出不穷
想让 AI 帮忙写代码，但现有工具不够智能

那么我们正在做的 HagiCode 可能你会感兴趣。

HagiCode 是什么？

一款 AI 驱动的代码智能助手
支持多语言、跨平台的代码生成与优化
内置游戏化机制，让编码不再枯燥

为什么在这里提它？ 本文分享的 StreamJsonRpc 集成方案，正是我们在开发 HagiCode 过程中实践总结出来的。如果你觉得这套工程化方案有价值，说明我们的技术品味还不错——那么 HagiCode 本身也值得关注一下。

想了解更多？

GitHub: github.com/HagiCode-org/site（求 Star）
官网: hagicode.com
视频演示: www.bilibili.com/video/BV1pirZBuEzq/（30 分钟实战演示）
安装指南: hagicode.com/installation/docker-compose
公测已开始：现在安装即可参与公测

分析

当前项目处于 ACP 协议集成的关键阶段，面临着以下几个技术痛点和架构挑战：

1. 自定义实现的局限

原有的 JSON-RPC 实现位于 src/HagiCode.ClaudeHelper/AcpImp/，包含 JsonRpcEndpoint 和 ClientSideConnection 等组件。维护这套自定义代码成本高，且缺乏成熟库的高级功能（如进度报告、取消支持）。

2. StreamJsonRpc 集成障碍

在尝试将现有的 CallbackProxyTarget 模式迁移到 StreamJsonRpc 时，发现 _rpc.AddLocalRpcTarget(target) 方法无法识别通过代理模式创建的目标。具体表现为，StreamJsonRpc 无法自动将泛型类型 T 的属性拆分为 RPC 方法参数，导致服务器端无法正确处理客户端发起的方法调用。

3. 架构分层混乱

现有的 ClientSideConnection 混合了传输层（WebSocket/Stdio）、协议层（JSON-RPC）和业务层（ACP Agent 接口），导致职责不清，且存在 AcpAgentCallbackRpcAdapter 方法绑定缺失的问题。

4. 日志缺失

WebSocket 传输层缺少对原始 JSON 内容的日志输出，导致在调试 RPC 通信问题时难以定位是序列化问题还是网络问题。

解决

针对上述问题，我们采用了以下系统化的解决方案，从架构重构、库集成和调试增强三个维度进行优化：

1. 全面迁移至 StreamJsonRpc

移除旧代码

删除 JsonRpcEndpoint.cs、AgentSideConnection.cs 及相关的自定义序列化转换器（JsonRpcMessageJsonConverter 等）。

集成官方库

引入 StreamJsonRpc NuGet 包，利用其 JsonRpc 类处理核心通信逻辑。

抽象传输层

定义 IAcpTransport 接口，统一处理 WebSocket 和 Stdio 两种传输模式，确保协议层与传输层解耦。

// IAcpTransport 接口定义
public interface IAcpTransport
{
    Task SendAsync(string message, CancellationToken cancellationToken = default);
    Task<string> ReceiveAsync(CancellationToken cancellationToken = default);
    Task CloseAsync(CancellationToken cancellationToken = default);
}

// WebSocket 传输实现
public class WebSocketTransport : IAcpTransport
{
    private readonly WebSocket _webSocket;

    public WebSocketTransport(WebSocket webSocket)
    {
        _webSocket = webSocket;
    }

    // 实现发送和接收方法
    // ...
}

// Stdio 传输实现
public class StdioTransport : IAcpTransport
{
    private readonly StreamReader _reader;
    private readonly StreamWriter _writer;

    public StdioTransport(StreamReader reader, StreamWriter writer)
    {
        _reader = reader;
        _writer = writer;
    }

    // 实现发送和接收方法
    // ...
}

2. 修复代理目标识别问题

分析 `CallbackProxyTarget`

检查现有的动态代理生成逻辑，确定 StreamJsonRpc 无法识别的根本原因（通常是因为代理对象没有公开实际的方法签名，或者使用了 StreamJsonRpc 不支持的参数类型）。

重构参数传递

将泛型属性拆分为明确的 RPC 方法参数。不再依赖动态属性，而是定义具体的 Request/Response DTO（数据传输对象），确保 StreamJsonRpc 能通过反射正确识别方法签名。

// 原有的泛型属性方式
public class CallbackProxyTarget<T>
{
    public Func<T, Task> Callback { get; set; }
}

// 重构后的具体方法方式
public class ReadTextFileRequest
{
    public string FilePath { get; set; }
}

public class ReadTextFileResponse
{
    public string Content { get; set; }
}

public interface IAcpAgentCallback
{
    Task<ReadTextFileResponse> ReadTextFileAsync(ReadTextFileRequest request);
    // 其他方法...
}

使用 `Attach` 替代 `AddLocalRpcTarget`

在某些复杂场景下，手动代理 JsonRpc 对象并处理 RpcConnection 可能比直接添加目标更灵活。

3. 实现方法绑定与日志增强

实现 `AcpAgentCallbackRpcAdapter`

确保该组件显式实现 StreamJsonRpc 的代理接口，将 ACP 协议定义的方法（如 ReadTextFileAsync）映射到 StreamJsonRpc 的回调处理器上。

集成日志记录

在 WebSocket 或 Stdio 的消息处理管道中，拦截并记录 JSON-RPC 请求和响应的原始文本。利用 ILogger 在解析前和序列化后输出原始 payload，以便排查格式错误。

// 日志增强的传输包装器
public class LoggingAcpTransport : IAcpTransport
{
    private readonly IAcpTransport _innerTransport;
    private readonly ILogger<LoggingAcpTransport> _logger;

    public LoggingAcpTransport(IAcpTransport innerTransport, ILogger<LoggingAcpTransport> logger)
    {
        _innerTransport = innerTransport;
        _logger = logger;
    }

    public async Task SendAsync(string message, CancellationToken cancellationToken = default)
    {
        _logger.LogTrace("Sending message: {Message}", message);
        await _innerTransport.SendAsync(message, cancellationToken);
    }

    public async Task<string> ReceiveAsync(CancellationToken cancellationToken = default)
    {
        var message = await _innerTransport.ReceiveAsync(cancellationToken);
        _logger.LogTrace("Received message: {Message}", message);
        return message;
    }

    public async Task CloseAsync(CancellationToken cancellationToken = default)
    {
        _logger.LogDebug("Closing connection");
        await _innerTransport.CloseAsync(cancellationToken);
    }
}

4. 架构分层重构

传输层 (`AcpRpcClient`)

封装 StreamJsonRpc 连接，负责 InvokeAsync 和连接生命周期管理。

public class AcpRpcClient : IDisposable
{
    private readonly JsonRpc _rpc;
    private readonly IAcpTransport _transport;

    public AcpRpcClient(IAcpTransport transport)
    {
        _transport = transport;
        _rpc = new JsonRpc(new StreamRpcTransport(transport));
        _rpc.StartListening();
    }

    public async Task<TResponse> InvokeAsync<TResponse>(string methodName, object parameters)
    {
        return await _rpc.InvokeAsync<TResponse>(methodName, parameters);
    }

    public void Dispose()
    {
        _rpc.Dispose();
        _transport.Dispose();
    }

    // StreamRpcTransport 是对 IAcpTransport 的 StreamJsonRpc 适配器
    private class StreamRpcTransport : IDuplexPipe
    {
        // 实现 IDuplexPipe 接口
        // ...
    }
}

协议层 (`IAcpAgentClient` / `IAcpAgentCallback`)

定义清晰的 client-to-agent 和 agent-to-client 接口，移除 Func<IAcpAgent, IAcpClient> 这种循环依赖的工厂模式，改用依赖注入或直接注册回调。

实践

基于 StreamJsonRpc 的最佳实践和项目经验，以下是实施过程中的关键建议：

1. 强类型 DTO 优于动态对象

StreamJsonRpc 的核心优势在于强类型。不要使用 dynamic 或 JObject 传递参数。应为每个 RPC 方法定义明确的 C# POCO 类作为参数。这不仅解决了代理目标识别问题，还能在编译时发现类型错误。

示例：将 CallbackProxyTarget 中的泛型属性替换为 ReadTextFileRequest 和 WriteTextFileRequest 等具体类。

2. 显式声明 Method Name

使用 [JsonRpcMethod] 特性显式指定 RPC 方法名称，不要依赖默认的方法名映射。这可以防止因命名风格差异（如 PascalCase vs camelCase）导致的调用失败。

public interface IAcpAgentCallback
{
    [JsonRpcMethod("readTextFile")]
    Task<ReadTextFileResponse> ReadTextFileAsync(ReadTextFileRequest request);

    [JsonRpcMethod("writeTextFile")]
    Task WriteTextFileAsync(WriteTextFileRequest request);
}

3. 利用连接状态回调

StreamJsonRpc 提供了 JsonRpc.ConnectionLost 事件。务必监听此事件以处理进程意外退出或网络断开的情况，这比单纯依赖 Orleans 的 Grain 失效检测更及时。

_rpc.ConnectionLost += (sender, e) =>
{
    _logger.LogError("RPC connection lost: {Reason}", e.ToString());
    // 处理重连逻辑或通知用户
};

4. 日志分层记录

Trace 级别：记录完整的 JSON Request/Response 原文。
Debug 级别：记录方法调用栈和参数摘要。
注意：确保日志中不包含敏感的 Authorization Token 或大文件内容的 Base64 编码。

5. 处理流式传输的特殊性

StreamJsonRpc 原生支持 IAsyncEnumerable。在实现 ACP 的流式 Prompt 响应时，应直接使用 IAsyncEnumerable 而不是自定义的分页逻辑。这能极大简化流式处理的代码量。

public interface IAcpAgentCallback
{
    [JsonRpcMethod("streamText")]
    IAsyncEnumerable<string> StreamTextAsync(StreamTextRequest request);
}

6. 适配器模式 (Adapter Pattern)

保持 ACPSession 和 ClientSideConnection 的分离。ACPSession 应专注于 Orleans 的状态管理和业务逻辑（如消息入队），通过组合而非继承的方式使用 StreamJsonRpc 连接对象。

总结

通过全面集成 StreamJsonRpc，HagiCode 项目成功解决了原自定义实现的维护成本高、功能局限性和架构分层混乱等问题。关键改进包括：

采用强类型 DTO 替代动态属性，提高了代码的可维护性和可靠性
实现了传输层抽象和协议层分离，提升了架构的清晰性
增强了日志记录功能，便于排查通信问题
引入了流式传输支持，简化了流式处理的实现

这些改进为 HagiCode 提供了更稳定、更高效的通信基础，使其能够更好地与外部 AI 工具进行交互，并为未来的功能扩展奠定了坚实的基础。

参考资料

StreamJsonRpc 官方文档：https://learn.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.threading.streamjsonrpc
ACP (Agent Communication Protocol) 规范：https://github.com/microsoft/agentcommunicationprotocol
HagiCode 项目：https://github.com/HagiCode-org/site
Orleans 官方文档：https://learn.microsoft.com/en-us/dotnet/orleans

如果本文对你有帮助：

点个赞让更多人看到
来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：hagicode.com/installation/docker-compose
公测已开始，欢迎安装体验

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026/01/28/streamjsonrpc-integration-in-hagicode
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

利用 Worker Threads 优化 Vite 构建性能的实战

2026年1月28日

120秒到45秒：利用 Worker Threads 优化 Vite 构建性能的实战

在处理大型前端项目时，生产环境的代码构建往往让人望眼欲穿。本文分享如何通过 Node.js Worker Threads 将 Vite 构建中的代码混淆环节耗时从 120 秒降低至 45 秒，并详细介绍 HagiCode 项目中的实施细节与踩坑经验。

背景

在我们的前端工程化实践中，随着项目规模的扩大，构建效率问题逐渐凸显。特别是在生产环境构建流程中，为了保护源码逻辑，我们通常会引入 JavaScript 混淆工具（如 javascript-obfuscator）。这一步虽然必要，但计算量巨大，极其消耗 CPU 资源。

在HagiCode项目的早期开发阶段，我们遇到了一个非常棘手的性能瓶颈：生产构建时间随着代码量的增加迅速恶化。

具体痛点如下：

单线程串行执行混淆任务，CPU 单核跑满，其他核心闲置
构建时间从最初的 30 秒飙升至 110-120 秒
每次修改代码后的构建验证流程极其漫长，严重拖慢了开发迭代效率
CI/CD 流水线中，构建环节成为最耗时的部分

为什么 HagiCode 会有这个需求？ HagiCode 是一款 AI 驱动的代码智能助手，其前端架构包含复杂的业务逻辑和 AI 交互模块。为了确保核心代码的安全性，我们在生产发布时强制开启了高强度混淆。面对长达两分钟的构建等待，我们决定对构建系统进行一次深度的性能优化。

关于 HagiCode

既然提到了这个项目，不妨多介绍两句。

如果你在开发中遇到过这些烦恼：

多项目、多技术栈，构建脚本维护成本高
CI/CD 流水线配置繁琐，每次改都要查文档
跨平台兼容性问题层出不穷
想让 AI 帮忙写代码，但现有工具不够智能

那么我们正在做的 HagiCode 可能你会感兴趣。

HagiCode 是什么？

一款 AI 驱动的代码智能助手
支持多语言、跨平台的代码生成与优化
内置游戏化机制，让编码不再枯燥

为什么在这里提它？ 本文分享的 JavaScript 并行混淆方案，正是我们在开发 HagiCode 过程中实践总结出来的。如果你觉得这套工程化方案有价值，说明我们的技术品味还不错——那么 HagiCode 本身也值得关注一下。

想了解更多？

GitHub: github.com/HagiCode-org/site（求 Star）
官网: hagicode.com
视频演示: www.bilibili.com/video/BV1pirZBuEzq/（30 分钟实战演示）
安装指南: hagicode.com/installation/docker-compose
公测已开始：现在安装即可参与公测

分析：寻找性能瓶颈的突破口

在着手解决性能问题之前，我们需要先理清思路，确定最优的技术方案。

核心决策：为什么选择 Worker Threads？

Node.js 环境下实现并行计算主要有三种方案：

child_process：创建独立的子进程
Web Workers：主要用于浏览器端
worker_threads：Node.js 原生多线程支持

经过对比分析，HagiCode 最终选择了 Worker Threads，原因如下：

零序列化开销：Worker Threads 位于同一进程，可以通过 SharedArrayBuffer 或转移控制权的方式共享内存，避免了进程间通信的大额序列化成本。
原生支持：Node.js 12+ 版本内置支持，无需引入额外的重依赖。
上下文统一：调试和日志记录比子进程更方便。

任务粒度：如何拆分混淆任务？

混淆一个巨大的 JS Bundle 文件很难并行（因为代码有依赖关系），但 Vite 的构建产物是由多个 Chunk 组成的。这给了我们一个天然的并行边界：

独立性：Vite 打包后的不同 Chunk 之间依赖关系已解耦，可以安全地并行处理。
粒度适中：通常项目会有 10-30 个 Chunk，这个数量级非常适合并行调度。
易于集成：Vite 插件的 generateBundle 钩子允许我们在文件生成前拦截并处理这些 Chunk。

架构设计

我们设计了一个包含四个核心组件的并行处理系统：

Task Splitter：遍历 Vite 的 bundle 对象，过滤不需要混淆的文件（如 vendor），生成任务队列。
Worker Pool Manager：管理 Worker 的生命周期，负责任务的分发、回收和错误重试。
Progress Reporter：实时输出构建进度，消除用户的等待焦虑。
ObfuscationWorker：实际执行混淆逻辑的工作线程。

解决：实战编码与实施

基于上述分析，我们开始动手实现这套并行混淆系统。

1. 配置 Vite 插件

首先，我们在 vite.config.ts 中集成并行混淆插件。配置非常直观，只需指定 Worker 数量和混淆规则。

import { defineConfig } from 'vite'
import { parallelJavascriptObfuscator } from './buildTools/plugin'

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production'

  return {
    build: {
      rollupOptions: {
        ...(isProduction
          ? {
              plugins: [
                parallelJavascriptObfuscator({
                  enabled: true,
                  // 根据 CPU 核心数自动调整，建议留出一个核心给主线程
                  workerCount: 4,
                  retryAttempts: 3,
                  fallbackToMainThread: true, // 出错时自动降级为单线程
                  // 过滤掉 vendor chunk，通常不需要混淆第三方库
                  isVendorChunk: (fileName: string) => fileName.includes('vendor-'),
                  obfuscationConfig: {
                    compact: true,
                    controlFlowFlattening: true,
                    deadCodeInjection: true,
                    disableConsoleOutput: true,
                    // ... 更多混淆选项
                  },
                }),
              ],
            }
          : {}),
      },
    },
  }
})

2. 实现 Worker 逻辑

Worker 是执行任务的单元。我们需要定义好输入和输出的数据结构。

注意：这里的代码虽然简单，但有几个坑点需要注意。比如 parentPort 的空值检查，以及错误处理。在 HagiCode 的实践中，我们发现有些特殊的 ES6 语法可能会导致混淆器崩溃，所以加上了 try-catch 保护。

import { parentPort } from 'worker_threads'
import javascriptObfuscator from 'javascript-obfuscator'

export interface ObfuscationTask {
  chunkId: string
  code: string
  config: any
}

export interface ObfuscationResult {
  chunkId: string
  obfuscatedCode: string
  error?: string
}

// 监听主线程发来的任务
if (parentPort) {
  parentPort.on('message', async (task: ObfuscationTask) => {
    try {
      // 执行混淆
      const obfuscated = javascriptObfuscator.obfuscate(task.code, task.config)
      const result: ObfuscationResult = {
        chunkId: task.chunkId,
        obfuscatedCode: obfuscated.getObfuscatedCode(),
      }
      // 将结果发回主线程
      parentPort?.postMessage(result)
    } catch (error) {
      // 处理异常，确保单个 Worker 崩溃不会阻塞整个构建
      const result: ObfuscationResult = {
        chunkId: task.chunkId,
        obfuscatedCode: '',
        error: error instanceof Error ? error.message : 'Unknown error',
      }
      parentPort?.postMessage(result)
    }
  })
}

3. Worker 池管理器

这是整个方案的核心。我们需要维护一个固定大小的 Worker 池，采用 FIFO（先进先出） 策略调度任务。

import { Worker } from 'worker_threads'
import os from 'os'

export class WorkerPool {
  private workers: Worker[] = []
  private taskQueue: Array<{
    task: ObfuscationTask
    resolve: (result: ObfuscationResult) => void
    reject: (error: Error) => void
  }> = []

  constructor(options: WorkerPoolOptions = {}) {
    // 默认为核心数 - 1，给主线程留一点喘息的空间
    const workerCount = options.workerCount ?? Math.max(1, (os.cpus().length || 4) - 1)

    for (let i = 0; i < workerCount; i++) {
      this.createWorker()
    }
  }

  private createWorker() {
    const worker = new Worker('./worker.ts')

    worker.on('message', (result) => {
      // 任务完成后，从队列中取出下一个任务
      const nextTask = this.taskQueue.shift()
      if (nextTask) {
        this.dispatchTask(worker, nextTask)
      } else {
        // 如果没有待处理任务，标记 Worker 为空闲
        this.activeWorkers.delete(worker)
      }
    })

    this.workers.push(worker)
  }

  // 提交任务到池中
  public runTask(task: ObfuscationTask): Promise<ObfuscationResult> {
    return new Promise((resolve, reject) => {
      const job = { task, resolve, reject }
      const idleWorker = this.workers.find(w => !this.activeWorkers.has(w))

      if (idleWorker) {
        this.dispatchTask(idleWorker, job)
      } else {
        this.taskQueue.push(job)
      }
    })
  }

  private dispatchTask(worker: Worker, job: any) {
    this.activeWorkers.set(worker, job.task)
    worker.postMessage(job.task)
  }
}

4. 进度报告

等待是痛苦的，尤其是不知道还要等多久。我们增加了一个简单的进度报告器，实时反馈当前状态。

export class ProgressReporter {
  private completed = 0
  private readonly total: number
  private readonly startTime: number

  constructor(total: number) {
    this.total = total
    this.startTime = Date.now()
  }

  increment(): void {
    this.completed++
    this.report()
  }

  private report(): void {
    const now = Date.now()
    const elapsed = now - this.startTime
    const percentage = (this.completed / this.total) * 100

    // 简单的 ETA 估算
    const avgTimePerChunk = elapsed / this.completed
    const remaining = (this.total - this.completed) * avgTimePerChunk

    console.log(
      `[Parallel Obfuscation] ${this.completed}/${this.total} chunks completed (${percentage.toFixed(1)}%) | ETA: ${(remaining / 1000).toFixed(1)}s`
    )
  }
}

实践：效果与踩坑

部署这套方案后，HagiCode 项目的构建性能有了立竿见影的提升。

性能基准数据

我们在以下环境进行了测试：

CPU：Intel Core i7-12700K (12 cores / 20 threads)
RAM：32GB DDR4
Node.js：v18.17.0
OS：Ubuntu 22.04

结果对比：

单线程（优化前）：118 秒
4 Workers：55 秒（提升 53%）
8 Workers：48 秒（提升 60%）
12 Workers：45 秒（提升 62%）

可以看出，收益并不是线性的。当 Worker 数量超过 8 个后，提升幅度变小。这主要受限于任务分配的均匀度和内存带宽瓶颈。

常见问题与解决方案

在 HagiCode 的实际使用中，我们也遇到了一些坑，这里分享给大家：

Q1: 构建时间没有明显减少，反而变慢了？

原因：Worker 创建本身有开销，或者 Worker 数量设置过多导致上下文切换频繁。
解决：建议 Worker 数量设置为 CPU 核心数 - 1。同时检查是否有单个 Chunk 特别大（例如 > 5MB），这种”巨无霸”文件会成为短板，可以考虑优化代码分割策略。

Q2: 偶尔出现 Worker 崩溃，构建失败？

原因：某些特殊的代码语法可能导致混淆器内部报错。
解决：我们实现了 自动降级机制。当 Worker 连续失败次数达到阈值时，插件会自动回退到单线程模式，确保构建不中断。同时记录下错误的文件名，方便后续针对性修复。

Q3: 内存占用过高（OOM）？

原因：每个 Worker 都需要独立内存空间来加载混淆器和解析 AST。
解决：
- 减少 Worker 数量。
- 增加 Node.js 的内存限制：NODE_OPTIONS="--max-old-space-size=4096" npm run build。
- 确保不在 Worker 内部持有不必要的大对象引用。

总结

通过引入 Node.js Worker Threads，我们成功将 HagiCode 项目的生产构建时间从 120 秒降低到了 45 秒左右，极大提升了开发体验和 CI/CD 效率。

这套方案的核心在于：

合理拆分任务：利用 Vite 的 Chunk 作为并行单元。
资源控制：使用 Worker 池避免资源耗尽。
容错设计：自动降级机制确保构建稳定性。

如果你也在为前端构建效率发愁，或者你的项目也在做重度代码处理，不妨试试这套方案。当然，更推荐你直接关注我们的 HagiCode 项目，这些工程化的细节都已经集成在里面了。

如果本文对你有帮助，欢迎来 GitHub 给个 Star，或者参与公测体验一下～

参考资料

Node.js Worker Threads 官方文档: nodejs.org/api/worker_threads.html
javascript-obfuscator 文档: github.com/javascript-obfuscator/javascript-obfuscator
Vite 插件开发指南: vitejs.dev/guide/api-plugin.html
HagiCode GitHub: github.com/HagiCode-org/site
HagiCode 官网: hagicode.com
安装指南: hagicode.com/installation/docker-compose

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026/01/27/optimizing-vite-build-with-worker-threads
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

HagiCode 实践:如何利用 GitHub Actions 实现 Docusaurus 自动部署

2026年1月26日

为 HagiCode 添加 GitHub Pages 自动部署支持

本项目早期代号为 PCode，现已正式更名为 HagiCode。本文记录了如何为项目引入自动化静态站点部署能力，让内容发布像喝水一样简单。

背景/引言

在 HagiCode 的开发过程中，我们遇到了一个很现实的问题：随着文档和提案越来越多，如何高效地管理和展示这些内容成了当务之急。我们决定引入 GitHub Pages 来托管我们的静态站点，但是手动构建和部署实在是太麻烦了——每次改动都要本地构建、打包，然后手动推送到 gh-pages 分支。这不仅效率低下，还容易出错。

为了解决这个问题（主要是为了偷懒），我们需要一套自动化的部署流程。本文将详细记录如何为 HagiCode 项目添加 GitHub Actions 自动部署支持，让我们只需专注于内容创作，剩下的交给自动化流程。

关于 HagiCode

嘿，介绍一下我们正在做的东西

我们正在开发 HagiCode——一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能——AI 全程辅助，从想法到代码，让编码效率提升数倍。便捷——多线程并发操作，充分利用资源，开发流程顺畅无阻。有趣——游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看～

目标分析

在动手之前，我们得先明确这次任务到底要干啥。毕竟（这里打错了，应该是毕竟）磨刀不误砍柴工嘛。

核心需求

自动化构建：当代码推送到 main 分支时，自动触发构建流程。
自动部署：构建成功后，自动将生成的静态文件部署到 GitHub Pages。
环境一致性：确保 CI 环境和本地构建环境一致，避免”本地能跑，线上报错”的尴尬。

技术选型

考虑到 HagiCode 是基于 Docusaurus 构建的（一种非常流行的 React 静态站点生成器），我们可以利用 GitHub Actions 来实现这一目标。

配置 GitHub Actions 工作流

GitHub Actions 是 GitHub 提供的 CI/CD 服务。通过在代码仓库中定义 YAML 格式的工作流文件，我们可以定制各种自动化任务。

创建工作流文件

我们需要在项目根目录下的 .github/workflows 文件夹中创建一个新的配置文件，比如叫 deploy.yml。如果文件夹不存在，记得先手动创建一下。

这个配置文件的核心逻辑如下：

触发条件：监听 main 分支的 push 事件。
运行环境：最新版的 Ubuntu。
构建步骤：
- 检出代码
- 安装 Node.js
- 安装依赖 (npm install)
- 构建静态文件 (npm run build)
部署步骤：使用官方提供的 action-gh-pages 将构建产物推送到 gh-pages 分支。

关键配置代码

以下是我们最终采用的配置模板：

name: Deploy to GitHub Pages

# 触发条件：当推送到 main 分支时
on:
  push:
    branches:
      - main
    # 可以根据需要添加路径过滤，比如只有文档变动才构建
    # paths:
    #   - 'docs/**'
    #   - 'package.json'

# 设置权限，这对于部署到 GitHub Pages 很重要
permissions:
  contents: read
  pages: write
  id-token: write

# 并发控制：取消同一分支的旧构建
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        # 注意：必须设置 fetch-depth: 0，否则可能导致构建版本号不准确
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 建议与本地开发环境保持一致
          cache: 'npm'     # 启用缓存可以加速构建过程

      - name: Install dependencies
        run: npm ci
        # 使用 npm ci 而不是 npm install，因为它更快、更严格，适合 CI 环境

      - name: Build website
        run: npm run build
        env:
          # 如果你的站点构建需要环境变量，在这里配置
          # NODE_ENV: production
          # PUBLIC_URL: /your-repo-name

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./build # Docusaurus 默认输出目录

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

实施过程中的坑点

在实际操作中，我们遇到了一些问题，这里分享出来希望大家能避开（或者提前准备好解决方案）。

1. GitHub Token 权限问题

最开始配置的时候，部署总是报错 403 (Forbidden)。查了好久才发现，是因为 GitHub 默认的 GITHUB_TOKEN 并没有写入 Pages 的权限。

解决方案：在仓库的 Settings -> Actions -> General -> Workflow permissions 中，务必选择 “Read and write permissions”。

2. 构建目录路径错误

Docusaurus 默认把构建好的静态文件放在 build 目录。但是有些项目（比如 Create React App 默认是 build，Vite 默认是 dist）可能配置不一样。如果在 Actions 中报错找不到文件，记得去 docusaurus.config.js 里检查一下输出路径配置。

3. 子路径问题

如果你的仓库不是用户主页（即不是 username.github.io），而是项目主页（比如 username.github.io/project-name），你需要配置 baseUrl。

在 docusaurus.config.js 中：

module.exports = {
  // ...
  url: 'https://hagicode.com', // 你的 Hagicode URL
  baseUrl: '/', // 根路径部署
  // ...
};

这一点很容易被忽略，配置不对会导致页面打开全是白屏，因为资源路径加载不到。

验证成果

配置完所有东西并推送代码后，我们就可以去 GitHub 仓库的 Actions 标签页看戏了。

你会看到黄色的圆圈（工作流正在运行），变绿就代表成功啦！如果变红了，点击进去查看日志，通常都能排查出问题（大部分时候是拼写错误或者路径配置不对）。

构建成功后，访问 https://<你的用户名>.github.io/<仓库名>/ 就能看到崭新的站点了。

总结

通过引入 GitHub Actions，我们成功实现了 HagiCode 文档站的自动化部署。这不仅节省了手动操作的时间，更重要的是保证了发布流程的标准化。现在不管是哪位小伙伴更新了文档，只要合并到 main 分支，几分钟后就能在线上看到最新的内容。

核心收益：

效率提升：从”手动打包、手动上传”变成”代码即发布”。
降低错误：消除了人为操作失误的可能性。
体验优化：让开发者更专注于内容质量，而不是被繁琐的部署流程困扰。

虽然配置 CI/CD 刚开始有点麻烦（尤其是各种权限和路径问题），但这是一次性投入，长期回报巨大的工作。强烈建议所有静态站点项目都接入类似的自动化流程。

参考资料

GitHub Actions 官方文档
Docusaurus 部署指南
[actions-gh-pages Action 使用说明](https://github.com peaceiris/actions-gh-pages)

互动引导

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

AI 辅助声明

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

元信息

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026/01/25/docusaurus-auto-deployment-with-github-actions
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

基于 C# 和 Nuke 打造现代化构建系统的最佳实践

2026年1月26日

告别脚本地狱：为什么我们选择用 C# 打造现代化构建系统

揭秘 HagiCode 项目如何利用 Nuke 实现类型安全、跨平台且高度可扩展的自动化构建流程，彻底解决传统构建脚本的维护痛点。

背景

在软件开发的漫长旅途中，“构建”这个词往往让人又爱又恨。爱的是，一键点击，代码变成产品，那是程序员最迷人的时刻；恨的是，维护那一堆乱糟糟的构建脚本，简直是噩梦。

在很多项目中，我们习惯了用 Python 写脚本，或者用 XML 配置文件（想象一下那段被 <property> 支配的恐惧）。但随着项目复杂度的提升，尤其是像 HagiCode 这样涉及前后端、多平台、多语言混合开发的项目，传统的构建方式开始显得力不从心。脚本逻辑分散、缺乏类型检查、IDE 支持弱……这些问题像一个个小坑，时不时就让开发团队绊个跟头。

为了解决这些痛点，在 HagiCode 项目中，我们决定引入 Nuke —— 一个基于 C# 的现代化构建系统。它不仅仅是一个工具，更像是一种对构建流程的重新思考。今天，我们就来聊聊为什么选择它，以及它是如何让我们的开发体验”起飞”的。

关于 HagiCode

嘿，介绍一下我们正在做的东西

我们正在开发 HagiCode —— 一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能 —— AI 全程辅助，从想法到代码，让编码效率提升数倍。便捷 —— 多线程并发操作，充分利用资源，开发流程顺畅无阻。有趣 —— 游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看～

核心剖析：为什么是 Nuke？

你可能心里会犯嘀咕：“哎呀，构建系统那么多，比如 Make、Gradle，甚至直接用 Shell 脚本不行吗？为啥非得整一个 C# 的？”

这其实是个好问题。Nuke 的核心魅力在于它把我们最熟悉的编程语言特性带进了构建脚本的世界。

1. 将构建流程模块化：Target 的艺术

Nuke 的设计理念非常清晰：一切皆为目标。

在传统的脚本里，我们可能会写出几百行线性执行的代码，逻辑错综复杂。而在 Nuke 中，我们将构建流程分解为独立的 Target（目标）。每个目标只负责一件事，比如：

Clean: 清理输出目录
Restore: 还原依赖包
Compile: 编译代码
Test: 运行单元测试

这种设计非常符合单一职责原则。就像搭积木一样，我们可以随意组合这些 Target。更重要的是，Nuke 允许我们定义 Target 之间的依赖关系。比如，你想要 Test，那系统会自动检查你是否先执行了 Compile；想要 Compile，自然得先 Restore。

这种依赖关系图不仅让逻辑更清晰，还极大地提高了执行效率，Nuke 会自动分析最优执行路径。

2. 类型安全：告别拼写错误的噩梦

用过 Python 写构建脚本的朋友肯定遇到过这种尴尬：脚本跑了五分钟，最后报错说 Confi.guration 拼写错了，或者传了一个字符串给了一个本该是数字的参数。

使用 C# 编写构建脚本最大的优势就是 类型安全。这意味着：

编译时检查：你在敲代码的时候，IDE 就会告诉你哪里错了，不用等到运行时才发现。
重构无忧：如果你想改个变量名或者方法名，IDE 的重构功能一键搞定，不用全局搜索替换提心吊胆。
智能提示：强大的 IntelliSense 会自动补全代码，你不需要去翻文档记那些生僻的 API。

3. 跨平台：统一的构建体验

以前在 Windows 上写 .bat，在 Linux 上写 .sh，为了兼容两者，还得写个 Python 脚本。现在，只要是 .NET Core（现 .NET 5+）能跑的地方，Nuke 就能跑。

这意味着无论团队成员是使用 Windows、Linux 还是 macOS，无论是用 Visual Studio、VS Code 还是 Rider，大家执行的都是同一套逻辑。这就极大地消除了”在我机器上能跑”这类环境差异导致的问题。

4. 参数与配置管理

Nuke 提供了一套非常优雅的参数解析机制。你不需要手动去解析 string[] args，只需要定义一个属性，加上 [Parameter] 特性，Nuke 就会自动处理命令行参数和配置文件的映射。

比如，我们可以轻松定义构建配置：

[Parameter("Configuration to build - Default is 'Debug'")]
readonly Configuration BuildConfiguration = IsLocalBuild ? Configuration.Debug : Configuration.Release;

Target Compile => _ => _
    .DependsOn(Restore)
    .Executes(() =>
    {
        // 在这里使用 BuildConfiguration，它是类型安全的
        DotNetBuild(s => s
            .SetConfiguration(BuildConfiguration)
            .SetProjectFile(SolutionFile));
    });

这种写法既直观又不容易出错。

实践指南：如何在项目中落地

空谈误国，实干兴邦。让我们看看在 HagiCode 项目中，具体是怎么落地这套方案的。

1. 规划项目结构

我们不想让构建脚本污染项目根目录，也不想搞得像某些 Java 项目那样目录结构深不见底。所以，我们将所有与 Nuke 相关的构建文件统一放置在 nukeBuild/ 文件夹中。

这样做的好处是：

项目根目录保持清爽。
构建逻辑内聚，方便管理。
新成员加入时，一眼就能看到”哦，这是构建相关的逻辑”。

2. 设计清晰的 Target 依赖链

在设计 Target 时，我们遵循了一个原则：原子化 + 依赖流。

每个 Target 应该足够小，只做一件事。比如 Clean 就只管删文件，不要在里面顺便做打包。

推荐的依赖流大概是这个样子的：

Clean -> Restore -> Compile -> Test -> Pack

当然，这不是绝对的。比如如果你只想跑个测试，不想打包，Nuke 允许你直接执行 nuke Test，它会自动处理好前置的 Restore 和 Compile 步骤。

3. 完善的错误处理与日志

构建脚本最怕的是什么？是报错信息不明确。比如构建失败了，日志只显示 “Error: 1”，这就让人很抓狂。

在 Nuke 中，由于我们可以直接使用 C# 的异常处理机制，因此可以非常精确地捕获和报告错误。

Target Publish => _ => _
    .DependsOn(Test)
    .Executes(() =>
    {
        try
        {
            // 尝试发布到 NuGet
            DotNetNuGetPush(s => s
                .SetTargetPath(ArtifactPath)
                .SetSource("https://api.nuget.org/v3/index.json")
                .SetApiKey(ApiKey));
        }
        catch (Exception ex)
        {
            Log.Error($"发布失败了，兄弟们检查一下 Key 对不对: {ex.Message}");
            throw; // 确保构建进程以非零退出码结束
        }
    });

4. 集成测试保障质量

构建脚本本身也是代码，也需要测试。Nuke 允许我们为构建流程编写测试，确保当我们修改了构建逻辑后，不会破坏现有的发布流程。这在持续集成（CI）流水线中尤为重要。

总结

通过引入 Nuke，HagiCode 的构建流程变得前所未有的顺畅。它不仅仅是一个工具的替换，更是工程化思维的提升。

我们收获了什么？

可维护性：代码即配置，逻辑清晰，新人也能快速上手。
稳定性：强类型检查减少了 90% 以上的低级错误。
一致性：跨平台的统一体验，消除了环境差异。

如果说以前写构建脚本是”在黑暗中摸索”，那么使用 Nuke 就像是”开着灯走夜路”。如果你受够了维护那些难以调试的脚本语言，不妨试试把构建逻辑也搬到 C# 的世界里来，也许你会发现，原来构建也可以这么优雅。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026/01/26/modern-build-system-with-csharp-and-nuke
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

如何使用 GitHub Actions + image-syncer 实现 Docker Hub 到 Azure ACR 的自动化镜像同步

2026年1月25日

实现 Docker Hub 到 Azure ACR 的自动化镜像同步

本文介绍了如何使用 GitHub Actions 和 image-syncer 工具，实现 Docker Hub 镜像到 Azure Container Registry 的自动化同步，解决了国内及部分 Azure 区域访问 Docker Hub 速度慢的问题，提升了镜像的可用性和 Azure 环境的部署效率。

背景/引言

HagiCode 项目使用 Docker 镜像作为核心运行时组件，主要镜像托管在 Docker Hub。随着项目发展和 Azure 环境部署需求的增加，我们遇到了以下痛点：

镜像拉取速度慢，Docker Hub 在国内及部分 Azure 区域访问受限
依赖单一镜像源存在单点故障风险
Azure 环境下使用 Azure Container Registry 能获得更好的网络性能和集成体验

为解决这些问题，我们需要建立一个自动化的镜像同步机制，将 Docker Hub 的镜像定期同步到 Azure ACR，确保用户能够在 Azure 环境中获得更快的镜像拉取速度和更高的可用性。

关于 HagiCode

我们正在开发 HagiCode——一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看。

技术方案对比

在制定解决方案时，我们对比了多种技术方案：

1. image-syncer（最终选择）

增量同步：仅同步变更的镜像层，显著减少网络传输
断点续传：网络中断后可恢复同步
并发控制：支持配置并发线程数，提升大镜像同步效率
完善的错误处理：内置失败重试机制（默认 3 次）
轻量级部署：单二进制文件，无依赖
多仓库支持：兼容 Docker Hub、Azure ACR、Harbor 等

2. Docker CLI

不支持增量同步：每次都需要拉取完整的镜像内容
效率较低：网络传输量大，时间长
简单易用：使用熟悉的 docker pull/push 命令

3. Azure CLI

复杂度高：需要配置 Azure CLI 认证
功能限制：az acr import 功能相对单一
原生集成：与 Azure 服务集成良好

架构设计决策

决策 1：同步频率设置为每日 UTC 00:00

平衡镜像新鲜度和资源消耗
避开业务高峰期，减少对其他操作的影响
Docker Hub 镜像通常在每日构建后更新

决策 2：同步所有镜像标签

保持与 Docker Hub 的完全一致性
为用户提供灵活的版本选择
简化同步逻辑，避免复杂的标签过滤规则

决策 3：使用 GitHub Secrets 存储认证信息

GitHub Actions 原生支持，安全性高
配置简单，易于管理和维护
支持仓库级别的访问控制

风险评估与缓解

风险 1：Azure ACR 认证信息泄露

使用 GitHub Secrets 加密存储
定期轮换 ACR 密码
限制 ACR 用户权限为仅推送
监控 ACR 访问日志

风险 2：同步失败导致镜像不一致

image-syncer 内置增量同步机制
自动失败重试（默认 3 次）
详细的错误日志和失败通知
断点续传功能

风险 3：资源消耗过大

增量同步减少网络传输
可配置并发线程数（当前设置为 10）
监控同步的镜像数量和大小
在非高峰时段运行同步

核心解决方案

我们采用 GitHub Actions + image-syncer 的自动化方案，实现从 Docker Hub 到 Azure ACR 的镜像同步。

实施步骤

1. 准备阶段

在 Azure Portal 中创建或确认 Azure Container Registry
创建 ACR 访问密钥（用户名和密码）
确认 Docker Hub 镜像仓库访问权限

2. 配置 GitHub Secrets

在 GitHub 仓库设置中添加以下 Secrets：

AZURE_ACR_USERNAME: Azure ACR 用户名
AZURE_ACR_PASSWORD: Azure ACR 密码

3. 创建 GitHub Actions 工作流

在 .github/workflows/sync-docker-acr.yml 中配置工作流：

定时触发：每天 UTC 00:00
手动触发：支持 workflow_dispatch
额外触发：publish 分支推送时触发（用于快速同步）

4. 工作流执行流程

GitHub Actions 工作流实现

以下是实际运行的工作流配置（.github/workflows/sync-docker-acr.yml）：

name: Sync Docker Image to Azure ACR

on:
  schedule:
    - cron: "0 0 * * *" # 每天 UTC 00:00
  workflow_dispatch: # 手动触发
  push:
    branches: [publish]

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Download image-syncer
        run: |
          # 下载 image-syncer 二进制文件
          wget https://github.com/AliyunContainerService/image-syncer/releases/download/v1.5.5/image-syncer-v1.5.5-linux-amd64.tar.gz
          tar -zxvf image-syncer-v1.5.5-linux-amd64.tar.gz
          chmod +x image-syncer

      - name: Create auth config
        run: |
          # 生成认证配置文件 (YAML 格式)
          cat > auth.yaml <<EOF
          hagicode.azurecr.io:
            username: "${{ secrets.AZURE_ACR_USERNAME }}"
            password: "${{ secrets.AZURE_ACR_PASSWORD }}"
          EOF

      - name: Create images config
        run: |
          # 生成镜像同步配置文件 (YAML 格式)
          cat > images.yaml <<EOF
          docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode
          EOF

      - name: Run image-syncer
        run: |
          # 执行同步 (使用新版 --auth 和 --images 参数)
          ./image-syncer --auth=./auth.yaml --images=./images.yaml --proc=10 --retries=3

      - name: Upload logs
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: sync-logs
          path: image-syncer-*.log
          retention-days: 7

配置说明

1. 触发条件

定时触发：cron: “0 0 * * *” - 每天 UTC 00:00 执行
手动触发：workflow_dispatch - 允许用户在 GitHub UI 手动运行
推送触发：push: branches: [publish] - 发布分支推送时触发（用于快速同步）

2. 认证配置 (auth.yaml)

hagicode.azurecr.io:
  username: "${{ secrets.AZURE_ACR_USERNAME }}"
  password: "${{ secrets.AZURE_ACR_PASSWORD }}"

3. 镜像同步配置

docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode

此配置表示将 docker.io/newbe36524/hagicode 的所有标签同步到 hagicode.azurecr.io/hagicode

4. image-syncer 参数

—auth=./auth.yaml: 认证配置文件路径
—images=./images.yaml: 镜像同步配置文件路径
—proc=10: 并发线程数为 10
—retries=3: 失败重试 3 次

GitHub Secrets 配置清单

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置：

Secret 名称	描述	示例值	获取方式
AZURE_ACR_USERNAME	Azure ACR 用户名	hagicode	Azure Portal → ACR → Access keys
AZURE_ACR_PASSWORD	Azure ACR 密码	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Azure Portal → ACR → Access keys → Password

使用说明

1. 手动触发同步

访问 GitHub 仓库的 Actions 标签页
选择 Sync Docker Image to Azure ACR 工作流
点击 Run workflow 按钮
选择分支并点击 Run workflow 确认

2. 查看同步日志

在 Actions 页面点击具体的工作流运行记录
查看各个步骤的执行日志
在页面底部的 Artifacts 区域下载 sync-logs 文件

3. 验证同步结果

# 登录到 Azure ACR
az acr login --name hagicode

# 列出镜像及其标签
az acr repository show-tags --name hagicode --repository hagicode --output table

注意事项和最佳实践

1. 安全建议

定期轮换 Azure ACR 密码（建议每 90 天）
使用专用的 ACR 服务账户，限制权限为仅推送
监控 ACR 的访问日志，及时发现异常访问
不要在日志中输出认证信息
不要将认证信息提交到代码仓库

2. 性能优化

调整 —proc 参数：根据网络带宽调整并发数（建议 5-20）
监控同步时间：如果同步时间过长，考虑减少并发数
定期清理日志：设置合理的 retention-days（当前为 7 天）

3. 故障排查

问题 1：认证失败

Error: failed to authenticate to hagicode.azurecr.io

解决方案：

检查 GitHub Secrets 是否正确配置
验证 Azure ACR 密码是否过期
确认 ACR 服务账户权限是否正确

问题 2：网络超时

Error: timeout waiting for response

解决方案：

检查网络连接
减少并发线程数（—proc 参数）
等待网络恢复后重新触发工作流

问题 3：镜像同步不完整

Warning: some tags failed to sync

解决方案：

检查同步日志，识别失败的标签
手动触发工作流重新同步
验证 Docker Hub 源镜像是否正常

4. 监控和告警

定期检查 Actions 页面，确认工作流运行状态
设置 GitHub 通知，及时获取工作流失败通知
监控 Azure ACR 的存储使用情况
定期验证镜像标签一致性

常见问题和解决方案

Q1: 如何同步特定标签而不是所有标签？

修改 images.yaml 配置文件：

# 仅同步 latest 和 v1.0 标签
docker.io/newbe36524/hagicode:latest: hagicode.azurecr.io/hagicode:latest
docker.io/newbe36524/hagicode:v1.0: hagicode.azurecr.io/hagicode:v1.0

Q2: 如何同步多个镜像仓库？

在 images.yaml 中添加多行配置：

docker.io/newbe36524/hagicode: hagicode.azurecr.io/hagicode
docker.io/newbe36524/another-image: hagicode.azurecr.io/another-image

Q3: 同步失败后如何重试？

自动重试：image-syncer 内置重试机制（默认 3 次）
手动重试：在 GitHub Actions 页面点击 Re-run all jobs

Q4: 如何查看同步的详细进度？

在 Actions 页面查看实时日志
下载 sync-logs artifact 查看完整日志文件
日志文件包含每个标签的同步状态和传输速度

Q5: 同步需要多长时间？

首次全量同步：根据镜像大小，通常需要 10-30 分钟
增量同步：如果镜像变更小，通常 2-5 分钟
时间取决于网络带宽、镜像大小和并发设置

扩展功能建议

1. 添加同步通知

在工作流中添加通知步骤：

- name: Notify on success
  if: success()
  run: |
    echo "Docker images synced successfully to Azure ACR"

2. 实现镜像标签过滤

在工作流中添加标签过滤逻辑：

- name: Filter tags
  run: |
    # 仅同步以 v 开头的标签
    echo "docker.io/newbe36524/hagicode:v* : hagicode.azurecr.io/hagicode:v*" > images.yaml

3. 添加同步统计报告

- name: Generate report
  if: always()
  run: |
    echo "## Sync Report" >> $GITHUB_STEP_SUMMARY
    echo "- Total tags: $(grep -c 'synced' image-syncer-*.log)" >> $GITHUB_STEP_SUMMARY
    echo "- Sync time: ${{ steps.sync.outputs.duration }}" >> $GITHUB_STEP_SUMMARY

总结

通过本文介绍的方法，我们成功实现了从 Docker Hub 到 Azure ACR 的自动化镜像同步。这个方案利用 GitHub Actions 的定时触发和手动触发功能，结合 image-syncer 的增量同步和错误处理机制，确保了镜像的及时同步和一致性。

我们还讨论了安全最佳实践、性能优化、故障排查等方面的内容，帮助用户更好地管理和维护这个同步机制。希望本文能够为需要在 Azure 环境中部署 Docker 镜像的开发者提供有价值的参考。

参考资料

互动引导

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

AI 辅助声明

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

元信息

本文作者: newbe36524
本文链接: https://hagicode.com/blog/2026/01/25/how-to-sync-docker-hub-to-azure-acr-with-github
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

GitHub Issues 集成

2026年1月22日

从零构建 GitHub Issues 集成：HagiCode 的前端直连实践

本文记录了在 HagiCode 平台中集成 GitHub Issues 的全过程。我们将探讨如何通过”前端直连 + 后端最小化”的架构，在保持后端轻量的同时，实现安全的 OAuth 认证与高效的 Issues 同步。

背景：为什么要集成 GitHub？

HagiCode 作为一个 AI 辅助开发平台，核心价值在于连接想法与实现。但在实际使用中，我们发现用户在 HagiCode 中完成了 Proposal（提案）后，往往需要手动将内容复制到 GitHub Issues 中进行项目跟踪。

这带来了几个明显的痛点：

工作流割裂：用户需要在两个系统之间来回切换，体验不仅不流畅，还容易导致关键信息在复制粘贴的过程中丢失。
协作不便：团队其他成员习惯在 GitHub 上查看任务，无法直接看到 HagiCode 中的提案进展。
重复劳动：每当提案更新，就要人工去 GitHub 更新对应的 Issue，增加不必要的维护成本。

为了解决这个问题，我们决定引入 GitHub Issues Integration 功能，打通 HagiCode 会话与 GitHub 仓库的连接，实现”一键同步”。

关于 HagiCode

嘿，介绍一下我们正在做的东西

我们正在开发 HagiCode —— 一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能 —— AI 全程辅助，从想法到代码，让编码效率提升数倍。便捷 —— 多线程并发操作，充分利用资源，开发流程顺畅无阻。有趣 —— 游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来 GitHub 看看～

技术选型：前端直连 vs 后端代理

在设计集成方案时，摆在我们面前的有两条路：传统的”后端代理模式”和更激进的”前端直连模式”。

方案对比

在传统的后端代理模式中，前端所有的请求都要先经过我们的后端，再由后端去调用 GitHub API。这虽然逻辑集中，但给后端带来了不小的负担：

后端臃肿：需要编写专门的 GitHub API 客户端封装，还要处理 OAuth 的复杂状态机。
Token 风险：用户的 GitHub Token 必须存储在后端数据库中，虽然可以加密，但毕竟增加了安全风险面。
开发成本：需要数据库迁移来存储 Token，还需要维护一套额外的同步服务。

而前端直连模式则要轻量得多。在这个方案中，我们只利用后端来处理最敏感的”密钥交换”环节（OAuth callback），获取到 Token 后，直接存在浏览器的 localStorage 里。后续创建 Issue、更新评论等操作，直接由前端发 HTTP 请求到 GitHub。

对比维度	后端代理模式	前端直连模式
后端复杂度	需要完整的 OAuth 服务和 GitHub API 客户端	仅需一个 OAuth 回调端点
Token 管理	需加密存储在数据库，有泄露风险	存储在浏览器，仅用户自己可见
实施成本	需数据库迁移、多服务开发	主要是前端工作量
用户体验	逻辑统一，但服务器延迟可能稍高	响应极快，直接与 GitHub 交互

考虑到我们要的是快速集成和最小化后端改动，最终我们采用了”前端直连模式”。这就像给浏览器发了一张”临时通行证”，拿到证之后，浏览器就可以自己去 GitHub 办事了，不需要每次都找后端管理员批准。

核心设计：数据流与安全

在确定架构后，我们需要设计具体的数据流。整个同步流程的核心在于如何安全地获取 Token 并高效地利用它。

整体架构图

整个系统可以抽象为三个角色：浏览器（前端）、HagiCode 后端、GitHub。

+--------------+        +--------------+        +--------------+
|  前端 React  |        |    后端      |        |    GitHub    |
|              |        |   ASP.NET    |        |    REST API  |
|  +--------+  |        |              |        |              |
|  |  OAuth |--+--------> /callback    |        |              |
|  |  流程  |  |        |              |        |              |
|  +--------+  |        |              |        |              |
|              |        |              |        |              |
|  +--------+  |        |  +--------+  |        |  +--------+  |
|  |GitHub  |  +------------>Session |  +----------> Issues |  |
|  |API     |  |        |  |Metadata|  |        |  |        |  |
|  |直连    |  |        |  +--------+  |        |  +--------+  |
|  +--------+  |        |              |        |              |
+--------------+        +--------------+        +--------------+

关键点在于：只有 OAuth 的一小步（获取 code 换 token）需要经过后端，之后的粗活累活（创建 Issue）都是前端直接跟 GitHub 打交道。

同步数据流详解

当用户点击 HagiCode 界面上的”Sync to GitHub”按钮时，会发生一系列复杂的动作：

用户点击 "Sync to GitHub"
         │
         ▼
1. 前端检查 localStorage 获取 GitHub Token
         │
         ▼
2. 格式化 Issue 内容（将 Proposal 转换为 Markdown）
         │
         ▼
3. 前端直接调用 GitHub API 创建/更新 Issue
         │
         ▼
4. 调用 HagiCode 后端 API 更新 Session.metadata (存储 Issue URL 等信息)
         │
         ▼
5. 后端通过 SignalR 广播 SessionUpdated 事件
         │
         ▼
6. 前端接收事件，更新 UI 显示"已同步"状态

安全设计

安全问题始终是集成第三方服务的重中之重。我们做了以下考量：

防 CSRF 攻击：在 OAuth 跳转时，生成随机的 state 参数并存入 sessionStorage。回调时严格验证 state，防止请求被伪造。
Token 存储隔离：Token 仅存储在浏览器的 localStorage 中，利用同源策略（Same-Origin Policy），只有 HagiCode 的脚本才能读取，避免了服务器端数据库泄露波及用户。
错误边界：针对 GitHub API 常见的错误（如 401 Token 过期、422 验证失败、429 速率限制），设计了专门的错误处理逻辑，给用户以友好的提示。

实践：代码实现细节

纸上得来终觉浅，咱们来看看具体的代码是怎么实现的。

1. 后端最小化改动

后端只需要做两件事：存储同步信息、处理 OAuth 回调。

数据库变更 我们只需要在 Sessions 表增加一个 Metadata 列，用来存储 JSON 格式的扩展信息。

-- 添加 metadata 列到 Sessions 表
ALTER TABLE "Sessions" ADD COLUMN "Metadata" text NULL;

实体与 DTO 定义

public class Session : AuditedAggregateRoot<SessionId>
{
    // ... 其他属性 ...

    /// <summary>
    /// JSON metadata for storing extension data like GitHub integration
    /// </summary>
    public string? Metadata { get; set; }
}

// DTO 定义，方便前端序列化
public class GitHubIssueMetadata
{
    public required string Owner { get; set; }
    public required string Repo { get; set; }
    public int IssueNumber { get; set; }
    public required string IssueUrl { get; set; }
    public DateTime SyncedAt { get; set; }
    public string LastSyncStatus { get; set; } = "success";
}

public class SessionMetadata
{
    public GitHubIssueMetadata? GitHubIssue { get; set; }
}

2. 前端 OAuth 流程

这是连接的入口。我们使用标准的 Authorization Code Flow。

// 生成授权 URL 并跳转
export async function generateAuthUrl(): Promise<string> {
  const state = generateRandomString(); // 生成防 CSRF 的随机串
  sessionStorage.setItem('hagicode_github_state', state);

  const params = new URLSearchParams({
    client_id: clientId,
    redirect_uri: window.location.origin + '/settings?tab=github&oauth=callback',
    scope: ['repo', 'public_repo'].join(' '),
    state: state,
  });

  return `https://github.com/login/oauth/authorize?${params.toString()}`;
}

// 在回调页面处理 Code 换取 Token
export async function exchangeCodeForToken(code: string, state: string): Promise<GitHubToken> {
  // 1. 验证 State 防止 CSRF
  const savedState = sessionStorage.getItem('hagicode_github_state');
  if (state !== savedState) throw new Error('Invalid state parameter');

  // 2. 调用后端 API 进行 Token 交换
  // 注意：这里必须经过后端，因为需要 ClientSecret，不能暴露在前端
  const response = await fetch('/api/GitHubOAuth/callback', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code, state, redirectUri: window.location.origin + '/settings?tab=github&oauth=callback' }),
  });

  if (!response.ok) throw new Error('Failed to exchange token');

  const token = await response.json();

  // 3. 存入 LocalStorage
  saveToken(token);
  return token;
}

3. GitHub API 客户端封装

有了 Token 之后，我们就需要一个强有力的工具来调 GitHub API。

const GITHUB_API_BASE = 'https://api.github.com';

// 核心请求封装
async function githubApi<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const token = localStorage.getItem('gh_token');
  if (!token) throw new Error('Not connected to GitHub');

  const response = await fetch(`${GITHUB_API_BASE}${endpoint}`, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
      Accept: 'application/vnd.github.v3+json', // 指定 API 版本
    },
  });

  // 错误处理逻辑
  if (!response.ok) {
    if (response.status === 401) throw new Error('GitHub Token 失效，请重新连接');
    if (response.status === 403) throw new Error('无权访问该仓库或超出速率限制');
    if (response.status === 422) throw new Error('Issue 验证失败，可能标题重复');
    throw new Error(`GitHub API Error: ${response.statusText}`);
  }

  return response.json();
}

// 创建 Issue
export async function createIssue(owner: string, repo: string, data: { title: string, body: string, labels: string[] }) {
  return githubApi(`/repos/${owner}/${repo}/issues`, {
    method: 'POST',
    body: JSON.stringify(data),
  });
}

4. 内容格式化与同步

最后一步，就是把 HagiCode 的 Session 数据转换成 GitHub Issue 的格式。这有点像”翻译”工作。

// 将 Session 对象转换为 Markdown 字符串
function formatIssueForSession(session: Session): string {
  let content = `# ${session.title}\n\n`;
  content += `**> HagiCode Session:** #${session.code}\n`;
  content += `**> Status:** ${session.status}\n\n`;
  content += `## Description\n\n${session.description || 'No description provided.'}\n\n`;

  // 如果是 Proposal 类型，添加额外字段
  if (session.type === 'proposal') {
    content += `## Chief Complaint\n\n${session.chiefComplaint || ''}\n\n`;
    // 添加一个深链接，方便从 GitHub 跳回 HagiCode
    content += `---\n\n**[View in HagiCode](hagicode://sessions/${session.id})**\n`;
  }

  return content;
}

// 点击同步按钮的主逻辑
const handleSync = async (session: Session) => {
  try {
    const repoInfo = parseRepositoryFromUrl(session.repoUrl); // 解析仓库 URL
    if (!repoInfo) throw new Error('Invalid repository URL');

    toast.loading('正在同步到 GitHub...');

    // 1. 格式化内容
    const issueBody = formatIssueForSession(session);

    // 2. 调用 API
    const issue = await githubApiClient.createIssue(repoInfo.owner, repoInfo.repo, {
      title: `[HagiCode] ${session.title}`,
      body: issueBody,
      labels: ['hagicode', 'proposal', `status:${session.status}`],
    });

    // 3. 更新 Session Metadata (保存 Issue 链接)
    await SessionsService.patchApiSessionsSessionId(session.id, {
      metadata: {
        githubIssue: {
          owner: repoInfo.owner,
          repo: repoInfo.repo,
          issueNumber: issue.number,
          issueUrl: issue.html_url,
          syncedAt: new Date().toISOString(),
        }
      }
    });

    toast.success('同步成功！');
  } catch (err) {
    console.error(err);
    toast.error('同步失败，请检查 Token 或网络');
  }
};

总结与展望

通过这套”前端直连”方案，我们用最少的后端代码实现了 GitHub Issues 的无缝集成。

收获

开发效率高：后端改动极小，主要是数据库加一个字段和一个简单的 OAuth 回调接口，大部分逻辑都在前端完成。
安全性好：Token 不经过服务器数据库，降低了泄露风险。
用户体验佳：直接从前端发起请求，响应速度快，不需要经过后端中转。

注意事项

在实际部署时，有几个坑大家要注意：

OAuth App 设置：记得在 GitHub OAuth App 设置里填正确的 Authorization callback URL（通常是 http://localhost:3000/settings?tab=github&oauth=callback）。
速率限制：GitHub API 对未认证请求限制较严，但用 Token 后通常足够（5000次/小时）。
URL 解析：用户输入的 Repo URL 千奇百怪，记得正则要匹配 .git 后缀、SSH 格式等情况。

后续增强

目前的功能还是单向同步（HagiCode -> GitHub）。未来我们计划通过 GitHub Webhooks 实现双向同步，比如在 GitHub 里关闭 Issue，HagiCode 这边的会话状态也能自动更新。这需要我们在后端暴露一个 Webhook 接收端点，这也是下一步要做的有趣工作。

希望这篇文章能给你的第三方集成开发带来一点灵感！如果有问题，欢迎在 HagiCode GitHub 上提 Issue 讨论。