# Mounted AI V2 需求规格（直接替换旧链路，多来源架构，Feishu 首验）

## Summary
将现有“飞书旧捕获链路 + consultant 话术层 + 多套 draft/对话脑”升级为一个真正的挂载式 AI runtime。  
目标形态对齐 Codex CLI / OpenClaw：持续镜像上下文、统一主题工作区、明确会话状态、按 agent 编排执行、对外只输出自然短话术。  
本次按**直接替换**设计，不保留长期并行旧方案；架构按**多来源**设计，但首个验收来源只要求 **Feishu**。

默认行为：
- 所有接入来源的消息/事件先被动镜像进系统。
- 只有 `@机器人` 或私聊才触发主动回复。
- 不明确执行就不执行，不明确出草稿就继续聊需求，不明确语义就进入澄清层。
- 对外回复简短自然；对内保留完整状态、上下文切片、agent trace 和执行审计。

## Core Product Behavior
### 会话模式
定义统一 5 态，替代现有分散的 followup / consultant / draft 规则：
- `chat`：普通讨论、看法、开放式交流；不生成草稿，不执行。
- `plan`：在聊需求、收敛范围；每轮最多追一个关键问题，持续维护隐藏需求卡片。
- `clarify`：上下文或指代不足；只问一个最小澄清问题，等待用户继续。
- `draft_ready`：需求完整度达标；仅提示“可以整理成草稿”，需用户确认才真正落草稿。
- `execute`：用户明确要求立项、创建、分配、入库、更新状态等写操作时进入。

### 需求对话规则
- 非明确创建/执行场景，一律优先进入 `plan`，禁止直接甩整套模板。
- “分配给谁更合适”“这个范围太大”“按上面的思路继续”这类回复必须结合当前主题工作区理解，不再按单句路由。
- 草稿不再由一次性长回复触发，而是来自持续收敛后的 `Requirement Workspace`。
- `Requirement Workspace` 至少维护：`facts / goals / constraints / options / open_questions / readiness / recommended_assignees / next_action`。

### Agent 编排
统一由 `Conversation Orchestrator Agent` 负责仲裁，其他 agent 不直接抢主导权：
- `Context Mirror Agent`：镜像所有来源消息与事件，不主动回复。
- `Topic Memory Agent`：维护线程、主题、当日记忆、待确认事项、业务事实快照。
- `Conversation Orchestrator Agent`：输出模式判定、目标主题、上下文切片、下游 agent 选择。
- `Plan Coach Agent`：负责“循循善诱”地聊需求。
- `Clarifier Agent`：负责澄清提问。
- `Draft Synthesizer Agent`：仅在 `draft_ready + 用户确认` 后生成正式草稿。
- `Assignee Recommender Agent`：专门回答负责人推荐。
- `Executor Agent`：唯一允许调用写操作执行器。
- `Reply Composer Agent`：把内部结果转成自然中文短回复。

## Architecture & Interfaces
### 新增运行时抽象
新增 Mounted AI runtime，作为统一入口层，复用现有 work item / executor / 审计能力：
- `Source Envelope`：统一所有来源消息字段，至少包含 `source_system / channel_ref / thread_key / message_id / reply_to / sender / mentions / attachments / timestamp / raw_payload`。
- `Topic Workspace`：统一当前事项状态，替代飞书专属 thread/session 逻辑。
- `Conversation Run`：记录一次触发后的编排过程、上下文切片、模式转换、agent trace、最终回复和执行结果。
- `Context Slice`：将上下文分层组装为 `current_message / thread / active_topic / recent_relevant_context / business_facts / long_term_memory`。
- `Agent Trace`：记录每个 agent 的输入摘要、输出摘要、耗时、失败原因。

### API / Type 变更
新增一组 Mounted AI 运维接口，沿用 `{code, message, data}` 包络：
- `GET /mounted-ai/sources`
  返回来源接入状态、镜像吞吐、最近错误、触发规则。
- `GET /mounted-ai/topics`
  返回活跃主题、当前模式、readiness、待澄清问题、是否可出草稿。
- `GET /mounted-ai/runs`
  返回最近编排运行记录、agent trace、模式切换、上下文层命中。
- `GET /mounted-ai/runs/{id}`
  返回单次运行详情、上下文切片、最终回复、执行/草稿结果。
- `GET /mounted-ai/cutover-status`
  返回旧链路删除进度、当前实际生效入口、Feishu 验证状态。

