@gt-fe/eap-cli 0.2.11 → 0.2.12

package/dist/templates/agent-api-orchestration/scripts/build-runtime.mjs

@@ -1,26 +1,26 @@
-import { config } from 'dotenv';
-import { packageStandaloneAgentProject } from '@gt-fe/eap-sdk';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-
-// --dev 使用项目根的 .eap/runtime；生产构建使用 dist/.eap/runtime。
-const isDev = process.argv.includes('--dev');
-
-// 统一读取项目根 .env。
-config({ path: resolve(root, '.env') });
-
-// 生产输出目录必须位于 dist 下，便于与 dist/index.js 一起发布。
-const runtimeBase = isDev ? root : resolve(root, 'dist');
-const runtimeRoot = resolve(
-  runtimeBase,
-  process.env.EAP_RUNTIME_ROOT?.trim() || './.eap/runtime',
-);
-
-const prepared = await packageStandaloneAgentProject({
-  root,
-  outputDirectory: runtimeRoot,
-});
-
-console.log(`Runtime 已生成: ${prepared.runtimeRoot}`);
+import { config } from 'dotenv';
+import { packageStandaloneAgentProject } from '@gt-fe/eap-sdk';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// --dev 使用项目根的 .eap/runtime；生产构建使用 dist/.eap/runtime。
+const isDev = process.argv.includes('--dev');
+
+// 统一读取项目根 .env。
+config({ path: resolve(root, '.env') });
+
+// 生产输出目录必须位于 dist 下，便于与 dist/index.js 一起发布。
+const runtimeBase = isDev ? root : resolve(root, 'dist');
+const runtimeRoot = resolve(
+  runtimeBase,
+  process.env.EAP_RUNTIME_ROOT?.trim() || './.eap/runtime',
+);
+
+const prepared = await packageStandaloneAgentProject({
+  root,
+  outputDirectory: runtimeRoot,
+});
+
+console.log(`Runtime 已生成: ${prepared.runtimeRoot}`);

package/dist/templates/agent-api-orchestration/scripts/validate.mjs

@@ -1,12 +1,12 @@
-import { validateAgentProject } from '@gt-fe/eap-sdk';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// 校验脚本始终以模板项目根目录为 Agent 源项目根。
-const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const result = validateAgentProject(root);
-// 输出全部问题，交给调用方根据退出码阻止后续构建。
-for (const issue of result.issues) {
-  console.log(`[${issue.severity}] ${issue.message}`);
-}
-if (!result.valid) process.exitCode = 1;
+import { validateAgentProject } from '@gt-fe/eap-sdk';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// 校验脚本始终以模板项目根目录为 Agent 源项目根。
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const result = validateAgentProject(root);
+// 输出全部问题，交给调用方根据退出码阻止后续构建。
+for (const issue of result.issues) {
+  console.log(`[${issue.severity}] ${issue.message}`);
+}
+if (!result.valid) process.exitCode = 1;

package/dist/templates/agent-api-orchestration/src/embedded-agent.ts

