Forem: Hagicode

AI Output Token Optimization: Practice of Classical Chinese Ultra-Minimal Mode

Hagicode — Sat, 04 Apr 2026 02:27:21 +0000

AI Output Token Optimization: Practice of Classical Chinese Ultra-Minimal Mode

In AI application development, token consumption directly impacts costs. The HagiCode project implements a "Classical Chinese Ultra-Minimal Output Mode" through the SOUL system, reducing output tokens by approximately 30-50% without compromising information density. This article shares the implementation details and usage experience of this solution.

Background

In AI application development, token consumption is an unavoidable cost issue. Especially in scenarios requiring AI to output large amounts of content, figuring out how to reduce output tokens without sacrificing information density can become quite a headache if dwelled upon too much.

Traditional optimization approaches focus on the input side: streamlining system prompts, compressing context, and using more efficient encoding methods. However, these methods eventually hit a ceiling—further compression may affect AI's understanding capability and output quality. This is tantamount to cutting content, which holds little significance.

What about the output side? Can we make AI express the same meaning more concisely?

This question seems simple but actually contains considerable nuance. Simply telling AI to "be concise" might result in just a few words; adding "maintain complete information" may cause it to revert to its original verbose style. Too strong constraints affect usability, too weak constraints have no effect—and no one can say exactly where that balance point lies.

To address these pain points, we made a bold decision: start from language style and design a configurable, composable expression constraint system. The changes brought by this decision might be greater than you imagine—I'll elaborate shortly, perhaps you'll be pleasantly surprised.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is an open-source AI coding assistant project supporting multiple AI models and custom configurations. During development, we discovered the issue of excessive AI output tokens and designed a solution. If you find this solution valuable, it demonstrates our engineering capability is quite solid—then HagiCode itself is worth attention, after all, code doesn't lie.

SOUL System Overview

The SOUL system's full name is Soul Oriented Universal Language, a configuration system in the HagiCode project for defining AI Hero language styles. Its core idea is: by constraining AI's expression method, use more concise language forms to output content while maintaining information integrity.

This thing is like putting a language mask on AI... well, actually it's not that mysterious.

Technical Architecture

The SOUL system adopts a frontend-backend separated architecture:

Frontend (Soul Builder):

Built with React + TypeScript + Vite
Located in repos/soul/ directory
Provides visual Soul building interface
Supports bilingual (zh-CN / en-US)

Backend:

Based on .NET (C#) + Orleans distributed runtime
Hero entity includes Soul field (maximum 8000 characters)
Injects Soul into system prompts through SessionSystemMessageCompiler

Agent Templates Generation:

Generated from reference materials
Output to /agent-templates/soul/templates/ directory
Contains 50 main Catalog groups and 10 orthogonal dimension groups

Soul Injection Mechanism

When Session executes for the first time, the system reads the Hero's Soul configuration and injects it into the system prompt:

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: 流式响应

The injected system prompt format is:

<hero_soul>
[User's custom Soul content]
</hero_soul>

This injection mechanism is implemented in 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);
}

Code reviewed, principles understood—essentially, that's all there is to it.

Classical Chinese Ultra-Minimal Mode

Classical Chinese Ultra-Minimal Mode is the most representative token-saving solution in the SOUL system. Its core principle is leveraging Classical Chinese's high semantic density to compress output length while maintaining information integrity.

Why Classical Chinese

Classical Chinese has several natural advantages:

Semantic Compression: The same meaning can be expressed with fewer characters
Removing Redundancy: Classical Chinese inherently omits many conjunctions and particles found in modern Chinese
Concise Structure: High information density per sentence, suitable as an AI output carrier

A practical example to illustrate:

Modern Chinese output (approximately 80 characters):

根据你的代码分析，我发现了几个问题。首先，在第 23 行，变量名太长了，建议缩短一些。其次，在第 45 行，你没有处理空值的情况，应该加上判断逻辑。最后，整体的代码结构还可以，但是可以进一步优化。

Classical Chinese ultra-minimal output (approximately 35 characters, 56% savings):

代码审阅毕：第 23 行变量名冗长，宜缩写；第 45 行缺空值处理，应加判断。整体结构尚可，微调即可。

This difference is quite interesting when you think about it.

Soul Configuration Template

The complete Soul configuration for Classical Chinese Ultra-Minimal Mode is as follows:

{
  "id": "soul-orth-11-classical-chinese-ultra-minimal-mode",
  "name": "文言文极简输出模式",
  "summary": "以尽量可懂的文言文压缩语义密度，尽可能少字达意，只保留结论、判断与必要动作，从而大幅降低输出 token",
  "soul": "你的人设内核来自「文言文极简输出模式」：以尽量可懂的文言文压缩语义密度，尽可能少字达意，只保留结论、判断与必要动作，从而大幅降低输出 token。\n保持以下标志性语言特征：1. 优先使用简明文言句式，如「可」「宜」「勿」「已」「然」「故」等，避免生僻艰涩字词；\n2. 单句尽量压缩至 4-12 字，删除铺垫、寒暄、重复解释与无效修饰；\n3. 非必要不展开论证，用户未追问则只给结论、步骤或判断；\n4. 不改变主 Catalog 的核心人设，只将表达收束为克制、古雅、极简的短句。"
}

This template's design has several key points:

Clear Constraints: 4-12 characters per sentence, remove redundancy, conclusions first
Avoid Obscurity: Use simple Classical Chinese sentence patterns, avoid rare words
Maintain Persona: Only change expression method, not core persona

Configuration tuning is just a matter of adjusting a few parameters, really.

Other Minimal Modes

Beyond Classical Chinese mode, HagiCode's SOUL system provides various other token-saving modes:

Telegraphic Ultra-Minimal Output Mode (soul-orth-02):

Single sentences strictly controlled within 10 characters
Prohibits decorative adjectives
No modal particles, exclamation marks, or reduplicated words throughout

Short Sentence Murmur Mode (soul-orth-01):

Sentences controlled at 1-5 characters
Simulates fragmented self-talk expression
Weakened logic, prioritize emotional transmission

Guided Q&A Mode (soul-orth-03):

Guide user thinking through questions
Reduce direct output content
Interactive token consumption reduction

Each mode has different design priorities, but the core goal is consistent: reduce output tokens while maintaining information quality. All roads lead to Rome—some paths are just easier to walk than others.

Combination Strategy

A powerful feature of the SOUL system is support for cross-combination of main Catalogs and orthogonal dimensions:

50 Main Catalog Groups: Define base personas (such as healing style, academic style, cool style, etc.)
10 Orthogonal Dimensions: Define expression methods (such as Classical Chinese, telegraphic, Q&A style, etc.)
Combination Effect: Can generate 500+ unique language style combinations

For example, you can combine "Professional Development Engineer" with "Classical Chinese Ultra-Minimal Output Mode" to get an AI assistant that is both professional and concise. This flexibility allows the SOUL system to adapt to various usage scenarios. Combine however you want—there are more combinations than you can possibly explore...

Practice Guide

Creating via Soul Builder

Visit soul.hagicode.com and follow these steps:

Select main Catalog (such as "Professional Development Engineer")
Select orthogonal dimension (such as "Classical Chinese Ultra-Minimal Output Mode")
Preview generated Soul content
Copy generated Soul configuration

Point-and-click operations, shouldn't need much explanation.

Using in Hero Configuration

Apply Soul configuration to Hero through Web interface or API:

// Hero Soul update example
const heroUpdate = {
  soul: "你的人设内核来自「文言文极简输出模式」：...",
  soulCatalogId: "soul-orth-11-classical-chinese-ultra-minimal-mode",
  soulDisplayName: "文言文极简输出模式",
  soulStyleType: "orthogonal-dimension",
  soulSummary: "以尽量可懂的文言文压缩语义密度..."
};

await updateHero(heroId, heroUpdate);

Custom Soul Templates

Users can fine-tune based on preset templates or completely customize. Here's a custom example for code review scenarios:

你是一位追求极致简洁的代码审查员。
所有输出必须遵循：
1. 仅指出具体问题和行号
2. 每条问题不超过 15 字
3. 使用「宜」「应」「勿」等简洁词汇
4. 不做多余解释

示例输出：
- 第 23 行：变量名过长，宜缩写
- 第 45 行：未处理空值，应加判断
- 第 67 行：逻辑冗余，可简化

Modify however you want—templates are just a starting point anyway.

Notes

Compatibility:

Classical Chinese mode adapts to all 50 main Catalog groups
Can be combined with any base persona
Does not alter main Catalog's core persona

Caching Mechanism:

Soul is cached when Session first executes
Cache is reused within the same SessionId
Modifying Hero configuration does not affect already started Sessions

Limitation Constraints:

Soul field maximum length is 8000 characters
Heroes without Soul field in historical data can still be used normally
Soul is independent from style equipment slot, will not overwrite each other

Effect Comparison

Based on actual test data from the project, the effects after using Classical Chinese Ultra-Minimal Mode are as follows:

Scenario	Original Output Token	Classical Chinese Mode	Savings Ratio
Code Review	850	420	51%
Technical Q&A	620	380	39%
Solution Suggestions	1100	680	38%
Average	-	-	30-50%

Data comes from actual usage statistics of the HagiCode project, specific effects vary by scenario. However, the saved tokens accumulate over time—your wallet will thank you.

Summary

HagiCode's SOUL system provides an innovative AI output optimization approach: reducing token consumption by constraining expression methods rather than compressing information itself. As the most representative solution, Classical Chinese Ultra-Minimal Mode has achieved 30-50% token savings in actual use.

The core value of this solution lies in:

Maintaining Information Quality: Not simply truncating output, but expressing more efficiently
Flexible and Composable: Supports 500+ combinations of personas and expression methods
Easy to Use: Through Soul Builder visual interface, no coding required
Production-Grade Stability: Verified in project, supports large-scale usage

If you're also developing AI applications or interested in the HagiCode project, welcome to exchange ideas. The meaning of open source is progress together, and I look forward to seeing your innovative usage. After all, one person walks fast, a group walks far... a bit cliché, but that's how it is.

References

HagiCode GitHub: github.com/HagiCode-org/site
HagiCode Official Site: hagicode.com
Soul Builder: soul.hagicode.com
Docker Deployment Guide: docs.hagicode.com/installation/docker-compose
Desktop Client: hagicode.com/desktop/
30-Minute Practical Demo: www.bilibili.com/video/BV1pirZBuEzq/

If this article helps you:

