企业官网建设流程全解析

PinchBench 是一个开源基准测试系统（benchmark），用于评估 LLM 模型作为 OpenClaw 编码智能体（coding agent）完成真实任务的能力。这篇贡献指南带你走完全流程：编写你的第一个基准任务、在tasks/manifest.yaml中注册、跑通 Lint 检查与单元测试（pytest），最后本地验证并提交 PR。

一、PinchBench 是什么？值得贡献吗？

PinchBench 不做"合成考题"，而是把 53 个真实世界任务直接丢给智能体：排会议、写代码、分诊邮件、查股价、分析 CSV……每个任务都有明确的评分标准，由自动化脚本、LLM 评审或两者混合（hybrid）打分。

它考察的不是模型"知道多少"，而是：

• 工具调用— 能否用正确参数调用正确的工具
• 多步推理— 能否把一系列动作串起来完成复杂任务
• 真实世界的脏乱— 能否处理模糊指令与不完整信息

上图就是仓库里真实任务使用的照片素材之一——PinchBench 的基准任务覆盖图像识别、数据分析、邮件分诊等几乎全部日常场景。

仓库目录速览：

二、第一步：克隆仓库并验证运行环境

环境要求：Python 3.10+、uv包管理器、一个运行中的 OpenClaw 实例。

git clone https://gitcode.com/gh_mirrors/skill1/skill cd skill

安装开发依赖（pytest、pytest-cov、black、ruff 均配置在 pyproject.toml 的dev可选依赖中）：

uv sync --extra dev

用最小任务task_sanity冒烟验证环境（--no-upload只保留本地结果，不上传）：

./scripts/run.sh --model openrouter/openai/gpt-4o --suite task_sanity --no-upload

💡 模型 ID 必须带 provider 前缀；scripts/run.sh 只是 scripts/benchmark.py 的便捷入口。

三、如何编写一个基准任务文件

1. 从官方模板开始

模板是 tasks/TASK_TEMPLATE.md，复制并重命名即可：

cp tasks/TASK_TEMPLATE.md tasks/task_my_first_task.md

⚠️ 关键规则：frontmatter 里的id必须与文件名（去掉.md）完全一致，否则 Lint 直接报错。

2. 填写 YAML frontmatter

--- id: task_my_first_task name: My First Task category: csv_analysis # 必须与 manifest.yaml 中的分类一致 grading_type: automated # automated | llm_judge | hybrid timeout_seconds: 120 workspace_files: - source: csvs/apple_stock_2014.csv dest: stock.csv ---

• grading_type决定后续要写哪些小节：automated必须提供 Python 评分函数；llm_judge提供评分细则（rubric）；hybrid两者都要，并通过grading_weights给出权重（总和为 1.0）。
• workspace_files会把 assets/ 下的素材复制进任务的隔离工作区。仓库自带 8 个小而精的 CSV 数据集，用途说明见 assets/csvs/README.md。

3. 四个必填正文小节

想看最小可用示例，读 tasks/task_sanity.md 即可——完整任务不到 60 行。数据类任务可参考 tasks/task_csv_cities_ranking.md（hybrid 评分 + 工作区 CSV）。

上面三张照片来自 tasks/task_image_identification.md 的真实workspace_files（智能体需把它们分到 phone / food / menu 三类）。注意：答案键 assets/image_classification_answer_key.json 绝不能复制进工作区，否则任务就"泄题"了。

四、在 manifest.yaml 中注册任务（新手最常漏的一步）

tasks/manifest.yaml 是任务顺序与分类的唯一事实来源。新任务必须追加到对应分类列表的末尾：

categories: csv_analysis: - task_csv_cities_growth - task_my_first_task # ← 追加到这里

两条硬性约定：

• 一个任务只能出现在一个分类，且run_first里的任务必须存在于某个分类中
• 如果任务足够"有代表性"，也可以加入core列表——那是约 25 个任务的快速基准集，用--core参数运行

