feat: 避免删除配置后 Gist 变空，新增占位文件兜底并回传同步状态

- 删除 artifact 时新增空仓库兜底文件 `.sub-store-placeholder`，避免 GitHub/GitLab Gist/代码片段因无文件而报错
- `syncToGist` 支持可选 `emptyFileFallback`，默认写入上述占位文件，并在上传真实文件时自动移除
- `Gist.upload` 增加空文件兜底元信息上报（created/removed/retained），兼容 GitHub 与 GitLab 的文件增删改造
- 恢复配置时会跳过占位文件，artifact 名称校验也排除该占位文件名
- 删除接口返回值改为包含远端同步状态（成功/失败/占位文件保留）
- 补充 `gist.spec.js` 单测，覆盖占位文件创建、移除、默认兜底参数是否透传

Author: xream

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sub-store",
-  "version": "2.22.21",
+  "version": "2.22.22",
   "description": "Advanced Subscription Manager for QX, Loon, Surge, Stash and Shadowrocket.",
   "main": "src/main.js",
   "scripts": {

backend/src/restful/artifacts.js

@@ -21,6 +21,12 @@ import {
 import Gist from '@/utils/gist';
 import { archiveArtifact } from '@/utils/archive';
 
+const ARTIFACT_GIST_PLACEHOLDER_FILENAME = '.sub-store-placeholder';
+const ARTIFACT_GIST_PLACEHOLDER_CONTENT = [
+    'Sub-Store placeholder',
+    'This file keeps the Gist alive when all sync configuration files are deleted.',
+].join('\n');
+
 export default function register($app) {
     // Initialization
     if (!$.read(ARTIFACTS_KEY)) $.write({}, ARTIFACTS_KEY);
@@ -62,6 +68,10 @@ async function restoreArtifacts(_, res) {
             Object.keys(gist.files).map((key) => {
                 const filename = gist.files[key]?.filename;
                 if (filename) {
+                    if (isArtifactGistPlaceholder(filename)) {
+                        $.info(`忽略 Gist 占位文件: ${filename}`);
+                        return;
+                    }
                     if (encodeURIComponent(filename) !== filename) {
                         $.error(`文件名 ${filename} 未编码 不保存`);
                         failed.push(filename);
@@ -188,8 +198,8 @@ async function deleteArtifact(req, res) {
         if (shouldArchiveDeletion(req.query.mode)) {
             archiveArtifact(name);
         }
-        await deleteArtifactItem(name);
-        success(res);
+        const result = await deleteArtifactItem(name);
+        success(res, result);
     } catch (err) {
         $.error(`无法删除远程配置：${req.params.name}，原因：${err}`);
         failed(
@@ -208,7 +218,10 @@ async function deleteArtifact(req, res) {
 }
 
 function validateArtifactName(name) {
-    return /^[a-zA-Z0-9._-]*$/.test(name);
+    return (
+        /^[a-zA-Z0-9._-]*$/.test(name) &&
+        !isArtifactGistPlaceholder(name)
+    );
 }
 
 function createArtifactItem(artifact) {
@@ -241,6 +254,10 @@ async function deleteArtifactItem(name) {
             `Artifact ${name} does not exist!`,
         );
     }
+    const remote = {
+        attempted: false,
+        status: 'not_attempted',
+    };
     if (artifact.updated) {
         const files = {};
         files[encodeURIComponent(artifact.name)] = {
@@ -251,15 +268,30 @@ async function deleteArtifactItem(name) {
                 content: '',
             };
         }
+        remote.attempted = true;
         try {
-            await syncToGist(files);
+            const resp = await syncToGist(files);
+            const fallback = resp.subStoreUploadMeta?.emptyFileFallback;
+            remote.status =
+                fallback?.status === 'created' ||
+                fallback?.status === 'retained'
+                    ? 'placeholder_retained'
+                    : 'deleted';
+            if (fallback?.filename) {
+                remote.placeholderFilename = fallback.filename;
+            }
         } catch (error) {
+            remote.status = 'failed';
+            remote.message = `${error.message ?? error}`;
             $.error(`Function syncToGist: ${name} : ${error}`);
         }
     }
     deleteByName(allArtifacts, name);
     $.write(allArtifacts, ARTIFACTS_KEY);
-    return artifact;
+    return {
+        artifact,
+        remote,
+    };
 }
 
 function shouldArchiveDeletion(mode) {
@@ -275,7 +307,18 @@ function shouldArchiveDeletion(mode) {
     );
 }
 
-async function syncToGist(files) {
+function isArtifactGistPlaceholder(name) {
+    return name === ARTIFACT_GIST_PLACEHOLDER_FILENAME;
+}
+
+function getArtifactGistEmptyFileFallback() {
+    return {
+        filename: ARTIFACT_GIST_PLACEHOLDER_FILENAME,
+        content: ARTIFACT_GIST_PLACEHOLDER_CONTENT,
+    };
+}
+
+async function syncToGist(files, options = {}) {
     const { gistToken, syncPlatform } = $.read(SETTINGS_KEY);
     if (!gistToken) {
         return Promise.reject('未设置 GitHub Token！');
@@ -285,7 +328,11 @@ async function syncToGist(files) {
         key: ARTIFACT_REPOSITORY_KEY,
         syncPlatform,
     });
-    const res = await manager.upload(files);
+    const res = await manager.upload(files, {
+        ...options,
+        emptyFileFallback:
+            options.emptyFileFallback ?? getArtifactGistEmptyFileFallback(),
+    });
     let body = {};
     try {
         body = JSON.parse(res.body);

backend/src/test/utils/gist.spec.js

@@ -1,7 +1,10 @@
 import { expect } from 'chai';
 import { describe, it } from 'mocha';
 
-import { getGithubGistBaseURL } from '@/utils/gist';
+import $ from '@/core/app';
+import { SETTINGS_KEY } from '@/constants';
+import Gist, { getGithubGistBaseURL } from '@/utils/gist';
+import { syncToGist } from '@/restful/artifacts';
 
 describe('Gist GitHub API URL', function () {
     it('uses the default GitHub API URL when unset', function () {
@@ -32,4 +35,163 @@ describe('Gist GitHub API URL', function () {
             }),
         ).to.equal('https://litegist.example.com/api');
     });
+
+    it('keeps an existing Gist alive with a fallback file when a delete would empty it', async function () {
+        const manager = Object.create(Gist.prototype);
+        let patchBody;
+
+        manager.syncPlatform = '';
+        manager.locate = async () => ({
+            id: 'gist-id',
+            files: {
+                artifact: {
+                    filename: 'artifact',
+                },
+            },
+        });
+        manager.http = {
+            patch: async ({ body }) => {
+                patchBody = JSON.parse(body);
+                return {
+                    body: JSON.stringify({
+                        files: {
+                            '.sub-store-placeholder': {
+                                filename: '.sub-store-placeholder',
+                            },
+                        },
+                    }),
+                };
+            },
+        };
+
+        const response = await manager.upload(
+            {
+                artifact: {
+                    content: '',
+                },
+            },
+            {
+                emptyFileFallback: {
+                    filename: '.sub-store-placeholder',
+                    content: 'placeholder',
+                },
+            },
+        );
+
+        expect(patchBody.files.artifact).to.equal(null);
+        expect(patchBody.files['.sub-store-placeholder']).to.deep.equal({
+            content: 'placeholder',
+        });
+        expect(response.subStoreUploadMeta.emptyFileFallback).to.deep.equal({
+            status: 'created',
+            filename: '.sub-store-placeholder',
+        });
+    });
+
+    it('removes the fallback file when a real file is uploaded later', async function () {
+        const manager = Object.create(Gist.prototype);
+        let patchBody;
+
+        manager.syncPlatform = '';
+        manager.locate = async () => ({
+            id: 'gist-id',
+            files: {
+                '.sub-store-placeholder': {
+                    filename: '.sub-store-placeholder',
+                },
+            },
+        });
+        manager.http = {
+            patch: async ({ body }) => {
+                patchBody = JSON.parse(body);
+                return {
+                    body: JSON.stringify({
+                        files: {
+                            artifact: {
+                                filename: 'artifact',
+                            },
+                        },
+                    }),
+                };
+            },
+        };
+
+        const response = await manager.upload(
+            {
+                artifact: {
+                    content: 'real content',
+                },
+            },
+            {
+                emptyFileFallback: {
+                    filename: '.sub-store-placeholder',
+                    content: 'placeholder',
+                },
+            },
+        );
+
+        expect(patchBody.files.artifact).to.deep.equal({
+            content: 'real content',
+        });
+        expect(patchBody.files['.sub-store-placeholder']).to.equal(null);
+        expect(response.subStoreUploadMeta.emptyFileFallback).to.deep.equal({
+            status: 'removed',
+            filename: '.sub-store-placeholder',
+        });
+    });
+
+    it('passes the artifact placeholder fallback to syncToGist by default', async function () {
+        const originalRead = $.read.bind($);
+        const originalWrite = $.write.bind($);
+        const originalUpload = Gist.prototype.upload;
+        let capturedOptions;
+        let writtenSettings;
+
+        $.read = (key) => {
+            if (key === SETTINGS_KEY) {
+                return {
+                    gistToken: 'token',
+                };
+            }
+            return originalRead(key);
+        };
+        $.write = (data, key) => {
+            if (key === SETTINGS_KEY) {
+                writtenSettings = data;
+                return true;
+            }
+            return originalWrite(data, key);
+        };
+        Gist.prototype.upload = async function (_, options) {
+            capturedOptions = options;
+            return {
+                body: JSON.stringify({
+                    html_url: 'https://gist.example.com/sub-store',
+                    files: {},
+                }),
+            };
+        };
+
+        try {
+            await syncToGist({
+                artifact: {
+                    content: 'real content',
+                },
+            });
+        } finally {
+            $.read = originalRead;
+            $.write = originalWrite;
+            Gist.prototype.upload = originalUpload;
+        }
+
+        expect(capturedOptions.emptyFileFallback).to.deep.equal({
+            filename: '.sub-store-placeholder',
+            content:
+                'Sub-Store placeholder\nThis file keeps the Gist alive when all sync configuration files are deleted.',
+        });
+        expect(writtenSettings.artifactStore).to.equal(
+            'https://gist.example.com/sub-store',
+        );
+        expect(writtenSettings.artifactStoreStatus).to.equal('VALID');
+    });
 });