Nhiệm vụ: Cấu hình Open Graph / meta tags để hiển thị bản xem trước trang chính xác trong các ứng dụng nhắn tin

Tăng cường kiểm tra og:image sau các lỗi từ Google

Google đã báo cáo lỗi "URL không hợp lệ trong trường image" cho một số thẻ sản phẩm. Nguyên nhân được cho là các đường dẫn hình ảnh gốc có chứa ký tự tiếng Cyrillic chưa được mã hóa và khoảng trắng, mà hệ thống kiểm tra trước đây chưa phát hiện ra.

Đã cập nhật tập lệnh agent/scripts/check-page-image/index.ts của dự án happybaby2000.ru:

• kiểm tra giá trị og:image gốc trước khi thực hiện bất kỳ chuẩn hóa nào;
• URL phải là địa chỉ HTTP(S) tuyệt đối có chứa host;
• phát hiện các khoảng trắng chưa mã hóa, tiếng Cyrillic, ký tự điều khiển và các ký tự không hợp lệ khác;
• kiểm tra tính hợp lệ của các chuỗi thoát %-escape;
• phát hiện dấu ngoặc vuông chưa mã hóa trong path/query/fragment và dấu # lặp lại trong phần fragment, đồng thời cho phép IPv6 nằm trong dấu ngoặc vuông;
• kiểm tra tất cả các thẻ og:image trên trang, không chỉ thẻ đầu tiên;
• phần chẩn đoán chỉ rõ số thứ tự hình ảnh, URL gốc và nguyên nhân lỗi; đối với các ký tự không hợp lệ, hệ thống cũng hiển thị mã Unicode và vị trí;
• khi xảy ra lỗi, tập lệnh trả về mã 1, khi thành công trả về 0.

Bên cạnh đó, một bài kiểm tra liên tục agent/scripts/check-page-image/index.test.ts sử dụng Vitest đã được thêm vào. Cấu hình Vitest được mở rộng cho scripts/**/*.test.ts. Bộ kiểm tra bao gồm 28 kịch bản, bao gồm URL hợp lệ và không hợp lệ, ký tự được mã hóa, IPv6, không có hình ảnh, nhiều thẻ og:image và độ chính xác của chẩn đoán.

Quá trình kiểm tra diễn ra thành công: đã vượt qua 28 bài kiểm tra, ESLint, Prettier và git diff --check — không có lỗi.

Lệnh chạy kiểm tra:

npm run test -- scripts/check-page-image/index.test.ts

Hạn chế kiểm tra: tập lệnh này xác thực cú pháp URL từ og:image, nhưng không kiểm tra tính khả dụng của chính hình ảnh đó và không đảm bảo URL sẽ được các dịch vụ của Google chấp nhận. Tập lệnh không tự động sửa lỗi URL.

Tiến trình: Đầu tiên là kiểm tra chạy được, sau đó mới đến triển khai

Trước khi thực hiện các thay đổi, một tập lệnh TypeScript chạy trên terminal riêng biệt đã được viết trước. Tập lệnh này thực hiện yêu cầu HTTP tới trang, phân tích cú pháp HTML thông qua cheerio và kiểm tra các thẻ Open Graph bắt buộc. Điều này cung cấp một đường cơ sở khách quan trước khi chỉnh sửa và một tiêu chí nghiệm thu sẵn có cho AI agent.

Tập lệnh kiểm tra

import * as cheerio from "cheerio";

const REQUIRED_TAGS = [
  "og:title",
  "og:description",
  "og:image",
  "og:url",
  "og:type",
] as const;

function isAbsoluteHttpUrl(value: string): boolean {
  try {
    const url = new URL(value);
    return url.protocol === "http:" || url.protocol === "https:";
  } catch {
    return false;
  }
}

