claude-council

LLM Council

安装路径假设： 本技能假设安装在 ~/.claude/skills/claude-council/。如果安装在其他位置（例如 ~/.claude/plugins/<name>/skills/claude-council/），请相应调整步骤 0、2 和 10 中的脚本路径。

针对任何高风险决策，运用五种结构化思考视角、一轮同行评审、在共识过于一致时进行强制辩论，并由双主席综合结论，同时保留异议。每次运行都会记录到日志；结果会进入自我改进循环，随时间推移提出角色设定优化建议。

不适用： 查询事实、调试、单一领域的技术问题、快速判断是或否的决策、情感支持。如果没有哪个选项真的让你左右为难，就直接回答。

---

步骤 0 — 优先处理特殊调用

• /claude-council outcome <sha1> <note> — 在 ~/.claude/skills/claude-council/journal/council-log.jsonl 中按 sha1 前缀查找运行记录，更新其 outcome 字段并确认。完成。
• /claude-council meta — 运行 bash ~/.claude/skills/claude-council/scripts/meta_analysis.sh 并提供生成的修订文件路径。完成。
• 其他任何调用 → 继续步骤 1。

---

步骤 1 — 分流

如果满足以下任一条件，则拒绝并直接回答：

1. 事实类／只有一个正确答案（“法国的首都是哪里？”）
2. 单一领域的技术问题——称职的从业者发条推文就能解答
3. 未说明利害关系——通过 AskUserQuestion 询问一次“这件事为什么风险很高？”；如果用户不以为意，就不再进行评议
4. 二选一且答案显而易见（“周五把未经测试的代码部署到生产环境？”）
5. 已经做出决定，只是想寻求认可——询问：要挑战还是确认？如果是确认，则跳过
6. 以寻求情感支持的方式提出——友善地说明，不对此进行评议

---

步骤 2 — 运行前查询日志

为安全地通过 shell 传递原始问题，先将所有单引号替换为 '\''，再用单引号括起来。保存为 $ESCAPED_QUESTION。绝不要直接将原始用户文本传给 bash——问题中的 $(...)、反引号和 \ 序列会被执行。

bash ~/.claude/skills/claude-council/scripts/journal_search.sh "$ESCAPED_QUESTION"

如果有 ≥1 条既往运行记录在 sha1 前缀或关键词重叠方面匹配：显示一行摘要（“DATE 的相关评议——建议 X——结果：Y”），并将最多 2 条既往结论作为 “Prior council context” 注入整理后的问题。

---

步骤 3 — 整理问题 + 偏见审计

3a. 工作区扫描 — 搜索 CLAUDE.md、memory/ 和用户提及的任何文件。最多选择 3 个文件，按最近程度和 CLAUDE.md 优先级决定。将整理后的问题限制在约 4k tokens；如有截断，请在记录中注明。如果未找到 CLAUDE.md 或 memory/ 文件，请在记录中加入：“工作区扫描：未找到项目上下文。评议仅基于用户提供的上下文进行。”

如果问题含糊不清，通过 AskUserQuestion 澄清一次。然后生成 {{FRAMED_QUESTION}}：

DECISION: <core question>
CONTEXT: <workspace + user context>
STAKES: <what's at stake>
OPTIONS: <options named by user, if any>
PRIOR: <prior council context if any>

将完整的整理后问题文本保存为 shell 变量 FRAMED_QUESTION，供步骤 9 计算 SHA 时使用。转义文本中的单引号（' → '\''）。

3b. 偏见审计 — Quick 模式下跳过（不值得付出延迟成本；参见 references/modes.md）。Standard/Deep 模式下：使用 references/bias-audit.md 中的提示词进行一次 Agent() 调用。传入 {{FRAMED_QUESTION}}。接收结构化的偏见标记列表。将其附加到整理后的问题中：

BIAS FLAGS: <list — these are signals, not verdicts>

如果偏见审计返回“BIAS AUDIT: Clean — no significant distortions detected.”，则完全省略整理后问题中的 BIAS FLAGS: 部分。在 HTML 报告中，将 {{BIAS_FLAGS_HTML}} 渲染为空字符串。

---

步骤 4 — 选择模式

阅读 references/modes.md 了解完整的升级逻辑。摘要：

