@deepmaid/maid-setup 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenyonxu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @deepmaid/maid-setup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepMaid 首次迎接与设置服务(M3j)。职责:稳定 hostId、公共 Doris 模板目录(只读 `@deepmaid/maid-doris`)、可恢复的迎接/换模板事务(journal + 备份 + 崩溃回滚)、状态与预检。M3k 将在同一服务上扩展状态服务与 MSLM 向导。
+
+- 挂载:`maid-identity` 之后(inject);`agentPresets`/`maidComposer`/`llm` 经 reflect 软依赖。
+- apply 期零副作用(不创建 Doris、不改默认女仆、不开端口);创建期恢复未完成事务是唯一写操作。
+- 不静态 import `node:sqlite`——嵌入式状态不可用时排障面仍可用。
+- MIT;engines: dsh >=0.2.1-rc.2 <0.3。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: deepmaid-maid-setup
+      name: '@deepmaid/maid-setup'

package/lib/index.d.ts

@@ -0,0 +1,129 @@
+import { MaidIdentity, ManagedPaths, OnboardingStatus, PersonaTemplatePreview } from "@deepmaid/maid-identity";
+//#region src/types.d.ts
+/** host agent-preset-registry 只读鸭子面(缺席 → 状态 blocked)。 */
+interface AgentPresetsFace {
+  list(): Promise<ReadonlyArray<{
+    id: string;
+    name?: string;
+  }>>;
+  readonly defaultId: string;
+}
+/** createMaidSetupService 消费的最小 identity 面(真插件形态由宿主装配提供)。 */
+type SetupIdentityFace = Pick<MaidIdentity, 'get' | 'list' | 'reload'> & Partial<Pick<MaidIdentity, 'getDefaultMaid' | 'setDefaultMaid'>>;
+interface MaidSetupDeps {
+  identity: SetupIdentityFace;
+  paths: ManagedPaths;
+  agentPresets(): AgentPresetsFace | undefined;
+  composer?(): {
+    invalidate?(maidId: string): void;
+  } | undefined;
+  llm?(): unknown;
+  warn?(message: string): void;
+  /** 测试注入缝(照 distiller/judge 先例):maid commit 后、pack commit 前的崩溃窗口。 */
+  hooks?: {
+    afterMaidCommit?(): void;
+  };
+}
+type MaidSetupErrorCode = 'invalid-template' | 'invalid-operation' | 'conflict' | 'confirmation-required' | 'blocked' | 'operation-failed';
+declare class MaidSetupError extends Error {
+  readonly code: MaidSetupErrorCode;
+  constructor(code: MaidSetupErrorCode, message: string, options?: ErrorOptions);
+}
+interface MaidSetupService {
+  /** 稳定 hostId(首次生成后长期固定;规格 §9.2 落点 4)。 */
+  hostId(): string;
+  onboardingStatus(): Promise<OnboardingStatus>;
+  personaTemplates(): Promise<PersonaTemplatePreview[]>;
+  activateDoris(input: {
+    operationId: string;
+    templateId: string;
+  }): Promise<OnboardingStatus>;
+  changeDorisTemplate(input: {
+    operationId: string;
+    templateId: string;
+    confirmCustomized?: boolean;
+  }): Promise<OnboardingStatus>;
+}
+//#endregion
+//#region src/service.d.ts
+declare function createMaidSetupService(deps: MaidSetupDeps): MaidSetupService;
+//#endregion
+//#region src/host-identity.d.ts
+declare function ensureStableHostId(file: string): string;
+//#endregion
+//#region src/catalog.d.ts
+/**
+ * M3j 公共模板目录(规格 §6.1/§8):只读 @deepmaid/maid-doris 包内 catalog 与
+ * templates——离线、不外呼;id 白名单字符;root 必须落在包根内(防路径拼接逃逸)。
+ * 不静态 import 内容包(保持「maid-setup 不随内容包膨胀」的装配关系)。
+ */
+interface DorisCatalogEntry {
+  id: string;
+  version: number;
+  name: string;
+  tagline: string;
+  preview: Array<{
+    user: string;
+    assistant: string;
+  }>;
+  /** 相对包根的 root(templates/<id>/root)。 */
+  root: string;
+}
+declare function dorisCatalogRoot(): string;
+declare function readDorisCatalog(warn: (message: string) => void): DorisCatalogEntry[];
+declare function templateDirOf(entry: DorisCatalogEntry): string;
+//#endregion
+//#region src/template-hash.d.ts
+declare function hashManagedContent(maidDir: string, packDir: string): string;
+//#endregion
+//#region src/transactions.d.ts
+/**
+ * M3j 可恢复迎接/换模板事务(规格 §8.2):
+ * staging 物化 → 隔离校验(composer validate + 独立 loadRegistry)→ 备份(change)→
+ * maid rename → pack rename → identity.reload → 默认女仆(仅缺席时)→ completed;
+ * 每步先写 journal 再执行下一步,任何失败按 journal 逆回滚(删除 createdTargets、
+ * 恢复 backups、还原默认女仆),回滚失败保留现场并上抛。恢复入口在 service 创建期
+ * 扫描 .transactions:completed 清理、非 completed 回滚、坏 journal 清退。
+ */
+interface TransactionJournal {
+  operationId: string;
+  kind: 'activate' | 'change';
+  templateId: string;
+  phase: 'prepared' | 'maid-committed' | 'pack-committed' | 'default-committed' | 'completed';
+  createdTargets: string[];
+  backups: Array<{
+    target: string;
+    backup: string;
+  }>;
+  previousDefaultMaid?: string;
+  changedDefault: boolean;
+}
+interface TransactionPorts {
+  paths: ManagedPaths;
+  identity: SetupIdentityFace;
+  entry: DorisCatalogEntry;
+  warn(message: string): void;
+  hooks?: {
+    afterMaidCommit?(): void;
+  };
+}
+declare function runDorisTransaction(input: {
+  operationId: string;
+  kind: 'activate' | 'change';
+  entry: DorisCatalogEntry;
+}, ports: TransactionPorts): void;
+/** service 创建期恢复:completed → 清理;非 completed → 回滚;坏/残留 staging → 清退。 */
+declare function recoverDorisTransactions(paths: ManagedPaths, identity: SetupIdentityFace, warn: (message: string) => void): void;
+//#endregion
+//#region src/index.d.ts
+declare const name = "maid-setup";
+declare const inject: string[];
+/**
+ * 宿主接线(M3j 规格 §6.2):identity 必在(inject);agentPresets/maidComposer/llm 经
+ * reflect 免 inject 直读(缺席容忍——状态 blocked / composer 失效仅影响换模板后的
+ * 缓存失效)。apply 不创建 Doris、不改默认女仆、不开端口;创建期恢复未完成事务是
+ * 唯一写操作。
+ */
+declare function apply(ctx: any): void;
+//#endregion
+export { type AgentPresetsFace, type DorisCatalogEntry, type MaidSetupDeps, MaidSetupError, type MaidSetupErrorCode, type MaidSetupService, type SetupIdentityFace, type TransactionJournal, type TransactionPorts, apply, createMaidSetupService, dorisCatalogRoot, ensureStableHostId, hashManagedContent, inject, name, readDorisCatalog, recoverDorisTransactions, runDorisTransaction, templateDirOf };

