dsh-sun-space 0.3.0 → 0.3.2

package/lib/index.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
@@ -20,43 +20,95 @@ var __exportAll = (all, no_symbols) => {
 *
 * 解析优先级（vaultPath() 每次调用重读，运行期变更即时生效）：
 *   ① 环境变量 SUN_VAULT（启动命令注入，随进程生效）
-*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写，持久化，不入库）
-*   ③ ~/.dsh/state/sun-space/state.json 的 vault 字段（Router 会话创建时插件自动登记 = 用户选定的工作区目录）
-*   ④ 会话工作目录（调用方从 exec 提取传入——用户在哪个工作区开会话，vault 就解析到哪）
-*   ⑤ 默认约定 ~/Workspace/sun-vault
+*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写/补建指令写入，持久化，不入库）
+*   ③ 会话工作目录（调用方从 exec 提取传入，须过 cwdHasSkeleton 门控——目录已含 90-Meta
+*      骨架才算；"空目录"不算：DSH 默认 boot 桶 default-workspace 全新时也是空的，无法与
+*      "用户新建目录当知识库"区分，空目录意图在会话创建时由 registerVaultRootFromSession 落到 ④）
+*   ④ state.json 的 workspaces 映射（分桶登记：workspaces[<会话/实例 cwd>] = vault。
+*      DSH 会话按实例 boot cwd 分桶，一桶一 vault——多实例并存互不污染：
+*      homevault 实例登记 homevault，主实例解析不受影响）
+*   ⑤ state.json 的 vault 字段（全局兜底；只承载 ①② 显式值的镜像，见 publishVaultState）
+*   ⑥ 默认约定 ~/Workspace/sun-vault（仅全新裸环境兜底）
 *
-* ③ 的设计动机：用户的 vault 就是他在 DSH 里选定的那个目录——Router 会话创建时
-* 插件自动把该会话 cwd 登记为 vault 根（registerVaultRootFromSession），无需任何
-* 手工配置。①② 供自定义/覆盖；⑤ 仅在全新裸环境兜底。
+* 无会话上下文的调用方（source/worker-watchdog）：用 vaultPathForHost()——以实例进程
+* cwd（= 本桶 boot 目录）查 ④ 映射，与本实例会话解析一致。
 *
-* 解析结果写回 state.json，作为浏览器端（孙学空间）的发现通道——浏览器经
-* workspaceFiles/read 以绝对路径读取该文件（工作区外绝对路径读取被宿主允许）。
+* publishVaultState 纪律（v0.3.2 根因修复）：落盘值仅限显式来源（①②⑤），⑥ 兜底值不写——
+* 落了会把默认路径固化成登记值，堵死 ③④ 级（v0.3.1 及之前每次插件启动即写入，新开工作区
+* 时"识别到的知识库"永远是 ~/Workspace/sun-vault 的幽灵）。
+*
+* registerVaultRootFromSession（首个 sun-router 会话创建时调用）：仅对 vault 候选目录
+* （空目录或已含 90-Meta）登记 workspaces[cwd]=cwd，不写全局 vault 字段——全局槽一旦
+* 写入首个工作区，会遮蔽其他实例/桶的解析（多 vault 场景交叉污染）。
 *
 * 目录约定沿用 DSH 官方先例：~/.dsh/state/<插件名>/（session-superagent 同款）。
-* 本文件不携带任何个人路径；个人 vault 位置只存在于①②③（均不入库）。
+* 本文件不携带任何个人路径；个人 vault 位置只存在于①②⑤（均不入库）。
 */
 const DEFAULT_VAULT_DIRNAME = "sun-vault";
 /** 插件自有状态目录（<DSH_HOME 或 ~/>/.dsh/state/sun-space/），沿用官方 state/<插件名> 约定。
 *  跟随 DSH_HOME：多实例（隔离 HOME 的测试环境）之间状态互不串扰。 */
 const stateDir = () => join(process.env.DSH_HOME ?? homedir(), ".dsh", "state", "sun-space");
-/** 纯函数：五级优先解析（测试与 vaultPath 共用）。 */
-function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir()) {
+function parseState(stateJson) {
+	try {
+		return JSON.parse(stateJson ?? "");
+	} catch {
+		return null;
+	}
+}
+/** 目录是否已含 vault 骨架（③ 级门控：已初始化的工作区目录就是 vault）。 */
+function cwdHasSkeleton(cwd) {
+	if (!cwd || !cwd.startsWith("/")) return false;
+	try {
+		return existsSync(join(cwd, "90-Meta"));
+	} catch {
+		return false;
+	}
+}
+/** 目录是否为 vault 候选（登记门控）：空目录（非隐藏项为 0，git init 过的也算）
+*  或已含 90-Meta 骨架。有内容而无骨架的目录（代码仓库根等）不是候选。 */
+function cwdIsVaultCandidate(cwd) {
+	if (!cwd || !cwd.startsWith("/")) return false;
+	try {
+		if (existsSync(join(cwd, "90-Meta"))) return true;
+		return readdirSync(cwd).every((name) => name.startsWith("."));
+	} catch {
+		return false;
+	}
+}
+/** 纯函数：六级优先解析（测试与 vaultPath 共用）。
+*  sessionCwd 须由调用方先过 cwdHasSkeleton 门控；bucketCwd 为分桶目录（④ 映射查询用，
+*  缺省同 sessionCwd）。 */
+function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir(), bucketCwd) {
 	if (envValue && envValue.trim() !== "") return envValue;
-	for (const raw of [configJson, stateJson]) try {
-		const parsed = JSON.parse(raw ?? "");
-		if (typeof parsed?.vault === "string" && parsed.vault.startsWith("/")) return parsed.vault;
+	try {
+		const cfg = JSON.parse(configJson ?? "");
+		if (typeof cfg?.vault === "string" && cfg.vault.startsWith("/")) return cfg.vault;
 	} catch {}
+	const state = parseState(stateJson);
 	if (sessionCwd && sessionCwd.startsWith("/")) return sessionCwd;
+	const bucket = bucketCwd ?? sessionCwd;
+	if (bucket && bucket.startsWith("/")) {
+		const mapped = state?.workspaces?.[bucket];
+		if (typeof mapped === "string" && mapped.startsWith("/")) return mapped;
+	}
+	if (typeof state?.vault === "string" && state.vault.startsWith("/")) return state.vault;
 	return join(home, "Workspace", DEFAULT_VAULT_DIRNAME);
 }
+/** ①②⑤ 显式来源（env/config/全局镜像）的取值；全空返回 undefined——
+*  ⑥ 兜底、③ 会话目录、④ 分桶映射都不算"显式"（publishVaultState 据此决定是否落盘）。 */
+function explicitVaultValue(envValue, configJson, stateJson) {
+	if (envValue && envValue.trim() !== "") return envValue;
+	for (const raw of [configJson, stateJson]) {
+		const parsed = parseState(raw);
+		if (parsed && typeof parsed.vault === "string" && parsed.vault.startsWith("/")) return parsed.vault;
+	}
+}
 let cached = {
 	at: 0,
 	key: "",
 	value: ""
 };
-/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
-*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——用户在哪个工作区开会话，vault 就解析到哪。 */
-function vaultPath(sessionCwd, now = Date.now()) {
+function resolve(sessionCwd, now) {
 	const dir = stateDir();
 	let configJson;
 	let stateJson;
@@ -66,9 +118,11 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	try {
 		stateJson = readFileSync(join(dir, "state.json"), "utf8");
 	} catch {}
-	const key = `${sessionCwd ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
+	const cwdSkeleton = cwdHasSkeleton(sessionCwd) ? sessionCwd : void 0;
+	const bucket = sessionCwd && sessionCwd.startsWith("/") ? sessionCwd : void 0;
+	const key = `${cwdSkeleton ?? ""}|${bucket ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
 	if (now - cached.at < 6e4 && cached.key === key) return cached.value;
-	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, sessionCwd);
+	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, cwdSkeleton, homedir(), bucket);
 	cached = {
 		at: now,
 		key,
@@ -76,26 +130,41 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	};
 	return value;
 }
+/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
+*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——本桶已初始化（含 90-Meta）
+*  或已在 workspaces 映射登记时，vault 就解析到哪。 */
+function vaultPath(sessionCwd, now = Date.now()) {
+	return resolve(sessionCwd, now);
+}
+/** 无会话上下文的调用方（source/watchdog 等）：以实例进程 cwd（= 本桶 boot 目录）解析，
+*  与本实例会话一致（④ 映射按桶命中）。 */
+function vaultPathForHost(now = Date.now()) {
+	return resolve(process.cwd(), now);
+}
 vaultPath();
 /**
 * Router 会话创建时登记 vault 根（"当前目录作为 vault"语义的落点）。
-* 仅在更高优先级来源（env/config/state）均未设置时才登记首个值——
-* 多 Router 并存或重复创建时第一个登记者生效。
-* 尽力而为：任何失败静默退场（最坏是回退到约定路径）。
+* 仅对候选目录（空目录或已含 90-Meta 骨架）登记 workspaces[cwd]=cwd——分桶登记，
+* 不写全局 vault 字段（防多实例交叉污染）；env 钉死时不登记（尊重显式覆盖）。
+* 同桶幂等；尽力而为：任何失败静默退场（最坏是回退到约定路径）。
 */
 function registerVaultRootFromSession(cwd, now = /* @__PURE__ */ new Date()) {
-	if (!cwd || !cwd.startsWith("/")) return false;
+	if (!cwdIsVaultCandidate(cwd)) return false;
 	if (process.env.SUN_VAULT?.trim()) return false;
 	try {
 		const dir = stateDir();
 		mkdirSync(dir, { recursive: true });
 		const p = join(dir, "state.json");
-		let state = {};
+		let raw;
 		try {
-			state = JSON.parse(readFileSync(p, "utf8"));
+			raw = readFileSync(p, "utf8");
 		} catch {}
-		if (state.vault && state.vault.startsWith("/")) return false;
-		state.vault = cwd;
+		const state = parseState(raw) ?? {};
+		if (state.workspaces?.[cwd]) return false;
+		state.workspaces = {
+			...state.workspaces ?? {},
+			[cwd]: cwd
+		};
 		state.updatedAt = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}T${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
 		writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
 		return true;
@@ -103,16 +172,25 @@ function registerVaultRootFromSession(cwd, now = /* @__PURE__ */ new Date()) {
 		return false;
 	}
 }
-/** 把解析结果写回状态目录的 state.json（apply 时调用，尽力而为），供客户端发现。 */
+/** 把显式解析结果写回状态目录的 state.json（apply 时调用，尽力而为），供客户端发现。
+*  纪律：仅显式来源（①env/②config/⑤全局镜像）才落盘；⑥ 兜底值不写——
+*  否则默认路径被固化成登记值，堵死 ③④ 级（v0.3.2 修复的根因）。
+*  workspaces 分桶映射由 registerVaultRootFromSession 维护，此处原样保留。 */
 function publishVaultState(now = /* @__PURE__ */ new Date()) {
 	try {
 		const dir = stateDir();
-		mkdirSync(dir, { recursive: true });
-		const p = join(dir, "state.json");
-		let state = {};
+		let configJson;
+		let stateJson;
 		try {
-			state = JSON.parse(readFileSync(p, "utf8"));
+			configJson = readFileSync(join(dir, "config.json"), "utf8");
 		} catch {}
+		try {
+			stateJson = readFileSync(join(dir, "state.json"), "utf8");
+		} catch {}
+		if (!explicitVaultValue(process.env.SUN_VAULT, configJson, stateJson)) return;
+		mkdirSync(dir, { recursive: true });
+		const p = join(dir, "state.json");
+		const state = parseState(stateJson) ?? {};
 		state.vault = vaultPath(void 0, now.getTime());
 		state.updatedAt = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}T${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
 		writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
@@ -236,8 +314,8 @@ var source_exports = /* @__PURE__ */ __exportAll({
 const inject$2 = ["timer"];
 /** 轮询周期（毫秒）：纯程序层，可调密。 */
 const POLL_MS = 18e5;
-const triggerDir$1 = () => `${vaultPath()}/90-Meta/triggers`;
-const snapshotFile = () => `${vaultPath()}/90-Meta/mock-data/last-snapshot.json`;
+const triggerDir$1 = () => `${vaultPathForHost()}/90-Meta/triggers`;
+const snapshotFile = () => `${vaultPathForHost()}/90-Meta/mock-data/last-snapshot.json`;
 /** trigger 文件 TTL：超过即视为已消费/过期，轮询成功路径顺带清理。 */
 const TRIGGER_TTL_MS = 6048e5;
 const CREDENTIAL_ALERT_COOLDOWN_MS = 36e5;
@@ -389,7 +467,7 @@ var worker_watchdog_exports = /* @__PURE__ */ __exportAll({
 });
 const name$1 = "worker-watchdog";
 const inject$1 = ["timer"];
-const triggerDir = () => `${vaultPath()}/90-Meta/triggers`;
+const triggerDir = () => `${vaultPathForHost()}/90-Meta/triggers`;
 /** 默认停滞阈值 15 分钟：长思考/长命令完成后即重置计时，真卡死撑不到这么久。 */
 const DEFAULT_STALL_MS = 9e5;
 /** 巡检间隔 30 秒。 */

package/lib/router-tools.mjs

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
 import { execFile } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 // src/vault.ts
 /**
@@ -191,33 +191,78 @@ async function dingSelf(userId, content, type = "app") {
 *
 * 解析优先级（vaultPath() 每次调用重读，运行期变更即时生效）：
 *   ① 环境变量 SUN_VAULT（启动命令注入，随进程生效）
-*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写，持久化，不入库）
-*   ③ ~/.dsh/state/sun-space/state.json 的 vault 字段（Router 会话创建时插件自动登记 = 用户选定的工作区目录）
-*   ④ 会话工作目录（调用方从 exec 提取传入——用户在哪个工作区开会话，vault 就解析到哪）
-*   ⑤ 默认约定 ~/Workspace/sun-vault
+*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写/补建指令写入，持久化，不入库）
+*   ③ 会话工作目录（调用方从 exec 提取传入，须过 cwdHasSkeleton 门控——目录已含 90-Meta
+*      骨架才算；"空目录"不算：DSH 默认 boot 桶 default-workspace 全新时也是空的，无法与
+*      "用户新建目录当知识库"区分，空目录意图在会话创建时由 registerVaultRootFromSession 落到 ④）
+*   ④ state.json 的 workspaces 映射（分桶登记：workspaces[<会话/实例 cwd>] = vault。
+*      DSH 会话按实例 boot cwd 分桶，一桶一 vault——多实例并存互不污染：
+*      homevault 实例登记 homevault，主实例解析不受影响）
+*   ⑤ state.json 的 vault 字段（全局兜底；只承载 ①② 显式值的镜像，见 publishVaultState）
+*   ⑥ 默认约定 ~/Workspace/sun-vault（仅全新裸环境兜底）
 *
-* ③ 的设计动机：用户的 vault 就是他在 DSH 里选定的那个目录——Router 会话创建时
-* 插件自动把该会话 cwd 登记为 vault 根（registerVaultRootFromSession），无需任何
-* 手工配置。①② 供自定义/覆盖；⑤ 仅在全新裸环境兜底。
+* 无会话上下文的调用方（source/worker-watchdog）：用 vaultPathForHost()——以实例进程
+* cwd（= 本桶 boot 目录）查 ④ 映射，与本实例会话解析一致。
 *
-* 解析结果写回 state.json，作为浏览器端（孙学空间）的发现通道——浏览器经
-* workspaceFiles/read 以绝对路径读取该文件（工作区外绝对路径读取被宿主允许）。
+* publishVaultState 纪律（v0.3.2 根因修复）：落盘值仅限显式来源（①②⑤），⑥ 兜底值不写——
+* 落了会把默认路径固化成登记值，堵死 ③④ 级（v0.3.1 及之前每次插件启动即写入，新开工作区
+* 时"识别到的知识库"永远是 ~/Workspace/sun-vault 的幽灵）。
+*
+* registerVaultRootFromSession（首个 sun-router 会话创建时调用）：仅对 vault 候选目录
+* （空目录或已含 90-Meta）登记 workspaces[cwd]=cwd，不写全局 vault 字段——全局槽一旦
+* 写入首个工作区，会遮蔽其他实例/桶的解析（多 vault 场景交叉污染）。
 *
 * 目录约定沿用 DSH 官方先例：~/.dsh/state/<插件名>/（session-superagent 同款）。
-* 本文件不携带任何个人路径；个人 vault 位置只存在于①②③（均不入库）。
+* 本文件不携带任何个人路径；个人 vault 位置只存在于①②⑤（均不入库）。
 */
 const DEFAULT_VAULT_DIRNAME = "sun-vault";
 /** 插件自有状态目录（<DSH_HOME 或 ~/>/.dsh/state/sun-space/），沿用官方 state/<插件名> 约定。
 *  跟随 DSH_HOME：多实例（隔离 HOME 的测试环境）之间状态互不串扰。 */
 const stateDir = () => join(process.env.DSH_HOME ?? homedir(), ".dsh", "state", "sun-space");
-/** 纯函数：五级优先解析（测试与 vaultPath 共用）。 */
-function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir()) {
+function parseState(stateJson) {
+	try {
+		return JSON.parse(stateJson ?? "");
+	} catch {
+		return null;
+	}
+}
+/** 目录是否已含 vault 骨架（③ 级门控：已初始化的工作区目录就是 vault）。 */
+function cwdHasSkeleton(cwd) {
+	if (!cwd || !cwd.startsWith("/")) return false;
+	try {
+		return existsSync(join(cwd, "90-Meta"));
+	} catch {
+		return false;
+	}
+}
+/** 目录是否为 vault 候选（登记门控）：空目录（非隐藏项为 0，git init 过的也算）
+*  或已含 90-Meta 骨架。有内容而无骨架的目录（代码仓库根等）不是候选。 */
+function cwdIsVaultCandidate(cwd) {
+	if (!cwd || !cwd.startsWith("/")) return false;
+	try {
+		if (existsSync(join(cwd, "90-Meta"))) return true;
+		return readdirSync(cwd).every((name) => name.startsWith("."));
+	} catch {
+		return false;
+	}
+}
+/** 纯函数：六级优先解析（测试与 vaultPath 共用）。
+*  sessionCwd 须由调用方先过 cwdHasSkeleton 门控；bucketCwd 为分桶目录（④ 映射查询用，
+*  缺省同 sessionCwd）。 */
+function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir(), bucketCwd) {
 	if (envValue && envValue.trim() !== "") return envValue;
-	for (const raw of [configJson, stateJson]) try {
-		const parsed = JSON.parse(raw ?? "");
-		if (typeof parsed?.vault === "string" && parsed.vault.startsWith("/")) return parsed.vault;
+	try {
+		const cfg = JSON.parse(configJson ?? "");
+		if (typeof cfg?.vault === "string" && cfg.vault.startsWith("/")) return cfg.vault;
 	} catch {}
+	const state = parseState(stateJson);
 	if (sessionCwd && sessionCwd.startsWith("/")) return sessionCwd;
+	const bucket = bucketCwd ?? sessionCwd;
+	if (bucket && bucket.startsWith("/")) {
+		const mapped = state?.workspaces?.[bucket];
+		if (typeof mapped === "string" && mapped.startsWith("/")) return mapped;
+	}
+	if (typeof state?.vault === "string" && state.vault.startsWith("/")) return state.vault;
 	return join(home, "Workspace", DEFAULT_VAULT_DIRNAME);
 }
 let cached = {
@@ -225,9 +270,7 @@ let cached = {
 	key: "",
 	value: ""
 };
-/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
-*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——用户在哪个工作区开会话，vault 就解析到哪。 */
-function vaultPath(sessionCwd, now = Date.now()) {
+function resolve$1(sessionCwd, now) {
 	const dir = stateDir();
 	let configJson;
 	let stateJson;
@@ -237,9 +280,11 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	try {
 		stateJson = readFileSync(join(dir, "state.json"), "utf8");
 	} catch {}
-	const key = `${sessionCwd ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
+	const cwdSkeleton = cwdHasSkeleton(sessionCwd) ? sessionCwd : void 0;
+	const bucket = sessionCwd && sessionCwd.startsWith("/") ? sessionCwd : void 0;
+	const key = `${cwdSkeleton ?? ""}|${bucket ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
 	if (now - cached.at < 6e4 && cached.key === key) return cached.value;
-	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, sessionCwd);
+	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, cwdSkeleton, homedir(), bucket);
 	cached = {
 		at: now,
 		key,
@@ -247,7 +292,61 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	};
 	return value;
 }
+/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
+*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——本桶已初始化（含 90-Meta）
+*  或已在 workspaces 映射登记时，vault 就解析到哪。 */
+function vaultPath(sessionCwd, now = Date.now()) {
+	return resolve$1(sessionCwd, now);
+}
 vaultPath();
+/** 状态目录诊断快照（sun_state_read 用）：config/state 解析值 + 调用方视角的实际解析结果。
+*  "登记了什么 vs 实际生效什么"一眼可比（晨报自检/vault 解析诊断）。只读，不触发写回。 */
+function readStateSnapshot(sessionCwd, now = Date.now()) {
+	const dir = stateDir();
+	let config = null;
+	let state = null;
+	try {
+		config = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+	} catch {}
+	try {
+		state = JSON.parse(readFileSync(join(dir, "state.json"), "utf8"));
+	} catch {}
+	return {
+		config,
+		state,
+		resolvedVault: vaultPath(sessionCwd, now)
+	};
+}
+/**
+* Router 会话创建时登记 vault 根（"当前目录作为 vault"语义的落点）。
+* 仅对候选目录（空目录或已含 90-Meta 骨架）登记 workspaces[cwd]=cwd——分桶登记，
+* 不写全局 vault 字段（防多实例交叉污染）；env 钉死时不登记（尊重显式覆盖）。
+* 同桶幂等；尽力而为：任何失败静默退场（最坏是回退到约定路径）。
+*/
+function registerVaultRootFromSession(cwd, now = /* @__PURE__ */ new Date()) {
+	if (!cwdIsVaultCandidate(cwd)) return false;
+	if (process.env.SUN_VAULT?.trim()) return false;
+	try {
+		const dir = stateDir();
+		mkdirSync(dir, { recursive: true });
+		const p = join(dir, "state.json");
+		let raw;
+		try {
+			raw = readFileSync(p, "utf8");
+		} catch {}
+		const state = parseState(raw) ?? {};
+		if (state.workspaces?.[cwd]) return false;
+		state.workspaces = {
+			...state.workspaces ?? {},
+			[cwd]: cwd
+		};
+		state.updatedAt = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}T${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
+		writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
+		return true;
+	} catch {
+		return false;
+	}
+}
 // src/router-tools.ts
 const inject = ["tools", "subagents"];
 /** 从工具执行上下文提取会话工作目录（用户在哪个工作区开会话，vault 就解析到哪）。防御式：形状未知时返回 undefined。 */
@@ -459,7 +558,8 @@ function apply(ctx) {
 		required: ["path", "content"]
 	}, async (args, exec) => {
 		try {
-			const p = resolveSafe(vaultPath(sessionCwdOf(exec)), args.path);
+			const root = vaultPath(sessionCwdOf(exec));
+			const p = resolveSafe(root, args.path);
 			await mkdir(join(p, ".."), { recursive: true });
 			if (args.mode === "append") await appendFile(p, args.content, "utf8");
 			else await writeFile(p, args.content, "utf8");
@@ -467,6 +567,7 @@ function apply(ctx) {
 				ok: true,
 				data: {
 					path: args.path,
+					vault: root,
 					bytes: Buffer.byteLength(args.content)
 				}
 			};
@@ -576,6 +677,66 @@ function apply(ctx) {
 			};
 		}
 	}));
+	ctx.tools.register(def("sun_state_read", "读取插件状态目录（~/.dsh/state/sun-space/）的登记与解析视图：config（用户手写 vault 覆盖）、state（workspaces 分桶登记 + 全局 vault 镜像）、resolvedVault（本会话实际生效的知识库根）。vault 解析诊断 / 晨报自检\"登记 vs 生效\"比对用。", {
+		type: "object",
+		properties: {}
+	}, async (_args, exec) => {
+		try {
+			return {
+				ok: true,
+				data: readStateSnapshot(sessionCwdOf(exec))
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				note: String(e.message).slice(0, 200)
+			};
+		}
+	}));
+	ctx.tools.register(def("sun_state_write", "把当前会话工作目录登记为本工作区的 vault 根（state.json 的 workspaces 分桶映射——一桶一 vault，不影响其他工作区/实例；仅空目录或已含 90-Meta 骨架的目录可登记）。零审批。用于：插件升级前创建的旧会话迁移、登记缺失自愈。值由系统从会话上下文派生，只接受 vault:true，不接受路径参数。", {
+		type: "object",
+		properties: { vault: {
+			type: "boolean",
+			description: "登记本会话工作目录为 vault 根（唯一合法值 true）"
+		} },
+		required: ["vault"]
+	}, async (args, exec) => {
+		if (args.vault !== true) return {
+			ok: false,
+			note: "仅接受 vault:true——登记值由系统从会话上下文派生，不接受手工传路径"
+		};
+		const cwd = sessionCwdOf(exec);
+		if (!cwd) return {
+			ok: false,
+			note: "无法从会话上下文提取工作目录（绝对路径）"
+		};
+		if (process.env.SUN_VAULT?.trim()) return {
+			ok: false,
+			note: `SUN_VAULT 已显式钉死（${process.env.SUN_VAULT}），不登记——尊重显式覆盖`
+		};
+		if (!cwdIsVaultCandidate(cwd)) return {
+			ok: false,
+			note: `${cwd} 不是 vault 候选（须为空目录或已含 90-Meta 骨架）——有内容而无骨架的工作区目录不登记`
+		};
+		try {
+			const changed = registerVaultRootFromSession(cwd);
+			const snap = readStateSnapshot(cwd);
+			return {
+				ok: true,
+				data: {
+					bucket: cwd,
+					registered: snap.state?.workspaces?.[cwd] ?? null,
+					changed,
+					resolvedVault: snap.resolvedVault
+				}
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				note: String(e.message).slice(0, 200)
+			};
+		}
+	}));
 	ctx.tools.register(def("sun_route", "创建子 Worker 会话并分派任务（task_id + prompt，可选 cwd）。子会话以 task_id 命名、其会话 id 自动回写任务笔记 session 字段（工作台卡片可直达）。cwd 用于跨目录任务（如代码开发，传仓库根的绝对路径）——沙箱可写区自动跟随会话 cwd；产物落库仍走 sun_artifact_write（vault 绝对路径，不受 cwd 影响）。name 冲突时自动改用系统命名。", {
 		type: "object",
 		properties: {
@@ -639,6 +800,6 @@ function apply(ctx) {
 			child_id: activation.childId ?? null
 		};
 	}));
-	ctx.logger?.info?.("[sun-space] router tools registered: sun_read sun_vault_write sun_vault_meta sun_notify sun_route(subagents)");
+	ctx.logger?.info?.("[sun-space] router tools registered: sun_read sun_vault_write sun_vault_meta sun_notify sun_state_read sun_state_write sun_route(subagents)");
 }
 export { apply, inject, lossless };

package/lib/worker-vault.mjs

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 // src/vault.ts
 /**
@@ -34,33 +34,67 @@ function resolveSafe(vaultRoot, rel) {
 *
 * 解析优先级（vaultPath() 每次调用重读，运行期变更即时生效）：
 *   ① 环境变量 SUN_VAULT（启动命令注入，随进程生效）
-*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写，持久化，不入库）
-*   ③ ~/.dsh/state/sun-space/state.json 的 vault 字段（Router 会话创建时插件自动登记 = 用户选定的工作区目录）
-*   ④ 会话工作目录（调用方从 exec 提取传入——用户在哪个工作区开会话，vault 就解析到哪）
-*   ⑤ 默认约定 ~/Workspace/sun-vault
+*   ② ~/.dsh/state/sun-space/config.json 的 vault 字段（用户手写/补建指令写入，持久化，不入库）
+*   ③ 会话工作目录（调用方从 exec 提取传入，须过 cwdHasSkeleton 门控——目录已含 90-Meta
+*      骨架才算；"空目录"不算：DSH 默认 boot 桶 default-workspace 全新时也是空的，无法与
+*      "用户新建目录当知识库"区分，空目录意图在会话创建时由 registerVaultRootFromSession 落到 ④）
+*   ④ state.json 的 workspaces 映射（分桶登记：workspaces[<会话/实例 cwd>] = vault。
+*      DSH 会话按实例 boot cwd 分桶，一桶一 vault——多实例并存互不污染：
+*      homevault 实例登记 homevault，主实例解析不受影响）
+*   ⑤ state.json 的 vault 字段（全局兜底；只承载 ①② 显式值的镜像，见 publishVaultState）
+*   ⑥ 默认约定 ~/Workspace/sun-vault（仅全新裸环境兜底）
 *
-* ③ 的设计动机：用户的 vault 就是他在 DSH 里选定的那个目录——Router 会话创建时
-* 插件自动把该会话 cwd 登记为 vault 根（registerVaultRootFromSession），无需任何
-* 手工配置。①② 供自定义/覆盖；⑤ 仅在全新裸环境兜底。
+* 无会话上下文的调用方（source/worker-watchdog）：用 vaultPathForHost()——以实例进程
+* cwd（= 本桶 boot 目录）查 ④ 映射，与本实例会话解析一致。
 *
-* 解析结果写回 state.json，作为浏览器端（孙学空间）的发现通道——浏览器经
-* workspaceFiles/read 以绝对路径读取该文件（工作区外绝对路径读取被宿主允许）。
+* publishVaultState 纪律（v0.3.2 根因修复）：落盘值仅限显式来源（①②⑤），⑥ 兜底值不写——
+* 落了会把默认路径固化成登记值，堵死 ③④ 级（v0.3.1 及之前每次插件启动即写入，新开工作区
+* 时"识别到的知识库"永远是 ~/Workspace/sun-vault 的幽灵）。
+*
+* registerVaultRootFromSession（首个 sun-router 会话创建时调用）：仅对 vault 候选目录
+* （空目录或已含 90-Meta）登记 workspaces[cwd]=cwd，不写全局 vault 字段——全局槽一旦
+* 写入首个工作区，会遮蔽其他实例/桶的解析（多 vault 场景交叉污染）。
 *
 * 目录约定沿用 DSH 官方先例：~/.dsh/state/<插件名>/（session-superagent 同款）。
-* 本文件不携带任何个人路径；个人 vault 位置只存在于①②③（均不入库）。
+* 本文件不携带任何个人路径；个人 vault 位置只存在于①②⑤（均不入库）。
 */
 const DEFAULT_VAULT_DIRNAME = "sun-vault";
 /** 插件自有状态目录（<DSH_HOME 或 ~/>/.dsh/state/sun-space/），沿用官方 state/<插件名> 约定。
 *  跟随 DSH_HOME：多实例（隔离 HOME 的测试环境）之间状态互不串扰。 */
 const stateDir = () => join(process.env.DSH_HOME ?? homedir(), ".dsh", "state", "sun-space");
-/** 纯函数：五级优先解析（测试与 vaultPath 共用）。 */
-function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir()) {
+function parseState(stateJson) {
+	try {
+		return JSON.parse(stateJson ?? "");
+	} catch {
+		return null;
+	}
+}
+/** 目录是否已含 vault 骨架（③ 级门控：已初始化的工作区目录就是 vault）。 */
+function cwdHasSkeleton(cwd) {
+	if (!cwd || !cwd.startsWith("/")) return false;
+	try {
+		return existsSync(join(cwd, "90-Meta"));
+	} catch {
+		return false;
+	}
+}
+/** 纯函数：六级优先解析（测试与 vaultPath 共用）。
+*  sessionCwd 须由调用方先过 cwdHasSkeleton 门控；bucketCwd 为分桶目录（④ 映射查询用，
+*  缺省同 sessionCwd）。 */
+function computeVaultPath(envValue, configJson, stateJson, sessionCwd, home = homedir(), bucketCwd) {
 	if (envValue && envValue.trim() !== "") return envValue;
-	for (const raw of [configJson, stateJson]) try {
-		const parsed = JSON.parse(raw ?? "");
-		if (typeof parsed?.vault === "string" && parsed.vault.startsWith("/")) return parsed.vault;
+	try {
+		const cfg = JSON.parse(configJson ?? "");
+		if (typeof cfg?.vault === "string" && cfg.vault.startsWith("/")) return cfg.vault;
 	} catch {}
+	const state = parseState(stateJson);
 	if (sessionCwd && sessionCwd.startsWith("/")) return sessionCwd;
+	const bucket = bucketCwd ?? sessionCwd;
+	if (bucket && bucket.startsWith("/")) {
+		const mapped = state?.workspaces?.[bucket];
+		if (typeof mapped === "string" && mapped.startsWith("/")) return mapped;
+	}
+	if (typeof state?.vault === "string" && state.vault.startsWith("/")) return state.vault;
 	return join(home, "Workspace", DEFAULT_VAULT_DIRNAME);
 }
 let cached = {
@@ -68,9 +102,7 @@ let cached = {
 	key: "",
 	value: ""
 };
-/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
-*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——用户在哪个工作区开会话，vault 就解析到哪。 */
-function vaultPath(sessionCwd, now = Date.now()) {
+function resolve$1(sessionCwd, now) {
 	const dir = stateDir();
 	let configJson;
 	let stateJson;
@@ -80,9 +112,11 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	try {
 		stateJson = readFileSync(join(dir, "state.json"), "utf8");
 	} catch {}
-	const key = `${sessionCwd ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
+	const cwdSkeleton = cwdHasSkeleton(sessionCwd) ? sessionCwd : void 0;
+	const bucket = sessionCwd && sessionCwd.startsWith("/") ? sessionCwd : void 0;
+	const key = `${cwdSkeleton ?? ""}|${bucket ?? ""}|${configJson ?? ""}|${stateJson ?? ""}`;
 	if (now - cached.at < 6e4 && cached.key === key) return cached.value;
-	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, sessionCwd);
+	const value = computeVaultPath(process.env.SUN_VAULT, configJson, stateJson, cwdSkeleton, homedir(), bucket);
 	cached = {
 		at: now,
 		key,
@@ -90,6 +124,12 @@ function vaultPath(sessionCwd, now = Date.now()) {
 	};
 	return value;
 }
+/** 运行期解析：每次调用重读状态目录（60s 微缓存防抖），登记/手改后即时生效。
+*  sessionCwd：调用方从 exec 提取的会话工作目录（可选）——本桶已初始化（含 90-Meta）
+*  或已在 workspaces 映射登记时，vault 就解析到哪。 */
+function vaultPath(sessionCwd, now = Date.now()) {
+	return resolve$1(sessionCwd, now);
+}
 vaultPath();
 // src/worker-vault.ts
 const inject = ["tools"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sun-space",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Sun Space：DeepSeek Harness 个人超智能体插件——Router/Worker 双预设工具白名单、钉钉待办轮询、Obsidian 知识库落库、会话工作台与定时任务管理。",
   "exports": {
@@ -54,4 +54,4 @@
       "esbuild"
     ]
   }
-}
+}

package/src/client.js

@@ -20,9 +20,10 @@ window.__ModuleLoader__.load({
       const VAULT_DIRNAME = 'sun-vault' // vault 目录名约定；绝对路径动态发现，见 resolveVault
       // 架构 §4.1 不变量：呈现层不得持有会话 id / vault 绝对路径常量（Router 会话会轮换，机器会换）。
       // 会话解析链：session/list（sun-router 会话）→ 90-Meta/system/state.json 裁决 → updatedAt 最新兜底。
-      // vault 解析链：会话 cwd 推 HOME → 约定布局探测 state.json → state.json 的 vault 字段裁决（跨机自愈）。
+      // vault 解析链（server 端 vault-path.ts 为唯一事实源）：config/分桶映射（workspaces[本工作区]）→
+      // 约定布局发现；当前工作区无骨架时引导以工作区为根初始化（服务端登记仅放行空目录/已含骨架）。
       // 写回：① 创建会话后经 session/prompt 引导自登记（含 vault 字段）；② 晨报自检发现缺失/不一致自动修正。
-      const WB_REV = 'v18' // 根节点 data-wb-rev 版本标记：判别浏览器是否吃到旧 client.js（immutable 缓存坑，HANDOFF 踩坑 1）
+      const WB_REV = 'v20' // 根节点 data-wb-rev 版本标记：判别浏览器是否吃到旧 client.js（immutable 缓存坑，HANDOFF 踩坑 1）
 
       const STATUS_META = {
         proposed: { label: '待确认派发', color: '#9e9e9e' },
@@ -97,12 +98,18 @@ window.__ModuleLoader__.load({
 
       // ===== vault 绝对路径发现（跨机器；呈现层不持常量，架构 §4.1 同款不变量）=====
       // 链：会话 cwd 推 HOME → 约定布局 <HOME>/Workspace/sun-vault 探测 state.json → state.json.vault 字段裁决。
-      // state.json.vault 由 Router 自登记/晨报自检维护（server 端 VAULT 是唯一事实源）。
-      async function resolveVault() {
-        const v = await gw('session/list', {})
-        const items = Array.isArray(v?.items) ? v.items : Object.values(v?.items ?? v ?? {})
+      // state.json 由 Router 自登记/晨报自检维护（server 端解析链是唯一事实源）；
+      // workspaces 分桶映射优先（一桶一 vault，多实例互不污染，与 server ④ 级一致）。
+      // items 可选：调用方已取过 session/list 时复用（免重复 RPC）。
+      async function resolveVault(itemsIn, currentSessionId) {
+        let items = itemsIn
+        if (!items) {
+          const v = await gw('session/list', {})
+          items = Array.isArray(v?.items) ? v.items : Object.values(v?.items ?? v ?? {})
+        }
         const scope = items.find(s => s?.projections?.values?.agentPreset === 'sun-router')?.sessionId ?? items[0]?.sessionId
         if (!scope) return null
+        const myCwd = currentSessionId ? String((items.find(s => s.sessionId === currentSessionId) ?? {}).cwd ?? '') : ''
         // ① 插件状态目录（HOME 从会话 cwd 推导，绝对路径读取）：
         //    config.json 优先（运行期事实源——引导初始化/用户手写即时生效），state.json 兜底（启动期快照）
         const homes = [...new Set(items.map(s => String(s.cwd || '')).filter(c => c.startsWith('/')).map(c => c.split('/').slice(0, 3).join('/')))]
@@ -111,6 +118,8 @@ window.__ModuleLoader__.load({
             try {
               const raw = await readVaultFile(scope, `${home}/.dsh/state/sun-space/${file}`, 8)
               const st = JSON.parse(raw)
+              const mapped = myCwd.startsWith('/') ? st?.workspaces?.[myCwd] : undefined // 分桶登记（本工作区）
+              if (typeof mapped === 'string' && mapped.startsWith('/')) return mapped
               if (st?.vault && st.vault.startsWith('/')) return st.vault
             } catch { /* 该文件不存在 → 下一个 */ }
           }
@@ -163,15 +172,31 @@ window.__ModuleLoader__.load({
       // ===== 初始化检查（在任何会话的 tab 上都能跑；① 用当前会话作 workspaceFiles scope）=====
       async function runInitChecks(currentSessionId) {
         const c = { vault: false, presets: false, routerSession: null, vaultPath: null, currentCwd: null, notes: [] }
+        // 会话列表只取一次：currentCwd 供 ① 跨工作区提示与一键初始化，router 解析复用
+        let items = null
+        try {
+          const sl = await gw('session/list', {})
+          items = Array.isArray(sl?.items) ? sl.items : Object.values(sl?.items ?? {})
+          c.currentCwd = (items.find(s => s.sessionId === currentSessionId) ?? {}).cwd ?? null
+        } catch { c.notes.push('会话列表不可达 → 重试或检查实例') }
         // ① 知识库：vault 路径动态发现 + runbook 探测
-        const vault = await resolveVault()
+        const vault = await resolveVault(items, currentSessionId)
         c.vaultPath = vault
         if (vault && currentSessionId) {
           try { await readVaultFile(currentSessionId, `${vault}/90-Meta/runbook.md`, 10); c.vault = true } catch {
             c.notes.push(`知识库未就绪（已定位 ${vault}，缺 90-Meta 骨架）：① 用 Obsidian 打开该目录 ② 可让任意 Router 会话执行"初始化知识库"指令 ③ 重新检查`)
           }
+          // 跨工作区提示：识别到的 vault 在别处、当前工作区无骨架——一键初始化将以当前工作区为根
+          //（服务端门控：仅空目录或已含 90-Meta 的工作区目录会被当 vault 登记/解析，见 vault-path.ts）
+          if (c.currentCwd && c.currentCwd !== vault) {
+            try { await readVaultFile(currentSessionId, `${c.currentCwd}/90-Meta/runbook.md`, 2) } catch {
+              c.notes.push(`知识库识别在 ${vault}；当前工作区 ${c.currentCwd} 尚无骨架——【创建 Router 会话】将以当前工作区为知识库根初始化；若要沿用 ${vault}，请到它所在的工作区开会话`)
+            }
+          }
         } else if (!vault) {
-          c.notes.push(`未找到知识库目录：按约定应在 <用户目录>/Workspace/${VAULT_DIRNAME}（含 90-Meta/system/state.json）；自定义位置需由 Router 把绝对路径写进 state.json 的 vault 字段`)
+          c.notes.push(c.currentCwd
+            ? `未找到既有知识库——当前工作区 ${c.currentCwd} 将作为知识库根（待初始化）：完成下方初始化引导即可`
+            : `未找到知识库目录：按约定应在 <用户目录>/Workspace/${VAULT_DIRNAME}（含 90-Meta/system/state.json）；自定义位置需由 Router 把绝对路径写进 state.json 的 vault 字段`)
         } else {
           c.notes.push('知识库检查需要会话作读取通道 → 先创建会话')
         }
@@ -188,11 +213,12 @@ window.__ModuleLoader__.load({
           c.notes.push('预设服务不可达 → 确认 Harness 实例在线、插件已启用')
         }
         // ③ Router 会话：动态解析 + 首个 sun-router 会话创建时自动登记其 cwd 为 vault 根
-        //   （"当前目录作为 vault"语义的插件层落点；env/config 更高优先级不受影响）
+        //   （"当前目录作为 vault"语义的插件层落点；门控在服务端——空目录/已含骨架才登记）
         try {
-          const sl = await gw('session/list', {})
-          const items = Array.isArray(sl?.items) ? sl.items : Object.values(sl?.items ?? {})
-          c.currentCwd = (items.find(s => s.sessionId === currentSessionId) ?? {}).cwd ?? null
+          if (!items) { // 顶部取失败时兜底重取
+            const sl = await gw('session/list', {})
+            items = Array.isArray(sl?.items) ? sl.items : Object.values(sl?.items ?? {})
+          }
           // vault 根登记由宿主插件在 sun-router 会话创建时自动完成（index.ts agent/created 钩子）
           c.routerSession = vault ? await resolveRouterSession(vault, items) : null
           if (!c.routerSession) c.notes.push('Router 会话不存在 → 点下方「创建 Router 会话」（sun-router 预设，随当前工作区），创建后自动登记 state.json')
@@ -277,13 +303,14 @@ window.__ModuleLoader__.load({
             requestId: 'sun-init-' + Date.now(),
             sessionId: sid,
             mode: 'queue',
-            content: [{ type: 'text', text: `【孙学空间初始化】你是新环境的 Sun Router（你的会话 id：${sid}）。你的工作目录即知识库根（vault）。按顺序完成：
-1) 用 sun_vault_write 创建知识库骨架（vault 即你的工作目录，已在会话创建时自动登记）：
+            content: [{ type: 'text', text: `【孙学空间初始化】你是新环境的 Sun Router（你的会话 id：${sid}）。按顺序完成：
+1) 用 sun_state_write 确认/补全本工作区的 vault 根登记（参数 {"vault": true}——会话创建时已自动登记，此步幂等自愈；若 ok:false 按注记处理）
+2) 用 sun_vault_write 创建知识库骨架（实际根以工具返回的 vault 字段为准，勿凭工作目录猜测）：
    - 90-Meta/schemas.md：frontmatter 契约最小集（通用字段 type/id/status/created/updated；task 的 status 枚举 proposed|running|need-confirm|done|blocked|dropped；写入纪律：Journal 由 Router 独占、日期一律本地时间 YYYY-MM-DDTHH:mm 不带时区后缀、结论必注出处）
    - 90-Meta/runbook.md：初始版（# Sun 行为手册 + v0.1 版本行 + §1 角色：Router 只分派不执行 + §2 沟通规范：IM ≤100 字结论先行 + §3 打扰分级：info 攒批/ask 立即/urgent 加 DING）
    - 90-Meta/memory.md：初始版（# 关于用户，待填充）
-2) 用 sun_vault_write 写 90-Meta/system/state.json：{"routerSession": "${sid}", "vault": "<你的工作目录绝对路径>", "updatedAt": "<本地时间 YYYY-MM-DDTHH:mm>"}（自登记，供孙学空间发现与轮换机制使用）
-3) 完成后列出生成的文件清单与知识库路径。` }],
+3) 用 sun_vault_write 写 90-Meta/system/state.json：{"routerSession": "${sid}", "vault": "<知识库根绝对路径——填第 2 步 sun_vault_write 返回的 vault 值>", "updatedAt": "<本地时间 YYYY-MM-DDTHH:mm>"}（自登记，供孙学空间发现与轮换机制使用）
+4) 完成后列出生成的文件清单与知识库路径。` }],
             clientTimeZone: 'Asia/Shanghai',
           })
           try { hostCtx.uiWorkspace.openSession(sid) } catch (e) { D.errors.push('openSession: ' + String(e)) }
@@ -298,12 +325,14 @@ window.__ModuleLoader__.load({
             requestId: 'sun-skel-' + Date.now(),
             sessionId: routerSession,
             mode: 'queue',
-            content: [{ type: 'text', text: `【知识库骨架补建】用 sun_vault_write 在你的 vault 路径下创建：
-- 90-Meta/schemas.md：frontmatter 契约最小集（通用字段 type/id/status/created/updated；写入纪律同 runbook）
-- 90-Meta/runbook.md：若缺失则写初始版（# Sun 行为手册 + v0.1）
-- 90-Meta/memory.md：若缺失则写初始版（# 关于用户）
-- 90-Meta/system/state.json：{"routerSession": "${routerSession}", "vault": "<你的 vault 绝对路径>", "updatedAt": "<本地时间>"}（已有的话合并更新 routerSession/vault 字段）
-完成后报告清单。` }],
+            content: [{ type: 'text', text: `【知识库骨架补建 + vault 根登记】按顺序完成：
+1) 用 sun_state_write 登记本工作区为 vault 根（参数 {"vault": true}——分桶登记，零审批，不影响其他工作区；值由系统从你的会话上下文派生。若 ok:false 按注记处理，禁止用 shell 手写状态目录）
+2) 用 sun_vault_write 创建/补全知识库骨架（实际根以工具返回的 vault 字段为准，勿凭工作目录猜测）：
+   - 90-Meta/schemas.md：frontmatter 契约最小集（通用字段 type/id/status/created/updated；task 的 status 枚举 proposed|running|need-confirm|done|blocked|dropped；写入纪律同 runbook）
+   - 90-Meta/runbook.md：若缺失则写初始版（# Sun 行为手册 + v0.1）
+   - 90-Meta/memory.md：若缺失则写初始版（# 关于用户）
+   - 90-Meta/system/state.json：{"routerSession": "${routerSession}", "vault": "<第 2 步 sun_vault_write 返回的 vault 值>", "updatedAt": "<本地时间 YYYY-MM-DDTHH:mm 无时区后缀>"}（已有的话合并更新 routerSession/vault 字段）
+完成后报告清单与知识库路径。` }],
             clientTimeZone: 'Asia/Shanghai',
           })
           onRetry()
@@ -421,7 +450,7 @@ window.__ModuleLoader__.load({
       function OnboardPanel({ checks, currentSessionId, onRetry }) {
         const steps = [
           { n: 1, ok: checks.presets, title: '确认依赖插件', desc: checks.presets ? '智能体协作 / 子智能体插件已启用' : '打开插件面板，启用 sun-space / 智能体协作相关插件后重启实例', action: checks.presets ? null : 'plugins' },
-          { n: 2, ok: !!checks.routerSession, title: '一键初始化（Router 会话 + 知识库）', desc: checks.routerSession ? `已就绪：${checks.routerSession.slice(0, 28)}…` : `一键完成：以当前工作区目录${checks.currentCwd ? `（${checks.currentCwd}）` : ''}为知识库根 → 创建 Router 会话 → 写入 90-Meta 骨架 → 自登记（仅 ~/.dsh 登记需一次批准）`, action: checks.presets && !checks.routerSession ? 'create-router' : null },
+          { n: 2, ok: !!checks.routerSession, title: '一键初始化（Router 会话 + 知识库）', desc: checks.routerSession ? `已就绪：${checks.routerSession.slice(0, 28)}…` : `一键完成：以当前工作区目录${checks.currentCwd ? `（${checks.currentCwd}）` : ''}为知识库根 → 创建 Router 会话 → 写入 90-Meta 骨架 → 分桶自登记（全程零审批）`, action: checks.presets && !checks.routerSession ? 'create-router' : null },
           { n: 3, ok: checks.vault, title: '知识库就绪', desc: checks.vault ? `已就绪：${checks.vaultPath}` : (checks.routerSession ? '知识库骨架缺失 → 点下方按钮让 Router 补建' : '完成第②步后自动创建'), action: checks.presets && checks.routerSession && !checks.vault ? 'init-skeleton' : null },
         ]
         const allOk = steps.every(x => x.ok)