bhg-helper 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# BHG-helper
+
+BHG-helper 是一个本地可视化工具，用于让 Claude Code CLI（`claude.exe`）通过本机中转访问 DeepSeek API。
+
+核心目标：
+- 可视化配置 DeepSeek API Key
+- 本地保存配置，前端读取时自动脱敏
+- 启动 / 停止 / 重启 Anthropic ↔ DeepSeek 中转服务
+- 显示实时事件日志
+- 管理模型名映射，兼容 Claude Code 的模型选择逻辑
+
+## 架构
+
+```
+claude.exe
+  ↓ ANTHROPIC_BASE_URL=http://127.0.0.1:8787
+BHG-helper relay
+  ↓ Authorization: Bearer <DeepSeek API Key>
+DeepSeek API
+```
+
+BHG-helper 不修改 hosts，不复用其他工具的配置文件，也不依赖外部代理服务。
+
+## 快速开始
+
+```cmd
+scripts\start.bat
+```
+
+启动后打开：
+
+```text
+http://localhost:5173
+```
+
+在「中转服务」页：
+1. 填写 DeepSeek API Key
+2. 保存配置
+3. 点击启动
+4. 新终端运行 `claude`
+
+## API 配置设计
+
+BHG-helper 借鉴成熟 CLI 工具的配置方式，但使用自己的目录和文件：
+
+```text
+%USERPROFILE%\.bhg-helper\
+├── relay.config.json      # 中转端口、DeepSeek Key、模型映射
+├── config.json            # 预留运行配置
+├── credentials\           # 预留凭据目录
+├── logs\                  # 日志目录
+└── backups\               # 备份目录
+```
+
+关键实践：
+- **配置与程序分离**：程序目录可移动，用户配置保存在用户目录。
+- **密钥服务端保存**：UI 只显示脱敏值，保存时不会用脱敏值覆盖真实密钥。
+- **默认配置合并**：新增模型映射会自动叠加，不破坏用户自定义映射。
+- **环境变量可覆盖**：可通过 `BHG_HELPER_DIR` 指定配置目录。
+
+## 端口
+
+- `5173`：BHG-helper UI
+- `3001`：BHG-helper API
+- `8787`：Anthropic ↔ DeepSeek 中转服务
+
+## 常见问题
+
+| 现象 | 处理 |
+|---|---|
+| 页面提示 Key 未配置 | 在「中转服务」填 DeepSeek API Key 并保存 |
+| Claude Code 报模型不可用 | 重启 BHG-helper 中转，并在 `/model` 选择 deepseek 模型 |
+| 请求返回 401 | DeepSeek API Key 无效或余额不足 |
+| 端口被占用 | 在「中转服务」修改端口并保存 |
+
+## License
+
+MIT

package/api/app.ts

@@ -0,0 +1,53 @@
+/**
+ * BHG-helper API server
+ */
+import express, {
+  type Request,
+  type Response,
+  type NextFunction,
+} from 'express'
+import cors from 'cors'
+import { log } from './lib/logger.js'
+import { BHG_HELPER_DIR } from './lib/paths.js'
+import configRoutes from './routes/config.js'
+import backupRoutes from './routes/backups.js'
+import logRoutes from './routes/logs.js'
+import providerRoutes from './routes/providers.js'
+import relayRoutes from './routes/relay.js'
+import installRoutes from './routes/install.js'
+
+const app: express.Application = express()
+
+app.use(cors())
+app.use(express.json({ limit: '5mb' }))
+app.use(express.urlencoded({ extended: true, limit: '5mb' }))
+
+// request log
+app.use((req, _res, next) => {
+  if (req.path.startsWith('/api/')) {
+    log('INFO', 'http', `${req.method} ${req.path}`)
+  }
+  next()
+})
+
+app.use('/api/config', configRoutes)
+app.use('/api/backups', backupRoutes)
+app.use('/api/logs', logRoutes)
+app.use('/api/providers', providerRoutes)
+app.use('/api/relay', relayRoutes)
+app.use('/api/install', installRoutes)
+
+app.get('/api/health', (_req: Request, res: Response) => {
+  res.json({ ok: true, data: { bhgHelperDir: BHG_HELPER_DIR } })
+})
+
+app.use((error: Error, _req: Request, res: Response, _next: NextFunction) => {
+  log('ERR', 'http', error.message)
+  res.status(500).json({ ok: false, error: error.message })
+})
+
+app.use((req: Request, res: Response) => {
+  res.status(404).json({ ok: false, error: `API not found: ${req.path}` })
+})
+
+export default app

