@actiondock/core 2.6.0 → 2.8.0

package/README.md

@@ -1,115 +1,108 @@
 # @actiondock/core
 
-ActionDock 2.0 核心领域模型与调度引擎。
+ActionDock 2.x Node-first 原生运行时与核心领域。
 
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-`@actiondock/core` 承载 ActionDock 的领域对象、状态机、数据目录排他锁、统一调用门面、依赖事务管理与执行服务，是与具体宿主环境解耦的通用内核。
+`@actiondock/core` 是 ActionDock 2.x 的核心领域内核与 Node-first 原生运行时。统一暴露最小化核心服务门面（`createActionDock`、`connectActionDock`）、标准服务端口体系（`DiscoveryPort`、`ExecutionPort`、`RunsPort`、`EventsPort`、`ConfigPort`、`StatePort`）、统一错误模型（`ActionDockError`）、原生平台装配（`createNodePlatform`）、服务启动（`startActionDockServer`）与包图依赖契约（`PackageGraph`），内部驱动存储引擎、受管进程与 HTTP 网络服务。
 
 ---
 
-## 统一调用门面与异常
+## 子路径导出规范
 
-### ActionDockTarget 统一调用门面
+为保障边界清晰与根入口极简，`@actiondock/core` 提供精细化子路径导出：
 
-[ActionDockTarget](./src/target/types.ts) 为命令行工具、上层服务与应用集成屏蔽本地执行、远程服务与跨进程通信的物理拓扑差异：
-
-- 本地门面 LocalTarget：直接调用本地加载的 ActionDockApp 或 ActionDockHost 实例，在同进程内高效执行。
-- 远程门面 RemoteTarget：通过 HTTP 协议与远程 ActionDock 服务通信，支持鉴权令牌与请求超时控制。
-- 跨进程门面 IpcTarget：通过 Node.js 进程间通信通道与子进程交互，包含诊断流速率保护与反压控制。
-
-### TargetError 结构化异常
-
-[TargetError](./src/target/types.ts) 继承标准 Error，提供机器可读的结构化错误码与附加详情：
-
-- `TARGET_PROTOCOL_UNSUPPORTED`：协议版本或特性不受支持。
-- `TARGET_CAPABILITY_UNAVAILABLE`：目标端未启用或缺失所需能力。
-- `TARGET_RESULT_UNKNOWN`：连接超时或中断导致执行结果状态未知。
+- `.`：核心公共根入口，仅暴露 minimal 服务门面、服务端口、平台工厂与核心契约。
+- `./server`：HTTP 服务容器、路由分发、TLS 安全与服务端守护进程。
+- `./project`：项目元数据、清单与依赖管理、依赖闭包及原子事务。
+- `./registry`：包注册表、软链接治理与包根目录寻址。
+- `./profile`：远程连接配置与管理客户端。
+- `./graph`：包图模型与动作目录解析。
+- `./package`：包级运行时、存储驱动与参数解析工具。
 
 ---
 
-## 数据目录锁与故障恢复
-
-[DataDirLock](./src/storage/data-dir-lock.ts) 在数据目录下维护 `.actiondock.data.lock` 排他文件锁，记录宿主主进程与受管子进程状态，防止多实例并发冲突：
-
-- `DATA_DIR_IN_USE`：检测到已有活跃宿主主进程正在持有该数据目录，拒绝并发启动。
-- `DATA_DIR_RECOVERY_REQUIRED`：检测到前序宿主主进程异常退出，但仍有关联受管子进程处于运行状态，触发故障恢复拦截。
-- 正常退出时自动释放并移除锁文件；非正常退出且无任何残留进程时允许安全接管。
-
----
+## 统一执行主链
 
-## 依赖管理与锁定规范
+ActionDock 2.x 将所有调用形态（命令行、协议服务、微服务与测试沙箱）收敛至统一的确定性执行主链：
 
