

## 导语

市面上多数 AI 写作工具是对大模型 API 的薄封装——套一层 prompt 模板，加几个按钮。Goink 走了一条更重的路：自研 ReAct Agent 引擎、自建六维结构化记忆、自写 ONNX 本地语义搜索引擎。不是轮子好造，是因为给长篇创作做基础设施，现成的轮子不够用。

这篇文章讲的是架构层面的关键决策——为什么选 Wails 而不是 Electron、Agent 引擎怎么设计、Skill 系统和风格提取怎么和 Agent 联动。不含产品推销，纯技术复盘。

---

## 一、技术栈选型：为什么是 Wails

做桌面应用，第一反应是 Electron。但计算一下体积就放弃了——Electron 空壳就 100MB+。

Wails v2 用系统原生 WebView，安装包直接降到 60MB 以内。Go 编译为原生二进制，用户不需要安装任何运行时依赖。

实际的技术栈：

```
前端: React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui + Monaco Editor + G6
后端: Go 1.25 + GORM + SQLite + go-sqlite3 + ONNX Runtime
桥接: Wails v2.12
搜索: sqlite-vec + BGE 中文嵌入模型 (ONNX 本地推理)
版本管理: Git (os/exec 调用系统 Git 二进制)
```

选择 Wails 的一个隐性收益：Go 的并发模型让 Agent 引擎的流式处理天然简单。每个 LLM 请求一个 goroutine，channel 推事件到前端，不需要引入消息队列或 WebSocket。

---

## 二、Agent 引擎设计：ReAct 循环 + 失败降级

Agent 引擎是 Goink 的中枢。没有使用 LangChain 或任何第三方框架，直接在 Go 里写了一个 ReAct 循环。

### 核心流程

```
用户消息 → 注入 System Prompt（身份 + 小说状态 + Skill 目录）
       → LLM 流式推理
       → 解析响应：文本内容 or tool_calls？
            ├─ 纯文本 → 本轮结束，内容推给前端
            └─ tool_calls → 并行执行工具 → 结果追加到消息列表 → 继续循环
```

循环上限 50 轮。实际上正常写作通常 2-4 轮就结束，50 轮是安全兜底。

### 安全机制（踩坑产物）

Agent 在生产环境跑了一段时间后，暴露出几个需要兜底的场景：

**死循环检测**：LLM 有时会陷入"读文件 → 读同一个文件 → 再读一次"的循环。检测规则：最近 4 轮中工具调用种类 ≤ 2 且全是只读操作，触发则终止本轮。

**异常降级**：连续 3 次工具调用返回系统错误，自动禁用工具，后续作为纯文本对话继续。避免 LLM 在工具不可用时反复重试浪费 token。

**事件驱动的状态推送**：Agent 的每一步——开始思考、内容流式输出、工具调用开始/执行中/完成/失败、token 用量统计——都通过 Wails EventsEmit 实时推送到前端。用户看到的不是"AI 正在输入..."，而是能看到 AI 此刻在查什么资料、调什么工具。

### 子 Agent 设计

主 Agent 可以启动子 Agent 处理特定任务：

```
主 Agent → RunSubAgent("review")
         → 独立上下文 + 独立工具集
         → 审稿结果返回主 Agent
         → 结果追加到主对话，用户可见
```

子 Agent 和主 Agent 复用同一个 Run() 方法，差异仅在 RunOptions：

```go
type RunOptions struct {
    AgentType    AgentType  // main / review / memory
    ParentTurnID int        // 关联到主对话的 turn
    AllowedTools []string   // 子 Agent 的可用工具白名单
}
```

审稿 Agent 只有读权限，不能写文件。记忆 Agent 只能读和搜索，不能编辑。这种细粒度的权限控制靠的是工具注册时的分组标签，而不是在代码里硬编码白名单。

---

## 三、Skill 系统：把写作方法论做成可编程资产

通用 AI 聊天的一个根本问题是：prompt 是一次性的。你花两小时调出一个完美的写作 prompt，关掉窗口就没了。换一部小说要重新贴。