Give a Star on GitHub: github.com/HagiCode-org/site
Visit the official site to learn more: hagicode.com
Beta testing has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-04-soul-token-optimization-classical-chinese%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

From CLI Invocation to SDK Integration: Best Practices for GitHub Copilot in .NET Projects

Hagicode — Fri, 03 Apr 2026 02:05:09 +0000

From CLI Invocation to SDK Integration: Best Practices for GitHub Copilot in .NET Projects

The upgrade path from command-line invocation to official SDK integration has been quite a journey. Today, I'll share the pitfalls we encountered and lessons learned in the HagiCode project.

Background

After the official release of the GitHub Copilot SDK in 2025, we began integrating it into our AI capability layer. Prior to this, the project primarily used GitHub Copilot capabilities by directly calling the Copilot CLI command-line tool. However, this approach presented several obvious issues:

Complex process management: Need to manually manage CLI process lifecycle, startup timeouts, and process cleanup—after all, processes can crash without any warning
Incomplete event handling: Raw CLI invocation makes it difficult to capture fine-grained events during model inference and tool execution—like only seeing the result without witnessing the thinking process
Difficult session management: Lack of effective session reuse and recovery mechanisms, meaning starting from scratch every time, which gets quite exhausting
Compatibility issues: CLI parameters update frequently, requiring continuous maintenance of parameter compatibility logic—fighting against windmills, essentially

These issues gradually became apparent in daily development, especially when needing real-time tracking of model inference process (thinking) and tool execution status. The limitations of CLI invocation became particularly obvious. We eventually realized we needed a lower-level, more complete integration approach—after all, all roads lead to Rome, it's just that some roads are easier to travel than others.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an open-source AI code assistant project. During development, we needed deep integration of various GitHub Copilot capabilities—from basic code completion to complex multi-turn conversations and tool calls. These actual requirements drove our upgrade from CLI invocation to official SDK integration.

If you're interested in the practical solutions in this article, it means our engineering practices might be helpful to you—then the HagiCode project itself is worth checking out. Perhaps at the end of the article, you'll discover more information and links about the project, who knows...

Architecture Design

The project adopts a layered architecture to address CLI invocation issues:

┌─────────────────────────────────────────────────────────┐
│  hagicode-core (Orleans Grains + AI Provider Layer)    │
│  - CopilotAIProvider: Convert AIRequest to CopilotOptions │
│  - GitHubCopilotGrain: Orleans distributed execution interface            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  HagiCode.Libs (Shared Provider Layer)                 │
│  - CopilotProvider: CLI Provider interface implementation               │
│  - ICopilotSdkGateway: SDK invocation abstraction                     │
│  - GitHubCopilotSdkGateway: SDK session management & event distribution     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  GitHub Copilot SDK (Official .NET SDK)                │
│  - CopilotClient: SDK client                            │
│  - CopilotSession: Session management                             │
│  - SessionEvent: Event stream                                 │
└─────────────────────────────────────────────────────────┘

The technical advantages of this layered design are actually quite practical:

Separation of concerns: Core business logic decoupled from SDK implementation details—after all, each layer has its responsibilities, not stepping on each other's toes
Testability: Through the ICopilotSdkGateway interface, unit testing becomes straightforward, making testing less painful
Reusability: HagiCode.Libs can be referenced by multiple projects, write once, use everywhere
Maintainability: SDK upgrades only require modifying the Gateway layer, upper code remains untouched, quite nice

Core Implementation

Authentication Flow

Authentication is the first and most important step in SDK integration—after all, if you can't get through the door, nothing else matters. We designed a flexible authentication configuration that supports multiple authentication sources:

// CopilotProvider.cs - Authentication source configuration
public class CopilotOptions
{
    public bool UseLoggedInUser { get; set; } = true;
    public string? GitHubToken { get; set; }
    public string? CliUrl { get; set; }
}

// Convert to SDK request
return new CopilotSdkRequest(
    GitHubToken: options.AuthSource == CopilotAuthSource.GitHubToken
        ? options.GitHubToken
        : null,
    UseLoggedInUser: options.AuthSource != CopilotAuthSource.GitHubToken
);

The benefits of this design are quite obvious:

Supports logged-in user mode (no token required), suitable for desktop scenarios—users log in with their own accounts
Supports GitHub Token mode, applicable for server-side deployment—unified management is convenient
Supports Copilot CLI URL override, convenient for enterprise proxy configuration—enterprise environments always have special rules

In actual use, this flexible authentication approach greatly simplifies configuration work for different deployment scenarios. Desktop clients can use the user's own Copilot login state, while servers can manage unified access through tokens. Different approaches for different needs, really.

Event Stream Processing

One of the SDK's most powerful capabilities is complete event stream capture. We implemented an event dispatch system capable of real-time processing of various SDK events—after all, knowing the process versus just knowing the result feels quite different:

// GitHubCopilotSdkGateway.cs - Event dispatch core logic
internal static SessionEventDispatchResult DispatchSessionEvent(
    SessionEvent evt, bool sawDelta)
{
    switch (evt)
    {
        case AssistantReasoningEvent reasoningEvent:
            // Capture model reasoning process
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ReasoningDelta,
                Content: reasoningEvent.Data.Content));
            break;

        case ToolExecutionStartEvent toolStartEvent:
            // Capture tool call start
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ToolExecutionStart,
                ToolName: toolStartEvent.Data.ToolName,
                ToolCallId: toolStartEvent.Data.ToolCallId));
            break;

        case ToolExecutionCompleteEvent toolCompleteEvent:
            // Capture tool call completion and result
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.ToolExecutionEnd,
                Content: ExtractToolExecutionContent(toolCompleteEvent)));
            break;

        default:
            // Unhandled events preserved as RawEvent
            events.Add(new CopilotSdkStreamEvent(
                CopilotSdkStreamEventType.RawEvent,
                RawEventType: evt.GetType().Name));
            break;
    }
}

The value this implementation brings, how should I put it:

Complete capture of model reasoning process (thinking): Users can see the AI's thinking process, not just the final result—like knowing how to think is better than just knowing the answer
Real-time tracking of tool execution status: Know which tools are running, when they complete, and what results they return
Zero event loss: Through fallback to RawEvent mechanism, ensures all events are recorded, nothing gets left behind

In HagiCode's actual use, these fine-grained events allow users to gain deeper understanding of the AI's work process, especially when debugging complex tasks—this is actually quite useful.

CLI Compatibility Handling

After migrating from CLI invocation to SDK, we found that some original CLI parameters were no longer applicable in the SDK. To maintain backward compatibility, we implemented a parameter filtering system—after all, it's quite headache-inducing when old configurations don't work:

// CopilotCliCompatibility.cs - Parameter filtering
private static readonly Dictionary<string, string> RejectedFlags = new()
{
    ["--headless"] = "Unsupported startup parameter",
    ["--model"] = "Passed through SDK native fields",
    ["--prompt"] = "Passed through SDK native fields",
    ["--interactive"] = "Interaction managed by provider",
};

public static CopilotCliArgumentBuildResult BuildCliArgs(CopilotOptions options)
{
    // Filter unsupported parameters, retain compatible parameters
    // Generate diagnostic information
}

Benefits of doing this:

Automatically filters incompatible CLI parameters, avoiding runtime errors—program crashes are no joke
Generates clear error diagnostic information, helping developers quickly locate problems
Ensures SDK stability, unaffected by CLI parameter changes

During the upgrade process, this compatibility handling mechanism helped us transition smoothly. Old configuration files can still be used, only requiring gradual adjustments based on diagnostic information—consider it a gradual process.

Runtime Pooling

Creating Copilot SDK sessions is costly, and frequently creating and destroying sessions affects performance. We implemented a session pool management system—like water in a pool, better to keep it for next use rather than refilling each time:

// CopilotProvider.cs - Session pool management
await using var lease = await _poolCoordinator.AcquireCopilotRuntimeAsync(
    request,
    async ct => await _gateway.CreateRuntimeAsync(sdkRequest, ct),
    cancellationToken);

if (lease.IsWarmLease)
{
    // Reuse existing session
    yield return CreateSessionReusedMessage();
}

await foreach (var eventData in lease.Entry.Resource.SendPromptAsync(...))
{
    yield return MapEvent(eventData);
}

Benefits of session pooling:

Session reuse: Requests with the same sessionId can reuse existing sessions, reducing startup overhead
Supports session recovery: Previous session state can be recovered after network interruption—after all, who can guarantee networks are always stable
Automatic pool management: Automatically cleans expired sessions, avoiding resource leaks

In HagiCode's actual use, session pooling significantly improved response speed, especially when handling continuous conversations—this improvement is quite noticeable.

Orleans Integration

HagiCode uses Orleans as its distributed framework, and we integrated the Copilot SDK into Orleans Grains—distributed systems, complex to talk about but quite smooth to use:

// GitHubCopilotGrain.cs - Distributed execution
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))
    {
        // Map to unified response format
        yield return BuildChunkResponse(chunk, startedAt);
    }
}

Advantages of Orleans integration:

Unified AI Provider abstraction: Can easily switch between different AI providers—use this today, that tomorrow, quite flexible
Multi-tenant isolation: Different users' Copilot sessions are isolated from each other, no interference
Persistent session state: Session state can recover across server restarts, no data loss from restarts

For scenarios needing to handle large volumes of concurrent requests, Orleans's distributed capabilities provide excellent scalability—after all, when a single machine can't handle it, distributed systems pick up the slack.

Practical Guide

Configuration Example

Here's a complete configuration example—copy, paste, modify, and it works:

{
  "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"]
          }
        }
      }
    }
  }
}

Usage Considerations

In actual use, we've summarized some points needing attention—some are lessons learned from pitfalls:

Startup timeout configuration: First-time Copilot CLI startup takes longer, recommend setting StartupTimeout to at least 30 seconds. For first-time login, even more time may be needed—after all, first-time login requires verification, can't be helped.

Permission management: Avoid using AllowAllTools: true in production. Use AllowedTools whitelist to control available tools, use DeniedTools blacklist to prohibit dangerous operations. This effectively prevents AI from executing dangerous commands—when it comes to security, being careful is always right.

Session management: Requests with the same sessionId automatically reuse sessions. Session state is persisted through ProviderSessionId. Cancellation operations are passed through CancellationTokenSource—good session management leads to good user experience.

Diagnostic output: Incompatible CLI parameters generate diagnostic type messages. Original SDK events are preserved as event.raw type. Error messages include categorization (startup timeout, parameter incompatibility, etc.) for convenient troubleshooting—quick problem location provides some comfort.

