@waterwx/dsh-novel-forge 1.3.2-alpha → 1.3.3-alpha

package/lib/index.js

@@ -1,9 +1,9 @@
-import { homedir, tmpdir } from "node:os";
-import { basename, extname, join, resolve, sep } from "node:path";
 import z from "schemastery";
 import { spawn } from "node:child_process";
 import { appendFileSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, join, resolve, sep } from "node:path";
 import { randomBytes } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
 import { BlockAssembler, ReasoningEffortId, createAssistantMessage, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { strFromU8, unzipSync } from "fflate";
 //#region src/assets.ts
@@ -3485,6 +3485,232 @@ async function withModelFallback(input, run) {
 		}
 	}
 }
+//#endregion
+//#region src/model-capability.ts
+const KIMI_SOURCE = "https://platform.kimi.com/docs/api/models-overview.md";
+/**
+* 把模型 id 归一化为「模型身份」。
+*
+* 处理：去空白与首尾斜杠、小写、剥掉供应商前缀（`kimi/kimi-k3` → `kimi-k3`）。
+* @param model - 原始模型 id。
+* @returns 归一化后的身份（小写、无前缀）。
+*/
+function canonicalModelId(model) {
+	if (typeof model !== "string") return "";
+	const trimmed = model.trim().toLowerCase().replace(/^\/+|\/+$/g, "");
+	if (trimmed === "") return "";
+	const segments = trimmed.split("/");
+	return segments[segments.length - 1] ?? "";
+}
+const RULES = [
+	{
+		rule: "kimi-k3-fixed-temperature",
+		source: KIMI_SOURCE,
+		matches: (m) => /^kimi[-_.]?k-?3(?:[-_.]|$)/.test(m),
+		capability: {
+			fixedTemperature: 1,
+			supportsReasoning: true,
+			reasoningControl: "reasoning-effort"
+		}
+	},
+	{
+		rule: "kimi-k2.7-code-fixed-temperature",
+		source: KIMI_SOURCE,
+		matches: (m) => /^kimi[-_.]?k-?2[-_.]?7(?:[-_.]|$)/.test(m),
+		capability: {
+			fixedTemperature: 1,
+			supportsReasoning: false,
+			reasoningControl: "thinking",
+			reasoningForcedOff: true
+		}
+	},
+	{
+		rule: "kimi-k2.6-temperature-by-thinking",
+		source: KIMI_SOURCE,
+		matches: (m) => /^kimi[-_.]?k-?2[-_.]?6(?:[-_.]|$)/.test(m),
+		capability: {
+			fixedTemperature: 1,
+			supportsReasoning: false,
+			reasoningControl: "thinking"
+		}
+	},
+	{
+		rule: "deepseek-reasoner-fixed-temperature",
+		source: "OpenAI 兼容约定：DeepSeek R1/reasoner 不接受自定义 temperature",
+		matches: (m) => /^deepseek[-_.]?(r1|reasoner)(?:[-_.]|$)/.test(m),
+		capability: {
+			fixedTemperature: 1,
+			supportsReasoning: true,
+			reasoningControl: "reasoning-effort"
+		}
+	}
+];
+/**
+* 解析一条模型的能力约束。
+* @param model - 模型 id（可能带供应商前缀）。
+* @returns 命中的能力；无约束时返回 undefined。
+*/
+function resolveModelCapability(model) {
+	const canonical = canonicalModelId(model);
+	if (canonical === "") return void 0;
+	for (const rule of RULES) if (rule.matches(canonical)) return {
+		...rule.capability,
+		rule: rule.rule,
+		source: rule.source
+	};
+}
+/**
+* 把请求参数收敛到模型允许的范围。
+*
+* @param params - 调用方希望使用的参数。
+* @param model - 实际要调用的模型 id（应传**实际模型**；换备用模型后需重算）。
+* @param options - `structured: true` 表示这是严格结构化输出任务；
+*   `omitFixedTemperature: true` 表示调用方可以不传温度（推荐，厂商建议如此），
+*   此时固定温度会收敛为 undefined 而不是钳到固定值。
+* @returns 最终请求值与被调整项。
+*/
+function convergeRequestParams(params, model, options = {}) {
+	const capability = resolveModelCapability(model);
+	const adjustments = [];
+	let temperature = params.temperature;
+	let reasoningEffort = params.reasoningEffort;
+	if (capability?.fixedTemperature !== void 0) {
+		const fixed = capability.fixedTemperature;
+		if (options.omitFixedTemperature === true) {
+			if (temperature !== void 0) adjustments.push(`temperature: ${temperature} -> 省略（${capability.rule} 固定 ${fixed}，厂商建议不要显式传入）`);
+			temperature = void 0;
+		} else if (temperature !== fixed) {
+			adjustments.push(`temperature: ${temperature} -> ${fixed}（${capability.rule} 固定值）`);
+			temperature = fixed;
+		}
+	} else if (capability !== void 0) {
+		const min = capability.minTemperature ?? 0;
+		const max = capability.maxTemperature ?? 2;
+		const clamped = Math.min(max, Math.max(min, temperature ?? min));
+		if (clamped !== temperature) {
+			adjustments.push(`temperature: ${temperature} -> ${clamped}（${capability.rule} 取值范围）`);
+			temperature = clamped;
+		}
+	}
+	if (capability?.supportsReasoning === false && reasoningEffort !== void 0) {
+		if (reasoningEffort !== "off") adjustments.push(`reasoningEffort: ${reasoningEffort} -> 省略（${capability.rule} 不支持该参数）`);
+		reasoningEffort = void 0;
+	}
+	if (options.structured === true && capability?.reasoningForcedOff === true && reasoningEffort !== void 0) {
+		adjustments.push(`reasoningEffort: ${reasoningEffort} -> off（结构化任务强制关闭思考）`);
+		reasoningEffort = "off";
+		if (capability.reasoningControl === "thinking") reasoningEffort = void 0;
+	}
+	return {
+		temperature,
+		reasoningEffort,
+		adjustments,
+		...capability === void 0 ? {} : {
+			rule: capability.rule,
+			source: capability.source
+		}
+	};
+}
+//#endregion
+//#region src/output-budget.ts
+/**
+* 数值口径：以**本插件真实产出字段的体积**折算，不是照搬参考项目的数字
+* （它的卷战略字段与本插件的章节字段结构不同，直接套用会造成新的截断）。
+*
+* 折算假设：中文约 1.5-2 token/字；账本式 JSON 的键名与括号再占约 15%。
+* 例如单章条目 = 标题(≤40) + 摘要(≤300) + 本章目标(≤200) + beats + 最多 4 条
+* payoff 指令 → 约 250-400 字 → **约 350 token/章**。若字段合同调整，这里必须同步。
+*/
+const SPECS = {
+	"volume-strategy": {
+		floor: 1800,
+		base: 1200,
+		perUnit: 220,
+		ceiling: 6e3
+	},
+	"chapter-list": {
+		floor: 2500,
+		base: 2e3,
+		perUnit: 350,
+		ceiling: 2e4
+	},
+	"character-cast": {
+		floor: 1500,
+		base: 1e3,
+		perUnit: 150,
+		ceiling: 8e3
+	},
+	"item-list": {
+		floor: 1e3,
+		base: 800,
+		perUnit: 60,
+		ceiling: 4e3
+	},
+	analysis: {
+		floor: 3e3,
+		base: 2e3,
+		perUnit: 12,
+		ceiling: 16e3
+	}
+};
+/**
+* 取出与任务类型相关的那一个规模量。
+* @param kind - 任务类型。
+* @param scope - 规模描述。
+* @returns 单位数；分析类返回千字单位（向上取整）。
+*/
+function scopeUnits(kind, scope) {
+	const positive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+	switch (kind) {
+		case "volume-strategy": return positive(scope.volumes);
+		case "chapter-list": return positive(scope.chapters);
+		case "character-cast": return positive(scope.characters);
+		case "item-list": return positive(scope.items);
+		case "analysis": return Math.ceil(positive(scope.sourceChars) / 1e3);
+	}
+}
+/**
+* 按规模推算输出额度。
+* @param kind - 结构化任务类型。
+* @param scope - 本次任务的规模（缺省时按最小规模处理）。
+* @returns 建议的 `maxTokens`，落在该类型的 [floor, ceiling] 内。
+*/
+function resolveOutputBudget(kind, scope = {}) {
+	const spec = SPECS[kind];
+	const raw = spec.base + scopeUnits(kind, scope) * spec.perUnit;
+	return Math.min(spec.ceiling, Math.max(spec.floor, Math.round(raw)));
+}
+/**
+* 结构化字段长度合同 —— 与 prompt 里的长度声明必须逐项一致。
+*
+* 两边同步的理由：只写进 schema，模型不知道就会超长被拒；只写进 prompt，模型
+* 偶尔超长没人拦。本表是单一数据源。
+*/
+const STRUCTURED_FIELD_LIMITS = {
+	/** 分卷战略：书级阶梯类字段。 */
+	volumeLadder: 160,
+	/** 分卷战略：每卷定位标签。 */
+	volumeRoleLabel: 32,
+	/** 分卷战略：每卷核心回报 / 升级焦点。 */
+	volumeReward: 64,
+	/** 分卷战略：不确定项原因。 */
+	volumeUncertaintyReason: 64,
+	/** 章节计划：单章标题。 */
+	chapterTitle: 40,
+	/** 章节计划：单章摘要。 */
+	chapterSummary: 300,
+	/** 章节计划：本章目标。 */
+	chapterGoal: 200
+};
+/**
+* 把长度合同渲染成可直接塞进 system prompt 的一句话，避免 prompt 与表漂移。
+* @param entries - 要声明的字段（描述 + 上限），按声明顺序渲染。
+* @returns 形如「为保证输出完整：A 不超过 160 字；B 不超过 64 字。」的中文说明。
+*/
+function renderLengthContract(entries) {
+	if (entries.length === 0) return "";
+	return `为保证输出完整：${entries.map(([label, limit]) => `${label}不超过 ${limit} 字`).join("；")}。每个字段只保留完成本阶段决策所需的信息，写完后立即结束输出，不要展开细纲或重复说明。`;
+}
 /**
 * 本项目设计的参考曲线形状（0-100 的采样序列）。
 * 只描述"形状"，不含任何外部数值表。
@@ -4649,7 +4875,7 @@ const COMPLIANCE_REDLINES = [
 	"8. 不得出现侮辱或者诽谤他人、侵害他人合法权益的内容（不得以真实人物、组织为原型进行侮辱或影射攻击）。",
 	"9. 不得出现法律法规禁止的其他内容。"
 ];
-/** 审稿维度取值（与 review-policy.ts 的 REVIEW_DIMENSIONS 对齐，用于归一化模型输出的 dimension 字段）。 */
+/** 审稿维度取值：归一化模型输出的 dimension 字段。维度清单以 reviewSystemPrompt 的九条为准。 */
 const REVIEW_DIMENSION_IDS = /* @__PURE__ */ new Set([
 	"character",
 	"setting",
@@ -5150,6 +5376,35 @@ function createProject(outline, outlinePath) {
 		updatedAt: now
 	};
 }
+/**
+* 把已经拼好的请求过一遍模型参数能力层。
+*
+* **凡是自己构造 `GenerateOptions`、不走 {@link complete} 的调用点都必须经过它**，
+* 否则那条路径会绕过厂商参数约束（固定温度、不支持的 reasoning 等），对 Kimi
+* 这类模型直接报参数错误 —— 而"测试连通"恰恰是用户用来判断配置对不对的地方。
+*
+* 抽成函数而不是在每个调用点内联：流式调用点有 5 处，还要各自处理备用模型切换，
+* 内联五遍就是同一件事写五份，必然漂移。
+* @param base - 已拼好的请求（调用方已确定 temperature / reasoningEffort）。
+* @param model - **本次实际要调用的模型**（切换备用模型后必须重算，故在循环内调用）。
+* @param options - `structured` 表示严格结构化输出任务。
+* @returns 收敛后的请求（固定温度的模型会省略 temperature / 不支持的参数会被移除）。
+*/
+function applyModelCapability(base, model, options = {}) {
+	const converged = convergeRequestParams({
+		temperature: base.temperature ?? .7,
+		reasoningEffort: base.reasoningEffort === void 0 ? void 0 : String(base.reasoningEffort)
+	}, model, {
+		structured: options.structured === true,
+		omitFixedTemperature: true
+	});
+	return {
+		...base,
+		model,
+		...converged.temperature === void 0 ? { temperature: void 0 } : { temperature: converged.temperature },
+		...converged.reasoningEffort === void 0 ? { reasoningEffort: void 0 } : { reasoningEffort: ReasoningEffortId(converged.reasoningEffort) }
+	};
+}
 /** One complete non-streaming LLM call. */
 async function complete(ctx, config, options) {
 	const liveLabel = options.liveLabel ?? "LLM 调用";
@@ -5171,14 +5426,22 @@ async function complete(ctx, config, options) {
 			system: options.system,
 			user: options.user
 		});
+		const converged = convergeRequestParams({
+			temperature: options.temperature ?? .7,
+			reasoningEffort: options.reasoning ?? config.reasoningEffort ?? "off"
+		}, model, {
+			structured: options.structured === true,
+			omitFixedTemperature: true
+		});
+		if (converged.adjustments.length > 0) ctx.logger("novel-forge").info("模型参数收敛（%s @ %s）：%s", liveLabel, model, converged.adjustments.join("；"));
 		const request = {
 			provider: config.provider,
 			model,
 			messages,
 			system: options.system,
 			maxTokens: options.maxTokens ?? config.maxTokens,
-			temperature: options.temperature ?? .7,
-			reasoningEffort: ReasoningEffortId(options.reasoning ?? config.reasoningEffort ?? "off")
+			...converged.temperature === void 0 ? {} : { temperature: converged.temperature },
+			...converged.reasoningEffort === void 0 ? {} : { reasoningEffort: ReasoningEffortId(converged.reasoningEffort) }
 		};
 		const assembler = new BlockAssembler();
 		for await (const chunk of ctx.llm.stream(request)) {
@@ -5447,17 +5710,19 @@ function volumeSystemPrompt() {
 		"输出必须是合法 JSON 数组，不要输出任何其他文字：",
 		"[{\"no\": 1, \"title\": \"卷名\", \"summary\": \"卷定位与剧情重心\", \"chapterStart\": 1, \"chapterEnd\": 80}]",
 		"重要：所有字符串值内部不得包含换行符，JSON 必须在一段内完整结束。",
-		"重要：直接输出 JSON 结果本身，不要把思考过程或推理内容写在输出里。"
+		"重要：直接输出 JSON 结果本身，不要把思考过程或推理内容写在输出里。",
+		renderLengthContract([["卷名", STRUCTURED_FIELD_LIMITS.chapterTitle], ["每卷定位", STRUCTURED_FIELD_LIMITS.chapterSummary]])
 	].join("\n");
 }
 /** Plan volumes from an outline. */
 async function planVolumes(ctx, config, outline) {
 	const user = `请为下面这部小说划分卷：\n\n${outline}`;
+	const expectedVolumes = Math.min(24, Math.max(3, Math.round(outline.length / 1200)));
 	const parsed = parseJsonArray(await complete(ctx, config, {
 		system: volumeSystemPrompt(),
 		user,
 		temperature: .4,
-		maxTokens: Math.max(config.maxTokens, 12e3)
+		maxTokens: resolveOutputBudget("volume-strategy", { volumes: expectedVolumes })
 	}));
 	const volumes = [];
 	for (let i = 0; i < parsed.length; i++) {
@@ -5470,8 +5735,8 @@ async function planVolumes(ctx, config, outline) {
 		const end = typeof entry.chapterEnd === "number" ? entry.chapterEnd : void 0;
 		volumes.push({
 			no,
-			title: title.slice(0, 40),
-			summary: summary.slice(0, 300),
+			title: title.slice(0, STRUCTURED_FIELD_LIMITS.chapterTitle),
+			summary: summary.slice(0, STRUCTURED_FIELD_LIMITS.chapterSummary),
 			chapterStart: start ?? 1,
 			chapterEnd: end ?? 1
 		});
@@ -5691,7 +5956,7 @@ async function planChapters(ctx, config, project, chapterCount, volumeNo, output
 		system: planSystemPrompt(project.volumes) + (continuation ? "\n重要：本次是**续写规划**——已有章节的剧情不得重写或重复，新章节标题不得与已有章节标题相同，新章节的剧情必须从上一章结尾自然接续（人物状态、时间线、地点衔接一致）。" : ""),
 		user,
 		temperature: .7,
-		maxTokens: Math.max(config.maxTokens, 4e4),
+		maxTokens: resolveOutputBudget("chapter-list", { chapters: chapterCount }),
 		liveLabel: "章节规划"
 	}, (t) => parseJsonArray(t));
 	const chapters = [];
@@ -6179,7 +6444,8 @@ async function extractRoles(ctx, config, project) {
 		system,
 		user,
 		temperature: .3,
-		maxTokens: Math.max(config.maxTokens, 16e3),
+		maxTokens: resolveOutputBudget("character-cast", { characters: 20 }),
+		structured: true,
 		reasoning: config.analysisReasoning ?? "low"
 	});
 	let raw = parseJsonArray(text);
@@ -6190,7 +6456,8 @@ async function extractRoles(ctx, config, project) {
 			system: system + (raw.length === 0 ? "\n上一次输出为空或格式不正确。请直接输出 JSON 数组（即使只有一个角色也要输出），不要输出其他文字。" : tooFew ? "\n上一次输出角色过少（不足 6 个）。这是一部完整故事，请重新核对正文摘录：主角、主要反派、重要配角与所有有名有姓的角色都要收录（宁多勿漏），输出 8-20 个。" : "\n上一次输出中缺少主角（roleLabel 为 protagonist 的角色）。请重新输出完整 JSON 数组，务必包含正文中的主角。"),
 			user,
 			temperature: .3,
-			maxTokens: Math.max(config.maxTokens, 12e3),
+			maxTokens: resolveOutputBudget("character-cast", { characters: 24 }),
+			structured: true,
 			reasoning: config.analysisReasoning ?? "low"
 		});
 		raw = parseJsonArray(text);
@@ -6720,7 +6987,7 @@ function describeLlmTestError(err) {
 /** 对选中的提供商/模型发一次最小真实调用（maxTokens=16），验证 Key / 端点 / 模型可用。 */
 async function testLlmModel(ctx, provider, model) {
 	const start = Date.now();
-	const request = {
+	const request = applyModelCapability({
 		provider,
 		model,
 		messages: [createUserMessage({
@@ -6735,7 +7002,7 @@ async function testLlmModel(ctx, provider, model) {
 		})],
 		maxTokens: 16,
 		temperature: 0
-	};
+	}, model);
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), 3e4);
 	try {
@@ -7130,10 +7397,7 @@ async function* rewriteChapterStream(ctx, config, project, outputDir, chapterNo,
 		});
 		const assembler = new BlockAssembler();
 		let produced = 0;
-		for await (const chunk of ctx.llm.stream({
-			...request,
-			model
-		})) {
+		for await (const chunk of ctx.llm.stream(applyModelCapability(request, model))) {
 			assembler.push(chunk);
 			if (chunk.type === "text-delta") {
 				produced += chunk.text.length;
@@ -7242,10 +7506,7 @@ async function* polishChapterStream(ctx, config, project, outputDir, chapterNo)
 		});
 		const assembler = new BlockAssembler();
 		let produced = 0;
-		for await (const chunk of ctx.llm.stream({
-			...request,
-			model
-		})) {
+		for await (const chunk of ctx.llm.stream(applyModelCapability(request, model))) {
 			assembler.push(chunk);
 			if (chunk.type === "text-delta") {
 				produced += chunk.text.length;
@@ -7387,10 +7648,7 @@ async function* generateChapterStream(ctx, config, project, outputDir, chapterNo
 		});
 		const assembler = new BlockAssembler();
 		let produced = 0;
-		for await (const chunk of ctx.llm.stream({
-			...request,
-			model
-		})) {
+		for await (const chunk of ctx.llm.stream(applyModelCapability(request, model))) {
 			assembler.push(chunk);
 			if (chunk.type === "text-delta") {
 				produced += chunk.text.length;
@@ -8661,7 +8919,8 @@ async function runMarketRadar(ctx, config, req) {
 	};
 	return {
 		signals: signalAs(raw.signals),
-		productionFoundation
+		productionFoundation,
+		reportId: `mr-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
 	};
 }
 const MARKET_MODE_HINT = {
@@ -9138,14 +9397,45 @@ function exportScope(outputDir, project, scope, format) {
 	};
 }
 //#endregion
+//#region src/home.ts
+/**
+* DeepSeek Harness home resolution for this plugin.
+*
+* Precedence mirrors `resolveDshHome` from `@deepseek-ai/dsh-home-paths`:
+* `$DSH_HOME` when set and non-blank, else `~/.dsh`. That package's remaining
+* input — the harness's own explicit override — is not reachable from a
+* plugin, so this reproduces the part a plugin can observe instead of taking
+* a dependency whose published range tracks a different harness line.
+*
+* State files must resolve through here rather than `~/.dsh` directly: the
+* desktop build points `DSH_HOME` at its own root, and a hardcoded path made
+* both builds share one store and lose it whenever that directory was cleaned.
+*/
+/**
+* Absolute Harness home for this process.
+* @returns the normalized home directory.
+*/
+function dshHome() {
+	const configured = process.env.DSH_HOME?.trim();
+	return resolve(configured !== void 0 && configured.length > 0 ? configured : join(homedir(), ".dsh"));
+}
+/**
+* Join path segments onto the Harness home.
+* @param segments - path segments appended to the home.
+* @returns the normalized absolute joined path.
+*/
+function dshHomePath(...segments) {
+	return join(dshHome(), ...segments);
+}
+//#endregion
 //#region src/bookshelf.ts
 /**
 * 书架（Bookshelf）— 多书管理：一本书记录一个独立输出目录。
-* 状态持久化到 ~/.dsh/dsh-novel-forge-bookshelf.json（跟随 dsh 配置惯例）。
+* 状态持久化到 <DSH_HOME>/dsh-novel-forge-bookshelf.json（跟随 dsh 配置惯例）。
 */
 /** 书架配置文件路径。 */
 function bookshelfFile() {
-	return join(homedir(), ".dsh", "dsh-novel-forge-bookshelf.json");
+	return dshHomePath("dsh-novel-forge-bookshelf.json");
 }
 function defaultStore() {
 	return {
@@ -9174,7 +9464,7 @@ function loadBookshelf() {
 /** 持久化书架。 */
 function saveBookshelf(store) {
 	const file = bookshelfFile();
-	mkdirSync(join(homedir(), ".dsh"), { recursive: true });
+	mkdirSync(dshHome(), { recursive: true });
 	writeFileSync(file, JSON.stringify(store, null, 2), "utf8");
 }
 /** 当前激活的书。 */
@@ -9300,10 +9590,15 @@ function repointBookDirs(from, to) {
 	if (count > 0) saveBookshelf(store);
 	return count;
 }
-/** 默认输出目录推断：~/.dsh/novels/书名。 */
-function defaultOutputDirFor(bookName) {
+/**
+* 新书默认输出目录：`<配置的输出目录>/书名`；未配置时回退 `<DSH_HOME>/novels/书名`。
+* @param bookName - 书名（剔除文件系统非法字符并截断到 40 字）。
+* @param baseDir - settings 里配置的输出目录（未经激活书合并的原始值）。
+* @returns 该书应写入的绝对目录。
+*/
+function defaultOutputDirFor(bookName, baseDir) {
 	const clean = bookName.replace(/[\\/:*?"<>|]/g, "").trim().slice(0, 40) || "未命名小说";
-	return join(homedir(), ".dsh", "novels", clean);
+	return join(baseDir !== void 0 && baseDir.trim() !== "" ? baseDir.trim() : dshHomePath("novels"), clean);
 }
 const REVISION_SOURCE_LABELS = {
 	review: "审稿",
@@ -11279,13 +11574,13 @@ function removeDir(dir) {
 //#region src/author-assets.ts
 /**
 * 作者资产库/总数据（跨书）— 按作者维度聚合的可复用资产。
-* 与书架同惯例持久化到 ~/.dsh/dsh-novel-forge-author-assets.json。
+* 与书架同惯例持久化到 <DSH_HOME>/dsh-novel-forge-author-assets.json。
 * 提供读取/持久化/新增或更新/删除，以及「导入默认」：把书架书的写作资产/角色 + 
 * 内置全局库（题材/反AI规则/风格模板/推进模式）批量沉淀成资产条目（默认库）。
 */
 /** 作者资产库配置文件路径。 */
 function authorAssetsFile() {
-	return join(homedir(), ".dsh", "dsh-novel-forge-author-assets.json");
+	return dshHomePath("dsh-novel-forge-author-assets.json");
 }
 /** 默认空资产库。 */
 function defaultLibrary() {
@@ -11315,7 +11610,7 @@ function loadAuthorAssets() {
 /** 持久化作者资产库。 */
 function saveAuthorAssets(library) {
 	const file = authorAssetsFile();
-	mkdirSync(join(homedir(), ".dsh"), { recursive: true });
+	mkdirSync(dshHome(), { recursive: true });
 	writeFileSync(file, JSON.stringify(library, null, 2), "utf8");
 }
 /** 按 id 更新一条资产；不存在则追加。 */
@@ -11618,7 +11913,6 @@ async function collectMarketSource(source) {
 /**
 * 热门题材雷达：真实榜单扫榜（聚合各平台榜单源，容错）。
 */
-let lastScan = null;
 async function scanMarketRanking(platforms) {
 	const wanted = new Set(platforms?.length ? platforms : [
 		"fanqie",
@@ -11650,11 +11944,10 @@ async function scanMarketRanking(platforms) {
 			});
 		}
 	}));
-	lastScan = {
+	return {
 		scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		groups
 	};
-	return lastScan;
 }
 //#endregion
 //#region src/global-assets.ts
@@ -11662,7 +11955,7 @@ async function scanMarketRanking(platforms) {
 * 全局资源库（跨书可复用的自定义题材/推进模式）。
 * 雷达「同步底座到全局资源库」写入此处；/assets 返回时与内置库合并展示。
 */
-const FILE = join(homedir(), ".dsh", "novel-forge-global-assets.json");
+const FILE = dshHomePath("novel-forge-global-assets.json");
 let cache = null;
 function load() {
 	if (cache !== null) return cache;
@@ -11683,7 +11976,7 @@ function load() {
 }
 function persist() {
 	if (cache === null) return;
-	mkdirSync(join(homedir(), ".dsh"), { recursive: true });
+	mkdirSync(dshHome(), { recursive: true });
 	writeFileSync(FILE, JSON.stringify(cache, null, 2), "utf8");
 }
 function globalGenreLibrary() {
@@ -11778,12 +12071,29 @@ async function readJsonBody(req) {
 /** Default chapter count for planning when the request omits it. */
 const DEFAULT_PLAN_COUNT = 30;
 /**
+* The profile this host booted (`--profile <name>` on the dsh CLI invocation).
+* Profile-scoped paths must not assume a name: the shipped template is `web`,
+* but a custom profile (`web-alpha`) is the one actually running.
+* @returns the profile name, or undefined when the flag is absent.
+*/
+function argvProfile() {
+	const flag = process.argv.indexOf("--profile");
+	const value = flag === -1 ? void 0 : process.argv[flag + 1];
+	return value !== void 0 && !value.startsWith("-") ? value : void 0;
+}
+/**
 * Build every /api/dsh-novel-forge route.
 * @param deps - context, config resolver, config patcher.
 * @returns the route list.
 */
 function makeRoutes(deps) {
 	const { ctx, getConfig, patchConfig } = deps;
+	/**
+	* 新书默认目录的基准：settings 里配置的输出目录（未经激活书合并，激活书的
+	* outputDir 指向它自己，不能当作新书的父目录）。未配置时 `defaultOutputDirFor`
+	* 回退到 `<DSH_HOME>/novels`。
+	*/
+	const defaultBookDir = (bookName) => defaultOutputDirFor(bookName, deps.rawConfig?.().outputDir);
 	/** 全书质检实时状态（内存态，重启后回到 idle；用于 /status 暴露进度）。 */
 	let auditState = {
 		status: "idle",
@@ -13645,7 +13955,7 @@ function makeRoutes(deps) {
 					writeJson(res, 400, { error: "bookName 不能为空" });
 					return;
 				}
-				const outputDir = body?.outputDir?.trim() !== "" && body?.outputDir !== void 0 ? body.outputDir : defaultOutputDirFor(bookName);
+				const outputDir = body?.outputDir?.trim() !== "" && body?.outputDir !== void 0 ? body.outputDir : defaultBookDir(bookName);
 				const book = createBook(bookName, outputDir);
 				const outline = body?.outline?.trim();
 				if (outline !== void 0 && outline.length >= 50) {
@@ -13756,7 +14066,7 @@ function makeRoutes(deps) {
 			try {
 				if (body?.text !== void 0 && body.text.length > 0) {
 					const bookName = (body.fileName ?? "").replace(/\.[^.]+$/, "").trim().slice(0, 40) || "导入小说";
-					const outDir = body?.outputDir?.trim() !== void 0 && body.outputDir.trim() !== "" ? body.outputDir.trim() : defaultOutputDirFor(bookName);
+					const outDir = body?.outputDir?.trim() !== void 0 && body.outputDir.trim() !== "" ? body.outputDir.trim() : defaultBookDir(bookName);
 					const result = importBookTextFromText(body.text, outDir, bookName);
 					const { book } = importDir(outDir);
 					writeJson(res, 200, {
@@ -13775,7 +14085,7 @@ function makeRoutes(deps) {
 					return;
 				}
 				const bookName = basename(filePath, extname(filePath)).slice(0, 40) || "导入小说";
-				const outDir = body?.outputDir?.trim() !== void 0 && body.outputDir.trim() !== "" ? body.outputDir.trim() : defaultOutputDirFor(bookName);
+				const outDir = body?.outputDir?.trim() !== void 0 && body.outputDir.trim() !== "" ? body.outputDir.trim() : defaultBookDir(bookName);
 				const result = importBookText(filePath, outDir);
 				const { book } = importDir(outDir);
 				writeJson(res, 200, {
@@ -14446,7 +14756,7 @@ function makeRoutes(deps) {
 				return;
 			}
 			try {
-				writeJson(res, 200, { config: await patchConfig(body) });
+				writeJson(res, 200, await patchConfig(body));
 			} catch (error) {
 				writeJson(res, 400, { error: error.message });
 			}
@@ -14485,7 +14795,7 @@ function makeRoutes(deps) {
 		path: NOVEL_API.pluginUpdate,
 		handler: async (req, res) => {
 			if (!guard(req, res, "POST")) return;
-			const profileDir = join(homedir(), ".dsh", "profiles", "web");
+			const profileDir = dshHomePath("profiles", argvProfile() ?? "web");
 			writeJson(res, 200, await new Promise((resolve) => {
 				const child = spawn("pnpm", ["add", "@waterwx/dsh-novel-forge@latest"], {
 					cwd: profileDir,
@@ -15213,7 +15523,7 @@ function makeRoutes(deps) {
 			}
 		}
 	};
-	const THEME_BG_DIR = join(homedir(), ".dsh", "dsh-novel-forge-assets");
+	const THEME_BG_DIR = dshHomePath("dsh-novel-forge-assets");
 	const MIME_BY_EXT = {
 		png: "image/png",
 		jpg: "image/jpeg",
@@ -15369,15 +15679,83 @@ function makeRoutes(deps) {
 	];
 }
 //#endregion
-//#region src/index.ts
+//#region src/settings-persist.ts
+/**
+* The Loader entry id the settings section is addressed by.
+* @param ctx - plugin context (structurally typed: only `fiber.entry.options.id` is read).
+* @returns the entry id, or undefined when the host exposes none.
+*/
+function novelSettingsNamespace(ctx) {
+	const id = ctx?.fiber?.entry?.options?.id;
+	return typeof id === "string" && id.trim() !== "" ? id : void 0;
+}
+/**
+* Pick the settings section to write through.
+*
+* The entry id is authoritative; the declared legacy name is used only when the
+* host actually registered a section under it. Guessing an id is never allowed:
+* a write to a wrong section would persist another plugin's config.
+* @param settings - the settings service, when present.
+* @param entryNs - entry id resolved from the context, when available.
+* @param legacyNs - this plugin's declared section name (0.1.x wiring).
+* @returns the section id to write to, or undefined when none is addressable.
+*/
+function resolveSettingsTarget(settings, entryNs, legacyNs) {
+	const describe = settings?.describe;
+	if (settings?.update === void 0) return void 0;
+	if (describe === void 0) return entryNs;
+	try {
+		const names = (describe() ?? []).map((row) => row?.ns).filter((ns) => typeof ns === "string");
+		if (entryNs !== void 0 && names.includes(entryNs)) return entryNs;
+		return names.includes(legacyNs) ? legacyNs : void 0;
+	} catch {
+		return entryNs;
+	}
+}
 /**
-* dsh-novel-forge — host half. Mounts the AI novel-forge workbench: docx
-* outline import, LLM chapter planning, chapter-by-chapter generation
-* (3000-4000 chars each), Markdown output into your chosen folder, and the
-* /api/dsh-novel-forge route family. The browser half (./client) renders the
-* workbench panel. Everything rides official NPM SDK packages — no dsh source
-* changes.
+* Merge one patch into the live config and persist it when the host allows.
+*
+* Never throws for a persistence failure: the edit is valid and already applied,
+* so failing the request would lose it and misreport a working save as an error.
+* @param current - the config as currently resolved.
+* @param patch - the subset to merge (`undefined` values are ignored by callers).
+* @param settings - the settings service, when present.
+* @param entryNs - entry id resolved from the context, when available.
+* @param legacyNs - this plugin's declared section name.
+* @returns the merged config plus a warning when it could not be persisted.
 */
+async function persistConfigPatch(current, patch, settings, entryNs, legacyNs) {
+	const next = {
+		...current,
+		...patch
+	};
+	const target = resolveSettingsTarget(settings, entryNs, legacyNs);
+	if (settings?.update === void 0) return {
+		config: next,
+		settingsWarning: "宿主未提供 settings.update，配置只在本次进程内生效。"
+	};
+	if (target === void 0) {
+		let registered = "不可枚举";
+		try {
+			registered = (settings.describe?.() ?? []).map((row) => row?.ns).filter((ns) => typeof ns === "string").join("、") || "（空）";
+		} catch {}
+		return {
+			config: next,
+			settingsWarning: `宿主 settings 未登记本插件的配置段（entry id「${entryNs ?? "未知"}」，已登记的段：${registered}），配置只在本次进程内生效。`
+		};
+	}
+	try {
+		await settings.update(target, patch);
+		return { config: next };
+	} catch (error) {
+		return {
+			config: next,
+			settingsWarning: `写入宿主设置段「${target}」失败：${error instanceof Error ? error.message : String(error)}；配置只在本次进程内生效。`
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
 /** Stable cordis plugin name. */
 const name = "novel-forge";
 /** Services required before the novel-forge surfaces can mount. */
@@ -15389,49 +15767,85 @@ const inject = [
 ];
 /**
 * Settings namespace of the novel-forge capability — the section the web
-* settings surface edits. Spelled here rather than imported: the browser half
-* spells the same value and must not depend on a Host package.
+* settings surface edits.
+*
+* Legacy fallback only: from Harness 0.2 the Loader derives the section from this
+* plugin's exported `Config`, and addresses it by the **entry id** it assigned in
+* the active profile. That id is not guaranteed to be this name (bundle rows may
+* be given a generated id), so the live id is read from the context instead —
+* see {@link novelSettingsNamespace}. The constant stays for the browser half and
+* for installations whose entry id really is this spelling.
 */
 const NOVEL_SETTINGS_NAMESPACE = "dsh-novel-forge";
+/**
+* Mark a config field as live-editable.
+*
+* From Harness 0.2 the settings surface builds its editable form from this
+* plugin's exported `Config` and only exposes fields whose nearest ancestor
+* declares volatility (`SettingsForms.schema` + `volatileForm`). Without the
+* marker the host refuses a write with `Plugin entry "…" has no volatile
+* fields`, so the plugin's own 保存设置 route could never persist anything.
+*
+* The canonical form is schemastery's `.volatile()` builder, but that builder
+* ships only in the Harness fork (`@deepseek-ai/schemastery`); the npm
+* `schemastery` this package depends on exposes the same switch as metadata
+* (`extra('volatile', true)`), which is what the fork's builder sets anyway.
+* Prefer the builder when the loaded copy has it, fall back to the metadata so
+* the schema is correct on either copy.
+* @param schema - the field schema.
+* @returns the same field marked live-editable.
+*/
+function live(schema) {
+	const candidate = schema;
+	if (typeof candidate.volatile === "function") return candidate.volatile();
+	if (typeof candidate.extra === "function") return candidate.extra("volatile", true);
+	return schema;
+}
+/**
+* Plugin config schema.
+*
+* Every field is live-editable (see {@link live}): the plugin re-reads the
+* settings section on every request, so a change must apply without remounting.
+*/
 const Config = z.object({
-	announceToAgent: z.boolean().default(true),
-	enabled: z.boolean().default(true),
-	outlinePath: z.string().default(""),
-	outputDir: z.string().default(join(homedir(), ".dsh", "novels")),
-	provider: z.string().default("deepseek-official"),
-	model: z.string().default("deepseek-flash"),
-	generateModel: z.string().default(""),
-	reviewModel: z.string().default(""),
-	auditModel: z.string().default(""),
-	fallbackModel: z.string().default(""),
-	autoTimeline: z.boolean().default(true),
-	reasoningEffort: z.union([
+	announceToAgent: live(z.boolean().default(true)),
+	enabled: live(z.boolean().default(true)),
+	outlinePath: live(z.string().default("")),
+	outputDir: live(z.string().default(dshHomePath("novels"))),
+	provider: live(z.string().default("deepseek-official")),
+	model: live(z.string().default("deepseek-flash")),
+	generateModel: live(z.string().default("")),
+	reviewModel: live(z.string().default("")),
+	auditModel: live(z.string().default("")),
+	fallbackModel: live(z.string().default("")),
+	autoTimeline: live(z.boolean().default(true)),
+	reasoningEffort: live(z.union([
 		"off",
 		"low",
 		"high",
 		"max"
-	]).default("off"),
-	analysisReasoning: z.union([
+	]).default("off")),
+	analysisReasoning: live(z.union([
 		"off",
 		"low",
 		"high",
 		"max"
-	]).default("low"),
-	chapterChars: z.number().default(3500),
-	maxTokens: z.number().default(12e3),
-	reviewPassScore: z.number().default(70),
-	autoReview: z.boolean().default(true),
-	autoAuthorReview: z.boolean().default(true),
-	autoReviewAfterRevise: z.boolean().default(true),
-	themeBackground: z.string().default(""),
-	themeBackgroundBlur: z.number().default(0),
-	themeOpacity: z.number().default(100),
-	enableAdaptMode: z.boolean().default(true)
+	]).default("low")),
+	chapterChars: live(z.number().default(3500)),
+	maxTokens: live(z.number().default(12e3)),
+	reviewPassScore: live(z.number().default(70)),
+	autoReview: live(z.boolean().default(true)),
+	autoAuthorReview: live(z.boolean().default(true)),
+	autoReviewAfterRevise: live(z.boolean().default(true)),
+	themeBackground: live(z.string().default("")),
+	themeBackgroundBlur: live(z.number().default(0)),
+	themeOpacity: live(z.number().default(100)),
+	enableAdaptMode: live(z.boolean().default(true))
 });
 /** Schema defaults, re-read for hand-built test contexts. */
 const DEFAULT_ANNOUNCE = true;
 const DEFAULT_OUTLINE_PATH = "";
-const DEFAULT_OUTPUT_DIR = join(homedir(), ".dsh", "novels");
+const DEFAULT_OUTPUT_DIR = dshHomePath("novels");
 const DEFAULT_PROVIDER = "deepseek-official";
 const DEFAULT_MODEL = "deepseek-flash";
 const DEFAULT_REASONING_EFFORT = "off";
@@ -15447,7 +15861,7 @@ const DEFAULT_AUTO_REVIEW_AFTER_REVISE = true;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 160;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const NOVEL_GUIDANCE = "本机已安装 dsh-novel-forge 插件（AI 编译小说工作台）：侧边栏「小说工坊」入口。能力：读取 docx 大纲、粘贴大纲文本或把 txt 全本拆章导入；用 LLM 提炼道藏（人设/世界观/金手指规则/写作红线）与大世界（境界/区域/势力）；生成卷计划与结构化章节计划（本章目标/剧情要点/必达项/义务合约/章末钩子）；逐章生成 3000-4000 字正文并保存为 Markdown（默认输出到用户主目录 ~/.dsh/novels）；每章自动生成摘要与编年录事实、抽取故事时间线（故事内时间/地点/在场角色/事件）、自动 AI 审稿（人设/设定/红线/文笔/爽点/逻辑/反 AI/呈现/合规九维）与作者复盘；支持按审稿意见合并修订（审稿 high + 时间线矛盾 + 张力偏差合成一轮，每章最多两轮后转人工）、去 AI 味润色、章节历史版本回滚、暗线（伏笔）管理、剧情线与角色库、张力曲线、全书一致性质检与敏感词扫描、分范围导出与项目备份、批量连写（生产单，可暂停/续跑）。限制：所有 AI 操作消耗 LLM API 额度；输出目录与模型可在插件设置中修改；章节正文质量取决于大纲完整度；张力/时间线问题默认只是建议（写日志与待办），不会自动改正文。用户提到「小说 / 大纲 / 写小说 / 章节 / 审稿 / 润色」时即指本插件，请据此协作。";
+const NOVEL_GUIDANCE = "本机已安装 dsh-novel-forge 插件（AI 编译小说工作台）：侧边栏「小说工坊」入口。能力：读取 docx 大纲、粘贴大纲文本或把 txt 全本拆章导入；用 LLM 提炼道藏（人设/世界观/金手指规则/写作红线）与大世界（境界/区域/势力）；生成卷计划与结构化章节计划（本章目标/剧情要点/必达项/义务合约/章末钩子）；逐章生成 3000-4000 字正文并保存为 Markdown（默认输出到插件设置里「输出目录」指定的位置，未配置时落到 Harness 数据目录下的 novels/书名）；每章自动生成摘要与编年录事实、抽取故事时间线（故事内时间/地点/在场角色/事件）、自动 AI 审稿（人设/设定/红线/文笔/爽点/逻辑/反 AI/呈现/合规九维）与作者复盘；支持按审稿意见合并修订（审稿 high + 时间线矛盾 + 张力偏差合成一轮，每章最多两轮后转人工）、去 AI 味润色、章节历史版本回滚、暗线（伏笔）管理、剧情线与角色库、张力曲线、全书一致性质检与敏感词扫描、分范围导出与项目备份、批量连写（生产单，可暂停/续跑）。限制：所有 AI 操作消耗 LLM API 额度；输出目录与模型可在插件设置中修改；章节正文质量取决于大纲完整度；张力/时间线问题默认只是建议（写日志与待办），不会自动改正文。用户提到「小说 / 大纲 / 写小说 / 章节 / 审稿 / 润色」时即指本插件，请据此协作。";
 /** Resolve a config-like value into the full runtime config. */
 function resolveConfig(value) {
 	return {
@@ -15480,7 +15894,11 @@ function resolveConfig(value) {
 * @param config - resolved plugin config (schema defaults applied by the loader).
 */
 function apply(ctx, config) {
-	let current = () => config ?? {};
+	let currentState = config ?? {};
+	const current = () => currentState;
+	const setCurrent = (next) => {
+		currentState = next;
+	};
 	const resolve = () => {
 		const resolved = resolveConfig(current());
 		const shelfDir = activeBookOutputDir();
@@ -15503,6 +15921,23 @@ function apply(ctx, config) {
 		if (bs.autoReviewAfterRevise !== void 0) book.autoReviewAfterRevise = bs.autoReviewAfterRevise;
 		return book;
 	};
+	/**
+	* The settings section this instance is addressed by, resolved once at mount.
+	* Undefined when the host exposes neither an entry id nor a registered section,
+	* in which case config edits stay in memory (see {@link patchConfig}).
+	*/
+	const settingsNs = novelSettingsNamespace(ctx);
+	/**
+	* Persist one config patch.
+	*
+	* Applies to the live config either way. Persistence goes through the host
+	* settings section when that section is addressable; when it is not (unknown
+	* entry id, or the section never registered), the patch is kept in memory and
+	* the caller is told it will not survive a restart — a config save must never
+	* fail the request just because the host does not offer persistence.
+	* @param patch - the subset to merge.
+	* @returns the config the host will read next, plus a persistence caveat.
+	*/
 	const patchConfig = async (patch) => {
 		const next = {};
 		if (patch.outlinePath !== void 0) next.outlinePath = patch.outlinePath;
@@ -15527,12 +15962,13 @@ function apply(ctx, config) {
 		if (patch.themeOpacity !== void 0) next.themeOpacity = patch.themeOpacity;
 		if (patch.enableAdaptMode !== void 0) next.enableAdaptMode = patch.enableAdaptMode;
 		const settings = ctx.get("settings");
-		if (settings !== void 0) await settings.update(NOVEL_SETTINGS_NAMESPACE, next);
-		else current = () => ({
-			...current(),
-			...next
-		});
-		return resolve();
+		const persisted = await persistConfigPatch(current(), next, settings, settingsNs, NOVEL_SETTINGS_NAMESPACE);
+		setCurrent(persisted.config);
+		if (persisted.settingsWarning !== void 0) ctx.logger("novel-forge").warn("%s", persisted.settingsWarning);
+		return {
+			config: resolve(),
+			...persisted.settingsWarning === void 0 ? {} : { settingsWarning: persisted.settingsWarning }
+		};
 	};
 	let disposeSection;
 	let disposeRoutes;
@@ -15556,7 +15992,8 @@ function apply(ctx, config) {
 			ctx,
 			getConfig: resolve,
 			patchConfig,
-			rawConfig: () => current()
+			rawConfig: () => current(),
+			settingsNs
 		});
 		disposeRoutes = ctx.effect(() => {
 			const disposers = routes.map((route) => ctx.webServer.register(route));
@@ -15565,9 +16002,10 @@ function apply(ctx, config) {
 			};
 		}, "dsh-novel-forge: routes");
 	};
-	ctx.settings.installSection(ctx, NOVEL_SETTINGS_NAMESPACE, Config, config ?? {}, {
+	const settingsService = ctx.get("settings");
+	if (settingsService !== void 0 && typeof settingsService.installSection === "function") settingsService.installSection(ctx, settingsNs ?? "dsh-novel-forge", Config, config ?? {}, {
 		setSource: (source) => {
-			current = source;
+			setCurrent(source());
 			sync();
 		},
 		onChange: sync