Goink 的解决思路是把写作方法论变成可持久化、可覆盖、可分发的 Markdown 文件。

### 一个 Skill 长什么样

```markdown
---
name: dialogue-subtext
description: 对白写作——潜台词、言外之意、语音差异化。写对话时 invoke。
category: 角色
mode: auto
version: 1
---

# 对白与潜台词

## 语音差异化四维度
- 词汇选择：不同教育背景用不同的词
- 句法节奏：短句 vs 长句，完整 vs 破碎
...
```

解析层用 Go 的标准 YAML 库处理 frontmatter，正文部分原样保留 Markdown，不做额外处理。这个设计的目的是零学习成本——会写 Markdown 就能写 Skill。

### 三种触发模式

不同的方法论适合不同的注入方式：

| 模式 | 行为 | 实现方式 |
|------|------|---------|
| auto | LLM 自主判断何时加载 | 注入到 `<available_skills>` XML 目录，LLM 通过 read 工具加载 |
| manual | 仅用户 `/skillname` 触发 | 不出现在目录中，触发时以 `<system-reminder>` 注入 |
| always | 会话开头自动注入 system 消息 | 直接拼接在 identity 之后、novel state 之前 |

`auto` 模式的关键设计是：只注入目录（name + description），不注入完整内容。LLM 需要时再通过已有的 `read` 工具加载。这样不会撑满上下文窗口，Skill 再多也不影响性能。

### 三层覆盖的优先级

```
novel 层（小说专属） > user 层（用户级） > builtin 层（内置只读）
```

实现上，`ListMeta(novelID)` 用 `seen map[string]bool` 按 name 去重。高优先级层先登记，低优先级层同名 Skill 被跳过。删除上层 Skill 后，下层自动恢复可见。

这种设计解决了一个实际问题：一个作者可能写不同类型的书。言情小说的对白风格和悬疑小说的对白风格完全不同。三层覆盖让作者可以在小说层为每部书定制专属的 Skill，同时在用户层保留跨作品复用的通用方法论。

---

## 四、风格提取：从文本到 Skill 的自动生成

Skill 系统可以手动编写，也可以自动生成。风格提取就是后者——从用户提供的文字样本中自动生成一份"风格仿写"Skill。

### 六个分析维度

