An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
AGENTS.md
SiYuan repository guide. Module path github.com/siyuan-note/siyuan, license AGPL-3.0.
1. Non-negotiable constraints
Verify the code baseline before repository tasks
- Before each new repository task, verify the repository, current commit, branch, and working-tree state. For work targeting the latest branch, select the baseline source branch using section 2's Git rules and fetch the relevant remote refs before analysis or editing. Respect explicitly requested commits, tags, or pull requests; for a fixed-revision review or historical investigation, inspect that revision without advancing it or synchronizing the working branch. Fetch only if needed to resolve the requested revision. If fetching is unavailable, report the known commit and freshness limit; read-only analysis may continue, but do not claim to have verified the latest remote baseline
- Follow the repository-specific Git rules for working branches and authorized push destinations. If the user explicitly requests a task branch or the repository's own rules require one, create it from the verified task baseline. Using an isolated worktree does not change the default working branch or authorize pushing to a task branch instead. When synchronizing a development branch, automatically fast-forward it only when its working tree is clean and it is merely behind. Rebase is permitted when synchronizing divergent development branches, provided existing work is preserved; this does not authorize force-pushing rewritten history. Read-only analysis does not itself authorize branch synchronization. If synchronization is blocked, preserve existing work and report the limitation; do not discard changes, automatically stash, create merge commits, or silently substitute another push destination
- Reuse the verified baseline for follow-ups in the same task; recheck after a substantial pause, a repository or branch change, or when newer commits could affect the task. Unrelated conversation needs no fetch
Requirement evaluation
Before implementing a requirement, evaluate its premise and approach with effort proportional to its complexity and risk
- Check compliance first: For major features, review applicable compliance requirements, licensing terms, privacy risks, and costs before technical design
- Check the premise and existing capabilities: Inspect the relevant implementation, settings, code snippets, shortcuts, APIs, or plugin capabilities, and reproduce reported behavior when feasible. Check applicable repository rules, encrypted notebook compatibility, the
.syformat, and API contracts. Distinguish the user's goal and acceptance criteria from a suggested implementation; a named implementation form (for example, a JS script) does not remove this evaluation step. Evaluate whether that implementation addresses the underlying problem, respect explicit user constraints, and state any limits to verification - Choose an appropriate approach: Prefer the smallest sufficient change consistent with existing practices and compatibility requirements. Consider whether an existing capability or a documentation correction already satisfies the need, including the option of making no code change. Compare user effort, persistence, reversibility, and maintenance when choosing among suitable approaches. For styling-only workarounds, consider CSS snippets with built-in enable/disable controls before JavaScript that injects styles. Explain how to enable, disable, or undo the chosen solution when relevant
- Briefly report before editing: State the conclusion, key evidence, and remaining uncertainty in a progress update before the first change. Discuss alternatives only when they involve meaningful tradeoffs; simple tasks need only a short explanation
- Ask only when a decision is needed: If the premise is false or implementation is unwarranted, explain the evidence and ask how to proceed unless the user's existing instructions already resolve the next step. Ask before changing the agreed goal or scope, or making an unresolved product, priority, or compatibility tradeoff. Do not silently narrow or broaden the task
- Otherwise proceed directly: When the requirement is reasonable, implement it without another confirmation round. Choosing a different implementation that meets the agreed goal and acceptance criteria does not itself require approval
Unambiguous mechanical edits with no behavioral or compatibility impact need no separate evaluation round. Continue to follow applicable repository checks; a rename, version bump, or documentation update is not automatically exempt
Do not hand-edit
app/stage/protyle/js/lute/lute.min.js(built from upstream88250/lute)app/stage/build/**,app/src/types/dist/**app/changelogs/**(generated by separate tooling)app/kernel/SiYuan-Kernel*,*.syso,kernel/kernel.aarapp/pandoc/*- Other files marked as generated: edit their source and regenerate them instead. API declarations and schemas come from
kernel/apicontract/; attribute-view capability declarations come fromkernel/av/capabilities.go. Before changing either, read the generation instructions and output inventory in docs/API-CONTRACTS.md, including Petal synchronization
Verification and prohibited operations
- Frontend verification: Do not use
npx webpackorpnpm devto verify changes. After frontend code changes, runpnpm run lintfromapp/; it includes type checks, ESLint automatic fixes, and CSS, menu, and startup-language checks, but not behavioral tests. Review the resulting diff and keep fixes within the task scope without overwriting existing work. In read-only tasks, use applicable non-mutating checks instead, such aspnpm run typecheckand ESLint without--fixor--cache; do not run the auto-fixing lint command - Frontend build: Do NOT run
pnpm build— the developer runspnpm devmanually, andpnpm buildwill conflict with it, producing broken bundles - Kernel development: After modifying Go code, run
gofmt, but do not compile the kernel binary or restart a running kernel; the developer handles both manually. Isolated regression tests and contract generation are allowed; they must not replace the product binary or restart the running instance - Git: NEVER run
git commit/git pushunless explicitly asked — no exceptions - UI verification in a browser: Open
/stage/build/desktop/directly instead of/. The kernel selects the frontend bundle by User-Agent inkernel/server/serve.go, and a UA containingElectronis redirected to the Electron-only/stage/build/app/, which fails in a plain browser withrequire is not defined; VSCode's built-in browser sends such a UA. The Electron main window does not expose a remote debugging port by default - Verification scope: Run the checks and regression tests applicable to the changed behavior, including non-API Go code, frontend interactions, and scripts. Select scope according to impact and risk; a full suite is not required for every task, and lint or formatting alone does not establish behavioral correctness. Use
app/scripts/test.mjsand the relevant maintenance guides to identify test discovery and commands. For frontend changes,pnpm run test:affectedfromapp/derives the affected tests from the changed files (it follows both imports and the source paths that tests read and evaluate themselves) and runs only those;pnpm run test:changedlists them without running. Fall back to the full suite when a change crosses many modules or touches shared setup, and say which scope you ran. For documentation-only changes, check accuracy, links, language alignment, and the diff rather than running auto-fixing code checks. Report passed, failed, and unrun checks with their limits; do not infer that tests passed solely from a successful CI job or release - Test synchronization: Whenever code or files change, handle the corresponding tests and fixtures in the same change rather than leaving them for later
- Rename, move, merge, split, or delete a test file together with its source, and keep the file name reflecting the code it covers; a test file whose source no longer exists or whose name no longer matches is stale and must be repaired or removed
- When behavior changes intentionally, update the affected assertions, case names, and comments to the new contract instead of dropping the coverage; when behavior is removed, delete only the cases that cover the removed behavior and keep adjacent assertions
- Keep test doubles aligned with the code under test: remove mocks of exports, constants, flags, and helpers that no longer exist, and do not preserve assertions that only pass because a stale stub keeps them alive
- Do not use a test that already fails for unrelated reasons as permission to leave a new mismatch; state such failures separately and verify whether the task changed their outcome
- Merge test files only when they cover the same subject and merging removes duplication without losing cases or discoverability; otherwise keep the current split
- Run the affected tests after the synchronization, and name the files and cases that were updated, merged, or deleted
Encrypted notebook compatibility
- Encrypted notebook development is complete. Maintain it as a released feature
- Existing encrypted data is the compatibility baseline. Upgrades must preserve access and recovery; do not treat it as disposable development data or require users to delete or recreate it
- Changes to document, asset, attribute-view, key-envelope, backup, history, or sync formats must retain authenticated reads of supported existing formats or provide a recoverable migration before removing a reader
- Changes to envelopes, AAD semantics, or key derivation must use an explicit format version and a compatibility plan. Migration must authenticate the source, preserve recovery material, and remain recoverable after failure or interruption; never regenerate MasterSalt or discard keys to work around incompatibility
- Unknown formats, corruption, and authentication failures must preserve the original data and return an error; compatibility must not bypass authentication or fall back to plaintext. Derived indexes may be rebuilt after the source ciphertext authenticates
- Format changes require regression coverage using fixtures from the supported previous format, including the affected read, export, history, backup, and recovery paths. See
docs/ENCRYPTED-NOTEBOOK.mdanddocs/ENCRYPTED-NOTEBOOK.zh-CN.md; keep their compatibility policies aligned
2. Project-specific rules
i18n:
- New keys go at the top of each
langs/*.jsonobject; add to every language file (referenceen.json) - Indent
langs/*.jsonwith tabs, using one tab per nesting level; do not use spaces for indentation - Exception: inside the
_kernelobject, append new entries at the end using the next incremental numeric key - Each language must be properly translated — do NOT copy the same text across all language files
- Use three ASCII periods (
...) for ellipses in all localized strings; do not use Unicode ellipsis characters (…or……) - Setting description tip strings must not end with a period or equivalent sentence-ending mark (for example
.,。, or।) - User-facing error messages must not end with a period or its language-specific equivalent (for example
.,。, or।); preserve punctuation between sentences and apply this rule consistently across all languages, including_kernelmessages - Domains:
ld246.comonly inzh-CN.json; useliuyun.ioin all other languages - In
zh-TWlocalization and the Traditional Chinese user guide, consistently translate the content-model term Block as區塊, including compounds (e.g.子區塊,程式碼區塊,區塊 ID); never abbreviate it as塊, and count blocks with個區塊 - Translate Block Reference as
區塊引用and Blockquote as引述區塊; preserve non-content-block terms such as分塊(data chunks) and覈取方塊(Checkbox) - Preserve each
_kernelmessage's Go format argument positions and verbs fromen.json; when translation requires a different order, use explicit argument indexes such as%[4]sand%[3]d. Preserve%%for literal percent signs - After modifying i18n files, run
python scripts/check-lang-keys.pyto verify key completeness and kernel format argument compatibility across all language files
- New keys go at the top of each
Cross-platform scripting:
- Do not assume the current shell is Bash, zsh, or PowerShell. Confirm the shell before using shell-specific syntax; otherwise avoid constructs such as
&&, heredocs, and/dev/null - For simple sequences, use separate command calls and set the command working directory instead of chaining
cdwith another command - For multi-step logic, write and run a temporary Node.js or Python script. On Windows, avoid PowerShell unless necessary
- Do not pass non-ASCII text through shell pipelines, PowerShell here-strings,
python -c, ornode -e; write the text to a UTF-8 file with a file-editing tool and consume that file instead
- Do not assume the current shell is Bash, zsh, or PowerShell. Confirm the shell before using shell-specific syntax; otherwise avoid constructs such as
Icons: Do not hand-write SVG; use existing icons from
app/appearance/icons/litheness/icon.jswhen possible- If no existing icon is suitable, source one from the official Lucide icon library and adapt only attributes such as stroke width to match the established icon style; preserve the upstream path data
- When adding an icon to
app/appearance/icons/litheness/icon.js, add its preview entry toapp/appearance/icons/index.htmlin the same change and keep the order aligned
User guide: When editing the user guide, follow
docs/SY-FORMAT.md- User-guide changes must be synchronized across all four bundled languages: English (
app/guide/20210808180117-6v0mkxr), Simplified Chinese (app/guide/20210808180117-czj9bvb), Traditional Chinese (app/guide/20211226090932-5lcq56f), and Japanese (app/guide/20240530133126-axarxgx). Do not omit Japanese or discover corresponding pages only by Chinese/English title matching - Before finishing a guide change, enumerate the language directories under
app/guide/and verify the corresponding section in each language. Translate the content, preserve existing document/block IDs, generate fresh IDs for new blocks, and validate the changed.syJSON.docs/developer documentation does not replace the bundled user guide - When a feature adds or changes shortcuts, update the shortcut documentation in the user guide in the same change; if the appropriate section is unclear, ask the user where it should be placed
- Outside list items, complete prose paragraphs must end with appropriate punctuation for their language (for example
.,。,?, or!); use a colon when introducing following content. Headings, navigation/reference directories, short labels, standalone links, and code, formulas, or technical syntax are exceptions and must not receive punctuation mechanically - List item text must not end with a period or equivalent sentence-ending mark (for example
.,。, or।) - Represent in-app UI navigation paths as segmented
kbdtext marks: use oneNodeTextMarkwithTextMarkType: "kbd"per navigation level, and place a plainNodeTextcontaining-between adjacent levels - In every language, separate a
kbdpath from adjacent prose with exactly one ASCII space on each side, except at block boundaries, after full-width punctuation, or before any punctuation. Half-width punctuation before the path still requires a space; keep internal-separators unchanged
- User-guide changes must be synchronized across all four bundled languages: English (
Git:
- Branch policy is repository-specific: in
siyuan-note/siyuan, usedevas the baseline source branch and default working branch. Ifdevis unavailable, use the repository's verified default branch. Do not commit on or push tomasterwhiledevis available; whendevis unavailable andmasteris the verified default branch, it is permitted - Select the working branch from the user's requested outcome. For direct commits and explicitly authorized pushes, use the selected baseline as the working branch, commit branch, and push destination unless the user explicitly requests a task branch. When the user explicitly requests an ordinary development pull request, create a task branch from the verified baseline before the first change and use it as the PR head, including when the authorized push destination is a fork; a shared baseline branch such as
dev, or a fork mirror of it, must not be used as the PR head except for the official release workflow below. GitHub does not support changing an existing PR's head branch, so verify the head before creating the PR. Creating a branch does not authorize committing or pushing without the user's authorization. Do not create or push a task branch merely to isolate changes or because the selected working branch has uncommitted work or is behind the remote - Official releases: Before release work, read and follow docs/RELEASE-VERIFICATION.zh-CN.md for preparation, build verification, integration, and history synchronization. Build from a verified
devcommit and keep it fixed until the release PR is merged; if it advances, stop and reconcile the build inputs. With authorized release integration, usedevas the PR head andmasteras the base, the sole exception to the shared-branch PR rule. Use a merge commit; if repository settings prohibit it, report the limitation instead of substituting squash or rebase. Verify the resultingmastertree against the package build commit before creating a release tag - Release history and authorization: Before further development, merge the released
mastercommit back intodev, preserving both histories and verifying an unchanged released code tree when no subsequent code changes have occurred. Perform this synchronization only with authorization for the merge and explicit authorization for its push. The release exception does not authorize direct commits or pushes tomaster, or unrequested PR merges, tags, uploads, or publication - In other repositories, follow their own branch rules for baseline selection and work; otherwise prefer
devwhen it exists locally or on the remote, and use the repository's actual default branch whendevdoes not exist. Do not extend SiYuan'smasterprohibition to other repositories or assume their default branch is namedmasterormain - If the intended branch cannot be determined confidently from the user's instructions, the repository's rules, and local or remote branch information, ask the user which branch to use and wait for their answer before editing, committing, or pushing; do not guess or silently choose a fallback
- Before editing, verify the repository and current branch. Before every explicitly authorized commit or push, verify the current branch again and, for a push, the destination remote and branch; never rely only on the upstream configuration. If SiYuan is checked out on a branch other than the selected working branch, switch to the selected working branch before making changes, or create and switch to a task branch based on the selected baseline when the user explicitly requests a pull request or task branch; preserve existing work and do not reset or discard it to switch branches
- When explicitly asked to commit, follow the style of recent commits (gitmoji prefix + subject, in English)
- Append the full issue/PR URL to the end of the commit title (e.g.
https://github.com/siyuan-note/siyuan/issues/<NNN>, not the#NNNshort form — it is clickable) only when a related issue exists; never put the URL in the commit body, and do not fabricate one - When creating a pull request, write an English title without a gitmoji shortcode or emoji prefix. Describe the final change in the PR title instead of copying a commit title with its gitmoji prefix or appended issue URL
- Branch policy is repository-specific: in
GitHub: Prefer the GitHub CLI (
gh) for all GitHub operations, including reading issues, comments, pull requests, commits, statuses, and metadata. Ifghis unavailable or does not support the operation, fall back to the GitHub API or web interface- File issues about dependencies maintained by the SiYuan organization and used by SiYuan in
siyuan-note/siyuan, even when the affected code lives in a dependency repository. Identify the dependency, affected implementation, and cross-repository work in the issue body; implement and verify dependency changes in their own repositories and link their commits or pull requests back to the SiYuan issue. Do not create a duplicate issue in the dependency repository or move an existing issue without explicit authorization - When creating an issue in this repository, use an English title and a Chinese body whose first paragraph is the corresponding Chinese title; do not use this repository's own issue templates or reproduce their form fields, and write a task-specific body directly. Preserve the relevant details from the discussion, including the problem, reproduction steps, expected and actual behavior, evidence, agreed approach, constraints, compatibility concerns, alternatives and tradeoffs, acceptance criteria, and unresolved questions, as applicable. Remove repetition and unrelated material, but do not omit information needed to understand, evaluate, or implement the issue merely to make it shorter
- Before filing an issue or pull request in any other repository, read that repository's own templates first and follow the one matching the task: check
.github/ISSUE_TEMPLATE/(issue forms and Markdown templates) and the PR template, then fill every section it marks as required. The conventions above — an English title, a Chinese body, and bypassing the templates — apply only to this repository and must not be carried over. Confirm separately whether and where the project accepts issues and pull requests; do not infer whether pull requests are accepted from mirror status or disabled issues. Identify the correct issue tracker (for example,golang/gocarries gopls issues, notgolang/tools) and code contribution destination before submitting - When changing the title of an existing issue, keep the replaced title as the first paragraph of the body, separated from the remaining content by a blank line, and keep the rest of the body unchanged
- When replying to an issue or pull request, explain the conclusion and its basis with detail proportional to the task. Include relevant implementation decisions, behavior changes, compatibility concerns, and unresolved issues. Report only verification and tests actually performed and the conclusions they support; do not list unperformed tests. Briefly disclose any verification gap that materially limits the conclusion, and never imply broader coverage than was verified. Avoid routine logs and unrelated commands. For implemented changes, invite the user to test the new version and provide feedback. If the issue or pull request body is in Chinese, reply in Chinese; otherwise, reply bilingually in the language of the body and Chinese.
- Published text must stand on its own. Readers of an issue, comment, or pull request do not see the conversation that produced it, so do not write "the previous comment", "my earlier estimate", "last time", "as mentioned above", or similar relative references unless that content exists on the same item, is unambiguous to a reader, and is linked. When revising text you already published, edit it in place and state the correct fact, value, or behavior directly instead of narrating that a correction is being made. Never refer to an earlier comment, edit, or discussion you have not confirmed exists on the remote, and do not state how many comments or revisions exist without checking
- When the selected endpoint supports labels, they may be included in the same create or update payload. Verify the issue or pull request identity and the requested non-label changes, including title, body, state, or base branch as applicable. The exception applies only to labels: do not check whether they were applied or send a follow-up request solely to apply them, and do not claim they were verified; GitHub may silently drop label changes when the actor lacks push access
- For GitHub write operations containing non-ASCII text on Windows or when shell encoding is uncertain, use this file-based workflow. Do not use this workflow for ASCII-only requests:
- Create the request payload as UTF-8 JSON with a file-editing tool, not an inline shell command
- Store it in the operating system's temporary directory with a unique name such as
siyuan-gh-<operation>-<timestamp>.json; do not leave temporary payloads in the repository - Call the appropriate endpoint with
gh api --method <method> "<endpoint>" --input "<absolute-json-path>" - Inspect the returned resource and read it back with
gh api. Prefer parsing JSON and comparing its fields with the submitted payload to verify the published text exactly, including line breaks and non-ASCII characters. Normalize CRLF to LF if needed, but preserve meaningful leading/trailing whitespace and blank lines. For--jqtext output, query one field per call (for example.titleand.body) and remove only the single output line terminator added by the command - Keep the submitted payload until comparison passes; then delete temporary payload and read-back files and confirm their removal
- Prefer capturing
ghstdout directly in a Node.js or Python script and decoding it as UTF-8. When using PowerShell to save output, explicitly useOut-File -Encoding utf8; Windows PowerShell 5.1 defaults to UTF-16LE for>andOut-File, and its UTF-8 output includes a BOM, so readers must handle that BOM. Explicit file encoding cannot repair text already corrupted by pipeline decoding; use direct process capture in that case gh apiapplies--jqlocally after sending the request, so an invalid or failing expression can cause a non-zero exit even when the write succeeded. Omit--jqon write commands and use separate read-back calls to verify individual fields. When a write command exits non-zero, confirm the remote state before deciding whether to retry; the write may already have succeeded, and retrying can create duplicate issues or comments or repeat other side effects
- File issues about dependencies maintained by the SiYuan organization and used by SiYuan in
Issue titles: Whenever the user asks to generate an issue title, provide it in English regardless of the wording of the request, and do not start it with
Fix. These rules choose title wording from the issue's nature; they are not an instruction to apply GitHub labels- For a bug, objectively describe the problem or symptom instead of writing from a bug-fix perspective
- For an improvement to existing functionality, write the title from an improvement perspective and prefer
Improve ... - For a capability that did not previously exist, write the title from a support perspective and prefer
Support ... - If the nature is unclear, infer the perspective from the issue content
LD246:
- When accessing
ld246.com, set the HTTPUser-Agentheader toSiYuan-Coding-Agent - Read post details with
GET https://ld246.com/api/v2/article/{articleId}?p=1;data.articlecontains the post, andppaginates replies. For Markdown, useGET https://ld246.com/article/raw/{articleId} - Publish a reply with
POST https://ld246.com/api/v2/comment, sendingarticleIdandcommentContentin the JSON body; optionally includecommentOriginalCommentIdwhen replying to an existing comment - Authenticate these endpoints with
Authorization: token <LD_TOKEN>using the environment variable; on Windows, check process, user, then machine scope. Do not expose the Token or rely on UA exemptions - Check HTTP status and JSON
code(0means success); report missing credentials or authentication errors
- When accessing
Configurable entries:
- Treat configurable desktop menu
data-idvalues and stable dock entry keys as persisted configuration identifiers. Resolve dock keys throughgetDockEntryKeyinapp/src/config/entryVisibility/catalog.ts: it prefersdata-entry-id, maps plugin runtime types to stable keys derived from plugin name and dock ID, and falls back to the built-indata-type. Do not rename or reuse persisted keys unless the same change migrates existing visibility and order configuration - When adding, removing, renaming, or moving a configurable desktop menu item or dock entry, or changing its identifier mapping, update
app/src/config/entryVisibility/catalog.tsin the same change, including its type, hierarchy, label, Simple profile default, and default position, and update the related tests - Give every configurable desktop menu separator a stable
data-idand register it in the catalog as aseparator. Keep the catalog order aligned with the actual menu declaration order because it defines the built-in order and where new entries are merged into existing custom profiles - Keep parent and child paths aligned with the actual menu hierarchy. Dock entries support visibility, ordering, and movement across the six scopes in
dockOrder.ts; use that mechanism rather than treating dock entries as ordinary menu siblings. Preserve existing placement, hidden entries, unavailable plugin slots, and compatibility with profiles that have no dock orders - Cover catalog consistency, separator placement, order migration, and plugin-slot preservation in the related tests. Configured menus must not produce leading, trailing, or consecutive separators
- The menu
ignoreoption controls conditional rendering and must not be used to opt an entry out of visibility or order configuration
- Treat configurable desktop menu
API contracts:
- Follow docs/API-CONTRACTS.md when adding or changing kernel HTTP APIs. Define new endpoints in
kernel/apicontract/and bind their handlers throughcontractHandler; keep contracts synchronized when changing existing endpoints - Treat
docs/API-CONTRACTS.mdand its localized versions as maintenance guides. For routine endpoint or feature changes, do not append endpoint-specific behavior, feature summaries, verification results, or focused test commands. Update these guides only when the contract mechanism, compatibility policy, generation workflow, or test discovery/verification rules change, or when the user explicitly requests a documentation update; keep localized versions aligned - Document endpoint behavior, defaults, constraints, and compatibility in comments on the corresponding contract source declarations. Synchronize plugin-facing explanations in the corresponding maintained declarations in
petal, following the Petal documentation rule below. Put user-facing feature instructions in the bundled user guide - Do not automatically add newly implemented endpoints to
docs/API.mdor its localized versions (docs/API.zh-CN.md,docs/API.ja.md); add such documentation only when explicitly requested by the user. Continue maintaining API contracts, generated declarations, and required regression tests. These documentation scope rules take precedence over broader documentation instructions in the maintenance guides - After changing an existing endpoint's request, response, or documented behavior, check its existing reference entries in
docs/API.md,docs/API.zh-CN.md, anddocs/API.ja.md. Update affected entries together; do not assume the language versions cover identical endpoints. Newly added endpoints remain documented only on request - Preserve existing input compatibility, response variants, authorization, and encrypted notebook lease behavior; cover affected behavior with regression tests
- Every route must have a typed contract; remove both the registration and contract when deleting a route, and never bypass contract checks with
anyor type assertions - After contract changes, run
pnpm run api:generate --petal ../../petalandpnpm run api:check --petal ../../petalfromapp/; verify the Petal checkout first using the cross-repo rules below. The example path is relative to the generator'skernel/working directory and assumes a siblingpetalrepository; substitute the verified path when different. Synchronize related public declarations inpetaland do not hand-edit generated declarations or schemas - Run
pnpm run lintfromapp/,go test ./apicontract/...fromkernel/, and the applicable API compatibility and route coverage tests described in the maintenance document. Verify that existing CI selections and documented commands discover new regression cases; automatic discovery or coverage by an existing full-suite command satisfies this requirement without a documentation edit. Update CI selections and documented commands only when they would otherwise miss the new tests. Report task-specific verification commands and results in the task response or PR description
- Follow docs/API-CONTRACTS.md when adding or changing kernel HTTP APIs. Define new endpoints in
Desktop and mobile parity:
- When changing functionality shared by desktop and mobile, inspect the corresponding mobile implementation under
app/src/mobile/and update it in the same task. This includes menus, toolbars, dialogs, interactions, and their event handlers; do not assume that desktop changes automatically apply to mobile - Before finishing, verify both implementations and their shared dependencies, preserving platform-appropriate interactions. If no corresponding mobile feature exists or the change is desktop-only, state why mobile changes are not needed in the task response
- When changing functionality shared by desktop and mobile, inspect the corresponding mobile implementation under
UI copy and user guides: Change wording only when needed, following nearby style and keeping necessary guidance and warnings. Put specific instructions beside the relevant control or in the corresponding guide section; do not overload general descriptions with feature lists or implementation details
Configuration defaults: Put a new setting's default value in its constructor (
NewAppearance,NewEditor,NewFileTree, etc.) and let the shared normalization functions fill missing containers and values.InitConfonly projects runtime state and runs versioned migrations; do not add a startup function that patches a single defaultconf.jsonwritten by an older version has no key for a new field, and configuration sections unmarshal into zero values, so a plainboolis only correct when the default isfalse- A default of
truerequires*bool(and a defaulted non-zero enumeration requires*int): initialize it in the constructor, keep thenilbranch in normalization, and preserve an explicitly savedfalse. SeeFileTree.CreateDocAtTop,Editor.CheckBlockRef, andSearch.HanSensitive - Keep a default-
trueplainboolonly when existing workspaces must stayfalsewhile new workspaces starttrue, as withAppearance.MenuMouseScroll: the constructor supplies the new-workspace value and the zero value supplies the existing-workspace one POST /api/setting/set<Section>merges the request into the current section: omitted fields keep their current value andnullrestores the default; declareMergeonSettingWriteinstead of adding per-field preservation branches. Decoding starts from the section constructor defaults sonullnever falls back to a zero value- Keep
*boolon the API request and response declaration when the wire format must distinguishnull, even if the persisted configuration uses a plainbool; seeapicontract.SettingFileTree - When an existing workspace must retain a legacy default that is not the zero value (for example
OCR.Auto), resolve it in the load path that knows whetherconf.jsonexisted; do not read that fact from a global inside a constructor or normalization helper. Resolve a segment that exists but lacks the decisive field the same way as a missing segment
3. Coding conventions
Comments: Write in Chinese, wrap at 120 characters, and state the behavior in effect now; do not narrate how the code got there or describe it relative to a previous implementation (
不再创建、保留旧行为), and drop any comment that only restates the next line- Keep an issue link only when it explains why the current rule exists
- Legacy data is the exception: deprecated fields and format migrations must still say which older shape they read
Punctuation: Use language-appropriate punctuation in UI text, comments, user guides, and documentation (e.g. Chinese punctuation ,。:;!?「」 for Chinese). Keep UI text and its punctuation in i18n language files rather than hard-coding them in code
UI paths: In all contexts, including code comments, UI text, i18n, user guides, documentation, issue/PR content, and responses, separate navigation levels with a hyphen surrounded by spaces (for example,
设置 - 快捷键 - 通用); do not use arrow symbols such as→Markdown: Do not hand-wrap; keep each line (paragraphs, table rows, list items, etc.) on a single line
TypeScript/JavaScript: Semicolons required, use double quotes, indent with spaces
- When moving or extracting a symbol into another module, update all affected imports to reference its defining module directly. Do not leave forwarding re-exports in the original module merely to avoid updating callers
CSS: Do not use the
:has()selector because of its performance impact, and prefer a comma-separated selector list over:is(), whose extra matching layer adds measurable cost- Expand selector groups instead of grouping them with
:is()or:where(); use:where()only to drop specificity from a single selector - Before adding or styling a basic control, inspect and reuse the existing component, markup pattern, and shared styles in
app/src/assets/scss/component/(for example,b3-button,b3-select, andb3-text-field), including existing modifiers; useblock__iconfor established icon-button patterns - Apply the same reuse-first rule to menus, dialogs, tooltips, and drag interactions: inspect existing implementations and APIs before adding a feature-specific replacement
- For single-choice enumerations in menus, use submenu items with the current option checked rather than embedding a select control. Show a right-arrow indicator on the parent item, open its submenu on hover on desktop, and support tapping on mobile. Reuse the existing menu implementation and positioning behavior
- Feature styles should describe layout (such as placement, width constraints, gaps, and wrapping), rather than duplicate or override basic control appearance (such as height, padding, typography, colors, borders, shadows, and hover/focus/disabled states). Do not use deeper selectors, inline styles, or
!importantmerely to restyle a shared control - If existing controls cannot meet a requirement, explain the concrete need and prefer extending a shared component or modifier when the need is reusable. Keep necessary feature-specific exceptions narrowly scoped; use theme variables for appearance and retain keyboard focus and disabled feedback
- Reuse components according to their purpose; do not borrow an unrelated component (for example, menu items for a form) and then cancel its styles. Preserve useful feature classes as theme hooks when switching to shared controls
- When reviewing control-style changes, check consistency with shared controls, theme overrides through shared classes, light/dark themes, narrow layouts, and large editor fonts. Preserve necessary layout and touch-target constraints; do not remove all feature styles indiscriminately
- Expand selector groups instead of grouping them with
CSS positioning and scrolling: When changing
position,transform,contain, oroverflowon a shared container, check the effects on descendant positioning reference frames, overlay coverage, and clipping. Prefer a dedicated container when a local control needs a positioning reference. For settings dialog changes, verify detail overlays, the top drag area, and scrollbar placement at different window widthsCustom attributes:
- HTML custom attributes used only for DOM/UI state must use the
data-prefix without an extrasynamespace, for exampledata-ui-density - Custom attributes owned by built-in features and persisted in notebook, document, or block data must use the
custom-sy-prefix. Preserve existing persisted attribute names and their compatibility; DOM/UI naming changes must not rename these data attributes - Define custom attribute name constants in
app/src/constants.ts, alongside similar constants inConstants, rather than in individual feature modules
- HTML custom attributes used only for DOM/UI state must use the
Frontend preference storage: Do not use browser
localStoragedirectly, includingwindow.localStorageandglobalThis.localStorage- New user-facing preferences, including settings switches and explicit reader or panel preferences, default to
conf.json; define them in the corresponding configuration namespace, normalize them in the kernel, and write throughcreateConfigNamespaceApi().patch - Reserve
local.jsonfor growing mappings keyed by document, view, or transaction IDs; transient or session state such as scroll positions, dialog geometry, and restored tabs; usage history and reading positions; and plugin runtime state - Writing frequency does not determine storage:
uiLayoutis already a frequently updated configuration namespace with silent notifications. Neitherconf.jsonnorlocal.jsonparticipates in data sync; configuration export includesconf.json - Read local state from
window.siyuan.storage; when changing it, update its in-memory value and persist it withsetStorageValfromapp/src/protyle/util/compatibility.ts. SiYuan persists these values in the workspace'sdata/storage/local.json; do not use browserstorageevents to observe changes to this store
- New user-facing preferences, including settings switches and explicit reader or panel preferences, default to
Frontend platform identification:
- Use the mutually exclusive
bodyclass names written byapplyPlatformClasses()inapp/src/protyle/util/compatibility.ts:body--mac,body--windows,body--linux,body--ios,body--android, andbody--harmony body--win32andbody--win32-browserare retained only for existing third-party themes; use neither in new code, and do not add consumers when changing related styles- Do not derive the frontend platform from the kernel reported container or from
data-backend: a remote kernel reports its own host, so both differ from the platform of the current frontend data-frontendon the root element reports the frontend form (desktop,desktop-window,mobile,browser-desktop,browser-mobile) and may be used by built-in styles and third-party theme CSS;data-backendon the root element is for third-party JavaScript only and must not appear in built-in CSS
- Source file headers:
kernel/**/*.goandapp/electron/main.jsstart with exactly these three lines, then one blank line// SiYuan - https://github.com/siyuan-note/siyuan // Copyright (c) 2020-present, b3log.org // SPDX-License-Identifier: AGPL-3.0-or-later- Sources in other languages carry no header; remove it from a non-Go file that still has one instead of extending the convention
//go:buildfollows the header after a blank line and needs its own blank line beforepackage; a build constraint without that blank line silently stops applying- Do not add this header under
kernel/plugin/encoding/(grafana/sobek-webapi-encoding, Apache-2.0) orkernel/heif/internal/h265heic/(roticv/h265, MIT); those subtrees keep their own license and a SiYuan header there would overwrite it scripts/check-license-headers.mjschecks both directions; the scopes are declared inscripts/license-header.mjs. CI runs it as a non-blocking step, so run it yourself before committing header changes
4. Required toolchain
| Tool | Version | Source of truth |
|---|---|---|
| Go | see go directive |
kernel/go.mod |
| Node (+ pnpm) | see CI matrix | .github/workflows/cd.yml, app/package.json (packageManager field) |
5. Repository layout
Architecture: Go kernel (kernel/) + TypeScript frontend (app/). Read versions from kernel/go.mod, app/package.json, kernel/util/working.go.
Top level (repo root):
| Path | Contents |
|---|---|
kernel/ |
Go backend — server, data engine, API, all domain logic |
app/ |
TypeScript frontend (Electron/web), built by webpack into app/stage/build/ |
app/appearance/ |
Themes, icons, i18n (appearance/langs/*.json) |
app/stage/ |
Build output served by the kernel |
app/changelogs/ |
Per-version changelog markdown |
.github/ |
Contribution and security policies, issue/PR templates, CI workflows |
scripts/ |
Release packaging, changelog generation, language-key checks |
Major kernel/ packages (under kernel/)
| Package | Responsibility |
|---|---|
main.go (//go:build !mobile) |
Desktop entry point, delegates to cli/cmd |
cli/cmd/ |
Cobra CLI subcommands |
model/ |
Core domain: blocks, transactions, indexing, search, attribute views, export, history, sync, flashcards, AI, CalDAV/CardDAV, auth |
treenode/ |
In-memory tree over the Lute AST + blocktree.db |
av/ |
Attribute View (database) engine: values, filters, sorts, layouts (table/kanban/gallery) |
sql/ |
Embedded SQLite (siyuan.db, history.db, asset_content.db) + FTS5; async index queues |
search/ |
FTS tokenizer helpers, CJK conversion (hanconv.go) |
bazaar/ |
Marketplace: plugins/widgets/themes/icons/templates |
filesys/ |
Read/write .sy files on disk (via filelock) |
server/ |
Gin server bootstrap (serve.go): middleware, TLS/cmux, WebDAV/CalDAV/CardDAV, WebSocket, MCP |
api/ |
HTTP route registration (router.go::ServeAPI) + per-area handlers |
conf/ |
Configuration structs |
util/ |
Cross-cutting: working.go (workspace, Boot()), lute.go, i18n.go, websocket.go (melody push), result.go (API envelope) |
plugin/ |
Plugin subsystem (kernel side) |
mcp/ |
MCP (Model Context Protocol) server |
agent/ |
AI agent runtime |
mobile/, harmony/ |
//go:build mobile gomobile bindings for Android/iOS/HarmonyOS |
Frontend (app/src/) highlights
| Dir | Purpose |
|---|---|
index.ts |
Main App class — boots SPA, opens main WebSocket, handles WS push events |
window/ |
Detached Electron window variant |
protyle/ |
Block editor; rich-content rendering in render/, attribute-view rendering in render/av/ |
editor/, layout/, menus/, dialog/, config/, mobile/, ai/, sync/, history/, search/, card/ |
Feature modules |
util/fetch.ts |
fetchGet/fetchPost — all kernel calls |
layout/Model.ts |
WebSocket client all UI binds to |
constants.ts |
Global constants (version, IDs, storage keys) |
Four webpack configs emit bundles to app/stage/build/{app,desktop,mobile,export}/; the kernel's serveAppearance selects the app bundle by User-Agent. The export bundle is a rendering library (global Protyle, entry app/src/protyle/method.ts) for code, math, and diagrams. Pages assembled by app/src/protyle/export/index.ts load it for desktop PDF preview and standalone exported HTML.
6. Related repositories (navigation)
| Repo | Role / what to know |
|---|---|
siyuan-android / siyuan-ios / siyuan-harmony |
Native apps wrapping the gomobile kernel; read each project's README for platform-specific build, kernel-binding, and integration steps |
siyuan-chrome |
Independent TypeScript browser extension (web clipper); interacts with the running kernel only through the HTTP API in docs/API.md |
siyuan-testing |
Playwright end-to-end tests for a running SiYuan instance; test data belongs in the SiYuan Testing notebook — see that repository's AGENTS.md |
petal |
SiYuan Plugin API declaration (the plugin system is named "petal"); consumed by plugins, not a kernel Go dependency |
lute |
Markdown/Kramdown AST engine for the editor and .sy format; source of lute.min.js. The maintainer's default checkout is $GOPATH/src/github.com/88250/lute, not a sibling repo; verify the actual checkout before use |
dejavu |
Data repo / sync engine (encrypted snapshots) |
riff |
Spaced-repetition (SRS) flashcard scheduler |
gulu / eventbus / filelock / httpclient / logging |
General utilities, in-process events, file locking, HTTP client, and logging |
go-sqlite3 / pdfcpu |
Maintainer's forks, pulled in via permanent replace in kernel/go.mod (keep those) |
epub / clipboard / go-humanize / vitess-sqlparser / dataparser / encryption |
Smaller Go libraries (export / clipboard / formatting / SQL parse / data parse / crypto) |
All Go libraries above are dependencies in kernel/go.mod. GitHub org: siyuan-note/* for the siyuan- apps and most libs; 88250/* for lute, gulu, and the forks (go-sqlite3 / pdfcpu).
Cross-repo notes
- Checkout availability: Before cross-repo work, verify each checkout's path, identity, branch, baseline, and existing changes under its own rules. If a required checkout is unavailable, complete independent work where possible and report the exact synchronization or verification blocker; do not claim the task is fully synchronized. These rules do not authorize automatically creating or downloading another repository
- Editing Go dependencies: To test a local change, add a temporary
replaceinkernel/go.modpointing at your local checkout; never commit that temporaryreplace. - Rebuilding
lute.min.js: Changelute, rebuild with GopherJS, and copy the artifact intoapp/stage/protyle/js/lute/. - Type declarations: when changing files under
app/src/types/or other TypeScript declarations and constants exposed to plugins, synchronize the corresponding declarations and constants in thepetalrepository in the same task. - Petal changelog: Whenever changing files in the
petalrepository, updatepetal/CHANGELOG.mdin the same task. Add a concise entry under the current unreleased version before committing the Petal change. - Petal documentation: Keep
petal/README.mdlimited to the project title and theplugin-samplelink. Do not add feature descriptions, API usage explanations, or code examples to the README. Document API behavior, constraints, and lifecycle in comments on the corresponding API declarations inpetal; put executable usage examples in the actual source code ofplugin-sample.
7. Response style
- Language: Match the user's language; do not mix languages mid-sentence (keep proper nouns / identifiers in their original form)