package/api/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Vercel deploy entry handler, for serverless deployment, please don't modify this file
+ */
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import app from './app.js';
+
+export default function handler(req: VercelRequest, res: VercelResponse) {
+  return app(req, res);
+}

package/api/lib/logger.ts

@@ -0,0 +1,65 @@
+/**
+ * 内存日志 + SSE 广播
+ */
+import type { Response } from 'express'
+
+export type LogLevel = 'INFO' | 'OK' | 'WARN' | 'ERR'
+
+export interface LogEntry {
+  id: number
+  ts: string
+  level: LogLevel
+  scope: string
+  message: string
+}
+
+const MAX_LOGS = 500
+const buffer: LogEntry[] = []
+let nextId = 1
+const sseClients = new Set<Response>()
+
+function nowIso(): string {
+  return new Date().toISOString().replace('T', ' ').slice(0, 19)
+}
+
+export function log(level: LogLevel, scope: string, message: string): LogEntry {
+  const entry: LogEntry = { id: nextId++, ts: nowIso(), level, scope, message }
+  buffer.push(entry)
+  if (buffer.length > MAX_LOGS) buffer.shift()
+
+  // 推送给 SSE 客户端
+  const payload = `data: ${JSON.stringify(entry)}\n\n`
+  for (const res of sseClients) {
+    try {
+      res.write(payload)
+    } catch {
+      // ignore
+    }
+  }
+
+  // 同时打到 stdout，方便开发时在终端看
+  const tag = `[${entry.level}] ${entry.scope}`
+  if (level === 'ERR') console.error(tag, message)
+  else if (level === 'WARN') console.warn(tag, message)
+  else console.log(tag, message)
+
+  return entry
+}
+
+export function listLogs(): LogEntry[] {
+  return buffer.slice()
+}
+
+export function addSseClient(res: Response): void {
+  res.setHeader('Content-Type', 'text/event-stream')
+  res.setHeader('Cache-Control', 'no-cache')
+  res.setHeader('Connection', 'keep-alive')
+  res.setHeader('X-Accel-Buffering', 'no')
+  res.flushHeaders?.()
+  // 启动时把历史日志先发过去
+  for (const entry of buffer) {
+    res.write(`data: ${JSON.stringify(entry)}\n\n`)
+  }
+  sseClients.add(res)
+  res.on('close', () => sseClients.delete(res))
+}

package/api/lib/paths.ts

@@ -0,0 +1,27 @@
+/**
+ * BHG-helper 运行时路径。
+ *
+ * 设计原则借鉴成熟 CLI 工具：
+ * - 项目运行目录与用户数据目录分离
+ * - API 配置集中存放
+ * - 日志、备份、凭据分目录管理
+ * - 可通过环境变量覆盖，便于迁移/打包
+ */
+import os from 'node:os'
+import path from 'node:path'
+
+const envDir = process.env.BHG_HELPER_DIR?.trim()
+export const BHG_HELPER_DIR = envDir
+  ? path.resolve(envDir)
+  : path.join(os.homedir(), '.bhg-helper')
+
+export const RUNTIME_CONFIG_FILE = path.join(BHG_HELPER_DIR, 'config.json')
+export const RELAY_CONFIG_FILE = path.join(BHG_HELPER_DIR, 'relay.config.json')
+export const CREDENTIALS_DIR = path.join(BHG_HELPER_DIR, 'credentials')
+export const LOGS_DIR = path.join(BHG_HELPER_DIR, 'logs')
+export const BACKUPS_DIR = path.join(BHG_HELPER_DIR, 'backups')
+
+// 旧版页面/接口仍引用这些常量；保留为 BHG-helper 自有文件，避免依赖 lucky 目录。
+export const BRIDGE_FILE = path.join(BHG_HELPER_DIR, 'bridge.json')
+export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.json')
+export const SETTINGS_FILE = path.join(BHG_HELPER_DIR, 'settings.json')