Best Practices

Based on our actual experience, here are some best practices—consider it a summary:

1. Use tool whitelists

var request = new AIRequest
{
    Prompt = "Analyze this file",
    AllowedTools = new[] { "Read", "Grep", "Bash(git:*)" }
};

Explicitly specify allowed tools through whitelisting to avoid AI performing unexpected operations. Especially for tools with write permissions (like Edit), extra caution is needed—after all, nobody wants to experience database deletion.

2. Set reasonable timeouts

options.Timeout = 3600;  // 1 hour
options.StartupTimeout = 60;  // 1 minute

Set appropriate timeout values based on task complexity. Too short may cause task interruption, too long may waste resources waiting for unresponsive requests—moderation in all things, excess is as bad as deficiency.

3. Enable session reuse

options.SessionId = "my-session-123";

Setting the same sessionId for related tasks can reuse previous session context, improving response speed—context is sometimes quite important.

4. Handle streaming responses

await foreach (var chunk in provider.StreamAsync(request))
{
    switch (chunk.Type)
    {
        case StreamingChunkType.ThinkingDelta:
            // Handle reasoning process
            break;
        case StreamingChunkType.ToolCallDelta:
            // Handle tool call
            break;
        case StreamingChunkType.ContentDelta:
            // Handle text output
            break;
    }
}

Streaming responses can display AI processing progress in real-time, improving user experience. Especially for time-consuming tasks, real-time feedback is very important—watching progress is better than waiting blindly.

5. Error handling and retry

try
{
    await foreach (var chunk in provider.StreamAsync(request))
    {
        // Handle response
    }
}
catch (CopilotSessionException ex)
{
    // Handle session exception
    logger.LogError(ex, "Copilot session failed");
    // Decide whether to retry based on exception type
}

Proper error handling and retry mechanisms can improve system stability—no one can guarantee programs never fail, being able to handle failures well is what matters.

Summary

The upgrade from CLI invocation to SDK integration brought significant value to the HagiCode project—how should I put it, this upgrade was quite worthwhile:

Improved stability: SDK provides more stable interfaces, unaffected by CLI version changes—no more worrying about version updates every day
Feature completeness: Can capture complete event streams, including reasoning process and tool execution status—can see both process and result
Development efficiency: Type-safe SDK interfaces make development more efficient, reducing runtime errors—with type checking, peace of mind
User experience: Real-time event feedback lets users more clearly understand the AI's work process—knowing what it's thinking is better than knowing nothing

This upgrade is not just a technical solution replacement, but an optimization of the entire AI capability layer architecture. Through layered design and abstract interfaces, we gained better maintainability and extensibility—once architecture is done well, subsequent tasks become easier.

If you're considering integrating GitHub Copilot into your .NET project, I hope the practical experiences in this article help you avoid some detours. The official SDK is indeed more stable and complete than CLI invocation, worth investing time to understand and master—after all, the right tools can make things事半功倍 (twice the result with half the effort), this saying isn't without reason.

References

If this article helped you:

Give it a like to let more people see it—your support means a lot to us
Come give us a Star on GitHub: github.com/HagiCode-org/site
Visit the official site to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click install to experience: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/
Public beta has started, welcome to install and experience

Writing this is about enough. Technical articles are never complete, after all technology evolves and we're always learning. If you have any questions or suggestions while using HagiCode, feel free to contact us anytime. Well, that's it for now...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-03-github-copilot-sdk-integration%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

The Hallucination Problem of AI Programming Assistants: How to Implement Specification-Driven Development with OpenSpec

Hagicode — Thu, 02 Apr 2026 02:33:59 +0000

The Hallucination Problem of AI Programming Assistants: How to Implement Specification-Driven Development with OpenSpec

AI programming assistants are powerful, but they often generate code that doesn't meet actual requirements or violates project specifications. This article shares how the HagiCode project implements "specification-driven development" through the OpenSpec process, significantly reducing AI hallucination risks with a structured proposal mechanism.

Background

Anyone who has used GitHub Copilot or ChatGPT to write code has likely experienced this: the AI-generated code looks beautiful, but it's full of problems when actually used. It might use a component from the project incorrectly, ignore the team's coding standards, or write large chunks of logic based on non-existent assumptions.

This is the so-called "AI hallucination" problem—in the programming domain, it manifests as generating code that appears reasonable but doesn't align with the actual situation of the project.

Actually, this situation is quite frustrating. As AI programming assistants become more widespread, this problem becomes increasingly serious. After all, AI lacks understanding of project history, architectural decisions, and coding standards, while excessive freedom easily leads it to "creatively" generate code that doesn't match reality. This is quite similar to writing articles—without proper structure, it's easy to write something unfocused, when that's not actually the case.

To address these pain points, we made a bold decision: instead of trying to make AI smarter, we put it in a "specification" cage. The changes brought by this decision may be greater than you imagine—I'll elaborate shortly.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an open-source AI code assistant project dedicated to solving real-world problems in AI programming through structured engineering practices.

The Root Causes of AI Hallucination

Before diving into the solution, let's first look at where the problem actually lies. After all, know yourself and know your enemy, and you can fight a hundred battles with no danger of defeat—though applying this saying to AI is also somewhat interesting.

Missing Context

AI models are trained on public codebases, but your project has its own history, conventions, and architectural decisions. This "tacit knowledge" cannot be directly accessed by AI, so the generated code often disconnects from the actual project situation.

This can't be entirely blamed on AI—after all, it hasn't worked on your project, so how would it know your unwritten rules? It's like a new intern who doesn't understand the rules—that's normal, but the cost might be somewhat high.

Excessive Freedom

When you ask AI to "help me implement a user authentication feature," it might generate code in any form. Without clear constraints, AI will implement according to what it "thinks" is reasonable, rather than according to your project's requirements.

This is like letting someone who has never learned your project specifications freely express themselves—can problems be avoided? Actually, it's not that it's irresponsible, it just doesn't know what responsibility is.

Lack of Verification

After AI generates code, if there's no structured review process, code based on wrong assumptions will directly enter the codebase. By the time problems are discovered in testing or even production environments, the cost is too high.

This is no different from locking the barn after the horse is stolen—except the horse has already run away, so what's the use of locking the barn? Everyone understands this principle, but actually doing it always feels troublesome. After all, before things go bad, who wants to spend extra time?

OpenSpec: The Answer to Specification-Driven Development

HagiCode chose OpenSpec as the solution, with the core idea being: all code changes must go through a structured proposal process, transforming abstract ideas into executable implementation plans.

This sounds quite grand, but it essentially means having AI write the requirements document before writing the code. After all, preparedness ensures success, unpreparedness spells failure—the ancients didn't deceive us.

What is OpenSpec

OpenSpec is an npm-based command-line tool (@fission-ai/openspec) that defines a standard proposal file structure and validation mechanism. Simply put, it requires AI to "write the requirements document first" before writing code.

Three-Step Process to Prevent Hallucination

OpenSpec ensures proposal quality through a three-step process:

Step 1: Initialize proposal - Set session state to Openspecing
Step 2: Intermediate processing - Maintain Openspecing state, gradually refine artifacts
Step 3: Complete proposal - Transition to Reviewing state

This design has a clever detail: the first step uses the ProposalGenerationStart type, and completion doesn't trigger a state transition. This ensures the entire multi-step process won't prematurely enter the review phase before completion.

Actually, this detail is quite interesting—it's like cooking. If you lift the lid before the cooking time is reached, you definitely won't produce a good dish. Only by being patient, taking it step by step, can you finally create a good dish.

// Implementation in the HagiCode project
public enum MessageAssociationType
{
    ProposalGeneration = 2,
    ProposalExecution = 3,

    /// <summary>
    /// Marks the start of the three-step proposal generation process
    /// Does not transition to Reviewing state upon completion
    /// </summary>
    ProposalGenerationStart = 5
}

Standardized File Structure

Every OpenSpec proposal follows the same directory structure:

openspec/
├── changes/                    # Active and archived changes
│   ├── {change-name}/
│   │   ├── proposal.md        # Proposal description
│   │   ├── design.md          # Design document
│   │   ├── specs/             # Technical specifications
│   │   └── tasks.md           # Executable task list
│   └── archive/               # Archived changes
└── specs/                     # Independent specification library

According to statistics from the HagiCode project, there are currently 4000+ archived changes and 150,000+ lines of specification files. This historical accumulation not only gives AI rules to follow but also provides a valuable knowledge base for the team.

This is like the classics left by ancients—read more and you'll naturally gain some insight. It's just that these classics aren't written on bamboo slips, but stored in files.

Multi-Layer Validation Mechanism

The system implements multi-layer validation to ensure proposal quality:

// Validate required files exist
ValidateProposalFiles()

// Validate execution prerequisites
ValidateExecuteAsync()

// Validate startup conditions
ValidateStartAsync()

// Validate archive conditions
ValidateArchiveAsync()

// Proposal name format validation (kebab-case)
ValidateNameFormat()

These validations are like gatekeepers with layers of checks—only truly qualified proposals can pass. Although it seems cumbersome, it's better than letting terrible code enter the codebase, right?

Prompt Template Constraints

AI execution in HagiCode uses predefined Handlebars templates that include clear step-by-step guidance and safeguards. For example:

Prohibit continuing without understanding user intent
Prohibit generating unverified code
Require re-providing when names are invalid
If a change already exists, recommend using the continue command rather than recreating

This approach of "dancing with shackles" actually makes AI more focused on understanding requirements and generating code that complies with specifications. Actually, constraints aren't necessarily a bad thing—after all, excessive freedom easily leads to chaos.

Practice: How to Use OpenSpec in Projects

Installation and Initialization

npm install -g @fission-ai/openspec@1
openspec --version  # Verify installation

The openspec/ folder structure will be automatically created in the project root directory.

This step doesn't need much explanation—installing tools, everyone understands. Just remember to use the @fission-ai/openspec@1 version, as new versions might have pitfalls—after all, stability comes first.

Creating Proposals

In HagiCode's conversation interface, use the shortcut command:

/opsx:new

Or specify the change name and target repository:

/opsx:new "add-user-auth" --repos "repos/web"

Creating proposals is like outlining an article—once you have an outline, the rest is easier to write. It's just that many people like to start writing directly, only to realize halfway through that their thinking doesn't flow—that's truly a headache.

Generating Artifacts

Use /opsx:continue to gradually generate the required artifacts:

proposal.md - Describes the purpose and scope of the change

