docs: main-only workflow, CI-filled versions, dev version format [CI]

.woodpecker/dev-image.yml

@@ -7,12 +7,19 @@ clone:
     image: plugin-git
     settings:
       lfs: false
+      # 要拿到 tag 才算得出开发版本号（ci/version.sh：自最近 tag 的提交数）
+      tags: true
 
 when:
   - event: push
     branch: main
     evaluate: 'CI_COMMIT_MESSAGE contains "[CI]"'
 
+# 先等后端测试和前端构建都通过再出镜像（提交信息写 [SKIP TESTS] 只跳过后端测试）
+depends_on:
+  - verify
+  - web-build
+
 concurrency: 1
 
 steps:
@@ -28,7 +35,7 @@ steps:
       RELEASE_SIGNING_KEY:
         from_secret: release_signing_key
     commands:
-      - bash ci/build-main-amd64.sh backend
+      - bash ci/build-dev-image.sh backend
     depends_on: []
 
   - name: build-linux-amd64-agent
@@ -43,7 +50,7 @@ steps:
       RELEASE_SIGNING_KEY:
         from_secret: release_signing_key
     commands:
-      - bash ci/build-main-amd64.sh agent
+      - bash ci/build-dev-image.sh agent
     depends_on: []
 
   - name: build-linux-amd64-probe
@@ -58,5 +65,5 @@ steps:
       RELEASE_SIGNING_KEY:
         from_secret: release_signing_key
     commands:
-      - bash ci/build-main-amd64.sh probe
+      - bash ci/build-dev-image.sh probe
     depends_on: []

.woodpecker/linux-release.yml

@@ -22,6 +22,8 @@ steps:
     environment:
       NPM_CONFIG_CACHE: /home/justme/.npm
     commands:
+      # 版本取自 tag：先写进工作区（仓库里的版本号只是占位），前端才会带上对的版本
+      - bash ci/version.sh apply
       - npm ci --prefix web --prefer-offline
       - timeout 600 npm run build --prefix web
     depends_on: []

.woodpecker/verify.yml

@@ -11,7 +11,7 @@ clone:
 when:
   - event: pull_request
   - event: push
-    branch: dev
+    branch: main
 
 # On Gitea PR events, CI_COMMIT_MESSAGE is the PR title.
 steps:

.woodpecker/web-build.yml

@@ -11,7 +11,7 @@ clone:
 when:
   - event: pull_request
   - event: push
-    branch: dev
+    branch: main
 
 depends_on:
   - verify

AGENTS.md

@@ -6,8 +6,9 @@ MoShiro is a self-hosted network path quality monitor. Backend coordinates Agent
 
 ## Branch and workspace safety
 
-- Treat `main` as the stable release branch and `dev` as the integration branch. Keep ordinary implementation work on `dev` or a feature branch; integrate into `main` through a pull request.
-- A push to `main` builds images only if its commit message contains `[CI]` (for a merged PR, put it in the PR or merge commit title). Without `[CI]` nothing is built; use `[CI SKIP]` to skip the pipeline entirely. When squashing or pushing to `main`, add `[CI]` unless a build is explicitly not wanted.
+- `main` is the only working branch (the old `dev` branch is retired and no pipeline uses it). Commit and push to `main` directly; use a pull request when a review is wanted.
+- A push to `main` publishes development images only if its commit message contains `[CI]` (for a merged PR, put it in the PR or merge commit title). Without `[CI]` nothing is built; use `[CI SKIP]` to skip the pipeline entirely. Backend tests and the web build run on every `main` push and must pass first; `[SKIP TESTS]` skips only the Backend tests.
+- Versions are filled in by CI (`ci/version.sh`): a `vX.Y.Z` tag builds exactly `X.Y.Z`; a `[CI]` build on `main` is `vX.Y.(Z+1)-dev.<N>-<sha7>` (`N` = commits since the latest tag). The `<Version>` in `backend/Directory.Build.props` and the `version` in the `web` `package.json` files are placeholders (`0.0.0-dev`); never bump them by hand.
 - Before editing, inspect `git status`. Preserve pre-existing user changes: do not reset, clean, stash, or include unrelated files in a commit.
 - Do not commit credentials, API keys, registry passwords, or generated runtime data. CI credentials belong in Woodpecker secrets (`zot_secret`, `gitea_token`, `release_signing_key` for signing release manifests). CI registers the signed manifests at `/api/release/offer`, which needs no token because the panel verifies the signature. The release signing private key never goes into the repository or the panel; only the public key in `packaging/update/` does.
 - Keep development OCI images in the `moshiro-dev/` repository path and release images in `moshiro/`. Do not let a development build overwrite release tags such as `latest`.
@@ -40,4 +41,4 @@ Follow the user's requested validation scope. Do not start a full tag/release bu
 
 CI triggers and image tags can change; inspect `.woodpecker/*.yml` and `docs/ops/deployment.md` before changing or describing them. In particular, check the distinction between `[CI]` main builds, `[SKIP TESTS]`, and version-tag releases in the current branch.
 
-A version tag `vMAJOR.MINOR.PATCH` runs the full cross-platform release pipeline. Development image builds and releases must remain isolated in their respective Zot repository paths.
+A version tag `vMAJOR.MINOR.PATCH` runs the full cross-platform release pipeline; it needs no version-bump commit, because CI takes the version from the tag. Development image builds and releases must remain isolated in their respective Zot repository paths.

backend/Directory.Build.props

@@ -13,7 +13,7 @@
     <UseArtifactsOutput>true</UseArtifactsOutput>
     <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
     <Deterministic>true</Deterministic>
-    <Version>0.4.0</Version>
+    <Version>0.0.0-dev</Version>
     <NuGetAudit>false</NuGetAudit>
   </PropertyGroup>
   <ItemGroup>

backend/agent/src/MoShiro.Agent/AgentApp.cs

@@ -143,6 +143,7 @@ public sealed class AgentApp : IDisposable
 
     public async Task RunAsync(CancellationToken ct)
     {
+        _log.Info("moshiro agent starting", MoShiro.Protocol.BuildInfo.Fields);
         using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct);
         // 数据面和控制端口先开始监听，再连接 Backend：hello 里上报的是实际端口
         _udp.Bind();

backend/probe/src/MoShiro.Probe/ProbeApp.cs

@@ -103,6 +103,7 @@ public sealed class ProbeApp : IDisposable
 
     public async Task RunAsync(CancellationToken ct)
     {
+        _log.Info("moshiro probe starting", MoShiro.Protocol.BuildInfo.Fields);
         if (_env.Directory.Agents.Count == 0)
         {
             _log.Info("no agents known yet, waiting for the panel to send the list");

backend/shared/MoShiro.Protocol/BuildInfo.Summary.cs

@@ -0,0 +1,19 @@
+namespace MoShiro.Protocol;
+
+/// <summary>构建信息的人能读的形式（启动时打进日志）；常量部分由 MoShiro.Protocol.csproj 的 WriteBuildInfo 在构建时生成。</summary>
+public static partial class BuildInfo
+{
+    /// <summary>版本、tag、提交、构建时间的字段，没有的（本地构建不设环境变量）写 unknown。</summary>
+    public static (string Key, object? Value)[] Fields { get; } =
+    [
+        ("version", Or(Version)),
+        ("tag", Or(Tag)),
+        ("commit", Or(Commit)),
+        ("built_at", Or(BuiltAt)),
+    ];
+
+    /// <summary>一行摘要，例如：0.4.1-dev.2-a3338e1 (tag v0.4.1-dev.2-a3338e1, commit a3338e1b2c, built 2026-10-09T03:00:00Z)。</summary>
+    public static string Summary => $"{Or(Version)} (tag {Or(Tag)}, commit {Or(Commit)}, built {Or(BuiltAt)})";
+
+    private static string Or(string value) => string.IsNullOrWhiteSpace(value) ? "unknown" : value;
+}

backend/shared/MoShiro.Protocol/MoShiro.Protocol.csproj

@@ -18,7 +18,7 @@
     <ItemGroup>
       <BuildInfoLine Include="namespace MoShiro.Protocol%3B" />
       <BuildInfoLine Include="/// &lt;summary&gt;这个程序是什么时候、从哪个版本构建出来的（构建时生成）。&lt;/summary&gt;" />
-      <BuildInfoLine Include="public static class BuildInfo" />
+      <BuildInfoLine Include="public static partial class BuildInfo" />
       <BuildInfoLine Include="{" />
       <BuildInfoLine Include="    public const string Version = &quot;$(Version)&quot;%3B" />
       <BuildInfoLine Include="    public const string Tag = &quot;$(MOSHIRO_TAG)&quot;%3B" />

backend/src/MoShiro.Backend.Application/Updates/BackendUpdates.cs

@@ -55,9 +55,14 @@ public sealed class BackendUpdates : IHostedService
             return "release";
         }
 
-        return BuildInfo.Tag is { } tag && (tag.StartsWith("dev-", StringComparison.Ordinal) || tag.StartsWith("main-", StringComparison.Ordinal)) ? "dev" : "release";
+        return IsDevTag(BuildInfo.Tag) ? "dev" : "release";
     }
 
