ATools · 纯粹工具站

一个「100% 纯前端本地运行」的工具集合站：PWA 可安装、支持 Next.js 静态导出、内置统一 SEO 系统。

• 纯前端：所有文件处理默认在浏览器本地完成（不上传服务器），适合隐私敏感场景。
• 95+ 工具：覆盖文本/编码/JSON/图片/音视频/PDF/办公格式等高频需求（见 src/app/tools）。
• PWA 可安装：每个工具都有独立 manifest，支持"添加到主屏幕"与离线缓存策略。
• Chrome 扩展（可选）：提供 Web 站点无法稳定实现的能力（如对任意网页整页长截图），并在侧边栏内搜索/打开工具（见 docs/browser-extension.md）。
• 完整 i18n 支持：所有工具支持中英双语，基于 tool.en-us.json 的 UI 字段实现优雅的多语言架构。
• FFmpeg.wasm：音视频工具使用本地打包的 @ffmpeg/core。

• Node.js 20+（CI 使用 Node 22）
• 推荐使用 Yarn 1.x（仓库提供 yarn.lock）

yarn install --frozen-lockfile
yarn dev

打开 http://localhost:3000。

首次 dev/build 会自动生成工具导航数据与 PWA 资源（见 scripts/）。

• yarn dev：本地开发（Next Dev）
• yarn build：生产构建（CI 使用 next build --webpack）
• yarn build:turbo：生产构建（next build，用于对比/调试）
• yarn lint：ESLint
• yarn generate:manifests：生成 public/tools/<slug>/manifest.webmanifest 与导航数据
• yarn generate:sw：生成 public/sw.js
• yarn scaffold:tool <slug>：交互式创建新工具骨架（tool.json / tool.en-us.json / page.tsx / *Client.tsx）
• yarn check:tools：检查所有工具目录配置完整性（缺失文件、必填字段、SEO 元数据调用等）

如果需要启用站点行为分析，在构建前设置环境变量：

NEXT_PUBLIC_CLARITY_ID=your-clarity-project-id

当前接入策略为默认 no-consent mode：站点会预加载 Clarity，但在用户未授权前始终以 analytics_Storage=denied、ad_Storage=denied 运行，仅采集无 Cookie 的匿名页面级使用数据。用户在页脚“统计设置”中同意后，才升级为可跨页关联的完整分析模式；工具页主交互区默认额外遮罩，避免会话回放直接暴露用户在工具中的原始内容。

1. 渐进式开发：先实现基础功能，再添加高级特性
2. 频繁测试：每次修改后及时测试功能是否正常
3. 代码审查：提交前检查代码质量和类型安全
4. 性能监控：定期检查页面加载速度和资源使用
5. 多语言测试：确保中英双语环境下功能正常

• src/app/tools/<slug>/：每个工具一个目录（路由：/<locale>/tools/<slug>）
  • tool.json：工具配置（名称/描述/关键词/SEO 文本等）
  • tool.en-us.json：英文 UI 配置文件（含 ui 字段）
  • page.tsx：App Router 页面，导出 dynamic = "force-static" 与 metadata
  • *Client.tsx：客户端组件，使用统一布局 ToolPageLayout
• src/lib/：工具配置、SEO 生成等通用逻辑
• src/components/ToolPageLayout.tsx：统一工具页布局（含 SEO/结构化数据/隐藏 SEO 文本）
• src/components/ToolConfigProvider.tsx：工具配置上下文，支持多语言
• scripts/：
  • generate-tool-manifests.mjs：扫描 tool.json，生成工具 manifests、导航数据、tool registry
  • generate-sw.mjs：生成 public/sw.js

1. 运行脚手架创建基础文件（推荐）：

yarn scaffold:tool my-tool

也可以不带参数启动后再输入 slug：

yarn scaffold:tool

脚本会交互询问以下信息（回车可使用默认值）：

• slug：工具目录名，必须是 kebab-case（如 text-to-speech）
• 中文/英文 shortName
• 中文分类 category
• 中文/英文 name（用于 SEO 标题）
• 中文/英文 description（用于描述与默认 SEO 文案）

脚本会自动生成：

• src/app/tools/<slug>/tool.json
• src/app/tools/<slug>/tool.en-us.json
• src/app/tools/<slug>/page.tsx
• src/app/tools/<slug>/<PascalCase>Client.tsx

2. 完善业务逻辑与 SEO 文案（尤其 seoDescription、keywords）。

3. 运行配置检查：

yarn check:tools

检查结果说明：

• 出现 ERROR：命令会以非 0 退出码结束（CI 会失败），必须修复。
• 仅有 WARN：命令可通过，但建议尽快处理（如缺少 tool.en-us.json、page.tsx 未声明 dynamic = "force-static" 等）。
• 全部通过会输出类似：

