@actiondock/core 2.5.0 → 2.6.0

package/dist/app/app.d.ts

@@ -22,14 +22,19 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     private readonly options;
     private runtimeConfig;
     private isClosed;
+    /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
+    private staticActionIndex?;
+    private staticPlaybookIndex?;
     constructor(options?: ActionDockAppOptions);
     /**
      * 静态读取并聚合当前包的 Action 规范索引。
-     * 不产生全量模块导入与执行副作用。
+     * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果，
+     * 消除重复查询单次调用内的重复读盘（磁盘清单在实例生命周期内视为静态事实）。
      */
     private getStaticActionMap;
     /**
      * 静态读取并聚合当前包的 Playbook 规范索引。
+     * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果。
      */
     private getStaticPlaybookMap;
     info(options?: {
@@ -52,6 +57,14 @@ export declare class DefaultActionDockApp implements ActionDockApp {
     getConfig(key: string): Promise<ConfigValueView>;
     setConfig(key: string, value: JsonValue): Promise<void>;
     deleteConfig(key: string): Promise<boolean>;
+    /**
+     * 状态作用域统一解析辅助函数（单一事实源）。
+     *
+     * 完成重载消歧与 actionId 冲突校验，返回最终生效的命名空间：
+     * - actionId 存在时拼 接 `${actionId}:${namespace}` 或直接 actionId；
+     * - 无 actionId 时返回显式 namespace 或空字符串（包级扁平状态）。
+     */
+    private resolveStateScope;
     getState<T extends JsonValue = JsonValue>(key: string, options?: StateScopeOptions): Promise<T | undefined>;
     getState<T extends JsonValue = JsonValue>(actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
     setState<T extends JsonValue = JsonValue>(key: string, value: T, options?: StateScopeOptions): Promise<void>;

package/dist/app/app.js

@@ -1,14 +1,14 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { DefaultExecutionService } from "../execution/service.js";
 import { createDefaultPlatform } from "../platform/index.js";
-import { findProjectRoot, loadPlaybooks, loadProjectConfig } from "../project/loader.js";
-import { loadManifest } from "../project/manifest.js";
+import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { RuntimeConfig } from "../runtime/context.js";
 import { normalizeActionCollection } from "../runtime/action-collection.js";
 import { createGlobalStorage, createLazyStorage, createStorage } from "../storage/index.js";
 import { isSecretConfigKey, sanitizeConfigDefinitions } from "../storage/mask.js";
 import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
+import { buildStaticActionMap, buildStaticPlaybookMap } from "./static-index.js";
 /**
  * ActionDock 统一应用默认实现。
  * 封装并管理单个 Action Package 的执行引擎、静态元数据索引、配置与状态存储生命周期。
@@ -27,6 +27,9 @@ export class DefaultActionDockApp {
     options;
     runtimeConfig;
     isClosed = false;
+    /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
+    staticActionIndex;
+    staticPlaybookIndex;
     constructor(options = {}) {
         this.options = options;
         // 1. 确定项目根路径与配置对象
@@ -41,12 +44,9 @@ export class DefaultActionDockApp {
         if (!projectConfig && packageRoot) {
             const configPath = join(packageRoot, "actiondock.json");
             if (existsSync(configPath)) {
-                try {
-                    projectConfig = loadProjectConfig(packageRoot);
-                }
-                catch {
-                    // 忽略解析失败，使用回退配置
-                }
+                // 文件存在但解析失败（损坏 JSON、校验失败）时直接向上抛出：
+                // 仅当确实不存在 actiondock.json 文件时才允许回退默认配置，杜绝幽灵包配置
+                projectConfig = loadProjectConfig(packageRoot);
             }
         }
         if (!projectConfig) {
@@ -75,6 +75,9 @@ export class DefaultActionDockApp {
                 dataDir: options.dataDir,
                 customHome: options.customHome,
                 inMemory: options.inMemory,
+                // 默认持有者语义：App 主路径打开时收割死亡会话遗留非终态运行记录；
+                // CLI 查询旁观视图显式置 recoverOrphans: false 跳过收割
+                recoverOrphans: options.recoverOrphans !== false,
             };
             const storageFactory = this.platform.storage;
             const initStorage = () => {
@@ -113,6 +116,8 @@ export class DefaultActionDockApp {
                 customHome: options.customHome,
                 dataDir: options.dataDir,
                 inMemory: options.inMemory,
+                // 与主存储保持同侧收割语义（全局库 runs 表为空集，收割无实际副作用）
+                recoverOrphans: options.recoverOrphans !== false,
             };
             const storageFactory = this.platform.storage;
             const initGlobalStorage = () => {
@@ -153,135 +158,33 @@ export class DefaultActionDockApp {
     }
     /**
      * 静态读取并聚合当前包的 Action 规范索引。
-     * 不产生全量模块导入与执行副作用。
+     * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果，
+     * 消除重复查询单次调用内的重复读盘（磁盘清单在实例生命周期内视为静态事实）。
      */
     getStaticActionMap() {
-        const map = new Map();
-        // 1. 读取声明式清单文件 (actiondock.json)
-        if (this.packageRoot) {
-            try {
-                const manifest = loadManifest(this.packageRoot);
-                if (manifest?.actions) {
-                    for (const [id, item] of Object.entries(manifest.actions)) {
-                        map.set(id, {
-                            id,
-                            packageId: this.packageId,
-                            description: item.description,
-                            inputSchema: item.inputSchema,
-                            outputSchema: item.outputSchema,
-                            tags: item.tags ? [...item.tags] : [],
-                            annotations: item.annotations,
-                            uses: item.uses ? [...item.uses] : [],
-                            entry: item.entry,
-                            filePath: item.entry ? resolve(this.packageRoot, item.entry) : undefined,
-                        });
-                    }
-                }
-            }
-            catch {
-                // 忽略清单缺失或解析异常
-            }
-        }
-        // 2. 读取项目配置文件中声明的 actions (Manifest v2 格式)
-        if (this.projectConfig && this.projectConfig.actions) {
-            const rawActions = this.projectConfig.actions;
-            if (typeof rawActions === "object" && rawActions !== null) {
-                for (const [id, item] of Object.entries(rawActions)) {
-                    const existing = map.get(id);
-                    map.set(id, {
-                        id,
-                        packageId: this.packageId,
-                        description: item.description ?? existing?.description,
-                        inputSchema: item.inputSchema ?? existing?.inputSchema,
-                        outputSchema: item.outputSchema ?? existing?.outputSchema,
-                        tags: item.tags ?? existing?.tags,
-                        annotations: item.annotations ?? existing?.annotations,
-                        uses: item.uses ?? existing?.uses,
-                        entry: item.entry ?? existing?.entry,
-                        filePath: item.entry && this.packageRoot
-                            ? resolve(this.packageRoot, item.entry)
-                            : existing?.filePath,
-                    });
-                }
-            }
-        }
-        // 3. 读取内存显式注入的 Action 定义
-        for (const [id, act] of this.actionsMap) {
-            const existing = map.get(id);
-            const actObj = act;
-            map.set(id, {
-                id,
+        if (!this.staticActionIndex) {
+            this.staticActionIndex = buildStaticActionMap({
+                packageRoot: this.packageRoot,
                 packageId: this.packageId,
-                description: actObj.description ?? existing?.description,
-                inputSchema: actObj.inputSchema ?? existing?.inputSchema,
-                outputSchema: actObj.outputSchema ?? existing?.outputSchema,
-                tags: actObj.tags ? [...actObj.tags] : existing?.tags,
-                annotations: actObj.annotations ?? existing?.annotations,
-                uses: actObj.uses ? [...actObj.uses] : existing?.uses,
-                entry: existing?.entry,
-                filePath: existing?.filePath,
+                projectConfig: this.projectConfig,
+                actionsMap: this.actionsMap,
             });
         }
-        return map;
+        return this.staticActionIndex;
     }
     /**
      * 静态读取并聚合当前包的 Playbook 规范索引。
+     * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果。
      */
     getStaticPlaybookMap() {
-        const map = new Map();
-        // 1. 扫描磁盘规程文件
-        if (this.packageRoot) {
-            const playbooksDir = this.projectConfig?.playbooksDir || "playbooks";
-            const dirPath = join(this.packageRoot, playbooksDir);
-            if (existsSync(dirPath)) {
-                try {
-                    const loaded = loadPlaybooks(this.packageRoot, playbooksDir);
-                    for (const [id, def] of loaded) {
-                        map.set(id, {
-                            id: def.id,
-                            packageId: this.packageId,
-                            description: def.description,
-                            actions: def.actions,
-                            content: def.content,
-                            filePath: def.filePath,
-                        });
-                    }
-                }
-                catch {
-                    // 忽略规程加载异常
-                }
-            }
-        }
-        // 2. 读取项目配置文件中的 playbooks
-        if (this.projectConfig && this.projectConfig.playbooks) {
-            const rawPlaybooks = this.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 && this.packageRoot
-                        ? resolve(this.packageRoot, item.entry)
-                        : existing?.filePath;
-                    if (!content && filePath && existsSync(filePath)) {
-                        try {
-                            content = readFileSync(filePath, "utf-8");
-                        }
-                        catch {
-                            // 忽略读取异常
-                        }
-                    }
-                    map.set(id, {
-                        id,
-                        packageId: this.packageId,
-                        description: item.description ?? existing?.description,
-                        actions: item.actions ?? existing?.actions,
-                        content,
-                        filePath,
-                    });
-                }
-            }
+        if (!this.staticPlaybookIndex) {
+            this.staticPlaybookIndex = buildStaticPlaybookMap({
+                packageRoot: this.packageRoot,
+                packageId: this.packageId,
+                projectConfig: this.projectConfig,
+            });
         }
-        return map;
+        return this.staticPlaybookIndex;
     }
     async info(options) {
         const actionsMap = this.getStaticActionMap();
@@ -477,36 +380,47 @@ export class DefaultActionDockApp {
     async deleteConfig(key) {
         return await this.storage.deleteConfig(key);
     }
-    async getState(actionIdOrKey, keyOrOptions, options) {
+    /**
+     * 状态作用域统一解析辅助函数（单一事实源）。
+     *
+     * 完成重载消歧与 actionId 冲突校验，返回最终生效的命名空间：
+     * - actionId 存在时拼 接 `${actionId}:${namespace}` 或直接 actionId；
+     * - 无 actionId 时返回显式 namespace 或空字符串（包级扁平状态）。
+     */
+    resolveStateScope(actionIdOrKey, keyOrOptions, options) {
         let actionId;
-        let key;
-        let opts;
+        let resolvedOpts;
+        // 消歧规则（与原始重载语义严格一致）：仅当第二参为字符串时认定为
+        // (actionId, key, options) 形态；否则（undefined 或选项对象）认定为
+        // (key, options) 扁平调用形态，首参是状态键而非 actionId
         if (typeof keyOrOptions === "string") {
             actionId = actionIdOrKey;
-            key = keyOrOptions;
-            opts = options;
-            if (opts?.actionId && opts.actionId !== actionId) {
-                throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${opts.actionId}'`);
+            resolvedOpts = options;
+            if (resolvedOpts?.actionId && resolvedOpts.actionId !== actionId) {
+                throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${resolvedOpts.actionId}'`);
             }
         }
         else {
+            // (key, options) 扁平调用：首参是状态键，无位置 actionId；
+            // options.actionId 属于合法的显式指定，直接采纳而非判为冲突
             actionId = "";
-            key = actionIdOrKey;
-            opts = keyOrOptions;
+            resolvedOpts = keyOrOptions;
         }
-        if (!actionId && opts?.actionId) {
-            actionId = opts.actionId;
+        if (!actionId && resolvedOpts?.actionId) {
+            actionId = resolvedOpts.actionId;
         }
         const ns = actionId
-            ? (opts?.namespace ? `${actionId}:${opts.namespace}` : actionId)
-            : (opts?.namespace ?? "");
+            ? (resolvedOpts?.namespace ? `${actionId}:${resolvedOpts.namespace}` : actionId)
+            : (resolvedOpts?.namespace ?? "");
+        return { ns, opts: resolvedOpts };
+    }
+    async getState(actionIdOrKey, keyOrOptions, options) {
+        const { ns, opts } = this.resolveStateScope(actionIdOrKey, keyOrOptions, options);
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : actionIdOrKey;
         if (opts?.detail) {
             const entry = await this.storage.findState(key, ns || undefined);
             return entry;
         }
-        if (actionId) {
-            return await this.storage.getState(ns, key);
-        }
         if (ns) {
             return await this.storage.getState(ns, key);
         }
@@ -514,10 +428,10 @@ export class DefaultActionDockApp {
         return entry?.value;
     }
     async setState(actionIdOrKey, keyOrValue, valueOrOptions, options) {
-        let actionId;
         let key;
         let value;
         let opts;
+        let actionId;
         if (arguments.length >= 4) {
             if (options?.actionId && options.actionId !== actionIdOrKey) {
                 throw new Error(`Conflicting actionId specified: positional '${actionIdOrKey}' vs options.actionId '${options.actionId}'`);
@@ -563,28 +477,8 @@ export class DefaultActionDockApp {
         await this.storage.setState(targetNs, targetKey, value, opts?.ttl);
     }
     async deleteState(actionIdOrKey, keyOrOptions, options) {
-        let actionId;
-        let key;
-        let opts;
-        if (typeof keyOrOptions === "string") {
-            actionId = actionIdOrKey;
-            key = keyOrOptions;
-            opts = options;
-            if (opts?.actionId && opts.actionId !== actionId) {
-                throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${opts.actionId}'`);
-            }
-        }
-        else {
-            actionId = "";
-            key = actionIdOrKey;
-            opts = keyOrOptions;
-        }
-        if (!actionId && opts?.actionId) {
-            actionId = opts.actionId;
-        }
-        const ns = actionId
-            ? (opts?.namespace ? `${actionId}:${opts.namespace}` : actionId)
-            : (opts?.namespace ?? "");
+        const { ns } = this.resolveStateScope(actionIdOrKey, keyOrOptions, options);
+        const key = typeof keyOrOptions === "string" ? keyOrOptions : actionIdOrKey;
         if (ns) {
             return await this.storage.deleteState(ns, key);
         }
@@ -601,74 +495,53 @@ export class DefaultActionDockApp {
         return await this.storage.deleteState(targetNs, targetKey);
     }
     async getActionState(actionId, key, options) {
-        if (options?.actionId && options.actionId !== actionId) {
-            throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
-        }
-        const ns = options?.namespace ? `${actionId}:${options.namespace}` : actionId;
-        if (options?.detail) {
+        const { ns, opts } = this.resolveStateScope(actionId, key, options);
+        if (opts?.detail) {
             const entry = await this.storage.findState(key, ns || undefined);
             return entry;
         }
         return await this.storage.getState(ns, key);
     }
     async setActionState(actionId, key, value, options) {
-        if (options?.actionId && options.actionId !== actionId) {
-            throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
-        }
-        const ns = options?.namespace ? `${actionId}:${options.namespace}` : actionId;
-        await this.storage.setState(ns, key, value, options?.ttl);
+        const { ns, opts } = this.resolveStateScope(actionId, key, options);
+        await this.storage.setState(ns, key, value, opts?.ttl);
     }
     async deleteActionState(actionId, key, options) {
-        if (options?.actionId && options.actionId !== actionId) {
-            throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${options.actionId}'`);
-        }
-        const ns = options?.namespace ? `${actionId}:${options.namespace}` : actionId;
+        const { ns } = this.resolveStateScope(actionId, key, options);
         return await this.storage.deleteState(ns, key);
     }
     async listStateKeys(actionIdOrOptions, options) {
-        let actionId;
-        let opts;
+        // 重载消歧：首参为字符串时是 (actionId, options) 调用（完成冲突校验后取其域）；
+        // 否则首参本身就是选项对象（或未传），取 options.actionId 或 namespace 扁平域
+        let ns;
         if (typeof actionIdOrOptions === "string") {
-            actionId = actionIdOrOptions;
-            opts = options;
-            if (opts?.actionId && opts.actionId !== actionId) {
-                throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${opts.actionId}'`);
-            }
+            ns = this.resolveStateScope(actionIdOrOptions, "", options).ns;
         }
         else {
-            actionId = "";
-            opts = actionIdOrOptions;
+            const opts = actionIdOrOptions;
+            ns = opts?.actionId
+                ? (opts.namespace ? `${opts.actionId}:${opts.namespace}` : opts.actionId)
+                : (opts?.namespace ?? "");
         }
-        if (!actionId && opts?.actionId) {
-            actionId = opts.actionId;
-        }
-        const ns = actionId
-            ? (opts?.namespace ? `${actionId}:${opts.namespace}` : actionId)
-            : (opts?.namespace ?? null);
-        return this.storage.listStateKeys(ns, opts?.prefix);
+        const opts = typeof actionIdOrOptions === "string" ? options : actionIdOrOptions;
+        return this.storage.listStateKeys(ns ? ns : null, opts?.prefix);
     }
     async clearState(actionIdOrOptions, options) {
-        let actionId;
-        let opts;
+        // 首参为字符串时是 (actionId, options) 调用：以伪 key 消费冲突校验后取其 actionId 域；
+        // 否则首参本身就是选项对象（或未传），直接走扁平分支
         if (typeof actionIdOrOptions === "string") {
-            actionId = actionIdOrOptions;
-            opts = options;
-            if (opts?.actionId && opts.actionId !== actionId) {
-                throw new Error(`Conflicting actionId specified: positional '${actionId}' vs options.actionId '${opts.actionId}'`);
-            }
-        }
-        else {
-            actionId = "";
-            opts = actionIdOrOptions;
-        }
-        if (!actionId && opts?.actionId) {
-            actionId = opts.actionId;
+            const { ns } = this.resolveStateScope(actionIdOrOptions, "", options);
+            const finalNs = ns || (options?.namespace ?? "");
+            return this.storage.clearState({
+                namespace: finalNs ? finalNs : undefined,
+                prefix: options?.prefix,
+                all: options?.all,
+            });
         }
-        const ns = actionId
-            ? (opts?.namespace ? `${actionId}:${opts.namespace}` : actionId)
-            : (opts?.namespace ?? undefined);
+        const opts = actionIdOrOptions;
+        const ns = opts?.namespace;
         return this.storage.clearState({
-            namespace: ns,
+            namespace: ns ? ns : undefined,
             prefix: opts?.prefix,
             all: opts?.all,
         });

package/dist/app/static-index.d.ts

@@ -0,0 +1,39 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import type { ProjectConfig } from "../project/types.js";
+import type { ActionSpec, PlaybookSpec } from "./types.js";
+/**
+ * 静态清单索引构建入参：同一包的全部静态事实来源。
+ * 入参不可变（同实例内复用解析结果的前提），字段与 App 实例的运行时只读状态一一对应。
+ */
+export interface StaticIndexInput {
+    /** 包根目录（磁盘清单来源；缺省时仅聚合配置与内存注入来源） */
+    packageRoot?: string;
+    /** 包唯一标识 */
+    packageId: string;
+    /** 项目配置（Manifest v2 声明来源） */
+    projectConfig: ProjectConfig;
+}
+/** Action 索引构建入参：静态事实来源之上叠加内存注入的 Action 定义集合 */
+export interface StaticActionIndexInput extends StaticIndexInput {
+    /** 内存显式注入的 Action 定义集合 */
+    actionsMap: ReadonlyMap<string, ActionDefinition>;
+}
+/**
+ * 静态读取并聚合指定包的 Action 规范索引。
+ * 不产生全量模块导入与执行副作用。
+ *
+ * 聚合优先级（后者覆盖前者同名字段，缺省字段回退前者）：
+ * - 磁盘声明式清单文件（actiondock.json）；
+ * - 项目配置中声明的 actions（Manifest v2 格式）；
+ * - 内存显式注入的 Action 定义。
+ *
+ * 清单文件不存在属于合法空态；解析失败（损坏 JSON 等）输出告警并跳过清单部分。
+ */
+export declare function buildStaticActionMap(input: StaticActionIndexInput): Map<string, ActionSpec>;
+/**
+ * 静态读取并聚合指定包的 Playbook 规范索引。
+ *
+ * 聚合来源：磁盘规程目录扫描（以 actiondock.json 声明为事实源）与
+ * 项目配置中声明的 playbooks；同键时配置声明覆盖磁盘扫描结果。
+ */
+export declare function buildStaticPlaybookMap(input: StaticIndexInput): Map<string, PlaybookSpec>;

package/dist/app/static-index.js

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadPlaybooks } from "../project/loader.js";
+import { loadManifest, MANIFEST_FILE_NAME } from "../project/manifest.js";
+/**
+ * 静态读取并聚合指定包的 Action 规范索引。
+ * 不产生全量模块导入与执行副作用。
+ *
+ * 聚合优先级（后者覆盖前者同名字段，缺省字段回退前者）：
+ * - 磁盘声明式清单文件（actiondock.json）；
+ * - 项目配置中声明的 actions（Manifest v2 格式）；
+ * - 内存显式注入的 Action 定义。
+ *
+ * 清单文件不存在属于合法空态；解析失败（损坏 JSON 等）输出告警并跳过清单部分。
+ */
+export function buildStaticActionMap(input) {
+    const { packageRoot, packageId, projectConfig, actionsMap } = input;
+    const map = new Map();
+    // 读取声明式清单文件 (actiondock.json)
+    if (packageRoot) {
+        const manifestPath = join(packageRoot, MANIFEST_FILE_NAME);
+        // 文件不存在属于合法空态（无清单包）；解析失败（损坏 JSON 等）则输出告警并跳过清单部分
+        if (!existsSync(manifestPath)) {
+            // 合法空态：无清单文件，仅依赖后续配置与内存注入来源
+        }
+        else {
+            try {
+                const manifest = loadManifest(packageRoot);
+                if (manifest?.actions) {
+                    for (const [id, item] of Object.entries(manifest.actions)) {
+                        map.set(id, {
+                            id,
+                            packageId,
+                            description: item.description,
+                            inputSchema: item.inputSchema,
+                            outputSchema: item.outputSchema,
+                            tags: item.tags ? [...item.tags] : [],
+                            annotations: item.annotations,
+                            uses: item.uses ? [...item.uses] : [],
+                            entry: item.entry,
+                            filePath: item.entry ? resolve(packageRoot, item.entry) : undefined,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`[App] Failed to load manifest for package '${packageId}' from '${manifestPath}': ${err?.message || String(err)}`);
+            }
+        }
+    }
+    // 读取项目配置文件中声明的 actions (Manifest v2 格式)
+    if (projectConfig && projectConfig.actions) {
+        const rawActions = projectConfig.actions;
+        if (typeof rawActions === "object" && rawActions !== null) {
+            for (const [id, item] of Object.entries(rawActions)) {
+                const existing = map.get(id);
+                map.set(id, {
+                    id,
+                    packageId,
+                    description: item.description ?? existing?.description,
+                    inputSchema: item.inputSchema ?? existing?.inputSchema,
+                    outputSchema: item.outputSchema ?? existing?.outputSchema,
+                    tags: item.tags ?? existing?.tags,
+                    annotations: item.annotations ?? existing?.annotations,
+                    uses: item.uses ?? existing?.uses,
+                    entry: item.entry ?? existing?.entry,
+                    filePath: item.entry && packageRoot
+                        ? resolve(packageRoot, item.entry)
+                        : existing?.filePath,
+                });
+            }
+        }
+    }
+    // 读取内存显式注入的 Action 定义
+    for (const [id, act] of actionsMap) {
+        // 若为当前包完全限定名别名（例如 "pkgId/actionId"），跳过以防与短名 action 重复
+        if (id.startsWith(`${packageId}/`)) {
+            const shortId = id.slice(packageId.length + 1);
+            if (actionsMap.has(shortId) || map.has(shortId)) {
+                continue;
+            }
+        }
+        const existing = map.get(id);
+        const actObj = act;
+        map.set(id, {
+            id,
+            packageId,
+            description: actObj.description ?? existing?.description,
+            inputSchema: actObj.inputSchema ?? existing?.inputSchema,
+            outputSchema: actObj.outputSchema ?? existing?.outputSchema,
+            tags: actObj.tags ? [...actObj.tags] : existing?.tags,
+            annotations: actObj.annotations ?? existing?.annotations,
+            uses: actObj.uses ? [...actObj.uses] : existing?.uses,
+            entry: existing?.entry,
+            filePath: existing?.filePath,
+        });
+    }
+    return map;
+}
+/**
+ * 静态读取并聚合指定包的 Playbook 规范索引。
+ *
+ * 聚合来源：磁盘规程目录扫描（以 actiondock.json 声明为事实源）与
+ * 项目配置中声明的 playbooks；同键时配置声明覆盖磁盘扫描结果。
+ */
+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);
+        if (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,
+                });
+            }
+        }
+    }
+    return map;
+}