|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +SiYuan repository guide. Module path `github.com/siyuan-note/siyuan`, license AGPL-3.0. |
| 4 | + |
| 5 | +**Architecture:** Go kernel (`kernel/`) + TypeScript frontend (`app/`), plus a separate `export` bundle (global `Protyle`, entry `src/protyle/method.ts`) for rendering rich content in exported HTML / PDF preview. Read versions from `kernel/go.mod`, `app/package.json`, `kernel/util/working.go`. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 1. Required toolchain |
| 10 | + |
| 11 | +| Tool | Version | Source of truth | |
| 12 | +|---|---|---| |
| 13 | +| Go | see `go` directive | `kernel/go.mod` | |
| 14 | +| Node (+ pnpm) | see CI matrix | `.github/workflows/cd.yml`, `app/package.json` (`packageManager` field) | |
| 15 | + |
| 16 | +Two build-time requirements that aren't separate installs (see §5 #1–2): the Go |
| 17 | +build needs a C compiler with `CGO_ENABLED=1` (sqlite3 is cgo), and every |
| 18 | +`go build` / `go test` must pass `-tags fts5`. Re-read the sources above before |
| 19 | +pinning a version in commands or docs. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## 2. Related repositories (navigation) |
| 24 | + |
| 25 | +SiYuan spans several repos. This repo (`siyuan`) holds the kernel + Electron/web |
| 26 | +frontend; the others are separate projects with their own tooling. |
| 27 | + |
| 28 | +| Repo | Role / what to know | |
| 29 | +|---|---| |
| 30 | +| `siyuan` | **This repo** — kernel + Electron/web/tablet UI | |
| 31 | +| `siyuan-android` / `siyuan-ios` / `siyuan-harmony` | Native apps wrapping the gomobile kernel; build steps differ per platform — see each project's README | |
| 32 | +| `siyuan-chrome` | Browser extension (web clipper); talks to the running kernel over HTTP only | |
| 33 | +| `lute` | Markdown/Kramdown AST engine — the editor + `.sy` format; also the source of the bundled `lute.min.js`. **Lives under `$GOPATH/src/github.com/88250/lute`, not as a sibling repo** | |
| 34 | +| `dejavu` | Data repo / sync engine (encrypted snapshots) | |
| 35 | +| `riff` | Spaced-repetition (SRS) flashcard scheduler | |
| 36 | +| `gulu` | General Go utility library (`gulu.Ret`, `gulu.JSON`, …) | |
| 37 | +| `eventbus` | In-process event bus | |
| 38 | +| `filelock` | Cross-platform file locking (`.sy` read/write) | |
| 39 | +| `httpclient` | HTTP client wrapper (cloud / sync / bazaar calls) | |
| 40 | +| `logging` | Leveled logging used throughout the kernel | |
| 41 | +| `go-sqlite3` / `pdfcpu` | Maintainer's forks, pulled in via permanent `replace` in `kernel/go.mod` (keep those) | |
| 42 | +| `epub` / `clipboard` / `go-humanize` / `vitess-sqlparser` / `dataparser` / `encryption` | Smaller Go libraries (export / clipboard / formatting / SQL parse / data parse / crypto) | |
| 43 | + |
| 44 | +All Go libraries above are dependencies in `kernel/go.mod`. GitHub org: `siyuan-note/*` |
| 45 | +for the `siyuan-` apps and most libs; `88250/*` for lute, gulu, and the forks. |
| 46 | + |
| 47 | +### Cross-repo notes |
| 48 | + |
| 49 | +- **Editing any Go dependency (Lute / dejavu / gulu / eventbus / riff / filelock / |
| 50 | + httpclient / logging / go-sqlite3 / pdfcpu / epub / …):** these are imported by the |
| 51 | + kernel as Go modules (`kernel/go.mod`). To test a local change, add a temporary |
| 52 | + `replace` in `kernel/go.mod` pointing at your local checkout — but **never commit that |
| 53 | + `replace`**; it breaks builds for everyone else. (`go-sqlite3` and `pdfcpu` already have |
| 54 | + permanent `replace` directives pointing at the maintainer's forks — keep those.) |
| 55 | +- **Rebuilding `lute.min.js`:** it's the JS build of the Go `lute` project — generated |
| 56 | + upstream and checked into `app/stage/protyle/js/lute/`. Don't edit it here; change |
| 57 | + `lute`, rebuild, and copy the artifact in. |
| 58 | +- **Mobile apps (`siyuan-android` / `siyuan-ios` / `siyuan-harmony`):** each is a |
| 59 | + separate native app that wraps the kernel built from this repo. For how to build, |
| 60 | + vendor the kernel binding, and wire everything up, **read each project's own README** |
| 61 | + — the toolchains and steps differ per platform and aren't documented here. |
| 62 | +- **`siyuan-chrome`:** independent TypeScript project; it only interacts with a running |
| 63 | + SiYuan instance through the public HTTP API documented in `API.md`. |
| 64 | + |
| 65 | +--- |
| 66 | + |
| 67 | +## 3. Repository layout |
| 68 | + |
| 69 | +Top level (repo root): |
| 70 | + |
| 71 | +| Path | Contents | |
| 72 | +|---|---| |
| 73 | +| `kernel/` | Go backend — server, data engine, API, all domain logic | |
| 74 | +| `app/` | TypeScript frontend (Electron/web), built by webpack into `app/stage/build/` | |
| 75 | +| `app/electron/` | Electron main process | |
| 76 | +| `app/pandoc/` | Bundled pandoc binary (document conversion) | |
| 77 | +| `app/appearance/` | Themes, icons, **i18n** (`appearance/langs/*.json`) | |
| 78 | +| `app/stage/` | Build output served by the kernel | |
| 79 | +| `app/changelogs/` | Per-version changelog markdown | |
| 80 | +| `.github/` | `CONTRIBUTING.md` (+zh-CN), `SECURITY.md`, `CODE_OF_CONDUCT.md`, `PULL_REQUEST_TEMPLATE.md`, issue templates, `workflows/` | |
| 81 | +| `scripts/` | Release packaging: `win-build.bat`, `darwin-build.sh`, `linux-build.sh`, `parse-changelog.py`, `check-lang-keys.py` | |
| 82 | +| `README*.md` | README in EN / zh-CN / ja / tr | |
| 83 | +| `API*.md` | HTTP API reference in EN / zh-CN / ja | |
| 84 | +| `CHANGELOG.md`, `Dockerfile`, `LICENSE` | — | |
| 85 | + |
| 86 | +### Major `kernel/` packages (under `kernel/`) |
| 87 | + |
| 88 | +| Package | Responsibility | |
| 89 | +|---|---| |
| 90 | +| `main.go` (`//go:build !mobile`) | Desktop entry point → `cli/cmd` | |
| 91 | +| `cli/cmd/` | Cobra CLI subcommands (`serve`, `notebook`, `block`, `search`, `sql`, `export`, `repo`, `sync`, …) | |
| 92 | +| `model/` | **Core domain** (~70 files): blocks/trees, transactions, notebooks, indexing, search, attribute views, export, history, sync, SRS flashcards, AI/embedding, CalDAV/CardDAV, auth middleware | |
| 93 | +| `treenode/` | In-memory tree over the Lute AST + `blocktree.db` (`BlockTree{ID,RootID,ParentID,BoxID,Path,HPath,Type,...}`) | |
| 94 | +| `av/` | **Attribute View** (database) engine: values, filters, sorts, layouts (table/kanban/gallery) | |
| 95 | +| `sql/` | **Embedded SQLite** (`siyuan.db`, `history.db`, `asset_content.db`) + FTS5; async index queues | |
| 96 | +| `search/` | FTS tokenizer helpers, CJK conversion (`hanconv.go`) | |
| 97 | +| `bazaar/` | Marketplace: plugins/widgets/themes/icons/templates | |
| 98 | +| `filesys/` | Read/write `.sy` files on disk (via `filelock`) | |
| 99 | +| `server/` | Gin server bootstrap (`serve.go`): middleware, TLS/cmux, WebDAV/CalDAV/CardDAV, WebSocket, MCP | |
| 100 | +| `api/` | HTTP route registration (`router.go::ServeAPI`, ~400 endpoints) + per-area handlers | |
| 101 | +| `conf/` | Configuration structs | |
| 102 | +| `util/` | Cross-cutting: `working.go` (workspace, `Boot()`), `lute.go`, `i18n.go`/`lang.go`, `websocket.go` (melody push), `result.go` (API envelope), etc. | |
| 103 | +| `plugin/` | Plugin subsystem (kernel side) | |
| 104 | +| `mcp/` | MCP (Model Context Protocol) server | |
| 105 | +| `agent/` | AI agent runtime | |
| 106 | +| `mobile/`, `harmony/` | `//go:build mobile` gomobile bindings for Android/iOS/HarmonyOS | |
| 107 | + |
| 108 | +### Frontend (`app/src/`) highlights |
| 109 | + |
| 110 | +| Dir | Purpose | |
| 111 | +|---|---| |
| 112 | +| `index.ts` | Main `App` class — boots SPA, opens main WebSocket, handles WS push events | |
| 113 | +| `window/` | Detached Electron window variant | |
| 114 | +| `protyle/` | **The block editor** — `wysiwyg/`, `toolbar/`, `gutter/`, `breadcrumb/`, `header/`, `hint/`, `scroll/`, `undo/`, `upload/`, `preview/`, `render/` (incl. `render/av/`) | |
| 115 | +| `editor/`, `layout/`, `menus/`, `dialog/`, `config/`, `mobile/`, `ai/`, `sync/`, `history/`, `search/`, `card/` | Feature modules | |
| 116 | +| `util/fetch.ts` | `fetchGet`/`fetchPost` — all kernel calls | |
| 117 | +| `layout/Model.ts` | WebSocket client all UI binds to | |
| 118 | +| `constants.ts` | Global constants (version, IDs, storage keys) | |
| 119 | + |
| 120 | +Four webpack configs each emit a separate bundle to `app/stage/build/{app,desktop,mobile,export}/`. |
| 121 | +The kernel's `serveAppearance` picks which bundle to serve based on User-Agent. The `export` |
| 122 | +bundle is different from the other three: it is not an app UI — it is a client-side library |
| 123 | +(global `Protyle`, entry `src/protyle/method.ts`) exposing renderers for code highlighting, |
| 124 | +math (KaTeX), and diagrams (Mermaid/flowchart/graphviz/…). It is loaded by the HTML pages |
| 125 | +assembled during export (`app/src/protyle/export/index.ts`) — the desktop PDF preview window |
| 126 | +and standalone exported HTML files — so rich content renders outside the editor. |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | + |
| 131 | +## 4. Do not hand-edit |
| 132 | + |
| 133 | +- `app/stage/protyle/js/lute/lute.min.js` (built from upstream `88250/lute`) |
| 134 | +- `app/stage/build/**`, `app/src/types/dist/**` |
| 135 | +- `app/kernel/SiYuan-Kernel*`, `*.syso`, `kernel/kernel.aar` |
| 136 | +- `app/pandoc/*` |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +## 5. Project-specific rules |
| 141 | + |
| 142 | +1. **i18n:** New keys go at the **top** of each `langs/*.json` object; add to every language file (reference `en.json`); sync `app/changelogs/` for user-visible changes |
| 143 | +2. **Domains:** `ld246.com` only in `zh-CN.json`; use `liuyun.io` in all other languages |
| 144 | +3. **Line endings:** LF for `.go`, `.ts`, `.json`, `.scss` (`.gitattributes`) |
| 145 | +4. **Windows scripting:** Prefer Node.js / Python; avoid PowerShell unless necessary |
| 146 | +5. **Frontend verification:** Do not use `npx webpack` to verify changes |
0 commit comments