@bachi/pi-coder 1.0.0 → 1.1.0

package/extensions/mcp/fixtures/fake-mcp-server.mjs

@@ -0,0 +1,155 @@
+/**
+ * fake-mcp-server.mjs — client.test.ts 用的假 MCP stdio 服务端。
+ *
+ * 只实现测试需要的那部分协议：newline-JSON 的 initialize / tools/list / tools/call，
+ * 外加几个「难形状」的返回值（图片、resource、错误、超时、退出、未实现方法）。
+ * 事实基准是真实 wechat-local-mcp 的响应形状（protocolVersion 2025-06-18）。
+ */
+
+const TOOLS = [
+	{
+		name: "echo",
+		description: "回显传入的参数（JSON 文本）",
+		inputSchema: {
+			type: "object",
+			properties: { text: { type: "string" }, nested: { type: "object" } },
+			required: ["text"],
+		},
+		annotations: { readOnlyHint: true },
+	},
+	{ name: "no_schema", description: "没有 inputSchema 的工具" },
+	{ name: "fail", description: "返回 isError: true", inputSchema: { type: "object", properties: {} } },
+	{
+		name: "image",
+		description: "返回一个 image 内容块",
+		inputSchema: { type: "object", properties: {} },
+	},
+	{ name: "resource", description: "返回 resource 内容块", inputSchema: { type: "object", properties: {} } },
+	{ name: "delay", description: "延迟 N 毫秒后返回", inputSchema: { type: "object", properties: { ms: { type: "number" } } } },
+	{ name: "exit", description: "直接退出进程", inputSchema: { type: "object", properties: {} } },
+	{ name: "stderr", description: "往 stderr 写一行再返回", inputSchema: { type: "object", properties: {} } },
+	{ name: "server_request", description: "向客户端发一个反向请求再返回", inputSchema: { type: "object", properties: {} } },
+];
+
+const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+
+let buffer = "";
+let nextServerRequestId = 1000;
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	buffer += chunk;
+	let index = buffer.indexOf("\n");
+	while (index >= 0) {
+		const line = buffer.slice(0, index).trim();
+		buffer = buffer.slice(index + 1);
+		if (line) handleLine(line);
+		index = buffer.indexOf("\n");
+	}
+});
+
+function send(message) {
+	process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function respond(id, result) {
+	send({ jsonrpc: "2.0", id, result });
+}
+
+function respondError(id, code, message) {
+	send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function handleLine(line) {
+	let message;
+	try {
+		message = JSON.parse(line);
+	} catch {
+		return;
+	}
+
+	// 客户端对我们反向请求的回复（错误响应也要看得见）。
+	if (!("method" in message) && "id" in message && message.id >= 1000) {
+		process.stderr.write(
+			`server request ${message.id} answered: ${message.error ? `error ${message.error.code}` : "result"}\n`,
+		);
+		return;
+	}
+	if (!("method" in message)) return;
+
+	if (message.method === "notifications/cancelled") {
+		process.stderr.write(`cancelled request ${message.params?.requestId}: ${message.params?.reason}\n`);
+		return;
+	}
+	if (!("id" in message)) return;
+
+	switch (message.method) {
+		case "initialize":
+			respond(message.id, {
+				protocolVersion: "2025-06-18",
+				capabilities: { tools: { listChanged: false } },
+				serverInfo: { name: "fake-mcp-server", version: "9.9.9" },
+			});
+			return;
+		case "tools/list":
+			respond(message.id, { tools: TOOLS });
+			return;
+		case "tools/call":
+			handleCall(message);
+			return;
+		default:
+			respondError(message.id, -32601, `Method not found: ${message.method}`);
+	}
+}
+
+function handleCall(message) {
+	const name = message.params?.name;
+	const args = message.params?.arguments ?? {};
+	switch (name) {
+		case "echo":
+			respond(message.id, { content: [{ type: "text", text: JSON.stringify(args) }] });
+			return;
+		case "fail":
+			respond(message.id, {
+				content: [{ type: "text", text: "工具内部失败了" }],
+				isError: true,
+			});
+			return;
+		case "image":
+			respond(message.id, {
+				content: [
+					{ type: "text", text: "这是一张图片" },
+					{ type: "image", data: PNG, mimeType: "image/png" },
+					{ type: "audio", data: "AAAA", mimeType: "audio/wav" },
+					{ type: "resource", resource: { uri: "file:///tmp/x.txt", mimeType: "text/plain", text: "resource 文本" } },
+					{ type: "resource", resource: { uri: "file:///tmp/big.bin", mimeType: "application/octet-stream", blob: "AAECAw==" } },
+					{ type: "resource_link", uri: "https://example.com/a", name: "链接名" },
+				],
+			});
+			return;
+		case "resource":
+			respond(message.id, { content: [{ type: "resource", resource: { uri: "x", blob: "AAECAw==" } }] });
+			return;
+		case "delay": {
+			const ms = typeof args.ms === "number" ? args.ms : 100;
+			setTimeout(() => respond(message.id, { content: [{ type: "text", text: `延迟 ${ms}ms` }] }), ms);
+			return;
+		}
+		case "exit":
+			setTimeout(() => process.exit(3), 10);
+			respond(message.id, { content: [{ type: "text", text: "bye" }] });
+			return;
+		case "server_request": {
+			// 反向请求：客户端应该回一个「未实现」错误，而不是傻等。
+			send({ jsonrpc: "2.0", id: nextServerRequestId++, method: "roots/list" });
+			respond(message.id, { content: [{ type: "text", text: "server request sent" }] });
+			return;
+		}
+		case "stderr":
+			process.stderr.write("这是一行诊断输出\n");
+			respond(message.id, { content: [{ type: "text", text: "ok" }] });
+			return;
+		default:
+			respondError(message.id, -32602, `Unknown tool: ${name}`);
+	}
+}

package/extensions/mcp/fixtures/token-helper.mjs

@@ -0,0 +1,51 @@
+/**
+ * token-helper.mjs — headers-command 测试用的假"取 token 命令"。
+ *
+ * 三种模式（用来覆盖真实场景里头的三种行为）：
+ *   --file <路径> 每次运行取下一个 token（`token-1`、`token-2`…），计数写在文件里
+ *                 → 模拟"刷新后 token 会变"（能验证 401 后重试）
+ *   --fixed <值> 每次运行都返回同一个 token → 模拟"命令没取到新 token"（不该重试）
+ *   --fail        非零退出并往 stderr 写一行 → 模拟命令坏了
+ *   --lines       用 `Key: Value` 行格式输出（而不是 JSON）
+ *
+ * 输出严格照契约：一行 JSON 对象，或一行 `Name: Value`。
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+	const index = args.indexOf(name);
+	return index === -1 ? undefined : args[index + 1];
+};
+
+if (args.includes("--fail")) {
+	process.stderr.write("token 服务连不上\n");
+	process.exit(3);
+}
+
+const fixed = flag("--fixed");
+const counterFile = flag("--file");
+
+let token;
+if (fixed !== undefined) {
+	token = fixed;
+} else if (counterFile) {
+	let counter = 0;
+	try {
+		counter = Number.parseInt(readFileSync(counterFile, "utf8").trim(), 10) || 0;
+	} catch {
+		counter = 0;
+	}
+	counter += 1;
+	writeFileSync(counterFile, String(counter));
+	token = `token-${counter}`;
+} else {
+	token = "token-fixed";
+}
+
+if (args.includes("--lines")) {
+	process.stdout.write(`Authorization: Bearer ${token}\nX-Tenant: acme\n`);
+} else {
+	process.stdout.write(`${JSON.stringify({ Authorization: `Bearer ${token}` })}\n`);
+}

package/extensions/mcp/headers-command.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for headers-command.ts — 动态请求头（跑命令取 header）。
+ *
+ * Run with:  node --test clients/pi/extensions/mcp/headers-command.test.ts
+ *
+ * 两条边界最要紧，都直接断言：
+ *   - **绝不泄露头值**：诊断只用 `describeHeaderNames`，解析失败也不能回显命令输出（输出可能是整段 token）。
+ *   - **失败不致命**：命令挂了要抛一个可读错误给上层降级，而不是静默产出空头。
+ * 真实命令执行用 `node -e`（不 mock exec），超时用例故意睡过头。
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+	DEFAULT_HEADERS_COMMAND_TIMEOUT_MS,
+	describeHeaderNames,
+	headersSignature,
+	mergeHeaders,
+	parseHeadersOutput,
+	resolveCommandHeaders,
+} from "./headers-command.ts";
+
+const SECRET = "s3cr3t-token-value";
+
+describe("parseHeadersOutput", () => {
+	it("扁平 JSON 对象", () => {
+		const { headers, warnings } = parseHeadersOutput('{"Authorization":"Bearer x","X-Tenant":"acme"}');
+		assert.deepEqual(headers, { Authorization: "Bearer x", "X-Tenant": "acme" });
+		assert.deepEqual(warnings, []);
+	});
+
+	it("带 headers 包装的 JSON（有些 helper 会包一层）", () => {
+		const { headers } = parseHeadersOutput('{"headers":{"Authorization":"Bearer x"},"expires_in":3600}');
+		assert.deepEqual(headers, { Authorization: "Bearer x" });
+	});
+
+	it("Key: Value 行（手写命令最省事的形式）", () => {
+		const { headers } = parseHeadersOutput("Authorization: Bearer x\nX-Tenant: acme\n");
+		assert.deepEqual(headers, { Authorization: "Bearer x", "X-Tenant": "acme" });
+	});
+
+	it("值里的冒号不会被切开", () => {
+		const { headers } = parseHeadersOutput("Authorization: Bearer a:b:c");
+		assert.equal(headers.Authorization, "Bearer a:b:c");
+	});
+
+	it("非字符串值静默丢弃（expires_in 这类常见）", () => {
+		const { headers, warnings } = parseHeadersOutput('{"Authorization":"Bearer x","expires_in":3600,"n":null}');
+		assert.deepEqual(headers, { Authorization: "Bearer x" });
+		assert.deepEqual(warnings, []);
+	});
+
+	it("空值记 warning 并丢弃", () => {
+		const { headers, warnings } = parseHeadersOutput('{"Authorization":"","X-Ok":"y"}');
+		assert.deepEqual(headers, { "X-Ok": "y" });
+		assert.equal(warnings.length, 1);
+		assert.match(warnings[0] ?? "", /Authorization 的值为空/);
+	});
+
+	it("非法头名记 warning 并丢弃", () => {
+		const { headers, warnings } = parseHeadersOutput('{"Bad Header":"x","Good":"y"}');
+		assert.deepEqual(headers, { Good: "y" });
+		assert.match(warnings[0] ?? "", /非法字符/);
+	});
+
+	it("空输出 = 无头（不是错误）", () => {
+		assert.deepEqual(parseHeadersOutput("   \n"), { headers: {}, warnings: [] });
+	});
+
+	it("无法解析时报错，且**不回显输出内容**", () => {
+		assert.throws(
+			() => parseHeadersOutput(`不给你解析 ${SECRET}`),
+			(error: unknown) => {
+				const message = error instanceof Error ? error.message : String(error);
+				assert.match(message, /无法解析/);
+				assert.ok(!message.includes(SECRET), "错误信息里不能出现命令输出");
+				return true;
+			},
+		);
+	});
+
+	it("JSON 数组 / 裸标量 → 报错（不当成头行处理）", () => {
+		assert.throws(() => parseHeadersOutput("[1,2]"), /无法解析/);
+		assert.throws(() => parseHeadersOutput("42"), /无法解析/);
+	});
+});
+
+describe("resolveCommandHeaders", () => {
+	it("跑真实命令并解析 JSON 输出", async () => {
+		const result = await resolveCommandHeaders({
+			command: `node -e 'console.log(JSON.stringify({Authorization:"Bearer ${SECRET}"}))'`,
+		});
+		assert.deepEqual(result.headers, { Authorization: `Bearer ${SECRET}` });
+		assert.deepEqual(result.names, ["Authorization"]);
+	});
+
+	it("非零退出 → 错误信息带第一行 stderr", async () => {
+		await assert.rejects(
+			() => resolveCommandHeaders({ command: "node -e 'console.error(\"token 过期了\"); process.exit(3)'" }),
+			(error: unknown) => {
+				const message = error instanceof Error ? error.message : String(error);
+				assert.match(message, /退出码非 0/);
+				assert.match(message, /token 过期了/);
+				return true;
+			},
+		);
+	});
+
+	it("超过 timeout 直接失败（不会永远挂着）", async () => {
+		await assert.rejects(
+			() =>
+				resolveCommandHeaders(
+					{ command: "node -e 'setTimeout(()=>{}, 5000)'", timeoutMs: 150 },
+					{},
+				),
+			(error: unknown) => {
+				assert.match(error instanceof Error ? error.message : "", /超时/);
+				return true;
+			},
+		);
+	});
+
+	it("AbortSignal 能取消命令", async () => {
+		const controller = new AbortController();
+		const pending = resolveCommandHeaders(
+			{ command: "node -e 'setTimeout(()=>{}, 5000)'", timeoutMs: 4000 },
+			{ signal: controller.signal },
+		);
+		setTimeout(() => controller.abort(), 50);
+		await assert.rejects(pending);
+	});
+
+	it("默认超时是 10s（够跑一次钥匙串查询）", () => {
+		assert.equal(DEFAULT_HEADERS_COMMAND_TIMEOUT_MS, 10_000);
+	});
+
+	it("命令输出多个头（Key: Value 形式）", async () => {
+		const result = await resolveCommandHeaders({
+			command: `printf 'Authorization: Bearer ${SECRET}\\nX-Tenant: acme\\n'`,
+		});
+		assert.deepEqual(result.headers, { Authorization: `Bearer ${SECRET}`, "X-Tenant": "acme" });
+	});
+});
+
+describe("mergeHeaders", () => {
+	it("动态头覆盖静态头（它是更新鲜的凭据）", () => {
+		const merged = mergeHeaders({ Authorization: "Bearer old", "X-Static": "keep" }, { Authorization: "Bearer new" });
+		assert.deepEqual(merged, { Authorization: "Bearer new", "X-Static": "keep" });
+	});
+
+	it("没有动态头时保持静态头不变", () => {
+		assert.deepEqual(mergeHeaders({ A: "1" }, {}), { A: "1" });
+	});
+});
+
+describe("describeHeaderNames / headersSignature", () => {
+	it("只输出头名，绝不输出值", () => {
+		const text = describeHeaderNames({ Authorization: `Bearer ${SECRET}`, "X-Tenant": "acme" });
+		assert.equal(text, "Authorization, X-Tenant");
+		assert.ok(!text.includes(SECRET));
+	});
+
+	it("无头时给一个明确的占位", () => {
+		assert.equal(describeHeaderNames({}), "(无)");
+	});
+
+	it("签名与键序无关（用于判断头是否真的变了）", () => {
+		assert.equal(headersSignature({ A: "1", B: "2" }), headersSignature({ B: "2", A: "1" }));
+		assert.notEqual(headersSignature({ A: "1" }), headersSignature({ A: "2" }));
+	});
+});

package/extensions/mcp/headers-command.ts

@@ -0,0 +1,203 @@
+/**
+ * headers-command.ts — 动态请求头：跑一条命令、把它的输出解析成 HTTP 头。
+ *
+ * 这是 OAuth 的"便宜档"（对标 Claude Code 的 `headersHelper`、Codex 的 `http_headers_helper`）：
+ * 很多 SaaS MCP 既支持 OAuth，也支持静态 token 走 header（GitHub PAT、Context7 的 `CONTEXT7_API_KEY`、
+ * Sentry / Figma 的 token）。与其为一个 header 实现整套 OAuth 2.1 + 发现 + DCR + 回调，
+ * 不如让用户写一条命令把 token 取出来 —— 命令自己去读钥匙串、跑 `opencode auth`、解密文件都行。
+ *
+ * 设计边界：
+ *   - **不 import pi**（与 config/protocol/tools/client 一致），所以能直接 `node --test`。
+ *   - **绝不记录头的值**：诊断只输出头的名字（见 `describeHeaderNames`）。命令的输出可能整段都是密钥，
+ *     解析失败时也不回显原文 —— 只报"解析失败 + 前 N 字节的形状提示"，避免把 token 写进日志。
+ *   - 失败**不致命**：命令挂了就退回静态 headers 继续连，把失败记进诊断；真被 401 时错误信息里会带上
+ *     这条失败原因，用户才知道该去修命令，而不是以为 token 不对。
+ */
+
+import { exec } from "node:child_process";
+
+/** 头命令默认超时：只是取个 token，不该像工具调用那样等两分钟。 */
+export const DEFAULT_HEADERS_COMMAND_TIMEOUT_MS = 10_000;
+
+/** 命令输出的采集上限：正常就几十字节，超过这个量级说明命令写错了。 */
+const MAX_OUTPUT_BYTES = 64 * 1024;
+
+/** HTTP 头名允许的字符（RFC 7230 token）。 */
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+export interface HeadersCommandSpec {
+	command: string;
+	timeoutMs?: number;
+	/** 覆盖工作目录（默认继承当前进程）。 */
+	cwd?: string;
+	env?: Record<string, string>;
+}
+
+export interface ResolvedHeaders {
+	/** 解析出来的动态头（可能为空 —— 命令成功但没输出头）。 */
+	headers: Record<string, string>;
+	/** 命令原始输出里出现过的头名，用于诊断（不含值）。 */
+	names: string[];
+	/** 非致命问题（被丢掉的头、格式提示等）。 */
+	warnings: string[];
+}
+
+/**
+ * 运行头命令并解析结果。失败（超时/非零退出/输出不可解析）时抛错，由调用方决定降级策略。
+ */
+export async function resolveCommandHeaders(
+	spec: HeadersCommandSpec,
+	options: { signal?: AbortSignal } = {},
+): Promise<ResolvedHeaders> {
+	const stdout = await runCommand(spec, options.signal);
+	const parsed = parseHeadersOutput(stdout);
+	return { headers: parsed.headers, names: Object.keys(parsed.headers), warnings: parsed.warnings };
+}
+
+function runCommand(spec: HeadersCommandSpec, signal?: AbortSignal): Promise<string> {
+	return new Promise<string>((resolve, reject) => {
+		// 刻意**不** unref：这条命令是我们正在等的结果，子进程必须把事件循环钉住直到它结束
+		// （unref 会让 `pi -p` / probe 这类短命进程先退出，promise 永远不 resolve —— 单测当场拦到过）。
+		// 挂死风险由 exec 的 timeout 堵住。
+		exec(
+			spec.command,
+			{
+				timeout: spec.timeoutMs ?? DEFAULT_HEADERS_COMMAND_TIMEOUT_MS,
+				maxBuffer: MAX_OUTPUT_BYTES,
+				cwd: spec.cwd,
+				env: spec.env ? { ...process.env, ...spec.env } : process.env,
+				signal,
+			},
+			(error, stdout, stderr) => {
+				if (error) {
+					const timedOut = (error as { killed?: boolean }).killed === true;
+					const detail = stderr.trim() ? `：${firstLine(stderr.trim())}` : "";
+					reject(
+						new Error(
+							timedOut
+								? `头命令超时（${spec.timeoutMs ?? DEFAULT_HEADERS_COMMAND_TIMEOUT_MS}ms）`
+								: `头命令退出码非 0${detail}`,
+						),
+					);
+					return;
+				}
+				resolve(stdout);
+			},
+		);
+	});
+}
+
+/**
+ * 解析命令输出。
+ *
+ * 接受三种形状（前两种是各家客户端的契约，第三种是最省事的手写形式）：
+ *   1. 扁平 JSON 对象：`{"Authorization": "Bearer x"}`
+ *   2. 带 `headers` 包装的 JSON：`{"headers": {"Authorization": "Bearer x"}}`
+ *   3. `Name: Value` 行（每行一个头）
+ *
+ * 非字符串值、空值、非法头名一律丢弃并记 warning —— 丢弃比报错好，因为命令可能同时输出
+ * 一堆无关字段（比如 `{...token, "expires_in": 3600}`），为此整条命令失败太苛刻。
+ */
+export function parseHeadersOutput(raw: string): { headers: Record<string, string>; warnings: string[] } {
+	const warnings: string[] = [];
+	const text = raw.trim();
+	if (!text) return { headers: {}, warnings };
+
+	const fromJson = tryParseJsonHeaders(text, warnings);
+	if (fromJson) return { headers: fromJson, warnings };
+
+	const fromLines = tryParseHeaderLines(text, warnings);
+	if (fromLines) return { headers: fromLines, warnings };
+
+	throw new Error(
+		`头命令输出无法解析为请求头（${Buffer.byteLength(text, "utf8")} 字节；内容已省略以免泄露密钥）`,
+	);
+}
+
+function tryParseJsonHeaders(text: string, warnings: string[]): Record<string, string> | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+
+	const record = parsed as Record<string, unknown>;
+	const nested = record.headers;
+	const source =
+		typeof nested === "object" && nested !== null && !Array.isArray(nested)
+			? (nested as Record<string, unknown>)
+			: record;
+
+	const headers: Record<string, string> = {};
+	for (const [name, value] of Object.entries(source)) {
+		if (typeof value !== "string") {
+			// 数字/bool（如 expires_in）很常见，静默丢弃；对象/数组说明写错了，提一句。
+			if (typeof value === "object" && value !== null) warnings.push(`头 ${name} 的值不是字符串，已丢弃`);
+			continue;
+		}
+		if (value.trim() === "") {
+			warnings.push(`头 ${name} 的值为空，已丢弃`);
+			continue;
+		}
+		if (!HEADER_NAME_PATTERN.test(name)) {
+			warnings.push(`头名 ${name} 含非法字符，已丢弃`);
+			continue;
+		}
+		headers[name] = value;
+	}
+	return headers;
+}
+
+function tryParseHeaderLines(text: string, warnings: string[]): Record<string, string> | undefined {
+	const headers: Record<string, string> = {};
+	let matched = 0;
+	for (const line of text.split("\n")) {
+		const trimmedLine = line.trim();
+		if (!trimmedLine) continue;
+		const colon = trimmedLine.indexOf(":");
+		if (colon <= 0) return undefined;
+		const name = trimmedLine.slice(0, colon).trim();
+		const value = trimmedLine.slice(colon + 1).trim();
+		if (!HEADER_NAME_PATTERN.test(name)) return undefined;
+		matched += 1;
+		if (!value) {
+			warnings.push(`头 ${name} 的值为空，已丢弃`);
+			continue;
+		}
+		headers[name] = value;
+	}
+	return matched > 0 ? headers : undefined;
+}
+
+/** 合并静态与动态头：动态（命令取来的）覆盖静态，因为它是更新鲜的凭据。 */
+export function mergeHeaders(
+	base: Record<string, string>,
+	dynamic: Record<string, string>,
+): Record<string, string> {
+	return { ...base, ...dynamic };
+}
+
+/**
+ * 头名的可读列表（**永远不要把值放进来**）。
+ *
+ * Authorization 这类头只暴露名字，诊断输出才能安全地贴到 `/mcp <server>` 或日志里。
+ */
+export function describeHeaderNames(headers: Record<string, string>): string {
+	const names = Object.keys(headers);
+	return names.length > 0 ? names.join(", ") : "(无)";
+}
+
+/** 用于判断"重跑命令后头有没有变化"：只有变了才值得重试一次请求。 */
+export function headersSignature(headers: Record<string, string>): string {
+	return Object.keys(headers)
+		.sort()
+		.map((name) => `${name}:${headers[name]}`)
+		.join("\n");
+}
+
+function firstLine(text: string): string {
+	const index = text.indexOf("\n");
+	return index === -1 ? text : text.slice(0, index);
+}