[check-tools] 检查完成。
工具数量: <N>
错误总数: 0
警告总数: 0

mkdir src/app/tools/my-tool

tool.json（工具元数据）：

{
  "name": "免费在线我的工具 - 纯粹工具站",
  "shortName": "我的工具",
  "description": "一句话描述这个工具做什么。",
  "seoDescription": "详细的SEO优化描述，包含关键词、工具优势、使用场景等，200-300字，针对搜索引擎和LLM优化...",
  "category": "工具分类",
  "lang": "zh-CN",
  "themeColor": "#0f172a",
  "backgroundColor": "#0f172a",
  "icon": "/icon.svg",
  "keywords": ["免费工具", "在线工具", "关键词"]
}

tool.en-us.json（多语言 UI 配置）：

{
  "name": "Free Online My Tool - ATools",
  "shortName": "My Tool",
  "description": "Brief description of what this tool does.",
  "seoDescription": "Detailed SEO-optimized description for search engines and LLM indexing, 200-300 characters...",
  "category": "Tool Category",
  "lang": "en-US",
  "ui": {
    "title": "My Tool",
    "inputLabel": "Input",
    "outputLabel": "Output",
    "processButton": "Process",
    "clearButton": "Clear",
    "inputPlaceholder": "Enter your input here...",
    "outputPlaceholder": "Results will appear here...",
    "errorMessage": "Error: {message}",
    "successMessage": "Processing completed successfully!"
  },
  "keywords": ["free online tool", "web tool", "keyword"]
}

page.tsx：

import { generateToolMetadata } from "../../../lib/generate-tool-page";
import MyToolClient from "./MyToolClient";

export const dynamic = "force-static";
export const metadata = generateToolMetadata("my-tool");

export default function Page() {
  return <MyToolClient />;
}

MyToolClient.tsx：

"use client";

import { useOptionalToolConfig } from "../../../components/ToolConfigProvider";
import ToolPageLayout from "../../../components/ToolPageLayout";

// 中文默认值
const DEFAULT_UI = {
  title: "我的工具",
  inputLabel: "输入",
  outputLabel: "输出",
  processButton: "处理",
  clearButton: "清空",
  inputPlaceholder: "请输入内容...",
  outputPlaceholder: "处理结果会显示在这里...",
  errorMessage: "错误：{message}",
  successMessage: "处理完成！"
} as const;

// 类型安全的文案配置
type MyToolUi = typeof DEFAULT_UI;

export default function MyToolClient() {
  const config = useOptionalToolConfig("my-tool");
  // 配置合并，英文优先，中文回退
  const ui: MyToolUi = {
    ...DEFAULT_UI,
    ...((config?.ui ?? {}) as Partial<MyToolUi>)
  };

  return (
    <ToolPageLayout toolSlug="my-tool">
      <div className="glass-card rounded-3xl p-6 shadow-2xl ring-1 ring-black/5">
        <div className="text-sm font-semibold text-slate-900">{ui.title}</div>

        <div className="mt-4 space-y-4">
          <div>
            <label className="block text-sm font-medium text-slate-700">
              {ui.inputLabel}
            </label>
            <textarea
              placeholder={ui.inputPlaceholder}
              className="mt-2 w-full rounded-2xl border border-slate-200 bg-white px-4 py-3 text-sm outline-none focus:border-blue-400 focus:ring-2 focus:ring-blue-400/30"
            />
          </div>

          <div className="flex gap-2">
            <button className="rounded-2xl bg-blue-600 px-5 py-2.5 text-sm font-semibold text-white transition hover:bg-blue-700">
              {ui.processButton}
            </button>
            <button className="rounded-2xl bg-slate-100 px-5 py-2.5 text-sm font-medium text-slate-800 transition hover:bg-slate-200">
              {ui.clearButton}
            </button>
          </div>

          <div>
            <label className="block text-sm font-medium text-slate-700">
              {ui.outputLabel}
            </label>
            <textarea
              placeholder={ui.outputPlaceholder}
              readOnly
              className="mt-2 w-full rounded-2xl border border-slate-200 bg-slate-50 px-4 py-3 text-sm"
            />
          </div>
        </div>
      </div>
    </ToolPageLayout>
  );
}

• PR 规范：PR 尽量小而专注，每个 PR 专注一个功能或修复
• 纯前端：保持工具纯前端运行（不引入后端依赖）；不上传用户文件。
• 多语言支持：所有工具必须实现完整的多语言支持（基于 tool.en-us.json 的 ui 字段）。
• UI/UX 一致性：优先保持一致的布局与可访问性

• 类型安全：所有 TypeScript 代码必须严格类型检查通过
• 测试验证：确保多语言环境下功能正常工作
• 统一规范：遵循 src/app/tools/<slug>/ 目录约定和统一的代码模式。

更多细节见：

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md

GNU AGPLv3. See LICENSE.