go-GenericAgent · Go 自治智能体

go-GenericAgent

English | 简体中文

go-GenericAgent 是 GenericAgent 的 Go 版本迁移实现。原项目是一个极简的自进化自治智能体框架；本仓库对其约 3K 行 Python 核心进行了 1:1 级别复刻。

状态：已完成与原项目生产等价的迁移。功能已全部覆盖。偏差项与已接受缺口见 MIGRATION_NOTES.md。

🤖 AI 驱动迁移（由 lang-migration-skill 提供工作流）

本仓库由 AI 智能体在 lang-migration-skill 的端到端工作流指导下，完成了从 Python 到 Go 的完整重写。该技能包可复用、开源，面向全项目语言迁移。

lang-migration-skill 通过结构化流程，让 AI 智能体可以在几乎零人工逐行翻译的前提下，执行 大规模、结构等价 的语言迁移：

• 结构等价优先：先完成模块、类、函数级映射，再落代码，避免架构漂移。
• 全资产覆盖：不仅迁移代码，还覆盖配置、模板、资源文件，不漏文件。
• YAML 状态持久化：支持跨会话检查点，任务中断后可无损续跑。
• 严格禁用 mock 验证：要求对齐原行为，禁止用占位实现掩盖问题。
• 人工门控决策：遇到歧义设计时显式上抛给开发者，不做静默拍板。

这件事为什么重要：将约 3K 行 Python 智能体基础设施（并发模型、LLM 会话、流式解析、浏览器自动化、多平台机器人适配）迁移为惯用 Go，人工通常需要数天到数周；借助 lang-migration-skill，AI 可在受控流程下完成生产可用级复刻，并通过行为测试验证。

如果你也需要做跨语言迁移，可直接复用该技能包到你的项目： suifei/lang-migration-skill。

快速开始

1. 构建

# Windows（PowerShell）
git clone https://github.com/suifei/go-GenericAgent.git
cd go-GenericAgent
go build -o go-GenericAgent.exe   ./cmd/go-GenericAgent
go build -o ga.exe         ./cmd/ga
go build -o hub.exe        ./cmd/hub
go build -o launch.exe     ./cmd/launch
go build -o desktoppet.exe ./cmd/desktoppet
go build -o skillsearch.exe ./cmd/skillsearch
go build -o ga_cli.exe     ./cmd/ga_cli

# Linux / macOS
git clone https://github.com/suifei/go-GenericAgent.git
cd go-GenericAgent
go build -o go-GenericAgent    ./cmd/go-GenericAgent
go build -o ga          ./cmd/ga
go build -o hub         ./cmd/hub
go build -o launch      ./cmd/launch
go build -o desktoppet  ./cmd/desktoppet
go build -o skillsearch ./cmd/skillsearch
go build -o ga_cli      ./cmd/ga_cli

或一次性构建全部组件 (Windows Powershell)：

bun .\scripts\release\build-dist.js

Windows 下需要 cgo，采用的mingw64，此配置和安装可以要AI自行完成

// ─── CGO / ONNX Runtime 检测 ──────────────────────────────────────────────────
// CGO 仅在本机 windows-amd64 原生编译时启用（交叉编译不支持 CGO）。
// onnxruntime 路径优先读取环境变量 ORT_LIB_LOCATION，否则尝试默认安装路径。
const ORT_BASE_DEFAULT = 'C:\\devtools\\onnxruntime\\onnxruntime-win-x64-1.21.0';
const MINGW_BIN        = 'C:\\msys64\\mingw64\\bin';

2. 配置 API Key

cp mykey_template.json mykey.json

编辑 mykey.json，填写 一个 LLM 会话配置。最简示例：

{
  "native_oai_config": {
    "name": "gpt",
    "apikey": "sk-YOUR_OPENAI_KEY",
    "apibase": "https://api.openai.com/v1",
    "model": "gpt-5.4"
  }
}

完整字段说明见 mykey_template.json。

3. 运行

