UHolli/ai-website-cloner

# Website Cloner — Next.js Agent 模板 这是一个面向生产环境的模板，旨在帮助 AI 编程代理将现有网站重建为强类型的 Next.js 应用。该模板内置了严格的 TypeScript 工具链、可选的基于 Redis 的会话持久化，以及多平台的 agent 技能，从而确保 `/clone-website` 工作流在不同团队间保持可复现性。 ## 目录 - [为什么选择这个模板](#why-this-template) - [系统架构](#system-architecture) - [克隆工作流](#clone-workflow) - [功能](#features) - [环境要求](#requirements) - [安装](#installation) - [配置](#configuration) - [开发](#development) - [测试](#testing) - [项目结构](#project-structure) - [故障排除](#troubleshooting) - [贡献](#contributing) - [常见问题](#faq) - [许可证](#license) ## 为什么选择这个模板 大多数网站重建项目的失败，往往发生在设计提取与组件实现交接的阶段。本仓库对该边界进行了标准化： | 关注点 | 处理方式 | |---------|----------| | Agent 指令 | 统一集中在 `AGENTS.md` 中，并同步至 10 多个平台 | | 设计还原度 | 包含计算出的 CSS 值的组件规范，位于 `docs/research/` | | 运行时质量 | 严格的 TypeScript、ESLint、Vitest 以及 CI 验证 | | 会话连续性 | 提供可选的 Redis 缓存，用于多步骤克隆流水线 | | 部署 | 独立的 Next.js 输出，并附带 Docker Compose 配置 | ## 系统架构 ``` flowchart TB subgraph agents [AI Coding Agents] CC[Claude Code] CX[Codex / Cursor / Copilot] Others[Gemini / Windsurf / ...] end subgraph template [Template Repository] SKILL["/clone-website skill"] AGENTS[AGENTS.md rules] APP[Next.js App Router] CACHE[Cache layer] API["/api/cache/*"] end subgraph persistence [Optional Persistence] MEM[(In-memory store)] REDIS[(Redis)] end subgraph output [Generated Clone] COMP[React components] ASSETS[public/images + seo] SPECS[docs/research/components] end agents --> SKILL SKILL --> AGENTS AGENTS --> APP APP --> API API --> CACHE CACHE --> MEM CACHE --> REDIS SKILL --> SPECS SPECS --> COMP SKILL --> ASSETS ``` ### 缓存层 ``` sequenceDiagram participant Agent participant API as /api/cache/sessions participant Service as CacheService participant Backend as Memory or Redis Agent->>API: POST session metadata API->>Service: saveCloneSession() Service->>Backend: SET session:{id} Backend-->>Service: OK Service-->>API: session record API-->>Agent: 201 Created Agent->>API: GET ?id=session-1 API->>Service: getCloneSession() Service->>Backend: GET session:{id} Backend-->>Service: JSON payload Service-->>API: CloneSessionRecord API-->>Agent: 200 OK ``` ## 克隆工作流 ``` flowchart LR A[Reconnaissance] --> B[Foundation] B --> C[Component specs] C --> D[Parallel builders] D --> E[Assembly and QA] A --- A1[Screenshots + tokens] B --- B1[Fonts, globals, assets] C --- C1[docs/research/components] D --- D1[Git worktrees per section] E --- E1[Visual diff + merge] ``` 在你的 agent 中运行： ``` /clone-website https://example.com ``` 各阶段定义在 `.claude/skills/clone-website/SKILL.md` 中，并通过 `npm run sync:skills` 传播到其他平台。 ## 功能 - **严格的 TypeScript** — 启用 `noUnusedLocals`，禁用 `allowJs`，并为应用、脚本和测试提供独立配置 - **可选的 Redis 持久化** — 具备重试机制、优雅关闭和强类型配置的连接管理器 - **内存回退机制** — 本地开发无需任何外部服务 - **缓存 HTTP API** — 在 `/api/cache/*` 提供健康探针和克隆会话的 CRUD 操作 - **多平台技能** — 一套技能源码，可生成九个目标平台版本 - **Docker Compose 技术栈** — 包含应用、开发和 Redis 服务，并配置了健康检查 - **CI 流水线** — 每次推送时自动进行 lint、类型检查、测试和构建 ## 环境要求 | 工具 | 版本 | |------|---------| | Node.js | 24+（见 `.nvmrc`） | | npm | 10+ | | Redis | 7+（可选，通过 Docker Compose 运行） | | AI agent | 推荐 Claude Code；详见 `AGENTS.md` | ## 安装 ``` # 从 GitHub template UI 创建你的 repository # 克隆你的副本 git clone https://github.com/YOUR-ORG/YOUR-REPO.git cd YOUR-REPO # 安装依赖项（lockfile 仅限本地） npm install # 复制环境默认值 cp .env.example .env # 启动 dev server npm run dev ``` 打开 [http://localhost:3000](http://localhost:3000)。占位页面会提示你运行 `/clone-website`。 ### Docker ``` # 类 Production container docker compose up app --build # 带 bind mount 的 dev container（默认端口 3001） docker compose up dev --build # 启用 Redis-backed cache REDIS_ENABLED=true docker compose up app redis --build ``` ## 配置 环境变量（见 `.env.example`）： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `LOG_LEVEL` | `info` | 应用日志级别（`debug` … `error`） | | `REDIS_ENABLED` | `false` | 使用 Redis 替代内存缓存 | | `REDIS_URL` | `redis://127.0.0.1:6379` | Redis 连接 URL | | `REDIS_KEY_PREFIX` | `website-cloner:` | 缓存键的命名空间 | | `REDIS_CONNECT_TIMEOUT_MS` | `10000` | 连接超时时间 | | `REDIS_MAX_RETRIES` | `5` | 重连尝试次数 | | `REDIS_DEFAULT_TTL_SECONDS` | `86400` | 默认条目 TTL（24 小时） | | `PORT` | `3000` | 生产环境容器端口映射 | | `DEV_PORT` | `3001` | 开发环境容器端口映射 | ### 缓存 API 示例 ``` # 健康检查 curl http://localhost:3000/api/cache/status # 保存 clone 会话 metadata curl -X POST http://localhost:3000/api/cache/sessions \ -H "Content-Type: application/json" \ -d '{"session":{"id":"demo","targetUrl":"https://example.com","status":"pending","createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}}' # 加载会话 curl "http://localhost:3000/api/cache/sessions?id=demo" ``` ## 开发 | 命令 | 描述 | |---------|-------------| | `npm run dev` | Next.js 开发服务器 | | `npm run build` | 生产环境构建（standalone） | | `npm run start` | 启动生产环境构建 | | `npm run lint` | 对应用、脚本和测试执行 ESLint | | `npm run typecheck` | 对应用、脚本和测试执行 TypeScript 类型检查 | | `npm run test` | Vitest 单元测试 | | `npm run validate` | lint + 类型检查 + 测试 + 构建 | | `npm run sync:skills` | 重新生成各平台的 clone-website 文件 | | `npm run sync:agents` | 重新生成各平台的 agent 规则文件 | ### 同步工作流 | 真值来源 | 生成的目标 | 命令 | |-----------------|-------------------|---------| | `AGENTS.md` | Copilot, Cline, Continue, Amazon Q | `npm run sync:agents` | | `.claude/skills/clone-website/SKILL.md` | Codex, Cursor, Gemini, … | `npm run sync:skills` | 内部审计记录：[`docs/internal/AUDIT.md`](docs/internal/AUDIT.md)。 ## 测试 测试文件位于 `tests/` 目录下，使用 Vitest 运行： ``` npm test # single run npm run test:watch # watch mode ``` 测试覆盖范围包括： - 环境配置解析 - 内存缓存 TTL 及 CRUD 行为 - Redis 存储操作（模拟客户端） - 克隆会话辅助函数 CI 会在 Node 24 环境下为每个拉取请求执行相同的测试套件。 ## 项目结构 ``` . ├── src/ │ ├── app/ # Next.js routes and API handlers │ │ └── api/cache/ # Cache health + session endpoints │ ├── components/ui/ # shadcn/ui primitives │ ├── hooks/ # Shared React hooks (scaffold) │ ├── lib/ │ │ ├── cache/ # Memory + Redis cache backends │ │ ├── config/ # Typed environment configuration │ │ ├── errors/ # Application error types │ │ └── logger/ # Structured logging utility │ └── types/ # Shared TypeScript interfaces ├── tests/cache/ # Vitest unit tests ├── scripts/ # TypeScript build/sync tooling ├── docs/ │ ├── internal/ # Engineering audit notes │ └── research/ # Agent extraction output (generated) ├── .claude/skills/ # Canonical clone-website skill ├── docker-compose.yml # app + dev + redis services ├── vitest.config.ts ├── tsconfig.json # App compiler config ├── tsconfig.scripts.json # Scripts compiler config └── tsconfig.test.json # Test compiler config ``` **设计决策** - `src/lib/cache/` 将持久化逻辑与 API 路由隔离，以便 agent 能在脚本中复用缓存逻辑。 - `tests/` 位于顶层（非同级目录），以保持生产环境包的精简。 - 锁文件被有意设置为了 gitignore 忽略项；CI 使用 `npm install`。 ## 故障排除 | 症状 | 可能原因 | 解决方法 | |---------|--------------|-----| | `Redis is disabled` API 错误 | `REDIS_ENABLED=false` | 设置 `REDIS_ENABLED=true` 并启动 Redis | | 缓存 ping 返回 503 | Redis 无法连接 | 检查 `REDIS_URL`，运行 `docker compose up redis` | | `Session-store bridge not found`（旧版文档） | 说明文档已过时 | 改用 `/api/cache/status` | | 脚本类型检查失败 | 工作目录错误 | 请在仓库根目录下运行命令 | | ESLint 忽略了测试 | 配置已过期 | 确保 `eslint .` 包含了 `tests/` | | Docker 健康检查失败 | 应用仍在编译中 | 增加 compose 文件中的 `start_period` 时间 | | Agent 找不到技能文件 | 平台副本已过期 | 运行 `npm run sync:skills` | ## 常见问题 **我必须使用 Redis 吗？** 不需要。默认的内存后端即可满足单机 agent 运行的需求。当多个 agent 或 CI 运行器需要共享克隆会话状态时，请启用 Redis。 **没有 Claude Code 可以使用吗？** 可以。在编辑规范技能文件后，运行 `npm run sync:skills`。大多数 agent 会自动读取 `AGENTS.md` 或其特定平台的副本。 **它能自动复制任何网站吗？** 不能。该模板仅提供基础脚手架和 agent 指令。提取、规范编写和组件生成工作仍需由编程 agent 完成。 **抓取网页总是合法的吗？** 不是。在克隆之前，请验证所有权、授权许可以及目标站点的服务条款。请参阅 `AGENTS.md` 中的道德使用章节。 **为什么 `package-lock.json` 被忽略了？** 该模板旨在优化分支级别的依赖项解析。请在本地通过 `npm install` 生成该锁文件。 ## 许可证 MIT — 详见 [许可证](LICENSE)。

标签：搜索引擎查询, 自动化攻击, 请求拦截