mark-hallam/multi-evaluator

多评审员设计改进循环

多轮独立评审，直到产品 可供用户使用：每个旅程从每位评审员处获得 9 分或更高，无高严重性未修复问题，评审员之间意见分歧不超过 1 分，并且此状态已连续保持两轮。一致给出 10 分是提示需要重新审视需求，而不是目标。AI 评分是强有力的信号而非最终证明：当循环判定“准备就绪”后，应由真实的首次用户进行测试；如果他们与 AI 意见不一致，则以用户意见为准。

所有操作都通过一个命令行工具 scripts/eval_loop.py（位于此文件旁边）完成，因此无论执行者是人、当前代理还是其他任何代理，结果都是一致的。每个命令都接受 --dir <review folder> 参数，并且 status --json 总是会报告当前循环状态以及下一步操作。需要 Python 3.9 或更高版本、Node.js 18 或更高版本以及 Google Chrome 或 Chromium。无需安装其他依赖。

以下内容中，LOOP 代表 python3 <此技能所在文件夹>/scripts/eval_loop.py。

开始之前（所有 mStack 技能通用）

• 如果 ~/.mstack/config.json 在 "disabled" 下列出了 multi-evaluator，或者对方要求此任务不使用该技能，则按常规方式工作。
• 如果存在 ~/.mstack/learned/multi-evaluator.md，请阅读它：其中包含此人已接受的改进，其优先级高于本文件。
• 当循环结束（或停止）时，私下记录其执行情况： python3 <mstack 技能文件夹>/scripts/mstack.py log multi-evaluator --outcome reached|partial|not-reached --needed-user "..." --stalled "..." （mstack 技能位于此技能旁边）。

1. 首先确定旅程和评审标准

在任何评审之前，必须与此人达成一致，确定一个真实用户必须能够完成的端到端任务。

1. LOOP init --dir design-review --name "<product>" --start "<启动产品及其端口的命令，其中 {port} 会被替换>" --cwd <产品文件夹> （对于已运行的实例，例如一个预发布站点，则使用 --url <address>）。
2. 与此人一起填写 design-review/mstack-eval.json。每个字段的详细说明请参考 references/config.md：
   • about 和 persona：描述产品是什么以及由谁评判。将设计方向和任何约束条件放在 rules 中，而不是 about 里：它们会作为“不计分”项展示给评审员，确保需求说明不会预先引导出你希望听到的答案。
   • journeys：3 到 6 个真实的端到端任务（例如“添加一本书并在列表中看到它”）。
   • views：每轮捕获的固定截图（桌面端、手机端、深色主题）。浅色主题排第一。
   • criteria：基础标准是清晰、快捷、可信、熟悉、冷静、通用。随着产品成熟，stages 可添加更多标准（使用价值时间、错误恢复、文案、代理体验、可测量的可访问性、速度、五秒测试、情绪基调、一致性、数据安全性、愉悦感）。当评分显示基础标准已满足时，可通过 "active": true 或 "from_round": <n> 开启某个阶段。
   • reviewers：至少两个，来自不同的 AI 制造商。默认是 Claude（由你，即代理，运行）和 Codex（由工具通过 codex exec 运行）。
   • control：噪声检查（推荐）。第一轮捕获会将该轮的截图冻结在 control/ 目录中；每位评审员在每一轮都会作为旅程 control 对其评分，报告会显示该分数的变化幅度。小于此变化幅度的得分变动被认为是噪声而非实际进步。
3. 在开始第一轮之前，向对方展示旅程和评审标准并获得肯定答案。

2. 每一轮

LOOP start-round --dir design-review          # 创建 rounds/r<N>/ 目录，快照本轮评审标准
                                              # 编写 rounds/r<N>/changes.md：记录改了哪些内容，每个要点一行
LOOP capture --dir design-review              # 以相同方式、捕获相同的截图，每轮如此
LOOP brief --dir design-review                # 在 rounds/r<N>/briefs/ 生成盲评简介，从第二轮起还生成 -compare 简介
LOOP review --dir design-review               # 并行运行命令行评审员（如 Codex）；建议在后台运行

同时，自行以 全新上下文 运行每个 kind 为 agent 的评审员：

