Wingman Mcp

Wingman 是一个面向编码 Agent 的辅助模型 MCP server。它把大文件、长文本、命令输出和代码 diff 压缩成结构化、可回查的上下文，帮助主 Agent 更快定位重点。

Wingman 不负责最终判断。所有输出均为辅助性结果，调用方在编辑代码、执行命令或作出架构与安全决策前，必须回查原文和源码。

核心定位

主 Agent 负责：理解完整上下文、作出决策、实施与验证
Wingman 负责：压缩输入、提取证据、提出风险假设、暴露不确定性

Wingman 的价值不是替代主模型，而是用独立的辅助模型减少上下文占用，并提供第二视角。

模型优先

Wingman 采用模型优先架构：

模型负责语义理解、归纳、风险判断和压缩
本地代码负责安全、确定性结构、调用预算、证据校验和明确降级

新增语言、测试框架或构建工具通常不应要求新增专用 parser。只有格式稳定、场景高频且能够证明准确率、成本或可靠性收益时，才保留确定性 adapter。

完整决策见 ADR-0001：模型优先架构。

工具定位

工具	核心意图	适合输入	不承担的职责
aux_summarize_file	建立单个大文件的结构与职责认知	源码、Markdown、测试文件、Swift/多语言	权威符号索引、依赖分析、重构决策；新语言由模型路径承担语义，不新增语言正则
aux_compress_text	压缩通用非结构化文本	长文档、普通日志、错误说明	精确诊断、命令失败统计
aux_compress_command_output	从命令输出提取失败点和 evidence	test/build/lint/compiler/stack trace 等任意命令输出	自动修复、权威根因判断
aux_review_diff	对小型 unified diff 提出有证据的风险假设	小 diff、提交前快速初筛	最终 code review、安全审计、合并决策
aux_review_diff_by_file	显式按文件/hunk 审查大型 diff	多文件大 diff、PR diff	跨仓库影响分析、完整源码语义
aux_report_tool_feedback	收集调用方对工具输出质量的反馈	质量问题报告、字段矛盾、hallucination 报告	自动修复、替代人工校验
aux_tool_stats	查询各工具累计调用次数和 token 消耗	用量观测、成本估算	账单审计、跨进程持久化

工具边界

compress_text 与 compress_command_output

• 输入是命令的 stdout/stderr，并且关心失败点、文件、行号、错误码：使用 aux_compress_command_output。
• 输入是普通长文本，只需要摘要和关键事实：使用 aux_compress_text。

review_diff 与 review_diff_by_file

两个工具表达的是同一个用户意图，区别主要在当前的大输入执行策略：

• 小 diff：使用 aux_review_diff，单次模型调用更直接。
• 大型多文件 diff：使用 aux_review_diff_by_file，能够记录文件/hunk 的分析与省略状态。

长期方向是将按文件分批变成 aux_review_diff 的内部策略，减少调用方选择成本；当前保留两个入口以兼容现有行为。

选择指南

你的输入	推荐工具
不熟悉的大源码文件	aux_summarize_file
长文档或非命令型日志	aux_compress_text
npm test、tsc、ESLint、构建或运行时输出	aux_compress_command_output
小型 diff	aux_review_diff
大型多文件 diff	aux_review_diff_by_file

不建议使用 Wingman 的场景：

• 小文件或短文本，直接阅读更准确；
• 精确符号依赖与 blast-radius 分析，应使用代码图谱或语言工具；
• 最终 code review、架构决策或安全审计；
• 需要确定性结论但无法回查原始证据的任务。

执行模型

MCP request
  → 输入 schema 校验
  → 安全清理与确定性结构处理
  → 构造模型 payload
  → 小输入单次调用；超预算后才分批
  → 模型返回结构化 JSON
  → schema / evidence 校验
  → 无损聚合与状态计算
  → 非权威结果

模型不可用或调用失败时，工具会进入 heuristic fallback。fallback 返回低置信度结构 signals（heuristic_signals），analysis_status 为 partial（有 heuristic 结果）或 incomplete（无结果）。调用方应检查 _meta.fallback_used 和 analysis_status 判断结果可靠性。

