博客

如何实现 Claude Code 和 Codex 等 Agent CLI 的自动重试

2026年4月18日

如何实现 Claude Code 和 Codex 等 Agent CLI 的自动重试

自动重试这个词，看着像是个小开关，真落到工程现场里，完全不是那么回事。全民制作人们大家好，我是 HagiCode 制作人俞坤。今天这篇我们不聊空话，就聊 Claude Code、Codex 这类 Agent CLI 的自动重试到底该怎么做，才能既接得住异常，又不把系统带进无休止的重复执行里。

背景

如果你最近也在折腾 AI 编程，那这类问题你大概率已经碰到过了：任务不是一上来就挂，而是跑到一半断掉。

这事儿放到普通 HTTP 请求里，很多时候就是重发一下，顶多补个指数退避。可是 Agent CLI 不一样。Claude Code、Codex 这类工具通常是流式执行的，输出是一段一段往外推，过程中还会绑定 thread、session 或 resume token。换句话说，它不是“这一请求失败了没有”，而是：

前面已经吐出来的内容还算不算数
当前上下文还能不能接着跑
这次失败该不该自动恢复
如果要恢复，多久再试，试的时候发什么，原上下文还要不要复用

很多团队第一次做这里，都会下意识写一个最朴素的版本：报错了就再试一次。你说得非常正确，这个想法很自然，可是真进项目里，问题就一个接一个冒出来了。

有些错误明明是暂时故障，却被当成最终失败
有些错误根本不值得重试，却被系统反复重放
有 thread 的请求和没有 thread 的请求，被一把梭地一视同仁
退避策略没边界，后台请求自己把自己打爆

HagiCode 在接多种 Agent CLI 的过程中，也踩过这些坑。尤其是 Codex 这一侧，最初暴露出来的问题就是某类 reconnect 报文没有被识别成可重试终态，结果原本已有的恢复机制根本没机会生效。说白了，不是系统没有自动重试，而是系统没把“这次值得重试”认出来。

所以这篇文章想讲的核心点很明确：自动重试不是一个按钮，而是一套分层设计。

关于 HagiCode

本文分享的方案，来自我们在 HagiCode 项目里的真实实践。HagiCode 要做的事情，不是把某一个模型接上就完事，而是把多种 Agent CLI 的流式消息、工具调用、失败恢复、会话上下文，统一成一套能长期维护的执行模型。

我平时最关心的事情之一，就是怎么让 AI 编程这件事真正落到工程现场。写 Demo 不难，难的是把 Demo 变成团队真的愿意长期使用的东西。HagiCode 之所以认真做自动重试，不是因为这个功能看起来高级，而是因为长链路、流式、可续跑的 CLI 执行如果接不稳，用户看到的就不是智能助手，而是一个动不动半路掉线的命令包装器。

如果你想先看看项目入口，这里先放两个：

GitHub: github.com/HagiCode-org/site
官网: hagicode.com

再往前走一步讲，HagiCode 现在也已经上架 Steam 了，有 Steam 的朋友可以先加个愿望单：

Steam 商店页（加入愿望单 / 查看详情）

为什么 Agent CLI 的自动重试比普通重试更难

这个问题提得很实在，我们直接上结论：Agent CLI 的自动重试，难点不在“隔几秒再试一次”，而在“还能不能在原上下文里继续”。

你可以把它理解成一次长对话。普通 API 重试，更像电话占线再拨一遍；而 Agent CLI 重试，更像对方刚讲到一半信号断了，你得先判断要不要回拨，回拨以后要不要从头说，对方还记不记得刚刚聊到哪。谁说这两者是一回事呢？它们压根不是一个工程问题。

具体看，有四个难点最典型。

1. 它是流式的

一旦输出已经发给用户，你就不能像处理普通请求那样，把失败偷偷吞掉然后悄悄重来。因为前面那部分内容已经被看到了，再次重放时如果策略不对，前端很容易看到重复文本、错乱状态，工具调用生命周期也会一起乱套。这波不是玄学，是工程。

2. 它通常绑定会话上下文

Codex 这类 provider 会绑定 thread，Claude Code 一类实现也会有 continuation target 或等价的续跑上下文。真正能自动重试的前提，不只是“这个错误长得像暂时故障”，还包括“这次执行还有没有继续下去的载体”。

3. 它不是所有错误都值得重试

网络抖动、SSE idle timeout、上游临时故障，这些通常可以试一试。可如果你遇到的是认证失败、上下文已经丢了，或者 provider 根本没有 resume 能力，那继续重试多数不是恢复，而是在制造噪音。

4. 它需要边界

无限自动重试几乎总是错的。技术趋势可以热闹一阵子，工程规律往往会稳定很多年，其中一条就是：失败恢复一定要有边界。系统必须知道自己最多试几次、每次隔多久、什么时候该停手承认这回真不行了。

也正因为这几个特点，HagiCode 最后没有把自动重试写成某个 provider 里的几行 try/catch，而是把它提炼成一层共享能力。说到底，工程问题还是要回到工程方法里解决。

HagiCode 的做法：把重试从 Provider 里拿出来

HagiCode 当前这套真实实现，可以压缩成一句话：

共享层统一管理重试流程，具体 Provider 只负责回答两个问题：这个终态值不值得重试？当前上下文还能不能继续？

这件事不复杂，可是很关键。因为一旦把职责切开，Claude Code、Codex，甚至其他 Agent CLI 都能复用同一个骨架。模型会说，工具会变，工作流会升级，但工程上的基本盘一直都在那里。

第一层：用统一协调器管理重试循环

项目中的核心实现片段大概是下面这样：

internal static class ProviderErrorAutoRetryCoordinator
{
    public static async IAsyncEnumerable<CliMessage> ExecuteAsync(
        string prompt,
        ProviderErrorAutoRetrySettings? settings,
        Func<string, IAsyncEnumerable<CliMessage>> executeAttemptAsync,
        Func<bool> canRetryInSameContext,
        Func<TimeSpan, CancellationToken, Task> delayAsync,
        Func<CliMessage, bool> isRetryableTerminalMessage,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        var normalizedSettings = ProviderErrorAutoRetrySettings.Normalize(settings);
        var retrySchedule = normalizedSettings.Enabled
            ? normalizedSettings.GetRetrySchedule()
            : [];

        for (var attempt = 0; ; attempt++)
        {
            var attemptPrompt = attempt == 0
                ? prompt
                : ProviderErrorAutoRetrySettings.ContinuationPrompt;

            CliMessage? terminalFailure = null;

            await foreach (var message in executeAttemptAsync(attemptPrompt)
                               .WithCancellation(cancellationToken))
            {
                if (isRetryableTerminalMessage(message))
                {
                    terminalFailure = message;
                    break;
                }

                yield return message;
            }

            if (terminalFailure is null)
            {
                yield break;
            }

            if (attempt >= retrySchedule.Count || !canRetryInSameContext())
            {
                yield return terminalFailure;
                yield break;
            }

            await delayAsync(retrySchedule[attempt], cancellationToken);
        }
    }
}

这段代码干的事情，其实非常朴素，但很有力。

中间失败先不直接透传，协调器先判断能不能恢复
只有重试预算耗尽，最终失败才真正回到上层
第二轮开始不再发送原始 prompt，而是统一发送 continuation prompt

这也就是为什么我前面一直强调，自动重试不是简单的“再请求一次”。它不是在补一个异常分支，而是在管理一条执行生命周其。听起来有点像产品经理，但工程上确实如此。

第二层：把重试策略快照化

另一个很容易被忽略的问题是：谁来决定这次请求是否开启自动重试？

HagiCode 的答案是，不要依赖某个“此刻的全局配置”，而是把策略做成 snapshot，跟着这次请求一起走。这样一来，会话排队、消息持久化、执行转发、provider 适配，都不会把策略弄丢。一次成功不叫体系，持续成功才叫体系。

核心结构可以简化成这样：

public sealed record ProviderErrorAutoRetrySnapshot
{
    public const string DefaultStrategy = "default";

    public bool Enabled { get; init; }

    public string Strategy { get; init; } = DefaultStrategy;

    public static ProviderErrorAutoRetrySnapshot Normalize(bool? enabled, string? strategy)
    {
        return new ProviderErrorAutoRetrySnapshot
        {
            Enabled = enabled ?? true,
            Strategy = string.IsNullOrWhiteSpace(strategy)
                ? DefaultStrategy
                : strategy.Trim()
        };
    }
}

然后在执行侧再映射成 provider 真正消费的设置对象。这个做法的价值很直接：

业务层决定“该不该重试”
运行时决定“怎么重试”

两边各管一摊，互相不打架。很多问题不是不能做，只是没把代价算明白。把策略快照化，本质上就是在提前把代价算清楚。

第三层：Provider 只做终态判定和上下文判定

到了具体的 Claude Code 或 Codex provider，这里的职责反而很薄。你可以把它理解成增强，不要把它误会成代替。

以 Codex 为例，它最终接入共享协调器时，本质上只需要提供三样东西：

await foreach (var message in ProviderErrorAutoRetryCoordinator.ExecuteAsync(
                   prompt,
                   options.ProviderErrorAutoRetry,
                   retryPrompt => ExecuteCodexAttemptAsync(...),
                   () => !string.IsNullOrWhiteSpace(resolvedThreadId),
                   DelayAsync,
                   IsRetryableTerminalFailure,
                   cancellationToken))
{
    yield return message;
}

你会发现，真正属于 Provider 自己的判断只有两个：

IsRetryableTerminalFailure
canRetryInSameContext

Codex 看的是 thread 还能不能续上，Claude Code 看的是 continuation target 还在不在。退避策略、重试次数、后续 prompt，这些通通不该让 Provider 自己重新发明一遍。

这一层拆出来以后，HagiCode 接更多 CLI 的成本就低很多了。你不用复制一整套重试状态机，只要把“这个 provider 的边界条件”接进来就行。写得快，不等于写得稳；接得住，不等于接得好；能跑起来，也不等于能长期维护。

一个很容易做错的点：别把所有报错都当可重试

这次分析里，我觉得最值得单拎出来讲的，不是“怎么实现重试”，而是“怎么避免错误重试”。

最开始的问题切入口，是 Codex 少识别了一条 reconnect 报文。按直觉，很多人会选一个最小修法：往白名单里再加一条字符串前缀。这个思路不能说错，只是它更像 Demo 时期的解法，不太像长期维护的解法。

从当前 HagiCode 的落地来看，系统已经往更稳的方向走了一步。它不再只盯着某个字面字符串，而是把可恢复的终态统一交给共享协调器处理。这样做的好处很明显：

不容易因为某条文案的小改动就彻底失效
测试覆盖可以围绕“终态 envelope”展开，而不是单条硬编码文本
同一个 provider 的重试逻辑会更一致

当然，这里要立一个边界：更通用，不等于更宽松。只要当前上下文不能继续，哪怕报错看起来很像暂时故障，也不应该盲目 replay。

这点很关键。真正让人安心的，不是它偶尔灵一次，而是它大多数时候都靠谱。如果一个流程只能靠高手维持，那它离普及还差得远。

实践里最值得保留的三条经验

文章写到这里，差不多可以往实践层收一收了。如果你准备在自己的项目里实现类似能力，我最建议先守住下面三条。

1. 重试预算必须有边界

HagiCode 当前默认的退避节奏是：

10 秒
20 秒
60 秒

这个节奏不一定适合所有系统，但“有边界”这件事必须保留。要不然，自动重试很快就会从恢复机制变成事故放大器。别急着把名字起得太大，先看看这东西能不能在团队里活过两个迭代。

2. continuation prompt 要统一

项目里使用的是固定 continuation prompt，让后续 attempt 明确走“继续当前上下文”的路径，而不是重新发起一轮完整请求。这个能力不花哨，可是你真做项目时离不开。很多能力看起来像魔法，拆开以后不过是一套被打磨过的工程流程。

3. 共享库和适配层都要有镜像测试

这点我很想多说一句。很多团队会在共享运行时里写一层测试，然后觉得差不多了。其实不够。

HagiCode 这边之所以让我比较放心，是因为两层都补了测试：

共享 Provider 测“是否真的发生了自动续跑”
适配层测“最终错误和流式消息有没有被整理坏”

我这次也额外补跑了两组相关测试，结果都是 31 个用例全部通过。这个结果本身说明不了设计一定完美，可它至少能说明一件事：当前这套自动重试不是纸面方案，而是已经被代码和测试共同约束住的能力。Talk is cheap. Show me the code. 放到这里，恰好合适。

总结

如果把整篇文章压缩成一句话，那就是：

Claude Code、Codex 等 Agent CLI 的自动重试，最好不要做成某个 Provider 内部的局部技巧，而应该做成共享协调器 + 策略快照 + 上下文判定 + 镜像测试的组合。

这样做带来的收益，其实非常实在：

逻辑只写一遍，多个 Provider 都能复用
请求是否允许重试，可以稳定地跟着执行链路走
有上下文时继续跑，没上下文时及时停手
前端最终看到的是稳定的完成态或失败态，而不是一堆半途而废的中间噪音

这套方案，是 HagiCode 在真实接入多种 Agent CLI 的过程中一点点打磨出来的。谁说 AI 辅助编程就不是新时代的结对编程呢？模型帮你起步、补全、发散，可真正决定体验上限的，往往还是上下文、流程和约束。

如果本文对你有帮助，也欢迎顺手看看 HagiCode 的公开入口：

GitHub: github.com/HagiCode-org/site
官网: hagicode.com
30 分钟实战演示: www.bilibili.com/video/BV1pirZBuEzq/
Desktop 安装入口: hagicode.com/desktop/
Steam: Steam 商店页（加入愿望单 / 查看详情）

HagiCode 现在已经上架 Steam 了，这不是画饼，链接也给你放这儿了。有 Steam 的朋友可以先加个愿望单，自己点进去看一眼，比我在这儿多说十句都来得直接。

先把这件事讲到这里，剩下的我们继续在真实项目里见。

参考资料

HagiCode 项目主页: https://hagicode.com
HagiCode GitHub 仓库: https://github.com/HagiCode-org/site
官方演示视频: https://www.bilibili.com/video/BV1pirZBuEzq/
Desktop 安装说明: https://hagicode.com/desktop/

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-02-11-agent-cli-automatic-retry/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

SQLite 分片方案实战：三种分片策略的深度对比

2026年4月17日

SQLite 分片方案实战：三种分片策略的深度对比

当单文件 SQLite 遇到并发瓶颈，我们该如何破局？本文分享 HagiCode 项目中三种不同场景下的 SQLite 分片方案，帮你理解如何选择合适的分片策略。

全民制作人们大家好，我是 HagiCode 制作人俞坤。

背景

在构建高性能应用时，单文件 SQLite 数据库会碰到很现实的问题。用户量和数据量一上来，这些状况就会排队找上门：

写入操作开始排队，响应时间肉眼可见地变长
查询性能随数据增长往下掉
多线程访问时频繁出现 “database is locked” 错误

很多人第一反应是：要不要直接迁移到 PostgreSQL 或者 MySQL？这波操作虽然能解决问题，但部署复杂度会直线上升。有没有更轻量的方案？

答案是：分片。说到底，工程问题还是要回到工程方法里解决，通过将数据分散到多个 SQLite 文件，可以显著提升并发能力和查询性能，同时保持 SQLite 的轻量级特性。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。作为一个 AI 代码助手项目，HagiCode 需要处理大量的对话消息、状态持久化和事件历史记录。正是在解决这些实际问题的过程中，我们总结出了三种不同场景下的分片方案。

工欲善其事，必先利其器，但这些”器”怎么用，还得看具体的”事”是什么。

我们的代码仓库在 github.com/HagiCode-org/site，欢迎感兴趣的朋友深入了解。

三种分片方案概览

经过对 HagiCode 代码库的分析，我们发现了三种针对不同业务场景的 SQLite 分片方案：

Session Message 分片存储：AI 对话消息存储，特点是高频写入、基于 Session 的隔离查询
Orleans Grain 分片存储：分布式框架状态持久化，特点是跨节点访问、需要确定性路由
Hero History 分片存储：游戏化系统历史事件记录，特点是事件溯源、需要迁移兼容

虽然业务场景不同，但三者都遵循相同的核心设计原则：

确定性路由：直接从业务 ID 计算分片，无需元数据表
透明访问：上层通过统一接口操作，不感知分片存在
独立存储：每个分片是完全独立的 SQLite 文件
并发优化：WAL 模式 + busy_timeout 降低锁竞争

很多人会问：为什么不搞一套通用的分片方案？这个问题问得很实在，我们直接上结论：工程上没有万能方案，只有最贴合当前业务场景的方案。接下来我们深入对比这三种方案的具体实现。

分片策略对比

分片数量与命名规则

方面	Session Message	Orleans Grain	Hero History
分片数量	256 (16²)	100	10
命名规则	16 进制 (00-ff)	10 进制 (00-99)	10 进制 (0-9)
存储目录	`DataDir/messages/`	`DataDir/orleans/grains/`	`DataDir/hero-history/`
文件名模式	`{shard}.db`	`grains-{shard}.db`	`{shard}.db`

为什么分片数量差异这么大？这取决于业务特点。换句话说，模型会说，工具会变，工作流会升级，但工程上的基本盘一直都在那里：你得先搞清楚自己要解决什么问题。

Session Message 使用 256 个分片，因为对话消息的写入频率最高，需要更多的分片来分散负载
Orleans Grain 使用 100 个分片，平衡了并发性能和管理复杂度
Hero History 只用 10 个分片，因为历史事件写入频率较低，且需要考虑迁移成本

路由算法差异

路由算法是分片方案的核心，决定了数据如何分布到各个分片。三种方案使用了不同的路由策略：

// Session Message: GUID 后两位 16 进制
var normalized = Guid.Parse(sessionId.Value).ToString("N").ToLowerInvariant();
return normalized[^2..];  // 取末两位 16 进制字符

// Orleans Grain: 提取数字后两位取模
var digits = ExtractDigits(grainId);  // 提取所有数字
var lastTwoDigits = (digits[^2] * 10) + digits[^1];
return lastTwoDigits % shardCount;

// Hero History: 末位字符 ASCII 值取模
return heroId[^1] % 10;

设计思路解析：

Session Message 的 ID 是 GUID，转换为 16 进制后取末两位，可以得到均匀分布的 256 个分片
Orleans Grain 的 ID 格式不统一，可能包含字母和数字，所以提取所有数字后取模
Hero History 的 ID 是字符串，直接用末位字符的 ASCII 值取模，简单但分布可能不够均匀

关键点：无论使用哪种算法，都必须保证同一 ID 永远映射到同一分片。这是分布式系统中最基本的要求，否则会导致数据不一致。说到底，路由不稳定，一切努力都是零。

初始化策略差异

方面	Session Message	Orleans Grain	Hero History
初始化时机	按需懒加载	启动时全量并行初始化	按需懒加载
并发控制	`Lazy<Task>` 防重复初始化	`Parallel.ForEachAsync`	`Lazy<Task>` 防重复初始化

为什么 Orleans Grain 选择启动时全量初始化？

因为 Orleans 是分布式框架，Grain 可能被调度到任意节点。如果在运行时才发现分片文件不存在，会导致请求失败。启动时全量初始化虽然会延长启动时间，但能确保运行时的稳定性。能跑起来只是开始，能维护下去才算本事。

懒加载的优势：

对于 Session Message 和 Hero History，使用懒加载可以减少启动时间，只有在真正需要访问某个分片时才创建文件和初始化 Schema。使用 Lazy<Task> 可以防止并发初始化时的竞态条件。这个设计看着简单，但在真实项目里能省掉很多不必要的麻烦。

Schema 设计特点

三种方案的 Schema 设计反映了各自的业务特点：

Session Message：

支持 Event Sourcing 模式（事件表 + 快照表）
包含消息内容块子表（MessageContentBlocks）
具有压缩和压缩标记字段，支持后续优化

Orleans Grain：

最简设计：单表 GrainState
JSON 序列化存储状态
ETag 乐观并发控制

Hero History：

时间线查询优化索引
DedupeKey 唯一约束防重复
支持多种事件类型和状态

从这些设计中可以看出，Schema 设计应该紧密贴合业务需求，而不是追求通用性。Orleans Grain 的简单设计正是因为它只需要存储序列化后的状态，不需要复杂的查询能力。这波不是玄学，是工程。别急着把名字起得太大，先看看这东西能不能在团队里活过两个迭代。

并发配置对比

三种方案都使用了相同的 SQLite 并发优化配置：

PRAGMA journal_mode=WAL;      -- 写前日志模式
PRAGMA synchronous=NORMAL;     -- 降低持久化开销
PRAGMA busy_timeout=5000;      -- 5秒忙等待
PRAGMA foreign_keys=ON;        -- 外键约束

WAL 模式的优势：

传统的回滚日志模式在写入时会产生锁竞争，而 WAL 模式允许读写并发进行。这在大数据量场景下可以显著提升性能。很多人不知道这个配置，其实它比你想的要重要得多。

synchronous=NORMAL 的权衡：

设置为 FULL 可以保证最高安全性，但会显著降低性能。NORMAL 模式在安全性和性能之间取得了平衡，对于大多数应用来说是合适的选择。这个配置不需要纠结太久，NORMAL 就够了。

如何选择分片策略

基于对 HagiCode 三种方案的分析，我们可以总结出以下决策矩阵：

高吞吐量场景 → 更多分片（如 Message 用 256）
简单维护性   → 较少分片（如 Hero History 用 10）
数字 ID 为主 → 取模算法（Orleans Grain）
GUID 为主    → 16 进制后缀（Session Message）
字符串 ID    → ASCII 取模（Hero History）

分片数量选择的经验值：

太少（< 10）：并发提升有限，分片意义不大
太多（> 1000）：文件管理复杂，连接池开销大
经验值：10-100 个分片适用于大多数场景
极高并发场景：可以考虑 256 个分片

这事你要是只看演示，确实容易上头；可一旦进了生产环境，账就得一笔一笔算清楚。很多问题不是不能做，只是没把代价算明白。

实践指南

实现标准化分片路由器

public interface IShardResolver<TId>
{
    string ResolveShardKey(TId id);
}

// 16 进制分片（适用于 GUID）
public class HexSuffixShardResolver : IShardResolver<string>
{
    private readonly int _suffixLength;

    public HexSuffixShardResolver(int suffixLength = 2)
    {
        _suffixLength = suffixLength;
    }

    public string ResolveShardKey(string id)
    {
        var normalized = id.Replace("-", "").ToLowerInvariant();
        return normalized[^_suffixLength..];
    }
}

// 数字取模分片（适用于纯数字 ID）
public class NumericModuloShardResolver : IShardResolver<long>
{
    private readonly int _shardCount;

    public NumericModuloShardResolver(int shardCount)
    {
        _shardCount = shardCount;
    }

    public string ResolveShardKey(long id)
    {
        return (id % _shardCount).ToString("D2");
    }
}

统一连接工厂模式

public class ShardedConnectionFactory<TOptions>
{
    private readonly ConcurrentDictionary<string, Lazy<Task>> _initializationTasks = new();
    private readonly TOptions _options;
    private readonly IShardSchemaInitializer _initializer;

    public ShardedConnectionFactory(
        TOptions options,
        IShardSchemaInitializer initializer)
    {
        _options = options;
        _initializer = initializer;
    }

    public async Task<TDbContext> CreateAsync(string shardKey, CancellationToken ct)
    {
        var connectionString = BuildConnectionString(shardKey);

        // 使用 Lazy<Task> 防止并发初始化
        var initTask = _initializationTasks.GetOrAdd(
            connectionString,
            _ => new Lazy<Task>(() => InitializeShardAsync(connectionString, ct))
        );

        await initTask.Value;
        return CreateDbContext(connectionString);
    }

    private async Task InitializeShardAsync(string connectionString, CancellationToken ct)
    {
        await _initializer.InitializeAsync(connectionString, ct);
    }

    private string BuildConnectionString(string shardKey)
    {
        var shardPath = Path.Combine(_options.BaseDirectory, $"{shardKey}.db");
        return $"Data Source={shardPath}";
    }

    private TDbContext CreateDbContext(string connectionString)
    {
        // 根据具体的 ORM 创建 DbContext
        return Activator.CreateInstance(typeof(TDbContext), connectionString) as TDbContext;
    }
}

Schema 初始化最佳实践

public class SqliteShardInitializer : IShardSchemaInitializer
{
    public async Task InitializeAsync(string connectionString, CancellationToken ct)
    {
        await using var connection = new SqliteConnection(connectionString);
        await connection.OpenAsync(ct);

        // 并发优化配置
        await connection.ExecuteAsync("""
            PRAGMA journal_mode=WAL;
            PRAGMA synchronous=NORMAL;
            PRAGMA busy_timeout=5000;
            PRAGMA foreign_keys=ON;
        """);

        // 创建表结构
        await connection.ExecuteAsync("""
            CREATE TABLE IF NOT EXISTS Entities (
                Id TEXT PRIMARY KEY,
                CreatedAt TEXT NOT NULL,
                UpdatedAt TEXT NOT NULL,
                Data TEXT NOT NULL,
                ETag TEXT
            );
        """);

        // 创建索引
        await connection.ExecuteAsync("""
            CREATE INDEX IF NOT EXISTS IX_Entities_CreatedAt
            ON Entities(CreatedAt DESC);

            CREATE INDEX IF NOT EXISTS IX_Entities_UpdatedAt
            ON Entities(UpdatedAt DESC);
        """);
    }
}

关键注意事项

1. 路由稳定性

路由算法必须保证同一 ID 永远映射到同一分片。避免使用随机或时间相关的计算，也不要在算法中引入可变参数。

2. 分片数量选择

分片数量应该在设计阶段确定，后期修改非常困难。需要考虑：

当前和未来的并发量
单个分片的管理成本
数据迁移的复杂度

3. 迁移考虑

Hero History 方案展示了完整的迁移路径：

新建分片存储基础设施
实现迁移服务将主库数据复制到分片
验证迁移后查询兼容性
切换读写路径到分片
清理主库旧表

设计分片方案时就需要考虑未来的迁移需求。Talk is cheap. Show me the code，但光有代码还不够，你还得有完整的迁移路径。一次成功不叫体系，持续成功才叫体系。

4. 监控与运维

监控各分片的大小分布，及时发现数据倾斜
设置告警检测分片热点，避免单个分片成为瓶颈
定期检查 WAL 文件大小，防止磁盘空间占用过多
建立分片健康检查机制

5. 测试覆盖

测试边界条件（空 ID、特殊字符、超长 ID）
验证路由确定性，确保同一 ID 总是映射到同一分片
并发写入压力测试，验证锁竞争得到有效缓解
迁移测试，确保数据完整性和一致性

总结

通过对比 HagiCode 项目中的三种 SQLite 分片方案，我们可以看到：

没有万能的解决方案：不同业务场景需要不同的分片策略
核心原则是通用的：确定性路由、透明访问、独立存储、并发优化
设计要面向未来：考虑迁移路径和运维成本

如果你的项目正在使用 SQLite，并且开始遇到并发瓶颈，希望这篇文章能为你提供一些思路。不需要急着迁移到重量级数据库，有时候合适的分片方案就能解决问题。

当然，分片不是银弹。在选择分片方案之前，先确保：

你已经优化了单表查询性能
你已经使用了合适的索引
你已经启用了 WAL 模式

只有在这些优化都做完之后，仍然存在性能瓶颈时，才考虑引入分片。你能把简单的事情做好，这本身就是一种能力。

很多话讲一遍不如做一遍，接下来就让工程结果自己发声。

参考资料

HagiCode 项目仓库：github.com/HagiCode-org/site
SQLite WAL 模式文档：sqlite.org/wal.html
Orleans 分布式框架：dotnet.github.io/orleans

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-17-sqlite-sharding-strategies-comparison/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

如何用 GitHub Actions 实现 Steam 自动化发布

2026年4月16日

如何用 GitHub Actions 实现 Steam 自动化发布

本文分享了 HagiCode Desktop 项目中实现 Steam 自动化发布的完整方案，从 GitHub Release 到 Steam 平台的全链路自动化流程，包括 Steam Guard 认证、多平台 Depot 上传等关键技术细节。

背景

Steam 平台的发布流程，其实和传统的应用分发方式挺不一样的。Steam 有自己的一套完整更新分发系统，开发者得通过 SteamCMD 工具把构建产物上传到 Steam 的 CDN 网络，而不是像其他平台那样直接丢个下载链接就完事了。

HagiCode Desktop 项目计划上架 Steam 平台，这也算是给我们的发布流程带来了点新挑战：

需要把现有的构建产物转换成 Steam 兼容的格式
得通过 SteamCMD 工具上传到 Steam 平台
还必须处理 Steam Guard 认证这玩意儿
需要支持多平台（Linux、Windows、macOS）的 Depot 上传
还要实现从 GitHub Release 到 Steam 的自动化流转

项目此前已经实现了”便携版模式”（portable version mode），允许应用检测打包在 extra 目录中的固定服务载荷。我们的目标，其实就是让这套便携版模式和 Steam 分发能无缝集成罢了。

关于 HagiCode

本文分享的方案，来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，支持桌面端运行，我们正在推进 Steam 平台的上架工作，因此才需要建立一套可靠的自动化发布流程。

架构设计

整个 Steam 发布流程的核心是一个 GitHub Actions 工作流，它把整个过程分为三个主要阶段：

┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow (Steam Release)                      │
├─────────────────────────────────────────────────────────────┤
│ 1. 准备阶段:                                                 │
│    - 检出 portable-version 代码                             │
│    - 从 GitHub Release 下载构建产物                         │
│    - 解压并准备 Steam 内容目录                              │
│                                                             │
│ 2. SteamCMD 设置:                                           │
│    - 安装/复用 SteamCMD                                     │
│    - 使用 Steam Guard 进行认证                              │
│                                                             │
│ 3. 发布阶段:                                                 │
│    - 生成 Depot VDF 配置文件                                │
│    - 生成 App Build VDF 配置文件                            │
│    - 调用 SteamCMD 上传到 Steam                             │
└─────────────────────────────────────────────────────────────┘

这种设计的优势，怎么说呢：

复用现有的 GitHub Release 产物，避免重复构建，毕竟谁愿意重复劳动呢
通过自托管运行器实现安全隔离，多一层保障总是好的
支持预览模式和正式发布分支切换，灵活一点
完整的错误处理和日志记录，出问题的时候不至于太迷茫

工作流实现

触发参数设计

我们的工作流支持以下关键参数：

inputs:
  release:           # Portable Version 发布标签
    description: '要发布的版本标签（如 v1.0.0）'
    required: true
  steam_preview:     # 是否生成预览构建
    description: '是否为预览模式'
    required: false
    default: 'false'
  steam_branch:      # 设置为 live 的 Steam 分支
    description: '目标 Steam 分支'
    required: false
    default: 'preview'
  steam_description: # 构建描述覆盖
    description: '构建描述'
    required: false

