vzwjustin/advisor

# advisor  一个为 Claude Code 打造的单命令、由 Opus 主导的代码审查与修复流水线。Opus 优先执行——进行自身的 Glob+Grep 发现，将文件按 P1–P5 排名，并 **基于刚才掌握的信息为每个 agent 编写独特且具备文件感知能力的 prompt**。 随后它保持在线，并**全程主动引导团队**：纠正偏离方向，实时回答问题， 在每个输出生成时立即验证，并在发现新问题改变全局时调整计划。Opus 是 那位直到最终报告交付前绝不空闲的战略家。可选的修复波次会以相同方式应用 编辑。 无外部 API 调用。完全通过 Claude Code 的原生 `TeamCreate` / `Agent` / `SendMessage` 工具运行。 **实现方式：** Rust（`advisor-rs` crate，`advisor` CLI）。Python 包已在 `main` 分支上被取代；请参阅 [`RUST_PORT_PLAN.md`](RUST_PORT_PLAN.md) 和 [`PORT_NOTES.md`](PORT_NOTES.md) 了解迁移状态。 ## 团队（三层架构，默认） | 角色 | 模型 | Agent 类型 | 任务 | |------|-------|------------|-----| | **Advisor** | Opus 4.8 (`claude-opus-4-8`) | `generalPurpose` | Glob+Grep 发现，P1–P5 排名，配置 explorer 和 coder 池，编写各 agent 的 prompt，分发探索与修复波次——保持活跃：纠正偏离、回答问题、验证每个输出、在波次进行中调整计划 | | **Explorer 池** | Haiku 4.5 (`claude-haiku-4-5`) × N | `explore` | 对 Advisor 分配的文件批次进行只读结构化发现；将发现报告给 team-lead → Advisor | | **Coder 池** | Sonnet 4.6 (`claude-sonnet-4-6`) × N | `generalPurpose` | 长效修复 worker；每个都会获得一个特定领域的 prompt（在分配修复任务时包含探索上下文）；将发现和差异报告给 team-lead → Advisor | 优先级划分：**P5** 认证/密钥 · **P4** 用户输入/解析 · **P3** handlers/DB/exec · **P2** 配置/加密/日志 · **P1** 工具/测试。 循环：**Explorer 发现 → Advisor 推理 → Coder 修复。**

旧版两层模式

设置 `max_explorers=0` 或 `ADVISOR_MAX_EXPLORERS=0` 可跳过 explorer 波次，并运行原始的 advisor + Sonnet-runner 流水线。

## 安装 ### 从源码构建（推荐） 需要 [Rust](https://rustup.rs/) **1.74+**。该二进制文件具有**零运行时 依赖**——仅需 Rust 工具链即可构建。 ``` git clone https://github.com/vzwjustin/advisor && cd advisor cargo install --path . advisor install # wire SKILL.md + CLAUDE.md nudge (idempotent) advisor status # confirm what landed where ``` 修改后，使用 `cargo install --path . --force` 重新安装。

其他安装方法

``` # 在不 clone 的情况下安装带 tag 的 release（需要 Rust + git） cargo install --git https://github.com/vzwjustin/advisor --tag v0.8.7 # 在不安装的情况下运行 cargo run -- version cargo run -- pipeline src/ # PyPI（已发布的 release —— 包名为 advisor-agent） pipx install advisor-agent pipx upgrade advisor-agent # 普通的 pip / uv pip install advisor-agent uv tool install advisor-agent ``` 在 Rust 迁移期间，PyPI 的发布可能会滞后于 `main` 分支。若要获取最新 功能（三层架构、Rust 移植），请从源码构建。

首次运行 `advisor install` 会自动配置 `~/.claude/CLAUDE.md` 和 `/advisor` 斜杠命令。CLAUDE.md 块中还嵌入了包含 4 条规则的 **行为准则**部分（三思而后行 · 简洁至上 · 精准修改 · 目标驱动执行）。每次升级都会打印来自 `CHANGELOG.md` 的“更新摘要”。

手动管理 nudge / 技能

``` advisor status # install health check advisor install # append / update the nudge + skill (idempotent) advisor install --check # dry-run: print status, exit 3 if anything missing advisor uninstall # cleanly remove the nudge + skill advisor install --path /x # target a different CLAUDE.md ``` 使用 `ADVISOR_NO_NUDGE=1` 退出自动安装。使用 `ADVISOR_QUIET=1` 抑制诊断 TTY 加载动画。CLAUDE.md 块 被 `` / `` 标记包裹，以便重新安装时能原地更新。