package/lib/index.js

@@ -0,0 +1,507 @@
+import { createRequire } from "node:module";
+import { managedPathsOf } from "@deepmaid/maid-identity/managed-paths";
+import { accessSync, constants, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { parse, stringify } from "yaml";
+import { validateMaidDeclaration } from "@deepmaid/maid-composer";
+import { loadRegistry } from "@deepmaid/maid-identity/registry";
+//#region src/host-identity.ts
+/**
+* M3j 稳定 hostId(规格 §9.2 落点 4):$DSH_HOME/deepmaid/state/host.json 持有
+* {version:1, hostId:'host_<uuid>'};首次生成原子落盘(tmp+rename),此后任何重建
+* 都复用同一值——eventId 命名空间不漂移,M3k 连接包沿用。坏文件(解析失败/坏型)
+* → 重写新生成值(fail-forward:状态文件可重建,身份不可复用旧坏值)。
+*/
+const HOST_ID_RE = /^host_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function ensureStableHostId(file) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (parsed?.version === 1 && typeof parsed.hostId === "string" && HOST_ID_RE.test(parsed.hostId)) return parsed.hostId;
+	} catch {}
+	const hostId = `host_${randomUUID()}`;
+	mkdirSync(dirname(file), { recursive: true });
+	const temp = `${file}.${randomUUID()}.tmp`;
+	writeFileSync(temp, `${JSON.stringify({
+		version: 1,
+		hostId
+	}, null, 2)}\n`, "utf8");
+	renameSync(temp, file);
+	return hostId;
+}
+//#endregion
+//#region src/catalog.ts
+const REQUIRE = createRequire(import.meta.url);
+const PKG_ROOT = dirname(REQUIRE.resolve("@deepmaid/maid-doris/package.json"));
+const TEMPLATE_ID_RE = /^[a-z][a-z0-9-]*$/;
+function dorisCatalogRoot() {
+	return PKG_ROOT;
+}
+function isEntry(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const e = value;
+	return typeof e.id === "string" && TEMPLATE_ID_RE.test(e.id) && typeof e.version === "number" && Number.isInteger(e.version) && e.version >= 1 && typeof e.name === "string" && e.name.length > 0 && typeof e.tagline === "string" && Array.isArray(e.preview) && typeof e.root === "string" && !e.root.startsWith("/");
+}
+function readDorisCatalog(warn) {
+	const file = resolve(PKG_ROOT, "catalog.json");
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		throw new Error(`maid-setup: cannot read @deepmaid/maid-doris catalog (${error.message})`, { cause: error });
+	}
+	const templates = parsed?.templates;
+	if (!Array.isArray(templates)) throw new Error("maid-setup: maid-doris catalog.json 缺 templates 数组");
+	const entries = [];
+	for (const item of templates) {
+		if (!isEntry(item)) {
+			warn(`maid-setup: catalog 跳过坏条目 ${JSON.stringify(item)?.slice(0, 80)}`);
+			continue;
+		}
+		const dir = resolve(PKG_ROOT, item.root);
+		if (relative(PKG_ROOT, dir).startsWith("..")) throw new Error(`maid-setup: catalog 条目 '${item.id}' 的 root 越出包根`);
+		if (!existsSync(resolve(dir, "maids/doris/maid.yml"))) throw new Error(`maid-setup: 模板 '${item.id}' 缺 maids/doris/maid.yml`);
+		entries.push(item);
+	}
+	if (entries.length === 0) throw new Error("maid-setup: maid-doris catalog 为空");
+	return entries;
+}
+function templateDirOf(entry) {
+	return resolve(PKG_ROOT, entry.root);
+}
+function catalogEntryOf(id, warn) {
+	if (!TEMPLATE_ID_RE.test(id)) throw new Error(`maid-setup: 非法模板 id '${id}'`);
+	const entry = readDorisCatalog(warn).find((candidate) => candidate.id === id);
+	if (entry === void 0) throw new Error(`maid-setup: 模板 '${id}' 不在 catalog`);
+	return entry;
+}
+//#endregion
+//#region src/template-hash.ts
+/**
+* M3j 受管内容校验值(规格 §8.1/§8.3):只覆盖「换模板会触及的表达资产白名单」——
+* agent.cordis.yml、seeds/**、gestures.yml、当前 voice pack 的 pack.yml,加 maid.yml
+* 的 voice.pack/personaTemplate 投影(剔除 contentHash 自身)。数值配置(emotion/
+* calendar)与身份键不参与——换模板不动它们,hash 不因它们漂移。确定性:相对路径
+* 排序 + base64 内容 + 投影 JSON,同内容同 hash。
+*/
+function filesUnder(dir, base) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, {
+		recursive: true,
+		withFileTypes: true
+	}).filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name)).map((file) => relative(base, file)).sort();
+}
+function hashManagedContent(maidDir, packDir) {
+	const parts = [];
+	for (const rel of ["agent.cordis.yml", "gestures.yml"]) {
+		const file = join(maidDir, rel);
+		if (existsSync(file)) parts.push(`${rel}\0${readFileSync(file).toString("base64")}`);
+	}
+	for (const rel of filesUnder(join(maidDir, "seeds"), maidDir)) parts.push(`${rel}\0${readFileSync(join(maidDir, rel)).toString("base64")}`);
+	const packFile = join(packDir, "pack.yml");
+	if (existsSync(packFile)) parts.push(`packs/${relative(packDir, packFile)}\0${readFileSync(packFile).toString("base64")}`);
+	let projection = {};
+	try {
+		const maid = parse(readFileSync(join(maidDir, "maid.yml"), "utf8"));
+		const voice = maid?.voice;
+		const template = maid?.personaTemplate;
+		projection = {
+			...typeof voice?.pack === "string" ? { voicePack: voice.pack } : {},
+			...typeof template?.id === "string" && typeof template?.version === "number" ? {
+				templateId: template.id,
+				templateVersion: template.version
+			} : {}
+		};
+	} catch {}
+	parts.push(`maid.yml@projection\0${JSON.stringify(projection)}`);
+	const canonical = parts.join("\n");
+	return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+//#endregion
+//#region src/types.ts
+var MaidSetupError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+		this.name = "MaidSetupError";
+	}
+};
+//#endregion
+//#region src/transactions.ts
+const DORIS = "doris";
+function journalPath(txDir) {
+	return join(txDir, "journal.json");
+}
+function writeJournal(txDir, journal) {
+	writeFileSync(journalPath(txDir), `${JSON.stringify(journal, null, 2)}\n`, "utf8");
+}
+function rollback(journal, ports) {
+	for (const target of [...journal.createdTargets].reverse()) rmSync(target, {
+		recursive: true,
+		force: true
+	});
+	for (const { target, backup } of [...journal.backups].reverse()) if (existsSync(backup)) cpSync(backup, target, { recursive: true });
+	if (journal.changedDefault) ports.identity.setDefaultMaid?.(journal.previousDefaultMaid);
+	ports.identity.reload();
+}
+/** 隔离校验:composer 声明门槛 + 独立注册表装载(doris 可解析)。 */
+function validateStaged(maidDir, ports) {
+	validateMaidDeclaration(maidDir);
+	const registry = loadRegistry([join(maidDir, "..")], { warn: ports.warn });
+	try {
+		if (registry.get(DORIS) === void 0) throw new MaidSetupError("operation-failed", `maid-setup: staging 装载失败:'${DORIS}' 未注册`);
+	} finally {
+		registry.dispose();
+	}
+}
+/** maid.yml 元数据写回(两段式):先写 voice.pack/personaTemplate(id/version),再以
+* 此投影计算受管 hash 落 contentHash——一次写完会把旧投影烤进 hash(change 场景)。 */
+function stampMaidYml(maidDir, entry, packDir) {
+	const file = join(maidDir, "maid.yml");
+	const raw = parse(readFileSync(file, "utf8"));
+	raw.voice = {
+		...raw.voice ?? {},
+		pack: `doris-${entry.id}`
+	};
+	raw.personaTemplate = {
+		id: entry.id,
+		version: entry.version
+	};
+	writeFileSync(file, stringify(raw), "utf8");
+	const contentHash = hashManagedContent(maidDir, packDir);
+	raw.personaTemplate.contentHash = contentHash;
+	writeFileSync(file, stringify(raw), "utf8");
+}
+function runDorisTransaction(input, ports) {
+	const { paths, entry } = ports;
+	const templateMaidDir = join(templateDirOf(entry), "maids", DORIS);
+	const templatePackDir = join(templateDirOf(entry), "packs", `doris-${entry.id}`);
+	const managedMaidDir = join(paths.maids, DORIS);
+	const packTarget = join(paths.packs, "packs", `doris-${entry.id}`);
+	const change = input.kind === "change";
+	const txDir = join(paths.transactionsDir, input.operationId);
+	const staging = join(txDir, "staging");
+	mkdirSync(staging, { recursive: true });
+	const journal = {
+		operationId: input.operationId,
+		kind: input.kind,
+		templateId: entry.id,
+		phase: "prepared",
+		createdTargets: [],
+		backups: [],
+		changedDefault: false
+	};
+	let keepScene = false;
+	try {
+		const stagedMaid = join(staging, "maids", DORIS);
+		const stagedPack = join(staging, "packs", `doris-${entry.id}`);
+		mkdirSync(join(staging, "maids"), { recursive: true });
+		mkdirSync(join(staging, "packs"), { recursive: true });
+		cpSync(templateMaidDir, stagedMaid, { recursive: true });
+		cpSync(templatePackDir, stagedPack, { recursive: true });
+		if (change) {
+			for (const kept of ["emotion.yml", "calendar.yml"]) {
+				const from = join(managedMaidDir, kept);
+				if (existsSync(from)) cpSync(from, join(stagedMaid, kept));
+			}
+			const currentMaidYml = readFileSync(join(managedMaidDir, "maid.yml"), "utf8");
+			writeFileSync(join(stagedMaid, "maid.yml"), currentMaidYml);
+		}
+		stampMaidYml(stagedMaid, entry, stagedPack);
+		validateStaged(stagedMaid, ports);
+		writeJournal(txDir, journal);
+		if (change) {
+			const backupDir = join(paths.backupsDir, input.operationId);
+			mkdirSync(backupDir, { recursive: true });
+			const maidBackup = join(backupDir, "maids", DORIS);
+			mkdirSync(join(backupDir, "maids"), { recursive: true });
+			cpSync(managedMaidDir, maidBackup, { recursive: true });
+			journal.backups.push({
+				target: managedMaidDir,
+				backup: maidBackup
+			});
+			if (existsSync(packTarget)) {
+				const packBackup = join(backupDir, "packs", `doris-${entry.id}`);
+				mkdirSync(join(backupDir, "packs"), { recursive: true });
+				cpSync(packTarget, packBackup, { recursive: true });
+				journal.backups.push({
+					target: packTarget,
+					backup: packBackup
+				});
+			}
+			writeJournal(txDir, journal);
+		}
+		mkdirSync(paths.maids, { recursive: true });
+		mkdirSync(join(paths.packs, "packs"), { recursive: true });
+		rmSync(managedMaidDir, {
+			recursive: true,
+			force: true
+		});
+		renameSync(stagedMaid, managedMaidDir);
+		journal.createdTargets.push(managedMaidDir);
+		journal.phase = "maid-committed";
+		writeJournal(txDir, journal);
+		ports.hooks?.afterMaidCommit?.();
+		rmSync(packTarget, {
+			recursive: true,
+			force: true
+		});
+		renameSync(stagedPack, packTarget);
+		journal.createdTargets.push(packTarget);
+		journal.phase = "pack-committed";
+		writeJournal(txDir, journal);
+		ports.identity.reload();
+		if (ports.identity.get(DORIS) === void 0) throw new MaidSetupError("operation-failed", "maid-setup: 提交后 identity 回读失败");
+		if (ports.identity.getDefaultMaid?.() === void 0) {
+			ports.identity.setDefaultMaid?.(DORIS);
+			journal.changedDefault = true;
+			journal.phase = "default-committed";
+			writeJournal(txDir, journal);
+		}
+		journal.phase = "completed";
+		writeJournal(txDir, journal);
+	} catch (error) {
+		try {
+			rollback(journal, ports);
+			rmSync(txDir, {
+				recursive: true,
+				force: true
+			});
+		} catch (rollbackError) {
+			keepScene = true;
+			ports.warn(`maid-setup: 事务 ${input.operationId} 回滚失败(${rollbackError.message}),现场保留于 ${txDir}`);
+			throw new MaidSetupError("operation-failed", `maid-setup: 事务 ${input.operationId} 失败且回滚未完成(现场保留于 ${txDir})`, { cause: rollbackError });
+		}
+		throw error;
+	} finally {
+		if (!keepScene) rmSync(txDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** service 创建期恢复:completed → 清理;非 completed → 回滚;坏/残留 staging → 清退。 */
+function recoverDorisTransactions(paths, identity, warn) {
+	if (!existsSync(paths.transactionsDir)) return;
+	const ports = {
+		paths,
+		identity,
+		warn,
+		entry: void 0
+	};
+	for (const name of readdirSync(paths.transactionsDir)) {
+		const txDir = join(paths.transactionsDir, name);
+		let journal;
+		try {
+			journal = JSON.parse(readFileSync(journalPath(txDir), "utf8"));
+		} catch {}
+		try {
+			if (journal === void 0 || journal.phase === "completed") rmSync(txDir, {
+				recursive: true,
+				force: true
+			});
+			else {
+				rollback(journal, ports);
+				rmSync(txDir, {
+					recursive: true,
+					force: true
+				});
+			}
+		} catch (error) {
+			warn(`maid-setup: 事务 ${name} 恢复失败(${error.message}),现场保留于 ${txDir}`);
+		}
+	}
+}
+//#endregion
+//#region src/service.ts
+/**
+* M3j service 面(规格 §5.4/§8):状态识别由真实注册表+内容文件+预检推导;事务经
+* inFlight/completed 幂等(同 id 并发=同一 Promise,成功后重放=回读状态,失败
+* 不缓存可同 id 重试);同一时刻同一 Doris 的事务串行。恢复未完成事务是创建期的
+* 唯一写操作——apply 期不创建 Doris、不改默认女仆、不开端口(规格 §6.2)。
+*/
+const OPERATION_ID_RE = /^[A-Za-z0-9_-]{8,80}$/;
+function nodeSupported() {
+	const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+	return major === 22 && minor >= 19 || major >= 24;
+}
+function createMaidSetupService(deps) {
+	const warn = deps.warn ?? (() => {});
+	const hostId = ensureStableHostId(deps.paths.hostFile);
+	const recoveryBlockers = [];
+	recoverDorisTransactions(deps.paths, deps.identity, (message) => {
+		recoveryBlockers.push({
+			code: "recovery-failed",
+			detail: message
+		});
+		warn(message);
+	});
+	const managedMaidDir = join(deps.paths.maids, "doris");
+	const managedMaidFile = join(managedMaidDir, "maid.yml");
+	const packDirOf = (packId) => join(deps.paths.packs, "packs", packId);
+	const modelOf = () => deps.llm?.() !== void 0 ? {
+		state: "unknown",
+		detail: "DSH 已配置主对话模型(未验证连通)"
+	} : {
+		state: "missing",
+		detail: "尚未配置主对话模型——请先在 DSH 设置中配置"
+	};
+	async function blockersOf() {
+		const blockers = [...recoveryBlockers];
+		if (!nodeSupported()) blockers.push({
+			code: "node-version",
+			detail: `Node ${process.versions.node} 不满足(node:sqlite 需 ≥22.19 或 ≥24)`
+		});
+		try {
+			accessSync(deps.paths.maids, constants.W_OK);
+		} catch {
+			blockers.push({
+				code: "maids-not-writable",
+				detail: `托管目录不可写:${deps.paths.maids}`
+			});
+		}
+		const presets = deps.agentPresets();
+		if (presets === void 0) blockers.push({
+			code: "agent-presets-unavailable",
+			detail: "agentPresets 服务缺席(宿主未装载 preset 名册)"
+		});
+		else if (!(await presets.list()).some((preset) => preset.id === "standard")) blockers.push({
+			code: "standard-missing",
+			detail: "standard 基底不在 preset 名册(迎接需 standard 工作基底)"
+		});
+		return blockers;
+	}
+	async function statusOf() {
+		const defaultMaid = deps.identity.getDefaultMaid?.() ?? null;
+		const record = deps.identity.get("doris");
+		const model = modelOf();
+		if (record === void 0) return {
+			kind: "uninitialized",
+			maidId: null,
+			defaultMaid,
+			blockers: await blockersOf(),
+			model
+		};
+		const base = {
+			maidId: "doris",
+			defaultMaid,
+			blockers: await blockersOf(),
+			model
+		};
+		if (!existsSync(managedMaidFile)) return {
+			kind: "existing",
+			...base
+		};
+		const template = record.personaTemplate;
+		if (template === void 0) return {
+			kind: "existing",
+			...base
+		};
+		const packId = record.voice?.pack ?? `doris-${template.id}`;
+		return {
+			kind: hashManagedContent(managedMaidDir, packDirOf(packId)) === template.contentHash ? "ready" : "customized",
+			...base,
+			currentTemplate: template
+		};
+	}
+	let lane = Promise.resolve();
+	const inFlight = /* @__PURE__ */ new Map();
+	const completed = /* @__PURE__ */ new Map();
+	function requireOperationId(operationId) {
+		if (!OPERATION_ID_RE.test(operationId)) throw new MaidSetupError("invalid-operation", `maid-setup: 非法 operationId '${operationId}'(须 8-80 位 [A-Za-z0-9_-])`);
+	}
+	function runTransaction(input) {
+		const existing = completed.get(input.operationId);
+		if (existing !== void 0) return Promise.resolve(existing);
+		const pending = inFlight.get(input.operationId);
+		if (pending !== void 0) return pending;
+		const run = (async () => {
+			requireOperationId(input.operationId);
+			const status = await statusOf();
+			if (status.kind === "blocked") throw new MaidSetupError("blocked", `maid-setup: 当前部署阻塞(${status.blockers.map((b) => b.code).join(", ")})`);
+			if (input.kind === "activate") {
+				if (status.kind !== "uninitialized") throw new MaidSetupError("conflict", `maid-setup: Doris 已存在(${status.kind}),迎接仅适用于未初始化部署;更换请走 changeDorisTemplate`);
+			} else {
+				if (status.kind === "uninitialized" || status.kind === "existing") throw new MaidSetupError("conflict", `maid-setup: 无受管 Doris(${status.kind}),更换模板需要先完成迎接`);
+				if (status.kind === "customized" && input.confirmCustomized !== true) throw new MaidSetupError("confirmation-required", "maid-setup: 受管内容已被自定义,更换模板将覆盖表达资产——需显式确认(确认前自动备份)");
+			}
+			let entry;
+			try {
+				entry = catalogEntryOf(input.templateId, warn);
+			} catch (error) {
+				throw new MaidSetupError("invalid-template", error.message, { cause: error });
+			}
+			runDorisTransaction({
+				operationId: input.operationId,
+				kind: input.kind,
+				entry
+			}, {
+				paths: deps.paths,
+				identity: deps.identity,
+				entry,
+				warn,
+				...deps.hooks !== void 0 ? { hooks: deps.hooks } : {}
+			});
+			deps.composer?.()?.invalidate?.("doris");
+			const after = await statusOf();
+			completed.set(input.operationId, after);
+			return after;
+		})();
+		inFlight.set(input.operationId, run);
+		const enqueue = (promise) => {
+			lane = lane.then(() => promise.then(() => {}, () => {}));
+			return promise;
+		};
+		return enqueue(run.finally(() => {
+			inFlight.delete(input.operationId);
+		}));
+	}
+	return {
+		hostId: () => hostId,
+		onboardingStatus: statusOf,
+		personaTemplates: async () => readDorisCatalog(warn).map((entry) => ({
+			id: entry.id,
+			version: entry.version,
+			name: entry.name,
+			tagline: entry.tagline,
+			preview: entry.preview
+		})),
+		activateDoris: (input) => runTransaction({
+			...input,
+			kind: "activate"
+		}),
+		changeDorisTemplate: (input) => runTransaction({
+			...input,
+			kind: "change"
+		})
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "maid-setup";
+const inject = ["maidIdentity"];
+/**
+* 宿主接线(M3j 规格 §6.2):identity 必在(inject);agentPresets/maidComposer/llm 经
+* reflect 免 inject 直读(缺席容忍——状态 blocked / composer 失效仅影响换模板后的
+* 缓存失效)。apply 不创建 Doris、不改默认女仆、不开端口;创建期恢复未完成事务是
+* 唯一写操作。
+*/
+function apply(ctx) {
+	const logger = ctx.logger?.("maid-setup") ?? console;
+	const warn = (m) => logger.warn(m);
+	const service = createMaidSetupService({
+		identity: ctx.maidIdentity,
+		paths: managedPathsOf(ctx),
+		agentPresets: () => ctx.reflect?.get?.("agentPresets", false),
+		composer: () => ctx.reflect?.get?.("maidComposer", false),
+		llm: () => ctx.reflect?.get?.("llm", false),
+		warn
+	});
+	const dispose = ctx.provide("maidSetup", service);
+	ctx.effect(() => () => {
+		dispose();
+	}, "maid-setup: unload");
+}
+//#endregion
+export { MaidSetupError, apply, createMaidSetupService, dorisCatalogRoot, ensureStableHostId, hashManagedContent, inject, name, readDorisCatalog, recoverDorisTransactions, runDorisTransaction, templateDirOf };

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@deepmaid/maid-setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.2",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.2.1-rc.2 <0.3"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "meta": {
+      "title": "Maid Setup",
+      "description": "首次迎接与设置服务:稳定 hostId、公共 Doris 模板目录、可恢复迎接/换模板事务与状态预检。关闭=迎接向导与模板更换不可用,已物化女仆不受影响。"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "0.2.2-rc.1",
+    "yaml": "2.9.0",
+    "@deepmaid/maid-composer": "0.1.0-alpha.2",
+    "@deepmaid/maid-doris": "0.1.0-alpha.2",
+    "@deepmaid/maid-identity": "0.1.0-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }