@downcity/agent 1.1.25 → 1.1.35

package/src/runtime/server/http/services/services.ts

@@ -1,98 +0,0 @@
-/**
- * Service 路由模块。
- *
- * 职责说明：
- * 1. 提供 service 状态列表接口。
- * 2. 提供 service lifecycle 控制接口。
- * 3. 提供统一 service command 桥接。
- */
-
-import { Hono } from "hono";
-import {
-  controlServiceState,
-  listServiceStates,
-  runServiceCommand,
-} from "@/service/core/Manager.js";
-import type { ServiceStateControlAction } from "@/service/core/Manager.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import { parseServiceCommandRequestBody } from "@/service/core/ServiceCommandRequest.js";
-
-/**
- * Service 路由参数。
- */
-type ServicesRouterOptions = {
-  /**
-   * 读取当前 agent 执行上下文。
-   */
-  getAgentContext: () => AgentContext;
-};
-
-/**
- * 创建 service 路由。
- */
-export function createServicesRouter(
-  options: ServicesRouterOptions,
-): Hono {
-  const router = new Hono();
-
-  router.get("/api/services/list", (c) => {
-    const context = options.getAgentContext();
-    return c.json({
-      success: true,
-      services: listServiceStates({ context }),
-    });
-  });
-
-  router.post("/api/services/control", async (c) => {
-    const body = await c.req.json().catch(() => null);
-    const serviceName = String(body?.serviceName || "").trim();
-    const action = String(body?.action || "")
-      .trim()
-      .toLowerCase();
-
-    if (!serviceName) {
-      return c.json({ success: false, error: "serviceName is required" }, 400);
-    }
-    if (!action) {
-      return c.json({ success: false, error: "action is required" }, 400);
-    }
-    if (!["start", "stop", "restart", "status"].includes(action)) {
-      return c.json({ success: false, error: "invalid action" }, 400);
-    }
-
-    const result = await controlServiceState({
-      serviceName,
-      action: action as ServiceStateControlAction,
-      context: options.getAgentContext(),
-    });
-    return c.json(result, result.success ? 200 : 400);
-  });
-
-  router.post("/api/services/command", async (c) => {
-    const body = await c.req.json().catch(() => null);
-    let requestBody;
-    try {
-      requestBody = parseServiceCommandRequestBody(body);
-    } catch (error) {
-      return c.json({ success: false, error: String(error) }, 400);
-    }
-
-    if (!requestBody.serviceName) {
-      return c.json({ success: false, error: "serviceName is required" }, 400);
-    }
-    if (!requestBody.command) {
-      return c.json({ success: false, error: "command is required" }, 400);
-    }
-
-    const result = await runServiceCommand({
-      serviceName: requestBody.serviceName,
-      command: requestBody.command,
-      payload: requestBody.payload,
-      schedule: requestBody.schedule,
-      context: options.getAgentContext(),
-    });
-    return c.json(result, result.success ? 200 : 400);
-  });
-
-  return router;
-}

package/src/sdk/session/ServicePort.ts

