dsh-plugin-manager-companion 0.1.0

package/dist/kinds.d.ts

@@ -0,0 +1,464 @@
+/**
+ * 多类型安装：skill / agent 预设的检测、直装，以及安装记录与屏蔽名单。
+ *
+ * 归属：A 类·重写（写文件、复制目录、管持久化状态；旧 src/kinds.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/kinds.ts（536 行：分层检测、SKILL.md 发现、
+ *   installed-kinds.json 记录、blocked-repos.json 屏蔽名单、isUnderRoot 守卫、
+ *   rmRetry/renameRetry 的 Windows 占用重试）。
+ * 官方复用：官方 skill-filesystem 扫描 <dshHome>/skills（默认 chokidar 热加载），
+ *   官方 agent-presets 每次读取都重扫 <dshHome>/.agent-presets 且以 agent.cordis.yml
+ *   为组合文件——本模块只往这两个官方根里落文件，**不复制官方发现逻辑、
+ *   不注册任何服务、不动 cordis.patch.yml**。路径基座复用 src/paths.ts 的 dshHome()。
+ * 前提检查：仍然成立且这正是我们的作业面——官方 README 明说 "loading plain plugin
+ *   modules stays a file operation"，skill 与 agent 预设没有安装器。旧实现的前提
+ *   （官方只有只读清单、必须自建写路径）对 cordis 插件已消失，所以这里**不做**
+ *   cordis 插件的安装：那种仓库交给官方 plugin_manager / CLI 的 pnpm 通道。
+ *   本模块对 cordis-plugin 只做"识别并指引"。
+ *
+ * 四条硬约束：
+ *   1. 每个落地目录都必须校验在目标根之内（isUnderRoot）——SKILL.md frontmatter
+ *      里的 name 是第三方内容，可能写成 ../.. 或绝对路径。
+ *   2. 删除/改名带重试：Windows 上 AV 扫描器与编辑器会短暂占用句柄。
+ *   3. 记录与屏蔽名单的读改写串行化，且落盘是"临时文件 + 改名"的原子写。
+ *   4. 永不执行第三方脚本：仓库里的 install.sh 只被扫描（见 scan.ts），不被运行。
+ */
+import type { InstalledKind, MarketItemKind } from './types.ts';
+/** 可安装的非插件资源类型。'unknown' 表示检测不出（应拒绝安装）。 */
+export type RepoKind = 'agent-preset' | 'cordis-plugin' | 'skill';
+/** 检测结果：三类之一，或 unknown（非插件/技能/预设仓库）。 */
+export type DetectedRepoKind = RepoKind | 'unknown';
+/** 官方预设组合文件：一个目录里有它就构成一个 agent 预设（官方单文件判定）。 */
+export declare const PRESET_COMPOSITION_FILE = "agent.cordis.yml";
+/** 官方技能清单文件（大小写不敏感，见 findSkillRoots）。 */
+export declare const SKILL_MANIFEST_FILE = "SKILL.md";
+/** 技能根发现的默认上限：5 层 / 200 个。 */
+export declare const DEFAULT_ROOT_LIMITS: {
+    readonly maxDepth: 5;
+    readonly limit: 200;
+};
+/** 插件根发现的默认上限（比技能浅：packages/* 这种布局三层足够）。 */
+export declare const DEFAULT_PLUGIN_LIMITS: {
+    readonly maxDepth: 3;
+    readonly limit: 50;
+};
+/** 预设根发现的默认上限。 */
+export declare const DEFAULT_PRESET_LIMITS: {
+    readonly maxDepth: 3;
+    readonly limit: 50;
+};
+/**
+ * 覆盖 Harness home 并清掉全部进程内缓存（仅测试用）。
+ * @param home - 临时 home；传 null 恢复真实 home。
+ */
+export declare function __setHomeForTests(home: string | null): void;
+/**
+ * 当前生效的 Harness home（含测试覆盖）。
+ *
+ * 兄弟模块（presets.ts）必须用这个而不是直接调 paths.dshHome()：否则测试里
+ * 覆盖过的 home 只有一半模块看得见，落地根与归档根会分叉。
+ * @returns 绝对路径。
+ */
+export declare function resolvedHome(): string;
+/** 本插件管辖的缓存目录（与旧仓库共用同一目录名，但文件名不同，见下）。 */
+export declare function cacheRoot(): string;
+/**
+ * 安装记录文件。
+ *
+ * 与旧仓库的 installed-kinds.json **不同文件**：那个文件由已停止维护的旧包读写，
+ * 两边并发写会互相覆盖。读取端做兼容（见 loadKindRecords），写入端只碰自己的
+ * 文件，因此两个包共存期间各自的数据都完好。
+ */
+export declare function kindRecordsFile(): string;
+/** 屏蔽名单文件（同样是独立文件，避免与旧包并发写）。 */
+export declare function blockedReposFile(): string;
+/** 官方技能落地根。 */
+export declare function skillsRoot(): string;
+/** 官方 agent 预设落地根。 */
+export declare function presetsRoot(): string;
+/** 根发现选项。 */
+export interface RootSearchOptions {
+    /** 递归层数上限（根为第 0 层）。 */
+    readonly maxDepth?: number;
+    /** 最多返回的根数量。 */
+    readonly limit?: number;
+}
+/**
+ * 路径包含判定：target 必须位于 root 之内（不等于 root）。
+ *
+ * 用途是删除/移动前的最后一道守卫：SKILL.md 的 frontmatter name、预设目录名
+ * 都可能包含 ../ 或绝对路径（第三方内容），一旦漏判就会删到用户的主目录
+ * （旧仓库记录过"删掉整个 Harness home"的事故）。大小写按平台语义处理：
+ * Windows/macOS 的文件系统大小写不敏感，用大小写精确比较会误拒合法路径
+ * （旧仓库审计 W2）。
+ *
+ * @param target - 待校验路径。
+ * @param root - 允许的根。
+ * @returns 是否严格位于根之内。
+ */
+export declare function isUnderRoot(target: string, root: string): boolean;
+/**
+ * 删除一棵目录树，带短暂重试。
+ *
+ * Windows 上 AV 扫描器/编辑器会短暂持有句柄，第一次 rm 常以 EPERM/EBUSY 失败；
+ * rm 的 force 只容忍"不存在"，不容忍"被占用"。退避用定时器而不是忙循环：
+ * 调用点都在 async 路径上，同步自旋会冻住整个事件循环。
+ *
+ * @param target - 要删除的路径。
+ * @throws 重试耗尽后抛出最后一次错误。
+ */
+export declare function rmRetry(target: string): Promise<void>;
+/**
+ * 改名（移动），带短暂重试。归档/恢复预设目录时目标可能被占用。
+ *
+ * @param from - 源路径。
+ * @param to - 目标路径。
+ * @throws 重试耗尽后抛出最后一次错误。
+ */
+export declare function renameRetry(from: string, to: string): Promise<void>;
+/** 生成文件系统安全的目录名：小写、非字母数字折叠成 '-'。 */
+export declare function slugDirName(name: string): string;
+/**
+ * 平台安全的目录名：Windows 保留名加后缀。
+ * @param name - 期望的目录名。
+ * @returns 可直接 mkdir 的名字。
+ */
+export declare function safeDirName(name: string): string;
+/**
+ * 归一化仓库引用为小写 owner/repo。
+ *
+ * 支持 github:owner/repo、git+https://…、https://github.com/owner/repo、
+ * git@github.com:owner/repo、末尾 .git 与 #ref 片段。非 GitHub 形态（本地路径）
+ * 返回 null——调用方必须自己决定用什么做键，而不是被塞一个被改写的路径。
+ *
+ * @param value - 用户输入的仓库引用。
+ * @returns owner/repo 小写形式；无法识别的形态返回 null。
+ */
+export declare function normalizeRepoRef(value: string): string | null;
+/**
+ * 判断一个 package.json 是否声明了 DSH 能力。
+ *
+ * 判据（与旧实现意图一致，重写实现）：有 dsh 对象字段，或依赖/peerDependencies 里
+ * 出现 @deepseek-ai/cordis、@deepseek-ai/dsh、@deepseek-ai/dsh-*。仅带 package.json
+ * 的聚合页/桌面壳/普通 npm 项目返回 false——那种仓库不该被当成插件强装。
+ *
+ * @param manifest - 解析后的 package.json 内容（任意 JSON）。
+ * @returns true/false；不是对象时返回 null（无法判定）。
+ */
+export declare function looksLikeDshPlugin(manifest: unknown): boolean | null;
+/**
+ * 找出仓库里的 SKILL.md 根（单技能仓库与技能集合仓库）。
+ *
+ * 一个目录里有 SKILL.md 就不再往下走：技能目录内部的子目录属于该技能自己的
+ * 结构（脚本、资源），把其中的 SKILL.md 当成第二个技能会装出重复内容。
+ *
+ * @param root - 仓库根目录。
+ * @param options - 层数与数量上限（默认 5 层 / 200 个）。
+ * @returns 技能根目录的绝对路径列表。
+ */
+export declare function findSkillRoots(root: string, options?: RootSearchOptions): Promise<string[]>;
+/**
+ * 找出仓库里的 agent 预设根（根预设与预设集合都覆盖）。
+ *
+ * 判定只看官方组合文件 agent.cordis.yml 是否存在——preset.yml 只是可选展示元数据，
+ * 不是构成条件（官方 discovery 的口径）。
+ *
+ * @param root - 仓库根目录。
+ * @param options - 层数与数量上限（默认 3 层 / 50 个）。
+ * @returns 预设根目录的绝对路径列表。
+ */
+export declare function findPresetRoots(root: string, options?: RootSearchOptions): Promise<string[]>;
+/**
+ * 找出仓库里的 DSH 插件包根（monorepo / 多包仓库）。
+ *
+ * @param root - 仓库根目录。
+ * @param options - 层数与数量上限（默认 3 层 / 50 个）。
+ * @returns 插件包目录列表。
+ */
+export declare function findPluginRoots(root: string, options?: RootSearchOptions): Promise<string[]>;
+/**
+ * 分层类型检测。
+ *
+ * 顺序（旧实现的顺序保留，重写实现）：
+ *   1. 根目录就是预设（agent.cordis.yml 在根）→ agent-preset；
+ *   2. 根 package.json 声明了 DSH 能力 → cordis-plugin；
+ *   3. 根有 SKILL.md → skill（工具链 package.json 在纯技能仓库上很常见，
+ *      不能因为"有 package.json"就判成插件）；
+ *   4. 嵌套检测**统一放最后一层**：预设 → 插件 → 技能，三层只要有一层命中就
+ *      返回该类型；这样"技能集合里夹带一个预设目录"和"预设集合里夹带技能"
+ *      都按预设优先（预设是更具体的形态）；
+ *   5. 都不命中 → unknown（调用方据此拒绝安装并加入屏蔽名单）。
+ *
+ * 与旧实现的差别：旧实现有第四类 'instructions'（带 install.sh 的仓库）。
+ * 'unknown' 已经覆盖那个语义（拒绝安装 + 指引用户自己看仓库），少一个类型名
+ * 少一处分支。**任何仓库的 install.sh 都不会被自动执行**，这一点没有变。
+ *
+ * @param root - 仓库根目录。
+ * @returns 检测到的类型；无法识别时为 'unknown'。
+ */
+export declare function detectRepoType(root: string): Promise<DetectedRepoKind>;
+/**
+ * 读取 SKILL.md 的 YAML frontmatter 里的 name。
+ *
+ * 只做一件小事：'---' 块里的 name: 行。不引入 YAML 解析器——技能清单的
+ * frontmatter 由官方解析，我们只需要拿它当**建议目录名**，解析失败就回退到
+ * 仓库名/目录名，不影响技能本身能否被官方加载。
+ *
+ * @param skillDir - 技能根目录。
+ * @returns 合法的技能名；没有或非法时返回 null。
+ */
+export declare function skillDisplayName(skillDir: string): Promise<string | null>;
+/** 一次直装的结果。 */
+export interface InstallOutcome {
+    /** 单个落地时的名字；多个时是 N-skills / N-presets 这类汇总名。 */
+    readonly name: string;
+    /** 每个落地目录名。 */
+    readonly names: readonly string[];
+    /** 落地根目录。 */
+    readonly location: string;
+    /** 每个落地目录的绝对路径（与 names 同序）。 */
+    readonly dirs: readonly string[];
+}
+/** 直装选项。 */
+export interface InstallOptions {
+    /** 已被其他安装记录占用的名字；命中即拒绝（避免静默覆盖别人的技能）。 */
+    readonly occupied?: ReadonlySet<string>;
+    /** 覆盖落地根（测试用；默认是官方用户根）。 */
+    readonly root?: string;
+    /**
+     * 是否写入安装记录（默认 true）。
+     *
+     * 记录是「市场已安装标记」与「uninstall-kind 卸载」的唯一依据——安装不记账等于装完就找不到。
+     * 只有明确的例外场景（例如调用方已经把多个根聚合成一条记录）才关掉它。
+     */
+    readonly record?: boolean;
+}
+/**
+ * 安装技能仓库到 <dshHome>/skills。
+ *
+ * 单技能仓库与技能集合仓库都覆盖：每个 SKILL.md 根装成一个目录，目录名优先取
+ * frontmatter 的 name，其次单根时取仓库名、多根时取该根自己的目录名。
+ *
+ * 落地前会 rm 掉同名目录（这是"重装同一技能"的语义），但**先校验包含关系**：
+ * 名字来自第三方 frontmatter，必须落在技能根之内。名字已被另一条安装记录占用时
+ * 抛错而不是覆盖——静默覆盖等于让用户丢掉另一个技能。
+ *
+ * @param repoRoot - 仓库根目录（已就绪的克隆或本地目录）。
+ * @param repoName - 仓库展示名（owner/repo 或本地目录名）。
+ * @param options - 已占用名字集合与根覆盖。
+ * @returns 落地结果。
+ * @throws 没有 SKILL.md、名字冲突、越界时。
+ */
+export declare function installSkill(repoRoot: string, repoName: string, options?: InstallOptions): Promise<InstallOutcome>;
+/**
+ * 安装 agent 预设仓库到 <dshHome>/.agent-presets。
+ *
+ * 目录名即 preset id（官方语义）。嵌套预设立于子目录时用子目录名做 id；名字是
+ * 惯例的 preset 或根预设时回退到仓库名——这样常见布局 repo/preset/agent.cordis.yml
+ * 装出来是仓库名而不是一堆同名 preset。
+ *
+ * 每个落地目录写一份**中立标准归属标记**（.dsh-preset-owner.json），让插件卸载时
+ * 能分清"这个预设是谁装的、用户改过没有"（见 presets.ts）。已有标记不覆盖。
+ *
+ * @param repoRoot - 仓库根目录。
+ * @param repoName - 仓库展示名（owner/repo 或本地目录名）。
+ * @param options - 已占用 id 集合与根覆盖。
+ * @returns 落地结果。
+ * @throws 没有 agent.cordis.yml、id 冲突、越界时。
+ */
+export declare function installPreset(repoRoot: string, repoName: string, options?: InstallOptions): Promise<InstallOutcome>;
+/**
+ * 删除一个已安装的 kind 目录（越界即拒绝）。
+ *
+ * @param root - 允许的根（技能根或预设根）。
+ * @param dir - 待删除目录。
+ * @throws 越界时（不删除任何东西）。
+ */
+export declare function removeKindDir(root: string, dir: string): Promise<void>;
+/**
+ * 把任意仓库拼写收敛成记录表的规范键。
+ *
+ * 记录表的键一律是 normalizeRepoRef 的结果（小写 owner/repo）；本地路径这类
+ * normalizeRepoRef 认不出的形态按原样当键。
+ *
+ * @param ref - 任意仓库拼写（owner/repo、URL、github:、客户端回传的展示名…）。
+ * @returns 规范键。
+ */
+export declare function canonicalKindKey(ref: string): string;
+/**
+ * 落盘形态的记录。
+ *
+ * 比 wire 类型 InstalledKind 多两个**仅供本模块内部使用**的字段，它们解决的问题是
+ * 精确性：一个技能集合仓库会落下多个目录，只记 `dir` 无法回答"这次安装到底碰了哪些
+ * 目录"。孤儿扫描（findOrphanKindDirs）与将来的多目录卸载都要靠 `dirs`。
+ * 多出来的键会随记录一起落盘，客户端 wire 解析只挑它认识的字段，因此不影响契约。
+ */
+export interface StoredKindRecord extends InstalledKind {
+    /** 本次安装落地的全部目录（单目录安装时就是那一个）。旧记录没有这个字段。 */
+    readonly dirs?: readonly string[];
+    /** 本次安装落地的目录名（多目录安装时用于展示与归属说明）。 */
+    readonly names?: readonly string[];
+}
+/**
+ * 安装记录表。
+ *
+ * 键是 canonicalKindKey 归一化后的仓库引用，**查询接口对任何等价拼写宽容**：
+ * 市场索引里的 repo 是原样大小写（WriteAudit/Probe-Skill-Mixed），客户端把记录体里
+ * 的 repo 原样回传给卸载 op，而表键是小写——两者不相等。修复做在**查表侧**而不是
+ * 写入侧，因为记录体的 repo 是给用户看的展示名，把它小写化会让 UI 丢掉原始大小写。
+ *
+ * 宽容只作用在 get/has/delete 的入参上；遍历（entries/values/keys）与落盘仍是每个记录
+ * 一条，所以不会出现"同一个记录在列表里显示两次"。
+ */
+export declare class KindRecordMap extends Map<string, InstalledKind> {
+    /**
+     * 按任意等价拼写取记录。
+     *
+     * 顺序：规范键 → 原样键 → 逐条比对（键与记录体 repo 都过一遍归一化）。
+     * 逐条比对是最后的兜底：旧包写的记录可能以 URL 为键、以 owner/repo 为体。
+     *
+     * @param ref - 仓库拼写。
+     * @returns 记录；不存在时 undefined。
+     */
+    get(ref: string): InstalledKind | undefined;
+    /**
+     * 是否存在等价拼写的记录。
+     * @param ref - 仓库拼写。
+     * @returns 是否存在。
+     */
+    has(ref: string): boolean;
+    /**
+     * 按任意等价拼写删除记录（删的是它真正存放时用的那个键）。
+     * @param ref - 仓库拼写。
+     * @returns 是否真的删掉了一条。
+     */
+    delete(ref: string): boolean;
+    /**
+     * 找出某个仓库拼写真正对应的键。
+     * @param ref - 仓库拼写。
+     * @returns 表中的键；不存在时 undefined。
+     */
+    keyOf(ref: string): string | undefined;
+}
+/**
+ * 组装一条安装记录（把落地结果 + 仓库身份收敛成落盘形态）。
+ *
+ * @param kind - 资源类型。
+ * @param repo - 仓库展示名（原样大小写，UI 直接展示）。
+ * @param outcome - 直装结果。
+ * @returns 可直接落盘的记录。
+ */
+export declare function kindRecordOf(kind: Exclude<MarketItemKind, 'unknown'>, repo: string, outcome: InstallOutcome): StoredKindRecord;
+/** 当前记录代数（0 表示本进程还没读过记录）。 */
+export declare function kindRecordsGeneration(): number;
+/**
+ * 读取安装记录（带进程内缓存）。
+ *
+ * 兼容读取旧包的 installed-kinds.json：两个包可能共存一段时间，用户已经装好的
+ * 技能/预设不该在新插件里"消失"。合并规则是本文件优先（同键时以我们自己的为准），
+ * 写入永远只写本文件。
+ *
+ * @returns 记录表（副本；调用方改它不影响缓存）。
+ */
+export declare function loadKindRecords(): Promise<KindRecordMap>;
+/**
+ * 写入一条记录（串行读改写）。
+ *
+ * 键走 canonicalKindKey（小写 owner/repo），记录体里的 repo 原样保留——展示名不能被
+ * 键的归一化污染，查询侧由 KindRecordMap 承担宽容。
+ *
+ * @param repoKey - 仓库引用（会被归一化）。
+ * @param record - 记录内容（可以是带 dirs/names 的落盘形态）。
+ */
+export declare function saveKindRecord(repoKey: string, record: InstalledKind | StoredKindRecord): Promise<void>;
+/**
+ * 删除一条记录（串行读改写）。
+ * @param repoKey - 仓库引用（会被归一化）。
+ * @returns 是否真的存在并被删除。
+ */
+export declare function removeKindRecord(repoKey: string): Promise<boolean>;
+/**
+ * 按任意等价拼写查一条安装记录（含它真正存放时用的键）。
+ *
+ * 这是写入侧与卸载侧应该用的显式入口：调用方拿到的是 `{ key, record }`，卸载时用 `key`
+ * 精确删除、用 `record.dirs` 精确清理目录，不再依赖"查表键恰好等于客户端回传字符串"。
+ *
+ * @param repoRef - 任意仓库拼写（owner/repo、URL、github:、展示名）。
+ * @returns 记录与其键；不存在时 undefined。
+ */
+export declare function findKindRecord(repoRef: string): Promise<{
+    readonly key: string;
+    readonly record: StoredKindRecord;
+} | undefined>;
+/**
+ * 一条记录应当清理的目录（越界的不返回）。
+ *
+ * 优先用落盘形态的 `dirs`（多目录安装也精确）；旧记录退回 `dir`。返回的目录已经过
+ * isUnderRoot 过滤——卸载是破坏性操作，宁可少删也不越界删。
+ *
+ * @param record - 安装记录。
+ * @param root - 允许的根（技能根或预设根）。
+ * @returns 应当删除的绝对目录列表（去重、保持记录顺序）。
+ */
+export declare function kindDirsOf(record: InstalledKind | StoredKindRecord, root: string): string[];
+/**
+ * 扫描技能根与预设根，找出**没有任何安装记录认领**的目录。
+ *
+ * 为什么要有它：卸载失败、用户手工放置、外部工具清理记录都会留下目录残留，而契约
+ * （KindListResult.orphans）与客户端字典都承诺展示这一节。发布一个恒为空的区块等于
+ * 让用户以为"磁盘干净"，所以这里给出真实扫描。
+ *
+ * 扫描语义（刻意保守，宁可少报也不误报）：
+ *   - 只扫根的**下一层**目录：安装永远落在根下第一层，更深层属于技能/预设自己的内容，
+ *     把它们当成"未登记目录"没有意义；
+ *   - 跳过点目录（`.dsh-preset-owner.json` 之类的标记是文件，点目录不是安装产物）；
+ *   - 认领判定：任一记录的 `dirs` 或 `dir` 等于该目录，或者（旧记录没有 `dirs`、且 `dir`
+ *     等于根本身时）该目录名等于仓库末段的 slug——即单根安装的命名规则。
+ *     旧的多目录记录无法精确归属其余子目录，按"宁可少报"处理。
+ *
+ * @param options - 根覆盖（测试用）。
+ * @returns 未登记目录的绝对路径（排序后）。
+ */
+export declare function findOrphanKindDirs(options?: {
+    readonly skillsRootDir?: string;
+    readonly presetsRootDir?: string;
+}): Promise<string[]>;
+/**
+ * 清理幽灵记录：目录被插件外部删掉（手工 rm、别的工具、临时目录清理）的记录。
+ *
+ * 进程内缓存看不到外部删除，所以每个读取面（列表、市场已安装标记）都要先调它，
+ * 否则已删的技能会永远显示"已安装"。
+ *
+ * @returns 被清掉的记录键。
+ */
+export declare function pruneGhostRecords(): Promise<string[]>;
+/** 清空记录与屏蔽名单缓存（测试用；让下一次读取重新读盘）。 */
+export declare function __resetKindCacheForTests(): void;
+/**
+ * 读取屏蔽名单（带缓存，兼容旧包的 blocked-repos.json）。
+ * @returns 归一化后的仓库引用集合（副本）。
+ */
+export declare function loadBlockedRepos(): Promise<Set<string>>;
+/**
+ * 加入屏蔽名单（检测为非三类的仓库）。
+ * @param repoKey - 仓库引用。
+ * @returns 归一化后的键。
+ */
+export declare function addBlockedRepo(repoKey: string): Promise<string>;
+/**
+ * 移出屏蔽名单（市场页"解除屏蔽"）。
+ * @param repoKey - 仓库引用。
+ * @returns 是否真的存在并被移除。
+ */
+export declare function removeBlockedRepo(repoKey: string): Promise<boolean>;
+/**
+ * 判断仓库是否被屏蔽。
+ * @param repoKey - 仓库引用。
+ * @returns 是否在屏蔽名单里。
+ */
+export declare function isBlockedRepo(repoKey: string): Promise<boolean>;
+/**
+ * 目录是否存在且是目录（供 UI/CLI 汇报"记录是否还活着"）。
+ * @param path - 绝对路径。
+ * @returns 是否为存在的目录。
+ */
+export declare function isDirectory(path: string): Promise<boolean>;