🐙 octo-agent 架构地图

Go 1.22+ 单二进制 · 五层单向依赖 · 协议无关 Agent 循环

入口层
装配层
Agent 核心
Provider
工具集
服务层
IM 桥接
跨切关注
📥 入口层 cmd/octo/
CLI / TUI / Headless▶
Bubble Tea 交互界面 + claude -p 风格单次执行
关键文件：main.go → chat.go / tuirepl.go / repl.go / turncore.go
职责：解析命令行 → 装配 session → 分派到 runTurn()
octo serve▶
启动内嵌 Web 服务 + WebSocket 网关
关键文件：cmd/octo/serve.go
职责：拉起 server 实例，监听 8088 端口，承载 Web + REST + WS
↓ 装配 NewSessionToolEnv ↓
🔧 装配层 internal/app/
Sender 适配▶
Provider → agent.Sender 统一接口
关键文件：sender.go — NewSender()
解耦点：agent 不知道 HTTP、JSON 字段、SSE 细节
工具环境装配▶
并发安全的工具运行时环境
关键文件：toolenv.go — NewSessionToolEnv()
装配内容：权限闸门、SubAgentManager、GoalStore、browser、memory
Permission Gate▶
每 turn 重建规则引擎
行为：prepareToolTurn 中调用，即时生效 + 失败回退 lastGoodRules
MCP 连接▶
启动时连接所有配置中的 MCP server
关键文件：mcp.go — ConnectAll()
装配时机：session 启动时一次性建立
↓ Sender 协议无关抽象 ↓
🧠 Agent 核心 internal/agent/ — 叶子包，不导入任何上层
runLoop / RunStream▶
send → tool dispatch → reply 的 agentic 循环
关键文件：agent.go — Turn() / Run() / RunStream()
核心：持 senderMu，单 turn 全局互斥
History + Session▶
消息历史 + JSONL 持久化
关键文件：history.go / session.go
存储：~/.octo/sessions/<id>.jsonl
Overflow / Compaction▶
上下文溢出处理（分层状态机）
关键文件：overflow.go / compaction.go / microcompact.go
策略：microcompact → compact → overflow 降级
EventHandler▶
抽象事件流（text_delta / tool_start / turn_done）
关键文件：event.go — EventKind / EventHandler
下游适配：TUI card ← ViewSink | WS broadcast | IM message
↕ agent 不导入这些包 — 通过接口反转 ↕
🔌 LLM 后端适配 internal/provider/
Anthropic (Messages API)▶
claude-3-5-sonnet 等模型
关键文件：anthropic/client.go / stream.go
Wire 归一化：stop_reason → "tool_use"，cache_read_input_tokens 分桶
OpenAI (Chat Completions)▶
GPT-4o / DeepSeek 等兼容端点
关键文件：openai/client.go / stream.go
特殊处理：tool_calls 流式片段拼接、cached_tokens 从 prompt_tokens 扣减
DashScope / DeepSeek▶
百炼 / DeepSeek 兼容端点
注意：Bailian 需要 stream_options.include_usage=true，DeepSeek 自带 usage
Retry Layer▶
请求级恢复 + 流式 idle 超时
关键文件：retry/retry.go
退避：exponential backoff + jitter
🛠️ 内置工具集 internal/tools/ — 30+ ToolExecutor
终端 + 沙盒▶
命令执行典范实现
文件：terminal.go / sandbox.go
文件读写▶
读写 + grep + glob
文件：read_file.go / write_file.go 等
Web + Browser▶
抓取 + CDP 浏览器自动化
文件：web_fetch.go / browser.go
Skill + MCP▶
技能按需加载 + MCP server 中转
文件：skill.go / mcp*.go
Sub-agent▶
派生子 agent 处理子任务
文件：subagent_manager/
Workflow / Memory▶
mruby 工作流 + 语义记忆 recall
文件：workflow.go / memory.go
↕ HTTP · WebSocket · IM 调用 ↕
🌐 服务层 internal/server/
REST + WebSocket▶
80+ 路由 + /ws 双向通信
关键文件：server.go / ws_handlers.go / ws_hub.go
职责：session binding、turn 锁、wake-up 调度、优雅 shutdown
prepareToolTurn▶
装配 turn 环境（server 路径入口）
关键文件：handlers_prepare_toolturn.go
流程：app.NewSessionToolEnv → 注入权限/agent/browser/memory
📡 IM 桥接 internal/channel/ — 6 大平台
Telegram / Discord / Feishu▶
按钮支持（callback_query / interactive card）
接口：SupportsButtons() + SendButtons()
数据映射：按钮 → text，复用 isAffirmative/isAlways
微信 / 企微 / 钉钉▶
纯文本 reply 契约
限制：无按钮 SDK，走纯文本交互
chunking：长消息自动分片
⚙️ 跨切关注点 internal/*
Permission▶
deny > ask > allow 三级决策
文件：permission.go + defaults.yml
Skills▶
L1 name 注入 / L2 body 按需加载
文件：skills.go + defaults.go (go:embed)
Workflow▶
mruby (wazero) Ruby DSL
文件：runtime.go / prelude.rb / journal.go
Scheduler▶
cron 定时任务调度
路径：~/.octo/tasks/*.json
Hooks▶
pre/post-turn + TOFU 信任
文件：internal/hooks/
Memory Backend▶
hindsight / mem0 / MemTensor
文件：memorybackend/backend.go
🎯 关键解耦设计