+    /// <summary>开发构建的 tag：新格式 v0.4.1-dev.12-abc1234（含 -dev.），以及旧的 dev-&lt;sha&gt;、main-&lt;sha&gt;。</summary>
+    public static bool IsDevTag(string? tag) =>
+        tag is not null
+        && (tag.Contains("-dev.", StringComparison.Ordinal) || tag.StartsWith("dev-", StringComparison.Ordinal) || tag.StartsWith("main-", StringComparison.Ordinal));
+
     public async ValueTask<BackendUpdateView> GetAsync(CancellationToken ct)
     {
         string channel = ChannelOf(_options);

backend/src/MoShiro.Backend/Program.cs

@@ -1,3 +1,10 @@
 using MoShiro.Backend;
 
-await BackendHost.Build(args).RunAsync();
+WebApplication app = BackendHost.Build(args);
+// 启动时打一行构建信息：版本、tag、提交、构建时间（和 Agent、Probe 启动时打的是同一组）
+if (app.Logger.IsEnabled(LogLevel.Information))
+{
+    app.Logger.LogInformation("moshiro backend starting: version {BuildInfo}", MoShiro.Protocol.BuildInfo.Summary);
+}
+
+await app.RunAsync();

backend/tests/MoShiro.Backend.Tests/BackendUpdateTests.cs

@@ -30,6 +30,18 @@ public sealed class BackendUpdateTests : IAsyncLifetime
         Assert.Equal(expected, BackendUpdates.ChannelOf(new BackendOptions { UpdateChannel = "auto", ImageNamespace = imageNamespace }));
     }
 
+    [Theory]
+    [InlineData("v0.4.1-dev.12-044ce0c", true)]
+    [InlineData("dev-725fe17a7de8", true)]
+    [InlineData("main-725fe17a7d", true)]
+    [InlineData("v0.4.0", false)]
+    [InlineData("v0.4.1-rc.1", false)]
+    [InlineData(null, false)]
+    public void IsDevTag_RecognisesDevelopmentBuilds(string? tag, bool expected)
+    {
+        Assert.Equal(expected, BackendUpdates.IsDevTag(tag));
+    }
+
     private async Task<HttpResponseMessage> PublishAsync(long seq, string channel = "dev")
     {
         string manifest = $$"""{"component":"backend","channel":"{{channel}}","image":"registry.example/moshiro-{{channel}}/moshiro-backend","digest":"{{Digest}}","tag":"{{channel}}-{{seq}}","version":"0.1.1","seq":{{seq}}}""";

ci/build-dev-image.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
-# Build and push one opt-in main Linux amd64 image to the dev repository in Zot.
+# Build and push one opt-in Linux amd64 development image (main push with [CI]) to the moshiro-dev repository in Zot.
 set -euo pipefail
 
 [[ "${CI_PIPELINE_EVENT:-}" == push && "${CI_COMMIT_BRANCH:-}" == main && "${CI_COMMIT_MESSAGE:-}" == *"[CI]"* ]] || {
-  echo "main amd64 builds require a main push with [CI] in the commit message" >&2
+  echo "development image builds require a main push with [CI] in the commit message" >&2
   exit 2
 }
 
-component="${1:?usage: build-main-amd64.sh <backend|agent|probe>}"
+component="${1:?usage: build-dev-image.sh <backend|agent|probe>}"
 case "$component" in
   backend|agent|probe) ;;
   *) echo "unsupported component: $component" >&2; exit 2 ;;
@@ -22,20 +22,22 @@ esac
 }
 
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# 版本：v<下一个补丁版本>-dev.<自最近 tag 的提交数>-<提交前 7 位>（见 ci/version.sh）；写进工作区的 Directory.Build.props，镜像标签、构建信息、签名清单都用它
+source "$root/ci/version.sh"
+moshiro_apply_version
 registry="${ZOT_REGISTRY:-registry.oeo.one}"
 repository="$registry/moshiro-dev/moshiro-$component"
-work="$root/.release/main-amd64-build"
-base_home="/home/justme/woodpecker/buildah-home/main-amd64-build-$component"
-short_sha="${CI_COMMIT_SHA:0:12}"
-dev_tag="dev-$short_sha"
+work="$root/.release/dev-image-build"
+base_home="/home/justme/woodpecker/buildah-home/dev-image-build-$component"
+# 镜像标签不带 v（和正式版一致）：latest 和 <版本>；构建信息和清单里的 tag 带 v
+image_version="$MOSHIRO_VERSION"
 mkdir -p "$work" "$base_home"
 
 if [[ "$component" == backend ]]; then
-  export MOSHIRO_TAG="$dev_tag"
   BUILDAH_HOME="$base_home" \
     ZOT_REGISTRY="$registry" \
     ZOT_IMAGE_REPOSITORY="$repository" \
-    IMAGE_TAGS="latest,$dev_tag" \
+    IMAGE_TAGS="latest,$image_version" \
     IMAGE_PUBLISH=true \
     bash "$root/ci/release-linux.sh" amd64 backend
   exit 0
@@ -45,12 +47,12 @@ export HOME="$base_home"
 export BUILDAH_HOME="$base_home"
 export REGISTRY_AUTH_FILE="$work/$component-auth.json"
 context="$work/$component"
-local_image="localhost/moshiro-$component:main-amd64-check"
+local_image="localhost/moshiro-$component:dev-amd64-check"
 
 python3 "$root/ci/stage-node-image.py" "$component" "$context"
 buildah bud --layers --network host --tls-verify=true --arch amd64 \
-  --build-arg APP_VERSION=main \
-  --build-arg "MOSHIRO_TAG=$dev_tag" --build-arg "MOSHIRO_COMMIT=${CI_COMMIT_SHA:0:10}" --build-arg "MOSHIRO_BUILT_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --build-arg "APP_VERSION=$image_version" \
+  --build-arg "MOSHIRO_TAG=$MOSHIRO_TAG" --build-arg "MOSHIRO_COMMIT=${CI_COMMIT_SHA:0:10}" --build-arg "MOSHIRO_BUILT_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   -f "$context/Containerfile" \
   -t "$local_image" "$context"
 
@@ -67,7 +69,7 @@ for attempt in 1 2 3 4; do
 done
 [[ "$logged_in" == true ]] || { echo "could not authenticate to Zot after 4 attempts" >&2; exit 1; }
 
-for tag in latest "$dev_tag"; do
+for tag in latest "$image_version"; do
   pushed=false
   for attempt in 1 2 3; do
     if buildah push --tls-verify=true --digestfile "$work/$component.digest" "$local_image" "docker://$repository:$tag"; then
@@ -86,5 +88,5 @@ done
 # 发布清单：给镜像的 digest 签名（私钥只在 CI 密钥里），放进镜像仓库（<仓库>-manifest:dev），面板在线时再登记一份加速。
 # 没有配置签名密钥（例如 fork）就只构建镜像、不发清单。
 if [[ -n "${RELEASE_SIGNING_KEY:-}" ]]; then
-  bash "$root/ci/publish-release-offer.sh" "$component" "$repository" "$(cat "$work/$component.digest")" "$dev_tag" dev "$work/$component-release"
+  bash "$root/ci/publish-release-offer.sh" "$component" "$repository" "$(cat "$work/$component.digest")" "$MOSHIRO_TAG" dev "$work/$component-release"
 fi

ci/package-cross-platform.ps1

