dsh-skill-hub 0.3.27 → 0.3.28

package/lib/index.js

@@ -1,11 +1,11 @@
 import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
-import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { isSkillName } from "@deepseek-ai/dsh-skill";
 import { dump, load } from "js-yaml";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/protocol/api.ts
 /**
 * Root path of the skill-hub API family. The host also registers this as its
@@ -56,9 +56,40 @@ const SKILL_HUB_API = {
 	sourceTrashClear: "/api/skill-hub/sources/trash/clear",
 	diagnosticFix: "/api/skill-hub/diagnostic/fix",
 	marketSourceVersions: "/api/skill-hub/market/source/versions",
-	marketStats: "/api/skill-hub/market/stats"
+	marketStats: "/api/skill-hub/market/stats",
+	foreign: "/api/skill-hub/foreign",
+	foreignImport: "/api/skill-hub/foreign/import"
 };
 //#endregion
+//#region src/protocol/catalog.ts
+/**
+* 技能目录的建议字符预算。取 8000：这是 Codex 在上下文窗口未知时对初始
+* 技能清单的硬上限，也是目前公开客户端里最保守的一档。超出后尾部条目会被
+* 静默丢弃（技能看起来装了，实际不触发）。
+*/
+const ANNOUNCEMENT_CHAR_BUDGET = 8e3;
+/**
+* 按「已启用且模型可调用」的技能估算公告成本。只统计一层渐进加载真正注入的
+* 字段（name + description + whenToUse），不含正文 —— 正文是激活后才载入的，
+* 不占常驻预算。
+*/
+function computeAnnouncementBudget(skills) {
+	let chars = 0;
+	let count = 0;
+	for (const skill of skills) {
+		if (!skill.invocation.modelInvocable) continue;
+		count += 1;
+		chars += skill.name.length + skill.description.length + (skill.whenToUse?.length ?? 0);
+	}
+	return {
+		skills: count,
+		chars,
+		approxTokens: Math.ceil(chars / 3),
+		budget: ANNOUNCEMENT_CHAR_BUDGET,
+		overBudget: chars > ANNOUNCEMENT_CHAR_BUDGET
+	};
+}
+//#endregion
 //#region src/protocol/config.ts
 /**
 * This plugin's Loader entry id — the settings namespace dsh serves its config
@@ -313,6 +344,7 @@ function hydrateMigratedState(migrated) {
 		const source = entry;
 		if (source !== null && typeof source === "object" && typeof source.repo === "string" && source.repo !== "" && Array.isArray(source.skills)) {
 			const manifest = source.manifest;
+			const localHashes = source.localHashes;
 			const rawRoot = isValidRepoRoot(source.root) ? source.root : "skills";
 			sourcesByRepo.set(source.repo, {
 				repo: source.repo,
@@ -320,7 +352,8 @@ function hydrateMigratedState(migrated) {
 				root: rawRoot,
 				commitSha: typeof source.commitSha === "string" ? source.commitSha : "",
 				skills: source.skills.filter((n) => typeof n === "string"),
-				...manifest !== null && typeof manifest === "object" && !Array.isArray(manifest) ? { manifest: Object.fromEntries(Object.entries(manifest).filter(([, size]) => typeof size === "number")) } : {}
+				...manifest !== null && typeof manifest === "object" && !Array.isArray(manifest) ? { manifest: Object.fromEntries(Object.entries(manifest).filter(([, size]) => typeof size === "number")) } : {},
+				...localHashes !== null && typeof localHashes === "object" && !Array.isArray(localHashes) ? { localHashes: Object.fromEntries(Object.entries(localHashes).filter(([, hash]) => typeof hash === "string" && hash !== "")) } : {}
 			});
 		}
 	}
@@ -978,10 +1011,22 @@ var SkillHubStore = class {
 		if (existing === void 0) return void 0;
 		const names = [...new Set(skills.filter((n) => n.trim() !== ""))].sort((a, b) => a.localeCompare(b));
 		if (names.length === 0) this.sourcesByRepo.delete(repo);
-		else this.sourcesByRepo.set(repo, {
-			...existing,
-			skills: names
-		});
+		else {
+			const next = {
+				...existing,
+				skills: names
+			};
+			if (existing.localHashes !== void 0) {
+				const localHashes = {};
+				for (const name of names) {
+					const hash = existing.localHashes[name];
+					if (hash !== void 0) localHashes[name] = hash;
+				}
+				if (Object.keys(localHashes).length > 0) next.localHashes = localHashes;
+				else delete next.localHashes;
+			}
+			this.sourcesByRepo.set(repo, next);
+		}
 		await this.persist();
 		return this.sourcesByRepo.get(repo);
 	}
@@ -993,10 +1038,17 @@ var SkillHubStore = class {
 			if (!source.skills.includes(name)) continue;
 			const skills = source.skills.filter((n) => n !== name);
 			if (skills.length === 0) this.sourcesByRepo.delete(repo);
-			else this.sourcesByRepo.set(repo, {
-				...source,
-				skills
-			});
+			else {
+				const localHashes = {};
+				for (const [key, value] of Object.entries(source.localHashes ?? {})) if (key !== name) localHashes[key] = value;
+				const next = {
+					...source,
+					skills
+				};
+				if (Object.keys(localHashes).length > 0) next.localHashes = localHashes;
+				else delete next.localHashes;
+				this.sourcesByRepo.set(repo, next);
+			}
 			changed = true;
 		}
 		if (changed) await this.persist();
@@ -1012,6 +1064,24 @@ var SkillHubStore = class {
 		});
 		await this.persist();
 	}
+	/**
+	* Record one skill's local content hash (sampled right after the bytes land).
+	* This is the only thing that can tell "the user edited this" apart from
+	* "upstream moved", so it is written on every import and every sync.
+	*/
+	async setSourceSkillHash(repo, skillName, hash) {
+		await this.ensureLoaded();
+		const existing = this.sourcesByRepo.get(repo);
+		if (existing === void 0 || hash === "") return;
+		this.sourcesByRepo.set(repo, {
+			...existing,
+			localHashes: {
+				...existing.localHashes ?? {},
+				[skillName]: hash
+			}
+		});
+		await this.persist();
+	}
 	/** Update a source's pinned ref (release tag / branch) when the market syncs. */
 	async setSourceRef(repo, ref) {
 		await this.ensureLoaded();
@@ -1399,6 +1469,199 @@ function rootOfPath(path, home = dshHome()) {
 	}
 }
 //#endregion
