PMFlow/mdproject/ai-steward-mainline-plan-zh.md

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

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

Phase 0：基础就绪

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

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

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

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

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

Phase 3：会话语义状态机

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

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

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

Phase 5：发布门禁评测

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

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

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

本轮执行回填

• 完成 Phase 1 全部骨架与接口
• 代码完成静态编译检查与容器热更新加载
• 烟测完成：
  • sync_structured_entities(limit=200) 可执行（当前样本库返回 0 条）
  • sync_codebase_snapshot('/app/backend') 可执行
  • get_overview() 可返回总量统计
• Phase 2 增量流水线：新增 /ai-steward/knowledge-graph/sync/incremental、/sync/feishu、/events/process，并接入 KnowledgeGraphIncrementalScheduler
• Phase 3 会话状态机：接入 qa_session_states、追问改写、缺主语澄清、调试接口 /rag/qa-sessions/{session_id}/state
• Phase 4 双引擎标准化：新增 QueryType 分类、count/list/status 确定性执行、标准响应字段 answer/evidence/confidence/missing_fields/query_type
• Phase 5 评测门禁：新增 backend/evals/golden_qa_v1.jsonl、scripts/ai_steward_eval.py、.github/workflows/ai-steward-eval-gate.yml、报告对比脚本
• Phase 6 运营化：新增 kg_sync_runs、SLO 可观测接口、followup smoke 强制门禁
• 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 条）