-基于 `actiondock.lock.json`（规范版本 `lockfileVersion: 1`）提供严格的依赖版本锁定与原子事务保护：
+```text
+Service -> Resolution -> PackageRuntime -> ExecutionService -> ActionRunner -> Action
+```
 
-- 依赖解析：[ActionPackageResolver](./src/project/resolver.ts) 递归解析本地包依赖与符号链接，避免重复加载。
-- 原子事务：[beginTransaction](./src/project/transactions.ts) 在执行依赖增删（如 `ad add` 与 `ad remove`）前为 `package.json`、`actiondock.json` 与 `actiondock.lock.json` 创建磁盘快照。若安装或校验流程失败，自动执行原子回滚并恢复原始状态。
+- 服务接入：通过统一服务门面或标准服务端口接收外部调用请求与入参数据。
+- 解析定位：通过 `resolveAction` 依赖单一事实源完成动作寻址与跨包引用消歧。
+- 运行时装配：基于包图节点构建隔离的包级执行上下文与依赖环境。
+- 执行协调：统筹并发配额、追踪根调用与协同取消信号。
+- 动作执行：驱动单一终态状态机，执行入参出参模式校验、循环依赖拦截与状态持久化。
+- 业务执行：执行开发者编写的纯粹业务逻辑并产出强类型结果。
 
 ---
 
-## 核心领域模型
+## 统一服务门面与标准服务端口
 
-- ProjectConfig：定义在 `actiondock.json` 中的项目规范，包含包标识、名称、版本号、目录配置以及配置项元数据。
-- PlaybookDefinition：智能体操作规程定义，由 Markdown 文本与其头部 YAML 元数据构成，静态记录任务步骤与调用的 Action 依赖列表。
-- ConfigItemDefinition：单项配置规范，涵盖默认值、类型约束、敏感脱敏标记及绑定的外部环境变量。
+### 统一服务门面
 
----
+通过顶层工厂函数提供无缝屏蔽本地与远程拓扑差异的服务门面：
 
-## 关键抽象契约
+- 本地服务门面 `createActionDock`：创建本地 `ActionDockService` 服务端口实例，在当前 Node.js 进程内装配原生运行时驱动并高效执行。
+- 远端服务门面 `connectActionDock`：创建远端 `ActionDockService` 服务端口实例，通过 HTTP 协议与远端 ActionDock 服务通信，支持鉴权令牌、请求超时控制与证书安全校验。
 
-### SqliteDriver 驱动接口
+### 标准服务端口体系
 
-解耦底层数据库实现，提供一致的参数化执行与事务契约：
+系统将所有对外能力解耦并收敛为六大标准服务端口契约：
 
-- `exec(sql: string): void`：执行无返回值的 SQL 语句。
-- `prepare(sql: string): SqliteStatement`：编译 SQL 模板，生成预编译语句对象。
-- `transaction<T>(fn: () => T): T`：同步事务执行器，在出现异常时自动回滚，并在驱动层严格拦截异步 Promise 以避免事务泄漏。
-- `close(): void`：释放数据库连接与文件句柄。
+- 发现端口 `DiscoveryPort`：负责包与动作的元数据发现、清单检索、全文过滤与规程查询。
+- 执行端口 `ExecutionPort`：负责动作的同步阻塞执行（`run`）与异步启动执行（`start`）。
+- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询与协同取消（`cancel`）。
+- 事件端口 `EventsPort`：负责任务执行实时事件流订阅。
+- 配置端口 `ConfigPort`：负责运行时分层配置读取、持久化配置管理与环境变量满足度体检。
+- 状态端口 `StatePort`：负责包级与动作级持久化键值存取、前缀列举与过期清理。
 
-### ProcessDriver 进程驱动契约与受管进程架构
+---
 
-Core 层内置完整的工业级受管进程治理体系，全面解耦具体操作系统运行时：
+## 单一事实源架构原则
 
