@sparkelf/dsh-client-ui-skill-center 0.2.0-rc.9

package/lib/index.js

@@ -0,0 +1,396 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+//#region lib/types/index.js
+/**
+* Skill center — host half. Serves the skill-center data source over the
+* `/api/dsh-skill-center` route family: list grouped by source, enable or disable
+* model invocation, create, delete into a recoverable trash, and health.
+*
+* Reading goes through the official `ctx.skills` registry, so the catalog, its
+* provider precedence, and its hot reload are the harness's rather than a second
+* scanner's. The three writes have no official equivalent — the registry is
+* read-only — so they are implemented here against the skill file's YAML
+* frontmatter.
+*
+* @module @sparkelf/dsh-client-ui-skill-center
+*/
+/** Stable cordis plugin name. */
+const name = "ui-skill-center";
+/** Services required before the routes can mount. */
+const inject = [
+	"webServer",
+	"skills",
+	"sessions"
+];
+/** Route paths, mirrored by the browser half. */
+const ROUTES = {
+	list: "/api/dsh-skill-center/list",
+	setEnabled: "/api/dsh-skill-center/set-enabled",
+	create: "/api/dsh-skill-center/create",
+	delete: "/api/dsh-skill-center/delete",
+	health: "/api/dsh-skill-center/health"
+};
+/**
+* Groups the panel renders, in order. The level a skill resolves to selects its
+* group; anything matching no convention lands in the custom group.
+*/
+const SOURCE_GROUPS = [
+	{
+		key: "bundled",
+		title: "系统内置",
+		hint: "随 Harness 一同安装，不能删除"
+	},
+	{
+		key: "runtime",
+		title: "运行时注册",
+		hint: "由已安装的插件在运行时注册"
+	},
+	{
+		key: "user-agents",
+		title: "用户 ~/.agents/skills",
+		hint: "在用户 agents 目录下，对所有项目生效"
+	},
+	{
+		key: "user-dsh",
+		title: "用户 ~/.dsh/skills",
+		hint: "在用户 dsh 目录下，对所有项目生效"
+	},
+	{
+		key: "project-agents",
+		title: "项目 .agents/skills",
+		hint: "随项目提交，对协作者共享"
+	},
+	{
+		key: "project-dsh",
+		title: "项目 .dsh/skills",
+		hint: "项目本地技能，通常不提交"
+	},
+	{
+		key: "custom",
+		title: "自定义目录",
+		hint: "由本插件的 customSkillDirs 配置"
+	}
+];
+/**
+* The user skill root convention.
+* @param dshHome - the user's dsh config root, usually `~/.dsh`.
+* @returns the directory holding user-level skills.
+*/
+function userSkillRoot(dshHome) {
+	return join(dshHome, "skills");
+}
+/**
+* The project skill root convention.
+* @param projectRoot - the project's root directory.
+* @returns the directory holding that project's skills.
+*/
+function projectSkillRoot(projectRoot) {
+	return join(projectRoot, ".dsh", "skills");
+}
+/**
+* The nearest ancestor holding a `.git` entry.
+* @param cwd - the directory to search upward from.
+* @returns the project root, or `cwd` itself when no ancestor holds `.git`.
+*/
+function findProjectRoot(cwd) {
+	let current = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(current, ".git"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return resolve(cwd);
+		current = parent;
+	}
+}
+/**
+* The display group a skill belongs to.
+*
+* The registry summary reports a discovery source rather than a file path, so
+* grouping follows the source name the filesystem provider assigns to each root
+* it scans. An unrecognized source falls through to the custom group.
+* @param source - the registry's discovery source label.
+* @param provider - the provider that owns the skill body.
+* @returns the group key.
+*/
+function levelOfSource(source, provider) {
+	if (provider === "runtime") return "runtime";
+	const s = source.toLowerCase();
+	if (s.includes("bundled")) return "bundled";
+	if (s.includes(".agents")) return "project-agents";
+	if (s.includes(".dsh")) return "project-dsh";
+	if (s.includes("agents")) return "user-agents";
+	if (s.includes("dsh")) return "user-dsh";
+	if (s.includes("runtime")) return "runtime";
+	return "custom";
+}
+/**
+* Read `disable-model-invocation` from a skill file.
+* @param source - the skill file's content.
+* @returns the flag when the frontmatter declares it, otherwise undefined.
+*/
+function readDisabledFlag(source) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
+	if (match === null) return void 0;
+	const line = /^\s*disable-model-invocation\s*:\s*(true|false)\s*$/m.exec(match[1] ?? "");
+	return line === null ? void 0 : line[1] === "true";
+}
+/**
+* Rewrite `disable-model-invocation`, adding it when absent.
+*
+* The field is one YAML scalar in the leading frontmatter block, so this edits
+* that line rather than re-serializing the document: comments, key order, and
+* the body all survive unchanged.
+* @param source - the skill file's current content.
+* @param disabled - the value to write.
+* @returns the new content.
+*/
+function withDisabledFlag(source, disabled) {
+	const match = /^(---\r?\n)([\s\S]*?)(\r?\n---)/.exec(source);
+	if (match === null) return "---\ndisable-model-invocation: " + String(disabled) + "\n---\n" + source;
+	const body = match[2] ?? "";
+	const field = /^\s*disable-model-invocation\s*:.*$/m;
+	const next = field.test(body) ? body.replace(field, "disable-model-invocation: " + String(disabled)) : body + "\ndisable-model-invocation: " + String(disabled);
+	return (match[1] ?? "---\n") + next + (match[3] ?? "\n---") + source.slice(match[0].length);
+}
+/**
+* Build the SKILL.md a create writes.
+* @param name - the skill's kebab-case name.
+* @param description - the routing description.
+* @param whenToUse - extra routing guidance, omitted when undefined.
+* @param content - the instruction body; an empty value yields a heading.
+* @returns the complete file content.
+*/
+function buildSkillContent(name, description, whenToUse, content) {
+	const lines = [
+		"---",
+		"name: " + name,
+		"description: " + description
+	];
+	if (whenToUse !== void 0 && whenToUse.trim() !== "") lines.push("when-to-use: " + whenToUse);
+	lines.push("---", "");
+	lines.push(content.trim() === "" ? "# " + name : content.trim());
+	return lines.join("\n") + "\n";
+}
+/** Write a JSON response. */
+function writeJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": String(Buffer.byteLength(text))
+	});
+	res.end(text);
+}
+/** Read a bounded JSON request body. */
+async function readJson(req, maxBytes) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += buf.length;
+		if (total > maxBytes) throw new Error("request body too large");
+		chunks.push(buf);
+	}
+	if (total === 0) return {};
+	const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("request body must be a JSON object");
+	return parsed;
+}
+/** The list handler: group the registry snapshot by source. */
+async function handleList(deps, cwd) {
+	const projectRoots = [...new Set(deps.activeSessionCwds().map(findProjectRoot).concat(findProjectRoot(cwd)))];
+	const snapshot = await deps.snapshotProject(cwd);
+	const byGroup = new Map(SOURCE_GROUPS.map((g) => [g.key, []]));
+	for (const skill of snapshot.skills) {
+		const level = levelOfSource(skill.source, skill.provider);
+		const entry = {
+			name: skill.name,
+			description: skill.description,
+			level,
+			provider: skill.provider,
+			modelInvocable: skill.invocation.modelInvocable,
+			userInvocable: skill.invocation.userInvocable,
+			...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse }
+		};
+		(byGroup.get(level) ?? byGroup.get("custom"))?.push(entry);
+	}
+	const groups = [];
+	for (const g of SOURCE_GROUPS) {
+		const skills = (byGroup.get(g.key) ?? []).sort((a, b) => a.name.localeCompare(b.name));
+		if (skills.length > 0) groups.push({
+			key: g.key,
+			title: g.title,
+			hint: g.hint,
+			skills
+		});
+	}
+	return {
+		cwd,
+		projectRoots,
+		complete: snapshot.complete,
+		groups
+	};
+}
+/** The set-enabled handler: rewrite the skill's frontmatter flag. */
+async function handleSetEnabled(deps, body, cwd) {
+	const path = await resolveSkillPath(deps, requireString(body.name, "name"), body, cwd);
+	const enabled = body.enabled === true;
+	const source = await readFile(path, "utf8");
+	const before = readDisabledFlag(source);
+	const next = withDisabledFlag(source, !enabled);
+	if (next !== source) await writeFile(path, next, "utf8");
+	return {
+		name: requireString(body.name, "name"),
+		enabled,
+		modelInvocable: enabled,
+		changed: before !== !enabled
+	};
+}
+/** The create handler: write a new SKILL.md under the chosen root. */
+async function handleCreate(deps, body) {
+	const root = body.root === "project" ? "project" : "user";
+	const skillName = requireString(body.name, "name");
+	if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(skillName)) throw new Error("skill name must be kebab-case");
+	const dir = join(root === "project" ? projectSkillRoot(deps.activeSessionCwds()[0] ?? process.cwd()) : userSkillRoot(deps.dshHome), skillName);
+	const target = join(dir, "SKILL.md");
+	await mkdir(dir, { recursive: true });
+	await writeFile(target, buildSkillContent(skillName, requireString(body.description, "description"), typeof body.whenToUse === "string" ? body.whenToUse : void 0, typeof body.content === "string" ? body.content : ""), "utf8");
+	return {
+		ok: true,
+		name: skillName,
+		path: target
+	};
+}
+/** The delete handler: move the skill directory into a recoverable trash. */
+async function handleDelete(deps, body, cwd) {
+	const path = await resolveSkillPath(deps, requireString(body.name, "name"), body, cwd);
+	if (!existsSync(path)) throw new Error("skill file not found");
+	const dir = dirname(path);
+	const trash = join(dirname(dir), ".trash", String(Date.now()) + "-" + (body.name === void 0 ? "skill" : String(body.name)));
+	await mkdir(dirname(trash), { recursive: true });
+	await rename(dir, trash);
+	return {
+		ok: true,
+		moved: trash
+	};
+}
+/** The workspace a request is about: its own `cwd` query, else the first active session's. */
+function currentCwd(deps, req) {
+	try {
+		const asked = new URL(req.url ?? "/", "http://localhost").searchParams.get("cwd");
+		if (asked !== null && asked !== "") return asked;
+	} catch {}
+	return deps.activeSessionCwds()[0] ?? process.cwd();
+}
+/** One required string field. */
+function requireString(value, field) {
+	if (typeof value !== "string" || value === "") throw new Error("missing " + field);
+	return value;
+}
+/**
+* The absolute file path a write should touch.
+*
+* A caller-supplied path is honoured so the panel can act on the exact file it
+* listed; otherwise the registry resolves it, which is also what rejects a
+* skill the registry does not know.
+* @param deps - the route dependencies.
+* @param name - the skill name.
+* @param body - the request body, which may carry an explicit path.
+* @param cwd - the workspace the caller is viewing.
+* @returns the resolved path.
+* @throws when the skill has no file (a virtual or runtime-registered skill).
+*/
+async function resolveSkillPath(deps, name, body, cwd) {
+	if (typeof body.path === "string" && body.path !== "") return body.path;
+	const path = await deps.pathOf(name, cwd);
+	if (path === void 0) throw new Error("skill \"" + name + "\" has no file on disk");
+	return path;
+}
+/**
+* Build the skill-center routes.
+* @param deps - resolved roots, the registry snapshot, and the session list.
+* @returns the routes for `ctx.webServer.register`.
+*/
+function makeRoutes(deps) {
+	return [
+		{
+			kind: "exact",
+			path: ROUTES.health,
+			handler: (_req, res) => writeJson(res, 200, { ok: true })
+		},
+		{
+			kind: "exact",
+			path: ROUTES.list,
+			handler: async (req, res) => {
+				try {
+					writeJson(res, 200, await handleList(deps, currentCwd(deps, req)));
+				} catch (error) {
+					deps.logger.warn(error);
+					writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: ROUTES.setEnabled,
+			handler: async (req, res) => {
+				const cwd = currentCwd(deps, req);
+				try {
+					writeJson(res, 200, await handleSetEnabled(deps, await readJson(req, 1 << 20), cwd));
+				} catch (error) {
+					deps.logger.warn(error);
+					writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: ROUTES.create,
+			handler: async (req, res) => {
+				try {
+					writeJson(res, 200, await handleCreate(deps, await readJson(req, 1 << 20)));
+				} catch (error) {
+					deps.logger.warn(error);
+					writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: ROUTES.delete,
+			handler: async (req, res) => {
+				const cwd = currentCwd(deps, req);
+				try {
+					writeJson(res, 200, await handleDelete(deps, await readJson(req, 1 << 20), cwd));
+				} catch (error) {
+					deps.logger.warn(error);
+					writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+				}
+			}
+		}
+	];
+}
+/**
+* Mount the skill-center routes.
+* @param ctx - host context carrying `webServer`, `skills`, and `sessions`.
+* @param config - resolved plugin config.
+*/
+function apply(ctx, config = {}) {
+	const deps = {
+		dshHome: config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), ".dsh"),
+		agentsHome: config.agentsHome ?? process.env.DSH_AGENTS_HOME ?? join(homedir(), ".agents"),
+		customSkillDirs: config.customSkillDirs ?? [],
+		snapshotProject: (cwd) => ctx.skills.snapshot({ cwd }).then((s) => ({
+			skills: s.skills,
+			complete: s.complete
+		})),
+		pathOf: async (name, cwd) => (await ctx.skills.get(name, { cwd }))?.path,
+		activeSessionCwds: () => ctx.sessions.list().map((s) => s.header.cwd).filter((c) => typeof c === "string" && c !== ""),
+		logger: { warn: (error) => {
+			ctx.logger.warn(error);
+		} }
+	};
+	for (const route of makeRoutes(deps)) ctx.effect(() => ctx.webServer.register(route), "ui-skill-center: route " + route.path);
+}
+//#endregion
+export { ROUTES, apply, buildSkillContent, findProjectRoot, inject, levelOfSource, makeRoutes, name, projectSkillRoot, readDisabledFlag, userSkillRoot, withDisabledFlag };

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

@@ -0,0 +1,23 @@
+/**
+ * Skill center page. Browses the loaded skills grouped by source, toggles model
+ * invocation, creates a skill, and deletes one into a recoverable trash.
+ *
+ * The header, rows, and glyph frame follow the official plugin panel's layout so
+ * the page reads as one of the shell's own.
+ *
+ * @module @sparkelf/dsh-client-ui-skill-center/client/SkillCenterPage
+ */
+import { type ReactNode } from 'react';
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SkillCenterLocaleKey } from './locales.ts';
+/** What the panel needs from its slot: the dictionary resolver. */
+export interface SkillCenterPageProps {
+    t(key: SkillCenterLocaleKey): string;
+}
+/**
+ * The skill center panel.
+ * @param props - the slot's runtime share, providing the dictionary resolver.
+ * @returns the rendered panel.
+ */
+export declare function SkillCenterPage({ t }: PropsRuntime<'main'> & SkillCenterPageProps): ReactNode;
+//# sourceMappingURL=SkillCenterPage.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * The sidebar's Skill Center glyph.
+ *
+ * The icon comes from the shared primitives library, so the row matches every
+ * other sidebar entry instead of carrying a hand-drawn SVG.
+ *
+ * @module @sparkelf/dsh-client-ui-skill-center/client/SkillCenterPanelIcon
+ */
+import type { ReactNode } from 'react';
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/**
+ * Render the glyph at the size the sidebar asks for.
+ * @param props - the sidebar's icon share: requested edge and selected state.
+ * @returns the icon element.
+ */
+export declare function SkillCenterPanelIcon({ size }: PropsRuntime<'sidebar.panellist'>): ReactNode;
+//# sourceMappingURL=SkillCenterPanelIcon.d.ts.map

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

@@ -0,0 +1,75 @@
+/**
+ * Skill center API client. Talks to the host route family over same-origin
+ * fetch; the host owns the trust fence.
+ *
+ * @module @sparkelf/dsh-client-ui-skill-center/client/api
+ */
+/** One skill entry as the host serves it. */
+export interface SkillEntry {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    provider?: string;
+    level: string;
+    path?: string;
+    /** True when discovered through a symlink; deletion is refused. */
+    linked?: boolean;
+    modelInvocable: boolean;
+    userInvocable: boolean;
+    workspaceRoot?: string;
+    workspaceName?: string;
+    isActiveWorkspace?: boolean;
+}
+/** One group as the host serves it. */
+export interface GroupPayload {
+    key: string;
+    title: string;
+    hint: string;
+    skills: SkillEntry[];
+}
+/** One selectable workspace. */
+export interface WorkspaceItem {
+    root: string;
+    name: string;
+    active: boolean;
+}
+/** The list route's payload. */
+export interface ListPayload {
+    cwd: string;
+    projectRoots: string[];
+    complete: boolean;
+    groups: GroupPayload[];
+    workspaces?: WorkspaceItem[];
+}
+/** One thrown API error carrying the host's message. */
+export declare class ApiError extends Error {
+}
+/** Skill center API client. */
+export declare class SkillApi {
+    /** Fetch the grouped skill list. */
+    list(cwd?: string): Promise<ListPayload>;
+    /** Enable or disable a skill by rewriting its frontmatter flag. */
+    setEnabled(name: string, path: string, enabled: boolean): Promise<{
+        name: string;
+        enabled: boolean;
+    }>;
+    /** Create a skill file under the user or project root. */
+    create(payload: {
+        root: 'user' | 'project';
+        name: string;
+        description: string;
+        whenToUse?: string;
+        content?: string;
+    }): Promise<{
+        ok: true;
+        name: string;
+        path: string;
+    }>;
+    /** Delete a skill by moving it into the recoverable trash. */
+    remove(name: string, path: string): Promise<{
+        ok: true;
+        moved: string;
+    }>;
+    private request;
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Skill center — browser half. Contributes the sidebar entry and the panel it
+ * opens through the same official slots the Plugins panel uses: a
+ * `sidebar.panellist` row and a keyed `main` page, with the sidebar shell
+ * owning the button, label, and selected state around the glyph.
+ *
+ * @module @sparkelf/dsh-client-ui-skill-center/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MainPanelId } from '@deepseek-ai/dsh-client-ui-layout/client';
+import { type SkillCenterLocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Skill center panel copy. */
+        'skillCenter': SkillCenterLocaleKey;
+    }
+}
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "skillCenter";
+/** The id shared by the sidebar entry and the main panel it opens. */
+export declare const PANEL_ID: MainPanelId;
+/** Services required by the sidebar and page registrations. */
+export declare const inject: string[];
+/**
+ * Contribute the Skill Center entry and the page it opens.
+ * @param ctx - the browser plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * Skill center dictionaries. Keys are typed so the panel and the sidebar entry
+ * cannot reference a string that does not exist in both languages.
+ *
+ * @module @sparkelf/dsh-client-ui-skill-center/client/locales
+ */
+/** Every string this plugin renders. */
+export interface SkillCenterLocale {
+    'panel': string;
+    'panel.intro': string;
+    'search.placeholder': string;
+    'search.clear': string;
+    'search.noMatches': string;
+    'action.refresh': string;
+    'action.create': string;
+    'action.delete': string;
+    'action.cancel': string;
+    'action.confirm': string;
+    'state.loading': string;
+    'state.empty': string;
+    'state.failed': string;
+    'skill.enabled': string;
+    'skill.disabled': string;
+    'skill.modelInvocable': string;
+    'skill.userInvocable': string;
+    'skill.linked': string;
+    'create.title': string;
+    'create.name': string;
+    'create.description': string;
+    'create.whenToUse': string;
+    'create.content': string;
+    'create.root': string;
+    'create.rootUser': string;
+    'create.rootProject': string;
+    'delete.confirm': string;
+}
+/** Locale keys, for callers that resolve them dynamically. */
+export type SkillCenterLocaleKey = keyof SkillCenterLocale;
+/** Simplified Chinese dictionary. */
+export declare const zh: SkillCenterLocale;
+/** English dictionary. */
+export declare const en: SkillCenterLocale;
+//# sourceMappingURL=locales.d.ts.map