aux_compress_command_output 会区分 valid、partial_valid、empty、JSON/schema 失败和 transport failure。非零退出且模型响应不可用时，工具最多进行一次受限修复调用；已有稳定 adapter 的格式可进入 deterministic coverage guard，并明确标记 fallback 和分析状态。

共享模型执行、预算、evidence 和状态能力位于 src/model-runtime/。各工具仍处于渐进迁移阶段，具体完成度见全工具模型优先评审与重构计划。

接入方式

Wingman 提供两种接入方式，按需选择：

CLI 模式（推荐）

按需运行，用完即退，零常驻 token 占用。

# 直接分析文件
wingman summarize-file --path src/index.ts

# 通过 stdin pipe 传入数据
cat build-output.log | wingman compress-command-output --focus "errors only"

# 审查 diff
git diff | wingman review-diff --focus security

# 查看帮助
wingman --help

MCP 模式（向后兼容）

通过 Claude Code 的 MCP server 接入，工具定义常驻上下文。

{
  "mcpServers": {
    "wingman": {
      "command": "npx",
      "args": ["-y", "@jafish/wingman-mcp", "--mcp"]
    }
  }
}

Claude Code Skill

Wingman 提供 Claude Code skill，可通过 /wingman 调用。安装后包含各工具的使用时机、命令示例和输出解读指南。

# 安装到当前项目（推荐）
wingman install-skill

# 或安装到全局（所有 Claude Code 会话可用）
wingman install-skill --global

可靠性与安全边界

• 五个分析工具均为只读 MCP 工具；aux_report_tool_feedback 写入本地 JSONL 日志（非破坏性），是唯一可写的工具。
• 输出中的 is_authoritative 固定为 false。
• openWorldHint 表示输出可能不完整。
• 模型结论必须尽量携带可回查 evidence；无法验证的结论应降级。
• 模型未运行、部分失败和完整成功使用 analysis_status（complete | partial | incomplete）区分；所有工具已统一使用 modelPathStatus() / fallbackStatus() 计算。
• aux_summarize_file 的文件访问限制在 AUX_WORKSPACE_ROOT 内，并拒绝绝对路径与路径穿越。
• Chat client 强制执行 HTTPS（可显式允许本地 loopback HTTP）、SSRF 防护、超时与重试；配置 AUX_MODEL_ALLOWED_HOSTS 后还会执行 host allowlist。
• Prompt 使用内容分隔、focus 数据隔离、无状态调用、JSON-only 和 schema 校验降低注入风险。
• 日志写入 stderr 和可选文件，不占用 MCP stdio 的 stdout。

质量反馈

Wingman 提供 aux_report_tool_feedback 工具，供调用方在发现输出质量问题时主动报告。报告内容写入结构化日志文件，支持后续聚合分析。

何时主动反馈：

• 输出字段自相矛盾（如 first_failure 指向文件 A，但 findings 中对应分析指向文件 B）
• finding 缺少可回查 evidence，无法验证其正确性
• 模型产生 hallucination（结论与原文明显不符）
• fallback 结果过度确定（如将 heuristic signals 表述为确信判断）
• schema 字段语义误导（如实为 partial 的分析被误标为 complete）
• summary 低信号，未能有效压缩关键信息

反馈工具用法：

调用 aux_report_tool_feedback，传入 tool_name、trace_id、issue_category、severity、summary、confidence，可选 evidence、expected_behavior、actual_behavior，以及可复现性字段 repro_input_ref、assertion_hint、project_context、output_meta（仅 white-listed 字段）。工具返回 recorded、feedback_id 和 log_file。

**主动引导（_meta 反馈提示）：**五个分析工具在输出 _meta 中包含 feedback_recommended 和 feedback_reason 字段。当触发 fallback、输入被截断、结果为空或证据被拒绝时，feedback_recommended 设为 true。feedback_reason 取值为 fallback_used | input_truncated | partial_analysis | low_confidence | empty_result | evidence_rejected。调用模型无须主动检测这些状况——检查 _meta 即可判断是否应报告反馈。