package/api/lib/providers.ts

@@ -0,0 +1,66 @@
+/**
+ * 预置 API Provider 配置
+ *
+ * 注意：LUCKY 仅作为 geo-bypass 通道使用，**不再使用其模型 API**。
+ * 这里的预设只列出"真正能用的"模型服务方。
+ */
+
+export interface ProviderPreset {
+  id: string
+  name: string
+  protocol: 'anthropic' | 'openai'
+  baseUrl?: string
+  notes: string
+  models: Array<{
+    id: string
+    label: string
+    tier: 'large' | 'middle' | 'small'
+    description: string
+  }>
+}
+
+export const PROVIDER_PRESETS: ProviderPreset[] = [
+  {
+    id: 'deepseek-official',
+    name: 'DeepSeek 官方',
+    protocol: 'openai',
+    baseUrl: 'https://api.deepseek.com',
+    notes:
+      'platform.deepseek.com 申请的 sk-… Key。DeepSeek V3 / R1 / V4-Flash 都是 OpenAI Chat Completions 兼容格式。',
+    models: [
+      {
+        id: 'deepseek-chat',
+        label: 'deepseek-chat (V3)',
+        tier: 'middle',
+        description: 'DeepSeek V3 · 通用对话与代码，128K 上下文',
+      },
+      {
+        id: 'deepseek-reasoner',
+        label: 'deepseek-reasoner (R1)',
+        tier: 'large',
+        description: 'DeepSeek R1 · 强推理，64K 上下文',
+      },
+      {
+        id: 'deepseek-v4-flash',
+        label: 'deepseek-v4-flash (V4 Flash)',
+        tier: 'small',
+        description: 'DeepSeek V4 Flash · 高速低成本版本（如果 API 已上线）',
+      },
+    ],
+  },
+  {
+    id: 'openai-compatible',
+    name: 'OpenAI 兼容端点（自定义）',
+    protocol: 'openai',
+    notes:
+      '任何 OpenAI Chat Completions 兼容服务。预留扩展位——目前主线只用 DeepSeek。',
+    models: [
+      {
+        id: 'deepseek-chat',
+        label: 'deepseek-chat',
+        tier: 'middle',
+        description: '默认转发到自定义端点的 deepseek-chat',
+      },
+    ],
+  },
+]

package/api/lib/repository.ts