五、跑 Lint 检查：让 CI 一次通过

1. 清单一致性检查（最重要）

uv run scripts/lint_manifest.py

scripts/lint_manifest.py 共检查 7 项，全部通过才返回退出码 0：

1. manifest 中每个条目都有对应的.md文件
2. 每个task_*.md（模板除外）都登记在 manifest 中
3. 无重复条目
4. frontmatter 的id与文件名一致
5. 任务不跨多个分类
6. run_first条目存在于某个分类
7. frontmattercategory与 manifest 分类一致（不一致仅告警，不阻断）

看到Manifest lint: OK (N tasks in M categories, all in sync)即通过 ✅

2. argparse 帮助文案检查

如果你给 scripts/benchmark.py 新增了命令行参数，记得跑：

uv run scripts/lint_argparse_help.py

scripts/lint_argparse_help.py 会扫描所有 Python 文件中的add_argument(..., help=...)，揪出未转义的%——argparse 会对 help 文本做旧式%插值，字面量必须写成%%。

3. 代码风格

pyproject.toml 已配置 black 与 ruff（行宽 100，目标 Python 3.10）：

uv run black . uv run ruff check .

六、单元测试：为你的评分逻辑上保险 🧪

仓库测试位于 tests/，pytest 配置在 pyproject 中：testpaths = ["tests"]，文件命名test_*.py、类Test*、方法test_*。现有测试可直接当风格样板：

• tests/test_lib_grading.py：评分归一化、hybrid 加权合并
• tests/test_multi_session.py：多会话 frontmatter 解析
• tests/test_lib_trend.py：多次运行趋势分析

如果你为新任务抽出了可复用的评分辅助函数（例如放进 scripts/lib_grading.py），就为它补一个测试：

# tests/test_lib_grading_mytask.py import sys import unittest from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts")) from lib_grading import my_new_helper # 你新增的辅助函数 class TestMyTaskGrading(unittest.TestCase): def test_partial_credit_between_0_and_1(self): self.assertTrue(0.0 <= my_new_helper("partial") <= 1.0)

运行全部测试（或按关键词过滤）：

uv run pytest tests/ -v uv run pytest tests/ -k grading

七、本地验证与提交清单

提交前，只跑你自己的任务做端到端验证：

./scripts/run.sh --model openrouter/openai/gpt-4o --suite task_my_first_task --no-upload

会话转录会自动保存到results/{run_id}_transcripts/task_my_first_task.jsonl，方便复查智能体到底做了什么。

提交前自查（tasks/TASK_TEMPLATE.md 末尾有官方版清单）：

• frontmatter 完整，id与文件名一致
• 任务已登记进 tasks/manifest.yaml，category对齐
• grading_type与实际提供的小节对应；hybrid 权重总和为 1.0
• 评分函数本地运行无异常，超时时间合理
• uv run scripts/lint_manifest.py输出 OK
• uv run pytest tests/全部通过，uv run ruff check .无告警

全部打勾后就可以发起 Pull Request 了。如果 CI 需要容器化环境，Dockerfile.benchmark 已预装 OpenClaw 与 uv，可直接复用。

常见问题速查

Q：Lint 报File exists but missing from manifest？A：你创建了任务文件但忘了登记 manifest——把任务 ID 追加到对应分类末尾即可。

Q：frontmatter category 只有告警、不阻断？A：说明 frontmatter 的category与 manifest 分类不一致（含大小写），两者对齐后告警即消失。

Q：想测多轮对话任务怎么办？A：frontmatter 设multi_session: true并写sessions列表（格式见 tasks/TASK_TEMPLATE.md 的 Multi-Session 小节）。会话数控制在 2–5 个，并相应调大timeout_seconds。

走完"写任务 → 注册清单 → Lint → 单元测试 → 本地验证"这条流水线，你就已经具备了和 PinchBench 维护者相同的检查标准。下一个目标：让你的任务进入core快速基准集 🚀