refactor: 取消content分支并更新抓取流程

Author: Ziphyrien

.github/workflows/deploy.yml

@@ -6,10 +6,12 @@ on:
     paths:
       - "starlight/**"
       - ".github/workflows/deploy.yml"
-  repository_dispatch:
-    types: [content-updated]
   workflow_dispatch:
 
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
 permissions:
   contents: read
   pages: write
@@ -19,29 +21,18 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout Main (Scripts & Starlight)
-        uses: actions/checkout@v6
-
-      - name: Checkout Content
+      - name: Checkout Main
         uses: actions/checkout@v6
-        with:
-          ref: content
-          path: content
-          fetch-depth: 0
 
-      - name: Sync Content to Starlight
+      - name: Validate content tree
         run: |
-          TARGET="starlight/src/content/docs"
-          SOURCE="content/docs"
-
-          mkdir -p "$TARGET"
-
-          if [ -d "$SOURCE" ]; then
-            cp -r "$SOURCE"/* "$TARGET"/
+          if [ ! -d "starlight/src/content/docs" ]; then
+            echo "::error::Missing content docs directory: starlight/src/content/docs"
+            exit 1
           fi
 
-          echo "Content synced:"
-          ls -R starlight/src/content/docs | head -n 30
+          echo "Content ready at starlight/src/content/docs"
+          find starlight/src/content/docs -maxdepth 2 -type f | head -n 30
 
       - name: Install, build, and upload site
         uses: withastro/action@v5

.gitignore

@@ -36,5 +36,3 @@ yarn-error.log*
 *.temp
 .cache/
 
-# Content
-starlight/src/content/

README.md

@@ -12,17 +12,14 @@
 
 ## 结构
 
-本项目采用 **Git Worktree** 实现代码与内容的分离：
+本项目采用 **单分支结构**，代码与文档内容统一维护在 `main` 分支中：
 
-- **Main 分支** (`/`): 存放项目基础设施代码。
-  - `scripts/`: Python 爬虫核心代码。
-    - `crawl.py`: 爬虫入口。
-    - `wiki_configs.json`: 爬虫源配置。
-  - `starlight/`: 文档网站前端项目 (Astro)。
-  - `TRANSLATION_PROMPT.md`: 翻译规范与术语表。
-
-- **Content 分支** (挂载于 `starlight/src/content/`): 存放所有文档数据。
-  - `docs/`: Markdown 文档源文件（爬虫输出目标）。
+- `scripts/`: Python 爬虫核心代码。
+  - `crawl.py`: 爬虫入口。
+  - `wiki_configs.json`: 爬虫源配置。
+- `starlight/`: 文档网站前端项目 (Astro)。
+  - `src/content/docs/`: Markdown 文档源文件（爬虫输出目标）。
+- `TRANSLATION_PROMPT.md`: 翻译规范与术语表。
 
 ## 开始
 
@@ -36,15 +33,9 @@
 
 ### 2. 克隆仓库
 
-由于本项目采用 **Git Worktree** 管理文档内容（代码与内容分离），请严格按照以下步骤克隆与初始化：
-
 ```bash
-# 克隆主仓库
 git clone https://github.com/Ziphyrien/Plugins-Wiki.git
 cd Plugins-Wiki
-
-# 挂载 content 分支到 starlight/src/content
-git worktree add starlight/src/content content
 ```
 
 ### 3. 安装依赖
@@ -80,7 +71,7 @@ python crawl.py coinsengine
 python crawl.py all
 ```
 
-> **注意**: 爬取的内容会自动输出到 Worktree 挂载的 `starlight/src/content/docs` 目录中。
+> **注意**: 爬取的内容会直接输出到仓库内的 `starlight/src/content/docs` 目录中。
 
 ### 5. 本地预览
 

scripts/core/base_crawler.py

@@ -13,10 +13,9 @@
 class BaseCrawler(ABC):
     """Abstract base class for all wiki crawlers."""
 
-    def __init__(self, name: str, config: dict, content_root: Path):
+    def __init__(self, name: str, config: dict):
         self.name = name
         self.config = config
-        self.content_root = Path(content_root)
         self.base_url = config["base_url"].rstrip("/")
         self.output_dir = Path(config["output_dir"])
         self.session = requests.Session()
@@ -39,12 +38,17 @@ def run(self) -> tuple[int, int]:
         Main entry point. Returns (success_count, fail_count).
         """
         logger.info("=" * 60)
-        logger.info(f"文档同步工具 - {self.name} ({self.__class__.__name__})")
+        logger.info(f"文档抓取工具 - {self.name} ({self.__class__.__name__})")
         logger.info("=" * 60)
 
         try:
             pages = self.fetch_pages()
             total = len(pages)
+
+            if total == 0:
+                logger.warning("⚠️ 未发现可抓取页面")
+                return 0, 0
+
             logger.info(f"📄 发现 {total} 个页面")
             logger.info("-" * 60)
 
@@ -56,7 +60,7 @@ def run(self) -> tuple[int, int]:
                     failed += 1
 
             logger.info("-" * 60)
-            logger.info(f"📊 同步完成: {success} 成功, {failed} 失败")
+            logger.info(f"📊 抓取完成: {success} 成功, {failed} 失败")
             return success, failed
 
         except Exception as e:

scripts/core/crawler_gitbook.py

@@ -2,7 +2,6 @@
 GitBook crawler implementation.
 """
 import xml.etree.ElementTree as ET
-from pathlib import Path
 from urllib.parse import unquote
 import logging
 
@@ -16,8 +15,8 @@
 class GitBookCrawler(BaseCrawler):
     """Crawler for GitBook-based wikis using sitemap."""
 
-    def __init__(self, name: str, config: dict, content_root: Path):
-        super().__init__(name, config, content_root)
+    def __init__(self, name: str, config: dict):
+        super().__init__(name, config)
         self.sitemap_url = config["sitemap_url"]
 
     def fetch_pages(self) -> list[dict]:

scripts/core/crawler_retype.py

@@ -98,8 +98,8 @@ def convert_img(self, el, text, parent_tags):
 class RetypeCrawler(BaseCrawler):
     """Crawler for Retype-based documentation sites."""
 
-    def __init__(self, name: str, config: dict, content_root: Path):
-        super().__init__(name, config, content_root)
+    def __init__(self, name: str, config: dict):
+        super().__init__(name, config)
         self.config_url = config["config_url"]
 
     def fetch_pages(self) -> list[dict]:

scripts/crawl.py

@@ -4,6 +4,7 @@
 """
 import argparse
 import logging
+import shutil
 import sys
 from pathlib import Path
 
@@ -22,33 +23,86 @@
 
 # Paths
 SCRIPT_DIR = Path(__file__).parent
-PROJECT_ROOT = SCRIPT_DIR.parent
-CONTENT_ROOT = PROJECT_ROOT.parent / "content"
+PROJECT_ROOT = SCRIPT_DIR.parent.resolve()
 
 CRAWLER_MAP = {
     "gitbook": GitBookCrawler,
     "retype": RetypeCrawler,
 }
 
 
+def resolve_output_dir(config: dict) -> Path | None:
+    """Resolve and validate output_dir relative to the project root."""
+    raw_output_dir = str(config.get("output_dir", "")).strip()
+    if not raw_output_dir:
+        logger.error("配置缺少 output_dir")
+        return None
+
+    output_dir = (PROJECT_ROOT / raw_output_dir).resolve()
+
+    try:
+        output_dir.relative_to(PROJECT_ROOT)
+    except ValueError:
+        logger.error(f"output_dir 超出项目目录: {output_dir}")
+        return None
+
+    return output_dir
+
+
+def create_staging_dir(output_dir: Path) -> Path:
+    """Create a clean staging directory next to the final output directory."""
+    staging_dir = output_dir.parent / f".{output_dir.name}.staging"
+    if staging_dir.exists():
+        shutil.rmtree(staging_dir)
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    return staging_dir
+
+
+def publish_staging_dir(staging_dir: Path, output_dir: Path) -> None:
+    """Atomically replace the final output directory with staged content."""
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+    staging_dir.rename(output_dir)
+
+
 def run_crawler(name: str, config: dict) -> tuple[int, int]:
     """Run a crawler for the given wiki config."""
     crawler_type = config.get("type")
     crawler_class = CRAWLER_MAP.get(crawler_type)
 
     if not crawler_class:
         logger.error(f"未知爬虫类型: {crawler_type}")
-        return 0, 0
+        return 0, 1
 
-    # Resolve output_dir relative to PROJECT_ROOT
-    raw_output_dir = config.get("output_dir", "")
-    abs_output_dir = (PROJECT_ROOT / raw_output_dir).resolve()
+    output_dir = resolve_output_dir(config)
+    if output_dir is None:
+        return 0, 1
+
+    staging_dir = create_staging_dir(output_dir)
+    logger.info(f"输出目录: {output_dir.relative_to(PROJECT_ROOT)}")
 
     crawl_config = config.copy()
-    crawl_config["output_dir"] = abs_output_dir
+    crawl_config["output_dir"] = staging_dir
+
+    crawler = crawler_class(name, crawl_config)
+
+    try:
+        success, failed = crawler.run()
+
+        if success == 0 and failed == 0:
+            logger.error("未抓取到任何页面，保留现有输出目录")
+            return 0, 1
+
+        if failed > 0:
+            logger.error("存在抓取失败页面，保留现有输出目录")
+            return success, failed
 
-    crawler = crawler_class(name, crawl_config, CONTENT_ROOT)
-    return crawler.run()
+        publish_staging_dir(staging_dir, output_dir)
+        logger.info(f"📦 已发布到: {output_dir.relative_to(PROJECT_ROOT)}")
+        return success, failed
+    finally:
+        if staging_dir.exists():
+            shutil.rmtree(staging_dir)
 
 
 def main():

starlight/src/content/docs/en/coinsengine/commands.md

@@ -0,0 +1,65 @@
+---
+title: Commands
+sidebar:
+  order: 2
+---
+
+Command aliases can be changed in the **engine.yml**. By default it's `/coinsengine` or `/coe`.
+
+## Flags
+
+* `-s` - makes silent command execution (target player won't be notified).
+* `-sf` - disables command feedback to the command sender.
+
+## Plugin Commands
+
+`<> Required` `[] Optional`
+
+* `/coe [help]` - List of all plugin commands.
+* `/coe reload` - Reload the plugin.
+* `/coe create <name> <symbol> <decimals>` - [Creates](features/currencies#creation) a new currency.
+* `/coe reset <player>` - Reset player's balance for all currencies.
+* `/coe resetall [currency]` - Reset balance of all or specific currency for all players.
+* `/coe migrate <plugin> <currency>` - [Migrate](features/migration) balances from specific plugin to specific currency.
+
+## Currency Commands
+
+Each currency has it's own command aliases defined in the [currency config](features/currencies) under `Command_Aliases` option.
+
+Commands listed below are valid for the currency with the `coins` command alias.
+
+`<> Required` `[] Optional`
+
+* `/coins balance [player]` - View "coins" balance.
+* `/coins pay <player> <amount>` - Pay some "coins" some player.
+* `/coins payments [player] [-s]` - Toggle "coins" payments from other players.
+* `/coins giveall <amount> [-s] [-sf]` - Give "coins" to all online players.
+* `/coins give <player> <amount> [-s] [-sf]` - Give "coins" to a player.
+* `/coins take <player> <amount> [-s] [-sf]` - Take "coins" from a player.
+* `/coins set <player> <amount> [-s] [-sf]` - Set "coins" balance for a player.
+* `/coins exchange <currency> <amount>` - Exchange "coins" for other currency.
+* `/coins top [page]` - Top players with "coins". Requires the [Leaderboards](features/leaderboards) feature to be enabled.
+
+:::note
+[Number Shortcuts](https://nightexpressdev.com/nightcore/configuration/number-formation/#number-shortcuts) are supported in the `amount` argument!
+:::
+
+There is the `commands.yml` config file inside the CoinsEngine directory, where you can edit and disable any currency-related command.
+
+**Command Options:**
+
+* `Children` - Controls whether the command is available as  of the currency command. Example: `/coins balance`
+* `Dedicated` - Controls whether the command is available as  command for primary currency. Example: `/balance`
+
+## Dedicated Commands
+
+* `/wallet [player]` - View balance of all currencies. Requires the [Wallet](features/wallet) feature to be enabled.
+* `/balance [player]` - View balance of primary currency.
+* `/baltop [page]` - Top players by primary currency. Requires the [Leaderboards](features/leaderboards) feature to be enabled.
+* `/pay <player> <amount>` - Pay player with primary currency.
+* `/paytoggle [player]` - Toggle primary currency payments from players.
+
+:::note
+Primary currency is the one that linked with [Vault](hooks/vault).
+:::
+