# Petrichor
### 让知识被人读懂，也被 AI Agent 正确调用
**开源、自托管的知识平台：用 Markdown 写作，把内容编译成语义 Wiki，\
再通过 Agentic RAG 生成可追溯的回答。**
*A self-hosted knowledge platform that turns Markdown into wikis, evidence and agent-ready knowledge.*
[](https://github.com/Ciao1019/Petrichor/actions/workflows/ci.yml)
[](LICENSE)
[](https://go.dev)
[](https://bun.sh)
[](https://react.dev)
[](https://www.postgresql.org/)
[**产品介绍**](https://wl.do/petrichor) · [**在线体验**](https://wl.do) · [**快速开始**](#-快速开始) · [**文档中心**](docs/README.md) · [**GitHub Wiki**](https://github.com/Ciao1019/Petrichor/wiki)
---
## 🎬 一分钟了解 Petrichor
[](https://streamable.com/w2v5x2)
*写作 → 编译语义 Wiki → 可追溯问答 → 划词问 AI → 交给你的 Agent。画面取自 [wl.do](https://wl.do) 的真实公开页面。*
## ✨ 为什么是 Petrichor
- **知识不是一次性向量。** 原文分片、推荐问题、语义 Wiki 和文章目录并存，分别处理事实、用户问法、概念关系与结构性问题。
- **检索和阅读严格分离。** Agent 先用 Search / Outline 定位，再 Read 原文形成 Evidence，避免把一批相似片段无差别塞进上下文。
- **Wiki 是可维护的知识中间层。** 从整篇文档抽取实体、概念和关系，让多篇文章聚合到同一页面，同时保留来源引用与新鲜度指纹。
- **知识可以交给其它 Agent。** 除 REST 和 MCP 外，还能导出 OKF、Obsidian 与可安装的 Agent Skill 包。
- **运行边界完全可控。** Web、API、Worker、PostgreSQL、Redis 和对象存储均由部署者管理，模型供应商可按用途自由配置。
## 🧩 核心能力
- **随笔与网页采集** — 后台首页随手记录 Markdown、图片和标签，也可粘贴网址交给 Firecrawl 抓取并由模型整理；支持草稿恢复、搜索、置顶和智能归档推荐，整理后归档为指定知识库和文件夹中的正式文章。
- **结构化写作** — PlateJS、Markdown、代码块、公式、表格、白板、思维导图与媒体嵌入。
- **知识库与发布** — 多级目录、标签、全文搜索、文章分享、公开问答、正文划词问 AI，以及标准 [`/rss.xml`](https://wl.do/rss.xml) / [`/atom.xml`](https://wl.do/atom.xml) 订阅。
- **Agentic RAG** — 标题感知切片、推荐问题、BM25 / Vector / Wiki 融合、目录导航、Evidence / Trace。
- **语义 Wiki** — 实体与概念抽取、多文章聚合、关系图谱、来源引用、补丁审计与结构检查。
- **Pi Agent Runtime** — 站内助手、前台公开问答、子 Agent 与 Wiki 文档 Agent 统一基于 [Pi Agent Core](https://github.com/earendil-works/pi)；计划、动态 Skill、预算、Evidence 与权限由 Go 掌控，支持运行中补充要求和检查点恢复。
- **Agent 扩展** — 外部 MCP Client、文件化 `SKILL.md`、Jina 兼容模型重排、隔离代码沙箱与 Playwright 浏览器执行，凭据和白名单只保存在 Go。
- **开放集成** — API Key、MCP、REST、知识 Skill 包、能力清单与完整调用审计。
- **自托管基础设施** — Go + Gin、Goose、Sa-Token-Go、PostgreSQL、Redis + Asynq、S3 兼容存储和 Caddy。
## 🚀 快速开始
### Vercel 纯前端演示
只需要展示产品、暂时不接后端时，可直接部署仓库内置的静态 Demo：
```bash
bun install --cwd apps/web
bun run build:demo
bunx vercel --prod
```
它覆盖前台文章与问答、后台随笔、知识库与编辑器、Wiki 知识空间和图谱；已保存的数据在浏览器内生成，刷新即重置，未保存的随笔草稿会保留在当前浏览器。不需要数据库、Redis、S3 或模型密钥。详细说明见 [`docs/vercel-static-demo.md`](docs/vercel-static-demo.md)。
### Docker Compose 部署
准备 Docker Engine、Compose v2，以及一套可从容器访问、已启用 `pg_trgm` 与 `vector`（pgvector）扩展的 **PostgreSQL 16+** 数据库：
```bash
git clone https://github.com/Ciao1019/Petrichor.git
cd Petrichor
cp .env.example .env
cp apps/api/config.example.toml apps/api/config.toml
```
启动前至少完成以下配置：
1. 在 `.env` 中设置 `PETRICHOR_DOMAIN`；本机 HTTP 可保持 `:80`。
2. 在 `apps/api/config.toml` 中填写 `[database].url`。
3. 为 `[encryption]` 生成稳定的随机 `key` 和 `salt`。
4. 在 `[storage]` 中选择 `/data/uploads`，或配置 `[storage.s3]`。
5. 按需配置登录、AI 模型供应商和外部搜索能力。
```bash
# 拉取公开的 GHCR 多架构镜像（linux/amd64、linux/arm64）
docker compose pull
docker compose up -d --no-build
docker compose ps
docker compose logs -f api worker
```
Compose 默认使用以下公开镜像；API 镜像同时包含 Server、Asynq Worker 与迁移命令：
| 服务 | 镜像 |
| --- | --- |
| API / Worker / Migrate | [`ghcr.io/ciao1019/petrichor-api:latest`](https://github.com/users/Ciao1019/packages/container/package/petrichor-api) |
| Web / Caddy | [`ghcr.io/ciao1019/petrichor-web:latest`](https://github.com/users/Ciao1019/packages/container/package/petrichor-web) |
镜像同时发布 `latest`、`master` 与不可变的 `sha-<12 位提交哈希>` 标签。生产环境建议在 `.env`
中通过 `PETRICHOR_API_IMAGE` 和 `PETRICHOR_WEB_IMAGE` 固定同一提交的 `sha-*` 标签。需要从当前源码
重新构建时，仍可执行 `docker compose up -d --build`。
打开配置的域名，首次访问会进入管理员初始化页。官方 Asynq 可视化管理器 asynqmon 默认同时启动，
仅监听宿主机 `http://127.0.0.1:8081`，可查看、重试、归档或删除两个队列中的任务。Petrichor 不写入默认账号，初始化只能成功执行一次。
> [!IMPORTANT]
> `compose.yaml` 不内置 PostgreSQL，请连接本地、自建或托管的 PostgreSQL 实例，并确认可以创建 `pg_trgm` 与 `vector` 扩展。不要把数据库连接串、Cookie、Token、API Key 或真实 `config.toml` 提交到仓库。