@@ -0,0 +1,153 @@
+/**
+ * 配置文件的原子读写。
+ * 写入前自动复制当前文件到 backups/，保证可回滚。
+ */
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import {
+  BACKUPS_DIR,
+  BRIDGE_FILE,
+  CREDENTIALS_FILE,
+  SETTINGS_FILE,
+} from './paths.js'
+import { log } from './logger.js'
+
+export type Scope = 'bridge' | 'credentials' | 'settings'
+
+const SCOPE_TO_FILE: Record<Scope, string> = {
+  bridge: BRIDGE_FILE,
+  credentials: CREDENTIALS_FILE,
+  settings: SETTINGS_FILE,
+}
+
+const SCOPE_TO_DEFAULT_SCOPE_NAME: Record<Scope, string> = {
+  bridge: 'bridge',
+  credentials: 'credentials',
+  settings: 'settings',
+}
+
+async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true })
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function readJson<T = unknown>(file: string): Promise<T | null> {
+  if (!(await fileExists(file))) return null
+  const raw = await fs.readFile(file, 'utf-8')
+  if (!raw.trim()) return null
+  try {
+    return JSON.parse(raw) as T
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    log('ERR', 'repo', `JSON parse failed for ${path.basename(file)}: ${msg}`)
+    return null
+  }
+}
+
+async function backupCurrent(file: string, scope: Scope): Promise<string | null> {
+  if (!(await fileExists(file))) return null
+  await ensureDir(BACKUPS_DIR)
+  const ts = Date.now()
+  const base = path.basename(file).replace(/^\./, '')
+  const filename = `${base}.${SCOPE_TO_DEFAULT_SCOPE_NAME[scope]}.backup.${ts}`
+  const dest = path.join(BACKUPS_DIR, filename)
+  await fs.copyFile(file, dest)
+  log('INFO', 'repo', `auto-backup → ${filename}`)
+  return filename
+}
+
+export async function writeJson(
+  scope: Scope,
+  data: unknown
+): Promise<{ ok: true; backup: string | null; size: number }> {
+  const file = SCOPE_TO_FILE[scope]
+  const backup = await backupCurrent(file, scope)
+  const json = JSON.stringify(data, null, 2) + '\n'
+  // 原子写：写到临时文件再 rename
+  const tmp = file + '.tmp'
+  await fs.writeFile(tmp, json, 'utf-8')
+  await fs.rename(tmp, file)
+  const size = Buffer.byteLength(json, 'utf-8')
+  log('OK', 'repo', `wrote ${path.basename(file)} (${size} bytes)`)
+  return { ok: true, backup, size }
+}
+
+export async function listBackups(): Promise<
+  Array<{ filename: string; scope: string; size: number; createdAt: string }>
+> {
+  await ensureDir(BACKUPS_DIR)
+  const entries = await fs.readdir(BACKUPS_DIR, { withFileTypes: true })
+  const out: Array<{ filename: string; scope: string; size: number; createdAt: string }> = []
+  for (const e of entries) {
+    if (!e.isFile()) continue
+    if (!e.name.endsWith('.json') && !e.name.startsWith('.')) continue
+    const full = path.join(BACKUPS_DIR, e.name)
+    const stat = await fs.stat(full)
+    // 解析 scope
+    let scope = 'unknown'
+    if (e.name.startsWith('claude-thkj-bridge')) scope = 'bridge'
+    else if (e.name.startsWith('credentials')) scope = 'credentials'
+    else if (e.name.startsWith('settings')) scope = 'settings'
+    out.push({
+      filename: e.name,
+      scope,
+      size: stat.size,
+      createdAt: stat.mtime.toISOString(),
+    })
+  }
+  out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
+  return out
+}
+
+export async function deleteBackup(filename: string): Promise<void> {
+  // 安全：只允许删除 backups/ 下的文件
+  if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+    throw new Error('invalid filename')
+  }
+  const target = path.join(BACKUPS_DIR, filename)
+  await fs.unlink(target)
+  log('OK', 'repo', `deleted backup ${filename}`)
+}
+
+export async function restoreBackup(filename: string): Promise<{ scope: Scope }> {
+  if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
+    throw new Error('invalid filename')
+  }
+  const src = path.join(BACKUPS_DIR, filename)
+  if (!(await fileExists(src))) throw new Error('backup not found')
+
+  let scope: Scope
+  if (filename.startsWith('claude-thkj-bridge')) scope = 'bridge'
+  else if (filename.startsWith('credentials')) scope = 'credentials'
+  else if (filename.startsWith('settings')) scope = 'settings'
+  else throw new Error('cannot determine scope from filename')
+
+  const data = await readJson(src)
+  if (data == null) throw new Error('backup file is not valid JSON')
+  await writeJson(scope, data)
+  log('OK', 'repo', `restored ${filename} → ${scope}`)
+  return { scope }
+}
+
+export async function createManualBackup(
+  scope: Scope
+): Promise<{ filename: string }> {
+  const file = SCOPE_TO_FILE[scope]
+  if (!(await fileExists(file))) throw new Error(`${scope} file does not exist`)
+  await ensureDir(BACKUPS_DIR)
+  const ts = Date.now()
+  const base = path.basename(file).replace(/^\./, '')
+  const filename = `${base}.manual.${ts}`
+  const dest = path.join(BACKUPS_DIR, filename)
+  await fs.copyFile(file, dest)
+  log('OK', 'repo', `manual backup → ${filename}`)
+  return { filename }
+}

package/api/lib/types.ts

@@ -0,0 +1,43 @@
+/**
+ * 后端类型定义
+ */
+
+export interface ModelEntry {
+  id: string
+  label: string
+  tier: 'large' | 'middle' | 'small'
+  provider: string
+  context_window: number
+  default_max_tokens: number
+  max_tokens: number
+  pricing: {
+    currency: string
+    quota_type: string
+    pricing_group: string
+    input_per_1m_tokens: number
+    output_per_1m_tokens: number
+    cache_read_per_1m_tokens: number
+    cache_write_per_1m_tokens: number
+  }
+  description: string
+  protocol: 'anthropic' | 'openai'
+  enabled: boolean
+  available: boolean
+}
+
+export interface BridgeConfig {
+  bridgeModelCatalogCache?: {
+    models: ModelEntry[]
+    defaults: { large: string; middle: string; small: string }
+    pricing_version?: string
+    pricing_group?: string
+  }
+  additionalModelOptionsCache?: Array<{
+    value: string
+    label: string
+    description: string
+    descriptionForModel: string
+  }>
+  oauthAccount?: null | Record<string, unknown>
+  [key: string]: unknown
+}

