@actalk/inkos-studio 1.2.0 → 1.3.0

package/dist/api/server.js

@@ -2,12 +2,68 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { streamSSE } from "hono/streaming";
 import { serve } from "@hono/node-server";
-import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionInput, processProjectInteractionRequest, resolveSessionActiveBook, } from "@actalk/inkos-core";
-import { access, readFile, readdir } from "node:fs/promises";
+import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionRequest, resolveSessionActiveBook, findOrCreateBookSession, listBookSessions, loadBookSession, persistBookSession, appendBookSessionMessage, runAgentSession, buildAgentSystemPrompt, resolveServicePreset, resolveServiceModel, loadSecrets, saveSecrets, getServiceApiKey, listModelsForService, chatCompletion, GLOBAL_ENV_PATH, } from "@actalk/inkos-core";
+import { access, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isSafeBookId } from "./safety.js";
 import { ApiError } from "./errors.js";
 import { buildStudioBookConfig } from "./book-create.js";
+// -- Pipeline stage definitions per agent type --
+const PIPELINE_STAGES = {
+    writer: [
+        "准备章节输入", "撰写章节草稿", "落盘最终章节",
+        "生成最终真相文件", "校验真相文件变更", "同步记忆索引",
+        "更新章节索引与快照",
+    ],
+    architect: [
+        "生成基础设定", "保存书籍配置", "写入基础设定文件",
+        "初始化控制文档", "创建初始快照",
+    ],
+    reviser: [
+        "加载修订上下文", "修订章节", "落盘修订结果",
+        "更新索引与快照",
+    ],
+    auditor: ["审计章节"],
+};
+const AGENT_LABELS = {
+    architect: "建书", writer: "写作", auditor: "审计",
+    reviser: "修订", exporter: "导出",
+};
+const TOOL_LABELS = {
+    read: "读取文件", edit: "编辑文件", grep: "搜索", ls: "列目录",
+};
+function resolveToolLabel(tool, agent) {
+    if (tool === "sub_agent" && agent)
+        return AGENT_LABELS[agent] ?? agent;
+    return TOOL_LABELS[tool] ?? tool;
+}
+function summarizeResult(result) {
+    if (typeof result === "string")
+        return result.slice(0, 200);
+    if (result && typeof result === "object") {
+        const r = result;
+        if (typeof r.content === "string")
+            return r.content.slice(0, 200);
+        if (typeof r.text === "string")
+            return r.text.slice(0, 200);
+    }
+    return String(result).slice(0, 200);
+}
+function extractToolError(result) {
+    if (typeof result === "string")
+        return result.slice(0, 500);
+    if (result && typeof result === "object") {
+        const r = result;
+        if (typeof r.content === "string")
+            return r.content.slice(0, 500);
+        if (r.content && Array.isArray(r.content)) {
+            const textPart = r.content.find((c) => c.type === "text");
+            if (textPart)
+                return textPart.text?.slice(0, 500) ?? "";
+        }
+    }
+    return String(result).slice(0, 500);
+}
 const subscribers = new Set();
 const bookCreateStatus = new Map();
 function broadcast(event, data) {
@@ -15,6 +71,154 @@ function broadcast(event, data) {
         handler(event, data);
     }
 }
+function isCustomServiceId(serviceId) {
+    return serviceId === "custom" || serviceId.startsWith("custom:");
+}
+function serviceConfigKey(entry) {
+    return entry.service === "custom" ? `custom:${entry.name ?? "Custom"}` : entry.service;
+}
+function normalizeServiceEntry(serviceId, value) {
+    if (serviceId.startsWith("custom:")) {
+        return {
+            service: "custom",
+            name: decodeURIComponent(serviceId.slice("custom:".length)),
+            ...(typeof value.baseUrl === "string" && value.baseUrl.length > 0 ? { baseUrl: value.baseUrl } : {}),
+            ...(typeof value.temperature === "number" ? { temperature: value.temperature } : {}),
+            ...(typeof value.maxTokens === "number" ? { maxTokens: value.maxTokens } : {}),
+            ...(value.apiFormat === "chat" || value.apiFormat === "responses" ? { apiFormat: value.apiFormat } : {}),
+            ...(typeof value.stream === "boolean" ? { stream: value.stream } : {}),
+        };
+    }
+    if (serviceId === "custom") {
+        return {
+            service: "custom",
+            ...(typeof value.name === "string" && value.name.length > 0 ? { name: value.name } : {}),
+            ...(typeof value.baseUrl === "string" && value.baseUrl.length > 0 ? { baseUrl: value.baseUrl } : {}),
+            ...(typeof value.temperature === "number" ? { temperature: value.temperature } : {}),
+            ...(typeof value.maxTokens === "number" ? { maxTokens: value.maxTokens } : {}),
+            ...(value.apiFormat === "chat" || value.apiFormat === "responses" ? { apiFormat: value.apiFormat } : {}),
+            ...(typeof value.stream === "boolean" ? { stream: value.stream } : {}),
+        };
+    }
+    return {
+        service: serviceId,
+        ...(typeof value.temperature === "number" ? { temperature: value.temperature } : {}),
+        ...(typeof value.maxTokens === "number" ? { maxTokens: value.maxTokens } : {}),
+        ...(value.apiFormat === "chat" || value.apiFormat === "responses" ? { apiFormat: value.apiFormat } : {}),
+        ...(typeof value.stream === "boolean" ? { stream: value.stream } : {}),
+    };
+}
+function normalizeConfigSource(value) {
+    return value === "studio" ? "studio" : "env";
+}
+function normalizeServiceConfig(raw) {
+    if (Array.isArray(raw)) {
+        return raw
+            .filter((entry) => Boolean(entry) && typeof entry === "object")
+            .map((entry) => ({
+            service: typeof entry.service === "string" && entry.service.length > 0 ? entry.service : "custom",
+            ...(typeof entry.name === "string" && entry.name.length > 0 ? { name: entry.name } : {}),
+            ...(typeof entry.baseUrl === "string" && entry.baseUrl.length > 0 ? { baseUrl: entry.baseUrl } : {}),
+            ...(typeof entry.temperature === "number" ? { temperature: entry.temperature } : {}),
+            ...(typeof entry.maxTokens === "number" ? { maxTokens: entry.maxTokens } : {}),
+            ...(entry.apiFormat === "chat" || entry.apiFormat === "responses" ? { apiFormat: entry.apiFormat } : {}),
+            ...(typeof entry.stream === "boolean" ? { stream: entry.stream } : {}),
+        }));
+    }
+    if (raw && typeof raw === "object") {
+        return Object.entries(raw)
+            .filter(([, value]) => value && typeof value === "object")
+            .map(([serviceId, value]) => normalizeServiceEntry(serviceId, value));
+    }
+    return [];
+}
+function mergeServiceConfig(existing, updates) {
+    const merged = new Map(existing.map((entry) => [serviceConfigKey(entry), entry]));
+    for (const update of updates) {
+        merged.set(serviceConfigKey(update), update);
+    }
+    return [...merged.values()];
+}
+async function loadRawConfig(root) {
+    const configPath = join(root, "inkos.json");
+    const raw = await readFile(configPath, "utf-8");
+    return JSON.parse(raw);
+}
+async function saveRawConfig(root, config) {
+    await writeFile(join(root, "inkos.json"), JSON.stringify(config, null, 2), "utf-8");
+}
+async function readEnvConfigSummary(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        const values = new Map();
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+            if (!match)
+                continue;
+            const [, key, value] = match;
+            values.set(key, value.trim());
+        }
+        const provider = values.get("INKOS_LLM_PROVIDER") ?? null;
+        const baseUrl = values.get("INKOS_LLM_BASE_URL") ?? null;
+        const model = values.get("INKOS_LLM_MODEL") ?? null;
+        const apiKey = values.get("INKOS_LLM_API_KEY") ?? "";
+        const detected = Boolean(provider || baseUrl || model || apiKey);
+        return {
+            detected,
+            provider,
+            baseUrl,
+            model,
+            hasApiKey: apiKey.length > 0,
+        };
+    }
+    catch {
+        return {
+            detected: false,
+            provider: null,
+            baseUrl: null,
+            model: null,
+            hasApiKey: false,
+        };
+    }
+}
+async function readEnvConfigStatus(root) {
+    const project = await readEnvConfigSummary(join(root, ".env"));
+    const global = await readEnvConfigSummary(GLOBAL_ENV_PATH);
+    return {
+        project,
+        global,
+        effectiveSource: project.detected ? "project" : global.detected ? "global" : null,
+    };
+}
+async function resolveConfiguredServiceBaseUrl(root, serviceId, inlineBaseUrl) {
+    if (inlineBaseUrl?.trim())
+        return inlineBaseUrl.trim();
+    if (!isCustomServiceId(serviceId)) {
+        return resolveServicePreset(serviceId)?.baseUrl;
+    }
+    try {
+        const config = await loadRawConfig(root);
+        const services = normalizeServiceConfig(config.llm?.services);
+        const matched = services.find((entry) => serviceConfigKey(entry) === serviceId);
+        return matched?.baseUrl;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolveConfiguredServiceEntry(root, serviceId) {
+    try {
+        const config = await loadRawConfig(root);
+        const services = normalizeServiceConfig(config.llm?.services);
+        return services.find((entry) => serviceConfigKey(entry) === serviceId);
+    }
+    catch {
+        return undefined;
+    }
+}
 // --- Server factory ---
 export function createStudioServer(initialConfig, root) {
     const app = new Hono();
@@ -29,14 +233,14 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ error: { code: "INTERNAL_ERROR", message: "Unexpected server error." } }, 500);
     });
     // BookId validation middleware — blocks path traversal on all book routes
-    app.use("/api/books/:id/*", async (c, next) => {
+    app.use("/api/v1/books/:id/*", async (c, next) => {
         const bookId = c.req.param("id");
         if (!isSafeBookId(bookId)) {
             throw new ApiError(400, "INVALID_BOOK_ID", `Invalid book ID: "${bookId}"`);
         }
         await next();
     });
-    app.use("/api/books/:id", async (c, next) => {
+    app.use("/api/v1/books/:id", async (c, next) => {
         const bookId = c.req.param("id");
         if (!isSafeBookId(bookId)) {
             throw new ApiError(400, "INVALID_BOOK_ID", `Invalid book ID: "${bookId}"`);
@@ -49,36 +253,47 @@ export function createStudioServer(initialConfig, root) {
             broadcast("log", { level: entry.level, tag: entry.tag, message: entry.message });
         },
     };
+    // Logger sink that prints to server terminal
+    const consoleSink = {
+        write(entry) {
+            const prefix = `[${entry.tag}]`;
+            if (entry.level === "warn")
+                console.warn(prefix, entry.message);
+            else if (entry.level === "error")
+                console.error(prefix, entry.message);
+            else
+                console.log(prefix, entry.message);
+        },
+    };
     async function loadCurrentProjectConfig(options) {
         const freshConfig = await loadProjectConfig(root, options);
         cachedConfig = freshConfig;
         return freshConfig;
     }
     async function buildPipelineConfig(overrides) {
-        const currentConfig = await loadCurrentProjectConfig();
-        const logger = createLogger({ tag: "studio", sinks: [sseSink] });
+        const currentConfig = overrides?.currentConfig ?? await loadCurrentProjectConfig();
+        const logger = createLogger({ tag: "studio", sinks: [sseSink, consoleSink] });
         return {
-            client: createLLMClient(currentConfig.llm),
-            model: currentConfig.llm.model,
+            client: overrides?.client ?? createLLMClient(currentConfig.llm),
+            model: overrides?.model ?? currentConfig.llm.model,
             projectRoot: root,
             defaultLLMConfig: currentConfig.llm,
             modelOverrides: currentConfig.modelOverrides,
             notifyChannels: currentConfig.notify,
             logger,
             onStreamProgress: (progress) => {
-                if (progress.status === "streaming") {
-                    broadcast("llm:progress", {
-                        elapsedMs: progress.elapsedMs,
-                        totalChars: progress.totalChars,
-                        chineseChars: progress.chineseChars,
-                    });
-                }
+                broadcast("llm:progress", {
+                    status: progress.status,
+                    elapsedMs: progress.elapsedMs,
+                    totalChars: progress.totalChars,
+                    chineseChars: progress.chineseChars,
+                });
             },
             externalContext: overrides?.externalContext,
         };
     }
     // --- Books ---
-    app.get("/api/books", async (c) => {
+    app.get("/api/v1/books", async (c) => {
         const bookIds = await state.listBooks();
         const books = await Promise.all(bookIds.map(async (id) => {
             const book = await state.loadBookConfig(id);
@@ -87,7 +302,7 @@ export function createStudioServer(initialConfig, root) {
         }));
         return c.json({ books });
     });
-    app.get("/api/books/:id", async (c) => {
+    app.get("/api/v1/books/:id", async (c) => {
         const id = c.req.param("id");
         try {
             const book = await state.loadBookConfig(id);
@@ -100,7 +315,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Genres ---
-    app.get("/api/genres", async (c) => {
+    app.get("/api/v1/genres", async (c) => {
         const { listAvailableGenres, readGenreProfile } = await import("@actalk/inkos-core");
         const rawGenres = await listAvailableGenres(root);
         const genres = await Promise.all(rawGenres.map(async (g) => {
@@ -115,7 +330,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ genres });
     });
     // --- Book Create ---
-    app.post("/api/books/create", async (c) => {
+    app.post("/api/v1/books/create", async (c) => {
         const body = await c.req.json();
         const now = new Date().toISOString();
         const bookConfig = buildStudioBookConfig(body, now);
@@ -156,7 +371,7 @@ export function createStudioServer(initialConfig, root) {
         });
         return c.json({ status: "creating", bookId });
     });
-    app.get("/api/books/:id/create-status", async (c) => {
+    app.get("/api/v1/books/:id/create-status", async (c) => {
         const id = c.req.param("id");
         const status = bookCreateStatus.get(id);
         if (!status) {
@@ -165,7 +380,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json(status);
     });
     // --- Chapters ---
-    app.get("/api/books/:id/chapters/:num", async (c) => {
+    app.get("/api/v1/books/:id/chapters/:num", async (c) => {
         const id = c.req.param("id");
         const num = parseInt(c.req.param("num"), 10);
         const bookDir = state.bookDir(id);
@@ -184,7 +399,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Chapter Save ---
-    app.put("/api/books/:id/chapters/:num", async (c) => {
+    app.put("/api/v1/books/:id/chapters/:num", async (c) => {
         const id = c.req.param("id");
         const num = parseInt(c.req.param("num"), 10);
         const bookDir = state.bookDir(id);
@@ -206,12 +421,13 @@ export function createStudioServer(initialConfig, root) {
     });
     // --- Truth files ---
     const TRUTH_FILES = [
+        "author_intent.md", "current_focus.md",
         "story_bible.md", "volume_outline.md", "current_state.md",
         "particle_ledger.md", "pending_hooks.md", "chapter_summaries.md",
         "subplot_board.md", "emotional_arcs.md", "character_matrix.md",
         "style_guide.md", "parent_canon.md", "fanfic_canon.md", "book_rules.md",
     ];
-    app.get("/api/books/:id/truth/:file", async (c) => {
+    app.get("/api/v1/books/:id/truth/:file", async (c) => {
         const id = c.req.param("id");
         const file = c.req.param("file");
         if (!TRUTH_FILES.includes(file)) {
@@ -227,7 +443,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Analytics ---
-    app.get("/api/books/:id/analytics", async (c) => {
+    app.get("/api/v1/books/:id/analytics", async (c) => {
         const id = c.req.param("id");
         try {
             const chapters = await state.loadChapterIndex(id);
@@ -238,7 +454,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Actions ---
-    app.post("/api/books/:id/write-next", async (c) => {
+    app.post("/api/v1/books/:id/write-next", async (c) => {
         const id = c.req.param("id");
         const body = await c.req.json().catch(() => ({ wordCount: undefined }));
         broadcast("write:start", { bookId: id });
@@ -251,7 +467,7 @@ export function createStudioServer(initialConfig, root) {
         });
         return c.json({ status: "writing", bookId: id });
     });
-    app.post("/api/books/:id/draft", async (c) => {
+    app.post("/api/v1/books/:id/draft", async (c) => {
         const id = c.req.param("id");
         const body = await c.req.json().catch(() => ({ wordCount: undefined, context: undefined }));
         broadcast("draft:start", { bookId: id });
@@ -263,7 +479,7 @@ export function createStudioServer(initialConfig, root) {
         });
         return c.json({ status: "drafting", bookId: id });
     });
-    app.post("/api/books/:id/chapters/:num/approve", async (c) => {
+    app.post("/api/v1/books/:id/chapters/:num/approve", async (c) => {
         const id = c.req.param("id");
         const num = parseInt(c.req.param("num"), 10);
         try {
@@ -276,7 +492,7 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 500);
         }
     });
-    app.post("/api/books/:id/chapters/:num/reject", async (c) => {
+    app.post("/api/v1/books/:id/chapters/:num/reject", async (c) => {
         const id = c.req.param("id");
         const num = parseInt(c.req.param("num"), 10);
         try {
@@ -300,7 +516,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- SSE ---
-    app.get("/api/events", (c) => {
+    app.get("/api/v1/events", (c) => {
         return streamSSE(c, async (stream) => {
             const handler = (event, data) => {
                 stream.writeSSE({ event, data: JSON.stringify(data) });
@@ -318,8 +534,184 @@ export function createStudioServer(initialConfig, root) {
             await new Promise(() => { });
         });
     });
+    // --- Model discovery ---
+    app.get("/api/v1/services", async (c) => {
+        const secrets = await loadSecrets(root);
+        const SERVICE_KEYS = [
+            "openai", "anthropic", "deepseek", "moonshot", "minimax",
+            "bailian", "zhipu", "siliconflow", "ppio", "openrouter", "ollama",
+        ];
+        // Fast: only check connection status from secrets, no external API calls
+        const services = SERVICE_KEYS.map((key) => {
+            const preset = resolveServicePreset(key);
+            return {
+                service: key,
+                label: preset?.label ?? key,
+                connected: Boolean(secrets.services[key]?.apiKey),
+            };
+        });
+        // Add custom services from inkos.json
+        try {
+            const config = await loadRawConfig(root);
+            for (const svc of normalizeServiceConfig(config.llm?.services)) {
+                if (svc.service === "custom") {
+                    const secretKey = `custom:${svc.name}`;
+                    services.push({
+                        service: secretKey,
+                        label: svc.name ?? "Custom",
+                        connected: Boolean(secrets.services[secretKey]?.apiKey),
+                    });
+                }
+            }
+        }
+        catch { /* no config file */ }
+        return c.json({ services });
+    });
+    app.get("/api/v1/services/config", async (c) => {
+        const config = await loadRawConfig(root);
+        const llm = config.llm ?? {};
+        const services = normalizeServiceConfig(llm.services);
+        const envConfig = await readEnvConfigStatus(root);
+        return c.json({
+            services,
+            defaultModel: llm.defaultModel ?? null,
+            configSource: normalizeConfigSource(llm.configSource),
+            envConfig,
+        });
+    });
+    app.put("/api/v1/services/config", async (c) => {
+        const body = await c.req.json();
+        const config = await loadRawConfig(root);
+        config.llm = config.llm ?? {};
+        const llm = config.llm;
+        if (body.services !== undefined) {
+            const existingServices = normalizeServiceConfig(llm.services);
+            const incomingServices = normalizeServiceConfig(body.services);
+            llm.services = mergeServiceConfig(existingServices, incomingServices);
+        }
+        if (body.defaultModel !== undefined) {
+            llm.defaultModel = body.defaultModel;
+        }
+        if (body.configSource !== undefined) {
+            llm.configSource = normalizeConfigSource(body.configSource);
+        }
+        await saveRawConfig(root, config);
+        return c.json({ ok: true });
+    });
+    app.post("/api/v1/services/:service/test", async (c) => {
+        const service = c.req.param("service");
+        const { apiKey, baseUrl, apiFormat, stream } = await c.req.json();
+        if (!apiKey?.trim()) {
+            return c.json({ ok: false, error: "API Key 不能为空" }, 400);
+        }
+        const resolvedBaseUrl = await resolveConfiguredServiceBaseUrl(root, service, baseUrl);
+        if (!resolvedBaseUrl) {
+            return c.json({ ok: false, error: `未知服务商: ${service}` }, 400);
+        }
+        // Call the real /models API — no fallback
+        const modelsUrl = resolvedBaseUrl.replace(/\/$/, "") + "/models";
+        try {
+            const res = await fetch(modelsUrl, {
+                headers: { Authorization: `Bearer ${apiKey.trim()}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                if (res.status === 401 || res.status === 403) {
+                    return c.json({ ok: false, error: "API Key 无效，请检查后重试" }, 400);
+                }
+                return c.json({ ok: false, error: `服务商返回 ${res.status}: ${body.slice(0, 200)}` }, 400);
+            }
+            const json = await res.json();
+            const models = (json.data ?? []).map((m) => ({ id: m.id, name: m.id }));
+            if (models.length === 0) {
+                return c.json({ ok: false, error: "连接成功但未返回可用模型" }, 400);
+            }
+            const rawConfig = await loadRawConfig(root).catch(() => ({}));
+            const preferredModel = typeof rawConfig.llm?.defaultModel === "string"
+                ? String(rawConfig.llm.defaultModel)
+                : undefined;
+            const sampleModel = models.find((m) => m.id === preferredModel)?.id
+                ?? models.find((m) => m.id === "gpt-5.4")?.id
+                ?? models[0]?.id;
+            if (sampleModel) {
+                const client = createLLMClient({
+                    provider: service === "anthropic" ? "anthropic" : "openai",
+                    service: isCustomServiceId(service) ? "custom" : service,
+                    configSource: "studio",
+                    baseUrl: resolvedBaseUrl,
+                    apiKey: apiKey.trim(),
+                    model: sampleModel,
+                    temperature: 0.7,
+                    maxTokens: 64,
+                    thinkingBudget: 0,
+                    apiFormat: apiFormat ?? "chat",
+                    stream: stream ?? true,
+                });
+                try {
+                    await chatCompletion(client, sampleModel, [{ role: "user", content: "ping" }], { maxTokens: 5 });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return c.json({ ok: false, error: `模型列表可读，但生成测试失败：${message}` }, 400);
+                }
+            }
+            return c.json({ ok: true, modelCount: models.length, models: models.slice(0, 50) });
+        }
+        catch (err) {
+            if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+                return c.json({ ok: false, error: `连接超时：无法访问 ${modelsUrl}` }, 400);
+            }
+            return c.json({ ok: false, error: `连接失败: ${err?.message ?? String(err)}` }, 400);
+        }
+    });
+    app.put("/api/v1/services/:service/secret", async (c) => {
+        const service = c.req.param("service");
+        const { apiKey } = await c.req.json();
+        const secrets = await loadSecrets(root);
+        if (apiKey?.trim()) {
+            secrets.services[service] = { apiKey: apiKey.trim() };
+        }
+        else {
+            delete secrets.services[service];
+        }
+        await saveSecrets(root, secrets);
+        return c.json({ ok: true });
+    });
+    app.get("/api/v1/services/:service/secret", async (c) => {
+        const service = c.req.param("service");
+        const secrets = await loadSecrets(root);
+        return c.json({
+            apiKey: secrets.services[service]?.apiKey ?? "",
+        });
+    });
+    app.get("/api/v1/services/:service/models", async (c) => {
+        const service = c.req.param("service");
+        const apiKey = c.req.query("apiKey") || await getServiceApiKey(root, service);
+        // No key = no models (don't fallback to built-in list)
+        if (!apiKey)
+            return c.json({ models: [] });
+        const resolvedBaseUrl = await resolveConfiguredServiceBaseUrl(root, service);
+        if (!resolvedBaseUrl)
+            return c.json({ models: [] });
+        // Call real API only
+        let models = [];
+        try {
+            const modelsUrl = resolvedBaseUrl.replace(/\/$/, "") + "/models";
+            const res = await fetch(modelsUrl, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (res.ok) {
+                const json = await res.json();
+                models = (json.data ?? []).map((m) => ({ id: m.id, name: m.id }));
+            }
+        }
+        catch { /* timeout or network error — return empty */ }
+        return c.json({ models });
+    });
     // --- Project info ---
-    app.get("/api/project", async (c) => {
+    app.get("/api/v1/project", async (c) => {
         const currentConfig = await loadCurrentProjectConfig({ requireApiKey: false });
         // Check if language was explicitly set in inkos.json (not just the schema default)
         const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
@@ -337,7 +729,7 @@ export function createStudioServer(initialConfig, root) {
         });
     });
     // --- Config editing ---
-    app.put("/api/project", async (c) => {
+    app.put("/api/v1/project", async (c) => {
         const updates = await c.req.json();
         const configPath = join(root, "inkos.json");
         try {
@@ -365,7 +757,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Truth files browser ---
-    app.get("/api/books/:id/truth", async (c) => {
+    app.get("/api/v1/books/:id/truth", async (c) => {
         const id = c.req.param("id");
         const bookDir = state.bookDir(id);
         const storyDir = join(bookDir, "story");
@@ -384,12 +776,12 @@ export function createStudioServer(initialConfig, root) {
     });
     // --- Daemon control ---
     let schedulerInstance = null;
-    app.get("/api/daemon", (c) => {
+    app.get("/api/v1/daemon", (c) => {
         return c.json({
             running: schedulerInstance?.isRunning ?? false,
         });
     });
-    app.post("/api/daemon/start", async (c) => {
+    app.post("/api/v1/daemon/start", async (c) => {
         if (schedulerInstance?.isRunning) {
             return c.json({ error: "Daemon already running" }, 400);
         }
@@ -429,7 +821,7 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 500);
         }
     });
-    app.post("/api/daemon/stop", (c) => {
+    app.post("/api/v1/daemon/stop", (c) => {
         if (!schedulerInstance?.isRunning) {
             return c.json({ error: "Daemon not running" }, 400);
         }
@@ -439,7 +831,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true, running: false });
     });
     // --- Logs ---
-    app.get("/api/logs", async (c) => {
+    app.get("/api/v1/logs", async (c) => {
         const logPath = join(root, "inkos.log");
         try {
             const content = await readFile(logPath, "utf-8");
@@ -459,7 +851,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Agent chat ---
-    app.get("/api/interaction/session", async (c) => {
+    app.get("/api/v1/interaction/session", async (c) => {
         const session = await loadProjectSession(root);
         const activeBookId = await resolveSessionActiveBook(root, session);
         return c.json({
@@ -469,38 +861,307 @@ export function createStudioServer(initialConfig, root) {
             activeBookId,
         });
     });
-    app.post("/api/agent", async (c) => {
-        const { instruction, activeBookId } = await c.req.json();
+    // -- Per-book session endpoints --
+    app.get("/api/v1/sessions", async (c) => {
+        const bookId = c.req.query("bookId");
+        const sessions = await listBookSessions(root, bookId === undefined ? null : bookId === "null" ? null : bookId);
+        return c.json({ sessions: sessions.map((s) => ({
+                sessionId: s.sessionId,
+                bookId: s.bookId,
+                messageCount: s.messages.length,
+                createdAt: s.createdAt,
+                updatedAt: s.updatedAt,
+            })) });
+    });
+    app.get("/api/v1/sessions/:sessionId", async (c) => {
+        const session = await loadBookSession(root, c.req.param("sessionId"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        return c.json({ session });
+    });
+    app.post("/api/v1/sessions", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const bookId = body.bookId ?? null;
+        const session = await findOrCreateBookSession(root, bookId);
+        return c.json({ session });
+    });
+    app.post("/api/v1/agent", async (c) => {
+        const { instruction, activeBookId, sessionId: reqSessionId, model: reqModel, service: reqService } = await c.req.json();
+        const sessionId = reqSessionId;
         if (!instruction?.trim()) {
             return c.json({ error: "No instruction provided" }, 400);
         }
         broadcast("agent:start", { instruction, activeBookId });
         try {
-            const pipeline = new PipelineRunner(await buildPipelineConfig());
-            const tools = createInteractionToolsFromDeps(pipeline, state);
-            const result = await processProjectInteractionInput({
+            // Load config + create LLM client (pipeline created after model resolution)
+            const config = await loadCurrentProjectConfig({ requireApiKey: false });
+            const client = createLLMClient(config.llm);
+            // Resolve or create BookSession for history
+            let bookSession;
+            if (sessionId) {
+                bookSession =
+                    (await loadBookSession(root, sessionId)) ??
+                        (await findOrCreateBookSession(root, activeBookId ?? null));
+            }
+            else {
+                bookSession = await findOrCreateBookSession(root, activeBookId ?? null);
+            }
+            // Build initial message context from persisted session
+            const initialMessages = bookSession.messages
+                .filter((m) => m.role === "user" || m.role === "assistant")
+                .map((m) => ({ role: m.role, content: m.content }));
+            // Resolve model — multi-service resolution
+            let resolvedModel;
+            let resolvedApiKey;
+            if (reqService && reqModel) {
+                // 1. Frontend explicitly selected a service+model — fail loudly if no key
+                try {
+                    const configuredEntry = await resolveConfiguredServiceEntry(root, reqService);
+                    const resolved = await resolveServiceModel(reqService, reqModel, root, await resolveConfiguredServiceBaseUrl(root, reqService), configuredEntry?.apiFormat);
+                    resolvedModel = resolved.model;
+                    resolvedApiKey = resolved.apiKey;
+                }
+                catch (e) {
+                    const msg = e?.message ?? String(e);
+                    if (/API key/i.test(msg)) {
+                        return c.json({
+                            error: `请先为 ${reqService} 配置 API Key`,
+                            response: `请先在模型配置中为 ${reqService} 填写 API Key，然后再试。`,
+                        }, 400);
+                    }
+                    throw e;
+                }
+            }
+            if (!resolvedModel) {
+                // 2. Try defaultModel from new config format
+                const rawConfig = config.llm;
+                const defaultModel = rawConfig.defaultModel;
+                const servicesArr = normalizeServiceConfig(rawConfig.services);
+                const firstService = servicesArr[0];
+                if (firstService?.service && defaultModel) {
+                    try {
+                        const resolved = await resolveServiceModel(serviceConfigKey(firstService), defaultModel, root, firstService.baseUrl, firstService.apiFormat);
+                        resolvedModel = resolved.model;
+                        resolvedApiKey = resolved.apiKey;
+                    }
+                    catch { /* fall through */ }
+                }
+            }
+            if (!resolvedModel) {
+                // 3. Try first connected service from secrets
+                const secrets = await loadSecrets(root);
+                for (const [svcName, svcData] of Object.entries(secrets.services)) {
+                    if (svcData?.apiKey) {
+                        try {
+                            const models = await listModelsForService(svcName, svcData.apiKey);
+                            if (models.length > 0) {
+                                const configuredEntry = await resolveConfiguredServiceEntry(root, svcName);
+                                const resolved = await resolveServiceModel(svcName, models[0].id, root, await resolveConfiguredServiceBaseUrl(root, svcName), configuredEntry?.apiFormat);
+                                resolvedModel = resolved.model;
+                                resolvedApiKey = resolved.apiKey;
+                                break;
+                            }
+                        }
+                        catch { /* try next */ }
+                    }
+                }
+            }
+            if (!resolvedModel) {
+                // 4. Legacy fallback: use createLLMClient
+                resolvedModel = client._piModel
+                    ? client._piModel
+                    : { provider: config.llm.provider ?? "anthropic", modelId: config.llm.model };
+                resolvedApiKey = client._apiKey;
+            }
+            const model = resolvedModel;
+            const agentApiKey = resolvedApiKey;
+            const configuredEntry = reqService ? await resolveConfiguredServiceEntry(root, reqService) : undefined;
+            // Create pipeline with resolved model (so sub_agent tools use the frontend-selected model)
+            // Don't spread config.llm — its baseUrl/provider belong to the old service.
+            // Let createLLMClient resolve baseUrl from the service preset.
+            const pipelineClient = (reqService && reqModel && resolvedApiKey)
+                ? createLLMClient({
+                    ...config.llm,
+                    service: configuredEntry?.service ?? reqService,
+                    model: reqModel,
+                    apiKey: resolvedApiKey,
+                    ...(configuredEntry?.apiFormat ? { apiFormat: configuredEntry.apiFormat } : {}),
+                    ...(configuredEntry?.stream !== undefined ? { stream: configuredEntry.stream } : {}),
+                    baseUrl: configuredEntry?.baseUrl ?? "",
+                })
+                : client;
+            const pipeline = new PipelineRunner(await buildPipelineConfig({
+                client: pipelineClient,
+                model: reqModel ?? config.llm.model,
+                currentConfig: config,
+            }));
+            // Run pi-agent session
+            const collectedToolExecs = [];
+            const result = await runAgentSession({
+                model,
+                apiKey: agentApiKey,
+                pipeline,
                 projectRoot: root,
-                input: instruction,
-                tools,
-                activeBookId,
+                bookId: activeBookId ?? null,
+                sessionId: bookSession.sessionId,
+                language: config.language ?? "zh",
+                onEvent: (event) => {
+                    if (event.type === "message_update") {
+                        const ame = event.assistantMessageEvent;
+                        if (ame.type === "text_delta") {
+                            broadcast("draft:delta", { text: ame.delta });
+                        }
+                        else if (ame.type === "thinking_delta") {
+                            broadcast("thinking:delta", { text: ame.delta });
+                        }
+                        else if (ame.type === "thinking_start") {
+                            broadcast("thinking:start", {});
+                        }
+                        else if (ame.type === "thinking_end") {
+                            broadcast("thinking:end", {});
+                        }
+                    }
+                    if (event.type === "tool_execution_start") {
+                        const args = event.args;
+                        const agent = event.toolName === "sub_agent" ? args?.agent : undefined;
+                        const stages = agent ? (PIPELINE_STAGES[agent] ?? []) : [];
+                        collectedToolExecs.push({
+                            id: event.toolCallId,
+                            tool: event.toolName,
+                            agent,
+                            label: resolveToolLabel(event.toolName, agent),
+                            status: "running",
+                            args,
+                            stages: stages.length > 0
+                                ? stages.map(l => ({ label: l, status: "pending" }))
+                                : undefined,
+                            startedAt: Date.now(),
+                        });
+                        broadcast("tool:start", {
+                            id: event.toolCallId,
+                            tool: event.toolName,
+                            args,
+                            stages,
+                        });
+                    }
+                    if (event.type === "tool_execution_update") {
+                        broadcast("tool:update", { tool: event.toolName, partialResult: event.partialResult });
+                    }
+                    if (event.type === "tool_execution_end") {
+                        const exec = collectedToolExecs.find(t => t.id === event.toolCallId);
+                        if (exec) {
+                            exec.status = event.isError ? "error" : "completed";
+                            exec.completedAt = Date.now();
+                            exec.stages = exec.stages?.map(s => ({ ...s, status: "completed" }));
+                            if (event.isError)
+                                exec.error = extractToolError(event.result);
+                            else
+                                exec.result = summarizeResult(event.result);
+                        }
+                        broadcast("tool:end", {
+                            id: event.toolCallId,
+                            tool: event.toolName,
+                            result: event.result,
+                            isError: event.isError,
+                        });
+                    }
+                },
+            }, instruction, initialMessages);
+            // Persist user + assistant messages to BookSession
+            bookSession = appendBookSessionMessage(bookSession, {
+                role: "user",
+                content: instruction,
+                timestamp: Date.now(),
+            });
+            if (result.responseText) {
+                const lastAssistant = result.messages?.filter((m) => m.role === "assistant").pop();
+                const thinking = lastAssistant?.thinking;
+                bookSession = appendBookSessionMessage(bookSession, {
+                    role: "assistant",
+                    content: result.responseText,
+                    ...(thinking ? { thinking } : {}),
+                    ...(collectedToolExecs.length > 0 ? { toolExecutions: collectedToolExecs } : {}),
+                    timestamp: Date.now() + 1,
+                });
+            }
+            if (!result.responseText) {
+                try {
+                    const fallbackClient = createLLMClient({
+                        ...config.llm,
+                        service: configuredEntry?.service ?? reqService ?? config.llm.service,
+                        model: reqModel ?? config.llm.model,
+                        apiKey: agentApiKey ?? config.llm.apiKey,
+                        baseUrl: configuredEntry?.baseUrl ?? config.llm.baseUrl,
+                        ...(configuredEntry?.apiFormat ? { apiFormat: configuredEntry.apiFormat } : {}),
+                        ...(configuredEntry?.stream !== undefined ? { stream: configuredEntry.stream } : {}),
+                    });
+                    const fallback = await chatCompletion(fallbackClient, reqModel ?? config.llm.model, [
+                        { role: "system", content: buildAgentSystemPrompt(activeBookId ?? null, config.language ?? "zh") },
+                        { role: "user", content: instruction },
+                    ], { maxTokens: 256 });
+                    if (fallback.content?.trim()) {
+                        bookSession = appendBookSessionMessage(bookSession, {
+                            role: "assistant",
+                            content: fallback.content,
+                            timestamp: Date.now() + 1,
+                        });
+                        await persistBookSession(root, bookSession);
+                        return c.json({
+                            response: fallback.content,
+                            session: { sessionId: bookSession.sessionId },
+                        });
+                    }
+                }
+                catch {
+                    // fall through to probe-based diagnosis below
+                }
+                try {
+                    const probeClient = createLLMClient({
+                        ...config.llm,
+                        service: configuredEntry?.service ?? reqService ?? config.llm.service,
+                        model: reqModel ?? config.llm.model,
+                        apiKey: agentApiKey ?? config.llm.apiKey,
+                        baseUrl: configuredEntry?.baseUrl ?? config.llm.baseUrl,
+                        ...(configuredEntry?.apiFormat ? { apiFormat: configuredEntry.apiFormat } : {}),
+                        ...(configuredEntry?.stream !== undefined ? { stream: configuredEntry.stream } : {}),
+                    });
+                    await chatCompletion(probeClient, reqModel ?? config.llm.model, [{ role: "user", content: "ping" }], { maxTokens: 5 });
+                }
+                catch (probeError) {
+                    const probeMessage = probeError instanceof Error ? probeError.message : String(probeError);
+                    return c.json({
+                        error: { code: "AGENT_EMPTY_RESPONSE", message: probeMessage },
+                        response: probeMessage,
+                    }, 502);
+                }
+                const emptyMessage = "模型未返回文本内容。请检查协议类型（chat/responses）、流式开关或上游服务兼容性。";
+                return c.json({
+                    error: { code: "AGENT_EMPTY_RESPONSE", message: emptyMessage },
+                    response: emptyMessage,
+                }, 502);
+            }
+            await persistBookSession(root, bookSession);
+            broadcast("agent:complete", { instruction, activeBookId });
+            return c.json({
+                response: result.responseText,
+                session: { sessionId: bookSession.sessionId },
             });
-            const response = result.responseText ?? "Acknowledged.";
-            broadcast("agent:complete", { instruction, activeBookId, response });
-            return c.json({ response, session: result.session, request: result.request });
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             broadcast("agent:error", { instruction, activeBookId, error: msg });
-            return c.json({
-                error: {
-                    code: "INTERACTION_ERROR",
-                    message: msg,
-                },
-            }, 500);
+            // Agent busy — return 429 with user-friendly message
+            if (/already processing|prompt.*queue/i.test(msg)) {
+                return c.json({
+                    error: { code: "AGENT_BUSY", message: "正在处理中，请等待当前操作完成" },
+                    response: "正在处理中，请等待当前操作完成后再发送。",
+                }, 429);
+            }
+            return c.json({ error: { code: "AGENT_ERROR", message: msg } }, 500);
         }
     });
     // --- Language setup ---
-    app.post("/api/project/language", async (c) => {
+    app.post("/api/v1/project/language", async (c) => {
         const { language } = await c.req.json();
         const configPath = join(root, "inkos.json");
         try {
@@ -516,7 +1177,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Audit ---
-    app.post("/api/books/:id/audit/:chapter", async (c) => {
+    app.post("/api/v1/books/:id/audit/:chapter", async (c) => {
         const id = c.req.param("id");
         const chapterNum = parseInt(c.req.param("chapter"), 10);
         const bookDir = state.bookDir(id);
@@ -548,7 +1209,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Revise ---
-    app.post("/api/books/:id/revise/:chapter", async (c) => {
+    app.post("/api/v1/books/:id/revise/:chapter", async (c) => {
         const id = c.req.param("id");
         const chapterNum = parseInt(c.req.param("chapter"), 10);
         const bookDir = state.bookDir(id);
@@ -578,7 +1239,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Export ---
-    app.get("/api/books/:id/export", async (c) => {
+    app.get("/api/v1/books/:id/export", async (c) => {
         const id = c.req.param("id");
         const format = (c.req.query("format") ?? "txt");
         const approvedOnly = c.req.query("approvedOnly") === "true";
@@ -634,7 +1295,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Export to file (save to project dir) ---
-    app.post("/api/books/:id/export-save", async (c) => {
+    app.post("/api/v1/books/:id/export-save", async (c) => {
         const id = c.req.param("id");
         const { format, approvedOnly } = await c.req.json().catch(() => ({ format: "txt", approvedOnly: false }));
         const fmt = format ?? "txt";
@@ -667,7 +1328,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Genre detail + copy ---
-    app.get("/api/genres/:id", async (c) => {
+    app.get("/api/v1/genres/:id", async (c) => {
         const genreId = c.req.param("id");
         try {
             const { readGenreProfile } = await import("@actalk/inkos-core");
@@ -678,7 +1339,7 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 404);
         }
     });
-    app.post("/api/genres/:id/copy", async (c) => {
+    app.post("/api/v1/genres/:id/copy", async (c) => {
         const genreId = c.req.param("id");
         if (/[/\\\0]/.test(genreId) || genreId.includes("..")) {
             throw new ApiError(400, "INVALID_GENRE_ID", `Invalid genre ID: "${genreId}"`);
@@ -697,11 +1358,11 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Model overrides ---
-    app.get("/api/project/model-overrides", async (c) => {
+    app.get("/api/v1/project/model-overrides", async (c) => {
         const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
         return c.json({ overrides: raw.modelOverrides ?? {} });
     });
-    app.put("/api/project/model-overrides", async (c) => {
+    app.put("/api/v1/project/model-overrides", async (c) => {
         const { overrides } = await c.req.json();
         const configPath = join(root, "inkos.json");
         const raw = JSON.parse(await readFile(configPath, "utf-8"));
@@ -711,11 +1372,11 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true });
     });
     // --- Notify channels ---
-    app.get("/api/project/notify", async (c) => {
+    app.get("/api/v1/project/notify", async (c) => {
         const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
         return c.json({ channels: raw.notify ?? [] });
     });
-    app.put("/api/project/notify", async (c) => {
+    app.put("/api/v1/project/notify", async (c) => {
         const { channels } = await c.req.json();
         const configPath = join(root, "inkos.json");
         const raw = JSON.parse(await readFile(configPath, "utf-8"));
@@ -725,7 +1386,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true });
     });
     // --- AIGC Detection ---
-    app.post("/api/books/:id/detect/:chapter", async (c) => {
+    app.post("/api/v1/books/:id/detect/:chapter", async (c) => {
         const id = c.req.param("id");
         const chapterNum = parseInt(c.req.param("chapter"), 10);
         const bookDir = state.bookDir(id);
@@ -746,7 +1407,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Truth file edit ---
-    app.put("/api/books/:id/truth/:file", async (c) => {
+    app.put("/api/v1/books/:id/truth/:file", async (c) => {
         const id = c.req.param("id");
         const file = c.req.param("file");
         if (!TRUTH_FILES.includes(file)) {
@@ -763,7 +1424,7 @@ export function createStudioServer(initialConfig, root) {
     // NEW ENDPOINTS — CLI parity
     // =============================================
     // --- Book Delete ---
-    app.delete("/api/books/:id", async (c) => {
+    app.delete("/api/v1/books/:id", async (c) => {
         const id = c.req.param("id");
         const bookDir = state.bookDir(id);
         try {
@@ -777,7 +1438,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Book Update ---
-    app.put("/api/books/:id", async (c) => {
+    app.put("/api/v1/books/:id", async (c) => {
         const id = c.req.param("id");
         const updates = await c.req.json();
         try {
@@ -798,7 +1459,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Write Rewrite (specific chapter) ---
-    app.post("/api/books/:id/rewrite/:chapter", async (c) => {
+    app.post("/api/v1/books/:id/rewrite/:chapter", async (c) => {
         const id = c.req.param("id");
         const chapterNum = parseInt(c.req.param("chapter"), 10);
         const body = await c.req
@@ -819,7 +1480,7 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 500);
         }
     });
-    app.post("/api/books/:id/resync/:chapter", async (c) => {
+    app.post("/api/v1/books/:id/resync/:chapter", async (c) => {
         const id = c.req.param("id");
         const chapterNum = parseInt(c.req.param("chapter"), 10);
         const body = await c.req
@@ -837,7 +1498,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Detect All chapters ---
-    app.post("/api/books/:id/detect-all", async (c) => {
+    app.post("/api/v1/books/:id/detect-all", async (c) => {
         const id = c.req.param("id");
         const bookDir = state.bookDir(id);
         try {
@@ -858,7 +1519,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Detect Stats ---
-    app.get("/api/books/:id/detect/stats", async (c) => {
+    app.get("/api/v1/books/:id/detect/stats", async (c) => {
         const id = c.req.param("id");
         try {
             const { loadDetectionHistory, analyzeDetectionInsights } = await import("@actalk/inkos-core");
@@ -872,7 +1533,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Genre Create ---
-    app.post("/api/genres/create", async (c) => {
+    app.post("/api/v1/genres/create", async (c) => {
         const body = await c.req.json();
         if (!body.id || !body.name) {
             return c.json({ error: "id and name are required" }, 400);
@@ -904,7 +1565,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true, id: body.id });
     });
     // --- Genre Edit ---
-    app.put("/api/genres/:id", async (c) => {
+    app.put("/api/v1/genres/:id", async (c) => {
         const genreId = c.req.param("id");
         if (/[/\\\0]/.test(genreId) || genreId.includes("..")) {
             throw new ApiError(400, "INVALID_GENRE_ID", `Invalid genre ID: "${genreId}"`);
@@ -935,7 +1596,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true, id: genreId });
     });
     // --- Genre Delete (project-level only) ---
-    app.delete("/api/genres/:id", async (c) => {
+    app.delete("/api/v1/genres/:id", async (c) => {
         const genreId = c.req.param("id");
         if (/[/\\\0]/.test(genreId) || genreId.includes("..")) {
             throw new ApiError(400, "INVALID_GENRE_ID", `Invalid genre ID: "${genreId}"`);
@@ -951,7 +1612,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Style Analyze ---
-    app.post("/api/style/analyze", async (c) => {
+    app.post("/api/v1/style/analyze", async (c) => {
         const { text, sourceName } = await c.req.json();
         if (!text?.trim())
             return c.json({ error: "text is required" }, 400);
@@ -965,7 +1626,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Style Import to Book ---
-    app.post("/api/books/:id/style/import", async (c) => {
+    app.post("/api/v1/books/:id/style/import", async (c) => {
         const id = c.req.param("id");
         const { text, sourceName } = await c.req.json();
         broadcast("style:start", { bookId: id });
@@ -981,7 +1642,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Import Chapters ---
-    app.post("/api/books/:id/import/chapters", async (c) => {
+    app.post("/api/v1/books/:id/import/chapters", async (c) => {
         const id = c.req.param("id");
         const { text, splitRegex } = await c.req.json();
         if (!text?.trim())
@@ -1001,7 +1662,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Import Canon ---
-    app.post("/api/books/:id/import/canon", async (c) => {
+    app.post("/api/v1/books/:id/import/canon", async (c) => {
         const id = c.req.param("id");
         const { fromBookId } = await c.req.json();
         if (!fromBookId)
@@ -1019,7 +1680,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Fanfic Init ---
-    app.post("/api/fanfic/init", async (c) => {
+    app.post("/api/v1/fanfic/init", async (c) => {
         const body = await c.req.json();
         if (!body.title || !body.sourceText) {
             return c.json({ error: "title and sourceText are required" }, 400);
@@ -1052,7 +1713,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Fanfic Show (read canon) ---
-    app.get("/api/books/:id/fanfic", async (c) => {
+    app.get("/api/v1/books/:id/fanfic", async (c) => {
         const id = c.req.param("id");
         const bookDir = state.bookDir(id);
         try {
@@ -1064,7 +1725,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Fanfic Refresh ---
-    app.post("/api/books/:id/fanfic/refresh", async (c) => {
+    app.post("/api/v1/books/:id/fanfic/refresh", async (c) => {
         const id = c.req.param("id");
         const { sourceText, sourceName } = await c.req.json();
         if (!sourceText?.trim())
@@ -1083,7 +1744,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Radar Scan ---
-    app.post("/api/radar/scan", async (c) => {
+    app.post("/api/v1/radar/scan", async (c) => {
         broadcast("radar:start", {});
         try {
             const pipeline = new PipelineRunner(await buildPipelineConfig());
@@ -1097,7 +1758,7 @@ export function createStudioServer(initialConfig, root) {
         }
     });
     // --- Doctor (environment health check) ---
-    app.get("/api/doctor", async (c) => {
+    app.get("/api/v1/doctor", async (c) => {
         const { existsSync } = await import("node:fs");
         const { GLOBAL_ENV_PATH } = await import("@actalk/inkos-core");
         const checks = {
@@ -1127,7 +1788,7 @@ export function createStudioServer(initialConfig, root) {
 }
 // --- Standalone runner ---
 export async function startStudioServer(root, port = 4567, options) {
-    const config = await loadProjectConfig(root);
+    const config = await loadProjectConfig(root, { requireApiKey: false });
     const app = createStudioServer(config, root);
     // Serve frontend static files — single process for API + frontend
     if (options?.staticDir) {
@@ -1161,7 +1822,7 @@ export async function startStudioServer(root, port = 4567, options) {
         if (existsSync(indexPath)) {
             const indexHtml = await readFileFs(indexPath, "utf-8");
             app.get("*", (c) => {
-                if (c.req.path.startsWith("/api/"))
+                if (c.req.path.startsWith("/api/v1/"))
                     return c.notFound();
                 return c.html(indexHtml);
             });