ai-xray 1.2.0 → 2.0.0

package/PRD.md

@@ -1,397 +1,538 @@
-# ai-xray: X-Ray Vision for AI Coding Agents (PRD)
+# ai-xray — AI Model Diagnostics Toolkit (PRD v2.0.0)
 
-> **版本:** v1.0 Revised
-> **日期:** 2026-03-06
-> **一句话定位:** Give your AI coding agent x-ray vision into any codebase.
+> **Tagline:** X-ray your AI. Know what's under the hood.
+> **npm:** `ai-xray` | **GitHub:** `10iii/ai-xray` | **Author:** `10iii <zh@ngxil.in>`
 
 ---
 
-## 1. 产品愿景
+## 1. Repositioning
 
-当 AI Agent 接手一个陌生项目时，它面对的是一间漆黑的房间——不知道技术栈、不知道目录结构、不知道怎么跑测试。
-**`ai-xray` 就是那束穿透黑暗的 X 光。** 一条命令，瞬间看穿项目的骨骼结构。
+`ai-xray` was originally a codebase context scanner for AI agents. That functionality has been migrated to `ai-see`.
 
-- 不是 AI 助手（不帮你写代码）
-- 不是 DevTools（不面向人类）
-- 是 **AI 助手的眼睛**——专为 LLM 设计的、结构化的、Token 友好的本地环境探测器
+**New mission:** `ai-xray` is now a **diagnostic and probing toolkit for AI models and agents themselves.** It answers the question: *"What AI am I talking to, and what can it actually do?"*
 
----
+Think of it as `curl` for AI models — a lightweight CLI that lets you probe, benchmark, and fingerprint any LLM through its API.
 
-## 2. 核心设计原则
+## 2. Problem Statement
 
-### 2.1 Machine-First 协议
+Developers and AI agent systems work with dozens of LLM providers (OpenAI, Anthropic, Google, Ollama, Groq, etc.) but have no standardized way to:
+1. **Identify** which model is actually responding (API version, model ID, context window).
+2. **Probe** what capabilities a model supports (function calling, vision, streaming, JSON mode).
+3. **Benchmark** response speed, token throughput, and cost across providers.
+4. **Compare** multiple models on the same prompt side-by-side.
 
-| 规则 | 含义 |
-|---|---|
-| **Pure JSON stdout** | 成功时 stdout 只包含一个合法 JSON 对象，无任何其他字符 |
-| **Structured stderr** | 失败时 stderr 输出 `{"error": "...", "code": "..."}` + 非零 Exit Code |
-| **Zero interactivity** | 绝不等待用户输入。所有选项必须通过参数传入 |
-| **No ANSI escapes** | 输出中不含颜色码、进度条、emoji |
+## 3. Core Design Principles
 
-### 2.2 全局 Token 预算 `--budget`
+1. **Provider-Agnostic:** Works with any OpenAI-compatible API endpoint (covers 90%+ of providers).
+2. **Zero External Dependencies:** Uses Node.js built-in `https`/`http` modules for API calls.
+3. **Machine-First Output:** All output is JSON by default (can format for humans with `--pretty`).
+4. **Non-Destructive:** Read-only probing. Never sends harmful or creative prompts — only diagnostic prompts.
 
-**核心差异化特性。** 所有产生大量输出的命令都接受 `--budget <number>` 参数（近似 Token 数）。超出时自动截断并附加 `"truncated": true` 和下一步操作提示。
+## 4. Technology Stack
 
----
+- **Language:** TypeScript
+- **Build:** tsup (CJS output, target node18)
+- **Test:** vitest
+- **Dependencies:** Zero runtime dependencies
 
-## 3. 技术栈
+## 5. File Structure
 