-- ProcessManager 进程调度引擎：承载受管进程全生命周期状态机（`starting`、`running`、`stopping`、`exited`、`failed`、`lost`），提供独占控制权令牌分配与续租排队、有界环形输出日志管理、输入队列异步调度、资源硬性限额与宿主/作用域配额审计。
-- ContextProcessAPI 运行上下文适配器：将 ProcessAPI 绑定至具体的 ActionContext 执行链路，自动注入所有者身份与运行标识，跟踪持有的控制令牌；当 Run 结束或异常而未显式释放控制权时，自动触发目标进程隔离或终止。
-- ProcessDriver 平台驱动契约：定义平台底层派生与进程控制的抽象接口（`getCapabilities`、`spawn`、`write`、`inputEOF`、`terminate` 等），屏蔽各操作系统底层实现差异。
-- ProcessOutputLog 有界环形输出日志：单进程独立的有界内存日志缓冲区，支持基于字节游标的分页查询与长轮询等待，自动识别缓冲区淘汰断层。
-- ProcessMetadataStore 元数据存储接口：提供进程运行记录与幂等请求键索引的持久化抽象，默认提供纯内存实现 MemoryProcessMetadataStore。
-- ProcessExecutor 进程执行器接口：抽象跨平台的子进程操作，向后兼容一次性命令执行。
+ActionDock 2.x 全面贯彻单一事实源设计，彻底杜绝各模块私自实现短名搜索或启发式猜测：
+
+- 包图发现单一事实源 `PackageDiscovery`：自顶向下扫描工作区与全局注册表，建立包目录索引。
+- 包拓扑图单一事实源 `PackageGraph`：维护包节点身份标识、实例版本与拓扑依赖关系。
+- 动作目录单一事实源 `ActionCatalog`：统一聚合索引所有已加载包的动作元数据，提供确定性的多维检索能力。
+- 动作解析单一事实源 `resolveAction`：作为全系统动作引用的唯一解析函数。优先支持包限定斜杠语法（`<package-id>/<action-id>`）与当前调用方所属包优先匹配；严格禁止冒号历史语法（`pkg:action`）。
+- 调用治理策略单一事实源 `InvocationPolicy`：统筹管理根任务最大并发配额（默认 32）、子任务并发上限（默认 64）与最大调用嵌套深度（默认 16）。
 
 ---
 
-## 执行核心与状态机
+## 原生运行时驱动
 
-### ActionRunner 执行状态机
+`@actiondock/core` 深度集成 Node.js 24 原生能力，无需编译外部二进制扩展：
 
-[ActionRunner](./src/execution/runner.ts) 是单个 Action 执行的核心引擎，负责完整的生命周期状态流转与契约保障：
+- 原生存储驱动 `NodeSqliteDriver`：基于 Node.js 原生 `node:sqlite`（`DatabaseSync`）构建同步存储驱动。默认启用预写日志模式（WAL）、外键约束检查与忙等待超时。
+- 受管进程平台驱动 `NodeProcessDriver`：实现完整的受管进程治理体系。基于管道彻底切断子进程与宿主标准流的物理连通；支持跨平台独立进程组管理与信号派发；提供独占控制权租约、逐流增量读取与优雅终止。
+- 原生网络服务容器 `NodeHttpServer`：基于 Node.js 原生 `node:http` 承载 RESTful 微服务与 Server-Sent Events 事件流。
+- 原生模块加载器 `NodeModuleLoader`：基于 Node.js 原生类型擦除机制直接加载 TypeScript 源码，免除前置编译转译开销。
+- 原生文件系统抽象 `NodeFileSystem`：提供跨平台文件读写与原子文件事务保障。
 