@@ -10,10 +10,10 @@ if (-not $env:GITEA_TOKEN) {
 $version = $Matches[1]
 $root = Split-Path -Parent $PSScriptRoot
 $backend = Join-Path $root 'backend'
-$projectVersion = [regex]::Match((Get-Content (Join-Path $backend 'Directory.Build.props') -Raw), '<Version>([^<]+)</Version>').Groups[1].Value
-if ($version -ne $projectVersion) {
-    throw "Tag version $version does not match project version $projectVersion."
-}
+# 版本取自 tag：写进工作区的 Directory.Build.props（仓库里的 <Version> 只是占位，发版不用再提交 bump）
+$propsPath = Join-Path $backend 'Directory.Build.props'
+$props = Get-Content $propsPath -Raw
+Set-Content -LiteralPath $propsPath -Value ([regex]::Replace($props, '<Version>[^<]*</Version>', "<Version>$version</Version>")) -NoNewline
 
 $tarProject = Join-Path $PSScriptRoot 'MoShiro.Tar\MoShiro.Tar.csproj'
 $tarTool = Join-Path $PSScriptRoot 'MoShiro.Tar\bin\Release\net10.0\MoShiro.Tar.dll'

ci/release-cross-platform.ps1

@@ -20,10 +20,10 @@ if (-not $env:CI_COMMIT_TAG -or $env:CI_COMMIT_TAG -notmatch '^v(\d+\.\d+\.\d+(?
 $version = $Matches[1]
 $root = Split-Path -Parent $PSScriptRoot
 $backend = Join-Path $root 'backend'
-$projectVersion = [regex]::Match((Get-Content (Join-Path $backend 'Directory.Build.props') -Raw), '<Version>([^<]+)</Version>').Groups[1].Value
-if ($version -ne $projectVersion) {
-    throw "Tag version $version does not match project version $projectVersion."
-}
+# 版本取自 tag：写进工作区的 Directory.Build.props（仓库里的 <Version> 只是占位，发版不用再提交 bump）
+$propsPath = Join-Path $backend 'Directory.Build.props'
+$props = Get-Content $propsPath -Raw
+Set-Content -LiteralPath $propsPath -Value ([regex]::Replace($props, '<Version>[^<]*</Version>', "<Version>$version</Version>")) -NoNewline
 
 if ($RuntimeIdentifier -in @('win-x64', 'win-arm64')) {
     $vcArchitecture = if ($RuntimeIdentifier -eq 'win-x64') { 'x64' } else { 'arm64' }
@@ -52,7 +52,7 @@ $buildRoot = Join-Path $root ".release\build\$RuntimeIdentifier-$Component"
 $null = New-Item -ItemType Directory -Force -Path $output
 
 # 构建信息：程序里显示的 tag、提交、构建时间
-$env:MOSHIRO_TAG = if ($env:CI_COMMIT_TAG) { $env:CI_COMMIT_TAG } else { "main-$($env:CI_COMMIT_SHA.Substring(0, 10))" }
+$env:MOSHIRO_TAG = $env:CI_COMMIT_TAG
 $env:MOSHIRO_COMMIT = $env:CI_COMMIT_SHA.Substring(0, 10)
 $env:MOSHIRO_BUILT_AT = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
 

ci/release-linux.sh

@@ -6,19 +6,16 @@ set -euo pipefail
 arch="${1:?usage: release-linux.sh <amd64|arm64>}"
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 tag="${CI_COMMIT_TAG:-}"
-if [[ -n "$tag" ]]; then
-  [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || {
-    echo "release must run from a vMAJOR.MINOR.PATCH tag" >&2
-    exit 2
-  }
-  version="${tag#v}"
-else
+if [[ -z "$tag" ]]; then
   [[ "${CI_PIPELINE_EVENT:-}" == push && "${CI_COMMIT_BRANCH:-}" == main && "${CI_COMMIT_MESSAGE:-}" == *"[CI]"* ]] || {
     echo "untagged backend builds require a main push with [CI] in the commit message" >&2
     exit 2
   }
-  version=main
 fi
+# 版本：tag 发版就是 tag 的版本，开发构建是 v<下一个补丁版本>-dev.<N>-<提交>（ci/version.sh）；写进工作区的 Directory.Build.props
+source "$root/ci/version.sh"
+moshiro_apply_version
+version="$MOSHIRO_VERSION"
 image_publish="${IMAGE_PUBLISH:-true}"
 [[ "$image_publish" == true || "$image_publish" == false ]] || {
   echo "IMAGE_PUBLISH must be true or false" >&2; exit 2;
@@ -34,12 +31,6 @@ case "$arch" in
   *) echo "unsupported architecture: $arch" >&2; exit 2 ;;
 esac
 
-project_version="$(sed -n 's#.*<Version>\(.*\)</Version>.*#\1#p' "$root/backend/Directory.Build.props" | head -1)"
-if [[ -n "$tag" && "$version" != "$project_version" ]]; then
-  echo "tag version $version does not match project version $project_version" >&2
-  exit 1
-fi
-
 registry="${ZOT_REGISTRY:-registry.oeo.one}"
 image="${ZOT_IMAGE_REPOSITORY:-$registry/moshiro/moshiro-backend}"
 output="$root/.release/linux-$arch/backend"
@@ -47,8 +38,7 @@ build_root="$root/.release/build/linux-$arch-backend"
 container_context="$root/.release/container/linux-$arch"
 mkdir -p "$output" "$build_root" "$container_context/app" "$container_context/data"
 
-# 构建信息：tag 发布用 tag，main 构建用 main-<提交>
-export MOSHIRO_TAG="${MOSHIRO_TAG:-${tag:-main-${CI_COMMIT_SHA:0:10}}}"
+# 构建信息：tag 发布用 tag，开发构建用 v<版本>-dev.<N>-<提交>（MOSHIRO_TAG 已由 ci/version.sh 设好）
 export MOSHIRO_COMMIT="${MOSHIRO_COMMIT:-${CI_COMMIT_SHA:0:10}}"
 export MOSHIRO_BUILT_AT="${MOSHIRO_BUILT_AT:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
 

ci/release-manifest.sh

@@ -14,7 +14,8 @@ repository="${2:?}"; digest="${3:?}"; tag="${4:?}"; channel="${5:?}"; outdir="${
 [[ -n "${RELEASE_SIGNING_KEY:-}" ]] || { echo "RELEASE_SIGNING_KEY is required" >&2; exit 2; }
 
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-version="$(sed -n 's#.*<Version>\(.*\)</Version>.*#\1#p' "$root/backend/Directory.Build.props" | head -1)"
+source "$root/ci/version.sh"
+version="$MOSHIRO_VERSION"
 commit="$(git -C "$root" rev-parse --short=10 HEAD 2>/dev/null || true)"
 built_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 seq="$(date +%s)"

ci/release-node-images.sh

@@ -15,11 +15,9 @@ tag="${CI_COMMIT_TAG:-}"
 
 version="${tag#v}"
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-project_version="$(sed -n 's#.*<Version>\(.*\)</Version>.*#\1#p' "$root/backend/Directory.Build.props" | head -1)"
-if [[ "$version" != "$project_version" ]]; then
-  echo "tag version $version does not match project version $project_version" >&2
-  exit 1
-fi
+# 版本取自 tag：写进工作区的 Directory.Build.props（仓库里的 <Version> 只是占位，发版不用再提交 bump）
+source "$root/ci/version.sh"
+moshiro_apply_version
 
 gitea_base="${GITEA_BASE:-http://127.0.0.1:3100}"
 gitea_base="${gitea_base%/}"

ci/version.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# 算出这次构建的版本号。用法：
+#   source ci/version.sh          # 得到 MOSHIRO_VERSION（不带 v）和 MOSHIRO_TAG（带 v）
+#   bash ci/version.sh apply      # 同上，并把 MOSHIRO_VERSION 写进工作区里的 backend/Directory.Build.props 和三个 web/*/package.json（只改工作区，不提交）
+#
+# 规则：
+#   - 打 tag 发版（CI_COMMIT_TAG 是 vMAJOR.MINOR.PATCH）：版本就是 tag 的版本。仓库里的 <Version> 只是占位，发版不用再提交一次 bump；
+#   - 其余（main 上带 [CI] 的开发构建）：vMAJOR.MINOR.(PATCH+1)-dev.<N>-<提交前 7 位>，
+#     基准是最近一个 v* tag，N 是这个 tag 之后的提交数。开发版本按语义化版本排在下一个正式版之前，同一个提交算出来永远一样。
+#   最近的 tag 要拿得到：CI 的克隆要带 tags（见 .woodpecker/dev-image.yml 的 clone 设置）；没有任何 tag 时基准是 0.0.0。
+_moshiro_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+_moshiro_compute_version() {
+  local tag="${CI_COMMIT_TAG:-}"
+  if [[ -n "$tag" ]]; then
+    [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || {
+      echo "release must run from a vMAJOR.MINOR.PATCH tag" >&2
+      return 2
+    }
+    MOSHIRO_VERSION="${tag#v}"
+  else
+    local sha="${CI_COMMIT_SHA:-$(git -C "$_moshiro_root" rev-parse HEAD)}"
+    local last base count major minor patch
+    last="$(git -C "$_moshiro_root" describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' "$sha" 2>/dev/null || true)"
+    if [[ -n "$last" ]]; then
+      base="${last#v}"
+      base="${base%%-*}"
+      count="$(git -C "$_moshiro_root" rev-list --count "$last..$sha")"
+    else
+      base="0.0.0"
+      count="$(git -C "$_moshiro_root" rev-list --count "$sha")"
+    fi
+    IFS=. read -r major minor patch <<< "$base"
+    MOSHIRO_VERSION="$major.$minor.$((patch + 1))-dev.$count-${sha:0:7}"
+  fi
+  MOSHIRO_TAG="v$MOSHIRO_VERSION"
+  export MOSHIRO_VERSION MOSHIRO_TAG
+}
+
+# 把算出来的版本写进工作区的 backend/Directory.Build.props（所有 .NET 项目、清单、镜像标签都从那里读版本）和三个 package.json
+moshiro_apply_version() {
+  [[ -n "${MOSHIRO_VERSION:-}" ]] || _moshiro_compute_version
+  sed -i "s#<Version>[^<]*</Version>#<Version>$MOSHIRO_VERSION</Version>#" "$_moshiro_root/backend/Directory.Build.props"
+  # 前端在构建时从 web/package.json 读版本（web/build-info.mjs），其余两个工作区包的版本也一起对上
+  local manifest
+  for manifest in web/package.json web/display/package.json web/admin/package.json; do
+    sed -i -E '0,/"version": "[^"]*"/s//"version": "'"$MOSHIRO_VERSION"'"/' "$_moshiro_root/$manifest"
+  done
+}
+
+_moshiro_compute_version
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  if [[ "${1:-}" == apply ]]; then moshiro_apply_version; fi
+  echo "$MOSHIRO_VERSION"
+fi

docs/ops/deployment.md

@@ -23,7 +23,7 @@ scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid>      → backend/art
 scripts/package.sh <agent|probe> <rid>                           → backend/artifacts/packages/moshiro-<role>-<version>-<rid>.tar.gz（附 .sha256）
 ```
 
-构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MOSHIRO_TAG`、`MOSHIRO_COMMIT`、`MOSHIRO_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器镜像的 `*.NativeBuild.Containerfile` 用同名的 `--build-arg`，CI 脚本会传）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`）。
+构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MOSHIRO_TAG`、`MOSHIRO_COMMIT`、`MOSHIRO_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器镜像的 `*.NativeBuild.Containerfile` 用同名的 `--build-arg`，CI 脚本会传）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`；仓库里它只是占位（`0.0.0-dev`），CI 构建时由 `ci/version.sh` 写进工作区（见下文「版本号」）。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`，同样由 CI 填写）。Agent、Probe、Backend 启动时都会在日志里打印一行构建信息：版本、tag、提交、构建时间（没设置环境变量的本地构建显示 `unknown`）。
 
 | rid | 目标 | 构建方式 |
 | --- | --- | --- |
@@ -74,25 +74,36 @@ Woodpecker 在 `vMAJOR.MINOR.PATCH` tag 上，由 Windows runner 使用 AotAnywh
 
 ## CI 工作流
 
-### Pull request 与 dev 验证
+### Pull request 与 main 验证
 
-Pull request 和 `dev` push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。
+Pull request 和 `main` 的 push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。项目只用 `main` 一个工作分支，旧的 `dev` 分支不再被任何流水线使用。
+
+### 版本号
+
+版本都由 CI 填写，仓库里写死的只是占位（`backend/Directory.Build.props` 的 `<Version>` 和三个 `web/**/package.json` 的 `version` 都是 `0.0.0-dev`），发版不需要提交 bump。规则在 `ci/version.sh`：
+
+| 构建 | 版本 | 构建信息里的 tag |
+| --- | --- | --- |
+| 推 `vX.Y.Z` tag（正式版） | `X.Y.Z` | `vX.Y.Z` |
+| `main` 上带 `[CI]` 的 push（开发镜像） | `X.Y.(Z+1)-dev.<N>-<提交前 7 位>` | `v` + 同一个版本 |
+
+开发版本的基准是最近一个 `v*` tag（`X.Y.Z`），`N` 是这个 tag 之后的提交数（`git rev-list --count`），所以同一个提交算出来永远一样，也按语义化版本排在下一个正式版之前，例如 `0.4.1-dev.12-044ce0c`。算版本要拿得到 tag，所以开发镜像的 workflow 克隆时带 `tags: true`。镜像标签不带 `v`（和正式版一致），构建信息和签名清单里的 `tag` 带 `v`。
 
 ### main 开发镜像
 
-`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `moshiro-dev/` 仓库：
+`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像，并且要等上面的 Backend tests 和 `web-build` 都通过（提交信息写 `[SKIP TESTS]` 可以跳过测试）。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `moshiro-dev/` 仓库：
 
-| 镜像 | 滚动标签 | 固定提交标签 |
+| 镜像 | 滚动标签 | 固定版本标签 |
 | --- | --- | --- |
-| Backend | `registry.oeo.one/moshiro-dev/moshiro-backend:latest` | `registry.oeo.one/moshiro-dev/moshiro-backend:dev-<12位SHA>` |
-| Agent | `registry.oeo.one/moshiro-dev/moshiro-agent:latest` | `registry.oeo.one/moshiro-dev/moshiro-agent:dev-<12位SHA>` |
-| Probe | `registry.oeo.one/moshiro-dev/moshiro-probe:latest` | `registry.oeo.one/moshiro-dev/moshiro-probe:dev-<12位SHA>` |
+| Backend | `registry.oeo.one/moshiro-dev/moshiro-backend:latest` | `registry.oeo.one/moshiro-dev/moshiro-backend:<版本>`（如 `0.4.1-dev.12-044ce0c`） |
+| Agent | `registry.oeo.one/moshiro-dev/moshiro-agent:latest` | `registry.oeo.one/moshiro-dev/moshiro-agent:<版本>` |
+| Probe | `registry.oeo.one/moshiro-dev/moshiro-probe:latest` | `registry.oeo.one/moshiro-dev/moshiro-probe:<版本>` |
 
-Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。
+Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。节点和 Backend 判断自己是不是开发构建，看构建信息里的 tag 含 `-dev.`（旧的 `dev-<sha>`、`main-<sha>` 也认）。
 
 ### 正式版发布
 
-推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/moshiro/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `moshiro-dev/` 的 dev `latest` 相互独立。
+在 `main` 上推送 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release，版本取自 tag，不需要先提交版本号。正式镜像使用 `registry.oeo.one/moshiro/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `moshiro-dev/` 的 dev `latest` 相互独立。
 
 Agent 和 Probe 镜像分别发布为 `registry.oeo.one/moshiro/moshiro-agent:<version>` 与 `registry.oeo.one/moshiro/moshiro-probe:<version>`，包含 amd64、arm64 多架构索引；也可指定 `:<version>-amd64` 或 `:<version>-arm64`。稳定版本同时更新 `latest`。镜像以非 root 用户（UID/GID 1654）运行，默认读取 `/etc/moshiro/agent.json` 或 `/etc/moshiro/probe.json`。使用 `packaging/compose/agent`、`probe` 下的标准 Compose 模板，配置和身份放在命名 volume 中；首次注册/导入、宿主指标挂载与更新器见下文。
 
@@ -261,7 +272,7 @@ chmod 600 .env && curl -fsSL 'https://panel.example.com/install/compose/probe.ya
 - 只读根文件系统、丢掉全部能力、`no-new-privileges`、命名卷；Linux 上用宿主网络（Agent 对外暴露端口，也靠它识别本机公网地址，并只读挂载 `/proc`、`/sys`、`/` 读主机指标）。**Agent 的 compose 只适用于 Linux**；Probe 在 macOS 和 Windows（Docker Desktop）上没有宿主网络，面板给的命令会在 `.env` 里写 `MOSHIRO_NETWORK_MODE=bridge`。
 - 身份和配置在命名卷 `moshiro-<role>-config` 里：镜像入口脚本（`packaging/container/entrypoint.sh`）第一次启动用 `MOSHIRO_SERVER`、`MOSHIRO_JOIN`（和信任根指纹、属主）注册并写配置，之后重启、换新镜像重建容器都不需要再给参数，所以注册成功之后可以把 `.env` 里的 `MOSHIRO_JOIN` 删掉。缺了信任根指纹或属主就不注册（只有还没有信任根的老面板才用 `MOSHIRO_ALLOW_NO_OWNER=1`）。
 - Podman 的开机自启要靠 `podman-restart.service`（`systemctl enable --now podman-restart`；rootless 用 `--user`，并 `loginctl enable-linger`）；Docker 用 compose 里的 `restart: unless-stopped`。
-- **更新**：`podman compose pull && podman compose up -d`（Docker 用 `docker compose`），只重建镜像变了的容器，身份和配置不动，节点几十秒内重连。想固定版本，在 `.env` 里写 `MOSHIRO_VERSION=0.3.3`；想要更严，写成 `MOSHIRO_VERSION=0.3.3@sha256:<digest>`，digest 取自面板信任页或签名清单（那里有发布签名）。回滚就是改回旧版本再 `up -d`。
+- **更新**：`podman compose pull && podman compose up -d`（Docker 用 `docker compose`），只重建镜像变了的容器，身份和配置不动，节点几十秒内重连。想固定版本，在 `.env` 里写 `MOSHIRO_VERSION=<版本号>`；想要更严，写成 `MOSHIRO_VERSION=<版本号>@sha256:<digest>`，digest 取自面板信任页或签名清单（那里有发布签名）。回滚就是改回旧版本再 `up -d`。
 - **信任**：compose 来自面板或 CI 渠道，面板被攻破也改不了镜像地址；但客户端不再验发布签名，拉取靠 TLS 加「注册表可信」这个假设（文档里本来就把 CI、Gitea、注册表放在可信范围内）。compose 不会自动更新（见下节），也没有管理端的「更新」列和确认更新按钮。
 
 **一行安装脚本（备用，Docker 或 Podman，Agent 和 Probe 共用）**：管理端的弹窗里折叠着一条旧的一行命令，先核对脚本哈希再执行，脚本向面板取签名清单、用内置发布公钥验签、按 digest 拉镜像：

packaging/compose/agent/compose.yaml

@@ -5,7 +5,7 @@
 #   把面板给的 .env 内容存成 .env，再下载本文件为 compose.yaml
 #   podman compose up -d            # Docker 用 docker compose
 # 更新：podman compose pull && podman compose up -d      （身份和配置在命名卷里，不会动）
-# 固定版本：在 .env 里写 MOSHIRO_VERSION=0.3.3；想要更严，写成 MOSHIRO_VERSION=0.3.3@sha256:<digest>。
+# 固定版本：在 .env 里写 MOSHIRO_VERSION=<版本号>；想要更严，写成 MOSHIRO_VERSION=<版本号>@sha256:<digest>。
 # .env 里的 MOSHIRO_SERVER、MOSHIRO_JOIN（只在第一次启动用来注册，之后可以删掉）、MOSHIRO_GENESIS、MOSHIRO_CONTROLLERS、MOSHIRO_NAME 原样传进容器。
 # 说明见 docs/ops/deployment.md。
 services:

packaging/compose/probe/compose.yaml

@@ -5,7 +5,7 @@
 #   把面板给的 .env 内容存成 .env，再下载本文件为 compose.yaml
 #   podman compose up -d            # Docker 用 docker compose
 # 更新：podman compose pull && podman compose up -d      （身份和配置在命名卷里，不会动）
-# 固定版本：在 .env 里写 MOSHIRO_VERSION=0.3.3；想要更严，写成 MOSHIRO_VERSION=0.3.3@sha256:<digest>。
+# 固定版本：在 .env 里写 MOSHIRO_VERSION=<版本号>；想要更严，写成 MOSHIRO_VERSION=<版本号>@sha256:<digest>。
 # macOS、Windows 的 Docker Desktop 没有宿主网络：面板给的 .env 里已经写了 MOSHIRO_NETWORK_MODE=bridge。
 # .env 里的 MOSHIRO_SERVER、MOSHIRO_JOIN（只在第一次启动用来注册，之后可以删掉）、MOSHIRO_GENESIS、MOSHIRO_CONTROLLERS、MOSHIRO_NAME 原样传进容器。
 # 说明见 docs/ops/deployment.md。

packaging/quadlet/moshiro-agent.container

@@ -10,7 +10,7 @@
 #   loginctl enable-linger $USER                                              # 退出登录后继续运行（需要管理员执行一次）
 # rootful：本文件放进 /etc/containers/systemd/，.env 内容存成 /etc/moshiro/agent.env，把下面的 EnvironmentFile 改成这个路径、
 #   WantedBy 改成 multi-user.target，用 systemctl（不加 --user）。
-# 开发通道：把 Image 的 moshiro 换成 moshiro-dev。固定版本：把 :latest 换成 :0.3.3（固定之后更新不会换版本）。
+# 开发通道：把 Image 的 moshiro 换成 moshiro-dev。固定版本：把 :latest 换成 :<版本号>（固定之后更新不会换版本）。
 # 想要完全自动、不用在管理端点：另外启用 podman-auto-update.timer，并在 [Container] 里加 AutoUpdate=registry（Pull=always 也保留）。
 # 说明见 docs/ops/deployment.md。
 [Unit]

packaging/quadlet/moshiro-probe.container

@@ -10,7 +10,7 @@
 #   loginctl enable-linger $USER                                              # 退出登录后继续运行（需要管理员执行一次）
 # rootful：本文件放进 /etc/containers/systemd/，.env 内容存成 /etc/moshiro/probe.env，把下面的 EnvironmentFile 改成这个路径、
 #   WantedBy 改成 multi-user.target，用 systemctl（不加 --user）。
-# 开发通道：把 Image 的 moshiro 换成 moshiro-dev。固定版本：把 :latest 换成 :0.3.3（固定之后更新不会换版本）。
+# 开发通道：把 Image 的 moshiro 换成 moshiro-dev。固定版本：把 :latest 换成 :<版本号>（固定之后更新不会换版本）。
 # 想要完全自动、不用在管理端点：另外启用 podman-auto-update.timer，并在 [Container] 里加 AutoUpdate=registry（Pull=always 也保留）。
 # 说明见 docs/ops/deployment.md。
 [Unit]

web/admin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moshiro-admin",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.0.0-dev",
   "type": "module",
   "scripts": {
     "dev": "vite",

web/display/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moshiro-display",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.0.0-dev",
   "type": "module",
   "scripts": {
     "dev": "vite",

web/display/src/AppearancePanel.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import { APPEARANCE_DEFAULTS, APPEARANCE_RANGES, resetAppearance, setAppearance, useAppearance, type AppearanceSettings } from './appearance'
+import { PHOTO_GROUPS, PHOTOS } from './backgrounds'
 
 type Tab = 'weather' | 'background'
 
@@ -8,6 +9,8 @@ type SliderName = keyof typeof APPEARANCE_RANGES
 interface Slider {
   name: SliderName
   label: string
+  /** 悬停提示。 */
+  hint?: string
   /** 数值怎么显示：默认是百分比。 */
   format?: (value: number) => string
 }
@@ -29,17 +32,26 @@ const WEATHER_SWITCHES: { name: 'mouse' | 'bullet'; label: string; hint: string
 ]
 
 const BACKGROUND_SLIDERS: Slider[] = [
-  { name: 'bgBlur', label: '模糊', format: (value) => `${value}px` },
+  { name: 'bgBlur', label: '再模糊', format: (value) => `${value}px` },
   { name: 'parallax', label: '晃动' },
+  { name: 'bgVeil', label: '遮罩', hint: '盖在背景图上的那层灰色（暗色）/ 白色（亮色），0% 就是不盖' },
 ]
 
 const WEATHER_KEYS: (keyof AppearanceSettings)[] = ['enabled', 'density', 'speed', 'wind', 'size', 'blur', 'opacity', 'bullet', 'mouse']
-const BACKGROUND_KEYS: (keyof AppearanceSettings)[] = ['bgBlur', 'parallax']
+type Quality = 'blur' | 'sharp' | 'original'
+
+const QUALITY_OPTIONS: { value: Quality; label: string; hint: string }[] = [
+  { value: 'blur', label: '模糊', hint: '预先模糊过的图，最小（约 200–400KB）' },
+  { value: 'sharp', label: '清晰', hint: '不模糊，压缩过的图（约 200–400KB）' },
+  { value: 'original', label: '原图', hint: '不模糊，没压缩的原图（每张约 0.3–2MB，PNG 的更大）' },
+]
+
+const BACKGROUND_KEYS: (keyof AppearanceSettings)[] = ['photo', 'bgBlurred', 'bgBlur', 'bgOriginal', 'sway', 'parallax', 'bgVeil']
 
 function SliderRow({ slider, settings, disabled }: { slider: Slider; settings: AppearanceSettings; disabled?: boolean }) {
-  const { name, label, format = percent } = slider
+  const { name, label, hint, format = percent } = slider
   return (
-    <label className="appearance-row">
+    <label className="appearance-row" title={hint}>
       <span>{label}</span>
       <input type="range" {...APPEARANCE_RANGES[name]} value={settings[name]} disabled={disabled} onChange={(event) => setAppearance({ [name]: Number(event.target.value) })} />
       <output>{format(settings[name])}</output>
@@ -85,6 +97,9 @@ export function AppearancePanel() {
     }
   }, [open])
 
+  // 画质：模糊 / 清晰（不模糊，压缩）/ 原图（不模糊，没压缩）
+  const quality: Quality = settings.bgBlurred ? 'blur' : settings.bgOriginal ? 'original' : 'sharp'
+  const setQuality = (value: Quality) => setAppearance({ bgBlurred: value === 'blur', bgOriginal: value === 'original' })
   const keys = tab === 'weather' ? WEATHER_KEYS : BACKGROUND_KEYS
   const changed = keys.some((name) => settings[name] !== APPEARANCE_DEFAULTS[name])
 
@@ -111,9 +126,33 @@ export function AppearancePanel() {
           </div>
         ) : (
           <div className="appearance-body" key="background">
-            {BACKGROUND_SLIDERS.map((slider) => (
-              <SliderRow key={slider.name} slider={slider} settings={settings} />
+            {PHOTO_GROUPS.map((group) => (
+              <div key={group} role="group" aria-label={group}>
+                <div className="appearance-group-title">{group}</div>
+                <div className="appearance-choices">
+                  {PHOTOS.filter((photo) => photo.group === group).map(({ id, label, light }) => (
+                    <button key={id} type="button" className="appearance-choice" aria-pressed={settings.photo === id} onClick={() => setAppearance({ photo: id })}>
+                      <img src={light.blur} alt="" loading="lazy" />
+                      {label}
+                    </button>
+                  ))}
+                </div>
+              </div>
             ))}
+            <div className="appearance-row appearance-row-segment" role="group" aria-label="背景画质">
+              <span>画质</span>
+              <div className="appearance-segment">
+                {QUALITY_OPTIONS.map(({ value, label, hint }) => (
+                  <button key={value} type="button" title={hint} aria-pressed={quality === value} onClick={() => setQuality(value)}>
+                    {label}
+                  </button>
+                ))}
+              </div>
+            </div>
+            <SliderRow slider={BACKGROUND_SLIDERS[0]} settings={settings} disabled={quality !== 'blur'} />
+            <SwitchRow label="背景晃动" hint="关掉就不跟着鼠标晃" checked={settings.sway} onChange={(sway) => setAppearance({ sway })} />
+            <SliderRow slider={BACKGROUND_SLIDERS[1]} settings={settings} disabled={!settings.sway} />
+            <SliderRow slider={BACKGROUND_SLIDERS[2]} settings={settings} />
           </div>
         )}
         <button type="button" className="appearance-reset" disabled={!changed} tabIndex={open ? 0 : -1} onClick={() => resetAppearance(keys)}>

web/display/src/appearance.ts

@@ -1,4 +1,5 @@
 import { useEffect, useSyncExternalStore } from 'react'
+import { backgroundUrl, DEFAULT_PHOTO, PHOTOS } from './backgrounds'
 
 /**
  * 展示页右下角「外观」里能调的参数：都是相对默认值的倍数（1 = 原样），存在浏览器里。
@@ -23,10 +24,20 @@ export interface AppearanceSettings {
   bullet: boolean
   /** 鼠标拨动雪。 */
   mouse: boolean
-  /** 背景在预先模糊的基础上再模糊多少（像素，0 是不再模糊）。 */
+  /** 用哪张照片（id，见 backgrounds.ts）。 */
+  photo: string
+  /** 背景模糊：开是随主题的两张预先模糊过的图，关是不模糊的图（两张，也是随主题）。 */
+  bgBlurred: boolean
+  /** 背景模糊关着的时候：开是加载没压缩的原图（PNG，近 2MB 一张），关是压缩过的（JPG，不到 300KB）。 */
+  bgOriginal: boolean
+  /** 背景模糊开着的时候，在预先模糊的基础上再模糊多少（像素，0 是不再模糊）。 */
   bgBlur: number
-  /** 背景跟着鼠标晃动的幅度（0 是不动，1 是默认）。 */
+  /** 背景跟着鼠标晃动：总开关，关了背景就完全不动。 */
+  sway: boolean
+  /** 背景跟着鼠标晃动的幅度（1 是默认）。 */
   parallax: number
+  /** 盖在背景图上的那层遮罩（亮色是白、暗色是灰）的浓度：0 是不盖，1 是默认（亮色 50%、暗色 62%）。 */
+  bgVeil: number
 }
 
 export const APPEARANCE_DEFAULTS: AppearanceSettings = {
@@ -39,8 +50,13 @@ export const APPEARANCE_DEFAULTS: AppearanceSettings = {
   opacity: 1,
   bullet: true,
   mouse: true,
+  photo: DEFAULT_PHOTO,
+  bgBlurred: true,
+  bgOriginal: false,
   bgBlur: 0,
+  sway: true,
   parallax: 1,
+  bgVeil: 1,
 }
 
 /** 每个滑块的范围（和 AppearanceSettings 里同名的数值项对应）。 */
@@ -53,6 +69,7 @@ export const APPEARANCE_RANGES = {
   opacity: { min: 0.2, max: 2.5, step: 0.05 },
   bgBlur: { min: 0, max: 30, step: 1 },
   parallax: { min: 0, max: 1.5, step: 0.05 },
+  bgVeil: { min: 0, max: 1.6, step: 0.05 },
 } as const
 
 const KEY = 'moshiro.appearance'
@@ -64,7 +81,10 @@ function load(): AppearanceSettings {
     const merged: Record<string, unknown> = { ...APPEARANCE_DEFAULTS }
     for (const name of Object.keys(APPEARANCE_DEFAULTS) as (keyof AppearanceSettings)[]) {
       const value = saved[name]
-      if (typeof value === typeof APPEARANCE_DEFAULTS[name]) merged[name] = value
+      if (typeof value !== typeof APPEARANCE_DEFAULTS[name]) continue
+      // 照片只认列表里有的，图删了、改名了就回到默认
+      if (name === 'photo' && !PHOTOS.some((photo) => photo.id === value)) continue
+      merged[name] = value
     }
     return merged as unknown as AppearanceSettings
   } catch {
@@ -96,14 +116,28 @@ export function subscribeAppearance(listener: () => void): () => void {
 
 export const useAppearance = () => useSyncExternalStore(subscribeAppearance, getAppearance)
 
-/** 把背景的额外模糊写进 <html> 的 --bg-filter（display.css 里 .bg-layer 用它；不模糊的时候是 none，不给浏览器多一层滤镜）。 */
+/**
+ * 把当前该用的背景图写进 <html> 的 --bg-image（照片、主题、背景模糊、不压缩一起决定用哪个版本；display.css 里 .bg-layer 用它），
+ * 把遮罩的浓度写进 --bg-veil-scale，把背景的额外模糊写进 --bg-filter（不模糊的时候是 none，不给浏览器多一层滤镜），
+ * 把晃动的开关写进 data-sway（关了就按窗口的原始比例铺满，display.css 里 data-sway='off'）。切换主题时也重新算。
+ */
 export function useAppearanceVars() {
   useEffect(() => {
+    const root = document.documentElement
     const apply = () => {
-      const blur = getAppearance().bgBlur
-      document.documentElement.style.setProperty('--bg-filter', blur > 0 ? `blur(${blur}px)` : 'none')
+      const { bgBlur, bgBlurred, bgOriginal, photo, bgVeil, sway } = getAppearance()
+      root.style.setProperty('--bg-veil-scale', String(bgVeil))
+      root.style.setProperty('--bg-filter', bgBlurred && bgBlur > 0 ? `blur(${bgBlur}px)` : 'none')
+      root.style.setProperty('--bg-image', `url("${backgroundUrl(photo, root.dataset.theme === 'dark', bgBlurred, bgOriginal)}")`)
+      root.dataset.sway = sway ? 'on' : 'off'
     }
     apply()
-    return subscribeAppearance(apply)
+    const observer = new MutationObserver(apply)
+    observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })
+    const unsubscribe = subscribeAppearance(apply)
+    return () => {
+      observer.disconnect()
+      unsubscribe()
+    }
   }, [])
 }

web/display/src/backgroundTint.ts

@@ -1,6 +1,6 @@
 import { useEffect } from 'react'
-import bgLight from './assets/bg.jpg'
-import bgDark from './assets/bg-dark.jpg'
+import { getAppearance, subscribeAppearance } from './appearance'
+import { backgroundUrl } from './backgrounds'
 
 /** 取样的缩略图大小：背景本来就是预先模糊过的，缩得很小就够算平均色。 */
 const SAMPLE_WIDTH = 32
@@ -46,8 +46,8 @@ function toHsl(r: number, g: number, b: number): [number, number, number] {
 }
 
 /**
- * 暗色下玻璃的颜色，和盖在背景图上的底色，都从当前背景图自己的平均色算出来：
- * 色相照搬图里的，饱和度打个折（免得发艳、发蓝），亮度压到很暗。写进 <html> 的 --bg-tint（玻璃）和 --bg-veil-tint（底色），
+ * 暗色下玻璃的颜色，和盖在背景图上的底色，都从当前背景图（选了哪组照片、哪个主题）自己的平均色算出来：
+ * 色相照搬图里的，饱和度保留大半，亮度跟着图本身的亮度走但压得很暗。写进 <html> 的 --bg-tint（玻璃）和 --bg-veil-tint（底色），
  * tokens.css 里暗色的 --glass-tint / --glass-veil 用它们；切换主题时重新取。亮色不用这个。
  */
 export function useBackgroundTint() {
@@ -58,12 +58,18 @@ export function useBackgroundTint() {
       const image = images.get(url)
       const average = image && averageColor(image)
       if (!average) return
-      const [h, s] = toHsl(...average)
-      root.style.setProperty('--bg-tint', `hsl(${h.toFixed(0)} ${(s * 55).toFixed(0)}% 13%)`)
-      root.style.setProperty('--bg-veil-tint', `hsl(${h.toFixed(0)} ${(s * 45).toFixed(0)}% 8%)`)
+      const [h, s, l] = toHsl(...average)
+      // 玻璃：色相照搬，饱和度保留大半（上限 45%），亮度跟着图本身的亮度走（图越亮，玻璃越亮，10%–22%）；
+      // 底色（盖在背景图上的遮罩）同理，但更暗（6%–14%）。所以换一张照片，暗色玻璃的颜色和深浅都会跟着变
+      const clamp = (value: number, low: number, high: number) => Math.max(low, Math.min(high, value))
+      const glass = clamp(9 + l * 26, 10, 22)
+      const veil = clamp(5 + l * 14, 6, 14)
+      root.style.setProperty('--bg-tint', `hsl(${h.toFixed(0)} ${clamp(s * 90, 0, 45).toFixed(0)}% ${glass.toFixed(1)}%)`)
+      root.style.setProperty('--bg-veil-tint', `hsl(${h.toFixed(0)} ${clamp(s * 75, 0, 38).toFixed(0)}% ${veil.toFixed(1)}%)`)
     }
     const update = () => {
-      const url = root.dataset.theme === 'dark' ? bgDark : bgLight
+      // 取样用预先模糊的那个版本：和不模糊的原图平均色一样，图小、取得快
+      const url = backgroundUrl(getAppearance().photo, root.dataset.theme === 'dark', true, false)
       if (images.has(url)) {
         apply(url)
         return
@@ -76,6 +82,10 @@ export function useBackgroundTint() {
     update()
     const observer = new MutationObserver(update)
     observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })
-    return () => observer.disconnect()
+    const unsubscribe = subscribeAppearance(update)
+    return () => {
+      observer.disconnect()
+      unsubscribe()
+    }
   }, [])
 }

web/display/src/backgrounds.ts

@@ -0,0 +1,81 @@
+import bgBlurLight from './assets/bg.jpg'
+import bgBlurDark from './assets/bg-dark.jpg'
+import bgSharpLight from './assets/bg-sharp.jpg'
+import bgSharpDark from './assets/bg-sharp-dark.jpg'
+import bgOriginalLight from './assets/bg-sharp.png'
+import bgOriginalDark from './assets/bg-sharp-dark.png'
+import banaBlur from './assets/bg-bana.jpg'
+import banaSharp from './assets/bg-bana-sharp.jpg'
+import banaOriginal from './assets/bg-bana-sharp.png'
+import bana2Blur from './assets/bg-bana2.jpg'
+import bana2Sharp from './assets/bg-bana2-sharp.jpg'
+import bana2Original from './assets/bg-bana2-sharp.png'
+import photo86_3Blur from './assets/photo86-3-blur.jpg'
+import photo86_3 from './assets/photo86-3.jpg'
+import photo86_3Original from './assets/photo86-3-original.png'
+import photo86_7Blur from './assets/photo86-7-blur.jpg'
+import photo86_7 from './assets/photo86-7.jpg'
+import photo86_7Original from './assets/photo86-7-original.jpg'
+import photo86_2Blur from './assets/photo86-2-blur.jpg'
+import photo86_2 from './assets/photo86-2.jpg'
+import photo86_2Original from './assets/photo86-2-original.jpg'
+import photo86_8Blur from './assets/photo86-8-blur.jpg'
+import photo86_8 from './assets/photo86-8.jpg'
+import photo86_8Original from './assets/photo86-8-original.jpg'
+import photo86_5Blur from './assets/photo86-5-blur.jpg'
+import photo86_5 from './assets/photo86-5.jpg'
+import photo86_5Original from './assets/photo86-5-original.jpg'
+import photo86_6Blur from './assets/photo86-6-blur.jpg'
+import photo86_6 from './assets/photo86-6.jpg'
+import photo86_6Original from './assets/photo86-6-original.jpg'
+
+/** 一张照片的三个版本：blur 是预先模糊过的，sharp 是不模糊但压缩过的，original 是没压缩的原图。 */
+export interface Variants {
+  blur: string
+  sharp: string
+  original: string
+}
+
+/** 可选的背景照片：group 是分组（面板里一组一行），亮色和暗色可以是不同的两张，也可以是同一张。 */
+export interface Photo {
+  id: string
+  group: string
+  label: string
+  light: Variants
+  dark: Variants
+}
+
+const same = (variants: Variants) => ({ light: variants, dark: variants })
+
+/** 加一张照片：把它的三个版本放进 assets/，在这里加一项。第一项是默认的。 */
+export const PHOTOS: Photo[] = [
+  {
+    id: 'sleep',
+    group: 'shirobana',
+    label: '睡颜',
+    // 亮色睁眼、暗色闭眼
+    light: { blur: bgBlurLight, sharp: bgSharpLight, original: bgOriginalLight },
+    dark: { blur: bgBlurDark, sharp: bgSharpDark, original: bgOriginalDark },
+  },
+  { id: 'bana', group: 'shirobana', label: '伸手', ...same({ blur: banaBlur, sharp: banaSharp, original: banaOriginal }) },
+  { id: 'bana2', group: 'shirobana', label: '海边', ...same({ blur: bana2Blur, sharp: bana2Sharp, original: bana2Original }) },
+  { id: '86-3', group: '86', label: '小憩', ...same({ blur: photo86_3Blur, sharp: photo86_3, original: photo86_3Original }) },
+  { id: '86-7', group: '86', label: '窗边', ...same({ blur: photo86_7Blur, sharp: photo86_7, original: photo86_7Original }) },
+  { id: '86-2', group: '86', label: '伞下', ...same({ blur: photo86_2Blur, sharp: photo86_2, original: photo86_2Original }) },
+  { id: '86-8', group: '86', label: '驾驶', ...same({ blur: photo86_8Blur, sharp: photo86_8, original: photo86_8Original }) },
+  { id: '86-5', group: '86', label: '怀中', ...same({ blur: photo86_5Blur, sharp: photo86_5, original: photo86_5Original }) },
+  { id: '86-6', group: '86', label: '倚靠', ...same({ blur: photo86_6Blur, sharp: photo86_6, original: photo86_6Original }) },
+]
+
+export const DEFAULT_PHOTO = PHOTOS[0].id
+
+/** 照片所在的分组，按出现的顺序。 */
+export const PHOTO_GROUPS = [...new Set(PHOTOS.map((photo) => photo.group))]
+
+export const findPhoto = (id: string): Photo => PHOTOS.find((photo) => photo.id === id) ?? PHOTOS[0]
+
+/** 当前该用哪张图：哪张照片、哪个主题，再按「背景模糊」「不压缩」选版本。 */
+export function backgroundUrl(id: string, dark: boolean, blurred: boolean, original: boolean): string {
+  const variants = dark ? findPhoto(id).dark : findPhoto(id).light
+  return blurred ? variants.blur : original ? variants.original : variants.sharp
+}

web/display/src/display.css

@@ -1008,7 +1008,7 @@
   z-index: -1;
   background-image:
     linear-gradient(color-mix(in srgb, var(--glass-veil) var(--bg-veil), transparent), color-mix(in srgb, var(--glass-veil) var(--bg-veil), transparent)),
-    url('./assets/bg.jpg');
+    var(--bg-image, url('./assets/bg.jpg'));
   background-size: cover;
   background-position: center;
   pointer-events: none;
@@ -1017,18 +1017,24 @@
 }
 
 :root {
-  --bg-veil: 50%;
+  /* 盖在背景图上的遮罩的浓度：默认亮色 50%、暗色 62%；右下角「外观」里按倍数调（--bg-veil-scale，0 是不盖） */
+  --bg-veil: min(100%, calc(50% * var(--bg-veil-scale, 1)));
 }
 
 :root[data-theme="dark"] {
-  --bg-veil: 62%;
+  --bg-veil: min(100%, calc(62% * var(--bg-veil-scale, 1)));
 }
 
-/* 暗色模式换一张背景图 */
+/* 用哪张图由「外观」里的选择决定（backgrounds.ts，JS 把它写进 --bg-image）；这里的回退只管 JS 还没跑的第一帧：暗色先用暗色那张 */
 :root[data-theme="dark"] .bg-layer {
   background-image:
     linear-gradient(color-mix(in srgb, var(--glass-veil) var(--bg-veil), transparent), color-mix(in srgb, var(--glass-veil) var(--bg-veil), transparent)),
-    url('./assets/bg-dark.jpg');
+    var(--bg-image, url('./assets/bg-dark.jpg'));
+}
+
+/* 关了背景晃动：背景不会再移动，就不用向外多留一圈边距了，按窗口的原始比例铺满（不会被放大裁掉四周） */
+:root[data-sway='off'] .bg-layer {
+  inset: 0;
 }
 
 /* ── 亚克力（毛玻璃）规范：所有玻璃面（卡片、线路面板、顶部栏、时间轴）只用下面这组变量；颜色来自 tokens.css 的 --glass-*，换风格改那里 ──
@@ -1313,8 +1319,8 @@ input {
   white-space: nowrap;
 }
 
-/* 悬浮提示弹在卡片右边，会盖到下一张卡片上：每张卡片都有自己的层叠上下文（毛玻璃），所以悬停（提示打开）的那张要整张抬到兄弟卡片之上 */
-.agent-card:hover,
+/* 悬浮提示弹在卡片右边，会盖到下一张卡片上：每张卡片都有自己的层叠上下文（毛玻璃），所以提示打开的那张要整张抬到兄弟卡片之上。
+   只在提示真的打开时才抬，不要鼠标一碰到卡片就抬：z-index 一变，带 backdrop-filter 的整张卡片要重新分层，那一帧底部会闪黑 */
 .agent-card:has(.pop.open) {
   z-index: 30;
 }
@@ -1393,8 +1399,7 @@ input {
   height: 100%;
   z-index: -1;
   pointer-events: none;
-  /* 滤色：粒子只会把背后的图提亮，边缘羽化的地方自然融进图里 */
-  mix-blend-mode: screen;
+  /* 不要用 mix-blend-mode（滤色等）：画布在带 backdrop-filter 的卡片后面每帧都在变，再叠一层混合，Chrome 给卡片取背景的时候会整块重新分层，卡片底部就闪黑；边缘的羽化用颜色和透明度做，已经是浅色半透明的，效果和滤色差不多 */
 }
 
 @media (max-width: 640px), ((pointer: coarse) and (max-width: 900px)) {
@@ -1624,6 +1629,38 @@ input {
   transform: translateX(14px);
 }
 
+.appearance-row-segment {
+  grid-template-columns: 52px 1fr;
+}
+
+/* 三选一：连在一起的三个按钮，选中的那个是实心的 */
+.appearance-segment {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  padding: 2px;
+  border-radius: var(--r-pill);
+  background: color-mix(in srgb, var(--app-ink) 8%, transparent);
+}
+
+.appearance-segment button {
+  padding: 3px 0;
+  border: 0;
+  border-radius: var(--r-pill);
+  color: var(--app-ink-muted);
+  background: none;
+  cursor: pointer;
+  transition:
+    background 0.2s,
+    color 0.2s;
+}
+
+.appearance-segment button[aria-pressed='true'] {
+  color: var(--app-ink);
+  font-weight: 600;
+  background: var(--app-card);
+  box-shadow: 0 1px 3px color-mix(in srgb, var(--glass-shade) 25%, transparent);
+}
+
 .appearance-reset {
   margin-top: 12px;
   width: 100%;
@@ -1657,3 +1694,55 @@ input {
     display: none;
   }
 }
+
+/* 照片的选择：按组分行，每组一个小标题，下面是缩略图，选中的描一圈 */
+.appearance-group-title {
+  margin-bottom: 4px;
+  color: var(--app-ink-faint);
+  font-size: 11px;
+  letter-spacing: 0.04em;
+}
+
+.appearance-choices {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+}
+
+.appearance-choice {
+  display: grid;
+  gap: 4px;
+  padding: 0;
+  border: 0;
+  color: var(--app-ink-muted);
+  background: none;
+  cursor: pointer;
+  text-align: center;
+  font-size: 12px;
+}
+
+.appearance-choice img {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  border-radius: var(--r-control);
+  box-shadow: inset 0 0 0 1px var(--glass-ring);
+  transition:
+    box-shadow 0.2s,
+    transform 0.2s;
+}
+
+.appearance-choice:hover img {
+  transform: translateY(-1px);
+}
+
+.appearance-choice[aria-pressed='true'] {
+  color: var(--app-ink);
+  font-weight: 600;
+}
+
+.appearance-choice[aria-pressed='true'] img {
+  box-shadow:
+    0 0 0 2px var(--app-primary),
+    0 0 0 4px color-mix(in srgb, var(--app-primary) 25%, transparent);
+}

web/display/src/parallax.ts

@@ -1,5 +1,5 @@
 import { useEffect, type RefObject } from 'react'
-import { getAppearance } from './appearance'
+import { getAppearance, subscribeAppearance } from './appearance'
 
 /** 指针在窗口里的位置带来的偏移上限（像素）：鼠标停在窗口边缘时背景偏这么多。 */
 const POSITION_SHIFT = 30
@@ -53,7 +53,7 @@ export function useBackgroundParallax(layer: RefObject<HTMLElement | null>) {
     const clamp = (value: number) => Math.max(-SWAY_MAX, Math.min(SWAY_MAX, value))
     const move = (event: PointerEvent) => {
       // 位置：指针在窗口里的位置换成 -1 到 1（背景朝同一个方向偏移，想要反方向就把符号取反）
-      const amount = getAppearance().parallax
+      const amount = swayAmount()
       baseX = ((event.clientX / window.innerWidth) * 2 - 1) * POSITION_SHIFT * amount
       baseY = ((event.clientY / window.innerHeight) * 2 - 1) * POSITION_SHIFT * amount
       // 晃动：这一次移动了多远，就再推背景一把
@@ -65,6 +65,11 @@ export function useBackgroundParallax(layer: RefObject<HTMLElement | null>) {
       lastY = event.clientY
       schedule()
     }
+    // 晃动的幅度：总开关关了就是 0
+    const swayAmount = () => {
+      const { sway, parallax } = getAppearance()
+      return sway ? parallax : 0
+    }
     const leave = () => {
       baseX = 0
       baseY = 0
@@ -75,7 +80,16 @@ export function useBackgroundParallax(layer: RefObject<HTMLElement | null>) {
 
     window.addEventListener('pointermove', move, { passive: true })
     document.documentElement.addEventListener('mouseleave', leave)
+    // 设置里把晃动关了：背景慢慢回到中间，不用等下一次鼠标移动
+    const unsubscribe = subscribeAppearance(() => {
+      if (swayAmount() === 0) {
+        swayX = 0
+        swayY = 0
+        leave()
+      }
+    })
     return () => {
+      unsubscribe()
       window.removeEventListener('pointermove', move)
       document.documentElement.removeEventListener('mouseleave', leave)
       cancelAnimationFrame(frame)

web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "moshiro-web",
-  "version": "0.4.0",
+  "version": "0.0.0-dev",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "moshiro-web",
-      "version": "0.4.0",
+      "version": "0.0.0-dev",
       "workspaces": [
         "display",
         "admin"
@@ -18,7 +18,7 @@
     },
     "admin": {
       "name": "moshiro-admin",
-      "version": "0.1.0",
+      "version": "0.0.0-dev",
       "dependencies": {
         "lucide-react": "^0.468.0",
         "react": "^19.2.8",
@@ -38,7 +38,7 @@
     },
     "display": {
       "name": "moshiro-display",
-      "version": "0.1.0",
+      "version": "0.0.0-dev",
       "dependencies": {
         "lucide-react": "^0.468.0",
         "react": "^19.2.8",

web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moshiro-web",
   "private": true,
-  "version": "0.4.0",
+  "version": "0.0.0-dev",
   "workspaces": [
     "display",
     "admin"