@@ -1,130 +0,0 @@
-/**
- * SDK Session service 端口构造器。
- *
- * 关键点（中文）
- * - 把 SDK 本地 session 适配成 runtime / service 依赖的 `SessionPort`。
- * - SDK 公开面只保留 `prompt()` / `subscribe()`；内部单轮执行原语仍通过这里暴露给 service/runtime。
- */
-
-import type { SessionPort } from "@/core/AgentContextTypes.js";
-import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
-import type { SessionRunResult } from "@/session/types/SessionRun.js";
-import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
-import type {
-  SessionAssistantStepCallback,
-  SessionUiMessageChunkCallback,
-} from "@/session/types/SessionRun.js";
-import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
-import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
-import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-
-/**
- * 构造 SDK SessionPort 的参数。
- */
-export interface CreateSessionServicePortParams {
-  /**
-   * 当前 sessionId。
-   */
-  sessionId: string;
-  /**
-   * 读取当前 session 底层执行端口。
-   */
-  getExecutor: SessionPort["getExecutor"];
-  /**
-   * 运行一次内部 direct execution。
-   *
-   * 关键点（中文）
-   * - 这是 runtime / service 侧保留的内部原语。
-   * - 它不属于 SDK 用户推荐直接调用的公开模式。
-   */
-  executeDirect: (params: {
-    query: string;
-    onStepCallback?: () => Promise<SessionUserMessageV1[]>;
-    onAssistantStepCallback?: SessionAssistantStepCallback;
-    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
-  }) => Promise<SessionRunResult>;
-  /**
-   * 追加一条新的 session prompt。
-   */
-  prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
-  /**
-   * 订阅当前 session 的 future 事件。
-   */
-  subscribe: (
-    subscriber: AgentSessionSubscriber,
-  ) => AgentSessionUnsubscribe;
-  /**
-   * 清理当前 session executor 状态。
-   */
-  clearExecutor: () => void;
-  /**
-   * session 更新后的异步通知回调。
-   */
-  afterSessionUpdatedAsync: () => Promise<void>;
-  /**
-   * 追加 user 消息到底层历史。
-   */
-  appendUserMessage: SessionPort["appendUserMessage"];
-  /**
-   * 追加 assistant 消息到底层历史。
-   */
-  appendAssistantMessage: SessionPort["appendAssistantMessage"];
-  /**
-   * 返回当前 session 是否正在执行。
-   */
-  isExecuting: () => boolean;
-  /**
-   * 当前 session 历史持久化端口。
-   */
-  historyStore: SessionHistoryStore;
-  /**
-   * 在执行前确保当前 session 已完成初始化与宿主级配置。
-   */
-  ensureReadyForExecution: () => Promise<void>;
-  /**
-   * session 更新后需要同步执行的持久化回调。
-   */
-  touchMetadata: () => Promise<void>;
-}
-
-/**
- * 创建供 service 使用的 session 端口。
- */
-export function createSessionServicePort(
-  params: CreateSessionServicePortParams,
-): SessionPort {
-  return {
-    sessionId: params.sessionId,
-    getExecutor: () => params.getExecutor(),
-    getHistoryStore: () => params.historyStore,
-    execute: async (runParams) => {
-      await params.ensureReadyForExecution();
-      return await params.executeDirect(runParams);
-    },
-    prompt: async (input) => {
-      await params.ensureReadyForExecution();
-      return await params.prompt(input);
-    },
-    subscribe: (subscriber) => {
-      return params.subscribe(subscriber);
-    },
-    clearExecutor: () => {
-      params.clearExecutor();
-    },
-    afterSessionUpdatedAsync: async () => {
-      await params.afterSessionUpdatedAsync();
-    },
-    appendUserMessage: async (messageParams) => {
-      await params.appendUserMessage(messageParams);
-      await params.touchMetadata();
-    },
-    appendAssistantMessage: async (messageParams) => {
-      await params.appendAssistantMessage(messageParams);
-      await params.touchMetadata();
-    },
-    isExecuting: () => params.isExecuting(),
-  };
-}

package/src/service/builtins/BaseService.ts