• Claude Code：启动一个子代理（Agent 工具，通用类型），其提示词为 rounds/r<N>/briefs/claude.md 的完整文本。不要加入你自己的看法、预期的答案或之前的评分。
• 任何其他代理：打开一个新的会话或线程，将该简介作为唯一的指令。
• 评审员类型为 chat（可选，需选择加入：例如 Gemini 或 ChatGPT，使用对方自己已登录的浏览器，无需 API 密钥）：仅当对方同意分享内容后，打开一个新的私密聊天，粘贴 rounds/r<N>/briefs/<id>.md，如果产品不公开则上传本轮固定截图，保存回复，关闭标签页，然后执行 verdict。这类评审员看到的是截图而非真实产品，因此仅作为平局仲裁员：它不计入“可供用户测试”状态，且永远不能作为唯一的评审员。

当评审员回复后，保存其 JSON（工具会校验回复，不符合格式的将被拒绝）：

LOOP verdict --dir design-review --reviewer claude reply.json      # 或者通过管道 - 输入回复

先盲评，后对比。 评分简介只显示本轮内容：没有之前的截图、没有之前的分数、没有设计方向，这样才能确保第一轮和第九轮的评分含义相同。从第二轮起，还会生成 rounds/r<N>/briefs/<reviewer>-compare.md。在评分 verdict 保存之后，将其提供给同一评审员（同一会话即可，此时已非盲评），并单独保存回复：

LOOP verdict --dir design-review --reviewer claude --compare compare-reply.json
LOOP report --dir design-review                                     # 在 design-review/report.html 生成报告

对比结果不会改变评分；报告会在“有何变化”部分展示对比分析。

然后向对方展示报告和浅色主题截图（rounds/r<N>/shots/）。如果你的代理支持发送通知（在 Claude Code 中可使用 PushNotification），在一轮报告就绪或循环需要决策时通知对方；配置文件中的 notify 命令也可发送通知（详见 references/config.md）。

3. 修复，然后重复

1. 从报告的 接下来要做的事 列表开始修复（优先修复每位评审员都标记的旅程问题，其次是高严重性问题，然后是“修复后”预估分提升最大的项目）。如果旅程表格显示不同评审员对同一旅程的分歧达到或超过 2 分，在依据任何一方的评分行动之前，请自行检查该旅程。
2. 修改产品代码，运行其自身测试，并编写下一轮的 changes.md。
3. LOOP start-round，然后重复，直到 LOOP status 显示 可供用户测试（即上述停止规则已连续保持两轮）。如果某一轮通过了，不进行大的更改，再运行一轮以确认状态稳定。如果经过 max_rounds（默认 6 轮）仍未达成，status 会指示停止并与对方沟通：可能旅​​程或标准的要求超出了产品应有的范围。
4. 随后进行真人测试：五名首次用户尝试完成这些旅程，无人辅助。记录他们的用时、遇到的障碍以及口头反馈，记录在 rounds/r<N>/people.md 中（每个用户一条记录；报告会展示这些信息）。当真人测试结果与 AI 评审员意见不同时，以真人意见为准：将其发现转化为下一轮的新旅程或新标准。

规则

• 评审员在评分期间不得互相查看对方的 verdict、之前的轮次、之前的分数或报告；简介会明确告知他们这一点。与上一轮的对比是单独的环节，在 verdict 提交之后进行。
• 每轮以相同方式捕获相同视图，确保前后对比具有可比性。
• 绝不允许评审员提交真实的支付、消息或个人数据。请使用演示数据和全新副本。
• 沙盒化评审员（如 Codex）无法启动 Chrome：review 命令会启动一个共享的无头 Chrome，简介会指示它们在驱动命令前加上 MSTACK_CDP_PORT=<port>。
• 如果评审员的回复不符合格式要求，请读取 rounds/r<N>/work/<reviewer>/raw-reply.txt 的内容，然后重新运行。如果评审员给出 10 分但仍提出修复建议，工具会拒绝该回复；同样，如果“修复后”预估分低于当前评分，也会被拒绝。
• 将评审文件夹放置在产品仓库内（或旁边），以确保每一轮的数据都得到保存。

文件

• scripts/eval_loop.py：命令行工具（包含 init, status, start-round, capture, brief, serve, review, verdict, validate, report, notify 等子命令）。
• scripts/drive.mjs：旅程驱动器，使用真实的无头 Chrome；评审员通过它直接操作。
• scripts/report.py：报告生成器。scripts/readiness.py：停止规则和噪声检查实现。
• templates/mstack-eval.json：起始配置文件模板。
• references/config.md：所有配置字段说明。references/verdict-format.md：回复格式说明。references/method.md：解释为何采用此循环机制以及标准如何迭代增长。