fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/AGENTS.md

15 KiB
Raw Blame History

Fischer AgentKit — 项目上下文

规则

  • Python >= 3.11，必须使用类型注解，所有数据模型使用 pydantic>=2.0
  • 使用 Ruff 进行 lint 和格式化：ruff check src/ && ruff format src/（目标 py311，行宽 100）
  • 测试：pytest（asyncio_mode=auto），标记：integration、redis、postgres
  • 禁止使用 any 类型 — 使用合适的 Pydantic 模型或 Unknown
  • API Key 比较必须使用 hmac.compare_digest（恒定时间比较）
  • 专家名称使用 _EXPERT_NAME_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$") 校验
  • HandoffTransport 队列有界（maxsize=1024），关闭使用 sentinel 模式
  • 前端：Vue 3 + TypeScript + Ant Design Vue，Pinia stores，禁止 require() 调用
  • 异步生成器安全：在 async def 中禁止在第一个 yield 之前使用 return — 改用 return; yield 模式（见 .trae/rules/project_rules.md）
  • 所有回复必须是中文

技术栈

  • 后端：Python 3.11+、FastAPI、Uvicorn、Pydantic v2、SQLAlchemy 2（async）
  • 前端：Vue 3、TypeScript、Vite 5、Ant Design Vue 4、Pinia、Vue Router 4
  • 桌面端：Tauri 2.x（Rust 外壳 + Python sidecar）
  • 基础设施：Redis（总线/缓存/状态）、PostgreSQL + pgvector（情景记忆）
  • CLI：Typer + Rich
  • 精确版本：见 pyproject.toml（Python）、package.json（Node）

命令

# 后端
pip install -e ".[dev]"                # 安装开发依赖
agentkit gui --port 8002               # Web GUI（前端 + API）
agentkit serve --port 8001             # 仅 API 服务
agentkit chat                          # CLI 交互式聊天
agentkit init                          # 生成 agentkit.yaml
agentkit version / doctor / usage      # 工具命令
agentkit task submit/status/list/cancel # 任务管理
agentkit skill list/load/info          # 技能管理
agentkit pair --name X                 # 为外部系统生成 API Key
pytest                                 # 运行所有测试
pytest -m "not integration"            # 仅单元测试
ruff check src/ && ruff format src/    # Lint + 格式化

# 前端
cd src/agentkit/server/frontend
npm install                            # 安装依赖
npm run dev                            # Vite 开发服务器（代理 /api -> :8000）
npm run build:frontend                 # 生产构建 -> ../static
npm run typecheck                      # TypeScript 检查

# 桌面端
cd src/agentkit/server/frontend
npm run tauri dev                      # Tauri 开发模式
npm run tauri build                    # Tauri 生产构建

# Docker
docker-compose up -d                   # AgentKit + Redis + PostgreSQL

架构

请求流程

用户输入
  ├─ @board 前缀 -> BoardRouter (experts/board_router.py) -> BoardOrchestrator（多轮讨论）
  ├─ @team 前缀  -> ExpertTeamRouter (experts/router.py) -> TeamOrchestrator（流水线协作）
  └─ 其他         -> RequestPreprocessor (chat/request_preprocessor.py)
       Layer 0: @skill:xxx 前缀 -> 显式技能选择（SKILL_REACT 或技能配置的模式）
       Layer 1: 琐碎输入正则（~0ms，0 tokens）-> DIRECT_CHAT
                （问候、身份、事实问答、数学、翻译；由 _TOOL_CONTEXT_RE 守护）
       默认: -> REACT（LLM 在 agent 循环中自主决定工具使用）
  -> ExecutionMode: DIRECT_CHAT / REACT / SKILL_REACT / REWOO / REFLEXION / PLAN_EXEC / TEAM_COLLAB
     （chat handler 当前支持 DIRECT_CHAT、REACT、SKILL_REACT；其余抛出 "not yet supported"）

注意：旧的 3 层 CostAwareRouter（含 RegexRules / HeuristicClassifier / SemanticRouter / Vickrey Auction）已被 RequestPreprocessor 替换。IntentRouter（router/intent.py）存在但未接入 chat 流程。AuctionHouse（Vickrey 拍卖）位于 marketplace/auction.py（属于 marketplace 子系统，非路由）。

Agent 层级

BaseAgent (core/base.py) — 抽象基类，execute() 是 final 方法
  +-- ConfigDrivenAgent (core/config_driven.py) — YAML 驱动，3 种任务模式
  +-- ReActEngine (core/react.py) — Think->Act->Observe
  +-- ReflexionAgent (core/reflexion.py) — 反思驱动
  +-- ReWOOAgent (core/rewoo.py) — 无观察规划
  +-- StandaloneAgent (core/standalone.py) — 独立运行器

专家团队模式（流水线）

