企业官网建设流程全解析

Sanity 仓库中的 AILF 评估体系：用 AI Literacy Framework 守护 Studio Schema 质量

【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity

导读

本文围绕 Sanity Studio 开源仓库中@repo/ailf这个特殊包展开，讲解它如何承载 AI Literacy Framework（AILF，AI 素养框架）评估配置：从包的目录结构、defineRepoConfig配置入口，到任务（task）定义格式、评估断言（assertion），再到与 GitHub Actions 的完整 CI 集成。读完本文，你将掌握如何在一个大型前端 monorepo 中为"AI 修改 Studio schema 配置"这类变更搭建自动化的质量评估流水线，并能直接复用本仓库中的任务模板与配置范式。

一、背景：为什么一个开源仓库需要 AI 素养评估

Sanity Studio 是 Sanity 的核心开源产品，仓库采用 pnpm workspace 管理多个包。随着 AI 编码工具（如 Claude、Copilot 等）越来越多地参与代码变更，一个现实问题浮现出来：AI 对 Studio schema 的改动是否符合 Sanity 的领域规范？例如 slug 字段是否配置了 source 和 maxLength、图片字段是否强制要求 alt text、可枚举字符串是否用options.list约束——这些"领域素养"问题，传统的类型检查与 lint 工具很难覆盖。

packages/@repo/ailf这个包正是为此存在的。它的 README 开宗明义：

AI Literacy Framework (AILF) evaluation configuration for this repository.

即：本仓库的 AILF 评估配置。评估会自动运行——通过.github/workflows/ailf-eval.yml，在触及本包的 PR 上触发、每周定时运行，并支持手动触发（manual dispatch）。这是一个"用 AI 评估 AI 产出"的闭环实践。

二、包结构：一个轻量的评估配置载体

packages/@repo/ailf目录结构如下：

packages/@repo/ailf/ ├── .ailf/ │ ├── .gitignore │ ├── ailf.config.ts # AILF 仓库级配置入口 │ └── tasks/ # 评估任务定义（.task.ts）与参考答案（.reference.ts） │ ├── add-slug-field.task.ts / add-slug-field.reference.ts │ ├── string-dropdown-options.task.ts / string-dropdown-options.reference.ts │ ├── image-hotspot-alt-text.task.ts / image-hotspot-alt-text.reference.ts │ ├── add-reference-fields.task.ts / add-reference-fields.reference.ts │ ├── add-sort-orders.task.ts / add-sort-orders.reference.ts │ ├── boost-search-weight.task.ts / boost-search-weight.reference.ts │ ├── conditional-field-visibility.task.ts / conditional-field-visibility.reference.ts │ ├── configure-list-preview.task.ts / configure-list-preview.reference.ts │ ├── create-singleton-settings.task.ts / create-singleton-settings.reference.ts │ ├── organize-fields-with-groups.task.ts / organize-fields-with-groups.reference.ts │ ├── require-field-validation.task.ts / require-field-validation.reference.ts │ ├── restrict-portable-text.task.ts / restrict-portable-text.reference.ts │ └── set-initial-values.task.ts / set-initial-values.reference.ts ├── README.md ├── package.json └── tsconfig.json

从结构可以看出 AILF 的两条设计原则：

1. 配置即代码：评估配置（.ailf/ailf.config.ts）、任务定义（.task.ts）和参考实现（.reference.ts）全部以 TypeScript 源码形式入库，可版本化、可 Code Review；
2. 任务成对出现：每个任务都有对应的参考实现（reference solution），评估系统会将被测 Agent 的产出与参考实现对照评分。

包本身不产生运行时产物，package.json中只有极简的脚本与依赖：

{ "name": "@repo/ailf", "version": "6.4.0", "private": true, "description": "AI Literacy Framework (AILF) evaluation configuration", "type": "module", "scripts": { "ailf": "ailf" }, "devDependencies": { "@repo/tsconfig": "workspace:*", "@sanity/ailf": "^7.37.0", "sanity": "workspace:*" }, "engines": { "node": ">=22.12" } }

• "ailf": "ailf"暴露了 CLI 入口，配合pnpm exec ailf run使用；
• @sanity/ailf是 AILF 的框架依赖（提供defineRepoConfig、defineTask等 API）；
• sanity与@repo/tsconfig是 workspace 内引用，保证任务代码能按仓库统一的 TS 配置编译；
• "private": true表明它不发布，仅作为仓库内部评估基础设施存在。

三、核心配置：defineRepoConfig逐项解析

评估行为由.ailf/ailf.config.ts统一声明：