# Proposal: Add User Authentication

## Why
The current system lacks user authentication functionality and cannot protect sensitive APIs.

## What Changes
- Add JWT authentication middleware
- Implement login/registration API
- Update frontend integration

design.md - Detailed technical design

# Design: Add User Authentication

## Context
Currently using public APIs accessible to anyone...

## Decisions
1. Choose JWT over Session...
2. Use HS256 algorithm...

## Risks
- Token leakage risk...
- Mitigation measures...

specs/ - Technical specifications and test scenarios

# user-auth Specification

## Requirements

### Requirement: JWT Token Generation
The system SHALL use the HS256 algorithm to generate JWT tokens.

#### Scenario: Valid login
- WHEN user provides valid credentials
- THEN the system SHALL return a valid JWT token

tasks.md - Executable task list

# Tasks: Add User Authentication

## 1. Backend Changes
- [ ] 1.1 Create AuthController
- [ ] 1.2 Implement JWT middleware
- [ ] 1.3 Add unit tests

These artifacts are actually like drafts for writing an article—once the draft is written, the main text naturally flows smoothly. It's just that many people don't like writing drafts, thinking it wastes time, but actually drafts are where you can best clarify your thinking.

Review and Application

After completing all artifacts:

/opsx:apply

AI will read all context files and execute tasks step by step according to the checklist in tasks.md. At this point, because there are clear specifications, the quality of generated code will be much higher.

Actually, by this step, things are already halfway done. With a clear task list, the rest is just methodical execution. It's just that many people skip the previous steps and come directly here, so quality naturally can't be guaranteed.

Archiving

After the change is complete:

/opsx:archive

Move completed changes to the archive/ directory for future reference and reuse.

Archiving is quite important—like properly storing a finished article. When you encounter similar problems in the future, flipping through previous records might give you answers. It's just that many people are too lazy to do it, thinking it's troublesome, but actually these accumulations are the most precious wealth.

Notes and Best Practices

Proposal Naming Convention

Use kebab-case format, starting with a letter, containing only lowercase letters, numbers, and hyphens:

✅ add-user-auth
❌ AddUserAuth
❌ add--user-auth

Naming conventions aren't a big deal, but being unified is generally good. After all, in code, consistency is important—it's just that many people don't pay attention to it.

Avoiding Common Errors

Using the wrong type in step 1 of the three-step process - Will transition state prematurely
Forgetting to trigger state transition in the final step - Will get stuck in Openspecing state
Skipping review to execute directly - Should first verify all artifacts are complete

These errors are easily made by beginners—experienced people naturally know how to avoid them. It's just that beginners will eventually become experienced, and taking some detours is fine, I just hope they don't take too many.

Managing Multiple Changes

OpenSpec supports managing multiple proposals simultaneously, which is particularly useful when handling large features:

# View all active changes
openspec list

# Switch to a specific change
openspec apply "add-user-auth"

# View change status
openspec status --change "add-user-auth"

Managing multiple changes is like writing several articles simultaneously—it requires some skill and patience. But you'll get used to it—after all, people can always adapt.

Understanding the Session State Machine

Understanding state transitions helps troubleshoot problems:

Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

Openspecing: Planning in progress
Reviewing: Under review (can repeatedly modify artifacts)
Executing: Executing (applying tasks.md)

State machines are essentially a set of rules. Rules can be annoying sometimes, but more often they're useful. After all, nothing can be accomplished without norms—as the ancients said long ago.

Summary

Through the OpenSpec process, the HagiCode project has achieved significant results in addressing AI hallucination:

Reduce hallucinations - AI must follow structured specifications and cannot generate code arbitrarily
Improve quality - Multi-layer validation ensures changes meet project standards
Accelerate collaboration - Archived changes provide reference for future development
Traceability - Each change has complete proposal, design, specification, and task records

This solution doesn't make AI smarter, but puts it in a "specification" cage. Practice has shown that dancing with shackles actually produces better dance.

Actually, this principle is simple—constraints aren't necessarily a bad thing. It's like writing articles—with format constraints, it's actually easier to write good things. It's just that many people don't like constraints, thinking they limit their creativity, but actually creativity also needs soil to bloom and bear fruit.

If you're also using AI programming assistants and have encountered similar problems, why not try OpenSpec? Specification-driven development may seem to add some steps, but this upfront investment will pay back many times over in code quality and maintenance efficiency.

After all, sometimes being slower is actually being faster. It's just that many people don't understand this principle...

References

OpenSpec npm package: www.npmjs.com/package/@fission-ai/openspec
HagiCode project repository: github.com/HagiCode-org/site
HagiCode official website: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
Docker Compose one-click installation: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/

If this article helps you, feel free to give a Star on GitHub. HagiCode public beta has begun—install now to participate in the experience.

This article is pretty much done. There's nothing particularly profound, just a summary of some practical experience. Hope it's useful to everyone—after all, with sharing, you learn and let others learn too—it's a win-win, so why not?

But articles are just articles—what's truly useful is practice. After all, what you get from paper is shallow—you must personally practice to truly understand, as the ancients said...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Elegantly Implementing New User Onboarding in React: HagiCode's driver.js Practice

Hagicode — Wed, 01 Apr 2026 07:37:53 +0000

Elegantly Implementing New User Onboarding in React: HagiCode's driver.js Practice

When users open your product for the first time, do they really know where to start? This article discusses our experience with driver.js for new user onboarding in the HagiCode project—just sharing some thoughts to spark discussion.

Background

Have you encountered this scenario: a new user signs up for your product, opens the page, and looks around confused—unsure where to click or what to do. As developers, we assume users will "explore on their own"—after all, human curiosity is limitless. But the reality is—most users will quietly leave within minutes because they can't find the entry point. The story begins abruptly, and ends just as naturally.

New user onboarding is an important solution to this problem, though implementation isn't simple. A good onboarding system needs to:

Accurately target and highlight page elements
Support multi-step onboarding flows
Remember user choices (complete/skip)
Not affect page performance and normal interactions
Have clear code structure for easy maintenance

During HagiCode's development, we faced the same challenges. HagiCode is an AI coding assistant project with a core workflow of "user creates proposal → AI generates plan → user reviews → AI executes"—an OpenSpec process. For users new to this concept, this workflow is entirely new, so we needed good onboarding to help them get started quickly. After all, new things always take some time to get used to.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is a Claude-based AI coding assistant that helps developers complete code tasks more efficiently through the OpenSpec workflow. You can view our open-source code on GitHub.

Why Choose driver.js

During the technology selection phase, we evaluated several mainstream onboarding libraries—each has its own characteristics:

Intro.js: Powerful but large in size, with relatively complex style customization
Shepherd.js: Well-designed API, but a bit "heavy" for our scenario
driver.js: Lightweight, concise, intuitive API, and supports React ecosystem

We ultimately chose driver.js, mainly based on these considerations:

Lightweight: Small core library that won't significantly increase bundle size
Simple API: Clear and intuitive configuration, quick to get started
Flexibility: Supports custom positioning, styles, and interaction behaviors
Dynamic Import: Can be loaded on-demand without affecting first-screen performance

When it comes to technology selection, there's no "best"—only "most suitable."

Technical Implementation

Core Configuration

driver.js configuration is very straightforward. Here's the core configuration from the HagiCode project:

import { driver } from 'driver.js';
import 'driver.js/dist/driver.css';

const newConversationDriver = driver({
  allowClose: true,           // Allow users to close the onboarding
  animate: true,              // Enable animation effects
  overlayClickBehavior: 'close', // Click overlay to close onboarding
  disableActiveInteraction: false, // Keep elements interactive
  showProgress: false,        // Don't show progress bar (we have custom progress management)
  steps: guideSteps           // Array of onboarding steps
});

The considerations behind these configurations:

allowClose: true - Respect user choice, don't force completion of onboarding
disableActiveInteraction: false - Some steps require actual user interaction (like typing), so we can't disable interaction
overlayClickBehavior: 'close' - Give users a quick way to exit

State Management

Persisting onboarding state is crucial—we don't want to re-onboard users every time they refresh the page. HagiCode uses localStorage to manage onboarding state:

export type GuideState = 'pending' | 'dismissed' | 'completed';

export interface UserGuideState {
  session: GuideState;
  detailGuides: Record<string, GuideState>;
}

// Read state
export const getUserGuideState = (): UserGuideState => {
  const state = localStorage.getItem('userGuideState');
  return state ? JSON.parse(state) : { session: 'pending', detailGuides: {} };
};

// Update state
export const setUserGuideState = (state: UserGuideState) => {
  localStorage.setItem('userGuideState', JSON.stringify(state));
};

We defined three states:

pending: Onboarding in progress, user hasn't completed or skipped yet
dismissed: User actively closed the onboarding
completed: User completed all steps

For proposal detail page onboarding, we also support more fine-grained state tracking (through the detailGuides dictionary), because a proposal may go through multiple stages (draft, review, execution complete), each requiring different onboarding. After all, the state of things is always changing.

Target Element Positioning

driver.js uses CSS selectors to locate target elements. HagiCode adopts a convention: using the data-guide custom attribute to mark onboarding targets:

const steps = [
  {
    element: '[data-guide="launch"]',
    popover: {
      title: 'Start New Conversation',
      description: 'Click here to create a new conversation session...'
    }
  }
];

Usage in components:

<button data-guide="launch" onClick={handleLaunch}>
  New Conversation
</button>

Benefits of this approach:

Avoids conflicts with business style class names
Clear semantics—immediately apparent that this element relates to onboarding
Easy to manage and maintain uniformly

Dynamic Import Optimization

Because onboarding functionality is only needed in specific scenarios (like new users visiting for the first time), we use dynamic import to optimize initial load performance:

const initNewUserGuide = async () => {
  // Dynamically import driver.js
  const { driver } = await import('driver.js');
  await import('driver.js/dist/driver.css');

  // Initialize onboarding
  const newConversationDriver = driver({
    // ...configuration
  });

  newConversationDriver.drive();
};

This way, driver.js and its styles are only loaded when needed, without affecting first-screen performance. After all, who wants to pay the waiting cost for something temporarily unused?

Onboarding Flow Design

HagiCode implements two onboarding paths covering users' core usage scenarios.

Conversation Onboarding (10 Steps)

This onboarding helps users complete the entire flow from creating a conversation to submitting their first complete proposal:

