ZhiWeave（知织）

从教材 PDF 到可审核、可追溯、可导出 Obsidian 的知识网络。

ZhiWeave 面向需要把教材变成长期知识资产的学习者、教师与内容整理者。它不追求一次生成一张“漂亮大图”，而是把教材拆成可回到原页、可人工否决、可版本化发布的知识节点和关系。

当前状态：MVP 纵切。现阶段已经实现 PDF 入库、分页文本、目录提取、内容哈希去重、教材库与审核工作区外壳。AI 知识卡片、关系生成、人工审核持久化和 Obsidian 导出尚未实现。

产品闭环

教材 PDF
  -> PDF 提取
  -> 章节结构分析
  -> 原子知识卡片
  -> 知识关联构建
  -> 人工审核与版本发布
  -> Obsidian Vault 导出

每个获准发布的知识节点都应回答三个问题：它是什么、来自教材哪一页、为什么与另一个节点有关。

当前 MVP

已实现	尚未实现
文本型 PDF 上传与格式校验	OCR 与扫描教材文字识别
SHA-256 内容寻址和重复上传去重	大文件流式上传与后台任务队列
PyMuPDF 分页文本提取	AI 原子知识卡片生成
PDF 书签目录提取	章节树人工修订
扫描件/低文本量显式标记	关系候选生成与审核事件持久化
教材列表、详情和指定页 API	图谱版本发布与 Obsidian ZIP
React 教材库与审核工作区原型	学习路径、复习调度、跨教材问答

“待 OCR”是受控停止状态，不会调用模型猜测空白页面。当前演示应使用带可检索文本层的 PDF。

技术轮廓

• 后端：Python、FastAPI、Pydantic、PyMuPDF、文件工件存储。
• 前端：React 19、TypeScript、Vite、原生 CSS。
• 数据：按源 PDF SHA-256 内容寻址；原件、分页文本和清单均保存在本机。
• 当前不需要：FFmpeg、Whisper、Redis、Celery、向量数据库、图数据库、Docker 或 GPU。

详细设计见 架构说明，分阶段验收门见 路线图。

快速开始

要求：Python 3.11+、Node.js 20.19.x 或 22.12+、npm 10+、PowerShell 7+。

1. 后端

从仓库根目录执行：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r .\backend\requirements.txt

$env:ZHIWEAVE_DATA_DIR = (Join-Path (Resolve-Path .\backend) 'data')
.\.venv\Scripts\python.exe .\backend\main.py

默认地址：

API:     http://127.0.0.1:8001/api
OpenAPI: http://127.0.0.1:8001/docs
健康:    http://127.0.0.1:8001/api/sys_health

2. 前端

另开一个 PowerShell 终端：

Set-Location .\web
npm install
$env:VITE_API_BASE_URL = 'http://127.0.0.1:8001/api'
npm run dev

打开 http://127.0.0.1:5173/。

3. API 冒烟检查

$Api = 'http://127.0.0.1:8001/api'
Invoke-RestMethod "$Api/sys_check"
Invoke-RestMethod "$Api/textbooks"

$Pdf = Get-Item 'C:\path\to\textbook.pdf'
$Created = Invoke-RestMethod -Method Post -Uri "$Api/textbooks" -Form @{
  file = $Pdf
  title = '测试教材'
  subject = '数学'
  grade = '高中'
}

$TextbookId = $Created.data.textbook.id
Invoke-RestMethod "$Api/textbooks/$TextbookId"
Invoke-RestMethod "$Api/textbooks/$TextbookId/pages/1"

测试

后端：

$PytestTemp = Join-Path $env:TEMP 'zhiweave-pytest'
.\.venv\Scripts\python.exe -m pip install -r .\backend\requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -c .\backend\pytest.ini .\backend\tests -q --basetemp $PytestTemp

前端：

Set-Location .\web
npm run typecheck
npm run build
npm run sizecheck

sizecheck 将首屏 JavaScript 与 CSS 的合计体积限制在 150 KiB gzip；后续图谱渲染只能按需加载，不能重新塞回首屏。

本地数据

默认工件目录是 backend/data/，可通过 ZHIWEAVE_DATA_DIR 覆盖。该目录包含用户上传的教材，不应提交到 Git，也不应在日志或公开演示包中泄露。

环境变量	默认值	说明
ZHIWEAVE_HOST	127.0.0.1	后端监听地址
ZHIWEAVE_PORT	8001	后端监听端口
ZHIWEAVE_DATA_DIR	backend/data	源 PDF 和工件目录
ZHIWEAVE_MAX_UPLOAD_BYTES	134217728	单个 PDF 上限，即 128 MiB
VITE_API_BASE_URL	/api	Web API 基址；开发代理默认指向 8001

backend/data/textbooks/<source_sha256>/
├── source.pdf
├── manifest.json
├── pages/0001.json
└── graphs/              # 首个图版本发布时按需创建

项目边界

• 首期只验证一本教材的两个章节，优先高中数学、文本型 PDF。
• 生成结果在人工审核前只能称为“候选”，不能称为正确知识。
• 教材页码与原文是主证据；联网搜索不是首期真值来源。
• 图谱采用有限节点/关系词表和局部学习路径，不追求全书力导向“毛线团”。

开源与来源

ZhiWeave 使用 MIT License。初始工程纵切借鉴并包含来自 seintbe/reelmind 的 MIT 授权思路或代码，原始版权归 Jeffery Huang 所有；完整归属见 LICENSE。ZhiWeave 是独立项目，ReelMind 仅表示代码来源，不是当前产品品牌。