ExpertConfig（继承 AgentConfig）-> Expert（通过 AgentPool 包装 ConfigDrivenAgent）
ExpertTeam：管理专家、共享工作区、团队状态（FORMING→PLANNING→EXECUTING→SYNTHESIZING→COMPLETED）
TeamOrchestrator：流水线执行 — Lead 将任务分解为带 depends_on 的 PlanPhase，拓扑排序，并行分层
PlanPhase：id、name、assigned_expert、task_description、depends_on、status（PENDING/RUNNING/COMPLETED/FAILED）
TeamPlan：带依赖的阶段，topological_sort() 返回执行层（Kahn 算法）
ExpertTeamRouter：@team 前缀路由、@team:dev_team 模板展开、名称校验、MAX_EXPERTS=10
HandoffTransport：InProcess（asyncio.Queue）+ Redis Pub/Sub — 仅用于事件广播

流水线流程：

  1. @team 前缀触发团队模式（或 @team:dev_team 用模板，@team:expert1,expert2 显式指定）
  2. ExpertTeam.create_team() 将状态置为 PLANNING
  3. Lead Expert 通过 LLM 将任务分解为阶段（失败时回退为单阶段）
  4. topological_sort() 将阶段排成层（同层并行，层间串行）
  5. 每个阶段通过 AgentPool.create_agent 创建隔离的 ConfigDrivenAgent（上下文隔离，KTD3）
  6. 阶段输出通过 SharedWorkspace 传递（{plan_id}/phase/{phase_id}/output）
  7. Lead 综合结果（BEST 策略）
  8. 所有阶段都失败时：回退到单 agent 模式

事件序列：team_formed → plan_update → phase_started → expert_step → expert_result → phase_completed → team_synthesis → team_dissolved

团队模板：configs/experts/dev_team.yaml 在 bound_skills 字段存储成员列表（tech_lead、frontend_engineer、backend_engineer、qa_engineer、code_reviewer）

生命周期：FORMING -> PLANNING -> EXECUTING -> SYNTHESIZING -> COMPLETED -> DISSOLVED 失败时：回退到单 agent 模式（lead 或第一个活跃专家）。

模块映射

层级 模块 用途
API server/、cli/ FastAPI 路由 + Typer CLI
认证 server/auth/ JWT + RBAC + 终端安全（6 层白名单）
服务 core/、chat/、skills/、experts/ Agent 引擎、路由、技能、专家团队
数据 memory/、session/、bus/ 持久化、会话、消息
工具 llm/、tools/、evolution/、quality/、mcp/ LLM 网关、工具、自进化、质量、MCP
客户端 client/ ConfigSync、RemoteLLMProvider 集成

关键子系统

  • LLM 网关（llm/）：基于 LiteLLM 统一适配层（U15 迁移），保留原 6 个 provider 命名作为别名（OpenAI/Anthropic/Gemini/Doubao/Wenxin/Yuanbao），支持任意 OpenAI 兼容 API（如 DashScope/DeepSeek）；含 fallback、语义缓存、用量追踪、RemoteLLMProvider（client→server 代理，带 401 刷新重试）
  • 记忆（memory/）：4 层（SOUL/USER/MEMORY/DAILY）、WorkingMemory（Redis）、EpisodicMemory（PG+pgvector）、SemanticMemory（HTTP RAG）
  • 进化（evolution/）：Reflector、PromptOptimizer（遗传算法）、PitfallDetector、ABTester
  • 工具（tools/）：21 个内置 + MCP 扩展，组合（SequentialChain/ParallelFanOut/DynamicSelector）
  • 流水线（orchestrator/）：PipelineEngine、SagaOrchestrator、DynamicPipeline、HandoffManager
  • 总线（bus/）：MemoryBus（进程内）、RedisBus（分布式）
  • 认证（server/auth/）：JWT（access 15min + refresh 7d，HS256）、API Key（恒定时间比较）、3 级 RBAC（member/operator/admin + 权限位）、6 层终端安全（blocklist→shell-ops→builtin→global→user→session→danger）、bcrypt 密码哈希（rounds=12）

服务端路由（28 个模块）