模式	适用情形	~调用次数
Quick	后缀为“quick”／利害关系 < $1k／可在 ≤ 1 天内逆转	4
Standard	默认	13–15
Deep	“deep”／高风险／因信心低而自动升级	16 + 1 Codex

---

第 5 步 — 扇出（并行 Agent 调用）

阅读 references/personas.md 中的全部五个角色提示词。在单轮中派发：

• Standard/Deep： 并行调用 5 个 Agent(subagent_type="general-purpose", description="<persona>", prompt=<persona_prompt with FRAMED_QUESTION substituted>)
• Quick： 3 位顾问（Red Team、Executor、First Principles）

Deep 模式增强： 对于 Deep 模式，在 First Principles 和 Expansionist 的提示词后追加：“完整返回全部三种重新框定的问题／选项，并分别给出完整推理，而不只是最强选项和次优选项。”

每个角色提示词都要求在响应末尾附上以下内容：

=== CONFIDENCE ===
confidence: high | medium | low
assumptions: <bulleted premises>
what_would_change_my_mind: <1-3 signals>
unknowns: <missing facts>

对于 Deep 模式，Codex 决策科学环节在顾问返回后运行（第 6 步）——而非并行运行——这样 Codex 就能评估顾问提出的选项，而不只是用户列出的选项。

---

第 6 步 — Codex 决策科学环节（Deep 模式／“with codex”）

阅读 references/decision-science.md。从 {{FRAMED_QUESTION}} 和顾问的响应中提取选项。

调用 Codex：

检测可用的超时命令；在原版 macOS 上优雅回退：

if command -v timeout >/dev/null 2>&1; then
  TIMEOUT_CMD="timeout 120"
elif command -v gtimeout >/dev/null 2>&1; then
  TIMEOUT_CMD="gtimeout 120"
else
  TIMEOUT_CMD=""
fi

if command -v codex >/dev/null 2>&1; then
  CODEX_OUTPUT=$(printf '%s' "$DECISION_SCIENCE_PROMPT" \
    | $TIMEOUT_CMD codex exec --sandbox read-only --skip-git-repo-check -) \
    || CODEX_OUTPUT=""
fi

安全说明： 提示词通过 stdin 使用 printf '%s' 传入，而不是使用 heredoc——这样可以避免 shell 展开提示词文本中的任何 $、反引号或元字符。协调器必须预先构建 $DECISION_SCIENCE_PROMPT shell 变量，其中包含完整的决策科学提示词（来自 references/decision-science.md），并已将 {{FRAMED_QUESTION}} 和 {{OPTIONS_LIST}} 替换为字面文本。

回退（Codex 不可用、超时或出错）：Agent(subagent_type="general-purpose", prompt=<decision-science prompt>)。将 CODEX_USED=false。如果 Codex 成功运行，则将 CODEX_USED=true。这些必须是字面量 JSON 布尔值 true 或 false（不能加引号）——第 10 步中的 --argjson 要求使用有效 JSON。

解析决策科学输出： 输出包含 JSON 块，后面跟着纯文本的 RANKING／DOMINATED／KEY ASSUMPTION 部分。通过匹配 { ... } 边界解析 JSON 块（该架构没有嵌套对象）。如果任何块的 JSON 解析失败，则捕获原始文本并在记录中呈现——不要因此中断讨论。纯文本部分位于最后一个 JSON 块之后。

---

步骤 7 — 匿名化 + 同行评审 + 强制辩论

7a. 匿名化 — 步骤：

1. 使用 $SHA 的前 4 个十六进制数字作为种子，生成随机的 A-E 排列（每个问题都保持确定性，可减少日志差异）。在记录中记下映射关系。
2. 如果某个回答的首行包含自我身份标识，则将其删除。
3. 结构性清理 — 使用正则表达式替换通过匿名文本泄露身份的角色特征模式：
   • THE FAILURE MODE / THE ROOT CAUSE / THE MISSED SIGNAL / THE ALTERNATIVE → POINT 1 / POINT 2 / POINT 3 / POINT 4
   • REFRAMING [ABC] → PERSPECTIVE [1/2/3]；STRONGEST: / RUNNER-UP: → PRIMARY: / SECONDARY:
   • OPTION [XYZ] → ALTERNATIVE [1/2/3]；DOMINANT: → RECOMMENDED:
   • FIELD: / NAIVE READ: / BUBBLE SPOTS: / CROSS-DOMAIN INSIGHT: → LENS: / INITIAL READ: / ASSUMPTIONS: / INSIGHT:
   • OODA STAGE → PHASE ASSESSMENT；RICE SCORING / RICE Score → PRIORITY SCORING / Priority Score；STATUS: DRAFT → NOTE: INCOMPLETE DATA
