@downcity/agent 1.1.7 → 1.1.10

package/src/service/types/Service.ts

@@ -0,0 +1,223 @@
+/**
+ * Service 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 service 体系的共享契约。
+ * - 这些类型会被 service 管理层、内建 service 与测试多处复用，因此收敛在 `service/types/`。
+ * - `service/core/ServiceManager.ts` 之后只保留门面 re-export，不再承担类型源文件职责。
+ */
+
+import type { Command } from "commander";
+import type { Context as HonoContext } from "hono";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { JsonValue } from "@/utils/types/Json.js";
+
+/**
+ * 服务运行状态。
+ *
+ * 说明（中文）
+ * - `starting` / `stopping` 仅用于生命周期控制中的过渡态。
+ * - `error` 表示最近一次控制或命令执行失败后留下的状态标记。
+ */
+export type ServiceState =
+  | "running"
+  | "stopped"
+  | "starting"
+  | "stopping"
+  | "error";
+
+/**
+ * 服务命令执行结果。
+ */
+export type ServiceCommandResult = {
+  /**
+   * 本次命令是否执行成功。
+   */
+  success: boolean;
+  /**
+   * 对人类可读的补充说明文本。
+   */
+  message?: string;
+  /**
+   * 命令附带返回的数据载荷。
+   */
+  data?: JsonValue;
+};
+
+/**
+ * 单个 action 执行结果。
+ */
+export type ServiceActionResult<R extends JsonValue = JsonValue> = {
+  /**
+   * action 是否执行成功。
+   */
+  success: boolean;
+  /**
+   * action 成功时返回的数据载荷。
+   */
+  data?: R;
+  /**
+   * action 失败时返回的错误文本。
+   */
+  error?: string;
+};
+
+/**
+ * Action CLI 输入。
+ */
+export type ServiceActionCommandInput = {
+  /**
+   * 位置参数列表。
+   */
+  args: string[];
+  /**
+   * 解析后的 option 键值对。
+   */
+  opts: Record<string, JsonValue>;
+};
+
+/**
+ * Action CLI 定义。
+ */
+export type ServiceActionCommand<P extends JsonValue = JsonValue> = {
+  /**
+   * CLI 子命令描述。
+   */
+  description: string;
+  /**
+   * 对 commander command 的额外配置。
+   */
+  configure?: (command: Command) => void;
+  /**
+   * 把 CLI 输入映射为结构化 payload。
+   */
+  mapInput: (input: ServiceActionCommandInput) => P | Promise<P>;
+};
+
+/**
+ * Action HTTP 定义。
+ */
+export type ServiceActionApi<P extends JsonValue = JsonValue> = {
+  /**
+   * HTTP 方法。
+   */
+  method?: "GET" | "POST" | "PUT" | "DELETE";
+  /**
+   * 自定义路由路径；省略时走默认 `/service/<service>/<action>`。
+   */
+  path?: string;
+  /**
+   * 把 HTTP 请求映射为结构化 payload。
+   */
+  mapInput?: (ctx: HonoContext) => P | Promise<P>;
+};
+
+/**
+ * 单个 service action 定义。
+ */
+export type ServiceAction<
+  P extends JsonValue = JsonValue,
+  R extends JsonValue = JsonValue,
+> = {
+  /**
+   * CLI 定义；省略则该 action 不暴露为 CLI 子命令。
+   */
+  command?: ServiceActionCommand<P>;
+  /**
+   * HTTP API 定义；省略则该 action 不注册 HTTP 路由。
+   */
+  api?: ServiceActionApi<P>;
+  /**
+   * action 的实际执行函数。
+   */
+  execute: (params: {
+    /**
+     * 当前统一执行上下文。
+     */
+    context: AgentContext;
+    /**
+     * 当前 action 的结构化输入。
+     */
+    payload: P;
+    /**
+     * 当前 service 名称。
+     */
+    serviceName: string;
+    /**
+     * 当前 action 名称。
+     */
+    actionName: string;
+  }) => Promise<ServiceActionResult<R>> | ServiceActionResult<R>;
+};
+
+/**
+ * Service action 映射。
+ *
+ * 关键点（中文）
+ * - key 就是 action 名称。
+ * - 使用对象结构，便于直接按名称索引和动态装配。
+ */
+export type ServiceActions = {
+  [actionName: string]: ServiceAction<JsonValue, JsonValue>;
+};
+
+/**
+ * Service 生命周期扩展能力。
+ */
+export interface ServiceLifecycle {
+  /**
+   * service 启动钩子。
+   */
+  start?(context: AgentContext): Promise<void> | void;
+  /**
+   * service 停止钩子。
+   */
+  stop?(context: AgentContext): Promise<void> | void;
+  /**
+   * 非 action 命令分发钩子。
+   */
+  command?(params: {
+    /**
+     * 当前统一执行上下文。
+     */
+    context: AgentContext;
+    /**
+     * 当前命令名称。
+     */
+    command: string;
+    /**
+     * 可选 payload。
+     */
+    payload?: JsonValue;
+  }): Promise<ServiceCommandResult> | ServiceCommandResult;
+}
+
+/**
+ * Service：服务统一契约。
+ *
+ * 关键点（中文）
+ * - 一个 service 至少要提供稳定名称与 action 集合。
+ * - 生命周期钩子与 system 构建器都是可选能力，不强制所有 service 实现。
+ */
+export interface Service {
+  /**
+   * service 名称。
+   */
+  name: string;
+  /**
+   * action 集合。
+   *
+   * 关键点（中文）
+   * - 一个 service 对应多个 action。
+   * - main 会基于这里自动注册 CLI 与 HTTP 路由。
+   */
+  actions: ServiceActions;
+  /**
+   * service 级 system 文本构建器。
+   */
+  system?: (context: AgentContext) => string | Promise<string>;
+  /**
+   * service 生命周期钩子集合。
+   */
+  lifecycle?: ServiceLifecycle;
+}