./go-GenericAgent            # 交互式智能体（终端 Chat UI）
./go-GenericAgent tui        # 终端 TUI 界面
./go-GenericAgent web        # Web conductor 界面（HTTP）
./hub                        # 服务管理器

使用场景与启动顺序

唯一前置条件：mykey.json 与 go-GenericAgent 二进制在同一目录（或设 GA_CONFIG_DIR）。其余服务互相独立，按需启动，没有强依赖顺序。

场景 1：个人本地对话（最简单）

./go-GenericAgent chat

无需提前启动任何服务，直接交互。-i 可做单次任务：

./go-GenericAgent chat -i "帮我总结这段代码"

场景 2：Web 界面对话

# 方式 A：一键启动（自动选端口，自动打开浏览器）
./launch

# 方式 B：手动指定端口
./go-GenericAgent conductor --port 8900
# 浏览器访问 http://localhost:8900

场景 3：长期挂机 + 多平台机器人

先在 mykey.json 填好对应平台的 token，再用 hub 统一管理：

# 启动指定服务（逗号分隔）
./hub --start frontends/conductor,frontends/telegram,reflect/scheduler

# 或全部启动
./hub --all

hub 监控子进程、打印带前缀的日志，Ctrl-C 统一关闭所有子进程。

场景 4：嵌入 IDE / VS Code（ACP 协议）

由 IDE 插件自动拉起，无需手动启动：

./go-GenericAgent acp -n 0    # JSON-RPC 2.0 over stdio

场景 5：自治定时任务

./go-GenericAgent reflect -m scheduler      # 定时调度
./go-GenericAgent reflect -m autonomous     # 自主运行
./go-GenericAgent reflect -m goal_mode      # 目标模式
./go-GenericAgent reflect -m team_worker    # 团队协作模式

启动路径速查

配置（一次性）：./go-GenericAgent configure  →  生成 mykey.json
       │
       ├─ 命令行对话        →  ./go-GenericAgent chat
       ├─ Web 浏览器        →  ./launch  或  ./go-GenericAgent conductor
       ├─ 多服务挂机        →  ./hub --start / --all
       ├─ 机器人集成         →  ./hub --start frontends/tg  （需 mykey.json 含 token）
       ├─ 定时/自治         →  ./go-GenericAgent reflect -m scheduler|autonomous|goal_mode
       └─ IDE 集成          →  ./go-GenericAgent acp  （由插件拉起）

二进制程序

go-GenericAgent 子命令

go-GenericAgent              交互式智能体（默认）
go-GenericAgent tui          终端 UI（bubbletea）
go-GenericAgent web          Web conductor（SSE + HTML）
go-GenericAgent tg           Telegram bot
go-GenericAgent feishu       飞书（Lark）bot
go-GenericAgent discord      Discord bot
go-GenericAgent dingtalk     DingTalk bot
go-GenericAgent wecom        WeCom bot
go-GenericAgent qq           QQ bot
go-GenericAgent acp          ACP 桥接（Codeg 集成）
go-GenericAgent reflect      自治反思循环
go-GenericAgent configure    交互式密钥配置向导

ga 子命令

ga chat / ga web / ga tui / ga hub / ga configure / ga tg / ga feishu
ga discord / ga dingtalk / ga wecom / ga qq / ga acp / ga reflect
ga status   显示正在运行的 agent 进程
ga update   从 origin/main 拉取并更新
ga list     显示全部命令

会话类型

mykey.json 中的 key 决定使用哪一种 LLM 后端。key 名称会编码会话类型：

推荐：优先使用 native_claude_config 或 native_oai_config。文本协议会话仅用于兼容场景。

Mixin 故障转移

{
  "native_claude_config": { "name": "claude", "apikey": "...", "apibase": "...", "model": "..." },
  "native_oai_config":    { "name": "gpt",    "apikey": "...", "apibase": "...", "model": "..." },
  "mixin_config": {
    "llm_nos": ["claude", "gpt"],
    "max_retries": 10,
    "base_delay": 0.5
  }
}