**工具描述交叉引用：**每个分析工具的 MCP description 末尾均内嵌了提示：当输出 analysis_status 为 partial/incomplete、fallback_used 为 true、或 confidence 为 low 时，应通过 aux_report_tool_feedback 报告质量问题。这使反馈闭环成为工具契约的一部分，调用模型在每次工具使用中都能看到这一引导。

反馈日志：

• 默认写入用户目录下的 ~/.wingman/feedback.jsonl（JSON Lines 格式，每行一个 JSON 对象），所有消费项目共享同一个反馈入口
• 通过 AUX_FEEDBACK_LOG_FILE 环境变量自定义路径，设为 off 则禁用
• 反馈不包含完整源码、完整 diff 或敏感凭据。超长字段和疑似 token 会在写入前被脱敏
• 反馈写入失败不影响原 MCP 工具调用

聚合分析：

使用 npx tsx scripts/summarize-feedback.ts 读取反馈 JSONL，输出按工具和类别统计的 Markdown 汇总报告至 ~/.wingman/feedback-reports/。可通过 --output 参数自定义输出目录。

工具调用统计

Wingman 提供 aux_tool_stats 工具，查询各工具的累计调用次数和 token 消耗（持久化到本地文件，server 重启后保留）。

统计指标： 按 MCP tool 名称聚合 calls、input_tokens、output_tokens、total_tokens。

持久化： 统计数据原子写入 ~/.wingman/tool-stats.json（可通过 AUX_TOOL_STATS_FILE 自定义路径），server 重启后保留。文件损坏时自动从空统计恢复。

重要限制： 统计数据仅供观测，不得作为账单或审计依据。无模型调用（fallback）的工具 token 计数为 0。

默认落盘文件

Wingman 产生的默认本地文件统一放在 ~/.wingman/ 目录下：

文件	默认路径	环境变量/参数覆盖
反馈 JSONL	~/.wingman/feedback.jsonl	AUX_FEEDBACK_LOG_FILE
工具统计 JSON	~/.wingman/tool-stats.json	AUX_TOOL_STATS_FILE
运行日志	~/.wingman/wingman.log	AUX_LOG_FILE
反馈汇总报告	~/.wingman/feedback-reports/	--output (CLI)

所有环境变量覆盖均保留原语义；设为 off 可禁用对应文件的写入。

安装

推荐：npm 全局安装

npm install -g @jafish/wingman-mcp

# 注册并配置环境变量
claude mcp add -s user wingman \
  -e AUX_MODEL_API_KEY=sk-xxx \
  -e AUX_MODEL_BASE_URL=https://api.deepseek.com/v1 \
  -e AUX_MODEL_NAME=deepseek-v4-flash \
  -e AUX_MODEL_PROVIDER=remote \
  -e AUX_MODEL_ALLOWED_HOSTS=api.deepseek.com \
  -- wingman-mcp

本地 OpenAI-compatible 模型也可以直接注册，例如本地 Qwen 服务监听 8080：

claude mcp add -s user wingman \
  -e AUX_MODEL_API_KEY=local \
  -e AUX_MODEL_BASE_URL=http://127.0.0.1:8080/v1 \
  -e AUX_MODEL_NAME=/Users/jafish/Documents/models/Qwen3.6-35B-A3B-4bit \
  -e AUX_MODEL_PROVIDER=local \
  -e AUX_MODEL_TIMEOUT_MS=120000 \
  -e AUX_MODEL_ALLOWED_HOSTS=127.0.0.1,localhost \
  -e AUX_ALLOW_INSECURE_LOCAL_HTTP=true \
  -e AUX_MODEL_DISABLE_THINKING=true \
  -- wingman-mcp

或手动编辑配置文件（项目级为项目根目录 .mcp.json，用户级为 ~/.claude.json）：

