ai-friendly-check 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 落地派 (https://www.geofde.cn)
+
+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/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# ai-friendly-check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+检查一个网页对 **AI 搜索引擎**（DeepSeek、豆包、元宝、ChatGPT 等）的友好度。
+
+8 项指标，40 分制，一行命令出报告。
+
+> 由 [落地派](https://www.geofde.cn) 维护 · 企业搞 AI，就找落地派
+
+## 快速开始
+
+```bash
+npx ai-friendly-check https://example.com
+```
+
+输出示例：
+
+```
+AI 友好度检测  https://example.com
+
+  ████████████████░░░░  32/40  良好
+
+  ✓ 页面标题   长度 24 字：企业官网建设与 AI 搜索优化
+  ✓ 页面描述   长度 86 字
+  ✓ H1 结构    检测到 1 个 H1
+  ✓ 结构化数据 检测到 JSON-LD
+  ✗ 问答结构   未检测到问答内容
+  ✓ 语义化标签 检测到：main, nav, header
+  ✓ 正文信息量 正文约 1200 字
+  ✗ 可索引性   可索引，但缺少 canonical
+
+  先改这两项
+  1. 问答结构：把客户最常问的 5–10 个问题做成「问题 + 简明回答」，并加 FAQPage 标记。
+  2. 可索引性：移除 noindex，并声明 canonical 指向规范地址，避免同一内容多个 URL 分散权重。
+
+  完整 40 分自测（含改进清单）：https://www.geofde.cn/tools
+```
+
+## 8 项指标
+
+| # | 指标 | 检查内容 | 分值 |
+| --- | --- | --- | --- |
+| 1 | 页面标题 | `<title>` 长度 8–60 字 | 5 |
+| 2 | 页面描述 | `meta description` 长度 40–160 字 | 5 |
+| 3 | H1 结构 | 恰好一个 `<h1>` | 5 |
+| 4 | 结构化数据 | 存在 JSON-LD | 5 |
+| 5 | 问答结构 | FAQPage 标记或问答式标题 | 5 |
+| 6 | 语义化标签 | main/article/nav/header 等 ≥ 2 种 | 5 |
+| 7 | 正文信息量 | 有效正文 ≥ 500 字 | 5 |
+| 8 | 可索引性 | 无 noindex 且声明 canonical | 5 |
+
+## 作为库使用
+
+```js
+const { audit } = require('ai-friendly-check');
+
+const result = audit('<html>...</html>', 'https://example.com');
+console.log(result.score);      // 0–40
+console.log(result.grade);      // 优秀 / 良好 / 及格 / 待改进
+console.log(result.checks);     // 每项检测详情
+console.log(result.suggestions);// 优先改进建议（最多 2 条）
+```
+
+也支持 CLI 输出 JSON，便于接入 CI 或批量检测：
+
+```bash
+npx ai-friendly-check https://example.com --json
+```
+
+## 为什么做这个
+
+客户已经开始在 AI 里找供应商了。如果 AI 回答「XX 找哪家好」时从没提到你，生意就在悄悄流走。
+
+让 AI 愿意推荐你，第一步是让它**读得懂你的网站**：有结构、有出处、有明确的问答。`ai-friendly-check` 把这套检查做成了一行命令。
+
+想系统做这件事（内容建设、实体标注、按月效果对比），可以看看落地派的做法：
+**[https://www.geofde.cn](https://www.geofde.cn)** · 免费自测：[https://www.geofde.cn/tools](https://www.geofde.cn/tools)
+
+## License
+
+[MIT](LICENSE) © 2026 落地派

package/bin/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict';
+
+const { audit } = require('../index');
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+function help() {
+  console.log(`
+${C.bold}ai-friendly-check${C.reset} — 检查网页对 AI 搜索引擎的友好度
+
+${C.bold}用法${C.reset}
+  npx ai-friendly-check <url>            检查一个网页
+  npx ai-friendly-check <url> --json     输出 JSON（便于接入自动化）
+  npx ai-friendly-check <url> --no-color 关闭颜色
+
+${C.bold}示例${C.reset}
+  npx ai-friendly-check https://www.geofde.cn
+
+${C.dim}8 项指标，40 分制 · 官网 https://www.geofde.cn/tools${C.reset}
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (!args.length || args.includes('-h') || args.includes('--help')) {
+    help();
+    return;
+  }
+
+  const json = args.includes('--json');
+  const noColor = args.includes('--no-color') || !process.stdout.isTTY;
+  const color = (code, text) => (noColor ? text : `${code}${text}${C.reset}`);
+
+  const url = args.find((a) => !a.startsWith('-'));
+  if (!url) {
+    console.error('缺少网址参数。运行 npx ai-friendly-check --help 查看用法。');
+    process.exitCode = 1;
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(url);
+    if (!/^https?:$/.test(parsed.protocol)) throw new Error('only http/https');
+  } catch {
+    console.error(`网址格式不对：${url}（需要以 http:// 或 https:// 开头）`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 20000);
+
+  let res;
+  try {
+    res = await fetch(parsed.toString(), {
+      redirect: 'follow',
+      signal: controller.signal,
+      headers: {
+        'user-agent': 'ai-friendly-check/1.0 (+https://www.geofde.cn)',
+        accept: 'text/html,application/xhtml+xml',
+      },
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    console.error(`抓取失败：${err.name === 'AbortError' ? '请求超时（20 秒）' : err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  clearTimeout(timer);
+
+  if (!res.ok) {
+    console.error(`抓取失败：HTTP ${res.status} ${res.statusText}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const html = await res.text();
+  const result = audit(html, res.url || parsed.toString());
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const barLen = 20;
+  const filled = Math.round((result.score / result.maxScore) * barLen);
+  const bar = '█'.repeat(filled) + '░'.repeat(barLen - filled);
+  const scoreColor = result.score >= 28 ? C.green : result.score >= 20 ? C.yellow : C.red;
+
+  console.log('');
+  console.log(`${C.bold}AI 友好度检测${C.reset}  ${C.dim}${result.url}${C.reset}`);
+  console.log('');
+  console.log(`  ${color(scoreColor, bar)}  ${color(scoreColor, `${result.score}/${result.maxScore}`)}  ${result.grade}`);
+  console.log('');
+  for (const c of result.checks) {
+    const mark = c.passed ? color(C.green, '✓') : color(C.red, '✗');
+    console.log(`  ${mark} ${c.name.padEnd(8, ' ')} ${C.dim}${c.detail}${C.reset}`);
+  }
+  if (result.suggestions.length) {
+    console.log('');
+    console.log(`  ${C.bold}先改这两项${C.reset}`);
+    result.suggestions.forEach((s, i) => {
+      console.log(`  ${i + 1}. ${s.name}：${s.advice}`);
+    });
+  }
+  console.log('');
+  console.log(`${C.dim}  完整 40 分自测（含改进清单）：https://www.geofde.cn/tools${C.reset}`);
+  console.log('');
+}
+
+main();

package/index.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * ai-friendly-check — 检查网页对 AI 搜索引擎（GEO）的友好度
+ * 8 项指标，40 分制。
+ *
+ * 官网：https://www.geofde.cn/tools
+ * 许可：MIT
+ */
+
+const MAX_SCORE = 40;
+
+function parseAttrs(tag) {
+  const attrs = {};
+  const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g;
+  let m;
+  while ((m = re.exec(tag))) {
+    attrs[m[1].toLowerCase()] = m[3] !== undefined ? m[3] : m[4] !== undefined ? m[4] : m[5];
+  }
+  return attrs;
+}
+
+function findMeta(html, name) {
+  const re = /<meta\b[^>]*>/gi;
+  let m;
+  while ((m = re.exec(html))) {
+    const a = parseAttrs(m[0]);
+    const key = (a.name || a.property || '').toLowerCase();
+    if (key === name.toLowerCase()) return (a.content || '').trim();
+  }
+  return '';
+}
+
+function extractText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function textSize(text) {
+  const cjk = (text.match(/[\u4e00-\u9fff]/g) || []).length;
+  const words = (text.replace(/[\u4e00-\u9fff]/g, ' ').match(/[a-zA-Z0-9]+/g) || []).length;
+  return cjk + words;
+}
+
+/**
+ * 审计一段 HTML。
+ * @param {string} html 页面 HTML
+ * @param {string} [url] 页面地址（可选，仅用于回显）
+ * @returns {object} 审计结果
+ */
+function audit(html, url = '') {
+  if (typeof html !== 'string') throw new TypeError('html must be a string');
+  const source = html;
+
+  const titleMatch = source.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].replace(/\s+/g, ' ').trim() : '';
+  const description = findMeta(source, 'description');
+  const h1Count = (source.match(/<h1\b[^>]*>/gi) || []).length;
+  const hasJsonLd = /<script[^>]+type\s*=\s*["']application\/ld\+json["'][^>]*>/i.test(source);
+  const hasFaqSchema = /FAQPage|"@type"\s*:\s*"Question"/i.test(source);
+  const hasFaqHeadings = /<h[23][^>]*>[^<]{0,80}[?？]\s*<\/h[23]>/i.test(source);
+  const semanticTags = ['main', 'article', 'nav', 'header', 'footer'].filter((t) =>
+    new RegExp(`<${t}\\b`, 'i').test(source)
+  );
+  const text = extractText(source);
+  const size = textSize(text);
+  const robots = findMeta(source, 'robots');
+  const noindex = /noindex/i.test(robots);
+  const hasCanonical = /<link\b[^>]*rel\s*=\s*["']canonical["']/i.test(source);
+
+  const checks = [
+    {
+      id: 'title',
+      name: '页面标题',
+      points: 5,
+      passed: title.length >= 8 && title.length <= 60,
+      detail: title ? `长度 ${title.length} 字：${title.slice(0, 40)}${title.length > 40 ? '…' : ''}` : '未找到 <title>',
+      advice: '标题控制在 8–60 字，写清「做什么 + 给谁 + 在哪」，避免纯关键词堆砌。',
+    },
+    {
+      id: 'description',
+      name: '页面描述',
+      points: 5,
+      passed: description.length >= 40 && description.length <= 160,
+      detail: description ? `长度 ${description.length} 字` : '未找到 meta description',
+      advice: '补一段 40–160 字的 meta description，用完整句子说清「你是谁、解决什么问题」。',
+    },
+    {
+      id: 'h1',
+      name: 'H1 结构',
+      points: 5,
+      passed: h1Count === 1,
+      detail: `检测到 ${h1Count} 个 H1`,
+      advice: '每页只保留一个 H1，用一句话概括页面主题，其余层级用 H2/H3。',
+    },
+    {
+      id: 'jsonld',
+      name: '结构化数据',
+      points: 5,
+      passed: hasJsonLd,
+      detail: hasJsonLd ? '检测到 JSON-LD' : '未检测到 JSON-LD',
+      advice: '用 JSON-LD 标注 Organization、Product、FAQPage 等实体，AI 更容易准确引用你。',
+    },
+    {
+      id: 'faq',
+      name: '问答结构',
+      points: 5,
+      passed: hasFaqSchema || hasFaqHeadings,
+      detail: hasFaqSchema ? '检测到 FAQ 结构化标记' : hasFaqHeadings ? '检测到问答式标题' : '未检测到问答内容',
+      advice: '把客户最常问的 5–10 个问题做成「问题 + 简明回答」，并加 FAQPage 标记。',
+    },
+    {
+      id: 'semantic',
+      name: '语义化标签',
+      points: 5,
+      passed: semanticTags.length >= 2,
+      detail: semanticTags.length ? `检测到：${semanticTags.join(', ')}` : '未检测到语义化标签',
+      advice: '用 main / article / nav / header 等标签划分页面结构，帮助 AI 判断内容主次。',
+    },
+    {
+      id: 'content',
+      name: '正文信息量',
+      points: 5,
+      passed: size >= 500,
+      detail: `正文约 ${size} 字`,
+      advice: '正文至少 500 字有效内容，围绕真实业务问题展开，而不是口号式短句。',
+    },
+    {
+      id: 'indexable',
+      name: '可索引性',
+      points: 5,
+      passed: !noindex && hasCanonical,
+      detail: noindex ? '检测到 noindex' : hasCanonical ? '可索引，已声明 canonical' : '可索引，但缺少 canonical',
+      advice: '移除 noindex，并声明 canonical 指向规范地址，避免同一内容多个 URL 分散权重。',
+    },
+  ];
+
+  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
+  const failed = checks.filter((c) => !c.passed);
+  const grade =
+    score >= 36 ? '优秀' : score >= 28 ? '良好' : score >= 20 ? '及格' : '待改进';
+
+  return {
+    url,
+    score,
+    maxScore: MAX_SCORE,
+    grade,
+    checks,
+    suggestions: failed.slice(0, 2).map((c) => ({ id: c.id, name: c.name, advice: c.advice })),
+  };
+}
+
+module.exports = { audit, MAX_SCORE };

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "ai-friendly-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "检查网页对 AI 搜索引擎的友好度：8 项指标、40 分制评分，一行命令出报告。",
+  "main": "index.js",
+  "bin": {
+    "ai-friendly-check": "bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "geo",
+    "generative-engine-optimization",
+    "ai-search",
+    "seo",
+    "audit",
+    "llm",
+    "ai-friendly",
+    "structured-data"
+  ],
+  "homepage": "https://www.geofde.cn/tools",
+  "author": "落地派 <hello@geofde.cn> (https://www.geofde.cn)",
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test/audit.test.js"
+  }
+}