@actiondock/core 2.0.0 → 2.0.2

package/README.md

@@ -10,7 +10,7 @@ The core engine and domain kernel of ActionDock 2.0.
 
 > **Role & Usage Context**:
 > - **Authoring Actions**: Use [`@actiondock/sdk`](../sdk) for defining actions, testing with in-memory harness, and zero-dependency action packages.
-> - **CLI Toolchain**: Use [`@actiondock/cli`](../cli) (`ac`) for command-line workflows.
+> - **CLI Toolchain**: Use [`@actiondock/cli`](../cli) (`ad`) for command-line workflows.
 > - **Engine & Embedding**: Use `@actiondock/core` when you need programmatic access to the ActionRunner engine, project loader, or custom server integrations.
 >
 > **Runtime requirement**: [Bun](https://bun.sh/) >= 1.2.0 is required (`@actiondock/core` leverages native `bun:sqlite` and Bun runtime APIs).
@@ -38,13 +38,13 @@ bun add @actiondock/core
 
 ## 📖 Documentation
 
-- [Runtime Architecture](https://github.com/team4u/actiondock/blob/main/docs/architecture/runtime.md)
-- [Storage & Persistence Guide](https://github.com/team4u/actiondock/blob/main/docs/guides/storage.md)
-- [Standalone Binary Build](https://github.com/team4u/actiondock/blob/main/docs/guides/standalone-build.md)
-- [HTTP Server & Remote Dispatch](https://github.com/team4u/actiondock/blob/main/docs/guides/http-server.md)
+- [Runtime Architecture](../../docs/architecture/runtime.md)
+- [Storage & Persistence Guide](../../docs/developer/storage.md)
+- [Standalone Binary Build](../../docs/developer/build-and-export.md)
+- [HTTP Server & Remote Dispatch](../../docs/consumer/http-service.md)
 
 ---
 
 ## License
 
-[Apache-2.0](LICENSE) © team4u
+[Apache-2.0](../../LICENSE) © team4u

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./src/index.ts",

package/src/build/builder.ts

@@ -18,7 +18,7 @@ export interface BuildOptions {
   outfile?: string;
   /** 是否开启代码压缩混淆（默认 true） */
   minify?: boolean;
-  /** 是否编译为 V8/JavaScriptCore 字节码（默认 false） */
+  /** 是否编译为 V8/JavaScriptCore 字节码（默认 true） */
   bytecode?: boolean;
   /** 显式挑选打包的 Action ID 清单（用于按需子集打包） */
   actions?: string[];

package/src/doctor/doctor.ts

@@ -55,25 +55,25 @@ export async function runDoctorChecks(options?: {
       name: "Bun Runtime",
       status: "error",
       message: "Bun runtime not detected",
-      fix: "Install Bun via 'npm install bun -g'",
+      fix: "Install Bun via 'npm install -g bun'",
     });
   }
 
   // 2. Check CLI in PATH
-  let acPath: string | null = null;
+  let adPath: string | null = null;
   try {
-    acPath = typeof Bun !== "undefined" && Bun.which ? Bun.which("ac") : null;
+    adPath = typeof Bun !== "undefined" && Bun.which ? Bun.which("ad") : null;
   } catch {
     // ignore
   }
 
-  if (acPath) {
+  if (adPath) {
     checks.push({
       id: "runtime.cli",
       category: "runtime",
       name: "CLI Executable",
       status: "ok",
-      message: `Found 'ac' in PATH at ${acPath}`,
+      message: `Found 'ad' in PATH at ${adPath}`,
     });
   } else {
     checks.push({
@@ -81,8 +81,8 @@ export async function runDoctorChecks(options?: {
       category: "runtime",
       name: "CLI Executable",
       status: "warn",
-      message: "'ac' command not found in PATH",
-      fix: "Run 'bun add -g @actiondock/cli' or in SDK workspace run 'cd packages/cli && bun link'",
+      message: "'ad' command not found in PATH",
+      fix: "Run 'npm install -g @actiondock/cli' or in SDK workspace run 'cd packages/cli && bun link'",
     });
   }
 
@@ -99,7 +99,7 @@ export async function runDoctorChecks(options?: {
       category: "storage",
       name: "Global Storage",
       status: "ok",
-      message: `Database writable at ${join(globalHome, ".actiondock", "global.db")}`,
+      message: `Global SQLite database verified at ${globalHome}`,
     });
   } catch (err: any) {
     checks.push({
@@ -107,8 +107,8 @@ export async function runDoctorChecks(options?: {
       category: "storage",
       name: "Global Storage",
       status: "error",
-      message: `Failed to write global database: ${err.message}`,
-      fix: `Check write permissions for directory '${join(globalHome, ".actiondock")}'`,
+      message: `Failed to access global storage: ${err.message}`,
+      fix: `Ensure directory '${globalHome}' is writable`,
     });
   }
 
@@ -122,7 +122,7 @@ export async function runDoctorChecks(options?: {
         name: "Global Registry",
         status: "warn",
         message: `${regStatus.totalPackagesCount} package(s), ${regStatus.workspaces.length} workspace(s), but ${regStatus.staleCount} stale path(s) detected`,
-        fix: "Run 'ac unlink --prune' to clean up stale entries from registry",
+        fix: "Run 'ad unlink --prune' to clean up stale entries from registry",
       });
     } else {
       checks.push({
@@ -226,7 +226,7 @@ export async function runDoctorChecks(options?: {
             name: "Actions",
             status: "warn",
             message: `No actions found in '${config.actionsDir || "actions"}'`,
-            fix: "Run 'ac action create <id>' to create your first action",
+            fix: "Run 'ad action create <id>' to create your first action",
           });
         } else {
           checks.push({
@@ -289,7 +289,7 @@ export async function runDoctorChecks(options?: {
             name: "Config Readiness",
             status: "warn",
             message: `Required config item(s) missing: ${missingKeys.join(", ")}`,
-            fix: `Run 'ac config set <KEY> <VALUE>' to configure missing keys`,
+            fix: `Run 'ad config set <KEY> <VALUE>' to configure missing keys`,
           });
         } else {
           checks.push({

package/src/export/templates.ts

@@ -30,7 +30,7 @@ function renderActionListMarkdown(
       const idLabel = options.packageId
         ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
         : `\`${a.id}\``;
-      return `* ${idLabel}${aDesc}${params}`;
+      return `- ${idLabel}${aDesc}${params}`;
     })
     .join("\n");
 }
@@ -40,7 +40,7 @@ function renderPlaybookSectionMarkdown(playbooks: PlaybookDefinition[]): string
   const list = playbooks
     .map((p) => {
       const rel = `./playbooks/${basename(p.filePath)}`;
-      return `* **${p.id}** (\`${rel}\`): ${p.description || "任务指南"}`;
+      return `- **${p.id}** (\`${rel}\`): ${p.description || "任务指南"}`;
     })
     .join("\n");
   return `
@@ -73,34 +73,34 @@ description: ${desc}
 
 ${desc}
 
-## ActionDock 运行时 (ActionDock Runtime)
+## ActionDock 运行时
 
-本技能为 **ActionDock 源码型 Package (Source Skill)**。AI Agent 可直接通过已安装的 ActionDock 命令行工具 (\`ac\`) 执行其中的 Action。
+本技能为 **ActionDock 源码型技能包**。AI Agent 可直接通过已安装的 ActionDock 命令行工具 (\`ad\`) 执行其中的 Action。
 
-### 注册与链接 (Idempotent Setup)
+### 注册与链接
 
 在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册：
 
 \`\`\`bash
-ac link "<skill_root>"
+ad link "<skill_root>"
 \`\`\`
 
-> \`ac link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。
+> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。
 
-### 执行 Action (统一推荐 Package-Qualified ID)
+### 执行 Action
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID：
 
 \`\`\`bash
-# 格式：ac run <package-id>/<action-id> --input '<json>'
-ac run ${pkgId}/${firstAction} --input '{"param": "value"}'
+# 格式：ad run <package-id>/<action-id> --input '<json>'
+ad run ${pkgId}/${firstAction} --input '{"param": "value"}'
 \`\`\`
 
-> **免注册本地执行 (Direct Execution Alternative)**:
+> **免注册本地执行**：
 > 若 Agent 工作目录已位于本 Skill 根目录，亦可直接免 link 执行：
 > \`\`\`bash
 > cd <skill_root>
-> ac run <action-id> --input '<json>'
+> ad run <action-id> --input '<json>'
 > \`\`\`
 
 所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON Envelope：
@@ -127,13 +127,56 @@ ${playbookSection}
 
 \`\`\`bash
 # 查看与设置配置项
-ac config list --package ${pkgId}
-ac config set KEY VALUE --package ${pkgId}
+ad config list --package ${pkgId}
+ad config set KEY VALUE --package ${pkgId}
 
 # 查看与检索状态数据
-ac state list --package ${pkgId}
-ac state get KEY --package ${pkgId}
+ad state list --package ${pkgId}
+ad state get KEY --package ${pkgId}
 \`\`\`
+
+---
+
+## 故障排查与环境安装指引（按需查阅）
+
+> [!NOTE]
+> **按需排查原则**：默认宿主环境中已预置 \`ad\` 命令行工具。正常执行流程直接调用上述 Action 即可，**严禁在任务启动前盲目进行前置环境检查或体检**；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）时，方可按本节指引安装初始化。
+
+### 命令行工具未找到时的安装指引
+
+若宿主环境未安装 \`ad\` 命令行工具，请依次按如下步骤完成安装：
+
+- **安装 Bun 运行时**（若系统未安装）：
+  \`\`\`bash
+  npm install -g bun
+  \`\`\`
+
+- **全局安装 ActionDock 命令行工具**：
+  \`\`\`bash
+  npm install -g @actiondock/cli
+  \`\`\`
+
+- **验证工具就绪**：
+  \`\`\`bash
+  ad --version
+  \`\`\`
+
+- **源码本地开发模式**（若在本地源码仓库中贡献或开发）：
+  \`\`\`bash
+  cd packages/cli && bun link
+  cd ../sdk && bun link
+  \`\`\`
+
+- **环境诊断与体检**：
+  安装完成后若仍遇到异常，执行体检命令排查：
+  \`\`\`bash
+  ad doctor
+  \`\`\`
+
+- **完成安装后重新链接本技能**：
+  \`\`\`bash
+  ad link "<skill_root>"
+  \`\`\`
 `;
 }
 

package/src/profile/client.ts

@@ -291,12 +291,262 @@ export async function fetchRemoteActionShow(
 
 export async function fetchRemoteInfo(
   serverUrl: string,
-  token?: string
+  token?: string,
+  options?: { intent?: string; package?: string; tree?: boolean }
 ): Promise<any> {
+  const params = new URLSearchParams();
+  if (options?.intent) params.set("intent", options.intent);
+  if (options?.package) params.set("package", options.package);
+  if (options?.tree) params.set("tree", "true");
+  const qs = params.toString() ? `?${params.toString()}` : "";
   return fetchRemoteJson(
     serverUrl,
-    "/api/v1/info",
+    `/api/v1/info${qs}`,
     token,
     { errorPrefix: "Failed to fetch remote info" }
   );
 }
+
+export async function fetchRemoteDoctor(
+  serverUrl: string,
+  token?: string,
+  targetPackage?: string
+): Promise<any> {
+  const query = targetPackage ? `?package=${encodeURIComponent(targetPackage)}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/doctor${query}`,
+    token,
+    { errorPrefix: "Failed to fetch remote doctor report" }
+  );
+}
+
+export async function fetchRemotePlaybooks(
+  serverUrl: string,
+  token?: string,
+  options?: { intent?: string; package?: string }
+): Promise<Array<{ id: string; description: string; actions: string[]; packageId: string; filePath: string }>> {
+  const params = new URLSearchParams();
+  if (options?.intent) params.set("intent", options.intent);
+  if (options?.package) params.set("package", options.package);
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/playbooks${qs}`,
+    token,
+    { errorPrefix: "Failed to fetch remote playbooks" }
+  );
+}
+
+export async function fetchRemotePlaybookShow(
+  serverUrl: string,
+  playbookId: string,
+  token?: string
+): Promise<any> {
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/playbooks/${encodeURIComponent(playbookId)}`,
+    token,
+    { errorPrefix: `Failed to fetch remote playbook '${playbookId}'` }
+  );
+}
+
+export async function fetchRemoteRuns(
+  serverUrl: string,
+  token?: string,
+  options?: { status?: string; actionId?: string; packageId?: string; intent?: string; limit?: number }
+): Promise<{ ok: boolean; total: number; items: RunRecord[] }> {
+  const params = new URLSearchParams();
+  if (options?.status) params.set("status", options.status);
+  if (options?.actionId) params.set("actionId", options.actionId);
+  if (options?.packageId) params.set("packageId", options.packageId);
+  if (options?.intent) params.set("intent", options.intent);
+  if (options?.limit) params.set("limit", String(options.limit));
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/runs${qs}`,
+    token,
+    { errorPrefix: "Failed to fetch remote runs" }
+  );
+}
+
+export async function clearRemoteRuns(
+  serverUrl: string,
+  token?: string,
+  options?: { packageId?: string; actionId?: string; status?: string }
+): Promise<{ ok: boolean; clearedCount: number }> {
+  return fetchRemoteJson(
+    serverUrl,
+    "/api/v1/runs/clear",
+    token,
+    {
+      method: "POST",
+      body: options || {},
+      errorPrefix: "Failed to clear remote runs",
+    }
+  );
+}
+
+export async function fetchRemoteStateList(
+  serverUrl: string,
+  token?: string,
+  options?: { package?: string; namespace?: string; prefix?: string }
+): Promise<{ ok: boolean; packageId: string; keys: string[] }> {
+  const params = new URLSearchParams();
+  if (options?.package) params.set("package", options.package);
+  if (options?.namespace !== undefined) params.set("namespace", options.namespace);
+  if (options?.prefix) params.set("prefix", options.prefix);
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/state${qs}`,
+    token,
+    { errorPrefix: "Failed to list remote state keys" }
+  );
+}
+
+export async function getRemoteStateKey(
+  serverUrl: string,
+  key: string,
+  token?: string,
+  options?: { package?: string; namespace?: string }
+): Promise<any> {
+  const params = new URLSearchParams();
+  if (options?.package) params.set("package", options.package);
+  if (options?.namespace !== undefined) params.set("namespace", options.namespace);
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/state/${encodeURIComponent(key)}${qs}`,
+    token,
+    { errorPrefix: `Failed to fetch remote state key '${key}'` }
+  );
+}
+
+export async function setRemoteStateKey(
+  serverUrl: string,
+  key: string,
+  value: unknown,
+  token?: string,
+  options?: { package?: string; namespace?: string; ttl?: number }
+): Promise<any> {
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/state/${encodeURIComponent(key)}`,
+    token,
+    {
+      method: "PUT",
+      body: {
+        value,
+        package: options?.package,
+        namespace: options?.namespace,
+        ttl: options?.ttl,
+      },
+      errorPrefix: `Failed to set remote state key '${key}'`,
+    }
+  );
+}
+
+export async function deleteRemoteStateKey(
+  serverUrl: string,
+  key: string,
+  token?: string,
+  options?: { package?: string; namespace?: string }
+): Promise<any> {
+  const params = new URLSearchParams();
+  if (options?.package) params.set("package", options.package);
+  if (options?.namespace !== undefined) params.set("namespace", options.namespace);
+  const qs = params.toString() ? `?${params.toString()}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/state/${encodeURIComponent(key)}${qs}`,
+    token,
+    {
+      method: "DELETE",
+      errorPrefix: `Failed to delete remote state key '${key}'`,
+    }
+  );
+}
+
+export async function clearRemoteState(
+  serverUrl: string,
+  token?: string,
+  options?: { package?: string; namespace?: string; prefix?: string; all?: boolean }
+): Promise<{ ok: boolean; packageId: string; clearedCount: number }> {
+  return fetchRemoteJson(
+    serverUrl,
+    "/api/v1/state/clear",
+    token,
+    {
+      method: "POST",
+      body: options || {},
+      errorPrefix: "Failed to clear remote state",
+    }
+  );
+}
+
+export async function fetchRemoteConfig(
+  serverUrl: string,
+  token?: string,
+  packageId?: string
+): Promise<any> {
+  const query = packageId ? `?package=${encodeURIComponent(packageId)}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/config${query}`,
+    token,
+    { errorPrefix: "Failed to fetch remote config" }
+  );
+}
+
+export async function setRemoteConfig(
+  serverUrl: string,
+  key: string,
+  value: unknown,
+  token?: string,
+  packageId?: string
+): Promise<any> {
+  return fetchRemoteJson(
+    serverUrl,
+    "/api/v1/config",
+    token,
+    {
+      method: "PUT",
+      body: { key, value, package: packageId },
+      errorPrefix: `Failed to set remote config '${key}'`,
+    }
+  );
+}
+
+export async function deleteRemoteConfig(
+  serverUrl: string,
+  key: string,
+  token?: string,
+  packageId?: string
+): Promise<any> {
+  const query = packageId ? `?package=${encodeURIComponent(packageId)}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/config/${encodeURIComponent(key)}${query}`,
+    token,
+    {
+      method: "DELETE",
+      errorPrefix: `Failed to delete remote config '${key}'`,
+    }
+  );
+}
+
+export async function fetchRemoteConfigEnv(
+  serverUrl: string,
+  token?: string,
+  packageId?: string
+): Promise<any> {
+  const query = packageId ? `?package=${encodeURIComponent(packageId)}` : "";
+  return fetchRemoteJson(
+    serverUrl,
+    `/api/v1/config/env${query}`,
+    token,
+    { errorPrefix: "Failed to fetch remote config env checks" }
+  );
+}

package/src/profile/manager.ts

@@ -144,7 +144,7 @@ export function useProfile(name: string, customHome?: string): void {
 
   if (trimmedName !== "local" && !profilesConfig.profiles[trimmedName]) {
     throw new Error(
-      `Profile '${trimmedName}' not found. Use 'ac profile list' to see available profiles or 'ac profile add' to register one.`
+      `Profile '${trimmedName}' not found. Use 'ad profile list' to see available profiles or 'ad profile add' to register one.`
     );
   }
 
@@ -274,7 +274,7 @@ export function resolveTarget(
     const found = profilesConfig.profiles[pName];
     if (!found) {
       throw new Error(
-        `Profile '${pName}' not found. Configure it with 'ac profile add ${pName} --server <url>'`
+        `Profile '${pName}' not found. Configure it with 'ad profile add ${pName} --server <url>'`
       );
     }
     const resolvedToken = resolveProfileToken(pName, found, options.token);
@@ -307,7 +307,7 @@ export function resolveTarget(
     const found = profilesConfig.profiles[pName];
     if (!found) {
       throw new Error(
-        `Profile '${pName}' (from ACTIONDOCK_PROFILE) not found. Configure it with 'ac profile add ${pName} --server <url>'`
+        `Profile '${pName}' (from ACTIONDOCK_PROFILE) not found. Configure it with 'ad profile add ${pName} --server <url>'`
       );
     }
     const resolvedToken = resolveProfileToken(pName, found, options?.token);

package/src/project/init.ts

@@ -161,8 +161,8 @@ actions:
 
 # Greeting SOP
 
-1. Call \`sample.greet\` with the user's name.
-2. Confirm the returned greeting message.
+- Call \`sample.greet\` with the user's name.
+- Confirm the returned greeting message.
 `;
   writeFileSync(join(playbooksDir, "greet-user.md"), samplePlaybook);
 

package/src/registry/registry.ts

@@ -376,7 +376,7 @@ export async function resolveActionProject(
 
     if (!pkg || !existsSync(pkg.path)) {
       throw new Error(
-        `Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ac link' in the package directory.`
+        `Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ad link' in the package directory.`
       );
     }
 
@@ -428,7 +428,7 @@ export async function resolveActionProject(
     throw new Error(`Action '${actionIdentifier}' not found in current project or any linked packages`);
   } else {
     throw new Error(
-      `Action '${actionIdentifier}' not found. You are not in an ActionDock project, and no linked package provides '${actionIdentifier}'. Use 'ac link' to register your package.`
+      `Action '${actionIdentifier}' not found. You are not in an ActionDock project, and no linked package provides '${actionIdentifier}'. Use 'ad link' to register your package.`
     );
   }
 }
@@ -505,7 +505,7 @@ export function resolvePlaybookProject(
 
     if (!pkg || !existsSync(pkg.path)) {
       throw new Error(
-        `Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ac link' in the package directory.`
+        `Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ad link' in the package directory.`
       );
     }
 
@@ -564,7 +564,7 @@ export function resolvePlaybookProject(
     throw new Error(`Playbook '${playbookIdentifier}' not found in current project or any linked packages`);
   } else {
     throw new Error(
-      `Playbook '${playbookIdentifier}' not found. You are not in an ActionDock project, and no linked package provides '${playbookIdentifier}'. Use 'ac link' to register your package.`
+      `Playbook '${playbookIdentifier}' not found. You are not in an ActionDock project, and no linked package provides '${playbookIdentifier}'. Use 'ad link' to register your package.`
     );
   }
 }

package/src/runtime/standalone.ts

@@ -26,8 +26,8 @@ export interface StandaloneRuntimeOptions {
  * 独立二进制可执行文件运行时（Standalone Runtime）。
  * 
  * 职责：
- * 1. 作为由 `ac build` 编译生成的单文件独立可执行文件（Standalone Binary）的运行时入口。
- * 2. 保证与开发态（`ac run` / `ac action`）在输出信封、配置优先级、状态存储等方面的 100% 行为一致性。
+ * 1. 作为由 `ad build` 编译生成的单文件独立可执行文件（Standalone Binary）的运行时入口。
+ * 2. 保证与开发态（`ad run` / `ad action`）在输出信封、配置优先级、状态存储等方面的 100% 行为一致性。
  * 3. 自带轻量 CLI 分发器，支持 `list`, `describe`, `run`, `config`, `state`, `version`, `help` 子命令。
  */
 export class StandaloneRuntime {

package/src/server/runtime-registry.ts

@@ -6,18 +6,53 @@ import type { RuntimeStorage } from "../storage/types";
  * 服务端运行时注册表（ServerRuntimeRegistry）。
  * 
  * 职责：
- * 1. 在长期运行的 HTTP 服务端（`ac serve` / `ac mcp serve`）中，跨请求缓存并池化管理 SQLite 数据库存储连接。
+ * 1. 在长期运行的 HTTP 服务端（`ad serve` / `ad mcp serve`）中，跨请求缓存并池化管理 SQLite 数据库存储连接。
  * 2. 集中维护活跃的在途任务执行句柄（ExecutionManager）。
  * 3. 服务端停止或优雅关机（Graceful Shutdown）时，统一中断在途任务并安全关闭所有数据库连接。
  */
 export class ServerRuntimeRegistry {
   private storages = new Map<string, RuntimeStorage>();
+  private listeners = new Map<string, Set<(event: { type: string; data: any }) => void>>();
   public executionManager: ExecutionManager;
 
   constructor() {
     this.executionManager = new ExecutionManager();
   }
 
+  /**
+   * 订阅指定 runId 的事件（用于 SSE 流式推送）。
+   */
+  public subscribe(runId: string, listener: (event: { type: string; data: any }) => void): () => void {
+    let set = this.listeners.get(runId);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(runId, set);
+    }
+    set.add(listener);
+    return () => {
+      set?.delete(listener);
+      if (set && set.size === 0) {
+        this.listeners.delete(runId);
+      }
+    };
+  }
+
+  /**
+   * 向指定 runId 的订阅者广播事件。
+   */
+  public emit(runId: string, event: { type: string; data: any }): void {
+    const set = this.listeners.get(runId);
+    if (set) {
+      for (const listener of set) {
+        try {
+          listener(event);
+        } catch {
+          // 忽略单个监听器错误
+        }
+      }
+    }
+  }
+
   /**
    * 获取或懒加载指定 Package 和 projectRoot 的缓存 RuntimeStorage 实例。
    *