```
句式特征 ─── 句长分布（短/中/长句比例）、句长标准差
用词习惯 ─── 成语频率、口语 vs 书面语、高频词汇
修辞手法 ─── 比喻类型、意象来源、修辞密度
节奏控制 ─── 标点密度（逗号/句号/感叹号/引号比例）
叙事视角 ─── 人称选择、叙述者和角色的距离
氛围语调 ─── 冷暖倾向、严肃 vs 轻松
```
![模式提取结果展示 .png](https://developer.qcloudimg.com/http-save/yehe-1179379/289632ec84ffcfa7fd56f1c9fd5b00c2.png)
### 为什么先用确定性统计再交给 LLM

纯靠 LLM 分析文本风格有一个问题——大模型容易给出"听起来很对但无法验证"的结论。Goink 的做法是多一层确定性统计：

```go
type Stats struct {
    TotalChars      int
    TotalWords      int
    SentenceCount   int
    ShortPct        float64  // 短句比例
    MediumPct       float64  // 中句比例
    LongPct         float64  // 长句比例
    AvgSentenceLen  float64
    SentenceLenStd  float64  // 句长标准差
    CommaDensity    float64  // 逗号密度
    PeriodDensity   float64  // 句号密度
    ExclamDensity   float64  // 感叹号密度
    QuoteDensity    float64  // 引号密度
    ParagraphCount  int
    AvgParaLen      float64
}
```

`ComputeStats(samples)` 先跑一遍文本统计，把硬数据拼进 LLM 的 prompt——"这个作者的短句占比 62%，句长标准差 8.3，逗号密度是句号密度的 3 倍"。LLM 在这个数据框架下做定性分析，大幅减少了幻觉。
![2aa08e28-39b0-4e0c-87cd-259b7d014da2.png](https://developer.qcloudimg.com/http-save/yehe-1179379/72466fe911d1555578a5e413232569b2.png)
### 输出产物

LLM 的输出被解析为一份标准的 Skill 文件（`category: 风格仿写`），包含：
- 各维度的具体分析
- 仿写要点清单
- 4-6 个 80-150 字的原文锚点片段

用户可以直接把它设为 auto 模式，之后每次写作 AI 都会自动参考这份风格手册。

---

## 五、开发中的几个经验

**1. ONNX 初始化的异步加载问题**

ONNX Runtime 加载 100MB 的 BGE 模型需要几秒钟，如果同步加载会阻塞 GUI。解决方案是 `sync.Once` + channel 广播：

```go
var (
    embedder   *OnnxEmbedder
    once       sync.Once
    readyCh    = make(chan struct{})
)

func InitEmbedder() {
    once.Do(func() {
        go func() {
            embedder = loadModel()
            close(readyCh)
        }()
    })
}

func GetEmbedder() *OnnxEmbedder {
    <-readyCh  // 阻塞到加载完成
    return embedder
}
```

GUI 先渲染，搜索功能在模型加载完成后自动激活。用户感知不到等待。

**2. 多 Provider 的接口适配**

7 个国产模型的 OpenAI 兼容 API 各有"毛刺"。千问的请求格式不完全一致、MiniMax 的请求体需要特殊处理、小米 MiMo 需要额外的请求头。解决方案是 Provider 级别的拦截器链：

```go
type Provider struct {
    ChatURL      string
    Models       []Model
    BuildRequest func(*http.Request, *ChatRequest) // 可选，修改请求体
    BuildHeaders func(*http.Request)               // 可选，修改请求头
}
```

每个特殊的 Provider 注册自己的钩子，主流程不改一行代码。

**3. Git Diff 审批的可靠性**

AI 修改文件不是直接写入，而是生成 search/replace 操作 → 后端执行 → 生成 Git Diff → 前端展示逐行对比 → 用户批准才 commit。这个流程的关键在于：如果替换失败（旧内容找不到），直接 return error 让 AI 重试，而不是部分写入。避免了半修改半损坏的状态。

---

Goink 还在持续迭代中。最新开发分支 v1.2.0 在做 Skill 市场（基于 GitHub Content API 的远程分发），欢迎感兴趣的开发者来交流。

GitHub: [github.com/sigpanic/goink](https://github.com/sigpanic/goink)，AGPL v3 开源。

市面上多数 AI 写作工具是对大模型 API 的薄封装——套一层 prompt 模板，加几个按钮。Goink 走了一条更重的路：自研 ReAct Agent 引擎、自建六维结构化记忆、自写 ONNX 本地语义搜索引擎。不是轮子好造，是因为给长篇创作做基础设施，现成的轮子不够用。

Goink Agent 架构实践：用 Go + React 构建桌面 AI 写作系统

一篇面向开发者的技术复盘：Goink 的 Agent 架构设计。
  核心内容：为什么选 Wails 不选 Electron（体积 <60MB）、ReAct 引擎怎么设计（循环 + 死循环检测 + 子 Agent 隔离）、Skill系统三层覆盖机制、风格提取为什么要先用确定性统计再交给 LLM、以及 ONNX 异步加载和多 Provider 适配的踩坑经验。纯技术向，不含产品推销。

架构设计

开发工具

人工智能

Goink自研ReActAgent引擎，采用Wails框架构建60MB轻量级桌面应用，实现六维结构化记忆与本地ONNX语义搜索。独创Skill系统将写作方法论转化为可编程Markdown资产，支持三层优先级覆盖。通过确定性统计+LLM分析实现文本风格自动提取，为长篇创作提供基础设施级支持。

消息队列

代码解释

TypeScript

WebSocket

SQLite

GitHub

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Goink Agent 架构实践：用 Go + React 构建桌面 AI 写作系统-腾讯云开发者社区-腾讯云

Goink Agent 架构实践：用 Go + React 构建桌面 AI 写作系统

Goink Agent 架构实践：用 Go + React 构建桌面 AI 写作系统

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