feikong-teams: Instructions file for Codex

fkteams 开发指南

项目概览

fkteams 是基于 AgentKit（底层为 CloudWeGo Eino ADK）的 Go 多智能体协作系统，提供 CLI/TUI、Web UI、OpenAI 兼容 API，以及 Discord、QQ、微信消息通道。前端位于 web/，构建产物通过 //go:embed 嵌入 Go 二进制。

本文件适用于整个仓库。若子目录以后增加更具体的 AGENTS.md，只写该子树的增量规则；冲突时以更具体的文件和用户当次指令为准。

• Go 模块：fkteams，版本以 go.mod 为准。
• 前端：React、TypeScript、Vite、Bun。
• 默认应用目录：~/.fkteams；可通过 FEIKONG_APP_DIR 覆盖。
• 完整架构说明见 docs/architecture.md；修改跨层依赖或运行链路前先阅读该文档。

常用命令

# 完整质量检查（格式、前端类型检查与构建、Go vet/test、diff check）
make check

# 开发与定向验证
make web-build
go test ./path/to/package
go test ./path/to/package -run TestName
go build ./...
go vet ./...

# 运行
go run ./cmd/fkteams
go run ./cmd/fkteams web             # 默认监听 :23456
go run ./cmd/fkteams serve

# 前端
cd web && bun run dev
cd web && bun test src

# 发布构建
make native
make all
make build t=linux:amd64
make clean

# 生成配置示例
go run ./cmd/fkteams generate config

go build ./...、go test ./... 和 go vet ./... 依赖已生成的 web/dist；直接运行这些命令前先执行 make web-build，或使用已包含该步骤的 Make 目标。web/dist/ 与 release/ 是生成物，不提交。

架构边界

分层与依赖方向

cmd -> bootstrap -> adapters -> app/runtime -> ports -> domain

• internal/domain 只放领域模型和值对象，不依赖框架、SDK、app、runtime 或 adapters。
• internal/ports 定义运行时无关契约，不依赖 app、runtime 或具体 adapter。
• internal/app 实现用例，不导入具体 adapter、AgentKit、Eino 或终端展示库。
• internal/runtime 提供运行时无关内核，不依赖 app 或具体 adapter。
• internal/adapters 实现外部技术和传输协议；AgentKit、Eino 及其 SDK 只能出现在 internal/adapters/runtime/agentkit。
• internal/bootstrap 是组合根，负责创建并连接 runtime、模型、工具、存储和后台服务。
• cmd/fkteams/main.go 保持最小化，只连接组合根和 CLI 命令入口。

入口必须调用 internal/app 用例，不能在 CLI、HTTP 或消息通道中重新实现核心业务流程。注册表和运行态依赖必须由应用实例持有并显式注入；不要引入可变的进程级默认实例、依赖注册副作用的 init() 或空白 import。

不要恢复已经移除的根级 agentcore、events、server、cli、channels 门面。对应实现分别位于 internal/app、internal/runtime/events 和 internal/adapters/transport。

关键目录

• cmd/fkteams/：可执行入口。
• internal/app/：chat、agent、tools、memory、schedule、skill、lifecycle 等用例。
• internal/domain/：event、history、memory、message、schedule、session 等领域类型。
• internal/ports/：hooks、memory、runtime、scheduler、storage、tools 契约。
• internal/runtime/：turn、events、hooks、checkpoint、retry、pathguard 等内核能力。
• internal/adapters/：模型、runtime、工具、存储、调度器和传输实现。
• internal/bootstrap/：默认依赖与服务装配。
• web/：React 前端；web/dist/ 为生成物。