# PMFlow 三引擎统一方案（v2）

## 1. 目标
- 用 3 个引擎达到“质量/成本/稳定性”平衡。
- 飞书与内置 AI 管家使用同一智能链路，避免 IQ 不一致。
- 所有系统操作（不止创建需求）由 AI 覆盖，但写库/副作用必须可控可审计。
- 消除多控制面冲突（PMFlow 配一套、PMFlow 本地路由层 配一套、规则文件又一套）。

## 2. 先把名词说清楚
当前不是“3 个 agent”，而是：
- 2 个 agent
  - PMFlow Orchestrator Agent：流程编排与执行（唯一执行入口）。
  - PMFlow 本地路由层 Reasoning Agent：模型网关与推理。
- 3 个引擎（模型层）
  - Engine-L（Low）：低成本/低延迟，处理执行态与轻分类。
  - Engine-H（High）：高推理，处理复杂问答/规划。
  - Engine-S（Safety）：兜底引擎，处理故障与降级。

## 3. 单一控制面原则（必须）
只保留一个“模型真相源（Source of Truth）”：
- 推荐：PMFlow 本地路由层 作为唯一模型控制面（模型、fallback、配额、可用性）。
- PMFlow 只做函数路由和执行状态机，不再直连多个云厂商。

> 结论：PMFlow 不再同时保存 GLM/OpenAI/DeepSeek 直连 key 参与主路由；
> PMFlow 统一走 PMFlow 本地路由层 网关。

## 4. 三引擎职责分配（推荐）
- Engine-L：`zai/glm-4-flash`
  - 场景：执行态分类、信号抽取、简短回执、轻量意图识别。
- Engine-H：`openai-compatible/GLM-5`
  - 场景：复杂问答、多约束规划、任务编排、项目方案生成。
- Engine-S：`deepseek/deepseek-chat`（或你可用的稳定备份模型）
  - 场景：H 不可用/超时/限流后的稳定兜底。

## 5. 路由矩阵（按 function_name）
### 5.1 走 Engine-L
- `feishu_level_classification`
- `feishu_signal_extraction`
- `rag_intent_classification`
- `classify_intent`
- `feishu_humanized_reply`（仅咨询态；执行态优先模板）

### 5.2 走 Engine-H
- `adaptive_rag_answer`
- `feishu_project_prefill`
- `feishu_task_orchestration`
- `generate_task_breakdown`
- `generate_charter_from_signal`
- `decompose_tasks_from_charter`
- `recommend_assignees_for_task`
- `evaluate_model_requirement`
- `calculate_alignment_score`
- `detect_cognitive_conflicts`
- `rag_db_project_semantic_retrieval`
- `workload_optimize_prompt`
- `analyze_cost_roi`

### 5.3 走 Engine-S（故障兜底）
- 触发条件：`Engine-L/H` 超时、5xx、限流、空响应、无效结构化输出。
- 行为：单次兜底重试 + 记录 `routing_decision=fallback_safety_engine`。

## 6. “低阶答不上来 -> 高阶接管”硬规则
已建议启用：
- 对低阶函数结果做“不可答”检测（如“信息不足/无法回答/不知道”）。
- 命中后自动升级到 High-tier 再请求 1 次。
- 若 High-tier 也失败，最后走 Safety-tier。

优先级链：
`Engine-L -> Engine-H -> Engine-S -> 固定降级模板`

## 7. 飞书与内置 AI 管家一致性
两入口统一走同一条链路：
- `RECEIVED -> CLASSIFIED -> ROUTED -> COMMITTED -> REPLIED`
- 执行态：禁自由文本，固定模板。
- 咨询态：允许文本回答，但同样走统一路由与审计。

这样飞书和内置管家不会再出现“一个聪明一个笨”的模型漂移。

## 8. 全功能 AI 操作覆盖（不止建需求）
建立 `Operation Catalog`，每个操作都必须有：
- `operation_code`
- `input_schema`（Pydantic strict）
- `rbac_policy`
- `idempotency_key`
- `audit_fields`
- `side_effect_guard`

覆盖范围：
- 项目：create/update/archive/reopen
- 任务：create/update/assign/prioritize/status_transition/delete
- 人员：role/workload/availability
- 知识库：doc/chunk/link/reindex
- 通知：create/ack/close
- 文件：白名单路径写入（禁止任意路径）

注意：LLM 只产出结构化意图；真正写库必须由 Tool 层执行。

## 9. 推荐配置模板

### 9.1 PMFlow `.env`（统一走 PMFlow 本地路由层）
```env
LLM_PROVIDER=openai
OPENAI_BASE_URL=http://control-plane:18789/v1
OPENAI_API_KEY=<CONTROL_PLANE_GATEWAY_TOKEN>

CONTROL_PLANE_ROUTING_ENABLED=true
CONTROL_PLANE_ROUTING_RULES_PATH=/app/backend/.control_plane/pmflow-routing-rules.json

LLM_MIXED_ROUTING_ENABLED=false
LLM_LOW_TO_HIGH_ESCALATION_ENABLED=true
```

### 9.2 PMFlow 本地路由层 Agent（main）
- Primary model：`zai/glm-4-flash`（Engine-L）
- Fallbacks：`openai-compatible/GLM-5,deepseek/deepseek-chat`

> 如果你要严格“低->高->安全”，可在 PMFlow 本地路由层 路由中按函数直接指定模型，fallback 只做同层灾备。

### 9.3 PMFlow 路由规则（关键）
- 同一文件统一管理：`backend/.control_plane/pmflow-routing-rules.json`
- 生产发布必须过 lint + replay gate。

## 10. 安全边界（必须守）
- 执行态不允许自由文本动作建议驱动写库。
- 所有写操作必须经过 schema 校验；失败直接模板降级，不猜测。
- 事务与副作用解耦：先 commit，再 outbox 回复。
- 每条请求全链路 trace：可追溯“模型选择 -> 操作执行 -> 回执结果”。

## 11. 落地步骤（按优先级）
1. 统一控制面：PMFlow 改为只调用 PMFlow 本地路由层 网关。
2. 清理直连模型 key 的主路径，仅保留应急开关。
3. 完整补齐 function_name 路由矩阵（L/H/S）。
4. 启用低阶失败自动升级高阶（已具备，可保持开启）。
5. 扩展 Operation Catalog 覆盖全系统操作。
6. 回放测试扩展到“多操作写库场景”。

## 12. 验收标准
- 飞书与内置管家：同问题同输入，模型决策一致（允许渠道文案差异，不允许能力差异）。
- 执行态回复无“教程/curl”污染。
- 回放集通过率 100%，且 `DB + route_status + reply_text` 一致。
- 任一引擎故障时，系统可自动降级不中断主流程。