@downcity/agent 1.1.408 → 1.1.437

package/src/plugin/core/HookRegistry.ts

@@ -1,297 +0,0 @@
-/**
- * Plugin 点注册表。
- *
- * 关键点（中文）
- * - 统一管理 pipeline / guard / effect / resolve 四类 plugin 点。
- * - service 只依赖固定执行语义，不再自己拼装扩展调度逻辑。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-import type {
-  PluginEffectHook,
-  PluginGuardHook,
-  PluginPipelineHook,
-  PluginResolveHook,
-} from "@/types/plugin/PluginRuntime.js";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-
-type PipelineRecord = {
-  plugin_name: string;
-  handler: PluginPipelineHook<JsonValue>;
-};
-
-type GuardRecord = {
-  plugin_name: string;
-  handler: PluginGuardHook<JsonValue>;
-};
-
-type EffectRecord = {
-  plugin_name: string;
-  handler: PluginEffectHook<JsonValue>;
-};
-
-type ResolveRecord = {
-  plugin_name: string;
-  handler: PluginResolveHook<JsonValue, JsonValue>;
-};
-
-/**
- * HookRegistry：plugin 点注册与执行实现。
- */
-export class HookRegistry {
-  private readonly is_plugin_ready: (plugin_name: string) => boolean;
-
-  private readonly pipelineHooks = new Map<string, PipelineRecord[]>();
-
-  private readonly guardHooks = new Map<string, GuardRecord[]>();
-
-  private readonly effectHooks = new Map<string, EffectRecord[]>();
-
-  private readonly resolveHooks = new Map<string, ResolveRecord>();
-
-  constructor(params: {
-    is_plugin_ready: (plugin_name: string) => boolean;
-  }) {
-    this.is_plugin_ready = params.is_plugin_ready;
-  }
-
-  /**
-   * 注册 pipeline 扩展点。
-   */
-  pipeline(
-    point_name: string,
-    plugin_name: string,
-    handler: PluginPipelineHook<JsonValue>,
-  ): void {
-    const key = String(point_name || "").trim();
-    if (!key) {
-      throw new Error("Pipeline point name is required");
-    }
-    const bucket = this.pipelineHooks.get(key) || [];
-    bucket.push({
-      plugin_name: String(plugin_name || "").trim(),
-      handler,
-    });
-    this.pipelineHooks.set(key, bucket);
-  }
-
-  /**
-   * 注册 guard 扩展点。
-   */
-  guard(
-    point_name: string,
-    plugin_name: string,
-    handler: PluginGuardHook<JsonValue>,
-  ): void {
-    const key = String(point_name || "").trim();
-    if (!key) {
-      throw new Error("Guard point name is required");
-    }
-    const bucket = this.guardHooks.get(key) || [];
-    bucket.push({
-      plugin_name: String(plugin_name || "").trim(),
-      handler,
-    });
-    this.guardHooks.set(key, bucket);
-  }
-
-  /**
-   * 注册 effect 扩展点。
-   */
-  effect(
-    point_name: string,
-    plugin_name: string,
-    handler: PluginEffectHook<JsonValue>,
-  ): void {
-    const key = String(point_name || "").trim();
-    if (!key) {
-      throw new Error("Effect point name is required");
-    }
-    const bucket = this.effectHooks.get(key) || [];
-    bucket.push({
-      plugin_name: String(plugin_name || "").trim(),
-      handler,
-    });
-    this.effectHooks.set(key, bucket);
-  }
-
-  /**
-   * 注册 resolve 扩展点。
-   *
-   * 关键点（中文）
-   * - resolve 语义要求单点单处理器，避免 service 侧再做二次仲裁。
-   */
-  resolve(
-    point_name: string,
-    plugin_name: string,
-    handler: PluginResolveHook<JsonValue, JsonValue>,
-  ): void {
-    const key = String(point_name || "").trim();
-    if (!key) {
-      throw new Error("Resolve point name is required");
-    }
-    if (this.resolveHooks.has(key)) {
-      throw new Error(`Resolve point already registered: ${key}`);
-    }
-    this.resolveHooks.set(key, {
-      plugin_name: String(plugin_name || "").trim(),
-      handler,
-    });
-  }
-
-  /**
-   * 移除指定 plugin 注册的全部扩展点。
-   */
-  unregister_plugin(plugin_name: string): void {
-    const key = String(plugin_name || "").trim();
-    if (!key) return;
-
-    for (const [point_name, bucket] of this.pipelineHooks.entries()) {
-      const next = bucket.filter((item) => item.plugin_name !== key);
-      if (next.length > 0) {
-        this.pipelineHooks.set(point_name, next);
-      } else {
-        this.pipelineHooks.delete(point_name);
-      }
-    }
-
-    for (const [point_name, bucket] of this.guardHooks.entries()) {
-      const next = bucket.filter((item) => item.plugin_name !== key);
-      if (next.length > 0) {
-        this.guardHooks.set(point_name, next);
-      } else {
-        this.guardHooks.delete(point_name);
-      }
-    }
-
-    for (const [point_name, bucket] of this.effectHooks.entries()) {
-      const next = bucket.filter((item) => item.plugin_name !== key);
-      if (next.length > 0) {
-        this.effectHooks.set(point_name, next);
-      } else {
-        this.effectHooks.delete(point_name);
-      }
-    }
-
-    for (const [point_name, record] of this.resolveHooks.entries()) {
-      if (record.plugin_name === key) {
-        this.resolveHooks.delete(point_name);
-      }
-    }
-  }
-
-  /**
-   * 列出所有已注册扩展点。
-   */
-  list(): string[] {
-    const keys = new Set<string>([
-      ...this.pipelineHooks.keys(),
-      ...this.guardHooks.keys(),
-      ...this.effectHooks.keys(),
-      ...this.resolveHooks.keys(),
-    ]);
-    return Array.from(keys).sort((a, b) => a.localeCompare(b));
-  }
-
-  /**
-   * 运行 pipeline 扩展点。
-   */
-  async pipelineValue<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-    resolve_context: (plugin_name: string) => PluginContext = () => context,
-  ): Promise<T> {
-    const key = String(point_name || "").trim();
-    if (!key) return value;
-    const bucket = this.pipelineHooks.get(key) || [];
-    if (bucket.length === 0) return value;
-
-    let current = value as JsonValue;
-    for (const item of bucket) {
-      if (!this.is_plugin_ready(item.plugin_name)) continue;
-      current = await item.handler({
-        context: resolve_context(item.plugin_name),
-        value: current,
-        plugin: item.plugin_name,
-      });
-    }
-    return current as T;
-  }
-
-  /**
-   * 运行 guard 扩展点。
-   */
-  async guardValue<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-    resolve_context: (plugin_name: string) => PluginContext = () => context,
-  ): Promise<void> {
-    const key = String(point_name || "").trim();
-    if (!key) return;
-    const bucket = this.guardHooks.get(key) || [];
-    if (bucket.length === 0) return;
-
-    for (const item of bucket) {
-      if (!this.is_plugin_ready(item.plugin_name)) continue;
-      await item.handler({
-        context: resolve_context(item.plugin_name),
-        value: value as JsonValue,
-        plugin: item.plugin_name,
-      });
-    }
-  }
-
-  /**
-   * 运行 effect 扩展点。
-   */
-  async effectValue<T = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: T,
-    resolve_context: (plugin_name: string) => PluginContext = () => context,
-  ): Promise<void> {
-    const key = String(point_name || "").trim();
-    if (!key) return;
-    const bucket = this.effectHooks.get(key) || [];
-    if (bucket.length === 0) return;
-
-    for (const item of bucket) {
-      if (!this.is_plugin_ready(item.plugin_name)) continue;
-      await item.handler({
-        context: resolve_context(item.plugin_name),
-        value: value as JsonValue,
-        plugin: item.plugin_name,
-      });
-    }
-  }
-
-  /**
-   * 运行 resolve 点。
-   */
-  async resolveValue<TInput = JsonValue, TOutput = JsonValue>(
-    context: PluginContext,
-    point_name: string,
-    value: TInput,
-    resolve_context: (plugin_name: string) => PluginContext = () => context,
-  ): Promise<TOutput> {
-    const key = String(point_name || "").trim();
-    if (!key) {
-      throw new Error("Resolve point name is required");
-    }
-    const record = this.resolveHooks.get(key);
-    if (!record) {
-      throw new Error(`No plugin resolver registered for point: ${key}`);
-    }
-    if (!this.is_plugin_ready(record.plugin_name)) {
-      throw new Error(`No active plugin resolver registered for point: ${key}`);
-    }
-
-    return await record.handler({
-      context: resolve_context(record.plugin_name),
-      value: value as JsonValue,
-      plugin: record.plugin_name,
-    }) as TOutput;
-  }
-}