-- 调用链环路检测：基于调用栈跟踪，当检测到依赖循环调用时立即拦截并返回错误信封。
-- 模式严格校验：在 Action 执行前校验输入数据是否满足模式规范，校验失败时直接阻断并生成结构化诊断信息。
-- 运行记录持久化：在 SQLite 中写入 `running` 状态记录，并在结束时流转至对应终态。
-- 生命周期状态转换：涵盖 `running`、`success`、`failed`、`timed_out`、`cancelled`、`interrupted` 状态。
-- 上下文环境合成：动态构建 ActionContext，集成配置优先级解析器、状态存储器与标准错误流日志记录器。
+---
 
-### DefaultExecutionService 统一执行服务
+## 数据目录锁与故障自愈
 
-[DefaultExecutionService](./src/execution/service.ts) 负责系统层面的并发控制、任务追踪与生命周期协同：
+通过 `DataDirLock` 在数据目录下维护 `.actiondock.data.lock` 排他文件锁，记录宿主进程与受管子进程状态：
 
-- 并发度控制：维护活跃任务表，支持配置系统最大并发上限，超限时排队或拒绝。
-- 全链路追踪：为每次执行分配全局唯一的根运行标识与父子调用关联。
-- 协同取消传播：支持根据运行标识获取执行句柄，向下游所有派生子任务广播取消信号。
-- 事件汇聚分发：将执行过程中的状态变更事件统一推送到事件接收器中。
+- 活跃进程冲突防护：检测到已有活跃宿主主进程正在持有该数据目录时，抛出 `DATA_DIR_IN_USE` 错误拒绝并发启动。
+- 孤儿进程保护：检测到前序宿主主进程异常退出但仍有关联受管子进程处于运行状态时，抛出 `DATA_DIR_RECOVERY_REQUIRED` 错误，阻止脏写并等待子进程回收。
+- 故障自动恢复：前序宿主进程与关联子进程均已死亡时，当前宿主自动接管排他锁并安全清理残留会话。
 
 ---
 
-## 运行时可插拔设计
+## 依赖管理与原子事务
 
-`@actiondock/core` 保持平台中立，不绑定任何特定运行环境：
+基于 `actiondock.lock.json`（规范版本 `lockfileVersion: 1`）提供严格的依赖版本锁定与原子事务保护：
 
-- 在日常生产与 Node.js 运行时中，通过 [@actiondock/runtime-node](../runtime-node/README.md) 注入默认同步存储驱动与 Node.js 进程执行器（另有独立异步驱动 WorkerSqliteDriver 可选）。
-- 在自动化测试中，通过 [@actiondock/testing](../testing/README.md) 注入纯内存存储驱动 MemoryStorage 与模拟进程执行器 MockProcessExecutor。
+- 依赖图构建：`PackageGraphBuilder` 递归解析本地包依赖与符号链接，统一建立拓扑图并检测版本冲突。
+- 原子事务：`beginTransaction` 在执行依赖增删（如 `ad add` 与 `ad remove`）前为 `package.json`、`actiondock.json` 与 `actiondock.lock.json` 创建快照。若安装或校验流程失败，自动执行原子回滚并恢复原始状态。
 
 ---
 

package/dist/catalog/action-catalog.d.ts

