Principia本地文献发现教程：连接私有文档文件夹，如何提取可复用的研究发现并归档-开发者社区

【免费下载链接】Principia

Principia extracts reusable principles, composes those principles into traceable research ideas, and helps researchers inspect why an idea may be worth testing.

项目地址：https://gitcode.com/gh_mirrors/princi/Principia

点击查看免费下载

Principia 是一个本地优先的科学研究工具，它可以连接你电脑上的私有文档文件夹，把散落的论文、实验笔记和数据文件索引起来，并从中提取带完整证据链的可复用研究发现（Candidate Principles）。本教程带你完整走一遍本地文献发现的流程：连接私有文档文件夹 → 索引 → 提取 → 审查证据 → 归档导出，全程无需把资料上传到任何服务器。

一、为什么需要「本地文献发现」

很多科研笔记工具只能"存"文档，却不能从文档里"长"出结论。Principia 的本地文献发现（Local Literature Discovery）做了不同的事：

你的痛点	Principia 的做法
文献、笔记、CSV 散落在各处文件夹	直接把私有文件夹整体接入，支持 PDF、Markdown、HTML/XML、LaTeX、纯文本、CSV/JSON 等格式
结论没有出处，无法复核	每条候选发现都附带精确证据摘录、Work 来源引用和 SHA-256 溯源
提取结果不可控	只对你精确选中的文档做提取，模型策略（`no_llm`/`local`/`remote`）透明可见
成果难以迁移分享	一键导出"无论文"的可移植 showcase，4 个文件即可在新工作区重建 Principles 库

每条提取出的 Candidate Principle 都是一个有界范围、带证据的类型化科学声明，并带有明确的unassessed（待评估）标签——它不冒充已验证结论。完整流程说明见 local-literature-discovery.md。

二、快速安装并启动 Principia 本地工作区

环境要求Python 3.11 或 3.12，建议放在虚拟环境中：

git clone --depth 1 https://gitcode.com/gh_mirrors/princi/Principia cd Principia python3 -m venv .venv && source .venv/bin/activate python -m pip install "./Principia-v1.4.2/core-v1.4.2[asd,local]" principia open --working-directory ./principia-workspace --port 8142

浏览器会自动打开http://127.0.0.1:8142/。启动后，Principia 会在工作目录下创建两个明确的边界（这也是"归档"的基础）：

workspace/—— 数据库、索引缓存与持久化的 Principles（可移植成果）
local_data/—— 你拥有的原始资料（私有，默认被 Git 忽略）

目录布局细节可参考 storage-and-portability.md 与 getting-started.md。

三、三步连接私有文档文件夹 📁

打开 Local Discovery：在左侧 Principles Library / Local Discovery 入口进入本地发现面板；
选择文件夹：可以选择、连接或新建一个私有文件夹。它的精确路径、文档数量、可用状态始终可见，还能一键"Open Folder"回到原目录核对；
索引文档：一键索引后，支持 PDF、Markdown、HTML/XML、LaTeX、纯文本、JSON/JSONL、CSV/TSV 等；DOCX、PPTX、XLSX 需要安装时带上[local]额外依赖（上面已包含）。

几个值得知道的默认值（来自 local-corpus.md）：

限制项	默认值
单文件夹最大文件数	500
单文件大小上限	50 MiB
隐藏文件	自动跳过
符号链接	不跟随

💡缺文献怎么办？如果文件夹里论文不够，可以打开Find public literature：搜索只做元数据检索，审阅后可把允许获取的内容（开放获取全文或摘要）安全下载到选中的文件夹。下载不会自动触发提取，也不会发起任何模型调用。

四、选择文档并提取可复用的研究发现

索引完成后，进入提取环节——这是整个本地文献发现的核心：

精确选择范围：可以全选、按过滤条件选择，或勾选一个精确子集。提取只作用于你选中的文档，多一篇都不会碰；
（可选）填写研究焦点：research focus 用于引导提取，Area 标签只是事后可编辑的组织信息，不参与判定；
确认模型策略与限额：
- no_llm：只做确定性索引与结构化，绝不"编造"文本；
- local：仅接受本机回环（loopback）的 OpenAI 兼容端点；
- remote：必须命名具体的提供商与模型，并且每次运行都要显式确认外发（egress）；
开始提取：进度、重试次数、token 用量、被搁置的候选数都会实时可见，刷新页面也不会丢失已完成的部分。

提取完成后，你会得到一批Candidate Principles。每一条都可以点开审查：声明本身、适用边界（Conditions / Boundary & Disproof）、可靠性评分、以及可点击的公开来源。确认无误后，可以选择Open in Principles Explorer把它并入你的 Principles 库。

五、归档与导出：让研究发现可迁移、可审计

提取出的记录会自动归档到工作区：原始文件留在你的私有文件夹里不动，结构化成果保存在workspace/下。整个研究上下文（Study map）把 Principles、发现记录、证据锚点连成一张可导航的图，你可以从一条发现顺藤摸到它背后的原文摘录：

当记录足够完整时，它会沉淀为带公式、校验指标与验证拆分的可审计记录卡，例如一条 Rule 会展示符号公式、白话解释、归一化 RMSE 与基线对比、验证拆分方式和适用范围的说明——这就是"归档"的最终形态：

一键导出可移植 showcase

Principia 的归档导出不依赖原始论文：4 个文件即可把整个 Principles 库带到干净的工作区：

principia showcase --working-directory ./principia-workspace export ./principles-showcase principia showcase --working-directory ./clean-project import ./principles-showcase

导出目录固定包含manifest.json、principles.jsonl、works.jsonl、relations.jsonl。它刻意排除PDF、摘要、原文引用、归一化文本、凭据和绝对路径——即使删掉私有论文树，导出包里的每条 Principle 仍保留其公开来源链接与证据哈希。导入是幂等的，可反复执行。

六、命令行进阶：先搜索、后提取（可选）

习惯 CLI 的话，可以先做元数据搜索、审阅文献集合，再显式发起获取与提取（完整示例见 local-literature-discovery.md）：

principia local --workspace ./principia-workspace search \ --goal "When does verifier-guided inference improve LLM reasoning?" \ --target-count 20

七、隐私与可靠性速记 🔒

私有优先：本地文档默认私有，远程模型接收文本前必须逐次显式确认；凭据只保存在你的私有工作区中；
可恢复：每篇文档是独立的工作单元，任务带检查点，中断后可以 Resume 从最后有效检查点继续，不重复已完成调用；
可清理：导出完成后，工作区支持清除缓存的私有归一化文本，原始文件不受影响。

写在最后

本地文献发现的完整路径可以浓缩为一句话：

连接私有文件夹 → 索引 → 精确选择 → 提取 Candidate Principles → 审查证据 → 归档到 workspace/ 或导出 4 文件 showcase

把这套流程跑通后，你私有文件夹里的文档就不再只是"存档"，而是持续产出可复用、可复核研究发现的科学工作区。想进一步用它分析实验数据集，可以继续了解>

【免费下载链接】Principia

Principia extracts reusable principles, composes those principles into traceable research ideas, and helps researchers inspect why an idea may be worth testing.

项目地址：https://gitcode.com/gh_mirrors/princi/Principia

点击查看免费下载