async function main() {
  const targetUrl = process.argv[2];

  if (!targetUrl) {
    console.error("Usage: npx tsx check-open-graph.ts <url>");
    process.exit(2);
  }

  const response = await fetch(targetUrl, {
    redirect: "follow",
    headers: {
      "User-Agent": "OpenGraphChecker/1.0",
    },
  });

  if (!response.ok) {
    console.error(`HTTP ${response.status} ${response.statusText}`);
    process.exit(1);
  }

  const html = await response.text();
  const $ = cheerio.load(html);

  let hasErrors = false;

  console.log(`HTTP: ${response.status}\n`);

  const values = Object.fromEntries(
    REQUIRED_TAGS.map((property) => {
      const value =
        $(`meta[property="${property}"]`).first().attr("content")?.trim() ?? "";

      if (!value) {
        console.log(`✗ ${property}: missing`);
        hasErrors = true;
      } else {
        console.log(`✓ ${property}: ${value}`);
      }

      return [property, value];
    }),
  );

  const image = values["og:image"];
  const ogUrl = values["og:url"];

  if (image && !isAbsoluteHttpUrl(image)) {
    console.log(`✗ og:image is not absolute: ${image}`);
    hasErrors = true;
  }

  if (ogUrl && !isAbsoluteHttpUrl(ogUrl)) {
    console.log(`✗ og:url is not absolute: ${ogUrl}`);
    hasErrors = true;
  }

  console.log(
    hasErrors
      ? "\nRESULT: invalid or incomplete"
      : "\nRESULT: OK",
  );

  process.exit(hasErrors ? 1 : 0);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Trạng thái trước khi triển khai

Lần chạy đầu tiên đã cho ra kết quả âm tính đúng như dự kiến:

HTTP: 200

✗ og:title: missing
✗ og:description: missing
✗ og:image: missing
✗ og:url: missing
✗ og:type: missing

RESULT: invalid or incomplete

Sau đó, tác vụ đã được chuyển cho AI agent không phải theo cách diễn đạt trừu tượng như "thêm Open Graph", mà đi kèm với một tập lệnh kiểm tra cụ thể và cách thức có thể tái tạo để kiểm tra kết quả.

Báo cáo của Agent

Agent đã thông báo về các thay đổi sau:

Đã xong. Các thay đổi:

index.tsx — đã thêm các prop image và ogType, hiển thị og:title, og:description, og:image, og:url, og:type
index.tsx — tính toán imageUrl và truyền vào SeoHeaders với ogType="product"
Bạn có thể kiểm tra bằng tập lệnh:

npx tsx scripts/check-page-image/index.ts "http://localhost:3000/catalog/product.html"

Kiểm tra lại

Sau khi thực hiện các thay đổi, phương pháp kiểm tra tương tự đã cho kết quả:

HTTP: 200

✓ og:title: Sân chơi kích thước nhỏ Korabl
✓ og:description: Kích thước 3.48 x 1.78 x 2.32 m.
✓ og:image: http://localhost:3000/images/resized/middle/images/img.jpg
✓ og:url: http://localhost:3000/catalog/product.html
✓ og:type: product

RESULT: OK

Kết luận thực tế

Phương pháp này tỏ ra rất hữu ích: đầu tiên, một bài kiểm tra có thể chạy được tạo ra để ghi nhận trạng thái hiện tại và tiêu chí hoàn thành, sau đó bài kiểm tra này được chuyển cho người thực hiện cùng với tác vụ. Điều này làm giảm sự mơ hồ trong việc giao nhiệm vụ và giúp kết quả có thể được kiểm chứng không dựa trên báo cáo của agent, mà dựa trên hành vi thực tế của hệ thống.

Bước tiếp theo là củng cố mẫu này: nếu agent được cung cấp một tập lệnh kiểm tra, phần giao việc sẽ ngay lập tức yêu cầu không chỉ thực hiện các thay đổi mà còn phải tự chạy tập lệnh đó sau khi triển khai và đính kèm kết quả thực tế. Khi đó, chu trình sẽ trở nên khép kín: reproduce → implement → verify (tái tạo → triển khai → xác minh), và con người chỉ còn phải thực hiện việc kiểm tra đối soát thay vì kiểm tra ban đầu.