deep-execution

Agent 增强型委员会执行

运行一个由多个并行 Claude 分析师 Agent 组成的工作流，进行更深入的分析。每位分析师都会查询其提供方、评估回复质量、可以提出后续问题，并返回结构化分析；工作流会强制要求其符合架构。

步骤 1：解析提供方并编写问题

一次 shell 调用即可解析工作流所需的信息——每个提供方的模型、角色和要发送的问题文件——使用的辅助工具与标准流程相同。将最终问题原样粘贴到 heredoc 中：带引号的标记意味着 shell 不会解析其中的引号、反引号或 $()。 问题只会输出一次；每个提供方注入角色后的版本会在 shell 中构建，无需再次粘贴。

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/providers.sh"
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/roles.sh"
PROVIDERS=(<the selected providers, space separated>)
ROLES="<the --roles value, or empty>"
RUN=$(date +%s)                                  # names this run's files; Step 6 reuses it
Q="$PWD/.claude/council-cache/.agents-$RUN"
mkdir -p "$PWD/.claude/council-cache"
# Self-ignoring, as cache.sh and run-council.sh keep it: these files carry the
# question and any --file contents, and must never land in a commit.
[[ -f "$PWD/.claude/council-cache/.gitignore" ]] || printf '*\n' > "$PWD/.claude/council-cache/.gitignore"
cat > "$Q.txt" <<'COUNCIL_Q_EOF'
<the question, verbatim>
COUNCIL_Q_EOF
# --file / auto-context: append the context to the question file here, e.g.
#   { printf '\n\nHere is the content of %s:\n\n```\n' "<path>"; cat "<path>"; printf '```\n'; } >> "$Q.txt"
# An unknown role is refused, as the standard flow refuses it; assigning it
# would hand that provider the bare question under a role heading.
[[ -z "$ROLES" ]] || validate_roles "$ROLES" || exit 1
# The model the ANALYST agents run on — distinct from the provider models below,
# which are what actually answer the question. Pinned rather than inherited: an
# omitted model makes every analyst run on whatever model the user's session
# happens to use, so the cost of a mode that already fans out one agent per
# provider varies by a factor of several for no stated reason. Sonnet handles
# the analyst's work — run a query, judge the answer, emit a structured object.
ANALYST_MODEL="${COUNCIL_AGENT_MODEL:-sonnet}"
case "$ANALYST_MODEL" in
    sonnet|opus|haiku|fable) ;;
    *) echo "COUNCIL_AGENT_MODEL must be one of: sonnet, opus, haiku, fable (got '$ANALYST_MODEL')" >&2; exit 1 ;;
esac
echo "analyst model $ANALYST_MODEL"
ASSIGNMENTS=""
[[ -n "$ROLES" ]] && ASSIGNMENTS=$(assign_roles_to_providers "$ROLES" "${PROVIDERS[@]}")
echo "run $RUN"
for p in "${PROVIDERS[@]}"; do
    role=""
    [[ -n "$ASSIGNMENTS" ]] && role=$(get_provider_role "$p" "$ASSIGNMENTS")
    qf="$Q.txt"
    if [[ -n "$role" ]]; then
        qf="$Q-$p.txt"
        build_prompt_with_role "$(cat "$Q.txt")" "$role" > "$qf"
    fi
    printf '%s\t%s\t%s\n' "$p" "$(get_model "$p")" "$qf"
done

它会先打印运行 ID，再打印分析师模型，最后为每个提供方打印一行：名称、模型（显示在步骤 4 的标题中）以及该提供方问题文件的绝对路径。将分析师模型作为 analystModel 传给工作流；工作流脚本无法自行读取环境变量。

步骤 2：运行分析师工作流

Agent 模式是一个工作流：每个提供方对应一个分析师 Agent，并行运行，每位分析师都通过受架构强制约束的结构化输出返回分析结果。用户选择了 Agent 模式（--agents，或在 ask.md 步骤 1.5 的提示中选择 yes）；这是 Workflow 工具要求的显式选择。

如果此会话中无法使用 Workflow 工具，请在此处停止：告知用户 --agents 需要配备 Workflow 工具的 Claude Code，并提出改为标准模式运行相同问题。不要改用其他方式启动 Agent。

使用 Read 工具读取 ${CLAUDE_PLUGIN_ROOT}/schemas/agent-analysis.schema.json，然后通过 script 调用 Workflow 工具，脚本内容如下，必须原样使用：

export const meta = {
  name: 'council-agents',
  description: 'One analyst per council provider: query it, judge the answer, follow up, return a structured analysis',
  phases: [{ title: 'Analyze', detail: 'one analyst agent per provider, in parallel' }],
}
// The tool's schema validator does not know the draft-2020-12 dialect the
// file declares; without the declaration it validates the same keywords fine.
const schema = { ...args.schema }
delete schema.$schema
const template = `${args.pluginRoot}/skills/deep-execution/agent-prompt-template.md`
// Single stage: there is no later step for a finished analyst to move on to,
// so the barrier costs nothing.
const results = await parallel(args.providers.map(p => () =>
  agent(
    `You are the council analyst for the provider "${p.name}".\n` +
    `Read ${template} and carry out every step in it, with these values:\n` +
    `- {PROVIDER} = ${p.name}\n` +
    `- {PLUGIN_ROOT} = ${args.pluginRoot}\n` +
    `- {QUESTION_FILE} = ${p.questionFile}\n` +
    `Your final answer is the Round 3 analysis object, returned through the structured output tool.`,
    { label: p.name, phase: 'Analyze', schema, agentType: 'general-purpose',
      model: args.analystModel })))
