# Flyto Agent Core

可嵌入的 Go Agent 核心库 -- 领域无关的智能体运行时.Go SDK 直接消费,零外部依赖.

## 项目统计

| 指标 | 数值 |
|------|------|
| Go 源文件 | 247 个 |
| 测试文件 | 178 个 |
| 测试函数 | 2585 个 |
| 源代码行数 | ~134,500 行(含测试) |
| 内置工具 | 14 个 |
| 模块路径 | `flyto-agent` |

## 目录结构

```
core/
├── internal/                 内部实现（消费者不可 import）
│   ├── transport/            通用 SSE 流式 HTTP 客户端（ClientOption 注入）
│   │   └── retry/            重试策略框架
│   ├── wire/                 协议序列化（Anthropic/OpenAI/Gemini 三种格式）
│   ├── apierror/             共享错误类型
│   ├── mcp/                  MCP 协议客户端
│   ├── cache/                TTL 缓存 + prompt hash
│   ├── tokenizer/            Token 估算
│   ├── logger/               结构化日志（脱敏）
│   └── syslib/               系统级库
│       ├── bash/             Bash AST 解析
│       ├── diff/             Myers diff 算法
│       └── git/              Git 操作封装
├── pkg/                      公共包（消费者可 import）
│   ├── flyto/                公共契约（ModelProvider / Event / Request / ModelInfo）
│   ├── engine/               核心引擎（Run loop / 工具分发 / Dream / SubAgent）
│   ├── config/               配置（ModelRegistry / ModelRole）
│   ├── query/                内部消息类型（Message / Content / Usage）
│   ├── context/              Prompt Bundle + 压缩策略
│   ├── hooks/                Hook 系统
│   ├── plugin/               插件系统
│   ├── memory/               记忆系统
│   ├── permission/           权限系统
│   ├── security/             审计 + Secret 扫描
│   ├── evolve/               自进化 -- v0.2+ 9 接口矩阵 (ParameterStore / LogSource /
│   │                          FeedbackChannel / LogReplayer / Generator / Evaluator /
│   │                          Reflector / ParameterEvolver / ShadowRunner), 每接口含
│   │                          文件引用实现 + 单元测试, 零外部依赖
│   ├── websocket/            WebSocket 传输
│   ├── inbox/                进程间通信（UDS）
│   ├── tools/                工具框架 + 内置工具
│   │   └── builtin/
│   └── providers/            Provider 实现
│       ├── anthropic/
│       ├── openai/
│       ├── gemini/
│       ├── minimax/
│       ├── ollama/
│       ├── lmstudio/
│       ├── openrouter/
│       └── shared/
├── examples/                 使用示例
├── docs/                     文档
├── FLYTO.md                  AI Agent 系统指令
└── TODO.md                   待办事项
```

## 快速开始

### Go SDK 模式(10 行代码)

Provider + Model 必填,引擎不预设供应商和模型.

```go
package main

import (
    "context"
    "fmt"
    "os"

    "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"
)

func main() {
    agent, err := engine.New(&engine.Config{
        Provider: anthropic.New(anthropic.Config{APIKey: os.Getenv("ANTHROPIC_API_KEY")}),
        Model:    "claude-sonnet-4-6",
        Cwd:      ".",
    })
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        os.Exit(1)
    }
    defer agent.Close()

    for event := range agent.Run(context.Background(), "查看当前目录结构") {
        switch e := event.(type) {
        case *engine.TextDeltaEvent:
            fmt.Print(e.Text)
        case *engine.ToolUseEvent:
            fmt.Printf("\n[tool] %s\n", e.ToolName)
        case *engine.DoneEvent:
            fmt.Printf("\n--- %d turns, $%.4f ---\n", e.TurnCount, e.TotalCostUSD)
        case *engine.ErrorEvent:
            fmt.Fprintf(os.Stderr, "error: %v\n", e.Err)
        }
    }
}
```

## 特性