package/src/service/types/ServiceSchedule.ts

@@ -0,0 +1,134 @@
+/**
+ * Service Schedule 类型定义。
+ *
+ * 关键点（中文）
+ * - 统一描述“延迟/定时执行 service action”的持久化记录结构。
+ * - 该模块只承载调度层状态，不耦合具体 service 的业务语义。
+ */
+
+import type { JsonValue } from "@/utils/types/Json.js";
+
+/**
+ * 调度任务状态。
+ *
+ * 说明（中文）
+ * - `pending`：等待到点执行。
+ * - `running`：已被调度器领取，当前正在执行。
+ * - `succeeded`：执行成功。
+ * - `failed`：执行失败。
+ * - `cancelled`：已取消，不再执行。
+ */
+export type ScheduledJobStatus =
+  | "pending"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled";
+
+/**
+ * 调度任务完整记录。
+ */
+export interface ScheduledJobRecord {
+  /**
+   * 调度任务唯一 ID。
+   *
+   * 说明（中文）
+   * - 由 runtime 创建并稳定持久化。
+   * - 用于取消、查询、状态更新与恢复。
+   */
+  id: string;
+
+  /**
+   * 目标 service 名称。
+   *
+   * 说明（中文）
+   * - 对应 `city <service> <action>` 中的 `<service>`。
+   */
+  serviceName: string;
+
+  /**
+   * 目标 action 名称。
+   *
+   * 说明（中文）
+   * - 对应 `city <service> <action>` 中的 `<action>`。
+   */
+  actionName: string;
+
+  /**
+   * 原始 action payload。
+   *
+   * 说明（中文）
+   * - 直接保存 service action 的 JSON payload。
+   * - 调度器到点后会原样回放给 `runServiceCommand(...)`。
+   */
+  payload: JsonValue;
+
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   *
+   * 说明（中文）
+   * - 统一归一化为 Unix epoch ms。
+   */
+  runAtMs: number;
+
+  /**
+   * 当前调度状态。
+   */
+  status: ScheduledJobStatus;
+
+  /**
+   * 最近一次错误文本。
+   *
+   * 说明（中文）
+   * - 仅在失败场景下写入。
+   */
+  error?: string;
+
+  /**
+   * 创建时间（毫秒时间戳）。
+   */
+  createdAt: number;
+
+  /**
+   * 最近更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+}
+
+/**
+ * 创建调度任务所需输入。
+ */
+export interface CreateScheduledJobInput {
+  /**
+   * 目标 service 名称。
+   */
+  serviceName: string;
+
+  /**
+   * 目标 action 名称。
+   */
+  actionName: string;
+
+  /**
+   * 目标 action payload。
+   */
+  payload: JsonValue;
+
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+}
+
+/**
+ * 统一 service command 调度输入。
+ */
+export interface ServiceCommandScheduleInput {
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   *
+   * 说明（中文）
+   * - command 层统一只接收归一化后的绝对时间。
+   */
+  runAtMs: number;
+}

package/src/service/types/ServiceState.ts

@@ -0,0 +1,112 @@
+/**
+ * ServiceState：service 状态相关共享类型。
+ *
+ * 关键点（中文）
+ * - 这里只放状态快照与控制结果，不放 service 契约本身。
+ * - 目的是让 main/service 内部拆分后，仍能共享统一的状态结构。
+ */
+
+import type { ServiceState } from "@/service/types/Service.js";
+
+/**
+ * 单个 service 实例内部持有的状态记录。
+ *
+ * 关键点（中文）
+ * - 这是 service 实例级的内部状态，不直接暴露给外部 API。
+ * - `ServiceStateController` 负责更新它，service 实例负责持有它。
+ */
+export type ServiceStateRecord = {
+  /**
+   * 当前运行状态。
+   */
+  state: ServiceState;
+  /**
+   * 最近一次状态更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+  /**
+   * 最近一次错误信息。
+   */
+  lastError?: string;
+  /**
+   * 最近一次执行的命令名。
+   */
+  lastCommand?: string;
+  /**
+   * 最近一次执行命令的时间（毫秒时间戳）。
+   */
+  lastCommandAt?: number;
+  /**
+   * 当前串行控制链。
+   *
+   * 关键点（中文）
+   * - 用于把同一 service 的 start/stop/restart 串行化。
+   * - 避免并发控制命令把状态机打乱。
+   */
+  chain: Promise<void>;
+};
+
+/**
+ * 单个 service 状态的对外快照。
+ */
+export type ServiceStateSnapshot = {
+  /**
+   * service 名称。
+   */
+  name: string;
+  /**
+   * 当前运行状态。
+   */
+  state: ServiceState;
+  /**
+   * 最近一次状态更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+  /**
+   * 最近一次错误信息。
+   */
+  lastError?: string;
+  /**
+   * 最近一次执行的命令名。
+   */
+  lastCommand?: string;
+  /**
+   * 最近一次执行命令的时间（毫秒时间戳）。
+   */
+  lastCommandAt?: number;
+  /**
+   * 是否支持 start/stop 生命周期控制。
+   */
+  supportsLifecycle: boolean;
+  /**
+   * 是否支持 command/action 命令调用。
+   */
+  supportsCommand: boolean;
+};
+
+/**
+ * service 状态控制动作。
+ */
+export type ServiceStateControlAction =
+  | "start"
+  | "stop"
+  | "restart"
+  | "status";
+
+/**
+ * service 状态控制结果。
+ */
+export type ServiceStateControlResult = {
+  /**
+   * 控制动作是否成功。
+   */
+  success: boolean;
+  /**
+   * 成功或失败后返回的最新 service 快照。
+   */
+  service?: ServiceStateSnapshot;
+  /**
+   * 失败时的错误信息。
+   */
+  error?: string;
+};

package/src/service/types/Services.ts

@@ -0,0 +1,100 @@
+/**
+ * service 管理命令类型。
+ *
+ * 关键点（中文）
+ * - 统一描述 CLI -> daemon 的 service 管理协议
+ * - 支持 lifecycle 控制与通用 command 转发
+ */
+
+import type { JsonValue } from "@/utils/types/Json.js";
+
+export type ServiceControlAction = "start" | "stop" | "restart" | "status";
+
+/**
+ * 单个 service 的对外状态视图。
+ */
+export type ServiceStateView = {
+  /** service 稳定名称。 */
+  name: string;
+  /** 当前运行状态。 */
+  state: "running" | "stopped" | "starting" | "stopping" | "error";
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名称。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 当前 service 是否支持显式 start/stop 生命周期控制。 */
+  supportsLifecycle: boolean;
+  /** 当前 service 是否支持 command/action 调用。 */
+  supportsCommand: boolean;
+};
+
+/**
+ * service 列表响应。
+ */
+export type ServiceListResponse = {
+  /** 本次读取是否成功。 */
+  success: boolean;
+  /** 成功时返回的 service 状态列表。 */
+  services?: ServiceStateView[];
+  /** 失败时返回的错误信息。 */
+  error?: string;
+};
+
+/**
+ * service 生命周期控制响应。
+ */
+export type ServiceControlResponse = {
+  /** 本次控制动作是否成功。 */
+  success: boolean;
+  /** 成功时返回最新的 service 状态视图。 */
+  service?: ServiceStateView;
+  /** 失败时的错误信息。 */
+  error?: string;
+};
+
+/**
+ * service command/action 执行响应。
+ */
+export type ServiceCommandResponse = {
+  /** 本次 command/action 是否执行成功。 */
+  success: boolean;
+  /** 当前 service 的最新状态视图。 */
+  service?: ServiceStateView;
+  /** 面向人类可读的补充文本。 */
+  message?: string;
+  /** command/action 的数据输出。 */
+  data?: JsonValue;
+  /** 失败时的错误信息。 */
+  error?: string;
+};
+
+export type ServiceCliBaseOptions = {
+  /**
+   * agent 项目路径（默认当前目录）。
+   */
+  path?: string;
+  /**
+   * agent 名称（从 managed agent registry 解析到项目路径）。
+   */
+  agent?: string;
+  /**
+   * 覆盖服务主机地址。
+   */
+  host?: string;
+  /**
+   * 覆盖服务端口。
+   */
+  port?: number;
+  /**
+   * 显式覆盖 Bearer Token。
+   */
+  token?: string;
+  /**
+   * 是否输出 JSON。
+   */
+  json?: boolean;
+};

package/src/session/Session.ts

@@ -12,10 +12,10 @@ import type { SessionHistoryComposer } from "@session/composer/history/SessionHi
 import { withSessionRunScope } from "@session/SessionRunScope.js";
 import type { SessionRunScope } from "@session/SessionRunScope.js";
 import { buildSessionStepEventMessages } from "@session/messages/SessionStepEventMapper.js";
-import type { JsonObject } from "@/shared/types/Json.js";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { SessionExecutor } from "@/types/session/SessionExecutor.js";
-import type { SessionRunResult } from "@/types/session/SessionRun.js";
+import type { JsonObject } from "@/utils/types/Json.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionExecutor } from "@/session/types/SessionExecutor.js";
+import type { SessionRunResult } from "@/session/types/SessionRun.js";
 
 type SessionOptions = {
   /**

package/src/session/SessionRunScope.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionUserMessageV1 } from "@/types/session/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
 import type {
   SessionAssistantStepCallback,
   SessionUiMessageChunkCallback,
-} from "@/types/session/SessionRun.js";
+} from "@/session/types/SessionRun.js";
 
 /**
  * SessionRunScope（单次请求作用域）。

package/src/session/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -15,13 +15,13 @@ import {
   type LanguageModel,
   type SystemModelMessage,
 } from "ai";
-import { generateId } from "@shared/utils/Id.js";
-import { getLogger } from "@shared/utils/logger/Logger.js";
+import { generateId } from "@/utils/Id.js";
+import { getLogger } from "@/utils/logger/Logger.js";
 import type {
   SessionMessageV1,
   SessionMetadataV1,
-} from "@/types/session/SessionMessages.js";
-import type { SessionHistoryMetaV1 } from "@/types/session/SessionHistoryMeta.js";
+} from "@/session/types/SessionMessages.js";
+import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
 
 export type SessionCompactParams = {
   model: LanguageModel;

package/src/session/composer/execution/LocalSessionExecutionComposer.ts

@@ -7,7 +7,7 @@
  */
 
 import type { ModelMessage } from "ai";
-import { generateId } from "@shared/utils/Id.js";
+import { generateId } from "@/utils/Id.js";
 import {
   drainInjectedUserMessages,
   getSessionRunScope,
@@ -16,8 +16,8 @@ import { SessionExecutionComposer } from "@session/composer/execution/SessionExe
 import type {
   SessionExecutionComposeResult,
 } from "@session/composer/execution/SessionExecutionComposer.js";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
 import type { Tool } from "ai";
 
 type LocalSessionExecutionComposerOptions = {

package/src/session/composer/execution/SessionExecutionComposer.ts

@@ -7,8 +7,8 @@
  */
 
 import type { ModelMessage, Tool } from "ai";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
 import { SessionComposer } from "@session/composer/SessionComposer.js";
 
 /**

package/src/session/composer/history/SessionHistoryComposer.ts

@@ -10,8 +10,8 @@ import type { LanguageModel, Tool } from "ai";
 import type {
   SessionMessageV1,
   SessionMetadataV1,
-} from "@/types/session/SessionMessages.js";
-import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
+} from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
 import { SessionComposer } from "@session/composer/SessionComposer.js";
 
 /**

package/src/session/composer/history/SessionHistoryWriter.ts

@@ -7,11 +7,11 @@
  * - 会话更新后的通知也收在这里，避免把写入细节散到 Session 主类里。
  */
 
-import type { JsonObject } from "@/shared/types/Json.js";
+import type { JsonObject } from "@/utils/types/Json.js";
 import type {
   SessionMessageV1,
   SessionMetadataV1,
-} from "@/types/session/SessionMessages.js";
+} from "@/session/types/SessionMessages.js";
 import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
 
 type SessionHistoryWriterOptions = {

package/src/session/composer/history/jsonl/JsonlSessionHistoryComposer.ts

@@ -17,16 +17,16 @@ import path from "node:path";
 import {
   type Tool,
 } from "ai";
-import { generateId } from "@shared/utils/Id.js";
-import { getLogger } from "@shared/utils/logger/Logger.js";
+import { generateId } from "@/utils/Id.js";
+import { getLogger } from "@/utils/logger/Logger.js";
 import { compactSessionMessagesIfNeeded } from "@session/composer/compaction/jsonl/JsonlSessionCompactionExecutor.js";
 import type {
   SessionMessageV1,
   SessionMetadataV1,
-} from "@/types/session/SessionMessages.js";
-import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
-import type { SessionHistoryMetaV1 } from "@/types/session/SessionHistoryMeta.js";
-import type { SessionHistoryPathOverrides } from "@/types/session/SessionHistoryPaths.js";
+} from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
+import type { SessionHistoryPathOverrides } from "@/session/types/SessionHistoryPaths.js";
 import {
   SessionHistoryComposer,
   type SessionHistoryCompactInput,