DocWeave 是一个在 Windows 本机运行的研究报告工作台。用户导入资料并说明写作目标后，系统检索可核对的证据，生成带 PDF 与 LaTeX 源文件包的报告候选；候选经审阅接受后形成新的文档版本。
- 导入 UTF-8 文本、Markdown、CSV、DOCX、XLSX 和文本型 PDF，也可授权本地资料目录。
- 将资料拆分为带文件路径、行号和 SHA-256 的片段，通过 SQLite FTS5 检索，并把选中片段保存为引用证据。
- 使用 LangGraph 组织模型决策与工具调用，图状态保存在独立的 SQLite Checkpoint 数据库中。
- 通过 FastAPI 接收生成与修订任务，以 SSE 返回过程事件；React 界面用于正文、引用和候选审阅。
- 使用独立的 TinyTeX / TeX Live 2026 运行时构建 PDF，记录工具、包与字体身份，并打包 LaTeX 源文件与资源。
- 在同一会话中继续修订已接受版本，保留候选、文档版本和交付文件之间的内容哈希关系。
主工作区使用 SQLite FTS5 检索本地资料。backend/src/docweave/retrieval/ 还提供离线混合检索模块：multilingual-e5-small 负责向量编码，SQLite FTS5 与 LanceDB 分别召回候选，RRF 负责结果融合。
主工作区按空白拆分查询词，所有查询词须在同一资料片段内出现；中文词语及两个汉字支持子串检索。升级已有工作区时，数据库迁移 0019 会自动重建该全文索引。
- Windows 10/11 x64
- PowerShell 7
- Python 3.11 或 3.12
- Node.js 22
- pnpm 11
- TinyTeX v2026.08
在新的 PowerShell 窗口中安装基础工具：
winget install -e --id Microsoft.PowerShell
winget install -e --id astral-sh.uv
winget install -e --id OpenJS.NodeJS.22
winget install -e --id pnpm.pnpm
winget install -e --id GnuPG.GnuPG安装后重新打开 PowerShell，并确认命令可用：
pwsh --version
uv --version
node --version
pnpm --version在仓库根目录执行：
uv python install 3.12
uv sync --locked --group dev --python 3.12
pnpm install --frozen-lockfileDocWeave 使用 TinyTeX v2026.08 的 TinyTeX-1 Windows 基础包。安装器校验该发行包的 SHA-256，在独立暂存目录解包，再从官方 CTAN 仓库安装报告模板需要的 TeX Live 2026 包；tlmgr --verify-repo=all 要求仓库签名验证成功。
仓库签名验证使用原生 Windows GnuPG 2.x（上面的 GnuPG.GnuPG 包）。自定义安装位置可通过 -GpgPath <gpg.exe> 指定。模板使用 Windows 的 SimSun、SimHei 和 Times New Roman。安装前，在“设置 → 可选功能”中确认已安装“中文（简体）补充字体 / Chinese (Simplified) Supplemental Fonts”。安装器会先检查 GnuPG 和所需字体，在首次包更新前确认仓库签名有效，再用实际模板编译包含中文、公式与参考文献的 PDF。
pwsh -NoProfile -File scripts/Install-DocWeaveRuntime.ps1已下载同一官方基础包时，可传入 -ArchivePath <TinyTeX-1-windows-v2026.08.exe> 复用文件；SHA-256 校验仍会执行。
安装成功后，运行时位于 %LOCALAPPDATA%\DocWeave\runtimes\TinyTeX-1-v2026.08。目录中的 installation-source.json 记录基础包来源及仓库，installation-identity.json 记录实际工具版本、已安装包 revision 和字体 SHA-256；smoke/chinese-smoke/main.pdf 是安装验收文件。目标目录已存在时，安装器会停止，可使用下文的 Doctor 检查该运行时。
backend/src/docweave/runtime/tex_runtime_baseline.json 定义受支持年度、工具版本系列与必要包/字体。安装时取得的包 revision 和系统字体版本可以不同，每次 PDF 构建都会记录具体身份；要重现同一安装环境，可保留整个运行时目录及对应字体版本。报告构建过程使用已安装依赖，更新依赖属于显式安装操作。
Poppler 为导出文件的 PDF 页面预览提供 pdftoppm。Markdown、TXT、CSV、DOCX、XLSX 和文本型 PDF 的导入流程可直接使用 Python 依赖；需要页面预览时安装 Poppler：
winget install -e --id oschwartz10612.Poppler
pdftoppm -v扫描型 PDF 请先完成 OCR，再作为文本资料导入。
AI 写作使用 DeepSeek API。密钥放在当前 PowerShell 会话中：
$env:DEEPSEEK_API_KEY = "你的密钥"直接运行 ASGI 服务时，也可以复制 .env.example 为 .env 并填写本地配置。
检查依赖、数据库迁移、端口和 PDF 工具：
pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/DocWeave-Doctor.ps1输出中的 status 表示启动必需项状态；optional 列出页面预览等可选能力。
启动器会构建前端、迁移业务数据库和 Checkpoint 数据库，然后打开 http://127.0.0.1:8000/：
.\start-docweave.cmd停止服务：
pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/Stop-DocWeave.ps1运行数据、进程状态和日志保存在 .local/product/。
- 启动 DocWeave，在浏览器中新建项目和会话。
- 上传一个包含事实材料的
.md或.txt文件。 - 输入报告目标，例如“根据已上传资料生成一份带引用的两节研究摘要”。
- 在正文和引用面板核对来源片段。
- 查看 PDF 与 LaTeX 源文件包，接受候选后继续提出修订要求。
retrieval/ 模块提供可独立调用的 E5、FTS5、LanceDB 和 RRF 管线。主工作区的资料检索入口使用 SQLite FTS5。
联网准备模型，固定版本为 intfloat/multilingual-e5-small@614241f6：
.\.venv\Scripts\python.exe scripts/prepare_local_e5.py --output .local/models/multilingual-e5-small准备脚本下载 safetensors 权重、分词器、模块配置与模型说明，逐文件核对该 revision 的上游哈希，然后生成 model-manifest.json。建议为模型及下载暂存预留 2 GB 磁盘空间；目标目录须为新目录。模型说明中的 MIT 许可元数据与固定 revision 一并核对。
准备完成后运行 CPU 示例：
.\.venv\Scripts\python.exe scripts/demo_local_retrieval.py --model-dir .local/models/multilingual-e5-small示例在临时目录创建三条资料的 SQLite/LanceDB 索引，执行查询并打印融合排名。模型通过 local_files_only=True 加载，输出为 384 维归一化向量。LocalE5EmbeddingProvider(input_budget=100) 的限制是每次调用最多 100 条输入；文档与查询可多批复用同一个实例，input_count 累计记录成功编码的输入数。文档和查询分别使用 passage: 与 query: 前缀。
核心测试覆盖资料上传与中文检索、项目隔离、候选文档生成与审阅、版本及交付内容一致性，FTS5/LanceDB/RRF 检索模块，以及本地模型文件校验、安装失败处理和 TeX 运行时契约。模型、下载服务与运行时检查使用测试替身。
uv run pytest
uv run ruff check backend/src tests
pnpm --dir frontend run build项目结构：
backend/src/docweave/agent/：LangGraph 会话图与工具注册backend/src/docweave/application/：资料、证据、报告、版本和导出服务backend/src/docweave/retrieval/：FTS5、Embedding、LanceDB 与 RRFbackend/src/docweave/document/：Document IR、DOCX 与 LaTeX 构建frontend/：React 编辑与审阅界面tests/：核心业务测试