+//#region src/skillfs/audit.ts
+/** 单文件字节上限：技能是纯文本加少量脚本，2 MiB 已远超正常体积。 */
+const MAX_SKILL_FILE_BYTES = 2 * 1024 * 1024;
+/** 单个技能总字节上限。 */
+const MAX_SKILL_BUNDLE_BYTES = 10 * 1024 * 1024;
+/** agentskills.io 规范对 description 的硬上限。 */
+const MAX_DESCRIPTION_CHARS = 1024;
+/** 裸 ESC —— 终端转义注入（CWE-150）的起点，正常技能正文不含。 */
+const ANSI_RE = /\u001B/;
+/** Unicode 标签字符区，唯一用途是承载不可见文本。 */
+const UNICODE_TAG_RE = /[\u{E0000}-\u{E007F}]/u;
+/** 双向控制符：Trojan Source 式视觉重排。 */
+const BIDI_RE = /[\u202A-\u202E\u2066-\u2069]/;
+/** 零宽字符：可能来自从网页复制的正文，也可能用于隐藏内容。 */
+const ZERO_WIDTH_RE = /[\u200B-\u200D\u2060\uFEFF]/;
+/**
+* 危险命令：只匹配「下载后直接执行」这一族，也就是审计报告里出现频率最高、
+* 且人类肉眼最容易滑过去的那几种形态。普通的 `curl URL` 取数据不在此列。
+*/
+const DANGEROUS_COMMANDS = [
+	{
+		re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b/,
+		label: "remote script piped straight into a shell"
+	},
+	{
+		re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?python[0-9.]*\b/,
+		label: "remote script piped straight into python"
+	},
+	{
+		re: /\bbase64\s+(?:-d|--decode)\b[^\n|]*\|\s*(?:ba|z|k)?sh\b/,
+		label: "base64 payload decoded into a shell"
+	},
+	{
+		re: /\beval\s+["']?\$\(\s*(?:curl|wget)\b/,
+		label: "eval of a downloaded command"
+	},
+	{
+		re: /\bnc\b[^\n]*\s-e\s/,
+		label: "netcat with command execution"
+	},
+	{
+		re: /\/dev\/tcp\//,
+		label: "raw TCP socket via /dev/tcp"
+	}
+];
+/** 凭据路径：技能正文提到这些路径本身未必有恶意，但值得让人看一眼上下文。 */
+const CREDENTIAL_PATHS = [
+	{
+		re: /(?:^|[\s"'`/])\.ssh\/id_(?:rsa|dsa|ecdsa|ed25519)\b/,
+		label: "SSH private key"
+	},
+	{
+		re: /(?:^|[\s"'`/])\.aws\/credentials\b/,
+		label: "AWS credentials file"
+	},
+	{
+		re: /(?:^|[\s"'`/])\.netrc\b/,
+		label: "netrc credentials file"
+	},
+	{
+		re: /Library\/Keychains\b/,
+		label: "macOS keychain"
+	},
+	{
+		re: /(?:^|[\s"'`])\.docker\/config\.json\b/,
+		label: "Docker registry credentials"
+	},
+	{
+		re: /(?:^|\s)\/etc\/shadow\b/,
+		label: "system password database"
+	}
+];
+/** 1 起行号（按 `\n` 计）。 */
+function lineOf(text, index) {
+	let line = 1;
+	const end = Math.min(index, text.length);
+	for (let i = 0; i < end; i += 1) if (text.charCodeAt(i) === 10) line += 1;
+	return line;
+}
+/** 首个匹配位置与总数。每次新建带 `g` 的正则，避免 lastIndex 跨调用残留。 */
+function collect$1(text, re) {
+	const global = new RegExp(re.source, "gu");
+	let first = -1;
+	let count = 0;
+	let match;
+	while ((match = global.exec(text)) !== null) {
+		if (first === -1) first = match.index;
+		count += 1;
+		if (match[0].length === 0) global.lastIndex += 1;
+	}
+	return {
+		first,
+		count
+	};
+}
+/**
+* 审计一段技能文本（SKILL.md 正文、脚本、参考文档都适用）。
+* 纯函数：同样的输入永远给同样的结果，便于单测与「改动前后对比」。
+*/
+function auditSkillText(relativePath, text) {
+	const findings = [];
+	const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+	const push = (rule, severity, message, index) => {
+		findings.push({
+			rule,
+			severity,
+			file: relativePath,
+			line: lineOf(body, index),
+			message
+		});
+	};
+	if (ANSI_RE.test(body)) push("ansi-escape", "block", "contains a raw ESC control character — it can rewrite what a terminal displays (escape-sequence injection, CWE-150)", body.search(ANSI_RE));
+	const tags = collect$1(body, UNICODE_TAG_RE);
+	if (tags.count > 0) push("unicode-tag", "block", `contains ${tags.count} invisible Unicode tag character(s); text hidden there is not rendered by any editor, so a reviewer cannot see what the agent reads`, tags.first);
+	const bidi = collect$1(body, BIDI_RE);
+	if (bidi.count > 0) push("bidi-control", "block", `contains ${bidi.count} bidirectional control character(s); they can make the file read differently than it executes`, bidi.first);
+	const zeroWidth = collect$1(body, ZERO_WIDTH_RE);
+	if (zeroWidth.count > 0) push("zero-width", "warn", `contains ${zeroWidth.count} zero-width character(s); usually a copy-paste artifact, but they can also split a keyword so a reviewer's search misses it`, zeroWidth.first);
+	for (const { re, label } of DANGEROUS_COMMANDS) {
+		const hit = re.exec(body);
+		if (hit !== null && hit.index !== void 0) {
+			push("dangerous-command", "warn", `contains ${label}: \`${hit[0].trim().slice(0, 120)}\``, hit.index);
+			break;
+		}
+	}
+	for (const { re, label } of CREDENTIAL_PATHS) {
+		const hit = re.exec(body);
+		if (hit !== null && hit.index !== void 0) {
+			push("credential-path", "warn", `references ${label}; check the surrounding instructions actually need it`, hit.index);
+			break;
+		}
+	}
+	return findings;
+}
+/** description 超出规范上限：部分客户端会截断，技能因此静默失去自动激活能力。 */
+function auditDescription(file, description) {
+	if (description.length <= 1024) return [];
+	return [{
+		rule: "description-too-long",
+		severity: "warn",
+		file,
+		message: `description is ${description.length} chars; the Agent Skills spec caps it at ${MAX_DESCRIPTION_CHARS} and longer ones get truncated by clients, which silently stops the skill from auto-activating`
+	}];
+}
+/**
+* 审计一个完整技能目录：体积/数量上限 + 每个文本文件的规则扫描。
+* `block` 级发现（体积越界）意味着不该落盘；文本级 `block` 由调用方决定。
+*/
+function auditSkillBundle(files, description) {
+	const findings = [];
+	if (files.length > 500) findings.push({
+		rule: "too-many-files",
+		severity: "block",
+		file: ".",
+		message: `skill has ${files.length} files; the hub imports at most 500 per skill`
+	});
+	const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+	if (totalBytes > 10485760) findings.push({
+		rule: "bundle-too-large",
+		severity: "block",
+		file: ".",
+		message: `skill is ${formatBytes(totalBytes)} in total; the hub imports at most ${formatBytes(MAX_SKILL_BUNDLE_BYTES)} per skill`
+	});
+	for (const file of files) {
+		if (file.size > 2097152) {
+			findings.push({
+				rule: "file-too-large",
+				severity: "block",
+				file: file.path,
+				message: `${formatBytes(file.size)} is over the ${formatBytes(MAX_SKILL_FILE_BYTES)} per-file limit`
+			});
+			continue;
+		}
+		if (file.text !== void 0) findings.push(...auditSkillText(file.path, file.text));
+	}
+	if (description !== void 0) findings.push(...auditDescription("SKILL.md", description));
+	return findings;
+}
+/** 阻断性发现的单行摘要（导入失败时的错误文本）。 */
+function blockingReason(findings) {
+	const blocked = findings.filter((finding) => finding.severity === "block");
+	if (blocked.length === 0) return void 0;
+	const head = blocked.slice(0, 3).map((finding) => `${finding.file}${finding.line !== void 0 ? ":" + String(finding.line) : ""} ${finding.message}`);
+	const rest = blocked.length > head.length ? ` (+${blocked.length - head.length} more)` : "";
+	return "skill rejected by content audit: " + head.join("; ") + rest;
+}
+/** 字节数的人读形式（诊断文案用）。 */
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+//#endregion
 //#region src/concurrency.ts
 /**
 * 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
@@ -1594,6 +1857,14 @@ async function scanDiagnostics(root, home = dshHome()) {
 			});
 			return found;
 		}
+		const auditFindings = [...auditSkillText(basename(entry.path), text), ...auditDescription(basename(entry.path), parsed.value.description)];
+		for (const finding of auditFindings) found.push({
+			path: entry.path,
+			root,
+			reason: (finding.line !== void 0 ? `line ${finding.line}: ` : "") + finding.message,
+			kind: "security",
+			severity: finding.severity
+		});
 		if (repairFrontmatterFileText(text) !== null) found.push({
 			path: entry.path,
 			root,
@@ -1678,6 +1949,302 @@ async function occupancyOf(base, name) {
 	return result;
 }
 //#endregion
+//#region src/skillfs/hash.ts
+/**
+* 技能内容哈希：给「本地这份技能到底有没有被改过」一个确定答案。
+*
+* 现有来源记录只存上游的 commit 与按路径的字节数基线，能回答「上游变没变」，
+* 回答不了「磁盘上这份还是不是我当初导入的那份」。于是「一键全更」只能盲覆盖，
+* 用户唯一的保护是弹窗里那句他自己也判断不了的「会覆盖本地修改」。
+*
+* 哈希的粒度是**整个技能**（目录包 = 目录下全部文件；扁平技能 = 那一个文件），
+* 而不是单文件：用户改的是「这个技能」，不是「这个技能里的第 3 个文件」。
+*
+* 边界（与体积审计同一套取舍）：技能是纯文本加少量脚本，正常体积在几十 KB。
+* 走查上限存在的意义是「一个恶意或事故性的巨大目录不能把 /catalog 拖死」，
+* 不是为了支持大包。
+*/
+/** 单个技能参与哈希的文件数上限；超出部分不参与（并在结果里体现为截断）。 */
+const MAX_FILES = 2e3;
+/** 目录走查深度上限。 */
+const MAX_DEPTH = 8;
+/** 超过这个大小的文件不读内容，只把大小计入（避免一次同步卡在几个大二进制上）。 */
+const MAX_HASH_BYTES = 8 * 1024 * 1024;
+/** 递归收集相对路径与大小。符号链接不跟随（lstat），避免指到目录外。 */
+async function collect(dir, depth, out) {
+	if (depth > MAX_DEPTH || out.length >= MAX_FILES) return;
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch {
+		return;
+	}
+	names.sort();
+	for (const name of names) {
+		if (out.length >= MAX_FILES) return;
+		if (name === ".git" || name === ".trash") continue;
+		const absolute = join(dir, name);
+		let info;
+		try {
+			info = await lstat(absolute);
+		} catch {
+			continue;
+		}
+		if (info.isSymbolicLink()) continue;
+		if (info.isDirectory()) await collect(absolute, depth + 1, out);
+		else if (info.isFile()) out.push({
+			path: relative(dir, absolute),
+			size: info.size,
+			absolute
+		});
+	}
+}
+/** 把一组 (相对路径, 大小, 内容摘要) 折叠成一个十六进制摘要。 */
+function fold(entries) {
+	const digest = createHash("sha256");
+	for (const entry of [...entries].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+		digest.update(entry.path);
+		digest.update("\0");
+		digest.update(String(entry.size));
+		digest.update("\0");
+		digest.update(entry.digest);
+		digest.update("\0");
+	}
+	return digest.digest("hex");
+}
+/** 单文件内容摘要；不可读或过大时给一个稳定占位符。 */
+async function digestFile(absolute, size) {
+	if (size > MAX_HASH_BYTES) return "oversize";
+	try {
+		return createHash("sha256").update(await readFile(absolute)).digest("hex");
+	} catch {
+		return "unreadable";
+	}
+}
+/**
+* 一个技能目录的内容哈希。目录不可读时返回 undefined（调用方据此跳过比对，
+* 而不是把它当成「改过了」—— 读不到不等于变了）。
+*/
+async function hashSkillDirectory(dir) {
+	const collected = [];
+	await collect(dir, 0, collected);
+	if (collected.length === 0) return void 0;
+	const entries = [];
+	for (const file of collected) entries.push({
+		path: file.path,
+		size: file.size,
+		digest: await digestFile(file.absolute, file.size)
+	});
+	return fold(entries);
+}
+/**
+* 从一个发现文件推断技能形态并算哈希：`SKILL.md`（含 `.disabled` 变体）是
+* 目录包，其余 `<name>.md` 是扁平技能。两种形态共用同一个返回契约。
+*/
+async function hashSkillAt(discoveryPath) {
+	const file = basename(discoveryPath).replace(/\.disabled$/, "");
+	if (file === "SKILL.md") return hashSkillDirectory(dirname(discoveryPath));
+	try {
+		const info = await lstat(discoveryPath);
+		if (!info.isFile()) return void 0;
+		return fold([{
+			path: file,
+			size: info.size,
+			digest: await digestFile(discoveryPath, info.size)
+		}]);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/skillfs/foreign.ts
+/**
+* 外部 agent 技能的只读发现与收编。
+*
+* SKILL.md 已经是跨 agent 的事实标准（Claude Code / Codex / Cursor / Gemini CLI
+* 等 45+ 产品读同一份文件），但**发现路径各家不同**。于是「我在 Claude Code 里
+* 调好的技能」在 dsh 里看不见，用户只能手工复制目录。
+*
+* 这里只做两件事：读（列出别处有什么）和复制（把选中的收编到本地可写根）。
+* 外部目录一律**只读**，绝不改写 —— 那是别的 agent 的资产。
+*/
+/**
+* 常见 agent 的用户级技能目录。`~/.agents/skills` 不在此列 —— 那是 hub 自己的
+* 可写根（user-agents），重复列会让同一个技能出现两次。
+* 路径取自 vercel-labs/skills 的 agent 注册表，只保留桌面端常见的几个。
+*/
+function foreignRoots(userHome) {
+	return [
+		{
+			agent: "claude-code",
+			dir: join(userHome, ".claude", "skills")
+		},
+		{
+			agent: "codex",
+			dir: join(userHome, ".codex", "skills")
+		},
+		{
+			agent: "cursor",
+			dir: join(userHome, ".cursor", "skills")
+		},
+		{
+			agent: "gemini-cli",
+			dir: join(userHome, ".gemini", "skills")
+		},
+		{
+			agent: "copilot",
+			dir: join(userHome, ".copilot", "skills")
+		},
+		{
+			agent: "opencode",
+			dir: join(userHome, ".config", "opencode", "skills")
+		},
+		{
+			agent: "goose",
+			dir: join(userHome, ".config", "goose", "skills")
+		}
+	];
+}
+/**
+* 扫描所有外部根。解析不出 frontmatter 的条目直接跳过 —— 它们在任何 agent 里
+* 都不会生效，列出来只会让人以为「导入就好了」。
+*/
+async function scanForeignSkills(userHome, existing = /* @__PURE__ */ new Set()) {
+	const found = [];
+	for (const root of foreignRoots(userHome)) for (const entry of await scanRoot(root.dir)) {
+		let text;
+		try {
+			text = await readFile(entry.path, "utf8");
+		} catch {
+			continue;
+		}
+		const parsed = parseFrontmatter(text);
+		if ("error" in parsed) continue;
+		const name = entry.kind === "directory" ? basename(entry.directory) : basename(entry.path, ".md");
+		found.push({
+			name,
+			description: parsed.value.description,
+			agent: root.agent,
+			path: entry.path,
+			directory: entry.directory,
+			kind: entry.kind,
+			existing: existing.has(name)
+		});
+	}
+	return found.sort((a, b) => a.name === b.name ? a.agent.localeCompare(b.agent) : a.name.localeCompare(b.name));
+}
+/**
+* 递归列文件。符号链接不跟随（lstat）：一个指向 `~/.ssh` 的链接不该因为
+* 「用户点了导入」就被复制进技能目录。
+*/
+async function walk(dir, base, depth, out) {
+	if (depth > 8 || out.length >= 500) return;
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch {
+		return;
+	}
+	names.sort();
+	for (const name of names) {
+		if (out.length >= 500) return;
+		if (name === ".git") continue;
+		const absolute = join(dir, name);
+		let info;
+		try {
+			info = await lstat(absolute);
+		} catch {
+			continue;
+		}
+		if (info.isSymbolicLink()) continue;
+		if (info.isDirectory()) await walk(absolute, base, depth + 1, out);
+		else if (info.isFile()) out.push({
+			path: relative(base, absolute),
+			absolute,
+			size: info.size
+		});
+	}
+}
+async function collectForCopy(skill) {
+	if (skill.kind === "flat") {
+		const info = await lstat(skill.path);
+		return [{
+			path: basename(skill.path),
+			absolute: skill.path,
+			size: info.size
+		}];
+	}
+	const out = [];
+	await walk(skill.directory, skill.directory, 0, out);
+	return out;
+}
+/** 文本文件的判定与市场导入一致：无 NUL、解码无替换字符。 */
+function asText(buffer) {
+	if (buffer.includes(0)) return void 0;
+	const text = buffer.toString("utf8");
+	return text.includes("�") ? void 0 : text;
+}
+/**
+* 把一个外部技能收编到 `targetRoot`（通常是 `~/.dsh/skills`）。
+*
+* 与市场导入同一套闸：体积/数量上限 + 内容审计，命中阻断级直接拒绝；
+* 落盘仍是「临时目录 → 校验 → 原子 rename」，失败不留半成品。
+* 扁平技能统一落成目录包 —— hub 的所有写入路径都建目录包，两种形态并存会
+* 触发同名不可达（issue #16 那一类）。
+*/
+async function importForeignSkill(skill, targetRoot) {
+	const collected = await collectForCopy(skill);
+	if (collected.length === 0) throw new Error("skill has no files to import");
+	const audited = [];
+	const payload = [];
+	for (const file of collected) {
+		const buffer = await readFile(file.absolute);
+		const text = asText(buffer);
+		audited.push({
+			path: file.path,
+			size: buffer.length,
+			...text !== void 0 ? { text } : {}
+		});
+		payload.push({
+			relative: file.path,
+			buffer
+		});
+	}
+	const blocked = blockingReason(auditSkillBundle(audited));
+	if (blocked !== void 0) throw new Error(blocked);
+	await mkdir(targetRoot, { recursive: true });
+	const tempDir = await mkdtemp(join(targetRoot, "." + skill.name + ".foreign-"));
+	try {
+		for (const file of payload) {
+			const target = join(tempDir, file.relative);
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, file.buffer);
+		}
+		const discovery = skill.kind === "flat" ? join(tempDir, basename(skill.path)) : join(tempDir, "SKILL.md");
+		let text;
+		try {
+			text = await readFile(discovery, "utf8");
+		} catch {
+			throw new Error("imported skill has no SKILL.md");
+		}
+		const parsed = parseFrontmatter(text);
+		if ("error" in parsed) throw new Error("imported skill rejected: " + parsed.error);
+		if (parsed.value.name !== skill.name) throw new Error(`skill declares name "${parsed.value.name}", expected "${skill.name}"`);
+		if (skill.kind === "flat") {
+			await mkdir(join(tempDir, skill.name), { recursive: true });
+			await rename(discovery, join(tempDir, skill.name, "SKILL.md"));
+		}
+		const targetDir = join(targetRoot, skill.name);
+		await rename(skill.kind === "flat" ? join(tempDir, skill.name) : tempDir, targetDir);
+		return join(targetDir, "SKILL.md");
+	} finally {
+		await rm(tempDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+//#endregion
 //#region src/skillfs.ts
 /**
 * Skill filesystem operations for the writable roots and the hub provider's
@@ -2299,23 +2866,50 @@ async function downloadGitHubFile(repo, ref, path, fetchImpl = fetch, signal) {
 	}
 }
 /**
+* Treat a downloaded buffer as text when it plausibly is one: no NUL byte and
+* no U+FFFD from a failed UTF-8 decode. Binary files (icons, archives) are
+* size-checked only — running the text rules over a PNG would produce noise.
+*/
+function asAuditText(buffer) {
+	if (buffer.includes(0)) return void 0;
+	const text = buffer.toString("utf8");
+	return text.includes("�") ? void 0 : text;
+}
+/**
 * Download a full skill directory into a temporary dir, validate SKILL.md,
 * then atomically rename it into place. The target root is created when missing.
 * Callers pass a target root and a skill entry plus its collected files.
+*
+* 写盘前有两道闸：体积/数量上限（预检用 tree 的 size，落盘前再用实际字节复核）
+* 和内容审计（隐藏字符、危险命令、凭据路径）。审计的 `block` 级发现直接拒绝
+* 导入 —— 一个能藏住指令的技能不该靠用户「看得仔细」来兜底。
 */
 async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl = fetch, signal, onProgress) {
 	if (signal?.aborted) throw new DOMException("aborted", "AbortError");
+	const preflight = blockingReason(auditSkillBundle(files.map((file) => ({
+		path: relativeToSkillDir(entry.dir, file.path),
+		size: file.size
+	}))));
+	if (preflight !== void 0) throw new RepoFetchError(preflight, 422);
 	const targetDir = join(targetRoot, entry.name);
 	await mkdir(targetRoot, { recursive: true });
 	const tempDir = await mkdtemp(join(targetRoot, "." + entry.name + ".import-"));
 	let renamed = false;
 	try {
+		const audited = [];
 		await mapConcurrent(files, 6, async (file) => {
 			if (signal?.aborted) throw new DOMException("aborted", "AbortError");
 			const relative = relativeToSkillDir(entry.dir, file.path);
 			if (relative === "" || relative.includes("..")) throw new RepoFetchError("unsafe repo path: " + file.path);
 			const target = join(tempDir, relative);
 			const buffer = await downloadGitHubFile(repo, ref, file.path, fetchImpl, signal);
+			if (buffer.length > 2097152) throw new RepoFetchError(`skill rejected by content audit: ${relative} is ${buffer.length} bytes, over the per-file limit`, 422);
+			const text = asAuditText(buffer);
+			audited.push({
+				path: relative,
+				size: buffer.length,
+				...text !== void 0 ? { text } : {}
+			});
 			await mkdir(dirname(target), { recursive: true });
 			await writeFile(target, buffer);
 			onProgress?.(buffer.length, relative);
@@ -2330,6 +2924,8 @@ async function downloadRepoSkill(repo, ref, entry, files, targetRoot, fetchImpl
 		const parsed = parseFrontmatter(text);
 		if ("error" in parsed) throw new RepoFetchError("downloaded skill rejected: " + parsed.error, 422);
 		if (parsed.value.name !== entry.name) throw new RepoFetchError("downloaded skill declares name \"" + parsed.value.name + "\", expected \"" + entry.name + "\"", 422);
+		const blocked = blockingReason(auditSkillBundle(audited, parsed.value.description));
+		if (blocked !== void 0) throw new RepoFetchError(blocked, 422);
 		await rename(tempDir, targetDir);
 		renamed = true;
 		return {
@@ -2525,6 +3121,13 @@ function homeOf(deps) {
 	return deps.home ?? dshHome();
 }
 /**
+* Resolve the user's home directory — the base every other agent's user-level
+* skill folder hangs off. Distinct from `homeOf` (the DSH state root).
+*/
+function userHomeOf(deps) {
+	return deps.userHome ?? homedir();
+}
+/**
 * Resolve a skill by name as something the hub may write, or the exact
 * refusal the caller should answer with. Owns the guard sequence shared by
 * toggle, toggle-batch, and skill/delete: registry lookup, writable source,
@@ -2856,6 +3459,7 @@ async function buildCatalog(deps, cwd) {
 		skills,
 		disabled,
 		diagnostics,
+		announcement: computeAnnouncementBudget(skills),
 		...duplicateNames.length > 0 ? { duplicateNames } : {}
 	};
 }
@@ -3930,6 +4534,8 @@ function repoImportRoutes(deps) {
 							});
 							await deps.store.addSourceSkill(repo, entry.root, commitSha, resolvedRef, entry.name);
 							await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
+							const hash = await hashSkillAt(result.skillPath);
+							if (hash !== void 0) await deps.store.setSourceSkillHash(repo, entry.name, hash);
 							if (defaultTag !== void 0) await deps.store.addSkillToTag(defaultTag.id, entry.name);
 							job.imported.push({
 								name: entry.name,
@@ -4166,6 +4772,29 @@ function groupRoutes(deps) {
 * 删除 / restore 恢复 / trash/clear 清空回收站。从 routes.ts 原样搬出，
 * handler 逻辑不变。
 */
+/**
+* 本地被改过的技能：磁盘内容哈希 ≠ 导入/同步时记录的哈希。
+*
+* 只对「记录里已有哈希」的技能判定 —— 旧记录没采集过哈希，硬比会得到
+* 「全部已改」的假警报。技能目录读不到（被删/被移走）同样不算改过：
+* 那是另一种状态，由发现诊断去报。
+*/
+async function localModifiedSkills(source, home) {
+	const hashes = source.localHashes;
+	if (hashes === void 0 || Object.keys(hashes).length === 0) return [];
+	const base = rootPath("user-dsh", home);
+	const modified = [];
+	await mapConcurrent(source.skills, 8, async (name) => {
+		const expected = hashes[name];
+		if (expected === void 0) return;
+		const occupancy = await occupancyOf(base, name);
+		const path = occupancy.enabled[0] ?? occupancy.disabled[0];
+		if (path === void 0) return;
+		const actual = await hashSkillAt(path);
+		if (actual !== void 0 && actual !== expected) modified.push(name);
+	});
+	return modified.sort((a, b) => a.localeCompare(b));
+}
 /** 来源跟踪域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 function sourceRoutes(deps) {
 	return [
@@ -4206,11 +4835,14 @@ function sourceRoutes(deps) {
 				}
 				const sources = source !== void 0 ? [source] : await deps.store.listSources();
 				if (lastSourceCheck.size > 500) lastSourceCheck.clear();
+				const home = homeOf(deps);
 				const results = [];
 				for (const item of sources) {
+					const modified = await localModifiedSkills(item, home);
 					const base = {
 						repo: item.repo,
-						...item.ref !== void 0 ? { ref: item.ref } : {}
+						...item.ref !== void 0 ? { ref: item.ref } : {},
+						...modified.length > 0 ? { localModified: modified } : {}
 					};
 					const now = Date.now();
 					if (now - (lastSourceCheck.get(item.repo) ?? 0) < 3e5) {
@@ -4293,6 +4925,7 @@ function sourceRoutes(deps) {
 				const targetRoot = rootPath("user-dsh", homeOf(deps));
 				await mkdir(targetRoot, { recursive: true });
 				const synced = [];
+				const overwritten = [];
 				const failed = [];
 				for (const name of targets) {
 					if (!isSkillName(name) || !source.skills.includes(name)) {
@@ -4318,6 +4951,12 @@ function sourceRoutes(deps) {
 						const record = await deps.store.getDisabled(name);
 						const occupancy = await occupancyOf(targetRoot, name);
 						const download = () => downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot);
+						const expectedHash = source.localHashes?.[name];
+						const localPath = occupancy.enabled[0] ?? occupancy.disabled[0];
+						if (expectedHash !== void 0 && localPath !== void 0) {
+							const actualHash = await hashSkillAt(localPath);
+							if (actualHash !== void 0 && actualHash !== expectedHash) overwritten.push(name);
+						}
 						await retireNamePlaceholders(deps, targetRoot, name);
 						const enabled = occupancy.enabled[0];
 						if (enabled !== void 0) await replaceInPlace(trashSourceOf(enabled), download);
@@ -4331,6 +4970,12 @@ function sourceRoutes(deps) {
 							});
 						} else await deps.store.removeDisabled(name);
 						await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
+						const settled = await occupancyOf(targetRoot, name);
+						const settledPath = settled.enabled[0] ?? settled.disabled[0];
+						if (settledPath !== void 0) {
+							const hash = await hashSkillAt(settledPath);
+							if (hash !== void 0) await deps.store.setSourceSkillHash(repo, name, hash);
+						}
 						synced.push(name);
 					} catch (error) {
 						failed.push({
@@ -4346,6 +4991,7 @@ function sourceRoutes(deps) {
 					repo,
 					commitSha: latest.commitSha,
 					synced,
+					...overwritten.length > 0 ? { overwritten } : {},
 					failed
 				});
 			}
@@ -4536,6 +5182,134 @@ async function sweepOrphanTrash(deps, home, failed) {
 	return orphans;
 }
 //#endregion
+//#region src/routes/foreign.ts
+/**
+* 外部 agent 技能域路由：发现（只读扫描别家目录）与收编（复制进本地可写根）。
+*
+* 两条约束：
+* 1. 外部目录只读 —— 扫描不会 mkdir，也不会写任何东西到别家路径下；
+* 2. 导入不信任前端给的路径：只接受 `agent + name`，服务端重新扫一遍定位，
+*    否则一个拼出来的绝对路径就能把任意文件复制进技能目录。
+*/
+/** 判断一个外部根是否真实存在（只 stat 一次，不列目录）。 */
+async function dirExists(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function foreignRoutes(deps) {
+	return [{
+		path: SKILL_HUB_API.foreign,
+		methods: ["GET"],
+		handler: async ({ res }) => {
+			const home = homeOf(deps);
+			const userHome = userHomeOf(deps);
+			const skills = await scanForeignSkills(userHome, await knownSkillNames(deps, { includeDisabled: false }));
+			const roots = await Promise.all(foreignRoots(userHome).map(async (root) => ({
+				...root,
+				present: await dirExists(root.dir)
+			})));
+			const targetRoot = rootPath("user-dsh", home);
+			const view = await Promise.all(skills.map(async (skill) => ({
+				name: skill.name,
+				description: skill.description,
+				agent: skill.agent,
+				path: skill.path,
+				kind: skill.kind,
+				existing: skill.existing || await pathExists(join(targetRoot, skill.name, "SKILL.md")) || await pathExists(join(targetRoot, skill.name + ".md"))
+			})));
+			writeJson(res, 200, {
+				ok: true,
+				roots: roots.filter((root) => root.present),
+				skills: view
+			});
+		}
+	}, {
+		path: SKILL_HUB_API.foreignImport,
+		methods: ["POST"],
+		jsonBody: true,
+		handler: async ({ res, body }) => {
+			const items = Array.isArray(body.items) ? body.items : [];
+			if (items.length === 0) {
+				writeError(res, 400, "items must be a non-empty array");
+				return;
+			}
+			if (items.length > 100) {
+				writeError(res, 400, "import at most 100 skills per request");
+				return;
+			}
+			const home = homeOf(deps);
+			const available = await scanForeignSkills(userHomeOf(deps), await knownSkillNames(deps, { includeDisabled: false }));
+			const targetRoot = rootPath("user-dsh", home);
+			await mkdir(targetRoot, { recursive: true });
+			const imported = [];
+			const replaced = [];
+			const skipped = [];
+			const failed = [];
+			const seen = /* @__PURE__ */ new Set();
+			for (const raw of items) {
+				const item = raw;
+				const agent = item !== null && typeof item.agent === "string" ? item.agent : "";
+				const name = item !== null && typeof item.name === "string" ? item.name : "";
+				if (agent === "" || name === "") {
+					failed.push({
+						name,
+						error: "agent and name are required"
+					});
+					continue;
+				}
+				if (seen.has(agent + "/" + name)) continue;
+				seen.add(agent + "/" + name);
+				const skill = available.find((candidate) => candidate.agent === agent && candidate.name === name);
+				if (skill === void 0) {
+					failed.push({
+						name,
+						error: "skill not found under " + agent
+					});
+					continue;
+				}
+				if (skill.existing) {
+					skipped.push({
+						name,
+						reason: "a skill with this name already exists"
+					});
+					continue;
+				}
+				const occupancy = await occupancyOf(targetRoot, name);
+				if (occupancy.enabled.length > 0) {
+					skipped.push({
+						name,
+						reason: "a skill with this name already exists"
+					});
+					continue;
+				}
+				if (occupancy.disabled.length > 0 || occupancy.bareDir !== void 0) {
+					if (await retireNamePlaceholders(deps, targetRoot, name) !== void 0) replaced.push(name);
+				}
+				try {
+					await importForeignSkill(skill, targetRoot);
+					imported.push(name);
+				} catch (error) {
+					failed.push({
+						name,
+						error: errorText(error)
+					});
+				}
+			}
+			if (imported.length > 0) deps.invalidate?.();
+			writeJson(res, 200, {
+				ok: true,
+				imported,
+				...replaced.length > 0 ? { replaced } : {},
+				skipped,
+				failed
+			});
+		}
+	}];
+}
+//#endregion
 //#region src/routes.ts
 /**
 * Build the family's trust fence from the host's `/api` model.
@@ -4586,7 +5360,8 @@ function makeRoutes(deps) {
 		...marketRoutes(deps),
 		...repoImportRoutes(deps),
 		...groupRoutes(deps),
-		...sourceRoutes(deps)
+		...sourceRoutes(deps),
+		...foreignRoutes(deps)
 	].map((spec) => createRoute(deps, spec)), createRoute(deps, {
 		kind: "prefix",
 		path: SKILL_HUB_API_ROOT,
@@ -5082,7 +5857,7 @@ const CONFIG_FIELDS = [
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 152;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由受 dsh 自身的 /api 信任栅栏保护（回环、监听器绑定地址、--trusted-host 声明的 authority，外加浏览器会话认证），因此反代部署下与 GUI 同一套放行规则。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; the plugin's configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; the routes sit behind dsh's own /api trust fence (loopback, the listener's bind address, any --trusted-host authority, plus browser-session authentication), so a reverse-proxied deployment is judged exactly like the GUI around it. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
+const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；内容审计（隐藏字符、危险命令、凭据路径与体积上限；市场导入命中阻断级规则即整包拒绝）；技能目录公告预算（一层渐进加载注入的字符数与 token 估算）；本地内容哈希比对（标出被自己改过、同步会覆盖的技能）；从其他 agent 的技能目录只读导入（Claude Code / Codex / Cursor / Gemini CLI 等）；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由受 dsh 自身的 /api 信任栅栏保护（回环、监听器绑定地址、--trusted-host 声明的 authority，外加浏览器会话认证），因此反代部署下与 GUI 同一套放行规则。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; the plugin's configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics plus a content audit (hidden characters, dangerous commands, credential paths, size caps — a market import with a blocking finding is refused as a whole); the skill-catalog announcement budget (characters and estimated tokens for the first progressive-disclosure layer); local content-hash comparison (flags skills you edited that a sync would overwrite); read-only import from other agents' skill folders (Claude Code / Codex / Cursor / Gemini CLI and friends); new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; the routes sit behind dsh's own /api trust fence (loopback, the listener's bind address, any --trusted-host authority, plus browser-session authentication), so a reverse-proxied deployment is judged exactly like the GUI around it. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
 /**
 * Mount the skill hub routes and announcement.
 * @param ctx - host plugin context carrying webServer/skills/systemPrompt/settings.