@@ -0,0 +1,56 @@
+import type { ActionContract, ActionRef } from "@actiondock/sdk";
+import type { PackageIdentity } from "../runtime/identity.js";
+import type { PackageGraph } from "./graph.js";
+/**
+ * 动作目录候选条目规范。
+ */
+export interface ActionCandidate {
+    /** 所属包唯一逻辑标识 */
+    readonly packageId: string;
+    /** 所属包唯一身份标识值对象 */
+    readonly packageIdentity: PackageIdentity;
+    /** 动作唯一标识符 */
+    readonly actionId: string;
+    /** 动作契约元数据定义 */
+    readonly contract: ActionContract;
+    /** 动作执行入口相对文件路径 */
+    readonly entry: string;
+    /** 所属包根目录绝对物理路径 */
+    readonly packageRoot: string;
+}
+/**
+ * 动作目录索引 ActionCatalog 契约。
+ */
+export interface ActionCatalog {
+    /**
+     * 按动作引用查找候选动作列表。
+     * 若指定了 packageId，仅匹配对应包；若未指定 packageId，返回全部同名候选。
+     */
+    find(ref: ActionRef | string): ActionCandidate[];
+    /**
+     * 获取已索引候选动作集合（可选限定指定包）。
+     */
+    list(packageId?: string): ActionCandidate[];
+    /**
+     * 精确获取特定包内的特定动作候选。
+     */
+    get(packageId: string, actionId: string): ActionCandidate | undefined;
+}
+/**
+ * 动作目录默认实现 DefaultActionCatalog。
+ * 基于 PackageGraph 与包内 manifest/actions 构建 Action 索引。
+ */
+export declare class DefaultActionCatalog implements ActionCatalog {
+    private readonly byPackageAndAction;
+    private readonly byActionId;
+    private readonly byPackageId;
+    private readonly graph;
+    private readonly actionsProvider?;
+    constructor(graph: PackageGraph, actionsProvider?: (packageId: string) => Map<string, any> | undefined);
+    private checkDynamicAction;
+    private addCandidate;
+    private indexGraph;
+    find(ref: ActionRef | string): ActionCandidate[];
+    list(packageId?: string): ActionCandidate[];
+    get(packageId: string, actionId: string): ActionCandidate | undefined;
+}

package/dist/catalog/action-catalog.js

