@doubleelec/dsh-workspace-explorer 0.7.1-fork.4

package/lib/index.js

@@ -0,0 +1,385 @@
+import { open, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+/** @internal 运行期配置(供单元测试调整),不构成公开 API。 */
+const cfg = {
+	ignore: [...[
+		".git",
+		"node_modules",
+		"__pycache__",
+		".venv",
+		"venv",
+		".pytest_cache",
+		".ruff_cache",
+		".mypy_cache",
+		"dist",
+		"build",
+		".next",
+		".nuxt",
+		"coverage",
+		".idea",
+		"target"
+	]],
+	max: 400,
+	peekMaxLines: 60
+};
+const WHOLE_MAX_BYTES = 32768;
+const SMALL_FILE_MAX = 4194304;
+const PAGE_SCAN_CHUNK = 262144;
+const TREE_MAX_DEPTH = 10;
+const TREE_MAX_ENTRIES = 5e3;
+const MAX_CACHED_LINES = 2e6;
+const LINE_CACHE_MAX_FILES = 64;
+/** @internal 大文件行起始字节缓存(key=绝对路径),供单元测试断言,不构成公开 API。 */
+const lineIndexCache = /* @__PURE__ */ new Map();
+async function readJsonBody(req) {
+	let raw = "";
+	for await (const chunk of req) raw += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8");
+	try {
+		const parsed = JSON.parse(raw);
+		return parsed !== null && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function writeJson(res, value, status = 200) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-cache"
+	});
+	res.end(JSON.stringify(value));
+}
+/** @internal 把「工作区根目录 + 相对路径」解析为绝对路径,并校验 rel 不含危险段。 */
+function resolveRel(root, rel) {
+	if (root === "") return { error: "missing-root" };
+	if (rel !== "") {
+		if (rel.split("/").some((s) => s === "" || s === "." || s === "..")) return { error: "bad-rel" };
+	}
+	return { abs: rel === "" ? root : root.replace(/\/+$/, "") + "/" + rel };
+}
+/** @internal 列一个目录层级(目录优先、按名排序、噪声目录过滤、400 上限)。 */
+async function listDir(abs, baseRel) {
+	const dirents = await readdir(abs, { withFileTypes: true });
+	const out = [];
+	for (const d of dirents) {
+		if (d.name === ".DS_Store") continue;
+		if (d.isDirectory() && cfg.ignore.includes(d.name)) continue;
+		const target = join(abs, d.name);
+		let size = null;
+		if (d.isFile()) try {
+			size = (await stat(target)).size;
+		} catch {}
+		out.push({
+			name: d.name,
+			type: d.isDirectory() ? "directory" : "file",
+			path: target,
+			rel: baseRel === "" ? d.name : baseRel + "/" + d.name,
+			size
+		});
+	}
+	out.sort((a, b) => a.type !== b.type ? a.type === "directory" ? -1 : 1 : a.name.localeCompare(b.name));
+	const truncated = out.length > cfg.max;
+	return {
+		entries: truncated ? out.slice(0, cfg.max) : out,
+		truncated
+	};
+}
+/**
+* 按行读取 [offset, offset+limit) 一页内容。
+* 小文件(≤4MB)整读、行数精确;大文件块扫描定位行区间,行数未知(null)。
+*/
+/** @internal 按行读取一页内容。 */
+async function readLinesPage(abs, offset, limit) {
+	const size = (await stat(abs)).size;
+	if (size <= SMALL_FILE_MAX) {
+		const lines = (await readFile(abs)).toString("utf-8").split("\n");
+		if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+		const page = lines.slice(offset, offset + limit);
+		return {
+			content: page.join("\n"),
+			startLine: offset,
+			lineCount: lines.length,
+			hasMore: offset + page.length < lines.length
+		};
+	}
+	return pageScanLarge(abs, size, offset, limit);
+}
+/** @internal 大文件分页:增量缓存每行起始字节,翻页复用已扫描结果,避免每页从头重扫 O(n)。 */
+async function pageScanLarge(abs, size, offset, limit) {
+	const target = offset + limit;
+	const fh = await open(abs, "r");
+	try {
+		if (target > MAX_CACHED_LINES) {
+			let pos = 0;
+			let newlines = 0;
+			let startByte = offset === 0 ? 0 : -1;
+			let endByte = -1;
+			while (pos < size && endByte === -1) {
+				const want = Math.min(PAGE_SCAN_CHUNK, size - pos);
+				const chunk = Buffer.allocUnsafe(want);
+				await fh.read(chunk, 0, want, pos);
+				let idx = chunk.indexOf(10);
+				while (idx !== -1) {
+					newlines++;
+					if (newlines === offset) startByte = pos + idx + 1;
+					if (newlines === target) {
+						endByte = pos + idx + 1;
+						break;
+					}
+					idx = chunk.indexOf(10, idx + 1);
+				}
+				pos += want;
+			}
+			if (startByte === -1) startByte = size;
+			if (endByte === -1) endByte = size;
+			const len = endByte - startByte;
+			const buf = len > 0 ? Buffer.allocUnsafe(len) : Buffer.alloc(0);
+			if (len > 0) await fh.read(buf, 0, len, startByte);
+			return {
+				content: buf.toString("utf-8").replace(/\n$/, ""),
+				startLine: offset,
+				lineCount: null,
+				hasMore: endByte < size
+			};
+		}
+		let cached = lineIndexCache.get(abs);
+		if (!cached || cached.size !== size) {
+			if (lineIndexCache.size >= LINE_CACHE_MAX_FILES) lineIndexCache.clear();
+			cached = {
+				offsets: [0],
+				scannedBytes: 0,
+				size
+			};
+			lineIndexCache.set(abs, cached);
+		}
+		while (cached.offsets.length <= target && cached.scannedBytes < size) {
+			const pos = cached.scannedBytes;
+			const want = Math.min(PAGE_SCAN_CHUNK, size - pos);
+			const chunk = Buffer.allocUnsafe(want);
+			await fh.read(chunk, 0, want, pos);
+			let idx = chunk.indexOf(10);
+			while (idx !== -1) {
+				cached.offsets.push(pos + idx + 1);
+				idx = chunk.indexOf(10, idx + 1);
+			}
+			cached.scannedBytes = pos + want;
+		}
+		const startByte = offset < cached.offsets.length ? cached.offsets[offset] : size;
+		const endByte = target < cached.offsets.length ? cached.offsets[target] : size;
+		const len = endByte - startByte;
+		const buf = len > 0 ? Buffer.allocUnsafe(len) : Buffer.alloc(0);
+		if (len > 0) await fh.read(buf, 0, len, startByte);
+		const fullyScanned = cached.scannedBytes >= size;
+		const lastOffset = cached.offsets[cached.offsets.length - 1];
+		const lineCount = fullyScanned ? cached.offsets.length - (lastOffset === size ? 1 : 0) : null;
+		return {
+			content: buf.toString("utf-8").replace(/\n$/, ""),
+			startLine: offset,
+			lineCount,
+			hasMore: endByte < size
+		};
+	} finally {
+		await fh.close();
+	}
+}
+/** @internal 嗅探是否二进制(NUL 字节),只读前 8KB。 */
+async function sniffBinary(abs, size) {
+	const probe = Buffer.alloc(Math.min(8192, size));
+	if (probe.length === 0) return false;
+	const fh = await open(abs, "r");
+	try {
+		await fh.read(probe, 0, probe.length, 0);
+	} finally {
+		await fh.close();
+	}
+	return probe.includes(0);
+}
+/** @internal 递归收集目录树节点(树根相对 rel 从 '' 开始;受深度/条目预算限制)。 */
+async function buildTreeNodes(abs, rel, depth, budget, out) {
+	if (depth < 0 || budget.remaining <= 0) return;
+	const { entries } = await listDir(abs, rel);
+	for (const e of entries) {
+		if (budget.remaining <= 0) break;
+		out.push({
+			name: e.name,
+			type: e.type,
+			rel: e.rel
+		});
+		budget.remaining--;
+		if (e.type === "directory") await buildTreeNodes(e.path, e.rel, depth - 1, budget, out);
+	}
+}
+var src_default = {
+	inject: ["webServer"],
+	apply(ctx) {
+		const routes = [
+			{
+				kind: "exact",
+				path: "/dsh-we/api/config",
+				handler: async (req, res) => {
+					const body = await readJsonBody(req);
+					if (Array.isArray(body.ignore)) cfg.ignore = body.ignore.map((s) => String(s)).filter((s) => s !== "");
+					if (typeof body.max === "number" && body.max >= 1 && body.max <= 2e3) cfg.max = Math.floor(body.max);
+					if (typeof body.peekMaxLines === "number" && body.peekMaxLines >= 10 && body.peekMaxLines <= 500) cfg.peekMaxLines = Math.floor(body.peekMaxLines);
+					return writeJson(res, {
+						ok: true,
+						ignore: cfg.ignore,
+						max: cfg.max,
+						peekMaxLines: cfg.peekMaxLines
+					});
+				}
+			},
+			{
+				kind: "exact",
+				path: "/dsh-we/api/list",
+				handler: async (req, res) => {
+					const body = await readJsonBody(req);
+					const rel = String(body.rel ?? "");
+					const resolved = resolveRel(String(body.root ?? body.path ?? ""), rel);
+					if ("error" in resolved) return writeJson(res, {
+						ok: false,
+						error: resolved.error
+					});
+					const abs = resolved.abs;
+					try {
+						const { entries, truncated } = await listDir(abs, rel);
+						return writeJson(res, {
+							ok: true,
+							path: abs,
+							rel,
+							entries,
+							truncated
+						});
+					} catch (err) {
+						return writeJson(res, {
+							ok: false,
+							error: err instanceof Error ? err.message : String(err)
+						});
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: "/dsh-we/api/peek",
+				handler: async (req, res) => {
+					const body = await readJsonBody(req);
+					const resolved = resolveRel(String(body.root ?? ""), String(body.rel ?? ""));
+					if ("error" in resolved) return writeJson(res, {
+						ok: false,
+						error: resolved.error
+					});
+					const path = resolved.abs;
+					try {
+						const size = (await stat(path)).size;
+						if (await sniffBinary(path, size)) return writeJson(res, {
+							ok: true,
+							binary: true,
+							size,
+							lineCount: null,
+							startLine: 0,
+							content: "",
+							hasMore: false
+						});
+						if (body.whole === true && size <= WHOLE_MAX_BYTES) {
+							const lines = (await readFile(path)).toString("utf-8").split("\n");
+							if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+							return writeJson(res, {
+								ok: true,
+								binary: false,
+								size,
+								lineCount: lines.length,
+								startLine: 0,
+								content: lines.join("\n"),
+								hasMore: false
+							});
+						}
+						return writeJson(res, {
+							ok: true,
+							binary: false,
+							size,
+							...await readLinesPage(path, Math.max(0, Math.floor(Number(body.offset) || 0)), Math.min(2e3, Math.max(1, Math.floor(Number(body.limit) || cfg.peekMaxLines))))
+						});
+					} catch (err) {
+						return writeJson(res, {
+							ok: false,
+							error: err instanceof Error ? err.message : String(err)
+						});
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: "/dsh-we/api/tree",
+				handler: async (req, res) => {
+					const body = await readJsonBody(req);
+					const resolved = resolveRel(String(body.root ?? ""), String(body.rel ?? ""));
+					if ("error" in resolved) return writeJson(res, {
+						ok: false,
+						error: resolved.error
+					});
+					const path = resolved.abs;
+					const depth = Math.min(TREE_MAX_DEPTH, Math.max(1, Math.floor(Number(body.depth) || 3)));
+					const maxEntries = Math.min(TREE_MAX_ENTRIES, Math.max(1, Math.floor(Number(body.maxEntries) || 200)));
+					try {
+						const name = basename(path.replace(/\/+$/, "")) || basename(path);
+						const entries = [];
+						const budget = { remaining: maxEntries };
+						await buildTreeNodes(path, "", depth, budget, entries);
+						return writeJson(res, {
+							ok: true,
+							name,
+							entries,
+							entryCount: entries.length,
+							truncated: budget.remaining <= 0
+						});
+					} catch (err) {
+						return writeJson(res, {
+							ok: false,
+							error: err instanceof Error ? err.message : String(err)
+						});
+					}
+				}
+			},
+			{
+				kind: "exact",
+				path: "/dsh-we/api/write",
+				handler: async (req, res) => {
+					const body = await readJsonBody(req);
+					const resolved = resolveRel(String(body.root ?? ""), String(body.rel ?? ""));
+					if ("error" in resolved) return writeJson(res, {
+						ok: false,
+						error: resolved.error
+					});
+					const abs = resolved.abs;
+					const content = typeof body.content === "string" ? body.content : null;
+					if (content === null) return writeJson(res, {
+						ok: false,
+						error: "missing-content"
+					});
+					try {
+						if (typeof body.expectedSize === "number") try {
+							const info = await stat(abs);
+							if (info.size !== body.expectedSize) return writeJson(res, {
+								ok: false,
+								error: "file-changed",
+								currentSize: info.size
+							});
+						} catch {}
+						await writeFile(abs, content, "utf-8");
+						return writeJson(res, {
+							ok: true,
+							size: (await stat(abs)).size
+						});
+					} catch (err) {
+						return writeJson(res, {
+							ok: false,
+							error: err instanceof Error ? err.message : String(err)
+						});
+					}
+				}
+			}
+		];
+		for (const route of routes) ctx.webServer.register(route);
+	}
+};
+//#endregion
+export { buildTreeNodes, cfg, src_default as default, lineIndexCache, listDir, pageScanLarge, readLinesPage, resolveRel, sniffBinary };

package/lib/types/client/format.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 纯格式化工具(浏览器端,无 DOM / 无副作用),供面板与单元测试复用。
+ */
+/** 人类可读文件大小(空值返回空串)。 */
+export declare const fmtSize: (n: number | null | undefined) => string;
+/** 浏览器安全的 basename(兼容正斜杠结尾;DSH 内不依赖 node:path)。 */
+export declare const basename: (p: string) => string;
+/** 取小写扩展名;点开头(隐藏文件)或无扩展名返回空串。 */
+export declare const extOf: (name: string) => string;
+/** 把 /dsh-we/api/tree 的平铺条目渲染成带缩进与树形连线的文本块(目录拖拽 / 多选批量插入共用)。 */
+export declare function formatTreeBlock(name: string, entries: Array<{
+    rel: string;
+    type: string;
+    name: string;
+}>, truncated: boolean): string;

package/lib/types/client/index.d.ts

@@ -0,0 +1,8 @@
+interface CtxLike {
+    get(name: string): unknown;
+    effect(fn: () => () => void): void;
+    inject(deps: string[], callback: (scope: unknown) => unknown): void;
+}
+export declare const inject: string[];
+export declare function apply(ctx: CtxLike): void;
+export {};

package/lib/types/client/markdown.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 轻量 Markdown 渲染器(浏览器端,无 DOM / 无副作用)。
+ *
+ * 只覆盖预览场景的常用子集:标题 / 加粗 / 斜体 / 删除线 / 行内码 /
+ * 代码块(围栏```/缩进4空格) / 引用 / 有序+无序列表(含任务列表) /
+ * 分隔线 / 链接(纯文本展示,不生成 <a> 以免 file:// 外跳) / 表格(简单行)。
+ * 输出 React 元素描述(不直接依赖 react,调用方用 h 函数还原),
+ * 因此天然免疫 XSS——不做任何 innerHTML 拼接。
+ */
+export type MdNode = {
+    t: 'h';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    inline: MdInline[];
+} | {
+    t: 'p';
+    inline: MdInline[];
+} | {
+    t: 'code';
+    lang: string;
+    text: string;
+} | {
+    t: 'quote';
+    children: MdNode[];
+} | {
+    t: 'ul';
+    items: MdInline[][];
+} | {
+    t: 'ol';
+    start: number;
+    items: MdInline[][];
+} | {
+    t: 'task';
+    checked: boolean[];
+    items: MdInline[][];
+} | {
+    t: 'hr';
+} | {
+    t: 'table';
+    head: MdInline[][];
+    rows: MdInline[][][];
+};
+export type MdInline = {
+    t: 'text';
+    text: string;
+} | {
+    t: 'b';
+    children: MdInline[];
+} | {
+    t: 'i';
+    children: MdInline[];
+} | {
+    t: 's';
+    children: MdInline[];
+} | {
+    t: 'code';
+    text: string;
+} | {
+    t: 'link';
+    text: string;
+};
+/** 解析行内格式,返回 inline 节点数组。 */
+export declare function parseInline(src: string): MdInline[];
+/** 解析整篇 Markdown 为块节点数组。 */
+export declare function parseMarkdown(src: string): MdNode[];
+/** 是否 Markdown 文件(按扩展名)。 */
+export declare function isMarkdownFile(name: string): boolean;

package/lib/types/client/popupLayout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 弹窗高度纯函数(无 DOM / 无副作用,可单元测试)。
+ *
+ * 背景:弹窗高度 = 输入框顶部 − 会话头部底部,输入框多行变高、手机键盘弹起、
+ * 会话切换后旧监听没更新都会让它忽高忽矮;旧下限 200 被头部+搜索框吃完就只剩几行。
+ * 对策:自动测量保底 320 + 底部拖拽条手动覆盖(存 localStorage,双击恢复自动)。
+ */
+/** 自动/手动高度下限:保底能看清 ~10 行文件。 */
+export declare const POPUP_MIN_H = 320;
+/** 手动高度 localStorage key。 */
+export declare const POPUP_MANUAL_KEY = "dshwe.popupH.v1";
+/** 手动宽度下限:再窄目录树没法看。 */
+export declare const POPUP_MIN_W = 280;
+/** 手动宽度 localStorage key。 */
+export declare const POPUP_MANUAL_W_KEY = "dshwe.popupW.v1";
+/**
+ * 自动高度数学(measurePopup 的 DOM-free 部分)。
+ * @param top - 弹窗顶部(会话 header 底部 + 8)。
+ * @param bottomLimit - 底部上限(输入框顶部 − 8,无输入框时 vh − 48)。
+ * @param vh - 视口高度(移动端取 min(innerHeight, visualViewport.height))。
+ * @returns 钳制到 [minH, vh − top − 16] 的高度;空间不足保底 minH(允许轻微盖住输入框)。
+ */
+export declare function autoPopupHeight(top: number, bottomLimit: number, vh: number, minH?: number): number;
+/**
+ * 手动高度钳制(拖拽中 / 渲染时用,顺手取整)。
+ */
+export declare function clampPopupHeight(h: number, top: number, vh: number, minH?: number): number;
+/**
+ * 读手动高度:无存储 / 非法值 / 无 window(node 单测)一律返回 null(回落自动高度)。
+ */
+export declare function loadManualHeight(key?: string): number | null;
+/**
+ * 写手动高度:null 清除(恢复自动);存储不可用时静默忽略,自动高度兜底。
+ */
+export declare function saveManualHeight(h: number | null, key?: string): void;
+/**
+ * 手动宽度钳制(拖拽中 / 渲染时用,顺手取整)。
+ * @param w - 拖拽目标宽度;左边缘左拉变宽(增量为负),右推变窄。
+ * @param vw - 视口宽度;最大留 16px 边距,手机上自动收窄不挤出屏幕。
+ */
+export declare function clampPopupWidth(w: number, vw: number, minW?: number): number;
+/**
+ * 读手动宽度:无存储 / 非法值 / 无 window(node 单测)一律返回 null(回落设置页宽度)。
+ */
+export declare function loadManualWidth(key?: string): number | null;
+/**
+ * 写手动宽度:null 清除(恢复设置页宽度);存储不可用时静默忽略。
+ */
+export declare function saveManualWidth(w: number | null, key?: string): void;

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+import type { Context } from 'cordis';
+/** 请求面(结构子集:URL/method/headers + 异步 body 迭代)。 */
+export interface WsHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<string | Uint8Array>;
+}
+/** 响应面(结构子集:status/header/body 写)。 */
+export interface WsHttpResponse {
+    statusCode: number;
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string | Uint8Array): void;
+}
+/** 一行目录条目。 */
+export interface WsEntry {
+    name: string;
+    type: 'directory' | 'file';
+    path: string;
+    rel: string;
+    size: number | null;
+}
+/** cordis Context 增强:webServer 路由注册面(镜像 @deepseek-ai/dsh-host-webserver 的 WebRoute)。 */
+declare module 'cordis' {
+    interface Context {
+        webServer: {
+            register(route: {
+                kind: 'exact' | 'prefix';
+                path: string;
+                handler: (req: WsHttpRequest, res: WsHttpResponse) => void | Promise<void>;
+            }): () => void;
+        };
+    }
+}
+declare const _default: {
+    inject: string[];
+    apply(ctx: Context): void;
+};
+export default _default;

package/manifest.json

@@ -0,0 +1,36 @@
+{
+  "id": "elec-workspace-explorer",
+  "name": "工作区文件面板 (Workspace Explorer)",
+  "version": "0.7.1-fork.4",
+  "description": "右侧弹出面板展示当前工作区目录文件树,顶部 Tab 切换文件/设置,点击或拖拽文件引用到聊天输入框发送给大模型",
+  "kind": "dynamic-cordis-plugin",
+  "platforms": {
+    "host": "src/index.ts",
+    "client": "src/client/index.tsx"
+  },
+  "host": {
+    "handlers": [
+      "ws-tree.list",
+      "ws-tree.peek",
+      "ws-tree.tree"
+    ],
+    "services": [
+      "fs"
+    ]
+  },
+  "client": {
+    "slots": [
+      "conversation.session.header.utilities",
+      "sidebar.footer.action",
+      "shell.overlay",
+      "conversation.input.dock",
+      "settings.section"
+    ],
+    "services": [
+      "slots",
+      "layout",
+      "workspaces"
+    ]
+  },
+  "license": "MIT"
+}