聊天平台集成

在 mykey.json 中加入以下字段即可启用对应机器人前端：

{
  "tg_bot_token": "...",
  "tg_allowed_users": [123456789],

  "feishu_app_id": "cli_...",
  "feishu_app_secret": "...",

  "discord_token": "...",
  "discord_channel_id": 0,

  "dingtalk_client_id": "...",
  "dingtalk_client_secret": "...",

  "wecom_corp_id": "...",
  "wecom_agent_id": 0,
  "wecom_secret": "...",

  "qq_appid": "...",
  "qq_secret": "..."
}

可选：Langfuse 可观测性

在 mykey.json 中加入以下配置，可自动追踪每次工具调用与 LLM 生成：

{
  "langfuse_config": {
    "public_key": "pk-lf-...",
    "secret_key": "sk-lf-...",
    "host": "https://cloud.langfuse.com"
  }
}

检测到配置后，插件会在启动时自动激活，无需修改代码。

运行时 REPL 命令

在交互式会话中，以 / 前缀输入命令：

/session.temperature=0.3
/session.reasoning_effort=high
/session.thinking_type=adaptive
/session.max_tokens=16384
/session.thinking_budget_tokens=32768
/help
/exit

Agent 核心架构与长任务设计

本章节回答三个问题：agent 的工作原理是什么？它如何在 ~32k token 的上下文窗口内完成几百轮迭代的长任务？任务状态和记忆如何在会话之间传递而不丢失？

整体运行模型

                    ┌─────────────────────────────────────────┐
 任务投递           │            GenericAgent                  │
 PutTask(query) ──▶│  taskQueue chan TaskRequest               │
                    │         │                                 │
                    │         ▼                                 │
                    │   Run() goroutine                         │
                    │   ┌────────────────────────────────────┐ │
                    │   │  agent_runner_loop(max_turns=70)   │ │
                    │   │                                    │ │
                    │   │  每轮：                            │ │
                    │   │  1. LLMClient.Chat(messages, tools)│ │
                    │   │  2. 解析 tool_calls                │ │
                    │   │  3. handler.Dispatch(tool, args)   │ │
                    │   │  4. 收集 tool_results              │ │
                    │   │  5. _get_anchor_prompt()           │ │◀── 核心
                    │   │  6. messages = [新的 user 消息]   │ │
                    │   └────────────────────────────────────┘ │
                    │         │                                 │
                    │         ▼ TaskResult{Done/Next}           │
                    └─────────────────────────────────────────┘
                              │
                    输出 channel ──▶ 调用方(REPL/Web/Bot/ACP)

关键设计：每轮循环结束时 messages 被重置为仅含一条新 user 消息（工具结果 + 重建上下文），而不是追加到历史中。完整的对话历史由 LLM 客户端（NativeClaudeSession / NativeOAISession）在 backend 内部维护〔FACT｜genericagent/agentmain.py:151〕。

上下文窗口管理：_get_anchor_prompt()

这是整个长任务能力的核心机制〔FACT｜genericagent/ga.py:535〕。每次工具调用返回后，下一轮的 user 消息不是空的，而是包含完整的重建上下文：

### [WORKING MEMORY]
 
  [USER]: 任务描述（永远保留）
  [Agent]（47 turns）          ← 早期 agent 动作被折叠为计数
  [USER]: 中途用户指令（保留）
  [Agent]（12 turns）
 
 
  [USER]: 最近用户输入         ← 最近 30 条 history_info 完整保留
  [Agent] 读取了配置文件
  [Agent] 执行了构建脚本，exit 0
  ...
 
Current turn: 58

 
  目标：完成 X 功能
  当前状态：Y 模块已完成，Z 模块待处理
  关键约束：需要先执行 A 再执行 B
 

_fold_earlier() 的折叠逻辑〔FACT｜genericagent/ga.py:582〕：

