| 模块 | 能力 | 用户价值 |
|---|---|---|
| Vault 管理 | 新建 / 打开 open-llm-wiki vault，检测 runtime、schema、Obsidian 状态 |
避免把原始 PDF 文件夹误当知识库，第一步就知道项目是否可运行 |
| Raw Sources | 导入 PDF、Markdown、txt、zip，保留目录上下文，记录 hash、parser、artifact | 每份 evidence 都可追踪，重复文件和阻塞状态清楚可见 |
| Ingest Pipeline | 串行执行 parse、source discovery、claims、normalize、QA、contradictions、review、concept revision、lint | 把论文语料转成稳定 source、claim、concept 和 review queue |
| Evidence Graph | 展示 source、claim、concept、review、proposal、warning 的关系 | 从结论反查证据，也能发现断链、桥接节点和可写回 insight |
| Chat / Writeback | 基于 vault evidence 提问，生成 answer draft 和 proposal-first writeback | 不把模型回答静默写入知识库，先审查 diff 和证据链接 |
| Review Queue | 显示 science review、needs_review、stale、contradicted、traceability warning | 保留人工审查边界，不伪造批准 |
| Obsidian Handoff | 从桌面端打开生成后的 vault 或 entry note | 阅读、反链、图谱和人工整理交给熟悉的 Obsidian 工作流 |
| Agent Read API | 通过 readiness gate 后开放 127.0.0.1 只读、token-protected API |
给 Codex / Claude Code 读 evidence，不开放删除、apply 或后台 ingest |
截图来自本地 DeepSeek 论文语料验收流程，已裁掉菜单栏、Dock 和本机绝对路径，只保留软件窗口本身。
Raw Sources 管理导入文件、parser artifact、source registry 和 traceability 状态。 |
Chat / Writeback 基于 vault evidence 检索、回答，并生成可审核写回提案。 |
Evidence Graph 查看 source -> claim -> concept / review / proposal / warning 关系。 |
Provider Settings 配置 ERNIE、PaddleOCR、本地 CLI 和 provider 边界，不保存明文 key。 |
cd /path/to/llm-wiki-desktop
npm ci
npm run desktop:dev已经完成本地打包时，也可以直接打开 macOS app：
open "src-tauri/target/release/bundle/macos/LLM Wiki.app"- 在 Welcome 页选择
新建项目或打开项目。 - 如果 vault 内还没有 runtime，在 Settings 中选择本地
open-llm-wiki仓库路径。 - 在
Raw Sources导入 PDF、Markdown、txt 或 zip 论文包。 - 先查看 ingest plan 和 action panel，再运行 ingest pipeline。
- 在
Graph、Review、Chat / Writeback和 Obsidian 中检查生成结果。
不要直接打开原始 PDF 文件夹。Obsidian 应该打开生成后的 LLM Wiki vault。
PDF / Markdown / ZIP
|
v
LLM Wiki Desktop
|
v
open-llm-wiki Runtime
|
+--> raw evidence / parser artifacts
+--> source pages / claims / QA reports
+--> science review queue / contradictions
+--> concept pages / query writeback proposals
|
v
Obsidian + Evidence Graph + Review UI
| 阶段 | 桌面端入口 | 结果 |
|---|---|---|
| 创建知识库 | Welcome / Dashboard | 初始化 vault，检测 runtime、schema、Obsidian |
| 导入资料 | Raw Sources | 文件进入 raw/inbox/，生成 plan、hash 和 artifact contract |
| 运行流程 | Dashboard / Raw Sources | 执行 parse -> ingest -> claims -> QA -> review -> concept revision |
| 浏览证据 | Sources / Concepts / Graph | 查看 evidence anchor、claim、concept 和断链 warning |
| 提问写回 | Chat / Writeback | 生成带 evidence map 的 answer draft 和 proposal artifact |
| 人工审查 | Review / Obsidian | 只在明确批准后 apply writeback |
flowchart LR
A["Desktop UI<br>React + TypeScript + Vite"] --> B["Tauri Shell<br>Rust commands"]
B --> C["Vault Runtime<br>open-llm-wiki scripts"]
C --> D["Local Vault<br>raw / sources / claims / concepts / reviews"]
D --> E["Obsidian<br>reading and backlinks"]
D --> F["Evidence Graph<br>source-claim-concept"]
D --> G["Query Writeback<br>proposal-first"]
B --> H["Optional Providers<br>ERNIE / PaddleOCR / local CLI"]
| 层级 | 技术 |
|---|---|
| 前端 | React 18、TypeScript 5、Vite 6、lucide-react、react-markdown、Mermaid、KaTeX |
| 桌面壳 | Tauri 2、Rust 2021、tauri-plugin-dialog、tauri-plugin-opener |
| 图谱 | Sigma、Graphology、ForceAtlas2 |
| Runtime | open-llm-wiki Python scripts and vault schema |
| 本地数据 | Generated vault files, _state/*.jsonl, log-archive/desktop/ |
| 可选 provider | ERNIE、PaddleOCR-VL 文档解析技能、本地 Codex / Claude CLI |
- 默认本地优先。没有显式配置和用户动作时，不上传 raw documents。
- API key 通过环境变量或安全路径传入，不在 UI 明文保存或展示。
- 桌面端不直接把 draft 移到
sources/，不修改 QA verdict，不重写历史 QA report。 - Query writeback 默认生成
reviews/query-writeback/proposal，不静默写入concepts/或sources/。 - Science review、human review 和 writeback approval 不会被桌面端伪造。
- Agent API 必须先通过只读 readiness gate；不提供 apply、delete、parser、ingest、cloud OCR 或外部搜索端点。
- 所有 source、claim、QA、contradiction、concept 写入都走
open-llm-wikiruntime 边界。
展开常用配置
| 配置项 | 用途 | 默认行为 |
|---|---|---|
AI_STUDIO_API_KEY |
ERNIE / 文心一言连接测试和 evidence-first answer draft | 缺失时显示未配置，不上传 raw documents |
PADDLEOCR_API_KEY |
PaddleOCR-VL 文档解析技能的默认 key 来源 | 缺失时 ingest plan 阻塞，不运行 OCR |
| OCR Parser endpoint | PaddleOCR-VL service URL | 必须显式配置；非 localhost HTTP 会被拒绝 |
| Local CLI paths | Codex / Claude 本地 CLI 检测 | 只做本地诊断，不自动执行写入动作 |
详细说明：
展开开发、测试和打包命令
npm ci
npm run desktop:dev| Command | Purpose |
|---|---|
npm run start |
启动完整 Tauri 桌面端 |
npm run desktop:dev |
启动 Tauri dev shell，内部拉起 Vite |
npm run dev:web |
只启动 Vite Web 视图，用于 UI 调试 |
npm test |
运行 TypeScript/Rust/smoke 测试组合 |
npm run build |
运行 typecheck 并生成前端 dist/ |
npm run build:app |
运行 Tauri 本地应用打包 |
npm run smoke:macos:bundle |
打开打包后的 macOS .app，并确认进程启动后至少创建一个可见窗口 |
cargo test --manifest-path src-tauri/Cargo.toml |
单独运行 Rust tests |
npm ci
npm run build
npm test
npm run build:app
npm run smoke:macos:bundle本地 .app / .dmg 只能证明当前机器可构建和启动，不等同于签名、notarization 或公开分发。完整检查见 Release Readiness。
展开 ZIP import 合同检查
deepseek_paper_中文.zip 用于验证中文文件名和混合资料包导入体验。smoke 必须只读原始 ZIP：不要修改 ZIP、不要提交解压内容、不要移动或重命名原始文件，也不要把真实论文截图或私有路径提交进 Git。
mkdir -p artifacts/smoke/zip
node scripts/smoke/zip-import-contract.mjs \
"../deepseek_paper_中文.zip" \
--out "artifacts/smoke/zip/deepseek_paper_中文-report.json"报告应记录每个 ZIP 条目的 source_path、target_path、sha256、是否 ignored、以及 ignored_reason。__MACOSX/、.DS_Store、._*、../ traversal、绝对路径和 symlink escape 风险必须被忽略或拒绝，不能写入 vault 外部。
llm-wiki-desktop/
|-- src/ # React desktop UI
|-- src-tauri/ # Tauri 2 shell and Rust commands
|-- docs/ # Product, provider, release and smoke docs
|-- docs/screenshots/ # README and PR evidence screenshots
|-- examples/demo-vault/ # Synthetic demo vault, no private papers
|-- scripts/ # Local smoke, benchmark and build helpers
|-- benchmarks/ # Submission and OCR/QA benchmark assets
|-- package.json
`-- README.md
| 文档 | 适合谁 |
|---|---|
| Product Requirements | 产品范围、用户故事和验收标准 |
| Scoring Mapping | 比赛/评审评分点与功能映射 |
| Product Parity Matrix | 与参考 wiki / Obsidian 工作流的能力对照 |
| Agent Read API | Codex / Claude Code 只读 API readiness gate |
| Runtime Dependency Strategy | runtime、vault 和桌面端依赖边界 |
| macOS Clean Profile Smoke | macOS 干净环境手动验收 |
| Windows Dev Smoke | Windows 开发环境 smoke 检查 |
| License | Apache-2.0 license |
| Contributing | 协作者指南 |
| Security | 安全漏洞报告 |
| Code of Conduct | 社区行为准则 |
| Changelog | 版本变化记录 |
| Roadmap | 后续路线图 |
不配置 API key 能用吗？
可以打开、创建 vault、浏览本地资料、查看 graph、运行不依赖 provider 的本地流程。需要 ERNIE、PaddleOCR 或 hosted parser 时，必须显式配置对应环境变量和 endpoint。
数据会自动上传到云端吗？
不会。默认不会上传 raw documents。PaddleOCR / hosted parser / 外部 LLM 都需要用户配置和显式运行；缺少配置时会显示 blocked 或 not configured。
它会替代 Obsidian 吗？
不会。桌面端负责 ingest、证据追踪、review、writeback proposal 和 runtime 编排；Obsidian 仍是阅读、反链、图谱和人工整理的 companion layer。
为什么不能直接编辑 concept 或 source？
因为 sources/、claims/、concepts/ 是可审核知识库的一部分。桌面端默认通过 review queue 和 query writeback proposal 写入，避免模型输出绕过 evidence、QA 和人工批准。