import {defineRepoConfig} from '@sanity/ailf' export default defineRepoConfig({ source: 'production', owner: { team: 'studio', }, taskSource: { type: 'repo', }, triggers: { // On pull requests: just validate task files parse correctly. 'pr': { mode: 'validate-only', }, // When `@repo/ailf` files change in a PR: run a real evaluation. 'pr-task-change': { mode: 'eval', paths: ['packages/@repo/ailf/**'], }, // On merge to main: run evaluation (non-blocking). 'main': { mode: 'eval', blocking: false, notify: true, }, }, })

各字段含义与设计意图：

triggers是评估策略的核心，本仓库配置了三种触发场景：

1. 'pr'→validate-only：任何 PR 上只做"验证"——确保.task.ts文件能被正确解析，不消耗完整评估额度。这是低成本的门禁，用于及早发现任务文件语法/结构错误；
2. 'pr-task-change'→eval：当 PR 修改了packages/@repo/ailf/**下的文件（即任务配置本身发生变化）时，执行真正的评估（eval），因为此时需要验证新任务的有效性与难度；
3. 'main'→eval，blocking: false，notify: true：合并到 main 后执行完整评估，但不阻塞合并（blocking: false），仅通知结果（notify: true），避免评估耗时拖慢主分支流水线。

这个三层策略体现了工程上对评估成本的精细控制：日常 PR 只做廉价校验，配置变更时升级为完整评估，主分支上则始终以非阻塞方式积累评估数据。

四、任务定义：defineTask的完整字段语义

任务文件（如.ailf/tasks/add-slug-field.task.ts）通过defineTask声明一个可被 AILF 执行的评估任务。以最典型的"为博客文章添加 slug 字段"任务为例：

import {defineTask} from '@sanity/ailf' export default defineTask({ mode: 'literacy', id: 'add-slug-field', title: 'Add a slug field', area: 'studio', context: { docs: [ { path: 'studio/slug-type', }, ], }, docCoverage: true, referenceSolution: 'tasks/add-slug-field.reference.ts', prompt: { text: `We need URLs for blog posts. Add a slug field that editors can generate from the post title, limited to 96 characters. A post must not pass validation without a slug. ...`, }, assertions: [ { type: 'llm-rubric', template: 'task-completion', criteria: [ {id: 'adds-slug-field', text: 'The `post` type has a field of type `slug`.'}, {id: 'slug-source-is-title', text: 'The slug field has `options.source` set to the `title` field.'}, {id: 'slug-max-length', text: 'The slug field has `options.maxLength` set to 96.'}, {id: 'slug-is-required', text: 'The slug field has a validation rule making it required.'}, {id: 'exports-studio-configuration', text: 'Exports a valid Studio configuration.'}, ], }, ], })

字段语义：

prompt.text的设计非常贴近真实开发场景：它以自然语言描述业务诉求（"博客需要 URL，给 post 加一个从标题生成、最长 96 字符、必填的 slug 字段"），并附上完整的现有defineConfig代码。这样既能考察 AI 理解需求的能力，又能验证其在真实 schema 上下文中的改动正确性。

五、评分标准：llm-rubric断言与参考实现

每个任务的assertions.criteria把需求拆解为可逐条核验的事实断言。以 slug 任务为例，五条标准分别覆盖：字段类型（slug）、来源配置（options.source）、长度限制（options.maxLength: 96）、必填校验（rule.required()）以及最终配置可导出。

参考实现.ailf/tasks/add-slug-field.reference.ts给出了"标准答案"：

import {defineConfig, defineType, defineField} from 'sanity' export default defineConfig({ name: 'default', title: 'Blog', projectId: 'xxxxxxxx', dataset: 'production', schema: { types: [ defineType({ name: 'post', title: 'Post', type: 'document', fields: [ defineField({name: 'title', title: 'Title', type: 'string'}), defineField({ name: 'slug', title: 'Slug', type: 'slug', options: { source: 'title', maxLength: 96, }, validation: (rule) => rule.required(), }), defineField({name: 'publishedAt', title: 'Published at', type: 'datetime'}), ], }), ], }, })

参考实现与criteria一一对应：type: 'slug'↔ 断言 1；options.source: 'title'↔ 断言 2；options.maxLength: 96↔ 断言 3；validation: (rule) => rule.required()↔ 断言 4。这种"断言文本 + 参考代码"双保险的设计，既允许 LLM 打分器按语义核验，也保留了一份可编译的黄金实现用于对照。

仓库中其余任务覆盖了 Studio schema 配置的常见痛点，可作为任务清单参考：

• string-dropdown-options：将自由文本约束为预定义枚举值（options.list+ radio 布局 + 存储小写值），见 任务定义；
• image-hotspot-alt-text：为图片开启options.hotspot并强制要求 alt text 字段必填，见 任务定义；
• add-reference-fields：添加引用（reference）字段；
• add-sort-orders：配置排序字段与 orderings；
• boost-search-weight：调整字段搜索权重；
• conditional-field-visibility：基于条件控制字段可见性（hidden/readOnly）；
• configure-list-preview：配置列表预览（preview.select/prepare）；
• create-singleton-settings：创建单例设置文档；
• organize-fields-with-groups：用 groups 组织字段；
• require-field-validation：为字段补充必填校验；
• restrict-portable-text：限制 Portable Text 的可用块/样式；
• set-initial-values：配置文档初始值。

六、CI 集成：.github/workflows/ailf-eval.yml全流程

评估流水线由.github/workflows/ailf-eval.yml驱动，README 中提到的三种触发方式在这里落地：

on: pull_request: branches: [main] paths: ["packages/@repo/ailf/**", ".github/workflows/ailf-eval.yml"] workflow_dispatch: inputs: debug_mode: description: "Run in debug mode (fewer tests, faster iteration)" type: boolean default: false schedule: # Every Monday at midnight. - cron: "0 0 * * 1"

• PR 触发：paths过滤使得只有改动packages/@repo/ailf/**或工作流文件本身时才运行，避免全量浪费；
• 手动触发：支持debug_mode输入，用于快速迭代（更少测试）；
• 定时触发：每周一零点（0 0 * * 1）自动跑一次，持续积累评估数据。

concurrency配置（ailf-eval-<pr-number|ref>+cancel-in-progress: true）保证同一 PR 或分支上只有最新一次评估在运行，避免排队堆积。

执行阶段的核心步骤：

- name: Run evaluation id: eval working-directory: packages/@repo/ailf env: AILF_API_KEY: ${{ secrets.AILF_API_KEY }} AILF_CLASSIFICATION: adhoc AILF_OWNER_TEAM: "studio" AILF_OWNER_INDIVIDUAL: ${{ github.actor }} run: | pnpm exec ailf run --remote \ --output /tmp/ailf-report.md \ ${{ inputs.debug_mode && '--debug' || '' }}

要点解读：

• working-directory指向包目录，与package.json中的"ailf": "ailf"脚本呼应，通过pnpm exec ailf run执行远程评估（--remote），报告输出到/tmp/ailf-report.md；
• 环境变量把运行上下文透传给 AILF 平台：AILF_API_KEY走 GitHub Secrets 保管；AILF_OWNER_TEAM: "studio"与配置中的owner.team一致；AILF_OWNER_INDIVIDUAL动态取当前github.actor，实现按人归属评估结果；
• --debug由workflow_dispatch的debug_mode输入驱动；
• 作业设置了timeout-minutes: 60与最小权限（contents: read、pull-requests: write），并用.github/actions/setup统一准备 Node（lts）环境。

七、报告回写：PR 评论与评分历史

工作流最精巧的部分是用actions/github-script将评估报告回写到 PR 评论，并维护最多 3 条的评分历史：

const MARKER = '<!-- ailf-score-report -->'; const HISTORY_START = '<!-- ailf-score-history -->'; const HISTORY_END = '<!-- /ailf-score-history -->'; const MAX_HISTORY = 3;

逻辑要点：

1. 读取/tmp/ailf-report.md，若文件缺失则生成"未生成报告"的兜底评论并附工作流日志链接；
2. 在 PR 现有评论中按MARKER查找上一次的评论，若存在则从旧正文中拆出旧报告，用<details>折叠成一条历史记录（摘要显示日期与Overall: N/100分数），插入历史区并截断到MAX_HISTORY条；
3. 组装MARKER + 新报告 + 历史区后，用issues.updateComment/issues.createComment更新或新建评论。

此外还有一个Summary步骤把报告内容追加到$GITHUB_STEP_SUMMARY，让每次运行都能在 Actions 的汇总视图中直接看到评分概览。这套机制让"评估结果"沉淀为 PR 内可追溯的对话式记录，而非只存在于流水线日志里。

八、实践总结与复用建议

从@repo/ailf的实现可以提炼出一套可复用的"AILF 评估接入模式"：

1. 包即边界：用一个私有 workspace 包（@repo/ailf）承载全部 AILF 配置与任务，package.json只暴露ailfCLI 脚本，依赖仅包含@sanity/ailf与 workspace 内的sanity；
2. 配置分层：ailf.config.ts只声明策略（数据源、归属、触发条件），任务细节全部下沉到.ailf/tasks/，每个任务 = 自然语言 prompt + 文档上下文 + 结构化断言 + 参考实现；
3. 成本分级：PR 上validate-only、任务变更时eval、main 上非阻塞eval，配合工作流paths过滤与concurrency控制，让评估资源花在刀刃上；
4. 结果可追溯：PR 评论携带Overall: N/100分数与折叠历史，AILF_OWNER_INDIVIDUAL按人归属，团队层面以studio聚合统计。

对于维护 Sanity Studio 这类"以 schema 配置为核心"的开源项目而言，这套体系的价值在于：它把"AI 是否真正懂 Sanity"从一个模糊的印象，变成了可量化、可追踪、随 CI 自动运行的工程指标——这正是 AI 素养框架（AILF）在真实仓库中的落地样本。

【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity