@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/utils/outline-paths.ts

@@ -0,0 +1,275 @@
+/**
+ * Phase 5 (v13) path resolution — prefer the new prose outline files, fall
+ * back to legacy paths so older books keep working during transition.
+ *
+ * Maps:
+ *   story/outline/story_frame.md  →  preferred replacement for story_bible.md
+ *   story/outline/volume_map.md   →  preferred replacement for volume_outline.md
+ *   story/roles/主要角色/*.md +
+ *   story/roles/次要角色/*.md    →  preferred replacement for character_matrix.md
+ *
+ * All helpers accept a bookDir (path to a book root, containing `story/`)
+ * and return a string — either the new-file content when it exists, or the
+ * legacy file content, or an empty default placeholder.
+ */
+
+import { readFile, readdir, access } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Detect whether a book uses the Phase 5 new layout (outline/story_frame.md
+ * exists on disk). If yes, story_bible.md / book_rules.md are compat shims.
+ * If no, those files ARE the authoritative source.
+ */
+export async function isNewLayoutBook(bookDir: string): Promise<boolean> {
+  try {
+    await access(join(bookDir, "story", "outline", "story_frame.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readOr(path: string, fallback: string): Promise<string> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return fallback;
+  }
+}
+
+/** Read story_frame.md, falling back to legacy story_bible.md. */
+export async function readStoryFrame(
+  bookDir: string,
+  fallbackPlaceholder: string = "",
+): Promise<string> {
+  const newPath = join(bookDir, "story", "outline", "story_frame.md");
+  const legacyPath = join(bookDir, "story", "story_bible.md");
+
+  const newContent = await readOr(newPath, "");
+  if (newContent.trim()) return newContent;
+
+  return readOr(legacyPath, fallbackPlaceholder);
+}
+
+/** Read volume_map.md, falling back to legacy volume_outline.md. */
+export async function readVolumeMap(
+  bookDir: string,
+  fallbackPlaceholder: string = "",
+): Promise<string> {
+  const newPath = join(bookDir, "story", "outline", "volume_map.md");
+  const legacyPath = join(bookDir, "story", "volume_outline.md");
+
+  const newContent = await readOr(newPath, "");
+  if (newContent.trim()) return newContent;
+
+  return readOr(legacyPath, fallbackPlaceholder);
+}
+
+/** Read the rhythm principles file (zh or en variant). */
+export async function readRhythmPrinciples(bookDir: string): Promise<string> {
+  const zhPath = join(bookDir, "story", "outline", "节奏原则.md");
+  const enPath = join(bookDir, "story", "outline", "rhythm_principles.md");
+
+  const zh = await readOr(zhPath, "");
+  if (zh.trim()) return zh;
+  return readOr(enPath, "");
+}
+
+export interface RoleCard {
+  readonly tier: "major" | "minor";
+  readonly name: string;
+  readonly content: string;
+}
+
+/**
+ * Read the roles/ directory. Returns [] when no roles are present (e.g. old
+ * books still on character_matrix.md).
+ */
+export async function readRoleCards(bookDir: string): Promise<ReadonlyArray<RoleCard>> {
+  const rolesRoot = join(bookDir, "story", "roles");
+  const majorDirZh = join(rolesRoot, "主要角色");
+  const minorDirZh = join(rolesRoot, "次要角色");
+  const majorDirEn = join(rolesRoot, "major");
+  const minorDirEn = join(rolesRoot, "minor");
+
+  const cards: RoleCard[] = [];
+  await Promise.all([
+    collectRoleDir(majorDirZh, "major", cards),
+    collectRoleDir(minorDirZh, "minor", cards),
+    collectRoleDir(majorDirEn, "major", cards),
+    collectRoleDir(minorDirEn, "minor", cards),
+  ]);
+  return cards;
+}
+
+async function collectRoleDir(
+  dir: string,
+  tier: "major" | "minor",
+  out: RoleCard[],
+): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  const reads = entries
+    .filter((entry) => entry.endsWith(".md"))
+    .map(async (entry) => {
+      const content = await readOr(join(dir, entry), "");
+      if (!content.trim()) return;
+      out.push({
+        tier,
+        name: entry.replace(/\.md$/, ""),
+        content,
+      });
+    });
+  await Promise.all(reads);
+}
+
+/**
+ * Render role cards in a format compatible with downstream consumers that
+ * previously expected character_matrix.md prose. When no role cards exist,
+ * returns the legacy character_matrix.md content or the placeholder.
+ */
+export async function readCharacterContext(
+  bookDir: string,
+  fallbackPlaceholder: string = "",
+): Promise<string> {
+  const cards = await readRoleCards(bookDir);
+  if (cards.length > 0) {
+    const groups: Record<"major" | "minor", RoleCard[]> = { major: [], minor: [] };
+    for (const card of cards) groups[card.tier].push(card);
+
+    const render = (tierCards: RoleCard[], heading: string): string => {
+      if (tierCards.length === 0) return "";
+      const sections = tierCards.map((card) => `### ${card.name}\n\n${card.content.trim()}`);
+      return `## ${heading}\n\n${sections.join("\n\n")}`;
+    };
+
+    const blocks = [
+      render(groups.major, "主要角色 / Major characters"),
+      render(groups.minor, "次要角色 / Minor characters"),
+    ].filter(Boolean);
+
+    return blocks.join("\n\n");
+  }
+
+  // Fallback: legacy character_matrix.md (may itself be a shim pointer).
+  const legacyPath = join(bookDir, "story", "character_matrix.md");
+  return readOr(legacyPath, fallbackPlaceholder);
+}
+
+// ---------------------------------------------------------------------------
+// Phase 5 consolidation: current_state.md initial fallback
+//
+// After architect consolidation (7→5 sections), current_state.md is seeded
+// with a tiny placeholder at book creation. Real content only arrives once
+// the consolidator has appended output from chapter 1 onward. Readers that
+// previously relied on architect-provided initial state (writer phase-1
+// creative prompt, continuity, chapter-analyzer, reviser, composer) should
+// substitute a derived initial-state block when the seed placeholder is all
+// that's on disk — otherwise the "## 当前状态卡" block in prompts degenerates
+// into a meta note about runtime append behaviour.
+// ---------------------------------------------------------------------------
+
+/**
+ * Marker substring emitted by architect.writeFoundationFiles when seeding
+ * current_state.md. Its presence is how readers detect "nothing real yet".
+ */
+const CURRENT_STATE_SEED_MARKERS = [
+  "建书时占位",
+  "Seeded at book creation",
+];
+
+export function isCurrentStateSeedPlaceholder(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) return true;
+  // Heuristic: short file AND contains one of the seed markers.
+  if (trimmed.length > 600) return false;
+  return CURRENT_STATE_SEED_MARKERS.some((marker) => trimmed.includes(marker));
+}
+
+function extractCurrentStateFromRole(content: string): string | null {
+  // Accept both zh (`## 当前现状`) and en (`## Current_State` / `## Current State`).
+  const pattern = /^##\s*(?:当前现状|Current[_\s]?State)[^\n]*$/im;
+  const match = content.match(pattern);
+  if (!match || match.index === undefined) return null;
+  const after = content.slice(match.index + match[0].length);
+  // Cut at next `## ` heading (same or higher level).
+  const nextHeading = after.search(/^##\s/m);
+  const raw = nextHeading >= 0 ? after.slice(0, nextHeading) : after;
+  const text = raw.trim();
+  return text.length > 0 ? text : null;
+}
+
+function extractSeedHooksFromPendingHooks(raw: string): string[] {
+  if (!raw.trim()) return [];
+  const lines = raw.split("\n").map((line) => line.trim()).filter(Boolean);
+  const seedRows: string[] = [];
+  for (const line of lines) {
+    if (!line.startsWith("|")) continue;
+    if (/^\|\s*-/.test(line)) continue;
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (cells.length < 2) continue;
+    if (cells[0]?.toLowerCase() === "hook_id" || cells[0] === "hookId") continue;
+    const startCh = Number.parseInt(cells[1] ?? "", 10);
+    if (!Number.isFinite(startCh) || startCh !== 0) continue;
+    // cells[2] type, cells[5] expected payoff, last cell notes
+    const notes = cells[cells.length - 1] ?? "";
+    const summary = [cells[0], cells[2], notes].filter(Boolean).join(" · ");
+    if (summary) seedRows.push(summary);
+  }
+  return seedRows;
+}
+
+/**
+ * Read current_state.md; when the file is only a seed placeholder (chapter 0,
+ * before consolidator has appended anything), derive an initial-state block
+ * from roles/*.Current_State + pending_hooks startChapter=0 rows so callers
+ * still have substantive content to feed into writer / analyzer prompts.
+ */
+export async function readCurrentStateWithFallback(
+  bookDir: string,
+  fallbackPlaceholder: string = "",
+): Promise<string> {
+  const storyDir = join(bookDir, "story");
+  const currentStatePath = join(storyDir, "current_state.md");
+  const raw = await readOr(currentStatePath, "");
+
+  if (!isCurrentStateSeedPlaceholder(raw)) {
+    return raw;
+  }
+
+  const [cards, pendingHooks] = await Promise.all([
+    readRoleCards(bookDir),
+    readOr(join(storyDir, "pending_hooks.md"), ""),
+  ]);
+
+  const roleLines = cards
+    .map((card) => {
+      const state = extractCurrentStateFromRole(card.content);
+      if (!state) return null;
+      const tierLabel = card.tier === "major" ? "主要" : "次要";
+      return `- ${card.name}（${tierLabel}）：${state.replace(/\s+/g, " ")}`;
+    })
+    .filter((line): line is string => line !== null);
+
+  const hookLines = extractSeedHooksFromPendingHooks(pendingHooks);
+
+  if (roleLines.length === 0 && hookLines.length === 0) {
+    return raw.trim() ? raw : fallbackPlaceholder;
+  }
+
+  const parts: string[] = ["# 初始状态（第 0 章，由 roles + 种子伏笔派生）"];
+  if (roleLines.length > 0) {
+    parts.push("\n## 角色初始位置 / 处境");
+    parts.push(...roleLines);
+  }
+  if (hookLines.length > 0) {
+    parts.push("\n## 种子伏笔（startChapter = 0）");
+    parts.push(...hookLines.map((line) => `- ${line}`));
+  }
+  return parts.join("\n");
+}

package/inkos/packages/core/src/utils/path-safety.ts

@@ -0,0 +1,11 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export function safeChildPath(root: string, requestedPath: string): string {
+  const resolvedRoot = resolve(root);
+  const resolvedPath = resolve(resolvedRoot, requestedPath);
+  const rel = relative(resolvedRoot, resolvedPath);
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+    return resolvedPath;
+  }
+  throw new Error(`Path traversal blocked: ${requestedPath}`);
+}