launch - Start onboarding, introduce the "New Conversation" button
compose - Guide user to type request in the input box
send - Guide clicking the send button
proposal-launch-readme - Guide creating a README proposal
proposal-compose-readme - Guide editing README request content
proposal-submit-readme - Guide submitting README proposal
proposal-launch-agents - Guide creating an AGENTS.md proposal
proposal-compose-agents - Guide editing AGENTS.md request
proposal-submit-agents - Guide submitting AGENTS.md proposal
proposal-wait - Explain that AI is processing, please wait

The design philosophy behind this onboarding: through two actual proposal creation tasks (README and AGENTS.md), let users personally experience HagiCode's core workflow. After all, knowledge from books is shallow—true understanding comes from practice.

The following images correspond to key nodes in the conversation onboarding:

The first step of conversation onboarding first brings users to the "New Normal Conversation" entry point.

Then guide users to write their first request in the input box, lowering the barrier for that first interaction.

After input is complete, clearly prompt users to send their first message, making the operation path more coherent.

When both proposals are created, the onboarding returns to the conversation list, letting users know they only need to wait for the system to continue executing and refresh.

Proposal Detail Onboarding (3 Steps)

When users enter the proposal detail page, corresponding onboarding is triggered based on the proposal's current state:

drafting (Draft stage) - Guide users to view AI-generated plan
reviewing (Review stage) - Guide users to execute the plan
executionCompleted (Complete stage) - Guide users to archive the plan

This onboarding's characteristic is state-driven—dynamically deciding which onboarding step to display based on the proposal's actual state. Things are always changing, so onboarding should change accordingly.

The image below shows the proposal detail page's onboarding state during the "drafting stage":

At this stage, the onboarding focuses user attention on the key action of "Generate Plan," avoiding confusion about what to do first when entering the detail page for the first time.

Element Rendering Retry Mechanism

In React applications, onboarding target elements may not have finished rendering yet (for example, waiting for asynchronous data loading). To handle this situation, HagiCode implements a retry mechanism:

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();
  });
};

Call this function before initializing onboarding to ensure target elements exist. Sometimes, waiting a bit longer is worth it.

Best Practices Summary

Based on HagiCode's practical experience, here are several key best practices:

1. Onboarding Should Be "Escapable"

Don't force users to complete onboarding. Some users are explorers who prefer to figure things out themselves. Provide a clear "Skip" button and remember their choice so you don't bother them next time. After all, beautiful things or people don't need to be possessed—appreciating their beauty from afar is enough.

2. Onboarding Content Should Be Concise and Powerful

Each onboarding step should focus on a single goal:

Title: Short and clear, no more than 10 characters
Description: Get straight to the point, tell users "what this is" and "why use it"

Avoid lengthy explanations—user attention during onboarding is very limited. Say too much, and no one will want to read it.

3. Selectors Should Be Stable

Use stable element marking methods that don't change frequently. The data-guide custom attribute is a good choice—avoid relying on class names or DOM structure, as these easily change during refactoring. Code is always changing, but some things should remain as stable as possible.

4. Test Your Onboarding

HagiCode wrote complete test cases for the onboarding functionality:

describe('NewUserConversationGuide', () => {
  it('should correctly initialize onboarding state', () => {
    const state = getUserGuideState();
    expect(state.session).toBe('pending');
  });

  it('should correctly update onboarding state', () => {
    setUserGuideState({ session: 'completed', detailGuides: {} });
    const state = getUserGuideState();
    expect(state.session).toBe('completed');
  });
});

Testing ensures that when refactoring code, you won't accidentally break onboarding functionality. After all, no one wants to break existing functionality while making changes.

5. Performance Optimization

Use dynamic imports to lazy load the onboarding library
Avoid initializing onboarding logic after users have completed it
Consider the performance impact of onboarding animations—can disable animations on low-end devices

Performance, like life, should be conserved where it should be.

Summary

New user onboarding is an important part of improving product user experience. In the HagiCode project, we used driver.js to build a complete onboarding system covering the entire workflow from conversation creation to proposal execution.

Through this article, we hope to convey these core points:

Technology selection should match requirements: driver.js isn't the most powerful, but it's the most suitable for us
State management is crucial: Use localStorage to persist onboarding state and avoid repeatedly bothering users
Onboarding design should be focused: Each step solves one problem, don't try to do too much
Code structure should be clear: Separate onboarding configuration, state management, and UI logic for easy maintenance

If you're adding new user onboarding functionality to your project, I hope the practical experience shared in this article helps you. Actually, technology isn't that mysterious—try more, summarize more, and it'll get better over time...

References

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-01-new-user-guide-with-driverjs%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Typing is Not as Good as Speaking, Speaking is Not as Good as Screenshots—Multimodal Input Practices for AI Code Assistants

Hagicode — Tue, 31 Mar 2026 01:37:23 +0000

Typing is Not as Good as Speaking, Speaking is Not as Good as Screenshots—Multimodal Input Practices for AI Code Assistants

Actually, when it comes to writing code, there's an upper limit to how fast you can type. Sometimes something that can be said in a sentence requires banging on the keyboard for ages; sometimes a single image can explain clearly what would take piles of text to describe. This article discusses the experiences we encountered while building HagiCode—whether it's speech recognition or image upload, the goal is simply to make the AI code assistant a bit easier to use, that's all.

Background

While working on HagiCode, we discovered a problem—or rather, a problem that naturally emerged as users spent more time with it: relying solely on typing can be quite exhausting.

Think about it: user interaction with the Agent is a core scenario. But having to sit at the keyboard clacking away every time... well, the efficiency isn't exactly high:

Typing is too slow: Some complex problems—errors, interface issues—can take half a minute to type out, but might be spoken in ten seconds. That time difference is pretty frustrating.
Images are more direct: Sometimes when the interface throws an error, or you want to compare with a design mock, or show code structure... the saying "a picture is worth a thousand words" may be old, but the truth remains. Letting AI "see" the problem directly is much clearer than describing it for ages.
Interaction should be natural: Modern AI assistants should support text, voice, images and other methods, right? Users should be able to use whatever they want—that's what natural means, isn't it?

So we thought, why not add speech recognition and image upload features to HagiCode, making Agent operations more convenient. After all, letting users type a few less characters is a good thing.

About HagiCode

The solutions shared in this article come from our practice in the HagiCode project—or rather, experiences discovered through constantly stepping into pits.

HagiCode is an open-source AI code assistant project with a simple idea: use AI technology to improve development efficiency. As we built it, we discovered that users actually have quite strong demand for multimodal input—sometimes saying a sentence is faster than typing a pile of text, sometimes a single screenshot is clearer than describing for ages.

These demands pushed us forward, and eventually we ended up with features like speech recognition and image upload. Users can interact with AI in the most natural way. It feels pretty good.

Analysis

Technical Challenges of Speech Recognition

When implementing the speech recognition feature, we encountered a tricky problem: the browser's WebSocket API doesn't support custom HTTP headers.

And the speech recognition service we chose is ByteDance's Doubao speech recognition API. This API偏偏 insists on passing authentication information through HTTP headers—things like accessToken, secretKey, and such. Great, now we have a technical contradiction:

// Browser WebSocket API doesn't support the following approach
const ws = new WebSocket('wss://api.com/ws', {
  headers: {
    'Authorization': 'Bearer token'  // Not supported
  }
});

The solutions before us basically came down to two:

URL query parameter solution: Put authentication info in the URL
- Advantage: simple to implement
- Disadvantage: credentials exposed on frontend, poor security; and some APIs strictly require header validation
Backend proxy solution: Implement WebSocket proxy on the backend
- Advantage: credentials stored securely on backend; fully compatible with API requirements
- Disadvantage: slightly more complex to implement

Ultimately we chose the backend proxy solution. After all, security is a bottom line that cannot be compromised—on this point, no one should try to fool anyone.

Image Upload Functional Requirements

For the image upload feature, our requirements were actually quite simple:

Multiple upload methods: click to select file, drag-and-drop upload, clipboard paste—gotta have them all, right?
File validation: type restrictions (PNG, JPG, WebP, GIF), size limits (5-10MB)—these are basic operations
User experience: upload progress, preview, error prompts—people need to know what's happening
Security: server-side validation, prevent malicious file uploads—this is a big deal

Solutions

Speech Recognition: WebSocket Proxy Architecture

We designed a three-layer architecture for speech recognition. How should I put it—we basically found a path:

Browser WebSocket
       |
       | ws://backend/api/voice/ws
       | (binary audio)
       v
Backend Proxy
       |
       | wss://openspeech.bytedance.com/ (with auth header)
       v
Doubao API

Core Component Implementation:

Frontend AudioWorklet Processor:

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

    // Resample to 16kHz (Doubao API requirement)
    const samples = this.resampleAudio(input, 48000, 16000);

    // Accumulate samples to 500ms chunks
    this.accumulatedSamples.push(...samples);

    if (this.accumulatedSamples.length >= 8000) {
      // Convert to 16-bit PCM and send
      const pcm = this.floatToPcm16(this.accumulatedSamples);
      this.port.postMessage({ type: 'audioData', data: pcm.buffer }, [pcm.buffer]);
      this.accumulatedSamples = [];
    }
    return true;
  }
}

Backend WebSocket Handler (C#):

[HttpGet("ws")]
public async Task GetWebSocket()
{
    if (HttpContext.WebSockets.IsWebSocketRequest)
    {
        await _webSocketHandler.HandleAsync(HttpContext);
    }
}

Frontend VoiceTextArea Component:

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">
        {/* Voice button */}
        <button onClick={handleButtonClick}>
          {isRecording ? <VolumeWaveform volume={volume} /> : <Mic />}
        </button>
        {/* Text input */}
        <textarea value={displayValue} onChange={handleChange} />
      </div>
    );
  }
);

Image Upload: Multi-Method Upload Component

We built a fully-featured image upload component that supports all three upload methods. How should I put it—we basically covered all the common user scenarios.

Core Features:

Three Upload Methods:

// Click upload
const handleClick = () => fileInputRef.current?.click();

// Drag-and-drop upload
const handleDrop = (e: React.DragEvent) => {
  const file = e.dataTransfer.files?.[0];
  if (file) uploadFile(file);
};

// Clipboard paste
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);
    }
  }
};

Frontend Validation:

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 };
};

Backend Upload Handler (TypeScript):

export const Route = createFileRoute('/api/upload')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const formData = await request.formData();
        const file = formData.get('file') as File;

        // Validate
        const validation = validateFile(file);
        if (!validation.isValid) {
          return Response.json({ error: validation.error }, { status: 400 });
        }

        // Save file
        const uuid = uuidv4();
        const filePath = join(uploadDir, `${uuid}${extension}`);
        await writeFile(filePath, buffer);

        return Response.json({ url: `/uploaded/${today}/${uuid}${extension}` });
      }
    }
  }
});

