Home

Petrichor Wiki

Tip

让一份知识同时服务于人和 AI Agent。

Petrichor 是一个开源、自托管的知识平台：用 Markdown 写作，把文章编译成可维护的语义 Wiki， 再通过 Agentic RAG 生成带来源、可追溯的回答。

项目主页 · 在线 Demo · 文档中心 · Issues

Note

本站是 GitHub 项目文档 Wiki。文中“产品内 Wiki”指 Petrichor 从用户文章编译出的知识层， 两者不是同一个系统。

先选择你的目标

目标	推荐入口
安装、升级或本地开发	项目 README
看懂知识如何进入问答	Agentic RAG
配置 Chat / Embedding 模型	AI 模型配置
部署并维护生产环境	运维手册
接入 Claude Code / Codex / Cursor	外部客户端接入
导出 OKF、Obsidian 或 Agent Skill	知识可移植性

平台如何工作

flowchart LR
  source["Markdown / PDF"] --> build["构建知识"]
  build --> chunks["结构分片"]
  build --> questions["推荐问题"]
  build --> wiki["语义 Wiki"]
  chunks --> recall["BM25 + Vector"]
  questions --> recall
  wiki --> recall
  query["用户问题"] --> recall
  recall --> agent["Search · Outline · Read"]
  agent --> evidence["Evidence + Trace"]
  evidence --> answer["可追溯回答"]

Loading

01 · 结构优先，而不是固定窗口

切片器识别 h1–h6 标题路径，不跨一级主题合并，并保护代码围栏。每个分片都保留 “文章 › 章节 › 子章节”的定位，避免正文和上下文被拆散。

02 · 一份原文，多种知识表示

原文分片负责事实，推荐问题负责匹配用户问法，语义 Wiki 负责实体与概念导航，PageIndex 负责章节顺序。它们分别解决不同问题，而不是重复保存同一份索引。

03 · Agent 按需阅读

knowledge.search 只返回候选；Agent 根据问题选择 knowledge.outline、knowledge.read 或 read_many。正文只有在 Read 后才会进入 Evidence，避免把 Top-K 全文一次性塞进上下文。

04 · 可追溯，也可带走

答案保留来源、Evidence 和 Trace。知识库还可导出为 OKF、Obsidian vault，或蒸馏成可安装到 Claude Code / Codex 的 Agent Skill 包。

推荐的知识构建顺序

1. 创建或导入文章：Markdown、REST / MCP，或 PDF 视觉转写。
2. 构建知识：生成结构分片、推荐问题、实体与概念 Wiki。
3. 更新 Wiki：补齐 source 页面和 PageIndex 章节树。
4. 生成向量：先补原文分片，再补推荐问题。
5. 结构检查：处理陈旧页面、断链和旧构建版本。
6. 问答验收：分别测试精确事实、章节总结和跨文章比较。

Important

保存文章不等于完成索引。至少执行一次“构建知识”；需要语义召回时，还要配置 Embedding 模型并生成向量。

生产部署边界

flowchart TB
  internet["Browser / MCP / REST"] --> caddy["Caddy<br/>HTTPS · 静态资源 · API 反代"]
  caddy --> web["Vite SPA"]
  caddy --> api["Go + Gin API"]
  api --> postgres["PostgreSQL<br/>业务数据 · Wiki · 索引 · 任务事实"]
  api --> redis["Redis<br/>热点缓存"]
  api --> storage["S3 / 本地卷<br/>上传文件"]
  worker["视觉导入 Worker"] --> postgres
  worker --> storage

Loading

• 生产环境只公开 Caddy；Go API、Worker 与 Redis 位于内部网络。
• 知识构建使用 API 进程内有界队列；API 重启后，排队或执行中的任务需要重新发起。
• 视觉导入以 PostgreSQL 为事实来源，可恢复、可重试；Redis 不承担任务事实。

安装命令和生产注意事项以 README 与 运维手册 为准。

---

继续阅读

• 完整算法与边界：Petrichor Agentic RAG
• 完整技术文档：Petrichor 文档中心
• 运行时与工具：Agent Runtime
• 参与项目：Issues · Contributing