// parallel() keeps a dead or skipped analyst's slot as null, index-aligned with args.providers.
const failed = args.providers.filter((_, i) => !results[i]).map(p => p.name)
if (failed.length) log(`no analysis from: ${failed.join(', ')}`)
return {
  // The label goes last so an analyst that emits its own "provider" key cannot rename itself.
  analyses: results.map((a, i) => a && { ...a, provider: args.providers[i].name }).filter(Boolean),
  failed,
}

并传入以下 args（实际 JSON 值，而非字符串；pluginRoot 是 ${CLAUDE_PLUGIN_ROOT} 的实际路径，questionFile 是步骤 1 打印的路径）：

{
  "pluginRoot": "<CLAUDE_PLUGIN_ROOT>",
  "analystModel": "<the model Step 1 printed>",
  "schema": { "...the parsed schema file..." },
  "providers": [
    { "name": "gemini", "questionFile": "<absolute path from Step 1>" }
  ]
}

工作流会返回 { analyses, failed }。analyses 中的每个对象都符合架构；failed 列出分析师已退出或被跳过的提供方。返回错误的提供方不会列入 failed：其分析师会按照模板要求，将错误文本作为 full_response，并返回 quality: poor、confidence: low 的分析。步骤 5 会将这两种情况同等处理——均视为未作答的提供方。

步骤 3：读取结果

无需验证：在步骤 4 至 5 中直接使用每项分析的字段，并将 failed 纳入步骤 5 的提供方失败名单。

步骤 4：展示结果

按以下格式展示每项分析。{MODEL} 是步骤 1 中的模型：分析师内部因模型回退而重新运行时，不会更改此标题；模型替换情况只会在分析文本中体现。

## {EMOJI} {PROVIDER} ({MODEL}) — Agent Analysis

**Quality**: {quality} | **Confidence**: {confidence} | **Retried**: {retried}

### Key Recommendations
{recommendations}

### Unique Perspective
{unique_perspective}

### Blind Spots
{blind_spots}

---

<details>
<summary>Full {PROVIDER} Response</summary>

{full_response}

</details>

提供方表情符号（始终使用表情符号 + 空格）：

• 🟦 Gemini
• 🔳 OpenAI
• 🟥 Grok
• 🟩 Perplexity

步骤 5：增强综合分析

基于预先分析的回复，生成比标准模式更丰富的综合分析。${CLAUDE_PLUGIN_ROOT}/prompts/synthesis.md 中的校准规则同样适用于此处。其中“返回错误”的情况包括 failed 中的提供方，以及所有 quality: poor 且 full_response 为提供方错误的分析：将这些提供方列入失败名单，并排除在共识之外，不论其 confidence 字段会赋予多大权重。

置信度加权共识

根据各提供方的置信度，对其观点一致程度进行加权。高置信度的一致比低置信度的一致更有说服力——但这只适用于推理，绝不适用于前提。每个提供方读到的都是同一段系统描述，而他们都无法检查该系统；因此，信心十足的一致也可能意味着问题中有某个断言是错误的，而每个提供方都正确地基于该断言进行了推理。如果广泛一致且置信度高，请明确指出这一点，然后说明整个回答所依赖的前提，以及是否有人有条件核实该前提。

盲点分析

将各提供方的盲点与其他提供方的建议交叉比对。 标出没有任何提供方考虑到的风险。

分歧及背景

如果各提供方意见不一，请说明它们可能产生分歧的原因（假设不同、 优化目标不同、风险容忍度不同）。

建议

综合得出最优方案，并注明哪些提供方支持该方案及其置信度。

第 6 步：保存输出

将完整输出（所有提供方的分析和综合结论）保存到 .claude/council-cache/council-agents-{RUN}.md，其中 RUN 为第 1 步打印的运行 ID（该目录已在第 1 步创建）。然后删除本次运行的 问题文件，这些文件不会被清理：

rm -f .claude/council-cache/.agents-{RUN}*

告诉用户：

---

完整的 Agent 分析已保存到 .claude/council-cache/council-agents-{RUN}.md

错误处理

• 如果某个提供方的分析器失败（它会列在 failed 中），请说明并继续处理其他提供方
• 如果所有分析器都失败，请明确报告，并建议切换回标准模式
• 如果只选择了一个提供方且其分析器失败，请建议不使用 --agents 重试
• 如果工作流被终止或中断，可以恢复：使用相同参数以及工具结果中的 scriptPath 和 resumeFromRunId 重新启动；已完成的分析器会从缓存中返回