# AI 管家主干系统开发清单（执行版）

> 目标：把 AI 管家从“补丁式问答”升级为“项目认知系统智能体”。
> 规则：完成一项即勾选。

## Phase 0：基础就绪

- [x] Docker 开发态热部署启用（`docker-compose.dev.yml` + `./start.sh`）
- [x] 双引擎能力打通（`GLM` 主路由 + `Ollama` 回退）
- [x] 运行态健康检查脚本就绪（`scripts/docker_stack.sh`）

## Phase 1：Project Knowledge Graph（唯一真相层）

- [x] 新增图谱实体表：`kg_entities`
- [x] 新增图谱关系表：`kg_relations`
- [x] 新增图谱证据表：`kg_evidences`
- [x] 新增增量事件表：`ingest_events`
- [x] 新增同步偏移表：`ingest_offsets`
- [x] 模型接入 `Base` 元数据（应用启动可自动建表）
- [x] Alembic 迁移脚本：`add_project_knowledge_graph_tables`
- [x] 图谱服务骨架：`ProjectKnowledgeGraphService`
- [x] 结构化同步能力（project/task/signal/user -> 图谱）
- [x] 代码扫描快照能力（backend 代码指标 -> 图谱）
- [x] 图谱概览统计能力（entity/relation/evidence/event）
- [x] 管理 API：`/ai-steward/knowledge-graph/*`

## Phase 2：持续学习管线（增量）

- [x] DB 增量同步游标（按 `updated_at` 与 `ingest_offsets` 断点续传）
- [x] 飞书增量事件入队（`ingest_events` 幂等去重）
- [x] 失败重试与死信策略（`retry_count` + 状态流转）
- [x] 定时任务接入 scheduler（自动跑 structured/code/feishu sync）

## Phase 3：会话语义状态机

- [x] 新增 `qa_session_state` 表（`last_subject/intent/ambiguity`）
- [x] 追问改写统一迁移到状态机（替代散落规则）
- [x] 澄清问句机制（无实体时先澄清再检索）
- [x] 状态回放调试接口

## Phase 4：双引擎执行器标准化

- [x] QueryType 分类器（`count/list/status/explain/unknown`）
- [x] 确定性执行器优先（SQL/Graph）
- [x] LLM 仅负责解释层
- [x] 输出 schema 统一：`answer/evidence/confidence/missing_fields/query_type`

## Phase 5：发布门禁评测

- [x] 50-100 条金标准问答集（含追问链）
- [x] 自动评测脚本（准确率/幻觉率/追问命中率）
- [x] CI 门禁阈值与阻断策略
- [x] 评测报告归档与版本对比

## Phase 6：长期机制运营化（可观测 + 强制门禁）

- [x] 新增同步运行日志表：`kg_sync_runs`
- [x] 增量任务全链路运行打点（`run_id/run_status/stage_errors/duration_ms`）
- [x] 同步运行查询 API：`/ai-steward/knowledge-graph/sync-runs`
- [x] 同步 SLO API：`/ai-steward/knowledge-graph/sync-slo`
- [x] Scheduler 与手动触发写入 `trigger_source`（区分 system/scheduler/manual）
- [x] 增加 followup smoke 门禁脚本：`scripts/rag_followup_smoke.sh`
- [x] CI 门禁加入 followup smoke（与 golden eval 并行阻断）
- [x] 修复飞书队列时区比较异常（避免 `timestamp` aware/naive 导致 500）

## 本轮执行回填

- [x] 完成 Phase 1 全部骨架与接口
- [x] 代码完成静态编译检查与容器热更新加载
- [x] 烟测完成：
  - `sync_structured_entities(limit=200)` 可执行（当前样本库返回 0 条）
  - `sync_codebase_snapshot('/app/backend')` 可执行
  - `get_overview()` 可返回总量统计
- [x] Phase 2 增量流水线：新增 `/ai-steward/knowledge-graph/sync/incremental`、`/sync/feishu`、`/events/process`，并接入 `KnowledgeGraphIncrementalScheduler`
- [x] Phase 3 会话状态机：接入 `qa_session_states`、追问改写、缺主语澄清、调试接口 `/rag/qa-sessions/{session_id}/state`
- [x] Phase 4 双引擎标准化：新增 QueryType 分类、count/list/status 确定性执行、标准响应字段 `answer/evidence/confidence/missing_fields/query_type`
- [x] Phase 5 评测门禁：新增 `backend/evals/golden_qa_v1.jsonl`、`scripts/ai_steward_eval.py`、`.github/workflows/ai-steward-eval-gate.yml`、报告对比脚本
- [x] Phase 6 运营化：新增 `kg_sync_runs`、SLO 可观测接口、followup smoke 强制门禁
- [x] 2026-03-02 执行验证：
  - `POST /ai-steward/knowledge-graph/sync/incremental` 成功（`run_id=7`，`run_status=success`）
  - `GET /ai-steward/knowledge-graph/sync-runs?limit=3` 可返回最近运行记录
  - `GET /ai-steward/knowledge-graph/sync-slo?lookback_hours=24` 可返回 SLO 指标（`success_rate=1.0`）
  - `bash scripts/rag_followup_smoke.sh` 通过
  - `python3 scripts/ai_steward_eval.py --lint-only --input backend/evals/golden_qa_v1.jsonl` 通过（55 条）