@@ -1,92 +1,92 @@
-import {
-  createAgent,
-  resolveProjectRuntimeEnvironment,
-  type Agent,
-  type AgentCredentialProvider,
-  type AgentResourceManager,
-  type EmbeddedSdkConfig,
-} from '@gt-fe/eap-sdk';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { loadTemplateRuntime, resolveTemplateRuntimeRoot } from './project-config.js';
-export { AgentResourceService, createAgentResourceService } from './http/services/resource-service.js';
-export { createAgentApp, createAgentHttpServer, startAgentHttpServer } from './http/index.js';
-export type { AgentHttpStartOptions } from './http/index.js';
-
-const entryDirectory = dirname(fileURLToPath(import.meta.url));
-const isDev = process.argv.includes('--dev');
-
-export interface EmbeddedAgentOptions {
-  /** 生产宿主显式注入的短期凭证 Provider；优先级高于 EAP_SDK_TOKEN。 */
-  credentialProvider?: AgentCredentialProvider;
-  /** 仅用于开发演示的 Token 回退。 */
-  sdkToken?: string;
-  /** 覆盖模板默认的物化 Runtime 路径。 */
-  runtimeRoot?: string;
-  /** 宿主实现的资源 manager；模板只负责把它注入 SDK。 */
-  resourceManager?: AgentResourceManager;
-}
-
-/**
- * 创建一个使用模板项目配置的内嵌 Agent。
- *
- * platform.portalUrl 和 platform.foundationServiceUrl 来自 eap.config.json；
- * 凭证优先使用宿主显式传入的 Provider；只有开发模式才回退到 EAP_SDK_TOKEN。
- */
-export async function createEmbeddedAgent(options: EmbeddedAgentOptions = {}): Promise<Agent> {
-  const runtimeRoot = options.runtimeRoot ?? resolveTemplateRuntimeRoot(entryDirectory);
-  const loadedRuntime = loadTemplateRuntime(entryDirectory, runtimeRoot);
-  const platform = {
-    portalEndpoint: loadedRuntime.config.platform.portalUrl.trim(),
-    ...(loadedRuntime.config.platform.foundationServiceUrl?.trim()
-      ? { foundationEndpoint: loadedRuntime.config.platform.foundationServiceUrl.trim() }
-      : {}),
-  };
-  // 凭证优先级：宿主显式注入的 credentialProvider > EAP_SDK_TOKEN 环境变量回退。
-  // 显式注入用于生产托管；EAP_SDK_TOKEN 用于本地演示（npm run dev / 本地起 dist 冒烟）。
-  const provider =
-    options.credentialProvider ??
-    createSdkTokenProvider(options.sdkToken ?? process.env.EAP_SDK_TOKEN);
-  const embeddedConfig: EmbeddedSdkConfig = {
-    platform,
-    credentials: { provider },
-    ...(options.resourceManager ? { resources: { manager: options.resourceManager } } : {}),
-  };
-  const deploymentRoot = resolve(runtimeRoot, '..', '..');
-
-  // 把 eap.config.json 里的 runtime.llm.models 映射成运行时识别的本地模型连接
-  // （EAP_LLM_MODE=local + EAP_LLM_CONNECTIONS）。漏掉这一步时，运行时会因为拿不到
-  // 本地网关而退回 EchoLLMProvider，表现为 [echo:model] 回显用户输入而非真实对话。
-  const projectRoot = resolve(entryDirectory, '..');
-  const runtimeEnvironment = resolveProjectRuntimeEnvironment({
-    root: projectRoot,
-    preinstallRoot: runtimeRoot,
-  }).environment;
-
-  return createAgent({
-    runtimeRoot,
-    deploymentContext: isDev ? 'dev' : 'server',
-    embeddedConfig,
-    environment: {
-      ...runtimeEnvironment,
-      // 模板以物化 Runtime 目录为基准，覆盖 SDK 相对项目根算出的路径。
-      EAP_DATA_DIR: resolve(runtimeRoot, '..'),
-      EAP_CHECKPOINT_DIR: resolve(deploymentRoot, loadedRuntime.config.runtime.storage.checkpointDir),
-    },
-    // 模板默认 eap.config.json 使用 dev 存储档，由 Runtime 提供本地文件实现。
-    sessionPersistence: loadedRuntime.config.runtime.storage.profile === 'dev',
-  });
-}
-
-export function createSdkTokenProvider(token?: string): AgentCredentialProvider {
-  return {
-    async getToken() {
-      const value = token?.trim() || process.env.EAP_SDK_TOKEN?.trim();
-      if (!value) {
-        throw new Error('请由生产宿主显式注入 credentialProvider；EAP_SDK_TOKEN 仅用于本地演示回退');
-      }
-      return { value };
-    },
-  };
+import {
+  createAgent,
+  resolveProjectRuntimeEnvironment,
+  type Agent,
+  type AgentCredentialProvider,
+  type AgentResourceManager,
+  type EmbeddedSdkConfig,
+} from '@gt-fe/eap-sdk';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadTemplateRuntime, resolveTemplateRuntimeRoot } from './project-config.js';
+export { AgentResourceService, createAgentResourceService } from './http/services/resource-service.js';
+export { createAgentApp, createAgentHttpServer, startAgentHttpServer } from './http/index.js';
+export type { AgentHttpStartOptions } from './http/index.js';
+
+const entryDirectory = dirname(fileURLToPath(import.meta.url));
+const isDev = process.argv.includes('--dev');
+
+export interface EmbeddedAgentOptions {
+  /** 生产宿主显式注入的短期凭证 Provider；优先级高于 EAP_SDK_TOKEN。 */
+  credentialProvider?: AgentCredentialProvider;
+  /** 仅用于开发演示的 Token 回退。 */
+  sdkToken?: string;
+  /** 覆盖模板默认的物化 Runtime 路径。 */
+  runtimeRoot?: string;
+  /** 宿主实现的资源 manager；模板只负责把它注入 SDK。 */
+  resourceManager?: AgentResourceManager;
+}
+
+/**
+ * 创建一个使用模板项目配置的内嵌 Agent。
+ *
+ * platform.portalUrl 和 platform.foundationServiceUrl 来自 eap.config.json；
+ * 凭证优先使用宿主显式传入的 Provider；只有开发模式才回退到 EAP_SDK_TOKEN。
+ */
+export async function createEmbeddedAgent(options: EmbeddedAgentOptions = {}): Promise<Agent> {
+  const runtimeRoot = options.runtimeRoot ?? resolveTemplateRuntimeRoot(entryDirectory);
+  const loadedRuntime = loadTemplateRuntime(entryDirectory, runtimeRoot);
+  const platform = {
+    portalEndpoint: loadedRuntime.config.platform.portalUrl.trim(),
+    ...(loadedRuntime.config.platform.foundationServiceUrl?.trim()
+      ? { foundationEndpoint: loadedRuntime.config.platform.foundationServiceUrl.trim() }
+      : {}),
+  };
+  // 凭证优先级：宿主显式注入的 credentialProvider > EAP_SDK_TOKEN 环境变量回退。
+  // 显式注入用于生产托管；EAP_SDK_TOKEN 用于本地演示（npm run dev / 本地起 dist 冒烟）。
+  const provider =
+    options.credentialProvider ??
+    createSdkTokenProvider(options.sdkToken ?? process.env.EAP_SDK_TOKEN);
+  const embeddedConfig: EmbeddedSdkConfig = {
+    platform,
+    credentials: { provider },
+    ...(options.resourceManager ? { resources: { manager: options.resourceManager } } : {}),
+  };
+  const deploymentRoot = resolve(runtimeRoot, '..', '..');
+
+  // 把 eap.config.json 里的 runtime.llm.models 映射成运行时识别的本地模型连接
+  // （EAP_LLM_MODE=local + EAP_LLM_CONNECTIONS）。漏掉这一步时，运行时会因为拿不到
+  // 本地网关而退回 EchoLLMProvider，表现为 [echo:model] 回显用户输入而非真实对话。
+  const projectRoot = resolve(entryDirectory, '..');
+  const runtimeEnvironment = resolveProjectRuntimeEnvironment({
+    root: projectRoot,
+    preinstallRoot: runtimeRoot,
+  }).environment;
+
+  return createAgent({
+    runtimeRoot,
+    deploymentContext: isDev ? 'dev' : 'server',
+    embeddedConfig,
+    environment: {
+      ...runtimeEnvironment,
+      // 模板以物化 Runtime 目录为基准，覆盖 SDK 相对项目根算出的路径。
+      EAP_DATA_DIR: resolve(runtimeRoot, '..'),
+      EAP_CHECKPOINT_DIR: resolve(deploymentRoot, loadedRuntime.config.runtime.storage.checkpointDir),
+    },
+    // 模板默认 eap.config.json 使用 dev 存储档，由 Runtime 提供本地文件实现。
+    sessionPersistence: loadedRuntime.config.runtime.storage.profile === 'dev',
+  });
+}
+
+export function createSdkTokenProvider(token?: string): AgentCredentialProvider {
+  return {
+    async getToken() {
+      const value = token?.trim() || process.env.EAP_SDK_TOKEN?.trim();
+      if (!value) {
+        throw new Error('请由生产宿主显式注入 credentialProvider；EAP_SDK_TOKEN 仅用于本地演示回退');
+      }
+      return { value };
+    },
+  };
 }

