@downcity/agent 1.1.25 → 1.1.32

package/src/plugin/builtins/task/runtime/TaskRunnerTypes.ts

@@ -0,0 +1,199 @@
+/**
+ * TaskRunner 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task runner 在拆分后跨模块共享的内部类型。
+ * - 这些类型服务于 task 运行链路，统一归档到 `src/types/task/`。
+ */
+
+import type { JsonlSessionHistoryStore } from "@/session/store/history/jsonl/JsonlSessionHistoryStore.js";
+import type { SessionExecutor } from "@/session/types/SessionExecutor.js";
+import type {
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunProgressPhaseV1,
+  ShipTaskRunProgressStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+} from "@/plugin/builtins/task/types/Task.js";
+
+/**
+ * run-progress.json 的当前快照状态。
+ */
+export type RunProgressSnapshot = {
+  /**
+   * 当前进度状态。
+   */
+  status: ShipTaskRunProgressStatusV1;
+  /**
+   * 当前进度阶段。
+   */
+  phase: ShipTaskRunProgressPhaseV1;
+  /**
+   * 当前阶段对人类可读的说明文本。
+   */
+  message: string;
+  /**
+   * 当前对话轮次。
+   */
+  round?: number;
+  /**
+   * 最大允许轮次。
+   */
+  maxRounds?: number;
+  /**
+   * 运行结束时间（毫秒时间戳）。
+   */
+  endedAt?: number;
+  /**
+   * 任务总体运行状态。
+   */
+  runStatus?: ShipTaskRunStatusV1;
+  /**
+   * 执行阶段状态。
+   */
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  /**
+   * 结果校验状态。
+   */
+  resultStatus?: ShipTaskRunResultStatusV1;
+};
+
+/**
+ * 任务结果校验结果。
+ */
+export type TaskResultValidation = {
+  /**
+   * 结果校验后的状态。
+   */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 校验失败时的错误列表。
+   */
+  errors: string[];
+};
+
+/**
+ * 模拟用户的判定结果。
+ */
+export type UserSimulatorDecision = {
+  /**
+   * 模拟用户是否认为当前结果已满足要求。
+   */
+  satisfied: boolean;
+  /**
+   * 模拟用户给出的回复文本。
+   */
+  reply: string;
+  /**
+   * 判定理由。
+   */
+  reason: string;
+  /**
+   * 可选评分，范围通常为 0-10。
+   */
+  score?: number;
+  /**
+   * 原始输出文本快照。
+   */
+  raw: string;
+};
+
+/**
+ * 单轮对话的落盘记录。
+ */
+export type DialogueRoundRecord = {
+  /**
+   * 当前任务是否启用了 review 多轮模式。
+   */
+  reviewEnabled: boolean;
+  /**
+   * 当前轮次编号。
+   */
+  round: number;
+  /**
+   * 本轮执行器收到的 query。
+   */
+  executorQuery: string;
+  /**
+   * 本轮执行器输出文本。
+   */
+  executorOutput: string;
+  /**
+   * 本轮执行器是否通过 `chat_send` 等方式实际送达文本。
+   */
+  executorDelivered: boolean;
+  /**
+   * 执行器 assistantMessage 的调试快照。
+   */
+  executorAssistantMessageSnapshot?: string;
+  /**
+   * 本轮结果校验状态。
+   */
+  validationResultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 本轮规则校验失败项。
+   */
+  ruleErrors: string[];
+  /**
+   * 模拟用户收到的 query。
+   */
+  userSimulatorQuery?: string;
+  /**
+   * 模拟用户输出文本。
+   */
+  userSimulatorOutput?: string;
+  /**
+   * 模拟用户 assistantMessage 的调试快照。
+   */
+  userSimulatorAssistantMessageSnapshot?: string;
+  /**
+   * 模拟用户最终判定结果。
+   */
+  userSimulator: UserSimulatorDecision;
+  /**
+   * 传递给下一轮执行器的反馈文本。
+   */
+  feedbackForNextRound?: string;
+};
+
+/**
+ * script 类型任务的执行结果。
+ */
+export type ScriptExecutionResult = {
+  /**
+   * script 标准输出与标准错误合并后的文本。
+   */
+  outputText: string;
+};
+
+/**
+ * task 运行专用的 session runtime 端口。
+ *
+ * 关键点（中文）
+ * - task runner 不直接依赖具体 SDK `Session` 实现。
+ * - 这里暴露的是 task 场景最小可用端口：执行器 + history Store。
+ */
+export type TaskSessionRuntimePort = {
+  /**
+   * 获取指定 sessionId 对应的 Session 执行端口。
+   */
+  getExecutor(sessionId: string): SessionExecutor;
+  /**
+   * 获取指定 sessionId 对应的 JsonlSessionHistoryStore。
+   */
+  getHistoryStore(sessionId: string): JsonlSessionHistoryStore;
+};
+
+/**
+ * 从 assistant 输出中提取的文本结果。
+ */
+export type ChatSendOutputPick = {
+  /**
+   * 最终提取到的文本内容。
+   */
+  text: string;
+  /**
+   * 该文本是否已经通过 chat_send 等方式送达。
+   */
+  delivered: boolean;
+};