扩展现有工作项/Inbox 详情接口字段：
- 增加 `topic_id / conversation_mode / readiness_score / active_agent / context_layers_hit / trigger_reason / source_thread_key`。
- 工作项详情增加 `agent_trace_summary / context_slice_summary / replacement_origin`。

### 前端承载
- 将现有 `SchedulerCenter` 升级为 **Mounted AI Console**，作为内部运营/管理员主入口。
- `Inbox` 保留为操作视图，但不承担完整编排拓扑展示，只承接待确认、澄清、执行结果和草稿动作。
- Mounted AI Console 必须可视化：
  - 来源状态：Feishu 长连接、消息镜像、触发/不触发计数。
  - 编排图：各 agent 节点、当前激活节点、最近运行链路。
  - 主题工作区：当前模式、需求收敛状态、readiness、待确认问题。
  - 上下文层：当前消息、线程摘要、主题摘要、业务事实、长期记忆的命中情况。
  - 运行回放：一次触发的 agent trace、模式切换、最终回复、是否落草稿/执行。
  - 删除/替换状态：旧模块退役清单及当前 cutover 生效点。

## Replace / Delete Strategy
本次需求按“直接替换旧链路”写，旧模块分三类处理：

### 必须保留并复用
- `ingest_events / work_items / decision_records / reply_receipts / outbox / 审计 / 租户隔离 / 执行门禁`
- AI PMO kernel 的执行与事实链能力
- 人员能力图谱、负载、负责人推荐的事实数据源

### 合并后只保留一套
- `draft_generator_service` 与 `ai_steward` 中的项目创建草稿链路，合并为统一 `Draft Workspace + Draft Synthesizer`
- 分散的 thread/session/followup 记忆逻辑，合并为统一 `Topic Workspace`
- RAG/context/recent chat 的补上下文逻辑，合并为统一 `Context Slice Assembler`

### 直接退役或降级为适配层
- `signal_capture_service/mixin_capture_legacy.py`
- 以 `feishu_signal_pipeline` 为“业务主脑”的整条语义/回复链；如需复用，仅保留 transport/adapter 能力
- `ai_pmo/consultant_dispatch.py` 及其在回复层的包装逻辑
- 各类统一 ack/fallback/“收到，正在处理”式伪对话层
- legacy command 兼容语义与旧的飞书专属 followup 规则

删除原则：
- 不再允许多个模块分别决定“当前是在聊天、聊需求、出草稿还是执行”
- 不再允许多个模块分别生成 draft、决定 followup、拼接上下文、包装回复

## Feishu Validation & Acceptance
### Feishu 首验范围
只以 Feishu 作为首个生产级验收来源，要求：
- 长连接健康、状态可视化、可重启
- 群聊全量镜像可入库
- 仅 `@机器人` 或私聊触发主动回复
- reply/thread/引用关系能够还原到统一 `Topic Workspace`

### 必测场景
- 群聊 `@机器人` 普通聊天，进入 `chat`
- 群聊 `@机器人` 聊需求，进入 `plan`
- 群聊 thread 中使用“这个/那个/按上面”，能命中当前主题
- 上下文不足时进入 `clarify`
- 需求完整后提示可出草稿，用户确认后才真正生成草稿
- “分配给谁更合适”命中 `Assignee Recommender Agent`
- 明确执行指令才进入 `execute`
- Feishu DM 与群聊行为一致
- 每次触发都能在 Mounted AI Console 回放 agent trace 与模式切换
- Inbox 能正确显示澄清中、草稿待确认、执行中、执行完成

### 验收标准
- 同一条 Feishu 需求对话不再出现“误把追问当执行”的行为
- 非执行场景不再生成整套模板式回复
- 草稿只在 `draft_ready + 用户确认` 后出现
- 控制台能清楚看到当前 active agent、上下文层命中、最终模式和执行结果
- 旧飞书主脑链路被切断，不再作为生产入口生效

## Assumptions
- 替换策略固定为**直接替换**，不设计长期双轨并行。
- 前端可视化主入口固定为 **SchedulerCenter -> Mounted AI Console**，Inbox 只承接操作结果。
- 架构按多来源抽象，但本次只要求 **Feishu 首验**；其它来源不进入本期验收。
- 旧模块删除以“停止作为生产主脑生效”为准；若部分代码临时复用，仅允许作为 adapter/persist helper，不得保留决策权。
- 对外回复风格固定为自然短话术，禁止再以 consultant/fallback 模板充当主交互层。