M2-06 Artifact & KnowledgeItem 基础版 #26

New Issue

wangdl · 2026-05-22T21:09:50+08:00

wangdl commented

2026-05-22 21:09:50 +08:00

目标

设计知习学习工件与知识点模块，负责从解析后的资料中生成候选知识点（ImportCandidate），用户确认后转为正式知识点（KnowledgeItem），并预留 learnable 标识供 M3 LearningSession 引用。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

资料进入知习后不是直接变成学习内容，而是先由 AI 从 Material 的 chunks 中抽取候选知识点（ImportCandidate），用户在界面上审阅、编辑、确认或拒绝。确认后的知识点成为 KnowledgeItem，作为后续学习（LearningSession）和复习（ReviewCard）的基础。

本阶段只做 Candidate + Item + Citation，不做全量的 Quiz/StudyGuide/PracticeTest 生成（留到 M3）。

模块职责

本模块负责：
- ImportCandidate 生成（基于 Material 的 chunks + AI Gateway）
- KnowledgeItem 管理（确认/编辑/拒绝/批量操作）
- SourceReference 绑定（每个知识点关联到具体的 Material 来源位置）
- 预留 learnable 标识（供 M3 LearningSession 判断哪些 KnowledgeItem 可以用于学习）
- Artifact 基础模型（为后续 FlashcardSet/Quiz/StudyGuide 预留基类）
本模块不负责：
- 全量学习工件生成（FlashcardSet/Quiz/PracticeTest/StudyGuide 留到 M3）
- 学习会话和主动回忆（走 Learning Engine）
- 复习调度（走 Review Engine）
- Material 的解析和索引（走 Ingestion）

候选数据对象

ImportCandidate（候选知识点）
KnowledgeItem（正式知识点）
Artifact（工件基类，预留扩展）
ArtifactItem（工件条目基类）
GenerationJob（AI 生成任务）

预留扩展（M3 阶段使用）

FlashcardItem extends ArtifactItem
QuestionItem extends ArtifactItem
StudyGuideBlock extends ArtifactItem
所有 KnowledgeItem 需有 learnable 字段（boolean），供 M3 判断是否可用于学习

基础设施依赖判断

MySQL：是
Redis：否
BullMQ：是（AI 批量生成 Candidate 异步执行）
Qdrant：否
AI Gateway：是（生成 Candidate 时调用 LLM）
Content Safety：是（生成的内容需要审核）
Cost：是（AI 调用消耗）

API 设计

CAPI：
- 触发 Candidate 生成（按 Material/Source）
- Candidate 列表（按状态/知识库筛选）
- 确认/编辑/拒绝 Candidate
- KnowledgeItem CRUD
- KnowledgeItem 列表和搜索
AAPI：
- Candidate 质量巡检
- KnowledgeItem 全量查询

Domain Event 设计

ImportCandidateGenerated
KnowledgeItemAccepted
KnowledgeItemRejected
KnowledgeItemUpdated

交付检查

路由归属：CAPI + AAPI
是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：否
是否需要 BullMQ：是
是否需要 Qdrant：否
是否需要 AI Gateway：是
是否需要 Content Safety：是
是否需要 Cost 记录：是
是否需要 AuditLog：否
是否需要 Domain Event：是
是否需要 Admin 视图：是

验收标准

ImportCandidate / KnowledgeItem / Artifact Prisma schema
Candidate AI 生成方案（Prompt 设计 + 批量生成流水线）
Candidate → KnowledgeItem 确认流程设计
SourceReference 绑定方案
learnable 字段预留方案
Admin 候选知识点质量巡检视图设计
集成测试覆盖生成和确认流程

禁止事项

禁止在 M2 做全量 Quiz/StudyGuide/PracticeTest 生成
禁止 Candidate 自动变为 KnowledgeItem（必须用户确认）
禁止 KnowledgeItem 不关联 SourceReference
禁止 AI 生成内容不经过 Content Safety 直接入库

不建议当前阶段实现

FlashcardSet / Quiz / PracticeTest / StudyGuide
知识点自动标签和分类
知识点之间的关联图谱
知识点难度自动评估