自托管运行器配置

出于安全考虑，我们使用带 steam 标签的自托管运行器：

runs-on:
  - self-hosted
  - Linux
  - X64
  - steam

这样可以确保 Steam 发布在专用运行器上执行，保持敏感凭据的安全隔离。毕竟安全这事儿，多注意一点总是好的。

并发控制

为了避免同一版本的发布相互干扰，我们配置了并发控制：

concurrency:
  group: portable-version-steam-${{ github.event.inputs.release }}
  cancel-in-progress: false

注意这里设置 cancel-in-progress: false，因为 Steam 发布过程可能较长，我们也不想因为新的触发就取消正在进行的发布。毕竟发布个版本也不容易，总得让人家跑完不是？

核心脚本实现

准备发布输入

prepare-steam-release-input.mjs 脚本负责准备发布所需的输入：

// 下载 GitHub Release 的构建清单和产物清单
const buildManifest = await downloadBuildManifest(releaseTag);
const artifactInventory = await downloadArtifactInventory(releaseTag);

// 下载各平台的压缩包
for (const platform of ['linux-x64', 'win-x64', 'osx-universal']) {
  const artifactUrl = getArtifactUrl(artifactInventory, platform);
  await downloadArtifact(artifactUrl, platform);
}

// 解压到 Steam 内容目录结构
await extractToSteamContent(sources, contentRoot);

Steam Guard 认证

Steam 要求使用 Steam Guard 保护账户，我们实现了基于共享密钥的代码生成算法：

function generateSteamGuardCode(sharedSecret, timestamp = Date.now()) {
  const secret = decodeSharedSecret(sharedSecret);
  const time = Math.floor(timestamp / 1000 / 30);

  const timeBuffer = Buffer.alloc(8);
  timeBuffer.writeBigUInt64BE(BigInt(time));

  // 使用 HMAC-SHA1 生成时间基础的一次性代码
  const hash = crypto.createHmac('sha1', secret)
    .update(timeBuffer)
    .digest();

  // 转换为 5 字符的 Steam Guard 代码
  const code = steamGuardCode(hash);
  return code;
}

这个实现基于 Steam Guard 的 TOTP（Time-based One-Time Password）机制，每 30 秒生成一个新的验证码。毕竟安全这东西，还是得用靠谱的方式才行。

VDF 配置生成

VDF（Valve Data Format）是 Steam 使用的配置格式，我们需要生成两种类型的 VDF 文件：

Depot VDF 用于配置各个平台的内容：

function buildDepotVdf(depotId, contentRoot) {
  return [
    '"DepotBuildConfig"',
    '{',
    `  "DepotID" "${escapeVdf(depotId)}"`,
    `  "ContentRoot" "${escapeVdf(contentRoot)}"`,
    '  "FileMapping"',
    '  {',
    '    "LocalPath" "*"',
    '    "DepotPath" "."',
    '    "recursive" "1"',
    '  }',
    '}'
  ].join('\n');
}

App Build VDF 用于配置整个应用构建：

function buildAppBuildVdf(appId, depotBuilds, description, setLive) {
  const vdf = [
    '"appbuild"',
    '{',
    `  "appid" "${appId}"`,
    `  "desc" "${escapeVdf(description)}"`,
    `  "contentroot" "${escapeVdf(contentRoot)}"`,
    '  "buildoutput" "build_output"',
    '  "depots"',
    '  {'
  ];

  for (const [depotId, depotVdfPath] of Object.entries(depotBuilds)) {
    vdf.push(`    "${depotId}" "${depotVdfPath}"`);
  }

  if (setLive) {
    vdf.push(`  }`);
    vdf.push(`  "setlive" "${setLive}"`);
  }

  vdf.push('}');
  return vdf.join('\n');
}

SteamCMD 调用

最后，通过调用 SteamCMD 执行上传：

await runCommand(steamcmdPath, [
  '+login', steamUsername, steamPassword, steamGuardCode,
  '+run_app_build', appBuildPath,
  '+quit'
]);

这一步算是整个流程的最后一跃，跨过去就完成了…

多平台 Depot 处理

Steam 使用 Depot 系统管理不同平台的内容，我们支持三种主要的 Depot：

平台	Depot 标识	架构支持
Linux	`linux-x64`	x64_64
Windows	`win-x64`	x64_64
macOS	`osx-universal`	universal, x64_64, arm64

每个 Depot 都有独立的内容目录和 VDF 配置文件，这样可以确保不同平台的用户只下载自己需要的内容。毕竟流量也是钱，能省一点是一点。

发布流程

步骤 1：准备 GitHub Release

首先需要在 portable-version 仓库创建一个 GitHub Release，包含：

各平台的压缩包
构建清单（{tag}.build-manifest.json）
产物清单（{tag}.artifact-inventory.json）

步骤 2：触发 Steam 发布工作流

通过 GitHub Actions 手动触发工作流，填写必要参数：

release: 要发布的版本标签（如 v1.0.0）
steam_branch: 目标分支（如 preview 或 public）
steam_preview: 是否预览模式

步骤 3：自动执行发布流程

工作流会自动执行以下步骤：

下载并解压 GitHub Release 产物
安装/更新 SteamCMD
生成 Steam VDF 配置文件
使用 Steam Guard 认证
上传内容到 Steam CDN
设置指定分支为 live

这一套流程走下来，也算是把该做的都做了。

配置指南

必需的 Secrets 配置

在 GitHub 仓库设置中配置以下密钥：

Secret 名称	说明
`STEAM_USERNAME`	Steam 账户用户名
`STEAM_PASSWORD`	Steam 账户密码
`STEAM_SHARED_SECRET`	Steam Guard 共享密钥（可选）
`STEAM_GUARD_CODE`	Steam Guard 代码（可选）
`STEAM_APP_ID`	Steam 应用 ID
`STEAM_DEPOT_ID_LINUX`	Linux Depot ID
`STEAM_DEPOT_ID_WINDOWS`	Windows Depot ID
`STEAM_DEPOT_ID_MACOS`	macOS Depot ID

这些配置项，其实也没什么特别的，就是该有的都得有罢了。

环境变量配置

变量名称	说明	默认值
`PORTABLE_VERSION_STEAMCMD_ROOT`	SteamCMD 安装目录	`~/.local/share/portable-version/steamcmd`

最佳实践

Steam Guard 认证管理

首次运行需要手动输入 Steam Guard 代码，之后建议配置共享密钥自动生成代码。这样可以避免每次发布都需要手动干预，毕竟谁也不想每次都重复同样的操作。

SteamCMD 会保存登录令牌，后续可以复用。但要注意令牌的有效期，过期后还是得重新认证的，这也没办法。

内容目录结构

确保 Steam 内容目录结构正确：

steam-content/
├── linux-x64/     # Linux 平台内容
├── win-x64/       # Windows 平台内容
└── osx-universal/ # macOS 通用二进制内容

每个目录下应该包含对应平台的完整应用文件。这点倒也没什么好说的，该怎么做就怎么做。

预览模式使用

预览模式不会设置任何分支为 live，适合测试验证：

if [ "$STEAM_PREVIEW_INPUT" = 'true' ]; then
  cmd+=(--preview)
fi

这样可以先上传到 Steam 平台进行验证，确认无误后再切换到正式分支。多一层验证，总是好的。

错误处理和日志

脚本包含了完善的错误处理和日志记录：

验证 GitHub Release 存在性
检查必需的元数据文件
确保平台内容存在
生成 GitHub Actions 摘要报告

这些信息对于调试和审计都非常有价值，毕竟出问题的时候能有个线索，总比一头雾水要好。

产物管理

工作流生成两种产物：

portable-steam-release-preparation-{tag}: 发布准备元数据
portable-steam-build-metadata-{tag}: Steam 构建元数据

这些产物可以用于后续的审计和调试，保存时间建议设置为 30 天。反正也不占多少地方，留着也无妨。

实际应用

在 HagiCode 项目中，这套自动化发布流程已经成功运行了多个版本。从 GitHub Release 到 Steam 平台的整个链路完全自动化，无需人工干预。

这大大提高了我们的发布效率和可靠性。之前手动发布一个版本需要 30 分钟以上的时间，现在只需要几分钟就能完成整个流程。时间这东西，省下来总归是好的。

更重要的是，自动化流程减少了人为错误的可能性，每次发布都是标准化的流程，结果也更加可预测。毕竟重复的事情交给机器去做，人也轻松点。

总结

通过本文分享的方案，我们实现了：

从 GitHub Release 到 Steam 平台的完全自动化
支持多平台的 Depot 上传
基于 Steam Guard 的安全认证
预览模式和正式发布的灵活切换
完善的错误处理和日志记录

这套方案不仅适用于 HagiCode 项目，也可以为其他计划上架 Steam 平台的项目提供参考。如果你也在考虑 Steam 自动化发布，希望本文的实践能够对你有所帮助。

其实技术这东西，说复杂也复杂，说简单也简单。关键是找到适合自己的方式罢了。

如果本文对你有帮助，欢迎来 HagiCode 的 GitHub 仓库给个 Star，或者访问官网了解更多信息。

参考资料

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-16-steam-release-automation-github-actions/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

如何利用廉价的云服务器搭建加速下载的分发站

2026年4月15日

如何利用廉价的云服务器搭建加速下载的分发站

云存储的流量贵得离谱，跨国访问慢得让人抓狂，CDN 的价格又让人望而却步…这些痛，大概做分发的都懂吧。本文分享一下我们在 HagiCode 项目里摸索出来的一套低成本方案。云服务器 + Nginx 缓存层，成本降了一半，速度倒是提上去了，也算是一点小小的安慰。

背景

互联网嘛，下载速度和稳定性，说到底都是用户体验。开源也好，商业也罢，总得给用户一个靠谱的下载方式。

直接从云存储（比如 Azure Blob Storage、AWS S3）下文件，看起来简单，实际上问题还真不少：

网络延迟：跨国跨地域的访问，慢得让人想砸键盘。用户等得花儿都谢了，体验能好到哪去？

带宽成本：云存储的出口流量，贵得让人心疼。Azure Blob Storage 在中国大陆访问，差不多每 GB 0.5 元，一个月 1TB 就是 500 块。对于小团队来说，这笔钱说多不多，说少也不少，毕竟谁的钱都不是大风刮来的。

访问限制：某些地区访问国外云服务，时好时坏，有时候干脆就访问不了。用户想下都下不了，这事儿本身就挺无奈的。

CDN 成本：商业 CDN 确实能解决问题，但价格也确实美丽。小团队哪里用得起？

那有没有既省钱又好用的办法呢？其实也是有的。云服务器 + 反向代理 + 缓存层，就这么简单粗暴。成本降了一半左右，速度还提上去了，也算是一点小小的慰藉。

关于 HagiCode

这套方案也不是凭空想出来的，是我们在 HagiCode 项目里折腾出来的经验。

HagiCode 是一个 AI 代码助手，要给用户提供服务器端和桌面端的下载服务。既然是给开发者用的工具，全球用户都能快速稳定地下载，这事儿本身就很重要。这也是我们为什么非要琢磨出一套低成本方案的原因——毕竟谁的钱都不是大风刮来的。

如果你觉得这套方案还挺有价值的，那说明我们工程实力还算凑合…既然如此，HagiCode 本身也值得关注一下吧？

架构设计

整体架构思路

先来看一下整体的架构设计：

用户请求
    ↓
DNS 解析
    ↓
┌─────────────────────────────────────┐
│   反向代理层 (Traefik/Bunker Web)   │ ← SSL 终止、路由分发、安全防护
├─────────────────────────────────────┤
│   端口: 80/443                       │
│   功能: 自动 Let's Encrypt 证书      │
│         Host 路由                    │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│   缓存层 (Nginx)                     │ ← 文件缓存、Gzip 压缩
├─────────────────────────────────────┤
│   端口: 8080(server) / 8081(desktop) │
│   缓存策略:                          │
│   - index.json: 1 小时               │
│   - 其他文件: 7 天                   │
│   缓存大小: 1GB                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│   源站 (Azure Blob Storage)         │ ← 文件存储
└─────────────────────────────────────┘

这个架构的核心思想，说白了就是：在用户和云存储之间，加一层缓存罢了。

用户请求先到云服务器上的反向代理层，然后 Nginx 缓存层接手。缓存里有文件？直接给用户。没有？去云存储拉一份，顺便在本地存一份。下次再访问同一个文件，就不用麻烦云存储了。其实就像记忆一样，有些东西记住了，下次就不用再费劲去想…

为什么选择这个架构？

云服务器优势：

成本可控：阿里云等提供廉价云服务器（1-2 核 2GB 配置月费约 50-100 元）
部署灵活：可自由配置反向代理、缓存策略
地理位置灵活：可选择靠近用户的服务器区域
扩展性强：可根据流量需求升级配置

反向代理 + 缓存架构：

减少源站压力：缓存热点文件，减少对云存储的访问
降低成本：云服务器流量费用远低于云存储出口流量
提升速度：就近访问，服务器带宽通常优于云存储

为什么选择 Nginx 作为缓存层？

这事儿也不是随便选的，毕竟 Nginx 确实有它的道理：

高性能：Nginx 反向代理的性能，业界是有目共睹的
缓存成熟：内置的 proxy_cache 功能，稳定可靠，不会动不动就出幺蛾子
资源占用低：256MB 内存就能跑，对服务器也算友好
配置灵活：不同的文件类型可以设置不同的缓存策略，这点还是很贴心的

反向代理层：Traefik vs Bunker Web

HagiCode 的部署方案，其实支持两种反向代理，怎么说呢，各有各的特点：

方案	特点	适用场景
Traefik	轻量级、自动 SSL、配置简单	基础部署、低流量场景
Bunker Web	内置 WAF、防 DDoS、防爬虫	高安全要求、高流量场景

Traefik：轻量级首选

Traefik 是一个现代 HTTP 反向代理和负载均衡器，最大的特点就是配置简单，还能自动搞 Let’s Encrypt 证书。

对于初始部署或者流量不大的场景，Traefik 其实是挺不错的选择：

资源占用不多（1.5 CPU/512MB 内存就够了）
SSL 证书自动配置，不用自己操心
路由配置基于 Docker 标签，也算方便

Bunker Web：高安全场景

Bunker Web 是一个基于 Nginx 的 Web 应用防火墙，安全防护更全面一些。

什么时候可以考虑切换到 Bunker Web 呢？大概就是这些情况吧：

遭受 DDoS 攻击（虽然谁都不希望遇到）
需要 ModSecurity 防护
想要防爬虫功能
对安全有更高的要求

HagiCode 提供了 switch-deployment.sh 脚本，可以在两种方案之间快速切换：

# 切换到 Bunker Web
./switch-deployment.sh bunkerweb

# 切换回 Traefik
./switch-deployment.sh traefik

# 查看当前状态
./switch-deployment.sh status

脚本会自动做预检查、健康检查，还能自动回滚，切换过程也算安全可靠，不会说换着换着就挂了。

Nginx 缓存层配置

缓存层是整个架构的核心，Nginx 配置得好不好，缓存效果天差地别。毕竟这事儿还挺关键的。

缓存路径配置

# 缓存路径配置
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=azure_cache:10m
                   max_size=1g inactive=7d use_temp_path=off;

参数说明：

levels=1:2：缓存目录层级，2 级目录结构，提高文件访问效率
keys_zone=azure_cache:10m：缓存键存储区域，10MB 足够存储大量键
max_size=1g：最大缓存大小 1GB
inactive=7d：缓存文件 7 天未被访问则删除
use_temp_path=off：直接写入缓存目录，提高性能

分级缓存策略

不同类型的文件需要不同的缓存策略：

# Server 下载服务
server {
    listen 8080;

    # index.json 短期缓存（便于及时更新）
    location /index.json {
        proxy_cache azure_cache;
        proxy_cache_valid 200 1h;
        proxy_cache_key "$scheme$server_port$request_uri";
        add_header X-Cache-Status $upstream_cache_status;
        add_header Cache-Control "public, max-age=3600";

        # 反向代理到 Azure OSS
        proxy_pass https://${SERVER_DL_HOST}/${SERVER_DL_CONTAINER}$uri?${SERVER_DL_SAS_TOKEN};
        proxy_ssl_server_name on;
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
    }

    # 安装包等静态文件长期缓存
    location / {
        proxy_cache azure_cache;
        proxy_cache_valid 200 7d;
        proxy_cache_key "$scheme$server_port$request_uri";
        add_header X-Cache-Status $upstream_cache_status;
        add_header Cache-Control "public, max-age=604800";

        proxy_pass https://${SERVER_DL_HOST}/${SERVER_DL_CONTAINER}$uri?${SERVER_DL_SAS_TOKEN};
        proxy_ssl_server_name on;
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
    }
}

为什么这样设计？

index.json 是版本检查文件，得及时更新，所以缓存时间设成了 1 小时。这样发布新版本后，最多 1 小时用户就能检测到更新，也不算太久。

安装包这些静态文件，变化本来就少，缓存 7 天能大幅减少源站访问。需要更新的时候手动清理一下缓存就好了，也不算麻烦。

X-Cache-Status 响应头：

这个响应头能让你看看缓存命中情况怎么样，也挺有用的：

HIT：缓存命中
MISS：缓存未命中，从源站拉取
EXPIRED：缓存过期，重新从源站拉取
BYPASS：缓存被绕过

查看方法：

curl -I https://server.dl.hagicode.com/app.zip

成本分析

假设每月下载流量 1TB，我们来算算账：

方案	流量费用	服务器费用	合计
直接 Azure OSS	约 ¥500	¥0	¥500
云服务器 + OSS (缓存命中率 80%)	¥100 + ¥80	¥60	¥240
商业 CDN	¥300-500	¥0	¥300-500

结论：缓存层能省下大概 50% 的分发成本。

这个计算假设缓存命中率 80%，实际情况中，如果文件更新频率不高，命中率可能还会更高一些，毕竟这也是自然而然的事。

部署实践

环境准备

首先配置环境变量：

cd /path/to/hagicode_aliyun_deployment/docker
cp .env.example .env
vi .env  # 填入 Azure OSS SAS URL、Lark Webhook URL

重要：.env 文件包含敏感信息（SAS Token、Webhook URL），千万别提交到版本控制，这事儿还是挺关键的。

DNS 配置

添加以下 DNS A 记录，这步别忘了：

server.dl.hagicode.com → 服务器 IP
desktop.dl.hagicode.com → 服务器 IP

初始化服务器

使用 Ansible 自动化初始化服务器：

cd /path/to/hagicode_aliyun_deployment
ansible-playbook -i ./ansible/inventory/hosts.yml ./ansible/playbooks/init.yml

这个 Playbook 会自动搞定这些：

创建部署用户
安装 Docker 和 Docker Compose
配置 SSH 密钥
设置防火墙规则

也不算太复杂，毕竟自动化这东西，省时省力。

部署服务

./deploy.sh

部署脚本会帮你做这些：

检查环境配置
拉取最新代码
启动 Docker 容器
执行健康检查
发送部署通知（飞书）

一条命令搞定，也算方便。

验证部署

# 检查容器状态
docker ps

# 测试下载域名
curl -I https://server.dl.hagicode.com/index.json
curl -I https://desktop.dl.hagicode.com/index.json

运维技巧

缓存管理

缓存这东西，偶尔也得打理一下：

查看缓存磁盘使用：

docker volume inspect docker_nginx-cache
du -sh /var/lib/docker/volumes/docker_nginx-cache/_data

手动清除缓存：

./clear-cache.sh

或者手动执行，虽然麻烦一点，但也管用：

docker exec nginx sh -c "rm -rf /var/cache/nginx/*"
docker restart nginx

资源限制

在 1 核 2GB 服务器上，资源限制配置如下：

services:
  traefik:
    deploy:
      resources:
        limits:
          cpus: '1.50'
          memory: 512M

  nginx:
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 256M

监控资源使用情况，偶尔看看也挺好：

docker stats

SAS Token 安全实践

SAS Token 是访问 Azure Blob Storage 的凭证，泄露了可不是闹着玩的：

.env 文件不提交到版本控制（已在 .gitignore）
SAS Token 设置适当过期时间（推荐 1 年）
限制 SAS Token 权限（仅读取）
定期轮换 SAS Token

监控告警

HagiCode 集成了 Lark/飞书 Webhook 通知，可以在以下情况发送通知：

部署成功/失败
缓存清除状态
服务异常

通知包含服务器信息、时间戳、错误详情，快速定位问题也方便一些。

高可用扩展

当单台服务器撑不住的时候，也可以考虑：

水平扩展：部署多个节点，通过 DNS 轮询或负载均衡分发
CDN 加持：在云服务器前接入 CDN，进一步提升访问速度
缓存预热：使用脚本提前将热门文件加载到缓存

注意事项

有几点还是得提醒一下，毕竟谁都不想遇到幺蛾子：

SSL 证书：Let’s Encrypt 有速率限制，别频繁切换部署，不然可能申请不到证书
缓存清理：更新重要文件后记得清理缓存，不然用户可能下载不到新版本
日志管理：定期清理 Docker 日志，不然磁盘满了就麻烦了
备份策略：Traefik acme.json、Bunker Web 配置这些，还是备份一下比较好
监控告警：配置飞书通知，及时了解部署状态，出问题也能快速反应

总结

云服务器 + Nginx 缓存层，就这么简单。HagiCode 用这套方案，成本不算高（服务器费用大概 60-100 元/月），效果还挺不错的。核心优势大概也就这些：

成本可控：比直接用云存储或商业 CDN，成本降了大概 50%
部署灵活：Traefik 还是 Bunker Web，看你自己选
扩展性强：需要的话可以水平扩展，或者再加个 CDN
运维简单：Shell 脚本 + Ansible，自动化部署也方便

对于需要文件分发的小团队和个人开发者来说，这方案倒是可以试试。

HagiCode 用这套架构在生产环境稳定运行了一段时间，全球用户下载也没出什么大问题。如果你也在找类似的解决方案，不妨试试看，说不定对你也有帮助。

技术栈总结

最后整理一下用到的技术，也算有个交代：

组件	选型	用途
云服务器	阿里云 ECS	基础运行环境
反向代理	Traefik / Bunker Web	SSL 终止、路由、安全防护
缓存层	Nginx	反向代理缓存、Gzip 压缩
文件存储	Azure Blob Storage	文件源站
容器化	Docker Compose	服务编排
自动化	Ansible	服务器配置管理
通知	Lark/飞书 Webhook	部署状态通知

参考资料

最后还是给些参考资料吧，也算有个着落：

HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose 一键安装：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/

如果本文对你有帮助，那也算是值得了：

点个赞让更多人看到
来 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-04-15-low-cost-cloud-server-download-distribution-station/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

Hermes Agent 集成实践：从协议到生产

2026年4月14日

Hermes Agent 集成实践：从协议到生产

分享 HagiCode 集成 Hermes Agent 的完整实践，包括 ACP 协议适配、会话池管理、前后端契约同步等核心经验。

背景

在构建 AI 辅助编码平台 HagiCode 的过程中，团队需要集成一个既能在本地运行又能扩展到云端的 Agent 框架。经过调研，Nous Research 的 Hermes Agent 被选为综合 Agent 的底层引擎。

其实选型这事儿，说难也不难，说简单也不简单。毕竟市面上能打的 Agent 框架也不少，只是 Hermes 那个 ACP 协议和工具系统确实有点东西，刚好契合 HagiCode “既要又要”的需求场景——本地开发、团队协作和云端扩展。但要把 Hermes 真正融入生产系统，还需要解决一系列工程问题，这可不是闹着玩的。

HagiCode 的技术栈基于 Orleans 构建分布式系统，前端使用 React + TypeScript。集成 Hermes 需要在保持现有架构统一性的前提下，让 Hermes 成为与 ClaudeCode、OpenCode 等并行的”一等公民”执行器。说起来容易，做起来嘛，也就那样吧。

本文分享我们在 HagiCode 项目中集成 Hermes Agent 的实践经验，希望能给面临类似需求的团队提供参考。毕竟，踩过的坑，没必要让别人再踩一遍。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 驱动的编码辅助平台，支持多种 AI Provider 的统一接入和管理。在集成 Hermes Agent 的过程中，我们设计了一套通用的 Provider 抽象层，使得新的 Agent 类型可以无缝接入现有系统。

如果你对 HagiCode 感兴趣，欢迎访问 GitHub 了解更多。多个人看，多份力量罢了。

架构设计

分层设计思路

HagiCode 的 Hermes 集成采用了清晰的分层架构，每层各司其职：

后端核心层

HermesCliProvider: 实现 IAIProvider 接口，作为统一的 AI Provider 入口
HermesPlatformConfiguration: 管理 Hermes 可执行文件路径、参数、认证等配置
ICliProvider<HermesOptions>: HagiCode.Libs 提供的底层 CLI 抽象，处理子进程生命周期

传输层

StdioAcpTransport: 通过标准输入输出与 Hermes ACP 子进程通信
ACP 协议方法：initialize、authenticate、session/new、session/prompt

运行时层

HermesGrain: Orleans Grain 实现，处理分布式会话执行
CliAcpSessionPool: 会话池，复用 ACP 子进程，避免频繁启动开销

前端层

ExecutorAvatar: Hermes 视觉标识和图标
executorTypeAdapter: Provider 类型映射逻辑
SignalR 实时消息传递：保持 Hermes 身份在消息流中的一致性

这种分层设计使得各层可以独立演进，比如未来要添加新的传输方式（如 WebSocket），只需修改传输层即可。毕竟，谁愿意因为改一个传输方式就把整个系统都翻一遍呢？多累啊。

统一接口抽象

所有 AI Provider 都实现 IAIProvider 接口，这是 HagiCode 架构的核心设计：

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

    IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        CancellationToken cancellationToken = default);

    Task<AIResponse> ExecuteAsync(
        AIRequest request,
        CancellationToken cancellationToken = default);
}

HermesCliProvider 实现了这个接口，与 ClaudeCodeProvider、OpenCodeProvider 等处于平等地位。这种设计带来的好处：

可替换性: 切换 Provider 不影响上层业务逻辑
可测试性: 可以轻松 Mock Provider 进行单元测试
可扩展性: 新增 Provider 只需实现接口即可

说到底，接口这东西，就像规矩一样。有了规矩，大家才能和谐共处，各自发挥所长，互不干扰。这难道不是一种美吗？

核心实现

Provider 层实现

HermesCliProvider 是整个集成的核心，它负责协调各个组件完成一次 AI 调用：

public sealed class HermesCliProvider : IAIProvider, IVersionedAIProvider
{
    private readonly ICliProvider<LibsHermesOptions> _provider;
    private readonly ConcurrentDictionary<string, string> _sessionBindings;

    public ProviderCapabilities Capabilities { get; } = new()
    {
        SupportsStreaming = true,
        SupportsTools = true,
        SupportsSystemMessages = true,
        SupportsArtifacts = false
    };

    public async IAsyncEnumerable<AIStreamingChunk> StreamAsync(
        AIRequest request,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        // 1. 解析会话绑定 key
        var bindingKey = ResolveBindingKey(request.CessionId);

        // 2. 通过会话池获取或创建 Hermes 会话
        var options = new HermesOptions
        {
            ExecutablePath = _platformConfiguration.ExecutablePath,
            Arguments = _platformConfiguration.Arguments,
            SessionId = _sessionBindings.TryGetValue(bindingKey, out var sessionId) ? sessionId : null,
            WorkingDirectory = request.WorkingDirectory,
            Model = request.Model
        };

        // 3. 执行并收集流式响应
        await foreach (var message in _provider.ExecuteAsync(options, request.Prompt, cancellationToken))
        {
            // 4. 映射 ACP 消息到 AIStreamingChunk
            if (_responseMapper.TryConvertToStreamingChunk(message, out var chunk))
            {
                yield return chunk;
            }
        }
    }
}

这里有几个关键设计点：

会话绑定: 通过 CessionId 将多个请求绑定到同一个 Hermes 子进程，实现多轮对话的上下文连续性
响应映射: 将 Hermes ACP 消息格式转换为统一的 AIStreamingChunk 格式
流式处理: 使用 IAsyncEnumerable 支持真正的流式响应

其实会话绑定这事儿，就像人和人之间的关系一样。一旦建立了联系，后续的交流就有了上下文，不用每次都从头开始。只是这关系要维护好，不然断了就断了。

ACP 协议适配

Hermes 使用 ACP（Agent Communication Protocol）协议，与传统的 HTTP API 不同。ACP 是基于标准输入输出的协议，有几个特点：

启动标记: Hermes 进程启动后会输出 //ready 标记
动态认证: 认证方法不是固定的，需要通过协议协商
会话复用: 通过 SessionId 复用已建立的会话
响应分散: 完整响应可能分散在多个 session/update 通知中

HagiCode 通过 StdioAcpTransport 处理这些特性：

public class StdioAcpTransport
{
    public async Task InitializeAsync(CancellationToken cancellationToken)
    {
        // 等待 //ready 标记
        var readyLine = await _outputReader.ReadLineAsync(cancellationToken);
        if (readyLine != "//ready")
        {
            throw new InvalidOperationException("Hermes did not send ready signal");
        }

        // 发送 initialize 请求
        await SendRequestAsync(new
        {
            jsonrpc = "2.0",
            id = 1,
            method = "initialize",
            @params = new
            {
                protocolVersion = "2024-11-05",
                capabilities = new { },
                clientInfo = new { name = "HagiCode", version = "1.0.0" }
            }
        }, cancellationToken);
    }
}

协议这东西，就像人与人之间的默契。有了默契，交流就会顺畅很多。只是建立默契需要时间，磨合嘛，谁都免不了。

会话池管理

频繁启动 Hermes 子进程的开销很大，因此我们实现了会话池机制：

services.AddSingleton(static _ =>
{
    var registry = new CliProviderPoolConfigurationRegistry();
    registry.Register("hermes", new CliPoolSettings
    {
        MaxActiveSessions = 50,
        IdleTimeout = TimeSpan.FromMinutes(10)
    });
    return registry;
});

会话池的关键参数：

MaxActiveSessions: 控制并发上限，避免资源耗尽
IdleTimeout: 空闲超时，平衡启动成本和内存占用

实践中我们发现：

空闲超时设置太短会导致频繁重启，设置太长会占用内存
并发上限需要根据实际负载调整，过大可能导致系统卡顿
需要监控会话池的使用情况，以便及时调整参数

这就好比人生中的许多选择，太激进容易出问题，太保守又错失机会。找个平衡点罢了。

前端集成

类型映射

前端需要正确识别 Hermes Provider 并显示对应的视觉元素：

