在 Codex 中跑通第一个 Skill：给博客文章做一次发布前检查

1
---
2
name: article-preflight
3
description: 检查指定博客文章的元数据、正文重复主标题和站内文章链接，输出问题及未完成项。用于发布前检查，不修改或发布。
4
---
5

6
# 文章发布前检查
7

8
输入是指定稿件路径和项目根目录。
9

10
1. 读取稿件和内容规则。在项目根目录运行：
11
   node .agents/skills/article-preflight/scripts/check.mjs <稿件路径>
12
2. 本项目要求 title 为非空字符串，published 被 YAML 解析为有效日期。
13
3. 正文不重复一级标题；代码块中的标题和链接不作为正文检查项。
14
4. 本地目标存在不等于线上可访问、草稿已发布或锚点有效。
15
5. 阅读效果数字和验证状态。缺少依据时标为待核实，
16
   不把“建议运行”“尚未运行”写成“已经通过”。
17
6. 分开报告通过项、问题和未完成项，注明位置、依据及建议。
18

19
只输出报告，不修改文章、不提交、不发布。

1
import fs from "node:fs";
2
import path from "node:path";
3
import matter from "gray-matter";
4
import { marked } from "marked";
5

6
const root = process.cwd();
7
const file = process.argv[2];
8
if (!file) throw new Error("请提供待检查的文章文件路径");
9
const { data, content } = matter(fs.readFileSync(file, "utf8"));
10
const problems = [];
11
let headings = 0;
12
let links = 0;
13

14
if (typeof data.title !== "string" || !data.title.trim()) {
15
  problems.push({ item: "title", reason: "标题不是非空字符串" });
16
}
17
if (!(data.published instanceof Date) ||
18
    Number.isNaN(data.published.getTime())) {
19
  problems.push({ item: "published", reason: "未被 YAML 解析为有效日期" });
20
}
21

22
marked.walkTokens(marked.lexer(content), (token) => {
23
  if (token.type === "heading" && token.depth === 1) {
24
    headings++;
25
    problems.push({ item: "正文一级标题", text: token.text });
26
  }
27
  if (token.type !== "link" || !token.href.startsWith("/posts/")) return;
28
  links++;
29
  const url = new URL(token.href, "https://local.invalid");
30
  const slug = decodeURIComponent(url.pathname.slice(7)).replace(/\/$/, "");
31
  const base = path.resolve(root, "src/content/posts", slug);
32
  const posts = path.resolve(root, "src/content/posts") + path.sep;
33
  if (!base.startsWith(posts)) throw new Error("链接目标超出文章目录");
34
  if (![".md", ".mdx"].some((ext) => fs.existsSync(base + ext))) {
35
    problems.push({ item: "本地文章链接", text: token.href });
36
  }
37
});
38

39
console.log(JSON.stringify({
40
  file,
41
  metadata: {
42
    title: data.title,
43
    publishedType: data.published instanceof Date ? "Date" : typeof data.published,
44
  },
45
  bodyH1: headings,
46
  localPostLinks: links,
47
  problems,
48
  scope: "固定项检查；不检查线上可达性、链接锚点、MDX 组件语义或事实依据",
49
}, null, 2));

1
---
2
title: 用 AI 检查一篇博客文章
3
published: 日期待定
4
description: 用于验证文章检查规则的错误样例，不属于正式文章。
5
draft: true
6
---
7

8
# 用 AI 检查一篇博客文章
9

10
下面是希望读者继续阅读的内容：[后续教程](/posts/article-that-does-not-exist/)。
11

12
建议上线前执行 pnpm check。目前还没有运行这项检查。
13

14
使用这个流程，检查时间减少了 40%。
15

16
## 命令示例
17

18
以下内容是代码示例，不是正文标题和实际链接：
19

20
```markdown
21
# 示例标题
22
[示例链接](/posts/only-in-code/)
23
```