前缀 模块 用途
/api/v1/agents agents.py Agent CRUD
/api/v1/tasks tasks.py 任务提交/查询/取消
/api/v1/skills skills.py 技能注册/列表
/api/v1/chat chat.py Chat REST + WebSocket
/api/v1/ws ws.py WebSocket 通道
/api/v1/llm llm.py LLM 用量
/api/v1/llm/chat llm_gateway.py LLM 网关代理（JWT 认证，SSE 流式）
/api/v1/health health.py 健康检查
/api/v1/metrics metrics.py 指标
/api/v1/evolution evolution.py + evolution_dashboard.py 自进化 API
/api/v1/memory memory.py 记忆管理
/api/v1/portal portal.py Portal
/api/v1/kb kb_management.py 知识库
/api/v1/skill-mgmt skill_management.py 技能管理
/api/v1/workflows workflows.py 工作流
/api/v1/terminal terminal.py 本地终端（client sidecar PTY）
/api/v1/terminal/server terminal_server.py 服务端终端（server PTY + 管理员审批）
/api/v1/terminal terminal_whitelist.py 白名单/黑名单/审计日志管理
/api/v1/settings settings.py 设置
/api/v1/auth auth.py 登录/刷新/登出/me
/api/v1/system system.py 系统资源（需 SYSTEM_CONFIG 权限）
/api/v1/config config_sync.py 配置版本 + 同步（轮询）
/api/v1/bitable bitable.py 多维表格 companion 服务
/api/v1/calendar calendar.py 日历服务（事件/提醒/同步）
/api/v1/documents documents.py 文档管理
/api/v1/admin admin.py 管理员操作
/api/v1/experts experts.py 专家团队管理
/api/v1/mcp mcp_publish.py MCP 发布

WebSocket Chat 协议

Client -> Server：message、reply、confirmation_reply、cancel、ping Server -> Client：connected、token、thinking、step、final_answer、skill_match、confirmation_request、confirmation_result、ask_human、error、pong 专家团队事件：

  • 生命周期：team_formed、plan_update、phase_started、phase_completed、phase_failed、team_dissolved
  • 专家执行（流式）：expert_step（thinking/tool_call/tool_result 步骤，payload 携带 expert_id/expert_name/expert_color/content/step）、expert_result_chunk（token 增量）、expert_result_chunk_reset（重试前清空）、expert_result（终结，status=completed|error）
  • 综合（流式）：team_synthesis_chunk（增量 chunk，携带 synthesis_id）、team_synthesis（终结，携带 synthesis_id + status=completed|error|cancelled）
  • PLAN_EXEC (U4)：phase_changed、phase_violation

synthesis_id 去重契约：后端在 team_synthesis_chunk 和 team_synthesis 事件中注入稳定标识 {plan_id}:synthesis，前端用它精确匹配 streaming milestone，避免重试/并发时孤儿 milestone。

execute_stream() 取消契约：ConfigDrivenAgent.execute_stream() 注册 CancellationToken 到 _active_tokens（与 BaseAgent.execute() 一致），使 cancel_task() 能协作式取消流式任务。

前端页面

  • /agent/chat — 专家团队聊天视图
  • /agent/code — 代码/工作流
  • /agent/monitor — 进化看板
  • /computer-use — 桌面控制
  • /login — 登录页（JWT 认证）
  • 终端面板 — 本地 + 服务端终端，含白名单管理器

配置优先级

CLI 参数 > agentkit.yaml > 环境变量（${VAR:-default}）> .env > 硬编码默认值

配置查找：--config 路径 > ./agentkit.yaml > ~/.agentkit/agentkit.yaml（三个路径都不存在时使用硬编码默认值，CLI 仍可启动）

约定

  • 技能配置：configs/skills/*.yaml（16 个预设，统一为 SkillConfig）
  • 技能分类：agent_template（执行引擎：react/direct/rewoo/reflexion/plan_exec/goal_driven）vs business_skill（领域技能）。通过 server/routes/skill_management.py 中的 _ENGINE_TEMPLATE_NAMES 分类。前端按 category 字段分组 — SkillsView 双栏布局，SkillCard/SkillsTab 显示类型标签（引擎/技能）和基于分类的图标
  • LLM 配置：agentkit.yaml llm 段（与服务端配置统一）
  • 流水线配置：configs/pipelines/*.yaml
  • 专家模板：configs/experts/*.yaml（15 个模板 — 5 编程专家 + 9 商业/思想领袖 + 1 团队模板 dev_team），通过 ExpertTemplateRegistry 注册
  • 团队模板：bound_skills 字段存储成员列表（如 dev_team.yaml 列出 tech_lead、frontend_engineer、backend_engineer、qa_engineer、code_reviewer）
  • 所有 Pydantic 模型使用 model_config = ConfigDict(...) 而非 class Config
  • 测试文件：tests/unit/ 和 tests/integration/
  • 前端 stores：Pinia，每个领域一个（chat、team、settings）
  • 前端组件：src/agentkit/server/frontend/src/components/
  • 知识库：docs/solutions/ — 已记录的问题解决方案（bug 修复、最佳实践、架构模式），按类别组织，YAML frontmatter 可搜索（module、tags、problem_type）。在已记录的领域内实现或调试时相关。
  • 领域词汇：CONCEPTS.md — 项目共享领域词汇表（实体、命名流程、状态概念），在熟悉代码库或讨论领域概念时相关。

边界

  • 未经明确请求不得修改 pyproject.toml 版本
  • 禁止直接推送到 main — 使用 feature 分支
  • 集成测试需要 Docker（Redis + PostgreSQL）
  • 桌面端构建需要 Rust 工具链 + PyInstaller