export const resolveExecutorVisualTypeFromProviderType = (
  providerType: PCode_Models_AIProviderType | null | undefined
): ExecutorVisualType => {
  switch (providerType) {
    case PCode_Models_AIProviderType.HERMES_CLI:
      return 'Hermes';
    default:
      return 'Unknown';
  }
};

视觉呈现

Hermes 有专属的图标和颜色标识：

const renderExecutorGlyph = (executorType: ExecutorVisualType, iconSize: number) => {
  switch (executorType) {
    case 'Hermes':
      return (
        <svg viewBox="0 0 24 24" fill="none" className="h-4 w-4">
          <rect x="4" y="4" width="16" height="16" rx="4" fill="currentColor" opacity="0.16" />
          <path d="M8 7v10M16 7v10M8 12h8" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
        </svg>
      );
    default:
      return <DefaultAvatar />;
  }
};

毕竟，美的东西也要有美的呈现。只是这美要被人看见，还得靠前端同学的努力。

契约同步

前后端通过 OpenAPI 生成保持契约一致。后端定义了 AIProviderType 枚举：

public enum AIProviderType
{
    Unknown,
    ClaudeCode,
    OpenCode,
    HermesCli  // 新增
}

前端通过 OpenAPI 生成对应的 TypeScript 类型，确保枚举值一致。这是避免前端显示 “Unknown” 的关键。

契约这东西，就像承诺一样。说好了就要做到，不然就会出现”Unknown”这种尴尬的局面。

配置管理

Hermes 的配置通过 appsettings.json 管理：

{
  "Providers": {
    "HermesCli": {
      "ExecutablePath": "hermes",
      "Arguments": "acp",
      "StartupTimeoutMs": 10000,
      "ClientName": "HagiCode",
      "Authentication": {
        "PreferredMethodId": "api-key",
        "MethodInfo": {
          "api-key": "your-api-key-here"
        }
      },
      "SessionDefaults": {
        "Model": "claude-sonnet-4-20250514",
        "ModeId": "default"
      }
    }
  }
}

这种配置驱动的设计带来了灵活性：

可以覆盖可执行文件路径，方便开发测试
可以自定义启动参数，适配不同版本的 Hermes
可以配置认证信息，支持多种认证方式

配置这东西，就像人生的选择题。给足了选项，总能找到适合自己的那一个。只是有时候选项太多，也会让人犯选择困难症。

实践经验

健康检查

实现一个可靠的 Provider 需要完善的健康检查：

public async Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default)
{
    var response = await ExecuteAsync(new AIRequest
    {
        Prompt = "Reply with exactly PONG.",
        CessionId = null,
        AllowedTools = Array.Empty<string>(),
        WorkingDirectory = ResolveWorkingDirectory(null)
    }, cancellationToken);

    var success = string.Equals(response.Content.Trim(), "PONG", StringComparison.OrdinalIgnoreCase);
    return new ProviderTestResult
    {
        ProviderName = Name,
        Success = success,
        ResponseTimeMs = stopwatch.ElapsedMilliseconds,
        ErrorMessage = success ? null : $"Unexpected Hermes ping response: '{response.Content}'."
    };
}

健康检查需要注意：

使用简单的测试用例，避免复杂场景
设置合理的超时时间
记录响应时间，便于性能分析

就像人需要体检一样，系统也需要健康检查。早发现早治疗，省得到时候出大问题。

验证工具

HagiCode 提供专用控制台用于验证 Hermes 集成：

# 基础验证
HagiCode.Libs.Hermes.Console --test-provider

# 完整套件（含仓库分析）
HagiCode.Libs.Hermes.Console --test-provider-full --repo .

# 自定义可执行文件
HagiCode.Libs.Hermes.Console --test-provider-full --executable /path/to/hermes

这个工具在开发过程中非常有用，可以快速验证集成是否正确。毕竟，谁愿意在发现问题的时候才想起来去测试呢？

常见问题处理

认证失败

检查 Authentication.PreferredMethodId 与 Hermes 实际支持的认证方法是否匹配
确认认证信息格式正确（API Key、Bearer Token 等）

会话超时

增加 StartupTimeoutMs 值
检查 MCP 服务器可达性
查看系统资源使用情况

响应不完整

确保正确聚合 session/update 通知和最终结果
检查流式处理的取消逻辑
验证错误处理是否完整

前端显示 Unknown

确认 OpenAPI 生成已包含 HermesCli 枚举值
检查类型映射是否正确
清除浏览器缓存重新生成类型

问题嘛，总会有的。只是遇到问题的时候，别慌，慢慢找原因，总能解决的。毕竟，办法总比困难多。

性能优化建议

使用会话池: 复用 ACP 子进程，减少启动开销
合理设置超时: 平衡内存和启动成本
复用会话 ID: 批量任务使用同一个 CessionId
按需配置 MCP: 避免不必要的工具调用

性能这东西，就像生活中的效率。做对了，事半功倍；做错了，事倍功半。只是找到那个”对”的点，需要经验和运气。

总结

集成 Hermes Agent 到生产系统需要考虑多个层面的问题：

架构层面: 设计统一的 Provider 接口，实现可替换的组件架构
协议层面: 正确处理 ACP 协议的特殊性，如启动标记、动态认证等
性能层面: 通过会话池复用资源，平衡启动成本和内存占用
前端层面: 确保契约同步，提供一致的视觉体验

HagiCode 的实践表明，通过良好的分层设计和配置驱动，可以将复杂的 Agent 系统无缝集成到现有架构中。

其实这些道理说起来都挺简单的，只是真正做起来的时候，总会遇到各种各样的问题。不过没关系，问题解决了就是经验，解决不了就是教训，都是有价值的东西。

美的事物或人，不一定要占有，只要她还是美的，自己好好看着她的美就好了。技术也是如此，只要能让系统变得更好，用什么框架、什么协议，其实都没那么重要…

参考资料

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-14-hermes-agent-integration-practice/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

VSCode 与 code-server：浏览器端代码编辑方案选型

2026年4月13日

VSCode 与 code-server：浏览器端代码编辑方案选型

在构建浏览器端的代码编辑能力时，开发者面临一个关键选择：使用 VSCode 官方的 code serve-web 功能，还是采用社区驱动的 code-server 方案？这个选择不仅影响技术架构，还关系到许可证合规性和部署灵活性。

背景

其实做技术选型这事儿，跟选择人生道路有点像。你选了一条路，就得一直走下去，想换路的时候，成本可就大了。

在 AI 辅助编程的时代，浏览器端的代码编辑能力变得越来越重要。用户期望在 AI 助手分析完代码后，能够立即在同一个浏览器会话中打开编辑器进行修改，无需切换应用。这种无缝的体验，怎么说呢，就像你想的时候，它就在那里——只是有时候它偏偏不在。

然而，在实现这个功能时，开发者面临一个关键的技术选型：是使用 VSCode 官方的 code serve-web 功能，还是采用社区驱动的 code-server 方案？

这两个方案各有优劣，选择错了可能会在后期带来不少麻烦。比如许可证问题——等到产品上线了才发现许可证不合规，那可就晚了。这跟谈恋爱有点像，一开始没想清楚，到头来才发现两个人的价值观根本不合，那付出的代价就大了。再比如部署方式——某个方案在开发环境跑得好好的，一上容器就各种问题，这种坑谁也不想踩，毕竟踩坑踩多了，人也就麻了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 驱动的代码助手，在实现浏览器端代码编辑能力时，我们深入研究了这两个方案，最终在架构设计中同时支持两者，但默认优先选择 code-server。

项目地址：github.com/HagiCode-org/site

许可证差异（最关键）

这是两个方案最根本的区别，也是我们在选型时最先考虑的因素。毕竟选型这事儿，第一步就要想清楚法律风险，不然以后出事了，怪谁呢？

code-server

MIT 许可证，完全开源
由 Coder.com 公司维护，社区活跃
可以自由商用、修改和分发
无使用场景限制

VSCode code serve-web

属于 Microsoft VSCode 产品的一部分
使用 Microsoft 的许可证（VS Code 的许可证有商业使用限制）
主要面向个人开发者使用
企业级部署可能需要额外的商业授权考虑

从许可证角度看，code-server 对商业项目更友好。这一点在产品规划阶段就要想清楚，不然等到规模上来了再去迁移，那成本可就大了。毕竟迁移这事儿，说起来容易，做起来难，谁经历过谁知道。

部署方式差异

许可证问题解决后，接下来就是部署方式。这直接影响到你的运维成本和架构设计，也间接影响着你每天的心情——部署越简单，心情越好，这道理大家都懂。

code-server

独立的 Node.js 应用，可单独部署
支持多种运行时来源：
- 直接指定可执行文件路径
- 系统 PATH 查找
- NVM Node.js 22.x 环境自动检测
服务器上无需安装 VSCode 桌面版
容器化部署更简单

VSCode code serve-web

必须依赖本地安装的 VSCode CLI
需要本机有可用的 code 命令
系统会过滤掉 VS Code Remote CLI 包装器
主要设计用于本地开发场景

code-server 更适合服务器/容器部署场景。如果你的产品需要跑在 Docker 里，或者用户环境没有 VSCode，那选 code-server 就对了。毕竟简单就是美，复杂了容易出问题，出了问题还得修，修完了还可能引入新问题，这无穷无尽的循环，谁愿意经历呢？

功能参数差异

两个方案在功能参数上也有一些差异，虽然不大，但在实际使用中可能会带来一些麻烦。这些细节就像生活中的小摩擦，不多，但多了就让人烦。

特性	code-server	code serve-web
公开基路径	`/` (可配置)	`/vscode-server` (固定)
认证方式	`--auth` 参数，支持多种模式	`--connection-token` / `--without-connection-token`
数据目录	`{DataDir}/code-server`	`{DataDir}/vscode-serve-web`
遥测	默认禁用 `--disable-telemetry`	依赖 VSCode 设置
更新检查	可禁用 `--disable-update-check`	依赖 VSCode 设置

这些差异在集成时需要特别注意。比如 URL 路径的不同，意味着前端代码需要做针对性处理。做开发的都知道，这种细节处理起来最费时间，但也没办法，不做就跑不通。

可用性检测差异

在实现编辑器切换功能时，可用性检测的逻辑也有所不同。这种差异就像人与人之间的相处方式，有的人喜欢直来直去，有的人喜欢含蓄委婉。

code-server

始终作为可见实现返回
即使不可用也会显示，提示 install-required 状态
支持自动检测 NVM Node.js 22.x 环境

code serve-web

只有检测到本机 code CLI 时才可见
如果不可用，前端会自动隐藏此选项
依赖本地 VSCode 安装状态

这种差异直接影响用户体验。code-server 的方式更透明，用户知道有这个选项，只是还没安装；code serve-web 的方式更隐蔽，用户可能都不知道还有这个选择。哪种方式更好？这得看产品定位了，毕竟用户体验这事儿，没有标准答案，只有合适不合适。

HagiCode 的双实现架构

经过深入分析，HagiCode 项目采用了双实现架构，在架构层面同时支持两种方案。这倒不是我们技术选型困难症，而是真的有实际需求。毕竟在技术世界里，没有什么绝对正确的选择，只有最适合自己的选择。

默认选择 code-server

// 默认活动实现是 code-server
// 如果保存了显式的 activeImplementation，优先尝试该实现
// 如果所请求实现不可用，解析器会尝试另一个实现
// 如果发生回退，返回 fallbackReason

我们默认选择 code-server，主要考虑是许可证和部署灵活性。但对于有本地 VSCode 环境的用户，code serve-web 也是一个不错的选择。毕竟给用户多一种选择，总归是好的，强迫别人接受单一方案，这事儿我干不出来。

实现选择器

CodeServerImplementationResolver 统一负责：

启动预热时的实现选择
状态读取时的实现选择
项目打开时的实现选择
Vault 打开时的实现选择

这种设计让系统可以灵活应对不同场景，用户可以根据自己的环境选择最合适的实现。灵活设计这事儿，前期花的时间多一点，但后期省心，毕竟谁也不想到处改代码。

前端适配规则

// localCodeAvailable=false 时，不显示 code serve-web
// localCodeAvailable=true 时，显示 code serve-web 配置

前端根据环境自动显示可用选项，避免用户看到无法使用的功能而困惑。用户困惑了，就来问你，问多了你也烦，烦多了就想改代码，改代码又可能引入 bug，这恶性循环，谁爱经历谁经历。

实践指南

说了这么多理论，实际部署时要注意什么呢？其实理论说得再好，落地不行也没用，毕竟实践是检验真理的唯一标准。

Docker 部署建议

对于容器化部署，code-server 是更优选择：

# 直接使用 code-server 官方镜像
FROM codercom/code-server:latest

# 或者通过 npm 安装
RUN npm install -g code-server

这样一层就搞定，不需要额外安装 VSCode。简单就是好，复杂了容易出错，这道理放哪儿都适用。

配置示例

code-server 配置

{
  "vscodeServer": {
    "enabled": true,
    "activeImplementation": "code-server",
    "codeServer": {
      "host": "0.0.0.0",
      "port": 8080,
      "executablePath": "",
      "authMode": "none"
    }
  }
}

code serve-web 配置

{
  "vscodeServer": {
    "enabled": true,
    "activeImplementation": "serve-web",
    "serveWeb": {
      "host": "0.0.0.0",
      "port": 8080,
      "executablePath": "/usr/local/bin/code"
    }
  }
}

配置这事儿，第一次麻烦点，配好了后面就省心了。就像生活一样，前期投入多一点，后面日子就好过一点。

URL 构建差异

code-server

http://localhost:8080/?folder=/path/to/project&vscode-lang=zh-CN

code serve-web

http://localhost:8080/vscode-server/?folder=/path/to/project&tkn=xxx&vscode-lang=zh-CN

注意路径和参数的差异，集成时需要分别处理。细节决定成败，这话一点都不假，少一个参数，可能就打不开页面。

切换实现

系统支持运行时切换，切换时会自动停止旧实现：

// VsCodeServerManager 自动处理互斥
// 切换 activeImplementation 时，旧实现不会继续后台保活

这种设计让用户可以随时尝试不同实现，找到最适合自己的方案。毕竟适合自己的才是最好的，别人的建议仅供参考，最终还得自己试。

状态监控

const { settings, runtime } = await getVsCodeServerSettings();

// runtime.activeImplementation: "code-server" | "serve-web"
// runtime.fallbackReason: 切换原因
// runtime.status: "running" | "starting" | "stopped" | "unhealthy"

状态可见，心里才有数。用户在遇到问题时可以快速定位是服务端问题还是自己操作问题。不知道状态的时候，人就容易慌，慌了就容易做出错误判断，这链条一旦启动，就停不下来了。

总结

对比维度	code-server	code serve-web	推荐
许可证	MIT（商用友好）	Microsoft（有限制）	code-server
部署灵活性	独立部署	依赖本地 VSCode	code-server
服务器适用性	专为服务器设计	主要面向本地开发	code-server
容器化	原生支持	需要安装 VSCode	code-server
功能完整性	接近桌面版	官方完整版	code serve-web
维护活跃度	社区活跃	Microsoft 官方	各有优势

推荐策略：优先使用 code-server，在需要完整官方功能且具备本地 VSCode 环境时考虑 code serve-web。

本文分享的方案是 HagiCode 在实际开发中总结出来的。如果你觉得这套方案有价值，说明我们的工程实践还不错——那么 HagiCode 本身也值得关注一下。毕竟分享这事儿，有来有往才有趣，只有输出没有输入，总归不是长久之计。

参考资料

HagiCode GitHub：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
code-server 官网：coder.com/code-server
VSCode 官方文档：code.visualstudio.com/docs

如果本文对你有帮助：

来 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-04-13-vscode-web-integration-browser-editing/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

如何安装和使用 Hermes：从本地 CLI 到 Feishu 接入快速上手

2026年4月13日

想安装并开始使用 Hermes，最短路径其实只有三步：

运行官方安装命令
在终端里用 hermes 启动 CLI
如果你想在飞书里继续用，再配置 hermes gateway setup

这篇文章不打算把 Hermes 的所有能力一次讲完，而是先帮你完成最关键的入门闭环：装上、跑起来、开始用，然后再接一个最常见的消息平台场景。

Hermes 是什么，适合谁用

Hermes Agent 是一个既可以在本地终端使用，也可以通过消息平台网关使用的 AI agent。

对大多数开发者来说，它有两个最常见的入口：

CLI：在终端里输入 hermes，直接进入交互式界面
Messaging Gateway：运行 hermes gateway，再从 Feishu、Telegram、Discord、Slack 等平台和它对话

如果你现在的目标只是快速上手，建议顺序不要反过来，先走这条路线：

先安装 Hermes
先从 CLI 验证是否可用
再决定要不要接消息平台

这样更容易定位问题，也更适合第一次接触 Hermes 的用户。

安装 Hermes 之前要知道什么

根据 Hermes README，官方快速安装路径支持这些环境：

Linux
macOS
WSL2
Android via Termux

Windows 用户注意事项

Hermes 当前不支持原生 Windows 直接运行。如果你使用 Windows，推荐先安装 WSL2，再在 WSL2 里执行安装命令。

这点最好在文章开头就说清楚，因为很多安装失败其实不是命令问题，而是运行环境不符合要求。

如何安装 Hermes

Hermes README 给出的快速安装命令是：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

这条命令会执行官方安装脚本，处理平台相关的初始化流程。

安装完成后刷新 shell

安装结束后，先重新加载 shell 环境。最常见的是：

source ~/.bashrc

如果你用的是 zsh，也可以改成：

source ~/.zshrc

如何确认 Hermes 已经装好

最直接的检查方式就是运行：

hermes

如果你想进一步确认配置和依赖是否正常，可以再执行：

hermes doctor

hermes doctor 适合在这些时候使用：

安装后命令行为不正常
模型配置失败
gateway 启动失败
不确定环境依赖是否完整

第一次如何开始使用 Hermes

先从 CLI 开始

如果你只是想尽快确认 Hermes 能不能用，最简单的方法就是：

hermes

这会启动 Hermes 的交互式 CLI。对于第一次接触 Hermes 的用户，这也是最推荐的起点，因为你可以先验证最核心的几件事：

命令是否真的可用
当前模型配置是否正常
终端工具链是否工作正常
交互体验是不是你需要的那种方式

这几个命令足够你完成第一轮配置

Hermes README 里列出的几条高频命令，基本就构成了第一轮上手路径：

hermes model
hermes tools
hermes config set
hermes setup
hermes update
hermes doctor

如果你不知道它们各自是做什么的，可以先这样记：

hermes model：选模型、切模型
hermes tools：看和配当前可用工具
hermes config set：改具体配置项
hermes setup：跑一次完整初始化向导
hermes update：更新 Hermes
hermes doctor：做故障排查

对新手最实用的顺序通常是：

先运行 hermes model
如果你希望一次把常用项配完整，再运行 hermes setup

Hermes 最常见的两种使用方式

1. 在终端里把 Hermes 当成日常开发助手

CLI 模式适合这些场景：

本地写代码时直接问问题
查项目、改文件、跑命令
做一次性调试或 review
在当前工作目录里持续协作

它最大的优点就是路径最短：不用额外接平台，不用先处理机器人配置，也最适合建立第一轮使用习惯。

2. 通过消息平台使用 Hermes

如果你希望在飞书、Telegram、Discord 等平台上和 Hermes 对话，就需要使用 messaging gateway。

最常见的入口命令是：

hermes gateway setup
hermes gateway

其中：

hermes gateway setup 用来做交互式平台配置
hermes gateway 用来启动网关进程

根据官方文档，gateway 是一个统一的后台进程，用来连接你已配置的平台、管理会话，并处理定时任务等功能。

以 Feishu 为例，如何把 Hermes 接入消息平台

如果你的日常工作主要在飞书里，那么 Feishu/Lark 会是一个很自然的 Hermes 接入方式。

最小可行接入方式

官方文档对 Feishu/Lark 的推荐入口是：

hermes gateway setup

运行后，在向导中选择 Feishu / Lark 即可。

Feishu 文档给出的两种连接模式是：

websocket：推荐
webhook：可选

如果 Hermes 跑在你的笔记本、工作站或者私有服务器上，优先使用 websocket 会更简单，因为不需要额外暴露公网回调地址。

如果你手动配置，至少要知道这些变量

如果你不是通过向导配置，而是手动写配置，Feishu 文档里列出的核心变量包括：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=***
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

其中最值得注意的是两项：

FEISHU_ALLOWED_USERS：建议配置，避免任何能接触到 bot 的人都可以直接使用它
FEISHU_HOME_CHANNEL：可以预先指定一个 home chat，用来接收 cron 结果或默认通知

Feishu 群聊里为什么有时不回复

这一点很容易被忽略：在 Feishu 群聊里，Hermes 默认不是看到每条消息都响应。

官方文档明确说明：

私聊时，Hermes 会响应消息
群聊里，必须显式 @ bot，它才会处理消息

如果你想把某个飞书会话设成 home channel，也可以在聊天里使用：

/set-home

或者提前在配置里写：

FEISHU_HOME_CHANNEL=oc_xxx

新手最值得先记住的 Hermes 命令

不管你是在 CLI 里，还是在消息平台里，先记住下面这些命令就已经够用了：

/new 或 /reset：开始新会话
/model：查看或切换模型
/retry：重试上一轮
/undo：撤销上一轮交互
/compress：手动压缩上下文
/help：查看帮助

如果你主要在消息平台里使用，再额外记住一个：

/sethome 或 /set-home：把当前聊天设为 home channel

这些命令覆盖了新手阶段最常见的操作：重开、调整、回退、查看和继续用。

常见问题

Windows 能直接安装 Hermes 吗？

不能。当前官方文档明确说明，原生 Windows 不支持，推荐使用 WSL2。

安装之后输入 `hermes` 没反应怎么办？

建议按下面顺序排查：

先重新加载 shell，例如 source ~/.bashrc
再重新运行 hermes
如果还是异常，执行 hermes doctor

Feishu 群里为什么 bot 不回复？

先检查这三项：

你有没有在群里 @ Hermes
FEISHU_ALLOWED_USERS 是否限制了当前用户
当前群聊策略是否允许处理群消息

根据官方 Feishu 文档，群聊场景里，显式 @mention 是必要条件。

下一步建议

如果你只是想尽快开始使用 Hermes，最推荐的顺序是：

先执行安装命令
先用 hermes 在本地 CLI 里开始
再用 hermes model 和 hermes setup 补齐基础配置
如果你希望在飞书里继续使用，再配置 hermes gateway setup

如果这篇文章作为一个系列的第一篇，它最适合承担的角色不是“把所有高级功能一次讲完”，而是先把用户带进门。

后续更适合继续拆分成这些主题：

Hermes Feishu 接入完整指南
Hermes 常用 slash commands 指南
Hermes gateway 配置与排错指南

如果你准备继续做 Hermes 内容，这篇就可以作为后续文章的起点，并逐步把内部链接体系补起来。

在浏览器中快速编辑代码：VSCode Web 集成实践

2026年4月12日

在浏览器中快速编辑代码：VSCode Web 集成实践

AI 分析完代码后，如何立即在浏览器中打开编辑器进行修改？本文分享 HagiCode 项目中集成 code-server 的实践经验，实现 AI 助手与代码编辑体验的无缝连接。

背景

在 AI 辅助编程的时代，开发者经常需要快速查看和编辑代码。传统的开发流程是：在桌面端 IDE 中打开项目，定位文件，编辑，保存。只是这个流程在某些场景下，总觉得哪里不太对劲。

场景一：远程开发。当使用 HagiCode 这样的 AI 助手时，后端可能运行在远程服务器或容器中，本地无法直接访问项目文件。每次要查看或修改代码，都需要通过 SSH 或其他方式连接，体验割裂。这感觉就像你想见一个人，却隔着一层厚厚的玻璃，能看见却摸不着。

场景二：快速预览。AI 助手分析代码后，用户可能只是想快速浏览某个文件或做小幅修改。启动完整的桌面 IDE 显得重量级，浏览器内的轻量级编辑器更符合”快速查看”的需求。毕竟，谁愿意为了看一眼就大动干戈呢？

场景三：跨设备协作。在不同设备上工作时，浏览器中的编辑器提供了统一的访问入口，无需每台设备都配置开发环境。这倒也省事，毕竟人生苦短，何必重复劳动。

为了解决这些痛点，我们在 HagiCode 项目中集成了 VSCode Web。让 AI 助手与代码编辑体验无缝连接——AI 分析完代码后，用户可以立即在同一个浏览器会话中打开编辑器进行修改，无需切换应用。这种体验，怎么说呢，就像你想的时候，它就在那里。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 驱动的代码助手，旨在通过自然语言交互提升开发效率。在开发过程中，我们发现用户经常需要在 AI 分析和代码编辑之间快速切换，这促使我们探索如何将编辑器直接集成到浏览器中。

项目地址：github.com/HagiCode-org/site

技术选型：为什么是 code-server？

在众多 VSCode Web 解决方案中，我们选择了 code-server。这个选择，其实也有几个考量：

功能完整。code-server 是 VSCode 的 Web 版本，支持桌面版的大部分功能，包括扩展系统、智能提示、调试等。这意味着用户在浏览器中也能获得接近桌面版的编辑体验。毕竟，谁又愿意在功能上妥协呢？

部署灵活。code-server 可以作为独立服务运行，也支持 Docker 容器化部署，与 HagiCode 的架构契合。我们的后端用 C# 编写，前端是 React，通过 REST API 与 code-server 服务通信。这就像搭积木，每块都有自己的位置。

认证安全。code-server 内置 connection-token 机制，防止未授权访问。每个会话都有唯一的 token，确保只有授权用户才能访问编辑器。安全感这东西，有了才知道重要。

架构设计

HagiCode 的 VSCode Web 集成采用前后端分离的架构设计。

前端服务层

前端通过 vscodeServerService.ts 封装了与后端的交互：

// 打开项目
export async function openProjectInCodeServer(
  id: string,
  currentInterfaceLanguage?: string,
): Promise<VsCodeServerLaunchResponseDto>

// 打开 vault
export async function openVaultInCodeServer(
  id: string,
  path?: string,
  currentInterfaceLanguage?: string,
): Promise<VsCodeServerLaunchResponseDto>

这两个方法的区别在于：openProjectInCodeServer 用于打开整个项目，而 openVaultInCodeServer 用于打开 Vault 的特定路径。对于 MonoSpecs 多仓库项目，系统会自动创建工作区文件。分工明确，各自做好自己的事，这就够了。

后端服务层

后端的 VaultAppService.cs 实现了核心逻辑：

public async Task<VsCodeServerLaunchResponseDto> OpenInCodeServerAsync(
    string id,
    string? relativePath = null,
    string? currentInterfaceLanguage = null,
    CancellationToken cancellationToken = default)
{
    // 1. 获取设置并检查是否启用
    var settings = await _vsCodeServerSettingsService.GetResolvedSettingsAsync(cancellationToken);
    if (!settings.Enabled) {
        throw new BusinessException(VsCodeServerErrorCodes.Disabled, "VSCode Server is disabled.");
    }

    // 2. 获取 vault 并解析启动目录
    var vault = await RequireVaultAsync(id, cancellationToken);
    var launchDirectory = ResolveLaunchDirectory(vault, relativePath);

    // 3. 确保 code-server 运行并获取运行时信息
    var runtime = await _vsCodeServerManager.EnsureStartedAsync(settings, cancellationToken);

    // 4. 解析语言设置
    var language = _vsCodeServerSettingsService.ResolveLaunchLanguage(
        settings.Language,
        currentInterfaceLanguage);

    // 5. 构建启动 URL
    return new VsCodeServerLaunchResponseDto {
        LaunchUrl = AppendQueryString(runtime.BaseUrl, new Dictionary<string, string?> {
            ["folder"] = launchDirectory,
            ["tkn"] = runtime.ConnectionToken,
            ["vscode-lang"] = language,
        }),
        ConnectionToken = runtime.ConnectionToken,
        OpenMode = "folder",
        Runtime = VsCodeServerSettingsService.MapRuntime(
            await _vsCodeServerManager.GetRuntimeSnapshotAsync(cancellationToken)),
    };
}

这个方法的职责很清晰：检查设置、解析路径、启动服务、构建 URL。其中 ResolveLaunchDirectory 方法会进行路径安全检查，防止路径穿越攻击。代码就像诗，每一行都有自己的韵律。

自动运行时管理

后端通过 VsCodeServerManager 管理 code-server 进程：

检查进程状态
自动启动已停止的服务
返回运行时快照（端口、进程 ID、启动时间等）

这种设计让系统可以自动处理 code-server 的生命周期，用户无需手动管理服务进程。毕竟，人生已经够复杂了，能自动化的就自动化吧。

语言跟随机制

HagiCode 支持多语言界面，code-server 也需要跟随这个设置。系统支持三种语言模式：

follow：跟随当前界面语言
zh-CN：固定中文
en-US：固定英文

通过 URL 参数 vscode-lang 传递给 code-server，确保编辑器语言与 HagiCode 界面保持一致。语言这东西，统一了才舒服。

MonoSpecs 多仓库工作区

对于 MonoSpecs 项目（包含多个子仓库的 mono-repo），系统会自动创建 .code-workspace 文件：

private async Task<string> CreateWorkspaceFileAsync(Project project, Guid projectId)
{
    var folders = await ResolveWorkspaceFoldersAsync(project.Path);
    var workspaceDocument = new {
        folders = folders.Select(path => new { path }).ToArray(),
    };
    // 生成 workspace 文件...
}

这样可以在一个 code-server 实例中同时编辑多个子仓库，对于大型 mono-repo 项目非常实用。多个仓库在一个窗口里，就像多个故事在同一本书里。

前端集成

HagiCode 前端使用 React + TypeScript，集成 code-server 的步骤倒也不复杂。

快速操作按钮

在项目卡片中添加 Code Server 按钮：

<Button
  size="sm"
  variant="default"
  onClick={() => onAction({ type: 'open-code-server' })}
>
  <Globe className="h-3 w-3 mr-1" />
  <span className="text-xs">{t('project.openCodeServer')}</span>
</Button>

这个按钮会触发打开动作，调用后端 API 获取启动 URL。一个按钮，承载一个动作，简单直接。

处理打开动作

const handleAction = async (action: ProjectAction) => {
  if (action.type === 'open-code-server') {
    const response = await openProjectInCodeServer(project.id, i18n.language);
    window.open(response.launchUrl, '_blank', 'noopener,noreferrer');
  }
};

使用 window.open 在新标签页中打开 code-server，noopener,noreferrer 参数确保安全性。安全这东西，再怎么小心都不为过。

Vault 编辑入口

在 Vault 列表中添加类似的编辑按钮：

const handleEditVault = async (vault: VaultItemDto) => {
  const response = await openVaultInCodeServer(vault.id);
  window.open(response.launchUrl, '_blank', 'noopener,noreferrer');
};

