dsh-projects-panel 0.1.0

package/lib/index.js

@@ -0,0 +1,1025 @@
+import { createRequire } from "node:module";
+import { mkdir, open, readFile, readdir, rename } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+
+//#region src/host-tree.ts
+/** 项目目录集合的子目录名（数据根之下；projects.json 位于数据根）。 */
+const PROJECTS_DIRECTORY = "projects";
+/** 项目目录集合的磁盘路径：数据根下 projects/ 子目录（不创建）。 */
+function projectStoreRoot(root) {
+	return join(root, PROJECTS_DIRECTORY);
+}
+/** 新建一棵空的项目树：unit 标记沿用 Cordis 数据文件约定。 */
+const emptyTree = () => ({
+	unit: {
+		name: "project",
+		version: 1
+	},
+	global: { initialized: true },
+	projectIds: [],
+	archivedProjectIds: [],
+	projects: {}
+});
+/** 运行时对象判定：排除 null 与数组，用作外部 JSON 数据的收窄基元。 */
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/**
+* 校验项目名。
+*
+* 项目名仅做展示用（目录名 = 项目 ID），因此放宽为：非空、不含路径
+* 分隔符（/ \）、不含控制字符、长度不超过 255。
+*/
+function validateProjectName(name) {
+	if (name.length === 0) throw new Error("项目名称不能为空");
+	if (name.length > 255) throw new Error("项目名称不能超过 255 个字符");
+	if (/[\\/]/.test(name)) throw new Error("项目名称不能包含路径分隔符");
+	if (/[\u0000-\u001f\u007f]/.test(name)) throw new Error("项目名称不能包含控制字符");
+}
+/** UUID v4 格式校验（连字符分组，不强制版本位）。 */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** 校验项目 id 是否为合法 UUID 格式。 */
+function validateProjectId(id) {
+	if (!UUID_RE.test(id)) throw new Error(`项目 id 不是合法 UUID: ${id}`);
+}
+/**
+* 递归校验单个项目节点。
+*
+* @param all 已见过的项目 id，用于检出跨层重复引用
+* @param parent 当前节点的父 id，用于检出自环
+*/
+function validateNode(node, all, parent) {
+	if (!isRecord(node)) throw new Error("项目节点必须是对象");
+	for (const key of [
+		"projectIds",
+		"workspaceIds",
+		"archivedProjectIds"
+	]) if (!Array.isArray(node[key]) || node[key].some((v) => typeof v !== "string")) throw new Error(`字段 ${key} 无效`);
+	if (!isRecord(node.projects) || !isRecord(node.workspaces) || typeof node.name !== "string") throw new Error("项目节点结构无效");
+	for (const id of node.projectIds) {
+		if (id === parent || all.has(id)) throw new Error("项目树存在重复引用或循环");
+		if (!node.projects[id]) throw new Error(`未知项目引用: ${id}`);
+		all.add(id);
+		validateNode(node.projects[id], all, id);
+	}
+	for (const id of node.archivedProjectIds) if (node.projects[id]) throw new Error(`归档项目仍在活动树中: ${id}`);
+	for (const id of node.workspaceIds) if (!node.workspaces[id]) throw new Error(`未知工作区引用: ${id}`);
+}
+/**
+* 校验整棵项目树的根结构：顶层 id 不得重复、必须可解析，
+* 且活动与归档两个集合不允许出现同一项目。
+*/
+function validateProjectTree(tree) {
+	if (!isRecord(tree) || !Array.isArray(tree.projectIds) || !Array.isArray(tree.archivedProjectIds) || !isRecord(tree.projects)) throw new Error("projects.json 根结构无效");
+	const all = /* @__PURE__ */ new Set();
+	for (const id of tree.projectIds) {
+		if (all.has(id) || !tree.projects[id]) throw new Error(`未知或重复项目引用: ${id}`);
+		all.add(id);
+		validateNode(tree.projects[id], all, id);
+	}
+	for (const id of tree.archivedProjectIds) if (all.has(id)) throw new Error(`项目同时处于活动和归档状态: ${id}`);
+}
+/**
+* 以「临时文件 + fsync + rename」方式原子写入 JSON。
+*
+* rename 在同一文件系统内是原子的，避免读者读到写了一半的文件；
+* 0o600 保证项目数据目录不被他人在磁盘上读取。
+*/
+async function atomicWriteJson(file, value) {
+	await mkdir(resolve(file, ".."), { recursive: true });
+	const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+	const handle = await open(tmp, "w", 384);
+	try {
+		await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await rename(tmp, file);
+}
+/**
+* 读取项目树；projects.json 缺失或损坏时以项目目录集合内容重建。
+*
+* 缺失（ENOENT）或 JSON 损坏（SyntaxError）都视为首次启动：
+* 扫描 root/projects 下 UUID 格式的目录，为每个目录建立一个顶层项目
+* （名称缺省为 id，可由用户后续通过编辑补全）。
+*/
+async function readProjectTree(root) {
+	const file = join(root, "projects.json");
+	try {
+		const tree = JSON.parse(await readFile(file, "utf8"));
+		validateProjectTree(tree);
+		return tree;
+	} catch (error) {
+		if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+		const store = projectStoreRoot(root);
+		await mkdir(store, { recursive: true });
+		const tree = emptyTree();
+		try {
+			for (const entry of await readdir(store, { withFileTypes: true })) if (entry.isDirectory() && UUID_RE.test(entry.name)) {
+				const id = entry.name;
+				const now = (/* @__PURE__ */ new Date()).toISOString();
+				tree.projectIds.push(id);
+				tree.projects[id] = newProject(id, now);
+			}
+		} catch {}
+		await atomicWriteJson(file, tree);
+		return tree;
+	}
+}
+/** 校验后原子写入项目树。 */
+async function writeProjectTree(root, tree) {
+	validateProjectTree(tree);
+	await atomicWriteJson(join(root, "projects.json"), tree);
+}
+/** 构造一个新项目节点；默认时间戳为当前时间。 */
+function newProject(name, now = (/* @__PURE__ */ new Date()).toISOString(), description = "", link = "") {
+	validateProjectName(name);
+	return {
+		name,
+		description,
+		link,
+		createdAt: now,
+		updatedAt: now,
+		projectIds: [],
+		workspaceIds: [],
+		archivedProjectIds: [],
+		projects: {},
+		workspaces: {}
+	};
+}
+/** 项目对应的磁盘目录路径：root/projects/<id>（不创建目录）。 */
+function projectDirectory(root, id) {
+	validateProjectId(id);
+	return join(projectStoreRoot(root), id);
+}
+/** link 必须是宿主已有的绝对路径，拒绝相对路径与空值。 */
+function isSafeLinkPath(link) {
+	return link.length > 0 && resolve(link) === link;
+}
+/** 在活动树内按 id 查找项目节点（跨层深度优先）。 */
+function findActiveNode(nodes, id) {
+	const direct = nodes[id];
+	if (direct) return direct;
+	for (const node of Object.values(nodes)) {
+		const found = findActiveNode(node.projects, id);
+		if (found) return found;
+	}
+}
+/** 在活动树内按 id 查找项目容器与其节点（跨层深度优先）。 */
+function findProjectHolder(tree, id) {
+	const walk = (holder, parentNode) => {
+		const direct = holder.projects[id];
+		if (direct) return {
+			holder,
+			node: direct,
+			parentNode
+		};
+		for (const [key, node] of Object.entries(holder.projects)) {
+			const found = walk(node, node);
+			if (found) return found;
+		}
+	};
+	return walk(tree);
+}
+/** 收集某项目子树内的全部后代项目 id（含嵌套）。 */
+function collectDescendantIds(node) {
+	const result = /* @__PURE__ */ new Set();
+	const walk = (current) => {
+		for (const [id, child] of Object.entries(current.projects)) {
+			result.add(id);
+			walk(child);
+		}
+	};
+	walk(node);
+	return result;
+}
+/** 收集整棵活动树声明的工作区 id（含嵌套子项目）。 */
+function collectWorkspaceIds(tree) {
+	const result = [];
+	const walk = (nodes) => {
+		for (const node of Object.values(nodes)) {
+			result.push(...node.workspaceIds);
+			walk(node.projects);
+		}
+	};
+	walk(tree.projects);
+	return result;
+}
+/**
+* 断言整树改写未改变任何项目的父归属（换父一律走 moveProject）。
+*
+* 比较口径：每个项目 id 的父容器 id（顶层为空串）；新增项目允许
+* （设置页新建经 project 路由，此处仅防换父脱节），删除项目允许
+* （归档经 project 路由）。
+*/
+function assertNoParentChange(oldTree, nextTree) {
+	const parentsOf = (tree) => {
+		const result = /* @__PURE__ */ new Map();
+		const walk = (nodes, parentId) => {
+			for (const [id, node] of Object.entries(nodes)) {
+				result.set(id, parentId);
+				walk(node.projects, id);
+			}
+		};
+		for (const id of tree.projectIds) {
+			result.set(id, "");
+			const node = tree.projects[id];
+			if (node) walk(node.projects, id);
+		}
+		return result;
+	};
+	const oldParents = parentsOf(oldTree);
+	const nextParents = parentsOf(nextTree);
+	for (const [id, nextParent] of nextParents) {
+		const oldParent = oldParents.get(id);
+		if (oldParent !== void 0 && oldParent !== nextParent) throw new Error("换父请使用项目移动路由");
+	}
+}
+/**
+* 断言工作区归属在全树唯一（同一工作区至多出现一次）。
+*
+* 仅供整树替换（POST /projects-panel/tree）写边界兜底；日常挂载
+* 走先摘除再挂载已天然保证唯一，不经此断言。
+*/
+function assertWorkspaceUnique(tree) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const id of collectWorkspaceIds(tree)) {
+		if (seen.has(id)) throw new Error(`工作区重复归属: ${id}`);
+		seen.add(id);
+	}
+}
+/**
+* 移动项目归属与排序（UUID 身份不变）。
+*
+* 项目目录 = projects/<id>/，与名称/归属解耦，因此移动只改树，不碰目录。
+* 同容器纯排序只改顺序；换父只改父子引用。移动到自身或后代下、
+* 锚点不存在或锚点已归档时拒绝且不落盘；同容器内锚点指向源自身
+* 视为无排序变化，同样不落盘。
+*/
+async function moveProject(root, sourceId, parentId, beforeId) {
+	const tree = await readProjectTree(root);
+	const found = findProjectHolder(tree, sourceId);
+	if (!found) throw new Error("项目不存在");
+	const { holder: oldHolder, node } = found;
+	let targetHolder;
+	if (parentId === void 0) targetHolder = tree;
+	else {
+		const target = findActiveNode(tree.projects, parentId);
+		if (!target) throw new Error("父项目不存在或已归档");
+		if (parentId === sourceId || collectDescendantIds(node).has(parentId)) throw new Error("不能移动到自身或子项目下");
+		targetHolder = target;
+	}
+	if (beforeId !== void 0 && beforeId === sourceId && oldHolder === targetHolder) return;
+	const movedAcross = oldHolder !== targetHolder;
+	const anchor = movedAcross && beforeId === sourceId ? void 0 : beforeId;
+	const isActiveAnchor = (holder, anchorId) => {
+		if (!holder.projectIds.includes(anchorId)) return false;
+		return findActiveNode(tree.projects, anchorId) !== void 0;
+	};
+	if (anchor !== void 0 && !isActiveAnchor(targetHolder, anchor)) throw new Error("排序锚点不存在或已归档");
+	if (!movedAcross) {
+		const oldIndex = oldHolder.projectIds.indexOf(sourceId);
+		if (oldIndex >= 0) oldHolder.projectIds.splice(oldIndex, 1);
+		if (anchor === void 0) targetHolder.projectIds.push(sourceId);
+		else targetHolder.projectIds.splice(targetHolder.projectIds.indexOf(anchor), 0, sourceId);
+		node.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		await writeProjectTree(root, tree);
+		return;
+	}
+	if (Object.entries(targetHolder.projects).some(([id, other]) => id !== sourceId && other.name === node.name)) throw new Error("目标项目下已存在同名项目");
+	applyProjectMove(tree, oldHolder, targetHolder, sourceId, node, anchor);
+	node.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await writeProjectTree(root, tree);
+}
+/**
+* 在内存树上执行换父（摘除源容器引用并按锚插入目标容器）。
+*
+* @param anchor 排序锚（省略=追加目标末尾）。
+*/
+function applyProjectMove(tree, oldHolder, targetHolder, sourceId, node, anchor) {
+	const oldIndex = oldHolder.projectIds.indexOf(sourceId);
+	if (oldIndex >= 0) oldHolder.projectIds.splice(oldIndex, 1);
+	delete oldHolder.projects[sourceId];
+	targetHolder.projects[sourceId] = node;
+	if (anchor === void 0) targetHolder.projectIds.push(sourceId);
+	else targetHolder.projectIds.splice(targetHolder.projectIds.indexOf(anchor), 0, sourceId);
+}
+/**
+* 从全部活动节点摘除某工作区引用（含 joinedAt 记录）。
+*
+* @returns 最后一次摘除到的成员关系记录（用于重新挂载时保留加入时间）；
+* 从未挂载过返回 undefined。
+*/
+function detachWorkspaceRef(holder, id) {
+	let meta;
+	for (const node of Object.values(holder.projects)) {
+		const index = node.workspaceIds.indexOf(id);
+		if (index >= 0) {
+			node.workspaceIds.splice(index, 1);
+			meta = node.workspaces[id];
+			delete node.workspaces[id];
+		}
+		const child = detachWorkspaceRef(node, id);
+		if (child) meta = child;
+	}
+	return meta;
+}
+/**
+* 挂载工作区到指定项目下（新增成员关系或移动归属）。
+*
+* 无论目标如何，都会先把该工作区从原有位置摘除再挂到目标项目，
+* 保证同一工作区在整棵活动树中至多出现一次；加入时间保留原记录。
+* parentId 省略时视为「移到顶层」——顶层不记录成员关系，因此等价于
+* 仅摘除（工作区随后以悬浮节点显示，此时 beforeId 不允许）。
+* beforeId 省略表示追加到目标末尾，否则插入到锚点之前；锚点等于
+* 工作区自身或锚点已归属异常时视为无操作或拒绝（锚点须为目标现成员）。
+*/
+async function attachWorkspace(root, workspaceId, parentId, beforeId) {
+	const tree = await readProjectTree(root);
+	const meta = detachWorkspaceRef(tree, workspaceId);
+	if (parentId === void 0) {
+		if (beforeId !== void 0) throw new Error("顶层排序请使用官方工作区排序");
+		await writeProjectTree(root, tree);
+		return;
+	}
+	const target = findActiveNode(tree.projects, parentId);
+	if (!target) throw new Error("父项目不存在");
+	if (beforeId !== void 0 && beforeId === workspaceId) return;
+	if (beforeId !== void 0 && !target.workspaceIds.includes(beforeId)) throw new Error("排序锚点不存在");
+	if (beforeId === void 0) target.workspaceIds.push(workspaceId);
+	else target.workspaceIds.splice(target.workspaceIds.indexOf(beforeId), 0, workspaceId);
+	target.workspaces[workspaceId] = meta ?? { joinedAt: (/* @__PURE__ */ new Date()).toISOString() };
+	await writeProjectTree(root, tree);
+}
+/** 从活动树摘除某工作区的全部成员关系（官方工作区删除后的清理）。 */
+async function detachWorkspace(root, workspaceId) {
+	const tree = await readProjectTree(root);
+	detachWorkspaceRef(tree, workspaceId);
+	await writeProjectTree(root, tree);
+}
+
+//#endregion
+//#region src/host-project.ts
+/** 按 id 深度查找节点，返回节点与其直接父（顶层项目无父）。 */
+function findNode(tree, id) {
+	const walk = (nodes, path, parent) => {
+		for (const [key, node] of Object.entries(nodes)) {
+			const nextPath = [...path, key];
+			if (key === id) return {
+				node,
+				parent,
+				path: nextPath
+			};
+			const found = walk(node.projects, nextPath, node);
+			if (found) return found;
+		}
+	};
+	return walk(tree.projects, []);
+}
+/** 从 id 列表移除一项（幂等：不存在时无操作）。 */
+function removeId(list, id) {
+	const i = list.indexOf(id);
+	if (i >= 0) list.splice(i, 1);
+}
+/**
+* 创建项目：建磁盘目录 + 挂入项目树。
+*
+* 目录名 = 项目 ID（UUID），与名称解耦。目录创建成功而树写入失败时，
+* 残留一个孤儿目录，下次启动会通过 readProjectTree 的扫描恢复逻辑被重新挂载。
+*/
+async function createProject(root, input) {
+	const tree = await readProjectTree(root);
+	const parentFound = input.parentId ? findNode(tree, input.parentId) : void 0;
+	const parent = parentFound?.node;
+	if (input.parentId && !parentFound) throw new Error("父项目不存在");
+	if (input.link && !isSafeLinkPath(input.link)) throw new Error("link 必须是绝对路径");
+	const holder = parent ?? tree;
+	if (Object.values(holder.projects).some((p) => p.name === input.name)) throw new Error("项目名称已存在");
+	const id = randomUUID();
+	const node = newProject(input.name, void 0, input.description ?? "", input.link ?? "");
+	await mkdir(projectStoreRoot(root), { recursive: true });
+	await mkdir(projectDirectory(root, id), { recursive: false });
+	holder.projects[id] = node;
+	holder.projectIds.push(id);
+	await writeProjectTree(root, tree);
+	return id;
+}
+/**
+* 更新项目：可改名、改描述、改 link。
+*
+* 改名只更新 projects.json 的 name 字段，不碰磁盘目录（目录名 = ID，
+* 与名称解耦）。重名检查在父级（顶层为树根）内进行。
+*/
+async function updateProject(root, id, patch) {
+	const tree = await readProjectTree(root);
+	const found = findNode(tree, id);
+	if (!found) throw new Error("项目不存在");
+	const node = found.node;
+	if (patch.link !== void 0 && patch.link && !isSafeLinkPath(patch.link)) throw new Error("link 必须是绝对路径");
+	if (patch.name && patch.name !== node.name) {
+		if ((found.parent ? Object.values(found.parent.projects) : Object.values(tree.projects)).some((other) => other !== node && other.name === patch.name)) throw new Error("项目名称已存在");
+		node.name = patch.name;
+	}
+	if (patch.description !== void 0) node.description = patch.description;
+	if (patch.link !== void 0) node.link = patch.link;
+	node.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await writeProjectTree(root, tree);
+}
+/**
+* 归档项目：移出活动树（加入 archivedProjectIds），不碰磁盘目录。
+*
+* 目录名 = ID，与归档状态解耦，恢复零成本，数据零丢失。
+*/
+async function archiveProject(root, id) {
+	const tree = await readProjectTree(root);
+	const found = findNode(tree, id);
+	if (!found) throw new Error("项目不存在");
+	const { node, parent } = found;
+	const holder = parent ?? tree;
+	removeId(holder.projectIds, id);
+	holder.archivedProjectIds.push(id);
+	if (parent) delete parent.projects[id];
+	else delete tree.projects[id];
+	node.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await writeProjectTree(root, tree);
+}
+/** link 文件白名单：只允许宿主项目根下的少数约定文件，拒绝路径穿越。 */
+const LINKED_FILES = [
+	"AGENTS.md",
+	".mcp.json",
+	".env"
+];
+/**
+* 读取 link 指向目录内的约定文件（如 AGENTS.md 供侧栏摘要展示）。
+*
+* @returns 文件不存在时返回 undefined；相对路径、绝对子路径或白名单外的
+* 文件名一律抛错，防止把任意宿主文件暴露给客户端。
+*/
+async function readLinkFile(link, relative) {
+	if (!isSafeLinkPath(link) || relative.includes("..") || relative.startsWith("/") || !LINKED_FILES.includes(relative)) throw new Error("不允许读取该 link 文件");
+	try {
+		return await readFile(join(link, relative), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+
+//#endregion
+//#region src/host-settings.ts
+/** settings.json 缺失字段时的默认值（旧路由兼容）。 */
+const defaultSettings = {
+	version: 1,
+	previewUrl: "/preview.html",
+	defaultProject: null,
+	tree: {
+		expandCurrent: true,
+		filter: null
+	}
+};
+/**
+* 读取插件设置（旧路由兼容）：与默认值做浅合并。
+*/
+async function readSettings(root) {
+	try {
+		const parsed = JSON.parse(await readFile(join(root, "settings.json"), "utf8"));
+		return {
+			...defaultSettings,
+			...parsed,
+			tree: {
+				...defaultSettings.tree,
+				...parsed.tree
+			}
+		};
+	} catch (error) {
+		if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+		return { ...defaultSettings };
+	}
+}
+/** 写入设置（旧路由兼容）：version 固定为当前结构版本 1。 */
+async function writeSettings(root, settings) {
+	await atomicWriteJson(join(root, "settings.json"), {
+		...settings,
+		version: 1
+	});
+}
+/** settings 命名空间名称。 */
+const SETTINGS_NAMESPACE = "projects-panel";
+/** projects-panel 命名空间 schema（schemastery）。 */
+const PROJECTS_PANEL_SETTINGS_SCHEMA = z.object({
+	workspaces: z.object({ enabled: z.boolean() }),
+	notifications: z.object({ enabled: z.boolean() }),
+	brand: z.object({
+		mark: z.string(),
+		name: z.string()
+	}),
+	previewUrl: z.string(),
+	defaultProject: z.any(),
+	tree: z.object({ expandCurrent: z.boolean() })
+});
+/** base 默认层（schema 校验后与用户层合并）。 */
+const PROJECTS_PANEL_SETTINGS_BASE = {
+	workspaces: { enabled: true },
+	notifications: { enabled: true },
+	brand: {
+		mark: "",
+		name: ""
+	},
+	previewUrl: "/preview.html",
+	defaultProject: null,
+	tree: { expandCurrent: true }
+};
+/** 注册 projects-panel 设置命名空间到宿主（fail-open：settings 服务缺失时不抛）。 */
+function registerSettingsNamespace(ctx) {
+	ctx.settings?.register(SETTINGS_NAMESPACE, PROJECTS_PANEL_SETTINGS_SCHEMA, { base: PROJECTS_PANEL_SETTINGS_BASE });
+}
+
+//#endregion
+//#region src/core/workspace.ts
+/**
+* 解析工作区的稳定标识。
+*
+* 宿主注入的 WorkspaceView 可能带显式 workspaceId；没有时退化为 view 自身的 id。
+* 树推导、筛选与展开状态都以该返回值作为统一键。
+*/
+function workspaceIdOf(workspace) {
+	return workspace.workspaceId ?? workspace.id ?? "";
+}
+/** Windows 风格路径判定：盘符或 UNC 前缀（官方 util/workspace-path 同源）。 */
+function isWindowsStylePath(value) {
+	return /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("\\\\") || value.startsWith("//");
+}
+/**
+* 把主目录下路径缩写为 `~` 形式（hover 卡展示用，与官方
+* abbreviateHomePath 语义一致）：home 缺省/空、非 POSIX 路径、
+* home 为根或不在该 home 下时原样返回。
+* @param path 绝对路径。
+* @param home 宿主主目录；缺省或空表示无法缩写。
+* @returns 缩写后的展示路径。
+*/
+function abbreviateHomePath(path, home) {
+	if (home === void 0 || home === "") return path;
+	if (isWindowsStylePath(path) || isWindowsStylePath(home)) return path;
+	const root = home.replace(/\/+$/, "");
+	if (root === "" || root === "/") return path;
+	if (path.replace(/\/+$/, "") === root) return "~";
+	if (path.startsWith(`${root}/`)) return `~${path.slice(root.length)}`;
+	return path;
+}
+
+//#endregion
+//#region src/index.ts
+/** 数据根目录名（位于 DSH_HOME 之下，缺省 ~/.dsh）。 */
+const DATA_ROOT_DIRECTORY = "dsh-projects-panel";
+/** 健康检查路径：供网关探活。 */
+const HEALTH_PATH = "/projects-panel/health";
+/** 插件版本：与 package.json version 保持同步；打包期无法注入动态版本。 */
+const PLUGIN_VERSION = "0.1.0";
+/** DSH CLI 自身清单：`dsh --version` 读取的同一文件。 */
+const DSH_MANIFEST_ID = "@deepseek-ai/dsh/package.json";
+/** 解析锚点取本模块：插件安装位置决定向上查找的 node_modules 链。 */
+const moduleRequire = createRequire(import.meta.url);
+/**
+* 解析用户主目录缩写：~ 展开为 homedir()。
+*
+* 仅识别单独的 "~" 或 "~/..." 形式；其它位置出现的 "~" 视为普通字符。
+*/
+function expandTilde(value) {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+	if (value.startsWith("~\\")) return join(homedir(), value.slice(2));
+	return value;
+}
+/** 反射软取会话查询服务：未装配（旧宿主/测试）时返回 undefined，不抛错。 */
+function sessionQueryOf(ctx) {
+	if (typeof ctx.get !== "function") return void 0;
+	const candidate = ctx.get("sessionQuery");
+	if (typeof candidate !== "object" || candidate === null) return void 0;
+	return typeof candidate.readTitleSnapshots === "function" ? candidate : void 0;
+}
+const inject = [
+	"webServer",
+	"workspaceRegistry",
+	"sessionController",
+	"settings"
+];
+/**
+* 计算项目数据根目录。
+*
+* DSH_PROJECTS_ROOT_DIR 设置时直接采用（支持 "~" 缩写，展开为用户主目录）；
+* 未设置时回落到 DSH_HOME（缺省 ~/.dsh）下的 dsh-projects-panel 目录。
+*
+* @param home 宿主数据根，测试时可注入临时目录
+*/
+function projectsRoot(home = process.env.DSH_HOME || join(homedir(), ".dsh")) {
+	const override = process.env.DSH_PROJECTS_ROOT_DIR;
+	if (override && override.trim()) return resolve(expandTilde(override.trim()));
+	return join(home, DATA_ROOT_DIRECTORY);
+}
+/** 确保数据根与项目目录集合存在，返回数据根路径。 */
+async function ensureProjectsRoot() {
+	const root = projectsRoot();
+	await mkdir(projectStoreRoot(root), { recursive: true });
+	return root;
+}
+/** 以 JSON 形式写出响应。 */
+function json(res, status, value) {
+	res.statusCode = status;
+	res.setHeader("content-type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(value));
+}
+/** 统一的路由错误出口：业务错误的中文消息直接透传给客户端展示。 */
+function routeError(res, error) {
+	json(res, 400, { error: error instanceof Error ? error.message : "请求失败" });
+}
+/** 读取并解析请求体；要求整体为 JSON 对象，其余字段留待各路由校验。 */
+async function readBodyObject(req) {
+	let text = "";
+	for await (const chunk of req) text += chunk;
+	const parsed = text ? JSON.parse(text) : {};
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("请求体必须是 JSON 对象");
+	return parsed;
+}
+/** 取出必填字符串字段；缺失或类型不符时抛出客户端可读的错误。 */
+function requireString(value, field) {
+	if (typeof value !== "string") throw new Error(`字段 ${field} 必须是字符串`);
+	return value;
+}
+/** 取出可选字符串字段；非字符串一律视为未提供。 */
+function optionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* settings 为宽容结构：读侧 readSettings 会与默认值合并并恢复缺字段，
+* 因此写侧仅做对象级校验，不逐字段验证类型。
+*/
+function settingsInput(input) {
+	return input;
+}
+/** 健康检查：报告插件存活与版本。 */
+function healthHandler(_req, res) {
+	json(res, 200, {
+		ok: true,
+		plugin: "dsh-projects-panel",
+		version: PLUGIN_VERSION
+	});
+}
+/**
+* 读取 package.json 的 version 字段。
+* @param manifestPath - package.json 绝对路径。
+* @returns 版本号字符串；文件不可读、JSON 非法或缺 version 字段时返回 undefined。
+*/
+function readPackageVersion(manifestPath) {
+	try {
+		const pkg = moduleRequire(manifestPath);
+		return typeof pkg.version === "string" ? pkg.version : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 解析 DSH 官方版本号，与 `dsh --version` 同源：同读 `@deepseek-ai/dsh/package.json`。
+*
+* DSH 启动时把安装依赖闭包镜像到 `$DSH_HOME/profiles/node_modules`，插件由自身
+* 安装位置向上即可解析到该清单，因此结果与 `dsh --version` 恒等；清单不可解析或
+* 读取失败（非标准安装）时回退插件版本。
+* @param resolveManifest - 模块解析器，默认取本模块的 createRequire。
+* @param readManifest - 清单读取器，默认 readPackageVersion。
+* @returns DSH 版本号；解析失败回退 PLUGIN_VERSION。
+*/
+function readDshVersion(resolveManifest = (id) => moduleRequire.resolve(id), readManifest = readPackageVersion) {
+	let manifest;
+	try {
+		manifest = resolveManifest(DSH_MANIFEST_ID);
+	} catch {
+		return PLUGIN_VERSION;
+	}
+	return readManifest(manifest) ?? PLUGIN_VERSION;
+}
+/** DSH 官方版本号缓存：解析结果在进程内不变。 */
+let dshVersionCache;
+function getDshVersion() {
+	dshVersionCache ??= readDshVersion();
+	return dshVersionCache;
+}
+/** 版本信息路由：返回 DSH 官方版本号。 */
+function versionHandler(_req, res) {
+	json(res, 200, {
+		ok: true,
+		dshVersion: getDshVersion()
+	});
+}
+/**
+* 聚合官方 workspace 列表为客户端视图。
+*
+* registry.list() 失败（官方 workspace 域不可用）时降级为空列表并记录，
+* 保证项目树仍可读。
+*/
+function workspaceViews(ctx) {
+	try {
+		return ctx.workspaceRegistry.list().map((workspace) => ({
+			workspaceId: workspace.id,
+			path: workspace.path,
+			title: workspace.title,
+			createdAt: workspace.createdAt,
+			updatedAt: workspace.updatedAt,
+			sessionIds: [...workspace.sessionIds]
+		}));
+	} catch (error) {
+		console.error("[projects-panel] 读取官方工作区列表失败，降级为空列表", error);
+		return [];
+	}
+}
+/** 从会话摘要的投影缓存中取 title（缓存缺失或非字符串时返回 undefined）。 */
+function titleOf(summary) {
+	const title = summary.projections?.values.title;
+	return typeof title === "string" && title.length > 0 ? title : void 0;
+}
+/**
+* 用官方会话查询服务补读缺失标题：对标题缺失的冷会话（含归档，
+* 投影缓存未预热）批量折叠日志中的持久 title，成功者回填。
+*
+* 官方 list 只携带投影缓存中已有的值（fail-soft 缓存，见
+* session-projection-cache），冷会话可能缺标题；而标题的权威持久源
+* 是日志里的 session/title 事件，sessionQuery.readTitleSnapshots 是
+* live 优先的批量冷读（持久会话开只读日志折叠），对归档会话同样有效。
+* 空白会话无标题事件、subagent 标题来自父链，均无需补读。
+* sessionQuery 未装配或整次补读失败时原样返回并记录，不阻塞树读取。
+*
+* @param ctx 宿主上下文（反射读取 sessionQuery）
+* @param views 已按工作区聚合的会话视图
+* @returns 补读后的会话视图（顺序不变）
+*/
+async function backfillSessionTitles(ctx, views) {
+	const missingIds = views.filter((view) => !view.blank && !view.subagent && !view.title?.trim().length).map((view) => view.id);
+	if (missingIds.length === 0) return [...views];
+	const query = sessionQueryOf(ctx);
+	if (query === void 0) return [...views];
+	try {
+		const results = await query.readTitleSnapshots(missingIds);
+		const byId = new Map(results.filter((result) => result.status === "fulfilled").map((result) => [result.sessionId, result.value?.title?.title]));
+		return views.map((view) => byId.has(view.id) && byId.get(view.id)?.trim().length ? {
+			...view,
+			title: byId.get(view.id)
+		} : view);
+	} catch (error) {
+		console.error("[projects-panel] 会话标题权威补读失败，保留投影标题", error);
+		return [...views];
+	}
+}
+/**
+* 聚合官方会话列表为客户端视图（挂在所属 workspace 下）。
+*
+* 输出顺序与官方一致：按 workspace 的 attach 记录（sessionIds 顺序，
+* 新会话前置）逐工作区聚合，保证新建会话显示在工作区列表最上方。
+* 归属与官方分组语义一致：仅采用 workspace 的 attach 记录；未 attach
+* 的会话官方显示在「未分组」，本树暂无未分组容器故不展示。归档标记
+* 来自 registry 全局归档集，subagent 来自摘要 origin。投影标题缺失的
+* 冷会话（含归档）由 sessionQuery 从日志权威补读（见
+* backfillSessionTitles）。
+* list() 失败时降级为空列表并记录，不阻塞树读取。
+*/
+async function sessionViews(ctx) {
+	try {
+		const workspaces = ctx.workspaceRegistry.list();
+		if (workspaces.length === 0) return [];
+		const archived = new Set(ctx.workspaceRegistry.archivedSessionIds);
+		const result = await ctx.sessionController.list({});
+		const bySessionId = new Map(result.items.map((summary) => [summary.sessionId, summary]));
+		const views = [];
+		for (const workspace of workspaces) for (const sessionId of workspace.sessionIds) {
+			const summary = bySessionId.get(sessionId);
+			if (!summary) continue;
+			views.push({
+				id: summary.sessionId,
+				workspaceId: workspace.id,
+				title: titleOf(summary),
+				updatedAt: summary.updatedAt,
+				running: summary.running,
+				blank: summary.blank,
+				subagent: summary.origin === "subagent",
+				archived: archived.has(summary.sessionId)
+			});
+		}
+		return await backfillSessionTitles(ctx, views);
+	} catch (error) {
+		console.error("[projects-panel] 读取官方会话列表失败，降级为空列表", error);
+		return [];
+	}
+}
+/** /projects-panel/tree：GET 返回完整树，POST 整树改写（仅排序与字段，不允许换父），其余 405。 */
+function registerTreeRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/tree",
+		handler: async (req, res) => {
+			try {
+				if (req.method === "GET") {
+					json(res, 200, {
+						tree: await readProjectTree(root),
+						workspaces: workspaceViews(ctx),
+						sessions: await sessionViews(ctx),
+						archivedSessionIds: [...ctx.workspaceRegistry.archivedSessionIds],
+						home: homedir()
+					});
+					return;
+				}
+				if (req.method === "POST") {
+					const input = await readBodyObject(req);
+					validateProjectTree(input);
+					assertWorkspaceUnique(input);
+					assertNoParentChange(await readProjectTree(root), input);
+					await writeProjectTree(root, input);
+					json(res, 200, { ok: true });
+					return;
+				}
+				json(res, 405, { error: "method not allowed" });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/**
+* /projects-panel/project：POST 建项目或归档。
+*
+* 建项目仅携带顶层字段并逐项校验，避免把客户端未知字段透传进树结构。
+*/
+function registerProjectRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/project",
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				const input = await readBodyObject(req);
+				if (input.action === "archive") {
+					await archiveProject(root, requireString(input.id, "id"));
+					json(res, 200, { ok: true });
+					return;
+				}
+				json(res, 201, { id: await createProject(root, {
+					name: requireString(input.name, "name"),
+					description: optionalString(input.description),
+					link: optionalString(input.link),
+					parentId: optionalString(input.parentId)
+				}) });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/** /projects-panel/project-update：POST 更新项目（改名/描述/link）。 */
+function registerProjectUpdateRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/project-update",
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				const input = await readBodyObject(req);
+				await updateProject(root, requireString(input.id, "id"), {
+					name: optionalString(input.name),
+					description: optionalString(input.description),
+					link: optionalString(input.link)
+				});
+				json(res, 200, { ok: true });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/**
+* /projects-panel/project-move：POST 移动项目归属与排序。
+*
+* UUID 身份不变；同容器纯排序只改顺序，换父同步搬磁盘目录
+* （先搬后写树，树写失败回滚；源目录缺失则新建空目录）。
+* 移动到自身或子项目下、目标同名、排序锚点不存在时拒绝。
+* parentId 省略表示回到顶层，beforeId 省略表示追加末尾。
+*/
+function registerProjectMoveRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/project-move",
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				const input = await readBodyObject(req);
+				await moveProject(root, requireString(input.id, "id"), optionalString(input.parentId), optionalString(input.beforeId));
+				json(res, 200, { ok: true });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/** /projects-panel/settings：GET 读设置，POST 整写设置，其余 405。 */
+function registerSettingsRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/settings",
+		handler: async (req, res) => {
+			try {
+				if (req.method === "GET") {
+					json(res, 200, await readSettings(root));
+					return;
+				}
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				await writeSettings(root, settingsInput(await readBodyObject(req)));
+				json(res, 200, { ok: true });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/**
+* /projects-panel/workspace-attach：POST 挂载工作区到项目。
+*
+* body 携带 workspaceId 与可选 parentId/beforeId：parentId 省略表示移到顶层
+* （只做摘除，工作区随后以悬浮节点显示，此时不允许 beforeId，顶层排序
+* 请使用官方工作区排序）；beforeId 省略表示追加到目标项目末尾。
+* 写入失败时整体拒绝。
+*/
+function registerWorkspaceAttachRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/workspace-attach",
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				const input = await readBodyObject(req);
+				await attachWorkspace(root, requireString(input.workspaceId, "workspaceId"), optionalString(input.parentId), optionalString(input.beforeId));
+				json(res, 200, { ok: true });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/** /projects-panel/workspace-detach：POST 摘除工作区归属（官方删除后的清理）。 */
+function registerWorkspaceDetachRoute(ctx, root) {
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/workspace-detach",
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					json(res, 405, { error: "method not allowed" });
+					return;
+				}
+				await detachWorkspace(root, requireString((await readBodyObject(req)).workspaceId, "workspaceId"));
+				json(res, 200, { ok: true });
+			} catch (error) {
+				routeError(res, error);
+			}
+		}
+	});
+}
+/** 插件入口：注册全部 HTTP 路由。数据根目录就绪后注册数据路由，健康检查立即生效。 */
+function apply(ctx) {
+	registerSettingsNamespace(ctx);
+	ctx.webServer.register({
+		kind: "exact",
+		path: HEALTH_PATH,
+		handler: healthHandler
+	});
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/projects-panel/version",
+		handler: versionHandler
+	});
+	ensureProjectsRoot().then((root) => {
+		registerTreeRoute(ctx, root);
+		registerProjectRoute(ctx, root);
+		registerProjectUpdateRoute(ctx, root);
+		registerProjectMoveRoute(ctx, root);
+		registerSettingsRoute(ctx, root);
+		registerWorkspaceAttachRoute(ctx, root);
+		registerWorkspaceDetachRoute(ctx, root);
+	}).catch((error) => {
+		console.error("[projects-panel] 初始化失败", error);
+	});
+}
+
+//#endregion
+export { PROJECTS_PANEL_SETTINGS_BASE, PROJECTS_PANEL_SETTINGS_SCHEMA, SETTINGS_NAMESPACE, abbreviateHomePath, apply, applyProjectMove, archiveProject, assertNoParentChange, assertWorkspaceUnique, atomicWriteJson, attachWorkspace, createProject, defaultSettings, detachWorkspace, emptyTree, findNode, inject, isSafeLinkPath, moveProject, newProject, projectDirectory, projectStoreRoot, projectsRoot, readDshVersion, readLinkFile, readProjectTree, readSettings, registerSettingsNamespace, updateProject, validateProjectName, validateProjectTree, workspaceIdOf, writeProjectTree, writeSettings };