{
  "mcpServers": {
    "wingman": {
      "command": "wingman-mcp",
      "env": {
        "AUX_MODEL_API_KEY": "sk-xxx",
        "AUX_MODEL_BASE_URL": "https://api.deepseek.com/v1",
        "AUX_MODEL_NAME": "deepseek-v4-flash",
        "AUX_MODEL_ALLOWED_HOSTS": "api.deepseek.com"
      }
    }
  }
}

注意：npx @jafish/wingman-mcp 在部分环境下存在兼容性问题（sh: wingman-mcp: command not found），推荐使用 npm install -g 全局安装。AUX_WORKSPACE_ROOT 默认为当前工作目录。

本地 build（开发 / 自定义模型配置）

cd /path/to/Wingman
npm install
npm run build
claude mcp add -s project wingman -- node "$(pwd)/dist/index.js"

配置

Wingman 支持云端模型和本地模型两种接入方式。两者都需要提供 OpenAI-compatible /v1/chat/completions 接口；未配置 API key 时会进入 heuristic fallback。

配置默认只读取 MCP 注册时传入的环境变量或 shell 环境变量，不会自动读取当前项目的 .env。如需使用 env 文件，显式设置 AUX_ENV_FILE=/absolute/path/to/.env。

云端模型

环境变量示例：

AUX_MODEL_API_KEY=your-api-key
AUX_MODEL_BASE_URL=https://api.deepseek.com/v1
AUX_MODEL_NAME=deepseek-v4-flash
AUX_MODEL_PROVIDER=remote
AUX_MODEL_TIMEOUT_MS=30000
AUX_MODEL_ALLOWED_HOSTS=api.deepseek.com
AUX_MODEL_DISABLE_THINKING=false
AUX_LOG_FILE=~/.wingman/wingman.log

环境变量：

变量	必填	默认值	说明
AUX_MODEL_API_KEY	是*	—	模型 API key
AUX_MODEL_BASE_URL	否	https://api.deepseek.com/v1	OpenAI-compatible API 地址
AUX_MODEL_NAME	否	deepseek-v4-flash	模型名称
AUX_MODEL_PROVIDER	否	remote	模型来源标签
AUX_MODEL_TIMEOUT_MS	否	30000	请求超时，单位毫秒
AUX_MODEL_ALLOWED_HOSTS	否	—	允许的 API host，逗号分隔
AUX_MODEL_DISABLE_THINKING	否	false	为 Qwen 等模型附加 chat_template_kwargs.enable_thinking=false
AUX_ENV_FILE	否	—	显式加载的 env 文件路径；未设置时不会读取 .env
AUX_WORKSPACE_ROOT	否	当前进程目录	文件读取根目录
AUX_ALLOW_INSECURE_LOCAL_HTTP	否	false	仅允许 loopback 的本地 HTTP
AUX_LOG_LEVEL	否	info	debug/info/warn/error
AUX_LOG_FILE	否	~/.wingman/wingman.log	设置为 off 禁用文件日志
AUX_FEEDBACK_LOG_FILE	否	~/.wingman/feedback.jsonl	反馈日志路径，设置为 off 禁用

* 未配置 API key 时进入 heuristic fallback。该模式可用于降级和结构信号提取，但不等同于完整模型分析。

本地模型

本地模型需要显式允许 loopback HTTP。Qwen thinking 模型通常还需要关闭 thinking，确保服务返回标准 choices[0].message.content。

例如 Qwen 服务监听 8080：

AUX_MODEL_API_KEY=local
AUX_MODEL_BASE_URL=http://127.0.0.1:8080/v1
AUX_MODEL_NAME=/Users/jafish/Documents/models/Qwen3.6-35B-A3B-4bit
AUX_MODEL_PROVIDER=local
AUX_MODEL_TIMEOUT_MS=120000
AUX_MODEL_ALLOWED_HOSTS=127.0.0.1,localhost
AUX_ALLOW_INSECURE_LOCAL_HTTP=true
AUX_MODEL_DISABLE_THINKING=true

