branching-chat-connector 0.1.0

package/claude-connector.mjs

@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+// 本机「陪读」连接器：把本机已登录的 Claude（Agent SDK）暴露成一个
+// OpenAI 兼容的流式 /v1/chat/completions，供 Branching Chat 前端在选用
+// `claude-cli` 模型时直接连接。只监听 127.0.0.1，不收集任何密钥。
+import http from 'node:http'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+
+const HOST = '127.0.0.1'
+const PORT = Number.parseInt(process.env.CLAUDE_CONNECTOR_PORT || '8765', 10)
+const MODEL = process.env.CLAUDE_CONNECTOR_MODEL?.trim() || undefined
+const MAX_BODY_BYTES = 5 * 1024 * 1024
+const TOKEN_FILE = path.join(os.homedir(), '.branching-chat-connector.json')
+
+const DEFAULT_ALLOWED_ORIGINS = [
+	'https://chat.branchingchat.xyz',
+	'https://staging.branchingchat.xyz',
+	'http://localhost:5173',
+	'http://127.0.0.1:5173',
+]
+const ALLOWED_ORIGINS = new Set(
+	((process.env.CLAUDE_CONNECTOR_ALLOWED_ORIGINS || '')
+		.split(',')
+		.map((value) => value.trim().replace(/\/+$/, ''))
+		.filter(Boolean)
+		.length
+		? process.env.CLAUDE_CONNECTOR_ALLOWED_ORIGINS.split(',')
+		: DEFAULT_ALLOWED_ORIGINS
+	)
+		.map((value) => value.trim().replace(/\/+$/, ''))
+		.filter(Boolean)
+)
+
+function loadOrCreateToken() {
+	const envToken = process.env.CLAUDE_CONNECTOR_TOKEN?.trim()
+	if (envToken) return { token: envToken, source: 'env' }
+	try {
+		const parsed = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf8'))
+		if (parsed && typeof parsed.token === 'string' && parsed.token.length >= 16) {
+			return { token: parsed.token, source: 'file' }
+		}
+	} catch {
+		// no existing token file; fall through to generate one
+	}
+	const token = crypto.randomBytes(24).toString('base64url')
+	try {
+		fs.writeFileSync(TOKEN_FILE, `${JSON.stringify({ token }, null, 2)}\n`, { mode: 0o600 })
+		fs.chmodSync(TOKEN_FILE, 0o600)
+	} catch {
+		// best effort; token still works for this run even if it can't be persisted
+	}
+	return { token, source: 'generated' }
+}
+
+const { token: PAIRING_TOKEN, source: TOKEN_SOURCE } = loadOrCreateToken()
+
+// 系统提示以网页端「编辑系统 Prompt」为准：请求里携带的 system 消息会直接作为
+// SDK systemPrompt。只有当网页没有下发任何 system 时，才用这个极简兜底（或下面的环境变量覆盖）。
+const FALLBACK_SYSTEM_PROMPT =
+	process.env.CLAUDE_CONNECTOR_SYSTEM_PROMPT?.trim() ||
+	'请用简体中文，清晰、有条理地回答。你没有文件读写或命令执行能力，直接用文字回答即可。'
+
+// 订阅登录链路上 Claude 的思考文本会被加密屏蔽（只回签名、不回文字）。思考确实发生时
+// 用这句占位，让前端的「思考」折叠至少能显示出来，而不是空白。
+const THINKING_REDACTED_NOTE = '（本机 Claude 思考过程不外显：订阅链路只返回加密签名，没有可显示的思考文本。）'
+
+function normalizeOrigin(origin) {
+	return typeof origin === 'string' ? origin.trim().replace(/\/+$/, '') : ''
+}
+
+function isAllowedOrigin(origin) {
+	// No Origin header = non-browser/local caller (curl, same process) — trusted on loopback.
+	if (!origin) return true
+	return ALLOWED_ORIGINS.has(normalizeOrigin(origin))
+}
+
+function applyCors(req, res) {
+	const origin = normalizeOrigin(req.headers.origin)
+	// Only reflect explicitly allow-listed origins; a disallowed site gets no ACAO and is blocked.
+	if (origin && ALLOWED_ORIGINS.has(origin)) {
+		res.setHeader('Access-Control-Allow-Origin', req.headers.origin)
+		// HTTPS sites (e.g. chat.branchingchat.xyz) calling http://127.0.0.1 trigger Chrome's
+		// Private Network Access preflight; acknowledge it so the loopback request isn't blocked.
+		if (req.headers['access-control-request-private-network'] === 'true') {
+			res.setHeader('Access-Control-Allow-Private-Network', 'true')
+		}
+	}
+	res.setHeader('Vary', 'Origin')
+	res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+	res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Pairing-Token')
+	res.setHeader('Access-Control-Max-Age', '600')
+}
+
+function getRequestToken(req) {
+	const header = req.headers['x-pairing-token']
+	if (typeof header === 'string' && header.trim()) return header.trim()
+	const auth = req.headers['authorization']
+	if (typeof auth === 'string') {
+		const match = /^Bearer\s+(.+)$/i.exec(auth.trim())
+		if (match) return match[1].trim()
+	}
+	return ''
+}
+
+function tokenValid(req) {
+	const provided = getRequestToken(req)
+	if (!provided || !PAIRING_TOKEN) return false
+	const a = Buffer.from(provided)
+	const b = Buffer.from(PAIRING_TOKEN)
+	if (a.length !== b.length) return false
+	return crypto.timingSafeEqual(a, b)
+}
+
+function sendJson(res, status, body) {
+	res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
+	res.end(JSON.stringify(body))
+}
+
+function extractText(content) {
+	if (typeof content === 'string') return content
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => {
+				if (part && typeof part === 'object') {
+					if (part.type === 'text' && typeof part.text === 'string') return part.text
+					if (part.type === 'image_url') return '［图片：本机 Claude 暂不支持图片，已忽略］'
+				}
+				return ''
+			})
+			.filter(Boolean)
+			.join('\n')
+	}
+	return ''
+}
+
+function extractSystemPrompt(messages) {
+	const parts = []
+	for (const message of Array.isArray(messages) ? messages : []) {
+		if (message?.role !== 'system') continue
+		const text = extractText(message.content).trim()
+		if (text) parts.push(text)
+	}
+	return parts.join('\n\n')
+}
+
+// system 消息已经单独抽给 SDK 的 systemPrompt，这里只拍平用户/助手对话。
+function buildPrompt(messages) {
+	const lines = []
+	for (const message of Array.isArray(messages) ? messages : []) {
+		if (message?.role === 'system') continue
+		const text = extractText(message?.content).trim()
+		if (!text) continue
+		const role = message.role === 'assistant' ? '助手' : '用户'
+		lines.push(`${role}：${text}`)
+	}
+	return lines.join('\n\n')
+}
+
+function buildQueryOptions({ stream, systemPrompt, thinking }) {
+	const options = {
+		systemPrompt: systemPrompt || FALLBACK_SYSTEM_PROMPT,
+		allowedTools: [],
+		settingSources: [],
+		maxTurns: 1,
+		includePartialMessages: stream,
+	}
+	if (MODEL) options.model = MODEL
+	if (thinking) options.thinking = { type: 'adaptive' }
+	return options
+}
+
+function streamEventText(message) {
+	if (message?.type !== 'stream_event') return ''
+	const event = message.event
+	if (event?.type !== 'content_block_delta') return ''
+	const delta = event.delta
+	if (delta?.type === 'text_delta' && typeof delta.text === 'string') return delta.text
+	return ''
+}
+
+function streamEventThinking(message) {
+	if (message?.type !== 'stream_event') return ''
+	const event = message.event
+	if (event?.type !== 'content_block_delta') return ''
+	const delta = event.delta
+	if (delta?.type === 'thinking_delta' && typeof delta.thinking === 'string') return delta.thinking
+	return ''
+}
+
+function isThinkingBlockStart(message) {
+	if (message?.type !== 'stream_event') return false
+	const event = message.event
+	if (event?.type !== 'content_block_start') return false
+	const blockType = event.content_block?.type
+	return blockType === 'thinking' || blockType === 'redacted_thinking'
+}
+
+function assistantMessageText(message) {
+	if (message?.type !== 'assistant') return ''
+	const content = message.message?.content
+	if (!Array.isArray(content)) return ''
+	return content
+		.map((block) =>
+			block?.type === 'text' && typeof block.text === 'string' ? block.text : ''
+		)
+		.filter(Boolean)
+		.join('')
+}
+
+function assistantMessageThinking(message) {
+	if (message?.type !== 'assistant') return ''
+	const content = message.message?.content
+	if (!Array.isArray(content)) return ''
+	return content
+		.map((block) =>
+			block?.type === 'thinking' && typeof block.thinking === 'string' ? block.thinking : ''
+		)
+		.filter(Boolean)
+		.join('')
+}
+
+function assistantHasThinkingBlock(message) {
+	if (message?.type !== 'assistant') return false
+	const content = message.message?.content
+	return (
+		Array.isArray(content) &&
+		content.some((block) => block?.type === 'thinking' || block?.type === 'redacted_thinking')
+	)
+}
+
+function sseData(payload) {
+	return `data: ${JSON.stringify(payload)}\n\n`
+}
+
+// 识别 Claude 订阅用量/速率达到上限的错误（订阅链路常见的几种措辞）。
+function isCliLimitText(text) {
+	return /usage limit|rate.?limit|rate_limit|limit reached|limit_reached|too many requests|overloaded|429|quota|用量.{0,4}上限|额度|限额/i.test(
+		String(text || '')
+	)
+}
+
+async function handleChatCompletion(req, res, body) {
+	const stream = Boolean(body?.stream)
+	const prompt = buildPrompt(body?.messages)
+	const systemPrompt = extractSystemPrompt(body?.messages)
+	const thinking = body?.thinkingMode === 'enabled'
+	if (!prompt) {
+		sendJson(res, 400, {
+			error: { message: 'messages 为空，无法生成回答。', code: 'empty_messages' },
+		})
+		return
+	}
+
+	const routeHeaders = {
+		'x-chat-provider': 'claude-cli',
+		'x-chat-model': MODEL || 'claude-code',
+		'x-chat-route': 'local:claude-cli',
+	}
+
+	if (!stream) {
+		try {
+			let full = ''
+			let reasoning = ''
+			let sawThinking = false
+			for await (const message of query({
+				prompt,
+				options: buildQueryOptions({ stream: false, systemPrompt, thinking }),
+			})) {
+				full += assistantMessageText(message)
+				reasoning += assistantMessageThinking(message)
+				if (assistantHasThinkingBlock(message)) sawThinking = true
+			}
+			const reasoningOut = thinking
+				? reasoning.trim() || (sawThinking ? THINKING_REDACTED_NOTE : '')
+				: ''
+			res.writeHead(200, { ...routeHeaders, 'Content-Type': 'application/json; charset=utf-8' })
+			res.end(
+				JSON.stringify({
+					choices: [
+						{
+							message: {
+								role: 'assistant',
+								content: full,
+								...(reasoningOut ? { reasoning_content: reasoningOut } : {}),
+							},
+							finish_reason: 'stop',
+						},
+					],
+				})
+			)
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error)
+			if (isCliLimitText(detail)) {
+				sendJson(res, 429, {
+					error: { message: `本机 Claude 用量已达上限：${detail}`, code: 'cli_rate_limited' },
+				})
+			} else {
+				sendJson(res, 502, {
+					error: { message: `本机 Claude 连接器出错：${detail}`, code: 'connector_error' },
+				})
+			}
+		}
+		return
+	}
+
+	res.writeHead(200, {
+		...routeHeaders,
+		'Content-Type': 'text/event-stream; charset=utf-8',
+		'Cache-Control': 'no-cache, no-transform',
+		Connection: 'keep-alive',
+	})
+	let sentAny = false
+	let reasoningSent = false
+	let thinkingNoteSent = false
+	const emitThinkingNote = () => {
+		if (thinkingNoteSent || reasoningSent) return
+		thinkingNoteSent = true
+		res.write(sseData({ choices: [{ delta: { reasoning_content: THINKING_REDACTED_NOTE } }] }))
+	}
+	try {
+		for await (const message of query({
+			prompt,
+			options: buildQueryOptions({ stream: true, systemPrompt, thinking }),
+		})) {
+			// 思考块出现就先亮出折叠（订阅链路里随后的 thinking_delta 文本是空的）。
+			// 仅当用户开启思考模式时才显示；关闭时即便底层默认触发思考块也不外显。
+			if (isThinkingBlockStart(message)) {
+				if (thinking) emitThinkingNote()
+				continue
+			}
+			const reasoning = thinking ? streamEventThinking(message) : ''
+			if (reasoning) {
+				reasoningSent = true
+				res.write(sseData({ choices: [{ delta: { reasoning_content: reasoning } }] }))
+				continue
+			}
+			const text = streamEventText(message)
+			if (text) {
+				sentAny = true
+				res.write(sseData({ choices: [{ delta: { content: text } }] }))
+				continue
+			}
+			if (
+				message?.type === 'result' &&
+				message.subtype &&
+				message.subtype !== 'success'
+			) {
+				if (isCliLimitText(message.subtype)) {
+					res.write(sseData({ x_limit: 'cli_rate_limited' }))
+				}
+				if (!sentAny) {
+					res.write(
+						sseData({
+							choices: [{ delta: { content: `本机 Claude 返回错误：${message.subtype}` } }],
+						})
+					)
+				}
+			}
+		}
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error)
+		if (isCliLimitText(detail)) {
+			res.write(sseData({ x_limit: 'cli_rate_limited' }))
+		}
+		if (!sentAny) {
+			res.write(sseData({ choices: [{ delta: { content: `本机 Claude 连接器出错：${detail}` } }] }))
+		}
+	}
+	res.write(sseData({ choices: [{ delta: {}, finish_reason: 'stop' }] }))
+	res.write('data: [DONE]\n\n')
+	res.end()
+}
+
+const server = http.createServer((req, res) => {
+	applyCors(req, res)
+
+	if (req.method === 'OPTIONS') {
+		res.writeHead(204)
+		res.end()
+		return
+	}
+
+	const url = new URL(req.url || '/', `http://${HOST}:${PORT}`)
+	const originOk = isAllowedOrigin(req.headers.origin)
+
+	if (req.method === 'GET' && url.pathname === '/health') {
+		sendJson(res, 200, {
+			ok: true,
+			provider: 'claude-cli',
+			model: MODEL || 'claude-code',
+			requiresPairing: true,
+			paired: tokenValid(req),
+		})
+		return
+	}
+
+	if (req.method === 'POST' && url.pathname === '/pair') {
+		// Hand the pairing token only to allow-listed browser origins (or local non-browser callers).
+		if (!originOk) {
+			sendJson(res, 403, {
+				error: { message: '该来源未被授权配对。', code: 'origin_not_allowed' },
+			})
+			return
+		}
+		sendJson(res, 200, { ok: true, token: PAIRING_TOKEN, model: MODEL || 'claude-code' })
+		return
+	}
+
+	if (req.method === 'POST' && url.pathname === '/v1/chat/completions') {
+		if (!originOk) {
+			sendJson(res, 403, {
+				error: { message: '该来源未被授权访问本机 Claude。', code: 'origin_not_allowed' },
+			})
+			return
+		}
+		if (!tokenValid(req)) {
+			sendJson(res, 401, {
+				error: { message: '未配对或配对令牌失效，请在设置里重新配对。', code: 'unauthorized' },
+			})
+			return
+		}
+		let received = 0
+		const chunks = []
+		req.on('data', (chunk) => {
+			received += chunk.length
+			if (received > MAX_BODY_BYTES) {
+				sendJson(res, 413, { error: { message: '请求体过大。', code: 'payload_too_large' } })
+				req.destroy()
+				return
+			}
+			chunks.push(chunk)
+		})
+		req.on('end', () => {
+			if (res.writableEnded) return
+			let body
+			try {
+				body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+			} catch {
+				sendJson(res, 400, {
+					error: { message: '请求体不是合法 JSON。', code: 'invalid_json' },
+				})
+				return
+			}
+			handleChatCompletion(req, res, body).catch((error) => {
+				if (res.writableEnded) return
+				const detail = error instanceof Error ? error.message : String(error)
+				sendJson(res, 500, { error: { message: detail, code: 'connector_error' } })
+			})
+		})
+		return
+	}
+
+	sendJson(res, 404, { error: { message: 'Not found', code: 'not_found' } })
+})
+
+server.listen(PORT, HOST, () => {
+	const tokenSourceLabel =
+		TOKEN_SOURCE === 'env'
+			? '来自环境变量 CLAUDE_CONNECTOR_TOKEN'
+			: TOKEN_SOURCE === 'file'
+				? `来自 ${TOKEN_FILE}`
+				: `已生成并保存到 ${TOKEN_FILE}`
+	process.stdout.write(`Claude 陪读连接器已启动：http://${HOST}:${PORT}\n`)
+	process.stdout.write(
+		`模型：${MODEL || '（SDK 默认）'}；健康检查 GET /health；配对 POST /pair；聊天 POST /v1/chat/completions\n`
+	)
+	process.stdout.write(`允许的网页来源：${[...ALLOWED_ORIGINS].join('，') || '（无）'}\n`)
+	process.stdout.write(`配对令牌（${tokenSourceLabel}）：${PAIRING_TOKEN}\n`)
+	process.stdout.write(
+		'在网页设置里点「一键配对」即可自动获取上面的令牌；也可手动复制。只有列表里的来源才能配对。\n'
+	)
+	process.stdout.write('凭证使用本机已登录的 Claude（或 ANTHROPIC_API_KEY），连接器不收集任何密钥。\n')
+})

package/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "branching-chat-connector",
+	"version": "0.1.0",
+	"description": "本机「陪读」连接器：把你已登录的 Claude（Agent SDK）暴露成 OpenAI 兼容接口，供 Branching Chat 的「claude-cli（本机）」模型调用。只监听 127.0.0.1，不收集任何密钥。",
+	"type": "module",
+	"bin": "claude-connector.mjs",
+	"files": [
+		"claude-connector.mjs"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"@anthropic-ai/claude-agent-sdk": "^0.3.158"
+	},
+	"license": "MIT"
+}