package/dist/templates/agent-api-orchestration/src/http/app.ts

@@ -1,58 +1,58 @@
-import express, { type Express } from 'express';
-import { createServer, type Server } from 'node:http';
-import type { Agent } from '@gt-fe/eap-sdk';
-import { errorHandler, notFound } from './errors.js';
-import { resolveAgentHttpStartOptions, formatHost } from './config.js';
-import { corsMiddleware } from './middleware/cors.js';
-import { createAgentApiRouter } from './routes/agent.js';
-import { createHealthRouter } from './routes/health.js';
-import type { AgentHttpService, AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';
-
-export function createAgentApp(agent: Agent, options: AgentHttpStartOptions = {}): Express {
-  const resolved = resolveAgentHttpStartOptions(options);
-  const app = express();
-  app.disable('x-powered-by');
-  app.use(corsMiddleware(resolved.corsOrigin));
-  app.use((_request, response, next) => {
-    // 统一返回 Agent 标识，前端可以用响应头确认当前服务版本。
-    response.setHeader('X-Agent-Code', agent.target.agentCode);
-    response.setHeader('X-Agent-Version', agent.target.version);
-    next();
-  });
-  app.use(express.json({ limit: resolved.maxBodyBytes }));
-  app.use('/health', createHealthRouter(agent));
-  app.use('/api/v1/agents', createAgentApiRouter(agent));
-  app.use((_request, _response, next) => next(notFound()));
-  app.use(errorHandler);
-  return app;
-}
-
-export function createAgentHttpServer(agent: Agent, options: AgentHttpStartOptions = {}): Server {
-  return createServer(createAgentApp(agent, options));
-}
-
-export async function startAgentHttpServer(agent: Agent, options: AgentHttpStartOptions = {}): Promise<AgentHttpService> {
-  const resolved: ResolvedAgentHttpOptions = resolveAgentHttpStartOptions(options);
-  // 返回实际监听的 app，便于宿主读取 Express 实例或交给框架托管。
-  const app = createAgentApp(agent, resolved);
-  const server = createServer(app);
-  await new Promise<void>((resolve, reject) => {
-    const onError = (error: Error) => reject(error);
-    server.once('error', onError);
-    server.listen(resolved.port, resolved.host, () => {
-      server.off('error', onError);
-      resolve();
-    });
-  });
-  const address = server.address();
-  const port = address && typeof address !== 'string' ? address.port : resolved.port;
-  return {
-    app,
-    server,
-    address: `http://${formatHost(resolved.host)}:${port}`,
-    async stop() {
-      if (!server.listening) return;
-      await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
-    },
-  };
-}
+import express, { type Express } from 'express';
+import { createServer, type Server } from 'node:http';
+import type { Agent } from '@gt-fe/eap-sdk';
+import { errorHandler, notFound } from './errors.js';
+import { resolveAgentHttpStartOptions, formatHost } from './config.js';
+import { corsMiddleware } from './middleware/cors.js';
+import { createAgentApiRouter } from './routes/agent.js';
+import { createHealthRouter } from './routes/health.js';
+import type { AgentHttpService, AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';
+
+export function createAgentApp(agent: Agent, options: AgentHttpStartOptions = {}): Express {
+  const resolved = resolveAgentHttpStartOptions(options);
+  const app = express();
+  app.disable('x-powered-by');
+  app.use(corsMiddleware(resolved.corsOrigin));
+  app.use((_request, response, next) => {
+    // 统一返回 Agent 标识，前端可以用响应头确认当前服务版本。
+    response.setHeader('X-Agent-Code', agent.target.agentCode);
+    response.setHeader('X-Agent-Version', agent.target.version);
+    next();
+  });
+  app.use(express.json({ limit: resolved.maxBodyBytes }));
+  app.use('/health', createHealthRouter(agent));
+  app.use('/api/v1/agents', createAgentApiRouter(agent));
+  app.use((_request, _response, next) => next(notFound()));
+  app.use(errorHandler);
+  return app;
+}
+
+export function createAgentHttpServer(agent: Agent, options: AgentHttpStartOptions = {}): Server {
+  return createServer(createAgentApp(agent, options));
+}
+
+export async function startAgentHttpServer(agent: Agent, options: AgentHttpStartOptions = {}): Promise<AgentHttpService> {
+  const resolved: ResolvedAgentHttpOptions = resolveAgentHttpStartOptions(options);
+  // 返回实际监听的 app，便于宿主读取 Express 实例或交给框架托管。
+  const app = createAgentApp(agent, resolved);
+  const server = createServer(app);
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => reject(error);
+    server.once('error', onError);
+    server.listen(resolved.port, resolved.host, () => {
+      server.off('error', onError);
+      resolve();
+    });
+  });
+  const address = server.address();
+  const port = address && typeof address !== 'string' ? address.port : resolved.port;
+  return {
+    app,
+    server,
+    address: `http://${formatHost(resolved.host)}:${port}`,
+    async stop() {
+      if (!server.listening) return;
+      await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+    },
+  };
+}

