@actiondock/core 2.13.0 → 2.15.0

package/dist/package/static-index.js

@@ -1,7 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { loadPlaybooks } from "../project/loader.js";
-import { MANIFEST_FILE_NAME } from "../project/manifest.js";
 /**
  * 将增量声明合并到既有 Action 规范之上（纯函数，单一事实源）。
  *
@@ -86,67 +84,21 @@ export function buildStaticActionMap(input) {
 }
 /**
  * 静态读取并聚合指定包的 Playbook 规范索引。
- *
- * 聚合来源：磁盘规程目录扫描（以 actiondock.json 声明为事实源）与
- * 项目配置中声明的 playbooks；同键时配置声明覆盖磁盘扫描结果。
+ * 统一复用 project/loader 的 loadPlaybooks（单一事实源），不再自行读文件或吞异常。
  */
 export function buildStaticPlaybookMap(input) {
     const { packageRoot, packageId, projectConfig } = input;
     const map = new Map();
-    // 扫描磁盘规程文件
-    if (packageRoot) {
-        const playbooksDir = projectConfig?.playbooksDir || "playbooks";
-        const dirPath = join(packageRoot, playbooksDir);
-        const manifestPath = join(packageRoot, MANIFEST_FILE_NAME);
-        if (existsSync(manifestPath) || existsSync(dirPath)) {
-            try {
-                const loaded = loadPlaybooks(packageRoot, playbooksDir);
-                for (const [id, def] of loaded) {
-                    map.set(id, {
-                        id: def.id,
-                        packageId,
-                        description: def.description,
-                        actions: def.actions,
-                        content: def.content,
-                        filePath: def.filePath,
-                    });
-                }
-            }
-            catch (err) {
-                // 规程加载失败（清单声明非法、规程文件损坏等）输出告警并跳过磁盘部分，保持返回可用列表
-                console.warn(`[App] Failed to load playbooks for package '${packageId}' from '${dirPath}': ${err?.message || String(err)}`);
-            }
-        }
-    }
-    // 读取项目配置文件中的 playbooks
-    if (projectConfig && projectConfig.playbooks) {
-        const rawPlaybooks = projectConfig.playbooks;
-        if (typeof rawPlaybooks === "object" && rawPlaybooks !== null) {
-            for (const [id, item] of Object.entries(rawPlaybooks)) {
-                const existing = map.get(id);
-                let content = item.content ?? existing?.content ?? "";
-                let filePath = item.entry && packageRoot
-                    ? resolve(packageRoot, item.entry)
-                    : existing?.filePath;
-                if (!content && filePath && existsSync(filePath)) {
-                    try {
-                        content = readFileSync(filePath, "utf-8");
-                    }
-                    catch (err) {
-                        // 读取失败（权限、IO 错误等）输出告警并保持空正文，不再无声吞没
-                        console.warn(`[App] Failed to read playbook '${id}' content from '${filePath}' in package '${packageId}': ${err?.message || String(err)}`);
-                    }
-                }
-                map.set(id, {
-                    id,
-                    packageId,
-                    description: item.description ?? existing?.description,
-                    actions: item.actions ?? existing?.actions,
-                    content,
-                    filePath,
-                });
-            }
-        }
+    const loaded = loadPlaybooks(packageRoot || "", projectConfig.playbooksDir, projectConfig);
+    for (const [id, def] of loaded) {
+        map.set(id, {
+            id: def.id,
+            packageId,
+            description: def.description,
+            actions: def.actions,
+            content: def.content,
+            filePath: def.filePath,
+        });
     }
     return map;
 }

package/dist/package/types.d.ts

@@ -1,7 +1,7 @@
 import type { ActionDefinition, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord } from "@actiondock/sdk";
 import type { ActionInvoker, CancelResult, ExecutionTicket, LocalActionResolver } from "../execution/types.js";
 import type { InvocationContext, RunOptions } from "../invocation/types.js";
-import type { ConfigItemDefinition, ProjectConfig } from "../project/types.js";
+import type { ConfigItemDefinition, ProjectConfig, RuntimeProjectConfig } from "../project/types.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform, StorageFactory, StorageFactoryOptions } from "../platform/types.js";
 import type { RuntimeStorage, StateEntry } from "../storage/types.js";
@@ -156,8 +156,8 @@ export interface StateOptions {
 export interface PackageRuntimeOptions {
     /** 项目根目录绝对物理路径 */
     packageRoot?: string;
-    /** 项目配置文件 (actiondock.json) 对象 */
-    projectConfig?: ProjectConfig;
+    /** 项目配置文件 (actiondock.json) 对象或运行时规程来源配置 */
+    projectConfig?: ProjectConfig | RuntimeProjectConfig;
     /** 数据持久化存储目录 */
     dataDir?: string;
     /** 自定义家目录绝对路径 */
@@ -241,8 +241,8 @@ export interface PackageRuntime {
     readonly generationId?: string;
     /** 包根目录绝对物理路径 */
     readonly packageRoot?: string;
-    /** 项目配置对象（actiondock.json 解析结果） */
-    readonly projectConfig: ProjectConfig;
+    /** 项目配置对象（actiondock.json 解析结果或运行时配置） */
+    readonly projectConfig: ProjectConfig | RuntimeProjectConfig;
     /** 是否采用纯内存运行模式 */
     readonly inMemory?: boolean;
     /**

package/dist/project/index.d.ts

@@ -3,6 +3,7 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
+export * from "./skill-dir.js";
 export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 export * from "./types-generator.js";

package/dist/project/index.js

@@ -3,6 +3,7 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
+export * from "./skill-dir.js";
 export { SNAPSHOT_TRACKED_FILES, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 export * from "./types-generator.js";

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.13.0",
+            "@actiondock/sdk": "^2.15.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.13.0",
+            "@actiondock/testing": "^2.15.0",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/project/loader.d.ts

@@ -1,6 +1,6 @@
 import type { ActionDefinition } from "@actiondock/sdk";
 import { type ModuleLoader } from "../platform/module-loader.js";
-import type { ActionDockManifest, PlaybookDefinition, PlaybookManifestEntry, ProjectConfig } from "./types.js";
+import type { ActionDockManifest, PlaybookDefinition, PlaybookManifestEntry, PlaybookSourceManifest, ProjectConfig, RuntimeProjectConfig } from "./types.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
  *
@@ -16,6 +16,8 @@ export declare function findProjectRoot(cwd?: string): string | null;
  * @throws {Error} 若文件不存在或 JSON 格式错误、缺失必要字段
  */
 export declare function loadProjectConfig(projectRoot: string): ProjectConfig;
+/** 在运行时装配边界补全未声明的磁盘规程；显式规程来源（包括空集合）始终优先。 */
+export declare function completeRuntimeProjectConfig(projectRoot: string | undefined, config: RuntimeProjectConfig): RuntimeProjectConfig;
 export declare const ALLOWED_INSTALLERS: Set<string>;
 /**
  * 探测宿主系统中可用的包管理工具。
@@ -71,4 +73,4 @@ export declare function parsePlaybookContent(content: string, filePath: string,
  * @param customManifest 可选的显式清单对象（若未提供则从磁盘加载）
  * @returns Map<PlaybookId, PlaybookDefinition> 映射
  */
-export declare function loadPlaybooks(projectRoot: string, _playbooksDir?: string, customManifest?: ActionDockManifest | null): Map<string, PlaybookDefinition>;
+export declare function loadPlaybooks(projectRoot: string, _playbooksDir?: string, customManifest?: ActionDockManifest | PlaybookSourceManifest | null): Map<string, PlaybookDefinition>;

package/dist/project/loader.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { NodeModuleLoader, unwrapDefaultExport } from "../platform/module-loader.js";
 import { ActionDockError, ACTION_LOAD_FAILED, describeActionLoadFailure, INVALID_ACTION_ID, INVALID_JSON, INVALID_PACKAGE_ID, INVALID_PLAYBOOK_ID, MANIFEST_LOAD_FAILED, PLAYBOOK_NOT_FOUND, PROJECT_CONFIG_NOT_FOUND, } from "../errors.js";
-import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
+import { loadManifest, normalizeFilePlaybookEntries, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
  *
@@ -68,7 +68,7 @@ export function loadProjectConfig(projectRoot) {
         if (parsed.playbooksDir) {
             assertWithinProjectRoot(projectRoot, parsed.playbooksDir, "playbooksDir");
         }
-        return parsed;
+        return normalizeFilePlaybookEntries(parsed);
     }
     catch (err) {
         if (err instanceof ActionDockError) {
@@ -77,6 +77,15 @@ export function loadProjectConfig(projectRoot) {
         throw new ActionDockError(INVALID_JSON, `Failed to parse actiondock.json: ${err.message}`);
     }
 }
+/** 在运行时装配边界补全未声明的磁盘规程；显式规程来源（包括空集合）始终优先。 */
+export function completeRuntimeProjectConfig(projectRoot, config) {
+    if (!projectRoot || config.playbooks !== undefined)
+        return config;
+    const diskManifest = loadManifest(projectRoot);
+    return diskManifest?.playbooks === undefined
+        ? config
+        : { ...config, playbooks: diskManifest.playbooks };
+}
 export const ALLOWED_INSTALLERS = new Set(["npm", "bun"]);
 /**
  * 异步探测包管理器可用性（通过执行 --version 并检查退出码）。
@@ -308,43 +317,38 @@ export function parsePlaybookContent(content, filePath, metadata) {
  */
 export function loadPlaybooks(projectRoot, _playbooksDir = "playbooks", customManifest) {
     const playbooks = new Map();
-    let manifest = null;
-    if (customManifest !== undefined) {
-        manifest = customManifest;
-    }
-    else {
-        try {
-            manifest = loadManifest(projectRoot);
+    const isExplicitSource = customManifest !== undefined;
+    const manifest = isExplicitSource
+        ? customManifest
+        : projectRoot ? loadManifest(projectRoot) : null;
+    for (const [playbookId, entry] of Object.entries(manifest?.playbooks || {})) {
+        if (!PLAYBOOK_ID_REGEX.test(playbookId)) {
+            throw new ActionDockError(INVALID_PLAYBOOK_ID, `Invalid playbook ID '${playbookId}' in manifest. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
         }
-        catch (err) {
-            // 容错与可观测性取舍说明：
-            // - 工程无清单时 loadManifest 返回 null，按空规程集处理属正常场景；
-            // - 清单文件存在但内容损坏或解析失败时，记录可观测警告后安全降级，避免静默吞没异常。
-            const reason = err instanceof Error ? err.message : String(err ?? "Unknown error");
-            process.stderr.write(`[actiondock] Warning: Failed to load manifest in ${projectRoot}: ${reason}\n`);
-            return playbooks;
+        let content;
+        let filePath;
+        if (isExplicitSource && "content" in entry && typeof entry.content === "string") {
+            // 真实内联来源（包括空字符串）无需访问磁盘。
+            content = entry.content;
+            filePath = entry.entry ? (projectRoot ? resolve(projectRoot, entry.entry) : entry.entry) : "";
         }
-    }
-    // 以 actiondock.json 为唯一事实源
-    if (manifest?.playbooks && Object.keys(manifest.playbooks).length > 0) {
-        for (const [playbookId, pbEntry] of Object.entries(manifest.playbooks)) {
-            if (!PLAYBOOK_ID_REGEX.test(playbookId)) {
-                throw new ActionDockError(INVALID_PLAYBOOK_ID, `Invalid playbook ID '${playbookId}' in actiondock.json. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
+        else {
+            if (!entry.entry || typeof entry.entry !== "string") {
+                throw new ActionDockError(PLAYBOOK_NOT_FOUND, `Playbook entry for '${playbookId}' must specify a valid file path or explicit inline content`);
             }
-            const fullPath = resolve(projectRoot, pbEntry.entry);
-            assertPathWithinRoot(projectRoot, fullPath, `playbook entry '${pbEntry.entry}'`);
-            if (!existsSync(fullPath)) {
-                throw new ActionDockError(PLAYBOOK_NOT_FOUND, `Playbook file '${pbEntry.entry}' for '${playbookId}' not found in ${projectRoot}`);
+            filePath = resolve(projectRoot, entry.entry);
+            assertPathWithinRoot(projectRoot, filePath, `playbook entry '${entry.entry}'`);
+            if (!existsSync(filePath)) {
+                throw new ActionDockError(PLAYBOOK_NOT_FOUND, `Playbook file '${entry.entry}' for '${playbookId}' not found in ${projectRoot}`);
             }
-            const content = readFileSync(fullPath, "utf-8");
-            const def = parsePlaybookContent(content, fullPath, {
-                id: playbookId,
-                name: pbEntry?.name,
-                description: pbEntry.description,
-                actions: pbEntry.actions,
-            });
-            playbooks.set(playbookId, def);
+            content = readFileSync(filePath, "utf-8");
         }
+        playbooks.set(playbookId, parsePlaybookContent(content, filePath, {
+            id: playbookId,
+            name: entry.name,
+            description: entry.description,
+            actions: entry.actions,
+        }));
     }
     return playbooks;
 }

package/dist/project/manifest.d.ts

@@ -2,6 +2,8 @@ import type { ActionDockManifest } from "./types.js";
 export declare const MANIFEST_FILE_NAME = "actiondock.json";
 export declare const ACTION_ID_REGEX: RegExp;
 export declare const PLAYBOOK_ID_REGEX: RegExp;
+/** 磁盘规程始终采用文件声明，不能把非契约 content 字段带入运行时内联来源。 */
+export declare function normalizeFilePlaybookEntries(manifest: ActionDockManifest): ActionDockManifest;
 /**
  * 读取并解析项目的声明式清单文件（actiondock.json 为唯一事实源）。
  * 若文件不存在则返回 null。

package/dist/project/manifest.js

@@ -5,6 +5,22 @@ import { ActionDockError, MANIFEST_CORRUPTED, MANIFEST_INVALID, MANIFEST_READ_FA
 export const MANIFEST_FILE_NAME = "actiondock.json";
 export const ACTION_ID_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
 export const PLAYBOOK_ID_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
+/** 磁盘规程始终采用文件声明，不能把非契约 content 字段带入运行时内联来源。 */
+export function normalizeFilePlaybookEntries(manifest) {
+    if (!manifest.playbooks || typeof manifest.playbooks !== "object" || Array.isArray(manifest.playbooks)) {
+        return manifest;
+    }
+    let changed = false;
+    const playbooks = Object.fromEntries(Object.entries(manifest.playbooks).map(([id, entry]) => {
+        if (entry && typeof entry === "object" && "content" in entry) {
+            const { content: _inlineContent, ...fileEntry } = entry;
+            changed = true;
+            return [id, fileEntry];
+        }
+        return [id, entry];
+    }));
+    return changed ? { ...manifest, playbooks } : manifest;
+}
 /**
  * 读取并解析项目的声明式清单文件（actiondock.json 为唯一事实源）。
  * 若文件不存在则返回 null。
@@ -38,7 +54,7 @@ export function loadManifest(projectRoot) {
     if (!parsed.id) {
         parsed.id = basename(projectRoot);
     }
-    return parsed;
+    return normalizeFilePlaybookEntries(parsed);
 }
 /**
  * 保存声明式清单文件至项目根目录（actiondock.json）。

package/dist/project/skill-dir.d.ts

@@ -0,0 +1,72 @@
+import type { ProjectConfig } from "./types.js";
+/**
+ * 本地包条目；是否构成封闭集合由校验入口保证。
+ */
+export interface LocalPackageEntry {
+    packageId: string;
+    packageRoot: string;
+    projectConfig: ProjectConfig;
+}
+/**
+ * 本地技能 / 包目录发现视图，不代表已经通过封闭集合校验。
+ */
+export interface LocalSkillDirectory {
+    type: "single" | "composite";
+    root: string;
+    packages: LocalPackageEntry[];
+}
+/**
+ * 判定路径字符串是否为显式文件/目录路径形态（而非包标识符）。
+ *
+ * 规则：
+ * - 以 .、/、~ 开头；
+ * - 包含 / 或 \\，且不是 scoped 包（@scope/name 仅含一个 /）；
+ * - scoped 包若包含反斜杠或多于一个 /，亦视作路径。
+ */
+export declare function isExplicitPath(p: string): boolean;
+/**
+ * 对明确的本地封闭包集合实施一致性校验。
+ *
+ * 校验规则：
+ * - 重复包标识防护：集合内不得存在相同 packageId；
+ * - 依赖存在性与版本兼容性：声明的直接依赖必须在集合内存在且满足语义版本约束（复用 PackageGraphBuilder）；
+ * - 跨包 uses 目标完整性：uses 声明引用的目标包与目标 Action 必须在集合内存在。
+ *
+ * @param packages 封闭包条目集合
+ */
+export declare function validateLocalSkillPackages(packages: Array<{
+    packageId: string;
+    packageRoot: string;
+    projectConfig: ProjectConfig;
+}>): void;
+/**
+ * 发现本地 Skill / 包目录结构（支持单包根目录与 packages/* 复合套件布局）。
+ * 仅执行物理布局发现与清单加载，不执行跨包封闭依赖集合校验。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export declare function discoverLocalSkillDirectory(directoryPath: string, cwd?: string): LocalSkillDirectory | null;
+/**
+ * 查询指定路径的本地包或技能目录（供 info / 查询命令使用）。
+ * 单包不要求 node_modules 依赖闭包；复合目录仍要求封闭集合完整。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export declare function queryLocalPackageDirectory(directoryPath: string, cwd?: string): LocalSkillDirectory | null;
+/**
+ * 探测指定路径是否为本地 Skill / 包目录（支持单包根目录与 packages/* 复合套件布局）。
+ *
+ * 封闭包装配与校验规则：
+ * - 符号链接按目录布局正常解析；Action 与规程入口的文件边界由相应加载器校验；
+ * - 单包布局：目录根部存在 actiondock.json，解析为包含单一包的 LocalSkillDirectory；
+ * - 复合布局：目录根部存在 packages/ 目录，遍历其直接子目录，收集包含 actiondock.json 的子包；
+ * - 集合一致性校验：通过 validateLocalSkillPackages 严格核查依赖闭包、版本兼容与 uses 目标；
+ * - 异常透传：坏清单或权限异常原样抛出，严禁静默回退 Registry；
+ * - 若非候选技能目录，返回 null。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export declare function inspectLocalPackageDirectory(directoryPath: string, cwd?: string): LocalSkillDirectory | null;

package/dist/project/skill-dir.js

@@ -0,0 +1,244 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ActionDockError, ACTION_NOT_FOUND, PACKAGE_NOT_FOUND, PACKAGE_ID_CONFLICT, } from "../errors.js";
+import { loadProjectConfig } from "./loader.js";
+import { PackageGraphBuilder } from "../catalog/graph.js";
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { createPackageIdentity } from "../runtime/identity.js";
+/**
+ * 判定路径字符串是否为显式文件/目录路径形态（而非包标识符）。
+ *
+ * 规则：
+ * - 以 .、/、~ 开头；
+ * - 包含 / 或 \\，且不是 scoped 包（@scope/name 仅含一个 /）；
+ * - scoped 包若包含反斜杠或多于一个 /，亦视作路径。
+ */
+export function isExplicitPath(p) {
+    if (!p)
+        return false;
+    if (p.startsWith("@")) {
+        const slashCount = (p.match(/\//g) || []).length;
+        return slashCount > 1 || p.includes("\\");
+    }
+    return (p.startsWith(".") ||
+        p.startsWith("/") ||
+        p.startsWith("~") ||
+        p.includes("/") ||
+        p.includes("\\"));
+}
+/**
+ * 对明确的本地封闭包集合实施一致性校验。
+ *
+ * 校验规则：
+ * - 重复包标识防护：集合内不得存在相同 packageId；
+ * - 依赖存在性与版本兼容性：声明的直接依赖必须在集合内存在且满足语义版本约束（复用 PackageGraphBuilder）；
+ * - 跨包 uses 目标完整性：uses 声明引用的目标包与目标 Action 必须在集合内存在。
+ *
+ * @param packages 封闭包条目集合
+ */
+export function validateLocalSkillPackages(packages) {
+    if (!packages || packages.length === 0)
+        return;
+    // 1. 重复 packageId 校验
+    const seenIds = new Set();
+    for (const pkg of packages) {
+        if (seenIds.has(pkg.packageId)) {
+            throw new ActionDockError(PACKAGE_ID_CONFLICT, `Package ID conflict: package '${pkg.packageId}' is declared more than once in skill packages`);
+        }
+        seenIds.add(pkg.packageId);
+    }
+    // 2. 构造包发现视图并交由 PackageGraphBuilder 校验依赖与版本
+    const discovered = packages.map((pkg) => ({
+        id: pkg.packageId,
+        root: pkg.packageRoot,
+        manifest: pkg.projectConfig,
+        identity: createPackageIdentity({
+            id: pkg.packageId,
+            instanceId: `${pkg.packageId}:${pkg.packageRoot}`,
+            generation: "skill-local",
+        }),
+        isCurrentProject: true,
+    }));
+    const builder = new PackageGraphBuilder({
+        packages: discovered,
+        validateDependencies: true,
+    });
+    builder.buildSync();
+    // 3. uses 声明目标存在性校验
+    const pkgMap = new Map();
+    for (const pkg of packages) {
+        pkgMap.set(pkg.packageId, pkg.projectConfig);
+    }
+    const validateUseRef = (rawRef, caller, currentPkg) => {
+        if (typeof rawRef !== "string" || !rawRef.trim())
+            return;
+        const trimmed = rawRef.trim();
+        // 先按完整包身份识别裸包引用，包括 scoped 包。
+        if (pkgMap.has(trimmed)) {
+            return;
+        }
+        // 裸 scoped 包只有一个斜杠，不能按限定动作拆分。
+        if (trimmed.startsWith("@") && (trimmed.match(/\//g) || []).length === 1) {
+            throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${trimmed}' referenced by uses in '${caller}' was not found in skill directory`);
+        }
+        // 限定动作与包级通配符复用统一引用解析器。
+        if (trimmed.includes("/")) {
+            const ref = parseActionRef(trimmed);
+            const targetPkgId = ref.packageId;
+            const targetActionId = ref.actionId;
+            const targetPkg = pkgMap.get(targetPkgId);
+            if (!targetPkg) {
+                throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${targetPkgId}' referenced by uses in '${caller}' was not found in skill directory`);
+            }
+            if (targetActionId !== "*") {
+                const hasAction = Boolean(targetPkg.actions && targetPkg.actions[targetActionId]);
+                if (!hasAction) {
+                    throw new ActionDockError(ACTION_NOT_FOUND, `Action '${targetActionId}' referenced by uses in '${caller}' was not found in package '${targetPkgId}'`);
+                }
+            }
+            return;
+        }
+        // 本包短动作引用。
+        if (currentPkg.actions && currentPkg.actions[trimmed]) {
+            return;
+        }
+        // 目标不存在。
+        throw new ActionDockError(PACKAGE_NOT_FOUND, `Package or action '${trimmed}' referenced by uses in '${caller}' was not found in skill directory`);
+    };
+    for (const pkg of packages) {
+        const pkgUses = pkg.projectConfig.uses;
+        if (Array.isArray(pkgUses)) {
+            for (const ref of pkgUses) {
+                validateUseRef(ref, `package '${pkg.packageId}'`, pkg.projectConfig);
+            }
+        }
+        if (pkg.projectConfig.actions && typeof pkg.projectConfig.actions === "object") {
+            for (const [actionId, actionEntry] of Object.entries(pkg.projectConfig.actions)) {
+                if (actionEntry && Array.isArray(actionEntry.uses)) {
+                    for (const ref of actionEntry.uses) {
+                        validateUseRef(ref, `action '${pkg.packageId}/${actionId}'`, pkg.projectConfig);
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * 发现本地 Skill / 包目录结构（支持单包根目录与 packages/* 复合套件布局）。
+ * 仅执行物理布局发现与清单加载，不执行跨包封闭依赖集合校验。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export function discoverLocalSkillDirectory(directoryPath, cwd) {
+    if (!directoryPath || typeof directoryPath !== "string") {
+        return null;
+    }
+    const absDir = resolve(cwd || process.cwd(), directoryPath);
+    if (!existsSync(absDir)) {
+        return null;
+    }
+    try {
+        const stat = statSync(absDir);
+        if (!stat.isDirectory()) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    // 单包布局：根目录包含 actiondock.json
+    const rootManifest = join(absDir, "actiondock.json");
+    if (existsSync(rootManifest)) {
+        const config = loadProjectConfig(absDir);
+        const packages = [
+            {
+                packageId: config.id,
+                packageRoot: absDir,
+                projectConfig: config,
+            },
+        ];
+        return {
+            type: "single",
+            root: absDir,
+            packages,
+        };
+    }
+    // 复合 Skill 布局：存在 packages/ 目录且包含至少一个有效子包
+    const packagesDir = join(absDir, "packages");
+    if (existsSync(packagesDir)) {
+        const pStat = statSync(packagesDir);
+        if (pStat.isDirectory()) {
+            const entries = readdirSync(packagesDir, { withFileTypes: true });
+            const packages = [];
+            const seenIds = new Set();
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                const subDir = join(packagesDir, entry.name);
+                const sStat = statSync(subDir);
+                if (sStat.isDirectory()) {
+                    const subManifest = join(subDir, "actiondock.json");
+                    if (existsSync(subManifest)) {
+                        const childConfig = loadProjectConfig(subDir);
+                        if (seenIds.has(childConfig.id)) {
+                            throw new ActionDockError(PACKAGE_ID_CONFLICT, `Package ID conflict: package '${childConfig.id}' is declared more than once in skill directory '${absDir}'`);
+                        }
+                        seenIds.add(childConfig.id);
+                        packages.push({
+                            packageId: childConfig.id,
+                            packageRoot: subDir,
+                            projectConfig: childConfig,
+                        });
+                    }
+                }
+            }
+            if (packages.length > 0) {
+                return {
+                    type: "composite",
+                    root: absDir,
+                    packages,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 查询指定路径的本地包或技能目录（供 info / 查询命令使用）。
+ * 单包不要求 node_modules 依赖闭包；复合目录仍要求封闭集合完整。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export function queryLocalPackageDirectory(directoryPath, cwd) {
+    const discovered = discoverLocalSkillDirectory(directoryPath, cwd);
+    if (!discovered) {
+        return null;
+    }
+    if (discovered.type === "composite") {
+        validateLocalSkillPackages(discovered.packages);
+    }
+    return discovered;
+}
+/**
+ * 探测指定路径是否为本地 Skill / 包目录（支持单包根目录与 packages/* 复合套件布局）。
+ *
+ * 封闭包装配与校验规则：
+ * - 符号链接按目录布局正常解析；Action 与规程入口的文件边界由相应加载器校验；
+ * - 单包布局：目录根部存在 actiondock.json，解析为包含单一包的 LocalSkillDirectory；
+ * - 复合布局：目录根部存在 packages/ 目录，遍历其直接子目录，收集包含 actiondock.json 的子包；
+ * - 集合一致性校验：通过 validateLocalSkillPackages 严格核查依赖闭包、版本兼容与 uses 目标；
+ * - 异常透传：坏清单或权限异常原样抛出，严禁静默回退 Registry；
+ * - 若非候选技能目录，返回 null。
+ *
+ * @param directoryPath 待检查的目录路径（相对路径将基于 cwd 解析）
+ * @param cwd 解析基准工作目录（默认为 process.cwd()）
+ */
+export function inspectLocalPackageDirectory(directoryPath, cwd) {
+    const discovered = discoverLocalSkillDirectory(directoryPath, cwd);
+    if (!discovered) {
+        return null;
+    }
+    validateLocalSkillPackages(discovered.packages);
+    return discovered;
+}