项目和 Vault 使用相同的打开方式，保持了交互的一致性。一致性的重要，不亚于功能本身。

URL 构建逻辑

code-server 的 URL 格式，其实也有点讲究：

文件夹模式：

http://{host}:{port}/?folder={path}&tkn={token}&vscode-lang={lang}

工作区模式：

http://{host}:{port}/?workspace={workspacePath}&tkn={token}&vscode-lang={lang}

其中 tkn 是连接 token，每次启动 code-server 时自动生成，确保访问安全。vscode-lang 参数控制编辑器界面语言。这些参数各有各的用处，缺一不可。

使用场景

场景一：AI 辅助代码审查

用户与 HagiCode 对话，AI 分析项目代码并发现潜在问题。用户点击 “Open in Code Server” 按钮直接在浏览器中打开编辑器，查看问题文件并修复，然后返回 HagiCode 继续对话。整个流程在浏览器中完成，无需切换应用。这种感觉，怎么说呢，就像流水一样顺畅。

场景二：Vault 学习资料编辑

用户创建了学习某个开源项目的 Vault，想在 docs/ 目录添加学习笔记。通过 code-server 直接在浏览器中编辑 Markdown 文件，保存后 HagiCode 可以同步读取更新的笔记内容。这对于构建个人知识库非常有用。知识这东西，越积累越有价值。

场景三：MonoSpecs 多仓库开发

MonoSpecs 项目包含多个子仓库，code-server 自动创建多文件夹工作区。用户在浏览器中可以同时编辑多个仓库的代码，修改后提交到各自的 Git 仓库。这种工作方式特别适合需要跨仓库修改的场景。多个仓库一起改，就像同时处理多件事情，需要点技巧。

安全性考虑

在实现 code-server 集成时，安全性是需要重点关注的问题。毕竟，安全这种事，出了问题就晚了。

Connection Token

connection-token 是随机生成的，不应泄露。建议在 HTTPS 环境下使用，防止 token 被中间人截获。敏感信息，还是保护好为妙。

文件路径安全

后端实现了路径穿越检查：

private static string ResolveLaunchDirectory(VaultRegistryEntry vault, string? relativePath)
{
    var vaultRoot = EnsureTrailingSeparator(Path.GetFullPath(vault.PhysicalPath));
    var combinedPath = Path.GetFullPath(Path.Combine(vaultRoot, relativePath ?? "."));
    if (!combinedPath.StartsWith(vaultRoot, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode, "Relative path traversal detected.");
    }
    return combinedPath;
}

这段代码确保用户无法通过 ../ 等方式访问 vault 目录之外的文件。边界检查这种事，做总比不做强。

权限控制

code-server 进程以适当的用户权限运行，避免访问系统敏感文件。建议使用专用用户运行 code-server 服务。权限控制，该有的还是要有。

性能优化

code-server 会消耗服务器资源，以下是一些优化建议：

监控 CPU/内存使用，必要时调整资源限制
大型项目可能需要增加超时时间
实现会话超时自动清理，释放资源
考虑使用缓存减少重复计算

HagiCode 提供了运行时状态监控 API，前端可以通过 getVsCodeServerSettings() 获取当前状态：

const { settings, runtime } = await getVsCodeServerSettings();
// runtime.status: 'disabled' | 'stopped' | 'starting' | 'running' | 'unhealthy'
// runtime.baseUrl: "http://localhost:8080"
// runtime.processId: 12345

这个设计让用户可以清楚了解 code-server 的健康状态，在出现问题时快速定位。状态可见，心里才有数。

用户体验细节

在实现过程中，我们发现了一些影响用户体验的细节，值得特别关注：

首次打开 code-server 可能需要等待启动，这个时间可能从几秒到半分钟不等。建议在前端显示加载状态，让用户知道系统正在处理。等待这事儿，有反馈就好。

浏览器可能会阻止弹窗，需要提示用户手动允许。HagiCode 在首次打开时会显示引导信息，告诉用户如何设置浏览器权限。用户体验，就是在这些细节里体现的。

建议显示运行时状态（启动中/运行中/错误），这样用户在遇到问题时可以知道是服务端问题还是自己操作问题。知道问题出在哪里，至少心里有底。

配置示例

code-server 的配置倒也不复杂：

{
  "vscodeServer": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 8080,
    "language": "follow"
  }
}

enabled 控制功能开关，host 和 port 指定监听地址，language 设置语言模式。这些配置可以通过 UI 界面修改，实时生效。简单的东西，往往最好用。

总结

HagiCode 的 VSCode Web 集成提供了一个优雅的解决方案：让 AI 助手与代码编辑体验无缝连接。通过在浏览器中集成 code-server，用户可以快速响应 AI 的分析结果，在同一个浏览器会话中完成从分析到编辑的完整流程。

这套方案的几个关键优势：一是统一体验，项目和 Vault 使用相同的打开方式；二是多仓库支持，MonoSpecs 项目自动创建工作区；三是安全可控，运行时状态监控和路径安全检查。

本文分享的方案是 HagiCode 在实际开发中总结出来的。如果你觉得这套方案有价值，说明我们的工程实践还不错——那么 HagiCode 本身也值得关注一下。毕竟，好东西值得被更多人看见。

参考资料

HagiCode GitHub：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
code-server 官网：coder.com/code-server
相关代码文件：
- repos/web/src/services/vscodeServerService.ts
- repos/hagicode-core/src/PCode.Application/Services/VaultAppService.cs
- repos/hagicode-core/src/PCode.Application/ProjectAppService.VsCodeServer.cs

如果本文对你有帮助：

来 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-04-12-vscode-web-integration-browser-editing/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

边框灯光环绕动画特效实现指南

2026年4月11日

边框灯光环绕动画特效实现指南

那个让用户一眼就注意到的重要元素，到底是怎么用纯 CSS 做出来的？其实也不难，就是绕了个弯子罢了。这篇文章带你从零开始实现边框灯光环绕动画，也顺带聊聊我们在 HagiCode 项目里踩过的那些坑。

背景

做前端的同学应该都有过这样的经历：产品经理跑过来，脸上挂着那种”这需求很简单”的表情——“这个正在运行的任务，能不能加个特效让用户一眼就能看到？”

你说行啊，加个边框变色呗。结果对方摇摇头，眼神里透着一种”你不懂”的意味：“不够明显，要那种灯光绕着边框跑的效果，跟科幻电影里一样。”

这时候你可能就会犯嘀咕：这玩意儿怎么实现？用 Canvas？用 SVG？还是说 CSS 能搞？毕竟谁也不想承认自己不会嘛。

其实啊，边框灯光环绕动画在现代 Web 应用中特别常见，主要用在这么几个场景：

状态指示：标记正在进行的任务或活跃的项目
视觉焦点：突出显示重要的内容区域
品牌增强：营造科技感和现代感的视觉体验
节日主题：配合特殊节日创建庆祝氛围

我们做 HagiCode 的时候就遇到过这个需求——用户需要一眼看出哪些会话正在运行、哪些提案正在处理中。试了好几种方案，有些路好走一点，有些路稍微曲折一点罢了，最后沉淀出了一套还算成熟的实现思路。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 驱动的代码助手项目，在界面中大量使用边框灯光动画来指示各种运行状态。比如会话列表的运行状态、提案流程图的状态过渡、吞吐量指示器的强度显示等等。

其实这些效果说起来也不复杂，就是做的时候踩了不少坑。如果你想看看实际效果，可以访问我们的 GitHub 仓库或者直接去官网了解一下，毕竟能用的才是最好的嘛。

核心实现思路

经过对 HagiCode 代码的分析，我们总结出了下面几种核心的实现模式，每种都有它适用的场景，或者说，每种都有它存在的意义罢了。

1. Conic Gradient 旋转光晕（最常用）

这是最经典的边框灯光环绕实现方式，核心思路是用 CSS 的 conic-gradient 创建一个圆锥渐变，然后让它转起来。就像夜晚的路灯，一直在那里转啊转的。

关键要素：

用 ::before 伪元素创建光晕层
用 conic-gradient 定义渐变色分布
用 ::after 伪元素遮罩中心区域（可选）
用 @keyframes 实现旋转动画

2. 侧边发光线条

这个适用于列表项的状态指示，在元素的一侧创建发光的细线条就行，不用整个边框都动。毕竟有时候，一点光就够了，不需要照亮整个世界。

关键要素：

绝对定位的细线元素
用 box-shadow 创建发光效果
用 scale 和 opacity 实现呼吸动画

3. Box-Shadow 发光背景

如果不需要环绕效果，只是想要个柔和的背景光晕，那用多层 box-shadow 叠加就够了。有些东西，简单点反而更好。

4. 无障碍访问支持

这个容易被忽略，但特别重要。所有动画都应该考虑 prefers-reduced-motion 媒体查询，给不喜欢动画的用户提供一个静态替代方案。毕竟不是所有人都喜欢动来动去的，尊重每个人的选择才是对的。

实现方案

方案一：Conic Gradient 旋转边框（推荐）

这是最完整的环绕灯光效果实现，也是 HagiCode 里用得最多的方案。毕竟，如果一样东西好用，为什么还要换呢？

/* 父容器 */
.glow-border-container {
  position: relative;
  overflow: hidden;
}

/* 旋转的光晕层 */
.glow-border-container::before {
  content: '';
  position: absolute;
  top: -50%;
  left: -50%;
  width: 200%;
  height: 200%;
  background: conic-gradient(
    transparent 0deg,
    rgba(59, 130, 246, 0.6) 60deg,
    rgba(59, 130, 246, 0.3) 120deg,
    rgba(59, 130, 246, 0.6) 180deg,
    transparent 240deg
  );
  animation: border-rotate 3s linear infinite;
  z-index: -1;
}

/* 遮罩层（可选，用于创建空心边框效果） */
.glow-border-container::after {
  content: '';
  position: absolute;
  inset: 2px;
  background: inherit;
  border-radius: inherit;
  z-index: -1;
}

@keyframes border-rotate {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

这个方案的原理挺简单的：创建一个比父容器大的伪元素，上面画一个圆锥渐变，然后让它不停旋转。父容器设置 overflow: hidden，所以只能看到边框那一部分的光在转。就像我们在窗子里看外面的路灯，只能看到它经过的那一小段罢了。

方案二：简化版旋转光边框

如果你不需要那么复杂的效果，HagiCode 里有个更轻量的工具类实现。毕竟简单点，有时候反而更好。

/* 旋转光边框工具类 */
.running-light-border {
  position: absolute;
  inset: -2px;
  background: conic-gradient(
    from 0deg,
    transparent 0deg 270deg,
    var(--theme-running-color) 270deg 360deg
  );
  border-radius: inherit;
  animation: lightRayRotate 3s linear infinite;
  will-change: transform;
  z-index: 0;
}

@keyframes lightRayRotate {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

/* 无障碍支持 */
@media (prefers-reduced-motion: reduce) {
  .running-light-border {
    animation: none;
  }
}

注意这里的 will-change: transform，这是告诉浏览器”这个元素要一直变”，浏览器就会提前做些优化，动画会更流畅。毕竟提前准备，总比临时抱佛脚强嘛。

方案三：侧边发光线条

列表项的状态指示用这个特别合适，HagiCode 的会话列表就是用的这个方案。一条细线，却能在众多项目中脱颖而出，这不也是一种生活哲学吗？

.side-glow {
  position: relative;
  isolation: isolate;
}

.side-glow::before {
  content: '';
  position: absolute;
  left: 0;
  top: 14px;
  bottom: 14px;
  width: 1px;
  border-radius: 999px;
  background: var(--theme-running-color);
  box-shadow:
    0 0 16px var(--theme-running-color),
    0 0 28px var(--theme-running-color);
  z-index: 1;
  pointer-events: none;
  animation: sidePulse 2.6s ease-in-out infinite;
}

.side-glow > * {
  position: relative;
  z-index: 2;
}

@keyframes sidePulse {
  0%, 100% {
    opacity: 0.55;
    transform: scaleY(0.96);
  }
  50% {
    opacity: 0.95;
    transform: scaleY(1);
  }
}

这里用了 isolation: isolate 创建一个新的层叠上下文，然后用 z-index 控制各层的显示顺序。pointer-events: none 也很关键，不然那个伪元素会挡住用户的点击操作。就像有些东西，好看是好看，但是不能碍事才行。

方案四：React 组件封装

如果你项目里用 React，可以封装一个组件来处理这些逻辑，特别是无障碍访问的部分。毕竟代码写一次，用很多次，这才是我们想要的嘛。

import React from 'react';
import { useReducedMotion } from 'framer-motion';
import styles from './GlowBorder.module.css';

interface GlowBorderProps {
  isActive: boolean;
  children: React.ReactNode;
  className?: string;
}

export const GlowBorder = React.memo<GlowBorderProps>(
  ({ isActive, children, className = '' }) => {
    const prefersReducedMotion = useReducedMotion();

    if (!isActive) {
      return <div className={className}>{children}</div>;
    }

    if (prefersReducedMotion) {
      return (
        <div className={`${styles.glowStatic} ${className}`}>
          {children}
        </div>
      );
    }

    return (
      <div className={`${styles.glowAnimated} ${className}`}>
        {children}
      </div>
    );
  }
);

对应的 CSS 模块：

/* 动画版本 */
.glowAnimated {
  position: relative;
  overflow: hidden;
}

.glowAnimated::before {
  content: '';
  position: absolute;
  top: -50%;
  left: -50%;
  width: 200%;
  height: 200%;
  background: conic-gradient(
    from 0deg,
    transparent,
    rgba(59, 130, 246, 0.6),
    transparent,
    rgba(59, 130, 246, 0.6),
    transparent
  );
  animation: rotateGlow 3s linear infinite;
  z-index: -1;
}

.glowAnimated::after {
  content: '';
  position: absolute;
  inset: 2px;
  background: inherit;
  border-radius: inherit;
  z-index: -1;
}

/* 静态版本（无障碍） */
.glowStatic {
  position: relative;
  border: 1px solid rgba(59, 130, 246, 0.5);
  box-shadow: 0 0 15px rgba(59, 130, 246, 0.3);
}

@keyframes rotateGlow {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

framer-motion 的 useReducedMotion hook 会自动检测用户的系统偏好，如果用户开启了”减弱动态效果”，就会返回 true，这时候就显示静态版本。毕竟，尊重用户的选择比强行展示更重要。

实践经验分享

下面这些是我们在做 HagiCode 时踩过坑、总结出来的经验。其实也就是些碎碎念罢了，希望能帮到后来的你。

1. 主题变量系统

用 CSS 变量实现多主题支持特别方便。毕竟谁也不想每次切换主题都要改一堆代码呢？

:root {
  --glow-color-light: rgb(16, 185, 129);
  --glow-color-dark: rgb(16, 185, 129);
  --theme-glow-color: var(--glow-color-light);
}

html.dark {
  --theme-glow-color: var(--glow-color-dark);
}

/* 使用 */
.glow-effect {
  background: var(--theme-glow-color);
  box-shadow: 0 0 20px var(--theme-glow-color);
}

这样切换主题的时候只需要改一下 html 标签的 class，所有动画颜色都会自动更新。一套代码，两种风格，这不就是我们追求的吗？

2. 性能优化

使用 will-change 提示浏览器优化：

.animated-glow {
  will-change: transform, opacity;
}

提前告诉浏览器，它就会帮你做些优化。就像生活中的很多事情，提前准备总是好的。

避免在大面积元素上使用复杂的 box-shadow：

/* 不好 - 大面积元素上使用模糊阴影 */
.large-card {
  box-shadow: 0 0 50px rgba(0, 0, 0, 0.5);
}

/* 更好 - 使用伪元素限制发光区域 */
.large-card::before {
  content: '';
  position: absolute;
  inset: 0;
  border-radius: inherit;
  box-shadow: 0 0 20px var(--glow-color);
  pointer-events: none;
}

我们在 HagiCode 里测试过，在大卡片上直接加模糊阴影会让滚动帧率掉到 30fps 以下，改用伪元素后就稳稳 60fps 了。这种体验上的差异，用户是能感觉到的。

3. 无障碍访问

这个真的不能省，有些用户会觉得动画很晕或者很吵，尊重他们的选择是做产品的基本素养。毕竟美的事物不必强加于人嘛。

CSS 媒体查询：

@media (prefers-reduced-motion: reduce) {
  .glow-animation {
    animation: none;
  }

  .glow-animation::before {
    /* 提供静态替代方案 */
    opacity: 1;
  }
}

React 中检测用户偏好：

import { useReducedMotion } from 'framer-motion';

const Component = () => {
  const prefersReducedMotion = useReducedMotion();

  return (
    <div className={prefersReducedMotion ? 'static-glow' : 'animated-glow'}>
      Content
    </div>
  );
};

4. 强度级别控制

HagiCode 里的 Token 吞吐量指示器会根据实时吞吐量显示不同颜色的灯光，这个是动态实现的。毕竟不同的状态，应该有不一样的表达方式。

const colors = [
  null,       // Level 0 - no color
  '#3b82f6',  // Level 1 - Blue
  '#34d399',  // Level 2 - Emerald
  '#facc15',  // Level 3 - Yellow
  '#fbbf24',  // Level 4 - Amber
  '#f97316',  // Level 5 - Orange
  '#22d3ee',  // Level 6 - Cyan
  '#d946ef',  // Level 7 - Fuchsia
  '#f43f5e',  // Level 8 - Rose
];

const IntensityGlow = ({ intensity }) => {
  const glowColor = colors[Math.min(intensity, colors.length - 1)];

  return (
    <div
      className="glow-effect"
      style={{
        '--glow-color': glowColor,
        opacity: 0.6 + (intensity * 0.08),
      }}
    />
  );
};

5. 注意事项

有些细节还是要注意的，不然踩了坑才知道就晚了。

注意事项	说明
z-index 管理	光晕层应设置合适的 z-index，避免影响内容交互
pointer-events	光晕伪元素应设置 `pointer-events: none`
边界溢出	父容器需要设置 `overflow: hidden` 或调整伪元素尺寸
性能影响	复杂动画在移动设备上可能影响性能，需要测试
深色模式	确保发光颜色在深色背景下清晰可见
主题切换	使用 CSS 变量确保主题切换时动画颜色正确更新

6. 调试技巧

伪元素在开发者工具里有时候不太好找，可以临时加个边框来看看位置。

/* 临时显示伪元素边界用于调试 */
.glow-effect::before {
  /* debug: border: 1px solid red; */
}

调好位置之后记得把这行注释掉或者删掉，不然生产环境会很尴尬。有些东西，还是留在开发环境比较好。

总结

边框灯光环绕动画说难不难，说简单也不简单。核心就是 conic-gradient 加旋转，但要做到性能好、可维护、无障碍友好，还是有不少细节要注意的。

HagiCode 在这个上面踩了不少坑，也总结出了一些最佳实践。其实做项目就是这样，一遍遍试错，一遍遍改进。如果你在做类似的需求，希望这篇文章能帮你少走点弯路。

毕竟，有些东西，还是要亲自实践才知道深浅。

参考资料

HagiCode 项目 SessionRunningBorderHighlight 组件
HagiCode 项目 ProposalFlowDiagram.css 样式
HagiCode 项目 globals.css 中的 .running-light-border 工具类
MDN - conic-gradient
MDN - prefers-reduced-motion

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-11-border-light-animation-effect/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

用 Vault 系统构建 AI 时代的跨项目知识库

2026年4月10日

用 Vault 系统构建 AI 时代的跨项目知识库

临摹项目学习法正在成为主流，只是学习资料分散、上下文断裂的痛点让 AI 助手难以发挥最大价值。本文介绍 HagiCode 项目的 Vault 系统设计——通过统一的存储抽象层，让 AI 助手能够理解和访问所有学习资源，实现真正的跨项目知识复用。

背景

其实，在 AI 时代，我们学习新技术的方式正在悄然改变。传统的读书、看视频固然重要，但”临摹项目”——深入研究和学习优秀开源项目的代码、架构和设计模式——确实越来越高效。直接运行和修改高质量的开源项目，能让你最快理解真实世界的工程实践。

只是这种方式也带来了新的挑战。

学习资料太分散。笔记可能在 Obsidian 里，代码仓库散落在各个文件夹，AI 助手的对话历史又是一个独立的数据孤岛。每次需要 AI 帮助分析某个项目时，都得手动复制代码片段、整理上下文，过程相当繁琐。

上下文经常断掉。AI 助手无法直接访问本地学习资源，每次对话都得重新提供背景信息。临摹的代码仓库更新快，手动同步容易出错。更糟的是，多个学习项目之间难以共享知识——在 A 项目中学到的设计模式，AI 处理 B 项目时完全不知道。

这些问题的本质是”数据孤岛”。如果能有一个统一的存储抽象层，让 AI 助手能够理解和访问所有学习资源，问题就迎刃而解了。

为了解决这些痛点，我们在开发 HagiCode 时做了一个关键的设计决策：构建一个 Vault 系统作为统一的知识存储抽象层。这个决定带来的变化，可能比想象的还要大——稍后具体说。

关于 HagiCode

本文分享的方案来自在 HagiCode 项目中的实践经验。HagiCode 是一个基于 OpenSpec 工作流的 AI 代码助手，它的核心理念是让 AI 不仅会”说”，更会”做”——能够直接操作代码仓库、执行命令、运行测试。GitHub：github.com/HagiCode-org/site

在开发过程中，我们发现 AI 助手需要频繁访问用户的各类学习资源：代码仓库、笔记文档、配置文件等。如果每次都要用户手动提供，体验就太糟糕了。这促使设计了 Vault 系统。

核心设计

多类型支持

HagiCode 的 Vault 系统支持四种类型，分别对应不同的使用场景：

类型	用途	典型场景
`folder`	通用文件夹类型	临时学习资料、草稿
`coderef`	专门用于临摹代码项目	系统化学习某个开源项目
`obsidian`	与 Obsidian 笔记软件集成	现有笔记库的复用
`system-managed`	系统自动管理	项目配置、提示词模板等

其中 coderef 类型是 HagiCode 中最常用的，它为临摹代码项目提供了标准化的目录结构和 AI 可读的元数据描述。为什么要专门设计这个类型？因为临摹一个开源项目不是简单的”下载代码”，需要同时管理代码本身、学习笔记、配置文件等多种内容，coderef 把这些都规范好了。

持久化存储机制

Vault 的注册表以 JSON 格式持久化存储到文件系统：

_registryFilePath = Path.Combine(absoluteDataDir, "personal-data", "vaults", "registry.json");

这个设计看似简单，实则经过深思熟虑：

简单可靠。JSON 格式人类可读，便于调试和手动修改。当系统出现问题时，可以直接打开文件查看状态，甚至手动修复——这在开发阶段特别有用。

降低依赖。文件系统存储避免了数据库的复杂性。不需要额外安装和配置数据库服务，降低了系统复杂度和维护成本。

并发安全。使用 SemaphoreSlim 确保多线程安全。在 AI 代码助手的场景下，可能会有多个操作同时访问 vault 注册表，需要做好并发控制。

AI 上下文集成

系统的核心能力在于能够自动将 vault 信息注入到 AI 提案的上下文中：

export function buildTargetVaultsText(
  vaults: VaultForText[],
  template: VaultPromptTemplate = DEFAULT_VAULT_PROMPT_TEMPLATE,
): string {
  const readOnlyVaults = vaults.filter((vault) => vault.accessType === 'read');
  const editableVaults = vaults.filter((vault) => vault.accessType === 'write');

  const sections = [
    buildVaultSection(readOnlyVaults, template.reference),
    buildVaultSection(editableVaults, template.editable),
  ].filter(Boolean);

  return `\n\n### ${template.heading}\n\n${sections.join('\n')}`;
}

这样 AI 助手就能自动理解可用的学习资源，无需用户每次手动提供上下文。这个设计让 HagiCode 的体验变得特别自然——告诉 AI “帮我分析 React 的并发渲染”，AI 就能自动找到之前注册的 React 学习 vault，而不是一遍遍贴代码。

访问控制机制

系统将 vault 分为两种访问类型：

reference（只读）：AI 仅用于分析和理解，不能修改内容
editable（可编辑）：AI 可以根据任务需要修改内容

这种区分让 AI 知道哪些内容是”只读参考”，哪些是”可以动手改的”，避免了误操作风险。比如注册了一个开源项目的 vault 作为学习材料，肯定不希望 AI 随手修改里面的代码——那就标记为 reference。但如果是自己的项目 vault，就可以标记为 editable，让 AI 帮着改代码。

实践指南

CodeRef Vault 的标准化结构

对于 coderef 类型的 vault，系统提供了一套标准化的目录结构：

my-coderef-vault/
├── index.yaml          # vault 元数据描述
├── AGENTS.md           # AI 助手的操作指南
├── docs/               # 存放学习笔记和文档
└── repos/              # 通过 Git 子模块管理临摹的代码仓库

这个结构的设计理念是什么？

docs/ 存放学习笔记，用 Markdown 格式记录对代码的理解、架构分析、踩坑经验。这些笔记不仅自己看，AI 也能读懂——在处理相关任务时会自动参考。

repos/ 通过 Git 子模块管理临摹的仓库，而不是直接复制代码。这样做有两个好处：一是保持与上游同步，一个 git submodule update 就能拿到最新代码；二是节省空间，多个 vault 可以引用同一个仓库的不同版本。

index.yaml 包含 vault 的元数据，让 AI 助手快速理解用途和内容。相当于给 vault 写了个”自我介绍”，AI 第一次见到就知道这是干嘛的。

AGENTS.md 是专门写给 AI 助手看的指南，说明如何处理 vault 中的内容。可以在这里告诉 AI：“分析这个项目时重点关注性能优化相关的代码”或者”不要修改测试文件”。

创建和使用 Vault

创建一个 CodeRef vault 很简单：

const createCodeRefVault = async () => {
  const response = await VaultService.postApiVaults({
    requestBody: {
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/Users/developer/vaults/react-learning",
      gitUrl: "https://github.com/facebook/react.git"
    }
  });

  // 系统会自动：
  // 1. 克隆 React 仓库到 vault/repos/react
  // 2. 创建 docs/ 目录用于笔记
  // 3. 生成 index.yaml 元数据
  // 4. 创建 AGENTS.md 指南文件

  return response;
};

然后在 AI 提案中引用这个 vault：

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "帮我分析 React 的并发渲染机制",
  repositories: [
    { id: "react", gitUrl: "https://github.com/facebook/react.git" }
  ],
  vaults: [
    {
      id: "react-learning",
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/vaults/react-learning",
      accessType: "read"  // AI 只能读取，不能修改
    }
  ],
  quickRequestText: "重点关注 fiber 架构和 scheduler 实现"
});

典型使用场景

场景一：系统化学习开源项目

创建一个 CodeRef vault，通过 Git 子模块管理目标仓库，在 docs/ 目录记录学习笔记。AI 可以同时访问代码和笔记，提供更精准的分析。在学习某个模块时写的笔记，AI 后续分析相关代码时会自动参考——就像有个”助手”记住了之前的思考。

场景二：复用 Obsidian 笔记库

如果已经在用 Obsidian 管理笔记，直接把现有的 vault 注册到 HagiCode 中就行。AI 可以直接访问知识库，无需手动复制粘贴。这个功能特别实用，很多人都有积累多年的笔记库，接入之后 AI 就能”读”懂知识体系。

场景三：跨项目知识复用

多个 AI 提案可以引用同一个 vault，实现知识的跨项目复用。比如创建了一个”设计模式学习 vault”，里面记录了各种设计模式的笔记和代码示例。无论在分析哪个项目，AI 都能参考这个 vault 中的内容——知识不用重复积累。

路径安全机制

系统严格校验路径，防止路径穿越攻击：

private static string ResolveFilePath(string vaultRoot, string relativePath)
{
    var rootPath = EnsureTrailingSeparator(Path.GetFullPath(vaultRoot));
    var combinedPath = Path.GetFullPath(Path.Combine(rootPath, relativePath));
    if (!combinedPath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode,
            "Vault file paths must stay inside the registered vault root.");
    }
    return combinedPath;
}

这确保了所有文件操作都在 vault 的根目录范围内，防止恶意路径访问。安全这块不能马虎，AI 助手要操作文件系统，必须把边界划清楚。

注意事项

使用 HagiCode Vault 系统时，有几点需要特别注意：

路径安全：确保自定义路径在允许的范围内，否则系统会拒绝操作。这是为了防止误操作和潜在的安全风险。
Git 子模块管理：CodeRef vault 推荐使用 Git 子模块而非直接复制代码。好处前面说过——保持同步、节省空间。只是子模块有自己的使用方式，第一次使用可能需要熟悉一下。
文件预览限制：系统限制文件大小（256KB）和数量（500个），超大文件需分批处理。这个限制是为了性能考虑，如果遇到超大文件，可以手动拆分或者用其他方式处理。
诊断信息：创建 vault 会返回诊断信息，失败时可用于调试。遇到问题时先看诊断信息，大部分情况下都能找到线索。

总结

HagiCode 的 Vault 系统本质上是在解决一个简单但深刻的问题：如何让 AI 助手理解和使用本地知识资源。

通过统一的存储抽象层、标准化的目录结构、自动化的上下文注入，实现了”一次注册，处处复用”的知识管理方式。创建一个 vault 后，无论是学习笔记、代码仓库还是文档资料，AI 都能自动访问和理解。

这种设计带来的体验提升是明显的。不再需要手动复制代码片段、重复解释背景信息——AI 助手就像一个真正了解项目情况的同事，能够基于已有知识提供更有价值的帮助。

本文分享的 Vault 系统，正是开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果觉得这套设计有价值，说明工程实力还不错——那么 HagiCode 本身也值得关注一下。

参考资料

HagiCode GitHub：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose 安装指南：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/

如果本文对你有帮助：

来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
观看实战演示视频：www.bilibili.com/video/BV1pirZBuEzq/
一键安装体验：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/

公测已开始，欢迎安装体验。

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-10-vault-system-ai-knowledge-base/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

在 Web 界面直接编辑 DESIGN.md：从思路到实现

2026年4月9日

在 Web 界面直接编辑 DESIGN.md：从思路到实现

在 MonoSpecs 项目管理系统中，DESIGN.md 承载着项目的架构设计和技术决策。但传统的编辑方式要求用户必须切换到外部编辑器，这种割裂的流程，怎么说呢，就像在读一首诗的时候突然被打断了——灵感没了，心情也没了。本文分享了我们在 HagiCode 项目中实践的解决方案：在 Web 界面直接编辑 DESIGN.md，并支持从线上设计站点导入模板。毕竟，谁不喜欢一气呵成的感觉呢？

背景