@@ -1,97 +0,0 @@
-/**
- * BaseService：service 类实现的统一基类。
- *
- * 关键点（中文）
- * - agent 会持有 per-agent 的 service instance，而不再直接依赖全局 service 单例对象。
- * - 各 service 的长期状态应归属于实例本身，而不是模块级单例。
- */
-
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import type {
-  Service,
-  ServiceActions,
-  ServiceLifecycle,
-} from "@/service/types/Service.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ServiceStateRecord } from "@/service/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 agent: AgentRuntime | null;
-
-  constructor(agent: AgentRuntime | null = 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;
-
-  /**
-   * 绑定当前 service 所属的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - SDK `new Agent({ services: [...] })` 会在装配阶段调用这里完成后绑定。
-   * - 若 service 已在构造阶段绑定过宿主，则这里允许覆盖到新的宿主实例。
-   */
-  bindAgent(agent: AgentRuntime | null): this {
-    this.agent = agent;
-    return this;
-  }
-
-  /**
-   * 读取绑定的 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.`,
-    );
-  }
-}

package/src/service/builtins/README.md

@@ -1,121 +0,0 @@
-# services
-
-## 模块定位
-
-`service/builtins/` 是 Downcity 的内建主动业务层。  
-每个 service 对外暴露统一的 `Service` 契约，但在运行时已经逐步迁移为 `BaseService` 子类，由 agent 在启动时创建 `per-agent service instance`。
-
-## 当前整体模型
-
-1. `service/core/Services.ts`
-   - 维护 service 的静态注册清单。
-2. `service/core/ServiceClassRegistry.ts`
-   - 负责把静态 service 定义实例化为 `BaseService` 子类。
-3. `runtime/AgentRuntime.ts`
-   - agent 持有当前运行中的 service 实例集合。
-4. `service/core/Manager.ts`
-   - 统一做 service lifecycle、action 调度、CLI/API 桥接。
-5. `service/types/Service.ts`
-   - 作为 service 共享契约的单一事实源。
-
-## 当前内建 service
-
-1. `chat/`
-   - 负责聊天渠道接入、session 路由、消息发送与会话查询。
-   - `ChatService.ts` 是实例入口。
-   - `ChatService` 只保留实例骨架，持有实例级 `channelState` 与 `queueWorker`。
-   - `runtime/ChatServiceActions.ts` 负责 action 注册表装配。
-   - `runtime/ChatServiceSystem.ts` 负责 system prompt。
-   - `runtime/ChatChannelCore.ts` 负责渠道基础 helper。
-   - `runtime/ChatChannelLifecycle.ts` 负责渠道 bot 生命周期。
-   - `runtime/ChatChannelConfig.ts` 负责状态快照与配置落盘。
-   - `runtime/ChatChannelActions.ts` 负责渠道类 action 执行。
-   - `runtime/ChatChannelFacade.ts` 只保留门面导出。
-   - `runtime/ChatActionInput.ts` 负责非 send 类 CLI/API 输入映射与统一导出。
-   - `runtime/ChatSendActionInput.ts` 负责 `chat send` 正文协议、stdin/file 与定时发送输入映射。
-   - `runtime/ChatActionInputSupport.ts` 负责 chat action 输入映射共享解析辅助。
-   - `runtime/ChatActionExecution.ts` 负责消息类 action 执行。
-   - `runtime/ChatQueueSessionBridge.ts` 负责 queue 与 session 的桥接写入协议。
-   - `runtime/ChatQueueWorkerSupport.ts` 负责 worker 辅助能力。
-   - `runtime/ChatQueueReplyDispatch.ts` 负责 direct/fallback 回复分发。
-   - `runtime/ChatQueueWorker.ts` 负责 queue lane 调度与主执行链。
-   - `channels/BaseChatChannel.ts` 负责渠道基类门面与公共编排。
-   - `channels/BaseChatChannelSupport.ts` 负责 session 映射、history 与 chat meta 辅助。
-   - `channels/BaseChatChannelQueue.ts` 负责 audit/exec 入队编排。
-   - `channels/telegram/Bot.ts` 现在只保留 Telegram 渠道门面与编排。
-   - `channels/telegram/TelegramMessageHandler.ts` 负责 Telegram 普通消息授权、附件与执行入队。
-   - `channels/telegram/TelegramPendingUpdates.ts` 负责 Telegram 积压 updates 的 audit 补录。
-   - `channels/telegram/TelegramPlatformClient.ts` 负责 Telegram polling/API/发送主逻辑。
-   - `channels/telegram/TelegramInbound.ts` 负责 Telegram 入站归一化辅助。
-   - `channels/feishu/Feishu.ts` 现在只保留 Feishu 渠道门面与编排。
-   - `channels/feishu/FeishuMessageHandler.ts` 负责 Feishu 入站去重、授权、附件与执行入队。
-   - `channels/feishu/FeishuPlatformClient.ts` 负责 Feishu runtime 宿主与 token/cache 状态。
-   - `channels/feishu/FeishuPlatformLookup.ts` 负责 Feishu 用户/群聊/reply 查询与入站附件下载。
-   - `channels/feishu/FeishuPlatformMessaging.ts` 负责 Feishu 消息发送与附件上传。
-   - `channels/feishu/FeishuInbound.ts` 负责 Feishu 入站归一化辅助。
-   - `channels/qq/QQ.ts` 现在只保留 QQ 渠道门面与编排。
-   - `channels/qq/QQMessageHandler.ts` 负责 QQ group/c2c/channel 入站主流程。
-   - `channels/qq/QQSupport.ts` 负责 QQ READY 身份解析、命令映射与入站增强组装。
-   - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
-   - `channels/qq/QQGatewayConnection.ts` 负责 QQ Gateway WebSocket 创建与事件绑定。
-   - `channels/qq/QQGatewayProtocol.ts` 负责 QQ Gateway op code 协议路由与 Identify。
-   - `channels/qq/QQGatewayHeartbeat.ts` 负责 QQ Gateway heartbeat payload 发送。
-   - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
-   - `channels/qq/QQGatewayAuth.ts` 负责 QQ 鉴权、Gateway URL 与 HTTP 连通性测试。
-   - `channels/qq/QQGatewaySend.ts` 负责 QQ 回发请求构造、超时与自动重试。
-   - `channels/qq/QQInbound.ts` 负责 QQ 入站归一化辅助。
-2. `task/`
-   - 负责任务定义、计划调度、手动执行与 run 落盘。
-   - `TaskService.ts` 是实例入口，持有实例级 cron runtime 状态。
-   - `runtime/TaskServiceActions.ts` 负责 action 注册表装配。
-   - `runtime/TaskServiceSystem.ts` 负责 task system prompt。
-   - `runtime/TaskActionInput.ts` 负责 CLI/API 输入映射。
-   - `runtime/TaskActionExecution.ts` 负责 task 领域执行逻辑。
-   - `runtime/TaskRunnerProgress.ts` 负责 progress 快照与文本辅助。
-   - `runtime/TaskRunnerSession.ts` 负责 task 专用 session runtime。
-   - `runtime/TaskRunnerRound.ts` 负责单轮执行与模拟用户判定。
-   - `runtime/TaskRunnerScript.ts` 负责 script 类型任务的 one-shot 执行与校验分支。
-   - `runtime/TaskRunArtifacts.ts` 负责 run 产物写入与 markdown/json 摘要格式。
-   - `runtime/Runner.ts` 负责主编排并协调 run 产物写入。
-3. `memory/`
-   - 负责记忆提取、索引、检索与 flush。
-   - `MemoryService.ts` 持有实例级 memory runtime 状态。
-4. `shell/`
-   - 负责 shell session 生命周期与命令执行。
-   - `ShellService.ts` 持有实例级 shell session 状态。
-   - `runtime/ShellActionRuntime.ts` 负责公开 action 编排。
-   - `runtime/ShellActionRuntimeSupport.ts` 负责持久化、waiter 与 session 查找等共享运行时细节。
-   - `runtime/ShellRuntimeEnvironment.ts` 负责 shell cwd、env 与 owner context 解析。
-   - `runtime/ShellActionResponse.ts` 负责输出游标裁剪与标准 action response 构造。
-   - `runtime/ShellProcessEvents.ts` 负责 shell 子进程输出、错误与 close 事件绑定。
-   - `session/tools/shell/ShellToolDefinition.ts` 作为 session tool facade，只做协议适配。
-   - `session/tools/shell/ShellToolSchemas.ts` 负责 shell tool schema。
-   - `session/tools/shell/ShellToolBridge.ts` 负责 runtime bridge 与响应整理。
-5. `contact/`
-   - 负责 agent 点对点关系、长期 contact chat、内容分享与 inbox 接收。
-   - `ContactService.ts` 是实例入口，只保留 service 骨架与 contact 业务动作。
-   - `Action.ts` 负责 CLI/API action 注册表与输入映射。
-   - `runtime/ContactPayload.ts` 负责远端 HTTP payload 与 contact token 读取。
-   - `runtime/ContactStore.ts`、`LinkStore.ts`、`InboxStore.ts` 负责 contact/link/inbox 落盘。
-   - `runtime/LinkApproval.ts`、`ApproveCallback.ts` 负责建联与双向回连确认。
-   - `runtime/ShareBundle.ts` 负责分享内容打包与接收。
-
-## 统一服务模式
-
-1. `Index.ts`
-   - 只保留静态导出入口。
-2. `<Domain>Service.ts`
-   - 作为真正的 class service 实现。
-3. `Action.ts`
-   - 负责 action 注册表、CLI/API 输入映射与 handler 注入。
-4. `runtime/`
-   - 承载具体运行时实现、状态管理与输入映射。
-5. `types/`
-   - 存放领域内部协议；跨层共享契约统一提升到 `service/types/` 或包级 `types/`。
-
-## 边界约束
-
-1. service 通过 `AgentContext` 读取运行时能力。
-2. service 的实例状态应归属于 service instance，而不是模块级单例。
-3. plugin 只能作为被动扩展，不替代 service 主流程。
-4. service 间协作优先通过 `AgentContext.invoke`，而不是隐式全局状态。