试开发团队那就是deepseek,hermes,claude,gpt一众大佬了。个人精力有限上线bug用户体验问题肯定少不了望多担待或者一起修复。临近上线还是bug不断让它自己来修。该项目源码就不一一展示了特征如下鉴于golang语言的简介实现起来非常简单结构也非常明了一看就知道实现了哪些功能。上手非常简单有完整的使用文档以及命令提示。以下纯属项目介绍# agentgo 运行时架构深度解析一个 Go AI 编程助手的核心引擎设计 本文从代码层面剖析 agentgo 的运行时机制——Tool-Calling 循环、权限沙箱、护栏防循环、Git 检查点、记忆梦境整理、子代理架构等核心子系统。 --- ## 0. 先看全貌25 个内部包最小依赖 agentgo 的 internal/ 目录下挂着 25 个包但 go.mod 只有两个外部依赖 module github.com/agentgo go 1.24.0 require golang.org/x/term v0.29.0 require golang.org/x/sys v0.30.0 term 用于终端原始模式REPL 输入sys 是 term 的传递依赖。没有 ORM、没有 Web 框架、没有 JSON schema 库——**一切从零手写**。 这个极简依赖策略带来了一个关键收益**安全审计面积极小**。你可以在一小时内 review 完所有第三方代码。 --- ## 1. 核心引擎循环Engine.RunMessageWithStream 一切从 engine.go 的 RunMessageWithStream 开始。这是整个运行时的心脏约 200 行实现了一个完整的 Agentic Loop go for iter : 0; iter MaxIterations; iter { // 1. 检查 context 取消CtrlC 中断 if ctx.Err() ! nil { return , ctx.Err() } // 2. 构建请求系统提示词 历史消息 工具定义 req : api.ChatRequest{ Model: e.config.Model, Messages: reqMessages, SystemBase: sp, Tools: toolDefs, MaxTokens: 64000, } // 3. 调用 LLM支持流式 非流式两种路径 resp, err e.provider.ChatStream(ctx, req, onDelta) // 或 Chat() // 4. 更新费用追踪 e.costTracker.AddDetailed(e.config.Model, resp.InputTokens, resp.OutputTokens, ...) // 5. 处理截断响应max_tokens stop reason → 注入续写提示 if resp.StopReason max_tokens len(resp.ToolCalls) 0 { e.messages append(e.messages, api.Message{Role: user, Content: [system: previous response was truncated...]}) continue } // 6. 无工具调用 → 对话结束返回 if len(resp.ToolCalls) 0 { e.runTurnEndPipeline() // 触发后台任务 return resp.Content, nil } // 7. 执行工具调用支持并行 // ... // 8. 护栏检查 熔断器 // ... // 9. 上下文压缩检查 if e.totalTokens CompactTokenThreshold { e.Compact(ctx) } } ### 设计要点 **a) MaxIterations 200 上限保护** 每一轮对话最多执行 200 次 LLM 调用。超过上限直接报错退出防止无限循环烧钱。 **b) 截断续写机制** LLM 可能在生成到一半时达到 max_tokens 上限此时如果只是文本截断没有完整的 tool_call引擎会自动注入一条 system 消息让模型继续 go e.messages append(e.messages, api.Message{ Role: user, Content: [system: your previous response was truncated due to length. Please continue, writing one file at a time.], }) **c) ctx.Err() 快速退出** 每次迭代开始时第一件事就是检查 context——如果用户按了 CtrlC立即退出而非继续消耗 API 调用。 **d) CompactTokenThreshold 64000** 当累计 token 超过 64000 且已执行 5 次迭代时自动触发上下文压缩。 --- ## 2. 权限系统三层决策链 agentgo 的权限模型不是简单的「允许/拒绝」二元开关而是一条**三层决策链** go // 第一层工具自身声明权限意向 toolDecision : t.CheckPermissions(tc.Input, tctx) // 第二层权限管理器综合判断 decision, reason : e.perm.Check(tc.Name, tc.Input, mapToolDecision(toolDecision.Decision)) // 第三层用户交互确认 if decision permission.DAsk { approved : e.PermissionPrompt(tc.Name, tc.Input, reason) } ### 权限管理器核心逻辑 (permission/permission.go): go func (m *Manager) Check(toolName string, toolInput map[string]any, defaultDecision Decision) (Decision, string) { // 1. Deny 规则优先黑名单中的操作直接拒绝 for _, r : range m.deny { if matchRule(r, toolName, toolInput) { return DDeny, denied by policy rule } } // 2. Bypass 模式完全绕过 if m.mode Bypass m.bypassAvailable { return DBypass, bypass mode } // 3. Allow 规则白名单放行 for _, r : range m.allow { ... return DAllow } // 4. Ask 规则需要确认 for _, r : range m.ask { ... return DAsk } // 5. 模式默认行为 switch m.mode { case Auto: // 安全工具自动放行危险工具仍需确认 case Plan: // 只读工具放行写操作直接拒绝 default: // default 模式尊重工具自身声明 } } 四种模式的行为矩阵 | 模式 | 只读工具 (read/grep/glob) | 写文件 (write/edit) | 执行命令 (bash) | 危险命令 (rm -rf) | | --------- | ------------------------- | ------------------- | --------------- | ----------------- | | default | ✅ 自动 | ⚠️ 询问 | ⚠️ 询问 | ❌ 阻断 | | plan | ✅ 自动 | ❌ 拒绝 | ❌ 拒绝 | ❌ 阻断 | | auto | ✅ 自动 | ✅ 自动 | ⚠️ 询问 | ❌ 阻断 | | bypass | ✅ 自动 | ✅ 自动 | ✅ 自动 | ✅ 自动 | 其中「危险命令」由 classifier.Classify(cmd) 判定permission/classifier.go独立于模式设置——**任何模式都阻止 rm -rf /、format c: 这类操作**。 --- ## 3. 护栏系统防死循环的三路检测器 guardrail/guardrail.go 实现了一个轻量级的工具调用异常检测器在每次工具执行前进行拦截 go type Tracker struct { exactFailures map[signature]int // 相同工具参数连续失败次数 sameToolFails map[string]int // 同一工具名连续失败次数 idempotentSeen map[signature]string // 只读工具上次返回结果哈希 idempotentCount map[signature]int // 相同结果连续返回次数 } ### 三路检测逻辑 1. **精确失败检测**同一工具 同一参数连续失败 ≥ 5 次 → **Block**请换一种方法 2. **工具级失败检测**同一工具连续失败 ≥ 8 次 → **Block**尝试其他工具 3. **只读无进展检测**read/grep/glob/webfetch 返回相同结果 ≥ 5 次 → **Block**无需重复调用 签名生成使用SHA256取前8位 go func makeSignature(name string, args map[string]any) signature { data, _ : json.Marshal(args) h : sha256.Sum256(data) return signature{Name: name, ArgsHash: hex.EncodeToString(h[:8])} } 此外引擎层还有一个**熔断器**Circuit Breaker go if allFailed len(results) 0 { e.consecutiveErrors if e.consecutiveErrors 3 { // 注入 system 消息引导模型换方案 e.messages append(e.messages, api.Message{ Role: user, Content: [system: The last 3 tool calls all failed. Please try a different approach...], }) } } --- ## 4. Git 检查点用 Bare Repo 实现无侵入快照 checkpoint/checkpoint.go 是一个精巧的设计——它在 ~/.agentgo/checkpoints/store 下初始化一个 **bare Git 仓库**用一个 **临时 index 文件** 来做快照完全不污染工作目录的 .git go env : []string{ GIT_DIR m.storeDir, // 独立的 bare repo GIT_WORK_TREE m.workDir, // 指向实际工作目录 GIT_INDEX_FILE indexFile, // 临时索引不影响真实 git 状态 } 每个工作目录通过 SHA256 哈希映射到独立的 ref go h : sha256.Sum256([]byte(workDir)) refName : refs/agentgo/ hex.EncodeToString(h[:8]) 自动排除大文件和构建产物 go var excludePatterns []string{ node_modules, .git, .venv, __pycache__, *.exe, *.dll, *.so, *.dylib, target/, dist/, build/, .next/, } 在引擎中写文件和编辑文件之前自动创建检查点 go if e.checkpointMgr ! nil (tc.Name write || tc.Name edit || tc.Name bash) { e.checkpointMgr.Create(tc.Name : shortPath(tc.Input)) } 用户可以用 /undo 回退用 /checkpoints 查看历史。 --- ## 5. 多供应商抽象一个 Interface两种实现 api/provider.go 定义了一个统一的 Provider 接口 go type Provider interface { Name() string DisplayName() string Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error) ChatStream(ctx context.Context, req ChatRequest, handler StreamHandler) (*ChatResponse, error) Validate() error } 实际上只有两个具体实现 - **anthropicProvider** — 调用 Anthropic Messages API - **openAICompatProvider** — 覆盖所有 OpenAI-compatible APIDeepSeek、GLM、Kimi、Qwen、Groq 等 15 个供应商 DetectProvider 根据模型名自动推断 go func DetectProvider(model string, cfg ProviderConfig) Provider { if cfg.Name ! { return NewProvider(cfg) } // 用户指定 if containsAny(model, deepseek) { ... } // 模型名包含 deepseek if containsAny(model, gpt-, o1-, o3-, o4-) { ... } // OpenAI 系列 return newAnthropicProvider(cfg) // 默认走 Anthropic } ### 密钥池多 Key 轮转 自动冷却 api/keypool.go 实现了一个带健康状态的 API Key 池 go type PoolKey struct { Key string Status KeyStatus // KeyOK | KeyExhausted | KeyDead CoolUntil time.Time // 冷却到期时间 UseCount int LastError string } - Round-robin 轮转取 key - 收到 429 (Rate Limit) → 自动标记 KeyExhausted 设定冷却时间 - 冷却期满自动复活 - 认证失败 (401/403) → 标记 KeyDead不再使用 - /ratelimit 命令可查看当前密钥池健康状态 --- ## 6. 记忆系统磁盘文件 XML 注入 梦境整理 ### 6.1 存储层 (memory/store.go) 记忆以**独立文件**存储在 ~/.agentgo/memory/ 目录同时自动加载工作目录下的 CLAUDE.md go func (s *Store) All() []Entry { // 1. 读取 ~/.agentgo/memory/ 下所有文件 // 2. 读取项目根目录的 CLAUDE.md // 3. 读取 .claude/CLAUDE.md如有 } 容量限制 - 单个条目 ≤ 25KB - 总容量 ≤ 100KB - 自动 truncation ### 6.2 注入到 System Prompt 记忆内容以 XML 格式注入到系统提示词中放在 user_memories 标签内 xml user_memories memory nameenvironment.md/name content.../content /memory /user_memories 带 30 秒 TTL 的缓存 go if s.cachedAll ! nil time.Since(s.cacheTime) s.cacheTTL { return s.cachedAll // 避免每次构建 system prompt 都读磁盘 } ### 6.3 Dream 梦境整理 (dream/dream.go) 这是一个**后台运行的独立 LLM 代理**专门负责记忆文件的增删改和整理。 触发门控三重检查 1. 时间门控距上次整理 ≥ MinHours 小时默认 24h 2. 扫描节流两次扫描间隔 ≥ 10 分钟避免高频检查 3. 会话门控新会话数 ≥ MinSessions默认 3 个 触发后独立运行一个 Tool-Calling 循环最多 30 次迭代只授予受限工具 允许bash(ls/find/grep/cat/stat/wc/head/tail), read, write, edit, glob, grep 禁止任何写命令rm/mv/cp、网络请求 且 write/edit 被限制只能操作 ~/.agentgo/memory/ 目录 go if !isInsideMemoryDir(absPath, r.memoryRoot) { return Error: dream mode can only write to memory directory } 加锁机制防止多个 agentgo 进程同时运行 dream go priorMtime, acquired, err : TryAcquireConsolidationLock() if !acquired { return } defer RollbackConsolidationLock(task.PriorMtime) // 失败回滚 --- ## 7. 并行工具执行区分并发安全与串行 当 LLM 返回多个 tool_call 时引擎自动并行执行并发安全的工具 go if len(resp.ToolCalls) 1 { var wg sync.WaitGroup for i, tc : range resp.ToolCalls { t, _ : e.registry.Find(tc.Name) safe : t ! nil t.Def().IsConcurrencySafe // write/edit 到不同文件也可以并行 if !safe (tc.Name write || tc.Name edit) { if fp, ok : tc.Input[filePath].(string); ok fp ! { if !serialFilePaths[fp] { serialFilePaths[fp] true safe true } } } if safe { wg.Add(1) go func(idx int, tcall api.ToolCall) { defer wg.Done() defer func() { if r : recover(); r ! nil { results[idx] toolResult{...Error: tool panicked: ...} } }() results[idx] toolResult{...e.executeTool(ctx, tcall)} }(i, tc) } else { results[i] toolResult{...e.executeTool(ctx, tc)} // 串行 } } wg.Wait() } 关键设计 - 每个并行 goroutine 包裹 recover() 防止 panic 导致进程崩溃 - write/edit 到不同文件路径视为安全的并发操作 - bash 命令默认串行有副作用 --- ## 8. 上下文窗口管理三级压缩策略 ### 8.1 工具输出自适应截断 不同工具的输出采用不同的 token 上限 go switch tc.Name { case read, grep: maxTokens 6000 // 源代码上下文更有价值 case bash: maxTokens 3000 // 构建/测试输出通常重复 case webfetch: maxTokens 3000 default: maxTokens 4000 } ### 8.2 旧工具结果瘦身 trimOldToolResults 将早期的 verbose 工具输出替换为一行摘要 go m.Content fmt.Sprintf([%s] %s (%d chars原始输出已压缩), m.Name, firstLine, len(m.Content)) ### 8.3 全量压缩 (Compact) 当 token 超过 64000 时调用 LLM 对早期对话进行摘要保留最近的消息段 go // 结构: [第一条用户消息] [LLM 摘要] [最近消息] newMsgs : make([]api.Message, 0, 2keepTail) newMsgs append(newMsgs, e.messages[0]) // 第一个 user 消息 newMsgs append(newMsgs, api.Message{ Role: user, Content: [Context Summary]\n compactResp.Content, }) newMsgs append(newMsgs, e.messages[splitIdx:]...) // 保留尾部 --- ## 9. Turn-End Pipeline后台任务流水线 每轮对话结束后runTurnEndPipeline 启动五个并行的后台 goroutine go func (e *Engine) runTurnEndPipeline() { // 1. 会话笔记落盘无 API 开销 go func() { e.sessionNotes.Flush() }() // 2. Dream 梦境整理检查条件触发 go func() { e.dreamRunner.ExecuteAutoDream(context.Background()) }() // 3. 后台回顾学习 go func() { e.backgroundReview() }() if !e.autoExtract { return } // 4. 记忆提取调用 LLM 从对话中提取关键信息 go func() { e.extractRunner.Extract(context.Background(), msgs) }() // 5. 后续建议生成带 5 秒超时 go func() { ctx, cancel : context.WithTimeout(context.Background(), 5*time.Second) defer cancel() sug : e.suggestRunner.Generate(ctx, msgs) e.lastSuggestions sug }() } 所有 goroutine 都包裹了 recover()保证一个后台 panic 不会炸掉主进程。 --- ## 10. 子代理系统递归的引擎实例化 agent/runner.go 实现了子代理调度器 go func (r *Runner) Run(ctx context.Context, name string, task string) (*api.AgentRunResult, error) { def : r.defs[name] agentTools : r.filterTools(def.Tools) // 创建独立的 Engine 实例 eng, _ : engine.New(engine.Config{ Model: def.Model, PermissionMode: auto, // 子代理默认 auto 模式 Tools: agentTools, Provider: r.config.Provider, }) eng.SetSystemOverride(strings.Join([]string{ fmt.Sprintf([Sub-agent: %s], def.Name), def.Description, def.Prompt, }, \n)) output, err : eng.Run(ctx, task) return api.AgentRunResult{Output: output, Cost: ..., Success: err nil} } 预定义了五种子代理类型 - general — 通用任务 - explore — 代码探索 - plan — 方案设计 - review — 代码审查 - test — 测试编写 每个子代理是**全新的 Engine 实例**有自己的消息历史、费用追踪和工具集。这相当于在主会话中 fork 出一个隔离的沙箱执行环境。 --- ## 11. 费用追踪精算到 Token 级别 cost/tracker.go 硬编码了主流模型的实时价格 go var Prices map[string]Price{ claude-sonnet-4-20250514: {Input: 3.0, Output: 15.0}, // $3/$15 per 1M tokens deepseek-v4-pro: {Input: 0.435, Output: 0.87}, // $0.435/$0.87 gpt-4o: {Input: 2.5, Output: 10.0}, // ... } 支持 Anthropic 的 Prompt Cache 分层计费 go t.TotalCost (float64(cacheMiss)/1e6)*p.Input (float64(cacheHit)/1e6)*p.InputCacheHit (float64(output)/1e6)*p.Output 每次 API 调用后更新OverBudget() 检查在下一轮迭代前生效 go if e.costTracker.OverBudget() { return , fmt.Errorf(budget exceeded: %s, e.costTracker.Summary()) } 持久化的 CostHistory 提供 24 小时、7 天、累计统计。 --- ## 结语 agentgo 的核心引擎设计体现了一种 **「深度防御 激进优化」** 的哲学 - **深度防御**Classifier → Permission Manager → Guardrail → Circuit Breaker → MaxIterations五层保护 - **激进优化**并行工具执行、自适应截断、多级压缩、Prompt 缓存 - **最小依赖**两个外部包一切从零手写 它证明了一件事用 8,000 行 Go 代码 两个第三方依赖完全可以构建出一个功能不输于任何竞品的 AI 编程助手运行时。