# AI 数据飞轮 开发 TODO

更新时间：2026-07-03

文档路径：document/development/2026-07-03/feature/ai-data-flywheel/TODO.md

## 使用规则

- 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力、方案或验收点。
- 只有完成并验证后，才能把 `[ ]` 改成 `[x]`。
- 勾选时在任务后补充简短证据，例如文件、接口、命令或验证结果。
- 如果需求发生变化，先更新 `CONCEPT.md`，再调整本 TODO。
- 实施顺序建议：阶段 1 → 2 → 3（飞轮 1+2 是地基）→ 4/5/6 并行 → 7。

## 1. 调研与边界

- [x] [CONCEPT: 背景与问题] 盘点现有 accumulator / feedback / RAG / 规则生成能力，确认飞轮骨架已存在、断点在"检索注入 + 评测门禁"。
  证据：`server/src/app/skills/domain/{false-positive-sample-accumulator,risk-feedback-sample-accumulator,risk-clue-collector}`、`services/agent_feedback.py`、`services/knowledge_rag_runtime.py`、`services/risk_rule_generation*.py`。
- [x] [CONCEPT: 目标与非目标] 确认本轮范围 = 飞轮 1-6（few-shot 注入 / golden set 门禁 / prompt 版本化 / 抽取修正回流 / 低分归因 / 智商看板），不做模型微调、不改业务接口契约。
  证据：CONCEPT.md「目标与非目标」章节。
- [ ] [CONCEPT: 风险与开放问题] 与业务确认 Canary 流量比例、智商看板菜单位置、政策新鲜度检测是否本轮接入。
  证据：

## 2. 契约与设计

- [ ] [CONCEPT: 功能能力] 定义 4 张新表的字段、状态枚举（prompt stable/canary/pinned/archived、golden draft/confirmed/deprecated、eval pass/fail/blocked、correction）。
  证据：
- [ ] [CONCEPT: 方案设计] 明确 5 个新 service 的职责边界与 inject 钩子点（risk_rule_generation_prompt / user_agent_application / expense_claim_pre_review / document_intelligence_rules / ontology_extraction）。
  证据：
- [ ] [CONCEPT: 算法与公式] 确认 few-shot 检索排序公式权重（默认 α=0.8 β=0.2）与门禁阈值（recall 不降、f1 下降 ≤ 2pp）。
  证据：
- [ ] [CONCEPT: 指标与验收] 把验收点 A1-A5 转成可验证检查项，附命令与期望结果。
  证据：

## 3. 后端实现

- [x] [CONCEPT: 后端] 新增 `services/few_shot_retrieval.py`：复用 Qdrant，按 case 特征检索 top-k confirmed 样本，带 token 预算裁剪。
  证据：`server/src/app/services/few_shot_retrieval.py`；`server/src/app/services/few_shot_store.py`（独立 Qdrant collection `few_shot_samples`）；`server/src/app/services/embedding_provider.py`（公共 EmbeddingProvider，复用 knowledge_rag_runtime 的 HTTP 调用）。
- [ ] [CONCEPT: 后端] 新增 `services/prompt_registry.py`：prompt 版本 CRUD + 策略取版（latest/canary/pinned）+ 回退硬编码。
  证据：飞轮 3（prompt 版本化 + Canary）未启动，本轮只做飞轮 1。
- [ ] [CONCEPT: 后端] 新增 `services/eval_harness.py`：在 golden set 上跑评测，输出 precision/recall/f1，供门禁与看板共用。
  证据：飞轮 2（golden set + 门禁）未启动，本轮只做飞轮 1。
- [ ] [CONCEPT: 后端] 新增 `services/feedback_attribution.py`：低分反馈触发，复用 AgentTraceCenter trace 做归因，输出错误环节标签 + 改进任务。
  证据：飞轮 5（低分归因）未启动，本轮只做飞轮 1。
- [ ] [CONCEPT: 后端] 新增 `services/extraction_correction_recorder.py`：在附件/明细字段更新处记录 raw vs corrected diff。
  证据：飞轮 4（抽取修正回流）未启动，本轮只做飞轮 1。
- [ ] [CONCEPT: 后端] Alembic 迁移：prompt_version / golden_set / extraction_correction / eval_run 四张表。
  证据：本轮新增的是 FewShotSample 一张表（`server/src/app/models/few_shot_sample.py`），项目靠 `Base.metadata.create_all()` 建表（无 alembic versions/ 目录），已注册到 `db/base.py` 和 `models/__init__.py`。其余三表随对应飞轮再建。
- [x] [CONCEPT: 后端] 新增 `services/few_shot_ingestion.py`：RiskObservation confirmed/false_positive → FewShotSample + Qdrant 向量，在 `risk_observations.create_feedback` commit 后 hook 触发。
  证据：`server/src/app/services/few_shot_ingestion.py`；`server/src/app/services/risk_observations.py:324-345`（`_maybe_ingest_few_shot` hook，带 feature flag + try/except 兜底）。