验证

claude mcp list

AUX_WORKSPACE_ROOT 默认取启动 Wingman 进程时的当前目录。全局注册时，应确认宿主是否以目标项目目录启动 MCP；需要固定范围时请显式设置该变量。

开发

npm install
npm run build
npm test
npm run smoke
npm run dev

测试包括（共 314 个）：

• workspace 与 schema 安全边界；
• command output diagnostic、overlay、调用预算、handler 级恢复和真实 fixture；
• diff chunking 与文件级聚合；
• 无模型配置下的 smoke fallback；
• SwiftUI/DSL 误识别红灯测试（summarize_file model-first 迁移）；
• prompt 注入防护、JSON 提取与响应后处理；
• chat-client SSRF/CIDR/IPv4/IPv6/重试逻辑；
• 五个工具的模型路径集成测试（需 API key）；
• 行覆盖率 87.8%。

Round 4 真实模型回放连续 3 次均保留 14/14 findings，每次 1 次模型调用且未使用 fallback。脱敏结果见回放证据。

项目结构

src/
├── index.ts                 MCP server 与工具注册
├── config.ts                环境变量和 fallback 配置
├── chat-client.ts           OpenAI-compatible client、安全与重试
├── workspace.ts             文件访问边界
├── schema.ts                Zod 输入/输出 schema
├── prompts.ts               无状态 prompt 与响应提取
├── logger.ts                trace 日志
├── model-runtime/           共享模型调用、预算、evidence、状态
├── decoding/                模型响应分层解码与逐 finding 校验
├── diagnostics/             少量确定性 diagnostic adapter
├── chunking/                diff/command-output 结构分块与聚合
├── fallback/                降级结构与 heuristic signals
└── tools/                   六个 MCP handler

scripts/
├── replay-round4.ts         脱敏回放聚合与分析
└── summarize-feedback.ts    反馈日志聚合分析脚本

test/
├── fixtures/                匿名化真实输入与 expectations
├── helpers/                 fixture runner
└── *.test.ts                单元、契约、预算和 smoke tests

当前架构评审

定位正确的部分

• “辅助模型压缩上下文、主 Agent 最终决策”的总定位正确。
• 文件摘要、通用文本压缩、命令诊断和 diff review 是四种不同用户意图。
• 安全边界、schema、真实 fixture 和非权威标记符合辅助工具定位。
• model-runtime 已开始统一模型调用、预算、evidence 和状态。

需要继续收敛的部分

• review_diff_by_file 长期应成为 review_diff 的内部大输入策略。
• review_diff 和 compress_text fallback 中仍有较多关键词和风险规则，应逐步降级为 validators/signals。
• 各工具的长输入策略和执行元数据尚未完全统一。
• src/index.ts 的 MCP JSON schema 与 src/schema.ts 手工重复，存在字段漂移风险。
• compress_command_output 外的其他工具真实模型成功、部分失败和大输入回归仍需补齐。

文档

文档	内容
计划地图	计划类型、依赖、状态和推荐实施顺序
施工计划模板	不变量、Step 0 红灯测试、migration 和完成定义
ADR-0001	模型优先架构与 adapter 准入原则
全工具模型优先评审	五个工具的定位评审和迁移计划
计划质量评审	7 份设计文档的强项/弱项分析与改进建议
Command Output 模型优先计划	任意命令输出、evidence 和通用分块
输出 Schema 迁移	analysis status、heuristic signals 和 failure 字段迁移
Summarize File 模型优先计划	已完成 — DSL 误识别修复、智能截断、heuristic_signals、Swift/多语言支持
模型响应契约恢复	已完成 — Round 4 分层校验、null 规范化、非零退出恢复
Round 4 回放证据	3 次真实模型回放的脱敏状态、计数和门禁结果
真实场景验证方案	fixtures、契约、模型评测与 Shadow 验证
Phase 2 计划	分块框架与新增工具的原始设计

兼容性

• Node.js 18+
• OpenAI-compatible Chat API
• macOS

License

MIT