package/dist/templates/agent-api-orchestration/src/http/config.ts

@@ -1,34 +1,34 @@
-import type { AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';
-
-export function resolveAgentHttpStartOptions(
-  options: AgentHttpStartOptions = {},
-  env: NodeJS.ProcessEnv = process.env,
-): ResolvedAgentHttpOptions {
-  // 显式 options 优先于环境变量，便于测试、嵌入其他服务或动态选择端口。
-  return {
-    host: options.host ?? env.EAP_HTTP_HOST ?? '127.0.0.1',
-    port: options.port ?? parsePort(env.EAP_HTTP_PORT ?? env.EAP_RUNTIME_PORT),
-    corsOrigin: options.corsOrigin ?? env.EAP_HTTP_CORS_ORIGIN ?? '*',
-    maxBodyBytes: options.maxBodyBytes ?? parseBodyLimit(env.EAP_HTTP_MAX_BODY_BYTES),
-  };
-}
-
-export function formatHost(host: string): string {
-  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
-}
-
-function parsePort(value: string | undefined): number {
-  // 允许传 0，让 Node 自动分配空闲端口，适合宿主编排和本地联调。
-  if (!value) return 3000;
-  const port = Number(value);
-  if (Number.isInteger(port) && port >= 0 && port <= 65535) return port;
-  throw new Error(`Invalid EAP_HTTP_PORT: ${value}`);
-}
-
-function parseBodyLimit(value: string | undefined): number {
-  // 限制请求体大小，避免前端误传大对象占满服务内存。
-  if (!value) return 1024 * 1024;
-  const limit = Number(value);
-  if (Number.isInteger(limit) && limit >= 1024 && limit <= 50 * 1024 * 1024) return limit;
-  throw new Error(`Invalid EAP_HTTP_MAX_BODY_BYTES: ${value}`);
-}
+import type { AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';
+
+export function resolveAgentHttpStartOptions(
+  options: AgentHttpStartOptions = {},
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedAgentHttpOptions {
+  // 显式 options 优先于环境变量，便于测试、嵌入其他服务或动态选择端口。
+  return {
+    host: options.host ?? env.EAP_HTTP_HOST ?? '127.0.0.1',
+    port: options.port ?? parsePort(env.EAP_HTTP_PORT ?? env.EAP_RUNTIME_PORT),
+    corsOrigin: options.corsOrigin ?? env.EAP_HTTP_CORS_ORIGIN ?? '*',
+    maxBodyBytes: options.maxBodyBytes ?? parseBodyLimit(env.EAP_HTTP_MAX_BODY_BYTES),
+  };
+}
+
+export function formatHost(host: string): string {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+function parsePort(value: string | undefined): number {
+  // 允许传 0，让 Node 自动分配空闲端口，适合宿主编排和本地联调。
+  if (!value) return 3000;
+  const port = Number(value);
+  if (Number.isInteger(port) && port >= 0 && port <= 65535) return port;
+  throw new Error(`Invalid EAP_HTTP_PORT: ${value}`);
+}
+
+function parseBodyLimit(value: string | undefined): number {
+  // 限制请求体大小，避免前端误传大对象占满服务内存。
+  if (!value) return 1024 * 1024;
+  const limit = Number(value);
+  if (Number.isInteger(limit) && limit >= 1024 && limit <= 50 * 1024 * 1024) return limit;
+  throw new Error(`Invalid EAP_HTTP_MAX_BODY_BYTES: ${value}`);
+}

package/dist/templates/agent-api-orchestration/src/http/errors.ts

@@ -1,63 +1,63 @@
-import type { ErrorRequestHandler, RequestHandler, Response } from 'express';
-
-export class HttpError extends Error {
-  readonly status: number;
-  readonly code: string;
-
-  constructor(status: number, code: string, message: string) {
-    super(message);
-    this.name = 'HttpError';
-    this.status = status;
-    this.code = code;
-  }
-}
-
-export function badRequest(message: string): HttpError {
-  return new HttpError(400, 'bad_request', message);
-}
-
-export function notFound(message = 'Route not found'): HttpError {
-  return new HttpError(404, 'not_found', message);
-}
-
-export function asyncRoute(handler: RequestHandler): RequestHandler {
-  // Express 4 不会自动接住 Promise rejection，统一在这里转给错误处理中间件。
-  return (request, response, next) => {
-    Promise.resolve(handler(request, response, next)).catch(next);
-  };
-}
-
-export const errorHandler: ErrorRequestHandler = (error, _request, response, _next) => {
-  // 普通请求返回 JSON；如果 SSE 已经开始，则用 error 事件结束当前流。
-  // SDK 的能力错误（例如 SessionCapabilityError）也带 status/code，直接映射可保留 501 等语义。
-  const status = error instanceof HttpError ? error.status : readStatus(error) ?? 500;
-  const code = error instanceof HttpError ? error.code : readCode(error) ?? 'internal_error';
-  const message = error instanceof Error ? error.message : String(error);
-  if (response.headersSent) {
-    if (!response.destroyed) {
-      response.write(`event: error\ndata: ${JSON.stringify({ code, error: message })}\n\n`);
-      response.end();
-    }
-    return;
-  }
-  response.status(status).json({ error: message, code });
-};
-
-function readStatus(error: unknown): number | undefined {
-  if (!error || typeof error !== 'object') return undefined;
-  const status = (error as { status?: unknown }).status;
-  return typeof status === 'number' && status >= 400 && status <= 599 ? status : undefined;
-}
-
-function readCode(error: unknown): string | undefined {
-  if (!error || typeof error !== 'object') return undefined;
-  const code = (error as { code?: unknown }).code;
-  return typeof code === 'string' && code.trim() ? code : undefined;
-}
-
-export function sendSseError(response: Response, error: unknown): void {
-  if (response.destroyed) return;
-  const message = error instanceof Error ? error.message : String(error);
-  response.write(`event: error\ndata: ${JSON.stringify({ code: 'stream_error', error: message })}\n\n`);
-  response.end();
-}
+import type { ErrorRequestHandler, RequestHandler, Response } from 'express';
+
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = 'HttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function badRequest(message: string): HttpError {
+  return new HttpError(400, 'bad_request', message);
+}
+
+export function notFound(message = 'Route not found'): HttpError {
+  return new HttpError(404, 'not_found', message);
+}
+
+export function asyncRoute(handler: RequestHandler): RequestHandler {
+  // Express 4 不会自动接住 Promise rejection，统一在这里转给错误处理中间件。
+  return (request, response, next) => {
+    Promise.resolve(handler(request, response, next)).catch(next);
+  };
+}
+
+export const errorHandler: ErrorRequestHandler = (error, _request, response, _next) => {
+  // 普通请求返回 JSON；如果 SSE 已经开始，则用 error 事件结束当前流。
+  // SDK 的能力错误（例如 SessionCapabilityError）也带 status/code，直接映射可保留 501 等语义。
+  const status = error instanceof HttpError ? error.status : readStatus(error) ?? 500;
+  const code = error instanceof HttpError ? error.code : readCode(error) ?? 'internal_error';
+  const message = error instanceof Error ? error.message : String(error);
+  if (response.headersSent) {
+    if (!response.destroyed) {
+      response.write(`event: error\ndata: ${JSON.stringify({ code, error: message })}\n\n`);
+      response.end();
+    }
+    return;
+  }
+  response.status(status).json({ error: message, code });
+};
+
+function readStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const status = (error as { status?: unknown }).status;
+  return typeof status === 'number' && status >= 400 && status <= 599 ? status : undefined;
+}
+
+function readCode(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === 'string' && code.trim() ? code : undefined;
+}
+
+export function sendSseError(response: Response, error: unknown): void {
+  if (response.destroyed) return;
+  const message = error instanceof Error ? error.message : String(error);
+  response.write(`event: error\ndata: ${JSON.stringify({ code: 'stream_error', error: message })}\n\n`);
+  response.end();
+}

package/dist/templates/agent-api-orchestration/src/http/index.ts

@@ -1,4 +1,4 @@
-// 对外只暴露 Express 适配器的稳定入口，内部路由文件可按宿主需求替换。
-export { createAgentApp, createAgentHttpServer, startAgentHttpServer } from './app.js';
-export { resolveAgentHttpStartOptions } from './config.js';
-export type { AgentHttpService, AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';
+// 对外只暴露 Express 适配器的稳定入口，内部路由文件可按宿主需求替换。
+export { createAgentApp, createAgentHttpServer, startAgentHttpServer } from './app.js';
+export { resolveAgentHttpStartOptions } from './config.js';
+export type { AgentHttpService, AgentHttpStartOptions, ResolvedAgentHttpOptions } from './types.js';

package/dist/templates/agent-api-orchestration/src/http/middleware/cors.ts

@@ -1,17 +1,17 @@
-import type { RequestHandler } from 'express';
-
-export function corsMiddleware(origin: string): RequestHandler {
-  return (_request, response, next) => {
-    // 这是最小的跨域适配器；生产环境建议由宿主按自己的 Origin 白名单替换。
-    response.setHeader('Access-Control-Allow-Origin', origin);
-    response.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Correlation-Id');
-    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    response.setHeader('Access-Control-Expose-Headers', 'X-Agent-Code, X-Agent-Version');
-    response.setHeader('Vary', 'Origin');
-    if (_request.method === 'OPTIONS') {
-      response.status(204).end();
-      return;
-    }
-    next();
-  };
-}
+import type { RequestHandler } from 'express';
+
+export function corsMiddleware(origin: string): RequestHandler {
+  return (_request, response, next) => {
+    // 这是最小的跨域适配器；生产环境建议由宿主按自己的 Origin 白名单替换。
+    response.setHeader('Access-Control-Allow-Origin', origin);
+    response.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Correlation-Id');
+    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    response.setHeader('Access-Control-Expose-Headers', 'X-Agent-Code, X-Agent-Version');
+    response.setHeader('Vary', 'Origin');
+    if (_request.method === 'OPTIONS') {
+      response.status(204).end();
+      return;
+    }
+    next();
+  };
+}