Practice Guide

How to Use Speech Recognition

Configure speech recognition service:
- Go to speech recognition settings page
- Configure Doubao Speech's AppId and AccessToken
- (Optional) Configure hot words to improve recognition accuracy for technical terms
Use in input field:
- Click the microphone icon on the left side of the input field
- Start speaking when you see the waveform animation
- Click the icon again to stop recording
- Recognition results will be automatically inserted at the cursor position
Hot Word Configuration Example:

TypeScript
React
useState
useEffect

How to Use Image Upload

Upload methods:
- Click upload button to select file
- Drag image directly to upload area
- Use Ctrl+V to paste screenshot from clipboard
Supported formats: PNG, JPG, JPEG, WebP, GIF
Size limit: Default 5MB (configurable)

Notes

Speech recognition:
- Requires microphone permission
- Recommended for use in quiet environments
- Maximum recording duration supported is 300 seconds (configurable)
Image upload:
- Only supports common image formats
- Note file size limits
- Uploaded images automatically generate preview URLs
Security considerations:
- Speech recognition credentials stored on backend
- Image upload has strict server-side validation
- Production environment recommends using HTTPS/WSS

Summary

After adding speech recognition and image upload, HagiCode's user experience has indeed improved significantly. Users can now interact with AI in more natural ways—speaking instead of typing, screenshots instead of describing. How should I put it... it's like finally finding a more comfortable way to communicate.

When building this feature, we encountered the browser WebSocket issue of not supporting custom headers, and ultimately solved it through the backend proxy solution. This solution not only ensures security but also lays the foundation for integrating other WebSocket services that require authentication in the future—I guess that's an unexpected bonus.

The image upload component is similar too—using multiple upload methods lets users choose the most convenient one for their scenario. Whether clicking, dragging, or pasting directly, uploads can be completed quickly. All roads lead to Rome, it's just that some roads are easier to travel, others are a bit more winding.

"Typing is not as good as speaking, speaking is not as good as screenshots"—this saying fits quite well here. If you're also building similar AI assistant products, I hope these experiences can help you, even if just a little.

References

If this article helps you:

Give it a like to help more people see it
Come to GitHub and give us a Star: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch the 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click install and experience: docs.hagicode.com/installation/docker-compose
Desktop quick install: hagicode.com/desktop/
Public beta has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-03-31-voice-and-image-upload-multimodal-input%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

GLM-5.1 Full Support and Gemini CLI Integration: HagiCode's Multi-Model Evolution

Hagicode — Mon, 30 Mar 2026 01:57:32 +0000

GLM-5.1 Full Support and Gemini CLI Integration: HagiCode's Multi-Model Evolution

This article introduces recent important updates to the HagiCode platform—comprehensive support for Zhipu AI's GLM-5.1 model, and the successful integration of Gemini CLI as the tenth Agent CLI. These two updates further strengthen the platform's multi-model capabilities and multi-CLI ecosystem.

Background

Time flies, and the development of large language models grows like bamboo in spring—shooting upward rapidly. Once we cheered for "an AI that can write code," but now we're in an era of multi-model collaboration and multi-tool integration. Is this interesting? Perhaps, after all, what developers need has never been just tools themselves, but a kind of composure that can adapt to different scenarios and switch flexibly.

As an AI-assisted coding platform, HagiCode has recently welcomed two major events: first, the comprehensive integration of Zhipu AI's GLM-5.1 model, and second, Gemini CLI officially becoming the tenth supported Agent CLI. These events are neither big nor small, but for the platform's improvement, they're certainly a good thing.

GLM-5.1 is Zhipu AI's latest flagship model. Compared to GLM-5.0, it has stronger reasoning capabilities, deeper code understanding, and smoother tool calling. More importantly, it's the first GLM model to support image input—what does this mean? It means users can directly take screenshots for the AI to see problems, without struggling to describe them. If you've used it, you understand this convenience.

At the same time, through the HagiCode.Libs.Providers architecture, HagiCode has successfully integrated Gemini CLI. This is the tenth Agent CLI, and honestly, reaching this point brings some sense of accomplishment.

It's worth mentioning that HagiCode's image upload feature allows users to communicate directly with AI through screenshots. Even when running GLM 4.7, the platform runs well and has already helped complete many important construction projects for the project. As for GLM-5.1? Naturally, it will go even further.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an open-source AI-assisted coding platform, designed to provide developers with a flexible and powerful AI programming assistant through multi-model and multi-CLI architecture design. Project address: github.com/HagiCode-org/site

Multi-CLI Architecture Design

One of HagiCode's core advantages is supporting multiple different AI programming CLI tools through a unified abstraction layer. The benefits of this design, when you get down to it, are just: new things can come in, old things can stay, and the code doesn't get messy. After all, everyone hopes life could be like this, right?

AIProviderType Enumeration

The platform defines supported CLI provider types through the AIProviderType enumeration:

public enum AIProviderType
{
    ClaudeCodeCli = 0,    // Claude Code CLI
    CodexCli = 1,          // GitHub Copilot Codex
    GitHubCopilot = 2,     // GitHub Copilot
    CodebuddyCli = 3,     // Codebuddy CLI
    OpenCodeCli = 4,      // OpenCode CLI
    IFlowCli = 5,         // IFlow CLI
    HermesCli = 6,        // Hermes CLI
    QoderCli = 7,         // Qoder CLI
    KiroCli = 8,          // Kiro CLI
    KimiCli = 9,          // Kimi CLI
    GeminiCli = 10,       // Gemini CLI (newly added)
}

As you can see, Gemini CLI has joined this family as the tenth member. Each CLI has unique characteristics and applicable scenarios, and users can flexibly choose according to their needs. After all, all roads lead to Rome—some roads are just easier to walk, others a bit more winding.

Provider Architecture

HagiCode.Libs.Providers provides a unified Provider interface, making the integration of each CLI standardized and concise. Taking Gemini CLI as an example:

public class GeminiProvider : ICliProvider<GeminiOptions>
{
    private static readonly string[] DefaultExecutableCandidates = ["gemini", "gemini-cli"];
    private const string ManagedBootstrapArgument = "--acp";

    public string Name => "gemini";
    public bool IsAvailable => _executableResolver.ResolveFirstAvailablePath(DefaultExecutableCandidates) is not null;
}

The benefits of this design are:

New CLI integration only requires implementing one Provider class
Unified lifecycle management and session pooling
Automated alias resolution and executable file lookup

When you get down to it, this design just simplifies complex things and makes life a little easier.

Provider Registry

The Provider Registry automatically handles alias mapping and registration:

if (provider is GeminiProvider)
{
    registry.Register(provider.Name, provider, ["gemini-cli"]);
    continue;
}

This means users can call Gemini CLI using either gemini or gemini-cli, and the system will automatically recognize it. It's like having many friends—some call you by your formal name, some by your nickname, but either way, it's you.

GLM-5.1 Model Support

GLM-5.1 is Zhipu AI's latest flagship model, and HagiCode has completed comprehensive support for it.

Secondary Professions Catalog

HagiCode manages all supported models through the Secondary Professions Catalog. Here's the configuration for the GLM series:

Model ID	Name	SupportsImage	Compatible CLI Families
`glm-4.7`	GLM 4.7	-	claude, codebuddy, hermes, qoder, kiro
`glm-5`	GLM 5	-	claude, codebuddy, hermes, qoder, kiro
`glm-5-turbo`	GLM 5 Turbo	-	claude, codebuddy, hermes, qoder, kiro
`glm-5.0`	GLM 5.0 (Legacy)	-	claude, codebuddy, hermes, qoder, kiro
`glm-5.1`	GLM 5.1	true	claude, codebuddy, hermes, qoder, kiro

The key features of GLM-5.1 can be summarized as:

Independent version identifier, without legacy baggage
First GLM model to support image input
Stronger reasoning capabilities and code understanding
Extensive multi-CLI compatibility

GLM-5.1 vs GLM-5.0

From a code perspective, the key differences between GLM-5.1 and GLM-5.0:

// GLM-5.0 (Legacy) - has special retention logic
private const string Glm50CodebuddySecondaryProfessionId = "secondary-glm-5-codebuddy";
private const string Glm50CodebuddyModelValue = "glm-5.0";

// GLM-5.1 - independent new model identifier
private const string Glm51SecondaryProfessionId = "secondary-glm-5-1";
private const string Glm51ModelValue = "glm-5.1";

GLM-5.0 carries a "Legacy" mark, which is an old version identifier retained for backward compatibility. GLM-5.1 is a completely new independent version without any historical baggage. It's like some people always live in the past, while others travel light and walk faster.

Configuring GLM-5.1

Example configuration for using GLM-5.1 in HagiCode:

{
  "primaryProfessionId": "profession-claude-code",
  "secondaryProfessionId": "secondary-glm-5-1",
  "model": "glm-5.1",
  "reasoning": "high"
}

Image Upload Feature

HagiCode's image support is implemented through the SupportsImage property of SecondaryProfession:

public class HeroSecondaryProfessionSettingDto
{
    public bool SupportsImage { get; set; }
}

In the Secondary Professions Catalog, the configuration for GLM-5.1 is as follows:

{
  "id": "secondary-glm-5-1",
  "supportsImage": true
}

This means users can directly upload screenshots for AI analysis, such as:

Screenshots of error messages
UI interface issues
Data visualization charts
Code execution results

No need to manually describe problems—just take a screenshot. Once you use this feature, you'll understand its convenience. After all, for some things, seeing is better than hearing a thousand descriptions.

Gemini CLI Integration

As the tenth Agent CLI, Gemini CLI is integrated into HagiCode through the standard Provider architecture.

Configuration Options

Gemini CLI supports rich configuration options:

public class GeminiOptions
{
    public string? ExecutablePath { get; set; }
    public string? WorkingDirectory { get; set; }
    public string? SessionId { get; set; }
    public string? Model { get; set; }
    public string? AuthenticationMethod { get; set; }
    public string? AuthenticationToken { get; set; }
    public Dictionary<string, string?> AuthenticationInfo { get; set; }
    public Dictionary<string, string?> EnvironmentVariables { get; set; }
    public string[] ExtraArguments { get; set; }
    public TimeSpan? StartupTimeout { get; set; }
    public CliPoolSettings? PoolSettings { get; set; }
}