4. 保持 === CONFIDENCE === 区块不变（所有角色都使用此格式）。

7b. 同行评审（Standard/Deep） — 阅读 references/peer-review.md，了解完整的评审提示词。并行分发 5 次 Agent() 调用，每次都提供所有匿名化的 A–E 回答以及评审提示词。

分数提取： 每位评审者对 Q4 的回答必须是 1–5 之间的单个整数。使用正则表达式提取：CONSENSUS STRENGTH:\s*(\d)（不区分大小写）。如果评审者输出的值不是整数或超出范围，则默认为 3（中立），并在记录中记下警告。计算提取出的 5 个分数的算术平均值，四舍五入到小数点后一位。

共识摘要合成： 收集完同行评审后，生成一段 2–3 句的 CONSENSUS_SUMMARY，概括：(a) 多数顾问的建议；(b) 主导理由；(c) 各评审共同提出的条件或注意事项。将其存储为变量 $CONSENSUS_SUMMARY——该变量将替换 references/debate-round.md 中 Prosecutor 和 Defender 提示词内的内容。

7c. 强制辩论 — 如果共识强度平均值 ≥ 4.0（或始终处于 Deep 模式）：使用 references/debate-round.md 运行两次顺序执行的 Agent() 调用。如果 Standard 模式下平均值 > 2.0 且 < 4.0：跳过辩论（健康的分歧，无需施加对抗压力）。如果平均值 ≤ 2.0：跳过辩论，并在记录中注明：“Debate round skipped — insufficient consensus (score: X/5).”

1. Prosecutor — 对共识发起质疑。等待其回复。
2. Defender — 将 {{PROSECUTOR_RESPONSE}} 替换为 Prosecutor 的输出，然后分发。必须等 Prosecutor 返回后，Defender 才能运行。

阅读 references/debate-round.md，查看完整提示词。

---

步骤 8 — 双主席 + 异议保留

主席调度前取消匿名： 使用步骤 7a 中的 A-E 映射，为每个响应恢复角色标签。references/chairman.md 中的主席提示词要求输入带有角色标签（Red Team: ...、First Principles: ... 等）——使用原始（未匿名）响应文本，而不是经过净化处理的同行评审版本。

阅读 references/chairman.md。分两轮调用三次 Agent()：

A 轮（并行）： 在同一轮中调度两位主席：

1. Chairman-Consensus（偏向多数意见）——标准的 5 部分裁决
2. Chairman-Dissent（偏向少数意见）——结构相同，以异议为核心

B 轮（依次执行，在两位主席都返回后）： 3. 异议保留环节——接收两位主席的输出；生成异议清单（列出 2–5 条被共识主席弱化的见解）

最终裁决 = Chairman-Consensus 输出 + 附加的异议清单。

裁决标题必须为：

Council confidence: high | medium | low  (n/5 high, n/5 medium, n/5 low)
Dominant assumption: <single shared premise>
Breakers: <top 2 signals that flip the recommendation>

升级检查（仅限标准模式——深度模式不再升级）：

符合以下任一条件时触发升级：

• chairman_confidence 为 low
• 3 位或更多顾问给出的 confidence: low
• “理事会意见冲突之处”部分中，有 ≥2 项未能判定哪一方“更有说服力”

如果触发：AskUserQuestion — “理事会置信度较低（原因：{which trigger}）。是否切换到深度模式进行更彻底的分析？”

• 如果是：在深度模式下从步骤 5 重新运行，并将之前的顾问输出作为上下文传入，让顾问在此基础上完善，而不是重新开始。
• 如果否：继续使用标准裁决；在 HTML 报告中使用 confidence-low（红色）样式渲染置信度标题。
• 如果当前已是深度模式：不要再次升级。继续给出低置信度裁决，并突出说明。

---

步骤 9 — 生成输出

时间戳 + sha1：

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
FILE_TS=$(date -u +%Y%m%d-%H%M%SZ)
SHA=$(printf '%s' "$FRAMED_QUESTION" | shasum | cut -c1-8)

