dsh-skill-hub 0.3.26 → 0.3.28

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

@@ -2,7 +2,7 @@
  * Browser-side API client for the /api/skill-hub route family. The only
  * data access path the panel uses — plain fetch, same origin.
  */
-import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourceAddResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
+import { type CatalogResponse, type ConfigResponse, type CreateRequest, type CreateResponse, type DiagnosticFixResponse, type ForeignImportResponse, type ForeignListResponse, type GroupsResponse, type MarketCheckResponse, type MarketSourceAddResponse, type MarketSourcesResponse, type MarketSourceVersionsResponse, type MarketStatsResponse, type MarketSyncResponse, type RepoDiscoverResponse, type RepoImportCancelResponse, type RepoImportProgressResponse, type RepoImportResponse, type SkillDetail, type SkillDeleteResponse, type SkillTag, type SourceCheckResponse, type SourceDeleteResponse, type SourceRestoreResponse, type SourceTrashClearResponse, type SourcesResponse, type SourceSyncResponse, type StatsResponse, type TagSaveRequest, type ToggleBatchResponse, type UpdateCheckResponse } from '../protocol.ts';
 /** Error carrying the route's JSON error message. */
 export declare class SkillHubApiError extends Error {
     constructor(message: string);
@@ -93,6 +93,13 @@ export declare class SkillHubApi {
     reorderSourceGroups(orderedKeys: string[]): Promise<string[]>;
     /** 来源列表 + 派生 origin 映射 + 集合组 + 回收站。 */
     sources(): Promise<SourcesResponse>;
+    /** 列出其他 agent 用户级技能目录里的可收编技能（只读扫描）。 */
+    listForeignSkills(): Promise<ForeignListResponse>;
+    /** 收编所选外部技能到 ~/.dsh/skills。 */
+    importForeignSkills(items: Array<{
+        agent: string;
+        name: string;
+    }>): Promise<ForeignImportResponse>;
     /** 检查指定（或全部）来源的上游更新。 */
     checkSources(repo?: string): Promise<SourceCheckResponse>;
     /** 同步一个来源的所选（或全部）技能到上游最新版本。 */

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

@@ -17,6 +17,10 @@ export declare const zhCommon: {
     readonly 'legend.hint': "每个技能最多一个圆点；无圆点 = 不可被调用。";
     readonly 'panel.disabled': "已禁用";
     readonly 'panel.diagnostics': "发现诊断";
+    readonly 'panel.auditBadge': "审计";
+    readonly 'panel.announcement': "公告预算 {chars} 字符 ≈ {tokens} tokens · {skills} 个技能";
+    readonly 'panel.announcementOver': "超出建议上限 {budget} 字符，排在后面的技能可能不触发";
+    readonly 'panel.announcementHint': "技能目录的第一层（name + description）常驻在 system prompt 里。建议不超 {budget} 字符 —— 超出后客户端会截断尾部条目，表现为「装了却不触发」。";
     readonly 'panel.empty': "没有匹配的技能。";
     readonly 'panel.emptyAll': "本地还没有技能。点击「新建技能」创建第一个。";
     readonly 'panel.loading': "读取中…";

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

@@ -79,5 +79,15 @@ export declare const zhMarket: {
     readonly 'repo.root.skills': "skills";
     readonly 'repo.root.designTemplates': "design-templates";
     readonly 'repo.root.generic': "{root}";
+    readonly 'foreign.open': "从其他 Agent 导入";
+    readonly 'foreign.title': "从其他 Agent 导入";
+    readonly 'foreign.text': "读取 Claude Code / Codex / Cursor 等工具的用户级技能目录（只读），把所选技能复制到 ~/.dsh/skills。原目录不受影响。";
+    readonly 'foreign.empty': "没有在这些工具的技能目录里发现技能。";
+    readonly 'foreign.exists': "已存在";
+    readonly 'foreign.import': "导入所选（{count}）";
+    readonly 'foreign.importing': "导入中…";
+    readonly 'foreign.skipped': "{count} 个因同名已存在被跳过。";
+    readonly 'foreign.importedBanner': "已导入 {count} 个技能。";
+    readonly 'foreign.importedReplacedBanner': "已导入 {count} 个技能，另有 {replaced} 个同名占位被移入回收站（可恢复）。";
 };
 export declare const enMarket: Record<keyof typeof zhMarket, string>;

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

@@ -11,6 +11,9 @@ export declare const zhSources: {
     readonly 'source.checking': "检查中…";
     readonly 'source.upToDate': "已是最新";
     readonly 'source.updated': "有更新 {count} 个";
+    readonly 'source.localModified': "本地改动 {count} 个";
+    readonly 'source.localModifiedBadge': "本地已改";
+    readonly 'source.localModifiedHint': "这些技能的磁盘内容与导入/同步时不一致（你自己改过）。同步会覆盖它们。";
     readonly 'source.deleted': "上游已删除 {count} 个";
     readonly 'source.error': "检查失败";
     readonly 'source.throttled': "刚刚检查过";

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

@@ -63,6 +63,9 @@ export declare const zh: {
     readonly 'source.checking': "检查中…";
     readonly 'source.upToDate': "已是最新";
     readonly 'source.updated': "有更新 {count} 个";
+    readonly 'source.localModified': "本地改动 {count} 个";
+    readonly 'source.localModifiedBadge': "本地已改";
+    readonly 'source.localModifiedHint': "这些技能的磁盘内容与导入/同步时不一致（你自己改过）。同步会覆盖它们。";
     readonly 'source.deleted': "上游已删除 {count} 个";
     readonly 'source.error': "检查失败";
     readonly 'source.throttled': "刚刚检查过";
@@ -162,6 +165,16 @@ export declare const zh: {
     readonly 'repo.root.skills': "skills";
     readonly 'repo.root.designTemplates': "design-templates";
     readonly 'repo.root.generic': "{root}";
+    readonly 'foreign.open': "从其他 Agent 导入";
+    readonly 'foreign.title': "从其他 Agent 导入";
+    readonly 'foreign.text': "读取 Claude Code / Codex / Cursor 等工具的用户级技能目录（只读），把所选技能复制到 ~/.dsh/skills。原目录不受影响。";
+    readonly 'foreign.empty': "没有在这些工具的技能目录里发现技能。";
+    readonly 'foreign.exists': "已存在";
+    readonly 'foreign.import': "导入所选（{count}）";
+    readonly 'foreign.importing': "导入中…";
+    readonly 'foreign.skipped': "{count} 个因同名已存在被跳过。";
+    readonly 'foreign.importedBanner': "已导入 {count} 个技能。";
+    readonly 'foreign.importedReplacedBanner': "已导入 {count} 个技能，另有 {replaced} 个同名占位被移入回收站（可恢复）。";
     readonly 'edit.start': "编辑";
     readonly 'edit.hint': "开启后显示删除与排序操作";
     readonly 'edit.done': "完成";
@@ -238,6 +251,10 @@ export declare const zh: {
     readonly 'legend.hint': "每个技能最多一个圆点；无圆点 = 不可被调用。";
     readonly 'panel.disabled': "已禁用";
     readonly 'panel.diagnostics': "发现诊断";
+    readonly 'panel.auditBadge': "审计";
+    readonly 'panel.announcement': "公告预算 {chars} 字符 ≈ {tokens} tokens · {skills} 个技能";
+    readonly 'panel.announcementOver': "超出建议上限 {budget} 字符，排在后面的技能可能不触发";
+    readonly 'panel.announcementHint': "技能目录的第一层（name + description）常驻在 system prompt 里。建议不超 {budget} 字符 —— 超出后客户端会截断尾部条目，表现为「装了却不触发」。";
     readonly 'panel.empty': "没有匹配的技能。";
     readonly 'panel.emptyAll': "本地还没有技能。点击「新建技能」创建第一个。";
     readonly 'panel.loading': "读取中…";

package/lib/types/client/panel/ForeignImportDialog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 从其他 agent 导入：列出 Claude Code / Codex / Cursor / Gemini CLI 等技能目录里的
+ * 技能，勾选后复制到本地可写根。
+ *
+ * 只读扫描 + 复制，不改动别家目录。已存在的同名技能不可选（导入会覆盖，
+ * 那是用户在别处没预期的事）。
+ */
+import type { SkillHubApi } from '../api.ts';
+export interface ForeignImportDialogProps {
+    api: SkillHubApi;
+    onClose: () => void;
+    /** 导入成功后回调，由面板负责刷新目录与提示（replaced = 被移入回收站的同名占位）。 */
+    onImported: (imported: string[], replaced: number) => void;
+}
+export declare function ForeignImportDialog(props: ForeignImportDialogProps): React.JSX.Element;

package/lib/types/client/panel/PanelDialogs.d.ts

@@ -18,6 +18,8 @@ export interface PanelDialogsProps {
     confirmDialog: SkillHubState['confirmDialog'];
     setConfirmDialog: SkillHubState['setConfirmDialog'];
     runConfirmed: SkillHubState['runConfirmed'];
+    /** 来源检查结果（同步确认里标出本地改动过的技能）。 */
+    sourceCheck: SkillHubState['sourceCheck'];
     /** 无 release 的市场源分支选择。 */
     branchChoice: SkillHubState['branchChoice'];
     branchBusy: SkillHubState['branchBusy'];

package/lib/types/client/panel/dialogs.d.ts

@@ -4,7 +4,7 @@
  * market sync selection). Every dialog closes on outside click and keeps
  * the same role/aria shell; the panel owns all dialog state.
  */
-import { type JSX } from 'react';
+import { type JSX, type ReactNode } from 'react';
 import type { CollectionGroup, SkillTag } from '../../protocol.ts';
 /** A group-close conflict waiting for the user's decision. */
 export interface ConflictDialogState {
@@ -44,12 +44,22 @@ export interface MarketSyncDialogState {
     skills: string[];
     selected: ReadonlySet<string>;
 }
+/** Overlay + centered alert-dialog shell; outside click or Escape cancels. */
+export declare function DialogShell(props: {
+    onClose: () => void;
+    children: ReactNode;
+}): JSX.Element;
 /** Simple confirm dialog: title + text + optional skill list + cancel/confirm. */
 export declare function ConfirmDialog(props: {
     title: string;
     text: string;
     /** Optional skill names listed between the text and the buttons. */
     items?: readonly string[];
+    /**
+     * 这些条目在磁盘上已被本地改过。列出来时逐个标记 —— 「会覆盖本地修改」
+     * 这句话只有在能指出是哪几个时才有用。
+     */
+    marked?: readonly string[];
     confirmLabel: string;
     /** Danger-styled confirm button (destructive actions). */
     danger?: boolean;

package/lib/types/client/panel/useSkillHub.d.ts

@@ -183,4 +183,5 @@ export declare function useSkillHub(api: SkillHubApi): {
     confirmMarketSync: () => Promise<void>;
     updateAll: () => Promise<void>;
     create: (event: import("react").FormEvent) => Promise<void>;
+    reloadCatalog: () => Promise<void>;
 };

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

@@ -48,4 +48,6 @@ export declare const SKILL_HUB_API: {
     readonly diagnosticFix: "/api/skill-hub/diagnostic/fix";
     readonly marketSourceVersions: "/api/skill-hub/market/source/versions";
     readonly marketStats: "/api/skill-hub/market/stats";
+    readonly foreign: "/api/skill-hub/foreign";
+    readonly foreignImport: "/api/skill-hub/foreign/import";
 };

package/lib/types/protocol/catalog.d.ts

@@ -50,7 +50,43 @@ export interface DiagnosticEntry {
     reason: string;
     /** Whether this diagnostic can be auto-fixed (e.g. unquoted colon). */
     fixable?: boolean;
-}
+    /**
+     * 条目来源。缺省 = 发现诊断（provider 跳过了这个文件）；`security` = 内容审计
+     * （文件能被加载，但正文里有值得看一眼的东西）。两者共用同一块 UI，但
+     * security 条目不能「修复」，只能说清问题在哪一行。
+     */
+    kind?: 'security';
+    /** security 条目的严重度；发现诊断条目省略。 */
+    severity?: 'block' | 'warn';
+}
+/**
+ * 技能目录在 system prompt 里占用的公告预算。渐进加载的第一层只放
+ * name + description，但技能多了这一层本身就会顶到客户端的上限而被截断，
+ * 表现为「装了却不触发」—— 面板必须能看见这个数字。
+ */
+export interface AnnouncementBudget {
+    /** 参与公告的技能数（已启用且 modelInvocable）。 */
+    skills: number;
+    /** name + description + whenToUse 的总字符数。 */
+    chars: number;
+    /** 粗略 token 估算（按 3 字符/token）。 */
+    approxTokens: number;
+    /** 建议预算（字符），超出即 overBudget。 */
+    budget: number;
+    overBudget: boolean;
+}
+/**
+ * 技能目录的建议字符预算。取 8000：这是 Codex 在上下文窗口未知时对初始
+ * 技能清单的硬上限，也是目前公开客户端里最保守的一档。超出后尾部条目会被
+ * 静默丢弃（技能看起来装了，实际不触发）。
+ */
+export declare const ANNOUNCEMENT_CHAR_BUDGET = 8000;
+/**
+ * 按「已启用且模型可调用」的技能估算公告成本。只统计一层渐进加载真正注入的
+ * 字段（name + description + whenToUse），不含正文 —— 正文是激活后才载入的，
+ * 不占常驻预算。
+ */
+export declare function computeAnnouncementBudget(skills: readonly CatalogSkill[]): AnnouncementBudget;
 /** POST /api/skill-hub/diagnostic/fix — repair a fixable diagnostic in place. */
 export interface DiagnosticFixRequest {
     path: string;
@@ -72,6 +108,8 @@ export interface CatalogResponse {
     disabled: DisabledSkill[];
     /** Files in the writable roots the provider ignores, with reasons. */
     diagnostics: DiagnosticEntry[];
+    /** 技能目录占用的公告预算（见 AnnouncementBudget）。 */
+    announcement: AnnouncementBudget;
     /** Skill names that appeared in multiple roots (first wins, others hidden). Mirrors codex name_counts. */
     duplicateNames?: string[];
 }

package/lib/types/protocol/foreign.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 外部 agent 技能（收编）的线格式。
+ *
+ * 发现源是别的 agent 的用户级技能目录（Claude Code / Codex / Cursor / …），
+ * 它们一律只读：这里只描述「看到了什么」和「要收编哪一个」。
+ */
+/** 一个被扫描的外部技能根。 */
+export interface ForeignRootView {
+    agent: string;
+    dir: string;
+    /** 该目录在本机是否存在（不存在时 skills 里不会出现它的条目）。 */
+    present: boolean;
+}
+/** 一条可收编的外部技能。 */
+export interface ForeignSkillView {
+    name: string;
+    description: string;
+    agent: string;
+    /** 发现文件绝对路径（只读展示）。 */
+    path: string;
+    kind: 'directory' | 'flat';
+    /** 目标根已有同名技能，不可导入。 */
+    existing: boolean;
+}
+/** GET /api/skill-hub/foreign */
+export interface ForeignListResponse {
+    ok: true;
+    roots: ForeignRootView[];
+    skills: ForeignSkillView[];
+}
+/** POST /api/skill-hub/foreign/import — 按 agent + 名字收编（不信任前端给的路径）。 */
+export interface ForeignImportRequest {
+    items: Array<{
+        agent: string;
+        name: string;
+    }>;
+}
+export interface ForeignImportResponse {
+    ok: true;
+    imported: string[];
+    /** 导入前被移入回收站的同名占位（已禁用的发现文件 / 空壳目录），可恢复。 */
+    replaced?: string[];
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}

package/lib/types/protocol/sources.d.ts

@@ -14,6 +14,12 @@ export interface SourceRecord {
     skills: string[];
     /** 仓库内路径 → 文件大小 的基线清单（差异检测用；缺失 = 无基线）。 */
     manifest?: Record<string, number>;
+    /**
+     * 技能名 → 本地内容哈希（导入/同步落盘后立刻采集）。用于区分「上游变了」
+     * 与「本地被改过」：没有它，「全部更新」只能盲覆盖。缺失 = 该技能还没采集过
+     * （旧记录），比对时按「未知」处理，不误报为已修改。
+     */
+    localHashes?: Record<string, string>;
 }
 /** 回收站条目：上游删除后跟进删除（移入 .trash）的技能。 */
 export interface TrashEntry {
@@ -72,6 +78,11 @@ export interface SourceCheckResult {
     throttled?: boolean;
     /** 该来源此前没有快照（迁移/旧记录），本次已回填 commit，尚未有差异基线。 */
     unverified?: boolean;
+    /**
+     * 本地磁盘内容与上次导入/同步时不一致的技能（用户自己改过）。只在检查
+     * 时本地能读到文件才判定；哈希未采集过（旧记录）的技能不出现在这里。
+     */
+    localModified?: string[];
 }
 /** POST /api/skill-hub/sources/check */
 export interface SourceCheckResponse {
@@ -92,6 +103,8 @@ export interface SourceSyncResponse {
     commitSha: string;
     /** 成功同步的技能。 */
     synced: string[];
+    /** 本次同步覆盖掉的、本地有改动的技能（改前哈希 ≠ 记录哈希）。 */
+    overwritten?: string[];
     /** 失败的技能。 */
     failed: Array<{
         name: string;

package/lib/types/protocol.d.ts

@@ -8,7 +8,8 @@
  * 新代码可按需直引 `from './protocol/<domain>.ts'`。
  */
 export { SKILL_HUB_API, SKILL_HUB_API_ROOT } from './protocol/api.ts';
-export type { WritableRoot, HubInvocation, CatalogSkill, DisabledSkill, DiagnosticEntry, DiagnosticFixRequest, DiagnosticFixResponse, CatalogResponse, SkillDetail, SkillDetailResponse, SkillDeleteRequest, SkillDeleteResponse, ToggleRequest, ToggleResponse, ToggleBatchRequest, ToggleBatchResponse, CreateRequest, CreateResponse, } from './protocol/catalog.ts';
+export type { WritableRoot, HubInvocation, CatalogSkill, DisabledSkill, DiagnosticEntry, AnnouncementBudget, DiagnosticFixRequest, DiagnosticFixResponse, CatalogResponse, SkillDetail, SkillDetailResponse, SkillDeleteRequest, SkillDeleteResponse, ToggleRequest, ToggleResponse, ToggleBatchRequest, ToggleBatchResponse, CreateRequest, CreateResponse, } from './protocol/catalog.ts';
+export { ANNOUNCEMENT_CHAR_BUDGET, computeAnnouncementBudget } from './protocol/catalog.ts';
 export type { SkillStat, StatsResponse, SkillStatsCheckpoint } from './protocol/stats.ts';
 export type { ErrorResponse, HubConfig, HubSettingsValue, RedactedHubConfig, ConfigResponse, ConfigRequest } from './protocol/config.ts';
 export { HUB_CONFIG_DEFAULTS, HUB_ENTRY_ID, HEX_COLOR_RE, GITHUB_TOKEN_RE, resolveHubConfig, redactGithubToken } from './protocol/config.ts';
@@ -17,3 +18,4 @@ export type { RepoSkillEntry, RepoRoot, RepoDiscoverResponse, RepoImportRequest,
 export type { SkillTag, CollectionGroup, GroupsResponse, TagSaveRequest, TagSaveResponse, TagDeleteRequest, TagDeleteResponse, TagMembersRequest, TagMembersResponse, TagReorderRequest, TagReorderResponse, CollectionReorderRequest, CollectionReorderResponse, SourceGroupReorderRequest, SourceGroupReorderResponse, } from './protocol/groups.ts';
 export type { SourceRecord, TrashEntry, SourcesResponse, SourceCheckRequest, SourceCheckResult, SourceCheckResponse, SourceSyncRequest, SourceSyncResponse, SourceDeleteRequest, SourceDeleteResponse, SourceRestoreRequest, SourceRestoreResponse, SourceTrashClearResponse, } from './protocol/sources.ts';
 export { isProjectSource } from './protocol/sources.ts';
+export type { ForeignRootView, ForeignSkillView, ForeignListResponse, ForeignImportRequest, ForeignImportResponse } from './protocol/foreign.ts';

package/lib/types/repo/install.d.ts

@@ -16,6 +16,10 @@ export declare function downloadGitHubFile(repo: string, ref: string, path: stri
  * 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` 级发现直接拒绝
+ * 导入 —— 一个能藏住指令的技能不该靠用户「看得仔细」来兜底。
  */
 export declare function downloadRepoSkill(repo: string, ref: string, entry: RepoSkillEntry, files: readonly RepoFile[], targetRoot: string, fetchImpl?: typeof fetch, signal?: AbortSignal, onProgress?: (bytes: number, file: string) => void): Promise<{
     targetDir: string;

package/lib/types/routes/deps.d.ts

@@ -31,6 +31,12 @@ export interface SkillHubRouteDeps {
     fence?: RouteFence;
     /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
     home?: string;
+    /**
+     * 用户主目录覆盖（其他 agent 的 `~/.claude/skills` 等相对它解析）。
+     * 与 `home` 是两个概念：`home` 是 DSH 自己的状态根（`~/.dsh`），
+     * 这个才是 `/Users/<user>`。测试用它把外部扫描圈在临时目录里。
+     */
+    userHome?: string;
     /** Invalidate the registry catalog cache after hub-driven mutations. */
     invalidate?: () => void;
     /** Optional invocation-count reader; absent means the stats route reports unavailable. */
@@ -55,6 +61,11 @@ export declare function savedOf(deps: SkillHubRouteDeps): Partial<HubConfig>;
 export declare function disabledGate(deps: SkillHubRouteDeps, res: ServerResponse): boolean;
 /** Resolve the home used for writable-root operations. */
 export declare function homeOf(deps: SkillHubRouteDeps): string;
+/**
+ * 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).
+ */
+export declare function userHomeOf(deps: SkillHubRouteDeps): string;
 /** A skill resolved as a hub-writable user-level file. */
 export interface WritableSkill {
     skill: SkillDefinition;

package/lib/types/routes/foreign.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 外部 agent 技能域路由：发现（只读扫描别家目录）与收编（复制进本地可写根）。
+ *
+ * 两条约束：
+ * 1. 外部目录只读 —— 扫描不会 mkdir，也不会写任何东西到别家路径下；
+ * 2. 导入不信任前端给的路径：只接受 `agent + name`，服务端重新扫一遍定位，
+ *    否则一个拼出来的绝对路径就能把任意文件复制进技能目录。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+export declare function foreignRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/helpers.d.ts

@@ -10,7 +10,7 @@ import type { WebRoute, WebRouteKind } from '@deepseek-ai/dsh-host-webserver';
 import { type SkillHubRouteDeps } from './deps.ts';
 export { MAX_JSON_BODY_BYTES, STORE_ERROR_STATUS, isLoopbackRequest, loopbackOnlyFence, pathExists, queryParam, readJsonBody, readString, readStrings, writeError, writeJson, writeRouteError, } from './http.ts';
 export type { RouteFence } from './http.ts';
-export { configOf, disabledGate, homeOf, isWritableSource, resolveWritableSkill, savedOf, } from './deps.ts';
+export { configOf, disabledGate, homeOf, isWritableSource, resolveWritableSkill, savedOf, userHomeOf, } from './deps.ts';
 export type { SkillHubRouteDeps, SkillLookupLike, WritableSkill, WritableSkillRefusal, WritableSkillResult, } from './deps.ts';
 export { buildCollections, buildGroups } from './collection.ts';
 export { applyInterface, buildCatalog, knownSkillNames, toDetail, workspaceEntries, } from './catalog-data.ts';

package/lib/types/skillfs/audit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 技能内容审计：安装前拦截与常驻体检共用的一套纯函数规则。
+ *
+ * 两条设计约束：
+ * 1. 零依赖、纯字符串处理。宿主每 5 秒轮询一次 /catalog，扫描必须廉价，
+ *    否则面板响应时间会随技能数量线性变慢（与 scanDiagnostics 同一理由）。
+ * 2. 规则只认结构特征（不可见字符、命令管道、凭据路径），不做语义判断。
+ *    语义/LLM 判断误报率高且要模型调用，不属于一个管理器的职责边界；
+ *    这里的目标是「让藏起来的东西显形」，不是「判定作者意图」。
+ *
+ * 两级严重度：
+ * - `block`：安装阶段拒绝落盘。只用于「没有任何正当用途」的特征 ——
+ *   裸 ESC 控制字符、Unicode 标签字符、双向控制符、以及体积越界。
+ * - `warn`：落盘但标记。零宽字符、危险命令、凭据路径、超长描述都可能
+ *   出现在正常技能里（比如一个教人用 curl 的技能），交给人判断。
+ */
+/** 规则 id：稳定，测试与文案都按它断言。 */
+export type AuditRuleId = 'ansi-escape' | 'unicode-tag' | 'bidi-control' | 'zero-width' | 'dangerous-command' | 'credential-path' | 'file-too-large' | 'bundle-too-large' | 'too-many-files' | 'description-too-long';
+export type AuditSeverity = 'block' | 'warn';
+/** 一条审计发现。`file` 相对技能目录，便于在面板上直接定位。 */
+export interface AuditFinding {
+    rule: AuditRuleId;
+    severity: AuditSeverity;
+    file: string;
+    /** 1 起行号；整文件级规则（体积、文件数）省略。 */
+    line?: number;
+    message: string;
+}
+/** 单文件字节上限：技能是纯文本加少量脚本，2 MiB 已远超正常体积。 */
+export declare const MAX_SKILL_FILE_BYTES: number;
+/** 单个技能总字节上限。 */
+export declare const MAX_SKILL_BUNDLE_BYTES: number;
+/** 单个技能文件数上限。 */
+export declare const MAX_SKILL_FILES = 500;
+/** agentskills.io 规范对 description 的硬上限。 */
+export declare const MAX_DESCRIPTION_CHARS = 1024;
+/**
+ * 审计一段技能文本（SKILL.md 正文、脚本、参考文档都适用）。
+ * 纯函数：同样的输入永远给同样的结果，便于单测与「改动前后对比」。
+ */
+export declare function auditSkillText(relativePath: string, text: string): AuditFinding[];
+/** description 超出规范上限：部分客户端会截断，技能因此静默失去自动激活能力。 */
+export declare function auditDescription(file: string, description: string): AuditFinding[];
+/** 一个待落盘/待检查的技能文件。`text` 只在能当作文本读时提供。 */
+export interface AuditBundleFile {
+    /** 相对技能目录的路径。 */
+    path: string;
+    size: number;
+    /** 文本内容；二进制或未下载时省略。 */
+    text?: string;
+}
+/**
+ * 审计一个完整技能目录：体积/数量上限 + 每个文本文件的规则扫描。
+ * `block` 级发现（体积越界）意味着不该落盘；文本级 `block` 由调用方决定。
+ */
+export declare function auditSkillBundle(files: readonly AuditBundleFile[], description?: string): AuditFinding[];
+/** 阻断性发现的单行摘要（导入失败时的错误文本）。 */
+export declare function blockingReason(findings: readonly AuditFinding[]): string | undefined;

package/lib/types/skillfs/foreign.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 外部 agent 技能的只读发现与收编。
+ *
+ * SKILL.md 已经是跨 agent 的事实标准（Claude Code / Codex / Cursor / Gemini CLI
+ * 等 45+ 产品读同一份文件），但**发现路径各家不同**。于是「我在 Claude Code 里
+ * 调好的技能」在 dsh 里看不见，用户只能手工复制目录。
+ *
+ * 这里只做两件事：读（列出别处有什么）和复制（把选中的收编到本地可写根）。
+ * 外部目录一律**只读**，绝不改写 —— 那是别的 agent 的资产。
+ */
+/** 一个外部 agent 的技能根。`agent` 是展示用的稳定标识。 */
+export interface ForeignRoot {
+    agent: string;
+    /** 绝对路径；不存在时扫描直接返回空。 */
+    dir: string;
+}
+/** 一条可收编的外部技能。 */
+export interface ForeignSkill {
+    /** 技能名（目录名或扁平文件名，与 frontmatter 一致时才算有效）。 */
+    name: string;
+    description: string;
+    /** 来源 agent 标识。 */
+    agent: string;
+    /** 发现文件绝对路径。 */
+    path: string;
+    /** 资源基目录（目录包本身，或扁平文件的父目录）。 */
+    directory: string;
+    kind: 'directory' | 'flat';
+    /** 目标根已有同名技能（不可导入）。 */
+    existing: boolean;
+}
+/**
+ * 常见 agent 的用户级技能目录。`~/.agents/skills` 不在此列 —— 那是 hub 自己的
+ * 可写根（user-agents），重复列会让同一个技能出现两次。
+ * 路径取自 vercel-labs/skills 的 agent 注册表，只保留桌面端常见的几个。
+ */
+export declare function foreignRoots(userHome: string): ForeignRoot[];
+/**
+ * 扫描所有外部根。解析不出 frontmatter 的条目直接跳过 —— 它们在任何 agent 里
+ * 都不会生效，列出来只会让人以为「导入就好了」。
+ */
+export declare function scanForeignSkills(userHome: string, existing?: ReadonlySet<string>): Promise<ForeignSkill[]>;
+/**
+ * 把一个外部技能收编到 `targetRoot`（通常是 `~/.dsh/skills`）。
+ *
+ * 与市场导入同一套闸：体积/数量上限 + 内容审计，命中阻断级直接拒绝；
+ * 落盘仍是「临时目录 → 校验 → 原子 rename」，失败不留半成品。
+ * 扁平技能统一落成目录包 —— hub 的所有写入路径都建目录包，两种形态并存会
+ * 触发同名不可达（issue #16 那一类）。
+ */
+export declare function importForeignSkill(skill: ForeignSkill, targetRoot: string): Promise<string>;

package/lib/types/skillfs/hash.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 技能内容哈希：给「本地这份技能到底有没有被改过」一个确定答案。
+ *
+ * 现有来源记录只存上游的 commit 与按路径的字节数基线，能回答「上游变没变」，
+ * 回答不了「磁盘上这份还是不是我当初导入的那份」。于是「一键全更」只能盲覆盖，
+ * 用户唯一的保护是弹窗里那句他自己也判断不了的「会覆盖本地修改」。
+ *
+ * 哈希的粒度是**整个技能**（目录包 = 目录下全部文件；扁平技能 = 那一个文件），
+ * 而不是单文件：用户改的是「这个技能」，不是「这个技能里的第 3 个文件」。
+ *
+ * 边界（与体积审计同一套取舍）：技能是纯文本加少量脚本，正常体积在几十 KB。
+ * 走查上限存在的意义是「一个恶意或事故性的巨大目录不能把 /catalog 拖死」，
+ * 不是为了支持大包。
+ */
+/**
+ * 一个技能目录的内容哈希。目录不可读时返回 undefined（调用方据此跳过比对，
+ * 而不是把它当成「改过了」—— 读不到不等于变了）。
+ */
+export declare function hashSkillDirectory(dir: string): Promise<string | undefined>;
+/**
+ * 从一个发现文件推断技能形态并算哈希：`SKILL.md`（含 `.disabled` 变体）是
+ * 目录包，其余 `<name>.md` 是扁平技能。两种形态共用同一个返回契约。
+ */
+export declare function hashSkillAt(discoveryPath: string): Promise<string | undefined>;

package/lib/types/skillfs.d.ts

@@ -15,6 +15,8 @@ import type { TrashEntry, WritableRoot } from './protocol.ts';
 export * from './skillfs/frontmatter.ts';
 export * from './skillfs/paths.ts';
 export * from './skillfs/scan.ts';
+export * from './skillfs/hash.ts';
+export * from './skillfs/foreign.ts';
 /**
  * Scaffold a directory-bundle skill: <root>/<name>/SKILL.md with a frontmatter
  * template. Refuses non-kebab-case names.

package/lib/types/store/store.d.ts

@@ -101,6 +101,12 @@ export declare class SkillHubStore {
     removeSkillFromSources(name: string): Promise<void>;
     /** Update a source's commit snapshot. */
     setSourceCommit(repo: string, commitSha: string): Promise<void>;
+    /**
+     * 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.
+     */
+    setSourceSkillHash(repo: string, skillName: string, hash: string): Promise<void>;
     /** Update a source's pinned ref (release tag / branch) when the market syncs. */
     setSourceRef(repo: string, ref: string): Promise<void>;
     /**