Flyto Agent - 平台层 & 消费层 TODO
以下功能不属于引擎层(将开源),需要在平台层(独立仓库)或消费层中实现.
引擎层只提供接口/钩子,具体实现由消费者决定.
更新时间:2026-04-05
优先级说明
- 🔴 P0:平台 MVP 必须有
- 🟡 P1:平台第二阶段
- 🟢 P2:平台扩展功能
- ⚪ P3:长期规划
1.1 HTTP API Server(P0)
当前状态:internal/server/server.go 是一个单节点原型,功能已完整但不具备生产级多租户能力.
| 条目 |
说明 |
引擎钩子 |
| ✅ 多租户 API Key 管理 |
TenantConfig{TenantID,APIKey} + map[APIKey]TenantConfig 索引,authMiddleware 验证并注入 TenantID |
platform/pkg/server/server.go |
| ✅ 会话管理 API |
POST /v1/sessions,GET /v1/sessions/:id,DELETE /v1/sessions/:id,SessionPool 容量控制,IdleTimer 空闲超时 |
platform/pkg/server/server.go |
| ✅ 流式 SSE API |
持久 SSE(GET /v1/sessions/:id/events)+ 独立 POST 消息端点,Last-Event-ID 断线重连(事件环形缓冲),X-Accel-Buffering:no |
platform/pkg/server/server.go |
| ✅ 权限请求转发 API |
HandlePermission(sessionID) 返回 permission.Handler,通过 channel 桥接 SSE 推送和 POST /permissions/:req_id 回复 |
platform/pkg/server/server.go |
| 🟡 WebSocket API |
双向通信替代 SSE + REST 轮询,适合低延迟交互和实时状态同步 |
同 SSE,引擎事件 channel 接入 |
| 🟡 健康检查与就绪探针 |
GET /healthz,GET /readyz,Kubernetes Deployment 必须 |
无 |
| 🟡 Prometheus 指标暴露 |
GET /metrics,接入 EventObserver/MetricObserver 实现 |
engine.EventObserver(pkg/engine/observer.go) |
| 🟡 请求追踪(OpenTelemetry) |
Trace/Span 注入,接入 TraceObserver 实现 |
engine.TraceObserver(pkg/engine/observer.go) |
| 🟢 gRPC API |
为低延迟 SDK 客户端提供 protobuf 接口,可选 |
无 |
1.2 数据库持久化(P0)
方案:Neon PostgreSQL + MySQL Gateway + 前进式分支(已在讨论中确定).
| 条目 |
说明 |
引擎接口 |
| 🔴 会话历史持久化 |
Transcript JSON 存数据库,替代本地文件.引擎已支持从 transcriptPath 恢复,平台实现路径策略 |
engine.LoadTranscript(),engine.SaveTranscript()(pkg/engine/session_persist.go) |
| 🔴 用户偏好持久化 |
~/.flyto/settings.json 的内容持久化到数据库,多设备同步 |
pkg/config/config.go(引擎读本地,平台提供远端同步) |
| 🟡 记忆持久化(跨会话) |
将 memory.Store 内容持久化到数据库,实现 HTTP SyncAdapter |
memory.SyncAdapter(pkg/memory/sync.go) |
| 🟡 审计日志持久化 |
将 AuditEntry 写入数据库,支持查询和导出 |
security.AuditSink(pkg/security/audit.go) |
| 🟡 插件安装记录 |
记录哪个租户安装了哪个插件,版本和状态 |
pkg/plugin/(引擎只做加载,不管安装记录) |
| 🟡 自进化产物持久化 |
ToolBuilder / SkillLearner 生成的文件持久化到数据库,而非本地磁盘 |
pkg/evolve/(目前写磁盘) |
| 🟢 向量数据库集成 |
为 Memory 相关性搜索提供向量检索(pgvector / Pinecone 等) |
memory.RelevanceScorer(pkg/memory/scorer.go) |
1.3 用户与认证(P0)
| 条目 |
说明 |
引擎接口 |
| 🔴 用户注册/登录 |
邮箱密码注册,JWT 签发,refresh token 管理 |
无(平台自建) |
| 🔴 Bearer Token 验证中间件 |
原型已有简单实现(server.authMiddleware),生产需接数据库验证 |
无 |
| 🟡 OAuth2 / OIDC 登录 |
实现 AuthProvider 接口,支持 GitHub OAuth,Google 等第三方登录 |
mcp.AuthProvider(internal/mcp/transport.go) |
| 🟡 SSO 集成 |
企业级 SAML / OIDC SSO,统一身份入口 |
无 |
| 🟡 MCP OAuth 代理 |
CLI 通过平台完成 OAuth2 Authorization Code flow,获得 MCP server token |
mcp.AuthProvider(internal/mcp/transport.go) |
| 🟢 角色权限管理(RBAC) |
用户角色(admin/developer/viewer),控制哪些 Agent 类型可用,哪些工具可操作 |
permission.Handler(pkg/permission/permission.go) |
1.4 计费与速率限制(P0)
| 条目 |
说明 |
引擎接口 |
| 🔴 按 token 计费 |
从 UsageEvent 获取每次调用的 InputTokens/OutputTokens/CostUSD,写入计费流水 |
engine.UsageEvent(pkg/engine/events.go) |
| 🔴 速率限制(租户级) |
原型已有 IP 级速率限制(rateLimiter),平台需要租户级精细限流(token/min,请求/min) |
无 |
| 🟡 用量配额管理 |
每个租户设置月度 token 上限,超限后拒绝请求或降级 |
engine.TokenBudgetState(pkg/engine/token_budget.go) |
| 🟡 账单查询 API |
GET /billing/usage,返回当月用量和账单明细 |
无 |
1.5 插件市场(P1)
引擎层只负责从本地路径加载插件(pkg/plugin/),分发,签名,安装均在平台层.
| 条目 |
说明 |
引擎接口 |
| 🟡 插件发布 API |
开发者上传 plugin bundle(DXT/MCPB 格式),平台验证 manifest 并存储 |
plugin.ValidateManifest()(pkg/plugin/loader.go) |
| 🟡 插件签名与验证 |
上传时生成 ECDSA 签名,安装时验证签名完整性,防篡改 |
无(平台实现) |
| 🟡 插件搜索与发现 API |
GET /plugins?q=keyword&category=tools,返回插件列表 |
无 |
| 🟡 插件安装 API |
POST /plugins/install,将 bundle 下载到用户的 ~/.flyto/plugins/ 或平台存储 |
plugin.Manager(pkg/plugin/plugin.go) |
| 🟡 插件版本管理 |
存储多版本 bundle,支持回滚;解析 plugin.json 中的 version 字段 |
pkg/plugin/manifest.go(Version 字段) |
| 🟡 插件依赖解析(语义版本约束) |
支持 ^1.0.0,~1.2.3 版本约束,跨组织依赖白名单 |
plugin.DependencyResolver(pkg/plugin/dependency.go) |
| 🟢 插件市场 Web UI |
搜索/浏览/安装插件的 Web 界面 |
无 |
| 🟢 插件评分与评论 |
用户对插件打分,展示下载量 |
无 |
1.6 远程 Bridge 模式(P1)
将本地开发环境接入云端任务分发(对应早期方案 Cloud Bridge 功能).
| 条目 |
说明 |
引擎接口 |
| 🟡 环境注册 API |
本地 CLI 启动时向平台注册机器信息(机器名,Git 仓库,当前分支,工作目录) |
无(平台新增) |
| 🟡 任务轮询 API |
本地 CLI 长轮询 GET /bridge/tasks,获取待处理任务 |
engine.Engine.Run()(pkg/engine/engine.go) |
| 🟡 任务确认与心跳 |
本地 CLI 定期 POST /bridge/heartbeat,上报任务执行状态,防超时 |
无 |
| 🟡 权限请求转发(Bridge) |
本地执行遇到权限请求时,通过平台推给远端操作者,操作者通过 Web UI 审批 |
permission.Handler(pkg/permission/permission.go) |
| 🟡 事件流回传 |
本地引擎事件通过 WebSocket / SSE 实时回传到平台,远端用户可看到执行进度 |
engine.Session.Events() channel |
| 🟢 SSE/WebSocket 传输层 |
支持两种协议,按客户端能力协商;WSS 加密 |
无 |
1.7 安全与审计扩展(P1)
| 条目 |
说明 |
引擎接口 |
| 🟡 AuditSink 数据库实现 |
将 AuditEntry 写入 PostgreSQL,支持时间范围查询,按租户隔离 |
security.AuditSink(pkg/security/audit.go) |
| 🟡 审计日志 API |
GET /audit?session_id=xxx&from=...&to=...,返回操作审计列表 |
无 |
| 🟡 企业 SIEM 对接 |
实现 AuditSink 将审计数据推送到 Splunk / Datadog / ELK |
security.AuditSink(pkg/security/audit.go) |
| 🟡 密钥扫描结果上报 |
SecretGuard 拦截到泄露时,除本地日志外还上报平台告警 |
security.SecretGuard(pkg/security/secret_scanner.go) |
| 🟢 合规报告生成 |
基于审计日志自动生成 SOC2 / ISO27001 合规报告 |
无 |
1.8 模型路由(P2)
| 条目 |
说明 |
引擎接口 |
| 🟢 多模型负载均衡 |
同一模型角色(Role)分配到多个 API 端点,按权重路由 |
config.ModelRegistry(pkg/config/models.go) |
| 🟢 模型降级策略 |
主模型不可用时自动切换到备用模型,避免服务中断 |
engine.FallbackConfig(pkg/engine/fallback.go) |
| 🟢 自定义模型端点 |
通过平台代理国产模型(千问/文心/Kimi),注入兼容 OpenAI 格式的 endpoint |
config.ModelRegistry + 自定义 API transport |
| 🟢 按租户路由 |
不同租户配置不同的模型端点(VIP 租户用专属高性能模型) |
无 |
2. CLI 消费层
2.1 终端 UI(P0)
引擎通过 Go channel 输出事件流,CLI 负责渲染.
| 条目 |
说明 |
引擎事件 |
| 🔴 文本流式输出渲染 |
TextDeltaEvent → 逐字输出,支持颜色,行宽自适应 |
engine.TextDeltaEvent(pkg/engine/events.go) |
| 🔴 工具调用展示 |
ToolUseEvent 展示工具名,输入参数;ToolResultEvent 展示执行结果摘要 |
engine.ToolUseEvent,engine.ToolSummaryEvent |
| 🔴 权限确认对话框 |
收到 PermissionRequestEvent 后弹出终端交互框(y/n/永久允许),通过 Session.ResolvePermission() 回复 |
engine.PermissionRequestEvent(pkg/engine/events.go) |
| 🔴 Token 用量状态栏 |
接收 UsageEvent 更新底部状态栏(token 用量,估算费用,上下文窗口占用百分比) |
engine.UsageEvent,engine.TokenBudgetState(pkg/engine/token_budget.go) |
| 🟡 文件变更可视化 |
Edit/Write 工具执行后展示 diff,与 FileEditResultData 的结构化结果对接 |
tools.FileEditResultData(pkg/tools/builtin/fileedit.go) |
| 🟡 斜杠命令处理 |
收到 SlashCommandEvent 后由 CLI 层处理(引擎不内置处理斜杠命令) |
engine.SlashCommandEvent(pkg/engine/events.go) |
| 🟡 多 Agent 并行进度展示 |
Tmux pane 风格,每个 SubAgent 独占一列,实时更新执行状态 |
engine.SubAgentEvent(pkg/engine/events.go) |
| 🟡 错误友好提示 |
ErrorEvent 按错误码分类展示(网络错误,上下文溢出,权限拒绝),提示用户下一步操作 |
engine.ErrorEvent(pkg/engine/events.go) |
| 🟢 自动补全(工具名/路径) |
命令行输入时提示工具名和文件路径 |
无 |
2.2 Daemon 模式(P1)
长运行监督进程,管理多个并发会话.
| 条目 |
说明 |
引擎接口 |
🟡 flyto daemon start 命令 |
后台启动长运行 HTTP 服务,监听 Unix socket,管理多会话进程池 |
engine.SessionManager(pkg/engine/session_manager.go) |
🟡 flyto ps 会话列表 |
列出所有活跃会话(ID,状态,运行时长,token 用量) |
engine.SessionManager.List() |
🟡 flyto logs <session-id> |
实时 tail 指定会话的事件流 |
engine.Session.Events() channel |
🟡 flyto attach <session-id> |
接管现有会话的终端 UI |
无(需要引擎增加 re-attach 能力) |
🟡 flyto kill <session-id> |
强制终止会话,发送 StopEvent |
engine.Engine.Close()(pkg/engine/engine.go) |
| 🟡 Worker 进程池 |
Daemon 维护可复用的 engine 实例池,降低冷启动延迟 |
engine.New()(pkg/engine/engine.go) |
| 🟡 会话状态持久化(跨重启) |
Daemon 崩溃后恢复未完成的会话,依赖数据库或文件系统 |
engine.SaveTranscript() / LoadTranscript()(pkg/engine/session_persist.go) |
| 🟡 崩溃恢复 |
会话进程崩溃时自动 restart,从最后一个检查点继续 |
无(消费层自建) |
| 🟢 日志轮转 |
会话日志按天或按大小轮转,防止磁盘打满 |
无 |
| 🟢 资源限制 |
每个会话配置 CPU/内存上限(cgroup / ulimit) |
无 |
2.3 CLI 专用 Agent 类型(P1)
这些 Agent 类型属于 CLI 场景,不应内置在引擎层.引擎层只提供注册机制.
| 条目 |
说明 |
引擎接口 |
🟡 claude-code-guide Agent |
引导新用户了解 Flyto Agent 功能的专属 Agent,CLI 定义并注册 |
engine.AgentRegistry.Register()(pkg/engine/agent_def.go) |
🟡 statusline-setup Agent |
帮助用户配置 shell 状态栏的专属 Agent,CLI 定义并注册 |
engine.AgentRegistry.Register() |
| 🟡 Plugin Agent 类型注册 |
插件安装后,将 plugin.json 中定义的 Agent 类型注册到引擎 |
engine.AgentRegistry.Register() |
🟡 .flyto/agents/ 目录加载 |
CLI 启动时扫描 .flyto/agents/ 目录,加载自定义 Agent 定义文件(YAML/JSON) |
engine.AgentRegistry.Register() |
2.4 自进化审批 UI(P1)
| 条目 |
说明 |
引擎接口 |
| 🟡 进化提案终端展示 |
Agent 提交 EvolutionProposal 时,CLI 展示提案详情(工具代码/技能/配置变更),等待用户确认 |
evolve.ApprovalFunc(pkg/evolve/evolve.go) |
| 🟡 进化历史查询 |
flyto evolve list 查看所有历史提案及状态(pending/approved/rejected) |
evolve.Evolver(pkg/evolve/evolve.go) |
| 🟢 进化提案 Web 审批 |
Web UI 中的进化提案审批界面,适合远程场景 |
evolve.ApprovalFunc |
3. Web UI 消费层
3.1 Agent 交互界面(P1)
| 条目 |
说明 |
| 🟡 对话界面 |
类 ChatGPT 风格,支持 Markdown 渲染,代码高亮 |
| 🟡 工具调用可视化 |
每次工具调用展示输入/输出,可折叠查看详情 |
| 🟡 文件树变更展示 |
Edit/Write 操作的 diff 展示,支持接受/拒绝 |
| 🟡 权限弹框 |
接收平台 SSE permission_request 事件,弹出审批对话框,调用 POST /sessions/:id/permissions/:toolId 回复 |
| 🟡 Token 用量仪表盘 |
实时展示当前会话的 token 消耗和预估费用 |
3.2 多 Agent 看板(P2)
| 条目 |
说明 |
| 🟢 并行 Agent 进度看板 |
Web 看板,类 GitHub Actions 流水线风格,展示多 SubAgent 并行执行状态 |
| 🟢 Agent 依赖图可视化 |
有向图展示 Agent 之间的依赖关系和数据流 |
| 🟢 自进化提案 Web 审批 |
展示 EvolutionProposal 详情,支持在线代码审查后批准 |
4. SDK 消费层示例
4.1 嵌入示例(P1)
| 条目 |
说明 |
相关文件 |
| 🟡 最小嵌入示例 |
展示如何用 5 行代码将引擎嵌入 Go 应用(参考 examples/basic.go) |
engine/examples/basic.go |
| 🟡 自定义 PermissionHandler 示例 |
展示 CLI(终端对话框),HTTP(WebSocket),自动允许三种实现 |
pkg/permission/permission.go(Handler 类型) |
| 🟡 自定义 AuditSink 示例 |
展示数据库实现(写入 PostgreSQL)和远端上报实现(HTTP POST) |
pkg/security/audit.go(AuditSink 接口) |
| 🟡 自定义 SyncAdapter 示例 |
展示 HTTP 后端和 NFS 后端的 Memory 同步实现 |
pkg/memory/sync.go(SyncAdapter 接口) |
| 🟡 自定义 AuthProvider 示例 |
展示 OAuth2 token 动态刷新的实现 |
internal/mcp/transport.go(AuthProvider 接口) |
| 🟢 仓储场景嵌入示例 |
展示跨行业:禁用 Bash/Edit 工具,只开放仓储查询工具 |
pkg/engine/agent_def.go(AgentDefinition) |
4.2 自定义 PermissionHandler 参考实现(P1)
| 条目 |
说明 |
| 🟡 CLI Handler |
使用 github.com/charmbracelet/bubbletea 或纯 bufio.Scanner 读取终端输入,渲染选项菜单 |
| 🟡 HTTP/WebSocket Handler |
通过 WebSocket 将权限请求推送到前端,等待用户在 Web UI 中点击批准/拒绝 |
| 🟡 Auto-Allow Handler |
测试 / CI 场景,所有请求自动批准,配合 permission.ModeBypass 使用 |
| 🟢 规则导入 Handler |
从配置文件加载预定义规则,无需用户交互(适合批量自动化场景) |
5. 引擎层预留的接口(平台层/消费层对接点)
这些接口在引擎里已定义,平台层/消费层需要实现:
| 接口 |
位置 |
说明 |
permission.Handler |
pkg/permission/permission.go |
权限请求回调,CLI 弹终端对话框,HTTP 用 WebSocket 推前端 |
security.AuditSink |
pkg/security/audit.go |
审计落地接口,实现数据库存储或 SIEM 对接 |
mcp.AuthProvider |
internal/mcp/transport.go |
MCP HTTP 鉴权,实现 OAuth2 token 动态刷新 |
memory.SyncAdapter |
pkg/memory/sync.go |
记忆同步后端,实现 HTTP 同步或企业数据库同步 |
engine.EventObserver |
pkg/engine/observer.go |
事件可观测性,实现 Prometheus 指标上报 |
engine.MetricObserver |
pkg/engine/observer.go |
指标可观测性,实现 Datadog / InfluxDB 上报 |
engine.TraceObserver |
pkg/engine/observer.go |
追踪可观测性,实现 OpenTelemetry / Jaeger 接入 |
evolve.ApprovalFunc |
pkg/evolve/evolve.go |
自进化提案审批回调,CLI 展示提案等待用户输入 |
engine.AgentRegistry |
pkg/engine/agent_def.go |
Agent 类型注册,CLI/Plugin 注册场景专用 Agent 类型 |
context.CompactionPolicy |
pkg/context/policy.go |
上下文压缩策略,自定义压缩触发时机和保留规则 |
memory.RelevanceScorer |
pkg/memory/scorer.go |
记忆相关性评分,可替换为向量检索实现 |
memory.MemoryExtractor |
pkg/memory/extractor.go |
记忆抽取策略,可替换为自定义 prompt 策略 |
6. 分仓库时机检查清单
在引擎层开源前,必须完成以下剥离工作:
- [ ]
internal/server/ 移至平台层仓库(包含单节点 HTTP Server 原型,可作为平台层起点)
- [ ]
cmd/agent-engine/main.go 保留在引擎层,只做最小 CLI 演示(无平台依赖)
- [ ] 确认
pkg/ 下所有包零外部依赖(运行 go mod tidy 验证)
- [ ] 确认代码/注释中无 "Anthropic"/"Claude Code" 品牌痕迹(保留 API endpoint 和 model ID)
- [ ]
FLYTO.md 不随引擎层开源(产品级宪法,仅内部使用)
- [ ]
examples/ 目录保留,作为 SDK 嵌入文档的起点
- [ ] 所有引擎接口有对应的 noop 实现(空实现降低消费者上手成本)
本文件由引擎代码扫描 + 架构讨论整理生成,随实现进度更新.
下次更新时机:平台层仓库建立后,将各条目与 Issue/PR 关联.