• [USER] 行：永远完整保留（用户意图不可丢弃）
• [Agent] 行：早期连续 agent 动作折叠为 [Agent]（N turns），仅保留最后一条摘要

这使得即使任务已执行数百轮，注入到每轮提示的历史摘要也控制在可预测的 token 范围内。

三层记忆架构

 L0  memory_management_sop.md  ─── 记忆操作规程（agent 读取后按 SOP 更新记忆）
  │
  ├── L1  系统提示 + working checkpoint（会话内）
  │       sys_prompt.txt  +  key_info（每轮注入）
  │       生命周期：单次 agent_runner_loop 内
  │
  ├── L2  global_mem.txt / global_mem_insight.txt（跨会话持久）
  │       路径：memory/global_mem.txt
  │       注入时机：每次 get_system_prompt() + 每隔 10 轮重注入
  │       内容：环境事实、用户偏好、验证过的路径/凭证
  │
  └── L3  memory/*.md SOP 文件（长期过程知识）
          按需 file_read 读取
          内容：复杂任务 SOP、关键坑点、前置条件

L2 注入频率〔FACT｜genericagent/ga.py:565〕：

Working Checkpoint：跨会话状态传递

这是"不丢失超大轮次任务核心状态"的关键机制。

会话内：update_working_checkpoint 工具

当 agent 判断当前任务状态需要记录时，主动调用此工具〔FACT｜genericagent/ga.py:435〕：

{
  "tool": "update_working_checkpoint",
  "args": {
    "key_info": "目标：重构 X 模块\n当前：已完成 A/B，下步 C\n约束：必须保持 API 兼容",
    "related_sop": "memory/refactor_sop.md"
  }
}

存储在 handler.working['key_info']，之后每轮都通过 _get_anchor_prompt() 自动注入。

跨任务/会话：key_info 继承

当用户发起新任务时，GenericAgent.run() 创建新的 handler，但检查前一个 handler 是否有 key_info，如有则继承〔FACT｜genericagent/agentmain.py:143〕：

// Go 等价逻辑（internal/agent/agent.go）
if prev.Working["key_info"] != "" {
    newHandler.Working["key_info"] = cleanedKeyInfo
    newHandler.Working["passed_sessions"] = prevPassedSessions + 1
    // 并附加提示："此为 N 个对话前设置的 key_info，若已在新任务，先更新或清除"
}

passed_sessions 计数器告知 agent 这段记忆已经"老化"了多少轮，让 agent 自行判断是否还有效。

长期固化：start_long_term_update 工具

任务完成后，若 agent 判断有值得保留的信息，调用此工具触发记忆结算流程：

start_long_term_update
  → 读取 memory/memory_management_sop.md（L0）
  → 按 SOP 判断信息类型：
      环境事实（路径/配置/凭证）→ file_patch 更新 global_mem.txt (L2)
      复杂任务经验（坑点/步骤）  → 写入/更新 memory/xxx_sop.md (L3)
  → 禁止写入：临时变量、推理过程、未验证信息、通用常识

Token 压力调控机制

agent_runner_loop 内置多个压力调控点，防止 agent 陷入无效循环〔FACT｜genericagent/ga.py:558〕：

每 7 轮   → next_prompt 注入警告："禁止无效重试，若无进展切换策略"
每 10 轮  → client.last_tools = ''（重置工具描述缓存，防退化）
           → 重注入全局记忆（确保 L2 始终可见）
每 65 轮  → 强制 next_prompt："必须 ask_user 汇报进度，不允许继续重试"
Plan模式  → 每 5 轮 file_read(plan.md)，确认当前步骤
           → 90 轮上限：强制 ask_user

工具描述缓存重置的原因：LLM 在长对话后对早期注入的工具定义理解会退化（上下文干扰），每 10 轮清空缓存，强制 LLM 重新关注工具 schema。

单次 agent_runner_loop 的完整流程

flowchart TD
    A[用户任务 PutTask]