package/src/plugin/core/PluginActionExecution.ts

@@ -1,230 +0,0 @@
-/**
- * Plugin Action 统一执行流水线。
- *
- * 关键点（中文）
- * - Registry 负责解析 Action，本模块统一处理 payload、执行身份、取消、超时与错误结果。
- * - 超时采用协作式取消：运行时触发 abort_signal，Action 必须把信号传给网络、轮询和长任务。
- * - Action 普通失败只返回业务结果，不修改 Plugin 生命周期状态。
- */
-
-import type { PluginAction, PluginActionResult } from "@/types/plugin/PluginAction.js";
-import type { PluginActionExecutionContext } from "@/types/plugin/PluginActionExecution.js";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { SessionInteractionPort } from "@/types/session/SessionInteraction.js";
-import { generate_id } from "@/utils/Id.js";
-
-/** Action 超时写入 abort_signal.reason 的内部错误。 */
-class PluginActionTimeoutError extends Error {
-  constructor(
-    readonly plugin_name: string,
-    readonly action_name: string,
-    readonly timeout_ms: number,
-  ) {
-    super(`Plugin action timed out after ${timeout_ms} ms: ${plugin_name}.${action_name}`);
-    this.name = "PluginActionTimeoutError";
-  }
-}
-
-/** Action 取消信号及其清理行为。 */
-interface PluginActionAbortScope {
-  /** 传给 Action 的统一取消信号。 */
-  signal: AbortSignal;
-  /** 清理上游监听与超时计时器。 */
-  dispose(): void;
-}
-
-/** Action 执行流水线输入。 */
-export interface ExecutePluginActionInput {
-  /** 当前 Plugin Workspace 上下文。 */
-  context: PluginContext;
-  /** 当前 Plugin 稳定名称。 */
-  plugin_name: string;
-  /** 当前 Action 稳定名称。 */
-  action_name: string;
-  /** 当前 Action 定义。 */
-  action: PluginAction<JsonValue, JsonValue>;
-  /** 未校验的调用 payload。 */
-  payload: JsonValue;
-  /** Session 或其他入口提供的可选执行快照。 */
-  snapshot?: PluginExecutionContext;
-  /** 当前 Session 的 Interaction 端口。 */
-  interactions?: SessionInteractionPort;
-}
-
-/** 读取异常的稳定可读文本。 */
-function error_message(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/** 创建稳定失败结果。 */
-function failure_result(message: string): PluginActionResult<JsonValue> {
-  return { success: false, error: message, message };
-}
-
-/** 校验并解析 Action payload。 */
-function parse_action_payload(
-  input: ExecutePluginActionInput,
-): PluginActionResult<JsonValue> | { input: JsonValue } {
-  const schema = input.action.input_schema?.zod;
-  if (!schema) return { input: input.payload };
-  const parsed = schema.safeParse(input.payload);
-  if (parsed.success) return { input: parsed.data as JsonValue };
-  return failure_result(
-    `Invalid payload for ${input.plugin_name}.${input.action_name}: ${parsed.error.message}`,
-  );
-}
-
-/** 解析 Action 的可选协作式超时。 */
-function resolve_timeout_ms(action: PluginAction<JsonValue, JsonValue>): number | undefined {
-  if (action.timeout_ms === undefined) return undefined;
-  if (!Number.isInteger(action.timeout_ms) || action.timeout_ms <= 0) {
-    throw new Error("Plugin action timeout_ms must be a positive integer");
-  }
-  return action.timeout_ms;
-}
-
-/** 合并上游取消和 Action 超时，并返回可清理的统一信号。 */
-function create_abort_scope(input: {
-  plugin_name: string;
-  action_name: string;
-  source_signal?: AbortSignal;
-  timeout_ms?: number;
-}): PluginActionAbortScope {
-  if (!input.timeout_ms && input.source_signal) {
-    return { signal: input.source_signal, dispose: () => undefined };
-  }
-
-  const controller = new AbortController();
-  const abort_from_source = () => {
-    if (!controller.signal.aborted) controller.abort(input.source_signal?.reason);
-  };
-  if (input.source_signal?.aborted) {
-    abort_from_source();
-  } else {
-    input.source_signal?.addEventListener("abort", abort_from_source, { once: true });
-  }
-
-  const timeout_ms = input.timeout_ms;
-  const timeout = timeout_ms
-    ? setTimeout(() => {
-        if (!controller.signal.aborted) {
-          controller.abort(new PluginActionTimeoutError(
-            input.plugin_name,
-            input.action_name,
-            timeout_ms,
-          ));
-        }
-      }, timeout_ms)
-    : undefined;
-
-  return {
-    signal: controller.signal,
-    dispose: () => {
-      input.source_signal?.removeEventListener("abort", abort_from_source);
-      if (timeout) clearTimeout(timeout);
-    },
-  };
-}
-
-/** 把可选入口快照归一化为 Action 必定可用的完整执行上下文。 */
-function create_action_execution_context(input: {
-  context: PluginContext;
-  snapshot?: PluginExecutionContext;
-  interactions?: SessionInteractionPort;
-  abort_signal: AbortSignal;
-}): PluginActionExecutionContext {
-  const source = input.snapshot;
-  const session_id = String(source?.session_id || "").trim();
-  const turn_id = String(source?.turn_id || "").trim();
-  const call_id = String(source?.call_id || "").trim() || `plugin:${generate_id()}`;
-  const snapshot: PluginExecutionContext = Object.freeze({
-    ...(session_id ? { session_id } : {}),
-    ...(turn_id ? { turn_id } : {}),
-    project_root: input.context.workspace_path,
-    workspace_env: Object.freeze({
-      ...(source?.workspace_env ?? input.context.workspace_env ?? {}),
-    }),
-    agent_systems: Object.freeze([
-      ...(source?.agent_systems ?? input.context.instructions ?? []),
-    ]),
-    abort_signal: input.abort_signal,
-    call_id,
-  });
-  return Object.freeze({
-    call_id,
-    abort_signal: input.abort_signal,
-    snapshot,
-    ...(session_id && turn_id
-      ? {
-          session: Object.freeze({
-            session_id,
-            turn_id,
-            ...(input.interactions
-              ? { interactions: input.interactions }
-              : {}),
-          }),
-        }
-      : {}),
-  });
-}
-
-/** 运行一个已经解析到具体 Plugin 的 Action。 */
-export async function execute_plugin_action(
-  input: ExecutePluginActionInput,
-): Promise<PluginActionResult<JsonValue>> {
-  const parsed_payload = parse_action_payload(input);
-  if (!("input" in parsed_payload)) return parsed_payload;
-
-  let timeout_ms: number | undefined;
-  try {
-    timeout_ms = resolve_timeout_ms(input.action);
-  } catch (error) {
-    return failure_result(
-      `${input.plugin_name}.${input.action_name}: ${error_message(error)}`,
-    );
-  }
-
-  const abort_scope = create_abort_scope({
-    plugin_name: input.plugin_name,
-    action_name: input.action_name,
-    source_signal: input.snapshot?.abort_signal,
-    timeout_ms,
-  });
-  const action_execution = create_action_execution_context({
-    context: input.context,
-    snapshot: input.snapshot,
-    interactions: input.interactions,
-    abort_signal: abort_scope.signal,
-  });
-
-  try {
-    if (abort_scope.signal.aborted) {
-      return failure_result(
-        error_message(abort_scope.signal.reason || "Plugin action cancelled"),
-      );
-    }
-    const result = await input.action.execute({
-      execution: action_execution,
-      context: input.context,
-      input: parsed_payload.input,
-      plugin_name: input.plugin_name,
-      action_name: input.action_name,
-    });
-    if (abort_scope.signal.aborted) {
-      return failure_result(
-        error_message(abort_scope.signal.reason || "Plugin action cancelled"),
-      );
-    }
-    return result;
-  } catch (error) {
-    return failure_result(
-      abort_scope.signal.aborted
-        ? error_message(abort_scope.signal.reason || error)
-        : error_message(error),
-    );
-  } finally {
-    abort_scope.dispose();
-  }
-}

package/src/plugin/core/PluginActionFactory.ts

@@ -1,172 +0,0 @@
-/**
- * PluginActionFactory：创建带 metadata 和 schema 的 plugin/action。
- *
- * 关键点（中文）
- * - `create_action` 让 action 的运行时 schema 与 TypeScript 输入类型保持一致。
- * - `create_plugin` 只做轻量对象装配，不强制继承 BasePlugin。
- * - 旧的 class extends BasePlugin 写法仍可继续使用。
- */
-
-import type { z } from "zod";
-import type { PluginContext } from "@/types/plugin/PluginContext.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type {
-  PluginAction,
-  PluginActionApi,
-  PluginActionCommand,
-  PluginActionExample,
-  PluginActionInputSchema,
-  PluginActionResult,
-  PluginActions,
-} from "@/types/plugin/PluginAction.js";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type {
-  PluginAvailability,
-  PluginHooks,
-  PluginResolves,
-} from "@/types/plugin/PluginRuntime.js";
-import type { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
-import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
-import type { PluginActionExecutionContext } from "@/types/plugin/PluginActionExecution.js";
-
-/**
- * 从 Zod schema 推导 JSON 输入类型。
- */
-type InferZodJson<TSchema extends z.ZodTypeAny> =
-  z.infer<TSchema> extends JsonValue ? z.infer<TSchema> : JsonValue;
-
-/**
- * create_action 参数。
- */
-export interface CreatePluginActionOptions<
-  P extends JsonValue,
-  R extends JsonValue,
-> {
-  /** Action 用途说明。 */
-  description?: string;
-  /** Zod 输入 schema。 */
-  input_schema?: z.ZodTypeAny | PluginActionInputSchema<P>;
-  /** Action 调用示例。 */
-  examples?: PluginActionExample<P>[];
-  /** Action 的协作式超时上限（毫秒）。 */
-  timeout_ms?: number;
-  /** CLI 定义。 */
-  command?: PluginActionCommand<P>;
-  /** HTTP 定义。 */
-  api?: PluginActionApi<P>;
-  /** Action 执行器。 */
-  execute: (params: {
-    /** 当前 Session Workspace 上下文创建的稳定 Plugin 能力视图。 */
-    context: PluginContext;
-    /** 当前 Action 的执行身份和生命周期。 */
-    execution: PluginActionExecutionContext;
-    /** 已通过 schema 校验后的输入。 */
-    input: P;
-    /** 当前插件名称。 */
-    plugin_name: string;
-    /** 当前 Action 名称。 */
-    action_name: string;
-  }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
-}
-
-/**
- * create_plugin 参数。
- */
-export interface CreatePluginOptions<TActions extends PluginActions> {
-  /** Plugin 稳定名称。 */
-  name: string;
-  /** Plugin 展示标题。 */
-  title?: string;
-  /** Plugin 用途说明。 */
-  description?: string;
-  /** Plugin 显式 action 集合。 */
-  actions?: TActions;
-  /** Plugin hook 集合。 */
-  hooks?: PluginHooks;
-  /** Plugin resolve 集合。 */
-  resolves?: PluginResolves;
-  /** Plugin system 文本构建器。 */
-  system?: (
-    context: PluginContext,
-    execution_context?: PluginExecutionContext,
-  ) => string | Promise<string>;
-  /** Plugin 生命周期定义。 */
-  lifecycle?: PluginLifecycle;
-  /** Plugin 可用性检查。 */
-  availability?: (
-    context: PluginContext,
-  ) => Promise<PluginAvailability> | PluginAvailability;
-  /** Plugin HTTP 注入定义。 */
-  http?: PluginHttpDefinition;
-}
-
-/**
- * 归一化输入 schema。
- */
-function normalize_input_schema<P extends JsonValue>(
-  input_schema: z.ZodTypeAny | PluginActionInputSchema<P> | undefined,
-): PluginActionInputSchema<P> | undefined {
-  if (!input_schema) return undefined;
-  if (typeof (input_schema as z.ZodTypeAny).safeParse === "function") {
-    return { zod: input_schema as z.ZodTypeAny };
-  }
-  return input_schema as PluginActionInputSchema<P>;
-}
-
-/**
- * 创建带 metadata 的 action。
- */
-export function create_action<
-  TSchema extends z.ZodTypeAny,
-  R extends JsonValue = JsonValue,
->(
-  options: CreatePluginActionOptions<InferZodJson<TSchema>, R> & {
-    /** Zod 输入 schema。 */
-    input_schema?: TSchema | PluginActionInputSchema<InferZodJson<TSchema>>;
-  },
-): PluginAction<InferZodJson<TSchema>, R>;
-export function create_action<R extends JsonValue = JsonValue>(
-  options: CreatePluginActionOptions<JsonValue, R>,
-): PluginAction<JsonValue, R>;
-export function create_action(
-  options: CreatePluginActionOptions<JsonValue, JsonValue>,
-): PluginAction<JsonValue, JsonValue> {
-  return {
-    ...(options.description ? { description: options.description } : {}),
-    ...(options.input_schema
-      ? { input_schema: normalize_input_schema(options.input_schema) }
-      : {}),
-    ...(options.examples ? { examples: options.examples } : {}),
-    ...(options.timeout_ms !== undefined
-      ? { timeout_ms: options.timeout_ms }
-      : {}),
-    ...(options.command ? { command: options.command } : {}),
-    ...(options.api ? { api: options.api } : {}),
-    execute: options.execute,
-  };
-}
-
-/**
- * 创建 plugin 对象。
- */
-export function create_plugin<TActions extends PluginActions>(
-  options: CreatePluginOptions<TActions>,
-): Plugin & { actions: TActions } {
-  const name = String(options.name || "").trim();
-  if (!name) {
-    throw new Error("create_plugin requires a non-empty name");
-  }
-  return {
-    name,
-    title: String(options.title || name).trim(),
-    description: String(options.description || "").trim(),
-    actions: options.actions || ({} as TActions),
-    ...(options.hooks ? { hooks: options.hooks } : {}),
-    ...(options.resolves ? { resolves: options.resolves } : {}),
-    ...(options.system ? { system: options.system } : {}),
-    ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
-    ...(options.availability ? { availability: options.availability } : {}),
-    ...(options.http ? { http: options.http } : {}),
-  };
-}