package/inkos/packages/core/src/utils/planning-materials.ts

@@ -0,0 +1,185 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { StoredHook, StoredSummary } from "../state/memory-db.js";
+import {
+  parseChapterSummariesMarkdown,
+  retrieveMemorySelection,
+  type MemorySelection,
+} from "./memory-retrieval.js";
+import {
+  readStoryFrame,
+  readVolumeMap,
+  readCurrentStateWithFallback,
+} from "./outline-paths.js";
+
+export interface PlanningSeedMaterials {
+  readonly storyDir: string;
+  readonly authorIntent: string;
+  readonly currentFocus: string;
+  readonly storyBible: string;
+  readonly volumeOutline: string;
+  readonly bookRulesRaw: string;
+  readonly currentState: string;
+  readonly chapterSummariesRaw: string;
+  readonly brief: string;
+  readonly outlineNode?: string;
+  readonly recentSummaries: ReadonlyArray<StoredSummary>;
+  readonly previousEndingHook?: string;
+  readonly previousEndingExcerpt?: string;
+}
+
+export interface PlanningMaterials extends PlanningSeedMaterials {
+  readonly activeHooks: ReadonlyArray<StoredHook>;
+  readonly memorySelection: MemorySelection;
+  readonly plannerInputs: ReadonlyArray<string>;
+}
+
+async function readFileOrDefault(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return "(文件尚未创建)";
+  }
+}
+
+async function readBriefFile(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+async function readPreviousEndingExcerpt(
+  bookDir: string,
+  chapterNumber: number,
+): Promise<string | undefined> {
+  const previousChapter = chapterNumber - 1;
+  if (previousChapter < 1) {
+    return undefined;
+  }
+
+  const chaptersDir = join(bookDir, "chapters");
+  const padded = String(previousChapter).padStart(4, "0");
+  try {
+    const files = await readdir(chaptersDir);
+    const match = files.find((file) => file.startsWith(padded) && file.endsWith(".md"));
+    if (!match) {
+      return undefined;
+    }
+    const markdown = await readFile(join(chaptersDir, match), "utf-8");
+    const body = markdown
+      .split("\n")
+      .slice(1)
+      .join("\n")
+      .trim();
+    if (!body) {
+      return undefined;
+    }
+    return body.slice(-320).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadPlanningSeedMaterials(params: {
+  readonly bookDir: string;
+  readonly chapterNumber: number;
+}): Promise<PlanningSeedMaterials> {
+  const storyDir = join(params.bookDir, "story");
+  const sourcePaths = {
+    authorIntent: join(storyDir, "author_intent.md"),
+    currentFocus: join(storyDir, "current_focus.md"),
+    chapterSummaries: join(storyDir, "chapter_summaries.md"),
+    bookRules: join(storyDir, "book_rules.md"),
+    currentState: join(storyDir, "current_state.md"),
+    brief: join(storyDir, "brief.md"),
+  } as const;
+
+  // Phase 5: prefer the new prose outline files (outline/story_frame.md +
+  // outline/volume_map.md). Fall back to the legacy files transparently.
+  const placeholder = "(文件尚未创建)";
+
+  const [
+    authorIntent,
+    currentFocus,
+    storyBible,
+    volumeOutline,
+    chapterSummariesRaw,
+    bookRulesRaw,
+    currentState,
+    previousEndingExcerpt,
+    brief,
+  ] = await Promise.all([
+    readFileOrDefault(sourcePaths.authorIntent),
+    readFileOrDefault(sourcePaths.currentFocus),
+    readStoryFrame(params.bookDir, placeholder),
+    readVolumeMap(params.bookDir, placeholder),
+    readFileOrDefault(sourcePaths.chapterSummaries),
+    readFileOrDefault(sourcePaths.bookRules),
+    // Phase 5 consolidation: derive initial state from roles + pending_hooks
+    // seed rows when current_state.md is still just the architect's placeholder.
+    readCurrentStateWithFallback(params.bookDir, placeholder),
+    readPreviousEndingExcerpt(params.bookDir, params.chapterNumber),
+    readBriefFile(sourcePaths.brief),
+  ]);
+
+  const chapterSummaries = parseChapterSummariesMarkdown(chapterSummariesRaw)
+    .filter((summary) => summary.chapter < params.chapterNumber)
+    .sort((left, right) => right.chapter - left.chapter);
+
+  return {
+    storyDir,
+    authorIntent,
+    currentFocus,
+    storyBible,
+    volumeOutline,
+    bookRulesRaw,
+    currentState,
+    chapterSummariesRaw,
+    brief,
+    recentSummaries: chapterSummaries.slice(0, 4).sort((left, right) => left.chapter - right.chapter),
+    previousEndingHook: chapterSummaries[0]?.hookActivity || undefined,
+    previousEndingExcerpt,
+  };
+}
+
+export async function gatherPlanningMaterials(params: {
+  readonly bookDir: string;
+  readonly chapterNumber: number;
+  readonly goal: string;
+  readonly outlineNode?: string;
+  readonly mustKeep?: ReadonlyArray<string>;
+  readonly seed?: PlanningSeedMaterials;
+}): Promise<PlanningMaterials> {
+  const seed = params.seed ?? await loadPlanningSeedMaterials({
+    bookDir: params.bookDir,
+    chapterNumber: params.chapterNumber,
+  });
+
+  const memorySelection = await retrieveMemorySelection({
+    bookDir: params.bookDir,
+    chapterNumber: params.chapterNumber,
+    goal: params.goal,
+    outlineNode: params.outlineNode,
+    mustKeep: params.mustKeep,
+  });
+
+  return {
+    ...seed,
+    outlineNode: params.outlineNode,
+    activeHooks: memorySelection.activeHooks,
+    memorySelection,
+    plannerInputs: [
+      join(seed.storyDir, "author_intent.md"),
+      join(seed.storyDir, "current_focus.md"),
+      join(seed.storyDir, "outline", "story_frame.md"),
+      join(seed.storyDir, "outline", "volume_map.md"),
+      join(seed.storyDir, "chapter_summaries.md"),
+      join(seed.storyDir, "book_rules.md"),
+      join(seed.storyDir, "current_state.md"),
+      join(seed.storyDir, "pending_hooks.md"),
+      ...(memorySelection.dbPath ? [memorySelection.dbPath] : []),
+    ],
+  };
+}

package/inkos/packages/core/src/utils/pov-filter.ts

@@ -0,0 +1,149 @@
+/**
+ * POV-aware context filtering.
+ *
+ * Filters truth file content based on the current POV character's
+ * information boundaries. Characters should only "see" information
+ * they've actually witnessed or been told about.
+ *
+ * Works with markdown-based truth files (no DB dependency).
+ * When MemoryDB is available, can do more precise queries.
+ */
+
+/**
+ * Extract the POV character from the volume outline for a given chapter.
+ * Looks for patterns like "POV: 角色名" or "视角: 角色名" or "POV: CharacterName"
+ * in the chapter's section of the outline.
+ */
+export function extractPOVFromOutline(volumeOutline: string, chapterNumber: number): string | null {
+  // Find the section for this chapter
+  const lines = volumeOutline.split("\n");
+
+  // Look for chapter reference near the chapter number
+  const chapterPatterns = [
+    new RegExp(`第${chapterNumber}章`),
+    new RegExp(`Chapter\\s+${chapterNumber}\\b`),
+    new RegExp(`\\b${chapterNumber}\\b.*章`),
+  ];
+
+  let inChapterSection = false;
+  for (const line of lines) {
+    // Check if we're in the right chapter section
+    if (chapterPatterns.some((p) => p.test(line))) {
+      inChapterSection = true;
+    } else if (inChapterSection && /^[#-]/.test(line) && !line.includes(String(chapterNumber))) {
+      // Left the chapter section
+      break;
+    }
+
+    if (inChapterSection) {
+      // Look for POV declaration
+      const povMatch = line.match(/(?:POV|视角|pov)[：:\s]+([^\s，,。.、]+)/i);
+      if (povMatch) return povMatch[1]!;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Filter character_matrix information boundaries for the POV character.
+ * Returns only what the POV character knows — strips other characters' "known info".
+ */
+export function filterMatrixByPOV(characterMatrix: string, povCharacter: string): string {
+  if (!characterMatrix || characterMatrix === "(文件尚未创建)") return characterMatrix;
+  if (!povCharacter) return characterMatrix;
+
+  // Find the 信息边界 / Information Boundaries section
+  const sections = characterMatrix.split(/(?=^###)/m);
+  const filtered = sections.map((section) => {
+    const isInfoBoundary = /信息边界|Information\s+Boundar/i.test(section);
+    if (!isInfoBoundary) return section;
+
+    // In the info boundary table, keep only the POV character's row
+    // and add a note about what other characters know
+    const lines = section.split("\n");
+    const headerLines = lines.filter((l) =>
+      l.startsWith("|") && (l.includes("---") || l.includes("角色") || l.includes("Character") || l.includes("已知") || l.includes("Known")),
+    );
+    const dataLines = lines.filter((l) =>
+      l.startsWith("|") && !l.includes("---") && !l.includes("角色") && !l.includes("Character") && !l.includes("已知") && !l.includes("Known"),
+    );
+
+    // Keep POV character's row + a summary note
+    const povRows = dataLines.filter((l) => l.includes(povCharacter));
+    const otherCharCount = dataLines.length - povRows.length;
+
+    const sectionHeader = lines.find((l) => l.startsWith("###"));
+    const result = [
+      sectionHeader ?? "### 信息边界",
+      `（当前视角：${povCharacter}，其他 ${otherCharCount} 个角色的信息边界已隐藏）`,
+      ...headerLines,
+      ...povRows,
+    ];
+
+    return result.join("\n");
+  });
+
+  return filtered.join("\n");
+}
+
+/**
+ * Filter pending_hooks by POV character's knowledge.
+ * Hooks planted in scenes where the POV character was NOT present are hidden.
+ *
+ * This is a heuristic: if the hook's chapter summary mentions the POV character,
+ * they likely know about it.
+ */
+export function filterHooksByPOV(
+  hooks: string,
+  povCharacter: string,
+  chapterSummaries: string,
+): string {
+  if (!hooks || hooks === "(文件尚未创建)") return hooks;
+  if (!povCharacter) return hooks;
+
+  const lines = hooks.split("\n");
+  const headerLines = lines.filter((l) =>
+    l.startsWith("|") && (l.includes("hook_id") || l.includes("---")),
+  );
+  const dataLines = lines.filter((l) =>
+    l.startsWith("|") && !l.includes("hook_id") && !l.includes("---"),
+  );
+
+  // Parse summary rows to find which chapters the POV character appeared in
+  const povChapters = new Set<number>();
+  if (chapterSummaries) {
+    for (const line of chapterSummaries.split("\n")) {
+      if (line.includes(povCharacter)) {
+        const match = line.match(/\|\s*(\d+)\s*\|/);
+        if (match) povChapters.add(parseInt(match[1]!, 10));
+      }
+    }
+  }
+
+  // Keep hooks where:
+  // 1. The POV character was present in the source chapter, OR
+  // 2. The hook mentions the POV character directly, OR
+  // 3. We can't determine (keep to be safe)
+  const filtered = dataLines.filter((row) => {
+    // If hook directly mentions POV character, keep it
+    if (row.includes(povCharacter)) return true;
+
+    // Extract source chapter from hook row
+    const chapterMatch = row.match(/\|\s*(\d+)\s*\|/);
+    if (!chapterMatch) return true; // can't determine, keep
+
+    const sourceChapter = parseInt(chapterMatch[1]!, 10);
+    // If POV was in that chapter, they know about the hook
+    if (povChapters.has(sourceChapter)) return true;
+
+    // POV wasn't in that chapter — hide this hook
+    return false;
+  });
+
+  // Fallback: if filtering removes everything, return original
+  if (filtered.length === 0 && dataLines.length > 0) return hooks;
+
+  const nonTableLines = lines.filter((l) => !l.startsWith("|"));
+  return [...nonTableLines, ...headerLines, ...filtered].join("\n");
+}

package/inkos/packages/core/src/utils/proxy-fetch.ts

@@ -0,0 +1,44 @@
+import { ProxyAgent } from "undici";
+
+type ProxyEnv = Record<string, string | undefined>;
+type FetchInitWithDispatcher = RequestInit & { dispatcher?: unknown };
+
+export function resolveProxyUrl(explicitProxyUrl?: string, env: ProxyEnv = process.env): string | undefined {
+  const candidate = [
+    explicitProxyUrl,
+    env.INKOS_LLM_PROXY_URL,
+    env.HTTPS_PROXY,
+    env.https_proxy,
+    env.HTTP_PROXY,
+    env.http_proxy,
+  ].find((value) => typeof value === "string" && value.trim().length > 0)?.trim();
+
+  if (!candidate) return undefined;
+  const parsed = new URL(candidate);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Unsupported proxy protocol: ${parsed.protocol}`);
+  }
+  return candidate;
+}
+
+export function buildProxyFetchInit(
+  init: RequestInit = {},
+  explicitProxyUrl?: string,
+  env: ProxyEnv = process.env,
+): FetchInitWithDispatcher {
+  const proxyUrl = resolveProxyUrl(explicitProxyUrl, env);
+  if (!proxyUrl) return init;
+  return {
+    ...init,
+    dispatcher: new ProxyAgent(proxyUrl) as any,
+  };
+}
+
+export function fetchWithProxy(
+  input: Parameters<typeof fetch>[0],
+  init: RequestInit = {},
+  explicitProxyUrl?: string,
+  env: ProxyEnv = process.env,
+): ReturnType<typeof fetch> {
+  return fetch(input, buildProxyFetchInit(init, explicitProxyUrl, env));
+}