SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tutorial-checker

tutorial-checker

写作与研究

查看项目

更新于 10-16 07:29

技能介绍

用途

Tutorial Checker 用于在合并或发布任何教程之前，对教程进行结构一致性、完整性和代码可运行性校验。它适合在评审、定稿或对 cookbook/tutorial 做质量保证（QA）时使用。

主要能力

该技能被调用后，会按顺序执行全部检查，并以清单形式报告每项的通过/失败状态，最后给出通过项、失败项汇总以及针对每个失败项的具体修复说明。检查分为六个阶段：

阶段 1：文件结构检查

验证教程文件夹是否包含必需文件：README.md、setup.sql（数据库教程）或等效安装脚本、requirements.txt（存在 Python 代码时）、至少一个支持脚本（如 embed.py、load.py）、包含所有必需环境变量的 .env.example；仓库根目录的 .gitignore 需排除 .env 并包含 !.env.example；根目录需有 LICENSE、CLAUDE.md；根 README.md 需用文件索引表链接到教程文件夹；任何已提交文件中不得出现密钥或 API key（检查 sk-、key-、API token 等模式）。

阶段 2：README 结构检查

读取教程 README.md，验证章节顺序：标题（H1）、Overview、Getting Started、What You'll Need（带粗体名称、描述和链接的项目符号前置条件列表）、至少两种安装方式、编号教程步骤（Step 1、Step 2……）、Going Further（或等效）、Current Limitations、What's Next（至少 4 个带链接的具体方向）、Resources（底部链接列表）。

阶段 3：内容质量检查

  • 代码片段：每个代码块上方有粗体标签说明用途；无“孤立”代码块；SQL 块使用 sql 标签，Python 块使用 python 或 bash 标签；产生输出的代码块包含预期输出或“you should see”描述。
  • 概念与解释：新概念（embeddings、BM25、RRF 等）首次出现时解释；解释不超过 2-4 句并配教程数据集中的具体示例；演示技术的步骤包含“What X is good at”和“Where it falls short”总结；每个步骤以连接下一步的过渡句结尾。
  • 前置条件与安装：每个前置条件链接到下载/注册页；明确说明包管理器选择并链接替代方案；Docker 安装包含确切的 docker run 命令；手动安装包含各平台（Linux、macOS、Windows）特定路径/命令；每个可能失败的安装步骤有验证命令；常见错误有排障指引。
  • 数据与署名：示例数据使用真实数据集（非“Document 1”“test”“foo”等占位符）；数据集来源带链接署名；注明数据集许可证；README 和包含数据的 SQL/脚本文件中均有署名。

阶段 4：一致性检查

验证跨文件名称与引用一致：表名、列名、索引名在 README.md、setup.sql 和所有脚本中一致；.env.example 中的环境变量名与脚本预期一致；requirements.txt 列出 Python 脚本使用的每个导入；Python 脚本导入 load_dotenv 并从教程文件夹（与脚本同目录）加载 .env；示例数据行数在 README、setup.sql 和脚本输出引用之间一致（如“Found 12 episodes”）。

阶段 5：代码可运行性检查

实际运行代码验证：

  • 5a. SQL 安装：对测试数据库运行 setup.sql 并确认无错误（psql -h localhost -U postgres -f setup.sql）；验证表以正确 schema 创建（\d episodes）；验证示例数据以预期行数插入（SELECT count(*) FROM episodes;）；验证索引已创建（SELECT indexname FROM pg_indexes WHERE tablename = '<table_name>';）。
  • 5b. Python 环境：创建虚拟环境并无错误安装依赖（cd <tutorial-folder>；uv venv && source .venv/bin/activate；uv pip install -r requirements.txt）；验证所有导入可解析（python -c "import openai; import psycopg2; from dotenv import load_dotenv; print('All imports OK')"）。
  • 5c. Python 脚本：运行主脚本（如 embed.py）并确认成功完成；验证输出与 README 所述一致；再次运行确认幂等性（应报告“nothing to do”或等效）；验证数据确实写入数据库（SELECT count(*) FROM episodes WHERE embedding IS NOT NULL;）。
  • 5d. 教程查询：运行 README 中部分 SQL 查询并验证返回结果；至少一个 BM25/关键词搜索查询返回行；验证结果合理（相关标题靠前）；若向量搜索查询使用 $1 占位符，注明需要运行时 embedding（可接受，只需验证查询无语法错误即可解析）。

重要：若数据库或 API key 不可用，跳过可运行性检查并清楚注明跳过了哪些检查及原因。不要因缺少基础设施而判定教程失败。

阶段 6：链接检查

验证 README 中所有链接：无占位链接（如 (link-to-part-1)、(TODO)、#）；内部文件链接可解析（如 ./setup.sql、./embed.py）；GitHub 仓库链接指向存在的仓库；外部链接为 HTTPS（非 HTTP）。

使用方式

调用该技能后，它会按上述六个阶段依次执行检查，并以下列格式输出结果：

# Tutorial Check: [Tutorial Name]

## Summary
- **Passed:** X / Y checks
- **Failed:** N checks
- **Skipped:** M checks (reason)

## Results

### Phase 1: File Structure
- [x] README.md exists
- [x] setup.sql exists
- [ ] requirements.txt — MISSING (embed.py imports openai but no requirements.txt)

### Phase 2: README Structure
...

### Phase 3: Content Quality
...

### Phase 4: Consistency
...

### Phase 5: Code Runnability
...

### Phase 6: Link Check
...

## Fixes Needed

1. **[Phase 1]** Create `requirements.txt` with: openai, psycopg2-binary, python-dotenv
2. **[Phase 3]** Add a bold label above the SQL block on line 142
3. ...

适用场景

  • 评审、定稿或对 cookbook/tutorial 做质量保证（QA）。
  • 在合并或发布任何教程之前运行。

限制与规则

  • 要彻底但公平：标记真实问题，而非风格吹毛求疵。
  • 修复说明要具体：“Add a bold label above the SQL block on line 142”优于“some code blocks are missing labels”。
  • 不自动修复：报告问题，由用户决定处理哪些。仅在明确要求时才做更改。
  • 若代码无法运行（无数据库、无 API key、无 Docker），跳过这些检查并清楚说明跳过了什么。
  • 积极检查密钥：grep sk-proj-、sk-、key-、token、password（排除 .env.example 中的占位值）。泄露的密钥是最高优先级发现。