package/src/plugin/builtins/task/types/TaskPluginTypes.ts

@@ -0,0 +1,55 @@
+/**
+ * TaskService 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task service 在类化拆分后共享的 action payload 与调度结果类型。
+ * - 跨模块复用的 task service 类型统一收敛在 `service/builtins/task/types/`。
+ */
+
+import type { ShipTaskStatus } from "@/plugin/builtins/task/types/Task.js";
+
+/**
+ * `task.list` action 的输入载荷。
+ */
+export type TaskListActionPayload = {
+  /**
+   * 按任务状态过滤；省略时返回全部状态。
+   */
+  status?: ShipTaskStatus;
+};
+
+/**
+ * task cron runtime 启动或重载后的统计结果。
+ */
+export type TaskCronRegisterResult = {
+  /**
+   * 本次扫描到的任务定义数量。
+   */
+  tasksFound: number;
+  /**
+   * 本次成功注册到 cron engine 的作业数量。
+   */
+  jobsScheduled: number;
+};
+
+/**
+ * 任务定义变更后 scheduler 重载结果。
+ */
+export type TaskSchedulerReloadResult = {
+  /**
+   * scheduler 是否成功完成重载。
+   */
+  reloaded: boolean;
+  /**
+   * 成功重载时扫描到的任务数量。
+   */
+  tasksFound?: number;
+  /**
+   * 成功重载时注册成功的 cron 作业数量。
+   */
+  jobsScheduled?: number;
+  /**
+   * 重载失败时的错误文本。
+   */
+  error?: string;
+};

package/src/plugin/builtins/tts/runtime/Synthesizer.ts

@@ -13,7 +13,7 @@ import fs from "fs-extra";
 import type { TtsPluginConfig, TtsSynthesizeInput } from "@/plugin/builtins/tts/types/TtsPlugin.js";
 import type { TtsAudioFormat, TtsModelId } from "@/plugin/builtins/tts/types/Tts.js";
 import type { PluginCommandContext } from "@/plugin/types/Plugin.js";
-import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import { renderChatMessageFileTag } from "@/plugin/builtins/chat/runtime/ChatMessageMarkup.js";
 import { getTtsModelCatalogItem, resolveTtsModelId } from "@/plugin/builtins/tts/runtime/Catalog.js";
 import { resolveTtsModelsRootDir } from "@/plugin/builtins/tts/runtime/Paths.js";
 

package/src/plugin/builtins/voice/InboundAugment.ts

@@ -7,7 +7,7 @@
  */
 
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ChatInboundAugmentInput } from "@/service/builtins/chat/types/ChatPlugin.js";
+import type { ChatInboundAugmentInput } from "@/plugin/builtins/chat/types/ChatPlugin.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import { transcribeWithVoiceDependency } from "@/plugin/builtins/voice/Dependency.js";
 

package/src/plugin/builtins/workboard/runtime/Collector.ts

@@ -3,11 +3,11 @@
  *
  * 关键点（中文）
  * - 这里只做确定性采集，不引入 LLM 推理。
- * - 内部仍聚合 session、task、service 三类运行事实，但最终只输出对外安全的模糊状态。
+ * - 内部仍聚合 session、task、runtime plugin 三类运行事实，但最终只输出对外安全的模糊状态。
  */
 