@@ -0,0 +1,202 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parseActionRef } from "./resolve-action.js";
+/**
+ * 推断清单声明的 Action 入口相对路径：优先 .ts，不存在时回退 .js，兼容纯 JS 包。
+ */
+function inferActionEntry(packageRoot, manifest, actionId) {
+    const actionsDir = manifest?.actionsDir || "actions";
+    const tsEntry = join(actionsDir, `${actionId}.ts`);
+    return existsSync(join(packageRoot, tsEntry)) ? tsEntry : join(actionsDir, `${actionId}.js`);
+}
+/**
+ * 动作目录默认实现 DefaultActionCatalog。
+ * 基于 PackageGraph 与包内 manifest/actions 构建 Action 索引。
+ */
+export class DefaultActionCatalog {
+    byPackageAndAction = new Map();
+    byActionId = new Map();
+    byPackageId = new Map();
+    graph;
+    actionsProvider;
+    constructor(graph, actionsProvider) {
+        this.graph = graph;
+        this.actionsProvider = actionsProvider;
+        this.indexGraph(graph, actionsProvider);
+    }
+    checkDynamicAction(packageId, actionId) {
+        if (!this.actionsProvider)
+            return undefined;
+        const provided = this.actionsProvider(packageId);
+        if (!provided)
+            return undefined;
+        const act = provided.get(actionId);
+        if (!act)
+            return undefined;
+        const node = this.graph.packages.get(packageId);
+        if (!node)
+            return undefined;
+        const candidate = {
+            packageId,
+            packageIdentity: node.identity,
+            actionId,
+            contract: {
+                id: actionId,
+                description: act?.description,
+                inputSchema: act?.inputSchema,
+                outputSchema: act?.outputSchema,
+                uses: act?.uses,
+                tags: act?.tags,
+                annotations: act?.annotations,
+            },
+            entry: act?.entry || "",
+            packageRoot: node.root || "",
+        };
+        this.addCandidate(candidate);
+        return candidate;
+    }
+    addCandidate(candidate) {
+        const qualifiedKey = `${candidate.packageId}/${candidate.actionId}`;
+        this.byPackageAndAction.set(qualifiedKey, candidate);
+        let forAction = this.byActionId.get(candidate.actionId);
+        if (!forAction) {
+            forAction = [];
+            this.byActionId.set(candidate.actionId, forAction);
+        }
+        forAction.push(candidate);
+        let forPackage = this.byPackageId.get(candidate.packageId);
+        if (!forPackage) {
+            forPackage = [];
+            this.byPackageId.set(candidate.packageId, forPackage);
+        }
+        forPackage.push(candidate);
+    }
+    indexGraph(graph, actionsProvider) {
+        for (const node of graph.packages.values()) {
+            const packageId = node.identity.id;
+            const manifest = node.manifest;
+            // 1. 清单显式 actions 声明优先索引
+            if (manifest?.actions && typeof manifest.actions === "object") {
+                for (const [actionId, item] of Object.entries(manifest.actions)) {
+                    const entry = item?.entry || inferActionEntry(node.root, manifest, actionId);
+                    const candidate = {
+                        packageId,
+                        packageIdentity: node.identity,
+                        actionId,
+                        contract: {
+                            id: actionId,
+                            description: item?.description,
+                            inputSchema: item?.inputSchema,
+                            outputSchema: item?.outputSchema,
+                            uses: item?.uses,
+                            tags: item?.tags,
+                            annotations: item?.annotations,
+                        },
+                        entry,
+                        packageRoot: node.root,
+                    };
+                    this.addCandidate(candidate);
+                }
+            }
+            // 2. 内存动态注入动作索引（测试或 Host 注册场景）
+            if (actionsProvider) {
+                const dynActions = actionsProvider(packageId);
+                if (dynActions && typeof dynActions.entries === "function") {
+                    for (const [actionId, act] of dynActions.entries()) {
+                        const qualifiedKey = `${packageId}/${actionId}`;
+                        if (!this.byPackageAndAction.has(qualifiedKey)) {
+                            const contract = act?.contract || { id: actionId };
+                            const candidate = {
+                                packageId,
+                                packageIdentity: node.identity,
+                                actionId,
+                                contract,
+                                entry: "",
+                                packageRoot: node.root,
+                            };
+                            this.addCandidate(candidate);
+                        }
+                    }
+                }
+            }
+            // 3. actions 目录回退扫描
+            const actionsDir = join(node.root, manifest?.actionsDir || "actions");
+            if (existsSync(actionsDir)) {
+                try {
+                    const files = readdirSync(actionsDir);
+                    for (const file of files) {
+                        if (file.endsWith(".ts") || file.endsWith(".js")) {
+                            if (file.endsWith(".d.ts") || file.endsWith(".test.ts") || file.endsWith(".spec.ts")) {
+                                continue;
+                            }
+                            const actionId = file.replace(/\.(ts|js)$/, "");
+                            const qualifiedKey = `${packageId}/${actionId}`;
+                            if (!this.byPackageAndAction.has(qualifiedKey)) {
+                                const candidate = {
+                                    packageId,
+                                    packageIdentity: node.identity,
+                                    actionId,
+                                    contract: { id: actionId },
+                                    entry: join(manifest?.actionsDir || "actions", file),
+                                    packageRoot: node.root,
+                                };
+                                this.addCandidate(candidate);
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // 忽略扫描目录异常
+                }
+            }
+        }
+    }
+    find(ref) {
+        const parsed = parseActionRef(ref);
+        if (parsed.packageId) {
+            const item = this.get(parsed.packageId, parsed.actionId);
+            return item ? [item] : [];
+        }
+        if (this.actionsProvider) {
+            for (const node of this.graph.packages.values()) {
+                const key = `${node.identity.id}/${parsed.actionId}`;
+                if (!this.byPackageAndAction.has(key)) {
+                    this.checkDynamicAction(node.identity.id, parsed.actionId);
+                }
+            }
+        }
+        return this.byActionId.get(parsed.actionId) || [];
+    }
+    list(packageId) {
+        if (packageId) {
+            if (this.actionsProvider) {
+                const provided = this.actionsProvider(packageId);
+                if (provided) {
+                    for (const actionId of provided.keys()) {
+                        if (!this.byPackageAndAction.has(`${packageId}/${actionId}`)) {
+                            this.checkDynamicAction(packageId, actionId);
+                        }
+                    }
+                }
+            }
+            return this.byPackageId.get(packageId) || [];
+        }
+        if (this.actionsProvider) {
+            for (const node of this.graph.packages.values()) {
+                const provided = this.actionsProvider(node.identity.id);
+                if (provided) {
+                    for (const actionId of provided.keys()) {
+                        if (!this.byPackageAndAction.has(`${node.identity.id}/${actionId}`)) {
+                            this.checkDynamicAction(node.identity.id, actionId);
+                        }
+                    }
+                }
+            }
+        }
+        return Array.from(this.byPackageAndAction.values());
+    }
+    get(packageId, actionId) {
+        return (this.byPackageAndAction.get(`${packageId}/${actionId}`) ||
+            this.checkDynamicAction(packageId, actionId));
+    }
+}

package/dist/catalog/discovery.d.ts

@@ -0,0 +1,60 @@
+import type { ActionDockManifest } from "../project/types.js";
+import { type RegistryStore } from "../registry/store.js";
+import type { PackageIdentity } from "../runtime/identity.js";
+/**
+ * 发现的包基本信息规范。
+ */
+export interface DiscoveredPackage {
+    /** 逻辑包唯一标识符 */
+    readonly id: string;
+    /** 包物理根目录绝对路径 */
+    readonly root: string;
+    /** 包清单定义 */
+    readonly manifest: ActionDockManifest;
+    /** 包物理与快照身份凭证（可选，由已有运行时传入） */
+    readonly identity?: PackageIdentity;
+    /** 是否来自工作区目录扫描发现 */
+    readonly isWorkspaceChild?: boolean;
+    /** 是否为当前工作目录工程 */
+    readonly isCurrentProject?: boolean;
+    /** 是否来自显式链接的外部包 */
+    readonly isLinked?: boolean;
+}
+/**
+ * 包发现配置选项。
+ */
+export interface PackageDiscoveryOptions {
+    /** 当前项目根路径（可选） */
+    currentProjectRoot?: string;
+    /** 自定义 ActionDock 主目录路径（用于定位注册表） */
+    customHome?: string;
+    /** 显式注入的注册表存储实例（可选，默认使用 DefaultRegistryStore） */
+    registryStore?: RegistryStore;
+    /** 附加显式包根目录集合 */
+    packageRoots?: string[];
+    /** 附加显式工作区根目录集合 */
+    workspaceRoots?: string[];
+    /** 工作区目录扫描最大深度（默认 3） */
+    workspaceScanDepth?: number;
+    /** 是否扫描已注册链接包（默认为 true） */
+    scanLinkedPackages?: boolean;
+}
+/**
+ * 包发现单一事实源 PackageDiscovery。
+ * 负责聚合当前工程、用户显式注册包位置与工作区根目录，输出已发现包集合。
+ * 纯粹负责发现物理位置并去重冲突检测，严禁进行依赖鉴权或动作调用拦截。
+ */
+export declare class PackageDiscovery {
+    private readonly options;
+    /** 包标识到物理根路径（realpath 归一）的查重映射，避免注册路径的线性全表扫描 */
+    private readonly idRealPaths;
+    constructor(options?: PackageDiscoveryOptions);
+    /**
+     * 同步发现所有可用包基本信息集合。
+     */
+    discoverSync(): DiscoveredPackage[];
+    /**
+     * 异步发现所有可用包基本信息集合。
+     */
+    discover(): Promise<DiscoveredPackage[]>;
+}

package/dist/catalog/discovery.js

@@ -0,0 +1,119 @@
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadProjectConfig } from "../project/loader.js";
+import { loadManifest } from "../project/manifest.js";
+import { DefaultRegistryStore } from "../registry/store.js";
+import { discoverProjectConfigs } from "../registry/scan.js";
+/**
+ * 包发现单一事实源 PackageDiscovery。
+ * 负责聚合当前工程、用户显式注册包位置与工作区根目录，输出已发现包集合。
+ * 纯粹负责发现物理位置并去重冲突检测，严禁进行依赖鉴权或动作调用拦截。
+ */
+export class PackageDiscovery {
+    options;
+    /** 包标识到物理根路径（realpath 归一）的查重映射，避免注册路径的线性全表扫描 */
+    idRealPaths = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * 同步发现所有可用包基本信息集合。
+     */
+    discoverSync() {
+        const packages = new Map();
+        this.idRealPaths.clear();
+        const registryStore = this.options.registryStore || new DefaultRegistryStore(this.options.customHome);
+        const scanLinked = this.options.scanLinkedPackages !== false;
+        const registerPackage = (pathOrRoot, flags) => {
+            const abs = resolve(pathOrRoot);
+            if (!existsSync(abs))
+                return;
+            const real = realpathSync(abs);
+            if (packages.has(real)) {
+                const existing = packages.get(real);
+                if (flags.isCurrentProject && !existing.isCurrentProject) {
+                    packages.set(real, { ...existing, isCurrentProject: true });
+                }
+                return;
+            }
+            let manifest;
+            try {
+                manifest = loadManifest(abs) || loadProjectConfig(abs);
+            }
+            catch (err) {
+                if (flags.isCurrentProject) {
+                    throw err;
+                }
+                console.warn(`[PackageDiscovery] Skipping invalid package at '${abs}': ${err?.message || String(err)}`);
+                return;
+            }
+            // 以 id 到物理路径的映射做常数查重，替代全表线性扫描；同物理路径重复注册静默去重
+            const idRealPaths = this.idRealPaths;
+            const existingReal = idRealPaths.get(manifest.id);
+            if (existingReal !== undefined && existingReal !== real) {
+                throw new Error(`PACKAGE_ID_CONFLICT: Package ID '${manifest.id}' is declared by multiple directories: '${existingReal}' and '${abs}'`);
+            }
+            idRealPaths.set(manifest.id, real);
+            packages.set(real, {
+                id: manifest.id,
+                root: abs,
+                manifest,
+                ...flags,
+            });
+        };
+        // 1. 当前工程根路径
+        if (this.options.currentProjectRoot) {
+            registerPackage(this.options.currentProjectRoot, { isCurrentProject: true });
+        }
+        // 2. 显式包路径
+        if (this.options.packageRoots) {
+            for (const p of this.options.packageRoots) {
+                registerPackage(p, { isLinked: true });
+            }
+        }
+        // 3. 注册表登记位置
+        if (scanLinked) {
+            try {
+                const regData = registryStore.load();
+                if (regData.packages) {
+                    for (const pkg of Object.values(regData.packages)) {
+                        if (pkg.path) {
+                            registerPackage(pkg.path, { isLinked: true });
+                        }
+                    }
+                }
+                if (regData.workspaces) {
+                    for (const wsPath of Object.keys(regData.workspaces)) {
+                        if (existsSync(wsPath)) {
+                            const configs = discoverProjectConfigs(wsPath, this.options.workspaceScanDepth ?? 3);
+                            for (const item of configs) {
+                                registerPackage(item.root, { isWorkspaceChild: true });
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                console.warn(`[PackageDiscovery] Failed to load registry locations: ${err?.message || String(err)}`);
+            }
+        }
+        // 4. 显式附加工作区根目录
+        if (this.options.workspaceRoots) {
+            for (const wsPath of this.options.workspaceRoots) {
+                if (existsSync(wsPath)) {
+                    const configs = discoverProjectConfigs(wsPath, this.options.workspaceScanDepth ?? 3);
+                    for (const item of configs) {
+                        registerPackage(item.root, { isWorkspaceChild: true });
+                    }
+                }
+            }
+        }
+        return Array.from(packages.values());
+    }
+    /**
+     * 异步发现所有可用包基本信息集合。
+     */
+    async discover() {
+        return this.discoverSync();
+    }
+}