@downcity/agent 1.1.1 → 1.1.6

package/src/service/ServiceStateController.ts

@@ -1,316 +0,0 @@
-/**
- * ServiceStateController：service 状态控制与状态记录模块。
- *
- * 关键点（中文）
- * - 专门负责 service 状态记录、生命周期控制、状态快照。
- * - 不处理 action payload，也不处理 HTTP route 注册。
- * - Manager.ts 只作为门面导出，真正逻辑在这里分层实现。
- */
-
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type {
-  ServiceStateControlAction,
-  ServiceStateControlResult,
-  ServiceStateRecord,
-  ServiceStateSnapshot,
-} from "@/shared/types/ServiceState.js";
-import { getAgentRuntime } from "@/agent/AgentRuntimeState.js";
-import {
-  getRegisteredStaticServiceInstances,
-  listRegisteredServices,
-  listRegisteredServiceNames,
-} from "@/service/ServiceClassRegistry.js";
-import type { BaseService } from "@services/BaseService.js";
-import type { Service, ServiceState } from "@/shared/types/Service.js";
-
-function nowMs(): number {
-  return Date.now();
-}
-
-/**
- * 列出当前进程内可见的 service 实例。
- *
- * 关键点（中文）
- * - 若 agent 已就绪，则返回 per-agent service instances。
- * - 若 agent 尚未初始化，则退回静态装配实例，方便测试与只读场景。
- */
-export function listServiceInstances(): BaseService[] {
-  try {
-    const agent = getAgentRuntime();
-    if (agent.services.size > 0) {
-      return [...agent.services.values()];
-    }
-  } catch {
-    // ignore and fallback
-  }
-  return [...getRegisteredStaticServiceInstances().values()];
-}
-
-/**
- * 按名称解析 service 实例。
- */
-export function resolveServiceByName(
-  name: string,
-): BaseService | null {
-  const key = String(name || "").trim();
-  if (!key) return null;
-  return listServiceInstances().find((service) => service.name === key) || null;
-}
-
-/**
- * 确保 service 对应的状态记录存在。
- */
-export function ensureServiceStateRecord(
-  service: BaseService,
-): ServiceStateRecord {
-  return service.serviceStateRecord;
-}
-
-function hasCommandActions(service: BaseService): boolean {
-  return Object.values(service.actions).some((action) =>
-    Boolean(action.command),
-  );
-}
-
-/**
- * 把内部 record 映射为对外快照。
- */
-export function toServiceStateSnapshot(
-  record: ServiceStateRecord,
-  service: BaseService,
-): ServiceStateSnapshot {
-  const lifecycle = service.lifecycle;
-  return {
-    name: service.name,
-    state: record.state,
-    updatedAt: record.updatedAt,
-    ...(record.lastError ? { lastError: record.lastError } : {}),
-    ...(record.lastCommand ? { lastCommand: record.lastCommand } : {}),
-    ...(typeof record.lastCommandAt === "number"
-      ? { lastCommandAt: record.lastCommandAt }
-      : {}),
-    supportsLifecycle: Boolean(lifecycle?.start || lifecycle?.stop),
-    supportsCommand:
-      Boolean(lifecycle?.command) || hasCommandActions(service),
-  };
-}
-
-async function runSerialByService(
-  record: ServiceStateRecord,
-  step: () => Promise<void> | void,
-): Promise<void> {
-  const next = record.chain.then(() => Promise.resolve(step()));
-  record.chain = next.then(
-    () => undefined,
-    () => undefined,
-  );
-  await next;
-}
-
-/**
- * 标记 service 当前状态。
- */
-export function markServiceState(
-  record: ServiceStateRecord,
-  state: ServiceState,
-  error?: string,
-): void {
-  record.state = state;
-  record.updatedAt = nowMs();
-  if (error) {
-    record.lastError = error;
-  } else {
-    delete record.lastError;
-  }
-}
-
-/**
- * 标记最近一次 service command。
- */
-export function markServiceCommand(
-  record: ServiceStateRecord,
-  command: string,
-): void {
-  record.lastCommand = command;
-  record.lastCommandAt = nowMs();
-  record.updatedAt = nowMs();
-}
-
-/**
- * 返回静态 service 定义清单。
- */
-export function getStaticServices(): Service[] {
-  return listRegisteredServices();
-}
-
-/**
- * 返回 service 根命令名清单。
- */
-export function getServiceRootCommandNames(): string[] {
-  return listRegisteredServiceNames();
-}
-
-/**
- * 列出全部 service 状态快照。
- */
-export function listServiceStates(): ServiceStateSnapshot[] {
-  return listServiceInstances()
-    .map((service) =>
-      toServiceStateSnapshot(ensureServiceStateRecord(service), service),
-    )
-    .sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * 判断指定 service 是否处于运行中。
- */
-export function isServiceRunning(serviceName: string): boolean {
-  const service = resolveServiceByName(serviceName);
-  if (!service) return false;
-  return ensureServiceStateRecord(service).state === "running";
-}
-
-async function startServiceInternal(
-  service: BaseService,
-  context: AgentContext,
-): Promise<ServiceStateControlResult> {
-  const record = ensureServiceStateRecord(service);
-  try {
-    await runSerialByService(record, async () => {
-      if (record.state === "running") return;
-      markServiceState(record, "starting");
-      try {
-        await service.lifecycle?.start?.(context);
-        markServiceState(record, "running");
-      } catch (error) {
-        markServiceState(record, "error", String(error));
-        throw error;
-      }
-    });
-    return {
-      success: true,
-      service: toServiceStateSnapshot(record, service),
-    };
-  } catch (error) {
-    return {
-      success: false,
-      service: toServiceStateSnapshot(record, service),
-      error: String(error),
-    };
-  }
-}
-
-async function stopServiceInternal(
-  service: BaseService,
-  context: AgentContext,
-): Promise<ServiceStateControlResult> {
-  const record = ensureServiceStateRecord(service);
-  try {
-    await runSerialByService(record, async () => {
-      if (record.state === "stopped") return;
-      markServiceState(record, "stopping");
-      try {
-        await service.lifecycle?.stop?.(context);
-        markServiceState(record, "stopped");
-      } catch (error) {
-        markServiceState(record, "error", String(error));
-        throw error;
-      }
-    });
-    return {
-      success: true,
-      service: toServiceStateSnapshot(record, service),
-    };
-  } catch (error) {
-    return {
-      success: false,
-      service: toServiceStateSnapshot(record, service),
-      error: String(error),
-    };
-  }
-}
-
-/**
- * 执行单个 service 状态控制动作。
- */
-export async function controlServiceState(params: {
-  serviceName: string;
-  action: ServiceStateControlAction;
-  context: AgentContext;
-}): Promise<ServiceStateControlResult> {
-  const service = resolveServiceByName(params.serviceName);
-  if (!service) {
-    return {
-      success: false,
-      error: `Unknown service: ${params.serviceName}`,
-    };
-  }
-
-  if (params.action === "status") {
-    const record = ensureServiceStateRecord(service);
-    return {
-      success: true,
-      service: toServiceStateSnapshot(record, service),
-    };
-  }
-
-  if (params.action === "start") {
-    return startServiceInternal(service, params.context);
-  }
-
-  if (params.action === "stop") {
-    return stopServiceInternal(service, params.context);
-  }
-
-  const stopped = await stopServiceInternal(service, params.context);
-  if (!stopped.success) return stopped;
-  return startServiceInternal(service, params.context);
-}
-
-/**
- * 启动全部 service。
- */
-export async function startAllServices(
-  context: AgentContext,
-): Promise<{
-  success: boolean;
-  results: ServiceStateControlResult[];
-}> {
-  const results: ServiceStateControlResult[] = [];
-  for (const service of listServiceInstances()) {
-    results.push(
-      await controlServiceState({
-        serviceName: service.name,
-        action: "start",
-        context,
-      }),
-    );
-  }
-  return {
-    success: results.every((item) => item.success),
-    results,
-  };
-}
-
-/**
- * 停止全部 service。
- */
-export async function stopAllServices(context: AgentContext): Promise<{
-  success: boolean;
-  results: ServiceStateControlResult[];
-}> {
-  const results: ServiceStateControlResult[] = [];
-  for (const service of listServiceInstances()) {
-    results.push(
-      await controlServiceState({
-        serviceName: service.name,
-        action: "stop",
-        context,
-      }),
-    );
-  }
-  return {
-    success: results.every((item) => item.success),
-    results,
-  };
-}

package/src/service/ServiceSystemProviders.ts

@@ -1,50 +0,0 @@
-/**
- * ServiceSystemProviders：service system prompt 的静态提供器清单。
- *
- * 关键点（中文）
- * - 这里仅负责收集各 service 的 system 文本提供器。
- * - 不依赖完整 service instance，避免把 system 域与 service 运行态耦合在一起。
- * - 这样也能避开 `task -> runner -> prompt system -> service class registry` 的循环依赖。
- */
-
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import { buildChatServiceSystem } from "@services/chat/runtime/ChatServiceSystem.js";
-import { buildContactServiceSystemText } from "@services/contact/runtime/SystemProvider.js";
-import { buildMemoryServiceSystemText } from "@services/memory/runtime/SystemProvider.js";
-import { TASK_SERVICE_PROMPT } from "@services/task/runtime/TaskServiceSystem.js";
-
-/**
- * 单个 service 的 system provider。
- */
-export type ServiceSystemProvider = {
-  /**
-   * 对应的 service 名称。
-   */
-  name: string;
-  /**
-   * 生成该 service system 文本的函数。
-   */
-  system: (context: AgentContext) => Promise<string> | string;
-};
-
-/**
- * 全部静态 service system providers。
- */
-export const SERVICE_SYSTEM_PROVIDERS: ServiceSystemProvider[] = [
-  {
-    name: "chat",
-    system: buildChatServiceSystem,
-  },
-  {
-    name: "contact",
-    system: buildContactServiceSystemText,
-  },
-  {
-    name: "task",
-    system: () => TASK_SERVICE_PROMPT,
-  },
-  {
-    name: "memory",
-    system: buildMemoryServiceSystemText,
-  },
-];

package/src/service/Services.ts

@@ -1,33 +0,0 @@
-/**
- * Service 类注册表（单一事实源）。
- *
- * 关键点（中文）
- * - 统一维护所有可注册 service class，避免 Manager/AgentRuntime 各自硬编码。
- * - 这里只声明“有哪些 service class”，不承载运行态逻辑。
- */
-
-import type { AgentRuntime } from "@/types/agent/AgentRuntime.js";
-import type { BaseService } from "@services/BaseService.js";
-import { ChatService } from "@services/chat/ChatService.js";
-import { TaskService } from "@services/task/TaskService.js";
-import { MemoryService } from "@services/memory/MemoryService.js";
-import { ShellService } from "@services/shell/ShellService.js";
-import { ContactService } from "@services/contact/ContactService.js";
-
-/**
- * 单个 service class 构造器。
- */
-export type ServiceClass<T extends BaseService = BaseService> = new (
-  agent: AgentRuntime | null,
-) => T;
-
-/**
- * 全部已注册 service classes。
- */
-export const SERVICE_CLASSES: ServiceClass[] = [
-  ChatService,
-  ContactService,
-  TaskService,
-  MemoryService,
-  ShellService,
-];

package/src/services/BaseService.ts

@@ -1,85 +0,0 @@
-/**
- * BaseService：service 类实现的统一基类。
- *
- * 关键点（中文）
- * - agent 会持有 per-agent 的 service instance，而不再直接依赖全局 service 单例对象。
- * - 各 service 的长期状态应归属于实例本身，而不是模块级单例。
- */
-
-import type { AgentRuntime } from "@/types/agent/AgentRuntime.js";
-import type {
-  Service,
-  ServiceActions,
-  ServiceLifecycle,
-} from "@/shared/types/Service.js";
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type { ServiceStateRecord } from "@/shared/types/ServiceState.js";
-
-/**
- * BaseService 抽象基类。
- *
- * 关键点（中文）
- * - 保留统一 `Service` 契约。
- * - 为实例字段状态（cronEngine / queueWorker / watchers / shellSessions）预留宿主引用。
- */
-export abstract class BaseService implements Service {
-  /**
-   * 当前实例持有的通用 service 状态记录。
-   *
-   * 关键点（中文）
-   * - 通用 lifecycle 状态直接归属于 service 实例。
-   * - `ServiceStateController` 只负责读写，不再维护全局状态表。
-   */
-  public readonly serviceStateRecord: ServiceStateRecord = {
-    state: "stopped",
-    updatedAt: Date.now(),
-    chain: Promise.resolve(),
-  };
-
-  /**
-   * 当前 service 所属的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - 允许为空，仅用于静态装配与无宿主测试场景。
-   * - 真正运行中的 service 实例应始终绑定一个 agent。
-   */
-  protected readonly agent: AgentRuntime | null;
-
-  constructor(agent: AgentRuntime | null) {
-    this.agent = agent;
-  }
-
-  /**
-   * 当前 service 名称。
-   */
-  abstract readonly name: string;
-
-  /**
-   * 当前 service 的 action 定义表。
-   */
-  abstract readonly actions: ServiceActions;
-
-  /**
-   * 可选的 service 级 system 文本提供器。
-   */
-  system?(context: AgentContext): string | Promise<string>;
-
-  /**
-   * 可选的 service 生命周期定义。
-   */
-  lifecycle?: ServiceLifecycle;
-
-  /**
-   * 读取绑定的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - 仅供后续真正 class service 在实例方法中读取宿主能力。
-   * - 未绑定 agent 时直接 fail-fast，避免静默读取 undefined。
-   */
-  protected requireAgent(): AgentRuntime {
-    if (this.agent) return this.agent;
-    throw new Error(
-      `Service "${this.name}" is not bound to an agent instance.`,
-    );
-  }
-}