编排器必须将步骤 3 输出中的 FRAMED_QUESTION 设为 shell 变量。printf '%s' 可避免末尾换行影响哈希。-u 强制使用 UTC。FILE_TS 是适合文件名的变体；TS 是日志使用的 ISO 8601 格式。

文件名： council-report-${FILE_TS}-q${SHA}.html、council-transcript-${FILE_TS}-q${SHA}.md

输出目录： $PWD ——先测试写入权限。回退目录：~/Documents/claude-council-reports/

HTML 标记 → 源内容映射：

Token	来源	备注
{{TITLE}}	带框问题中 DECISION 行的前 80 个字符	对所有 <>&"' 字符进行 HTML 转义
{{TIMESTAMP}}	$TS（ISO 8601 UTC）
{{MODE_LABEL}}	"Quick" / "Standard" / "Deep"
{{MODE_CLASS}}	"quick" / "standard" / "deep"（CSS 使用的小写形式）
{{CODEX_BADGE_HTML}}	如果运行了 codex，则为 <span class="badge codex">Decision Science</span>；否则为空字符串
{{CONFIDENCE_HEADER_HTML}}	将结论置信度标题渲染为 <div class="confidence-block confidence-{level}">，包含 Council 置信度行、主导假设和推翻因素	使用 confidence-high、confidence-medium 或 confidence-low 类
{{QUESTION_HTML}}	完整的带框问题文本	对所有 <>&"' 字符进行 HTML 转义，以防止 XSS
{{BIAS_FLAGS_HTML}}	将偏见审计输出放入 <div class="bias-flags"><strong>Pre-council bias scan</strong>...</div>；如果模式为 Quick 或审计结果干净，则为空字符串
{{VERDICT_HTML}}	Chairman-Consensus 结论（markdown → HTML：## H2 → <h2>，- bullet → <ul><li>，段落 → <p>）
{{DISSENT_LEDGER_HTML}}	将异议项目符号放入 <div class="dissent-ledger"><strong>Dissent Ledger</strong><ul><li>...</li></ul></div>；如果结果干净或模式为 Quick，则为空
{{AGREEMENT_GRID_HTML}}	将“委员会一致之处”呈现为包含顾问意见一致情况的 <div class="card"> 和 <table class="grid-table">；如果模式为 Quick，则为空
{{RICE_TABLE_HTML}}	将执行者 RICE 分析呈现为 <div class="card"><div class="card-title">RICE Analysis</div><div class="card-body"><table class="rice-table">...</table></div></div>；如果没有 RICE 数据，则为空
{{DECISION_SCIENCE_MATRIX_HTML}}	将 Decision Science JSON 呈现为 <div class="card"><div class="card-title">Decision Science</div><div class="card-body"><table class="ds-table">...</table></div></div>；如果未运行，则为空	行类：主导项使用 dominant，受支配项使用 dominated
{{DEBATE_HTML}}	将辩论呈现为 <div class="card"><div class="card-title">Debate Round</div><div class="card-body"><div class="debate-callout">...</div></div></div>，包含控方和辩方；如果跳过，则为空
{{ADVISORS_HTML}}	将每位顾问呈现为 <details class="advisor-{kebab}"><summary>{Name} <span class="conf-{level}">{level}</span></summary><div class="detail-body">{text}</div></details>	kebab：red-team、first-principles、expansionist、outsider、executor
{{REVIEWS_HTML}}	将每份评审呈现为 <details><summary>Reviewer {N}</summary><div class="detail-body">{text}</div></details>；如果模式为 Quick，则为空
{{FOOTER_HTML}}	LLM Council &middot; Mode: {mode} &middot; SHA: {sha} &middot; <a href="{transcript_path}">Full transcript</a>

**HTML：**读取 assets/report-template.html，按照上表替换所有 token，然后写入文件。在 darwin 上使用 open <path> 打开。

**Transcript：**编写一个 markdown 文件，包含：调用时间戳、带框问题、匿名化映射、所有顾问的回复及其角色名称、所有同行评审、辩论记录（如果运行）、两份 chairman 输出、异议记录、完整结论、Decision Science 矩阵（如果运行）。

