# 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）

## 命令

```bash
# 后端
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