## 使用方法 在 Claude Code 内部调用： ``` /advisor # review the cwd /advisor src/ # review a specific dir /advisor review the auth flow # add scope context ``` 或者使用独立的 CLI 来检查 prompt 和计划： ``` advisor pipeline src/ # full pipeline reference (three-tier by default) advisor protocol # print the strict team-lifecycle protocol advisor plan src/ # rank local files, print dispatch plan advisor plan src/ --json # same, machine-readable for `jq` etc. advisor plan src/ --format json # explicit selector (alias of --json; pretty overrides) advisor plan src/ --sarif out.sarif # SARIF 2.1.0 output for Code Scanning advisor audit RUN_ID [TARGET] # post-hoc diagnostic for a completed run advisor prompt advisor src/ # the advisor's prompt body advisor prompt runner src/ --runner-id 1 # a coder's bootstrap prompt advisor prompt verify src/ < findings # verify-pass prompt advisor status # install health check advisor status --json # JSON-formatted health for scripting advisor doctor # extended diagnostic: git/claude/codex/env checks advisor install # install nudge + /advisor skill (prints What's new on upgrade) advisor update # self-upgrade via PyPI, then re-runs install advisor changelog [VERSION] # print bundled CHANGELOG section(s); --since X.Y.Z for a digest advisor uninstall # remove nudge + /advisor skill advisor ui # launch local web dashboard on 127.0.0.1:8765 (Findings · Live · Plan · Run config · Cost) advisor live tail # tail the live event stream (the Live tab subscribes to this) advisor history # recent findings from .advisor/history.jsonl advisor history --stats # aggregate: confirm rate, breakdowns, top files advisor baseline create # snapshot current findings as baseline advisor baseline diff # compare current run vs. baseline advisor checkpoints # list saved plan checkpoints advisor checkpoints --rm RUN_ID # delete a single checkpoint advisor checkpoints --clear # delete all checkpoints advisor presets # list available rule-pack presets advisor suppressions --list # list active false-positive suppressions advisor version # print version + environment info ``` 每个子命令的 `target` 默认为 `.`（当前目录）。支持通过 `--context -`（读取标准输入）管道传递长范围描述。 Flags：`--team`、`--file-types`、`--max-runners`（建议性——对于大型代码库 Opus 可能会超出此限制）、`--min-priority`、`--context`、`--advisor-model`、 `--runner-model`。默认模型：`claude-opus-4-8` / `claude-sonnet-4-6` / `claude-haiku-4-5`（完整 ID 会锁定版本；裸别名 `opus`/`sonnet`/`haiku` 会在生成时解析为最新版本）。中等长度的 ID（如 `opus-4-8`）会自动标准化为 `claude-opus-4-8`。 环境变量覆盖（也会被 `default_team_config` 读取）： | 变量 | 默认值 | 效果 | |----------|---------|--------| | `ADVISOR_MODEL` | `claude-opus-4-8` | Advisor 模型 | | `ADVISOR_RUNNER_MODEL` | `claude-sonnet-4-6` | Coder 模型 | | `ADVISOR_EXPLORER_MODEL` | `claude-haiku-4-5` | Explorer 模型 | | `ADVISOR_MAX_RUNNERS` | `5` | 建议的 coder 池大小 | | `ADVISOR_MAX_EXPLORERS` | 与 max runners 相同 | Explorer 池大小（`0` = 旧版两层架构） | | `ADVISOR_MIN_PRIORITY` | `3` | 包含的最低 P 级别 | | `ADVISOR_FILE_TYPES` | `*.*` | `advisor plan` 的 Glob 过滤器 | | `ADVISOR_EXPLORER_OUTPUT_CHAR_CEILING` | `40000` | Explorer 输出预算 | | `ADVISOR_EXPLORER_FILE_READ_CEILING` | `40` | Explorer 不同文件读取上限 | 上下文压力调节参数（减少 coder 上下文耗尽）： `--max-fixes-per-runner N` · `--large-file-line-threshold N` · `--large-file-max-fixes M` · `--runner-output-char-ceiling K` · `--runner-file-read-ceiling L`。 自动化 flags：在 `status`/`plan`/`install --check` 时使用 `--json`， 在 `install`/`uninstall` 时使用 `--quiet`，在 `status`/`install`/`uninstall` 时使用 `--strict` （如果没有变化或安装不健康则 exit `3`）。 默认启用颜色。使用 `NO_COLOR=1` 或 `TERM=dumb` 退出。 ## 排除文件 (`.advisorignore`) 在项目根目录下放置一个 `.advisorignore` 文件，可以在执行 `advisor plan` 和实时流水线处理期间跳过这些路径： ``` # 注释以 # 开头 tests/ # skip directories (trailing slash) *.md # skip by filename glob vendor/ generated/**/*.py # ** recursive globs are supported ``` 模式遵循 `fnmatch` 语义进行文件名匹配，并在包含 `**` 时使用 `PurePath.match`。纯单词会匹配任何路径 组件（`docs` 可匹配 `docs/` 和 `foo/docs/bar.py`）。 ## Rust 库 crate 根目录重新导出了与 Python 包相同的接口： ``` use advisor::{ default_team_config, TeamConfig, TeamConfigInput, build_advisor_prompt, build_explorer_prompt, build_explorer_pool_agents, build_coder_prompt, build_runner_pool_prompt, build_runner_dispatch_messages, build_fix_assignment_message, build_verify_dispatch_prompt, build_verify_message, render_pipeline, rank_files, create_focus_tasks, parse_findings_from_text, estimate_cost, findings_to_sarif, resolve_version, }; let config = default_team_config(TeamConfigInput::new("src/")); println!("{}", render_pipeline(&config)); ``` Builder 函数返回纯字符串或对 JSON 友好的结构体——可以将它们直接 放入 Claude Code 的 `Agent(...)` 或 `SendMessage(...)` 调用中。有关 完整的导出列表，请参阅 `src/lib.rs`。 ## 模块 (`src/`) | 模块 | 职责 | |--------|------| | `config.rs` | `TeamConfig`，环境变量组装，模型验证 | | `orchestrate/` | Advisor、explorer 和 coder 的 prompt 构建器；`render_pipeline` | | `rank.rs` | `rank_files`，基于关键字信号的 P1–P5 排名 | | `focus.rs` | `create_focus_tasks` / `create_focus_batches`，计划格式化工具 | | `verify.rs` | `Finding`，`parse_findings_from_text`，验证阶段构建器 | | `runner_budget.rs` | 每个 coder 的输出字符预算和轮换 | | `install.rs` | 幂等 CLAUDE.md nudge + `/advisor` 技能安装 | | `doctor.rs` | Git / Claude / Codex / 安装健康检查 | | `audit.rs` | 事后运行记录诊断 | | `baseline.rs` | 用于检测偏离的 Finding 基准 | | `checkpoint.rs` | 用于 `--resume` 的计划检查点 | | `cost.rs` | 各层级的 token 和成本范围估算 | | `git_scope.rs` | `--since` / `--staged` / `--branch` 范围界定 | | `history.rs` | 确认的发现日志 (`.advisor/history.jsonl`) | | `sarif.rs` | SARIF 2.1.0 序列化器 | | `suppressions.rs` | 按规则划分的误报抑制 | | `skill_asset.rs` | 内置的 `/advisor` 技能内容 | | `web.rs` | 本地仪表板 (`advisor ui`) | | `live.rs` | 用于 Live 标签页的临时事件流 | Prompt 模板位于 `src/assets/` (`advisor.txt`, `explorer.txt`, …) 下。 ## 实时仪表板 (0.8.0 新增) 运行 `advisor ui` 并打开 http://127.0.0.1:8765，即可实时观看 `/advisor` 的运行过程，无需将 Claude Code 保持在前台。**Live** 标签页每 2 秒 轮询一次 `/api/events`，并将 team-lead 的 事件流呈现为一个 feed：每次 runner 生成、每个报告转发、每次 修复分发，以及最终的运行摘要。新到达的行会短暂 闪烁；在 500 行时执行 FIFO 裁剪；支持 `prefers-reduced-motion`。 team-lead 通过 `advisor live record` 在三个 检查点（`run_start`、每次 `report_relay`、`run_end`）发出事件，这是 由内置的 `/advisor` 技能主体指示的。事件是尽力而为的：写入失败 永远不会中断流水线。从不启动 `advisor ui` 的用户不会 看到任何行为变化——事件文件只会在 `/.advisor/live/events.jsonl` 中无害地累积。 事件存储刻意与 `history.jsonl` 分开： - `history.jsonl` — 权威的 CONFIRMED 发现；驱动 ranker 提升、SARIF 排放、惯犯分析。 - `live/events.jsonl` — 临时事件 feed；对 orchestrator 不透明，对仪表板具有参考性，采用自由格式 payload。 如需从终端进行临时检查：`advisor live tail --limit 50` （使用 `--json` 用于脚本）。`advisor live clear` 会删除该文件； 游标会干净地保留，以便下一次运行时恢复流。 ## 编排规则 - 在生成任何 agent 之前执行 `TeamCreate`；在创建新团队之前执行 `TeamDelete`。 - Opus 优先——在 Opus 的第一轮处理产生池大小之前，不会出现 explorer 或 coder。 - 每个 agent 都使用 Opus 分发计划中的 **逐字逐句的 per-agent prompt** 进行生成。不要替换为通用模板。 - 在包含 `run_in_background=true` 的**单条消息**中分发 agent， 以便它们能并行启动。 - 每个 agent prompt 必须以 `SendMessage(...)` 结尾——否则 agent 会静默进入空闲状态。 - 按名称单独关闭队友；广播关闭无效。 有关完整的协议，请参阅 `CLAUDE.md`。 ## 开发 ``` git clone https://github.com/vzwjustin/advisor && cd advisor cargo build make check # clippy + fmt --check + test cargo test # 125+ parity tests (Linux, macOS, Windows in CI) cargo fmt # format cargo clippy --all-targets ``` 发布检查清单：`make release-check`（打印版本和 tag 命令）。 版本号记录在 `Cargo.toml` 中；使用 `git tag vX.Y.Z && git push origin vX.Y.Z` 进行 tag。 ## GitHub Action 可重用的工作流，它会运行 `advisor plan`，将 SARIF 2.1.0 输出上传到 GitHub Code Scanning，并（可选）发布 PR 评论。将此内容粘贴到 代码库的 `.github/workflows/advisor.yml` 中： ``` name: Advisor on: pull_request: push: branches: [main] jobs: advisor: uses: vzwjustin/advisor/.github/workflows/advisor.yml@v0.8.7 with: target: "." min-priority: 3 preset: "python-web" # optional rule-pack tuning post-pr-comment: false ``` 或者自行构建：任何 CI 系统都可以运行 `advisor plan --sarif advisor.sarif` 并将文件上传到您使用的任何扫描器。 ## 预设 精心策划的规则包捆绑方案，可为 常见技术栈调整文件类型默认值和优先级关键字： | Preset | 技术栈 | 默认值 | |--------------------|------------------------------|------------------------------------| `general-python` | 通用 Python 代码库 | `*.py`，无特定技术栈的提升 | | `python-web` | Flask / Django / FastAPI | `*.py`，P5 认证关键字 | | `python-cli` | argparse / click CLIs | `*.py`，P3 subprocess 关键字 | | `node-api` | Express / Fastify / Koa | `*.js,*.ts`，P5 JWT/session | | `typescript-react` | React + TS | `*.ts,*.tsx`，P4 DOM sinks | | `go-service` | net/http services | `*.go`，P3 net/http/sql | | `rust-crate` | library / crate | `*.rs`，P3 unsafe/transmute | ``` advisor plan src/ --preset python-web advisor presets # list presets advisor presets --json # machine-readable ``` ## 自动化 flags 发现结果来自于 `advisor audit`（验证阶段）——`advisor plan` 会打印分发排名。依赖于 发现结果的门控和输出 flags（`--fail-on`、`--format pr-comment`、`--baseline`）仅存在于 `audit` 上。`--sarif` 两者都有——`plan` 会写入一个空结果 文档（还没有发现结果），而 `audit` 会写入真实的结果。 | Flag | 适用于 | 效果 | |----------------------------|-----------------|-------------------------------------------| | `--sarif PATH` | `plan`, `audit` | 为 Code Scanning 写入 SARIF 2.1.0 | | `--fail-on LEVEL` | `audit` | 如果有任何发现结果 ≥ LEVEL 则 Exit 4 | | `--format pr-comment` | `audit` | 输出适合 PR 正文格式的 Markdown 摘要 | | `--baseline PATH` | `audit` | 抑制与基准匹配的发现结果 | | `--no-history` | `plan` | 为确保 CI 计划的确定性而忽略历史记录 | | `--json` / `--output FILE` | `plan`, `audit` | 机器可读的输出 | Exit 代码：`0` 干净 · `4` 触发 `--fail-on` 阈值 · `3` `--strict` 无操作或安装不健康 · `2` argparse / 用户错误 · `1` 意外情况。 ## 发现结果生命周期 - **`advisor history`** — 来自 `.advisor/history.jsonl` 的近期确认发现（`--stats` 用于聚合视图） - **`advisor baseline create`** — 将当前发现快照为已接受的基准 - **`advisor baseline diff`** — 将当前运行与基准进行比较 - **`.advisor/suppressions.jsonl`** — 带有 过期日期的按规则、按文件划分的抑制（运行 `advisor suppressions` 列出，添加 `--expired` 进行过滤） ## 延伸阅读 - [`docs/architecture.md`](docs/architecture.md) — 模块依赖图、 运行时流程、数据契约、设计不变式 - [`docs/prompts.md`](docs/prompts.md) — 面向 修改 prompt 模板的贡献者的 prompt 工程笔记 - [`RUST_PORT_PLAN.md`](RUST_PORT_PLAN.md) — Rust 迁移计划 - [`PORT_NOTES.md`](PORT_NOTES.md) — Python 对等状态 ## 许可证 [MIT](LICENSE) — 版权所有 (c) 2025–2026 Justin Adams ([@vzwjustin](https://github.com/vzwjustin))。

标签：AI代理, Claude Code, Rust, SOC Prime, 代码审查, 可视化界面, 多模型协作, 开发工具, 模块化设计, 网络流量审计, 自动化修复, 通知系统