DESIGN.md 作为项目设计文档的核心载体，承载着架构设计、技术决策和实现指导等关键信息。然而，传统的编辑方式要求用户必须切换到外部编辑器（如 VS Code），手动定位物理路径后再进行编辑。这过程说起来也不算复杂，只是反复几次之后，人也就乏了。

具体问题体现在以下几个方面：

流程割裂：用户需要在 Web 管理界面和本地编辑器之间频繁切换，破坏了工作流连贯性——就像听歌的时候突然断网了，节奏全乱了。
复用困难：设计站点已经发布了丰富的设计模板库，但无法直接集成到项目编辑流程中。明明有好东西，就是用不上，这感觉确实有点遗憾。
体验缺失：缺少”预览-选择-导入”的闭环，用户必须手动复制粘贴，增加了出错风险。手动操作的次数多了，出错的机会自然也多了。
协作障碍：设计文档与代码实现的同步维护变得高摩擦，阻碍团队协作效率。团队协作本就不易，何必再添这些阻力呢？

为了解决这些痛点，我们决定在 Web 界面中实现 DESIGN.md 的直接编辑能力，并支持从线上设计站点一键导入模板。这也不算是什么惊天动地的决策，只是想让开发体验更顺畅一点罢了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 驱动的代码助手项目，在开发过程中，我们需要频繁维护项目的设计文档。为了让团队能够更高效地协作，我们探索并实现了这套在线编辑和导入方案。其实也没什么特别的，只是遇到了问题，想办法解决而已。

技术方案

整体架构

该解决方案采用前后端分离的同源代理架构，主要由以下几个层次构成。这种架构的设计，说起来也不过是”各司其职”四个字罢了：

1. 前端编辑器层

// 核心组件：DesignMdManagementDrawer
// 功能：承载编辑、保存、版本冲突检测、导入流程

2. 后端服务层

// 位置：repos/hagicode-core/src/PCode.Application/ProjectAppService.DesignMd.cs
// 功能：路径解析、文件读写、版本管理

3. 同源代理层

// 位置：repos/hagicode-core/src/PCode.Application/ProjectAppService.DesignMdSiteIndex.cs
// 功能：代理设计站点资源、预览图缓存、安全校验

关键技术决策

决策 1：全局抽屉模式

采用单一全局抽屉而非局部弹层，通过 layoutSlice 管理状态，实现了跨视图（classic/kanban）的一致体验。这种方式确保用户无论在哪个视图中打开编辑器，都能获得统一的交互体验。毕竟，一致的体验能让用户感觉更自在，不会因为换个视图就迷失方向。

决策 2：项目作用域 API

将 DESIGN.md 相关接口挂在 ProjectController 下，复用现有项目权限边界，避免了新增独立控制器的复杂度。这样设计的好处是权限管理更清晰，也符合 RESTful 的资源组织原则。有时候，复用比重新创建更有意义，不是吗？

决策 3：版本冲突检测

基于文件系统 LastWriteTimeUtc 派生 opaque version，实现了轻量级的乐观并发控制。当多个用户同时编辑同一文件时，系统能够检测到冲突并提示用户刷新。这种设计既不阻塞用户的编辑操作，又能保证数据的一致性——就像人际交往中的边界感，既不过分疏离，也不越界。

决策 4：同源代理模式

通过 IHttpClientFactory 代理外部设计站点资源，避免了跨域问题和 SSRF 风险。这种设计既保证了安全性，又简化了前端调用。安全这件事，做再多也不为过，毕竟数据安全就像健康，失去了才后悔就晚了。

核心实现

1. 直接编辑 DESIGN.md

后端实现

后端主要负责路径解析、文件读写和版本管理。这些工作虽然基础，但必不可少，就像房子的地基一样：

// 路径解析与安全校验
private Task<string> ResolveDesignDocumentDirectoryAsync(string projectPath, string? repositoryPath)
{
    if (string.IsNullOrWhiteSpace(repositoryPath))
    {
        return Task.FromResult(Path.GetFullPath(projectPath));
    }
    return ValidateSubPathAsync(projectPath, repositoryPath);
}

// 版本号生成（基于文件系统时间戳和大小）
private static string BuildDesignDocumentVersion(string path)
{
    var fileInfo = new FileInfo(path);
    fileInfo.Refresh();
    return string.Create(
        CultureInfo.InvariantCulture,
        $"{fileInfo.LastWriteTimeUtc.Ticks:x}-{fileInfo.Length:x}");
}

版本号的设计其实也挺有意思的，我们用文件的最后修改时间和大小来生成一个唯一的版本标识。这样既轻量又可靠，不需要维护额外的版本数据库。简单的东西，往往更有效，不是吗？

前端实现

前端实现了脏状态检测和保存逻辑。这种设计让用户随时知道自己的修改是否已保存，减少”万一丢失了怎么办”的焦虑：

// 脏状态检测与保存逻辑
const [draft, setDraft] = useState('');
const [savedDraft, setSavedDraft] = useState('');
const isDirty = draft !== savedDraft;

const handleSave = useCallback(async () => {
    const result = await saveProjectDesignMdDocument({
        ...activeTarget,
        content: draft,
        expectedVersion: document.version, // 乐观并发控制
    });
    setSavedDraft(draft); // 更新已保存状态
}, [activeTarget, document, draft]);

这个实现中，我们维护了两个状态：draft 是当前编辑的内容，savedDraft 是已保存的内容。通过比较两者来判断是否有未保存的修改。这种设计虽然简单，但能给人安心感，毕竟谁愿意辛辛苦苦写的东西突然消失呢？

2. 从线上导入设计文件

目录结构

repos/index/
└── src/data/public/design.json    # 设计模板索引

repos/awesome-design-md-site/
├── vendor/awesome-design-md/       # 上游设计模板
│   └── design-md/
│       ├── clickhouse/
│       │   └── DESIGN.md
│       ├── linear/
│       │   └── DESIGN.md
│       └── ...
└── src/lib/content/
    └── awesomeDesignCatalog.ts     # 内容管线

索引数据格式

设计站点的索引文件定义了所有可用的模板。有了这个索引，用户就能像在餐厅点菜一样，轻松选择自己想要的模板：

{
  "entries": [
    {
      "slug": "linear.app",
      "title": "Linear Inspired Design System",
      "summary": "AI 产品 / 深色感",
      "detailUrl": "/designs/linear.app/",
      "designDownloadUrl": "/designs/linear.app/DESIGN.md",
      "previewLightImageUrl": "...",
      "previewDarkImageUrl": "..."
    }
  ]
}

每个条目包含了模板的基本信息和下载链接。后端会从这个索引中读取可用的模板列表，然后展示给用户选择。这种设计让选择变得直观，而不是在黑暗中摸索。

同源代理实现

为了保证安全性，后端对设计站点的访问做了严格的校验。安全这件事，再怎么小心也不为过：

// 安全的 slug 校验
private static readonly Regex SafeDesignSiteSlugRegex =
    new("^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,127})$", RegexOptions.Compiled);

private static string NormalizeDesignSiteSlug(string slug)
{
    var normalizedSlug = slug?.Trim() ?? string.Empty;
    if (!IsSafeDesignSiteSlug(normalizedSlug))
    {
        throw new BusinessException(
            ProjectDesignSiteIndexErrorCodes.InvalidSlug,
            "Design site slug must be a single safe path segment.");
    }
    return normalizedSlug;
}

// 预览图缓存（OS 临时目录）
private static string ComputePreviewCacheKey(string slug, string theme, string previewUrl)
{
    var raw = $"{slug}|{theme}|{previewUrl}";
    var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(raw));
    return Convert.ToHexString(bytes).ToLowerInvariant();
}

这里我们做了两件事：一是用正则表达式严格校验 slug 的格式，防止路径遍历攻击；二是对预览图进行缓存，减少对外部站点的请求压力。前者是防护，后者是优化，缺一不可罢了。

3. 完整的导入流程

// 1. 打开导入抽屉
const handleRequestImportDrawer = useCallback(() => {
    setIsImportDrawerOpen(true);
}, []);

// 2. 选择并导入
const handleImportRequest = useCallback((entry) => {
    if (isDirty) {
        setPendingImportEntry(entry);
        setConfirmMode('import'); // 覆盖确认
        return;
    }
    void executeImport(entry);
}, [isDirty]);

// 3. 执行导入
const executeImport = useCallback(async (entry) => {
    const result = await getProjectDesignMdSiteImportDocument(
        activeTarget.projectId,
        entry.slug
    );
    setDraft(result.content); // 只替换编辑器文本，不自动保存
    setIsImportDrawerOpen(false);
}, [activeTarget?.projectId]);

导入流程的设计遵循了”用户确认”的原则：导入后只更新编辑器内容，不会自动保存。用户可以检查导入的内容，确认无误后再手动保存。毕竟，用户对自己写的东西应该有最终决定权，不是吗？

实践示例

场景 1：项目根目录 DESIGN.md 创建

当 DESIGN.md 不存在时，后端返回虚拟文档状态。这种设计让前端不需要特殊处理”文件不存在”的情况，统一的 API 接口简化了代码逻辑：

return new ProjectDesignDocumentDto
{
    Path = targetPath,
    Exists = false,  // 虚拟文档状态
    Content = string.Empty,
    Version = null
};

// 首次保存时自动创建文件
public async Task<SaveProjectDesignDocumentResultDto> SaveDesignDocumentAsync(...)
{
    Directory.CreateDirectory(targetDirectory);
    await File.WriteAllTextAsync(targetPath, input.Content);
    return new SaveProjectDesignDocumentResultDto { Created = !exists };
}

这种设计的好处是前端不需要特殊处理”文件不存在”的情况，统一的 API 接口简化了代码逻辑。有时候，把复杂性隐藏在后端，前端就能更轻松地专注于用户体验。

场景 2：从设计站点导入模板

用户在导入抽屉中选择 “Linear” 设计模板后，系统会通过后端代理获取 DESIGN.md 内容。整个流程对用户来说是透明的，他们只需要选择模板，系统会自动处理所有的网络请求和数据转换：

// 1. 系统通过后端代理获取 DESIGN.md 内容
GET /api/project/{id}/design-md/site-index/linear.app

// 2. 后端验证 slug 并从上游获取内容
var entry = FindDesignSiteEntry(catalog, "linear.app");
using var upstreamResponse = await httpClient.SendAsync(request);
var content = await upstreamResponse.Content.ReadAsStringAsync();

// 3. 前端替换编辑器文本
setDraft(result.content);
// 用户检查后手动保存到磁盘

整个流程对用户来说是透明的，他们只需要选择模板，系统会自动处理所有的网络请求和数据转换。用户不需要关心背后的复杂性，这就是我们追求的体验——简单，但强大。

场景 3：版本冲突处理

当多个用户同时编辑同一 DESIGN.md 时，系统会检测到版本冲突。这种乐观并发控制机制确保了数据的一致性，同时又不会阻塞用户的编辑操作：

if (!string.Equals(currentVersion, expectedVersion, StringComparison.Ordinal))
{
    throw new BusinessException(
        ProjectDesignDocumentErrorCodes.VersionConflict,
        $"DESIGN.md at '{targetPath}' changed on disk.");
}

前端会捕获这个错误并提示用户：

// 前端提示用户刷新并重试
<Alert>
    <AlertTitle>版本冲突</AlertTitle>
    <AlertDescription>
        文件已被其他进程修改。请刷新最新版本后重试。
    </AlertDescription>
</Alert>

这种乐观并发控制机制确保了数据的一致性，同时又不会阻塞用户的编辑操作。冲突不可避免，但至少可以让用户知道发生了什么，而不是默默丢失修改。

注意事项与最佳实践

1. 路径安全

始终校验 repositoryPath，防止路径遍历攻击。安全这种事，做再多也不为过：

// 始终校验 repositoryPath，防止路径遍历攻击
return ValidateSubPathAsync(projectPath, repositoryPath);
// 拒绝 "../", 绝对路径等危险输入

2. 缓存策略

预览图缓存 24 小时，最大 160 个文件。适度的缓存能提升性能，但也不能过度，毕竟平衡才是关键：

// 预览图缓存 24 小时，最大 160 个文件
private static readonly TimeSpan PreviewCacheTtl = TimeSpan.FromHours(24);
private const int PreviewCacheMaxFiles = 160;
// 定期清理过期缓存

3. 错误处理

上游站点不可用时降级处理。这种优雅降级的设计确保了即使外部依赖不可用，核心编辑功能仍然正常工作。毕竟，不能因为一个外部服务挂了，整个系统就瘫痪了：

// 上游站点不可用时降级处理
try {
    const catalog = await getProjectDesignMdSiteImportCatalog(projectId);
} catch (error) {
    toast.error(t('project.designMd.siteImport.feedback.catalogLoadFailed'));
    // 主编辑抽屉仍然可用
}

这种优雅降级的设计确保了即使外部依赖不可用，核心编辑功能仍然正常工作。系统应该有韧性，而不是一遇到问题就倒下。

4. 用户体验优化

导入前确认覆盖，导入后不自动保存。用户应该对自己的操作有控制权，而不是系统自作主张：

// 导入前确认覆盖
if (isDirty) {
    setConfirmMode('import');
    return;
}

// 导入后不自动保存，由用户确认
setDraft(result.content); // 只更新草稿
// 用户检查后点击 Save 才真正写入磁盘

5. 性能考虑

使用 HTTP 客户端工厂，避免创建过多连接。资源管理这种事，看似不起眼，但做好了能带来意想不到的效果：

// 使用 HTTP 客户端工厂，避免创建过多连接
private const string DesignSiteProxyClientName = "ProjectDesignSiteProxy";
private static readonly TimeSpan DesignSiteProxyTimeout = TimeSpan.FromSeconds(8);

扩展建议

Markdown 增强：当前使用基础 Textarea，可考虑升级为 CodeMirror 以支持语法高亮和快捷键。编辑器的体验好了，写文档的心情也会好一些。
预览模式：添加 Markdown 实时预览，提升编辑体验。所见即所得，总能给人更多信心。
差异合并：实现智能合并算法，而非简单的全文替换。冲突是难免的，但至少可以让处理冲突的过程不那么痛苦。
本地缓存：将 design.json 缓存到数据库，减少对外部站点的依赖。依赖越少，系统越稳定，这是简单的道理。

总结

在 HagiCode 项目中，我们通过前后端协作实现了一套完整的 DESIGN.md 在线编辑和导入方案。这套方案的核心价值在于：

提升效率：无需切换工具，在统一的 Web 界面完成设计文档的编辑和导入。省下的时间，可以做更有意义的事情。
降低门槛：设计模板一键导入，新项目可以快速起步。开始得越容易，坚持下去的可能性就越大。
安全可靠：路径校验、版本冲突检测、优雅降级等机制确保系统稳定运行。稳定是基础，没有稳定，一切都是空谈。
用户体验：全局抽屉、脏状态检测、确认对话框等细节打磨了交互体验。细节决定成败，这句话在用户体验上尤其适用。

这套方案已经在 HagiCode 项目中实际运行，解决了团队在设计文档管理方面的痛点。如果你也在面临类似的问题，希望这篇文章能给你一些启发。其实也没什么高深的理论，只是遇到了问题，想办法解决而已。

参考资料

HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
MonoSpecs 项目管理系统：docs.hagicode.com
30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose 安装指南：docs.hagicode.com/installation/docker-compose
Desktop 桌面端安装：hagicode.com/desktop/

如果本文对你有帮助，欢迎来 GitHub 给个 Star，公测已开始，现在安装即可参与体验。毕竟，开源项目最缺的就是反馈和鼓励，如果你觉得有用，不妨让它被更多人看到…

“美的事物或人，不一定要占有，只要她还是美的，自己好好看着她的美就好了。”

DESIGN.md 编辑器也是一样，不一定要多么复杂，只要能帮你高效地完成工作，那就是好的罢了。

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-09-design-md-web-editor-implementation/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

Design.md：让 AI 一致性进行前端 UI 设计的解决方案

2026年4月8日

Design.md：让 AI 一致性进行前端 UI 设计的解决方案

在 AI 辅助前端开发时代，如何让 AI 生成的 UI 保持一致性？本文分享了我们基于 awesome-design-md 构建设计画廊站点的实践经验，以及如何创建结构化的 design.md 来指导 AI 进行规范化的 UI 设计。

背景

用过 AI 写前端代码的朋友应该都有过类似的经历：同一个页面，让 AI 多生成几次，每次的风格都不一样。有时候是圆角有时候是方角，有时候间距是 8px 有时候又变成 16px，甚至同一个按钮在不同对话里长得都不一样。

这不仅仅是个别现象。随着 AI 辅助开发的普及，AI 生成的前端 UI 缺乏一致性已经成为一个普遍问题。不同的 AI 助手、不同的提示词，甚至同一助手在不同对话中，都会产生风格迥异的界面设计。这给产品迭代带来了巨大的维护成本。

问题的根源其实很简单：缺少一份权威的设计参考文档。传统的 CSS 样式文件只能告诉开发者”怎么实现”，却无法完整传达”为什么这样设计”以及”在什么场景下使用什么设计模式”。而对于 AI 来说，它更需要一个清晰的结构化描述来理解设计规范。

与此同时，开源社区已经有了一些很好的资源。VoltAgent/awesome-design-md 项目收集了大量知名公司的设计系统文档，每个目录包含 README.md、DESIGN.md 和预览 HTML。但这些都分散在上游仓库中，难以快速查阅和比较。

那能不能把这些资源整合起来，做成一个方便查阅的设计画廊，同时沉淀出一份结构化的 design.md 给 AI 用呢？

答案是肯定的。接下来分享一下我们的方案。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 辅助开发平台，在开发过程中，我们也遇到了 AI 生成 UI 不一致的问题。为了解决这个问题，我们构建设计画廊站点并创建规范化的 design.md，本文就是这套方案的总结。

GitHub - HagiCode-org/site

先看一眼最终做出来的首页效果。首页把设计画廊入口、站点仓库、上游仓库和 HagiCode 的背景介绍收拢在同一个界面里，方便团队先建立统一上下文，再继续阅读具体条目。

Awesome Design MD Gallery 首页概览

分析

在动手写代码之前，我们先来拆解一下这个问题的几个技术挑战。

内容源管理：如何统一分散的设计资源？

上游的 awesome-design-md 仓库包含了大量设计文档，但我们需要一种方式把它纳入到我们的项目中。

方案：使用 git submodule

awesome-design-md-site
└── vendor/awesome-design-md          # 上游资源（git submodule）

这样做有几个好处：

版本可控：可以锁定特定的上游版本
离线构建：不需要在构建时请求外部 API
内容审阅：可以在 PR 中看到具体变更

数据标准化：不同文档结构怎么统一？

不同公司的设计文档结构可能不同，有些缺少预览文件，有些命名不统一。我们需要在构建期进行标准化处理。

方案：构建期扫描并生成标准化条目

核心模块是 awesomeDesignCatalog.ts，负责：

