# expert-router

给 Claude Code 用的**按项目开通**的专家咨询层：便宜模型在本地读仓库、跑测试；真正难的问题才压缩成 briefing，交给 ChatGPT 网页版（极高档）回答。

传输层使用 [`ai-browser-bridge`](https://github.com/YosefHayim/ai-browser-bridge)（或你自己的 fork）。本仓库**不** fork 那套浏览器适配器，只做路由、压缩、开通开关和防重试。

> **条款风险（必读）**  
> 用浏览器自动化抓取 ChatGPT 网页的回答，可能违反 OpenAI 现行使用条款。这是个人技术实验，不是生产方案。账号风险自负。长期依赖请走官方 API。

---

## 它做什么、不做什么

**做：**

- 默认**所有仓库关闭**。只有你对某个 git 仓库跑开通脚本后，该仓库的 Claude Code 会话才会出现 `expert_consult`。
- 调用必须带闭集 `reason`、绝对路径 `repo_root`、结构化 briefing（有体积上限）。
- 摘录路径必须留在仓内，不能把仓外文件送进专家。
- 进程内同时只允许一次咨询；`follow-up` 仅在同一次 MCP 进程已有会话时允许。
- 返回给 Claude 的是专家正文，不回 ChatGPT conversation URL。

**不做：**

- 不自动切 ChatGPT 模型（v1 请你自己把专用窗口拧到「极高」）。
- 不把原始 `bridge ask` 暴露给 Claude（开通后也只有 `expert_consult`）。
- 不启动、不关闭日常浏览器。专用 Brave 由你手动拉起。

---

## 架构

```text
某个已开通的 git 仓库
        │
        ▼
 Claude Code（本地调查、改代码、跑测试）
        │  仅当 reason 命中闭集
        ▼
 expert_consult MCP（本仓库）
        │  校验开通标记 + briefing
        ▼
 ai-browser-bridge CLI（本机 spawn）
        │  --debug-port（默认 9333）
        ▼
 专用 Brave（独立 profile + CDP）
        │
        ▼
 ChatGPT 网页（极高档）
```

机器配置在 `~/.ai-browser-bridge/expert.json`（**不要提交**）。  
项目开通标记在该仓库的 `.claude/expert-consult.json`（脚本会写入 `.git/info/exclude`）。

---

## 环境要求

- Windows 10/11（开通脚本是 PowerShell）
- Node.js ≥ 22
- 已安装并登录过的 **Brave**（也可用其它 Chromium，但脚本默认 Brave）
- 已构建的 `ai-browser-bridge`（`dist/bridge.js`）
- Claude Code CLI（`claude` 在 PATH 里）

Windows 上系统的 IP Helper 经常占用 **9222**。本项目默认 CDP 端口是 **9333**。  
上游 `bridge serve` 默认仍找 9222，因此你需要一份支持 `--debug-port` 的构建（见下文「与 ai-browser-bridge 的关系」）。

---

## 安装（只需一次）

在**本仓库**目录：

```powershell
npm install
npm run build
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
```

如果 `ai-browser-bridge` 和本仓库是同级目录，且已经 `npm run build` 过，`install.ps1` 会自动填上 `bridgeBinary`。否则：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -BridgeRoot "D:\path\to\ai-browser-bridge"
```

安装结果：

| 路径 | 含义 |
|---|---|
| `~/.ai-browser-bridge/*.ps1` | 启动 / 开通 / 关闭脚本的本机副本 |
| `~/.ai-browser-bridge/expert.json` | 本机路径，勿提交、勿分享 |
| `~/.ai-browser-bridge/brave-profile/` | 专用浏览器登录态 |
| `~/.ai-expert/consultations/` | 咨询记录（本机） |

打开 `expert.json`，确认：

- `routerBinary` 指向本仓库的 `dist/index.js`
- `bridgeBinary` 指向 `ai-browser-bridge` 的 `dist/bridge.js`
- `debugPort` 与专用 Brave 一致（默认 `9333`）
- `braveExe` 是本机 Brave 路径

---

## 启动专用浏览器（每次开工）

```powershell
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ai-browser-bridge\start-brave.ps1"
```

看到 `CDP 已在 9333 就绪` 后，在**这一扇**窗口里：

1. 登录 ChatGPT
2. 把推理档设为 **极高 / Extra High**
3. 窗口保持开着（可最小化）

不要把 debug port 打到你正在用的日常 Brave 上。

冒烟测试（可选）：

```powershell
node <ai-browser-bridge>/dist/bridge.js ask "Reply with exactly: pong" --provider chatgpt --debug-port 9333 --json
```

---

## 给某个项目开通（默认关闭）

```powershell
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ai-browser-bridge\enable-expert.ps1" -RepoRoot "D:\path\to\your\repo"
```

然后**在该仓库开一个新的 Claude Code 会话**。其他仓库仍然没有 `expert_consult`。

开通写入（均不进 git）：

```text
<repo>/.claude/expert-consult.json
<repo>/.claude/settings.local.json
<repo>/.claude/skills/expert-consult/SKILL.md
<repo>/.git/info/exclude
```

关掉：

```powershell
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ai-browser-bridge\disable-expert.ps1" -RepoRoot "D:\path\to\your\repo"
```

没有开通标记时，即使有人把 MCP 配进项目，调用也会被拒绝。

---

## Claude 应如何调用

Skill 会随开通复制进项目。要点：

1. 先本地调查，再升级。
2. `reason` 只能是：

   `architecture` · `concurrency` · `security` · `destructive-migration` · `local-failed-twice` · `unclear-tradeoff` · `low-confidence-after-evidence` · `user-explicit`

   同会话续问用 `follow-up`（只发增量）。
3. 必填：`repo_root`（git 根绝对路径）、`question`、`established`、`excerpts`、`attempts`、`desired_output`。
4. 整份 briefing ≤ 24000 字符；单条 excerpt ≤ 4000 字符。
5. 陈述用英文，源码不翻译。
6. 不要因为慢就重试。不要把专家回复当可应用补丁直接打进去。

---

## 与 ai-browser-bridge 的关系

本仓库 spawn：

```text
node <bridgeBinary> ask <prompt> --provider chatgpt --timeout 900 --debug-port <debugPort> --json
```

Windows 上请使用支持 `--debug-port` 的 `bridge serve` / `bridge ask` 构建。上游默认端口 9222；本机若被 IP Helper 占用，用 9333。

建议流程：

1. 构建你的 `ai-browser-bridge` fork（含 `--debug-port`）。
2. `install.ps1 -BridgeRoot <该 fork>`。
3. 不要把 `bridge serve` 注册成 Claude 的全局 MCP，以免模型直接 `ask`。

---

## 不要提交这些

| 内容 | 原因 |
|---|---|
| `~/.ai-browser-bridge/expert.json` | 本机绝对路径 |
| `~/.ai-browser-bridge/brave-profile/` | 浏览器登录态、Cookie |
| `~/.ai-expert/` | 咨询正文 |
| 项目里的 `.claude/settings.local.json`、`.claude/expert-consult.json` | 本机开通状态 |
| ChatGPT 页面截图、账号相关调试脚本 | 隐私 |

本仓库的 `.gitignore` 已忽略 `expert.json` 和常见本机 Claude 文件。开通脚本还会把项目侧文件写入 `.git/info/exclude`。

---

## 故障排除

**开通后工具列表里没有 `expert_consult`**  
在该仓库新开 Claude Code 会话。`claude mcp list`（在该仓库目录下）应显示 `expert-router`。

**调用报 off / marker**  
确认 `<repo>/.claude/expert-consult.json` 存在且 `"enabled": true`，`repo_root` 是 git 根的绝对路径。

**Brave 起不来 / CDP 超时**  
检查 `expert.json` 的 `braveExe`、`debugPort`。`http://127.0.0.1:9333/json/version` 应能打开。9222 被占用时不要改回 9222。

**ask 超时或找不到输入框**  
确认专用窗口已登录 ChatGPT。v1 不切模型，窗口应停在极高档。

**两个 Claude 同时咨询**  
v1 只做进程内互斥。不要对同一专用窗口开两个会咨询的会话。

---

## 开发

```powershell
npm install
npm run build
npm run dev
```

入口：`src/index.ts`（stdio MCP）。脚本：`scripts/`。Skill 模板：`skills/expert-consult/SKILL.md`。