These options cover everything from basic configuration to advanced features, allowing users to flexibly configure according to their needs. After all, everyone's needs are different, and having flexibility is always good.

ACP Communication Protocol

Gemini CLI supports the ACP (Agent Communication Protocol), which is HagiCode's unified CLI communication standard. Through ACP, different CLIs can interact with the platform in a consistent manner, greatly simplifying integration work. When you get down to it, it's just unifying complex things so everyone can work a little easier.

Environment Configuration

To use Zhipu AI's models, you need to configure the corresponding environment variables.

Zhipu AI ZAI Platform

export ANTHROPIC_AUTH_TOKEN="your-zai-api-key"
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"

Alibaba Cloud DashScope

export ANTHROPIC_AUTH_TOKEN="your-aliyun-api-key"
export ANTHROPIC_BASE_URL="https://coding.dashscope.aliyuncs.com/apps/anthropic"

After configuration is complete, HagiCode can call the GLM-5.1 model normally. This task is neither difficult nor simple—just follow the steps.

HagiCode's Own Build Practice

Speaking of practice, the best example is HagiCode platform's own build process. HagiCode's development has already fully utilized AI capabilities:

Runs Well with GLM 4.7

HagiCode platform is well-optimized, so even using GLM 4.7 provides a good development experience. The platform has helped complete several important build projects, including:

Multi-CLI Provider integration
Image upload feature implementation
Documentation generation and content publishing

This is actually quite good—after all, not everyone needs to use the latest things. What suits you is best.

GLM-5.1 for Greater Efficiency

After upgrading to GLM-5.1, these capabilities will be further enhanced:

Stronger code understanding, reducing back-and-forth communication
More accurate dependency analysis, pointing in the right direction in one go
More efficient error diagnosis, quickly locating problems
Image input support, accelerating problem description

It's like upgrading from a bicycle to a car—you can reach the same destinations, just with different speed and comfort.

Multi-CLI Integration Best Practices

HagiCode.Libs.Providers provides a unified registration and usage mechanism:

services.AddHagiCodeLibs();

var gemini = serviceProvider.GetRequiredService<ICliProvider<GeminiOptions>>();
var codebuddy = serviceProvider.GetRequiredService<ICliProvider<CodebuddyOptions>>();
var hermes = serviceProvider.GetRequiredService<ICliProvider<HermesOptions>>();

This dependency injection design makes using each CLI very concise, and also facilitates unit testing and mocking. After all, writing clean code is also a form of responsibility to yourself.

Notes

In actual use, there are a few things to note:

API Key Configuration: Ensure ANTHROPIC_AUTH_TOKEN is correctly set, otherwise the model cannot be called
Model Availability: GLM-5.1 requires enabling permissions at the corresponding model provider
Image Feature: Only models with supportsImage: true can use the image upload feature
CLI Installation: Before using Gemini CLI, ensure gemini or gemini-cli is in the system PATH

These are small things, but if small things aren't handled well, they can become big things. So pay attention to them.

Summary

Through comprehensive support for GLM-5.1 and successful integration of Gemini CLI, HagiCode has further strengthened its capabilities as a multi-model, multi-CLI AI programming platform. These updates not only provide users with more choices but also demonstrate HagiCode's forward-looking and extensible architecture design.

GLM-5.1's image support capability, combined with HagiCode's screenshot upload feature, makes "speaking through pictures" possible—greatly reducing the cost of problem description. And support for ten CLIs means users can flexibly choose the most suitable AI programming assistant based on their preferences and scenarios. After all, having more choices is always a good thing.

Most importantly, HagiCode platform's own build practice proves: even using GLM 4.7, the platform can run well and complete complex tasks; after upgrading to GLM-5.1, development efficiency will be further improved. It's like life—you don't necessarily have to pursue the best, what suits you is good. Of course, if you can become better while still being suitable, that's naturally even better.

If you're interested in a multi-model, multi-CLI AI programming platform, why not try HagiCode—open-source, free, and constantly evolving. Trying doesn't cost anything, and it might really suit you.

References

If this article helped you:

Give a Star on GitHub: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch a 30-minute practical demo: www.bilibili.com/video/BV1pirZBuEzq/
One-click installation experience: docs.hagicode.com/installation/docker-compose
Public beta has started, welcome to install and experience

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-03-30-hagicode-glm-5-1-gemini-cli-update%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Technical Analysis of the HagiCode Soul Platform: From Concept to Independent Platform

Hagicode — Sun, 29 Mar 2026 13:20:14 +0000

Technical Analysis of the HagiCode Soul Platform: From Concept to Independent Platform

Writing technical articles isn't really a big deal—it's just organizing the pits you've fallen into and the detours you've taken. After all, who hasn't been young? This article will dive deep into the design philosophy, architectural evolution, and core technical implementation of the Soul (AI Agent Personality Configuration System) in the HagiCode project, exploring how to provide a more focused experience for creating and sharing Agent personalities through an independent platform.

Background

In the practice of AI Agent development, we often encounter a seemingly simple yet extremely important question: How can different Agents have stable and unique language styles and personality traits?

This question is quite frustrating. In the early Hero system of HagiCode, different heroes (Agent instances) mainly relied on class configurations and generic prompts to distinguish their expression styles. This approach brought some obvious pain points—perhaps those who have done this can relate.

First, language styles are difficult to maintain consistently. For the same "software engineer" role, today's response might be professional and rigorous, while tomorrow's output becomes casual and scattered. This isn't a problem with the model itself, but rather the lack of an independent personality configuration layer to constrain and guide the output style.

Second, the sense of character is generally weak. When we describe an Agent's characteristics, we can often only use vague adjectives like "friendly," "professional," or "humorous," without specific language rules to support these abstract descriptions. Simply put, it sounds nice but there's no way to actually implement it.

Third, the reusability of personality configurations is nearly zero. Suppose we carefully design a "cat maid waitress" speaking style and want to reuse this expression in another business scenario—we almost need to configure from scratch. Beautiful things or people don't have to be possessed, we just want to reuse them... but it's really difficult.

It was precisely to solve these practical problems that we introduced the Soul mechanism—a language style configuration layer independent of equipment and descriptions. Soul can define an Agent's speaking habits, tone preferences, and word choice boundaries, can be shared and reused across multiple heroes, and can be automatically injected into system prompts when a Session is first called.

Some might think this is nothing special—just configuring a few prompts, right? But sometimes, the key to a problem isn't whether it can be done, but how to do it more elegantly. As Soul capabilities gradually matured, we realized it had the potential for independent development. A dedicated Soul platform could allow users to more focusedly create, share, and browse various interesting personality configurations without being distracted by other features of the Hero system. Thus, the soul.hagicode.com independent platform was born.

About HagiCode

HagiCode is an open-source AI code assistant project built with a modern tech stack, dedicated to providing developers with a smooth intelligent programming experience. The Soul platform solution shared in this article is exactly the practical experience we explored during HagiCode development to solve the practical problem of Agent personality management. If you find this solution valuable, it shows we've accumulated certain technical judgment in engineering practice—then the HagiCode project itself is worth understanding.

GitHub: github.com/HagiCode-org/site
Official Site: hagicode.com
Video Demo: www.bilibili.com/video/BV1pirZBuEzq/
Desktop Quick Install: hagicode.com/desktop/

Technical Architecture Evolution of the Soul Platform

The development of the Soul Platform didn't happen overnight, but went through three clear stages. This story started suddenly and ended naturally.

Phase 1: Hero-Embedded Soul Configuration

The earliest Soul implementation existed as a functional module within the Hero workspace. We added an independent SOUL editing area in the Hero interface, supporting both preset application and text fine-tuning.

Preset application allowed users to select from classic personality templates, such as "Professional Software Engineer" or "Cat Maid Waitress." Text fine-tuning let users make personalized modifications based on presets. The backend Hero entity correspondingly added a Soul field and identified the source through SoulCatalogId.

This phase solved the "is it there" problem, and it was still a child, growing through stumbles. But as Soul content became richer, the architecture coupled with the Hero system began to show limitations.

Phase 2: In-Site Marketplace

To provide better Soul discovery and reuse experience, we built a SOUL Marketplace directory page, supporting browsing, searching, detail viewing, and favoriting.

In this phase, we introduced a combination design of 50 main Catalogs (base characters) and 10 orthogonal rules (expression styles). The main Catalog defines the Agent's core persona, such as abstract character settings like "Mistport Traveler" or "Night Hunter"; orthogonal rules define the expression methods, such as language style features like "Concise & Professional" or "Verbose & Friendly".

50 × 10 = 500 combination possibilities, providing users with a rich personality configuration space. This number isn't much, but isn't little either—how should I put it, all roads lead to Rome, some roads are just easier to walk. The backend generates a complete SOUL catalog through catalog-sources.json, while the frontend is responsible for presenting these catalog items as an interactive card list.

The in-site Marketplace was a good transition solution, but still just a transition. It still depended on the main system, and for users who only wanted to use Soul functionality, the access path was still too deep. After all, who wants to go in a big circle just to do something simple?

Phase 3: Independent Platform Split

Ultimately, we decided to migrate Soul capabilities to an independent repository (repos/soul), changing the original main system's Marketplace to external jump guidance. The new platform adopts a Builder-first design philosophy—the default homepage is the creation workspace, where users can start creating their own personality configurations the moment they open the website.

The tech stack in this phase also underwent a comprehensive upgrade: adopting the Vite 8 + React 19 + TypeScript 5.9 combination, using the shadcn/ui component system to unify design language, and introducing Tailwind CSS 4's theme variable system. The improvement in frontend engineering level laid a solid foundation for subsequent feature iterations.

Everything faded... no, everything is just beginning.

Core Technical Design and Implementation

Material Integration Strategy

A core design philosophy of the Soul platform is local-first. This means the homepage must be fully operable without a backend, and remote material failures must not block page entry.

Actually, this isn't a big deal—just considering one more step when designing the system. Local snapshots serve as the baseline, remote serves as enhancement, and this approach allows the product to provide basic usability under any network conditions. Specifically, we adopted a two-layer material architecture:

export async function loadBuilderMaterials(): Promise<BuilderMaterials> {
  const localMaterials = createLocalMaterials(snapshot)  // Local baseline

  try {
    const inspirationFragments = await fetchMarketplaceItems()  // Remote enhancement
    return { ...localMaterials, inspirationFragments, remoteState: "ready" }
  } catch (error) {
    return { ...localMaterials, remoteState: "fallback" }  // Graceful degradation
  }
}