扫描 vendor/awesome-design-md/design-md/* 目录
校验每个条目是否包含必需文件（README.md、DESIGN.md、至少一个预览文件）
提取并渲染 Markdown 内容为 HTML
生成标准化的条目数据

export interface DesignEntry {
  slug: string;
  title: string;
  summary: string;
  readmeHtml: string;
  designHtml: string;
  previewLight?: string;
  previewDark?: string;
  searchText: string;
}

export async function scanSourceEntries() {
  // 扫描 vendor/awesome-design-md/design-md/*
  // 校验文件完整性
  // 生成标准化条目
}

export async function normalizeDesignEntry(dir: string) {
  // 提取 README.md、DESIGN.md
  // 解析预览文件
  // 渲染 Markdown 为 HTML
}

静态站点架构：怎么在保持静态部署的同时提供动态搜索？

既然是设计画廊，搜索功能是必须的。但 Astro 是静态站点生成器，怎么实现实时搜索呢？

方案：React island + URL 查询参数同步

export function SearchToolbar() {
  const [query, setQuery] = useState('');

  // URL 同步
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    setQuery(params.get('q') || '');
  }, []);

  // 实时过滤
  const filtered = entries.filter(entry =>
    entry.searchText.includes(query)
  );

  return <input value={query} onChange={e => {
    setQuery(e.target.value);
    updateURL(e.target.value);
  }} />;
}

这样做的好处是保留了静态站点的可部署性（可以部署到任何静态托管服务），同时提供了即时过滤的用户体验。

设计文档化：怎么让 AI 理解并遵守设计规范？

这是整个方案的核心。我们需要创建一份结构化的 design.md，让 AI 能够理解并应用我们的设计规范。

方案：借鉴 ClickHouse DESIGN.md 的结构

ClickHouse 的 DESIGN.md 是一个很好的参考，它包含了：

Visual Theme & Atmosphere
Color Palette & Roles
Typography Rules
Component Stylings
Layout Principles
Depth & Elevation
Do’s and Don’ts
Responsive Behavior
Agent Prompt Guide

我们的做法是：结构参考，内容重写。保留 ClickHouse DESIGN.md 的章节结构，但把内容替换成我们自己项目实际使用的设计 token 和组件规范。

解决

基于上述分析，我们的解决方案包含四个核心模块。

1. 内容摄取管线

这是整个系统的基础，负责从上游资源中提取和标准化内容。

export async function scanSourceEntries(): Promise<DesignEntry[]> {
  const designDir = 'vendor/awesome-design-md/design-md';
  const entries: DesignEntry[] = [];

  for (const dir of await fs.readdir(designDir)) {
    const entryPath = path.join(designDir, dir);
    if (await isValidDesignEntry(entryPath)) {
      const entry = await normalizeDesignEntry(entryPath);
      entries.push(entry);
    }
  }

  return entries;
}

async function isValidDesignEntry(dir: string): Promise<boolean> {
  const requiredFiles = ['README.md', 'DESIGN.md'];
  for (const file of requiredFiles) {
    if (!(await fileExists(path.join(dir, file)))) {
      return false;
    }
  }
  return true;
}

2. 画廊浏览界面

画廊界面包括三个主要部分：

首页：展示所有设计条目的卡片网格，每个卡片包含：

设计条目标题和简介
预览图（如果有）
快速搜索高亮

详情页：聚合展示单个设计条目的完整信息：

README 文档
DESIGN 文档
预览（支持明/暗主题切换）
相邻条目导航

导航：支持返回画廊、浏览相邻条目

首页画廊使用高密度卡片布局，把不同来源的 design.md 条目平铺在一个统一的视觉框架里，方便快速对比品牌风格、按钮模式和排版节奏。

Awesome Design MD Gallery 设计卡片网格

进入具体条目后，详情页会把设计摘要和实时预览放在同一个页面中，减少在文档、预览和源码之间来回切换的成本。

Awesome Design MD Gallery 设计详情预览页

3. 搜索功能

搜索功能基于客户端过滤，使用 URL 查询参数保持状态：

function SearchToolbar({ entries }: { entries: DesignEntry[] }) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState(entries);

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const initialQuery = params.get('q') || '';
    setQuery(initialQuery);
    filterEntries(initialQuery);
  }, []);

  const filterEntries = (searchQuery: string) => {
    const filtered = entries.filter(entry =>
      entry.searchText.toLowerCase().includes(searchQuery.toLowerCase())
    );
    setResults(filtered);
  };

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setQuery(value);
    filterEntries(value);

    // 更新 URL（不触发页面刷新）
    const newUrl = value
      ? `${window.location.pathname}?q=${encodeURIComponent(value)}`
      : window.location.pathname;
    window.history.replaceState({}, '', newUrl);
  };

  return (
    <div className="search-toolbar">
      <input
        type="text"
        value={query}
        onChange={handleChange}
        placeholder="搜索设计条目..."
      />
      <span className="result-count">{results.length} 个结果</span>
    </div>
  );
}

4. 设计参考文档（design.md）

这是整个方案的核心输出。我们在项目根目录创建 design.md，结构如下：

除了给 AI 消费的原始 design.md 内容，我们还把 README 和 DESIGN 两份文档放进同一个阅读界面，方便人工校对、复制片段和对照预览结果。

Awesome Design MD Gallery README 与 DESIGN 文档页

# Design Reference for [Project Name]

## 1. Visual Theme & Atmosphere
- 整体风格描述
- 设计哲学和原则

## 2. Color Palette & Roles
- 主色调、辅助色
- 语义化颜色（success、warning、error）
- CSS Variables 定义

## 3. Typography Rules
- 字体家族
- 字号层级（h1-h6, body, small）
- 行高和字重

## 4. Component Stylings
- 按钮样式规范
- 表单组件样式
- 卡片和容器样式

## 5. Layout Principles
- 间距系统
- 网格和断点
- 对齐原则

## 6. Depth & Elevation
- 阴影层级
- z-index 规范

## 7. Do's and Don'ts
- 常见错误和正确做法

## 8. Responsive Behavior
- 断点定义
- 响应式适配规则

## 9. Agent Prompt Guide
- 如何将本文档用于 AI 提示词
- 示例提示词模板

实践

了解了方案之后，具体怎么实施呢？

实施步骤

第一步：初始化子模块

# 添加上游仓库为子模块
git submodule add https://github.com/VoltAgent/awesome-design-md.git vendor/awesome-design-md

# 初始化并更新子模块
git submodule update --init --recursive

第二步：创建内容管线

实现 awesomeDesignCatalog.ts，包括：

文件扫描和校验逻辑
Markdown 渲染（使用 Astro 的内置渲染器）
条目数据提取

第三步：构建画廊 UI

使用 Astro + React Islands 创建：

首页画廊布局（卡片网格）
设计卡片组件
搜索工具栏
详情页布局

第四步：编写设计文档

基于 ClickHouse DESIGN.md 结构，填充自己项目的实际设计 token。更新 README.md，添加指向 design.md 的链接。

注意事项

安全性：Markdown 渲染需要过滤不安全的 HTML。Astro 的内置渲染器默认会过滤 script 标签，但仍需注意 XSS 风险。

性能：大量 iframe 预览可能影响首屏加载。建议使用 loading="lazy" 延迟加载预览内容。

维护性：design.md 需要与代码实现保持同步。建议在 CI 中添加检查，确保 CSS 变量在文档和代码中一致。

可访问性：确保颜色对比度符合 WCAG AA 标准（至少 4.5:1）。

AI 使用指南

创建 design.md 之后，怎么让 AI 真正用它呢？这里有几个实用技巧：

技巧一：在提示词中明确引用

请参考项目根目录的 design.md 文件，使用其中定义的设计规范来实现以下组件：
- 按钮：使用 primary 色调，圆角 8px
- 卡片：使用 elevation-2 阴影层级

技巧二：要求 AI 引用具体的 CSS 变量

实现一个导航栏，要求：
- 背景色使用 --color-bg-primary
- 边框使用 --color-border-subtle
- 文字使用 --text-color-primary

技巧三：在系统提示词中包含 design.md 内容

如果你的 AI 工具支持自定义系统提示词，可以将 design.md 的核心内容直接添加进去。

测试策略

内容管线测试：

文件缺失场景（缺少 README.md 或 DESIGN.md）
格式错误场景（Markdown 解析失败）
空目录场景

搜索功能测试：

空结果处理
特殊字符（如中文、emoji）
URL 同步验证

UI 组件测试：

明/暗主题切换
响应式布局
预览加载状态

部署流程

# 1. 更新子模块到最新版本
git submodule update --remote

# 2. 重新构建站点
npm run build

# 3. 部署静态资源
npm run deploy

建议将子模块更新和构建部署自动化，可以在上游仓库更新时自动触发 CI 流程。

总结

HagiCode 在开发过程中遇到的 AI 生成 UI 不一致问题，本质上是缺少结构化的设计参考文档。通过构建设计画廊站点和创建规范化的 design.md，我们成功解决了这个问题。

这套方案的核心价值在于：

统一资源：整合分散的设计系统文档
结构化规范：将设计规范以 AI 可理解的形式呈现
持续维护：通过 git submodule 保持内容更新

如果你也在使用 AI 辅助前端开发，建议尝试一下这个方案。创建一份结构化的 design.md，不仅能提升 AI 生成代码的一致性，也能帮助团队内部保持设计规范的统一。

参考资料

VoltAgent/awesome-design-md - 设计系统文档集合
ClickHouse DESIGN.md - 设计文档结构参考
Astro 官方文档 - 静态站点生成框架
HagiCode 源码 - 本方案的实际实现

如果本文对你有帮助：

点个赞让更多人看到
来 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-04-08-design-md-consistent-ui/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

为什么使用 Skillsbase 维护自己的 Skills 收藏仓库

2026年4月7日

为什么使用 Skillsbase 维护自己的 Skills 收藏仓库

说起来也挺好笑的，AI 编程时代来了，我们手里的 Agent Skills 越来越多，可随之而来的麻烦也越来越多。这篇文章就是想聊聊我们是怎么用 skillsbase 解决这些问题的。

背景

在 AI 编程时代，开发者需要维护越来越多的 Agent Skills——这些是可复用的指令集，用于扩展 Claude Code、OpenCode、Cursor 等编码助手的能力。然而，随着技能数量的增长，一个现实问题逐渐浮现：

其实也不能说是什么大问题，只是东西多了，管理起来就麻烦了。

技能分散存储，管理成本高

本地技能散落在多个位置：~/.agents/skills/、~/.claude/skills/、~/.codex/skills/.system/ 等
不同位置可能存在命名冲突（例如 skill-creator 同时存在于用户目录和系统目录）
缺乏统一的管理入口，备份和迁移困难

这点挺烦人的。有时候你自己都不知道某个技能到底在哪，像丢了东西一样，找起来费劲。

缺乏标准化维护流程

手工复制技能容易出错，难以追踪来源
没有统一的验证机制，无法保证技能仓库的完整性
团队协作时，难以同步和共享技能集合

手工操作嘛，总是容易出错的。毕竟人的记忆力有限，谁记得住那么多东西是从哪来的呢？

无法满足可复现性要求

更换开发机器时，需要重新配置所有技能
CI/CD 环境中无法自动验证和同步技能仓库

换个电脑就得重新来一遍，这种感觉，怎么说呢，就像搬家一样麻烦。每次都得重新适应新的环境，重新配置所有东西。

为了解决这些痛点，我们尝试过多种方案：从手工复制到脚本自动化，从直接管理目录到全局安装再回收。每种方案都有各自的缺陷，要么无法保证一致性，要么污染环境，要么难以在 CI 中使用。

其实也是走了不少弯路。

最终，我们找到了一套更优雅的解决方案——skillsbase。这个方案的核心思想是：先本地安装验证，再转换结构写入仓库，最后卸载临时文件。这样既能确保仓库内容与实际安装结果一致，又不会污染全局环境。

说起来简单，只是踩了不少坑才琢磨出来罢了。

关于 HagiCode

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

HagiCode 是一个 AI 代码助手项目，在开发过程中我们需要维护大量的 Agent Skills 来扩展各种编码能力。正是这些实际需求，促使我们开发了 skillsbase 这套工具来规范化管理技能仓库。

其实这东西也不是凭空想出来的，都是被逼的。技能多了，自然就需要管理。管理的过程中遇到问题，自然就需要解决。一步一步，就走到今天了。

如果你对 HagiCode 感兴趣，可以访问官网了解更多或在 GitHub 上查看源码。

分析

技术挑战

要建立一个可维护的技能收藏仓库，需要解决以下核心问题：

统一命名空间冲突：当多个来源存在同名技能时，如何避免覆盖？
来源可追溯性：如何记录每个技能的来源，以便后续更新和审计？
同步与验证：如何确保仓库内容与实际安装结果一致？
自动化集成：如何与 CI/CD 流程集成，实现自动同步和验证？

这些问题看似简单，但每一个都够头疼的。不过话说回来，做什么事不难呢？

设计权衡

方案一：直接复制目录

优点：实现简单缺点：无法保证与 skills CLI 实际安装结果一致

这个方案嘛，说真的，我们也想过。只是后来发现，CLI 安装的时候可能有一些预处理逻辑，直接复制就跳过了。结果就是，复制的东西和实际装的东西不一样，这就有问题了。

方案二：全局安装后回收

优点：可以验证安装过程缺点：污染执行环境，CI 与本地结果难以保持一致

这个方案更糟糕。全局安装，会污染环境。更麻烦的是，CI 环境和本地环境很难保持一致，导致”本地能跑，CI 失败”的问题。这种感觉，谁懂啊？

方案三：本地安装 → 转换 → 卸载（最终方案）

这是 skillsbase 采用的方案：

先通过 npx skills 把技能安装到临时位置
转换目录结构并添加来源元数据
写入目标仓库
最后卸载临时文件

这种方案确保了仓库内容与实际消费者安装结果一致，同时不污染全局环境，转换过程可标准化，支持幂等操作。

其实这个方案也不是一开始就想到的，只是试错试多了，自然就知道什么可行、什么不可行了。

架构决策

决策项	选择	理由
运行时	Node.js ESM	无需构建步骤，`.mjs` 足以完成文件系统编排
配置格式	YAML (`sources.yaml`)	可读性强，支持人工维护
命名策略	命名空间前缀	用户技能保持原名，系统技能添加 `system-` 前缀
工作流	`add` 修改清单 → `sync` 执行同步	单一同步引擎，避免规则双份实现
文件管理	受管文件标识	添加注释头，支持安全覆盖

这些决策，说到底都是为了一个目标：让事情变得简单。毕竟，简单才是王道。

解决

CLI 架构

skillsbase CLI 提供四个核心命令：

skillsbase
├── init          # 初始化仓库结构
├── sync          # 同步技能内容
├── add           # 添加新技能
└── github_action # 生成 GitHub Actions 配置

命令不多，但也够了。毕竟，工具这东西，够用就好。

核心工作流

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    init     │───▶│    add      │───▶│    sync     │───▶│github_action│
│  初始化仓库  │    │  添加来源   │    │  同步内容   │    │  生成 CI    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

一步一步来，急不得。

同步流程设计

sources.yaml → 解析来源 → npx skills 安装 → 转换结构 → 写入 skills/ → 卸载临时文件
                              ↓
                        .skill-source.json (来源元数据)

这个流程设计得还算清晰。至少我自己看的时候，能明白每一步在做什么。

仓库结构

repos/skillsbase/
├── sources.yaml              # 来源清单（单一真相源）
├── skills/                   # 技能目录
│   ├── frontend-design/      # 用户技能
│   ├── skill-creator/        # 用户技能
│   └── system-skill-creator/ # 系统技能（带前缀）
├── scripts/
│   ├── sync-skills.mjs       # 同步脚本
│   └── validate-skills.mjs   # 验证脚本
├── docs/
│   └── maintainer-workflow.md # 维护者文档
└── .github/
    ├── workflows/
    │   └── skills-sync.yml   # CI 工作流
    └── actions/
        └── skillsbase-sync/
            └── action.yml     # 复用型 Action

文件多了点，不过也还好。毕竟，组织结构清晰了，维护起来也方便。

实践

初始化技能仓库

# 1. 创建空仓库
mkdir repos/myskills && cd repos/myskills
git init

# 2. 使用 skillsbase 初始化
npx skillsbase init

# 输出：
# [1/4] create manifest ................. done
# [2/4] create scripts .................. done
# [3/4] create docs ..................... done
# [4/4] create github workflow .......... done
#
# next: skillsbase add <skill-name>

这一步会生成一堆文件，不过不用担心，都是自动生成的。接下来就可以开始添加技能了。

添加技能

# 添加单个技能（会自动执行同步）
npx skillsbase add frontend-design --source vercel-labs/agent-skills

# 添加到本地来源
npx skillsbase add documentation-writer --source /home/user/.agents/skills

# 输出：
# source: first-party ......... updated
# target: skills/frontend-design ... synced
# status: 1 skill added, 0 removed

添加技能挺简单的，一条命令就够了。只是有时候会遇到一些意外情况，比如网络不好、权限问题之类的。不过这些都是小事，慢慢来。

同步技能

# 执行同步（对账所有来源）
npx skillsbase sync

# 仅检查是否漂移（不修改文件）
npx skillsbase sync --check

# 允许缺失来源（CI 场景）
npx skillsbase sync --allow-missing-sources

同步的时候，系统会把 sources.yaml 里定义的来源都检查一遍，然后和 skills/ 目录里的内容对账。有差异就更新，没差异就跳过。这样就不会出现”配置改了但文件没变”的问题。

生成 CI 配置

# 生成 workflow
npx skillsbase github_action --kind workflow

# 生成 action
npx skillsbase github_action --kind action

# 生成全部
npx skillsbase github_action --kind all

CI 配置也是自动生成的。只是你需要自己调整一些细节，比如触发条件、运行环境之类的。不过这些都不难。

sources.yaml 配置示例

# 技能根目录配置
skillsRoot: skills/
metadataFile: .skill-source.json

# 来源定义
sources:
  # 第一方：本地用户技能
  first-party:
    type: local
    path: /home/user/.agents/skills
    naming: original  # 保持原名
    includes:
      - documentation-writer
      - frontend-design
      - skill-creator

  # 系统：系统提供技能
  system:
    type: local
    path: /home/user/.codex/skills/.system
    naming: prefix-system  # 添加 system- 前缀
    includes:
      - imagegen
      - openai-docs
      - skill-creator  # 会变成 system-skill-creator

  # 远程：第三方仓库
  vercel:
    type: remote
    url: vercel-labs/agent-skills
    naming: original
    includes:
      - web-design-guidelines

这个配置文件是整个系统的核心。所有的来源都在这里定义，改了这里，下次同步就会生效。所以说，这算是一个”单一真相源”。

.skill-source.json 元数据示例

{
  "source": "first-party",
  "originalPath": "/home/user/.agents/skills/documentation-writer",
  "originalName": "documentation-writer",
  "targetName": "documentation-writer",
  "syncedAt": "2026-04-07T00:00:00.000Z",
  "version": "unknown"
}

每个技能目录下都会有这个文件，记录了它的来源信息。这样以后出问题的时候，能快速定位是从哪来的、什么时候同步的。

安全与验证

# 验证仓库结构
node scripts/validate-skills.mjs

# 使用 skills CLI 验证
npx skills add . --list

# 检查更新
npx skills check

验证这东西，说重要也重要，说没必要也没必要。不过为了保险起见，偶尔跑一下也无妨。毕竟，谁知道会不会有什么意外呢？

GitHub Actions 集成

name: Skills Sync

on:
  push:
    paths:
      - 'sources.yaml'
      - 'skills/**'
  workflow_dispatch:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate repository
        run: |
          npx skills add . --list
          node scripts/validate-skills.mjs
      - name: Sync check
        run: npx skillsbase sync --check

CI 集成之后，每次改 sources.yaml 或者 skills/ 目录，都会自动触发验证。这样就不会出现”本地改了忘了同步”的问题了。

最佳实践

命名冲突处理：系统技能统一添加 system- 前缀。这样既能保留所有技能，又能避免命名冲突。
幂等操作：所有命令支持重复执行，多次运行 sync 不会产生副作用。这点在 CI 里特别重要。
受管文件：生成的文件包含 # Managed by skillsbase CLI 注释，方便识别和管理。这些文件可以安全覆盖，手工修改不会被保留。
非交互模式：CI 环境默认使用确定性行为，不会因为交互式提示而中断。所有配置都通过 sources.yaml 声明。
来源可追溯：每个技能都有 .skill-source.json 记录来源信息，出问题的时候能快速定位。

团队协作

# 团队成员安装共享技能库
npx skills add your-org/myskills -g --all

# 本地克隆验证
git clone https://github.com/your-org/myskills.git
cd myskills
npx skills add . --list

通过 Git 管理技能仓库，团队成员可以轻松同步技能集合，确保每个人都使用相同版本的工具和配置。

这点在团队协作里特别有用，不会出现”我这边能跑你那边不行”的情况。毕竟，环境统一了，问题就少了一半。

总结

使用 skillsbase 维护技能收藏仓库的核心价值在于：

安全性：来源验证、冲突检测、受管文件保护
可维护性：统一入口、幂等操作、配置即文档
标准化：统一的目录结构、命名规范、元数据格式
自动化：CI/CD 集成、自动同步、自动验证

通过这套方案，开发者可以像管理 npm 包一样管理自己的 Agent Skills，实现可复现、可共享、可维护的技能仓库体系。

本文分享的这套工具和流程，正是我们在开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果你觉得这套方案有价值，说明我们的工程实践方向是正确的——那么 HagiCode 本身也值得关注一下。

毕竟，好的工具是值得被更多人使用的。

参考资料

skillsbase 仓库：github.com/HagiCode-org/skillsbase
HagiCode 官网：hagicode.com
HagiCode 源码：github.com/HagiCode-org/site
安装指南：docs.hagicode.com/installation/docker-compose
桌面端快速安装：hagicode.com/desktop/

如果本文对你有帮助：

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

本文首发于 HagiCode 博客

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-07-why-use-skillsbase-for-skills-repository/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

AI时代如何临摹项目：Vault跨项目持久化存储系统

2026年4月6日

AI时代如何临摹项目：Vault跨项目持久化存储系统

在AI辅助开发时代，如何让AI助手更好地理解我们的学习资源？HagiCode项目通过Vault系统实现了一个统一的、可被AI理解的知识存储抽象层，让临摹项目的学习效率大幅提升。

背景

在AI时代，开发者学习新技术和架构的方式正在发生深刻变化。“临摹项目”——即深入研究和学习优秀开源项目的代码、架构和设计模式——已经成为一种高效的学习方法。相比传统的读书、看视频，直接阅读和运行高质量的开源项目能让你更快地理解真实世界的工程实践。

只是这种学习方式也面临着不少挑战。

学习资料太分散了。你的笔记可能在Obsidian里，代码仓库散落在各个文件夹，AI助手的对话历史又是一个独立的数据孤岛。当你想让AI帮你分析某个项目时，得手动复制代码片段、整理上下文，这个过程相当繁琐。

其实更麻烦的是上下文断裂。AI助手无法直接访问你的本地学习资源，每次对话都得重新提供背景信息。而且临摹的代码仓库更新很快，手动同步容易出错，多个学习项目之间也难以共享知识。

这些问题本质上都是”数据孤岛”导致的。如果能有一个统一的存储抽象层，让AI助手能够理解和访问你的所有学习资源，问题就迎刃而解了。

关于 HagiCode

本文分享的Vault系统，正是我们在开发 HagiCode 过程中实践出来的解决方案。HagiCode 是一个AI代码助手项目，在我们的日常开发中，经常需要学习和参考各种开源项目。为了让AI助手更好地理解这些学习资源，我们设计了Vault跨项目持久化存储系统。

这套方案已经在HagiCode中经过了实际验证，如果你也面临类似的知识管理难题，希望这些经验能给你一些启发。毕竟，有些坑踩过了，总得留下点什么给后来的人。

Vault系统设计理念

Vault系统的核心思想很简单：创建一个统一的、可被AI理解的知识存储抽象层。从实现角度来看，系统具有几个关键特征。

多类型支持

系统支持四种vault类型，分别对应不同的使用场景：

// folder：通用文件夹类型
export const DEFAULT_VAULT_TYPE = 'folder';

// coderef：专门用于临摹代码项目的类型
export const CODEREF_VAULT_TYPE = 'coderef';

// obsidian：与Obsidian笔记软件集成
export const OBSIDIAN_VAULT_TYPE = 'obsidian';

// system-managed：系统自动管理的vault
export const SYSTEM_MANAGED_VAULT_TYPE = 'system-managed';

其中 coderef 类型是HagiCode中最常用的。它专门为临摹代码项目设计，提供了标准化的目录结构和AI可读的元数据描述。

持久化存储机制

Vault的注册表以JSON格式持久化存储，确保配置在应用重启后仍然可用：

public class VaultRegistryStore : IVaultRegistryStore
{
    private readonly string _registryFilePath;

    public VaultRegistryStore(IConfiguration configuration, ILogger<VaultRegistryStore> logger)
    {
        var dataDir = configuration["DataDir"] ?? "./data";
        var absoluteDataDir = Path.IsPathRooted(dataDir)
            ? dataDir
            : Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), dataDir));

        _registryFilePath = Path.Combine(absoluteDataDir, "personal-data", "vaults", "registry.json");
    }
}

这种设计的好处是简单可靠。JSON格式人类可读，便于调试和手动修改；文件系统存储避免了数据库的复杂性，降低了系统的依赖。毕竟，有时候简单的反而是最好的。

AI上下文集成

最关键的是，系统能够自动将vault信息注入到AI提案的上下文中：

export function buildTargetVaultsText(
  vaults: VaultForText[],
  template: VaultPromptTemplate = DEFAULT_VAULT_PROMPT_TEMPLATE,
): string {
  const readOnlyVaults = vaults.filter((vault) => vault.accessType === 'read');
  const editableVaults = vaults.filter((vault) => vault.accessType === 'write');

  if (readOnlyVaults.length === 0 && editableVaults.length === 0) {
    return '';
  }

  const sections = [
    buildVaultSection(readOnlyVaults, template.reference),
    buildVaultSection(editableVaults, template.editable),
  ].filter(Boolean);

  return `\n\n### ${template.heading}\n\n${sections.join('\n')}`;
}

这样就实现了一个重要的功能：AI助手能够自动理解可用的学习资源，无需用户手动提供上下文。这倒也算是一种默契了。

CodeRef Vault的标准化结构

对于coderef类型的vault，HagiCode提供了一套标准化的目录结构：

my-coderef-vault/
├── index.yaml          # vault元数据描述
├── AGENTS.md           # AI助手的操作指南
├── docs/               # 存放学习笔记和文档
└── repos/              # 通过Git子模块管理临摹的代码仓库

创建vault时，系统会自动初始化这个结构：

private async Task EnsureCodeRefStructureAsync(
    string vaultName,
    string physicalPath,
    ICollection<VaultBootstrapDiagnosticDto> diagnostics,
    CancellationToken cancellationToken)
{
    Directory.CreateDirectory(physicalPath);

    var indexPath = Path.Combine(physicalPath, CodeRefIndexFileName);
    var docsPath = Path.Combine(physicalPath, CodeRefDocsDirectoryName);
    var reposPath = Path.Combine(physicalPath, CodeRefReposDirectoryName);

    // 创建标准目录结构
    if (!Directory.Exists(docsPath))
    {
        Directory.CreateDirectory(docsPath);
    }

    if (!Directory.Exists(reposPath))
    {
        Directory.CreateDirectory(reposPath);
    }

    // 创建AGENTS.md指南
    await EnsureCodeRefAgentsDocumentAsync(physicalPath, cancellationToken);

    // 创建index.yaml元数据
    await WriteCodeRefIndexDocumentAsync(indexPath, mergedDocument, cancellationToken);
}

这套结构的设计也是有讲究的：

docs/ 目录存放你的学习笔记，可以用Markdown格式记录对代码的理解、架构分析、踩坑经验等
repos/ 目录通过Git子模块管理临摹的仓库，而不是直接复制代码。这样既能保持代码同步，又能节省空间
index.yaml 包含vault的元数据，让AI助手快速理解这个vault的用途和内容
AGENTS.md 是专门写给AI助手看的指南，说明如何处理这个vault中的内容

或许这样组织起来，AI也能更容易理解你的想法吧。

系统管理的自动初始化

除了手动创建vault，HagiCode还支持系统自动管理的vault：

public async Task<IReadOnlyList<VaultRegistryEntry>> EnsureAllSystemManagedVaultsAsync(
    CancellationToken cancellationToken = default)
{
    var definitions = GetAllResolvedDefinitions();
    var entries = new List<VaultRegistryEntry>(definitions.Count);

    foreach (var definition in definitions)
    {
        entries.Add(await EnsureResolvedSystemManagedVaultAsync(definition, cancellationToken));
    }

    return entries;
}

系统会自动创建和管理以下vault：

hagiprojectdata：项目数据存储，用于保存项目的配置和状态
personaldata：个人数据存储，用于保存用户的偏好设置
hbsprompt：提示词模板库，用于管理常用的AI提示词

这些vault在系统启动时自动初始化，无需用户手动配置。毕竟，有些事情交给系统去做就好了，人类何必操心呢。

访问控制机制

一个重要的设计是访问控制。系统将vault分为两种访问类型：

export interface VaultForText {
  id: string;
  name: string;
  type: string;
  physicalPath: string;
  accessType: 'read' | 'write';  // 关键：区分只读和可编辑
}

reference（只读）：AI仅用于分析和理解，不能修改内容。适用于参考的开源项目、文档等
editable（可编辑）：AI可以根据任务需要修改内容。适用于你的笔记、草稿等

这种区分很重要。它让AI知道哪些内容是”只读参考”，哪些是”可以动手改的”，避免了误操作风险。毕竟，谁也不想自己的心血被无意中改没了。

实战：创建和使用Vault

看完了原理，咱们来看看实际怎么用。

创建CodeRef Vault

以下是一个完整的前端调用示例：

const createCodeRefVault = async () => {
  const response = await VaultService.postApiVaults({
    requestBody: {
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/Users/developer/vaults/react-learning",
      gitUrl: "https://github.com/facebook/react.git"
    }
  });

  // 系统会自动：
  // 1. 克隆React仓库到vault/repos/react
  // 2. 创建docs/目录用于笔记
  // 3. 生成index.yaml元数据
  // 4. 创建AGENTS.md指南文件

  return response;
};

这个API调用会完成一系列操作：创建目录结构、初始化Git子模块、生成元数据文件等。你只需要提供基本信息，剩下的交给系统处理。其实这样也挺省心的。

在AI提案中使用Vault

创建好vault后，就可以在AI提案中引用它了：

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "帮我分析React的并发渲染机制",
  repositories: [
    { id: "react", gitUrl: "https://github.com/facebook/react.git" }
  ],
  vaults: [
    {
      id: "react-learning",
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/vaults/react-learning",
      accessType: "read"  // AI只能读取，不能修改
    }
  ],
  quickRequestText: "重点关注fiber架构和scheduler实现"
});

系统会自动将vault信息注入到AI的上下文中，让AI知道你有哪些学习资源可用。AI能理解你的想法，这倒也算是一种难得的默契了。

最佳实践和注意事项

在使用Vault系统的过程中，我们总结了一些经验教训。

路径安全

系统会严格校验路径，防止路径穿越攻击：

private static string ResolveFilePath(string vaultRoot, string relativePath)
{
    var rootPath = EnsureTrailingSeparator(Path.GetFullPath(vaultRoot));
    var combinedPath = Path.GetFullPath(Path.Combine(rootPath, relativePath));
    if (!combinedPath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode,
            "Vault file paths must stay inside the registered vault root.");
    }
    return combinedPath;
}

这点很重要。如果你在自定义vault路径，一定要确保路径在允许的范围内，否则系统会拒绝操作。安全这东西，怎么强调都不过分。

Git子模块管理

CodeRef vault推荐使用Git子模块而非直接复制代码：

private static string BuildCodeRefAgentsContent()
{
    return """
    # CodeRef Vault Guide

    Repositories under `repos/` should be maintained through Git submodules
    rather than copied directly into the vault root.

    Keep this structure stable so assistants and tools can understand the vault quickly.
    """ + Environment.NewLine;
}

这样做有几个好处：保持代码与上游同步、节省磁盘空间、便于管理多个版本的代码。毕竟，谁愿意一遍遍地重复下载同样的东西呢。

文件预览限制

为了防止性能问题，系统限制了文件大小和类型：

private const int FileEnumerationLimit = 500;
private const int PreviewByteLimit = 256 * 1024;  // 256KB

如果你的vault包含大量文件或超大文件，可能会影响预览功能的性能。这种情况下可以考虑分批处理或使用专门的搜索工具。毕竟，有些东西太大了，反而不好处理。

诊断信息

创建vault时会返回诊断信息，帮助调试：

List<VaultBootstrapDiagnosticDto> bootstrapDiagnostics = [];

if (IsCodeRefVaultType(normalizedType))
{
    bootstrapDiagnostics = await EnsureCodeRefBootstrapAsync(
        normalizedName,
        normalizedPhysicalPath,
        normalizedGitUrl,
        cancellationToken);
}

如果创建失败，可以查看诊断信息了解具体原因。出错了就看看诊断信息，这倒也是一种解决问题的方法。

总结

Vault系统通过统一的存储抽象层，解决了AI时代临摹项目的核心痛点：

知识集中管理：所有学习资源集中在一个地方，不再散落各处
AI上下文自动注入：AI助手能够自动理解可用的学习资源，无需手动提供上下文
跨项目知识复用：多个学习项目之间可以共享和复用知识
标准化目录结构：提供一致的目录结构，降低学习成本

这套方案在HagiCode项目中已经经过了实际验证。如果你也在做AI辅助开发相关的工具，或者面临类似的知识管理问题，希望这些经验能给你一些参考。

其实技术方案的价值不在于有多复杂，而在于能不能解决实际问题。Vault系统的核心思想很简单——就是建立一个统一的、AI可理解的知识存储层。但正是这个简单的抽象，让我们的开发效率提升了不少。

有时候，简单的反而是最好的。毕竟，复杂的东西往往藏着更多的坑…

参考资料

HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
HagiCode 安装文档：docs.hagicode.com/installation/docker-compose
Obsidian 官网：obsidian.md
Git 子模块文档：git-scm.com/docs/gitsubmodules

如果本文对你有帮助，欢迎来 GitHub 给个 Star，或者访问官网了解更多关于HagiCode的信息。公测已开始，现在安装即可体验完整的AI代码助手功能。

或许，你也可以试试看…

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-06-vault-persistent-storage-for-ai-era/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

渐进式披露：如何用少即是多的理念改进 AI 产品的人机交互

2026年4月5日

渐进式披露：如何用”少即是多”的理念改进 AI 产品的人机交互

在 AI 产品设计中，用户输入的质量往往决定了输出的质量。本文分享我们在 HagiCode 项目中实践的一套”渐进式披露”交互方案，通过分步引导、智能补全和即时反馈，将用户简短模糊的输入转化为结构化的技术提案，显著提升了人机交互效率。

背景

做 AI 产品的同学应该都遇到过这样的场景：用户打开你的应用，兴致勃勃地输入一行需求，结果 AI 返回的内容完全不搭边。不是 AI 不聪明，只是用户给的信息太少了，毕竟猜心这种事，谁也做不好。

这种现象在我们开发 HagiCode 的过程中尤为明显。HagiCode 是一个 AI 驱动的代码助手，用户通过自然语言描述需求来创建技术提案和会话。可在实际使用中，我们发现用户输入的内容往往存在这些问题：

输入质量参差不齐：有的用户只输入几个字，比如”优化登录”、“修复 bug”，缺乏必要的上下文
技术术语不统一：不同用户用不同的词说同一件事，有人说”前端”有人说”FE”
缺少结构化信息：没有项目背景、没有仓库范围、没有影响范围这些关键信息
重复性问题：相同类型的需求反复出现，每次都要从头解释

这些问题导致的直接后果就是：AI 理解困难、生成的提案质量不稳定、用户体验差。用户觉得”这 AI 不行啊”，我们也很委屈——你只给一句话，让我怎么猜你想要啥？

其实这也没办法，毕竟人和人之间的理解都需要时间，更何况是机器呢？

为了解决这些痛点，我们做了一个大胆的决定：引入”渐进式披露”的设计理念来改进人机交互。这个决定带来的变化，可能比你想象的还要大，只是当时我们也没想到会这么有效罢了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，旨在通过自然语言交互帮助开发者完成代码编写、技术提案生成、代码审查等任务。项目地址：github.com/HagiCode-org/site。

这套渐进式披露方案是我们在实际开发过程中，经过多次迭代和优化总结出来的。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下，毕竟好东西是值得分享的。

什么是渐进式披露

“渐进式披露”（Progressive Disclosure）是一个源自 HCI（人机交互）领域的设计原则，核心思想很简单：不要一次性把所有信息和选项都展示给用户，而是根据用户的操作和需求，逐步展示必要的内容。

这个原则特别适合 AI 产品，因为 AI 交互天然就是渐进式的——用户说一点，AI 理解一点，然后补充一点，再理解更多。就像人与人之间的交流一样，总得慢慢来，毕竟谁也不能一见面就把心掏出来不是？

具体到 HagiCode 的场景，我们从四个方面实施了渐进式披露：

1. 描述优化机制：让 AI 帮你把话说清楚

当用户输入简短描述时，我们不是直接让 AI 去理解，而是先触发一个”描述优化”流程。这个流程的核心是”结构化输出”——把用户的自由文本转化为标准格式。就像把散落一地的珍珠串成项链，看起来也就不那么乱了。

优化后的描述必须包含以下几个标准章节：

背景：问题背景和上下文
分析：技术分析和思考过程
解决：解决方案和实施步骤
实践：实际代码示例和注意事项

同时，我们还会自动生成一个 Markdown 表格，展示目标仓库、路径、编辑权限等信息，方便 AI 后续操作。毕竟有个清晰的目录，找起东西来也方便。

下面是实际的代码实现：

// ProposalDescriptionMemoryService.cs 中的核心方法
public async Task<string> OptimizeDescriptionAsync(
    string title,
    string description,
    string locale = "zh-CN",
    DescriptionOptimizationMemoryContext? memoryContext = null,
    CancellationToken cancellationToken = default)
{
    // 构建查询参数
    var queryContext = BuildQueryContext(title, description);

    // 检索历史上下文
    var memoryContext = await RetrieveHistoricalContextAsync(queryContext, cancellationToken);

    // 生成结构化提示词
    var prompt = await BuildOptimizationPromptAsync(
        title,
        description,
        memoryContext,
        cancellationToken);

    // 调用 AI 进行优化
    return await _aiService.CompleteAsync(prompt, cancellationToken);
}

这个流程的关键在于”记忆注入”——我们会把项目惯例、相似案例、负面模式等历史上下文注入到提示词中，让 AI 在优化时能够参考过去的经验。毕竟吃一堑长一智，过去的经验总不能白白浪费了不是？

注意事项：

确保当前输入优先于历史记忆，避免覆盖用户显式指定的信息
HagIndex 引用必须作为事实来源，不得被历史案例修改
低置信度的纠错建议不应作为强约束注入

2. 语音输入能力：说话比打字更自然

除了文本输入，我们还支持语音输入。这在描述复杂需求时特别有用——你想想，打一段技术需求可能要几分钟，但说可能几十秒就完事了，毕竟嘴总是比手快。

语音输入的设计重点是”状态管理”，用户必须清楚当前系统处于什么状态。我们定义了以下几种状态：

空闲：系统就绪，可以开始录制
等待上游：正在连接后端服务
录制中：正在录制用户语音
处理中：正在将语音转换为文本
错误：发生错误，需要用户处理

前端的状态模型大概是这样的：

interface VoiceInputState {
  status: 'idle' | 'waiting-upstream' | 'recording' | 'processing' | 'error';
  duration: number;
  error?: string;
  deletedSet: Set<string>; // 已删除结果的指纹集合
}

// 开始录制时的状态转换
const handleVoiceInputStart = async () => {
  // 先进入等待状态，显示加载动画
  setState({ status: 'waiting-upstream' });

  // 等待后端就绪确认
  const isReady = await waitForBackendReady();
  if (!isReady) {
    setState({ status: 'error', error: '后端服务未就绪' });
    return;
  }

  // 开始录制
  setState({ status: 'recording', startTime: Date.now() });
};

// 处理识别结果
const handleRecognitionResult = (result: RecognitionResult) => {
  const fingerprint = normalizeFingerprint(result.text);

  // 检查是否已被删除
  if (state.deletedSet.has(fingerprint)) {
    return; // 跳过已删除的内容
  }

  // 合并结果到文本框
  appendResult(result);
};

这里有个细节：我们用”指纹集合”来管理删除同步。当语音识别返回多条结果时，用户可能会删除其中一些。我们把已删除内容的指纹存起来，后续如果相同内容再出现就自动跳过。这就像记住了哪些菜不爱吃，下次就不会再点了，毕竟谁也不想被同样的问题困扰两次。

3. 提示词管理系统：把 AI 的”脑子”外置

HagiCode 有一个灵活的提示词管理系统，所有提示词都以文件形式存储：

prompts/
├── metadata/
│   ├── optimize-description.zh-CN.json
│   └── optimize-description.en-US.json
└── templates/
    ├── optimize-description.zh-CN.hbs
    └── optimize-description.en-US.hbs

每个提示词由两部分组成：

元数据文件（.json）：定义提示词的场景、版本、参数等信息
模板文件（.hbs）：使用 Handlebars 语法的实际提示词内容

元数据文件的格式是这样的：

{
  "scenario": "optimize-description",
  "locale": "zh-CN",
  "version": "1.0.0",
  "syntax": "handlebars",
  "syntaxVersion": "1.0",
  "parameters": [
    {
      "name": "title",
      "type": "string",
      "required": true,
      "description": "提案标题"
    },
    {
      "name": "description",
      "type": "string",
      "required": true,
      "description": "原始描述"
    }
  ],
  "author": "HagiCode Team",
  "description": "优化用户输入的技术提案描述",
  "lastModified": "2026-04-05",
  "tags": ["optimization", "nlp"]
}

模板文件使用 Handlebars 语法，支持参数注入：

你是一个技术提案专家。

<task>
根据以下信息生成结构化的技术提案描述。
</task>

<input>
<title>{{title}}</title>
<description>{{description}}</description>
{{#if memoryContext}}
<memory_context>
{{memoryContext}}
</memory_context>
{{/if}}
</input>

<output_format>
## 背景
[描述问题背景和上下文，包括项目信息、仓库范围等]

## 分析
[技术分析和思考过程，说明为什么需要这个改动]

## 解决
[解决方案和实施步骤，列出关键代码位置]

## 实践
[实际代码示例和注意事项]
</output_format>

这种设计的好处是：

提示词可以像代码一样版本管理
支持多语言，根据用户偏好自动切换
参数化设计，可以动态注入上下文
启动时验证完备性，避免运行时出错

毕竟脑子里的东西不写下来，谁也不知道什么时候就忘了，与其到时候懊悔，不如一开始就做好记录罢了。

4. 渐进式向导：复杂任务拆成小步

对于复杂任务（比如首次安装配置），我们使用了多步骤向导的设计。每个步骤只请求必要信息，并提供清晰的进度指示。生活也是这样嘛，一口吃不成胖子，一步一步来反而更稳妥。

向导的状态模型：

interface WizardState {
  currentStep: number;           // 0-3，对应 4 个步骤
  steps: WizardStep[];
  canGoNext: boolean;
  canGoBack: boolean;
  isLoading: boolean;
  error: string | null;
}

interface WizardStep {
  id: number;
  title: string;
  description: string;
  completed: boolean;
}

// 步骤导航逻辑
const goToNextStep = () => {
  if (wizardState.currentStep < wizardState.steps.length - 1) {
    // 验证当前步骤的输入
    if (validateCurrentStep()) {
      wizardState.currentStep++;
      wizardState.steps[wizardState.currentStep - 1].completed = true;
    }
  }
};

const goToPreviousStep = () => {
  if (wizardState.currentStep > 0) {
    wizardState.currentStep--;
  }
};

每个步骤都有独立的验证逻辑，已完成步骤会有清晰的视觉标记。取消操作会弹出确认对话框，防止用户误操作丢失进度。毕竟走错路可以回头，但如果把路都拆了，那就真的没辙了。

总结

回顾 HagiCode 的渐进式披露实践，我们可以总结出几个核心原则：

分步引导：把复杂任务拆成小步，每步只请求必要信息
智能补全：利用历史上下文和项目知识自动补全信息
即时反馈：每个操作都有清晰的视觉反馈和状态提示
容错机制：允许用户撤销、重置，避免错误造成不可逆损失
输入多样化：支持文本、语音等多种输入方式

这套方案在 HagiCode 中的实际效果是：用户输入的平均长度从不到 20 字提升到了结构化的 200-300 字，AI 生成的提案质量显著提高，用户满意度也跟着上来了。

其实这也不奇怪，毕竟你给的信息越多，AI 理解得越准确，返回的结果自然就越好，这和人与人之间的交流也没什么两样。

如果你也在做 AI 相关的产品，希望这些经验能给你带来一些启发。记住：用户不是不想给信息，而是你还没问对问题。渐进式披露的核心，就是找到问问题的最佳时机和方式，只是这个时机和方式，需要一点耐心去摸索罢了。

参考资料

HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
渐进式披露设计原则：Wikipedia - Progressive Disclosure
Handlebars 模板引擎：handlebarsjs.com

如果本文对你有帮助，欢迎来 GitHub 给个 Star，关注 HagiCode 项目的后续发展。公测已经开始，现在安装即可体验完整功能：

GitHub：github.com/HagiCode-org/site
官网：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose 一键安装：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

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

AI 输出 Token 优化：文言文极简模式的实践

2026年4月4日

AI 输出 Token 优化：文言文极简模式的实践

在 AI 应用开发中，token 消耗直接影响成本。HagiCode 项目通过 SOUL 系统实现了”文言文极简输出模式”，在不损失信息密度的前提下，将输出 token 降低约 30-50%。本文分享这套方案的实现细节和使用经验。

背景

在 AI 应用开发中，token 消耗是个绕不开的成本问题。尤其是需要 AI 输出大量内容的场景，怎么在不损失信息密度的情况下降低输出 token，这问题想多了也挺让人头疼。

传统的优化思路都集中在输入端：精简系统提示词、压缩上下文、用更高效的编码方式。只是这些方法终究会碰到天花板，再压缩就可能影响 AI 的理解能力和输出质量了。这无异于删减内容，意义不大。

那输出端呢？能不能让 AI 用更简洁的方式表达同样的意思？

这问题看似简单，其实藏着不少门道。直接让 AI”简洁点”，它可能真的就只给几个词；加上”保持信息完整”，它又可能回复到原来的冗长风格。约束太强影响可用性，约束太弱没有效果，这中间的平衡点在哪，谁也说不准。

为了解决这些痛点，我们做了一个大胆的决定：从语言风格入手，设计一套可配置、可组合的表达方式约束系统。这个决定带来的变化，可能比你想象的还要大——稍后我会具体说，或许你会有些意外。

关于 HagiCode

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

HagiCode 是一个开源的 AI 代码助手项目，支持多种 AI 模型和自定义配置。在开发过程中，我们发现了 AI 输出 token 过高的问题，并设计了一套解决方案。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下，毕竟代码不会撒谎。

SOUL 系统概览

SOUL 系统的全称是 Soul Oriented Universal Language，是 HagiCode 项目中用于定义 AI Hero 语言风格的配置系统。它的核心思想是：通过约束 AI 的表达方式，在保持信息完整性的前提下，使用更简洁的语言形式来输出内容。

这东西就像给 AI 戴上了一个语言面具…罢了，其实也没那么玄乎。

技术架构

SOUL 系统采用前后端分离的架构：

前端（Soul Builder）：

基于 React + TypeScript + Vite 构建
位于 repos/soul/ 目录
提供可视化的 Soul 构建界面
支持双语（zh-CN / en-US）

后端：

基于 .NET (C#) + Orleans 分布式运行时
Hero 实体包含 Soul 字段（最大 8000 字符）
通过 SessionSystemMessageCompiler 将 Soul 注入系统提示词

Agent Templates 生成：

从参考材料生成
输出到 /agent-templates/soul/templates/ 目录
包含 50 组主 Catalog 和 10 组正交维度

Soul 注入机制

在 Session 首次执行时，系统会读取 Hero 的 Soul 配置，将其注入到系统提示词中：

sequenceDiagram
    participant UI as 用户界面
    participant Session as SessionGrain
    participant Hero as Hero 仓库
    participant AI as AI 执行器

    UI->>Session: 发送消息（绑定 Hero）
    Session->>Hero: 读取 Hero.Soul
    Session->>Session: 缓存 Soul 快照
    Session->>AI: 构建 AIRequest（注入 Soul）
    AI-->>Session: 执行结果
    Session-->>UI: 流式响应

注入的系统提示词格式为：

<hero_soul>
[用户自定义的 Soul 内容]
</hero_soul>

这套注入机制在 SessionSystemMessageCompiler.cs 中实现：

internal static string? BuildSystemMessage(
    string? existingSystemMessage,
    string? languagePreference,
    IReadOnlyList<HeroTraitDto>? traits,
    string? soul)
{
    var segments = new List<string>();

    // ... 语言偏好和 Traits 处理 ...

    var normalizedSoul = NormalizeSoul(soul);
    if (!string.IsNullOrWhiteSpace(normalizedSoul))
    {
        segments.Add($"<hero_soul>\n{normalizedSoul}\n</hero_soul>");
    }

    // ... 其他系统消息 ...

    return segments.Count == 0 ? null : string.Join("\n\n", segments);
}

代码也看了，原理也懂了，其实就这么回事。

文言文极简模式

文言文极简模式是 SOUL 系统中最具代表性的节约 token 方案。它的核心原理是利用文言文的高语义密度特性，在保持信息完整的前提下压缩输出长度。

为什么是文言文

文言文具有几个天然优势：

语义压缩：相同含义可以用更少的字符表达
去除冗余：文言文本身就省略了很多现代汉语中的连接词和助词
结构简洁：单句信息密度高，适合作为 AI 输出的载体

以一个实际例子来说明：

现代汉语输出（约 80 字）：

根据你的代码分析，我发现了几个问题。首先，在第 23 行，变量名太长了，建议缩短一些。其次，在第 45 行，你没有处理空值的情况，应该加上判断逻辑。最后，整体的代码结构还可以，但是可以进一步优化。

文言文极简输出（约 35 字，节约 56%）：

代码审阅毕：第 23 行变量名冗长，宜缩写；第 45 行缺空值处理，应加判断。整体结构尚可，微调即可。

这差距，想想也挺有意思的。

Soul 配置模板

文言文极简模式的完整 Soul 配置如下：

{
  "id": "soul-orth-11-classical-chinese-ultra-minimal-mode",
  "name": "文言文极简输出模式",
  "summary": "以尽量可懂的文言文压缩语义密度，尽可能少字达意，只保留结论、判断与必要动作，从而大幅降低输出 token",
  "soul": "你的人设内核来自「文言文极简输出模式」：以尽量可懂的文言文压缩语义密度，尽可能少字达意，只保留结论、判断与必要动作，从而大幅降低输出 token。\n保持以下标志性语言特征：1. 优先使用简明文言句式，如「可」「宜」「勿」「已」「然」「故」等，避免生僻艰涩字词；\n2. 单句尽量压缩至 4-12 字，删除铺垫、寒暄、重复解释与无效修饰；\n3. 非必要不展开论证，用户未追问则只给结论、步骤或判断；\n4. 不改变主 Catalog 的核心人设，只将表达收束为克制、古雅、极简的短句。"
}

这个模板的设计有几个要点：

约束明确：单句 4-12 字，删除冗余，结论优先
避免晦涩：使用简明文言句式，避免生僻字词
保持人设：只改变表达方式，不改变核心人设

配置这东西，调来调去也就那么几个参数罢了。

其他极简模式

除了文言文模式，HagiCode 的 SOUL 系统还提供了其他多种节约 token 的模式：

电报式极简输出模式（soul-orth-02）：

单句严格控制在 10 字以内
禁止修饰性形容词
全程无语气词、感叹号、叠词

短句碎碎念模式（soul-orth-01）：

句子控制在 1-5 个字
模拟自言自语的碎片化表达
弱化逻辑，优先传递情绪

引导式问答模式（soul-orth-03）：

通过提问引导用户思考
减少直接输出内容
交互式降低 token 消耗

这些模式的设计思路各有侧重，但核心目标是一致的：在保持信息质量的前提下降低输出 token。条条大路通罗马，只是有的路好走一点，有的路稍微曲折一点罢了。

组合策略

SOUL 系统的一个强大特性是支持主 Catalog 与正交维度的交叉组合：

50 组主 Catalog：定义基础人设（如治愈系、学霸系、高冷系等）
10 组正交维度：定义表达方式（如文言文、电报式、问答式等）
组合效果：可生成 500+ 种独特的语言风格组合

例如，你可以将”专业开发工程师”与”文言文极简输出模式”组合，得到一个既专业又简洁的 AI 助手。这种灵活性让 SOUL 系统能够适应各种不同使用场景。想怎么配就怎么配，反正组合多得你玩不过来…

实践指南

通过 Soul Builder 创建

访问 soul.hagicode.com，按以下步骤操作：

选择主 Catalog（如”专业开发工程师”）
选择正交维度（如”文言文极简输出模式”）
预览生成的 Soul 内容
复制生成的 Soul 配置

点点点的事情，应该不用我多说吧。

在 Hero 配置中使用

通过 Web 界面或 API，将 Soul 配置应用到 Hero：

// Hero Soul 更新示例
const heroUpdate = {
  soul: "你的人设内核来自「文言文极简输出模式」：...",
  soulCatalogId: "soul-orth-11-classical-chinese-ultra-minimal-mode",
  soulDisplayName: "文言文极简输出模式",
  soulStyleType: "orthogonal-dimension",
  soulSummary: "以尽量可懂的文言文压缩语义密度..."
};

await updateHero(heroId, heroUpdate);

自定义 Soul 模板

用户可以基于预设模板进行微调，或完全自定义。下面是一个代码审查场景的自定义示例：

你是一位追求极致简洁的代码审查员。
所有输出必须遵循：
1. 仅指出具体问题和行号
2. 每条问题不超过 15 字
3. 使用「宜」「应」「勿」等简洁词汇
4. 不做多余解释

示例输出：
- 第 23 行：变量名过长，宜缩写
- 第 45 行：未处理空值，应加判断
- 第 67 行：逻辑冗余，可简化

想怎么改就怎么改，反正模板这东西也只是个起点而已。

注意事项

兼容性：

文言文模式适配全部 50 组主 Catalog
可与任何基础人设组合使用
不会改变主 Catalog 的核心人设

缓存机制：

Soul 在 Session 首次执行时缓存
同一 SessionId 内复用缓存
修改 Hero 配置不影响已启动的 Session

限制约束：

Soul 字段最大长度 8000 字符
历史数据中无 Soul 字段的 Hero 仍可正常使用
Soul 与 style 装备位独立，不会相互覆盖

效果对比

根据项目的实际测试数据，使用文言文极简模式后的效果如下：

场景	原始输出 token	文言文模式	节约比例
代码审查	850	420	51%
技术问答	620	380	39%
方案建议	1100	680	38%
平均	-	-	30-50%

数据来自 HagiCode 项目的实际使用统计，具体效果因场景而异。不过省下来的 token，积少成多，钱包会感谢你的。

总结

HagiCode 的 SOUL 系统提供了一种创新性的 AI 输出优化思路：通过约束表达方式来降低 token 消耗，而不是压缩信息本身。文言文极简模式作为其中最具代表性的方案，在实际使用中取得了 30-50% 的 token 节约效果。

这套方案的核心价值在于：

保持信息质量：不是简单截断输出，而是用更高效的方式表达
灵活可组合：支持 500+ 种人设与表达方式的组合
易于使用：通过 Soul Builder 可视化界面，无需编写代码
生产级稳定：已在项目中验证，支持大规模使用

如果你也在开发 AI 应用，或者对 HagiCode 项目感兴趣，欢迎来交流。开源的意义在于共同进步，也期待看的到你的创新用法。毕竟，一个人走得快，一群人走得远…这话说得挺俗套，但道理就是这么个道理。

参考资料

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode 官网: hagicode.com
Soul Builder: soul.hagicode.com
Docker 部署指南: docs.hagicode.com/installation/docker-compose
Desktop 桌面端: hagicode.com/desktop/
30 分钟实战演示: www.bilibili.com/video/BV1pirZBuEzq/

如果本文对你有帮助：

来 GitHub 给个 Star：github.com/HagiCode-org/site
访问官网了解更多：hagicode.com
公测已开始，欢迎安装体验

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-04-soul-token-optimization-classical-chinese/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

从 CLI 调用到 SDK 集成：GitHub Copilot 在 .NET 项目中的最佳实践

2026年4月3日

从 CLI 调用到 SDK 集成：GitHub Copilot 在 .NET 项目中的最佳实践

从命令行调用到官方 SDK 集成的升级之路，说起来也算是一段经历，今天就分享我们在 HagiCode 项目中踩过的坑和学到的东西。

背景

GitHub Copilot SDK 在 2025 年正式发布后，我们开始将其集成到 AI 能力层中。在此之前，项目主要通过直接调用 Copilot CLI 命令行工具来使用 GitHub Copilot 能力，这种方式其实也存在几个明显问题：

进程管理复杂：需要手动管理 CLI 进程的生命周期、启动超时和进程清理——毕竟进程这东西，说崩溃就崩溃了，也没什么预兆
事件处理不完整：原始 CLI 调用难以捕获模型推理过程和工具执行的细粒度事件，就像只能看到结果，却看不到思考的过程
会话管理困难：缺乏有效的会话复用和恢复机制，每次都得重新开始，想想也是挺累的
兼容性问题：CLI 参数更新频繁，需要持续维护参数兼容性逻辑，这无异于和风车作战了

这些问题在日常开发中逐渐显现，特别是在需要实时追踪模型推理过程（thinking）和工具执行状态时，CLI 调用的局限性尤为明显。我们也算是想明白了，需要一个更底层、更完整的集成方式——毕竟，条条大路通罗马，只是有的路好走一点，有的路稍微曲折一点罢了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，在开发过程中我们需要深度集成 GitHub Copilot 的各种能力——从基础的代码补全到复杂的多轮对话和工具调用。这些实际需求推动我们从 CLI 调用升级到了官方 SDK 集成。

如果你对本文的实践方案感兴趣，说明我们的工程实践可能对你有帮助——那么 HagiCode 项目本身也值得关注一下。或许在文末你会发现更多关于项目的信息和链接，谁知道呢…

架构设计

项目采用了分层架构来解决 CLI 调用的问题：

┌─────────────────────────────────────────────────────────┐
│  hagicode-core (Orleans Grains + AI Provider Layer)    │
│  - CopilotAIProvider: 将 AIRequest 转换为 CopilotOptions │
│  - GitHubCopilotGrain: Orleans 分布式执行接口            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  HagiCode.Libs (Shared Provider Layer)                 │
│  - CopilotProvider: CLI Provider 接口实现               │
│  - ICopilotSdkGateway: SDK 调用抽象                     │
│  - GitHubCopilotSdkGateway: SDK 会话管理与事件分发     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  GitHub Copilot SDK (Official .NET SDK)                │
│  - CopilotClient: SDK 客户端                            │
│  - CopilotSession: 会话管理                             │
│  - SessionEvent: 事件流                                 │
└─────────────────────────────────────────────────────────┘

这种分层设计带来的技术优势，其实也还挺实用的：

关注点分离：核心业务逻辑与 SDK 实现细节解耦——毕竟，什么层做什么事，井水不犯河水
可测试性：通过 ICopilotSdkGateway 接口可以轻松进行单元测试，测试起来也不那么费劲
复用性：HagiCode.Libs 可被多个项目引用，写一次，多处用
可维护性：SDK 升级只需修改 Gateway 层，上面的代码不用动，美得很

核心实现

认证流程

认证是 SDK 集成的第一步，也是最重要的一步——毕竟，门都进不去，后面的事情就免谈了。我们设计了一个灵活的认证配置，支持多种认证来源：

// CopilotProvider.cs - 认证来源配置
public class CopilotOptions
{
    public bool UseLoggedInUser { get; set; } = true;
    public string? GitHubToken { get; set; }
    public string? CliUrl { get; set; }
}

// 转换为 SDK 请求
return new CopilotSdkRequest(
    GitHubToken: options.AuthSource == CopilotAuthSource.GitHubToken
        ? options.GitHubToken
        : null,
    UseLoggedInUser: options.AuthSource != CopilotAuthSource.GitHubToken
);

这个设计的好处，其实也挺明显的：

支持已登录用户模式（无需 token），适合桌面端场景——用户用自己的账号登录就行
支持 GitHub Token 模式，适用于服务端部署——统一管理也方便
支持 Copilot CLI URL 覆盖，方便企业代理配置——企业环境嘛，总有些特殊的规矩

在实际使用中，这种灵活的认证方式大大简化了不同部署场景的配置工作。桌面端可以使用用户自己的 Copilot 登录状态，服务端则可以通过 Token 进行统一管理。怎么说呢，各取所需罢了。

事件流处理

SDK 最强大的能力之一，应该就是对事件流的完整捕获了。我们实现了一个事件分发系统，能够实时处理各种 SDK 事件——毕竟，知道过程和只知道结果，感觉还是不一样的：

// GitHubCopilotSdkGateway.cs - 事件分发核心逻辑
internal static SessionEventDispatchResult DispatchSessionEvent(
    SessionEvent evt, bool sawDelta)
{
    switch (evt)
    {
        case AssistantReasoningEvent reasoningEvent:
            // 捕获模型推理过程
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ReasoningDelta,
                Content: reasoningEvent.Data.Content));
            break;

        case ToolExecutionStartEvent toolStartEvent:
            // 捕获工具调用开始
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ToolExecutionStart,
                ToolName: toolStartEvent.Data.ToolName,
                ToolCallId: toolStartEvent.Data.ToolCallId));
            break;

        case ToolExecutionCompleteEvent toolCompleteEvent:
            // 捕获工具调用完成及结果
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ToolExecutionEnd,
                Content: ExtractToolExecutionContent(toolCompleteEvent)));
            break;

        default:
            // 未处理事件作为 RawEvent 保留
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.RawEvent,
                RawEventType: evt.GetType().Name));
            break;
    }
}

这个实现带来的价值，怎么说呢：

完整捕获模型推理过程（thinking）：用户可以看到 AI 的思考过程，而不仅仅是最终结果——就像知道答案不如知道怎么思考出来的
实时追踪工具执行状态：知道哪些工具正在运行、何时完成、返回了什么结果
零事件丢失：通过 fallback 到 RawEvent 机制，确保所有事件都被记录，什么都不落下

在 HagiCode 的实际使用中，这些细粒度的事件让用户能够更深入地理解 AI 的工作过程，特别是在调试复杂任务时——这还是有点用处的。

CLI 兼容性处理

从 CLI 调用迁移到 SDK 后，我们发现一些原有的 CLI 参数在 SDK 中不再适用。为了保持向后兼容，我们实现了一个参数过滤系统——毕竟，旧配置不能用，也挺让人头疼的：

// CopilotCliCompatibility.cs - 参数过滤
private static readonly Dictionary<string, string> RejectedFlags = new()
{
    ["--headless"] = "不支持的启动参数",
    ["--model"] = "通过 SDK 原生字段传递",
    ["--prompt"] = "通过 SDK 原生字段传递",
    ["--interactive"] = "由 provider 管理交互",
};

public static CopilotCliArgumentBuildResult BuildCliArgs(CopilotOptions options)
{
    // 过滤不支持的参数，保留兼容参数
    // 生成诊断信息
}

这样做的好处：

自动过滤不兼容的 CLI 参数，避免运行时错误——程序崩溃可不是闹着玩的
生成清晰的错误诊断信息，帮助开发者快速定位问题
保证 SDK 稳定性，不受 CLI 参数变化的影响

在升级过程中，这个兼容性处理机制帮助我们平滑过渡，旧的配置文件仍然可以使用，只需要根据诊断信息逐步调整即可——也算是个渐进的过程了。

运行时池化

Copilot SDK 的会话创建成本较高，频繁创建和销毁会话会影响性能。我们实现了一个会话池管理系统——就像池子里的水，用完了再装，不如留着下次接着用：

// CopilotProvider.cs - 会话池管理
await using var lease = await _poolCoordinator.AcquireCopilotRuntimeAsync(
    request,
    async ct => await _gateway.CreateRuntimeAsync(sdkRequest, ct),
    cancellationToken);

if (lease.IsWarmLease)
{
    // 复用已有会话
    yield return CreateSessionReusedMessage();
}

await foreach (var eventData in lease.Entry.Resource.SendPromptAsync(...))
{
    yield return MapEvent(eventData);
}

会话池化的好处：

会话复用：相同 sessionId 的请求可以复用已有会话，减少启动开销
支持会话恢复：网络中断后可以恢复之前的会话状态——毕竟网络这东西，谁敢保证一直稳定呢
自动池化管理：自动清理过期会话，避免资源泄漏

在 HagiCode 的实际使用中，会话池化显著提升了响应速度，特别是在处理连续对话时效果明显——这种提升还是能感觉到的。

Orleans 集成

HagiCode 使用 Orleans 作为分布式框架，我们将 Copilot SDK 集成到了 Orleans Grain 中——分布式这东西，说起来复杂，用起来倒也挺顺手：

// GitHubCopilotGrain.cs - 分布式执行
public async IAsyncEnumerable<GitHubCopilotResponse> ExecuteCommandStreamAsync(
    string command,
    CancellationToken token = default)
{
    var provider = await aiProviderFactory.GetProviderAsync(AIProviderType.GitHubCopilot);

    await foreach (var chunk in provider.SendMessageAsync(request, null, token))
    {
        // 映射为统一的响应格式
        yield return BuildChunkResponse(chunk, startedAt);
    }
}

Orleans 集成带来的优势：

统一的 AI Provider 抽象：可以轻松切换不同的 AI 提供商——今天用这个，明天用那个，也挺灵活
多租户隔离：不同用户的 Copilot 会话相互隔离，井水不犯河水
持久化会话状态：会话状态可以跨服务器重启恢复，重启也不怕丢数据

对于需要处理大量并发请求的场景，Orleans 的分布式能力提供了很好的扩展性——毕竟，单机扛不住的时候，只能靠分布式顶上了。

实践指南

配置示例

以下是一个完整的配置示例——直接复制粘贴改改就能用：

{
  "AI": {
    "Providers": {
      "Providers": {
        "GitHubCopilot": {
          "Enabled": true,
          "ExecutablePath": "copilot",
          "Model": "gpt-5",
          "WorkingDirectory": "/path/to/project",
          "Timeout": 7200,
          "StartupTimeout": 30,
          "UseLoggedInUser": true,
          "NoAskUser": true,
          "Permissions": {
            "AllowAllTools": false,
            "AllowedTools": ["Read", "Bash", "Grep"],
            "DeniedTools": ["Edit"]
          }
        }
      }
    }
  }
}

使用注意事项

在实际使用中，我们总结了一些需要注意的地方——有些是踩坑得来的经验：

启动超时配置：首次启动 Copilot CLI 需要较长时间，建议设置 StartupTimeout 至少 30 秒。如果是首次登录，可能需要更长的时间——毕竟首次登录总得验证一下，这也没办法。

权限管理：生产环境避免使用 AllowAllTools: true。使用 AllowedTools 白名单控制可用工具，使用 DeniedTools 黑名单禁止危险操作。这样可以有效防止 AI 执行危险命令——安全这东西，小心点总是对的。

会话管理：相同 sessionId 的请求会自动复用会话。会话状态通过 ProviderSessionId 持久化。取消操作通过 CancellationTokenSource 传递——会话管理做得好，体验自然就好。

诊断输出：不兼容的 CLI 参数会生成 diagnostic 类型消息。原始 SDK 事件以 event.raw 类型保留。错误信息包含分类（启动超时、参数不兼容等），方便排查问题——出了问题能快速定位，也算是一种安慰了。

最佳实践

基于我们的实际经验，这里分享一些最佳实践——算是一些总结吧：

1. 使用工具白名单

var request = new AIRequest
{
    Prompt = "分析这个文件",
    AllowedTools = new[] { "Read", "Grep", "Bash(git:*)" }
};

通过白名单明确指定允许的工具，避免 AI 执行意外操作。特别是对于有写入权限的工具（如 Edit），需要格外谨慎——毕竟删库这种事，谁也不想经历。

2. 设置合理的超时

options.Timeout = 3600;  // 1小时
options.StartupTimeout = 60;  // 1分钟

根据任务的复杂度设置合适的超时时间。太短可能导致任务中断，太长则可能浪费资源等待无响应的请求——凡事适度，过犹不及。

3. 启用会话复用

options.SessionId = "my-session-123";

为相关任务设置相同的 sessionId，可以复用之前的会话上下文，提升响应速度——上下文这东西，有时候还挺重要的。

4. 处理流式响应

await foreach (var chunk in provider.StreamAsync(request))
{
    switch (chunk.Type)
    {
        case StreamingChunkType.ThinkingDelta:
            // 处理推理过程
            break;
        case StreamingChunkType.ToolCallDelta:
            // 处理工具调用
            break;
        case StreamingChunkType.ContentDelta:
            // 处理文本输出
            break;
    }
}

流式响应可以实时显示 AI 的处理进度，提升用户体验。特别是对于耗时任务，实时反馈非常重要——看着进度条总比干等着强。

5. 错误处理和重试

try
{
    await foreach (var chunk in provider.StreamAsync(request))
    {
        // 处理响应
    }
}
catch (CopilotSessionException ex)
{
    // 处理会话异常
    logger.LogError(ex, "Copilot session failed");
    // 根据异常类型决定是否重试
}

适当的错误处理和重试机制可以提升系统的稳定性——谁也不能保证程序永远不出错，出了错能处理好就行。

总结

从 CLI 调用到 SDK 集成的升级，为 HagiCode 项目带来了显著的价值——怎么说呢，这次升级还是挺值的：

稳定性提升：SDK 提供了更稳定的接口，不受 CLI 版本变化影响——不用天天担心版本更新了
功能完整性：能够捕获完整的事件流，包括推理过程和工具执行状态——过程和结果都能看到
开发效率：类型安全的 SDK 接口让开发更高效，减少运行时错误——有类型检查，心里踏实
用户体验：实时的事件反馈让用户更清晰地了解 AI 的工作过程——知道它在想什么，总比一无所知强

这次升级不仅仅是技术方案的替换，更是对整个 AI 能力层架构的优化。通过分层设计和抽象接口，我们获得了更好的可维护性和可扩展性——架构做好了，后面的事情就好办了。

如果你正在考虑将 GitHub Copilot 集成到你的 .NET 项目中，希望本文的实践经验能够帮助你少走一些弯路。官方 SDK 确实比 CLI 调用更加稳定和完整，值得投入时间去理解和掌握——毕竟，正确的工具能让事情事半功倍，这话也不是没有道理的。

参考资料

如果本文对你有帮助：

点个赞让更多人看到——你的支持，对我们很重要
来 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 的过程中有什么问题或建议，欢迎随时联系我们。好了，就这样吧…

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

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

AI 编程助手的幻觉问题：如何用 OpenSpec 实现规范驱动开发

2026年4月2日

AI 编程助手的幻觉问题：如何用 OpenSpec 实现规范驱动开发

AI 编程助手虽然强大，但常常生成不符合实际需求、违反项目规范的代码。本文分享 HagiCode 项目如何通过 OpenSpec 流程实现”规范驱动开发”，用结构化的提案机制显著减少 AI 幻觉风险。

背景

用过 GitHub Copilot 或 ChatGPT 写代码的同学可能都有过这样的经历：AI 生成的代码看起来很漂亮，但真正用起来却问题百出。可能是用错了项目里的某个组件，可能是忽略了团队的编码规范，也可能是基于一些不存在的假设写了大段逻辑。

这就是所谓的”AI 幻觉”问题——在编程领域，它表现为生成看似合理但实际上不符合项目实际情况的代码。

其实这事儿也挺无奈的。AI 编程助手越来越普及，这个问题也就越发严重了。毕竟，AI 缺乏对项目历史、架构决策和编码规范的理解，而自由度过高又容易让它”创造性”地生成不符合实际的代码。这和写文章倒是挺像的，没有章法就容易写得天马行空，可实际上并不是那么回事儿。

为了解决这些痛点，我们做了一个大胆的决定：不是试图让 AI 更聪明，而是给它套上一个”规范”的笼子。这个决定带来的变化，可能比你想象的还要大——稍后我会具体说。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，致力于通过结构化的工程实践来解决 AI 编程中的实际问题。

AI 幻觉的根源

在深入解决方案之前，咱们先看看问题到底出在哪。毕竟知己知彼，方能百战不殆，只是这话用在 AI 身上，好像也有点意思。

上下文缺失

AI 模型训练时用的是公开的代码库，但你的项目有它自己的历史、约定和架构决策。这些”隐性知识” AI 没法直接获取，所以生成的代码往往和项目实际情况脱节。

这也不能全怪 AI，毕竟它又没在你们项目待过，哪知道你们那些江湖规矩呢？就像新来的实习生，不懂规矩也正常，只是代价可能有点大罢了。

自由度过高

当你问 AI”帮我实现一个用户认证功能”时，它可能生成任何形式的代码。没有明确的约束，AI 就会按照它”认为”合理的方式去实现，而不是按照你项目的要求。

这就像是让一个从未学过你项目规范的人自由发挥，能不出问题吗？其实也不是它不负责任，只是它压根不知道什么是责任。

缺乏验证

AI 生成代码后，如果没有经过结构化的审查流程，那些基于错误假设的代码就会直接进入代码库。等到测试甚至生产环境才发现问题，代价就太大了。

这无异于亡羊补牢，只是羊都已经跑光了，补牢又有什么用呢？这道理谁都懂，可真正做起来，又总觉得麻烦。毕竟在事情变坏之前，谁愿意多花时间呢？

OpenSpec：规范驱动开发的答案

HagiCode 选择 OpenSpec 作为解决方案，核心思路是：所有代码变更必须通过结构化的提案流程，把抽象的想法转化为可执行的实施计划。

这话说得挺高大上的，其实就是让 AI 在写代码之前，先把需求文档写好罢了。毕竟凡事预则立，不预则废，古人诚不我欺。

什么是 OpenSpec

OpenSpec 是一个基于 npm 的命令行工具（@fission-ai/openspec），它定义了一套标准的提案文件结构和验证机制。简单说，就是让 AI 在写代码之前，先”写好需求文档”。

三步流程防幻觉

OpenSpec 通过一个三步流程来确保提案质量：

Step 1：初始化提案 - 设置会话状态为 Openspecing Step 2：中间处理 - 保持 Openspecing 状态，逐步完善工件 Step 3：完成提案 - 转换到 Reviewing 状态

这个设计有个很巧妙的细节：第一步使用的是 ProposalGenerationStart 类型，完成后不会触发状态转换。这确保了整个多步流程完成前，不会过早进入审查阶段。

其实这个细节也挺有意思的，就像做菜一样，火候没到就揭锅盖，肯定是什么都做不好的。只有耐心一点，一步一步来，最后才能做出一道好菜。

// HagiCode 项目中的实现
public enum MessageAssociationType
{
    ProposalGeneration = 2,
    ProposalExecution = 3,

    /// <summary>
    /// 标记三步提案生成流程的开始
    /// 完成后不会转换到 Reviewing 状态
    /// </summary>
    ProposalGenerationStart = 5
}

标准化的文件结构

每个 OpenSpec 提案都遵循相同的目录结构：

openspec/
├── changes/                    # 活跃和归档的变更
│   ├── {change-name}/
│   │   ├── proposal.md        # 提案描述
│   │   ├── design.md          # 设计文档
│   │   ├── specs/             # 技术规范
│   │   └── tasks.md           # 可执行任务清单
│   └── archive/               # 归档的变更
└── specs/                     # 独立的规范库

根据 HagiCode 项目的统计，目前已经有 4000+ 个归档变更和 15 万+ 行规范文件。这些历史积累不仅让 AI 有章可循，也为团队提供了宝贵的知识库。

这就像是古人留下的典籍，读多了自然就能悟出点门道来。只是现在这典籍不是写在竹简上，而是存放在文件里罢了。

多层验证机制

系统实现了多层验证来确保提案质量：

// 验证必需文件存在
ValidateProposalFiles()

// 验证执行前提条件
ValidateExecuteAsync()

// 验证启动条件
ValidateStartAsync()

// 验证归档条件
ValidateArchiveAsync()

// 提案名称格式验证（kebab-case）
ValidateNameFormat()

这些验证就像是层层把关的守门人，只有真正合格的提案才能通过。虽然看起来繁琐，可总比让糟糕的代码进入代码库要强吧？

Prompt 模板约束

HagiCode 中的 AI 执行时使用预定义的 Handlebars 模板，这些模板包含明确的步骤指导和保护措施。比如：

禁止在未理解用户意图时继续
禁止生成未验证的代码
要求在名称无效时重新提供
如果变更已存在，建议使用继续命令而不是重新创建

这种”带着脚镣跳舞”的方式，反而让 AI 更聚焦于理解需求和生成符合规范的代码。其实约束这东西，也不一定是坏事，毕竟自由过头了就容易乱套。

实践：如何在项目中使用 OpenSpec

安装和初始化

npm install -g @fission-ai/openspec@1
openspec --version  # 验证安装

在项目根目录会自动创建 openspec/ 文件夹结构。

这步其实也没什么好说的，安装工具嘛，大家都懂。只是记得用 @fission-ai/openspec@1 这个版本，新版本可能有坑，毕竟稳定压倒一切。

创建提案

在 HagiCode 的对话界面中，使用快捷命令：

/opsx:new

或者指定变更名称和目标仓库：

/opsx:new "add-user-auth" --repos "repos/web"

创建提案这事儿，就像写文章列提纲一样，有了提纲后面就好写了。只是很多人喜欢直接开始写，写到一半才发现思路不通，那才叫头疼。

生成工件

使用 /opsx:continue 逐步生成所需的工件：

proposal.md - 描述变更的目的和范围

# Proposal: Add User Authentication

## Why
当前系统缺少用户认证功能，无法保护敏感 API。

## What Changes
- 添加 JWT 认证中间件
- 实现登录/注册 API
- 更新前端集成

design.md - 详细的技术设计

# Design: Add User Authentication

## Context
当前使用公开 API，任何人均可访问...

## Decisions
1. 选择 JWT 而非 Session...
2. 使用 HS256 算法...

## Risks
- 令牌泄露风险...
- 缓解措施...

specs/ - 技术规范和测试场景

# user-auth Specification

## Requirements

### Requirement: JWT Token Generation
系统 SHALL 使用 HS256 算法生成 JWT 令牌。

#### Scenario: Valid login
- WHEN 用户提供有效凭据
- THEN 系统 SHALL 返回有效的 JWT 令牌

tasks.md - 可执行的任务清单

# Tasks: Add User Authentication

## 1. Backend Changes
- [ ] 1.1 创建 AuthController
- [ ] 1.2 实现 JWT 中间件
- [ ] 1.3 添加单元测试

这些工件其实就像是写文章的草稿，草稿写好了，正文自然就顺畅了。只是很多人不喜欢写草稿，觉得浪费时间，可实际上草稿才是最能理清思路的地方。

审查和应用

完成所有工件后：

/opsx:apply

AI 会读取所有上下文文件，按照 tasks.md 中的清单逐步执行任务。这时候因为有了清晰的规范，生成的代码质量会高很多。

其实到了这一步，事情就已经成了一半了。有了明确的任务清单，剩下的就是按部就班地执行罢了。只是很多人跳过了前面的步骤，直接到这里，那质量自然就难以保证了。

归档

变更完成后：

/opsx:archive

将完成的变更移动到 archive/ 目录，方便以后查阅和复用。

归档这事儿挺重要的，就像把写完的文章好好收起来一样。以后遇到类似的问题，翻一翻以前的记录，可能就有答案了。只是很多人懒得做，觉得麻烦，可实际上这些积累才是最宝贵的财富。

注意事项和最佳实践

提案命名规范

使用 kebab-case 格式，以字母开头，仅包含小写字母、数字和连字符：

✅ add-user-auth
❌ AddUserAuth
❌ add--user-auth

命名规范这东西，说起来也没啥大不了的，只是统一一点总归是好的。毕竟代码这事儿， consistency 很重要，只是很多人不在意罢了。

避免常见错误

在三步流程的步骤 1 使用错误的类型 - 会过早转换状态
忘记在最后一步触发状态转换 - 会卡在 Openspecing 状态
跳过审查直接执行 - 应该先验证所有工件完整

这些错误其实都是新手容易犯的，老手自然知道怎么避免。只是新手总有变老手的一天，走了弯路也就罢了，只希望不要走太多弯路就好。

多变更管理

OpenSpec 支持同时管理多个提案，这在处理大型功能时特别有用：

# 查看所有活动变更
openspec list

# 切换到特定变更
openspec apply "add-user-auth"

# 查看变更状态
openspec status --change "add-user-auth"

多变更管理这事儿，就像同时写几篇文章一样，需要一点技巧和耐心。只是习惯了就好了，毕竟人嘛，总能适应的。

会话状态机理解

了解状态转换有助于排查问题：

Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

Openspecing：生成规划中
Reviewing：审查中（可反复修改工件）
Executing：执行中（应用 tasks.md）

状态机这东西，说白了就是一套规则。规则这东西，有时候挺烦人的，但更多时候是有用的。毕竟没有规矩不成方圆，这话古人早就说过了。

总结

通过 OpenSpec 流程，HagiCode 项目在解决 AI 幻觉问题上取得了显著效果：

减少幻觉 - AI 必须遵循结构化规范，不能随意生成代码
提高质量 - 多层验证确保变更符合项目标准
加速协作 - 归档的变更为后续开发提供参考
可追溯性 - 每个变更都有完整的提案、设计、规范和任务记录

这套方案不是让 AI 变聪明，而是给它套上”规范”的笼子。实践证明，带着脚镣跳舞，反而跳得更好。

其实这道理也简单，约束不一定是什么坏事。就像写文章，有了格式的约束，反而更容易写出好东西来。只是很多人不喜欢约束，觉得限制了自己的创造力，可实际上创造力也需要土壤才能开花结果。

如果你也在使用 AI 编程助手，并且遇到过类似的问题，不妨试试 OpenSpec。规范驱动开发可能看起来多了一些步骤，但这些前期投入会在代码质量和维护效率上得到数倍的回报。

毕竟，慢一点，有时候反而是快一点。只是很多人不明白这个道理罢了…

参考资料

OpenSpec npm 包：www.npmjs.com/package/@fission-ai/openspec
HagiCode 项目地址：github.com/HagiCode-org/site
HagiCode 官网：hagicode.com
观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose 一键安装：docs.hagicode.com/installation/docker-compose
Desktop 桌面端快速安装：hagicode.com/desktop/

如果本文对你有帮助，欢迎来 GitHub 给个 Star。HagiCode 公测已开始，现在安装即可参与体验。

这文章写得也差不多了，其实也没什么特别高深的东西，只是把一些实践经验总结了一下罢了。希望对大家有用，毕竟分享这东西，自己学到了，也让别人学到了，两全其美，何乐而不为呢？

只是文章终究是文章，真正有用的还是实践。毕竟纸上得来终觉浅，绝知此事要躬行，古人诚不我欺…

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

在 React 项目中优雅实现新用户引导：HagiCode 的 driver.js 实践

2026年4月1日

在 React 项目中优雅实现新用户引导：HagiCode 的 driver.js 实践

当用户第一次打开你的产品时，他们真的知道该从哪里开始吗？这篇文章聊聊我们在 HagiCode 项目里用 driver.js 做新用户引导的那些事儿，也算是抛砖引玉罢了。

背景

你有没有遇到过这样的场景：新用户注册了你的产品，打开页面后一脸茫然，东张西望，不知道该点哪里、该做什么。作为开发者，我们总以为用户会”自己探索”，毕竟人的好奇心是无限的嘛。可现实是——大部分用户会在几分钟内因为找不到入口而悄悄离开，就像故事开始得突然，结束得也自然。

新用户引导是解决这个问题的重要手段，只是实现起来也不那么简单。一个好的引导系统需要：

能够精准定位页面元素并高亮显示
支持多步骤引导流程
能够记住用户的选择（完成/跳过）
不影响页面性能和正常交互
代码结构清晰，易于维护

在开发 HagiCode 的过程中，我们也遇到了同样的挑战。HagiCode 是一个 AI 代码助手项目，核心工作流是”用户创建提案 → AI 生成计划 → 用户审核 → AI 执行”这样一套 OpenSpec 流程。对于第一次接触这个概念的用户来说，这套流程是全新的，必须有一个好的引导来帮助他们快速上手。毕竟，新事物总是需要一点时间的。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个基于 Claude 的 AI 代码助手，通过 OpenSpec 工作流帮助开发者更高效地完成代码任务。你可以在 GitHub 上查看我们的开源代码。

为什么选择 driver.js

在技术选型阶段，我们评估了几个主流的引导库，怎么说呢，每个都有自己的特点：

Intro.js：功能强大但体积较大，样式定制相对复杂
Shepherd.js：API 设计很好，但对于我们的场景来说有点”重”
driver.js：轻量、简洁、API 直观，且支持 React 生态

最终我们选择了 driver.js，其实也没什么特别的理由，主要基于以下几点考虑：

轻量级：核心库体积小，不会显著增加打包体积
API 简洁：配置项清晰直观，上手快
灵活性：支持自定义定位、样式和交互行为
动态导入：可以按需加载，不影响首屏性能

选型这件事，其实没有最好的，只有最合适的罢了。

技术实现

核心配置

driver.js 的配置非常直观，以下是 HagiCode 项目中的核心配置：

import { driver } from 'driver.js';
import 'driver.js/dist/driver.css';

const newConversationDriver = driver({
  allowClose: true,           // 允许用户关闭引导
  animate: true,              // 启用动画效果
  overlayClickBehavior: 'close', // 点击遮罩层关闭引导
  disableActiveInteraction: false, // 保持元素可交互
  showProgress: false,        // 不显示进度条（我们有自定义进度管理）
  steps: guideSteps           // 引导步骤数组
});

这些配置背后的考虑是：

allowClose: true - 尊重用户选择，不强制完成引导，毕竟强扭的瓜不甜
disableActiveInteraction: false - 某些步骤需要用户实际操作（如输入文字），所以不能禁用交互
overlayClickBehavior: 'close' - 给用户一个快速的退出方式

状态管理

引导状态的持久化是关键——我们不希望每次刷新页面都重新引导，那样挺烦人的。HagiCode 使用 localStorage 来管理引导状态：

export type GuideState = 'pending' | 'dismissed' | 'completed';

export interface UserGuideState {
  session: GuideState;
  detailGuides: Record<string, GuideState>;
}

// 读取状态
export const getUserGuideState = (): UserGuideState => {
  const state = localStorage.getItem('userGuideState');
  return state ? JSON.parse(state) : { session: 'pending', detailGuides: {} };
};

// 更新状态
export const setUserGuideState = (state: UserGuideState) => {
  localStorage.setItem('userGuideState', JSON.stringify(state));
};

我们定义了三种状态：

pending：引导进行中，用户还未完成或跳过
dismissed：用户主动关闭了引导
completed：用户完成了所有步骤

对于提案详情页的引导，我们还支持更细粒度的状态追踪（通过 detailGuides 字典），因为一个提案可能会经历多个阶段（草稿、审核、执行完成），每个阶段都需要不同的引导。毕竟，事情的状态总是在变化的。

目标元素定位

driver.js 使用 CSS 选择器来定位目标元素。HagiCode 采用了一个约定：使用 data-guide 自定义属性来标记引导目标：

const steps = [
  {
    element: '[data-guide="launch"]',
    popover: {
      title: '开始新对话',
      description: '点击这里创建一个新的对话会话...'
    }
  }
];

在组件中这样使用：

<button data-guide="launch" onClick={handleLaunch}>
  新建对话
</button>

这种做法的好处是：

避免与业务样式类名冲突
语义清晰，一眼就能看出这个元素与引导相关
便于统一管理和维护

动态导入优化

因为引导功能只在特定场景下才需要（比如新用户第一次访问），我们采用动态导入来优化初始加载性能：

const initNewUserGuide = async () => {
  // 动态导入 driver.js
  const { driver } = await import('driver.js');
  await import('driver.js/dist/driver.css');

  // 初始化引导
  const newConversationDriver = driver({
    // ...配置
  });

  newConversationDriver.drive();
};

这样 driver.js 及其样式文件只会在需要时才加载，不会影响首屏性能。毕竟，谁愿意为暂时用不到的东西付出等待的代价呢？

引导流程设计

HagiCode 实现了两条引导路径，覆盖了用户的核心使用场景。

会话引导（10步）

这条引导帮助用户完成从创建对话到提交第一个完整提案的整个流程：

launch - 启动引导，介绍”新建对话”按钮
compose - 引导用户在输入框中输入请求
send - 引导点击发送按钮
proposal-launch-readme - 引导创建 README 提案
proposal-compose-readme - 引导编辑 README 请求内容
proposal-submit-readme - 引导提交 README 提案
proposal-launch-agents - 引导创建 AGENTS.md 提案
proposal-compose-agents - 引导编辑 AGENTS.md 请求
proposal-submit-agents - 引导提交 AGENTS.md 提案
proposal-wait - 说明 AI 正在处理，请稍候

这条引导的设计思路是：通过两个实际的提案创建任务（README 和 AGENTS.md），让用户亲手体验 HagiCode 的核心工作流。毕竟，纸上得来终觉浅，绝知此事要躬行。

下面这几张图，对应的就是会话引导里的几个关键节点：

会话引导：从创建普通会话开始

会话引导的第一步，先把用户带到“新建普通会话”的入口上。

会话引导：输入第一句请求

接着引导用户在输入框里写下第一句请求，降低第一次开口的门槛。

会话引导：发送第一条消息

输入完成后，再明确提示用户发送第一条消息，让操作路径更连贯。

会话引导：等待会话列表继续执行

当两个提案都创建完成后，引导会回到会话列表，让用户知道接下来只需要等待系统继续执行和刷新。

提案详情引导（3步）

当用户进入提案详情页时，根据提案的当前状态触发对应的引导：

drafting（草稿阶段）- 引导用户查看 AI 生成的计划
reviewing（审核阶段）- 引导用户执行计划
executionCompleted（完成阶段）- 引导用户归档计划

这条引导的特点是状态驱动——根据提案的实际状态动态决定显示哪个引导步骤。事物总是在变化，引导也应该跟着变化才是。

下面这张图展示的是提案详情页在“起草阶段”的引导状态：

提案详情引导：起草阶段先生成规划

在这个阶段，引导会把用户注意力聚焦到“生成规划”这个关键动作上，避免第一次进入详情页时不知道该先做什么。

元素渲染重试机制

在 React 应用中，引导目标元素可能还没渲染完成（比如等待异步数据加载）。为了处理这种情况，HagiCode 实现了一个重试机制：

const waitForElement = (selector: string, maxRetries = 10, interval = 100) => {
  let retries = 0;
  return new Promise<HTMLElement>((resolve, reject) => {
    const checkElement = () => {
      const element = document.querySelector(selector) as HTMLElement;
      if (element) {
        resolve(element);
      } else if (retries < maxRetries) {
        retries++;
        setTimeout(checkElement, interval);
      } else {
        reject(new Error(`Element not found: ${selector}`));
      }
    };
    checkElement();
  });
};

在初始化引导前调用这个函数，确保目标元素已经存在。有时候，多等待一下也是值得的。

最佳实践总结

基于 HagiCode 的实践经验，这里分享几个关键的最佳实践：

1. 引导应该是”可逃离的”

不要强制用户完成引导。有些用户是探索型的，他们更喜欢自己摸索。提供清晰的”跳过”按钮，并记住用户的选择，下次不再打扰。毕竟，美的事物或人，不一定要占有，只要她还是美的，自己好好看着她的美就好了。

2. 引导内容要简洁有力

每个引导步骤应该聚焦于单一目标：

Title：简短清晰，不超过 10 个字
Description：直击要点，告诉用户”这是啥”和”为啥要用”

避免长篇大论的说明——用户在引导阶段的注意力是很有限的。话说多了，反而没人愿意看。

3. 选择器要稳定

使用稳定的、不频繁变化的元素标记方式。data-guide 自定义属性是一个好选择，避免依赖 class 名或 DOM 结构，因为这些很容易在重构中变化。代码总是在变化的，但有些东西应该尽量保持稳定。

4. 测试你的引导

HagiCode 为引导功能编写了完整的测试用例：

describe('NewUserConversationGuide', () => {
  it('应该正确初始化引导状态', () => {
    const state = getUserGuideState();
    expect(state.session).toBe('pending');
  });

  it('应该正确更新引导状态', () => {
    setUserGuideState({ session: 'completed', detailGuides: {} });
    const state = getUserGuideState();
    expect(state.session).toBe('completed');
  });
});

测试可以确保在重构代码时不会不小心破坏引导功能。毕竟，谁也不希望改点代码就把之前的功能搞坏了。

5. 性能优化

使用动态导入延迟加载引导库
避免在用户已经完成引导后仍然初始化引导逻辑
考虑引导动画的性能影响，低端设备上可以关闭动画

性能这东西，就像生活一样，该省的地方还是要省的。

总结

新用户引导是提升产品用户体验的重要环节。在 HagiCode 项目中，我们使用 driver.js 构建了一套完整的引导系统，覆盖了从会话创建到提案执行的整个工作流。

通过本文的分享，我们希望传达的核心观点是：

技术选型要匹配需求：driver.js 不是最强的，但对我们来说是最合适的
状态管理很关键：用 localStorage 持久化引导状态，避免重复打扰用户
引导设计要聚焦：每个步骤解决一个问题，不要贪多
代码结构要清晰：分离引导配置、状态管理和 UI 逻辑，便于维护

如果你正在为自己的项目添加新用户引导功能，希望本文的实践经验能对你有所帮助。其实技术这东西，也没什么神秘的，多尝试，多总结，慢慢就好了…

参考资料

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。

本文作者: newbe36524
原文链接: https://docs.hagicode.com/blog/2026-04-01-new-user-guide-with-driverjs/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

2026年3月31日

打字不如说话，说话不如截图——AI 代码助手的多模态输入实践

其实写代码这事儿，打字再快也有个上限。有时候说一句话的事，非得敲半天键盘；有时候一张图就能说明白，却得用一堆文字去描述。本文聊聊我们在做 HagiCode 时遇到的那些事儿——语音识别也好，图片上传也罢，反正就是想让 AI 代码助手变得好用一点，罢了。

背景

在做 HagiCode 的时候，我们发现了一个问题——或者说，用户们用得多了，自然就显现出来的问题：光靠打字，有时候挺累的。

你想啊，用户和 Agent 交互，这可是核心场景。可是每次都得坐在键盘上噼里啪啦地敲，怎么说呢，效率确实不太高：

打字太慢了：有些复杂的问题，什么报错啊、界面上的事儿啊，打字说出来得耗上半分钟，嘴上可能十秒就说完了。这时间差，挺让人难受的。
图片更直接：有时候界面报错了，或者想对比一下设计稿，又或者想展示代码结构……”一图胜千言”这话虽老，可理儿不假。让 AI 直接”看”到问题，比描述半天要清楚得多。
交互就该自然点：现在的 AI 助手，应该支持文字、语音、图片这些方式吧？用户想用什么就用什么，这才叫自然，不是吗？

所以啊，我们就想，不如给 HagiCode 加上语音识别和图片上传的功能，让 Agent 操作变得方便些。毕竟，能让用户少敲几个字，也是好的。

关于 HagiCode

本文分享的这些方案，来自我们在 HagiCode 项目中的实践——或者说，是在不断踩坑中摸索出来的经验。

HagiCode 是个开源的 AI 代码助手项目，想法很简单：用 AI 技术提升开发效率。做着做着就发现，用户对多模态输入的需求其实挺强烈的——有时候说一句话比打一堆字快，有时候一张截图比描述半天清楚。

这些需求推着我们往前走，最后也就有了语音识别和图片上传这些功能。用户可以用最自然的方式和 AI 交互，这感觉，挺好的。

分析

语音识别的技术挑战

做语音识别功能的时候，我们遇到了一个挺棘手的问题：浏览器的 WebSocket API 不支持自定义 HTTP header。

而我们选的语音识别服务，是字节跳动的豆包语音识别 API。这个 API 偏偏要求通过 HTTP header 传递认证信息，什么 accessToken、secretKey 之类的。这下好了，技术矛盾来了：

// 浏览器 WebSocket API 不支持以下方式
const ws = new WebSocket('wss://api.com/ws', {
  headers: {
    'Authorization': 'Bearer token'  // 不支持
  }
});

摆在我们面前的方案，大概有两个：

URL 查询参数方案：把认证信息放在 URL 里
- 优点是，实现起来简单
- 缺点是，凭证暴露在前端，安全性差；而且有些 API 强制要求 header 验证
后端代理方案：在后端实现 WebSocket 代理
- 优点是，凭证安全存储在后端；完全兼容 API 要求
- 缺点是，实现起来稍微复杂一点

最后我们还是选了后端代理方案。毕竟啊，安全性这东西，是不能妥协的底线——这一点，谁也别想糊弄过去。

图片上传的功能需求

图片上传功能嘛，我们的需求其实也挺简单的：

多种上传方式：点击选文件、拖拽上传、剪贴板粘贴，总得有吧？
文件验证：类型限制（PNG、JPG、WebP、GIF）、大小限制（5-10MB），这些是基本操作
用户体验：上传进度、预览、错误提示，总得让人知道发生了什么
安全性：服务端验证、防止恶意文件上传，这可是大事

解决方案

语音识别：WebSocket 代理架构

我们设计了一个三层架构的语音识别方案，怎么说呢，算是找到了一条路：

Browser WebSocket
       |
       | ws://backend/api/voice/ws
       | (binary audio)
       v
Backend Proxy
       |
       | wss://openspeech.bytedance.com/ (with auth header)
       v
Doubao API

核心组件实现：

前端 AudioWorklet 处理器：

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

    // 重采样到 16kHz（豆包 API 要求）
    const samples = this.resampleAudio(input, 48000, 16000);

    // 累积样本到 500ms 块
    this.accumulatedSamples.push(...samples);

    if (this.accumulatedSamples.length >= 8000) {
      // 转换为 16-bit PCM 并发送
      const pcm = this.floatToPcm16(this.accumulatedSamples);
      this.port.postMessage({ type: 'audioData', data: pcm.buffer }, [pcm.buffer]);
      this.accumulatedSamples = [];
    }
    return true;
  }
}

后端 WebSocket 处理器（C#）：

[HttpGet("ws")]
public async Task GetWebSocket()
{
    if (HttpContext.WebSockets.IsWebSocketRequest)
    {
        await _webSocketHandler.HandleAsync(HttpContext);
    }
}

前端 VoiceTextArea 组件：

export const VoiceTextArea = forwardRef<HTMLTextAreaElement, VoiceTextAreaProps>(
  ({ value, onChange, onTextRecognized, maxDuration }, ref) => {
    const { isRecording, interimText, volume, duration, startRecording, stopRecording } =
      useVoiceRecording({ onTextRecognized, maxDuration });

    return (
      <div className="flex gap-2">
        {/* 语音按钮 */}
        <button onClick={handleButtonClick}>
          {isRecording ? <VolumeWaveform volume={volume} /> : <Mic />}
        </button>
        {/* 文本输入框 */}
        <textarea value={displayValue} onChange={handleChange} />
      </div>
    );
  }
);