- [x] [CONCEPT: 数据与契约] 在现有 prompt 构造文件加 few-shot 注入，不改业务接口。
  证据：`server/src/app/services/risk_rule_generation_prompt.py`（新增 `few_shot_samples` 可选 kwarg，合并进 examples 字段）；`server/src/app/services/risk_rule_generation.py:271-292`（`_retrieve_few_shot_samples` 在构造 messages 前调用，失败降级为空）。

## 4. 算法/规则实现

- [x] [CONCEPT: 算法与规则] 实现few-shot 检索排序（向量相似度 + 元数据硬匹配），只取 confirmed 样本。
  证据：`server/src/app/services/few_shot_store.py`（Qdrant 余弦相似度 + payload 过滤 scene/label/status）；`few_shot_retrieval.py` 去重 + token 预算 + 单条字符上限裁剪。检索仅取 label ∈ {confirmed, false_positive}。
- [ ] [CONCEPT: 算法与规则] 实现评测指标比对器（风险标记 / 字段值 / 分类标签 三类场景）。
  证据：飞轮 2，未启动。
- [ ] [CONCEPT: 算法与规则] 接入发布门禁：`agent_asset_risk_rule_publish` 前调 eval_harness，不达标 block。
  证据：飞轮 2，未启动。
- [ ] [CONCEPT: 算法与规则] 接入 Canary 流量切分（默认 90 stable / 10 canary）+ 劣化自动回滚。
  证据：飞轮 3，未启动。
- [x] [CONCEPT: 结果解释] few-shot 块在 prompt 中保留 `source: "historical_confirmed"` 标记，可追溯。
  证据：`risk_rule_generation_prompt.py` 合并 examples 时每条历史样本带 `source`/`label`/`conclusion` 字段。

## 5. 前端实现

- [ ] [CONCEPT: 前端] AI 智商看板新页面：准确率/召回率/误报率/人工干预率随时间曲线 + golden set 覆盖度，复用 `finance-report` 看板骨架。
  证据：
- [ ] [CONCEPT: 前端] Canary 控制台（并入 Settings/Policies）：prompt 版本列表、流量比例、分数、一键回滚。
  证据：
- [ ] [CONCEPT: 前端] 实现加载/空态（样本不足）/错误态（评测失败）/权限态（仅算法运营）。
  证据：
- [ ] [CONCEPT: 前端] 对齐现有企业后台风格（参考 `chat-ui-saas-styling` / `theme-settings-enterprise-ai-style`），避免营销页观感。
  证据：

## 6. 测试与验证

- [x] [CONCEPT: 测试方案] 后端单测：embedding_provider（GLM/Ollama 分支、维度缓存、HTTP 错误降级）、few_shot_ingestion（confirmed/false_positive 入库、ignored 跳过、幂等去重、hook 触发、feature flag、吞异常）、few_shot_retrieval（去重、token 预算、超长截断）+ prompt 注入（合并 examples、向后兼容）。
  证据：`server/tests/test_embedding_provider.py`、`server/tests/test_few_shot_ingestion.py`、`server/tests/test_few_shot_retrieval_and_prompt.py`，容器内 `pytest -q` 20 passed。
- [ ] [CONCEPT: 测试方案] 前端：智商看板与 Canary 控制台视图模型 + 构建验证。
  证据：飞轮 3/6 前端，未启动。
- [ ] [CONCEPT: 测试方案] 集成：golden set → 改 prompt → 门禁拦截/通过 → 看板新增数据点，容器内跑通。
  证据：飞轮 2 集成，未启动。
- [x] [CONCEPT: 测试方案] 回归：现有 RAG / risk_observations / risk_rule_generation 测试全过。
  证据：容器内 `pytest -q server/tests/test_risk_observations_service.py server/tests/test_knowledge_rag_runtime.py server/tests/test_risk_rule_generation.py server/tests/test_risk_rule_generation_failure.py` → 35 passed，EmbeddingProvider 抽离零回归。
- [ ] [CONCEPT: 指标与验收] 记录验证命令与结果，确认 P95 检索 ≤ 200ms、单场景评测 ≤ 60s。
  证据：性能指标待飞轮 2 评测上线后连同 golden set 一起量。

## 7. 文档收尾

- [x] [CONCEPT: 指标与验收] 飞轮 1（few-shot 注入）A1 功能验收已达成：推理时 prompt 中可见带 `source: "historical_confirmed"` 的 few-shot 块，且样本来自 confirmed/false_positive 池。A5 可观测性部分达成（可追溯 source）。A2/A3/A4 随飞轮 2/3 补齐。
  证据：见阶段 3/4/6 已勾选项。
- [ ] [CONCEPT: 风险与开放问题] 更新 Canary 比例、看板菜单位置、政策新鲜度检测的最终结论与剩余风险。
  证据：飞轮 2-6 启动后再定稿。
- [x] [CONCEPT: 功能一句话] 确认飞轮 1 实现没有偏离"让系统越用越聪明"的原始目标。
  证据：人工确认风险观测 → 自动入库 + 向量化 → 下次规则编译时检索注入相似历史样本，形成"用得越多 → 样本越丰富 → 推理越准"的闭环。飞轮 2-6 待后续迭代。