counselors

顾问 — 多 Agent 审查技能

将提示词并行发送给多个 AI 编码 Agent，并综合它们的回复。

参数：$ARGUMENTS

如果未提供参数，询问用户想要审查什么。

---

阶段 1：收集上下文

解析 $ARGUMENTS，了解用户想要审查的内容。然后自动收集相关上下文：

1. 提示词中提及的文件：使用 Glob/Grep 查找按名称、类、函数或关键词引用的文件
2. 近期更改：运行 git diff HEAD 和 git diff --staged，获取近期工作内容
3. 相关代码：搜索提示词中的关键术语，并阅读最相关的文件（最多 5 个文件，总量上限约为 50KB）

谨慎筛选，不要倾倒整个代码库的内容。挑选最相关的代码片段。

---

阶段 1b：Context7 过时情况扫描

从 package.json、CLAUDE.md、tsconfig.json 或配置文件中检测项目的关键技术（如果阶段 1 的上下文中尚不明确）。针对最多 5 个关键库或框架：

1. mcp__plugin_compound-engineering_context7__resolve-library-id — 获取 Context7 库 ID
2. mcp__plugin_compound-engineering_context7__query-docs — 获取 2–3 个相关片段，重点关注 API、配置和破坏性更改

限制：

• 参考文档总量上限约为 8,000 个 token。若超出，则删减相关性最低的片段。
• 如果在 Context7 中找不到某个库：在 REFERENCE DOCUMENTATION 区块中添加一行，例如 [library name]（未验证文档），然后继续。
• 如果无法从上下文中识别出具体库：完全跳过此阶段。

构建一个 REFERENCE DOCUMENTATION 区块，每个条目包含库名称和版本。此区块将包含在提示词中（阶段 3），以便审查者标记过时的用法。

---

阶段 2：选择 Agent

默认 Agent： or-claude-opus、or-gemini-3.1-pro、or-codex-5.4

1. 除非用户另行指定，否则使用默认项。 如果 $ARGUMENTS 中不包含 Agent 选择指令（例如“使用所有 Agent”“添加 codex”“只用 gemini”），则跳过此步骤，直接使用默认项进入确认步骤。

2. 如果用户要求使用其他 Agent（在 $ARGUMENTS 中或通过后续消息提出），则通过 Bash 运行以下命令，发现可用 Agent：

   counselors ls
   

   打印完整输出，然后使用 AskUserQuestion 请用户选择。

   如果 Agent 不超过 4 个：使用 multiSelect: true 的 AskUserQuestion，每个 Agent 对应一个选项。

   如果 Agent 超过 4 个：AskUserQuestion 仅支持 4 个选项。使用以下固定选项：

   • 选项 1：“全部 [N] 个 Agent” — 发送给所有已配置的 Agent
   • 选项 2–4：按 ID 排序的前三个单独 Agent
   • 用户也可以随时选择“其他”，输入上述打印列表中的逗号分隔 Agent ID

   不要将 Agent 组合成预设组（例如“claude + codex + gemini”）。每个选项必须是单个 Agent 或“全部”。

3. 必须：继续前确认选择。 明确复述将要调用的 Agent 列表：

   将发送给：or-claude-opus、or-gemini-3.1-pro、or-codex-5.4

   然后请用户确认（例如“这样可以吗？”），再进入阶段 3。这样可以避免静默遗漏工具。如果用户更正列表，请相应更新选择。

阶段 3：提示词组装

1. 根据主题生成 slug（小写，使用连字符，最多 40 个字符）

   • “review the auth flow” → auth-flow-review
   • “is this migration safe” → migration-safety-review

2. 通过 Bash 创建输出目录。目录名 MUST 始终以秒级 UNIX 时间戳为前缀，以便按字典序排序运行记录，并避免冲突：

   ./agents/counselors/TIMESTAMP-[slug]
   

   例如：./agents/counselors/1770676882-auth-flow-review

   **Mac 提示：**使用 date +%s（自纪元以来的秒数）生成时间戳。在 macOS 上，不借助 GNU coreutils，date 不支持毫秒精度——请使用 date +%s 生成可移植的秒级时间戳。

3. 使用 Write 工具将提示词文件写入 ./agents/counselors/TIMESTAMP-[slug]/prompt.md：

# Review Request

