Flyto Agent¶
领域无关的智能体引擎 - 核心库 + 平台服务 + 终端 UI.
文档地图¶
本仓库 27+ 个 markdown 文档分布在多目录. 下表按目标读者 + 入口形态分组, 内部开发者从此入口查全套. v0.3.3+ 起 always-on 在 hub.flytoex.net.
在线入口 (always-on)¶
| 入口 | URL | 内容 | 来源 |
|---|---|---|---|
| 业务 REST API | https://hub.flytoex.net/swagger/ | 8 endpoint + 12 schema 的 Swagger UI | L407 swag 注解 (v0.3.0+) |
| Go API godoc | https://godoc.flytoex.net/ | core/ 22 子包 + platform/common exported type 的 pkgsite (子域名因 pkgsite href 绝对路径) | v0.3.3+ |
| 整合文档站 | https://docs.flytoex.net/ | mkdocs-material 串 README/CONSUMERS/ADR/CONTRIBUTING/CHANGELOG/providers/教程一站 | v0.3.3+ |
| 仓库源浏览 | https://git.flytoex.net/yuanwei/Flyto-Agent | Gitea 直接看 markdown 源, 任何 .md 都通 | 永久 |
按目标读者分组的文档清单¶
Agent / Claude (我自己日常工作)¶
CLAUDE.md— 项目宪法 + 关键记忆 + 最后变更, 5 分钟懂当前状态core/TODO.md— 65 项待办 + 已完成 + 统计 (grep 实查口径)CHANGELOG.md— 版本变更, 8 节结构 (核心新增 / platform 层 / 设计原则 / 已知限制 / 发布事实)~/.claude/projects/<slug>/memory/MEMORY.md— auto memory 索引 (project-scoped)
消费层开发者 (C# logistics + Web 前端 + 集成方 Agent)¶
docs/CONSUMERS.md— 一站式入口 端口拓扑 / 必填 env / cmd/common 10 flag / OIDC auth 流程 / curl 例子- https://hub.flytoex.net/swagger/ — 业务 REST 8 endpoint 交互式 (L407)
platform/common/docs/grpc-api.md— 观测 gRPC HealthService + SafetyChainService 字段表 (protoc-gen-doc 产)
core 引擎贡献者 (Go 端开发)¶
core/CONTRIBUTING.md— 8 条宪法 (反向思维 / 升华 / 三层防御 / 精妙注释 / 原方案保留 / 零硬编码 / 测试即文档 / 零外部依赖)core/FLYTO.md— 产品宪法 (Flyto Agent 自己读的)- https://godoc.flytoex.net/git.flytoex.net/yuanwei/flyto-agent — pkgsite 看 22 子包 godoc HTML
core/docs/adr/— 架构决策记录 (ADR-0001 反事实否决 / ADR-0002 REST/gRPC bifurcation)core/docs/configuration.md/defensive-programming.md/agent_teams_competitive.md— 主题深度文档docs/evolve-strategy.md— evolve 进化算法战略 (43 KB, 接口矩阵 9/9)
Provider 贡献者¶
docs/providers/README.md+ 7 个 provider 详细文档 (anthropic / openai / minimax / gemini / ollama / lmstudio / openrouter)
部署 / SRE¶
deploy/README.md— HK-133 Phase 1 + Phase 2-2a 拓扑deploy/Caddyfile+deploy/docker-compose.yml— 边界路由 + service 配置.gitea/workflows/release.yml— push tag v* 触发 build-push + SSH HK-133 deploy
TUI 用户¶
tui/README.md— 终端 UI dogfood CLI (Flyto SDK 消费者样例)
战略 / 专利 / 业务设计 (PM 视角)¶
docs/evolve-strategy.md— evolve 进化战略docs/patent-research.md— 专利调研docs/architecture/data-driven-capabilities-migration.mddocs/architecture/flysafe-migration-note.mdPLATFORM_TODO.md— platform 层 TODO
第一次进 repo 推荐打开顺序 (5 分钟入门)¶
- 本 README.md (你正在看的) — 项目结构 + 文档地图
CLAUDE.md— 5 分钟懂当前进度 / 优先级 / 最后变更docs/CONSUMERS.md— 业务消费视角 (端口 / env / curl 例子)core/CONTRIBUTING.md— 8 条宪法 (Go 开发第一课)CHANGELOG.md"## v0.3.0 (2026-04-26)" 段 — 最近周期做了什么
项目结构¶
├── core/ Go 核心库（module: flyto-agent）
│ │
│ ├── pkg/ 公共包（消费者可 import）
│ │ │
│ │ │ ── 公共契约 ──
│ │ ├── flyto/ 核心接口定义
│ │ │ ├── provider.go ModelProvider 接口 / Request / ModelInfo
│ │ │ ├── events.go Event 接口 / TextDelta / ToolUse / Usage 等
│ │ │ ├── message.go Message / Block / Role / ProviderMetadata
│ │ │ ├── engine.go Engine 接口 / RunOption
│ │ │ ├── tool.go Tool 结构体
│ │ │ ├── observer.go EventObserver / MetricObserver / TraceObserver
│ │ │ └── errors.go ErrorCode / EngineError
│ │ │
│ │ │ ── 引擎运行时 ──
│ │ ├── engine/ 引擎核心
│ │ │ ├── engine.go New() / Run() / Close() / 主循环
│ │ │ ├── session.go 会话管理 / 权限通道
│ │ │ ├── session_manager.go 多会话管理 / 自动保存
│ │ │ ├── subagent.go 子 Agent（fork 模式）
│ │ │ ├── dream.go Dream 引擎（记忆巩固）
│ │ │ ├── team.go 多 Agent 协调（Leader/Worker）
│ │ │ ├── normalizer.go 消息规范化管道（9 步）
│ │ │ ├── token_budget.go Token 预算管理
│ │ │ ├── fallback.go 模型降级
│ │ │ ├── backend.go EngineBackend 接口
│ │ │ └── ... plan / skill / activity / file_history
│ │ │
│ │ ├── config/ 配置
│ │ │ ├── config.go Settings 文件加载 / 多级合并
│ │ │ └── models.go ModelConfig(=ModelInfo) / ModelRegistry / ModelRole
│ │ │
│ │ │
│ │ ├── pricing/ 定价（运行时获取模型单价）
│ │ │ ├── loader.go 加载 pricing.json / 注册到 ModelRegistry
│ │ │ └── registry.go PricingRegistry / GetPrice
│ │ ├── query/ 内部消息类型
│ │ │ └── query.go Message / Content / Usage / CacheTokens
│ │ │
│ │ ├── context/ Prompt + 压缩
│ │ │ ├── bundle.go PromptBundle 接口 / BundleRegistry
│ │ │ ├── compact.go 三层压缩降级 / 断路器
│ │ │ ├── policy.go 压缩策略（部分/完整/反应式）
│ │ │ ├── grouping.go 消息分组（按 API 往返）
│ │ │ └── default_bundle.go 默认 Bundle（claude+programming）
│ │ │
│ │ │ ── 扩展机制 ──
│ │ ├── hooks/ Hook 系统
│ │ │ ├── hooks.go Manager / 12 种 HookType
│ │ │ ├── handler.go ShellHandler / CallbackHandler
│ │ │ └── executor.go 超时保护执行器
│ │ │
│ │ ├── plugin/ 插件系统
│ │ │ ├── loader.go 加载 / 启用 / 禁用
│ │ │ ├── dependency.go DFS 依赖解析 / 循环检测
│ │ │ └── manifest.go Manifest 解析 / 验证
│ │ │
│ │ ├── memory/ 记忆系统
│ │ │ ├── memory.go Store 接口 / fileStore 实现（RWMutex）
│ │ │ ├── relevance.go 相关性评分 / AI 选择器
│ │ │ ├── freshness.go 新鲜度警告 / 类型化阈值
│ │ │ ├── sync.go 团队同步（Git/HTTP adapter）
│ │ │ └── extractor.go 自动提取代理
│ │ │
│ │ ├── permission/ 权限系统
│ │ │ ├── checker.go dynClass 驱动检查（无 fallback 硬编码）
│ │ │ ├── bash_security.go 危险命令检测（递归 AST）
│ │ │ ├── classifier.go 白名单 → 规则 → AI 三层级联
│ │ │ └── rules.go 规则引擎 / 学习 / 持久化
│ │ │
│ │ ├── security/ 安全
│ │ │ ├── audit.go AuditSink 接口 / AuditEntry
│ │ │ ├── secret_scanner.go SecretGuard / 45 条内置规则
│ │ │ └── secret_rule.go 规则定义 / 编译缓存
│ │ │
│ │ ├── evolve/ 自进化 (v0.2+ 接口矩阵 9/9)
│ │ │ ├── interfaces.go 9 接口 + Candidate / Feedback / ReplayEvent / ShadowResult
│ │ │ ├── parameter_store_file.go FileParameterStore (版本化 + Lock + Watch)
│ │ │ ├── log_source_file.go FileLogSource (JSONL + UTC 日期分片)
│ │ │ ├── feedback_channel_file.go FileFeedbackChannel (entity×date 分片)
│ │ │ ├── default_log_replayer.go DefaultLogReplayer (first-touch per-metric 配对)
│ │ │ ├── generator_llm.go LLMGenerator (窄 LLMClient + JSON array 解析)
│ │ │ ├── evaluator_impls.go WeightedEvaluator + FuncEvaluator
│ │ │ ├── parameter_evolver_default.go DefaultParameterEvolver (Propose/Apply + AuditLogger)
│ │ │ ├── reflector_impls.go AggregatorReflector + FuncReflector
│ │ │ └── shadow_runner_default.go DefaultShadowRunner (相对 divergence ∈ [0,1])
│ │ │
│ │ ├── daemon/ 守护进程（CLI 后台模式 + 平台共用）
│ │ │ ├── daemon.go DaemonManager / Accept 循环
│ │ │ ├── session_pool.go 会话池 / 容量控制
│ │ │ ├── heartbeat.go 心跳服务 / 空闲检测
│ │ │ ├── crash_recovery.go 崩溃恢复（指数退避）
│ │ │ ├── idle_timeout.go 空闲超时（可重置定时器）
│ │ │ └── isolation.go 会话隔离（共享/独立）
│ │ │
│ │ ├── bridge/ 远程桥接（CLI 后台模式 + 平台共用）
│ │ │ ├── bridge.go BridgeTransport / SessionConn 接口
│ │ │ ├── event_serializer.go engine.Event → BridgeEvent 序列化
│ │ │ ├── serial_uploader.go 串行批量上传（背压控制）
│ │ │ ├── bounded_uuid_set.go 环形数组消息去重
│ │ │ └── transport/sse.go SSE Transport（断线重连 / Ping keepalive）
│ │ │
│ │ ├── execenv/ 执行环境（Executor 接口 + 本地实现）
│ │ │ ├── executor.go Executor 接口
│ │ │ ├── default_executor.go DefaultExecutor（本地 exec.Cmd）
│ │ │ └── env.go 环境变量注入
│ │ │
│ │ │ ── 工具 ──
│ │ ├── tools/ 工具框架
│ │ │ ├── tool.go Tool 接口 / DryRunnable / Reversible
│ │ │ ├── orchestrator.go 并发执行 / 分批 / panic 恢复
│ │ │ ├── registry.go 工具注册表
│ │ │ └── builtin/ 14 个内置工具
│ │ │ ├── bash.go Bash（进程管理/输出截断/后台化）
│ │ │ ├── fileedit.go FileEdit（原子写入/curly quote/diff 预览）
│ │ │ ├── fileread.go FileRead（图片/PDF/Notebook/EXIF）
│ │ │ ├── filewrite.go FileWrite（原子写入/secret 扫描）
│ │ │ ├── glob.go Glob（双引擎/symlink 安全）
│ │ │ ├── grep.go Grep（双引擎/多行匹配）
│ │ │ ├── webfetch.go WebFetch（SSRF 防护）
│ │ │ ├── websearch.go WebSearch
│ │ │ ├── agent.go Agent（子 Agent 启动）
│ │ │ ├── skill.go Skill（inline/fork 执行）
│ │ │ ├── task.go Task（创建/更新/列表）
│ │ │ └── ... scratchpad / monitor / exec / toolsearch
│ │ │
│ │ │ ── 通信 ──
│ │ ├── websocket/ WebSocket 传输
│ │ ├── inbox/ 进程间通信
│ │ │ ├── inbox.go Inbox 接口
│ │ │ ├── memory.go 内存 Inbox（同进程）
│ │ │ ├── uds_server.go UDS Inbox（跨进程）
│ │ │ └── router.go InboxRouter（agentName → Inbox）
│ │ │
│ │ ├── tasklist/ 共享任务板（Agent Teams）
│ │ │ ├── tasklist.go TaskList / Store 接口
│ │ │ ├── memory_store.go 内存 Store
│ │ │ └── markdown_store.go MarkdownStore（Flyto ↔ Claude Code 互操作）
│ │ │
│ │ │ ── Provider ──
│ │ └── providers/ Provider 实现
│ │ ├── anthropic/ Anthropic Messages API
│ │ │ └── provider.go Stream / buildRequest / Thinking / Caching
│ │ ├── openai/ OpenAI Chat Completions
│ │ ├── gemini/ Google Gemini（AI Studio + Vertex AI）
│ │ ├── minimax/ MiniMax（Native/OpenAI/Anthropic 三模式）
│ │ ├── ollama/ Ollama 本地
│ │ ├── lmstudio/ LM Studio 本地
│ │ ├── openrouter/ OpenRouter 聚合
│ │ └── shared/ 共享工具（MaskAPIKey）
│ │
│ ├── internal/ 内部实现（消费者不可 import）
│ │ ├── transport/ 通用 SSE 流式 HTTP 客户端
│ │ │ ├── client.go NewClient / ClientOption / Stream
│ │ │ ├── classifier.go ErrorClassifier 接口 / Default / Anthropic
│ │ │ ├── stream_guard.go 空闲看门狗 / 部分流检测
│ │ │ ├── preconnect.go TCP+TLS 预热 / DNS 缓存
│ │ │ └── retry/ 重试策略框架
│ │ │ ├── policy.go RetryPolicy / CompositePolicy
│ │ │ ├── backoff.go 指数退避 + crypto/rand jitter
│ │ │ ├── retryer.go 执行器 / Observer 回调
│ │ │ └── anthropic.go Anthropic 6 层策略组合
│ │ │
│ │ ├── wire/ 协议序列化
│ │ │ ├── anthropic.go Anthropic SSE 解析 → flyto.Event
│ │ │ ├── openai.go OpenAI SSE 解析 → flyto.Event
│ │ │ ├── gemini.go Gemini SSE 解析 → flyto.Event
│ │ │ ├── schema.go $ref 展开 / 约束裁剪 / 复杂度校验
│ │ │ └── tools.go 工具数量上限检查
│ │ │
│ │ ├── apierror/ 共享错误类型（打破循环依赖）
│ │ ├── mcp/ MCP 协议客户端
│ │ │ ├── client.go JSON-RPC / 工具列表刷新 / Elicitation
│ │ │ ├── manager.go 多服务器管理 / 并发连接 / 重连
│ │ │ ├── stdio_transport.go 子进程传输
│ │ │ ├── sse_transport.go SSE 传输
│ │ │ └── http_transport.go HTTP Streamable 传输
│ │ │
│ │ ├── cache/ 缓存
│ │ │ ├── ttl.go TTL 缓存 / 后台 GC / 后台刷新
│ │ │ ├── prompt_hash.go Prompt 内容 hash（cache 失效检测）
│ │ │ └── tool_schema_hash.go 工具 Schema hash（cache_control 排序）
│ │ │
│ │ ├── tokenizer/ Token 估算（通用 BPE 近似）
│ │ ├── logger/ 日志（secret 脱敏）
│ │ └── syslib/ 系统级库
│ │ ├── bash/ Bash AST 解析（heredoc/引号/命令替换）
│ │ ├── diff/ Myers diff 算法 + unified patch
│ │ └── git/ Git 操作封装（branch/status/worktree）
│ │
│ ├── cmd/ 开发工具（与 core 紧耦合）
│ │ ├── capability-probe/ 能力探测（产出 capabilities.json）
│ │ ├── minimax-probe/ MiniMax 专项探测
│ │ └── schema-probe/ Schema 兼容性探测
│ ├── examples/ 使用示例
│ ├── docs/ 核心库文档
│ ├── FLYTO.md AI Agent 系统指令
│ └── TODO.md 待办事项
│
├── platform/ 平台服务（分两层）
│ ├── common/ 通用 platform (Go, module: flyto-platform-common)
│ │ ├── cmd/common/ 平台通用服务入口
│ │ ├── internal/
│ │ │ ├── api/ gRPC + HTTP 入口（auth/tenant interceptor）
│ │ │ ├── auth/ JWT + OIDC 验证
│ │ │ ├── tenant/ 多租户 primitive（不透明 ID）
│ │ │ ├── server/ HTTP API server（REST/SSE，路由/中间件）
│ │ │ └── sandbox/ 沙箱 Executor（E2B cloud backend）
│ │ └── frontend/ 📌 Web 前端
│ └── industry/<name>/ 行业 platforms（C#）：logistics / erp / sales / crm / finance / ads / decision
│
├── tui/ 终端 UI（module: flyto-tui）
│ ├── cmd/flyto/ CLI 入口
│ └── internal/ UI 实现（app / render / commands）
│
├── docs/ 项目级文档
│ └── writing-guide.md 文档防坑清单（API 错误根因 + 检查清单）
├── CLAUDE.md 开发指令
└── go.work Go workspace（use ./core）
📌 = 占位，待实现
快速开始¶
import (
"git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/engine"
"git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/anthropic"
)
eng, _ := engine.New(&engine.Config{
Provider: anthropic.New(anthropic.Config{APIKey: "..."}),
Model: "claude-sonnet-4-6",
Cwd: ".",
})
defer eng.Close()
for event := range eng.Run(ctx, "hello") {
// 处理事件
}
架构决策¶
- Provider + Model 必填 - 引擎不预设任何供应商或模型
- 库 vs 平台 - core 是纯 Go 库(零 HTTP 服务),platform 是部署服务
- 零硬编码 - 定价/模型信息由运行时获取,不写死在代码中
- daemon 共享 - CLI 后台模式和平台服务共用 core/pkg/daemon