图片上传：多方式上传组件

我们做了一个功能完整的图片上传组件，三种上传方式都支持，怎么说呢，算是把用户常用的场景都覆盖到了。

核心特性：

三种上传方式：

// 点击上传
const handleClick = () => fileInputRef.current?.click();

// 拖拽上传
const handleDrop = (e: React.DragEvent) => {
  const file = e.dataTransfer.files?.[0];
  if (file) uploadFile(file);
};

// 剪贴板粘贴
const handlePaste = (e: ClipboardEvent) => {
  for (const item of Array.from(e.clipboardData?.items || [])) {
    if (item.type.startsWith('image/')) {
      const file = item.getAsFile();
      if (file) uploadFile(file);
    }
  }
};

前端验证：

const validateFile = (file: File): { valid: boolean; error?: string } => {
  if (!acceptedTypes.includes(file.type)) {
    return { valid: false, error: 'Only PNG, JPG, JPEG, WebP, and GIF images are allowed' };
  }
  if (file.size > maxSize) {
    return { valid: false, error: `Maximum file size is ${(maxSize / 1024 / 1024).toFixed(1)}MB` };
  }
  return { valid: true };
};

后端上传处理（TypeScript）：

export const Route = createFileRoute('/api/upload')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const formData = await request.formData();
        const file = formData.get('file') as File;

        // 验证
        const validation = validateFile(file);
        if (!validation.isValid) {
          return Response.json({ error: validation.error }, { status: 400 });
        }

        // 保存文件
        const uuid = uuidv4();
        const filePath = join(uploadDir, `${uuid}${extension}`);
        await writeFile(filePath, buffer);

        return Response.json({ url: `/uploaded/${today}/${uuid}${extension}` });
      }
    }
  }
});