## Question
[User's original prompt/question from $ARGUMENTS]

## Context

### Files Referenced
[Contents of the most relevant files found in Phase 1]

### Recent Changes
[git diff output, if any]

### Related Code
[Related files discovered via search]

## Reference Documentation
[Phase 1b content — current library docs from Context7. If Phase 1b was skipped, omit this section.]

## Instructions
You are providing an independent review. Be critical and thorough.
- Analyze the question in the context provided
- Identify risks, tradeoffs, and blind spots
- Suggest alternatives if you see better approaches
- Be direct and opinionated — don't hedge
- Structure your response with clear headings
- Flag any code patterns that appear outdated vs. the Reference Documentation above

---

阶段 4：分派

分派前告知用户：

“正在分派给 [N] 个 Agent：[列表]。通常需要 2-5 分钟……”

记下你创建的提示词目录路径（例如：./agents/counselors/1772865337-auth-flow-review/）。counselors CLI 会创建一个带有秒级时间戳后缀的同级输出目录。

通过 Bash 使用提示词文件运行 counselors，并传入用户选择的 Agent：

set -a; for f in ~/.env .env ~/.vibe-tools/.env; do [ -f "$f" ] && source "$f"; done; set +a; counselors run -f ./agents/counselors/[slug]/prompt.md --tools [comma-separated-selections] --json

为何要加载环境变量？ Claude Code 的 Bash 工具可能无法从用户的交互式 shell 继承 API 密钥（例如 OPENAI_API_KEY）。set -a + source 模式可跨平台地从标准 dotenv 文件加载密钥（适用于 bash、zsh、sh）。不存在的文件会被静默跳过。

示例：--tools claude,codex,gemini

使用 Bash timeout: 480000（8 分钟）。工具将并行运行（非顺序运行）。counselors 配置中的单工具超时用于控制每个工具的运行时长。

**重要：**使用 -f（文件模式），确保提示词原样发送，不添加包装内容。使用 --json 获取便于解析的结构化输出。

---

阶段 5：读取结果（基于文件系统——不依赖标准输出）

**重要：**不要只依赖 JSON 标准输出。CLI 只有在所有工具运行结束后才会写入 run.json 并打印 JSON。如果有工具挂起或进程被终止，标准输出将为空。请始终扫描文件系统作为备用方案。

步骤 1：查找输出目录。

ls -dt ./agents/counselors/[slug]-*/ 2>/dev/null | head -1

如果没有找到目录，说明 CLI 在分派前就已失败。告知用户并建议运行 counselors doctor。停止。

步骤 2：检查 run.json（正常情况）。 如果 run.json 存在，请解析：

• status: "success" 且 wordCount > 0——确实成功
• status: "timeout"——工具超时
• status: "error"——工具崩溃
• status: "success" 且 wordCount: 0——静默失败（读取 .stderr）

步骤 3：如果没有 run.json，扫描单个文件。 对每个预期工具，检查 {tool-id}.md 是否存在且大小大于 0。检查 {tool-id}.stderr，了解错误详情。

步骤 4：向用户报告。

• **所有工具均已生成输出：**继续阶段 6。
• **部分工具已生成输出：**告知用户哪些工具失败及原因，然后询问：“使用 [N] 份（共 [M] 份）响应继续，还是重试？”
• **没有工具生成输出：**报告错误。建议运行 counselors doctor。停止。

---

阶段 6：综合并呈现

将所有 Agent 的响应整合为一份综合报告：

## Counselors Review

**Agents consulted:** [list of agents that responded]

**Consensus:** [What most agents agree on — key takeaways]

**Disagreements:** [Where they differ, and reasoning behind each position]

**Key Risks:** [Risks or concerns flagged by any agent]

**Blind Spots:** [Things none of the agents addressed that seem important]

**Recommendation:** [Your synthesized recommendation based on all inputs]

---
Reports saved to: [output directory from manifest]

向用户呈现这份综合报告。内容应简洁——各份详细报告已保存，供深入阅读。

---

阶段 7：采取行动（可选）

呈现综合报告后，询问用户希望处理哪些事项。提供综合报告中最值得采取行动的 2-3 个选项。如果用户希望根据发现采取行动，应先规划实施方案，再进行更改。

---

错误处理

• 未安装 counselors：告知用户安装它（npm install -g counselors）
• 未配置工具：告知用户运行 counselors init 或 counselors add
• 未创建输出目录：CLI 在分发前失败（配置错误、缺少二进制文件）。检查 Bash 调用的 stderr。
• 输出目录已存在，但没有 run.json：CLI 在所有工具完成前被终止。检查各个 .md 文件——已完成的工具会写入其输出。这是最常见的部分失败情况。
• 无提示地失败（status: "success"，但 wordCount: 0，或 .md 文件大小为 0 字节）：读取 .stderr 文件。常见原因：API 密钥已过期、需要支付 402 错误、触发速率限制。
• 单个 Agent 失败：记录此情况，询问用户是继续处理其余响应还是重试。
• 所有 Agent 均失败：报告各个 .stderr 文件中的错误。建议运行 counselors doctor。不要继续进行综合处理。
• 绝不无限期等待：8 分钟的 Bash 超时是硬性上限。不要添加 sleep/retry 循环。