-| 选型 | 选择 | 理由 |
-|---|---|---|
-| Language | TypeScript | 强类型保证 JSON Schema 严谨 |
-| CLI Parsing | 手写 `process.argv` | 零依赖，启动极速 |
-| Build | `tsup` → 单文件 `dist/cli.js` | 最小安装体积 |
-| Runtime | Node.js ≥ 18 | 原生 `node:fs`, `node:child_process` |
-| **运行时依赖** | **零** | 打包后完全自包含 |
+```
+ai-xray/
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── vitest.config.ts
+├── README.md
+├── src/
+│   ├── cli.ts                  # Entry point
+│   ├── client.ts               # Universal LLM API client
+│   ├── commands/
+│   │   ├── ping.ts             # ai-xray ping — basic connectivity test
+│   │   ├── id.ts               # ai-xray id — model fingerprinting
+│   │   ├── probe.ts            # ai-xray probe — capability detection
+│   │   ├── bench.ts            # ai-xray bench — performance benchmark
+│   │   ├── tokenize.ts         # ai-xray tokens — token counting
+│   │   └── compare.ts          # ai-xray compare — multi-model comparison
+│   └── utils/
+│       ├── http.ts             # HTTP request helper (stdlib only)
+│       ├── timer.ts            # High-res timing utilities
+│       └── output.ts           # JSON / pretty output formatting
+└── tests/
+    ├── client.test.ts
+    ├── ping.test.ts
+    ├── id.test.ts
+    ├── probe.test.ts
+    ├── bench.test.ts
+    ├── tokenize.test.ts
+    ├── compare.test.ts
+    └── http.test.ts
+```
 
 ---
 
-## 4. 核心命令集
-
-### 命令速查表
-
-```
-ai-xray scout [--budget=N]                      一键全局侦察（env+tree+readme+rules+diff）
-ai-xray env                                     项目画像
-ai-xray tree [dir] [--depth=N] [--budget=N]     目录结构透视
-ai-xray read <file...> [--lines=N-M] [--keys=a,b] [--budget=N]  精准文件读取
-ai-xray diff [--full] [--file=path]              Git 变更摘要
-ai-xray init [--format=cursorrules|claude|agents] 注入/生成 AI rules 文件
-ai-xray help                                    获取专为 AI 设计的 JSON 格式命令指南
-```
+## 6. Global Flags
 
-通用参数：
-- `--budget=<tokens>` 限制输出的近似 Token 数
-- `--pretty` 仅供人类调试时使用
+| Flag | Alias | Description |
+|---|---|---|
+| `--help` | `-h` | Print help summary with all commands and usage examples. Exit 0. |
+| `--version` | `-v` | Print `ai-xray@<version>` and exit 0. |
+| `--pretty` | — | Format JSON output as human-readable tables (default is compact JSON). |
+| `--provider` | `-p` | Specify which provider config to use (default: env vars). |
 
 ---
 
-### 4.1⭐ `ai-xray help` — AI 专用使用指南
+## 7. Configuration
 
-**场景：** AI Agent 或大模型在调用工具发生错误，或者忘记具体参数时执行的自我修复制导。
+`ai-xray` reads provider config from environment variables or a config file.
 
+**Environment Variables (primary):**
 ```bash
-ai-xray help
+AI_XRAY_API_KEY=sk-xxxxx
+AI_XRAY_BASE_URL=https://api.openai.com/v1     # default
+AI_XRAY_MODEL=gpt-4o                            # default
 ```
 
-**Output：** （不同于传统人类易读的 `--help` 文本流，`ai-xray help` 返回纯结构的 JSON）
+**Config File (optional):** `~/.ai-xray.json`
 ```json
 {
-  "_help": "ai-xray: Structured Context Gathering for AI Agents",
-  "commands": {
-    "scout": { "usage": "...", "desc": "..." },
-    "tree": { "usage": "...", "desc": "..." }
-  },
-  "global_flags": {
-    "--budget=N": "Truncates/summarizes output to fit within N approximate tokens."
+  "providers": {
+    "openai": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "sk-xxxxx",
+      "model": "gpt-4o"
+    },
+    "anthropic": {
+      "baseUrl": "https://api.anthropic.com/v1",
+      "apiKey": "sk-ant-xxxxx",
+      "model": "claude-sonnet-4-20250514"
+    },
+    "ollama": {
+      "baseUrl": "http://localhost:11434/v1",
+      "model": "llama3"
+    }
   }
 }
 ```
 
----
+**Function Signature:**
+```typescript
+// src/client.ts
+export interface ProviderConfig {
+  baseUrl: string;
+  apiKey?: string;
+  model: string;
+}
 
-### 4.2 ⭐ `ai-xray scout` — 一键全局侦察
+export function loadConfig(provider?: string): ProviderConfig;
+```
 
