ai-xray 0.0.1

package/PRD.md

@@ -0,0 +1,372 @@
+# ai-xray: X-Ray Vision for AI Coding Agents (PRD)
+
+> **版本:** v1.0 Revised
+> **日期:** 2026-03-06
+> **一句话定位:** Give your AI coding agent x-ray vision into any codebase.
+
+---
+
+## 1. 产品愿景
+
+当 AI Agent 接手一个陌生项目时，它面对的是一间漆黑的房间——不知道技术栈、不知道目录结构、不知道怎么跑测试。
+**`ai-xray` 就是那束穿透黑暗的 X 光。** 一条命令，瞬间看穿项目的骨骼结构。
+
+- 不是 AI 助手（不帮你写代码）
+- 不是 DevTools（不面向人类）
+- 是 **AI 助手的眼睛**——专为 LLM 设计的、结构化的、Token 友好的本地环境探测器
+
+---
+
+## 2. 核心设计原则
+
+### 2.1 Machine-First 协议
+
+| 规则 | 含义 |
+|---|---|
+| **Pure JSON stdout** | 成功时 stdout 只包含一个合法 JSON 对象，无任何其他字符 |
+| **Structured stderr** | 失败时 stderr 输出 `{"error": "...", "code": "..."}` + 非零 Exit Code |
+| **Zero interactivity** | 绝不等待用户输入。所有选项必须通过参数传入 |
+| **No ANSI escapes** | 输出中不含颜色码、进度条、emoji |
+
+### 2.2 全局 Token 预算 `--budget`
+
+**核心差异化特性。** 所有产生大量输出的命令都接受 `--budget <number>` 参数（近似 Token 数）。超出时自动截断并附加 `"truncated": true` 和下一步操作提示。
+
+---
+
+## 3. 技术栈
+
+| 选型 | 选择 | 理由 |
+|---|---|---|
+| Language | TypeScript | 强类型保证 JSON Schema 严谨 |
+| CLI Parsing | 手写 `process.argv` | 零依赖，启动极速 |
+| Build | `tsup` → 单文件 `dist/cli.js` | 最小安装体积 |
+| Runtime | Node.js ≥ 18 | 原生 `node:fs`, `node:child_process` |
+| **运行时依赖** | **零** | 打包后完全自包含 |
+
+---
+
+## 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 文件
+```
+
+通用参数：
+- `--budget=<tokens>` 限制输出的近似 Token 数
+- `--pretty` 仅供人类调试时使用
+
+---
+
+### 4.1 ⭐ `ai-xray scout` — 一键全局侦察
+
+**这是 README 里第一个展示的命令，也是使用频率最高的命令。**
+
+**场景：** AI 刚 clone 了一个陌生项目（尤其是僵尸项目狩猎场景），需要一次性获取全部关键上下文。
+
+**内置逻辑（用户不需要写条件，工具自动判断）：**
+
+```
+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 场景）
+```
+
+**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
+  }
+}
+```
+
+**价值：** 将 AI 接手陌生项目时的 5 轮工具调用压缩为 1 轮。在僵尸项目狩猎场景下，"每个项目 2 小时" → "每个项目 30 分钟"。
+
+---
+
+### 4.2 `ai-xray env` — 项目画像
+
+**场景：** 只需要技术栈信息，不需要目录结构。
+
+```bash
+ai-xray env
+```
+
+```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"
+  },
+  "lintFramework": {
+    "name": "eslint",
+    "runCommand": "npx eslint . --format=json",
+    "parseHint": "Each element has filePath and messages[]"
+  },
+  "git": {
+    "branch": "main",
+    "hasUncommitted": true,
+    "remoteUrl": "https://github.com/10iii/ai-xray.git"
+  }
+}
+```
+
+---
+
+### 4.3 `ai-xray tree` — 结构透视
+
+```bash
+ai-xray tree                     # 整个项目，默认 depth=3
+ai-xray tree src/                # 只看 src
+ai-xray tree --depth=1           # 只看第一层
+ai-xray tree --budget=300        # Token 预算限制
+```
+
+```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"]
+  },
+  "truncated": false
+}
+```
+
+**设计要点：**
+- `_files` 数组：目录下只有文件时用扁平列表，极度节省 Token
+- `_more: 9`：告诉 AI "还有 9 个文件被省略了"，可据此决定是否深入
+- `ignored`：明确告诉 AI 哪些目录被跳过，消除困惑
+
+---
+
+### 4.4 `ai-xray read` — 精准文件读取
+
+支持四种模式：
+
+**A. 读取整个文件**
+```bash
+ai-xray read src/auth.ts
+```
+
+**B. 读取特定行范围**（AI 通常从报错信息中知道行号）
+```bash
+ai-xray read src/auth.ts --lines=40-65
+```
+
+**C. 从 JSON 提取特定键**
+```bash
+ai-xray read package.json --keys=scripts,dependencies
+```
+
+**D. 批量读取多文件**（一次调用替代多次，减少 Agent 轮次）
+```bash
+ai-xray read src/auth.ts src/db.ts src/utils.ts --budget=2000
+```
+
+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 }
+  ]
+}
+```
+
+---
+
+### 4.5 `ai-xray diff` — 变更摘要
+
+```bash
+ai-xray diff                     # 默认：stat 模式
+ai-xray diff --full              # 含完整 diff 内容
+ai-xray diff --file=src/auth.ts  # 只看某个文件
+```
+
+**stat 模式输出：**
+```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"]
+}
+```
+
+**`--full` 输出额外附带 `hunks` 字段包含实际变更内容。**
+
+---
+
+### 4.6 `ai-xray init` — 智能注入 AI Rules
+
+**场景：** 让项目"AI-Ready"。在项目的 AI 规则文件中注入 ai-xray 的使用指南，使得后续任何 AI Agent 打开该项目时都会自动使用 ai-xray。
+
+**核心行为（零参数智能默认）：**
+
+```
+1. 按优先级搜索已有的 AI 规则文件：
+   AGENTS.md > CLAUDE.md > .cursorrules > .github/copilot-instructions.md
+
+2. IF 找到了已有文件
+   THEN 将 ai-xray 使用指南注入到该文件末尾
+        （附加一个 <!-- ai-xray --> 标记，防止重复注入）
+   
+3. IF 没有找到任何已有文件
+   THEN 创建 AGENTS.md（最通用的格式）
+
+4. 输出操作摘要到 stdout（JSON 格式）
+```
+
+**注入的内容模板（自动根据当前项目技术栈定制）：**
+
+```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
+
+When debugging a failing test:
+  npx ai-xray read <file> --lines=<error-range>
+
+Before committing changes:
+  npx ai-xray diff --full
+<!-- ai-xray:end -->
+```
+
+**可选参数：**
+```bash
+ai-xray init                          # 智能默认：找到就注入，没有就创建 AGENTS.md
+ai-xray init --format=claude          # 强制创建/注入 CLAUDE.md
+ai-xray init --format=cursorrules     # 强制创建/注入 .cursorrules
+```
+
+**Output：**
+```json
+{
+  "action": "injected",
+  "target": "AGENTS.md",
+  "linesAdded": 12,
+  "marker": "ai-xray:start"
+}
+```
+
+**战略价值：** 这是 ai-xray 的**自我传播引擎**。用户运行 `ai-xray init` → 规则文件被提交到 Git → 其他开发者/AI 打开项目时读取规则 → 它们也开始用 `npx ai-xray` → 安装量自然增长。
+
+---
+
+## 5. 未来考量 (v2.0+)
+
+| 特性 | 描述 |
+|---|---|
+| **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`** | 真正执行测试并提取精炼的失败摘要 |
+
+---
+
+## 6. v1.0 路线图
+
+| 里程碑 | 内容 |
+|---|---|
+| **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 结构。
+
+---
+*PRD v1.0 Revised — 2026-03-06*

package/README.md

@@ -0,0 +1,10 @@
+# ai-xray
+
+> Give your AI coding agent x-ray vision into any codebase.
+
+This package is currently a placeholder for an upcoming CLI tool designed specifically for LLMs and AI Agents. 
+It aims to provide structured, token-efficient, and deterministic local environment context (env, tree, read, diff, scout, init) for AI tools like aider, Cursor, and Cline.
+
+## Status
+
+**Work in progress.** Stay tuned.

package/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "ai-xray",
+    "version": "0.0.1",
+    "description": "Give your AI coding agent x-ray vision into any codebase.",
+    "main": "index.js",
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "ai",
+        "llm",
+        "agent",
+        "context",
+        "cli"
+    ],
+    "author": "10iii",
+    "license": "MIT"
+}