howone 0.1.52 → 0.2.0

package/bin/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
-import { readdir, rename, stat, writeFile } from "node:fs/promises";
+import { readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -62,6 +62,18 @@ async function main() {
 		await runDeploy(command.options);
 		return;
 	}
+	if (scope === "capabilities" || scope === "capability" || scope === "caps") {
+		await runCapabilitiesCommand(subcommand, rest, command.options);
+		return;
+	}
+	if (scope === "skills" || scope === "skill") {
+		await runSkillsCommand(subcommand, rest, command.options);
+		return;
+	}
+	if (scope === "run") {
+		await runCapabilityRun(compact([subcommand, ...rest]), command.options);
+		return;
+	}
 	if (scope === "ai" && subcommand === "run") {
 		await runAiRun(rest, command.options);
 		return;
@@ -87,9 +99,22 @@ function parseCommand(args) {
 			"next",
 			"force",
 			"yes",
-			"json"
+			"json",
+			"stream"
 		],
-		string: ["template", "cwd"],
+		string: [
+			"template",
+			"cwd",
+			"scope",
+			"input",
+			"output",
+			"prompt",
+			"api-url",
+			"token",
+			"status",
+			"reason"
+		],
+		number: ["limit"],
 		configuration: { "camel-case-expansion": false }
 	});
 	return {
@@ -103,6 +128,16 @@ function parseCommand(args) {
 			yes: Boolean(parsed.yes),
 			json: Boolean(parsed.json),
 			cwd: typeof parsed.cwd === "string" ? parsed.cwd : void 0,
+			scope: typeof parsed.scope === "string" ? parsed.scope : void 0,
+			input: typeof parsed.input === "string" ? parsed.input : void 0,
+			output: typeof parsed.output === "string" ? parsed.output : void 0,
+			prompt: typeof parsed.prompt === "string" ? parsed.prompt : void 0,
+			apiUrl: typeof parsed["api-url"] === "string" ? parsed["api-url"] : void 0,
+			token: typeof parsed.token === "string" ? parsed.token : void 0,
+			stream: Boolean(parsed.stream),
+			status: typeof parsed.status === "string" ? parsed.status : void 0,
+			limit: typeof parsed.limit === "number" && Number.isFinite(parsed.limit) ? parsed.limit : void 0,
+			reason: typeof parsed.reason === "string" ? parsed.reason : void 0,
 			help: Boolean(parsed.help) || hasHelp,
 			version: Boolean(parsed.version) || hasVersion
 		}
@@ -182,6 +217,244 @@ async function runAiRun(pathArgs, options) {
 	}
 	printPending("howone ai run", result.message ?? "AI run is not implemented yet.");
 }