-**这是 README 里第一个展示的命令，也是使用频率最高的命令。**
+---
 
-**场景：** AI 刚 clone 了一个陌生项目（尤其是僵尸项目狩猎场景），需要一次性获取全部关键上下文。
+## 7. Command Reference
 
-**内置逻辑（用户不需要写条件，工具自动判断）：**
+### 7.1 `ai-xray ping [--provider=<name>]` — Connectivity Test
 
-```
-1. 执行 env                                      （总是）
-2. 执行 tree --depth=2                            （总是）
-3. IF README.md 存在 THEN 读取前 60 行             （常见）
-4. IF CLAUDE.md / .cursorrules / AGENTS.md 存在
-   THEN 读取其内容                                 （这些是 AI 约定文件，极重要）
-5. IF 是 git 仓库 THEN 输出 diff stat             （常见）
-6. IF package.json 有 workspaces 字段
-   THEN 列出所有 workspace 包名和路径              （monorepo 场景）
-```
+**Behavior:**
+1. Send a minimal request (`messages: [{ role: "user", content: "hi" }]`, `max_tokens: 1`) to the API.
+2. Measure response time.
+3. Report: reachable (true/false), latency, model echoed back, rate limit headers.
 
-**Output：**
+**Output:**
 ```json
 {
-  "env": {
-    "packageManager": { "name": "pnpm", "version": "9.1.0" },
-    "node": { "version": "20.11.0", "engines": ">=18" },
-    "frameworks": ["next", "tailwindcss", "prisma"],
-    "scripts": { "dev": "next dev", "build": "next build", "test": "vitest" },
-    "testFramework": {
-      "name": "vitest",
-      "runCommand": "npx vitest run --reporter=json",
-      "parseHint": "Look for testResults[].assertionResults[].failureMessages"
-    },
-    "lintFramework": {
-      "name": "eslint",
-      "runCommand": "npx eslint . --format=json"
-    }
-  },
-  "tree": {
-    "src/": {
-      "components/": { "_files": ["Button.tsx", "Modal.tsx"], "_more": 9 },
-      "pages/": { "index.tsx": {}, "auth/": { "login.tsx": {} } },
-      "lib/": { "_files": ["db.ts", "auth.ts", "utils.ts"] }
-    },
-    "package.json": {},
-    "README.md": {}
-  },
-  "readme": "# My Project\nA Next.js application for...\n...(truncated at 60 lines)",
-  "agentRules": null,
-  "diff": {
-    "branch": "main",
-    "ahead": 0,
-    "behind": 2,
-    "staged": [],
-    "unstaged": [],
-    "untracked": []
-  },
-  "workspaces": null,
-  "_meta": {
-    "tokensEstimate": 1850,
-    "budget": 3000,
-    "truncated": false
+  "reachable": true,
+  "latency_ms": 342,
+  "model": "gpt-4o-2024-08-06",
+  "rate_limit": {
+    "remaining": 9998,
+    "reset_at": "2026-03-07T21:00:00Z"
   }
 }
 ```
 
-**价值：** 将 AI 接手陌生项目时的 5 轮工具调用压缩为 1 轮。在僵尸项目狩猎场景下，"每个项目 2 小时" → "每个项目 30 分钟"。
-
----
+**Function Signature:**
+```typescript
+// src/commands/ping.ts
+export interface PingResult {
+  reachable: boolean;
+  latency_ms: number;
+  model: string | null;
+  rate_limit: { remaining: number | null; reset_at: string | null };
+  error?: string;
+}
 
-### 4.2 `ai-xray env` — 项目画像
+export async function ping(config: ProviderConfig): Promise<PingResult>;
+```
 
-**场景：** 只需要技术栈信息，不需要目录结构。
+### 7.2 `ai-xray id [--provider=<name>]` — Model Fingerprinting
 
-```bash
-ai-xray env
-```
+**Behavior:**
+Send a series of diagnostic prompts to identify the model:
+1. `"What model are you? Reply with only the model identifier."` → Extract self-reported model name.
+2. `"What is your knowledge cutoff date? Reply YYYY-MM only."` → Extract training cutoff.
+3. `"What is your maximum context window in tokens? Reply with only the number."` → Extract context size.
+4. Parse API response headers for `x-model`, `x-ratelimit-*`, `openai-organization`.
 