实践指南

如何使用语音识别

配置语音识别服务：
- 进入语音识别设置页面
- 配置豆包语音的 AppId 和 AccessToken
- （可选）配置热词以提升专业术语识别准确率
在输入框中使用：
- 点击输入框左侧的麦克风图标
- 看到波形动画后开始说话
- 再次点击图标停止录音
- 识别结果会自动插入到光标位置
热词配置示例：

TypeScript
React
useState
useEffect

如何使用图片上传

上传方式：
- 点击上传按钮选择文件
- 直接拖拽图片到上传区域
- 使用 Ctrl+V 粘贴剪贴板中的截图
支持的格式：PNG、JPG、JPEG、WebP、GIF
大小限制：默认 5MB（可配置）

注意事项

语音识别：
- 需要麦克风权限
- 建议在安静环境下使用
- 支持的最大录音时长为 300 秒（可配置）
图片上传：
- 仅支持常见图片格式
- 注意文件大小限制
- 上传后的图片会自动生成预览 URL
安全考虑：
- 语音识别凭证存储在后端
- 图片上传有严格的服务端验证
- 生产环境建议使用 HTTPS/WSS

总结

加上语音识别和图片上传之后，HagiCode 的用户体验确实提升了不少。用户现在可以用更自然的方式和 AI 交互——说话代替打字，截图代替描述。这种感觉，怎么说呢，就像是终于找到了一种更舒服的沟通方式。

做这个功能的时候，我们遇到了浏览器 WebSocket 不支持自定义 header 的问题，最后还是通过后端代理方案搞定了。这个方案不仅保证了安全性，也为后续集成其他需要认证的 WebSocket 服务打下了基础——也算是个意外收获吧。

图片上传组件也是，用了多种上传方式，让用户可以根据场景选择最方便的那一个。点击也好，拖拽也罢，或者直接粘贴，都能快速完成上传。条条大路通罗马，只是有的路好走一点，有的路稍微曲折一点罢了。

“打字不如说话，说话不如截图”，这话放在这里，倒也贴切。如果你也在做类似的 AI 助手产品，希望这些经验能对你有所帮助，哪怕只是一点点。

参考资料

如果本文对你有帮助：

点个赞让更多人看到
来 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-31-voice-and-image-upload-multimodal-input/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!