## 目标设计知习学习工件与知识点模块，负责从解析后的资料中生成候选知识点（ImportCandidate），用户确认后转为正式知识点（KnowledgeItem），并预留 learnable 标识供 M3 LearningSession 引用。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明资料进入知习后不是直接变成学习内容，而是先由 AI 从 Material 的 chunks 中抽取候选知识点（ImportCandidate），用户在界面上审阅、编辑、确认或拒绝。确认后的知识点成为 KnowledgeItem，作为后续学习（LearningSession）和复习（ReviewCard）的基础。本阶段只做 Candidate + Item + Citation，不做全量的 Quiz/StudyGuide/PracticeTest 生成（留到 M3）。 ## 模块职责 1. 本模块负责： - ImportCandidate 生成（基于 Material 的 chunks + AI Gateway） - KnowledgeItem 管理（确认/编辑/拒绝/批量操作） - SourceReference 绑定（每个知识点关联到具体的 Material 来源位置） - 预留 learnable 标识（供 M3 LearningSession 判断哪些 KnowledgeItem 可以用于学习） - Artifact 基础模型（为后续 FlashcardSet/Quiz/StudyGuide 预留基类） 2. 本模块不负责： - 全量学习工件生成（FlashcardSet/Quiz/PracticeTest/StudyGuide 留到 M3） - 学习会话和主动回忆（走 Learning Engine） - 复习调度（走 Review Engine） - Material 的解析和索引（走 Ingestion） ## 候选数据对象 - ImportCandidate（候选知识点） - KnowledgeItem（正式知识点） - Artifact（工件基类，预留扩展） - ArtifactItem（工件条目基类） - GenerationJob（AI 生成任务） ## 预留扩展（M3 阶段使用） - FlashcardItem extends ArtifactItem - QuestionItem extends ArtifactItem - StudyGuideBlock extends ArtifactItem - 所有 KnowledgeItem 需有 learnable 字段（boolean），供 M3 判断是否可用于学习 ## 基础设施依赖判断 - MySQL：是 - Redis：否 - BullMQ：是（AI 批量生成 Candidate 异步执行） - Qdrant：否 - AI Gateway：是（生成 Candidate 时调用 LLM） - Content Safety：是（生成的内容需要审核） - Cost：是（AI 调用消耗） ## API 设计 1. CAPI： - 触发 Candidate 生成（按 Material/Source） - Candidate 列表（按状态/知识库筛选） - 确认/编辑/拒绝 Candidate - KnowledgeItem CRUD - KnowledgeItem 列表和搜索 2. AAPI： - Candidate 质量巡检 - KnowledgeItem 全量查询 ## Domain Event 设计 - ImportCandidateGenerated - KnowledgeItemAccepted - KnowledgeItemRejected - KnowledgeItemUpdated ## 交付检查 - [x] 路由归属：CAPI + AAPI - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否 - [x] 是否需要 BullMQ：是 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：是 - [x] 是否需要 Content Safety：是 - [x] 是否需要 Cost 记录：是 - [x] 是否需要 AuditLog：否 - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是 ## 验收标准 1. ImportCandidate / KnowledgeItem / Artifact Prisma schema 2. Candidate AI 生成方案（Prompt 设计 + 批量生成流水线） 3. Candidate → KnowledgeItem 确认流程设计 4. SourceReference 绑定方案 5. learnable 字段预留方案 6. Admin 候选知识点质量巡检视图设计 7. 集成测试覆盖生成和确认流程 ## 禁止事项 - 禁止在 M2 做全量 Quiz/StudyGuide/PracticeTest 生成 - 禁止 Candidate 自动变为 KnowledgeItem（必须用户确认） - 禁止 KnowledgeItem 不关联 SourceReference - 禁止 AI 生成内容不经过 Content Safety 直接入库 ## 不建议当前阶段实现 - FlashcardSet / Quiz / PracticeTest / StudyGuide - 知识点自动标签和分类 - 知识点之间的关联图谱 - 知识点难度自动评估

wangdl added this to the M2：知识库主链路闭环（P1） milestone 2026-05-22 21:09:50 +08:00

wangdl self-assigned this 2026-05-22 21:09:50 +08:00

wangdl commented

2026-05-24 13:34:39 +08:00

✅ M2-06 实施完成

关键发现

KnowledgeItem 和 ImportCandidate 模型已有完整的字段设计（title/content/summary/sourceRef/confidence/difficulty/status）。本 Issue 补充了预留扩展能力。

交付内容

模块	说明
`Artifact` 模型	工件基类（type/title/configJson），为 M3 FlashcardSet/Quiz/StudyGuide 预留
`KnowledgeItem.learnable`	boolean 字段（默认 true），供 M3 LearningSession 判断是否可用于学习
Admin AAPI	`GET /admin-api/knowledge-bases/candidates` 候选列表、`GET .../items` 知识点列表

运行

npx jest --config ./test/jest-e2e.json  # all passing

## ✅ M2-06 实施完成 ### 关键发现 `KnowledgeItem` 和 `ImportCandidate` 模型已有完整的字段设计（title/content/summary/sourceRef/confidence/difficulty/status）。本 Issue 补充了预留扩展能力。 ### 交付内容 | 模块 | 说明 | |------|------| | `Artifact` 模型 | 工件基类（type/title/configJson），为 M3 FlashcardSet/Quiz/StudyGuide 预留 | | `KnowledgeItem.learnable` | boolean 字段（默认 true），供 M3 LearningSession 判断是否可用于学习 | | Admin AAPI | `GET /admin-api/knowledge-bases/candidates` 候选列表、`GET .../items` 知识点列表 | ### 运行 ```bash npx jest --config ./test/jest-e2e.json # all passing ```

wangdl commented

2026-05-24 13:59:13 +08:00

🔧 审计修复 — 2026-05-24

问题: Candidate 生成/确认时未接入 Content Safety 审核。

修复: ImportCandidateService.accept() 和 createCandidates() 新增 ContentSafetyService.check() 调用。审核不通过时拒绝确认（返回 BLOCKED），创建时过滤不安全候选。

Commit: 3c242a8

## 🔧 审计修复 — 2026-05-24 **问题**: Candidate 生成/确认时未接入 Content Safety 审核。 **修复**: `ImportCandidateService.accept()` 和 `createCandidates()` 新增 `ContentSafetyService.check()` 调用。审核不通过时拒绝确认（返回 `BLOCKED`），创建时过滤不安全候选。 **Commit**: `3c242a8`

wangdl closed this issue

2026-06-06 14:43:15 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#26