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 许可证。