diff --git a/frontend-web/docs/product-knowledge-base-dev.md b/frontend-web/docs/product-knowledge-base-dev.md
new file mode 100644
index 00000000..be287bfc
--- /dev/null
+++ b/frontend-web/docs/product-knowledge-base-dev.md
@@ -0,0 +1,1243 @@
+# 产品内知识库沉淀系统开发文档
+
+## 1. 背景
+
+当前项目是一个 DeerFlow 定制化离线部署系统，包含：
+
+- 前端：`frontend-web/`，Vite + React 19 + TypeScript。
+- 后端：`offline-backend-20260512/backend/`，FastAPI Gateway + LangGraph agent runtime。
+- 现有能力：对话线程、工具搜索、引用来源、Markdown 渲染、外部知识库 iframe 页面。
+
+本需求希望将“每次问答、搜索、工具调用、生成报告”等高价值内容自动或手动沉淀为产品内知识库，并在后续问答中可被检索和召回。
+
+本方案以 `ar9av/obsidian-wiki` 为底层知识组织规范：优先复用它的 vault 目录结构、Markdown frontmatter、`index.md`、`log.md`、`hot.md`、`.manifest.json`、wikilink、`wiki-capture`、`wiki-query`、`wiki-export`、`graph-colorize` 等原生技能/页面产物。产品侧负责把这些能力封装成后端 API 和 React 页面。
+
+## 2. 目标
+
+实现一套产品内知识库系统：
+
+1. 支持从单次对话线程沉淀知识。
+2. 支持从搜索结果、工具调用结果沉淀知识。
+3. 支持自动抽取摘要、标签、实体、来源、关键结论。
+4. 支持知识列表、详情、搜索、编辑、删除。
+5. 支持保存 Obsidian 兼容 Markdown 文件。
+6. 支持后续问答时召回相关知识，并显示引用来源。
+7. 首版支持知识图谱页面，后续可增强实体关系抽取、自动去重、知识合并。
+
+## 3. 首版交付范围
+
+首版必须实现：
+
+- 产品内知识库页面：列表、详情、搜索、编辑、删除/归档。
+- 产品内 Markdown 编辑体验：支持编辑正文、预览 Markdown、编辑标题/标签/状态/来源信息。
+- 当前对话沉淀：在聊天线程页面点击“保存到知识库”，生成 obsidian-wiki 兼容 Markdown 笔记。
+- 历史线程批量入库：提供后台接口和前端入口，可批量扫描已有线程并沉淀为知识库内容。
+- 搜索和工具结果沉淀：保存 query、结果标题、摘要、URL、工具名等来源信息。
+- 全局共享知识库：所有用户共用同一套 vault 和数据库索引，不按用户隔离。
+- 审计记录：写入、更新、删除记录 `created_by` / `updated_by`，用于追踪操作来源。
+- Obsidian 兼容 vault：后端自行维护 `index.md`、`log.md`、`hot.md`、`.manifest.json`、wikilinks 和 frontmatter。
+- 图谱页面：后端自行生成 `wiki-export/graph.html` 和 `graph.json`，前端直接 iframe 展示 `graph.html`。
+- 不安装、不调用 `obsidian-wiki` CLI。
+- 知识库功能由新增 `knowledge` 模块独立实现。
+
+首版暂缓实现：
+
+- 精确复刻 Obsidian 桌面端所有交互细节。
+- 图数据库服务。首版图谱用 Markdown wikilinks + `graph.json` / `graph.html` 实现，不额外引入图数据库中间件。
+- 向量 RAG 自动注入。首版先完成知识沉淀、管理、关键词搜索和图谱，向量召回后续增强。
+
+## 4. 总体架构
+
+数据流：
+
+```text
+用户问答 / 搜索 / 工具调用 / 生成文档
+        ↓
+Knowledge Event 采集
+        ↓
+Obsidian Wiki Adapter
+按 obsidian-wiki 原生技能规范抽取、分类、写入 vault
+        ↓
+三类存储
+1. Markdown Vault：obsidian-wiki 原生目录、frontmatter、wikilinks
+2. 数据库：产品检索、列表、来源映射、创建/修改审计
+3. 向量索引：语义检索和 RAG 召回
+        ↓
+前端知识库页面
+列表、搜索、详情、来源、编辑、图谱
+        ↓
+后续问答自动召回相关知识
+```
+
+推荐新增后端模块：
+
+```text
+offline-backend-20260512/backend/app/gateway/routers/knowledge.py
+offline-backend-20260512/backend/packages/harness/deerflow/knowledge/
+```
+
+推荐新增前端模块：
+
+```text
+frontend-web/src/core/knowledge/
+frontend-web/src/pages/KnowledgeBasePage.tsx
+frontend-web/src/components/knowledge/
+```
+
+## 4.1 obsidian-wiki 原生复用策略
+
+必须优先复用 `obsidian-wiki` 的原生约定，而不是另起一套知识库格式。
+
+### 4.1.1 复用对象
+
+从 `ar9av/obsidian-wiki` 复用以下内容：
+
+- `.skills/wiki-capture/SKILL.md`
+  - 用作“对话沉淀为知识笔记”的抽取和写作模板。
+  - 关键要求：写成 declarative knowledge，不保存聊天流水账。
+
+- `.skills/wiki-query/SKILL.md`
+  - 用作知识检索策略参考。
+  - 关键要求：先读 `hot.md` / `index.md` / frontmatter，再逐步升级到正文。
+
+- `.skills/wiki-export/SKILL.md`
+  - 用作知识图谱导出规范。
+  - 复用输出：`wiki-export/graph.json`、`graph.graphml`、`cypher.txt`、`graph.html`。
+
+- `.skills/graph-colorize/SKILL.md`
+  - 后续用于 Obsidian graph 配色。
+
+- `.skills/wiki-status/SKILL.md`
+  - 后续用于知识库状态、孤立页面、delta 分析。
+
+- `.skills/cross-linker/SKILL.md`
+  - 后续用于自动补充 wikilinks。
+
+- `.skills/wiki-dedup/SKILL.md`
+  - 后续用于重复知识合并。
+
+- vault 文件：
+  - `index.md`
+  - `log.md`
+  - `hot.md`
+  - `.manifest.json`
+  - `_insights.md`
+  - `_meta/taxonomy.md`
+
+### 4.1.2 产品封装原则
+
+产品后端新增 `ObsidianWikiAdapter`，负责：
+
+- 初始化 vault。
+- 调用或模拟 `wiki-capture` 的写入流程。
+- 写入 `index.md`、`log.md`、`hot.md`。
+- 维护 `.manifest.json`。
+- 按 `wiki-export` 规范生成 `wiki-export/graph.html/json`。
+- 将 vault 页面同步到产品数据库索引。
+
+前端不直接依赖 obsidian-wiki 技能文件。前端只调用 `/api/knowledge/*`。
+
+### 4.1.3 调用方式优先级
+
+优先级如下：
+
+1. 运行时不使用 `obsidian-wiki` CLI。
+2. 后端内置 obsidian-wiki 兼容实现，输出必须兼容 obsidian-wiki vault。
+3. 后端自行初始化 vault、写入 Markdown、维护 `index.md` / `log.md` / `hot.md` / `.manifest.json`。
+4. 后端自行按 `wiki-export` 规范生成 `wiki-export/graph.html` / `graph.json`。
+5. 对 `wiki-export/graph.html` 这类原生产物，优先直接作为静态页面 iframe 到产品内。
+6. 对 Markdown 笔记列表、详情、编辑，使用产品自研 React 页面读取同一个 vault。
+
+## 5. 与现有系统的关系
+
+可复用现有能力：
+
+- `app/gateway/routers/threads.py`
+  - `GET /api/threads/{thread_id}/state` 可读取线程 messages。
+  - `GET /api/threads/{thread_id}/reference-batches` 可读取工具搜索/引用来源。
+
+- 前端 Markdown 能力
+  - `frontend-web/src/strategy-components/MarkdownRenderer.tsx`
+  - `frontend-web/src/core/threads/export.ts`
+
+- 现有知识库入口
+  - `frontend-web/src/strategy-components/components/resource-management/KnowledgeBaseResourceManagement.tsx`
+  - 当前是 iframe，后续可替换为原生知识库管理页面。
+
+必须复用/兼容的外部项目能力：
+
+- `git-clone/obsidian-wiki/.skills/wiki-capture/SKILL.md`
+- `git-clone/obsidian-wiki/.skills/wiki-query/SKILL.md`
+- `git-clone/obsidian-wiki/.skills/wiki-export/SKILL.md`
+- `git-clone/obsidian-wiki/.skills/wiki-status/SKILL.md`
+- `git-clone/obsidian-wiki/.skills/wiki-dedup/SKILL.md`
+- `git-clone/obsidian-wiki/.skills/cross-linker/SKILL.md`
+
+## 6. 分阶段实现
+
+### 阶段一：首版完整交付
+
+目标：交付可用的产品内共享知识库。用户可以手动沉淀当前对话，也可以批量沉淀历史线程；所有知识写入同一套 obsidian-wiki 兼容 vault，并在产品内完成浏览、搜索、编辑、删除和图谱查看。
+
+范围：
+
+- 新增知识笔记数据库表。
+- 新增 `ObsidianWikiAdapter`。
+- 新增 obsidian-wiki 兼容 Markdown vault 写入能力。
+- 初始化并维护 `index.md`、`log.md`、`hot.md`、`.manifest.json`。
+- 新增 `POST /api/knowledge/ingest/thread/{thread_id}`。
+- 新增 `POST /api/knowledge/ingest/threads/batch`，支持批量扫描并沉淀历史线程。
+- 新增 `POST /api/knowledge/ingest/search`，支持搜索和工具结果来源沉淀。
+- 新增 `GET /api/knowledge/notes`。
+- 新增 `GET /api/knowledge/notes/{note_id}`。
+- 新增 `PUT /api/knowledge/notes/{note_id}`。
+- 新增 `DELETE /api/knowledge/notes/{note_id}`。
+- 新增 `POST /api/knowledge/search`，首版支持关键词/frontmatter/Markdown 内容检索。
+- 新增 `POST /api/knowledge/export/graph`，生成 `wiki-export/graph.html` 和 `graph.json`。
+- 前端新增“保存到知识库”按钮。
+- 前端新增“批量导入历史线程”入口。
+- 前端新增知识库列表、详情、编辑、搜索、删除/归档页面。
+- 前端新增图谱页面，iframe 展示 `wiki-export/graph.html`。
+- 知识库全局共享，不按用户隔离。
+
+阶段一暂缓：
+
+- 向量检索。
+- 自动合并重复知识。
+- agent 回答前的向量 RAG 自动注入。
+
+### 阶段二：向量检索和 RAG 召回
+
+目标：用户后续提问时，自动检索知识库并注入 agent 上下文。
+
+范围：
+
+- 先实现 obsidian-wiki 原生 `wiki-query` 风格的分层检索：
+  - `hot.md`
+  - `index.md`
+  - frontmatter
+  - 相关正文片段
+- 新增 Markdown 分块。
+- 新增 embedding 生成与索引。
+- 新增 `POST /api/knowledge/search`。
+- 在 agent 调用前执行知识召回。
+- 回答中展示引用的知识笔记和来源。
+
+### 阶段三：自动沉淀和知识治理
+
+目标：聊天完成后自动判断是否值得沉淀，并支持去重、合并、编辑审核。
+
+范围：
+
+- 后台任务队列。
+- 价值判断：是否值得入库。
+- 重复检测。
+- 版本记录。
+- 合并建议。
+- 敏感信息过滤。
+- 审核状态：draft、approved、archived。
+
+### 阶段四：图谱增强
+
+目标：在首版 `graph.html` / `graph.json` 基础上增强实体、关系和交互能力。
+
+范围：
+
+- 优先复用 obsidian-wiki `wiki-export` 输出。
+- 直接生成/服务 `wiki-export/graph.html` 作为第一版图谱页面。
+- 读取 `wiki-export/graph.json` 给产品自研图谱组件使用。
+- 后续再做实体抽取、关系抽取和自定义图谱。
+- `GET /api/knowledge/graph`。
+- 前端图谱页面。
+
+## 7. 数据库设计
+
+首版可使用当前项目已有数据库体系。字段名建议使用 snake_case。
+
+### 7.1 knowledge_notes
+
+知识笔记主表。
+
+```sql
+CREATE TABLE knowledge_notes (
+  id VARCHAR(64) PRIMARY KEY,
+  title VARCHAR(512) NOT NULL,
+  summary TEXT,
+  content_md LONGTEXT NOT NULL,
+  vault_path VARCHAR(1024),
+  source_type VARCHAR(64) NOT NULL,
+  source_id VARCHAR(256),
+  status VARCHAR(32) NOT NULL DEFAULT 'approved',
+  confidence FLOAT DEFAULT 0,
+  created_by VARCHAR(128),
+  updated_by VARCHAR(128),
+  created_at DATETIME NOT NULL,
+  updated_at DATETIME NOT NULL
+);
+```
+
+`source_type` 可选：
+
+- `thread`
+- `search`
+- `tool`
+- `file`
+- `manual`
+- `report`
+
+`status` 可选：
+
+- `draft`
+- `approved`
+- `archived`
+
+### 7.2 knowledge_sources
+
+知识来源表。
+
+```sql
+CREATE TABLE knowledge_sources (
+  id VARCHAR(64) PRIMARY KEY,
+  note_id VARCHAR(64) NOT NULL,
+  source_type VARCHAR(64) NOT NULL,
+  thread_id VARCHAR(128),
+  message_id VARCHAR(128),
+  tool_name VARCHAR(128),
+  title VARCHAR(512),
+  url TEXT,
+  snippet TEXT,
+  raw_json LONGTEXT,
+  created_by VARCHAR(128),
+  created_at DATETIME NOT NULL
+);
+```
+
+### 7.3 knowledge_tags
+
+```sql
+CREATE TABLE knowledge_tags (
+  id VARCHAR(64) PRIMARY KEY,
+  name VARCHAR(128) NOT NULL,
+  created_at DATETIME NOT NULL
+);
+```
+
+### 7.4 knowledge_note_tags
+
+```sql
+CREATE TABLE knowledge_note_tags (
+  note_id VARCHAR(64) NOT NULL,
+  tag_id VARCHAR(64) NOT NULL,
+  PRIMARY KEY (note_id, tag_id)
+);
+```
+
+### 7.5 knowledge_entities
+
+阶段五使用。
+
+```sql
+CREATE TABLE knowledge_entities (
+  id VARCHAR(64) PRIMARY KEY,
+  name VARCHAR(256) NOT NULL,
+  entity_type VARCHAR(64),
+  created_at DATETIME NOT NULL
+);
+```
+
+### 7.6 knowledge_relations
+
+阶段五使用。
+
+```sql
+CREATE TABLE knowledge_relations (
+  id VARCHAR(64) PRIMARY KEY,
+  from_note_id VARCHAR(64),
+  to_note_id VARCHAR(64),
+  from_entity_id VARCHAR(64),
+  to_entity_id VARCHAR(64),
+  relation_type VARCHAR(128) NOT NULL,
+  weight FLOAT DEFAULT 1,
+  created_at DATETIME NOT NULL
+);
+```
+
+### 7.7 knowledge_embeddings
+
+阶段三使用。如果使用外部向量库，此表只保存索引映射。
+
+```sql
+CREATE TABLE knowledge_embeddings (
+  id VARCHAR(64) PRIMARY KEY,
+  note_id VARCHAR(64) NOT NULL,
+  chunk_index INT NOT NULL,
+  content TEXT NOT NULL,
+  vector_id VARCHAR(256),
+  created_at DATETIME NOT NULL
+);
+```
+
+## 8. Markdown Vault 设计
+
+默认存储路径：
+
+```text
+offline-backend-20260512/backend/data/knowledge/obsidian-vault/
+```
+
+也可以通过配置项指定：
+
+```yaml
+knowledge:
+  enabled: true
+  provider: obsidian_wiki
+  vault_dir: data/knowledge/obsidian-vault
+  auto_ingest_enabled: false
+  max_thread_messages: 80
+```
+
+必须兼容 obsidian-wiki 原生结构：
+
+```text
+vault/
+  index.md
+  log.md
+  hot.md
+  .manifest.json
+  _meta/
+    taxonomy.md
+  concepts/
+  entities/
+  skills/
+  references/
+  synthesis/
+  journal/
+  projects/
+    deerflow/
+      concepts/
+      references/
+      synthesis/
+      journal/
+  wiki-export/
+    graph.json
+    graph.graphml
+    cypher.txt
+    graph.html
+```
+
+页面分类遵循 `wiki-capture`：
+
+- `synthesis`：多步骤分析、方案、结论。
+- `concepts`：概念、框架、模型。
+- `references`：外部来源、搜索结果、文章资料。
+- `synthesis` decision 类型：架构或设计决策。
+- `journal`：完整会话摘要。
+- `projects/<project-name>/...`：项目相关知识优先进入项目空间。
+
+Markdown frontmatter 必须优先兼容 `wiki-capture`：
+
+```markdown
+---
+title: >-
+  知识标题
+category: synthesis
+tags: [deerflow, knowledge-base, agent]
+sources:
+  - conversation:2026-06-08
+  - thread:thread_id
+  - message:message_id
+created: 2026-06-08T15:30:00+08:00
+updated: 2026-06-08T15:30:00+08:00
+summary: >-
+  一到两句话说明这页知识保存了什么。
+provenance:
+  extracted: 0.7
+  inferred: 0.2
+  ambiguous: 0.1
+base_confidence: 0.82
+lifecycle: draft
+lifecycle_changed: 2026-06-08
+relationships:
+  - target: "[[concepts/knowledge-graph]]"
+    type: uses
+---
+
+# 知识标题
+
+## Context
+
+问题背景或触发场景。
+
+## Finding / Decision
+
+沉淀后的知识本体。不要写成“用户问了什么，AI 回答了什么”的聊天摘要。
+
+## Reasoning
+
+为什么成立、取舍是什么、不确定性在哪里。推断内容使用 `^[inferred]` 标记。
+
+## Implications
+
+后续使用建议、风险、下一步。
+
+## Related
+
+- [[concepts/knowledge-graph]]
+- [[projects/deerflow/synthesis/product-knowledge-base]]
+```
+
+写入任何页面后必须同步：
+
+- `index.md`：加入页面索引。
+- `log.md`：追加 `CAPTURE` / `INGEST` / `QUERY` / `EXPORT` 记录。
+- `hot.md`：更新近期活动摘要。
+- `.manifest.json`：记录 source、hash、vault path、更新时间，用于去重和 delta。
+
+## 9. 后端接口设计
+
+统一前缀：
+
+```text
+/api/knowledge
+```
+
+### 9.1 从线程沉淀知识
+
+```http
+POST /api/knowledge/ingest/thread/{thread_id}
+```
+
+请求：
+
+```json
+{
+  "mode": "summary",
+  "title": "",
+  "status": "approved",
+  "tags": ["DeerFlow"],
+  "include_sources": true
+}
+```
+
+字段说明：
+
+- `mode`: `summary` 或 `full`
+- `title`: 可选，空时自动生成
+- `status`: `draft` 或 `approved`
+- `tags`: 用户手动附加标签
+- `include_sources`: 是否解析工具/搜索来源
+
+响应：
+
+```json
+{
+  "note": {
+    "id": "kb_xxx",
+    "title": "多智能体任务调度方案",
+    "summary": "...",
+    "source_type": "thread",
+    "source_id": "thread_id",
+    "vault_path": "threads/2026/06/xxx.md",
+    "created_at": "2026-06-08T15:30:00+08:00"
+  }
+}
+```
+
+### 9.2 批量沉淀历史线程
+
+```http
+POST /api/knowledge/ingest/threads/batch
+```
+
+请求：
+
+```json
+{
+  "limit": 100,
+  "offset": 0,
+  "status": "approved",
+  "include_sources": true,
+  "skip_existing": true
+}
+```
+
+字段说明：
+
+- `limit`: 本次最多处理多少个线程。
+- `offset`: 线程分页偏移。
+- `status`: 生成知识的默认状态。
+- `include_sources`: 是否解析工具/搜索来源。
+- `skip_existing`: 是否根据 `.manifest.json` / source hash 跳过已沉淀线程。
+
+响应：
+
+```json
+{
+  "ok": true,
+  "processed": 80,
+  "created": 52,
+  "skipped": 28,
+  "failed": 0,
+  "items": [
+    {
+      "thread_id": "thread_id",
+      "note_id": "kb_xxx",
+      "status": "created"
+    }
+  ]
+}
+```
+
+### 9.3 从搜索结果沉淀知识
+
+```http
+POST /api/knowledge/ingest/search
+```
+
+请求：
+
+```json
+{
+  "query": "LangGraph checkpoint",
+  "results": [
+    {
+      "title": "Example",
+      "url": "https://example.com",
+      "snippet": "..."
+    }
+  ],
+  "thread_id": "optional_thread_id",
+  "message_id": "optional_message_id"
+}
+```
+
+### 9.4 手动创建知识
+
+```http
+POST /api/knowledge/notes
+```
+
+请求：
+
+```json
+{
+  "title": "知识标题",
+  "content_md": "# 知识标题\n\n正文",
+  "tags": ["业务"],
+  "status": "approved"
+}
+```
+
+### 9.5 知识列表
+
+```http
+GET /api/knowledge/notes?keyword=&tag=&source_type=&status=&limit=20&offset=0
+```
+
+响应：
+
+```json
+{
+  "items": [
+    {
+      "id": "kb_xxx",
+      "title": "知识标题",
+      "summary": "摘要",
+      "tags": ["DeerFlow"],
+      "source_type": "thread",
+      "source_id": "thread_id",
+      "updated_at": "2026-06-08T15:30:00+08:00"
+    }
+  ],
+  "total": 1
+}
+```
+
+### 9.6 知识详情
+
+```http
+GET /api/knowledge/notes/{note_id}
+```
+
+响应：
+
+```json
+{
+  "id": "kb_xxx",
+  "title": "知识标题",
+  "summary": "摘要",
+  "content_md": "# 知识标题...",
+  "tags": ["DeerFlow"],
+  "sources": [
+    {
+      "id": "src_xxx",
+      "source_type": "thread",
+      "thread_id": "thread_id",
+      "message_id": "message_id",
+      "title": "来源标题",
+      "url": "https://example.com",
+      "snippet": "..."
+    }
+  ]
+}
+```
+
+### 9.7 更新知识
+
+```http
+PUT /api/knowledge/notes/{note_id}
+```
+
+请求：
+
+```json
+{
+  "title": "新标题",
+  "content_md": "# 新内容",
+  "tags": ["新标签"],
+  "status": "approved"
+}
+```
+
+### 9.8 删除知识
+
+```http
+DELETE /api/knowledge/notes/{note_id}
+```
+
+建议默认软删除：设置 `status = archived`。
+
+### 9.9 知识搜索
+
+阶段三实现。
+
+```http
+POST /api/knowledge/search
+```
+
+请求：
+
+```json
+{
+  "query": "如何做多智能体调度",
+  "mode": "hybrid",
+  "limit": 8
+}
+```
+
+`mode` 可选：
+
+- `keyword`
+- `vector`
+- `hybrid`
+
+响应：
+
+```json
+{
+  "items": [
+    {
+      "note_id": "kb_xxx",
+      "chunk_id": "chunk_xxx",
+      "title": "多智能体任务调度方案",
+      "snippet": "相关片段",
+      "score": 0.87,
+      "sources": []
+    }
+  ]
+}
+```
+
+### 9.10 知识图谱
+
+阶段五实现。
+
+```http
+GET /api/knowledge/graph?keyword=&limit=100
+```
+
+响应：
+
+```json
+{
+  "nodes": [
+    {
+      "id": "kb_xxx",
+      "type": "note",
+      "label": "知识标题"
+    }
+  ],
+  "edges": [
+    {
+      "id": "rel_xxx",
+      "source": "kb_a",
+      "target": "kb_b",
+      "label": "related",
+      "weight": 1
+    }
+  ]
+}
+```
+
+### 9.11 Export Obsidian Wiki Graph
+
+First implementation should reuse obsidian-wiki `wiki-export` compatible output.
+
+```http
+POST /api/knowledge/export/graph
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "files": {
+    "graph_json": "/api/knowledge/export/files/graph.json",
+    "graph_html": "/api/knowledge/export/files/graph.html",
+    "graph_graphml": "/api/knowledge/export/files/graph.graphml",
+    "cypher": "/api/knowledge/export/files/cypher.txt"
+  },
+  "stats": {
+    "nodes": 12,
+    "edges": 18
+  }
+}
+```
+
+### 9.12 Serve Obsidian Wiki Export Files
+
+```http
+GET /api/knowledge/export/files/{filename}
+```
+
+Allowed files:
+
+- `graph.json`
+- `graph.graphml`
+- `cypher.txt`
+- `graph.html`
+
+Frontend graph page first version:
+
+```text
+iframe src="/api/knowledge/export/files/graph.html"
+```
+
+## 10. 后端服务设计
+
+建议拆分：
+
+```text
+deerflow/knowledge/
+  __init__.py
+  models.py
+  repository.py
+  obsidian_adapter.py
+  skill_templates.py
+  markdown_vault.py
+  extractor.py
+  sources.py
+  manifest.py
+  exporter.py
+  chunking.py
+  embeddings.py
+  search.py
+```
+
+职责：
+
+- `models.py`
+  - Pydantic/领域模型。
+
+- `repository.py`
+  - 数据库读写。
+  - 不直接调用 LLM。
+
+- `obsidian_adapter.py`
+  - 核心适配器。
+  - 对外提供 `capture_thread`、`capture_search`、`list_notes`、`read_note`、`update_note`、`export_graph`。
+  - 输出必须兼容 obsidian-wiki vault。
+
+- `skill_templates.py`
+  - 读取或内置 `wiki-capture`、`wiki-query`、`wiki-export` 的关键模板。
+  - 后端 LLM 抽取 prompt 应以这些技能为准。
+
+- `markdown_vault.py`
+  - 负责生成 obsidian-wiki 兼容 frontmatter。
+  - 负责安全文件名。
+  - 负责写入/更新 Markdown 文件。
+  - 负责 wikilink 解析和基础 frontmatter 解析。
+
+- `extractor.py`
+  - 负责从 thread/search/tool 中抽取知识。
+  - 首版可用规则生成摘要，正式版可调用 LLM。
+  - LLM 输出必须映射为 `wiki-capture` 的类型：synthesis、concept、source、decision、session。
+
+- `sources.py`
+  - 负责归一化来源。
+  - 复用 `threads.py` 里的 reference normalize 逻辑时，建议抽公共函数，避免复制大段代码。
+
+- `manifest.py`
+  - 读写 `.manifest.json`。
+  - 记录 source hash，避免重复沉淀。
+
+- `exporter.py`
+  - 内置实现 obsidian-wiki `wiki-export` 等价逻辑。
+  - 生成 `wiki-export/graph.json` 和 `wiki-export/graph.html`。
+  - 前端图谱优先 iframe `graph.html`。
+
+- `chunking.py`
+  - Markdown 分块。
+
+- `embeddings.py`
+  - embedding 生成和索引写入。
+
+- `search.py`
+  - 关键词、向量、混合搜索。
+
+## 11. 知识抽取策略
+
+抽取策略必须优先遵循 obsidian-wiki 的 `wiki-capture`：
+
+- 保存知识本体，不保存聊天流水账。
+- 使用 declarative knowledge，不写“用户问了什么，AI 回答了什么”。
+- 明确分类为 `synthesis`、`concept`、`source`、`decision`、`session`。
+- 项目相关内容写入 `projects/<project-name>/...`。
+- 推断内容使用 `^[inferred]`。
+- 不确定或冲突内容使用 `^[ambiguous]`。
+- 每篇笔记尽量包含至少 2 个 `[[wikilinks]]`。
+
+从线程抽取时，只保留高价值内容：
+
+- 用户明确提问。
+- 助手最终回答。
+- 工具搜索结果。
+- 被引用的来源。
+- 生成的结论、方案、计划、代码设计。
+
+过滤：
+
+- 空消息。
+- 纯寒暄。
+- 中间推理内容。
+- 重复 token 流。
+- 错误堆栈中无价值的噪声。
+- 过长原文全文。
+
+首版规则：
+
+1. 读取 thread state 的 `messages`。
+2. 按 human 消息切分 turn。
+3. 找每个 turn 的最后一个有正文的 ai 消息。
+4. 拼成沉淀上下文。
+5. 自动生成标题：
+   - 优先使用 thread title。
+   - 没有 title 时使用第一条用户问题的前 40 字。
+6. 自动生成 summary：
+   - 首版可截取或简单规则总结。
+   - 正式版用 LLM 生成结构化 JSON。
+
+LLM 抽取推荐输出：
+
+```json
+{
+  "title": "知识标题",
+  "summary": "摘要",
+  "key_points": ["要点一", "要点二"],
+  "actions": ["建议一"],
+  "tags": ["标签"],
+  "entities": [
+    {"name": "LangGraph", "type": "technology"}
+  ],
+  "relations": [
+    {"from": "LangGraph", "to": "checkpoint", "type": "uses"}
+  ],
+  "confidence": 0.82,
+  "should_ingest": true,
+  "reason": "包含可复用架构决策"
+}
+```
+
+## 12. 前端页面设计
+
+### 12.1 路由
+
+新增路由建议：
+
+```text
+/page/knowledge
+/page/knowledge/:noteId
+```
+
+如果必须放在工作台内，可放：
+
+```text
+/page/workspace/knowledge
+```
+
+### 12.2 页面结构
+
+知识库主页面：
+
+```text
+顶部工具栏
+- 搜索框
+- 来源类型筛选
+- 标签筛选
+- 新建知识按钮
+
+左侧/主区域
+- 知识列表
+- 标题
+- 摘要
+- 标签
+- 来源类型
+- 更新时间
+
+右侧/详情区域
+- Markdown 内容
+- 来源列表
+- 编辑按钮
+- 删除/归档按钮
+```
+
+### 12.3 对话页入口
+
+在聊天线程页面增加按钮：
+
+```text
+保存到知识库
+```
+
+交互：
+
+1. 用户点击按钮。
+2. 弹窗展示：
+   - 标题输入框。
+   - 标签输入。
+   - 状态：草稿/正式。
+   - 是否包含搜索来源。
+3. 调用 `POST /api/knowledge/ingest/thread/{thread_id}`。
+4. 成功后 toast 提示。
+5. 可点击进入知识详情。
+
+### 12.4 知识详情页
+
+功能：
+
+- Markdown 渲染。
+- 显示 frontmatter 中的标签、来源、更新时间。
+- 来源区支持跳转：
+  - thread 来源跳回原对话。
+  - url 来源打开外链。
+- 编辑模式：
+  - 标题。
+  - Markdown 内容。
+  - 标签。
+  - 状态。
+
+## 13. RAG 召回接入
+
+阶段二再做，不建议首版强行接入。
+
+召回策略优先复用 obsidian-wiki `wiki-query` 的分层检索，而不是直接上向量库：
+
+1. 读取 `hot.md`，获取近期知识上下文。
+2. 读取 `index.md`，用标题、摘要、标签筛候选页面。
+3. 扫描 frontmatter：`title`、`tags`、`aliases`、`summary`、`tier`。
+4. 只读取候选页面相关片段。
+5. 必要时才读取全文。
+6. 向量检索作为增强，不作为首个唯一检索方式。
+
+推荐接入点：
+
+1. 用户发送问题。
+2. 后端进入 agent 运行前。
+3. 调用 `KnowledgeSearchService.search(query, limit=5)`。
+4. 将搜索结果转换为系统上下文：
+
+```text
+以下是产品知识库中与本问题相关的资料。回答时优先参考，若使用其中信息，请在回答中标注来源。
+
+[知识 1] 标题
+摘要/片段
+来源：note_id / url
+```
+
+注意：
+
+- 不要注入过多内容，建议限制 3-5 条。
+- 每条只注入 snippet，不要注入整篇 Markdown。
+- 必须携带来源 id，方便前端引用展示。
+- 知识库为全局共享，检索所有已批准的公共知识。
+
+## 14. 权限与安全
+
+必须实现：
+
+- 知识库为全局共享，不按用户隔离。
+- 所有用户读取同一套 vault 和知识索引。
+- 写入、更新、删除操作记录 `created_by` / `updated_by`，用于审计。
+- Markdown 文件路径必须防止路径穿越。
+- 文件名必须 sanitize。
+- 删除默认软删除。
+
+建议实现：
+
+- 自动沉淀前做敏感信息检测。
+- 对 token、密钥、手机号、身份证等内容做脱敏。
+- 提供“不要沉淀本次对话”的用户开关。
+
+## 15. 配置项
+
+建议在 `config.yaml` 中新增：
+
+```yaml
+knowledge:
+  enabled: true
+  provider: obsidian_wiki
+  vault_dir: data/knowledge/obsidian-vault
+  project_name: deerflow
+  auto_ingest_enabled: false
+  auto_ingest_min_chars: 300
+  max_thread_messages: 80
+  max_source_items: 20
+  export:
+    enabled: true
+    graph_html_enabled: true
+    graph_json_enabled: true
+  rag_enabled: false
+  rag_limit: 5
+  query:
+    use_hot_md: true
+    use_index_md: true
+    use_frontmatter_scan: true
+  embedding:
+    enabled: false
+    provider: local
+    model: ""
+```
+
+## 16. 验收标准
+
+阶段一验收：
+
+- 可以从一个已有 thread 生成知识笔记。
+- 可以批量扫描历史线程并生成知识笔记。
+- 搜索结果/工具结果能作为 sources 保存。
+- 数据库中存在 `knowledge_notes` 记录。
+- vault 中生成 Markdown 文件。
+- `index.md`、`log.md`、`hot.md`、`.manifest.json` 会同步更新。
+- 前端可以看到知识列表。
+- 前端可以查看知识详情。
+- 前端可以编辑标题、标签、状态和 Markdown 正文。
+- 前端可以关键词搜索知识。
+- 前端可以删除/归档知识。
+- 前端可以打开图谱页面，iframe 展示 `wiki-export/graph.html`。
+- 所有用户都能看到已批准的全局知识。
+- 删除知识后列表不再显示。
+
+阶段二验收：
+
+- `POST /api/knowledge/search` 能返回相关知识。
+- agent 回答能使用知识库内容。
+- 回答中能显示知识来源。
+
+阶段三验收：
+
+- 可配置自动沉淀开关。
+- 自动沉淀不会保存明显无价值寒暄。
+- 重复内容不会无限新增。
+- 用户可编辑和归档自动沉淀的知识。
+
+## 17. 推荐开发顺序
+
+1. 创建后端数据模型和 repository。
+2. 创建 `ObsidianWikiAdapter`，初始化 obsidian-wiki 兼容 vault。
+3. 创建 Markdown vault 写入工具，同步 `index.md`、`log.md`、`hot.md`、`.manifest.json`。
+4. 实现 `POST /api/knowledge/ingest/thread/{thread_id}`。
+5. 实现 `POST /api/knowledge/ingest/threads/batch`。
+6. 实现 `POST /api/knowledge/ingest/search`。
+7. 实现 `GET /api/knowledge/notes` 和详情接口。
+8. 实现 `PUT /api/knowledge/notes/{note_id}` 和 `DELETE /api/knowledge/notes/{note_id}`。
+9. 实现 `POST /api/knowledge/search` 的关键词/frontmatter/Markdown 内容检索。
+10. 增加 `POST /api/knowledge/export/graph`，生成并服务 `wiki-export/graph.html`。
+11. 前端创建 `core/knowledge/api.ts`。
+12. 前端实现知识列表、详情、编辑、搜索、图谱页面。
+13. 对话页增加“保存到知识库”按钮。
+14. 前端增加“批量导入历史线程”入口。
+15. 补充基础测试。
+16. 再进入向量 RAG、自动沉淀、自动合并阶段。
+
+## 18. 测试建议
+
+后端测试：
+
+- 从 thread state 生成知识。
+- 批量历史线程入库。
+- 搜索/工具来源入库。
+- 空 thread 返回合理错误。
+- 任意可读取的 thread 都可沉淀到全局知识库；需要按现有 thread 权限判断是否可读取来源。
+- Markdown 文件路径安全。
+- 知识列表分页正确。
+- 更新知识同步更新 vault 文件。
+- 删除知识为软删除。
+
+前端测试：
+
+- 知识列表加载态、空态、错误态。
+- 搜索和筛选。
+- 详情 Markdown 渲染。
+- 知识编辑和保存。
+- 图谱 iframe 页面。
+- 批量导入历史线程入口。
+- 保存到知识库弹窗。
+- 保存成功后跳转详情。
+
+手动测试：
+
+1. 新建一轮对话。
+2. 点击保存到知识库。
+3. 打开知识库页面。
+4. 查看生成的知识笔记。
+5. 编辑标题和内容。
+6. 批量导入历史线程。
+7. 打开图谱页面。
+8. 删除或归档知识。
+
+## 19. 给开发模型的任务提示词
+
+可将下面提示词交给其他模型：
+
+```text
+请基于 frontend-web/docs/product-knowledge-base-dev.md 实现阶段一：首版完整交付。
+
+要求：
+1. 后端新增 /api/knowledge 相关接口。
+2. 从 /api/threads/{thread_id}/state 读取 messages，生成知识笔记。
+3. 新增独立 knowledge 模块，知识库相关能力都在该模块内实现。
+4. 新增 ObsidianWikiAdapter，复用 ar9av/obsidian-wiki 的原生规范和技能思路。
+5. 将知识元数据写入数据库，将 content_md 写入 obsidian-wiki 兼容 Markdown vault。
+6. 写入后必须同步 index.md、log.md、hot.md、.manifest.json。
+7. Markdown frontmatter 和正文结构参考 obsidian-wiki 的 wiki-capture 技能。
+8. 前端新增知识库列表、详情、编辑、搜索、图谱页面。
+9. 在聊天线程页面增加“保存到知识库”入口。
+10. 增加批量导入历史线程入口。
+11. 知识库为全局共享，不做 user_id 隔离；写入时记录 created_by / updated_by 作为审计。
+12. 图谱第一版生成并服务 wiki-export 兼容的 graph.html/json。
+13. 首版实现关键词/frontmatter/Markdown 内容搜索；向量 RAG 后续增强。
+14. 遵循当前项目已有 FastAPI、SQLAlchemy、React、TanStack Query、UI 组件风格。
+15. 完成后运行后端相关测试和前端 typecheck/build。
+```
+
+## 20. 风险与注意事项
+
+- 知识库模块独立实现，相关能力都收敛在新增 `knowledge` 模块内。
+- 不要另起一套与 obsidian-wiki 不兼容的 Markdown 结构。
+- 不要忽略 `index.md`、`log.md`、`hot.md`、`.manifest.json`，这些是 obsidian-wiki 的关键原生资产。
+- 不要让前端直接读服务器 Markdown 文件，应通过 API。
+- 不要同步阻塞聊天流式响应，自动沉淀应后台执行。
+- 不要保存完整工具 raw_json 到前端展示，详情页只展示必要字段。
+- 不要把所有搜索结果无脑入库，应先关联来源，再由知识笔记引用。
+- 首版不额外引入图数据库中间件，图谱优先使用 `wiki-export/graph.html` 和 `graph.json`。