+**Output:**
 ```json
 {
-  "packageManager": { "name": "pnpm", "version": "9.1.0" },
-  "node": { "version": "20.11.0", "engines": ">=18" },
-  "workspaces": ["packages/*"],
-  "frameworks": ["next", "tailwindcss", "prisma"],
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "test": "vitest",
-    "lint": "eslint ."
-  },
-  "testFramework": {
-    "name": "vitest",
-    "runCommand": "npx vitest run --reporter=json",
-    "parseHint": "Look for testResults[].assertionResults[].failureMessages"
+  "self_reported": {
+    "model": "GPT-4o",
+    "cutoff": "2025-06",
+    "context_window": 128000
   },
-  "lintFramework": {
-    "name": "eslint",
-    "runCommand": "npx eslint . --format=json",
-    "parseHint": "Each element has filePath and messages[]"
+  "api_reported": {
+    "model": "gpt-4o-2024-08-06",
+    "organization": "org-xxxxx"
   },
-  "git": {
-    "branch": "main",
-    "hasUncommitted": true,
-    "remoteUrl": "https://github.com/10iii/ai-xray.git"
+  "fingerprint": {
+    "provider": "openai",
+    "confidence": 0.95
   }
 }
 ```
 
----
-
-### 4.3 `ai-xray tree` — 结构透视
+**Function Signature:**
+```typescript
+// src/commands/id.ts
+export interface IdResult {
+  self_reported: {
+    model: string | null;
+    cutoff: string | null;
+    context_window: number | null;
+  };
+  api_reported: {
+    model: string | null;
+    organization: string | null;
+  };
+  fingerprint: {
+    provider: string;
+    confidence: number;
+  };
+}
 
-```bash
-ai-xray tree                     # 整个项目，默认 depth=3
-ai-xray tree src/                # 只看 src
-ai-xray tree --depth=1           # 只看第一层
-ai-xray tree --budget=300        # Token 预算限制
+export async function identify(config: ProviderConfig): Promise<IdResult>;
 ```
 
+### 7.3 `ai-xray probe [--provider=<name>]` — Capability Detection
+
+**Behavior:**
+Run a battery of lightweight tests to detect model capabilities:
+
+| Test | How | Result |
+|---|---|---|
+| **JSON mode** | Send with `response_format: { type: "json_object" }` | `true/false` |
+| **Function calling** | Send with a dummy `tools` array | `true/false` |
+| **Vision** | Send a tiny base64 image in content | `true/false` |
+| **Streaming** | Send with `stream: true` | `true/false` |
+| **System prompt** | Send with a system message | `true/false` |
+| **Temperature control** | Send with `temperature: 0` | `true/false` |
+
+**Output:**
 ```json
 {
-  "root": ".",
-  "depth": 3,
-  "structure": {
-    "src/": {
-      "components/": {
-        "_files": ["Button.tsx", "Modal.tsx", "Header.tsx"],
-        "_more": 9
-      },
-      "pages/": {
-        "index.tsx": {},
-        "auth/": { "login.tsx": {}, "register.tsx": {} }
-      },
-      "lib/": {
-        "_files": ["db.ts", "auth.ts", "utils.ts"]
-      }
-    },
-    "tests/": { "_more": 8 },
-    "package.json": {},
-    "tsconfig.json": {}
-  },
-  "stats": {
-    "totalFiles": 47,
-    "displayed": 16,
-    "ignored": ["node_modules", "dist", ".next", ".git"]
+  "capabilities": {
+    "json_mode": true,
+    "function_calling": true,
+    "vision": true,
+    "streaming": true,
+    "system_prompt": true,
+    "temperature_control": true
   },
-  "truncated": false
+  "probe_duration_ms": 4521
 }
 ```
 
-**设计要点：**
-- `_files` 数组：目录下只有文件时用扁平列表，极度节省 Token
-- `_more: 9`：告诉 AI "还有 9 个文件被省略了"，可据此决定是否深入
-- `ignored`：明确告诉 AI 哪些目录被跳过，消除困惑
+**Function Signature:**
+```typescript
+// src/commands/probe.ts
+export interface ProbeResult {
+  capabilities: Record<string, boolean>;
+  probe_duration_ms: number;
+}
 
----
+export async function probe(config: ProviderConfig): Promise<ProbeResult>;
+```
 
-### 4.4 `ai-xray read` — 精准文件读取
+### 7.4 `ai-xray bench [--provider=<name>] [--rounds=5]` — Performance Benchmark
 
-支持四种模式：
+**Behavior:**
+1. Send a fixed prompt (`"Write a haiku about coding."`) N times.
+2. Measure: time-to-first-token (TTFT), total response time, tokens generated, tokens/second.
+3. Compute statistics: mean, median, p95.
 
-**A. 读取整个文件**
-```bash
-ai-xray read src/auth.ts
+**Output:**
+```json
+{
+  "rounds": 5,
+  "stats": {
+    "ttft_ms": { "mean": 280, "median": 265, "p95": 410 },
+    "total_ms": { "mean": 1200, "median": 1150, "p95": 1800 },
+    "tokens_per_second": { "mean": 42.5, "median": 40.1, "p95": 55.2 },
+    "output_tokens": { "mean": 51, "total": 255 }
+  }
+}
 ```
 
-**B. 读取特定行范围**（AI 通常从报错信息中知道行号）
-```bash
-ai-xray read src/auth.ts --lines=40-65
-```
+**Function Signature:**
+```typescript
+// src/commands/bench.ts
+export interface BenchStats {
+  mean: number;
+  median: number;
+  p95: number;
+}
 
-**C. 从 JSON 提取特定键**
-```bash
-ai-xray read package.json --keys=scripts,dependencies
-```
+export interface BenchResult {
+  rounds: number;
+  stats: {
+    ttft_ms: BenchStats;
+    total_ms: BenchStats;
+    tokens_per_second: BenchStats;
+    output_tokens: { mean: number; total: number };
+  };
+}
 
-**D. 批量读取多文件**（一次调用替代多次，减少 Agent 轮次）
-```bash
-ai-xray read src/auth.ts src/db.ts src/utils.ts --budget=2000
+export async function bench(
+  config: ProviderConfig,
+  options?: { rounds?: number }
+): Promise<BenchResult>;
 ```
 
-Output 示例（批量模式）：
+### 7.5 `ai-xray tokens <text_or_file>` — Token Counter
+
+**Behavior:**
+1. Accept text from argument, stdin pipe, or file path.
+2. Estimate token count using a simple whitespace/BPE heuristic (no tiktoken dependency).
+3. Report: estimated tokens, character count, word count, cost estimate (if model pricing known).
+
+**Output:**
 ```json
 {
-  "files": [
-    { "file": "src/auth.ts", "lines": 142, "content": "..." },
-    { "file": "src/db.ts", "lines": 58, "content": "..." },
-    { "file": "src/utils.ts", "lines": 31, "content": "...", "truncated": true }
-  ]
+  "characters": 1542,
+  "words": 287,
+  "estimated_tokens": 412,
+  "cost_estimate": {
+    "model": "gpt-4o",
+    "input_cost_usd": 0.00103
+  }
 }
 ```
 
----
-
-### 4.5 `ai-xray diff` — 变更摘要
+**Function Signature:**
+```typescript
+// src/commands/tokenize.ts
+export interface TokenResult {
+  characters: number;
+  words: number;
+  estimated_tokens: number;
+  cost_estimate?: {
+    model: string;
+    input_cost_usd: number;
+  };
+}
 
-```bash
-ai-xray diff                     # 默认：stat 模式
-ai-xray diff --full              # 含完整 diff 内容
-ai-xray diff --file=src/auth.ts  # 只看某个文件
+export async function countTokens(
+  input: string,
+  options?: { model?: string }
+): Promise<TokenResult>;
 ```
 
-**stat 模式输出：**
+### 7.6 `ai-xray compare --providers=openai,anthropic,ollama` — Multi-Model Comparison
+
+**Behavior:**
+1. Send the same prompt to all specified providers.
+2. Run `ping` + `bench` on each.
+3. Return a side-by-side comparison table.
+
+**Output:**
 ```json
 {
-  "branch": "feature/auth",
-  "ahead": 2,
-  "behind": 0,
-  "staged": [
-    { "file": "src/db.ts", "status": "M", "insertions": 5, "deletions": 1 }
-  ],
-  "unstaged": [
-    { "file": "src/auth.ts", "status": "M", "insertions": 15, "deletions": 2 }
-  ],
-  "untracked": ["src/components/LoginForm.tsx"]
+  "prompt": "Write a haiku about coding.",
+  "results": [
+    { "provider": "openai", "model": "gpt-4o", "ttft_ms": 280, "total_ms": 1200, "tokens": 51 },
+    { "provider": "anthropic", "model": "claude-sonnet-4-20250514", "ttft_ms": 350, "total_ms": 1400, "tokens": 48 },
+    { "provider": "ollama", "model": "llama3", "ttft_ms": 120, "total_ms": 800, "tokens": 45 }
+  ]
 }
 ```
 
-**`--full` 输出额外附带 `hunks` 字段包含实际变更内容。**
+**Function Signature:**
+```typescript
+// src/commands/compare.ts
+export interface CompareResult {
+  prompt: string;
+  results: Array<{
+    provider: string;
+    model: string;
+    ttft_ms: number;
+    total_ms: number;
+    tokens: number;
+    error?: string;
+  }>;
+}
+
+export async function compare(
+  providers: string[],
+  options?: { prompt?: string; rounds?: number }
+): Promise<CompareResult>;
+```
 
 ---
 
-### 4.6 `ai-xray init` — 智能注入 AI Rules
+## 8. Universal LLM API Client
 
-**场景：** 让项目"AI-Ready"。在项目的 AI 规则文件中注入 ai-xray 的使用指南，使得后续任何 AI Agent 打开该项目时都会自动使用 ai-xray。
+**File:** `src/client.ts`
 
-**核心行为（零参数智能默认）：**
+```typescript
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string | Array<{ type: string; [key: string]: unknown }>;
+}
 
-```
-1. 按优先级搜索已有的 AI 规则文件：
-   AGENTS.md > CLAUDE.md > .cursorrules > .github/copilot-instructions.md
+export interface ChatRequest {
+  model: string;
+  messages: ChatMessage[];
+  max_tokens?: number;
+  temperature?: number;
+  stream?: boolean;
+  response_format?: { type: string };
+  tools?: unknown[];
+}
 
-2. IF 找到了已有文件
-   THEN 将 ai-xray 使用指南注入到该文件末尾
-        （附加一个 <!-- ai-xray --> 标记，防止重复注入）
-   
-3. IF 没有找到任何已有文件
-   THEN 创建 AGENTS.md（最通用的格式）
+export interface ChatResponse {
+  id: string;
+  model: string;
+  choices: Array<{
+    message: { role: string; content: string };
+    finish_reason: string;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  headers: Record<string, string>;
+  latency_ms: number;
+}
 
-4. 输出操作摘要到 stdout（JSON 格式）
+export async function chat(
+  config: ProviderConfig,
+  request: ChatRequest
+): Promise<ChatResponse>;
 ```
 
-**注入的内容模板（自动根据当前项目技术栈定制）：**
+**Key behavior:**
+- Uses Node.js `https.request` (no `fetch`, no axios) for maximum compatibility.
+- Automatically adds `Authorization: Bearer <key>` header.
+- Captures response headers for rate limit info.
+- Measures latency with `performance.now()`.
 
-```markdown
-<!-- ai-xray:start -->
-## Project Context Protocol (powered by ai-xray)
+---
 
-Before modifying this project, gather context by running:
-  npx ai-xray scout --budget=2000
+## 9. Test Plan
 
-When debugging a failing test:
-  npx ai-xray read <file> --lines=<error-range>
+**Framework:** vitest  
+**Run:** `npx vitest run`
 
-Before committing changes:
-  npx ai-xray diff --full
-<!-- ai-xray:end -->
+### 9.1 `tests/client.test.ts` (5 tests)
+```
+✓ should construct correct request headers
+✓ should handle 401 unauthorized gracefully
+✓ should handle network timeout
+✓ should parse response JSON correctly
+✓ should measure latency
 ```
 
-**可选参数：**
-```bash
-ai-xray init                          # 智能默认：找到就注入，没有就创建 AGENTS.md
-ai-xray init --format=claude          # 强制创建/注入 CLAUDE.md
-ai-xray init --format=cursorrules     # 强制创建/注入 .cursorrules
+### 9.2 `tests/ping.test.ts` (4 tests)
+```
+✓ should report reachable=true for successful response
+✓ should report reachable=false for connection error
+✓ should extract rate limit headers
+✓ should measure latency_ms
 ```
 
-**Output：**
-```json
-{
-  "action": "injected",
-  "target": "AGENTS.md",
-  "linesAdded": 12,
-  "marker": "ai-xray:start"
-}
+### 9.3 `tests/id.test.ts` (5 tests)
+```
+✓ should extract self-reported model name
+✓ should extract knowledge cutoff
+✓ should extract context window size
+✓ should extract API-reported model from response
+✓ should compute provider fingerprint with confidence score
 ```
 
-**战略价值：** 这是 ai-xray 的**自我传播引擎**。用户运行 `ai-xray init` → 规则文件被提交到 Git → 其他开发者/AI 打开项目时读取规则 → 它们也开始用 `npx ai-xray` → 安装量自然增长。
+### 9.4 `tests/probe.test.ts` (7 tests)
+```
+✓ should detect JSON mode support (supported)
+✓ should detect JSON mode support (unsupported → graceful false)
+✓ should detect function calling support
+✓ should detect vision support
+✓ should detect streaming support
+✓ should detect system prompt support
+✓ should measure total probe duration
+```
 
----
+### 9.5 `tests/bench.test.ts` (5 tests)
+```
+✓ should run specified number of rounds
+✓ should compute mean correctly
+✓ should compute median correctly
+✓ should compute p95 correctly
+✓ should report output token totals
+```
 
-## 5. 未来考量 (v2.0+)
+### 9.6 `tests/tokenize.test.ts` (4 tests)
+```
+✓ should count characters accurately
+✓ should count words accurately
+✓ should estimate tokens within ±20% of actual
+✓ should compute cost estimate for known models
+```
 
-| 特性 | 描述 |
-|---|---|
-| **MCP 兼容** | 将 ai-xray 的命令暴露为 MCP Resources/Tools，使 Claude Desktop 等可原生调用 |
-| **AST 感知 read** | `ai-xray read src/auth.ts --symbol=login` 只返回某个函数体 |
-| **`search`** | 类 grep 但输出结构化 JSON（文件名 + 行号 + 上下文） |
-| **多语言** | 支持 Python (pip/poetry)、Go、Rust (cargo) 项目 |
-| **`run-test`** | 真正执行测试并提取精炼的失败摘要 |
+### 9.7 `tests/compare.test.ts` (4 tests)
+```
+✓ should query all specified providers
+✓ should handle one provider failing gracefully
+✓ should return results in consistent format
+✓ should accept custom prompt
+```
 
----
+### 9.8 `tests/http.test.ts` (3 tests)
+```
+✓ should make HTTPS POST request
+✓ should handle redirect
+✓ should timeout after specified duration
+```
 
-## 6. v1.0 路线图
+**Total: ~37 test cases**
 
-| 里程碑 | 内容 |
-|---|---|
-| **M1** | `env` + `tree` + `scout` (core engine) |
-| **M2** | `read` + `diff` |
-| **M3** | `init` (self-propagation engine) |
-| **M4** | `--budget` Token 预算系统 |
-| **M5** | tsup 构建 → `ai-xray@1.0.0` 发布 |
+---
 
-M5 后进入**自我验证阶段**：用 ai-xray 自己去猎杀僵尸项目，根据实战体验反向优化 JSON 结构。
+## 10. package.json (Final)
 
----
-*PRD v1.0 Revised — 2026-03-06*
+```json
+{
+  "name": "ai-xray",
+  "version": "2.0.0",
+  "description": "X-ray your AI. Probe, benchmark, and fingerprint any LLM.",
+  "main": "dist/cli.js",
+  "bin": { "ai-xray": "dist/cli.js" },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "test": "vitest run"
+  },
+  "keywords": ["ai","llm","benchmark","probe","diagnostics","model","agent"],
+  "author": "10iii <zh@ngxil.in> (https://zha.ngxil.in)",
+  "repository": { "type": "git", "url": "git+https://github.com/10iii/ai-xray.git" },
+  "homepage": "https://github.com/10iii/ai-xray#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}
+```