Blankfiles Website

🚀 空白文件網站

這是一個基於 Laravel 的應用程序，為 blankfiles.com 提供支持。用戶可以按類型和類別瀏覽並下載最小有效空白文件。文件數據和資源通過可配置的 CDN 從 filearchitect/blank-files 倉庫提供。

🚀 快速開始

本項目是一個基於 Laravel 的應用程序，用於搭建空白文件網站。用戶可通過該網站按類型和類別瀏覽並下載最小有效空白文件。

✨ 主要特性

• 支持按文件類型和類別瀏覽與下載空白文件。
• 文件數據和資源通過可配置的 CDN 從指定倉庫獲取。
• 提供 Web 界面和 API 接口，方便不同方式的訪問。
• 支持緩存配置，可減少 CDN 請求。
• 具備 API 速率限制和使用分析日誌。

📦 安裝指南

環境要求

• PHP 8.2 及以上版本
• Composer
• Node.js 18 及以上版本（用於 Vite 前端構建）

安裝步驟

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

在 .env 文件中設置 CDN_URL（詳見 配置說明）。然後構建前端並運行應用：

npm install && npm run build
php artisan serve

或者使用 Laravel Herd 並配置 .test 域名。

📚 詳細文檔

配置說明

項目結構

部署說明

當推送到 main 分支時，GitHub Actions 會執行以下操作：

1. 使用 npm ci 和 npm run build 構建前端（Vite）。
2. 使用 SCP 將 public/build/ 目錄複製到 Forge 服務器。
3. 觸發 Laravel Forge 部署。
4. 在服務器上運行 php artisan optimize:clear。

所需的倉庫密鑰：

• FORGE_SSH_HOST — 服務器的 SSH 主機。
• FORGE_SSH_USER — SSH 用戶（例如 forge）。
• SSH_PRIVATE_KEY — 用於 SCP/SSH 的私鑰。
• FORGE_SERVER_ID — Forge 服務器 ID。
• FORGE_SITE_ID — Forge 站點 ID。
• FORGE_API_KEY — Forge 部署令牌。

詳見 .github/workflows/deploy.yml。

開發者和機器人相關

基礎 URL

生產環境：https://blankfiles.com。支持 HTML 和 JSON 格式；在適用的情況下使用 Accept: application/json。

Web 路由

API 路由（前綴 api/v1）

機器友好說明

• 規範的文件目錄架構定義在 blank-files 倉庫中：files/files.json（鍵 files，數組元素為 { type, url, category, package? }）。
• 下載 URL：可使用 API 的 url 字段直接訪問 CDN，或使用 GET /files/download/{category}/{type} 進行同源下載並獲得可預測的文件名。
• API 響應和站點地圖支持條件請求（ETag、Last-Modified）。
• 速率限制：基於公共 IP 的限制和可選的 API 密鑰限制（X-API-Key）。
• API 使用分析日誌記錄到 storage/logs/api-usage-*.log（可配置通道）。
• 兼容性策略：API 策略。
• 增長頁面的 Web 著陸分析日誌記錄到 storage/logs/web-traffic-*.log。

客戶端代碼片段

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // 未更改
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

兼容性策略

• /api/v1/* 下的 URL 版本穩定。
• 重大變更需要新的主要 API 路徑版本。
• 棄用的端點在移除前至少保留 90 天。
• 可以添加新字段；客戶端應忽略未知字段。

相關項目

• filearchitect/blank-files — 文件列表和空白文件資源的真實來源。

MCP 服務器（適用於代理市場/註冊表）

本倉庫現在包含一個最小的 MCP 服務器，將空白文件作為工具調用公開。

• 腳本：scripts/mcp/blankfiles-mcp.mjs
• 運行：npm run mcp:server
• 可選環境變量：BLANKFILES_BASE_URL（默認值：https://blankfiles.com）

可用的 MCP 工具：

• list_blank_files — 列出文件，可選過濾器（category、type、limit）
• files_by_type — 按文件擴展名列出條目
• file_by_category_type — 通過類別 + 擴展名進行確定性單查找

本地 MCP 客戶端配置示例：

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

註冊表提交輔助工具：

• 模板元數據：scripts/mcp/registry/server.json.template
• 發佈清單：scripts/mcp/registry/PUBLISHING.md

已發佈的包工作區：

• packages/blankfiles-mcp（發佈為 @filearchitect/blankfiles-mcp）

OpenClaw 技能（ClawHub 可發現性）

本倉庫包含一個適用於 OpenClaw 的技能包：

• 技能路徑：skills/blankfiles
• 技能入口：skills/blankfiles/SKILL.md
• 發佈指南：skills/blankfiles/references/publish.md

典型的發佈流程：

npm i -g clawhub
clawhub login
clawhub publish ./skills/blankfiles \
  --slug blankfiles \
  --name "Blank Files Gateway" \
  --version 1.0.0 \
  --changelog "Initial release" \
  --tags latest

📄 許可證

本項目採用 MIT 許可證。