思特注释任务
一个 思特任务就是一份 YAML 配置加一个数据文件。构建它需要完成三项工作：决定询问什么以及如何询问、正确地将它写下来、以及持续运行直到您亲眼目睹一个人从登录界面走到研究结束。第二项工作因为有验证器支持，所以很容易让人开始并停止于此。但这也是最不可能导致研究失败的一环。
如果项目根目录下有 AGENTS.md 文件，请先阅读——它承载了本技能之上项目特定的约定。
如果您在没有描述任务的情况下被调用
有人键入了 /potato-tasks，但对话中没有提供任何简要说明。不要立即开始构建，也不要开口就问"您想做什么？"——一个从未使用过思特的研究人员无法给出有用的回答。
请要求对方提供一句话描述，从中提出一个设计方案，然后仅确认您必须猜测的部分。references/interviewing.md 是问题库：开场提问、四行方案提案，然后进行两轮选择题，涵盖模态、单元、响应格式、每项注释者数量、质量控制、导出目标以及谁能登录——接着是第三轮，提供七个能力集群作为菜单，并仅深入探讨被选中的部分。
有两件事需要特别强调。每次都要询问数据的模态：它决定了显示方式、方案族以及族内指定媒体存储位置的键，而弄错这一点会悄无声息地导致问题。并且不要强推阶段——consent、training 和 prestudy 是协议决策点，大多数任务不需要它们，而需要它们的研究人员自己知道需要。
基于已有假设进行构建而不是等待，这一基本原则仍然适用——但前提是访谈已经提供了一些可据以假设的信息。当上下文中完全没有信息时，提出四个结构化问题对研究人员来说比您可能做出的任何猜测都要快。
安装思特
本技能的大部分功能都驱动 potato 命令并导入思特的注册表。如果包不在您运行命令的环境中，这两个功能都无法工作。
potato --version || pip install potato-annotation
scripts/walk_task.py 中的浏览器漫游功能还需要 Playwright：pip install 'potato-annotation[preview]' && playwright install chromium。
本技能中的脚本
下面有七个过程是以脚本形式而非指令形式提供的，因为它们足够复杂，手动操作容易出错，并且您会反复运行它们。它们与本文件一同位于 scripts/ 目录下。
| 脚本 | 功能 |
|---|---|
boot_and_check.py config.yaml -p 8000 | 启动、等待 200 状态码，并列出所有已配置但未加载任何内容的特性 |
walk_task.py --url … --config … --task-dir . | 注册一个注释者，走完整个研究，并检查答案是否已到达 user_state.json |
estimate_effort.py config.yaml --rate 15 | 项目数、所需注释者数、每人分钟数、总小时数和成本 |
find_design.py --type span --with-instructions | 在思特展示库中搜索 440 个已发布的任务设计 |
handover.py config.yaml --confirm | 移除您在测试期间创建的账户并写入 RUNNING.md |
check_ui.py --url … --config config.yaml | 渲染每个页面并报告折叠线以下的方案、空媒体、空选择块、没有回答控件的方案、不收集任何答案的方案、小部件报告的错误、快捷键冲突以及从未出现的方案。--phase poststudy 用于测量漫游无法到达的页面 |
study_status.py --url … --task-dir . | 进度、每位注释者的节奏、一致性以及正在运行的研究中看上去有问题的地方 |
每个脚本都支持 --help，而 boot_and_check、walk_task、check_ui 和 study_status 支持 --json，当您希望基于结果执行操作而非仅仅阅读时可以使用。
工作循环
potato validate config.yaml --strict # 结构和未知键
potato preview config.yaml # 表单声明的内容
potato preview config.yaml --screenshot out.png # 渲染一页，报告浏览器错误
nohup potato start config.yaml -p 8000 > server.log 2>&1 & # 启动并读取日志
前三个命令会快速返回。第四个命令不会返回——将其放到后台运行，轮询 curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ 直到返回 200，然后读取 server.log。
potato --help 会在 other commands 下列出这些命令（在 start 标志下方）。每个命令都有自己的语法，因此 potato validate --help 和 potato preview --help 是查看其选项的位置。
每一步捕获不同类别的错误
| 步骤 | 捕获的错误 | 忽略的错误 |
|---|---|---|
validate --strict | 缺少必填键、类型错误、1-2 层内的未知键 | 侧文件、阶段类型、方案条目内部的任何内容 |
preview | 配置声明了哪些方案和快捷键绑定 | 其中任何内容是否渲染 |
preview --screenshot | 未捕获的异常、console.error、一个页面上的失败请求 | 900px 以下的所有内容、每个条件小部件、每个其他阶段 |
| 启动 + 读取日志 | 侧文件格式、阶段组装、子系统初始化 | 外观效果 |
| 在浏览器中驱动 | 实际研究 | — |
跳过最后两步意味着任务可能在验证通过、截图正常的情况下发布，但会丢失其训练阶段、注意力检查以及三分之一的项目。
及早启动
启动日志才是真正的验证器。它是唯一能报告 validate 从未打开的那些配置部分是否实际工作的方法：
grep -E "ERROR|Traceback|Loaded [0-9]+|phase|missing required" server.log
一个包含训练和注意力检查的任务的正常启动会输出 Loaded 3 training instances 和 Loaded 2 attention check items，并且不会输出任何关于阶段的信息。其他任何输出都意味着某个功能虽然已配置但未生效。
在配置解析后立即启动——在界面完成之前、在指令编写完成之前。running-a-task.md 包含了后台运行配方、就绪检查、日志行表格，以及编辑后需要删除哪些生成的文件。
三种静默失败模式
已启用不等于正在运行。attention_checks.enabled: true 配合格式错误的项目文件会记录一个警告，然后输出 Loaded 0 attention check items，接着带着关闭的质量控制运行整个研究。请检查计数，而不是配置。
--strict 无法覆盖所有内容。它检查顶层以及大多数块的一层深度。它不会检查以下内部：phases、surveyflow、quality_control、crowdsourcing、publish、automatic_assignment、ui、ui_config，以及 annotation_schemes 或 instance_display.fields 的任何条目。key_binding 拼写成 key_value 会验证通过但什么都不做。不存在的阶段 type: 也是如此。
截图是视口，而不是页面。--screenshot 输出 1280×900 的图像。对于带有说明横幅的任务，截图会显示横幅和项目的一半内容——所有问题都不在截图中。"查看 PNG 并检查"Next"按钮是否在折叠线以上"的建议无法仅靠此工具实现。请驱动浏览器并使用 full_page=True 进行截图。
了解他们已有的内容
简要说明加数据文件是常见情况，但并非唯一情况。在设计任何内容之前先问四个问题，因为每个问题都有一个对应的命令，而且在配置编写完成后发现问题会很麻烦：
| 提问 | 原因 |
|---|---|
| 数据是什么格式，媒体文件在哪？ | 转录稿和对话语料库有各自的转换器 |
| 你们已经有注释数据了吗？ | potato import 读取十四种格式并写入一个可运行的项目 |
| 最终需要输出什么？ | 二十九种导出格式。在进行任何注释之前先检查目标格式 |
| 交接后谁来运行，运行多久？ | 决定托管方式、登录方式和允许列表 |
potato import --list-formats # coco, cvat, labelme, labelbox, via, …
potato transcripts interviews/ -r --dry-run # whisper, srt, vtt, textgrid, eaf, …
potato convokit reddit-corpus-small --unit conversation --emit-config
references/importing-existing-work.md 涵盖了所有这三种情况，包括最重要的一项决策：导入的注释是供人类修正的预注释，还是标记项目为已完成的 --seed-user 工作。
不明确的简要说明
在编写配置之前，请先阅读 references/asking-the-experimenter.md。当犯错成本低时可以自行决定；当犯错成本高、不可逆转或不属于您时请询问——注释单元、注释者预算、同意措辞，以及任何涉及可识别人员的内容。
永远不要等待答案。基于已有假设进行构建，将问题写入 QUESTIONS.md，同时交付一个可运行的东西，并说明您会首先重新审视哪个假设。
在构建功能之前先查找已有特性
思特内置的功能比配置参考所显示的要多。最昂贵的错误不是发明了一个不存在的类型名称——验证会捕获这个——而是手动组装思特已经具备的功能。
references/modes-and-subsystems.md 是一个路由表，将研究人员的需求映射到对应的功能模块：QDA 和代码本、单人模式、房间、裁决、审查工作流、会话、袖珍模式、主动学习、评审、众包、发布、遥测。在编写一个听起来像变通方案的方案之前，请先查看这个路由表。
该文件以七个集群开头——素材、答案、单元、人员、信任、模型辅助、输出——这与访谈中作为菜单提供的映射相同。将其作为检查清单对照简要说明运行：简要说明从未提及的集群，正是研究人员最可能遗漏但他们其实会需要的内容。最多提其中两个，且仅在其重要的场合；其余内容放入 QUESTIONS.md。
研究人员最常遗漏的集群是答案。他们要求 radio 和 likert 然后就停了，而 soft_label、range_slider、semantic_differential、constant_sum 和 confidence 从未被触及。
设计
references/designing-a-task.md 涵盖了每个任务背后的七个决策：单元、问题、响应格式、每项注释者数量、项目顺序、质量控制以及两端的阶段。
**路由表涵盖了常见需求并就此打住。**有十一种类型仅在生成的参考中命名，因此从未被触及：multirate（一个尺度上的十个评分，而不是十个 likert 方案）、hierarchical_multiselect（一个折叠的、可搜索的分类结构）、select、soft_label（一个分布而非强制选择）、range_slider、semantic_differential、conjoint、card_sort、extractive_qa、multi_document_event、code_review。每种类型都有一个可工作的示例和在 designing-a-task.md 中的一行说明。
两个容易出错且发现晚代价高昂的设计决策：
- 响应格式决定一致性度量。 思特根据模式种类来选择度量。一个 1–5 的评分如果存储为
radio会被视为无序进行评分，因此 "1 vs 2" 和 "1 vs 5" 计分相同。这是一个测量错误，而非装饰性问题。表格见references/assignment-and-agreement.md。 num_annotators_per_item设置目标，max_annotations_per_user设置一个人实际能看到的内容。 如果未设置，上限就是项目总数，因此每个人都看到整个语料库。将其设置得低于项目数，注释者就会提前停止，且没有任何提示说明原因。automatic_assignment.instance_per_annotator看起来像是这个功能的键，但根本不会被读取。
设计记录和成本
配置文件旁边有两个文件，配置文件本身无法容纳它们：
DESIGN.md——注释单元及其原因、每种响应格式的原因、每项注释者数量、质量控制的用途，以及一份单独、明确的列表，列出您因为简要说明没说明而做出的假设。最后一段是使该文档值得打开的原因。QUESTIONS.md——您根本无法决定的内容。永远不要等待答案；交付一个可运行的东西，同时附上问题。
python .claude/skills/potato-tasks/scripts/estimate_effort.py config.yaml --rate 15
报告设计需要的注释者数量、每人工作的时间、总小时数和成本。在指令编写之前运行它——这是发现没人能负担得起的设计的最便宜的方法。
references/recording-decisions.md 包含了 DESIGN.md 模板以及影响估算的因素。
从已发布的设计开始
在根据字段列表编写方案之前，先查找别人已经运行过的方案：
python .claude/skills/potato-tasks/scripts/find_design.py --query "stance" --with-instructions
python .claude/skills/potato-tasks/scripts/find_design.py --show text/argumentation-stance/argument-quality
思特展示库包含 440 个注释任务设计，其中大多数来自已发表的论文，包含真实的标签集和真实的问题措辞——并且其中 281 个带有书面指令。它们都没有 phases 块、同意页面或训练轮次，因此请从中获取问题，并从 worked-example.md 获取围绕问题的研究结构。references/finding-a-design.md 涵盖了在重用之前需要更改的内容。
编写指令
配置文件有验证器支持。注释者阅读的文本没有验证器，而这正是完成数据集中大部分不一致的来源。
references/writing-guidelines.md 涵盖了注释者对文本可以存在的四个界面（instructions 阶段、annotation_instructions 横幅、annotation_codebook_url 以及每个方案的 description）、标签定义必须包含什么才能解决争议、打破平局规则、包含边界情况的工作示例，以及根据试注释的差异迭代指南。examples/advanced/long-guidelines/ 是一个所有要素的完整工作模型。
有两件事需要正确完成，无需进一步阅读：
- 横幅不是代码本。
annotation_instructions位于每一页上。