+async function runCapabilitiesCommand(subcommand, pathArgs, options) {
+	if (!subcommand || subcommand === "search") {
+		const query = pathArgs.join(" ").trim();
+		if (!query) throw new CliError("E_QUERY_REQUIRED", "Search query is required.");
+		await runCapabilitySearch(query, options);
+		return;
+	}
+	if (subcommand === "list") {
+		await runCapabilityList(options);
+		return;
+	}
+	if (subcommand === "inspect" || subcommand === "show") {
+		const ref = pathArgs[0];
+		if (!ref) throw new CliError("E_CAPABILITY_REF_REQUIRED", "Capability reference is required.");
+		await runCapabilityInspect(ref, options);
+		return;
+	}
+	if (subcommand === "proposals") {
+		await runCapabilityProposals(options);
+		return;
+	}
+	if (subcommand === "apply") {
+		const proposalId = pathArgs[0];
+		if (!proposalId) throw new CliError("E_PROPOSAL_ID_REQUIRED", "Capability proposal id is required.");
+		await runCapabilityProposalAction("apply", proposalId, options);
+		return;
+	}
+	if (subcommand === "reject") {
+		const proposalId = pathArgs[0];
+		if (!proposalId) throw new CliError("E_PROPOSAL_ID_REQUIRED", "Capability proposal id is required.");
+		await runCapabilityProposalAction("reject", proposalId, options);
+		return;
+	}
+	throw new CliError("E_COMMAND_UNKNOWN", `Unknown capabilities command: ${["capabilities", subcommand].join(" ")}`);
+}
+async function runSkillsCommand(subcommand, pathArgs, options) {
+	const ref = pathArgs[0];
+	if (subcommand === "export") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("export", ref, options);
+		return;
+	}
+	if (subcommand === "install") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("install", ref, options);
+		return;
+	}
+	if (subcommand === "publish") {
+		if (!ref) throw new CliError("E_SKILL_REF_REQUIRED", "Skill reference is required.");
+		await runSkillProjection("publish", ref, options);
+		return;
+	}
+	throw new CliError("E_COMMAND_UNKNOWN", `Unknown skills command: ${["skills", subcommand].filter(Boolean).join(" ")}`);
+}
+async function runCapabilitySearch(query, options) {
+	const params = new URLSearchParams({ q: query });
+	if (options.scope) params.set("scope", options.scope);
+	await printRegistryResult("capabilities search", await callHowoneRegistryApi(`/api/capabilities/search?${params}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	}), options);
+}
+async function runCapabilityList(options) {
+	const params = new URLSearchParams();
+	if (options.scope) params.set("scope", options.scope);
+	await printRegistryResult("capabilities list", await callHowoneRegistryApi(`/api/capabilities${params.size ? `?${params}` : ""}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	}), options);
+}
+async function runCapabilityInspect(ref, options) {
+	const result = await callHowoneRegistryApi(`/api/capabilities/${encodeURIComponent(ref)}`, {
+		options,
+		requireAuth: options.scope !== "public"
+	});
+	await printRegistryResult(`capabilities inspect ${ref}`, result, options);
+}
+async function runCapabilityProposals(options) {
+	const params = new URLSearchParams();
+	if (options.status) params.set("status", options.status);
+	if (options.limit) params.set("limit", String(options.limit));
+	await printRegistryResult("capabilities proposals", await callHowoneRegistryApi(`/api/capabilities/proposals${params.size ? `?${params}` : ""}`, {
+		options,
+		requireAuth: true
+	}), options);
+}
+async function runCapabilityProposalAction(action, proposalId, options) {
+	const result = await callHowoneRegistryApi(`/api/capabilities/proposals/${encodeURIComponent(proposalId)}/${action}`, {
+		options,
+		requireAuth: true,
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(action === "reject" ? { reason: options.reason } : {})
+		}
+	});
+	await printRegistryResult(`capabilities ${action} ${proposalId}`, result, options);
+}
+async function runCapabilityRun(pathArgs, options) {
+	const actionRef = pathArgs[0];
+	if (!actionRef && !options.prompt) throw new CliError("E_ACTION_REF_REQUIRED", "Capability action reference is required, or use --prompt for query-based routing.");
+	const input = await readCapabilityRunInput(options);
+	const body = {
+		...actionRef ? { actionRef } : {},
+		...options.prompt ? { prompt: options.prompt } : {},
+		input,
+		stream: Boolean(options.stream)
+	};
+	const result = await callHowoneRegistryApi("/api/capabilities/run", {
+		options,
+		requireAuth: true,
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+	await printRegistryResult(actionRef ? `run ${actionRef}` : "run query", result, options);
+}
+async function runSkillProjection(action, ref, options) {
+	const method = action === "export" ? "GET" : "POST";
+	const result = await callHowoneRegistryApi(`/api/capabilities/skills/${encodeURIComponent(ref)}/${action}`, {
+		options,
+		requireAuth: action !== "export",
+		init: { method }
+	});
+	await printRegistryResult(`skills ${action} ${ref}`, result, options);
+}
+async function readCapabilityRunInput(options) {
+	if (!options.input) return {};
+	const raw = options.input.trim();
+	const content = raw.startsWith("{") || raw.startsWith("[") ? raw : await readFile(path.resolve(options.cwd ?? process.cwd(), raw), "utf-8");
+	try {
+		const parsed = JSON.parse(content);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError("E_INPUT_INVALID", "Capability input must be a JSON object.");
+		return parsed;
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		throw new CliError("E_INPUT_INVALID", error instanceof Error ? error.message : "Invalid JSON input.");
+	}
+}
+function resolveHowoneApiUrl(options) {
+	return (options.apiUrl ?? process.env.HOWONE_API_URL ?? process.env.NEXT_PUBLIC_SERVER_URL ?? "https://howone.dev").replace(/\/+$/, "");
+}
+function resolveHowoneApiToken(options) {
+	return options.token ?? process.env.HOWONE_API_TOKEN ?? process.env.HOWONE_AGENT_TOKEN;
+}
+async function callHowoneRegistryApi(apiPath, args) {
+	const token = resolveHowoneApiToken(args.options);
+	if (args.requireAuth && !token) throw new CliError("E_AUTH_REQUIRED", "Set HOWONE_API_TOKEN or pass --token to access private/workspace capabilities.");
+	const url = `${resolveHowoneApiUrl(args.options)}${apiPath.startsWith("/") ? apiPath : `/${apiPath}`}`;
+	const headers = new Headers(args.init?.headers);
+	if (token) headers.set("Authorization", `Bearer ${token}`);
+	headers.set("Accept", args.options.stream ? "text/event-stream, application/json" : "application/json");
+	const response = await fetch(url, {
+		...args.init,
+		headers
+	});
+	const contentType = response.headers.get("content-type") ?? "";
+	if (args.options.stream && contentType.includes("text/event-stream")) return readSseResponse(response);
+	const text = await response.text();
+	const body = text ? parseJsonOrText(text) : null;
+	if (!response.ok) throw new CliError("E_API_REQUEST_FAILED", `HowOne API request failed: HTTP ${response.status}`, {
+		status: response.status,
+		body
+	});
+	return body;
+}
+async function readSseResponse(response) {
+	if (!response.ok) throw new CliError("E_API_REQUEST_FAILED", `HowOne API request failed: HTTP ${response.status}`);
+	if (!response.body) return {
+		ok: true,
+		events: []
+	};
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const events = [];
+	let buffer = "";
+	while (true) {
+		const { value, done } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let boundary = buffer.indexOf("\n\n");
+		while (boundary >= 0) {
+			const chunk = buffer.slice(0, boundary).trim();
+			buffer = buffer.slice(boundary + 2);
+			if (chunk) {
+				events.push(chunk);
+				console.log(chunk);
+			}
+			boundary = buffer.indexOf("\n\n");
+		}
+	}
+	const tail = buffer.trim();
+	if (tail) {
+		events.push(tail);
+		console.log(tail);
+	}
+	return {
+		ok: true,
+		events
+	};
+}
+function parseJsonOrText(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+async function printRegistryResult(command, result, options) {
+	if (options.output) await writeFile(path.resolve(options.cwd ?? process.cwd(), options.output), `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+	if (options.json || options.output) {
+		if (!options.output) console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	console.log(formatPanel(pc.bold(command), [formatRegistrySummary(result)]));
+}
+function formatRegistrySummary(result) {
+	if (typeof result === "string") return result;
+	if (!result || typeof result !== "object") return String(result);
+	const record = result;
+	const data = record.data ?? record.results ?? record.capabilities ?? record.actions;
+	if (Array.isArray(data)) {
+		if (!data.length) return "No capabilities found.";
+		return data.slice(0, 12).map((item) => {
+			if (!item || typeof item !== "object") return `- ${String(item)}`;
+			const row = item;
+			const name = row.name ?? row.title ?? row.slug ?? row.actionRef ?? row.proposalSlug ?? row.id ?? "capability";
+			const description = row.description ?? row.summary ?? row.reason ?? row.status;
+			return `- ${String(name)}${description ? `: ${String(description)}` : ""}`;
+		}).join("\n");
+	}
+	const name = record.name ?? record.title ?? record.slug ?? record.actionRef ?? record.proposalSlug ?? record.id;
+	const description = record.description ?? record.summary ?? record.reason ?? record.status;
+	if (name || description) return [name ? String(name) : void 0, description ? String(description) : void 0].filter(Boolean).join("\n");
+	return JSON.stringify(result, null, 2);
+}
 async function resolveCreatePlan(pathArgs, options, cwd, isInteractive) {
 	const template = resolveTemplateOption(options);
 	const projectName = pathArgs[0] === "template" ? pathArgs[1] : pathArgs[0];
@@ -417,6 +690,18 @@ function printHelp(pathArgs) {
 		printReservedHelp("howone deploy", "Deploy support is reserved and not implemented yet.");
 		return;
 	}
+	if (topic === "capabilities" || topic === "capabilities search") {
+		printCapabilitiesHelp();
+		return;
+	}
+	if (topic === "skills") {
+		printSkillsHelp();
+		return;
+	}
+	if (topic === "run") {
+		printRunHelp();
+		return;
+	}
 	if (topic === "ai" || topic === "ai run") {
 		printReservedHelp("howone ai run [aiId]", "AI run support is reserved and not implemented yet.");
 		return;
@@ -429,6 +714,11 @@ function printRootHelp() {
 		"",
 		pc.bold("Commands"),
 		formatCommand("init app [name]", "Create an app from a template"),
+		formatCommand("capabilities search <query>", "Search callable HowOne capabilities"),
+		formatCommand("capabilities inspect <ref>", "Inspect a capability package or action"),
+		formatCommand("capabilities proposals", "List generated capability proposals"),
+		formatCommand("run <package.action>", "Run a callable capability action"),
+		formatCommand("skills export <ref>", "Export a skill projection for a capability"),
 		formatCommand("create", "Reserved placeholder"),
 		formatCommand("deploy", "Reserved placeholder"),
 		formatCommand("ai run [aiId]", "Reserved placeholder"),
@@ -439,8 +729,10 @@ function printRootHelp() {
 		"",
 		pc.bold("Examples"),
 		`  ${pc.cyan("howone init app my-app --template vite")}`,
-		`  ${pc.cyan("howone deploy")}`,
-		`  ${pc.cyan("howone ai run generateImage")}`
+		`  ${pc.cyan("howone capabilities search \"海报生成\" --scope public")}`,
+		`  ${pc.cyan("howone capabilities proposals --status pending_review")}`,
+		`  ${pc.cyan("howone run poster-generator.createPoster --input input.json --output result.json")}`,
+		`  ${pc.cyan("howone run --prompt \"帮我生成一张 AI 发布会海报\" --stream")}`
 	]));
 }
 function printInitHelp() {
@@ -469,6 +761,71 @@ function printReservedHelp(command, description) {
 		`${pc.yellow("Pending")} This command is available as a stable placeholder.`
 	]));
 }
+function printCapabilitiesHelp() {
+	console.log(formatPanel(`${pc.bold("HowOne capabilities")}`, [
+		`${pc.dim("Usage")}    howone capabilities <command> [options]`,
+		"",
+		pc.bold("Commands"),
+		formatCommand("search <query>", "Search private, workspace, installed, or public capabilities"),
+		formatCommand("list", "List capabilities in a scope"),
+		formatCommand("inspect <ref>", "Inspect package/action schemas and runtime bindings"),
+		formatCommand("proposals", "List generated proposals for the current user"),
+		formatCommand("apply <proposalId>", "Apply a generated proposal to the registry"),
+		formatCommand("reject <proposalId>", "Reject a generated proposal"),
+		"",
+		pc.bold("Options"),
+		formatCommand("--scope <scope>", "private, workspace, installed, public, or global"),
+		formatCommand("--status <status>", "Filter proposal list by status"),
+		formatCommand("--limit <number>", "Limit result count"),
+		formatCommand("--reason <text>", "Reason for rejecting a proposal"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone capabilities search \"海报生成\" --scope public")}`,
+		`  ${pc.cyan("howone capabilities inspect poster-generator.createPoster")}`,
+		`  ${pc.cyan("howone capabilities proposals --status pending_review")}`,
+		`  ${pc.cyan("howone capabilities apply 00000000-0000-0000-0000-000000000000")}`
+	]));
+}
+function printRunHelp() {
+	console.log(formatPanel(`${pc.bold("Run a capability")}`, [
+		`${pc.dim("Usage")}    howone run <package.action> [options]`,
+		"",
+		pc.bold("Options"),
+		formatCommand("--input <json|file>", "JSON object or path to JSON input file"),
+		formatCommand("--prompt <text>", "Natural-language query routed through the registry"),
+		formatCommand("--output <file>", "Write JSON result to a file"),
+		formatCommand("--stream", "Request SSE and print events as they arrive"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone run poster-generator.createPoster --input input.json")}`,
+		`  ${pc.cyan("howone run --prompt \"帮我生成一张 AI 发布会海报\" --stream")}`
+	]));
+}
+function printSkillsHelp() {
+	console.log(formatPanel(`${pc.bold("HowOne skill projections")}`, [
+		`${pc.dim("Usage")}    howone skills <command> <ref> [options]`,
+		"",
+		pc.bold("Commands"),
+		formatCommand("export <ref>", "Export an agent-facing skill artifact"),
+		formatCommand("install <ref>", "Install a public or workspace skill projection"),
+		formatCommand("publish <ref>", "Request publication of a capability skill projection"),
+		"",
+		pc.bold("Options"),
+		formatCommand("--api-url <url>", "HowOne registry API origin"),
+		formatCommand("--token <token>", "Agent API token; defaults to HOWONE_API_TOKEN"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone skills export poster-generator")}`,
+		`  ${pc.cyan("howone skills install poster-generator")}`
+	]));
+}
 function printPending(command, message) {
 	console.log(formatPanel(pc.bold(command), [`${pc.yellow("Pending")} ${message}`]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.52",
+  "version": "0.2.0",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/web-clone/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jane (@xiaoerzhan / 小耳)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/vite/.howone/skills/web-clone/README.md

@@ -0,0 +1,179 @@
+# 🪞 Web Clone · 网站复刻方法论
+
+> Reproduce any website — from a single-file static page to a WebGL-heavy interactive demo — without faking it from AI hallucinations.
+> 把任何一个网站(从单文件静态页到 WebGL 重前端 demo)忠实复刻出来 —— 不靠 AI 臆测代码硬抄。
+
+**English** · [中文](#中文)
+
+---
+
+## What this skill does
+
+You see a website you love. You want to clone it — to learn how it works, to remix it into your own thing, or to run it offline. AI tools love to produce *plausible-looking* "clone analysis" documents full of code blocks that are entirely fabricated and break the moment you run them.
+
+This skill is a **methodology plus executable probes that put real source first**, with a 6-step decision tree covering:
+
+- Static HTML/CSS sites → `wget --mirror`
+- React / Vue / Next content sites → rebuild on a template
+- Multi-page sites → crawl internal routes before designing templates
+- Interactive sites → record hover / click / scroll / canvas-drag states before cloning
+- **WebGL / Canvas / Three.js heavy frontends** → reverse-engineer real source, line by line; when there's no findable source, runtime frame-capture + a **baseline-first replay gate** with `SOURCE / PARTIAL / GUESS` evidence grading
+- **Static-built sites (Astro / Vite SSG / Hugo), even WebGL-heavy** → `mirror-site.mjs` full-scroll-captures and mirrors every deployed asset (incl. runtime-fetched `.sog/.buf/.wasm`) for a true 1:1 clone — for a static site, "get the real source" = "mirror the whole deployed bundle"
+- Verify in a real browser, document the truth, replace content with yours
+- **Visual / rebrand modes** → distill a versionable `design-dna.json` (design tokens + style + effects), then "keep the DNA, swap the content"
+
+## Iron rule: real source first, never copy AI-guessed code
+
+> Any AI-written "clone analysis" — treat the conceptual skeleton as a hint, but **assume every executable code block is hallucinated** until you've verified it against real source code line by line.
+
+**Case in point** (see `references/marbles-case.md`): A real WebGL marbles demo uses **analytic ray-sphere intersection** + an SVG `feDisplacementMap` to refract the live DOM. An AI analysis confidently described it as **ray-marching + SDF + sampling the DOM as a texture** — two entirely different implementations. Copying the AI version produces nothing like the original and runs many times slower.
+
+So **step 1 is always: get the real source**.
+
+## What's in here
+
+```
+claude-skill-web-clone/
+├── SKILL.md                       ← The methodology (loaded by Claude Code / Codex / Cursor)
+├── README.md
+├── LICENSE                         ← MIT
+├── follow-wechat-qrcode.jpg
+└── references/
+    ├── reverse-engineering.md     ← How to dissect a WebGL/Canvas frontend, line by line
+    ├── effect-extraction.md       ← Evidence grading + baseline-first gate for extracting effects
+    ├── static-mirror.md           ← 1:1 clone of static-built sites (Astro/Vite SSG/Hugo) via full asset mirror
+    ├── design-dna.md              ← Structured design-identity layer (visual / rebrand modes)
+    ├── marbles-case.md            ← Flagship case: real architecture vs AI hallucination
+    └── deliverables.md            ← NOTES.md / TEARDOWN.md / RECON/ templates
+└── scripts/
+    ├── recon-site.mjs             ← Browser screenshots + DOM/framework/resource signals
+    ├── mirror-site.mjs            ← Full-scroll capture + mirror every same-origin asset (static-site 1:1 clone)
+    ├── route-crawl.mjs            ← Same-site route map + screenshot per route
+    ├── interaction-probe.mjs      ← Scroll/hover/click/canvas-drag state evidence
+    ├── network-capture.mjs        ← XHR/fetch capture for SPA fixtures
+    ├── asset-harvest.mjs          ← Download discovered source assets
+    ├── dna-scaffold.mjs           ← Build a design-dna.json skeleton, prefilled from recon
+    └── visual-diff.mjs            ← Pixel comparison for original vs clone screenshots
+```
+
+## Install
+
+This is a [Claude Code skill](https://docs.claude.com/en/docs/agents-and-tools/skills). Drop it into your skills directory:
+
+```bash
+git clone https://github.com/Jane-xiaoer/claude-skill-web-clone.git ~/.claude/skills/web-clone
+```
+
+Then use it by saying things like:
+- "复刻这个网站: https://..."
+- "Clone this site for me"
+- "Reverse-engineer this WebGL demo"
+- "把这个站抄下来改成我的"
+
+Claude / Codex will load `SKILL.md` and walk the decision tree.
+
+## The decision tree (one-screen summary)
+
+| Step | What to do |
+|---|---|
+| **1** | `gh api search/repositories?q=<name>` — find the real source on GitHub FIRST |
+| **2** | If no source: browser-probe the site, crawl routes, capture network, and probe interactions |
+| **3** | Pick the path: `wget` mirror / template rebuild / **WebGL reverse-engineering** / theme market |
+| **4** | Set up `~/projects/website-clones/<name>-clone/` (or your equivalent), keep `index-original.html` read-only |
+| **5** | Strip tracking, write `NOTES.md` + `TEARDOWN.md`, verify in a real browser with screenshots |
+| **6** | Replace text / media / brand colors with yours |
+
+## License & attribution discipline
+
+Before deploying anything publicly, **check the source repo's license**:
+
+| License | What you can do |
+|---|---|
+| MIT / Apache / BSD / Unlicense | Modify, redeploy, just keep credits |
+| **NONE / unstated** | Default = **All Rights Reserved**. Local learning only, must credit, **do not redeploy publicly without permission** |
+| Proprietary / explicitly forbidden | Read-only learning, no copying, no deployment |
+
+⚠️ "Code is on GitHub" ≠ "code is MIT". Many viral demos have no LICENSE file and default to All Rights Reserved.
+
+## Flagship case
+
+`marbles-case.md` documents the full reverse-engineering of [chiuhans111/marbles](https://github.com/chiuhans111/marbles) — a 1067-line single-file WebGL + SVG-filter glass marbles interactive demo — and contrasts the real architecture with an AI-generated clone analysis that got the core mechanism completely backwards. This is the canonical example of why you must verify against real source.
+
+---
+
+## 中文
+
+### 这个 skill 是干什么的
+
+你看到一个喜欢的网站,想复刻 —— 学它怎么做、改成你自己的版本、或者离线跑起来。AI 工具最爱产出**看起来煞有其事**的"复刻分析文档",里面的代码块几乎全是臆造的,照抄必崩。
+
+这个 skill 把"真源码至上"做成可重复的流程,**6 步决策树**覆盖三大分支:
+- 静态 HTML/CSS 站 → `wget --mirror`
+- React / Vue / Next 内容站 → 重建模板灌内容
+- **WebGL / Canvas / Three.js 重前端** → 逆向真源码,逐行核对;找不到源码时用运行时帧捕获 + **baseline-first 复现闸门** + `SOURCE/PARTIAL/GUESS` 证据分级
+- **静态构建站(Astro/Vite SSG/Hugo),哪怕重 WebGL** → `mirror-site.mjs` 全程滚动捕获 + 镜像每一个部署资产(含运行时 fetch 的 `.sog/.buf/.wasm`),做真 1:1 忠实复刻——对静态站,"拿到真源码"="镜像部署资产整套"(范例:Lusion oryzo.ai,高斯泼溅,hero 像素 diff 5/5)
+- **视觉复刻 / 内容爆改模式** → 把"那个站的感觉"蒸馏成可版本化的 `design-dna.json`(设计 token + 风格 + 特效),然后"DNA 留着、内容换掉"
+- 浏览器真验证,如实记录,最后替换成你自己的内容
+
+### 头号铁律:真源码至上,绝不抄 AI 臆造代码
+
+> 任何 AI 写的"复刻分析",**概念骨架可以参考,但里面的可执行代码块默认全是臆造的**,必须用真源码核对,否则照抄必崩。
+
+**实证案例**:一份 AI 分析文档把原站"解析法求光线-球体交点 + 把光学结果编码成位移图 + 交给 SVG `feDisplacementMap` 扭曲真实 DOM"的真架构,臆造成了"ray-marching + SDF + 把 DOM 当纹理采样"—— 两套完全不同的实现,照抄做不出原效果且慢 N 倍。详见 `references/marbles-case.md`。
+
+### 安装
+
+这是一个 [Claude Code skill](https://docs.claude.com/en/docs/agents-and-tools/skills)。clone 到你的 skills 目录:
+
+```bash
+git clone https://github.com/Jane-xiaoer/claude-skill-web-clone.git ~/.claude/skills/web-clone
+```
+
+然后跟 Claude / Codex / Cursor 说:
+- 「复刻这个网站: https://...」
+- 「把这个站抄下来改成我的」
+- 「逆向拆解这个 WebGL demo」
+
+AI 会自动加载 `SKILL.md` 走决策树。
+
+### 旗舰范例
+
+`references/marbles-case.md` 拆解了 [chiuhans111/marbles](https://github.com/chiuhans111/marbles) —— 1067 行单文件 WebGL + SVG filter 玻璃弹珠站,真架构对比 AI 分析文档的错误,是"为什么必须真源码核对"的标准教材。
+
+---
+
+## 致谢 / Credits
+
+- **方法论沉淀来源 / Origin**:Jane 的克隆中枢 `~/projects/website-clones/` 工作流(2026-05-27 marbles 案例跑通后抽出 skill)
+- **旗舰范例原作 / Flagship case author**:[chiuhans111/marbles](https://github.com/chiuhans111/marbles) by Hans Chiu — 没有这份单文件 1067 行的玻璃弹珠源码就没有这个 skill 的"真源码至上"铁律
+- **设计身份层 schema / Design-DNA schema**:`references/design-dna.md` 的三维 DNA JSON 改编自 [zanwei/design-dna](https://github.com/zanwei/design-dna)（MIT），用于"视觉复刻 / 内容爆改"模式
+- **特效提取纪律 / Effect-extraction discipline**:`references/effect-extraction.md` 的证据分级 + baseline-first 闸门受 [lixiaolin94/skills · web-shader-extractor](https://github.com/lixiaolin94/skills) 启发（该仓库无 LICENSE，本 skill 只借方法概念、用自己的话重写，未复制其代码或原文）
+- **迭代打磨 / Iteration**:Jane(`@xiaoerzhan`) + Claude Code(多轮 reverse-engineering)
+
+---
+
+## License
+
+MIT. Use it freely, remix it, ship it. Attribution welcome but not required.
+
+如果这个 skill 让你免于在 AI 臆造代码上浪费一个下午,欢迎 ⭐ 这个仓库。
+If this skill saves you a frustrating afternoon of debugging fake AI code, ⭐ the repo.
+
+---
+
+## 📱 关注作者 / Follow Me
+
+如果这个仓库对你有帮助,欢迎关注我。后面我会持续更新更多 AI Skill、设计方法、网站美学和创意工作流。
+
+If this repo helped you, follow me for more AI skills, design systems, web aesthetics, and creative workflows.
+
+- X (Twitter): [@xiaoerzhan](https://x.com/xiaoerzhan)
+- 微信公众号 / WeChat Official Account: 扫码关注 / Scan to follow
+
+<p align="center">
+  <img src="./follow-wechat-qrcode.jpg" alt="Jane WeChat Official Account QR code" width="300" />
+</p>
+
+<p align="center"><strong>中文:</strong>欢迎关注我的公众号,一起研究 AI Skill、设计原则、网站表达和创意工作流。</p>
+
+<p align="center"><strong>English:</strong> Follow my WeChat Official Account for more AI skills, design principles, web aesthetics, and creative workflows.</p>