- **可嵌入的 Agent 引擎** -- Go SDK 直接消费,引擎不知道自己跑在哪里
- **19 个内置工具** -- Bash, Read, Edit, Write, Glob, Grep, WebFetch, WebSearch, Agent, TaskCreate, TaskList, TaskUpdate, ToolSearch, Gitignore, SendMessage (Agent Teams), AddSharedTask / ListSharedTasks / ClaimSharedTask / CompleteSharedTask (Agent Teams 共享清单)
- **Bash AST 解析器** -- 完整的 Bash 命令 AST 解析(heredoc,引号,命令替换,进程替换,算术展开),替代字符串分割的安全分析
- **模型角色系统** -- ModelRegistry 管理 Main/Fast/Thinking/Embed 四种角色,业务逻辑不硬编码模型 ID,支持注册第三方模型
- **7 个 Provider** -- Anthropic/OpenAI/Gemini/MiniMax/OpenRouter/Ollama/LMStudio,通过 Provider 接口统一
- **Prompt Caching** -- 系统提示和工具描述自动缓存,多轮对话节省 ~78% 输入成本
- **完整的权限系统** -- 规则匹配 + 风险评估 + 自动学习,4 种权限模式,CompositeHandler 多处理器叠加
- **防御性编程** -- 三层防御模式(指令 + 参数 + 兜底),每个模型交互点都有降级策略
- **EngineObserver 可观测性** -- 结构化事件/指标/调用链接口,Noop/Stderr/Composite/Buffered 多种实现
- **NormalizePipeline** -- 10 步可组合消息规范化管道
- **自进化能力** -- CreateTool / LearnSkill / Reflect,Agent 运行时自己创建工具和学习技能
- **MCP 协议支持** -- Transport 接口抽象(Stdio/SSE/HTTP),工具名统一 mcp__server__tool 格式
- **插件系统** -- 发现 + 加载 + 技能注入 + Hook 扩展
- **记忆系统** -- 跨会话持久化 + RelevanceScorer 接口化
- **Hook 系统** -- 12 种 Hook 类型,覆盖工具调用,会话生命周期,权限等关键节点
- **三层压缩降级** -- 单次压缩 -> 砍头重试 -> 分块压缩,CompactCircuitBreaker 断路器
- **流式优先** -- 所有输出通过 Go channel 推送,消费层 `for range` 即可
- **Agent Teams (L1330)** -- peer-to-peer 通讯 + 共享任务清单, `send_message` 内置工具 / `tasklist.Store` 接口分层存储 / Anthropic Claude Code tasks.md 双向互操作 / 跨行业中立 (编程/金融/医疗/仓储/法律示例见 `examples/agent_teams/`)
- **零外部依赖** -- `go.mod` 只有标准库,编译产物是单个二进制

## 文档索引

| 文档 | 说明 |
|------|------|
| [docs/architecture.md](docs/architecture.md) | 内部架构,模块依赖,数据流 |
| [docs/api-reference.md](docs/api-reference.md) | HTTP API 完整参考 + [API 消费形态](docs/api-reference.md#api-消费形态--api-consumption-patterns) (push / pull / callback 三形态速查) |
| [docs/tools.md](docs/tools.md) | 14 个内置工具详细文档 |
| [docs/configuration.md](docs/configuration.md) | 多级配置,权限规则,Hook,MCP |
| [docs/evolution.md](docs/evolution.md) | 自进化系统(CreateTool/LearnSkill/Reflect) |
| [docs/model-roles.md](docs/model-roles.md) | 模型角色系统,定价,Prompt Caching |
| [docs/defensive-programming.md](docs/defensive-programming.md) | 防御性编程指南(内部文档) |
| [docs/agent_teams.md](docs/agent_teams.md) | Agent Teams MVP 设计 (L1330),Anthropic 对照表,跨行业场景 |
| [docs/agent_teams_tasklist.md](docs/agent_teams_tasklist.md) | TaskList 业务+存储分层,自定义 Store 接入模板 |

## 构建

```bash
# 运行测试
cd core && go test ./...

# 运行示例
cd core && go run ./examples/basic.go
```

## 许可证

Proprietary