package/api/relay/config.ts

@@ -0,0 +1,76 @@
+/**
+ * BHG-helper API 配置模块。
+ *
+ * 借鉴成熟 CLI 工具的配置设计：
+ * - 配置统一落在用户级运行目录，和程序文件分离
+ * - API Key 只在服务端保存，前端读取时脱敏
+ * - modelMap 使用默认值 + 用户覆盖的合并策略
+ * - 端口、上游地址、Provider 标识集中管理
+ */
+import { promises as fs } from 'node:fs'
+import { BHG_HELPER_DIR, RELAY_CONFIG_FILE } from '../lib/paths.js'
+import { log } from '../lib/logger.js'
+
+export interface RelayConfig {
+  port: number
+  deepseekApiKey: string
+  deepseekBaseUrl: string
+  modelMap: Record<string, string>
+  spoofProvider: string
+  verbose: boolean
+}
+
+const DEFAULT_CONFIG: RelayConfig = {
+  port: 8787,
+  deepseekApiKey: '',
+  deepseekBaseUrl: 'https://api.deepseek.com',
+  modelMap: {
+    'deepseek-v4-flash': 'deepseek-v4-flash',
+    'deepseek-v4-pro': 'deepseek-v4-pro',
+    'deepseek-chat': 'deepseek-v4-pro',
+    'deepseek-reasoner': 'deepseek-v4-pro',
+    'deepseek-v4-flash-cc': 'deepseek-v4-flash',
+    'deepseek-v4-pro-cc': 'deepseek-v4-pro',
+    'claude-opus-4-6': 'deepseek-v4-pro',
+    'claude-opus-4-6[1m]': 'deepseek-v4-pro',
+    'claude-opus-4-7': 'deepseek-v4-pro',
+    'claude-opus-4-7[1m]': 'deepseek-v4-pro',
+    'claude-opus-4-8': 'deepseek-v4-pro',
+    'claude-opus-4-8[1m]': 'deepseek-v4-pro',
+    'claude-sonnet-4-6': 'deepseek-v4-pro',
+    'claude-sonnet-4-6[1m]': 'deepseek-v4-pro',
+    'claude-haiku-4-5-20251001': 'deepseek-v4-flash',
+    'claude-haiku-4-5': 'deepseek-v4-flash',
+  },
+  spoofProvider: 'deepseek',
+  verbose: true,
+}
+
+export async function loadRelayConfig(): Promise<RelayConfig> {
+  let onDisk: Partial<RelayConfig> = {}
+  try {
+    const raw = await fs.readFile(RELAY_CONFIG_FILE, 'utf-8')
+    onDisk = JSON.parse(raw.replace(/^\uFEFF/, ''))
+  } catch {
+    return DEFAULT_CONFIG
+  }
+
+  return {
+    ...DEFAULT_CONFIG,
+    ...onDisk,
+    modelMap: { ...DEFAULT_CONFIG.modelMap, ...(onDisk.modelMap ?? {}) },
+  }
+}
+
+export async function saveRelayConfig(cfg: Partial<RelayConfig>): Promise<RelayConfig> {
+  const cur = await loadRelayConfig()
+  const next = { ...cur, ...cfg }
+  await fs.mkdir(BHG_HELPER_DIR, { recursive: true })
+  await fs.writeFile(RELAY_CONFIG_FILE, JSON.stringify(next, null, 2) + '\n', 'utf-8')
+  log('OK', 'relay', `relay config saved (port=${next.port}, base=${next.deepseekBaseUrl}, mapSize=${Object.keys(next.modelMap).length})`)
+  return next
+}
+
+export function getRelayConfigPath(): string {
+  return RELAY_CONFIG_FILE
+}