-import { listTaskDefinitions } from "@/service/builtins/task/Action.js";
-import { listServiceStates } from "@/service/core/Manager.js";
+import { listTaskDefinitions } from "@/plugin/builtins/task/Action.js";
+import { listPluginStates } from "@/plugin/core/Manager.js";
 import { listControlSessionSummaries } from "@/runtime/server/http/control/SessionSummaryStore.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { WorkboardSnapshot } from "@/plugin/builtins/workboard/types/Workboard.js";
@@ -32,13 +32,14 @@ export async function collectWorkboardSnapshot(
   const executingSessionIds = new Set(context.session.listExecutingSessionIds());
   const sessions = await listControlSessionSummaries({
     projectRoot: context.rootPath,
+    agentId: context.paths.agentId,
     executionContext: context,
     limit: WORKBOARD_RECENT_LIMIT + Math.max(executingSessionIds.size, 1),
     executingSessionIds,
   });
-  const services = listServiceStates({ context });
+  const runtimePlugins = listPluginStates({ context });
   const taskResult = await listTaskDefinitions({ projectRoot: context.rootPath });
-  const degradedCount = services.filter((item) => item.state !== "running").length;
+  const degradedCount = runtimePlugins.filter((item) => item.state !== "running").length;
 
   const current = sessions
     .filter((item) => item.executing === true)
@@ -71,7 +72,7 @@ export async function collectWorkboardSnapshot(
     signals: toWorkboardSignals({
       currentCount: current.length,
       recentCount: recent.length,
-      services,
+      services: runtimePlugins,
       taskResult,
     }),
   };

package/src/plugin/builtins/workboard/runtime/Normalizer.ts

@@ -7,8 +7,8 @@
  */
 
 import type { ControlSessionSummary } from "@/runtime/server/http/control/types/ControlViewData.js";
-import type { ServiceStateSnapshot } from "@/service/types/ServiceState.js";
-import type { TaskListResponse } from "@/service/builtins/task/types/TaskCommand.js";
+import type { ServiceStateSnapshot } from "@/plugin/types/PluginState.js";
+import type { TaskListResponse } from "@/plugin/builtins/task/types/TaskCommand.js";
 import type {
   WorkboardActivityItem,
   WorkboardAgentSummary,

package/src/plugin/core/BasePlugin.ts

@@ -0,0 +1,134 @@
+/**
+ * BasePlugin：统一 plugin 类基座。
+ *
+ * 关键点（中文）
+ * - 主动运行型能力与被动扩展型能力统一收敛到 plugin 概念。
+ * - plugin 的长期状态归属于实例本身，而不是模块级单例。
+ * - 旧 service 生命周期模型暂时通过 `lifecycle` 兼容，后续可逐步收敛到 `start/stop/command`。
+ */
+
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type {
+  Plugin,
+  PluginActions,
+  PluginAvailability,
+  PluginCommandContext,
+  PluginConfigDefinition,
+  PluginHooks,
+  PluginHttpDefinition,
+  PluginLifecycle,
+  PluginResolves,
+  PluginSetupDefinition,
+  PluginStateRecord,
+  PluginUsageDefinition,
+} from "@/plugin/types/Plugin.js";
+import type { StructuredConfig } from "@/core/AgentContextTypes.js";
+
+/**
+ * BasePlugin 抽象基类。
+ */
+export abstract class BasePlugin implements Plugin {
+  /**
+   * 当前实例持有的通用 plugin 运行状态记录。
+   */
+  public readonly pluginStateRecord: PluginStateRecord = {
+    state: "stopped",
+    updatedAt: Date.now(),
+    chain: Promise.resolve(),
+  };
+
+  /**
+   * 当前 plugin 所属的 agent 宿主。
+   */
+  protected agent: AgentRuntime | null;
+
+  constructor(agent: AgentRuntime | null = null) {
+    this.agent = agent;
+  }
+
+  /**
+   * 当前 plugin 名称。
+   */
+  abstract readonly name: string;
+
+  /**
+   * 插件标题。
+   */
+  readonly title = "";
+
+  /**
+   * 插件说明。
+   */
+  readonly description = "";
+
+  /**
+   * 插件配置定义。
+   */
+  readonly config?: PluginConfigDefinition<StructuredConfig>;
+
+  /**
+   * 插件 setup 协议。
+   */
+  readonly setup?: PluginSetupDefinition;
+
+  /**
+   * 插件 usage 协议。
+   */
+  readonly usage?: PluginUsageDefinition;
+
+  /**
+   * 显式 action 集合。
+   */
+  readonly actions: PluginActions = {};
+
+  /**
+   * pipeline / guard / effect 扩展点。
+   */
+  readonly hooks?: PluginHooks;
+
+  /**
+   * resolve 扩展点。
+   */
+  readonly resolves?: PluginResolves;
+
+  /**
+   * HTTP 路由扩展。
+   */
+  readonly http?: PluginHttpDefinition;
+
+  /**
+   * 旧生命周期兼容层。
+   */
+  lifecycle?: PluginLifecycle;
+
+  /**
+   * Plugin 可用性检查。
+   */
+  availability?(
+    context: PluginCommandContext | AgentContext,
+  ): Promise<PluginAvailability> | PluginAvailability;
+
+  /**
+   * Plugin system 文本提供器。
+   */
+  system?(context: AgentContext): Promise<string> | string;
+
+  /**
+   * 绑定当前 plugin 所属的 agent 宿主。
+   */
+  bindAgent(agent: AgentRuntime | null): this {
+    this.agent = agent;
+    return this;
+  }
+
+  /**
+   * 读取绑定的 agent 宿主。
+   */
+  protected requireAgent(): AgentRuntime {
+    if (this.agent) return this.agent;
+    throw new Error(
+      `Plugin "${this.name}" is not bound to an agent instance.`,
+    );
+  }
+}

package/src/plugin/core/BuiltinPluginClasses.ts

@@ -0,0 +1,31 @@
+/**
+ * 内建主动型 plugin 类清单。
+ */
+
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import { ChatPlugin } from "@/plugin/builtins/chat/ChatPlugin.js";
+import { ContactPlugin } from "@/plugin/builtins/contact/ContactPlugin.js";
+import { SchedulePlugin } from "@/plugin/builtins/schedule/SchedulePlugin.js";
+import { TaskPlugin } from "@/plugin/builtins/task/TaskPlugin.js";
+import { MemoryPlugin } from "@/plugin/builtins/memory/MemoryPlugin.js";
+import { ShellPlugin } from "@/plugin/builtins/shell/ShellPlugin.js";
+
+/**
+ * 单个主动型 plugin class 构造器。
+ */
+export type BuiltinPluginClass<T extends BasePlugin = BasePlugin> = new (
+  agent: AgentRuntime | null,
+) => T;
+
+/**
+ * 全部内建主动型 plugin classes。
+ */
+export const BUILTIN_PLUGIN_CLASSES: BuiltinPluginClass[] = [
+  ChatPlugin,
+  ContactPlugin,
+  SchedulePlugin,
+  TaskPlugin,
+  MemoryPlugin,
+  ShellPlugin,
+];

package/src/plugin/core/LocalExecution.ts

@@ -24,6 +24,7 @@ import type {
   PluginCommandContext,
   PluginView,
 } from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 
 function createLocalFallbackPlatformRuntime(): AgentPlatformRuntime {
   return {
@@ -67,7 +68,10 @@ export function createLocalPluginCommandContext(projectRoot: string): PluginComm
     config,
     env,
     globalEnv,
-    paths: createAgentPathRuntime(rootPath),
+    paths: createAgentPathRuntime(
+      rootPath,
+      String(config.name || "").trim() || path.basename(rootPath) || "agent",
+    ),
     pluginConfig: createAgentPluginConfigRuntime(rootPath),
     platform,
   };
@@ -165,7 +169,7 @@ export async function runLocalPluginAction(params: {
 
   try {
     return await action.execute({
-      context,
+      context: context as unknown as AgentContext,
       payload: (params.payload ?? {}) as JsonValue,
       pluginName: plugin.name,
       actionName,

package/src/plugin/core/Manager.ts

@@ -0,0 +1,21 @@
+/**
+ * Plugin Manager 门面模块。
+ */
+
+export type {
+  PluginStateControlAction,
+  PluginStateControlResult,
+  PluginStateSnapshot,
+} from "@/plugin/types/Plugin.js";
+export {
+  controlPluginState,
+  getPluginRootCommandNames,
+  getStaticPlugins,
+  isPluginRunning,
+  listPluginStates,
+  startAllPlugins,
+  stopAllPlugins,
+} from "@/plugin/core/PluginStateController.js";
+export {
+  runPluginCommand,
+} from "@/plugin/core/PluginActionRunner.js";