设计辩论 是做什么的?
你是编排者。你构建问题框架,等待用户批准,然后运行设计师和评判员作为子智能体,并撰写一份提案。你绝不允许子智能体写入仓库,也绝不提交。
参考文献,均已打包:
- @./references/lenses.md — 视角简介及可选菜单
- @./references/models.md — 每个槽位的模型系列、后备方案、评判员规则、每个工作流的努力级别
- @./references/prompts.md — 每个子智能体的提示及其必需标题
- @./references/proposal-template.md — 提案模板
需要子智能体工具
辩论依赖于设计师在独立上下文中独立工作。检查是否存在能生成带有自身提示的子智能体的工具(Copilot 中的 task,Claude Code 中的 Task,或其他客户端中的等价工具)。如果没有,则停止并说明此技能无法在此客户端运行。绝不要在你的上下文中模拟设计师:他们不会是独立的。
调用和默认值
design-debate <问题> [designers=3] [rounds=2] [lenses=a,b,c] [models=A:x,B:y]
[effort=high] [judge-model=x] [judge-effort=x] [slug=x]
design-debate resume <slug>
design-debate status <slug>
接受用自然语言表达的相同设置(“使用4个设计师,低努力级别”、“辩论直到他们达成一致”)。
| 设置 | 默认值 | 允许值 | 超出范围时 |
|---|---|---|---|
designers (N) | 3 | 2–5 | 钳制到最近边界 |
rounds (R) | 2 | 从1开始的整数,无上限,或 auto(见自动轮次) | 小于1:使用1 |
lenses | pragmatist, domain-architecture, operations-runtime | lenses.md 中的名称,或自由文本;一个视角可重复 | 使用自由文本作为简介;视角数少于N:先用默认值填充,然后从菜单中选择 |
models | 每个槽位的家族偏好(models.md) | 每个槽位的ID或家族 | 应用 models.md 中的后备方案 |
effort | high | low, medium, high, xhigh;全局或每个槽位 | 工作流无法设置:“not applied” |
judge-model | 最强模型,来自没有设计师使用的家族 | 模型ID | models.md 后备方案 |
judge-effort | 与 effort 相同 | 同 effort | 同 effort |
slug | 从问题的kebab-case形式,最多6个单词 | kebab-case | 转换为slug格式 |
在检查点列出每一个钳制、后备和“not applied”。绝不静默丢弃设置。
计划调用次数为 N + N×R + 1(设计、辩论轮次、评判员),加上最多N次修复调用(仅针对最终设计有缺失的情况,见完整性)和1次共享重试:默认情况下计划10次(所有修复时13次)。没有上限:检查点会显示计数,批准检查点即批准该计数。当 rounds=auto 时,计数事先未知:显示到第一轮结束时的调用次数(2N + 1,包括评判员)以及每增加一轮的 N 次调用。
默认值文件
调用时未给出的设置按以下优先级(从高到低)从以下位置获取:
- 调用参数;
- 仓库根目录下的
design-debate.json,针对项目; ${XDG_CONFIG_HOME:-~/.config}/design-debate/config.json,针对用户;- 上表中的默认值。
每个文件是一个JSON对象,其键为上述设置名称。两个文件都是可选的,较高优先级文件中的键会完全替换较低优先级文件中的相同键(models 对象或 lenses 列表不合并)。slug 是每次运行独有的,因此不会从文件中读取。
{
"designers": 3,
"rounds": "auto",
"lenses": ["pragmatist", "domain-architecture", "operations-runtime"],
"models": { "A": "opus", "B": "sonnet" },
"effort": "high",
"judge-model": "opus",
"judge-effort": "xhigh"
}
文件中的值会像调用时给出的值一样进行检查,并应用相同的超出范围规则。不是JSON对象的文件会被整体忽略。未知键或 slug 会被忽略。两者都在检查点列出,因此任何拼写错误都不会静默通过。仅在预检和恢复时读取文件:运行中途更改的文件在 resume 之前不会影响任何内容,resume 则会回到检查点(审批行不同)。
自动轮次
当 rounds=auto 时,运行辩论轮次直到没有设计再发生变化:
- 每轮结束后,将每个设计师的
## Key decisions与其自身之前的设计(第一轮为草案)逐条比较,忽略顺序和周围空白。 - 收敛: 每个设计师的要点与其之前的设计相同。将
converged: round-<k>追加到run.md,并以第k轮作为最终轮次进入完整性检查。 - 循环: 未收敛,但每个设计师的要点与其自身较早的设计之一匹配。再增加一轮只会重复辩论。追加
cycled: round-<k>并视为收敛。 - 否则运行下一轮。
每个自动轮次都携带最终设计说明(prompts.md),因为任何一轮都可能是最后一轮。设计师永远不会收敛的运行会继续进行;用户可以停止它,resume 会从下一轮继续。报告运行了多少轮以及它们结束的原因。
运行状态
将状态保存在工作树之外,位于 $(git rev-parse --absolute-git-dir)/design-debate/<slug>/。它能在新会话中存活,永远不会出现在 git status 中,并且是每个工作树独立的。
run.md 设置表、审批行、调度日志、重试行、状态
framing.md
drafts/<slot>.md 槽位为 A..E
round-<k>/<slot>.md 每轮一个文件夹,从 round-1 开始
completeness.md 由编排器编写,而非子智能体
repair/<slot>.md 仅针对需要修复的槽位
judge.md
run.md 行,按发生顺序追加:
approval: <hash>|N=<n>|R=<r or auto>|<slot:lens:model:effort,...>|judge=<model:effort>,其中<hash>是git hash-object framing.mddispatch: <stage>/<slot> <ISO time>,在每次子智能体生成前写入labels: <stage>/<reader> P=<slot>,Q=<slot>,...,在每轮或评判员生成前写入(见同行标签)retry-used: <stage>/<slot>converged: round-<k>或cycled: round-<k>,仅当rounds=auto时(见自动轮次)proposal: <仓库相对路径>,提案文件存在后立即写入status: <framing|approved|design|round-<k>|completeness|judge|written|validated|written-unvalidated|stopped:<reason>>
同行标签
设计师和评判员永远不会看到其他设计的槽位字母。使用同行标签 P, Q, R, S, T 展示设计,每个读者随机打乱,因此标签永远不会被误认为是槽位。
- 在每轮或评判员生成前,将该读者的映射追加到
run.md,例如labels: round-1/A P=C,Q=B或labels: judge P=B,Q=A,R=C。 - 在存储或转发每条批评之前,使用该行将其映射回其槽位。第一轮之后的每一轮,每个设计师都会收到上一轮针对其自身槽位的批评,这些批评会重新标记为该设计师的新映射。 评判员的批评和处置会被重新标记为评判员的映射。
- 在填充提案之前,使用评判员的
labels:行将评判员的获胜者和嫁接点映射回槽位。在恢复时,始终使用记录的行;切勿重新打乱已完成的阶段。
阶段文件仅在具有 prompts.md 为该阶段要求的每个标题时才有效。
阶段
- 预检。
- 确定仓库根目录。
- 将基线签名(见安全中的变异检查)记录到
run.md中。 - 检测工作流并读取子智能体工具的实时模型列表。
- 从调用参数和默认值文件解析设置(见默认值文件)。
- 如果该 slug 的状态文件夹已存在,则不要在其上启动新运行。以纯文本说明其状态和
resume <slug>命令,并结束你的回合。切勿通过 ask-user 或 question 工具提供此选项。 - 注意
docs/working/proposals/是否存在。
- 构建框架。 你自行编写
framing.md,不使用子智能体,遵循 prompts.md 中的 Framer 检查清单。使用解析后的设置和status: framing写入run.md。 - 检查点。 见下文。这是唯一的人工暂停点。
- 设计。 使用 Designer 提示并行生成 N 个设计师,每个使用其槽位的视角、模型和努力级别。首先记录每个调度。将每个有效回复保存到
drafts/<slot>.md。运行变异检查。 - 辩论。 按顺序一轮一轮地运行。每轮保存到
round-<k>/,并在每轮后运行变异检查。- 第1轮:每个设计师获得其自己的草案以及所有同行在打乱标签下的内容。
- 第2轮到第R轮,或者当
rounds=auto时直到它们收敛(见自动轮次):使用反驳提示,提供每个设计师的第k−1轮设计、第k−1轮针对它的批评以及其同行的第k−1轮设计。 - 最后一轮携带最终设计说明(prompts.md);当
rounds=auto时,每一轮都携带。
- 完整性。 见完整性。写入
completeness.md,运行任何修复,如果生成了修复则运行变异检查。 - 评判。 使用评判员提示生成评判员:最终设计在打乱后的同行标签下,加上所有批评和处置,以及
completeness.md中仍然存在的缺失项,重新标记为评判员的映射。保存到judge.md。运行变异检查。 - 编写。
- 将 proposal-template.md 填充到
docs/working/proposals/YYYY-MM-DD-<slug>.md,如果需要则创建文件夹。你自行根据评判员每个标准的分数计算所有设计的计分卡总计,包括标记为不合格的设计。 绝不覆盖:如果路径存在,则使用-2、-3等。立即将proposal: <path>和status: written追加到run.md。如果run.md已有proposal:行,则不要写入新文件:在该文件中就地重新验证和修复。 - 验证:
- 如果存在,运行
python3 .github/scripts/docs/check_integrity.py。 - 检查提案中的每个相对链接和每个
path:line引用是否都能解析。完整性检查器会跳过docs/working/。 - 检查是否至少有2个 mermaid 代码块。
- 如果存在,运行
- 设置
status: validated,或status: written-unvalidated并列出失败项。 - 运行最终的变异检查,该检查允许一个提案文件。
- 将 proposal-template.md 填充到
- 报告。 见报告。
完整性
评判员只读取每个设计师的最终设计:针对最后运行的轮次的 round-<k>/<slot>.md。一个在早期草案中回答了某个项目但最终文本中将其删除的设计,视为未回答该项目。在评判员之前进行检查,以便修复缺失项而不是决定结果。
- 对于每个槽位,读取最终设计的
## Framing answers,并检查其是否对framing.md中的每个需求(R1、R2、…)和开放问题(Q1、Q2、…)都有条目,并且每个条目都有实质性内容,而不是“见上文”或“未更改”。 - 写入
completeness.md:一个表格,每行对应一个框架项目,每列对应一个槽位,每个单元格为ok或missing。一个槽位的开放缺失项是它的missing单元格。 - 对于每个有缺失项的槽位,记录
dispatch: repair/<slot>并并行生成一个修复提示(prompts.md),使用该槽位的模型和努力级别。没有同行设计,因此没有labels:行。 - 仅当回复具有 prompts.md 要求的每个标题并且逐字保留了每个较早的
## Key decisions要点时,修复才被接受。将接受的回复保存到repair/<slot>.md;它成为该槽位的最终设计。否则保留最后一轮的设计并在表格下注明repair rejected: <reason>。 - 重新检查已接受的修复并更新表格。绝不发送第二次修复。
修复是尽力而为的,不属于共享重试。失败、无效或被拒绝的修复绝不使用重试,也绝不停止运行:评判员会对此缺失项进行评分(prompts.md,评判员)。在恢复时,一个没有文件的 repair/<slot> 调度会像任何不确定的调用一样重新运行一次。
检查点(硬停止)
显示检查点,然后结束你的回合。
- 审批是来自用户的明确新消息:
approve,或一个或多个edit回复后跟approve。 - 绝不要通过 ask-user、question 或 confirmation 工具请求审批。在自动驾驶或无人值守模式下,这些工具会自动回答,这将跳过唯一的人工关卡。
- 静默、超时、自动回复或“自行继续”的指令不视为审批。在自动驾驶模式下,无论如何都在检查点停止并说明原因。
检查点消息包含:
framing.md和状态文件夹作为可点击链接(见链接输出),附带3–5行的框架摘要。- slug 和提案路径。说明
docs/working/proposals/是否会被创建。 - 一个槽位表,包含每个的视角、请求的模型、解析后的模型、努力级别和后备说明,以及评判员。
- N、R、计划调用次数(
N + N×R + 1,或者对于rounds=auto为到第一轮为止的调用次数以及每增加一轮的N次调用),最多N次修复调用和1次重试。 - 每个钳制、后备和“not applied”设置,读取了哪些默认值文件,哪些设置来自它们,以及每个被忽略的文件或键。
- 回复形式:
approve、edit <setting>=<value>(例如edit rounds=1)、edit framing(用户编辑文件,然后回复approve)和cancel。
批准后,将审批行追加到 run.md 并设置 status: approved。任何编辑后,重新显示检查点。取消后,追加 status: stopped:cancelled 并结束。
链接输出
你交给用户的每个文件都是一个可点击的链接,而不是需要用户自己找到的裸路径:检查点处的 framing.md、报告中的提案以及状态文件夹。
- 如果客户端具有将文件发布或附加到聊天的工具,请使用它。
- 否则使用绝对路径写入一个 Markdown 链接:
[proposal](file:///abs/path.md)。
恢复和状态
design-debate status <slug> 读取 run.md 并将每个阶段列为已完成、缺失或不确定。
design-debate resume <slug>:
- 根据当前的
framing.md和设置(包括默认值文件)重新计算审批行。如果与记录的不同,或者没有记录,则返回检查点。” }```