Local materials come from build-time snapshots of the main system documentation, containing complete data for 50 base characters and 10 expression rules. Remote materials come from user-published Souls, obtained through the Marketplace API. The combination of both provides users with a complete material spectrum from official templates to community creativity. Wanting to laugh to disguise the tears you shed... no, actually it's nothing, just local plus remote.

Soul Fragment Data Model

The core data abstraction of Soul is SoulFragment (Soul Fragment):

export type SoulFragment = {
  fragmentId: string
  group: "main-catalog" | "expression-rule" | "published-soul"
  title: string
  summary: string
  content: string
  keywords: string[]
  localized?: Partial<Record<AppLocale, LocalizedFragmentContent>>
  sourceRef: SoulFragmentSourceRef
  meta: SoulFragmentMeta
}

The group field distinguishes fragment types: main catalog defines character core, orthogonal rules define expression methods, and user-published Souls are marked as published-soul. The localized field supports multiple languages, allowing the same fragment to present different titles and descriptions in different language environments. Internationalization design should be done early—we've also applied this principle.

Builder draft state encapsulates the user's current editing state:

export type SoulBuilderDraft = {
  draftId: string
  name: string
  selectedMainFragmentId: string | null
  selectedRuleFragmentId: string | null
  inspirationSoulId: string | null
  mainSlotText: string
  ruleSlotText: string
  customPrompt: string
  previewText: string
  updatedAt: string
}

Each fragment selected by the user in the editor has its content spliced into the corresponding slot, forming the final preview text. mainSlotText corresponds to main character content, ruleSlotText corresponds to expression rule content, and customPrompt is the user's additional supplementary instructions.

Preview Compilation Mechanism

Preview compilation is the core function of Soul Builder, assembling the fragments selected by the user and custom text into a copyable system prompt:

export function compilePreview(
  draft: Pick<SoulBuilderDraft, "mainSlotText" | "ruleSlotText" | "customPrompt">,
  fragments: {
    mainFragment: SoulFragment | null
    ruleFragment: SoulFragment | null
    inspirationFragment: SoulFragment | null
  }
): PreviewCompilation {
  // Assembly logic: main character + expression rule + inspiration reference + custom content
}

The compilation result is displayed in the central preview panel, where users can see the final effect in real-time and copy it to the clipboard with one click. This function is quite simple, isn't it? But simple things are often the most practical.

Frontend State Management

The frontend state management of Soul Builder follows an important principle: clear division of state boundaries. Specifically, drawer state is not persisted and not directly written to drafts; only explicit Builder operations trigger state changes.

// Domain state (useSoulBuilder)
export function useSoulBuilder() {
  // Material loading and caching
  // Slot aggregation and preview compilation
  // Copy behavior and feedback messages
  // Locale-safe descriptors
}

// Presentation state (useHomeEditorState)
export function useHomeEditorState() {
  // activeSlot, drawerSide, drawerOpen
  // Default focus behavior
}

This separation ensures the safety of editing state and the responsiveness of the interface. Opening and closing the drawer is pure UI interaction and doesn't need to trigger complex persistence logic. This is just stating the obvious! No, actually it's very important—interface state and business state should be clearly distinguished to avoid UI interaction polluting the core data model.

Single Drawer Lifecycle

Soul Builder adopts a single drawer mode: only one slot drawer can be open at a time. Clicking the overlay, pressing ESC, or switching slots automatically closes the current drawer. This design simplifies state management and aligns with common mobile drawer interaction patterns.

Closing the drawer doesn't clear the current editing content—when users switch back, their context is preserved. This "lightweight" drawer design avoids interrupting user operations. After all, who wants to lose their hard-written content because of an accidental click?

Bilingual Support Architecture

Internationalization is an important feature of the Soul platform. System copy fully supports bilingual switching, while user draft text is never rewritten due to language switching—because draft text itself is user-entered content and doesn't involve system translation.

Official inspiration cards (Marketplace Soul) maintain their upstream display names but provide best-effort English summaries. For Souls with Chinese names, we generate English versions through predefined mapping rules:

// Main character English name mapping
const mainNameEnglishMap = {
  "雾港旅人": "Mistport Traveler",
  "夜航猎手": "Night Hunter",
  // ...
}

// Orthogonal rule English name mapping
const ruleNameEnglishMap = {
  "简洁干练": "Concise & Professional",
  "啰嗦亲切": "Verbose & Friendly",
  // ...
}

This mapping table looks quite simple, but maintaining it well takes considerable thought. After all, with 50 main characters and 10 orthogonal rules, multiplied together that's 500 combinations—not large, not small.

Backend Catalog Generation

Batch generation of Soul Catalog is completed on the backend, using C# to implement the automated creation of 50 × 10 = 500 combinations:

foreach (var main in source.MainCatalogs)
{
    foreach (var orthogonal in source.OrthogonalCatalogs)
    {
        var catalogId = $"soul-{main.Index:00}-{orthogonal.Index:00}";
        var displayName = BuildNickname(main, orthogonal);
        var soulSnapshot = BuildSoulSnapshot(main, orthogonal);
        // Write to database...
    }
}

The nickname generation algorithm combines main character names with expression rule names to create imaginative Agent aliases:

private static readonly string[] MainHandleRoots = [
    "雾港", "夜航", "零帧", "星渊", "霓虹", "断云", ...
];
private static readonly string[] OrthogonalHandleSuffixes = [
    "旅人", "猎手", "术师", "行者", "星使", ...
];
// Combination examples: 雾港旅人, 夜航猎手, 零帧术师...

Soul snapshot assembly follows a fixed template format, combining main character core, signature features, expression rule core, and output constraints:

private static string BuildSoulSnapshot(main, orthogonal) => string.Join('\n', [
    $"你的人设内核来自「{main.Name}」：{main.Core}",
    $"保持以下标志性语言特征：{main.Signature}",
    $"你的表达规则来自「{orthogonal.Name}」：{orthogonal.Core}",
    $"必须遵循这些输出约束：{orthogonal.Signature}"
]);

This template assembly is boring work, but without these boring tasks, where would interesting products come from?

Platform Migration Strategy

After splitting Soul from the main system to an independent platform, we faced an important challenge: how to handle existing user data. This is a common problem—splitting is easy, migration is hard. We took three safeguards:

Backward Compatibility Guarantee. Saved Hero SOUL snapshots remain visible; historical snapshots can still be previewed even if they lose their Marketplace source ID. This means users' previous configurations won't be lost—only the display location has changed. After all, no one wants their hard-earned configurations to suddenly disappear.

Main System API Deprecation. The in-site Marketplace API returns a 410 Gone status code with migration guidance, directing users to visit soul.hagicode.com.

Hero SOUL Form Modification. A migration notice section is added to the Hero Soul editing area, explicitly informing users that the Soul platform is now independent and providing a one-click jump button:

// HeroSoulForm.tsx
<div className="rounded-2xl border border-orange-200/70 bg-orange-50/80 p-4">
  <div>{t('hero.soul.migrationTitle')}</div>
  <p>{t('hero.soul.migrationDescription')}</p>
  <Button onClick={onOpenSoulPlatform}>
    {t('hero.soul.openSoulPlatformAction')}
  </Button>
</div>

Practical Takeaways

Looking back at the entire development process of the Soul platform, there are several practical experiences worth sharing. These are just some insights from someone who's been through it—not grand principles, just pits fallen into.

Local-first runtime assumptions. When designing features that depend on remote data, always assume the network might be unavailable. Local snapshots as baseline, remote as enhancement—this approach allows the product to provide basic usability under any network conditions. After all, these days, network can cut out anytime, who can say for sure.

Clear division of state boundaries. Interface state and business state should be clearly distinguished to avoid UI interaction polluting the core data model. Drawer toggle is pure UI state and doesn't need to be mixed with draft persistence.

Internationalization design should be done early. If your product has internationalization needs, it's best to consider it during the data model design phase. The localized field, although increasing data structure complexity, greatly reduces the cost of maintaining multilingual content later.

Material synchronization workflow should be automated. The Soul platform's local materials come from the main system documentation. When upstream documentation updates, there needs to be a mechanism to sync to the frontend snapshot. We designed the npm run materials:sync script to automate this process, ensuring materials always stay consistent with upstream.

Future Outlook

Based on the current architecture design, the Soul platform could consider the following development directions. These are just some preliminary ideas, not necessarily correct—just throwing out bricks to attract jade.

Community sharing ecosystem. Support user upload and sharing of custom Souls, add rating, commenting, and recommendation mechanisms, allowing excellent Soul configurations to be discovered and used by more people. After all, shared joy is double joy.

Multimodal expansion. Beyond text style, could also consider supporting voice style configuration, emoji usage preferences, code style and formatting rules, and other dimensions. This sounds nice in theory, but in practice might be...

Intelligent assistance. Automatic Soul recommendations based on usage scenarios, style transfer and fusion, even A/B testing different Souls' actual effects. Why care if it's sunny or cloudy for beauty? Just try it and see.

Cross-platform synchronization. Support importing personality configurations from other AI platforms, provide standardized Soul export formats, integrate with mainstream Agent frameworks.

Summary

This article shared the complete evolution process of the HagiCode Soul platform from concept to independent platform. We explored why the Soul mechanism is needed (solving Agent personality consistency issues), analyzed the three development stages of the technical architecture (embedded configuration, in-site Marketplace, independent platform), deeply explained core data models, state management, preview compilation, and internationalization design, and shared practical experience with platform migration.

The essence of Soul is a personality configuration layer independent of business logic. It makes AI Agent language styles definable, reusable, and shareable. From a technical perspective, this design isn't complex, but the problem it solves is real and widely needed.

If you're also developing an AI Agent product, consider whether your personality configuration solution is flexible enough. The Soul platform practice might provide some inspiration.

This feeling could become a memory, but at that time I was already lost. Perhaps one day, you'll encounter similar problems, and when that time comes, if this article can help a little, that's enough.

References

HagiCode Official Site: hagicode.com
Soul Platform: soul.hagicode.com
HagiCode GitHub: github.com/HagiCode-org/site
HagiCode Desktop: hagicode.com/desktop/
HagiCode Installation Docs: docs.hagicode.com/installation/docker-compose

If you find this article helpful, feel free to give the project a Star on GitHub. Public beta has begun, welcome to install and experience.

原文与版权说明

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

本文作者: newbe36524
原文链接: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-03-25-hagicode-soul-platform-technical-analysis%2F
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!