**HTML 清理说明：**表格中标记为“HTML 转义”的 token（TITLE、QUESTION_HTML）包含原始用户文本，必须对其中的 <>&"' 进行转义。其余 *_HTML token（VERDICT_HTML、ADVISORS_HTML、REVIEWS_HTML、DEBATE_HTML、BIAS_FLAGS_HTML、FOOTER_HTML）由编排器生成，属于安全内容，因为编排器使用受控模板构造这些内容，且绝不会直接插入原始用户文本。如果这些 token 中出现任何用户提供的文本（例如，结论中复述的问题），必须在插入该文本时进行 HTML 转义，而不是在 token 层级转义。

替换后，请验证：grep '{{' <html_path> 必须不返回任何匹配项。如果仍有 token 未填充，请将其替换为空字符串，并在 transcript 中记录警告。

---

第 10 步 — 追加日志 + 用户提示

根据本次运行中收集的值构建日志载荷。所有字段均为必填项：

{
  "ts": "$TS",
  "question_sha1_prefix": "$SHA",
  "mode": "<Quick|Standard|Deep — the mode actually used, including escalation>",
  "codex_used": <true if Decision Science ran via Codex; false otherwise>,
  "biases_flagged": [<list of bias names from Step 3b, or empty array if Quick/clean>],
  "advisors_confidence": {
    "red_team": "<high|medium|low from Red Team's CONFIDENCE block>",
    "first_principles": "<from First Principles>",
    "expansionist": "<from Expansionist>",
    "outsider": "<from Outsider>",
    "executor": "<from Executor>"
  },
  "chairman_confidence": "<high|medium|low from the verdict header>",
  "recommendation_one_liner": "<one sentence — the Recommendation section's first sentence>",
  "dissent_ledger": [<each DISSENT PRESERVED bullet as a string, or empty array if Clean>],
  "html_path": "<absolute path to the HTML report written in Step 9>",
  "transcript_path": "<absolute path to the transcript written in Step 9>",
  "outcome": null
}

将其构建为有效的 JSON 字符串。使用 jq -n 安全地构建（可处理建议文本中的引号和特殊字符）：

PAYLOAD=$(jq -n \
  --arg ts "$TS" \
  --arg sha "$SHA" \
  --arg mode "$MODE" \
  --argjson codex "$CODEX_USED" \
  --argjson biases "$BIASES_JSON" \
  --argjson conf "$ADVISORS_CONF_JSON" \
  --arg chair_conf "$CHAIRMAN_CONF" \
  --arg rec "$RECOMMENDATION" \
  --argjson dissent "$DISSENT_JSON" \
  --arg html "$HTML_PATH" \
  --arg transcript "$TRANSCRIPT_PATH" \
  '{ts:$ts, question_sha1_prefix:$sha, mode:$mode, codex_used:$codex,
    biases_flagged:$biases, advisors_confidence:$conf,
    chairman_confidence:$chair_conf, recommendation_one_liner:$rec,
    dissent_ledger:$dissent, html_path:$html, transcript_path:$transcript,
    outcome:null}')
bash ~/.claude/skills/claude-council/scripts/journal_append.sh "$PAYLOAD"

其中，Shell 变量根据本次运行的输出设置：

• $TS、$SHA — 来自第 9 步
• $MODE — "Quick"、"Standard" 或 "Deep"
• $CODEX_USED — true 或 false（JSON 布尔值，不带引号）
• $BIASES_JSON — JSON 数组，例如 '["anchoring","sunk cost"]' 或 '[]'
• $ADVISORS_CONF_JSON — JSON 对象，例如 '{"red_team":"high","first_principles":"medium","expansionist":"high","outsider":"low","executor":"medium"}'
• $CHAIRMAN_CONF — "high"、"medium" 或 "low"
• $RECOMMENDATION — Recommendation 部分的第一句话
• $DISSENT_JSON — 异议条目的 JSON 数组，或 '[]'
• $HTML_PATH、$TRANSCRIPT_PATH — 第 9 步中的绝对路径

告诉用户："已记录委员会讨论（sha：$SHA）。要记录结果：/claude-council outcome $SHA <short note>。运行 /claude-council meta，在运行 5 次以上后获取角色优化建议（需要 jq）。"

然后显示 HTML 文件路径，并用一个段落概述对话内容（建议 + 首先要做的一件事）。不要再写其他内容。