514ab19759
Some checks failed
Auto-update PR branches / Update open PR branches (push) Has been cancelled
CI / Frontend Static Quality Checks (push) Has been cancelled
CI / Frontend Tests & Coverage (push) Has been cancelled
CI / Rust Tests & Quality Checks (push) Has been cancelled
CI / Linux build verification (push) Has been cancelled
Release (Alpha) / Compute alpha version (push) Has been cancelled
Release (Alpha) / Build release artifacts (push) Has been cancelled
Release (Alpha) / GitHub Release (alpha) (push) Has been cancelled
Release (Alpha) / Update docs and release pages (push) Has been cancelled
202 lines
9.5 KiB
Markdown
202 lines
9.5 KiB
Markdown
# 🔧 Tolaria 零件仓库(REPO-004)
|
||
|
||
> **本仓库 = 零件仓库,不是开发主仓库。**
|
||
> **冰朔 D165 · 2026-07-05 重划**
|
||
|
||
本仓库是 [Tolaria](https://github.com/refactoringhq/tolaria) 的 fork,作为光湖人格体的**零件源头**——不用于开发,只用于 rebase 上游,保留所有组件供光湖人格体按需挑选复用,避免重复造轮子。
|
||
|
||
上游采用 AGPL-3.0-or-later,本仓库继续遵守同一许可证并保留完整历史。
|
||
|
||
## 仓库角色(D165 19:23 冰朔亲口裁定)
|
||
|
||
- **角色:** 持续同步上游的"零件组件库" —— 不发布应用、不接受开发 PR、不作为光湖开发主仓库
|
||
- **维护:** 冰朔 · REPO 编号 = `REPO-004`
|
||
- **工作流:** 上游 `refactoringhq/tolaria` 一旦发 alpha,本仓库 rebase 同步 → 上游所有更新以 commit 形式保留 → 光湖人格体随时可以 `git log upstream/main` 找新零件
|
||
- **应用内更新:** 关闭(本仓库不参与光湖产品发布链)
|
||
|
||
## 光湖真正的开发主仓库 = REPO-005(待建)
|
||
|
||
本仓库之外的"光湖真正动代码的地方":
|
||
|
||
```
|
||
REPO-005 = bingshuo/guanghu-research ⏳ 待建 · 企业门户服务器下
|
||
```
|
||
|
||
人格体需要"找零件做组件"时去 R-004。
|
||
人格体需要"开发新模块写光湖产品"时去 R-005。
|
||
|
||
## 跨仓库编号 · REPO 体系
|
||
|
||
详见 [`REPO-004` 编号字典 · 第五域仓库](../fifth-domain/.code-map)
|
||
|
||
```
|
||
REPO-001 = bingshuo/fifth-domain 现行主仓库 · 个人作品
|
||
REPO-002 = bingshuo/guanghulab 历史档案 · 留痕区
|
||
REPO-003 = bingshuo/tolaria-src Tolaria 上游纯净镜像(可能并入 REPO-005)
|
||
REPO-004 = bingshuo/guanghu ← 本仓库 · 零件仓库
|
||
REPO-005 = bingshuo/guanghu-research ⏳ 光湖研发 · 待建
|
||
```
|
||
|
||
---
|
||
|
||
## Tolaria 上游说明
|
||
|
||
Tolaria 提供了跨平台 Markdown 知识库的基础能力。光湖在此基础上挑选零件,
|
||
不重造轮子。上游版权与贡献者署名保持不变。
|
||
|
||
---
|
||
|
||
## Tolaria 上游能力介绍
|
||
|
||
Tolaria is a desktop app for macOS, Windows, and Linux for managing **markdown knowledge bases**. People use it for a variety of use cases:
|
||
|
||
* Operate second brains and personal knowledge
|
||
* Organize company docs as context for AI
|
||
* Store OpenClaw/assistants memory and procedures
|
||
|
||
Personally, I use it to **run my life** (hey 👋 [Luca here](http://x.com/lucaronin)). I have a massive workspace of 10,000+ notes, which are the result of my [Refactoring](https://refactoring.fm/) work + a ton of personal journaling and *second braining*.
|
||
|
||
<img width="1000" height="656" alt="1776506856823-CleanShot_2026-04-18_at_12 06 57_2x" src="https://github.com/user-attachments/assets/8aeafb0a-b236-43c2-a083-ec111f903c38" />
|
||
|
||
## Sponsors
|
||
|
||
Tolaria is supported by a small panel of tools that help keep the project healthy, tested, and ready for AI-assisted development. I use these tools every day.
|
||
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="25%">
|
||
<a href="https://www.codacy.com/">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/codacy-light.svg">
|
||
<img src="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/codacy-dark.svg" alt="Codacy" height="32">
|
||
</picture>
|
||
</a>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="https://codescene.com/">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/codescene-light.svg">
|
||
<img src="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/codescene-dark.svg" alt="CodeScene" height="32">
|
||
</picture>
|
||
</a>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="https://circleci.com/">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/circleci-light.svg">
|
||
<img src="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/circleci-dark.svg" alt="CircleCI" height="32">
|
||
</picture>
|
||
</a>
|
||
</td>
|
||
<td align="center" width="25%">
|
||
<a href="https://getunblocked.com/">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/unblocked-light.svg">
|
||
<img src="https://raw.githubusercontent.com/refactoringhq/tolaria/main/site/public/landing/sponsors/unblocked-dark.svg" alt="Unblocked" height="32">
|
||
</picture>
|
||
</a>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## Walkthroughs
|
||
|
||
You can find some Loom walkthroughs below — they are short and to the point:
|
||
- [How I Organize My Own Tolaria Workspace](https://www.loom.com/share/bb3aaffa238b4be0bd62e4464bca2528)
|
||
- [My Inbox Workflow](https://www.loom.com/share/dffda263317b4fa8b47b59cdf9330571)
|
||
- [How I Save Web Resources to Tolaria](https://www.loom.com/share/8a3c1776f801402ebbf4d7b0f31e9882)
|
||
|
||
## Principles
|
||
|
||
- 📑 **Files-first** — Your notes are plain markdown files. They're portable, work with any editor, and require no export step. Your data belongs to you, not to any app.
|
||
- 🔌 **Git-first** — Every vault is a git repository. You get full version history, the ability to use any git remote, and zero dependency on Tolaria servers.
|
||
- 🛜 **Offline-first, zero lock-in** — No accounts, no subscriptions, no cloud dependencies. Your vault works completely offline and always will. If you stop using Tolaria, you lose nothing.
|
||
- 🔬 **Open source** — Tolaria is free and open source. I built this for [myself](https://x.com/lucaronin) and for sharing it with others.
|
||
- 📋 **Standards-based** — Notes are markdown files with YAML frontmatter. No proprietary formats, no locked-in data. Everything works with standard tools if you decide to move away from Tolaria.
|
||
- 🔍 **Types as lenses, not schemas** — Types in Tolaria are navigation aids, not enforcement mechanisms. There's no required fields, no validation, just helpful categories for finding notes.
|
||
- 🪄**AI-first but not AI-only** — A vault of files works very well with AI agents, but you are free to use whatever you want. We support Claude Code, Codex CLI, and Gemini CLI setup paths, but you can edit the vault with any AI you want. We provide an AGENTS file for your agents to figure out.
|
||
- ⌨️ **Keyboard-first** — Tolaria is designed for power-users who want to use keyboard as much as possible. A lot of how we designed the Editor and the Command Palette is based on this.
|
||
- 💪 **Built from real use** — Tolaria was created for manage my personal vault of 10,000+ notes, and I use it every day. Every feature exists because it solved a real problem.
|
||
|
||
## Installation
|
||
|
||
### Homebrew
|
||
|
||
Install via Homebrew on macOS:
|
||
|
||
```batch
|
||
brew install --cask tolaria
|
||
```
|
||
|
||
### Download from releases
|
||
|
||
Download the [latest release here](https://refactoringhq.github.io/tolaria/download/) for macOS, Windows, or Linux. Windows installers are Authenticode-signed; company-managed devices may still require IT approval of the Tolaria publisher before first install.
|
||
|
||
## Getting started
|
||
|
||
When you open Tolaria for the first time you get the chance of cloning the [getting started vault](https://github.com/refactoringhq/tolaria-getting-started) — which gives you a walkthrough of the whole app.
|
||
|
||
The public user docs live in [`site/`](site/) and are published to GitHub Pages. Start with [Install Tolaria](site/start/install.md), then [First Launch](site/start/first-launch.md).
|
||
|
||
## Open source and local setup
|
||
|
||
Tolaria is open source and built with Tauri, React, and TypeScript. If you want to run or contribute to the app locally, here is [how to get started](https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md). You can also find the gist below 👇
|
||
|
||
### Prerequisites
|
||
|
||
- Node.js 20+
|
||
- pnpm 8+
|
||
- Rust stable
|
||
- macOS or Linux for development
|
||
|
||
#### Linux system dependencies
|
||
|
||
Tauri 2 on Linux requires WebKit2GTK 4.1 and GTK 3:
|
||
|
||
- Arch / Manjaro:
|
||
```bash
|
||
sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl \
|
||
appmenu-gtk-module libappindicator-gtk3 librsvg
|
||
```
|
||
- Debian / Ubuntu (22.04+):
|
||
```bash
|
||
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
|
||
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \
|
||
libsoup-3.0-dev patchelf
|
||
```
|
||
- Fedora 38+:
|
||
```bash
|
||
sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file \
|
||
libappindicator-gtk3-devel librsvg2-devel
|
||
```
|
||
|
||
The bundled MCP server still spawns the system `node` binary at runtime on Linux, so install Node from your distro package manager if you want the external AI tooling flow.
|
||
|
||
### Quick start
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
Open `http://localhost:5173` for the browser-based mock mode, or run the native desktop app with:
|
||
|
||
```bash
|
||
pnpm tauri dev
|
||
```
|
||
|
||
## Tech Docs
|
||
|
||
- 📐 [ARCHITECTURE.md](docs/ARCHITECTURE.md) — System design, tech stack, data flow
|
||
- 🧩 [ABSTRACTIONS.md](docs/ABSTRACTIONS.md) — Core abstractions and models
|
||
- 🚀 [GETTING-STARTED.md](docs/GETTING-STARTED.md) — How to navigate the codebase
|
||
- 📚 [ADRs](docs/adr) — Architecture Decision Records
|
||
|
||
## Security
|
||
|
||
If you believe you have found a security issue, please report it privately as described in [SECURITY.md](./SECURITY.md).
|
||
|
||
## License
|
||
|
||
Tolaria is licensed under AGPL-3.0-or-later. The Tolaria name and logo remain covered by the project’s trademark policy.
|