Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

:memo: Clarify repository rules and verification scope

Daniel241e2a44a1a4
diff --git a/AGENTS.md b/AGENTS.md
index 30bd7bc407..eed54292e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,8 +8,8 @@ SiYuan repository guide. Module path `github.com/siyuan-note/siyuan`, license AG
### Verify the code baseline before repository tasks
-- Before each new repository task, select the baseline source branch using the repository-specific branch policy in section 2's Git rules, fetch the relevant remote refs, and verify the task's code baseline before analysis or other work. Respect explicitly requested commits, tags, or pull requests
-- 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. Automatically fast-forward an existing branch only when its working tree is clean and it is merely behind. Rebase is permitted when synchronizing divergent branches, provided existing work is preserved; this does not authorize force-pushing rewritten history. 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
+- 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
@@ -32,14 +32,16 @@ Unambiguous mechanical edits with no behavioral or compatibility impact need no
- `app/changelogs/**` (generated by separate tooling)
- `app/kernel/SiYuan-Kernel*`, `*.syso`, `kernel/kernel.aar`
- `app/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 from `kernel/av/capabilities.go`. Before changing either, read the generation instructions and output inventory in [docs/API-CONTRACTS.md](docs/API-CONTRACTS.md#generation-and-verification), including Petal synchronization
### Verification and prohibited operations
-1. **Frontend verification:** Do not use `npx webpack` or `pnpm dev` to verify changes; after changes, run `pnpm run lint` with `app/` as the working directory to check code style
+1. **Frontend verification:** Do not use `npx webpack` or `pnpm dev` to verify changes. After frontend code changes, run `pnpm run lint` from `app/`; 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 as `pnpm run typecheck` and ESLint without `--fix` or `--cache`; do not run the auto-fixing lint command
2. **Frontend build:** Do NOT run `pnpm build` — the developer runs `pnpm dev` manually, and `pnpm build` will conflict with it, producing broken bundles
-3. **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
+3. **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
4. **Git:** **NEVER** run `git commit` / `git push` unless explicitly asked — no exceptions
5. **UI verification in a browser:** Open `/stage/build/desktop/` directly instead of `/`. The kernel selects the frontend bundle by User-Agent in `kernel/server/serve.go`, and a UA containing `Electron` is redirected to the Electron-only `/stage/build/app/`, which fails in a plain browser with `require 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
+6. **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.mjs` and the relevant maintenance guides to identify test discovery and commands. 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
### Encrypted notebook compatibility
@@ -85,7 +87,8 @@ Unambiguous mechanical edits with no behavioral or compatibility impact need no
5. **Git:**
- Branch policy is repository-specific: in `siyuan-note/siyuan`, use `dev` as the baseline source branch and default working branch. If `dev` is unavailable, use the repository's verified default branch. Do not commit on or push to `master` while `dev` is available; when `dev` is unavailable and `master` is 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 in `siyuan-note/siyuan`: prepare release changes and build from a verified `dev` commit. Keep `dev` at that commit until the release PR is merged; if it advances, stop and reconcile the build inputs before merging. When the user authorizes release integration into `master`, use `dev` directly as the PR head and `master` as the base; this is the explicit exception to the shared-branch PR rule. `.github/workflows/target-branch.yml` already permits this head through `exclude: dev`; other heads targeting `master` are redirected to `dev`. Use a merge commit for release PRs to preserve the history of these long-running branches; if repository settings prohibit it, report the limitation rather than silently substituting squash or rebase. Verify that the resulting `master` tree matches the commit used to build the packages before creating a release tag. Before further development, merge the released `master` commit back into `dev`, preserving both histories and verifying that the merge does not change the released code tree when no subsequent code changes have occurred. This also anchors a past squash release in `dev`, but does not remove its original commits from later PR commit lists. Perform this history synchronization only when the user has authorized that merge, and push it only with explicit push authorization. The release exception does not authorize direct commits or pushes to `master`, or unrequested PR merges, tags, uploads, or publication
+ - **Official releases:** Before release work, read and follow [docs/RELEASE-VERIFICATION.zh-CN.md](docs/RELEASE-VERIFICATION.zh-CN.md) for preparation, build verification, integration, and history synchronization. Build from a verified `dev` commit and keep it fixed until the release PR is merged; if it advances, stop and reconcile the build inputs. With authorized release integration, use `dev` as the PR head and `master` as 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 resulting `master` tree against the package build commit before creating a release tag
+ - **Release history and authorization:** Before further development, merge the released `master` commit back into `dev`, 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 to `master`, or unrequested PR merges, tags, uploads, or publication
- In other repositories, follow their own branch rules for baseline selection and work; otherwise prefer `dev` when it exists locally or on the remote, and use the repository's actual default branch when `dev` does not exist. Do not extend SiYuan's `master` prohibition to other repositories or assume their default branch is named `master` or `main`
- 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
@@ -96,16 +99,14 @@ Unambiguous mechanical edits with no behavioral or compatibility impact need no
- When creating an issue, use an English title and a Chinese body whose first paragraph is the corresponding Chinese title; do not use the repository's 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
- 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. Preserve relevant review findings, implementation decisions, behavior changes, compatibility concerns, limitations, and unresolved questions; include testing and verification details when they help assess the conclusion, rather than replacing the explanation with a generic invitation to test. Avoid dumping routine logs or unrelated commands, and distinguish verified results from estimates, assumptions, and planned work. For implemented changes, also 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
- - When the selected endpoint supports labels, they may be included in the same create or update payload. Afterward, verify only that the issue or pull request itself succeeded (number, title, and body). Do not check whether labels were applied or send a follow-up request solely to apply them; GitHub silently drops label changes when the actor lacks push access
+ - 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:
1. Create the request payload as UTF-8 JSON with a file-editing tool, not an inline shell command
2. 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
3. Call the appropriate endpoint with `gh api --method <method> "<endpoint>" --input "<absolute-json-path>"`
- 4. Inspect the returned resource and read it back with `gh api` to verify the published text exactly, including line breaks and non-ASCII characters
- 5. Delete the temporary JSON file and confirm that it no longer exists
- - For shell-independent read-back verification, query one field per `gh api --jq` call, for example `--jq .title` and `--jq .body`
+ 4. 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 `--jq` text output, query one field per call (for example `.title` and `.body`) and remove only the single output line terminator added by the command
+ 5. Keep the submitted payload until comparison passes; then delete temporary payload and read-back files and confirm their removal
- Prefer capturing `gh` stdout directly in a Node.js or Python script and decoding it as UTF-8. When using PowerShell to save output, explicitly use `Out-File -Encoding utf8`; Windows PowerShell 5.1 defaults to UTF-16LE for `>` and `Out-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
- - Keep the submitted payload file until read-back comparison passes. Prefer parsing the returned resource as JSON and comparing its fields with the payload; normalize CRLF to LF on both sides if needed, but preserve meaningful leading/trailing whitespace and blank lines. For `--jq` text output, remove only the single output line terminator added by the command, not arbitrary trailing whitespace. Delete temporary payload and read-back files after successful verification and confirm their removal
- `gh api` applies `--jq` locally after sending the request, so an invalid or failing expression can cause a non-zero exit even when the write succeeded. Omit `--jq` on 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
7. **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
@@ -118,10 +119,10 @@ Unambiguous mechanical edits with no behavioral or compatibility impact need no
- Authenticate both 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` (`0` means success); report missing credentials or authentication errors
9. **Configurable entries:**
- - Treat the `data-id` of a configurable desktop menu item and the `data-type` of a configurable dock entry as persisted configuration identifiers. Do not rename or reuse them 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 `data-id` / `data-type`, update `app/src/config/entryVisibility/catalog.ts` in the same change, including its type, hierarchy, label, Simple profile default, and default position, and update the related tests
+ - Treat configurable desktop menu `data-id` values and stable dock entry keys as persisted configuration identifiers. Resolve dock keys through `getDockEntryKey` in `app/src/config/entryVisibility/catalog.ts`: it prefers `data-entry-id`, maps plugin runtime types to stable keys derived from plugin name and dock ID, and falls back to the built-in `data-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.ts` in 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-id` and register it in the catalog as a `separator`. 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 only and must not be included in sorting
+ - 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 `ignore` option controls conditional rendering and must not be used to opt an entry out of visibility or order configuration
10. **API contracts:**
@@ -132,7 +133,7 @@ Unambiguous mechanical edits with no behavioral or compatibility impact need no
- 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`, and `docs/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 `any` or type assertions
- - After contract changes, run `pnpm run api:generate --petal ../../petal` and `pnpm run api:check --petal ../../petal` from `app/`; synchronize related public declarations in `petal` and do not hand-edit generated declarations or schemas
+ - After contract changes, run `pnpm run api:generate --petal ../../petal` and `pnpm run api:check --petal ../../petal` from `app/`; verify the Petal checkout first using the cross-repo rules below. The example path is relative to the generator's `kernel/` working directory and assumes a sibling `petal` repository; substitute the verified path when different. Synchronize related public declarations in `petal` and do not hand-edit generated declarations or schemas
- Run `pnpm run lint` from `app/`, `go test ./apicontract/...` from `kernel/`, 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
11. **Desktop and mobile parity:**
@@ -250,7 +251,7 @@ Four webpack configs emit bundles to `app/stage/build/{app,desktop,mobile,export
| `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`. **Lives under `$GOPATH/src/github.com/88250/lute`, not as a sibling repo** |
+| `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 |
@@ -261,6 +262,7 @@ All Go libraries above are dependencies in `kernel/go.mod`. GitHub org: `siyuan-
### 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 `replace` in `kernel/go.mod` pointing at your local checkout; **never commit that temporary `replace`**.
- **Rebuilding `lute.min.js`:** Change `lute`, rebuild with GopherJS, and copy the artifact into `app/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 the `petal` repository in the same task.
diff --git a/docs/API-CONTRACTS.md b/docs/API-CONTRACTS.md
index 7708d75d2d..6f937ed494 100644
--- a/docs/API-CONTRACTS.md
+++ b/docs/API-CONTRACTS.md
@@ -12,7 +12,9 @@ This document defines type declarations, compatibility requirements, generated a
2. Bind business entry points through `contractHandler` and register their handlers with `contractRouteHandlers`, preserving route middleware order and lease scope
3. When deleting an endpoint, remove both its route registration and contract definition
4. Update actual-response, input-compatibility, and strict type tests; run generation and correct calls identified by the compiler
-5. Synchronize generated and related public declarations in `petal`; update API documentation for public endpoints
+5. Synchronize generated and related public declarations in `petal`. Maintain endpoint behavior, defaults, constraints, and compatibility in contract source comments and the corresponding maintained Petal declarations. For changed existing endpoints, check and update affected entries across `docs/API.md`, `docs/API.zh-CN.md`, and `docs/API.ja.md`; their endpoint coverage may differ. Add newly implemented endpoints to those references only when explicitly requested by the user
+
+This document and its translations are maintenance guides. Update them when the contract mechanism, compatibility policy, generation workflow, or test discovery/verification rules change, or when the user explicitly requests it. Do not append endpoint-specific behavior, feature summaries, verification results, or focused test commands for routine endpoint or feature changes. Put user-facing instructions in the bundled user guide, executable plugin examples in `plugin-sample`, and task-specific checks and results in the task response or PR description. Keep Petal's README limited to its project title and the `plugin-sample` link. Follow the documentation scope rules in [AGENTS.md](../AGENTS.md).
Generation checks inspect actual route and handler declarations to verify methods, paths, handlers, contract adapters, and authorization middleware. `define` requires an explicit authorization argument; public endpoints use `PublicAccess`, while authenticated endpoints may add `AdminAccess` and `WritableAccess`. Domain registration functions retain literal methods and paths, and `contractRouteHandlers` derives middleware from the bound endpoint. Generation rejects missing policies, mismatched endpoint bindings, and missing or reordered explicit middleware. Authorization metadata does not replace resource permissions or the global notebook lease middleware. Generation and CI reject every route without a contract and verify complete route coverage. Do not bypass contract checks with `any` or type assertions.
@@ -198,7 +200,7 @@ The generator reads the leading comments on endpoint declarations in `kernel/api
`/api/block/migrateLegacyMindmaps` is an authenticated administrator write endpoint with read-only protection and an encrypted-notebook request lease. It requires a document `id` and `notebook`, converts complete legacy `mindmap` lists in one undoable transaction after saving history, and returns `converted` and canonical `blocks` (`id`, `dom`) for the document's mind maps. Repeated requests return the current block content without reconverting lists; incomplete sources remain unchanged. Regression coverage runs with `go test -tags "fts5 sqlcipher" ./model ./api ./apicontract/... -run 'Test(LegacyMindmap|MigrateLegacyMindmaps|APIContractHeadingTransactions|APIContractRouterCoverage|RouteCoverage)' -count=1` and the frontend `listMindmap/migrate.test.ts` and `listMindmap/model.test.ts` suites. These tests use the existing CI discovery paths.
-Run from `app/`:
+After contract changes, run generation and checks from `app/`. The commands below also show the full frontend suite; select regression coverage according to the affected behavior and risk rather than requiring the full suite for every task:
```text
pnpm run api:generate --petal ../../petal
@@ -207,11 +209,13 @@ pnpm run lint
pnpm test
```
-The generation command updates both this repository and `petal`; a separate generation run without `--petal` is unnecessary. The `--petal` path is relative to the generator's working directory, `kernel/`; the example refers to a sibling repository. CI checks only this repository's artifacts. Local synchronization across repositories uses this option to verify plugin declarations.
+The generation command updates both this repository and `petal`; a separate generation run without `--petal` is unnecessary. The `--petal` path is relative to the generator's working directory, `kernel/`; the example refers to a sibling repository. Verify the target checkout's path, identity, branch, baseline, and existing changes before running it, and substitute the verified path when different. If the checkout is unavailable, complete independent work where possible and report cross-repo synchronization as blocked; do not automatically create or download another repository or report synchronization as complete. CI checks only this repository's artifacts. Local synchronization across repositories uses this option to verify plugin declarations.
+
+`pnpm run lint` includes type and static checks plus ESLint automatic fixes; review its diff and keep changes within the task scope without overwriting existing work. It does not run behavioral tests. For read-only reviews, use applicable non-mutating checks instead of this command. Report passed, failed, and unrun checks separately.
The same generator also reads the field capability declarations in `kernel/av/capabilities.go` and writes `app/src/protyle/render/av/capabilities.generated.ts`, `app/src/types/av/index.d.ts`, and the corresponding `petal/types/av/index.d.ts`. Maintain field capabilities and the filter operator registry in the kernel, then regenerate these artifacts; do not hand-edit the generated field type or operator unions. Tests enumerate the typed Go constants to reject missing declarations and verify generated artifacts through the existing commands and full kernel suite.
-Run from `kernel/`:
+Run `go test ./apicontract/...` and applicable API compatibility and route coverage tests from `kernel/`. The full kernel suite is available when the impact warrants broader coverage:
```text
go test -tags "fts5 sqlcipher" ./... -count=1
@@ -221,4 +225,6 @@ go test -tags "fts5 sqlcipher" ./... -count=1
Import and static-file fixtures use `internal/testutil.PublicDataDir` to create and clean up explicitly validated non-sensitive directories independently of `TMPDIR` and `GOTMPDIR`. The helper tries the user home, current directory, and filesystem root, and reports a fixture setup failure if none is safe and writable. CI also reruns the affected path tests with `/tmp` as `TMPDIR` and a separate `GOTMPDIR` to cover environment overrides.
-The prerelease workflow `.github/workflows/cd.yml` runs language validation, contract and type checks, all kernel packages on Linux, and all frontend, Electron, and packaging-script tests on Windows. These checks run only for prerelease tag pushes (`*-alpha*`, `*-beta*`, `*-rc*`) or manual dispatch of this workflow; ordinary branch pushes and pull requests do not trigger them. Desktop and Android packaging require all three validation and test jobs to pass. Frontend discovery is restricted to `src/**/*.test.ts`, `tests/**/*.test.js`, `electron/**/*.test.js`, and `scripts/**/*.test.js`, so packaged copies under `app/build` are excluded. Test files run in separate processes with concurrency selected from the available CPU cores, capped at four to limit Electron process startup contention. Use `pnpm test --test-concurrency=1` for serial execution. New regression tests in these locations are included automatically; update the test command and this document when adding a new test location or filename convention. Keep `Contract` in Go contract regression test names so they remain easy to run separately.
+The prerelease workflow `.github/workflows/cd.yml` runs language validation, contract and type checks, all kernel packages on Linux, and frontend, Electron, and packaging-script tests on Windows. It runs on prerelease tag pushes (`*-alpha*`, `*-beta*`, `*-rc*`) or manual dispatch; ordinary branch pushes and pull requests do not trigger it. Some test steps, including the full Linux kernel and frontend suites, use `continue-on-error: true`. A successful job or published release therefore does not establish that all tests passed; inspect the actual step outcomes, logs, and test reports before reporting verification results. This description does not change the workflow's release gates.
+
+Frontend discovery is restricted to `src/**/*.test.ts`, `tests/**/*.test.js`, `electron/**/*.test.js`, and `scripts/**/*.test.js`, so packaged copies under `app/build` are excluded. Test files run in separate processes with concurrency selected from the available CPU cores, capped at four to limit Electron process startup contention. Use `pnpm test --test-concurrency=1` for serial execution. New regression tests in these locations are included automatically; update the test command and this document when adding a new test location or filename convention. Keep `Contract` in Go contract regression test names so they remain easy to run separately.
diff --git a/docs/API-CONTRACTS.zh-CN.md b/docs/API-CONTRACTS.zh-CN.md
index 00e843b794..b01879c1b4 100644
--- a/docs/API-CONTRACTS.zh-CN.md
+++ b/docs/API-CONTRACTS.zh-CN.md
@@ -12,7 +12,9 @@
2. 用 `contractHandler` 绑定业务入口,并用 `contractRouteHandlers` 注册处理函数,保持路由中间件顺序和租约范围
3. 删除接口时同步移除路由注册和契约定义
4. 更新实际响应、兼容输入和严格类型测试,运行生成器,再修正编译器指出的调用问题
-5. 同步 `petal` 的生成声明和相关公共声明;公开接口同步更新接口文档
+5. 同步 `petal` 的生成声明和相关公共声明。接口行为、默认值、约束和兼容性在契约源码注释及对应的 Petal 维护声明中说明。修改已有接口时,检查并同步更新 `docs/API.md`、`docs/API.zh-CN.md` 和 `docs/API.ja.md` 中受影响的条目,不假定各语言覆盖相同接口;仅在用户明确要求时,将新实现的接口加入这些参考文档
+
+本文及其翻译是维护指南,仅在契约机制、兼容性政策、生成流程、测试发现或验证规则变化时,或用户明确要求时更新。常规接口或功能变更不向此处追加端点专用行为、功能摘要、验证结果或定向测试命令。面向用户的操作说明放入内置用户指南,可执行的插件示例放入 `plugin-sample`,任务专用检查及结果写入任务回复或 PR 描述。Petal 的 README 仅保留项目标题和 `plugin-sample` 链接。文档范围遵循 [AGENTS.md](../AGENTS.md)。
生成检查读取实际路由与处理函数声明,验证方法、路径、处理函数、契约适配器和鉴权中间件的对应关系。`define` 要求显式传入访问策略:公开端点使用 `PublicAccess`,已鉴权端点可叠加 `AdminAccess` 和 `WritableAccess`。分域注册函数保留字面量方法与路径,`contractRouteHandlers` 从绑定端点派生中间件。生成检查拒绝缺少策略、端点绑定不匹配,以及显式中间件遗漏或顺序改变。鉴权元数据不替代资源权限或全局笔记本租约中间件。生成器和 CI 拒绝没有契约的路由并检查完整路由覆盖。不得通过 `any` 或类型断言规避契约检查。
@@ -182,7 +184,7 @@ JSON SSE 接口通过 `SSEOptions` 和 `SSEEvent` 声明各事件名称及载荷
`/api/block/migrateLegacyMindmaps` 是要求管理员身份的写入端点,保留只读保护及加密笔记本请求租约。请求必须提供文档 `id` 和 `notebook`;保存历史后,在一次可撤销事务中转换能够完整解析的旧 `mindmap` 列表,返回 `converted` 数量和文档脑图的权威 `blocks`(`id`、`dom`)。重复请求返回当前块内容,不重复转换;不完整的原文保持不变。回归命令为 `go test -tags "fts5 sqlcipher" ./model ./api ./apicontract/... -run 'Test(LegacyMindmap|MigrateLegacyMindmaps|APIContractHeadingTransactions|APIContractRouterCoverage|RouteCoverage)' -count=1`,前端覆盖位于 `listMindmap/migrate.test.ts` 和 `listMindmap/model.test.ts`,均由现有持续集成规则发现。
-在 `app/` 下运行:
+契约变更后,在 `app/` 下运行生成和检查。以下命令也列出了前端全量测试;根据受影响的行为和风险选择回归范围,不要求每个任务都运行全量测试:
```text
pnpm run api:generate --petal ../../petal
@@ -191,11 +193,13 @@ pnpm run lint
pnpm test
```
-上述生成命令同时更新本仓库与 `petal`,无须再单独执行不带 `--petal` 的生成命令。`--petal` 路径相对于生成器的工作目录 `kernel/`,示例对应同级仓库。CI 只检查本仓库产物,而本地跨仓库同步须使用该参数核对插件声明。
+上述生成命令同时更新本仓库与 `petal`,无须再单独执行不带 `--petal` 的生成命令。`--petal` 路径相对于生成器的工作目录 `kernel/`,示例对应同级仓库。运行前核对目标仓库的路径、身份、分支、基线及已有改动;实际位置不同时使用已验证的路径。目标仓库不可用时,尽可能完成独立工作并报告跨仓库同步受阻,不自动创建或下载其他仓库,也不宣称同步完成。CI 只检查本仓库产物,而本地跨仓库同步须使用该参数核对插件声明。
+
+`pnpm run lint` 包含类型和静态检查,也会由 ESLint 自动修复文件;运行后检查差异,将改动限制在任务范围内,不覆盖已有工作。它不运行行为测试。只读审阅应使用适用的非修改性检查,不运行此命令。分别报告通过、失败和未运行的检查。
同一生成器还读取 `kernel/av/capabilities.go` 中的字段能力声明,输出 `app/src/protyle/render/av/capabilities.generated.ts`、`app/src/types/av/index.d.ts` 和对应的 `petal/types/av/index.d.ts`。字段能力和筛选算子清单在内核维护,修改后重新生成产物,不手工编辑生成的字段类型或算子联合类型。测试枚举 Go 类型常量,拒绝遗漏声明,并通过现有生成检查命令和内核全量测试核对生成产物。
-在 `kernel/` 下运行:
+在 `kernel/` 下运行 `go test ./apicontract/...` 及适用的 API 兼容性和路由覆盖测试。影响范围需要更广验证时,可运行内核全量测试:
```text
go test -tags "fts5 sqlcipher" ./... -count=1
@@ -205,4 +209,6 @@ go test -tags "fts5 sqlcipher" ./... -count=1
导入和静态文件测试数据使用 `internal/testutil.PublicDataDir` 创建并清理经过显式验证的非敏感目录,不依赖 `TMPDIR` 和 `GOTMPDIR`。该辅助函数依次尝试用户主目录、当前目录和文件系统根目录;若没有安全且可写的位置,则报告测试数据准备失败。CI 还会将 `TMPDIR` 设为 `/tmp`,并使用独立的 `GOTMPDIR` 重新运行受影响的路径测试,以覆盖环境变量覆盖的情况。
-CI 在 Linux 上运行所有内核包的测试,在 Windows 上运行所有前端、Electron 和打包脚本测试。前端测试发现范围限定为 `src/**/*.test.ts`、`tests/**/*.test.js`、`electron/**/*.test.js` 和 `scripts/**/*.test.js`,因此排除 `app/build` 下的打包副本。测试文件在独立进程中运行,根据可用 CPU 核心数选择并发度,上限为 4,以限制 Electron 进程启动争用。通过 `pnpm test --test-concurrency=1` 可串行执行。这些位置新增的回归测试会自动纳入;新增测试位置或文件命名约定时,须同步更新测试命令和本文档。Go 契约回归测试的名称应保留 `Contract`,以便单独运行。
+预发布工作流 `.github/workflows/cd.yml` 执行语言校验、契约和类型检查,在 Linux 上运行所有内核包的测试,在 Windows 上运行前端、Electron 和打包脚本测试。它仅由预发布标签推送(`*-alpha*`、`*-beta*`、`*-rc*`)或手动调度触发,普通分支推送和 PR 不触发该工作流。部分测试步骤,包括 Linux 内核全量测试和前端测试,设置了 `continue-on-error: true`。因此,任务成功或版本发布不代表所有测试通过;报告验证结果前,应检查实际步骤结果、日志和测试报告。此处说明不改变工作流的发布门禁。
+
+前端测试发现范围限定为 `src/**/*.test.ts`、`tests/**/*.test.js`、`electron/**/*.test.js` 和 `scripts/**/*.test.js`,因此排除 `app/build` 下的打包副本。测试文件在独立进程中运行,根据可用 CPU 核心数选择并发度,上限为 4,以限制 Electron 进程启动争用。通过 `pnpm test --test-concurrency=1` 可串行执行。这些位置新增的回归测试会自动纳入;新增测试位置或文件命名约定时,须同步更新测试命令和本文档。Go 契约回归测试的名称应保留 `Contract`,以便单独运行。
diff --git a/docs/RELEASE-VERIFICATION.zh-CN.md b/docs/RELEASE-VERIFICATION.zh-CN.md
index 74f28ff2d3..59b8177431 100644
--- a/docs/RELEASE-VERIFICATION.zh-CN.md
+++ b/docs/RELEASE-VERIFICATION.zh-CN.md
@@ -191,7 +191,7 @@ python -X utf8 scripts/verify-release.py check --version 3.8.7
在 GitHub 创建发布 PR,来源分支选择 `dev`,目标分支选择 `master`,确认来源提交就是步骤 1 记录的构建提交。正式发布允许直接使用 `dev` 作为 PR 来源;普通开发 PR 仍使用独立任务分支并合入 `dev`。[分支检查工作流](../.github/workflows/target-branch.yml) 已通过 `exclude: dev` 支持该发布流程,其他来源分支向 `master` 提 PR 时会被自动改为合入 `dev`。
-检查通过后使用 **Create a merge commit** 合并发布 PR,保留 `dev` 的完整提交历史,避免长期分支反复 squash 导致后续 PR 重复列出旧提交。仓库设置须启用 **Allow merge commits**,不要为发布 PR 选择 squash 或 rebase。通过 PR 更新 `master`,无需直接向 `master` 推送。
+检查通过后使用 **Create a merge commit** 合并发布 PR,保留 `dev` 的完整提交历史,避免长期分支反复 squash 导致后续 PR 重复列出旧提交。仓库设置须启用 **Allow merge commits**;如果设置不允许,报告限制并停止合并,不要为发布 PR 改用 squash 或 rebase。通过 PR 更新 `master`,无需直接向 `master` 推送。
合并后获取最新 `master`,将下面的 `<构建提交的完整 SHA>` 替换为步骤 1 记录的完整 SHA,核对其文件树与构建提交一致;差异检查必须无输出且退出码为 `0`,存在差异时停止发布并核对原因:
@@ -239,7 +239,7 @@ GitHub 源地址:https://github.com/siyuan-note/siyuan/releases/download/v3.8.
### 10. 将发布历史同步回 dev
-正式发布后、继续开发前,在工作区干净的 `dev` 上获取最新远端提交,将已发布的 `master` 合并回 `dev` 并推送。使用普通合并保留两边历史,不重置或强推 `dev`。如果发布后两边没有新增代码改动,同步前后的文件树应完全相同;存在其他改动或冲突时先核对并处理。
+正式发布后、继续开发前,在工作区干净的 `dev` 上获取最新远端提交,将已发布的 `master` 合并回 `dev` 并推送。代理执行时,合并须有用户授权,推送须有明确授权;发布流程本身不授权未请求的合并、标签、上传或公开发布,也不授权直接提交或推送到 `master`。使用普通合并保留两边历史,不重置或强推 `dev`。如果发布后两边没有新增代码改动,同步前后的文件树应完全相同;存在其他改动或冲突时先核对并处理。
历史上使用 squash 的发布也需要这次同步,它能让 `dev` 包含发布提交并更新共同祖先,但不会消除原始提交在后续 PR 提交列表中的重复。后续发布统一使用普通合并,让这些原始提交进入 `master` 的历史。